From 0ccd3ed4638f5ae10771cc74147fcfb8a92a7e2d Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Wed, 29 Jul 2026 13:34:45 +0800
Subject: [PATCH 001/516] feat(feedback): add a /feedback command recorded
 through the command plane
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Register a global `/feedback` command so a user can record a remark about the
session without spending a model turn. `/feedback <text>` acknowledges; empty
or whitespace-only input returns a usage error.

The plugin appends no session event of its own. `dsh-commands` already writes
a `command/run` / `command/done` pair for every dispatched command, carrying
the verbatim text and the settled outcome, and both records are log-only and
non-surface. The feedback is therefore durably in the session log and invisible
to the model without this package touching the log format.

Text is never parsed, so `/feedback /plan felt slow` records that literal
content. Nothing consumes the records; capture is deliberately inert.

New group `packages/feedback/` — no existing group owns feedback capture. Its
row raises the packages/README.md word ceiling by 10, which had no headroom;
one redundant sentence there was removed to offset most of the cost.
---
 .../2026-07-28-feedback-command.i18n.yaml     |   6 +
 .../feature/2026-07-28-feedback-command.md    |  61 ++++++
 .../feature/2026-07-28-feedback-command.zh.md |  61 ++++++
 docs/config-catalog.md                        |   3 +-
 docs/module-graph.md                          |   9 +-
 packages/README.i18n.yaml                     |   4 +-
 packages/README.md                            |   3 +-
 packages/README.zh.md                         |   3 +-
 packages/examples/tui-demo/package.json       |   2 +
 packages/examples/tui-demo/src/index.ts       |   4 +-
 .../examples/tui-demo/tests/tui-agent.spec.ts |  27 +--
 packages/examples/tui-demo/tsconfig.json      |   3 +
 packages/feedback/README.i18n.yaml            |   6 +
 packages/feedback/README.md                   |  11 ++
 packages/feedback/README.zh.md                |  11 ++
 .../command-feedback/README.i18n.yaml         |   6 +
 packages/feedback/command-feedback/README.md  |  60 ++++++
 .../feedback/command-feedback/README.zh.md    |  60 ++++++
 .../feedback/command-feedback/package.json    |  44 +++++
 .../feedback/command-feedback/src/index.ts    |  40 ++++
 .../command-feedback/src/invariant.ts         |  30 +++
 .../tests/command-feedback.spec.ts            | 176 ++++++++++++++++++
 .../tests/loader-composition.spec.ts          | 105 +++++++++++
 .../feedback/command-feedback/tsconfig.json   |  24 +++
 pnpm-lock.yaml                                |  30 +++
 scripts/doc-budgets.manifest.json             |   2 +-
 tsconfig.base.json                            |   2 +
 tsconfig.host.json                            |   1 +
 28 files changed, 774 insertions(+), 20 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-07-28-feedback-command.md
 create mode 100644 .agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
 create mode 100644 packages/feedback/README.i18n.yaml
 create mode 100644 packages/feedback/README.md
 create mode 100644 packages/feedback/README.zh.md
 create mode 100644 packages/feedback/command-feedback/README.i18n.yaml
 create mode 100644 packages/feedback/command-feedback/README.md
 create mode 100644 packages/feedback/command-feedback/README.zh.md
 create mode 100644 packages/feedback/command-feedback/package.json
 create mode 100644 packages/feedback/command-feedback/src/index.ts
 create mode 100644 packages/feedback/command-feedback/src/invariant.ts
 create mode 100644 packages/feedback/command-feedback/tests/command-feedback.spec.ts
 create mode 100644 packages/feedback/command-feedback/tests/loader-composition.spec.ts
 create mode 100644 packages/feedback/command-feedback/tsconfig.json

diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
new file mode 100644
index 0000000000..ba56da8945
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-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 .agents/notes/implemented/feature/2026-07-28-feedback-command.md
+2026-07-28-feedback-command.md: ae32d3908d568c4a511e8d9e2b8cf50569fb80bf
+2026-07-28-feedback-command.zh.md: f69dbf6a50161e7f5048b76be46bc4063f9e757a
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
new file mode 100644
index 0000000000..ae32d3908d
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
@@ -0,0 +1,61 @@
+# Agent Note: `/feedback` command
+
+Status: implemented
+
+English | [中文](2026-07-28-feedback-command.zh.md)
+
+## Problem
+
+A user who notices something wrong mid-session has nowhere to put that observation. Telling the model wastes a turn, changes the conversation the user was having, and buries the remark in derived history where no later reader can find it. Writing it outside the session loses the context that makes it meaningful — which session, at which point, against which work.
+
+The capture surface has to be usable at the moment of annoyance, which rules out anything requiring the user to leave the TUI, and it must not perturb the run in progress: no model tokens, no turn of work, no change to the request the user is waiting on.
+
+## Decision
+
+`@deepseek-ai/dsh-command-feedback` in `packages/feedback/command-feedback/` registers one global `feedback` command over `ctx.commands`. `/feedback <text>` acknowledges; bare or whitespace-only input returns a direct usage error. The handler is synchronous, injects only `commands`, and has no configuration.
+
+The plugin appends **no session event of its own**. `dsh-commands` already writes a `command/run` / `command/done` pair for every dispatched command, carrying the command name, the verbatim unparsed suffix, the invocation source, and the settled outcome. Those records are log-only and non-surface, so the feedback lands in the session log and stays invisible to the model without this package contributing anything to the log format. The appends start persistence's ordinary eager drain; nothing forces a flush, so the acknowledgement reports that the entry is recorded in the log rather than already on disk.
+
+Capture is deliberately inert: nothing in this repository reads those records back.
+
+### Why no dedicated `session/feedback` event
+
+An earlier iteration declared one. It was removed because it duplicated a record the registry already writes: both would carry the same text, appended microseconds apart, and a consumer would have to decide which is authoritative. Selecting `command/run` records by command name is enough to find feedback, and it keeps this package free of the session event format entirely — no `SessionEventMap` merge, no invariant relation, no persistence catalog entry.
+
+The cost is that the recorded text is the raw suffix including its leading separator whitespace, and that feedback is distinguished from other commands only by name. Both are read-time concerns for a consumer that does not yet exist; neither justifies a second durable record now.
+
+### Why the model never sees it
+
+Feedback is about the session, not input to it. Injecting it as a user message would change the next model request, contradicting the requirement that recording not perturb the run, and would make the remark part of the conversation it comments on. `command/run` and `command/done` are absent from `SurfaceEventType`, so they cannot acquire a `surfaceOp` or enter derived history even by mistake.
+
+### Verbatim text
+
+Nothing is parsed. `/feedback /plan felt slow` records that literal text; the leading `/plan` is content, not a nested command. The handler trims only to decide whether any text was supplied. Control-word grammar of the kind `/goal` uses would make the corresponding literal feedback impossible to express, which is the opposite of what a capture surface is for.
+
+### A new group
+
+`packages/feedback/` is a new group because no existing one owns this. `goal/` is objective state, `session-title/` is titles, `core/` is the product spine. The group holds one package; a consumer would join it rather than forcing this one to grow.
+
+## Alternatives considered
+
+**Declare a dedicated `session/feedback` log-only event.** Implemented first, then removed. It gave feedback a first-class queryable type with pre-trimmed text, but duplicated the registry's record, added a `SessionEventMap` member and persistence-catalog entry to the frozen log format, and created two records of one act with no rule for which wins.
+
+**Inject feedback as a user message via `agent.inject()`.** Needs no new event type and reuses the path `/goal` mutations take. Rejected: it makes the feedback model-visible, so it enters the next request, changes the run being commented on, and consumes tokens — contradicting all three parts of the no-perturbation requirement.
+
+**Make `/feedback` a true no-op that records nothing.** The most literal reading of "does not do anything". Rejected because it makes the command pointless: the stated requirement was that the remark reach the session log.
+
+**Register the command inside an existing package** such as `packages/ui/commands`. Avoids a new group and its README pair. Rejected: `ctx.commands` is the registry, not a home for arbitrary command implementations, and the requester asked for a standalone package.
+
+**Parse structure out of the text** (category prefixes, severity markers). Rejected as speculative: no consumer exists to use the structure, and any control-word grammar makes the corresponding literal feedback unrecordable. Verbatim text is the widest surface a future consumer can narrow; a parsed one cannot be widened after the fact.
+
+**Add a model-facing tool instead of a slash command.** Rejected: feedback is a direct human observation. Routing it through the model spends a turn, lets the model paraphrase the user's words, and makes the record contingent on the model choosing to call the tool.
+
+## Consequences
+
+The TUI mounts the command unconditionally — no configuration, no dependency on the goal stack. The headless CLI, ACP, and JSON-RPC apps do not consume `ctx.commands`, so `/feedback` is unavailable there.
+
+This package is now small enough that its whole contract is the command definition plus one validation branch. It owns no session event, so it needs no invariant relation and cannot affect replay, forking, or crash recovery.
+
+Deferred: no consumer; no structured fields; no amend or withdraw, since the log is append-only and this package adds no tombstone; the recorded text is untrimmed, so a consumer trims at read time; and no explicit durability barrier, so an entry recorded immediately before a crash can be lost with any other unflushed tail.
+
+No snapshot accompanies this change. AGENTS.md asks for a keyless snapshot through a runnable example for product-user-visible behavior; this was skipped at the requester's explicit direction. The package tests plus a real Loader composition test over a `cordis.yml` are the whole of the evidence, alongside interactive verification in the assembled TUI.
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
new file mode 100644
index 0000000000..f69dbf6a50
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
@@ -0,0 +1,61 @@
+# Agent Note: `/feedback` 命令
+
+Status: implemented
+
+[English](2026-07-28-feedback-command.md) | 中文
+
+## 问题
+
+用户在会话中途发现问题时，没有地方记下这个观察。告诉模型会浪费一个轮次、改变用户原本进行的对话，并把这条评论埋进派生历史，使后续读者无法找到它。写到会话之外则会丢失让它有意义的上下文：属于哪个会话、处于哪个时点、针对哪项工作。
+
+采集接口必须能在用户产生不满的那一刻使用，因此任何需要用户离开 TUI 的方案都不可行；它还不能扰动正在进行的运行：不消耗模型 token、不产生工作轮次、不改变用户正在等待的请求。
+
+## 决策
+
+位于 `packages/feedback/command-feedback/` 的 `@deepseek-ai/dsh-command-feedback` 通过 `ctx.commands` 注册一个全局 `feedback` 命令。`/feedback <text>` 给出确认；空输入或仅含空白的输入返回直接用法错误。处理器是同步的，只注入 `commands`，且没有任何配置。
+
+该插件**不追加属于自己的会话事件**。`dsh-commands` 已经为每个已分发命令写入一对 `command/run` / `command/done`，携带命令名、原样未解析的后缀、调用来源以及结算结果。这些记录仅写入日志且非 surface，因此反馈会进入会话日志并对模型保持不可见，而本包无需向日志格式贡献任何内容。这些追加会启动持久化的常规即时排空；没有任何环节强制 flush，因此确认文本报告的是条目已记录在日志中，而非已经落盘。
+
+采集刻意不产生后续动作：本仓库中没有任何代码读回这些记录。
+
+### 为何不设专用的 `session/feedback` 事件
+
+早先的实现声明过该事件，后来将其移除，因为它重复了注册表已经写入的记录：两者会携带相同文本、相隔极短时间先后追加，而消费方还得判断以哪一条为准。依据命令名筛选 `command/run` 记录已足以找到反馈，同时让本包完全不涉及会话事件格式——没有 `SessionEventMap` 合并、没有不变式关系、没有持久化目录条目。
+
+代价是被记录的文本为原始后缀，包含其前导分隔空白；且反馈仅凭命令名与其他命令相区分。两者都属于尚不存在的消费方在读取时需要处理的问题，目前都不足以支撑再增加一条持久记录。
+
+### 为何模型永不看到它
+
+反馈是关于会话的，而不是会话的输入。将其作为 user 消息注入会改变下一次模型请求，与「记录不得扰动运行」的要求相冲突，也会让该评论成为它所评论的那段对话的一部分。`command/run` 与 `command/done` 不属于 `SurfaceEventType`，因此即便出错也无法获得 `surfaceOp` 或进入派生历史。
+
+### 原样文本
+
+不做任何解析。`/feedback /plan felt slow` 记录的就是该字面文本；开头的 `/plan` 是内容，而非嵌套命令。处理器仅为判断是否提供了文本而修剪。若采用 `/goal` 那样的控制词语法，对应的字面反馈将无法表达，这与采集接口的目的正好相反。
+
+### 一个新的分组
+
+`packages/feedback/` 是新分组，因为现有分组都不拥有此职责：`goal/` 负责目标状态，`session-title/` 负责标题，`core/` 是产品主干。该分组目前只有一个包；未来的消费方应加入该分组，而不是迫使这个包不断膨胀。
+
+## 考虑过的替代方案
+
+**声明专用的 `session/feedback` 仅日志事件。** 先实现后移除。它让反馈拥有一等的可查询类型和预先修剪的文本，但重复了注册表的记录，向已冻结的日志格式新增了一个 `SessionEventMap` 成员与持久化目录条目，并使同一行为产生两条记录而没有取舍规则。
+
+**通过 `agent.inject()` 将反馈作为 user 消息注入。** 无需新增事件类型，并复用 `/goal` 变更所走的路径。已否决：它会让反馈对模型可见，从而进入下一次请求、改变正被评论的那次运行并消耗 token——与「不得扰动」要求的三个方面全部冲突。
+
+**让 `/feedback` 成为真正的空操作，什么都不记录。** 这是对「什么都不做」最字面的理解。已否决：这会使命令失去意义——明确的要求是让这条评论进入会话日志。
+
+**在现有包中注册该命令**，例如 `packages/ui/commands`。可省去新分组及其双语 README。已否决：`ctx.commands` 是注册表，而不是任意命令实现的归属地；且请求者明确要求独立的包。
+
+**从文本中解析结构**（类别前缀、严重程度标记）。已否决，属于投机设计：目前没有消费方使用该结构，而任何控制词语法都会让对应的字面反馈无法记录。原样文本是未来消费方可以收窄的最宽接口；而已被解析的接口无法事后放宽。
+
+**改为提供面向模型的工具。** 已否决：反馈是人类的直接观察。经由模型会消耗一个轮次、让模型改写用户的原话，并使记录取决于模型是否选择调用该工具。
+
+## 后果
+
+TUI 无条件挂载该命令：没有配置，也不依赖 goal 栈。无头 CLI、ACP 和 JSON-RPC 应用不消费 `ctx.commands`，因此 `/feedback` 在那里不可用。
+
+本包现已小到其全部契约就是命令定义加一个校验分支。它不拥有任何会话事件，因此无需不变式关系，也不可能影响回放、fork 或崩溃恢复。
+
+延期事项：没有消费方；没有结构化字段；不支持修改或撤回，因为日志仅追加且本包不新增 tombstone；被记录的文本未修剪，需由消费方在读取时处理；且没有显式持久化屏障，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。
+
+本次变更不附带 snapshot。AGENTS.md 要求面向产品用户的可见行为变更通过可运行示例附带无密钥 snapshot；此项按请求者的明确指示跳过。包测试连同一个基于真实 `cordis.yml` 的 Loader 组合测试即为全部证据，此外还有在组装后 TUI 中的交互验证。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 68343a6a19..2c2d68e934 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1994,7 +1994,7 @@ export interface Config {
 
 Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`SessionReferenceConfig`](#deepseek-aidsh-session-reference) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`uiTui`](../packages/ui/tui/src/index.ts)
 
-Source: [`packages/examples/tui-demo/src/index.ts:39`](../packages/examples/tui-demo/src/index.ts)
+Source: [`packages/examples/tui-demo/src/index.ts:40`](../packages/examples/tui-demo/src/index.ts)
 
 ## `@deepseek-ai/dsh-user-approval`
 
@@ -2219,6 +2219,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-client-ui-theme` ([`packages/client/ui-theme/src/index.ts`](../packages/client/ui-theme/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-trajectory` ([`packages/client/ui-trajectory/src/index.ts`](../packages/client/ui-trajectory/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-workspace` ([`packages/client/ui-workspace/src/index.ts`](../packages/client/ui-workspace/src/index.ts))
+- `@deepseek-ai/dsh-command-feedback` — requires `commands` ([`packages/feedback/command-feedback/src/index.ts`](../packages/feedback/command-feedback/src/index.ts))
 - `@deepseek-ai/dsh-command-goal` — requires `commands` · `goals` ([`packages/goal/command-goal/src/index.ts`](../packages/goal/command-goal/src/index.ts))
 - `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts))
 - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts))
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 703f4c8abf..cc680d7c96 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -181,6 +181,9 @@ flowchart TD
     pkg_jsonrpc_demo["jsonrpc-demo"]
     pkg_tui_demo["tui-demo"]
   end
+  subgraph group_feedback["packages/feedback"]
+    pkg_command_feedback["command-feedback"]
+  end
   subgraph group_guard["packages/guard"]
     pkg_repeat_tool_guard["repeat-tool-guard"]
   end
@@ -604,6 +607,8 @@ flowchart TD
   pkg_client_ui_goal --> pkg_client_ui_slots
   pkg_client_ui_goal --> pkg_goal
   pkg_client_ui_goal --> pkg_invariants
+  pkg_command_feedback --> pkg_commands
+  pkg_command_feedback --> pkg_invariants
   pkg_pty_local --> pkg_agent
   pkg_pty_local --> pkg_invariants
   pkg_pty_local --> pkg_pty
@@ -928,6 +933,7 @@ flowchart TD
   pkg_tui_demo --> pkg_agent
   pkg_tui_demo --> pkg_agent_loop
   pkg_tui_demo --> pkg_agent_spine_demo
+  pkg_tui_demo --> pkg_command_feedback
   pkg_tui_demo --> pkg_command_goal
   pkg_tui_demo --> pkg_commands
   pkg_tui_demo --> pkg_invariants
@@ -1069,6 +1075,7 @@ flowchart TD
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
 | [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
 | [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | `telemetry` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
@@ -1116,6 +1123,6 @@ flowchart TD
 | [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`cli-demo`](../packages/examples/cli-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
-| [`tui-demo`](../packages/examples/tui-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`session-reference`](../packages/context/session-reference), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
+| [`tui-demo`](../packages/examples/tui-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`command-feedback`](../packages/feedback/command-feedback), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`session-reference`](../packages/context/session-reference), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
 | [`sdk-client`](../packages/sdk/sdk-client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/sdk-client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index ba5ab61b06..0510fee0b7 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 7a86e0f034264d4059e75775016d8d5d84600d8d
-README.zh.md: bfcba626bea2a70f5c2aa508bb2a5b8c09bb61dc
+README.md: b283af83596b738deeb6fc482fb4ff18bedf8df8
+README.zh.md: 91bc90ff05b849aaeec1ce1010a0e5a45b5a402a
diff --git a/packages/README.md b/packages/README.md
index 7a86e0f034..b283af8359 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -12,6 +12,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 |---|---|---|
 | [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable surface |
 | [`goal/`](goal/README.md) | Persisted same-session goal state and lifecycle | Product — stable surface |
+| [`feedback/`](feedback/README.md) | Recorded human feedback | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
@@ -50,7 +51,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
 
-Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.
+New packages join an existing group; a new group updates its README and this table.
 
 ## Dependencies
 
diff --git a/packages/README.zh.md b/packages/README.zh.md
index bfcba626be..91bc90ff05 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -12,6 +12,7 @@
 |---|---|---|
 | [`core/`](core/README.md) | 产品 API 主干：会话、提示词、工具、agent（智能体）服务与具体循环 | 产品：稳定表面 |
 | [`goal/`](goal/README.md) | 持久化的同会话 goal 状态与生命周期 | 产品：稳定表面 |
+| [`feedback/`](feedback/README.md) | 记录人类对会话的反馈 | 产品：稳定表面 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
@@ -50,7 +51,7 @@
 | [`support/`](support/README.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | 支持：兼容性预期较低 |
 | [`util/`](util/README.md) | 组间共享的低层零依赖工具（`Branded<B>`、Harness home／路径辅助函数、超时、保留策略） | 支持：小型、稳定、无 harness 依赖 |
 
-组用于区分产品 API 与支持基础设施。新包加入现有组；新组则更新其 README 和此表。
+新包加入现有组；新组则更新其 README 和此表。
 
 ## 依赖
 
diff --git a/packages/examples/tui-demo/package.json b/packages/examples/tui-demo/package.json
index 50145e6c29..9c48f98511 100644
--- a/packages/examples/tui-demo/package.json
+++ b/packages/examples/tui-demo/package.json
@@ -32,6 +32,7 @@
     "@deepseek-ai/dsh-agent-loop": "^0.0.1",
     "@deepseek-ai/dsh-commands": "^0.0.1",
     "@deepseek-ai/dsh-command-goal": "^0.0.1",
+    "@deepseek-ai/dsh-command-feedback": "^0.0.1",
     "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
@@ -55,6 +56,7 @@
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-command-goal": "workspace:^",
+    "@deepseek-ai/dsh-command-feedback": "workspace:^",
     "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
diff --git a/packages/examples/tui-demo/src/index.ts b/packages/examples/tui-demo/src/index.ts
index c60ba94b3c..9d2f6a3bdf 100644
--- a/packages/examples/tui-demo/src/index.ts
+++ b/packages/examples/tui-demo/src/index.ts
@@ -1,6 +1,6 @@
 /**
  * Full-screen terminal app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo})
- * plus persisted goals, human commands, JSONL persistence, keyboard-backed
+ * plus persisted goals, human commands including `/feedback`, JSONL persistence, keyboard-backed
  * user interaction, and one pre-created agent whose exact session identity the
  * TUI drives. Swappable adapters, executors, optional tools, and HMR stay in the leaf. This Loader plugin
  * intentionally exposes named exports only; a default export would hide its
@@ -16,6 +16,7 @@ import { SessionId } from '@deepseek-ai/dsh-session'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import CommandService from '@deepseek-ai/dsh-commands'
 import * as commandGoal from '@deepseek-ai/dsh-command-goal'
+import * as commandFeedback from '@deepseek-ai/dsh-command-feedback'
 import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
 import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import SessionPersistenceJsonl, {
@@ -122,6 +123,7 @@ export function composeTuiApp(ctx: Context, config: Config): void {
   const goals = config.goals ?? {}
   const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
   ctx.plugin(CommandService)
+  ctx.plugin(commandFeedback)
   if (goals !== false) ctx.plugin(commandGoal)
   ctx.plugin(SessionPersistenceJsonl, {
     root: persistenceRoot,
diff --git a/packages/examples/tui-demo/tests/tui-agent.spec.ts b/packages/examples/tui-demo/tests/tui-agent.spec.ts
index f647b3d9c6..aa483e7b1b 100644
--- a/packages/examples/tui-demo/tests/tui-agent.spec.ts
+++ b/packages/examples/tui-demo/tests/tui-agent.spec.ts
@@ -49,6 +49,7 @@ describe('dsh-tui-demo app', () => {
 
     expect(calls.map(call => call.name)).toEqual([
       'CommandService',
+      'command-feedback',
       'command-goal',
       'SessionPersistenceJsonl',
       'session-checkpoint-policy',
@@ -61,14 +62,14 @@ describe('dsh-tui-demo app', () => {
       'tool-ask-user',
     ])
     expect(calls[0]?.config).toBeUndefined()
-    expect(calls[2]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
-    expect(calls[4]?.config).toEqual({ path: join('/tmp/tui-sessions', 'session-query.db') })
-    expect(calls[5]?.config).toEqual({
+    expect(calls[3]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
+    expect(calls[5]?.config).toEqual({ path: join('/tmp/tui-sessions', 'session-query.db') })
+    expect(calls[6]?.config).toEqual({
       maxReferences: 2,
       candidateLimit: 7,
       maxReferenceBytes: 1234,
     })
-    const tuiConfig = calls[8]?.config as { sessionId: string }
+    const tuiConfig = calls[9]?.config as { sessionId: string }
     expect(tuiConfig).toMatchObject({
       welcome: 'TUI ready',
       resumeCommand: 'dsh --resume {session}',
@@ -76,7 +77,7 @@ describe('dsh-tui-demo app', () => {
       maxToolOutputLines: 3,
     })
     expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    const spineConfig = calls[9]?.config as {
+    const spineConfig = calls[10]?.config as {
       readonly agents: Array<Record<string, unknown>>
       readonly goals: Record<string, never>
       readonly maxParallelToolCalls: number
@@ -109,11 +110,11 @@ describe('dsh-tui-demo app', () => {
       workspaceContext: false,
     })
 
-    expect(calls[2]?.config).toEqual({ root: './.sessions' })
-    expect(calls[5]?.config).toEqual({})
+    expect(calls[3]?.config).toEqual({ root: './.sessions' })
+    expect(calls[6]?.config).toEqual({})
     // No configured welcome forwards none: the TUI banner sweeps in without a subtitle.
-    expect(calls[8]?.config).toEqual({ sessionId: 'persisted-session' })
-    expect((calls[9]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
+    expect(calls[9]?.config).toEqual({ sessionId: 'persisted-session' })
+    expect((calls[10]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
       id: 'main',
       resumeSessionId: 'persisted-session',
     })
@@ -129,12 +130,14 @@ describe('dsh-tui-demo app', () => {
       workspaceContext: false,
     })
 
-    const tuiConfig = calls[7]?.config as { sessionId: string }
+    const tuiConfig = calls[8]?.config as { sessionId: string }
     expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    expect((calls[8]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
+    expect((calls[9]?.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[8]?.config).toMatchObject({ goals: false })
+    // `/feedback` is unconditional: disabling goals must not remove it.
+    expect(calls.map(call => call.name)).toContain('command-feedback')
+    expect(calls[9]?.config).toMatchObject({ goals: false })
   })
 
   it('has the namespace-plugin export shape so the Loader keeps its schema', () => {
diff --git a/packages/examples/tui-demo/tsconfig.json b/packages/examples/tui-demo/tsconfig.json
index d26d5b7da6..bfd6d5554c 100644
--- a/packages/examples/tui-demo/tsconfig.json
+++ b/packages/examples/tui-demo/tsconfig.json
@@ -35,6 +35,9 @@
     {
       "path": "../../goal/command-goal"
     },
+    {
+      "path": "../../feedback/command-feedback"
+    },
     {
       "path": "../agent-spine-demo"
     },
diff --git a/packages/feedback/README.i18n.yaml b/packages/feedback/README.i18n.yaml
new file mode 100644
index 0000000000..eca3b1c420
--- /dev/null
+++ b/packages/feedback/README.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 packages/feedback/README.md
+README.md: ab7bc6f3e3a3be0c280855ff80e92c7d7a7e665e
+README.zh.md: 9c050ac42aa468895c04124a76a3bce58756df0e
diff --git a/packages/feedback/README.md b/packages/feedback/README.md
new file mode 100644
index 0000000000..ab7bc6f3e3
--- /dev/null
+++ b/packages/feedback/README.md
@@ -0,0 +1,11 @@
+# feedback/ — recorded human feedback
+
+English | [中文](README.zh.md)
+
+The feedback family lets a human record a remark about the session without acting on it. Feedback is durable session-log content, separate from the model conversation and from any policy that might later read it.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `command-feedback/` | Human-facing `/feedback` command recorded through the command plane | — |
+
+A recorded remark is log-only: it never enters the model surface or derived history, and no shipped plugin consumes it. A future consumer reads the command records from the session log rather than changing how they are captured.
diff --git a/packages/feedback/README.zh.md b/packages/feedback/README.zh.md
new file mode 100644
index 0000000000..9c050ac42a
--- /dev/null
+++ b/packages/feedback/README.zh.md
@@ -0,0 +1,11 @@
+# feedback/：记录的人类反馈
+
+[English](README.md) | 中文
+
+feedback 家族让人类记录对会话的评价，但不据此采取任何动作。反馈属于持久的会话日志内容，与模型对话以及后续可能读取它的任何策略相互独立。
+
+| 包 | 职责 | ctx 键 |
+|---|---|---|
+| `command-feedback/` | 面向用户的 `/feedback` 命令，通过命令平面完成记录 | 无 |
+
+被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史，随附插件也不会消费它。未来的消费方从会话日志中读取命令记录，而不是改变它们的采集方式。
diff --git a/packages/feedback/command-feedback/README.i18n.yaml b/packages/feedback/command-feedback/README.i18n.yaml
new file mode 100644
index 0000000000..37f10ac485
--- /dev/null
+++ b/packages/feedback/command-feedback/README.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 packages/feedback/command-feedback/README.md
+README.md: 90992b7295536a9099766910f616e640d4b4bcfe
+README.zh.md: a7c4f03997cea182ed24dcfc7f309dc3bd872d5e
diff --git a/packages/feedback/command-feedback/README.md b/packages/feedback/command-feedback/README.md
new file mode 100644
index 0000000000..90992b7295
--- /dev/null
+++ b/packages/feedback/command-feedback/README.md
@@ -0,0 +1,60 @@
+# @deepseek-ai/dsh-command-feedback
+
+English | [中文](README.zh.md)
+
+Human-facing `/feedback` capture. The plugin registers one global command through [`ctx.commands`](../../ui/commands/README.md), so every composed command adapter discovers it; the shipped TUI executes it without a model turn.
+
+## Command contract
+
+| Input | Result |
+|---|---|
+| `/feedback <text>` | Acknowledge with `Feedback recorded.` The registry's `command/run` record carries the verbatim text. |
+| `/feedback` | Return a direct usage error. Whitespace-only input is treated as empty. |
+
+Feedback text is never parsed: no truncation, case folding, or control words. Text that looks like another command, such as `/feedback /plan felt slow`, is feedback content. Repeated commands each produce their own record; nothing is replaced or merged.
+
+## What this plugin does and does not do
+
+The command records a remark and does nothing else. It appends no session event of its own, starts no model work, and no plugin in this repository reads its records.
+
+The record is the command registry's own `command/run` / `command/done` pairing, which [`dsh-commands`](../../ui/commands/README.md) appends for every dispatched command. Those appends start persistence's ordinary eager drain; neither the registry nor this command forces a `session/flush`, so the acknowledgement means the entry is in the log, not that it has already reached disk. `command/run` carries the command name, the verbatim unparsed suffix, and the invocation source; the paired `command/done` carries the outcome. Both are log-only and are absent from the ordered surface, from `deriveMessages()`, and from every model request. A rejected empty input still leaves that pairing, settled as `kind: 'error'`, so no entry can be mistaken for accepted feedback.
+
+A dedicated `session/feedback` event was considered and rejected: it would duplicate a record the registry already writes, and a consumer can select feedback by the command name it already stores.
+
+## Composition
+
+The producer injects only `commands`. A custom app mounts the registry plus this plugin:
+
+```yaml
+- id: commands
+  name: '@deepseek-ai/dsh-commands'
+- id: command-feedback
+  name: '@deepseek-ai/dsh-command-feedback'
+```
+
+The TUI app mounts this command unconditionally; it has no configuration and no dependency on the persisted-goal stack. The headless CLI, ACP automation, and JSON-RPC adapters do not consume `ctx.commands`, so they do not expose it.
+
+## Model Experience
+
+### Human `/feedback` capture
+
+#### What the model sees
+
+Nothing. The slash input, the recorded text, and the acknowledgement are all absent from model requests. The registry's `command/run` and `command/done` records are log-only and carry no `surfaceOp`, so they never reach the ordered surface, `deriveMessages()`, or a system prompt. Recording feedback during a turn does not change that turn's remaining requests.
+
+#### Token effect
+
+Zero direct token effect. Neither an accepted entry nor a usage error adds model tokens, in the recording turn or any later one.
+
+#### KV Cache effect
+
+Independent of the model request path. Recording appends to the session log only, leaving an already-reusable request prefix untouched. Nothing this package contributes can invalidate cache reuse.
+
+## Known Limitations and Deferred Work
+
+- **Nothing consumes the recorded feedback** — capture is deliberately inert. There is no retrieval, aggregation, export, or reporting surface, and no model-facing tool reads it; a consumer is a separate package that selects `command/run` records by command name.
+- **No structured fields** — an entry is one free-text string with no category, severity, or referenced-event link, so feedback cannot be filtered by subject without re-reading its text.
+- **No amend or withdraw** — the session log is append-only and this package adds no tombstone, so a mistaken entry stays recorded and can only be superseded by a later one.
+- **Untrimmed text in the record** — the handler trims only to validate; `command/run` stores the raw suffix, including its leading separator whitespace, so a consumer trims at read time.
+- **No explicit durability barrier** — the acknowledgement follows the append, not a flush, so an entry recorded immediately before a crash can be lost with any other unflushed tail. Feedback is not worth forcing a synchronous disk write for; a consumer that needs one awaits `ctx.sessions.flush(session)`.
+- **TUI only in the shipped apps** — the headless CLI, ACP automation, and JSON-RPC adapters do not mount `ctx.commands`, so `/feedback` is unavailable there.
diff --git a/packages/feedback/command-feedback/README.zh.md b/packages/feedback/command-feedback/README.zh.md
new file mode 100644
index 0000000000..a7c4f03997
--- /dev/null
+++ b/packages/feedback/command-feedback/README.zh.md
@@ -0,0 +1,60 @@
+# @deepseek-ai/dsh-command-feedback
+
+[English](README.md) | 中文
+
+面向用户的 `/feedback` 采集。该插件通过 [`ctx.commands`](../../ui/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附 TUI 无需模型轮次即可执行。
+
+## 命令契约
+
+| 输入 | 结果 |
+|---|---|
+| `/feedback <text>` | 以 `Feedback recorded.` 确认。注册表的 `command/run` 记录携带原样文本。 |
+| `/feedback` | 返回一个直接用法错误。仅含空白的输入视为空输入。 |
+
+反馈文本从不被解析：没有截断、大小写折叠或控制词。看起来像另一个命令的文本（例如 `/feedback /plan felt slow`）就是反馈内容。重复执行命令会各自产生自己的记录，不会替换或合并。
+
+## 本插件做什么、不做什么
+
+该命令记录一条评价，不做别的事。它不追加属于自己的会话事件，不启动任何模型工作，本仓库中也没有任何插件读取它的记录。
+
+记录来自命令注册表自身的 `command/run` / `command/done` 配对，由 [`dsh-commands`](../../ui/commands/README.md) 为每个已分发命令追加。这些追加会启动持久化的常规即时排空；注册表与本命令都不会强制 `session/flush`，因此确认文本表示条目已进入日志，而不表示它已经落盘。`command/run` 携带命令名、原样未解析的后缀以及调用来源；配对的 `command/done` 携带结果。两者都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及任何模型请求中。被拒绝的空输入仍会留下该配对，并以 `kind: 'error'` 结算，因此任何条目都不会被误认为已接受的反馈。
+
+曾考虑并否决了专用的 `session/feedback` 事件：它会重复注册表已经写入的记录，而消费方可以依据注册表已存储的命令名筛选反馈。
+
+## 组合
+
+生产方只注入 `commands`。自定义应用挂载注册表以及本插件：
+
+```yaml
+- id: commands
+  name: '@deepseek-ai/dsh-commands'
+- id: command-feedback
+  name: '@deepseek-ai/dsh-command-feedback'
+```
+
+TUI 应用无条件挂载此命令；它没有配置，也不依赖持久 goal 栈。无头 CLI、ACP 自动化和 JSON-RPC 适配器不消费 `ctx.commands`，因此不会暴露它。
+
+## 模型体验
+
+### 用户 `/feedback` 采集
+
+#### 模型看到的内容
+
+无。斜杠输入、被记录的文本以及确认文本都不出现在模型请求中。注册表的 `command/run` 与 `command/done` 记录仅写入日志且不携带 `surfaceOp`，因此它们绝不会进入有序 surface、`deriveMessages()` 或系统提示词。在某个轮次中记录反馈不会改变该轮次剩余的请求。
+
+#### Token 影响
+
+无直接 token 影响。无论是已接受的条目还是用法错误，都不会在记录所在轮次或此后任何轮次增加模型 token。
+
+#### KV Cache 影响
+
+与模型请求路径无关。记录只追加到会话日志，不触碰已经可复用的请求前缀。本包贡献的任何内容都不会使缓存复用失效。
+
+## 已知限制与暂缓工作
+
+- **没有任何消费方读取被记录的反馈**：采集刻意不产生任何后续动作。这里没有检索、聚合、导出或报告 surface，也没有面向模型的工具读取它；消费方是另一个依据命令名筛选 `command/run` 记录的独立包。
+- **没有结构化字段**：一条条目就是一个自由文本字符串，没有类别、严重程度或关联事件链接，因此无法在不重读文本的情况下按主题过滤反馈。
+- **不支持修改或撤回**：会话日志是仅追加的，本包也不新增 tombstone，因此错误的条目会一直保留在记录中，只能由后续条目取代。
+- **记录中的文本未修剪**：处理器只为校验而修剪；`command/run` 存储原始后缀，包含其前导分隔空白，因此消费方需在读取时修剪。
+- **没有显式持久化屏障**：确认文本紧随追加而非 flush，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。为反馈强制同步写盘并不值得；需要该保证的消费方可自行等待 `ctx.sessions.flush(session)`。
+- **随附应用中只有 TUI 使用此命令**：无头 CLI、ACP 自动化和 JSON-RPC 适配器不挂载 `ctx.commands`，因此 `/feedback` 在那里不可用。
diff --git a/packages/feedback/command-feedback/package.json b/packages/feedback/command-feedback/package.json
new file mode 100644
index 0000000000..6ad91d0e0d
--- /dev/null
+++ b/packages/feedback/command-feedback/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@deepseek-ai/dsh-command-feedback",
+  "description": "Human-facing slash command that records session feedback as a log-only event",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-commands": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/feedback/command-feedback/src/index.ts b/packages/feedback/command-feedback/src/index.ts
new file mode 100644
index 0000000000..7bf7cd0853
--- /dev/null
+++ b/packages/feedback/command-feedback/src/index.ts
@@ -0,0 +1,40 @@
+/**
+ * Human-facing `/feedback` command. It records a remark about the session and
+ * does nothing else: the command registry's own `command/run` and
+ * `command/done` events are the whole record, so this plugin only validates the
+ * input and acknowledges it. Those appends are eager but unflushed, so the
+ * acknowledgement reports the entry is logged, not that it reached disk.
+ * @module @deepseek-ai/dsh-command-feedback
+ */
+
+import type { Context } from 'cordis'
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands'
+
+export const name = 'command-feedback'
+export const inject = ['commands']
+
+const USAGE = 'Usage: /feedback <text>'
+
+/**
+ * Validate and acknowledge one feedback entry. `command/run` already carries
+ * the verbatim text, so no further append is needed; returning an error instead
+ * settles that record as `kind: 'error'` and leaves no accepted feedback.
+ * @param invocation - receiving agent, raw command input, and UI cancellation.
+ * @returns an acknowledgement, or a usage error when no feedback text was supplied.
+ */
+function executeFeedbackCommand(invocation: CommandInvocation): CommandResult {
+  if (invocation.rawInput.trim().length === 0) {
+    return { kind: 'error', text: `Feedback text is required. ${USAGE}` }
+  }
+  return { kind: 'success', text: 'Feedback recorded.' }
+}
+
+/** Register the global `/feedback` command for every composed command adapter. */
+export function apply(ctx: Context): void {
+  ctx.commands.register({
+    name: 'feedback',
+    description: 'record feedback about this session',
+    input: { hint: '<text>' },
+    handler: executeFeedbackCommand,
+  })
+}
diff --git a/packages/feedback/command-feedback/src/invariant.ts b/packages/feedback/command-feedback/src/invariant.ts
new file mode 100644
index 0000000000..72a3ead213
--- /dev/null
+++ b/packages/feedback/command-feedback/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-command-feedback`.
+ * @module @deepseek-ai/dsh-command-feedback/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-command-feedback'
+
+/** Cordis companion plugin name. */
+export const name = 'command-feedback-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this command declares no session event and owns no state projection. The
+ * `command/run`/`command/done` pairing that records feedback belongs to `dsh-commands`.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/feedback/command-feedback/tests/command-feedback.spec.ts b/packages/feedback/command-feedback/tests/command-feedback.spec.ts
new file mode 100644
index 0000000000..362bb8ce30
--- /dev/null
+++ b/packages/feedback/command-feedback/tests/command-feedback.spec.ts
@@ -0,0 +1,176 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import CommandService from '@deepseek-ai/dsh-commands'
+import SessionStore, { foldSurface, Session, SessionId } from '@deepseek-ai/dsh-session'
+import * as commandFeedback from '@deepseek-ai/dsh-command-feedback'
+
+interface Harness {
+  readonly ctx: Context
+  readonly agent: Agent
+  readonly session: Session
+  readonly plugin: Awaited<ReturnType<Context['plugin']>>
+}
+
+/** Build a live idle agent over a store-owned session, as an app's spine does. */
+function stubAgent(ctx: Context, id: string): { agent: Agent; session: Session } {
+  const session = ctx.sessions.create(SessionId(id))
+  let status: AgentStatus = 'idle'
+  const agent: Agent = {
+    id: session.id,
+    options: {},
+    session,
+    ctx: new Context(),
+    get status() { return status },
+    get acceptsNextStep() { return status === 'running' },
+    send: () => {},
+    followup: () => {},
+    steer: () => {},
+    inject: () => {},
+    cancel() { status = 'idle' },
+    whenIdle() { return Promise.resolve() },
+  }
+  return { agent, session }
+}
+
+/** Mount the real command registry and this producer. */
+async function harness(): Promise<Harness> {
+  const ctx = new Context()
+  await ctx.plugin(CommandService)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(SessionStore)
+  const plugin = await ctx.plugin(commandFeedback)
+  const { agent, session } = stubAgent(ctx, `command-feedback-${Math.random()}`)
+  ctx.agents.register(agent)
+  return { ctx, agent, session, plugin }
+}
+
+/** Execute `/feedback` through the same registry boundary as a UI adapter. */
+async function run(test: Harness, suffix = ''): Promise<{ kind: string; text?: string }> {
+  const settled = await test.ctx.commands.execute(
+    test.agent,
+    `/feedback${suffix}`,
+    new AbortController().signal,
+  )
+  if (settled === undefined) throw new Error('feedback command was not registered')
+  return settled.result
+}
+
+/** The registry's durable record of each accepted command, in log order. */
+function commandRecords(session: Session): { name: string; args: string; kind: string }[] {
+  const runs = session.events.filter(event => event.type === 'command/run')
+  return runs.map((event) => {
+    const done = session.events.find(item =>
+      item.type === 'command/done' && item.data.commandId === event.data.commandId)
+    if (done?.type !== 'command/done') throw new Error('every command/run must be paired')
+    return { name: event.data.name, args: event.data.args, kind: done.data.kind }
+  })
+}
+
+describe('@deepseek-ai/dsh-command-feedback registration', () => {
+  it('registers one global command with Loader-safe exports and disposes it', async () => {
+    const test = await harness()
+    expect(commandFeedback.name).toBe('command-feedback')
+    expect(commandFeedback.inject).toEqual(['commands'])
+    expect('default' in commandFeedback).toBe(false)
+    const loader = Object.create(Loader.prototype) as Loader
+    expect(loader.unwrapExports(commandFeedback)).toBe(commandFeedback)
+
+    expect(test.ctx.commands.list(test.agent)).toContainEqual({
+      name: 'feedback',
+      description: 'record feedback about this session',
+      input: { hint: '<text>' },
+    })
+    expect(test.ctx.commands.find(test.agent, 'feedback')).toBeDefined()
+
+    await test.plugin.dispose()
+    expect(test.ctx.commands.find(test.agent, 'feedback')).toBeUndefined()
+  })
+})
+
+describe('/feedback human command', () => {
+  it('acknowledges feedback and leaves the registry record as its durable trace', async () => {
+    const test = await harness()
+    await expect(run(test, ' the diff view is unreadable')).resolves.toEqual({
+      kind: 'success',
+      text: 'Feedback recorded.',
+    })
+    expect(commandRecords(test.session)).toEqual([
+      { name: 'feedback', args: ' the diff view is unreadable', kind: 'success' },
+    ])
+  })
+
+  it('adds no event of its own beyond the registry pairing', async () => {
+    const test = await harness()
+    await run(test, ' nothing else happens')
+    // The whole point of the command: record and do nothing. Only the
+    // registry's own pairing appears, and no turn of model work starts.
+    expect(test.session.events.map(event => event.type)).toEqual(['command/run', 'command/done'])
+  })
+
+  it('records verbatim text, including input that looks like another command', async () => {
+    const test = await harness()
+    await run(test, ' /plan felt SLOW\n\ttwice today ')
+    expect(commandRecords(test.session)).toEqual([
+      { name: 'feedback', args: ' /plan felt SLOW\n\ttwice today ', kind: 'success' },
+    ])
+  })
+
+  it('records each entry separately without replacing earlier ones', async () => {
+    const test = await harness()
+    await run(test, ' first')
+    await run(test, ' second')
+    expect(commandRecords(test.session).map(record => record.args)).toEqual([' first', ' second'])
+  })
+
+  it('records concurrent submissions in dispatch order', async () => {
+    const test = await harness()
+    const signal = new AbortController().signal
+    // The shipped TUI dispatches commands fire-and-forget.
+    const settled = await Promise.all([
+      test.ctx.commands.execute(test.agent, '/feedback first', signal),
+      test.ctx.commands.execute(test.agent, '/feedback second', signal),
+    ])
+    expect(settled.map(item => item?.result)).toEqual([
+      { kind: 'success', text: 'Feedback recorded.' },
+      { kind: 'success', text: 'Feedback recorded.' },
+    ])
+    expect(commandRecords(test.session).map(record => record.args)).toEqual([' first', ' second'])
+  })
+
+  it('keeps every recorded event off the model surface and out of derived history', async () => {
+    const test = await harness()
+    await run(test, ' invisible to the model')
+    for (const event of test.session.events) {
+      expect('surfaceOp' in event).toBe(false)
+      expect(test.session.deriveEventMessage(event)).toBeNull()
+    }
+    expect(foldSurface(test.session.events).nodes).toEqual([])
+    expect(test.session.surface.nodes).toEqual([])
+    expect(test.session.deriveMessages()).toEqual([])
+  })
+
+  it('rejects empty and whitespace-only input as a failed command record', async () => {
+    const test = await harness()
+    const expected = {
+      kind: 'error',
+      text: 'Feedback text is required. Usage: /feedback <text>',
+    }
+    await expect(run(test)).resolves.toEqual(expected)
+    await expect(run(test, '   \n\t ')).resolves.toEqual(expected)
+    // Rejected input still leaves the registry's own pairing, settled as an
+    // error, so no entry is mistaken for accepted feedback.
+    expect(commandRecords(test.session).map(record => record.kind)).toEqual(['error', 'error'])
+  })
+
+  it('records nothing when dispatch rejects an already-cancelled request', async () => {
+    const test = await harness()
+    const controller = new AbortController()
+    controller.abort(new Error('user cancelled the command'))
+    await expect(test.ctx.commands.execute(test.agent, '/feedback too late', controller.signal))
+      .rejects.toThrow('user cancelled the command')
+    expect(test.session.events).toEqual([])
+  })
+})
diff --git a/packages/feedback/command-feedback/tests/loader-composition.spec.ts b/packages/feedback/command-feedback/tests/loader-composition.spec.ts
new file mode 100644
index 0000000000..9aa206f9ad
--- /dev/null
+++ b/packages/feedback/command-feedback/tests/loader-composition.spec.ts
@@ -0,0 +1,105 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import Include from '@cordisjs/plugin-include'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import CommandService from '@deepseek-ai/dsh-commands'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import * as CommandFeedback from '@deepseek-ai/dsh-command-feedback'
+
+let root: string | undefined
+let context: Context | undefined
+
+afterEach(async () => {
+  await context?.fiber.dispose()
+  context = undefined
+  if (root !== undefined) await rm(root, { recursive: true, force: true })
+  root = undefined
+})
+
+/** Register one idle agent over a store-owned session, as an app's spine does. */
+function agent(ctx: Context): Agent {
+  const scope = ctx.plugin(() => {})
+  const id = SessionId('feedback-loader-agent')
+  const session = ctx.sessions.create(id)
+  let status: AgentStatus = 'idle'
+  const value: Agent = {
+    id,
+    options: {},
+    session,
+    ctx: scope.ctx,
+    get status() { return status },
+    get acceptsNextStep() { return status === 'running' },
+    send: () => {},
+    followup: () => {},
+    steer: () => {},
+    inject: () => {},
+    cancel() { status = 'idle' },
+    whenIdle: () => Promise.resolve(),
+  }
+  ctx.agents.register(value)
+  return value
+}
+
+describe('/feedback real Loader composition through cordis.yml', () => {
+  it('boots cordis.yml and records feedback without model-visible output', async () => {
+    root = await mkdtemp(join(tmpdir(), 'dsh-command-feedback-loader-'))
+    const configPath = join(root, 'cordis.yml')
+    await writeFile(configPath, [
+      "- name: '@deepseek-ai/dsh-agent'",
+      "- name: '@deepseek-ai/dsh-session'",
+      "- name: '@deepseek-ai/dsh-commands'",
+      "- name: '@deepseek-ai/dsh-command-feedback'",
+      '',
+    ].join('\n'))
+
+    context = new Context()
+    context.baseUrl = pathToFileURL(root).href + '/'
+    await context.plugin(Loader)
+    context.loader.builtins.include = Include
+    const modules = new Map<string, unknown>([
+      ['@deepseek-ai/dsh-agent', AgentRegistry],
+      ['@deepseek-ai/dsh-session', SessionStore],
+      ['@deepseek-ai/dsh-commands', CommandService],
+      ['@deepseek-ai/dsh-command-feedback', CommandFeedback],
+    ])
+    context.loader.internal = {
+      version: 'v2',
+      async import(specifier: string) {
+        if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
+        return modules.get(specifier)
+      },
+    } as unknown as NonNullable<typeof context.loader.internal>
+    await context.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(configPath).href } })
+    await context.loader.await()
+
+    const owner = agent(context)
+    const signal = new AbortController().signal
+
+    // Discoverable through the composed registry, as a UI adapter finds it.
+    expect(context.commands.list(owner).map(command => command.name)).toContain('feedback')
+
+    const accepted = await context.commands.execute(owner, '/feedback the diff view is unreadable', signal)
+    expect(accepted?.result).toEqual({ kind: 'success', text: 'Feedback recorded.' })
+    const rejected = await context.commands.execute(owner, '/feedback', signal)
+    expect(rejected?.result).toEqual({
+      kind: 'error',
+      text: 'Feedback text is required. Usage: /feedback <text>',
+    })
+
+    // The command records itself through the registry and does nothing else.
+    expect(owner.session.events.map(event => event.type))
+      .toEqual(['command/run', 'command/done', 'command/run', 'command/done'])
+    const run = owner.session.events.find(event => event.type === 'command/run')
+    expect(run?.type === 'command/run' && run.data.args).toBe(' the diff view is unreadable')
+
+    // Nothing reached the model.
+    expect(owner.session.deriveMessages()).toEqual([])
+    expect(owner.session.surface.nodes).toEqual([])
+  })
+})
diff --git a/packages/feedback/command-feedback/tsconfig.json b/packages/feedback/command-feedback/tsconfig.json
new file mode 100644
index 0000000000..6a27b54d3a
--- /dev/null
+++ b/packages/feedback/command-feedback/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../ui/commands"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 18cb1ec0d1..38e1c9eef5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2303,6 +2303,9 @@ importers:
       '@deepseek-ai/dsh-agent-spine-demo':
         specifier: workspace:^
         version: link:../agent-spine-demo
+      '@deepseek-ai/dsh-command-feedback':
+        specifier: workspace:^
+        version: link:../../feedback/command-feedback
       '@deepseek-ai/dsh-command-goal':
         specifier: workspace:^
         version: link:../../goal/command-goal
@@ -2358,6 +2361,33 @@ importers:
         specifier: ^3.17.0
         version: 3.18.0
 
+  packages/feedback/command-feedback:
+    devDependencies:
+      '@cordisjs/plugin-include':
+        specifier: workspace:^
+        version: link:../../../vendor/include
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-commands':
+        specifier: workspace:^
+        version: link:../../ui/commands
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader)
+
   packages/fs/fs:
     devDependencies:
       '@deepseek-ai/dsh-brand':
diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json
index 42198d4eea..7a67ce8bac 100644
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -7,5 +7,5 @@
   "docs/testing.md": 1100,
   "examples/AGENTS.md": 310,
   "packages/AGENTS.md": 675,
-  "packages/README.md": 870
+  "packages/README.md": 880
 }
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 00c19c4b8c..b87f867107 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -72,6 +72,7 @@
         "./packages/compact/*/src/invariant.ts",
         "./packages/context/*/src/invariant.ts",
         "./packages/goal/*/src/invariant.ts",
+        "./packages/feedback/*/src/invariant.ts",
         "./packages/guard/*/src/invariant.ts",
         "./packages/plan/*/src/invariant.ts",
         "./packages/subagent/*/src/invariant.ts",
@@ -161,6 +162,7 @@
         "./packages/compact/*/src",
         "./packages/context/*/src",
         "./packages/goal/*/src",
+        "./packages/feedback/*/src",
         "./packages/guard/*/src",
         "./packages/plan/*/src",
         "./packages/subagent/*/src",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index e2112b7f6a..5c1a7488c0 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -83,6 +83,7 @@
     { "path": "./packages/goal/tool-goal" },
     { "path": "./packages/goal/goal-session" },
     { "path": "./packages/goal/command-goal" },
+    { "path": "./packages/feedback/command-feedback" },
     { "path": "./packages/context/time-context" },
     { "path": "./packages/context/session-reference" },
     { "path": "./packages/ui/user-interaction" },

From eb6fa864813f6513a037e79b4dbacf9d4477338d Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Wed, 29 Jul 2026 21:33:53 +0800
Subject: [PATCH 002/516] fix(feedback): keep payload in feedback event

---
 .../2026-07-28-feedback-command.i18n.yaml     |  4 +-
 .../feature/2026-07-28-feedback-command.md    | 20 +++---
 .../feature/2026-07-28-feedback-command.zh.md | 20 +++---
 ...ssion-projection-and-command-log.i18n.yaml |  4 +-
 ...7-27-session-projection-and-command-log.md |  4 +-
 ...7-session-projection-and-command-log.zh.md |  4 +-
 docs/cordis-catalog/events.md                 |  2 +-
 docs/cordis-catalog/services.md               |  2 +-
 docs/core-data-structures/commands.i18n.yaml  |  6 +-
 docs/core-data-structures/commands.md         |  6 ++
 docs/core-data-structures/commands.zh.md      |  6 ++
 docs/event-producer-consumer.md               |  2 +-
 docs/persistence-catalog.md                   | 23 +++++--
 .../client/connection/src/client/fixture.ts   | 12 ++--
 .../src/client/sessions/conversation.ts       |  5 +-
 .../src/client/sessions/fold-adapter.ts       |  4 +-
 packages/client/runtime/tests/event-script.ts |  2 +
 .../client/runtime/tests/fold-adapter.spec.ts |  8 +++
 .../src/client/chat/GenericCommandCard.tsx    |  4 +-
 .../cordis/tool-cordis/src/api-catalog.ts     |  2 +-
 packages/feedback/README.i18n.yaml            |  4 +-
 packages/feedback/README.md                   |  4 +-
 packages/feedback/README.zh.md                |  4 +-
 .../command-feedback/README.i18n.yaml         |  4 +-
 packages/feedback/command-feedback/README.md  | 17 +++--
 .../feedback/command-feedback/README.zh.md    | 17 +++--
 .../feedback/command-feedback/package.json    |  3 +-
 .../feedback/command-feedback/src/index.ts    | 39 +++++++++---
 .../command-feedback/src/invariant.ts         |  4 +-
 .../tests/command-feedback.spec.ts            | 62 +++++++++++--------
 .../tests/loader-composition.spec.ts          |  9 ++-
 .../feedback/command-feedback/tsconfig.json   |  3 +
 packages/plan/plan-mode/README.i18n.yaml      |  4 +-
 packages/plan/plan-mode/README.md             |  2 +-
 packages/plan/plan-mode/README.zh.md          |  2 +-
 packages/plan/plan-mode/src/index.ts          |  1 +
 .../plan/plan-mode/tests/projection.spec.ts   | 11 +++-
 packages/ui/commands/README.i18n.yaml         |  4 +-
 packages/ui/commands/README.md                |  4 +-
 packages/ui/commands/README.zh.md             |  4 +-
 packages/ui/commands/src/index.ts             | 17 ++++-
 packages/ui/commands/tests/commands.spec.ts   | 19 ++++++
 42 files changed, 248 insertions(+), 130 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
index ba56da8945..7a429953d8 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-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 .agents/notes/implemented/feature/2026-07-28-feedback-command.md
-2026-07-28-feedback-command.md: ae32d3908d568c4a511e8d9e2b8cf50569fb80bf
-2026-07-28-feedback-command.zh.md: f69dbf6a50161e7f5048b76be46bc4063f9e757a
+2026-07-28-feedback-command.md: 1c093d0e37eb72dc66e3c5569bd642557dde56a1
+2026-07-28-feedback-command.zh.md: 300946a71ac7485a4bc787dd70ae5357147627f3
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
index ae32d3908d..1c093d0e37 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
@@ -14,15 +14,15 @@ The capture surface has to be usable at the moment of annoyance, which rules out
 
 `@deepseek-ai/dsh-command-feedback` in `packages/feedback/command-feedback/` registers one global `feedback` command over `ctx.commands`. `/feedback <text>` acknowledges; bare or whitespace-only input returns a direct usage error. The handler is synchronous, injects only `commands`, and has no configuration.
 
-The plugin appends **no session event of its own**. `dsh-commands` already writes a `command/run` / `command/done` pair for every dispatched command, carrying the command name, the verbatim unparsed suffix, the invocation source, and the settled outcome. Those records are log-only and non-surface, so the feedback lands in the session log and stays invisible to the model without this package contributing anything to the log format. The appends start persistence's ordinary eager drain; nothing forces a flush, so the acknowledgement reports that the entry is recorded in the log rather than already on disk.
+The package declares the log-only `feedback/record { text }` session event and exports `recordFeedback(session, text)` as its command-independent producer. The producer discards surrounding whitespace, rejects an empty result, and appends exactly one event. `/feedback` delegates to it, so another UI, hook, or host integration can record the same domain fact without constructing a slash command.
 
-Capture is deliberately inert: nothing in this repository reads those records back.
+`dsh-commands` still writes its `command/run` / `command/done` lifecycle pair around `/feedback`, but this command sets `recordInput: false`. Its `command/run` therefore carries the command identity and source without `args`; the feedback text exists only in `feedback/record`, while `command/done` carries the acknowledgement outcome. All three records are log-only and non-surface. Their appends start persistence's ordinary eager drain; nothing forces a flush, so acknowledgement reports that the feedback is in the log rather than already on disk.
 
-### Why no dedicated `session/feedback` event
+Capture is deliberately inert: nothing in this repository reads `feedback/record`.
 
-An earlier iteration declared one. It was removed because it duplicated a record the registry already writes: both would carry the same text, appended microseconds apart, and a consumer would have to decide which is authoritative. Selecting `command/run` records by command name is enough to find feedback, and it keeps this package free of the session event format entirely — no `SessionEventMap` merge, no invariant relation, no persistence catalog entry.
+### Why feedback owns an event
 
-The cost is that the recorded text is the raw suffix including its leading separator whitespace, and that feedback is distinguished from other commands only by name. Both are read-time concerns for a consumer that does not yet exist; neither justifies a second durable record now.
+Feedback is a domain fact, while `/feedback` is one trigger. Keeping the only payload in `feedback/record` lets later triggers use the same event and lets consumers select feedback without depending on command names or parsing command lifecycle records. Omitting `command/run.args` for this definition avoids two authoritative-looking copies of one human remark.
 
 ### Why the model never sees it
 
@@ -30,7 +30,7 @@ Feedback is about the session, not input to it. Injecting it as a user message w
 
 ### Verbatim text
 
-Nothing is parsed. `/feedback /plan felt slow` records that literal text; the leading `/plan` is content, not a nested command. The handler trims only to decide whether any text was supplied. Control-word grammar of the kind `/goal` uses would make the corresponding literal feedback impossible to express, which is the opposite of what a capture surface is for.
+Surrounding whitespace is discarded, but nothing else is parsed. `/feedback /plan felt slow` records `/plan felt slow`; the leading `/plan` is content, not a nested command. Control-word grammar of the kind `/goal` uses would make the corresponding literal feedback impossible to express, which is the opposite of what a capture surface is for.
 
 ### A new group
 
@@ -38,7 +38,9 @@ Nothing is parsed. `/feedback /plan felt slow` records that literal text; the le
 
 ## Alternatives considered
 
-**Declare a dedicated `session/feedback` log-only event.** Implemented first, then removed. It gave feedback a first-class queryable type with pre-trimmed text, but duplicated the registry's record, added a `SessionEventMap` member and persistence-catalog entry to the frozen log format, and created two records of one act with no rule for which wins.
+**Use `command/run` as the feedback record.** Rejected because feedback would then be coupled to one trigger and consumers would have to identify a domain fact by command name. A non-command producer could not create the same record without pretending to execute a command.
+
+**Store the text in both `feedback/record` and `command/run.args`.** Rejected because one act would have two payload copies with no useful distinction. `recordInput: false` preserves the generic lifecycle while leaving the domain event authoritative.
 
 **Inject feedback as a user message via `agent.inject()`.** Needs no new event type and reuses the path `/goal` mutations take. Rejected: it makes the feedback model-visible, so it enters the next request, changes the run being commented on, and consumes tokens — contradicting all three parts of the no-perturbation requirement.
 
@@ -54,8 +56,8 @@ Nothing is parsed. `/feedback /plan felt slow` records that literal text; the le
 
 The TUI mounts the command unconditionally — no configuration, no dependency on the goal stack. The headless CLI, ACP, and JSON-RPC apps do not consume `ctx.commands`, so `/feedback` is unavailable there.
 
-This package is now small enough that its whole contract is the command definition plus one validation branch. It owns no session event, so it needs no invariant relation and cannot affect replay, forking, or crash recovery.
+The package owns one independent append-only event with no cross-event or mutable-data relation for an invariant companion to check. The event follows the session log's existing replay, fork, persistence, and crash-tail behavior.
 
-Deferred: no consumer; no structured fields; no amend or withdraw, since the log is append-only and this package adds no tombstone; the recorded text is untrimmed, so a consumer trims at read time; and no explicit durability barrier, so an entry recorded immediately before a crash can be lost with any other unflushed tail.
+Deferred: no consumer; no structured fields; no amend or withdraw, since the log is append-only and this package adds no tombstone; and no explicit durability barrier, so an entry recorded immediately before a crash can be lost with any other unflushed tail.
 
 No snapshot accompanies this change. AGENTS.md asks for a keyless snapshot through a runnable example for product-user-visible behavior; this was skipped at the requester's explicit direction. The package tests plus a real Loader composition test over a `cordis.yml` are the whole of the evidence, alongside interactive verification in the assembled TUI.
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
index f69dbf6a50..300946a71a 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
@@ -14,15 +14,15 @@ Status: implemented
 
 位于 `packages/feedback/command-feedback/` 的 `@deepseek-ai/dsh-command-feedback` 通过 `ctx.commands` 注册一个全局 `feedback` 命令。`/feedback <text>` 给出确认；空输入或仅含空白的输入返回直接用法错误。处理器是同步的，只注入 `commands`，且没有任何配置。
 
-该插件**不追加属于自己的会话事件**。`dsh-commands` 已经为每个已分发命令写入一对 `command/run` / `command/done`，携带命令名、原样未解析的后缀、调用来源以及结算结果。这些记录仅写入日志且非 surface，因此反馈会进入会话日志并对模型保持不可见，而本包无需向日志格式贡献任何内容。这些追加会启动持久化的常规即时排空；没有任何环节强制 flush，因此确认文本报告的是条目已记录在日志中，而非已经落盘。
+本包（package）声明仅写入日志的 `feedback/record { text }` 会话事件，并导出 `recordFeedback(session, text)`，作为不依赖命令的生产方。该生产方丢弃前后空白，拒绝空结果，并且恰好追加一个事件。`/feedback` 委托给它，因此其他 UI、钩子或 host 集成无需构造斜杠命令也能记录同一个领域事实。
 
-采集刻意不产生后续动作：本仓库中没有任何代码读回这些记录。
+`dsh-commands` 仍会围绕 `/feedback` 写入 `command/run` / `command/done` 生命周期配对，但该命令设置了 `recordInput: false`。因此，它的 `command/run` 携带命令标识与来源，但不携带 `args`；反馈文本只存在于 `feedback/record` 中，而 `command/done` 携带确认结果。三个记录都仅写入日志且非 surface。它们的追加会启动持久化的常规即时排空；没有任何环节强制 flush，因此确认文本报告的是反馈已进入日志，而非已经落盘。
 
-### 为何不设专用的 `session/feedback` 事件
+采集刻意不产生后续动作：本仓库中没有任何代码读取 `feedback/record`。
 
-早先的实现声明过该事件，后来将其移除，因为它重复了注册表已经写入的记录：两者会携带相同文本、相隔极短时间先后追加，而消费方还得判断以哪一条为准。依据命令名筛选 `command/run` 记录已足以找到反馈，同时让本包完全不涉及会话事件格式——没有 `SessionEventMap` 合并、没有不变式关系、没有持久化目录条目。
+### 为何反馈拥有自己的事件
 
-代价是被记录的文本为原始后缀，包含其前导分隔空白；且反馈仅凭命令名与其他命令相区分。两者都属于尚不存在的消费方在读取时需要处理的问题，目前都不足以支撑再增加一条持久记录。
+反馈是领域事实，而 `/feedback` 是一种触发方式。只把载荷保存在 `feedback/record` 中，既让后续触发方式可以使用同一个事件，也让消费方无需依赖命令名或解析命令生命周期记录即可筛选反馈。在该定义中省略 `command/run.args`，可避免同一条人类评价出现两个看起来都具有权威性的副本。
 
 ### 为何模型永不看到它
 
@@ -30,7 +30,7 @@ Status: implemented
 
 ### 原样文本
 
-不做任何解析。`/feedback /plan felt slow` 记录的就是该字面文本；开头的 `/plan` 是内容，而非嵌套命令。处理器仅为判断是否提供了文本而修剪。若采用 `/goal` 那样的控制词语法，对应的字面反馈将无法表达，这与采集接口的目的正好相反。
+前后空白会被丢弃，但除此之外不做解析。`/feedback /plan felt slow` 记录 `/plan felt slow`；开头的 `/plan` 是内容，而非嵌套命令。若采用 `/goal` 那样的控制词语法，对应的字面反馈将无法表达，这与采集接口的目的正好相反。
 
 ### 一个新的分组
 
@@ -38,7 +38,9 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-**声明专用的 `session/feedback` 仅日志事件。** 先实现后移除。它让反馈拥有一等的可查询类型和预先修剪的文本，但重复了注册表的记录，向已冻结的日志格式新增了一个 `SessionEventMap` 成员与持久化目录条目，并使同一行为产生两条记录而没有取舍规则。
+**使用 `command/run` 作为反馈记录。** 已否决，因为这会将反馈与一种触发方式耦合，消费方还必须通过命令名识别领域事实。非命令生产方若不伪装成执行命令，就无法创建相同记录。
+
+**同时在 `feedback/record` 与 `command/run.args` 中存储文本。** 已否决，因为同一行为会产生两个没有实质区别的载荷副本。`recordInput: false` 保留通用生命周期，同时让领域事件保持权威性。
 
 **通过 `agent.inject()` 将反馈作为 user 消息注入。** 无需新增事件类型，并复用 `/goal` 变更所走的路径。已否决：它会让反馈对模型可见，从而进入下一次请求、改变正被评论的那次运行并消耗 token——与「不得扰动」要求的三个方面全部冲突。
 
@@ -54,8 +56,8 @@ Status: implemented
 
 TUI 无条件挂载该命令：没有配置，也不依赖 goal 栈。无头 CLI、ACP 和 JSON-RPC 应用不消费 `ctx.commands`，因此 `/feedback` 在那里不可用。
 
-本包现已小到其全部契约就是命令定义加一个校验分支。它不拥有任何会话事件，因此无需不变式关系，也不可能影响回放、fork 或崩溃恢复。
+本包拥有一个独立的仅追加事件，不存在跨事件关系或可变数据关系可供不变式伴生插件检查。该事件遵循会话日志现有的回放、fork、持久化和崩溃尾部行为。
 
-延期事项：没有消费方；没有结构化字段；不支持修改或撤回，因为日志仅追加且本包不新增 tombstone；被记录的文本未修剪，需由消费方在读取时处理；且没有显式持久化屏障，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。
+延期事项：没有消费方；没有结构化字段；不支持修改或撤回，因为日志仅追加且本包不新增 tombstone；且没有显式持久化屏障，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。
 
 本次变更不附带 snapshot。AGENTS.md 要求面向产品用户的可见行为变更通过可运行示例附带无密钥 snapshot；此项按请求者的明确指示跳过。包测试连同一个基于真实 `cordis.yml` 的 Loader 组合测试即为全部证据，此外还有在组装后 TUI 中的交互验证。
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index 8f720e33b5..49c96e63a3 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.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 .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
-2026-07-27-session-projection-and-command-log.md: 6a073c956c27bbfc65cff2d4f44ca12023df0cd5
-2026-07-27-session-projection-and-command-log.zh.md: 500f07968db049e4a174ff3b7a075bfe095283db
+2026-07-27-session-projection-and-command-log.md: 6ffdae7df9e908356c972f077d66b831f3b6a1ff
+2026-07-27-session-projection-and-command-log.zh.md: d2a40fb72245df413c7790932a41ddea3be7902d
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
index 6a073c956c..6ffdae7df9 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
@@ -115,11 +115,11 @@ The one existing violation of "no hooks through inject" — `DetailsInjected.use
 Two log-only (non-surface, model-invisible) events, mirroring the `tool/call`/`tool/result` pairing:
 
 ```ts ignore-check
-'command/run':  { commandId: string; name: string; args: string; source: CommandSource }
+'command/run':  { commandId: string; name: string; args?: string; source: CommandSource }
 'command/done': { commandId: string; kind: 'success' | 'error'; text?: string }
 ```
 
-The host command executor (`packages/ui/commands`) appends `command/run` before invoking the handler and `command/done` at settlement — direct standalone appends on the receiving agent's session, in the same shape as every other plugin-owned log-only event after the [synthetic-turn removal](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md): no turn wraps them (turns describe model-loop executions only), persistence drains them at ordinary checkpoints, and the commands package's own invariant companion enforces the run/done pairing. The payload is structured — `name` and `args` are the parser's own split (`parseCommand`'s name and rawInput), so a consumer (a projection unit folding its own command records, a rich command card) never re-parses a line. `text` is the handler's verbatim outcome — factual data of the same nature as `tool/result.content`, not presentation (how it is laid out remains client-computed at render time, satisfying the "presentation never enters the log" red line). Domains that want the model to know the outcome keep doing what they do today (plan's narration, goal's inject) — that is a domain decision, unchanged.
+The host command executor (`packages/ui/commands`) appends `command/run` before invoking the handler and `command/done` at settlement — direct standalone appends on the receiving agent's session, in the same shape as every other plugin-owned log-only event after the [synthetic-turn removal](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md): no turn wraps them (turns describe model-loop executions only), persistence drains them at ordinary checkpoints, and the commands package's own invariant companion enforces the run/done pairing. The payload is structured — `name` and, by default, `args` are the parser's own split (`parseCommand`'s name and rawInput), so a consumer (a projection unit folding its own command records, a rich command card) never re-parses a line. A definition sets `recordInput: false` when its authoritative domain event owns the payload; `command/run` then omits `args` rather than duplicating it. `text` is the handler's verbatim outcome — factual data of the same nature as `tool/result.content`, not presentation (how it is laid out remains client-computed at render time, satisfying the "presentation never enters the log" red line). Domains that want the model to know the outcome keep doing what they do today (plan's narration, goal's inject) — that is a domain decision, unchanged.
 
 Because committed events broadcast on the mux stream, refresh persistence, multi-tab sync, and fork/resume recovery all come for free. The `command.execute` RPC degrades to admission — `{ matched, commandId? }`: whether the line resolved, and the minted pairing id when it did, so the issuing client can correlate its request with the flow node the lifecycle events produce. The one-shot notice channel (`runDetached` → `noticeFor`) is retired.
 
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index 500f07968d..d2a40fb722 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -115,11 +115,11 @@ type UseProjection = {
 两个仅日志（非 surface、模型不可见）事件，镜像 `tool/call`/`tool/result` 的配对：
 
 ```ts ignore-check
-'command/run':  { commandId: string; name: string; args: string; source: CommandSource }
+'command/run':  { commandId: string; name: string; args?: string; source: CommandSource }
 'command/done': { commandId: string; kind: 'success' | 'error'; text?: string }
 ```
 
-host 侧命令执行器（`packages/ui/commands`）在调用处理器前追加 `command/run`，在结算时追加 `command/done`——在接收 agent 的会话上直接独立追加，与[合成轮次移除](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md)之后所有插件自有 log-only 事件同一形状：没有轮次包裹它们（轮次只描述模型循环执行），持久化在常规检查点排空它们，run/done 配对由 commands 包自己的 invariant 伴生插件把守。载荷是结构化的——`name` 与 `args` 就是解析器自己的切分（`parseCommand` 的 name 与 rawInput），因此消费方（折叠自己命令记录的投影单元、富命令卡片）永远无需重新解析行文本。`text` 是处理器的原样结果——与 `tool/result.content` 同一性质的事实数据，不是呈现（版式如何编排仍由客户端在渲染时计算，满足「呈现永不入日志」这条红线）。想让模型知道结果的领域继续做它们今天在做的事（plan 的旁白、goal 的注入）——那是领域自己的决定，保持不变。
+host 侧命令执行器（`packages/ui/commands`）在调用处理器前追加 `command/run`，在结算时追加 `command/done`——在接收 agent 的会话上直接独立追加，与[合成轮次移除](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md)之后所有插件自有 log-only 事件同一形状：没有轮次包裹它们（轮次只描述模型循环执行），持久化在常规检查点排空它们，run/done 配对由 commands 包自己的 invariant 伴生插件把守。载荷是结构化的——`name` 以及默认携带的 `args` 来自解析器自己的切分（`parseCommand` 的 name 与 rawInput），因此消费方（折叠自己命令记录的投影单元、富命令卡片）永远无需重新解析行文本。当载荷由权威领域事件持有时，命令定义会设置 `recordInput: false`；此时 `command/run` 省略 `args`，而不是重复该载荷。`text` 是处理器的原样结果——与 `tool/result.content` 同一性质的事实数据，不是呈现（版式如何编排仍由客户端在渲染时计算，满足「呈现永不入日志」这条红线）。想让模型知道结果的领域继续做它们今天在做的事（plan 的旁白、goal 的注入）——那是领域自己的决定，保持不变。
 
 由于已提交事件会在 mux 流上广播，刷新后仍在、多标签页同步、fork/恢复后可还原这三件事随之全部自动获得。`command.execute` RPC 退化为准入判定——`{ matched, commandId? }`：该行是否匹配命中，以及命中时新铸的配对 id，发起命令的客户端据此把自己的请求与生命周期事件产出的 flow 节点关联起来。一次性通知通道（`runDetached` → `noticeFor`）就此下线。
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 967241fbf6..54291934fd 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -420,7 +420,7 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/ui/commands/src/index.ts:154`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/ui/commands/src/index.ts:161`](../../packages/ui/commands/src/index.ts)
 
 ## `domain/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index e0dd17fa02..ffd80cc6e5 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -442,7 +442,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](../core-data-structures/core.md) · [CommandDefinition](../core-data-structures/commands.md) · [CommandDescriptor](../core-data-structures/commands.md)
 
-Source: [`packages/ui/commands/src/index.ts:278`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/ui/commands/src/index.ts:286`](../../packages/ui/commands/src/index.ts)
 
 ## `ctx.compact` — `CompactService` (abstract seam)
 
diff --git a/docs/core-data-structures/commands.i18n.yaml b/docs/core-data-structures/commands.i18n.yaml
index ba55abec39..8053c11f1f 100644
--- a/docs/core-data-structures/commands.i18n.yaml
+++ b/docs/core-data-structures/commands.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
-commands.md: 056c775f4c2e1586447db11821e5c7d56be01881
-commands.zh.md: 1a51305df356d8becf8c5517704dc375cdb8b585
+#   pnpm run verify-translation-pairing --write docs/core-data-structures/commands.md
+commands.md: bc7cf676232a4271d7bc21d6688bc598d9325957
+commands.zh.md: f90e7c93c41699e8c05f5a4b709a75acc846c460
diff --git a/docs/core-data-structures/commands.md b/docs/core-data-structures/commands.md
index 056c775f4c..bc7cf67623 100644
--- a/docs/core-data-structures/commands.md
+++ b/docs/core-data-structures/commands.md
@@ -31,6 +31,12 @@ interface CommandDefinition {
   readonly description: string
   /** Optional free-form input hint advertised to capable clients. */
   readonly input?: CommandInputDescriptor
+  /**
+   * Whether `command/run` records `rawInput`. Defaults to true. A command
+   * whose domain event owns the payload sets this false to avoid duplicating
+   * that payload in the session log.
+   */
+  readonly recordInput?: boolean
   /** Execute against the receiving agent without sending the command to the model. */
   readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>
 }
diff --git a/docs/core-data-structures/commands.zh.md b/docs/core-data-structures/commands.zh.md
index 1a51305df3..f90e7c93c4 100644
--- a/docs/core-data-structures/commands.zh.md
+++ b/docs/core-data-structures/commands.zh.md
@@ -31,6 +31,12 @@ interface CommandDefinition {
   readonly description: string
   /** Optional free-form input hint advertised to capable clients. */
   readonly input?: CommandInputDescriptor
+  /**
+   * Whether `command/run` records `rawInput`. Defaults to true. A command
+   * whose domain event owns the payload sets this false to avoid duplicating
+   * that payload in the session log.
+   */
+  readonly recordInput?: boolean
   /** Execute against the receiving agent without sending the command to the model. */
   readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>
 }
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 9d66b52bfb..a169747843 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -24,7 +24,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/step` | `serial` | [`packages/core/agent/src/types.ts:326`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`plan-mode`](../packages/plan/plan-mode), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`time-context`](../packages/context/time-context), [`tool-skill`](../packages/skill/tool-skill), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:373`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:30`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp) |
-| `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:154`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy`, [`tui`](../packages/ui/tui) |
+| `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:161`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy`, [`tui`](../packages/ui/tui) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:62`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 7c027afd68..7c4dd1010b 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -185,7 +185,7 @@ Source: [`packages/core/session/src/types.ts:219`](../packages/core/session/src/
 'command/done': { commandId: CommandId; kind: 'success' | 'error'; text?: string }
 ```
 
-Source: [`packages/ui/commands/src/index.ts:138`](../packages/ui/commands/src/index.ts)
+Source: [`packages/ui/commands/src/index.ts:145`](../packages/ui/commands/src/index.ts)
 
 #### `command/run` — log-only
 
@@ -197,12 +197,13 @@ Source: [`packages/ui/commands/src/index.ts:138`](../packages/ui/commands/src/in
  * and `args` are `parseCommand`'s own split (name and verbatim rawInput,
  * separator whitespace included), so a consumer (a projection unit
  * folding its own command records, a rich command card) never re-parses
- * a line.
+ * a line. `args` is absent when the definition sets `recordInput: false`
+ * because an authoritative domain event owns the input payload.
  */
-'command/run': { commandId: CommandId; name: string; args: string; source: CommandSource }
+'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-Source: [`packages/ui/commands/src/index.ts:132`](../packages/ui/commands/src/index.ts)
+Source: [`packages/ui/commands/src/index.ts:139`](../packages/ui/commands/src/index.ts)
 
 ### `compact/*`
 
@@ -256,6 +257,20 @@ Types: [ContentBlock](core-data-structures/core.md)
 
 Source: [`packages/compact/compact/src/types.ts:22`](../packages/compact/compact/src/types.ts)
 
+### `feedback/*`
+
+#### `feedback/record` — log-only
+
+```ts persistence-catalog
+/**
+ * One recorded human remark about this session. Log-only and independent
+ * of its trigger; it never enters the model surface or derived history.
+ */
+'feedback/record': { text: string }
+```
+
+Source: [`packages/feedback/command-feedback/src/index.ts:24`](../packages/feedback/command-feedback/src/index.ts)
+
 ### `hook/*`
 
 #### `hook/invoked` — log-only
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index be9ba79347..5d5e34bf31 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -304,9 +304,9 @@ function viewFor(event: SessionEvent, log: readonly SessionEvent[]): ToolEventVi
 
 /**
  * Fixture parallel of the plan unit's double-event fold: `command/run`
- * records named `plan` set the wanted target (`off` → false, else true);
- * `plan/mode` commits and clears it. `wanted` is exposed for the prompt
- * boundary (the fixture's agent/step parallel).
+ * records named `plan` with recorded input set the wanted target (`off` →
+ * false, else true); `plan/mode` commits and clears it. `wanted` is exposed
+ * for the prompt boundary (the fixture's agent/step parallel).
  */
 function foldPlan(log: readonly SessionEvent[]): { active: boolean; pending: boolean; wanted: boolean | null } {
   let active = false
@@ -315,7 +315,8 @@ function foldPlan(log: readonly SessionEvent[]): { active: boolean; pending: boo
     const item = event as unknown as { type: string; data?: Record<string, unknown> }
     if (item.type === 'command/run' && item.data?.['name'] === 'plan') {
       const args = item.data['args']
-      wanted = (typeof args === 'string' ? args : '').trim() !== 'off'
+      if (typeof args !== 'string') continue
+      wanted = args.trim() !== 'off'
     } else if (item.type === 'plan/mode') {
       active = item.data?.['active'] === true
       wanted = null
@@ -374,8 +375,9 @@ function projectionFramesOf(id: SessionId, log: readonly SessionEvent[], event:
     }]
   }
   // The plan unit advances on its two folded event kinds.
+  const commandData = event as unknown as { data: { name?: string; args?: unknown } }
   if (type === 'plan/mode' || (type === 'command/run'
-    && (event as unknown as { data: { name?: string } }).data.name === 'plan')) {
+    && commandData.data.name === 'plan' && typeof commandData.data.args === 'string')) {
     return [{
       type: 'session/projection',
       sessionId: id,
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index f5f0717236..474f7cc8b3 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -140,7 +140,10 @@ export interface CommandNode {
   commandId: CommandId
   /** Command name (run payload's structured field); null when the run fell outside the window. */
   name: string | null
-  /** Verbatim rawInput after the name, separator whitespace included (run payload); null when the run fell outside the window. */
+  /**
+   * Verbatim rawInput after the name, including separator whitespace; null
+   * when omitted by the command or when the run fell outside the window.
+   */
   args: string | null
   /** Settlement outcome (done payload); null while the command is still executing. */
   outcome: { kind: 'success' | 'error'; text?: string } | null
diff --git a/packages/client/runtime/src/client/sessions/fold-adapter.ts b/packages/client/runtime/src/client/sessions/fold-adapter.ts
index 039c36056b..c884d2ec8e 100644
--- a/packages/client/runtime/src/client/sessions/fold-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/fold-adapter.ts
@@ -234,10 +234,10 @@ export class FoldAdapter {
     // enter the client program, so this wire consumer narrows structurally
     // (the same posture as tool/code-dispatch in session.ts).
     if ((event.type as string) === 'command/run') {
-      const data = event.data as unknown as { commandId: CommandId; name: string; args: string }
+      const data = event.data as unknown as { commandId: CommandId; name: string; args?: string }
       this.commandIdx.set(data.commandId, {
         kind: 'command', seq: event.seq, time: event.time,
-        commandId: data.commandId, name: data.name, args: data.args, outcome: null,
+        commandId: data.commandId, name: data.name, args: data.args ?? null, outcome: null,
       })
       return
     }
diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts
index 53f80e0e69..7da9bf0184 100644
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -67,6 +67,8 @@ export const ev = {
     at(seq, { type: 'turn/end', data: { turn, reason: { kind: reason } } }),
   commandRun: (seq: number, commandId: string, name: string, args = ''): SessionEvent =>
     at(seq, { type: 'command/run', data: { commandId, name, args, source: { kind: 'user' } } }),
+  commandRunWithoutInput: (seq: number, commandId: string, name: string): SessionEvent =>
+    at(seq, { type: 'command/run', data: { commandId, name, source: { kind: 'user' } } }),
   commandDone: (seq: number, commandId: string, kind: 'success' | 'error' = 'success', text?: string): SessionEvent =>
     at(seq, { type: 'command/done', data: { commandId, kind, ...text === undefined ? {} : { text } } }),
 }
diff --git a/packages/client/runtime/tests/fold-adapter.spec.ts b/packages/client/runtime/tests/fold-adapter.spec.ts
index b40bdb4111..0b14fda5c3 100644
--- a/packages/client/runtime/tests/fold-adapter.spec.ts
+++ b/packages/client/runtime/tests/fold-adapter.spec.ts
@@ -195,6 +195,14 @@ describe('FoldAdapter', () => {
       })
     })
 
+    it('represents command input omitted by the host as null', () => {
+      const adapter = new FoldAdapter()
+      adapter.reset([ev.commandRunWithoutInput(0, 'cmd-private', 'feedback')], 0)
+      expect(adapter.nodes().nodes[0]).toMatchObject({
+        kind: 'command', name: 'feedback', args: null, outcome: null,
+      })
+    })
+
     it('soft-falls a done-only window into a node built from the done (cross-window cut)', () => {
       const adapter = new FoldAdapter()
       adapter.reset([ev.commandDone(80, 'cmd-3', 'error', '失败了')], 80)
diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index 1dfea5488b..1d6db2581d 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -21,8 +21,8 @@ export function GenericCommandCard({ node }: CommandRowOwnerProps) {
     ? '执行中…'
     : text ?? (node.outcome.kind === 'error' ? '命令失败' : '已完成')
   // Display line rebuilt from the structured payload (args carries its own
-  // separator whitespace verbatim); a cross-window node whose run page fell
-  // out of the window has neither.
+  // separator whitespace verbatim); omitted input and a cross-window node
+  // whose run page fell out both render without it.
   const title = node.name === null ? '命令' : `/${node.name}${node.args ?? ''}`
   return (
     <ToolRow
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 629653d459..006dfed9f0 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -1585,7 +1585,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'CommandDefinition',
-    declaration: 'export interface CommandDefinition {\n    readonly name: string;\n    readonly description: string;\n    readonly input?: CommandInputDescriptor;\n    readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>;\n}',
+    declaration: 'export interface CommandDefinition {\n    readonly name: string;\n    readonly description: string;\n    readonly input?: CommandInputDescriptor;\n    readonly recordInput?: boolean;\n    readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>;\n}',
   },
   {
     name: 'CommandDescriptor',
diff --git a/packages/feedback/README.i18n.yaml b/packages/feedback/README.i18n.yaml
index eca3b1c420..31ed2d25e8 100644
--- a/packages/feedback/README.i18n.yaml
+++ b/packages/feedback/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/feedback/README.md
-README.md: ab7bc6f3e3a3be0c280855ff80e92c7d7a7e665e
-README.zh.md: 9c050ac42aa468895c04124a76a3bce58756df0e
+README.md: 7962a16ee9bc7d8a969a466591d761829cd55d7f
+README.zh.md: aad8f4d797ff16a5ef9be4c968fb28d708bad13e
diff --git a/packages/feedback/README.md b/packages/feedback/README.md
index ab7bc6f3e3..7962a16ee9 100644
--- a/packages/feedback/README.md
+++ b/packages/feedback/README.md
@@ -6,6 +6,6 @@ The feedback family lets a human record a remark about the session without actin
 
 | Package | Role | ctx key |
 |---|---|---|
-| `command-feedback/` | Human-facing `/feedback` command recorded through the command plane | — |
+| `command-feedback/` | Trigger-independent `feedback/record` event plus the human-facing `/feedback` producer | — |
 
-A recorded remark is log-only: it never enters the model surface or derived history, and no shipped plugin consumes it. A future consumer reads the command records from the session log rather than changing how they are captured.
+A recorded remark is log-only: it never enters the model surface or derived history, and no shipped plugin consumes it. A future consumer reads `feedback/record` events from the session log rather than changing how they are captured.
diff --git a/packages/feedback/README.zh.md b/packages/feedback/README.zh.md
index 9c050ac42a..aad8f4d797 100644
--- a/packages/feedback/README.zh.md
+++ b/packages/feedback/README.zh.md
@@ -6,6 +6,6 @@ feedback 家族让人类记录对会话的评价，但不据此采取任何动
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
-| `command-feedback/` | 面向用户的 `/feedback` 命令，通过命令平面完成记录 | 无 |
+| `command-feedback/` | 与触发方式无关的 `feedback/record` 事件，以及面向用户的 `/feedback` 生产方 | 无 |
 
-被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史，随附插件也不会消费它。未来的消费方从会话日志中读取命令记录，而不是改变它们的采集方式。
+被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史，随附插件也不会消费它。未来的消费方从会话日志中读取 `feedback/record` 事件，而不是改变它们的采集方式。
diff --git a/packages/feedback/command-feedback/README.i18n.yaml b/packages/feedback/command-feedback/README.i18n.yaml
index 37f10ac485..47c169ec3f 100644
--- a/packages/feedback/command-feedback/README.i18n.yaml
+++ b/packages/feedback/command-feedback/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/feedback/command-feedback/README.md
-README.md: 90992b7295536a9099766910f616e640d4b4bcfe
-README.zh.md: a7c4f03997cea182ed24dcfc7f309dc3bd872d5e
+README.md: c9650d6a2c595550545b3dbf07f62e6aa65f39b9
+README.zh.md: ba24276ba1bd71a4eb68c7fdb48a3760bdbec8fc
diff --git a/packages/feedback/command-feedback/README.md b/packages/feedback/command-feedback/README.md
index 90992b7295..c9650d6a2c 100644
--- a/packages/feedback/command-feedback/README.md
+++ b/packages/feedback/command-feedback/README.md
@@ -2,24 +2,24 @@
 
 English | [中文](README.zh.md)
 
-Human-facing `/feedback` capture. The plugin registers one global command through [`ctx.commands`](../../ui/commands/README.md), so every composed command adapter discovers it; the shipped TUI executes it without a model turn.
+Trigger-independent session feedback plus human-facing `/feedback` capture. The package exports `recordFeedback(session, text)`, which appends one log-only `feedback/record` event. Its plugin registers one global command through [`ctx.commands`](../../ui/commands/README.md), so every composed command adapter discovers it; the shipped TUI executes it without a model turn.
 
 ## Command contract
 
 | Input | Result |
 |---|---|
-| `/feedback <text>` | Acknowledge with `Feedback recorded.` The registry's `command/run` record carries the verbatim text. |
+| `/feedback <text>` | Append `feedback/record` and acknowledge with `Feedback recorded.` |
 | `/feedback` | Return a direct usage error. Whitespace-only input is treated as empty. |
 
-Feedback text is never parsed: no truncation, case folding, or control words. Text that looks like another command, such as `/feedback /plan felt slow`, is feedback content. Repeated commands each produce their own record; nothing is replaced or merged.
+Surrounding whitespace is discarded, but feedback is otherwise unparsed: no truncation, case folding, or control words. Text that looks like another command, such as `/feedback /plan felt slow`, is feedback content. Repeated commands each produce their own event; nothing is replaced or merged.
 
 ## What this plugin does and does not do
 
-The command records a remark and does nothing else. It appends no session event of its own, starts no model work, and no plugin in this repository reads its records.
+`recordFeedback(session, text)` is the command-independent write path. It rejects empty normalized text and appends `feedback/record { text }`; a different UI, hook, or host integration can call it without constructing a slash command. The `/feedback` handler uses that producer, starts no model work, and no plugin in this repository reads the event.
 
-The record is the command registry's own `command/run` / `command/done` pairing, which [`dsh-commands`](../../ui/commands/README.md) appends for every dispatched command. Those appends start persistence's ordinary eager drain; neither the registry nor this command forces a `session/flush`, so the acknowledgement means the entry is in the log, not that it has already reached disk. `command/run` carries the command name, the verbatim unparsed suffix, and the invocation source; the paired `command/done` carries the outcome. Both are log-only and are absent from the ordered surface, from `deriveMessages()`, and from every model request. A rejected empty input still leaves that pairing, settled as `kind: 'error'`, so no entry can be mistaken for accepted feedback.
+The feedback text appears in exactly one durable payload: `feedback/record`. [`dsh-commands`](../../ui/commands/README.md) still appends its generic `command/run` / `command/done` pairing, but this definition sets `recordInput: false`, so `command/run` omits `args`; the paired `command/done` carries only the outcome. All three events are log-only and absent from the ordered surface, `deriveMessages()`, and model requests. These appends start persistence's ordinary eager drain, but neither producer forces `session/flush`, so acknowledgement means the feedback is in the log, not that it has reached disk. Rejected empty input leaves only the command pairing settled as `kind: 'error'`, with no `feedback/record`.
 
-A dedicated `session/feedback` event was considered and rejected: it would duplicate a record the registry already writes, and a consumer can select feedback by the command name it already stores.
+The event is authoritative rather than the command record because feedback may arrive through a trigger other than `/feedback`. Keeping the payload out of `command/run` avoids two records carrying the same text.
 
 ## Composition
 
@@ -40,7 +40,7 @@ The TUI app mounts this command unconditionally; it has no configuration and no
 
 #### What the model sees
 
-Nothing. The slash input, the recorded text, and the acknowledgement are all absent from model requests. The registry's `command/run` and `command/done` records are log-only and carry no `surfaceOp`, so they never reach the ordered surface, `deriveMessages()`, or a system prompt. Recording feedback during a turn does not change that turn's remaining requests.
+Nothing. The slash input, `feedback/record`, and the acknowledgement are absent from model requests. The feedback event and registry lifecycle records are log-only and carry no `surfaceOp`, so they never reach the ordered surface, `deriveMessages()`, or a system prompt. Recording feedback during a turn does not change that turn's remaining requests.
 
 #### Token effect
 
@@ -52,9 +52,8 @@ Independent of the model request path. Recording appends to the session log only
 
 ## Known Limitations and Deferred Work
 
-- **Nothing consumes the recorded feedback** — capture is deliberately inert. There is no retrieval, aggregation, export, or reporting surface, and no model-facing tool reads it; a consumer is a separate package that selects `command/run` records by command name.
+- **Nothing consumes the recorded feedback** — capture is deliberately inert. There is no retrieval, aggregation, export, or reporting surface, and no model-facing tool reads `feedback/record`; a consumer is a separate package.
 - **No structured fields** — an entry is one free-text string with no category, severity, or referenced-event link, so feedback cannot be filtered by subject without re-reading its text.
 - **No amend or withdraw** — the session log is append-only and this package adds no tombstone, so a mistaken entry stays recorded and can only be superseded by a later one.
-- **Untrimmed text in the record** — the handler trims only to validate; `command/run` stores the raw suffix, including its leading separator whitespace, so a consumer trims at read time.
 - **No explicit durability barrier** — the acknowledgement follows the append, not a flush, so an entry recorded immediately before a crash can be lost with any other unflushed tail. Feedback is not worth forcing a synchronous disk write for; a consumer that needs one awaits `ctx.sessions.flush(session)`.
 - **TUI only in the shipped apps** — the headless CLI, ACP automation, and JSON-RPC adapters do not mount `ctx.commands`, so `/feedback` is unavailable there.
diff --git a/packages/feedback/command-feedback/README.zh.md b/packages/feedback/command-feedback/README.zh.md
index a7c4f03997..ba24276ba1 100644
--- a/packages/feedback/command-feedback/README.zh.md
+++ b/packages/feedback/command-feedback/README.zh.md
@@ -2,24 +2,24 @@
 
 [English](README.md) | 中文
 
-面向用户的 `/feedback` 采集。该插件通过 [`ctx.commands`](../../ui/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附 TUI 无需模型轮次即可执行。
+与触发方式无关的会话反馈，以及面向用户的 `/feedback` 采集。本包（package）导出 `recordFeedback(session, text)`，后者追加一个仅写入日志的 `feedback/record` 事件。该插件通过 [`ctx.commands`](../../ui/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附 TUI 无需模型轮次即可执行。
 
 ## 命令契约
 
 | 输入 | 结果 |
 |---|---|
-| `/feedback <text>` | 以 `Feedback recorded.` 确认。注册表的 `command/run` 记录携带原样文本。 |
+| `/feedback <text>` | 追加 `feedback/record`，并以 `Feedback recorded.` 确认。 |
 | `/feedback` | 返回一个直接用法错误。仅含空白的输入视为空输入。 |
 
-反馈文本从不被解析：没有截断、大小写折叠或控制词。看起来像另一个命令的文本（例如 `/feedback /plan felt slow`）就是反馈内容。重复执行命令会各自产生自己的记录，不会替换或合并。
+前后空白会被丢弃，但除此之外，反馈内容不会被解析：没有截断、大小写折叠或控制词。看起来像另一个命令的文本（例如 `/feedback /plan felt slow`）就是反馈内容。重复执行命令时，每次都会产生一个事件；不会发生替换或合并。
 
 ## 本插件做什么、不做什么
 
-该命令记录一条评价，不做别的事。它不追加属于自己的会话事件，不启动任何模型工作，本仓库中也没有任何插件读取它的记录。
+`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，不启动任何模型工作；本仓库中也没有任何插件读取该事件。
 
-记录来自命令注册表自身的 `command/run` / `command/done` 配对，由 [`dsh-commands`](../../ui/commands/README.md) 为每个已分发命令追加。这些追加会启动持久化的常规即时排空；注册表与本命令都不会强制 `session/flush`，因此确认文本表示条目已进入日志，而不表示它已经落盘。`command/run` 携带命令名、原样未解析的后缀以及调用来源；配对的 `command/done` 携带结果。两者都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及任何模型请求中。被拒绝的空输入仍会留下该配对，并以 `kind: 'error'` 结算，因此任何条目都不会被误认为已接受的反馈。
+反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../ui/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
 
-曾考虑并否决了专用的 `session/feedback` 事件：它会重复注册表已经写入的记录，而消费方可以依据注册表已存储的命令名筛选反馈。
+权威记录是该事件，而不是命令记录，因为反馈可能来自 `/feedback` 之外的触发方式。让载荷不进入 `command/run`，可避免两条记录携带相同文本。
 
 ## 组合
 
@@ -40,7 +40,7 @@ TUI 应用无条件挂载此命令；它没有配置，也不依赖持久 goal 
 
 #### 模型看到的内容
 
-无。斜杠输入、被记录的文本以及确认文本都不出现在模型请求中。注册表的 `command/run` 与 `command/done` 记录仅写入日志且不携带 `surfaceOp`，因此它们绝不会进入有序 surface、`deriveMessages()` 或系统提示词。在某个轮次中记录反馈不会改变该轮次剩余的请求。
+无。斜杠输入、`feedback/record` 以及确认文本都不出现在模型请求中。反馈事件和注册表生命周期记录仅写入日志且不携带 `surfaceOp`，因此它们绝不会进入有序 surface、`deriveMessages()` 或系统提示词。在某个轮次中记录反馈不会改变该轮次剩余的请求。
 
 #### Token 影响
 
@@ -52,9 +52,8 @@ TUI 应用无条件挂载此命令；它没有配置，也不依赖持久 goal 
 
 ## 已知限制与暂缓工作
 
-- **没有任何消费方读取被记录的反馈**：采集刻意不产生任何后续动作。这里没有检索、聚合、导出或报告 surface，也没有面向模型的工具读取它；消费方是另一个依据命令名筛选 `command/run` 记录的独立包。
+- **没有任何消费方读取被记录的反馈**：采集刻意不产生任何后续动作。这里没有检索、聚合、导出或报告 surface，也没有面向模型的工具读取 `feedback/record`；消费方是另一个独立包。
 - **没有结构化字段**：一条条目就是一个自由文本字符串，没有类别、严重程度或关联事件链接，因此无法在不重读文本的情况下按主题过滤反馈。
 - **不支持修改或撤回**：会话日志是仅追加的，本包也不新增 tombstone，因此错误的条目会一直保留在记录中，只能由后续条目取代。
-- **记录中的文本未修剪**：处理器只为校验而修剪；`command/run` 存储原始后缀，包含其前导分隔空白，因此消费方需在读取时修剪。
 - **没有显式持久化屏障**：确认文本紧随追加而非 flush，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。为反馈强制同步写盘并不值得；需要该保证的消费方可自行等待 `ctx.sessions.flush(session)`。
 - **随附应用中只有 TUI 使用此命令**：无头 CLI、ACP 自动化和 JSON-RPC 适配器不挂载 `ctx.commands`，因此 `/feedback` 在那里不可用。
diff --git a/packages/feedback/command-feedback/package.json b/packages/feedback/command-feedback/package.json
index 6ad91d0e0d..25bc8446c3 100644
--- a/packages/feedback/command-feedback/package.json
+++ b/packages/feedback/command-feedback/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-command-feedback",
-  "description": "Human-facing slash command that records session feedback as a log-only event",
+  "description": "Log-only session feedback producer and human-facing slash command",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -29,6 +29,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-commands": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
diff --git a/packages/feedback/command-feedback/src/index.ts b/packages/feedback/command-feedback/src/index.ts
index 7bf7cd0853..ae78b3cd4f 100644
--- a/packages/feedback/command-feedback/src/index.ts
+++ b/packages/feedback/command-feedback/src/index.ts
@@ -1,24 +1,45 @@
 /**
- * Human-facing `/feedback` command. It records a remark about the session and
- * does nothing else: the command registry's own `command/run` and
- * `command/done` events are the whole record, so this plugin only validates the
- * input and acknowledges it. Those appends are eager but unflushed, so the
- * acknowledgement reports the entry is logged, not that it reached disk.
+ * Session feedback event plus the human-facing `/feedback` producer. Recording
+ * appends one authoritative log-only event and does not start model work. The
+ * append is eager but unflushed, so acknowledgement reports that the entry is
+ * logged, not that it reached disk.
  * @module @deepseek-ai/dsh-command-feedback
  */
 
 import type { Context } from 'cordis'
 import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands'
+import type { Session } from '@deepseek-ai/dsh-session'
 
 export const name = 'command-feedback'
 export const inject = ['commands']
 
 const USAGE = 'Usage: /feedback <text>'
 
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    /**
+     * One recorded human remark about this session. Log-only and independent
+     * of its trigger; it never enters the model surface or derived history.
+     */
+    'feedback/record': { text: string }
+  }
+}
+
 /**
- * Validate and acknowledge one feedback entry. `command/run` already carries
- * the verbatim text, so no further append is needed; returning an error instead
- * settles that record as `kind: 'error'` and leaves no accepted feedback.
+ * Record feedback independently of any UI trigger.
+ * @param session - session the feedback describes.
+ * @param text - human-authored feedback; surrounding whitespace is discarded.
+ * @throws {TypeError} when the normalized text is empty.
+ */
+export function recordFeedback(session: Session, text: string): void {
+  const normalized = text.trim()
+  if (normalized.length === 0) throw new TypeError('feedback text must not be empty')
+  session.append('feedback/record', { text: normalized })
+}
+
+/**
+ * Validate, record, and acknowledge one feedback entry. Returning an error
+ * leaves no `feedback/record` event.
  * @param invocation - receiving agent, raw command input, and UI cancellation.
  * @returns an acknowledgement, or a usage error when no feedback text was supplied.
  */
@@ -26,6 +47,7 @@ function executeFeedbackCommand(invocation: CommandInvocation): CommandResult {
   if (invocation.rawInput.trim().length === 0) {
     return { kind: 'error', text: `Feedback text is required. ${USAGE}` }
   }
+  recordFeedback(invocation.agent.session, invocation.rawInput)
   return { kind: 'success', text: 'Feedback recorded.' }
 }
 
@@ -35,6 +57,7 @@ export function apply(ctx: Context): void {
     name: 'feedback',
     description: 'record feedback about this session',
     input: { hint: '<text>' },
+    recordInput: false,
     handler: executeFeedbackCommand,
   })
 }
diff --git a/packages/feedback/command-feedback/src/invariant.ts b/packages/feedback/command-feedback/src/invariant.ts
index 72a3ead213..9c825a6e87 100644
--- a/packages/feedback/command-feedback/src/invariant.ts
+++ b/packages/feedback/command-feedback/src/invariant.ts
@@ -15,8 +15,8 @@ export const name = 'command-feedback-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: this command declares no session event and owns no state projection. The
- * `command/run`/`command/done` pairing that records feedback belongs to `dsh-commands`.
+ * No runtime invariant: each `feedback/record` is an independent append-only
+ * fact with no cross-event or mutable-data relationship.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/feedback/command-feedback/tests/command-feedback.spec.ts b/packages/feedback/command-feedback/tests/command-feedback.spec.ts
index 362bb8ce30..853e967176 100644
--- a/packages/feedback/command-feedback/tests/command-feedback.spec.ts
+++ b/packages/feedback/command-feedback/tests/command-feedback.spec.ts
@@ -58,15 +58,11 @@ async function run(test: Harness, suffix = ''): Promise<{ kind: string; text?: s
   return settled.result
 }
 
-/** The registry's durable record of each accepted command, in log order. */
-function commandRecords(session: Session): { name: string; args: string; kind: string }[] {
-  const runs = session.events.filter(event => event.type === 'command/run')
-  return runs.map((event) => {
-    const done = session.events.find(item =>
-      item.type === 'command/done' && item.data.commandId === event.data.commandId)
-    if (done?.type !== 'command/done') throw new Error('every command/run must be paired')
-    return { name: event.data.name, args: event.data.args, kind: done.data.kind }
-  })
+/** Authoritative feedback payloads in log order. */
+function feedbackTexts(session: Session): string[] {
+  return session.events
+    .filter(event => event.type === 'feedback/record')
+    .map(event => event.data.text)
 }
 
 describe('@deepseek-ai/dsh-command-feedback registration', () => {
@@ -83,7 +79,7 @@ describe('@deepseek-ai/dsh-command-feedback registration', () => {
       description: 'record feedback about this session',
       input: { hint: '<text>' },
     })
-    expect(test.ctx.commands.find(test.agent, 'feedback')).toBeDefined()
+    expect(test.ctx.commands.find(test.agent, 'feedback')).toMatchObject({ recordInput: false })
 
     await test.plugin.dispose()
     expect(test.ctx.commands.find(test.agent, 'feedback')).toBeUndefined()
@@ -91,38 +87,47 @@ describe('@deepseek-ai/dsh-command-feedback registration', () => {
 })
 
 describe('/feedback human command', () => {
-  it('acknowledges feedback and leaves the registry record as its durable trace', async () => {
+  it('acknowledges feedback and records its payload exactly once in the domain event', async () => {
     const test = await harness()
     await expect(run(test, ' the diff view is unreadable')).resolves.toEqual({
       kind: 'success',
       text: 'Feedback recorded.',
     })
-    expect(commandRecords(test.session)).toEqual([
-      { name: 'feedback', args: ' the diff view is unreadable', kind: 'success' },
-    ])
+    expect(feedbackTexts(test.session)).toEqual(['the diff view is unreadable'])
+    const commandRun = test.session.events.find(event => event.type === 'command/run')
+    expect(commandRun?.type === 'command/run' && Object.hasOwn(commandRun.data, 'args')).toBe(false)
+    expect(JSON.stringify(test.session.events).match(/the diff view is unreadable/gu)).toHaveLength(1)
   })
 
-  it('adds no event of its own beyond the registry pairing', async () => {
+  it('exports a command-independent feedback producer', async () => {
+    const test = await harness()
+    commandFeedback.recordFeedback(test.session, '  recorded outside a command  ')
+    expect(test.session.events.map(event => event.type)).toEqual(['feedback/record'])
+    expect(feedbackTexts(test.session)).toEqual(['recorded outside a command'])
+    expect(() => { commandFeedback.recordFeedback(test.session, ' \n\t ') })
+      .toThrow('feedback text must not be empty')
+    expect(feedbackTexts(test.session)).toEqual(['recorded outside a command'])
+  })
+
+  it('keeps command bookkeeping around the authoritative feedback event', async () => {
     const test = await harness()
     await run(test, ' nothing else happens')
-    // The whole point of the command: record and do nothing. Only the
-    // registry's own pairing appears, and no turn of model work starts.
-    expect(test.session.events.map(event => event.type)).toEqual(['command/run', 'command/done'])
+    expect(test.session.events.map(event => event.type)).toEqual([
+      'command/run', 'feedback/record', 'command/done',
+    ])
   })
 
-  it('records verbatim text, including input that looks like another command', async () => {
+  it('normalizes surrounding whitespace without parsing command-like content', async () => {
     const test = await harness()
     await run(test, ' /plan felt SLOW\n\ttwice today ')
-    expect(commandRecords(test.session)).toEqual([
-      { name: 'feedback', args: ' /plan felt SLOW\n\ttwice today ', kind: 'success' },
-    ])
+    expect(feedbackTexts(test.session)).toEqual(['/plan felt SLOW\n\ttwice today'])
   })
 
   it('records each entry separately without replacing earlier ones', async () => {
     const test = await harness()
     await run(test, ' first')
     await run(test, ' second')
-    expect(commandRecords(test.session).map(record => record.args)).toEqual([' first', ' second'])
+    expect(feedbackTexts(test.session)).toEqual(['first', 'second'])
   })
 
   it('records concurrent submissions in dispatch order', async () => {
@@ -137,7 +142,7 @@ describe('/feedback human command', () => {
       { kind: 'success', text: 'Feedback recorded.' },
       { kind: 'success', text: 'Feedback recorded.' },
     ])
-    expect(commandRecords(test.session).map(record => record.args)).toEqual([' first', ' second'])
+    expect(feedbackTexts(test.session)).toEqual(['first', 'second'])
   })
 
   it('keeps every recorded event off the model surface and out of derived history', async () => {
@@ -160,9 +165,12 @@ describe('/feedback human command', () => {
     }
     await expect(run(test)).resolves.toEqual(expected)
     await expect(run(test, '   \n\t ')).resolves.toEqual(expected)
-    // Rejected input still leaves the registry's own pairing, settled as an
-    // error, so no entry is mistaken for accepted feedback.
-    expect(commandRecords(test.session).map(record => record.kind)).toEqual(['error', 'error'])
+    expect(feedbackTexts(test.session)).toEqual([])
+    const done = test.session.events.filter(event => event.type === 'command/done')
+    expect(done.map(event => event.data.kind)).toEqual(['error', 'error'])
+    for (const event of test.session.events) {
+      if (event.type === 'command/run') expect(Object.hasOwn(event.data, 'args')).toBe(false)
+    }
   })
 
   it('records nothing when dispatch rejects an already-cancelled request', async () => {
diff --git a/packages/feedback/command-feedback/tests/loader-composition.spec.ts b/packages/feedback/command-feedback/tests/loader-composition.spec.ts
index 9aa206f9ad..dbb175d304 100644
--- a/packages/feedback/command-feedback/tests/loader-composition.spec.ts
+++ b/packages/feedback/command-feedback/tests/loader-composition.spec.ts
@@ -92,11 +92,14 @@ describe('/feedback real Loader composition through cordis.yml', () => {
       text: 'Feedback text is required. Usage: /feedback <text>',
     })
 
-    // The command records itself through the registry and does nothing else.
+    // The domain event owns the payload; generic command bookkeeping omits it.
     expect(owner.session.events.map(event => event.type))
-      .toEqual(['command/run', 'command/done', 'command/run', 'command/done'])
+      .toEqual(['command/run', 'feedback/record', 'command/done', 'command/run', 'command/done'])
     const run = owner.session.events.find(event => event.type === 'command/run')
-    expect(run?.type === 'command/run' && run.data.args).toBe(' the diff view is unreadable')
+    expect(run?.type === 'command/run' && Object.hasOwn(run.data, 'args')).toBe(false)
+    const feedback = owner.session.events.find(event => event.type === 'feedback/record')
+    expect(feedback?.type === 'feedback/record' && feedback.data.text).toBe('the diff view is unreadable')
+    expect(JSON.stringify(owner.session.events).match(/the diff view is unreadable/gu)).toHaveLength(1)
 
     // Nothing reached the model.
     expect(owner.session.deriveMessages()).toEqual([])
diff --git a/packages/feedback/command-feedback/tsconfig.json b/packages/feedback/command-feedback/tsconfig.json
index 6a27b54d3a..0a99f13f01 100644
--- a/packages/feedback/command-feedback/tsconfig.json
+++ b/packages/feedback/command-feedback/tsconfig.json
@@ -17,6 +17,9 @@
     {
       "path": "../../ui/commands"
     },
+    {
+      "path": "../../core/session"
+    },
     {
       "path": "../../support/invariants"
     }
diff --git a/packages/plan/plan-mode/README.i18n.yaml b/packages/plan/plan-mode/README.i18n.yaml
index c5a13bee7e..791f77b637 100644
--- a/packages/plan/plan-mode/README.i18n.yaml
+++ b/packages/plan/plan-mode/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/plan/plan-mode/README.md
-README.md: d3c2c14fe616e1c9b4e33b716570b084db6474cf
-README.zh.md: 6d6878c4b0300a716ad16be60fd86bc79f1514ba
+README.md: e3a98115d2d9f14fa0bb46e4d867f6b79cbf269d
+README.zh.md: f8481cff12992e83af39498908c5ca2624a4f974
diff --git a/packages/plan/plan-mode/README.md b/packages/plan/plan-mode/README.md
index d3c2c14fe6..e3a98115d2 100644
--- a/packages/plan/plan-mode/README.md
+++ b/packages/plan/plan-mode/README.md
@@ -20,7 +20,7 @@ The TUI consumes the plugin-owned `/plan` command; other front doors may drive t
 
 ## Session projection
 
-When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)), this package registers the `plan` projection unit under an injected child. The unit folds two event kinds: a `command/run` record named `plan` sets the wanted target (`off` → inactive, anything else → active), and `plan/mode` commits the logged state and clears it; every other event returns the same state reference. `view` derives `{ active, pending }`, where `pending` is true only while an outstanding selection differs from the logged state — a pure replay quantity, so host restarts, other tabs, and cold reads all recover it from the log alone (the `/plan` handler calls `set()` before any failing path, keeping the logged request and the run plane from forking). The key merges into `SessionProjectionMap` from `src/types.ts` (served to host consumers via `./types` and client aggregates via `./client`); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected.
+When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)), this package registers the `plan` projection unit under an injected child. The unit folds two event kinds: a `command/run` record named `plan` with recorded `args` sets the wanted target (`off` → inactive, anything else → active), and `plan/mode` commits the logged state and clears it; every other event returns the same state reference. `view` derives `{ active, pending }`, where `pending` is true only while an outstanding selection differs from the logged state — a pure replay quantity, so host restarts, other tabs, and cold reads all recover it from the log alone (the `/plan` handler calls `set()` before any failing path, keeping the logged request and the run plane from forking). The key merges into `SessionProjectionMap` from `src/types.ts` (served to host consumers via `./types` and client aggregates via `./client`); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected.
 
 ## Configuration
 
diff --git a/packages/plan/plan-mode/README.zh.md b/packages/plan/plan-mode/README.zh.md
index 6d6878c4b0..f8481cff12 100644
--- a/packages/plan/plan-mode/README.zh.md
+++ b/packages/plan/plan-mode/README.zh.md
@@ -20,7 +20,7 @@ TUI 消费插件拥有的 `/plan` 命令；其他入口可以直接驱动同一
 
 ## 会话投影
 
-当组合挂载 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)）时，本包在注入子插件下注册 `plan` 投影单元。该单元折叠两种事件：名为 `plan` 的 `command/run` 记录设置目标值（`off` → 未激活，其余 → 激活），`plan/mode` 提交已记录状态并将其清除；其他任何事件返回同一状态引用。`view` 推导 `{ active, pending }`，其中 `pending` 仅在未兑现的选择不同于已记录状态时为 true——它是纯回放量，host 重启、其他标签页与冷读都只凭日志即可恢复（`/plan` 处理器在任何可能失败的路径之前调用 `set()`，使已入日志的请求与运行面不可能分叉）。key 从 `src/types.ts` merge 进 `SessionProjectionMap`（host 消费方经 `./types`、client 聚合经 `./client`）；框架驱动单元，载体在历史尾页与 `session/projection` 推送帧上提供该值。未挂注册表的组合不受影响。
+当组合挂载 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)）时，本包在注入子插件下注册 `plan` 投影单元。该单元折叠两种事件：名为 `plan` 且带有已记录 `args` 的 `command/run` 记录设置目标值（`off` → 未激活，其余 → 激活），`plan/mode` 提交已记录状态并将其清除；其他任何事件返回同一状态引用。`view` 推导 `{ active, pending }`，其中 `pending` 仅在未兑现的选择不同于已记录状态时为 true——它是纯回放量，host 重启、其他标签页与冷读都只凭日志即可恢复（`/plan` 处理器在任何可能失败的路径之前调用 `set()`，使已入日志的请求与运行面不可能分叉）。key 从 `src/types.ts` merge 进 `SessionProjectionMap`（host 消费方经 `./types`、client 聚合经 `./client`）；框架驱动单元，载体在历史尾页与 `session/projection` 推送帧上提供该值。未挂注册表的组合不受影响。
 
 ## 配置
 
diff --git a/packages/plan/plan-mode/src/index.ts b/packages/plan/plan-mode/src/index.ts
index dc6b788825..9d584dc776 100644
--- a/packages/plan/plan-mode/src/index.ts
+++ b/packages/plan/plan-mode/src/index.ts
@@ -234,6 +234,7 @@ export class PlanModeService extends Service {
         init: () => ({ active: false, wanted: null }),
         apply: (state, event) => {
           if (event.type === 'command/run' && event.data.name === 'plan') {
+            if (event.data.args === undefined) return state
             const wanted = event.data.args.trim() !== 'off'
             return wanted === state.wanted ? state : { active: state.active, wanted }
           }
diff --git a/packages/plan/plan-mode/tests/projection.spec.ts b/packages/plan/plan-mode/tests/projection.spec.ts
index 7c69417e58..cb662bc227 100644
--- a/packages/plan/plan-mode/tests/projection.spec.ts
+++ b/packages/plan/plan-mode/tests/projection.spec.ts
@@ -1,9 +1,9 @@
 /**
  * The `plan` projection unit (session-projection RFC's complete example): a
  * double-event fold over the session log. `command/run` records named `plan`
- * set the wanted target (`off` → false, anything else → true); `plan/mode`
- * commits and clears it; `view` derives `{ active, pending }` where pending
- * is true only while an outstanding selection differs from the logged state.
+ * with recorded input set the wanted target (`off` → false, anything else
+ * → true); `plan/mode` commits and clears it. `view` reports pending only
+ * while an outstanding selection differs from the logged state.
  * Pending is thereby a pure replay quantity — a cold fold answers it without
  * the service's in-memory intent. Composition without plan-mode has no `plan`
  * key; unloading the fiber removes it (HMR safety).
@@ -88,6 +88,11 @@ describe('plan projection unit', () => {
       commandId: CommandId('other-1'), name: 'compact', args: '', source: { kind: 'user' },
     })
     expect(bench.values().plan).toEqual({ active: true, pending: false })
+    // A command lifecycle with omitted input carries no plan selection.
+    bench.session.append('command/run', {
+      commandId: CommandId('plan-no-input'), name: 'plan', source: { kind: 'user' },
+    })
+    expect(bench.values().plan).toEqual({ active: true, pending: false })
     runPlanCommand(bench.session, ' off', 1)
     expect(bench.values().plan).toEqual({ active: true, pending: true })
     commitPlanMode(bench.session, false, 1)
diff --git a/packages/ui/commands/README.i18n.yaml b/packages/ui/commands/README.i18n.yaml
index 5c37ccbb16..339c11a248 100644
--- a/packages/ui/commands/README.i18n.yaml
+++ b/packages/ui/commands/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/commands/README.md
-README.md: 4ad72cf9e232c8d41e525f42eecde5637032a391
-README.zh.md: bace8f6346ac737a838d802dfc5c6ffe52c56edd
+README.md: 77397aadf8dd070d962d1a4f95dea2e4700a6c15
+README.zh.md: 8f02325271548b652b069433bcdb9c1c99de547e
diff --git a/packages/ui/commands/README.md b/packages/ui/commands/README.md
index 4ad72cf9e2..77397aadf8 100644
--- a/packages/ui/commands/README.md
+++ b/packages/ui/commands/README.md
@@ -6,9 +6,9 @@ Plugin-owned human-command registry consumed by interactive UI adapters. The [pl
 
 ## Service contract
 
-`ctx.commands.register(definition)` registers one lowercase command name, description, optional unstructured-input hint, and abortable handler. A registered command is available to every composed command adapter; a plugin that is incompatible with a deployment does not register there. A plain-context registration is global. A command-producing plugin mounted beneath `agent.ctx` declares its own `commands` injection and creates an exact agent-scoped definition; it shadows a global definition with the same name. This child-injection shape preserves the agent scope without making the core agent loop depend on a UI service. Duplicate names within one layer fail during registration. Every disposer is the exact Cordis effect disposer, and registration or removal notifies every `commands/change` observer so live adapters can refresh discovery; observer failures are logged and cannot veto the registry mutation or starve later observers.
+`ctx.commands.register(definition)` registers one lowercase command name, description, optional unstructured-input hint, optional `recordInput` policy, and abortable handler. `recordInput` defaults to true; a command whose authoritative domain event owns the payload sets it to false so `command/run` omits `args` instead of duplicating the input. A registered command is available to every composed command adapter; a plugin that is incompatible with a deployment does not register there. A plain-context registration is global. A command-producing plugin mounted beneath `agent.ctx` declares its own `commands` injection and creates an exact agent-scoped definition; it shadows a global definition with the same name. This child-injection shape preserves the agent scope without making the core agent loop depend on a UI service. Duplicate names within one layer fail during registration. Every disposer is the exact Cordis effect disposer, and registration or removal notifies every `commands/change` observer so live adapters can refresh discovery; observer failures are logged and cannot veto the registry mutation or starve later observers.
 
-`list(agent)` returns immutable, name-sorted descriptors after scoped shadowing. `find(agent, name)` returns the corresponding definition. `execute(agent, line, signal)` uses `parseCommand()` and runs only a known command, returning the settled `CommandExecution` (the normalized result plus the lifecycle pairing `commandId`) or `undefined` for invalid syntax or unknown names. A resolved command's lifecycle is logged on the receiving agent's session as the log-only pair `command/run` (before the handler, with a minted `commandId`, the parser's structured `name`/`args` split, and the issuing `CommandSource`) and `command/done` (at settlement, with the outcome kind and verbatim text; a thrown or aborted handler settles as `kind: 'error'`). Admission misses log nothing. Both are direct standalone appends on the receiving agent's session: no turn wraps them, and persistence drains them through ordinary checkpoints and teardown.
+`list(agent)` returns immutable, name-sorted descriptors after scoped shadowing. `find(agent, name)` returns the corresponding definition. `execute(agent, line, signal)` uses `parseCommand()` and runs only a known command, returning the settled `CommandExecution` (the normalized result plus the lifecycle pairing `commandId`) or `undefined` for invalid syntax or unknown names. A resolved command's lifecycle is logged on the receiving agent's session as the log-only pair `command/run` (before the handler, with a minted `commandId`, the parser's structured name, the issuing `CommandSource`, and `args` unless `recordInput` is false) and `command/done` (at settlement, with the outcome kind and verbatim text; a thrown or aborted handler settles as `kind: 'error'`). Admission misses log nothing. Both are direct standalone appends on the receiving agent's session: no turn wraps them, and persistence drains them through ordinary checkpoints and teardown.
 
 `parseCommand()` recognizes a slash at byte zero, a lowercase name containing letters, digits, `_`, or `-`, and either end-of-input or whitespace. It returns every byte after the name as `rawInput`, including separator whitespace; consumers own their command-specific grammar and may normalize only what that grammar permits.
 
diff --git a/packages/ui/commands/README.zh.md b/packages/ui/commands/README.zh.md
index bace8f6346..8f02325271 100644
--- a/packages/ui/commands/README.zh.md
+++ b/packages/ui/commands/README.zh.md
@@ -6,9 +6,9 @@
 
 ## 服务契约
 
-`ctx.commands.register(definition)` 注册一个小写命令名称、描述、可选的非结构化输入提示，以及可中止的处理器。每个已注册命令都可供所有已组合的命令适配器使用；与某项部署不兼容的插件不会在此注册。普通上下文中的注册全局生效。在 `agent.ctx` 下挂载的命令生产插件会声明自身的 `commands` 注入，并创建精确限定到该 agent 的定义；该定义会遮蔽同名的全局定义。这种子级注入形态保留了 agent 作用域，同时不会让核心 agent loop 依赖 UI 服务。同一层中的名称重复会在注册时失败。每个 disposer 都是 Cordis effect 返回的确切 disposer；注册或移除命令时，系统会通知每个 `commands/change` 观察者，使实时适配器能够刷新发现结果。观察者失败会写入日志，既不能否决注册表变更，也不能阻止后续观察者运行。
+`ctx.commands.register(definition)` 注册一个小写命令名称、描述、可选的非结构化输入提示、可选的 `recordInput` 策略，以及可中止的处理器。`recordInput` 默认为 true；若载荷由命令的权威领域事件持有，该命令会将 `recordInput` 设为 false，让 `command/run` 省略 `args`，避免重复记录输入。每个已注册命令都可供所有已组合的命令适配器使用；与某项部署不兼容的插件不会在此注册。普通上下文中的注册全局生效。在 `agent.ctx` 下挂载的命令生产插件会声明自身的 `commands` 注入，并创建精确限定到该 agent 的定义；该定义会遮蔽同名的全局定义。这种子级注入形态保留了 agent 作用域，同时不会让核心 agent loop 依赖 UI 服务。同一层中的名称重复会在注册时失败。每个 disposer 都是 Cordis effect 返回的确切 disposer；注册或移除命令时，系统会通知每个 `commands/change` 观察者，使实时适配器能够刷新发现结果。观察者失败会写入日志，既不能否决注册表变更，也不能阻止后续观察者运行。
 
-`list(agent)` 在应用作用域遮蔽后，返回按名称排序的不可变描述符。`find(agent, name)` 返回相应定义。`execute(agent, line, signal)` 使用 `parseCommand()`，且只运行已知命令，返回已结算的 `CommandExecution`（规范化结果加生命周期配对 `commandId`）；语法无效或名称未知时返回 `undefined`。已解析命令的生命周期会以 log-only 事件对的形式记录在接收 agent 的会话日志中：`command/run`（进入处理器前记录，携带铸造的 `commandId`、解析器的结构化 `name`/`args` 切分和发起方 `CommandSource`）与 `command/done`（结算时记录，携带结局种类与原样文本；处理器抛出或被中止时以 `kind: 'error'` 结算）。未通过准入的输入不记录任何事件。两者都是直接独立追加：没有轮次包裹它们，持久化在常规检查点与 teardown 时排空它们。
+`list(agent)` 在应用作用域遮蔽后，返回按名称排序的不可变描述符。`find(agent, name)` 返回相应定义。`execute(agent, line, signal)` 使用 `parseCommand()`，且只运行已知命令，返回已结算的 `CommandExecution`（规范化结果加生命周期配对 `commandId`）；语法无效或名称未知时返回 `undefined`。已解析命令的生命周期会以 log-only 事件对的形式记录在接收 agent 的会话日志中：`command/run`（进入处理器前记录，携带铸造的 `commandId`、解析器得到的结构化名称、发起方 `CommandSource`，以及 `args`（`recordInput` 为 false 时省略））与 `command/done`（结算时记录，携带结局种类与原样文本；处理器抛出或被中止时以 `kind: 'error'` 结算）。未通过准入的输入不记录任何事件。两者都是直接独立追加：没有轮次包裹它们，持久化在常规检查点与 teardown 时排空它们。
 
 `parseCommand()` 识别位于字节零位置的斜杠、由小写字母、数字、`_` 或 `-` 构成的名称，以及名称后紧接输入末尾或空白的形式。它将名称后的每个字节作为 `rawInput` 返回，其中包括分隔空白；消费方拥有各命令专用的语法，只能执行该语法允许的规范化。
 
diff --git a/packages/ui/commands/src/index.ts b/packages/ui/commands/src/index.ts
index b1a5121243..b6dea581eb 100644
--- a/packages/ui/commands/src/index.ts
+++ b/packages/ui/commands/src/index.ts
@@ -71,6 +71,12 @@ export interface CommandDefinition {
   readonly description: string
   /** Optional free-form input hint advertised to capable clients. */
   readonly input?: CommandInputDescriptor
+  /**
+   * Whether `command/run` records `rawInput`. Defaults to true. A command
+   * whose domain event owns the payload sets this false to avoid duplicating
+   * that payload in the session log.
+   */
+  readonly recordInput?: boolean
   /** Execute against the receiving agent without sending the command to the model. */
   readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>
 }
@@ -127,9 +133,10 @@ declare module '@deepseek-ai/dsh-session' {
      * and `args` are `parseCommand`'s own split (name and verbatim rawInput,
      * separator whitespace included), so a consumer (a projection unit
      * folding its own command records, a rich command card) never re-parses
-     * a line.
+     * a line. `args` is absent when the definition sets `recordInput: false`
+     * because an authoritative domain event owns the input payload.
      */
-    'command/run': { commandId: CommandId; name: string; args: string; source: CommandSource }
+    'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
     /**
      * The paired command settled. `kind`/`text` carry the handler's verbatim
      * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
@@ -239,6 +246,7 @@ function normalizeDefinition(definition: CommandDefinition): RegisteredCommand {
     name: definition.name,
     description: definition.description,
     ...input === undefined ? {} : { input },
+    ...definition.recordInput === undefined ? {} : { recordInput: definition.recordInput },
     handler: definition.handler,
   })
   const descriptor = Object.freeze({
@@ -357,7 +365,10 @@ export class CommandService extends Service {
     if (signal.aborted) throw abortError(signal)
     const commandId = this.mintCommandId()
     this.appendLifecycle(agent.session, 'command/run', {
-      commandId, name: parsed.name, args: parsed.rawInput, source: { kind: 'user' },
+      commandId,
+      name: parsed.name,
+      ...command.definition.recordInput === false ? {} : { args: parsed.rawInput },
+      source: { kind: 'user' },
     })
     const invocation = Object.freeze({ agent, rawInput: parsed.rawInput, signal })
     let result: CommandResult
diff --git a/packages/ui/commands/tests/commands.spec.ts b/packages/ui/commands/tests/commands.spec.ts
index f22e974d58..b85971f5d7 100644
--- a/packages/ui/commands/tests/commands.spec.ts
+++ b/packages/ui/commands/tests/commands.spec.ts
@@ -320,6 +320,25 @@ describe('CommandService', () => {
     ])
   })
 
+  it('omits raw input from command/run when an authoritative domain event owns it', async () => {
+    const ctx = await mount()
+    const { agent } = await mintAgentScope(ctx, 'a')
+    const seen = vi.fn(() => ({ kind: 'success' as const }))
+    ctx.commands.register({
+      name: 'private',
+      description: 'Record privately',
+      recordInput: false,
+      handler: seen,
+    })
+
+    await ctx.commands.execute(agent, '/private keep this once', new AbortController().signal)
+
+    expect(seen).toHaveBeenCalledWith(expect.objectContaining({ rawInput: ' keep this once' }))
+    const run = agent.session.events.find(event => event.type === 'command/run')
+    expect(run?.type).toBe('command/run')
+    expect(run?.type === 'command/run' && Object.hasOwn(run.data, 'args')).toBe(false)
+  })
+
   it('mints distinct monotonic commandIds across executions', async () => {
     const ctx = await mount()
     const { agent } = await mintAgentScope(ctx, 'a')

From b8d51704f343d730fda933148e0c3a0f3176bb1f Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Wed, 29 Jul 2026 21:43:31 +0800
Subject: [PATCH 003/516] docs: refresh feedback module graph

---
 docs/module-graph.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index 511e132360..61477ae104 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -618,6 +618,7 @@ flowchart TD
   pkg_client_ui_goal --> pkg_invariants
   pkg_command_feedback --> pkg_commands
   pkg_command_feedback --> pkg_invariants
+  pkg_command_feedback --> pkg_session
   pkg_pty_local --> pkg_agent
   pkg_pty_local --> pkg_invariants
   pkg_pty_local --> pkg_pty
@@ -1092,7 +1093,7 @@ flowchart TD
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
 | [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`user-approval`](../packages/ui/user-approval) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
-| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants) |
+| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
 | [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | `telemetry` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-telemetry`](../packages/telemetry/session-telemetry) |

From eb51d4c6696927556ab9ad554d173b2e6beeb8a1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 15:41:16 +0800
Subject: [PATCH 004/516] fix(acp-snapshot): retain unchanged message ids

---
 ...table-snapshot-refresh-volatiles.i18n.yaml |   4 +-
 ...07-27-stable-snapshot-refresh-volatiles.md |  10 +-
 ...27-stable-snapshot-refresh-volatiles.zh.md |  10 +-
 .../support/acp-snapshot/README.i18n.yaml     |   4 +-
 packages/support/acp-snapshot/README.md       |   2 +-
 packages/support/acp-snapshot/README.zh.md    |   2 +-
 packages/support/acp-snapshot/src/suite.ts    | 112 +++++++++++++--
 .../record-suite/rec-child/behavior.json      |   6 +-
 .../record-suite/rec-child/session.1.jsonl    |   1 +
 .../record-suite/rec-child/session.jsonl      |   1 +
 .../support/acp-snapshot/tests/suite.spec.ts  | 128 ++++++++++++++++++
 11 files changed, 253 insertions(+), 27 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
index f2d73ddf1f..28e3accc20 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.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 .agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
-2026-07-27-stable-snapshot-refresh-volatiles.md: e2e951cd9f78b319a701a3e60afba48786633f03
-2026-07-27-stable-snapshot-refresh-volatiles.zh.md: 55302b509e28520f90f6cd820e4962be014318cc
+2026-07-27-stable-snapshot-refresh-volatiles.md: 5b513ea026008fc0c4ae9a8045408c534c050bec
+2026-07-27-stable-snapshot-refresh-volatiles.zh.md: f3c21d14ae235179ca15ec30d964e02877aa86e9
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
index e2e951cd9f..5b513ea026 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
@@ -8,9 +8,13 @@ English | [中文](2026-07-27-stable-snapshot-refresh-volatiles.zh.md)
 
 ACP snapshot comparison normalizes generated UUIDs, cwd aliases, spill locators, embedded event times, and omitted-byte counts, but refresh write-back persisted the fresh raw values. A behaviorally unchanged refresh therefore rewrote fixtures with new randomness or host-specific path spellings even though the comparison contract considered both logs equal.
 
+Message identity needs a weaker structural precondition than aligned records: an unrelated log event can break record alignment while an inherited message's identity-free value remains unchanged across parent and child logs. Record mode also begins with freshly minted message UUIDs when it replaces an existing fixture.
+
 ## Decision
 
-Refresh write-back uses `normalizeSessionLog` as its sole volatile-value authority. It normalizes the original harvested records with the fresh run's ids, cwd, and every cwd alias, while normalizing fixture records with the fixture header context; literal replacements affect only the raw values being written. After existing record alignment, it recursively compares fresh and existing leaves through those normalized records: normalized-equivalent leaves retain the existing raw value, while normalized-distinct leaves retain the fresh semantic value.
+Before record or refresh writes fixtures, the suite fingerprints every complete surface message with its top-level `id` removed and groups occurrences across all parent/child logs. It reuses an existing UUID only when one fingerprint resolves to exactly one fresh ID and one existing ID, then applies that mapping to every fresh log. Repeated inherited occurrences with the same ID remain one candidate, while new, changed, duplicate-content, malformed, and conflicting messages keep their fresh IDs.
+
+Refresh write-back uses `normalizeSessionLog` as its volatile-value authority for aligned leaves. It normalizes the original harvested records with the fresh run's ids, cwd, and every cwd alias, while normalizing fixture records with the fixture header context; literal replacements affect only the raw values being written. After existing record alignment, it recursively compares fresh and existing leaves through those normalized records: normalized-equivalent leaves retain the existing raw value, while normalized-distinct leaves retain the fresh semantic value.
 
 Before reuse, the complete logical-record layout must align, apart from the existing packed-chunk and inserted-title equivalences. Normalized-equivalent changed strings form a log-wide bijection: one fresh string maps to exactly one existing string and vice versa, so repeated IDs remain correlated across records. An unexplained record mismatch or conflicting mapping disables normalized string reuse for that log.
 
@@ -26,6 +30,6 @@ Object fields align by key. Array elements align only when all corresponding arr
 
 ## Consequences
 
-Repeated refreshes no longer rewrite aligned fixture values solely because the normalizer classifies them as volatile, and new volatile categories added to the normalizer automatically inherit the write-back behavior. Structural ambiguity remains conservative: unmatched records, conflicting string mappings, resized arrays, and strings containing both semantic and volatile changes use fresh values rather than risk reusing misaligned data.
+Record and refresh no longer rewrite an unchanged unique message UUID solely because another event changed the surrounding record layout. Repeated refreshes also retain aligned fixture values that the normalizer classifies as volatile, and new volatile categories added to the normalizer automatically inherit that write-back behavior. Structural ambiguity remains conservative: unmatched records, conflicting string mappings, resized arrays, strings containing both semantic and volatile changes, and non-unique message fingerprints use fresh values rather than risk reusing misaligned data.
 
-Focused unit coverage pins recursive object/array behavior, correlated IDs, ambiguous-layout fallback, conflicting mappings, fresh cwd aliases, volatile strings, and fresh semantic fields. Keyless refresh coverage proves approval UUIDs, cwd aliases, spill paths, and event-read volatility leave their committed fixtures byte-identical.
+Focused unit coverage pins scenario-wide parent/child message correlation, unrelated event insertion, record write-back, new/changed/ambiguous messages, recursive object/array behavior, conflicting mappings, fresh cwd aliases, volatile strings, and fresh semantic fields. Keyless refresh coverage proves approval UUIDs, cwd aliases, spill paths, and event-read volatility leave their committed fixtures byte-identical.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
index 55302b509e..f3c21d14ae 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
@@ -8,9 +8,13 @@ Status: implemented
 
 ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别名、spill locator、嵌入的事件时间和省略字节数，但刷新写回会持久化本次生成的原始值。因此，即使比较契约将两份日志视为相等，一次行为未发生变化的刷新仍会用新的随机值或宿主特有的路径写法改写 fixture（测试前置数据）。
 
+消息身份所需的结构前提比记录对齐更弱：无关的日志事件可能破坏记录对齐，但继承而来的消息去除身份后的值在父级和子级日志之间仍保持不变。录制模式在替换现有 fixture 时也会从新生成的消息 UUID 开始。
+
 ## 决策
 
-刷新写回以 `normalizeSessionLog` 作为易变值的唯一判定依据。系统使用本次运行的 id、cwd 及全部 cwd 别名归一化原始收集记录，并使用 fixture header 上下文归一化 fixture 记录；字面量替换只影响要写入的原始值。现有记录完成对齐后，系统基于这些归一化记录，递归比较本次生成记录与现有记录的叶节点：归一化后等价的叶节点保留现有原始值，归一化后不同的叶节点则保留本次生成的语义值。
+在录制或刷新写入 fixture 前，套件会移除每条完整 surface 消息的顶层 `id` 并计算指纹，同时将所有父级/子级日志中的出现项分组。仅当一个指纹恰好对应一个本次生成的 ID 和一个现有 ID 时，才会复用现有 UUID，随后将该映射应用到每份本次生成的日志。具有相同 ID、重复出现的继承消息仍算作一个候选项；新增、发生变化、内容重复、格式错误和存在冲突的消息则保留本次生成的 ID。
+
+刷新写回以 `normalizeSessionLog` 作为已对齐叶值的易变值判定依据。系统使用本次运行的 id、cwd 及全部 cwd 别名归一化原始收集记录，并使用 fixture header 上下文归一化 fixture 记录；字面量替换只影响要写入的原始值。现有记录完成对齐后，系统基于这些归一化记录，递归比较本次生成记录与现有记录的叶节点：归一化后等价的叶节点保留现有原始值，归一化后不同的叶节点则保留本次生成的语义值。
 
 复用前必须确保完整逻辑记录布局对齐，现有的打包分片与插入标题等价情形除外。归一化后等价但发生变化的字符串在整份日志范围内形成双射：一个本次生成的字符串只映射到一个现有字符串，反向亦然，因此跨记录重复出现的 ID 仍保持关联。出现无法解释的记录不匹配或映射冲突时，该日志会停用规范化字符串复用。
 
@@ -26,6 +30,6 @@ ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别
 
 ## 后果
 
-重复刷新不再仅仅因为规范化器将已对齐的 fixture 值归类为易变值，就改写这些值；以后加入规范化器的新易变值类别也会自动继承该写回行为。结构有歧义时仍采取保守策略：记录无法匹配、字符串映射冲突、数组尺寸发生变化，或字符串同时包含语义变化与易变变化时，均使用本次生成的值，避免冒险复用未对齐的数据。
+录制和刷新不再仅仅因为另一个事件改变了周边记录布局，就改写未变化且唯一的消息 UUID。重复刷新也会保留规范化器归类为易变值的已对齐 fixture 值；以后加入规范化器的新易变值类别也会自动继承该写回行为。结构有歧义时仍采取保守策略：记录无法匹配、字符串映射冲突、数组尺寸发生变化、字符串同时包含语义变化与易变变化，或消息指纹不唯一时，均使用本次生成的值，避免冒险复用未对齐的数据。
 
-聚焦的单元测试固定了递归处理对象与数组的行为、关联 ID、有歧义布局时的回退、映射冲突、本次运行的 cwd 别名、易变字符串以及本次生成的语义字段。无密钥刷新测试证明，审批 UUID、cwd 别名、spill 路径和事件读取中的易变值不会改变已提交 fixture 的任何字节。
+聚焦的单元测试固定了场景范围内的父级/子级消息关联、无关事件插入、录制写回、新增/发生变化/有歧义的消息、递归处理对象与数组的行为、映射冲突、本次运行的 cwd 别名、易变字符串以及本次生成的语义字段。无密钥刷新测试证明，审批 UUID、cwd 别名、spill 路径和事件读取中的易变值不会改变已提交 fixture 的任何字节。
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index 363e0f268c..afabe9147a 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/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/support/acp-snapshot/README.md
-README.md: 948c33a91977f078d16842c285011bf8f83623bd
-README.zh.md: fb86bd4e236be1c79f66dc46fbaac4d7dfbf9977
+README.md: e3752dfb522cd55776f3ef796acdc15037e5a761
+README.zh.md: 6ce531640b5311662e4b958177e4417c8878617f
diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md
index 948c33a919..e3752dfb52 100644
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -9,7 +9,7 @@ Four layers, importable separately:
 - **`launchAcpTestAgent` (launcher)** — boots a source agent under tsx or a built `lib` agent under plain Node from a supplied cwd, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through startup, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. When Windows accepts forced termination but publishes its exit marker asynchronously, shutdown gives that marker a bounded grace before treating fallback refusal as a second failure. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy.
 - **`runScenario` (harness)** — drives ACP JSON-RPC stdio from a deterministic `input.json` script through the launcher, tees raw stdout for the expected-output and purity checks, and harvests every persisted raw JSONL session log (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, optional `libBinScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is outside the repo; `workspaceParent` may move the generated child cwd from the platform temp directory when that grant is itself under test. Startup failures preserve captured agent stderr in the rejected diagnostic.
 - **Normalizers** — pure functions turning captured surfaces into stable text or portable fixtures: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs and every native/JavaScript filesystem spelling of the generated cwd → tokens, longest-first; cwd-rooted separators selected as canonical `/` or host-native; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `tokenizeSessionFixtureCwd` (the generated workspace and its filesystem aliases → `{{cwd}}`, authored temp paths unchanged), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
-- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario expected-output and re-persisted-log comparisons, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, a tokenized pin per header class composed with independently shared `system-prompt.expected.md` and `tool-schemas.expected.json` sidecars, and a live uniformity guard. Its fixture guards reject orphan scenario dirs, missing files, multiple pins for one class, duplicate sidecar content, unscrubbed JSONL headers, and malformed pinning headers. Refresh evaluates fresh leaves with the harvested run's ids, cwd, and every cwd alias, then reuses normalized-equivalent leaves only when the complete logical-record layout aligns and volatile string replacements form a bijection; ambiguous logs keep fresh strings, and fresh semantic values remain authoritative. It also expands packed timing envelopes before aligning event times, so switching between packed and unpacked layouts cannot shift later records. A newly inserted `session/title` receives its preceding event's time so feature-driven insertions do not churn the remainder of a fixture. Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.
+- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario expected-output and re-persisted-log comparisons, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, a tokenized pin per header class composed with independently shared `system-prompt.expected.md` and `tool-schemas.expected.json` sidecars, and a live uniformity guard. Its fixture guards reject orphan scenario dirs, missing files, multiple pins for one class, duplicate sidecar content, unscrubbed JSONL headers, and malformed pinning headers. Before record or refresh writes fixtures, an unchanged complete message retains its committed UUID when its identity-free value resolves to exactly one fresh ID and one existing ID across the scenario's parent/child logs; new, changed, and ambiguous messages keep fresh UUIDs. Refresh evaluates fresh leaves with the harvested run's ids, cwd, and every cwd alias, then reuses normalized-equivalent leaves only when the complete logical-record layout aligns and volatile string replacements form a bijection; ambiguous logs keep fresh strings, and fresh semantic values remain authoritative. It also expands packed timing envelopes before aligning event times, so switching between packed and unpacked layouts cannot shift later records. A newly inserted `session/title` receives its preceding event's time so feature-driven insertions do not churn the remainder of a fixture. Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.
 
 Committed session fixtures use canonical packed rows. An in-flight branch that merges this contract runs the [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) with `pnpm run migrate:packed-session-fixtures`; its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns deletion after affected branches converge.
 
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index fb86bd4e23..6ce531640b 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -9,7 +9,7 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 - **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动过程中公开异步 spawn 失败，对未处理权限请求快速失败，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才解析或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
 - **`runScenario`（harness）**：通过启动器从确定性 `input.json` 脚本驱动 ACP JSON-RPC stdio，将原始 stdout tee 给预期输出和纯度检查，并在优雅 stdin EOF 后收集每个持久化原始 JSONL 会话日志（父级和 subagent 子级，主级优先）。`AgentUnderTest` 提供绝对 `binScript`、可选 `libBinScript`、`configPath` 和 `tsconfigPath` 路径，因为子进程 cwd 位于仓库外。当生成子级 cwd 自身位于待测授权中时，`workspaceParent` 可以将它从平台临时目录移出。启动失败会在拒绝诊断中保留已捕获 agent stderr。
 - **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每个原生/JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名 → `{{cwd}}`，手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）和 `scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
-- **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、未擦除的 JSONL header，以及格式错误的 pin header。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用规范化后等价的叶值；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件是有序主级/子级清单；场景表不重复其数量。必须在 vitest 收集时调用。
+- **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新写入 fixture 前，如果一条未变化的完整消息去除身份后的值在场景的父级/子级日志中恰好对应一个本次生成的 ID 和一个现有 ID，它就会保留已提交的 UUID；新增、发生变化和有歧义的消息则保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用规范化后等价的叶值；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件是有序主级/子级清单；场景表不重复其数量。必须在 vitest 收集时调用。
 
 签入仓库的会话 fixture 使用规范打包行。合并此契约的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
 
diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts
index 1a8a49dac5..8a99bc0813 100644
--- a/packages/support/acp-snapshot/src/suite.ts
+++ b/packages/support/acp-snapshot/src/suite.ts
@@ -48,6 +48,9 @@ const TOOLS_TOKEN = '{{tools}}'
 
 const PACKED_CHUNK_ROW_TYPES = new Set(['text-chunks', 'reasoning-chunks', 'tool-call-chunks'])
 
+/** Canonical UUID spelling minted for ordinary message identities. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
 /** A snapshot scenario and how its fixtures are produced. */
 export interface Scenario {
   name: string
@@ -480,9 +483,9 @@ export function headerChangeCount(rawLog: string): number {
     .length
 }
 
-/** A literal string replacement used to carry an existing fixture's volatile value into a refreshed log. */
+/** A literal string replacement used to carry an existing fixture value into fresh write-back. */
 export interface FixtureReplacement {
-  /** The fresh replay-run value to replace. */
+  /** The fresh run's value to replace. */
   from: string
   /** The existing fixture value to keep. */
   to: string
@@ -494,6 +497,82 @@ function parseJsonlRecords(text: string): Record<string, unknown>[] {
     .map(line => JSON.parse(line) as Record<string, unknown>)
 }
 
+/** Return the complete identified message carried by one surface event. */
+function eventMessage(record: Record<string, unknown>): Record<string, unknown> | undefined {
+  const data = record.data
+  if (!isRecord(data)) return undefined
+  const message = record.type === 'user/message'
+    ? data
+    : record.type === 'assistant/message' || record.type === 'tool/result' || record.type === 'steering/message'
+      ? data.message
+      : undefined
+  if (
+    !isRecord(message)
+    || typeof message.id !== 'string'
+    || !UUID_RE.test(message.id)
+    || typeof message.role !== 'string'
+    || !Array.isArray(message.content)
+    || !isRecord(message.source)
+  ) return undefined
+  return message
+}
+
+/** Serialize parsed JSON by value rather than insertion order. */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  if (isRecord(value)) {
+    return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`
+  }
+  return JSON.stringify(value)
+}
+
+/** Index each unambiguous identity-free message value by its sole message id. */
+function uniqueMessageIds(logs: readonly string[]): Map<string, string | undefined> {
+  const fingerprintsById = new Map<string, string | undefined>()
+  for (const log of logs) {
+    for (const record of parseJsonlRecords(log)) {
+      const message = eventMessage(record)
+      if (message === undefined) continue
+      const { id, ...withoutId } = message
+      const messageId = id as string
+      const fingerprint = canonicalJson(withoutId)
+      if (!fingerprintsById.has(messageId)) fingerprintsById.set(messageId, fingerprint)
+      else if (fingerprintsById.get(messageId) !== fingerprint) fingerprintsById.set(messageId, undefined)
+    }
+  }
+
+  const idsByFingerprint = new Map<string, string | undefined>()
+  for (const [id, fingerprint] of fingerprintsById) {
+    if (fingerprint === undefined) continue
+    if (!idsByFingerprint.has(fingerprint)) idsByFingerprint.set(fingerprint, id)
+    else idsByFingerprint.set(fingerprint, undefined)
+  }
+  return idsByFingerprint
+}
+
+/**
+ * Match unchanged complete messages across a scenario's fresh and existing logs.
+ * New, changed, repeated, or otherwise ambiguous messages keep their fresh ids.
+ */
+function fixtureMessageIdReplacements(logs: HarvestedLog[], fixtures: string[]): FixtureReplacement[] {
+  const freshIds = uniqueMessageIds(logs.map(log => log.content))
+  const existingIds = uniqueMessageIds(fixtures)
+  const replacements: FixtureReplacement[] = []
+  for (const [fingerprint, fresh] of freshIds) {
+    const existing = existingIds.get(fingerprint)
+    if (fresh === undefined || existing === undefined || fresh === existing) continue
+    replacements.push({ from: fresh, to: existing })
+  }
+  return replacements
+}
+
+/** Apply literal fixture replacements without changing any other fresh value. */
+function applyFixtureReplacements(content: string, replacements: readonly FixtureReplacement[]): string {
+  let stable = content
+  for (const { from, to } of replacements) stable = stable.split(from).join(to)
+  return stable
+}
+
 /** One packed row's member times, or `undefined` for an ordinary record. */
 function packedTimes(record: Record<string, unknown>): number[] | undefined {
   if (!PACKED_CHUNK_ROW_TYPES.has(record.type as string)) return undefined
@@ -539,14 +618,15 @@ export function unknownToolCallIds(rawLog: string): string[] {
 }
 
 /**
- * Build the cross-log id/cwd/spill-path replacements used by refresh write-back.
+ * Build refresh write-back replacements: scenario-wide unchanged message ids,
+ * plus per-log session ids, cwd values, and spill paths.
  *
  * @param logs The freshly harvested logs, in fixture order.
  * @param fixtures The existing fixture contents, in matching order.
- * @returns Literal replacements from fresh volatile values to the fixture's old values.
+ * @returns Literal replacements from fresh values to the fixture's existing values.
  */
 export function refreshFixtureReplacements(logs: HarvestedLog[], fixtures: string[]): FixtureReplacement[] {
-  const replacements: FixtureReplacement[] = []
+  const replacements = fixtureMessageIdReplacements(logs, fixtures)
   for (let i = 0; i < logs.length; i++) {
     const fresh = parseJsonlRecords((logs[i] as HarvestedLog).content)[0]
     const existing = parseJsonlRecords(fixtures[i] ?? '')[0]
@@ -823,8 +903,7 @@ export function stabilizeRefreshLog(
   freshContext: NormalizeContext,
 ): string {
   const freshRecords = parseJsonlRecords(fresh)
-  let stable = fresh
-  for (const { from, to } of replacements) stable = stable.split(from).join(to)
+  const stable = applyFixtureReplacements(fresh, replacements)
   const existingRecords = logicalRecords(parseJsonlRecords(existing))
   const records = parseJsonlRecords(stable)
   const existingContext = fixtureContext(existing)
@@ -1016,10 +1095,6 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
         const portableFixture = scenario.workspaceParent === undefined
           ? tokenizeSessionFixtureCwd
           : (log: string): string => log
-        const existingFixtures = REFRESHING
-          ? await Promise.all(fixtureFiles.map(file => readFile(join(dir, file), 'utf8')))
-          : []
-        const replacements = REFRESHING ? refreshFixtureReplacements(result.sessionLogs, existingFixtures) : []
         const writesSessionFixtures = (RECORDING && scenario.recorded && scenario.hasModelTurn)
           || (REFRESHING && comparesLog)
         if (writesSessionFixtures) {
@@ -1032,14 +1107,25 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
             'session.jsonl',
             ...Array.from({ length: result.sessionLogs.length - 1 }, (_, i) => `session.${i + 1}.jsonl`),
           ]
+          const existingFixtures = await Promise.all(outputFixtureFiles.map(async (file) => {
+            const path = join(dir, file)
+            return existsSync(path) ? readFile(path, 'utf8') : ''
+          }))
+          const replacements = REFRESHING
+            ? refreshFixtureReplacements(result.sessionLogs, existingFixtures)
+            : fixtureMessageIdReplacements(result.sessionLogs, existingFixtures)
           const primary = (result.sessionLogs[0] as HarvestedLog).content
           await writeFile(join(dir, outputFixtureFiles[0] as string), scrub(portableFixture(
-            REFRESHING ? stabilizeRefreshLog(primary, existingFixtures[0] as string, replacements, ctx) : primary,
+            REFRESHING
+              ? stabilizeRefreshLog(primary, existingFixtures[0] as string, replacements, ctx)
+              : applyFixtureReplacements(primary, replacements),
           )))
           for (let i = 1; i < result.sessionLogs.length; i++) {
             const child = (result.sessionLogs[i] as HarvestedLog).content
             await writeFile(join(dir, outputFixtureFiles[i] as string), scrub(portableFixture(
-              REFRESHING ? stabilizeRefreshLog(child, existingFixtures[i] as string, replacements, ctx) : child,
+              REFRESHING
+                ? stabilizeRefreshLog(child, existingFixtures[i] as string, replacements, ctx)
+                : applyFixtureReplacements(child, replacements),
             )))
           }
           if (RECORDING) {
diff --git a/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/behavior.json b/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/behavior.json
index d98afb4865..971006c139 100644
--- a/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/behavior.json
+++ b/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/behavior.json
@@ -3,11 +3,13 @@
   "logs": [
     { "file": "b/parent/session.jsonl", "lines": [
       { "type": "session", "id": "{{SID}}", "createdAt": 700, "cwd": "{{CWD}}", "delegationDepth": 0 },
-      { "type": "request/header", "seq": 0, "time": 3, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } }
+      { "type": "request/header", "seq": 0, "time": 3, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } },
+      { "type": "user/message", "seq": 1, "time": 5, "data": { "role": "user", "content": [{ "type": "text", "text": "same inherited message" }], "source": { "kind": "user" }, "id": "11111111-1111-4111-8111-111111111111" }, "surfaceOp": "append" }
     ]},
     { "file": "b/child/session.jsonl", "lines": [
       { "type": "session", "id": "abababab-cdcd-4efe-8ada-badabadabada", "createdAt": 800, "cwd": "{{CWD}}", "parentSession": "{{SID}}", "delegationDepth": 1 },
-      { "type": "request/header", "seq": 0, "time": 2, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } }
+      { "type": "request/header", "seq": 0, "time": 2, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } },
+      { "type": "user/message", "seq": 1, "time": 5, "data": { "role": "user", "content": [{ "type": "text", "text": "same inherited message" }], "source": { "kind": "user" }, "id": "11111111-1111-4111-8111-111111111111" }, "surfaceOp": "append" }
     ]}
   ]
 }
diff --git a/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/session.1.jsonl b/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/session.1.jsonl
index 4fa81014ae..384b3954cf 100644
--- a/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/session.1.jsonl
+++ b/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/session.1.jsonl
@@ -1,2 +1,3 @@
 {"type":"session","id":"abababab-cdcd-4efe-8ada-badabadabada","createdAt":800,"cwd":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-KBQJbW","parentSession":"f6fa7fcf-dd9c-4b39-8815-b25ddcebfd88","delegationDepth":1}
 {"type":"request/header","seq":0,"time":2,"data":{"header":{"config":{"model":"fake"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"user/message","seq":1,"time":5,"data":{"role":"user","content":[{"type":"text","text":"same inherited message"}],"source":{"kind":"user"},"id":"22222222-2222-4222-8222-222222222222"},"surfaceOp":"append"}
diff --git a/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/session.jsonl b/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/session.jsonl
index e972a78d8e..0ffe7f9f5f 100644
--- a/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/session.jsonl
+++ b/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-child/session.jsonl
@@ -1,2 +1,3 @@
 {"type":"session","id":"f6fa7fcf-dd9c-4b39-8815-b25ddcebfd88","createdAt":700,"cwd":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-KBQJbW","delegationDepth":0}
 {"type":"request/header","seq":0,"time":3,"data":{"header":{"config":{"model":"fake"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"user/message","seq":1,"time":5,"data":{"role":"user","content":[{"type":"text","text":"same inherited message"}],"source":{"kind":"user"},"id":"22222222-2222-4222-8222-222222222222"},"surfaceOp":"append"}
diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts
index da069905ec..2cd665f540 100644
--- a/packages/support/acp-snapshot/tests/suite.spec.ts
+++ b/packages/support/acp-snapshot/tests/suite.spec.ts
@@ -193,6 +193,18 @@ describe('defineAcpSnapshotSuite: record inventory write-back', () => {
     expect(fixture).toContain('"cwd":"{{cwd}}"')
     expect(() => readFileSync(join(recordDir, 'rec-child', 'session.2.jsonl'), 'utf8')).toThrow()
   })
+
+  it('retains an unchanged message id across the recorded parent and child fixtures', () => {
+    const existingMessageId = '22222222-2222-4222-8222-222222222222'
+    const freshMessageId = '11111111-1111-4111-8111-111111111111'
+    const fixtures = ['session.jsonl', 'session.1.jsonl']
+      .map(file => readFileSync(join(recordDir, 'rec-child', file), 'utf8'))
+
+    for (const fixture of fixtures) {
+      expect(fixture).toContain(`"id":"${existingMessageId}"`)
+      expect(fixture).not.toContain(freshMessageId)
+    }
+  })
 })
 
 describe('defineAcpSnapshotSuite: registration contract', () => {
@@ -663,6 +675,78 @@ describe('refreshFixtureReplacements', () => {
       { from: freshBash, to: oldBash },
     ])
   })
+
+  it('maps one inherited message id across parent and child logs', () => {
+    const freshMessageId = '11111111-1111-4111-8111-111111111111'
+    const existingMessageId = '22222222-2222-4222-8222-222222222222'
+    const content = [{ type: 'text', text: 'inherited' }]
+    const log = (sessionId: string, messageId: string): string => [
+      JSON.stringify({ type: 'session', id: sessionId, cwd: '/same' }),
+      JSON.stringify({
+        type: 'user/message',
+        data: { role: 'user', content, source: { kind: 'user' }, id: messageId },
+      }),
+      '',
+    ].join('\n')
+    const harvested = (content: string): HarvestedLog => ({ id: 'diagnostic', createdAt: 1, content })
+
+    const replacements = refreshFixtureReplacements(
+      [harvested(log('fresh-parent', freshMessageId)), harvested(log('fresh-child', freshMessageId))],
+      [log('old-parent', existingMessageId), log('old-child', existingMessageId)],
+    )
+
+    expect(replacements.filter(replacement => replacement.from === freshMessageId)).toEqual([
+      { from: freshMessageId, to: existingMessageId },
+    ])
+  })
+
+  it('keeps fresh ids for new, changed, and ambiguous messages', () => {
+    const ids = {
+      new: '11111111-1111-4111-8111-111111111111',
+      changed: '22222222-2222-4222-8222-222222222222',
+      ambiguousA: '33333333-3333-4333-8333-333333333333',
+      ambiguousB: '44444444-4444-4444-8444-444444444444',
+      oldChanged: '55555555-5555-4555-8555-555555555555',
+      oldAmbiguous: '66666666-6666-4666-8666-666666666666',
+      stable: '77777777-7777-4777-8777-777777777777',
+    } as const
+    const message = (id: string, text: string): Record<string, unknown> => ({
+      type: 'user/message',
+      data: { role: 'user', content: [{ type: 'text', text }], source: { kind: 'user' }, id },
+    })
+    const log = (messages: Record<string, unknown>[]): string => [
+      JSON.stringify({ type: 'session', id: 'same', cwd: '/same' }),
+      ...messages.map(record => JSON.stringify(record)),
+      '',
+    ].join('\n')
+    const fresh = log([
+      message(ids.new, 'new'),
+      message(ids.changed, 'changed'),
+      message(ids.changed, 'changed again'),
+      message(ids.ambiguousA, 'duplicate'),
+      message(ids.ambiguousB, 'duplicate'),
+      message(ids.stable, 'stable'),
+    ])
+    const existing = log([
+      message(ids.oldChanged, 'before'),
+      message(ids.oldAmbiguous, 'duplicate'),
+      message(ids.stable, 'stable'),
+    ])
+
+    const replacements = refreshFixtureReplacements(
+      [{ id: 'diagnostic', createdAt: 1, content: fresh }],
+      [existing],
+    )
+
+    const replacedIds = replacements.map(replacement => replacement.from)
+    for (const id of [
+      ids.new,
+      ids.changed,
+      ids.ambiguousA,
+      ids.ambiguousB,
+      ids.stable,
+    ]) expect(replacedIds).not.toContain(id)
+  })
 })
 
 describe('stabilizeRefreshLog', () => {
@@ -765,6 +849,50 @@ describe('stabilizeRefreshLog', () => {
     ].join('\n'))
   })
 
+  it('retains unchanged message ids across an unrelated inserted event', () => {
+    const freshUserId = '11111111-1111-4111-8111-111111111111'
+    const existingUserId = '22222222-2222-4222-8222-222222222222'
+    const freshAssistantId = '33333333-3333-4333-8333-333333333333'
+    const existingAssistantId = '44444444-4444-4444-8444-444444444444'
+    const user = (id: string): Record<string, unknown> => ({
+      type: 'user/message',
+      data: { role: 'user', content: [{ type: 'text', text: 'same user' }], source: { kind: 'user' }, id },
+    })
+    const assistant = (id: string): Record<string, unknown> => ({
+      type: 'assistant/message',
+      data: {
+        turn: 1,
+        step: 1,
+        message: {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'same assistant' }],
+          source: { kind: 'model', provider: 'fake', model: 'fake' },
+          id,
+        },
+      },
+    })
+    const lines = (records: Record<string, unknown>[]): string => [
+      JSON.stringify({ type: 'session', id: 'same', createdAt: 1, cwd: '/same' }),
+      ...records.map(record => JSON.stringify(record)),
+      '',
+    ].join('\n')
+    const fresh = lines([
+      user(freshUserId),
+      { type: 'session/inherited', data: {} },
+      assistant(freshAssistantId),
+    ])
+    const existing = lines([user(existingUserId), assistant(existingAssistantId)])
+    const replacements = refreshFixtureReplacements(
+      [{ id: 'diagnostic', createdAt: 1, content: fresh }],
+      [existing],
+    )
+    const output = stabilize(fresh, existing, replacements).trim().split('\n')
+      .map(line => JSON.parse(line) as Record<string, unknown>)
+
+    expect((output[1]?.data as { id: string }).id).toBe(existingUserId)
+    expect(((output[3]?.data as { message: { id: string } }).message).id).toBe(existingAssistantId)
+  })
+
   it('keeps volatile fixture fields while preserving fresh meaningful payloads', () => {
     const fresh = [
       '{"type":"session","id":"new-child","createdAt":200,"cwd":"/new","parentSession":"new-parent","seedLength":1}',

From 466a2f12c3196c532ea6fde0918805daf67d87a8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 17:51:07 +0800
Subject: [PATCH 005/516] fix(snapshot): stabilize all recorder message ids

---
 ...table-snapshot-refresh-volatiles.i18n.yaml |  4 +-
 ...07-27-stable-snapshot-refresh-volatiles.md |  4 +-
 ...27-stable-snapshot-refresh-volatiles.zh.md |  4 +-
 apps/web/tests/scaffold.ts                    |  9 ++--
 examples/jsonrpc-agent/tests/sdk.snapshot.ts  | 15 ++++--
 examples/tui-agent/tests/tui.snapshot.ts      | 25 +++++-----
 .../support/acp-snapshot/README.i18n.yaml     |  4 +-
 packages/support/acp-snapshot/README.md       |  4 +-
 packages/support/acp-snapshot/README.zh.md    |  4 +-
 packages/support/acp-snapshot/src/index.ts    |  1 +
 packages/support/acp-snapshot/src/suite.ts    | 49 ++++++++++++-------
 .../support/acp-snapshot/tests/suite.spec.ts  | 37 +++++++++++++-
 12 files changed, 110 insertions(+), 50 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
index 28e3accc20..3a474e377b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.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 .agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
-2026-07-27-stable-snapshot-refresh-volatiles.md: 5b513ea026008fc0c4ae9a8045408c534c050bec
-2026-07-27-stable-snapshot-refresh-volatiles.zh.md: f3c21d14ae235179ca15ec30d964e02877aa86e9
+2026-07-27-stable-snapshot-refresh-volatiles.md: cd806c929ba956098f532d19159ff2dc3e782325
+2026-07-27-stable-snapshot-refresh-volatiles.zh.md: 3144bcb45aa8524e29fae3d07479cb917987ea79
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
index 5b513ea026..cd806c929b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
@@ -12,7 +12,7 @@ Message identity needs a weaker structural precondition than aligned records: an
 
 ## Decision
 
-Before record or refresh writes fixtures, the suite fingerprints every complete surface message with its top-level `id` removed and groups occurrences across all parent/child logs. It reuses an existing UUID only when one fingerprint resolves to exactly one fresh ID and one existing ID, then applies that mapping to every fresh log. Repeated inherited occurrences with the same ID remain one candidate, while new, changed, duplicate-content, malformed, and conflicting messages keep their fresh IDs.
+Before record or refresh writes session fixtures, the shared snapshot support fingerprints every complete surface message with its top-level `id` removed and groups occurrences across all parent/child logs. It reuses an existing UUID only when one fingerprint resolves to exactly one fresh ID and one existing ID, then applies that mapping to every fresh log. Repeated inherited occurrences with the same ID remain one candidate, while new, changed, duplicate-content, malformed, and conflicting messages keep their fresh IDs. ACP, JSON-RPC, TUI, and web recorders pass fixture-ready logs through the same helper before writing.
 
 Refresh write-back uses `normalizeSessionLog` as its volatile-value authority for aligned leaves. It normalizes the original harvested records with the fresh run's ids, cwd, and every cwd alias, while normalizing fixture records with the fixture header context; literal replacements affect only the raw values being written. After existing record alignment, it recursively compares fresh and existing leaves through those normalized records: normalized-equivalent leaves retain the existing raw value, while normalized-distinct leaves retain the fresh semantic value.
 
@@ -30,6 +30,6 @@ Object fields align by key. Array elements align only when all corresponding arr
 
 ## Consequences
 
-Record and refresh no longer rewrite an unchanged unique message UUID solely because another event changed the surrounding record layout. Repeated refreshes also retain aligned fixture values that the normalizer classifies as volatile, and new volatile categories added to the normalizer automatically inherit that write-back behavior. Structural ambiguity remains conservative: unmatched records, conflicting string mappings, resized arrays, strings containing both semantic and volatile changes, and non-unique message fingerprints use fresh values rather than risk reusing misaligned data.
+Record and refresh no longer rewrite an unchanged unique message UUID solely because another event changed the surrounding record layout, regardless of whether ACP, JSON-RPC, TUI, or web owns the recording. Repeated refreshes also retain aligned fixture values that the normalizer classifies as volatile, and new volatile categories added to the normalizer automatically inherit that write-back behavior. Structural ambiguity remains conservative: unmatched records, conflicting string mappings, resized arrays, strings containing both semantic and volatile changes, and non-unique message fingerprints use fresh values rather than risk reusing misaligned data.
 
 Focused unit coverage pins scenario-wide parent/child message correlation, unrelated event insertion, record write-back, new/changed/ambiguous messages, recursive object/array behavior, conflicting mappings, fresh cwd aliases, volatile strings, and fresh semantic fields. Keyless refresh coverage proves approval UUIDs, cwd aliases, spill paths, and event-read volatility leave their committed fixtures byte-identical.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
index f3c21d14ae..3144bcb45a 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
@@ -12,7 +12,7 @@ ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别
 
 ## 决策
 
-在录制或刷新写入 fixture 前，套件会移除每条完整 surface 消息的顶层 `id` 并计算指纹，同时将所有父级/子级日志中的出现项分组。仅当一个指纹恰好对应一个本次生成的 ID 和一个现有 ID 时，才会复用现有 UUID，随后将该映射应用到每份本次生成的日志。具有相同 ID、重复出现的继承消息仍算作一个候选项；新增、发生变化、内容重复、格式错误和存在冲突的消息则保留本次生成的 ID。
+在录制或刷新写入会话 fixture 前，共享快照支持层会移除每条完整 surface 消息的顶层 `id` 并计算指纹，同时将所有父级/子级日志中的出现项分组。仅当一个指纹恰好对应一个本次生成的 ID 和一个现有 ID 时，才会复用现有 UUID，随后将该映射应用到每份本次生成的日志。具有相同 ID、重复出现的继承消息仍算作一个候选项；新增、发生变化、内容重复、格式错误和存在冲突的消息则保留本次生成的 ID。ACP、JSON-RPC、TUI 和 web 录制器都会先让可写入 fixture 的日志经过同一个辅助函数，再执行写入。
 
 刷新写回以 `normalizeSessionLog` 作为已对齐叶值的易变值判定依据。系统使用本次运行的 id、cwd 及全部 cwd 别名归一化原始收集记录，并使用 fixture header 上下文归一化 fixture 记录；字面量替换只影响要写入的原始值。现有记录完成对齐后，系统基于这些归一化记录，递归比较本次生成记录与现有记录的叶节点：归一化后等价的叶节点保留现有原始值，归一化后不同的叶节点则保留本次生成的语义值。
 
@@ -30,6 +30,6 @@ ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别
 
 ## 后果
 
-录制和刷新不再仅仅因为另一个事件改变了周边记录布局，就改写未变化且唯一的消息 UUID。重复刷新也会保留规范化器归类为易变值的已对齐 fixture 值；以后加入规范化器的新易变值类别也会自动继承该写回行为。结构有歧义时仍采取保守策略：记录无法匹配、字符串映射冲突、数组尺寸发生变化、字符串同时包含语义变化与易变变化，或消息指纹不唯一时，均使用本次生成的值，避免冒险复用未对齐的数据。
+录制和刷新不再仅仅因为另一个事件改变了周边记录布局，就改写未变化且唯一的消息 UUID，无论该录制由 ACP、JSON-RPC、TUI 还是 web 负责。重复刷新也会保留规范化器归类为易变值的已对齐 fixture 值；以后加入规范化器的新易变值类别也会自动继承该写回行为。结构有歧义时仍采取保守策略：记录无法匹配、字符串映射冲突、数组尺寸发生变化、字符串同时包含语义变化与易变变化，或消息指纹不唯一时，均使用本次生成的值，避免冒险复用未对齐的数据。
 
 聚焦的单元测试固定了场景范围内的父级/子级消息关联、无关事件插入、录制写回、新增/发生变化/有歧义的消息、递归处理对象与数组的行为、映射冲突、本次运行的 cwd 别名、易变字符串以及本次生成的语义字段。无密钥刷新测试证明，审批 UUID、cwd 别名、spill 路径和事件读取中的易变值不会改变已提交 fixture 的任何字节。
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 753cdc2953..d11604c075 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -27,7 +27,7 @@ import { expect } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import Include, { type PatchOptions } from '@cordisjs/plugin-include'
-import { scrubRequestHeaders } from '@deepseek-ai/dsh-acp-snapshot'
+import { scrubRequestHeaders, stabilizeFixtureMessageIds } from '@deepseek-ai/dsh-acp-snapshot'
 import { assertEntriesLoaded } from '@deepseek-ai/dsh-app-boot'
 import type { ReplayHandle } from '@deepseek-ai/dsh-llm-replay'
 import { installLlmReplay, parseSessionLog } from '@deepseek-ai/dsh-llm-replay'
@@ -302,11 +302,14 @@ function rawSessionLog(session: Session): string {
 export async function recordFixture(scaffold: WebScaffold, sessionId: SessionId, fixturePath: string): Promise<void> {
   const agent = scaffold.ctx.agents.get(sessionId)
   if (agent === undefined) throw new Error(`record harvest: no live agent for ${sessionId}`)
-  const tokenized = scrubRequestHeaders(rawSessionLog(agent.session))
+  const fresh = scrubRequestHeaders(rawSessionLog(agent.session))
     .split(sessionId).join('{{sessionId}}')
     .split(scaffold.workspaceCwd).join('{{cwd}}')
     .replace(/"rpcId":"[^"]+"/g, '"rpcId":"{{rpcId}}"')
-  await writeFile(fixturePath, tokenized)
+  const existing = existsSync(fixturePath) ? await readFile(fixturePath, 'utf8') : ''
+  const stable = stabilizeFixtureMessageIds([fresh], [existing])[0]
+  if (stable === undefined) throw new Error('record harvest: no stabilized fixture')
+  await writeFile(fixturePath, stable)
 }
 
 /**
diff --git a/examples/jsonrpc-agent/tests/sdk.snapshot.ts b/examples/jsonrpc-agent/tests/sdk.snapshot.ts
index c54812e3e5..3f0edac743 100644
--- a/examples/jsonrpc-agent/tests/sdk.snapshot.ts
+++ b/examples/jsonrpc-agent/tests/sdk.snapshot.ts
@@ -9,6 +9,7 @@
  * fixtures and rewrites expected outputs.
  */
 
+import { existsSync } from 'node:fs'
 import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { delimiter, join } from 'node:path'
@@ -19,6 +20,7 @@ import {
   normalizeStdout,
   refreshFixtureReplacements,
   scrubRequestHeaders,
+  stabilizeFixtureMessageIds,
   stabilizeRefreshLog,
   tokenizeSessionFixtureCwd,
   type HarvestedLog,
@@ -230,20 +232,25 @@ describe('TypeScript SDK snapshots over the jsonrpc runtime', () => {
       const { result, notifications, logs, cwd } = await runScenario(scenario)
       const ordered = orderLogs(logs, scenario)
       const actualContext = contextOf(ordered, cwd)
+      const files = fixtureFiles(scenario)
 
       if (recording) {
         // Fixtures carry tokenized request headers; llm-replay reads only
         // assistant output and tool traffic, so scrubbing keeps prompts and
         // schemas out of the corpus without affecting replay.
         await mkdir(scenarioDir, { recursive: true })
-        await Promise.all(ordered.map(async (log, index) => {
-          const file = fixtureFiles(scenario)[index]
+        const existing = await Promise.all(files.map(async file => existsSync(file) ? readFile(file, 'utf8') : ''))
+        const fixtures = stabilizeFixtureMessageIds(
+          ordered.map(log => scrubRequestHeaders(tokenizeSessionFixtureCwd(log.content))),
+          existing,
+        )
+        await Promise.all(fixtures.map(async (fixture, index) => {
+          const file = files[index]
           if (file === undefined) throw new Error(`no fixture path for persisted log ${index}`)
-          await writeFile(file, scrubRequestHeaders(tokenizeSessionFixtureCwd(log.content)))
+          await writeFile(file, fixture)
         }))
       }
 
-      const files = fixtureFiles(scenario)
       let expectedContents = await Promise.all(files.map(file => readFile(file, 'utf8')))
 
       if (refreshing) {
diff --git a/examples/tui-agent/tests/tui.snapshot.ts b/examples/tui-agent/tests/tui.snapshot.ts
index 95b960e3b6..934621b037 100644
--- a/examples/tui-agent/tests/tui.snapshot.ts
+++ b/examples/tui-agent/tests/tui.snapshot.ts
@@ -1,10 +1,15 @@
+import { existsSync } from 'node:fs'
 import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
 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, vi } from 'vitest'
 import { Context } from 'cordis'
-import { scrubRequestHeaders, tokenizeSessionFixtureCwd } from '@deepseek-ai/dsh-acp-snapshot'
+import {
+  scrubRequestHeaders,
+  stabilizeFixtureMessageIds,
+  tokenizeSessionFixtureCwd,
+} from '@deepseek-ai/dsh-acp-snapshot'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import * as AgentCore from '@deepseek-ai/dsh-agent-spine-demo'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
@@ -484,17 +489,15 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
 async function writeRecording(scenario: Scenario, result: ScenarioResult): Promise<void> {
   const dir = scenarioDir(scenario)
   await mkdir(dir, { recursive: true })
-  await writeFile(
-    join(dir, 'session.jsonl'),
-    scrubRequestHeaders(tokenizeSessionFixtureCwd(rawSessionLog(result.parent))),
-  )
   expect(result.children).toHaveLength(scenario.childSessions ?? 0)
-  for (const [index, child] of result.children.entries()) {
-    await writeFile(
-      join(dir, `session.${index + 1}.jsonl`),
-      scrubRequestHeaders(tokenizeSessionFixtureCwd(rawSessionLog(child))),
-    )
-  }
+  const files = [join(dir, 'session.jsonl'), ...childFixturePaths(scenario)]
+  const existing = await Promise.all(files.map(async file => existsSync(file) ? readFile(file, 'utf8') : ''))
+  const fixtures = stabilizeFixtureMessageIds(
+    [result.parent, ...result.children]
+      .map(session => scrubRequestHeaders(tokenizeSessionFixtureCwd(rawSessionLog(session)))),
+    existing,
+  )
+  await Promise.all(fixtures.map((fixture, index) => writeFile(files[index] as string, fixture)))
 }
 
 describe('TUI recorded-session terminal snapshots', () => {
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index afabe9147a..f90ce7ada8 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/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/support/acp-snapshot/README.md
-README.md: e3752dfb522cd55776f3ef796acdc15037e5a761
-README.zh.md: 6ce531640b5311662e4b958177e4417c8878617f
+README.md: c5a1a07b9f85e1a91c52fe102be17e4172be112d
+README.zh.md: 2454df9b3d8e67b4728d6582279ba21798d2ba9e
diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md
index e3752dfb52..c5a1a07b9f 100644
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -8,7 +8,7 @@ Four layers, importable separately:
 
 - **`launchAcpTestAgent` (launcher)** — boots a source agent under tsx or a built `lib` agent under plain Node from a supplied cwd, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through startup, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. When Windows accepts forced termination but publishes its exit marker asynchronously, shutdown gives that marker a bounded grace before treating fallback refusal as a second failure. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy.
 - **`runScenario` (harness)** — drives ACP JSON-RPC stdio from a deterministic `input.json` script through the launcher, tees raw stdout for the expected-output and purity checks, and harvests every persisted raw JSONL session log (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, optional `libBinScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is outside the repo; `workspaceParent` may move the generated child cwd from the platform temp directory when that grant is itself under test. Startup failures preserve captured agent stderr in the rejected diagnostic.
-- **Normalizers** — pure functions turning captured surfaces into stable text or portable fixtures: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs and every native/JavaScript filesystem spelling of the generated cwd → tokens, longest-first; cwd-rooted separators selected as canonical `/` or host-native; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `tokenizeSessionFixtureCwd` (the generated workspace and its filesystem aliases → `{{cwd}}`, authored temp paths unchanged), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **Normalizers** — pure functions turning captured surfaces into stable text or portable fixtures: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs and every native/JavaScript filesystem spelling of the generated cwd → tokens, longest-first; cwd-rooted separators selected as canonical `/` or host-native; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `tokenizeSessionFixtureCwd` (the generated workspace and its filesystem aliases → `{{cwd}}`, authored temp paths unchanged), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)), and `stabilizeFixtureMessageIds` (committed UUIDs carried into unchanged, unambiguous messages across any recorder's fixture-ready parent/child logs).
 - **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario expected-output and re-persisted-log comparisons, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, a tokenized pin per header class composed with independently shared `system-prompt.expected.md` and `tool-schemas.expected.json` sidecars, and a live uniformity guard. Its fixture guards reject orphan scenario dirs, missing files, multiple pins for one class, duplicate sidecar content, unscrubbed JSONL headers, and malformed pinning headers. Before record or refresh writes fixtures, an unchanged complete message retains its committed UUID when its identity-free value resolves to exactly one fresh ID and one existing ID across the scenario's parent/child logs; new, changed, and ambiguous messages keep fresh UUIDs. Refresh evaluates fresh leaves with the harvested run's ids, cwd, and every cwd alias, then reuses normalized-equivalent leaves only when the complete logical-record layout aligns and volatile string replacements form a bijection; ambiguous logs keep fresh strings, and fresh semantic values remain authoritative. It also expands packed timing envelopes before aligning event times, so switching between packed and unpacked layouts cannot shift later records. A newly inserted `session/title` receives its preceding event's time so feature-driven insertions do not churn the remainder of a fixture. Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.
 
 Committed session fixtures use canonical packed rows. An in-flight branch that merges this contract runs the [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) with `pnpm run migrate:packed-session-fixtures`; its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns deletion after affected branches converge.
@@ -59,7 +59,7 @@ Every scenario compares `stdout.expected.jsonl` with cwd-rooted separators canon
 
 The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config Agent Note](../../../.agents/notes/archived/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. `pnpm run test:snapshot:record` calls the live LLM and rewrites the recorded scenarios' model fixtures; `pnpm run test:snapshot:refresh` stays keyless, runs the replay overlay, and rewrites stdout, comparable session-log expected outputs, and owned prompt and tool-schema sidecars from the committed model scripts. Fixture roles, record/replay/refresh semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot Agent Note](../../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md).
 
-Constraints: `suite.ts` and `harness.ts` import vitest (the harness polls its durable-boundary waits through `vi.waitFor`), so the package entry is importable only inside a vitest run (the launcher and normalizers have no such dependency but ship from the same entry). The launcher and suite factory are ACP-specific by design — the launcher speaks the SDK's `ClientSideConnection` — while the normalizers are transport-neutral session-log/text helpers also consumed by the TUI snapshot suite and the web browser e2e lane. Input scripts cover initialization, fresh-session creation, text prompting, cancellation, expected RPC failures, and durable turn-boundary waits. Permission round-trips are a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) mapped to the agent-issued `optionId`; an absent or exhausted queue answers `cancelled`, and an unoffered kind rejects the run.
+Constraints: `suite.ts` and `harness.ts` import vitest (the harness polls its durable-boundary waits through `vi.waitFor`), so the package entry is importable only inside a vitest run (the launcher and normalizers have no such dependency but ship from the same entry). The launcher and suite factory are ACP-specific by design — the launcher speaks the SDK's `ClientSideConnection` — while the normalizers are transport-neutral session-log/text helpers also consumed by the JSON-RPC, TUI, and web snapshot recorders. Input scripts cover initialization, fresh-session creation, text prompting, cancellation, expected RPC failures, and durable turn-boundary waits. Permission round-trips are a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) mapped to the agent-issued `optionId`; an absent or exhausted queue answers `cancelled`, and an unoffered kind rejects the run.
 
 ## Model Experience
 
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index 6ce531640b..2454df9b3d 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -8,7 +8,7 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 
 - **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动过程中公开异步 spawn 失败，对未处理权限请求快速失败，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才解析或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
 - **`runScenario`（harness）**：通过启动器从确定性 `input.json` 脚本驱动 ACP JSON-RPC stdio，将原始 stdout tee 给预期输出和纯度检查，并在优雅 stdin EOF 后收集每个持久化原始 JSONL 会话日志（父级和 subagent 子级，主级优先）。`AgentUnderTest` 提供绝对 `binScript`、可选 `libBinScript`、`configPath` 和 `tsconfigPath` 路径，因为子进程 cwd 位于仓库外。当生成子级 cwd 自身位于待测授权中时，`workspaceParent` 可以将它从平台临时目录移出。启动失败会在拒绝诊断中保留已捕获 agent stderr。
-- **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每个原生/JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名 → `{{cwd}}`，手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）和 `scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
+- **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每个原生/JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名 → `{{cwd}}`，手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，将已提交 UUID 带入未变化且无歧义的消息）。
 - **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新写入 fixture 前，如果一条未变化的完整消息去除身份后的值在场景的父级/子级日志中恰好对应一个本次生成的 ID 和一个现有 ID，它就会保留已提交的 UUID；新增、发生变化和有歧义的消息则保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用规范化后等价的叶值；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件是有序主级/子级清单；场景表不重复其数量。必须在 vitest 收集时调用。
 
 签入仓库的会话 fixture 使用规范打包行。合并此契约的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
@@ -59,7 +59,7 @@ defineAcpSnapshotSuite({
 
 示例还发布 `cordis.snapshot.yml` 回放 overlay，位于 `cordis.yml` 旁边（bin 在 `DSH_SNAPSHOT=replay` 下交换它们，见[单源回放配置 Agent Note](../../../.agents/notes/archived/testing/2026-07-04-single-source-acp-replay-config.md)）；回放 fixture 由 [`dsh-llm-replay`](../llm-replay/README.md) 提供，该包通过对子级设置的 `DSH_SNAPSHOT_*` env var 指向它。`pnpm run test:snapshot:record` 调用实时 LLM，并重写已记录场景的模型 fixture；`pnpm run test:snapshot:refresh` 保持无密钥，运行回放 overlay，并从已提交模型脚本重写 stdout、可比较会话日志预期输出，以及各 pin 自有的提示词与工具 schema sidecar。Fixture 角色、录制/回放/刷新语义和场景表字段记录在 `Scenario` 以及[快照 Agent Note](../../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md) 中。
 
-约束：`suite.ts` 与 `harness.ts` 导入 vitest（harness 通过 `vi.waitFor` 轮询其持久边界等待），因此包入口只能在 vitest 运行中导入（启动器和规范化器没有此依赖，但从同一入口发布）。启动器和套件工厂按设计专用于 ACP，启动器使用 SDK 的 `ClientSideConnection`；规范化器是与传输无关的会话日志/文本辅助工具，还由 TUI 快照套件和 web 浏览器 e2e lane 消费。输入脚本覆盖初始化、新建会话、文本提示、取消、预期 RPC 失败和持久轮次边界等待。权限往返是选项类别选择（`allow_once`、`reject_once`等）的 FIFO 队列，映射到 agent 发出的 `optionId`；缺少或耗尽的队列回答 `cancelled`，未提供类别会拒绝运行。
+约束：`suite.ts` 与 `harness.ts` 导入 vitest（harness 通过 `vi.waitFor` 轮询其持久边界等待），因此包入口只能在 vitest 运行中导入（启动器和规范化器没有此依赖，但从同一入口发布）。启动器和套件工厂按设计专用于 ACP，启动器使用 SDK 的 `ClientSideConnection`；规范化器是与传输无关的会话日志/文本辅助工具，还由 JSON-RPC、TUI 和 web 快照录制器消费。输入脚本覆盖初始化、新建会话、文本提示、取消、预期 RPC 失败和持久轮次边界等待。权限往返是选项类别选择（`allow_once`、`reject_once`等）的 FIFO 队列，映射到 agent 发出的 `optionId`；缺少或耗尽的队列回答 `cancelled`，未提供类别会拒绝运行。
 
 ## 模型体验
 
diff --git a/packages/support/acp-snapshot/src/index.ts b/packages/support/acp-snapshot/src/index.ts
index 09d05031c7..6d8f5c0953 100644
--- a/packages/support/acp-snapshot/src/index.ts
+++ b/packages/support/acp-snapshot/src/index.ts
@@ -46,6 +46,7 @@ export {
 export {
   defineAcpSnapshotSuite,
   refreshFixtureReplacements,
+  stabilizeFixtureMessageIds,
   stabilizeRefreshLog,
   type Scenario,
   type SnapshotSuiteOptions,
diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts
index 8a99bc0813..315095cc10 100644
--- a/packages/support/acp-snapshot/src/suite.ts
+++ b/packages/support/acp-snapshot/src/suite.ts
@@ -554,8 +554,8 @@ function uniqueMessageIds(logs: readonly string[]): Map<string, string | undefin
  * Match unchanged complete messages across a scenario's fresh and existing logs.
  * New, changed, repeated, or otherwise ambiguous messages keep their fresh ids.
  */
-function fixtureMessageIdReplacements(logs: HarvestedLog[], fixtures: string[]): FixtureReplacement[] {
-  const freshIds = uniqueMessageIds(logs.map(log => log.content))
+function fixtureMessageIdReplacements(logs: readonly string[], fixtures: readonly string[]): FixtureReplacement[] {
+  const freshIds = uniqueMessageIds(logs)
   const existingIds = uniqueMessageIds(fixtures)
   const replacements: FixtureReplacement[] = []
   for (const [fingerprint, fresh] of freshIds) {
@@ -573,6 +573,18 @@ function applyFixtureReplacements(content: string, replacements: readonly Fixtur
   return stable
 }
 
+/**
+ * Carry committed UUIDs into unchanged, unambiguous messages in fresh session fixtures.
+ *
+ * @param logs Fresh fixture-ready session JSONL contents for one scenario.
+ * @param fixtures Existing fixture contents in matching order; missing fixtures may be empty strings.
+ * @returns The fresh contents with only reusable message UUIDs replaced.
+ */
+export function stabilizeFixtureMessageIds(logs: readonly string[], fixtures: readonly string[]): string[] {
+  const replacements = fixtureMessageIdReplacements(logs, fixtures)
+  return logs.map(log => applyFixtureReplacements(log, replacements))
+}
+
 /** One packed row's member times, or `undefined` for an ordinary record. */
 function packedTimes(record: Record<string, unknown>): number[] | undefined {
   if (!PACKED_CHUNK_ROW_TYPES.has(record.type as string)) return undefined
@@ -626,7 +638,7 @@ export function unknownToolCallIds(rawLog: string): string[] {
  * @returns Literal replacements from fresh values to the fixture's existing values.
  */
 export function refreshFixtureReplacements(logs: HarvestedLog[], fixtures: string[]): FixtureReplacement[] {
-  const replacements = fixtureMessageIdReplacements(logs, fixtures)
+  const replacements = fixtureMessageIdReplacements(logs.map(log => log.content), fixtures)
   for (let i = 0; i < logs.length; i++) {
     const fresh = parseJsonlRecords((logs[i] as HarvestedLog).content)[0]
     const existing = parseJsonlRecords(fixtures[i] ?? '')[0]
@@ -1111,23 +1123,22 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
             const path = join(dir, file)
             return existsSync(path) ? readFile(path, 'utf8') : ''
           }))
-          const replacements = REFRESHING
+          const refreshReplacements = REFRESHING
             ? refreshFixtureReplacements(result.sessionLogs, existingFixtures)
-            : fixtureMessageIdReplacements(result.sessionLogs, existingFixtures)
-          const primary = (result.sessionLogs[0] as HarvestedLog).content
-          await writeFile(join(dir, outputFixtureFiles[0] as string), scrub(portableFixture(
-            REFRESHING
-              ? stabilizeRefreshLog(primary, existingFixtures[0] as string, replacements, ctx)
-              : applyFixtureReplacements(primary, replacements),
-          )))
-          for (let i = 1; i < result.sessionLogs.length; i++) {
-            const child = (result.sessionLogs[i] as HarvestedLog).content
-            await writeFile(join(dir, outputFixtureFiles[i] as string), scrub(portableFixture(
-              REFRESHING
-                ? stabilizeRefreshLog(child, existingFixtures[i] as string, replacements, ctx)
-                : applyFixtureReplacements(child, replacements),
-            )))
-          }
+            : []
+          const outputFixtures = REFRESHING
+            ? result.sessionLogs.map((log, index) => scrub(portableFixture(stabilizeRefreshLog(
+              log.content,
+              existingFixtures[index] as string,
+              refreshReplacements,
+              ctx,
+            ))))
+            : stabilizeFixtureMessageIds(
+              result.sessionLogs.map(log => scrub(portableFixture(log.content))),
+              existingFixtures,
+            )
+          await Promise.all(outputFixtures.map((fixture, index) =>
+            writeFile(join(dir, outputFixtureFiles[index] as string), fixture)))
           if (RECORDING) {
             const outputNames = new Set(outputFixtureFiles)
             const entries = await readdir(dir, { withFileTypes: true })
diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts
index 2cd665f540..e2e4129a5b 100644
--- a/packages/support/acp-snapshot/tests/suite.spec.ts
+++ b/packages/support/acp-snapshot/tests/suite.spec.ts
@@ -4,7 +4,12 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, describe, expect, it } from 'vitest'
-import { defineAcpSnapshotSuite, type HarvestedLog, type Scenario } from '../src/index.ts'
+import {
+  defineAcpSnapshotSuite,
+  stabilizeFixtureMessageIds,
+  type HarvestedLog,
+  type Scenario,
+} from '../src/index.ts'
 import {
   assertUniqueSnapshotContents,
   claimSharedSnapshot,
@@ -635,6 +640,36 @@ describe('unknownToolCallIds', () => {
   })
 })
 
+describe('stabilizeFixtureMessageIds', () => {
+  it('reuses one committed message UUID across fixture-ready parent and child logs', () => {
+    const freshId = '11111111-1111-4111-8111-111111111111'
+    const existingId = '22222222-2222-4222-8222-222222222222'
+    const log = (session: string, id: string): string => [
+      JSON.stringify({ type: 'session', id: session, cwd: '{{cwd}}' }),
+      JSON.stringify({
+        type: 'user/message',
+        data: { role: 'user', content: [{ type: 'text', text: 'same' }], source: { kind: 'user' }, id },
+      }),
+      '',
+    ].join('\n')
+    const fresh = [log('fresh-parent', freshId), log('fresh-child', freshId)]
+    const existing = [log('old-parent', existingId), log('old-child', existingId)]
+
+    const stable = stabilizeFixtureMessageIds(fresh, existing)
+
+    expect(stable).toHaveLength(2)
+    for (const fixture of stable) {
+      expect(fixture).toContain(`"id":"${existingId}"`)
+      expect(fixture).not.toContain(freshId)
+    }
+  })
+
+  it('leaves fresh fixtures unchanged when no committed counterpart exists', () => {
+    const fresh = '{"type":"session","id":"new"}\n'
+    expect(stabilizeFixtureMessageIds([fresh], [''])).toEqual([fresh])
+  })
+})
+
 describe('refreshFixtureReplacements', () => {
   it('maps fresh ids and cwd values to the existing fixture values, skipping non-replacements', () => {
     const log = (content: string): HarvestedLog => ({ id: 'diagnostic', createdAt: 1, content })

From 00390ae851b838c50e981049156d1a54b8176ce2 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <zzy211851@gmail.com>
Date: Fri, 31 Jul 2026 12:07:43 -0700
Subject: [PATCH 006/516] feat(web): open a produced file from the conversation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Serve one file at a time out of a Session's workspace under /f on the web
transport, and point the conversation's existing file-open affordance at it.
Clicking a write/edit/read row's path now opens that file in a browser tab —
including from a LAN client, where the Host's system opener is fenced to
loopback and answered nothing.

- /f/<sessionId>/<segments> in client-connection, behind the same
  browser-trust fence as /api; realpath confinement, streamed reads,
  GET/HEAD only, nosniff + no-store.
- Script-capable documents carry CSP sandbox: model-authored markup must not
  be same-origin with /api, where events.mux is a readable GET stream.
- ApiProxy.workspaceRootOf answers where a Session's files live without
  resuming an agent; the client program cannot reach the core services.
- The /f URL shape lives in dsh-host-apiproxy/api so both ends share one
  encoding (client bundles may not value-import another plugin).
---
 ...6-07-31-web-workspace-file-links.i18n.yaml |   6 +
 .../2026-07-31-web-workspace-file-links.md    |  38 ++++
 .../2026-07-31-web-workspace-file-links.zh.md |  38 ++++
 apps/web/tests/workspace-file-open.e2e.ts     |  92 ++++++++++
 apps/web/tsconfig.json                        |   3 +-
 docs/config-catalog.md                        |   2 +-
 packages/client/connection/README.i18n.yaml   |   4 +-
 packages/client/connection/README.md          |   8 +-
 packages/client/connection/README.zh.md       |   8 +-
 .../client/connection/src/client/fixture.ts   |   5 +
 packages/client/connection/src/index.ts       |  44 ++++-
 .../client/connection/src/workspace-files.ts  | 169 ++++++++++++++++++
 .../client/connection/tests/node-half.spec.ts |  78 +++++++-
 .../connection/tests/workspace-files.spec.ts  | 134 ++++++++++++++
 .../runtime/src/client/contract/workspaces.ts |  11 ++
 .../runtime/src/client/workspaces/service.ts  |  14 ++
 .../runtime/tests/workspaces-service.spec.ts  |  15 ++
 .../client/test-runtime/src/workspaces.ts     |  17 ++
 .../test-runtime/tests/runtime.spec.tsx       |   9 +-
 .../ui-conversation/src/client/apply.ts       |   9 +
 .../tests/apply-inject.spec.tsx               |  13 +-
 .../tests/chat-code-subcalls.spec.tsx         |   5 +-
 .../tests/chat-toolview-slot.spec.tsx         |   6 +-
 packages/host/apiproxy/README.i18n.yaml       |   4 +-
 packages/host/apiproxy/README.md              |   2 +
 packages/host/apiproxy/README.zh.md           |   2 +
 packages/host/apiproxy/src/api-proxy.ts       |  11 ++
 packages/host/apiproxy/src/api/files.ts       |  98 ++++++++++
 packages/host/apiproxy/src/api/index.ts       |  18 ++
 packages/host/apiproxy/src/index.ts           |   2 +
 .../tests/api-proxy-workspace.spec.ts         |  32 +++-
 .../apiproxy/tests/client-handler.spec.ts     |   2 +
 .../host/apiproxy/tests/fetch-carrier.spec.ts |   2 +
 .../host/apiproxy/tests/files-path.spec.ts    |  74 ++++++++
 tsconfig.host.json                            |   1 +
 35 files changed, 946 insertions(+), 30 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
 create mode 100644 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
 create mode 100644 apps/web/tests/workspace-file-open.e2e.ts
 create mode 100644 packages/client/connection/src/workspace-files.ts
 create mode 100644 packages/client/connection/tests/workspace-files.spec.ts
 create mode 100644 packages/host/apiproxy/src/api/files.ts
 create mode 100644 packages/host/apiproxy/tests/files-path.spec.ts

diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
new file mode 100644
index 0000000000..2055af6cea
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.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-31-web-workspace-file-links.md
+2026-07-31-web-workspace-file-links.md: b7fd5ca240db3ca885e89f4cf6dcc135e7c88de8
+2026-07-31-web-workspace-file-links.zh.md: 74949afe0260d2d9018691740573ff24a1bce820
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
new file mode 100644
index 0000000000..b7fd5ca240
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
@@ -0,0 +1,38 @@
+# Agent Note: opening a produced file from the web UI
+
+Status: implemented
+
+English | [中文](2026-07-31-web-workspace-file-links.zh.md)
+
+> Scope: the `/f` workspace-file route on the web transport, the `IWorkspaces.fileUrl` derivation behind it, and the conversation's file-open affordance switching to it. Not in scope: an artifact registry, versioning, live reload, or any model-facing declaration.
+
+## Problem
+
+A web session that produced a file had no way to look at it. The agent wrote `deepseek-homepage.html`, said so, and the user's only recourse was to copy an absolute path like `/private/tmp/dsh-client-hotplug.ygPvsm/workspaces/plugin-hotplug/deepseek-homepage.html` into a terminal.
+
+The parts were nearly all present, pointed at the wrong target. `ToolRow` already renders a mutation or read row's path as a real button, `ui-conversation` already routes its click through `openFile`, and `workspaces.openPath` already carries it to the Host's system opener. But that opener runs on the Host machine, and `host.openPath` is loopback-pinned by the `/api` trust fence, so the affordance answered nothing for a browser reached over the LAN and was invisible even locally (the path styled as plain text, underlined only on hover). Meanwhile `MarkdownText` strips every non-`http(s)` URL, so a path the model wrote into its closing message could never become a link at all, and `ToolCallView.locations` — the follow-along vocabulary the file tools already populate — had no consumer in the client.
+
+## Decision
+
+**One prefix route on the transport that already exists, not a new capability.** `client-connection` owns both browser-facing prefixes: `/api` for RPC and `/f/<sessionId>/<segments…>` for workspace-file reads. It was already the package holding `httpServer`, the `trustedHosts` config, and the browser-trust fence; a separate package would have duplicated the fence and the config, and forced `AppCLIEntry` to patch two rows for one `--trusted-host` flag. The webserver's own contract — every feature surface is a route some other plugin registers — makes the route the whole mechanism. Segments ride the path rather than a query parameter so a served document's relative references resolve to its siblings.
+
+**The request names a Session; the gateway names the authority.** `ApiProxy.workspaceRootOf` answers where a Session's files live — a live agent's `session.header.cwd` first, then the persistence store, never a resume — as a second, non-envelope face of the `cwd` the session summaries already carry. The route reads that instead of `ctx.agents` directly, because `client-connection` is registered in the client program and importing the core service packages merges their host-side `sessions: SessionStore` declaration over the browser runtime's own `sessions: SessionsService` — the collision `tsconfig.host.json`/`tsconfig.client.json` exist to prevent. Both the cwd and the resolved target go through `realpath` before the prefix comparison, so a workspace-internal symlink pointing outward is refused by its target; traversal spellings are refused at parse time, before any filesystem call. Reads stream through `pipeline`, so a client that goes away destroys the descriptor and no request ever buffers a file.
+
+**The URL shape lives in `dsh-host-apiproxy/api`, with the other browser-importable contract surfaces.** Both ends must agree on one encoding, but a client bundle may not value-import another plugin's package: the purity gate in `packages/client/tsdown.client.ts` allows only platform modules and the `INLINE_SAFE` wire layers, of which apiproxy is one. Putting `api/files.ts` there is what lets the browser half build a URL and the serving half parse it from a single source, and it needed no new package edge — both sides already depend on apiproxy.
+
+**Model-authored documents are served into an opaque origin.** `.html`/`.htm`/`.xhtml`/`.svg` carry `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`. Serving generated markup same-origin with `/api` would put `/api/events.mux` — a readable `GET` stream — one `window.open` away from a page the model wrote. The sandbox costs the preview its `localStorage`, cookies, and same-origin `fetch`; `host.openPath` stays as the full-capability way to open the same file on the Host machine, so the trade is resolved by keeping both affordances rather than by weakening either.
+
+**The client decides by derivation, not by probing.** `IWorkspaces.fileUrl(sessionId, cwd, path)` expresses a tool-reported path as segments below the session cwd and returns the origin-relative URL, or `undefined` when the path leaves the workspace. `undefined` is exactly the signal to fall back to `openPath`, so a file outside the workspace behaves as it did before and no capability negotiation is needed.
+
+## Alternatives considered
+
+- **The artifact capability family (RFC #268 / PR #272)** — a seam with ids, versions, snapshot storage, its own HTTP server, SSE live reload, and a browser auto-opener. Its review found seven critical issues, and every one of them came from that machinery: an unlistened opener spawn crashing the harness, the opener inheriting `DEEPSEEK_API_KEY`, in-flight publishes outliving disposal, `readFile` preceding the size cap, a snapshot TOCTOU, and retention leaking with undisposed agents. `dsh web` already runs an HTTP server and the user is already in a browser, so none of that machinery buys anything here. The RFC and its tests stay as the input for the day a real cross-session or versioned-artifact need appears; this route is that seam's natural mount point when it does.
+- **A dedicated `dsh-client-workspace-files` package** — the honest seam shape if file serving were an independent capability. It is not: it needs the same fence and the same `trustedHosts` value as `/api`, and splitting would have duplicated both against the repository's own "don't split preemptively" rule.
+- **Keeping the URL-shape module in `client-connection` and importing it from the runtime** — the first cut, and the build refused it: a cross-plugin value import into a client bundle either inlines a duplicate runtime instance or names a specifier the frozen module table cannot answer. The gate is the reason the shared module sits in the wire layer rather than in the package that happens to own the route.
+- **`/f/<absolute path>`, so `openPath` could stay the single call site** — drops the sessionId from the URL, but then the served authority becomes the union of every workspace the host knows. The tight authority costs exactly one call-site edit, because `openFile` already has both the sessionId and the cwd in scope.
+- **`connect-src 'none'` instead of `sandbox`, to keep `localStorage` working** — blocks `fetch`/`EventSource` but not `window.open('/api/events.mux')`, which is readable same-origin. The two GET SSE endpoints are what make the sandbox necessary rather than optional.
+- **Linkifying paths in the assistant's closing message** — the shape a user asks for ("put the link at the end"), but it makes rendering depend on the model spelling a path recognizably. The tool calls already carry `locations` as structured fact; consuming that is the reliable source and is left as the follow-up this route unblocks.
+
+## Consequences
+
+Every existing file affordance changed target at once: write, edit, read, and the generic single-file card all reach `openFile`, so one call-site edit made produced files openable in the browser, LAN clients included. Three tests asserting the old `openPath` destination were rewritten to the new one; the outside-workspace fallback keeps the old assertion. The route is covered against a real HTTP server and a real temporary workspace, because confinement, content typing, and the sandbox header are wire facts, and the assembled web lane (`apps/web/tests/workspace-file-open.e2e.ts`, keyless over a cold-seeded session) proves the product path: clicking a read row's path opens `/f/<sessionId>/a.txt` in a second tab serving that workspace file, while a traversal spelling answers 404. `localStorage` is unavailable inside a preview, which is visible on generated pages that persist a theme toggle — the Host opener remains for those. Still deferred: the end-of-turn deliverable row derived from `locations`, and any linkification inside assistant Markdown.
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
new file mode 100644
index 0000000000..74949afe02
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -0,0 +1,38 @@
+# Agent Note：从 web UI 打开产出的文件
+
+Status: implemented
+
+[English](2026-07-31-web-workspace-file-links.md) | 中文
+
+> 范围：web 传输层上的 `/f` 工作区文件路由、其背后的 `IWorkspaces.fileUrl` 推导，以及会话中打开文件的交互改指向它。不在范围内：产物注册表、版本、实时重载，或任何面向模型的声明。
+
+## 问题
+
+一个产出了文件的 web 会话，没有办法看到那个文件。agent 写出了 `deepseek-homepage.html` 并如实告知，而用户唯一的办法是把 `/private/tmp/dsh-client-hotplug.ygPvsm/workspaces/plugin-hotplug/deepseek-homepage.html` 这样的绝对路径复制进终端。
+
+零件几乎都在，只是指错了目标。`ToolRow` 早已把改写行或读取行的路径渲染成一个真正的按钮，`ui-conversation` 早已把它的点击经由 `openFile` 转发，`workspaces.openPath` 也早已把它送到 Host 的系统打开器。但那个打开器运行在 Host 机器上，而 `host.openPath` 被 `/api` 信任 fence 钉在回环，所以这个交互对经 LAN 访问的浏览器什么都答不了，即便在本机也是隐形的（路径的样式就是普通文本，只有 hover 时才有下划线）。与此同时 `MarkdownText` 会剥掉每一个非 `http(s)` 的 URL，因此模型写进收尾消息里的路径根本不可能成为链接；而 `ToolCallView.locations`——文件工具早已填好的跟随文件词汇——在客户端没有任何消费方。
+
+## 决定
+
+**在已有的传输层上加一条前缀路由，而不是加一项能力。** `client-connection` 持有两条面向浏览器的前缀：`/api` 承载 RPC，`/f/<sessionId>/<segments…>` 承载工作区文件读取。它本来就是持有 `httpServer`、`trustedHosts` 配置和浏览器信任 fence 的那个包；单开一个包会把 fence 和配置各复制一份，并逼着 `AppCLIEntry` 为一个 `--trusted-host` 标志去 patch 两行。webserver 自己的契约——每个特性面都是别的插件注册的一条路由——让这条路由本身就是全部机制。段落走路径而非查询参数，是为了让所服务文档的相对引用能解析到它的同级文件。
+
+**请求指名 Session，由网关指名权限边界。** `ApiProxy.workspaceRootOf` 回答某个 Session 的文件位于何处——先看活跃 agent 的 `session.header.cwd`，再看持久化存储，绝不恢复会话——它是会话摘要早已携带的那个 `cwd` 的第二副面孔，只是不带信封。路由读取它而不是直接够 `ctx.agents`，因为 `client-connection` 注册在 client 程序里，而引入核心服务包会把它们 host 侧的 `sessions: SessionStore` 声明盖到浏览器运行时自己的 `sessions: SessionsService` 之上——这正是 `tsconfig.host.json`／`tsconfig.client.json` 分立所要防的那种冲突。cwd 与解析出的目标在前缀比较前都要过 `realpath`，因此工作区内指向工作区外的符号链接会因其目标而被拒绝；穿越写法在解析期就被拒，早于任何文件系统调用。读取经 `pipeline` 流出，因此客户端离开即销毁描述符，任何请求都不会把文件缓冲起来。
+
+**URL 形状落在 `dsh-host-apiproxy/api`，与其余浏览器可导入的契约面同处一地。** 两端必须就同一套编码达成一致，但客户端 bundle 不允许值导入另一个插件的包：`packages/client/tsdown.client.ts` 里的纯度 gate 只放行平台模块与 `INLINE_SAFE` 协议层，而 apiproxy 正是其中之一。把 `api/files.ts` 放在那里，才使构造 URL 的浏览器半侧与解析它的服务半侧共用单一来源，而且没有新增任何包依赖边——两侧本来就依赖 apiproxy。
+
+**模型撰写的文档被送进不透明源。** `.html`／`.htm`／`.xhtml`／`.svg` 会带上 `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`。若把生成的标记与 `/api` 同源提供，`/api/events.mux`——一条可读的 `GET` 流——离模型写的页面就只有一次 `window.open` 之遥。sandbox 让预览失去 `localStorage`、cookie 与同源 `fetch`；`host.openPath` 作为在 Host 机器上以完整能力打开同一文件的方式保留下来，因此这个取舍是靠同时保留两个交互解决的，而不是靠削弱其中之一。
+
+**客户端靠推导决定，而不是靠探测。** `IWorkspaces.fileUrl(sessionId, cwd, path)` 把工具报告的路径表达为 session cwd 之下的段落并返回相对于源的 URL，路径离开工作区时返回 `undefined`。`undefined` 恰好就是回退到 `openPath` 的信号，因此工作区外的文件行为与以往一致，也不需要任何能力协商。
+
+## 考虑过的替代方案
+
+- **产物能力族（RFC #268 / PR #272）**——一条带 id、版本、快照存储、自有 HTTP 服务器、SSE 实时重载与浏览器自动打开器的 seam。它的评审给出了七个 critical，而每一个都来自那套机械结构：未监听的打开器 spawn 会让 harness 崩溃、打开器继承 `DEEPSEEK_API_KEY`、进行中的 publish 活过 dispose、`readFile` 先于大小上限、快照的 TOCTOU，以及未 dispose 的 agent 导致保留期泄漏。`dsh web` 本来就跑着一个 HTTP 服务器，用户本来就在浏览器里，那套机械结构在这里买不到任何东西。RFC 与其测试保留下来，作为真正出现跨会话或版本化产物需求那天的输入；届时这条路由就是那条 seam 的天然挂载点。
+- **单开一个 `dsh-client-workspace-files` 包**——如果文件服务是一项独立能力，这才是诚实的 seam 形状。它不是：它需要与 `/api` 相同的 fence 和相同的 `trustedHosts` 值，拆分会把两者都复制一份，违背仓库自己的“不要预先拆分”。
+- **把 URL 形状模块留在 `client-connection` 里、由 runtime 去导入**——最初就是这么写的，构建直接拒绝：向客户端 bundle 做跨插件值导入，要么内联出一份重复的运行时实例，要么落到冻结模块表答不出的说明符上。这道 gate 正是共享模块落在协议层、而非落在恰好持有该路由的那个包里的原因。
+- **`/f/<绝对路径>`，好让 `openPath` 保持为唯一调用点**——这会把 sessionId 从 URL 里去掉，但所服务的权限边界随之变成 host 已知的全部工作区之并集。紧的权限边界只花掉一处调用点的改动，因为 `openFile` 本来就同时持有 sessionId 与 cwd。
+- **用 `connect-src 'none'` 代替 `sandbox`，以保住 `localStorage`**——它挡得住 `fetch`／`EventSource`，挡不住 `window.open('/api/events.mux')`，而后者是同源可读的。正是那两个 GET SSE 端点让 sandbox 成为必需而非可选。
+- **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带；消费它才是可靠来源，作为这条路由解锁的后续留下。
+
+## 影响
+
+现有的每一处文件交互都同时换了目标：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此一处调用点的改动就让产出的文件在浏览器里可打开，LAN 客户端也在内。三个断言旧 `openPath` 去向的测试被改写为新的去向；工作区外的回退保留了旧断言。这条路由对着真实 HTTP 服务器与真实临时工作区做覆盖，因为收敛、内容定型与 sandbox 头都是协议事实；而组装后的 web 通道（`apps/web/tests/workspace-file-open.e2e.ts`，在冷播种会话上无密钥运行）证明了产品路径：点击读取行的路径会在第二个标签页打开 `/f/<sessionId>/a.txt` 并提供那个工作区文件，而穿越写法应答 404。预览中无法使用 `localStorage`，这在会持久化主题切换的生成页面上是看得见的——那些场景仍有 Host 打开器。仍然暂缓：由 `locations` 推导的回合末交付物行，以及助手 Markdown 内部的任何链接化。
diff --git a/apps/web/tests/workspace-file-open.e2e.ts b/apps/web/tests/workspace-file-open.e2e.ts
new file mode 100644
index 0000000000..63d4266cf4
--- /dev/null
+++ b/apps/web/tests/workspace-file-open.e2e.ts
@@ -0,0 +1,92 @@
+// Web e2e scenario: clicking a tool row's file path opens that file in a new
+// browser tab, served by the web transport's own /f route. Cold-seeds the
+// seeded-history fixture (zero model calls). The surface package tests can
+// assert which opener the click reaches, but only the assembled application
+// proves the opened URL actually serves the workspace file — the whole point
+// of the route (docs/testing.md snapshot rule).
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import {
+  fixtureUserPrompts, launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+// Borrowed read-only: this scenario needs any settled turn whose tool rows
+// carry a workspace file path, not a new recording (message-actions pattern).
+const SEED = fileURLToPath(new URL('./snapshots/seeded-history/seed.jsonl', import.meta.url))
+const MODE = webSnapshotMode()
+const SEED_ID = 'workspace-file-open-web-e2e'
+
+const PROMPT = 'Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop.'
+
+describe('web e2e: opening a workspace file from a tool row', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    // The seeded Session's cwd is the scaffold workspace itself; the recording's
+    // own nested directory is written too, so the seed's paths stay resolvable.
+    await mkdir(join(scaffold.workspaceCwd, 'workspace'), { recursive: true })
+    for (const dir of [scaffold.workspaceCwd, join(scaffold.workspaceCwd, 'workspace')]) {
+      await writeFile(join(dir, 'a.txt'), 'alpha\n')
+      await writeFile(join(dir, 'b.txt'), 'beta\n')
+    }
+    const raw = await readFile(SEED, 'utf8')
+    expect(fixtureUserPrompts(raw), 'borrowed seed must carry the drive prompt').toEqual([PROMPT])
+    await seedSession(scaffold, raw, SEED_ID)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it.skipIf(MODE === 'record')('opens the read row’s file in a new tab, served from the session workspace', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-workspace-file-open'))
+    const groupRow = page.locator('[role="treeitem"]').first()
+    await groupRow.waitFor({ timeout: 15_000 })
+    await groupRow.click()
+    const sessionRow = page.locator('[role="treeitem"]').nth(1)
+    await sessionRow.waitFor({ timeout: 10_000 })
+    await sessionRow.click()
+    await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBe(1)
+
+    // The row summary IS the link: a button whose label is the tool's path.
+    const fileLink = page.getByRole('button', { name: 'a.txt', exact: true }).first()
+    await fileLink.waitFor({ timeout: 10_000 })
+    const [opened] = await Promise.all([
+      page.context().waitForEvent('page', { timeout: 15_000 }),
+      fileLink.click(),
+    ])
+    await opened.waitForLoadState('domcontentloaded')
+    expect(new URL(opened.url()).pathname).toBe(`/f/${SEED_ID}/a.txt`)
+    expect(await opened.locator('body').innerText()).toContain('alpha')
+
+    // The served response is a workspace read, not a download, and never cached
+    // past the turn that produced it.
+    const served = await page.request.get(opened.url())
+    expect(served.status()).toBe(200)
+    expect(served.headers()['x-content-type-options']).toBe('nosniff')
+    expect(served.headers()['cache-control']).toBe('no-store')
+
+    // Nothing outside the Session's workspace is reachable through the route.
+    const escape = await page.request.get(`${scaffold.baseUrl}/f/${SEED_ID}/..%2Fetc%2Fhosts`)
+    expect(escape.status()).toBe(404)
+
+    await opened.close()
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  }, 90_000)
+})
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index c795dc7aef..2c65f1e510 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -50,7 +50,8 @@
     "tests/permission-policy-context.e2e.ts",
     "tests/access-confirmation.e2e.ts",
     "tests/shipped-composition.e2e.ts",
-    "tests/startup-auto-selection.e2e.ts"
+    "tests/startup-auto-selection.e2e.ts",
+    "tests/workspace-file-open.e2e.ts"
   ],
   "references": [
     {
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a356a151e3..114e2bdb35 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -296,7 +296,7 @@ export interface ConnectionConfig {
 }
 ```
 
-Source: [`packages/client/connection/src/index.ts:20`](../packages/client/connection/src/index.ts)
+Source: [`packages/client/connection/src/index.ts:26`](../packages/client/connection/src/index.ts)
 
 ## `@deepseek-ai/dsh-client-hmr`
 
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 974e3014d6..101d8fd61b 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
-README.md: c8b7c4787cbcbf6a202fb944459a589fcadd7c8d
-README.zh.md: 693420183ffa4fb20e1fecbff523a12261a45d45
+README.md: 9a08cb4de5531b044bd411ea08595c22f88e5f8a
+README.zh.md: cfc427945f42b61288f57f5ca1db9af74dbcfb31
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index c8b7c4787c..9a08cb4de5 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,12 +2,18 @@
 
 English | [中文](README.zh.md)
 
-Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`, reads included, since describing returns the exposed configuration and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. Contract: api-contracts v3 §3.
+Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The node half owns both browser-facing prefixes — `/api` for RPC and `/f` for workspace-file reads — behind one trust fence. The `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`, reads included, since describing returns the exposed configuration and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. Contract: api-contracts v3 §3.
 
 ## /api browser-trust fence
 
 The node half guards every request under `/api` before bridging (`src/api-request-trust.ts`). Every request — browser-marked or not — must present a `Host` that is a loopback authority or matches a `trustedHosts` entry: exact on `host:port` entries, any port on port-less entries, both sides compared through WHATWG normalization (DNS-rebinding defense). There is deliberately no shortcut for requests without browser markers: over plain HTTP a browser attaches neither `Origin` nor Fetch-Metadata to reads (EventSource, images, navigations — those headers go only to trustworthy destinations), so an unmarked request may still be a rebound browser read with a readable response, and Host is the one header rebinding cannot forge; non-browser clients pass the same fence via loopback, the CLI-derived LAN IP literals, or a declared authority. When markers are present, an attached `Origin` must equal the Host authority, and an explicit `sec-fetch-site: cross-site` marker is refused. A `trustedHosts` entry that is not a bare, canonical `host[:port]` authority — one WHATWG parsing reads back exactly as written — fails the plugin load loudly: parsing would otherwise quietly authorize the hostname inside `harness.internal/path`, or broaden a dangling-colon or zero-padded port to an any-port grant. Failures answer plain 403 before any RPC dispatch. A non-loopback (`--host 0.0.0.0`) deployment therefore needs its serving authorities trusted: the dsh CLI derives the machine's LAN IP literals itself and its `--trusted-host` flag declares named ones, so `trustedHosts` in cordis.yml is for compositions the CLI does not boot. The fence is deliberately not an authentication layer — reachability policy stays with the webserver binding, and auth remains deferred work. Decision record: [the api browser-trust boundary Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md).
 
+## /f workspace-file reads
+
+The node half also serves one file at a time out of a Session's workspace under `/f/<sessionId>/<segments…>`, so a produced deliverable is reachable from the page that reported it — an `http` page cannot follow a `file://` link, and a browser that is not on the Host machine has no such path anyway. The segments ride the URL rather than a query parameter so a served document's relative references resolve to its siblings. The request names a Session and the gateway names that Session's directory (`ApiProxy.workspaceRootOf`, which answers from a live agent's header or the persistence store and never resumes an agent to serve a file); this package reads the authority rather than the core services, because holding their host-side Context declarations would merge them over the browser runtime's own. The URL shape itself lives with the other browser-importable contract surfaces, in [`@deepseek-ai/dsh-host-apiproxy/api`](../../host/apiproxy/README.md), so the browser half that builds a URL and this half that parses one share a single encoding decision. Both the cwd and the resolved target go through `realpath` before comparison, so a symlink inside the workspace pointing out of it is refused by its target rather than its name; traversal spellings are refused earlier still, at parse time, before any filesystem call. Reads stream (no request buffers a file), answer `GET`/`HEAD` only, and carry `nosniff` with `no-store`. Extensions outside the served content-type table are typed `text/plain` rather than offered as a download, because a workspace read is a request to see a file.
+
+Documents that can execute script — `.html`, `.htm`, `.xhtml`, `.svg` — additionally carry `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`. Model-authored markup is served from the same origin as `/api`, where `/api/events.mux` is a readable `GET` stream, so an opaque origin is what keeps a generated page from reading the session event stream one `window.open` away. The cost is borne by the preview: `localStorage`, cookies, and same-origin `fetch` are unavailable inside it, and `host.openPath` remains the full-capability way to open the same file on the Host machine. The same trust fence gates this prefix, so a `trustedHosts` deployment serves workspace files exactly where it serves ordinary reads.
+
 ## Keyless fixture
 
 Any `fixture` query parameter selects the in-memory carrier. `fixture=empty` starts with no Workspace or Session; `fixturePrompt=reject` rejects prompts before acceptance; `fixtureAttach=fail` publishes a Session but rejects its Workspace attachment; `fixtureSessionCreate=drop-response` publishes and frames a Session before dropping the create response; and `fixtureFrames=workspace-first` reverses the default session-first create-frame order. Workspace creation by name/path and caller-preallocated SessionIds remain deterministic enough for assembled Web tests to reconcile list and frame arrival. Fixture content search preserves the production-facing `unicode61`-style case, diacritic, and token-phrase behavior and returns a match-centered snippet of at most 120 Unicode code points.
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index 693420183f..cfc427945f 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,12 +2,18 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`，读取也在内，因为 describe 会返回已暴露的配置，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。契约：api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。node 半侧持有两条面向浏览器的前缀——`/api` 承载 RPC，`/f` 承载工作区文件读取——共用同一道信任 fence。`/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`，读取也在内，因为 describe 会返回已暴露的配置，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。契约：api-contracts v3 §3。
 
 ## /api 浏览器信任栅栏
 
 node 半侧在桥接前守卫 `/api` 下的每个请求（`src/api-request-trust.ts`）。每个请求——无论是否带浏览器标记——`Host` 都必须是回环地址权威，或与某个 `trustedHosts` 条目匹配：带端口的 `host:port` 条目精确匹配，不带端口的条目匹配任意端口，两侧均经 WHATWG 归一化后比较（DNS rebinding 防御）。刻意不为无浏览器标记的请求开捷径：明文 HTTP 下浏览器的读取（EventSource、图片、导航——这些头只发给可信目标）既不带 `Origin` 也不带 Fetch-Metadata，因此无标记请求仍可能是被重绑页面发起的、响应可被读走的读取，而 Host 是重绑唯一伪造不了的请求头；非浏览器客户端经由回环地址、CLI 推导的 LAN IP 字面量或已声明的权威通过同一道栅栏。当标记存在时，`Origin` 必须与 Host 权威完全一致；显式的 `sec-fetch-site: cross-site` 标记一律拒绝。不是纯的、规范形 `host[:port]` 权威的 `trustedHosts` 条目——即 WHATWG 解析读回后与原文不完全一致的——会让插件加载大声失败：否则解析会悄悄授权 `harness.internal/path` 这类笔误里的 hostname，或把悬空冒号、补零端口放大成任意端口授权。失败在任何 RPC 分发之前以纯 403 应答。因此非回环（`--host 0.0.0.0`）部署需要让自己的服务权威被信任：dsh CLI 会自行推导本机的 LAN IP 字面量，其 `--trusted-host` flag 用于声明具名权威，所以 cordis.yml 中的 `trustedHosts` 面向 CLI 不参与引导的组合。这道栅栏刻意不承担认证职责——可达性策略归 webserver 绑定配置，认证仍是延期工作。决策记录：[api 浏览器信任边界 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md)。
 
+## /f 工作区文件读取
+
+node 半侧还会在 `/f/<sessionId>/<segments…>` 下逐个提供某个 Session 工作区里的文件，让产出的交付物能从报告它的那个页面直接抵达——`http` 页面无法跟随 `file://` 链接，而不在 Host 机器上的浏览器本来也没有那条路径。段落走 URL 而非查询参数，是为了让所服务文档的相对引用能解析到它的同级文件。请求指名一个 Session，由网关指名该 Session 的目录（`ApiProxy.workspaceRootOf`，它从活跃 agent 的 header 或持久化存储作答，绝不会为了提供一个文件而恢复 agent）；本包读取这个权威来源而不去够核心服务，因为持有它们的 host 侧 Context 声明会把它们盖到浏览器运行时自己的声明之上。URL 形状本身与其余浏览器可导入的契约面放在一起，位于 [`@deepseek-ai/dsh-host-apiproxy/api`](../../host/apiproxy/README.md)，因此构造 URL 的浏览器半侧与解析 URL 的这一半共享同一个编码决定。cwd 与解析出的目标在比较前都要过 `realpath`，因此工作区内指向工作区外的符号链接会因其目标而被拒绝，而不是因其名字；穿越写法拒得更早，在解析期、任何文件系统调用之前。读取是流式的（没有请求会把文件缓冲起来），只应答 `GET`／`HEAD`，并带上 `nosniff` 与 `no-store`。所服务的内容类型表之外的扩展名一律按 `text/plain` 定型而非作为下载给出，因为工作区读取本就是一个“让我看看这个文件”的请求。
+
+能执行脚本的文档——`.html`、`.htm`、`.xhtml`、`.svg`——还会额外带上 `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`。模型撰写的标记与 `/api` 同源提供，而 `/api/events.mux` 是一条可读的 `GET` 流，因此正是不透明源阻止了一个生成页面通过一次 `window.open` 读走会话事件流。代价由预览承担：其中无法使用 `localStorage`、cookie 与同源 `fetch`，而 `host.openPath` 仍是在 Host 机器上以完整能力打开同一文件的方式。这条前缀由同一道信任 fence 把守，因此配置了 `trustedHosts` 的部署提供工作区文件的范围，与它提供普通读取的范围完全一致。
+
 ## 无密钥 fixture
 
 任何 `fixture` 查询参数都会选择内存载体。`fixture=empty` 启动时不含 Workspace 或 Session；`fixturePrompt=reject` 在接受前拒绝提示词；`fixtureAttach=fail` 发布 Session 但拒绝将其附加到 Workspace；`fixtureSessionCreate=drop-response` 在丢弃创建响应前发布 Session 并为其发出帧；`fixtureFrames=workspace-first` 则反转默认的 Session 优先创建帧顺序。按名称／路径创建 Workspace 以及由调用方预先分配 SessionId，均具有足够的确定性，组装后的 Web 测试可以据此协调列表与帧的到达。fixture 内容搜索会保留面向生产环境的 `unicode61` 式大小写、变音符号和 token／短语行为，并返回以匹配位置为中心、最多包含 120 个 Unicode 码点的 snippet。
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 9f091b26c5..f5fa3e34ea 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2362,6 +2362,11 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       })
       return Promise.resolve({ accepted: true })
     },
+
+    // The fixture has no filesystem behind its Sessions, so it names no
+    // directory for any of them; the /f route belongs to the node half, which
+    // a fixture page never reaches.
+    workspaceRootOf: () => Promise.resolve(undefined),
   }
 }
 
diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts
index ed4af2d21f..4f9ce7d51b 100644
--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -1,11 +1,17 @@
-/** Host HTTP bridge for browser-client RPC. */
+/** Host HTTP bridge for browser-client RPC and workspace-file reads. */
 import type { Context } from 'cordis'
 import z from 'schemastery'
 // Activates the httpServer Context merge used below.
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
+// The merge-free types subpath: pulling the session package's root into this
+// client-registered program would merge the host `sessions` service over the
+// browser runtime's own.
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { API_PATH } from './api-path.ts'
 import { bridge } from './http-bridge.ts'
+import { handleWorkspaceFile } from './workspace-files.ts'
 import { assertTrustedAuthority, isTrustedApiRequest } from './api-request-trust.ts'
 
 export { API_PATH } from './api-path.ts'
@@ -13,7 +19,7 @@ export { API_PATH } from './api-path.ts'
 /** Stable Cordis plugin name. */
 export const name = 'client-connection'
 
-/** Services required before mounting the route. */
+/** Services required before mounting the routes. */
 export const inject = ['httpServer', 'apiProxy']
 
 /** Plugin config: the deployment's non-loopback serving authorities. */
@@ -61,11 +67,11 @@ const PRIVILEGED_METHODS = new Set([
 ])
 
 /**
- * Mounts the API gateway under the browser transport prefix. Every request on
- * the prefix passes the browser-trust fence first (DNS-rebinding and
- * cross-site defense — [api-request-trust](./api-request-trust.ts));
- * privileged methods additionally pass it with an empty trust list, which
- * pins them to loopback.
+ * Mounts the API gateway and the workspace-file reads under the browser
+ * transport prefixes. Every request on either prefix passes the browser-trust
+ * fence first (DNS-rebinding and cross-site defense —
+ * [api-request-trust](./api-request-trust.ts)); privileged methods
+ * additionally pass it with an empty trust list, which pins them to loopback.
  * @param ctx - Host plugin context.
  * @param config - resolved plugin config (schema defaults applied).
  */
@@ -96,4 +102,28 @@ export function apply(ctx: Context, config?: ConnectionConfig): void {
     },
   }
   ctx.effect(() => ctx.httpServer.register(route), 'client-connection: /api route')
+
+  // The gateway is the host's session authority: it answers where a Session's
+  // files live without this package reaching into the core services, which
+  // would merge their host-side Context declarations into the browser lane.
+  const cwdFor = (sessionId: string): Promise<string | undefined> =>
+    ctx.apiProxy.workspaceRootOf(sessionId as SessionId)
+  const filesRoute: WebRoute = {
+    kind: 'prefix',
+    path: FILES_PATH,
+    handler: async (req, res) => {
+      if (!isTrustedApiRequest(req, trustedHosts)) {
+        res.writeHead(403)
+        res.end('forbidden')
+        return
+      }
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405)
+        res.end()
+        return
+      }
+      await handleWorkspaceFile(req, res, { cwdFor })
+    },
+  }
+  ctx.effect(() => ctx.httpServer.register(filesRoute), 'client-connection: /f route')
 }
diff --git a/packages/client/connection/src/workspace-files.ts b/packages/client/connection/src/workspace-files.ts
new file mode 100644
index 0000000000..9ad1b830a3
--- /dev/null
+++ b/packages/client/connection/src/workspace-files.ts
@@ -0,0 +1,169 @@
+/**
+ * The read half of the web transport: streams one file out of a session's
+ * workspace so the browser can open what the agent just produced. The RPC
+ * gateway carries structured session state; this route carries bytes, which a
+ * JSON-RPC envelope cannot stream and a `file://` link cannot reach from an
+ * http page.
+ *
+ * Confinement is the whole contract: a request names a session, the session
+ * names its cwd, and nothing outside that realpath is ever served. The caller
+ * owns the browser-trust fence ([api-request-trust](./api-request-trust.ts)) —
+ * this module is reached only by requests that already passed it.
+ */
+
+import { createReadStream } from 'node:fs'
+import { realpath, stat } from 'node:fs/promises'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { extname, resolve, sep } from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import { parseWorkspaceFilePath } from '@deepseek-ai/dsh-host-apiproxy/api'
+
+/**
+ * Content types served verbatim. Everything absent is `text/plain`, not
+ * `application/octet-stream`: a workspace read is a "show me what you made"
+ * gesture, and an unknown extension is far more often a source file to read
+ * than a binary to download. `nosniff` keeps that choice binding, so a
+ * mislabelled document can never be re-interpreted as HTML.
+ */
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.xhtml': 'application/xhtml+xml',
+  '.svg': 'image/svg+xml',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.wasm': 'application/wasm',
+}
+
+const DEFAULT_MIME = 'text/plain; charset=utf-8'
+
+/** Extensions whose top-level navigation can execute script, and so need the sandbox. */
+const SCRIPTABLE = new Set(['.html', '.htm', '.xhtml', '.svg'])
+
+/**
+ * Model-authored documents run in an opaque origin. Without it a generated page
+ * is same-origin with the RPC gateway, where `/api/events.mux` is a readable
+ * GET stream — one `window.open` away from every session's events. The cost is
+ * that `localStorage`, cookies, and same-origin `fetch` are unavailable inside
+ * a preview; the native-open path (`host.openPath`) remains the full-capability
+ * way to view a file.
+ */
+const SANDBOX_CSP = 'sandbox allow-scripts allow-popups allow-modals allow-forms'
+
+/** How the route learns which directory a session may serve from. */
+export interface WorkspaceFileDeps {
+  /**
+   * The session's absolute working directory.
+   * @param sessionId - the session named by the request path.
+   * @returns its cwd, or `undefined` when the id names no session this host serves.
+   */
+  cwdFor: (sessionId: string) => Promise<string | undefined>
+}
+
+function fail(res: ServerResponse, status: number): void {
+  res.writeHead(status)
+  res.end()
+}
+
+/**
+ * Resolve one request's segments against a session cwd, refusing anything that
+ * leaves it. Both sides go through `realpath`, so a symlink inside the
+ * workspace pointing out of it is refused by its resolved target rather than
+ * its name. A component swapped between this resolution and the open below
+ * would still be followed; closing that window needs privileges that already
+ * imply workspace write access, which is strictly stronger than reading a
+ * workspace file, so the check stops here.
+ */
+async function confine(cwd: string, segments: readonly string[]): Promise<string | undefined> {
+  const root = await realpath(cwd)
+  const real = await realpath(resolve(root, ...segments))
+  return real.startsWith(root + sep) ? real : undefined
+}
+
+/**
+ * Serve one workspace-file request. The caller has already applied the
+ * browser-trust fence and rejected non-read methods.
+ * @param req - the request, read for its url and method only (no body).
+ * @param res - the response this function owns to completion.
+ * @param deps - the session-to-cwd lookup this host answers with.
+ */
+export async function handleWorkspaceFile(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: WorkspaceFileDeps,
+): Promise<void> {
+  /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server requests. */
+  const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
+  const target = parseWorkspaceFilePath(pathname)
+  if (target === undefined) {
+    fail(res, 404)
+    return
+  }
+  const cwd = await deps.cwdFor(target.sessionId)
+  if (cwd === undefined) {
+    fail(res, 404)
+    return
+  }
+
+  let file: string | undefined
+  let size: number
+  try {
+    file = await confine(cwd, target.segments)
+    if (file === undefined) {
+      fail(res, 403)
+      return
+    }
+    const info = await stat(file)
+    // A directory read has no answer here: the route serves files, and listing
+    // is the directory-picker capability's job, behind its own fence.
+    if (!info.isFile()) {
+      fail(res, 404)
+      return
+    }
+    size = info.size
+  } catch {
+    // Missing, unreadable, or a path whose ancestor is not a directory: all
+    // report as absent, so a probe cannot distinguish them.
+    fail(res, 404)
+    return
+  }
+
+  const ext = extname(file).toLowerCase()
+  res.writeHead(200, {
+    'content-type': MIME[ext] ?? DEFAULT_MIME,
+    'content-length': String(size),
+    'content-disposition': 'inline',
+    'x-content-type-options': 'nosniff',
+    // Workspace files change under the agent's hands; a cached preview would
+    // show the previous turn's output after the next edit.
+    'cache-control': 'no-store',
+    ...SCRIPTABLE.has(ext) ? { 'content-security-policy': SANDBOX_CSP } : {},
+  })
+  if (req.method === 'HEAD') {
+    res.end()
+    return
+  }
+  try {
+    // pipeline (not pipe) so a client disconnect destroys the read stream:
+    // an abandoned preview must not leave a descriptor open.
+    await pipeline(createReadStream(file), res)
+  } catch {
+    // The status line is already out, so a mid-stream read failure or client
+    // disconnect can only end the response abruptly.
+    res.destroy()
+  }
+}
diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts
index 08c65de2ba..0b2c58ab37 100644
--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -1,6 +1,9 @@
-/** Node half: registers the /api prefix route bridging to the api gateway. */
+/** Node half: registers the /api and /f prefix routes over the api gateway and the session workspaces. */
 import { EventEmitter } from 'node:events'
 import { createServer, request as httpRequest } from 'node:http'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { Readable } from 'node:stream'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
@@ -8,6 +11,7 @@ import type { AddressInfo } from 'node:net'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { HttpServerService, WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { API_PATH, apply, inject } from '../src/index.ts'
 
 /** Structural httpServer fake: the plugin only touches register(). */
@@ -45,31 +49,45 @@ function fakeResponse(): { response: ServerResponse; state: { status?: number; b
   return { response, state }
 }
 
-async function mounted(config?: { trustedHosts?: string[] }): Promise<{ routes: WebRoute[]; dispose: () => Promise<void> }> {
+/** The gateway stub: only the session-directory authority the /f route reads. */
+function fakeApiProxy(workspaces: Record<string, string> = {}): ApiProxy {
+  return { workspaceRootOf: async (id: string) => workspaces[id] } as unknown as ApiProxy
+}
+
+async function mounted(
+  config?: { trustedHosts?: string[] },
+  workspaces: Record<string, string> = {},
+): Promise<{ routes: WebRoute[]; dispose: () => Promise<void> }> {
   const ctx = new Context()
   const routes: WebRoute[] = []
   ctx.provide('httpServer', fakeHttpServer(routes) as HttpServerService)
-  ctx.provide('apiProxy', {} as unknown as ApiProxy)
+  ctx.provide('apiProxy', fakeApiProxy(workspaces))
   const fiber = ctx.plugin({ inject: [...inject], apply }, config)
   await fiber.await()
   return { routes, dispose: () => fiber.dispose() }
 }
 
+/** The /f route is registered after /api; both are prefix routes on the same server. */
+function filesRoute(routes: WebRoute[]): WebRoute {
+  const route = routes.find(candidate => candidate.path === FILES_PATH)
+  if (route === undefined) throw new Error('the /f route was not registered')
+  return route
+}
+
 describe('connection node half', () => {
   it('fails the load on a trustedHosts entry that is not a bare authority', async () => {
     const routes: WebRoute[] = []
     const ctx = new Context()
     ctx.provide('httpServer', fakeHttpServer(routes) as HttpServerService)
-    ctx.provide('apiProxy', {} as unknown as ApiProxy)
+    ctx.provide('apiProxy', fakeApiProxy())
     const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.internal/path'] })
     await expect(fiber).rejects.toThrow(/not a bare host\[:port\] authority/)
     expect(routes).toHaveLength(0)
   })
 
-  it('registers the /api prefix route and removes it with the fiber', async () => {
+  it('registers both transport prefix routes and removes them with the fiber', async () => {
     const { routes, dispose } = await mounted()
-    expect(routes).toHaveLength(1)
-    expect(routes[0]).toMatchObject({ kind: 'prefix', path: API_PATH })
+    expect(routes).toMatchObject([{ kind: 'prefix', path: API_PATH }, { kind: 'prefix', path: FILES_PATH }])
     await dispose()
     expect(routes).toHaveLength(0)
   })
@@ -132,6 +150,52 @@ describe('connection node half', () => {
   })
 })
 
+describe('connection node half: the /f workspace-file route', () => {
+  /** A workspace holding one file, torn down with the returned disposer. */
+  async function workspace(): Promise<{ cwd: string; remove: () => Promise<void> }> {
+    const cwd = await mkdtemp(join(tmpdir(), 'dsh-node-half-'))
+    await writeFile(join(cwd, 'index.html'), '<h1>ok</h1>')
+    return { cwd, remove: () => rm(cwd, { recursive: true, force: true }) }
+  }
+
+  /** HEAD keeps the assertion on the route's decision, not on the byte stream. */
+  function head(url: string, headers: Record<string, string> = { host: '127.0.0.1:3080' }): IncomingMessage {
+    const request = fakeRequest(headers, url)
+    Object.assign(request, { method: 'HEAD' })
+    return request
+  }
+
+  it('applies the same browser-trust fence as /api, and refuses writes', async () => {
+    const { routes, dispose } = await mounted()
+    const untrusted = fakeResponse()
+    await filesRoute(routes).handler(head(`${FILES_PATH}/s-1/index.html`, { host: 'harness.example' }), untrusted.response)
+    expect(untrusted.state.status).toBe(403)
+    expect(untrusted.state.body).toBe('forbidden')
+
+    const written = fakeResponse()
+    const post = fakeRequest({ host: '127.0.0.1:3080' }, `${FILES_PATH}/s-1/index.html`)
+    Object.assign(post, { method: 'POST' })
+    await filesRoute(routes).handler(post, written.response)
+    expect(written.state.status).toBe(405)
+    await dispose()
+  })
+
+  it('confines reads to the directory the gateway names for that session', async () => {
+    const { cwd, remove } = await workspace()
+    const { routes, dispose } = await mounted(undefined, { 's-1': cwd })
+    const served = fakeResponse()
+    await filesRoute(routes).handler(head(`${FILES_PATH}/s-1/index.html`), served.response)
+    expect(served.state.status).toBe(200)
+    // A session the gateway names no directory for has no workspace to confine
+    // against, so there is nothing to serve.
+    const unknown = fakeResponse()
+    await filesRoute(routes).handler(head(`${FILES_PATH}/s-absent/index.html`), unknown.response)
+    expect(unknown.state.status).toBe(404)
+    await dispose()
+    await remove()
+  })
+})
+
 describe('connection node half over a real HTTP server', () => {
   /** Serve the registered prefix route from a real server and return its port. */
   async function serve(routes: WebRoute[]): Promise<{ port: number; close: () => Promise<void> }> {
diff --git a/packages/client/connection/tests/workspace-files.spec.ts b/packages/client/connection/tests/workspace-files.spec.ts
new file mode 100644
index 0000000000..fb4288a8b2
--- /dev/null
+++ b/packages/client/connection/tests/workspace-files.spec.ts
@@ -0,0 +1,134 @@
+/**
+ * Workspace-file reads over a real HTTP server and a real temporary
+ * workspace: confinement, content typing, and the sandbox header are wire
+ * facts, so they are asserted against responses Node actually produced.
+ */
+import { createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import type { ServerResponse } from 'node:http'
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Writable } from 'node:stream'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { handleWorkspaceFile } from '../src/workspace-files.ts'
+
+const SESSION = 's-1'
+
+let workspace: string
+let outside: string
+let origin: string
+let close: () => Promise<void>
+
+beforeAll(async () => {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-files-'))
+  workspace = join(root, 'workspace')
+  outside = join(root, 'outside')
+  await mkdir(join(workspace, 'out'), { recursive: true })
+  await mkdir(outside, { recursive: true })
+  await writeFile(join(workspace, 'index.html'), '<h1>产物</h1>')
+  await writeFile(join(workspace, 'notes.txt'), 'plain')
+  await writeFile(join(workspace, 'chart.svg'), '<svg xmlns="http://www.w3.org/2000/svg"/>')
+  await writeFile(join(workspace, 'model.safetensors'), 'unknown extension')
+  await writeFile(join(workspace, 'out', 'page.html'), '<p>nested</p>')
+  await writeFile(join(outside, 'secret.html'), 'SECRET')
+  await symlink(join(outside, 'secret.html'), join(workspace, 'escape.html'))
+
+  const server = createServer((req, res) => {
+    void handleWorkspaceFile(req, res, {
+      cwdFor: async sessionId => sessionId === SESSION ? workspace : undefined,
+    })
+  })
+  await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+  origin = `http://127.0.0.1:${String((server.address() as AddressInfo).port)}`
+  close = () => new Promise<void>((resolve, reject) => {
+    server.close((error) => {
+      if (error === undefined || error === null) resolve()
+      else reject(error)
+    })
+  })
+  return async () => { await rm(root, { recursive: true, force: true }) }
+})
+
+afterAll(async () => { await close() })
+
+function get(path: string, init?: RequestInit): Promise<Response> {
+  return fetch(`${origin}${path}`, init)
+}
+
+describe('workspace file reads', () => {
+  it('serves a produced document with the sandbox that keeps it off this origin', async () => {
+    const response = await get(`${FILES_PATH}/${SESSION}/index.html`)
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('<h1>产物</h1>')
+    expect(response.headers.get('content-type')).toBe('text/html; charset=utf-8')
+    // The whole reason a model-authored page may be served from the RPC
+    // origin: an opaque origin cannot read /api/events.mux.
+    expect(response.headers.get('content-security-policy')).toContain('sandbox')
+    expect(response.headers.get('x-content-type-options')).toBe('nosniff')
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    expect(response.headers.get('content-disposition')).toBe('inline')
+  })
+
+  it('sandboxes SVG too, and leaves non-scriptable types alone', async () => {
+    const svg = await get(`${FILES_PATH}/${SESSION}/chart.svg`)
+    expect(svg.headers.get('content-type')).toBe('image/svg+xml')
+    expect(svg.headers.get('content-security-policy')).toContain('sandbox')
+    const text = await get(`${FILES_PATH}/${SESSION}/notes.txt`)
+    expect(text.headers.get('content-type')).toBe('text/plain; charset=utf-8')
+    expect(text.headers.get('content-security-policy')).toBeNull()
+  })
+
+  it('shows an unknown extension as text rather than downloading it', async () => {
+    const response = await get(`${FILES_PATH}/${SESSION}/model.safetensors`)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toBe('text/plain; charset=utf-8')
+  })
+
+  it('serves a nested path, so a document reaches its own siblings', async () => {
+    const response = await get(`${FILES_PATH}/${SESSION}/out/page.html`)
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('<p>nested</p>')
+  })
+
+  it('answers HEAD with the length and no body', async () => {
+    const response = await get(`${FILES_PATH}/${SESSION}/notes.txt`, { method: 'HEAD' })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-length')).toBe('5')
+    expect(await response.text()).toBe('')
+  })
+
+  it('refuses a symlink whose target leaves the workspace', async () => {
+    const response = await get(`${FILES_PATH}/${SESSION}/escape.html`)
+    expect(response.status).toBe(403)
+    expect(await response.text()).not.toContain('SECRET')
+  })
+
+  it('reports missing files, directories, and unknown sessions as absent', async () => {
+    expect((await get(`${FILES_PATH}/${SESSION}/nope.html`)).status).toBe(404)
+    expect((await get(`${FILES_PATH}/${SESSION}/out`)).status).toBe(404)
+    // A path whose ancestor is a file, not a directory.
+    expect((await get(`${FILES_PATH}/${SESSION}/notes.txt/child`)).status).toBe(404)
+    expect((await get(`${FILES_PATH}/s-other/index.html`)).status).toBe(404)
+    expect((await get(`${FILES_PATH}/${SESSION}`)).status).toBe(404)
+  })
+})
+
+describe('workspace file streaming failures', () => {
+  it('tears the response down instead of rejecting when the body cannot be written', async () => {
+    // A client that goes away mid-stream must not surface as a handler
+    // rejection: the webserver's last-resort guard would log it and try to
+    // answer 400 on a response whose status line is already out.
+    const sink = new Writable({
+      write(_chunk, _encoding, callback) { callback(new Error('socket gone')) },
+    })
+    const response = Object.assign(sink, { writeHead: () => response }) as unknown as ServerResponse
+    await expect(handleWorkspaceFile(
+      { url: `${FILES_PATH}/${SESSION}/index.html`, method: 'GET', headers: {} } as never,
+      response,
+      { cwdFor: async () => workspace },
+    )).resolves.toBeUndefined()
+    expect(sink.destroyed).toBe(true)
+  })
+})
diff --git a/packages/client/runtime/src/client/contract/workspaces.ts b/packages/client/runtime/src/client/contract/workspaces.ts
index 3e64ef3717..dbc0f3b30f 100644
--- a/packages/client/runtime/src/client/contract/workspaces.ts
+++ b/packages/client/runtime/src/client/contract/workspaces.ts
@@ -56,6 +56,17 @@ export interface IWorkspaces {
    * @param path - absolute or host-resolvable path.
    */
   openPath(path: string): Promise<void>
+  /**
+   * URL serving one file out of a session's workspace, for a UI that opens a
+   * produced file in the browser instead of on the Host machine.
+   * @param sessionId - the session whose cwd anchors the path.
+   * @param cwd - that session's working directory, or `undefined` when unknown.
+   * @param path - the path a tool reported (absolute, or relative to `cwd`).
+   * @returns the origin-relative URL, or `undefined` when the path lies
+   * outside the workspace — which this transport never serves, leaving
+   * {@link IWorkspaces.openPath} as the only way to reach it.
+   */
+  fileUrl(sessionId: SessionId, cwd: string | undefined, path: string): string | undefined
   /**
    * Rename a Workspace.
    * @param workspaceId - target workspace.
diff --git a/packages/client/runtime/src/client/workspaces/service.ts b/packages/client/runtime/src/client/workspaces/service.ts
index a0a76670f2..837a7daa03 100644
--- a/packages/client/runtime/src/client/workspaces/service.ts
+++ b/packages/client/runtime/src/client/workspaces/service.ts
@@ -5,6 +5,7 @@ import type {
   DirectoryListing, IApiClient, RpcError,
   SessionId, WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
+import { workspaceFileSegments, workspaceFileUrl } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
 import type { SessionsPort, SessionsPortList } from '../contract/sessions-port.ts'
@@ -239,6 +240,19 @@ export class WorkspacesService implements IWorkspaces {
     }
   }
 
+  /**
+   * URL serving one file out of a session's workspace.
+   * @param sessionId - the session whose cwd anchors the path.
+   * @param cwd - that session's working directory, or `undefined` when unknown.
+   * @param path - the path a tool reported (absolute, or relative to `cwd`).
+   * @returns the origin-relative URL, or `undefined` for a path outside the workspace.
+   */
+  fileUrl(sessionId: SessionId, cwd: string | undefined, path: string): string | undefined {
+    const segments = workspaceFileSegments(cwd, path)
+    if (segments === undefined) return undefined
+    return workspaceFileUrl(sessionId, segments)
+  }
+
   /**
    * Rename a Workspace.
    * @param workspaceId - target workspace.
diff --git a/packages/client/runtime/tests/workspaces-service.spec.ts b/packages/client/runtime/tests/workspaces-service.spec.ts
index 4323d7ffce..3d9cef547f 100644
--- a/packages/client/runtime/tests/workspaces-service.spec.ts
+++ b/packages/client/runtime/tests/workspaces-service.spec.ts
@@ -276,6 +276,21 @@ describe('WorkspacesService', () => {
     await expect(workspaces.openPath('/missing')).rejects.toThrow(/path open failed/)
   })
 
+  it('addresses a workspace file by URL, and only inside the workspace', async () => {
+    const ctx = new Context()
+    const api = new FakeApiClient()
+    const sessions = new SessionsService(ctx, api)
+    const workspaces = new WorkspacesService(ctx, api, sessions)
+    const session = 's-1' as SessionId
+    // The URL is derived, not fetched: no wire call answers a link.
+    expect(workspaces.fileUrl(session, '/w/alpha', '/w/alpha/out/a b.html')).toBe('/f/s-1/out/a%20b.html')
+    expect(workspaces.fileUrl(session, '/w/alpha', 'out/index.html')).toBe('/f/s-1/out/index.html')
+    // Outside the workspace there is nothing this transport may serve, which
+    // is the signal a caller falls back to openPath on.
+    expect(workspaces.fileUrl(session, '/w/alpha', '/etc/hosts')).toBeUndefined()
+    expect(api.calls).toHaveLength(0)
+  })
+
   it('deletes a Workspace or preserves it when the Host rejects deletion', async () => {
     const ctx = new Context()
     const api = new FakeApiClient()
diff --git a/packages/client/test-runtime/src/workspaces.ts b/packages/client/test-runtime/src/workspaces.ts
index 7e626a3660..01e7db4c3d 100644
--- a/packages/client/test-runtime/src/workspaces.ts
+++ b/packages/client/test-runtime/src/workspaces.ts
@@ -1,5 +1,6 @@
 /** Test-owned workspaces face: the renderer standard-kit observable plus recorded actions. */
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { workspaceFileSegments, workspaceFileUrl } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type {
   DirectoryListing, IWorkspaces, SessionId, SnapshotStore, WorkspaceId, WorkspaceListState, WorkspaceView,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -98,6 +99,22 @@ export class TestWorkspaces implements IWorkspaces {
     await (this.stubs.get('openPath')?.(path) as Promise<void> | undefined)
   }
 
+  /**
+   * Workspace-file URL (recorded). Runs the production path derivation so a
+   * feature test sees the real in/outside-workspace split; stub to force either.
+   * @param sessionId - the session whose cwd anchors the path.
+   * @param cwd - that session's working directory.
+   * @param path - the path a tool reported.
+   * @returns the origin-relative URL, or undefined outside the workspace.
+   */
+  fileUrl(sessionId: SessionId, cwd: string | undefined, path: string): string | undefined {
+    this.calls.push({ method: 'fileUrl', args: [sessionId, cwd, path] })
+    const stub = this.stubs.get('fileUrl')
+    if (stub !== undefined) return stub(sessionId, cwd, path) as string | undefined
+    const segments = workspaceFileSegments(cwd, path)
+    return segments === undefined ? undefined : workspaceFileUrl(sessionId, segments)
+  }
+
   /**
    * Directory picker (recorded). The default cancels (null); stub to select.
    * @returns the picked path, or null.
diff --git a/packages/client/test-runtime/tests/runtime.spec.tsx b/packages/client/test-runtime/tests/runtime.spec.tsx
index 3675671f26..a9c4b0c9ca 100644
--- a/packages/client/test-runtime/tests/runtime.spec.tsx
+++ b/packages/client/test-runtime/tests/runtime.spec.tsx
@@ -549,6 +549,10 @@ describe('workspaces action face', () => {
     expect(renamed.title).toBe('Renamed')
     await ws.delete('w1' as WorkspaceId)
     await ws.openPath('/proj/file.ts')
+    // fileUrl runs the production derivation, so a feature test sees the same
+    // inside/outside-workspace split the browser half decides on.
+    expect(ws.fileUrl('s1' as SessionId, '/proj', 'out/a.html')).toBe('/f/s1/out/a.html')
+    expect(ws.fileUrl('s1' as SessionId, '/proj', '/etc/hosts')).toBeUndefined()
     const moved = await ws.insertSessionBefore('w1' as WorkspaceId, 's1' as SessionId, 's2' as SessionId)
     expect(moved.sessionIds).toEqual(['s1'])
     // Default archive mirrors the production effect: the id joins the list
@@ -556,13 +560,15 @@ describe('workspaces action face', () => {
     await ws.archiveSession('s1' as SessionId)
     expect(ws.list.getSnapshot().archivedSessionIds).toEqual(['s1'])
     expect(ws.calls.map(c => c.method)).toEqual(
-      ['create', 'create', 'pickDirectory', 'rename', 'delete', 'openPath', 'insertSessionBefore', 'archiveSession'])
+      ['create', 'create', 'pickDirectory', 'rename', 'delete', 'openPath', 'fileUrl', 'fileUrl',
+        'insertSessionBefore', 'archiveSession'])
 
     ws.stub('create', () => Promise.resolve({ workspaceId: 'ws-x', title: 'X', path: '/x', sessionIds: [] } as never))
     ws.stub('pickDirectory', () => Promise.resolve('/picked'))
     ws.stub('rename', () => Promise.resolve({ workspaceId: 'w1', title: 'S', path: '/s', sessionIds: [] } as never))
     ws.stub('delete', () => Promise.resolve())
     ws.stub('openPath', () => Promise.resolve())
+    ws.stub('fileUrl', () => '/f/forced/a.html')
     ws.stub('insertSessionBefore', () => Promise.resolve({ workspaceId: 'w1', title: '', path: '', sessionIds: [] } as never))
     ws.stub('archiveSession', () => Promise.resolve())
     expect((await ws.create({ name: 'y' })).title).toBe('X')
@@ -570,6 +576,7 @@ describe('workspaces action face', () => {
     expect((await ws.rename('w1' as WorkspaceId, 'z')).title).toBe('S')
     await ws.delete('w1' as WorkspaceId)
     await ws.openPath('/other')
+    expect(ws.fileUrl('s1' as SessionId, '/proj', '/etc/hosts')).toBe('/f/forced/a.html')
     expect((await ws.insertSessionBefore('w1' as WorkspaceId, 's1' as SessionId)).sessionIds).toEqual([])
     // The stub replaces the default set mutation: the set stays as-is.
     await ws.archiveSession('s2' as SessionId)
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index c67431e409..71f05267b3 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -275,6 +275,15 @@ export function apply(ctx: Context): void {
         },
         openFile: (path) => {
           const cwd = sessions.list.getSnapshot().byId[sessionId]?.cwd
+          // A file inside the workspace opens in a new tab, so a browser that
+          // is not on the Host machine can still see what the agent produced.
+          // Anything outside it has no served URL and falls back to the Host's
+          // own opener, which is loopback-only by the /api trust fence.
+          const url = workspaces.fileUrl(sessionId, cwd, path)
+          if (url !== undefined) {
+            window.open(url, '_blank', 'noopener,noreferrer')
+            return
+          }
           void workspaces.openPath(resolveToolPath(cwd, path)).catch(() => {
             // Host/OS open failures stay silent in the chat row; the native
             // app surfaces its own error dialog when the path is unusable.
diff --git a/packages/client/ui-conversation/tests/apply-inject.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
index cfbb0fdcbe..6427f6750c 100644
--- a/packages/client/ui-conversation/tests/apply-inject.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
@@ -218,13 +218,22 @@ describe('conversation slot inject surface', () => {
     await b.runtime.dispose()
   })
 
-  it('openFile (chat view face) resolves against session cwd and calls workspaces.openPath', async () => {
+  it('openFile (chat view face) opens a workspace file in a tab and falls back to the host opener outside it', async () => {
     const b = await bench()
+    const open = vi.spyOn(window, 'open').mockReturnValue(null)
     const { injected } = b.chatViewSurface(ROOT)
+    // Inside the session cwd: served by this origin, so a browser anywhere on
+    // the network sees the file the agent produced.
     injected.openFile('src/a.ts')
+    expect(open).toHaveBeenCalledWith(`/f/${ROOT}/src/a.ts`, '_blank', 'noopener,noreferrer')
+    expect(b.runtime.workspaces.calls.some(c => c.method === 'openPath')).toBe(false)
+    // Outside it there is no served URL, so the Host's own opener answers —
+    // resolved against the session cwd exactly as before.
+    injected.openFile('/etc/hosts')
     await vi.waitFor(() => {
-      expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['/proj/src/a.ts'] })
+      expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['/etc/hosts'] })
     })
+    open.mockRestore()
     await b.runtime.dispose()
   })
 
diff --git a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
index bafc6fe709..51e31c9750 100644
--- a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
@@ -134,6 +134,7 @@ async function bench(snapshot: ConversationSnapshot) {
     startSession: vi.fn(),
     sendSession: vi.fn(),
     openPath: vi.fn(async () => {}),
+    fileUrl: vi.fn((_sessionId: unknown, _cwd: string | undefined, path: string) => `/f/s-1/${path}`),
   }
   ctx.provide('workspaces', workspaces)
   ctx.provide('layout', layout)
@@ -243,12 +244,14 @@ describe('run_code sub-calls through the real chat machinery', () => {
       subCall(12, parent, 2, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt'),
     ]]])
     const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
+    const open = vi.spyOn(window, 'open').mockReturnValue(null)
     const view = mountApp(b.slots)
     view.getByText('notes/demo.txt').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
     await vi.waitFor(() => {
-      expect(b.workspaces.openPath).toHaveBeenCalledWith('notes/demo.txt')
+      expect(open).toHaveBeenCalledWith('/f/s-1/notes/demo.txt', '_blank', 'noopener,noreferrer')
     })
+    open.mockRestore()
     view.getByText('List notes').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
   })
diff --git a/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx b/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
index eb48677d4f..6cb46e7ea0 100644
--- a/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
@@ -119,14 +119,16 @@ describe('keyed toolview hole through the real machinery', () => {
     await b.runtime.dispose()
   })
 
-  it('file-path clicks travel owner openFile → chat inject → workspaces.openPath', async () => {
+  it('file-path clicks travel owner openFile → chat inject → the served workspace URL', async () => {
     const b = await bench([toolResult(3, 'c1', 'read', '{"path":"src/a.ts"}')])
+    const open = vi.spyOn(window, 'open').mockReturnValue(null)
     const view = b.runtime.renderRoot()
     view.getByText('src/a.ts').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
     await vi.waitFor(() => {
-      expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['src/a.ts'] })
+      expect(open).toHaveBeenCalledWith(expect.stringContaining('/src/a.ts'), '_blank', 'noopener,noreferrer')
     })
+    open.mockRestore()
     await b.runtime.dispose()
   })
 
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 27a1434e60..b96bf528a7 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 3c5a83a468b0cf9e596b8b13fafe40c409576fc5
-README.zh.md: f8533564575bf6b716f3fa7241ce47b8d4dd435f
+README.md: ee8e758a68f6efa3e363a36fcc9e8444e589ea40
+README.zh.md: 4ec3817e65543d6e248be9d902d0b74674f56e5a
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 3c5a83a468..ee8e758a68 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -36,6 +36,8 @@ The `command.*` and `skill.*` domains expose the host command registry and skill
 
 The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves the namespaces addressed by registered configurable providers (`ctx.llm.listConfigurableProviders()`) plus a small explicit allowlist — the Web preference `permission` and the product-owned `ui-onboarding`; adding a Settings registration alone never makes it remotely readable or writable. Any other namespace answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, and the section's `revision`. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired by `llm/adapters-updated` and by a change to a configurable-provider namespace, whose settings carry that provider's catalog and endpoint; a `permission` or `ui-onboarding` change emits only its settings invalidation. The browser carrier restricts the whole configuration plane, reads included (`settings.describe`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.
 
+Two members of `ApiProxy` are deliberately not wire methods. `respond` is the client-response entry (four-quadrant model), and `workspaceRootOf` answers where a Session's files live for an in-process reader — a live agent's header first, then the persistence store, never a resume. It has no wire face: a browser learns a Session's cwd from `sessions.view`, and reaches a file through the web transport's own `/f` route, never by asking for a host path. That route's URL shape (`api/files.ts`: `FILES_PATH`, `workspaceFileSegments`, `workspaceFileUrl`, `parseWorkspaceFilePath`) lives here with the other browser-importable contract surfaces, so the browser half that builds a `/f` URL and the serving half that parses one cannot drift apart; the route itself belongs to [`dsh-client-connection`](../../client/connection/README.md).
+
 ## Carrier layer (`/client` + root)
 
 `AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh -p` headless.
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index f853356457..4ec3817e65 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -36,6 +36,8 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 `settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表，以及该分节的 `revision`。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；过期的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取：`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
 
+`ApiProxy` 上有两个成员刻意不是协议方法。`respond` 是客户端响应入口（四象限模型），`workspaceRootOf` 则为进程内读取方回答某个 Session 的文件位于何处——先看活跃 agent 的 header，再看持久化存储，绝不恢复会话。它没有协议面：浏览器从 `sessions.view` 得知 Session 的 cwd，并经由 web 传输自己的 `/f` 路由抵达文件，而不是靠索要一条宿主路径。该路由的 URL 形状（`api/files.ts`：`FILES_PATH`、`workspaceFileSegments`、`workspaceFileUrl`、`parseWorkspaceFilePath`）与其余浏览器可导入的契约面一同放在这里，因此构造 `/f` URL 的浏览器半侧与解析它的服务半侧不会彼此漂移；路由本身则属于 [`dsh-client-connection`](../../client/connection/README.md)。
+
 ## 载体层（`/client` + 根路径）
 
 `AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供 `dsh -p` headless 模式使用。
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 4e506ed262..3c20785657 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -2290,5 +2290,16 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       pending.resolve(payload.answer)
       return Promise.resolve({ accepted: true })
     },
+
+    async workspaceRootOf(sessionId: SessionId): Promise<string | undefined> {
+      // A live agent answers from its own header; otherwise the store answers,
+      // deliberately without resuming — reading a session's directory must not
+      // pull an agent up the way the cold RPC path does.
+      const live = ctx.agents.get(sessionId)
+      if (live !== undefined) return live.session.header.cwd
+      const persistence = ctx.get('sessionPersistence')
+      if (persistence === undefined) return undefined
+      return (await persistence.list()).find(meta => meta.id === sessionId)?.cwd
+    },
   }
 }
diff --git a/packages/host/apiproxy/src/api/files.ts b/packages/host/apiproxy/src/api/files.ts
new file mode 100644
index 0000000000..b4ba01f29b
--- /dev/null
+++ b/packages/host/apiproxy/src/api/files.ts
@@ -0,0 +1,98 @@
+/**
+ * The `/f` workspace-file URL shape: the contract half of the web transport
+ * that carries bytes rather than RPC. The browser turns a tool's file path
+ * into a URL, the serving side turns that URL back into the segments below a
+ * session's cwd, and both read this one encoding decision so neither can drift
+ * into serving a path the other never meant. Pure string work with no Node and
+ * no DOM, like the rest of `api/` — the browser bundle inlines it.
+ * @module @deepseek-ai/dsh-host-apiproxy/api/files
+ */
+
+/**
+ * Route prefix owning every workspace-file read (`/f/<sessionId>/<segments…>`).
+ * The path carries the segments verbatim rather than a query parameter so a
+ * served document's relative references (`./logo.png`) resolve to their
+ * siblings in the same workspace directory.
+ */
+export const FILES_PATH = '/f'
+
+/** One parsed workspace-file request: whose workspace, and where inside it. */
+export interface WorkspaceFileTarget {
+  /** The owning session, still an opaque string — the caller resolves it to a cwd. */
+  sessionId: string
+  /** Decoded path segments below that session's cwd; never empty, never `.` or `..`. */
+  segments: string[]
+}
+
+/** A segment that survived decoding but would re-enter path resolution as more than one name. */
+function isPlainSegment(segment: string): boolean {
+  return segment !== '' && segment !== '.' && segment !== '..'
+    && !segment.includes('/') && !segment.includes('\\') && !segment.includes('\0')
+}
+
+function decode(raw: string): string | undefined {
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    // A malformed %-escape is a request we cannot interpret, not a miss.
+    return undefined
+  }
+}
+
+/**
+ * Express one tool-reported file path as segments below the session cwd.
+ * @param cwd - the session's working directory, or `undefined` when unknown.
+ * @param path - the path the tool reported (absolute, or relative to `cwd`).
+ * @returns the segments below `cwd`, or `undefined` when the path names
+ * something outside the workspace (which this route never serves) or resolves
+ * to the workspace directory itself.
+ */
+export function workspaceFileSegments(cwd: string | undefined, path: string): string[] | undefined {
+  const slashed = path.replace(/\\/g, '/')
+  const absolute = /^\/|^[A-Za-z]:\//.test(slashed)
+  let relative: string
+  if (absolute) {
+    if (cwd === undefined || cwd === '') return undefined
+    const root = cwd.replace(/\\/g, '/').replace(/\/+$/, '')
+    if (!slashed.startsWith(`${root}/`)) return undefined
+    relative = slashed.slice(root.length + 1)
+  } else {
+    relative = slashed
+  }
+  const segments = relative.split('/').filter(segment => segment !== '' && segment !== '.')
+  if (segments.length === 0 || segments.some(segment => !isPlainSegment(segment))) return undefined
+  return segments
+}
+
+/**
+ * Build the origin-relative URL serving one workspace file.
+ * @param sessionId - the session whose cwd anchors the path.
+ * @param segments - segments below that cwd, as {@link workspaceFileSegments} returns them.
+ * @returns the `/f/…` URL, resolved by the browser against the serving origin.
+ */
+export function workspaceFileUrl(sessionId: string, segments: readonly string[]): string {
+  const encoded = segments.map(segment => encodeURIComponent(segment)).join('/')
+  return `${FILES_PATH}/${encodeURIComponent(sessionId)}/${encoded}`
+}
+
+/**
+ * Parse a request pathname back into the session and segments it names.
+ * @param pathname - the request's raw (still percent-encoded) pathname.
+ * @returns the target, or `undefined` when the pathname is not a well-formed
+ * workspace-file read — including every traversal shape, which is refused here
+ * before any filesystem call rather than being resolved and then judged.
+ */
+export function parseWorkspaceFilePath(pathname: string): WorkspaceFileTarget | undefined {
+  if (!pathname.startsWith(`${FILES_PATH}/`)) return undefined
+  const [rawSession, ...rawSegments] = pathname.slice(FILES_PATH.length + 1).split('/')
+  if (rawSession === undefined || rawSegments.length === 0) return undefined
+  const sessionId = decode(rawSession)
+  if (sessionId === undefined || sessionId === '') return undefined
+  const segments: string[] = []
+  for (const raw of rawSegments) {
+    const segment = decode(raw)
+    if (segment === undefined || !isPlainSegment(segment)) return undefined
+    segments.push(segment)
+  }
+  return { sessionId, segments }
+}
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index 87aa1036bf..227e26264e 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -15,6 +15,9 @@ import type { SettingsApi } from './settings.ts'
 import type { CredentialsApi } from './credentials.ts'
 import type { LlmApi } from './llm.ts'
 import type { ClientResponse, RpcReceipt } from './rpc.ts'
+// The merge-free types subpath: api/ is imported from the browser lane, where
+// the host session service must not merge over the client runtime's own.
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
 
 /** Root interface of the unified API surface. New client-request domain = one new file pair + one field here + one map row. */
 export interface ApiProxy {
@@ -30,6 +33,17 @@ export interface ApiProxy {
   llm: LlmApi
   /** Response entry for server-requests (client-response, echoing their rpcId); not a domain method (four-quadrant model). */
   respond(message: ClientResponse): Promise<RpcReceipt>
+  /**
+   * The directory a Session's files may be read from — the same `cwd` the
+   * session summaries carry, in non-envelope form for an in-process reader.
+   * Not a domain method: it has no wire face, because a browser learns a
+   * Session's cwd from `sessions.view` and a file it may read from the web
+   * transport's own `/f` route, never by asking for a host path.
+   * @param sessionId - the Session to locate.
+   * @returns its absolute working directory, or `undefined` when this host
+   * serves no such Session. Resolving one never resumes an agent.
+   */
+  workspaceRootOf(sessionId: SessionId): Promise<string | undefined>
 }
 
 // ---- Domain interfaces and payload entities ----
@@ -48,6 +62,10 @@ export type { SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSe
 export type { CredentialsApi, CredentialView } from './credentials.ts'
 export type { ConfigurableProviderView, LlmApi } from './llm.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'
+
+// ---- Workspace-file URL shape (the transport's byte-carrying half) ----
+export { FILES_PATH, workspaceFileSegments, workspaceFileUrl, parseWorkspaceFilePath } from './files.ts'
+export type { WorkspaceFileTarget } from './files.ts'
 export type { QuestionResponsePayload } from './questions.ts'
 
 // ---- Message layer: narrow forms (domain-signature view) ----
diff --git a/packages/host/apiproxy/src/index.ts b/packages/host/apiproxy/src/index.ts
index 339b1e777d..f6dec19420 100644
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -64,6 +64,7 @@ export class ApiProxyService extends Service implements ApiProxy {
   readonly llm: ApiProxy['llm']
   readonly events: ApiProxy['events']
   readonly respond: ApiProxy['respond']
+  readonly workspaceRootOf: ApiProxy['workspaceRootOf']
 
   constructor(ctx: Context, config: Config) {
     super(ctx, 'apiProxy')
@@ -87,6 +88,7 @@ export class ApiProxyService extends Service implements ApiProxy {
     // createApiProxy returns closures (no `this` capture); bind only satisfies
     // the unbound-method lint without changing behavior.
     this.respond = api.respond.bind(api)
+    this.workspaceRootOf = api.workspaceRootOf.bind(api)
   }
 }
 
diff --git a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
index da05a4cd9b..cc30e5dee2 100644
--- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
@@ -62,7 +62,11 @@ function stubAgent(session: Session): Agent {
 async function harness(
   workspaceRoot = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-apiproxy-workspace-'))),
   picker: DirectoryPickerCapability = { kind: 'native', pick: async () => null },
-  extras: { openPath?: (path: string, signal: AbortSignal) => Promise<void> } = {},
+  extras: {
+    openPath?: (path: string, signal: AbortSignal) => Promise<void>
+    /** Store contents behind the gateway, or 'absent' for a composition with no persistence at all. */
+    persisted?: { id: SessionId; cwd?: string }[] | 'absent'
+  } = {},
 ) {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
@@ -73,7 +77,10 @@ async function harness(
   const storageDomain = new DomainFacility(ctx, { backend: 'memory', routes: {} })
   ctx.storage.mount('domain', storageDomain)
   ctx.provide('storageDomain', storageDomain)
-  ctx.provide('sessionPersistence', { list: () => Promise.resolve([]) } as never)
+  if (extras.persisted !== 'absent') {
+    const persisted = extras.persisted ?? []
+    ctx.provide('sessionPersistence', { list: () => Promise.resolve(persisted) } as never)
+  }
   await ctx.plugin(WorkspaceRegistry)
 
   const factory: AgentFactory = {
@@ -244,6 +251,27 @@ describe('host.openPath', () => {
   })
 })
 
+describe('workspaceRootOf', () => {
+  it('answers from the live agent, then the store, and names nothing for an unknown session', async () => {
+    const { api, workspaceRoot } = await harness(undefined, undefined, {
+      persisted: [{ id: 's-cold' as SessionId, cwd: '/w/cold' }],
+    })
+    const created = await api.sessions.create(request({ cwd: workspaceRoot }))
+    const sessionId = (created.result as { ok: true; value: { sessionId: SessionId } }).value.sessionId
+    // Live: the agent's own header, no store read involved.
+    await expect(api.workspaceRootOf(sessionId)).resolves.toBe(workspaceRoot)
+    // Not live: the store answers, and the lookup never resumes an agent —
+    // this harness's factory throws on resume, so a resuming lookup would fail.
+    await expect(api.workspaceRootOf('s-cold' as SessionId)).resolves.toBe('/w/cold')
+    await expect(api.workspaceRootOf('s-absent' as SessionId)).resolves.toBeUndefined()
+  })
+
+  it('names nothing at all when the host keeps no session store', async () => {
+    const { api } = await harness(undefined, undefined, { persisted: 'absent' })
+    await expect(api.workspaceRootOf('s-any' as SessionId)).resolves.toBeUndefined()
+  })
+})
+
 describe('workspace.create', () => {
   it('serializes concurrent names and rejects the duplicate', async () => {
     const { api, workspaceRoot } = await harness()
diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts
index 6307dfe8f9..2299949890 100644
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -108,6 +108,8 @@ function scriptedApi(overrides: {
     },
     events: { mux: () => empty<MuxFrame>(), host: () => empty<HostFrame>(), ...overrides.events },
     respond: overrides.respond ?? (() => Promise.resolve({ accepted: false as const, reason: 'not-pending' as const })),
+    // No wire face, so the handler map never reaches it.
+    workspaceRootOf: () => Promise.resolve(undefined),
   }
 }
 
diff --git a/packages/host/apiproxy/tests/fetch-carrier.spec.ts b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
index ef111afe12..dac49a1234 100644
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -233,6 +233,8 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
     async respond(message: ClientResponse): Promise<RpcReceipt> {
       return message.rpcId === 'known' ? { accepted: true } : { accepted: false, reason: 'not-pending' }
     },
+    // No wire face, so the carrier never reaches it.
+    workspaceRootOf: () => Promise.resolve(undefined),
   }
 }
 
diff --git a/packages/host/apiproxy/tests/files-path.spec.ts b/packages/host/apiproxy/tests/files-path.spec.ts
new file mode 100644
index 0000000000..df309a4783
--- /dev/null
+++ b/packages/host/apiproxy/tests/files-path.spec.ts
@@ -0,0 +1,74 @@
+/** The /f URL shape: one encoding decision, asserted from both ends. */
+import { describe, expect, it } from 'vitest'
+import {
+  FILES_PATH, parseWorkspaceFilePath, workspaceFileSegments, workspaceFileUrl,
+} from '../src/api/files.ts'
+
+describe('workspaceFileSegments', () => {
+  it('keeps a relative path as its own segments', () => {
+    expect(workspaceFileSegments('/w', 'out/index.html')).toEqual(['out', 'index.html'])
+    expect(workspaceFileSegments(undefined, 'index.html')).toEqual(['index.html'])
+    expect(workspaceFileSegments('/w', './a/./b.txt')).toEqual(['a', 'b.txt'])
+  })
+
+  it('strips the cwd prefix from an absolute path inside the workspace', () => {
+    expect(workspaceFileSegments('/w', '/w/a/b.html')).toEqual(['a', 'b.html'])
+    // A trailing separator on the cwd must not shift the split.
+    expect(workspaceFileSegments('/w/', '/w/a.html')).toEqual(['a.html'])
+  })
+
+  it('reads Windows paths on either separator', () => {
+    expect(workspaceFileSegments('C:\\w', 'C:\\w\\a\\b.html')).toEqual(['a', 'b.html'])
+    expect(workspaceFileSegments('C:/w', 'C:\\w\\a.html')).toEqual(['a.html'])
+  })
+
+  it('refuses everything the route would not serve', () => {
+    // Absolute, but not under this workspace.
+    expect(workspaceFileSegments('/w', '/etc/hosts')).toBeUndefined()
+    // A sibling directory sharing the cwd's name prefix is not inside it.
+    expect(workspaceFileSegments('/w', '/workspace-other/a')).toBeUndefined()
+    // Absolute with no cwd to anchor against.
+    expect(workspaceFileSegments(undefined, '/w/a.html')).toBeUndefined()
+    expect(workspaceFileSegments('', '/w/a.html')).toBeUndefined()
+    // Traversal, in either spelling.
+    expect(workspaceFileSegments('/w', '../secret')).toBeUndefined()
+    expect(workspaceFileSegments('/w', 'a/../../secret')).toBeUndefined()
+    // The workspace directory itself is not a file.
+    expect(workspaceFileSegments('/w', '/w')).toBeUndefined()
+    expect(workspaceFileSegments('/w', '.')).toBeUndefined()
+  })
+})
+
+describe('workspaceFileUrl', () => {
+  it('percent-encodes each segment but keeps the separators structural', () => {
+    expect(workspaceFileUrl('s-1', ['out', 'a b.html'])).toBe(`${FILES_PATH}/s-1/out/a%20b.html`)
+    expect(workspaceFileUrl('s/1', ['a#b.html'])).toBe(`${FILES_PATH}/s%2F1/a%23b.html`)
+  })
+})
+
+describe('parseWorkspaceFilePath', () => {
+  it('round-trips what the browser half builds', () => {
+    const url = workspaceFileUrl('s-1', ['out', 'a b.html'])
+    expect(parseWorkspaceFilePath(url)).toEqual({ sessionId: 's-1', segments: ['out', 'a b.html'] })
+  })
+
+  it('refuses malformed, prefix-foreign, and traversal pathnames', () => {
+    expect(parseWorkspaceFilePath('/api/session.list')).toBeUndefined()
+    expect(parseWorkspaceFilePath(FILES_PATH)).toBeUndefined()
+    // Session named but no file below it.
+    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1`)).toBeUndefined()
+    expect(parseWorkspaceFilePath(`${FILES_PATH}//a.html`)).toBeUndefined()
+    // Traversal is refused at parse time, before any filesystem call.
+    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/../etc/hosts`)).toBeUndefined()
+    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a/./b`)).toBeUndefined()
+    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a//b`)).toBeUndefined()
+    // A separator smuggled through percent-encoding stays one segment's problem.
+    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a%2F..%2Fb`)).toBeUndefined()
+    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a%5Cb`)).toBeUndefined()
+    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a%00b`)).toBeUndefined()
+    // Malformed percent-escapes are uninterpretable, not a miss to resolve.
+    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a%zz`)).toBeUndefined()
+    expect(parseWorkspaceFilePath(`${FILES_PATH}/%zz/a.html`)).toBeUndefined()
+    expect(parseWorkspaceFilePath(`${FILES_PATH}//`)).toBeUndefined()
+  })
+})
diff --git a/tsconfig.host.json b/tsconfig.host.json
index bae800f3ff..9de5b51da0 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -38,6 +38,7 @@
     "apps/web/tests/access-confirmation.e2e.ts",
     "apps/web/tests/shipped-composition.e2e.ts",
     "apps/web/tests/startup-auto-selection.e2e.ts",
+    "apps/web/tests/workspace-file-open.e2e.ts",
     "apps/cli/tests/**/*.ts",
     "examples/*/src/**/*.ts",
     "examples/*/start.ts",

From 35e9122a658659154691bddbe1d5aa150716ddcb Mon Sep 17 00:00:00 2001
From: ZiyaZhang <zzy211851@gmail.com>
Date: Fri, 31 Jul 2026 22:13:34 -0700
Subject: [PATCH 007/516] feat(web): list a turn's produced files under its
 closing message

The paths come from the mutation tools' follow-along locations, not from the
closing prose, so a turn's output is listed whether or not the model named
it. Each chip opens through the same openFile the tool rows use.

Reads contribute nothing (looking at a file does not produce it), a failed
mutation contributes nothing, a file touched twice is one entry, and the row
shows six with an explicit remainder rather than burying the answer.
---
 .../src/client/chat/AssistantMarkdown.tsx     | 11 +++-
 .../src/client/chat/ChatView.tsx              |  7 ++-
 .../src/client/chat/Deliverables.module.css   | 44 ++++++++++++++
 .../src/client/chat/Deliverables.tsx          | 54 ++++++++++++++++++
 .../src/client/chat/chat-flow.ts              | 37 ++++++++++++
 .../ui-conversation/src/client/locales.ts     |  6 ++
 .../ui-conversation/tests/chat-view.spec.tsx  | 57 ++++++++++++++++++-
 7 files changed, 213 insertions(+), 3 deletions(-)
 create mode 100644 packages/client/ui-conversation/src/client/chat/Deliverables.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/Deliverables.tsx

diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index 387a7fd82a..024a67a843 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -14,6 +14,7 @@ import {
   IconThinkOutline14, JsonBlock, MarkdownText,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
+import { Deliverables } from './Deliverables.tsx'
 import { MessageIconActions } from './MessageIconActions.tsx'
 import { ToolRow } from './ToolRow.tsx'
 import css from './AssistantMarkdown.module.css'
@@ -30,6 +31,11 @@ export interface AssistantMarkdownProps {
   seq?: number | undefined
   /** Fork the session through the turn containing this finalized message. */
   onFork?: ((seq: number) => void) | undefined
+  /** Files the closing turn produced, listed under the body; omitted for a
+   *  mid-turn assistant and for a turn that wrote nothing. */
+  produced?: readonly string[] | undefined
+  /** Opens one produced file; omitted wherever `produced` is. */
+  openFile?: ((path: string) => void) | undefined
   /** The owning view's locale seat, passed down as a plain prop. */
   t: ChatViewSlotProps['t']
 }
@@ -69,7 +75,7 @@ function ThinkRow({ text, running, t }: { text: string; running: boolean; t: Ass
 }
 
 export const AssistantMarkdown = memo(function AssistantMarkdown({
-  blocks, streaming, interrupted, time, seq, onFork, t,
+  blocks, streaming, interrupted, time, seq, onFork, produced, openFile, t,
 }: AssistantMarkdownProps) {
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
@@ -107,6 +113,9 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
         })}
         {interrupted && <span className={css.stopped}>{t('message.stopped')}</span>}
       </div>
+      {showActions && produced !== undefined && openFile !== undefined && (
+        <Deliverables paths={produced} openFile={openFile} t={t} />
+      )}
       {showActions && (
         <MessageIconActions
           text={copyText(blocks)}
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index 4a8e715bcf..798766dd8b 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -30,7 +30,7 @@ import type {
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
-import { assistantActionsSeqs, deriveChatFlow, type ChatFlowItem } from './chat-flow.ts'
+import { assistantActionsSeqs, deriveChatFlow, turnDeliverables, type ChatFlowItem } from './chat-flow.ts'
 import { AssistantMarkdown } from './AssistantMarkdown.tsx'
 import { GenericCommandCard } from './GenericCommandCard.tsx'
 import { GenericToolCard } from './GenericToolCard.tsx'
@@ -252,6 +252,9 @@ export function ChatView({
   // Only the last content assistant of each turn owns IconActions; mid-turn
   // text (before tools) omits `time` so AssistantMarkdown stays chrome-free.
   const actionSeqs = useMemo(() => assistantActionsSeqs(nodes), [nodes])
+  // Produced files per closing assistant: derived from the mutation tools'
+  // locations, so a turn's output is listed whether or not the model named it.
+  const produced = useMemo(() => turnDeliverables(nodes), [nodes])
 
   const listRef = useRef<HTMLDivElement | null>(null)
   const atBottomRef = useRef(true)
@@ -402,6 +405,8 @@ export function ChatView({
           time={actionSeqs.has(node.seq) ? node.time : undefined}
           seq={node.seq}
           onFork={forkAt}
+          produced={produced.get(node.seq)}
+          openFile={openFile}
           t={t}
         />
       )
diff --git a/packages/client/ui-conversation/src/client/chat/Deliverables.module.css b/packages/client/ui-conversation/src/client/chat/Deliverables.module.css
new file mode 100644
index 0000000000..2077de48ac
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/Deliverables.module.css
@@ -0,0 +1,44 @@
+/* Turn-tail produced-files row: a quiet label followed by wrapping file chips.
+   Sits between the assistant body and its IconActions footer, so it reads as
+   part of the answer rather than as another tool row. */
+
+.root {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin-top: 16px;
+  font-size: 13px;
+  line-height: 22px;
+}
+
+.label {
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* One produced file. A link by behavior (it opens the file), a chip by shape:
+   full paths are long and several may wrap onto one row. */
+.file {
+  max-width: 320px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  margin: 0;
+  padding: 0 8px;
+  border: none;
+  border-radius: 6px;
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-secondary);
+  font: inherit;
+  cursor: pointer;
+}
+
+.file:hover {
+  color: var(--dsw-alias-label-primary);
+  text-decoration: underline;
+}
+
+/* Overflow count: the row never silently drops files it did not show. */
+.more {
+  color: var(--dsw-alias-label-tertiary);
+}
diff --git a/packages/client/ui-conversation/src/client/chat/Deliverables.tsx b/packages/client/ui-conversation/src/client/chat/Deliverables.tsx
new file mode 100644
index 0000000000..0a0160b486
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/Deliverables.tsx
@@ -0,0 +1,54 @@
+// Deliverables: the produced-file row a finished turn ends with. The paths come
+// from the mutation tools' follow-along locations (see turnDeliverables), never
+// from the closing prose, so the answer carries its own output whether or not
+// the model remembered to name it. Clicking one goes through the same openFile
+// the tool rows use — in the browser that is a new tab served from the session
+// workspace, and outside it the Host's own opener.
+
+import type { ChatViewSlotProps } from '../contract/slots.ts'
+import css from './Deliverables.module.css'
+
+/** Files past this stay counted but unlisted: a refactor turn must not bury the answer. */
+const SHOWN = 6
+
+/** Trailing path segment, the part that identifies the file at a glance. */
+function basename(path: string): string {
+  const at = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
+  return at === -1 ? path : path.slice(at + 1)
+}
+
+/**
+ * Render one turn's produced files as openable chips.
+ * @param props - the turn's paths (tool order, already deduped), the chat
+ * view's file opener, and the owning view's locale seat.
+ * @returns The row, or `null` when the turn produced nothing.
+ */
+export function Deliverables({ paths, openFile, t }: {
+  paths: readonly string[]
+  openFile: (path: string) => void
+  t: ChatViewSlotProps['t']
+}) {
+  if (paths.length === 0) return null
+  const shown = paths.slice(0, SHOWN)
+  const hidden = paths.length - shown.length
+  return (
+    <div className={css.root}>
+      <span className={css.label}>{t('produced.label')}</span>
+      {shown.map(path => (
+        <button
+          key={path}
+          type="button"
+          className={css.file}
+          // The full path is the disambiguator when two turns produce files
+          // that share a basename; the chip itself stays short.
+          title={path}
+          aria-label={t('produced.open', { name: path })}
+          onClick={() => { openFile(path) }}
+        >
+          {basename(path)}
+        </button>
+      ))}
+      {hidden > 0 && <span className={css.more}>{t('produced.more', { count: String(hidden) })}</span>}
+    </div>
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/chat/chat-flow.ts b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
index 4958894154..83ba5c463c 100644
--- a/packages/client/ui-conversation/src/client/chat/chat-flow.ts
+++ b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
@@ -47,6 +47,43 @@ export function assistantActionsSeqs(nodes: readonly ConversationNode[]): Readon
   return new Set(lastByTurn.values())
 }
 
+/**
+ * Files each turn produced, keyed by the assistant seq that closes it — the
+ * same anchor {@link assistantActionsSeqs} elects, so the row lands under the
+ * message that reports the work rather than after some mid-turn narration.
+ *
+ * The source is the mutation tools' own follow-along `locations`, not the
+ * closing prose: a produced file must be listed whether or not the model
+ * remembered to name it. Reads contribute nothing (looking at a file does not
+ * produce it) and a failed mutation contributes nothing (there is no file to
+ * open). Paths keep first-seen order and appear once, so a file written and
+ * then edited in the same turn is one entry.
+ * @param nodes - snapshot nodes (surface order).
+ * @returns Per-closing-seq produced paths; a turn that produced none is absent.
+ */
+export function turnDeliverables(nodes: readonly ConversationNode[]): ReadonlyMap<number, readonly string[]> {
+  const closing = assistantActionsSeqs(nodes)
+  const byClosingSeq = new Map<number, readonly string[]>()
+  let pending: string[] = []
+  const seen = new Set<string>()
+  for (const node of nodes) {
+    if (node.kind === 'tool-result') {
+      if (node.isError || node.callView?.card !== 'diff') continue
+      for (const location of node.callView.locations ?? []) {
+        if (seen.has(location.path)) continue
+        seen.add(location.path)
+        pending.push(location.path)
+      }
+      continue
+    }
+    if (node.kind !== 'assistant' || !closing.has(node.seq)) continue
+    if (pending.length > 0) byClosingSeq.set(node.seq, pending)
+    pending = []
+    seen.clear()
+  }
+  return byClosingSeq
+}
+
 /**
  * Group finalized nodes into the step-summary flow.
  * @param nodes - snapshot nodes in human-transcript and durable-notice order.
diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index 1bda57660d..78114fa2a8 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -53,6 +53,9 @@ export const zh = {
   'message.unknownSurface': '未知 surface 事件：{type}',
   'message.unknownBlock': '未知内容块',
   'message.stopped': '已停止',
+  'produced.label': '产物',
+  'produced.more': '还有 {count} 个',
+  'produced.open': '打开 {name}',
   'message.branch': '在新对话中分支',
   'message.retry.active': '正在重试模型请求',
   'message.retry.cancelled': '模型请求重试已取消',
@@ -152,6 +155,9 @@ export const en = {
   'message.unknownSurface': 'Unknown surface event: {type}',
   'message.unknownBlock': 'Unknown content block',
   'message.stopped': 'Stopped',
+  'produced.label': 'Produced',
+  'produced.more': '{count} more',
+  'produced.open': 'Open {name}',
   'message.branch': 'Branch into a new conversation',
   'message.retry.active': 'Retrying model request',
   'message.retry.cancelled': 'Model request retry cancelled',
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index 110ab6a991..6f855231ac 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -20,7 +20,7 @@ import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts
 import { createChatStore } from '../src/client/stores.ts'
 import { ChatView } from '../src/client/chat/ChatView.tsx'
 import { zh } from '../src/client/locales.ts'
-import { assistantActionsSeqs, deriveChatFlow, flowKeys } from '../src/client/chat/chat-flow.ts'
+import { assistantActionsSeqs, deriveChatFlow, flowKeys, turnDeliverables } from '../src/client/chat/chat-flow.ts'
 
 afterEach(cleanup)
 // Keyless create() persists under the bare declared key; clear between cases
@@ -211,6 +211,61 @@ describe('chat-flow derivation', () => {
     ])
     expect([...seqs].sort((a, b) => a - b)).toEqual([5, 7])
   })
+
+  it('turnDeliverables attributes each turn’s written files to the assistant that closes it', () => {
+    const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
+      ...toolResult(seq, callId, 'write'),
+      callView: {
+        card: 'diff', title: `Write ${paths[0] ?? ''}`,
+        diffs: paths.map(path => ({ path, oldText: null, newText: 'x' })),
+        locations: paths.map(path => ({ path })),
+      },
+    })
+    const produced = turnDeliverables([
+      user(1, 'build it'),
+      assistant(2, 'writing', 1),
+      wrote(3, 'a', 'out/index.html'),
+      // Same file touched twice in one turn is one deliverable, in first-seen order.
+      wrote(4, 'b', 'out/app.css', 'out/index.html'),
+      // A read is not a deliverable; a failed write has no file to open.
+      { ...toolResult(5, 'c', 'read'), callView: { card: 'generic', title: 'Read x', locations: [{ path: 'x.ts' }] } },
+      { ...wrote(6, 'd', 'out/broken.html'), isError: true },
+      assistant(7, 'done', 1),
+      user(8, 'again'),
+      assistant(9, 'second turn', 2),
+    ])
+    expect(produced.get(7)).toEqual(['out/index.html', 'out/app.css'])
+    // A turn that produced nothing is absent, not an empty row.
+    expect(produced.has(9)).toBe(false)
+    // Nothing at all written: no entries.
+    expect(turnDeliverables([user(1, 'hi'), assistant(2, 'hello', 1)]).size).toBe(0)
+  })
+
+  it('renders the produced files under the closing message and opens one on click', () => {
+    const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
+      ...toolResult(seq, callId, 'write'),
+      callView: {
+        card: 'diff', title: 'Write',
+        diffs: paths.map(path => ({ path, oldText: null, newText: 'x' })),
+        locations: paths.map(path => ({ path })),
+      },
+    })
+    // Seven files: six chips plus an explicit remainder — the row bounds what
+    // it shows and says so rather than dropping the rest silently.
+    const paths = ['deep/a.html', 'b.css', 'c.ts', 'd.ts', 'e.ts', 'f.ts', 'g.ts']
+    const h = makeHarness({
+      nodes: [user(1, 'build it'), wrote(2, 'w', ...paths), assistant(3, 'done', 1)],
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.getByText('产物')).toBeTruthy()
+    // Chips carry the basename; the full path stays reachable as the title.
+    const chip = view.getByRole('button', { name: '打开 deep/a.html' })
+    expect(chip.textContent).toBe('a.html')
+    expect(view.queryByRole('button', { name: '打开 g.ts' })).toBeNull()
+    expect(view.getByText('还有 1 个')).toBeTruthy()
+    fireEvent.click(chip)
+    expect(h.openFile).toHaveBeenCalledWith('deep/a.html')
+  })
 })
 
 describe('ChatView', () => {

From f5d53f04b7f02f7ad69c0dd135b61ae4f16a7330 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <zzy211851@gmail.com>
Date: Fri, 31 Jul 2026 23:20:36 -0700
Subject: [PATCH 008/516] cleanup(web): stop sandboxing served workspace
 documents
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A preview lost localStorage and cookies under CSP sandbox — measurably, the
reported artifact throws SecurityError on load and its theme toggle goes
dead. The capability the sandbox denied is one the file's author, an agent
already holding this user's shell, never needed the browser for, so the
header sat behind a trust boundary it had already crossed.

Isolating a preview becomes a real question when workspace content stops
being the viewer's own; the answer then is a separate origin, not a header.
---
 ...6-07-31-web-workspace-file-links.i18n.yaml |  4 ++--
 .../2026-07-31-web-workspace-file-links.md    |  6 ++---
 .../2026-07-31-web-workspace-file-links.zh.md |  6 ++---
 packages/client/connection/README.i18n.yaml   |  4 ++--
 packages/client/connection/README.md          |  2 +-
 packages/client/connection/README.zh.md       |  2 +-
 .../client/connection/src/workspace-files.ts  | 22 +++++++------------
 .../connection/tests/workspace-files.spec.ts  | 13 +++++------
 8 files changed, 26 insertions(+), 33 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index 2055af6cea..78f99d03c9 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.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 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
-2026-07-31-web-workspace-file-links.md: b7fd5ca240db3ca885e89f4cf6dcc135e7c88de8
-2026-07-31-web-workspace-file-links.zh.md: 74949afe0260d2d9018691740573ff24a1bce820
+2026-07-31-web-workspace-file-links.md: 3cd7a075f091a50a980cde14fdfcd15e810ee1f4
+2026-07-31-web-workspace-file-links.zh.md: 5702730938a76042879989ea961fdbe251830839
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
index b7fd5ca240..3cd7a075f0 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
@@ -20,7 +20,7 @@ The parts were nearly all present, pointed at the wrong target. `ToolRow` alread
 
 **The URL shape lives in `dsh-host-apiproxy/api`, with the other browser-importable contract surfaces.** Both ends must agree on one encoding, but a client bundle may not value-import another plugin's package: the purity gate in `packages/client/tsdown.client.ts` allows only platform modules and the `INLINE_SAFE` wire layers, of which apiproxy is one. Putting `api/files.ts` there is what lets the browser half build a URL and the serving half parse it from a single source, and it needed no new package edge — both sides already depend on apiproxy.
 
-**Model-authored documents are served into an opaque origin.** `.html`/`.htm`/`.xhtml`/`.svg` carry `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`. Serving generated markup same-origin with `/api` would put `/api/events.mux` — a readable `GET` stream — one `window.open` away from a page the model wrote. The sandbox costs the preview its `localStorage`, cookies, and same-origin `fetch`; `host.openPath` stays as the full-capability way to open the same file on the Host machine, so the trade is resolved by keeping both affordances rather than by weakening either.
+**A served document carries no isolation header.** The first cut sandboxed script-capable documents, reasoning that `/api/events.mux` is a readable same-origin `GET` stream one `window.open` away from a page the model wrote. Measuring it settled the question the other way: under `CSP: sandbox` the report's own artifact throws `SecurityError` on `localStorage` and its theme toggle goes dead, and the capability the sandbox denies is one the page's author — an agent already holding this user's shell — never needed the browser for. A sandbox there sits behind a trust boundary it has already crossed. The rejected middle option (`connect-src 'none'` plus a `Sec-Fetch-Dest: document` refusal on the two SSE `GET`s) restored the preview but was the only option that had to edit the RPC gateway, and its fence goes quiet over plain-HTTP LAN, where `Sec-Fetch-*` is not sent. Isolating a preview becomes a real question when workspace content stops being the viewer's own; the answer then is a separate origin, not a header.
 
 **The client decides by derivation, not by probing.** `IWorkspaces.fileUrl(sessionId, cwd, path)` expresses a tool-reported path as segments below the session cwd and returns the origin-relative URL, or `undefined` when the path leaves the workspace. `undefined` is exactly the signal to fall back to `openPath`, so a file outside the workspace behaves as it did before and no capability negotiation is needed.
 
@@ -30,9 +30,9 @@ The parts were nearly all present, pointed at the wrong target. `ToolRow` alread
 - **A dedicated `dsh-client-workspace-files` package** — the honest seam shape if file serving were an independent capability. It is not: it needs the same fence and the same `trustedHosts` value as `/api`, and splitting would have duplicated both against the repository's own "don't split preemptively" rule.
 - **Keeping the URL-shape module in `client-connection` and importing it from the runtime** — the first cut, and the build refused it: a cross-plugin value import into a client bundle either inlines a duplicate runtime instance or names a specifier the frozen module table cannot answer. The gate is the reason the shared module sits in the wire layer rather than in the package that happens to own the route.
 - **`/f/<absolute path>`, so `openPath` could stay the single call site** — drops the sessionId from the URL, but then the served authority becomes the union of every workspace the host knows. The tight authority costs exactly one call-site edit, because `openFile` already has both the sessionId and the cwd in scope.
-- **`connect-src 'none'` instead of `sandbox`, to keep `localStorage` working** — blocks `fetch`/`EventSource` but not `window.open('/api/events.mux')`, which is readable same-origin. The two GET SSE endpoints are what make the sandbox necessary rather than optional.
+- **`connect-src 'none'` plus a navigation fence, to keep `localStorage` working under isolation** — measurably viable (Chrome sends `Sec-Fetch-Dest: document` for `window.open` and `empty` for `EventSource`, loopback included), and rejected anyway: it was the only option adding a rule to the RPC gateway, and the header it depends on is absent over plain-HTTP LAN. More mechanism than the threat it removes.
 - **Linkifying paths in the assistant's closing message** — the shape a user asks for ("put the link at the end"), but it makes rendering depend on the model spelling a path recognizably. The tool calls already carry `locations` as structured fact; consuming that is the reliable source and is left as the follow-up this route unblocks.
 
 ## Consequences
 
-Every existing file affordance changed target at once: write, edit, read, and the generic single-file card all reach `openFile`, so one call-site edit made produced files openable in the browser, LAN clients included. Three tests asserting the old `openPath` destination were rewritten to the new one; the outside-workspace fallback keeps the old assertion. The route is covered against a real HTTP server and a real temporary workspace, because confinement, content typing, and the sandbox header are wire facts, and the assembled web lane (`apps/web/tests/workspace-file-open.e2e.ts`, keyless over a cold-seeded session) proves the product path: clicking a read row's path opens `/f/<sessionId>/a.txt` in a second tab serving that workspace file, while a traversal spelling answers 404. `localStorage` is unavailable inside a preview, which is visible on generated pages that persist a theme toggle — the Host opener remains for those. Still deferred: the end-of-turn deliverable row derived from `locations`, and any linkification inside assistant Markdown.
+Every existing file affordance changed target at once: write, edit, read, and the generic single-file card all reach `openFile`, so one call-site edit made produced files openable in the browser, LAN clients included. Three tests asserting the old `openPath` destination were rewritten to the new one; the outside-workspace fallback keeps the old assertion. The route is covered against a real HTTP server and a real temporary workspace, because confinement, content typing, and the sandbox header are wire facts, and the assembled web lane (`apps/web/tests/workspace-file-open.e2e.ts`, keyless over a cold-seeded session) proves the product path: clicking a read row's path opens `/f/<sessionId>/a.txt` in a second tab serving that workspace file, while a traversal spelling answers 404. A preview keeps its own capabilities, so a generated page that persists a theme in `localStorage` works as its author intended. Still deferred: the end-of-turn deliverable row derived from `locations`, and any linkification inside assistant Markdown.
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index 74949afe02..5702730938 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 **URL 形状落在 `dsh-host-apiproxy/api`，与其余浏览器可导入的契约面同处一地。** 两端必须就同一套编码达成一致，但客户端 bundle 不允许值导入另一个插件的包：`packages/client/tsdown.client.ts` 里的纯度 gate 只放行平台模块与 `INLINE_SAFE` 协议层，而 apiproxy 正是其中之一。把 `api/files.ts` 放在那里，才使构造 URL 的浏览器半侧与解析它的服务半侧共用单一来源，而且没有新增任何包依赖边——两侧本来就依赖 apiproxy。
 
-**模型撰写的文档被送进不透明源。** `.html`／`.htm`／`.xhtml`／`.svg` 会带上 `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`。若把生成的标记与 `/api` 同源提供，`/api/events.mux`——一条可读的 `GET` 流——离模型写的页面就只有一次 `window.open` 之遥。sandbox 让预览失去 `localStorage`、cookie 与同源 `fetch`；`host.openPath` 作为在 Host 机器上以完整能力打开同一文件的方式保留下来，因此这个取舍是靠同时保留两个交互解决的，而不是靠削弱其中之一。
+**所服务的文档不带任何隔离头。** 最初的做法是给能执行脚本的文档加 sandbox，理由是 `/api/events.mux` 是一条同源可读的 `GET` 流，离模型写的页面只有一次 `window.open` 之遥。实测把这个问题判向了另一边：在 `CSP: sandbox` 之下，报告中那份产物自己就会在 `localStorage` 上抛 `SecurityError`，主题切换当场变死；而 sandbox 所拒绝的那项能力，对这个页面的作者——一个已经握着本用户 shell 的 agent——而言从来就不需要经由浏览器取得。那道 sandbox 立在一条它早已越过的信任边界之后。被否掉的折中方案（`connect-src 'none'` 加上对两个 SSE `GET` 拒绝 `Sec-Fetch-Dest: document`）确实能救回预览，但它是唯一必须去改 RPC 网关的方案，而它依赖的那个头在明文 HTTP 的 LAN 上根本不发送。当工作区内容不再属于观看者本人时，隔离预览才成为一个真问题；那时的答案是一个独立的源，而不是一个头。
 
 **客户端靠推导决定，而不是靠探测。** `IWorkspaces.fileUrl(sessionId, cwd, path)` 把工具报告的路径表达为 session cwd 之下的段落并返回相对于源的 URL，路径离开工作区时返回 `undefined`。`undefined` 恰好就是回退到 `openPath` 的信号，因此工作区外的文件行为与以往一致，也不需要任何能力协商。
 
@@ -30,9 +30,9 @@ Status: implemented
 - **单开一个 `dsh-client-workspace-files` 包**——如果文件服务是一项独立能力，这才是诚实的 seam 形状。它不是：它需要与 `/api` 相同的 fence 和相同的 `trustedHosts` 值，拆分会把两者都复制一份，违背仓库自己的“不要预先拆分”。
 - **把 URL 形状模块留在 `client-connection` 里、由 runtime 去导入**——最初就是这么写的，构建直接拒绝：向客户端 bundle 做跨插件值导入，要么内联出一份重复的运行时实例，要么落到冻结模块表答不出的说明符上。这道 gate 正是共享模块落在协议层、而非落在恰好持有该路由的那个包里的原因。
 - **`/f/<绝对路径>`，好让 `openPath` 保持为唯一调用点**——这会把 sessionId 从 URL 里去掉，但所服务的权限边界随之变成 host 已知的全部工作区之并集。紧的权限边界只花掉一处调用点的改动，因为 `openFile` 本来就同时持有 sessionId 与 cwd。
-- **用 `connect-src 'none'` 代替 `sandbox`，以保住 `localStorage`**——它挡得住 `fetch`／`EventSource`，挡不住 `window.open('/api/events.mux')`，而后者是同源可读的。正是那两个 GET SSE 端点让 sandbox 成为必需而非可选。
+- **用 `connect-src 'none'` 加一道导航栅栏，在保持隔离的同时保住 `localStorage`**——经实测确实可行（Chrome 对 `window.open` 发 `Sec-Fetch-Dest: document`、对 `EventSource` 发 `empty`，回环也在内），但仍被否：它是唯一要往 RPC 网关里加规则的方案，而它依赖的那个头在明文 HTTP 的 LAN 上并不发送。机制的分量超过了它移除的威胁。
 - **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带；消费它才是可靠来源，作为这条路由解锁的后续留下。
 
 ## 影响
 
-现有的每一处文件交互都同时换了目标：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此一处调用点的改动就让产出的文件在浏览器里可打开，LAN 客户端也在内。三个断言旧 `openPath` 去向的测试被改写为新的去向；工作区外的回退保留了旧断言。这条路由对着真实 HTTP 服务器与真实临时工作区做覆盖，因为收敛、内容定型与 sandbox 头都是协议事实；而组装后的 web 通道（`apps/web/tests/workspace-file-open.e2e.ts`，在冷播种会话上无密钥运行）证明了产品路径：点击读取行的路径会在第二个标签页打开 `/f/<sessionId>/a.txt` 并提供那个工作区文件，而穿越写法应答 404。预览中无法使用 `localStorage`，这在会持久化主题切换的生成页面上是看得见的——那些场景仍有 Host 打开器。仍然暂缓：由 `locations` 推导的回合末交付物行，以及助手 Markdown 内部的任何链接化。
+现有的每一处文件交互都同时换了目标：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此一处调用点的改动就让产出的文件在浏览器里可打开，LAN 客户端也在内。三个断言旧 `openPath` 去向的测试被改写为新的去向；工作区外的回退保留了旧断言。这条路由对着真实 HTTP 服务器与真实临时工作区做覆盖，因为收敛、内容定型与 sandbox 头都是协议事实；而组装后的 web 通道（`apps/web/tests/workspace-file-open.e2e.ts`，在冷播种会话上无密钥运行）证明了产品路径：点击读取行的路径会在第二个标签页打开 `/f/<sessionId>/a.txt` 并提供那个工作区文件，而穿越写法应答 404。预览保有自身的能力，因此把主题持久化到 `localStorage` 的生成页面，按其作者的意图正常工作。仍然暂缓：由 `locations` 推导的回合末交付物行，以及助手 Markdown 内部的任何链接化。
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 101d8fd61b..452ffe81c8 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
-README.md: 9a08cb4de5531b044bd411ea08595c22f88e5f8a
-README.zh.md: cfc427945f42b61288f57f5ca1db9af74dbcfb31
+README.md: ebc2dea2787268e1686eac24565c2433cb5f4b66
+README.zh.md: f5653e9e0e0aed3cbf7a9e6124668942f4dde44a
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index 9a08cb4de5..ebc2dea278 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -12,7 +12,7 @@ The node half guards every request under `/api` before bridging (`src/api-reques
 
 The node half also serves one file at a time out of a Session's workspace under `/f/<sessionId>/<segments…>`, so a produced deliverable is reachable from the page that reported it — an `http` page cannot follow a `file://` link, and a browser that is not on the Host machine has no such path anyway. The segments ride the URL rather than a query parameter so a served document's relative references resolve to its siblings. The request names a Session and the gateway names that Session's directory (`ApiProxy.workspaceRootOf`, which answers from a live agent's header or the persistence store and never resumes an agent to serve a file); this package reads the authority rather than the core services, because holding their host-side Context declarations would merge them over the browser runtime's own. The URL shape itself lives with the other browser-importable contract surfaces, in [`@deepseek-ai/dsh-host-apiproxy/api`](../../host/apiproxy/README.md), so the browser half that builds a URL and this half that parses one share a single encoding decision. Both the cwd and the resolved target go through `realpath` before comparison, so a symlink inside the workspace pointing out of it is refused by its target rather than its name; traversal spellings are refused earlier still, at parse time, before any filesystem call. Reads stream (no request buffers a file), answer `GET`/`HEAD` only, and carry `nosniff` with `no-store`. Extensions outside the served content-type table are typed `text/plain` rather than offered as a download, because a workspace read is a request to see a file.
 
-Documents that can execute script — `.html`, `.htm`, `.xhtml`, `.svg` — additionally carry `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`. Model-authored markup is served from the same origin as `/api`, where `/api/events.mux` is a readable `GET` stream, so an opaque origin is what keeps a generated page from reading the session event stream one `window.open` away. The cost is borne by the preview: `localStorage`, cookies, and same-origin `fetch` are unavailable inside it, and `host.openPath` remains the full-capability way to open the same file on the Host machine. The same trust fence gates this prefix, so a `trustedHosts` deployment serves workspace files exactly where it serves ordinary reads.
+A served document carries no isolation header and is same-origin with `/api`. That is a decision, not an omission: the only author of these files is the agent already holding this user's shell and filesystem, so a `Content-Security-Policy: sandbox` would sit behind a trust boundary it has already crossed while costing every preview its `localStorage` and cookies — a generated page that remembers a theme breaks under it. A deployment that serves `dsh web` beyond loopback should treat workspace content as trusted, which is already true of everything else its agent does. Isolating a preview becomes a real question when workspace content stops being the viewer's own; the answer then is a separate origin, not a header. The same trust fence gates this prefix, so a `trustedHosts` deployment serves workspace files exactly where it serves ordinary reads.
 
 ## Keyless fixture
 
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index cfc427945f..f5653e9e0e 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -12,7 +12,7 @@ node 半侧在桥接前守卫 `/api` 下的每个请求（`src/api-request-trust
 
 node 半侧还会在 `/f/<sessionId>/<segments…>` 下逐个提供某个 Session 工作区里的文件，让产出的交付物能从报告它的那个页面直接抵达——`http` 页面无法跟随 `file://` 链接，而不在 Host 机器上的浏览器本来也没有那条路径。段落走 URL 而非查询参数，是为了让所服务文档的相对引用能解析到它的同级文件。请求指名一个 Session，由网关指名该 Session 的目录（`ApiProxy.workspaceRootOf`，它从活跃 agent 的 header 或持久化存储作答，绝不会为了提供一个文件而恢复 agent）；本包读取这个权威来源而不去够核心服务，因为持有它们的 host 侧 Context 声明会把它们盖到浏览器运行时自己的声明之上。URL 形状本身与其余浏览器可导入的契约面放在一起，位于 [`@deepseek-ai/dsh-host-apiproxy/api`](../../host/apiproxy/README.md)，因此构造 URL 的浏览器半侧与解析 URL 的这一半共享同一个编码决定。cwd 与解析出的目标在比较前都要过 `realpath`，因此工作区内指向工作区外的符号链接会因其目标而被拒绝，而不是因其名字；穿越写法拒得更早，在解析期、任何文件系统调用之前。读取是流式的（没有请求会把文件缓冲起来），只应答 `GET`／`HEAD`，并带上 `nosniff` 与 `no-store`。所服务的内容类型表之外的扩展名一律按 `text/plain` 定型而非作为下载给出，因为工作区读取本就是一个“让我看看这个文件”的请求。
 
-能执行脚本的文档——`.html`、`.htm`、`.xhtml`、`.svg`——还会额外带上 `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`。模型撰写的标记与 `/api` 同源提供，而 `/api/events.mux` 是一条可读的 `GET` 流，因此正是不透明源阻止了一个生成页面通过一次 `window.open` 读走会话事件流。代价由预览承担：其中无法使用 `localStorage`、cookie 与同源 `fetch`，而 `host.openPath` 仍是在 Host 机器上以完整能力打开同一文件的方式。这条前缀由同一道信任 fence 把守，因此配置了 `trustedHosts` 的部署提供工作区文件的范围，与它提供普通读取的范围完全一致。
+所服务的文档不带任何隔离头，与 `/api` 同源。这是一个决定，不是遗漏：这些文件的唯一作者，正是那个已经握着本用户 shell 与文件系统的 agent，因此 `Content-Security-Policy: sandbox` 只会立在一条它早已越过的信任边界之后，代价却是每个预览都失去 `localStorage` 与 cookie——一个会记住主题的生成页面在它之下就是坏的。把 `dsh web` 服务到回环之外的部署，应当把工作区内容按可信处理，而这一点对其 agent 所做的其他一切本来就已成立。当工作区内容不再属于观看者本人时，隔离预览才成为一个真问题；那时的答案是一个独立的源，而不是一个头。这条前缀由同一道信任 fence 把守，因此配置了 `trustedHosts` 的部署提供工作区文件的范围，与它提供普通读取的范围完全一致。
 
 ## 无密钥 fixture
 
diff --git a/packages/client/connection/src/workspace-files.ts b/packages/client/connection/src/workspace-files.ts
index 9ad1b830a3..354b7b2225 100644
--- a/packages/client/connection/src/workspace-files.ts
+++ b/packages/client/connection/src/workspace-files.ts
@@ -9,6 +9,14 @@
  * names its cwd, and nothing outside that realpath is ever served. The caller
  * owns the browser-trust fence ([api-request-trust](./api-request-trust.ts)) —
  * this module is reached only by requests that already passed it.
+ *
+ * A served document is same-origin with `/api`, and deliberately carries no
+ * isolation header. The only author of these files is the agent already
+ * holding this user's shell and filesystem, so a browser sandbox would not
+ * move the trust boundary — it would sit behind one already crossed, at the
+ * cost of `localStorage` and cookies in every preview. Isolating a preview
+ * becomes a real question when workspace content stops being the viewer's own;
+ * the answer then is a separate origin, not a header.
  */
 
 import { createReadStream } from 'node:fs'
@@ -51,19 +59,6 @@ const MIME: Record<string, string> = {
 
 const DEFAULT_MIME = 'text/plain; charset=utf-8'
 
-/** Extensions whose top-level navigation can execute script, and so need the sandbox. */
-const SCRIPTABLE = new Set(['.html', '.htm', '.xhtml', '.svg'])
-
-/**
- * Model-authored documents run in an opaque origin. Without it a generated page
- * is same-origin with the RPC gateway, where `/api/events.mux` is a readable
- * GET stream — one `window.open` away from every session's events. The cost is
- * that `localStorage`, cookies, and same-origin `fetch` are unavailable inside
- * a preview; the native-open path (`host.openPath`) remains the full-capability
- * way to view a file.
- */
-const SANDBOX_CSP = 'sandbox allow-scripts allow-popups allow-modals allow-forms'
-
 /** How the route learns which directory a session may serve from. */
 export interface WorkspaceFileDeps {
   /**
@@ -151,7 +146,6 @@ export async function handleWorkspaceFile(
     // Workspace files change under the agent's hands; a cached preview would
     // show the previous turn's output after the next edit.
     'cache-control': 'no-store',
-    ...SCRIPTABLE.has(ext) ? { 'content-security-policy': SANDBOX_CSP } : {},
   })
   if (req.method === 'HEAD') {
     res.end()
diff --git a/packages/client/connection/tests/workspace-files.spec.ts b/packages/client/connection/tests/workspace-files.spec.ts
index fb4288a8b2..eb36fdd6ea 100644
--- a/packages/client/connection/tests/workspace-files.spec.ts
+++ b/packages/client/connection/tests/workspace-files.spec.ts
@@ -58,26 +58,25 @@ function get(path: string, init?: RequestInit): Promise<Response> {
 }
 
 describe('workspace file reads', () => {
-  it('serves a produced document with the sandbox that keeps it off this origin', async () => {
+  it('serves a produced document with its own capabilities intact', async () => {
     const response = await get(`${FILES_PATH}/${SESSION}/index.html`)
     expect(response.status).toBe(200)
     expect(await response.text()).toBe('<h1>产物</h1>')
     expect(response.headers.get('content-type')).toBe('text/html; charset=utf-8')
-    // The whole reason a model-authored page may be served from the RPC
-    // origin: an opaque origin cannot read /api/events.mux.
-    expect(response.headers.get('content-security-policy')).toContain('sandbox')
+    // No isolation header: a preview keeps localStorage and cookies, because
+    // the file's author already holds this user's shell (see the module doc).
+    expect(response.headers.get('content-security-policy')).toBeNull()
     expect(response.headers.get('x-content-type-options')).toBe('nosniff')
     expect(response.headers.get('cache-control')).toBe('no-store')
     expect(response.headers.get('content-disposition')).toBe('inline')
   })
 
-  it('sandboxes SVG too, and leaves non-scriptable types alone', async () => {
+  it('types SVG as a standalone document rather than sniffable bytes', async () => {
     const svg = await get(`${FILES_PATH}/${SESSION}/chart.svg`)
     expect(svg.headers.get('content-type')).toBe('image/svg+xml')
-    expect(svg.headers.get('content-security-policy')).toContain('sandbox')
+    expect(svg.headers.get('x-content-type-options')).toBe('nosniff')
     const text = await get(`${FILES_PATH}/${SESSION}/notes.txt`)
     expect(text.headers.get('content-type')).toBe('text/plain; charset=utf-8')
-    expect(text.headers.get('content-security-policy')).toBeNull()
   })
 
   it('shows an unknown extension as text rather than downloading it', async () => {

From dcf485ac5c2ee7373b0de683871cc63eb4a83152 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <zzy211851@gmail.com>
Date: Sat, 1 Aug 2026 01:08:16 -0700
Subject: [PATCH 009/516] fix(web): address the review of the workspace-file
 route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Isolation is restored on the premise the review corrected: a workspace file
need not be agent-authored — a read row makes every file in a cloned
repository openable — and a same-origin active document was measured driving
/api/settings.describe to a 200 with full data. Script-capable documents go
back into an opaque origin; the preview's lost localStorage is the known cost,
and a separate serving origin is the way to retire it.

- confine(): a workspace rooted at a filesystem root has a realpath already
  ending in the separator, and the doubled prefix 403'd every child.
- turnDeliverables(): reset on the turn boundary, not only at a closing
  assistant, so an interrupted turn cannot spill into the next turn's row;
  and recognize a mutation by render intent (diff card, or generic with
  kind 'edit') so str_replace_editor's insert counts.
- 405 answers name the methods it allows.
- The e2e now cold-seeds a recorded WRITE turn, so the assembled application
  covers the Produced row, its chip's served URL, and the isolation header.
- Agent Note matched to what shipped (the row is in this PR, not deferred);
  ui-conversation README documents the new destination and the row; the
  fixture lane's dead-tab quirk and the cold-path listing cost are recorded.
---
 ...6-07-31-web-workspace-file-links.i18n.yaml |  4 +-
 .../2026-07-31-web-workspace-file-links.md    | 11 ++--
 .../2026-07-31-web-workspace-file-links.zh.md | 11 ++--
 apps/web/tests/workspace-file-open.e2e.ts     | 66 ++++++++++---------
 packages/client/connection/README.i18n.yaml   |  4 +-
 packages/client/connection/README.md          |  4 +-
 packages/client/connection/README.zh.md       |  4 +-
 packages/client/connection/src/index.ts       |  3 +-
 .../client/connection/src/workspace-files.ts  | 31 ++++++---
 .../client/connection/tests/node-half.spec.ts | 11 +++-
 .../connection/tests/workspace-files.spec.ts  | 27 +++++---
 .../client/ui-conversation/README.i18n.yaml   |  4 +-
 packages/client/ui-conversation/README.md     |  4 +-
 packages/client/ui-conversation/README.zh.md  |  4 +-
 .../src/client/chat/chat-flow.ts              | 62 +++++++++++++----
 .../ui-conversation/tests/chat-view.spec.tsx  | 32 +++++++++
 packages/host/apiproxy/src/api-proxy.ts       |  4 ++
 17 files changed, 205 insertions(+), 81 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index 78f99d03c9..584f3c899d 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.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 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
-2026-07-31-web-workspace-file-links.md: 3cd7a075f091a50a980cde14fdfcd15e810ee1f4
-2026-07-31-web-workspace-file-links.zh.md: 5702730938a76042879989ea961fdbe251830839
+2026-07-31-web-workspace-file-links.md: a4bd8a2fecc2f1cb29d61a575b1ae0d31e5ebdd3
+2026-07-31-web-workspace-file-links.zh.md: 1d001710b2548343cb811fd6cca282cf956e95d9
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
index 3cd7a075f0..a4bd8a2fec 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-31-web-workspace-file-links.zh.md)
 
-> Scope: the `/f` workspace-file route on the web transport, the `IWorkspaces.fileUrl` derivation behind it, and the conversation's file-open affordance switching to it. Not in scope: an artifact registry, versioning, live reload, or any model-facing declaration.
+> Scope: the `/f` workspace-file route on the web transport, the `IWorkspaces.fileUrl` derivation behind it, the conversation's file-open affordance switching to it, and the produced-files row a finished turn ends with. Not in scope: an artifact registry, versioning, live reload, or any model-facing declaration.
 
 ## Problem
 
@@ -20,7 +20,7 @@ The parts were nearly all present, pointed at the wrong target. `ToolRow` alread
 
 **The URL shape lives in `dsh-host-apiproxy/api`, with the other browser-importable contract surfaces.** Both ends must agree on one encoding, but a client bundle may not value-import another plugin's package: the purity gate in `packages/client/tsdown.client.ts` allows only platform modules and the `INLINE_SAFE` wire layers, of which apiproxy is one. Putting `api/files.ts` there is what lets the browser half build a URL and the serving half parse it from a single source, and it needed no new package edge — both sides already depend on apiproxy.
 
-**A served document carries no isolation header.** The first cut sandboxed script-capable documents, reasoning that `/api/events.mux` is a readable same-origin `GET` stream one `window.open` away from a page the model wrote. Measuring it settled the question the other way: under `CSP: sandbox` the report's own artifact throws `SecurityError` on `localStorage` and its theme toggle goes dead, and the capability the sandbox denies is one the page's author — an agent already holding this user's shell — never needed the browser for. A sandbox there sits behind a trust boundary it has already crossed. The rejected middle option (`connect-src 'none'` plus a `Sec-Fetch-Dest: document` refusal on the two SSE `GET`s) restored the preview but was the only option that had to edit the RPC gateway, and its fence goes quiet over plain-HTTP LAN, where `Sec-Fetch-*` is not sent. Isolating a preview becomes a real question when workspace content stops being the viewer's own; the answer then is a separate origin, not a header.
+**Script-capable documents are served into an opaque origin.** `.html`/`.htm`/`.xhtml`/`.svg` carry `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`. The decision was briefly taken the other way, on the premise that these files are agent-authored and their author already holds this user's shell, so a browser sandbox would sit behind a trust boundary already crossed. Review falsified the premise: a workspace file need not be agent-authored at all — a read row makes every file in a cloned repository openable — and a same-origin active document was measured driving `/api/settings.describe` to a `200` with full data, so the loopback-pinned settings and credential plane was reachable from a page nobody in this session wrote. The cost is real and stays: a preview has no `localStorage` or cookies, so a generated page that remembers a theme will not. Restoring that without reopening the hole needs a separate origin, which is a different change; `host.openPath` remains the full-capability way to open the same file.
 
 **The client decides by derivation, not by probing.** `IWorkspaces.fileUrl(sessionId, cwd, path)` expresses a tool-reported path as segments below the session cwd and returns the origin-relative URL, or `undefined` when the path leaves the workspace. `undefined` is exactly the signal to fall back to `openPath`, so a file outside the workspace behaves as it did before and no capability negotiation is needed.
 
@@ -30,9 +30,10 @@ The parts were nearly all present, pointed at the wrong target. `ToolRow` alread
 - **A dedicated `dsh-client-workspace-files` package** — the honest seam shape if file serving were an independent capability. It is not: it needs the same fence and the same `trustedHosts` value as `/api`, and splitting would have duplicated both against the repository's own "don't split preemptively" rule.
 - **Keeping the URL-shape module in `client-connection` and importing it from the runtime** — the first cut, and the build refused it: a cross-plugin value import into a client bundle either inlines a duplicate runtime instance or names a specifier the frozen module table cannot answer. The gate is the reason the shared module sits in the wire layer rather than in the package that happens to own the route.
 - **`/f/<absolute path>`, so `openPath` could stay the single call site** — drops the sessionId from the URL, but then the served authority becomes the union of every workspace the host knows. The tight authority costs exactly one call-site edit, because `openFile` already has both the sessionId and the cwd in scope.
-- **`connect-src 'none'` plus a navigation fence, to keep `localStorage` working under isolation** — measurably viable (Chrome sends `Sec-Fetch-Dest: document` for `window.open` and `empty` for `EventSource`, loopback included), and rejected anyway: it was the only option adding a rule to the RPC gateway, and the header it depends on is absent over plain-HTTP LAN. More mechanism than the threat it removes.
-- **Linkifying paths in the assistant's closing message** — the shape a user asks for ("put the link at the end"), but it makes rendering depend on the model spelling a path recognizably. The tool calls already carry `locations` as structured fact; consuming that is the reliable source and is left as the follow-up this route unblocks.
+- **`connect-src 'none'` plus a navigation fence, to keep `localStorage` working under isolation** — measurably viable against the SSE-read vector (Chrome sends `Sec-Fetch-Dest: document` for `window.open` and `empty` for `EventSource`, loopback included), but it never addressed the larger one: same-origin `fetch` to a POST method is what reaches the configuration plane, and blocking `connect-src` from the served document is exactly what a hostile document would not do to itself. Only an origin boundary contains it.
+- **Serving `/f` from its own loopback port** — the one option that keeps both isolation and preview capabilities, and the shape a separate-origin answer would take. Deferred, not rejected: it needs a second listener with its own lifecycle plus the port plumbed to the client, which is a change of a different size than this one.
+- **Linkifying paths in the assistant's closing message** — the shape a user asks for ("put the link at the end"), but it makes rendering depend on the model spelling a path recognizably. The tool calls already carry `locations` as structured fact, so the produced-files row consumes that instead; linkifying the prose stays unnecessary rather than merely deferred.
 
 ## Consequences
 
-Every existing file affordance changed target at once: write, edit, read, and the generic single-file card all reach `openFile`, so one call-site edit made produced files openable in the browser, LAN clients included. Three tests asserting the old `openPath` destination were rewritten to the new one; the outside-workspace fallback keeps the old assertion. The route is covered against a real HTTP server and a real temporary workspace, because confinement, content typing, and the sandbox header are wire facts, and the assembled web lane (`apps/web/tests/workspace-file-open.e2e.ts`, keyless over a cold-seeded session) proves the product path: clicking a read row's path opens `/f/<sessionId>/a.txt` in a second tab serving that workspace file, while a traversal spelling answers 404. A preview keeps its own capabilities, so a generated page that persists a theme in `localStorage` works as its author intended. Still deferred: the end-of-turn deliverable row derived from `locations`, and any linkification inside assistant Markdown.
+Every existing file affordance changed target at once: write, edit, read, and the generic single-file card all reach `openFile`, so one call-site edit made produced files openable in the browser, LAN clients included. Three tests asserting the old `openPath` destination were rewritten to the new one; the outside-workspace fallback keeps the old assertion. The route is covered against a real HTTP server and a real temporary workspace, because confinement, content typing, and the sandbox header are wire facts, and the assembled web lane (`apps/web/tests/workspace-file-open.e2e.ts`, keyless over a cold-seeded session) proves the product path: clicking a read row's path opens `/f/<sessionId>/a.txt` in a second tab serving that workspace file, while a traversal spelling answers 404. A preview runs without `localStorage` or cookies, visible on generated pages that persist a theme — the Host opener remains for those, and a separate serving origin is the way to retire the limitation. The produced-files row ships here too: `turnDeliverables` reads a turn's output off the mutation tools' render intent (a diff card, or a generic card whose `kind` is `edit`), resets on the turn boundary so an interrupted turn cannot spill into the next, and renders under the closing assistant. Still deferred: linkification inside assistant Markdown, and any cross-session view of past deliverables.
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index 5702730938..1d001710b2 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-31-web-workspace-file-links.md) | 中文
 
-> 范围：web 传输层上的 `/f` 工作区文件路由、其背后的 `IWorkspaces.fileUrl` 推导，以及会话中打开文件的交互改指向它。不在范围内：产物注册表、版本、实时重载，或任何面向模型的声明。
+> 范围：web 传输层上的 `/f` 工作区文件路由、其背后的 `IWorkspaces.fileUrl` 推导、会话中打开文件的交互改指向它，以及完成的一轮以其产出文件收尾的那一行。不在范围内：产物注册表、版本、实时重载，或任何面向模型的声明。
 
 ## 问题
 
@@ -20,7 +20,7 @@ Status: implemented
 
 **URL 形状落在 `dsh-host-apiproxy/api`，与其余浏览器可导入的契约面同处一地。** 两端必须就同一套编码达成一致，但客户端 bundle 不允许值导入另一个插件的包：`packages/client/tsdown.client.ts` 里的纯度 gate 只放行平台模块与 `INLINE_SAFE` 协议层，而 apiproxy 正是其中之一。把 `api/files.ts` 放在那里，才使构造 URL 的浏览器半侧与解析它的服务半侧共用单一来源，而且没有新增任何包依赖边——两侧本来就依赖 apiproxy。
 
-**所服务的文档不带任何隔离头。** 最初的做法是给能执行脚本的文档加 sandbox，理由是 `/api/events.mux` 是一条同源可读的 `GET` 流，离模型写的页面只有一次 `window.open` 之遥。实测把这个问题判向了另一边：在 `CSP: sandbox` 之下，报告中那份产物自己就会在 `localStorage` 上抛 `SecurityError`，主题切换当场变死；而 sandbox 所拒绝的那项能力，对这个页面的作者——一个已经握着本用户 shell 的 agent——而言从来就不需要经由浏览器取得。那道 sandbox 立在一条它早已越过的信任边界之后。被否掉的折中方案（`connect-src 'none'` 加上对两个 SSE `GET` 拒绝 `Sec-Fetch-Dest: document`）确实能救回预览，但它是唯一必须去改 RPC 网关的方案，而它依赖的那个头在明文 HTTP 的 LAN 上根本不发送。当工作区内容不再属于观看者本人时，隔离预览才成为一个真问题；那时的答案是一个独立的源，而不是一个头。
+**能执行脚本的文档被送进不透明源。** `.html`／`.htm`／`.xhtml`／`.svg` 带上 `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`。这个决定曾短暂地被判向另一边，前提是这些文件由 agent 撰写、而其作者已经握着本用户的 shell，因此浏览器 sandbox 只会立在一条早已越过的信任边界之后。评审推翻了这个前提：工作区文件根本不必由 agent 撰写——一条 read 行就让 clone 下来的仓库里任何文件变得可打开——而同源的活动文档经实测能把 `/api/settings.describe` 打到 `200` 并拿到完整数据，也就是说被钉在回环的设置与凭据面，可以被一个本次会话中无人撰写的页面触达。代价真实且保留：预览没有 `localStorage` 与 cookie，因此会记住主题的生成页面在其中记不住。要在不重新打开这个洞的前提下取回它，需要一个独立的源，那是另一个尺寸的改动；`host.openPath` 仍是以完整能力打开同一文件的方式。
 
 **客户端靠推导决定，而不是靠探测。** `IWorkspaces.fileUrl(sessionId, cwd, path)` 把工具报告的路径表达为 session cwd 之下的段落并返回相对于源的 URL，路径离开工作区时返回 `undefined`。`undefined` 恰好就是回退到 `openPath` 的信号，因此工作区外的文件行为与以往一致，也不需要任何能力协商。
 
@@ -30,9 +30,10 @@ Status: implemented
 - **单开一个 `dsh-client-workspace-files` 包**——如果文件服务是一项独立能力，这才是诚实的 seam 形状。它不是：它需要与 `/api` 相同的 fence 和相同的 `trustedHosts` 值，拆分会把两者都复制一份，违背仓库自己的“不要预先拆分”。
 - **把 URL 形状模块留在 `client-connection` 里、由 runtime 去导入**——最初就是这么写的，构建直接拒绝：向客户端 bundle 做跨插件值导入，要么内联出一份重复的运行时实例，要么落到冻结模块表答不出的说明符上。这道 gate 正是共享模块落在协议层、而非落在恰好持有该路由的那个包里的原因。
 - **`/f/<绝对路径>`，好让 `openPath` 保持为唯一调用点**——这会把 sessionId 从 URL 里去掉，但所服务的权限边界随之变成 host 已知的全部工作区之并集。紧的权限边界只花掉一处调用点的改动，因为 `openFile` 本来就同时持有 sessionId 与 cwd。
-- **用 `connect-src 'none'` 加一道导航栅栏，在保持隔离的同时保住 `localStorage`**——经实测确实可行（Chrome 对 `window.open` 发 `Sec-Fetch-Dest: document`、对 `EventSource` 发 `empty`，回环也在内），但仍被否：它是唯一要往 RPC 网关里加规则的方案，而它依赖的那个头在明文 HTTP 的 LAN 上并不发送。机制的分量超过了它移除的威胁。
-- **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带；消费它才是可靠来源，作为这条路由解锁的后续留下。
+- **用 `connect-src 'none'` 加一道导航栅栏，在保持隔离的同时保住 `localStorage`**——针对“读走 SSE 流”这条向量经实测可行（Chrome 对 `window.open` 发 `Sec-Fetch-Dest: document`、对 `EventSource` 发 `empty`，回环也在内），但它从未触及更大的那条：真正够到配置面的是向 POST 方法发起的同源 `fetch`，而“从所服务文档一侧封住 `connect-src`”恰恰是敌意文档不会对自己做的事。只有源边界能收住它。
+- **让 `/f` 跑在自己的回环端口上**——唯一能同时保住隔离与预览能力的选项，也是“独立的源”这个答案该有的形状。是暂缓而非否决：它需要一个带自身生命周期的第二监听器，外加把端口铺到客户端，那是另一个尺寸的改动。
+- **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带，产出文件行消费的正是它；因此把正文链接化是不必要，而不只是被推迟。
 
 ## 影响
 
-现有的每一处文件交互都同时换了目标：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此一处调用点的改动就让产出的文件在浏览器里可打开，LAN 客户端也在内。三个断言旧 `openPath` 去向的测试被改写为新的去向；工作区外的回退保留了旧断言。这条路由对着真实 HTTP 服务器与真实临时工作区做覆盖，因为收敛、内容定型与 sandbox 头都是协议事实；而组装后的 web 通道（`apps/web/tests/workspace-file-open.e2e.ts`，在冷播种会话上无密钥运行）证明了产品路径：点击读取行的路径会在第二个标签页打开 `/f/<sessionId>/a.txt` 并提供那个工作区文件，而穿越写法应答 404。预览保有自身的能力，因此把主题持久化到 `localStorage` 的生成页面，按其作者的意图正常工作。仍然暂缓：由 `locations` 推导的回合末交付物行，以及助手 Markdown 内部的任何链接化。
+现有的每一处文件交互都同时换了目标：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此一处调用点的改动就让产出的文件在浏览器里可打开，LAN 客户端也在内。三个断言旧 `openPath` 去向的测试被改写为新的去向；工作区外的回退保留了旧断言。这条路由对着真实 HTTP 服务器与真实临时工作区做覆盖，因为收敛、内容定型与 sandbox 头都是协议事实；而组装后的 web 通道（`apps/web/tests/workspace-file-open.e2e.ts`，在冷播种会话上无密钥运行）证明了产品路径：点击读取行的路径会在第二个标签页打开 `/f/<sessionId>/a.txt` 并提供那个工作区文件，而穿越写法应答 404。预览在没有 `localStorage` 与 cookie 的情况下运行，这在会持久化主题的生成页面上看得见——那些场景仍有 Host 打开器，而独立的服务源是退休这条限制的路。产出文件行也在本次一并落地：`turnDeliverables` 依据改写工具的渲染意图（diff 卡片，或 `kind` 为 `edit` 的 generic 卡片）读出一轮的产出，在 turn 边界重置以免中断的一轮溢进下一轮，并渲染在收尾 assistant 之下。仍然暂缓：助手 Markdown 内部的链接化，以及任何跨会话回看既往产物的视图。
diff --git a/apps/web/tests/workspace-file-open.e2e.ts b/apps/web/tests/workspace-file-open.e2e.ts
index 63d4266cf4..98d239beb1 100644
--- a/apps/web/tests/workspace-file-open.e2e.ts
+++ b/apps/web/tests/workspace-file-open.e2e.ts
@@ -1,29 +1,31 @@
-// Web e2e scenario: clicking a tool row's file path opens that file in a new
-// browser tab, served by the web transport's own /f route. Cold-seeds the
-// seeded-history fixture (zero model calls). The surface package tests can
-// assert which opener the click reaches, but only the assembled application
-// proves the opened URL actually serves the workspace file — the whole point
-// of the route (docs/testing.md snapshot rule).
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
+// Web e2e scenario: a produced file, from the row that lists it to the bytes
+// the browser gets. Cold-seeds a recorded write turn (zero model calls).
+// Package tests cover the derivation and the route in isolation, but only the
+// assembled application shows that the turn's Produced row, the URL it opens,
+// and the file on disk are the same thing (docs/testing.md snapshot rule).
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import {
-  fixtureUserPrompts, launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
 import { newEnglishPage, saveFailureShot } from './support.ts'
 
-// Borrowed read-only: this scenario needs any settled turn whose tool rows
-// carry a workspace file path, not a new recording (message-actions pattern).
-const SEED = fileURLToPath(new URL('./snapshots/seeded-history/seed.jsonl', import.meta.url))
+// Borrowed read-only: this scenario needs any settled turn whose tools WROTE a
+// file, not a new recording (the message-actions borrowing pattern).
+const SEED = fileURLToPath(new URL('./snapshots/permission-policy-context/session.jsonl', import.meta.url))
 const MODE = webSnapshotMode()
 const SEED_ID = 'workspace-file-open-web-e2e'
 
-const PROMPT = 'Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop.'
+/** The file the borrowed recording's write tool produces. */
+const PRODUCED = 'policy-neutral.txt'
+/** An active document placed alongside it, for the isolation header the route puts on those. */
+const ACTIVE = 'preview.html'
 
-describe('web e2e: opening a workspace file from a tool row', () => {
+describe('web e2e: opening a produced file from the conversation', () => {
   let scaffold: WebScaffold
   let browser: Browser
   let page: Page
@@ -31,15 +33,13 @@ describe('web e2e: opening a workspace file from a tool row', () => {
 
   beforeAll(async () => {
     scaffold = await launchWebScaffold({})
-    // The seeded Session's cwd is the scaffold workspace itself; the recording's
-    // own nested directory is written too, so the seed's paths stay resolvable.
+    // The seeded Session's cwd is the scaffold workspace; the recording's own
+    // nested directory is created too, so its paths stay resolvable.
     await mkdir(join(scaffold.workspaceCwd, 'workspace'), { recursive: true })
-    for (const dir of [scaffold.workspaceCwd, join(scaffold.workspaceCwd, 'workspace')]) {
-      await writeFile(join(dir, 'a.txt'), 'alpha\n')
-      await writeFile(join(dir, 'b.txt'), 'beta\n')
-    }
+    await writeFile(join(scaffold.workspaceCwd, PRODUCED), 'neutral\n')
+    await writeFile(join(scaffold.workspaceCwd, ACTIVE), '<h1>produced</h1>\n')
     const raw = await readFile(SEED, 'utf8')
-    expect(fixtureUserPrompts(raw), 'borrowed seed must carry the drive prompt').toEqual([PROMPT])
+    expect(raw, 'borrowed recording must carry the write this scenario reads').toContain(PRODUCED)
     await seedSession(scaffold, raw, SEED_ID)
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
@@ -53,7 +53,7 @@ describe('web e2e: opening a workspace file from a tool row', () => {
     await scaffold?.close()
   })
 
-  it.skipIf(MODE === 'record')('opens the read row’s file in a new tab, served from the session workspace', async () => {
+  it.skipIf(MODE === 'record')('ends the turn with its produced file, which opens as the workspace file itself', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-workspace-file-open'))
     const groupRow = page.locator('[role="treeitem"]').first()
     await groupRow.waitFor({ timeout: 15_000 })
@@ -61,26 +61,32 @@ describe('web e2e: opening a workspace file from a tool row', () => {
     const sessionRow = page.locator('[role="treeitem"]').nth(1)
     await sessionRow.waitFor({ timeout: 10_000 })
     await sessionRow.click()
-    await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBe(1)
 
-    // The row summary IS the link: a button whose label is the tool's path.
-    const fileLink = page.getByRole('button', { name: 'a.txt', exact: true }).first()
-    await fileLink.waitFor({ timeout: 10_000 })
+    // The row the turn ends with — derived from the write call's locations,
+    // not from whatever the closing message happened to say.
+    const chip = page.getByRole('button', { name: `Open ${PRODUCED}`, exact: true }).first()
+    await chip.waitFor({ timeout: 15_000 })
+    expect(await chip.innerText()).toBe(PRODUCED)
+
     const [opened] = await Promise.all([
       page.context().waitForEvent('page', { timeout: 15_000 }),
-      fileLink.click(),
+      chip.click(),
     ])
     await opened.waitForLoadState('domcontentloaded')
-    expect(new URL(opened.url()).pathname).toBe(`/f/${SEED_ID}/a.txt`)
-    expect(await opened.locator('body').innerText()).toContain('alpha')
+    expect(new URL(opened.url()).pathname).toBe(`/f/${SEED_ID}/${PRODUCED}`)
+    expect(await opened.locator('body').innerText()).toContain('neutral')
 
-    // The served response is a workspace read, not a download, and never cached
-    // past the turn that produced it.
     const served = await page.request.get(opened.url())
     expect(served.status()).toBe(200)
     expect(served.headers()['x-content-type-options']).toBe('nosniff')
     expect(served.headers()['cache-control']).toBe('no-store')
 
+    // A workspace file is not necessarily agent-authored, so an active document
+    // is served into an opaque origin rather than same-origin with /api.
+    const active = await page.request.get(`${scaffold.baseUrl}/f/${SEED_ID}/${ACTIVE}`)
+    expect(active.status()).toBe(200)
+    expect(active.headers()['content-security-policy']).toContain('sandbox')
+
     // Nothing outside the Session's workspace is reachable through the route.
     const escape = await page.request.get(`${scaffold.baseUrl}/f/${SEED_ID}/..%2Fetc%2Fhosts`)
     expect(escape.status()).toBe(404)
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 452ffe81c8..68e7f42e21 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
-README.md: ebc2dea2787268e1686eac24565c2433cb5f4b66
-README.zh.md: f5653e9e0e0aed3cbf7a9e6124668942f4dde44a
+README.md: cc7070500645f407b46f0326bf74479a81c579d8
+README.zh.md: 600b4f19d3262cb2381ec9368bc92b93db183603
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index ebc2dea278..cc70705006 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -12,10 +12,12 @@ The node half guards every request under `/api` before bridging (`src/api-reques
 
 The node half also serves one file at a time out of a Session's workspace under `/f/<sessionId>/<segments…>`, so a produced deliverable is reachable from the page that reported it — an `http` page cannot follow a `file://` link, and a browser that is not on the Host machine has no such path anyway. The segments ride the URL rather than a query parameter so a served document's relative references resolve to its siblings. The request names a Session and the gateway names that Session's directory (`ApiProxy.workspaceRootOf`, which answers from a live agent's header or the persistence store and never resumes an agent to serve a file); this package reads the authority rather than the core services, because holding their host-side Context declarations would merge them over the browser runtime's own. The URL shape itself lives with the other browser-importable contract surfaces, in [`@deepseek-ai/dsh-host-apiproxy/api`](../../host/apiproxy/README.md), so the browser half that builds a URL and this half that parses one share a single encoding decision. Both the cwd and the resolved target go through `realpath` before comparison, so a symlink inside the workspace pointing out of it is refused by its target rather than its name; traversal spellings are refused earlier still, at parse time, before any filesystem call. Reads stream (no request buffers a file), answer `GET`/`HEAD` only, and carry `nosniff` with `no-store`. Extensions outside the served content-type table are typed `text/plain` rather than offered as a download, because a workspace read is a request to see a file.
 
-A served document carries no isolation header and is same-origin with `/api`. That is a decision, not an omission: the only author of these files is the agent already holding this user's shell and filesystem, so a `Content-Security-Policy: sandbox` would sit behind a trust boundary it has already crossed while costing every preview its `localStorage` and cookies — a generated page that remembers a theme breaks under it. A deployment that serves `dsh web` beyond loopback should treat workspace content as trusted, which is already true of everything else its agent does. Isolating a preview becomes a real question when workspace content stops being the viewer's own; the answer then is a separate origin, not a header. The same trust fence gates this prefix, so a `trustedHosts` deployment serves workspace files exactly where it serves ordinary reads.
+Documents that can execute script — `.html`, `.htm`, `.xhtml`, `.svg` — additionally carry `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`, which runs them in an opaque origin. A workspace file is not necessarily agent-authored: a read row makes every file in a cloned repository openable, so an active document served same-origin with `/api` would have its script pass the browser-trust fence into every method, the loopback-pinned settings and credential plane included. The cost is borne by the preview — `localStorage`, cookies, and same-origin `fetch` are unavailable inside it, so a generated page that remembers a theme will not — and `host.openPath` remains the full-capability way to open the same file on the Host machine. Restoring those capabilities without reopening the hole needs a separate origin, not a weaker header. The same trust fence gates this prefix, so a `trustedHosts` deployment serves workspace files exactly where it serves ordinary reads.
 
 ## Keyless fixture
 
+The fixture carrier has no `/f` route, and `IWorkspaces.fileUrl` derives its URL in the browser regardless of carrier, so a file-path row clicked under `fixture=` opens a tab that 404s where the Host opener used to be a silent no-op. Fixture pages carry no file rows today; a fixture scenario that adds them should stub the derivation rather than teach the in-memory carrier to serve bytes.
+
 Any `fixture` query parameter selects the in-memory carrier. `fixture=empty` starts with no Workspace or Session; `fixturePrompt=reject` rejects prompts before acceptance; `fixtureAttach=fail` publishes a Session but rejects its Workspace attachment; `fixtureSessionCreate=drop-response` publishes and frames a Session before dropping the create response; and `fixtureFrames=workspace-first` reverses the default session-first create-frame order. Workspace creation by name/path and caller-preallocated SessionIds remain deterministic enough for assembled Web tests to reconcile list and frame arrival. Fixture content search preserves the production-facing `unicode61`-style case, diacritic, and token-phrase behavior and returns a match-centered snippet of at most 120 Unicode code points.
 
 ## Model Experience
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index f5653e9e0e..600b4f19d3 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -12,10 +12,12 @@ node 半侧在桥接前守卫 `/api` 下的每个请求（`src/api-request-trust
 
 node 半侧还会在 `/f/<sessionId>/<segments…>` 下逐个提供某个 Session 工作区里的文件，让产出的交付物能从报告它的那个页面直接抵达——`http` 页面无法跟随 `file://` 链接，而不在 Host 机器上的浏览器本来也没有那条路径。段落走 URL 而非查询参数，是为了让所服务文档的相对引用能解析到它的同级文件。请求指名一个 Session，由网关指名该 Session 的目录（`ApiProxy.workspaceRootOf`，它从活跃 agent 的 header 或持久化存储作答，绝不会为了提供一个文件而恢复 agent）；本包读取这个权威来源而不去够核心服务，因为持有它们的 host 侧 Context 声明会把它们盖到浏览器运行时自己的声明之上。URL 形状本身与其余浏览器可导入的契约面放在一起，位于 [`@deepseek-ai/dsh-host-apiproxy/api`](../../host/apiproxy/README.md)，因此构造 URL 的浏览器半侧与解析 URL 的这一半共享同一个编码决定。cwd 与解析出的目标在比较前都要过 `realpath`，因此工作区内指向工作区外的符号链接会因其目标而被拒绝，而不是因其名字；穿越写法拒得更早，在解析期、任何文件系统调用之前。读取是流式的（没有请求会把文件缓冲起来），只应答 `GET`／`HEAD`，并带上 `nosniff` 与 `no-store`。所服务的内容类型表之外的扩展名一律按 `text/plain` 定型而非作为下载给出，因为工作区读取本就是一个“让我看看这个文件”的请求。
 
-所服务的文档不带任何隔离头，与 `/api` 同源。这是一个决定，不是遗漏：这些文件的唯一作者，正是那个已经握着本用户 shell 与文件系统的 agent，因此 `Content-Security-Policy: sandbox` 只会立在一条它早已越过的信任边界之后，代价却是每个预览都失去 `localStorage` 与 cookie——一个会记住主题的生成页面在它之下就是坏的。把 `dsh web` 服务到回环之外的部署，应当把工作区内容按可信处理，而这一点对其 agent 所做的其他一切本来就已成立。当工作区内容不再属于观看者本人时，隔离预览才成为一个真问题；那时的答案是一个独立的源，而不是一个头。这条前缀由同一道信任 fence 把守，因此配置了 `trustedHosts` 的部署提供工作区文件的范围，与它提供普通读取的范围完全一致。
+能执行脚本的文档——`.html`、`.htm`、`.xhtml`、`.svg`——还会额外带上 `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`，让它们运行在不透明源中。工作区文件未必由 agent 撰写：一条 read 行就能让 clone 下来的仓库里任何文件变得可打开，因此与 `/api` 同源提供的活动文档，其脚本会带着浏览器信任 fence 通行到每一个方法，包括那些正因会改动设置与凭据而被钉在回环的方法。代价由预览承担——其中无法使用 `localStorage`、cookie 与同源 `fetch`，因此一个会记住主题的生成页面在预览里记不住——而 `host.openPath` 仍是在 Host 机器上以完整能力打开同一文件的方式。要在不重新打开这个洞的前提下取回那些能力，需要的是一个独立的源，而不是一个更弱的头。这条前缀由同一道信任 fence 把守，因此配置了 `trustedHosts` 的部署提供工作区文件的范围，与它提供普通读取的范围完全一致。
 
 ## 无密钥 fixture
 
+fixture 载体没有 `/f` 路由，而 `IWorkspaces.fileUrl` 无论载体为何都在浏览器侧推导 URL，因此在 `fixture=` 下点击文件路径行会打开一个 404 的标签页，而此处从前是 Host 打开器的静默空操作。今天的 fixture 页面并不含文件行；若某个 fixture 场景要加上它们，应当把这段推导打桩，而不是教这个内存载体去提供字节。
+
 任何 `fixture` 查询参数都会选择内存载体。`fixture=empty` 启动时不含 Workspace 或 Session；`fixturePrompt=reject` 在接受前拒绝提示词；`fixtureAttach=fail` 发布 Session 但拒绝将其附加到 Workspace；`fixtureSessionCreate=drop-response` 在丢弃创建响应前发布 Session 并为其发出帧；`fixtureFrames=workspace-first` 则反转默认的 Session 优先创建帧顺序。按名称／路径创建 Workspace 以及由调用方预先分配 SessionId，均具有足够的确定性，组装后的 Web 测试可以据此协调列表与帧的到达。fixture 内容搜索会保留面向生产环境的 `unicode61` 式大小写、变音符号和 token／短语行为，并返回以匹配位置为中心、最多包含 120 个 Unicode 码点的 snippet。
 
 ## 模型体验
diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts
index 4f9ce7d51b..59bab263ea 100644
--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -118,7 +118,8 @@ export function apply(ctx: Context, config?: ConnectionConfig): void {
         return
       }
       if (req.method !== 'GET' && req.method !== 'HEAD') {
-        res.writeHead(405)
+        // RFC 9110 §15.5.6: a 405 names the methods the resource does support.
+        res.writeHead(405, { allow: 'GET, HEAD' })
         res.end()
         return
       }
diff --git a/packages/client/connection/src/workspace-files.ts b/packages/client/connection/src/workspace-files.ts
index 354b7b2225..e173c33a40 100644
--- a/packages/client/connection/src/workspace-files.ts
+++ b/packages/client/connection/src/workspace-files.ts
@@ -10,13 +10,13 @@
  * owns the browser-trust fence ([api-request-trust](./api-request-trust.ts)) —
  * this module is reached only by requests that already passed it.
  *
- * A served document is same-origin with `/api`, and deliberately carries no
- * isolation header. The only author of these files is the agent already
- * holding this user's shell and filesystem, so a browser sandbox would not
- * move the trust boundary — it would sit behind one already crossed, at the
- * cost of `localStorage` and cookies in every preview. Isolating a preview
- * becomes a real question when workspace content stops being the viewer's own;
- * the answer then is a separate origin, not a header.
+ * Script-capable documents are served into an opaque origin. A workspace file
+ * is not necessarily agent-authored — a read row makes every file in a cloned
+ * repository openable — so an active document served same-origin with `/api`
+ * reaches the whole RPC surface, the loopback-pinned settings and credential
+ * methods included. The sandbox costs a preview its `localStorage` and
+ * cookies; restoring those without reopening that hole needs a separate
+ * origin, not a weaker header.
  */
 
 import { createReadStream } from 'node:fs'
@@ -59,6 +59,17 @@ const MIME: Record<string, string> = {
 
 const DEFAULT_MIME = 'text/plain; charset=utf-8'
 
+/** Extensions whose top-level navigation can execute script, and so need the sandbox. */
+const SCRIPTABLE = new Set(['.html', '.htm', '.xhtml', '.svg'])
+
+/**
+ * The opaque origin an active workspace document runs in. Without it the
+ * document is same-origin with `/api` and its script passes the browser-trust
+ * fence, which admits every method — including the ones pinned to loopback
+ * precisely because they mutate settings and credentials.
+ */
+const SANDBOX_CSP = 'sandbox allow-scripts allow-popups allow-modals allow-forms'
+
 /** How the route learns which directory a session may serve from. */
 export interface WorkspaceFileDeps {
   /**
@@ -85,8 +96,11 @@ function fail(res: ServerResponse, status: number): void {
  */
 async function confine(cwd: string, segments: readonly string[]): Promise<string | undefined> {
   const root = await realpath(cwd)
+  // A filesystem root already ends in the separator; appending a second one
+  // would make every child fail the prefix test and 403 the whole workspace.
+  const prefix = root.endsWith(sep) ? root : root + sep
   const real = await realpath(resolve(root, ...segments))
-  return real.startsWith(root + sep) ? real : undefined
+  return real.startsWith(prefix) ? real : undefined
 }
 
 /**
@@ -146,6 +160,7 @@ export async function handleWorkspaceFile(
     // Workspace files change under the agent's hands; a cached preview would
     // show the previous turn's output after the next edit.
     'cache-control': 'no-store',
+    ...SCRIPTABLE.has(ext) ? { 'content-security-policy': SANDBOX_CSP } : {},
   })
   if (req.method === 'HEAD') {
     res.end()
diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts
index 0b2c58ab37..8ab1fbce8e 100644
--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -34,11 +34,15 @@ function fakeRequest(headers: Record<string, string>, url = `${API_PATH}/session
 }
 
 /** Response recorder compatible with both the fence's short-circuit and the bridge. */
-function fakeResponse(): { response: ServerResponse; state: { status?: number; body?: unknown } } {
-  const state: { status?: number; body?: unknown } = {}
+function fakeResponse(): { response: ServerResponse; state: { status?: number; body?: unknown; headers?: Record<string, string> } } {
+  const state: { status?: number; body?: unknown; headers?: Record<string, string> } = {}
   const response = Object.assign(new EventEmitter(), {
     writableEnded: false,
-    writeHead(value: number) { state.status = value; return this },
+    writeHead(value: number, headers?: Record<string, string>) {
+      state.status = value
+      if (headers !== undefined) state.headers = headers
+      return this
+    },
     write() { return true },
     end(this: { writableEnded: boolean }, value?: unknown) {
       if (value !== undefined) state.body = value
@@ -177,6 +181,7 @@ describe('connection node half: the /f workspace-file route', () => {
     Object.assign(post, { method: 'POST' })
     await filesRoute(routes).handler(post, written.response)
     expect(written.state.status).toBe(405)
+    expect(written.state.headers).toMatchObject({ allow: 'GET, HEAD' })
     await dispose()
   })
 
diff --git a/packages/client/connection/tests/workspace-files.spec.ts b/packages/client/connection/tests/workspace-files.spec.ts
index eb36fdd6ea..6aee38e4d9 100644
--- a/packages/client/connection/tests/workspace-files.spec.ts
+++ b/packages/client/connection/tests/workspace-files.spec.ts
@@ -8,7 +8,7 @@ import type { AddressInfo } from 'node:net'
 import type { ServerResponse } from 'node:http'
 import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { join, sep } from 'node:path'
 import { Writable } from 'node:stream'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -37,7 +37,8 @@ beforeAll(async () => {
 
   const server = createServer((req, res) => {
     void handleWorkspaceFile(req, res, {
-      cwdFor: async sessionId => sessionId === SESSION ? workspace : undefined,
+      // 'rooted' names the filesystem root, the separator-terminated realpath case.
+      cwdFor: async sessionId => sessionId === SESSION ? workspace : sessionId === 'rooted' ? sep : undefined,
     })
   })
   await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
@@ -58,25 +59,35 @@ function get(path: string, init?: RequestInit): Promise<Response> {
 }
 
 describe('workspace file reads', () => {
-  it('serves a produced document with its own capabilities intact', async () => {
+  it('serves an active document into an opaque origin', async () => {
     const response = await get(`${FILES_PATH}/${SESSION}/index.html`)
     expect(response.status).toBe(200)
     expect(await response.text()).toBe('<h1>产物</h1>')
     expect(response.headers.get('content-type')).toBe('text/html; charset=utf-8')
-    // No isolation header: a preview keeps localStorage and cookies, because
-    // the file's author already holds this user's shell (see the module doc).
-    expect(response.headers.get('content-security-policy')).toBeNull()
+    // A workspace file is not necessarily agent-authored, and same-origin
+    // script here would pass the browser-trust fence into every RPC method.
+    expect(response.headers.get('content-security-policy')).toContain('sandbox')
+    expect(response.headers.get('content-security-policy')).not.toContain('allow-same-origin')
     expect(response.headers.get('x-content-type-options')).toBe('nosniff')
     expect(response.headers.get('cache-control')).toBe('no-store')
     expect(response.headers.get('content-disposition')).toBe('inline')
   })
 
-  it('types SVG as a standalone document rather than sniffable bytes', async () => {
+  it('sandboxes SVG too, and leaves inert types unrestricted', async () => {
     const svg = await get(`${FILES_PATH}/${SESSION}/chart.svg`)
     expect(svg.headers.get('content-type')).toBe('image/svg+xml')
-    expect(svg.headers.get('x-content-type-options')).toBe('nosniff')
+    expect(svg.headers.get('content-security-policy')).toContain('sandbox')
     const text = await get(`${FILES_PATH}/${SESSION}/notes.txt`)
     expect(text.headers.get('content-type')).toBe('text/plain; charset=utf-8')
+    expect(text.headers.get('content-security-policy')).toBeNull()
+  })
+
+  it('serves a workspace rooted at a filesystem root, whose realpath already ends in a separator', async () => {
+    // `realpath('/')` is '/', so a naive `root + sep` prefix is '//' and every
+    // child of that workspace would 403.
+    const rooted = await fetch(`${origin}${FILES_PATH}/rooted${new URL(`file://${workspace}/notes.txt`).pathname}`)
+    expect(rooted.status).toBe(200)
+    expect(await rooted.text()).toBe('plain')
   })
 
   it('shows an unknown extension as text rather than downloading it', async () => {
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 505d693bb6..2a2857839d 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: b61a70fb079eb6a1bc2a67b682a337ffdf708b79
-README.zh.md: 0bb1740b166cfacc2bc79fe2f49793796f66c365
+README.md: ba55f0704500034b7afb37258064fe0801aaee91
+README.zh.md: 4212908b355a81dfd5af8645ce5d4284a4555622
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index b61a70fb07..ba55f07045 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -14,7 +14,7 @@ Approvals take over the composer through the chain this package declares: `Appro
 
 Logged non-user messages render as a default-collapsed `上下文注入` disclosure. It shares the Tool calls header geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap, shows inline JSON for both `content` and `source`, and synthesizes no tool state, summary, or keyed toolview dispatch ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)).
 
-Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is a hover-underline link that opens the file with the host OS default application (`host.openPath`, relative paths resolve against the session cwd). Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
+Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is a hover-underline link that opens the file: one inside the session workspace opens in a new browser tab, served by the web transport's `/f` route, so a client that is not on the Host machine still sees it; one outside the workspace has no served URL and falls back to the Host OS default application (`host.openPath`, relative paths resolve against the session cwd). Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
 
 A tool call declaring the `terminal` render intent renders its command output inline, at both conversation render sites, through ui-primitives' `TerminalBlock`. `contract/terminal-card-model.ts` is the single derivation from the snapshot's `callView`/`resultView` pair, so the sites cannot disagree about a command, its cwd, or its exit status; it yields null — the generic path — for any other card tag, including one this client version does not know. Both sites therefore also show the card's run-state dot, which is the same `StateDot` semantic a tool row's leading icon carries, so a row and its own card always agree about one command's state. A multi-line command gets one prompt row per line, with the dot marking the call once on the first row — the exit status is the whole call's, so a dot per line would claim a per-line outcome bash does not report. The keyed `BashRow` carries the card resident below its summary row; since tool rows are no longer details-panel click targets, the card's copy and expand controls are the row's only interactions. The render-site fallback row keeps the card behind its existing expand control. Rows cap at `CHAT_TERMINAL_MAX_LINES` (8) against the panel's 16, which is what keeps a summary surface bounded — the panel stays the single-call reading surface. Inline output is licensed per render intent — the terminal and web cards, each with its own bound; a generic tool's content remains panel-only ([decision](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)).
 
@@ -42,6 +42,8 @@ The chat stats line takes its token accounting from two generic token-meter proj
 
 `src/client/` is organized for the future package split: `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations + composed slot props including the tool-row contract, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` (sample registrants) domain directories import contract files and never each other; `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components (skeleton, chat rows) and the store factory stay internal and reach the page exclusively through apply's slot registrations (tests take them via the `./src/*` subpath).
 
+A finished turn ends with the files it produced. `chat-flow.ts`'s `turnDeliverables` reads them off the mutation tools' own follow-along `locations` — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a turn's output is listed whether or not the closing message named it, and a new mutation tool joins by declaring what it does rather than by being added to a list. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row. The row renders under the closing assistant's body and above its IconActions, keyed to the same seq `assistantActionsSeqs` elects. It shows six chips (basename, full path as the title) plus an explicit remainder count, and each chip opens through the same `openFile` the tool rows use.
+
 ## Model Experience
 
 None, as the conversation UI renders session history and streams in the browser; nothing here reaches a model request.
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 0bb1740b16..4212908b35 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -12,7 +12,7 @@
 
 已记录的非用户消息渲染为默认折叠的 `上下文注入` 展开项。它通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 标题栏的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，并以内联 JSON 展示 `content` 和 `source`，且不会合成工具状态、摘要或键控 toolview 分发（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)）。
 
-通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是悬停下划线链接，点击后通过宿主操作系统的默认应用打开文件（`host.openPath`，相对路径相对会话 cwd 解析）。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
+通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是悬停下划线链接，点击即打开文件：位于会话工作区之内的文件在新浏览器标签页打开，由 web 传输的 `/f` 路由提供，因此不在 Host 机器上的客户端也能看到；工作区之外的文件没有可服务的 URL，回退到宿主操作系统的默认应用（`host.openPath`，相对路径相对会话 cwd 解析）。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
 
 声明 `terminal` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `TerminalBlock` 内联渲染其命令输出。`contract/terminal-card-model.ts` 是从快照的 `callView`／`resultView` 对推导的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧；对任何其他 card 标签——包括当前客户端版本不认识的标签——它返回 null，落回通用路径。因此两个渲染点也都显示卡片的运行状态点，它与工具行行首图标承载同一套 `StateDot` 语义，所以一行与其自身的卡片对同一条命令的状态总是一致。多行命令的每一行各占一个提示行，状态点只在第一行为整次调用标记一次——退出状态属于整次调用，因此每行一枚就会声称一个 bash 并不报告的逐行结果。键控的 `BashRow` 把卡片常驻在摘要行下方；由于工具行已不再是详情面板的点击目标，卡片的复制与展开控件就是该行唯一的交互。渲染点兜底行则保持其既有的展开控件。行的上限是 `CHAT_TERMINAL_MAX_LINES`（8），面板为 16，正是这一点让摘要面保持有界——面板仍是单次调用的阅读面。内联输出按渲染意图开放——终端卡片与 web 卡片，各有自己的上限；通用工具的内容仍然只在面板中呈现（[决策](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)）。
 
@@ -42,6 +42,8 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插
 
 `src/client/` 按未来的包拆分组织：`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明 + 组合后的 slot props，包括工具行契约、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/`（示例注册方）领域目录只导入 contract 文件，彼此绝不导入；`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件（骨架、聊天行）与 store factory 保持内部状态，只能通过 apply 的 slot 注册到达页面（测试通过 `./src/*` 子路径获取它们）。
 
+完成的一轮以它产出的文件收尾。`chat-flow.ts` 的 `turnDeliverables` 从改写工具自身的跟随文件 `locations` 中读出它们——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，这一轮的产出都会被列出；新的改写工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。该行渲染在收尾 assistant 正文之下、其 IconActions 之上，键控到 `assistantActionsSeqs` 选出的同一个 seq。它展示六枚 chip（文本为文件名，完整路径作为 title），外加一个显式的剩余计数，每枚 chip 都经由工具行所用的同一个 `openFile` 打开。
+
 ## 模型体验
 
 无。会话 UI 在浏览器中渲染会话历史与流；这里没有任何内容进入模型请求。
diff --git a/packages/client/ui-conversation/src/client/chat/chat-flow.ts b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
index 83ba5c463c..7b5c53d7ac 100644
--- a/packages/client/ui-conversation/src/client/chat/chat-flow.ts
+++ b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
@@ -32,6 +32,21 @@ function rendersNothing(node: ConversationNode): boolean {
       || ((b.kind === 'text' || b.kind === 'reasoning') && b.text.trim() === ''))
 }
 
+/**
+ * Paths a call view reports having created or changed, by render intent rather
+ * than tool name: a diff card, or a generic card whose kind is `edit` (the
+ * shape `str_replace_editor`'s insert presents). Every other card produces
+ * nothing to open — a read looked, a delete removed, a terminal ran.
+ */
+function producedPaths(view: ToolResultNode['callView']): readonly string[] {
+  if (view === null) return []
+  if (view.card === 'diff') return (view.locations ?? []).map(location => location.path)
+  if (view.card === 'generic' && view.kind === 'edit') {
+    return (view.locations ?? []).map(location => location.path)
+  }
+  return []
+}
+
 /**
  * Seq set of assistants that own IconActions: the last content-text assistant
  * in each turn. Mid-turn narration (text before tools) stays chrome-free.
@@ -54,10 +69,19 @@ export function assistantActionsSeqs(nodes: readonly ConversationNode[]): Readon
  *
  * The source is the mutation tools' own follow-along `locations`, not the
  * closing prose: a produced file must be listed whether or not the model
- * remembered to name it. Reads contribute nothing (looking at a file does not
- * produce it) and a failed mutation contributes nothing (there is no file to
- * open). Paths keep first-seen order and appear once, so a file written and
- * then edited in the same turn is one entry.
+ * remembered to name it. A mutation is recognized by render intent, not by
+ * tool name — a diff card, or a generic card whose `kind` is `edit` (the shape
+ * `str_replace_editor`'s insert presents) — so a new mutation tool joins by
+ * declaring what it does. Reads contribute nothing (looking at a file does not
+ * produce it), and neither do deletes (there is nothing left to open) or
+ * failed calls. Paths keep first-seen order and appear once, so a file written
+ * and then edited in the same turn is one entry.
+ *
+ * Accumulation resets on the turn boundary, not merely at the closing
+ * assistant: a turn that mutates files and then ends without content text
+ * (interrupted mid-tool, or a turn whose last text precedes its last tool
+ * result) must not spill its paths into the next turn's row, nor leave `seen`
+ * suppressing a file the next turn legitimately rewrites.
  * @param nodes - snapshot nodes (surface order).
  * @returns Per-closing-seq produced paths; a turn that produced none is absent.
  */
@@ -65,21 +89,37 @@ export function turnDeliverables(nodes: readonly ConversationNode[]): ReadonlyMa
   const closing = assistantActionsSeqs(nodes)
   const byClosingSeq = new Map<number, readonly string[]>()
   let pending: string[] = []
-  const seen = new Set<string>()
+  let seen = new Set<string>()
+  let turn: number | undefined
   for (const node of nodes) {
     if (node.kind === 'tool-result') {
-      if (node.isError || node.callView?.card !== 'diff') continue
-      for (const location of node.callView.locations ?? []) {
-        if (seen.has(location.path)) continue
-        seen.add(location.path)
-        pending.push(location.path)
+      if (node.isError) continue
+      for (const path of producedPaths(node.callView)) {
+        if (seen.has(path)) continue
+        seen.add(path)
+        pending.push(path)
       }
       continue
     }
+    // Tool results carry no turn of their own, so the boundary is read off the
+    // nodes that do. A user message opens a turn without reporting a number,
+    // which is why the tracked turn goes back to undefined there: the next
+    // node to report one is stating the current turn, not entering a new one.
+    if (node.kind === 'user') {
+      turn = undefined
+      pending = []
+      seen = new Set()
+    } else if ('turn' in node) {
+      if (turn !== undefined && node.turn !== turn) {
+        pending = []
+        seen = new Set()
+      }
+      turn = node.turn
+    }
     if (node.kind !== 'assistant' || !closing.has(node.seq)) continue
     if (pending.length > 0) byClosingSeq.set(node.seq, pending)
     pending = []
-    seen.clear()
+    seen = new Set()
   }
   return byClosingSeq
 }
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index 6f855231ac..d95d1db9ff 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -241,6 +241,38 @@ describe('chat-flow derivation', () => {
     expect(turnDeliverables([user(1, 'hi'), assistant(2, 'hello', 1)]).size).toBe(0)
   })
 
+  it('turnDeliverables counts a generic edit and never spills across the turn boundary', () => {
+    const inserted = (seq: number, callId: string, path: string): ToolResultNode => ({
+      ...toolResult(seq, callId, 'str_replace_editor'),
+      // str_replace_editor's insert mutates behind a generic card, so the
+      // discriminant is the render intent, not the card shape alone.
+      callView: { card: 'generic', title: `insert ${path}`, kind: 'edit', locations: [{ path }] },
+    })
+    const wrote = (seq: number, callId: string, path: string): ToolResultNode => ({
+      ...toolResult(seq, callId, 'write'),
+      callView: {
+        card: 'diff', title: 'Write', diffs: [{ path, oldText: null, newText: 'x' }], locations: [{ path }],
+      },
+    })
+    const produced = turnDeliverables([
+      user(1, 'insert a line'),
+      inserted(2, 'i', 'notes.md'),
+      assistant(3, 'inserted', 1),
+      // Turn 2 mutates and then ends with no content text (interrupted, or its
+      // last text preceded the tool): its paths must not ride into turn 3.
+      user(4, 'now rewrite it'),
+      wrote(5, 'w', 'leaked.txt'),
+      user(6, 'and again'),
+      wrote(7, 'w2', 'notes.md'),
+      assistant(8, 'done', 3),
+    ])
+    expect(produced.get(3)).toEqual(['notes.md'])
+    // Turn 3 lists only its own file — and `seen` did not suppress the rewrite
+    // of a path an earlier turn already touched.
+    expect(produced.get(8)).toEqual(['notes.md'])
+    expect([...produced.values()].flat()).not.toContain('leaked.txt')
+  })
+
   it('renders the produced files under the closing message and opens one on click', () => {
     const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
       ...toolResult(seq, callId, 'write'),
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 3c20785657..63e1f0007c 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -2299,6 +2299,10 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       if (live !== undefined) return live.session.header.cwd
       const persistence = ctx.get('sessionPersistence')
       if (persistence === undefined) return undefined
+      // TODO(persistence/by-id): a full listing per lookup. Harmless while the
+      // caller is one preview open, but a served document with N relative
+      // sub-resources pays it N times; a by-id header read on the persistence
+      // seam would retire it.
       return (await persistence.list()).find(meta => meta.id === sessionId)?.cwd
     },
   }

From 59bfe77fb821eeadcea4b97cbb50981d04b556bd Mon Sep 17 00:00:00 2001
From: ZiyaZhang <zzy211851@gmail.com>
Date: Sat, 1 Aug 2026 02:17:25 -0700
Subject: [PATCH 010/516] feat(web): serve workspace files from their own
 origin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A sandbox header bought isolation by taking the document's origin away, and
measuring that cost decided against it: the reported artifact throws
SecurityError on load, and because an uncaught exception aborts the rest of
its <script>, every listener declared after that line — theme toggle, mobile
menu, model tabs — never binds. Two of the four artifacts in the reporting
user's workspace were dead pages under it, and they still looked right.

A second listener on the API's host, answering /f and nothing else, is the
same boundary without the amputation: cross-origin to /api (refused by the
Origin fence and by CORS), same-origin with itself (localStorage, cookies and
fetch all work). Its port is published into the index page; the browser half
reads it to address previews, and its absence — the keyless fixture lane — is
what makes a file row fall back to the Host opener instead of a dead tab.

fileUrl moves from IWorkspaces to ConnectionHandle: the transport owns both
the listener that serves the bytes and the port that addresses it.
---
 ...6-07-31-web-workspace-file-links.i18n.yaml |   4 +-
 .../2026-07-31-web-workspace-file-links.md    |  10 +-
 .../2026-07-31-web-workspace-file-links.zh.md |  10 +-
 apps/web/tests/workspace-file-open.e2e.ts     |  42 ++++--
 docs/config-catalog.md                        |   2 +-
 packages/client/connection/README.i18n.yaml   |   4 +-
 packages/client/connection/README.md          |   4 +-
 packages/client/connection/README.zh.md       |   4 +-
 .../client/connection/src/client/index.ts     |  25 ++++
 .../client/connection/src/files-server.ts     | 127 ++++++++++++++++++
 packages/client/connection/src/index.ts       |  41 +++---
 .../client/connection/src/workspace-files.ts  |  24 +---
 .../connection/tests/client-apply.spec.ts     |  27 +++-
 .../connection/tests/files-server.spec.ts     |  44 ++++++
 .../client/connection/tests/node-half.spec.ts | 110 +++++++++------
 .../connection/tests/workspace-files.spec.ts  |  14 +-
 .../runtime/src/client/contract/workspaces.ts |  11 --
 .../runtime/src/client/workspaces/service.ts  |  13 --
 .../client/runtime/tests/client-apply.spec.ts |   1 +
 .../client/runtime/tests/wire-events.spec.ts  |   1 +
 .../runtime/tests/workspaces-service.spec.ts  |  15 ---
 packages/client/test-runtime/package.json     |   2 +
 .../client/test-runtime/src/connection.ts     |  48 +++++++
 packages/client/test-runtime/src/index.ts     |   6 +
 .../client/test-runtime/src/workspaces.ts     |  16 ---
 .../test-runtime/tests/runtime.spec.tsx       |   9 +-
 packages/client/test-runtime/tsconfig.json    |   3 +
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +-
 packages/client/ui-conversation/README.zh.md  |   2 +-
 packages/client/ui-conversation/package.json  |   2 +
 .../ui-conversation/src/client/apply.ts       |  14 +-
 .../tests/apply-inject.spec.tsx               |   9 +-
 .../tests/chat-code-subcalls.spec.tsx         |   6 +-
 .../tests/chat-toolview-slot.spec.tsx         |   1 +
 packages/client/ui-conversation/tsconfig.json |   3 +
 pnpm-lock.yaml                                |   6 +
 37 files changed, 469 insertions(+), 197 deletions(-)
 create mode 100644 packages/client/connection/src/files-server.ts
 create mode 100644 packages/client/connection/tests/files-server.spec.ts
 create mode 100644 packages/client/test-runtime/src/connection.ts

diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index 584f3c899d..e8510d24e5 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.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 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
-2026-07-31-web-workspace-file-links.md: a4bd8a2fecc2f1cb29d61a575b1ae0d31e5ebdd3
-2026-07-31-web-workspace-file-links.zh.md: 1d001710b2548343cb811fd6cca282cf956e95d9
+2026-07-31-web-workspace-file-links.md: 8eeb96517aa905e77e50ce36f0efb704353c0821
+2026-07-31-web-workspace-file-links.zh.md: 63d746b0a9aabaf78ba5653e16705bd662a54126
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
index a4bd8a2fec..8eeb96517a 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
@@ -20,9 +20,9 @@ The parts were nearly all present, pointed at the wrong target. `ToolRow` alread
 
 **The URL shape lives in `dsh-host-apiproxy/api`, with the other browser-importable contract surfaces.** Both ends must agree on one encoding, but a client bundle may not value-import another plugin's package: the purity gate in `packages/client/tsdown.client.ts` allows only platform modules and the `INLINE_SAFE` wire layers, of which apiproxy is one. Putting `api/files.ts` there is what lets the browser half build a URL and the serving half parse it from a single source, and it needed no new package edge — both sides already depend on apiproxy.
 
-**Script-capable documents are served into an opaque origin.** `.html`/`.htm`/`.xhtml`/`.svg` carry `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`. The decision was briefly taken the other way, on the premise that these files are agent-authored and their author already holds this user's shell, so a browser sandbox would sit behind a trust boundary already crossed. Review falsified the premise: a workspace file need not be agent-authored at all — a read row makes every file in a cloned repository openable — and a same-origin active document was measured driving `/api/settings.describe` to a `200` with full data, so the loopback-pinned settings and credential plane was reachable from a page nobody in this session wrote. The cost is real and stays: a preview has no `localStorage` or cookies, so a generated page that remembers a theme will not. Restoring that without reopening the hole needs a separate origin, which is a different change; `host.openPath` remains the full-capability way to open the same file.
+**Workspace files get their own port, and therefore their own origin.** The isolation question was worked three ways before landing here. A sandbox header came first, on the reasoning that `/api/events.mux` is a readable same-origin `GET` stream. It was then dropped on the premise that these files are agent-authored, so a browser boundary would sit behind one already crossed — a premise review falsified: a read row makes every file in a cloned repository openable, and a same-origin active document was measured driving `/api/settings.describe` to a `200` with full data, reaching the loopback-pinned settings and credential plane from a page nobody in this session wrote. Restoring the sandbox closed that, and measuring what it cost decided the final shape: under `CSP: sandbox` the report's own artifact throws `SecurityError` on load, and because an uncaught exception aborts the rest of its `<script>`, every listener declared after that line — theme toggle, mobile menu, model tabs — never binds. Two of the four artifacts in the reporting user's workspace were dead pages under it, and they still *looked* right. A second port is the boundary without the amputation: cross-origin to `/api` (refused by the fence's Origin check and by CORS), same-origin with itself (so `localStorage`, cookies, and `fetch` all work). It binds the same host as the API so LAN previews keep working, answers `/f` and nothing else, and publishes its port into the index page for the browser half to address.
 
-**The client decides by derivation, not by probing.** `IWorkspaces.fileUrl(sessionId, cwd, path)` expresses a tool-reported path as segments below the session cwd and returns the origin-relative URL, or `undefined` when the path leaves the workspace. `undefined` is exactly the signal to fall back to `openPath`, so a file outside the workspace behaves as it did before and no capability negotiation is needed.
+**The client decides by derivation, not by probing.** `ConnectionHandle.fileUrl(sessionId, cwd, path)` expresses a tool-reported path as segments below the session cwd and returns an absolute URL on the workspace-file origin — the page's own hostname, the published port — or `undefined` when the path leaves the workspace or no port was published. It lives on the connection handle because the transport owns both ends: the listener that serves the bytes and the port that addresses it. `undefined` is exactly the signal to fall back to `openPath`, which is also what makes the keyless fixture lane (served by no host) degrade to the old behavior instead of opening a dead tab.
 
 ## Alternatives considered
 
@@ -30,10 +30,10 @@ The parts were nearly all present, pointed at the wrong target. `ToolRow` alread
 - **A dedicated `dsh-client-workspace-files` package** — the honest seam shape if file serving were an independent capability. It is not: it needs the same fence and the same `trustedHosts` value as `/api`, and splitting would have duplicated both against the repository's own "don't split preemptively" rule.
 - **Keeping the URL-shape module in `client-connection` and importing it from the runtime** — the first cut, and the build refused it: a cross-plugin value import into a client bundle either inlines a duplicate runtime instance or names a specifier the frozen module table cannot answer. The gate is the reason the shared module sits in the wire layer rather than in the package that happens to own the route.
 - **`/f/<absolute path>`, so `openPath` could stay the single call site** — drops the sessionId from the URL, but then the served authority becomes the union of every workspace the host knows. The tight authority costs exactly one call-site edit, because `openFile` already has both the sessionId and the cwd in scope.
-- **`connect-src 'none'` plus a navigation fence, to keep `localStorage` working under isolation** — measurably viable against the SSE-read vector (Chrome sends `Sec-Fetch-Dest: document` for `window.open` and `empty` for `EventSource`, loopback included), but it never addressed the larger one: same-origin `fetch` to a POST method is what reaches the configuration plane, and blocking `connect-src` from the served document is exactly what a hostile document would not do to itself. Only an origin boundary contains it.
-- **Serving `/f` from its own loopback port** — the one option that keeps both isolation and preview capabilities, and the shape a separate-origin answer would take. Deferred, not rejected: it needs a second listener with its own lifecycle plus the port plumbed to the client, which is a change of a different size than this one.
+- **`connect-src 'none'` plus a navigation fence, to keep `localStorage` working under a sandbox** — measurably viable against the SSE-read vector (Chrome sends `Sec-Fetch-Dest: document` for `window.open` and `empty` for `EventSource`, loopback included), but it never addressed the larger one: same-origin `fetch` to a POST method is what reaches the configuration plane, and blocking `connect-src` from the served document is exactly what a hostile document would not do to itself.
+- **Keeping the sandbox and accepting the limitation** — the honest reading of that trade only became visible once measured: it is not "a preview cannot remember a theme" but "a preview's entire script dies at its first storage access", on pages that still render perfectly. A limitation nobody can see is worse than one that costs a port.
 - **Linkifying paths in the assistant's closing message** — the shape a user asks for ("put the link at the end"), but it makes rendering depend on the model spelling a path recognizably. The tool calls already carry `locations` as structured fact, so the produced-files row consumes that instead; linkifying the prose stays unnecessary rather than merely deferred.
 
 ## Consequences
 
-Every existing file affordance changed target at once: write, edit, read, and the generic single-file card all reach `openFile`, so one call-site edit made produced files openable in the browser, LAN clients included. Three tests asserting the old `openPath` destination were rewritten to the new one; the outside-workspace fallback keeps the old assertion. The route is covered against a real HTTP server and a real temporary workspace, because confinement, content typing, and the sandbox header are wire facts, and the assembled web lane (`apps/web/tests/workspace-file-open.e2e.ts`, keyless over a cold-seeded session) proves the product path: clicking a read row's path opens `/f/<sessionId>/a.txt` in a second tab serving that workspace file, while a traversal spelling answers 404. A preview runs without `localStorage` or cookies, visible on generated pages that persist a theme — the Host opener remains for those, and a separate serving origin is the way to retire the limitation. The produced-files row ships here too: `turnDeliverables` reads a turn's output off the mutation tools' render intent (a diff card, or a generic card whose `kind` is `edit`), resets on the turn boundary so an interrupted turn cannot spill into the next, and renders under the closing assistant. Still deferred: linkification inside assistant Markdown, and any cross-session view of past deliverables.
+Every existing file affordance changed target at once: write, edit, read, and the generic single-file card all reach `openFile`, so one call-site edit made produced files openable in the browser, LAN clients included. Three tests asserting the old `openPath` destination were rewritten to the new one; the outside-workspace fallback keeps the old assertion. The route is covered against a real HTTP server and a real temporary workspace, because confinement, content typing, and the sandbox header are wire facts, and the assembled web lane (`apps/web/tests/workspace-file-open.e2e.ts`, keyless over a cold-seeded session) proves the product path: clicking a read row's path opens `/f/<sessionId>/a.txt` in a second tab serving that workspace file, while a traversal spelling answers 404. A preview runs with its own origin's full capabilities, so a generated page behaves as its author intended. The residual the port does not close: two Sessions share one workspace-file origin, so a document from one may fetch another's served files. That is strictly narrower than the API surface it replaces, and narrowing it further would mean an origin per Session, which nothing today needs. The produced-files row ships here too: `turnDeliverables` reads a turn's output off the mutation tools' render intent (a diff card, or a generic card whose `kind` is `edit`), resets on the turn boundary so an interrupted turn cannot spill into the next, and renders under the closing assistant. Still deferred: linkification inside assistant Markdown, and any cross-session view of past deliverables.
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index 1d001710b2..63d746b0a9 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -20,9 +20,9 @@ Status: implemented
 
 **URL 形状落在 `dsh-host-apiproxy/api`，与其余浏览器可导入的契约面同处一地。** 两端必须就同一套编码达成一致，但客户端 bundle 不允许值导入另一个插件的包：`packages/client/tsdown.client.ts` 里的纯度 gate 只放行平台模块与 `INLINE_SAFE` 协议层，而 apiproxy 正是其中之一。把 `api/files.ts` 放在那里，才使构造 URL 的浏览器半侧与解析它的服务半侧共用单一来源，而且没有新增任何包依赖边——两侧本来就依赖 apiproxy。
 
-**能执行脚本的文档被送进不透明源。** `.html`／`.htm`／`.xhtml`／`.svg` 带上 `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`。这个决定曾短暂地被判向另一边，前提是这些文件由 agent 撰写、而其作者已经握着本用户的 shell，因此浏览器 sandbox 只会立在一条早已越过的信任边界之后。评审推翻了这个前提：工作区文件根本不必由 agent 撰写——一条 read 行就让 clone 下来的仓库里任何文件变得可打开——而同源的活动文档经实测能把 `/api/settings.describe` 打到 `200` 并拿到完整数据，也就是说被钉在回环的设置与凭据面，可以被一个本次会话中无人撰写的页面触达。代价真实且保留：预览没有 `localStorage` 与 cookie，因此会记住主题的生成页面在其中记不住。要在不重新打开这个洞的前提下取回它，需要一个独立的源，那是另一个尺寸的改动；`host.openPath` 仍是以完整能力打开同一文件的方式。
+**工作区文件获得自己的端口，因而拥有自己的源。** 隔离这件事在落到此处之前走了三步。最初是加 sandbox 头，理由是 `/api/events.mux` 是一条同源可读的 `GET` 流。随后它被拿掉，前提是这些文件由 agent 撰写、浏览器边界只会立在一条早已越过的边界之后——而评审推翻了这个前提：一条 read 行就让 clone 下来的仓库里任何文件变得可打开，而同源的活动文档经实测能把 `/api/settings.describe` 打到 `200` 并拿到完整数据，从一个本次会话中无人撰写的页面触达了被钉在回环的设置与凭据面。加回 sandbox 堵住了它，而“量清楚它的代价”决定了最终形状：在 `CSP: sandbox` 之下，报告中那份产物加载时就抛 `SecurityError`，又因为未捕获异常会中止其 `<script>` 的其余部分，该行之后声明的所有监听器——主题切换、移动端菜单、模型 tabs——统统不会绑定。报告者工作区里四份产物有两份在它之下是死页面，而且它们**看上去**仍然正常。第二个端口给出了这条边界而无需截肢：对 `/api` 是跨源（被 fence 的 Origin 校验与 CORS 双重拒绝），对自身是同源（因此 `localStorage`、cookie 与 `fetch` 都可用）。它绑定与 API 相同的 host，因此 LAN 预览继续可用；只应答 `/f`，别无其他；并把端口注入首页供浏览器半侧寻址。
 
-**客户端靠推导决定，而不是靠探测。** `IWorkspaces.fileUrl(sessionId, cwd, path)` 把工具报告的路径表达为 session cwd 之下的段落并返回相对于源的 URL，路径离开工作区时返回 `undefined`。`undefined` 恰好就是回退到 `openPath` 的信号，因此工作区外的文件行为与以往一致，也不需要任何能力协商。
+**客户端靠推导决定，而不是靠探测。** `ConnectionHandle.fileUrl(sessionId, cwd, path)` 把工具报告的路径表达为 session cwd 之下的段落，并返回工作区文件源上的绝对 URL——页面自身的主机名，加上已发布的端口——路径离开工作区或没有端口发布时返回 `undefined`。它落在 connection 句柄上，是因为传输层同时持有两端：提供字节的监听器，和寻址它的端口。`undefined` 恰好就是回退到 `openPath` 的信号，这也让无密钥 fixture 通道（不由任何 host 提供）退化为旧行为，而不是打开一个空标签页。
 
 ## 考虑过的替代方案
 
@@ -30,10 +30,10 @@ Status: implemented
 - **单开一个 `dsh-client-workspace-files` 包**——如果文件服务是一项独立能力，这才是诚实的 seam 形状。它不是：它需要与 `/api` 相同的 fence 和相同的 `trustedHosts` 值，拆分会把两者都复制一份，违背仓库自己的“不要预先拆分”。
 - **把 URL 形状模块留在 `client-connection` 里、由 runtime 去导入**——最初就是这么写的，构建直接拒绝：向客户端 bundle 做跨插件值导入，要么内联出一份重复的运行时实例，要么落到冻结模块表答不出的说明符上。这道 gate 正是共享模块落在协议层、而非落在恰好持有该路由的那个包里的原因。
 - **`/f/<绝对路径>`，好让 `openPath` 保持为唯一调用点**——这会把 sessionId 从 URL 里去掉，但所服务的权限边界随之变成 host 已知的全部工作区之并集。紧的权限边界只花掉一处调用点的改动，因为 `openFile` 本来就同时持有 sessionId 与 cwd。
-- **用 `connect-src 'none'` 加一道导航栅栏，在保持隔离的同时保住 `localStorage`**——针对“读走 SSE 流”这条向量经实测可行（Chrome 对 `window.open` 发 `Sec-Fetch-Dest: document`、对 `EventSource` 发 `empty`，回环也在内），但它从未触及更大的那条：真正够到配置面的是向 POST 方法发起的同源 `fetch`，而“从所服务文档一侧封住 `connect-src`”恰恰是敌意文档不会对自己做的事。只有源边界能收住它。
-- **让 `/f` 跑在自己的回环端口上**——唯一能同时保住隔离与预览能力的选项，也是“独立的源”这个答案该有的形状。是暂缓而非否决：它需要一个带自身生命周期的第二监听器，外加把端口铺到客户端，那是另一个尺寸的改动。
+- **用 `connect-src 'none'` 加一道导航栅栏，在 sandbox 之下保住 `localStorage`**——针对“读走 SSE 流”这条向量经实测可行（Chrome 对 `window.open` 发 `Sec-Fetch-Dest: document`、对 `EventSource` 发 `empty`，回环也在内），但它从未触及更大的那条：真正够到配置面的是向 POST 方法发起的同源 `fetch`，而“从所服务文档一侧封住 `connect-src`”恰恰是敌意文档不会对自己做的事。
+- **保留 sandbox 并接受这条限制**——这笔交易的真实读数要量过才看得见：它不是“预览记不住主题”，而是“预览的整段脚本在第一次访问存储时就死了”，而页面照样渲染得完美无缺。一条没人看得见的限制，比一条要花掉一个端口的限制更糟。
 - **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带，产出文件行消费的正是它；因此把正文链接化是不必要，而不只是被推迟。
 
 ## 影响
 
-现有的每一处文件交互都同时换了目标：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此一处调用点的改动就让产出的文件在浏览器里可打开，LAN 客户端也在内。三个断言旧 `openPath` 去向的测试被改写为新的去向；工作区外的回退保留了旧断言。这条路由对着真实 HTTP 服务器与真实临时工作区做覆盖，因为收敛、内容定型与 sandbox 头都是协议事实；而组装后的 web 通道（`apps/web/tests/workspace-file-open.e2e.ts`，在冷播种会话上无密钥运行）证明了产品路径：点击读取行的路径会在第二个标签页打开 `/f/<sessionId>/a.txt` 并提供那个工作区文件，而穿越写法应答 404。预览在没有 `localStorage` 与 cookie 的情况下运行，这在会持久化主题的生成页面上看得见——那些场景仍有 Host 打开器，而独立的服务源是退休这条限制的路。产出文件行也在本次一并落地：`turnDeliverables` 依据改写工具的渲染意图（diff 卡片，或 `kind` 为 `edit` 的 generic 卡片）读出一轮的产出，在 turn 边界重置以免中断的一轮溢进下一轮，并渲染在收尾 assistant 之下。仍然暂缓：助手 Markdown 内部的链接化，以及任何跨会话回看既往产物的视图。
+现有的每一处文件交互都同时换了目标：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此一处调用点的改动就让产出的文件在浏览器里可打开，LAN 客户端也在内。三个断言旧 `openPath` 去向的测试被改写为新的去向；工作区外的回退保留了旧断言。这条路由对着真实 HTTP 服务器与真实临时工作区做覆盖，因为收敛、内容定型与 sandbox 头都是协议事实；而组装后的 web 通道（`apps/web/tests/workspace-file-open.e2e.ts`，在冷播种会话上无密钥运行）证明了产品路径：点击读取行的路径会在第二个标签页打开 `/f/<sessionId>/a.txt` 并提供那个工作区文件，而穿越写法应答 404。预览以自身源的完整能力运行，因此生成的页面按其作者的意图工作。端口没有堵住的残余：两个 Session 共用同一个工作区文件源，因此来自其一的文档可以 fetch 另一个已服务的文件。这比它所替代的 API 面严格更窄，而要再窄一层就意味着每个 Session 一个源，今天没有任何需求指向那里。产出文件行也在本次一并落地：`turnDeliverables` 依据改写工具的渲染意图（diff 卡片，或 `kind` 为 `edit` 的 generic 卡片）读出一轮的产出，在 turn 边界重置以免中断的一轮溢进下一轮，并渲染在收尾 assistant 之下。仍然暂缓：助手 Markdown 内部的链接化，以及任何跨会话回看既往产物的视图。
diff --git a/apps/web/tests/workspace-file-open.e2e.ts b/apps/web/tests/workspace-file-open.e2e.ts
index 98d239beb1..8f6bd6f665 100644
--- a/apps/web/tests/workspace-file-open.e2e.ts
+++ b/apps/web/tests/workspace-file-open.e2e.ts
@@ -73,25 +73,49 @@ describe('web e2e: opening a produced file from the conversation', () => {
       chip.click(),
     ])
     await opened.waitForLoadState('domcontentloaded')
-    expect(new URL(opened.url()).pathname).toBe(`/f/${SEED_ID}/${PRODUCED}`)
+    const url = new URL(opened.url())
+    expect(url.pathname).toBe(`/f/${SEED_ID}/${PRODUCED}`)
     expect(await opened.locator('body').innerText()).toContain('neutral')
 
+    // The isolation: previews come from the app's hostname on a DIFFERENT
+    // port, so a served document is cross-origin to /api while keeping its own
+    // capabilities. A workspace file is not necessarily agent-authored.
+    const app = new URL(scaffold.baseUrl)
+    expect(url.hostname).toBe(app.hostname)
+    expect(url.port).not.toBe(app.port)
+    const filesOrigin = url.origin
+
     const served = await page.request.get(opened.url())
     expect(served.status()).toBe(200)
     expect(served.headers()['x-content-type-options']).toBe('nosniff')
     expect(served.headers()['cache-control']).toBe('no-store')
+    // No document is stripped of its origin: the port is the boundary.
+    expect(served.headers()['content-security-policy']).toBeUndefined()
 
-    // A workspace file is not necessarily agent-authored, so an active document
-    // is served into an opaque origin rather than same-origin with /api.
-    const active = await page.request.get(`${scaffold.baseUrl}/f/${SEED_ID}/${ACTIVE}`)
-    expect(active.status()).toBe(200)
-    expect(active.headers()['content-security-policy']).toContain('sandbox')
+    // An active document keeps its own storage — the capability a sandbox
+    // header would have taken, and the reason this route has its own port.
+    const active = opened
+    await active.goto(`${filesOrigin}/f/${SEED_ID}/${ACTIVE}`, { waitUntil: 'load' })
+    expect(await active.evaluate(() => {
+      try { window.localStorage.setItem('probe', '1'); return 'ok' } catch { return 'blocked' }
+    })).toBe('ok')
+    // …and cannot reach the API, which lives on the other origin.
+    expect(await active.evaluate(async (base) => {
+      try {
+        await fetch(`${base}/api/session.list`, {
+          method: 'POST', headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ type: 'client-request', rpcId: 'x', method: 'session.list', payload: {} }),
+        })
+        return 'reached'
+      } catch { return 'blocked' }
+    }, scaffold.baseUrl)).toBe('blocked')
 
+    // The workspace-file origin serves that one prefix and nothing else.
+    expect((await page.request.get(`${filesOrigin}/`)).status()).toBe(404)
     // Nothing outside the Session's workspace is reachable through the route.
-    const escape = await page.request.get(`${scaffold.baseUrl}/f/${SEED_ID}/..%2Fetc%2Fhosts`)
-    expect(escape.status()).toBe(404)
+    expect((await page.request.get(`${filesOrigin}/f/${SEED_ID}/..%2Fetc%2Fhosts`)).status()).toBe(404)
 
-    await opened.close()
+    await active.close()
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
   }, 90_000)
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 114e2bdb35..7c21713f01 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -296,7 +296,7 @@ export interface ConnectionConfig {
 }
 ```
 
-Source: [`packages/client/connection/src/index.ts:26`](../packages/client/connection/src/index.ts)
+Source: [`packages/client/connection/src/index.ts:25`](../packages/client/connection/src/index.ts)
 
 ## `@deepseek-ai/dsh-client-hmr`
 
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 68e7f42e21..af7d3d590d 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
-README.md: cc7070500645f407b46f0326bf74479a81c579d8
-README.zh.md: 600b4f19d3262cb2381ec9368bc92b93db183603
+README.md: 5001da2458ea3470659f5983dffc8de832aadeac
+README.zh.md: 47e745964e4087c6ccc59aae5bbfba69f96480e4
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index cc70705006..5001da2458 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -12,11 +12,11 @@ The node half guards every request under `/api` before bridging (`src/api-reques
 
 The node half also serves one file at a time out of a Session's workspace under `/f/<sessionId>/<segments…>`, so a produced deliverable is reachable from the page that reported it — an `http` page cannot follow a `file://` link, and a browser that is not on the Host machine has no such path anyway. The segments ride the URL rather than a query parameter so a served document's relative references resolve to its siblings. The request names a Session and the gateway names that Session's directory (`ApiProxy.workspaceRootOf`, which answers from a live agent's header or the persistence store and never resumes an agent to serve a file); this package reads the authority rather than the core services, because holding their host-side Context declarations would merge them over the browser runtime's own. The URL shape itself lives with the other browser-importable contract surfaces, in [`@deepseek-ai/dsh-host-apiproxy/api`](../../host/apiproxy/README.md), so the browser half that builds a URL and this half that parses one share a single encoding decision. Both the cwd and the resolved target go through `realpath` before comparison, so a symlink inside the workspace pointing out of it is refused by its target rather than its name; traversal spellings are refused earlier still, at parse time, before any filesystem call. Reads stream (no request buffers a file), answer `GET`/`HEAD` only, and carry `nosniff` with `no-store`. Extensions outside the served content-type table are typed `text/plain` rather than offered as a download, because a workspace read is a request to see a file.
 
-Documents that can execute script — `.html`, `.htm`, `.xhtml`, `.svg` — additionally carry `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`, which runs them in an opaque origin. A workspace file is not necessarily agent-authored: a read row makes every file in a cloned repository openable, so an active document served same-origin with `/api` would have its script pass the browser-trust fence into every method, the loopback-pinned settings and credential plane included. The cost is borne by the preview — `localStorage`, cookies, and same-origin `fetch` are unavailable inside it, so a generated page that remembers a theme will not — and `host.openPath` remains the full-capability way to open the same file on the Host machine. Restoring those capabilities without reopening the hole needs a separate origin, not a weaker header. The same trust fence gates this prefix, so a `trustedHosts` deployment serves workspace files exactly where it serves ordinary reads.
+Workspace files are served from their own port, and therefore their own origin. That port is the isolation: a workspace file is not necessarily agent-authored — a read row makes every file in a cloned repository openable — so an active document served beside `/api` would have its script pass the browser-trust fence into every method, the loopback-pinned settings and credential plane included. A different origin closes that without touching the document: a preview keeps `localStorage`, cookies, and its own `fetch`, while a call to the API is cross-origin and refused twice over — by the fence's Origin check and by CORS. The alternative, `Content-Security-Policy: sandbox`, buys the same boundary by taking the document's origin away entirely, which measurably breaks the pages this route exists to show (a page that reads `localStorage` throws on load, and every listener declared after that line in the same script never binds). The listener binds the same host as the API, so a client that can reach the app can reach its previews; it answers the `/f` prefix and nothing else — no index, no SPA fallback, no API — and its port is published into the index page as `window.__DSH_FILES_PORT__`, which the browser half reads to address it. The same trust fence gates it, so a `trustedHosts` deployment serves workspace files exactly where it serves ordinary reads.
 
 ## Keyless fixture
 
-The fixture carrier has no `/f` route, and `IWorkspaces.fileUrl` derives its URL in the browser regardless of carrier, so a file-path row clicked under `fixture=` opens a tab that 404s where the Host opener used to be a silent no-op. Fixture pages carry no file rows today; a fixture scenario that adds them should stub the derivation rather than teach the in-memory carrier to serve bytes.
+A fixture page is served by no host, so no workspace-file port is published into it and `ConnectionHandle.fileUrl` answers `undefined` — a file-path row falls back to the Host opener rather than opening a dead tab.
 
 Any `fixture` query parameter selects the in-memory carrier. `fixture=empty` starts with no Workspace or Session; `fixturePrompt=reject` rejects prompts before acceptance; `fixtureAttach=fail` publishes a Session but rejects its Workspace attachment; `fixtureSessionCreate=drop-response` publishes and frames a Session before dropping the create response; and `fixtureFrames=workspace-first` reverses the default session-first create-frame order. Workspace creation by name/path and caller-preallocated SessionIds remain deterministic enough for assembled Web tests to reconcile list and frame arrival. Fixture content search preserves the production-facing `unicode61`-style case, diacritic, and token-phrase behavior and returns a match-centered snippet of at most 120 Unicode code points.
 
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index 600b4f19d3..47e745964e 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -12,11 +12,11 @@ node 半侧在桥接前守卫 `/api` 下的每个请求（`src/api-request-trust
 
 node 半侧还会在 `/f/<sessionId>/<segments…>` 下逐个提供某个 Session 工作区里的文件，让产出的交付物能从报告它的那个页面直接抵达——`http` 页面无法跟随 `file://` 链接，而不在 Host 机器上的浏览器本来也没有那条路径。段落走 URL 而非查询参数，是为了让所服务文档的相对引用能解析到它的同级文件。请求指名一个 Session，由网关指名该 Session 的目录（`ApiProxy.workspaceRootOf`，它从活跃 agent 的 header 或持久化存储作答，绝不会为了提供一个文件而恢复 agent）；本包读取这个权威来源而不去够核心服务，因为持有它们的 host 侧 Context 声明会把它们盖到浏览器运行时自己的声明之上。URL 形状本身与其余浏览器可导入的契约面放在一起，位于 [`@deepseek-ai/dsh-host-apiproxy/api`](../../host/apiproxy/README.md)，因此构造 URL 的浏览器半侧与解析 URL 的这一半共享同一个编码决定。cwd 与解析出的目标在比较前都要过 `realpath`，因此工作区内指向工作区外的符号链接会因其目标而被拒绝，而不是因其名字；穿越写法拒得更早，在解析期、任何文件系统调用之前。读取是流式的（没有请求会把文件缓冲起来），只应答 `GET`／`HEAD`，并带上 `nosniff` 与 `no-store`。所服务的内容类型表之外的扩展名一律按 `text/plain` 定型而非作为下载给出，因为工作区读取本就是一个“让我看看这个文件”的请求。
 
-能执行脚本的文档——`.html`、`.htm`、`.xhtml`、`.svg`——还会额外带上 `Content-Security-Policy: sandbox allow-scripts allow-popups allow-modals allow-forms`，让它们运行在不透明源中。工作区文件未必由 agent 撰写：一条 read 行就能让 clone 下来的仓库里任何文件变得可打开，因此与 `/api` 同源提供的活动文档，其脚本会带着浏览器信任 fence 通行到每一个方法，包括那些正因会改动设置与凭据而被钉在回环的方法。代价由预览承担——其中无法使用 `localStorage`、cookie 与同源 `fetch`，因此一个会记住主题的生成页面在预览里记不住——而 `host.openPath` 仍是在 Host 机器上以完整能力打开同一文件的方式。要在不重新打开这个洞的前提下取回那些能力，需要的是一个独立的源，而不是一个更弱的头。这条前缀由同一道信任 fence 把守，因此配置了 `trustedHosts` 的部署提供工作区文件的范围，与它提供普通读取的范围完全一致。
+工作区文件由它自己的端口提供，因而拥有自己的源。那个端口就是隔离：工作区文件未必由 agent 撰写——一条 read 行就能让 clone 下来的仓库里任何文件变得可打开——因此与 `/api` 并排提供的活动文档，其脚本会带着浏览器信任 fence 通行到每一个方法，包括那些正因会改动设置与凭据而被钉在回环的方法。换一个源即可堵死这条，且不必动文档本身：预览保有 `localStorage`、cookie 与自己的 `fetch`，而对 API 的调用属于跨源，会被两道独立的关卡拒绝——fence 的 Origin 校验，以及 CORS。另一种做法 `Content-Security-Policy: sandbox` 用"干脆剥夺文档的源"换来同一条边界，而这经实测会破坏本路由存在的意义所在的那类页面（读 `localStorage` 的页面在加载时抛异常，同一 script 块中该行之后声明的所有监听器都不会绑定）。该监听器绑定与 API 相同的 host，因此能访问应用的客户端也能访问它的预览；它只应答 `/f` 前缀，别无其他——没有首页、没有 SPA 兜底、没有 API——其端口以 `window.__DSH_FILES_PORT__` 注入首页，由浏览器半侧读取来寻址。它由同一道信任 fence 把守，因此配置了 `trustedHosts` 的部署提供工作区文件的范围，与它提供普通读取的范围完全一致。
 
 ## 无密钥 fixture
 
-fixture 载体没有 `/f` 路由，而 `IWorkspaces.fileUrl` 无论载体为何都在浏览器侧推导 URL，因此在 `fixture=` 下点击文件路径行会打开一个 404 的标签页，而此处从前是 Host 打开器的静默空操作。今天的 fixture 页面并不含文件行；若某个 fixture 场景要加上它们，应当把这段推导打桩，而不是教这个内存载体去提供字节。
+fixture 页面不由任何 host 提供，因此没有工作区文件端口注入其中，`ConnectionHandle.fileUrl` 应答 `undefined`——文件路径行会回退到 Host 打开器，而不是打开一个空标签页。
 
 任何 `fixture` 查询参数都会选择内存载体。`fixture=empty` 启动时不含 Workspace 或 Session；`fixturePrompt=reject` 在接受前拒绝提示词；`fixtureAttach=fail` 发布 Session 但拒绝将其附加到 Workspace；`fixtureSessionCreate=drop-response` 在丢弃创建响应前发布 Session 并为其发出帧；`fixtureFrames=workspace-first` 则反转默认的 Session 优先创建帧顺序。按名称／路径创建 Workspace 以及由调用方预先分配 SessionId，均具有足够的确定性，组装后的 Web 测试可以据此协调列表与帧的到达。fixture 内容搜索会保留面向生产环境的 `unicode61` 式大小写、变音符号和 token／短语行为，并返回以匹配位置为中心、最多包含 120 个 Unicode 码点的 snippet。
 
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index e286157e46..004b9fe286 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -4,6 +4,9 @@
  * controller with its sinks.
  */
 import type { Context } from 'cordis'
+import { workspaceFileSegments, workspaceFileUrl } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { FILES_PORT_GLOBAL } from '../files-server.ts'
 import type { IApiClient } from './api.ts'
 import { ConnectionController, type ConnectionConfig, type ConnectionSinks, type ConnectionState } from './connection.ts'
 import { FixtureApiClient } from './fixture.ts'
@@ -56,6 +59,19 @@ export interface ConnectionHandle {
    * @returns stop handle for the loop.
    */
   start(sinks: ConnectionSinks, config?: ConnectionConfig): { stop(): void }
+  /**
+   * Absolute URL serving one file out of a Session's workspace, on the
+   * transport's own workspace-file origin — the same hostname the page is
+   * reached by, a different port, so a served document is isolated from this
+   * API without being stripped of its own capabilities.
+   * @param sessionId - the Session whose cwd anchors the path.
+   * @param cwd - that Session's working directory, or `undefined` when unknown.
+   * @param path - the path a tool reported (absolute, or relative to `cwd`).
+   * @returns the URL, or `undefined` when the path lies outside the workspace
+   * (which this transport never serves) or when this page was not served by a
+   * host that published a workspace-file port (the fixture carrier).
+   */
+  fileUrl(sessionId: SessionId, cwd: string | undefined, path: string): string | undefined
 }
 
 /**
@@ -68,6 +84,15 @@ export function apply(ctx: Context): void {
   let started = false
   const handle: ConnectionHandle = {
     api,
+    fileUrl(sessionId, cwd, path) {
+      // Published by the node half's index tap; absent means no host is
+      // serving workspace files to this page (the keyless fixture lane).
+      const port = (globalThis as unknown as Record<string, unknown>)[FILES_PORT_GLOBAL]
+      if (typeof port !== 'number') return undefined
+      const segments = workspaceFileSegments(cwd, path)
+      if (segments === undefined) return undefined
+      return `${location.protocol}//${location.hostname}:${String(port)}${workspaceFileUrl(sessionId, segments)}`
+    },
     start(sinks, config) {
       if (started) throw new Error('connection: the stream loop is already owned by another consumer')
       started = true
diff --git a/packages/client/connection/src/files-server.ts b/packages/client/connection/src/files-server.ts
new file mode 100644
index 0000000000..73807c0810
--- /dev/null
+++ b/packages/client/connection/src/files-server.ts
@@ -0,0 +1,127 @@
+/**
+ * The workspace-file listener: a second loopback/LAN socket on the same host
+ * as the API, serving nothing but `/f`.
+ *
+ * The port is the isolation. A workspace file is not necessarily
+ * agent-authored — a read row makes every file in a cloned repository
+ * openable — so an active document must not be same-origin with `/api`, where
+ * its script would pass the browser-trust fence into every method, the
+ * loopback-pinned settings and credential plane included. A different port is
+ * a different origin, which the browser enforces for free: the document keeps
+ * `localStorage`, cookies, and its own `fetch`, while a call to the API is
+ * cross-origin and refused twice over — by the fence's Origin check and by
+ * CORS. The alternative, `Content-Security-Policy: sandbox`, buys the same
+ * boundary by taking the document's origin away entirely, which measurably
+ * breaks the pages this route exists to show.
+ */
+
+import { createServer } from 'node:http'
+import type { IncomingMessage, Server, ServerResponse } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { isTrustedApiRequest } from './api-request-trust.ts'
+import { handleWorkspaceFile, type WorkspaceFileDeps } from './workspace-files.ts'
+
+/** A listening workspace-file server: its port, and the teardown that reaches quiescence. */
+export interface FilesServer {
+  /** The bound port (OS-assigned), which the browser half needs to address this origin. */
+  port: number
+  /** Close the socket and destroy held connections; resolves once quiet. */
+  close: () => Promise<void>
+}
+
+/**
+ * Bind the workspace-file listener.
+ * @param host - the same bind host the API uses, so a client that can reach
+ * the app can reach its previews (a LAN deployment included).
+ * @param trustedHosts - the deployment's non-loopback serving authorities,
+ * applied through the same fence as `/api`.
+ * @param deps - the session-to-directory lookup reads are confined by.
+ * @param onSocketError - reports a post-listen socket error; without a
+ * listener node would raise it as an unhandled 'error' event.
+ * @returns the bound port and its disposer.
+ */
+export async function listenForWorkspaceFiles(
+  host: string,
+  trustedHosts: readonly string[],
+  deps: WorkspaceFileDeps,
+  onSocketError: (error: Error) => void,
+): Promise<FilesServer> {
+  const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    if (!isTrustedApiRequest(req, trustedHosts)) {
+      res.writeHead(403)
+      res.end('forbidden')
+      return
+    }
+    /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server requests. */
+    const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
+    // This origin serves one prefix and nothing else: no index, no SPA
+    // fallback, no API. Anything else is not here — answered before the method
+    // check, because a 405 would claim the resource exists.
+    if (pathname !== FILES_PATH && !pathname.startsWith(`${FILES_PATH}/`)) {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      // RFC 9110 §15.5.6: a 405 names the methods the resource does support.
+      res.writeHead(405, { allow: 'GET, HEAD' })
+      res.end()
+      return
+    }
+    await handleWorkspaceFile(req, res, deps)
+  }
+
+  const server: Server = createServer((req, res) => {
+    handle(req, res).catch((error: unknown) => {
+      // A malformed request must not become an unhandled rejection that takes
+      // the process down; the API carrier guards its own handler the same way.
+      if (res.headersSent) {
+        res.destroy()
+        return
+      }
+      onSocketError(error instanceof Error ? error : new Error(String(error)))
+      res.writeHead(400)
+      res.end()
+    })
+  })
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, host, () => {
+      server.off('error', reject)
+      server.on('error', onSocketError)
+      resolve()
+    })
+  })
+
+  return {
+    port: (server.address() as AddressInfo).port,
+    // close + closeAllConnections: a held-open response would otherwise keep
+    // teardown waiting forever.
+    close: () => new Promise<void>((resolve) => {
+      server.close(() => { resolve() })
+      server.closeAllConnections()
+    }),
+  }
+}
+
+/** The global the node half hands its port to the browser half through. */
+export const FILES_PORT_GLOBAL = '__DSH_FILES_PORT__'
+
+/**
+ * Inject the workspace-file port into index.html, ahead of the shell bundle
+ * that reads it. A boot-time fact of the serving host, delivered the way the
+ * module graph is: synchronously on the page, so the first click on a produced
+ * file does not race a round trip.
+ * @param html - the index.html source.
+ * @param port - the bound workspace-file port.
+ * @returns the html with the port script injected.
+ */
+export function injectFilesPort(html: string, port: number): string {
+  const script = `<script>window.${FILES_PORT_GLOBAL} = ${String(port)}</script>`
+  const head = html.indexOf('<head>')
+  if (head !== -1) return `${html.slice(0, head + 6)}${script}${html.slice(head + 6)}`
+  /* v8 ignore next -- headless fixture pages may lack <head>; prepending keeps read-before-shell ordering. */
+  return `${script}${html}`
+}
diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts
index 59bab263ea..f0a60bbfb9 100644
--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -4,14 +4,13 @@ import z from 'schemastery'
 // Activates the httpServer Context merge used below.
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
-import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
 // The merge-free types subpath: pulling the session package's root into this
 // client-registered program would merge the host `sessions` service over the
 // browser runtime's own.
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { API_PATH } from './api-path.ts'
 import { bridge } from './http-bridge.ts'
-import { handleWorkspaceFile } from './workspace-files.ts'
+import { injectFilesPort, listenForWorkspaceFiles } from './files-server.ts'
 import { assertTrustedAuthority, isTrustedApiRequest } from './api-request-trust.ts'
 
 export { API_PATH } from './api-path.ts'
@@ -74,8 +73,10 @@ const PRIVILEGED_METHODS = new Set([
  * additionally pass it with an empty trust list, which pins them to loopback.
  * @param ctx - Host plugin context.
  * @param config - resolved plugin config (schema defaults applied).
+ * @returns a promise settling once the workspace-file listener is bound and
+ * its port published — the page must never render before it can address one.
  */
-export function apply(ctx: Context, config?: ConnectionConfig): void {
+export async function apply(ctx: Context, config?: ConnectionConfig): Promise<void> {
   // The Loader resolves schema defaults; hand-built test contexts may pass none.
   const trustedHosts = config?.trustedHosts ?? []
   // Config boundary: a malformed entry fails the load loudly here rather than
@@ -108,23 +109,19 @@ export function apply(ctx: Context, config?: ConnectionConfig): void {
   // would merge their host-side Context declarations into the browser lane.
   const cwdFor = (sessionId: string): Promise<string | undefined> =>
     ctx.apiProxy.workspaceRootOf(sessionId as SessionId)
-  const filesRoute: WebRoute = {
-    kind: 'prefix',
-    path: FILES_PATH,
-    handler: async (req, res) => {
-      if (!isTrustedApiRequest(req, trustedHosts)) {
-        res.writeHead(403)
-        res.end('forbidden')
-        return
-      }
-      if (req.method !== 'GET' && req.method !== 'HEAD') {
-        // RFC 9110 §15.5.6: a 405 names the methods the resource does support.
-        res.writeHead(405, { allow: 'GET, HEAD' })
-        res.end()
-        return
-      }
-      await handleWorkspaceFile(req, res, { cwdFor })
-    },
-  }
-  ctx.effect(() => ctx.httpServer.register(filesRoute), 'client-connection: /f route')
+  // Workspace files get their own port, and therefore their own origin: an
+  // active document served beside `/api` would reach every method through the
+  // fence below. The listen is awaited inside the effect so the port is known
+  // before the index tap that publishes it can run.
+  await ctx.effect(async () => {
+    const files = await listenForWorkspaceFiles(
+      ctx.httpServer.host, trustedHosts, { cwdFor },
+      (error) => { ctx.logger.error(error) },
+    )
+    const untap = ctx.httpServer.tapIndex(html => injectFilesPort(html, files.port))
+    return async () => {
+      untap()
+      await files.close()
+    }
+  }, 'client-connection: /f listener')
 }
diff --git a/packages/client/connection/src/workspace-files.ts b/packages/client/connection/src/workspace-files.ts
index e173c33a40..c934b14516 100644
--- a/packages/client/connection/src/workspace-files.ts
+++ b/packages/client/connection/src/workspace-files.ts
@@ -10,13 +10,11 @@
  * owns the browser-trust fence ([api-request-trust](./api-request-trust.ts)) —
  * this module is reached only by requests that already passed it.
  *
- * Script-capable documents are served into an opaque origin. A workspace file
- * is not necessarily agent-authored — a read row makes every file in a cloned
- * repository openable — so an active document served same-origin with `/api`
- * reaches the whole RPC surface, the loopback-pinned settings and credential
- * methods included. The sandbox costs a preview its `localStorage` and
- * cookies; restoring those without reopening that hole needs a separate
- * origin, not a weaker header.
+ * Isolation is the listener's, not this module's: these responses carry no
+ * sandbox header because they are served from their own port, and therefore
+ * their own origin ([files-server](./files-server.ts)). A served document
+ * keeps `localStorage`, cookies, and its own `fetch`, while the API stays
+ * cross-origin to it.
  */
 
 import { createReadStream } from 'node:fs'
@@ -59,17 +57,6 @@ const MIME: Record<string, string> = {
 
 const DEFAULT_MIME = 'text/plain; charset=utf-8'
 
-/** Extensions whose top-level navigation can execute script, and so need the sandbox. */
-const SCRIPTABLE = new Set(['.html', '.htm', '.xhtml', '.svg'])
-
-/**
- * The opaque origin an active workspace document runs in. Without it the
- * document is same-origin with `/api` and its script passes the browser-trust
- * fence, which admits every method — including the ones pinned to loopback
- * precisely because they mutate settings and credentials.
- */
-const SANDBOX_CSP = 'sandbox allow-scripts allow-popups allow-modals allow-forms'
-
 /** How the route learns which directory a session may serve from. */
 export interface WorkspaceFileDeps {
   /**
@@ -160,7 +147,6 @@ export async function handleWorkspaceFile(
     // Workspace files change under the agent's hands; a cached preview would
     // show the previous turn's output after the next edit.
     'cache-control': 'no-store',
-    ...SCRIPTABLE.has(ext) ? { 'content-security-policy': SANDBOX_CSP } : {},
   })
   if (req.method === 'HEAD') {
     res.end()
diff --git a/packages/client/connection/tests/client-apply.spec.ts b/packages/client/connection/tests/client-apply.spec.ts
index 6892dc7721..4b323182bb 100644
--- a/packages/client/connection/tests/client-apply.spec.ts
+++ b/packages/client/connection/tests/client-apply.spec.ts
@@ -8,10 +8,11 @@ import { apply, type ConnectionHandle } from '../src/client/index.ts'
 import { FixtureApiClient } from '../src/client/fixture.ts'
 import { WebApiClient } from '../src/client/web-api-client.ts'
 
-type Win = { location?: { search: string } }
+type Win = { location?: { search: string; protocol?: string; hostname?: string }; __DSH_FILES_PORT__?: number }
 
 afterEach(() => {
   delete (globalThis as Win).location
+  delete (globalThis as Win).__DSH_FILES_PORT__
 })
 
 async function mount(): Promise<ConnectionHandle> {
@@ -62,4 +63,28 @@ describe('connection client apply', () => {
     }
     expect(seen.some(u => u.includes('/api/'))).toBe(true)
   })
+
+  it('addresses a workspace file on the port the host published, and only inside the workspace', async () => {
+    const win = globalThis as Win
+    win.location = { search: '', protocol: 'http:', hostname: '192.168.1.5' }
+    win.__DSH_FILES_PORT__ = 4321
+    const handle = await mount()
+    const session = 's-1' as never
+    // Same hostname the page was reached by — a LAN client must reach previews
+    // too — and the published port, which is what makes it another origin.
+    expect(handle.fileUrl(session, '/w/alpha', '/w/alpha/out/a b.html'))
+      .toBe('http://192.168.1.5:4321/f/s-1/out/a%20b.html')
+    // Outside the workspace there is nothing this transport may serve, which
+    // is the signal a caller falls back to openPath on.
+    expect(handle.fileUrl(session, '/w/alpha', '/etc/hosts')).toBeUndefined()
+  })
+
+  it('serves no file URL on a page no host published a port into', async () => {
+    const win = globalThis as Win
+    win.location = { search: '?fixture', protocol: 'http:', hostname: '127.0.0.1' }
+    const handle = await mount()
+    // The keyless fixture lane: no workspace-file origin exists, so the row
+    // falls back to the Host opener instead of opening a dead tab.
+    expect(handle.fileUrl('s-1' as never, '/w', 'a.txt')).toBeUndefined()
+  })
 })
diff --git a/packages/client/connection/tests/files-server.spec.ts b/packages/client/connection/tests/files-server.spec.ts
new file mode 100644
index 0000000000..4a2618709b
--- /dev/null
+++ b/packages/client/connection/tests/files-server.spec.ts
@@ -0,0 +1,44 @@
+/** The workspace-file listener's own failure and publication paths. */
+import { describe, expect, it } from 'vitest'
+import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { injectFilesPort, listenForWorkspaceFiles } from '../src/files-server.ts'
+
+describe('workspace-file listener', () => {
+  it('answers 400 and reports the failure when the directory lookup throws', async () => {
+    const seen: Error[] = []
+    const files = await listenForWorkspaceFiles(
+      '127.0.0.1', [],
+      { cwdFor: () => Promise.reject(new Error('store unavailable')) },
+      (error) => { seen.push(error) },
+    )
+    try {
+      // A lookup failure is the host's problem, not a miss: it must not become
+      // an unhandled rejection, and it must not be reported as "not found".
+      const response = await fetch(`http://127.0.0.1:${String(files.port)}${FILES_PATH}/s-1/a.txt`)
+      expect(response.status).toBe(400)
+      expect(seen.map(error => error.message)).toEqual(['store unavailable'])
+    } finally {
+      await files.close()
+    }
+  })
+
+  it('closes idempotently and stops answering', async () => {
+    const files = await listenForWorkspaceFiles(
+      '127.0.0.1', [], { cwdFor: async () => undefined }, () => {},
+    )
+    const origin = `http://127.0.0.1:${String(files.port)}`
+    expect((await fetch(`${origin}${FILES_PATH}/s-1/a.txt`)).status).toBe(404)
+    await files.close()
+    await files.close()
+    await expect(fetch(`${origin}${FILES_PATH}/s-1/a.txt`)).rejects.toThrow()
+  })
+})
+
+describe('injectFilesPort', () => {
+  it('publishes the port as the first script in head', () => {
+    const html = injectFilesPort('<html><head><title>x</title></head></html>', 4321)
+    expect(html).toContain('<head><script>window.__DSH_FILES_PORT__ = 4321</script>')
+    // Ahead of anything the shell might read it from.
+    expect(html.indexOf('__DSH_FILES_PORT__')).toBeLessThan(html.indexOf('<title>'))
+  })
+})
diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts
index 8ab1fbce8e..2561a0846f 100644
--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -15,14 +15,21 @@ import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { API_PATH, apply, inject } from '../src/index.ts'
 
 /** Structural httpServer fake: the plugin only touches register(). */
-function fakeHttpServer(routes: WebRoute[]): Pick<HttpServerService, 'register' | 'tapIndex' | 'port'> {
+function fakeHttpServer(
+  routes: WebRoute[],
+  taps: ((html: string) => string)[] = [],
+): Pick<HttpServerService, 'register' | 'tapIndex' | 'port' | 'host'> {
   return {
     register(route) {
       routes.push(route)
       return () => { routes.splice(routes.indexOf(route), 1) }
     },
-    tapIndex: () => () => {},
+    tapIndex(transform) {
+      taps.push(transform)
+      return () => { taps.splice(taps.indexOf(transform), 1) }
+    },
     port: 0,
+    host: '127.0.0.1',
   }
 }
 
@@ -61,21 +68,39 @@ function fakeApiProxy(workspaces: Record<string, string> = {}): ApiProxy {
 async function mounted(
   config?: { trustedHosts?: string[] },
   workspaces: Record<string, string> = {},
-): Promise<{ routes: WebRoute[]; dispose: () => Promise<void> }> {
+): Promise<{ routes: WebRoute[]; taps: ((html: string) => string)[]; dispose: () => Promise<void> }> {
   const ctx = new Context()
   const routes: WebRoute[] = []
-  ctx.provide('httpServer', fakeHttpServer(routes) as HttpServerService)
+  const taps: ((html: string) => string)[] = []
+  ctx.provide('httpServer', fakeHttpServer(routes, taps) as HttpServerService)
   ctx.provide('apiProxy', fakeApiProxy(workspaces))
   const fiber = ctx.plugin({ inject: [...inject], apply }, config)
   await fiber.await()
-  return { routes, dispose: () => fiber.dispose() }
+  return { routes, taps, dispose: () => fiber.dispose() }
 }
 
-/** The /f route is registered after /api; both are prefix routes on the same server. */
-function filesRoute(routes: WebRoute[]): WebRoute {
-  const route = routes.find(candidate => candidate.path === FILES_PATH)
-  if (route === undefined) throw new Error('the /f route was not registered')
-  return route
+/** One raw GET whose Host header is spoofed (fetch forbids setting it). */
+function statusWithHost(origin: string, path: string, host: string): Promise<number> {
+  const url = new URL(origin)
+  return new Promise((resolve, reject) => {
+    const request = httpRequest(
+      { host: url.hostname, port: url.port, path, method: 'GET', headers: { host } },
+      (response) => {
+        response.resume()
+        response.on('end', () => { resolve(response.statusCode ?? 0) })
+      },
+    )
+    request.on('error', reject)
+    request.end()
+  })
+}
+
+/** The workspace-file origin the node half published into the index page. */
+function filesOrigin(taps: ((html: string) => string)[]): string {
+  const html = taps.reduce((acc, tap) => tap(acc), '<head></head>')
+  const port = /__DSH_FILES_PORT__ = (\d+)/.exec(html)?.[1]
+  if (port === undefined) throw new Error(`no workspace-file port was published: ${html}`)
+  return `http://127.0.0.1:${port}`
 }
 
 describe('connection node half', () => {
@@ -89,11 +114,19 @@ describe('connection node half', () => {
     expect(routes).toHaveLength(0)
   })
 
-  it('registers both transport prefix routes and removes them with the fiber', async () => {
-    const { routes, dispose } = await mounted()
-    expect(routes).toMatchObject([{ kind: 'prefix', path: API_PATH }, { kind: 'prefix', path: FILES_PATH }])
+  it('registers the /api route and publishes a separate workspace-file origin, both removed with the fiber', async () => {
+    const { routes, taps, dispose } = await mounted()
+    // The API keeps one prefix on the shared server; workspace files get a
+    // port of their own, which is the origin boundary between them.
+    expect(routes).toMatchObject([{ kind: 'prefix', path: API_PATH }])
+    const origin = filesOrigin(taps)
+    expect(new URL(origin).port).not.toBe('')
+    expect((await fetch(`${origin}${FILES_PATH}/absent/x.txt`)).status).toBe(404)
     await dispose()
     expect(routes).toHaveLength(0)
+    expect(taps).toHaveLength(0)
+    // Disposal reaches quiescence: the socket is gone, not merely unrouted.
+    await expect(fetch(`${origin}${FILES_PATH}/absent/x.txt`)).rejects.toThrow()
   })
 
   it('refuses an untrusted Host on any /api path before the bridge runs', async () => {
@@ -154,7 +187,7 @@ describe('connection node half', () => {
   })
 })
 
-describe('connection node half: the /f workspace-file route', () => {
+describe('connection node half: the workspace-file origin', () => {
   /** A workspace holding one file, torn down with the returned disposer. */
   async function workspace(): Promise<{ cwd: string; remove: () => Promise<void> }> {
     const cwd = await mkdtemp(join(tmpdir(), 'dsh-node-half-'))
@@ -162,40 +195,35 @@ describe('connection node half: the /f workspace-file route', () => {
     return { cwd, remove: () => rm(cwd, { recursive: true, force: true }) }
   }
 
-  /** HEAD keeps the assertion on the route's decision, not on the byte stream. */
-  function head(url: string, headers: Record<string, string> = { host: '127.0.0.1:3080' }): IncomingMessage {
-    const request = fakeRequest(headers, url)
-    Object.assign(request, { method: 'HEAD' })
-    return request
-  }
-
-  it('applies the same browser-trust fence as /api, and refuses writes', async () => {
-    const { routes, dispose } = await mounted()
-    const untrusted = fakeResponse()
-    await filesRoute(routes).handler(head(`${FILES_PATH}/s-1/index.html`, { host: 'harness.example' }), untrusted.response)
-    expect(untrusted.state.status).toBe(403)
-    expect(untrusted.state.body).toBe('forbidden')
-
-    const written = fakeResponse()
-    const post = fakeRequest({ host: '127.0.0.1:3080' }, `${FILES_PATH}/s-1/index.html`)
-    Object.assign(post, { method: 'POST' })
-    await filesRoute(routes).handler(post, written.response)
-    expect(written.state.status).toBe(405)
-    expect(written.state.headers).toMatchObject({ allow: 'GET, HEAD' })
+  it('applies the same browser-trust fence as /api, refuses writes, and serves nothing else', async () => {
+    const { taps, dispose } = await mounted()
+    const origin = filesOrigin(taps)
+    // Rebound Host: refused before any filesystem work, exactly as on /api.
+    // node's fetch refuses to set Host (a forbidden header), so the spoof goes
+    // through the raw client — the same parse the server really performs.
+    expect(await statusWithHost(origin, `${FILES_PATH}/s-1/index.html`, 'harness.example')).toBe(403)
+    const written = await fetch(`${origin}${FILES_PATH}/s-1/index.html`, { method: 'POST' })
+    expect(written.status).toBe(405)
+    expect(written.headers.get('allow')).toBe('GET, HEAD')
+    // This origin is one route wide: no index, no SPA fallback, no API.
+    expect((await fetch(`${origin}/`)).status).toBe(404)
+    expect((await fetch(`${origin}${API_PATH}/session.list`, { method: 'POST' })).status).toBe(404)
     await dispose()
   })
 
   it('confines reads to the directory the gateway names for that session', async () => {
     const { cwd, remove } = await workspace()
-    const { routes, dispose } = await mounted(undefined, { 's-1': cwd })
-    const served = fakeResponse()
-    await filesRoute(routes).handler(head(`${FILES_PATH}/s-1/index.html`), served.response)
-    expect(served.state.status).toBe(200)
+    const { taps, dispose } = await mounted(undefined, { 's-1': cwd })
+    const origin = filesOrigin(taps)
+    const served = await fetch(`${origin}${FILES_PATH}/s-1/index.html`)
+    expect(served.status).toBe(200)
+    expect(await served.text()).toBe('<h1>ok</h1>')
+    // A served document keeps its own capabilities: the port is the boundary,
+    // so nothing here strips the document of its origin.
+    expect(served.headers.get('content-security-policy')).toBeNull()
     // A session the gateway names no directory for has no workspace to confine
     // against, so there is nothing to serve.
-    const unknown = fakeResponse()
-    await filesRoute(routes).handler(head(`${FILES_PATH}/s-absent/index.html`), unknown.response)
-    expect(unknown.state.status).toBe(404)
+    expect((await fetch(`${origin}${FILES_PATH}/s-absent/index.html`)).status).toBe(404)
     await dispose()
     await remove()
   })
diff --git a/packages/client/connection/tests/workspace-files.spec.ts b/packages/client/connection/tests/workspace-files.spec.ts
index 6aee38e4d9..8e33a6751b 100644
--- a/packages/client/connection/tests/workspace-files.spec.ts
+++ b/packages/client/connection/tests/workspace-files.spec.ts
@@ -59,27 +59,25 @@ function get(path: string, init?: RequestInit): Promise<Response> {
 }
 
 describe('workspace file reads', () => {
-  it('serves an active document into an opaque origin', async () => {
+  it('serves a produced document with its own capabilities intact', async () => {
     const response = await get(`${FILES_PATH}/${SESSION}/index.html`)
     expect(response.status).toBe(200)
     expect(await response.text()).toBe('<h1>产物</h1>')
     expect(response.headers.get('content-type')).toBe('text/html; charset=utf-8')
-    // A workspace file is not necessarily agent-authored, and same-origin
-    // script here would pass the browser-trust fence into every RPC method.
-    expect(response.headers.get('content-security-policy')).toContain('sandbox')
-    expect(response.headers.get('content-security-policy')).not.toContain('allow-same-origin')
+    // No isolation header: the listener's own port is the origin boundary, so
+    // a preview keeps localStorage and cookies (see files-server).
+    expect(response.headers.get('content-security-policy')).toBeNull()
     expect(response.headers.get('x-content-type-options')).toBe('nosniff')
     expect(response.headers.get('cache-control')).toBe('no-store')
     expect(response.headers.get('content-disposition')).toBe('inline')
   })
 
-  it('sandboxes SVG too, and leaves inert types unrestricted', async () => {
+  it('types SVG as a standalone document rather than sniffable bytes', async () => {
     const svg = await get(`${FILES_PATH}/${SESSION}/chart.svg`)
     expect(svg.headers.get('content-type')).toBe('image/svg+xml')
-    expect(svg.headers.get('content-security-policy')).toContain('sandbox')
+    expect(svg.headers.get('x-content-type-options')).toBe('nosniff')
     const text = await get(`${FILES_PATH}/${SESSION}/notes.txt`)
     expect(text.headers.get('content-type')).toBe('text/plain; charset=utf-8')
-    expect(text.headers.get('content-security-policy')).toBeNull()
   })
 
   it('serves a workspace rooted at a filesystem root, whose realpath already ends in a separator', async () => {
diff --git a/packages/client/runtime/src/client/contract/workspaces.ts b/packages/client/runtime/src/client/contract/workspaces.ts
index dbc0f3b30f..3e64ef3717 100644
--- a/packages/client/runtime/src/client/contract/workspaces.ts
+++ b/packages/client/runtime/src/client/contract/workspaces.ts
@@ -56,17 +56,6 @@ export interface IWorkspaces {
    * @param path - absolute or host-resolvable path.
    */
   openPath(path: string): Promise<void>
-  /**
-   * URL serving one file out of a session's workspace, for a UI that opens a
-   * produced file in the browser instead of on the Host machine.
-   * @param sessionId - the session whose cwd anchors the path.
-   * @param cwd - that session's working directory, or `undefined` when unknown.
-   * @param path - the path a tool reported (absolute, or relative to `cwd`).
-   * @returns the origin-relative URL, or `undefined` when the path lies
-   * outside the workspace — which this transport never serves, leaving
-   * {@link IWorkspaces.openPath} as the only way to reach it.
-   */
-  fileUrl(sessionId: SessionId, cwd: string | undefined, path: string): string | undefined
   /**
    * Rename a Workspace.
    * @param workspaceId - target workspace.
diff --git a/packages/client/runtime/src/client/workspaces/service.ts b/packages/client/runtime/src/client/workspaces/service.ts
index 837a7daa03..c0eb46fcf9 100644
--- a/packages/client/runtime/src/client/workspaces/service.ts
+++ b/packages/client/runtime/src/client/workspaces/service.ts
@@ -5,7 +5,6 @@ import type {
   DirectoryListing, IApiClient, RpcError,
   SessionId, WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
-import { workspaceFileSegments, workspaceFileUrl } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
 import type { SessionsPort, SessionsPortList } from '../contract/sessions-port.ts'
@@ -240,18 +239,6 @@ export class WorkspacesService implements IWorkspaces {
     }
   }
 
-  /**
-   * URL serving one file out of a session's workspace.
-   * @param sessionId - the session whose cwd anchors the path.
-   * @param cwd - that session's working directory, or `undefined` when unknown.
-   * @param path - the path a tool reported (absolute, or relative to `cwd`).
-   * @returns the origin-relative URL, or `undefined` for a path outside the workspace.
-   */
-  fileUrl(sessionId: SessionId, cwd: string | undefined, path: string): string | undefined {
-    const segments = workspaceFileSegments(cwd, path)
-    if (segments === undefined) return undefined
-    return workspaceFileUrl(sessionId, segments)
-  }
 
   /**
    * Rename a Workspace.
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index d389efe319..a5827173a8 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -26,6 +26,7 @@ async function mount(): Promise<Bench> {
   const bench: Bench = { ctx, api, sinks: undefined, stopped: 0 }
   const handle: ConnectionHandle = {
     api,
+    fileUrl: () => undefined,
     start: (sinks) => {
       bench.sinks = sinks
       return { stop: () => { bench.stopped += 1 } }
diff --git a/packages/client/runtime/tests/wire-events.spec.ts b/packages/client/runtime/tests/wire-events.spec.ts
index fd7858d60c..a35983d890 100644
--- a/packages/client/runtime/tests/wire-events.spec.ts
+++ b/packages/client/runtime/tests/wire-events.spec.ts
@@ -20,6 +20,7 @@ async function mount(): Promise<Bench> {
   const bench: Bench = { ctx, sinks: undefined }
   const handle: ConnectionHandle = {
     api,
+    fileUrl: () => undefined,
     start: (sinks) => {
       bench.sinks = sinks
       return { stop: () => {} }
diff --git a/packages/client/runtime/tests/workspaces-service.spec.ts b/packages/client/runtime/tests/workspaces-service.spec.ts
index 3d9cef547f..4323d7ffce 100644
--- a/packages/client/runtime/tests/workspaces-service.spec.ts
+++ b/packages/client/runtime/tests/workspaces-service.spec.ts
@@ -276,21 +276,6 @@ describe('WorkspacesService', () => {
     await expect(workspaces.openPath('/missing')).rejects.toThrow(/path open failed/)
   })
 
-  it('addresses a workspace file by URL, and only inside the workspace', async () => {
-    const ctx = new Context()
-    const api = new FakeApiClient()
-    const sessions = new SessionsService(ctx, api)
-    const workspaces = new WorkspacesService(ctx, api, sessions)
-    const session = 's-1' as SessionId
-    // The URL is derived, not fetched: no wire call answers a link.
-    expect(workspaces.fileUrl(session, '/w/alpha', '/w/alpha/out/a b.html')).toBe('/f/s-1/out/a%20b.html')
-    expect(workspaces.fileUrl(session, '/w/alpha', 'out/index.html')).toBe('/f/s-1/out/index.html')
-    // Outside the workspace there is nothing this transport may serve, which
-    // is the signal a caller falls back to openPath on.
-    expect(workspaces.fileUrl(session, '/w/alpha', '/etc/hosts')).toBeUndefined()
-    expect(api.calls).toHaveLength(0)
-  })
-
   it('deletes a Workspace or preserves it when the Host rejects deletion', async () => {
     const ctx = new Context()
     const api = new FakeApiClient()
diff --git a/packages/client/test-runtime/package.json b/packages/client/test-runtime/package.json
index e892d9cd52..6d7093a148 100644
--- a/packages/client/test-runtime/package.json
+++ b/packages/client/test-runtime/package.json
@@ -25,6 +25,7 @@
     "vitest": "^4.1.8"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
     "@deepseek-ai/dsh-client-web-react": "^0.0.1",
@@ -35,6 +36,7 @@
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-client-web-react": "workspace:^",
diff --git a/packages/client/test-runtime/src/connection.ts b/packages/client/test-runtime/src/connection.ts
new file mode 100644
index 0000000000..5df5d5a053
--- /dev/null
+++ b/packages/client/test-runtime/src/connection.ts
@@ -0,0 +1,48 @@
+/** Test-owned connection face: the transport members features read off `ctx.connection`. */
+import { workspaceFileSegments, workspaceFileUrl } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { ConnectionHandle, IApiClient, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+
+/**
+ * Connection test double. Implements the same `ConnectionHandle` face features
+ * receive as `ctx.connection`, so a production face change breaks this double
+ * at compile time. The wire client is not modelled — a feature that needs one
+ * composes its own connection over a fake api client; this double exists for
+ * the transport facts features read synchronously, above all the
+ * workspace-file URL.
+ */
+export class TestConnection implements ConnectionHandle {
+  /**
+   * The workspace-file port the host would have published into the page.
+   * Unset — the default, and the keyless fixture lane's real state — makes
+   * {@link TestConnection.fileUrl} answer `undefined`, which is the signal a
+   * caller falls back to the Host opener on.
+   */
+  filesPort: number | undefined
+
+  /** The wire client; unused by this double's consumers and absent by construction. */
+  readonly api: IApiClient = undefined as unknown as IApiClient
+
+  /**
+   * Stream-loop starter (inert).
+   * @returns a stop handle that does nothing.
+   */
+  start(): { stop(): void } {
+    return { stop: () => {} }
+  }
+
+  /**
+   * Workspace-file URL, deriving exactly as production does so a feature test
+   * sees the real inside/outside-workspace split.
+   * @param sessionId - the Session whose cwd anchors the path.
+   * @param cwd - that Session's working directory.
+   * @param path - the path a tool reported.
+   * @returns the absolute URL on the workspace-file origin, or undefined when
+   * the path leaves the workspace or no port is published.
+   */
+  fileUrl(sessionId: SessionId, cwd: string | undefined, path: string): string | undefined {
+    if (this.filesPort === undefined) return undefined
+    const segments = workspaceFileSegments(cwd, path)
+    if (segments === undefined) return undefined
+    return `http://localhost:${String(this.filesPort)}${workspaceFileUrl(sessionId, segments)}`
+  }
+}
diff --git a/packages/client/test-runtime/src/index.ts b/packages/client/test-runtime/src/index.ts
index 5ef5350434..cdbdca75a2 100644
--- a/packages/client/test-runtime/src/index.ts
+++ b/packages/client/test-runtime/src/index.ts
@@ -29,11 +29,13 @@ import type {
 } from '@deepseek-ai/dsh-client-ui-slots'
 import { registerDomSnapshotSerializer } from './snapshot.ts'
 import { TestSessions } from './sessions.ts'
+import { TestConnection } from './connection.ts'
 import { TestWorkspaces } from './workspaces.ts'
 import type { Stabilizer } from './fixtures.ts'
 
 export { domSnapshotSerializer, registerDomSnapshotSerializer } from './snapshot.ts'
 export { FixtureSession, TestSessions } from './sessions.ts'
+export { TestConnection } from './connection.ts'
 export { TestWorkspaces } from './workspaces.ts'
 export { conversationSnapshot, workspaceListState } from './fixtures.ts'
 export type { SessionBehaviorOverrides, SessionFixture, Stabilizer } from './fixtures.ts'
@@ -175,6 +177,8 @@ export class SlotTestRuntime {
   readonly sessions: TestSessions
   /** Workspaces double (list observable, recorded intent actions). */
   readonly workspaces: TestWorkspaces
+  /** The transport double features read as `ctx.connection`. */
+  readonly connection: TestConnection
 
   private readonly stabilizer: Stabilizer = async (fn) => {
     await act(async () => { await fn() })
@@ -195,8 +199,10 @@ export class SlotTestRuntime {
     this.root = new TestRoot(slots, this.stabilizer)
     this.sessions = new TestSessions(this.stabilizer, ctx)
     this.workspaces = new TestWorkspaces(this.stabilizer)
+    this.connection = new TestConnection()
     ctx.provide('sessions', this.sessions)
     ctx.provide('workspaces', this.workspaces)
+    ctx.provide('connection', this.connection)
     // Capturing install: the production renderer does the rendering; the
     // wrapper only takes the host face for storeOf (no machinery copied).
     const renderer = createSlotRenderer()
diff --git a/packages/client/test-runtime/src/workspaces.ts b/packages/client/test-runtime/src/workspaces.ts
index 01e7db4c3d..95f6574405 100644
--- a/packages/client/test-runtime/src/workspaces.ts
+++ b/packages/client/test-runtime/src/workspaces.ts
@@ -1,6 +1,5 @@
 /** Test-owned workspaces face: the renderer standard-kit observable plus recorded actions. */
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { workspaceFileSegments, workspaceFileUrl } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type {
   DirectoryListing, IWorkspaces, SessionId, SnapshotStore, WorkspaceId, WorkspaceListState, WorkspaceView,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -99,21 +98,6 @@ export class TestWorkspaces implements IWorkspaces {
     await (this.stubs.get('openPath')?.(path) as Promise<void> | undefined)
   }
 
-  /**
-   * Workspace-file URL (recorded). Runs the production path derivation so a
-   * feature test sees the real in/outside-workspace split; stub to force either.
-   * @param sessionId - the session whose cwd anchors the path.
-   * @param cwd - that session's working directory.
-   * @param path - the path a tool reported.
-   * @returns the origin-relative URL, or undefined outside the workspace.
-   */
-  fileUrl(sessionId: SessionId, cwd: string | undefined, path: string): string | undefined {
-    this.calls.push({ method: 'fileUrl', args: [sessionId, cwd, path] })
-    const stub = this.stubs.get('fileUrl')
-    if (stub !== undefined) return stub(sessionId, cwd, path) as string | undefined
-    const segments = workspaceFileSegments(cwd, path)
-    return segments === undefined ? undefined : workspaceFileUrl(sessionId, segments)
-  }
 
   /**
    * Directory picker (recorded). The default cancels (null); stub to select.
diff --git a/packages/client/test-runtime/tests/runtime.spec.tsx b/packages/client/test-runtime/tests/runtime.spec.tsx
index a9c4b0c9ca..3675671f26 100644
--- a/packages/client/test-runtime/tests/runtime.spec.tsx
+++ b/packages/client/test-runtime/tests/runtime.spec.tsx
@@ -549,10 +549,6 @@ describe('workspaces action face', () => {
     expect(renamed.title).toBe('Renamed')
     await ws.delete('w1' as WorkspaceId)
     await ws.openPath('/proj/file.ts')
-    // fileUrl runs the production derivation, so a feature test sees the same
-    // inside/outside-workspace split the browser half decides on.
-    expect(ws.fileUrl('s1' as SessionId, '/proj', 'out/a.html')).toBe('/f/s1/out/a.html')
-    expect(ws.fileUrl('s1' as SessionId, '/proj', '/etc/hosts')).toBeUndefined()
     const moved = await ws.insertSessionBefore('w1' as WorkspaceId, 's1' as SessionId, 's2' as SessionId)
     expect(moved.sessionIds).toEqual(['s1'])
     // Default archive mirrors the production effect: the id joins the list
@@ -560,15 +556,13 @@ describe('workspaces action face', () => {
     await ws.archiveSession('s1' as SessionId)
     expect(ws.list.getSnapshot().archivedSessionIds).toEqual(['s1'])
     expect(ws.calls.map(c => c.method)).toEqual(
-      ['create', 'create', 'pickDirectory', 'rename', 'delete', 'openPath', 'fileUrl', 'fileUrl',
-        'insertSessionBefore', 'archiveSession'])
+      ['create', 'create', 'pickDirectory', 'rename', 'delete', 'openPath', 'insertSessionBefore', 'archiveSession'])
 
     ws.stub('create', () => Promise.resolve({ workspaceId: 'ws-x', title: 'X', path: '/x', sessionIds: [] } as never))
     ws.stub('pickDirectory', () => Promise.resolve('/picked'))
     ws.stub('rename', () => Promise.resolve({ workspaceId: 'w1', title: 'S', path: '/s', sessionIds: [] } as never))
     ws.stub('delete', () => Promise.resolve())
     ws.stub('openPath', () => Promise.resolve())
-    ws.stub('fileUrl', () => '/f/forced/a.html')
     ws.stub('insertSessionBefore', () => Promise.resolve({ workspaceId: 'w1', title: '', path: '', sessionIds: [] } as never))
     ws.stub('archiveSession', () => Promise.resolve())
     expect((await ws.create({ name: 'y' })).title).toBe('X')
@@ -576,7 +570,6 @@ describe('workspaces action face', () => {
     expect((await ws.rename('w1' as WorkspaceId, 'z')).title).toBe('S')
     await ws.delete('w1' as WorkspaceId)
     await ws.openPath('/other')
-    expect(ws.fileUrl('s1' as SessionId, '/proj', '/etc/hosts')).toBe('/f/forced/a.html')
     expect((await ws.insertSessionBefore('w1' as WorkspaceId, 's1' as SessionId)).sessionIds).toEqual([])
     // The stub replaces the default set mutation: the set stays as-is.
     await ws.archiveSession('s2' as SessionId)
diff --git a/packages/client/test-runtime/tsconfig.json b/packages/client/test-runtime/tsconfig.json
index 6a758c66f9..681bff474c 100644
--- a/packages/client/test-runtime/tsconfig.json
+++ b/packages/client/test-runtime/tsconfig.json
@@ -17,6 +17,9 @@
     {
       "path": "../web-react"
     },
+    {
+      "path": "../connection"
+    },
     {
       "path": "../runtime"
     },
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 2a2857839d..446c2084b1 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: ba55f0704500034b7afb37258064fe0801aaee91
-README.zh.md: 4212908b355a81dfd5af8645ce5d4284a4555622
+README.md: 8c2075d615eccad1bbc7f5de1255ea4add69fab8
+README.zh.md: 634721b4248da75cbd4e81528340936a31ece28d
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index ba55f07045..8c2075d615 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -14,7 +14,7 @@ Approvals take over the composer through the chain this package declares: `Appro
 
 Logged non-user messages render as a default-collapsed `上下文注入` disclosure. It shares the Tool calls header geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap, shows inline JSON for both `content` and `source`, and synthesizes no tool state, summary, or keyed toolview dispatch ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)).
 
-Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is a hover-underline link that opens the file: one inside the session workspace opens in a new browser tab, served by the web transport's `/f` route, so a client that is not on the Host machine still sees it; one outside the workspace has no served URL and falls back to the Host OS default application (`host.openPath`, relative paths resolve against the session cwd). Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
+Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is a hover-underline link that opens the file: one inside the session workspace opens in a new browser tab on the transport's workspace-file origin (`ConnectionHandle.fileUrl`), so a client that is not on the Host machine still sees it; one outside the workspace has no served URL and falls back to the Host OS default application (`host.openPath`, relative paths resolve against the session cwd). Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
 
 A tool call declaring the `terminal` render intent renders its command output inline, at both conversation render sites, through ui-primitives' `TerminalBlock`. `contract/terminal-card-model.ts` is the single derivation from the snapshot's `callView`/`resultView` pair, so the sites cannot disagree about a command, its cwd, or its exit status; it yields null — the generic path — for any other card tag, including one this client version does not know. Both sites therefore also show the card's run-state dot, which is the same `StateDot` semantic a tool row's leading icon carries, so a row and its own card always agree about one command's state. A multi-line command gets one prompt row per line, with the dot marking the call once on the first row — the exit status is the whole call's, so a dot per line would claim a per-line outcome bash does not report. The keyed `BashRow` carries the card resident below its summary row; since tool rows are no longer details-panel click targets, the card's copy and expand controls are the row's only interactions. The render-site fallback row keeps the card behind its existing expand control. Rows cap at `CHAT_TERMINAL_MAX_LINES` (8) against the panel's 16, which is what keeps a summary surface bounded — the panel stays the single-call reading surface. Inline output is licensed per render intent — the terminal and web cards, each with its own bound; a generic tool's content remains panel-only ([decision](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)).
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 4212908b35..634721b424 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -12,7 +12,7 @@
 
 已记录的非用户消息渲染为默认折叠的 `上下文注入` 展开项。它通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 标题栏的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，并以内联 JSON 展示 `content` 和 `source`，且不会合成工具状态、摘要或键控 toolview 分发（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)）。
 
-通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是悬停下划线链接，点击即打开文件：位于会话工作区之内的文件在新浏览器标签页打开，由 web 传输的 `/f` 路由提供，因此不在 Host 机器上的客户端也能看到；工作区之外的文件没有可服务的 URL，回退到宿主操作系统的默认应用（`host.openPath`，相对路径相对会话 cwd 解析）。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
+通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是悬停下划线链接，点击即打开文件：位于会话工作区之内的文件在新浏览器标签页打开，位于传输层的工作区文件源上（`ConnectionHandle.fileUrl`），因此不在 Host 机器上的客户端也能看到；工作区之外的文件没有可服务的 URL，回退到宿主操作系统的默认应用（`host.openPath`，相对路径相对会话 cwd 解析）。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
 
 声明 `terminal` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `TerminalBlock` 内联渲染其命令输出。`contract/terminal-card-model.ts` 是从快照的 `callView`／`resultView` 对推导的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧；对任何其他 card 标签——包括当前客户端版本不认识的标签——它返回 null，落回通用路径。因此两个渲染点也都显示卡片的运行状态点，它与工具行行首图标承载同一套 `StateDot` 语义，所以一行与其自身的卡片对同一条命令的状态总是一致。多行命令的每一行各占一个提示行，状态点只在第一行为整次调用标记一次——退出状态属于整次调用，因此每行一枚就会声称一个 bash 并不报告的逐行结果。键控的 `BashRow` 把卡片常驻在摘要行下方；由于工具行已不再是详情面板的点击目标，卡片的复制与展开控件就是该行唯一的交互。渲染点兜底行则保持其既有的展开控件。行的上限是 `CHAT_TERMINAL_MAX_LINES`（8），面板为 16，正是这一点让摘要面保持有界——面板仍是单次调用的阅读面。内联输出按渲染意图开放——终端卡片与 web 卡片，各有自己的上限；通用工具的内容仍然只在面板中呈现（[决策](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)）。
 
diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
index 88c09b5550..55036600c6 100644
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -39,6 +39,7 @@
     "clsx": "^2.0.0"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
     "@deepseek-ai/dsh-client-locale": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
@@ -50,6 +51,7 @@
     "react": "^18.2.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 71f05267b3..a65ce1d7a4 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -2,6 +2,7 @@
 import type { Context } from 'cordis'
 import { resolveSlotLabel, type BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ISessions, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
@@ -42,7 +43,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 }
 
 /** Services required by the conversation plugin. */
-export const inject = ['slots', 'layout', 'sessions', 'workspaces', 'locale']
+export const inject = ['slots', 'layout', 'sessions', 'workspaces', 'locale', 'connection']
 
 // Static no-session sources for the composer-bar hooks compartment: module
 // constants so the render side's per-source hook cache (observableHook) keeps
@@ -275,11 +276,12 @@ export function apply(ctx: Context): void {
         },
         openFile: (path) => {
           const cwd = sessions.list.getSnapshot().byId[sessionId]?.cwd
-          // A file inside the workspace opens in a new tab, so a browser that
-          // is not on the Host machine can still see what the agent produced.
-          // Anything outside it has no served URL and falls back to the Host's
-          // own opener, which is loopback-only by the /api trust fence.
-          const url = workspaces.fileUrl(sessionId, cwd, path)
+          // A file inside the workspace opens in a new tab on the transport's
+          // workspace-file origin, so a browser that is not on the Host machine
+          // can still see what the agent produced. Anything outside it has no
+          // served URL and falls back to the Host's own opener, which is
+          // loopback-only by the /api trust fence.
+          const url = (ctx.get('connection') as ConnectionHandle).fileUrl(sessionId, cwd, path)
           if (url !== undefined) {
             window.open(url, '_blank', 'noopener,noreferrer')
             return
diff --git a/packages/client/ui-conversation/tests/apply-inject.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
index 6427f6750c..b9dbe0d6ad 100644
--- a/packages/client/ui-conversation/tests/apply-inject.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
@@ -220,12 +220,15 @@ describe('conversation slot inject surface', () => {
 
   it('openFile (chat view face) opens a workspace file in a tab and falls back to the host opener outside it', async () => {
     const b = await bench()
+    // A host that publishes a workspace-file port: previews come from that
+    // origin, which is what keeps them off the API's.
+    b.runtime.connection.filesPort = 4321
     const open = vi.spyOn(window, 'open').mockReturnValue(null)
     const { injected } = b.chatViewSurface(ROOT)
-    // Inside the session cwd: served by this origin, so a browser anywhere on
-    // the network sees the file the agent produced.
+    // Inside the session cwd: served on the workspace-file origin, so a browser
+    // anywhere on the network sees the file the agent produced.
     injected.openFile('src/a.ts')
-    expect(open).toHaveBeenCalledWith(`/f/${ROOT}/src/a.ts`, '_blank', 'noopener,noreferrer')
+    expect(open).toHaveBeenCalledWith(`http://localhost:4321/f/${ROOT}/src/a.ts`, '_blank', 'noopener,noreferrer')
     expect(b.runtime.workspaces.calls.some(c => c.method === 'openPath')).toBe(false)
     // Outside it there is no served URL, so the Host's own opener answers —
     // resolved against the session cwd exactly as before.
diff --git a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
index 51e31c9750..2763702c0b 100644
--- a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
@@ -134,9 +134,11 @@ async function bench(snapshot: ConversationSnapshot) {
     startSession: vi.fn(),
     sendSession: vi.fn(),
     openPath: vi.fn(async () => {}),
-    fileUrl: vi.fn((_sessionId: unknown, _cwd: string | undefined, path: string) => `/f/s-1/${path}`),
   }
   ctx.provide('workspaces', workspaces)
+  // The transport face the chat view reads its workspace-file URLs from.
+  const connection = { fileUrl: vi.fn((_s: unknown, _cwd: string | undefined, path: string) => `http://localhost:4321/f/s-1/${path}`) }
+  ctx.provide('connection', connection)
   ctx.provide('layout', layout)
   const locale = new LocaleService(ctx)
   ctx.provide('locale', locale)
@@ -249,7 +251,7 @@ describe('run_code sub-calls through the real chat machinery', () => {
     view.getByText('notes/demo.txt').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
     await vi.waitFor(() => {
-      expect(open).toHaveBeenCalledWith('/f/s-1/notes/demo.txt', '_blank', 'noopener,noreferrer')
+      expect(open).toHaveBeenCalledWith('http://localhost:4321/f/s-1/notes/demo.txt', '_blank', 'noopener,noreferrer')
     })
     open.mockRestore()
     view.getByText('List notes').click()
diff --git a/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx b/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
index 6cb46e7ea0..84cdd53eeb 100644
--- a/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
@@ -121,6 +121,7 @@ describe('keyed toolview hole through the real machinery', () => {
 
   it('file-path clicks travel owner openFile → chat inject → the served workspace URL', async () => {
     const b = await bench([toolResult(3, 'c1', 'read', '{"path":"src/a.ts"}')])
+    b.runtime.connection.filesPort = 4321
     const open = vi.spyOn(window, 'open').mockReturnValue(null)
     const view = b.runtime.renderRoot()
     view.getByText('src/a.ts').click()
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
index 04b265bdd5..33d45124b4 100644
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -20,6 +20,9 @@
     {
       "path": "../web-react"
     },
+    {
+      "path": "../connection"
+    },
     {
       "path": "../runtime"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7073f04e4b..5fb7df52ad 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1183,6 +1183,9 @@ importers:
         specifier: ^4.1.8
         version: 4.1.8(@opentelemetry/api@1.9.1)(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
     devDependencies:
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../connection
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../runtime
@@ -1263,6 +1266,9 @@ importers:
         specifier: ^2.0.0
         version: 2.1.1
     devDependencies:
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../connection
       '@deepseek-ai/dsh-client-locale':
         specifier: workspace:^
         version: link:../locale

From 8fb6c2bd698d75a621912570663505d4dd0d42e4 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <zzy211851@gmail.com>
Date: Sat, 1 Aug 2026 03:15:54 -0700
Subject: [PATCH 011/516] refactor(web): open produced files through the Host,
 not over HTTP
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Scope decision: previews for a browser that is not on the Host machine are
not supported. With that settled, host.openPath answers the supported case
completely — a file:// document in a real browser has full page capabilities
and no reach into /api — and the HTTP serving this branch had built answered
only the unsupported one.

Removed: the /f route and its listener, the workspace-file URL shape,
ApiProxy.workspaceRootOf, ConnectionHandle.fileUrl, and the port published
into the index page.

Kept, and finished:
- the produced-files row a turn ends with, derived from mutation locations;
- the path link now reads as a link at rest, not only on hover — the reported
  "I can't open what it made" was this, sitting on a working capability;
- the Host opener prefers the default BROWSER for .html/.htm/.xhtml/.svg, so
  a developer who binds .html to an editor still gets a rendered page
  (macOS via the LaunchServices https handler, Linux via $BROWSER, every
  failure falling back to the default application).

The retired designs and their measurements stay in the Agent Note, including
why same-origin serving was unsafe and why the sandbox that fixed it broke
the pages invisibly.
---
 ...6-07-31-web-workspace-file-links.i18n.yaml |   4 +-
 .../2026-07-31-web-workspace-file-links.md    |  28 ++-
 .../2026-07-31-web-workspace-file-links.zh.md |  28 ++-
 apps/web/tests/produced-files.e2e.ts          |  76 ++++++++
 apps/web/tests/workspace-file-open.e2e.ts     | 122 -------------
 apps/web/tsconfig.json                        |   2 +-
 docs/config-catalog.md                        |   2 +-
 packages/client/connection/README.i18n.yaml   |   4 +-
 packages/client/connection/README.md          |  10 +-
 packages/client/connection/README.zh.md       |   8 +-
 .../client/connection/src/client/fixture.ts   |   4 -
 .../client/connection/src/client/index.ts     |  25 ---
 .../client/connection/src/files-server.ts     | 127 --------------
 packages/client/connection/src/index.ts       |  41 +----
 .../client/connection/src/workspace-files.ts  | 164 ------------------
 .../connection/tests/client-apply.spec.ts     |  26 +--
 .../connection/tests/files-server.spec.ts     |  44 -----
 .../client/connection/tests/node-half.spec.ts | 114 ++----------
 .../connection/tests/workspace-files.spec.ts  | 142 ---------------
 .../client/runtime/tests/client-apply.spec.ts |   1 -
 .../client/runtime/tests/wire-events.spec.ts  |   1 -
 packages/client/test-runtime/package.json     |   2 -
 .../client/test-runtime/src/connection.ts     |  48 -----
 packages/client/test-runtime/src/index.ts     |   6 -
 packages/client/test-runtime/tsconfig.json    |   3 -
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +-
 packages/client/ui-conversation/README.zh.md  |   2 +-
 packages/client/ui-conversation/package.json  |   2 -
 .../ui-conversation/src/client/apply.ts       |  13 +-
 .../src/client/chat/ToolRow.module.css        |  13 +-
 .../tests/apply-inject.spec.tsx               |  16 +-
 .../tests/chat-code-subcalls.spec.tsx         |   7 +-
 .../tests/chat-toolview-slot.spec.tsx         |   7 +-
 packages/client/ui-conversation/tsconfig.json |   3 -
 packages/host/apiproxy/README.i18n.yaml       |   4 +-
 packages/host/apiproxy/README.md              |   2 -
 packages/host/apiproxy/README.zh.md           |   2 -
 packages/host/apiproxy/src/api-proxy.ts       |  15 --
 packages/host/apiproxy/src/api/files.ts       |  98 -----------
 packages/host/apiproxy/src/api/index.ts       |  17 --
 packages/host/apiproxy/src/index.ts           |   2 -
 .../host/apiproxy/src/native-path-opener.ts   |  76 +++++++-
 .../tests/api-proxy-workspace.spec.ts         |  32 +---
 .../apiproxy/tests/client-handler.spec.ts     |   2 -
 .../host/apiproxy/tests/fetch-carrier.spec.ts |   2 -
 .../host/apiproxy/tests/files-path.spec.ts    |  74 --------
 .../apiproxy/tests/native-path-opener.spec.ts |  93 ++++++++++
 pnpm-lock.yaml                                |   6 -
 tsconfig.host.json                            |   2 +-
 50 files changed, 317 insertions(+), 1211 deletions(-)
 create mode 100644 apps/web/tests/produced-files.e2e.ts
 delete mode 100644 apps/web/tests/workspace-file-open.e2e.ts
 delete mode 100644 packages/client/connection/src/files-server.ts
 delete mode 100644 packages/client/connection/src/workspace-files.ts
 delete mode 100644 packages/client/connection/tests/files-server.spec.ts
 delete mode 100644 packages/client/connection/tests/workspace-files.spec.ts
 delete mode 100644 packages/client/test-runtime/src/connection.ts
 delete mode 100644 packages/host/apiproxy/src/api/files.ts
 delete mode 100644 packages/host/apiproxy/tests/files-path.spec.ts

diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index e8510d24e5..2b75bc2eff 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.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 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
-2026-07-31-web-workspace-file-links.md: 8eeb96517aa905e77e50ce36f0efb704353c0821
-2026-07-31-web-workspace-file-links.zh.md: 63d746b0a9aabaf78ba5653e16705bd662a54126
+2026-07-31-web-workspace-file-links.md: da99426ecb5ca81dcc110bbd4d5c1218390ae4bd
+2026-07-31-web-workspace-file-links.zh.md: 91aa94c6fe253c64125eb31fd15973a5aaff1a8f
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
index 8eeb96517a..da99426ecb 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
@@ -4,36 +4,32 @@ Status: implemented
 
 English | [中文](2026-07-31-web-workspace-file-links.zh.md)
 
-> Scope: the `/f` workspace-file route on the web transport, the `IWorkspaces.fileUrl` derivation behind it, the conversation's file-open affordance switching to it, and the produced-files row a finished turn ends with. Not in scope: an artifact registry, versioning, live reload, or any model-facing declaration.
+> Scope: the produced-files row a finished turn ends with, the file-path link that reads as one, and the Host opener preferring the default browser for documents a browser renders. Not in scope, by decision: serving workspace files over HTTP, and previews for a client that is not on the Host machine.
 
 ## Problem
 
 A web session that produced a file had no way to look at it. The agent wrote `deepseek-homepage.html`, said so, and the user's only recourse was to copy an absolute path like `/private/tmp/dsh-client-hotplug.ygPvsm/workspaces/plugin-hotplug/deepseek-homepage.html` into a terminal.
 
-The parts were nearly all present, pointed at the wrong target. `ToolRow` already renders a mutation or read row's path as a real button, `ui-conversation` already routes its click through `openFile`, and `workspaces.openPath` already carries it to the Host's system opener. But that opener runs on the Host machine, and `host.openPath` is loopback-pinned by the `/api` trust fence, so the affordance answered nothing for a browser reached over the LAN and was invisible even locally (the path styled as plain text, underlined only on hover). Meanwhile `MarkdownText` strips every non-`http(s)` URL, so a path the model wrote into its closing message could never become a link at all, and `ToolCallView.locations` — the follow-along vocabulary the file tools already populate — had no consumer in the client.
+Two distinct defects sat behind that. The transcript never said what a turn had produced: `ToolCallView.locations` — the follow-along vocabulary the file tools already populate — had no consumer in the client, so a reader's only account of the output was whatever the closing message happened to spell. And the affordance that did exist was invisible: `ToolRow` already renders a mutation or read row's path as a real button wired to `host.openPath`, but styled exactly like the surrounding prose and underlined only on hover, so nobody found it. The reported "I can't open what it made" was a discoverability failure sitting on top of a working capability.
 
 ## Decision
 
-**One prefix route on the transport that already exists, not a new capability.** `client-connection` owns both browser-facing prefixes: `/api` for RPC and `/f/<sessionId>/<segments…>` for workspace-file reads. It was already the package holding `httpServer`, the `trustedHosts` config, and the browser-trust fence; a separate package would have duplicated the fence and the config, and forced `AppCLIEntry` to patch two rows for one `--trusted-host` flag. The webserver's own contract — every feature surface is a route some other plugin registers — makes the route the whole mechanism. Segments ride the path rather than a query parameter so a served document's relative references resolve to its siblings.
+**A finished turn ends with the files it produced.** `turnDeliverables` reads them off the mutation tools' own follow-along `locations` — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a turn's output is listed whether or not the closing message named it, and a new mutation tool joins by declaring what it does rather than by being added to a list. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row. The row renders under the closing assistant's body and above its IconActions, keyed to the seq `assistantActionsSeqs` already elects.
 
-**The request names a Session; the gateway names the authority.** `ApiProxy.workspaceRootOf` answers where a Session's files live — a live agent's `session.header.cwd` first, then the persistence store, never a resume — as a second, non-envelope face of the `cwd` the session summaries already carry. The route reads that instead of `ctx.agents` directly, because `client-connection` is registered in the client program and importing the core service packages merges their host-side `sessions: SessionStore` declaration over the browser runtime's own `sessions: SessionsService` — the collision `tsconfig.host.json`/`tsconfig.client.json` exist to prevent. Both the cwd and the resolved target go through `realpath` before the prefix comparison, so a workspace-internal symlink pointing outward is refused by its target; traversal spellings are refused at parse time, before any filesystem call. Reads stream through `pipeline`, so a client that goes away destroys the descriptor and no request ever buffers a file.
+**The path link reads as a link.** Underlined at rest, not only on hover. This is the smaller half of the diff and the larger half of the fix.
 
-**The URL shape lives in `dsh-host-apiproxy/api`, with the other browser-importable contract surfaces.** Both ends must agree on one encoding, but a client bundle may not value-import another plugin's package: the purity gate in `packages/client/tsdown.client.ts` allows only platform modules and the `INLINE_SAFE` wire layers, of which apiproxy is one. Putting `api/files.ts` there is what lets the browser half build a URL and the serving half parse it from a single source, and it needed no new package edge — both sides already depend on apiproxy.
+**Opening stays the Host's job, and prefers the default browser.** `host.openPath` hands the path to the operating system, which yields a `file://` document in a real browser: full page capabilities, and no reachability into `/api`, because a `file://` document is not same-origin with it. Measured on the reported artifact: `localStorage` works, the theme toggle flips, the tabs switch, and `fetch` to the API fails. For documents a browser renders — `.html`, `.htm`, `.xhtml`, `.svg` — the opener resolves the default *browser* rather than the type's default application, because a developer who binds `.html` to an editor would otherwise click a produced page and get source code. Each platform answers "which browser" as completely as it can (macOS from the LaunchServices `https` handler, Linux from `$BROWSER`), and every failure falls back to the default application rather than surfacing.
 
-**Workspace files get their own port, and therefore their own origin.** The isolation question was worked three ways before landing here. A sandbox header came first, on the reasoning that `/api/events.mux` is a readable same-origin `GET` stream. It was then dropped on the premise that these files are agent-authored, so a browser boundary would sit behind one already crossed — a premise review falsified: a read row makes every file in a cloned repository openable, and a same-origin active document was measured driving `/api/settings.describe` to a `200` with full data, reaching the loopback-pinned settings and credential plane from a page nobody in this session wrote. Restoring the sandbox closed that, and measuring what it cost decided the final shape: under `CSP: sandbox` the report's own artifact throws `SecurityError` on load, and because an uncaught exception aborts the rest of its `<script>`, every listener declared after that line — theme toggle, mobile menu, model tabs — never binds. Two of the four artifacts in the reporting user's workspace were dead pages under it, and they still *looked* right. A second port is the boundary without the amputation: cross-origin to `/api` (refused by the fence's Origin check and by CORS), same-origin with itself (so `localStorage`, cookies, and `fetch` all work). It binds the same host as the API so LAN previews keep working, answers `/f` and nothing else, and publishes its port into the index page for the browser half to address.
-
-**The client decides by derivation, not by probing.** `ConnectionHandle.fileUrl(sessionId, cwd, path)` expresses a tool-reported path as segments below the session cwd and returns an absolute URL on the workspace-file origin — the page's own hostname, the published port — or `undefined` when the path leaves the workspace or no port was published. It lives on the connection handle because the transport owns both ends: the listener that serves the bytes and the port that addresses it. `undefined` is exactly the signal to fall back to `openPath`, which is also what makes the keyless fixture lane (served by no host) degrade to the old behavior instead of opening a dead tab.
+**Serving workspace files over HTTP is out of scope, and so are non-local clients.** An earlier revision served files from the harness itself — first same-origin with `/api`, then behind `CSP: sandbox`, then from a second listener whose own port gave served documents their own origin. Each step answered a real problem, and the whole line was retired once the product scope was settled: previews for a browser that is not on the Host machine are not supported. With that decided, the Host opener answers the supported case completely and the HTTP machinery answered only the unsupported one.
 
 ## Alternatives considered
 
-- **The artifact capability family (RFC #268 / PR #272)** — a seam with ids, versions, snapshot storage, its own HTTP server, SSE live reload, and a browser auto-opener. Its review found seven critical issues, and every one of them came from that machinery: an unlistened opener spawn crashing the harness, the opener inheriting `DEEPSEEK_API_KEY`, in-flight publishes outliving disposal, `readFile` preceding the size cap, a snapshot TOCTOU, and retention leaking with undisposed agents. `dsh web` already runs an HTTP server and the user is already in a browser, so none of that machinery buys anything here. The RFC and its tests stay as the input for the day a real cross-session or versioned-artifact need appears; this route is that seam's natural mount point when it does.
-- **A dedicated `dsh-client-workspace-files` package** — the honest seam shape if file serving were an independent capability. It is not: it needs the same fence and the same `trustedHosts` value as `/api`, and splitting would have duplicated both against the repository's own "don't split preemptively" rule.
-- **Keeping the URL-shape module in `client-connection` and importing it from the runtime** — the first cut, and the build refused it: a cross-plugin value import into a client bundle either inlines a duplicate runtime instance or names a specifier the frozen module table cannot answer. The gate is the reason the shared module sits in the wire layer rather than in the package that happens to own the route.
-- **`/f/<absolute path>`, so `openPath` could stay the single call site** — drops the sessionId from the URL, but then the served authority becomes the union of every workspace the host knows. The tight authority costs exactly one call-site edit, because `openFile` already has both the sessionId and the cwd in scope.
-- **`connect-src 'none'` plus a navigation fence, to keep `localStorage` working under a sandbox** — measurably viable against the SSE-read vector (Chrome sends `Sec-Fetch-Dest: document` for `window.open` and `empty` for `EventSource`, loopback included), but it never addressed the larger one: same-origin `fetch` to a POST method is what reaches the configuration plane, and blocking `connect-src` from the served document is exactly what a hostile document would not do to itself.
-- **Keeping the sandbox and accepting the limitation** — the honest reading of that trade only became visible once measured: it is not "a preview cannot remember a theme" but "a preview's entire script dies at its first storage access", on pages that still render perfectly. A limitation nobody can see is worse than one that costs a port.
-- **Linkifying paths in the assistant's closing message** — the shape a user asks for ("put the link at the end"), but it makes rendering depend on the model spelling a path recognizably. The tool calls already carry `locations` as structured fact, so the produced-files row consumes that instead; linkifying the prose stays unnecessary rather than merely deferred.
+- **Serving `/f/<sessionId>/<segments…>` from the harness** — built and working, including confinement by dual `realpath`, the browser-trust fence, streamed reads, and a separate listener whose port gave served documents their own origin. It is the only design that shows a preview to a client on another machine, which is exactly the case ruled out of scope. Retired for that reason, not because it failed; its cost was a second socket with its own lifecycle, a port published into the page, and a URL-shape contract shared across two packages.
+- **Same-origin HTTP serving without isolation** — measurably unsafe, and recorded so nobody retries it: a document served beside `/api` drove `settings.describe` to a `200` with full data and `session.list` to 35 KB of every session's transcript, from a page that need not be agent-authored at all (a read row makes every file in a cloned repository openable).
+- **`Content-Security-Policy: sandbox` over that same-origin serving** — closes the hole by taking the document's origin away, which measurably breaks the pages this feature exists to show: the reported artifact throws `SecurityError` on load, and because an uncaught exception aborts the rest of its `<script>`, every listener declared after that line — theme toggle, mobile menu, model tabs — never binds. Two of the four artifacts in the reporting user's workspace were dead pages under it, and they still rendered perfectly, so the breakage was invisible.
+- **Linkifying paths in the assistant's closing message** — the shape a user asks for ("put the link at the end"), but it makes rendering depend on the model spelling a path recognizably. The tool calls already carry `locations` as structured fact, so the produced-files row consumes that instead.
+- **An embedded WebView in the desktop shell** — the strongest isolation available, since the preview then runs in a container the product owns rather than in the user's browser. It belongs to the desktop shell's own design, not to this surface, and is recorded here as the direction a future preview capability should take.
 
 ## Consequences
 
-Every existing file affordance changed target at once: write, edit, read, and the generic single-file card all reach `openFile`, so one call-site edit made produced files openable in the browser, LAN clients included. Three tests asserting the old `openPath` destination were rewritten to the new one; the outside-workspace fallback keeps the old assertion. The route is covered against a real HTTP server and a real temporary workspace, because confinement, content typing, and the sandbox header are wire facts, and the assembled web lane (`apps/web/tests/workspace-file-open.e2e.ts`, keyless over a cold-seeded session) proves the product path: clicking a read row's path opens `/f/<sessionId>/a.txt` in a second tab serving that workspace file, while a traversal spelling answers 404. A preview runs with its own origin's full capabilities, so a generated page behaves as its author intended. The residual the port does not close: two Sessions share one workspace-file origin, so a document from one may fetch another's served files. That is strictly narrower than the API surface it replaces, and narrowing it further would mean an origin per Session, which nothing today needs. The produced-files row ships here too: `turnDeliverables` reads a turn's output off the mutation tools' render intent (a diff card, or a generic card whose `kind` is `edit`), resets on the turn boundary so an interrupted turn cannot spill into the next, and renders under the closing assistant. Still deferred: linkification inside assistant Markdown, and any cross-session view of past deliverables.
+Every existing file affordance changed at once: write, edit, read, and the generic single-file card all reach `openFile`, so the link fix and the browser preference apply to all of them without a per-row change. The keyless web lane (`apps/web/tests/produced-files.e2e.ts`) cold-seeds a recorded write turn and pins the row in the assembled application; it deliberately does not click, because the click hands a path to the Host's opener and would launch a real application on the machine running the suite. A produced file opens as a `file://` document, which cannot `fetch` its own siblings (a multi-file artifact that loads `./data.json` breaks, while `<script src>`, `<img>`, and CSS `@import` are unaffected) — the one capability HTTP serving had that this does not. A client reached over the network sees nothing when it clicks: `host.openPath` runs on the Host and is loopback-pinned by the `/api` trust fence. That is the scope decision showing through, not a defect, and it is why the row keeps the full path in its `title` for a reader who can only copy it. Markdown opens in whatever the platform hands `.md`, usually an editor rather than a renderer; rendering it inside the product is a separate, deferred surface.
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index 63d746b0a9..91aa94c6fe 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -4,36 +4,32 @@ Status: implemented
 
 [English](2026-07-31-web-workspace-file-links.md) | 中文
 
-> 范围：web 传输层上的 `/f` 工作区文件路由、其背后的 `IWorkspaces.fileUrl` 推导、会话中打开文件的交互改指向它，以及完成的一轮以其产出文件收尾的那一行。不在范围内：产物注册表、版本、实时重载，或任何面向模型的声明。
+> 范围：完成的一轮以其产出文件收尾的那一行、读得出是链接的文件路径链接，以及 Host 打开器对浏览器可渲染文档优先选用默认浏览器。经决定不在范围内：以 HTTP 提供工作区文件，以及为不在 Host 机器上的客户端提供预览。
 
 ## 问题
 
 一个产出了文件的 web 会话，没有办法看到那个文件。agent 写出了 `deepseek-homepage.html` 并如实告知，而用户唯一的办法是把 `/private/tmp/dsh-client-hotplug.ygPvsm/workspaces/plugin-hotplug/deepseek-homepage.html` 这样的绝对路径复制进终端。
 
-零件几乎都在，只是指错了目标。`ToolRow` 早已把改写行或读取行的路径渲染成一个真正的按钮，`ui-conversation` 早已把它的点击经由 `openFile` 转发，`workspaces.openPath` 也早已把它送到 Host 的系统打开器。但那个打开器运行在 Host 机器上，而 `host.openPath` 被 `/api` 信任 fence 钉在回环，所以这个交互对经 LAN 访问的浏览器什么都答不了，即便在本机也是隐形的（路径的样式就是普通文本，只有 hover 时才有下划线）。与此同时 `MarkdownText` 会剥掉每一个非 `http(s)` 的 URL，因此模型写进收尾消息里的路径根本不可能成为链接；而 `ToolCallView.locations`——文件工具早已填好的跟随文件词汇——在客户端没有任何消费方。
+这背后是两个不同的缺陷。转录从不说明一轮产出了什么：`ToolCallView.locations`——文件工具早已填好的跟随文件词汇——在客户端没有任何消费方，因此读者对产出的唯一交代，就是收尾消息恰好拼出来的那点内容。而已经存在的那个交互是隐形的：`ToolRow` 早已把改写行或读取行的路径渲染成一个接到 `host.openPath` 的真按钮，但它的样式与周围正文一模一样、只有悬停才有下划线，于是没人发现。所报告的“做完了打不开”，是一个可发现性失败叠在一项本就可用的能力之上。
 
 ## 决定
 
-**在已有的传输层上加一条前缀路由，而不是加一项能力。** `client-connection` 持有两条面向浏览器的前缀：`/api` 承载 RPC，`/f/<sessionId>/<segments…>` 承载工作区文件读取。它本来就是持有 `httpServer`、`trustedHosts` 配置和浏览器信任 fence 的那个包；单开一个包会把 fence 和配置各复制一份，并逼着 `AppCLIEntry` 为一个 `--trusted-host` 标志去 patch 两行。webserver 自己的契约——每个特性面都是别的插件注册的一条路由——让这条路由本身就是全部机制。段落走路径而非查询参数，是为了让所服务文档的相对引用能解析到它的同级文件。
+**完成的一轮以它产出的文件收尾。** `turnDeliverables` 从改写工具自身的跟随文件 `locations` 中读出它们——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，这一轮的产出都会被列出；新的改写工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。该行渲染在收尾 assistant 正文之下、其 IconActions 之上，键控到 `assistantActionsSeqs` 早已选出的那个 seq。
 
-**请求指名 Session，由网关指名权限边界。** `ApiProxy.workspaceRootOf` 回答某个 Session 的文件位于何处——先看活跃 agent 的 `session.header.cwd`，再看持久化存储，绝不恢复会话——它是会话摘要早已携带的那个 `cwd` 的第二副面孔，只是不带信封。路由读取它而不是直接够 `ctx.agents`，因为 `client-connection` 注册在 client 程序里，而引入核心服务包会把它们 host 侧的 `sessions: SessionStore` 声明盖到浏览器运行时自己的 `sessions: SessionsService` 之上——这正是 `tsconfig.host.json`／`tsconfig.client.json` 分立所要防的那种冲突。cwd 与解析出的目标在前缀比较前都要过 `realpath`，因此工作区内指向工作区外的符号链接会因其目标而被拒绝；穿越写法在解析期就被拒，早于任何文件系统调用。读取经 `pipeline` 流出，因此客户端离开即销毁描述符，任何请求都不会把文件缓冲起来。
+**路径链接读得出是链接。** 静止状态下就带下划线，而不只在悬停时。这是本次改动中更小的那一半，却是修复中更大的那一半。
 
-**URL 形状落在 `dsh-host-apiproxy/api`，与其余浏览器可导入的契约面同处一地。** 两端必须就同一套编码达成一致，但客户端 bundle 不允许值导入另一个插件的包：`packages/client/tsdown.client.ts` 里的纯度 gate 只放行平台模块与 `INLINE_SAFE` 协议层，而 apiproxy 正是其中之一。把 `api/files.ts` 放在那里，才使构造 URL 的浏览器半侧与解析它的服务半侧共用单一来源，而且没有新增任何包依赖边——两侧本来就依赖 apiproxy。
+**打开仍然是 Host 的职责，并且优先选用默认浏览器。** `host.openPath` 把路径交给操作系统，得到的是真实浏览器里的一份 `file://` 文档：页面能力完整，且够不到 `/api`——因为 `file://` 文档与它并不同源。在所报告的那份产物上实测：`localStorage` 可用、主题切换生效、tabs 可切换，而对 API 的 `fetch` 失败。对浏览器能渲染的文档——`.html`、`.htm`、`.xhtml`、`.svg`——打开器解析的是默认**浏览器**而非该类型的默认应用，因为把 `.html` 绑给编辑器的开发者，否则点开一个产出的页面得到的会是源码。每个平台在自己能力范围内回答“哪个浏览器”（macOS 取 LaunchServices 的 `https` 处理程序，Linux 取 `$BROWSER`），任何一步失败都回退到默认应用，而不是把失败抛给用户。
 
-**工作区文件获得自己的端口，因而拥有自己的源。** 隔离这件事在落到此处之前走了三步。最初是加 sandbox 头，理由是 `/api/events.mux` 是一条同源可读的 `GET` 流。随后它被拿掉，前提是这些文件由 agent 撰写、浏览器边界只会立在一条早已越过的边界之后——而评审推翻了这个前提：一条 read 行就让 clone 下来的仓库里任何文件变得可打开，而同源的活动文档经实测能把 `/api/settings.describe` 打到 `200` 并拿到完整数据，从一个本次会话中无人撰写的页面触达了被钉在回环的设置与凭据面。加回 sandbox 堵住了它，而“量清楚它的代价”决定了最终形状：在 `CSP: sandbox` 之下，报告中那份产物加载时就抛 `SecurityError`，又因为未捕获异常会中止其 `<script>` 的其余部分，该行之后声明的所有监听器——主题切换、移动端菜单、模型 tabs——统统不会绑定。报告者工作区里四份产物有两份在它之下是死页面，而且它们**看上去**仍然正常。第二个端口给出了这条边界而无需截肢：对 `/api` 是跨源（被 fence 的 Origin 校验与 CORS 双重拒绝），对自身是同源（因此 `localStorage`、cookie 与 `fetch` 都可用）。它绑定与 API 相同的 host，因此 LAN 预览继续可用；只应答 `/f`，别无其他；并把端口注入首页供浏览器半侧寻址。
-
-**客户端靠推导决定，而不是靠探测。** `ConnectionHandle.fileUrl(sessionId, cwd, path)` 把工具报告的路径表达为 session cwd 之下的段落，并返回工作区文件源上的绝对 URL——页面自身的主机名，加上已发布的端口——路径离开工作区或没有端口发布时返回 `undefined`。它落在 connection 句柄上，是因为传输层同时持有两端：提供字节的监听器，和寻址它的端口。`undefined` 恰好就是回退到 `openPath` 的信号，这也让无密钥 fixture 通道（不由任何 host 提供）退化为旧行为，而不是打开一个空标签页。
+**以 HTTP 提供工作区文件不在范围内，非本机客户端亦然。** 更早的一版由 harness 自己提供文件——先是与 `/api` 同源，随后加上 `CSP: sandbox`，再后来交给一个以自身端口给所服务文档独立源的第二监听器。每一步都在回答一个真实问题，而整条线在产品范围定下之后被整体退役：不为“浏览器不在 Host 机器上”的场景提供预览。这一点定下之后，Host 打开器完整回答了受支持的场景，而那套 HTTP 机制回答的只是不受支持的那个。
 
 ## 考虑过的替代方案
 
-- **产物能力族（RFC #268 / PR #272）**——一条带 id、版本、快照存储、自有 HTTP 服务器、SSE 实时重载与浏览器自动打开器的 seam。它的评审给出了七个 critical，而每一个都来自那套机械结构：未监听的打开器 spawn 会让 harness 崩溃、打开器继承 `DEEPSEEK_API_KEY`、进行中的 publish 活过 dispose、`readFile` 先于大小上限、快照的 TOCTOU，以及未 dispose 的 agent 导致保留期泄漏。`dsh web` 本来就跑着一个 HTTP 服务器，用户本来就在浏览器里，那套机械结构在这里买不到任何东西。RFC 与其测试保留下来，作为真正出现跨会话或版本化产物需求那天的输入；届时这条路由就是那条 seam 的天然挂载点。
-- **单开一个 `dsh-client-workspace-files` 包**——如果文件服务是一项独立能力，这才是诚实的 seam 形状。它不是：它需要与 `/api` 相同的 fence 和相同的 `trustedHosts` 值，拆分会把两者都复制一份，违背仓库自己的“不要预先拆分”。
-- **把 URL 形状模块留在 `client-connection` 里、由 runtime 去导入**——最初就是这么写的，构建直接拒绝：向客户端 bundle 做跨插件值导入，要么内联出一份重复的运行时实例，要么落到冻结模块表答不出的说明符上。这道 gate 正是共享模块落在协议层、而非落在恰好持有该路由的那个包里的原因。
-- **`/f/<绝对路径>`，好让 `openPath` 保持为唯一调用点**——这会把 sessionId 从 URL 里去掉，但所服务的权限边界随之变成 host 已知的全部工作区之并集。紧的权限边界只花掉一处调用点的改动，因为 `openFile` 本来就同时持有 sessionId 与 cwd。
-- **用 `connect-src 'none'` 加一道导航栅栏，在 sandbox 之下保住 `localStorage`**——针对“读走 SSE 流”这条向量经实测可行（Chrome 对 `window.open` 发 `Sec-Fetch-Dest: document`、对 `EventSource` 发 `empty`，回环也在内），但它从未触及更大的那条：真正够到配置面的是向 POST 方法发起的同源 `fetch`，而“从所服务文档一侧封住 `connect-src`”恰恰是敌意文档不会对自己做的事。
-- **保留 sandbox 并接受这条限制**——这笔交易的真实读数要量过才看得见：它不是“预览记不住主题”，而是“预览的整段脚本在第一次访问存储时就死了”，而页面照样渲染得完美无缺。一条没人看得见的限制，比一条要花掉一个端口的限制更糟。
-- **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带，产出文件行消费的正是它；因此把正文链接化是不必要，而不只是被推迟。
+- **由 harness 提供 `/f/<sessionId>/<segments…>`**——已经实现并可用，包含双 `realpath` 收敛、浏览器信任 fence、流式读取，以及一个以自身端口给所服务文档独立源的监听器。它是唯一能把预览呈现给另一台机器上客户端的设计，而那恰恰是被判出范围的场景。因此退役，而不是因为它失败了；它的代价是一个带自身生命周期的第二 socket、一个注入页面的端口，以及一份跨两个包共享的 URL 形状契约。
+- **同源 HTTP 提供且不加隔离**——经实测不安全，记录在此以免有人重试：与 `/api` 并排提供的文档把 `settings.describe` 打到 `200` 并拿到完整数据，把 `session.list` 打到 35 KB 的全部会话转录，而这个页面根本不必由 agent 撰写（一条 read 行就让 clone 下来的仓库里任何文件变得可打开）。
+- **在那套同源提供之上加 `Content-Security-Policy: sandbox`**——它以剥夺文档的源来堵住这个洞，而这经实测会破坏本功能存在的意义所在的那类页面：所报告的产物在加载时抛 `SecurityError`，又因为未捕获异常会中止其 `<script>` 的其余部分，该行之后声明的所有监听器——主题切换、移动端菜单、模型 tabs——统统不会绑定。报告者工作区里四份产物有两份在它之下是死页面，而且它们渲染得完美无缺，所以这种破坏是看不见的。
+- **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带，产出文件行消费的正是它。
+- **桌面端外壳中的内嵌 WebView**——可得到的最强隔离，因为那时预览跑在产品自己拥有的容器里，而不是用户的浏览器里。它属于桌面端外壳自身的设计，而非本交互面，记录在此作为未来预览能力应走的方向。
 
 ## 影响
 
-现有的每一处文件交互都同时换了目标：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此一处调用点的改动就让产出的文件在浏览器里可打开，LAN 客户端也在内。三个断言旧 `openPath` 去向的测试被改写为新的去向；工作区外的回退保留了旧断言。这条路由对着真实 HTTP 服务器与真实临时工作区做覆盖，因为收敛、内容定型与 sandbox 头都是协议事实；而组装后的 web 通道（`apps/web/tests/workspace-file-open.e2e.ts`，在冷播种会话上无密钥运行）证明了产品路径：点击读取行的路径会在第二个标签页打开 `/f/<sessionId>/a.txt` 并提供那个工作区文件，而穿越写法应答 404。预览以自身源的完整能力运行，因此生成的页面按其作者的意图工作。端口没有堵住的残余：两个 Session 共用同一个工作区文件源，因此来自其一的文档可以 fetch 另一个已服务的文件。这比它所替代的 API 面严格更窄，而要再窄一层就意味着每个 Session 一个源，今天没有任何需求指向那里。产出文件行也在本次一并落地：`turnDeliverables` 依据改写工具的渲染意图（diff 卡片，或 `kind` 为 `edit` 的 generic 卡片）读出一轮的产出，在 turn 边界重置以免中断的一轮溢进下一轮，并渲染在收尾 assistant 之下。仍然暂缓：助手 Markdown 内部的链接化，以及任何跨会话回看既往产物的视图。
+现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接可见性修复与浏览器优先策略无需逐行改动即适用于全部。无密钥 web 通道（`apps/web/tests/produced-files.e2e.ts`）冷播种一段录制的 write 轮次，在组装后的应用中钉住该行；它刻意不点击，因为点击会把路径交给 Host 打开器，从而在跑测试的机器上启动一个真实应用。产出的文件以 `file://` 文档打开，它无法 `fetch` 自己的同级文件（一个加载 `./data.json` 的多文件产物会坏，而 `<script src>`、`<img>` 与 CSS `@import` 不受影响）——这是 HTTP 提供曾有、而此处没有的那一项能力。经网络访问的客户端点击后看不到任何东西：`host.openPath` 在 Host 上运行，且被 `/api` 信任 fence 钉在回环。那是范围决定的显现，不是缺陷，也正因如此该行把完整路径保留在 `title` 中，供只能复制它的读者使用。markdown 会由平台交给 `.md` 的默认处理程序打开，通常是编辑器而非渲染器；在产品内渲染它是另一个被推迟的交互面。
diff --git a/apps/web/tests/produced-files.e2e.ts b/apps/web/tests/produced-files.e2e.ts
new file mode 100644
index 0000000000..c96131bf69
--- /dev/null
+++ b/apps/web/tests/produced-files.e2e.ts
@@ -0,0 +1,76 @@
+// Web e2e scenario: the produced-files row a finished turn ends with. Cold-seeds
+// a recorded write turn (zero model calls). Package tests cover the derivation
+// in isolation, but only the assembled application shows that a turn's writes
+// reach the transcript as an openable row (docs/testing.md snapshot rule). The
+// click itself is not driven here: it hands the path to the Host's opener,
+// which would launch a real application on the machine running the suite.
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import {
+  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+// Borrowed read-only: this scenario needs any settled turn whose tools WROTE a
+// file, not a new recording (the message-actions borrowing pattern).
+const SEED = fileURLToPath(new URL('./snapshots/permission-policy-context/session.jsonl', import.meta.url))
+const MODE = webSnapshotMode()
+const SEED_ID = 'produced-files-web-e2e'
+
+/** The file the borrowed recording's write tool produces. */
+const PRODUCED = 'policy-neutral.txt'
+
+describe('web e2e: a finished turn ends with the files it produced', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    // The seeded Session's cwd is the scaffold workspace; the recording's own
+    // nested directory is created too, so its paths stay resolvable.
+    await mkdir(join(scaffold.workspaceCwd, 'workspace'), { recursive: true })
+    await writeFile(join(scaffold.workspaceCwd, PRODUCED), 'neutral\n')
+    const raw = await readFile(SEED, 'utf8')
+    expect(raw, 'borrowed recording must carry the write this scenario reads').toContain(PRODUCED)
+    await seedSession(scaffold, raw, SEED_ID)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it.skipIf(MODE === 'record')('lists the written file under the closing message, as an opener', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-produced-files'))
+    const groupRow = page.locator('[role="treeitem"]').first()
+    await groupRow.waitFor({ timeout: 15_000 })
+    await groupRow.click()
+    const sessionRow = page.locator('[role="treeitem"]').nth(1)
+    await sessionRow.waitFor({ timeout: 10_000 })
+    await sessionRow.click()
+
+    // The row the turn ends with — derived from the write call's locations,
+    // not from whatever the closing message happened to say.
+    const chip = page.getByRole('button', { name: `Open ${PRODUCED}`, exact: true }).first()
+    await chip.waitFor({ timeout: 15_000 })
+    expect(await chip.innerText()).toBe(PRODUCED)
+    // The full path stays reachable for a reader who wants to copy it.
+    expect(await chip.getAttribute('title')).toContain(PRODUCED)
+    // A turn's produced files are labelled, not left as bare chips.
+    expect(await page.getByText('Produced', { exact: true }).count()).toBeGreaterThan(0)
+
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  }, 90_000)
+})
diff --git a/apps/web/tests/workspace-file-open.e2e.ts b/apps/web/tests/workspace-file-open.e2e.ts
deleted file mode 100644
index 8f6bd6f665..0000000000
--- a/apps/web/tests/workspace-file-open.e2e.ts
+++ /dev/null
@@ -1,122 +0,0 @@
-// Web e2e scenario: a produced file, from the row that lists it to the bytes
-// the browser gets. Cold-seeds a recorded write turn (zero model calls).
-// Package tests cover the derivation and the route in isolation, but only the
-// assembled application shows that the turn's Produced row, the URL it opens,
-// and the file on disk are the same thing (docs/testing.md snapshot rule).
-import { readFile, writeFile, mkdir } from 'node:fs/promises'
-import { join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import type { Browser, Page } from 'playwright'
-import { chromium } from 'playwright'
-import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
-import {
-  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
-} from './scaffold.ts'
-import { newEnglishPage, saveFailureShot } from './support.ts'
-
-// Borrowed read-only: this scenario needs any settled turn whose tools WROTE a
-// file, not a new recording (the message-actions borrowing pattern).
-const SEED = fileURLToPath(new URL('./snapshots/permission-policy-context/session.jsonl', import.meta.url))
-const MODE = webSnapshotMode()
-const SEED_ID = 'workspace-file-open-web-e2e'
-
-/** The file the borrowed recording's write tool produces. */
-const PRODUCED = 'policy-neutral.txt'
-/** An active document placed alongside it, for the isolation header the route puts on those. */
-const ACTIVE = 'preview.html'
-
-describe('web e2e: opening a produced file from the conversation', () => {
-  let scaffold: WebScaffold
-  let browser: Browser
-  let page: Page
-  let tripwire: ReturnType<typeof watchConsole>
-
-  beforeAll(async () => {
-    scaffold = await launchWebScaffold({})
-    // The seeded Session's cwd is the scaffold workspace; the recording's own
-    // nested directory is created too, so its paths stay resolvable.
-    await mkdir(join(scaffold.workspaceCwd, 'workspace'), { recursive: true })
-    await writeFile(join(scaffold.workspaceCwd, PRODUCED), 'neutral\n')
-    await writeFile(join(scaffold.workspaceCwd, ACTIVE), '<h1>produced</h1>\n')
-    const raw = await readFile(SEED, 'utf8')
-    expect(raw, 'borrowed recording must carry the write this scenario reads').toContain(PRODUCED)
-    await seedSession(scaffold, raw, SEED_ID)
-    browser = await chromium.launch()
-    page = await newEnglishPage(browser)
-    tripwire = watchConsole(page)
-    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
-    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
-  }, 120_000)
-
-  afterAll(async () => {
-    await browser?.close()
-    await scaffold?.close()
-  })
-
-  it.skipIf(MODE === 'record')('ends the turn with its produced file, which opens as the workspace file itself', async () => {
-    onTestFailed(() => saveFailureShot(page, 'web-e2e-workspace-file-open'))
-    const groupRow = page.locator('[role="treeitem"]').first()
-    await groupRow.waitFor({ timeout: 15_000 })
-    await groupRow.click()
-    const sessionRow = page.locator('[role="treeitem"]').nth(1)
-    await sessionRow.waitFor({ timeout: 10_000 })
-    await sessionRow.click()
-
-    // The row the turn ends with — derived from the write call's locations,
-    // not from whatever the closing message happened to say.
-    const chip = page.getByRole('button', { name: `Open ${PRODUCED}`, exact: true }).first()
-    await chip.waitFor({ timeout: 15_000 })
-    expect(await chip.innerText()).toBe(PRODUCED)
-
-    const [opened] = await Promise.all([
-      page.context().waitForEvent('page', { timeout: 15_000 }),
-      chip.click(),
-    ])
-    await opened.waitForLoadState('domcontentloaded')
-    const url = new URL(opened.url())
-    expect(url.pathname).toBe(`/f/${SEED_ID}/${PRODUCED}`)
-    expect(await opened.locator('body').innerText()).toContain('neutral')
-
-    // The isolation: previews come from the app's hostname on a DIFFERENT
-    // port, so a served document is cross-origin to /api while keeping its own
-    // capabilities. A workspace file is not necessarily agent-authored.
-    const app = new URL(scaffold.baseUrl)
-    expect(url.hostname).toBe(app.hostname)
-    expect(url.port).not.toBe(app.port)
-    const filesOrigin = url.origin
-
-    const served = await page.request.get(opened.url())
-    expect(served.status()).toBe(200)
-    expect(served.headers()['x-content-type-options']).toBe('nosniff')
-    expect(served.headers()['cache-control']).toBe('no-store')
-    // No document is stripped of its origin: the port is the boundary.
-    expect(served.headers()['content-security-policy']).toBeUndefined()
-
-    // An active document keeps its own storage — the capability a sandbox
-    // header would have taken, and the reason this route has its own port.
-    const active = opened
-    await active.goto(`${filesOrigin}/f/${SEED_ID}/${ACTIVE}`, { waitUntil: 'load' })
-    expect(await active.evaluate(() => {
-      try { window.localStorage.setItem('probe', '1'); return 'ok' } catch { return 'blocked' }
-    })).toBe('ok')
-    // …and cannot reach the API, which lives on the other origin.
-    expect(await active.evaluate(async (base) => {
-      try {
-        await fetch(`${base}/api/session.list`, {
-          method: 'POST', headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ type: 'client-request', rpcId: 'x', method: 'session.list', payload: {} }),
-        })
-        return 'reached'
-      } catch { return 'blocked' }
-    }, scaffold.baseUrl)).toBe('blocked')
-
-    // The workspace-file origin serves that one prefix and nothing else.
-    expect((await page.request.get(`${filesOrigin}/`)).status()).toBe(404)
-    // Nothing outside the Session's workspace is reachable through the route.
-    expect((await page.request.get(`${filesOrigin}/f/${SEED_ID}/..%2Fetc%2Fhosts`)).status()).toBe(404)
-
-    await active.close()
-    expect(tripwire.pageErrors).toEqual([])
-    expect(tripwire.warnings).toEqual([])
-  }, 90_000)
-})
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 2c65f1e510..48db884aad 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -51,7 +51,7 @@
     "tests/access-confirmation.e2e.ts",
     "tests/shipped-composition.e2e.ts",
     "tests/startup-auto-selection.e2e.ts",
-    "tests/workspace-file-open.e2e.ts"
+    "tests/produced-files.e2e.ts"
   ],
   "references": [
     {
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 7c21713f01..a356a151e3 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -296,7 +296,7 @@ export interface ConnectionConfig {
 }
 ```
 
-Source: [`packages/client/connection/src/index.ts:25`](../packages/client/connection/src/index.ts)
+Source: [`packages/client/connection/src/index.ts:20`](../packages/client/connection/src/index.ts)
 
 ## `@deepseek-ai/dsh-client-hmr`
 
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index af7d3d590d..682314605d 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
-README.md: 5001da2458ea3470659f5983dffc8de832aadeac
-README.zh.md: 47e745964e4087c6ccc59aae5bbfba69f96480e4
+README.md: c8b7c4787cbcbf6a202fb944459a589fcadd7c8d
+README.zh.md: f36cb4c4c6856089751e4492eb6e4b8e22abde56
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index 5001da2458..c8b7c4787c 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,22 +2,14 @@
 
 English | [中文](README.zh.md)
 
-Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The node half owns both browser-facing prefixes — `/api` for RPC and `/f` for workspace-file reads — behind one trust fence. The `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`, reads included, since describing returns the exposed configuration and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. Contract: api-contracts v3 §3.
+Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`, reads included, since describing returns the exposed configuration and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. Contract: api-contracts v3 §3.
 
 ## /api browser-trust fence
 
 The node half guards every request under `/api` before bridging (`src/api-request-trust.ts`). Every request — browser-marked or not — must present a `Host` that is a loopback authority or matches a `trustedHosts` entry: exact on `host:port` entries, any port on port-less entries, both sides compared through WHATWG normalization (DNS-rebinding defense). There is deliberately no shortcut for requests without browser markers: over plain HTTP a browser attaches neither `Origin` nor Fetch-Metadata to reads (EventSource, images, navigations — those headers go only to trustworthy destinations), so an unmarked request may still be a rebound browser read with a readable response, and Host is the one header rebinding cannot forge; non-browser clients pass the same fence via loopback, the CLI-derived LAN IP literals, or a declared authority. When markers are present, an attached `Origin` must equal the Host authority, and an explicit `sec-fetch-site: cross-site` marker is refused. A `trustedHosts` entry that is not a bare, canonical `host[:port]` authority — one WHATWG parsing reads back exactly as written — fails the plugin load loudly: parsing would otherwise quietly authorize the hostname inside `harness.internal/path`, or broaden a dangling-colon or zero-padded port to an any-port grant. Failures answer plain 403 before any RPC dispatch. A non-loopback (`--host 0.0.0.0`) deployment therefore needs its serving authorities trusted: the dsh CLI derives the machine's LAN IP literals itself and its `--trusted-host` flag declares named ones, so `trustedHosts` in cordis.yml is for compositions the CLI does not boot. The fence is deliberately not an authentication layer — reachability policy stays with the webserver binding, and auth remains deferred work. Decision record: [the api browser-trust boundary Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md).
 
-## /f workspace-file reads
-
-The node half also serves one file at a time out of a Session's workspace under `/f/<sessionId>/<segments…>`, so a produced deliverable is reachable from the page that reported it — an `http` page cannot follow a `file://` link, and a browser that is not on the Host machine has no such path anyway. The segments ride the URL rather than a query parameter so a served document's relative references resolve to its siblings. The request names a Session and the gateway names that Session's directory (`ApiProxy.workspaceRootOf`, which answers from a live agent's header or the persistence store and never resumes an agent to serve a file); this package reads the authority rather than the core services, because holding their host-side Context declarations would merge them over the browser runtime's own. The URL shape itself lives with the other browser-importable contract surfaces, in [`@deepseek-ai/dsh-host-apiproxy/api`](../../host/apiproxy/README.md), so the browser half that builds a URL and this half that parses one share a single encoding decision. Both the cwd and the resolved target go through `realpath` before comparison, so a symlink inside the workspace pointing out of it is refused by its target rather than its name; traversal spellings are refused earlier still, at parse time, before any filesystem call. Reads stream (no request buffers a file), answer `GET`/`HEAD` only, and carry `nosniff` with `no-store`. Extensions outside the served content-type table are typed `text/plain` rather than offered as a download, because a workspace read is a request to see a file.
-
-Workspace files are served from their own port, and therefore their own origin. That port is the isolation: a workspace file is not necessarily agent-authored — a read row makes every file in a cloned repository openable — so an active document served beside `/api` would have its script pass the browser-trust fence into every method, the loopback-pinned settings and credential plane included. A different origin closes that without touching the document: a preview keeps `localStorage`, cookies, and its own `fetch`, while a call to the API is cross-origin and refused twice over — by the fence's Origin check and by CORS. The alternative, `Content-Security-Policy: sandbox`, buys the same boundary by taking the document's origin away entirely, which measurably breaks the pages this route exists to show (a page that reads `localStorage` throws on load, and every listener declared after that line in the same script never binds). The listener binds the same host as the API, so a client that can reach the app can reach its previews; it answers the `/f` prefix and nothing else — no index, no SPA fallback, no API — and its port is published into the index page as `window.__DSH_FILES_PORT__`, which the browser half reads to address it. The same trust fence gates it, so a `trustedHosts` deployment serves workspace files exactly where it serves ordinary reads.
-
 ## Keyless fixture
 
-A fixture page is served by no host, so no workspace-file port is published into it and `ConnectionHandle.fileUrl` answers `undefined` — a file-path row falls back to the Host opener rather than opening a dead tab.
-
 Any `fixture` query parameter selects the in-memory carrier. `fixture=empty` starts with no Workspace or Session; `fixturePrompt=reject` rejects prompts before acceptance; `fixtureAttach=fail` publishes a Session but rejects its Workspace attachment; `fixtureSessionCreate=drop-response` publishes and frames a Session before dropping the create response; and `fixtureFrames=workspace-first` reverses the default session-first create-frame order. Workspace creation by name/path and caller-preallocated SessionIds remain deterministic enough for assembled Web tests to reconcile list and frame arrival. Fixture content search preserves the production-facing `unicode61`-style case, diacritic, and token-phrase behavior and returns a match-centered snippet of at most 120 Unicode code points.
 
 ## Model Experience
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index 47e745964e..f36cb4c4c6 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,18 +2,12 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。node 半侧持有两条面向浏览器的前缀——`/api` 承载 RPC，`/f` 承载工作区文件读取——共用同一道信任 fence。`/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`，读取也在内，因为 describe 会返回已暴露的配置，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。契约：api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`，读取也在内，因为 describe 会返回已暴露的配置，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。契约：api-contracts v3 §3。
 
 ## /api 浏览器信任栅栏
 
 node 半侧在桥接前守卫 `/api` 下的每个请求（`src/api-request-trust.ts`）。每个请求——无论是否带浏览器标记——`Host` 都必须是回环地址权威，或与某个 `trustedHosts` 条目匹配：带端口的 `host:port` 条目精确匹配，不带端口的条目匹配任意端口，两侧均经 WHATWG 归一化后比较（DNS rebinding 防御）。刻意不为无浏览器标记的请求开捷径：明文 HTTP 下浏览器的读取（EventSource、图片、导航——这些头只发给可信目标）既不带 `Origin` 也不带 Fetch-Metadata，因此无标记请求仍可能是被重绑页面发起的、响应可被读走的读取，而 Host 是重绑唯一伪造不了的请求头；非浏览器客户端经由回环地址、CLI 推导的 LAN IP 字面量或已声明的权威通过同一道栅栏。当标记存在时，`Origin` 必须与 Host 权威完全一致；显式的 `sec-fetch-site: cross-site` 标记一律拒绝。不是纯的、规范形 `host[:port]` 权威的 `trustedHosts` 条目——即 WHATWG 解析读回后与原文不完全一致的——会让插件加载大声失败：否则解析会悄悄授权 `harness.internal/path` 这类笔误里的 hostname，或把悬空冒号、补零端口放大成任意端口授权。失败在任何 RPC 分发之前以纯 403 应答。因此非回环（`--host 0.0.0.0`）部署需要让自己的服务权威被信任：dsh CLI 会自行推导本机的 LAN IP 字面量，其 `--trusted-host` flag 用于声明具名权威，所以 cordis.yml 中的 `trustedHosts` 面向 CLI 不参与引导的组合。这道栅栏刻意不承担认证职责——可达性策略归 webserver 绑定配置，认证仍是延期工作。决策记录：[api 浏览器信任边界 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md)。
 
-## /f 工作区文件读取
-
-node 半侧还会在 `/f/<sessionId>/<segments…>` 下逐个提供某个 Session 工作区里的文件，让产出的交付物能从报告它的那个页面直接抵达——`http` 页面无法跟随 `file://` 链接，而不在 Host 机器上的浏览器本来也没有那条路径。段落走 URL 而非查询参数，是为了让所服务文档的相对引用能解析到它的同级文件。请求指名一个 Session，由网关指名该 Session 的目录（`ApiProxy.workspaceRootOf`，它从活跃 agent 的 header 或持久化存储作答，绝不会为了提供一个文件而恢复 agent）；本包读取这个权威来源而不去够核心服务，因为持有它们的 host 侧 Context 声明会把它们盖到浏览器运行时自己的声明之上。URL 形状本身与其余浏览器可导入的契约面放在一起，位于 [`@deepseek-ai/dsh-host-apiproxy/api`](../../host/apiproxy/README.md)，因此构造 URL 的浏览器半侧与解析 URL 的这一半共享同一个编码决定。cwd 与解析出的目标在比较前都要过 `realpath`，因此工作区内指向工作区外的符号链接会因其目标而被拒绝，而不是因其名字；穿越写法拒得更早，在解析期、任何文件系统调用之前。读取是流式的（没有请求会把文件缓冲起来），只应答 `GET`／`HEAD`，并带上 `nosniff` 与 `no-store`。所服务的内容类型表之外的扩展名一律按 `text/plain` 定型而非作为下载给出，因为工作区读取本就是一个“让我看看这个文件”的请求。
-
-工作区文件由它自己的端口提供，因而拥有自己的源。那个端口就是隔离：工作区文件未必由 agent 撰写——一条 read 行就能让 clone 下来的仓库里任何文件变得可打开——因此与 `/api` 并排提供的活动文档，其脚本会带着浏览器信任 fence 通行到每一个方法，包括那些正因会改动设置与凭据而被钉在回环的方法。换一个源即可堵死这条，且不必动文档本身：预览保有 `localStorage`、cookie 与自己的 `fetch`，而对 API 的调用属于跨源，会被两道独立的关卡拒绝——fence 的 Origin 校验，以及 CORS。另一种做法 `Content-Security-Policy: sandbox` 用"干脆剥夺文档的源"换来同一条边界，而这经实测会破坏本路由存在的意义所在的那类页面（读 `localStorage` 的页面在加载时抛异常，同一 script 块中该行之后声明的所有监听器都不会绑定）。该监听器绑定与 API 相同的 host，因此能访问应用的客户端也能访问它的预览；它只应答 `/f` 前缀，别无其他——没有首页、没有 SPA 兜底、没有 API——其端口以 `window.__DSH_FILES_PORT__` 注入首页，由浏览器半侧读取来寻址。它由同一道信任 fence 把守，因此配置了 `trustedHosts` 的部署提供工作区文件的范围，与它提供普通读取的范围完全一致。
-
 ## 无密钥 fixture
 
 fixture 页面不由任何 host 提供，因此没有工作区文件端口注入其中，`ConnectionHandle.fileUrl` 应答 `undefined`——文件路径行会回退到 Host 打开器，而不是打开一个空标签页。
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index f5fa3e34ea..0549fc1160 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2363,10 +2363,6 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       return Promise.resolve({ accepted: true })
     },
 
-    // The fixture has no filesystem behind its Sessions, so it names no
-    // directory for any of them; the /f route belongs to the node half, which
-    // a fixture page never reaches.
-    workspaceRootOf: () => Promise.resolve(undefined),
   }
 }
 
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index 004b9fe286..e286157e46 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -4,9 +4,6 @@
  * controller with its sinks.
  */
 import type { Context } from 'cordis'
-import { workspaceFileSegments, workspaceFileUrl } from '@deepseek-ai/dsh-host-apiproxy/api'
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import { FILES_PORT_GLOBAL } from '../files-server.ts'
 import type { IApiClient } from './api.ts'
 import { ConnectionController, type ConnectionConfig, type ConnectionSinks, type ConnectionState } from './connection.ts'
 import { FixtureApiClient } from './fixture.ts'
@@ -59,19 +56,6 @@ export interface ConnectionHandle {
    * @returns stop handle for the loop.
    */
   start(sinks: ConnectionSinks, config?: ConnectionConfig): { stop(): void }
-  /**
-   * Absolute URL serving one file out of a Session's workspace, on the
-   * transport's own workspace-file origin — the same hostname the page is
-   * reached by, a different port, so a served document is isolated from this
-   * API without being stripped of its own capabilities.
-   * @param sessionId - the Session whose cwd anchors the path.
-   * @param cwd - that Session's working directory, or `undefined` when unknown.
-   * @param path - the path a tool reported (absolute, or relative to `cwd`).
-   * @returns the URL, or `undefined` when the path lies outside the workspace
-   * (which this transport never serves) or when this page was not served by a
-   * host that published a workspace-file port (the fixture carrier).
-   */
-  fileUrl(sessionId: SessionId, cwd: string | undefined, path: string): string | undefined
 }
 
 /**
@@ -84,15 +68,6 @@ export function apply(ctx: Context): void {
   let started = false
   const handle: ConnectionHandle = {
     api,
-    fileUrl(sessionId, cwd, path) {
-      // Published by the node half's index tap; absent means no host is
-      // serving workspace files to this page (the keyless fixture lane).
-      const port = (globalThis as unknown as Record<string, unknown>)[FILES_PORT_GLOBAL]
-      if (typeof port !== 'number') return undefined
-      const segments = workspaceFileSegments(cwd, path)
-      if (segments === undefined) return undefined
-      return `${location.protocol}//${location.hostname}:${String(port)}${workspaceFileUrl(sessionId, segments)}`
-    },
     start(sinks, config) {
       if (started) throw new Error('connection: the stream loop is already owned by another consumer')
       started = true
diff --git a/packages/client/connection/src/files-server.ts b/packages/client/connection/src/files-server.ts
deleted file mode 100644
index 73807c0810..0000000000
--- a/packages/client/connection/src/files-server.ts
+++ /dev/null
@@ -1,127 +0,0 @@
-/**
- * The workspace-file listener: a second loopback/LAN socket on the same host
- * as the API, serving nothing but `/f`.
- *
- * The port is the isolation. A workspace file is not necessarily
- * agent-authored — a read row makes every file in a cloned repository
- * openable — so an active document must not be same-origin with `/api`, where
- * its script would pass the browser-trust fence into every method, the
- * loopback-pinned settings and credential plane included. A different port is
- * a different origin, which the browser enforces for free: the document keeps
- * `localStorage`, cookies, and its own `fetch`, while a call to the API is
- * cross-origin and refused twice over — by the fence's Origin check and by
- * CORS. The alternative, `Content-Security-Policy: sandbox`, buys the same
- * boundary by taking the document's origin away entirely, which measurably
- * breaks the pages this route exists to show.
- */
-
-import { createServer } from 'node:http'
-import type { IncomingMessage, Server, ServerResponse } from 'node:http'
-import type { AddressInfo } from 'node:net'
-import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
-import { isTrustedApiRequest } from './api-request-trust.ts'
-import { handleWorkspaceFile, type WorkspaceFileDeps } from './workspace-files.ts'
-
-/** A listening workspace-file server: its port, and the teardown that reaches quiescence. */
-export interface FilesServer {
-  /** The bound port (OS-assigned), which the browser half needs to address this origin. */
-  port: number
-  /** Close the socket and destroy held connections; resolves once quiet. */
-  close: () => Promise<void>
-}
-
-/**
- * Bind the workspace-file listener.
- * @param host - the same bind host the API uses, so a client that can reach
- * the app can reach its previews (a LAN deployment included).
- * @param trustedHosts - the deployment's non-loopback serving authorities,
- * applied through the same fence as `/api`.
- * @param deps - the session-to-directory lookup reads are confined by.
- * @param onSocketError - reports a post-listen socket error; without a
- * listener node would raise it as an unhandled 'error' event.
- * @returns the bound port and its disposer.
- */
-export async function listenForWorkspaceFiles(
-  host: string,
-  trustedHosts: readonly string[],
-  deps: WorkspaceFileDeps,
-  onSocketError: (error: Error) => void,
-): Promise<FilesServer> {
-  const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
-    if (!isTrustedApiRequest(req, trustedHosts)) {
-      res.writeHead(403)
-      res.end('forbidden')
-      return
-    }
-    /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server requests. */
-    const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
-    // This origin serves one prefix and nothing else: no index, no SPA
-    // fallback, no API. Anything else is not here — answered before the method
-    // check, because a 405 would claim the resource exists.
-    if (pathname !== FILES_PATH && !pathname.startsWith(`${FILES_PATH}/`)) {
-      res.writeHead(404)
-      res.end()
-      return
-    }
-    if (req.method !== 'GET' && req.method !== 'HEAD') {
-      // RFC 9110 §15.5.6: a 405 names the methods the resource does support.
-      res.writeHead(405, { allow: 'GET, HEAD' })
-      res.end()
-      return
-    }
-    await handleWorkspaceFile(req, res, deps)
-  }
-
-  const server: Server = createServer((req, res) => {
-    handle(req, res).catch((error: unknown) => {
-      // A malformed request must not become an unhandled rejection that takes
-      // the process down; the API carrier guards its own handler the same way.
-      if (res.headersSent) {
-        res.destroy()
-        return
-      }
-      onSocketError(error instanceof Error ? error : new Error(String(error)))
-      res.writeHead(400)
-      res.end()
-    })
-  })
-
-  await new Promise<void>((resolve, reject) => {
-    server.once('error', reject)
-    server.listen(0, host, () => {
-      server.off('error', reject)
-      server.on('error', onSocketError)
-      resolve()
-    })
-  })
-
-  return {
-    port: (server.address() as AddressInfo).port,
-    // close + closeAllConnections: a held-open response would otherwise keep
-    // teardown waiting forever.
-    close: () => new Promise<void>((resolve) => {
-      server.close(() => { resolve() })
-      server.closeAllConnections()
-    }),
-  }
-}
-
-/** The global the node half hands its port to the browser half through. */
-export const FILES_PORT_GLOBAL = '__DSH_FILES_PORT__'
-
-/**
- * Inject the workspace-file port into index.html, ahead of the shell bundle
- * that reads it. A boot-time fact of the serving host, delivered the way the
- * module graph is: synchronously on the page, so the first click on a produced
- * file does not race a round trip.
- * @param html - the index.html source.
- * @param port - the bound workspace-file port.
- * @returns the html with the port script injected.
- */
-export function injectFilesPort(html: string, port: number): string {
-  const script = `<script>window.${FILES_PORT_GLOBAL} = ${String(port)}</script>`
-  const head = html.indexOf('<head>')
-  if (head !== -1) return `${html.slice(0, head + 6)}${script}${html.slice(head + 6)}`
-  /* v8 ignore next -- headless fixture pages may lack <head>; prepending keeps read-before-shell ordering. */
-  return `${script}${html}`
-}
diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts
index f0a60bbfb9..03f8aaa257 100644
--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -1,16 +1,11 @@
-/** Host HTTP bridge for browser-client RPC and workspace-file reads. */
+/** Host HTTP bridge for browser-client RPC. */
 import type { Context } from 'cordis'
 import z from 'schemastery'
 // Activates the httpServer Context merge used below.
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
-// The merge-free types subpath: pulling the session package's root into this
-// client-registered program would merge the host `sessions` service over the
-// browser runtime's own.
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { API_PATH } from './api-path.ts'
 import { bridge } from './http-bridge.ts'
-import { injectFilesPort, listenForWorkspaceFiles } from './files-server.ts'
 import { assertTrustedAuthority, isTrustedApiRequest } from './api-request-trust.ts'
 
 export { API_PATH } from './api-path.ts'
@@ -66,17 +61,15 @@ const PRIVILEGED_METHODS = new Set([
 ])
 
 /**
- * Mounts the API gateway and the workspace-file reads under the browser
- * transport prefixes. Every request on either prefix passes the browser-trust
- * fence first (DNS-rebinding and cross-site defense —
- * [api-request-trust](./api-request-trust.ts)); privileged methods
- * additionally pass it with an empty trust list, which pins them to loopback.
+ * Mounts the API gateway under the browser transport prefix. Every request on
+ * the prefix passes the browser-trust fence first (DNS-rebinding and
+ * cross-site defense — [api-request-trust](./api-request-trust.ts));
+ * privileged methods additionally pass it with an empty trust list, which
+ * pins them to loopback.
  * @param ctx - Host plugin context.
  * @param config - resolved plugin config (schema defaults applied).
- * @returns a promise settling once the workspace-file listener is bound and
- * its port published — the page must never render before it can address one.
  */
-export async function apply(ctx: Context, config?: ConnectionConfig): Promise<void> {
+export function apply(ctx: Context, config?: ConnectionConfig): void {
   // The Loader resolves schema defaults; hand-built test contexts may pass none.
   const trustedHosts = config?.trustedHosts ?? []
   // Config boundary: a malformed entry fails the load loudly here rather than
@@ -104,24 +97,4 @@ export async function apply(ctx: Context, config?: ConnectionConfig): Promise<vo
   }
   ctx.effect(() => ctx.httpServer.register(route), 'client-connection: /api route')
 
-  // The gateway is the host's session authority: it answers where a Session's
-  // files live without this package reaching into the core services, which
-  // would merge their host-side Context declarations into the browser lane.
-  const cwdFor = (sessionId: string): Promise<string | undefined> =>
-    ctx.apiProxy.workspaceRootOf(sessionId as SessionId)
-  // Workspace files get their own port, and therefore their own origin: an
-  // active document served beside `/api` would reach every method through the
-  // fence below. The listen is awaited inside the effect so the port is known
-  // before the index tap that publishes it can run.
-  await ctx.effect(async () => {
-    const files = await listenForWorkspaceFiles(
-      ctx.httpServer.host, trustedHosts, { cwdFor },
-      (error) => { ctx.logger.error(error) },
-    )
-    const untap = ctx.httpServer.tapIndex(html => injectFilesPort(html, files.port))
-    return async () => {
-      untap()
-      await files.close()
-    }
-  }, 'client-connection: /f listener')
 }
diff --git a/packages/client/connection/src/workspace-files.ts b/packages/client/connection/src/workspace-files.ts
deleted file mode 100644
index c934b14516..0000000000
--- a/packages/client/connection/src/workspace-files.ts
+++ /dev/null
@@ -1,164 +0,0 @@
-/**
- * The read half of the web transport: streams one file out of a session's
- * workspace so the browser can open what the agent just produced. The RPC
- * gateway carries structured session state; this route carries bytes, which a
- * JSON-RPC envelope cannot stream and a `file://` link cannot reach from an
- * http page.
- *
- * Confinement is the whole contract: a request names a session, the session
- * names its cwd, and nothing outside that realpath is ever served. The caller
- * owns the browser-trust fence ([api-request-trust](./api-request-trust.ts)) —
- * this module is reached only by requests that already passed it.
- *
- * Isolation is the listener's, not this module's: these responses carry no
- * sandbox header because they are served from their own port, and therefore
- * their own origin ([files-server](./files-server.ts)). A served document
- * keeps `localStorage`, cookies, and its own `fetch`, while the API stays
- * cross-origin to it.
- */
-
-import { createReadStream } from 'node:fs'
-import { realpath, stat } from 'node:fs/promises'
-import type { IncomingMessage, ServerResponse } from 'node:http'
-import { extname, resolve, sep } from 'node:path'
-import { pipeline } from 'node:stream/promises'
-import { parseWorkspaceFilePath } from '@deepseek-ai/dsh-host-apiproxy/api'
-
-/**
- * Content types served verbatim. Everything absent is `text/plain`, not
- * `application/octet-stream`: a workspace read is a "show me what you made"
- * gesture, and an unknown extension is far more often a source file to read
- * than a binary to download. `nosniff` keeps that choice binding, so a
- * mislabelled document can never be re-interpreted as HTML.
- */
-const MIME: Record<string, string> = {
-  '.html': 'text/html; charset=utf-8',
-  '.htm': 'text/html; charset=utf-8',
-  '.xhtml': 'application/xhtml+xml',
-  '.svg': 'image/svg+xml',
-  '.css': 'text/css; charset=utf-8',
-  '.js': 'text/javascript; charset=utf-8',
-  '.mjs': 'text/javascript; charset=utf-8',
-  '.json': 'application/json',
-  '.pdf': 'application/pdf',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.avif': 'image/avif',
-  '.ico': 'image/x-icon',
-  '.mp4': 'video/mp4',
-  '.webm': 'video/webm',
-  '.mp3': 'audio/mpeg',
-  '.wav': 'audio/wav',
-  '.wasm': 'application/wasm',
-}
-
-const DEFAULT_MIME = 'text/plain; charset=utf-8'
-
-/** How the route learns which directory a session may serve from. */
-export interface WorkspaceFileDeps {
-  /**
-   * The session's absolute working directory.
-   * @param sessionId - the session named by the request path.
-   * @returns its cwd, or `undefined` when the id names no session this host serves.
-   */
-  cwdFor: (sessionId: string) => Promise<string | undefined>
-}
-
-function fail(res: ServerResponse, status: number): void {
-  res.writeHead(status)
-  res.end()
-}
-
-/**
- * Resolve one request's segments against a session cwd, refusing anything that
- * leaves it. Both sides go through `realpath`, so a symlink inside the
- * workspace pointing out of it is refused by its resolved target rather than
- * its name. A component swapped between this resolution and the open below
- * would still be followed; closing that window needs privileges that already
- * imply workspace write access, which is strictly stronger than reading a
- * workspace file, so the check stops here.
- */
-async function confine(cwd: string, segments: readonly string[]): Promise<string | undefined> {
-  const root = await realpath(cwd)
-  // A filesystem root already ends in the separator; appending a second one
-  // would make every child fail the prefix test and 403 the whole workspace.
-  const prefix = root.endsWith(sep) ? root : root + sep
-  const real = await realpath(resolve(root, ...segments))
-  return real.startsWith(prefix) ? real : undefined
-}
-
-/**
- * Serve one workspace-file request. The caller has already applied the
- * browser-trust fence and rejected non-read methods.
- * @param req - the request, read for its url and method only (no body).
- * @param res - the response this function owns to completion.
- * @param deps - the session-to-cwd lookup this host answers with.
- */
-export async function handleWorkspaceFile(
-  req: IncomingMessage,
-  res: ServerResponse,
-  deps: WorkspaceFileDeps,
-): Promise<void> {
-  /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server requests. */
-  const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
-  const target = parseWorkspaceFilePath(pathname)
-  if (target === undefined) {
-    fail(res, 404)
-    return
-  }
-  const cwd = await deps.cwdFor(target.sessionId)
-  if (cwd === undefined) {
-    fail(res, 404)
-    return
-  }
-
-  let file: string | undefined
-  let size: number
-  try {
-    file = await confine(cwd, target.segments)
-    if (file === undefined) {
-      fail(res, 403)
-      return
-    }
-    const info = await stat(file)
-    // A directory read has no answer here: the route serves files, and listing
-    // is the directory-picker capability's job, behind its own fence.
-    if (!info.isFile()) {
-      fail(res, 404)
-      return
-    }
-    size = info.size
-  } catch {
-    // Missing, unreadable, or a path whose ancestor is not a directory: all
-    // report as absent, so a probe cannot distinguish them.
-    fail(res, 404)
-    return
-  }
-
-  const ext = extname(file).toLowerCase()
-  res.writeHead(200, {
-    'content-type': MIME[ext] ?? DEFAULT_MIME,
-    'content-length': String(size),
-    'content-disposition': 'inline',
-    'x-content-type-options': 'nosniff',
-    // Workspace files change under the agent's hands; a cached preview would
-    // show the previous turn's output after the next edit.
-    'cache-control': 'no-store',
-  })
-  if (req.method === 'HEAD') {
-    res.end()
-    return
-  }
-  try {
-    // pipeline (not pipe) so a client disconnect destroys the read stream:
-    // an abandoned preview must not leave a descriptor open.
-    await pipeline(createReadStream(file), res)
-  } catch {
-    // The status line is already out, so a mid-stream read failure or client
-    // disconnect can only end the response abruptly.
-    res.destroy()
-  }
-}
diff --git a/packages/client/connection/tests/client-apply.spec.ts b/packages/client/connection/tests/client-apply.spec.ts
index 4b323182bb..f9fe1c1b71 100644
--- a/packages/client/connection/tests/client-apply.spec.ts
+++ b/packages/client/connection/tests/client-apply.spec.ts
@@ -8,11 +8,10 @@ import { apply, type ConnectionHandle } from '../src/client/index.ts'
 import { FixtureApiClient } from '../src/client/fixture.ts'
 import { WebApiClient } from '../src/client/web-api-client.ts'
 
-type Win = { location?: { search: string; protocol?: string; hostname?: string }; __DSH_FILES_PORT__?: number }
+type Win = { location?: { search: string } }
 
 afterEach(() => {
   delete (globalThis as Win).location
-  delete (globalThis as Win).__DSH_FILES_PORT__
 })
 
 async function mount(): Promise<ConnectionHandle> {
@@ -64,27 +63,4 @@ describe('connection client apply', () => {
     expect(seen.some(u => u.includes('/api/'))).toBe(true)
   })
 
-  it('addresses a workspace file on the port the host published, and only inside the workspace', async () => {
-    const win = globalThis as Win
-    win.location = { search: '', protocol: 'http:', hostname: '192.168.1.5' }
-    win.__DSH_FILES_PORT__ = 4321
-    const handle = await mount()
-    const session = 's-1' as never
-    // Same hostname the page was reached by — a LAN client must reach previews
-    // too — and the published port, which is what makes it another origin.
-    expect(handle.fileUrl(session, '/w/alpha', '/w/alpha/out/a b.html'))
-      .toBe('http://192.168.1.5:4321/f/s-1/out/a%20b.html')
-    // Outside the workspace there is nothing this transport may serve, which
-    // is the signal a caller falls back to openPath on.
-    expect(handle.fileUrl(session, '/w/alpha', '/etc/hosts')).toBeUndefined()
-  })
-
-  it('serves no file URL on a page no host published a port into', async () => {
-    const win = globalThis as Win
-    win.location = { search: '?fixture', protocol: 'http:', hostname: '127.0.0.1' }
-    const handle = await mount()
-    // The keyless fixture lane: no workspace-file origin exists, so the row
-    // falls back to the Host opener instead of opening a dead tab.
-    expect(handle.fileUrl('s-1' as never, '/w', 'a.txt')).toBeUndefined()
-  })
 })
diff --git a/packages/client/connection/tests/files-server.spec.ts b/packages/client/connection/tests/files-server.spec.ts
deleted file mode 100644
index 4a2618709b..0000000000
--- a/packages/client/connection/tests/files-server.spec.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-/** The workspace-file listener's own failure and publication paths. */
-import { describe, expect, it } from 'vitest'
-import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
-import { injectFilesPort, listenForWorkspaceFiles } from '../src/files-server.ts'
-
-describe('workspace-file listener', () => {
-  it('answers 400 and reports the failure when the directory lookup throws', async () => {
-    const seen: Error[] = []
-    const files = await listenForWorkspaceFiles(
-      '127.0.0.1', [],
-      { cwdFor: () => Promise.reject(new Error('store unavailable')) },
-      (error) => { seen.push(error) },
-    )
-    try {
-      // A lookup failure is the host's problem, not a miss: it must not become
-      // an unhandled rejection, and it must not be reported as "not found".
-      const response = await fetch(`http://127.0.0.1:${String(files.port)}${FILES_PATH}/s-1/a.txt`)
-      expect(response.status).toBe(400)
-      expect(seen.map(error => error.message)).toEqual(['store unavailable'])
-    } finally {
-      await files.close()
-    }
-  })
-
-  it('closes idempotently and stops answering', async () => {
-    const files = await listenForWorkspaceFiles(
-      '127.0.0.1', [], { cwdFor: async () => undefined }, () => {},
-    )
-    const origin = `http://127.0.0.1:${String(files.port)}`
-    expect((await fetch(`${origin}${FILES_PATH}/s-1/a.txt`)).status).toBe(404)
-    await files.close()
-    await files.close()
-    await expect(fetch(`${origin}${FILES_PATH}/s-1/a.txt`)).rejects.toThrow()
-  })
-})
-
-describe('injectFilesPort', () => {
-  it('publishes the port as the first script in head', () => {
-    const html = injectFilesPort('<html><head><title>x</title></head></html>', 4321)
-    expect(html).toContain('<head><script>window.__DSH_FILES_PORT__ = 4321</script>')
-    // Ahead of anything the shell might read it from.
-    expect(html.indexOf('__DSH_FILES_PORT__')).toBeLessThan(html.indexOf('<title>'))
-  })
-})
diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts
index 2561a0846f..216484ad67 100644
--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -1,9 +1,6 @@
-/** Node half: registers the /api and /f prefix routes over the api gateway and the session workspaces. */
+/** Node half: registers the /api prefix route bridging to the api gateway. */
 import { EventEmitter } from 'node:events'
 import { createServer, request as httpRequest } from 'node:http'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
 import { Readable } from 'node:stream'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
@@ -11,25 +8,17 @@ import type { AddressInfo } from 'node:net'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { HttpServerService, WebRoute } from '@deepseek-ai/dsh-host-webserver'
-import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { API_PATH, apply, inject } from '../src/index.ts'
 
 /** Structural httpServer fake: the plugin only touches register(). */
-function fakeHttpServer(
-  routes: WebRoute[],
-  taps: ((html: string) => string)[] = [],
-): Pick<HttpServerService, 'register' | 'tapIndex' | 'port' | 'host'> {
+function fakeHttpServer(routes: WebRoute[]): Pick<HttpServerService, 'register' | 'tapIndex' | 'port'> {
   return {
     register(route) {
       routes.push(route)
       return () => { routes.splice(routes.indexOf(route), 1) }
     },
-    tapIndex(transform) {
-      taps.push(transform)
-      return () => { taps.splice(taps.indexOf(transform), 1) }
-    },
+    tapIndex: () => () => {},
     port: 0,
-    host: '127.0.0.1',
   }
 }
 
@@ -60,47 +49,14 @@ function fakeResponse(): { response: ServerResponse; state: { status?: number; b
   return { response, state }
 }
 
-/** The gateway stub: only the session-directory authority the /f route reads. */
-function fakeApiProxy(workspaces: Record<string, string> = {}): ApiProxy {
-  return { workspaceRootOf: async (id: string) => workspaces[id] } as unknown as ApiProxy
-}
-
-async function mounted(
-  config?: { trustedHosts?: string[] },
-  workspaces: Record<string, string> = {},
-): Promise<{ routes: WebRoute[]; taps: ((html: string) => string)[]; dispose: () => Promise<void> }> {
+async function mounted(config?: { trustedHosts?: string[] }): Promise<{ routes: WebRoute[]; dispose: () => Promise<void> }> {
   const ctx = new Context()
   const routes: WebRoute[] = []
-  const taps: ((html: string) => string)[] = []
-  ctx.provide('httpServer', fakeHttpServer(routes, taps) as HttpServerService)
-  ctx.provide('apiProxy', fakeApiProxy(workspaces))
+  ctx.provide('httpServer', fakeHttpServer(routes) as HttpServerService)
+  ctx.provide('apiProxy', {} as unknown as ApiProxy)
   const fiber = ctx.plugin({ inject: [...inject], apply }, config)
   await fiber.await()
-  return { routes, taps, dispose: () => fiber.dispose() }
-}
-
-/** One raw GET whose Host header is spoofed (fetch forbids setting it). */
-function statusWithHost(origin: string, path: string, host: string): Promise<number> {
-  const url = new URL(origin)
-  return new Promise((resolve, reject) => {
-    const request = httpRequest(
-      { host: url.hostname, port: url.port, path, method: 'GET', headers: { host } },
-      (response) => {
-        response.resume()
-        response.on('end', () => { resolve(response.statusCode ?? 0) })
-      },
-    )
-    request.on('error', reject)
-    request.end()
-  })
-}
-
-/** The workspace-file origin the node half published into the index page. */
-function filesOrigin(taps: ((html: string) => string)[]): string {
-  const html = taps.reduce((acc, tap) => tap(acc), '<head></head>')
-  const port = /__DSH_FILES_PORT__ = (\d+)/.exec(html)?.[1]
-  if (port === undefined) throw new Error(`no workspace-file port was published: ${html}`)
-  return `http://127.0.0.1:${port}`
+  return { routes, dispose: () => fiber.dispose() }
 }
 
 describe('connection node half', () => {
@@ -108,25 +64,17 @@ describe('connection node half', () => {
     const routes: WebRoute[] = []
     const ctx = new Context()
     ctx.provide('httpServer', fakeHttpServer(routes) as HttpServerService)
-    ctx.provide('apiProxy', fakeApiProxy())
+    ctx.provide('apiProxy', {} as unknown as ApiProxy)
     const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.internal/path'] })
     await expect(fiber).rejects.toThrow(/not a bare host\[:port\] authority/)
     expect(routes).toHaveLength(0)
   })
 
-  it('registers the /api route and publishes a separate workspace-file origin, both removed with the fiber', async () => {
-    const { routes, taps, dispose } = await mounted()
-    // The API keeps one prefix on the shared server; workspace files get a
-    // port of their own, which is the origin boundary between them.
+  it('registers the /api prefix route and removes it with the fiber', async () => {
+    const { routes, dispose } = await mounted()
     expect(routes).toMatchObject([{ kind: 'prefix', path: API_PATH }])
-    const origin = filesOrigin(taps)
-    expect(new URL(origin).port).not.toBe('')
-    expect((await fetch(`${origin}${FILES_PATH}/absent/x.txt`)).status).toBe(404)
     await dispose()
     expect(routes).toHaveLength(0)
-    expect(taps).toHaveLength(0)
-    // Disposal reaches quiescence: the socket is gone, not merely unrouted.
-    await expect(fetch(`${origin}${FILES_PATH}/absent/x.txt`)).rejects.toThrow()
   })
 
   it('refuses an untrusted Host on any /api path before the bridge runs', async () => {
@@ -187,48 +135,6 @@ describe('connection node half', () => {
   })
 })
 
-describe('connection node half: the workspace-file origin', () => {
-  /** A workspace holding one file, torn down with the returned disposer. */
-  async function workspace(): Promise<{ cwd: string; remove: () => Promise<void> }> {
-    const cwd = await mkdtemp(join(tmpdir(), 'dsh-node-half-'))
-    await writeFile(join(cwd, 'index.html'), '<h1>ok</h1>')
-    return { cwd, remove: () => rm(cwd, { recursive: true, force: true }) }
-  }
-
-  it('applies the same browser-trust fence as /api, refuses writes, and serves nothing else', async () => {
-    const { taps, dispose } = await mounted()
-    const origin = filesOrigin(taps)
-    // Rebound Host: refused before any filesystem work, exactly as on /api.
-    // node's fetch refuses to set Host (a forbidden header), so the spoof goes
-    // through the raw client — the same parse the server really performs.
-    expect(await statusWithHost(origin, `${FILES_PATH}/s-1/index.html`, 'harness.example')).toBe(403)
-    const written = await fetch(`${origin}${FILES_PATH}/s-1/index.html`, { method: 'POST' })
-    expect(written.status).toBe(405)
-    expect(written.headers.get('allow')).toBe('GET, HEAD')
-    // This origin is one route wide: no index, no SPA fallback, no API.
-    expect((await fetch(`${origin}/`)).status).toBe(404)
-    expect((await fetch(`${origin}${API_PATH}/session.list`, { method: 'POST' })).status).toBe(404)
-    await dispose()
-  })
-
-  it('confines reads to the directory the gateway names for that session', async () => {
-    const { cwd, remove } = await workspace()
-    const { taps, dispose } = await mounted(undefined, { 's-1': cwd })
-    const origin = filesOrigin(taps)
-    const served = await fetch(`${origin}${FILES_PATH}/s-1/index.html`)
-    expect(served.status).toBe(200)
-    expect(await served.text()).toBe('<h1>ok</h1>')
-    // A served document keeps its own capabilities: the port is the boundary,
-    // so nothing here strips the document of its origin.
-    expect(served.headers.get('content-security-policy')).toBeNull()
-    // A session the gateway names no directory for has no workspace to confine
-    // against, so there is nothing to serve.
-    expect((await fetch(`${origin}${FILES_PATH}/s-absent/index.html`)).status).toBe(404)
-    await dispose()
-    await remove()
-  })
-})
-
 describe('connection node half over a real HTTP server', () => {
   /** Serve the registered prefix route from a real server and return its port. */
   async function serve(routes: WebRoute[]): Promise<{ port: number; close: () => Promise<void> }> {
diff --git a/packages/client/connection/tests/workspace-files.spec.ts b/packages/client/connection/tests/workspace-files.spec.ts
deleted file mode 100644
index 8e33a6751b..0000000000
--- a/packages/client/connection/tests/workspace-files.spec.ts
+++ /dev/null
@@ -1,142 +0,0 @@
-/**
- * Workspace-file reads over a real HTTP server and a real temporary
- * workspace: confinement, content typing, and the sandbox header are wire
- * facts, so they are asserted against responses Node actually produced.
- */
-import { createServer } from 'node:http'
-import type { AddressInfo } from 'node:net'
-import type { ServerResponse } from 'node:http'
-import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join, sep } from 'node:path'
-import { Writable } from 'node:stream'
-import { afterAll, beforeAll, describe, expect, it } from 'vitest'
-import { FILES_PATH } from '@deepseek-ai/dsh-host-apiproxy/api'
-import { handleWorkspaceFile } from '../src/workspace-files.ts'
-
-const SESSION = 's-1'
-
-let workspace: string
-let outside: string
-let origin: string
-let close: () => Promise<void>
-
-beforeAll(async () => {
-  const root = await mkdtemp(join(tmpdir(), 'dsh-files-'))
-  workspace = join(root, 'workspace')
-  outside = join(root, 'outside')
-  await mkdir(join(workspace, 'out'), { recursive: true })
-  await mkdir(outside, { recursive: true })
-  await writeFile(join(workspace, 'index.html'), '<h1>产物</h1>')
-  await writeFile(join(workspace, 'notes.txt'), 'plain')
-  await writeFile(join(workspace, 'chart.svg'), '<svg xmlns="http://www.w3.org/2000/svg"/>')
-  await writeFile(join(workspace, 'model.safetensors'), 'unknown extension')
-  await writeFile(join(workspace, 'out', 'page.html'), '<p>nested</p>')
-  await writeFile(join(outside, 'secret.html'), 'SECRET')
-  await symlink(join(outside, 'secret.html'), join(workspace, 'escape.html'))
-
-  const server = createServer((req, res) => {
-    void handleWorkspaceFile(req, res, {
-      // 'rooted' names the filesystem root, the separator-terminated realpath case.
-      cwdFor: async sessionId => sessionId === SESSION ? workspace : sessionId === 'rooted' ? sep : undefined,
-    })
-  })
-  await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
-  origin = `http://127.0.0.1:${String((server.address() as AddressInfo).port)}`
-  close = () => new Promise<void>((resolve, reject) => {
-    server.close((error) => {
-      if (error === undefined || error === null) resolve()
-      else reject(error)
-    })
-  })
-  return async () => { await rm(root, { recursive: true, force: true }) }
-})
-
-afterAll(async () => { await close() })
-
-function get(path: string, init?: RequestInit): Promise<Response> {
-  return fetch(`${origin}${path}`, init)
-}
-
-describe('workspace file reads', () => {
-  it('serves a produced document with its own capabilities intact', async () => {
-    const response = await get(`${FILES_PATH}/${SESSION}/index.html`)
-    expect(response.status).toBe(200)
-    expect(await response.text()).toBe('<h1>产物</h1>')
-    expect(response.headers.get('content-type')).toBe('text/html; charset=utf-8')
-    // No isolation header: the listener's own port is the origin boundary, so
-    // a preview keeps localStorage and cookies (see files-server).
-    expect(response.headers.get('content-security-policy')).toBeNull()
-    expect(response.headers.get('x-content-type-options')).toBe('nosniff')
-    expect(response.headers.get('cache-control')).toBe('no-store')
-    expect(response.headers.get('content-disposition')).toBe('inline')
-  })
-
-  it('types SVG as a standalone document rather than sniffable bytes', async () => {
-    const svg = await get(`${FILES_PATH}/${SESSION}/chart.svg`)
-    expect(svg.headers.get('content-type')).toBe('image/svg+xml')
-    expect(svg.headers.get('x-content-type-options')).toBe('nosniff')
-    const text = await get(`${FILES_PATH}/${SESSION}/notes.txt`)
-    expect(text.headers.get('content-type')).toBe('text/plain; charset=utf-8')
-  })
-
-  it('serves a workspace rooted at a filesystem root, whose realpath already ends in a separator', async () => {
-    // `realpath('/')` is '/', so a naive `root + sep` prefix is '//' and every
-    // child of that workspace would 403.
-    const rooted = await fetch(`${origin}${FILES_PATH}/rooted${new URL(`file://${workspace}/notes.txt`).pathname}`)
-    expect(rooted.status).toBe(200)
-    expect(await rooted.text()).toBe('plain')
-  })
-
-  it('shows an unknown extension as text rather than downloading it', async () => {
-    const response = await get(`${FILES_PATH}/${SESSION}/model.safetensors`)
-    expect(response.status).toBe(200)
-    expect(response.headers.get('content-type')).toBe('text/plain; charset=utf-8')
-  })
-
-  it('serves a nested path, so a document reaches its own siblings', async () => {
-    const response = await get(`${FILES_PATH}/${SESSION}/out/page.html`)
-    expect(response.status).toBe(200)
-    expect(await response.text()).toBe('<p>nested</p>')
-  })
-
-  it('answers HEAD with the length and no body', async () => {
-    const response = await get(`${FILES_PATH}/${SESSION}/notes.txt`, { method: 'HEAD' })
-    expect(response.status).toBe(200)
-    expect(response.headers.get('content-length')).toBe('5')
-    expect(await response.text()).toBe('')
-  })
-
-  it('refuses a symlink whose target leaves the workspace', async () => {
-    const response = await get(`${FILES_PATH}/${SESSION}/escape.html`)
-    expect(response.status).toBe(403)
-    expect(await response.text()).not.toContain('SECRET')
-  })
-
-  it('reports missing files, directories, and unknown sessions as absent', async () => {
-    expect((await get(`${FILES_PATH}/${SESSION}/nope.html`)).status).toBe(404)
-    expect((await get(`${FILES_PATH}/${SESSION}/out`)).status).toBe(404)
-    // A path whose ancestor is a file, not a directory.
-    expect((await get(`${FILES_PATH}/${SESSION}/notes.txt/child`)).status).toBe(404)
-    expect((await get(`${FILES_PATH}/s-other/index.html`)).status).toBe(404)
-    expect((await get(`${FILES_PATH}/${SESSION}`)).status).toBe(404)
-  })
-})
-
-describe('workspace file streaming failures', () => {
-  it('tears the response down instead of rejecting when the body cannot be written', async () => {
-    // A client that goes away mid-stream must not surface as a handler
-    // rejection: the webserver's last-resort guard would log it and try to
-    // answer 400 on a response whose status line is already out.
-    const sink = new Writable({
-      write(_chunk, _encoding, callback) { callback(new Error('socket gone')) },
-    })
-    const response = Object.assign(sink, { writeHead: () => response }) as unknown as ServerResponse
-    await expect(handleWorkspaceFile(
-      { url: `${FILES_PATH}/${SESSION}/index.html`, method: 'GET', headers: {} } as never,
-      response,
-      { cwdFor: async () => workspace },
-    )).resolves.toBeUndefined()
-    expect(sink.destroyed).toBe(true)
-  })
-})
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index a5827173a8..d389efe319 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -26,7 +26,6 @@ async function mount(): Promise<Bench> {
   const bench: Bench = { ctx, api, sinks: undefined, stopped: 0 }
   const handle: ConnectionHandle = {
     api,
-    fileUrl: () => undefined,
     start: (sinks) => {
       bench.sinks = sinks
       return { stop: () => { bench.stopped += 1 } }
diff --git a/packages/client/runtime/tests/wire-events.spec.ts b/packages/client/runtime/tests/wire-events.spec.ts
index a35983d890..fd7858d60c 100644
--- a/packages/client/runtime/tests/wire-events.spec.ts
+++ b/packages/client/runtime/tests/wire-events.spec.ts
@@ -20,7 +20,6 @@ async function mount(): Promise<Bench> {
   const bench: Bench = { ctx, sinks: undefined }
   const handle: ConnectionHandle = {
     api,
-    fileUrl: () => undefined,
     start: (sinks) => {
       bench.sinks = sinks
       return { stop: () => {} }
diff --git a/packages/client/test-runtime/package.json b/packages/client/test-runtime/package.json
index 6d7093a148..e892d9cd52 100644
--- a/packages/client/test-runtime/package.json
+++ b/packages/client/test-runtime/package.json
@@ -25,7 +25,6 @@
     "vitest": "^4.1.8"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-client-connection": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
     "@deepseek-ai/dsh-client-web-react": "^0.0.1",
@@ -36,7 +35,6 @@
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-client-web-react": "workspace:^",
diff --git a/packages/client/test-runtime/src/connection.ts b/packages/client/test-runtime/src/connection.ts
deleted file mode 100644
index 5df5d5a053..0000000000
--- a/packages/client/test-runtime/src/connection.ts
+++ /dev/null
@@ -1,48 +0,0 @@
-/** Test-owned connection face: the transport members features read off `ctx.connection`. */
-import { workspaceFileSegments, workspaceFileUrl } from '@deepseek-ai/dsh-host-apiproxy/api'
-import type { ConnectionHandle, IApiClient, SessionId } from '@deepseek-ai/dsh-client-connection/client'
-
-/**
- * Connection test double. Implements the same `ConnectionHandle` face features
- * receive as `ctx.connection`, so a production face change breaks this double
- * at compile time. The wire client is not modelled — a feature that needs one
- * composes its own connection over a fake api client; this double exists for
- * the transport facts features read synchronously, above all the
- * workspace-file URL.
- */
-export class TestConnection implements ConnectionHandle {
-  /**
-   * The workspace-file port the host would have published into the page.
-   * Unset — the default, and the keyless fixture lane's real state — makes
-   * {@link TestConnection.fileUrl} answer `undefined`, which is the signal a
-   * caller falls back to the Host opener on.
-   */
-  filesPort: number | undefined
-
-  /** The wire client; unused by this double's consumers and absent by construction. */
-  readonly api: IApiClient = undefined as unknown as IApiClient
-
-  /**
-   * Stream-loop starter (inert).
-   * @returns a stop handle that does nothing.
-   */
-  start(): { stop(): void } {
-    return { stop: () => {} }
-  }
-
-  /**
-   * Workspace-file URL, deriving exactly as production does so a feature test
-   * sees the real inside/outside-workspace split.
-   * @param sessionId - the Session whose cwd anchors the path.
-   * @param cwd - that Session's working directory.
-   * @param path - the path a tool reported.
-   * @returns the absolute URL on the workspace-file origin, or undefined when
-   * the path leaves the workspace or no port is published.
-   */
-  fileUrl(sessionId: SessionId, cwd: string | undefined, path: string): string | undefined {
-    if (this.filesPort === undefined) return undefined
-    const segments = workspaceFileSegments(cwd, path)
-    if (segments === undefined) return undefined
-    return `http://localhost:${String(this.filesPort)}${workspaceFileUrl(sessionId, segments)}`
-  }
-}
diff --git a/packages/client/test-runtime/src/index.ts b/packages/client/test-runtime/src/index.ts
index cdbdca75a2..5ef5350434 100644
--- a/packages/client/test-runtime/src/index.ts
+++ b/packages/client/test-runtime/src/index.ts
@@ -29,13 +29,11 @@ import type {
 } from '@deepseek-ai/dsh-client-ui-slots'
 import { registerDomSnapshotSerializer } from './snapshot.ts'
 import { TestSessions } from './sessions.ts'
-import { TestConnection } from './connection.ts'
 import { TestWorkspaces } from './workspaces.ts'
 import type { Stabilizer } from './fixtures.ts'
 
 export { domSnapshotSerializer, registerDomSnapshotSerializer } from './snapshot.ts'
 export { FixtureSession, TestSessions } from './sessions.ts'
-export { TestConnection } from './connection.ts'
 export { TestWorkspaces } from './workspaces.ts'
 export { conversationSnapshot, workspaceListState } from './fixtures.ts'
 export type { SessionBehaviorOverrides, SessionFixture, Stabilizer } from './fixtures.ts'
@@ -177,8 +175,6 @@ export class SlotTestRuntime {
   readonly sessions: TestSessions
   /** Workspaces double (list observable, recorded intent actions). */
   readonly workspaces: TestWorkspaces
-  /** The transport double features read as `ctx.connection`. */
-  readonly connection: TestConnection
 
   private readonly stabilizer: Stabilizer = async (fn) => {
     await act(async () => { await fn() })
@@ -199,10 +195,8 @@ export class SlotTestRuntime {
     this.root = new TestRoot(slots, this.stabilizer)
     this.sessions = new TestSessions(this.stabilizer, ctx)
     this.workspaces = new TestWorkspaces(this.stabilizer)
-    this.connection = new TestConnection()
     ctx.provide('sessions', this.sessions)
     ctx.provide('workspaces', this.workspaces)
-    ctx.provide('connection', this.connection)
     // Capturing install: the production renderer does the rendering; the
     // wrapper only takes the host face for storeOf (no machinery copied).
     const renderer = createSlotRenderer()
diff --git a/packages/client/test-runtime/tsconfig.json b/packages/client/test-runtime/tsconfig.json
index 681bff474c..6a758c66f9 100644
--- a/packages/client/test-runtime/tsconfig.json
+++ b/packages/client/test-runtime/tsconfig.json
@@ -17,9 +17,6 @@
     {
       "path": "../web-react"
     },
-    {
-      "path": "../connection"
-    },
     {
       "path": "../runtime"
     },
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 446c2084b1..e85aa2ca30 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 8c2075d615eccad1bbc7f5de1255ea4add69fab8
-README.zh.md: 634721b4248da75cbd4e81528340936a31ece28d
+README.md: a9d4aadf4b0acc21f3909319724645c10f08bd31
+README.zh.md: 16be57c9ed8f8101a61eb704ba5e94491803d9b5
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 8c2075d615..a9d4aadf4b 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -14,7 +14,7 @@ Approvals take over the composer through the chain this package declares: `Appro
 
 Logged non-user messages render as a default-collapsed `上下文注入` disclosure. It shares the Tool calls header geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap, shows inline JSON for both `content` and `source`, and synthesizes no tool state, summary, or keyed toolview dispatch ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)).
 
-Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is a hover-underline link that opens the file: one inside the session workspace opens in a new browser tab on the transport's workspace-file origin (`ConnectionHandle.fileUrl`), so a client that is not on the Host machine still sees it; one outside the workspace has no served URL and falls back to the Host OS default application (`host.openPath`, relative paths resolve against the session cwd). Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
+Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is an underlined link — it reads as one at rest, not only on hover, because a path styled like the surrounding prose is an affordance nobody finds — and it opens the file through the Host (`host.openPath`, relative paths resolve against the session cwd). A document a browser renders opens in the default browser rather than the type's default application, so a produced page is shown rather than edited. The Host opens it on the Host's own machine: a client reached over a network sees nothing, which is the deliberate scope of this surface. Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
 
 A tool call declaring the `terminal` render intent renders its command output inline, at both conversation render sites, through ui-primitives' `TerminalBlock`. `contract/terminal-card-model.ts` is the single derivation from the snapshot's `callView`/`resultView` pair, so the sites cannot disagree about a command, its cwd, or its exit status; it yields null — the generic path — for any other card tag, including one this client version does not know. Both sites therefore also show the card's run-state dot, which is the same `StateDot` semantic a tool row's leading icon carries, so a row and its own card always agree about one command's state. A multi-line command gets one prompt row per line, with the dot marking the call once on the first row — the exit status is the whole call's, so a dot per line would claim a per-line outcome bash does not report. The keyed `BashRow` carries the card resident below its summary row; since tool rows are no longer details-panel click targets, the card's copy and expand controls are the row's only interactions. The render-site fallback row keeps the card behind its existing expand control. Rows cap at `CHAT_TERMINAL_MAX_LINES` (8) against the panel's 16, which is what keeps a summary surface bounded — the panel stays the single-call reading surface. Inline output is licensed per render intent — the terminal and web cards, each with its own bound; a generic tool's content remains panel-only ([decision](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)).
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 634721b424..16be57c9ed 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -12,7 +12,7 @@
 
 已记录的非用户消息渲染为默认折叠的 `上下文注入` 展开项。它通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 标题栏的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，并以内联 JSON 展示 `content` 和 `source`，且不会合成工具状态、摘要或键控 toolview 分发（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)）。
 
-通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是悬停下划线链接，点击即打开文件：位于会话工作区之内的文件在新浏览器标签页打开，位于传输层的工作区文件源上（`ConnectionHandle.fileUrl`），因此不在 Host 机器上的客户端也能看到；工作区之外的文件没有可服务的 URL，回退到宿主操作系统的默认应用（`host.openPath`，相对路径相对会话 cwd 解析）。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
+通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是带下划线的链接——静止状态下就读得出是链接，而不只在悬停时，因为一条与周围正文同样样式的路径是没人会发现的交互——点击即经由 Host 打开文件（`host.openPath`，相对路径相对会话 cwd 解析）。浏览器能渲染的文档会用默认浏览器打开，而不是该类型的默认应用，因此产出的页面是被展示而不是被编辑。Host 在它自己的机器上打开：经网络访问的客户端看不到任何东西，这是本交互面刻意划定的范围。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
 
 声明 `terminal` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `TerminalBlock` 内联渲染其命令输出。`contract/terminal-card-model.ts` 是从快照的 `callView`／`resultView` 对推导的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧；对任何其他 card 标签——包括当前客户端版本不认识的标签——它返回 null，落回通用路径。因此两个渲染点也都显示卡片的运行状态点，它与工具行行首图标承载同一套 `StateDot` 语义，所以一行与其自身的卡片对同一条命令的状态总是一致。多行命令的每一行各占一个提示行，状态点只在第一行为整次调用标记一次——退出状态属于整次调用，因此每行一枚就会声称一个 bash 并不报告的逐行结果。键控的 `BashRow` 把卡片常驻在摘要行下方；由于工具行已不再是详情面板的点击目标，卡片的复制与展开控件就是该行唯一的交互。渲染点兜底行则保持其既有的展开控件。行的上限是 `CHAT_TERMINAL_MAX_LINES`（8），面板为 16，正是这一点让摘要面保持有界——面板仍是单次调用的阅读面。内联输出按渲染意图开放——终端卡片与 web 卡片，各有自己的上限；通用工具的内容仍然只在面板中呈现（[决策](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)）。
 
diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
index 55036600c6..88c09b5550 100644
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -39,7 +39,6 @@
     "clsx": "^2.0.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-client-connection": "^0.0.1",
     "@deepseek-ai/dsh-client-locale": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
@@ -51,7 +50,6 @@
     "react": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index a65ce1d7a4..c67431e409 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -2,7 +2,6 @@
 import type { Context } from 'cordis'
 import { resolveSlotLabel, type BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ISessions, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
@@ -43,7 +42,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 }
 
 /** Services required by the conversation plugin. */
-export const inject = ['slots', 'layout', 'sessions', 'workspaces', 'locale', 'connection']
+export const inject = ['slots', 'layout', 'sessions', 'workspaces', 'locale']
 
 // Static no-session sources for the composer-bar hooks compartment: module
 // constants so the render side's per-source hook cache (observableHook) keeps
@@ -276,16 +275,6 @@ export function apply(ctx: Context): void {
         },
         openFile: (path) => {
           const cwd = sessions.list.getSnapshot().byId[sessionId]?.cwd
-          // A file inside the workspace opens in a new tab on the transport's
-          // workspace-file origin, so a browser that is not on the Host machine
-          // can still see what the agent produced. Anything outside it has no
-          // served URL and falls back to the Host's own opener, which is
-          // loopback-only by the /api trust fence.
-          const url = (ctx.get('connection') as ConnectionHandle).fileUrl(sessionId, cwd, path)
-          if (url !== undefined) {
-            window.open(url, '_blank', 'noopener,noreferrer')
-            return
-          }
           void workspaces.openPath(resolveToolPath(cwd, path)).catch(() => {
             // Host/OS open failures stay silent in the chat row; the native
             // app surfaces its own error dialog when the path is unusable.
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css b/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
index 81e41b066f..3e4fda9ebe 100644
--- a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
+++ b/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
@@ -84,7 +84,10 @@
   color: var(--dsw-alias-label-tertiary);
 }
 
-/* File-tool path: same geometry as .summary; hover underline + pointer. */
+/* File-tool path: same geometry as .summary, but it must READ as a link. A
+   path styled exactly like the surrounding prose, underlined only on hover, is
+   an affordance nobody finds — the reported "I can't open what it made" was
+   this, not a missing capability. */
 .fileLink {
   flex: 1 1 auto;
   min-width: 0;
@@ -99,12 +102,16 @@
   text-align: left;
   font-size: 14px;
   line-height: 24px;
-  color: var(--dsw-alias-label-tertiary);
+  color: var(--dsw-alias-label-secondary);
+  text-decoration: underline;
+  text-decoration-color: var(--dsw-alias-label-quaternary);
+  text-underline-offset: 3px;
   cursor: pointer;
 }
 
 .fileLink:hover {
-  text-decoration: underline;
+  color: var(--dsw-alias-label-primary);
+  text-decoration-color: currentColor;
 }
 
 /* Error row's collapsed summary: the failure's first line in the error color. */
diff --git a/packages/client/ui-conversation/tests/apply-inject.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
index b9dbe0d6ad..cfbb0fdcbe 100644
--- a/packages/client/ui-conversation/tests/apply-inject.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
@@ -218,25 +218,13 @@ describe('conversation slot inject surface', () => {
     await b.runtime.dispose()
   })
 
-  it('openFile (chat view face) opens a workspace file in a tab and falls back to the host opener outside it', async () => {
+  it('openFile (chat view face) resolves against session cwd and calls workspaces.openPath', async () => {
     const b = await bench()
-    // A host that publishes a workspace-file port: previews come from that
-    // origin, which is what keeps them off the API's.
-    b.runtime.connection.filesPort = 4321
-    const open = vi.spyOn(window, 'open').mockReturnValue(null)
     const { injected } = b.chatViewSurface(ROOT)
-    // Inside the session cwd: served on the workspace-file origin, so a browser
-    // anywhere on the network sees the file the agent produced.
     injected.openFile('src/a.ts')
-    expect(open).toHaveBeenCalledWith(`http://localhost:4321/f/${ROOT}/src/a.ts`, '_blank', 'noopener,noreferrer')
-    expect(b.runtime.workspaces.calls.some(c => c.method === 'openPath')).toBe(false)
-    // Outside it there is no served URL, so the Host's own opener answers —
-    // resolved against the session cwd exactly as before.
-    injected.openFile('/etc/hosts')
     await vi.waitFor(() => {
-      expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['/etc/hosts'] })
+      expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['/proj/src/a.ts'] })
     })
-    open.mockRestore()
     await b.runtime.dispose()
   })
 
diff --git a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
index 2763702c0b..bafc6fe709 100644
--- a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
@@ -136,9 +136,6 @@ async function bench(snapshot: ConversationSnapshot) {
     openPath: vi.fn(async () => {}),
   }
   ctx.provide('workspaces', workspaces)
-  // The transport face the chat view reads its workspace-file URLs from.
-  const connection = { fileUrl: vi.fn((_s: unknown, _cwd: string | undefined, path: string) => `http://localhost:4321/f/s-1/${path}`) }
-  ctx.provide('connection', connection)
   ctx.provide('layout', layout)
   const locale = new LocaleService(ctx)
   ctx.provide('locale', locale)
@@ -246,14 +243,12 @@ describe('run_code sub-calls through the real chat machinery', () => {
       subCall(12, parent, 2, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt'),
     ]]])
     const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
-    const open = vi.spyOn(window, 'open').mockReturnValue(null)
     const view = mountApp(b.slots)
     view.getByText('notes/demo.txt').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
     await vi.waitFor(() => {
-      expect(open).toHaveBeenCalledWith('http://localhost:4321/f/s-1/notes/demo.txt', '_blank', 'noopener,noreferrer')
+      expect(b.workspaces.openPath).toHaveBeenCalledWith('notes/demo.txt')
     })
-    open.mockRestore()
     view.getByText('List notes').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
   })
diff --git a/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx b/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
index 84cdd53eeb..eb48677d4f 100644
--- a/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
@@ -119,17 +119,14 @@ describe('keyed toolview hole through the real machinery', () => {
     await b.runtime.dispose()
   })
 
-  it('file-path clicks travel owner openFile → chat inject → the served workspace URL', async () => {
+  it('file-path clicks travel owner openFile → chat inject → workspaces.openPath', async () => {
     const b = await bench([toolResult(3, 'c1', 'read', '{"path":"src/a.ts"}')])
-    b.runtime.connection.filesPort = 4321
-    const open = vi.spyOn(window, 'open').mockReturnValue(null)
     const view = b.runtime.renderRoot()
     view.getByText('src/a.ts').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
     await vi.waitFor(() => {
-      expect(open).toHaveBeenCalledWith(expect.stringContaining('/src/a.ts'), '_blank', 'noopener,noreferrer')
+      expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['src/a.ts'] })
     })
-    open.mockRestore()
     await b.runtime.dispose()
   })
 
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
index 33d45124b4..04b265bdd5 100644
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -20,9 +20,6 @@
     {
       "path": "../web-react"
     },
-    {
-      "path": "../connection"
-    },
     {
       "path": "../runtime"
     },
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index b96bf528a7..27a1434e60 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: ee8e758a68f6efa3e363a36fcc9e8444e589ea40
-README.zh.md: 4ec3817e65543d6e248be9d902d0b74674f56e5a
+README.md: 3c5a83a468b0cf9e596b8b13fafe40c409576fc5
+README.zh.md: f8533564575bf6b716f3fa7241ce47b8d4dd435f
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index ee8e758a68..3c5a83a468 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -36,8 +36,6 @@ The `command.*` and `skill.*` domains expose the host command registry and skill
 
 The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves the namespaces addressed by registered configurable providers (`ctx.llm.listConfigurableProviders()`) plus a small explicit allowlist — the Web preference `permission` and the product-owned `ui-onboarding`; adding a Settings registration alone never makes it remotely readable or writable. Any other namespace answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, and the section's `revision`. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired by `llm/adapters-updated` and by a change to a configurable-provider namespace, whose settings carry that provider's catalog and endpoint; a `permission` or `ui-onboarding` change emits only its settings invalidation. The browser carrier restricts the whole configuration plane, reads included (`settings.describe`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.
 
-Two members of `ApiProxy` are deliberately not wire methods. `respond` is the client-response entry (four-quadrant model), and `workspaceRootOf` answers where a Session's files live for an in-process reader — a live agent's header first, then the persistence store, never a resume. It has no wire face: a browser learns a Session's cwd from `sessions.view`, and reaches a file through the web transport's own `/f` route, never by asking for a host path. That route's URL shape (`api/files.ts`: `FILES_PATH`, `workspaceFileSegments`, `workspaceFileUrl`, `parseWorkspaceFilePath`) lives here with the other browser-importable contract surfaces, so the browser half that builds a `/f` URL and the serving half that parses one cannot drift apart; the route itself belongs to [`dsh-client-connection`](../../client/connection/README.md).
-
 ## Carrier layer (`/client` + root)
 
 `AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh -p` headless.
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index 4ec3817e65..f853356457 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -36,8 +36,6 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 `settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表，以及该分节的 `revision`。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；过期的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取：`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
 
-`ApiProxy` 上有两个成员刻意不是协议方法。`respond` 是客户端响应入口（四象限模型），`workspaceRootOf` 则为进程内读取方回答某个 Session 的文件位于何处——先看活跃 agent 的 header，再看持久化存储，绝不恢复会话。它没有协议面：浏览器从 `sessions.view` 得知 Session 的 cwd，并经由 web 传输自己的 `/f` 路由抵达文件，而不是靠索要一条宿主路径。该路由的 URL 形状（`api/files.ts`：`FILES_PATH`、`workspaceFileSegments`、`workspaceFileUrl`、`parseWorkspaceFilePath`）与其余浏览器可导入的契约面一同放在这里，因此构造 `/f` URL 的浏览器半侧与解析它的服务半侧不会彼此漂移；路由本身则属于 [`dsh-client-connection`](../../client/connection/README.md)。
-
 ## 载体层（`/client` + 根路径）
 
 `AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供 `dsh -p` headless 模式使用。
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 63e1f0007c..4e506ed262 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -2290,20 +2290,5 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       pending.resolve(payload.answer)
       return Promise.resolve({ accepted: true })
     },
-
-    async workspaceRootOf(sessionId: SessionId): Promise<string | undefined> {
-      // A live agent answers from its own header; otherwise the store answers,
-      // deliberately without resuming — reading a session's directory must not
-      // pull an agent up the way the cold RPC path does.
-      const live = ctx.agents.get(sessionId)
-      if (live !== undefined) return live.session.header.cwd
-      const persistence = ctx.get('sessionPersistence')
-      if (persistence === undefined) return undefined
-      // TODO(persistence/by-id): a full listing per lookup. Harmless while the
-      // caller is one preview open, but a served document with N relative
-      // sub-resources pays it N times; a by-id header read on the persistence
-      // seam would retire it.
-      return (await persistence.list()).find(meta => meta.id === sessionId)?.cwd
-    },
   }
 }
diff --git a/packages/host/apiproxy/src/api/files.ts b/packages/host/apiproxy/src/api/files.ts
deleted file mode 100644
index b4ba01f29b..0000000000
--- a/packages/host/apiproxy/src/api/files.ts
+++ /dev/null
@@ -1,98 +0,0 @@
-/**
- * The `/f` workspace-file URL shape: the contract half of the web transport
- * that carries bytes rather than RPC. The browser turns a tool's file path
- * into a URL, the serving side turns that URL back into the segments below a
- * session's cwd, and both read this one encoding decision so neither can drift
- * into serving a path the other never meant. Pure string work with no Node and
- * no DOM, like the rest of `api/` — the browser bundle inlines it.
- * @module @deepseek-ai/dsh-host-apiproxy/api/files
- */
-
-/**
- * Route prefix owning every workspace-file read (`/f/<sessionId>/<segments…>`).
- * The path carries the segments verbatim rather than a query parameter so a
- * served document's relative references (`./logo.png`) resolve to their
- * siblings in the same workspace directory.
- */
-export const FILES_PATH = '/f'
-
-/** One parsed workspace-file request: whose workspace, and where inside it. */
-export interface WorkspaceFileTarget {
-  /** The owning session, still an opaque string — the caller resolves it to a cwd. */
-  sessionId: string
-  /** Decoded path segments below that session's cwd; never empty, never `.` or `..`. */
-  segments: string[]
-}
-
-/** A segment that survived decoding but would re-enter path resolution as more than one name. */
-function isPlainSegment(segment: string): boolean {
-  return segment !== '' && segment !== '.' && segment !== '..'
-    && !segment.includes('/') && !segment.includes('\\') && !segment.includes('\0')
-}
-
-function decode(raw: string): string | undefined {
-  try {
-    return decodeURIComponent(raw)
-  } catch {
-    // A malformed %-escape is a request we cannot interpret, not a miss.
-    return undefined
-  }
-}
-
-/**
- * Express one tool-reported file path as segments below the session cwd.
- * @param cwd - the session's working directory, or `undefined` when unknown.
- * @param path - the path the tool reported (absolute, or relative to `cwd`).
- * @returns the segments below `cwd`, or `undefined` when the path names
- * something outside the workspace (which this route never serves) or resolves
- * to the workspace directory itself.
- */
-export function workspaceFileSegments(cwd: string | undefined, path: string): string[] | undefined {
-  const slashed = path.replace(/\\/g, '/')
-  const absolute = /^\/|^[A-Za-z]:\//.test(slashed)
-  let relative: string
-  if (absolute) {
-    if (cwd === undefined || cwd === '') return undefined
-    const root = cwd.replace(/\\/g, '/').replace(/\/+$/, '')
-    if (!slashed.startsWith(`${root}/`)) return undefined
-    relative = slashed.slice(root.length + 1)
-  } else {
-    relative = slashed
-  }
-  const segments = relative.split('/').filter(segment => segment !== '' && segment !== '.')
-  if (segments.length === 0 || segments.some(segment => !isPlainSegment(segment))) return undefined
-  return segments
-}
-
-/**
- * Build the origin-relative URL serving one workspace file.
- * @param sessionId - the session whose cwd anchors the path.
- * @param segments - segments below that cwd, as {@link workspaceFileSegments} returns them.
- * @returns the `/f/…` URL, resolved by the browser against the serving origin.
- */
-export function workspaceFileUrl(sessionId: string, segments: readonly string[]): string {
-  const encoded = segments.map(segment => encodeURIComponent(segment)).join('/')
-  return `${FILES_PATH}/${encodeURIComponent(sessionId)}/${encoded}`
-}
-
-/**
- * Parse a request pathname back into the session and segments it names.
- * @param pathname - the request's raw (still percent-encoded) pathname.
- * @returns the target, or `undefined` when the pathname is not a well-formed
- * workspace-file read — including every traversal shape, which is refused here
- * before any filesystem call rather than being resolved and then judged.
- */
-export function parseWorkspaceFilePath(pathname: string): WorkspaceFileTarget | undefined {
-  if (!pathname.startsWith(`${FILES_PATH}/`)) return undefined
-  const [rawSession, ...rawSegments] = pathname.slice(FILES_PATH.length + 1).split('/')
-  if (rawSession === undefined || rawSegments.length === 0) return undefined
-  const sessionId = decode(rawSession)
-  if (sessionId === undefined || sessionId === '') return undefined
-  const segments: string[] = []
-  for (const raw of rawSegments) {
-    const segment = decode(raw)
-    if (segment === undefined || !isPlainSegment(segment)) return undefined
-    segments.push(segment)
-  }
-  return { sessionId, segments }
-}
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index 227e26264e..c97cd33e1b 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -15,9 +15,6 @@ import type { SettingsApi } from './settings.ts'
 import type { CredentialsApi } from './credentials.ts'
 import type { LlmApi } from './llm.ts'
 import type { ClientResponse, RpcReceipt } from './rpc.ts'
-// The merge-free types subpath: api/ is imported from the browser lane, where
-// the host session service must not merge over the client runtime's own.
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
 
 /** Root interface of the unified API surface. New client-request domain = one new file pair + one field here + one map row. */
 export interface ApiProxy {
@@ -33,17 +30,6 @@ export interface ApiProxy {
   llm: LlmApi
   /** Response entry for server-requests (client-response, echoing their rpcId); not a domain method (four-quadrant model). */
   respond(message: ClientResponse): Promise<RpcReceipt>
-  /**
-   * The directory a Session's files may be read from — the same `cwd` the
-   * session summaries carry, in non-envelope form for an in-process reader.
-   * Not a domain method: it has no wire face, because a browser learns a
-   * Session's cwd from `sessions.view` and a file it may read from the web
-   * transport's own `/f` route, never by asking for a host path.
-   * @param sessionId - the Session to locate.
-   * @returns its absolute working directory, or `undefined` when this host
-   * serves no such Session. Resolving one never resumes an agent.
-   */
-  workspaceRootOf(sessionId: SessionId): Promise<string | undefined>
 }
 
 // ---- Domain interfaces and payload entities ----
@@ -63,9 +49,6 @@ export type { CredentialsApi, CredentialView } from './credentials.ts'
 export type { ConfigurableProviderView, LlmApi } from './llm.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'
 
-// ---- Workspace-file URL shape (the transport's byte-carrying half) ----
-export { FILES_PATH, workspaceFileSegments, workspaceFileUrl, parseWorkspaceFilePath } from './files.ts'
-export type { WorkspaceFileTarget } from './files.ts'
 export type { QuestionResponsePayload } from './questions.ts'
 
 // ---- Message layer: narrow forms (domain-signature view) ----
diff --git a/packages/host/apiproxy/src/index.ts b/packages/host/apiproxy/src/index.ts
index f6dec19420..339b1e777d 100644
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -64,7 +64,6 @@ export class ApiProxyService extends Service implements ApiProxy {
   readonly llm: ApiProxy['llm']
   readonly events: ApiProxy['events']
   readonly respond: ApiProxy['respond']
-  readonly workspaceRootOf: ApiProxy['workspaceRootOf']
 
   constructor(ctx: Context, config: Config) {
     super(ctx, 'apiProxy')
@@ -88,7 +87,6 @@ export class ApiProxyService extends Service implements ApiProxy {
     // createApiProxy returns closures (no `this` capture); bind only satisfies
     // the unbound-method lint without changing behavior.
     this.respond = api.respond.bind(api)
-    this.workspaceRootOf = api.workspaceRootOf.bind(api)
   }
 }
 
diff --git a/packages/host/apiproxy/src/native-path-opener.ts b/packages/host/apiproxy/src/native-path-opener.ts
index a4fbbaa72e..444cf3d408 100644
--- a/packages/host/apiproxy/src/native-path-opener.ts
+++ b/packages/host/apiproxy/src/native-path-opener.ts
@@ -1,5 +1,16 @@
-/** Cross-platform open-with-default-application used by the local GUI carrier. */
+/**
+ * Cross-platform open-with-default-application used by the local GUI carrier.
+ *
+ * A document a browser RENDERS is opened with the user's default browser
+ * rather than the default application for its type, when the platform can name
+ * one: a developer who binds `.html` to an editor would otherwise click a
+ * produced page and get source code. The contract is uniform — prefer the
+ * default browser, fall back to the default application — while how completely
+ * a platform can answer "which browser" differs, and every failure falls back
+ * rather than surfacing.
+ */
 
+import { extname } from 'node:path'
 import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
 
 /** Testable command boundary; native implementations never invoke a shell. */
@@ -9,6 +20,60 @@ export type PathOpenerRunner = NativeCommandRunner
 export interface PathOpenerInternals {
   platform?: NodeJS.Platform
   run?: PathOpenerRunner
+  /** Environment the linux browser convention reads; defaults to the process env. */
+  env?: NodeJS.ProcessEnv
+}
+
+/** Documents a browser renders, as opposed to ones an editor merely edits. */
+const BROWSER_DOCUMENTS = new Set(['.html', '.htm', '.xhtml', '.svg'])
+
+/**
+ * The macOS bundle registered for `https` — the default browser, as
+ * LaunchServices records it. The nested version dict is stripped first
+ * because it carries its own `LSHandlerRoleAll`.
+ */
+function macBundleForHttps(plist: string): string | undefined {
+  const stripped = plist.replace(/LSHandlerPreferredVersions\s*=\s*\{[^}]*\};/g, '')
+  const block = /\{[^{}]*LSHandlerURLScheme\s*=\s*"?https"?;[^{}]*\}/.exec(stripped)?.[0]
+  if (block === undefined) return undefined
+  return /LSHandlerRoleAll\s*=\s*"?([\w.-]+)"?;/.exec(block)?.[1]
+}
+
+/**
+ * Open one browser-renderable document with the default browser.
+ * @returns true when a browser took it; false when this platform cannot name
+ * one, or naming it failed — the caller then uses the default application.
+ */
+async function openInBrowser(
+  path: string, signal: AbortSignal, platform: NodeJS.Platform,
+  run: PathOpenerRunner, env: NodeJS.ProcessEnv,
+): Promise<boolean> {
+  if (platform === 'darwin') {
+    let bundle: string | undefined
+    try {
+      const { stdout } = await run(
+        'defaults', ['read', 'com.apple.LaunchServices/com.apple.launchservices.secure'], signal)
+      bundle = macBundleForHttps(stdout)
+    } catch {
+      // No LaunchServices record (a fresh account never changed a default):
+      // the content-type handler is then the system's own choice anyway.
+      return false
+    }
+    if (bundle === undefined) return false
+    await run('open', ['-b', bundle, path], signal)
+    return true
+  }
+  if (platform === 'linux') {
+    // $BROWSER is the portable convention; desktop-entry resolution through
+    // xdg-settings needs a launcher this package has no business shipping.
+    const browser = env.BROWSER
+    if (browser === undefined || browser === '') return false
+    await run(browser, [path], signal)
+    return true
+  }
+  // Windows names no browser without reading the UserChoice registry, and its
+  // .html association is the browser in the ordinary case.
+  return false
 }
 
 /** PowerShell single-quoted literal (doubles embedded quotes). */
@@ -17,10 +82,11 @@ function powershellLiteral(path: string): string {
 }
 
 /**
- * Open a filesystem path with the operating system's default application.
+ * Open a filesystem path with the operating system's default application, or
+ * with the default browser when the path names a document a browser renders.
  * @param path - absolute or host-resolvable path (caller owns resolution).
  * @param signal - caller/connection lifetime; abort terminates the native command.
- * @param internals - platform and runner seam for deterministic tests.
+ * @param internals - platform, environment, and runner seam for deterministic tests.
  */
 export async function openNativePath(
   path: string,
@@ -29,6 +95,10 @@ export async function openNativePath(
 ): Promise<void> {
   const platform = internals.platform ?? process.platform
   const run = internals.run ?? runNativeCommand
+  const env = internals.env ?? process.env
+
+  if (BROWSER_DOCUMENTS.has(extname(path).toLowerCase())
+    && await openInBrowser(path, signal, platform, run, env)) return
 
   if (platform === 'darwin') {
     await run('open', [path], signal)
diff --git a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
index cc30e5dee2..da05a4cd9b 100644
--- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
@@ -62,11 +62,7 @@ function stubAgent(session: Session): Agent {
 async function harness(
   workspaceRoot = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-apiproxy-workspace-'))),
   picker: DirectoryPickerCapability = { kind: 'native', pick: async () => null },
-  extras: {
-    openPath?: (path: string, signal: AbortSignal) => Promise<void>
-    /** Store contents behind the gateway, or 'absent' for a composition with no persistence at all. */
-    persisted?: { id: SessionId; cwd?: string }[] | 'absent'
-  } = {},
+  extras: { openPath?: (path: string, signal: AbortSignal) => Promise<void> } = {},
 ) {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
@@ -77,10 +73,7 @@ async function harness(
   const storageDomain = new DomainFacility(ctx, { backend: 'memory', routes: {} })
   ctx.storage.mount('domain', storageDomain)
   ctx.provide('storageDomain', storageDomain)
-  if (extras.persisted !== 'absent') {
-    const persisted = extras.persisted ?? []
-    ctx.provide('sessionPersistence', { list: () => Promise.resolve(persisted) } as never)
-  }
+  ctx.provide('sessionPersistence', { list: () => Promise.resolve([]) } as never)
   await ctx.plugin(WorkspaceRegistry)
 
   const factory: AgentFactory = {
@@ -251,27 +244,6 @@ describe('host.openPath', () => {
   })
 })
 
-describe('workspaceRootOf', () => {
-  it('answers from the live agent, then the store, and names nothing for an unknown session', async () => {
-    const { api, workspaceRoot } = await harness(undefined, undefined, {
-      persisted: [{ id: 's-cold' as SessionId, cwd: '/w/cold' }],
-    })
-    const created = await api.sessions.create(request({ cwd: workspaceRoot }))
-    const sessionId = (created.result as { ok: true; value: { sessionId: SessionId } }).value.sessionId
-    // Live: the agent's own header, no store read involved.
-    await expect(api.workspaceRootOf(sessionId)).resolves.toBe(workspaceRoot)
-    // Not live: the store answers, and the lookup never resumes an agent —
-    // this harness's factory throws on resume, so a resuming lookup would fail.
-    await expect(api.workspaceRootOf('s-cold' as SessionId)).resolves.toBe('/w/cold')
-    await expect(api.workspaceRootOf('s-absent' as SessionId)).resolves.toBeUndefined()
-  })
-
-  it('names nothing at all when the host keeps no session store', async () => {
-    const { api } = await harness(undefined, undefined, { persisted: 'absent' })
-    await expect(api.workspaceRootOf('s-any' as SessionId)).resolves.toBeUndefined()
-  })
-})
-
 describe('workspace.create', () => {
   it('serializes concurrent names and rejects the duplicate', async () => {
     const { api, workspaceRoot } = await harness()
diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts
index 2299949890..6307dfe8f9 100644
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -108,8 +108,6 @@ function scriptedApi(overrides: {
     },
     events: { mux: () => empty<MuxFrame>(), host: () => empty<HostFrame>(), ...overrides.events },
     respond: overrides.respond ?? (() => Promise.resolve({ accepted: false as const, reason: 'not-pending' as const })),
-    // No wire face, so the handler map never reaches it.
-    workspaceRootOf: () => Promise.resolve(undefined),
   }
 }
 
diff --git a/packages/host/apiproxy/tests/fetch-carrier.spec.ts b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
index dac49a1234..ef111afe12 100644
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -233,8 +233,6 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
     async respond(message: ClientResponse): Promise<RpcReceipt> {
       return message.rpcId === 'known' ? { accepted: true } : { accepted: false, reason: 'not-pending' }
     },
-    // No wire face, so the carrier never reaches it.
-    workspaceRootOf: () => Promise.resolve(undefined),
   }
 }
 
diff --git a/packages/host/apiproxy/tests/files-path.spec.ts b/packages/host/apiproxy/tests/files-path.spec.ts
deleted file mode 100644
index df309a4783..0000000000
--- a/packages/host/apiproxy/tests/files-path.spec.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-/** The /f URL shape: one encoding decision, asserted from both ends. */
-import { describe, expect, it } from 'vitest'
-import {
-  FILES_PATH, parseWorkspaceFilePath, workspaceFileSegments, workspaceFileUrl,
-} from '../src/api/files.ts'
-
-describe('workspaceFileSegments', () => {
-  it('keeps a relative path as its own segments', () => {
-    expect(workspaceFileSegments('/w', 'out/index.html')).toEqual(['out', 'index.html'])
-    expect(workspaceFileSegments(undefined, 'index.html')).toEqual(['index.html'])
-    expect(workspaceFileSegments('/w', './a/./b.txt')).toEqual(['a', 'b.txt'])
-  })
-
-  it('strips the cwd prefix from an absolute path inside the workspace', () => {
-    expect(workspaceFileSegments('/w', '/w/a/b.html')).toEqual(['a', 'b.html'])
-    // A trailing separator on the cwd must not shift the split.
-    expect(workspaceFileSegments('/w/', '/w/a.html')).toEqual(['a.html'])
-  })
-
-  it('reads Windows paths on either separator', () => {
-    expect(workspaceFileSegments('C:\\w', 'C:\\w\\a\\b.html')).toEqual(['a', 'b.html'])
-    expect(workspaceFileSegments('C:/w', 'C:\\w\\a.html')).toEqual(['a.html'])
-  })
-
-  it('refuses everything the route would not serve', () => {
-    // Absolute, but not under this workspace.
-    expect(workspaceFileSegments('/w', '/etc/hosts')).toBeUndefined()
-    // A sibling directory sharing the cwd's name prefix is not inside it.
-    expect(workspaceFileSegments('/w', '/workspace-other/a')).toBeUndefined()
-    // Absolute with no cwd to anchor against.
-    expect(workspaceFileSegments(undefined, '/w/a.html')).toBeUndefined()
-    expect(workspaceFileSegments('', '/w/a.html')).toBeUndefined()
-    // Traversal, in either spelling.
-    expect(workspaceFileSegments('/w', '../secret')).toBeUndefined()
-    expect(workspaceFileSegments('/w', 'a/../../secret')).toBeUndefined()
-    // The workspace directory itself is not a file.
-    expect(workspaceFileSegments('/w', '/w')).toBeUndefined()
-    expect(workspaceFileSegments('/w', '.')).toBeUndefined()
-  })
-})
-
-describe('workspaceFileUrl', () => {
-  it('percent-encodes each segment but keeps the separators structural', () => {
-    expect(workspaceFileUrl('s-1', ['out', 'a b.html'])).toBe(`${FILES_PATH}/s-1/out/a%20b.html`)
-    expect(workspaceFileUrl('s/1', ['a#b.html'])).toBe(`${FILES_PATH}/s%2F1/a%23b.html`)
-  })
-})
-
-describe('parseWorkspaceFilePath', () => {
-  it('round-trips what the browser half builds', () => {
-    const url = workspaceFileUrl('s-1', ['out', 'a b.html'])
-    expect(parseWorkspaceFilePath(url)).toEqual({ sessionId: 's-1', segments: ['out', 'a b.html'] })
-  })
-
-  it('refuses malformed, prefix-foreign, and traversal pathnames', () => {
-    expect(parseWorkspaceFilePath('/api/session.list')).toBeUndefined()
-    expect(parseWorkspaceFilePath(FILES_PATH)).toBeUndefined()
-    // Session named but no file below it.
-    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1`)).toBeUndefined()
-    expect(parseWorkspaceFilePath(`${FILES_PATH}//a.html`)).toBeUndefined()
-    // Traversal is refused at parse time, before any filesystem call.
-    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/../etc/hosts`)).toBeUndefined()
-    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a/./b`)).toBeUndefined()
-    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a//b`)).toBeUndefined()
-    // A separator smuggled through percent-encoding stays one segment's problem.
-    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a%2F..%2Fb`)).toBeUndefined()
-    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a%5Cb`)).toBeUndefined()
-    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a%00b`)).toBeUndefined()
-    // Malformed percent-escapes are uninterpretable, not a miss to resolve.
-    expect(parseWorkspaceFilePath(`${FILES_PATH}/s-1/a%zz`)).toBeUndefined()
-    expect(parseWorkspaceFilePath(`${FILES_PATH}/%zz/a.html`)).toBeUndefined()
-    expect(parseWorkspaceFilePath(`${FILES_PATH}//`)).toBeUndefined()
-  })
-})
diff --git a/packages/host/apiproxy/tests/native-path-opener.spec.ts b/packages/host/apiproxy/tests/native-path-opener.spec.ts
index c8622002e2..f56ff1c66b 100644
--- a/packages/host/apiproxy/tests/native-path-opener.spec.ts
+++ b/packages/host/apiproxy/tests/native-path-opener.spec.ts
@@ -80,3 +80,96 @@ describe('native path opener', () => {
     })
   })
 })
+
+describe('browser-renderable documents', () => {
+  const LS_PLIST = `{
+    LSHandlers = (
+        {
+            LSHandlerPreferredVersions =             {
+                LSHandlerRoleAll = "-";
+            };
+            LSHandlerRoleAll = "com.google.chrome";
+            LSHandlerURLScheme = https;
+        }
+    );
+}`
+
+  it('opens a page with the default browser rather than the .html handler on darwin', async () => {
+    const calls: { command: string; args: readonly string[] }[] = []
+    const run = async (command: string, args: readonly string[]) => {
+      calls.push({ command, args })
+      return { stdout: command === 'defaults' ? LS_PLIST : '', stderr: '' }
+    }
+    await openNativePath('/w/page.html', new AbortController().signal, { platform: 'darwin', run })
+    // A developer who bound .html to an editor still gets a rendered page.
+    expect(calls.map(c => [c.command, ...c.args])).toEqual([
+      ['defaults', 'read', 'com.apple.LaunchServices/com.apple.launchservices.secure'],
+      ['open', '-b', 'com.google.chrome', '/w/page.html'],
+    ])
+  })
+
+  it('leaves every other document to the default application', async () => {
+    const calls: string[][] = []
+    const run = async (command: string, args: readonly string[]) => {
+      calls.push([command, ...args])
+      return { stdout: '', stderr: '' }
+    }
+    await openNativePath('/w/report.md', new AbortController().signal, { platform: 'darwin', run })
+    // No LaunchServices read at all: markdown is not a browser document.
+    expect(calls).toEqual([['open', '/w/report.md']])
+  })
+
+  it('falls back to the default application when no browser can be named', async () => {
+    // LaunchServices has no https record (a fresh account), so the system's
+    // own content-type choice is the best answer available.
+    const calls: string[][] = []
+    const run = async (command: string, args: readonly string[]) => {
+      calls.push([command, ...args])
+      if (command === 'defaults') throw new Error('domain not found')
+      return { stdout: '', stderr: '' }
+    }
+    await openNativePath('/w/page.html', new AbortController().signal, { platform: 'darwin', run })
+    expect(calls).toEqual([
+      ['defaults', 'read', 'com.apple.LaunchServices/com.apple.launchservices.secure'],
+      ['open', '/w/page.html'],
+    ])
+
+    // A record without an https handler is the same answer.
+    const bare: string[][] = []
+    await openNativePath('/w/page.html', new AbortController().signal, {
+      platform: 'darwin',
+      run: async (command, args) => {
+        bare.push([command, ...args])
+        return { stdout: '{ LSHandlers = ( ); }', stderr: '' }
+      },
+    })
+    expect(bare[1]).toEqual(['open', '/w/page.html'])
+  })
+
+  it('honors $BROWSER on linux and leaves windows to its association', async () => {
+    const linux: string[][] = []
+    await openNativePath('/w/page.html', new AbortController().signal, {
+      platform: 'linux',
+      env: { BROWSER: 'firefox' },
+      run: async (command, args) => { linux.push([command, ...args]); return { stdout: '', stderr: '' } },
+    })
+    expect(linux).toEqual([['firefox', '/w/page.html']])
+
+    // Unset $BROWSER: xdg-open's association is the fallback.
+    const bare: string[][] = []
+    await openNativePath('/w/page.html', new AbortController().signal, {
+      platform: 'linux',
+      env: {},
+      run: async (command, args) => { bare.push([command, ...args]); return { stdout: '', stderr: '' } },
+    })
+    expect(bare).toEqual([['xdg-open', '/w/page.html']])
+
+    // Windows names no browser without the UserChoice registry.
+    const win: string[][] = []
+    await openNativePath('C:\\w\\page.html', new AbortController().signal, {
+      platform: 'win32',
+      run: async (command, args) => { win.push([command, ...args]); return { stdout: '', stderr: '' } },
+    })
+    expect(win[0]?.[0]).toBe('powershell.exe')
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5fb7df52ad..7073f04e4b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1183,9 +1183,6 @@ importers:
         specifier: ^4.1.8
         version: 4.1.8(@opentelemetry/api@1.9.1)(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
     devDependencies:
-      '@deepseek-ai/dsh-client-connection':
-        specifier: workspace:^
-        version: link:../connection
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../runtime
@@ -1266,9 +1263,6 @@ importers:
         specifier: ^2.0.0
         version: 2.1.1
     devDependencies:
-      '@deepseek-ai/dsh-client-connection':
-        specifier: workspace:^
-        version: link:../connection
       '@deepseek-ai/dsh-client-locale':
         specifier: workspace:^
         version: link:../locale
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 9de5b51da0..89f57e364a 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -38,7 +38,7 @@
     "apps/web/tests/access-confirmation.e2e.ts",
     "apps/web/tests/shipped-composition.e2e.ts",
     "apps/web/tests/startup-auto-selection.e2e.ts",
-    "apps/web/tests/workspace-file-open.e2e.ts",
+    "apps/web/tests/produced-files.e2e.ts",
     "apps/cli/tests/**/*.ts",
     "examples/*/src/**/*.ts",
     "examples/*/start.ts",

From 8d92a9bdaaebf79f45027a48ada60212416b20dc Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 11:43:44 +0800
Subject: [PATCH 012/516] fix(user-interaction): reject ask_user_question from
 delegated subagents

---
 ...-ask-user-delegated-caller-guard.i18n.yaml |  6 ++++
 ...6-08-01-ask-user-delegated-caller-guard.md | 29 +++++++++++++++
 ...8-01-ask-user-delegated-caller-guard.zh.md | 29 +++++++++++++++
 packages/ui/tool-ask-user/README.i18n.yaml    |  4 +--
 packages/ui/tool-ask-user/README.md           |  1 +
 packages/ui/tool-ask-user/README.zh.md        |  1 +
 .../tool-ask-user/tests/tool-ask-user.spec.ts | 33 ++++++++++++++++-
 packages/ui/user-interaction/README.i18n.yaml |  4 +--
 packages/ui/user-interaction/README.md        |  4 +--
 packages/ui/user-interaction/README.zh.md     |  4 +--
 packages/ui/user-interaction/src/index.ts     | 12 +++++++
 .../tests/user-interaction.spec.ts            | 35 +++++++++++++++++++
 12 files changed, 153 insertions(+), 9 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md

diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
new file mode 100644
index 0000000000..800a575f3b
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.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-08-01-ask-user-delegated-caller-guard.md
+2026-08-01-ask-user-delegated-caller-guard.md: 17c5e42a1d12c018507c6cf410129bb17099e967
+2026-08-01-ask-user-delegated-caller-guard.zh.md: 38f059ba87ac5208cca6cb94ba9ee5223a6987b0
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
new file mode 100644
index 0000000000..17c5e42a1d
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
@@ -0,0 +1,29 @@
+# Agent Note: Reject ask_user_question from delegated subagents
+
+Status: implemented
+
+English | [中文](2026-08-01-ask-user-delegated-caller-guard.zh.md)
+
+## Problem
+
+A delegated subagent that calls the `ask_user_question` tool blocks indefinitely. The tool pauses for a human answer, but a child context has no human answerer, so no answer ever arrives and the subagent run hangs until it is cancelled externally.
+
+## Decision
+
+`UserInteractionService.ask()` rejects any request whose calling agent is a delegated subagent — `request.agent.session.header.delegationDepth > 0` — with a new `UserInteractionError` code `DELEGATED_CALLER` and the message `ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent`. The check runs at the top of `ask()`, after the aborted/empty guards and before intent validation, so no provider interaction happens for a rejected child. This mirrors the goal tools' top-level-only authority (`create_goal` rejects non-top-level agents with a direct-human-turn requirement).
+
+## Alternatives considered
+
+**Leave the child blocked until the parent forwards an answer.** Rejected: no answerer exists in the child context and no forwarding seam exists; the observed behavior is a permanent hang.
+
+**Reject inside the tool (`dsh-tool-ask-user`) instead of the service.** Rejected: that consumer seam is bypassed by direct callers of `ctx.userInteraction.ask()`; the operation boundary that owns the decision is the service itself.
+
+**Warn children off via the model-facing description.** Rejected: the rejection is already a loud, self-explanatory error, and a description edit would not stop the hang for a model that calls anyway.
+
+## Consequences
+
+Delegated subagent calls fail fast with a stable error instead of hanging; a child that needs a decision must delegate the question to the top-level agent. Programmatic askers without an agent and top-level agents (`delegationDepth` absent or 0) are unaffected and still reach the provider. The `DELEGATED_CALLER` code joins the documented `UserInteractionError` taxonomy in the package READMEs, and the model-facing description is unchanged.
+
+## Testing
+
+Two new unit tests exercise the guard: `user-interaction.spec.ts` asserts that `ask()` rejects with `DELEGATED_CALLER` and never calls the provider for a session created with `{ meta: { delegationDepth: 1 } }`, plus a positive control at `delegationDepth: 0`; `tool-ask-user.spec.ts` asserts that a tool call from a delegated agent surfaces the structured error and never reaches the provider. Both packages pass, as does the parent `packages/ui` scope, and the two touched `src` files hold 100% per-file coverage.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
new file mode 100644
index 0000000000..38f059ba87
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 拒绝委托子代理调用 ask_user_question
+
+Status: implemented
+
+[English](2026-08-01-ask-user-delegated-caller-guard.md) | 中文
+
+## 问题
+
+委托子代理调用 `ask_user_question` 工具时会无限阻塞。该工具会暂停等待人类回答，但子代理上下文中没有人类应答者，因此永远等不到回答，子代理运行只能被外部取消。
+
+## 决策
+
+`UserInteractionService.ask()` 拒绝任何调用方为委托子代理的请求 —— `request.agent.session.header.delegationDepth > 0` —— 抛出新的 `UserInteractionError`，代码为 `DELEGATED_CALLER`，消息为 `ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent`。该检查位于 `ask()` 开头，在已中止/空问题守卫之后、意图校验之前，因此被拒绝的子代理不会触发任何提供方交互。这与 goal 工具仅限顶层代理的权限保持一致（`create_goal` 以直接人工回合要求拒绝非顶层代理）。
+
+## 备选方案
+
+**让子代理一直阻塞，直到父代理转发回答。** 不予采用：子代理上下文中不存在应答者，也没有任何转发 seam；实际观察到的行为就是永久挂起。
+
+**在工具（`dsh-tool-ask-user`）而非服务中拒绝。** 不予采用：直接调用 `ctx.userInteraction.ask()` 的调用方会绕过该消费方 seam；拥有此决策权的操作边界是服务本身。
+
+**通过模型侧描述来警告子代理。** 不予采用：拒绝本身已是响亮且自解释的错误，而且修改描述并不能阻止仍然去调用的模型造成挂起。
+
+## 影响
+
+委托子代理的调用会以稳定错误快速失败，而不是挂起；需要决策的子代理必须把问题转交给顶层代理。不带 agent 的程序化调用方以及顶层代理（`delegationDepth` 缺省或为 0）不受影响，仍会到达提供方。`DELEGATED_CALLER` 代码已加入包 README 中记载的 `UserInteractionError` 分类，模型侧描述保持不变。
+
+## Testing
+
+两个新的单元测试覆盖该守卫：`user-interaction.spec.ts` 断言以 `{ meta: { delegationDepth: 1 } }` 创建的会话调用 `ask()` 会以 `DELEGATED_CALLER` 拒绝且绝不调用提供方，并补充了 `delegationDepth: 0` 的正向对照；`tool-ask-user.spec.ts` 断言委托子代理发出的工具调用会呈现结构化错误且绝不触达提供方。两个包均通过，父级 `packages/ui` 作用域也通过，且两个被改动的 `src` 文件保持 100% 逐文件覆盖率。
diff --git a/packages/ui/tool-ask-user/README.i18n.yaml b/packages/ui/tool-ask-user/README.i18n.yaml
index 7b8e667b58..869a5988c1 100644
--- a/packages/ui/tool-ask-user/README.i18n.yaml
+++ b/packages/ui/tool-ask-user/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/tool-ask-user/README.md
-README.md: 8e779f4025c20cd200344efb7cb8cd6bc09ba64d
-README.zh.md: acaffec0764404a0e0e842ffc2b4efdee8869c4f
+README.md: d7866ff018ebfed5afbf105b1a20714490bdb818
+README.zh.md: 18a1c8e9f958c174fc34f26a572d88b6c031d7f9
diff --git a/packages/ui/tool-ask-user/README.md b/packages/ui/tool-ask-user/README.md
index 8e779f4025..d7866ff018 100644
--- a/packages/ui/tool-ask-user/README.md
+++ b/packages/ui/tool-ask-user/README.md
@@ -54,4 +54,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **A pending question blocks the tool call until the human answers** — the tool declares no `timeout-policy` budget; cancellation rides the turn's `exec.signal` only.
+- **Delegated subagents cannot ask the user** — `ask_user_question` rejects calls from a delegated subagent with `DELEGATED_CALLER`; a child that needs a decision must delegate the question to the top-level agent.
 - **Native answers render as JSON text** — the canonical value remains structured, but the model-facing result uses compact JSON rather than a richer content-block vocabulary.
diff --git a/packages/ui/tool-ask-user/README.zh.md b/packages/ui/tool-ask-user/README.zh.md
index acaffec076..18a1c8e9f9 100644
--- a/packages/ui/tool-ask-user/README.zh.md
+++ b/packages/ui/tool-ask-user/README.zh.md
@@ -54,4 +54,5 @@
 ## 已知限制与暂缓事项
 
 - **待处理问题会阻塞工具调用，直至用户作答**：该工具未声明 `timeout-policy` 预算；取消仅沿用当前轮次的 `exec.signal`。
+- **委托的子代理不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝来自委托子代理的调用；需要决策的子代理必须把问题转交给顶层代理。
 - **Native 回答渲染为 JSON 文本**：规范值仍为结构化数据，但模型侧结果使用紧凑 JSON，而非更丰富的内容块词汇。
diff --git a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts
index 395986aed1..4c9e572c40 100644
--- a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts
+++ b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import UserInteractionService, { type AskUserQuestionRequest } from '@deepseek-ai/dsh-user-interaction'
@@ -201,6 +202,7 @@ describe('ask_user_question tool', () => {
 
   it('passes optional header and agent through to the user-interaction request', async () => {
     const ctx = await setup()
+    await ctx.plugin(SessionStore)
     const seen: AskUserQuestionRequest[] = []
     ctx.userInteraction.registerProvider({
       async ask(request) {
@@ -208,7 +210,8 @@ describe('ask_user_question tool', () => {
         return { answers: [{ id: 'continue', selected: ['ok'] }] }
       },
     })
-    const agent = { id: 'main' } as unknown as Agent
+    const session = ctx.sessions.create(undefined, { meta: { delegationDepth: 0 } })
+    const agent = { session } as unknown as Agent
 
     const result = await ctx.tools.execute({
       signal: testToolSignal,
@@ -238,6 +241,34 @@ describe('ask_user_question tool', () => {
     })
   })
 
+  it('rejects a delegated subagent with a structured DELEGATED_CALLER error', async () => {
+    const ctx = await setup()
+    await ctx.plugin(SessionStore)
+    const seen: AskUserQuestionRequest[] = []
+    ctx.userInteraction.registerProvider({
+      async ask(request) {
+        seen.push(request)
+        return { answers: [{ id: 'continue', selected: ['ok'] }] }
+      },
+    })
+    const session = ctx.sessions.create(undefined, { meta: { delegationDepth: 1 } })
+    const agent = { session } as unknown as Agent
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('ask-delegated'),
+      name: 'ask_user_question',
+      arguments: { questions: [{ id: 'continue', question: 'Continue?' }] },
+      agent,
+    })
+
+    expect(result).toMatchObject({
+      isError: true,
+      error: { info: { name: 'UserInteractionError', code: 'DELEGATED_CALLER' } },
+    })
+    expect(seen).toHaveLength(0)
+  })
+
   it('returns a structured error for empty question batches', async () => {
     const ctx = await setup()
 
diff --git a/packages/ui/user-interaction/README.i18n.yaml b/packages/ui/user-interaction/README.i18n.yaml
index a74e6ec71b..7d2ea23b14 100644
--- a/packages/ui/user-interaction/README.i18n.yaml
+++ b/packages/ui/user-interaction/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/user-interaction/README.md
-README.md: d62e75d110b8be339c5f9449b0834320f695ac99
-README.zh.md: 55258e85e56df2375ed8f195fa0b3b731a9cb816
+README.md: 3459f915f2cd94d4083975440731661d8aeb9108
+README.zh.md: 26d40e98dbcc15ef18a85cd98205defb765d4469
diff --git a/packages/ui/user-interaction/README.md b/packages/ui/user-interaction/README.md
index d62e75d110..3459f915f2 100644
--- a/packages/ui/user-interaction/README.md
+++ b/packages/ui/user-interaction/README.md
@@ -18,7 +18,7 @@ Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a mod
 - `AskUserQuestionIntent` — `{ kind: 'plan-review', approve }`; the tagged presentation intent below.
 - `AskUserQuestionAnswer` — `{ answers: [{ id, selected, custom? }] }`.
 - `UserInteractionProvider` — UI implementation with `ask(request)`.
-- `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `BAD_INTENT`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`.
+- `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `BAD_INTENT`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, `ASK_ABORTED`, and `DELEGATED_CALLER`.
 
 When an answer includes `custom`, `selected` is empty; custom text is an override rather than a supplement to selected choices. A UI may preserve a skipped item as `{ id, selected: [] }`, keeping the existing answer shape while retaining other answers in the batch.
 
@@ -32,7 +32,7 @@ This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-
 
 ## Model Experience
 
-Indirectly, through `dsh-tool-ask-user`, which retains a successful provider answer as compact JSON or one of these failures: `Error: ask_user_question was aborted before the user answered`, `Error: ask_user_question requires at least one question`, `Error: no user-interaction provider is registered`, or `Error: <message>`. Waiting for the human adds no tokens.
+Indirectly, through `dsh-tool-ask-user`, which retains a successful provider answer as compact JSON or one of these failures: `Error: ask_user_question was aborted before the user answered`, `Error: ask_user_question requires at least one question`, `Error: ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent`, `Error: no user-interaction provider is registered`, or `Error: <message>`. Waiting for the human adds no tokens.
 
 #### KV Cache effect
 
diff --git a/packages/ui/user-interaction/README.zh.md b/packages/ui/user-interaction/README.zh.md
index 55258e85e5..26d40e98db 100644
--- a/packages/ui/user-interaction/README.zh.md
+++ b/packages/ui/user-interaction/README.zh.md
@@ -18,7 +18,7 @@
 - `AskUserQuestionIntent`：`{ kind: 'plan-review', approve }`；即下文的带标签呈现意图。
 - `AskUserQuestionAnswer`：`{ answers: [{ id, selected, custom? }] }`。
 - `UserInteractionProvider`：包含 `ask(request)` 的 UI 实现。
-- `UserInteractionError`：`HarnessError` 的子类，包含 `EMPTY_QUESTIONS`、`BAD_INTENT`、`NO_PROVIDER`、`DUPLICATE_PROVIDER` 和 `ASK_ABORTED` 等代码。
+- `UserInteractionError`：`HarnessError` 的子类，包含 `EMPTY_QUESTIONS`、`BAD_INTENT`、`NO_PROVIDER`、`DUPLICATE_PROVIDER`、`ASK_ABORTED` 和 `DELEGATED_CALLER` 等代码。
 
 当回答包含 `custom` 时，`selected` 为空；自定义文本是所选选项的替代，而不是补充。UI 可以把跳过的条目保留为 `{ id, selected: [] }`，既维持现有回答形态，也保留该批次中的其他回答。
 
@@ -32,7 +32,7 @@
 
 ## 模型体验
 
-间接地，通过 `dsh-tool-ask-user`：它会将成功的提供方回答保留为紧凑 JSON，或返回以下失败之一：`Error: ask_user_question was aborted before the user answered`、`Error: ask_user_question requires at least one question`、`Error: no user-interaction provider is registered` 或 `Error: <message>`。等待人类回答不会增加 token。
+间接地，通过 `dsh-tool-ask-user`：它会将成功的提供方回答保留为紧凑 JSON，或返回以下失败之一：`Error: ask_user_question was aborted before the user answered`、`Error: ask_user_question requires at least one question`、`Error: ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent`、`Error: no user-interaction provider is registered` 或 `Error: <message>`。等待人类回答不会增加 token。
 
 #### KV Cache 影响
 
diff --git a/packages/ui/user-interaction/src/index.ts b/packages/ui/user-interaction/src/index.ts
index 506b3c6bfe..b7e76c1d47 100644
--- a/packages/ui/user-interaction/src/index.ts
+++ b/packages/ui/user-interaction/src/index.ts
@@ -77,8 +77,15 @@ export class UserInteractionService extends Service {
   /**
    * Ask the active UI provider and wait for the user's answer.
    *
+   * Human-interaction requests are only valid from a top-level agent: a
+   * delegated subagent has no human answerer in its own context, so asking
+   * there would block forever. This mirrors the goal tools' top-level-only
+   * authority (`create_goal` rejects non-top-level agents).
+   *
    * @param request Questions, owner agent, and abort signal.
    * @returns The answer chosen or typed by the human.
+   * @throws {UserInteractionError} code `DELEGATED_CALLER` when the calling
+   *   agent is a delegated subagent (`session.header.delegationDepth > 0`).
    */
   async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer> {
     if (request.signal?.aborted) {
@@ -87,6 +94,11 @@ export class UserInteractionService extends Service {
     if (request.questions.length === 0) {
       throw new UserInteractionError('ask_user_question requires at least one question', 'EMPTY_QUESTIONS')
     }
+    if ((request.agent?.session.header.delegationDepth ?? 0) > 0) {
+      throw new UserInteractionError(
+        'ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent',
+        'DELEGATED_CALLER')
+    }
     // A presentation intent asserts two things the types cannot: that the
     // named approve label is one of this question's own options, and that a
     // plan-review carries the plan it is a review of. A UI honouring the
diff --git a/packages/ui/user-interaction/tests/user-interaction.spec.ts b/packages/ui/user-interaction/tests/user-interaction.spec.ts
index df6b878cbd..30fdf49a7e 100644
--- a/packages/ui/user-interaction/tests/user-interaction.spec.ts
+++ b/packages/ui/user-interaction/tests/user-interaction.spec.ts
@@ -1,5 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore from '@deepseek-ai/dsh-session'
 import UserInteractionService, {
   UserInteractionError,
   type AskUserQuestionRequest,
@@ -84,6 +86,39 @@ describe('UserInteractionService', () => {
     expect(p.ask).not.toHaveBeenCalled()
   })
 
+  it('rejects a delegated subagent before reaching the provider', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(UserInteractionService)
+    const p = { ask: vi.fn(async () => ({ answers: [] })) }
+    ctx.userInteraction.registerProvider(p)
+    const session = ctx.sessions.create(undefined, { meta: { delegationDepth: 1 } })
+    const agent = { session } as unknown as Agent
+
+    await expect(ctx.userInteraction.ask({
+      questions: [{ id: 'confirm', question: 'Proceed?' }],
+      agent,
+    })).rejects.toMatchObject({ name: 'UserInteractionError', code: 'DELEGATED_CALLER' })
+    expect(p.ask).not.toHaveBeenCalled()
+  })
+
+  it('still reaches the provider for a top-level agent (delegationDepth 0)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(UserInteractionService)
+    const p = provider('yes')
+    ctx.userInteraction.registerProvider(p)
+    const session = ctx.sessions.create(undefined, { meta: { delegationDepth: 0 } })
+    const agent = { session } as unknown as Agent
+
+    const result = await ctx.userInteraction.ask({
+      questions: [{ id: 'confirm', question: 'Proceed?' }],
+      agent,
+    })
+
+    expect(result).toEqual({ answers: [{ id: 'confirm', selected: ['yes'] }] })
+  })
+
   it('rejects an intent whose approve label names none of its own options', async () => {
     const ctx = new Context()
     await ctx.plugin(UserInteractionService)

From 46d8d97efec7aec57ac3a280a8b5956c0b13ccf9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 11:45:33 +0800
Subject: [PATCH 013/516] chore(cordis): regenerate service catalog for
 user-interaction JSDoc

---
 docs/cordis-catalog/services.md                | 7 +++++++
 packages/cordis/tool-cordis/src/api-catalog.ts | 2 +-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 22bc6343ea..dee9c09f38 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2445,8 +2445,15 @@ registerProvider(provider: UserInteractionProvider): () => void
 /**
  * Ask the active UI provider and wait for the user's answer.
  *
+ * Human-interaction requests are only valid from a top-level agent: a
+ * delegated subagent has no human answerer in its own context, so asking
+ * there would block forever. This mirrors the goal tools' top-level-only
+ * authority (`create_goal` rejects non-top-level agents).
+ *
  * @param request Questions, owner agent, and abort signal.
  * @returns The answer chosen or typed by the human.
+ * @throws {UserInteractionError} code `DELEGATED_CALLER` when the calling
+ *   agent is a delegated subagent (`session.header.delegationDepth > 0`).
  */
 async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 ```
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 2beb8a3c77..7089ee0f5d 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -1114,7 +1114,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>',
-        jsDoc: '/**\n * Ask the active UI provider and wait for the user\'s answer.\n *\n * @param request Questions, owner agent, and abort signal.\n * @returns The answer chosen or typed by the human.\n */',
+        jsDoc: '/**\n * Ask the active UI provider and wait for the user\'s answer.\n *\n * Human-interaction requests are only valid from a top-level agent: a\n * delegated subagent has no human answerer in its own context, so asking\n * there would block forever. This mirrors the goal tools\' top-level-only\n * authority (`create_goal` rejects non-top-level agents).\n *\n * @param request Questions, owner agent, and abort signal.\n * @returns The answer chosen or typed by the human.\n * @throws {UserInteractionError} code `DELEGATED_CALLER` when the calling\n *   agent is a delegated subagent (`session.header.delegationDepth > 0`).\n */',
       },
     ],
   },

From 1ee167aeaca76ef483db6d2e3a2c6ba1f110161f Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 3 Aug 2026 19:49:30 +0800
Subject: [PATCH 014/516] feat(fs): append recovery remedy to guarded-mutation
 errors

write/edit failures with FS_STALE_VERSION or FS_NOT_OBSERVED now reach the
model with the correct recovery instruction appended (re-read / read, then
retry) while preserving the structured code and chaining the cause. The
edit-intent waterfall sits inside the same try, so the policy's
FS_NOT_OBSERVED refusal is remediated too. Re-recorded the fs-policy-reject
keyless snapshot and the bilingual README pairs.
---
 .../snapshots/fs-policy-reject/session.jsonl  |  2 +-
 packages/fs/fs-policy/README.i18n.yaml        |  4 +-
 packages/fs/fs-policy/README.md               |  2 +-
 packages/fs/fs-policy/README.zh.md            |  2 +-
 packages/fs/tool-fs/README.i18n.yaml          |  4 +-
 packages/fs/tool-fs/README.md                 |  2 +-
 packages/fs/tool-fs/README.zh.md              |  2 +-
 packages/fs/tool-fs/src/edit.ts               | 14 +++-
 packages/fs/tool-fs/src/error.ts              | 34 ++++++++
 packages/fs/tool-fs/src/write.ts              |  6 +-
 packages/fs/tool-fs/tests/error.spec.ts       | 35 ++++++++
 packages/fs/tool-fs/tests/integration.spec.ts | 80 +++++++++++++++++++
 packages/fs/tool-fs/tests/tools.spec.ts       |  3 +-
 13 files changed, 174 insertions(+), 16 deletions(-)
 create mode 100644 packages/fs/tool-fs/src/error.ts
 create mode 100644 packages/fs/tool-fs/tests/error.spec.ts

diff --git a/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl b/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl
index 07d1408c9e..87cd7427f9 100644
--- a/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl
@@ -16,7 +16,7 @@
 {"type":"assistant/chunk","seq":78,"time":1785487602271,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":79,"time":1785487602271,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to use the edit tool to replace \"blue\" with \"green\" in settings.txt without reading the file first, and then reply with just \"DONE\"."},{"type":"tool-call","id":"call_00_x0zlnXl5JOxLrAYL9y7P0119","name":"edit","arguments":"{\"file_path\": \"settings.txt\", \"old_string\": \"blue\", \"new_string\": \"green\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"8bd34189-fb62-4106-9c25-b6022d48e059"},"usage":{"inputTokens":3132,"outputTokens":115,"cacheReadTokens":0,"reasoningTokens":36}},"sourceEventSeqs":[7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78],"surfaceOp":"append"}
 {"type":"tool/call","seq":80,"time":1785487602272,"data":{"turn":1,"step":1,"callId":"call_00_x0zlnXl5JOxLrAYL9y7P0119","name":"edit","arguments":"{\"file_path\": \"settings.txt\", \"old_string\": \"blue\", \"new_string\": \"green\"}"}}
-{"type":"tool/result","seq":81,"time":1785487602280,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_x0zlnXl5JOxLrAYL9y7P0119"},"content":[{"type":"tool-result","toolCallId":"call_00_x0zlnXl5JOxLrAYL9y7P0119","content":[{"type":"text","text":"Error: edit requires reading \"{{cwd}}/settings.txt\" first"}],"isError":true}],"role":"user","id":"c4018c31-b6fd-4f14-af3c-e609863bf501"},"error":{"name":"FsError","code":"FS_NOT_OBSERVED"}},"sourceEventSeqs":[80],"surfaceOp":"append"}
+{"type":"tool/result","seq":81,"time":1785487602280,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_x0zlnXl5JOxLrAYL9y7P0119"},"content":[{"type":"tool-result","toolCallId":"call_00_x0zlnXl5JOxLrAYL9y7P0119","content":[{"type":"text","text":"Error: edit requires reading \"{{cwd}}/settings.txt\" first — read the file, then retry"}],"isError":true}],"role":"user","id":"c4018c31-b6fd-4f14-af3c-e609863bf501"},"error":{"name":"FsError","code":"FS_NOT_OBSERVED"}},"sourceEventSeqs":[80],"surfaceOp":"append"}
 {"type":"step/end","seq":82,"time":1785487602280,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":83,"time":1785487602287,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":84,"time":1783611704931,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
diff --git a/packages/fs/fs-policy/README.i18n.yaml b/packages/fs/fs-policy/README.i18n.yaml
index 6690227dbc..5168b43d34 100644
--- a/packages/fs/fs-policy/README.i18n.yaml
+++ b/packages/fs/fs-policy/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/fs/fs-policy/README.md
-README.md: dc4e9377793570c80b8d71ec84196bebe7fe583a
-README.zh.md: aa0cb25899f5906ac9f531583ba48d01ad6095b4
+README.md: f6b3292bdc6e5565df0393a59c50d4e594921401
+README.zh.md: 2b30e6223719301df776b5d1cb7c674cb7ef7ff7
diff --git a/packages/fs/fs-policy/README.md b/packages/fs/fs-policy/README.md
index dc4e937779..f6b3292bdc 100644
--- a/packages/fs/fs-policy/README.md
+++ b/packages/fs/fs-policy/README.md
@@ -55,7 +55,7 @@ Because the plugin influences the world only through events, removing it does no
 
 #### What the model sees
 
-This plugin adds no prompt or schema. It rejects an edit without a prior read with code `FS_NOT_OBSERVED` and exact message `edit requires reading "<path>" first`. Guarded mutations whose observed version is stale propagate the provider-owned `FS_STALE_VERSION` error. [`dsh-tool-fs`](../tool-fs/README.md) owns the model-facing error wrapper; observation state is never shown.
+This plugin adds no prompt or schema. It rejects an edit without a prior read with code `FS_NOT_OBSERVED` and exact message `edit requires reading "<path>" first`. Guarded mutations whose observed version is stale propagate the provider-owned `FS_STALE_VERSION` error. [`dsh-tool-fs`](../tool-fs/README.md) owns the model-facing error wrapper, which appends the recovery instruction to `FS_STALE_VERSION` (`— re-read the file, then retry`) and `FS_NOT_OBSERVED` (`— read the file, then retry`) messages while preserving the code; observation state is never shown.
 
 #### Token effect
 
diff --git a/packages/fs/fs-policy/README.zh.md b/packages/fs/fs-policy/README.zh.md
index aa0cb25899..2b30e62237 100644
--- a/packages/fs/fs-policy/README.zh.md
+++ b/packages/fs/fs-policy/README.zh.md
@@ -55,7 +55,7 @@ await ctx.plugin(FsPolicy)
 
 #### 模型看到的内容
 
-该插件不添加提示词或 schema。编辑前未读取时，它会以代码 `FS_NOT_OBSERVED` 和精确消息 `edit requires reading "<path>" first` 拒绝。观察版本陈旧的防护变更会传播由提供方拥有的 `FS_STALE_VERSION` 错误。[`dsh-tool-fs`](../tool-fs/README.md)拥有面向模型的错误包装；观察状态绝不会显示。
+该插件不添加提示词或 schema。编辑前未读取时，它会以代码 `FS_NOT_OBSERVED` 和精确消息 `edit requires reading "<path>" first` 拒绝。观察版本陈旧的防护变更会传播由提供方拥有的 `FS_STALE_VERSION` 错误。[`dsh-tool-fs`](../tool-fs/README.md)拥有面向模型的错误包装，会为 `FS_STALE_VERSION` 消息追加恢复指令（`— re-read the file, then retry`）、为 `FS_NOT_OBSERVED` 消息追加恢复指令（`— read the file, then retry`），同时保留错误码；观察状态绝不会显示。
 
 #### Token 影响
 
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index fbe2e69043..8f462ed19b 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md
-README.md: a695d0ba8fb1d600689d2b68763e8423d1591da5
-README.zh.md: 5c600ab70b46da640637aec64efc1c0f0d0d54c0
+README.md: 246b1c8797e9a2ddc630724729edf8e2f1185bfc
+README.zh.md: 6cfc3d750b0f6ffc9ee886f4d0f058885bc19083
diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md
index a695d0ba8f..246b1c8797 100644
--- a/packages/fs/tool-fs/README.md
+++ b/packages/fs/tool-fs/README.md
@@ -136,7 +136,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-Failures are normalized as `Error: <message>`. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, and `offset <offset> is out of range for "<path>" (<total> lines)`; provider and policy templates are quoted in their package READMEs.
+Failures are normalized as `Error: <message>`. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, and `offset <offset> is out of range for "<path>" (<total> lines)`; provider and policy templates are quoted in their package READMEs. Guarded-mutation failures additionally carry their recovery instruction in the message, appended by this package's model-facing error wrapper: `FS_STALE_VERSION` (including a missing edit target) gets `— re-read the file, then retry`, `FS_NOT_OBSERVED` gets `— read the file, then retry`; the structured code is preserved.
 
 #### Token effect
 
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index 5c600ab70b..6cfc3d750b 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -136,7 +136,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 #### 模型看到的内容
 
-失败会规范化为 `Error: <message>`。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to <max>`、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "<path>": not found`、`cannot read "<path>": not a regular file` 和 `offset <offset> is out of range for "<path>" (<total> lines)`；提供方和策略模板在各自包的 README 中逐字列出。
+失败会规范化为 `Error: <message>`。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to <max>`、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "<path>": not found`、`cannot read "<path>": not a regular file` 和 `offset <offset> is out of range for "<path>" (<total> lines)`；提供方和策略模板在各自包的 README 中逐字列出。防护变更失败还会在消息中携带恢复指令，由本包面向模型的错误包装追加：`FS_STALE_VERSION`（包括编辑目标缺失）追加 `— re-read the file, then retry`，`FS_NOT_OBSERVED` 追加 `— read the file, then retry`；结构化错误码保持不变。
 
 #### Token 影响
 
diff --git a/packages/fs/tool-fs/src/edit.ts b/packages/fs/tool-fs/src/edit.ts
index 951c0b7b57..fcd04cb17c 100644
--- a/packages/fs/tool-fs/src/edit.ts
+++ b/packages/fs/tool-fs/src/edit.ts
@@ -11,6 +11,7 @@ import type { DiffCallView, DiffResultView, ToolResult } from '@deepseek-ai/dsh-
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta } from './diff.ts'
+import { remediateFsError } from './error.ts'
 import { sessionResolveOptions } from './session-cwd.ts'
 import type { FsSandboxSurface } from './sandbox.ts'
 
@@ -116,10 +117,13 @@ export function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void {
       const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath, sandboxPolicy?.workspaceRoot))
       // Single-slot decision: the policy plugin returns { version: vObserved } or
       // throws FS_NOT_OBSERVED; the bare default is undefined (unconditional edit).
-      // No stat — the bare default never manufactures a version basis.
-      const intent = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)
+      // No stat — the bare default never manufactures a version basis. The intent
+      // slot itself can throw FS_NOT_OBSERVED for an unread target, so it sits
+      // inside the try: both that refusal and the provider's guarded-mutation
+      // failure get the model-facing remedy below.
       let outcome
       try {
+        const intent = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)
         outcome = await ctx.fs.editText(
           target,
           { oldString: input.oldString, newString: input.newString, replaceAll: input.replaceAll },
@@ -128,8 +132,10 @@ export function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void {
           sandboxPolicy,
         )
       } catch (error: unknown) {
-        // A sandbox denial becomes the shared [sandbox: …] marker; any other error passes through.
-        throw sandbox.mapError(error, sandboxPolicy)
+        // A sandbox denial becomes the shared [sandbox: …] marker (the model
+        // recognizes it from bash); stale/not-observed failures gain their
+        // model-facing remedy; anything else passes through.
+        throw remediateFsError(sandbox.mapError(error, sandboxPolicy))
       }
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
diff --git a/packages/fs/tool-fs/src/error.ts b/packages/fs/tool-fs/src/error.ts
new file mode 100644
index 0000000000..e67616887f
--- /dev/null
+++ b/packages/fs/tool-fs/src/error.ts
@@ -0,0 +1,34 @@
+/**
+ * Model-facing remediation for guarded-mutation failures. The provider's
+ * `FS_STALE_VERSION` and `FS_NOT_OBSERVED` messages state the condition but
+ * not the only correct recovery (re-read / read the file), so this package
+ * appends the remedy at the model boundary; provider messages stay
+ * machine-oriented and unchanged.
+ * @module @deepseek-ai/dsh-tool-fs/src/error
+ */
+
+import { FsError } from '@deepseek-ai/dsh-fs'
+import type { FsErrorCode } from '@deepseek-ai/dsh-fs'
+
+/** The remedy appended to each remediable failure code's message. */
+const REMEDIES: Partial<Record<FsErrorCode, string>> = {
+  FS_STALE_VERSION: 're-read the file, then retry',
+  FS_NOT_OBSERVED: 'read the file, then retry',
+}
+
+/**
+ * Append the correct recovery instruction to a guarded-mutation failure's
+ * message. `FS_STALE_VERSION` (the file changed since this session's last
+ * observation, including a missing target) recovers only by re-reading;
+ * `FS_NOT_OBSERVED` (no prior read by this session) by reading. The `FsError`
+ * code is preserved so retry/permission/UI layers keep routing on it, and the
+ * original error chains as `cause`. Anything else passes through untouched.
+ * @param error - the caught value from a write/edit execution.
+ * @returns a remediated `FsError` for the two guarded-mutation codes, else the original value.
+ */
+export function remediateFsError(error: unknown): unknown {
+  if (!(error instanceof FsError)) return error
+  const remedy = REMEDIES[error.code]
+  if (!remedy) return error
+  return new FsError(`${error.message} — ${remedy}`, error.code, { cause: error })
+}
diff --git a/packages/fs/tool-fs/src/write.ts b/packages/fs/tool-fs/src/write.ts
index 37a6d67e59..56e2be488b 100644
--- a/packages/fs/tool-fs/src/write.ts
+++ b/packages/fs/tool-fs/src/write.ts
@@ -12,6 +12,7 @@ import type { FsWriteOutcome } from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta } from './diff.ts'
+import { remediateFsError } from './error.ts'
 import { sessionResolveOptions } from './session-cwd.ts'
 import type { FsSandboxSurface } from './sandbox.ts'
 
@@ -113,8 +114,9 @@ export function applyWriteTool(ctx: Context, sandbox: FsSandboxSurface): void {
         outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal, sandboxPolicy)
       } catch (error: unknown) {
         // A sandbox denial becomes the shared [sandbox: …] marker (the model
-        // recognizes it from bash); any other error passes through.
-        throw sandbox.mapError(error, sandboxPolicy)
+        // recognizes it from bash); stale/not-observed failures gain their
+        // model-facing remedy; anything else passes through.
+        throw remediateFsError(sandbox.mapError(error, sandboxPolicy))
       }
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
diff --git a/packages/fs/tool-fs/tests/error.spec.ts b/packages/fs/tool-fs/tests/error.spec.ts
new file mode 100644
index 0000000000..671eb32d9d
--- /dev/null
+++ b/packages/fs/tool-fs/tests/error.spec.ts
@@ -0,0 +1,35 @@
+/**
+ * Unit tests for the model-facing error remediation: the remedy appended to
+ * guarded-mutation failures, code preservation, and passthrough behavior.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { FsError } from '@deepseek-ai/dsh-fs'
+import { remediateFsError } from '../src/error.ts'
+
+describe('remediateFsError', () => {
+  it('appends the re-read remedy to FS_STALE_VERSION, preserving the code and chaining the cause', () => {
+    const original = new FsError('cannot edit "x": file changed since it was read', 'FS_STALE_VERSION')
+    const remedied = remediateFsError(original) as FsError
+    expect(remedied).toBeInstanceOf(FsError)
+    expect(remedied.message).toBe('cannot edit "x": file changed since it was read — re-read the file, then retry')
+    expect(remedied.code).toBe('FS_STALE_VERSION')
+    expect(remedied.cause).toBe(original)
+  })
+
+  it('appends the read remedy to FS_NOT_OBSERVED', () => {
+    const remedied = remediateFsError(new FsError('edit requires reading "x" first', 'FS_NOT_OBSERVED')) as FsError
+    expect(remedied.message).toBe('edit requires reading "x" first — read the file, then retry')
+    expect(remedied.code).toBe('FS_NOT_OBSERVED')
+  })
+
+  it('leaves other FsError codes untouched', () => {
+    const original = new FsError('no match anywhere', 'FS_EDIT_NOT_FOUND')
+    expect(remediateFsError(original)).toBe(original)
+  })
+
+  it('leaves non-FsError values untouched', () => {
+    const original = new Error('boom')
+    expect(remediateFsError(original)).toBe(original)
+  })
+})
diff --git a/packages/fs/tool-fs/tests/integration.spec.ts b/packages/fs/tool-fs/tests/integration.spec.ts
index c835baebb9..3482b38569 100644
--- a/packages/fs/tool-fs/tests/integration.spec.ts
+++ b/packages/fs/tool-fs/tests/integration.spec.ts
@@ -71,6 +71,9 @@ describe('default deployment (with dsh-fs-policy)', () => {
       const result = await call('write', { file_path: 'a.txt', content: 'clobber' })
       expect(result.isError).toBe(true)
       expect(result.error).toMatchObject({ info: { code: 'FS_NOT_OBSERVED' } })
+      // The model-facing text names the remedy, not just the condition.
+      expect(text(result)).toContain('without reading it first')
+      expect(text(result)).toContain('read the file, then retry')
       expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('original')
     })
 
@@ -89,6 +92,23 @@ describe('default deployment (with dsh-fs-policy)', () => {
       const result = await call('write', { file_path: 'a.txt', content: 'replaced' })
       expect(result.isError).toBe(true)
       expect(result.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
+      // The model-facing text names the remedy, not just the condition.
+      expect(text(result)).toContain('file changed since it was read')
+      expect(text(result)).toContain('re-read the file, then retry')
+    })
+
+    it('the stale remedy is actionable: re-reading the changed file unblocks the retried write', async () => {
+      await writeFile(join(dir, 'a.txt'), 'original')
+      await call('read', { file_path: 'a.txt' })
+      await writeFile(join(dir, 'a.txt'), 'changed-externally') // out-of-band change
+      const stale = await call('write', { file_path: 'a.txt', content: 'replaced' })
+      expect(stale.isError).toBe(true)
+      expect(stale.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
+      // Follow the remedy: re-read (refreshes the observed version), then retry.
+      expect((await call('read', { file_path: 'a.txt' })).isError).toBe(false)
+      const retried = await call('write', { file_path: 'a.txt', content: 'replaced' })
+      expect(retried.isError).toBe(false)
+      expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('replaced')
     })
   })
 
@@ -131,6 +151,9 @@ describe('default deployment (with dsh-fs-policy)', () => {
       const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
       expect(result.isError).toBe(true)
       expect(result.error).toMatchObject({ info: { code: 'FS_NOT_OBSERVED' } })
+      // The policy's refusal reaches the model with the read remedy appended.
+      expect(text(result)).toContain('edit requires reading')
+      expect(text(result)).toContain('read the file, then retry')
       expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('hello world')
     })
 
@@ -155,6 +178,23 @@ describe('default deployment (with dsh-fs-policy)', () => {
       const result = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
       expect(result.isError).toBe(true)
       expect(result.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
+      // The model-facing text names the remedy, not just the condition.
+      expect(text(result)).toContain('file changed since it was read')
+      expect(text(result)).toContain('re-read the file, then retry')
+    })
+
+    it('the stale remedy is actionable: re-reading the changed file unblocks the retried edit', async () => {
+      await writeFile(join(dir, 'a.txt'), 'hello world')
+      await call('read', { file_path: 'a.txt' })
+      await writeFile(join(dir, 'a.txt'), 'hello brave world') // out-of-band change
+      const stale = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
+      expect(stale.isError).toBe(true)
+      expect(stale.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
+      // Follow the remedy: re-read (refreshes the observed version), then retry.
+      expect((await call('read', { file_path: 'a.txt' })).isError).toBe(false)
+      const retried = await call('edit', { file_path: 'a.txt', old_string: 'world', new_string: 'there' })
+      expect(retried.isError).toBe(false)
+      expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('hello brave there')
     })
 
     it('rejects an ambiguous match without replace_all', async () => {
@@ -194,6 +234,43 @@ describe('default deployment (with dsh-fs-policy)', () => {
     })
   })
 
+  describe('deleted observed target (fail-closed corner)', () => {
+    it('a deleted observed file stays un-writable and un-editable in-session: the remedy cannot unblock it', async () => {
+      await writeFile(join(dir, 'a.txt'), 'original')
+      await call('read', { file_path: 'a.txt' })
+      await rm(join(dir, 'a.txt')) // out-of-band deletion
+
+      // Edit of the missing target: stale (the missing-target path shares the
+      // stale code and the re-read remedy).
+      const edit = await call('edit', { file_path: 'a.txt', old_string: 'original', new_string: 'x' })
+      expect(edit.isError).toBe(true)
+      expect(edit.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
+
+      // Re-reading the missing file FAILS with FS_NOT_FOUND and records no
+      // observation, so the retried edit fails identically: the observed entry
+      // is never cleared for a deleted target.
+      const reread = await call('read', { file_path: 'a.txt' })
+      expect(reread.isError).toBe(true)
+      expect(reread.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+      const retriedEdit = await call('edit', { file_path: 'a.txt', old_string: 'original', new_string: 'x' })
+      expect(retriedEdit.isError).toBe(true)
+      expect(retriedEdit.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
+
+      // Write cannot recreate it either: the stale observation still forces
+      // replaceIfVersion, which rejects a missing target ("file no longer exists").
+      const write = await call('write', { file_path: 'a.txt', content: 'fresh' })
+      expect(write.isError).toBe(true)
+      expect(write.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
+
+      // The dead end lifts once the file exists again and is freshly observed.
+      await writeFile(join(dir, 'a.txt'), 'restored')
+      expect((await call('read', { file_path: 'a.txt' })).isError).toBe(false)
+      const recovered = await call('write', { file_path: 'a.txt', content: 'fresh' })
+      expect(recovered.isError).toBe(false)
+      expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('fresh')
+    })
+  })
+
   describe('stat budget', () => {
     it('read stats once; write and edit never stat in the tool (the gate stats zero too)', async () => {
       await writeFile(join(dir, 'a.txt'), 'hello world')
@@ -264,6 +341,9 @@ describe('bare provider (no dsh-fs-policy)', () => {
     const result = await call('edit', { file_path: 'missing.txt', old_string: 'a', new_string: 'b' })
     expect(result.isError).toBe(true)
     expect(result.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
+    // Even without policy, the stale text carries the re-read remedy.
+    expect(text(result)).toContain('file changed since it was read')
+    expect(text(result)).toContain('re-read the file, then retry')
   })
 
   it('edit still enforces literal-match codes (FS_EDIT_NOT_FOUND), unrelated to freshness', async () => {
diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts
index 914a1bf7de..ad01237c2b 100644
--- a/packages/fs/tool-fs/tests/tools.spec.ts
+++ b/packages/fs/tool-fs/tests/tools.spec.ts
@@ -397,12 +397,13 @@ describe('write tool', () => {
     expect(text(result)).toContain('file_path must be a non-empty string')
   })
 
-  it('propagates a backend FsError as an isError result carrying its code', async () => {
+  it('propagates a backend FsError as an isError result carrying its code and remedy', async () => {
     const { ctx, fs } = await setup()
     fs.rejectWith = new FsError('blocked', 'FS_STALE_VERSION')
     const result = await call(ctx, 'write', { file_path: 'a.txt', content: 'hi' })
     expect(result.isError).toBe(true)
     expect(result.error).toMatchObject({ info: { name: 'FsError', code: 'FS_STALE_VERSION' } })
+    expect(text(result)).toContain('re-read the file, then retry')
   })
 })
 

From 044df0e0c8b30f1dab97db8e473317dc66b060c0 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Mon, 3 Aug 2026 19:49:38 +0800
Subject: [PATCH 015/516] docs(notes): record model-facing error remedy
 decision

The tool-fs error wrapper decision: guarded-mutation failures gain their
recovery instruction at the model boundary while the provider messages and
structured codes stay unchanged; includes the deleted-target fail-closed
corner.
---
 .../2026-08-03-fs-tool-error-remedy.i18n.yaml |  6 ++++
 .../2026-08-03-fs-tool-error-remedy.md        | 32 +++++++++++++++++++
 .../2026-08-03-fs-tool-error-remedy.zh.md     | 32 +++++++++++++++++++
 3 files changed, 70 insertions(+)
 create mode 100644 .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md

diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
new file mode 100644
index 0000000000..98500c284e
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.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-08-03-fs-tool-error-remedy.md
+2026-08-03-fs-tool-error-remedy.md: f227c31365725652b130e097d70c79d3daab3684
+2026-08-03-fs-tool-error-remedy.zh.md: 11acd0cf48924833ced91591d5ea1424735969cd
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
new file mode 100644
index 0000000000..f227c31365
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
@@ -0,0 +1,32 @@
+# Agent Note: Guarded-mutation errors append the recovery instruction at the model boundary
+
+Status: implemented
+
+English | [中文](2026-08-03-fs-tool-error-remedy.zh.md)
+
+## Problem
+
+Guarded `write` and `edit` failures reach the model with messages that state the condition but not the only correct recovery: `FS_STALE_VERSION` ("file changed since it was read") and `FS_NOT_OBSERVED` ("edit requires reading … first"). The model must guess that the recovery is a re-read (or a first read) followed by a retry, and the retry/permission/UI layers that route on the structured code see the same message text. The provider-owned messages are part of the storage seam's machine-oriented vocabulary ([filesystem capability seam](../architecture/2026-06-17-filesystem-capability-seam.md)), so the remedy cannot live there without leaking model-facing wording into every consumer of `FsError`.
+
+## Decision
+
+`dsh-tool-fs` owns a model-facing error wrapper, `remediateFsError` in `src/error.ts`, applied in `write.ts` and `edit.ts` after the sandbox denial mapping. It appends the recovery instruction to the two guarded-mutation codes and passes everything else through untouched:
+
+- `FS_STALE_VERSION` (including a missing edit target, which shares the stale code) gains `— re-read the file, then retry`.
+- `FS_NOT_OBSERVED` gains `— read the file, then retry`.
+
+The structured `FsError` code is preserved so retry/permission/UI layers keep routing on it, and the original error chains as `cause`. Provider messages stay machine-oriented and unchanged.
+
+In `edit.ts` the `fs/edit-intent` waterfall now sits inside the same `try` as the provider mutation, so the policy plugin's `FS_NOT_OBSERVED` refusal thrown from the intent slot also receives the remedy — both refusal paths reach the model with the same recovery wording.
+
+## Alternatives considered
+
+- **Append the remedy to the provider messages in `dsh-fs` / `dsh-fs-local`.** Rejected because those messages are machine-oriented seam vocabulary consumed by retry, permission, and UI layers as well as the model surface; model-facing wording belongs at the model boundary, where `dsh-tool-fs` already owns result formatting ([filesystem capability seam](../architecture/2026-06-17-filesystem-capability-seam.md)).
+- **Add the recovery to prompt guidance instead.** Rejected because the failure arrives mid-task; a static instruction does not reliably reach the retry decision, while the error message is present exactly when the model must act.
+- **Signal the remedy with a new `FsError` code.** Rejected because the two failures are the same conditions retry layers already handle; splitting the code would fork routing on identical semantics.
+
+## Consequences
+
+Model-visible text for the two codes changes; the `fs-policy-reject` keyless snapshot is re-recorded, and the READMEs of `dsh-tool-fs` and `dsh-fs-policy` pin the exact appended text. Unit tests cover the wrapper directly (remedy text, code preservation, cause chaining, passthrough of other codes and non-`FsError` values) and the assembled tool paths assert the remedy reaches the model for both codes.
+
+The remedy is not a promise: a deleted observed target cannot be unblocked, because re-reading a missing file fails with `FS_NOT_FOUND` and records no observation. That dead end is pinned fail-closed in the integration tests — the retried mutation fails identically until the target exists again and is freshly observed.
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
new file mode 100644
index 0000000000..11acd0cf48
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
@@ -0,0 +1,32 @@
+# Agent Note: Guarded-mutation errors append the recovery instruction at the model boundary
+
+Status: implemented
+
+[English](2026-08-03-fs-tool-error-remedy.md) | 中文
+
+## Problem
+
+受防护的 `write` 与 `edit` 失败以只陈述条件、不给出唯一正确恢复方式的消息到达模型：`FS_STALE_VERSION`（"file changed since it was read"）与 `FS_NOT_OBSERVED`（"edit requires reading … first"）。模型必须自行猜测恢复方式是重新读取（或首次读取）后重试，而基于结构化错误码路由的重试/权限/UI 层看到的也是同一段消息文本。提供方拥有的消息属于存储接缝的面向机器词汇（[filesystem capability seam](../architecture/2026-06-17-filesystem-capability-seam.md)），因此恢复指令不能放在那里，否则会把面向模型的措辞泄漏给 `FsError` 的每个消费者。
+
+## Decision
+
+`dsh-tool-fs` 拥有一个面向模型的错误包装 `remediateFsError`（位于 `src/error.ts`），在 `write.ts` 与 `edit.ts` 中于沙箱拒绝映射之后应用。它为两个受防护变更错误码追加恢复指令，其余错误原样透传：
+
+- `FS_STALE_VERSION`（包括缺失的编辑目标——它与陈旧错误共用同一错误码）追加 `— re-read the file, then retry`。
+- `FS_NOT_OBSERVED` 追加 `— read the file, then retry`。
+
+结构化 `FsError` 错误码保持不变，使重试/权限/UI 层继续基于它路由；原始错误作为 `cause` 链入。提供方消息保持面向机器且不变。
+
+在 `edit.ts` 中，`fs/edit-intent` waterfall 现在与提供方变更位于同一个 `try` 内，因此策略插件从 intent 槽抛出的 `FS_NOT_OBSERVED` 拒绝也会获得恢复指令——两条拒绝路径都以相同的恢复措辞到达模型。
+
+## Alternatives considered
+
+- **在 `dsh-fs` / `dsh-fs-local` 的提供方消息中追加恢复指令。** 被拒绝：这些消息是面向机器的接缝词汇，除模型表面外还被重试、权限与 UI 层消费；面向模型的措辞应位于模型边界，即 `dsh-tool-fs` 已经拥有结果格式化之处（[filesystem capability seam](../architecture/2026-06-17-filesystem-capability-seam.md)）。
+- **改为在提示词引导中加入恢复方式。** 被拒绝：失败发生在任务中途；静态指令无法可靠地影响重试决策，而错误消息恰好在模型必须行动时出现。
+- **用新的 `FsError` 错误码表达恢复指令。** 被拒绝：这两种失败本就是重试层已处理的相同条件；拆分错误码会让语义相同的路由分叉。
+
+## Consequences
+
+两个错误码的模型可见文本发生变化；`fs-policy-reject` 无密钥快照被重新录制，`dsh-tool-fs` 与 `dsh-fs-policy` 的 README 逐字固定追加后的文本。单元测试直接覆盖包装器（恢复指令文本、错误码保留、cause 链、其他错误码与非 `FsError` 值的透传），组装后的工具路径断言两个错误码的恢复指令都到达模型。
+
+恢复指令不是承诺：已删除的观察目标无法被解除阻塞，因为重新读取缺失文件会以 `FS_NOT_FOUND` 失败且不记录观察。这一死胡同在集成测试中以 fail-closed 方式固定——在目标重新存在并被新鲜观察之前，重试的变更以相同方式失败。

From cd6bd5c1882b455df0574f2d3dc260f3cdd67419 Mon Sep 17 00:00:00 2001
From: fz <fz@dsh.dev>
Date: Tue, 4 Aug 2026 11:48:34 +0800
Subject: [PATCH 016/516] fix(llm): honor DeepSeek SSE keep-alives

---
 ...-21-bounded-llm-request-recovery.i18n.yaml |  4 +--
 ...2026-06-21-bounded-llm-request-recovery.md |  4 +--
 ...6-06-21-bounded-llm-request-recovery.zh.md |  4 +--
 .../fixtures/deepseek-defaults.cordis.yml     |  1 +
 .../headless-agent/tests/headless.snapshot.ts | 23 +++++++++----
 packages/llm/llm-deepseek/README.i18n.yaml    |  4 +--
 packages/llm/llm-deepseek/README.md           |  2 +-
 packages/llm/llm-deepseek/README.zh.md        |  2 +-
 packages/llm/llm-deepseek/src/adapter.ts      | 11 ++++--
 packages/llm/llm-deepseek/src/sse.ts          | 19 +++++++----
 .../llm/llm-deepseek/tests/adapter.spec.ts    | 34 +++++++++++++++++++
 packages/llm/llm-deepseek/tests/sse.spec.ts   | 10 ++++++
 packages/util/timeout/README.i18n.yaml        |  4 +--
 packages/util/timeout/README.md               |  4 +--
 packages/util/timeout/README.zh.md            |  4 +--
 packages/util/timeout/src/index.ts            | 17 ++++++++--
 packages/util/timeout/tests/timeout.spec.ts   | 22 ++++++++++++
 17 files changed, 134 insertions(+), 35 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
index bf6f030683..d527bb9e7b 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.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 .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
-2026-06-21-bounded-llm-request-recovery.md: 24725dcf300cf69e9cc72580d0c8afe937d4e2b9
-2026-06-21-bounded-llm-request-recovery.zh.md: 5f03a65b00be8d3349addce82e4f3faa2af1fe7e
+2026-06-21-bounded-llm-request-recovery.md: 122f30118ebe3f213a887e56a9d3505e78b23070
+2026-06-21-bounded-llm-request-recovery.zh.md: 8af62cef952eba929dd770df15fdc0666f575666
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
index 24725dcf30..122f30118e 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
@@ -74,9 +74,9 @@ Adapters perform one provider request per `stream()` call. The pi-ai adapter rem
 
 ### Bound stalled streams where they can be stopped
 
-Each adapter exposes a validated `streamIdleTimeoutMs` configuration field with the five-minute prior-art default cited above. The interval is capped at Node's maximum timer delay so it cannot be clamped to one millisecond. It covers each outstanding iterator `next()` from demand to the next valid `StreamChunk`; time a consumer spends between `next()` calls is not provider idle time.
+Each adapter exposes a validated `streamIdleTimeoutMs` configuration field with the five-minute prior-art default cited above. The interval is capped at Node's maximum timer delay so it cannot be clamped to one millisecond. It covers each outstanding iterator `next()` from demand to adapter-recognized provider activity; time a consumer spends between `next()` calls is not provider idle time. DeepSeek SSE comments count as transport activity but never become `StreamChunk` values or session-log events.
 
-`@deepseek-ai/dsh-timeout` exposes a rearmable idle-watchdog primitive. One stable local `AbortController` is fused with the caller signal and passed to the transport for the whole adapter call; each outstanding `next()` arms the watchdog, resolution disarms it, and the next demand rearms it. Timeout aborts that stable controller with a capability-owned `TimeoutReason`, and `finally` clears the timer. The adapter classifies its watchdog as `TIMEOUT` and an earlier upstream abort as `ABORTED`. The existing one-shot `deadline()` is not presented as a sliding timer.
+`@deepseek-ai/dsh-timeout` exposes a rearmable idle-watchdog primitive. One stable local `AbortController` is fused with the caller signal and passed to the transport for the whole adapter call; each outstanding `next()` arms the watchdog, resolution disarms it, and the next demand rearms it. Out-of-band transport activity calls `pulse()` to rearm an outstanding demand without yielding a value. Timeout aborts that stable controller with a capability-owned `TimeoutReason`, and `finally` clears the timer. The adapter classifies its watchdog as `TIMEOUT` and an earlier upstream abort as `ABORTED`. The existing one-shot `deadline()` is not presented as a sliding timer.
 
 Boundary tests prove termination at both actual transports. The hand-written adapter aborts its fetch/reader, and the pi-ai adapter maps the stable signal through the SDK and proves the SDK closes the response. A timer that merely rejects a consumer promise while leaving the request running does not satisfy the contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
index 5f03a65b00..8af62cef95 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
@@ -74,9 +74,9 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 
 ### 在能够终止停滞流的位置施加边界
 
-每个适配器都公开一个经过验证的 `streamIdleTimeoutMs` 配置字段，默认值采用上文引用的五分钟先例。该间隔不超过 Node 的最大定时器延迟，因此不会被钳制为 1 毫秒。它覆盖每个尚未完成的迭代器 `next()`：从消费方请求下一项开始，到下一条有效 `StreamChunk` 到达为止；消费方在两次 `next()` 调用之间花费的时间不属于提供方空闲时间。
+每个适配器都公开一个经过验证的 `streamIdleTimeoutMs` 配置字段，默认值采用上文引用的五分钟先例。该间隔不超过 Node 的最大定时器延迟，因此不会被钳制为 1 毫秒。它覆盖每个尚未完成的迭代器 `next()`：从消费方请求下一项开始，到适配器识别到提供方活动为止；消费方在两次 `next()` 调用之间花费的时间不属于提供方空闲时间。DeepSeek SSE（Server-Sent Events）注释计为传输活动，但绝不会成为 `StreamChunk` 值或会话日志事件。
 
-`@deepseek-ai/dsh-timeout` 公开一个可重新布防的空闲看门狗原语。一个稳定的局部 `AbortController` 会与调用方信号融合，并在整个适配器调用期间传给传输层；每个尚未完成的 `next()` 都会布防看门狗，该调用完成时解除布防，下一次请求数据时再重新布防。超时会使用能力自身拥有的 `TimeoutReason` 中止这个稳定控制器，`finally` 则会清除定时器。适配器将自身看门狗归类为 `TIMEOUT`，将更早发生的上游中止归类为 `ABORTED`。现有的一次性 `deadline()` 不会被描述为滑动计时器。
+`@deepseek-ai/dsh-timeout` 公开一个可重新布防的空闲看门狗原语。一个稳定的局部 `AbortController` 会与调用方信号融合，并在整个适配器调用期间传给传输层；每个尚未完成的 `next()` 都会布防看门狗，该调用完成时解除布防，下一次请求数据时再重新布防。带外传输活动会调用 `pulse()`，在不产生值的情况下为尚未完成的需求重新布防。超时会使用能力自身拥有的 `TimeoutReason` 中止这个稳定控制器，`finally` 则会清除定时器。适配器将自身看门狗归类为 `TIMEOUT`，将更早发生的上游中止归类为 `ABORTED`。现有的一次性 `deadline()` 不会被描述为滑动计时器。
 
 边界测试证明两个实际传输层都能终止。手写适配器会中止其 fetch／reader，pi-ai 适配器会把稳定信号映射到 SDK，并证明 SDK 会关闭响应。如果定时器只拒绝消费方 promise，却让请求继续运行，就不满足此契约。
 
diff --git a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
index cd472f737d..829af9f813 100644
--- a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
@@ -8,6 +8,7 @@
           apiKey: snapshot-key
           baseURL: !!js process.env.DSH_SNAPSHOT_BASE_URL
           thinking: disabled
+          streamIdleTimeoutMs: 100
       - id: cli-agent
         config:
           provider: deepseek-official
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 8b48165a83..fd1bbd3086 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -66,12 +66,21 @@ async function deepseekDefaultsServer(): Promise<DeepSeekDefaultsServer> {
     request.on('end', () => {
       requests.push(JSON.parse(body) as JsonObject)
       response.writeHead(200, { 'content-type': 'text/event-stream' })
-      response.end([
-        'data: {"choices":[{"delta":{"content":"DEFAULTS_OK"}}]}',
-        'data: {"choices":[{"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":3,"completion_tokens":1}}',
-        'data: [DONE]',
-        '',
-      ].join('\n\n'))
+      let keepAlives = 3
+      const write = (): void => {
+        if (keepAlives-- > 0) {
+          response.write(': keep-alive\n\n')
+          setTimeout(write, 60)
+          return
+        }
+        response.end([
+          'data: {"choices":[{"delta":{"content":"DEFAULTS_OK"}}]}',
+          'data: {"choices":[{"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":3,"completion_tokens":1}}',
+          'data: [DONE]',
+          '',
+        ].join('\n\n'))
+      }
+      setTimeout(write, 60)
     })
   })
   await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
@@ -297,7 +306,7 @@ describe('headless stream-json snapshots', () => {
     `)
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
-  it('logs and sends the DeepSeek adapter maxTokens default through the one-shot app', async () => {
+  it('keeps provider comments alive and sends DeepSeek defaults through the one-shot app', async () => {
     const server = await deepseekDefaultsServer()
     try {
       const result = await runLoaderSmoke({
diff --git a/packages/llm/llm-deepseek/README.i18n.yaml b/packages/llm/llm-deepseek/README.i18n.yaml
index 45d9cee054..cb18c83eff 100644
--- a/packages/llm/llm-deepseek/README.i18n.yaml
+++ b/packages/llm/llm-deepseek/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/llm/llm-deepseek/README.md
-README.md: 020aa65073495526be3f32912b7cd06667c52a2e
-README.zh.md: 4c655e90ba00340c056f6ac16159621f7a8c1ddb
+README.md: 2ecdb4330e5871bbaf0da6fc583083a06c935486
+README.zh.md: 63eb7be330806b668e12867ed906d0d88acaff1f
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index 020aa65073..2ecdb4330e 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -46,7 +46,7 @@ The same exact-model result exposes ordered `off`, `high`, and `max` efforts und
 
 `thinking: disabled` is a deployment lock that publishes only `off` with `off` as its default. Omitting `reasoningEffort` or configuring it as `off` is valid; configuring `high` or `max` fails plugin loading, and a direct per-request attempt to enable thinking fails before network I/O. A request with `GenerateOptions.purpose: 'session-title'` also forces thinking disabled and omits the already-resolved effort, reserving its bounded output for visible title text without changing conversation or compaction defaults.
 
-`streamIdleTimeoutMs` bounds each outstanding provider read, including the initial `fetch`, without counting time the consumer spends between chunks. One stable abort signal reaches the request and body reader for the whole call; expiry stops the transport and throws `LlmError('TIMEOUT')`, while an earlier caller abort throws `LlmError('ABORTED')`. The adapter makes exactly one provider request per `stream()` call; it registers the configured policy as provider metadata, and `dsh-llm-retry` separately executes it at durable agent-step boundaries.
+`streamIdleTimeoutMs` bounds each outstanding provider read, including the initial `fetch`, without counting time the consumer spends between chunks. DeepSeek SSE comments rearm an outstanding read as transport activity but never become `StreamChunk` values or session-log events. One stable abort signal reaches the request and body reader for the whole call; expiry stops the transport and throws `LlmError('TIMEOUT')`, while an earlier caller abort throws `LlmError('ABORTED')`. The adapter makes exactly one provider request per `stream()` call; it registers the configured policy as provider metadata, and `dsh-llm-retry` separately executes it at durable agent-step boundaries.
 
 ## Dynamic configuration (settings + credentials)
 
diff --git a/packages/llm/llm-deepseek/README.zh.md b/packages/llm/llm-deepseek/README.zh.md
index 4c655e90ba..63eb7be330 100644
--- a/packages/llm/llm-deepseek/README.zh.md
+++ b/packages/llm/llm-deepseek/README.zh.md
@@ -46,7 +46,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
 
 `thinking: disabled` 是部署锁定：它只公布 `off`，并以 `off` 为默认值。省略 `reasoningEffort` 或将其配置为 `off` 均有效；配置 `high` 或 `max` 会使插件加载失败，直接按请求启用思考也会在网络 I/O 前失败。携带 `GenerateOptions.purpose: 'session-title'` 的请求也会强制禁用思考并省略已解析的推理强度，将有界输出保留给可见标题文本，不改变会话或压缩（compaction）默认值。
 
-`streamIdleTimeoutMs` 会限制每次未完成提供方读取，包括初始 `fetch`，但不计入消费方在分片间花费的时间。同一个稳定的 abort 信号会在整个调用期间传递给请求与 body reader；过期会停止传输并抛出 `LlmError('TIMEOUT')`，较早的调用方 abort 则抛出 `LlmError('ABORTED')`。适配器每次 `stream()` 调用恰好发起一次提供方请求；它把已配置策略注册为提供方元数据，再由 `dsh-llm-retry` 在持久化的 agent（智能体）步骤边界单独执行该策略。
+`streamIdleTimeoutMs` 会限制每次未完成提供方读取，包括初始 `fetch`，但不计入消费方在分片间花费的时间。DeepSeek SSE 注释会作为传输活动使尚未完成的读取重新布防，但绝不会成为 `StreamChunk` 值或会话日志事件。同一个稳定的 abort 信号会在整个调用期间传递给请求与 body reader；过期会停止传输并抛出 `LlmError('TIMEOUT')`，较早的调用方 abort 则抛出 `LlmError('ABORTED')`。适配器每次 `stream()` 调用恰好发起一次提供方请求；它把已配置策略注册为提供方元数据，再由 `dsh-llm-retry` 在持久化的 agent（智能体）步骤边界单独执行该策略。
 
 ## 动态配置（settings + credentials）
 
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 85985c41d8..c5f9655fa1 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -215,7 +215,13 @@ export class DeepSeekAdapter extends LlmAdapter {
       ? consumer.signal
       : AbortSignal.any([options.signal, consumer.signal])
     using watchdog = idleWatchdog(upstream, connection.streamIdleTimeoutMs, STREAM_IDLE_TIMEOUT_CODE)
-    const iterator = this.request(options, watchdog.signal, connection, apiKey)[Symbol.asyncIterator]()
+    const iterator = this.request(
+      options,
+      watchdog.signal,
+      connection,
+      apiKey,
+      () => { watchdog.pulse() },
+    )[Symbol.asyncIterator]()
     let exhausted = false
     try {
       while (true) {
@@ -256,6 +262,7 @@ export class DeepSeekAdapter extends LlmAdapter {
     signal: AbortSignal,
     connection: DeepSeekConnectionOptions,
     apiKey: string,
+    onComment: () => void,
   ): AsyncIterable<StreamChunk> {
     const body = serializeRequest(options, connection.defaults)
     // Prepared outside the try so the TRANSPORT label below covers exactly the
@@ -321,6 +328,6 @@ export class DeepSeekAdapter extends LlmAdapter {
       throw new LlmError('DeepSeek API returned no response body', 'EMPTY_RESPONSE')
     }
 
-    yield* translate(parseSse(response.body))
+    yield* translate(parseSse(response.body, onComment))
   }
 }
diff --git a/packages/llm/llm-deepseek/src/sse.ts b/packages/llm/llm-deepseek/src/sse.ts
index a8807a857c..9126a18940 100644
--- a/packages/llm/llm-deepseek/src/sse.ts
+++ b/packages/llm/llm-deepseek/src/sse.ts
@@ -1,11 +1,12 @@
 /**
  * Decode an SSE byte stream into event `data` payloads. Framing — chunk
  * reassembly, UTF-8/CRLF/BOM handling, comment and non-data field skipping,
- * multi-`data:` joining — is `eventsource-parser`'s; this module keeps only
- * the DeepSeek protocol: the literal `[DONE]` is yielded so the caller owns
- * final flushing, and EOF before it raises {@link LlmError}. Framing is
- * spec-strict: an event dispatches only on its blank-line terminator, so an
- * unterminated tail at EOF is truncation, not a flushable payload.
+ * multi-`data:` joining — is `eventsource-parser`'s. Comments are reported
+ * only through an optional transport-activity callback. This module keeps the
+ * DeepSeek protocol: the literal `[DONE]` is yielded so the caller owns final
+ * flushing, and EOF before it raises {@link LlmError}. Framing is spec-strict:
+ * an event dispatches only on its blank-line terminator, so an unterminated
+ * tail at EOF is truncation, not a flushable payload.
  *
  * @module dsh-llm-deepseek/sse
  */
@@ -21,12 +22,16 @@ export const DONE = '[DONE]'
  * value and returns; throws `LlmError('STREAM_CLOSED')` when the stream ends
  * without it (truncated response — the model call cannot be trusted).
  * @param stream - raw SSE bytes; reads may split anywhere, including mid-UTF-8 sequence.
+ * @param onComment - optional transport-activity callback; comments never enter the yielded payload stream.
  * @returns each event's data payload in arrival order, the `[DONE]` sentinel last.
  */
-export async function* parseSse(stream: ReadableStream<BufferSource>): AsyncGenerator<string> {
+export async function* parseSse(
+  stream: ReadableStream<BufferSource>,
+  onComment?: (comment: string) => void,
+): AsyncGenerator<string> {
   const events = stream
     .pipeThrough(new TextDecoderStream())
-    .pipeThrough(new EventSourceParserStream())
+    .pipeThrough(new EventSourceParserStream({ onComment }))
   for await (const { data } of events) {
     yield data
     if (data === DONE) return
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index ec4a271f15..8240dea7e6 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -545,6 +545,40 @@ describe('DeepSeekAdapter against a mock server', () => {
       fetchSpy.mockRestore()
     }
   })
+
+  it('keeps an idle provider read alive through SSE comments', async () => {
+    vi.useFakeTimers()
+    const encoder = new TextEncoder()
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(() => {
+      const body = new ReadableStream<Uint8Array>({
+        start(controller) {
+          setTimeout(() => { controller.enqueue(encoder.encode(': keep-alive\n\n')) }, 75)
+          setTimeout(() => { controller.enqueue(encoder.encode(': keep-alive\n\n')) }, 150)
+          setTimeout(() => {
+            controller.enqueue(encoder.encode(textEvents.map(event => `data: ${event}\n\n`).join('')))
+            controller.close()
+          }, 225)
+        },
+      })
+      return Promise.resolve(new Response(body, { status: 200 }))
+    })
+    const adapter = adapterOf({ baseURL: 'https://example.invalid', streamIdleTimeoutMs: 100 })
+    try {
+      const chunks: string[] = []
+      const drain = (async () => {
+        for await (const chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) {
+          chunks.push(chunk.type)
+        }
+      })()
+      await vi.advanceTimersByTimeAsync(75)
+      await vi.advanceTimersByTimeAsync(75)
+      await vi.advanceTimersByTimeAsync(75)
+      await expect(drain).resolves.toBeUndefined()
+      expect(chunks).toEqual(['block-start', 'text-delta', 'block-end', 'usage', 'finish'])
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
 })
 
 describe('plugin registration and config', () => {
diff --git a/packages/llm/llm-deepseek/tests/sse.spec.ts b/packages/llm/llm-deepseek/tests/sse.spec.ts
index 7ebb494a4d..67160d8079 100644
--- a/packages/llm/llm-deepseek/tests/sse.spec.ts
+++ b/packages/llm/llm-deepseek/tests/sse.spec.ts
@@ -31,6 +31,16 @@ describe('parseSse', () => {
     expect(events).toEqual(['{"a":1}', DONE])
   })
 
+  it('reports comments out of band without yielding them', async () => {
+    const comments: string[] = []
+    const events = await collect(parseSse(
+      bytes(': keep-alive\n\ndata: {"a":1}\n\ndata: [DONE]\n\n'),
+      (comment) => { comments.push(comment) },
+    ))
+    expect(comments).toEqual(['keep-alive'])
+    expect(events).toEqual(['{"a":1}', DONE])
+  })
+
   it('stops yielding after DONE even when more data follows', async () => {
     const events = await collect(parseSse(bytes('data: [DONE]\n\ndata: {"late":1}\n\n')))
     expect(events).toEqual([DONE])
diff --git a/packages/util/timeout/README.i18n.yaml b/packages/util/timeout/README.i18n.yaml
index 0436cc4d34..a578a0ac4f 100644
--- a/packages/util/timeout/README.i18n.yaml
+++ b/packages/util/timeout/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/util/timeout/README.md
-README.md: 11c55a45a1255e14fb551e42ba3965453dbd94ae
-README.zh.md: 8b63f00595139f9af2e9a31e8ab3c3494088e0ff
+README.md: 8892b2dce53b5c315c088430ed3fcf386a0f3101
+README.zh.md: ec99f38ff92890c854a1f902e56b2278a42318b6
diff --git a/packages/util/timeout/README.md b/packages/util/timeout/README.md
index 11c55a45a1..8892b2dce5 100644
--- a/packages/util/timeout/README.md
+++ b/packages/util/timeout/README.md
@@ -18,7 +18,7 @@ import { clampTimeout, deadline, idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf, Ti
 |---|---|
 | `clampTimeout(requested, def, max, name?)` | Validate the caller's optional positive-finite hint, fill from `def`, cap at `max`. Throws (with `name`) on a non-positive/non-finite hint. |
 | `deadline(upstream, timeoutMs, code)` | Fuse `upstream` cancellation with a timeout into one `AbortSignal` (`AbortSignal.any`); the timeout carries a `TimeoutReason`. `[Symbol.dispose]` clears the timer. |
-| `idleWatchdog(upstream, timeoutMs, code)` | Keep one stable fused signal and arm only while its guarded async-iterator `next()` is outstanding. Resolution disarms; later demand rearms; disposal clears; concurrent demand rejects. |
+| `idleWatchdog(upstream, timeoutMs, code)` | Keep one stable fused signal and arm only while its guarded async-iterator `next()` is outstanding. Resolution disarms; later demand or `pulse()` activity rearms; disposal clears; concurrent demand rejects. |
 | `MAX_TIMER_DELAY_MS` | Largest delay Node schedules without clamping it to one millisecond (`2_147_483_647`). Timer-owning config must not exceed it. |
 | `timeoutOf(signal \| { reason }, code?)` | Recover the `TimeoutReason` from an aborted signal/error, else `undefined` — the timeout-vs-cancel classifier. Pass `code` to match only THIS deadline's timer (see nesting below). |
 | `TimeoutReason` | The internal reason (`code` + `timeoutMs`) stamped on a timeout abort. Not a public error — providers translate it into their own error/field. |
@@ -48,7 +48,7 @@ The signal only *notifies* — the caller MUST attach its own termination (`d.si
 
 Pass your own `code` to `timeoutOf` so classification composes under nesting: when the `upstream` you were handed is *itself* a deadline signal (a future `tools/execute` middleware arming a per-call deadline), `AbortSignal.any` preserves the outer `TimeoutReason` if the outer timer fires first. Scoping to your `code` makes a foreign timeout read as an ordinary upstream cancel — the correct classification from your capability's view — instead of your own timeout firing when your local timer never expired.
 
-For a streamed transport, create one `idleWatchdog`, pass its stable `signal` into the transport, and call `watchdog.next(iterator)` for each provider read. The interval must be positive, finite, and no greater than `MAX_TIMER_DELAY_MS`; Node otherwise clamps it to one millisecond. It measures only outstanding demand, so no timer runs while downstream code renders or otherwise waits before asking for the next chunk. The primitive still only notifies, so the transport must observe the stable signal; the DeepSeek and pi-ai adapters prove that timeout closes their real response body or SDK request.
+For a streamed transport, create one `idleWatchdog`, pass its stable `signal` into the transport, and call `watchdog.next(iterator)` for each provider read. Call `watchdog.pulse()` when transport activity does not yield an iterator value. The interval must be positive, finite, and no greater than `MAX_TIMER_DELAY_MS`; Node otherwise clamps it to one millisecond. It measures only outstanding demand, so no timer runs while downstream code renders or otherwise waits before asking for the next chunk. The primitive still only notifies, so the transport must observe the stable signal; the DeepSeek and pi-ai adapters prove that timeout closes their real response body or SDK request.
 
 ## What does NOT get a timeout
 
diff --git a/packages/util/timeout/README.zh.md b/packages/util/timeout/README.zh.md
index 8b63f00595..ec99f38ff9 100644
--- a/packages/util/timeout/README.zh.md
+++ b/packages/util/timeout/README.zh.md
@@ -18,7 +18,7 @@ import { clampTimeout, deadline, idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf, Ti
 |---|---|
 | `clampTimeout(requested, def, max, name?)` | 验证调用方可选的、值为正且有限的提示，从 `def` 填充，并限制在 `max` 以内。如果提示为非正数或非有限数，则抛出错误（包含 `name`）。 |
 | `deadline(upstream, timeoutMs, code)` | 将 `upstream` 取消与超时融合为一个 `AbortSignal`（`AbortSignal.any`）；超时携带 `TimeoutReason`。`[Symbol.dispose]` 清除 timer。 |
-| `idleWatchdog(upstream, timeoutMs, code)` | 保持一个稳定的融合信号，并且只在受保护的异步迭代器 `next()` 尚未完成时启动 timer。完成后停止 timer；后续需求重新启动 timer；dispose（资源释放）时清除；并发需求被拒绝。 |
+| `idleWatchdog(upstream, timeoutMs, code)` | 保持一个稳定的融合信号，并且只在受保护的异步迭代器 `next()` 尚未完成时启动 timer。完成后停止 timer；后续需求或 `pulse()` 活动会重新启动 timer；dispose（资源释放）时清除；并发需求被拒绝。 |
 | `MAX_TIMER_DELAY_MS` | Node 在不将延迟限制为 1 毫秒时可调度的最大延迟（`2_147_483_647`）。负责 timer 的配置不得超过该值。 |
 | `timeoutOf(signal \| { reason }, code?)` | 从已中止的信号/错误中恢复 `TimeoutReason`，否则返回 `undefined`，即超时与取消的分类器。传入 `code` 可仅匹配这个 deadline 的 timer（见下文的嵌套）。 |
 | `TimeoutReason` | 标记在超时中止上的内部原因（`code` + `timeoutMs`）。它不是公开错误；提供方将其转换为自己的错误/字段。 |
@@ -48,7 +48,7 @@ export async function runWithDeadline(upstream: AbortSignal | undefined, timeout
 
 将你自己的 `code` 传给 `timeoutOf`，以便分类可在嵌套中组合：当你收到的 `upstream` *本身*就是 deadline 信号时（未来启动每次调用 deadline 的 `tools/execute` 中间件），如果外层 timer 首先触发，`AbortSignal.any` 会保留外层 `TimeoutReason`。将范围限定为你的 `code`，可将外部超时视为普通 upstream 取消，这才是你所属功能视角下的正确分类，而不会在本地 timer 尚未到期时就声称自己超时。
 
-对于流式传输，创建一个 `idleWatchdog`，将其稳定的 `signal` 传给传输层，并为提供方的每次读取调用 `watchdog.next(iterator)`。间隔必须为正有限数，且不得超过 `MAX_TIMER_DELAY_MS`；否则 Node 会将其限制为 1 毫秒。它只对尚未完成的读取请求计时，因此当下游代码进行渲染或在请求下一个分片前以其他方式等待时，timer 不会运行。该原语仍然只会通知，因此传输层必须观察稳定信号；DeepSeek 和 pi-ai 适配器证明，超时会关闭它们的真实响应正文或 SDK 请求。
+对于流式传输，创建一个 `idleWatchdog`，将其稳定的 `signal` 传给传输层，并为提供方的每次读取调用 `watchdog.next(iterator)`。当传输活动不产生迭代器值时，调用 `watchdog.pulse()`。间隔必须为正有限数，且不得超过 `MAX_TIMER_DELAY_MS`；否则 Node 会将其限制为 1 毫秒。它只对尚未完成的读取请求计时，因此当下游代码进行渲染或在请求下一个分片前以其他方式等待时，timer 不会运行。该原语仍然只会通知，因此传输层必须观察稳定信号；DeepSeek 和 pi-ai 适配器证明，超时会关闭它们的真实响应正文或 SDK 请求。
 
 ## 哪些操作不设置超时
 
diff --git a/packages/util/timeout/src/index.ts b/packages/util/timeout/src/index.ts
index a9bd47eb08..3fc4d2387b 100644
--- a/packages/util/timeout/src/index.ts
+++ b/packages/util/timeout/src/index.ts
@@ -72,6 +72,8 @@ export interface IdleWatchdog {
    * @returns the iterator's next result.
    */
   next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>>
+  /** Rearm an outstanding demand after transport activity that yields no iterator value; otherwise a no-op. */
+  pulse(): void
   /** Clear an armed timer; safe to call once at the owning stream's exit. */
   [Symbol.dispose](): void
 }
@@ -135,15 +137,20 @@ export function idleWatchdog(
   let outstanding = false
   let disposed = false
 
+  const arm = (): void => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = setTimeout(() => {
+      timeout.abort(new TimeoutReason(code, timeoutMs))
+    }, timeoutMs)
+  }
+
   return {
     signal,
     async next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>> {
       if (disposed) throw new Error('idleWatchdog is disposed')
       if (outstanding) throw new Error('idleWatchdog next is already outstanding')
       outstanding = true
-      timer = setTimeout(() => {
-        timeout.abort(new TimeoutReason(code, timeoutMs))
-      }, timeoutMs)
+      arm()
       try {
         return await iterator.next()
       } finally {
@@ -152,6 +159,10 @@ export function idleWatchdog(
         outstanding = false
       }
     },
+    pulse(): void {
+      if (disposed || !outstanding) return
+      arm()
+    },
     [Symbol.dispose](): void {
       if (disposed) return
       disposed = true
diff --git a/packages/util/timeout/tests/timeout.spec.ts b/packages/util/timeout/tests/timeout.spec.ts
index 11779c915f..af0389d3d7 100644
--- a/packages/util/timeout/tests/timeout.spec.ts
+++ b/packages/util/timeout/tests/timeout.spec.ts
@@ -229,6 +229,28 @@ describe('idleWatchdog', () => {
     await expect(secondNext).rejects.toBe(stableSignal.reason)
   })
 
+  it('rearms outstanding demand on an out-of-band activity pulse', async () => {
+    vi.useFakeTimers()
+    const pending = Promise.withResolvers<IteratorResult<number>>()
+    const watchdog = idleWatchdog(undefined, 100, 'LLM_STREAM_IDLE_TIMEOUT')
+    watchdog.pulse()
+    await vi.advanceTimersByTimeAsync(1_000)
+    expect(watchdog.signal.aborted).toBe(false)
+
+    const next = watchdog.next({ next: () => pending.promise })
+    await vi.advanceTimersByTimeAsync(99)
+    watchdog.pulse()
+    await vi.advanceTimersByTimeAsync(99)
+    expect(watchdog.signal.aborted).toBe(false)
+    await vi.advanceTimersByTimeAsync(1)
+    expect(timeoutOf(watchdog.signal, 'LLM_STREAM_IDLE_TIMEOUT')).toMatchObject({ timeoutMs: 100 })
+    pending.reject(watchdog.signal.reason)
+    await expect(next).rejects.toBe(watchdog.signal.reason)
+
+    watchdog[Symbol.dispose]()
+    watchdog.pulse()
+  })
+
   it('keeps an earlier upstream abort distinct from its own timeout', async () => {
     vi.useFakeTimers()
     const upstream = new AbortController()

From bf70345d81a35c1e821aa88a96b1dac7e3f38bb2 Mon Sep 17 00:00:00 2001
From: fz <fz@dsh.dev>
Date: Tue, 4 Aug 2026 12:00:14 +0800
Subject: [PATCH 017/516] test(snapshot): widen keep-alive timing margin

---
 .../headless-agent/tests/fixtures/deepseek-defaults.cordis.yml  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
index 829af9f813..8a1ca177f4 100644
--- a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
@@ -8,7 +8,7 @@
           apiKey: snapshot-key
           baseURL: !!js process.env.DSH_SNAPSHOT_BASE_URL
           thinking: disabled
-          streamIdleTimeoutMs: 100
+          streamIdleTimeoutMs: 150
       - id: cli-agent
         config:
           provider: deepseek-official

From 88c035c98e2992641d390bd083be400da5d7d3c2 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Tue, 4 Aug 2026 14:11:38 +0800
Subject: [PATCH 018/516] cleanup(cli): remove the profile-json config entry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`./.dsh-tmp-profile/config.json` was the web config-tree boot's user-config
plane, but never gained a writer: no production code created or edited it, no
test exercised it, and no user documentation named it. The fields it mapped
have owners elsewhere — provider/model are the api-gateway's default route and
persistenceRoot is an assembly fact, while typed user preferences live in
$DSH_HOME/settings.yaml.

Delete PROFILE_DIR, PROFILE_FILE, ProfileMapping, PROFILE_MAPPINGS, and
readProfile() with the patch source that consumed them. AppCLIEntry now
composes patches from CLI flags and the resolved frontend distIndex only; the
surrounding layers are unchanged. A file on disk is ignored completely — no
migration, replacement format, or deprecation diagnostic, per the pre-release
stance.
---
 ...tree-boot-and-transport-layering.i18n.yaml |  4 +-
 ...config-tree-boot-and-transport-layering.md |  4 +-
 ...fig-tree-boot-and-transport-layering.zh.md |  4 +-
 ...-08-04-remove-profile-json-entry.i18n.yaml |  6 ++
 .../2026-08-04-remove-profile-json-entry.md   | 32 +++++++++
 ...2026-08-04-remove-profile-json-entry.zh.md | 32 +++++++++
 apps/cli/config/web.cordis.yml                |  6 +-
 apps/cli/src/app-cli-entry.ts                 | 70 +++----------------
 docs/user/guide/config.i18n.yaml              |  4 +-
 docs/user/guide/config.md                     |  2 +-
 docs/user/guide/config.zh.md                  |  2 +-
 11 files changed, 94 insertions(+), 72 deletions(-)
 create mode 100644 .agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.i18n.yaml
 create mode 100644 .agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md
 create mode 100644 .agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
index d50428d5ed..aede84e27f 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.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 .agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
-2026-07-24-web-config-tree-boot-and-transport-layering.md: 88f94b1f58ae7a3451c7772f4a9ff7d6564254c0
-2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: ea2a8f70a6c2d4207d4388a9303fbc6ce6e94238
+2026-07-24-web-config-tree-boot-and-transport-layering.md: e4dd8b50fe565deecb6e64d307305c66af50c001
+2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 54b0a0e499954cd0e2ccd22cffdf7d09bed11a22
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
index 88f94b1f58..e4dd8b50fe 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
@@ -16,7 +16,7 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)
 
 **Boot glue is a class pair.** `AppCLIEntry` (apps/cli) and `AppWebEntry` (the shell kernel) hold only what must exist independently of cordis: argv facts, the composed patch set, the parsed boot manifest, the module system instance, loading-page handles — everything else lives in plugins. `AppCLIEntry.run()` is three stages: layered env (ambient > cwd `.env` > `$DSH_HOME/.env`, closing the defect above) → patch composition → Loader include boot plus the activation audit. `AppWebEntry.run()` mirrors it browser-side: parse `window.__DSH_BOOT__` into a `BootManifest` (two views: npm-package rows for the module table, cordis-plugin rows for entry composition; malformed wire throws), build the module system, render the loading page, prefetch the `immediately` tier in parallel with Context/Loader setup, **await the prefetch before creating entries** (materialization is `tree.import`'s synchronous require, unprotected by fiber inject waiting; cross-package require edges such as i18n → runtime/client need every immediately-tier factory registered first — an empirically found 10–25% boot race otherwise), adopt the modules entry, create the graph rows, settle, sweep.
 
-**Config sources have one declaration place each.** yml static values are engineering defaults; the profile json (`./.dsh-tmp-profile/config.json`, read-only, never created, cwd-anchored until the `$DSH_HOME` migration) is user config mapped through a static `PROFILE_MAPPINGS` table onto target rows (`provider`/`model` → the `api-gateway` row, `persistenceRoot` → the jsonl row); CLI flags map onto the `webserver` row with a field set disjoint from the json's; env values enter through yml `!!js` expressions, never through the mapping table. Patches replace a row's config wholesale, so the entry class re-reads the yml row's static values (bypass parse) and merges overrides on top. An unmapped json key fails loud. The resolved frontend `distIndex` rides the same patch channel — an assembly fact, not user config.
+**Config sources have one declaration place each.** yml static values are engineering defaults; CLI flags map onto the `webserver` row; env values enter through yml `!!js` expressions. This decision also introduced a profile json (`./.dsh-tmp-profile/config.json`) as the user-config source, mapped through a static `PROFILE_MAPPINGS` table onto target rows; it never gained a writer and is [now removed](../simplification/2026-08-04-remove-profile-json-entry.md), leaving flags and the assembly fact below as the only patch sources. Patches replace a row's config wholesale, so the entry class re-reads the yml row's static values (bypass parse) and merges overrides on top. The resolved frontend `distIndex` rides the same patch channel — an assembly fact, not user config.
 
 **The transport splits five ways.** `dsh-host-apiproxy` upgraded to the gateway plugin (`api-gateway` row): default-exports `ApiProxyService`, config `{provider, model}`, provides `ctx.apiProxy`, transport-agnostic and registers no routes — `createApiProxy` moved here from the retired runtime package. `dsh-host-webserver` shrank to a plain route-registration plugin: `HttpServerService` provides `ctx.httpServer` (`register(route) → disposer` with duplicate-pattern throw, `tapIndex` transforms applied in registration order, `port`), listens on activation, per-request failures answer 400 and log without exiting, and knows no harness concepts. The connection node half owns the binding: it injects both services and registers `toFetchHandler(ctx.apiProxy)` under the `/api` prefix — future IPC carriers swap connection's transport while the gateway stays untouched. The modules node half (`ClientModuleHostService`, providing `ctx.clientModuleHost`) owns the graph: incremental per-package scanning (no full-rescan code path — `internal/plugin` marks the fiber's entry name dirty, a flush reconciles each name against live entries, package metadata including negative verdicts is cached forever, re-hashing is reachable only through `rebuilt(id)`), the bundle route, the index tap, and `onRebuilt`/`onGraphChanged` notification. The hmr node half owns dev reload: `fs.watchFile` stat-polling driven by `onGraphChanged` membership, and the `/plugins/events` SSE route.
 
@@ -25,7 +25,7 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)
 ## Consequences
 
 - Recomposing a web deployment is a yml/patch edit; the retired pieces (`mountWebPlugins`, `CLIENT_PACKAGES`, `createHostWebPluginRegistry`, `startWebServer`, the webserver's graph/SSE/api knowledge) are deleted.
-- Headless boots the same composition through the same entry (landed in the stacked follow-up): port 0 is its only surface difference, the model face gains `ask_user_question`/workspace context/model titles per the unification ruling, and `bootHost`/`startHost` retired with the `dsh-host-runtime` package. The profile write path, the `$DSH_HOME` profile relocation, and IPC carriers remain recorded deferrals.
+- Headless boots the same composition through the same entry (landed in the stacked follow-up): port 0 is its only surface difference, the model face gains `ask_user_question`/workspace context/model titles per the unification ruling, and `bootHost`/`startHost` retired with the `dsh-host-runtime` package. IPC carriers remain a recorded deferral; the profile write path and the `$DSH_HOME` profile relocation were dropped with the profile json itself.
 - A TypeScript pitfall worth remembering: a `declare module 'cordis'` augmentation in a file with **no cordis import** is demoted to a standalone module declaration and silently shatters the program-wide `Context` merge (`ctx.on`/`ctx.effect` vanish across the program). Anchor with `import type {} from 'cordis'`.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
index ea2a8f70a6..54b0a0e499 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 **boot 胶水是一对 class。** `AppCLIEntry`（apps/cli）与 `AppWebEntry`（壳内核）只持有独立于 cordis 必须提前存在的东西：argv 事实、合成的 patch 集、解析出的 boot manifest、模块系统实例、loading 页句柄——其余一律进插件。`AppCLIEntry.run()` 三段：分层 env（ambient > cwd `.env` > `$DSH_HOME/.env`，顺手关掉上述缺陷）→ patch 合成 → Loader include boot 加 activation audit。`AppWebEntry.run()` 在浏览器侧镜像它：把 `window.__DSH_BOOT__` 解析成 `BootManifest`（双视角：npm 包行给模块表、cordis 插件行给 entry 组合；畸形 wire 大声抛）、建模块系统、渲染 loading 页、immediately 层预取与 Context/Loader 准备并行、**create entry 之前等预取齐**（物化是 `tree.import` 的同步 require，不受 fiber inject 等待保护；i18n → runtime/client 这类跨包 require 边要求 immediately 层工厂全部注册完——否则有实测 10–25% 的 boot 竞态）、收编 modules entry、逐图行 create、settle、sweep。
 
-**每个配置源有唯一声明位置。** yml 静态值是工程默认；profile json（`./.dsh-tmp-profile/config.json`，只读、绝不创建、暂锚 cwd 直至 `$DSH_HOME` 迁移）是用户配置，经静态 `PROFILE_MAPPINGS` 表映射到目标行（`provider`/`model` → `api-gateway` 行，`persistenceRoot` → jsonl 行）；CLI flags 映射到 `webserver` 行、字段集与 json 不相交；env 值经 yml `!!js` 表达式进入，绝不进映射表。patch 整体替换行 config，故 entry 类旁路 parse 重读 yml 行静态值再叠加覆盖。未映射的 json 键 fail loud。解析出的前端 `distIndex` 走同一 patch 通道——装配事实，不是用户配置。
+**每个配置源有唯一声明位置。** yml 静态值是工程默认；CLI flags 映射到 `webserver` 行；env 值经 yml `!!js` 表达式进入。本决策当时还引入了 profile json（`./.dsh-tmp-profile/config.json`）作为用户配置源，经静态 `PROFILE_MAPPINGS` 表映射到目标行；它始终没有获得写入方，[现已删除](../simplification/2026-08-04-remove-profile-json-entry.md)，patch 来源只剩 flags 与下述装配事实。patch 整体替换行 config，故 entry 类旁路 parse 重读 yml 行静态值再叠加覆盖。解析出的前端 `distIndex` 走同一 patch 通道——装配事实，不是用户配置。
 
 **传输五分。** `dsh-host-apiproxy` 升格网关插件（`api-gateway` 行）：默认导出 `ApiProxyService`，config `{provider, model}`，provide `ctx.apiProxy`，传输无关、不注册路由——`createApiProxy` 自已退役的 runtime 包迁入。`dsh-host-webserver` 缩成朴素路由注册插件：`HttpServerService` provide `ctx.httpServer`（`register(route) → disposer`、重复 pattern 即抛、`tapIndex` 按注册序应用、`port`），激活即 listen，单请求失败答 400 并记日志不退进程，不认识任何 harness 概念。connection node 半拥有绑定：inject 两个服务，把 `toFetchHandler(ctx.apiProxy)` 注册在 `/api` 前缀下——将来 IPC 载体只换 connection 的传输，网关零改动。modules node 半（`ClientModuleHostService`，provide `ctx.clientModuleHost`）拥有图：单包增量扫描（无全量重扫路径——`internal/plugin` 把 fiber 的 entry 名标脏，flush 逐名对账 live entries，包元数据含否定结论永久缓存，重哈希唯一入口 `rebuilt(id)`）、bundle 路由、index tap、`onRebuilt`/`onGraphChanged` 通知。hmr node 半拥有开发期重载：`fs.watchFile` stat 轮询、watch 集合跟随 `onGraphChanged`、`/plugins/events` SSE 路由。
 
@@ -25,7 +25,7 @@ Status: implemented
 ## 后果
 
 - 重组一个 web 部署 = 改 yml/patch；退役件（`mountWebPlugins`、`CLIENT_PACKAGES`、`createHostWebPluginRegistry`、`startWebServer`、webserver 的图/SSE/api 知识）全部删除。
-- headless 已在 stacked 后续轮迁入同一组合同一入口：唯一面差异是 port 0，模型面按统一裁决获得 `ask_user_question`/workspace context/模型标题，`bootHost`/`startHost` 随 `dsh-host-runtime` 包退役。profile 写入路径、profile 迁 `$DSH_HOME`、IPC 载体仍为挂账项。
+- headless 已在 stacked 后续轮迁入同一组合同一入口：唯一面差异是 port 0，模型面按统一裁决获得 `ask_user_question`/workspace context/模型标题，`bootHost`/`startHost` 随 `dsh-host-runtime` 包退役。IPC 载体仍为挂账项；profile 写入路径与 profile 迁 `$DSH_HOME` 已随 profile json 本身一并放弃。
 - 一个值得记住的 TypeScript 坑：`declare module 'cordis'` augmentation 所在文件若**没有任何 cordis import**，会被降级成独立 module declaration，无声打散全程序的 `Context` merge（`ctx.on`/`ctx.effect` 全程序消失）。用 `import type {} from 'cordis'` 锚定。
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.i18n.yaml
new file mode 100644
index 0000000000..60bfb506ae
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.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-08-04-remove-profile-json-entry.md
+2026-08-04-remove-profile-json-entry.md: 8ca81e2364e095d90c87febfe705ddec14269bf4
+2026-08-04-remove-profile-json-entry.zh.md: bbc3957d11a2051e7c1f9eaaed52d8af38fa1e5b
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md
new file mode 100644
index 0000000000..8ca81e2364
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md
@@ -0,0 +1,32 @@
+# Agent Note: Removing the profile-json config entry
+
+Status: implemented
+
+English | [中文](2026-08-04-remove-profile-json-entry.zh.md)
+
+## Problem
+
+`./.dsh-tmp-profile/config.json` was the user-configuration plane of the [web config-tree boot](../architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md): a read-only JSON object under the invoking directory, mapped by a static `PROFILE_MAPPINGS` table onto three fields across two rows. Its write path and its relocation to the Harness home were recorded there as deferrals, and neither arrived. Nothing in the product ever created or edited the file, no test exercised it, and no user documentation named it — the format existed only as a reader.
+
+Meanwhile the fields it mapped acquired owners elsewhere. `provider` and `model` are the api-gateway's default route for created and resumed agents, which a session's own picker overrides per agent; `persistenceRoot` is an assembly fact of the shipped composition. Typed user preferences became `$DSH_HOME/settings.yaml` under the [user-settings seam](../architecture/2026-07-28-user-settings-seam.md). What remained was a third user-configuration format, anchored to the invoking directory and behind a hand-maintained mapping table, that nothing wrote.
+
+## Decision
+
+`PROFILE_DIR`, `PROFILE_FILE`, `ProfileMapping`, `PROFILE_MAPPINGS`, and `readProfile()` are deleted along with the patch source that consumed them. `AppCLIEntry` composes its patches from CLI flags and the resolved frontend `distIndex` only; the layers around it — shipped base, surface overlay, `--config` or the personal overlay, and `--config-replace` — are unchanged.
+
+A `.dsh-tmp-profile/config.json` on disk is now ignored completely. There is no migration, no replacement format, and no deprecation diagnostic: the file never had a producer, so there is no installed base to carry forward, and the [pre-release stance](../../../../AGENTS.md) rejects compatibility shims.
+
+## Alternatives considered
+
+**Keep the reader until typed settings own `provider`/`model`.** Rejected because the gap is not real: with no writer, the file gave users no way to pin a default route either, so keeping it preserves an unproduced format rather than a capability.
+
+**Relocate it to `$DSH_HOME`, the deferral the original note recorded.** Rejected because that deferral assumed the write path would arrive with it. Moving a file nothing writes only moves the dead entry, and the Harness home already has an owner for typed user preferences.
+
+**Report the file through a deprecation diagnostic when it exists.** Rejected because a diagnostic for a format the product never produced would advertise it to users who have never seen it.
+
+## Consequences
+
+- Given up: no file-based way to pin `provider`, `model`, or `persistenceRoot` without editing yml or passing `--config`. A persistent default route needs a typed settings namespace owned by whoever creates sessions; `persistenceRoot` stays an assembly fact.
+- Bought: one fewer user-configuration format, one less input anchored to the invoking directory, and a patch composition whose only remaining sources are CLI flags and an assembly fact — the fail-loud mapping table goes with it.
+- The [web config-tree boot note](../architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md) is only partially superseded: its composition, boot-glue, transport, and export decisions stand. Both notes stay cross-linked, and its profile facts were rewritten in place.
+- Absence is verified by repo-wide search: `.dsh-tmp-profile`, `PROFILE_MAPPINGS`, and `readProfile` have no remaining match.
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md
new file mode 100644
index 0000000000..bbc3957d11
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md
@@ -0,0 +1,32 @@
+# Agent Note: 删除 profile-json 配置入口
+
+Status: implemented
+
+[English](2026-08-04-remove-profile-json-entry.md) | 中文
+
+## Problem
+
+`./.dsh-tmp-profile/config.json` 曾是 [web 配置树启动](../architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md)的用户配置面：调用目录下的一个只读 JSON 对象，经静态 `PROFILE_MAPPINGS` 表映射到两个行上的三个字段。它的写路径以及迁往 Harness home 的计划都记在那条 Note 里作为延后项，两者都没有落地。产品中从未有任何代码创建或编辑该文件，没有测试覆盖它，也没有用户文档提到它——这个格式只存在读取方。
+
+与此同时，它映射的字段各自有了别处的归属。`provider` 与 `model` 是 api-gateway 为新建和恢复的 agent 提供的默认路由，会话自己的选择器可按 agent 覆盖它；`persistenceRoot` 是交付组合的装配事实。类型化的用户偏好则由 [user-settings seam](../architecture/2026-07-28-user-settings-seam.md) 下的 `$DSH_HOME/settings.yaml` 承接。剩下的只是第三个用户配置格式：锚定在调用目录、藏在一张手工维护的映射表后面，而且没有任何东西写它。
+
+## Decision
+
+`PROFILE_DIR`、`PROFILE_FILE`、`ProfileMapping`、`PROFILE_MAPPINGS` 和 `readProfile()` 连同消费它们的那个 patch 来源一并删除。`AppCLIEntry` 现在只从 CLI 标志和解析出的前端 `distIndex` 合成 patch；它周围的各层——交付基座、surface overlay、`--config` 或个人 overlay、以及 `--config-replace`——保持不变。
+
+磁盘上的 `.dsh-tmp-profile/config.json` 现在被完全忽略。没有迁移、没有替代格式、也没有弃用诊断：该文件从来没有生产方，因此不存在需要承接的存量，而[未发布阶段的立场](../../../../AGENTS.md)拒绝兼容垫片。
+
+## Alternatives considered
+
+**保留读取方，直到类型化 settings 接管 `provider`/`model`。** 否决，因为这个缺口并不真实存在：既然没有写入方，该文件同样没有给用户任何钉住默认路由的途径，保留它保住的是一个无人生产的格式，而不是一项能力。
+
+**按原 Note 记录的延后项，把它迁到 `$DSH_HOME`。** 否决，因为那条延后项的前提是写路径会随之到来。搬动一个没人写的文件只是搬动了这个死入口，而 Harness home 已经有了类型化用户偏好的归属者。
+
+**文件存在时通过弃用诊断报告它。** 否决，因为为一个产品从未生产过的格式给出诊断，等于向从没见过它的用户宣传它。
+
+## Consequences
+
+- 放弃的：不再有基于文件、无需编辑 yml 或传 `--config` 就能钉住 `provider`、`model` 或 `persistenceRoot` 的途径。持久的默认路由需要一个由会话创建方拥有的类型化 settings namespace；`persistenceRoot` 仍是装配事实。
+- 换来的：少一个用户配置格式，少一个锚定在调用目录的输入，以及一处仅剩 CLI 标志与装配事实两个来源的 patch 合成——那张 fail-loud 映射表随之消失。
+- [web 配置树启动 Note](../architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md) 只被部分取代：它关于组合、启动胶水、传输与导出的决策仍然成立。两条 Note 保持互链，其中与 profile 相关的事实已就地改写。
+- 缺席由全仓搜索验证：`.dsh-tmp-profile`、`PROFILE_MAPPINGS` 与 `readProfile` 均无残留匹配。
diff --git a/apps/cli/config/web.cordis.yml b/apps/cli/config/web.cordis.yml
index daf597916e..efd2f93b2a 100644
--- a/apps/cli/config/web.cordis.yml
+++ b/apps/cli/config/web.cordis.yml
@@ -1,6 +1,6 @@
 # `dsh web` — the browser surface, as a patch list over `base.cordis.yml`.
 # The launcher includes the base and applies this file, then any `--config`
-# overlay, then AppCLIEntry's profile-json and CLI-flag patches, as sibling patch
+# overlay, then AppCLIEntry's CLI-flag patches, as sibling patch
 # lists at ONE include level: patches never cross an include boundary, so
 # stacking overlays as nested includes would silently stop reaching base rows.
 #
@@ -81,8 +81,8 @@
       name: '@deepseek-ai/dsh-host-directory-picker-auto'
 
     # The API gateway: the transport-agnostic dispatch face every client shape
-    # shares. provider/model are the host default routing — the profile json's
-    # mapping target (user config overrides these engineering defaults).
+    # shares. provider/model are the host default route for created and resumed
+    # agents; a session's own picker overrides it per agent.
     - id: api-gateway
       name: '@deepseek-ai/dsh-host-apiproxy'
       config:
diff --git a/apps/cli/src/app-cli-entry.ts b/apps/cli/src/app-cli-entry.ts
index eaa1902eff..e46c8d653a 100644
--- a/apps/cli/src/app-cli-entry.ts
+++ b/apps/cli/src/app-cli-entry.ts
@@ -2,8 +2,8 @@
  * AppCLIEntry — the pre-cordis boot glue the config-tree dsh surfaces share
  * (`dsh web` and `dsh -p`; the TUI composes dsh-app-boot directly).
  * Everything here is what must exist before the Loader runs: the patch
- * composition over the shipped base and surface overlay (profile json + CLI
- * flags + the resolved frontend dist), and the fail-loud activation audit after the tree
+ * composition over the shipped base and surface overlay (CLI flags + the
+ * resolved frontend dist), and the fail-loud activation audit after the tree
  * settles. The environment is what the bin already loaded (ambient plus the
  * invoking directory's `.env`); `$DSH_HOME/.env` belongs to the credential
  * provider and is never hoisted here.
@@ -12,7 +12,7 @@
 import { readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { networkInterfaces } from 'node:os'
-import { join, resolve } from 'node:path'
+import { resolve } from 'node:path'
 import { Context } from 'cordis'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import yaml from 'js-yaml'
@@ -26,10 +26,6 @@ import {
 // Empty type import carries the httpServer Context merge for the port read below.
 import type {} from '@deepseek-ai/dsh-host-webserver'
 
-/** Profile file under the invoking directory (read-only this round; never created — see the design's profile ruling). */
-const PROFILE_DIR = '.dsh-tmp-profile'
-const PROFILE_FILE = 'config.json'
-
 /** The session-telemetry row id the DSH_TELEMETRY_DISABLED switch targets (mounted in web.cordis.yml). */
 const TELEMETRY_ROW_ID = 'telemetry-otel'
 
@@ -100,25 +96,6 @@ export function configHasTelemetryRow(file: string): boolean {
     row.id === TELEMETRY_ROW_ID || (row.insert ?? []).some(inserted => inserted.id === TELEMETRY_ROW_ID))
 }
 
-/** One profile-json key mapped onto a yml row's config field. */
-interface ProfileMapping {
-  jsonPath: string
-  entryId: string
-  configKey: string
-}
-
-/**
- * The static profile→row mapping table. json is user config and wins over the
- * yml engineering default per field; a json key absent from this table fails
- * loud (a typo silently ignored would read as "setting has no effect").
- * Developers extend deployments by adding rows here.
- */
-const PROFILE_MAPPINGS: ProfileMapping[] = [
-  { jsonPath: 'provider', entryId: 'api-gateway', configKey: 'provider' },
-  { jsonPath: 'model', entryId: 'api-gateway', configKey: 'model' },
-  { jsonPath: 'persistenceRoot', entryId: 'session-persistence-jsonl', configKey: 'root' },
-]
-
 // The include's YAML dialect: `!!js` scalars become expression nodes the
 // Loader evaluates at entry activation. The bypass parse below must accept
 // them (and passing one through a patch unchanged is legal).
@@ -135,14 +112,14 @@ export interface AppCLIEntryOptions {
   configPath: string
   /**
    * Absolute path of this surface's overlay: a patch list applied over
-   * {@link configPath} before this entry's own profile/flag patches. Its rows
+   * {@link configPath} before this entry's own flag patches. Its rows
    * are also merge inputs, so a flag override preserves the overlay's other
    * fields on the same row.
    */
   overlayPath: string
   /**
    * Optional explicit overlay applied after {@link overlayPath} and before
-   * this entry's own profile/flag patches. When absent, the personal
+   * this entry's own flag patches. When absent, the personal
    * `$DSH_HOME/config.yaml` overlay is applied instead.
    */
   extraOverlayPath?: string
@@ -205,8 +182,8 @@ export class AppCLIEntry {
   }
 
   /**
-   * Compose the patch set from profile json, CLI flags, and the resolved
-   * frontend dist. Patches replace a row's config wholesale, so each patched row's yml
+   * Compose the patch set from CLI flags and the resolved frontend dist.
+   * Patches replace a row's config wholesale, so each patched row's yml
    * static values are re-read here (bypass parse) and merged under the overrides.
    */
   private composePatches(): void {
@@ -218,28 +195,19 @@ export class AppCLIEntry {
       overrides.set(entryId, bag)
     }
 
-    // Source 1: profile json (missing file = empty; unmapped key = loud).
-    for (const [key, value] of Object.entries(this.readProfile())) {
-      const mapping = PROFILE_MAPPINGS.find(m => m.jsonPath === key)
-      if (mapping === undefined) {
-        throw new Error(`dsh: profile key "${key}" has no mapping (known: ${PROFILE_MAPPINGS.map(m => m.jsonPath).join(', ')})`)
-      }
-      put(mapping.entryId, mapping.configKey, value)
-    }
-
-    // Source 2: CLI flags (field set disjoint from the json mappings).
+    // Source 1: CLI flags.
     if (this.options.host !== undefined) put('webserver', 'host', this.options.host)
     if (this.options.port !== undefined) put('webserver', 'port', this.options.port)
     if (this.options.workspaceRoot !== undefined) put('api-gateway', 'workspaceRoot', this.options.workspaceRoot)
 
-    // Source 2b: authorities for the /api browser-trust fence (rationale on
+    // Source 1b: authorities for the /api browser-trust fence (rationale on
     // resolveLanTrust).
     const ymlHost = (rows.get('webserver')?.config as { host?: string } | undefined)?.host
     const { lanAddresses, trustedHosts } = resolveLanTrust(this.options.host ?? ymlHost, this.options.trustedHosts ?? [])
     this.lanAddresses = lanAddresses
     if (trustedHosts.length > 0) put('connection', 'trustedHosts', trustedHosts)
 
-    // Source 3: the frontend dist — an assembly fact of this app, never yml
+    // Source 2: the frontend dist — an assembly fact of this app, never yml
     // user config. Workspace knowledge stays here.
     put('webserver', 'distIndex', this.resolveDistIndex())
 
@@ -262,7 +230,7 @@ export class AppCLIEntry {
     // One include of the shared base with every overlay as a sibling patch
     // list: patches never cross an include boundary, so nesting them would
     // silently stop reaching base rows. The surface overlay applies first, then
-    // this entry's profile-json and CLI-flag patches, which therefore win.
+    // this entry's CLI-flag patches, which therefore win.
     const compose = (overlay: PatchOptions[]): PatchOptions[] => [
       ...loadOverlayPatches('dsh', this.options.overlayPath),
       ...overlay,
@@ -327,22 +295,6 @@ export class AppCLIEntry {
     return doc as { id?: string; config?: unknown; insert?: { id?: string; config?: unknown }[] }[]
   }
 
-  /** Profile json under cwd; read-only — never created here, absent = no user config. */
-  private readProfile(): Record<string, unknown> {
-    let raw: string
-    try {
-      raw = readFileSync(join(process.cwd(), PROFILE_DIR, PROFILE_FILE), 'utf8')
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {}
-      throw error
-    }
-    const parsed: unknown = JSON.parse(raw)
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      throw new Error(`dsh: ${PROFILE_DIR}/${PROFILE_FILE} must hold a JSON object`)
-    }
-    return parsed as Record<string, unknown>
-  }
-
   /** Dist location is workspace knowledge of this app: resolved through the frontend package exports, not configured. */
   private resolveDistIndex(): string {
     const require = createRequire(import.meta.url)
diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml
index 4fd91343ac..6d1265e9f3 100644
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.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 docs/user/guide/config.md
-config.md: 0e2e0e7e7077adcacfaada1d038a0b1e63fcc0cd
-config.zh.md: 850a841286fe77db9169738b0b155f008205a1a8
+config.md: 6f656b573490a08ec893f4d14b487e6082015049
+config.zh.md: d4bb30023df46845ea720f3e6a45184479df0e72
diff --git a/docs/user/guide/config.md b/docs/user/guide/config.md
index 0e2e0e7e70..6f656b5734 100644
--- a/docs/user/guide/config.md
+++ b/docs/user/guide/config.md
@@ -50,7 +50,7 @@ Plugins load in file order. Place plugins that depend on services after the appl
 
 ## CLI overlays
 
-The TUI composes `base.cordis.yml` and `tui.cordis.yml`, then applies one optional patch list. By default that final list is `~/.dsh/config.yaml`; `dsh --config <path>` replaces the personal list with the named overlay. `dsh --config-replace <path>` instead boots the named file as the complete tree, without shipped or personal layers. `dsh web --config <path>` adds its overlay after the shared base and Web surface defaults and before Web profile and CLI-flag patches.
+The TUI composes `base.cordis.yml` and `tui.cordis.yml`, then applies one optional patch list. By default that final list is `~/.dsh/config.yaml`; `dsh --config <path>` replaces the personal list with the named overlay. `dsh --config-replace <path>` instead boots the named file as the complete tree, without shipped or personal layers. `dsh web --config <path>` adds its overlay after the shared base and Web surface defaults and before the Web launcher's CLI-flag patches.
 
 A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKey` and `baseURL`, so restate every key the row must retain.
 
diff --git a/docs/user/guide/config.zh.md b/docs/user/guide/config.zh.md
index 850a841286..d4bb30023d 100644
--- a/docs/user/guide/config.zh.md
+++ b/docs/user/guide/config.zh.md
@@ -50,7 +50,7 @@ Harness 使用 `cordis.yml` 描述 Agent 加载哪些插件以及每个插件的
 
 ## CLI 覆盖层
 
-TUI 先组合 `base.cordis.yml` 与 `tui.cordis.yml`，再应用一个可选补丁列表。默认的最后一层是 `~/.dsh/config.yaml`；`dsh --config <path>` 会以指定覆盖替代个人补丁列表。`dsh --config-replace <path>` 则把指定文件作为完整配置树启动，不使用已交付配置或个人层。`dsh web --config <path>` 会在共享基础配置与 Web 界面默认值之后、Web profile 与命令行标志补丁之前添加覆盖。
+TUI 先组合 `base.cordis.yml` 与 `tui.cordis.yml`，再应用一个可选补丁列表。默认的最后一层是 `~/.dsh/config.yaml`；`dsh --config <path>` 会以指定覆盖替代个人补丁列表。`dsh --config-replace <path>` 则把指定文件作为完整配置树启动，不使用已交付配置或个人层。`dsh web --config <path>` 会在共享基础配置与 Web 界面默认值之后、Web 启动器的命令行标志补丁之前添加覆盖。
 
 补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKey` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
 

From 03b534de1650255f5911eb79f3e44ada2bb37ed5 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Tue, 4 Aug 2026 14:50:38 +0800
Subject: [PATCH 019/516] feat(credentials): move the store to
 .credentials.yaml and layer $DSH_HOME/.env
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

$DSH_HOME/.env carried two incompatible jobs. As credentials-local's writable
secret store it could not be hoisted into process.env — hoisting makes every
stored key read as a read-only launch override and blocks rotation from the
TUI and the web page. But its name and dotenv format promise an environment
file, so a DEEPSEEK_BASE_URL sitting beside a working DEEPSEEK_API_KEY in the
same file was silently ignored: only the credential provider read the
document, and it addresses credential references alone.

Split the two jobs into two files.

.credentials.yaml is the provider-managed store: a strict YAML mapping of
CredentialRef to non-empty string, no version field, no wrapper level. Because
it holds credentials and nothing else, a non-mapping root, a non-identifier
key, a non-string value, an empty string, a duplicate key, and malformed YAML
are all rejections rather than skipped entries — loud at boot and at a write,
warn-and-keep-last-good on a live reload. The dotenv physical-line editor
gives way to a patch of the parsed document, so comments and untouched entries
keep their formatting and any string value round-trips, multi-line included.
Writer lock, read-modify-write, atomic 0600 write under a 0700 directory,
watcher, self-write suppression, and quiescent disposal are unchanged.

$DSH_HOME/.env becomes the user's ordinary environment layer. app-boot's new
loadLayeredEnv loads the invoking directory's .env then the Harness home's,
giving user < project < inherited; the home resolves from the inherited
environment first, so a project .env cannot redirect it.

Credential precedence is unchanged: the live environment still wins read-only
over the file, and shadowed writes still reject. Whether a provider-managed
store should instead win over the environment is a separate decision.

No migration: a key already in $DSH_HOME/.env keeps resolving through the new
environment layer, as a read-only env source that shadows the stored one.
---
 ...est-level-llm-config-credentials.i18n.yaml |   4 +-
 ...29-request-level-llm-config-credentials.md |   2 +-
 ...request-level-llm-config-credentials.zh.md |   2 +-
 ...undaries-and-atomic-registration.i18n.yaml |   4 +-
 ...tial-boundaries-and-atomic-registration.md |   2 +-
 ...l-boundaries-and-atomic-registration.zh.md |   2 +-
 ...-yaml-and-user-environment-layer.i18n.yaml |   6 +
 ...entials-yaml-and-user-environment-layer.md |  50 ++++
 ...ials-yaml-and-user-environment-layer.zh.md |  50 ++++
 THIRD_PARTY_NOTICES.md                        |   1 -
 apps/cli/config/base.cordis.yml               |   9 +-
 apps/cli/src/app-cli-entry.ts                 |   6 +-
 apps/cli/src/bin.ts                           |   4 +-
 apps/cli/src/tui.ts                           |  11 +-
 apps/cli/tests/tui-keyless-smoke.e2e.ts       |  31 +--
 apps/web/tests/models-settings.e2e.ts         |  10 +-
 .../tests/onboarding-deepseek-config.e2e.ts   |   4 +-
 docs/config-catalog.md                        |   4 +-
 examples/headless-agent/cordis.yml            |   2 +-
 packages/credentials/README.i18n.yaml         |   4 +-
 packages/credentials/README.md                |   2 +-
 packages/credentials/README.zh.md             |   2 +-
 .../credentials-local/README.i18n.yaml        |   4 +-
 .../credentials/credentials-local/README.md   |  21 +-
 .../credentials-local/README.zh.md            |  21 +-
 .../credentials-local/package.json            |   4 +-
 .../credentials-local/src/index.ts            | 250 +++++++-----------
 .../credentials-local/tests/drain.spec.ts     |   2 +-
 .../credentials-local/tests/local.spec.ts     | 161 ++++++-----
 .../tests/review-fixes.spec.ts                |  99 ++-----
 .../credentials-local/tests/watcher.spec.ts   |  55 ++--
 .../llm-deepseek/tests/dynamic-config.spec.ts |   8 +-
 .../tests/loader-composition.spec.ts          |  20 +-
 .../llm-pi-ai/tests/dynamic-config.spec.ts    |   6 +-
 .../tests/loader-composition.spec.ts          |   6 +-
 packages/ui/app-boot/README.i18n.yaml         |   4 +-
 packages/ui/app-boot/README.md                |   5 +-
 packages/ui/app-boot/README.zh.md             |   5 +-
 packages/ui/app-boot/src/index.ts             |  32 ++-
 packages/ui/app-boot/tests/app-boot.spec.ts   |  62 ++++-
 pnpm-lock.yaml                                |  12 +-
 41 files changed, 566 insertions(+), 423 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
index c7861321a0..ddb3a064d4 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.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 .agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
-2026-07-29-request-level-llm-config-credentials.md: f12a2496a767decc3ce2b065f6be03009aec8992
-2026-07-29-request-level-llm-config-credentials.zh.md: 99fd90013a24746962ca02a5f4f18cdccd53f71a
+2026-07-29-request-level-llm-config-credentials.md: 5359865d1ca0c6620f4af1fa82c2f7e5413e79d6
+2026-07-29-request-level-llm-config-credentials.zh.md: e23bf92a0d8efa68ad682e002f07732aaa114049
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
index f12a2496a7..5359865d1c 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
@@ -14,7 +14,7 @@ The [settings seam](2026-07-28-user-settings-seam.md) shipped without a producti
 
 **Per-request resolution, not fiber rebuilds.** The adapters take an options thunk (and a per-stream credential resolver) instead of frozen construction facts, resolving once per operation — the Pi pattern, with its tested semantics: two requests straddling a change see two configurations, one request resolves exactly once, and an in-flight stream keeps the facts it started with. This deletes the entire swap machinery a rebuild design needs (`DUPLICATE_ADAPTER` ordering, `NO_ADAPTER` windows, a deferred-activation state machine) and makes a missing key a *request-time* actionable failure (`MISSING_CREDENTIAL` naming every entry point) while the route stays registered and the catalog stays browsable. The one registration-captured fact — the retry policy the `ctx.llm` registry snapshots at `registerAdapter` (plus pi-ai's route *set*) — re-registers the same adapter instance in one synchronous section when it changes.
 
-**Secrets are references, values live behind `ctx.credentials`.** Configuration (both planes) carries `apiKeyEnv: DEEPSEEK_API_KEY`; the three-package credential seam resolves it per operation. `credentials-local` layers the live process environment (read-only, wins — a launch-time override is operator intent and must be *visibly* read-only, so shadowed writes reject instead of appearing to succeed) over `$DSH_HOME/.env` (writable, byte-preserving line edits, a quoting ladder dotenv reads back verbatim, wholesale snapshot replacement on reload so a deleted entry never lingers — the Claude Code additive-reapply lesson). Resolution order in the adapters is literal `apiKey` first (preserving the historical `config.apiKey ?? env` observable semantics), then the seam, then — only without a mounted seam — the raw environment variable.
+**Secrets are references, values live behind `ctx.credentials`.** Configuration (both planes) carries `apiKeyEnv: DEEPSEEK_API_KEY`; the three-package credential seam resolves it per operation. `credentials-local` layers the live process environment (read-only, wins — a launch-time override is operator intent and must be *visibly* read-only, so shadowed writes reject instead of appearing to succeed) over the provider-managed document (writable, wholesale snapshot replacement on reload so a deleted entry never lingers — the Claude Code additive-reapply lesson). That document was `$DSH_HOME/.env` in dotenv form; the [credentials document split](2026-08-04-credentials-yaml-and-user-environment-layer.md) later moved it to `$DSH_HOME/.credentials.yaml` and freed the old path to become the user's environment layer. Resolution order in the adapters is literal `apiKey` first (preserving the historical `config.apiKey ?? env` observable semantics), then the seam, then — only without a mounted seam — the raw environment variable.
 
 **Per-plugin namespaces, schema ≡ `Config`.** Each adapter registers its own namespace (`llm-deepseek`, `llm-pi-ai`) with its plugin `Config` schema and its `cordis.yml` entry as the composition `base` — a settings section is the same YAML shape as the entry config, and `resolveAdapterOptions`/`resolveProfiles` stay the one explicit resolve step for both. A live snapshot failing a beyond-schema bound keeps the last good facts (the seam's last-good philosophy extended one level up); the entry config itself still fails load. pi-ai's `providers` became a dict keyed by route so base and user layers merge per provider and the route set is structural; the array shape fails loud with migration directions, and an empty dict is the valid dormant posture — a composition ships the adapter bare and every route stays a user-plane decision.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
index 99fd90013a..e23bf92a0d 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 **按请求解析，而非重建 fiber。**适配器改为接收一个 options thunk（外加按流调用的凭据解析器），不再持有冻结的构造期事实，每个操作解析一次——即 Pi 的模式，连同其经测试固定的语义：跨越一次变更的两个请求看到两份配置，一个请求恰好解析一次，进行中的流保持其起始事实。这删掉了重建式设计所需的整套切换机制（`DUPLICATE_ADAPTER` 顺序问题、`NO_ADAPTER` 窗口、延迟激活状态机），并把密钥缺失变成*请求时*可行动的失败（`MISSING_CREDENTIAL` 点名每个配置入口），同时路由保持注册、catalog 保持可浏览。唯一在注册期捕获的事实——`ctx.llm` 注册表在 `registerAdapter` 时快照的重试策略（外加 pi-ai 的路由*集合*）——在其变化时于一个同步区段内原地重新注册同一适配器实例。
 
-**机密是引用，值藏在 `ctx.credentials` 背后。**配置（两个面）携带 `apiKeyEnv: DEEPSEEK_API_KEY`；三包凭据 seam 按操作解析它。`credentials-local` 把活跃进程环境（只读、优先——启动时覆盖是操作者意图，必须*可见地*只读，因此被遮蔽的写入直接拒绝而不是表面成功）叠加在 `$DSH_HOME/.env` 之上（可写、保字节行级编辑、dotenv 能逐字读回的引号阶梯、重载时整体替换快照使删除的条目绝不滞留——来自 Claude Code 增量重放（additive reapply）的教训）。适配器内的解析顺序为：字面 `apiKey` 优先（保留历史 `config.apiKey ?? env` 的可观察语义），然后是 seam，最后——仅在未挂载 seam 时——原始环境变量。
+**机密是引用，值藏在 `ctx.credentials` 背后。**配置（两个面）携带 `apiKeyEnv: DEEPSEEK_API_KEY`；三包凭据 seam 按操作解析它。`credentials-local` 把活跃进程环境（只读、优先——启动时覆盖是操作者意图，必须*可见地*只读，因此被遮蔽的写入直接拒绝而不是表面成功）叠加在 provider 管理的文档之上（可写、重载时整体替换快照使删除的条目绝不滞留——来自 Claude Code 增量重放（additive reapply）的教训）。该文档当时是 dotenv 形式的 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，并让旧路径转为用户的环境层。适配器内的解析顺序为：字面 `apiKey` 优先（保留历史 `config.apiKey ?? env` 的可观察语义），然后是 seam，最后——仅在未挂载 seam 时——原始环境变量。
 
 **按插件划分 namespace，schema ≡ `Config`。**每个适配器注册自己的 namespace（`llm-deepseek`、`llm-pi-ai`），schema 用其插件 `Config` schema，组合 `base` 用其 `cordis.yml` 条目——settings 分节与 entry 配置是同一种 YAML 形状，`resolveAdapterOptions`/`resolveProfiles` 对两者仍是唯一的显式 resolve 步骤。存活快照若违反 schema 之外的约束，则保留最后可用事实（seam 的最后可用值哲学向上延伸一层）；entry 配置本身仍会加载失败。pi-ai 的 `providers` 改为以路由为键的字典，base 层与用户层因此按提供方合并，路由集合也由结构直接表达；数组形状响亮失败并给出迁移指引，而空字典是合法的休眠姿态——组合可以裸挂该适配器，把每一条路由都留给用户面决定。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index 98f2b0cb0d..a4ac2f47bb 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.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 .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
-2026-07-30-credential-boundaries-and-atomic-registration.md: 6fe5f554acbfd804db9625fcaa794d513c8799c4
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 3eb3b022064124aad2a389abba3063af4e2110fa
+2026-07-30-credential-boundaries-and-atomic-registration.md: a093a78d7e3dafe218eb8f1013f226de0d6d9a0b
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 208642af34b5bda07a4e02bc991a655c5bb1fa20
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
index 6fe5f554ac..a093a78d7e 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
@@ -14,7 +14,7 @@ Two request-path defects sat beside them. DeepSeek's per-request resolution kept
 
 ## Decision
 
-**`$DSH_HOME/.env` belongs to the credential provider alone.** No surface loads it into `process.env`. The genuine launch environment and the invoking directory's `.env` (loaded by the bin) stay the read-only ambient layer, so a composition without the provider resolves keys exactly as before, while a stored key stays file-sourced and writable across restarts — proven by a real restart in the loader composition rather than by a unit assertion about `describe()`.
+**The credential document belongs to the credential provider alone.** No surface loads it into `process.env`. It was `$DSH_HOME/.env` here; the [credentials document split](2026-08-04-credentials-yaml-and-user-environment-layer.md) later moved it to `$DSH_HOME/.credentials.yaml`, so today it is the old path that is loaded — as the user's ordinary environment layer, holding no provider-managed secret. The genuine launch environment and the invoking directory's `.env` (loaded by the bin) stay the read-only ambient layer, so a composition without the provider resolves keys exactly as before, while a stored key stays file-sourced and writable across restarts — proven by a real restart in the loader composition rather than by a unit assertion about `describe()`.
 
 **The stored credential has no boundary against the model, and the READMEs say so.** `0600` under a `0700` directory stops other OS users; the model's bash and filesystem tools run as that same user, and the shipped default confines nothing. What the harness does hold to is narrower and stated as exactly that: no surface hoists the document into `process.env`, and the model is never handed a resolved path to it, so reaching the value takes a deliberate read of a path it was not given. An OS-keychain provider — a store the model's processes cannot read at all — is recorded as the real answer rather than implied by a partial one.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index 3eb3b02206..208642af34 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 ## 决策
 
-**`$DSH_HOME/.env` 只归凭据提供方所有。**没有任何一个面会把它加载进 `process.env`。真正的启动环境，以及调用目录中由 bin 加载的 `.env`，仍然是那一层只读的环境来源，因此不挂载该提供方的组合，解析密钥的方式与从前完全一致，而存下的密钥跨重启仍然来源于文件、仍然可写——这一点由 Loader 组合中的一次真实重启来证明，而不是靠对 `describe()` 的单元断言。
+**凭据文档只归凭据提供方所有。**没有任何一个面会把它加载进 `process.env`。当时该文档是 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，因此如今被加载的正是那条旧路径——作为用户的普通环境层，其中不含任何 provider 管理的密钥。真正的启动环境，以及调用目录中由 bin 加载的 `.env`，仍然是那一层只读的环境来源，因此不挂载该提供方的组合，解析密钥的方式与从前完全一致，而存下的密钥跨重启仍然来源于文件、仍然可写——这一点由 Loader 组合中的一次真实重启来证明，而不是靠对 `describe()` 的单元断言。
 
 **存下的凭据对模型没有边界，而 README 就是这么写的。**`0700` 目录下的 `0600` 挡得住其他 OS 用户；模型的 bash 与文件系统工具正是以同一用户身份运行，而已交付的默认值不约束任何东西。harness 真正守住的更窄，也就照这个宽度写下来：没有任何一个面会把该文档提升进 `process.env`，模型也从不会拿到它的解析后路径，因此要拿到这个值，需要刻意去读一条并未交给它的路径。OS 钥匙串（keychain）提供方——一个模型的进程根本读不到的存储——被记录为真正的答案，而不是靠一个残缺的方案去暗示它。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
new file mode 100644
index 0000000000..eb74fbd0e2
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.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/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
+2026-08-04-credentials-yaml-and-user-environment-layer.md: f1bca69820d03fe67849bd7c7159489ac27cd2e0
+2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 7e6714abd33baad1fb2a570514754b467fcf8bd5
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
new file mode 100644
index 0000000000..f1bca69820
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
@@ -0,0 +1,50 @@
+# Agent Note: Splitting the credential store from the user environment layer
+
+Status: implemented
+
+English | [中文](2026-08-04-credentials-yaml-and-user-environment-layer.zh.md)
+
+## Problem
+
+`$DSH_HOME/.env` carried two incompatible jobs. It was the writable secret store of [`credentials-local`](../../../../packages/credentials/credentials-local/README.md), so no surface could hoist it into `process.env` — hoisting would make every stored key read as a read-only launch override and block rotation from the TUI and the web page. But its name and dotenv format promise an environment file, so users put non-secrets in it and those values reached nothing: a `DEEPSEEK_BASE_URL` beside a working `DEEPSEEK_API_KEY` in the same file was silently ignored, because only the credential provider read the document and it addresses credential references alone.
+
+One file cannot be both a store the Harness owns and isolates and a layer that propagates by ordinary environment rules. The [request-level credential decision](2026-07-29-request-level-llm-config-credentials.md) chose dotenv to match peer products' home `.env`, and the conflation was not visible until a non-secret needed the same file.
+
+## Decision
+
+The two jobs become two files under the Harness home.
+
+**`.credentials.yaml` is the provider-managed store.** A strict YAML mapping of `CredentialRef` to non-empty string, with no `version` field and no wrapper level:
+
+```yaml
+DEEPSEEK_API_KEY: sk-…
+OPENAI_API_KEY: sk-…
+```
+
+Because the document holds credentials and nothing else, every deviation is a rejection rather than a skipped entry: a non-mapping root, a key that is not a POSIX identifier, a non-string value, an empty string, a duplicate key, and malformed YAML all fail — loud at boot and at a write, warn-and-keep-the-last-good-snapshot on a live reload. A silently ignored key would read as "the secret I stored has no effect", which is the failure this change exists to remove. The dotenv physical-line editor is replaced by a patch of the parsed document, so comments and untouched entries keep their formatting, any string value round-trips (multi-line included), and no entry is unwritable for want of a quoting style. The writer lock, read-modify-write, atomic `0600` write under a `0700` directory, exact-path watcher, content-equality self-write suppression, and quiescent disposal are unchanged.
+
+**`$DSH_HOME/.env` is the user's ordinary environment layer.** `loadLayeredEnv` in [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) loads the invoking directory's `.env` and then the Harness home's, giving `user < project < inherited` — `process.loadEnvFile` never replaces a name already set, which is what the load order exploits and what the app-boot tests pin across all three layers. The Harness home is resolved from the inherited environment *before* either file loads, so a project `.env` cannot redirect which user document is read. Only the product CLI layers these files; SDK and example bins keep loading their own directory through `loadEnv` and must not inherit a developer's `$DSH_HOME`.
+
+Credential precedence is unchanged this round: the live process environment still wins read-only over the file, and `set`/`unset` still reject a write the environment would shadow. Whether a provider-managed store should instead win over the environment is a separate decision, deliberately not taken here.
+
+There is no migration. The product is unreleased, and a key already in `$DSH_HOME/.env` keeps resolving through the new environment layer — as a read-only `env` source that shadows the stored one, which is exactly what the diagnostics say.
+
+## Consequences
+
+- Given up: a key left in `$DSH_HOME/.env` is now hoisted into `process.env`, so it reaches subprocesses under the [subprocess credential scrub](../../../../packages/subprocess/subprocess/README.md) rather than staying inside the provider. That is the honest meaning of "ordinary environment layer"; a secret the Harness should own and isolate belongs in `.credentials.yaml`, which is never hoisted.
+- Given up: the same key shadows `.credentials.yaml` and makes the web Models page's write reject. The seam already reports `source: 'env', writable: false` for that state, and the rejection message now names the loaded `.env` as a place to unset it.
+- Bought: a non-secret in the user's `.env` finally takes effect, which was the original defect; the document format can reject what it cannot serve; and `0600` covers a file that holds only secrets instead of a file users are told to put ordinary configuration in.
+- Not taken: a read-time permission check that fails startup when `.credentials.yaml` is more permissive than `0600`. Creation and atomic replacement already pin the mode; making a hand-created file fatal is a separable security decision.
+- The `0600` boundary still stops other OS users and not the model, unchanged by this split — the [provider README](../../../../packages/credentials/credentials-local/README.md) owns that limit and the keychain-provider deferral.
+
+## Alternatives considered
+
+**Keep one `$DSH_HOME/.env` and teach the CLI to hoist it.** Rejected: hoisting the store is precisely what makes stored keys unrotatable, which is why [app-boot documented the exclusion](../../../../packages/ui/app-boot/README.md) in the first place. The conflict is the file's two jobs, not the loader.
+
+**`$DSH_HOME/.credentials.env` — a second dotenv file.** Rejected: dotenv suits an environment layer but cannot express "a managed document indexed by credential reference". It cannot reject a non-string or an unaddressable key, and its line editor already refused values it could not quote, leaving entries readable but unwritable.
+
+**Add a `version` field to the new document.** Rejected: the format is one schema-constrained string mapping with no historical variant to discriminate. While the product is unreleased, changing the structure and rejecting the old one beats promising a migration protocol.
+
+**Migrate credential-shaped keys out of `$DSH_HOME/.env` on first run.** Rejected: migration code turns a short-lived format into a long-lived maintenance surface, and classifying which keys in an unknown file are secrets is exactly the ambiguity this split removes. The old file keeps working as environment, which is a truthful outcome rather than a silent one.
+
+**Drop the user `.env` layer entirely and keep only the inherited environment.** Rejected here as out of scope: it is a coherent design (fewer layers, one place per value), but it removes a workflow users have, and the layering question belongs with the deferred precedence decision rather than with this split.
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
new file mode 100644
index 0000000000..7e6714abd3
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
@@ -0,0 +1,50 @@
+# Agent Note: 把凭据存储与用户环境层拆开
+
+Status: implemented
+
+[English](2026-08-04-credentials-yaml-and-user-environment-layer.md) | 中文
+
+## Problem
+
+`$DSH_HOME/.env` 同时承担了两件互不相容的工作。它是 [`credentials-local`](../../../../packages/credentials/credentials-local/README.md) 的可写密钥存储，因此任何表层都不能把它提升进 `process.env`——一旦提升，每个已存密钥都会读作只读的启动时覆盖，从而阻断从 TUI 与 Web 页面轮换密钥。但它的文件名和 dotenv 格式承诺的是一个环境文件，于是用户把非密钥值放进去，而那些值哪儿也到不了：同一个文件里，一个能用的 `DEEPSEEK_API_KEY` 旁边的 `DEEPSEEK_BASE_URL` 会被静默忽略，因为只有凭据 provider 读这份文档，而它只寻址凭据引用。
+
+一个文件无法既是由 Harness 拥有并隔离的存储，又是按普通环境规则传播的层。[请求级凭据决策](2026-07-29-request-level-llm-config-credentials.md)当初选择 dotenv 是为了对齐同类产品的 home `.env`，而这种混同直到有非密钥值需要用同一个文件时才暴露出来。
+
+## Decision
+
+两件工作在 Harness home 下拆成两个文件。
+
+**`.credentials.yaml` 是 provider 管理的存储。** 一个从 `CredentialRef` 到非空字符串的严格 YAML mapping，没有 `version` 字段，也没有包装层：
+
+```yaml
+DEEPSEEK_API_KEY: sk-…
+OPENAI_API_KEY: sk-…
+```
+
+因为该文档只存放凭据、别无他物，任何偏离都是拒绝而不是跳过条目：非 mapping 的根、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败——启动时和写入时响亮失败，运行期热重载则告警并保留最后可用快照。被静默忽略的键读起来就是「我存进去的密钥没有生效」，而这正是本次变更要消除的失败。dotenv 物理行编辑器被替换为对已解析文档打补丁，因此注释与未触及条目的排版都会保留，任何字符串值都能往返（含多行），也不会再有条目因为缺少可用引号样式而不可写。写锁、read-modify-write、`0700` 目录下的 `0600` 原子写、精确路径 watcher、按内容相等抑制自写、以及 dispose 时的完全停稳，均保持不变。
+
+**`$DSH_HOME/.env` 是用户的普通环境层。** [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) 中的 `loadLayeredEnv` 先加载调用目录的 `.env`，再加载 Harness home 的，得到 `用户 < 项目 < 继承`——`process.loadEnvFile` 从不替换已经设置的名字，加载顺序正是利用了这一点，app-boot 的测试也把三层一起钉住。Harness home 在两个文件加载*之前*就从继承的环境解析完毕，因此项目 `.env` 无法改变读取哪份用户文档。只有产品 CLI（命令行界面）叠加这两个文件；SDK 与示例 bin 仍通过 `loadEnv` 加载各自的目录，绝不继承开发者的 `$DSH_HOME`。
+
+本轮不改凭据优先级：活跃进程环境仍然只读地优先于文件，`set`/`unset` 仍然拒绝会被环境遮蔽的写入。provider 管理的存储是否应当反过来压过环境，是另一个决策，此处刻意不作。
+
+不做迁移。产品尚未发布，而已经放在 `$DSH_HOME/.env` 里的密钥会继续通过新的环境层解析——作为只读的 `env` 来源遮蔽已存储的那一份，诊断给出的也正是这个结论。
+
+## Consequences
+
+- 放弃的：留在 `$DSH_HOME/.env` 里的密钥现在会被提升进 `process.env`，因而会按[子进程凭据清洗](../../../../packages/subprocess/subprocess/README.md)的规则抵达子进程，而不再留在 provider 内部。这就是「普通环境层」的诚实含义；需要由 Harness 拥有并隔离的密钥属于 `.credentials.yaml`，后者永不提升。
+- 放弃的：同一个键会遮蔽 `.credentials.yaml`，并让 Web Models 页的写入被拒。seam 对这种状态本来就报告 `source: 'env', writable: false`，而拒绝信息现在会把已加载的 `.env` 一并指为需要清除的位置。
+- 换来的：用户 `.env` 里的非密钥值终于生效，这正是最初的缺陷；文档格式可以拒绝它无法承担的内容；`0600` 保护的是一个只存密钥的文件，而不是一个我们同时叫用户往里写普通配置的文件。
+- 未采纳的：在读取时校验权限、并在 `.credentials.yaml` 宽于 `0600` 时让启动失败。创建与原子替换已经钉住了模式；让手工创建的文件直接致命是一个可分离的安全决策。
+- `0600` 这条边界仍然只挡其他 OS 用户、挡不住模型，本次拆分未改变这一点——该限制及 keychain provider 的延后项归 [provider README](../../../../packages/credentials/credentials-local/README.md) 所有。
+
+## Alternatives considered
+
+**保留单一的 `$DSH_HOME/.env`，让 CLI 去提升它。** 否决：提升存储本身正是让已存密钥无法轮换的原因，这也是 [app-boot 当初记录该排除](../../../../packages/ui/app-boot/README.md)的理由。冲突来自这个文件的两份工作，而不是加载器。
+
+**`$DSH_HOME/.credentials.env`——第二个 dotenv 文件。** 否决：dotenv 适合环境层，却无法表达「一份按凭据引用索引的受管文档」。它无法拒绝非字符串或无法寻址的键，而且它的行编辑器本来就会拒绝无法加引号的值，留下可读却不可写的条目。
+
+**给新文档加 `version` 字段。** 否决：该格式只有一个受 schema 约束的字符串 mapping，没有需要判别的历史变体。在未发布阶段，直接修改结构并拒绝旧结构，好过提前承诺迁移协议。
+
+**首次运行时把形似凭据的键从 `$DSH_HOME/.env` 迁出。** 否决：迁移代码会把短命格式变成长期维护面，而判断一个未知文件里哪些键是密钥，恰恰是本次拆分要消除的歧义。旧文件继续作为环境工作，这是诚实的结果，而不是静默的结果。
+
+**彻底取消用户 `.env` 层，只保留继承的环境。** 在此处否决为超出范围：它本身是自洽的设计（层次更少、每个值只有一处来源），但会移除用户已有的工作流，而分层问题属于那个被延后的优先级决策，不属于本次拆分。
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 92ea0d2406..515004086e 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -52,7 +52,6 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`clsx`](https://github.com/lukeed/clsx) | MIT |
 | [`commander`](https://github.com/tj/commander.js) | MIT |
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
-| [`dotenv`](https://github.com/motdotla/dotenv) | BSD-2-Clause |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
 | [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT |
 | [`immer`](https://github.com/immerjs/immer) | MIT |
diff --git a/apps/cli/config/base.cordis.yml b/apps/cli/config/base.cordis.yml
index b7860e2eaa..d46e103426 100644
--- a/apps/cli/config/base.cordis.yml
+++ b/apps/cli/config/base.cordis.yml
@@ -69,12 +69,13 @@
 - id: settings
   name: '@deepseek-ai/dsh-settings-local'
 
-# Credential store: the live process environment over `$DSH_HOME/.env`
+# Credential store: the live process environment over `$DSH_HOME/.credentials.yaml`
 # (owner-only file, hot-reloaded). Adapters resolve their key references
 # through it at each request, so no key is inlined in this file. The web
-# Models page's key inputs write it through `credentials.set`; nothing hoists
-# the document into the process environment, which would make every stored key
-# read as an unrotatable ambient override.
+# Models page's key inputs write it through `credentials.set`. The document
+# holds credentials only and is never hoisted into the process environment;
+# the user's ordinary environment layer is `$DSH_HOME/.env`, and a key placed
+# there instead reads as an unrotatable ambient override.
 - id: credentials
   name: '@deepseek-ai/dsh-credentials-local'
 
diff --git a/apps/cli/src/app-cli-entry.ts b/apps/cli/src/app-cli-entry.ts
index e46c8d653a..ba3105c3ef 100644
--- a/apps/cli/src/app-cli-entry.ts
+++ b/apps/cli/src/app-cli-entry.ts
@@ -4,9 +4,9 @@
  * Everything here is what must exist before the Loader runs: the patch
  * composition over the shipped base and surface overlay (CLI flags + the
  * resolved frontend dist), and the fail-loud activation audit after the tree
- * settles. The environment is what the bin already loaded (ambient plus the
- * invoking directory's `.env`); `$DSH_HOME/.env` belongs to the credential
- * provider and is never hoisted here.
+ * settles. The environment is what the bin already loaded (ambient over the
+ * invoking directory's `.env` over `$DSH_HOME/.env`); credentials live in
+ * `$DSH_HOME/.credentials.yaml` and are never hoisted into it.
  */
 
 import { readFileSync } from 'node:fs'
diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts
index 3886438bed..dd5642de10 100644
--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -10,7 +10,7 @@
 
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
-import { loadEnv } from '@deepseek-ai/dsh-app-boot'
+import { loadLayeredEnv } from '@deepseek-ai/dsh-app-boot'
 import { parseDshArgs } from './args.ts'
 
 // Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib) sit
@@ -24,7 +24,7 @@ function readVersion(): string {
   return typeof manifest.version === 'string' ? manifest.version : '0.0.0'
 }
 
-loadEnv('dsh')
+loadLayeredEnv('dsh')
 // The env opt-in is read at the process boundary; `1` is the documented value.
 const invocation = parseDshArgs(process.argv.slice(2), readVersion(), process.env.DSH_EXPERIMENTAL === '1')
 
diff --git a/apps/cli/src/tui.ts b/apps/cli/src/tui.ts
index 5af1a32cbb..f91ea05c4e 100644
--- a/apps/cli/src/tui.ts
+++ b/apps/cli/src/tui.ts
@@ -115,12 +115,11 @@ export async function runTui(
     )
     process.exit(1)
   }
-  // The bin already loaded the invoking directory's .env, and that is the
-  // whole environment: $DSH_HOME/.env is credentials-local's writable store,
-  // and hoisting it would make every stored key read as a read-only ambient
-  // override on the next run — unrotatable from the TUI or the web page.
-  // The environment is settled, so switching the workspace here cannot alter
-  // its precedence. The cwd IS the workspace seam: the shipped config
+  // The bin already loaded both environment files, and that is the whole
+  // environment: credentials live in `$DSH_HOME/.credentials.yaml`, which is
+  // never hoisted, so a stored key stays rotatable from the TUI and the web
+  // page. The environment is settled, so switching the workspace here cannot
+  // alter its precedence — the project layer is the *invoking* directory's. The cwd IS the workspace seam: the shipped config
   // resolves the session cwd and the HMR watch root from it, so one chdir moves
   // both together. Sessions themselves live under the Harness home so `/resume`
   // spans every workspace, and are unaffected by this chdir.
diff --git a/apps/cli/tests/tui-keyless-smoke.e2e.ts b/apps/cli/tests/tui-keyless-smoke.e2e.ts
index 17b33f37ce..ade38a0e9c 100644
--- a/apps/cli/tests/tui-keyless-smoke.e2e.ts
+++ b/apps/cli/tests/tui-keyless-smoke.e2e.ts
@@ -667,40 +667,41 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     expect(output).toContain('\u001B[?2004l')
   }, PTY_SMOKE_TEST_TIMEOUT_MS)
 
-  it('applies the personal overlay: config.yaml patches an overlay-inserted row, the invoking directory\'s .env feeds its !!js, and the home .env stays out of the environment', async () => {
-    // The whole personal-config chain in one boot, plus the environment layer
-    // it deliberately excludes. config.yaml patches the `tui` row — a row the
+  it('applies the personal overlay: config.yaml patches an overlay-inserted row, and both .env layers feed its !!js with the project one winning', async () => {
+    // The whole personal-config chain in one boot, plus the environment
+    // layering underneath it. config.yaml patches the `tui` row — a row the
     // SURFACE OVERLAY inserted, not one the base declares — proving a later
-    // patch list reaches a row an earlier one inserted. The single `!!js`
-    // expression prefers the PERSONAL variable, so the welcome can only render
-    // the project value while the harness home's .env — the credential store
-    // of `dsh-credentials-local` — is NOT hoisted into `process.env`; hoisting
-    // it would make every stored key read as a read-only launch override on
-    // the next run and hand it to every subprocess the agent starts.
+    // patch list reaches a row an earlier one inserted. The `!!js` expression
+    // renders both halves of the layering in one line: `DSH_LAYER_WELCOME` is
+    // set by BOTH .env files and must render the project value, while
+    // `DSH_USER_ONLY` exists only in the harness home's .env and must still
+    // arrive. Credentials are not part of this: they live in
+    // `.credentials.yaml`, which is never hoisted into `process.env`.
     const output = await smoke({
       label: 'dsh personal overlay',
       tempDirPrefix: 'dsh-personal-overlay-',
       binScript: dshBinScript,
       configArgs: [],
       prepare: seedWorkspace({
-        workspace: { '.env': 'DSH_PROJECT_WELCOME=PROJECT OVERLAY READY.\n' },
+        workspace: { '.env': 'DSH_LAYER_WELCOME=PROJECT WINS.\n' },
         personal: {
-          '.env': 'DSH_PERSONAL_WELCOME=HOME ENV LEAKED.\n',
+          '.env': 'DSH_LAYER_WELCOME=USER LAYER LOST.\nDSH_USER_ONLY=USER LAYER LOADED.\n',
           'config.yaml': [
             '- id: workspace-context',
             '  disabled: true',
             '- id: tui',
             '  config:',
             "    sessionId: !!js configuredAgentIdentities?.main?.id ?? 'main'",
-            '    welcome: !!js process.env.DSH_PERSONAL_WELCOME ?? process.env.DSH_PROJECT_WELCOME',
+            '    welcome: !!js "(process.env.DSH_LAYER_WELCOME ?? \'PROJECT LAYER MISSING.\')'
+            + ' + \' \' + (process.env.DSH_USER_ONLY ?? \'USER LAYER MISSING.\')"',
             '',
           ].join('\n'),
         },
       }),
-      actions: [{ waitFor: 'PROJECT OVERLAY READY.', send: '/exit\r' }],
+      actions: [{ waitFor: 'PROJECT WINS. USER LAYER LOADED.', send: '/exit\r' }],
     })
-    expect(output).toContain('PROJECT OVERLAY READY.')
-    expect(output).not.toContain('HOME ENV LEAKED.')
+    expect(output).toContain('PROJECT WINS. USER LAYER LOADED.')
+    expect(output).not.toContain('USER LAYER LOST.')
     expect(output).toContain('\u001B[?2004l')
   }, PTY_SMOKE_TEST_TIMEOUT_MS)
 
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index c46127c9db..33e27628b0 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -81,7 +81,7 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     await dialog.getByLabel('API 密钥').fill('sk-e2e-minimax')
     await dialog.getByRole('button', { name: '保存', exact: true }).click()
     // The profile lands in settings.yaml with only the derived reference, the
-    // key value lands in the harness home's .env, the dormant route
+    // key value lands in the harness home's .credentials.yaml, the dormant route
     // registers, and the topology frame invalidates the page into the row.
     const row = dialog.getByText('minimax-cn', { exact: true }).first()
     await row.waitFor({ timeout: 10_000 })
@@ -89,8 +89,8 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     expect(document).toContain('minimax-cn:')
     expect(document).toContain('apiKeyEnv: MINIMAX_CN_API_KEY')
     expect(document).not.toContain('sk-e2e-minimax')
-    const stored = await readFile(join(scaffold.harnessHome, '.env'), 'utf8')
-    expect(stored).toContain('MINIMAX_CN_API_KEY=sk-e2e-minimax')
+    const stored = await readFile(join(scaffold.harnessHome, '.credentials.yaml'), 'utf8')
+    expect(stored).toContain('MINIMAX_CN_API_KEY: sk-e2e-minimax')
     expect(await page.content()).not.toContain('sk-e2e-minimax')
   }, 60_000)
 
@@ -136,8 +136,8 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
       async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'),
       { timeout: 10_000 },
     ).not.toContain('minimax-cn:')
-    expect(await readFile(join(scaffold.harnessHome, '.env'), 'utf8'))
-      .toContain('MINIMAX_CN_API_KEY=sk-e2e-minimax')
+    expect(await readFile(join(scaffold.harnessHome, '.credentials.yaml'), 'utf8'))
+      .toContain('MINIMAX_CN_API_KEY: sk-e2e-minimax')
     await expect.poll(
       async () => page.getByRole('dialog', { name: '删除模型提供方？' }).count(),
       { timeout: 10_000 },
diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts
index 1ec36454d0..78dd8bf7da 100644
--- a/apps/web/tests/onboarding-deepseek-config.e2e.ts
+++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts
@@ -112,8 +112,8 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
     await settings.getByRole('button', { name: '保存', exact: true }).click()
     await keyInput.waitFor({ state: 'detached', timeout: 15_000 })
 
-    const stored = await readFile(join(scaffold.harnessHome, '.env'), 'utf8')
-    expect(stored.includes(`DEEPSEEK_API_KEY=${secret}`)).toBe(true)
+    const stored = await readFile(join(scaffold.harnessHome, '.credentials.yaml'), 'utf8')
+    expect(stored.includes(`DEEPSEEK_API_KEY: ${secret}`)).toBe(true)
     expect((await page.content()).includes(secret)).toBe(false)
     expect((await page.locator('body').ariaSnapshot()).includes(secret)).toBe(false)
     expect(browserConsole.some(line => line.includes(secret))).toBe(false)
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 617cfb82be..ab0ca22024 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -412,7 +412,7 @@ Source: [`packages/compact/compact-tool-result-prune/src/types.ts:4`](../package
 ```ts config-catalog
 /** Plugin config: file location and hot-reload behavior. */
 export interface Config {
-  /** Credentials document path; defaults to `.env` under the harness home. */
+  /** Credentials document path; defaults to `.credentials.yaml` under the harness home. */
   path?: string
   /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */
   dshHome?: string
@@ -423,7 +423,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/credentials/credentials-local/src/index.ts:26`](../packages/credentials/credentials-local/src/index.ts)
+Source: [`packages/credentials/credentials-local/src/index.ts:35`](../packages/credentials/credentials-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-fs-local`
 
diff --git a/examples/headless-agent/cordis.yml b/examples/headless-agent/cordis.yml
index 937c976c67..25fc5ea0a2 100644
--- a/examples/headless-agent/cordis.yml
+++ b/examples/headless-agent/cordis.yml
@@ -9,7 +9,7 @@
 - id: settings
   name: '@deepseek-ai/dsh-settings-local'
 
-# Credential store: the live process environment over `$DSH_HOME/.env`
+# Credential store: the live process environment over `$DSH_HOME/.credentials.yaml`
 # (owner-only file, hot-reloaded). The adapter resolves `DEEPSEEK_API_KEY`
 # through it at each request, so no key is inlined in this file.
 - id: credentials
diff --git a/packages/credentials/README.i18n.yaml b/packages/credentials/README.i18n.yaml
index e8b35ba48e..e62ea8db5c 100644
--- a/packages/credentials/README.i18n.yaml
+++ b/packages/credentials/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/credentials/README.md
-README.md: 1d450cbeef84750fa57ca0151563c496aed0ce12
-README.zh.md: 843230c3cebf35f234d3ad812165b16ea734678b
+README.md: 4ab315e01a30d55869dbbb27dfbaf0f318eadd9f
+README.zh.md: 736f7f02eb26b7e0931b676b854dd108fdfae3eb
diff --git a/packages/credentials/README.md b/packages/credentials/README.md
index 1d450cbeef..4ab315e01a 100644
--- a/packages/credentials/README.md
+++ b/packages/credentials/README.md
@@ -7,7 +7,7 @@ The credential capability seam, as three-package shape dictates (interface / imp
 | Package | Role |
 |---|---|
 | [`credentials/`](credentials/README.md) | Abstract `ctx.credentials`: branded `CredentialRef` references, per-operation `resolve`, UI-safe `describe`, fail-loud `set`/`unset`, the `credentials/updated` commit event |
-| [`credentials-local/`](credentials-local/README.md) | File/environment provider: the live process environment (read-only, wins) layered over `$DSH_HOME/.env` (writable, byte-preserving line edits, hot-reloaded) |
+| [`credentials-local/`](credentials-local/README.md) | File/environment provider: the live process environment (read-only, wins) layered over `$DSH_HOME/.credentials.yaml` (writable, comment-preserving edits, hot-reloaded) |
 
 Configuration files carry *references* to secrets (`apiKeyEnv: DEEPSEEK_API_KEY`), never the secrets: the settings document stays safe to sync and render, and rotating a value touches no configuration. The LLM adapters are the first consumers — they resolve their reference once per model request, which is what makes a key stored moments ago reach the very next request without restarting anything.
 
diff --git a/packages/credentials/README.zh.md b/packages/credentials/README.zh.md
index 843230c3ce..736f7f02eb 100644
--- a/packages/credentials/README.zh.md
+++ b/packages/credentials/README.zh.md
@@ -7,7 +7,7 @@
 | 包 | 角色 |
 |---|---|
 | [`credentials/`](credentials/README.md) | 抽象 `ctx.credentials`：品牌化 `CredentialRef` 引用、按操作 `resolve`、对 UI 安全的 `describe`、响亮失败的 `set`/`unset`，以及 `credentials/updated` 提交事件 |
-| [`credentials-local/`](credentials-local/README.md) | 文件／环境 provider：活跃进程环境（只读、优先）叠加在 `$DSH_HOME/.env`（可写、保字节行级编辑、热重载）之上 |
+| [`credentials-local/`](credentials-local/README.md) | 文件／环境 provider：活跃进程环境（只读、优先）叠加在 `$DSH_HOME/.credentials.yaml`（可写、保留注释的编辑、热重载）之上 |
 
 配置文件携带的是对机密的*引用*（`apiKeyEnv: DEEPSEEK_API_KEY`），绝不携带机密本身：设置文档可以放心同步与渲染，轮换值不触碰任何配置。LLM 适配器是第一批消费方——它们每次模型请求解析一次引用，正因如此，片刻前存入的密钥无需重启任何组件即可作用于紧随其后的下一次请求。
 
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index b5fb4b2f0e..fc89d359e8 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-local/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/credentials/credentials-local/README.md
-README.md: 02b883958faf8b695a3a2abf2df77790cc2fca86
-README.zh.md: 59c7fd5747f327e8998882ca4db1473173e793b5
+README.md: ca2af9d8a514b43aeef19abec7cda4e44645bdaf
+README.zh.md: a8be53629853fe6fb7c39ef2281ac798b5624010
diff --git a/packages/credentials/credentials-local/README.md b/packages/credentials/credentials-local/README.md
index 02b883958f..ca2af9d8a5 100644
--- a/packages/credentials/credentials-local/README.md
+++ b/packages/credentials/credentials-local/README.md
@@ -7,7 +7,7 @@ File-backed [credentials](../credentials/README.md) provider: two layers, one ho
 | Layer | Source id | Writable | Wins |
 |---|---|---|---|
 | Live process environment | `env` | no | always |
-| `$DSH_HOME/.env` document | `file` | yes (`set`/`unset`) | otherwise |
+| `$DSH_HOME/.credentials.yaml` document | `file` | yes (`set`/`unset`) | otherwise |
 
 The environment wins because a launch-time override (`DEEPSEEK_API_KEY=… dsh`, CI secrets, a dev shell sourcing the repo `.env`) is operator intent for this run — and because it cannot be edited from inside, it must be *visibly* read-only: `describe()` reports `source: 'env', writable: false`, and `set`/`unset` reject instead of writing a change the reader would never see. Resolution reads `process.env` live and never writes it back.
 
@@ -15,24 +15,33 @@ The environment wins because a launch-time override (`DEEPSEEK_API_KEY=… dsh`,
 
 | Field | Default | Meaning |
 |---|---|---|
-| `path` | `<harness home>/.env` | Credentials document location. |
+| `path` | `<harness home>/.credentials.yaml` | Credentials document location. |
 | `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home used when `path` is omitted. |
 | `watch` | `true` | Hot-publish external edits. |
 | `debounceMs` | `100` | Watcher write-settle window. |
 
 ## The document
 
-dotenv format, parsed with `dotenv` and edited by a physical-line editor that preserves every byte it does not own: `set` rewrites the first assignment of its key in place with that line's own ending (dropping later duplicates, which dotenv's last-wins reading would otherwise let override the edit), `unset` removes only the owning line, and comments, unrelated lines, CRLF endings, and the continuation lines of another key's quoted multi-line value all survive verbatim. Every write first re-reads the document under the cross-process writer lock of [`dsh-atomic-write`](../../util/atomic-write/README.md) and publishes anything it had not observed, then commits atomically with mode `0600` under an owner-only (`0700`) directory — so a concurrent writer or an external edit inside the watcher's debounce window is folded in rather than overwritten.
+A YAML mapping of credential reference to value, and nothing else:
 
-Values are rendered in the narrowest style dotenv reads back verbatim — bare, then single-quoted (fully literal), then double-quoted (only without backslashes, which double-quote reading expands). A value no style can represent, and any entry that already spans multiple physical lines, fails loud instead of being corrupted silently. An empty stored value is absent, per the seam rule.
+```yaml
+DEEPSEEK_API_KEY: sk-…
+OPENAI_API_KEY: sk-…
+```
+
+The document holds credentials only, so every deviation is a rejection rather than a skipped entry — a silently ignored key would read as "the secret I stored has no effect". A non-mapping root, a key that is not a POSIX identifier, a non-string value, an empty string, a duplicate key, and malformed YAML all fail: loud at boot, and warn-and-keep-the-last-good-snapshot on a live reload. There is no `version` field and no wrapper level; the format is the mapping.
+
+Writes patch the parsed document rather than rebuilding it, so comments and the formatting of every untouched entry survive. A comment directly above an entry is that entry's annotation and is removed with it. Every write first re-reads the document under the cross-process writer lock of [`dsh-atomic-write`](../../util/atomic-write/README.md) and publishes anything it had not observed, then commits atomically with mode `0600` under an owner-only (`0700`) directory — so a concurrent writer or an external edit inside the watcher's debounce window is folded in rather than overwritten. An on-disk document that no longer parses fails the write instead of overwriting content the provider could not understand.
+
+Any string value round-trips, multi-line values included, so no entry is unwritable for want of a quoting style. An empty stored value is absent, per the seam rule — which is why an empty string in the document is rejected outright: `unset` removes a key, it does not blank it.
 
 ## Hot reload
 
-External edits publish `credentials/updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable file at boot fails loud. Keys that are not POSIX identifiers are preserved file content the seam cannot address.
+External edits publish `credentials/updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable or invalid document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable or invalid file at boot fails loud.
 
 ## Security boundary
 
-The document is `0600` under a `0700` directory, which stops other OS users — **not** the model. Tool processes (bash, the filesystem tools) run as the same user, and the shipped `workspace-write` file policy confines mutations rather than reads, so they can read this file exactly like any other file the user owns; no sandbox mode singles it out. What the harness does hold to is narrower: it never hands the model a resolved path to the document, and never loads it into the process environment (see [app-boot's Personal config](../../ui/app-boot/README.md#personal-config)), so reaching the value takes a deliberate read of a path the agent was not given.
+The document is `0600` under a `0700` directory, which stops other OS users — **not** the model. Tool processes (bash, the filesystem tools) run as the same user, and the shipped `workspace-write` file policy confines mutations rather than reads, so they can read this file exactly like any other file the user owns; no sandbox mode singles it out. What the harness does hold to is narrower: it never hands the model a resolved path to the document, and never loads it into the process environment — unlike `$DSH_HOME/.env`, which is the user's ordinary environment layer (see [app-boot's Personal config](../../ui/app-boot/README.md#personal-config)) — so reaching the value takes a deliberate read of a path the agent was not given.
 
 That is discretion, not a boundary. A deployment that must keep provider keys away from its own agent cannot get there with file permissions; an OS-keychain provider — a store the model's processes cannot read at all — is the deferred answer and belongs beside this provider as a sibling package.
 
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index 59c7fd5747..a8be536298 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -7,7 +7,7 @@
 | 层 | 来源 id | 可写 | 优先 |
 |---|---|---|---|
 | 活跃进程环境 | `env` | 否 | 恒定优先 |
-| `$DSH_HOME/.env` 文档 | `file` | 是（`set`/`unset`） | 其余情况 |
+| `$DSH_HOME/.credentials.yaml` 文档 | `file` | 是（`set`/`unset`） | 其余情况 |
 
 环境优先，因为启动时覆盖（`DEEPSEEK_API_KEY=… dsh`、CI 机密、加载了仓库 `.env` 的开发 shell）代表本次运行的操作者意图——而它无法从进程内部修改，就必须*可见地*只读：`describe()` 报告 `source: 'env', writable: false`，`set`/`unset` 直接拒绝，而不是写下一个读取方永远看不到的变更。解析实时读取 `process.env`，绝不写回。
 
@@ -15,24 +15,33 @@
 
 | 字段 | 默认值 | 含义 |
 |---|---|---|
-| `path` | `<harness home>/.env` | 凭据文档位置。 |
+| `path` | `<harness home>/.credentials.yaml` | 凭据文档位置。 |
 | `dshHome` | `$DSH_HOME` 或 `~/.dsh` | `path` 缺省时使用的 harness home。 |
 | `watch` | `true` | 热发布外部编辑。 |
 | `debounceMs` | `100` | watcher 写入稳定窗口。 |
 
 ## 文档本身
 
-dotenv 格式，用 `dotenv` 解析；写回用物理行级编辑器，保留一切不属于本次编辑的字节：`set` 原位改写该键的第一条赋值行、沿用该行自身的行尾（丢弃后续重复行——dotenv 按最后一条生效，重复行会反过来覆盖这次编辑），`unset` 只删除所属行，注释、无关行、CRLF 行尾，以及另一个键的引号多行值的续行，都逐字保留。每次写入都先在 [`dsh-atomic-write`](../../util/atomic-write/README.md) 的跨进程写锁下重读文档、把此前未观察到的一切发布出去，再在仅属主可访问（`0700`）的目录下以 `0600` 权限原子提交——因此并发写入者、或落在 watcher 防抖窗口内的外部编辑会被并入，而不是被覆盖。
+一个从凭据引用到值的 YAML mapping，除此之外别无他物：
 
-值按 dotenv 能逐字读回的最窄样式渲染——裸值，其次单引号（完全字面），再次双引号（仅限无反斜杠，双引号读取会展开转义）。任何样式都无法表示的值，以及已经跨越多个物理行的条目，都会响亮失败而不是被静默破坏。空的存储值等于不存在（seam 规则）。
+```yaml
+DEEPSEEK_API_KEY: sk-…
+OPENAI_API_KEY: sk-…
+```
+
+该文档只存放凭据，因此任何偏离都是拒绝，而不是跳过某个条目——被静默忽略的键读起来就是「我存进去的密钥没有生效」。非 mapping 的根、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败：启动时响亮失败，运行期热重载则告警并保留最后可用快照。没有 `version` 字段，也没有包装层；格式就是这个 mapping。
+
+写入是对已解析文档打补丁而不是重建，因此注释与所有未触及条目的排版都会保留。直接位于某条目上方的注释属于该条目的注解，会随它一起删除。每次写入都先在 [`dsh-atomic-write`](../../util/atomic-write/README.md) 的跨进程写锁下重读文档、把此前未观察到的一切发布出去，再在仅属主可访问（`0700`）的目录下以 `0600` 权限原子提交——因此并发写入者、或落在 watcher 防抖窗口内的外部编辑会被并入，而不是被覆盖。磁盘上已经无法解析的文档会让写入失败，而不是覆盖 provider 读不懂的内容。
+
+任何字符串值都能往返，包括多行值，因此不会再有条目因为缺少可用引号样式而不可写。空的存储值等于不存在（seam 规则）——这也正是文档中的空字符串被直接拒绝的原因：`unset` 删除键，而不是把它置空。
 
 ## 热重载
 
-外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。provider 自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读时保留最后可用快照并告警；文件不存在即空存储；启动时不可读则响亮失败。非 POSIX 标识符的键属于被保留的文件内容，seam 无法寻址。
+外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。provider 自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则响亮失败。
 
 ## 安全边界
 
-文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境（见 [app-boot 的个人配置](../../ui/app-boot/README.md#personal-config)），因此要拿到这个值，需要刻意去读一条并未交给 agent 的路径。
+文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的个人配置](../../ui/app-boot/README.md#personal-config)）——因此要拿到这个值，需要刻意去读一条并未交给 agent 的路径。
 
 这是审慎，不是边界。必须让提供方密钥远离自身 agent 的部署无法靠文件权限做到；OS 钥匙串 provider——一个模型的进程根本读不到的存储——才是延后的答案，它应当作为平级包与本 provider 并列。
 
diff --git a/packages/credentials/credentials-local/package.json b/packages/credentials/credentials-local/package.json
index 0b8924d7f2..644904676a 100644
--- a/packages/credentials/credentials-local/package.json
+++ b/packages/credentials/credentials-local/package.json
@@ -35,8 +35,8 @@
   },
   "dependencies": {
     "chokidar": "^4.0.3",
-    "dotenv": "^17.2.0",
-    "schemastery": "^3.18.0"
+    "schemastery": "^3.18.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-atomic-write": "workspace:^",
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index c11c2db20c..bc1214d11b 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -1,13 +1,19 @@
 /**
  * File-backed credentials provider layering the live process environment over
- * a `$DSH_HOME/.env` document. The environment is authoritative and read-only
- * (a launch-time override must win, and must be visibly read-only rather than
- * silently shadow writes); the file is the provider-managed writable source:
- * every write re-reads the document under a cross-process writer lock before
- * rewriting only its own line — preserving every other byte, physical line
- * endings and quoted multi-line values included — external edits hot-publish
- * through the seam, and each reload replaces the snapshot wholesale so a
- * deleted entry never lingers in memory.
+ * a `$DSH_HOME/.credentials.yaml` document. The environment is authoritative
+ * and read-only (a launch-time override must win, and must be visibly
+ * read-only rather than silently shadow writes); the file is the
+ * provider-managed writable source: every write re-reads the document under a
+ * cross-process writer lock before patching only its own key — comments and
+ * the formatting of every untouched entry survive — external edits
+ * hot-publish through the seam, and each reload replaces the snapshot
+ * wholesale so a deleted entry never lingers in memory.
+ *
+ * The document holds nothing but credentials, which is why it is a strict
+ * `CredentialRef`-to-string mapping rather than a dotenv file: a store the
+ * Harness owns and never materializes into the environment cannot also serve
+ * as the user's environment layer, and conflating the two is what made a
+ * non-secret in the old `$DSH_HOME/.env` silently unreachable.
  * @module @deepseek-ai/dsh-credentials-local
  */
 
@@ -16,15 +22,18 @@ import z from 'schemastery'
 import { watch as chokidarWatch } from 'chokidar'
 import { mkdir, readFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
-import { parse } from 'dotenv'
+import { Document, parseDocument } from 'yaml'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { Credentials, credentialRef } from '@deepseek-ai/dsh-credentials'
 import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/dsh-credentials'
 
+/** Basename of the credentials document inside the harness home. */
+export const CREDENTIALS_FILENAME = '.credentials.yaml'
+
 /** Plugin config: file location and hot-reload behavior. */
 export interface Config {
-  /** Credentials document path; defaults to `.env` under the harness home. */
+  /** Credentials document path; defaults to `.credentials.yaml` under the harness home. */
   path?: string
   /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */
   dshHome?: string
@@ -43,13 +52,13 @@ interface ResolvedSpec {
 
 /**
  * Resolve the runtime spec from plugin config: an explicit `path` wins,
- * otherwise the document lives at `<harness home>/.env`.
+ * otherwise the document lives at `<harness home>/.credentials.yaml`.
  * @param config - raw plugin config.
  * @returns the resolved file location and watch behavior.
  */
 export function resolveSpec(config: Config): ResolvedSpec {
   return {
-    filename: resolve(config.path ?? join(resolveDshHome(config.dshHome), '.env')),
+    filename: resolve(config.path ?? join(resolveDshHome(config.dshHome), CREDENTIALS_FILENAME)),
     watch: config.watch ?? true,
     debounceMs: config.debounceMs ?? 100,
   }
@@ -60,129 +69,64 @@ function isENOENT(error: unknown): boolean {
   return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT'
 }
 
-/** Values that survive a dotenv round-trip without quoting. */
-const BARE_VALUE = /^[A-Za-z0-9_@%+:,./-]+$/
-
-/** Whether a value contains C0 control characters (newlines included) no dotenv style reads back. */
-function hasControlCharacters(value: string): boolean {
-  for (const char of value) {
-    if (char.charCodeAt(0) < 0x20) return true
+/**
+ * Parse one credentials document into its entries. The document is a strict
+ * mapping of {@link CredentialRef} to non-empty string: a non-mapping root, a
+ * key that is not a POSIX identifier, a non-string value, and an empty string
+ * are all rejected rather than skipped, because this file holds nothing but
+ * credentials and a silently ignored entry reads as "the key I stored has no
+ * effect". Duplicate keys surface as parser errors. An empty document is an
+ * empty store.
+ * @param text - the document's text.
+ * @param filename - absolute path, quoted in errors.
+ * @returns the parsed entries, keyed by reference.
+ */
+export function parseCredentialsDocument(text: string, filename: string): Map<string, string> {
+  const document = parseDocument(text, { prettyErrors: true, uniqueKeys: true })
+  if (document.errors.length > 0) {
+    throw new Error(`credentials-local: invalid document at ${filename}: ${
+      document.errors.map(error => error.message).join('; ')}`)
   }
-  return false
+  const root: unknown = document.toJS() ?? {}
+  if (typeof root !== 'object' || root === null || Array.isArray(root)) {
+    throw new TypeError(`credentials-local: ${filename} must be a mapping of credential reference to value`)
+  }
+  const entries = new Map<string, string>()
+  for (const [key, value] of Object.entries(root as Record<string, unknown>)) {
+    // credentialRef throws on anything that is not a POSIX identifier, which
+    // is exactly the constraint a stored reference must satisfy to be
+    // addressable through the seam.
+    credentialRef(key)
+    if (typeof value !== 'string') {
+      throw new TypeError(`credentials-local: the value for "${key}" in ${filename} must be a string`)
+    }
+    if (value.length === 0) {
+      throw new Error(`credentials-local: the value for "${key}" in ${filename} is empty; remove the key instead`)
+    }
+    entries.set(key, value)
+  }
+  return entries
 }
 
 /**
- * Render one `KEY=value` line in the narrowest style dotenv reads back
- * verbatim: bare, then single quotes (fully literal), then double quotes
- * (safe only without backslashes, which double-quote reading expands).
- * A value no style can represent fails loud instead of corrupting silently.
+ * Render the next document text with one reference set or deleted. Editing
+ * the parsed document rather than rebuilding it keeps comments and the
+ * formatting of every untouched entry; an absent document starts a fresh one.
+ * @param text - the current document text, `undefined` while the file is absent.
+ * @param ref - the reference to write.
+ * @param value - the new value, or `undefined` to delete the key.
+ * @returns the text to persist.
  */
-function renderLine(ref: CredentialRef, value: string): string {
-  if (BARE_VALUE.test(value)) return `${ref}=${value}`
-  if (hasControlCharacters(value)) {
-    throw new Error(`credentials-local: the value for "${ref}" contains control characters the .env line format cannot represent`)
-  }
-  if (!value.includes('\'')) return `${ref}='${value}'`
-  if (!value.includes('"') && !value.includes('\\')) return `${ref}="${value}"`
-  throw new Error(`credentials-local: the value for "${ref}" mixes quoting no .env style can represent; edit the file directly`)
+function renderDocument(text: string | undefined, ref: CredentialRef, value: string | undefined): string {
+  // `text` only ever caches content that parsed successfully, so this re-parse
+  // for the mutable comment-preserving tree cannot fail.
+  const document = text === undefined ? new Document({}) : parseDocument(text)
+  if (value === undefined) document.deleteIn([ref])
+  else document.setIn([ref], value)
+  return document.toString()
 }
 
-/** Split text into physical lines with their terminators attached. */
-function physicalLines(text: string): string[] {
-  return text.length === 0 ? [] : text.split(/(?<=\n)/)
-}
-
-/** One physical line's content without its terminator. */
-function lineContent(line: string): string {
-  if (line.endsWith('\r\n')) return line.slice(0, -2)
-  if (line.endsWith('\n')) return line.slice(0, -1)
-  return line
-}
-
-/** One physical line's terminator (empty on a final unterminated line). */
-function lineTerminator(line: string): string {
-  return line.slice(lineContent(line).length)
-}
-
-/** An assignment line: optional export, a POSIX identifier, `=`, the value part. */
-const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/
-
-/** Quote characters dotenv reads across physical lines. */
-const MULTILINE_QUOTES = ['\'', '"', '`']
-
-/**
- * The quote character an assignment's value part opens without closing on its
- * own line — the following physical lines are that value's continuation, not
- * assignments — or `undefined` for a single-line value.
- */
-function opensMultiline(valuePart: string): string | undefined {
-  const trimmed = valuePart.trimStart()
-  const quote = trimmed[0]
-  if (quote === undefined || !MULTILINE_QUOTES.includes(quote)) return undefined
-  const rest = trimmed.slice(1)
-  const body = quote === '"' ? rest.replaceAll('\\"', '') : rest
-  return body.includes(quote) ? undefined : quote
-}
-
-/** Whether a continuation line closes the given quote. */
-function closesQuote(content: string, quote: string): boolean {
-  const body = quote === '"' ? content.replaceAll('\\"', '') : content
-  return body.includes(quote)
-}
-
-/**
- * Replace, insert, or delete one reference's assignment while preserving
- * every other byte: untouched lines keep their exact content and terminators
- * (CRLF included), and the physical lines inside another key's quoted
- * multi-line value are never mistaken for assignments. The first matching
- * assignment is rewritten in place with its own line ending; later duplicates
- * drop (dotenv reads the last one, so a surviving duplicate would override
- * the edit); an insert appends in the document's dominant ending style.
- */
-function upsertLine(text: string | undefined, ref: CredentialRef, rendered: string | undefined): string {
-  const lines = physicalLines(text ?? '')
-  const dominant = lines.some(line => line.endsWith('\r\n')) ? '\r\n' : '\n'
-  const out: string[] = []
-  let placed = false
-  let pendingQuote: string | undefined
-  for (const line of lines) {
-    const content = lineContent(line)
-    if (pendingQuote !== undefined) {
-      // Inside a quoted multi-line value: never an assignment, always kept.
-      if (closesQuote(content, pendingQuote)) pendingQuote = undefined
-      out.push(line)
-      continue
-    }
-    const match = ASSIGNMENT.exec(content)
-    if (match === null) {
-      out.push(line)
-      continue
-    }
-    const [, key, valuePart] = match
-    if (key !== ref) {
-      /* v8 ignore next -- the value group is `(.*)`, which always participates; the fallback only satisfies noUncheckedIndexedAccess */
-      pendingQuote = opensMultiline(valuePart ?? '')
-      out.push(line)
-      continue
-    }
-    // The write path refuses multi-line targets before rendering, so the
-    // matched assignment is single-line and drops or rewrites wholesale.
-    if (rendered !== undefined && !placed) {
-      out.push(`${rendered}${lineTerminator(line) === '' ? dominant : lineTerminator(line)}`)
-      placed = true
-    }
-  }
-  if (rendered !== undefined && !placed) {
-    const last = out[out.length - 1]
-    if (last !== undefined && lineTerminator(last) === '') {
-      out[out.length - 1] = `${last}${dominant}`
-    }
-    out.push(`${rendered}${dominant}`)
-  }
-  return out.join('')
-}
-
-/** File-backed credentials provider (`$DSH_HOME/.env`). */
+/** File-backed credentials provider (`$DSH_HOME/.credentials.yaml`). */
 export class CredentialsLocal extends Credentials {
   /* jscpd:ignore-start -- deliberate config-surface and lifecycle symmetry with
      settings-local (prefer symmetry for parallel values); extracting the shared
@@ -273,7 +217,7 @@ export class CredentialsLocal extends Credentials {
     const env = process.env[ref]
     if (env !== undefined && env.length > 0) return Promise.resolve({ value: env, source: 'env' })
     const stored = this.values.get(ref)
-    if (stored !== undefined && stored.length > 0) return Promise.resolve({ value: stored, source: 'file' })
+    if (stored !== undefined) return Promise.resolve({ value: stored, source: 'file' })
     return Promise.resolve(undefined)
   }
 
@@ -283,11 +227,7 @@ export class CredentialsLocal extends Credentials {
       return Promise.resolve({ configured: true, source: 'env', writable: false })
     }
     const stored = this.values.get(ref)
-    if (stored !== undefined && stored.length > 0) {
-      // A quoted multi-line value resolves fine but the line editor refuses to
-      // rewrite it, so writability must say what set() would actually do.
-      return Promise.resolve({ configured: true, source: 'file', writable: !stored.includes('\n') })
-    }
+    if (stored !== undefined) return Promise.resolve({ configured: true, source: 'file', writable: true })
     return Promise.resolve({ configured: false, writable: true })
   }
 
@@ -350,12 +290,7 @@ export class CredentialsLocal extends Credentials {
         await this.reconcileFromDisk()
         const existing = this.values.get(ref)
         if (value === undefined && existing === undefined) return
-        if (existing !== undefined && existing.includes('\n')) {
-          throw new Error(
-            `credentials-local: "${ref}" is a multi-line entry this line editor would corrupt; edit ${this.spec.filename} directly`,
-          )
-        }
-        const nextText = upsertLine(this.text, ref, value === undefined ? undefined : renderLine(ref, value))
+        const nextText = renderDocument(this.text, ref, value)
         // 0600: a document holding secrets is never world-readable.
         await writeFileAtomic(this.spec.filename, nextText, { mode: 0o600, dirMode: 0o700 })
         this.text = nextText
@@ -374,12 +309,16 @@ export class CredentialsLocal extends Credentials {
     if (env !== undefined && env.length > 0) {
       throw new Error(
         `credentials-local: "${ref}" is supplied read-only by the process environment, so ${verb} would be`
-        + ' shadowed; change the launching environment instead',
+        + ' shadowed; unset it in the launching environment (or in a loaded .env) instead',
       )
     }
   }
 
-  /** Boot read: an absent file is an empty store; any other failure is loud. */
+  /**
+   * Boot read: an absent file is an empty store; an invalid one fails the
+   * plugin's activation, because a credentials document that exists but
+   * cannot be trusted must never be treated as "no credentials stored".
+   */
   private async loadInitial(): Promise<void> {
     let text: string
     try {
@@ -388,8 +327,8 @@ export class CredentialsLocal extends Credentials {
       if (!isENOENT(error)) throw error
       return
     }
+    this.values = parseCredentialsDocument(text, this.spec.filename)
     this.text = text
-    this.values = new Map(Object.entries(parse(text)))
   }
 
   /* jscpd:ignore-start -- same deliberate mirror of settings-local's reload and
@@ -415,10 +354,10 @@ export class CredentialsLocal extends Credentials {
 
   /**
    * Compare the on-disk text against the cache and publish any difference
-   * into the seam. Absence publishes the empty store; an unreadable file
-   * throws, so each caller picks its policy — a reload warns and keeps the
-   * last good snapshot, a write fails loud. dotenv parsing is lenient by
-   * design and cannot fail.
+   * into the seam. Absence publishes the empty store; an unreadable or
+   * invalid document throws, so each caller picks its policy — a reload warns
+   * and keeps the last good snapshot, a write fails loud rather than
+   * overwriting a document it could not understand.
    */
   private async reconcileFromDisk(): Promise<void> {
     let text: string | undefined
@@ -429,7 +368,7 @@ export class CredentialsLocal extends Credentials {
       text = undefined
     }
     if (text === this.text || this.isClosed()) return
-    const next = text === undefined ? new Map<string, string>() : new Map(Object.entries(parse(text)))
+    const next = text === undefined ? new Map<string, string>() : parseCredentialsDocument(text, this.spec.filename)
     const changed = this.changedRefs(this.values, next)
     this.text = text
     this.values = next
@@ -437,21 +376,12 @@ export class CredentialsLocal extends Credentials {
   }
   /* jscpd:ignore-end */
 
-  /** Seam-addressable entries whose effective (non-empty) value changed. */
+  /** Entries whose stored value changed; the parser has already proven every key addressable. */
   private changedRefs(prev: Map<string, string>, next: Map<string, string>): CredentialRef[] {
     const changed: CredentialRef[] = []
     for (const key of new Set([...prev.keys(), ...next.keys()])) {
-      const before = prev.get(key)
-      const after = next.get(key)
-      const effectiveBefore = before !== undefined && before.length > 0 ? before : undefined
-      const effectiveAfter = after !== undefined && after.length > 0 ? after : undefined
-      if (effectiveBefore === effectiveAfter) continue
-      try {
-        changed.push(credentialRef(key))
-      } catch (_unaddressableKey) {
-        // A key that is not a POSIX identifier is preserved file content the
-        // seam cannot address, so no observer could ever see it change.
-      }
+      if (prev.get(key) === next.get(key)) continue
+      changed.push(credentialRef(key))
     }
     return changed
   }
diff --git a/packages/credentials/credentials-local/tests/drain.spec.ts b/packages/credentials/credentials-local/tests/drain.spec.ts
index baefbd52c5..9cf4e600fb 100644
--- a/packages/credentials/credentials-local/tests/drain.spec.ts
+++ b/packages/credentials/credentials-local/tests/drain.spec.ts
@@ -42,7 +42,7 @@ describe('write-drain teardown', () => {
     const dir = await mkdtemp(join(tmpdir(), 'dsh-credentials-drain-'))
     cleanups.push(() => rm(dir, { recursive: true, force: true }))
     const ctx = new Context()
-    const fiber = ctx.plugin(CredentialsLocal, { path: join(dir, '.env'), watch: false })
+    const fiber = ctx.plugin(CredentialsLocal, { path: join(dir, '.credentials.yaml'), watch: false })
     await fiber
     const service = ctx.credentials
 
diff --git a/packages/credentials/credentials-local/tests/local.spec.ts b/packages/credentials/credentials-local/tests/local.spec.ts
index 4ebaed1a0c..d5ffddc54d 100644
--- a/packages/credentials/credentials-local/tests/local.spec.ts
+++ b/packages/credentials/credentials-local/tests/local.spec.ts
@@ -42,29 +42,29 @@ function updates(ctx: Context): CredentialRef[] {
 }
 
 describe('resolveSpec', () => {
-  it('defaults to .env under the harness home with watching on', () => {
+  it('defaults to .credentials.yaml under the harness home with watching on', () => {
     const spec = resolveSpec({ dshHome: '/custom/home' })
-    expect(spec).toEqual({ filename: resolve('/custom/home/.env'), watch: true, debounceMs: 100 })
+    expect(spec).toEqual({ filename: resolve('/custom/home/.credentials.yaml'), watch: true, debounceMs: 100 })
   })
 
   it('lets an explicit path win over the home', () => {
-    const spec = resolveSpec({ path: '/etc/dsh/creds.env', dshHome: '/ignored', watch: false, debounceMs: 5 })
-    expect(spec).toEqual({ filename: resolve('/etc/dsh/creds.env'), watch: false, debounceMs: 5 })
+    const spec = resolveSpec({ path: '/etc/dsh/creds.yaml', dshHome: '/ignored', watch: false, debounceMs: 5 })
+    expect(spec).toEqual({ filename: resolve('/etc/dsh/creds.yaml'), watch: false, debounceMs: 5 })
   })
 })
 
 describe('layering and reads', () => {
   it('treats an absent file as an empty writable store', async () => {
     const dir = await tempDir()
-    const ctx = await boot({ path: join(dir, '.env'), watch: false })
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
     expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
     expect(await ctx.credentials.describe(KEY)).toEqual({ configured: false, writable: true })
   })
 
-  it('serves file entries, including export-prefixed and quoted values', async () => {
+  it('serves file entries alongside comments and quoted values', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, '# notes\nexport DSH_CRED_TEST=plain\nDSH_CRED_OTHER="with space"\n')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, '# notes\nDSH_CRED_TEST: plain\nDSH_CRED_OTHER: "with space"\n')
     const ctx = await boot({ path, watch: false })
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'plain', source: 'file' })
     expect(await ctx.credentials.resolve(OTHER)).toEqual({ value: 'with space', source: 'file' })
@@ -73,22 +73,22 @@ describe('layering and reads', () => {
 
   it('lets a non-empty process environment win read-only over the file', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, 'DSH_CRED_TEST=from-file\n')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_TEST: from-file\n')
     const ctx = await boot({ path, watch: false })
     vi.stubEnv('DSH_CRED_TEST', 'from-env')
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'from-env', source: 'env' })
     expect(await ctx.credentials.describe(KEY)).toEqual({ configured: true, source: 'env', writable: false })
   })
 
-  it('treats empty values as absent in both layers', async () => {
+  it('treats an empty environment value as absent, falling through to the file', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, 'DSH_CRED_TEST=\n')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_TEST: stored\n')
     const ctx = await boot({ path, watch: false })
     vi.stubEnv('DSH_CRED_TEST', '')
-    expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
-    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: false, writable: true })
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'stored', source: 'file' })
+    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: true, source: 'file', writable: true })
   })
 
   it('fails boot loud when the document exists but cannot be read', async () => {
@@ -100,110 +100,149 @@ describe('layering and reads', () => {
   })
 })
 
-describe('line-editing writes', () => {
-  it('appends a missing key to a fresh 0600 document and emits the commit', async () => {
+describe('document validation', () => {
+  // Every rejection below is a boot failure rather than a skipped entry: this
+  // document holds nothing but credentials, so an ignored key would read as
+  // "the secret I stored has no effect".
+  it.each([
+    ['a non-mapping root', 'just a string\n', /must be a mapping/],
+    ['a sequence root', '- DSH_CRED_TEST\n', /must be a mapping/],
+    ['a key that is not a POSIX identifier', 'not-a-ref: value\n', /credential ref/],
+    ['a non-string value', 'DSH_CRED_TEST: 123\n', /must be a string/],
+    ['an empty value', 'DSH_CRED_TEST: ""\n', /is empty/],
+    ['duplicate keys', 'DSH_CRED_TEST: one\nDSH_CRED_TEST: two\n', /invalid document/],
+    ['malformed yaml', 'DSH_CRED_TEST: "unterminated\n', /invalid document/],
+  ])('fails boot on %s', async (_case, text, message) => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, text)
+    const ctx = new Context()
+    await expect(ctx.plugin(CredentialsLocal, { path, watch: false })).rejects.toThrow(message)
+  })
+
+  it('reads an empty document as an empty store', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, '# nothing stored yet\n')
+    const ctx = await boot({ path, watch: false })
+    expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
+  })
+})
+
+describe('document writes', () => {
+  it('adds a missing key to a fresh 0600 document and emits the commit', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, watch: false })
     const seen = updates(ctx)
     await ctx.credentials.set(KEY, 'sk-fresh')
-    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_TEST=sk-fresh\n')
+    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_TEST: sk-fresh\n')
     expect((await stat(path)).mode & 0o777).toBe(0o600)
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'sk-fresh', source: 'file' })
     expect(seen).toEqual([KEY])
   })
 
-  it('rewrites one line in place, preserving every other byte and dropping duplicates', async () => {
+  it('patches one entry, preserving comments and every untouched entry', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, '# deployment notes\nFIRST=one\n\nDSH_CRED_TEST=old\nTRAILING=x\nDSH_CRED_TEST=older')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, '# deployment notes\nDSH_CRED_OTHER: keep\n\n# the one under edit\nDSH_CRED_TEST: old\n')
     const ctx = await boot({ path, watch: false })
     await ctx.credentials.set(KEY, 'new value!')
-    expect(await readFile(path, 'utf8')).toBe('# deployment notes\nFIRST=one\n\nDSH_CRED_TEST=\'new value!\'\nTRAILING=x\n')
+    expect(await readFile(path, 'utf8')).toBe(
+      '# deployment notes\nDSH_CRED_OTHER: keep\n\n# the one under edit\nDSH_CRED_TEST: new value!\n',
+    )
   })
 
-  it('quotes hostile values so they round-trip through a fresh provider', async () => {
+  it('round-trips values no dotenv line could represent', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, watch: false })
-    const singleQuoted = 'with "quote", back\\slash and space'
-    const doubleQuoted = "it's got an apostrophe"
-    await ctx.credentials.set(KEY, singleQuoted)
-    await ctx.credentials.set(OTHER, doubleQuoted)
+    const multiLine = 'line one\nline two'
+    const mixedQuotes = 'both \' and "'
+    await ctx.credentials.set(KEY, multiLine)
+    await ctx.credentials.set(OTHER, mixedQuotes)
     const reread = await boot({ path, watch: false })
-    expect(await reread.credentials.resolve(KEY)).toEqual({ value: singleQuoted, source: 'file' })
-    expect(await reread.credentials.resolve(OTHER)).toEqual({ value: doubleQuoted, source: 'file' })
+    expect(await reread.credentials.resolve(KEY)).toEqual({ value: multiLine, source: 'file' })
+    expect(await reread.credentials.resolve(OTHER)).toEqual({ value: mixedQuotes, source: 'file' })
+    expect(await reread.credentials.describe(KEY)).toEqual({ configured: true, source: 'file', writable: true })
   })
 
-  it('fails loud on values no .env quoting style reads back verbatim', async () => {
+  it('unsets only the owning entry, with its own annotation, and keeps an absent unset silent', async () => {
     const dir = await tempDir()
-    const ctx = await boot({ path: join(dir, '.env'), watch: false })
-    await expect(ctx.credentials.set(KEY, 'line one\nline two')).rejects.toThrow(/control characters/)
-    await expect(ctx.credentials.set(KEY, 'both \' and "')).rejects.toThrow(/mixes quoting/)
-  })
-
-  it('unsets only the owning line and keeps an absent unset silent', async () => {
-    const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, '# keep\nDSH_CRED_TEST=gone\nDSH_CRED_OTHER=stays\n')
+    const path = join(dir, '.credentials.yaml')
+    // Comments above an entry are that entry's annotation and go with it when
+    // it is removed — including anything above the document's first entry.
+    // Every other entry keeps its own comments.
+    await writeFile(path, '# about the doomed one\nDSH_CRED_TEST: gone\n# about the survivor\nDSH_CRED_OTHER: stays\n')
     const ctx = await boot({ path, watch: false })
     const seen = updates(ctx)
     await ctx.credentials.unset(KEY)
-    expect(await readFile(path, 'utf8')).toBe('# keep\nDSH_CRED_OTHER=stays\n')
+    expect(await readFile(path, 'utf8')).toBe('# about the survivor\nDSH_CRED_OTHER: stays\n')
     await ctx.credentials.unset(KEY)
     expect(seen).toEqual([KEY])
   })
 
-  it('rejects empty values, shadowed writes, and multi-line entries', async () => {
+  it('rejects empty values and writes the environment would shadow', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, 'DSH_CRED_TEST="line one\nline two"\n')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_TEST: stored\n')
     const ctx = await boot({ path, watch: false })
 
     await expect(ctx.credentials.set(KEY, '')).rejects.toThrow(/empty value/)
-    await expect(ctx.credentials.set(KEY, 'next')).rejects.toThrow(/multi-line/)
-    await expect(ctx.credentials.unset(KEY)).rejects.toThrow(/multi-line/)
 
     vi.stubEnv('DSH_CRED_TEST', 'shadowing')
     await expect(ctx.credentials.set(KEY, 'next')).rejects.toThrow(/shadowed/)
     await expect(ctx.credentials.unset(KEY)).rejects.toThrow(/shadowed/)
   })
 
-  it('leaves an empty document after unsetting the only entry', async () => {
+  it('leaves an empty mapping after unsetting the only entry', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, 'DSH_CRED_TEST=only\n')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_TEST: only\n')
     const ctx = await boot({ path, watch: false })
     await ctx.credentials.unset(KEY)
-    expect(await readFile(path, 'utf8')).toBe('')
+    expect(await readFile(path, 'utf8')).toBe('{}\n')
+    // The emptied document still reloads as an empty store, not a parse error.
+    const reread = await boot({ path, watch: false })
+    expect(await reread.credentials.resolve(KEY)).toBeUndefined()
+  })
+
+  it('fails a write loud when the on-disk document became invalid', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    const ctx = await boot({ path, watch: false })
+    // An external editor left the document unparsable: the read-modify-write
+    // must refuse rather than overwrite content it cannot understand.
+    await writeFile(path, 'DSH_CRED_TEST: "unterminated\n')
+    await expect(ctx.credentials.set(OTHER, 'lands')).rejects.toThrow(/invalid document/)
   })
 
   it('chains past a rejected write so one bad value cannot poison the queue', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, watch: false })
-    const bad = expect(ctx.credentials.set(KEY, 'both \' and "')).rejects.toThrow(/mixes quoting/)
+    const bad = expect(ctx.credentials.set(KEY, '')).rejects.toThrow(/empty value/)
     const good = ctx.credentials.set(OTHER, 'lands')
     await bad
     await good
-    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_OTHER=lands\n')
+    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_OTHER: lands\n')
   })
 
   it('serializes concurrent writes so both land in the one document', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, watch: false })
     await Promise.all([
       ctx.credentials.set(KEY, 'one'),
       ctx.credentials.set(OTHER, 'two'),
     ])
-    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_TEST=one\nDSH_CRED_OTHER=two\n')
+    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_TEST: one\nDSH_CRED_OTHER: two\n')
   })
 
   it('refuses writes after disposal', async () => {
     const dir = await tempDir()
     const ctx = new Context()
-    const fiber = ctx.plugin(CredentialsLocal, { path: join(dir, '.env'), watch: false })
+    const fiber = ctx.plugin(CredentialsLocal, { path: join(dir, '.credentials.yaml'), watch: false })
     await fiber
     // Capture the handle first: disposal also removes the ctx.credentials service.
     const service = ctx.credentials
@@ -215,20 +254,20 @@ describe('line-editing writes', () => {
 describe('real hot reload', () => {
   it('publishes external edits, replaces the snapshot wholesale, and suppresses self-writes', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
     // Watching starts on an existing document: creation racing watcher setup
     // is a chokidar readiness gap, not the reload contract under test.
-    await writeFile(path, 'DSH_CRED_TEST=boot\n')
+    await writeFile(path, 'DSH_CRED_TEST: boot\n')
     const ctx = await boot({ path, debounceMs: 10 })
     const seen = updates(ctx)
 
-    await writeFile(path, 'DSH_CRED_TEST=live\nDSH_CRED_OTHER=extra\n')
+    await writeFile(path, 'DSH_CRED_TEST: live\nDSH_CRED_OTHER: extra\n')
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'live', source: 'file' })
     })
 
     // Wholesale replacement: an entry deleted on disk never lingers in memory.
-    await writeFile(path, 'DSH_CRED_TEST=live\n')
+    await writeFile(path, 'DSH_CRED_TEST: live\n')
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(OTHER)).toBeUndefined()
     })
diff --git a/packages/credentials/credentials-local/tests/review-fixes.spec.ts b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
index 78e51c90e1..7d2f447e5a 100644
--- a/packages/credentials/credentials-local/tests/review-fixes.spec.ts
+++ b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
@@ -1,7 +1,7 @@
 // Third-review behaviors: read-modify-write under the writer lock (external
 // edits survive an API write), the contained credentials/updated fan-out (a
-// broken observer never fails a committed write), and the physical-line
-// editor's multi-line and CRLF discipline.
+// broken observer never fails a committed write), and the YAML document
+// editor's isolation between entries.
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
@@ -37,18 +37,18 @@ async function boot(config: ConstructorParameters<typeof CredentialsLocal>[1]):
 describe('read-modify-write', () => {
   it('folds an unobserved external edit into a write instead of overwriting it', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, watch: false })
     const seen: string[] = []
     ctx.on('credentials/updated', (ref) => { seen.push(ref) })
     await ctx.credentials.set(ALPHA, 'one')
     // The external edit has landed on disk but no watcher reported it (watch
     // is off — the same blind spot as a debounce window or a missed event).
-    await writeFile(path, `${ALPHA}=one\n${BETA}=external\n`)
+    await writeFile(path, `${ALPHA}: one\n${BETA}: external\n`)
     await ctx.credentials.set(ALPHA, 'two')
     const text = await readFile(path, 'utf8')
-    expect(text).toContain(`${BETA}=external`)
-    expect(text).toContain(`${ALPHA}=two`)
+    expect(text).toContain(`${BETA}: external`)
+    expect(text).toContain(`${ALPHA}: two`)
     // The fold published the unobserved entry before the write's own commit.
     expect(seen).toEqual([ALPHA, BETA, ALPHA])
     expect(await ctx.credentials.resolve(BETA)).toEqual({ value: 'external', source: 'file' })
@@ -56,7 +56,7 @@ describe('read-modify-write', () => {
 
   it('keeps both refs when two providers write the same document concurrently', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
     const first = await boot({ path, watch: false })
     const second = await boot({ path, watch: false })
     await Promise.all([
@@ -71,7 +71,7 @@ describe('read-modify-write', () => {
   it('creates the credentials directory owner-only', async () => {
     const dir = await tempDir()
     const home = join(dir, 'home')
-    const ctx = await boot({ path: join(home, '.env'), watch: false })
+    const ctx = await boot({ path: join(home, '.credentials.yaml'), watch: false })
     await ctx.credentials.set(ALPHA, 'one')
     expect((await stat(home)).mode & 0o777).toBe(0o700)
   })
@@ -80,7 +80,7 @@ describe('read-modify-write', () => {
 describe('contained update fan-out', () => {
   it('does not fail a committed set when a listener throws, and later listeners still run', async () => {
     const dir = await tempDir()
-    const ctx = await boot({ path: join(dir, '.env'), watch: false })
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
     ctx.on('credentials/updated', () => {
       throw new Error('observer boom')
     })
@@ -93,7 +93,7 @@ describe('contained update fan-out', () => {
 
   it('contains an async listener rejection', async () => {
     const dir = await tempDir()
-    const ctx = await boot({ path: join(dir, '.env'), watch: false })
+    const ctx = await boot({ path: join(dir, '.credentials.yaml'), watch: false })
     // An unknown-returning function keeps the typed surface legal while the
     // runtime value is still the rejected promise the containment must handle.
     const boom = (): unknown => Promise.reject(new Error('async observer boom'))
@@ -104,7 +104,7 @@ describe('contained update fan-out', () => {
 
   it('rethrows an invariant-coded failure after the commit and the remaining listeners', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, watch: false })
     ctx.on('credentials/updated', () => {
       throw Object.assign(new Error('forged relation'), { code: 'INVARIANT' })
@@ -114,78 +114,33 @@ describe('contained update fan-out', () => {
     await expect(ctx.credentials.set(ALPHA, 'one')).rejects.toThrow(/forged relation/)
     // Harness-fatal by design — but the write itself committed first.
     expect(second).toHaveBeenCalledWith(ALPHA)
-    expect(await readFile(path, 'utf8')).toContain(`${ALPHA}=one`)
+    expect(await readFile(path, 'utf8')).toContain(`${ALPHA}: one`)
     expect(await ctx.credentials.resolve(ALPHA)).toEqual({ value: 'one', source: 'file' })
   })
 })
 
-describe('physical-line editor', () => {
-  it('never mistakes a quoted multi-line continuation for an assignment', async () => {
+describe('document editor', () => {
+  it('leaves a sibling multi-line value untouched while patching one entry', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    const wrapped = `DSH_REVIEW_WRAPPED="line1\n${INNER}=looks-like-one\nline3"\n${ALPHA}=a\n`
+    const path = join(dir, '.credentials.yaml')
+    const wrapped = `DSH_REVIEW_WRAPPED: |-\n  line1\n  line2\n${ALPHA}: a\n`
     await writeFile(path, wrapped)
     const ctx = await boot({ path, watch: false })
     await ctx.credentials.set(ALPHA, 'b')
-    // The wrapped value survives byte-for-byte; only ALPHA's line changed.
-    const afterAlpha = await readFile(path, 'utf8')
-    expect(afterAlpha).toBe(`DSH_REVIEW_WRAPPED="line1\n${INNER}=looks-like-one\nline3"\n${ALPHA}=b\n`)
-    // Setting the inner-looking ref appends a real assignment; the
-    // continuation line inside the quoted value stays untouched.
-    await ctx.credentials.set(INNER, 'real')
-    const afterInner = await readFile(path, 'utf8')
-    expect(afterInner).toBe(`DSH_REVIEW_WRAPPED="line1\n${INNER}=looks-like-one\nline3"\n${ALPHA}=b\n${INNER}=real\n`)
-    expect(await ctx.credentials.resolve(INNER)).toEqual({ value: 'real', source: 'file' })
+    expect(await readFile(path, 'utf8')).toBe(`DSH_REVIEW_WRAPPED: |-\n  line1\n  line2\n${ALPHA}: b\n`)
+    expect(await ctx.credentials.resolve(credentialRef('DSH_REVIEW_WRAPPED')))
+      .toEqual({ value: 'line1\nline2', source: 'file' })
   })
 
-  it('preserves CRLF line endings on untouched and edited lines', async () => {
+  it('stores a value that looks like another entry without creating one', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, `# note\r\n${ALPHA}=a\r\n${BETA}=keep\r\n`)
+    const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, watch: false })
-    await ctx.credentials.set(ALPHA, 'b')
-    expect(await readFile(path, 'utf8')).toBe(`# note\r\n${ALPHA}=b\r\n${BETA}=keep\r\n`)
-    await ctx.credentials.set(INNER, 'new')
-    expect(await readFile(path, 'utf8')).toBe(`# note\r\n${ALPHA}=b\r\n${BETA}=keep\r\n${INNER}=new\r\n`)
-  })
-
-  it('terminates a final unterminated line before appending', async () => {
-    const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, `${ALPHA}=a`)
-    const ctx = await boot({ path, watch: false })
-    await ctx.credentials.set(BETA, 'b')
-    expect(await readFile(path, 'utf8')).toBe(`${ALPHA}=a\n${BETA}=b\n`)
-  })
-
-  it('rewrites a final unterminated assignment in the dominant ending style', async () => {
-    const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, `${ALPHA}=a`)
-    const ctx = await boot({ path, watch: false })
-    await ctx.credentials.set(ALPHA, 'b')
-    expect(await readFile(path, 'utf8')).toBe(`${ALPHA}=b\n`)
-  })
-
-  it('tracks a single-quoted multi-line value through its continuation', async () => {
-    const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, `DSH_REVIEW_SQ='line1\n${INNER}=shadow\nline3'\n`)
-    const ctx = await boot({ path, watch: false })
-    await ctx.credentials.set(ALPHA, 'x')
-    expect(await readFile(path, 'utf8'))
-      .toBe(`DSH_REVIEW_SQ='line1\n${INNER}=shadow\nline3'\n${ALPHA}=x\n`)
-  })
-
-  it('reports a multi-line entry as unwritable and refuses to edit it', async () => {
-    const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, `${ALPHA}="line1\nline2"\n`)
-    const ctx = await boot({ path, watch: false })
-    expect(await ctx.credentials.describe(ALPHA)).toEqual({ configured: true, source: 'file', writable: false })
-    await expect(ctx.credentials.set(ALPHA, 'flat')).rejects.toThrow(/multi-line entry/)
-    await expect(ctx.credentials.unset(ALPHA)).rejects.toThrow(/multi-line entry/)
-    // Resolution still serves the multi-line value.
-    expect(await ctx.credentials.resolve(ALPHA)).toEqual({ value: 'line1\nline2', source: 'file' })
+    // The stored text must stay a value: a quoted-scalar write that leaked its
+    // own structure would silently mint a credential nobody stored.
+    await ctx.credentials.set(ALPHA, `${INNER}: injected`)
+    const reread = await boot({ path, watch: false })
+    expect(await reread.credentials.resolve(ALPHA)).toEqual({ value: `${INNER}: injected`, source: 'file' })
+    expect(await reread.credentials.resolve(INNER)).toBeUndefined()
   })
 })
diff --git a/packages/credentials/credentials-local/tests/watcher.spec.ts b/packages/credentials/credentials-local/tests/watcher.spec.ts
index 6ff53252cf..8f34b09868 100644
--- a/packages/credentials/credentials-local/tests/watcher.spec.ts
+++ b/packages/credentials/credentials-local/tests/watcher.spec.ts
@@ -66,21 +66,21 @@ async function boot(config: ConstructorParameters<typeof CredentialsLocal>[1]):
 describe('watcher pipeline', () => {
   it('clamps the write-settle poll interval for a zero debounce', async () => {
     const dir = await tempDir()
-    await boot({ path: join(dir, '.env'), debounceMs: 0 })
+    await boot({ path: join(dir, '.credentials.yaml'), debounceMs: 0 })
     const [instance] = await fakeInstances()
     expect(instance!.options.awaitWriteFinish).toEqual({ stabilityThreshold: 0, pollInterval: 1 })
   })
 
   it('survives a watcher error and keeps publishing later edits', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, debounceMs: 5 })
     const [instance] = await fakeInstances()
 
     instance!.watcher.emit('error', new Error('watch backend failure'))
     expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
 
-    await writeFile(path, 'DSH_CRED_PIPE=arrived\n')
+    await writeFile(path, 'DSH_CRED_PIPE: arrived\n')
     instance!.watcher.emit('all', 'change', path)
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'arrived', source: 'file' })
@@ -89,8 +89,8 @@ describe('watcher pipeline', () => {
 
   it('keeps the last good snapshot when the file turns unreadable at runtime', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, 'DSH_CRED_PIPE=good\n')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_PIPE: good\n')
     const ctx = await boot({ path, debounceMs: 5 })
 
     await chmod(path, 0o000)
@@ -104,7 +104,7 @@ describe('watcher pipeline', () => {
 
   it('keeps the reload queue alive after an invariant violation escapes the fan-out', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, debounceMs: 5 })
     let arm = true
     ctx.on('credentials/updated', () => {
@@ -113,7 +113,7 @@ describe('watcher pipeline', () => {
     })
     const [instance] = await fakeInstances()
 
-    await writeFile(path, 'DSH_CRED_PIPE=first\n')
+    await writeFile(path, 'DSH_CRED_PIPE: first\n')
     instance!.watcher.emit('all', 'change', path)
     // The snapshot commits before the fan-out, so the value lands even though
     // the listener threw out of the refresh.
@@ -122,7 +122,7 @@ describe('watcher pipeline', () => {
     })
 
     arm = false
-    await writeFile(path, 'DSH_CRED_PIPE=second\n')
+    await writeFile(path, 'DSH_CRED_PIPE: second\n')
     instance!.watcher.emit('all', 'change', path)
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'second', source: 'file' })
@@ -131,8 +131,8 @@ describe('watcher pipeline', () => {
 
   it('quiesces the refresh pipeline before dispose completes', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, 'DSH_CRED_PIPE=initial\n')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_PIPE: initial\n')
     const ctx = new Context()
     const fiber = ctx.plugin(CredentialsLocal, { path, debounceMs: 5 })
     await fiber
@@ -142,7 +142,7 @@ describe('watcher pipeline', () => {
       if (disposed) postDisposeCommits += 1
     })
 
-    await writeFile(path, 'DSH_CRED_PIPE=changed\n')
+    await writeFile(path, 'DSH_CRED_PIPE: changed\n')
     const [instance] = await fakeInstances()
     // Two queued refreshes: dispose interrupts one mid-flight and the other
     // before it starts, so both closed guards must hold.
@@ -158,8 +158,8 @@ describe('watcher pipeline', () => {
 
   it('empties the snapshot when the document is deleted and emits the removals', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, 'DSH_CRED_PIPE=doomed\n')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_PIPE: doomed\n')
     const ctx = await boot({ path, debounceMs: 5 })
     const seen: string[] = []
     ctx.on('credentials/updated', (ref) => {
@@ -175,30 +175,39 @@ describe('watcher pipeline', () => {
     expect(seen).toEqual([KEY])
   })
 
-  it('publishes only seam-addressable keys and preserves the rest untouched', async () => {
+  it('keeps the last good snapshot when an external edit makes the document invalid', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, 'BAD-KEY=1\nDSH_CRED_PIPE=a\n')
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_PIPE: a\n')
     const ctx = await boot({ path, debounceMs: 5 })
     const seen: string[] = []
     ctx.on('credentials/updated', (ref) => {
       seen.push(ref)
     })
 
-    await writeFile(path, 'BAD-KEY=2\nDSH_CRED_PIPE=b\n')
+    // A key the seam cannot address is a rejection, not preserved content:
+    // this document holds nothing but credentials. A live reload must warn
+    // and keep serving the last good snapshot rather than take the process
+    // down or silently drop the entry it could not validate.
+    await writeFile(path, 'BAD-KEY: 2\nDSH_CRED_PIPE: b\n')
     const [instance] = await fakeInstances()
     instance!.watcher.emit('all', 'change', path)
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'a', source: 'file' })
+    expect(seen).toEqual([])
+
+    // Repairing the document resumes publishing.
+    await writeFile(path, 'DSH_CRED_PIPE: b\n')
+    instance!.watcher.emit('all', 'change', path)
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'b', source: 'file' })
     })
-    // The dash-named key is preserved file content the seam cannot address:
-    // its change publishes nothing and breaks nothing.
     expect(seen).toEqual([KEY])
   })
 
   it('treats an event for a still-absent file as a no-op', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
+    const path = join(dir, '.credentials.yaml')
     const ctx = await boot({ path, debounceMs: 5 })
     const [instance] = await fakeInstances()
     instance!.watcher.emit('all', 'add', path)
@@ -208,12 +217,12 @@ describe('watcher pipeline', () => {
 
   it('reconciles at watcher ready so a change during setup is not missed', async () => {
     const dir = await tempDir()
-    const path = join(dir, '.env')
-    await writeFile(path, `${KEY}=a\n`)
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, `${KEY}: a\n`)
     const ctx = await boot({ path, debounceMs: 5 })
     // Written after the initial load but before the watcher became active:
     // no 'all' event will ever fire for it.
-    await writeFile(path, `${KEY}=written-before-ready\n`)
+    await writeFile(path, `${KEY}: written-before-ready\n`)
     const [instance] = await fakeInstances()
     instance!.watcher.emit('ready')
     await vi.waitFor(async () => {
diff --git a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
index 25cf4f293b..6aecdcdaf7 100644
--- a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
@@ -48,7 +48,7 @@ async function boot(dir: string, config: object): Promise<Harness> {
   await ctx.plugin(LlmService)
   const settingsFiber = ctx.plugin(SettingsLocal, { path: join(dir, 'settings.yaml'), watch: false })
   await settingsFiber
-  await ctx.plugin(CredentialsLocal, { path: join(dir, '.env'), watch: false })
+  await ctx.plugin(CredentialsLocal, { path: join(dir, '.credentials.yaml'), watch: false })
   await ctx.plugin(LlmDeepSeek, config)
   return { ctx, settingsFiber }
 }
@@ -61,7 +61,7 @@ describe('request-level dynamic configuration', () => {
   it('routes the next request with the freshly resolved base URL and credential', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.env'), 'DEEPSEEK_API_KEY=first-key\n')
+    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: first-key\n')
     const serverA = await mockServer([{ kind: 'sse', events: textEvents }])
     const serverB = await mockServer([{ kind: 'sse', events: textEvents }])
     const { ctx } = await boot(dir, { baseURL: serverA.url })
@@ -81,7 +81,7 @@ describe('request-level dynamic configuration', () => {
   it('prefers a literal settings apiKey over the credential layers', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.env'), 'DEEPSEEK_API_KEY=file-key\n')
+    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: file-key\n')
     const server = await mockServer([{ kind: 'sse', events: textEvents }])
     const { ctx } = await boot(dir, { baseURL: server.url })
 
@@ -178,7 +178,7 @@ describe('request-level dynamic configuration', () => {
   it('falls back to the composition entry when settings detach', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.env'), 'DEEPSEEK_API_KEY=steady-key\n')
+    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: steady-key\n')
     const serverA = await mockServer([{ kind: 'sse', events: textEvents }])
     const serverB = await mockServer([{ kind: 'sse', events: textEvents }])
     const { ctx, settingsFiber } = await boot(dir, { baseURL: serverA.url })
diff --git a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
index 402f94441d..c8d596af74 100644
--- a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
@@ -2,7 +2,7 @@
  * Real-composition guard for the dynamic-configuration chain: LlmService,
  * settings-local, credentials-local, and llm-deepseek boot from a test-only
  * cordis.yml through the actual Loader + Include path, external edits of
- * settings.yaml and .env hot-publish through their providers, and the very
+ * settings.yaml and the credentials document hot-publish through their providers, and the very
  * next request carries the fresh base URL and credential. The same adapter
  * composition without settings or credentials entries keeps entry-config
  * behavior — the documented optional-inject fallback.
@@ -42,16 +42,16 @@ afterEach(async () => {
 
 async function loadComposition(
   options: { withDynamic: boolean; baseURL: string; reuseRoot?: string },
-): Promise<{ ctx: Context; settingsPath: string; envPath: string }> {
+): Promise<{ ctx: Context; settingsPath: string; credentialsPath: string }> {
   // A reused root is the restart case: the same harness home, its documents
   // exactly as the previous process left them.
   const fresh = options.reuseRoot === undefined
   root = options.reuseRoot ?? await mkdtemp(join(tmpdir(), 'dsh-llm-composition-'))
   const settingsPath = join(root, 'settings.yaml')
-  const envPath = join(root, '.env')
+  const credentialsPath = join(root, '.credentials.yaml')
   if (options.withDynamic && fresh) {
     await writeFile(settingsPath, '# personal settings\n')
-    await writeFile(envPath, 'DEEPSEEK_API_KEY=boot-key\n')
+    await writeFile(credentialsPath, 'DEEPSEEK_API_KEY: boot-key\n')
   }
 
   const configPath = join(root, 'cordis.yml')
@@ -68,7 +68,7 @@ async function loadComposition(
         '- id: credentials',
         "  name: '@deepseek-ai/dsh-credentials-local'",
         '  config:',
-        `    path: ${JSON.stringify(envPath)}`,
+        `    path: ${JSON.stringify(credentialsPath)}`,
         '    debounceMs: 10',
       ]
       : [],
@@ -103,15 +103,15 @@ async function loadComposition(
     config: { path: pathToFileURL(configPath).href },
   })
   await ctx.loader.await()
-  return { ctx, settingsPath, envPath }
+  return { ctx, settingsPath, credentialsPath }
 }
 
 describe('llm-deepseek real dynamic composition', () => {
-  it('boots from cordis.yml and routes the next request after external settings and .env edits', async () => {
+  it('boots from cordis.yml and routes the next request after external settings and credential edits', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const serverA = await mockServer([{ kind: 'sse', events: textEvents }])
     const serverB = await mockServer([{ kind: 'sse', events: textEvents }])
-    const { ctx, settingsPath, envPath } = await loadComposition({ withDynamic: true, baseURL: serverA.url })
+    const { ctx, settingsPath, credentialsPath } = await loadComposition({ withDynamic: true, baseURL: serverA.url })
 
     expect(ctx.get('settings')!.describe().map(entry => entry.ns)).toEqual([NS])
     await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
@@ -122,7 +122,7 @@ describe('llm-deepseek real dynamic composition', () => {
     await vi.waitFor(() => {
       expect((ctx.get('settings')!.get(NS) as { baseURL?: string }).baseURL).toBe(serverB.url)
     }, { timeout: 5000 })
-    await writeFile(envPath, 'DEEPSEEK_API_KEY=rotated-key\n')
+    await writeFile(credentialsPath, 'DEEPSEEK_API_KEY: rotated-key\n')
     await vi.waitFor(async () => {
       expect(await ctx.get('credentials')!.resolve(KEY_REF)).toEqual({ value: 'rotated-key', source: 'file' })
     }, { timeout: 5000 })
@@ -134,7 +134,7 @@ describe('llm-deepseek real dynamic composition', () => {
 
   it('keeps a stored key writable and rotatable across a real restart', async () => {
     // No ambient DEEPSEEK_API_KEY: the shipped surfaces no longer hoist
-    // $DSH_HOME/.env into process.env, so a stored key must stay file-sourced.
+    // the credentials document into process.env, so a stored key must stay file-sourced.
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const first = await mockServer([{ kind: 'sse', events: textEvents }])
     const second = await mockServer([{ kind: 'sse', events: textEvents }])
diff --git a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
index d13234f8db..2c60ba0e83 100644
--- a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
@@ -44,7 +44,7 @@ async function boot(dir: string, config: LlmPiAi.Config): Promise<Context> {
   })
   await ctx.plugin(LlmService)
   await ctx.plugin(SettingsLocal, { path: join(dir, 'settings.yaml'), watch: false })
-  await ctx.plugin(CredentialsLocal, { path: join(dir, '.env'), watch: false })
+  await ctx.plugin(CredentialsLocal, { path: join(dir, '.credentials.yaml'), watch: false })
   await ctx.plugin(LlmPiAi, config)
   return ctx
 }
@@ -53,7 +53,7 @@ describe('request-level dynamic profiles', () => {
   it('mounts bare and dormant, then registers routes the moment settings supply providers', async () => {
     vi.stubEnv('PI_DYNAMIC_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.env'), 'PI_DYNAMIC_KEY=pk-from-settings\n')
+    await writeFile(join(dir, '.credentials.yaml'), 'PI_DYNAMIC_KEY: pk-from-settings\n')
     const server = await mockServer([{ events: textEvents }])
     // The exact product posture: `- id: llm-pi-ai` with no config at all.
     const ctx = await boot(dir, {})
@@ -112,7 +112,7 @@ describe('request-level dynamic profiles', () => {
   it('rotates the per-request credential referenced by apiKeyEnv', async () => {
     vi.stubEnv('PI_DYNAMIC_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.env'), 'PI_DYNAMIC_KEY=pk-one\n')
+    await writeFile(join(dir, '.credentials.yaml'), 'PI_DYNAMIC_KEY: pk-one\n')
     const server = await mockServer([{ events: textEvents }, { events: textEvents }])
     const ctx = await boot(dir, {
       providers: { deepseek: { apiKeyEnv: 'PI_DYNAMIC_KEY', baseURL: server.url } },
diff --git a/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts b/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts
index 460e78b7c2..5d32a748ea 100644
--- a/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts
@@ -3,7 +3,7 @@
  * settings-local, credentials-local, and a bare `llm-pi-ai` row boot from a
  * test-only cordis.yml through the actual Loader + Include path, an external
  * edit of settings.yaml registers the route live, and the next request
- * carries the credential the .env supplies. A hand-mounted `ctx.plugin` cannot
+ * carries the credential the credentials document supplies. A hand-mounted `ctx.plugin` cannot
  * catch Loader export-shape failures, which is why the twin adapter has the
  * same guard.
  */
@@ -40,7 +40,7 @@ async function loadComposition(): Promise<{ ctx: Context; settingsPath: string }
   root = await mkdtemp(join(tmpdir(), 'dsh-pi-composition-'))
   const settingsPath = join(root, 'settings.yaml')
   await writeFile(settingsPath, '# personal settings\n')
-  await writeFile(join(root, '.env'), 'PI_COMPOSITION_KEY=key-from-store\n')
+  await writeFile(join(root, '.credentials.yaml'), 'PI_COMPOSITION_KEY: key-from-store\n')
 
   const configPath = join(root, 'cordis.yml')
   await writeFile(configPath, [
@@ -54,7 +54,7 @@ async function loadComposition(): Promise<{ ctx: Context; settingsPath: string }
     '- id: credentials',
     "  name: '@deepseek-ai/dsh-credentials-local'",
     '  config:',
-    `    path: ${JSON.stringify(join(root, '.env'))}`,
+    `    path: ${JSON.stringify(join(root, '.credentials.yaml'))}`,
     '    debounceMs: 10',
     '- id: llm-pi-ai',
     "  name: '@deepseek-ai/dsh-llm-pi-ai'",
diff --git a/packages/ui/app-boot/README.i18n.yaml b/packages/ui/app-boot/README.i18n.yaml
index d565f6f11c..be3bb757a4 100644
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/ui/app-boot/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/app-boot/README.md
-README.md: 7e0466c40583e6f5b22e0d5ef25d211d595c3216
-README.zh.md: abb796aaa9fd6f8e6ee0578423382ed7f23909ab
+README.md: 8636af748168f6d898d7b44da298636af3686001
+README.zh.md: 0d956a3f5734cd04694fb96a6c89468e99413ebc
diff --git a/packages/ui/app-boot/README.md b/packages/ui/app-boot/README.md
index 7e0466c405..8636af7481 100644
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -8,6 +8,7 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | Absolute config path; `snapshotMode === 'replay'` swaps a `cordis.yml`/`.yaml` basename for its sibling `cordis.snapshot.yml` |
 | `loadEnv(binName, dir?, warn?)` | Load the gitignored `.env` (Node `process.loadEnvFile`); absent file is fine, an unloadable one warns a single labelled line (default: stderr) |
+| `loadLayeredEnv(binName, cwd?, warn?)` | The `dsh` product CLI's user environment: `loadEnv` over the invoking directory, then over the Harness home, giving `user < project < inherited`. The home is resolved from the inherited environment first, so a project `.env` cannot redirect it |
 | `installFailLoud(binName, proc?, release?)` | Turn an unhandled boot or later Loader rejection into one labelled stderr line + `exit(1)`; the optional `release` teardown is awaited between the two (bounded by `FAIL_LOUD_RELEASE_TIMEOUT_MS`) so a terminal-owning surface restores the terminal before exit; returns the uninstaller (for tests) |
 | `FAIL_LOUD_RELEASE_TIMEOUT_MS` | How long `installFailLoud` waits for its `release` hook; a wedged disposer delays the fatal exit, never cancels it |
 | `assertEntriesLoaded(ctx, binName)` | Throw when a settled tree holds an enabled entry with no fiber, reporting every unresolved plugin name as a Cordis startup failure |
@@ -33,7 +34,7 @@ This package carries no loader hooks and no dev-mode surface. The [`dsh` app](..
 
 A developer's machine-local preferences live outside every repository in the Harness home (default `~/.dsh`, overridable via `$DSH_HOME`; the single root [`resolveDshHome`](../../util/paths/README.md) resolves), consumed by the `dsh` CLI's TUI, Web, and headless surfaces ([`apps/cli`](../../../apps/cli/README.md)); the demo bins boot their committed trees verbatim. Two optional files:
 
-- **`.env`** — the credential store of [`dsh-credentials-local`](../../credentials/credentials-local/README.md), read by that provider alone. No surface hoists it into `process.env`: doing so would make every stored key look like a read-only launch override on the next run, blocking rotation from the TUI and the web page. The environment layers are the ambient one and the invoking directory's `.env` (loaded by the bin; `process.loadEnvFile` never overrides), and a composition without the credential provider keeps resolving keys from those alone.
+- **`.env`** — the user's ordinary environment layer, loaded by the `dsh` bin through `loadLayeredEnv` beneath the invoking directory's `.env` and the inherited environment. It is plain environment with plain environment reach, not a secret boundary: what the Harness owns and isolates lives in `.credentials.yaml`, which no surface hoists. A key placed in this file therefore still resolves — as a read-only `env` layer that shadows the stored one and blocks rotation from the TUI and the web page.
 - **`config.yaml`** — loader overlay patches applied over the shipped default config, with the same semantics as the shipped surface overlays: an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount. A patch naming an entry id absent from the booted tree is a silent no-op. An empty or comments-only file throws (it parses to nothing, not to a list); disable the overlay with `[]` or by deleting the file.
 
 The TUI and Web keep `config.yaml` live through `watchPersonalPatches`; one-shot headless runs read only the startup value. The watcher targets the exact personal path even when the file or immediate parent does not exist, serializes bursts, and recomposes the personal patches inside the caller's layer order (surface overlay below, app-generated patches above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
@@ -52,5 +53,5 @@ No direct invalidation from `boot()`; a consumer that calls `addHarnessSourceSec
 
 - **Bare package specifiers depend on Loader internals** — production bins need Loader's optional native helper; an in-process caller without it must use resolvable relative/file specifiers or provide its own module-resolution hook.
 - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection.
-- **Environment loading is cwd-scoped and optional** — the helper loads one `.env` file and warns on failure; it does not search parents, merge profiles, or validate required variables.
+- **Environment loading is directory-scoped and optional** — each layer is one named directory's `.env`, and a failure warns; neither helper searches parents or validates required variables. `loadLayeredEnv` fixes its two layers at the invoking directory and the Harness home, so a caller wanting different layers composes `loadEnv` itself.
 - **Personal config is patch-shaped** — an id-targeted patch replaces the entry's whole `config` rather than deep-merging, so a personal override restates the base fields it keeps.
diff --git a/packages/ui/app-boot/README.zh.md b/packages/ui/app-boot/README.zh.md
index abb796aaa9..0d956a3f57 100644
--- a/packages/ui/app-boot/README.zh.md
+++ b/packages/ui/app-boot/README.zh.md
@@ -8,6 +8,7 @@
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | 生成绝对配置路径；当 `snapshotMode === 'replay'` 时，把 basename 为 `cordis.yml`/`.yaml` 的文件替换为同级 `cordis.snapshot.yml` |
 | `loadEnv(binName, dir?, warn?)` | 加载已被 git 忽略的 `.env`（Node `process.loadEnvFile`）；文件不存在不影响启动，文件无法加载时输出一行带标签的警告（默认写入 stderr） |
+| `loadLayeredEnv(binName, cwd?, warn?)` | `dsh` 产品 CLI（命令行界面）的用户环境：先对调用目录、再对 Harness home 调用 `loadEnv`，得到 `用户 < 项目 < 继承` 的层次。Harness home 先从继承的环境解析，因此项目 `.env` 无法改变它的指向 |
 | `installFailLoud(binName, proc?, release?)` | 将启动期或后续未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 `exit(1)`；两者之间会等待可选的 `release` 拆卸回调（以 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 为上限），使持有终端的界面能在退出前恢复终端；返回卸载函数（供测试使用） |
 | `FAIL_LOUD_RELEASE_TIMEOUT_MS` | `installFailLoud` 等待其 `release` 回调的时长；卡住的 disposer 只会延迟致命退出，而不会取消它 |
 | `assertEntriesLoaded(ctx, binName)` | 树结算后，如果其中存在已启用但没有 fiber 的条目，则抛出异常，并以 Cordis 启动故障的形式报告每个未解析插件的名称 |
@@ -33,7 +34,7 @@ Loader 并发挂载各个条目，因此当其他环节失败时，某个界面
 
 开发者的机器本地偏好位于所有仓库之外的 Harness home 中（默认 `~/.dsh`，可由 `$DSH_HOME` 覆盖；统一由根级 [`resolveDshHome`](../../util/paths/README.md) 解析），并由 `dsh` CLI（命令行界面）的 TUI、Web 和无头界面（[`apps/cli`](../../../apps/cli/README.md)）使用；demo bin 会原样启动仓库中提交的树。这里有两个可选文件：
 
-- **`.env`**：[`dsh-credentials-local`](../../credentials/credentials-local/README.md) 的凭据存储，只由该 provider 读取。没有任何表层会把它提升进 `process.env`：那样做会让每个已存密钥在下次运行时看起来都像只读的启动时覆盖，从而阻断从 TUI 与 Web 页面轮换密钥。环境层次由环境中的值与调用目录的 `.env` 构成（由 bin 加载；`process.loadEnvFile` 从不覆盖已有值），没有凭据 provider 的组合仍然只从这两者解析密钥。
+- **`.env`**：用户的普通环境层，由 `dsh` bin 经 `loadLayeredEnv` 加载，位于调用目录的 `.env` 与继承环境之下。它是具有普通环境作用域的普通环境值，而不是密钥边界：由 Harness 拥有并隔离的东西放在 `.credentials.yaml` 里，后者不会被任何表层提升。因此放进本文件的密钥仍然可以解析——但会作为只读的 `env` 层遮蔽已存储的那一份，并阻断从 TUI 与 Web 页面轮换密钥。
 - **`config.yaml`**：在发布的默认配置上应用 Loader overlay patch，语义与交付的 surface overlay 相同：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在已启动树中，则静默不执行任何操作。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用 overlay，请使用 `[]` 或删除该文件。
 
 TUI 和 Web 会持续应用 `config.yaml` 的变更，具体由 `watchPersonalPatches` 负责；一次性无头运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切的个人配置路径；它会串行处理突发变更，并按调用方的层次顺序重新组合个人 patch（surface overlay 在下、应用生成的 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
@@ -52,5 +53,5 @@ TUI 和 Web 会持续应用 `config.yaml` 的变更，具体由 `watchPersonalPa
 
 - **裸包 specifier 依赖 Loader 内部机制**：生产 bin 需要 Loader 的可选原生 helper；没有该 helper 的进程内调用方必须使用可解析的相对／file specifier，或提供自己的模块解析钩子。
 - **快照回放替换仅识别特定 basename**：只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
-- **环境加载局限于 cwd 且为可选操作**：helper 只加载一个 `.env` 文件，并在失败时发出警告；它不会搜索父目录、合并 profile 或验证必需变量。
+- **环境加载按目录划分且为可选操作**：每一层都是一个指定目录下的 `.env`，失败时发出警告；两个 helper 都不会搜索父目录，也不验证必需变量。`loadLayeredEnv` 的两层固定为调用目录与 Harness home，需要其他层次的调用方请自行组合 `loadEnv`。
 - **个人配置采用 patch 形式**：按 id 定位的 patch 会替换条目的整个 `config`，而不是深度合并，因此个人覆盖必须重述需要保留的基础字段。
diff --git a/packages/ui/app-boot/src/index.ts b/packages/ui/app-boot/src/index.ts
index 7f3579cda1..94a7aa2c7d 100644
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -1,6 +1,6 @@
 /**
  * Shared boot glue for the app bins (`dsh`, `dsh-cli-demo`, `dsh-acp-demo`): load the gitignored
- * `.env`, install the fail-loud Loader guards, resolve the config path (snapshot-aware), load the
+ * `.env` files, install the fail-loud Loader guards, resolve the config path (snapshot-aware), load the
  * optional personal overlay patches from the Harness home (`~/.dsh`), expose its path resolver to
  * config expressions, and drive the Cordis Loader against a leaf `cordis.yml` until the tree settles.
  * @module @deepseek-ai/dsh-app-boot
@@ -65,6 +65,36 @@ export function loadEnv(
   }
 }
 
+/**
+ * Load the dsh product CLI's user environment: the invoking directory's `.env`
+ * over the Harness home's `.env`, both under the inherited process
+ * environment. `process.loadEnvFile` never replaces a name that is already
+ * set, so loading the project file first and the user file second is what
+ * makes the layering `user < project < inherited`; the app-boot tests pin all
+ * three layers because that ordering is the whole contract.
+ *
+ * The Harness home is resolved from the inherited environment *before* either
+ * file loads, so a project `.env` can never redirect which user document is
+ * read. Only the product CLI layers these files: an SDK or example bin loads
+ * its own directory through {@link loadEnv} and must not inherit a developer's
+ * `$DSH_HOME`.
+ *
+ * These are ordinary environment values with ordinary environment reach. A
+ * secret the Harness should own and isolate belongs in the credentials
+ * document, which is never materialized here.
+ * @param binName - the diagnostic prefix on the warn lines.
+ * @param cwd - the invoking directory whose `.env` is the project layer.
+ * @param warn - sink for the one-line misconfiguration diagnostics.
+ */
+export function loadLayeredEnv(
+  binName: string, cwd: string = process.cwd(),
+  warn: (line: string) => void = line => void process.stderr.write(line),
+): void {
+  const home = resolveDshHome()
+  loadEnv(binName, cwd, warn)
+  loadEnv(binName, home, warn)
+}
+
 /** File inside the Harness home holding the personal loader overlay patches. */
 export const PERSONAL_CONFIG_FILENAME = 'config.yaml'
 
diff --git a/packages/ui/app-boot/tests/app-boot.spec.ts b/packages/ui/app-boot/tests/app-boot.spec.ts
index 96cad31ea3..ece98a9716 100644
--- a/packages/ui/app-boot/tests/app-boot.spec.ts
+++ b/packages/ui/app-boot/tests/app-boot.spec.ts
@@ -7,7 +7,7 @@ import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import {
   addHarnessSourceSection, assertEntriesActivated, assertEntriesLoaded, boot,
   FAIL_LOUD_RELEASE_TIMEOUT_MS, HARNESS_SOURCE_SECTION,
-  installFailLoud, loadEnv, loadOverlayPatches, resolveConfigPath, type FailLoudProcess,
+  installFailLoud, loadEnv, loadLayeredEnv, loadOverlayPatches, resolveConfigPath, type FailLoudProcess,
 } from '../src/index.ts'
 
 const NAME = 'dsh-test-bin'
@@ -86,6 +86,66 @@ describe('loadEnv', () => {
   })
 })
 
+describe('loadLayeredEnv', () => {
+  const NAMES = ['DSH_APP_BOOT_LAYERED_SHARED', 'DSH_APP_BOOT_LAYERED_USER', 'DSH_APP_BOOT_LAYERED_PROJECT'] as const
+
+  function clear(): void {
+    for (const name of NAMES) Reflect.deleteProperty(process.env, name)
+  }
+
+  it('layers user under project under the inherited environment', () => {
+    const home = tmp()
+    const project = tmp()
+    writeFileSync(join(home, '.env'), [
+      `${NAMES[0]}=user`,
+      `${NAMES[1]}=user-only`,
+      'DSH_APP_BOOT_LAYERED_INHERITED=user-loses',
+      '',
+    ].join('\n'))
+    writeFileSync(join(project, '.env'), [
+      `${NAMES[0]}=project`,
+      `${NAMES[2]}=project-only`,
+      'DSH_APP_BOOT_LAYERED_INHERITED=project-loses',
+      '',
+    ].join('\n'))
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    vi.stubEnv('DSH_APP_BOOT_LAYERED_INHERITED', 'inherited')
+    const warn = vi.fn()
+    try {
+      loadLayeredEnv(NAME, project, warn)
+      // Both files load; the project layer wins the name they share, and the
+      // inherited environment wins over both.
+      expect(process.env[NAMES[0]]).toBe('project')
+      expect(process.env[NAMES[1]]).toBe('user-only')
+      expect(process.env[NAMES[2]]).toBe('project-only')
+      expect(process.env['DSH_APP_BOOT_LAYERED_INHERITED']).toBe('inherited')
+      expect(warn).not.toHaveBeenCalled()
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('resolves the harness home before the project file can redirect it', () => {
+    const home = tmp()
+    const decoy = tmp()
+    const project = tmp()
+    writeFileSync(join(home, '.env'), `${NAMES[1]}=real-home\n`)
+    writeFileSync(join(decoy, '.env'), `${NAMES[1]}=decoy-home\n`)
+    writeFileSync(join(project, '.env'), `DSH_HOME=${decoy}\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    try {
+      loadLayeredEnv(NAME, project, vi.fn())
+      expect(process.env[NAMES[1]]).toBe('real-home')
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+})
+
 describe('installFailLoud', () => {
   function fakeProc(): FailLoudProcess & { handlers: Array<(err: unknown) => void>; written: string[]; exits: number[] } {
     const handlers: Array<(err: unknown) => void> = []
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5e27760b0d..a74fc2677f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2625,12 +2625,12 @@ importers:
       chokidar:
         specifier: ^4.0.3
         version: 4.0.3
-      dotenv:
-        specifier: ^17.2.0
-        version: 17.4.2
       schemastery:
         specifier: ^3.18.0
         version: link:../../../vendor/schemastery
+      yaml:
+        specifier: ^2.9.0
+        version: 2.9.0
     devDependencies:
       '@deepseek-ai/dsh-atomic-write':
         specifier: workspace:^
@@ -9776,10 +9776,6 @@ packages:
   dompurify@3.4.11:
     resolution: {integrity: sha512-zhlUV12GsaRzMsf9q5M254YhA4+VuF0fG+QFqu6aYpoGlKtz+w8//jBcGVYBgQkR5GHjUomejY84AV+/uPbWdw==}
 
-  dotenv@17.4.2:
-    resolution: {integrity: sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==}
-    engines: {node: '>=12'}
-
   dts-resolver@3.0.0:
     resolution: {integrity: sha512-1T1f+z+4tl9XD+m+0HBgWoL/nm0bOIffyWaUuUSBlFg/86IWvfx+wjNaO/ybU0AJzG9/Mi5hBUgGV6zCmWEN7Q==}
     engines: {node: ^22.18.0 || >=24.0.0}
@@ -14832,8 +14828,6 @@ snapshots:
     optionalDependencies:
       '@types/trusted-types': 2.0.7
 
-  dotenv@17.4.2: {}
-
   dts-resolver@3.0.0(oxc-resolver@11.20.0):
     optionalDependencies:
       oxc-resolver: 11.20.0

From 8ddc53f7a036acb3efcf0a26827e04bbe6830430 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Tue, 4 Aug 2026 15:25:04 +0800
Subject: [PATCH 020/516] feat(cli)!: complete --config on every surface and
 delete the personal overlay

$DSH_HOME/config.yaml was an implicit composition layer: if the file existed,
every launch applied an arbitrary Loader patch graph over the shipped tree,
kept live by a dedicated HMR watcher. Three costs came from the implicitness,
not the capability. A patch replaces its target row's whole config, so a file
written months ago pins that row to the field set it knew and every default
the shipped tree later adds silently stops applying. It competed with the
typed settings namespaces llm-deepseek and llm-pi-ai already register, so
which one wins was a function of layer order rather than meaning. And the
explicit escape hatch it was supposedly redundant with did not exist on every
surface: dsh -p, dsh meta, and dsh upgrade all rejected --config, so for them
the implicit file was the only composition route at all.

Complete the explicit layer first: --config and --config-replace now work on
every booting surface. A headless --config-replace tree must still mount a
webserver row, because that surface reaches its own agent over the same HTTP
gateway the browser uses; AppCLIEntry names that contract in the failure
instead of reporting a bare missing service.

Then delete the implicit one. PERSONAL_CONFIG_FILENAME, loadPersonalPatches,
watchPersonalPatches, and the config-only HMR row mounted for it are gone; a
file left at that path is inert, and --dump-config no longer reads the Harness
home. --config therefore stops *replacing* the personal overlay and simply
*is* the user overlay.

No migration: a user who wants the old behavior names the same file
(dsh --config ~/.dsh/config.yaml), which a shell alias makes permanent.
---
 ...26-07-20-dsh-cli-personal-config.i18n.yaml |   4 +-
 .../2026-07-20-dsh-cli-personal-config.md     |   4 +-
 .../2026-07-20-dsh-cli-personal-config.zh.md  |   4 +-
 ...7-29-shared-base-config-overlays.i18n.yaml |   4 +-
 .../2026-07-29-shared-base-config-overlays.md |   4 +-
 ...26-07-29-shared-base-config-overlays.zh.md |   4 +-
 ...emove-personal-composition-layer.i18n.yaml |   6 +
 ...08-04-remove-personal-composition-layer.md |  47 +++
 ...04-remove-personal-composition-layer.zh.md |  47 +++
 apps/cli/README.i18n.yaml                     |   4 +-
 apps/cli/README.md                            |  12 +-
 apps/cli/README.zh.md                         |  12 +-
 apps/cli/config/base.cordis.yml               |   4 +-
 apps/cli/src/app-cli-entry.ts                 |  95 +++---
 apps/cli/src/args.ts                          | 113 +++++---
 apps/cli/src/bin.ts                           |   6 +-
 apps/cli/src/dump-config.ts                   |  25 +-
 apps/cli/src/headless.ts                      |  10 +-
 apps/cli/src/tui.ts                           |  48 ++--
 apps/cli/src/web.ts                           |   3 +-
 apps/cli/tests/args.spec.ts                   |  26 +-
 apps/cli/tests/built-bin.e2e.ts               |  16 +-
 apps/cli/tests/tui-keyless-smoke.e2e.ts       |  52 ++--
 docs/user/guide/config.i18n.yaml              |   4 +-
 docs/user/guide/config.md                     |   2 +-
 docs/user/guide/config.zh.md                  |   2 +-
 examples/mcp-memory/README.i18n.yaml          |   4 +-
 examples/mcp-memory/README.md                 |   2 +-
 examples/mcp-memory/README.zh.md              |   2 +-
 .../cordis/repository-plugin/README.i18n.yaml |   4 +-
 packages/cordis/repository-plugin/README.md   |   4 +-
 .../cordis/repository-plugin/README.zh.md     |   4 +-
 packages/ui/app-boot/README.i18n.yaml         |   4 +-
 packages/ui/app-boot/README.md                |  18 +-
 packages/ui/app-boot/README.zh.md             |  18 +-
 packages/ui/app-boot/src/index.ts             | 150 ++--------
 .../ui/app-boot/tests/config-dump.spec.ts     |  12 +-
 .../ui/app-boot/tests/config-reload.spec.ts   |  16 +-
 .../ui/app-boot/tests/personal-config.spec.ts | 270 ------------------
 39 files changed, 416 insertions(+), 650 deletions(-)
 create mode 100644 .agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.i18n.yaml
 create mode 100644 .agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md
 create mode 100644 .agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.zh.md
 delete mode 100644 packages/ui/app-boot/tests/personal-config.spec.ts

diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index e4e9dfb93a..8bdb3fc8c0 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.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 .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
-2026-07-20-dsh-cli-personal-config.md: 1fa8cda2b34b58cc7a28b722872520b68a9b7009
-2026-07-20-dsh-cli-personal-config.zh.md: e70b8914cf005e0a2e54ba2b29d3b7def84b00db
+2026-07-20-dsh-cli-personal-config.md: 3770fdbcac038874c8beb3071217ef40942f8dfe
+2026-07-20-dsh-cli-personal-config.zh.md: dcecf8749b29fd1023516570490adf2b256d0b35
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
index 1fa8cda2b3..3770fdbcac 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
@@ -17,7 +17,7 @@ Two coupled pieces, aligned with the `apps/` assembly tier proposed by the `dsh
 **Personal config (`dsh-app-boot`).** The personal overlay lives in the Harness home — `$DSH_HOME`, else `~/.dsh` — resolved by the shared [`resolveDshHome`](../architecture/2026-07-24-single-harness-home-resolver.md) (`@deepseek-ai/dsh-paths`), the same single root skills and AGENTS.md resolve against. The dsh TUI, Web, and headless surfaces consume its two optional files; the demo bins boot their committed trees verbatim:
 
 - `.env` — loaded after the invoking directory's `.env`; `process.loadEnvFile` never overrides, so precedence is ambient > project `.env` > personal `.env`.
-- `config.yaml` — a top-level YAML array of `@cordisjs/plugin-include` `PatchOptions`, parsed with the include's own `!!js` dialect (`loadPersonalPatches`) and passed to `boot()`, which forwards it as the root include's `patches`. Patch semantics match the shipped surface overlays: an id-targeted patch replaces the named entry's whole `config`, `insert` appends entries, and an unmatched id is a silent no-op. The [repository Plugin integration](2026-07-30-config-only-repository-plugins.md) uses one shipped row to make an exact GitHub source list a config-only choice.
+- `config.yaml` — [removed with the personal composition layer](../simplification/2026-08-04-remove-personal-composition-layer.md); while it existed, a top-level YAML array of `@cordisjs/plugin-include` `PatchOptions`, parsed with the include's own `!!js` dialect (`loadPersonalPatches`) and passed to `boot()`, which forwarded it as the root include's `patches`. Patch semantics match the shipped surface overlays: an id-targeted patch replaces the named entry's whole `config`, `insert` appends entries, and an unmatched id is a silent no-op. The [repository Plugin integration](2026-07-30-config-only-repository-plugins.md) uses one shipped row to make an exact GitHub source list a config-only choice.
 - A missing file means no overlay; a present-but-unreadable, unparsable, or non-array file throws at boot (misconfiguration fails loud, never a silent skip).
 
 The PTY smoke's launcher isolates `$DSH_HOME` to a per-test directory, exactly as it already isolates `DSH_AGENTS_HOME`, so a developer's real personal overlay cannot leak into fixtures; only the dsh CLI reads personal config, so no other test launcher needed changes.
@@ -46,4 +46,4 @@ The TUI and Web register the exact personal path through Cordis HMR after boot.
 
 ## Testing
 
-`packages/ui/app-boot/tests/personal-config.spec.ts` pins parsing, startup application, exact-path add/failure/recovery/removal, last-good rollback, failure broadcast, and preservation of app-owned patches. `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` boots the real dsh bin with no overlay, a personal environment and UI patch, a config-only cached repository skill, and invalid personal YAML. Test launchers isolate `$DSH_HOME`, so a developer's real overlay cannot leak into fixtures.
+The overlay's own spec covered parsing, startup application, exact-path add/failure/recovery/removal, last-good rollback, failure broadcast, and preservation of app-owned patches; it was deleted with the layer. `apps/cli/tests/tui-keyless-smoke.e2e.ts` still boots the real dsh bin with no overlay, with a named `--config` environment and UI patch, with a config-only cached repository skill, and with invalid overlay YAML. Test launchers isolate `$DSH_HOME`, so a developer's real overlay cannot leak into fixtures.
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index e70b8914cf..dcecf8749b 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -17,7 +17,7 @@ Status: implemented
 **个人配置（`dsh-app-boot`）。** 个人 overlay 存放在 Harness home——`$DSH_HOME`，否则 `~/.dsh`——由共享的 [`resolveDshHome`](../architecture/2026-07-24-single-harness-home-resolver.md)（`@deepseek-ai/dsh-paths`）解析，与 skills、AGENTS.md 解析所依据的单一根目录相同。dsh 的 TUI、Web 和无头界面使用其中两个可选文件；各示例 bin 仍然逐字节按已提交的配置树启动：
 
 - `.env`——在调用目录的 `.env` 之后加载；`process.loadEnvFile` 从不覆盖已有值，因此优先级为环境变量 > 项目 `.env` > 个人 `.env`。
-- `config.yaml`——顶层 YAML 数组，元素为 `@cordisjs/plugin-include` 的 `PatchOptions`，用 include 自己的 `!!js` 方言解析（`loadPersonalPatches`）并传给 `boot()`，由它作为根 include 的 `patches` 转发。补丁语义与交付的 surface overlay 一致：按 id 定位的补丁替换该配置项的整个 `config`，`insert` 追加配置项，未匹配的 id 静默不执行任何操作。[仓库插件集成](2026-07-30-config-only-repository-plugins.md)通过一个已交付配置项，使精确 GitHub 源列表成为纯配置选择。
+- `config.yaml`——[已随个人 composition 层一并删除](../simplification/2026-08-04-remove-personal-composition-layer.md)；它存在期间是顶层 YAML 数组，元素为 `@cordisjs/plugin-include` 的 `PatchOptions`，用 include 自己的 `!!js` 方言解析（`loadPersonalPatches`）并传给 `boot()`，由它作为根 include 的 `patches` 转发。补丁语义与交付的 surface overlay 一致：按 id 定位的补丁替换该配置项的整个 `config`，`insert` 追加配置项，未匹配的 id 静默不执行任何操作。[仓库插件集成](2026-07-30-config-only-repository-plugins.md)通过一个已交付配置项，使精确 GitHub 源列表成为纯配置选择。
 - 文件缺失即无 overlay；文件存在但不可读、不可解析或非数组则在启动时抛出（配置错误响亮失败，绝不静默跳过）。
 
 PTY 冒烟测试的启动器把 `$DSH_HOME` 隔离到每个测试自己的目录，与它已有的 `DSH_AGENTS_HOME` 隔离方式完全一致，开发者真实的个人 overlay 不可能泄漏进 fixture；只有 dsh CLI 读取个人配置，因此其他测试启动器无需改动。
@@ -46,4 +46,4 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 
 ## Testing
 
-`packages/ui/app-boot/tests/personal-config.spec.ts` 固定解析、启动时应用、确切路径的新增／失败／恢复／移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` 启动真实 dsh bin，覆盖无 overlay、个人环境与 UI patch、纯配置的缓存 repository skill，以及无效个人 YAML。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
+该 overlay 自己的 spec 曾固定解析、启动时应用、确切路径的新增／失败／恢复／移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留；它已随该层一并删除。`apps/cli/tests/tui-keyless-smoke.e2e.ts` 仍然启动真实 dsh bin，覆盖无 overlay、点名 `--config` 的环境与 UI patch、纯配置的缓存 repository skill，以及无效的 overlay YAML。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
index b100535da6..90523174f6 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.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 .agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
-2026-07-29-shared-base-config-overlays.md: ee642cbc786bef708791fb58e655c5a3f0e9c4e7
-2026-07-29-shared-base-config-overlays.zh.md: b7fc9c6b121b8d0eb94d734af6bda6df45e25b1d
+2026-07-29-shared-base-config-overlays.md: 494adcfc9efe2c88a67efd8a7ad2e5e0a2a39b4d
+2026-07-29-shared-base-config-overlays.zh.md: 919350db03420f9a5190c96e02fe774b6d2cb346
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
index ee642cbc78..494adcfc9e 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
@@ -18,9 +18,9 @@ One shared base, one overlay per surface, composed as sibling patch lists.
 
 `apps/cli/config/base.cordis.yml` holds the 43 rows both surfaces mount. `apps/cli/config/tui.cordis.yml` and `apps/cli/config/web.cordis.yml` are **patch lists**, not trees: each states the handful of rows whose value is surface-specific and inserts its own rows. The launcher includes the base once and applies every overlay as a sibling patch list at **one** include level, because include patches never cross an include boundary — stacking overlays as nested includes would silently stop reaching base rows.
 
-Precedence is list order, last write winning per row: base, then the surface overlay, then either a `--config` overlay or the personal `~/.dsh/config.yaml`, then the launcher's own flag and profile patches.
+Precedence is list order, last write winning per row: base, then the surface overlay, then a `--config` overlay, then the launcher's own flag patches. The personal `~/.dsh/config.yaml` sat in the `--config` slot until it was [removed with the personal composition layer](../simplification/2026-08-04-remove-personal-composition-layer.md).
 
-`--config <path>` now applies an overlay **instead of** the personal overlay, so a demo or test tree never inherits the user's provider and model. `--config-replace <path>` boots a file as the entire tree, bypassing base, surface overlay, and personal overlay alike; that is what the old `--config` did, so trees like `examples/web-cordis` moved to the new flag. Both flags survive the `/resume` execve handoff, or resuming would silently change the agent.
+`--config <path>` applies an overlay over the shipped tree (at the time, **instead of** the personal overlay, so a demo or test tree never inherited the user's provider and model). `--config-replace <path>` boots a file as the entire tree, bypassing base, surface overlay, and personal overlay alike; that is what the old `--config` did, so trees like `examples/web-cordis` moved to the new flag. Both flags survive the `/resume` execve handoff, or resuming would silently change the agent.
 
 A patch replaces its target row's whole `config` rather than merging, which shapes the split: a row whose value differs per surface lives in the overlays, never in the base, so no row is patched by three layers at once. Session identity therefore cannot ride a config key at all — it moved to `dsh-agent-loop`'s `CONFIGURED_AGENT_IDENTITIES_KEY`, as [the launcher-owned identity note](../architecture/2026-07-28-launcher-owned-resume-identity.md) now records.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
index b7fc9c6b12..919350db03 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
@@ -18,9 +18,9 @@ Status: implemented
 
 `apps/cli/config/base.cordis.yml` 持有两个 surface 都会挂载的 43 个配置项。`apps/cli/config/tui.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 是 **patch 列表**，不是配置树：各自声明少数取值因 surface 而异的配置项，并 insert 自己的配置项。启动器只 include base 一次，并把每个 overlay 作为**同一** include 层级上的平级 patch 列表应用——因为 include patch 不会跨越 include 边界，把 overlay 堆叠成嵌套 include 会使其静默地无法触达 base 配置项。
 
-优先级即列表顺序，逐配置项后写者胜：base，然后是 surface overlay，接着是 `--config` overlay 或个人 `~/.dsh/config.yaml`，最后是启动器自身的 flag 与 profile patch。
+优先级即列表顺序，逐配置项后写者胜：base，然后是 surface overlay，接着是 `--config` overlay，最后是启动器自身的 flag patch。个人 `~/.dsh/config.yaml` 曾占据 `--config` 这一槽位，直到它[已随个人 composition 层一并删除](../simplification/2026-08-04-remove-personal-composition-layer.md)。
 
-`--config <path>` 现在应用一个 overlay 来**取代**个人 overlay，因此 demo 或测试用的树绝不会继承用户的 provider 与 model。`--config-replace <path>` 则把某个文件作为整棵树启动，同时绕过 base、surface overlay 与个人 overlay；这正是旧 `--config` 的行为，所以像 `examples/web-cordis` 这样的树改用了新 flag。两个 flag 都会在 `/resume` 的 execve 交接中保留，否则 resume 会静默更换 agent。
+`--config <path>` 在已交付配置树上应用一个 overlay（当时是**取代**个人 overlay，因此 demo 或测试用的树绝不会继承用户的 provider 与 model）。`--config-replace <path>` 则把某个文件作为整棵树启动，同时绕过 base、surface overlay 与个人 overlay；这正是旧 `--config` 的行为，所以像 `examples/web-cordis` 这样的树改用了新 flag。两个 flag 都会在 `/resume` 的 execve 交接中保留，否则 resume 会静默更换 agent。
 
 patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆分方式：取值因 surface 而异的配置项住在 overlay 中，绝不住在 base 里，从而没有任何配置项会被三层同时 patch。因此会话身份根本不能经由配置键传递——它迁移到了 `dsh-agent-loop` 的 `CONFIGURED_AGENT_IDENTITIES_KEY`，如[启动器持有身份的 note](../architecture/2026-07-28-launcher-owned-resume-identity.md) 现在所记录。
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.i18n.yaml
new file mode 100644
index 0000000000..11239d3c23
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.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-08-04-remove-personal-composition-layer.md
+2026-08-04-remove-personal-composition-layer.md: 941e2248e15e235037e6bd48dcb3ba6c80bd83dd
+2026-08-04-remove-personal-composition-layer.zh.md: 6c6f3ecd541590368624f4ed4bd409321a2f9772
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md
new file mode 100644
index 0000000000..941e2248e1
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md
@@ -0,0 +1,47 @@
+# Agent Note: Removing the personal composition layer
+
+Status: implemented
+
+English | [中文](2026-08-04-remove-personal-composition-layer.zh.md)
+
+## Problem
+
+`$DSH_HOME/config.yaml` was an implicit composition layer: if the file existed, every `dsh` launch applied an arbitrary Loader patch graph over the shipped tree, and the TUI and Web kept it live through a dedicated HMR watcher. Three costs followed from the implicitness rather than from the capability.
+
+A patch replaces its target row's whole `config`, so a personal file written months ago pins that row to the field set it knew. Every default the shipped tree later adds to that row silently stops applying, and nothing surfaces it short of running `--dump-config`. Applying that on every launch turns a one-time edit into a standing divergence.
+
+It also competed with typed settings for the same values. `llm-deepseek` and `llm-pi-ai` register settings namespaces, and the same fields are reachable by patching their rows — so which one wins is a function of layer order, not of what the value means. That is the ownership ambiguity the [user-settings seam](../architecture/2026-07-28-user-settings-seam.md) exists to remove.
+
+Finally the escape hatch it was supposed to be redundant with did not cover every surface: `dsh -p`, `dsh meta`, and `dsh upgrade` all rejected `--config`. For those surfaces the implicit file was not one composition route among two — it was the only one.
+
+## Decision
+
+The implicit layer is deleted and the explicit one is completed.
+
+**Every booting surface takes `--config` and `--config-replace`.** `dsh -p`, `dsh meta`, and `dsh upgrade` join the TUI, so naming a tree is available wherever a tree boots. A headless `--config-replace` tree must still mount a webserver row, because that surface reaches its own agent over the same HTTP gateway the browser uses; `AppCLIEntry` now names that contract in the failure instead of reporting a bare missing service.
+
+**`$DSH_HOME/config.yaml` is not read, watched, or dumped.** `PERSONAL_CONFIG_FILENAME`, `loadPersonalPatches`, `watchPersonalPatches`, and the config-only HMR row mounted for it are deleted. A file left at that path is inert. The Harness home keeps `settings.yaml`, `.credentials.yaml`, and `.env`; an overlay may still live there, but as a path to name, not a layer to discover.
+
+`--config` therefore changes meaning slightly: it used to *replace* the personal overlay, and now it simply *is* the user overlay. `--config-replace` is unchanged.
+
+Everyday capabilities keep their owners. Model and provider parameters already belong to the adapters' typed settings namespaces. The `repository-plugins` row ships mounted with an empty list, so a repository Plugin list is a `--config` overlay today and a settings namespace when one lands. MCP servers stay a `--config` composition, which is what [the CLI README](../../../../apps/cli/README.md) now documents.
+
+There is no migration and no deprecation diagnostic: the product is unreleased, and a user who wants the old behavior names the same file (`dsh --config ~/.dsh/config.yaml`), which a shell alias makes permanent.
+
+## Consequences
+
+- Given up: a composition that follows you across launches without being named. Restoring it is an alias, which is the point — the graph is now something a launch declares rather than something the machine holds.
+- Given up: live reload of a composition file. Settings and credentials keep their own watchers; a composition change now takes a restart, which is what `--config` already meant for every explicit tree.
+- Bought: one composition route instead of two, a shipped tree that cannot be silently pinned to a stale field set, and typed settings as the uncontested owner of the values they declare.
+- The [personal-config feature note](../feature/2026-07-20-dsh-cli-personal-config.md) is only partially superseded — the `dsh` CLI it introduced stands — so both notes stay cross-linked and its config-overlay facts were rewritten in place.
+- `--dump-config` prints the shipped base, the surface overlay, and any named `--config`; with no flag it prints the shipped composition alone, so the Harness home no longer changes what a dump shows.
+
+## Alternatives considered
+
+**Keep the file but stop watching it.** Rejected: the watcher is the smaller half. The standing cost is that an old patch list silently pins a shipped row on every launch, which a startup-only read preserves exactly.
+
+**Name the overlay from `settings.yaml` (`compositionOverlay: ~/.dsh/my.cordis.yml`).** Rejected, and worth stating because it looks like the best of both: it keeps the runtime property that motivated the removal — every launch applies an arbitrary plugin graph — and only changes the trigger from "file exists" to "field is set". Worse, `settings.yaml` is written by the product's own settings UI, so it would let a settings page edit the composition tree.
+
+**Delete it only after the settings-driven repository and MCP managers exist.** Rejected as an unnecessary dependency once `--config` reached every surface: the managers make those two cases *nicer*, but with the flag available everywhere, nothing is lost by removing the implicit layer first.
+
+**Keep it for `dsh -p` alone, where no flag existed.** Rejected: that is the surface with the strongest case for explicitness. A CI or scripted run should name its composition rather than inherit whatever the machine holds.
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.zh.md
new file mode 100644
index 0000000000..6c6f3ecd54
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.zh.md
@@ -0,0 +1,47 @@
+# Agent Note: 删除个人 composition 层
+
+Status: implemented
+
+[English](2026-08-04-remove-personal-composition-layer.md) | 中文
+
+## Problem
+
+`$DSH_HOME/config.yaml` 是一个隐式的 composition 层：只要该文件存在，每次 `dsh` 启动都会在已交付配置树上应用一张任意的 Loader patch 图，而 TUI 与 Web 还用一个专门的 HMR watcher 让它保持热更新。随之而来的三项代价来自「隐式」，而不是来自这项能力本身。
+
+patch 会替换目标行的整个 `config`，因此几个月前写下的个人文件会把那一行钉死在它当时知道的字段集上。此后交付端给该行新增的每个默认值都会静默失效，而除非跑 `--dump-config`，否则没有任何东西会暴露这一点。每次启动都应用它，等于把一次性编辑变成了长期偏离。
+
+它还在同一批值上与类型化 settings 争夺所有权。`llm-deepseek` 与 `llm-pi-ai` 都注册了 settings namespace，而同样的字段也能通过 patch 它们的行抵达——于是谁赢取决于层序，而不取决于这个值的语义。这正是 [user-settings seam](../architecture/2026-07-28-user-settings-seam.md) 要消除的所有权歧义。
+
+最后，本应与它互为冗余的那条显式通道并未覆盖所有界面：`dsh -p`、`dsh meta` 和 `dsh upgrade` 都拒绝 `--config`。对这些界面来说，隐式文件不是两条 composition 路径之一——它是唯一的一条。
+
+## Decision
+
+删掉隐式的那一层，并把显式的那一层补完整。
+
+**每个会启动的界面都接受 `--config` 与 `--config-replace`。** `dsh -p`、`dsh meta` 和 `dsh upgrade` 与 TUI 看齐，因此只要有配置树启动的地方，就能点名一棵树。无头模式下的 `--config-replace` 树仍必须挂载 webserver 行，因为该界面是通过浏览器所用的同一个 HTTP 网关访问自己的 agent 的；`AppCLIEntry` 现在会在失败信息里说明这条契约，而不是只报告某个服务缺失。
+
+**`$DSH_HOME/config.yaml` 不再被读取、监视或 dump。** `PERSONAL_CONFIG_FILENAME`、`loadPersonalPatches`、`watchPersonalPatches`，以及专为它挂载的那一行 config-only HMR，全部删除。留在该路径上的文件是惰性的。Harness home 仍然保有 `settings.yaml`、`.credentials.yaml` 和 `.env`；overlay 也仍然可以放在那里，但它是一条待点名的路径，而不是一层待发现的配置。
+
+因此 `--config` 的含义略有变化：它过去是*替代*个人 overlay，现在它本身*就是*用户 overlay。`--config-replace` 保持不变。
+
+日常能力各自保有归属。模型与 provider 参数已经属于各适配器的类型化 settings namespace。`repository-plugins` 行随交付配置以空列表挂载，因此仓库插件列表今天是一个 `--config` overlay，等 settings namespace 落地后归它。MCP 服务器仍然是 `--config` composition，这也是 [CLI README](../../../../apps/cli/README.md) 现在的写法。
+
+不做迁移，也不给弃用诊断：产品尚未发布，想要旧行为的用户点名同一个文件即可（`dsh --config ~/.dsh/config.yaml`），配一个 shell alias 就是永久的。
+
+## Consequences
+
+- 放弃的：一份无需点名就跨启动跟随你的 composition。恢复它只需一个 alias，而这正是重点——插件图现在由一次启动声明，而不是由机器持有。
+- 放弃的：composition 文件的热重载。settings 与凭据各自保留 watcher；composition 变更现在需要重启，而这本来就是 `--config` 对每一棵显式树的既有含义。
+- 换来的：只有一条 composition 路径而不是两条；已交付配置树不会被静默钉死在陈旧字段集上；类型化 settings 成为其所声明的值的唯一所有者。
+- [个人配置特性 Note](../feature/2026-07-20-dsh-cli-personal-config.md) 只被部分取代——它引入的 `dsh` CLI（命令行界面）仍然成立——因此两条 Note 保持互链，其中关于 config overlay 的事实已就地改写。
+- `--dump-config` 打印已交付基座、surface overlay 以及任何被点名的 `--config`；不带标志时只打印已交付组合，因此 Harness home 不再改变 dump 的内容。
+
+## Alternatives considered
+
+**保留该文件，只是不再监视它。** 否决：watcher 是较小的那一半。长期代价在于一份旧 patch 列表会在每次启动时静默钉死一个已交付行，而只在启动时读取恰恰完整保留了这一点。
+
+**从 `settings.yaml` 里点名 overlay（`compositionOverlay: ~/.dsh/my.cordis.yml`）。** 否决，且值得写明，因为它看起来两全其美：它保留了促成本次删除的那条运行时性质——每次启动都应用一张任意插件图——只是把触发条件从「文件存在」换成「字段已设置」。更糟的是，`settings.yaml` 由产品自己的设置界面写入，那等于让设置页面能编辑 composition 树。
+
+**等 settings 驱动的 repository 与 MCP manager 落地后再删。** 在 `--config` 覆盖所有界面之后，这条依赖已无必要，故否决：那两个 manager 会让这两种场景*更好用*，但只要标志处处可用，先删掉隐式层就不损失任何东西。
+
+**只为 `dsh -p` 保留它，因为那里原本没有标志。** 否决：那恰恰是最需要显式的界面。CI 或脚本化运行应当点名自己的 composition，而不是继承机器上恰好存在的东西。
diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index 96a4588f2c..44cb46a317 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/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 apps/cli/README.md
-README.md: 76d9ed65398322cb9244a31661ee59b60c23f793
-README.zh.md: 16a7a4ec52b830e45c32a61a103d87be5941ab3b
+README.md: 3195fb4856ec794186658afd5e329cd58e6a3b28
+README.zh.md: 011cacb347aff88f6a04544dcd9b5e9b8d434c18
diff --git a/apps/cli/README.md b/apps/cli/README.md
index 76d9ed6539..3195fb4856 100644
--- a/apps/cli/README.md
+++ b/apps/cli/README.md
@@ -7,11 +7,11 @@ Argv is parsed once through a [Commander](https://github.com/tj/commander.js) ad
 
 The TUI surface:
 
-- boots `base.cordis.yml` plus `tui.cordis.yml` through [`dsh-app-boot`](../../packages/ui/app-boot/README.md); `--config <path>` applies a patch-list overlay instead of the personal overlay, while `--config-replace <path>` boots that file as the complete tree;
+- boots `base.cordis.yml` plus `tui.cordis.yml` through [`dsh-app-boot`](../../packages/ui/app-boot/README.md); `--config <path>` applies a patch-list overlay over that tree, while `--config-replace <path>` boots the named file as the complete tree; every booting surface takes both flags;
 - resumes a persisted session with `dsh --resume <session-id>` and, when the Node host exposes `process.execve`, supplies the TUI's in-place handoff host: after selector preflight and current-session flush, the host disposes the app and replaces the process with a normalized resume invocation; runtimes without process replacement leave the session running and say so. This CLI owns session identity and the exit line rather than the config: it mints or selects the `main` session id and provides it, plus the exact command that reproduces this invocation, on the boot context ([`MAIN_SESSION_ID_KEY`](../../packages/ui/tui/README.md) and `TUI_GOODBYE_MESSAGE_KEY`). No `cordis.yml` key can drop resume, and a missing or unreadable id fails loud instead of creating a fresh session;
 - treats the **invoking directory** as the workspace — sessions, relative paths, and workspace instructions resolve from the cwd (`dsh meta` is the sole exception, below);
 - tells the agent where its own source lives: after boot it adds a prompt section naming this harness checkout, resolved from the launcher's real path so it holds under a PATH symlink and an arbitrary cwd, so the self-referential `cordis` toolset can read and modify it;
-- applies the personal overlay from `~/.dsh` (see [app-boot's Personal config](../../packages/ui/app-boot/README.md#personal-config)): `config.yaml` patches the booted tree, while `.env` there is the credential provider's own store (never hoisted into the environment, so keys stay rotatable). Environment precedence is ambient > project `.env`. The shipped tree's Cordis HMR keeps `config.yaml` live; an explicit `--config` tree replaces that overlay, and a tree without HMR reads it at startup only.
+- reads the Harness home (`~/.dsh`) for user state only (see [app-boot's Harness home](../../packages/ui/app-boot/README.md#the-harness-home)): `.env` is the user environment layer and `.credentials.yaml` is the credential provider's own store, never hoisted into the environment, so keys stay rotatable. Environment precedence is ambient > project `.env` > user `.env`. No composition file is discovered there: an overlay reaches a launch only through `--config`.
 - presents the [versioned first-run welcome](../../.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md) through the mounted TUI overlay service when its immutable marker is absent under `DSH_HOME`; only Enter creates that version's marker, while Escape, disposal, or process exit leaves it eligible. The official DeepSeek icon, responsive terminal rasters, all-locale Chinese copy, and notice version are static local owners; the overlay never writes a session event or model context.
 - registers bare `/compact`: while the agent is idle, it summarizes useful older history even below automatic pressure, rejects arguments, and reports success only after the standalone replacement bracket is durable. A prompt submitted during compaction keeps its queue identity and starts after that checkpoint; injected context remains visible.
 
@@ -19,13 +19,13 @@ The TUI surface:
 
 `dsh upgrade` is a guided fresh-session entry over the default TUI surface: it mints a fresh session in the invoking directory and seeds its first turn with the bundled `dsh-upgrade` skill, exactly as if the user typed `/skill:<name>`. The launcher passes the skill name on the boot context ([`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)), which the TUI auto-invokes once the chat is live. The command takes no options beyond the experimental gate — `--config`, `-p`, and `--resume` fail loud — and seeds only on this first launch, so a later `dsh --resume <id>` of the session is an ordinary TUI session with no re-injection.
 
-`dsh --dump-config` and `dsh web --dump-config` print the composed config tree — the shipped base, the surface overlay, and the `--config` or personal overlay, exactly the layers that surface would boot — as YAML on stdout and exit without booting; `--dump-default-config` stops at the surface overlay, so diffing the two shows precisely what the user layer changes. Each run of rows is preceded by a `# ==` comment naming the file it comes from and the layers that patched it (e.g. `# == base.cordis.yml, patched by tui.cordis.yml`), so the output shows provenance while staying one loadable document. Composition runs through the include's own patch algorithm and YAML dialect (`applyEntryPatches`/`entryListSchema` from `@cordisjs/plugin-include`), so the dump cannot drift from what boots; `!!js` expressions print verbatim and unevaluated, and a patch whose target row is absent is reported on stderr with its layer, mirroring the Loader's boot-time warning. Launcher-owned boot-context values (session identity, CLI-flag patches) are per-invocation facts outside the config tree and do not appear. The dump flags reject boot-only flags (`-p`, `--resume`, `--config-replace`) rather than silently ignoring them, and `--dump-default-config` takes no `--config`.
+`dsh --dump-config` and `dsh web --dump-config` print the composed config tree — the shipped base, the surface overlay, and any `--config` overlay, exactly the layers that surface would boot — as YAML on stdout and exit without booting; `--dump-default-config` stops at the surface overlay, so diffing the two shows precisely what the user layer changes. Each run of rows is preceded by a `# ==` comment naming the file it comes from and the layers that patched it (e.g. `# == base.cordis.yml, patched by tui.cordis.yml`), so the output shows provenance while staying one loadable document. Composition runs through the include's own patch algorithm and YAML dialect (`applyEntryPatches`/`entryListSchema` from `@cordisjs/plugin-include`), so the dump cannot drift from what boots; `!!js` expressions print verbatim and unevaluated, and a patch whose target row is absent is reported on stderr with its layer, mirroring the Loader's boot-time warning. Launcher-owned boot-context values (session identity, CLI-flag patches) are per-invocation facts outside the config tree and do not appear. The dump flags reject boot-only flags (`-p`, `--resume`, `--config-replace`) rather than silently ignoring them, and `--dump-default-config` takes no `--config`.
 
-The Web and headless surfaces boot `base.cordis.yml` plus `web.cordis.yml`, then apply `$DSH_HOME/config.yaml`; an explicit `--config <path>` replaces that personal overlay. Both surfaces otherwise share the same composition: both tell the coding agent its resolved model and session working directory, treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root <path>` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, opt into first-message model titles, use the same bounded transient model-request retry policy as the TUI, and mount a disposable in-memory SQLite content-index service. Web additionally names the DeepSeek Harness Web GUI as the interaction surface, this checkout as its own source location, and the process's canonical local URL and mode in both the prompt and managed `$DSH_WEB_URL`/`$DSH_WEB_MODE`; references such as “this page” therefore identify the GUI without claiming access to implicit DOM, route, or screenshot state. In production mode the host reads rebuilt frontend dist and client bundles on the next request, so refreshing the existing URL updates that GUI without replacing its process. `dsh web --dev` mounts the client-plugin HMR receiver, but no-refresh updates additionally require `pnpm run dev:web` in the same checkout to watch and rebuild plugin bundles; shell and ordinary package changes still require a rebuild and page refresh. Bare `apps/web` Vite serving fails before listening because it cannot inject `window.__DSH_BOOT__`. The index service is ACTIVE at boot, while its `node:sqlite` module and database handle open only on the first content search. This keeps Node 22 startup output free of SQLite's experimental warning before search is used; the first actual search may still emit the runtime warning. Each service instance owns its database, so parallel invocations neither share unsupported SQLite state nor leave derived index files behind, and the first search lazily reconciles live and persisted logs. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`).
+The Web and headless surfaces boot `base.cordis.yml` plus `web.cordis.yml`, then any `--config <path>` overlay. Both surfaces otherwise share the same composition: both tell the coding agent its resolved model and session working directory, treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root <path>` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, opt into first-message model titles, use the same bounded transient model-request retry policy as the TUI, and mount a disposable in-memory SQLite content-index service. Web additionally names the DeepSeek Harness Web GUI as the interaction surface, this checkout as its own source location, and the process's canonical local URL and mode in both the prompt and managed `$DSH_WEB_URL`/`$DSH_WEB_MODE`; references such as “this page” therefore identify the GUI without claiming access to implicit DOM, route, or screenshot state. In production mode the host reads rebuilt frontend dist and client bundles on the next request, so refreshing the existing URL updates that GUI without replacing its process. `dsh web --dev` mounts the client-plugin HMR receiver, but no-refresh updates additionally require `pnpm run dev:web` in the same checkout to watch and rebuild plugin bundles; shell and ordinary package changes still require a rebuild and page refresh. Bare `apps/web` Vite serving fails before listening because it cannot inject `window.__DSH_BOOT__`. The index service is ACTIVE at boot, while its `node:sqlite` module and database handle open only on the first content search. This keeps Node 22 startup output free of SQLite's experimental warning before search is used; the first actual search may still emit the runtime warning. Each service instance owns its database, so parallel invocations neither share unsupported SQLite state nor leave derived index files behind, and the first search lazily reconciles live and persisted logs. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`).
 
 The shared composition defaults new TUI, Web, and headless sessions to the `workspace-write` permission preset (`workspace-write` file mode plus `ask` approval policy). Sandbox-enforced bash and filesystem mutations may write only under the session workspace and platform temporary roots; reads, network access, and process visibility are not confined. The browser answers one-shot approval requests and exposes the Access picker; the TUI exposes `/permission`, but has no approval-request answerer, so an automatic wider retry there fails closed until the user deliberately changes the session preset. `DSH_PERMISSION_MODE` changes the process fallback, while a stored General-settings Permission value applies to later sessions without changing an open one.
 
-All three surfaces consume `$DSH_HOME/config.yaml`; the TUI and Web apply valid edits live, while one-shot headless runs read it at startup. The shipped trees include an empty `repository-plugins` row, so a standalone user can add prepared GitHub Plugins without an SDK project or install command:
+Every surface reads its `--config` overlay once at startup. The shipped trees include an empty `repository-plugins` row, so a standalone user can add prepared GitHub Plugins without an SDK project or install command, by naming an overlay such as `dsh --config ~/.dsh/plugins.yml`:
 
 ```yaml
 - id: repository-plugins
@@ -53,7 +53,7 @@ pnpm run dsh web --config apps/cli/config/core-web.cordis.yml
 
 Every `dsh` surface — TUI, Web, and headless — reports session telemetry by default (the row lives in the shared `base.cordis.yml`): every session-log event streams as OTLP/HTTP log records to `https://harness-telemetry.deepseeksvc.com/v1/logs` on a 10-second batch cadence. `DSH_TELEMETRY_OTLP_URL` points the exporter at a different collector; setting `DSH_TELEMETRY_DISABLED` to ANY non-empty value — including `0` or `false` — disables the row before it loads (a privacy switch prefers off-by-mistake over on-by-mistake). No redaction rule is mounted in this composition yet: exported records are the raw captured copy, including message text, tool arguments and results, and the session's working-directory path. The deployment rulings live in the [web-telemetry-default-mount Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md).
 
-MCP servers are not a shipped default, because a default would have to name one: `@deepseek-ai/dsh-mcp-client` mounts exactly one server per row and spawns it as a child process, outside `ctx.bash` and so outside the sandbox policy. The package is a runtime dependency of this CLI, so an installed `dsh` can mount your own servers from `$DSH_HOME/config.yaml` or a `--config` overlay without a source checkout:
+MCP servers are not a shipped default, because a default would have to name one: `@deepseek-ai/dsh-mcp-client` mounts exactly one server per row and spawns it as a child process, outside `ctx.bash` and so outside the sandbox policy. The package is a runtime dependency of this CLI, so an installed `dsh` can mount your own servers from a `--config` overlay without a source checkout:
 
 ```yaml
 - insert:
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 16a7a4ec52..011cacb347 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -7,11 +7,11 @@ Argv 只会通过 [Commander](https://github.com/tj/commander.js) 适配器（[`
 
 TUI 界面：
 
-- 通过 [`dsh-app-boot`](../../packages/ui/app-boot/README.md) 启动 `base.cordis.yml` 与 `tui.cordis.yml`；`--config <path>` 应用一个补丁列表覆盖并替代个人覆盖，而 `--config-replace <path>` 将指定文件作为完整配置树启动；
+- 通过 [`dsh-app-boot`](../../packages/ui/app-boot/README.md) 启动 `base.cordis.yml` 与 `tui.cordis.yml`；`--config <path>` 在该树之上应用一个补丁列表覆盖，而 `--config-replace <path>` 将指定文件作为完整配置树启动；每个会启动的界面都接受这两个标志；
 - 使用 `dsh --resume <session-id>` 恢复已持久化会话。当 Node 宿主公开 `process.execve` 时，还会提供 TUI 的原地移交宿主：选择器预检并刷新当前会话后，宿主会释放应用，并以规范化的恢复调用替换进程；不支持进程替换的运行时会让会话继续运行并给出提示。会话身份与退出行由本 CLI 拥有，而非由配置指定：它创建或选定 `main` 会话 id，并把该 id 以及可复现本次调用的确切命令一起提供到启动上下文（[`MAIN_SESSION_ID_KEY`](../../packages/ui/tui/README.md) 与 `TUI_GOODBYE_MESSAGE_KEY`）。任何 `cordis.yml` 键都无法移除恢复能力；缺失或无法读取的 id 会明确报错，而不会创建新会话；
 - 将 **调用目录** 视为 workspace：会话、相对路径和 workspace 指令都从 cwd 解析（`dsh meta` 是唯一例外，见下文）；
 - 告知 agent 自身源码所在位置：启动后添加一个命名此 harness checkout 的提示词段。该路径从启动器的真实路径解析，因此在 PATH 符号链接和任意 cwd 下仍然有效，使自指的 `cordis` 工具集可以读取并修改它；
-- 应用 `~/.dsh` 中的个人覆盖（参见 [app-boot 的个人配置](../../packages/ui/app-boot/README.md#personal-config)）：`config.yaml` 修补已启动的树，而那里的 `.env` 是凭据 provider 自己的存储（绝不会被提升进环境，因此密钥始终可轮换）。环境优先级为环境中已有的值 > 项目 `.env`。已交付配置树中的 Cordis HMR 会持续应用 `config.yaml` 的变更；显式 `--config` 配置树会替代该个人覆盖，未包含 HMR 的配置树只在启动时读取该文件。
+- 只把 Harness home（`~/.dsh`）当作用户状态来读取（参见 [app-boot 的 Harness home](../../packages/ui/app-boot/README.md#the-harness-home)）：`.env` 是用户环境层，`.credentials.yaml` 是凭据 provider 自己的存储，绝不会被提升进环境，因此密钥始终可轮换。环境优先级为环境中已有的值 > 项目 `.env` > 用户 `.env`。那里不会发现任何 composition 文件：overlay 只能通过 `--config` 抵达一次启动。
 - 当 `DSH_HOME` 下不存在不可变确认标记时，通过已挂载的 TUI overlay 服务呈现[版本化首次运行欢迎页](../../.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md)；只有 Enter 会创建该版本的标记，Escape、资源释放或进程退出仍保留展示资格。官方 DeepSeek 图标、响应式终端栅格图、所有 locale 共用的中文文案和通知版本均由静态本地文件持有；overlay 不会写入会话事件或模型上下文。
 - 注册裸 `/compact`：agent 空闲时，即使未达到自动压力，也会摘要有效的较早历史；该命令拒绝参数，并只在独立替换标记对持久化后报告成功。压缩（compaction）期间提交的提示词保留其队列身份，并在该检查点之后启动；注入的上下文仍保持可见。
 
@@ -19,13 +19,13 @@ TUI 界面：
 
 `dsh upgrade` 是默认 TUI 界面之上的引导式全新会话入口：它在调用目录中创建一个全新会话，并以内置 `dsh-upgrade` skill 播种其首轮，效果等同于用户手动键入 `/skill:<name>`。启动器将 skill 名称提供到启动上下文（[`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)），TUI 在聊天就绪后自动调用它。该命令除实验性门槛外不接受任何选项——`--config`、`-p`、`--resume` 都会明确报错——且仅在首次启动时播种，因此之后 `dsh --resume <id>` 恢复该会话时是普通 TUI 会话，不会重复注入。
 
-`dsh --dump-config` 和 `dsh web --dump-config` 把合成后的配置树——已交付的基础配置、界面覆盖层，以及 `--config` 或个人覆盖层，恰好是该界面启动时组装的那些层——以 YAML 打印到 stdout 后退出，不启动任何东西；`--dump-default-config` 止步于界面覆盖层，因此对两份输出做 diff 就能精确看出用户层改了什么。每段连续的行之前都有一条 `# ==` 注释，标明该段来自哪个文件以及被哪些层修补过（例如 `# == base.cordis.yml, patched by tui.cordis.yml`），因此输出既展示来源，又仍是一份可加载的文档。合成通过 include 自己的补丁算法和 YAML 方言（`@cordisjs/plugin-include` 的 `applyEntryPatches`/`entryListSchema`）完成，因此 dump 不可能与实际启动漂移；`!!js` 表达式原样打印、不求值，目标行不存在的补丁会连同其所在层报到 stderr，与 Loader 启动时的警告一致。由启动器持有的启动上下文值（会话身份、CLI 标志补丁）是每次调用的事实，位于配置树之外，不会出现。dump 标志会拒绝仅用于启动的标志（`-p`、`--resume`、`--config-replace`）而不是静默忽略它们，`--dump-default-config` 不接受 `--config`。
+`dsh --dump-config` 和 `dsh web --dump-config` 把合成后的配置树——已交付的基础配置、界面覆盖层，以及任何 `--config` 覆盖层，恰好是该界面启动时组装的那些层——以 YAML 打印到 stdout 后退出，不启动任何东西；`--dump-default-config` 止步于界面覆盖层，因此对两份输出做 diff 就能精确看出用户层改了什么。每段连续的行之前都有一条 `# ==` 注释，标明该段来自哪个文件以及被哪些层修补过（例如 `# == base.cordis.yml, patched by tui.cordis.yml`），因此输出既展示来源，又仍是一份可加载的文档。合成通过 include 自己的补丁算法和 YAML 方言（`@cordisjs/plugin-include` 的 `applyEntryPatches`/`entryListSchema`）完成，因此 dump 不可能与实际启动漂移；`!!js` 表达式原样打印、不求值，目标行不存在的补丁会连同其所在层报到 stderr，与 Loader 启动时的警告一致。由启动器持有的启动上下文值（会话身份、CLI 标志补丁）是每次调用的事实，位于配置树之外，不会出现。dump 标志会拒绝仅用于启动的标志（`-p`、`--resume`、`--config-replace`）而不是静默忽略它们，`--dump-default-config` 不接受 `--config`。
 
-Web 和无头界面启动 `base.cordis.yml` 与 `web.cordis.yml`，随后应用 `$DSH_HOME/config.yaml`；显式的 `--config <path>` 会替代该个人覆盖。除此之外，两者共享同一套组合：两者都会告知编码 agent 所用模型和会话工作目录，将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root <path>` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，选用首条消息模型标题，采用与 TUI 相同的有界暂时性模型请求重试策略，并挂载一个可丢弃的内存 SQLite 内容索引服务。Web 还会明确说明交互界面是 DeepSeek Harness Web GUI、当前 checkout 是自身源码位置，并在提示词及受管的 `$DSH_WEB_URL`/`$DSH_WEB_MODE` 中提供该进程的规范本地 URL 和模式；因此，「这个页面」等表述会指向该 GUI，但 agent 不会声称可以访问未显式提供的 DOM、路由或截图状态。在生产模式下，宿主会在下次请求时读取重新构建的前端 dist 和客户端 bundle，因此刷新现有 URL 即可更新该 GUI，无须替换其进程。`dsh web --dev` 会挂载客户端插件的 HMR（热模块替换）接收端，但要实现无刷新更新，还需在同一 checkout 中运行 `pnpm run dev:web`，以监视并重新构建插件 bundle；shell 和普通包（package）的更改仍需重新构建并刷新页面。直接使用裸 `apps/web` Vite 服务会在开始监听前失败，因为它无法注入 `window.__DSH_BOOT__`。索引服务在启动时处于 ACTIVE 状态，但其 `node:sqlite` 模块与数据库句柄分别要到首次内容搜索才会导入和打开。这样可使 Node 22 在尚未使用搜索时的启动输出不出现 SQLite 实验性警告；首次实际搜索仍可能发出运行时警告。每个服务实例独占自己的数据库，因此并行调用既不会共享不受支持的 SQLite 状态，也不会留下派生索引文件，首次搜索还会惰性对账实时日志与持久化日志。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。
+Web 和无头界面启动 `base.cordis.yml` 与 `web.cordis.yml`，随后应用任何 `--config <path>` 覆盖。除此之外，两者共享同一套组合：两者都会告知编码 agent 所用模型和会话工作目录，将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root <path>` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，选用首条消息模型标题，采用与 TUI 相同的有界暂时性模型请求重试策略，并挂载一个可丢弃的内存 SQLite 内容索引服务。Web 还会明确说明交互界面是 DeepSeek Harness Web GUI、当前 checkout 是自身源码位置，并在提示词及受管的 `$DSH_WEB_URL`/`$DSH_WEB_MODE` 中提供该进程的规范本地 URL 和模式；因此，「这个页面」等表述会指向该 GUI，但 agent 不会声称可以访问未显式提供的 DOM、路由或截图状态。在生产模式下，宿主会在下次请求时读取重新构建的前端 dist 和客户端 bundle，因此刷新现有 URL 即可更新该 GUI，无须替换其进程。`dsh web --dev` 会挂载客户端插件的 HMR（热模块替换）接收端，但要实现无刷新更新，还需在同一 checkout 中运行 `pnpm run dev:web`，以监视并重新构建插件 bundle；shell 和普通包（package）的更改仍需重新构建并刷新页面。直接使用裸 `apps/web` Vite 服务会在开始监听前失败，因为它无法注入 `window.__DSH_BOOT__`。索引服务在启动时处于 ACTIVE 状态，但其 `node:sqlite` 模块与数据库句柄分别要到首次内容搜索才会导入和打开。这样可使 Node 22 在尚未使用搜索时的启动输出不出现 SQLite 实验性警告；首次实际搜索仍可能发出运行时警告。每个服务实例独占自己的数据库，因此并行调用既不会共享不受支持的 SQLite 状态，也不会留下派生索引文件，首次搜索还会惰性对账实时日志与持久化日志。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。
 
 共享组合把新建 TUI、Web 和无头会话的权限默认设为 `workspace-write` preset（`workspace-write` 文件模式加 `ask` 审批策略）。由沙箱强制约束的 bash 与文件系统修改只能写入会话工作区和平台临时根目录；读取、网络访问和进程可见性不受该策略约束。浏览器可以应答一次性审批请求，并提供 Access 选择器；TUI 提供 `/permission`，但没有审批请求应答者，因此自动请求更宽权限的重试会以拒绝方式关闭，直到用户主动更改会话 preset。`DSH_PERMISSION_MODE` 会更改进程回退值，而「通用」设置中已存储的「权限」值只适用于之后的会话，不会更改已打开的会话。
 
-三个界面都会使用 `$DSH_HOME/config.yaml`；TUI 和 Web 实时应用有效编辑，而一次性无头运行只在启动时读取。已交付的配置树包含一个空的 `repository-plugins` 配置项，因此独立用户无需 SDK 项目或安装命令，只需配置即可添加已准备的 GitHub 插件：
+每个界面都只在启动时读取自己的 `--config` 覆盖。已交付的配置树包含一个空的 `repository-plugins` 配置项，因此独立用户无需 SDK 项目或安装命令，只要点名一个覆盖文件（例如 `dsh --config ~/.dsh/plugins.yml`）即可添加已准备的 GitHub 插件：
 
 ```yaml
 - id: repository-plugins
@@ -53,7 +53,7 @@ pnpm run dsh web --config apps/cli/config/core-web.cordis.yml
 
 每个 `dsh` 界面——TUI、Web 与无头——都默认上报会话遥测（该行位于共享的 `base.cordis.yml`）：每条会话日志事件以 OTLP/HTTP 日志记录的形式、按 10 秒批处理节奏流向 `https://harness-telemetry.deepseeksvc.com/v1/logs`。`DSH_TELEMETRY_OTLP_URL` 可将 exporter 指向其他 collector；将 `DSH_TELEMETRY_DISABLED` 设为**任意非空值**——包括 `0` 或 `false`——都会在该行加载前将其关停（隐私开关取「宁可误关、不可误开」）。该组合当前未挂载任何脱敏规则：导出记录即原始捕获副本，包含消息正文、工具参数与结果、以及会话工作目录路径。部署口径见 [web-telemetry-default-mount Agent Note](../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)。
 
-MCP 服务器不是交付默认值,因为默认值必须点名一台:`@deepseek-ai/dsh-mcp-client` 每一行只挂载一台服务器,并把它作为子进程 spawn,该进程不经 `ctx.bash`,因此也不受沙箱策略约束。该包是本 CLI 的运行时依赖,所以已安装的 `dsh` 无需源码检出即可从 `$DSH_HOME/config.yaml` 或 `--config` 覆盖层挂载你自己的服务器:
+MCP 服务器不是交付默认值,因为默认值必须点名一台:`@deepseek-ai/dsh-mcp-client` 每一行只挂载一台服务器,并把它作为子进程 spawn,该进程不经 `ctx.bash`,因此也不受沙箱策略约束。该包是本 CLI 的运行时依赖,所以已安装的 `dsh` 无需源码检出即可从 `--config` 覆盖层挂载你自己的服务器:
 
 ```yaml
 - insert:
diff --git a/apps/cli/config/base.cordis.yml b/apps/cli/config/base.cordis.yml
index d46e103426..aea2f8934c 100644
--- a/apps/cli/config/base.cordis.yml
+++ b/apps/cli/config/base.cordis.yml
@@ -1,7 +1,7 @@
 # The shared `dsh` core: every row both the TUI (`tui.cordis.yml`) and the web
 # surface (`web.cordis.yml`) mount identically. Neither surface includes the
 # other — each is a patch list applied over THIS file at one include level, so a
-# surface overlay, a `--config` overlay, and the personal `~/.dsh/config.yaml`
+# surface overlay and an explicit `--config` overlay
 # all address these rows by id. Patch lists stack in that order, last write
 # winning per row.
 #
@@ -22,7 +22,7 @@
   config:
     root: ['.']
 
-# `$DSH_HOME/config.yaml` replaces this row's config to select exact GitHub
+# A `--config` overlay replaces this row's config to select exact GitHub
 # repository Plugin generations. The app registers the DSH-owned runtime even
 # when the list is empty so a later personal-config edit can load
 # transactionally; one-shot headless runs consume the startup value only.
diff --git a/apps/cli/src/app-cli-entry.ts b/apps/cli/src/app-cli-entry.ts
index ba3105c3ef..95776484d0 100644
--- a/apps/cli/src/app-cli-entry.ts
+++ b/apps/cli/src/app-cli-entry.ts
@@ -16,13 +16,7 @@ import { resolve } from 'node:path'
 import { Context } from 'cordis'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import yaml from 'js-yaml'
-import {
-  boot,
-  installFailLoud,
-  loadOverlayPatches,
-  loadPersonalPatches,
-  watchPersonalPatches,
-} from '@deepseek-ai/dsh-app-boot'
+import { boot, installFailLoud, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
 // Empty type import carries the httpServer Context merge for the port read below.
 import type {} from '@deepseek-ai/dsh-host-webserver'
 
@@ -117,16 +111,18 @@ export interface AppCLIEntryOptions {
    * fields on the same row.
    */
   overlayPath: string
-  /**
-   * Optional explicit overlay applied after {@link overlayPath} and before
-   * this entry's own flag patches. When absent, the personal
-   * `$DSH_HOME/config.yaml` overlay is applied instead.
-   */
+  /** Optional `--config` overlay applied after {@link overlayPath} and before this entry's own flag patches. */
   extraOverlayPath?: string
+  /**
+   * Optional `--config-replace` tree: booted INSTEAD of {@link configPath},
+   * {@link overlayPath}, {@link extraOverlayPath}, and every generated patch,
+   * so the caller's file is the whole composition. It must still supply the
+   * serving rows this entry needs — {@link run} rejects a settled tree with no
+   * `httpServer`.
+   */
+  configReplacePath?: string
   /** Whether to append client-bundle HMR (the Web surface's prod/dev difference). */
   dev: boolean
-  /** Whether `$DSH_HOME/config.yaml` remains live after the initial boot. */
-  watchPersonalConfig: boolean
   /** --host when explicitly passed; undefined keeps the yml engineering default. */
   host?: string
   /**
@@ -176,8 +172,15 @@ export class AppCLIEntry {
     await this.bootTree()
     this.assertBoot()
     const port = this.ctx.get('httpServer')?.port
-    /* v8 ignore next -- the sweep above guarantees an ACTIVE webserver row */
-    if (port === undefined) throw new Error('dsh: httpServer service missing after settled boot')
+    if (port === undefined) {
+      // The shipped tree always carries the webserver row, so this is only
+      // reachable through --config-replace: name the missing contract rather
+      // than report a bare missing service.
+      throw new Error(
+        `dsh: no httpServer after booting ${this.bootConfigPath()}; this surface serves over HTTP, so a`
+        + ' --config-replace tree must mount a webserver row',
+      )
+    }
     return { ctx: this.ctx, port }
   }
 
@@ -188,6 +191,16 @@ export class AppCLIEntry {
    */
   private composePatches(): void {
     const rows = this.parseYmlRows()
+    if (this.options.configReplacePath !== undefined) {
+      // A replacement tree is the caller's whole composition: the generated
+      // patches target shipped row ids this file cannot assume exist, and a
+      // patch whose id is absent is a silent no-op rather than a diagnostic.
+      // Telemetry stays, judged against the tree actually booting, because a
+      // privacy switch that silently no-ops is worse than a loud one.
+      const replaceTelemetry = resolveTelemetryPatch(process.env.DSH_TELEMETRY_DISABLED, rows.has(TELEMETRY_ROW_ID))
+      this.patches = replaceTelemetry === undefined ? [] : [replaceTelemetry]
+      return
+    }
     const overrides = new Map<string, Record<string, unknown>>()
     const put = (entryId: string, key: string, value: unknown): void => {
       const bag = overrides.get(entryId) ?? {}
@@ -230,31 +243,26 @@ export class AppCLIEntry {
     // One include of the shared base with every overlay as a sibling patch
     // list: patches never cross an include boundary, so nesting them would
     // silently stop reaching base rows. The surface overlay applies first, then
-    // this entry's CLI-flag patches, which therefore win.
-    const compose = (overlay: PatchOptions[]): PatchOptions[] => [
-      ...loadOverlayPatches('dsh', this.options.overlayPath),
-      ...overlay,
-      ...this.patches,
-    ]
-    // An explicit --config overlay REPLACES the personal overlay, so there is
-    // then no personal layer to keep live — the watcher is personal-only.
-    const watchPersonal = this.options.watchPersonalConfig && this.options.extraOverlayPath === undefined
-    const patches = compose(
-      this.options.extraOverlayPath === undefined
-        ? loadPersonalPatches('dsh') ?? []
-        : loadOverlayPatches('dsh', this.options.extraOverlayPath),
-    )
-    this.ctx = await boot('dsh', resolve(this.options.configPath), patches, async (ctx) => {
+    // any --config overlay, then this entry's CLI-flag patches, which win.
+    // --config-replace discards all three and boots the named file alone.
+    const patches = this.options.configReplacePath !== undefined
+      ? this.patches
+      : [
+        ...loadOverlayPatches('dsh', this.options.overlayPath),
+        ...this.options.extraOverlayPath === undefined
+          ? []
+          : loadOverlayPatches('dsh', this.options.extraOverlayPath),
+        ...this.patches,
+      ]
+    this.ctx = await boot('dsh', resolve(this.bootConfigPath()), patches, async (ctx) => {
       await this.options.prepare?.(ctx)
-      // Config-only HMR for the personal overlay: module reload stays off for
-      // this surface (web.cordis.yml disables the shared `hmr` row until its
-      // reload lifecycle is tested), so this row watches no module roots.
-      if (watchPersonal) await ctx.loader.create({ name: '@cordisjs/plugin-hmr', config: { root: [] } })
       if (this.options.dev) await ctx.loader.create({ name: '@deepseek-ai/dsh-client-hmr' })
     })
-    if (watchPersonal) {
-      await watchPersonalPatches(this.ctx, { binName: 'dsh', compose })
-    }
+  }
+
+  /** The file the Loader includes: the replacement tree when named, otherwise the shared base. */
+  private bootConfigPath(): string {
+    return this.options.configReplacePath ?? this.options.configPath
   }
 
   /** Install the diagnostic for plugin rejections that happen after settled boot. */
@@ -270,6 +278,17 @@ export class AppCLIEntry {
    */
   private parseYmlRows(): Map<string, { config?: unknown }> {
     const rows = new Map<string, { config?: unknown }>()
+    // A replacement tree stands alone, so only its own rows are indexed —
+    // the telemetry-row check must judge the tree that actually boots.
+    if (this.options.configReplacePath !== undefined) {
+      for (const row of this.parseRowList(this.options.configReplacePath)) {
+        if (typeof row.id === 'string') rows.set(row.id, row)
+        for (const inserted of row.insert ?? []) {
+          if (typeof inserted.id === 'string') rows.set(inserted.id, inserted)
+        }
+      }
+      return rows
+    }
     const files = [this.options.configPath, this.options.overlayPath]
     if (this.options.extraOverlayPath !== undefined) files.push(this.options.extraOverlayPath)
     for (const file of files) {
diff --git a/apps/cli/src/args.ts b/apps/cli/src/args.ts
index 19bc58ccd4..e2ef70bd10 100644
--- a/apps/cli/src/args.ts
+++ b/apps/cli/src/args.ts
@@ -16,8 +16,8 @@ import { Command, CommanderError } from 'commander'
 
 /**
  * Interactive TUI: the default mode. `--config` applies an overlay over the
- * shipped composition in place of the personal one, `--config-replace` boots a
- * file as the whole tree instead, and `--resume <id>` rehydrates a session.
+ * shipped composition, `--config-replace` boots a file as the whole tree
+ * instead, and `--resume <id>` rehydrates a session.
  */
 interface TuiInvocation {
   mode: 'tui'
@@ -28,40 +28,49 @@ interface TuiInvocation {
 
 /**
  * Print the composed config tree and exit, without booting: `--dump-config`
- * composes the shipped base, the surface overlay, and the `--config` or
- * personal overlay — exactly the layers that surface would boot;
- * `--dump-default-config` stops at the surface overlay (the shipped tree, no
- * user layer).
+ * composes the shipped base, the surface overlay, and any `--config` overlay —
+ * exactly the layers that surface would boot; `--dump-default-config` stops at
+ * the surface overlay (the shipped tree, no user layer).
  */
 interface DumpConfigInvocation {
   mode: 'dump-config'
   surface: 'tui' | 'web'
-  /** Omit the `--config`/personal layer and print only the shipped composition. */
+  /** Omit the `--config` layer and print only the shipped composition. */
   defaultOnly: boolean
-  /** The `--config` overlay to compose instead of the personal one. */
+  /** The `--config` overlay to compose over the shipped tree. */
   config?: string
 }
 
-/** Headless one-shot: `dsh -p "task"`. */
+/**
+ * Headless one-shot: `dsh -p "task"`. `--config` and `--config-replace` mean
+ * exactly what they mean for the TUI, so an automated run can name its
+ * composition instead of depending on whatever the machine happens to hold.
+ */
 interface HeadlessInvocation {
   mode: 'headless'
   prompt: string
+  config?: string
+  configReplace?: string
 }
 
-/** Interactive fresh TUI over this harness checkout; accepts no default-surface options, only the experimental gate. */
+/** Interactive fresh TUI over this harness checkout; takes the composition flags and the experimental gate. */
 interface MetaInvocation {
   mode: 'meta'
+  config?: string
+  configReplace?: string
 }
 
 /**
  * Guided fresh-session entry: `dsh upgrade` seeds the first turn
- * with the `dsh-upgrade` skill. It always mints a
- * fresh session in the invoking directory and takes no options beyond the
- * experimental gate — `--resume`, `--config`, and `-p` are rejected as
- * mistyped, so there is nothing to carry.
+ * with the `dsh-upgrade` skill. It always mints a fresh session in the
+ * invoking directory, so `--resume` and `-p` are rejected as mistyped; the
+ * composition flags are accepted because the update runs against whatever
+ * tree the caller names.
  */
 interface SkillSessionInvocation {
   mode: 'upgrade'
+  config?: string
+  configReplace?: string
 }
 
 /**
@@ -184,9 +193,9 @@ Examples:
     // subcommand without a positional collision.
     .option('-p, --prompt <task>', 'answer this task without the interactive UI, then exit')
     .option('--resume <id>', 'continue a past session by id')
-    .option('--config <path>', 'apply this overlay of loader patches instead of the personal one')
-    .option('--config-replace <path>', 'boot this file as the entire tree, ignoring the shipped and personal configuration')
-    .option('--dump-config', 'print the composed config tree (base + surface + --config/personal overlay) and exit')
+    .option('--config <path>', 'apply this overlay of loader patches over the shipped configuration')
+    .option('--config-replace <path>', 'boot this file as the entire tree, ignoring the shipped configuration')
+    .option('--dump-config', 'print the composed config tree (base + surface + --config overlay) and exit')
     .option('--dump-default-config', 'print the shipped config tree (base + surface overlay, no user layer) and exit')
     .action((options: {
       config?: string
@@ -208,23 +217,24 @@ Examples:
       }
       if (options.prompt !== undefined) {
         // A headless prompt owns the invocation; an empty task has nothing to
-        // run, and --config/--resume are TUI inputs that must not silently
-        // vanish from a headless run.
+        // run, and --resume is a TUI input that must not silently vanish from
+        // a one-shot run. The composition flags DO apply: naming a tree is how
+        // an automated run pins its composition.
         if (options.prompt === '') program.error('error: --prompt needs a task')
-        if (options.config !== undefined || options.configReplace !== undefined || options.resume !== undefined) {
-          program.error('error: --prompt takes no --config, --config-replace, or --resume')
+        if (options.resume !== undefined) program.error('error: --prompt takes no --resume')
+        assertOneConfigFlag(options)
+        resolved = {
+          mode: 'headless',
+          prompt: options.prompt,
+          ...options.config !== undefined && { config: options.config },
+          ...options.configReplace !== undefined && { configReplace: options.configReplace },
         }
-        resolved = { mode: 'headless', prompt: options.prompt }
         return
       }
       // An empty --resume= id would silently start a fresh session downstream
       // (agent-loop treats '' as no-resume), so a mistyped resume must fail loud.
       if (options.resume === '') program.error('error: --resume needs a session id')
-      // The two config flags are mutually exclusive: one layers over the shipped
-      // tree, the other discards it, so accepting both would silently drop one.
-      if (options.config !== undefined && options.configReplace !== undefined) {
-        program.error('error: --config and --config-replace are mutually exclusive')
-      }
+      assertOneConfigFlag(options)
       resolved = {
         mode: 'tui',
         ...options.config !== undefined && { config: options.config },
@@ -233,10 +243,27 @@ Examples:
       }
     })
 
+  /**
+   * The two config flags are mutually exclusive on every surface that takes
+   * them: one layers over the shipped tree, the other discards it, so
+   * accepting both would silently drop one.
+   * @param options - the parsed options of the surface being resolved.
+   */
+  function assertOneConfigFlag(options: { config?: string; configReplace?: string }): void {
+    if (options.config !== undefined && options.configReplace !== undefined) {
+      program.error('error: --config and --config-replace are mutually exclusive')
+    }
+  }
+
+  /** The composition flags every booting surface registers, in one place so their help text cannot drift. */
+  const withConfigFlags = (command: Command): Command => command
+    .option('--config <path>', 'apply this overlay of loader patches over the shipped configuration')
+    .option('--config-replace <path>', 'boot this file as the entire tree, ignoring the shipped configuration')
+
   // Commander parses the parent (default-surface) options on either side of a
-  // subcommand into `program.opts()`. For a subcommand that shares none of them,
-  // a leaked config/prompt/resume option is a mistyped invocation that must fail
-  // loud rather than silently run and drop the input.
+  // subcommand into `program.opts()`. A subcommand takes its own flags after
+  // its own name, so a leaked parent config/prompt/resume option is a mistyped
+  // invocation that must fail loud rather than silently run and drop the input.
   const rejectParentOptions = (command: string): void => {
     const parent = program.opts<{
       config?: string
@@ -267,14 +294,18 @@ Examples:
   // come last. `upgrade` is a guided fresh-session entry: beyond the
   // experimental gate it takes no options and always mints a fresh session,
   // so nothing is left to carry.
-  program
-    .command('upgrade')
+  withConfigFlags(program.command('upgrade'))
     .description('update this dsh installation to the latest version (experimental)')
     .option('--experimental', 'acknowledge this subcommand is experimental')
-    .action((options: { experimental?: boolean }) => {
+    .action((options: { experimental?: boolean; config?: string; configReplace?: string }) => {
       rejectParentOptions('upgrade')
       requireExperimental('upgrade', options.experimental)
-      resolved = { mode: 'upgrade' }
+      assertOneConfigFlag(options)
+      resolved = {
+        mode: 'upgrade',
+        ...options.config !== undefined && { config: options.config },
+        ...options.configReplace !== undefined && { configReplace: options.configReplace },
+      }
     })
 
   // Host and port name no default: the CLI passes neither through when the flag
@@ -288,7 +319,7 @@ Examples:
     .option('--dev', 'mount the client-plugin HMR receiver (run pnpm run dev:web separately to rebuild bundles)')
     .option('--workspace-root <path>', 'parent directory for workspaces created from the browser UI')
     .option('--trusted-host <authority...>', 'extra authority the /api browser-trust fence accepts (host or host:port; repeatable)')
-    .option('--dump-config', 'print the composed config tree (base + web + --config/personal overlay) and exit')
+    .option('--dump-config', 'print the composed config tree (base + web + --config overlay) and exit')
     .option('--dump-default-config', 'print the shipped config tree (base + web overlay, no user layer) and exit')
     .action((options: WebOptions) => {
       rejectParentOptions('web')
@@ -300,14 +331,18 @@ Examples:
       resolved = resolveWeb(options)
     })
 
-  program
-    .command('meta')
+  withConfigFlags(program.command('meta'))
     .description('work on the dsh source that runs this command, from any directory (experimental)')
     .option('--experimental', 'acknowledge this subcommand is experimental')
-    .action((options: { experimental?: boolean }) => {
+    .action((options: { experimental?: boolean; config?: string; configReplace?: string }) => {
       rejectParentOptions('meta')
       requireExperimental('meta', options.experimental)
-      resolved = { mode: 'meta' }
+      assertOneConfigFlag(options)
+      resolved = {
+        mode: 'meta',
+        ...options.config !== undefined && { config: options.config },
+        ...options.configReplace !== undefined && { configReplace: options.configReplace },
+      }
     })
 
   try {
diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts
index dd5642de10..bdef3205b9 100644
--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -36,7 +36,7 @@ switch (invocation.mode) {
   }
   case 'headless': {
     const { runHeadless } = await import('./headless.ts')
-    await runHeadless(invocation.prompt)
+    await runHeadless(invocation.prompt, invocation.config, invocation.configReplace)
     break
   }
   case 'tui': {
@@ -51,12 +51,12 @@ switch (invocation.mode) {
   }
   case 'meta': {
     const { runTui, SOURCE_ROOT } = await import('./tui.ts')
-    await runTui(undefined, undefined, SOURCE_ROOT)
+    await runTui(invocation.config, undefined, SOURCE_ROOT, undefined, invocation.configReplace)
     break
   }
   case 'upgrade': {
     const { runTui } = await import('./tui.ts')
-    await runTui(undefined, undefined, undefined, `dsh-${invocation.mode}`)
+    await runTui(invocation.config, undefined, undefined, `dsh-${invocation.mode}`, invocation.configReplace)
     break
   }
   default:
diff --git a/apps/cli/src/dump-config.ts b/apps/cli/src/dump-config.ts
index 39a87c2dc8..80022a0efb 100644
--- a/apps/cli/src/dump-config.ts
+++ b/apps/cli/src/dump-config.ts
@@ -1,7 +1,7 @@
 /**
  * `dsh --dump-config` / `dsh web --dump-config` — print the composed config
  * tree without booting: the shipped base, the surface overlay, and (unless
- * `--dump-default-config`) the `--config` or personal overlay, composed
+ * `--dump-default-config`) any `--config` overlay, composed
  * through the include's own patch algorithm so the printed tree is exactly
  * what that surface would mount. `!!js` expressions print verbatim,
  * unevaluated — the dump shows composition, not one process's environment.
@@ -10,16 +10,13 @@
  * @module @deepseek-ai/dsh/dump-config
  */
 
-import { basename, join } from 'node:path'
+import { basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import {
   loadOverlayPatches,
-  loadPersonalPatches,
-  PERSONAL_CONFIG_FILENAME,
   renderConfigDump,
   type ConfigDumpLayer,
 } from '@deepseek-ai/dsh-app-boot'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 
 const NAME = 'dsh'
 
@@ -36,25 +33,17 @@ const SURFACE_OVERLAYS = {
  * separator naming the file each section of rows comes from (and the layers
  * that patched it).
  * @param surface - which surface overlay to compose over the shared base.
- * @param defaultOnly - stop at the surface overlay (no `--config`/personal layer).
- * @param config - the `--config` overlay path composed instead of the personal
- * one, or `undefined` to use `$DSH_HOME/config.yaml`.
+ * @param defaultOnly - stop at the surface overlay (no `--config` layer).
+ * @param config - the `--config` overlay path to compose over the shipped
+ * tree, or `undefined` for the shipped composition alone.
  */
 export function runDumpConfig(surface: 'tui' | 'web', defaultOnly: boolean, config?: string): void {
   const overlay = SURFACE_OVERLAYS[surface]
   const layers: ConfigDumpLayer[] = [
     { label: basename(overlay), patches: loadOverlayPatches(NAME, overlay) },
   ]
-  if (!defaultOnly) {
-    if (config === undefined) {
-      const personal = loadPersonalPatches(NAME)
-      // The personal file may be absent; the shipped layers still print.
-      if (personal !== undefined) {
-        layers.push({ label: join(resolveDshHome(), PERSONAL_CONFIG_FILENAME), patches: personal })
-      }
-    } else {
-      layers.push({ label: config, patches: loadOverlayPatches(NAME, config) })
-    }
+  if (!defaultOnly && config !== undefined) {
+    layers.push({ label: config, patches: loadOverlayPatches(NAME, config) })
   }
   process.stdout.write(renderConfigDump(NAME, BASE_CONFIG, layers))
 }
diff --git a/apps/cli/src/headless.ts b/apps/cli/src/headless.ts
index e41bc03c6c..5864604e05 100644
--- a/apps/cli/src/headless.ts
+++ b/apps/cli/src/headless.ts
@@ -9,6 +9,7 @@
  */
 
 import { fileURLToPath } from 'node:url'
+import { resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 import { InProcessApiClient, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
 import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
@@ -71,14 +72,19 @@ async function consumeUntilTurnEnd(frames: AsyncIterable<RpcRequest<MuxFrame>>,
  * is the non-empty prompt the argument adapter parsed from `-p`/`--prompt`
  * (the adapter rejects an empty task, so no guard is needed here).
  * @param task - the prompt text for the single turn.
+ * @param config - a `--config` overlay applied over the shipped composition, or `undefined`.
+ * @param configReplace - a `--config-replace` tree booted instead of the
+ * shipped composition, or `undefined`. It must mount a webserver row: this
+ * surface reaches its own agent over the same HTTP gateway the browser uses.
  */
-export async function runHeadless(task: string): Promise<void> {
+export async function runHeadless(task: string, config?: string, configReplace?: string): Promise<void> {
   // A missing DEEPSEEK_API_KEY throws here (plugin load is fail-loud, uncaught by design).
   const entry = new AppCLIEntry({
     configPath: fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url)),
     overlayPath: fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url)),
+    ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },
+    ...configReplace !== undefined && { configReplacePath: resolveConfigPath(configReplace, undefined) },
     dev: false,
-    watchPersonalConfig: false,
     port: 0,
   })
   const { ctx, port } = await entry.run()
diff --git a/apps/cli/src/tui.ts b/apps/cli/src/tui.ts
index f91ea05c4e..20981dc068 100644
--- a/apps/cli/src/tui.ts
+++ b/apps/cli/src/tui.ts
@@ -1,9 +1,9 @@
 /**
  * `dsh` default surface — the interactive TUI coding agent. Boots the shipped
- * shared base and TUI overlay, followed by either `--config` or the personal overlay
- * from the Harness home (`~/.dsh`): its `.env` fills environment gaps (precedence:
- * ambient environment, then the invoking directory's `.env`, then the personal one)
- * and its `config.yaml` patches the booted tree. The workspace is the invoking
+ * shared base and TUI overlay, followed by any `--config` overlay. The Harness
+ * home (`~/.dsh`) contributes the user environment layer only: its `.env` fills
+ * environment gaps (precedence: ambient environment, then the invoking
+ * directory's `.env`, then the user one). The workspace is the invoking
  * directory: the session cwd, relative paths, and workspace instructions resolve
  * from it, so `dsh` acts on whatever project it is launched in. Session storage
  * is the exception — it lives under the Harness home so `/resume` reaches every
@@ -26,9 +26,7 @@ import {
   boot,
   installFailLoud,
   loadOverlayPatches,
-  loadPersonalPatches,
   resolveConfigPath,
-  watchPersonalPatches,
 } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import type { PatchOptions } from '@cordisjs/plugin-include'
@@ -77,13 +75,12 @@ const SESSION_QUERY_DB = `session-query-${String(process.pid)}-${randomUUID()}.d
 export const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
 
 /* v8 ignore start -- composition over the unit-tested dsh-app-boot helpers;
-   the CLI PTY smoke drives this path end to end, personal overlay included */
+   the CLI PTY smoke drives this path end to end, --config overlay included */
 /**
  * Run the interactive TUI from the invoking directory.
  * @param config - an overlay patch list applied over the shared base and the
- * TUI overlay, REPLACING the personal `~/.dsh/config.yaml` so a named tree never
- * inherits the user's route, or `undefined` to use the personal overlay;
- * already parsed from `--config`.
+ * TUI overlay, or `undefined` for the shipped composition alone; already
+ * parsed from `--config`.
  * @param resumeSessionId - a persisted session id to resume, or `undefined` to
  * mint a fresh one; already parsed and non-empty-validated from `--resume`.
  * Either way the resulting identity reaches the booted app through
@@ -95,9 +92,9 @@ export const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
  * first turn, or `undefined`. Set only by `dsh upgrade` and
  * ignored on a resume, so it never re-fires; reaches the app through
  * {@link INITIAL_SKILL_KEY}.
- * @param configReplace - a config path to boot as the ENTIRE tree, bypassing the
- * shared base, the TUI overlay, and the personal overlay alike, or `undefined`
- * to compose them; already parsed from `--config-replace`.
+ * @param configReplace - a config path to boot as the ENTIRE tree, bypassing
+ * the shared base and the TUI overlay alike, or `undefined` to compose them;
+ * already parsed from `--config-replace`.
  */
 export async function runTui(
   config: string | undefined,
@@ -202,10 +199,8 @@ export async function runTui(
   // patch list: patches never cross an include boundary, so stacking these as
   // nested includes would silently stop reaching base rows. Later lists win.
   //
-  // `--config` REPLACES the personal overlay rather than layering under it: an
-  // explicitly named tree must not inherit `~/.dsh/config.yaml`'s route, or a
-  // demo or test config would silently run on the user's provider and model.
-  // `--config-replace` additionally discards the base and the surface overlay.
+  // `--config` layers over the shipped base and TUI overlay; `--config-replace`
+  // discards both and boots the named file alone.
   const replaceTree = configReplace !== undefined
   const bootConfig = resolvedConfigReplace === undefined ? BASE_CONFIG : resolveConfigPath(resolvedConfigReplace, undefined)
   // Same opt-out semantics as the web surface (resolveTelemetryPatch: any
@@ -214,16 +209,13 @@ export async function runTui(
   // presence is checked against the tree actually booting, so a
   // --config-replace tree is judged on its own rows, not the shipped base's.
   const telemetryPatch = resolveTelemetryPatch(process.env.DSH_TELEMETRY_DISABLED, configHasTelemetryRow(bootConfig))
-  const composePatches = (personalPatches: PatchOptions[]): PatchOptions[] => [
+  const patches: PatchOptions[] = [
     ...replaceTree ? [] : [
       ...loadOverlayPatches(NAME, TUI_OVERLAY),
-      ...resolvedConfig === undefined
-        ? personalPatches
-        : loadOverlayPatches(NAME, resolveConfigPath(resolvedConfig, undefined)),
+      ...resolvedConfig === undefined ? [] : loadOverlayPatches(NAME, resolveConfigPath(resolvedConfig, undefined)),
     ],
     ...telemetryPatch === undefined ? [] : [telemetryPatch],
   ]
-  const patches = composePatches(loadPersonalPatches(NAME) ?? [])
   const queryIndexPath = join(tmpdir(), SESSION_QUERY_DB)
   const ctx = await boot(
     NAME,
@@ -243,8 +235,8 @@ export async function runTui(
       // the Harness home across every cwd, so /resume sees every workspace.
       // The bundle treats the slot as opaque.
       // The agent-loop row reads this to bind `main`, and the tui row reads the
-      // same id, so a personal overlay repointing the model route cannot drop
-      // the session identity or desynchronise the two.
+      // same id, so an overlay repointing the model route cannot drop the
+      // session identity or desynchronise the two.
       hostCtx.provide(CONFIGURED_AGENT_IDENTITIES_KEY, { [MAIN_AGENT_ID]: identity })
       // The query database is a disposable derived index with single-process
       // ownership. Keep it process-local while it indexes the shared logs.
@@ -264,14 +256,6 @@ export async function runTui(
       }
     },
   )
-  // The shipped tree includes HMR and keeps personal config live. An explicit
-  // --config tree replaces the personal overlay (so there is nothing to keep
-  // live), and a --config-replace or HMR-less tree remains a valid composition
-  // that still receives the startup overlay but deliberately has no hidden
-  // watcher.
-  if (resolvedConfig === undefined && !replaceTree && ctx.get('hmr') !== undefined) {
-    await watchPersonalPatches(ctx, { binName: NAME, compose: composePatches })
-  }
   app.current = ctx
   addHarnessSourceSection(ctx, SOURCE_ROOT)
   if (showFirstRunWelcome) {
diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts
index 4fbfba4d8d..a3dc446706 100644
--- a/apps/cli/src/web.ts
+++ b/apps/cli/src/web.ts
@@ -91,7 +91,7 @@ export function prepareWebRuntimeContext(ctx: Context, sourceRoot: string, mode:
  * @param workspaceRoot - parent directory for name-created workspaces, or `undefined` for the gateway's cwd fallback.
  * @param trustedHosts - extra authorities for the /api browser-trust fence, or `undefined` for the derived LAN literals alone.
  * @param config - an overlay of loader patches applied over the shipped web
- * composition instead of `$DSH_HOME/config.yaml`, or `undefined` to use the
+ * composition, or `undefined` to boot the
  * personal overlay; already parsed from `--config`.
  */
 export async function runWeb(
@@ -109,7 +109,6 @@ export async function runWeb(
     ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },
     dev,
     prepare: (ctx) => { prepareWebRuntimeContext(ctx, SOURCE_ROOT, mode) },
-    watchPersonalConfig: true,
     ...host !== undefined && { host },
     ...port !== undefined && { port },
     ...workspaceRoot !== undefined && { workspaceRoot },
diff --git a/apps/cli/tests/args.spec.ts b/apps/cli/tests/args.spec.ts
index 5b0e76323d..a9f7d228bf 100644
--- a/apps/cli/tests/args.spec.ts
+++ b/apps/cli/tests/args.spec.ts
@@ -30,6 +30,17 @@ describe('parseDshArgs', () => {
     expect(parse(['--config-replace', 'tree.yml'])).toEqual({ mode: 'tui', configReplace: 'tree.yml' })
     expect(parse(['--resume', 'sess', '--config', 'app.yml'])).toEqual({ mode: 'tui', config: 'app.yml', resume: 'sess' })
     expect(parse(['-p', 'do the thing'])).toEqual({ mode: 'headless', prompt: 'do the thing' })
+    // Every booting surface takes the composition flags: with the personal
+    // overlay gone, naming a tree is the only way to compose one, so a
+    // surface that could not name one would have no composition path at all.
+    expect(parse(['-p', 'task', '--config', 'c.yml']))
+      .toEqual({ mode: 'headless', prompt: 'task', config: 'c.yml' })
+    expect(parse(['-p', 'task', '--config-replace', 'tree.yml']))
+      .toEqual({ mode: 'headless', prompt: 'task', configReplace: 'tree.yml' })
+    expect(parse(['meta', '--experimental', '--config', 'c.yml']))
+      .toEqual({ mode: 'meta', config: 'c.yml' })
+    expect(parse(['upgrade', '--experimental', '--config-replace', 'tree.yml']))
+      .toEqual({ mode: 'upgrade', configReplace: 'tree.yml' })
     // Experimental subcommands run under the per-invocation flag or the env opt-in.
     expect(parse(['meta', '--experimental'])).toEqual({ mode: 'meta' })
     expect(parse(['meta'], true)).toEqual({ mode: 'meta' })
@@ -77,9 +88,8 @@ describe('parseDshArgs', () => {
     // schema at boot, not here.)
     expect(exitCode(['--resume='])).toBe(1)
     expect(exitCode(['-p', ''])).toBe(1)
-    expect(exitCode(['-p', 'x', '--config', 'c.yml'])).toBe(1)
-    expect(exitCode(['-p', 'x', '--config-replace', 'tree.yml'])).toBe(1)
     expect(exitCode(['--config', 'c.yml', '--config-replace', 'tree.yml'])).toBe(1)
+    expect(exitCode(['-p', 'x', '--config', 'c.yml', '--config-replace', 'tree.yml'])).toBe(1)
     expect(exitCode(['-p', 'x', '--resume', 's'])).toBe(1)
     expect(exitCode(['--bogus'])).toBe(1)
     expect(exitCode(['bogus-positional'])).toBe(1)
@@ -91,16 +101,14 @@ describe('parseDshArgs', () => {
     expect(exitCode(['--config-replace', 'tree.yml', 'web'])).toBe(1)
     // Same rule for each subcommand that shares no option with the default
     // surface, so a leaked flag is a typo, not something to ignore.
-    // `meta` fixes its own config tree and always starts fresh,
-    // so every default-surface option is rejected.
+    // `meta` always starts fresh, so the session options are rejected; the
+    // composition flags are its own and only their combination is rejected.
     expect(exitCode(['meta', '--experimental', '--resume', 's'])).toBe(1)
-    expect(exitCode(['meta', '--experimental', '--config', 'c.yml'])).toBe(1)
-    expect(exitCode(['meta', '--experimental', '--config-replace', 'tree.yml'])).toBe(1)
     expect(exitCode(['meta', '--experimental', '-p', 'task'])).toBe(1)
-    // `upgrade` takes no options beyond the gate: any leaked default-surface
-    // flag is a mistyped invocation, not a silently-dropped input.
+    expect(exitCode(['meta', '--experimental', '--config', 'c.yml', '--config-replace', 't.yml'])).toBe(1)
+    // `upgrade` always mints a fresh session, so `--resume` and a leaked
+    // parent flag are mistyped invocations; its own composition flags are not.
     expect(exitCode(['upgrade', '--experimental', '--resume', 's'])).toBe(1)
-    expect(exitCode(['upgrade', '--experimental', '--config', 'c.yml'])).toBe(1)
     expect(exitCode(['-p', 'task', 'upgrade', '--experimental'])).toBe(1)
     // The pre-release command names have no compatibility aliases.
     expect(exitCode(['experimental-meta'])).toBe(1)
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index 3592d438dd..67bccd8048 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -107,8 +107,9 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       expect(stdout).toContain('# == tui.cordis.yml')
     }, 30_000)
 
-    it('layers the personal overlay in --dump-config and reports an unmatched patch on stderr', async () => {
-      writeFileSync(join(home, 'config.yaml'), [
+    it('layers a --config overlay in --dump-config and reports an unmatched patch on stderr', async () => {
+      const overlay = join(home, 'overlay.yml')
+      writeFileSync(overlay, [
         '- id: agent-loop',
         '  config:',
         '    agents:',
@@ -120,16 +121,19 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
         '    value: 1',
         '',
       ].join('\n'))
-      const { stdout, code, stderr } = await runBuiltBin(['--dump-config'], { DSH_HOME: home })
+      const { stdout, code, stderr } = await runBuiltBin(['--dump-config', '--config', overlay], { DSH_HOME: home })
       expect(code).toBe(0)
       expect(stdout).toContain('provider: custom-provider')
       expect(stdout).not.toContain('model: deepseek-v4-pro')
-      // The personal layer appears in the patched row's provenance and the
+      // The named layer appears in the patched row's provenance and the
       // skipped-patch warning carries its label.
-      expect(stdout).toContain(`patched by tui.cordis.yml, ${join(home, 'config.yaml')}`)
+      expect(stdout).toContain(`patched by tui.cordis.yml, ${overlay}`)
       expect(stderr).toContain('patch: entry "only-on-web" not found')
 
-      // The shipped view ignores the personal overlay entirely.
+      // An unnamed dump composes the shipped tree only: a file sitting in the
+      // Harness home is not a layer any more.
+      const unnamed = await runBuiltBin(['--dump-config'], { DSH_HOME: home })
+      expect(unnamed.stdout).not.toContain('custom-provider')
       const shipped = await runBuiltBin(['--dump-default-config'], { DSH_HOME: home })
       expect(shipped.stdout).not.toContain('custom-provider')
       expect(shipped.stdout).toContain('model: deepseek-v4-pro')
diff --git a/apps/cli/tests/tui-keyless-smoke.e2e.ts b/apps/cli/tests/tui-keyless-smoke.e2e.ts
index ade38a0e9c..2894d0a1ca 100644
--- a/apps/cli/tests/tui-keyless-smoke.e2e.ts
+++ b/apps/cli/tests/tui-keyless-smoke.e2e.ts
@@ -40,7 +40,7 @@ const PTY_SMOKE_TEST_TIMEOUT_MS = process.env.DSH_EXAMPLE_MODE === 'lib'
   : LOADER_SMOKE_TEST_TIMEOUT_MS
 
 /**
- * Seed the isolated process workspace: ordinary files land in `cwd`, personal
+ * Seed the isolated process workspace: ordinary files land in `cwd`, harness
  * files in the Harness home (`.dsh`), and skill bundles under the agents
  * home's `skills/` root — the same trees `$DSH_HOME` /
  * `$DSH_AGENTS_HOME` point the child at.
@@ -48,7 +48,7 @@ const PTY_SMOKE_TEST_TIMEOUT_MS = process.env.DSH_EXAMPLE_MODE === 'lib'
 function seedWorkspace(
   files: {
     workspace?: Record<string, string>
-    personal?: Record<string, string>
+    harnessHome?: Record<string, string>
     skills?: Record<string, string>
   },
 ): (cwd: string) => Promise<void> {
@@ -58,7 +58,7 @@ function seedWorkspace(
       await mkdir(dirname(file), { recursive: true })
       await writeFile(file, content)
     }
-    for (const [name, content] of Object.entries(files.personal ?? {})) {
+    for (const [name, content] of Object.entries(files.harnessHome ?? {})) {
       const file = join(cwd, '.dsh', name)
       await mkdir(dirname(file), { recursive: true })
       await writeFile(file, content)
@@ -652,7 +652,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     expect(output).toContain('Preserve restored state')
   }, PTY_SMOKE_TEST_TIMEOUT_MS)
 
-  it('boots the shipped default config with no arguments and no personal overlay', async () => {
+  it('boots the shipped default config with no arguments and no overlay', async () => {
     const output = await smoke({
       label: 'dsh default boot',
       tempDirPrefix: 'dsh-default-boot-',
@@ -667,9 +667,9 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     expect(output).toContain('\u001B[?2004l')
   }, PTY_SMOKE_TEST_TIMEOUT_MS)
 
-  it('applies the personal overlay: config.yaml patches an overlay-inserted row, and both .env layers feed its !!js with the project one winning', async () => {
-    // The whole personal-config chain in one boot, plus the environment
-    // layering underneath it. config.yaml patches the `tui` row — a row the
+  it('applies a --config overlay: it patches an overlay-inserted row, and both .env layers feed its !!js with the project one winning', async () => {
+    // The whole explicit-overlay chain in one boot, plus the environment
+    // layering underneath it. The named file patches the `tui` row — a row the
     // SURFACE OVERLAY inserted, not one the base declares — proving a later
     // patch list reaches a row an earlier one inserted. The `!!js` expression
     // renders both halves of the layering in one line: `DSH_LAYER_WELCOME` is
@@ -678,13 +678,13 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     // arrive. Credentials are not part of this: they live in
     // `.credentials.yaml`, which is never hoisted into `process.env`.
     const output = await smoke({
-      label: 'dsh personal overlay',
-      tempDirPrefix: 'dsh-personal-overlay-',
+      label: 'dsh explicit overlay',
+      tempDirPrefix: 'dsh-explicit-overlay-',
       binScript: dshBinScript,
-      configArgs: [],
+      configArgs: ['--config', '.dsh/config.yaml'],
       prepare: seedWorkspace({
         workspace: { '.env': 'DSH_LAYER_WELCOME=PROJECT WINS.\n' },
-        personal: {
+        harnessHome: {
           '.env': 'DSH_LAYER_WELCOME=USER LAYER LOST.\nDSH_USER_ONLY=USER LAYER LOADED.\n',
           'config.yaml': [
             '- id: workspace-context',
@@ -705,7 +705,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     expect(output).toContain('\u001B[?2004l')
   }, PTY_SMOKE_TEST_TIMEOUT_MS)
 
-  it('loads a cached repository Plugin from personal config alone', async () => {
+  it('loads a cached repository Plugin from a --config overlay alone', async () => {
     const source = 'github:fixture/repository#fixed-ref'
     const specifier = `${source}&path:/.dsh-plugin`
     const key = createHash('sha256').update(specifier).digest('hex')
@@ -717,12 +717,12 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     // deliberate external pin of the durable on-disk format.
     const wrapper = await generatePreparedWrapper('config-only-fixture')
     const output = await smoke({
-      label: 'dsh personal repository Plugin',
-      tempDirPrefix: 'dsh-personal-repository-plugin-',
+      label: 'dsh overlay repository Plugin',
+      tempDirPrefix: 'dsh-overlay-repository-plugin-',
       binScript: dshBinScript,
-      configArgs: [],
+      configArgs: ['--config', '.dsh/config.yaml'],
       prepare: seedWorkspace({
-        personal: {
+        harnessHome: {
           'config.yaml': [
             '- id: repository-plugins',
             "  name: '@deepseek-ai/dsh-repository-plugin'",
@@ -753,13 +753,13 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     expect(output).toContain('\u001B[?2004l')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
-  it('fails loud instead of booting when the personal config.yaml is invalid', async () => {
+  it('fails loud instead of booting when a named --config overlay is invalid', async () => {
     const output = await smoke({
-      label: 'dsh invalid personal config',
-      tempDirPrefix: 'dsh-invalid-personal-',
+      label: 'dsh invalid overlay',
+      tempDirPrefix: 'dsh-invalid-overlay-',
       binScript: dshBinScript,
-      configArgs: [],
-      prepare: seedWorkspace({ personal: { 'config.yaml': 'id: not-a-list\n' } }),
+      configArgs: ['--config', '.dsh/config.yaml'],
+      prepare: seedWorkspace({ harnessHome: { 'config.yaml': 'id: not-a-list\n' } }),
       expectedExitCode: 1,
     })
     expect(output).toContain('must be a top-level YAML array of loader patch entries')
@@ -793,18 +793,18 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     expect(output).toMatch(/To resume this session: dsh --resume=main-session-[0-9a-f-]{36} --config/)
   }, PTY_SMOKE_TEST_TIMEOUT_MS)
 
-  it('keeps resume working when the personal overlay replaces the whole agent-loop config', async () => {
-    // Loader patches replace a targeted `config` key wholesale, so a personal
-    // overlay repointing the model route drops every identity key the shipped
+  it('keeps resume working when a --config overlay replaces the whole agent-loop config', async () => {
+    // Loader patches replace a targeted `config` key wholesale, so an overlay
+    // repointing the model route drops every identity key the shipped
     // row declared. Launcher-owned identity makes that unreachable: agent-loop
     // applies the launcher's id over whatever route survives.
     const output = await smoke({
       label: 'dsh overlay keeps resume',
       tempDirPrefix: 'dsh-overlay-resume-',
       binScript: dshBinScript,
-      configArgs: [],
+      configArgs: ['--config', '.dsh/config.yaml'],
       prepare: seedWorkspace({
-        personal: {
+        harnessHome: {
           'config.yaml': [
             '- id: workspace-context',
             '  disabled: true',
diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml
index 6d1265e9f3..525fc2f1d8 100644
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.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 docs/user/guide/config.md
-config.md: 6f656b573490a08ec893f4d14b487e6082015049
-config.zh.md: d4bb30023df46845ea720f3e6a45184479df0e72
+config.md: b1cf3a57b2fd16d4139f1a11a6cd85e54bb957b5
+config.zh.md: dad03d8232851678cfb6dc690f0bbd3f02380fc8
diff --git a/docs/user/guide/config.md b/docs/user/guide/config.md
index 6f656b5734..b1cf3a57b2 100644
--- a/docs/user/guide/config.md
+++ b/docs/user/guide/config.md
@@ -50,7 +50,7 @@ Plugins load in file order. Place plugins that depend on services after the appl
 
 ## CLI overlays
 
-The TUI composes `base.cordis.yml` and `tui.cordis.yml`, then applies one optional patch list. By default that final list is `~/.dsh/config.yaml`; `dsh --config <path>` replaces the personal list with the named overlay. `dsh --config-replace <path>` instead boots the named file as the complete tree, without shipped or personal layers. `dsh web --config <path>` adds its overlay after the shared base and Web surface defaults and before the Web launcher's CLI-flag patches.
+The TUI composes `base.cordis.yml` and `tui.cordis.yml`, then applies the optional `dsh --config <path>` overlay. `dsh --config-replace <path>` instead boots the named file as the complete tree, without any shipped layer. Every booting surface takes both flags — `dsh -p`, `dsh web`, `dsh meta`, and `dsh upgrade` included — because naming a file is the only way to compose your own tree.
 
 A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKey` and `baseURL`, so restate every key the row must retain.
 
diff --git a/docs/user/guide/config.zh.md b/docs/user/guide/config.zh.md
index d4bb30023d..dad03d8232 100644
--- a/docs/user/guide/config.zh.md
+++ b/docs/user/guide/config.zh.md
@@ -50,7 +50,7 @@ Harness 使用 `cordis.yml` 描述 Agent 加载哪些插件以及每个插件的
 
 ## CLI 覆盖层
 
-TUI 先组合 `base.cordis.yml` 与 `tui.cordis.yml`，再应用一个可选补丁列表。默认的最后一层是 `~/.dsh/config.yaml`；`dsh --config <path>` 会以指定覆盖替代个人补丁列表。`dsh --config-replace <path>` 则把指定文件作为完整配置树启动，不使用已交付配置或个人层。`dsh web --config <path>` 会在共享基础配置与 Web 界面默认值之后、Web 启动器的命令行标志补丁之前添加覆盖。
+TUI 先组合 `base.cordis.yml` 与 `tui.cordis.yml`，再应用可选的 `dsh --config <path>` 覆盖。`dsh --config-replace <path>` 则把指定文件作为完整配置树启动，不使用任何已交付层。每个会启动的界面都接受这两个标志，包括 `dsh -p`、`dsh web`、`dsh meta` 和 `dsh upgrade`——因为点名一个文件是组合自己配置树的唯一途径。
 
 补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKey` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
 
diff --git a/examples/mcp-memory/README.i18n.yaml b/examples/mcp-memory/README.i18n.yaml
index def44e65e3..41266f9194 100644
--- a/examples/mcp-memory/README.i18n.yaml
+++ b/examples/mcp-memory/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 examples/mcp-memory/README.md
-README.md: b5dd7ffc4ad248d38e108d9aa28c7c26e0c76913
-README.zh.md: 1249ae40bb344fc81836cb49d71dd5656457b1b3
+README.md: 6e4c68277a99b2ac739bdfb71e6c36dfbef44e86
+README.zh.md: 66efb05e1aa1d295f1712f5f31b93f98ba68eb8e
diff --git a/examples/mcp-memory/README.md b/examples/mcp-memory/README.md
index b5dd7ffc4a..6e4c68277a 100644
--- a/examples/mcp-memory/README.md
+++ b/examples/mcp-memory/README.md
@@ -42,7 +42,7 @@ dsh --config "${DSH_HOME:-$HOME/.dsh}/memory.cordis.yml"
 
 Replace `memorix.cordis.yml` in the URL with either of the other filenames to select it. Review a downloaded overlay before running it: Cordis configuration can contain executable `!!js` expressions.
 
-To keep the selection in personal configuration, merge the chosen file's single `insert` patch into `$DSH_HOME/config.yaml` (normally `~/.dsh/config.yaml`). Do not copy over an existing file: it may already contain unrelated personal patches.
+To keep the selection across runs, merge the chosen file's single `insert` patch into your own overlay and name it on every launch (`dsh --config ~/.dsh/mcp.yml`). Do not copy over an existing overlay: it may already contain unrelated patches.
 
 ## Provider setup
 
diff --git a/examples/mcp-memory/README.zh.md b/examples/mcp-memory/README.zh.md
index 1249ae40bb..66efb05e1a 100644
--- a/examples/mcp-memory/README.zh.md
+++ b/examples/mcp-memory/README.zh.md
@@ -42,7 +42,7 @@ dsh --config "${DSH_HOME:-$HOME/.dsh}/memory.cordis.yml"
 
 若要选择另外任一配置，请将 URL 中的 `memorix.cordis.yml` 替换为对应文件名。运行下载的 overlay 前，请先审阅其内容：Cordis 配置可以包含可执行的 `!!js` 表达式。
 
-如果要把所选配置保存在个人配置中，请将对应文件中的单个 `insert` patch 合并到 `$DSH_HOME/config.yaml`（通常是 `~/.dsh/config.yaml`）。不要覆盖已有文件，其中可能已经包含无关的个人 patch。
+如果要跨多次运行保留所选配置，请把对应文件中的单个 `insert` patch 合并到你自己的覆盖文件里，并在每次启动时点名它（`dsh --config ~/.dsh/mcp.yml`）。不要覆盖已有的覆盖文件，其中可能已经包含无关的 patch。
 
 ## 提供方设置
 
diff --git a/packages/cordis/repository-plugin/README.i18n.yaml b/packages/cordis/repository-plugin/README.i18n.yaml
index 8cd641781f..b64a5ea9c9 100644
--- a/packages/cordis/repository-plugin/README.i18n.yaml
+++ b/packages/cordis/repository-plugin/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/cordis/repository-plugin/README.md
-README.md: 0ba1ce86d99a12e0f94e7a39fd3ae44dc29889a7
-README.zh.md: 2d9544166eafbb1066b65031969925890f2b9797
+README.md: d523d0e6296fc060741b7bc8e843c1332ea1677f
+README.zh.md: c3240bad3f292ecfaa51e62d93e59cbf1c69be7f
diff --git a/packages/cordis/repository-plugin/README.md b/packages/cordis/repository-plugin/README.md
index 0ba1ce86d9..d523d0e629 100644
--- a/packages/cordis/repository-plugin/README.md
+++ b/packages/cordis/repository-plugin/README.md
@@ -30,7 +30,7 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
 
 ## Standalone app configuration
 
-The shipped `dsh` TUI, Web, and headless trees contain an empty `repository-plugins` row. A standalone user enables exact GitHub generations by replacing that row's config in `$DSH_HOME/config.yaml` (default `~/.dsh/config.yaml`):
+The shipped `dsh` TUI, Web, and headless trees contain an empty `repository-plugins` row. A standalone user enables exact GitHub generations by replacing that row's config in a `--config` overlay (`dsh --config ~/.dsh/plugins.yml`):
 
 ```yaml
 - id: repository-plugins
@@ -43,7 +43,7 @@ The shipped `dsh` TUI, Web, and headless trees contain an empty `repository-plug
 
 Each source must use `github:owner/repository#<ref>`. Omitting `&path:` selects `/.dsh-plugin`; an explicit path is absolute within the repository and must end in `.dsh-plugin`. A commit ref gives the clearest immutable identity, while tags and branches remain accepted exact config values. `cacheDir` may override the default `$DSH_HOME/cache/repository-plugins` cache root.
 
-The TUI and Web watch `config.yaml` through Cordis HMR. A valid source-list change installs and swaps the complete repository Plugin generation; a failed fetch, prepare, import, or Plugin application keeps the last good tree and broadcasts `hmr/config-update-failed(filename, error)`. Headless runs consume the file only at startup. An identical source string permanently reuses its prepared cache entry, so selecting changed code requires a ref, path, or other source-config change. App integration rationale: [config-only repository Plugins Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md).
+Every surface reads the overlay once at startup. An identical source string permanently reuses its prepared cache entry, so selecting changed code requires a ref, path, or other source-config change. App integration rationale: [config-only repository Plugins Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md).
 
 ## Preparation
 
diff --git a/packages/cordis/repository-plugin/README.zh.md b/packages/cordis/repository-plugin/README.zh.md
index 2d9544166e..c3240bad3f 100644
--- a/packages/cordis/repository-plugin/README.zh.md
+++ b/packages/cordis/repository-plugin/README.zh.md
@@ -30,7 +30,7 @@
 
 ## 独立应用配置
 
-已交付的 `dsh` TUI、Web 和无头配置树包含一个空的 `repository-plugins` 配置项。独立用户只需在 `$DSH_HOME/config.yaml`（默认 `~/.dsh/config.yaml`）中替换该配置项的配置，即可启用精确指定的 GitHub generation：
+已交付的 `dsh` TUI、Web 和无头配置树包含一个空的 `repository-plugins` 配置项。独立用户只需在一个 `--config` 覆盖文件中替换该配置项的配置（`dsh --config ~/.dsh/plugins.yml`），即可启用精确指定的 GitHub generation：
 
 ```yaml
 - id: repository-plugins
@@ -43,7 +43,7 @@
 
 每个源都必须采用 `github:owner/repository#<ref>`。省略 `&path:` 时选择 `/.dsh-plugin`；显式路径是仓库内的绝对路径，并且必须以 `.dsh-plugin` 结尾。commit ref 提供最清晰的不可变身份；tag 和 branch 仍可作为显式配置值使用。`cacheDir` 可覆盖默认缓存根 `$DSH_HOME/cache/repository-plugins`。
 
-TUI 和 Web 通过 Cordis HMR（热模块替换）监视 `config.yaml`。有效的源列表变更会安装并替换整套仓库插件 generation；拉取、准备、导入或插件应用失败时，最后一个可用树保持运行，并广播 `hmr/config-update-failed(filename, error)`。无头运行只在启动时使用该文件。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入仓库插件的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
+每个界面都只在启动时读取该覆盖文件。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入仓库插件的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
 
 ## 准备阶段
 
diff --git a/packages/ui/app-boot/README.i18n.yaml b/packages/ui/app-boot/README.i18n.yaml
index be3bb757a4..ef81d9a2fd 100644
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/ui/app-boot/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/app-boot/README.md
-README.md: 8636af748168f6d898d7b44da298636af3686001
-README.zh.md: 0d956a3f5734cd04694fb96a6c89468e99413ebc
+README.md: 9b443cb0850ba989733aa2dadd587088b60a51c2
+README.zh.md: dffc9eb5205edb52d9b9a84d98d20af0b17469b0
diff --git a/packages/ui/app-boot/README.md b/packages/ui/app-boot/README.md
index 8636af7481..9b443cb085 100644
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -13,10 +13,8 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c
 | `FAIL_LOUD_RELEASE_TIMEOUT_MS` | How long `installFailLoud` waits for its `release` hook; a wedged disposer delays the fatal exit, never cancels it |
 | `assertEntriesLoaded(ctx, binName)` | Throw when a settled tree holds an enabled entry with no fiber, reporting every unresolved plugin name as a Cordis startup failure |
 | `assertEntriesActivated(ctx, binName)` | Include the `assertEntriesLoaded` check, then await every enabled entry after the Loader settles; throw with each failed plugin's original stack or each pending plugin's unresolved services |
-| `loadPersonalPatches(binName, dir?)` | Parse the optional `config.yaml` in the Harness home (default [`resolveDshHome()`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) — a top-level YAML array of include `PatchOptions` (id-targeted config overrides, `insert` lists, `!!js` allowed); absent file → `undefined`, an unreadable/unparsable/non-array file throws |
-| `loadOverlayPatches(binName, file)` | Parse a required patch-list file with the same shape as personal config; read or parse failures throw a labelled error |
-| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | Mount the statically imported Include builtin and retain the exact root entry used by personal-config HMR |
-| `watchPersonalPatches(ctx, options)` | Register `$DSH_HOME/config.yaml` with the existing Cordis HMR service; each add/change/removal transactionally recomposes the full patch list through the caller's `compose` closure (app-owned layers around the current personal overlay) and returns an async disposer |
+| `loadOverlayPatches(binName, file)` | Parse a required patch-list file (a surface overlay or a `--config` file); read or parse failures throw a labelled error |
+| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | Mount the statically imported Include builtin as the boot's root entry |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, expose `dshHomePath(...segments)` to Loader `!!js` config expressions, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots such as [`MAIN_SESSION_ID_KEY`](../tui/README.md)), then mount and await the include tree, assert entries loaded and activated, and return the root context — or dispose the partial context and reject a labelled error |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | Compose the base config and labeled overlay layers offline — the include's own parser and patch algorithm (`entryListSchema`/`applyEntryPatches`), so the result equals what `boot()` mounts — and render YAML with `!!js` expressions verbatim; each run of same-provenance rows is preceded by a `# ==` comment naming the contributing file and the layers that patched it, keeping the output one loadable document; a patch matching no row goes to `warn` with its layer label (default: one stderr line), read/parse/shape failures throw |
 | `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to the DSH implementation checkout while warning it not to infer the current working directory from that path and to use `pwd` instead; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
@@ -30,17 +28,15 @@ Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`, npm packages) resolve
 
 This package carries no loader hooks and no dev-mode surface. The [`dsh` app](../../../apps/cli/README.md) owns its Node source-launch hook and consumes these helpers for the boot sequence; built consumers continue to use plain Node package resolution.
 
-## Personal config
+## The Harness home
 
-A developer's machine-local preferences live outside every repository in the Harness home (default `~/.dsh`, overridable via `$DSH_HOME`; the single root [`resolveDshHome`](../../util/paths/README.md) resolves), consumed by the `dsh` CLI's TUI, Web, and headless surfaces ([`apps/cli`](../../../apps/cli/README.md)); the demo bins boot their committed trees verbatim. Two optional files:
+A developer's machine-local state lives outside every repository in the Harness home (default `~/.dsh`, overridable via `$DSH_HOME`; the single root [`resolveDshHome`](../../util/paths/README.md) resolves). What this package reads from it is one file:
 
 - **`.env`** — the user's ordinary environment layer, loaded by the `dsh` bin through `loadLayeredEnv` beneath the invoking directory's `.env` and the inherited environment. It is plain environment with plain environment reach, not a secret boundary: what the Harness owns and isolates lives in `.credentials.yaml`, which no surface hoists. A key placed in this file therefore still resolves — as a read-only `env` layer that shadows the stored one and blocks rotation from the TUI and the web page.
-- **`config.yaml`** — loader overlay patches applied over the shipped default config, with the same semantics as the shipped surface overlays: an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount. A patch naming an entry id absent from the booted tree is a silent no-op. An empty or comments-only file throws (it parses to nothing, not to a list); disable the overlay with `[]` or by deleting the file.
 
-The TUI and Web keep `config.yaml` live through `watchPersonalPatches`; one-shot headless runs read only the startup value. The watcher targets the exact personal path even when the file or immediate parent does not exist, serializes bursts, and recomposes the personal patches inside the caller's layer order (surface overlay below, app-generated patches above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
-
-Subprocess test launchers point `DSH_HOME` at an isolated per-test directory so a developer's personal overlay can never leak into fixtures.
+There is no automatically discovered composition file. Loader overlays reach a surface only by being named: `dsh --config <path>` layers a patch list over the shipped tree and `dsh --config-replace <path>` boots one instead of it, on every booting surface. Keeping an overlay in `~/.dsh` is fine — it is a location, not a layer, and nothing loads it unless the launch names it ([rationale](../../../.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md)).
 
+Subprocess test launchers point `DSH_HOME` at an isolated per-test directory so a developer's own files can never leak into fixtures.
 ## Model Experience
 
 Indirectly, through the plugin tree it loads, which determines the prompts, schemas, messages, and model adapter in the resulting application; the one export that contributes model-visible text, `addHarnessSourceSection`, does so only when a consumer calls it after boot.
@@ -54,4 +50,4 @@ No direct invalidation from `boot()`; a consumer that calls `addHarnessSourceSec
 - **Bare package specifiers depend on Loader internals** — production bins need Loader's optional native helper; an in-process caller without it must use resolvable relative/file specifiers or provide its own module-resolution hook.
 - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection.
 - **Environment loading is directory-scoped and optional** — each layer is one named directory's `.env`, and a failure warns; neither helper searches parents or validates required variables. `loadLayeredEnv` fixes its two layers at the invoking directory and the Harness home, so a caller wanting different layers composes `loadEnv` itself.
-- **Personal config is patch-shaped** — an id-targeted patch replaces the entry's whole `config` rather than deep-merging, so a personal override restates the base fields it keeps.
+- **Overlays are patch-shaped** — an id-targeted patch replaces the entry's whole `config` rather than deep-merging, so an override restates the base fields it keeps.
diff --git a/packages/ui/app-boot/README.zh.md b/packages/ui/app-boot/README.zh.md
index 0d956a3f57..dffc9eb520 100644
--- a/packages/ui/app-boot/README.zh.md
+++ b/packages/ui/app-boot/README.zh.md
@@ -13,10 +13,8 @@
 | `FAIL_LOUD_RELEASE_TIMEOUT_MS` | `installFailLoud` 等待其 `release` 回调的时长；卡住的 disposer 只会延迟致命退出，而不会取消它 |
 | `assertEntriesLoaded(ctx, binName)` | 树结算后，如果其中存在已启用但没有 fiber 的条目，则抛出异常，并以 Cordis 启动故障的形式报告每个未解析插件的名称 |
 | `assertEntriesActivated(ctx, binName)` | 先执行 `assertEntriesLoaded` 检查，再在 Loader 结算后等待每个已启用配置项；抛出的错误包含每个失败插件的原始错误堆栈，或每个等待中插件尚未解析的服务 |
-| `loadPersonalPatches(binName, dir?)` | 解析 Harness home 中可选的 `config.yaml`（默认使用 [`resolveDshHome()`](../../util/paths/README.md)：先取 `$DSH_HOME`，否则取 `~/.dsh`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
-| `loadOverlayPatches(binName, file)` | 解析一份必需的 patch 列表文件，其形状与个人配置相同；读取或解析失败时抛出带标签的错误 |
-| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | 挂载静态导入的 Include builtin，并保留个人配置 HMR（热模块替换）使用的确切根配置项 |
-| `watchPersonalPatches(ctx, options)` | 向现有 Cordis HMR 服务注册 `$DSH_HOME/config.yaml`；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前个人 overlay）以事务方式重新组合完整 patch 列表，并返回异步 disposer |
+| `loadOverlayPatches(binName, file)` | 解析一份必需的 patch 列表文件（surface overlay 或 `--config` 文件）；读取或解析失败时抛出带标签的错误 |
+| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | 挂载静态导入的 Include builtin，作为本次启动的根配置项 |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽，例如 [`MAIN_SESSION_ID_KEY`](../tui/README.md)），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
@@ -30,17 +28,15 @@ Loader 并发挂载各个条目，因此当其他环节失败时，某个界面
 
 此包不包含 loader 钩子，也不提供开发模式接口。[`dsh` 应用](../../../apps/cli/README.md)持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。
 
-## 个人配置
+## Harness home
 
-开发者的机器本地偏好位于所有仓库之外的 Harness home 中（默认 `~/.dsh`，可由 `$DSH_HOME` 覆盖；统一由根级 [`resolveDshHome`](../../util/paths/README.md) 解析），并由 `dsh` CLI（命令行界面）的 TUI、Web 和无头界面（[`apps/cli`](../../../apps/cli/README.md)）使用；demo bin 会原样启动仓库中提交的树。这里有两个可选文件：
+开发者的机器本地状态位于所有仓库之外的 Harness home 中（默认 `~/.dsh`，可由 `$DSH_HOME` 覆盖；统一由根级 [`resolveDshHome`](../../util/paths/README.md) 解析）。本包从中读取的只有一个文件：
 
 - **`.env`**：用户的普通环境层，由 `dsh` bin 经 `loadLayeredEnv` 加载，位于调用目录的 `.env` 与继承环境之下。它是具有普通环境作用域的普通环境值，而不是密钥边界：由 Harness 拥有并隔离的东西放在 `.credentials.yaml` 里，后者不会被任何表层提升。因此放进本文件的密钥仍然可以解析——但会作为只读的 `env` 层遮蔽已存储的那一份，并阻断从 TUI 与 Web 页面轮换密钥。
-- **`config.yaml`**：在发布的默认配置上应用 Loader overlay patch，语义与交付的 surface overlay 相同：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在已启动树中，则静默不执行任何操作。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用 overlay，请使用 `[]` 或删除该文件。
 
-TUI 和 Web 会持续应用 `config.yaml` 的变更，具体由 `watchPersonalPatches` 负责；一次性无头运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切的个人配置路径；它会串行处理突发变更，并按调用方的层次顺序重新组合个人 patch（surface overlay 在下、应用生成的 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
-
-子进程测试 launcher 会把 `DSH_HOME` 指向逐测试隔离的目录，确保开发者的个人 overlay 不会泄漏到 fixture（测试前置数据）中。
+不存在会被自动发现的组合文件。Loader overlay 只有被点名才会抵达某个界面：`dsh --config <path>` 在已交付配置树上叠加一个 patch 列表，`dsh --config-replace <path>` 则用它取代整棵树，两者在每个会启动的界面上都可用。把 overlay 放在 `~/.dsh` 里没有问题——那只是一个位置，不是一层，启动时不点名就不会加载它（[依据](../../../.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md)）。
 
+子进程测试启动器会把 `DSH_HOME` 指向每个测试独立的目录，因此开发者自己的文件绝不会泄漏进 fixture。
 ## 模型体验
 
 模型通过此包加载的插件树间接受到影响；该树决定最终应用中的提示词、schema、消息和模型适配器。唯一贡献模型可见文本的导出 `addHarnessSourceSection`，也只有在消费方启动后调用它时才会产生影响。
@@ -54,4 +50,4 @@ TUI 和 Web 会持续应用 `config.yaml` 的变更，具体由 `watchPersonalPa
 - **裸包 specifier 依赖 Loader 内部机制**：生产 bin 需要 Loader 的可选原生 helper；没有该 helper 的进程内调用方必须使用可解析的相对／file specifier，或提供自己的模块解析钩子。
 - **快照回放替换仅识别特定 basename**：只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
 - **环境加载按目录划分且为可选操作**：每一层都是一个指定目录下的 `.env`，失败时发出警告；两个 helper 都不会搜索父目录，也不验证必需变量。`loadLayeredEnv` 的两层固定为调用目录与 Harness home，需要其他层次的调用方请自行组合 `loadEnv`。
-- **个人配置采用 patch 形式**：按 id 定位的 patch 会替换条目的整个 `config`，而不是深度合并，因此个人覆盖必须重述需要保留的基础字段。
+- **overlay 采用 patch 形式**：按 id 定位的 patch 会替换条目的整个 `config`，而不是深度合并，因此覆盖必须重述需要保留的基础字段。
diff --git a/packages/ui/app-boot/src/index.ts b/packages/ui/app-boot/src/index.ts
index 94a7aa2c7d..78dff3eca8 100644
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -1,14 +1,14 @@
 /**
  * Shared boot glue for the app bins (`dsh`, `dsh-cli-demo`, `dsh-acp-demo`): load the gitignored
  * `.env` files, install the fail-loud Loader guards, resolve the config path (snapshot-aware), load the
- * optional personal overlay patches from the Harness home (`~/.dsh`), expose its path resolver to
+ * explicit overlay patch lists a surface composes, expose the Harness-home path resolver to
  * config expressions, and drive the Cordis Loader against a leaf `cordis.yml` until the tree settles.
  * @module @deepseek-ai/dsh-app-boot
  */
 
 import { pathToFileURL } from 'node:url'
 import { readFileSync } from 'node:fs'
-import { basename, dirname, join, resolve } from 'node:path'
+import { basename, dirname, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
 import { Context, type FiberState } from 'cordis'
 import Loader, { type Entry, type EntryOptions } from '@cordisjs/plugin-loader'
@@ -95,49 +95,15 @@ export function loadLayeredEnv(
   loadEnv(binName, home, warn)
 }
 
-/** File inside the Harness home holding the personal loader overlay patches. */
-export const PERSONAL_CONFIG_FILENAME = 'config.yaml'
-
-const bootstrapIncludes = new WeakMap<Context, Entry>()
-
-// The include's YAML dialect (`!!js` scalars become expression nodes the
-// Loader interpolates against each entry's context at mount time), imported
-// from the include itself so patch parsing and config dumping can never drift
-// from what the include mounts. Personal patches share it so they may
-// reference `process.env`.
-const personalPatchesSchema = entryListSchema
-
 /**
- * Load the optional personal overlay patches (`config.yaml` under the Harness
- * home). The file is a top-level YAML array of loader patch entries
- * (`@cordisjs/plugin-include`'s `PatchOptions`): id-targeted config overrides
- * and `insert` lists, with `!!js` expressions allowed. A missing file means
- * "no personal overlay"; an unreadable, unparsable, or non-array file throws —
- * a present personal config that cannot apply is a misconfiguration and must
- * fail loud at boot, never be silently skipped.
- * @param binName - the diagnostic prefix on the thrown error.
- * @param dir - the Harness home; defaults to {@link resolveDshHome} (`$DSH_HOME` or `~/.dsh`).
- * @returns the parsed patches, or `undefined` when the file does not exist.
- */
-export function loadPersonalPatches(
-  binName: string, dir: string = resolveDshHome(),
-): PatchOptions[] | undefined {
-  const file = join(dir, PERSONAL_CONFIG_FILENAME)
-  let content: string
-  try {
-    content = readFileSync(file, 'utf8')
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException | null)?.code === 'ENOENT') return undefined
-    throw new Error(`${binName}: failed to read personal patches ${file}: ${String(error)}`)
-  }
-  return parsePatchList(binName, file, content, 'personal patches')
-}
-
-/**
- * Load a required overlay patch list: a surface overlay (`tui.cordis.yml`) or a
- * `--config <path>` overlay applied over the shared base. Same file format as
- * {@link loadPersonalPatches}, but a missing file throws, because the caller
- * named this file — its absence is a misconfiguration, not "no overlay".
+ * Load an overlay patch list: a surface overlay (`tui.cordis.yml`) or a
+ * `--config <path>` overlay applied over the shared base. The file is a
+ * top-level YAML array of loader patch entries (`@cordisjs/plugin-include`'s
+ * `PatchOptions`): id-targeted config overrides and `insert` lists, with
+ * `!!js` expressions allowed — the dialect is imported from the include
+ * itself, so patch parsing and config dumping can never drift from what the
+ * include mounts. A missing file throws, because the caller named this file:
+ * its absence is a misconfiguration, not "no overlay".
  * @param binName - the diagnostic prefix on the thrown error.
  * @param file - absolute path of the overlay file.
  * @returns the parsed patch list.
@@ -149,37 +115,32 @@ export function loadOverlayPatches(binName: string, file: string): PatchOptions[
   } catch (error) {
     throw new Error(`${binName}: failed to read overlay ${file}: ${String(error)}`)
   }
-  return parsePatchList(binName, file, content, 'overlay')
+  return parsePatchList(binName, file, content)
 }
 
 /**
- * Parse one loader patch list: a top-level YAML array of
- * `@cordisjs/plugin-include` `PatchOptions` (id-targeted config overrides and
- * `insert` lists, `!!js` expressions allowed). Every shape failure throws,
- * because a patch file that cannot be applied at all is a misconfiguration; a
- * single patch whose target row is absent stays a per-entry Loader warning, so
- * one overlay shared across surfaces does not have to match every tree.
+ * Parse one loader patch list. Every shape failure throws, because a patch
+ * file that cannot be applied at all is a misconfiguration; a single patch
+ * whose target row is absent stays a per-entry Loader warning, so one overlay
+ * shared across surfaces does not have to match every tree.
  * @param binName - the diagnostic prefix on the thrown error.
  * @param file - the source path, quoted in errors.
  * @param content - the file's text.
- * @param label - what to call this list in errors (`personal patches`, `overlay`).
  * @returns the parsed patch list.
  */
-function parsePatchList(
-  binName: string, file: string, content: string, label: string,
-): PatchOptions[] {
+function parsePatchList(binName: string, file: string, content: string): PatchOptions[] {
   let parsed: unknown
   try {
-    parsed = yaml.load(content, { schema: personalPatchesSchema })
+    parsed = yaml.load(content, { schema: entryListSchema })
   } catch (error) {
-    throw new Error(`${binName}: failed to parse ${label} ${file}: ${String(error)}`)
+    throw new Error(`${binName}: failed to parse overlay ${file}: ${String(error)}`)
   }
   if (!Array.isArray(parsed)) {
-    throw new Error(`${binName}: ${label} ${file} must be a top-level YAML array of loader patch entries`)
+    throw new Error(`${binName}: overlay ${file} must be a top-level YAML array of loader patch entries`)
   }
   parsed.forEach((entry, index) => {
     if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
-      throw new Error(`${binName}: ${label} entry ${index + 1} in ${file} must be a mapping (a loader patch entry)`)
+      throw new Error(`${binName}: overlay entry ${index + 1} in ${file} must be a mapping (a loader patch entry)`)
     }
   })
   return parsed as PatchOptions[]
@@ -189,7 +150,7 @@ function parsePatchList(
 export interface ConfigDumpLayer {
   /** Source name shown in provenance comments (a file basename or path). */
   label: string
-  /** The layer's patches, from {@link loadOverlayPatches} / {@link loadPersonalPatches}. */
+  /** The layer's patches, from {@link loadOverlayPatches}. */
   patches: PatchOptions[]
 }
 
@@ -320,70 +281,11 @@ function groupedDump(
   return lines.join('\n') + '\n'
 }
 
-/** Options for live personal-config reconciliation. */
-export interface PersonalPatchWatchOptions {
-  /** Diagnostic prefix used by {@link loadPersonalPatches}. */
-  binName: string
-  /** Harness home containing `config.yaml`; defaults to {@link resolveDshHome}. */
-  dir?: string
-  /**
-   * Compose the full patch list for a fresh personal-overlay generation —
-   * the same composition the app booted with, so a reload can interleave the
-   * new personal patches between app-owned layers (surface overlay below,
-   * profile/flag patches above). Identity when omitted: the personal overlay
-   * is the whole patch list.
-   */
-  compose?: (personalPatches: PatchOptions[]) => PatchOptions[]
-}
-
 /**
- * Watch the personal overlay through Cordis HMR and transactionally reapply it to the boot include.
- * @param ctx - settled app context containing the root Include and an active HMR service.
- * @param options - diagnostic, Harness-home, and patch-composition inputs.
- * @returns an asynchronous disposer after the exact-path watcher is ready.
- * @throws when HMR or the root Include is absent, watcher setup fails, or initial path resolution fails.
- */
-export async function watchPersonalPatches(
-  ctx: Context,
-  options: PersonalPatchWatchOptions,
-): Promise<() => Promise<void>> {
-  const { binName, dir = resolveDshHome(), compose = (patches: PatchOptions[]) => patches } = options
-  const hmr = ctx.get('hmr')
-  if (hmr === undefined) throw new Error(`${binName}: personal config watching requires the Cordis HMR service`)
-  const entry = bootstrapIncludes.get(ctx)
-  if (entry === undefined) throw new Error(`${binName}: personal config watching requires the root Include entry`)
-  const filename = join(dir, PERSONAL_CONFIG_FILENAME)
-  const register = hmr.registerConfig(filename, async () => {
-    // Re-read the include's non-patch options per refresh: a writer that
-    // updates the root Include's other options between refreshes (none exists
-    // today) must not have them silently reverted by a personal reload.
-    const { patches: _previousPatches, ...includeConfig } = entry.options.config as Include.Config
-    const personalPatches = loadPersonalPatches(binName, dir) ?? []
-    const patches = compose(personalPatches)
-    await entry.update({
-      config: {
-        ...includeConfig,
-        patches,
-      },
-    })
-  })
-  try {
-    return await register
-  } catch (error) {
-    // A surface can dispose the whole tree while the watcher is still opening
-    // (a TUI `/exit` typed during startup): the HMR effect registration then
-    // fails with INACTIVE_EFFECT. That is the app exiting exactly as asked,
-    // not a watch failure — return a no-op disposer instead of crashing.
-    if ((error as { code?: string } | null)?.code === 'INACTIVE_EFFECT') return async () => {}
-    throw error
-  }
-}
-
-/**
- * Mount and remember the exact root Include entry used by app boot and personal-config HMR.
+ * Mount the root Include entry app boot drives.
  * @param ctx - context carrying an initialized Loader service.
  * @param absoluteConfigPath - absolute YAML or JSON configuration path.
- * @param patches - initial app and personal patches, applied in order.
+ * @param patches - the surface's overlay patches, applied in order.
  * @returns the created root Include entry, or `undefined` when a surface
  * disposed the whole tree (taking the Loader service with it) while the
  * transactional create was still settling entry lifecycle.
@@ -408,9 +310,7 @@ export async function mountRootInclude(
   const includeId = await ctx.loader.create(rootInclude)
   const loader = ctx.get('loader')
   if (loader === undefined) return undefined
-  const entry = loader.resolve(includeId)
-  bootstrapIncludes.set(ctx, entry)
-  return entry
+  return loader.resolve(includeId)
 }
 
 /**
@@ -629,7 +529,7 @@ export async function assertEntriesActivated(ctx: Context, binName: string): Pro
  * @param absoluteConfigPath - the config to include; must already be absolute
  * (see {@link resolveConfigPath}).
  * @param patches - optional overlay patches applied over the included tree
- * (see {@link loadPersonalPatches}); an empty list mounts none.
+ * (see {@link loadOverlayPatches}); an empty list mounts none.
  * @param prepare - optional host setup run after Loader installation and before any config-tree entry mounts.
  * @returns the root context once every entry has started, or as soon as a
  * surface disposed the tree while startup was still in flight.
diff --git a/packages/ui/app-boot/tests/config-dump.spec.ts b/packages/ui/app-boot/tests/config-dump.spec.ts
index 99af81f2c2..4f5d8e83e5 100644
--- a/packages/ui/app-boot/tests/config-dump.spec.ts
+++ b/packages/ui/app-boot/tests/config-dump.spec.ts
@@ -49,17 +49,17 @@ describe('renderConfigDump', () => {
       '      name: ./noop.mjs',
       '',
     ].join('\n'))
-    const personal = join(dir, 'personal.yml')
-    writeFileSync(personal, [
+    const user = join(dir, 'user.yml')
+    writeFileSync(user, [
       '- id: surface-extra',
       '  config:',
-      '    value: personal',
+      '    value: user',
       '',
     ].join('\n'))
 
     const dump = renderConfigDump(NAME, base, [
       { label: 'surface.yml', patches: loadOverlayPatches(NAME, surface) },
-      { label: 'personal.yml', patches: loadOverlayPatches(NAME, personal) },
+      { label: 'user.yml', patches: loadOverlayPatches(NAME, user) },
     ], () => {})
     // Comments do not break loadability: the dump parses as one document
     // equal to what boot() would mount.
@@ -74,7 +74,7 @@ describe('renderConfigDump', () => {
         config: { value: 'surface', key: { __jsExpr: 'process.env.DSH_DUMP_SPEC' } },
       },
       { id: 'untouched', name: './noop.mjs' },
-      { id: 'surface-extra', name: './noop.mjs', config: { value: 'personal' } },
+      { id: 'surface-extra', name: './noop.mjs', config: { value: 'user' } },
     ])
     // Unevaluated: the expression text round-trips as a !!js scalar.
     expect(dump).toContain('!!js process.env.DSH_DUMP_SPEC')
@@ -82,7 +82,7 @@ describe('renderConfigDump', () => {
     // row; an inserted row carries the inserting layer as its origin.
     expect(dump).toContain('# == base.yml, patched by surface.yml')
     expect(dump).toContain('# == base.yml\n- id: untouched')
-    expect(dump).toContain('# == surface.yml, patched by personal.yml\n- id: surface-extra')
+    expect(dump).toContain('# == surface.yml, patched by user.yml\n- id: surface-extra')
     expect(dump.indexOf('# == base.yml, patched by surface.yml')).toBeLessThan(dump.indexOf('# == base.yml\n- id: untouched'))
   })
 
diff --git a/packages/ui/app-boot/tests/config-reload.spec.ts b/packages/ui/app-boot/tests/config-reload.spec.ts
index d9f4ffa830..81ba2fc845 100644
--- a/packages/ui/app-boot/tests/config-reload.spec.ts
+++ b/packages/ui/app-boot/tests/config-reload.spec.ts
@@ -341,12 +341,12 @@ describe('include refresh with overlay patches', () => {
 
 describe('include patches layered over one base', () => {
   it('lets a later patch configure or disable a row an earlier patch inserted', async () => {
-    // The surface/`--config`/personal composition: `dsh` includes one shared
-    // base and applies each source as its own patch list at the SAME include
-    // level, because patches never cross an include boundary. A later layer
-    // must therefore be able to reach a row an earlier layer inserted —
-    // otherwise every surface-only row (the whole TUI front door) would be
-    // invisible to the user's `~/.dsh/config.yaml`.
+    // The surface/`--config` composition: `dsh` includes one shared base and
+    // applies each source as its own patch list at the SAME include level,
+    // because patches never cross an include boundary. A later layer must
+    // therefore be able to reach a row an earlier layer inserted — otherwise
+    // every surface-only row (the whole TUI front door) would be invisible to
+    // the user's `--config` overlay.
     const dir = mkdtempSync(join(tmpdir(), 'dsh-config-layered-'))
     writeFileSync(join(dir, 'noop.mjs'), NOOP_PLUGIN)
     writeFileSync(join(dir, 'base.yml'), '- id: shared\n  name: ./noop.mjs\n  config:\n    value: base\n')
@@ -370,7 +370,7 @@ describe('include patches layered over one base', () => {
       // Layer 2 (the user): reconfigure one inserted row and disable the other.
       '      - id: surface-kept',
       '        config:',
-      '          value: personal',
+      '          value: user',
       '      - id: surface-dropped',
       '        disabled: true',
       '',
@@ -378,7 +378,7 @@ describe('include patches layered over one base', () => {
     const ctx = await boot(NAME, join(dir, 'cordis.yml'))
     try {
       expect(entryConfig(ctx, 'shared')).toEqual({ value: 'surface' })
-      expect(entryConfig(ctx, 'surface-kept')).toEqual({ value: 'personal' })
+      expect(entryConfig(ctx, 'surface-kept')).toEqual({ value: 'user' })
       const dropped = [...ctx.loader.entries()].find(entry => entry.options.id === 'surface-dropped')
       expect(dropped?.options.disabled).toBe(true)
       expect(dropped?.fiber).toBeUndefined()
diff --git a/packages/ui/app-boot/tests/personal-config.spec.ts b/packages/ui/app-boot/tests/personal-config.spec.ts
deleted file mode 100644
index 53df1d84b7..0000000000
--- a/packages/ui/app-boot/tests/personal-config.spec.ts
+++ /dev/null
@@ -1,270 +0,0 @@
-/**
- * Personal-config behavior of `dsh-app-boot`: the Harness home (`~/.dsh`)
- * `config.yaml` overlay loader and `boot()` applying the personal overlay over
- * a real Loader tree.
- */
-
-import { mkdirSync, mkdtempSync, unlinkSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { afterEach, describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
-import Hmr from '@cordisjs/plugin-hmr'
-import Loader from '@cordisjs/plugin-loader'
-import Timer from '@cordisjs/plugin-timer'
-import {
-  boot,
-  loadPersonalPatches,
-  PERSONAL_CONFIG_FILENAME,
-  watchPersonalPatches,
-} from '../src/index.ts'
-
-const NAME = 'dsh-test-bin'
-
-const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-personal-config-'))
-
-async function eventually(test: () => boolean, message: string): Promise<void> {
-  const deadline = Date.now() + 10_000
-  while (!test()) {
-    if (Date.now() >= deadline) throw new Error(message)
-    await new Promise(resolve => setTimeout(resolve, 10))
-  }
-}
-
-const settleChokidarChangeThrottle = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 75))
-
-describe('loadPersonalPatches', () => {
-  afterEach(() => {
-    delete process.env.DSH_HOME
-  })
-
-  it('returns undefined when no personal patches file exists', () => {
-    expect(loadPersonalPatches(NAME, tmp())).toBeUndefined()
-  })
-
-  it('parses a patch list and preserves !!js expressions as loader expression nodes', () => {
-    const dir = tmp()
-    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), [
-      '- id: tui-agent',
-      "  name: '@deepseek-ai/dsh-tui-demo'",
-      '  config:',
-      '    model: !!js process.env.DSH_SPEC_MODEL',
-      '- insert:',
-      '    - id: llm',
-      "      name: '@deepseek-ai/dsh-llm-pi-ai'",
-      '',
-    ].join('\n'))
-    const patches = loadPersonalPatches(NAME, dir)
-    expect(patches).toHaveLength(2)
-    expect(patches?.[0]).toMatchObject({
-      id: 'tui-agent',
-      config: { model: { __jsExpr: 'process.env.DSH_SPEC_MODEL' } },
-    })
-    expect(patches?.[1]?.insert).toHaveLength(1)
-  })
-
-  it('defaults its directory to the Harness home ($DSH_HOME)', () => {
-    const dir = tmp()
-    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), '- id: x\n  config:\n    a: 1\n')
-    process.env.DSH_HOME = dir
-    expect(loadPersonalPatches(NAME)).toHaveLength(1)
-  })
-
-  it('fails loud on an unreadable file (a present personal config is never skipped)', () => {
-    const dir = tmp()
-    mkdirSync(join(dir, PERSONAL_CONFIG_FILENAME)) // a directory: present, unreadable as a file
-    expect(() => loadPersonalPatches(NAME, dir))
-      .toThrow(new RegExp(`^${NAME}: failed to read personal patches `))
-  })
-
-  it('fails loud on unparsable YAML and on a !!js tag with no expression body', () => {
-    const dir = tmp()
-    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), 'invalid: [unclosed\n')
-    expect(() => loadPersonalPatches(NAME, dir))
-      .toThrow(new RegExp(`^${NAME}: failed to parse personal patches `))
-    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), '- id: x\n  config:\n    a: !!js\n')
-    expect(() => loadPersonalPatches(NAME, dir))
-      .toThrow(new RegExp(`^${NAME}: failed to parse personal patches `))
-  })
-
-  it('fails loud when the file is not a top-level array or an entry is not an object', () => {
-    const dir = tmp()
-    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), 'id: not-a-list\n')
-    expect(() => loadPersonalPatches(NAME, dir))
-      .toThrow('must be a top-level YAML array of loader patch entries')
-    writeFileSync(join(dir, PERSONAL_CONFIG_FILENAME), '- just-a-string\n')
-    expect(() => loadPersonalPatches(NAME, dir))
-      .toThrow(`${NAME}: personal patches entry 1 in`)
-  })
-})
-
-describe('boot with personal patches', () => {
-  function writeTree(dir: string): string {
-    writeFileSync(join(dir, 'noop.mjs'), [
-      'export const name = "noop"',
-      'export function apply(_ctx, config = {}) {',
-      '  if (config.fail) throw new Error("candidate config failed")',
-      '}',
-      '',
-    ].join('\n'))
-    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: base\n')
-    return join(dir, 'cordis.yml')
-  }
-
-  function entryConfig(ctx: Context, id: string): unknown {
-    return [...ctx.loader.entries()].find(entry => entry.options.id === id)?.options.config
-  }
-
-  it('applies id-targeted overrides, inserts, and interpolates !!js from the environment', async () => {
-    const dir = tmp()
-    const personal = tmp()
-    writeFileSync(join(personal, PERSONAL_CONFIG_FILENAME), [
-      '- id: noop',
-      '  name: ./noop.mjs',
-      '  config:',
-      '    value: !!js process.env.DSH_APP_BOOT_PERSONAL_SPEC',
-      '- insert:',
-      '    - id: personal-extra',
-      '      name: ./noop.mjs',
-      '',
-    ].join('\n'))
-    process.env['DSH_APP_BOOT_PERSONAL_SPEC'] = 'personal-value'
-    const ctx = await boot(NAME, writeTree(dir), loadPersonalPatches(NAME, personal))
-    try {
-      const noop = [...ctx.loader.entries()].find(entry => entry.options.id === 'noop')
-      // The mounted plugin received the interpolated environment value.
-      expect(noop?.fiber?.config).toEqual({ value: 'personal-value' })
-      expect([...ctx.loader.entries()].some(entry => entry.options.id === 'personal-extra')).toBe(true)
-    } finally {
-      await ctx.fiber.dispose()
-      delete process.env['DSH_APP_BOOT_PERSONAL_SPEC']
-    }
-  })
-
-  it('mounts no patch layer for an absent or empty personal overlay', async () => {
-    const dir = tmp()
-    const ctx = await boot(NAME, writeTree(dir), loadPersonalPatches(NAME, tmp()))
-    try {
-      expect(entryConfig(ctx, 'noop')).toEqual({ value: 'base' })
-    } finally {
-      await ctx.fiber.dispose()
-    }
-    const empty = tmp()
-    writeFileSync(join(empty, PERSONAL_CONFIG_FILENAME), '[]\n')
-    const ctxEmpty = await boot(NAME, writeTree(tmp()), loadPersonalPatches(NAME, empty))
-    try {
-      expect(entryConfig(ctxEmpty, 'noop')).toEqual({ value: 'base' })
-    } finally {
-      await ctxEmpty.fiber.dispose()
-    }
-  })
-
-  it('watches add, failure, recovery, and removal through transactional HMR', { timeout: 20_000 }, async () => {
-    const dir = tmp()
-    const personal = tmp()
-    const filename = join(personal, PERSONAL_CONFIG_FILENAME)
-    const basePatches = [{ id: 'noop', config: { value: 'generated' } }]
-    const ctx = await boot(NAME, writeTree(dir), basePatches)
-    await ctx.plugin(Timer)
-    await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
-    const failures: Array<{ filename: string; error: Error }> = []
-    ctx.on('hmr/config-update-failed', (failedFilename, error) => {
-      failures.push({ filename: failedFilename, error })
-    })
-    const dispose = await watchPersonalPatches(ctx, {
-      binName: NAME,
-      dir: personal,
-      compose: personalPatches => [...basePatches, ...personalPatches],
-    })
-    try {
-      writeFileSync(filename, '- id: noop\n  config:\n    value: live\n')
-      await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'live', 'personal config addition was not applied')
-
-      writeFileSync(filename, '- id: noop\n  config:\n    fail: true\n')
-      await eventually(() => failures.length === 1, 'failed candidate was not broadcast')
-      expect(failures[0]).toMatchObject({ filename })
-      expect(failures[0]?.error).toBeInstanceOf(Error)
-      expect((entryConfig(ctx, 'noop') as { value?: string }).value).toBe('live')
-      await settleChokidarChangeThrottle()
-
-      writeFileSync(filename, 'invalid: [unclosed\n')
-      await eventually(() => failures.length === 2, 'parse failure was not broadcast')
-      expect(failures[1]?.error).toBeInstanceOf(Error)
-      expect((entryConfig(ctx, 'noop') as { value?: string }).value).toBe('live')
-      await settleChokidarChangeThrottle()
-
-      writeFileSync(filename, '- id: noop\n  config:\n    value: recovered\n')
-      await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'recovered', 'valid recovery was not applied')
-      await settleChokidarChangeThrottle()
-
-      unlinkSync(filename)
-      await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'generated', 'personal config removal did not restore the app-owned patch')
-      expect(failures).toHaveLength(2)
-      await settleChokidarChangeThrottle()
-
-      // Default compose: the personal overlay IS the whole patch list, so a
-      // fresh generation replaces the app-owned layer instead of stacking on it.
-      await dispose()
-      const disposeDefault = await watchPersonalPatches(ctx, { binName: NAME, dir: personal })
-      try {
-        writeFileSync(filename, '- id: noop\n  config:\n    value: identity\n')
-        await eventually(() => (entryConfig(ctx, 'noop') as { value?: string }).value === 'identity', 'default-compose personal patch was not applied')
-      } finally {
-        await disposeDefault()
-      }
-    } finally {
-      await dispose()
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('fails loud when the exact watcher lacks HMR or a root Include', async () => {
-    const dir = tmp()
-    const withoutHmr = await boot(NAME, writeTree(dir))
-    await expect(watchPersonalPatches(withoutHmr, { binName: NAME, dir: tmp() })).rejects.toThrow('requires the Cordis HMR service')
-    await withoutHmr.fiber.dispose()
-
-    const withoutInclude = new Context()
-    withoutInclude.baseUrl = pathToFileURL(`${tmp()}/`).href
-    await withoutInclude.plugin(Loader)
-    await withoutInclude.plugin(Timer)
-    await withoutInclude.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
-    await expect(watchPersonalPatches(withoutInclude, { binName: NAME, dir: tmp() })).rejects.toThrow('requires the root Include entry')
-    await withoutInclude.fiber.dispose()
-  })
-
-  it('returns a no-op disposer when the tree is disposed while the watcher opens', async () => {
-    // A TUI `/exit` typed during startup disposes the whole tree while
-    // registerConfig's effect registration is still in flight (the HMR effect
-    // then fails with INACTIVE_EFFECT); the app is exiting exactly as asked,
-    // so the watcher must not crash the process. The stub makes the race
-    // deterministic — the live-teardown ordering itself is not stageable.
-    const dir = tmp()
-    const ctx = await boot(NAME, writeTree(dir))
-    try {
-      const teardown = Object.assign(new Error('cannot create effect on inactive context'), { code: 'INACTIVE_EFFECT' })
-      ctx.provide('hmr', { registerConfig: () => Promise.reject(teardown) })
-      const dispose = await watchPersonalPatches(ctx, { binName: NAME, dir: tmp() })
-      await expect(dispose()).resolves.toBeUndefined()
-    } finally {
-      await ctx.fiber.dispose()
-    }
-  })
-
-  it('propagates registration failures other than mid-teardown', async () => {
-    const dir = tmp()
-    const personal = tmp()
-    const ctx = await boot(NAME, writeTree(dir))
-    try {
-      await ctx.plugin(Timer)
-      await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
-      const dispose = await watchPersonalPatches(ctx, { binName: NAME, dir: personal })
-      // Same personal path registered twice: HMR refuses; not a teardown race.
-      await expect(watchPersonalPatches(ctx, { binName: NAME, dir: personal })).rejects.toThrow('already registered')
-      await dispose()
-    } finally {
-      await ctx.fiber.dispose()
-    }
-  })
-})

From 0512b12714634ffcdddef1df741e34c2fed53cb7 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Tue, 4 Aug 2026 16:17:32 +0800
Subject: [PATCH 021/516] feat(config)!: one ordering for configuration
 sources, and a bootstrap deny rule
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

$DSH_HOME/.env had just become an ordinary environment layer, which left the
harness resolving user-facing values from a flattened process.env that could
no longer say where a value came from. A key stored through the web page
stayed shadowed by an older key in the user's own .env. An endpoint could be
redirected by the project: the invoking directory's .env is materialized like
every other layer, and a base URL decides where a resolved API key is sent, so
a DEEPSEEK_BASE_URL written into a model-editable workspace would send the
user's credential — and the prompts carrying their code — to whatever host
that file named.

Give every user-facing value one ordering, with four kinds of source:

  explicit for this run     per-operation override, CLI argument
  > authored by deployment  --config / --config-replace
  > this launch's shell     inherited process environment
  > product-managed store   settings.yaml, .credentials.yaml
  > discovered file         $DSH_HOME/.env
  > defaults                schema default, shipped base, public default

The domains differ only in which tiers exist. The earlier split — credentials
ranking the environment over the managed file while settings ranked over the
environment — was inconsistent: the distinguishing fact is who authored the
source, not the domain.

packages/util/environment owns an immutable snapshot with per-layer
provenance. getFrom(name, sources) searches only the layers a caller names,
and omitting one is a refusal rather than a demotion: the adapters ask for
['process', 'user-env'], so no reordering can let a project file back into a
decision it was excluded from.

isBootstrapOnly rejects, before anything is materialized, any .env setting a
variable that governs how a process launches (PATH, SHELL, NODE_OPTIONS,
LD_PRELOAD), where code or model-visible instructions load from (the whole
DSH_* namespace, HOME, XDG_*), or how the network is reached (proxy and CA
variables). The namespace is denied wholesale so a switch added later cannot
become settable by being forgotten, and there is no opt-out.

verify-config-source-ownership keeps both rules: no unregistered process.env
read under packages/*/*/src (26 allowlisted with reasons), and no apiKey,
baseURL, or headers inlined from the environment in shipped Cordis config —
removing those inlines is what makes the deployment tier meaningful.
---
 ...4-configuration-source-ownership.i18n.yaml |   6 +
 ...26-08-04-configuration-source-ownership.md |  63 +++++++
 ...08-04-configuration-source-ownership.zh.md |  65 +++++++
 THIRD_PARTY_NOTICES.md                        |   1 +
 apps/cli/config/base.cordis.yml               |   1 -
 apps/cli/config/tui.cordis.yml                |   2 -
 apps/cli/config/web.cordis.yml                |   5 -
 apps/cli/package.json                         |   3 +-
 apps/cli/src/app-cli-entry.ts                 |   6 +
 apps/cli/src/bin.ts                           |  15 +-
 apps/cli/src/headless.ts                      |   7 +-
 apps/cli/src/tui.ts                           |   5 +
 apps/cli/src/web.ts                           |   4 +
 apps/cli/tests/tui-keyless-smoke.e2e.ts       |  12 +-
 apps/cli/tsconfig.json                        |   3 +
 docs/config-catalog.md                        |  13 +-
 examples/acp-agent/cordis.yml                 |   2 -
 examples/acp-agent/retry.cordis.yml           |   2 -
 examples/jsonrpc-agent/cordis.yml             |   2 -
 .../jsonrpc-agent/persistent-tools.cordis.yml |   2 -
 package.json                                  | 157 +++++++--------
 .../credentials-local/package.json            |   2 +
 .../credentials-local/src/index.ts            |  75 ++++++--
 .../credentials-local/tests/local.spec.ts     |  69 +++++++
 .../credentials-local/tsconfig.json           |   3 +
 packages/llm/llm-deepseek/package.json        |   2 +
 packages/llm/llm-deepseek/src/index.ts        |  28 ++-
 .../llm/llm-deepseek/tests/adapter.spec.ts    |  22 ++-
 packages/llm/llm-deepseek/tsconfig.json       |   3 +
 packages/llm/llm-pi-ai/package.json           |   2 +
 packages/llm/llm-pi-ai/src/index.ts           |   7 +-
 packages/llm/llm-pi-ai/tsconfig.json          |   3 +
 packages/ui/app-boot/package.json             |   3 +
 packages/ui/app-boot/src/index.ts             |  76 +++++++-
 packages/ui/app-boot/tests/app-boot.spec.ts   |  64 ++++++-
 packages/ui/app-boot/tsconfig.json            |   3 +
 packages/util/environment/README.i18n.yaml    |   6 +
 packages/util/environment/README.md           |  42 +++++
 packages/util/environment/README.zh.md        |  42 +++++
 packages/util/environment/package.json        |  37 ++++
 packages/util/environment/src/index.ts        | 178 ++++++++++++++++++
 packages/util/environment/src/invariant.ts    |  30 +++
 .../environment/tests/environment.spec.ts     | 118 ++++++++++++
 packages/util/environment/tsconfig.json       |  15 ++
 packages/web/web-search-deepseek/package.json |   2 +
 packages/web/web-search-deepseek/src/index.ts |   7 +-
 .../web/web-search-deepseek/tsconfig.json     |   3 +
 packages/web/web-search-exa/package.json      |   2 +
 packages/web/web-search-exa/src/index.ts      |   6 +-
 packages/web/web-search-exa/tsconfig.json     |   3 +
 .../web/web-search-perplexity/package.json    |   2 +
 .../web/web-search-perplexity/src/index.ts    |   6 +-
 .../web/web-search-perplexity/tsconfig.json   |   3 +
 pnpm-lock.yaml                                |  45 +++++
 python/sdk-runtime/package.json               |   1 +
 scripts/run-gates.ts                          |   1 +
 scripts/verify-config-source-ownership.ts     | 117 ++++++++++++
 .../verify-package-readme-model-experience.ts |   1 +
 tsconfig.host.json                            |   1 +
 59 files changed, 1241 insertions(+), 165 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
 create mode 100644 packages/util/environment/README.i18n.yaml
 create mode 100644 packages/util/environment/README.md
 create mode 100644 packages/util/environment/README.zh.md
 create mode 100644 packages/util/environment/package.json
 create mode 100644 packages/util/environment/src/index.ts
 create mode 100644 packages/util/environment/src/invariant.ts
 create mode 100644 packages/util/environment/tests/environment.spec.ts
 create mode 100644 packages/util/environment/tsconfig.json
 create mode 100644 scripts/verify-config-source-ownership.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
new file mode 100644
index 0000000000..7ff8cfa74c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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/architecture/2026-08-04-configuration-source-ownership.md
+2026-08-04-configuration-source-ownership.md: f19067abb899e41742f88ce6d17623bc5b82d008
+2026-08-04-configuration-source-ownership.zh.md: a5fd7c61ee71eb9ed9184c3f9c557fb1c3b951ad
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
new file mode 100644
index 0000000000..f19067abb8
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -0,0 +1,63 @@
+# Agent Note: One ordering for configuration sources, and what a discovered file may not decide
+
+Status: implemented
+
+English | [中文](2026-08-04-configuration-source-ownership.zh.md)
+
+## Problem
+
+`$DSH_HOME/.env` had just [become an ordinary environment layer](2026-08-04-credentials-yaml-and-user-environment-layer.md), which left the harness resolving user-facing values from a flattened `process.env` that could no longer say where a value came from. Three consequences followed.
+
+A key stored through the web page stayed shadowed by an older key in the user's own `.env`, because the credential provider compared "the environment" against its file and the environment now included that file. The migration dead end the split was supposed to remove had simply moved.
+
+An endpoint could be redirected by the project. The invoking directory's `.env` is materialized like every other layer, and a base URL decides where a resolved API key is sent — so a `DEEPSEEK_BASE_URL` written into a workspace the model can edit would send the user's own credential, and the prompts carrying their code, to whatever host that file named. Nothing about the flattened view could distinguish that from the operator exporting the same variable.
+
+And `!!js process.env.X` in the shipped composition made the same value reachable twice: once through the entry config and once through whatever ladder its consumer applied, with the winner decided by layer order rather than by what the value means.
+
+## Decision
+
+**One ordering, four kinds of source.** Every user-facing value resolves in the same order; the domains differ only in which tiers exist.
+
+```text
+explicit for this run     per-operation override, CLI argument
+> authored by deployment  --config / --config-replace
+> this launch's shell     inherited process environment
+> product-managed store   settings.yaml, .credentials.yaml
+> discovered file         $DSH_HOME/.env
+> defaults                schema default, shipped base, provider public default
+```
+
+Credentials have no deployment tier (configuration carries a reference, never a value) and no default. Endpoints have every tier. Model selection has CLI, settings, and the shipped default. The earlier proposal ranked a UI-written credential *below* the environment while ranking UI-written settings *above* it; the distinguishing fact is not the domain but who authored the file, so `.credentials.yaml` and `settings.yaml` now sit together, both under the launching shell and both over a discovered `.env`.
+
+**The invoking directory's `.env` decides no credential and no route.** `EnvironmentSnapshot.getFrom(name, sources)` searches only the layers a caller names, and omitting one is a refusal rather than a demotion: the adapters ask for `['process', 'user-env']`, so no future reordering can let a project file back into a decision it was excluded from. A project `.env` remains an ordinary environment layer for ordinary variables.
+
+**A discovered file may not decide how the process starts.** `isBootstrapOnly` rejects, at load and before anything is materialized, any `.env` that sets a variable governing how a process launches (`PATH`, `SHELL`, `NODE_OPTIONS`, `LD_PRELOAD`, …), where code or model-visible instructions load from (the whole `DSH_*` namespace, `HOME`, `XDG_*`), or how the network is reached and trusted (proxy and CA variables). Matching is case-insensitive, so `https_proxy` is not a bypass.
+
+The whole `DSH_*` namespace is denied rather than an audited subset. The harness's own switches — the permission mode, the agents home that holds model-visible skills, the bundled skill root — are exactly what a hostile project would reach for, and a switch added later must not become settable by being forgotten. There is no opt-out: an escape hatch would have to be readable from somewhere, and anything a discovered file could set is the hole itself.
+
+**`packages/util/environment` owns the snapshot**, deliberately as a utility rather than a three-package capability seam. The snapshot is frozen before Cordis starts and injected once by the launcher, so there is no runtime implementation to swap; consumers need types and pure functions, which a `util/` package gives them without depending on a UI package. `environmentOf(ctx)` returns the launcher's snapshot, or the inherited environment as the only layer — an SDK host or bare `cordis.yml` discovered no files, so its single layer really is what it was launched with, and the same trusted lookups keep working there unchanged.
+
+**`verify-config-source-ownership`** keeps both rules: no unregistered `process.env` read under `packages/*/*/src` (26 allowlisted, each with the reason it is a process fact), and no `apiKey`/`baseURL`/`headers` inlined from the environment in shipped Cordis configuration. Removing those inlines is what makes the deployment tier meaningful — with the shipped tree silent on `baseURL`, a present value means a human or deployment set it.
+
+## Consequences
+
+- The web credential form now takes effect against an older key in the user's `.env`; only a key exported in the launching shell still makes it read-only, and the diagnostic says so.
+- A `.env` holding `DSH_*`, `PATH`, or a proxy variable fails the launch instead of being applied. Developers keeping switches in a repository `.env` move them to their shell — a deliberate, loud break.
+- `--config` is no longer overridable by a stale shell endpoint, so a deployment can pin an enterprise gateway.
+- Given up: an endpoint or key in the invoking directory's `.env` no longer applies. Per-project routing is a `--config` overlay or an `export` in that project's shell.
+- Not solved: the layers are still materialized into `process.env`, so ordinary project variables continue to reach child processes under the subprocess scrub. Bootstrap variables cannot come from a file at all, which closes the escalation path; a project `.env` setting something like `GIT_SSH_COMMAND` for the tools an agent runs remains possible and is recorded as a limitation on the package.
+- Exa and Perplexity still capture their key at load time rather than through the credential seam. They no longer read raw `process.env` — they resolve through the trusted layers — but converting them to per-request seam resolution is separate work.
+
+## Alternatives considered
+
+**Keep the proposal's split ladders (credentials env-over-file, endpoints settings-over-env).** Rejected on its own inconsistency: both arguments — "an export is this run's intent" and "a deployment's file should not be rewritten by a stale shell" — apply to both domains. Sorting by *who authored the source* explains both and produces one table instead of four.
+
+**Let the invoking directory's `.env` supply a credential, ranked below the managed store.** Rejected: with no key stored, a hostile project's key would be used silently, and the account holder reads every prompt sent under it. That is the same exfiltration the endpoint rule exists to prevent, so it takes the same answer.
+
+**Audit an allowlist of `DSH_*` variables a `.env` may set.** Rejected: the list would have to be re-audited on every new switch, and the failure mode of forgetting is silent. Denying the namespace fails safe.
+
+**Rank a bootstrap variable below the process layer instead of rejecting it.** Rejected: `PATH` and `NODE_OPTIONS` have no meaningful "loser" behavior — a user who put one in a `.env` believes it applies, and silently ignoring it is the "my setting has no effect" failure this whole series exists to remove.
+
+**Build the snapshot as a three-package capability seam (`environment` / `environment-local` / consumers).** Rejected as premature: the producer runs before Cordis exists and there is no second implementation to select. The repository rule is to not split preemptively.
+
+**Stop materializing the layers into `process.env`.** Deferred, not rejected: it would keep project variables out of child processes entirely, but it silently breaks any user `--config` tree that reads `!!js process.env.X`. The snapshot is already the authority for everything the harness resolves, so this can land later without changing any ladder.
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
new file mode 100644
index 0000000000..a5fd7c61ee
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -0,0 +1,65 @@
+# Agent Note: 配置来源的统一顺序，以及被发现的文件不得决定什么
+
+Status: implemented
+
+[English](2026-08-04-configuration-source-ownership.md) | 中文
+
+## Problem
+
+`$DSH_HOME/.env` 刚刚[变成普通环境层](2026-08-04-credentials-yaml-and-user-environment-layer.md)，这使得 harness 解析面向用户的值时面对的是一个压平的 `process.env`，再也说不清某个值来自哪里。由此产生三个后果。
+
+通过 Web 页面存下的密钥仍然被用户自己 `.env` 里更旧的密钥遮蔽，因为凭据 provider 是拿「环境」与自己的文件比较，而现在环境包含了那个文件。这次拆分本该消除的迁移死路，只是换了个位置。
+
+endpoint 可以被项目重定向。调用目录的 `.env` 和其他层一样会被物化，而 base URL 决定已解析的 API key 发往何处——于是写进模型可编辑工作区的 `DEEPSEEK_BASE_URL`，会把用户自己的凭据、以及承载其代码的提示词，一起发给该文件指定的任何主机。压平的视图无法把这件事和运维显式 export 同一个变量区分开。
+
+而已交付组合里的 `!!js process.env.X` 让同一个值有两条抵达路径：一条经 entry config，一条经消费方各自的 ladder，胜负取决于层序而非这个值的语义。
+
+## Decision
+
+**一条顺序，四类来源。** 每个面向用户的值按同一顺序解析；各领域的差别只在于哪些层存在。
+
+```text
+explicit for this run     per-operation override, CLI argument
+> authored by deployment  --config / --config-replace
+> this launch's shell     inherited process environment
+> product-managed store   settings.yaml, .credentials.yaml
+> discovered file         $DSH_HOME/.env
+> defaults                schema default, shipped base, provider public default
+```
+
+自上而下依次是：本次运行的显式意图、部署授权、本次启动的 shell、产品受管存储、被发现的文件、默认值。
+
+凭据没有部署层（配置携带引用，从不携带值），也没有默认值层。endpoint 拥有全部层。模型选择只有 CLI、settings 与已交付默认值。此前的方案把 UI 写入的凭据排在环境*之下*，却把 UI 写入的 settings 排在环境*之上*；真正的区分依据不是领域，而是这个文件由谁书写，因此 `.credentials.yaml` 与 `settings.yaml` 现在并列，同在启动 shell 之下、同在被发现的 `.env` 之上。
+
+**调用目录的 `.env` 不决定任何凭据与路由。** `EnvironmentSnapshot.getFrom(name, sources)` 只搜索调用方点名的层，省略某层是拒绝而不是降级：适配器请求的是 `['process', 'user-env']`，因此后续任何重新排序都无法让项目文件重新进入一个它被排除在外的决策。对普通变量而言，项目 `.env` 仍然是普通环境层。
+
+**被发现的文件不得决定进程如何启动。** `isBootstrapOnly` 会在加载时、且在物化任何内容之前，拒绝任何设置了下列变量的 `.env`：决定进程如何启动的（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD` 等）、决定代码或模型可见指令从哪里加载的（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），以及决定网络如何抵达与信任的（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
+
+被拒绝的是整个 `DSH_*` 命名空间，而不是一份经过审查的子集。harness 自己的开关——权限模式、存放模型可见 skill（技能）的 agents home、内置 skill 根目录——恰恰是敌意项目最想伸手的地方，而后来新增的开关不能因为被遗忘就变得可设置。不设逃生门：逃生门本身总得从某处读取，而任何被发现的文件能设置的东西，就是那个漏洞本身。
+
+**`packages/util/environment` 拥有该快照**，刻意做成 utility 而不是三包能力 seam。快照在 Cordis 启动前就冻结，并由启动器一次性注入，因此不存在需要切换的运行时实现；消费方需要的只是类型和纯函数，而 `util/` 包能提供这些且不必依赖 UI 包。`environmentOf(ctx)` 返回启动器的快照，或者返回只含继承环境的那一层——SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，它那唯一一层确实就是它被启动时的环境，因此同样的受信查询在那里原样继续工作。
+
+**`verify-config-source-ownership`** 守住这两条规则：`packages/*/*/src` 下没有未登记的 `process.env` 读取（26 处在 allowlist 中，各自写明它为何是进程事实），以及已交付 Cordis 配置中不得从环境内联 `apiKey`/`baseURL`/`headers`。删除这些内联正是「部署层」得以成立的原因——已交付配置树对 `baseURL` 保持沉默之后，「有值」就意味着「人或部署设过它」。
+
+## Consequences
+
+- Web 凭据表单现在能压过用户 `.env` 里更旧的密钥；只有在启动 shell 里 export 的密钥才会让它变成只读，诊断信息也会这么说。
+- 含 `DSH_*`、`PATH` 或 proxy 变量的 `.env` 会导致启动失败而不是被应用。把开关放在仓库 `.env` 里的开发者需要改放到 shell——这是一次刻意且响亮的破坏。
+- `--config` 不再会被陈旧的 shell endpoint 覆盖，因此部署方可以钉住企业网关。
+- 放弃的：调用目录 `.env` 里的 endpoint 或密钥不再生效。按项目切换路由请用 `--config` overlay 或该项目 shell 里的 `export`。
+- 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件，提权路径已封闭；项目 `.env` 为 agent 运行的工具设置诸如 `GIT_SSH_COMMAND` 之类的变量仍然可能，已作为限制记录在该包上。
+- Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求经 seam 解析是另一件事。
+
+## Alternatives considered
+
+**沿用方案里分开的两条 ladder（凭据环境压过文件、endpoint settings 压过环境）。** 因其自身的不自洽而否决：两条理由——「export 是本次运行的意图」和「部署方的文件不该被陈旧 shell 改写」——对两个领域同样成立。按*来源由谁书写*排序能同时解释两者，并且把四张表变成一张。
+
+**允许调用目录 `.env` 提供凭据，排在受管存储之下。** 否决：在没有存储密钥时，敌意项目的密钥会被静默使用，而该账号持有者能读到以它发出的每一条提示词。这与 endpoint 规则要防的外泄是同一件事，因此答案也相同。
+
+**审查出一份 `.env` 可设置的 `DSH_*` 白名单。** 否决：每新增一个开关都要重新审查，而遗漏的失败模式是静默的。拒绝整个命名空间是 fail safe。
+
+**把 bootstrap 变量排在 process 层之下，而不是拒绝它。** 否决：`PATH` 和 `NODE_OPTIONS` 没有有意义的「输了之后」行为——把它写进 `.env` 的用户认为它生效，而静默忽略正是整个系列要消除的那种「我的设置没有效果」。
+
+**把快照做成三包能力 seam（`environment` / `environment-local` / 消费方）。** 作为过早拆分而否决：生产方在 Cordis 存在之前就运行，也没有第二个实现需要选择。仓库规则是不要预先拆分。
+
+**不再把各层物化进 `process.env`。** 延后而非否决：它能让项目变量彻底进不了子进程，但会静默破坏任何读 `!!js process.env.X` 的用户 `--config` 树。快照已经是 harness 解析一切的依据，因此这件事以后落地也不改变任何 ladder。
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 515004086e..92ea0d2406 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -52,6 +52,7 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`clsx`](https://github.com/lukeed/clsx) | MIT |
 | [`commander`](https://github.com/tj/commander.js) | MIT |
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
+| [`dotenv`](https://github.com/motdotla/dotenv) | BSD-2-Clause |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
 | [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT |
 | [`immer`](https://github.com/immerjs/immer) | MIT |
diff --git a/apps/cli/config/base.cordis.yml b/apps/cli/config/base.cordis.yml
index aea2f8934c..9985e8fbd0 100644
--- a/apps/cli/config/base.cordis.yml
+++ b/apps/cli/config/base.cordis.yml
@@ -360,7 +360,6 @@
   name: '@deepseek-ai/dsh-web-search-deepseek'
   config:
     apiKeyEnv: DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
 
 - id: tool-web
   name: '@deepseek-ai/dsh-tool-web'
diff --git a/apps/cli/config/tui.cordis.yml b/apps/cli/config/tui.cordis.yml
index 02d8649447..a3118a5419 100644
--- a/apps/cli/config/tui.cordis.yml
+++ b/apps/cli/config/tui.cordis.yml
@@ -40,8 +40,6 @@
 # resolution materializes request defaults before the request header is logged.
 - id: llm-deepseek
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
     thinking: enabled
     reasoningEffort: max
 
diff --git a/apps/cli/config/web.cordis.yml b/apps/cli/config/web.cordis.yml
index efd2f93b2a..7dc72708c3 100644
--- a/apps/cli/config/web.cordis.yml
+++ b/apps/cli/config/web.cordis.yml
@@ -36,11 +36,6 @@
     # once the web UI owns the choice per session.
     mode: !!js process.env.DSH_TOOLS_MODE
 
-- id: llm-deepseek
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
-
 # ── web-only host rows, the transport layer, and the browser roster ─────────
 
 # `dshClient` rows are the browser roster the modules node half scans into
diff --git a/apps/cli/package.json b/apps/cli/package.json
index 8c482ac3e2..7d67e704b9 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -54,6 +54,7 @@
     "@deepseek-ai/dsh-compact-basic": "workspace:^",
     "@deepseek-ai/dsh-compact-tool-result-prune": "workspace:^",
     "@deepseek-ai/dsh-credentials-local": "workspace:^",
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-frontend": "workspace:^",
     "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-fs-policy": "workspace:^",
@@ -74,9 +75,9 @@
     "@deepseek-ai/dsh-paths": "workspace:^",
     "@deepseek-ai/dsh-permission": "workspace:^",
     "@deepseek-ai/dsh-plan-mode": "workspace:^",
-    "@deepseek-ai/dsh-repeat-tool-guard": "workspace:^",
     "@deepseek-ai/dsh-pty": "workspace:^",
     "@deepseek-ai/dsh-pty-local": "workspace:^",
+    "@deepseek-ai/dsh-repeat-tool-guard": "workspace:^",
     "@deepseek-ai/dsh-repository-plugin": "workspace:^",
     "@deepseek-ai/dsh-sandbox-local": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
diff --git a/apps/cli/src/app-cli-entry.ts b/apps/cli/src/app-cli-entry.ts
index 95776484d0..6b072e8aeb 100644
--- a/apps/cli/src/app-cli-entry.ts
+++ b/apps/cli/src/app-cli-entry.ts
@@ -14,6 +14,7 @@ import { createRequire } from 'node:module'
 import { networkInterfaces } from 'node:os'
 import { resolve } from 'node:path'
 import { Context } from 'cordis'
+import { DSH_ENVIRONMENT_KEY, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import yaml from 'js-yaml'
 import { boot, installFailLoud, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
@@ -102,6 +103,8 @@ const includeYamlSchema = yaml.JSON_SCHEMA.extend(jsExprType)
 
 /** Constructor facts for one dsh invocation over the shared composition (argv already parsed by the surface bin). */
 export interface AppCLIEntryOptions {
+  /** This run's frozen environment, provided to the tree before any config entry mounts. */
+  environment: EnvironmentSnapshot
   /** Absolute path of the shared base config the Loader includes. */
   configPath: string
   /**
@@ -255,6 +258,9 @@ export class AppCLIEntry {
         ...this.patches,
       ]
     this.ctx = await boot('dsh', resolve(this.bootConfigPath()), patches, async (ctx) => {
+      // Before any config-tree entry mounts, so a plugin that resolves a
+      // user-facing value at construction already sees this run's layers.
+      ctx.provide(DSH_ENVIRONMENT_KEY, this.options.environment)
       await this.options.prepare?.(ctx)
       if (this.options.dev) await ctx.loader.create({ name: '@deepseek-ai/dsh-client-hmr' })
     })
diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts
index bdef3205b9..ae00d6b168 100644
--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -24,24 +24,27 @@ function readVersion(): string {
   return typeof manifest.version === 'string' ? manifest.version : '0.0.0'
 }
 
-loadLayeredEnv('dsh')
+const environment = loadLayeredEnv('dsh')
 // The env opt-in is read at the process boundary; `1` is the documented value.
 const invocation = parseDshArgs(process.argv.slice(2), readVersion(), process.env.DSH_EXPERIMENTAL === '1')
 
 switch (invocation.mode) {
   case 'web': {
     const { runWeb } = await import('./web.ts')
-    await runWeb(invocation.host, invocation.port, invocation.dev, invocation.workspaceRoot, invocation.trustedHosts, invocation.config)
+    await runWeb(
+      environment, invocation.host, invocation.port, invocation.dev,
+      invocation.workspaceRoot, invocation.trustedHosts, invocation.config,
+    )
     break
   }
   case 'headless': {
     const { runHeadless } = await import('./headless.ts')
-    await runHeadless(invocation.prompt, invocation.config, invocation.configReplace)
+    await runHeadless(environment, invocation.prompt, invocation.config, invocation.configReplace)
     break
   }
   case 'tui': {
     const { runTui } = await import('./tui.ts')
-    await runTui(invocation.config, invocation.resume, undefined, undefined, invocation.configReplace)
+    await runTui(environment, invocation.config, invocation.resume, undefined, undefined, invocation.configReplace)
     break
   }
   case 'dump-config': {
@@ -51,12 +54,12 @@ switch (invocation.mode) {
   }
   case 'meta': {
     const { runTui, SOURCE_ROOT } = await import('./tui.ts')
-    await runTui(invocation.config, undefined, SOURCE_ROOT, undefined, invocation.configReplace)
+    await runTui(environment, invocation.config, undefined, SOURCE_ROOT, undefined, invocation.configReplace)
     break
   }
   case 'upgrade': {
     const { runTui } = await import('./tui.ts')
-    await runTui(invocation.config, undefined, undefined, `dsh-${invocation.mode}`, invocation.configReplace)
+    await runTui(environment, invocation.config, undefined, undefined, `dsh-${invocation.mode}`, invocation.configReplace)
     break
   }
   default:
diff --git a/apps/cli/src/headless.ts b/apps/cli/src/headless.ts
index 5864604e05..098992f181 100644
--- a/apps/cli/src/headless.ts
+++ b/apps/cli/src/headless.ts
@@ -10,6 +10,7 @@
 
 import { fileURLToPath } from 'node:url'
 import { resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import type { EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import { InProcessApiClient, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
 import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
@@ -71,15 +72,19 @@ async function consumeUntilTurnEnd(frames: AsyncIterable<RpcRequest<MuxFrame>>,
  * Run one headless turn for `task` and exit (completed → 0, else 1). The task
  * is the non-empty prompt the argument adapter parsed from `-p`/`--prompt`
  * (the adapter rejects an empty task, so no guard is needed here).
+ * @param environment - this run's frozen environment snapshot.
  * @param task - the prompt text for the single turn.
  * @param config - a `--config` overlay applied over the shipped composition, or `undefined`.
  * @param configReplace - a `--config-replace` tree booted instead of the
  * shipped composition, or `undefined`. It must mount a webserver row: this
  * surface reaches its own agent over the same HTTP gateway the browser uses.
  */
-export async function runHeadless(task: string, config?: string, configReplace?: string): Promise<void> {
+export async function runHeadless(
+  environment: EnvironmentSnapshot, task: string, config?: string, configReplace?: string,
+): Promise<void> {
   // A missing DEEPSEEK_API_KEY throws here (plugin load is fail-loud, uncaught by design).
   const entry = new AppCLIEntry({
+    environment,
     configPath: fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url)),
     overlayPath: fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url)),
     ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },
diff --git a/apps/cli/src/tui.ts b/apps/cli/src/tui.ts
index 20981dc068..6d36b0faa8 100644
--- a/apps/cli/src/tui.ts
+++ b/apps/cli/src/tui.ts
@@ -29,6 +29,7 @@ import {
   resolveConfigPath,
 } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { DSH_ENVIRONMENT_KEY, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { configHasTelemetryRow, resolveTelemetryPatch } from './app-cli-entry.ts'
@@ -78,6 +79,8 @@ export const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
    the CLI PTY smoke drives this path end to end, --config overlay included */
 /**
  * Run the interactive TUI from the invoking directory.
+ * @param environment - this run's frozen environment snapshot, provided to the
+ * tree before any config entry mounts.
  * @param config - an overlay patch list applied over the shared base and the
  * TUI overlay, or `undefined` for the shipped composition alone; already
  * parsed from `--config`.
@@ -97,6 +100,7 @@ export const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
  * already parsed from `--config-replace`.
  */
 export async function runTui(
+  environment: EnvironmentSnapshot,
   config: string | undefined,
   resumeSessionId: string | undefined,
   workspace?: string,
@@ -225,6 +229,7 @@ export async function runTui(
       // Runs after the Loader installs and before any config-tree entry mounts,
       // so the fail-loud release hook can reach the tree for the whole window in
       // which an entry may reject.
+      hostCtx.provide(DSH_ENVIRONMENT_KEY, environment)
       app.current = hostCtx
       // The launcher owns session identity and the exit line: a config-mounted
       // app bundle reads both from these slots, so no cordis.yml key can drop
diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts
index a3dc446706..fcab06f54b 100644
--- a/apps/cli/src/web.ts
+++ b/apps/cli/src/web.ts
@@ -12,6 +12,7 @@ import { addHarnessSourceSection, resolveConfigPath } from '@deepseek-ai/dsh-app
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tool-bash'
+import type { EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import { AppCLIEntry } from './app-cli-entry.ts'
 
 // The shared core every `dsh` surface mounts, plus this surface's overlay over it.
@@ -85,6 +86,7 @@ export function prepareWebRuntimeContext(ctx: Context, sourceRoot: string, mode:
 /**
  * Serve the browser UI from the shipped config tree. `host`/`port` are passed
  * through only when the flag was given; absent, the shipped Web overlay value stands.
+ * @param environment - this run's frozen environment snapshot.
  * @param host - the bind host, or `undefined` to keep the config default.
  * @param port - the listen port (`0` requests an OS-assigned port), or `undefined` to keep the config default.
  * @param dev - mount the client HMR receiver; `pnpm run dev:web` separately rebuilds watched plugin bundles.
@@ -95,6 +97,7 @@ export function prepareWebRuntimeContext(ctx: Context, sourceRoot: string, mode:
  * personal overlay; already parsed from `--config`.
  */
 export async function runWeb(
+  environment: EnvironmentSnapshot,
   host: string | undefined,
   port: number | undefined,
   dev: boolean,
@@ -104,6 +107,7 @@ export async function runWeb(
 ): Promise<void> {
   const mode: WebMode = dev ? 'development' : 'production'
   const entry = new AppCLIEntry({
+    environment,
     configPath: BASE_CONFIG,
     overlayPath: WEB_OVERLAY,
     ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },
diff --git a/apps/cli/tests/tui-keyless-smoke.e2e.ts b/apps/cli/tests/tui-keyless-smoke.e2e.ts
index 2894d0a1ca..94366f4c61 100644
--- a/apps/cli/tests/tui-keyless-smoke.e2e.ts
+++ b/apps/cli/tests/tui-keyless-smoke.e2e.ts
@@ -672,9 +672,9 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     // layering underneath it. The named file patches the `tui` row — a row the
     // SURFACE OVERLAY inserted, not one the base declares — proving a later
     // patch list reaches a row an earlier one inserted. The `!!js` expression
-    // renders both halves of the layering in one line: `DSH_LAYER_WELCOME` is
+    // renders both halves of the layering in one line: `OVERLAY_LAYER_WELCOME` is
     // set by BOTH .env files and must render the project value, while
-    // `DSH_USER_ONLY` exists only in the harness home's .env and must still
+    // `OVERLAY_USER_ONLY` exists only in the harness home's .env and must still
     // arrive. Credentials are not part of this: they live in
     // `.credentials.yaml`, which is never hoisted into `process.env`.
     const output = await smoke({
@@ -683,17 +683,17 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
       binScript: dshBinScript,
       configArgs: ['--config', '.dsh/config.yaml'],
       prepare: seedWorkspace({
-        workspace: { '.env': 'DSH_LAYER_WELCOME=PROJECT WINS.\n' },
+        workspace: { '.env': 'OVERLAY_LAYER_WELCOME=PROJECT WINS.\n' },
         harnessHome: {
-          '.env': 'DSH_LAYER_WELCOME=USER LAYER LOST.\nDSH_USER_ONLY=USER LAYER LOADED.\n',
+          '.env': 'OVERLAY_LAYER_WELCOME=USER LAYER LOST.\nOVERLAY_USER_ONLY=USER LAYER LOADED.\n',
           'config.yaml': [
             '- id: workspace-context',
             '  disabled: true',
             '- id: tui',
             '  config:',
             "    sessionId: !!js configuredAgentIdentities?.main?.id ?? 'main'",
-            '    welcome: !!js "(process.env.DSH_LAYER_WELCOME ?? \'PROJECT LAYER MISSING.\')'
-            + ' + \' \' + (process.env.DSH_USER_ONLY ?? \'USER LAYER MISSING.\')"',
+            '    welcome: !!js "(process.env.OVERLAY_LAYER_WELCOME ?? \'PROJECT LAYER MISSING.\')'
+            + ' + \' \' + (process.env.OVERLAY_USER_ONLY ?? \'USER LAYER MISSING.\')"',
             '',
           ].join('\n'),
         },
diff --git a/apps/cli/tsconfig.json b/apps/cli/tsconfig.json
index 2f995abf87..77da8d2bff 100644
--- a/apps/cli/tsconfig.json
+++ b/apps/cli/tsconfig.json
@@ -29,6 +29,9 @@
     {
       "path": "../../packages/ui/tui"
     },
+    {
+      "path": "../../packages/util/environment"
+    },
     {
       "path": "../../packages/util/paths"
     },
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index ab0ca22024..44888f182a 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -423,7 +423,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/credentials/credentials-local/src/index.ts:35`](../packages/credentials/credentials-local/src/index.ts)
+Source: [`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-fs-local`
 
@@ -632,7 +632,7 @@ export interface Config {
   apiKey?: string
   /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
   apiKeyEnv?: string
-  /** Endpoint base; falls back to $DEEPSEEK_BASE_URL, then the public API. */
+  /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */
   baseURL?: string
   /** Deployment thinking policy; `disabled` limits every conversation request to `off`. */
   thinking?: 'enabled' | 'disabled'
@@ -665,7 +665,7 @@ export interface DeepSeekCatalogModel {
 
 Depends on: [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
 
-Source: [`packages/llm/llm-deepseek/src/index.ts:60`](../packages/llm/llm-deepseek/src/index.ts)
+Source: [`packages/llm/llm-deepseek/src/index.ts:61`](../packages/llm/llm-deepseek/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-pi-ai`
 
@@ -2229,7 +2229,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-deepseek/src/index.ts:43`](../packages/web/web-search-deepseek/src/index.ts)
+Source: [`packages/web/web-search-deepseek/src/index.ts:44`](../packages/web/web-search-deepseek/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-search-exa`
 
@@ -2251,7 +2251,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-exa/src/index.ts:37`](../packages/web/web-search-exa/src/index.ts)
+Source: [`packages/web/web-search-exa/src/index.ts:38`](../packages/web/web-search-exa/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-search-perplexity`
 
@@ -2273,7 +2273,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-perplexity/src/index.ts:31`](../packages/web/web-search-perplexity/src/index.ts)
+Source: [`packages/web/web-search-perplexity/src/index.ts:32`](../packages/web/web-search-perplexity/src/index.ts)
 
 ## `@deepseek-ai/dsh-workflow-workerthread`
 
@@ -2417,6 +2417,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-client-ui-slots` ([`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts))
 - `@deepseek-ai/dsh-client-web` ([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts))
 - `@deepseek-ai/dsh-client-web-react` ([`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts))
+- `@deepseek-ai/dsh-environment` ([`packages/util/environment/src/index.ts`](../packages/util/environment/src/index.ts))
 - `@deepseek-ai/dsh-helper` ([`packages/sdk/helper/src/index.ts`](../packages/sdk/helper/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
 - `@deepseek-ai/dsh-jsonrpc-demo` ([`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts))
diff --git a/examples/acp-agent/cordis.yml b/examples/acp-agent/cordis.yml
index 6edcee5cd8..8aaf690002 100644
--- a/examples/acp-agent/cordis.yml
+++ b/examples/acp-agent/cordis.yml
@@ -9,8 +9,6 @@
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
     thinking: enabled
     reasoningEffort: max
     models:
diff --git a/examples/acp-agent/retry.cordis.yml b/examples/acp-agent/retry.cordis.yml
index 589120c080..087faa271d 100644
--- a/examples/acp-agent/retry.cordis.yml
+++ b/examples/acp-agent/retry.cordis.yml
@@ -13,8 +13,6 @@
       - id: llm-deepseek
         name: '@deepseek-ai/dsh-llm-deepseek'
         config:
-          apiKey: !!js process.env.DEEPSEEK_API_KEY
-          baseURL: !!js process.env.DEEPSEEK_BASE_URL
           thinking: enabled
           reasoningEffort: max
           retryPolicy:
diff --git a/examples/jsonrpc-agent/cordis.yml b/examples/jsonrpc-agent/cordis.yml
index 9806413725..9e9d908593 100644
--- a/examples/jsonrpc-agent/cordis.yml
+++ b/examples/jsonrpc-agent/cordis.yml
@@ -12,8 +12,6 @@
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
     thinking: enabled
     reasoningEffort: max
 
diff --git a/examples/jsonrpc-agent/persistent-tools.cordis.yml b/examples/jsonrpc-agent/persistent-tools.cordis.yml
index b5ae81b100..6f42441ca7 100644
--- a/examples/jsonrpc-agent/persistent-tools.cordis.yml
+++ b/examples/jsonrpc-agent/persistent-tools.cordis.yml
@@ -8,8 +8,6 @@
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
 
 - id: sandbox
   name: '@deepseek-ai/dsh-sandbox-local'
diff --git a/package.json b/package.json
index c1013c23c6..3abd24ca1a 100644
--- a/package.json
+++ b/package.json
@@ -17,101 +17,102 @@
     "build": "npm run build:lib && npm run build:web",
     "build:lib": "tsc -b && tsdown",
     "build:web": "pnpm --filter @deepseek-ai/dsh-frontend run build",
-    "clean": "tsx scripts/clean.ts",
     "change-scope": "tsx scripts/change-scope.ts",
-    "typecheck": "tsc -b",
-    "lint": "tsx scripts/run-oxlint.ts .",
-    "lint:fix": "eslint --config eslint.format.config.mjs --fix . && tsx scripts/run-oxlint.ts . --fix",
-    "duplication": "jscpd --config .jscpd.json packages scripts",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "test:snapshot": "vitest run --config vitest.snapshot.config.ts",
-    "test:snapshot:record": "DSH_SNAPSHOT=record vitest run --config vitest.snapshot.config.ts --update",
-    "test:snapshot:refresh": "DSH_SNAPSHOT=refresh vitest run --config vitest.snapshot.config.ts",
-    "migrate:packed-session-fixtures": "tsx scripts/migrate-packed-session-fixtures.ts",
-    "test:web": "npm run build && npm run test:web:built",
-    "test:web:refresh": "npm run build && DSH_SNAPSHOT=refresh vitest run --config vitest.web.config.ts",
-    "test:web:built": "vitest run --config vitest.web.config.ts",
-    "test:gui": "vitest run packages/client packages/host",
     "check:all": "tsx scripts/run-gates.ts check-all",
     "check:ci": "tsx scripts/run-gates.ts ci-primary",
-    "check:ci:linux-primary": "tsx scripts/run-gates.ts ci-linux-primary",
-    "check:ci:static": "tsx scripts/run-gates.ts ci-static",
-    "check:ci:lint": "tsx scripts/run-gates.ts ci-lint",
-    "check:ci:coverage": "tsx scripts/run-gates.ts ci-coverage",
-    "check:ci:snapshot": "tsx scripts/run-gates.ts ci-snapshot",
     "check:ci:artifacts": "tsx scripts/run-gates.ts ci-artifacts",
     "check:ci:consumers": "tsx scripts/run-gates.ts ci-consumers",
+    "check:ci:coverage": "tsx scripts/run-gates.ts ci-coverage",
+    "check:ci:lint": "tsx scripts/run-gates.ts ci-lint",
+    "check:ci:linux-primary": "tsx scripts/run-gates.ts ci-linux-primary",
+    "check:ci:snapshot": "tsx scripts/run-gates.ts ci-snapshot",
+    "check:ci:static": "tsx scripts/run-gates.ts ci-static",
     "check:ci:windows-blocking": "tsx scripts/run-gates.ts ci-windows-blocking",
     "check:ci:windows-complete": "tsx scripts/run-gates.ts ci-windows-complete",
     "check:ci:windows-observational": "tsx scripts/run-gates.ts ci-windows-observational",
-    "check:windows-wine": "bash scripts/wine-windows-gates.sh",
     "check:node-compat": "tsx scripts/run-gates.ts node-compat",
-    "knip": "knip --treat-config-hints-as-errors",
-    "publint": "tsx scripts/publint-all.ts",
+    "check:windows-wine": "bash scripts/wine-windows-gates.sh",
+    "clean": "tsx scripts/clean.ts",
+    "constraints": "tsx scripts/check-workspace-constraints.ts",
+    "demo:acp": "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",
+    "demo:code-mode": "node scripts/demo-code-mode.mjs",
+    "demo:cordis": "node scripts/demo-cordis.mjs",
+    "demo:headless": "node --import tsx packages/examples/cli-demo/src/bin.ts --config examples/headless-agent/cordis.yml",
+    "demo:tui": "node --import tsx/esm apps/cli/src/bin.ts",
+    "demo:web": "npm run build && node --import tsx/esm apps/cli/src/bin.ts web",
+    "dev:web": "tsx scripts/dev-web.ts --poll",
+    "doc-sync": "tsx scripts/run-gates.ts doc-sync",
     "doc-typecheck": "tsx scripts/doc-typecheck.ts",
-    "verify-md-wrap": "tsx scripts/verify-md-wrap.ts",
-    "verify-md-links": "tsx scripts/verify-md-links.ts",
-    "verify-doc-refs": "tsx scripts/verify-doc-refs.ts",
-    "verify-package-paths": "tsx scripts/verify-package-paths.ts",
-    "verify-package-invariants": "tsx scripts/verify-package-invariants.ts",
-    "verify-built-package-invariants": "node scripts/verify-built-package-invariants.mjs",
-    "verify-package-readme-model-experience": "tsx scripts/verify-package-readme-model-experience.ts",
-    "verify-mermaid": "tsx scripts/verify-mermaid.ts",
+    "docs:build": "pnpm --filter @deepseek-ai/website run build",
+    "docs:build:mpa": "pnpm --filter @deepseek-ai/website exec vitepress build . --mpa",
+    "docs:check": "pnpm exec vitest run scripts/project-doc-site.spec.ts && pnpm run docs:build",
+    "docs:dev": "pnpm --filter @deepseek-ai/website run dev",
+    "docs:preview": "pnpm --filter @deepseek-ai/website run preview",
+    "dsh": "node --import tsx/esm apps/cli/src/bin.ts",
+    "duplication": "jscpd --config .jscpd.json packages scripts",
+    "gen-config-catalog": "tsx scripts/gen-config-catalog.ts",
+    "gen-cordis-api": "tsx scripts/gen-cordis-api.ts",
+    "gen-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts",
+    "gen-doc-graphs": "tsx scripts/gen-doc-graphs.ts",
+    "gen-module-graph": "tsx scripts/gen-module-graph.ts",
+    "gen-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts",
+    "gen-scoped-events": "tsx scripts/gen-scoped-events.ts",
+    "gen-third-party-notices": "tsx scripts/gen-third-party-notices.ts",
+    "gen-tool-catalog": "tsx scripts/gen-tool-catalog.ts",
+    "gen-translation-brief": "tsx scripts/gen-translation-brief.ts",
+    "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-package-invariants && pnpm run verify-built-package-invariants && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure && pnpm run verify-vendored-links",
+    "knip": "knip --treat-config-hints-as-errors",
+    "lint": "tsx scripts/run-oxlint.ts .",
+    "lint:fix": "eslint --config eslint.format.config.mjs --fix . && tsx scripts/run-oxlint.ts . --fix",
+    "migrate:packed-session-fixtures": "tsx scripts/migrate-packed-session-fixtures.ts",
+    "mock:llm": "node --import tsx packages/support/llm-mock-server/src/bin.ts",
+    "postinstall": "node scripts/install-lefthook.mjs",
+    "publint": "tsx scripts/publint-all.ts",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:gui": "vitest run packages/client packages/host",
+    "test:snapshot": "vitest run --config vitest.snapshot.config.ts",
+    "test:snapshot:record": "DSH_SNAPSHOT=record vitest run --config vitest.snapshot.config.ts --update",
+    "test:snapshot:refresh": "DSH_SNAPSHOT=refresh vitest run --config vitest.snapshot.config.ts",
+    "test:web": "npm run build && npm run test:web:built",
+    "test:web:built": "vitest run --config vitest.web.config.ts",
+    "test:web:refresh": "npm run build && DSH_SNAPSHOT=refresh vitest run --config vitest.web.config.ts",
+    "typecheck": "tsc -b",
     "verify-agent-note-classification": "tsx scripts/verify-agent-note-classification.ts",
     "verify-agent-note-format": "tsx scripts/verify-agent-note-format.ts",
     "verify-archived-agent-notes": "tsx scripts/verify-archived-agent-notes.ts",
-    "verify-type-equiv": "tsx scripts/verify-type-equiv.ts",
-    "verify-translation-prompt": "tsx scripts/verify-translation-prompt.ts",
-    "verify-translation-pairing": "tsx scripts/verify-translation-pairing.ts",
-    "gen-translation-brief": "tsx scripts/gen-translation-brief.ts",
-    "verify-doc-budgets": "tsx scripts/verify-doc-budgets.ts",
-    "docs:dev": "pnpm --filter @deepseek-ai/website run dev",
-    "docs:build": "pnpm --filter @deepseek-ai/website run build",
-    "docs:build:mpa": "pnpm --filter @deepseek-ai/website exec vitepress build . --mpa",
-    "docs:preview": "pnpm --filter @deepseek-ai/website run preview",
-    "docs:check": "pnpm exec vitest run scripts/project-doc-site.spec.ts && pnpm run docs:build",
-    "website:dev": "pnpm run docs:dev",
-    "website:build": "pnpm run docs:build",
-    "verify-package-readme-limitations": "tsx scripts/verify-package-readme-limitations.ts",
-    "verify-node-next-types": "tsx scripts/verify-node-next-types.ts",
-    "verify-runtime-closure": "tsx scripts/verify-runtime-closure.ts",
-    "verify-vendored-links": "tsx scripts/verify-vendored-links.ts",
-    "verify-cordis-config": "tsx scripts/verify-cordis-config.ts",
+    "verify-built-package-invariants": "node scripts/verify-built-package-invariants.mjs",
     "verify-client-domain-graph": "tsx scripts/verify-client-domain-graph.ts",
-    "gen-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts",
-    "verify-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts --check",
-    "gen-cordis-api": "tsx scripts/gen-cordis-api.ts",
-    "verify-cordis-api": "tsx scripts/gen-cordis-api.ts --check",
-    "verify-export-jsdoc": "tsx scripts/verify-export-jsdoc.ts",
-    "gen-tool-catalog": "tsx scripts/gen-tool-catalog.ts",
-    "verify-tool-catalog": "tsx scripts/gen-tool-catalog.ts --check",
-    "gen-config-catalog": "tsx scripts/gen-config-catalog.ts",
     "verify-config-catalog": "tsx scripts/gen-config-catalog.ts --check",
-    "gen-doc-graphs": "tsx scripts/gen-doc-graphs.ts",
+    "verify-config-source-ownership": "tsx scripts/verify-config-source-ownership.ts",
+    "verify-cordis-api": "tsx scripts/gen-cordis-api.ts --check",
+    "verify-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts --check",
+    "verify-cordis-config": "tsx scripts/verify-cordis-config.ts",
+    "verify-doc-budgets": "tsx scripts/verify-doc-budgets.ts",
     "verify-doc-graphs": "tsx scripts/gen-doc-graphs.ts --check",
-    "gen-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts",
-    "verify-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts --check",
-    "gen-third-party-notices": "tsx scripts/gen-third-party-notices.ts",
-    "verify-third-party-notices": "tsx scripts/gen-third-party-notices.ts --check",
-    "gen-module-graph": "tsx scripts/gen-module-graph.ts",
-    "gen-scoped-events": "tsx scripts/gen-scoped-events.ts",
-    "verify-scoped-events": "tsx scripts/gen-scoped-events.ts --check",
+    "verify-doc-refs": "tsx scripts/verify-doc-refs.ts",
+    "verify-export-jsdoc": "tsx scripts/verify-export-jsdoc.ts",
+    "verify-md-links": "tsx scripts/verify-md-links.ts",
+    "verify-md-wrap": "tsx scripts/verify-md-wrap.ts",
+    "verify-mermaid": "tsx scripts/verify-mermaid.ts",
     "verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
-    "constraints": "tsx scripts/check-workspace-constraints.ts",
-    "doc-sync": "tsx scripts/run-gates.ts doc-sync",
-    "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-package-invariants && pnpm run verify-built-package-invariants && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure && pnpm run verify-vendored-links",
-    "dsh": "node --import tsx/esm apps/cli/src/bin.ts",
-    "demo:headless": "node --import tsx packages/examples/cli-demo/src/bin.ts --config examples/headless-agent/cordis.yml",
-    "demo:tui": "node --import tsx/esm apps/cli/src/bin.ts",
-    "demo:code-mode": "node scripts/demo-code-mode.mjs",
-    "demo:cordis": "node scripts/demo-cordis.mjs",
-    "demo:acp": "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",
-    "demo:web": "npm run build && node --import tsx/esm apps/cli/src/bin.ts web",
-    "mock:llm": "node --import tsx packages/support/llm-mock-server/src/bin.ts",
-    "dev:web": "tsx scripts/dev-web.ts --poll",
-    "postinstall": "node scripts/install-lefthook.mjs"
+    "verify-node-next-types": "tsx scripts/verify-node-next-types.ts",
+    "verify-package-invariants": "tsx scripts/verify-package-invariants.ts",
+    "verify-package-paths": "tsx scripts/verify-package-paths.ts",
+    "verify-package-readme-limitations": "tsx scripts/verify-package-readme-limitations.ts",
+    "verify-package-readme-model-experience": "tsx scripts/verify-package-readme-model-experience.ts",
+    "verify-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts --check",
+    "verify-runtime-closure": "tsx scripts/verify-runtime-closure.ts",
+    "verify-scoped-events": "tsx scripts/gen-scoped-events.ts --check",
+    "verify-third-party-notices": "tsx scripts/gen-third-party-notices.ts --check",
+    "verify-tool-catalog": "tsx scripts/gen-tool-catalog.ts --check",
+    "verify-translation-pairing": "tsx scripts/verify-translation-pairing.ts",
+    "verify-translation-prompt": "tsx scripts/verify-translation-prompt.ts",
+    "verify-type-equiv": "tsx scripts/verify-type-equiv.ts",
+    "verify-vendored-links": "tsx scripts/verify-vendored-links.ts",
+    "website:build": "pnpm run docs:build",
+    "website:dev": "pnpm run docs:dev"
   },
   "devDependencies": {
     "@agentclientprotocol/sdk": "0.25.1",
diff --git a/packages/credentials/credentials-local/package.json b/packages/credentials/credentials-local/package.json
index 644904676a..132db124b2 100644
--- a/packages/credentials/credentials-local/package.json
+++ b/packages/credentials/credentials-local/package.json
@@ -29,6 +29,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-atomic-write": "^0.0.1",
     "@deepseek-ai/dsh-credentials": "^0.0.1",
+    "@deepseek-ai/dsh-environment": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-paths": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
@@ -41,6 +42,7 @@
   "devDependencies": {
     "@deepseek-ai/dsh-atomic-write": "workspace:^",
     "@deepseek-ai/dsh-credentials": "workspace:^",
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-paths": "workspace:^",
     "cordis": "^4.0.0-rc.7"
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index bc1214d11b..6d5db0776f 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -1,12 +1,29 @@
 /**
- * File-backed credentials provider layering the live process environment over
- * a `$DSH_HOME/.credentials.yaml` document. The environment is authoritative
- * and read-only (a launch-time override must win, and must be visibly
- * read-only rather than silently shadow writes); the file is the
- * provider-managed writable source: every write re-reads the document under a
- * cross-process writer lock before patching only its own key — comments and
- * the formatting of every untouched entry survive — external edits
- * hot-publish through the seam, and each reload replaces the snapshot
+ * File-backed credentials provider over `$DSH_HOME/.credentials.yaml`, layered
+ * against the environment by how much each layer is trusted:
+ *
+ * ```text
+ * inherited process environment  (read-only, wins)
+ * > $DSH_HOME/.credentials.yaml  (provider-managed, writable)
+ * > $DSH_HOME/.env               (read-only fallback)
+ * ```
+ *
+ * The inherited environment wins because `DEEPSEEK_API_KEY=… dsh`, a CI
+ * secret, or a container `-e` is this run's explicit intent; it cannot be
+ * edited from inside, so it must be *visibly* read-only rather than silently
+ * shadow writes. Everything below it loses to the managed store, so a key the
+ * web page or TUI writes takes effect immediately even when an older key sits
+ * in the user's `.env`.
+ *
+ * The invoking directory's `.env` supplies no credential at all. A project
+ * directory can be written by the model, and a substituted key would send
+ * every request — prompts included — through an account someone else reads;
+ * that decision belongs to the launching shell, not to a discovered file.
+ *
+ * The file is the provider-managed writable source: every write re-reads the
+ * document under a cross-process writer lock before patching only its own key
+ * — comments and the formatting of every untouched entry survive — external
+ * edits hot-publish through the seam, and each reload replaces the snapshot
  * wholesale so a deleted entry never lingers in memory.
  *
  * The document holds nothing but credentials, which is why it is a strict
@@ -25,8 +42,10 @@ import { dirname, join, resolve } from 'node:path'
 import { Document, parseDocument } from 'yaml'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { environmentOf } from '@deepseek-ai/dsh-environment'
 import { Credentials, credentialRef } from '@deepseek-ai/dsh-credentials'
 import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/dsh-credentials'
+import type { EnvironmentEntry } from '@deepseek-ai/dsh-environment'
 
 /** Basename of the credentials document inside the harness home. */
 export const CREDENTIALS_FILENAME = '.credentials.yaml'
@@ -169,6 +188,18 @@ export class CredentialsLocal extends Credentials {
     this.spec = resolveSpec(config)
   }
 
+  /** The inherited-environment value for a reference, or `undefined` when empty or unset. */
+  private inherited(ref: CredentialRef): string | undefined {
+    const entry = environmentOf(this.ctx).getFrom(ref, ['process'])
+    return entry !== undefined && entry.value.length > 0 ? entry.value : undefined
+  }
+
+  /** The user `.env` fallback for a reference — below the managed store, never above it. */
+  private userEnvFallback(ref: CredentialRef): EnvironmentEntry | undefined {
+    const entry = environmentOf(this.ctx).getFrom(ref, ['user-env'])
+    return entry !== undefined && entry.value.length > 0 ? entry : undefined
+  }
+
   async* [Service.init](): AsyncGenerator<() => Promise<void> | void, void, void> {
     yield async () => {
       // Drain: refuse new operations, then settle the queued ones so disposal
@@ -214,20 +245,27 @@ export class CredentialsLocal extends Credentials {
   }
 
   override resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined> {
-    const env = process.env[ref]
-    if (env !== undefined && env.length > 0) return Promise.resolve({ value: env, source: 'env' })
+    const inherited = this.inherited(ref)
+    if (inherited !== undefined) return Promise.resolve({ value: inherited, source: 'env' })
     const stored = this.values.get(ref)
     if (stored !== undefined) return Promise.resolve({ value: stored, source: 'file' })
+    const fallback = this.userEnvFallback(ref)
+    if (fallback !== undefined) return Promise.resolve({ value: fallback.value, source: 'user-env' })
     return Promise.resolve(undefined)
   }
 
   override describe(ref: CredentialRef): Promise<CredentialInfo> {
-    const env = process.env[ref]
-    if (env !== undefined && env.length > 0) {
+    // Only the inherited environment is unwritable: it is the one layer this
+    // process cannot edit. A user `.env` value is writable in the sense that
+    // matters — storing a key replaces it as the effective one.
+    if (this.inherited(ref) !== undefined) {
       return Promise.resolve({ configured: true, source: 'env', writable: false })
     }
     const stored = this.values.get(ref)
     if (stored !== undefined) return Promise.resolve({ configured: true, source: 'file', writable: true })
+    if (this.userEnvFallback(ref) !== undefined) {
+      return Promise.resolve({ configured: true, source: 'user-env', writable: true })
+    }
     return Promise.resolve({ configured: false, writable: true })
   }
 
@@ -303,13 +341,16 @@ export class CredentialsLocal extends Credentials {
     })
   }
 
-  /** Reject a write the live environment would shadow into apparent no-effect. */
+  /**
+   * Reject a write the inherited environment would shadow into apparent
+   * no-effect. Only that layer can shadow a write: everything else this
+   * provider resolves ranks below the document being written.
+   */
   private assertUnshadowed(ref: CredentialRef, verb: 'set' | 'unset'): void {
-    const env = process.env[ref]
-    if (env !== undefined && env.length > 0) {
+    if (this.inherited(ref) !== undefined) {
       throw new Error(
-        `credentials-local: "${ref}" is supplied read-only by the process environment, so ${verb} would be`
-        + ' shadowed; unset it in the launching environment (or in a loaded .env) instead',
+        `credentials-local: "${ref}" is supplied read-only by the launching environment, so ${verb} would be`
+        + ' shadowed; unset it in the shell you start dsh from instead',
       )
     }
   }
diff --git a/packages/credentials/credentials-local/tests/local.spec.ts b/packages/credentials/credentials-local/tests/local.spec.ts
index d5ffddc54d..abc3521111 100644
--- a/packages/credentials/credentials-local/tests/local.spec.ts
+++ b/packages/credentials/credentials-local/tests/local.spec.ts
@@ -4,6 +4,7 @@ import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { createEnvironmentSnapshot, DSH_ENVIRONMENT_KEY } from '@deepseek-ai/dsh-environment'
 import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
 import { CredentialsLocal, resolveSpec } from '../src/index.ts'
 
@@ -100,6 +101,74 @@ describe('layering and reads', () => {
   })
 })
 
+describe('layer ladder', () => {
+  // inherited process env > .credentials.yaml > $DSH_HOME/.env, and the
+  // invoking directory's .env supplies no credential at all.
+  async function bootLayered(
+    path: string,
+    layers: Parameters<typeof createEnvironmentSnapshot>[0],
+  ): Promise<Context> {
+    const ctx = new Context()
+    ctx.provide(DSH_ENVIRONMENT_KEY, createEnvironmentSnapshot(layers))
+    const fiber = ctx.plugin(CredentialsLocal, { path, watch: false })
+    cleanups.push(async () => { await fiber.dispose() })
+    await fiber
+    return ctx
+  }
+
+  it('lets the stored value beat the user .env, so a UI write takes effect immediately', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_TEST: stored\n')
+    const ctx = await bootLayered(path, [
+      { source: 'process', values: {} },
+      { source: 'user-env', path: '/home/.dsh/.env', values: { DSH_CRED_TEST: 'older-user-env' } },
+    ])
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'stored', source: 'file' })
+    // The old dead end is gone: a key sitting in the user's .env no longer
+    // makes the stored one unwritable.
+    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: true, source: 'file', writable: true })
+    await expect(ctx.credentials.set(KEY, 'rotated')).resolves.toBeUndefined()
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'rotated', source: 'file' })
+  })
+
+  it('serves the user .env only when nothing is stored', async () => {
+    const dir = await tempDir()
+    const ctx = await bootLayered(join(dir, '.credentials.yaml'), [
+      { source: 'process', values: {} },
+      { source: 'user-env', path: '/home/.dsh/.env', values: { DSH_CRED_TEST: 'from-user-env' } },
+    ])
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'from-user-env', source: 'user-env' })
+    // Writable: storing a key replaces it as the effective one.
+    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: true, source: 'user-env', writable: true })
+  })
+
+  it('ignores the invoking directory .env entirely', async () => {
+    const dir = await tempDir()
+    const ctx = await bootLayered(join(dir, '.credentials.yaml'), [
+      { source: 'process', values: {} },
+      { source: 'project-env', path: '/work/.env', values: { DSH_CRED_TEST: 'from-project' } },
+    ])
+    // A project directory can be written by the model, and a substituted key
+    // would route every request through an account someone else reads.
+    expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
+    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: false, writable: true })
+  })
+
+  it('lets only the inherited environment shadow the store, read-only', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_TEST: stored\n')
+    const ctx = await bootLayered(path, [
+      { source: 'process', values: { DSH_CRED_TEST: 'from-shell' } },
+      { source: 'user-env', path: '/home/.dsh/.env', values: { DSH_CRED_TEST: 'from-user-env' } },
+    ])
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'from-shell', source: 'env' })
+    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: true, source: 'env', writable: false })
+    await expect(ctx.credentials.set(KEY, 'next')).rejects.toThrow(/launching environment/)
+  })
+})
+
 describe('document validation', () => {
   // Every rejection below is a boot failure rather than a skipped entry: this
   // document holds nothing but credentials, so an ignored key would read as
diff --git a/packages/credentials/credentials-local/tsconfig.json b/packages/credentials/credentials-local/tsconfig.json
index 3acfbdeffe..75e6b0aeb0 100644
--- a/packages/credentials/credentials-local/tsconfig.json
+++ b/packages/credentials/credentials-local/tsconfig.json
@@ -20,6 +20,9 @@
     {
       "path": "../../util/atomic-write"
     },
+    {
+      "path": "../../util/environment"
+    },
     {
       "path": "../../util/paths"
     },
diff --git a/packages/llm/llm-deepseek/package.json b/packages/llm/llm-deepseek/package.json
index 2c39e2d920..f9a114d908 100644
--- a/packages/llm/llm-deepseek/package.json
+++ b/packages/llm/llm-deepseek/package.json
@@ -28,6 +28,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-credentials": "^0.0.1",
+    "@deepseek-ai/dsh-environment": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-settings": "^0.0.1",
@@ -40,6 +41,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-credentials": "workspace:^",
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-settings": "workspace:^",
diff --git a/packages/llm/llm-deepseek/src/index.ts b/packages/llm/llm-deepseek/src/index.ts
index 3ecc0bec77..effa080409 100644
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/packages/llm/llm-deepseek/src/index.ts
@@ -16,6 +16,7 @@ import z from 'schemastery'
 import { LlmError, resolveRetryPolicy, RetryPolicySchema } from '@deepseek-ai/dsh-llm'
 import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { environmentOf, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import { deepEqualJson, installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import {
@@ -62,7 +63,7 @@ export interface Config {
   apiKey?: string
   /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
   apiKeyEnv?: string
-  /** Endpoint base; falls back to $DEEPSEEK_BASE_URL, then the public API. */
+  /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */
   baseURL?: string
   /** Deployment thinking policy; `disabled` limits every conversation request to `off`. */
   thinking?: 'enabled' | 'disabled'
@@ -103,6 +104,9 @@ export const Config: z<Config> = z.object({
 /** Public API default; the internal endpoint comes from $DEEPSEEK_BASE_URL. */
 export const PUBLIC_BASE_URL = 'https://api.deepseek.com'
 
+/** Environment variable naming this provider's endpoint, honored only from trusted layers. */
+const BASE_URL_ENV = 'DEEPSEEK_BASE_URL'
+
 /**
  * One resolution's complete request facts. Connection and credential facts
  * are one value on purpose: a snapshot the resolver rejects keeps the whole
@@ -142,9 +146,13 @@ function resolveModels(models: readonly DeepSeekCatalogModel[] | undefined): Dee
  * every default and bound is re-judged here — for the composition entry at
  * load (fail loud) and for each settings snapshot at its first use.
  * @param config - raw plugin config or resolved settings snapshot.
+ * @param environment - this run's environment layers, or `undefined` outside
+ * the product CLI. Only the launching shell and the user's own `.env` may
+ * supply an endpoint: a base URL decides where the resolved API key is sent,
+ * so a file inside the workspace must not be able to redirect it.
  * @returns validated connection facts plus the credential reference.
  */
-export function resolveAdapterOptions(config: Config): ResolvedDeepSeekOptions {
+export function resolveAdapterOptions(config: Config, environment?: EnvironmentSnapshot): ResolvedDeepSeekOptions {
   if (config.thinking === 'disabled'
     && config.reasoningEffort !== undefined
     && config.reasoningEffort !== 'off') {
@@ -169,7 +177,9 @@ export function resolveAdapterOptions(config: Config): ResolvedDeepSeekOptions {
   return {
     ...config.apiKey !== undefined && config.apiKey.length > 0 ? { apiKey: config.apiKey } : {},
     apiKeyEnv: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
-    baseURL: config.baseURL ?? process.env.DEEPSEEK_BASE_URL ?? PUBLIC_BASE_URL,
+    baseURL: config.baseURL
+      ?? environment?.getFrom(BASE_URL_ENV, ['process', 'user-env'])?.value
+      ?? PUBLIC_BASE_URL,
     defaults: {
       thinking: config.thinking,
       reasoningEffort: config.reasoningEffort,
@@ -190,7 +200,7 @@ export function apply(ctx: Context, config: Config): void {
     const raw = current()
     if (raw === lastRaw && lastGood !== undefined) return lastGood
     try {
-      const next = resolveAdapterOptions(raw)
+      const next = resolveAdapterOptions(raw, environmentOf(ctx))
       lastRaw = raw
       lastGood = next
       return next
@@ -217,10 +227,12 @@ export function apply(ctx: Context, config: Config): void {
       const hit = await credentials.resolve(ref)
       if (hit !== undefined) return hit.value
     } else {
-      // Without the seam, keep the historical ambient fallback so a plain
-      // cordis.yml composition works from the environment alone.
-      const ambient = process.env[ref]
-      if (ambient !== undefined && ambient.length > 0) return ambient
+      // Without the seam there is no managed store to rank against, so the
+      // launching environment is the whole credential plane — but only that
+      // layer: a key from a discovered project file would route this request
+      // through an account the launch never chose.
+      const inherited = environmentOf(ctx).getFrom(ref, ['process'])
+      if (inherited !== undefined && inherited.value.length > 0) return inherited.value
     }
     throw new LlmError(
       `llm-deepseek: no API key for provider route "${PROVIDER}"; store ${ref} through the credentials`
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index ec4a271f15..c9db376c8a 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
+import { createEnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import LlmService, { createUserMessage,
   CONTEXT_WINDOW_EXCEEDED_CODE,
   errorChain,
@@ -12,7 +13,7 @@ import LlmService, { createUserMessage,
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
-import { DeepSeekAdapter, resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
+import { DeepSeekAdapter, PUBLIC_BASE_URL, resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
 import { httpErrorCode } from '../src/adapter.ts'
 import { assemble } from './assemble.ts'
 import { closeMockServers, mockServer, textEvents } from './mock-server.ts'
@@ -906,6 +907,25 @@ describe('plugin registration and config', () => {
     expect(server.requests).toHaveLength(1)
   })
 
+
+  it('takes DEEPSEEK_BASE_URL from the launching shell or the user .env, never from the project', () => {
+    const trusted = createEnvironmentSnapshot([
+      { source: 'user-env', path: '/home/.dsh/.env', values: { DEEPSEEK_BASE_URL: 'https://user.example' } },
+    ])
+    expect(resolveAdapterOptions({}, trusted).baseURL).toBe('https://user.example')
+    // A base URL decides where the resolved API key is sent, so a file inside
+    // a model-writable workspace must not be able to redirect it.
+    const project = createEnvironmentSnapshot([
+      { source: 'project-env', path: '/work/.env', values: { DEEPSEEK_BASE_URL: 'https://attacker.example' } },
+    ])
+    expect(resolveAdapterOptions({}, project).baseURL).toBe(PUBLIC_BASE_URL)
+    // An explicitly configured endpoint outranks every environment layer, so a
+    // stale shell value cannot rewrite a deployment's own gateway.
+    const shell = createEnvironmentSnapshot([
+      { source: 'process', values: { DEEPSEEK_BASE_URL: 'https://stale.example' } },
+    ])
+    expect(resolveAdapterOptions({ baseURL: 'https://gateway.internal' }, shell).baseURL).toBe('https://gateway.internal')
+  })
   it('defaults to the public base URL without config or env', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', 'k')
     vi.stubEnv('DEEPSEEK_BASE_URL', undefined)
diff --git a/packages/llm/llm-deepseek/tsconfig.json b/packages/llm/llm-deepseek/tsconfig.json
index ee8a81e73b..0b524a257b 100644
--- a/packages/llm/llm-deepseek/tsconfig.json
+++ b/packages/llm/llm-deepseek/tsconfig.json
@@ -23,6 +23,9 @@
     {
       "path": "../../credentials/credentials"
     },
+    {
+      "path": "../../util/environment"
+    },
     {
       "path": "../../settings/settings"
     },
diff --git a/packages/llm/llm-pi-ai/package.json b/packages/llm/llm-pi-ai/package.json
index 43b97a14f0..5e86ac5b40 100644
--- a/packages/llm/llm-pi-ai/package.json
+++ b/packages/llm/llm-pi-ai/package.json
@@ -28,6 +28,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-credentials": "^0.0.1",
+    "@deepseek-ai/dsh-environment": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-settings": "^0.0.1",
@@ -40,6 +41,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-credentials": "workspace:^",
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index 91cb32a181..862aa2afca 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -29,6 +29,7 @@
  */
 
 import type { Context } from 'cordis'
+import { environmentOf } from '@deepseek-ai/dsh-environment'
 import { getBuiltinProviders } from '@earendil-works/pi-ai/providers/all'
 import { LlmError } from '@deepseek-ai/dsh-llm'
 import type { AdapterRegistrationHandle } from '@deepseek-ai/dsh-llm'
@@ -99,9 +100,9 @@ export function apply(ctx: Context, config: Config): void {
     const credentials = ctx.get('credentials')
     const hit = credentials !== undefined
       ? (await credentials.resolve(ref))?.value
-      // Without the seam, read exactly the named variable so a plain
-      // cordis.yml composition works from the environment alone.
-      : process.env[ref]
+      // Without the seam the launching environment is the whole credential
+      // plane — but only that layer, never a discovered project file.
+      : environmentOf(ctx).getFrom(ref, ['process'])?.value
     if (hit !== undefined && hit.length > 0) return hit
     throw new LlmError(
       `llm-pi-ai: no credential for provider route "${provider}"; its profile resolves ${ref}, which is not`
diff --git a/packages/llm/llm-pi-ai/tsconfig.json b/packages/llm/llm-pi-ai/tsconfig.json
index ee8a81e73b..dd364e493a 100644
--- a/packages/llm/llm-pi-ai/tsconfig.json
+++ b/packages/llm/llm-pi-ai/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../util/environment"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/packages/ui/app-boot/package.json b/packages/ui/app-boot/package.json
index 18a42a27a1..fc4f173263 100644
--- a/packages/ui/app-boot/package.json
+++ b/packages/ui/app-boot/package.json
@@ -27,12 +27,14 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
+    "dotenv": "^17.2.0",
     "js-yaml": "^4.2.0"
   },
   "peerDependencies": {
     "@cordisjs/plugin-hmr": "^1.0.15",
     "@cordisjs/plugin-include": "^1.0.4",
     "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-environment": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-paths": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
@@ -48,6 +50,7 @@
     "@cordisjs/plugin-include": "workspace:^",
     "@cordisjs/plugin-loader": "workspace:^",
     "@cordisjs/plugin-timer": "workspace:^",
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-paths": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
diff --git a/packages/ui/app-boot/src/index.ts b/packages/ui/app-boot/src/index.ts
index 78dff3eca8..0f3cbd6687 100644
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -9,11 +9,13 @@
 import { pathToFileURL } from 'node:url'
 import { readFileSync } from 'node:fs'
 import { basename, dirname, resolve } from 'node:path'
+import { parse as parseDotenv } from 'dotenv'
 import * as yaml from 'js-yaml'
 import { Context, type FiberState } from 'cordis'
 import Loader, { type Entry, type EntryOptions } from '@cordisjs/plugin-loader'
 import Include, { applyEntryPatches, entryListSchema, type PatchOptions } from '@cordisjs/plugin-include'
 import { dshHomePath, resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { createEnvironmentSnapshot, isBootstrapOnly, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import type {} from '@cordisjs/plugin-hmr'
 // Side-effect type import: resolves `ctx.get('systemPrompt')` to the service.
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -66,12 +68,57 @@ export function loadEnv(
 }
 
 /**
- * Load the dsh product CLI's user environment: the invoking directory's `.env`
+ * Parse one directory's `.env` without applying it, rejecting any bootstrap
+ * variable it declares. A discovered file must not decide how this process
+ * launches, where its code and model-visible instructions come from, or how it
+ * reaches the network, so a violation fails the launch BEFORE anything is
+ * materialized — reporting it afterwards would leave the process already
+ * running under the value it refused.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param dir - the directory whose `.env` to read.
+ * @param warn - sink for the one-line unreadable-file diagnostic.
+ * @returns the parsed entries, or `undefined` when the file is absent or unreadable.
+ * @throws when the file declares a name {@link isBootstrapOnly} rejects.
+ */
+function readEnvLayer(
+  binName: string, dir: string, warn: (line: string) => void,
+): { path: string; values: Record<string, string> } | undefined {
+  const path = resolve(dir, '.env')
+  let content: string
+  try {
+    content = readFileSync(path, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') {
+      warn(`${binName}: failed to load .env: ${String(error)}\n`)
+    }
+    // ENOENT (no .env) is fine — rely on the ambient environment.
+    return undefined
+  }
+  const values = parseDotenv(content)
+  for (const name of Object.keys(values)) {
+    if (!isBootstrapOnly(name)) continue
+    throw new Error(
+      `${binName}: ${path} sets "${name}", which only the launching environment may set`
+      + ' (it decides how this process starts, where its code and instructions load from, or how it'
+      + ` reaches the network); export ${name} instead of putting it in a .env file`,
+    )
+  }
+  return { path, values }
+}
+
+/**
+ * Load the dsh product CLI's user environment and return it as a snapshot that
+ * remembers which layer supplied each value: the invoking directory's `.env`
  * over the Harness home's `.env`, both under the inherited process
- * environment. `process.loadEnvFile` never replaces a name that is already
- * set, so loading the project file first and the user file second is what
- * makes the layering `user < project < inherited`; the app-boot tests pin all
- * three layers because that ordering is the whole contract.
+ * environment.
+ *
+ * Each layer is parsed and checked before anything is applied, then applied in
+ * the order that makes the layering `user < project < inherited` —
+ * `process.loadEnvFile` never replaces a name already set. Values do reach
+ * `process.env`, because a user's own `--config` tree and third-party
+ * libraries read it; the returned snapshot is the authority for everything the
+ * harness itself resolves, since `process.env` alone cannot say whether a
+ * value came from the launching shell or from a file inside the workspace.
  *
  * The Harness home is resolved from the inherited environment *before* either
  * file loads, so a project `.env` can never redirect which user document is
@@ -82,17 +129,28 @@ export function loadEnv(
  * These are ordinary environment values with ordinary environment reach. A
  * secret the Harness should own and isolate belongs in the credentials
  * document, which is never materialized here.
- * @param binName - the diagnostic prefix on the warn lines.
+ * @param binName - the diagnostic prefix on the diagnostics.
  * @param cwd - the invoking directory whose `.env` is the project layer.
  * @param warn - sink for the one-line misconfiguration diagnostics.
+ * @returns this run's frozen environment snapshot.
+ * @throws when either file declares a bootstrap-only variable.
  */
 export function loadLayeredEnv(
   binName: string, cwd: string = process.cwd(),
   warn: (line: string) => void = line => void process.stderr.write(line),
-): void {
+): EnvironmentSnapshot {
   const home = resolveDshHome()
-  loadEnv(binName, cwd, warn)
-  loadEnv(binName, home, warn)
+  const inherited = { ...process.env } as Record<string, string>
+  // Parse both layers first: a rejection must not leave one file applied.
+  const project = readEnvLayer(binName, cwd, warn)
+  const user = home === resolve(cwd) ? undefined : readEnvLayer(binName, home, warn)
+  if (project !== undefined) process.loadEnvFile(project.path)
+  if (user !== undefined) process.loadEnvFile(user.path)
+  return createEnvironmentSnapshot([
+    { source: 'process', values: inherited },
+    ...project === undefined ? [] : [{ source: 'project-env' as const, path: project.path, values: project.values }],
+    ...user === undefined ? [] : [{ source: 'user-env' as const, path: user.path, values: user.values }],
+  ])
 }
 
 /**
diff --git a/packages/ui/app-boot/tests/app-boot.spec.ts b/packages/ui/app-boot/tests/app-boot.spec.ts
index ece98a9716..fba1ad1993 100644
--- a/packages/ui/app-boot/tests/app-boot.spec.ts
+++ b/packages/ui/app-boot/tests/app-boot.spec.ts
@@ -87,7 +87,7 @@ describe('loadEnv', () => {
 })
 
 describe('loadLayeredEnv', () => {
-  const NAMES = ['DSH_APP_BOOT_LAYERED_SHARED', 'DSH_APP_BOOT_LAYERED_USER', 'DSH_APP_BOOT_LAYERED_PROJECT'] as const
+  const NAMES = ['APP_BOOT_LAYERED_SHARED', 'APP_BOOT_LAYERED_USER', 'APP_BOOT_LAYERED_PROJECT'] as const
 
   function clear(): void {
     for (const name of NAMES) Reflect.deleteProperty(process.env, name)
@@ -99,18 +99,18 @@ describe('loadLayeredEnv', () => {
     writeFileSync(join(home, '.env'), [
       `${NAMES[0]}=user`,
       `${NAMES[1]}=user-only`,
-      'DSH_APP_BOOT_LAYERED_INHERITED=user-loses',
+      'APP_BOOT_LAYERED_INHERITED=user-loses',
       '',
     ].join('\n'))
     writeFileSync(join(project, '.env'), [
       `${NAMES[0]}=project`,
       `${NAMES[2]}=project-only`,
-      'DSH_APP_BOOT_LAYERED_INHERITED=project-loses',
+      'APP_BOOT_LAYERED_INHERITED=project-loses',
       '',
     ].join('\n'))
     clear()
     vi.stubEnv('DSH_HOME', home)
-    vi.stubEnv('DSH_APP_BOOT_LAYERED_INHERITED', 'inherited')
+    vi.stubEnv('APP_BOOT_LAYERED_INHERITED', 'inherited')
     const warn = vi.fn()
     try {
       loadLayeredEnv(NAME, project, warn)
@@ -119,7 +119,7 @@ describe('loadLayeredEnv', () => {
       expect(process.env[NAMES[0]]).toBe('project')
       expect(process.env[NAMES[1]]).toBe('user-only')
       expect(process.env[NAMES[2]]).toBe('project-only')
-      expect(process.env['DSH_APP_BOOT_LAYERED_INHERITED']).toBe('inherited')
+      expect(process.env['APP_BOOT_LAYERED_INHERITED']).toBe('inherited')
       expect(warn).not.toHaveBeenCalled()
     } finally {
       clear()
@@ -127,18 +127,64 @@ describe('loadLayeredEnv', () => {
     }
   })
 
-  it('resolves the harness home before the project file can redirect it', () => {
+  it.each([
+    ['a harness switch', 'DSH_PERMISSION_MODE=danger-full-access\n'],
+    ['the executable search path', 'PATH=/tmp/evil\n'],
+    ['a module preload', 'NODE_OPTIONS=--require /tmp/evil.js\n'],
+    ['a skill root', 'DSH_AGENTS_HOME=/tmp/injected\n'],
+    ['a network proxy', 'HTTPS_PROXY=http://attacker.example\n'],
+    ['a lowercase network proxy', 'https_proxy=http://attacker.example\n'],
+  ])('refuses to launch when a .env sets %s, before applying anything', (_case, content) => {
+    const home = tmp()
+    const project = tmp()
+    writeFileSync(join(project, '.env'), `${NAMES[1]}=applied-anyway\n${content}`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    try {
+      expect(() => loadLayeredEnv(NAME, project, vi.fn())).toThrow(/only the launching environment may set/)
+      // Rejected BEFORE materialization: reporting the violation after the
+      // file was applied would leave the process running under what it refused.
+      expect(process.env[NAMES[1]]).toBeUndefined()
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('reports each layer with its absolute path', () => {
+    const home = tmp()
+    const project = tmp()
+    writeFileSync(join(home, '.env'), `${NAMES[1]}=u\n`)
+    writeFileSync(join(project, '.env'), `${NAMES[2]}=p\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    try {
+      const snapshot = loadLayeredEnv(NAME, project, vi.fn())
+      expect(snapshot.layers).toEqual([
+        { source: 'process' },
+        { source: 'project-env', path: join(project, '.env') },
+        { source: 'user-env', path: join(home, '.env') },
+      ])
+      expect(snapshot.get(NAMES[1])).toEqual({ value: 'u', source: 'user-env', path: join(home, '.env') })
+      // getFrom is a refusal, not a demotion: an omitted layer is invisible.
+      expect(snapshot.getFrom(NAMES[2], ['process', 'user-env'])).toBeUndefined()
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('resolves the harness home from the inherited environment, never from a file', () => {
     const home = tmp()
-    const decoy = tmp()
     const project = tmp()
     writeFileSync(join(home, '.env'), `${NAMES[1]}=real-home\n`)
-    writeFileSync(join(decoy, '.env'), `${NAMES[1]}=decoy-home\n`)
-    writeFileSync(join(project, '.env'), `DSH_HOME=${decoy}\n`)
+    writeFileSync(join(project, '.env'), `${NAMES[2]}=set-by-project\n`)
     clear()
     vi.stubEnv('DSH_HOME', home)
     try {
       loadLayeredEnv(NAME, project, vi.fn())
       expect(process.env[NAMES[1]]).toBe('real-home')
+      expect(process.env[NAMES[2]]).toBe('set-by-project')
     } finally {
       clear()
       vi.unstubAllEnvs()
diff --git a/packages/ui/app-boot/tsconfig.json b/packages/ui/app-boot/tsconfig.json
index beb61317dc..18ddbedad3 100644
--- a/packages/ui/app-boot/tsconfig.json
+++ b/packages/ui/app-boot/tsconfig.json
@@ -26,6 +26,9 @@
     {
       "path": "../../core/system-prompt"
     },
+    {
+      "path": "../../util/environment"
+    },
     {
       "path": "../../util/paths"
     }
diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
new file mode 100644
index 0000000000..9d251d1940
--- /dev/null
+++ b/packages/util/environment/README.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 packages/util/environment/README.md
+README.md: f642aa715c87878b2eaab9f034fb18163a6fbd2e
+README.zh.md: a095730dbc8c2a4e7dc8dc57dc2930685c8fb453
diff --git a/packages/util/environment/README.md b/packages/util/environment/README.md
new file mode 100644
index 0000000000..f642aa715c
--- /dev/null
+++ b/packages/util/environment/README.md
@@ -0,0 +1,42 @@
+# dsh-environment
+
+English | [中文](README.zh.md)
+
+This run's environment as one immutable snapshot that remembers **which layer supplied each value**. Consumers resolve user-facing values against it instead of `process.env`, because the layers are not equally trusted and a flattened view cannot tell them apart.
+
+| Layer | Source id | What it is |
+|---|---|---|
+| Inherited process environment | `process` | What the launching shell, CI job, or container passed in — this run's explicit intent |
+| `<invocation cwd>/.env` | `project-env` | Whatever the project directory happens to contain; a model working in that workspace can write it |
+| `$DSH_HOME/.env` | `user-env` | The user's own machine-level defaults |
+
+Values do also reach `process.env` — a user's `--config` tree and third-party libraries read it — but that flattened view is not the authority for anything the harness resolves.
+
+## Resolving
+
+`get(name)` searches every layer, most trusted first. `getFrom(name, sources)` searches only the layers the caller trusts.
+
+**Omitting a layer is a refusal, not a demotion.** A base URL decides where a resolved API key is sent, so the LLM adapters ask for `['process', 'user-env']`: no future reordering can let a project file redirect a credential, because that layer is never consulted at all.
+
+```ts
+import type { Context } from 'cordis'
+import { environmentOf } from '@deepseek-ai/dsh-environment'
+
+declare const ctx: Context
+const endpoint = environmentOf(ctx).getFrom('DEEPSEEK_BASE_URL', ['process', 'user-env'])?.value
+```
+
+`environmentOf(ctx)` returns the launcher's snapshot when the product CLI booted the tree, and otherwise the inherited environment as the only layer. That fallback does not weaken the rules: an SDK host or a bare `cordis.yml` discovered no files, so everything it has really is the environment it was launched with.
+
+## Bootstrap variables
+
+`isBootstrapOnly(name)` names the variables only the inherited environment may set. The launcher rejects a `.env` that declares one, before applying anything.
+
+A bootstrap variable decides **how a process launches** (`PATH`, `SHELL`, `NODE_OPTIONS`, `NODE_PATH`, `LD_PRELOAD`, `LD_LIBRARY_PATH`, `DYLD_*`), **where code or model-visible instructions load from** (the whole `DSH_*` namespace, `HOME`, `USERPROFILE`, `XDG_*`), or **how the network is reached and trusted** (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`, `SSL_CERT_FILE`, `SSL_CERT_DIR`, `NODE_EXTRA_CA_CERTS`). Matching is case-insensitive, so `https_proxy` is not a bypass.
+
+The whole `DSH_*` namespace is denied rather than an audited subset: the harness's own switches — the permission mode, the agents home, the bundled skill root — are exactly what a hostile project would want, and a switch added later must not become settable by forgetting to list it.
+
+## Known Limitations and Deferred Work
+
+- **The snapshot is not a subprocess boundary** — every layer is also materialized into `process.env`, so ordinary project variables still reach child processes under [`dsh-subprocess`](../../subprocess/subprocess/README.md)'s scrub. Bootstrap variables cannot come from a file at all, but a project `.env` can still set, say, `GIT_SSH_COMMAND` for the tools an agent runs.
+- **No per-workspace layer** — the project layer is the *invoking* directory, fixed at launch. A workspace selected later in the Web UI contributes nothing, deliberately: following it would let a model's own workspace change the harness environment mid-session.
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
new file mode 100644
index 0000000000..a095730dbc
--- /dev/null
+++ b/packages/util/environment/README.zh.md
@@ -0,0 +1,42 @@
+# dsh-environment
+
+[English](README.md) | 中文
+
+把本次运行的环境冻结为一份不可变快照，并记住**每个值来自哪一层**。消费方用它而不是 `process.env` 解析面向用户的值，因为各层的可信程度并不相同，而压平后的视图无法区分它们。
+
+| 层 | 来源 id | 它是什么 |
+|---|---|---|
+| 继承的进程环境 | `process` | 启动 shell、CI 任务或容器传入的东西——本次运行的明确意图 |
+| `<invocation cwd>/.env` | `project-env` | 项目目录里恰好有的东西；在该工作区里工作的模型可以写它 |
+| `$DSH_HOME/.env` | `user-env` | 用户自己的机器级默认值 |
+
+这些值同样会进入 `process.env`——用户自己的 `--config` 树和第三方库要读它——但那份压平的视图不是 harness 解析任何值的依据。
+
+## 解析
+
+`get(name)` 按可信度从高到低搜索所有层。`getFrom(name, sources)` 只搜索调用方信任的层。
+
+**省略某一层是拒绝，不是降级。** base URL 决定已解析的 API key 被发往何处，因此 LLM 适配器请求的是 `['process', 'user-env']`：后续任何重新排序都无法让项目文件重定向凭据，因为那一层根本不会被查询。
+
+```ts
+import type { Context } from 'cordis'
+import { environmentOf } from '@deepseek-ai/dsh-environment'
+
+declare const ctx: Context
+const endpoint = environmentOf(ctx).getFrom('DEEPSEEK_BASE_URL', ['process', 'user-env'])?.value
+```
+
+当产品 CLI（命令行界面）启动了这棵树时，`environmentOf(ctx)` 返回启动器的快照；否则返回只含继承环境的那一层。该回退并不削弱规则：SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，因此它拥有的一切确实就是它被启动时的环境。
+
+## bootstrap 变量
+
+`isBootstrapOnly(name)` 给出只有继承环境才能设置的变量。启动器一旦发现某个 `.env` 声明了其中之一，就会在应用任何内容之前拒绝启动。
+
+bootstrap 变量决定**进程如何启动**（`PATH`、`SHELL`、`NODE_OPTIONS`、`NODE_PATH`、`LD_PRELOAD`、`LD_LIBRARY_PATH`、`DYLD_*`）、**代码或模型可见的指令从哪里加载**（整个 `DSH_*` 命名空间、`HOME`、`USERPROFILE`、`XDG_*`），或者**网络如何抵达与信任**（`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY`、`SSL_CERT_FILE`、`SSL_CERT_DIR`、`NODE_EXTRA_CA_CERTS`）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
+
+整个 `DSH_*` 命名空间被拒绝，而不是只拒绝一份经过审查的子集：harness 自己的开关——权限模式、agents home、内置 skill（技能）根目录——恰恰是敌意项目最想要的，而后来新增的开关不能因为忘记登记就变得可设置。
+
+## Known Limitations and Deferred Work
+
+- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此普通的项目变量仍会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。bootstrap 变量完全不能来自文件，但项目 `.env` 仍可以为 agent 运行的工具设置诸如 `GIT_SSH_COMMAND` 之类的变量。
+- **没有按工作区划分的层**：项目层是*调用*目录，在启动时固定。之后在 Web UI 中选择的工作区不贡献任何内容，这是刻意的：跟随它等于让模型自己的工作区在会话中途改变 harness 的环境。
diff --git a/packages/util/environment/package.json b/packages/util/environment/package.json
new file mode 100644
index 0000000000..94a2a76ef6
--- /dev/null
+++ b/packages/util/environment/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-environment",
+  "description": "Immutable launch-time environment snapshot with per-layer provenance for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/util/environment/src/index.ts b/packages/util/environment/src/index.ts
new file mode 100644
index 0000000000..100a0fe9f0
--- /dev/null
+++ b/packages/util/environment/src/index.ts
@@ -0,0 +1,178 @@
+/**
+ * The launch-time environment as one immutable snapshot that remembers which
+ * layer supplied each value. The harness resolves user-facing values against
+ * this rather than against `process.env`, because the layers differ in how
+ * much they are trusted: an inherited variable is this run's explicit intent,
+ * a file discovered under the invoking directory is whatever the project
+ * happens to contain, and a consumer that cannot tell them apart cannot make
+ * that distinction.
+ *
+ * Values still reach `process.env` as well — a user's own `--config` tree and
+ * third-party libraries read it — but that flattened view is not the
+ * authority for anything the harness itself resolves.
+ * @module @deepseek-ai/dsh-environment
+ */
+
+import type { Context } from 'cordis'
+
+/**
+ * Which layer supplied a value, from most to least trusted: the environment
+ * this process inherited, the invoking directory's `.env`, the Harness home's
+ * `.env`.
+ */
+export type EnvironmentSource = 'process' | 'project-env' | 'user-env'
+
+/** Layer order, most trusted first — the default search order of {@link EnvironmentSnapshot.get}. */
+export const ENVIRONMENT_SOURCES: readonly EnvironmentSource[] = ['process', 'project-env', 'user-env']
+
+/** One resolved variable and the layer it came from. */
+export interface EnvironmentEntry {
+  /** The value as the layer supplied it; may be empty, which each owner judges for itself. */
+  value: string
+  /** The layer that supplied it. */
+  source: EnvironmentSource
+  /** Absolute path of the file that supplied it; absent for `process`. */
+  path?: string
+}
+
+/** One environment layer's identity, for diagnostics. */
+export interface EnvironmentLayer {
+  source: EnvironmentSource
+  /** Absolute path of the file behind this layer; absent for `process`. */
+  path?: string
+}
+
+/**
+ * The frozen environment of one launch. Construct through
+ * {@link createEnvironmentSnapshot}; nothing mutates it afterwards, so a
+ * later `chdir`, workspace switch, or resumed session observes the same
+ * values a consumer resolved at boot.
+ */
+export interface EnvironmentSnapshot {
+  /**
+   * Resolve one name across every layer, most trusted first.
+   * @param name - the variable name.
+   * @returns the winning entry, or `undefined` when no layer supplies it.
+   */
+  get(name: string): EnvironmentEntry | undefined
+  /**
+   * Resolve one name across only the layers the caller trusts for this
+   * decision. Omitting a layer is a refusal, not a demotion: a routing field
+   * that must never come from a project directory omits `project-env` so no
+   * ordering change can let it back in.
+   * @param name - the variable name.
+   * @param sources - the layers to search, in the caller's own priority order.
+   * @returns the first matching entry, or `undefined`.
+   */
+  getFrom(name: string, sources: readonly EnvironmentSource[]): EnvironmentEntry | undefined
+  /** The layers this snapshot was built from, most trusted first. */
+  readonly layers: readonly EnvironmentLayer[]
+}
+
+/** One layer's raw contents, as {@link createEnvironmentSnapshot} receives them. */
+export interface EnvironmentLayerInput {
+  source: EnvironmentSource
+  /** Absolute path of the file behind this layer; omit for `process`. */
+  path?: string
+  values: Readonly<Record<string, string>>
+}
+
+/**
+ * Build the snapshot from each layer's contents.
+ * @param layers - the layers in any order; the result searches them by {@link ENVIRONMENT_SOURCES}.
+ * @returns the immutable snapshot.
+ */
+export function createEnvironmentSnapshot(layers: readonly EnvironmentLayerInput[]): EnvironmentSnapshot {
+  // Copied per layer so a later mutation of `process.env` — or of a caller's
+  // own object — cannot change what this snapshot reports.
+  const bySource = new Map<EnvironmentSource, { path?: string; values: Map<string, string> }>()
+  for (const layer of layers) {
+    bySource.set(layer.source, {
+      ...layer.path === undefined ? {} : { path: layer.path },
+      values: new Map(Object.entries(layer.values)),
+    })
+  }
+  const getFrom = (name: string, sources: readonly EnvironmentSource[]): EnvironmentEntry | undefined => {
+    for (const source of sources) {
+      const layer = bySource.get(source)
+      const value = layer?.values.get(name)
+      if (value === undefined) continue
+      return { value, source, ...layer?.path === undefined ? {} : { path: layer.path } }
+    }
+    return undefined
+  }
+  return {
+    get: name => getFrom(name, ENVIRONMENT_SOURCES),
+    getFrom,
+    layers: ENVIRONMENT_SOURCES
+      .filter(source => bySource.has(source))
+      .map((source): EnvironmentLayer => {
+        const path = bySource.get(source)?.path
+        return { source, ...path === undefined ? {} : { path } }
+      }),
+  }
+}
+
+/** Context slot the launcher fills with this run's snapshot before any config entry mounts. */
+export const DSH_ENVIRONMENT_KEY = 'launcherEnvironment'
+
+/**
+ * The snapshot to resolve against, whatever booted this tree: the launcher's
+ * when the product CLI provided one, otherwise the inherited environment
+ * alone.
+ *
+ * The fallback does not weaken the layer rules — it applies the same rules to
+ * a host that has exactly one layer. An SDK embedder or a bare `cordis.yml`
+ * never discovered a project or user file, so everything it has really is the
+ * environment it was launched with, and `getFrom(..., ['process'])` is exactly
+ * right for it.
+ * @param ctx - the consuming plugin's context.
+ * @returns the snapshot to resolve user-facing values against.
+ */
+export function environmentOf(ctx: Context): EnvironmentSnapshot {
+  return ctx.get(DSH_ENVIRONMENT_KEY)
+    ?? createEnvironmentSnapshot([{ source: 'process', values: process.env as Record<string, string> }])
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** Launcher-owned snapshot of this run's environment; absent in compositions the product CLI did not boot. */
+    launcherEnvironment?: EnvironmentSnapshot
+  }
+}
+
+/** Exact names no discovered file may set. */
+const BOOTSTRAP_NAMES = new Set([
+  // Process launch and module resolution.
+  'PATH', 'HOME', 'USERPROFILE', 'SHELL',
+  'NODE_OPTIONS', 'NODE_PATH', 'NODE_EXTRA_CA_CERTS',
+  'LD_PRELOAD', 'LD_LIBRARY_PATH',
+  // Network reach and trust.
+  'SSL_CERT_FILE', 'SSL_CERT_DIR',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+])
+
+/** Name prefixes no discovered file may set. */
+const BOOTSTRAP_PREFIXES = ['DSH_', 'XDG_', 'DYLD_']
+
+/**
+ * Whether a variable may come only from the inherited process environment.
+ *
+ * A bootstrap variable decides how a process launches (`PATH`, `NODE_OPTIONS`,
+ * `LD_PRELOAD`), where code or model-visible instructions load from (`DSH_*`
+ * covers the Harness home, the agents home, and the bundled skill root), or
+ * how the network is reached and trusted (proxy and CA variables). A file the
+ * harness merely finds — including one a model can write inside the workspace
+ * — must never set them, so they are rejected at load rather than ranked
+ * below another layer.
+ *
+ * The whole `DSH_*` namespace is denied rather than an audited subset: the
+ * harness's own switches are exactly the ones a hostile project would want,
+ * and a new switch must not become settable by forgetting to list it.
+ * @param name - the variable name.
+ * @returns true when only the inherited environment may supply it.
+ */
+export function isBootstrapOnly(name: string): boolean {
+  const upper = name.toUpperCase()
+  return BOOTSTRAP_NAMES.has(upper) || BOOTSTRAP_PREFIXES.some(prefix => upper.startsWith(prefix))
+}
diff --git a/packages/util/environment/src/invariant.ts b/packages/util/environment/src/invariant.ts
new file mode 100644
index 0000000000..96e53828ae
--- /dev/null
+++ b/packages/util/environment/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-environment`.
+ * @module @deepseek-ai/dsh-environment/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-environment'
+
+/** Cordis companion plugin name. */
+export const name = 'environment-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the snapshot is frozen before any fiber starts and this package owns no
+ * event stream or mutable runtime data; its lookup and rejection rules are enforced by unit tests.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/util/environment/tests/environment.spec.ts b/packages/util/environment/tests/environment.spec.ts
new file mode 100644
index 0000000000..27c7b16e55
--- /dev/null
+++ b/packages/util/environment/tests/environment.spec.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import {
+  createEnvironmentSnapshot, DSH_ENVIRONMENT_KEY, ENVIRONMENT_SOURCES, environmentOf, isBootstrapOnly,
+} from '../src/index.ts'
+
+const layered = createEnvironmentSnapshot([
+  { source: 'process', values: { SHARED: 'from-process', ONLY_PROCESS: 'p' } },
+  { source: 'project-env', path: '/work/.env', values: { SHARED: 'from-project', ONLY_PROJECT: 'j' } },
+  { source: 'user-env', path: '/home/.dsh/.env', values: { SHARED: 'from-user', ONLY_USER: 'u' } },
+])
+
+describe('createEnvironmentSnapshot', () => {
+  it('resolves across every layer, most trusted first, and reports the winning source', () => {
+    expect(layered.get('SHARED')).toEqual({ value: 'from-process', source: 'process' })
+    expect(layered.get('ONLY_PROJECT')).toEqual({ value: 'j', source: 'project-env', path: '/work/.env' })
+    expect(layered.get('ONLY_USER')).toEqual({ value: 'u', source: 'user-env', path: '/home/.dsh/.env' })
+    expect(layered.get('ABSENT')).toBeUndefined()
+  })
+
+  it('treats an omitted layer as invisible, not merely lower', () => {
+    // The point of getFrom: a routing field that must never come from a
+    // project directory cannot be reached by reordering, only by listing it.
+    expect(layered.getFrom('ONLY_PROJECT', ['process', 'user-env'])).toBeUndefined()
+    expect(layered.getFrom('SHARED', ['user-env', 'process'])).toEqual({
+      value: 'from-user', source: 'user-env', path: '/home/.dsh/.env',
+    })
+    expect(layered.getFrom('SHARED', [])).toBeUndefined()
+  })
+
+  it('lists its layers in trust order with their paths', () => {
+    expect(layered.layers).toEqual([
+      { source: 'process' },
+      { source: 'project-env', path: '/work/.env' },
+      { source: 'user-env', path: '/home/.dsh/.env' },
+    ])
+    expect(createEnvironmentSnapshot([{ source: 'process', values: {} }]).layers).toEqual([{ source: 'process' }])
+  })
+
+  it('copies each layer, so a later mutation of the source object cannot change it', () => {
+    const values: Record<string, string> = { KEY: 'first' }
+    const snapshot = createEnvironmentSnapshot([{ source: 'process', values }])
+    values.KEY = 'second'
+    values.LATE = 'added'
+    expect(snapshot.get('KEY')).toEqual({ value: 'first', source: 'process' })
+    expect(snapshot.get('LATE')).toBeUndefined()
+  })
+
+  it('keeps an empty value as a present value, for its owner to judge', () => {
+    const snapshot = createEnvironmentSnapshot([{ source: 'process', values: { EMPTY: '' } }])
+    expect(snapshot.get('EMPTY')).toEqual({ value: '', source: 'process' })
+  })
+
+  it('orders lookups by ENVIRONMENT_SOURCES regardless of construction order', () => {
+    const reversed = createEnvironmentSnapshot([
+      { source: 'user-env', path: '/u', values: { K: 'u' } },
+      { source: 'process', values: { K: 'p' } },
+    ])
+    expect(ENVIRONMENT_SOURCES).toEqual(['process', 'project-env', 'user-env'])
+    expect(reversed.get('K')).toEqual({ value: 'p', source: 'process' })
+  })
+})
+
+describe('environmentOf', () => {
+  it('returns the launcher snapshot when the product CLI provided one', () => {
+    const ctx = new Context()
+    ctx.provide(DSH_ENVIRONMENT_KEY, layered)
+    expect(environmentOf(ctx)).toBe(layered)
+  })
+
+  it('falls back to the inherited environment as the only layer', () => {
+    vi.stubEnv('DSH_ENV_SPEC_FALLBACK', 'ambient')
+    try {
+      const snapshot = environmentOf(new Context())
+      expect(snapshot.get('DSH_ENV_SPEC_FALLBACK')).toEqual({ value: 'ambient', source: 'process' })
+      // A host that discovered no files has exactly one layer, so the trusted
+      // lookups every consumer makes still find what it was launched with.
+      expect(snapshot.getFrom('DSH_ENV_SPEC_FALLBACK', ['process', 'user-env'])?.value).toBe('ambient')
+      expect(snapshot.layers).toEqual([{ source: 'process' }])
+    } finally {
+      vi.unstubAllEnvs()
+    }
+  })
+})
+
+describe('isBootstrapOnly', () => {
+  it.each([
+    'PATH', 'HOME', 'USERPROFILE', 'SHELL',
+    'NODE_OPTIONS', 'NODE_PATH', 'NODE_EXTRA_CA_CERTS',
+    'LD_PRELOAD', 'LD_LIBRARY_PATH',
+    'SSL_CERT_FILE', 'SSL_CERT_DIR',
+    'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+  ])('rejects %s, which decides how the process starts or reaches the network', (name) => {
+    expect(isBootstrapOnly(name)).toBe(true)
+  })
+
+  it.each([
+    ['DSH_HOME', 'the harness home'],
+    ['DSH_PERMISSION_MODE', 'the permission mode'],
+    ['DSH_AGENTS_HOME', 'a model-visible instruction root'],
+    ['DSH_ANYTHING_ADDED_LATER', 'a switch that does not exist yet'],
+    ['XDG_CONFIG_HOME', 'a state root'],
+    ['DYLD_INSERT_LIBRARIES', 'a library preload'],
+  ])('rejects the whole namespace: %s (%s)', (name) => {
+    expect(isBootstrapOnly(name)).toBe(true)
+  })
+
+  it('matches case-insensitively, so a lowercase proxy name is not a bypass', () => {
+    expect(isBootstrapOnly('https_proxy')).toBe(true)
+    expect(isBootstrapOnly('dsh_permission_mode')).toBe(true)
+  })
+
+  it('allows ordinary variables, including provider credentials and endpoints', () => {
+    for (const name of ['DEEPSEEK_API_KEY', 'DEEPSEEK_BASE_URL', 'EXA_API_KEY', 'MY_PROJECT_FLAG', 'PATHS']) {
+      expect(isBootstrapOnly(name)).toBe(false)
+    }
+  })
+})
diff --git a/packages/util/environment/tsconfig.json b/packages/util/environment/tsconfig.json
new file mode 100644
index 0000000000..d970a00263
--- /dev/null
+++ b/packages/util/environment/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/web/web-search-deepseek/package.json b/packages/web/web-search-deepseek/package.json
index e1dbf720f6..b286c5d421 100644
--- a/packages/web/web-search-deepseek/package.json
+++ b/packages/web/web-search-deepseek/package.json
@@ -29,6 +29,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-credentials": "^0.0.1",
+    "@deepseek-ai/dsh-environment": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-web": "^0.0.1",
@@ -41,6 +42,7 @@
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-credentials": "workspace:^",
     "@deepseek-ai/dsh-credentials-local": "workspace:^",
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-web": "workspace:^",
diff --git a/packages/web/web-search-deepseek/src/index.ts b/packages/web/web-search-deepseek/src/index.ts
index 8569f0e944..3a7e1f65a9 100644
--- a/packages/web/web-search-deepseek/src/index.ts
+++ b/packages/web/web-search-deepseek/src/index.ts
@@ -9,6 +9,7 @@ import type { Context } from 'cordis'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-agent'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { environmentOf } from '@deepseek-ai/dsh-environment'
 import type {} from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-web'
 import {
@@ -80,8 +81,10 @@ export function apply(ctx: Context, config: Config): void {
     resolveApiKey: async () => {
       const credentials = ctx.get('credentials')
       if (credentials !== undefined) return (await credentials.resolve(apiKeyEnv))?.value
-      const ambient = process.env[apiKeyEnv]
-      return ambient !== undefined && ambient.length > 0 ? ambient : undefined
+      // Without the seam the launching environment is the whole credential
+      // plane — but only that layer, never a discovered project file.
+      const inherited = environmentOf(ctx).getFrom(apiKeyEnv, ['process'])
+      return inherited !== undefined && inherited.value.length > 0 ? inherited.value : undefined
     },
     apiKeyEnv,
     baseURL: config.baseURL ?? DEEPSEEK_DEFAULT_BASE_URL,
diff --git a/packages/web/web-search-deepseek/tsconfig.json b/packages/web/web-search-deepseek/tsconfig.json
index 76c411d089..b3d8e2ade6 100644
--- a/packages/web/web-search-deepseek/tsconfig.json
+++ b/packages/web/web-search-deepseek/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../util/environment"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/packages/web/web-search-exa/package.json b/packages/web/web-search-exa/package.json
index 7d6b802d2e..b9c2fba351 100644
--- a/packages/web/web-search-exa/package.json
+++ b/packages/web/web-search-exa/package.json
@@ -27,6 +27,7 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-environment": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-web": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
@@ -35,6 +36,7 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-web": "workspace:^",
     "cordis": "^4.0.0-rc.7"
diff --git a/packages/web/web-search-exa/src/index.ts b/packages/web/web-search-exa/src/index.ts
index 67b2eed574..87a8e6572e 100644
--- a/packages/web/web-search-exa/src/index.ts
+++ b/packages/web/web-search-exa/src/index.ts
@@ -9,6 +9,7 @@
  */
 
 import type { Context } from 'cordis'
+import { environmentOf } from '@deepseek-ai/dsh-environment'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-web'
 import {
@@ -58,7 +59,10 @@ export const Config: z<Config> = z.object({
 /** Register the Exa search provider with `ctx.web`. */
 export function apply(ctx: Context, config: Config): void {
   ctx.web.registerSearchProvider(new ExaSearchProvider({
-    apiKey: config.apiKey ?? process.env.EXA_API_KEY ?? '',
+    // Only the launching shell and the user's own `.env` may name this key:
+    // a project directory can be written by the model, and a substituted key
+    // would route every request through an account someone else reads.
+    apiKey: config.apiKey ?? environmentOf(ctx).getFrom('EXA_API_KEY', ['process', 'user-env'])?.value ?? '',
     baseURL: config.baseURL ?? EXA_DEFAULT_BASE_URL,
     searchType: config.searchType ?? EXA_DEFAULT_SEARCH_TYPE,
     highlightsPerResult: config.highlightsPerResult ?? EXA_DEFAULT_HIGHLIGHTS_PER_RESULT,
diff --git a/packages/web/web-search-exa/tsconfig.json b/packages/web/web-search-exa/tsconfig.json
index e9610ea5c9..770ee55a04 100644
--- a/packages/web/web-search-exa/tsconfig.json
+++ b/packages/web/web-search-exa/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../util/environment"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/packages/web/web-search-perplexity/package.json b/packages/web/web-search-perplexity/package.json
index 9aa7080431..5f64df89ee 100644
--- a/packages/web/web-search-perplexity/package.json
+++ b/packages/web/web-search-perplexity/package.json
@@ -27,6 +27,7 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-environment": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-web": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
@@ -35,6 +36,7 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-web": "workspace:^",
     "cordis": "^4.0.0-rc.7"
diff --git a/packages/web/web-search-perplexity/src/index.ts b/packages/web/web-search-perplexity/src/index.ts
index d673f575c8..b2b5804a92 100644
--- a/packages/web/web-search-perplexity/src/index.ts
+++ b/packages/web/web-search-perplexity/src/index.ts
@@ -8,6 +8,7 @@
  */
 
 import type { Context } from 'cordis'
+import { environmentOf } from '@deepseek-ai/dsh-environment'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-web'
 import { PerplexitySearchProvider, PERPLEXITY_DEFAULT_BASE_URL, PERPLEXITY_DEFAULT_MAX_TOKENS, PERPLEXITY_DEFAULT_MODEL } from './provider.ts'
@@ -52,7 +53,10 @@ export const Config: z<Config> = z.object({
 /** Register the Perplexity search provider with `ctx.web`. */
 export function apply(ctx: Context, config: Config): void {
   ctx.web.registerSearchProvider(new PerplexitySearchProvider({
-    apiKey: config.apiKey ?? process.env.PERPLEXITY_API_KEY ?? '',
+    // Only the launching shell and the user's own `.env` may name this key:
+    // a project directory can be written by the model, and a substituted key
+    // would route every request through an account someone else reads.
+    apiKey: config.apiKey ?? environmentOf(ctx).getFrom('PERPLEXITY_API_KEY', ['process', 'user-env'])?.value ?? '',
     baseURL: config.baseURL ?? PERPLEXITY_DEFAULT_BASE_URL,
     model: config.model ?? PERPLEXITY_DEFAULT_MODEL,
     maxTokens: config.maxTokens ?? PERPLEXITY_DEFAULT_MAX_TOKENS,
diff --git a/packages/web/web-search-perplexity/tsconfig.json b/packages/web/web-search-perplexity/tsconfig.json
index e9610ea5c9..770ee55a04 100644
--- a/packages/web/web-search-perplexity/tsconfig.json
+++ b/packages/web/web-search-perplexity/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../util/environment"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a74fc2677f..ac412c983a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -243,6 +243,9 @@ importers:
       '@deepseek-ai/dsh-credentials-local':
         specifier: workspace:^
         version: link:../../packages/credentials/credentials-local
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../packages/util/environment
       '@deepseek-ai/dsh-frontend':
         specifier: workspace:^
         version: link:../web
@@ -2638,6 +2641,9 @@ importers:
       '@deepseek-ai/dsh-credentials':
         specifier: workspace:^
         version: link:../credentials
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../util/environment
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3609,6 +3615,9 @@ importers:
       '@deepseek-ai/dsh-credentials':
         specifier: workspace:^
         version: link:../../credentials/credentials
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../util/environment
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3637,6 +3646,9 @@ importers:
       '@deepseek-ai/dsh-credentials':
         specifier: workspace:^
         version: link:../../credentials/credentials
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../util/environment
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -5673,6 +5685,9 @@ importers:
 
   packages/ui/app-boot:
     dependencies:
+      dotenv:
+        specifier: ^17.2.0
+        version: 17.4.2
       js-yaml:
         specifier: ^4.2.0
         version: 4.2.0
@@ -5689,6 +5704,9 @@ importers:
       '@cordisjs/plugin-timer':
         specifier: workspace:^
         version: link:../../../vendor/timer
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../util/environment
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -5988,6 +6006,15 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/util/environment:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/util/native-command:
     devDependencies:
       '@deepseek-ai/dsh-invariants':
@@ -6129,6 +6156,9 @@ importers:
       '@deepseek-ai/dsh-credentials-local':
         specifier: workspace:^
         version: link:../../credentials/credentials-local
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../util/environment
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -6148,6 +6178,9 @@ importers:
         specifier: ^3.18.0
         version: link:../../../vendor/schemastery
     devDependencies:
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../util/environment
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -6164,6 +6197,9 @@ importers:
         specifier: ^3.18.0
         version: link:../../../vendor/schemastery
     devDependencies:
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../util/environment
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -6420,6 +6456,9 @@ importers:
       '@deepseek-ai/dsh-credentials':
         specifier: workspace:^
         version: link:../../packages/credentials/credentials
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../packages/util/environment
       '@deepseek-ai/dsh-fs':
         specifier: workspace:^
         version: link:../../packages/fs/fs
@@ -9776,6 +9815,10 @@ packages:
   dompurify@3.4.11:
     resolution: {integrity: sha512-zhlUV12GsaRzMsf9q5M254YhA4+VuF0fG+QFqu6aYpoGlKtz+w8//jBcGVYBgQkR5GHjUomejY84AV+/uPbWdw==}
 
+  dotenv@17.4.2:
+    resolution: {integrity: sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==}
+    engines: {node: '>=12'}
+
   dts-resolver@3.0.0:
     resolution: {integrity: sha512-1T1f+z+4tl9XD+m+0HBgWoL/nm0bOIffyWaUuUSBlFg/86IWvfx+wjNaO/ybU0AJzG9/Mi5hBUgGV6zCmWEN7Q==}
     engines: {node: ^22.18.0 || >=24.0.0}
@@ -14828,6 +14871,8 @@ snapshots:
     optionalDependencies:
       '@types/trusted-types': 2.0.7
 
+  dotenv@17.4.2: {}
+
   dts-resolver@3.0.0(oxc-resolver@11.20.0):
     optionalDependencies:
       oxc-resolver: 11.20.0
diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json
index a4d555055d..bfbf63ba9a 100644
--- a/python/sdk-runtime/package.json
+++ b/python/sdk-runtime/package.json
@@ -24,6 +24,7 @@
     "@deepseek-ai/dsh-compact-basic": "workspace:^",
     "@deepseek-ai/dsh-compact-tool-result-prune": "workspace:^",
     "@deepseek-ai/dsh-credentials": "workspace:^",
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-fs": "workspace:^",
     "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-fs-policy": "workspace:^",
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index f2173478f1..92c4d31d59 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -569,6 +569,7 @@ function docSyncLeafGates(options: {
     pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
     pnpmScript('doc-refs', 'verify-doc-refs', { label: 'doc refs' }),
     pnpmScript('package-paths', 'verify-package-paths', { label: 'package paths' }),
+    pnpmScript('config-source-ownership', 'verify-config-source-ownership', { label: 'config source ownership' }),
     pnpmScript('package-readme-model-experience', 'verify-package-readme-model-experience', { label: 'package README model experience' }),
     pnpmScript('mermaid', 'verify-mermaid'),
     pnpmScript('agent-note-classification', 'verify-agent-note-classification', { label: 'agent note classification' }),
diff --git a/scripts/verify-config-source-ownership.ts b/scripts/verify-config-source-ownership.ts
new file mode 100644
index 0000000000..d346b19233
--- /dev/null
+++ b/scripts/verify-config-source-ownership.ts
@@ -0,0 +1,117 @@
+/**
+ * Gate: every user-facing value has one owner, and no shipped file smuggles a
+ * second one in.
+ *
+ * Two rules, both about the same failure — a value reaching the harness
+ * through a path nobody ranked:
+ *
+ * 1. Production package source does not read `process.env` directly. A
+ *    credential belongs to `ctx.credentials`, a user-configurable value to the
+ *    environment snapshot plus its owner's resolve step, and a real
+ *    process-launch fact to the app bootstrap. Each remaining read is listed
+ *    below with the reason it is one of those.
+ * 2. Shipped Cordis configuration does not inline a credential or an endpoint
+ *    from the environment. Doing so re-creates the layer the snapshot exists
+ *    to rank: `apiKey: !!js process.env.X` and `baseURL: !!js process.env.X`
+ *    bypass both the credential seam and the endpoint ladder, and a project
+ *    file could then decide where a key is sent.
+ * @module scripts/verify-config-source-ownership
+ */
+
+import { globSync, readFileSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
+
+const ROOT = resolve(import.meta.dirname, '..')
+
+/**
+ * Production package sources allowed to read `process.env`, each with the
+ * reason it is a process fact rather than a user-configurable value. Adding a
+ * row is a deliberate act: state which of the three owners it belongs to and
+ * why it cannot go there.
+ */
+const ENV_READ_ALLOWLIST: Readonly<Record<string, string>> = {
+  // The environment plane itself.
+  'packages/util/environment/src/index.ts': 'defines the snapshot; the inherited environment is its input',
+  'packages/ui/app-boot/src/index.ts': 'the app bootstrap that builds the snapshot and reads $DSH_SNAPSHOT',
+  'packages/util/paths/src/index.ts': 'resolves $DSH_HOME before any snapshot exists',
+
+  // Process-launch facts owned by the boundary that spawns or is spawned.
+  'packages/subprocess/subprocess/src/index.ts': 'scrubs the parent environment for children',
+  'packages/workflow/workflow-workerthread/src/host.ts': 'passes the parent environment to a worker thread',
+  'packages/ui/tui/src/index.ts': 'reads $COLORTERM, a terminal capability of this process',
+  'packages/lsp/lsp-local/src/index.ts': 'passes the parent environment to a language server it spawns',
+  'packages/cordis/repository-plugin/src/index.ts': 'resolves an MCP manifest against the spawning environment',
+
+  // Bootstrap-only DSH_* switches, which no discovered file may set.
+  'packages/skill/skill-local/src/index.ts': 'reads $DSH_AGENTS_HOME and $DSH_BUNDLED_SKILL_DIR, both bootstrap-only',
+  'packages/web/web/src/index.ts': 'reads $DSH_WEB_SEARCH_PROVIDER and $DSH_WEB_FETCH_PROVIDER, both bootstrap-only',
+  'packages/host/directory-picker-auto/src/index.ts': 'reads launch facts (display, SSH) of this process',
+  'packages/host/directory-picker-auto/src/resolve.ts': 'reads launch facts (display, SSH) of this process',
+
+  // Telemetry identity and consent, resolved once per process at bootstrap.
+  'packages/telemetry/session-telemetry-otel/src/user-id.ts': 'derives a machine identity from process facts',
+  'packages/sdk/telemetry/src/consent-resolver.ts': 'reads the SDK bootstrap consent switch',
+  'packages/sdk/telemetry/src/anonymous-id.ts': 'derives a machine identity from process facts',
+
+  // SDK and example bins: their own app bootstrap, outside the product CLI.
+  'packages/sdk/sdk-client/src/client.ts': 'SDK host bootstrap',
+  'packages/sdk/helper/src/features/builtin/provider.ts': 'SDK scaffolding reads the developer environment',
+  'packages/sdk/helper/src/features/builtin/app.ts': 'SDK scaffolding reads the developer environment',
+  'packages/sdk/helper/src/package-managers/package-manager.ts': 'detects the invoking package manager',
+  'packages/sdk/create-sdk/src/create-wizard.ts': 'SDK scaffolding reads the developer environment',
+  'packages/examples/jsonrpc-demo/src/bin.ts': 'demo bin bootstrap',
+  'packages/examples/acp-demo/src/bin.ts': 'demo bin bootstrap',
+
+  // Test and replay infrastructure.
+  'packages/support/loader-smoke/src/index.ts': 'test launcher composing a child environment',
+  'packages/support/llm-replay/src/index.ts': 'replay fixture switch',
+  'packages/support/acp-snapshot/src/launcher.ts': 'snapshot launcher composing a child environment',
+
+  // Browser bundle: `process.env` is replaced at build time, never read at runtime.
+  'packages/client/runtime/src/client/contract/store.ts': 'build-time constant folded by the bundler',
+}
+
+/** Shipped Cordis configuration these rules apply to. */
+const SHIPPED_CONFIG_GLOBS = ['apps/*/config/*.yml', 'examples/*/*.cordis.yml', 'examples/*/cordis.yml']
+
+/** Config keys that must never be inlined from the environment. */
+const INLINE_DENY = /^\s*(apiKey|baseURL|apiKeyEnv|authToken|headers)\s*:\s*!!js\b/
+
+const failures: string[] = []
+
+for (const file of globSync('packages/*/*/src/**/*.ts', { cwd: ROOT })) {
+  const rel = file.split(sep).join('/')
+  if (!readFileSync(resolve(ROOT, rel), 'utf8').includes('process.env')) continue
+  if (rel in ENV_READ_ALLOWLIST) continue
+  failures.push(
+    `${rel}: reads process.env directly. A credential belongs to ctx.credentials, a user-configurable`
+    + ' value to environmentOf(ctx) plus its owner\'s resolve step, and a process-launch fact to the app'
+    + ' bootstrap. If it is genuinely one of those, add it to ENV_READ_ALLOWLIST with the reason.',
+  )
+}
+
+for (const glob of SHIPPED_CONFIG_GLOBS) {
+  for (const file of globSync(glob, { cwd: ROOT })) {
+    const rel = file.split(sep).join('/')
+    readFileSync(resolve(ROOT, rel), 'utf8').split('\n').forEach((line, index) => {
+      if (!INLINE_DENY.test(line)) return
+      failures.push(
+        `${rel}:${String(index + 1)}: inlines a credential or endpoint from the environment.`
+        + ' The adapter resolves apiKeyEnv through ctx.credentials and the endpoint through the'
+        + ' environment snapshot; inlining here bypasses both ladders.',
+      )
+    })
+  }
+}
+
+if (failures.length > 0) {
+  process.stderr.write('verify-config-source-ownership: configuration source ownership violated:\n')
+  for (const failure of failures) process.stderr.write(`  ${failure}\n`)
+  process.exit(1)
+}
+
+const allowed = Object.keys(ENV_READ_ALLOWLIST).length
+process.stdout.write(
+  `verify-config-source-ownership: no unregistered process.env reads (${String(allowed)} allowlisted)`
+  + ' and no credential or endpoint inlined in shipped configuration.\n',
+)
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 4104ff8fdc..641daefa01 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -33,6 +33,7 @@ const NO_MODEL_EXPERIENCE_SECTION: Readonly<Record<string, string>> = {
   'packages/core/scope': 'The package is a model-agnostic registration and lifecycle primitive; model-facing consumers own any context selection.',
   'packages/util/brand': 'The package is a type-only primitive erased at compile time.',
   'packages/util/paths': 'The package only resolves harness-owned host paths; model-facing consumers own any rendered use.',
+  'packages/util/environment': 'The package only resolves host environment values; model-facing consumers own any rendered use.',
 }
 
 /**
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 82abd3cfc3..0e3aa509fa 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -72,6 +72,7 @@
     { "path": "./vendor/hmr" },
     { "path": "./vendor/logger-console" },
     { "path": "./packages/util/brand" },
+    { "path": "./packages/util/environment" },
     { "path": "./packages/util/native-command" },
     { "path": "./packages/util/paths" },
     { "path": "./packages/util/timeout" },

From 8c2970e70ef7aa3bcf923648e5bb06447efd74b8 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Tue, 4 Aug 2026 17:16:11 +0800
Subject: [PATCH 022/516] fix(config): trust the invoking project, and stop
 leaking what it must not decide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review found five real defects in the configuration-source work, all confirmed
against the code rather than argued:

1. The note claimed --config outranks settings.yaml. It does not: the settings
   seam registers a plugin's cordis entry config as the `base` layer and the
   user section layers over it, and the seam cannot tell a shipped value from a
   --config one. The note now states shipped reality and names --config-replace
   as the lever for a deployment that must win. Separately, a literal `apiKey`
   in settings outranked both the environment and .credentials.yaml — the field
   is removed, so configuration carries a reference and nothing else.
2. DEEPSEEK_SEARCH_BASE_URL was functionally deleted: the shipped inline went
   away without the provider learning to read it. It now resolves from the
   environment snapshot, as the README always claimed.
3. The bootstrap deny list missed the interpreter start-up hooks. BASH_ENV is
   the sharpest: `bash -c` sources it on every bash tool call, so a project
   .env could run a file of its choosing before every command. The list now
   covers BASH_ENV and its per-language siblings, the Git hook commands, and
   the remaining preload and CA variables, organised by what a variable does
   rather than which runtime owns it.
4. YAML parse errors quoted the offending source line — which in a credentials
   document is the secret — into boot stderr and the watcher's logger. Only the
   error code and position are reported now, in credentials-local and
   settings-local alike, pinned by a test that asserts the secret is absent.
5. 0600 governed only files the harness wrote. A hand-created 0644 document was
   read normally. POSIX now checks the mode before reading contents, at boot
   and on every reload; Windows has no mode to inspect and is skipped rather
   than faked.

The project a session is launched in is trusted by default, with no prompt and
no stored trust record: it may supply its own endpoint, ordinary variables, and
a key ranked below the managed store. Trust stops at the harness itself — a
discovered file still cannot set DSH_PERMISSION_MODE, PATH, BASH_ENV, or the
rest, because those take effect with no user action, before any turn, outside
the permission policy and the sandbox.
---
 ...4-configuration-source-ownership.i18n.yaml |  4 +-
 ...26-08-04-configuration-source-ownership.md | 35 ++++---
 ...08-04-configuration-source-ownership.zh.md | 37 +++++---
 docs/config-catalog.md                        |  4 +-
 .../fixtures/deepseek-defaults.cordis.yml     |  1 -
 .../headless-agent/tests/headless.snapshot.ts | 10 +-
 .../stream-json.expected.jsonl                |  4 +-
 .../credentials-local/src/index.ts            | 94 +++++++++++++++----
 .../credentials-local/tests/local.spec.ts     | 93 +++++++++++++-----
 .../tests/review-fixes.spec.ts                |  9 +-
 .../credentials-local/tests/watcher.spec.ts   | 29 +++---
 packages/llm/llm-deepseek/src/adapter.ts      |  9 +-
 packages/llm/llm-deepseek/src/index.ts        | 24 ++---
 .../llm/llm-deepseek/tests/adapter.spec.ts    | 41 +++-----
 .../llm-deepseek/tests/dynamic-config.spec.ts | 26 ++---
 .../tests/loader-composition.spec.ts          | 11 ++-
 packages/llm/llm-pi-ai/src/index.ts           |  5 +-
 .../llm-pi-ai/tests/dynamic-config.spec.ts    |  4 +-
 .../tests/loader-composition.spec.ts          |  2 +-
 .../tests/transport-recovery.spec.ts          |  4 +-
 packages/settings/settings-local/src/index.ts |  8 +-
 packages/util/environment/README.i18n.yaml    |  4 +-
 packages/util/environment/README.md           | 12 ++-
 packages/util/environment/README.zh.md        | 12 ++-
 packages/util/environment/src/index.ts        | 46 ++++++---
 .../web/web-search-deepseek/README.i18n.yaml  |  4 +-
 packages/web/web-search-deepseek/README.md    |  4 +-
 packages/web/web-search-deepseek/README.zh.md |  4 +-
 packages/web/web-search-deepseek/src/index.ts | 19 +++-
 packages/web/web-search-exa/src/index.ts      |  7 +-
 .../web/web-search-perplexity/src/index.ts    |  7 +-
 31 files changed, 366 insertions(+), 207 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 7ff8cfa74c..0bc04dc2bb 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: f19067abb899e41742f88ce6d17623bc5b82d008
-2026-08-04-configuration-source-ownership.zh.md: a5fd7c61ee71eb9ed9184c3f9c557fb1c3b951ad
+2026-08-04-configuration-source-ownership.md: 101c0e6ba4954b3fbb418b775322a9fd92c46a8c
+2026-08-04-configuration-source-ownership.zh.md: ad59f9a96e144dd5078898da57195a8bb6897451
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index f19067abb8..101c0e6ba4 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -16,24 +16,35 @@ And `!!js process.env.X` in the shipped composition made the same value reachabl
 
 ## Decision
 
-**One ordering, four kinds of source.** Every user-facing value resolves in the same order; the domains differ only in which tiers exist.
+**One ordering for non-secret values.** Every configurable value that is not itself a credential resolves in the same order; the domains differ only in which tiers exist.
 
 ```text
 explicit for this run     per-operation override, CLI argument
-> authored by deployment  --config / --config-replace
+> user settings           settings.yaml
+> composition             --config / --config-replace, shipped base
 > this launch's shell     inherited process environment
-> product-managed store   settings.yaml, .credentials.yaml
 > discovered file         $DSH_HOME/.env
-> defaults                schema default, shipped base, provider public default
+> defaults                schema default, provider public default
 ```
 
-Credentials have no deployment tier (configuration carries a reference, never a value) and no default. Endpoints have every tier. Model selection has CLI, settings, and the shipped default. The earlier proposal ranked a UI-written credential *below* the environment while ranking UI-written settings *above* it; the distinguishing fact is not the domain but who authored the file, so `.credentials.yaml` and `settings.yaml` now sit together, both under the launching shell and both over a discovered `.env`.
+Settings sit above composition because that is what the [settings seam](2026-07-28-user-settings-seam.md) does: a plugin registers its cordis entry config as the `base` layer and the user's section layers over it, and the seam cannot tell a value the shipped base set from one a `--config` overlay set — both arrive as entry config. A deployment that must pin a field against a user's stored settings therefore uses `--config-replace`, which bypasses the tree the settings base is derived from. Composition still outranks the environment, so a stale `DEEPSEEK_BASE_URL` in a shell cannot rewrite a configured endpoint.
 
-**The invoking directory's `.env` decides no credential and no route.** `EnvironmentSnapshot.getFrom(name, sources)` searches only the layers a caller names, and omitting one is a refusal rather than a demotion: the adapters ask for `['process', 'user-env']`, so no future reordering can let a project file back into a decision it was excluded from. A project `.env` remains an ordinary environment layer for ordinary variables.
+**Credentials keep a narrower, separate ordering**, and this note does not unify them:
 
-**A discovered file may not decide how the process starts.** `isBootstrapOnly` rejects, at load and before anything is materialized, any `.env` that sets a variable governing how a process launches (`PATH`, `SHELL`, `NODE_OPTIONS`, `LD_PRELOAD`, …), where code or model-visible instructions load from (the whole `DSH_*` namespace, `HOME`, `XDG_*`), or how the network is reached and trusted (proxy and CA variables). Matching is case-insensitive, so `https_proxy` is not a bypass.
+```text
+inherited process environment      (read-only, wins)
+> $DSH_HOME/.credentials.yaml      (provider-managed, writable)
+> <invocation cwd>/.env
+> $DSH_HOME/.env
+```
 
-The whole `DSH_*` namespace is denied rather than an audited subset. The harness's own switches — the permission mode, the agents home that holds model-visible skills, the bundled skill root — are exactly what a hostile project would reach for, and a switch added later must not become settable by being forgotten. There is no opt-out: an escape hatch would have to be readable from somewhere, and anything a discovered file could set is the hole itself.
+The launching environment wins because `DEEPSEEK_API_KEY=… dsh`, a CI secret, and a container `-e` are the one override an operator must be able to apply per run without editing machine state, and because it cannot be edited from inside it must be *visibly* read-only. Configuration is meant to carry only the *reference* — which name to resolve — and that name follows the non-secret ordering above.
+
+**The project the harness is launched in is trusted, by default and without a prompt.** A checkout may carry its own endpoint, its own ordinary variables, and its own key; the key ranks below the managed store, so a key stored through the web page or TUI is never displaced by one a checkout happens to contain. `EnvironmentSnapshot.getFrom(name, sources)` still searches only the layers a caller names, and omitting one is a refusal rather than a demotion — the mechanism exists for the decisions where a layer must be unreachable, not because the project is one of them today.
+
+**Trust does not extend to changing the harness itself.** `isBootstrapOnly` rejects, at load and before anything is materialized, any `.env` that sets a variable governing how a process launches (`PATH`, `SHELL`, `NODE_OPTIONS`, `LD_PRELOAD`), what code a runtime executes before the program it was asked to run (`BASH_ENV`, `PERL5OPT`, `PYTHONSTARTUP`, `RUBYOPT`, `JAVA_TOOL_OPTIONS`, the Git hook commands), where model-visible instructions load from (the whole `DSH_*` namespace, `HOME`, `XDG_*`), or how the network is reached and trusted (proxy and CA variables). Matching is case-insensitive, so `https_proxy` is not a bypass.
+
+The line is that these take effect with no user action, before any turn, outside the permission policy and the sandbox. `DSH_PERMISSION_MODE` would switch off the approvals that make trusting a project meaningful at all, and `BASH_ENV` runs a file of the project's choosing on every single `bash -c` the bash tool issues — the project's code running under the agent's policy is the deal; the project rewriting that policy is not. Enumerating these is a losing game one variable at a time, which is why the whole `DSH_*` namespace is denied rather than an audited subset, and why the list is organised by what a variable *does* rather than by which runtime owns it. There is no opt-out: an escape hatch would have to be readable from somewhere, and anything a discovered file could set is the hole itself.
 
 **`packages/util/environment` owns the snapshot**, deliberately as a utility rather than a three-package capability seam. The snapshot is frozen before Cordis starts and injected once by the launcher, so there is no runtime implementation to swap; consumers need types and pure functions, which a `util/` package gives them without depending on a UI package. `environmentOf(ctx)` returns the launcher's snapshot, or the inherited environment as the only layer — an SDK host or bare `cordis.yml` discovered no files, so its single layer really is what it was launched with, and the same trusted lookups keep working there unchanged.
 
@@ -43,16 +54,16 @@ The whole `DSH_*` namespace is denied rather than an audited subset. The harness
 
 - The web credential form now takes effect against an older key in the user's `.env`; only a key exported in the launching shell still makes it read-only, and the diagnostic says so.
 - A `.env` holding `DSH_*`, `PATH`, or a proxy variable fails the launch instead of being applied. Developers keeping switches in a repository `.env` move them to their shell — a deliberate, loud break.
-- `--config` is no longer overridable by a stale shell endpoint, so a deployment can pin an enterprise gateway.
-- Given up: an endpoint or key in the invoking directory's `.env` no longer applies. Per-project routing is a `--config` overlay or an `export` in that project's shell.
+- `--config` is no longer overridable by a stale shell endpoint. It is still overridable by a user's stored `settings.yaml`, which is the settings seam's layering and not something this note changes; a deployment that must win against stored settings uses `--config-replace`.
 - Not solved: the layers are still materialized into `process.env`, so ordinary project variables continue to reach child processes under the subprocess scrub. Bootstrap variables cannot come from a file at all, which closes the escalation path; a project `.env` setting something like `GIT_SSH_COMMAND` for the tools an agent runs remains possible and is recorded as a limitation on the package.
+- The adapters no longer accept a literal `apiKey`: configuration carries the reference and nothing else, so a settings document cannot become a second credential store. No adapter namespace is strict, so writing one is dropped rather than rejected.
 - Exa and Perplexity still capture their key at load time rather than through the credential seam. They no longer read raw `process.env` — they resolve through the trusted layers — but converting them to per-request seam resolution is separate work.
 
 ## Alternatives considered
 
-**Keep the proposal's split ladders (credentials env-over-file, endpoints settings-over-env).** Rejected on its own inconsistency: both arguments — "an export is this run's intent" and "a deployment's file should not be rewritten by a stale shell" — apply to both domains. Sorting by *who authored the source* explains both and produces one table instead of four.
+**Unify credentials into the non-secret ordering, by who authored each source.** Attempted and abandoned: it reads well, but the settings seam already fixes composition *below* the user section, so "authored by deployment" is not a tier the seam can express — and moving `.credentials.yaml` above the launching environment would take away the one override CI, containers, and a per-run `DEEPSEEK_API_KEY=…` depend on. Two orderings that each say why they are shaped that way beat one that describes neither accurately.
 
-**Let the invoking directory's `.env` supply a credential, ranked below the managed store.** Rejected: with no key stored, a hostile project's key would be used silently, and the account holder reads every prompt sent under it. That is the same exfiltration the endpoint rule exists to prevent, so it takes the same answer.
+**Withhold routing and credentials from the invoking project until it is explicitly trusted.** Rejected as the product's stance: a checkout is trusted by default, with no prompt and no stored trust record. The residual is real and worth naming — cloning a repository that carries a `.env` naming another endpoint or key routes that session through it — and a later project-trust gate is where that gets addressed, not a rule that makes the common case require ceremony.
 
 **Audit an allowlist of `DSH_*` variables a `.env` may set.** Rejected: the list would have to be re-audited on every new switch, and the failure mode of forgetting is silent. Denying the namespace fails safe.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index a5fd7c61ee..ad59f9a96e 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -16,26 +16,37 @@ endpoint 可以被项目重定向。调用目录的 `.env` 和其他层一样会
 
 ## Decision
 
-**一条顺序，四类来源。** 每个面向用户的值按同一顺序解析；各领域的差别只在于哪些层存在。
+**非密钥值走同一条顺序。** 每个本身不是凭据的可配置值都按同一顺序解析；各领域的差别只在于哪些层存在。
 
 ```text
 explicit for this run     per-operation override, CLI argument
-> authored by deployment  --config / --config-replace
+> user settings           settings.yaml
+> composition             --config / --config-replace, shipped base
 > this launch's shell     inherited process environment
-> product-managed store   settings.yaml, .credentials.yaml
 > discovered file         $DSH_HOME/.env
-> defaults                schema default, shipped base, provider public default
+> defaults                schema default, provider public default
 ```
 
-自上而下依次是：本次运行的显式意图、部署授权、本次启动的 shell、产品受管存储、被发现的文件、默认值。
+自上而下依次是：本次运行的显式意图、用户 settings、composition、本次启动的 shell、被发现的文件、默认值。
 
-凭据没有部署层（配置携带引用，从不携带值），也没有默认值层。endpoint 拥有全部层。模型选择只有 CLI、settings 与已交付默认值。此前的方案把 UI 写入的凭据排在环境*之下*，却把 UI 写入的 settings 排在环境*之上*；真正的区分依据不是领域，而是这个文件由谁书写，因此 `.credentials.yaml` 与 `settings.yaml` 现在并列，同在启动 shell 之下、同在被发现的 `.env` 之上。
+settings 在 composition 之上，因为 [settings seam](2026-07-28-user-settings-seam.md) 就是这么做的：插件把自己的 cordis entry config 注册为 `base` 层，用户 section 叠加其上，而 seam 无法区分某个值是交付基座设的还是 `--config` overlay 设的——两者都以 entry config 的形式抵达。因此，需要把某字段钉死、不被用户已存 settings 覆盖的部署方，应使用 `--config-replace`，它绕过了 settings base 所派生的那棵树。composition 仍然高于环境，所以 shell 里陈旧的 `DEEPSEEK_BASE_URL` 无法改写已配置的 endpoint。
 
-**调用目录的 `.env` 不决定任何凭据与路由。** `EnvironmentSnapshot.getFrom(name, sources)` 只搜索调用方点名的层，省略某层是拒绝而不是降级：适配器请求的是 `['process', 'user-env']`，因此后续任何重新排序都无法让项目文件重新进入一个它被排除在外的决策。对普通变量而言，项目 `.env` 仍然是普通环境层。
+**凭据保留一条更窄的独立顺序**，本 Note 不把它并入上表：
 
-**被发现的文件不得决定进程如何启动。** `isBootstrapOnly` 会在加载时、且在物化任何内容之前，拒绝任何设置了下列变量的 `.env`：决定进程如何启动的（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD` 等）、决定代码或模型可见指令从哪里加载的（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），以及决定网络如何抵达与信任的（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
+```text
+inherited process environment      (read-only, wins)
+> $DSH_HOME/.credentials.yaml      (provider-managed, writable)
+> <invocation cwd>/.env
+> $DSH_HOME/.env
+```
 
-被拒绝的是整个 `DSH_*` 命名空间，而不是一份经过审查的子集。harness 自己的开关——权限模式、存放模型可见 skill（技能）的 agents home、内置 skill 根目录——恰恰是敌意项目最想伸手的地方，而后来新增的开关不能因为被遗忘就变得可设置。不设逃生门：逃生门本身总得从某处读取，而任何被发现的文件能设置的东西，就是那个漏洞本身。
+继承环境优先，因为 `DEEPSEEK_API_KEY=… dsh`、CI 机密与容器 `-e` 是运维必须能按次施加、且无需改动机器状态的那一种覆盖；而它无法从进程内部修改，就必须*可见地*只读。配置本应只携带*引用*——解析哪个名字——该名字本身遵循上面的非密钥顺序。
+
+**harness 被启动于其中的项目默认可信，且不做询问。** 一个 checkout 可以携带自己的 endpoint、自己的普通变量和自己的密钥；密钥排在受管存储之下，因此通过 Web 页面或 TUI 存下的密钥绝不会被 checkout 中恰好带有的那一个顶掉。`EnvironmentSnapshot.getFrom(name, sources)` 仍然只搜索调用方点名的层，省略某层仍是拒绝而不是降级——该机制是为「某一层必须不可达」的那些决策准备的，而项目层今天不在其列。
+
+**信任不延伸到改变 harness 本身。** `isBootstrapOnly` 会在加载时、且在物化任何内容之前，拒绝任何设置了下列变量的 `.env`：决定进程如何启动的（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD`）、决定运行时在执行被要求运行的程序之前先执行哪些代码的（`BASH_ENV`、`PERL5OPT`、`PYTHONSTARTUP`、`RUBYOPT`、`JAVA_TOOL_OPTIONS`、Git 的钩子命令）、决定模型可见指令从哪里加载的（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），以及决定网络如何抵达与信任的（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
+
+这条界线在于：它们无需任何用户动作、在任何一轮开始之前、且在权限策略与沙箱之外就生效。`DSH_PERMISSION_MODE` 会关掉让「信任项目」根本成立的那道审批，而 `BASH_ENV` 会在 bash 工具发出的每一次 `bash -c` 上执行项目指定的文件——项目的代码在 agent 的策略下运行是约定，项目改写那份策略不是。一个变量一个变量地枚举是必输的游戏，所以整个 `DSH_*` 命名空间被拒绝而不是只拒绝一份经审查的子集，也所以这份清单是按变量*做什么*而不是按哪个运行时拥有它来组织的。不设逃生门：逃生门本身总得从某处读取，而任何被发现的文件能设置的东西，就是那个漏洞本身。
 
 **`packages/util/environment` 拥有该快照**，刻意做成 utility 而不是三包能力 seam。快照在 Cordis 启动前就冻结，并由启动器一次性注入，因此不存在需要切换的运行时实现；消费方需要的只是类型和纯函数，而 `util/` 包能提供这些且不必依赖 UI 包。`environmentOf(ctx)` 返回启动器的快照，或者返回只含继承环境的那一层——SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，它那唯一一层确实就是它被启动时的环境，因此同样的受信查询在那里原样继续工作。
 
@@ -45,16 +56,16 @@ explicit for this run     per-operation override, CLI argument
 
 - Web 凭据表单现在能压过用户 `.env` 里更旧的密钥；只有在启动 shell 里 export 的密钥才会让它变成只读，诊断信息也会这么说。
 - 含 `DSH_*`、`PATH` 或 proxy 变量的 `.env` 会导致启动失败而不是被应用。把开关放在仓库 `.env` 里的开发者需要改放到 shell——这是一次刻意且响亮的破坏。
-- `--config` 不再会被陈旧的 shell endpoint 覆盖，因此部署方可以钉住企业网关。
-- 放弃的：调用目录 `.env` 里的 endpoint 或密钥不再生效。按项目切换路由请用 `--config` overlay 或该项目 shell 里的 `export`。
+- `--config` 不再会被陈旧的 shell endpoint 覆盖。但它仍然会被用户已存的 `settings.yaml` 覆盖，这是 settings seam 的分层方式，本 Note 不改变它；需要压过已存 settings 的部署方应使用 `--config-replace`。
 - 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件，提权路径已封闭；项目 `.env` 为 agent 运行的工具设置诸如 `GIT_SSH_COMMAND` 之类的变量仍然可能，已作为限制记录在该包上。
+- 适配器不再接受字面 `apiKey`：配置只携带引用，因此 settings 文档无法成为第二个凭据存储。由于没有任何适配器 namespace 是 strict 的，写入该键会被 schema 丢弃而不是报错。
 - Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求经 seam 解析是另一件事。
 
 ## Alternatives considered
 
-**沿用方案里分开的两条 ladder（凭据环境压过文件、endpoint settings 压过环境）。** 因其自身的不自洽而否决：两条理由——「export 是本次运行的意图」和「部署方的文件不该被陈旧 shell 改写」——对两个领域同样成立。按*来源由谁书写*排序能同时解释两者，并且把四张表变成一张。
+**按「来源由谁书写」把凭据并入非密钥顺序。** 尝试过并放弃：它读起来很顺，但 settings seam 已经把 composition 固定在用户 section *之下*，因此「部署授权」根本不是该 seam 能表达的一层；而把 `.credentials.yaml` 抬到启动环境之上，会夺走 CI、容器和一次性 `DEEPSEEK_API_KEY=…` 所依赖的那唯一一种覆盖。两条各自说清自身形状成因的顺序，好过一条两边都描述不准的顺序。
 
-**允许调用目录 `.env` 提供凭据，排在受管存储之下。** 否决：在没有存储密钥时，敌意项目的密钥会被静默使用，而该账号持有者能读到以它发出的每一条提示词。这与 endpoint 规则要防的外泄是同一件事，因此答案也相同。
+**在项目被显式信任之前，不给它路由与凭据能力。** 作为产品立场被否决：checkout 默认可信，不询问，也不存储信任记录。残留风险是真实的、值得写明——克隆一个携带 `.env`、其中指定了另一个 endpoint 或密钥的仓库，会让该会话经由它——处理它的地方是日后的 project trust 门禁，而不是一条让常见情形都要走仪式的规则。
 
 **审查出一份 `.env` 可设置的 `DSH_*` 白名单。** 否决：每新增一个开关都要重新审查，而遗漏的失败模式是静默的。拒绝整个命名空间是 fail safe。
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 44888f182a..9240454926 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -423,7 +423,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
+Source: [`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-fs-local`
 
@@ -628,8 +628,6 @@ Requires: `llm`
  * reasoning effort resolves to `high`.
  */
 export interface Config {
-  /** Literal API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
-  apiKey?: string
   /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
   apiKeyEnv?: string
   /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */
diff --git a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
index cd472f737d..c501901604 100644
--- a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
@@ -5,7 +5,6 @@
     patches:
       - id: llm-deepseek
         config:
-          apiKey: snapshot-key
           baseURL: !!js process.env.DSH_SNAPSHOT_BASE_URL
           thinking: disabled
       - id: cli-agent
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 8b48165a83..29493b307a 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -244,13 +244,12 @@ describe('headless stream-json snapshots', () => {
       prepare: (cwd) => { runCwd = cwd },
     })
 
-    // The guidance leads with the credential store — the path that keeps the
-    // secret out of configuration files — and offers a literal key last.
+    // The guidance names both places a credential can come from, and nothing
+    // else: configuration carries the reference, never a literal key.
     expect(result.stderr).toBe(
       'dsh-cli-demo: turn 1 failed at step 1: llm-deepseek: no API key for provider route "deepseek-official";'
       + ' store DEEPSEEK_API_KEY through the credentials service (the web Models page writes it),'
-      + ' export DEEPSEEK_API_KEY in the launching environment, or — as a last resort — set a literal'
-      + ' "apiKey" in the llm-deepseek settings section\n',
+      + ' or export DEEPSEEK_API_KEY in the launching environment\n',
     )
     const normalized = normalizeHeadlessStream(result.stdout, runCwd)
     if (refreshing) await writeFile(streamExpected, normalized)
@@ -314,6 +313,9 @@ describe('headless stream-json snapshots', () => {
         ],
         tsconfigPath,
         env: {
+          // Configuration carries only the reference; the key rides the
+          // launching environment, which is the whole credential plane here.
+          DEEPSEEK_API_KEY: 'snapshot-key',
           DSH_SNAPSHOT_BASE_URL: server.url,
           NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
         },
diff --git a/examples/headless-agent/tests/snapshots/missing-credential/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/missing-credential/stream-json.expected.jsonl
index 4f3bcd2321..2ca5c63dc9 100644
--- a/examples/headless-agent/tests/snapshots/missing-credential/stream-json.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/missing-credential/stream-json.expected.jsonl
@@ -5,5 +5,5 @@
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/context","seq":5,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":1000000}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":6,"time":0,"data":{"turn":1,"step":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":7,"time":0,"data":{"turn":1,"reason":{"kind":"error","step":1,"failure":{"message":"llm-deepseek: no API key for provider route \"deepseek-official\"; store DEEPSEEK_API_KEY through the credentials service (the web Models page writes it), export DEEPSEEK_API_KEY in the launching environment, or — as a last resort — set a literal \"apiKey\" in the llm-deepseek settings section","code":"MISSING_CREDENTIAL"}}}}}
-{"type":"result","success":false,"sessionId":"{{sessionId}}","turn":1,"result":"","reason":{"kind":"error","step":1,"failure":{"message":"llm-deepseek: no API key for provider route \"deepseek-official\"; store DEEPSEEK_API_KEY through the credentials service (the web Models page writes it), export DEEPSEEK_API_KEY in the launching environment, or — as a last resort — set a literal \"apiKey\" in the llm-deepseek settings section","code":"MISSING_CREDENTIAL"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":7,"time":0,"data":{"turn":1,"reason":{"kind":"error","step":1,"failure":{"message":"llm-deepseek: no API key for provider route \"deepseek-official\"; store DEEPSEEK_API_KEY through the credentials service (the web Models page writes it), or export DEEPSEEK_API_KEY in the launching environment","code":"MISSING_CREDENTIAL"}}}}}
+{"type":"result","success":false,"sessionId":"{{sessionId}}","turn":1,"result":"","reason":{"kind":"error","step":1,"failure":{"message":"llm-deepseek: no API key for provider route \"deepseek-official\"; store DEEPSEEK_API_KEY through the credentials service (the web Models page writes it), or export DEEPSEEK_API_KEY in the launching environment","code":"MISSING_CREDENTIAL"}}}
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index 6d5db0776f..1f0f550c05 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -3,9 +3,10 @@
  * against the environment by how much each layer is trusted:
  *
  * ```text
- * inherited process environment  (read-only, wins)
- * > $DSH_HOME/.credentials.yaml  (provider-managed, writable)
- * > $DSH_HOME/.env               (read-only fallback)
+ * inherited process environment      (read-only, wins)
+ * > $DSH_HOME/.credentials.yaml      (provider-managed, writable)
+ * > <invocation cwd>/.env            (read-only fallback)
+ * > $DSH_HOME/.env                   (read-only fallback)
  * ```
  *
  * The inherited environment wins because `DEEPSEEK_API_KEY=… dsh`, a CI
@@ -15,10 +16,10 @@
  * web page or TUI writes takes effect immediately even when an older key sits
  * in the user's `.env`.
  *
- * The invoking directory's `.env` supplies no credential at all. A project
- * directory can be written by the model, and a substituted key would send
- * every request — prompts included — through an account someone else reads;
- * that decision belongs to the launching shell, not to a discovered file.
+ * The invoking project may supply a key, because the product trusts the
+ * project it is launched in. It ranks below the managed store, so a key stored
+ * through the web page or TUI is never displaced by one a checkout happens to
+ * carry.
  *
  * The file is the provider-managed writable source: every write re-reads the
  * document under a cross-process writer lock before patching only its own key
@@ -37,7 +38,7 @@
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import { watch as chokidarWatch } from 'chokidar'
-import { mkdir, readFile } from 'node:fs/promises'
+import { mkdir, readFile, stat } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { Document, parseDocument } from 'yaml'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
@@ -83,11 +84,56 @@ export function resolveSpec(config: Config): ResolvedSpec {
   }
 }
 
+/** Permission bits outside the owner; a credentials document must have none of them. */
+const GROUP_OTHER_BITS = 0o077
+
+/**
+ * Reject a credentials document other OS users can read, before its contents
+ * are read at all. The provider creates and replaces the file at `0600`, but a
+ * hand-written or externally generated one carries whatever umask produced it,
+ * and silently serving secrets out of a world-readable file would make the
+ * mode the provider promises meaningless.
+ *
+ * POSIX only: Windows has no mode to inspect — its ACLs are not expressible
+ * here — so the check is skipped rather than faked, and the file's protection
+ * there is whatever the create and replace APIs express.
+ * @param filename - absolute path of the document.
+ * @throws when the file exists with group or other permission bits set.
+ */
+async function assertOwnerOnly(filename: string): Promise<void> {
+  if (process.platform === 'win32') return
+  let mode: number
+  try {
+    mode = (await stat(filename)).mode
+  } catch (error) {
+    if (!isENOENT(error)) throw error
+    return
+  }
+  const offending = mode & GROUP_OTHER_BITS
+  if (offending === 0) return
+  throw new Error(
+    `credentials-local: ${filename} is readable beyond its owner (mode ${(mode & 0o777).toString(8)});`
+    + ` run "chmod 600 ${filename}" before starting again`,
+  )
+}
+
 /** Whether a filesystem error means absence; every non-ENOENT failure must surface. */
 function isENOENT(error: unknown): boolean {
   return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT'
 }
 
+/**
+ * Describe one YAML parse failure without quoting the source. The parser's own
+ * message embeds the offending line, which here holds a secret.
+ * @param error - the parser's error.
+ * @returns the error code with its line and column.
+ */
+function describeYamlError(error: { code?: string; linePos?: [{ line: number; col: number }, ...unknown[]] }): string {
+  const at = error.linePos?.[0]
+  const where = at === undefined ? '' : ` at line ${String(at.line)}, column ${String(at.col)}`
+  return `${error.code ?? 'YAML_ERROR'}${where}`
+}
+
 /**
  * Parse one credentials document into its entries. The document is a strict
  * mapping of {@link CredentialRef} to non-empty string: a non-mapping root, a
@@ -101,10 +147,15 @@ function isENOENT(error: unknown): boolean {
  * @returns the parsed entries, keyed by reference.
  */
 export function parseCredentialsDocument(text: string, filename: string): Map<string, string> {
+  // `prettyErrors` is on only for `linePos`; `error.message` is never used,
+  // because the parser quotes the offending source line and in this document
+  // that line is a secret. Only the code and position leave this function, and
+  // the same rule governs every other diagnostic here — a key name is safe to
+  // print, a value is not.
   const document = parseDocument(text, { prettyErrors: true, uniqueKeys: true })
   if (document.errors.length > 0) {
     throw new Error(`credentials-local: invalid document at ${filename}: ${
-      document.errors.map(error => error.message).join('; ')}`)
+      document.errors.map(describeYamlError).join('; ')}`)
   }
   const root: unknown = document.toJS() ?? {}
   if (typeof root !== 'object' || root === null || Array.isArray(root)) {
@@ -116,6 +167,8 @@ export function parseCredentialsDocument(text: string, filename: string): Map<st
     // is exactly the constraint a stored reference must satisfy to be
     // addressable through the seam.
     credentialRef(key)
+    // The key name is quoted, never the value: a wrong-typed entry is still a
+    // secret the user meant to store.
     if (typeof value !== 'string') {
       throw new TypeError(`credentials-local: the value for "${key}" in ${filename} must be a string`)
     }
@@ -194,9 +247,13 @@ export class CredentialsLocal extends Credentials {
     return entry !== undefined && entry.value.length > 0 ? entry.value : undefined
   }
 
-  /** The user `.env` fallback for a reference — below the managed store, never above it. */
-  private userEnvFallback(ref: CredentialRef): EnvironmentEntry | undefined {
-    const entry = environmentOf(this.ctx).getFrom(ref, ['user-env'])
+  /**
+   * The `.env` fallback for a reference — below the managed store, never above
+   * it. The invoking project ranks over the user's home file, matching the
+   * environment layering: the more specific location wins.
+   */
+  private dotenvFallback(ref: CredentialRef): EnvironmentEntry | undefined {
+    const entry = environmentOf(this.ctx).getFrom(ref, ['project-env', 'user-env'])
     return entry !== undefined && entry.value.length > 0 ? entry : undefined
   }
 
@@ -249,8 +306,8 @@ export class CredentialsLocal extends Credentials {
     if (inherited !== undefined) return Promise.resolve({ value: inherited, source: 'env' })
     const stored = this.values.get(ref)
     if (stored !== undefined) return Promise.resolve({ value: stored, source: 'file' })
-    const fallback = this.userEnvFallback(ref)
-    if (fallback !== undefined) return Promise.resolve({ value: fallback.value, source: 'user-env' })
+    const fallback = this.dotenvFallback(ref)
+    if (fallback !== undefined) return Promise.resolve({ value: fallback.value, source: fallback.source })
     return Promise.resolve(undefined)
   }
 
@@ -263,9 +320,8 @@ export class CredentialsLocal extends Credentials {
     }
     const stored = this.values.get(ref)
     if (stored !== undefined) return Promise.resolve({ configured: true, source: 'file', writable: true })
-    if (this.userEnvFallback(ref) !== undefined) {
-      return Promise.resolve({ configured: true, source: 'user-env', writable: true })
-    }
+    const fallback = this.dotenvFallback(ref)
+    if (fallback !== undefined) return Promise.resolve({ configured: true, source: fallback.source, writable: true })
     return Promise.resolve({ configured: false, writable: true })
   }
 
@@ -361,6 +417,7 @@ export class CredentialsLocal extends Credentials {
    * cannot be trusted must never be treated as "no credentials stored".
    */
   private async loadInitial(): Promise<void> {
+    await assertOwnerOnly(this.spec.filename)
     let text: string
     try {
       text = await readFile(this.spec.filename, 'utf8')
@@ -401,6 +458,9 @@ export class CredentialsLocal extends Credentials {
    * overwriting a document it could not understand.
    */
   private async reconcileFromDisk(): Promise<void> {
+    // Re-checked on every reload and before every write: an external editor or
+    // a restored backup can loosen the mode after boot.
+    await assertOwnerOnly(this.spec.filename)
     let text: string | undefined
     try {
       text = await readFile(this.spec.filename, 'utf8')
diff --git a/packages/credentials/credentials-local/tests/local.spec.ts b/packages/credentials/credentials-local/tests/local.spec.ts
index abc3521111..7a8b8fdc17 100644
--- a/packages/credentials/credentials-local/tests/local.spec.ts
+++ b/packages/credentials/credentials-local/tests/local.spec.ts
@@ -8,6 +8,11 @@ import { createEnvironmentSnapshot, DSH_ENVIRONMENT_KEY } from '@deepseek-ai/dsh
 import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
 import { CredentialsLocal, resolveSpec } from '../src/index.ts'
 
+/** Credential documents are seeded owner-only, exactly as the provider creates them. */
+function writeCredentials(file: string, text: string): Promise<void> {
+  return writeFile(file, text, { mode: 0o600 })
+}
+
 const KEY = credentialRef('DSH_CRED_TEST')
 const OTHER = credentialRef('DSH_CRED_OTHER')
 
@@ -65,7 +70,7 @@ describe('layering and reads', () => {
   it('serves file entries alongside comments and quoted values', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, '# notes\nDSH_CRED_TEST: plain\nDSH_CRED_OTHER: "with space"\n')
+    await writeCredentials(path, '# notes\nDSH_CRED_TEST: plain\nDSH_CRED_OTHER: "with space"\n')
     const ctx = await boot({ path, watch: false })
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'plain', source: 'file' })
     expect(await ctx.credentials.resolve(OTHER)).toEqual({ value: 'with space', source: 'file' })
@@ -75,7 +80,7 @@ describe('layering and reads', () => {
   it('lets a non-empty process environment win read-only over the file', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_TEST: from-file\n')
+    await writeCredentials(path, 'DSH_CRED_TEST: from-file\n')
     const ctx = await boot({ path, watch: false })
     vi.stubEnv('DSH_CRED_TEST', 'from-env')
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'from-env', source: 'env' })
@@ -85,7 +90,7 @@ describe('layering and reads', () => {
   it('treats an empty environment value as absent, falling through to the file', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_TEST: stored\n')
+    await writeCredentials(path, 'DSH_CRED_TEST: stored\n')
     const ctx = await boot({ path, watch: false })
     vi.stubEnv('DSH_CRED_TEST', '')
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'stored', source: 'file' })
@@ -119,7 +124,7 @@ describe('layer ladder', () => {
   it('lets the stored value beat the user .env, so a UI write takes effect immediately', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_TEST: stored\n')
+    await writeCredentials(path, 'DSH_CRED_TEST: stored\n')
     const ctx = await bootLayered(path, [
       { source: 'process', values: {} },
       { source: 'user-env', path: '/home/.dsh/.env', values: { DSH_CRED_TEST: 'older-user-env' } },
@@ -143,22 +148,41 @@ describe('layer ladder', () => {
     expect(await ctx.credentials.describe(KEY)).toEqual({ configured: true, source: 'user-env', writable: true })
   })
 
-  it('ignores the invoking directory .env entirely', async () => {
+  it('serves the invoking project .env over the user one, but never over the store', async () => {
     const dir = await tempDir()
-    const ctx = await bootLayered(join(dir, '.credentials.yaml'), [
-      { source: 'process', values: {} },
-      { source: 'project-env', path: '/work/.env', values: { DSH_CRED_TEST: 'from-project' } },
-    ])
-    // A project directory can be written by the model, and a substituted key
-    // would route every request through an account someone else reads.
-    expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
-    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: false, writable: true })
+    const path = join(dir, '.credentials.yaml')
+    // The product trusts the project it is launched in, so a checkout may
+    // carry its own key — ranked above the user's home file (more specific
+    // wins) and below the managed store, which a stored key must never lose to.
+    const layers = [
+      { source: 'process' as const, values: {} },
+      { source: 'project-env' as const, path: '/work/.env', values: { DSH_CRED_TEST: 'from-project' } },
+      { source: 'user-env' as const, path: '/home/.dsh/.env', values: { DSH_CRED_TEST: 'from-user' } },
+    ]
+    const bare = await bootLayered(path, layers)
+    expect(await bare.credentials.resolve(KEY)).toEqual({ value: 'from-project', source: 'project-env' })
+    expect(await bare.credentials.describe(KEY)).toEqual({ configured: true, source: 'project-env', writable: true })
+
+    await writeCredentials(path, 'DSH_CRED_TEST: stored\n')
+    const stored = await bootLayered(path, layers)
+    expect(await stored.credentials.resolve(KEY)).toEqual({ value: 'stored', source: 'file' })
+  })
+
+  it('refuses a document other OS users can read', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    await writeFile(path, 'DSH_CRED_TEST: leaked\n', { mode: 0o644 })
+    const ctx = new Context()
+    // Before the contents are read at all: serving secrets out of a
+    // world-readable file would make the 0600 the provider writes meaningless.
+    await expect(ctx.plugin(CredentialsLocal, { path, watch: false }))
+      .rejects.toThrow(/readable beyond its owner \(mode 644\)/)
   })
 
   it('lets only the inherited environment shadow the store, read-only', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_TEST: stored\n')
+    await writeCredentials(path, 'DSH_CRED_TEST: stored\n')
     const ctx = await bootLayered(path, [
       { source: 'process', values: { DSH_CRED_TEST: 'from-shell' } },
       { source: 'user-env', path: '/home/.dsh/.env', values: { DSH_CRED_TEST: 'from-user-env' } },
@@ -184,15 +208,36 @@ describe('document validation', () => {
   ])('fails boot on %s', async (_case, text, message) => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, text)
+    await writeCredentials(path, text)
     const ctx = new Context()
     await expect(ctx.plugin(CredentialsLocal, { path, watch: false })).rejects.toThrow(message)
   })
 
+  it('never puts a credential value in a diagnostic', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    const secret = 'sk-live-DO-NOT-LOG-abcdef123456'
+    // The yaml parser's own message quotes the offending source line, which in
+    // this document is the secret itself. Boot stderr and the watcher's logger
+    // both receive whatever this throws.
+    await writeCredentials(path, `DSH_CRED_TEST: "${secret}\n`)
+    let failure: unknown
+    try {
+      await new Context().plugin(CredentialsLocal, { path, watch: false })
+    } catch (error) {
+      failure = error
+    }
+    expect(String(failure)).toMatch(/invalid document/)
+    // The position survives; the line's contents do not.
+    expect(String(failure)).toMatch(/line 2, column 1/)
+    expect(String(failure)).not.toContain(secret)
+    expect((failure as Error).stack ?? '').not.toContain(secret)
+  })
+
   it('reads an empty document as an empty store', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, '# nothing stored yet\n')
+    await writeCredentials(path, '# nothing stored yet\n')
     const ctx = await boot({ path, watch: false })
     expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
   })
@@ -214,7 +259,7 @@ describe('document writes', () => {
   it('patches one entry, preserving comments and every untouched entry', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, '# deployment notes\nDSH_CRED_OTHER: keep\n\n# the one under edit\nDSH_CRED_TEST: old\n')
+    await writeCredentials(path, '# deployment notes\nDSH_CRED_OTHER: keep\n\n# the one under edit\nDSH_CRED_TEST: old\n')
     const ctx = await boot({ path, watch: false })
     await ctx.credentials.set(KEY, 'new value!')
     expect(await readFile(path, 'utf8')).toBe(
@@ -242,7 +287,7 @@ describe('document writes', () => {
     // Comments above an entry are that entry's annotation and go with it when
     // it is removed — including anything above the document's first entry.
     // Every other entry keeps its own comments.
-    await writeFile(path, '# about the doomed one\nDSH_CRED_TEST: gone\n# about the survivor\nDSH_CRED_OTHER: stays\n')
+    await writeCredentials(path, '# about the doomed one\nDSH_CRED_TEST: gone\n# about the survivor\nDSH_CRED_OTHER: stays\n')
     const ctx = await boot({ path, watch: false })
     const seen = updates(ctx)
     await ctx.credentials.unset(KEY)
@@ -254,7 +299,7 @@ describe('document writes', () => {
   it('rejects empty values and writes the environment would shadow', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_TEST: stored\n')
+    await writeCredentials(path, 'DSH_CRED_TEST: stored\n')
     const ctx = await boot({ path, watch: false })
 
     await expect(ctx.credentials.set(KEY, '')).rejects.toThrow(/empty value/)
@@ -267,7 +312,7 @@ describe('document writes', () => {
   it('leaves an empty mapping after unsetting the only entry', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_TEST: only\n')
+    await writeCredentials(path, 'DSH_CRED_TEST: only\n')
     const ctx = await boot({ path, watch: false })
     await ctx.credentials.unset(KEY)
     expect(await readFile(path, 'utf8')).toBe('{}\n')
@@ -282,7 +327,7 @@ describe('document writes', () => {
     const ctx = await boot({ path, watch: false })
     // An external editor left the document unparsable: the read-modify-write
     // must refuse rather than overwrite content it cannot understand.
-    await writeFile(path, 'DSH_CRED_TEST: "unterminated\n')
+    await writeCredentials(path, 'DSH_CRED_TEST: "unterminated\n')
     await expect(ctx.credentials.set(OTHER, 'lands')).rejects.toThrow(/invalid document/)
   })
 
@@ -326,17 +371,17 @@ describe('real hot reload', () => {
     const path = join(dir, '.credentials.yaml')
     // Watching starts on an existing document: creation racing watcher setup
     // is a chokidar readiness gap, not the reload contract under test.
-    await writeFile(path, 'DSH_CRED_TEST: boot\n')
+    await writeCredentials(path, 'DSH_CRED_TEST: boot\n')
     const ctx = await boot({ path, debounceMs: 10 })
     const seen = updates(ctx)
 
-    await writeFile(path, 'DSH_CRED_TEST: live\nDSH_CRED_OTHER: extra\n')
+    await writeCredentials(path, 'DSH_CRED_TEST: live\nDSH_CRED_OTHER: extra\n')
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'live', source: 'file' })
     })
 
     // Wholesale replacement: an entry deleted on disk never lingers in memory.
-    await writeFile(path, 'DSH_CRED_TEST: live\n')
+    await writeCredentials(path, 'DSH_CRED_TEST: live\n')
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(OTHER)).toBeUndefined()
     })
diff --git a/packages/credentials/credentials-local/tests/review-fixes.spec.ts b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
index 7d2f447e5a..fcec7fceb9 100644
--- a/packages/credentials/credentials-local/tests/review-fixes.spec.ts
+++ b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
@@ -10,6 +10,11 @@ import { join } from 'node:path'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import { CredentialsLocal } from '../src/index.ts'
 
+/** Credential documents are seeded owner-only, exactly as the provider creates them. */
+function writeCredentials(file: string, text: string): Promise<void> {
+  return writeFile(file, text, { mode: 0o600 })
+}
+
 const ALPHA = credentialRef('DSH_REVIEW_ALPHA')
 const BETA = credentialRef('DSH_REVIEW_BETA')
 const INNER = credentialRef('DSH_REVIEW_INNER')
@@ -44,7 +49,7 @@ describe('read-modify-write', () => {
     await ctx.credentials.set(ALPHA, 'one')
     // The external edit has landed on disk but no watcher reported it (watch
     // is off — the same blind spot as a debounce window or a missed event).
-    await writeFile(path, `${ALPHA}: one\n${BETA}: external\n`)
+    await writeCredentials(path, `${ALPHA}: one\n${BETA}: external\n`)
     await ctx.credentials.set(ALPHA, 'two')
     const text = await readFile(path, 'utf8')
     expect(text).toContain(`${BETA}: external`)
@@ -124,7 +129,7 @@ describe('document editor', () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
     const wrapped = `DSH_REVIEW_WRAPPED: |-\n  line1\n  line2\n${ALPHA}: a\n`
-    await writeFile(path, wrapped)
+    await writeCredentials(path, wrapped)
     const ctx = await boot({ path, watch: false })
     await ctx.credentials.set(ALPHA, 'b')
     expect(await readFile(path, 'utf8')).toBe(`DSH_REVIEW_WRAPPED: |-\n  line1\n  line2\n${ALPHA}: b\n`)
diff --git a/packages/credentials/credentials-local/tests/watcher.spec.ts b/packages/credentials/credentials-local/tests/watcher.spec.ts
index 8f34b09868..8c216e6976 100644
--- a/packages/credentials/credentials-local/tests/watcher.spec.ts
+++ b/packages/credentials/credentials-local/tests/watcher.spec.ts
@@ -6,6 +6,11 @@ import { join } from 'node:path'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import { CredentialsLocal } from '../src/index.ts'
 
+/** Credential documents are seeded owner-only, exactly as the provider creates them. */
+function writeCredentials(file: string, text: string): Promise<void> {
+  return writeFile(file, text, { mode: 0o600 })
+}
+
 // chokidar is the nondeterministic OS boundary: faking it lets these tests
 // drive the event pipeline (error events, races with unreadable files)
 // deterministically. Real end-to-end watching stays covered by local.spec.ts.
@@ -80,7 +85,7 @@ describe('watcher pipeline', () => {
     instance!.watcher.emit('error', new Error('watch backend failure'))
     expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
 
-    await writeFile(path, 'DSH_CRED_PIPE: arrived\n')
+    await writeCredentials(path, 'DSH_CRED_PIPE: arrived\n')
     instance!.watcher.emit('all', 'change', path)
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'arrived', source: 'file' })
@@ -90,7 +95,7 @@ describe('watcher pipeline', () => {
   it('keeps the last good snapshot when the file turns unreadable at runtime', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_PIPE: good\n')
+    await writeCredentials(path, 'DSH_CRED_PIPE: good\n')
     const ctx = await boot({ path, debounceMs: 5 })
 
     await chmod(path, 0o000)
@@ -113,7 +118,7 @@ describe('watcher pipeline', () => {
     })
     const [instance] = await fakeInstances()
 
-    await writeFile(path, 'DSH_CRED_PIPE: first\n')
+    await writeCredentials(path, 'DSH_CRED_PIPE: first\n')
     instance!.watcher.emit('all', 'change', path)
     // The snapshot commits before the fan-out, so the value lands even though
     // the listener threw out of the refresh.
@@ -122,7 +127,7 @@ describe('watcher pipeline', () => {
     })
 
     arm = false
-    await writeFile(path, 'DSH_CRED_PIPE: second\n')
+    await writeCredentials(path, 'DSH_CRED_PIPE: second\n')
     instance!.watcher.emit('all', 'change', path)
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'second', source: 'file' })
@@ -132,7 +137,7 @@ describe('watcher pipeline', () => {
   it('quiesces the refresh pipeline before dispose completes', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_PIPE: initial\n')
+    await writeCredentials(path, 'DSH_CRED_PIPE: initial\n')
     const ctx = new Context()
     const fiber = ctx.plugin(CredentialsLocal, { path, debounceMs: 5 })
     await fiber
@@ -142,7 +147,7 @@ describe('watcher pipeline', () => {
       if (disposed) postDisposeCommits += 1
     })
 
-    await writeFile(path, 'DSH_CRED_PIPE: changed\n')
+    await writeCredentials(path, 'DSH_CRED_PIPE: changed\n')
     const [instance] = await fakeInstances()
     // Two queued refreshes: dispose interrupts one mid-flight and the other
     // before it starts, so both closed guards must hold.
@@ -159,7 +164,7 @@ describe('watcher pipeline', () => {
   it('empties the snapshot when the document is deleted and emits the removals', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_PIPE: doomed\n')
+    await writeCredentials(path, 'DSH_CRED_PIPE: doomed\n')
     const ctx = await boot({ path, debounceMs: 5 })
     const seen: string[] = []
     ctx.on('credentials/updated', (ref) => {
@@ -178,7 +183,7 @@ describe('watcher pipeline', () => {
   it('keeps the last good snapshot when an external edit makes the document invalid', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, 'DSH_CRED_PIPE: a\n')
+    await writeCredentials(path, 'DSH_CRED_PIPE: a\n')
     const ctx = await boot({ path, debounceMs: 5 })
     const seen: string[] = []
     ctx.on('credentials/updated', (ref) => {
@@ -189,7 +194,7 @@ describe('watcher pipeline', () => {
     // this document holds nothing but credentials. A live reload must warn
     // and keep serving the last good snapshot rather than take the process
     // down or silently drop the entry it could not validate.
-    await writeFile(path, 'BAD-KEY: 2\nDSH_CRED_PIPE: b\n')
+    await writeCredentials(path, 'BAD-KEY: 2\nDSH_CRED_PIPE: b\n')
     const [instance] = await fakeInstances()
     instance!.watcher.emit('all', 'change', path)
     await new Promise(resolve => setTimeout(resolve, 50))
@@ -197,7 +202,7 @@ describe('watcher pipeline', () => {
     expect(seen).toEqual([])
 
     // Repairing the document resumes publishing.
-    await writeFile(path, 'DSH_CRED_PIPE: b\n')
+    await writeCredentials(path, 'DSH_CRED_PIPE: b\n')
     instance!.watcher.emit('all', 'change', path)
     await vi.waitFor(async () => {
       expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'b', source: 'file' })
@@ -218,11 +223,11 @@ describe('watcher pipeline', () => {
   it('reconciles at watcher ready so a change during setup is not missed', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
-    await writeFile(path, `${KEY}: a\n`)
+    await writeCredentials(path, `${KEY}: a\n`)
     const ctx = await boot({ path, debounceMs: 5 })
     // Written after the initial load but before the watcher became active:
     // no 'all' event will ever fire for it.
-    await writeFile(path, `${KEY}: written-before-ready\n`)
+    await writeCredentials(path, `${KEY}: written-before-ready\n`)
     const [instance] = await fakeInstances()
     instance!.watcher.emit('ready')
     await vi.waitFor(async () => {
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 85985c41d8..7ab5dd8dd2 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -47,12 +47,11 @@ export interface DeepSeekConnectionOptions {
   /** Endpoint base; `/chat/completions` is appended. */
   baseURL: string
   /**
-   * Literal API key of this same resolution, when the configuration carried
-   * one. Travelling with the endpoint is the point: a request can never pair
-   * one generation's URL with another generation's secret.
+   * Credential reference of this same resolution, resolved per request.
+   * Travelling with the endpoint is the point: a request can never pair one
+   * generation's URL with another generation's secret. Configuration carries
+   * only this name — a literal key is not a configuration value.
    */
-  apiKey?: string
-  /** Credential reference of this same resolution, resolved per request when no literal key exists. */
   apiKeyEnv: CredentialRef
   /** Request defaults applied to every call (thinking mode, effort). */
   defaults: RequestDefaults
diff --git a/packages/llm/llm-deepseek/src/index.ts b/packages/llm/llm-deepseek/src/index.ts
index effa080409..bdcdfc6006 100644
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/packages/llm/llm-deepseek/src/index.ts
@@ -59,8 +59,6 @@ const DEFAULT_MODELS: DeepSeekCatalogModel[] = [
  * reasoning effort resolves to `high`.
  */
 export interface Config {
-  /** Literal API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
-  apiKey?: string
   /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
   apiKeyEnv?: string
   /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */
@@ -89,7 +87,6 @@ const catalogModel: z<DeepSeekCatalogModel> = z.object({
 })
 
 export const Config: z<Config> = z.object({
-  apiKey: z.string().role('secret'),
   apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
   baseURL: z.string(),
   thinking: z.union(['enabled', 'disabled']),
@@ -147,9 +144,9 @@ function resolveModels(models: readonly DeepSeekCatalogModel[] | undefined): Dee
  * load (fail loud) and for each settings snapshot at its first use.
  * @param config - raw plugin config or resolved settings snapshot.
  * @param environment - this run's environment layers, or `undefined` outside
- * the product CLI. Only the launching shell and the user's own `.env` may
- * supply an endpoint: a base URL decides where the resolved API key is sent,
- * so a file inside the workspace must not be able to redirect it.
+ * the product CLI. Every layer may supply an endpoint: the product trusts the
+ * project it is launched in, so a checkout can point its own agent at the
+ * gateway that checkout is meant to use.
  * @returns validated connection facts plus the credential reference.
  */
 export function resolveAdapterOptions(config: Config, environment?: EnvironmentSnapshot): ResolvedDeepSeekOptions {
@@ -175,10 +172,9 @@ export function resolveAdapterOptions(config: Config, environment?: EnvironmentS
     )
   }
   return {
-    ...config.apiKey !== undefined && config.apiKey.length > 0 ? { apiKey: config.apiKey } : {},
     apiKeyEnv: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
     baseURL: config.baseURL
-      ?? environment?.getFrom(BASE_URL_ENV, ['process', 'user-env'])?.value
+      ?? environment?.getFrom(BASE_URL_ENV, ['process', 'project-env', 'user-env'])?.value
       ?? PUBLIC_BASE_URL,
     defaults: {
       thinking: config.thinking,
@@ -220,7 +216,6 @@ export function apply(ctx: Context, config: Config): void {
   const resolveApiKey = async (connection: ResolvedDeepSeekOptions): Promise<string> => {
     // Every credential fact comes from the caller's snapshot, so a rejected
     // settings generation cannot leak its key onto the previous endpoint.
-    if (connection.apiKey !== undefined) return connection.apiKey
     const ref = connection.apiKeyEnv
     const credentials = ctx.get('credentials')
     if (credentials !== undefined) {
@@ -228,16 +223,13 @@ export function apply(ctx: Context, config: Config): void {
       if (hit !== undefined) return hit.value
     } else {
       // Without the seam there is no managed store to rank against, so the
-      // launching environment is the whole credential plane — but only that
-      // layer: a key from a discovered project file would route this request
-      // through an account the launch never chose.
-      const inherited = environmentOf(ctx).getFrom(ref, ['process'])
-      if (inherited !== undefined && inherited.value.length > 0) return inherited.value
+      // environment is the whole credential plane.
+      const ambient = environmentOf(ctx).getFrom(ref, ['process', 'project-env', 'user-env'])
+      if (ambient !== undefined && ambient.value.length > 0) return ambient.value
     }
     throw new LlmError(
       `llm-deepseek: no API key for provider route "${PROVIDER}"; store ${ref} through the credentials`
-      + ` service (the web Models page writes it), export ${ref} in the launching environment, or — as a`
-      + ' last resort — set a literal "apiKey" in the llm-deepseek settings section',
+      + ` service (the web Models page writes it), or export ${ref} in the launching environment`,
       'MISSING_CREDENTIAL',
     )
   }
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index c9db376c8a..4f720ca1b8 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -13,7 +13,7 @@ import LlmService, { createUserMessage,
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
-import { DeepSeekAdapter, PUBLIC_BASE_URL, resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
+import { DeepSeekAdapter, resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
 import { httpErrorCode } from '../src/adapter.ts'
 import { assemble } from './assemble.ts'
 import { closeMockServers, mockServer, textEvents } from './mock-server.ts'
@@ -26,9 +26,12 @@ afterEach(async () => {
 })
 
 async function harness(baseURL: string, config: object = {}) {
+  // Configuration carries only the reference; the key comes from the
+  // environment, which is the whole credential plane without a mounted seam.
+  vi.stubEnv('DEEPSEEK_API_KEY', 'test-key')
   const ctx = new Context()
   await ctx.plugin(LlmService)
-  await ctx.plugin(LlmDeepSeek, { apiKey: 'test-key', baseURL, ...config })
+  await ctx.plugin(LlmDeepSeek, { baseURL, ...config })
   return ctx
 }
 
@@ -567,7 +570,6 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     const fiber = await ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: server.url,
     })
     expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
@@ -586,7 +588,6 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: 'http://127.0.0.1:1',
       retryPolicy: {
         mode: 'always',
@@ -605,7 +606,7 @@ describe('plugin registration and config', () => {
   it('owns the deepseek provider and advertises the default models', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
-    await ctx.plugin(LlmDeepSeek, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
+    await ctx.plugin(LlmDeepSeek, { baseURL: 'http://127.0.0.1:1' })
     expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
     await expect(ctx.llm.listModels('deepseek-official')).resolves.toEqual([
       { provider: 'deepseek-official', id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash' },
@@ -633,7 +634,6 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: 'http://127.0.0.1:1',
       reasoningEffort: effort,
     })
@@ -654,7 +654,6 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: 'http://127.0.0.1:1',
       thinking: 'disabled',
       reasoningEffort: 'off',
@@ -674,7 +673,6 @@ describe('plugin registration and config', () => {
       const ctx = new Context()
       await ctx.plugin(LlmService)
       await expect(ctx.plugin(LlmDeepSeek, {
-        apiKey: 'k',
         baseURL: 'http://127.0.0.1:1',
         thinking: 'disabled',
         reasoningEffort,
@@ -704,7 +702,7 @@ describe('plugin registration and config', () => {
   it('uses the default model catalog when apply is called directly', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
-    LlmDeepSeek.apply(ctx, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
+    LlmDeepSeek.apply(ctx, { baseURL: 'http://127.0.0.1:1' })
     await expect(ctx.llm.listModels('deepseek-official')).resolves.toEqual([
       { provider: 'deepseek-official', id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash' },
       { provider: 'deepseek-official', id: 'deepseek-v4-pro', name: 'DeepSeek-V4-Pro' },
@@ -715,7 +713,6 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: 'http://127.0.0.1:1',
       models: [
         { id: 'private-fast', contextWindow: 32_000 },
@@ -749,7 +746,6 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: 'http://127.0.0.1:1',
       defaultContextWindow: 256_000,
       models: [
@@ -770,7 +766,6 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: 'http://127.0.0.1:1',
       models: [],
     })
@@ -787,7 +782,6 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await expect(ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: 'http://127.0.0.1:1',
       models: [...models],
     })).rejects.toThrow(message)
@@ -799,7 +793,6 @@ describe('plugin registration and config', () => {
     await ctx.plugin(LlmService)
     expect(() => {
       LlmDeepSeek.apply(ctx, {
-        apiKey: 'k',
         baseURL: 'http://127.0.0.1:1',
         models: [{ id: 'invalid-context', contextWindow: 0 }],
       })
@@ -816,7 +809,6 @@ describe('plugin registration and config', () => {
       const ctx = new Context()
       await ctx.plugin(LlmService)
       await expect(ctx.plugin(LlmDeepSeek, {
-        apiKey: 'k',
         baseURL: 'http://127.0.0.1:1',
         defaultContextWindow,
       })).rejects.toThrow(/defaultContextWindow/)
@@ -833,7 +825,6 @@ describe('plugin registration and config', () => {
       const ctx = new Context()
       await ctx.plugin(LlmService)
       await expect(ctx.plugin(LlmDeepSeek, {
-        apiKey: 'k',
         baseURL: 'http://127.0.0.1:1',
         maxTokens,
       })).rejects.toThrow(/maxTokens/)
@@ -864,7 +855,7 @@ describe('plugin registration and config', () => {
     // The guidance leads with the credential store — the path that keeps the
     // secret out of configuration files — and mentions a literal key last.
     await expect(assemble(ctx, { model: 'deepseek-v4-flash', messages: [] }))
-      .rejects.toThrow(/store DEEPSEEK_API_KEY through the credentials service.*as a last resort.*"apiKey"/s)
+      .rejects.toThrow(/store DEEPSEEK_API_KEY through the credentials service.*export DEEPSEEK_API_KEY/s)
   })
 
   it('reads the ambient variable when no credentials seam is mounted', async () => {
@@ -900,25 +891,26 @@ describe('plugin registration and config', () => {
   it('uses DEEPSEEK_BASE_URL when config omits baseURL', async () => {
     const server = await mockServer([{ kind: 'sse', events: textEvents }])
     vi.stubEnv('DEEPSEEK_BASE_URL', server.url)
+    vi.stubEnv('DEEPSEEK_API_KEY', 'test-key')
     const ctx = new Context()
     await ctx.plugin(LlmService)
-    await ctx.plugin(LlmDeepSeek, { apiKey: 'k' })
+    await ctx.plugin(LlmDeepSeek, {})
     await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
     expect(server.requests).toHaveLength(1)
   })
 
 
-  it('takes DEEPSEEK_BASE_URL from the launching shell or the user .env, never from the project', () => {
+  it('takes DEEPSEEK_BASE_URL from any environment layer, with explicit config still on top', () => {
     const trusted = createEnvironmentSnapshot([
       { source: 'user-env', path: '/home/.dsh/.env', values: { DEEPSEEK_BASE_URL: 'https://user.example' } },
     ])
     expect(resolveAdapterOptions({}, trusted).baseURL).toBe('https://user.example')
-    // A base URL decides where the resolved API key is sent, so a file inside
-    // a model-writable workspace must not be able to redirect it.
+    // The product trusts the project it is launched in, so a checkout can
+    // point its own agent at the gateway that checkout is meant to use.
     const project = createEnvironmentSnapshot([
-      { source: 'project-env', path: '/work/.env', values: { DEEPSEEK_BASE_URL: 'https://attacker.example' } },
+      { source: 'project-env', path: '/work/.env', values: { DEEPSEEK_BASE_URL: 'https://project.example' } },
     ])
-    expect(resolveAdapterOptions({}, project).baseURL).toBe(PUBLIC_BASE_URL)
+    expect(resolveAdapterOptions({}, project).baseURL).toBe('https://project.example')
     // An explicitly configured endpoint outranks every environment layer, so a
     // stale shell value cannot rewrite a deployment's own gateway.
     const shell = createEnvironmentSnapshot([
@@ -966,12 +958,10 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await expect(ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: 'http://127.0.0.1:1',
       streamIdleTimeoutMs: 0,
     })).rejects.toThrow(/streamIdleTimeoutMs/)
     await expect(ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: 'http://127.0.0.1:1',
       streamIdleTimeoutMs: MAX_TIMER_DELAY_MS + 1,
     })).rejects.toThrow(/streamIdleTimeoutMs/)
@@ -982,7 +972,6 @@ describe('plugin registration and config', () => {
     await ctx.plugin(LlmService)
 
     await expect(ctx.plugin(LlmDeepSeek, {
-      apiKey: 'k',
       baseURL: 'http://127.0.0.1:1',
       retryPolicy: { mode: 'normal', maxRetries: -1 },
     })).rejects.toThrow(/retryPolicy/)
diff --git a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
index 6aecdcdaf7..153281afe3 100644
--- a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
@@ -61,7 +61,7 @@ describe('request-level dynamic configuration', () => {
   it('routes the next request with the freshly resolved base URL and credential', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: first-key\n')
+    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: first-key\n', { mode: 0o600 })
     const serverA = await mockServer([{ kind: 'sse', events: textEvents }])
     const serverB = await mockServer([{ kind: 'sse', events: textEvents }])
     const { ctx } = await boot(dir, { baseURL: serverA.url })
@@ -78,16 +78,21 @@ describe('request-level dynamic configuration', () => {
     expect(serverB.headers[0]?.authorization).toBe('Bearer second-key')
   })
 
-  it('prefers a literal settings apiKey over the credential layers', async () => {
+  it('refuses a literal apiKey in settings and keeps serving the stored credential', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: file-key\n')
+    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: file-key\n', { mode: 0o600 })
     const server = await mockServer([{ kind: 'sse', events: textEvents }])
     const { ctx } = await boot(dir, { baseURL: server.url })
 
+    // Configuration carries a reference, never a value. The namespace has no
+    // `apiKey` field, so writing one is dropped by the schema rather than
+    // rejected (no adapter namespace is strict); what matters is that a
+    // settings document cannot become a second credential store outranking
+    // `.credentials.yaml` and the environment.
     await ctx.settings.update(NS, { apiKey: 'literal-key' })
     await prompt(ctx)
-    expect(server.headers[0]?.authorization).toBe('Bearer literal-key')
+    expect(server.headers[0]?.authorization).toBe('Bearer file-key')
   })
 
   it('starts keyless and serves the next request once the key arrives', async () => {
@@ -152,17 +157,16 @@ describe('request-level dynamic configuration', () => {
     ])
   })
 
-  it('sends the whole last-good snapshot when a rejected one changed both the key and the URL', async () => {
-    vi.stubEnv('DEEPSEEK_API_KEY', '')
+  it('keeps the whole last-good snapshot when a rejected one changed the URL', async () => {
     const dir = await home()
     const good = await mockServer([{ kind: 'sse', events: textEvents }])
     const rejected = await mockServer([{ kind: 'sse', events: textEvents }])
-    const { ctx } = await boot(dir, { apiKey: 'good-key', baseURL: good.url })
+    vi.stubEnv('DEEPSEEK_API_KEY', 'good-key')
+    const { ctx } = await boot(dir, { baseURL: good.url })
 
-    // One snapshot moves the endpoint AND the literal key, and fails the
-    // resolve step beyond the schema (duplicate catalog ids).
+    // One snapshot moves the endpoint and fails the resolve step beyond the
+    // schema (duplicate catalog ids).
     await ctx.settings.update(NS, {
-      apiKey: 'rejected-key',
       baseURL: rejected.url,
       models: [{ id: 'dup' }, { id: 'dup' }],
     })
@@ -178,7 +182,7 @@ describe('request-level dynamic configuration', () => {
   it('falls back to the composition entry when settings detach', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: steady-key\n')
+    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: steady-key\n', { mode: 0o600 })
     const serverA = await mockServer([{ kind: 'sse', events: textEvents }])
     const serverB = await mockServer([{ kind: 'sse', events: textEvents }])
     const { ctx, settingsFiber } = await boot(dir, { baseURL: serverA.url })
diff --git a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
index c8d596af74..a7e1f433e5 100644
--- a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
@@ -51,7 +51,7 @@ async function loadComposition(
   const credentialsPath = join(root, '.credentials.yaml')
   if (options.withDynamic && fresh) {
     await writeFile(settingsPath, '# personal settings\n')
-    await writeFile(credentialsPath, 'DEEPSEEK_API_KEY: boot-key\n')
+    await writeFile(credentialsPath, 'DEEPSEEK_API_KEY: boot-key\n', { mode: 0o600 })
   }
 
   const configPath = join(root, 'cordis.yml')
@@ -76,7 +76,6 @@ async function loadComposition(
     "  name: '@deepseek-ai/dsh-llm-deepseek'",
     '  config:',
     `    baseURL: ${JSON.stringify(options.baseURL)}`,
-    ...options.withDynamic ? [] : ['    apiKey: entry-key'],
     '',
   ].join('\n'))
 
@@ -122,7 +121,7 @@ describe('llm-deepseek real dynamic composition', () => {
     await vi.waitFor(() => {
       expect((ctx.get('settings')!.get(NS) as { baseURL?: string }).baseURL).toBe(serverB.url)
     }, { timeout: 5000 })
-    await writeFile(credentialsPath, 'DEEPSEEK_API_KEY: rotated-key\n')
+    await writeFile(credentialsPath, 'DEEPSEEK_API_KEY: rotated-key\n', { mode: 0o600 })
     await vi.waitFor(async () => {
       expect(await ctx.get('credentials')!.resolve(KEY_REF)).toEqual({ value: 'rotated-key', source: 'file' })
     }, { timeout: 5000 })
@@ -161,8 +160,10 @@ describe('llm-deepseek real dynamic composition', () => {
     expect(second.headers[0]?.authorization).toBe('Bearer rotated-after-restart')
   })
 
-  it('boots the same adapter without settings or credentials entries on entry config alone', async () => {
-    vi.stubEnv('DEEPSEEK_API_KEY', '')
+  it('boots the same adapter on entry config alone, resolving the reference from the environment', async () => {
+    // No settings and no credentials provider: configuration carries only the
+    // reference, so the environment is the whole credential plane here.
+    vi.stubEnv('DEEPSEEK_API_KEY', 'entry-key')
     const server = await mockServer([{ kind: 'sse', events: textEvents }])
     const { ctx } = await loadComposition({ withDynamic: false, baseURL: server.url })
 
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index 862aa2afca..c138b8f5fc 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -100,9 +100,8 @@ export function apply(ctx: Context, config: Config): void {
     const credentials = ctx.get('credentials')
     const hit = credentials !== undefined
       ? (await credentials.resolve(ref))?.value
-      // Without the seam the launching environment is the whole credential
-      // plane — but only that layer, never a discovered project file.
-      : environmentOf(ctx).getFrom(ref, ['process'])?.value
+      // Without the seam the environment is the whole credential plane.
+      : environmentOf(ctx).getFrom(ref, ['process', 'project-env', 'user-env'])?.value
     if (hit !== undefined && hit.length > 0) return hit
     throw new LlmError(
       `llm-pi-ai: no credential for provider route "${provider}"; its profile resolves ${ref}, which is not`
diff --git a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
index 2c60ba0e83..cc5cd17e55 100644
--- a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
@@ -53,7 +53,7 @@ describe('request-level dynamic profiles', () => {
   it('mounts bare and dormant, then registers routes the moment settings supply providers', async () => {
     vi.stubEnv('PI_DYNAMIC_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.credentials.yaml'), 'PI_DYNAMIC_KEY: pk-from-settings\n')
+    await writeFile(join(dir, '.credentials.yaml'), 'PI_DYNAMIC_KEY: pk-from-settings\n', { mode: 0o600 })
     const server = await mockServer([{ events: textEvents }])
     // The exact product posture: `- id: llm-pi-ai` with no config at all.
     const ctx = await boot(dir, {})
@@ -112,7 +112,7 @@ describe('request-level dynamic profiles', () => {
   it('rotates the per-request credential referenced by apiKeyEnv', async () => {
     vi.stubEnv('PI_DYNAMIC_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.credentials.yaml'), 'PI_DYNAMIC_KEY: pk-one\n')
+    await writeFile(join(dir, '.credentials.yaml'), 'PI_DYNAMIC_KEY: pk-one\n', { mode: 0o600 })
     const server = await mockServer([{ events: textEvents }, { events: textEvents }])
     const ctx = await boot(dir, {
       providers: { deepseek: { apiKeyEnv: 'PI_DYNAMIC_KEY', baseURL: server.url } },
diff --git a/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts b/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts
index 5d32a748ea..d5eed60e5e 100644
--- a/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/loader-composition.spec.ts
@@ -40,7 +40,7 @@ async function loadComposition(): Promise<{ ctx: Context; settingsPath: string }
   root = await mkdtemp(join(tmpdir(), 'dsh-pi-composition-'))
   const settingsPath = join(root, 'settings.yaml')
   await writeFile(settingsPath, '# personal settings\n')
-  await writeFile(join(root, '.credentials.yaml'), 'PI_COMPOSITION_KEY: key-from-store\n')
+  await writeFile(join(root, '.credentials.yaml'), 'PI_COMPOSITION_KEY: key-from-store\n', { mode: 0o600 })
 
   const configPath = join(root, 'cordis.yml')
   await writeFile(configPath, [
diff --git a/packages/llm/llm-retry/tests/transport-recovery.spec.ts b/packages/llm/llm-retry/tests/transport-recovery.spec.ts
index a17074504a..653bade210 100644
--- a/packages/llm/llm-retry/tests/transport-recovery.spec.ts
+++ b/packages/llm/llm-retry/tests/transport-recovery.spec.ts
@@ -1,7 +1,7 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { createServer } from 'node:http'
 import type { AddressInfo } from 'node:net'
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -34,10 +34,10 @@ async function harness(
   baseURL: string,
   options: { streamIdleTimeoutMs?: number; initialDelayMs?: number } = {},
 ): Promise<Context> {
+  vi.stubEnv('DEEPSEEK_API_KEY', 'mock-key')
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx)
   await ctx.plugin(LlmDeepSeek, {
-    apiKey: 'mock-key',
     baseURL,
     streamIdleTimeoutMs: options.streamIdleTimeoutMs ?? 1_000,
     retryPolicy: {
diff --git a/packages/settings/settings-local/src/index.ts b/packages/settings/settings-local/src/index.ts
index 6b14eccc8f..d713083c20 100644
--- a/packages/settings/settings-local/src/index.ts
+++ b/packages/settings/settings-local/src/index.ts
@@ -242,10 +242,16 @@ export class SettingsLocal extends Settings {
   private parse(text: string): Record<string, unknown> {
     let root: unknown
     if (this.spec.format === 'yaml') {
+      // `prettyErrors` is on only for `linePos`; `error.message` is never
+      // used, because the parser quotes the offending source line and a
+      // settings document can hold a `role('secret')` value.
       const document = parseDocument(text, { prettyErrors: true })
       if (document.errors.length > 0) {
         throw new Error(`settings-local: invalid document at ${this.spec.filename}: ${
-          document.errors.map(error => error.message).join('; ')}`)
+          document.errors.map((error) => {
+            const at = error.linePos?.[0]
+            return `${error.code}${at === undefined ? '' : ` at line ${String(at.line)}, column ${String(at.col)}`}`
+          }).join('; ')}`)
       }
       root = document.toJS() ?? {}
     } else {
diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index 9d251d1940..c7ad354478 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/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/util/environment/README.md
-README.md: f642aa715c87878b2eaab9f034fb18163a6fbd2e
-README.zh.md: a095730dbc8c2a4e7dc8dc57dc2930685c8fb453
+README.md: 526c7263106962cdbc19ec58c00b06e58849a258
+README.zh.md: 203b8252d2e96235ec083481ccafda129902cd38
diff --git a/packages/util/environment/README.md b/packages/util/environment/README.md
index f642aa715c..526c726310 100644
--- a/packages/util/environment/README.md
+++ b/packages/util/environment/README.md
@@ -7,7 +7,7 @@ This run's environment as one immutable snapshot that remembers **which layer su
 | Layer | Source id | What it is |
 |---|---|---|
 | Inherited process environment | `process` | What the launching shell, CI job, or container passed in — this run's explicit intent |
-| `<invocation cwd>/.env` | `project-env` | Whatever the project directory happens to contain; a model working in that workspace can write it |
+| `<invocation cwd>/.env` | `project-env` | The project the harness was launched in, which the product trusts to configure its own agent |
 | `$DSH_HOME/.env` | `user-env` | The user's own machine-level defaults |
 
 Values do also reach `process.env` — a user's `--config` tree and third-party libraries read it — but that flattened view is not the authority for anything the harness resolves.
@@ -16,14 +16,14 @@ Values do also reach `process.env` — a user's `--config` tree and third-party
 
 `get(name)` searches every layer, most trusted first. `getFrom(name, sources)` searches only the layers the caller trusts.
 
-**Omitting a layer is a refusal, not a demotion.** A base URL decides where a resolved API key is sent, so the LLM adapters ask for `['process', 'user-env']`: no future reordering can let a project file redirect a credential, because that layer is never consulted at all.
+**Omitting a layer is a refusal, not a demotion** — a caller that must never accept a layer leaves it out of the list, so no future reordering can let it back in. The provider adapters name all three, because the product trusts the project it runs in; the mechanism exists for the decisions where that is not true.
 
 ```ts
 import type { Context } from 'cordis'
 import { environmentOf } from '@deepseek-ai/dsh-environment'
 
 declare const ctx: Context
-const endpoint = environmentOf(ctx).getFrom('DEEPSEEK_BASE_URL', ['process', 'user-env'])?.value
+const endpoint = environmentOf(ctx).getFrom('DEEPSEEK_BASE_URL', ['process', 'project-env', 'user-env'])?.value
 ```
 
 `environmentOf(ctx)` returns the launcher's snapshot when the product CLI booted the tree, and otherwise the inherited environment as the only layer. That fallback does not weaken the rules: an SDK host or a bare `cordis.yml` discovered no files, so everything it has really is the environment it was launched with.
@@ -32,11 +32,13 @@ const endpoint = environmentOf(ctx).getFrom('DEEPSEEK_BASE_URL', ['process', 'us
 
 `isBootstrapOnly(name)` names the variables only the inherited environment may set. The launcher rejects a `.env` that declares one, before applying anything.
 
-A bootstrap variable decides **how a process launches** (`PATH`, `SHELL`, `NODE_OPTIONS`, `NODE_PATH`, `LD_PRELOAD`, `LD_LIBRARY_PATH`, `DYLD_*`), **where code or model-visible instructions load from** (the whole `DSH_*` namespace, `HOME`, `USERPROFILE`, `XDG_*`), or **how the network is reached and trusted** (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`, `SSL_CERT_FILE`, `SSL_CERT_DIR`, `NODE_EXTRA_CA_CERTS`). Matching is case-insensitive, so `https_proxy` is not a bypass.
+Trusting a project to configure the agent's work is not the same as letting it change the harness. A bootstrap variable decides **how a process launches** (`PATH`, `SHELL`, `NODE_OPTIONS`, `LD_PRELOAD`, `DYLD_*`), **what code a runtime executes before the program it was asked to run** (`BASH_ENV` and its per-language siblings — `PERL5OPT`, `PYTHONSTARTUP`, `RUBYOPT`, `JAVA_TOOL_OPTIONS` — plus the Git hook commands), **where model-visible instructions load from** (the whole `DSH_*` namespace, `HOME`, `XDG_*`), or **how the network is reached and trusted** (proxy and CA variables). Matching is case-insensitive, so `https_proxy` is not a bypass.
+
+These take effect with no user action, before any turn, outside the permission policy and the sandbox: `DSH_PERMISSION_MODE` would switch off the approvals that make trusting a project meaningful, and `BASH_ENV` runs a file of the project's choosing on every `bash -c` the bash tool issues.
 
 The whole `DSH_*` namespace is denied rather than an audited subset: the harness's own switches — the permission mode, the agents home, the bundled skill root — are exactly what a hostile project would want, and a switch added later must not become settable by forgetting to list it.
 
 ## Known Limitations and Deferred Work
 
-- **The snapshot is not a subprocess boundary** — every layer is also materialized into `process.env`, so ordinary project variables still reach child processes under [`dsh-subprocess`](../../subprocess/subprocess/README.md)'s scrub. Bootstrap variables cannot come from a file at all, but a project `.env` can still set, say, `GIT_SSH_COMMAND` for the tools an agent runs.
+- **The snapshot is not a subprocess boundary** — every layer is also materialized into `process.env`, so ordinary project variables reach child processes under [`dsh-subprocess`](../../subprocess/subprocess/README.md)'s scrub. That is intended for ordinary variables; the code-loading hooks that would abuse it are rejected at load instead, and the deny list is the thing to extend when a new runtime hook appears.
 - **No per-workspace layer** — the project layer is the *invoking* directory, fixed at launch. A workspace selected later in the Web UI contributes nothing, deliberately: following it would let a model's own workspace change the harness environment mid-session.
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index a095730dbc..203b8252d2 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -7,7 +7,7 @@
 | 层 | 来源 id | 它是什么 |
 |---|---|---|
 | 继承的进程环境 | `process` | 启动 shell、CI 任务或容器传入的东西——本次运行的明确意图 |
-| `<invocation cwd>/.env` | `project-env` | 项目目录里恰好有的东西；在该工作区里工作的模型可以写它 |
+| `<invocation cwd>/.env` | `project-env` | harness 被启动于其中的项目；产品信任它配置自己的 agent |
 | `$DSH_HOME/.env` | `user-env` | 用户自己的机器级默认值 |
 
 这些值同样会进入 `process.env`——用户自己的 `--config` 树和第三方库要读它——但那份压平的视图不是 harness 解析任何值的依据。
@@ -16,14 +16,14 @@
 
 `get(name)` 按可信度从高到低搜索所有层。`getFrom(name, sources)` 只搜索调用方信任的层。
 
-**省略某一层是拒绝，不是降级。** base URL 决定已解析的 API key 被发往何处，因此 LLM 适配器请求的是 `['process', 'user-env']`：后续任何重新排序都无法让项目文件重定向凭据，因为那一层根本不会被查询。
+**省略某一层是拒绝，不是降级**——绝不能接受某一层的调用方直接不把它列进去，后续任何重新排序都无法让它回来。provider 适配器三层全列，因为产品信任它所运行的项目；该机制是为那些「并非如此」的决策准备的。
 
 ```ts
 import type { Context } from 'cordis'
 import { environmentOf } from '@deepseek-ai/dsh-environment'
 
 declare const ctx: Context
-const endpoint = environmentOf(ctx).getFrom('DEEPSEEK_BASE_URL', ['process', 'user-env'])?.value
+const endpoint = environmentOf(ctx).getFrom('DEEPSEEK_BASE_URL', ['process', 'project-env', 'user-env'])?.value
 ```
 
 当产品 CLI（命令行界面）启动了这棵树时，`environmentOf(ctx)` 返回启动器的快照；否则返回只含继承环境的那一层。该回退并不削弱规则：SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，因此它拥有的一切确实就是它被启动时的环境。
@@ -32,11 +32,13 @@ const endpoint = environmentOf(ctx).getFrom('DEEPSEEK_BASE_URL', ['process', 'us
 
 `isBootstrapOnly(name)` 给出只有继承环境才能设置的变量。启动器一旦发现某个 `.env` 声明了其中之一，就会在应用任何内容之前拒绝启动。
 
-bootstrap 变量决定**进程如何启动**（`PATH`、`SHELL`、`NODE_OPTIONS`、`NODE_PATH`、`LD_PRELOAD`、`LD_LIBRARY_PATH`、`DYLD_*`）、**代码或模型可见的指令从哪里加载**（整个 `DSH_*` 命名空间、`HOME`、`USERPROFILE`、`XDG_*`），或者**网络如何抵达与信任**（`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY`、`SSL_CERT_FILE`、`SSL_CERT_DIR`、`NODE_EXTRA_CA_CERTS`）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
+信任一个项目配置 agent 的工作，不等于让它改变 harness 本身。bootstrap 变量决定**进程如何启动**（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD`、`DYLD_*`）、**运行时在执行被要求运行的程序之前先执行哪些代码**（`BASH_ENV` 及其各语言同类——`PERL5OPT`、`PYTHONSTARTUP`、`RUBYOPT`、`JAVA_TOOL_OPTIONS`——以及 Git 的钩子命令）、**模型可见的指令从哪里加载**（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），或者**网络如何抵达与信任**（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
+
+这些变量无需任何用户动作、在任何一轮开始之前、且在权限策略与沙箱之外就生效：`DSH_PERMISSION_MODE` 会关掉让「信任项目」有意义的那道审批，而 `BASH_ENV` 会在 bash 工具发出的每一次 `bash -c` 上执行项目指定的文件。
 
 整个 `DSH_*` 命名空间被拒绝，而不是只拒绝一份经过审查的子集：harness 自己的开关——权限模式、agents home、内置 skill（技能）根目录——恰恰是敌意项目最想要的，而后来新增的开关不能因为忘记登记就变得可设置。
 
 ## Known Limitations and Deferred Work
 
-- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此普通的项目变量仍会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。bootstrap 变量完全不能来自文件，但项目 `.env` 仍可以为 agent 运行的工具设置诸如 `GIT_SSH_COMMAND` 之类的变量。
+- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。这对普通变量是有意为之；会滥用这一点的代码加载钩子改为在加载时拒绝，新的运行时钩子出现时该扩展的是那份拒绝清单。
 - **没有按工作区划分的层**：项目层是*调用*目录，在启动时固定。之后在 Web UI 中选择的工作区不贡献任何内容，这是刻意的：跟随它等于让模型自己的工作区在会话中途改变 harness 的环境。
diff --git a/packages/util/environment/src/index.ts b/packages/util/environment/src/index.ts
index 100a0fe9f0..6e27656805 100644
--- a/packages/util/environment/src/index.ts
+++ b/packages/util/environment/src/index.ts
@@ -146,29 +146,51 @@ const BOOTSTRAP_NAMES = new Set([
   // Process launch and module resolution.
   'PATH', 'HOME', 'USERPROFILE', 'SHELL',
   'NODE_OPTIONS', 'NODE_PATH', 'NODE_EXTRA_CA_CERTS',
-  'LD_PRELOAD', 'LD_LIBRARY_PATH',
+  'LD_PRELOAD', 'LD_LIBRARY_PATH', 'LD_AUDIT',
+  // Interpreter start-up hooks: each of these makes a runtime execute a file
+  // of the setter's choosing on every invocation, before the program runs.
+  // `BASH_ENV` is the sharpest — the bash tool spawns `bash -c`, which sources
+  // it every time — but every runtime an agent shells out to has one.
+  'BASH_ENV', 'ENV', 'SHELLOPTS', 'BASHOPTS',
+  'PERL5OPT', 'PERL5LIB', 'PYTHONSTARTUP', 'PYTHONPATH', 'RUBYOPT', 'RUBYLIB',
+  'JAVA_TOOL_OPTIONS', '_JAVA_OPTIONS', 'JDK_JAVA_OPTIONS',
+  // Version-control hooks that run a command on the setter's behalf.
+  'GIT_SSH', 'GIT_SSH_COMMAND', 'GIT_EXTERNAL_DIFF', 'GIT_PAGER', 'GIT_EDITOR',
+  'EDITOR', 'VISUAL', 'PAGER',
   // Network reach and trust.
   'SSL_CERT_FILE', 'SSL_CERT_DIR',
   'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+  'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE',
 ])
 
 /** Name prefixes no discovered file may set. */
-const BOOTSTRAP_PREFIXES = ['DSH_', 'XDG_', 'DYLD_']
+const BOOTSTRAP_PREFIXES = ['DSH_', 'XDG_', 'DYLD_', 'BASH_FUNC_']
 
 /**
  * Whether a variable may come only from the inherited process environment.
  *
- * A bootstrap variable decides how a process launches (`PATH`, `NODE_OPTIONS`,
- * `LD_PRELOAD`), where code or model-visible instructions load from (`DSH_*`
- * covers the Harness home, the agents home, and the bundled skill root), or
- * how the network is reached and trusted (proxy and CA variables). A file the
- * harness merely finds — including one a model can write inside the workspace
- * — must never set them, so they are rejected at load rather than ranked
- * below another layer.
+ * The invoking project is trusted to *configure* the agent's work — its
+ * endpoints, its ordinary variables, even a credential. It is not trusted to
+ * change the harness itself, and that is what a bootstrap variable does: it
+ * decides how a process launches (`PATH`, `NODE_OPTIONS`, `LD_PRELOAD`), what
+ * code a runtime executes before the program it was asked to run (`BASH_ENV`
+ * and its per-language siblings, the Git hook commands), where model-visible
+ * instructions load from (`DSH_*` covers the Harness home, the agents home,
+ * and the bundled skill root), or how the network is reached and trusted
+ * (proxy and CA variables).
  *
- * The whole `DSH_*` namespace is denied rather than an audited subset: the
- * harness's own switches are exactly the ones a hostile project would want,
- * and a new switch must not become settable by forgetting to list it.
+ * The distinction is that these take effect with no user action, before any
+ * turn, outside the permission policy and the sandbox — `DSH_PERMISSION_MODE`
+ * would switch off the approvals that make trusting a project meaningful at
+ * all, and `BASH_ENV` runs a file of the project's choosing on every single
+ * `bash -c` the tool issues. Trusting a project's code to run under the
+ * agent's policy is not the same as letting it rewrite that policy.
+ *
+ * They are therefore rejected at load rather than ranked below another layer:
+ * a user who wrote one into a file believes it applies, and silently ignoring
+ * it is its own failure. The whole `DSH_*` namespace is denied rather than an
+ * audited subset, because a switch added later must not become settable by
+ * being forgotten.
  * @param name - the variable name.
  * @returns true when only the inherited environment may supply it.
  */
diff --git a/packages/web/web-search-deepseek/README.i18n.yaml b/packages/web/web-search-deepseek/README.i18n.yaml
index edc7b5d18b..41fb3ae35c 100644
--- a/packages/web/web-search-deepseek/README.i18n.yaml
+++ b/packages/web/web-search-deepseek/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/web/web-search-deepseek/README.md
-README.md: 9046934de209ed0787efa50332e5be16bfdf55c6
-README.zh.md: 94e01daba69cecd2f5c3c6680979ee5fd66d7cdd
+README.md: 95340314fe08d0963b899f4a1d704a98f85963a5
+README.zh.md: efd02af805faa96781654b4a4a0dd69a6b8ed3e4
diff --git a/packages/web/web-search-deepseek/README.md b/packages/web/web-search-deepseek/README.md
index 9046934de2..95340314fe 100644
--- a/packages/web/web-search-deepseek/README.md
+++ b/packages/web/web-search-deepseek/README.md
@@ -20,7 +20,7 @@ It reuses the `DEEPSEEK_API_KEY` credential reference (no new secret) but **not*
 |---|---|---|
 | `apiKey` | omitted | Literal DeepSeek API key. Prefer `apiKeyEnv` so no secret enters configuration; a non-empty literal wins. |
 | `apiKeyEnv` | `DEEPSEEK_API_KEY` | Credential reference resolved for each search through `ctx.credentials`, or from the process environment when that seam is absent. A missing value fails the call as `WEB_PROVIDER_CREDENTIAL_MISSING`. |
-| `baseURL` | `https://api.deepseek.com/anthropic/v1` | Anthropic-compatible endpoint base; `/messages` is appended. Use a separate env var such as `$DEEPSEEK_SEARCH_BASE_URL` when overriding it; do not reuse `$DEEPSEEK_BASE_URL`, which belongs to the chat-completions LLM adapter. An unparseable value makes the provider unavailable. |
+| `baseURL` | `https://api.deepseek.com/anthropic/v1` | Anthropic-compatible endpoint base; `/messages` is appended. Falls back to `$DEEPSEEK_SEARCH_BASE_URL` from any environment layer; do not reuse `$DEEPSEEK_BASE_URL`, which belongs to the chat-completions LLM adapter. An unparseable value makes the provider unavailable. |
 | `model` | `deepseek-v4-flash` | Anthropic-format model name. |
 | `apiVersion` | `2023-06-01` | `anthropic-version` header value. |
 | `maxTokens` | `4096` | Positive-integer upper bound on generated tokens for the Messages request. |
@@ -31,7 +31,7 @@ It reuses the `DEEPSEEK_API_KEY` credential reference (no new secret) but **not*
   name: '@deepseek-ai/dsh-web-search-deepseek'
   config:
     apiKeyEnv: DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
+    baseURL: https://gateway.internal/anthropic/v1
 ```
 
 ## Mapping
diff --git a/packages/web/web-search-deepseek/README.zh.md b/packages/web/web-search-deepseek/README.zh.md
index 94e01daba6..efd02af805 100644
--- a/packages/web/web-search-deepseek/README.zh.md
+++ b/packages/web/web-search-deepseek/README.zh.md
@@ -20,7 +20,7 @@ Exa 和 Perplexity 提供专用搜索端点，DeepSeek 则没有。该提供方
 |---|---|---|
 | `apiKey` | 未设置 | DeepSeek API 密钥字面值。优先使用 `apiKeyEnv`，避免密钥进入配置；非空字面值优先。 |
 | `apiKeyEnv` | `DEEPSEEK_API_KEY` | 每次搜索都会通过 `ctx.credentials` 解析该凭据引用；没有该 seam 时则从进程环境解析。值缺失时，调用以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败。 |
-| `baseURL` | `https://api.deepseek.com/anthropic/v1` | Anthropic 兼容端点基址；追加 `/messages`。覆盖时使用 `$DEEPSEEK_SEARCH_BASE_URL` 等独立环境变量；禁止复用属于 chat-completions LLM 适配器的 `$DEEPSEEK_BASE_URL`。无法解析时提供方不可用。 |
+| `baseURL` | `https://api.deepseek.com/anthropic/v1` | Anthropic 兼容端点基址；追加 `/messages`。缺省时回退到任一环境层中的 `$DEEPSEEK_SEARCH_BASE_URL`；禁止复用属于 chat-completions LLM 适配器的 `$DEEPSEEK_BASE_URL`。无法解析时提供方不可用。 |
 | `model` | `deepseek-v4-flash` | Anthropic 格式模型名称。 |
 | `apiVersion` | `2023-06-01` | `anthropic-version` 标头值。 |
 | `maxTokens` | `4096` | Messages 请求生成 token 的正整数上限。 |
@@ -31,7 +31,7 @@ Exa 和 Perplexity 提供专用搜索端点，DeepSeek 则没有。该提供方
   name: '@deepseek-ai/dsh-web-search-deepseek'
   config:
     apiKeyEnv: DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
+    baseURL: https://gateway.internal/anthropic/v1
 ```
 
 ## 映射
diff --git a/packages/web/web-search-deepseek/src/index.ts b/packages/web/web-search-deepseek/src/index.ts
index 3a7e1f65a9..60b5a64692 100644
--- a/packages/web/web-search-deepseek/src/index.ts
+++ b/packages/web/web-search-deepseek/src/index.ts
@@ -68,6 +68,14 @@ export const Config: z<Config> = z.object({
   maxUses: z.number().step(1).min(1),
 })
 
+/**
+ * Environment variable naming this provider's endpoint. Deliberately distinct
+ * from `$DEEPSEEK_BASE_URL`, which belongs to the chat-completions adapter:
+ * search speaks the Anthropic-compatible Messages API, so one variable cannot
+ * serve both.
+ */
+const SEARCH_BASE_URL_ENV = 'DEEPSEEK_SEARCH_BASE_URL'
+
 /** Register the DeepSeek search provider with `ctx.web`. */
 export function apply(ctx: Context, config: Config): void {
   const maxTokens = config.maxTokens ?? DEEPSEEK_DEFAULT_MAX_TOKENS
@@ -81,13 +89,14 @@ export function apply(ctx: Context, config: Config): void {
     resolveApiKey: async () => {
       const credentials = ctx.get('credentials')
       if (credentials !== undefined) return (await credentials.resolve(apiKeyEnv))?.value
-      // Without the seam the launching environment is the whole credential
-      // plane — but only that layer, never a discovered project file.
-      const inherited = environmentOf(ctx).getFrom(apiKeyEnv, ['process'])
-      return inherited !== undefined && inherited.value.length > 0 ? inherited.value : undefined
+      // Without the seam the environment is the whole credential plane.
+      const ambient = environmentOf(ctx).getFrom(apiKeyEnv, ['process', 'project-env', 'user-env'])
+      return ambient !== undefined && ambient.value.length > 0 ? ambient.value : undefined
     },
     apiKeyEnv,
-    baseURL: config.baseURL ?? DEEPSEEK_DEFAULT_BASE_URL,
+    baseURL: config.baseURL
+      ?? environmentOf(ctx).getFrom(SEARCH_BASE_URL_ENV, ['process', 'project-env', 'user-env'])?.value
+      ?? DEEPSEEK_DEFAULT_BASE_URL,
     model: config.model ?? DEEPSEEK_DEFAULT_MODEL,
     apiVersion: config.apiVersion ?? DEEPSEEK_DEFAULT_API_VERSION,
     maxTokens,
diff --git a/packages/web/web-search-exa/src/index.ts b/packages/web/web-search-exa/src/index.ts
index 87a8e6572e..d5c8b938ac 100644
--- a/packages/web/web-search-exa/src/index.ts
+++ b/packages/web/web-search-exa/src/index.ts
@@ -59,10 +59,9 @@ export const Config: z<Config> = z.object({
 /** Register the Exa search provider with `ctx.web`. */
 export function apply(ctx: Context, config: Config): void {
   ctx.web.registerSearchProvider(new ExaSearchProvider({
-    // Only the launching shell and the user's own `.env` may name this key:
-    // a project directory can be written by the model, and a substituted key
-    // would route every request through an account someone else reads.
-    apiKey: config.apiKey ?? environmentOf(ctx).getFrom('EXA_API_KEY', ['process', 'user-env'])?.value ?? '',
+    // Every environment layer may name this key: the product trusts the
+    // project it is launched in, and the managed store is not involved here.
+    apiKey: config.apiKey ?? environmentOf(ctx).getFrom('EXA_API_KEY', ['process', 'project-env', 'user-env'])?.value ?? '',
     baseURL: config.baseURL ?? EXA_DEFAULT_BASE_URL,
     searchType: config.searchType ?? EXA_DEFAULT_SEARCH_TYPE,
     highlightsPerResult: config.highlightsPerResult ?? EXA_DEFAULT_HIGHLIGHTS_PER_RESULT,
diff --git a/packages/web/web-search-perplexity/src/index.ts b/packages/web/web-search-perplexity/src/index.ts
index b2b5804a92..c8088a3c23 100644
--- a/packages/web/web-search-perplexity/src/index.ts
+++ b/packages/web/web-search-perplexity/src/index.ts
@@ -53,10 +53,9 @@ export const Config: z<Config> = z.object({
 /** Register the Perplexity search provider with `ctx.web`. */
 export function apply(ctx: Context, config: Config): void {
   ctx.web.registerSearchProvider(new PerplexitySearchProvider({
-    // Only the launching shell and the user's own `.env` may name this key:
-    // a project directory can be written by the model, and a substituted key
-    // would route every request through an account someone else reads.
-    apiKey: config.apiKey ?? environmentOf(ctx).getFrom('PERPLEXITY_API_KEY', ['process', 'user-env'])?.value ?? '',
+    // Every environment layer may name this key: the product trusts the
+    // project it is launched in, and the managed store is not involved here.
+    apiKey: config.apiKey ?? environmentOf(ctx).getFrom('PERPLEXITY_API_KEY', ['process', 'project-env', 'user-env'])?.value ?? '',
     baseURL: config.baseURL ?? PERPLEXITY_DEFAULT_BASE_URL,
     model: config.model ?? PERPLEXITY_DEFAULT_MODEL,
     maxTokens: config.maxTokens ?? PERPLEXITY_DEFAULT_MAX_TOKENS,

From f22cacc63b7c503cdde6915ba6c21b98774e8cfe Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 4 Aug 2026 17:49:21 +0800
Subject: [PATCH 023/516] fix: advance resolving issue status from PRs

---
 ...-04-forward-only-pr-issue-status.i18n.yaml |  6 +++
 ...2026-08-04-forward-only-pr-issue-status.md | 39 ++++++++++++++++
 ...6-08-04-forward-only-pr-issue-status.zh.md | 39 ++++++++++++++++
 .github/issue-management/policy.mjs           | 32 ++++++++++----
 .github/issue-management/policy.test.mjs      | 44 +++++++++++++++++++
 package.json                                  |  1 +
 scripts/run-gates.ts                          |  3 ++
 7 files changed, 155 insertions(+), 9 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.md
 create mode 100644 .agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md

diff --git a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml
new file mode 100644
index 0000000000..1b704da8f1
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.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/process/2026-08-04-forward-only-pr-issue-status.md
+2026-08-04-forward-only-pr-issue-status.md: dd567707bc7fccd0a631943ab3ffd2838a7f2f76
+2026-08-04-forward-only-pr-issue-status.zh.md: f19cceafbde074d298a7c7f27829c8ab919f00b6
diff --git a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.md b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.md
new file mode 100644
index 0000000000..dd567707bc
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.md
@@ -0,0 +1,39 @@
+# Agent Note: Forward-only PR-to-Issue status projection
+
+Status: implemented
+
+English | [中文](2026-08-04-forward-only-pr-issue-status.zh.md)
+
+## Problem
+
+The Issue Project status represents the phase of the work, while an exact same-repository resolving keyword establishes the authoritative PR-to-Issue relationship. Restricting lifecycle advancement to Issues already in `Ready` leaves an Issue in `Inbox` or `Backlog` after implementation has demonstrably started. Requiring otherwise valid PR metadata before projecting the phase also conflates policy compliance with the work's observable state.
+
+## Decision
+
+PR and PR-review events project the current PR phase to every exact same-repository resolving Issue. A draft PR, or a non-draft PR without a review request or submitted review, targets `In progress`. A non-draft PR with either form of review activity targets `In review`.
+
+The active statuses have the order `Inbox`, `Backlog`, `Ready`, `In progress`, and `In review`. Projection writes only when the target is later in that order. It does not move an Issue backward, alter `Done` or `No action`, or add an Issue that has no Project status. The lifecycle path is independent of PR metadata validation; the separate required PR policy check continues to enforce labels, references, and priority consistency.
+
+This projection is intentionally one-way. It does not query from an Issue to related PRs, and it does not add a scheduled reconciler. PR events are the source of lifecycle advancement. The pure transition decision is exercised by the Issue-management test and that test runs in the `check-all`, `ci-primary`, and `ci-static` gates.
+
+## Verification
+
+`.github/issue-management/policy.test.mjs` covers advancement from every earlier active status, the draft and review distinctions, metadata-policy independence, and protection against backward or terminal transitions. `scripts/run-gates.ts` owns execution of that focused policy test in top-level local and CI gate modes.
+
+## Alternatives considered
+
+**Require `Ready` as the only source status.** This preserves a manual prerequisite but leaves stale `Inbox` and `Backlog` items even though the resolving PR proves implementation has begun.
+
+**Add bidirectional or scheduled reconciliation.** Looking up PRs from Issue events or sweeping the Project could repair more histories, but it adds another authority direction and recurring API work beyond the required PR-driven lifecycle.
+
+**Gate projection on complete PR metadata.** Labels, references, and priority still require enforcement, but a metadata defect does not make the implementation or review phase untrue.
+
+**Move statuses backward when a PR becomes a draft or loses reviewers.** That would make transient PR state overwrite a later observed work phase and complicate status ownership. Projection therefore remains monotonic.
+
+## Consequences
+
+- A PR event self-corrects a resolving Issue left in `Inbox`, `Backlog`, or `Ready`.
+- An Issue created after the last relevant PR event waits for a later PR event or a manual status update because there is no reverse lookup or scheduled sweep.
+- A draft PR remains `In progress` even if it has historical review activity; only a non-draft PR targets `In review`.
+- Terminal statuses and later active statuses remain protected from regression.
+- PR metadata failures remain visible through the required policy check without suppressing lifecycle projection.
diff --git a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md
new file mode 100644
index 0000000000..f19cceafbd
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: PR 到 Issue 的状态仅向前投射
+
+Status: implemented
+
+[English](2026-08-04-forward-only-pr-issue-status.md) | 中文
+
+## 问题
+
+Issue Project 状态表示工作所处阶段，同仓库内精确匹配的解决型关键字引用则建立权威的 PR（Pull Request）到 Issue 关系。若仅允许已处于 `Ready` 的 Issue 推进生命周期，即使实现已经明确开始，处于 `Inbox` 或 `Backlog` 的 Issue 仍会停留在原状态。只有 PR 元数据在其他方面均有效时才投射工作阶段，也会把政策合规性与可观察到的工作状态混为一谈。
+
+## 决策
+
+PR 事件和 PR 评审事件会把当前 PR 阶段投射到同仓库内被精确引用的每个解决型 Issue。草稿 PR，或既没有评审请求也没有已提交评审的非草稿 PR，目标状态为 `In progress`。具备上述任一类评审活动的非草稿 PR，目标状态为 `In review`。
+
+活跃状态依次为 `Inbox`、`Backlog`、`Ready`、`In progress` 和 `In review`。只有目标状态在该顺序中位于当前状态之后时，投射才会写入。投射不会把 Issue 状态向后移动，不会改动 `Done` 或 `No action`，也不会把没有 Project 状态的 Issue 加入 Project。生命周期路径独立于 PR 元数据校验；另行执行的必需 PR 政策检查继续强制落实标签、引用和优先级一致性。
+
+这项投射刻意保持单向。它不会从 Issue 反查关联 PR，也不会添加定时对账任务。PR 事件是推进生命周期的来源。Issue 管理测试会验证纯函数实现的状态转换决策，并且该测试会在 `check-all`、`ci-primary` 和 `ci-static` 门禁中运行。
+
+## 验证
+
+`.github/issue-management/policy.test.mjs` 覆盖从所有更早活跃状态推进、区分草稿与评审状态、独立于元数据政策，以及防止状态倒退或改动终态。`scripts/run-gates.ts` 负责在顶层本地门禁模式和 CI 门禁模式中执行这项专项政策测试。
+
+## 考虑过的替代方案
+
+**仅允许从 `Ready` 状态推进。** 这种方案保留了人工前置条件，但解决型 PR 已经证明实现开始后，仍会让处于 `Inbox` 和 `Backlog` 的条目保持陈旧状态。
+
+**增加双向或定时对账。** 由 Issue 事件反查 PR，或定期扫描 Project，可以修复更多历史遗留状态；但这会新增一条反向的权威状态更新路径，并增加周期性 API 工作量，超出所需的 PR 驱动生命周期范围。
+
+**以完整的 PR 元数据作为投射前提。** 标签、引用和优先级仍须强制落实，但元数据缺陷并不能否定工作实际处于实现或评审阶段。
+
+**PR 转为草稿或失去评审人时将状态向后移动。** 这会让临时的 PR 状态覆盖已经观察到的更靠后工作阶段，也会使状态所有权更复杂。因此，投射保持单调。
+
+## 后果
+
+- PR 事件会自动纠正停留在 `Inbox`、`Backlog` 或 `Ready` 的解决型 Issue。
+- 若 Issue 创建于最后一个相关 PR 事件之后，则必须等待后续 PR 事件或人工更新状态，因为系统不会反向查找或定时扫描。
+- 即使存在历史评审活动，草稿 PR 仍保持 `In progress`；只有非草稿 PR 才会以 `In review` 为目标状态。
+- 终态以及顺序中更靠后的活跃状态不会倒退。
+- 必需的政策检查仍会暴露 PR 元数据错误，而不会因此阻止生命周期投射。
diff --git a/.github/issue-management/policy.mjs b/.github/issue-management/policy.mjs
index 4c9242bab5..73703bd199 100644
--- a/.github/issue-management/policy.mjs
+++ b/.github/issue-management/policy.mjs
@@ -12,6 +12,7 @@ const AUDIT_MARKER = '<!-- dsh-issue-policy -->'
 const OWNER_LINE = /^Owner: @([A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?)$/
 const TYPES = new Set(['Idea', 'Feature', 'Bug', 'Research', 'Task'])
 const PRIORITIES = ['p0', 'p1', 'p2', 'p3']
+const ACTIVE_STATUS_ORDER = ['Inbox', 'Backlog', 'Ready', 'In progress', 'In review']
 
 /**
  * Return Markdown outside balanced details elements.
@@ -129,6 +130,22 @@ export function requiresPullRequestPolicy({
   return !isDraft && !automated && (reviewRequestCount > 0 || reviewCount > 0)
 }
 
+/**
+ * Derive a forward-only Issue status from the current PR phase.
+ * @param {string|null} currentStatus Current Project status.
+ * @param {{isDraft: boolean, reviewRequestCount: number, reviewCount: number}} pull PR phase.
+ * @returns {string|null} Status to write, or null when no forward transition exists.
+ */
+export function nextResolvingIssueStatus(currentStatus, pull) {
+  const target =
+    !pull.isDraft && (pull.reviewRequestCount > 0 || pull.reviewCount > 0)
+      ? 'In review'
+      : 'In progress'
+  const currentIndex = ACTIVE_STATUS_ORDER.indexOf(currentStatus)
+  const targetIndex = ACTIVE_STATUS_ORDER.indexOf(target)
+  return currentIndex >= 0 && currentIndex < targetIndex ? target : null
+}
+
 function stripIgnoredMarkdown(body) {
   const lines = body.replace(/<!--[\s\S]*?-->/g, '').split(/\r?\n/)
   const kept = []
@@ -491,11 +508,13 @@ async function pullRequestSnapshot(number) {
   }
 }
 
-async function moveResolvingIssues(pull, from, to) {
+async function advanceResolvingIssues(pull) {
   for (const number of pull.references.resolving) {
     const current = await issueSnapshot(number)
-    if (!current || current.status !== from) continue
-    await setStatus(number, to)
+    if (!current) continue
+    const target = nextResolvingIssueStatus(current.status, pull)
+    if (!target) continue
+    await setStatus(number, target)
     await auditIssue(number)
   }
 }
@@ -530,12 +549,7 @@ async function runLifecycle(eventName, event) {
 
   if (eventName === 'pull_request' || eventName === 'pull_request_review') {
     const pull = await pullRequestSnapshot(event.pull_request.number)
-    const errors = validatePullRequest(pull)
-    if (errors.length > 0) return
-    await moveResolvingIssues(pull, 'Ready', 'In progress')
-    if (pull.reviewRequestCount > 0 || pull.reviewCount > 0) {
-      await moveResolvingIssues(pull, 'In progress', 'In review')
-    }
+    await advanceResolvingIssues(pull)
   }
 }
 
diff --git a/.github/issue-management/policy.test.mjs b/.github/issue-management/policy.test.mjs
index 8e0c253796..86750127a7 100644
--- a/.github/issue-management/policy.test.mjs
+++ b/.github/issue-management/policy.test.mjs
@@ -3,6 +3,7 @@ import test from 'node:test'
 
 import {
   countVisibleUnits,
+  nextResolvingIssueStatus,
   parseReferences,
   retainIssueReferences,
   requiresPullRequestPolicy,
@@ -191,6 +192,49 @@ test('requires policy only after a human PR enters review', () => {
   )
 })
 
+test('advances resolving Issues to the live PR phase', () => {
+  const draft = { isDraft: true, reviewRequestCount: 1, reviewCount: 4 }
+  const open = { isDraft: false, reviewRequestCount: 0, reviewCount: 0 }
+  const requestedReview = { isDraft: false, reviewRequestCount: 1, reviewCount: 0 }
+  const submittedReview = { isDraft: false, reviewRequestCount: 0, reviewCount: 1 }
+
+  for (const status of ['Inbox', 'Backlog', 'Ready']) {
+    assert.equal(nextResolvingIssueStatus(status, draft), 'In progress')
+    assert.equal(nextResolvingIssueStatus(status, open), 'In progress')
+    assert.equal(nextResolvingIssueStatus(status, requestedReview), 'In review')
+    assert.equal(nextResolvingIssueStatus(status, submittedReview), 'In review')
+  }
+  assert.equal(nextResolvingIssueStatus('In progress', requestedReview), 'In review')
+  assert.equal(nextResolvingIssueStatus('In progress', submittedReview), 'In review')
+})
+
+test('never regresses or reopens a resolving Issue', () => {
+  const implementation = { isDraft: false, reviewRequestCount: 0, reviewCount: 0 }
+  const review = { isDraft: false, reviewRequestCount: 0, reviewCount: 1 }
+
+  assert.equal(nextResolvingIssueStatus('In progress', implementation), null)
+  assert.equal(nextResolvingIssueStatus('In review', implementation), null)
+  assert.equal(nextResolvingIssueStatus('In review', review), null)
+  assert.equal(nextResolvingIssueStatus('Done', review), null)
+  assert.equal(nextResolvingIssueStatus('No action', review), null)
+  assert.equal(nextResolvingIssueStatus(null, review), null)
+})
+
+test('keeps lifecycle projection independent of PR metadata enforcement', () => {
+  const pull = {
+    isDraft: false,
+    authorType: 'User',
+    reviewRequestCount: 1,
+    reviewCount: 0,
+    labels: [],
+    references: { all: [2], resolving: [2], related: [] },
+    issues: new Map([[2, { priority: null }]]),
+  }
+
+  assert.ok(validatePullRequest(pull).length > 0)
+  assert.equal(nextResolvingIssueStatus('Inbox', pull), 'In review')
+})
+
 test('exempts Draft, Bot, and App PRs', () => {
   const invalid = {
     isDraft: false,
diff --git a/package.json b/package.json
index fef0a1eb53..fd7f5447ff 100644
--- a/package.json
+++ b/package.json
@@ -26,6 +26,7 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:issue-management": "node --test .github/issue-management/policy.test.mjs",
     "test:snapshot": "vitest run --config vitest.snapshot.config.ts",
     "test:snapshot:record": "DSH_SNAPSHOT=record vitest run --config vitest.snapshot.config.ts --update",
     "test:snapshot:refresh": "DSH_SNAPSHOT=refresh vitest run --config vitest.snapshot.config.ts",
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 74d90a547d..956617c024 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -224,6 +224,7 @@ export function gatesForMode(selected: Mode): Gate[] {
         pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
         pnpmScript('client-domain-graph', 'verify-client-domain-graph', { label: 'client domain graph' }),
         pnpmScript('test', 'test'),
+        pnpmScript('issue-management', 'test:issue-management', { label: 'Issue management policy' }),
         pnpmScript('duplication', 'duplication'),
         snapshotGate(),
         pnpmScript('build', 'build'),
@@ -246,6 +247,7 @@ function ciPrimaryGates(): Gate[] {
     pnpmScript('constraints', 'constraints'),
     pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }),
     pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
+    pnpmScript('issue-management', 'test:issue-management', { label: 'Issue management policy' }),
     pnpmScript('typecheck', 'typecheck'),
     lintGate(),
     pnpmScript('duplication', 'duplication'),
@@ -343,6 +345,7 @@ function ciStaticGates(options: { ownsBuild: boolean }): Gate[] {
     pnpmScript('constraints', 'constraints'),
     pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }),
     pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
+    pnpmScript('issue-management', 'test:issue-management', { label: 'Issue management policy' }),
     ...options.ownsBuild ? [pnpmScript('build', 'build')] : [],
     ...docSyncLeafGates({
       includeDocTypecheck: options.ownsBuild,

From 7aa0ae34b372bb5b91571830c416c661da1ae33f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 4 Aug 2026 18:12:55 +0800
Subject: [PATCH 024/516] fix: harden issue status projection

---
 .github/issue-management/policy.mjs | 23 ++++++++++++++++-------
 scripts/run-gates.ts                | 14 ++++++++------
 2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/.github/issue-management/policy.mjs b/.github/issue-management/policy.mjs
index 73703bd199..608291c4f8 100644
--- a/.github/issue-management/policy.mjs
+++ b/.github/issue-management/policy.mjs
@@ -12,7 +12,12 @@ const AUDIT_MARKER = '<!-- dsh-issue-policy -->'
 const OWNER_LINE = /^Owner: @([A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?)$/
 const TYPES = new Set(['Idea', 'Feature', 'Bug', 'Research', 'Task'])
 const PRIORITIES = ['p0', 'p1', 'p2', 'p3']
-const ACTIVE_STATUS_ORDER = ['Inbox', 'Backlog', 'Ready', 'In progress', 'In review']
+const TERMINAL_STATUSES = new Set(['Done', 'No action'])
+const ACTIVE_STATUS_ORDER = config.statuses.filter((status) => !TERMINAL_STATUSES.has(status))
+
+for (const status of ['In progress', 'In review']) {
+  if (!ACTIVE_STATUS_ORDER.includes(status)) throw new Error(`config.statuses 缺少 ${status}`)
+}
 
 /**
  * Return Markdown outside balanced details elements.
@@ -418,8 +423,7 @@ async function ensureProjectItem(number) {
   }
 }
 
-async function setStatus(number, status) {
-  const context = await ensureProjectItem(number)
+async function updateStatus(context, status) {
   const option = context.statusField.options.find((candidate) => candidate.name === status)
   if (!option) throw new Error(`Status 不存在：${status}`)
   if (context.item.fieldValueByName?.name === status) return
@@ -441,6 +445,10 @@ async function setStatus(number, status) {
   )
 }
 
+async function setStatus(number, status) {
+  await updateStatus(await ensureProjectItem(number), status)
+}
+
 async function upsertAudit(number, errors) {
   const comments = await api(
     `/repos/${config.organization}/${config.repository}/issues/${number}/comments?per_page=100`,
@@ -510,11 +518,12 @@ async function pullRequestSnapshot(number) {
 
 async function advanceResolvingIssues(pull) {
   for (const number of pull.references.resolving) {
-    const current = await issueSnapshot(number)
-    if (!current) continue
-    const target = nextResolvingIssueStatus(current.status, pull)
+    const context = await projectContext(number)
+    const target = nextResolvingIssueStatus(context.item?.fieldValueByName?.name ?? null, pull)
     if (!target) continue
-    await setStatus(number, target)
+    // TODO: Replace this latest-state guard with per-Issue serialization or a
+    // conditional ProjectV2 update; GraphQL currently has no compare-and-swap.
+    await updateStatus(context, target)
     await auditIssue(number)
   }
 }
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 956617c024..7503c77072 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -241,13 +241,19 @@ export function gatesForMode(selected: Mode): Gate[] {
   }
 }
 
-function ciPrimaryGates(): Gate[] {
+function ciSharedStaticGates(): Gate[] {
   return [
     pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }),
     pnpmScript('constraints', 'constraints'),
     pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }),
     pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
     pnpmScript('issue-management', 'test:issue-management', { label: 'Issue management policy' }),
+  ]
+}
+
+function ciPrimaryGates(): Gate[] {
+  return [
+    ...ciSharedStaticGates(),
     pnpmScript('typecheck', 'typecheck'),
     lintGate(),
     pnpmScript('duplication', 'duplication'),
@@ -341,11 +347,7 @@ function runningNodeMajor(): number {
 
 function ciStaticGates(options: { ownsBuild: boolean }): Gate[] {
   return [
-    pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }),
-    pnpmScript('constraints', 'constraints'),
-    pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }),
-    pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
-    pnpmScript('issue-management', 'test:issue-management', { label: 'Issue management policy' }),
+    ...ciSharedStaticGates(),
     ...options.ownsBuild ? [pnpmScript('build', 'build')] : [],
     ...docSyncLeafGates({
       includeDocTypecheck: options.ownsBuild,

From 590b76a7f018d61a13c89155904bb6e4fc4e8df1 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 5 Aug 2026 11:18:06 +0800
Subject: [PATCH 025/516] fix(config): close the review findings on
 configuration source ownership
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two had real security consequences:

The bootstrap rejection ran on npm dotenv's parser while process.loadEnvFile
applied the file with Node's own. Two independently maintained dialects meant
the check and the thing it guards could disagree: a name Node accepts but the
checker misses would reach process.env unchecked, and BASH_ENV there runs a
file of the project's choosing on every `bash -c` the bash tool issues. Parse
once with node:util's parseEnv — the same engine loadEnvFile uses — and assign
the entries already checked, which also drops the dotenv dependency.

llm-pi-ai still returned a literal profile.apiKey ahead of everything, and it
registers a settings namespace, so the defect removed from llm-deepseek
survived intact in its design twin. The field is gone from the profile schema,
the resolution path, and the tests.

The rest are consistency and documentation defects the review named:

- verify-config-source-ownership did not scan the Python runtime's bundled
  cordis.yml, which still inlined apiKey and baseURL. Both are covered now, and
  the line-anchored INLINE_DENY documents that it is a tripwire, not a parser.
- The deny list missed NODE_TLS_REJECT_UNAUTHORIZED, the askpass hooks, the
  GIT_CONFIG_* redirections, and PYTHONHOME — all implied by its own stated
  rule about what a variable does.
- Snapshot lookups folded case on Windows, where environment names are
  case-insensitive and an exact-match Map could miss a higher-ranked layer.
- The credentials note claimed a read-time permission check was "not taken"
  while this PR implemented it; the credentials-local README still described
  two layers, live process.env reads, dotenv-era limitations, and a renamed
  anchor; the llm-deepseek README still advertised the removed literal apiKey;
  and web.ts and base.cordis.yml kept personal-overlay wording.
- The ownership note's literal-apiKey claim now names its scope: the
  web-search providers keep a literal field but register no settings
  namespace, so nothing can shadow a stored credential through them.
---
 ...4-configuration-source-ownership.i18n.yaml |  4 +-
 ...26-08-04-configuration-source-ownership.md |  2 +-
 ...08-04-configuration-source-ownership.zh.md |  2 +-
 ...-yaml-and-user-environment-layer.i18n.yaml |  4 +-
 ...entials-yaml-and-user-environment-layer.md |  2 +-
 ...ials-yaml-and-user-environment-layer.zh.md |  2 +-
 THIRD_PARTY_NOTICES.md                        |  1 -
 apps/cli/config/base.cordis.yml               |  5 ++-
 apps/cli/src/web.ts                           |  2 +-
 docs/config-catalog.md                        |  4 +-
 .../credentials.i18n.yaml                     |  4 +-
 docs/core-data-structures/credentials.md      |  2 +-
 docs/core-data-structures/credentials.zh.md   |  2 +-
 .../credentials-local/README.i18n.yaml        |  4 +-
 .../credentials/credentials-local/README.md   | 24 +++++++----
 .../credentials-local/README.zh.md            | 24 +++++++----
 .../credentials-local/src/index.ts            |  6 +--
 packages/credentials/credentials/src/index.ts |  2 +-
 packages/llm/llm-deepseek/README.i18n.yaml    |  4 +-
 packages/llm/llm-deepseek/README.md           |  4 +-
 packages/llm/llm-deepseek/README.zh.md        |  6 +--
 .../llm-deepseek/tests/dynamic-config.spec.ts |  6 +--
 packages/llm/llm-pi-ai/src/config.ts          |  6 ---
 packages/llm/llm-pi-ai/src/index.ts           |  1 -
 packages/llm/llm-pi-ai/tests/adapter.spec.ts  | 40 ++++++++++++-------
 .../llm-pi-ai/tests/dynamic-config.spec.ts    | 26 +++++++++---
 .../llm/llm-pi-ai/tests/sdk-options.spec.ts   |  2 +-
 packages/ui/app-boot/package.json             |  1 -
 packages/ui/app-boot/src/index.ts             | 32 +++++++++++----
 packages/util/environment/src/index.ts        | 32 +++++++++++++--
 pnpm-lock.yaml                                |  9 -----
 .../runtime/cordis.yml                        |  9 ++---
 scripts/verify-config-source-ownership.ts     | 16 +++++++-
 33 files changed, 180 insertions(+), 110 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 0bc04dc2bb..cbce8a65e8 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: 101c0e6ba4954b3fbb418b775322a9fd92c46a8c
-2026-08-04-configuration-source-ownership.zh.md: ad59f9a96e144dd5078898da57195a8bb6897451
+2026-08-04-configuration-source-ownership.md: 97daf3c430ba09c000eab947e159030568a7f89d
+2026-08-04-configuration-source-ownership.zh.md: 424c47d36f47136669f4e02f980e63cabd203f9c
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index 101c0e6ba4..97daf3c430 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -56,7 +56,7 @@ The line is that these take effect with no user action, before any turn, outside
 - A `.env` holding `DSH_*`, `PATH`, or a proxy variable fails the launch instead of being applied. Developers keeping switches in a repository `.env` move them to their shell — a deliberate, loud break.
 - `--config` is no longer overridable by a stale shell endpoint. It is still overridable by a user's stored `settings.yaml`, which is the settings seam's layering and not something this note changes; a deployment that must win against stored settings uses `--config-replace`.
 - Not solved: the layers are still materialized into `process.env`, so ordinary project variables continue to reach child processes under the subprocess scrub. Bootstrap variables cannot come from a file at all, which closes the escalation path; a project `.env` setting something like `GIT_SSH_COMMAND` for the tools an agent runs remains possible and is recorded as a limitation on the package.
-- The adapters no longer accept a literal `apiKey`: configuration carries the reference and nothing else, so a settings document cannot become a second credential store. No adapter namespace is strict, so writing one is dropped rather than rejected.
+- The LLM adapters no longer accept a literal `apiKey`: configuration carries the reference and nothing else, so a settings document cannot become a second credential store. No adapter namespace is strict, so writing one is dropped rather than rejected. The web-search providers still declare a `role('secret')` literal key; they register no settings namespace, so nothing can shadow a stored credential through them, but the claim is about the adapters rather than the repository as a whole.
 - Exa and Perplexity still capture their key at load time rather than through the credential seam. They no longer read raw `process.env` — they resolve through the trusted layers — but converting them to per-request seam resolution is separate work.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index ad59f9a96e..424c47d36f 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -58,7 +58,7 @@ inherited process environment      (read-only, wins)
 - 含 `DSH_*`、`PATH` 或 proxy 变量的 `.env` 会导致启动失败而不是被应用。把开关放在仓库 `.env` 里的开发者需要改放到 shell——这是一次刻意且响亮的破坏。
 - `--config` 不再会被陈旧的 shell endpoint 覆盖。但它仍然会被用户已存的 `settings.yaml` 覆盖，这是 settings seam 的分层方式，本 Note 不改变它；需要压过已存 settings 的部署方应使用 `--config-replace`。
 - 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件，提权路径已封闭；项目 `.env` 为 agent 运行的工具设置诸如 `GIT_SSH_COMMAND` 之类的变量仍然可能，已作为限制记录在该包上。
-- 适配器不再接受字面 `apiKey`：配置只携带引用，因此 settings 文档无法成为第二个凭据存储。由于没有任何适配器 namespace 是 strict 的，写入该键会被 schema 丢弃而不是报错。
+- LLM 适配器不再接受字面 `apiKey`：配置只携带引用，因此 settings 文档无法成为第二个凭据存储。由于没有任何适配器 namespace 是 strict 的，写入该键会被 schema 丢弃而不是报错。web-search 提供方仍声明 `role('secret')` 的字面密钥字段；它们不注册 settings namespace，因此无法借此遮蔽已存凭据，但这条声明的范围是适配器，而不是整个仓库。
 - Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求经 seam 解析是另一件事。
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
index eb74fbd0e2..376838d151 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.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 .agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
-2026-08-04-credentials-yaml-and-user-environment-layer.md: f1bca69820d03fe67849bd7c7159489ac27cd2e0
-2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 7e6714abd33baad1fb2a570514754b467fcf8bd5
+2026-08-04-credentials-yaml-and-user-environment-layer.md: f03f3f885c13476619ba3cda51e2dfed7e3258c1
+2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 7cce1daeffadb18678f00a5c9acd1b14c6ac1b22
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
index f1bca69820..f03f3f885c 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
@@ -34,7 +34,7 @@ There is no migration. The product is unreleased, and a key already in `$DSH_HOM
 - Given up: a key left in `$DSH_HOME/.env` is now hoisted into `process.env`, so it reaches subprocesses under the [subprocess credential scrub](../../../../packages/subprocess/subprocess/README.md) rather than staying inside the provider. That is the honest meaning of "ordinary environment layer"; a secret the Harness should own and isolate belongs in `.credentials.yaml`, which is never hoisted.
 - Given up: the same key shadows `.credentials.yaml` and makes the web Models page's write reject. The seam already reports `source: 'env', writable: false` for that state, and the rejection message now names the loaded `.env` as a place to unset it.
 - Bought: a non-secret in the user's `.env` finally takes effect, which was the original defect; the document format can reject what it cannot serve; and `0600` covers a file that holds only secrets instead of a file users are told to put ordinary configuration in.
-- Not taken: a read-time permission check that fails startup when `.credentials.yaml` is more permissive than `0600`. Creation and atomic replacement already pin the mode; making a hand-created file fatal is a separable security decision.
+- The `0600` the provider writes is also enforced on what it reads: on POSIX, a document with any group or other permission bit fails the launch before its contents are read, at boot and on every reload, and the diagnostic names the `chmod 600` repair. Windows has no mode to inspect — its ACLs are not expressible here — so the check is skipped rather than faked.
 - The `0600` boundary still stops other OS users and not the model, unchanged by this split — the [provider README](../../../../packages/credentials/credentials-local/README.md) owns that limit and the keychain-provider deferral.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
index 7e6714abd3..7cce1daeff 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
@@ -34,7 +34,7 @@ OPENAI_API_KEY: sk-…
 - 放弃的：留在 `$DSH_HOME/.env` 里的密钥现在会被提升进 `process.env`，因而会按[子进程凭据清洗](../../../../packages/subprocess/subprocess/README.md)的规则抵达子进程，而不再留在 provider 内部。这就是「普通环境层」的诚实含义；需要由 Harness 拥有并隔离的密钥属于 `.credentials.yaml`，后者永不提升。
 - 放弃的：同一个键会遮蔽 `.credentials.yaml`，并让 Web Models 页的写入被拒。seam 对这种状态本来就报告 `source: 'env', writable: false`，而拒绝信息现在会把已加载的 `.env` 一并指为需要清除的位置。
 - 换来的：用户 `.env` 里的非密钥值终于生效，这正是最初的缺陷；文档格式可以拒绝它无法承担的内容；`0600` 保护的是一个只存密钥的文件，而不是一个我们同时叫用户往里写普通配置的文件。
-- 未采纳的：在读取时校验权限、并在 `.credentials.yaml` 宽于 `0600` 时让启动失败。创建与原子替换已经钉住了模式；让手工创建的文件直接致命是一个可分离的安全决策。
+- provider 写入时用的 `0600` 同样约束它读取的内容：在 POSIX 上，只要文档带有任何 group 或 other 权限位，就会在读取内容之前让启动失败——启动时与每次 reload 都检查，诊断里给出 `chmod 600` 的修复命令。Windows 没有可检查的 mode（其 ACL 无法在此表达），因此跳过该检查而不是伪造它。
 - `0600` 这条边界仍然只挡其他 OS 用户、挡不住模型，本次拆分未改变这一点——该限制及 keychain provider 的延后项归 [provider README](../../../../packages/credentials/credentials-local/README.md) 所有。
 
 ## Alternatives considered
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 8cd2964da6..ca83c91965 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -52,7 +52,6 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`clsx`](https://github.com/lukeed/clsx) | MIT |
 | [`commander`](https://github.com/tj/commander.js) | MIT |
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
-| [`dotenv`](https://github.com/motdotla/dotenv) | BSD-2-Clause |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
 | [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT |
 | [`immer`](https://github.com/immerjs/immer) | MIT |
diff --git a/apps/cli/config/base.cordis.yml b/apps/cli/config/base.cordis.yml
index 213841f58d..421a831362 100644
--- a/apps/cli/config/base.cordis.yml
+++ b/apps/cli/config/base.cordis.yml
@@ -22,8 +22,9 @@
 
 # A `--config` overlay replaces this row's config to select exact GitHub
 # repository Plugin generations. The app registers the DSH-owned runtime even
-# when the list is empty so a later personal-config edit can load
-# transactionally; one-shot headless runs consume the startup value only.
+# when the list is empty, so a `--config` overlay that supplies repositories
+# needs no composition change here. Every surface reads that overlay once at
+# startup.
 - id: repository-plugins
   name: '@deepseek-ai/dsh-repository-plugin'
 
diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts
index ab4f195423..0265e3fe6a 100644
--- a/apps/cli/src/web.ts
+++ b/apps/cli/src/web.ts
@@ -95,7 +95,7 @@ export function prepareWebRuntimeContext(ctx: Context, sourceRoot: string, mode:
  * @param trustedHosts - extra authorities for the /api browser-trust fence, or `undefined` for the derived LAN literals alone.
  * @param config - an overlay of loader patches applied over the shipped web
  * composition, or `undefined` to boot the
- * personal overlay; already parsed from `--config`.
+ * shipped Web composition; already parsed from `--config`.
  */
 export async function runWeb(
   environment: EnvironmentSnapshot,
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 3646f58fb7..0d5c71648f 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -682,8 +682,6 @@ export interface Config {
 
 /** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */
 export interface PiAiProviderProfile {
-  /** Literal provider credential; prefer {@link apiKeyEnv}. With both absent pi-ai uses its provider-native ambient discovery. */
-  apiKey?: string
   /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */
   apiKeyEnv?: string
   /** Override the selected catalog model's endpoint without changing its protocol metadata. */
@@ -711,7 +709,7 @@ export interface PiAiProviderProfile {
 
 Depends on: `CacheRetention` (`@earendil-works/pi-ai`) · `ModelThinkingLevel` (`@earendil-works/pi-ai`) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) · `ThinkingBudgets` (`@earendil-works/pi-ai`) · `Transport` (`@earendil-works/pi-ai`)
 
-Source: [`packages/llm/llm-pi-ai/src/config.ts:62`](../packages/llm/llm-pi-ai/src/config.ts)
+Source: [`packages/llm/llm-pi-ai/src/config.ts:60`](../packages/llm/llm-pi-ai/src/config.ts)
 
 ## `@deepseek-ai/dsh-llm-replay`
 
diff --git a/docs/core-data-structures/credentials.i18n.yaml b/docs/core-data-structures/credentials.i18n.yaml
index 23bb940afe..d44275d97e 100644
--- a/docs/core-data-structures/credentials.i18n.yaml
+++ b/docs/core-data-structures/credentials.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 docs/core-data-structures/credentials.md
-credentials.md: 3f6fcd127d01e2c49e17c70c002bebe9f363e951
-credentials.zh.md: b5d2d9e164a85ce090790635c438b768cae4c9ca
+credentials.md: ef74ddeb4346e18f8d5d33488657e5d50f1d754e
+credentials.zh.md: 09cf374a2346fd93aa834e3372321e6eeece6ed8
diff --git a/docs/core-data-structures/credentials.md b/docs/core-data-structures/credentials.md
index 3f6fcd127d..ef74ddeb43 100644
--- a/docs/core-data-structures/credentials.md
+++ b/docs/core-data-structures/credentials.md
@@ -24,7 +24,7 @@ type CredentialRef = Branded<'CredentialRef'>
 interface ResolvedCredential {
   /** The non-empty secret value. */
   value: string
-  /** Provider-defined source layer id (the local provider uses `env` and `file`). */
+  /** Provider-defined source layer id (the local provider uses `env`, `file`, `project-env`, and `user-env`). */
   source: string
 }
 ```
diff --git a/docs/core-data-structures/credentials.zh.md b/docs/core-data-structures/credentials.zh.md
index b5d2d9e164..09cf374a23 100644
--- a/docs/core-data-structures/credentials.zh.md
+++ b/docs/core-data-structures/credentials.zh.md
@@ -24,7 +24,7 @@ type CredentialRef = Branded<'CredentialRef'>
 interface ResolvedCredential {
   /** The non-empty secret value. */
   value: string
-  /** Provider-defined source layer id (the local provider uses `env` and `file`). */
+  /** Provider-defined source layer id (the local provider uses `env`, `file`, `project-env`, and `user-env`). */
   source: string
 }
 ```
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index fc89d359e8..729ae6f958 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-local/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/credentials/credentials-local/README.md
-README.md: ca2af9d8a514b43aeef19abec7cda4e44645bdaf
-README.zh.md: a8be53629853fe6fb7c39ef2281ac798b5624010
+README.md: 45c18714c9ca81d98d2c18c385c772545e2e15d1
+README.zh.md: 59e0158980cede3eb3f5590b00f858ddffcee328
diff --git a/packages/credentials/credentials-local/README.md b/packages/credentials/credentials-local/README.md
index ca2af9d8a5..45c18714c9 100644
--- a/packages/credentials/credentials-local/README.md
+++ b/packages/credentials/credentials-local/README.md
@@ -2,14 +2,20 @@
 
 English | [中文](README.zh.md)
 
-File-backed [credentials](../credentials/README.md) provider: two layers, one honest precedence.
+File-backed [credentials](../credentials/README.md) provider: four layers, one honest precedence.
 
 | Layer | Source id | Writable | Wins |
 |---|---|---|---|
-| Live process environment | `env` | no | always |
-| `$DSH_HOME/.credentials.yaml` document | `file` | yes (`set`/`unset`) | otherwise |
+| Inherited process environment | `env` | no | always |
+| `$DSH_HOME/.credentials.yaml` document | `file` | yes (`set`/`unset`) | over both `.env` layers |
+| `<invocation cwd>/.env` | `project-env` | not here | over the user `.env` |
+| `$DSH_HOME/.env` | `user-env` | not here | otherwise |
 
-The environment wins because a launch-time override (`DEEPSEEK_API_KEY=… dsh`, CI secrets, a dev shell sourcing the repo `.env`) is operator intent for this run — and because it cannot be edited from inside, it must be *visibly* read-only: `describe()` reports `source: 'env', writable: false`, and `set`/`unset` reject instead of writing a change the reader would never see. Resolution reads `process.env` live and never writes it back.
+The launching environment wins because a per-run override (`DEEPSEEK_API_KEY=… dsh`, a CI secret, a container `-e`) is operator intent for this run — and because it cannot be edited from inside, it must be *visibly* read-only: `describe()` reports `source: 'env', writable: false`, and `set`/`unset` reject instead of writing a change the reader would never see.
+
+Everything below it loses to the managed store, so a key written by the web page or TUI takes effect immediately even when an older key sits in a `.env`. Those two layers still resolve when nothing is stored, and `describe()` names them `project-env` or `user-env` with `writable: true` — storing a key replaces them as the effective source.
+
+Under the product CLI, resolution reads the launcher's frozen [environment snapshot](../../util/environment/README.md) rather than `process.env`: only the snapshot can say whether a value came from the launching shell or from a file. A composition the product CLI did not boot has the inherited environment as its only layer, which keeps embedders on the semantics they already had.
 
 ## Config
 
@@ -35,13 +41,17 @@ Writes patch the parsed document rather than rebuilding it, so comments and the
 
 Any string value round-trips, multi-line values included, so no entry is unwritable for want of a quoting style. An empty stored value is absent, per the seam rule — which is why an empty string in the document is rejected outright: `unset` removes a key, it does not blank it.
 
+## Permissions
+
+The provider creates the directory `0700` and creates or atomically replaces the document `0600`. It holds what it *reads* to that same bound: on POSIX a document carrying any group or other permission bit fails before its contents are parsed — at boot and on every reload — and the error names the `chmod 600` repair. Windows has no mode to inspect, so the check is skipped there rather than faked.
+
 ## Hot reload
 
 External edits publish `credentials/updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable or invalid document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable or invalid file at boot fails loud.
 
 ## Security boundary
 
-The document is `0600` under a `0700` directory, which stops other OS users — **not** the model. Tool processes (bash, the filesystem tools) run as the same user, and the shipped `workspace-write` file policy confines mutations rather than reads, so they can read this file exactly like any other file the user owns; no sandbox mode singles it out. What the harness does hold to is narrower: it never hands the model a resolved path to the document, and never loads it into the process environment — unlike `$DSH_HOME/.env`, which is the user's ordinary environment layer (see [app-boot's Personal config](../../ui/app-boot/README.md#personal-config)) — so reaching the value takes a deliberate read of a path the agent was not given.
+The document is `0600` under a `0700` directory, which stops other OS users — **not** the model. Tool processes (bash, the filesystem tools) run as the same user, and the shipped `workspace-write` file policy confines mutations rather than reads, so they can read this file exactly like any other file the user owns; no sandbox mode singles it out. What the harness does hold to is narrower: it never hands the model a resolved path to the document, and never loads it into the process environment — unlike `$DSH_HOME/.env`, which is the user's ordinary environment layer (see [app-boot's Harness home](../../ui/app-boot/README.md#the-harness-home)) — so reaching the value takes a deliberate read of a path the agent was not given.
 
 That is discretion, not a boundary. A deployment that must keep provider keys away from its own agent cannot get there with file permissions; an OS-keychain provider — a store the model's processes cannot read at all — is the deferred answer and belongs beside this provider as a sibling package.
 
@@ -55,9 +65,7 @@ No direct invalidation; credentials never enter a request prefix.
 
 ## Known Limitations and Deferred Work
 
-- **Multi-line entries refuse `set`/`unset`** — the line editor will not rewrite an entry it would corrupt; `describe` reports them `writable: false` and edits must go to the file directly.
 - **Same-reference concurrent writes are last-write-wins** — the writer lock and the read-modify-write keep concurrent writers from dropping each other's entries, but two writers editing one reference still resolve to the later write; there is no revision check.
 - **A same-UID process can read the document** — see [Security boundary](#security-boundary): the file-effect sandbox modes do not deny reads, and an OS-keychain provider is deferred.
-- **Unrepresentable values fail loud** — control characters, or a mix of both quote styles with backslashes, cannot round-trip the dotenv line format.
-- **Environment changes are invisible** — `process.env` is read live per resolution, but no event can announce a change there.
+- **Environment changes are invisible** — the snapshot is frozen at launch, so a variable exported after startup reaches neither resolution nor `describe`; changing an environment-sourced credential takes a restart.
 - **Atomic, not crash-durable** — inherited from `dsh-atomic-write`; the store re-reads on boot.
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index a8be536298..59e0158980 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -2,14 +2,20 @@
 
 [English](README.md) | 中文
 
-文件型[凭据](../credentials/README.md) provider：两层来源，一条诚实的优先级。
+文件型[凭据](../credentials/README.md) provider：四层来源，一条诚实的优先级。
 
 | 层 | 来源 id | 可写 | 优先 |
 |---|---|---|---|
-| 活跃进程环境 | `env` | 否 | 恒定优先 |
-| `$DSH_HOME/.credentials.yaml` 文档 | `file` | 是（`set`/`unset`） | 其余情况 |
+| 继承的进程环境 | `env` | 否 | 恒定优先 |
+| `$DSH_HOME/.credentials.yaml` 文档 | `file` | 是（`set`/`unset`） | 高于两个 `.env` 层 |
+| `<invocation cwd>/.env` | `project-env` | 不在此处 | 高于用户 `.env` |
+| `$DSH_HOME/.env` | `user-env` | 不在此处 | 其余情况 |
 
-环境优先，因为启动时覆盖（`DEEPSEEK_API_KEY=… dsh`、CI 机密、加载了仓库 `.env` 的开发 shell）代表本次运行的操作者意图——而它无法从进程内部修改，就必须*可见地*只读：`describe()` 报告 `source: 'env', writable: false`，`set`/`unset` 直接拒绝，而不是写下一个读取方永远看不到的变更。解析实时读取 `process.env`，绝不写回。
+启动环境优先，因为按次覆盖（`DEEPSEEK_API_KEY=… dsh`、CI 机密、容器 `-e`）代表本次运行的操作者意图——而它无法从进程内部修改，就必须*可见地*只读：`describe()` 报告 `source: 'env', writable: false`，`set`/`unset` 直接拒绝，而不是写下一个读取方永远看不到的变更。
+
+它之下的一切都输给受管存储，因此 Web 页面或 TUI 写入的密钥会立即生效，即使某个 `.env` 里还留着更旧的密钥。没有存储任何东西时这两层仍会解析，`describe()` 会把来源报告为 `project-env` 或 `user-env` 且 `writable: true`——存入一个密钥就会取代它们成为生效来源。
+
+在产品 CLI（命令行界面）下，解析读取的是启动器冻结的[环境快照](../../util/environment/README.md)而不是 `process.env`：只有快照才说得清某个值来自启动 shell 还是来自某个文件。并非由产品 CLI 启动的组合只有继承环境这一层，这让嵌入方保持它们原有的语义。
 
 ## 配置
 
@@ -35,13 +41,17 @@ OPENAI_API_KEY: sk-…
 
 任何字符串值都能往返，包括多行值，因此不会再有条目因为缺少可用引号样式而不可写。空的存储值等于不存在（seam 规则）——这也正是文档中的空字符串被直接拒绝的原因：`unset` 删除键，而不是把它置空。
 
+## 权限
+
+provider 以 `0700` 创建目录，以 `0600` 创建或原子替换文档。它对*读取*同样守住这条界线：在 POSIX 上，只要文档带有任何 group 或 other 权限位，就会在解析其内容之前失败——启动时与每次 reload 都检查——并在错误里给出 `chmod 600` 的修复命令。Windows 没有可检查的 mode，因此在那里跳过该检查而不是伪造它。
+
 ## 热重载
 
 外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。provider 自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则响亮失败。
 
 ## 安全边界
 
-文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的个人配置](../../ui/app-boot/README.md#personal-config)）——因此要拿到这个值，需要刻意去读一条并未交给 agent 的路径。
+文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的 Harness home](../../ui/app-boot/README.md#the-harness-home)）——因此要拿到这个值，需要刻意去读一条并未交给 agent 的路径。
 
 这是审慎，不是边界。必须让提供方密钥远离自身 agent 的部署无法靠文件权限做到；OS 钥匙串 provider——一个模型的进程根本读不到的存储——才是延后的答案，它应当作为平级包与本 provider 并列。
 
@@ -55,9 +65,7 @@ OPENAI_API_KEY: sk-…
 
 ## Known Limitations and Deferred Work
 
-- **多行条目拒绝 `set`/`unset`**——行编辑器不改写会被它破坏的条目；`describe` 把它们报为 `writable: false`，编辑必须直接落到文件上。
 - **同一引用的并发写入是后写胜出**——写锁加读-改-写让并发写入者不会丢掉彼此的条目，但两个写入者编辑同一个引用时仍以较后的写入为准；没有修订检查。
 - **同 UID 进程可以读取该文档**——见[安全边界](#security-boundary)：文件效果沙箱模式不会拒绝读取，OS 钥匙串 provider 仍是延后项。
-- **无法表示的值响亮失败**——控制字符，或同时混用两种引号又含反斜杠的值，无法在 dotenv 行格式中往返。
-- **环境变化不可见**——每次解析实时读取 `process.env`，但那里的变化不可能发出事件。
+- **环境变化不可见**：快照在启动时冻结，因此启动之后 export 的变量既不会进入解析，也不会进入 `describe`；要更换来自环境的凭据需要重启。
 - **原子但不保证崩溃持久**——继承自 `dsh-atomic-write`；存储在启动时重新读取。
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index 1f0f550c05..a5024353c8 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -40,7 +40,7 @@ import z from 'schemastery'
 import { watch as chokidarWatch } from 'chokidar'
 import { mkdir, readFile, stat } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
-import { Document, parseDocument } from 'yaml'
+import { Document, parseDocument, type YAMLError } from 'yaml'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { environmentOf } from '@deepseek-ai/dsh-environment'
@@ -128,10 +128,10 @@ function isENOENT(error: unknown): boolean {
  * @param error - the parser's error.
  * @returns the error code with its line and column.
  */
-function describeYamlError(error: { code?: string; linePos?: [{ line: number; col: number }, ...unknown[]] }): string {
+function describeYamlError(error: YAMLError): string {
   const at = error.linePos?.[0]
   const where = at === undefined ? '' : ` at line ${String(at.line)}, column ${String(at.col)}`
-  return `${error.code ?? 'YAML_ERROR'}${where}`
+  return `${error.code}${where}`
 }
 
 /**
diff --git a/packages/credentials/credentials/src/index.ts b/packages/credentials/credentials/src/index.ts
index b640b42881..c6470c1628 100644
--- a/packages/credentials/credentials/src/index.ts
+++ b/packages/credentials/credentials/src/index.ts
@@ -32,7 +32,7 @@ export function credentialRef(value: string): CredentialRef {
 export interface ResolvedCredential {
   /** The non-empty secret value. */
   value: string
-  /** Provider-defined source layer id (the local provider uses `env` and `file`). */
+  /** Provider-defined source layer id (the local provider uses `env`, `file`, `project-env`, and `user-env`). */
   source: string
 }
 
diff --git a/packages/llm/llm-deepseek/README.i18n.yaml b/packages/llm/llm-deepseek/README.i18n.yaml
index 45d9cee054..d456e9282e 100644
--- a/packages/llm/llm-deepseek/README.i18n.yaml
+++ b/packages/llm/llm-deepseek/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/llm/llm-deepseek/README.md
-README.md: 020aa65073495526be3f32912b7cd06667c52a2e
-README.zh.md: 4c655e90ba00340c056f6ac16159621f7a8c1ddb
+README.md: b8619268fc264439184ad51d208996ebb3c64e66
+README.zh.md: 650185083e5b36bc8508bc3847f87bdf5e1c5678
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index 020aa65073..b8619268fc 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -15,7 +15,6 @@ The package root exposes the Cordis plugin contract and `DeepSeekAdapter`; wire
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
     apiKeyEnv: DEEPSEEK_API_KEY  # default; resolved per request via ctx.credentials, then the environment
-    # apiKey: …                  # literal escape hatch; prefer the reference so no secret enters this file
     baseURL: https://api.deepseek.com # optional; $DEEPSEEK_BASE_URL then the public API when omitted
     thinking: enabled        # optional; provider default is enabled
     reasoningEffort: high    # optional; off | high | max — omitted ⇒ high
@@ -53,7 +52,7 @@ The same exact-model result exposes ordered `off`, `high`, and `max` efforts und
 Connection facts are not frozen at load. `resolveAdapterOptions` is the one explicit resolve step from raw config to validated facts, and the adapter re-reads them through a thunk **once per operation**: base URL, catalog, request defaults, and idle budget all take effect on the next request, while an in-flight stream keeps the facts it started with. Two optional seams feed that thunk:
 
 - **`ctx.settings`** — the plugin registers the `llm-deepseek` namespace with this same `Config` schema and its `cordis.yml` entry as the composition `base`, so a `llm-deepseek:` section in the user settings document overrides any field without a restart. Without a mounted settings service the entry config alone drives the adapter, unchanged. A live settings snapshot that passes the schema but fails a beyond-schema bound (a duplicate catalog id, a broken thinking/effort pair) keeps the last good facts and logs the failure; the entry config itself still fails plugin load.
-- **`ctx.credentials`** — the API key resolves per stream call, from the *same* resolved snapshot that supplies the endpoint: a non-empty literal `apiKey` wins, then `apiKeyEnv` through the credential seam (`$DSH_HOME/.env` under the live environment), then — only without a mounted seam — the raw environment variable. Because credential facts travel with the connection facts, a settings snapshot the resolver rejects contributes neither its endpoint nor its key: the whole previous generation keeps serving. A request with no key anywhere fails with `MISSING_CREDENTIAL` naming every configuration entry point, while the route stays registered and the catalog stays browsable — first-run onboarding is "browse models, store the key, prompt again", with no restart between.
+- **`ctx.credentials`** — the API key resolves per stream call, from the *same* resolved snapshot that supplies the endpoint. Configuration carries only `apiKeyEnv`, never a literal key: the reference resolves through the credential seam, and without a mounted seam through the trusted environment layers. Because credential facts travel with the connection facts, a settings snapshot the resolver rejects contributes neither its endpoint nor its key: the whole previous generation keeps serving. A request with no key anywhere fails with `MISSING_CREDENTIAL` naming every configuration entry point, while the route stays registered and the catalog stays browsable — first-run onboarding is "browse models, store the key, prompt again", with no restart between.
 
 The one registration-captured fact is the retry policy: when its resolved value changes, the plugin re-registers the route in place (same adapter instance, one synchronous section), so `ctx.llm.providerRetryPolicy('deepseek-official')` always reports the current policy.
 
@@ -112,7 +111,6 @@ Loop-retained response blocks append to the next request and preserve its earlie
 ## Known Limitations and Deferred Work
 
 - **A settings `models` list replaces the composition list wholesale** — settings-layer merging is per-field, and arrays are one field; per-entry catalog merging would need a keyed shape.
-- **`Config.apiKey` is redacted on the wire but still a stored literal** — `describe({ redactSecrets: true })` strips it and reports the slot, so a configuration UI never receives the value; the key is nonetheless stored in the settings document rather than the credential store, so prefer `apiKeyEnv`.
 - **`tool_choice` is not mapped** — not part of the core vocabulary (MVP cut, shared with the pi-ai twin).
 - **Requests use raw `fetch`, not `@cordisjs/plugin-http`** — no shared proxy/interception configuration; adoption is deferred until a second adapter wants it (`TODO(http)`).
 - **Serialization flattens user and tool-result content to text blocks** — plugin-added block types are skipped, and empty tool output crosses the wire as the literal `(no output)`.
diff --git a/packages/llm/llm-deepseek/README.zh.md b/packages/llm/llm-deepseek/README.zh.md
index 4c655e90ba..650185083e 100644
--- a/packages/llm/llm-deepseek/README.zh.md
+++ b/packages/llm/llm-deepseek/README.zh.md
@@ -15,7 +15,6 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
     apiKeyEnv: DEEPSEEK_API_KEY  # default; resolved per request via ctx.credentials, then the environment
-    # apiKey: …                  # literal escape hatch; prefer the reference so no secret enters this file
     baseURL: https://api.deepseek.com # optional; $DEEPSEEK_BASE_URL then the public API when omitted
     thinking: enabled        # optional; provider default is enabled
     reasoningEffort: high    # optional; off | high | max — omitted ⇒ high
@@ -53,7 +52,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
 连接事实不在加载时冻结。`resolveAdapterOptions` 是从原始配置到已校验事实的唯一显式 resolve 步骤，适配器经由一个 thunk **每操作重读一次**：base URL、catalog、请求默认值与 idle 预算都在下一次请求生效，进行中的流则保持其起始事实。两个可选 seam 供给该 thunk：
 
 - **`ctx.settings`**——插件用同一份 `Config` schema 注册 `llm-deepseek` namespace，并以其 `cordis.yml` 条目为组合 `base`，因此用户设置文档中的 `llm-deepseek:` 分节可以免重启覆盖任何字段。未挂载 settings 服务时，仅由 entry 配置驱动适配器，行为不变。存活 settings 快照若通过 schema 却违反 schema 之外的约束（重复的 catalog id、无法成立的 thinking／推理强度组合），则保留最后可用事实并记录失败；entry 配置本身仍会使插件加载失败。
-- **`ctx.credentials`**——API 密钥按每次 stream 调用解析，取自与端点*同一*份解析后的快照：非空的字面 `apiKey` 优先，其次经凭据 seam 解析 `apiKeyEnv`（活跃环境之下的 `$DSH_HOME/.env`），最后——仅在未挂载 seam 时——读取原始环境变量。由于凭据事实与连接事实同行，被 resolver 拒绝的 settings 快照既不贡献自己的端点，也不贡献自己的密钥：整个先前世代继续服务。任何地方都没有密钥的请求以 `MISSING_CREDENTIAL` 失败，并点名每个配置入口，同时路由保持注册、catalog 保持可浏览——首次运行的上手流程就是「浏览模型、存入密钥、再次发起提示」，中间无需任何重启。
+- **`ctx.credentials`**——API 密钥按每次 stream 调用解析，取自与端点*同一*份解析后的快照。配置只携带 `apiKeyEnv`，从不携带字面密钥：该引用经凭据 seam 解析，未挂载 seam 时则经受信环境层解析。由于凭据事实与连接事实同行，被 resolver 拒绝的 settings 快照既不贡献自己的端点，也不贡献自己的密钥：整个先前世代继续服务。任何地方都没有密钥的请求以 `MISSING_CREDENTIAL` 失败，并点名每个配置入口，同时路由保持注册、catalog 保持可浏览——首次运行的上手流程就是「浏览模型、存入密钥、再次发起提示」，中间无需任何重启。
 
 唯一在注册期捕获的事实是重试策略：其解析值变化时，插件原地重新注册该路由（同一适配器实例、一个同步区段），因此 `ctx.llm.providerRetryPolicy('deepseek-official')` 始终报告当前策略。
 
@@ -77,7 +76,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
 
 ## 测试
 
-单元套件使用本地 `node:http` mock SSE 服务器（无网络），覆盖动态 `high`／`off`／`max` 选择、结构化 HTTP 事实、格式错误／截断流、调用方 abort、连接失败，以及 idle 超时确实会 abort 实际 body 的证明。`tests/dynamic-config.spec.ts` 驱动真实的 settings-local 与 credentials-local provider（下一请求即生效的 base-URL／密钥拾取、字面值优先、无密钥上手、最后可用快照、重试策略重注册），`tests/loader-composition.spec.ts` 则从仅测试用的 `cordis.yml` 出发，经真实 Loader 拉起完整链路，并在磁盘上编辑 `settings.yaml`/`.env`。真实 API 覆盖位于 `tests/adapter.e2e.ts`（`pnpm run test:e2e`，需有 key 才会运行）：V4 Flash + V4 Pro，覆盖思考启用／禁用与两种官方 effort 级别，包括思考 + 工具往返与推理回传，以及密钥仅存在于 credentials-local 文档中的请求。
+单元套件使用本地 `node:http` mock SSE 服务器（无网络），覆盖动态 `high`／`off`／`max` 选择、结构化 HTTP 事实、格式错误／截断流、调用方 abort、连接失败，以及 idle 超时确实会 abort 实际 body 的证明。`tests/dynamic-config.spec.ts` 驱动真实的 settings-local 与 credentials-local provider（下一请求即生效的 base-URL／密钥拾取、无密钥上手、最后可用快照、重试策略重注册），`tests/loader-composition.spec.ts` 则从仅测试用的 `cordis.yml` 出发，经真实 Loader 拉起完整链路，并在磁盘上编辑 `settings.yaml`/`.env`。真实 API 覆盖位于 `tests/adapter.e2e.ts`（`pnpm run test:e2e`，需有 key 才会运行）：V4 Flash + V4 Pro，覆盖思考启用／禁用与两种官方 effort 级别，包括思考 + 工具往返与推理回传，以及密钥仅存在于 credentials-local 文档中的请求。
 
 ## 模型体验
 
@@ -112,7 +111,6 @@ loop 保留的响应块会追加到下一个请求，并保留其较早可复用
 ## 已知限制与暂缓事项
 
 - **settings 的 `models` 列表会整体替换组合列表**：settings 层按字段合并，而数组是单个字段；按条目合并 catalog 需要带键的形状。
-- **`Config.apiKey` 在协议上已脱敏，但仍是一个已存的字面值**：`describe({ redactSecrets: true })` 会把它剥离并报告该槽位，配置 UI 因此永远收不到该值；但这个密钥仍存放在 settings 文档而非凭据存储中，所以请优先使用 `apiKeyEnv`。
 - **未映射 `tool_choice`**：它不属于核心词汇（MVP 取舍，与 pi-ai twin 共享）。
 - **请求使用原始 `fetch`，而非 `@cordisjs/plugin-http`**：没有共享 proxy／拦截配置；采用暂缓到第二个适配器需要该功能时（`TODO(http)`）。
 - **序列化会将 user 与工具结果内容展平为文本块**：会跳过插件添加的块类型，空工具输出会以字面 `(no output)` 通过协议发送。
diff --git a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
index 153281afe3..f1127dbf57 100644
--- a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
@@ -109,7 +109,7 @@ describe('request-level dynamic configuration', () => {
 
   it('advertises a live settings catalog without re-registration', async () => {
     const dir = await home()
-    const { ctx } = await boot(dir, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
+    const { ctx } = await boot(dir, { baseURL: 'http://127.0.0.1:1' })
 
     await expect(ctx.llm.listModels('deepseek-official')).resolves.toHaveLength(2)
     await ctx.settings.update(NS, { models: [{ id: 'settings-model', name: 'From Settings' }] })
@@ -120,7 +120,7 @@ describe('request-level dynamic configuration', () => {
 
   it('re-registers the route in place when the captured retry policy changes, without an empty-registry window', async () => {
     const dir = await home()
-    const { ctx } = await boot(dir, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
+    const { ctx } = await boot(dir, { baseURL: 'http://127.0.0.1:1' })
 
     // Observing the topology event, not just the end state: disposing and
     // re-registering also lands on the right final registry, but publishes an
@@ -145,7 +145,7 @@ describe('request-level dynamic configuration', () => {
 
   it('keeps the last good options when a settings snapshot fails beyond-schema validation', async () => {
     const dir = await home()
-    const { ctx } = await boot(dir, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
+    const { ctx } = await boot(dir, { baseURL: 'http://127.0.0.1:1' })
 
     // Schema-valid but resolver-invalid: duplicate catalog ids pass the array
     // schema and fail the explicit resolve step.
diff --git a/packages/llm/llm-pi-ai/src/config.ts b/packages/llm/llm-pi-ai/src/config.ts
index c635b1f13e..1e546b6e3a 100644
--- a/packages/llm/llm-pi-ai/src/config.ts
+++ b/packages/llm/llm-pi-ai/src/config.ts
@@ -20,8 +20,6 @@ export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000
 
 /** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */
 export interface PiAiProviderProfile {
-  /** Literal provider credential; prefer {@link apiKeyEnv}. With both absent pi-ai uses its provider-native ambient discovery. */
-  apiKey?: string
   /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */
   apiKeyEnv?: string
   /** Override the selected catalog model's endpoint without changing its protocol metadata. */
@@ -76,7 +74,6 @@ const thinkingBudgets = z.object({
 })
 
 const profile = z.object({
-  apiKey: z.string().role('secret'),
   apiKeyEnv: z.string().role('credential-ref'),
   baseURL: z.string(),
   headers: z.dict(z.string()),
@@ -126,9 +123,6 @@ export function resolveProfiles(
     }
     if (provider.length === 0) throw new Error('llm-pi-ai: provider names must be non-empty')
     if (!supported.has(provider)) throw new Error(`llm-pi-ai: unknown pi-ai provider "${provider}"`)
-    if (source.apiKey !== undefined && source.apiKey.trim().length === 0) {
-      throw new Error(`llm-pi-ai: provider "${provider}" has an empty apiKey; omit it to use ambient authentication`)
-    }
     if (source.baseURL !== undefined && source.baseURL.length === 0) {
       throw new Error(`llm-pi-ai: provider "${provider}" has an empty baseURL`)
     }
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index c138b8f5fc..d5664b7cb2 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -89,7 +89,6 @@ export function apply(ctx: Context, config: Config): void {
     provider: string,
     profile: ResolvedPiAiProviderProfile,
   ): Promise<string | undefined> => {
-    if (profile.apiKey !== undefined) return profile.apiKey
     const ref = profile.apiKeyEnv
     // Only a profile that names no credential at all defers to pi-ai's
     // provider-native discovery. Once one is named, a miss must fail loud:
diff --git a/packages/llm/llm-pi-ai/tests/adapter.spec.ts b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
index a0826b3571..daf9c517a4 100644
--- a/packages/llm/llm-pi-ai/tests/adapter.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { createUserMessage, CONTEXT_WINDOW_EXCEEDED_CODE, LlmError, ReasoningEffortId, userAgent  } from '@deepseek-ai/dsh-llm'
 import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
@@ -15,22 +15,32 @@ afterEach(async () => {
 })
 
 async function harness(baseURL: string, overrides: Record<string, unknown> = {}): Promise<Context> {
+  vi.stubEnv('PI_TEST_KEY', 'test-key')
   const ctx = new Context()
   await ctx.plugin(LlmService)
   await ctx.plugin(LlmPiAi, {
-    providers: { deepseek: { apiKey: 'test-key', baseURL, ...overrides } },
+    providers: { deepseek: { apiKeyEnv: 'PI_TEST_KEY', baseURL, ...overrides } },
   })
   return ctx
 }
 
-/** Direct adapter over the real profile resolver, with literal-key resolution. */
-function adapterOf(providers: Record<string, LlmPiAi.PiAiProviderProfile>): PiAiAdapter {
+/** Direct adapter over the real profile resolver, with a fixed key per call. */
+function adapterOf(
+  providers: Record<string, LlmPiAi.PiAiProviderProfile>,
+  apiKey: string | undefined = 'test-key',
+): PiAiAdapter {
   return new PiAiAdapter({
     profiles: () => resolveProfiles(providers),
-    resolveApiKey: (_provider, profile) => Promise.resolve(profile.apiKey),
+    resolveApiKey: () => Promise.resolve(apiKey),
   })
 }
 
+beforeEach(() => {
+  // Configuration carries only the reference; these mounts resolve it from
+  // the environment, which is the whole credential plane without a seam.
+  vi.stubEnv('PI_TEST_KEY', 'test-key')
+})
+
 describe('PiAiAdapter provider routing', () => {
   it('resolves a catalog model dynamically and uses a private endpoint', async () => {
     const server = await mockServer([{ events: textEvents }])
@@ -117,7 +127,7 @@ describe('PiAiAdapter provider routing', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     ctx.llm.registerAdapter(['deepseek'], adapterOf({
-      deepseek: { apiKey: 'test-key', baseURL: server.url },
+      deepseek: { apiKeyEnv: 'PI_TEST_KEY', baseURL: server.url },
     }))
 
     const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
@@ -146,7 +156,7 @@ describe('PiAiAdapter provider routing', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmPiAi, {
-      providers: { openai: { apiKey: 'test-key', baseURL: `${server.url}/v1` } },
+      providers: { openai: { apiKeyEnv: 'PI_TEST_KEY', baseURL: `${server.url}/v1` } },
     })
     const result = await assemble(ctx, { provider: 'openai', model: 'gpt-4.1', messages: [] })
     expect(result.finish.kind).toBe('error')
@@ -166,7 +176,7 @@ describe('PiAiAdapter provider routing', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmPiAi, {
-      providers: { openai: { apiKey: 'test-key', baseURL: `${server.url}/v1` } },
+      providers: { openai: { apiKeyEnv: 'PI_TEST_KEY', baseURL: `${server.url}/v1` } },
     })
 
     const result = await assemble(ctx, { provider: 'openai', model: 'gpt-4.1', messages: [] })
@@ -182,7 +192,7 @@ describe('PiAiAdapter provider routing', () => {
     await ctx.plugin(LlmPiAi, {
       providers: {
         openai: {
-          apiKey: 'test-key',
+          apiKeyEnv: 'PI_TEST_KEY',
           baseURL: `${server.url}/api/projects/openai/openai/v1`,
           headers: { 'api-key': 'test-key', Authorization: '' },
         },
@@ -372,7 +382,9 @@ describe('provider profile lifecycle', () => {
   it('accepts absent credentials for pi-ai ambient authentication', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', 'ambient-key')
     const server = await mockServer([{ events: textEvents }])
-    const ctx = await harness(server.url, { apiKey: undefined })
+    // A profile that names no reference at all is the one case that defers to
+    // pi-ai's own provider-native discovery.
+    const ctx = await harness(server.url, { apiKeyEnv: undefined })
     await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
     expect(server.headers[0]?.authorization).toBe('Bearer ambient-key')
   })
@@ -410,8 +422,6 @@ describe('provider profile lifecycle', () => {
     // loud with migration directions instead of half-working.
     expect(() => resolveProfiles([{ provider: 'openai' }] as never)).toThrow(/dict keyed by provider/)
     expect(() => resolveProfiles({ openai: { provider: 'openai' } as never })).toThrow(/moved to the providers dict key/)
-    expect(() => resolveProfiles({ openai: { apiKey: '' } })).toThrow(/empty apiKey/)
-    expect(() => resolveProfiles({ openai: { apiKey: '  ' } })).toThrow(/empty apiKey/)
     expect(() => resolveProfiles({ openai: { baseURL: '' } })).toThrow(/empty baseURL/)
     expect(() => resolveProfiles({ openai: { apiKeyEnv: 'not-a-var!' } })).toThrow(/must match/)
   })
@@ -486,7 +496,7 @@ describe('abort wiring', () => {
     const message = Object.defineProperty({}, 'role', {
       get() { throw original },
     })
-    const adapter = adapterOf({ deepseek: { apiKey: 'test-key' } })
+    const adapter = adapterOf({ deepseek: {} })
     const drain = async (): Promise<void> => {
       for await (const _chunk of adapter.stream({
         provider: 'deepseek',
@@ -507,7 +517,7 @@ describe('abort wiring', () => {
         throw original
       },
     })
-    const adapter = adapterOf({ deepseek: { apiKey: 'test-key' } })
+    const adapter = adapterOf({ deepseek: {} })
     const drain = async (): Promise<void> => {
       for await (const _chunk of adapter.stream({
         provider: 'deepseek',
@@ -521,7 +531,7 @@ describe('abort wiring', () => {
   })
 
   it('resolves catalog endpoints without an override before honoring pre-abort', async () => {
-    const adapter = adapterOf({ deepseek: { apiKey: 'test-key' } })
+    const adapter = adapterOf({ deepseek: {} })
     const controller = new AbortController()
     controller.abort('already stopped')
     const chunks = []
diff --git a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
index cc5cd17e55..2c8b07a2aa 100644
--- a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
@@ -53,7 +53,11 @@ describe('request-level dynamic profiles', () => {
   it('mounts bare and dormant, then registers routes the moment settings supply providers', async () => {
     vi.stubEnv('PI_DYNAMIC_KEY', '')
     const dir = await home()
-    await writeFile(join(dir, '.credentials.yaml'), 'PI_DYNAMIC_KEY: pk-from-settings\n', { mode: 0o600 })
+    await writeFile(
+      join(dir, '.credentials.yaml'),
+      'PI_DYNAMIC_KEY: pk-from-settings\nPI_LIVE_KEY: live-key\nPI_OTHER_KEY: other\n',
+      { mode: 0o600 },
+    )
     const server = await mockServer([{ events: textEvents }])
     // The exact product posture: `- id: llm-pi-ai` with no config at all.
     const ctx = await boot(dir, {})
@@ -86,14 +90,19 @@ describe('request-level dynamic profiles', () => {
 
   it('adds a provider route from settings and drops it when the user layer resets', async () => {
     const dir = await home()
+    await writeFile(
+      join(dir, '.credentials.yaml'),
+      'PI_LIVE_KEY: live-key\nPI_OTHER_KEY: other\n',
+      { mode: 0o600 },
+    )
     const server = await mockServer([{ events: textEvents }])
     const ctx = await boot(dir, {
-      providers: { openai: { apiKey: 'k', baseURL: 'http://127.0.0.1:1/v1' } },
+      providers: { openai: { apiKeyEnv: 'PI_DYNAMIC_KEY', baseURL: 'http://127.0.0.1:1/v1' } },
     })
 
     expect(ctx.llm.listProviders().map(provider => provider.id)).toEqual(['openai'])
     await ctx.settings.update(NS, {
-      providers: { deepseek: { apiKey: 'live-key', baseURL: server.url } },
+      providers: { deepseek: { apiKeyEnv: 'PI_LIVE_KEY', baseURL: server.url } },
     })
     expect(ctx.llm.listProviders().map(provider => provider.id)).toEqual(['openai', 'deepseek'])
 
@@ -158,15 +167,20 @@ describe('request-level dynamic profiles', () => {
 
   it('keeps serving its routes when a settings-born route collides with another adapter', async () => {
     const dir = await home()
+    await writeFile(
+      join(dir, '.credentials.yaml'),
+      'PI_LIVE_KEY: live-key\nPI_OTHER_KEY: other\n',
+      { mode: 0o600 },
+    )
     const server = await mockServer([{ events: textEvents }, { events: textEvents }])
-    const ctx = await boot(dir, { providers: { openai: { apiKey: 'pk', baseURL: `${server.url}/v1` } } })
+    const ctx = await boot(dir, { providers: { openai: { apiKeyEnv: 'PI_LIVE_KEY', baseURL: `${server.url}/v1` } } })
     // Another adapter owns `anthropic`; the registry must refuse to hand it over.
     ctx.llm.registerAdapter(['anthropic'], new StubAdapter())
 
     await ctx.settings.update(NS, {
       providers: {
-        openai: { apiKey: 'pk', baseURL: `${server.url}/v1` },
-        anthropic: { apiKey: 'other' },
+        openai: { apiKeyEnv: 'PI_LIVE_KEY', baseURL: `${server.url}/v1` },
+        anthropic: { apiKeyEnv: 'PI_OTHER_KEY' },
       },
     })
 
diff --git a/packages/llm/llm-pi-ai/tests/sdk-options.spec.ts b/packages/llm/llm-pi-ai/tests/sdk-options.spec.ts
index 3f12ef4460..a2727de75f 100644
--- a/packages/llm/llm-pi-ai/tests/sdk-options.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/sdk-options.spec.ts
@@ -23,7 +23,7 @@ describe('pi-ai SDK retry boundary', () => {
       },
     })
     const adapter = new PiAiAdapter({
-      profiles: () => resolveProfiles({ openai: { apiKey: 'test-key' } }),
+      profiles: () => resolveProfiles({ openai: {} }),
       resolveApiKey: () => Promise.resolve('test-key'),
     })
     const drain = async (): Promise<void> => {
diff --git a/packages/ui/app-boot/package.json b/packages/ui/app-boot/package.json
index fc4f173263..b978bd33bb 100644
--- a/packages/ui/app-boot/package.json
+++ b/packages/ui/app-boot/package.json
@@ -27,7 +27,6 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
-    "dotenv": "^17.2.0",
     "js-yaml": "^4.2.0"
   },
   "peerDependencies": {
diff --git a/packages/ui/app-boot/src/index.ts b/packages/ui/app-boot/src/index.ts
index 0f3cbd6687..99220e4269 100644
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -6,10 +6,10 @@
  * @module @deepseek-ai/dsh-app-boot
  */
 
+import { parseEnv } from 'node:util'
 import { pathToFileURL } from 'node:url'
 import { readFileSync } from 'node:fs'
 import { basename, dirname, resolve } from 'node:path'
-import { parse as parseDotenv } from 'dotenv'
 import * as yaml from 'js-yaml'
 import { Context, type FiberState } from 'cordis'
 import Loader, { type Entry, type EntryOptions } from '@cordisjs/plugin-loader'
@@ -94,7 +94,13 @@ function readEnvLayer(
     // ENOENT (no .env) is fine — rely on the ambient environment.
     return undefined
   }
-  const values = parseDotenv(content)
+  // `node:util`'s parseEnv is the same parser `--env-file` and
+  // `process.loadEnvFile` use. Checking with a second dialect (npm dotenv)
+  // would leave the rejection rule and the thing it guards on independently
+  // maintained parsers: a name Node accepts but the checker does not would
+  // reach `process.env` unchecked, and `BASH_ENV` there runs a file of the
+  // project's choosing on every `bash -c` the bash tool issues.
+  const values = parseEnv(content) as Record<string, string>
   for (const name of Object.keys(values)) {
     if (!isBootstrapOnly(name)) continue
     throw new Error(
@@ -112,9 +118,11 @@ function readEnvLayer(
  * over the Harness home's `.env`, both under the inherited process
  * environment.
  *
- * Each layer is parsed and checked before anything is applied, then applied in
- * the order that makes the layering `user < project < inherited` —
- * `process.loadEnvFile` never replaces a name already set. Values do reach
+ * Each layer is parsed once, checked, and only then applied — never replacing
+ * a name already set, which is what makes the layering `user < project <
+ * inherited`. The single parse is deliberate: the rejection rule and the
+ * values that reach `process.env` must come from the same parser, or a name
+ * one dialect accepts and the other misses would slip past the check. Values do reach
  * `process.env`, because a user's own `--config` tree and third-party
  * libraries read it; the returned snapshot is the authority for everything the
  * harness itself resolves, since `process.env` alone cannot say whether a
@@ -144,8 +152,18 @@ export function loadLayeredEnv(
   // Parse both layers first: a rejection must not leave one file applied.
   const project = readEnvLayer(binName, cwd, warn)
   const user = home === resolve(cwd) ? undefined : readEnvLayer(binName, home, warn)
-  if (project !== undefined) process.loadEnvFile(project.path)
-  if (user !== undefined) process.loadEnvFile(user.path)
+  // Assign the entries this function already parsed and checked, rather than
+  // re-reading each file through `process.loadEnvFile`. One parse means the
+  // snapshot, the rejection rule, and `process.env` can never disagree about
+  // what a file contains. Skipping names already set reproduces the
+  // never-replace behavior that makes the layering `user < project <
+  // inherited`.
+  for (const layer of [project, user]) {
+    if (layer === undefined) continue
+    for (const [name, value] of Object.entries(layer.values)) {
+      if (process.env[name] === undefined) process.env[name] = value
+    }
+  }
   return createEnvironmentSnapshot([
     { source: 'process', values: inherited },
     ...project === undefined ? [] : [{ source: 'project-env' as const, path: project.path, values: project.values }],
diff --git a/packages/util/environment/src/index.ts b/packages/util/environment/src/index.ts
index 6e27656805..11014f64b5 100644
--- a/packages/util/environment/src/index.ts
+++ b/packages/util/environment/src/index.ts
@@ -69,6 +69,16 @@ export interface EnvironmentSnapshot {
   readonly layers: readonly EnvironmentLayer[]
 }
 
+/**
+ * The map key one variable name resolves under. Windows treats environment
+ * names case-insensitively; every other platform does not.
+ * @param name - the variable name as written.
+ * @returns the key to store and look up by.
+ */
+function lookupKey(name: string): string {
+  return process.platform === 'win32' ? name.toUpperCase() : name
+}
+
 /** One layer's raw contents, as {@link createEnvironmentSnapshot} receives them. */
 export interface EnvironmentLayerInput {
   source: EnvironmentSource
@@ -84,18 +94,24 @@ export interface EnvironmentLayerInput {
  */
 export function createEnvironmentSnapshot(layers: readonly EnvironmentLayerInput[]): EnvironmentSnapshot {
   // Copied per layer so a later mutation of `process.env` — or of a caller's
-  // own object — cannot change what this snapshot reports.
+  // own object — cannot change what this snapshot reports. Windows environment
+  // names are case-insensitive, so lookups there fold case: otherwise a shell
+  // that set `deepseek_api_key` would be invisible to a consumer asking for
+  // `DEEPSEEK_API_KEY`, and a lower-ranked layer spelling it in caps would win
+  // a decision the launch had already made. POSIX names are case-sensitive and
+  // must stay exact.
   const bySource = new Map<EnvironmentSource, { path?: string; values: Map<string, string> }>()
   for (const layer of layers) {
     bySource.set(layer.source, {
       ...layer.path === undefined ? {} : { path: layer.path },
-      values: new Map(Object.entries(layer.values)),
+      values: new Map(Object.entries(layer.values).map(([name, value]) => [lookupKey(name), value])),
     })
   }
   const getFrom = (name: string, sources: readonly EnvironmentSource[]): EnvironmentEntry | undefined => {
+    const key = lookupKey(name)
     for (const source of sources) {
       const layer = bySource.get(source)
-      const value = layer?.values.get(name)
+      const value = layer?.values.get(key)
       if (value === undefined) continue
       return { value, source, ...layer?.path === undefined ? {} : { path: layer.path } }
     }
@@ -154,13 +170,21 @@ const BOOTSTRAP_NAMES = new Set([
   'BASH_ENV', 'ENV', 'SHELLOPTS', 'BASHOPTS',
   'PERL5OPT', 'PERL5LIB', 'PYTHONSTARTUP', 'PYTHONPATH', 'RUBYOPT', 'RUBYLIB',
   'JAVA_TOOL_OPTIONS', '_JAVA_OPTIONS', 'JDK_JAVA_OPTIONS',
-  // Version-control hooks that run a command on the setter's behalf.
+  'PYTHONHOME',
+  // Version-control hooks that run a command on the setter's behalf, and the
+  // config redirections that can define such a hook indirectly (a substituted
+  // git config file can set core.pager or a credential helper).
   'GIT_SSH', 'GIT_SSH_COMMAND', 'GIT_EXTERNAL_DIFF', 'GIT_PAGER', 'GIT_EDITOR',
+  'GIT_ASKPASS', 'SSH_ASKPASS',
+  'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_COUNT',
   'EDITOR', 'VISUAL', 'PAGER',
   // Network reach and trust.
   'SSL_CERT_FILE', 'SSL_CERT_DIR',
   'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
   'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE',
+  // Turns off TLS verification outright, which is the sharpest form of
+  // "how the network is trusted".
+  'NODE_TLS_REJECT_UNAUTHORIZED',
 ])
 
 /** Name prefixes no discovered file may set. */
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 18b62cae80..adeea9a056 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -5657,9 +5657,6 @@ importers:
 
   packages/ui/app-boot:
     dependencies:
-      dotenv:
-        specifier: ^17.2.0
-        version: 17.4.2
       js-yaml:
         specifier: ^4.2.0
         version: 4.2.0
@@ -9752,10 +9749,6 @@ packages:
   dompurify@3.4.11:
     resolution: {integrity: sha512-zhlUV12GsaRzMsf9q5M254YhA4+VuF0fG+QFqu6aYpoGlKtz+w8//jBcGVYBgQkR5GHjUomejY84AV+/uPbWdw==}
 
-  dotenv@17.4.2:
-    resolution: {integrity: sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==}
-    engines: {node: '>=12'}
-
   dts-resolver@3.0.0:
     resolution: {integrity: sha512-1T1f+z+4tl9XD+m+0HBgWoL/nm0bOIffyWaUuUSBlFg/86IWvfx+wjNaO/ybU0AJzG9/Mi5hBUgGV6zCmWEN7Q==}
     engines: {node: ^22.18.0 || >=24.0.0}
@@ -14843,8 +14836,6 @@ snapshots:
     optionalDependencies:
       '@types/trusted-types': 2.0.7
 
-  dotenv@17.4.2: {}
-
   dts-resolver@3.0.0(oxc-resolver@11.20.0):
     optionalDependencies:
       oxc-resolver: 11.20.0
diff --git a/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml b/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml
index 2f35e58d43..318bda59b0 100644
--- a/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml
+++ b/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml
@@ -13,13 +13,12 @@
     workspaceContext:
       maxBytes: 65536
 
-# Stock DeepSeek adapters. Loading requires an API key; initialize and shutdown
-# may use a dummy key because they do not call the model.
+# Stock DeepSeek adapters. The adapter resolves DEEPSEEK_API_KEY through the
+# credential seam and, with no provider mounted here, from the launching
+# environment; DEEPSEEK_BASE_URL follows the same environment ladder. Neither
+# is inlined, so this file names no secret and no route.
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
 
 # JSONL persistence; $DSH_SESSION_ROOT wins over ./.sessions in the process cwd.
 - id: sessions
diff --git a/scripts/verify-config-source-ownership.ts b/scripts/verify-config-source-ownership.ts
index d346b19233..8b59957c4b 100644
--- a/scripts/verify-config-source-ownership.ts
+++ b/scripts/verify-config-source-ownership.ts
@@ -72,9 +72,21 @@ const ENV_READ_ALLOWLIST: Readonly<Record<string, string>> = {
 }
 
 /** Shipped Cordis configuration these rules apply to. */
-const SHIPPED_CONFIG_GLOBS = ['apps/*/config/*.yml', 'examples/*/*.cordis.yml', 'examples/*/cordis.yml']
+const SHIPPED_CONFIG_GLOBS = [
+  'apps/*/config/*.yml',
+  'examples/*/*.cordis.yml',
+  'examples/*/cordis.yml',
+  // The Python runtime ships its own default composition inside the wheel.
+  'python/*/src/**/cordis.yml',
+]
 
-/** Config keys that must never be inlined from the environment. */
+/**
+ * Config keys that must never be inlined from the environment. Line-anchored
+ * on purpose: this is a tripwire for the shape people actually write, not a
+ * YAML analysis. A folded scalar or a block-literal spelling would slip past
+ * it, which is acceptable because the rule it guards is also stated in the
+ * owning Agent Note and enforced by the adapters' own resolution.
+ */
 const INLINE_DENY = /^\s*(apiKey|baseURL|apiKeyEnv|authToken|headers)\s*:\s*!!js\b/
 
 const failures: string[] = []

From 286f356942207ac60b6a898188d8d90f1316814b Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 5 Aug 2026 11:29:36 +0800
Subject: [PATCH 026/516] docs: narrow the composition claims to what survived
 the TUI removal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Master's #1369 deleted the TUI, the meta and upgrade subcommands, and the
whole-tree --config-replace path. These notes were written before that landed
and still promised a flag the CLI no longer registers, and named it as the
lever a deployment uses to pin a field against a user's stored settings —
which now has no CLI equivalent at all.

State what shipped: every booting surface takes --config, dsh -p is the
surface this change actually gave it to, and a deployment that must win
against stored settings ships its own bin or loader tree. Each note
cross-links #1369's own note rather than restating the removal, and the
shared-base note moves its --config-replace sentences to past tense.
---
 .../2026-08-04-configuration-source-ownership.i18n.yaml   | 4 ++--
 .../2026-08-04-configuration-source-ownership.md          | 6 +++---
 .../2026-08-04-configuration-source-ownership.zh.md       | 6 +++---
 .../2026-07-29-shared-base-config-overlays.i18n.yaml      | 4 ++--
 .../2026-07-29-shared-base-config-overlays.md             | 2 +-
 .../2026-07-29-shared-base-config-overlays.zh.md          | 2 +-
 ...2026-08-04-remove-personal-composition-layer.i18n.yaml | 4 ++--
 .../2026-08-04-remove-personal-composition-layer.md       | 8 ++++----
 .../2026-08-04-remove-personal-composition-layer.zh.md    | 8 ++++----
 .../2026-08-04-remove-profile-json-entry.i18n.yaml        | 4 ++--
 .../2026-08-04-remove-profile-json-entry.md               | 2 +-
 .../2026-08-04-remove-profile-json-entry.zh.md            | 2 +-
 12 files changed, 26 insertions(+), 26 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index cbce8a65e8..51d58cd442 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: 97daf3c430ba09c000eab947e159030568a7f89d
-2026-08-04-configuration-source-ownership.zh.md: 424c47d36f47136669f4e02f980e63cabd203f9c
+2026-08-04-configuration-source-ownership.md: 7f8dba2e4879fee34c4526bd73436b4c8ddd13aa
+2026-08-04-configuration-source-ownership.zh.md: 26fdad39887c07fe420e1c37d49b252eeeb2e3ae
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index 97daf3c430..7f8dba2e48 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -21,13 +21,13 @@ And `!!js process.env.X` in the shipped composition made the same value reachabl
 ```text
 explicit for this run     per-operation override, CLI argument
 > user settings           settings.yaml
-> composition             --config / --config-replace, shipped base
+> composition             --config overlay, shipped base
 > this launch's shell     inherited process environment
 > discovered file         $DSH_HOME/.env
 > defaults                schema default, provider public default
 ```
 
-Settings sit above composition because that is what the [settings seam](2026-07-28-user-settings-seam.md) does: a plugin registers its cordis entry config as the `base` layer and the user's section layers over it, and the seam cannot tell a value the shipped base set from one a `--config` overlay set — both arrive as entry config. A deployment that must pin a field against a user's stored settings therefore uses `--config-replace`, which bypasses the tree the settings base is derived from. Composition still outranks the environment, so a stale `DEEPSEEK_BASE_URL` in a shell cannot rewrite a configured endpoint.
+Settings sit above composition because that is what the [settings seam](2026-07-28-user-settings-seam.md) does: a plugin registers its cordis entry config as the `base` layer and the user's section layers over it, and the seam cannot tell a value the shipped base set from one a `--config` overlay set — both arrive as entry config. The product CLI has no lever above stored settings: `--config-replace` was removed with the TUI ([explicit-config entrypoint](../simplification/2026-08-03-explicit-config-dsh-entrypoint.md)), so a deployment that must pin a field against a user's settings ships its own bin or loader tree, or mounts no settings provider at all. Composition still outranks the environment, so a stale `DEEPSEEK_BASE_URL` in a shell cannot rewrite a configured endpoint.
 
 **Credentials keep a narrower, separate ordering**, and this note does not unify them:
 
@@ -54,7 +54,7 @@ The line is that these take effect with no user action, before any turn, outside
 
 - The web credential form now takes effect against an older key in the user's `.env`; only a key exported in the launching shell still makes it read-only, and the diagnostic says so.
 - A `.env` holding `DSH_*`, `PATH`, or a proxy variable fails the launch instead of being applied. Developers keeping switches in a repository `.env` move them to their shell — a deliberate, loud break.
-- `--config` is no longer overridable by a stale shell endpoint. It is still overridable by a user's stored `settings.yaml`, which is the settings seam's layering and not something this note changes; a deployment that must win against stored settings uses `--config-replace`.
+- `--config` is no longer overridable by a stale shell endpoint. It is still overridable by a user's stored `settings.yaml`, which is the settings seam's layering and not something this note changes; the product CLI offers no flag above it, so a deployment that must win against stored settings owns its own bin or loader tree.
 - Not solved: the layers are still materialized into `process.env`, so ordinary project variables continue to reach child processes under the subprocess scrub. Bootstrap variables cannot come from a file at all, which closes the escalation path; a project `.env` setting something like `GIT_SSH_COMMAND` for the tools an agent runs remains possible and is recorded as a limitation on the package.
 - The LLM adapters no longer accept a literal `apiKey`: configuration carries the reference and nothing else, so a settings document cannot become a second credential store. No adapter namespace is strict, so writing one is dropped rather than rejected. The web-search providers still declare a `role('secret')` literal key; they register no settings namespace, so nothing can shadow a stored credential through them, but the claim is about the adapters rather than the repository as a whole.
 - Exa and Perplexity still capture their key at load time rather than through the credential seam. They no longer read raw `process.env` — they resolve through the trusted layers — but converting them to per-request seam resolution is separate work.
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index 424c47d36f..26fdad3988 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -21,7 +21,7 @@ endpoint 可以被项目重定向。调用目录的 `.env` 和其他层一样会
 ```text
 explicit for this run     per-operation override, CLI argument
 > user settings           settings.yaml
-> composition             --config / --config-replace, shipped base
+> composition             --config overlay, shipped base
 > this launch's shell     inherited process environment
 > discovered file         $DSH_HOME/.env
 > defaults                schema default, provider public default
@@ -29,7 +29,7 @@ explicit for this run     per-operation override, CLI argument
 
 自上而下依次是：本次运行的显式意图、用户 settings、composition、本次启动的 shell、被发现的文件、默认值。
 
-settings 在 composition 之上，因为 [settings seam](2026-07-28-user-settings-seam.md) 就是这么做的：插件把自己的 cordis entry config 注册为 `base` 层，用户 section 叠加其上，而 seam 无法区分某个值是交付基座设的还是 `--config` overlay 设的——两者都以 entry config 的形式抵达。因此，需要把某字段钉死、不被用户已存 settings 覆盖的部署方，应使用 `--config-replace`，它绕过了 settings base 所派生的那棵树。composition 仍然高于环境，所以 shell 里陈旧的 `DEEPSEEK_BASE_URL` 无法改写已配置的 endpoint。
+settings 在 composition 之上，因为 [settings seam](2026-07-28-user-settings-seam.md) 就是这么做的：插件把自己的 cordis entry config 注册为 `base` 层，用户 section 叠加其上，而 seam 无法区分某个值是交付基座设的还是 `--config` overlay 设的——两者都以 entry config 的形式抵达。产品 CLI（命令行界面）没有高于已存 settings 的手段：`--config-replace` 已随 TUI 一并移除（见[显式配置入口](../simplification/2026-08-03-explicit-config-dsh-entrypoint.md)），因此需要把某字段钉死、不被用户已存 settings 覆盖的部署方，应自带 bin 或 loader 配置树，或者干脆不挂载 settings provider。composition 仍然高于环境，所以 shell 里陈旧的 `DEEPSEEK_BASE_URL` 无法改写已配置的 endpoint。
 
 **凭据保留一条更窄的独立顺序**，本 Note 不把它并入上表：
 
@@ -56,7 +56,7 @@ inherited process environment      (read-only, wins)
 
 - Web 凭据表单现在能压过用户 `.env` 里更旧的密钥；只有在启动 shell 里 export 的密钥才会让它变成只读，诊断信息也会这么说。
 - 含 `DSH_*`、`PATH` 或 proxy 变量的 `.env` 会导致启动失败而不是被应用。把开关放在仓库 `.env` 里的开发者需要改放到 shell——这是一次刻意且响亮的破坏。
-- `--config` 不再会被陈旧的 shell endpoint 覆盖。但它仍然会被用户已存的 `settings.yaml` 覆盖，这是 settings seam 的分层方式，本 Note 不改变它；需要压过已存 settings 的部署方应使用 `--config-replace`。
+- `--config` 不再会被陈旧的 shell endpoint 覆盖。但它仍然会被用户已存的 `settings.yaml` 覆盖，这是 settings seam 的分层方式，本 Note 不改变它；产品 CLI 没有高于它的标志，因此需要压过已存 settings 的部署方要自带 bin 或 loader 配置树。
 - 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件，提权路径已封闭；项目 `.env` 为 agent 运行的工具设置诸如 `GIT_SSH_COMMAND` 之类的变量仍然可能，已作为限制记录在该包上。
 - LLM 适配器不再接受字面 `apiKey`：配置只携带引用，因此 settings 文档无法成为第二个凭据存储。由于没有任何适配器 namespace 是 strict 的，写入该键会被 schema 丢弃而不是报错。web-search 提供方仍声明 `role('secret')` 的字面密钥字段；它们不注册 settings namespace，因此无法借此遮蔽已存凭据，但这条声明的范围是适配器，而不是整个仓库。
 - Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求经 seam 解析是另一件事。
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
index 37df0f897d..0dfa674535 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.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 .agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
-2026-07-29-shared-base-config-overlays.md: 80418447cf45f9f4aa279d1b46b5181d383d0a12
-2026-07-29-shared-base-config-overlays.zh.md: c75dd66c8fb299d4f2a57f7e9ea1acb54a2f8951
+2026-07-29-shared-base-config-overlays.md: 8e83282ed7ea2d3264f38bee8c29f72d0288aed5
+2026-07-29-shared-base-config-overlays.zh.md: bc2be5d74f57df7e15a4c7170a1162398229df5d
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
index 80418447cf..8e83282ed7 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
@@ -20,7 +20,7 @@ One shared base, one overlay per surface, composed as sibling patch lists.
 
 Precedence is list order, last write winning per row: base, then the surface overlay, then a `--config` overlay, then the launcher's own flag patches. The personal `~/.dsh/config.yaml` sat in the `--config` slot until it was [removed with the personal composition layer](../simplification/2026-08-04-remove-personal-composition-layer.md).
 
-`--config <path>` applies an overlay over the shipped tree (at the time, **instead of** the personal overlay, so a demo or test tree never inherited the user's provider and model). `--config-replace <path>` boots a file as the entire tree, bypassing base, surface overlay, and personal overlay alike; that is what the old `--config` did, so trees like `examples/web-cordis` moved to the new flag. Both flags survive the `/resume` execve handoff, or resuming would silently change the agent.
+`--config <path>` applies an overlay over the shipped tree (at the time, **instead of** the personal overlay, so a demo or test tree never inherited the user's provider and model). `--config-replace <path>` booted a file as the entire tree, bypassing base, surface overlay, and personal overlay alike; that is what the old `--config` did, so trees like `examples/web-cordis` moved to the new flag. Both flags survived the `/resume` execve handoff, or resuming would silently have changed the agent. That flag and the resume handoff were later removed with the TUI ([explicit-config entrypoint](2026-08-03-explicit-config-dsh-entrypoint.md)).
 
 A patch replaces its target row's whole `config` rather than merging, which shapes the split: a row whose value differs per surface lives in the overlays, never in the base, so no row is patched by three layers at once. Session identity therefore cannot ride a config key at all — it moved to `dsh-agent-loop`'s `CONFIGURED_AGENT_IDENTITIES_KEY`, as the launcher-owned identity record documented.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
index c75dd66c8f..bc2be5d74f 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 优先级即列表顺序，逐配置项后写者胜：base，然后是 surface overlay，接着是 `--config` overlay，最后是启动器自身的 flag patch。个人 `~/.dsh/config.yaml` 曾占据 `--config` 这一槽位，直到它[已随个人 composition 层一并删除](../simplification/2026-08-04-remove-personal-composition-layer.md)。
 
-`--config <path>` 在已交付配置树上应用一个 overlay（当时是**取代**个人 overlay，因此 demo 或测试用的树绝不会继承用户的 provider 与 model）。`--config-replace <path>` 则把某个文件作为整棵树启动，同时绕过 base、surface overlay 与个人 overlay；这正是旧 `--config` 的行为，所以像 `examples/web-cordis` 这样的树改用了新 flag。两个 flag 都会在 `/resume` 的 execve 交接中保留，否则 resume 会静默更换 agent。
+`--config <path>` 在已交付配置树上应用一个 overlay（当时是**取代**个人 overlay，因此 demo 或测试用的树绝不会继承用户的 provider 与 model）。`--config-replace <path>` 当时把某个文件作为整棵树启动，同时绕过 base、surface overlay 与个人 overlay；这正是旧 `--config` 的行为，所以像 `examples/web-cordis` 这样的树改用了新 flag。两个 flag 当时都会在 `/resume` 的 execve 交接中保留，否则 resume 会静默更换 agent。该标志与 resume 交接后来随 TUI 一并移除（见[显式配置入口](2026-08-03-explicit-config-dsh-entrypoint.md)）。
 
 patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆分方式：取值因 surface 而异的配置项住在 overlay 中，绝不住在 base 里，从而没有任何配置项会被三层同时 patch。因此会话身份根本不能经由配置键传递——它迁移到了 `dsh-agent-loop` 的 `CONFIGURED_AGENT_IDENTITIES_KEY`，正如启动器持有身份的记录所述。
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.i18n.yaml
index 11239d3c23..e000e463b7 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.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 .agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md
-2026-08-04-remove-personal-composition-layer.md: 941e2248e15e235037e6bd48dcb3ba6c80bd83dd
-2026-08-04-remove-personal-composition-layer.zh.md: 6c6f3ecd541590368624f4ed4bd409321a2f9772
+2026-08-04-remove-personal-composition-layer.md: e41109d4c141f55e511e102f99e87ef5c696ac47
+2026-08-04-remove-personal-composition-layer.zh.md: b5e47e188db6dfccb55b2800329a2f2e6cd2787f
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md
index 941e2248e1..e41109d4c1 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.md
@@ -12,17 +12,17 @@ A patch replaces its target row's whole `config`, so a personal file written mon
 
 It also competed with typed settings for the same values. `llm-deepseek` and `llm-pi-ai` register settings namespaces, and the same fields are reachable by patching their rows — so which one wins is a function of layer order, not of what the value means. That is the ownership ambiguity the [user-settings seam](../architecture/2026-07-28-user-settings-seam.md) exists to remove.
 
-Finally the escape hatch it was supposed to be redundant with did not cover every surface: `dsh -p`, `dsh meta`, and `dsh upgrade` all rejected `--config`. For those surfaces the implicit file was not one composition route among two — it was the only one.
+Finally the escape hatch it was supposed to be redundant with did not cover every surface: `dsh -p` rejected `--config`, and so did the `meta` and `upgrade` subcommands of the time. For those surfaces the implicit file was not one composition route among two — it was the only one.
 
 ## Decision
 
 The implicit layer is deleted and the explicit one is completed.
 
-**Every booting surface takes `--config` and `--config-replace`.** `dsh -p`, `dsh meta`, and `dsh upgrade` join the TUI, so naming a tree is available wherever a tree boots. A headless `--config-replace` tree must still mount a webserver row, because that surface reaches its own agent over the same HTTP gateway the browser uses; `AppCLIEntry` now names that contract in the failure instead of reporting a bare missing service.
+**Every booting surface takes `--config`.** `dsh -p` joins the surfaces that already had it, so naming an overlay is available wherever a tree boots. The TUI, `meta`, and `upgrade` were removed in parallel by the [explicit-config entrypoint](2026-08-03-explicit-config-dsh-entrypoint.md), which also deleted the whole-tree `--config-replace` path; what remains of this change on that side is headless, which previously rejected the flag and had the implicit file as its only composition route.
 
 **`$DSH_HOME/config.yaml` is not read, watched, or dumped.** `PERSONAL_CONFIG_FILENAME`, `loadPersonalPatches`, `watchPersonalPatches`, and the config-only HMR row mounted for it are deleted. A file left at that path is inert. The Harness home keeps `settings.yaml`, `.credentials.yaml`, and `.env`; an overlay may still live there, but as a path to name, not a layer to discover.
 
-`--config` therefore changes meaning slightly: it used to *replace* the personal overlay, and now it simply *is* the user overlay. `--config-replace` is unchanged.
+`--config` therefore changes meaning slightly: it used to *replace* the personal overlay, and now it simply *is* the user overlay.
 
 Everyday capabilities keep their owners. Model and provider parameters already belong to the adapters' typed settings namespaces. The `repository-plugins` row ships mounted with an empty list, so a repository Plugin list is a `--config` overlay today and a settings namespace when one lands. MCP servers stay a `--config` composition, which is what [the CLI README](../../../../apps/cli/README.md) now documents.
 
@@ -44,4 +44,4 @@ There is no migration and no deprecation diagnostic: the product is unreleased,
 
 **Delete it only after the settings-driven repository and MCP managers exist.** Rejected as an unnecessary dependency once `--config` reached every surface: the managers make those two cases *nicer*, but with the flag available everywhere, nothing is lost by removing the implicit layer first.
 
-**Keep it for `dsh -p` alone, where no flag existed.** Rejected: that is the surface with the strongest case for explicitness. A CI or scripted run should name its composition rather than inherit whatever the machine holds.
+**Keep it for `dsh -p` alone, where no flag existed.** Rejected: that is the surface with the strongest case for explicitness. A CI or scripted run should name its composition rather than inherit whatever the machine holds — which is why `-p` gained `--config` here instead.
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.zh.md
index 6c6f3ecd54..b5e47e188d 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-personal-composition-layer.zh.md
@@ -12,17 +12,17 @@ patch 会替换目标行的整个 `config`，因此几个月前写下的个人
 
 它还在同一批值上与类型化 settings 争夺所有权。`llm-deepseek` 与 `llm-pi-ai` 都注册了 settings namespace，而同样的字段也能通过 patch 它们的行抵达——于是谁赢取决于层序，而不取决于这个值的语义。这正是 [user-settings seam](../architecture/2026-07-28-user-settings-seam.md) 要消除的所有权歧义。
 
-最后，本应与它互为冗余的那条显式通道并未覆盖所有界面：`dsh -p`、`dsh meta` 和 `dsh upgrade` 都拒绝 `--config`。对这些界面来说，隐式文件不是两条 composition 路径之一——它是唯一的一条。
+最后，本应与它互为冗余的那条显式通道并未覆盖所有界面：`dsh -p` 拒绝 `--config`，当时的 `meta` 与 `upgrade` 子命令同样如此。对这些界面来说，隐式文件不是两条 composition 路径之一——它是唯一的一条。
 
 ## Decision
 
 删掉隐式的那一层，并把显式的那一层补完整。
 
-**每个会启动的界面都接受 `--config` 与 `--config-replace`。** `dsh -p`、`dsh meta` 和 `dsh upgrade` 与 TUI 看齐，因此只要有配置树启动的地方，就能点名一棵树。无头模式下的 `--config-replace` 树仍必须挂载 webserver 行，因为该界面是通过浏览器所用的同一个 HTTP 网关访问自己的 agent 的；`AppCLIEntry` 现在会在失败信息里说明这条契约，而不是只报告某个服务缺失。
+**每个会启动的界面都接受 `--config`。** `dsh -p` 与本来就有该标志的界面看齐，因此只要有配置树启动的地方，就能点名一份 overlay。TUI、`meta` 与 `upgrade` 由[显式配置入口](2026-08-03-explicit-config-dsh-entrypoint.md)并行移除，它同时删除了整棵树的 `--config-replace` 路径；本次变更在这一侧留下的就是 headless——它此前拒绝该标志，隐式文件是它唯一的 composition 路径。
 
 **`$DSH_HOME/config.yaml` 不再被读取、监视或 dump。** `PERSONAL_CONFIG_FILENAME`、`loadPersonalPatches`、`watchPersonalPatches`，以及专为它挂载的那一行 config-only HMR，全部删除。留在该路径上的文件是惰性的。Harness home 仍然保有 `settings.yaml`、`.credentials.yaml` 和 `.env`；overlay 也仍然可以放在那里，但它是一条待点名的路径，而不是一层待发现的配置。
 
-因此 `--config` 的含义略有变化：它过去是*替代*个人 overlay，现在它本身*就是*用户 overlay。`--config-replace` 保持不变。
+因此 `--config` 的含义略有变化：它过去是*替代*个人 overlay，现在它本身*就是*用户 overlay。
 
 日常能力各自保有归属。模型与 provider 参数已经属于各适配器的类型化 settings namespace。`repository-plugins` 行随交付配置以空列表挂载，因此仓库插件列表今天是一个 `--config` overlay，等 settings namespace 落地后归它。MCP 服务器仍然是 `--config` composition，这也是 [CLI README](../../../../apps/cli/README.md) 现在的写法。
 
@@ -44,4 +44,4 @@ patch 会替换目标行的整个 `config`，因此几个月前写下的个人
 
 **等 settings 驱动的 repository 与 MCP manager 落地后再删。** 在 `--config` 覆盖所有界面之后，这条依赖已无必要，故否决：那两个 manager 会让这两种场景*更好用*，但只要标志处处可用，先删掉隐式层就不损失任何东西。
 
-**只为 `dsh -p` 保留它，因为那里原本没有标志。** 否决：那恰恰是最需要显式的界面。CI 或脚本化运行应当点名自己的 composition，而不是继承机器上恰好存在的东西。
+**只为 `dsh -p` 保留它，因为那里原本没有标志。** 否决：那恰恰是最需要显式的界面。CI 或脚本化运行应当点名自己的 composition，而不是继承机器上恰好存在的东西——所以这里改为给 `-p` 补上 `--config`。
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.i18n.yaml
index 60bfb506ae..5059240ce9 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.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 .agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md
-2026-08-04-remove-profile-json-entry.md: 8ca81e2364e095d90c87febfe705ddec14269bf4
-2026-08-04-remove-profile-json-entry.zh.md: bbc3957d11a2051e7c1f9eaaed52d8af38fa1e5b
+2026-08-04-remove-profile-json-entry.md: 90d90adc8c4a6828f3ce49253150d09527a8304a
+2026-08-04-remove-profile-json-entry.zh.md: 60646a0ffc76ec967fef57f54ff0865b3c842754
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md
index 8ca81e2364..90d90adc8c 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md
@@ -12,7 +12,7 @@ Meanwhile the fields it mapped acquired owners elsewhere. `provider` and `model`
 
 ## Decision
 
-`PROFILE_DIR`, `PROFILE_FILE`, `ProfileMapping`, `PROFILE_MAPPINGS`, and `readProfile()` are deleted along with the patch source that consumed them. `AppCLIEntry` composes its patches from CLI flags and the resolved frontend `distIndex` only; the layers around it — shipped base, surface overlay, `--config` or the personal overlay, and `--config-replace` — are unchanged.
+`PROFILE_DIR`, `PROFILE_FILE`, `ProfileMapping`, `PROFILE_MAPPINGS`, and `readProfile()` are deleted along with the patch source that consumed them. `AppCLIEntry` composes its patches from CLI flags and the resolved frontend `distIndex` only; the layers around it — shipped base, surface overlay, and the `--config` overlay — are unchanged.
 
 A `.dsh-tmp-profile/config.json` on disk is now ignored completely. There is no migration, no replacement format, and no deprecation diagnostic: the file never had a producer, so there is no installed base to carry forward, and the [pre-release stance](../../../../AGENTS.md) rejects compatibility shims.
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md
index bbc3957d11..60646a0ffc 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## Decision
 
-`PROFILE_DIR`、`PROFILE_FILE`、`ProfileMapping`、`PROFILE_MAPPINGS` 和 `readProfile()` 连同消费它们的那个 patch 来源一并删除。`AppCLIEntry` 现在只从 CLI 标志和解析出的前端 `distIndex` 合成 patch；它周围的各层——交付基座、surface overlay、`--config` 或个人 overlay、以及 `--config-replace`——保持不变。
+`PROFILE_DIR`、`PROFILE_FILE`、`ProfileMapping`、`PROFILE_MAPPINGS` 和 `readProfile()` 连同消费它们的那个 patch 来源一并删除。`AppCLIEntry` 现在只从 CLI 标志和解析出的前端 `distIndex` 合成 patch；它周围的各层——交付基座、surface overlay、以及 `--config` overlay——保持不变。
 
 磁盘上的 `.dsh-tmp-profile/config.json` 现在被完全忽略。没有迁移、没有替代格式、也没有弃用诊断：该文件从来没有生产方，因此不存在需要承接的存量，而[未发布阶段的立场](../../../../AGENTS.md)拒绝兼容垫片。
 

From 84b119619ae3ad5482cd36eb874e728ea1a9b1e3 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 5 Aug 2026 12:42:06 +0800
Subject: [PATCH 027/516] chore(environment): match the tightened
 published-files constraint

Master narrowed `files` to the built entrypoints plus declarations; the
new environment package still carried declaration maps and `src`.
---
 packages/util/environment/package.json | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/util/environment/package.json b/packages/util/environment/package.json
index 94a2a76ef6..6029a9f52a 100644
--- a/packages/util/environment/package.json
+++ b/packages/util/environment/package.json
@@ -21,9 +21,7 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {

From c836fcd416ddf0bc0c384fa24d6abbebdeb12c8d Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Wed, 5 Aug 2026 12:43:35 +0800
Subject: [PATCH 028/516] feat(telemetry): add feedback-gated OTEL modes

---
 ...3-session-telemetry-otel-revival.i18n.yaml |   4 +-
 ...26-07-23-session-telemetry-otel-revival.md |   4 +-
 ...07-23-session-telemetry-otel-revival.zh.md |   4 +-
 .../2026-07-28-feedback-command.i18n.yaml     |   4 +-
 .../feature/2026-07-28-feedback-command.md    |   8 +-
 .../feature/2026-07-28-feedback-command.zh.md |   8 +-
 ...feedback-gated-session-telemetry.i18n.yaml |   6 +
 ...-08-05-feedback-gated-session-telemetry.md |  35 ++++
 ...-05-feedback-gated-session-telemetry.zh.md |  35 ++++
 docs/config-catalog.md                        |  16 +-
 docs/cordis-catalog/events.md                 |   2 +-
 docs/cordis-catalog/services.md               |   2 +-
 docs/event-producer-consumer.md               |   4 +-
 .../tests/fixtures/telemetry-otel-driver.ts   |  10 ++
 .../tests/fixtures/telemetry-otel.cordis.yml  |   9 +
 examples/package.json                         |   2 +
 packages/feedback/README.i18n.yaml            |   4 +-
 packages/feedback/README.md                   |   2 +-
 packages/feedback/README.zh.md                |   2 +-
 .../command-feedback/README.i18n.yaml         |   4 +-
 packages/feedback/command-feedback/README.md  |   4 +-
 .../feedback/command-feedback/README.zh.md    |   4 +-
 packages/telemetry/README.i18n.yaml           |   4 +-
 packages/telemetry/README.md                  |   6 +-
 packages/telemetry/README.zh.md               |   6 +-
 .../session-telemetry-otel/README.i18n.yaml   |   4 +-
 .../session-telemetry-otel/README.md          |  16 +-
 .../session-telemetry-otel/README.zh.md       |  16 +-
 .../session-telemetry-otel/package.json       |   2 +
 .../session-telemetry-otel/src/index.ts       |  94 +++++++----
 .../session-telemetry-otel/src/invariant.ts   |   7 +-
 .../tests/loader-composition.e2e.ts           |  93 ++++++++---
 .../session-telemetry-otel/tests/otel.spec.ts |  90 +++++++++-
 .../session-telemetry-otel/tsconfig.json      |   3 +
 .../session-telemetry/README.i18n.yaml        |   4 +-
 .../telemetry/session-telemetry/README.md     |  11 +-
 .../telemetry/session-telemetry/README.zh.md  |  11 +-
 .../session-telemetry/src/coordinator.ts      | 158 ++++++++++++------
 .../telemetry/session-telemetry/src/index.ts  |  17 +-
 .../session-telemetry/tests/telemetry.spec.ts |  93 ++++++++++-
 pnpm-lock.yaml                                |   9 +
 41 files changed, 635 insertions(+), 182 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md

diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index cd9e4f7e9f..3f487762d6 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.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 .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
-2026-07-23-session-telemetry-otel-revival.md: a58598d8a956d47cb0cf6aa3e659f38314bc4b17
-2026-07-23-session-telemetry-otel-revival.zh.md: cc09717e349d5ae2ab5157bf46de30b1823c775f
+2026-07-23-session-telemetry-otel-revival.md: dcbff9757cbb730b66f456535fbd7ae471b6ffd1
+2026-07-23-session-telemetry-otel-revival.zh.md: c3a098041795fa92bb4e0dd421ca09be94907cb8
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
index a58598d8a9..dcbff9757c 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
@@ -14,7 +14,7 @@ Every deployment that wants harness sessions in an observability stack must hand
 
 - **`@deepseek-ai/dsh-session-telemetry`** — the seam. `TelemetryBackend` (`emit`/`flush?`/`shutdown`), the service-registered `Telemetry` form, and `TelemetryCoordinator` owning capture: adoption with cursor read-back, the per-append firehose (project → `structuredClone` → redact → `emit`, zero I/O), the fixed first-chunk-per-(turn, step) projection, the `agent/error` relay, and dispose-time `shutdown` records.
 - **The `telemetry/record` waterfall** — the delta over the branch version and the seam's redaction extension point. Every record passes it before reaching any backend; the seam ships NO rules of its own — the innermost `next()` is a pass-through, deployments mount their rules as listeners (stacking by transforming `next()`'s return value), and a throwing rule withholds the record fail-closed. Redaction applies to the exported copy only; the canonical log is never rewritten.
-- **`@deepseek-ai/dsh-session-telemetry-otel`** — the reference backend: OTel JS SDK log pipeline (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter), configured verbatim through `exporter`/`processor` passthroughs. `exporter.url` is required and validated at load; unmounted or unconfigured, nothing leaves the process.
+- **`@deepseek-ai/dsh-session-telemetry-otel`** — the reference backend: OTel JS SDK log pipeline (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter), configured verbatim through `exporter`/`processor` passthroughs. Its default `FULL` mode requires `exporter.url`; the later [feedback-gated telemetry decision](2026-08-05-feedback-gated-session-telemetry.md) adds `FEEDBACK_ONLY` and `DISABLED` delivery modes without moving the redaction or backend boundary.
 
 The boundary axiom holds: the harness's aspect ends at `emit()`. Batching, retry, queueing, and loss policy are the reporting SDK's, configured through passthroughs — delivery is best-effort (at-most-once across a crash), which the READMEs state plainly.
 
@@ -34,4 +34,4 @@ The boundary axiom holds: the harness's aspect ends at `emit()`. Batching, retry
 
 ## Consequences
 
-A deployment adds one `cordis.yml` entry with an OTLP endpoint and gets its session stream in any OTel-compatible stack; removing the entry is the opt-out, with no residual state. A rule-free deployment exports records exactly as captured — including any credentials embedded in file contents or command output — so a deployment crossing a trust boundary must mount `telemetry/record` listeners, and both READMEs state this plainly. Where rules are mounted, exported bodies can differ from canonical log bytes, so receivers must not treat telemetry as a byte-exact replica; the log remains the source of truth. Crash durability is explicitly out of scope until the outbox decision above is revisited.
+A deployment adds one `cordis.yml` entry with an OTLP endpoint and gets its session stream in any OTel-compatible stack. `FULL` preserves that behavior by default, `FEEDBACK_ONLY` withholds records until feedback releases a prefix, and `DISABLED` constructs no reporting pipeline; removing the entry remains a silent opt-out, while the disabled mode keeps the local feedback warning. A rule-free deployment exports records exactly as captured — including any credentials embedded in file contents or command output — so a deployment crossing a trust boundary must mount `telemetry/record` listeners, and both READMEs state this plainly. Where rules are mounted, exported bodies can differ from canonical log bytes, so receivers must not treat telemetry as a byte-exact replica; the log remains the source of truth. Crash durability is explicitly out of scope until the outbox decision above is revisited.
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index cc09717e34..c3a0980417 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 - **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的收养、逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、固定的每 (turn, step) 首 chunk 投影、`agent/error` 转发、以及 dispose 时的 `shutdown` 记录。
 - **`telemetry/record` waterfall** —— 相对分支版本的增量，也是该 seam 的脱敏扩展点。每条记录抵达任何 backend 前必经此处；seam 自身不带任何规则——最内层 `next()` 原样透传，部署方以监听器挂载自己的规则（通过变换 `next()` 的返回值堆叠），抛异常的规则将该记录 fail-closed 扣下。脱敏只作用于导出副本；canonical log 永不改写。
-- **`@deepseek-ai/dsh-session-telemetry-otel`** —— 参考 backend：OTel JS SDK 日志管线（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter），经 `exporter`/`processor` passthrough 原样配置。`exporter.url` 必填且加载时校验；未挂载或未配置时，任何数据都不会离开进程。
+- **`@deepseek-ai/dsh-session-telemetry-otel`** —— 参考 backend：OTel JS SDK 日志管线（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter），经 `exporter`/`processor` passthrough 原样配置。其默认 `FULL` 模式要求 `exporter.url`；后续的[反馈门控遥测决策](2026-08-05-feedback-gated-session-telemetry.md)增加了 `FEEDBACK_ONLY` 与 `DISABLED` 投递模式，但未移动脱敏或后端边界。
 
 边界公理保持不变：harness 的职责止于 `emit()`。批处理、重试、排队与丢失策略属于 reporting SDK，经 passthrough 配置——投递是尽力而为（崩溃时至多一次），README 对此如实陈述。
 
@@ -34,4 +34,4 @@ Status: implemented
 
 ## Consequences
 
-部署方在 `cordis.yml` 加一个带 OTLP endpoint 的条目即可把会话流接入任何 OTel 兼容体系；删除条目即退出，无残留状态。未挂载规则的部署导出的记录与捕获时完全一致——包括文件内容与命令输出中内嵌的任何凭据——因此跨信任边界的部署必须挂载 `telemetry/record` 监听器，两个 README 对此如实陈述。挂载规则后，导出的 body 可能与 canonical log 字节不同，接收端不得把遥测当作字节精确副本；日志仍是唯一事实源。崩溃持久性在上述 outbox 决定重启前明确不在范围内。
+部署方在 `cordis.yml` 加一个带 OTLP endpoint 的条目即可把会话流接入任何 OTel 兼容体系。`FULL` 默认保留该行为，`FEEDBACK_ONLY` 在反馈释放前暂存记录前缀，`DISABLED` 则不构造上报流水线；删除条目仍是静默退出方式，而禁用模式会保留本地反馈警告。未挂载规则的部署导出的记录与捕获时完全一致，包括文件内容与命令输出中内嵌的任何凭据。因此，跨信任边界的部署必须挂载 `telemetry/record` 监听器，两个 README 对此如实陈述。挂载规则后，导出的 body 可能与 canonical log 字节不同，接收端不得把遥测当作字节精确副本；日志仍是真源。崩溃持久性在上述 outbox 决定重启前明确不在范围内。
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
index 7a429953d8..be039deb2c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-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 .agents/notes/implemented/feature/2026-07-28-feedback-command.md
-2026-07-28-feedback-command.md: 1c093d0e37eb72dc66e3c5569bd642557dde56a1
-2026-07-28-feedback-command.zh.md: 300946a71ac7485a4bc787dd70ae5357147627f3
+2026-07-28-feedback-command.md: 963153ceb4332b74693ff5c1d248c616ff4e8de9
+2026-07-28-feedback-command.zh.md: 4dd02dcfb8d0606436c22e269db8c0d6cf163cee
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
index 1c093d0e37..963153ceb4 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
@@ -18,7 +18,7 @@ The package declares the log-only `feedback/record { text }` session event and e
 
 `dsh-commands` still writes its `command/run` / `command/done` lifecycle pair around `/feedback`, but this command sets `recordInput: false`. Its `command/run` therefore carries the command identity and source without `args`; the feedback text exists only in `feedback/record`, while `command/done` carries the acknowledgement outcome. All three records are log-only and non-surface. Their appends start persistence's ordinary eager drain; nothing forces a flush, so acknowledgement reports that the feedback is in the log rather than already on disk.
 
-Capture is deliberately inert: nothing in this repository reads `feedback/record`.
+Capture remains inert for the running agent and model. The optional OTel telemetry package later adds one infrastructure consumer: it observes `feedback/record` as a release trigger in `FEEDBACK_ONLY` mode and as the local-only warning trigger in `DISABLED` mode, without changing the feedback event or command path. See [Feedback-gated session telemetry](2026-08-05-feedback-gated-session-telemetry.md).
 
 ### Why feedback owns an event
 
@@ -34,7 +34,7 @@ Surrounding whitespace is discarded, but nothing else is parsed. `/feedback /pla
 
 ### A new group
 
-`packages/feedback/` is a new group because no existing one owns this. `goal/` is objective state, `session-title/` is titles, `core/` is the product spine. The group holds one package; a consumer would join it rather than forcing this one to grow.
+`packages/feedback/` is a new group because no existing one owns this. `goal/` is objective state, `session-title/` is titles, `core/` is the product spine. The group holds one producer package; cross-cutting consumers stay in their owning groups rather than forcing this one to grow.
 
 ## Alternatives considered
 
@@ -48,7 +48,7 @@ Surrounding whitespace is discarded, but nothing else is parsed. `/feedback /pla
 
 **Register the command inside an existing package** such as `packages/ui/commands`. Avoids a new group and its README pair. Rejected: `ctx.commands` is the registry, not a home for arbitrary command implementations, and the requester asked for a standalone package.
 
-**Parse structure out of the text** (category prefixes, severity markers). Rejected as speculative: no consumer exists to use the structure, and any control-word grammar makes the corresponding literal feedback unrecordable. Verbatim text is the widest surface a future consumer can narrow; a parsed one cannot be widened after the fact.
+**Parse structure out of the text** (category prefixes, severity markers). Rejected as speculative: no consumer needs that structure, and any control-word grammar makes the corresponding literal feedback unrecordable. Verbatim text is the widest surface a future consumer can narrow; a parsed one cannot be widened after the fact.
 
 **Add a model-facing tool instead of a slash command.** Rejected: feedback is a direct human observation. Routing it through the model spends a turn, lets the model paraphrase the user's words, and makes the record contingent on the model choosing to call the tool.
 
@@ -58,6 +58,6 @@ The TUI mounts the command unconditionally — no configuration, no dependency o
 
 The package owns one independent append-only event with no cross-event or mutable-data relation for an invariant companion to check. The event follows the session log's existing replay, fork, persistence, and crash-tail behavior.
 
-Deferred: no consumer; no structured fields; no amend or withdraw, since the log is append-only and this package adds no tombstone; and no explicit durability barrier, so an entry recorded immediately before a crash can be lost with any other unflushed tail.
+Deferred: no product or model consumer; no structured fields; no amend or withdraw, since the log is append-only and this package adds no tombstone; and no explicit durability barrier, so an entry recorded immediately before a crash can be lost with any other unflushed tail. The optional telemetry consumer treats the event only as an export-policy trigger.
 
 No snapshot accompanies this change. AGENTS.md asks for a keyless snapshot through a runnable example for product-user-visible behavior; this was skipped at the requester's explicit direction. The package tests plus a real Loader composition test over a `cordis.yml` are the whole of the evidence, alongside interactive verification in the assembled TUI.
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
index 300946a71a..4dd02dcfb8 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 `dsh-commands` 仍会围绕 `/feedback` 写入 `command/run` / `command/done` 生命周期配对，但该命令设置了 `recordInput: false`。因此，它的 `command/run` 携带命令标识与来源，但不携带 `args`；反馈文本只存在于 `feedback/record` 中，而 `command/done` 携带确认结果。三个记录都仅写入日志且非 surface。它们的追加会启动持久化的常规即时排空；没有任何环节强制 flush，因此确认文本报告的是反馈已进入日志，而非已经落盘。
 
-采集刻意不产生后续动作：本仓库中没有任何代码读取 `feedback/record`。
+采集对正在运行的 agent 与模型仍不产生后续动作。可选的 OTel 遥测包后续增加了一个基础设施消费方：它在 `FEEDBACK_ONLY` 模式下将 `feedback/record` 作为释放触发器，在 `DISABLED` 模式下将其作为本地警告触发器，且不改变反馈事件或命令路径。见[反馈门控的会话遥测](2026-08-05-feedback-gated-session-telemetry.md)。
 
 ### 为何反馈拥有自己的事件
 
@@ -34,7 +34,7 @@ Status: implemented
 
 ### 一个新的分组
 
-`packages/feedback/` 是新分组，因为现有分组都不拥有此职责：`goal/` 负责目标状态，`session-title/` 负责标题，`core/` 是产品主干。该分组目前只有一个包；未来的消费方应加入该分组，而不是迫使这个包不断膨胀。
+`packages/feedback/` 是新分组，因为现有分组都不拥有此职责：`goal/` 负责目标状态，`session-title/` 负责标题，`core/` 是产品主干。该分组只包含一个生产方包；跨领域的消费方留在各自所属的分组，而不是迫使这个包不断膨胀。
 
 ## 考虑过的替代方案
 
@@ -48,7 +48,7 @@ Status: implemented
 
 **在现有包中注册该命令**，例如 `packages/ui/commands`。可省去新分组及其双语 README。已否决：`ctx.commands` 是注册表，而不是任意命令实现的归属地；且请求者明确要求独立的包。
 
-**从文本中解析结构**（类别前缀、严重程度标记）。已否决，属于投机设计：目前没有消费方使用该结构，而任何控制词语法都会让对应的字面反馈无法记录。原样文本是未来消费方可以收窄的最宽接口；而已被解析的接口无法事后放宽。
+**从文本中解析结构**（类别前缀、严重程度标记）。已否决，属于投机设计：没有消费方需要该结构，而任何控制词语法都会让对应的字面反馈无法记录。原样文本是未来消费方可以收窄的最宽接口；而已被解析的接口无法事后放宽。
 
 **改为提供面向模型的工具。** 已否决：反馈是人类的直接观察。经由模型会消耗一个轮次、让模型改写用户的原话，并使记录取决于模型是否选择调用该工具。
 
@@ -58,6 +58,6 @@ TUI 无条件挂载该命令：没有配置，也不依赖 goal 栈。无头 CLI
 
 本包拥有一个独立的仅追加事件，不存在跨事件关系或可变数据关系可供不变式伴生插件检查。该事件遵循会话日志现有的回放、fork、持久化和崩溃尾部行为。
 
-延期事项：没有消费方；没有结构化字段；不支持修改或撤回，因为日志仅追加且本包不新增 tombstone；且没有显式持久化屏障，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。
+延期事项：没有产品或模型消费方；没有结构化字段；不支持修改或撤回，因为日志仅追加且本包不新增 tombstone；且没有显式持久化屏障，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。可选的遥测消费方只将该事件作为导出策略触发器。
 
 本次变更不附带 snapshot。AGENTS.md 要求面向产品用户的可见行为变更通过可运行示例附带无密钥 snapshot；此项按请求者的明确指示跳过。包测试连同一个基于真实 `cordis.yml` 的 Loader 组合测试即为全部证据，此外还有在组装后 TUI 中的交互验证。
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
new file mode 100644
index 0000000000..d12ad78728
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.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-08-05-feedback-gated-session-telemetry.md
+2026-08-05-feedback-gated-session-telemetry.md: 21a9028c603f3faaec39b2ddb8ef14644d6c84d4
+2026-08-05-feedback-gated-session-telemetry.zh.md: ea94c743b962a93a5fc64bdc2e4ed103aadecc99
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
new file mode 100644
index 0000000000..21a9028c60
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
@@ -0,0 +1,35 @@
+# Agent Note: Feedback-gated session telemetry
+
+Status: implemented
+
+English | [中文](2026-08-05-feedback-gated-session-telemetry.zh.md)
+
+## Problem
+
+Session telemetry originally has one mounted behavior: every accepted record enters the reporting backend immediately. Deployments need two stricter policies without replacing the plugin: hold a session's telemetry unless its user records feedback, or disable reporting while still explaining what happens to feedback. The policy must preserve the existing full-export default and the telemetry seam's redaction-before-backend boundary.
+
+## Decision
+
+`@deepseek-ai/dsh-session-telemetry-otel` exposes three uppercase `mode` values:
+
+- `FULL` is the default and preserves immediate delivery to the configured OTel pipeline.
+- `FEEDBACK_ONLY` captures redacted copies in memory and releases the pending session prefix when `feedback/record` is appended. The released prefix includes the feedback event itself. Records appended after that event form another withheld prefix until another feedback event releases them.
+- `DISABLED` constructs no exporter, processor, or logger provider. A `feedback/record` listener prints that nothing is shared and the feedback remains local.
+
+The generic telemetry coordinator owns the delivery distinction as `immediate` or `held`. Both paths project, clone, and run `telemetry/record` listeners at capture time. Immediate delivery sends the accepted record to the backend and advances the session's handoff cursor. Held delivery retains the accepted record per session without moving that cursor. `release(session)` submits the retained records in order, contains each backend failure independently, advances the cursor only for submitted records, and removes the released prefix.
+
+The OTel feedback listener is registered after the coordinator's session listener. Cordis therefore gives the coordinator the feedback append first, then the OTel listener releases a prefix that already contains that event. `exporter.url` is required in `FULL` and `FEEDBACK_ONLY`; `DISABLED` does not validate or use exporter configuration.
+
+## Alternatives considered
+
+**Open a session permanently after its first feedback.** Rejected because later work would be shared without another feedback act and the plugin would need additional open-session state. Releasing one pending prefix per feedback has the smaller state machine and the narrower sharing boundary.
+
+**Buffer after `TelemetryCoordinator.emit()` in the OTel backend.** Rejected because the coordinator would advance its handoff cursor before a record became eligible for upload. A plugin rebuild would then lose the only retained copy and incorrectly treat the prefix as handed off.
+
+**Replay the canonical session log when feedback arrives.** Rejected because replay would repeat projection and redaction, exclude telemetry operation records that are not session events, and require more lifecycle state to distinguish previously released prefixes.
+
+**Use an unmounted plugin as the disabled state.** That remains the silent opt-out, but it cannot warn when feedback is recorded. The explicit disabled mode lets a deployment keep one configuration shape and communicate that the local feedback did not leave the process.
+
+## Consequences
+
+`FULL` remains source- and wire-compatible with the original default. `FEEDBACK_ONLY` retains deep-copied, already-redacted records in process memory until feedback or session collection; a crash before release uploads nothing from that prefix. A clean shutdown after the last feedback is part of the new withheld suffix, so feedback-only streams do not carry a reliable shutdown or crash signal. Each later feedback releases the suffix accumulated since the previous one. `DISABLED` can omit `exporter.url`, does no reporting work, and keeps feedback only in the canonical session log.
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
new file mode 100644
index 0000000000..ea94c743b9
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
@@ -0,0 +1,35 @@
+# Agent Note：反馈门控的会话遥测
+
+Status: implemented
+
+[English](2026-08-05-feedback-gated-session-telemetry.md) | 中文
+
+## 问题
+
+会话遥测原本只有一种已挂载行为：每条已接受记录都立即进入上报后端。部署方需要两种更严格的策略，且不替换插件：只有用户记录反馈时才释放该会话的遥测，或禁用上报并仍向用户说明反馈的去向。该策略必须保留现有的全量导出默认值，以及遥测 seam 在记录抵达后端之前脱敏的边界。
+
+## 决策
+
+`@deepseek-ai/dsh-session-telemetry-otel` 公开三个大写的 `mode` 值：
+
+- `FULL` 是默认值，保留向已配置 OTel 流水线的即时投递。
+- `FEEDBACK_ONLY` 在内存中捕获已脱敏副本，并在追加 `feedback/record` 时释放待处理的会话前缀。已释放前缀包含反馈事件本身。在该事件之后追加的记录会形成另一个暂存前缀，直到下一个反馈事件将其释放。
+- `DISABLED` 不构造导出器、处理器或日志提供方。`feedback/record` 监听器会输出警告，说明什么都不会共享，且反馈仍留在本地。
+
+通用遥测协调器以 `immediate` 或 `held` 的形式拥有这两种投递方式。两条路径都会在捕获时进行投影、深拷贝，并运行 `telemetry/record` 监听器。即时投递把已接受记录发送到后端，并推进会话的 handoff 游标。暂存投递按会话保留已接受记录，且不移动该游标。`release(session)` 按顺序提交保留的记录，独立隔离每个后端失败，仅为已提交的记录推进游标，并移除已释放前缀。
+
+OTel 反馈监听器在协调器的会话监听器之后注册。因此，Cordis 先将反馈追加交给协调器，再由 OTel 监听器释放已包含该事件的前缀。`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填；`DISABLED` 不校验也不使用导出器配置。
+
+## 考虑过的替代方案
+
+**会话在首次反馈后永久开放。** 已否决，因为后续工作会在用户未再次提交反馈的情况下被共享，而且插件需要额外的会话开放状态。每次反馈只释放一个待处理前缀，状态机更小，共享边界也更窄。
+
+**在 OTel 后端的 `TelemetryCoordinator.emit()` 之后缓冲。** 已否决，因为协调器会在记录具备上传资格前推进 handoff 游标。插件重建后，唯一保留的副本会丢失，而协调器会错误地将该前缀视为已交接。
+
+**反馈到达时回放权威会话日志。** 已否决，因为回放会重复执行投影与脱敏，排除不属于会话事件的遥测运维记录，且需要更多生命周期状态才能区分已释放前缀。
+
+**以不挂载插件表示禁用状态。** 这仍然是静默退出方式，但无法在记录反馈时输出警告。显式禁用模式让部署方可以保持同一种配置形态，并说明本地反馈未离开进程。
+
+## 后果
+
+`FULL` 与原有默认值保持源码及协议兼容。`FEEDBACK_ONLY` 会在进程内存中保留已深拷贝且已脱敏的记录，直到收到反馈或会话被回收；释放前发生崩溃时，该前缀不上传任何内容。上次反馈之后的干净关闭属于新的暂存后缀，因此仅反馈的流不携带可靠的关闭或崩溃信号。每个后续反馈都会释放从上一个反馈开始累积的后缀。`DISABLED` 可省略 `exporter.url`，不执行任何上报工作，并仅在权威会话日志中保留反馈。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index f552e6ab63..0c4fb632c1 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1159,12 +1159,13 @@ Requires: `sessions`
 
 ```ts config-catalog
 /**
- * Plugin configuration: two verbatim SDK option shapes plus nothing else.
- * `exporter.url` is the one field this package validates itself — required,
- * no default, must parse as an `http(s)` URL — because a missing endpoint
- * must fail at plugin load, not at first export.
+ * Plugin configuration: one sharing policy plus two verbatim SDK option
+ * shapes. `exporter.url` is required for modes that upload and unused for
+ * `DISABLED`.
  */
 export interface Config {
+  /** Sharing policy; defaults to immediate `FULL` delivery. */
+  mode?: TelemetryMode
   /**
    * Passed verbatim to the SDK's OTLP/HTTP log exporter — the complete
    * `OTLPExporterNodeConfigBase` shape (`headers`, `timeoutMillis`,
@@ -1172,7 +1173,7 @@ export interface Config {
    * is the one field this package requires and validates itself.
    */
   exporter?: OTLPExporterNodeConfigBase & {
-    /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required; validated at plugin load. */
+    /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required outside `DISABLED`; validated at load. */
     url?: string
   }
   /**
@@ -1181,11 +1182,14 @@ export interface Config {
    */
   processor?: Omit<BatchLogRecordProcessorOptions, 'exporter'>
 }
+
+/** Session-sharing policy selected by {@link Config.mode}. */
+export type TelemetryMode = typeof TELEMETRY_MODES[number]
 ```
 
 Depends on: `BatchLogRecordProcessorOptions` (`@opentelemetry/sdk-logs`) · `OTLPExporterNodeConfigBase` (`@opentelemetry/otlp-exporter-base`)
 
-Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:40`](../packages/telemetry/session-telemetry-otel/src/index.ts)
+Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:54`](../packages/telemetry/session-telemetry-otel/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title`
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 54291934fd..d159fa0a53 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -853,7 +853,7 @@ Transform one outbound record before it reaches the backend. This waterfall is t
 'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
 ```
 
-Source: [`packages/telemetry/session-telemetry/src/index.ts:41`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/telemetry/session-telemetry/src/index.ts:42`](../../packages/telemetry/session-telemetry/src/index.ts)
 
 ## `tools/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 395d0850e1..e051463877 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -1996,7 +1996,7 @@ flush?(): void
 abstract shutdown(): Promise<void>
 ```
 
-Source: [`packages/telemetry/session-telemetry/src/index.ts:135`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/telemetry/session-telemetry/src/index.ts:140`](../../packages/telemetry/session-telemetry/src/index.ts)
 
 ## `ctx.tokenMeter` — `TokenMeterService`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index fabd16bbdd..4ccc19f305 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -33,7 +33,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:58`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:71`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:81`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:93`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:93`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:103`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `slash/input-begin-command` | `bail` | [`packages/client/ui-slash/src/types.ts:230`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` |
 | `slash/input-consume-token` | `bail` | [`packages/client/ui-slash/src/types.ts:244`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` |
@@ -45,7 +45,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:131`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
-| `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:41`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - |
+| `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:42`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:156`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
 | `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:138`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
 | `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:113`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`timeout-policy`](../packages/timeout/timeout-policy) |
diff --git a/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts b/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts
index 02be1a9011..72305f0724 100644
--- a/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts
+++ b/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts
@@ -11,6 +11,7 @@ import { createServer } from 'node:http'
 import { once } from 'node:events'
 import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 import { runOneShot } from '@deepseek-ai/dsh-cli-demo/src/cli.ts'
+import { recordFeedback } from '@deepseek-ai/dsh-command-feedback'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('telemetry-otel driver requires a config path')
@@ -35,6 +36,15 @@ try {
   // The fixture credential rides the model-visible user message; the exported
   // copy must scrub it while the canonical log keeps the original bytes.
   await runOneShot(ctx, { task: 'prove telemetry with key sk-e2efixture1234567890' })
+  const mode = process.env.DSH_TELEMETRY_E2E_MODE ?? 'FULL'
+  if (mode !== 'FULL') {
+    const [agent] = ctx.get('agents')?.roots() ?? []
+    if (agent === undefined) throw new Error('telemetry-otel driver requires one root agent')
+    recordFeedback(agent.session, 'fixture feedback')
+    if (mode === 'FEEDBACK_ONLY') {
+      await runOneShot(ctx, { task: 'post-feedback private suffix' })
+    }
+  }
 } finally {
   await ctx.fiber.dispose()
 }
diff --git a/examples/headless-agent/tests/fixtures/telemetry-otel.cordis.yml b/examples/headless-agent/tests/fixtures/telemetry-otel.cordis.yml
index 34e23b828e..1433173768 100644
--- a/examples/headless-agent/tests/fixtures/telemetry-otel.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/telemetry-otel.cordis.yml
@@ -2,6 +2,14 @@
 # path, exporting to the mock OTLP collector the driver starts (url via env).
 # The redact-rule entry models a deployment mounting its own scrub rule on the
 # telemetry/record waterfall — the seam itself ships no rules.
+- id: logger-console
+  name: '@cordisjs/plugin-logger-console'
+  config:
+    colors: false
+    levels:
+      default: 3
+    showTime: ''
+
 - id: cli-mock-llm
   name: './cli-mock-llm.ts'
 
@@ -14,6 +22,7 @@
 - id: telemetry-otel
   name: '@deepseek-ai/dsh-session-telemetry-otel'
   config:
+    mode: !!js process.env.DSH_TELEMETRY_E2E_MODE || 'FULL'
     exporter:
       url: !!js process.env.DSH_TELEMETRY_E2E_URL
 
diff --git a/examples/package.json b/examples/package.json
index 51fc48b8fa..0298685693 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -7,6 +7,7 @@
   "dependencies": {
     "@cordisjs/plugin-hmr": "workspace:*",
     "@cordisjs/plugin-include": "workspace:*",
+    "@cordisjs/plugin-logger-console": "workspace:*",
     "@deepseek-ai/dsh-acp-demo": "workspace:*",
     "@deepseek-ai/dsh-agent-spine-demo": "workspace:*",
     "@deepseek-ai/dsh-app-boot": "workspace:*",
@@ -14,6 +15,7 @@
     "@deepseek-ai/dsh-bash-sandbox": "workspace:*",
     "@deepseek-ai/dsh-cli-demo": "workspace:*",
     "@deepseek-ai/dsh-code-runtime-worker": "workspace:*",
+    "@deepseek-ai/dsh-command-feedback": "workspace:*",
     "@deepseek-ai/dsh-compact-basic": "workspace:*",
     "@deepseek-ai/dsh-compact-tool-result-prune": "workspace:*",
     "@deepseek-ai/dsh-fs-local": "workspace:*",
diff --git a/packages/feedback/README.i18n.yaml b/packages/feedback/README.i18n.yaml
index 31ed2d25e8..4ad5a93fb5 100644
--- a/packages/feedback/README.i18n.yaml
+++ b/packages/feedback/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/feedback/README.md
-README.md: 7962a16ee9bc7d8a969a466591d761829cd55d7f
-README.zh.md: aad8f4d797ff16a5ef9be4c968fb28d708bad13e
+README.md: d2a4a5a27e1c661d2f62b328578fd890a0c622ee
+README.zh.md: 2fa42e3bb5f05dfc425356f302f44e497b100f24
diff --git a/packages/feedback/README.md b/packages/feedback/README.md
index 7962a16ee9..d2a4a5a27e 100644
--- a/packages/feedback/README.md
+++ b/packages/feedback/README.md
@@ -8,4 +8,4 @@ The feedback family lets a human record a remark about the session without actin
 |---|---|---|
 | `command-feedback/` | Trigger-independent `feedback/record` event plus the human-facing `/feedback` producer | — |
 
-A recorded remark is log-only: it never enters the model surface or derived history, and no shipped plugin consumes it. A future consumer reads `feedback/record` events from the session log rather than changing how they are captured.
+A recorded remark is log-only: it never enters the model surface or derived history. When mounted, [`dsh-session-telemetry-otel`](../telemetry/session-telemetry-otel/) observes `feedback/record` to release a pending telemetry prefix or warn that disabled telemetry leaves the feedback local; capture itself remains independent of that policy.
diff --git a/packages/feedback/README.zh.md b/packages/feedback/README.zh.md
index aad8f4d797..2fa42e3bb5 100644
--- a/packages/feedback/README.zh.md
+++ b/packages/feedback/README.zh.md
@@ -8,4 +8,4 @@ feedback 家族让人类记录对会话的评价，但不据此采取任何动
 |---|---|---|
 | `command-feedback/` | 与触发方式无关的 `feedback/record` 事件，以及面向用户的 `/feedback` 生产方 | 无 |
 
-被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史，随附插件也不会消费它。未来的消费方从会话日志中读取 `feedback/record` 事件，而不是改变它们的采集方式。
+被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史。挂载后，[`dsh-session-telemetry-otel`](../telemetry/session-telemetry-otel/) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
diff --git a/packages/feedback/command-feedback/README.i18n.yaml b/packages/feedback/command-feedback/README.i18n.yaml
index 47c169ec3f..ea439ce2fe 100644
--- a/packages/feedback/command-feedback/README.i18n.yaml
+++ b/packages/feedback/command-feedback/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/feedback/command-feedback/README.md
-README.md: c9650d6a2c595550545b3dbf07f62e6aa65f39b9
-README.zh.md: ba24276ba1bd71a4eb68c7fdb48a3760bdbec8fc
+README.md: e3b0e58f1746c7bcd1c74ac0990a872a1f24d7d7
+README.zh.md: 40ec871caff6f90b0b1c685e833c874e32a48d16
diff --git a/packages/feedback/command-feedback/README.md b/packages/feedback/command-feedback/README.md
index c9650d6a2c..e3b0e58f17 100644
--- a/packages/feedback/command-feedback/README.md
+++ b/packages/feedback/command-feedback/README.md
@@ -15,7 +15,7 @@ Surrounding whitespace is discarded, but feedback is otherwise unparsed: no trun
 
 ## What this plugin does and does not do
 
-`recordFeedback(session, text)` is the command-independent write path. It rejects empty normalized text and appends `feedback/record { text }`; a different UI, hook, or host integration can call it without constructing a slash command. The `/feedback` handler uses that producer, starts no model work, and no plugin in this repository reads the event.
+`recordFeedback(session, text)` is the command-independent write path. It rejects empty normalized text and appends `feedback/record { text }`; a different UI, hook, or host integration can call it without constructing a slash command. The `/feedback` handler uses that producer and starts no model work. The optional [`dsh-session-telemetry-otel`](../../telemetry/session-telemetry-otel/) consumer observes the event without changing its capture contract.
 
 The feedback text appears in exactly one durable payload: `feedback/record`. [`dsh-commands`](../../ui/commands/README.md) still appends its generic `command/run` / `command/done` pairing, but this definition sets `recordInput: false`, so `command/run` omits `args`; the paired `command/done` carries only the outcome. All three events are log-only and absent from the ordered surface, `deriveMessages()`, and model requests. These appends start persistence's ordinary eager drain, but neither producer forces `session/flush`, so acknowledgement means the feedback is in the log, not that it has reached disk. Rejected empty input leaves only the command pairing settled as `kind: 'error'`, with no `feedback/record`.
 
@@ -52,7 +52,7 @@ Independent of the model request path. Recording appends to the session log only
 
 ## Known Limitations and Deferred Work
 
-- **Nothing consumes the recorded feedback** — capture is deliberately inert. There is no retrieval, aggregation, export, or reporting surface, and no model-facing tool reads `feedback/record`; a consumer is a separate package.
+- **No feedback retrieval or management surface** — the optional OTel plugin uses the event only as a sharing trigger. There is no retrieval, aggregation, categorization, or model-facing tool for `feedback/record`.
 - **No structured fields** — an entry is one free-text string with no category, severity, or referenced-event link, so feedback cannot be filtered by subject without re-reading its text.
 - **No amend or withdraw** — the session log is append-only and this package adds no tombstone, so a mistaken entry stays recorded and can only be superseded by a later one.
 - **No explicit durability barrier** — the acknowledgement follows the append, not a flush, so an entry recorded immediately before a crash can be lost with any other unflushed tail. Feedback is not worth forcing a synchronous disk write for; a consumer that needs one awaits `ctx.sessions.flush(session)`.
diff --git a/packages/feedback/command-feedback/README.zh.md b/packages/feedback/command-feedback/README.zh.md
index ba24276ba1..40ec871caf 100644
--- a/packages/feedback/command-feedback/README.zh.md
+++ b/packages/feedback/command-feedback/README.zh.md
@@ -15,7 +15,7 @@
 
 ## 本插件做什么、不做什么
 
-`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，不启动任何模型工作；本仓库中也没有任何插件读取该事件。
+`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../telemetry/session-telemetry-otel/) 消费方会观察该事件，但不改变它的采集契约。
 
 反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../ui/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
 
@@ -52,7 +52,7 @@ TUI 应用无条件挂载此命令；它没有配置，也不依赖持久 goal 
 
 ## 已知限制与暂缓工作
 
-- **没有任何消费方读取被记录的反馈**：采集刻意不产生任何后续动作。这里没有检索、聚合、导出或报告 surface，也没有面向模型的工具读取 `feedback/record`；消费方是另一个独立包。
+- **没有反馈检索或管理 surface**：可选的 OTel 插件仅将该事件用作共享触发器。本包不为 `feedback/record` 提供检索、聚合、分类或面向模型的工具。
 - **没有结构化字段**：一条条目就是一个自由文本字符串，没有类别、严重程度或关联事件链接，因此无法在不重读文本的情况下按主题过滤反馈。
 - **不支持修改或撤回**：会话日志是仅追加的，本包也不新增 tombstone，因此错误的条目会一直保留在记录中，只能由后续条目取代。
 - **没有显式持久化屏障**：确认文本紧随追加而非 flush，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。为反馈强制同步写盘并不值得；需要该保证的消费方可自行等待 `ctx.sessions.flush(session)`。
diff --git a/packages/telemetry/README.i18n.yaml b/packages/telemetry/README.i18n.yaml
index 41f1bd956f..cd3be8d155 100644
--- a/packages/telemetry/README.i18n.yaml
+++ b/packages/telemetry/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/telemetry/README.md
-README.md: 944cb3f9bac6169feddf8b49bc481cfbe7c6fa9d
-README.zh.md: 795b20abb47e1bf791730cc7f3ebb0522549a271
+README.md: 0adf140a19bd6ab19c4d4139d4ebdae941c0d1b0
+README.zh.md: 57988732e36d105ebcc48adcdab9344a6cccb525
diff --git a/packages/telemetry/README.md b/packages/telemetry/README.md
index 944cb3f9ba..0adf140a19 100644
--- a/packages/telemetry/README.md
+++ b/packages/telemetry/README.md
@@ -2,9 +2,9 @@
 
 English | [中文](README.zh.md)
 
-Outbound session reporting: the telemetry seam plus its OpenTelemetry backend. The design — the boundary axiom (the harness's aspect ends at `emit()`; delivery is the reporting SDK's), the `telemetry/record` waterfall (deployment-mounted redaction rules; the seam ships none), the fixed chunk projection, the handoff cursor, and the operational-record channel — is pinned in [the revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md).
+Outbound session reporting: the telemetry seam plus its OpenTelemetry backend. The boundary axiom, redaction waterfall, fixed chunk projection, handoff cursor, and operational-record channel are pinned in [the revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); immediate, feedback-gated, and disabled delivery are owned by [the mode decision](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md).
 
 | Package | Role |
 |---|---|
-| [`@deepseek-ai/dsh-session-telemetry`](session-telemetry/) | The seam: capture points, projection, redaction, handoff cursor, ops signals, and the minimal backend contract (`emit`/`flush?`/`shutdown`). |
-| [`@deepseek-ai/dsh-session-telemetry-otel`](session-telemetry-otel/) | The backend a deployment loads: the OTel JS SDK's log pipeline (`LoggerProvider` + `BatchLogRecordProcessor` + OTLP/HTTP exporter), configured verbatim through passthroughs. |
+| [`@deepseek-ai/dsh-session-telemetry`](session-telemetry/) | The seam: capture points, projection, redaction, immediate or held handoff, cursor, ops signals, and the minimal backend contract (`emit`/`flush?`/`shutdown`). |
+| [`@deepseek-ai/dsh-session-telemetry-otel`](session-telemetry-otel/) | The backend a deployment loads: `FULL`, `FEEDBACK_ONLY`, or `DISABLED` policy around the OTel JS SDK log pipeline. |
diff --git a/packages/telemetry/README.zh.md b/packages/telemetry/README.zh.md
index 795b20abb4..57988732e3 100644
--- a/packages/telemetry/README.zh.md
+++ b/packages/telemetry/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-面向外部的会话上报：遥测（telemetry）seam 及其 OpenTelemetry 后端。整套设计固定在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中：边界公理（harness 的职责止于 `emit()`，投递由上报 SDK 负责）、`telemetry/record` waterfall（瀑布式事件；脱敏规则由部署方挂载，seam 自身不带任何规则）、固定分片投影、handoff 游标，以及运维记录通道。
+面向外部的会话上报：遥测（telemetry）seam 及其 OpenTelemetry 后端。边界公理、脱敏 waterfall（瀑布式事件）、固定分片投影、handoff 游标及运维记录通道的决定见[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)；即时、反馈门控及禁用投递由[模式决策](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)统一规定。
 
 | 包（package） | 职责 |
 |---|---|
-| [`@deepseek-ai/dsh-session-telemetry`](session-telemetry/) | seam 本体：捕获点、投影、脱敏、handoff 游标、运维信号，以及最小后端契约（`emit`/`flush?`/`shutdown`）。 |
-| [`@deepseek-ai/dsh-session-telemetry-otel`](session-telemetry-otel/) | 部署方要加载的后端：OTel JS SDK 的日志流水线（`LoggerProvider` + `BatchLogRecordProcessor` + OTLP/HTTP 导出器），经透传（passthrough）原样配置。 |
+| [`@deepseek-ai/dsh-session-telemetry`](session-telemetry/) | seam 本体：捕获点、投影、脱敏、即时或暂存交接、游标、运维信号，以及最小后端契约（`emit`/`flush?`/`shutdown`）。 |
+| [`@deepseek-ai/dsh-session-telemetry-otel`](session-telemetry-otel/) | 部署方要加载的后端：围绕 OTel JS SDK 日志流水线实施 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 策略。 |
diff --git a/packages/telemetry/session-telemetry-otel/README.i18n.yaml b/packages/telemetry/session-telemetry-otel/README.i18n.yaml
index b1a2052a3f..6557557b8c 100644
--- a/packages/telemetry/session-telemetry-otel/README.i18n.yaml
+++ b/packages/telemetry/session-telemetry-otel/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/telemetry/session-telemetry-otel/README.md
-README.md: 9b208e291e77bee50d9d4fd14808268dca75f2db
-README.zh.md: 76de1bf1ad58a0239907f3b63c672177874c7966
+README.md: fab2461477b2174bded42ed6f05ae55c7c5f697c
+README.zh.md: ab0191188836e03434adbce527d31b62ead848a3
diff --git a/packages/telemetry/session-telemetry-otel/README.md b/packages/telemetry/session-telemetry-otel/README.md
index 9b208e291e..fab2461477 100644
--- a/packages/telemetry/session-telemetry-otel/README.md
+++ b/packages/telemetry/session-telemetry-otel/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — the only entry a deployment loads. It composes the OTel JS SDK as-is (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP log exporter) and maps each record the seam hands over onto `logger.emit()`, under two instrumentation scopes: ledger records on `@deepseek-ai/dsh-session-telemetry-otel`, operational records on `@deepseek-ai/dsh-session-telemetry-otel/ops`. Resource identity (`service.name`/`service.version`) comes from `dsh-llm`'s `APP_IDENTITY`, the same source the attribution headers use.
+The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — the only entry a deployment loads. Its `mode` decides whether the seam hands records over immediately, releases them only at recorded feedback, or keeps telemetry local. Uploading modes compose the OTel JS SDK as-is (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP log exporter) and map each handed-over record onto `logger.emit()`, under two instrumentation scopes: ledger records on `@deepseek-ai/dsh-session-telemetry-otel`, operational records on `@deepseek-ai/dsh-session-telemetry-otel/ops`. Resource identity (`service.name`/`service.version`) comes from `dsh-llm`'s `APP_IDENTITY`, the same source the attribution headers use.
 
 ## Config
 
@@ -10,6 +10,7 @@ The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — th
 - id: telemetry-otel
   name: '@deepseek-ai/dsh-session-telemetry-otel'
   config:
+    mode: FULL                # FULL (default), FEEDBACK_ONLY, or DISABLED
     exporter:                # passed verbatim to the SDK's OTLP/HTTP log exporter
       url: https://collector.example.com/v1/logs
       headers:
@@ -17,15 +18,21 @@ The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — th
     processor: {}            # optional; passed verbatim to BatchLogRecordProcessor
 ```
 
-`exporter.url` is the one field this package validates itself — required, no default, must parse as `http(s)` — so a missing endpoint fails at plugin load (as does a non-positive-integer `processor.maxExportBatchSize`, which the SDK accepts but then hangs on at shutdown). Everything else is the SDK's option shape, owned and documented by the SDK, and both blocks pass through whole: every `OTLPExporterNodeConfigBase` field (`headers`, `timeoutMillis`, `compression`, `keepAlive`, …) reaches the exporter, and batching, export cadence (`scheduledDelayMillis`), retry, queue bounds, and loss policy under sustained failure are the SDK's documented behavior, tuned through the `processor` passthrough. The backend deliberately implements no `flush()`: the batch processor is the only flusher in the process, which is what makes `shutdown()`'s drain complete. Removing this block from `cordis.yml` is the opt-out: no residual state, no `enabled` flag.
+| `mode` | Behavior |
+|---|---|
+| `FULL` | Default. Each projected record, including lifecycle ops records, is handed to the OTel SDK immediately. |
+| `FEEDBACK_ONLY` | Each `feedback/record` releases the redacted, projected session prefix through that event. Later records wait for another feedback event and remain local if none arrives. |
+| `DISABLED` | No coordinator, provider, processor, or exporter is constructed. No telemetry record leaves the process. A `feedback/record` logs `session telemetry is DISABLED; nothing will be shared and this feedback remains local`; the event remains in the local session log. |
+
+`exporter.url` is required in `FULL` and `FEEDBACK_ONLY`, has no default, and must parse as `http(s)`; it is optional and unused in `DISABLED`. Uploading modes also reject a non-positive-integer `processor.maxExportBatchSize`, which the SDK accepts but then hangs on at shutdown. Everything else is the SDK's option shape, owned and documented by the SDK, and both blocks pass through whole: every `OTLPExporterNodeConfigBase` field (`headers`, `timeoutMillis`, `compression`, `keepAlive`, …) reaches the exporter, and batching, export cadence (`scheduledDelayMillis`), retry, queue bounds, and loss policy under sustained failure are the SDK's documented behavior, tuned through the `processor` passthrough. The backend deliberately implements no `flush()`: the batch processor is the only flusher in the process, which is what makes `shutdown()`'s drain complete.
 
 ## What leaves the machine
 
-Records carry the complete `event.data` as the seam's `telemetry/record` waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (`request/header`), todo text, compaction summaries, hook `stderrSummary`, and the session `cwd` (a local path). The seam ships no redaction rules: with no `telemetry/record` listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see [the seam README](../session-telemetry/README.md#the-redact-waterfall)). Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry.
+In uploading modes, records carry the complete `event.data` as the seam's `telemetry/record` waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (`request/header`), todo text, compaction summaries, hook `stderrSummary`, feedback text, and the session `cwd` (a local path). The seam ships no redaction rules: with no `telemetry/record` listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see [the seam README](../session-telemetry/README.md#the-redact-waterfall)). Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry. `DISABLED` does not construct the SDK pipeline or hand any capture to a backend.
 
 ## Field mapping
 
-Seam record → SDK log record: `time` → `timestamp`/`observedTimestamp`; `severity` → `severityNumber`/`severityText` (INFO 9 / WARN 13 / ERROR 17); `body` → the structured log body; `attributes` verbatim. Receivers dedupe on `(session.id, event.seq)`, alert on severity, and detect crashes by `shutdown`-record absence (a session with activity, no `shutdown` ops record, gone stale ended uncleanly). The marker means telemetry stopped observing the session cleanly — emitted at the session's own disposal, or at application teardown for sessions still running then; a marker followed by more of that session's events is a telemetry reload, not a session restart. Streams are not self-contained across lineage: a resumed session continues its own id's stream from where the previous process left off, and a forked session's stream starts at its inherited boundary — its prefix lives in the parent's stream, stitched via `session.parent_id` + `session.seed_length`. One consequence of continuing rather than replaying: a turn left open mid-stream and never closed marks the previous process dying inside it. The local log is repaired with synthetic closers at resume, but those repairs are never exported — the wire stream stays faithful to what the crashed process actually shipped, and a later clean `shutdown` marker attests only to the resumed process's own exit.
+Seam record → SDK log record: `time` → `timestamp`/`observedTimestamp`; `severity` → `severityNumber`/`severityText` (INFO 9 / WARN 13 / ERROR 17); `body` → the structured log body; `attributes` verbatim. Receivers dedupe on `(session.id, event.seq)` and alert on severity. In `FULL`, they may also detect crashes by `shutdown`-record absence: the marker is emitted at the session's own disposal or application teardown, and a marker followed by more events is a telemetry reload. In `FEEDBACK_ONLY`, a released prefix normally has no later `shutdown` marker, so its absence is not a crash signal. Streams are not self-contained across lineage: a resumed session continues its own id's stream from where the previous process left off, and a forked session's stream starts at its inherited boundary — its prefix lives in the parent's stream, stitched via `session.parent_id` + `session.seed_length`. A resumed local log may contain synthetic closers that were never exported; the wire stream stays faithful to records actually handed to the SDK.
 
 ## Model Experience
 
@@ -39,3 +46,4 @@ None; this package neither assembles nor sends a provider request.
 
 - **Upstream experimental tree** — `@opentelemetry/sdk-logs` is still published from the upstream experimental tree; SDK API churn lands here and only here — the seam contract does not move.
 - **No live-collector coverage** — every test exports to a local mock collector; the keyless Loader-composition e2e (`tests/loader-composition.e2e.ts`) covers the wire shape on every run, and behavior against a real OTLP deployment (auth, TLS, throttling) is the SDK exporter's documented territory.
+- **Feedback-only memory** — each session retains deep-copied, redacted projected records in memory until feedback releases them or the session becomes unreachable. There is no durable pre-feedback spool; a crash before feedback uploads nothing.
diff --git a/packages/telemetry/session-telemetry-otel/README.zh.md b/packages/telemetry/session-telemetry-otel/README.zh.md
index 76de1bf1ad..ab01911888 100644
--- a/packages/telemetry/session-telemetry-otel/README.zh.md
+++ b/packages/telemetry/session-telemetry-otel/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[遥测（telemetry）seam](../session-telemetry/) 的 OpenTelemetry 后端，也是部署方唯一要加载的条目。它原样组合 OTel JS SDK（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP 日志导出器），把 seam 交接过来的每条记录映射到 `logger.emit()`，并使用两个插桩作用域（instrumentation scope）：ledger 记录挂在 `@deepseek-ai/dsh-session-telemetry-otel` 下，运维记录挂在 `@deepseek-ai/dsh-session-telemetry-otel/ops` 下。资源身份（`service.name`/`service.version`）来自 `dsh-llm` 的 `APP_IDENTITY`，与归因标头同源。
+[遥测（telemetry）seam](../session-telemetry/) 的 OpenTelemetry 后端，也是部署方唯一要加载的条目。其 `mode` 决定 seam 是立即交接记录、仅在记录反馈时释放记录，还是将遥测留在本地。上传模式会原样组合 OTel JS SDK（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP 日志导出器），把每条已交接记录映射到 `logger.emit()`，并使用两个插桩作用域（instrumentation scope）：ledger 记录挂在 `@deepseek-ai/dsh-session-telemetry-otel` 下，运维记录挂在 `@deepseek-ai/dsh-session-telemetry-otel/ops` 下。资源身份（`service.name`/`service.version`）来自 `dsh-llm` 的 `APP_IDENTITY`，与归因标头同源。
 
 ## 配置
 
@@ -10,6 +10,7 @@
 - id: telemetry-otel
   name: '@deepseek-ai/dsh-session-telemetry-otel'
   config:
+    mode: FULL                # FULL (default), FEEDBACK_ONLY, or DISABLED
     exporter:                # passed verbatim to the SDK's OTLP/HTTP log exporter
       url: https://collector.example.com/v1/logs
       headers:
@@ -17,15 +18,21 @@
     processor: {}            # optional; passed verbatim to BatchLogRecordProcessor
 ```
 
-`exporter.url` 是本包（package）唯一自行校验的字段：必填、无默认值、必须能解析为 `http(s)`，因此缺失端点会在插件加载时失败（`processor.maxExportBatchSize` 不是正整数时同样如此：SDK 会接受该值，随后却在关闭时因它挂起）。其余全部是 SDK 自己的选项形态，由 SDK 拥有并在 SDK 文档中说明，两个配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是 SDK 的文档化行为，经 `processor` 透传调优。该后端刻意不实现 `flush()`：批处理器是进程内唯一执行 flush 的组件，`shutdown()` 的排空正因如此才是完整的。从 `cordis.yml` 中删除该配置块即为退出方式：无残留状态，也没有 `enabled` 开关。
+| `mode` | 行为 |
+|---|---|
+| `FULL` | 默认值。每条已投影记录都立即交给 OTel SDK，包括生命周期运维记录。 |
+| `FEEDBACK_ONLY` | 每个 `feedback/record` 都会释放截至该事件的已脱敏、已投影会话前缀。后续记录等待下一个反馈事件；如果没有后续反馈，则留在本地。 |
+| `DISABLED` | 不构造协调器、提供方、处理器或导出器。没有遥测记录会离开进程。`feedback/record` 会记录 `session telemetry is DISABLED; nothing will be shared and this feedback remains local`；该事件留在本地会话日志中。 |
+
+`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填，无默认值，且必须能解析为 `http(s)`；在 `DISABLED` 中可省略且不使用。上传模式也会拒绝不是正整数的 `processor.maxExportBatchSize`，SDK 虽会接受该值，但随后会在关闭时挂起。其余全部是 SDK 自己的选项形态，由 SDK 拥有并在 SDK 文档中说明，两个配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是 SDK 的文档化行为，经 `processor` 透传调优。该后端刻意不实现 `flush()`：批处理器是进程内唯一执行 flush 的组件，`shutdown()` 的排空正因如此才是完整的。
 
 ## 哪些数据会离开本机
 
-记录携带完整的 `event.data`，内容以 seam 的 `telemetry/record` waterfall（瀑布式事件）返回的结果为准：用户与 assistant 消息内容、工具参数与工具结果（命令输出、文件内容）、完整的系统提示词与工具 schema（`request/header`）、todo 文本、压缩（compaction）摘要、钩子的 `stderrSummary`，以及会话 `cwd`（一个本地路径）。seam 不带任何脱敏规则：未挂载 `telemetry/record` 监听器时，导出的就是捕获原样的副本，因此向可信边界之外导出的部署方要挂载自己的规则（见 [seam README](../session-telemetry/README.md#the-redact-waterfall)）。无论如何，提供方凭据都不会出现：适配器的 API key 是构造函数参数而非会话事件，因此它们在结构上就不存在于日志中，也就不存在于遥测中。
+在上传模式中，记录携带完整的 `event.data`，内容以 seam 的 `telemetry/record` waterfall（瀑布式事件）返回的结果为准：用户与 assistant 消息内容、工具参数与工具结果（命令输出、文件内容）、完整的系统提示词与工具 schema（`request/header`）、todo 文本、压缩（compaction）摘要、钩子的 `stderrSummary`、反馈文本，以及会话 `cwd`（一个本地路径）。seam 不带任何脱敏规则：未挂载 `telemetry/record` 监听器时，导出的就是捕获原样的副本，因此向可信边界之外导出的部署方要挂载自己的规则（见 [seam README](../session-telemetry/README.md#the-redact-waterfall)）。无论如何，提供方凭据都不会出现：适配器的 API key 是构造函数参数而非会话事件，因此它们在结构上就不存在于日志中，也就不存在于遥测中。`DISABLED` 不会构造 SDK 流水线，也不会将任何捕获内容交给后端。
 
 ## 字段映射
 
-seam 记录 → SDK 日志记录：`time` → `timestamp`/`observedTimestamp`；`severity` → `severityNumber`/`severityText`（INFO 9 / WARN 13 / ERROR 17）；`body` → 结构化日志 body；`attributes` 原样照搬。接收端基于 `(session.id, event.seq)` 去重、按严重级别告警，并通过 `shutdown` 记录的缺失检测崩溃（一个曾有活动、没有 `shutdown` 运维记录、且已然陈旧的会话，就是未干净结束的会话）。该标记的含义是遥测干净地停止了对该会话的观察：它在会话自身 dispose（资源释放）时发出，对于届时仍在运行的会话，则在应用关闭时发出；标记之后又出现该会话的更多事件，说明发生的是遥测重载，而不是会话重启。跨谱系（lineage）的流并不自足：恢复的会话在其自身 id 的流上从上一个进程停止之处继续；fork 出的会话，其流从继承边界开始，前缀位于父会话的流中，由接收端基于 `session.parent_id` + `session.seed_length` 拼接。继续而非回放的一个后果：流中一个开启后再未关闭的轮次，标志着上一个进程死在了该轮次之内。恢复时本地日志会以合成的关闭事件修复，但这些修复绝不导出：导出的流忠实于崩溃进程实际发出的内容，其后干净的 `shutdown` 标记也只证明恢复后进程自身的退出。
+seam 记录 → SDK 日志记录：`time` → `timestamp`/`observedTimestamp`；`severity` → `severityNumber`/`severityText`（INFO 9 / WARN 13 / ERROR 17）；`body` → 结构化日志 body；`attributes` 原样照搬。接收端基于 `(session.id, event.seq)` 去重，并按严重级别告警。在 `FULL` 中，接收端还可通过缺少 `shutdown` 记录检测崩溃：该标记在会话自身 dispose（资源释放）或应用关闭时发出；标记之后出现更多事件，说明遥测发生了重载。在 `FEEDBACK_ONLY` 中，已释放的前缀通常不包含随后的 `shutdown` 标记，因此缺少该标记不是崩溃信号。跨谱系（lineage）的流并不自足：恢复的会话在其自身 id 的流上从上一个进程停止之处继续；fork 出的会话的流从继承边界开始，其前缀位于父会话的流中，由接收端基于 `session.parent_id` + `session.seed_length` 拼接。恢复后的本地日志可能包含从未导出的合成关闭事件；协议流忠实于实际交给 SDK 的记录。
 
 ## 模型体验
 
@@ -39,3 +46,4 @@ seam 记录 → SDK 日志记录：`time` → `timestamp`/`observedTimestamp`；
 
 - **上游实验性源码树**：`@opentelemetry/sdk-logs` 仍从上游实验性（experimental）源码树发布；SDK API 的变动只会落在本包，也仅落在本包；seam 契约不动。
 - **无真实 collector 覆盖**：所有测试都导出到本地 mock collector；无密钥的 Loader 组合 e2e（`tests/loader-composition.e2e.ts`）在每次运行中都覆盖协议格式（wire format）形态，而面对真实 OTLP 部署的行为（认证、TLS、限流）属于 SDK 导出器文档的职责范围。
+- **仅反馈模式的内存占用**：每个会话都会在内存中保留已深拷贝、已脱敏的投影记录，直到反馈将其释放或会话变得不可达。反馈前不存在持久化 spool；如果在反馈前崩溃，则什么都不上传。
diff --git a/packages/telemetry/session-telemetry-otel/package.json b/packages/telemetry/session-telemetry-otel/package.json
index 7be8c04ce4..4037cfe28a 100644
--- a/packages/telemetry/session-telemetry-otel/package.json
+++ b/packages/telemetry/session-telemetry-otel/package.json
@@ -36,6 +36,7 @@
     "schemastery": "^3.18.0"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-command-feedback": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
@@ -44,6 +45,7 @@
   },
   "devDependencies": {
     "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-command-feedback": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/telemetry/session-telemetry-otel/src/index.ts b/packages/telemetry/session-telemetry-otel/src/index.ts
index 85dd75f275..cb0ee71fc7 100644
--- a/packages/telemetry/session-telemetry-otel/src/index.ts
+++ b/packages/telemetry/session-telemetry-otel/src/index.ts
@@ -6,8 +6,8 @@
  * record handed over by the seam onto `logger.emit()`. Per the seam's
  * boundary axiom, everything downstream of that call (batching, retry,
  * queueing, loss policy) is the SDK's documented behavior, configured
- * verbatim through the `exporter`/`processor` passthroughs; this package
- * adds no knobs of its own on top of them.
+ * verbatim through the `exporter`/`processor` passthroughs. This package owns
+ * only whether capture is immediate, feedback-released, or disabled.
  *
  * @module @deepseek-ai/dsh-session-telemetry-otel
  */
@@ -15,7 +15,14 @@
 import { createRequire } from 'node:module'
 import z from 'schemastery'
 import type { Context } from 'cordis'
-import { Telemetry, TelemetryCoordinator, type TelemetryRecord, type TelemetrySeverity } from '@deepseek-ai/dsh-session-telemetry'
+import type {} from '@deepseek-ai/dsh-command-feedback'
+import {
+  Telemetry,
+  TelemetryCoordinator,
+  type TelemetryDelivery,
+  type TelemetryRecord,
+  type TelemetrySeverity,
+} from '@deepseek-ai/dsh-session-telemetry'
 import { APP_IDENTITY } from '@deepseek-ai/dsh-llm'
 import {
   BatchLogRecordProcessor,
@@ -31,13 +38,22 @@ import { resourceFromAttributes } from '@opentelemetry/resources'
 // version (same pattern as dsh-llm's attribution identity).
 const { version } = createRequire(import.meta.url)('../package.json') as { version: string }
 
+/** Supported session-sharing policies for the OTel backend. */
+export const TELEMETRY_MODES = ['FULL', 'FEEDBACK_ONLY', 'DISABLED'] as const
+
+/** Session-sharing policy selected by {@link Config.mode}. */
+export type TelemetryMode = typeof TELEMETRY_MODES[number]
+
+const DISABLED_FEEDBACK_WARNING = 'session telemetry is DISABLED; nothing will be shared and this feedback remains local'
+
 /**
- * Plugin configuration: two verbatim SDK option shapes plus nothing else.
- * `exporter.url` is the one field this package validates itself — required,
- * no default, must parse as an `http(s)` URL — because a missing endpoint
- * must fail at plugin load, not at first export.
+ * Plugin configuration: one sharing policy plus two verbatim SDK option
+ * shapes. `exporter.url` is required for modes that upload and unused for
+ * `DISABLED`.
  */
 export interface Config {
+  /** Sharing policy; defaults to immediate `FULL` delivery. */
+  mode?: TelemetryMode
   /**
    * Passed verbatim to the SDK's OTLP/HTTP log exporter — the complete
    * `OTLPExporterNodeConfigBase` shape (`headers`, `timeoutMillis`,
@@ -45,7 +61,7 @@ export interface Config {
    * is the one field this package requires and validates itself.
    */
   exporter?: OTLPExporterNodeConfigBase & {
-    /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required; validated at plugin load. */
+    /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required outside `DISABLED`; validated at load. */
     url?: string
   }
   /**
@@ -57,13 +73,14 @@ export interface Config {
 
 /**
  * Schemastery validator for {@link Config}; cordis runs it before the plugin
- * starts. Shape-level only — the load-bearing `exporter.url` check lives in
- * the constructor so its error message names the field. Both slots are opaque
- * passthroughs: the SDK owns their shapes and validates its own options;
- * re-declaring them field-by-field here would violate the boundary axiom
- * (and silently drop every field not re-declared).
+ * starts. Shape-level only — the mode-dependent `exporter.url` check lives in
+ * the constructor so its error message names the field. Both SDK slots are
+ * opaque passthroughs: the SDK owns their shapes and validates its own
+ * options; re-declaring them field-by-field here would violate the boundary
+ * axiom (and silently drop every field not re-declared).
  */
 export const Config: z<Config> = z.object({
+  mode: z.union(TELEMETRY_MODES).default('FULL'),
   exporter: z.any(),
   processor: z.any(),
 })
@@ -76,22 +93,32 @@ const SEVERITY: Record<TelemetrySeverity, { severityNumber: SeverityNumber; seve
 }
 
 /**
- * The backend plugin — the only entry a deployment loads. Constructing it
- * wires the SDK pipeline, registers the `telemetry` service (duplicate load
- * throws, cordis' standard duplicate-service behavior), and composes the
- * seam's {@link TelemetryCoordinator}, which installs the capture side onto
- * this fiber.
+ * The backend plugin — the only entry a deployment loads. It always registers
+ * the `telemetry` service (duplicate load throws). Uploading modes wire the SDK
+ * pipeline and compose {@link TelemetryCoordinator}; `DISABLED` constructs no
+ * SDK state and listens only to warn when recorded feedback stays local.
  */
 export class TelemetryOtel extends Telemetry {
   static inject = ['sessions']
   static Config = Config
 
-  private readonly provider: LoggerProvider
-  private readonly ledger: Logger
-  private readonly ops: Logger
+  private readonly provider: LoggerProvider | undefined
+  private readonly ledger: Logger | undefined
+  private readonly ops: Logger | undefined
 
   constructor(ctx: Context, config: Config) {
     super(ctx)
+    const mode = config.mode ?? 'FULL'
+    if (mode === 'DISABLED') {
+      this.provider = undefined
+      this.ledger = undefined
+      this.ops = undefined
+      ctx.on('session/event', (_session, event) => {
+        if (event.type === 'feedback/record') ctx.logger.warn(DISABLED_FEEDBACK_WARNING)
+      })
+      return
+    }
+
     const url = config.exporter?.url
     if (url === undefined || url.length === 0) {
       throw new Error('session-telemetry-otel: exporter.url is required (the full OTLP logs endpoint)')
@@ -134,16 +161,26 @@ export class TelemetryOtel extends Telemetry {
     })
     this.ledger = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel', version)
     this.ops = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel/ops', version)
-    new TelemetryCoordinator(ctx, this)
+    const delivery: TelemetryDelivery = mode === 'FULL' ? 'immediate' : 'held'
+    const coordinator = new TelemetryCoordinator(ctx, this, delivery)
+    if (mode === 'FEEDBACK_ONLY') {
+      // The coordinator listener is registered first, so a feedback event
+      // enters the held prefix before this listener releases that exact prefix.
+      ctx.on('session/event', (session, event) => {
+        if (event.type === 'feedback/record') coordinator.release(session)
+      })
+    }
   }
 
   /**
    * Map one seam record onto the SDK logger for its channel — a synchronous
-   * enqueue into the batch processor's queue.
+   * enqueue into the batch processor's queue. Direct calls are no-ops in
+   * `DISABLED`, where no coordinator or SDK pipeline exists.
    * @param record - the logical record handed over by the coordinator.
    */
   emit(record: TelemetryRecord): void {
     const logger = record.channel === 'ops' ? this.ops : this.ledger
+    if (logger === undefined) return
     logger.emit({
       timestamp: record.time,
       observedTimestamp: record.time,
@@ -167,14 +204,15 @@ export class TelemetryOtel extends Telemetry {
   /**
    * Delegate disposal to the SDK's shutdown contract: drain the queue and
    * quiesce. With no concurrent `forceFlush()` in the process (see above),
-   * shutdown's internal drain is complete — everything emitted before this
-   * call, including the coordinator's dispose-time `shutdown` markers, is
-   * exported before the exporter closes. Awaited (and error-contained) by
-   * the coordinator's disposer.
+   * shutdown's internal drain is complete — everything handed to the SDK
+   * before this call is exported before the exporter closes. In `FULL`, that
+   * includes dispose-time `shutdown` markers; held suffixes never reach the
+   * SDK. Awaited (and error-contained) by the coordinator's disposer. A
+   * disabled backend resolves immediately.
    * @returns resolves when the SDK pipeline has quiesced.
    */
   shutdown(): Promise<void> {
-    return this.provider.shutdown()
+    return this.provider === undefined ? Promise.resolve() : this.provider.shutdown()
   }
 }
 
diff --git a/packages/telemetry/session-telemetry-otel/src/invariant.ts b/packages/telemetry/session-telemetry-otel/src/invariant.ts
index 075e5cc193..030b7ce670 100644
--- a/packages/telemetry/session-telemetry-otel/src/invariant.ts
+++ b/packages/telemetry/session-telemetry-otel/src/invariant.ts
@@ -15,10 +15,9 @@ export const name = 'session-telemetry-otel-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: the backend forwards seam records into the OTel SDK's
- * in-process pipeline and appends nothing to any session; its only observable
- * effects (batching, export) happen inside the SDK past the seam's boundary
- * axiom, out of reach of an independent companion.
+ * No runtime invariant: mode selection changes capture handoff, SDK setup, and
+ * local diagnostics without mutating session or service state an independent
+ * companion can compare. Export remains inside the SDK past the seam boundary.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/telemetry/session-telemetry-otel/tests/loader-composition.e2e.ts b/packages/telemetry/session-telemetry-otel/tests/loader-composition.e2e.ts
index 8f16662614..e07e05fed9 100644
--- a/packages/telemetry/session-telemetry-otel/tests/loader-composition.e2e.ts
+++ b/packages/telemetry/session-telemetry-otel/tests/loader-composition.e2e.ts
@@ -40,6 +40,11 @@ interface OtlpCapture {
   }[]
 }
 
+interface FixtureOutput {
+  captures: OtlpCapture[]
+  logContent: string
+}
+
 async function jsonlFiles(dir: string): Promise<string[]> {
   const entries = await readdir(dir, { withFileTypes: true })
   const paths = await Promise.all(entries.map(async (entry) => {
@@ -50,10 +55,29 @@ async function jsonlFiles(dir: string): Promise<string[]> {
   return paths.flat()
 }
 
+async function readFixtureOutput(cwd: string): Promise<FixtureOutput> {
+  const captures = JSON.parse(await readFile(join(cwd, 'otlp-captures.json'), 'utf8')) as OtlpCapture[]
+  const logs = await jsonlFiles(join(cwd, '.sessions'))
+  expect(logs).toHaveLength(1)
+  return { captures, logContent: await readFile(logs[0] as string, 'utf8') }
+}
+
+function allRecords(captures: OtlpCapture[]) {
+  return captures.flatMap(capture => capture.resourceLogs.flatMap(resource =>
+    resource.scopeLogs.flatMap(scoped => scoped.logRecords.map(record => ({ scope: scoped.scope.name, record })))))
+}
+
+function eventTypes(captures: OtlpCapture[]): string[] {
+  return allRecords(captures).flatMap(({ record }) =>
+    record.attributes?.flatMap(attribute =>
+      attribute.key === 'event.type' && typeof attribute.value['stringValue'] === 'string'
+        ? [attribute.value['stringValue']]
+        : []) ?? [])
+}
+
 describe('session-telemetry-otel through a real headless cordis.yml', () => {
   it('exports redacted ledger records to the collector while the canonical log keeps the secret', async () => {
-    let captures: OtlpCapture[] = []
-    let logContent = ''
+    let output!: FixtureOutput
     const { stderr } = await runLoaderSmoke({
       label: 'session-telemetry-otel loader smoke',
       tempDirPrefix: 'telemetry-otel-e2e-',
@@ -61,39 +85,70 @@ describe('session-telemetry-otel through a real headless cordis.yml', () => {
       libBinScript: driver,
       configPath,
       tsconfigPath: repoTsconfig,
-      inspect: async (cwd) => {
-        captures = JSON.parse(await readFile(join(cwd, 'otlp-captures.json'), 'utf8')) as OtlpCapture[]
-        const logs = await jsonlFiles(join(cwd, '.sessions'))
-        expect(logs).toHaveLength(1)
-        logContent = await readFile(logs[0] as string, 'utf8')
-      },
+      inspect: async (cwd) => { output = await readFixtureOutput(cwd) },
     })
     expect(stderr).not.toContain('UNHANDLED')
 
-    const records = captures.flatMap(capture => capture.resourceLogs.flatMap(resource =>
-      resource.scopeLogs.flatMap(scoped => scoped.logRecords.map(record => ({ scope: scoped.scope.name, record })))))
+    const records = allRecords(output.captures)
     expect(records.length).toBeGreaterThan(0)
 
-    const eventTypes = records.flatMap(({ record }) =>
-      record.attributes?.flatMap(attribute =>
-        attribute.key === 'event.type' && typeof attribute.value['stringValue'] === 'string'
-          ? [attribute.value['stringValue']]
-          : []) ?? [])
+    const types = eventTypes(output.captures)
     for (const expected of ['turn/start', 'user/message', 'tool/call', 'tool/result', 'assistant/message', 'turn/end']) {
-      expect(eventTypes, expected).toContain(expected)
+      expect(types, expected).toContain(expected)
     }
     expect(records.some(({ scope }) => scope.endsWith('/ops'))).toBe(true)
 
     // The deployment-mounted rule on the wire: the fixture credential never
     // leaves the process, its surrounding prose does, and the placeholder
     // marks the spot — the seam itself ships no rules.
-    const wire = JSON.stringify(captures)
+    const wire = JSON.stringify(output.captures)
     expect(wire).not.toContain(FIXTURE_SECRET)
     expect(wire).toContain(FIXTURE_PLACEHOLDER)
     expect(wire).toContain('prove telemetry with key')
 
     // The canonical session log is never rewritten.
-    expect(logContent).toContain(FIXTURE_SECRET)
-    expect(logContent).not.toContain(FIXTURE_PLACEHOLDER)
+    expect(output.logContent).toContain(FIXTURE_SECRET)
+    expect(output.logContent).not.toContain(FIXTURE_PLACEHOLDER)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
+  it('exports only prefixes ending in feedback under feedback-only mode', async () => {
+    let output!: FixtureOutput
+    const { stderr } = await runLoaderSmoke({
+      label: 'session-telemetry-otel feedback-only loader smoke',
+      tempDirPrefix: 'telemetry-otel-feedback-e2e-',
+      binScript: driver,
+      libBinScript: driver,
+      configPath,
+      tsconfigPath: repoTsconfig,
+      env: { DSH_TELEMETRY_E2E_MODE: 'FEEDBACK_ONLY' },
+      inspect: async (cwd) => { output = await readFixtureOutput(cwd) },
+    })
+    expect(stderr).not.toContain('UNHANDLED')
+
+    const wire = JSON.stringify(output.captures)
+    expect(eventTypes(output.captures)).toContain('feedback/record')
+    expect(wire).toContain('fixture feedback')
+    expect(wire).toContain('prove telemetry with key')
+    expect(wire).not.toContain('post-feedback private suffix')
+    expect(output.logContent).toContain('post-feedback private suffix')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
+  it('keeps disabled feedback local and prints the stable warning', async () => {
+    let output!: FixtureOutput
+    const { stdout } = await runLoaderSmoke({
+      label: 'session-telemetry-otel disabled loader smoke',
+      tempDirPrefix: 'telemetry-otel-disabled-e2e-',
+      binScript: driver,
+      libBinScript: driver,
+      configPath,
+      tsconfigPath: repoTsconfig,
+      env: { DSH_TELEMETRY_E2E_MODE: 'DISABLED' },
+      inspect: async (cwd) => { output = await readFixtureOutput(cwd) },
+    })
+
+    expect(output.captures).toEqual([])
+    expect(output.logContent).toContain('fixture feedback')
+    expect(stdout.match(/session telemetry is DISABLED; nothing will be shared and this feedback remains local/)?.[0])
+      .toMatchInlineSnapshot('"session telemetry is DISABLED; nothing will be shared and this feedback remains local"')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })
diff --git a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
index cccb90ed43..18c466f7aa 100644
--- a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
+++ b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
@@ -5,12 +5,13 @@
  * for the default-exported Service class.
  */
 
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createServer, type Server } from 'node:http'
 import { once } from 'node:events'
 import { gunzipSync } from 'node:zlib'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
+import { recordFeedback } from '@deepseek-ai/dsh-command-feedback'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import TelemetryOtel, { Config } from '../src/index.ts'
 
@@ -30,6 +31,7 @@ interface OtlpLogsRequest {
         severityNumber: number
         severityText: string
         attributes?: { key: string; value: Record<string, unknown> }[]
+        body?: unknown
       }[]
     }[]
   }[]
@@ -88,6 +90,14 @@ function allRecords(captures: Capture[]) {
     s.logRecords.map(record => ({ scope: s.scope.name, record })))))
 }
 
+function eventTypes(captures: Capture[]): string[] {
+  return allRecords(captures).flatMap(({ record }) =>
+    record.attributes?.flatMap(attribute =>
+      attribute.key === 'event.type' && typeof attribute.value['stringValue'] === 'string'
+        ? [attribute.value['stringValue']]
+        : []) ?? [])
+}
+
 describe('TelemetryOtel wire', () => {
   it('ships session records and the ops shutdown marker through the real SDK pipeline', async () => {
     const { url, captures } = await mockCollector()
@@ -195,6 +205,82 @@ describe('TelemetryOtel wire', () => {
       r.record.attributes?.some(a => a.key === 'event.type' && a.value.stringValue === 'turn/start'))
     expect(start?.record.severityNumber).toBe(13)
   })
+
+  it('holds each session suffix until the next feedback event', async () => {
+    const { url, captures } = await mockCollector()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(TelemetryOtel, {
+      mode: 'FEEDBACK_ONLY',
+      exporter: { url },
+    })
+    const session = ctx.sessions.create(SessionId('feedback-only'), { meta: {} })
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    recordFeedback(session, 'first report')
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    recordFeedback(session, 'second report')
+    session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
+    await fiber.dispose()
+
+    const types = allRecords(captures).flatMap(({ record }) =>
+      record.attributes?.flatMap(attribute =>
+        attribute.key === 'event.type' ? [attribute.value.stringValue] : []) ?? [])
+    expect(types).toEqual(['turn/start', 'feedback/record', 'turn/end', 'feedback/record'])
+    expect(JSON.stringify(captures)).toContain('first report')
+    expect(JSON.stringify(captures)).toContain('second report')
+    expect(allRecords(captures).some(({ scope }) => scope.endsWith('/ops'))).toBe(false)
+  })
+
+  it('sends no request when feedback-only mode ends without feedback', async () => {
+    const { url, captures } = await mockCollector()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(TelemetryOtel, {
+      mode: 'FEEDBACK_ONLY',
+      exporter: { url },
+    })
+    const session = ctx.sessions.create(SessionId('no-feedback'), { meta: {} })
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    await fiber.dispose()
+    expect(captures).toEqual([])
+  })
+
+  it('boots disabled without exporter config and warns when feedback stays local', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const fiber = await ctx.plugin(TelemetryOtel, { mode: 'DISABLED' })
+    const session = ctx.sessions.create(SessionId('disabled'), { meta: {} })
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    recordFeedback(session, 'local report')
+
+    expect(warn).toHaveBeenCalledWith(
+      'session telemetry is DISABLED; nothing will be shared and this feedback remains local',
+    )
+    ctx.telemetry.emit({
+      channel: 'ledger',
+      time: 0,
+      severity: 'info',
+      attributes: {},
+      body: null,
+    })
+    await ctx.telemetry.shutdown()
+    await fiber.dispose()
+    recordFeedback(session, 'after disposal')
+    expect(warn).toHaveBeenCalledTimes(1)
+  })
+
+  it('defaults direct construction to full delivery', async () => {
+    const { url, captures } = await mockCollector()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    new TelemetryOtel(ctx, { exporter: { url } })
+    const session = ctx.sessions.create(SessionId('direct-default'), { meta: {} })
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    await ctx.fiber.dispose()
+
+    expect(eventTypes(captures)).toContain('turn/start')
+  })
 })
 
 describe('TelemetryOtel config fails loud', () => {
@@ -203,6 +289,8 @@ describe('TelemetryOtel config fails loud', () => {
     [{ exporter: { url: '' } }, /exporter\.url is required/],
     [{ exporter: { url: 'not a url' } }, /not a valid URL/],
     [{ exporter: { url: 'ftp://collector' } }, /must be http\(s\)/],
+    [{ mode: 'FEEDBACK_ONLY' }, /exporter\.url is required/],
+    [{ mode: 'INVALID' }, /INVALID/],
     // The SDK accepts a non-positive batch size but its shutdown drain then
     // splices empty batches forever — dispose would hang, so reject at load.
     [{ exporter: { url: 'http://c/v1/logs' }, processor: { maxExportBatchSize: 0 } }, /maxExportBatchSize/],
diff --git a/packages/telemetry/session-telemetry-otel/tsconfig.json b/packages/telemetry/session-telemetry-otel/tsconfig.json
index 9512133cf7..4ba93f9eb1 100644
--- a/packages/telemetry/session-telemetry-otel/tsconfig.json
+++ b/packages/telemetry/session-telemetry-otel/tsconfig.json
@@ -20,6 +20,9 @@
     {
       "path": "../../core/session"
     },
+    {
+      "path": "../../feedback/command-feedback"
+    },
     {
       "path": "../../llm/llm"
     },
diff --git a/packages/telemetry/session-telemetry/README.i18n.yaml b/packages/telemetry/session-telemetry/README.i18n.yaml
index 18f6751424..da3a62e2fd 100644
--- a/packages/telemetry/session-telemetry/README.i18n.yaml
+++ b/packages/telemetry/session-telemetry/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/telemetry/session-telemetry/README.md
-README.md: 272c9abe78849be3d2bba2c54cd7e25bcbe2d4c2
-README.zh.md: e6f077c1d12d00e746147908560d05381fde11c3
+README.md: d38433a728c699c7fb3cc0512bb6a2d977dd4cc6
+README.zh.md: 3a86b01321fc7dfd33d39530ee7fa38a6ee1f2dc
diff --git a/packages/telemetry/session-telemetry/README.md b/packages/telemetry/session-telemetry/README.md
index 272c9abe78..d38433a728 100644
--- a/packages/telemetry/session-telemetry/README.md
+++ b/packages/telemetry/session-telemetry/README.md
@@ -2,23 +2,23 @@
 
 English | [中文](README.zh.md)
 
-The telemetry seam: the CAPTURE side of session-event reporting, behind a backend contract any reporting SDK satisfies with zero bending. The boundary axiom that shapes everything here: **this package's aspect ends at `emit()`** — batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md).
+The telemetry seam: the capture side of session-event reporting, behind a backend contract any reporting SDK satisfies with zero bending. Capture can hand each redacted record over immediately or hold a per-session prefix for an explicit release. The boundary axiom that shapes everything here: **this package's aspect ends at `emit()`** — batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md) and [feedback-gated delivery](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md).
 
 ## The backend contract
 
-`TelemetryBackend` is three members: `emit(record)` (MUST be a non-blocking enqueue — it runs synchronously on the `session/event` hot path), optional `flush()` (a turn-boundary hint, fire-and-forget; most backends leave it unimplemented and let their SDK's batching cadence govern export timing — an implementer owns the interaction between concurrent flushes and `shutdown()`'s drain), and `shutdown()` (the lifecycle forward: drain-and-quiesce, awaited at dispose). `Telemetry` is its service-registered form under the `telemetry` context key — one implementation per context, duplicate load throws. A backend composes `TelemetryCoordinator` in its constructor.
+`TelemetryBackend` is three members: `emit(record)` (MUST be a non-blocking enqueue — it runs synchronously on the `session/event` hot path, either at capture or held-prefix release), optional `flush()` (a turn-boundary hint, fire-and-forget; most backends leave it unimplemented and let their SDK's batching cadence govern export timing — an implementer owns the interaction between concurrent flushes and `shutdown()`'s drain), and `shutdown()` (the lifecycle forward: drain-and-quiesce, awaited at dispose). `Telemetry` is its service-registered form under the `telemetry` context key — one implementation per context, duplicate load throws. A backend composes `TelemetryCoordinator` with `immediate` delivery or `held` delivery and calls `release(session)` at its owning trigger.
 
 ## Capture points
 
-The coordinator registers, all through the composing fiber's effects: `session/created` (adopt: record the header, read the log back through the projection from the construction boundary — constructor seeds from fork/resume never re-emit on the firehose and never re-export), `session/event` (project, deep-copy, redact, hand off; zero I/O), `session/flush` (forward the optional `flush()` hint and return void — the loop's awaited parallel must never wait on telemetry), `session/disposed` (emit the session's `shutdown` operational record at its own termination edge — where receivers key crash detection — then retire it, so a long-lived backend neither retains closed sessions nor re-marks them at unload), `agent/error` (the one live-bus relay; the session event vocabulary intentionally has no operational-error record), a dispose effect (mark each session still alive at teardown, then await the backend's `shutdown()`; failures warn instead of throwing), and an adoption sweep of `ctx.sessions.list()` (a hot reload does not replay `session/created`).
+The coordinator registers, all through the composing fiber's effects: `session/created` (adopt: record the header, read the log back through the projection from the construction boundary — constructor seeds from fork/resume never re-emit on the firehose and never re-export), `session/event` (project, deep-copy, redact, then hand off or hold; zero I/O), `session/flush` (forward the optional `flush()` hint and return void — the loop's awaited parallel must never wait on telemetry), `session/disposed` (capture the session's `shutdown` operational record at its termination edge, then retire it), `agent/error` (the one live-bus relay; the session event vocabulary intentionally has no operational-error record), a dispose effect (capture shutdown for each still-live session, then await the backend's `shutdown()`; failures warn instead of throwing), and an adoption sweep of `ctx.sessions.list()` (a hot reload does not replay `session/created`). Immediate delivery hands lifecycle records over; held delivery leaves any suffix after the last release local, including its later shutdown marker.
 
 ## The redact waterfall
 
-Every record passes the `telemetry/record` waterfall between projection and `emit()` — the seam's scrubbing extension point. The seam ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+Every record passes the `telemetry/record` waterfall immediately after projection — the seam's scrubbing extension point. The seam ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Held delivery stores only the waterfall result, so later policy removal cannot expose the original capture. Redaction applies to the outbound copy only; the canonical session log is never rewritten.
 
 ## The handoff cursor
 
-A module-scope `WeakMap<Session, seq>` marks the highest seq HANDED OFF (not delivered) per session, advanced at emit time. It survives reloads that do not re-evaluate this module — config re-applies and backend source reloads, which is where iteration happens; that asymmetry is why the cursor lives in the seam. On re-adoption the coordinator re-hands only events past the cursor (events at or below it still rebuild the chunk-projection state); a missing cursor safely degrades to a re-hand from the session's construction boundary (`Session.firstLiveSeq` — seq 0 for a session born in this process), absorbed by receiver-side dedupe on `(session.id, event.seq)`. Constructor seeds never re-export: a resumed session's history shipped from the previous process under the same id, and a fork's inherited prefix lives in the parent's stream (receivers stitch on `session.parent_id` + `session.seed_length`). The accepted cost, consistent with at-most-once delivery: a resume does not backfill records a previous process failed to deliver — a deployment with a backfill requirement needs the deferred outbox, not replay. This is a deliberate, narrow exception to the registrations-are-effects discipline: entries die with their sessions, the value is a monotonic watermark, and losing it is never an error.
+A module-scope `WeakMap<Session, seq>` marks the highest seq HANDED OFF (not delivered) per session. Immediate delivery advances it at capture; held delivery advances it only when `release(session)` hands that record to the backend. An unreleased prefix therefore survives a coordinator reload through deterministic re-adoption instead of disappearing with its in-memory copy. On re-adoption the coordinator re-hands only events past the cursor (events at or below it still rebuild the chunk-projection state); a missing cursor safely degrades to a re-hand from the session's construction boundary (`Session.firstLiveSeq` — seq 0 for a session born in this process), absorbed by receiver-side dedupe on `(session.id, event.seq)`. Constructor seeds never re-export: a resumed session's history shipped from the previous process under the same id, and a fork's inherited prefix lives in the parent's stream (receivers stitch on `session.parent_id` + `session.seed_length`). The accepted cost, consistent with at-most-once delivery: a resume does not backfill records a previous process failed to deliver — a deployment with a backfill requirement needs the deferred outbox, not replay. This is a deliberate, narrow exception to the registrations-are-effects discipline: entries die with their sessions, the value is a monotonic watermark, and losing it is never an error.
 
 ## The fixed chunk projection
 
@@ -40,3 +40,4 @@ None; this package neither assembles nor sends a provider request.
 
 - **Best-effort delivery** — the cursor marks handed-off, not delivered; a session torn down inside a reload window cannot be re-adopted; whatever sits in a backend queue at crash time is lost. A durable outbox (spool, per-sink cursors, at-least-once) is deferred until a deployment states a crash-loss requirement — see [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md).
 - **No built-in redaction rules** — with no `telemetry/record` listener mounted, records leave the process exactly as captured, including any credentials embedded in file contents or command output; a deployment exporting to a shared collector owns its rule set.
+- **Held prefixes duplicate memory** — held delivery retains one deep-copied, redacted record per projected event until release or session collection. It adds no durable outbox and intentionally trades memory for a simple no-upload-before-trigger boundary.
diff --git a/packages/telemetry/session-telemetry/README.zh.md b/packages/telemetry/session-telemetry/README.zh.md
index e6f077c1d1..3a86b01321 100644
--- a/packages/telemetry/session-telemetry/README.zh.md
+++ b/packages/telemetry/session-telemetry/README.zh.md
@@ -2,23 +2,23 @@
 
 [English](README.md) | 中文
 
-遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端契约之后，任何上报 SDK 都无需变形即可满足该契约。塑造本包（package）一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)。
+遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端契约之后，任何上报 SDK 都无需变形即可满足该契约。捕获侧可立即交接每条已脱敏记录，也可按会话暂存一个前缀，等待显式释放。塑造本包（package）一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)与[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)。
 
 ## 后端契约
 
-`TelemetryBackend` 只有三个成员：`emit(record)`（必须是非阻塞入队；它在 `session/event` 热路径上同步执行）、可选的 `flush()`（轮次边界提示，触发后不等待结果；多数后端不实现它，而由其 SDK 的批处理节奏决定导出时机；并发 flush 与 `shutdown()` 的排空之间的交互由实现方自行负责）、以及 `shutdown()`（生命周期转发点：排空并完全停稳，在 dispose（资源释放）时被等待）。`Telemetry` 是它注册在 `telemetry` 上下文键下的服务形态：每个上下文只允许一个实现，重复加载会抛出异常。后端在其构造函数中组合 `TelemetryCoordinator`。
+`TelemetryBackend` 只有三个成员：`emit(record)`（必须是非阻塞入队；它会在捕获或暂存前缀释放时，于 `session/event` 热路径上同步执行）、可选的 `flush()`（轮次边界提示，触发后不等待结果；多数后端不实现它，而由其 SDK 的批处理节奏决定导出时机；并发 flush 与 `shutdown()` 的排空之间的交互由实现方自行负责）、以及 `shutdown()`（生命周期转发点：排空并完全停稳，在 dispose（资源释放）时被等待）。`Telemetry` 是它注册在 `telemetry` 上下文键下的服务形态：每个上下文只允许一个实现，重复加载会抛出异常。后端以 `immediate` 或 `held` 投递模式组合 `TelemetryCoordinator`，并在自身所属的触发器中调用 `release(session)`。
 
 ## 捕获点
 
-协调器的全部注册都经由组合方 fiber 的 effect 完成：`session/created`（收养：记录 header，并经投影从构造边界起回读日志；来自 fork 或恢复的构造函数种子绝不会在 firehose 上再次发出，也绝不会再次导出）、`session/event`（投影、深拷贝、脱敏、交接；零 I/O）、`session/flush`（转发可选的 `flush()` 提示并返回 void；循环所等待的并行任务绝不能等待遥测）、`session/disposed`（在会话自身的终止边缘发出该会话的 `shutdown` 运维记录，接收端正是在这个边缘锚定崩溃检测；随后将该会话退役，因此长生命周期的后端既不会保留已关闭的会话，也不会在卸载时再次标记它们）、`agent/error`（唯一的实时总线转发；会话事件词汇有意不包含运维错误记录）、一个 dispose effect（拆卸时先标记每个仍存活的会话，再等待后端的 `shutdown()`；失败只发出警告而不抛出），以及对 `ctx.sessions.list()` 的收养扫描（热重载不会重放 `session/created`）。
+协调器的全部注册都经由组合方 fiber 的 effect 完成：`session/created`（收养：记录 header，并经投影从构造边界起回读日志；来自 fork 或恢复的构造函数种子绝不会在 firehose 上再次发出，也绝不会再次导出）、`session/event`（投影、深拷贝、脱敏，再交接或暂存；零 I/O）、`session/flush`（转发可选的 `flush()` 提示并返回 void；循环所等待的并行任务绝不能等待遥测）、`session/disposed`（在会话自身的终止边缘捕获该会话的 `shutdown` 运维记录，然后将其退役）、`agent/error`（唯一的实时总线转发；会话事件词汇有意不包含运维错误记录）、一个 dispose effect（捕获每个仍存活会话的 shutdown，再等待后端的 `shutdown()`；失败只发出警告而不抛出），以及对 `ctx.sessions.list()` 的收养扫描（热重载不会重放 `session/created`）。即时投递会交接生命周期记录；暂存投递会将上次释放后的任何后缀留在本地，包括随后的 shutdown 标记。
 
 ## 脱敏 waterfall（瀑布式事件）
 
-每条记录在投影与 `emit()` 之间都要经过 `telemetry/record` waterfall，这是该 seam 的脱敏扩展点。seam 自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
+每条记录在投影后立即经过 `telemetry/record` waterfall，这是该 seam 的脱敏扩展点。seam 自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。暂存投递只保留 waterfall 的结果，因此后续移除策略也无法暴露捕获时的原始内容。脱敏只作用于外发副本；权威会话日志永不改写。
 
 ## handoff 游标
 
-一个模块作用域的 `WeakMap<Session, seq>` 记录每个会话已交接（而非已投递）的最高 seq，在 emit 时推进。游标在不重新求值本模块的重载（配置重新应用、后端源码重载）中存活，而迭代恰恰发生在这类重载中；这种不对称正是游标放在 seam 一侧的原因。重新收养时，协调器只重新交接游标之后的事件（游标及其之前的事件仍用于重建分片投影状态）；游标缺失时安全退化为从会话构造边界起的重新交接（`Session.firstLiveSeq`，对在本进程中诞生的会话即 seq 0），由接收端基于 `(session.id, event.seq)` 的去重吸收。构造函数种子绝不会再次导出：恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀则位于父会话的流中（接收端基于 `session.parent_id` + `session.seed_length` 拼接）。由此接受的代价与至多一次（at-most-once）投递一致：恢复不会回填上一个进程未能投递的记录；有回填要求的部署需要的是已推迟的 outbox，而不是回放。这是对「注册即 effect」纪律的一次有意且范围极窄的例外：条目随其会话消亡，值是单调水位线，丢失它绝不是错误。
+一个模块作用域的 `WeakMap<Session, seq>` 记录每个会话已交接（而非已投递）的最高 seq。即时投递在捕获时推进游标；暂存投递只有在 `release(session)` 将记录交给后端时才推进游标。因此，重建协调器后会通过确定性重新收养恢复未释放的前缀，而不会随其内存副本一同消失。重新收养时，协调器只重新交接游标之后的事件（游标及其之前的事件仍用于重建分片投影状态）；游标缺失时安全退化为从会话构造边界起的重新交接（`Session.firstLiveSeq`，对在本进程中诞生的会话即 seq 0），由接收端基于 `(session.id, event.seq)` 的去重吸收。构造函数种子绝不会再次导出：恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀则位于父会话的流中（接收端基于 `session.parent_id` + `session.seed_length` 拼接）。由此接受的代价与至多一次（at-most-once）投递一致：恢复不会回填上一个进程未能投递的记录；有回填要求的部署需要的是已推迟的 outbox，而不是回放。这是对「注册即 effect」纪律的一次有意且范围极窄的例外：条目随其会话消亡，值是单调水位线，丢失它绝不是错误。
 
 ## 固定分片投影
 
@@ -40,3 +40,4 @@
 
 - **尽力而为的投递**：游标标记的是已交接而非已投递；在重载窗口内被拆除的会话无法重新收养；崩溃时留在后端队列中的内容会丢失。持久化 outbox（spool、每 sink 游标、at-least-once）推迟到有部署方提出明确的崩溃丢失要求时再实现；见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)。
 - **不内置脱敏规则**：未挂载 `telemetry/record` 监听器时，记录以捕获时的原样离开进程，包括文件内容或命令输出中内嵌的任何凭据；向共享 collector 导出的部署方自行负责其规则集。
+- **暂存前缀会重复占用内存**：暂存投递会为每个已投影事件保留一份深拷贝且已脱敏的记录，直到释放或回收会话。它不增加持久化 outbox，而是有意以内存换取简单的「触发前不上传」边界。
diff --git a/packages/telemetry/session-telemetry/src/coordinator.ts b/packages/telemetry/session-telemetry/src/coordinator.ts
index 0bebbcc561..710e9b81f9 100644
--- a/packages/telemetry/session-telemetry/src/coordinator.ts
+++ b/packages/telemetry/session-telemetry/src/coordinator.ts
@@ -3,10 +3,11 @@
  * firehose plus the one live-bus relay (`agent/error`), applies the fixed
  * chunk projection, builds logical records, runs each through the
  * `telemetry/record` waterfall (deployment-mounted redaction rules;
- * pass-through when none), and hands the result to the backend — synchronously, with every
- * handler self-contained so a failing backend can never starve other
- * subscribers (cordis `emit` is stop-on-throw) or touch the agent loop.
- * Composed by a backend in its constructor.
+ * pass-through when none), then hands the result to the backend immediately
+ * or holds it for explicit release. Every synchronous handler is
+ * self-contained so a failing backend can never starve other subscribers
+ * (cordis `emit` is stop-on-throw) or touch the agent loop. Composed by a
+ * backend in its constructor.
  *
  * @module @deepseek-ai/dsh-session-telemetry/coordinator
  */
@@ -16,6 +17,16 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { TelemetryBackend, TelemetryRecord, TelemetrySeverity } from './index.ts'
 
+/** Whether capture hands records over immediately or holds them for an explicit release. */
+export type TelemetryDelivery = 'immediate' | 'held'
+
+/** One redacted record waiting at the capture boundary. */
+interface PendingRecord {
+  readonly record: TelemetryRecord
+  /** Ledger cursor advanced only after the backend accepts this record. */
+  readonly seq?: number
+}
+
 /**
  * The handoff cursor: per session, the highest `seq` handed to a backend.
  * Deliberately MODULE-scope ambient state — a narrow, documented exception
@@ -35,14 +46,13 @@ const handoffCursor = new WeakMap<Session, number>()
  * Registers the persistence-coordinator listener set plus the `agent/error`
  * relay, all through `ctx.effect()`/`ctx.on()` on the composing fiber, and
  * sweeps already-live sessions (a hot reload does not replay
- * `session/created`). A `session/disposed` emits the session's `shutdown`
- * operational record — the marker rides the session's own termination edge,
- * where receivers key crash detection — and retires it from the adopted set,
- * so a long-lived backend neither retains closed sessions (and their frozen
- * event logs) nor re-marks them at unload. Disposal marks the sessions still
- * alive at teardown (their own edge would fire unobserved) and then awaits
- * the backend's `shutdown()`; a failure there warns instead of throwing —
- * best-effort reporting must not fail application teardown.
+ * `session/created`). A `session/disposed` captures the session's `shutdown`
+ * operational record at its own termination edge and retires it from the
+ * adopted set. Immediate delivery hands that marker over; held delivery keeps
+ * it local without another explicit release. Disposal captures the same
+ * marker for sessions still alive, then awaits the backend's `shutdown()`; a
+ * failure there warns instead of throwing — best-effort reporting must not
+ * fail application teardown.
  */
 export class TelemetryCoordinator {
   /**
@@ -53,28 +63,30 @@ export class TelemetryCoordinator {
   private readonly adopted = new Set<Session>()
   /** Per session, the `turn:step` keys whose first chunk already shipped; rebuilt from the log on re-adoption. */
   private readonly chunkSeen = new WeakMap<Session, Set<string>>()
+  /** Redacted records retained until {@link release}; weak keys do not extend session lifetime. */
+  private readonly held = new WeakMap<Session, PendingRecord[]>()
 
   /**
    * @param ctx - the composing backend's context; listeners bind to its fiber.
    * @param backend - the backend receiving records; owned elsewhere, never disposed here beyond `shutdown()` forwarding.
+   * @param delivery - immediate handoff, or held delivery released explicitly per session.
    */
   constructor(
     private readonly ctx: Context,
     private readonly backend: TelemetryBackend,
+    private readonly delivery: TelemetryDelivery = 'immediate',
   ) {
     ctx.on('session/created', (session) => {
       this.adopt(session)
     })
-    // The session's own termination edge: emit the shutdown marker HERE —
-    // receivers classify a session with activity and no marker as crashed,
-    // so a normally closed session in a long-running host must get its
-    // marker at disposal, not never. Then retire: the projection/cursor
-    // WeakMaps die with the Session object; only the strong adopted set
-    // needs the explicit release.
+    // Capture the shutdown marker at the session's own termination edge.
+    // Immediate delivery preserves crash classification; held delivery does
+    // not let a later lifecycle edge extend a user-released prefix. Then
+    // retire the only strong reference owned by this coordinator.
     ctx.on('session/disposed', (session) => {
       this.contain(() => {
         if (!this.adopted.delete(session)) return
-        this.handOff(shutdownRecord(session))
+        this.submit(session, { record: this.redact(shutdownRecord(session)) })
       })
     })
     ctx.on('session/event', (session, event) => {
@@ -95,13 +107,12 @@ export class TelemetryCoordinator {
       })
     })
     ctx.effect(() => async () => {
-      // Sessions still adopted here are alive through a whole-application
-      // teardown (their own disposal edge will fire after telemetry is gone,
-      // unobserved) — mark them now so the receiver sees a clean stop of
-      // observation rather than a crash-shaped silence.
+      // Sessions still adopted here are alive through whole-application
+      // teardown, so capture the marker before the backend quiesces. Held
+      // delivery intentionally leaves it local without another release.
       for (const session of this.adopted) {
         this.contain(() => {
-          this.handOff(shutdownRecord(session))
+          this.submit(session, { record: this.redact(shutdownRecord(session)) })
         })
       }
       try {
@@ -115,6 +126,23 @@ export class TelemetryCoordinator {
     }
   }
 
+  /**
+   * Hand the records currently held for one session to the backend in capture order.
+   * Records captured after this call form a new held prefix. Backend failures remain
+   * contained per record and do not starve later records in the same release.
+   * @param session - session whose pending capture prefix may leave the process.
+   */
+  release(session: Session): void {
+    const pending = this.held.get(session)
+    if (pending === undefined) return
+    this.held.delete(session)
+    for (const record of pending) {
+      this.contain(() => {
+        this.deliver(session, record)
+      })
+    }
+  }
+
   /**
    * Adopt a session: replay its log THROUGH the projection from the handoff
    * cursor, then rely on the firehose for everything after. When no cursor
@@ -153,7 +181,7 @@ export class TelemetryCoordinator {
     }
   }
 
-  /** Project one event and hand it to the backend, advancing the cursor on handoff. */
+  /** Project and redact one event, then submit it under the delivery policy. */
   private capture(session: Session, event: SessionEvent): void {
     if (event.type === 'assistant/chunk') {
       const key = `${event.data.turn}:${event.data.step}`
@@ -165,27 +193,47 @@ export class TelemetryCoordinator {
       if (seen.has(key)) return
       seen.add(key)
     }
-    this.handOff({
-      channel: 'ledger',
-      time: event.time,
-      severity: severityOf(event),
-      attributes: identityOf(session, event),
-      // The live event object is mutable and the backend serializes later;
-      // append-time validation guarantees this clone cannot throw.
-      body: structuredClone(event.data),
+    this.submit(session, {
+      record: this.redact({
+        channel: 'ledger',
+        time: event.time,
+        severity: severityOf(event),
+        attributes: identityOf(session, event),
+        // The live event object is mutable and the backend serializes later;
+        // append-time validation guarantees this clone cannot throw.
+        body: structuredClone(event.data),
+      }),
+      seq: event.seq,
     })
-    handoffCursor.set(session, event.seq)
   }
 
   /**
-   * Run the `telemetry/record` waterfall over one record and hand the result
-   * to the backend. The innermost `next` passes the record through unchanged
-   * — the seam ships no rules; exported data is as clean as the listeners a
-   * deployment mounts. Callers run inside {@link contain}, so a throwing
-   * rule withholds the record instead of reaching the loop (fail-closed).
+   * Run the `telemetry/record` waterfall at capture time. The innermost `next`
+   * passes the record through unchanged — the seam ships no rules; exported
+   * data is as clean as the listeners a deployment mounts. Callers run inside
+   * {@link contain}, so a throwing rule withholds the record instead of
+   * reaching the loop (fail-closed). Held delivery stores only this result, so
+   * a later policy reload cannot expose the pre-redaction capture.
    */
-  private handOff(record: TelemetryRecord): void {
-    this.backend.emit(this.ctx.waterfall('telemetry/record', record, () => record))
+  private redact(record: TelemetryRecord): TelemetryRecord {
+    return this.ctx.waterfall('telemetry/record', record, () => record)
+  }
+
+  /** Hold one redacted record or deliver it immediately under the configured policy. */
+  private submit(session: Session, pending: PendingRecord): void {
+    if (this.delivery === 'held') {
+      let records = this.held.get(session)
+      if (records === undefined) this.held.set(session, records = [])
+      records.push(pending)
+      return
+    }
+    this.deliver(session, pending)
+  }
+
+  /** Hand one redacted record to the backend, then advance its ledger cursor. */
+  private deliver(session: Session, pending: PendingRecord): void {
+    this.backend.emit(pending.record)
+    if (pending.seq !== undefined) handoffCursor.set(session, pending.seq)
   }
 
   /** Forward the turn-end boundary to the backend's optional flush hint. */
@@ -196,19 +244,21 @@ export class TelemetryCoordinator {
   /** Relay one `agent/error` bus emission as an `agent-error` operational record. */
   private relayAgentError(agent: Agent, turn: number, step: number, error: unknown): void {
     const detail = errorDetail(error)
-    this.handOff({
-      channel: 'ops',
-      time: Date.now(),
-      severity: 'error',
-      attributes: {
-        'telemetry.op': 'agent-error',
-        'session.id': String(agent.session.id),
-        'agent.id': agent.id,
-        'error.name': detail.name,
-        turn,
-        step,
-      },
-      body: detail,
+    this.submit(agent.session, {
+      record: this.redact({
+        channel: 'ops',
+        time: Date.now(),
+        severity: 'error',
+        attributes: {
+          'telemetry.op': 'agent-error',
+          'session.id': String(agent.session.id),
+          'agent.id': agent.id,
+          'error.name': detail.name,
+          turn,
+          step,
+        },
+        body: detail,
+      }),
     })
   }
 
diff --git a/packages/telemetry/session-telemetry/src/index.ts b/packages/telemetry/session-telemetry/src/index.ts
index e7340eedd5..914ef96a95 100644
--- a/packages/telemetry/session-telemetry/src/index.ts
+++ b/packages/telemetry/session-telemetry/src/index.ts
@@ -3,8 +3,9 @@
  *
  * The seam owns the CAPTURE side of session-event reporting — which records
  * exist (the chunk projection), what they carry (the logical record), when
- * they are handed over (adoption, the per-append firehose, lifecycle
- * forwarding), and the HMR handoff cursor. Everything downstream of
+ * they are captured (adoption, the per-append firehose, lifecycle
+ * forwarding), immediate versus explicitly released handoff, and the HMR
+ * cursor. Everything downstream of
  * {@link Telemetry.emit} — batching, retry, queueing, loss policy — is the
  * reporting SDK's territory and is deliberately not modelled here. The
  * design and its trade-offs are pinned in
@@ -94,9 +95,10 @@ export interface TelemetryBackend {
   /**
    * Hand one record to the backend's pipeline. MUST be a non-blocking
    * enqueue — the coordinator calls this synchronously from the
-   * `session/event` hot path, so anything slower than a queue push would tax
-   * the agent loop. Errors thrown here are contained by the coordinator and
-   * logged; they never reach the loop.
+   * `session/event` hot path, either at capture or while releasing a held
+   * prefix, so anything slower than a queue push would tax the agent loop.
+   * Errors thrown here are contained by the coordinator and logged; they
+   * never reach the loop.
    * @param record - the logical record to report; owned by the backend after the call.
    */
   emit(record: TelemetryRecord): void
@@ -121,6 +123,9 @@ export interface TelemetryBackend {
    * coordinator emits its dispose-time `shutdown` markers immediately before
    * calling this). Awaited by the coordinator's dispose; a rejection is
    * logged as a warning and never fails application teardown.
+   * The coordinator captures dispose-time shutdown markers immediately
+   * before this call; immediate delivery enqueues them, while held delivery
+   * leaves an unreleased suffix local.
    * @returns resolves when the backend's pipeline has quiesced.
    */
   shutdown(): Promise<void>
@@ -153,4 +158,4 @@ export abstract class Telemetry extends Service implements TelemetryBackend {
   abstract shutdown(): Promise<void>
 }
 
-export { TelemetryCoordinator } from './coordinator.ts'
+export { TelemetryCoordinator, type TelemetryDelivery } from './coordinator.ts'
diff --git a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts b/packages/telemetry/session-telemetry/tests/telemetry.spec.ts
index a449a4053d..d913e6a742 100644
--- a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts
+++ b/packages/telemetry/session-telemetry/tests/telemetry.spec.ts
@@ -10,7 +10,12 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import SessionStore, { SessionId, type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { TelemetryCoordinator, type TelemetryBackend, type TelemetryRecord } from '../src/index.ts'
+import {
+  TelemetryCoordinator,
+  type TelemetryBackend,
+  type TelemetryDelivery,
+  type TelemetryRecord,
+} from '../src/index.ts'
 
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
@@ -54,15 +59,21 @@ class FakeBackend implements TelemetryBackend {
   }
 }
 
-async function setup(backend: FakeBackend = new FakeBackend()) {
+async function setup(
+  backend: FakeBackend = new FakeBackend(),
+  delivery: TelemetryDelivery = 'immediate',
+) {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
+  let coordinator!: TelemetryCoordinator
   const fiber = await ctx.plugin({
     name: 'fake-telemetry',
     inject: ['sessions'],
-    apply: (inner: Context) => void new TelemetryCoordinator(inner, backend),
+    apply: (inner: Context) => {
+      coordinator = new TelemetryCoordinator(inner, backend, delivery)
+    },
   })
-  return { ctx, backend, fiber }
+  return { ctx, backend, coordinator, fiber }
 }
 
 function liveSession(ctx: Context, id = `s-${Math.random().toString(36).slice(2)}`): Session {
@@ -167,6 +178,80 @@ describe('TelemetryCoordinator capture', () => {
   })
 })
 
+describe('TelemetryCoordinator held delivery', () => {
+  it('releases one pending prefix at a time without handing later records over early', async () => {
+    const { ctx, backend, coordinator } = await setup(new FakeBackend(), 'held')
+    const session = liveSession(ctx, 'held-prefix')
+    appendTurn(session)
+    expect(backend.records).toEqual([])
+
+    coordinator.release(session)
+    expect(backend.ledger().map(record => record.attributes['event.type'])).toEqual([
+      'turn/start',
+      'user/message',
+    ])
+
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    expect(backend.ledger()).toHaveLength(2)
+    coordinator.release(session)
+    coordinator.release(session)
+    expect(backend.ledger().map(record => record.attributes['event.type'])).toEqual([
+      'turn/start',
+      'user/message',
+      'turn/end',
+    ])
+  })
+
+  it('stores the capture-time redacted copy rather than re-running policy at release', async () => {
+    const { ctx, backend, coordinator } = await setup(new FakeBackend(), 'held')
+    const disposeRule = ctx.on('telemetry/record', (_record, next) => ({
+      ...next(),
+      body: { scrubbed: true },
+    }))
+    const session = liveSession(ctx, 'held-redacted')
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    disposeRule()
+
+    coordinator.release(session)
+    expect(backend.ledger()[0]!.body).toEqual({ scrubbed: true })
+  })
+
+  it('contains each backend failure independently while releasing a batch', async () => {
+    const backend = new FakeBackend()
+    backend.rejectSeq = 1
+    const { ctx, coordinator } = await setup(backend, 'held')
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const session = liveSession(ctx, 'held-failure')
+    appendTurn(session)
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+    coordinator.release(session)
+    expect(backend.ledger().map(record => record.attributes['event.seq'])).toEqual([0, 2])
+    expect(warn).toHaveBeenCalled()
+  })
+
+  it('rebuilds an unreleased prefix after coordinator reload', async () => {
+    const first = new FakeBackend()
+    const { ctx, fiber } = await setup(first, 'held')
+    const session = liveSession(ctx, 'held-reload')
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    await fiber.dispose()
+    expect(first.records).toEqual([])
+
+    const second = new FakeBackend()
+    let coordinator!: TelemetryCoordinator
+    await ctx.plugin({
+      name: 'fake-telemetry-after-held-reload',
+      inject: ['sessions'],
+      apply: (inner: Context) => {
+        coordinator = new TelemetryCoordinator(inner, second, 'held')
+      },
+    })
+    coordinator.release(session)
+    expect(second.ledger().map(record => record.attributes['event.seq'])).toEqual([0])
+  })
+})
+
 describe('TelemetryCoordinator adoption', () => {
   it('exports an unpublished suffix without re-exporting constructor history', async () => {
     const backend = new FakeBackend()
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2ecfd0e869..882d42c8d8 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -445,6 +445,9 @@ importers:
       '@cordisjs/plugin-include':
         specifier: workspace:*
         version: link:../vendor/include
+      '@cordisjs/plugin-logger-console':
+        specifier: workspace:*
+        version: link:../vendor/logger-console
       '@deepseek-ai/dsh-acp-demo':
         specifier: workspace:*
         version: link:../packages/examples/acp-demo
@@ -466,6 +469,9 @@ importers:
       '@deepseek-ai/dsh-code-runtime-worker':
         specifier: workspace:*
         version: link:../packages/code-runtime/code-runtime-worker
+      '@deepseek-ai/dsh-command-feedback':
+        specifier: workspace:*
+        version: link:../packages/feedback/command-feedback
       '@deepseek-ai/dsh-compact-basic':
         specifier: workspace:*
         version: link:../packages/compact/compact-basic
@@ -4810,6 +4816,9 @@ importers:
       '@cordisjs/plugin-loader':
         specifier: workspace:^
         version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-command-feedback':
+        specifier: workspace:^
+        version: link:../../feedback/command-feedback
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants

From 2c47636a85b2ac4dc38c399a58b2923456913ce3 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 5 Aug 2026 12:45:18 +0800
Subject: [PATCH 029/516] docs(environment): state the snapshot's name-matching
 contract

The Windows case-folding in the lookup was implemented without a
user-facing contract. Name matching follows the platform, and the
reason it must is the layer ranking it would otherwise invert.
---
 packages/util/environment/README.i18n.yaml | 4 ++--
 packages/util/environment/README.md        | 2 ++
 packages/util/environment/README.zh.md     | 2 ++
 3 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index c7ad354478..ea1e025257 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/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/util/environment/README.md
-README.md: 526c7263106962cdbc19ec58c00b06e58849a258
-README.zh.md: 203b8252d2e96235ec083481ccafda129902cd38
+README.md: 1bb444bc217ce1a01fb98f954d6e1c2bbc3db957
+README.zh.md: a46adf0beeb0fb2069e198c99e4c00c2e8c09c6c
diff --git a/packages/util/environment/README.md b/packages/util/environment/README.md
index 526c726310..1bb444bc21 100644
--- a/packages/util/environment/README.md
+++ b/packages/util/environment/README.md
@@ -18,6 +18,8 @@ Values do also reach `process.env` — a user's `--config` tree and third-party
 
 **Omitting a layer is a refusal, not a demotion** — a caller that must never accept a layer leaves it out of the list, so no future reordering can let it back in. The provider adapters name all three, because the product trusts the project it runs in; the mechanism exists for the decisions where that is not true.
 
+Names match the way the platform matches them: exactly on POSIX, case-insensitively on Windows. A case-sensitive lookup there would rank the wrong layer — a shell's `deepseek_api_key` and a project `.env`'s `DEEPSEEK_API_KEY` are one variable to the OS, and treating them as two would let the project win.
+
 ```ts
 import type { Context } from 'cordis'
 import { environmentOf } from '@deepseek-ai/dsh-environment'
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index 203b8252d2..a46adf0bee 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -18,6 +18,8 @@
 
 **省略某一层是拒绝，不是降级**——绝不能接受某一层的调用方直接不把它列进去，后续任何重新排序都无法让它回来。provider 适配器三层全列，因为产品信任它所运行的项目；该机制是为那些「并非如此」的决策准备的。
 
+变量名按平台自身的规则匹配：POSIX 上精确匹配，Windows 上不区分大小写。在 Windows 上做大小写敏感的查找会选错层——shell 里的 `deepseek_api_key` 与项目 `.env` 里的 `DEEPSEEK_API_KEY` 对操作系统而言是同一个变量，把它们当成两个就会让项目胜出。
+
 ```ts
 import type { Context } from 'cordis'
 import { environmentOf } from '@deepseek-ai/dsh-environment'

From f50b60390c539a979ca69713ab92ae72682a4c8c Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 5 Aug 2026 12:49:05 +0800
Subject: [PATCH 030/516] docs: regenerate the module graph for the environment
 package

`dsh-environment` and its consumer edges were missing from the
generated graph.
---
 docs/module-graph.md | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index aae611eff5..344d1f7131 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -10,6 +10,7 @@ flowchart TD
   subgraph group_util["packages/util"]
     pkg_atomic_write["atomic-write"]
     pkg_brand["brand"]
+    pkg_environment["environment"]
     pkg_native_command["native-command"]
     pkg_paths["paths"]
     pkg_retention["retention"]
@@ -275,6 +276,7 @@ flowchart TD
   end
   pkg_atomic_write --> pkg_invariants
   pkg_brand --> pkg_invariants
+  pkg_environment --> pkg_invariants
   pkg_native_command --> pkg_invariants
   pkg_paths --> pkg_invariants
   pkg_retention --> pkg_invariants
@@ -345,11 +347,13 @@ flowchart TD
   pkg_typert_loader --> pkg_invariants
   pkg_typert_loader --> pkg_typert_registry
   pkg_llm_deepseek --> pkg_credentials
+  pkg_llm_deepseek --> pkg_environment
   pkg_llm_deepseek --> pkg_invariants
   pkg_llm_deepseek --> pkg_llm
   pkg_llm_deepseek --> pkg_settings
   pkg_llm_deepseek --> pkg_timeout
   pkg_llm_pi_ai --> pkg_credentials
+  pkg_llm_pi_ai --> pkg_environment
   pkg_llm_pi_ai --> pkg_invariants
   pkg_llm_pi_ai --> pkg_llm
   pkg_llm_pi_ai --> pkg_settings
@@ -402,6 +406,7 @@ flowchart TD
   pkg_client_ui_workspace --> pkg_invariants
   pkg_credentials_local --> pkg_atomic_write
   pkg_credentials_local --> pkg_credentials
+  pkg_credentials_local --> pkg_environment
   pkg_credentials_local --> pkg_invariants
   pkg_credentials_local --> pkg_paths
   pkg_lsp --> pkg_brand
@@ -435,8 +440,10 @@ flowchart TD
   pkg_web_fetch_local --> pkg_invariants
   pkg_web_fetch_local --> pkg_timeout
   pkg_web_fetch_local --> pkg_web
+  pkg_web_search_exa --> pkg_environment
   pkg_web_search_exa --> pkg_invariants
   pkg_web_search_exa --> pkg_web
+  pkg_web_search_perplexity --> pkg_environment
   pkg_web_search_perplexity --> pkg_invariants
   pkg_web_search_perplexity --> pkg_web
   pkg_spill --> pkg_brand
@@ -449,6 +456,7 @@ flowchart TD
   pkg_llm_replay --> pkg_invariants
   pkg_llm_replay --> pkg_llm
   pkg_llm_replay --> pkg_session
+  pkg_app_boot --> pkg_environment
   pkg_app_boot --> pkg_invariants
   pkg_app_boot --> pkg_paths
   pkg_app_boot --> pkg_system_prompt
@@ -520,6 +528,7 @@ flowchart TD
   pkg_skill_local --> pkg_skill
   pkg_web_search_deepseek --> pkg_agent
   pkg_web_search_deepseek --> pkg_credentials
+  pkg_web_search_deepseek --> pkg_environment
   pkg_web_search_deepseek --> pkg_invariants
   pkg_web_search_deepseek --> pkg_session
   pkg_web_search_deepseek --> pkg_web
@@ -1078,6 +1087,7 @@ flowchart TD
 | [`invariants`](../packages/support/invariants) | `support` | — |
 | [`atomic-write`](../packages/util/atomic-write) | `util` | [`invariants`](../packages/support/invariants) |
 | [`brand`](../packages/util/brand) | `util` | [`invariants`](../packages/support/invariants) |
+| [`environment`](../packages/util/environment) | `util` | [`invariants`](../packages/support/invariants) |
 | [`native-command`](../packages/util/native-command) | `util` | [`invariants`](../packages/support/invariants) |
 | [`paths`](../packages/util/paths) | `util` | [`invariants`](../packages/support/invariants) |
 | [`retention`](../packages/util/retention) | `util` | [`invariants`](../packages/support/invariants) |
@@ -1119,8 +1129,8 @@ flowchart TD
 | [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
 | [`subprocess-local`](../packages/subprocess/subprocess-local) | `subprocess` | [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
 | [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
-| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
-| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
@@ -1131,7 +1141,7 @@ flowchart TD
 | [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`settings-local`](../packages/settings/settings-local) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`settings`](../packages/settings/settings) |
@@ -1141,12 +1151,12 @@ flowchart TD
 | [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
-| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
-| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`app-boot`](../packages/ui/app-boot) | `ui` | [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
+| [`app-boot`](../packages/ui/app-boot) | `ui` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
@@ -1163,7 +1173,7 @@ flowchart TD
 | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
 | [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
 | [`skill-local`](../packages/skill/skill-local) | `skill` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`skill`](../packages/skill/skill) |
-| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
+| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |

From 9d9b547d55dc6a2db4449193bcc505e2b5282712 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Wed, 5 Aug 2026 12:47:53 +0800
Subject: [PATCH 031/516] docs: refresh telemetry module graph

---
 docs/module-graph.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index 61477ae104..bddaf47f98 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -630,10 +630,6 @@ flowchart TD
   pkg_tasks_local --> pkg_invariants
   pkg_tasks_local --> pkg_tasks
   pkg_tasks_local --> pkg_timeout
-  pkg_session_telemetry_otel --> pkg_invariants
-  pkg_session_telemetry_otel --> pkg_llm
-  pkg_session_telemetry_otel --> pkg_session
-  pkg_session_telemetry_otel --> pkg_session_telemetry
   pkg_agent_loop --> pkg_agent
   pkg_agent_loop --> pkg_invariants
   pkg_agent_loop --> pkg_llm
@@ -813,6 +809,11 @@ flowchart TD
   pkg_tool_tasks --> pkg_system_prompt
   pkg_tool_tasks --> pkg_tasks
   pkg_tool_tasks --> pkg_tools
+  pkg_session_telemetry_otel --> pkg_command_feedback
+  pkg_session_telemetry_otel --> pkg_invariants
+  pkg_session_telemetry_otel --> pkg_llm
+  pkg_session_telemetry_otel --> pkg_session
+  pkg_session_telemetry_otel --> pkg_session_telemetry
   pkg_tool_workflow --> pkg_agent
   pkg_tool_workflow --> pkg_invariants
   pkg_tool_workflow --> pkg_llm
@@ -1096,7 +1097,6 @@ flowchart TD
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
-| [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | `telemetry` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
@@ -1126,6 +1126,7 @@ flowchart TD
 | [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools) |
 | [`tool-pty`](../packages/pty/tool-pty) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`pty`](../packages/pty/pty), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | `telemetry` | [`command-feedback`](../packages/feedback/command-feedback), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |

From 69d8621e2e060ab158467809b47a0841a976ecbe Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 5 Aug 2026 13:20:56 +0800
Subject: [PATCH 032/516] test: close the per-file coverage gaps this PR opened
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The layered-env reader gained an unreadable-layer path, a default
reporter, and two absent-layer arms with no cases; the credential store
gained two error paths that must not be mistaken for an absent file.

The platform arms and the `linePos` guard cannot be reached from a POSIX
test run — the first is covered by the native Windows job, the second
only satisfies an optional type that `prettyErrors` always fills — so
both carry a v8 ignore naming why.
---
 .../credentials-local/src/index.ts            |   2 +
 .../credentials-local/tests/local.spec.ts     |  23 ++++
 packages/settings/settings-local/src/index.ts |   1 +
 packages/ui/app-boot/tests/app-boot.spec.ts   | 107 ++++++++++++++++++
 packages/util/environment/src/index.ts        |   1 +
 5 files changed, 134 insertions(+)

diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index a5024353c8..ea77458d12 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -101,6 +101,7 @@ const GROUP_OTHER_BITS = 0o077
  * @throws when the file exists with group or other permission bits set.
  */
 async function assertOwnerOnly(filename: string): Promise<void> {
+  /* v8 ignore next -- native Windows coverage exercises the skip; POSIX covers the check */
   if (process.platform === 'win32') return
   let mode: number
   try {
@@ -130,6 +131,7 @@ function isENOENT(error: unknown): boolean {
  */
 function describeYamlError(error: YAMLError): string {
   const at = error.linePos?.[0]
+  /* v8 ignore next -- `prettyErrors` populates linePos on every error; the guard answers its optional type */
   const where = at === undefined ? '' : ` at line ${String(at.line)}, column ${String(at.col)}`
   return `${error.code}${where}`
 }
diff --git a/packages/credentials/credentials-local/tests/local.spec.ts b/packages/credentials/credentials-local/tests/local.spec.ts
index 7a8b8fdc17..43e42cd53f 100644
--- a/packages/credentials/credentials-local/tests/local.spec.ts
+++ b/packages/credentials/credentials-local/tests/local.spec.ts
@@ -179,6 +179,29 @@ describe('layer ladder', () => {
       .rejects.toThrow(/readable beyond its owner \(mode 644\)/)
   })
 
+  it('propagates a permission check that fails for a reason other than absence', async () => {
+    const dir = await tempDir()
+    const notADirectory = join(dir, 'occupied')
+    await writeFile(notADirectory, 'a regular file\n')
+    // An absent document is an empty store, but a path that cannot be
+    // reached at all is a misconfiguration: the parent is a file, so the
+    // check fails with ENOTDIR rather than concluding "no credentials yet".
+    const ctx = new Context()
+    await expect(ctx.plugin(CredentialsLocal, { path: join(notADirectory, '.credentials.yaml'), watch: false }))
+      .rejects.toThrow(/ENOTDIR/)
+  })
+
+  it('propagates a read that fails for a reason other than absence', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.credentials.yaml')
+    // Owner-only, so the permission check passes, and unreadable as a file:
+    // the store is present but cannot be parsed, which must fail the launch
+    // rather than silently serve nothing.
+    await mkdir(path, { mode: 0o700 })
+    const ctx = new Context()
+    await expect(ctx.plugin(CredentialsLocal, { path, watch: false })).rejects.toThrow(/EISDIR/)
+  })
+
   it('lets only the inherited environment shadow the store, read-only', async () => {
     const dir = await tempDir()
     const path = join(dir, '.credentials.yaml')
diff --git a/packages/settings/settings-local/src/index.ts b/packages/settings/settings-local/src/index.ts
index d713083c20..142d7935bd 100644
--- a/packages/settings/settings-local/src/index.ts
+++ b/packages/settings/settings-local/src/index.ts
@@ -250,6 +250,7 @@ export class SettingsLocal extends Settings {
         throw new Error(`settings-local: invalid document at ${this.spec.filename}: ${
           document.errors.map((error) => {
             const at = error.linePos?.[0]
+            /* v8 ignore next -- `prettyErrors` populates linePos on every error; the guard answers its optional type */
             return `${error.code}${at === undefined ? '' : ` at line ${String(at.line)}, column ${String(at.col)}`}`
           }).join('; ')}`)
       }
diff --git a/packages/ui/app-boot/tests/app-boot.spec.ts b/packages/ui/app-boot/tests/app-boot.spec.ts
index fba1ad1993..4d44c780c7 100644
--- a/packages/ui/app-boot/tests/app-boot.spec.ts
+++ b/packages/ui/app-boot/tests/app-boot.spec.ts
@@ -190,6 +190,113 @@ describe('loadLayeredEnv', () => {
       vi.unstubAllEnvs()
     }
   })
+
+  it('warns and continues when a layer exists but cannot be read', () => {
+    const home = tmp()
+    const project = tmp()
+    // A directory named `.env` is present-but-unreadable (EISDIR): unlike an
+    // absent file, it is a real misconfiguration, so it is reported rather
+    // than passed over in silence — and the other layers still load.
+    mkdirSync(join(home, '.env'))
+    writeFileSync(join(project, '.env'), `${NAMES[2]}=project-only\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    const warn = vi.fn()
+    try {
+      const snapshot = loadLayeredEnv(NAME, project, warn)
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining(`${NAME}: failed to load .env`))
+      expect(snapshot.layers).toEqual([
+        { source: 'process' },
+        { source: 'project-env', path: join(project, '.env') },
+      ])
+      expect(process.env[NAMES[2]]).toBe('project-only')
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('reports to stderr when the caller supplies no reporter', () => {
+    const home = tmp()
+    const project = tmp()
+    mkdirSync(join(home, '.env'))
+    writeFileSync(join(project, '.env'), `${NAMES[2]}=project-only\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    const write = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+    try {
+      const snapshot = loadLayeredEnv(NAME, project)
+      expect(write).toHaveBeenCalledWith(expect.stringContaining(`${NAME}: failed to load .env`))
+      expect(snapshot.layers).toEqual([
+        { source: 'process' },
+        { source: 'project-env', path: join(project, '.env') },
+      ])
+      expect(process.env[NAMES[2]]).toBe('project-only')
+    } finally {
+      write.mockRestore()
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('passes over an absent layer without reporting it', () => {
+    const home = tmp()
+    const project = tmp()
+    writeFileSync(join(project, '.env'), `${NAMES[2]}=project-only\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    const warn = vi.fn()
+    try {
+      // No user `.env` exists, which is ordinary rather than a fault: the
+      // layer is simply absent, and nothing is reported.
+      const snapshot = loadLayeredEnv(NAME, project, warn)
+      expect(warn).not.toHaveBeenCalled()
+      expect(snapshot.layers).toEqual([
+        { source: 'process' },
+        { source: 'project-env', path: join(project, '.env') },
+      ])
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('carries only the inherited environment when neither file exists', () => {
+    const home = tmp()
+    const project = tmp()
+    clear()
+    vi.stubEnv('DSH_HOME', home)
+    vi.stubEnv('APP_BOOT_LAYERED_INHERITED', 'inherited')
+    try {
+      const snapshot = loadLayeredEnv(NAME, project, vi.fn())
+      expect(snapshot.layers).toEqual([{ source: 'process' }])
+      expect(snapshot.get('APP_BOOT_LAYERED_INHERITED')).toEqual({ value: 'inherited', source: 'process' })
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
+
+  it('reads a harness home that is also the invocation directory exactly once', () => {
+    const both = tmp()
+    writeFileSync(join(both, '.env'), `${NAMES[2]}=one-file\n`)
+    clear()
+    vi.stubEnv('DSH_HOME', both)
+    try {
+      // One file cannot be two layers. It is the project layer, because that
+      // is the more trusted of the two — reading it twice would otherwise
+      // put the same path at two different ranks.
+      const snapshot = loadLayeredEnv(NAME, both, vi.fn())
+      expect(snapshot.layers).toEqual([
+        { source: 'process' },
+        { source: 'project-env', path: join(both, '.env') },
+      ])
+      expect(snapshot.get(NAMES[2])).toEqual({ value: 'one-file', source: 'project-env', path: join(both, '.env') })
+    } finally {
+      clear()
+      vi.unstubAllEnvs()
+    }
+  })
 })
 
 describe('installFailLoud', () => {
diff --git a/packages/util/environment/src/index.ts b/packages/util/environment/src/index.ts
index 11014f64b5..f35e32f9c5 100644
--- a/packages/util/environment/src/index.ts
+++ b/packages/util/environment/src/index.ts
@@ -76,6 +76,7 @@ export interface EnvironmentSnapshot {
  * @returns the key to store and look up by.
  */
 function lookupKey(name: string): string {
+  /* v8 ignore next -- native Windows coverage exercises the folding arm; POSIX covers the exact one */
   return process.platform === 'win32' ? name.toUpperCase() : name
 }
 

From e1d226c4affa5137cb253a40b7a5f25aa7279e59 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 5 Aug 2026 13:23:19 +0800
Subject: [PATCH 033/516] test: point the last two credential stores at the
 YAML document

The e2e store and the web-search store still named a `.env` path; the
e2e one also wrote dotenv syntax, which the YAML document rejects. That
path now names the ordinary environment layer, so a test pointing the
credential store at it asserts the distinction this PR removes.
---
 packages/llm/llm-deepseek/tests/adapter.e2e.ts          | 6 ++++--
 packages/web/web-search-deepseek/tests/deepseek.spec.ts | 2 +-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/llm/llm-deepseek/tests/adapter.e2e.ts b/packages/llm/llm-deepseek/tests/adapter.e2e.ts
index 5468cd8d9f..97ae629001 100644
--- a/packages/llm/llm-deepseek/tests/adapter.e2e.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.e2e.ts
@@ -62,14 +62,16 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-deepseek e2e (real API)', ()
     if (key === undefined) throw new Error('e2e ran without DEEPSEEK_API_KEY')
     const dir = await mkdtemp(join(tmpdir(), 'dsh-e2e-credentials-'))
     try {
-      await writeFile(join(dir, '.env'), `DEEPSEEK_API_KEY=${key}\n`, { mode: 0o600 })
+      // JSON.stringify quotes the value: YAML is a JSON superset, so a real
+      // key survives whatever characters it happens to carry.
+      await writeFile(join(dir, '.credentials.yaml'), `DEEPSEEK_API_KEY: ${JSON.stringify(key)}\n`, { mode: 0o600 })
       // Scrub the ambient variable so only the credential seam can supply the
       // key: this request proves the per-request resolution path end to end.
       vi.stubEnv('DEEPSEEK_API_KEY', '')
       const ctx = new Context()
       contexts.push(ctx)
       await ctx.plugin(LlmService)
-      await ctx.plugin(CredentialsLocal, { path: join(dir, '.env'), watch: false })
+      await ctx.plugin(CredentialsLocal, { path: join(dir, '.credentials.yaml'), watch: false })
       await ctx.plugin(LlmDeepSeek, {})
 
       const result = await assemble(ctx, {
diff --git a/packages/web/web-search-deepseek/tests/deepseek.spec.ts b/packages/web/web-search-deepseek/tests/deepseek.spec.ts
index 7990a96a9b..23c2d2c237 100644
--- a/packages/web/web-search-deepseek/tests/deepseek.spec.ts
+++ b/packages/web/web-search-deepseek/tests/deepseek.spec.ts
@@ -455,7 +455,7 @@ describe('web-search-deepseek plugin registration', () => {
     const ctx = new Context()
     try {
       await ctx.plugin(WebService, { searchProvider: DEEPSEEK_PROVIDER_ID })
-      await ctx.plugin(CredentialsLocal, { path: join(dir, '.env'), watch: false })
+      await ctx.plugin(CredentialsLocal, { path: join(dir, '.credentials.yaml'), watch: false })
       await ctx.plugin(deepseekPlugin, { baseURL: 'https://api.deepseek.test/anthropic/v1' })
 
       await expect(ctx.web.search({ query: 'missing' }))

From 6cd0eea52d92dc3596851316623674e4ec502fb9 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Tue, 4 Aug 2026 22:37:19 -0700
Subject: [PATCH 034/516] docs: propose Task Surface protocol

---
 .../feature/2026-08-04-task-surface.i18n.yaml |   6 +
 .../feature/2026-08-04-task-surface.md        | 232 ++++++++++++++++++
 .../feature/2026-08-04-task-surface.zh.md     | 232 ++++++++++++++++++
 3 files changed, 470 insertions(+)
 create mode 100644 .agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
 create mode 100644 .agents/notes/proposed/feature/2026-08-04-task-surface.md
 create mode 100644 .agents/notes/proposed/feature/2026-08-04-task-surface.zh.md

diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml b/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
new file mode 100644
index 0000000000..36e7d8c5d6
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.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/proposed/feature/2026-08-04-task-surface.md
+2026-08-04-task-surface.md: 780d5d884c83ab47535fff95efcd80b0b7f0181f
+2026-08-04-task-surface.zh.md: 38e6787ee5a4d86261e79c66d99f81614bdb5871
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
new file mode 100644
index 0000000000..780d5d884c
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
@@ -0,0 +1,232 @@
+# Agent Note: Task Surface for structured session interaction
+
+Status: proposed
+
+English | [中文](2026-08-04-task-surface.zh.md)
+
+## Problem
+
+Some tasks are awkward to finish through alternating prose messages. Comparing several options, reordering a plan, reviewing a table, or filling a small set of related fields all work better as one structured interaction. Today an agent can describe such an interaction, but it cannot ask the Web client to render one without adding a permanent product component or generating executable Client Plugin code.
+
+Those two workarounds put ownership in the wrong place. Product-specific components require a new trigger and release for every task shape. Generated code has far more authority and lifecycle cost than a one-turn form needs. It also makes the presentation, rather than the user's conclusion, the durable artifact.
+
+The missing contract is a bounded, replayable description of a temporary UI that belongs to one Session and one tool occurrence. The product should own validation, placement, interaction mechanics, and submission. The agent should own the task-specific copy, data, and choice of supported components.
+
+## Proposal
+
+Add **Task Surface**, a versioned declarative model rendered by a normal Web Client Plugin. One stable model-facing tool, `show_task_surface`, publishes the model. A successful call ends the current turn. The user edits and submits the rendered panel; the Host records the submission as one ordinary visible user message and starts the next turn.
+
+Task Surface is the default structured-UI path when all of the following hold:
+
+- the interaction belongs to the current Session and current task;
+- its behavior fits the declared component set;
+- it needs no background execution or new runtime authority; and
+- the useful durable result is the user's submitted conclusion, not the panel itself.
+
+This is one trigger, not a family of product heuristics. The agent calls `show_task_surface` explicitly. A user may ask the agent to use a Task Surface in ordinary language. Products do not inspect tool names or task topics to open bespoke panels, and repeated use does not automatically turn a Task Surface into a Plugin.
+
+Short blocking questions remain with [`ask_user_question`](../../implemented/feature/2026-07-29-ask-question-web-presentation.md). Plain explanation remains chat. Cross-Session navigation, background behavior, new services, or durable custom UI belongs to the Generated Client Plugin workflow.
+
+## Declarative model
+
+`TaskSurfaceModelV1` is JSON. It contains content blocks, input fields, and one submit label; it contains no code, callbacks, selectors, HTML, CSS, URLs to executable assets, or expression language. This type is unrelated to core Session's existing `SurfaceManager`/`SurfaceOp` message-reduction types; Task Surface is a product interaction protocol.
+
+```ts ignore-check
+interface TaskSurfaceModelV1 {
+  version: 1
+  title: string
+  description?: string
+  sections: TaskSurfaceSection[]
+  fields?: TaskSurfaceField[]
+  submit: { label: string }
+}
+
+interface TaskSurfaceSection {
+  id: string
+  title?: string
+  layout?: 'stack' | 'grid'
+  columns?: 2 | 3
+  blocks: TaskSurfaceBlock[]
+}
+
+type TaskSurfaceBlock =
+  | { kind: 'markdown'; text: string }
+  | { kind: 'metrics'; items: { label: string; value: string; detail?: string }[] }
+  | { kind: 'table'; columns: { id: string; label: string }[]; rows: Record<string, string | number | boolean | null>[] }
+  | { kind: 'diff'; path?: string; before: string | null; after: string; language?: string }
+  | { kind: 'notice'; tone: 'neutral' | 'info' | 'warning'; text: string }
+
+type TaskSurfaceField =
+  | { kind: 'text'; id: string; label: string; multiline?: boolean; required?: boolean; initial?: string }
+  | { kind: 'choice'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string }
+  | { kind: 'multi-choice'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string[] }
+  | { kind: 'toggle'; id: string; label: string; initial?: boolean }
+  | { kind: 'order'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string[] }
+
+interface TaskSurfaceOption { id: string; label: string; detail?: string }
+```
+
+The renderer controls typography, spacing, responsive layout, focus order, keyboard behavior, and theme tokens. `grid` is a layout hint: it collapses when the available width cannot support the requested columns. Markdown uses the product's supported Markdown subset. Unknown versions or union arms use the generic tool-result fallback instead of partial interpretation.
+
+Version 1 deliberately omits conditional fields, client-side data fetching, charts, file uploads, and arbitrary event handlers. A new block or field kind is a protocol change with a parser, renderer, accessibility behavior, fallback, and replay fixture in the same change.
+
+Limits are schema-backed configuration on the Task Surface service. The initial defaults are 64 KiB for the normalized model, 64 blocks, 32 fields, 200 table rows, and 32 KiB for a submission. IDs are unique within the model; field values must match their declarations; unknown fields are rejected. The limits bound log, DOM, and prompt costs without changing the protocol.
+
+## Tool and presentation contract
+
+`show_task_surface` accepts `{ model: TaskSurfaceModelV1 }`. The Host parses and normalizes the complete model, rejects the call when that Session already has an open Task Surface, mints `surfaceId`, and returns canonical `{ surfaceId, model }` with the normalized model. `presentationMeta` persists `value.model`, so the projector and executor cannot disagree about normalization. The Native result names the Surface and explains that an ordinary message bypasses it when the client cannot render the panel. The tool then calls `exec.concludeTurn()` so the agent does not continue past the requested human checkpoint.
+
+The tool definition sets `exclusive: true`, and the tool is composed only in Web profiles that mount both the Host service and Web renderer. Version 1 supports `native` and `both` tool modes; a `code`-only profile does not advertise it because Code Mode dispatch is nested and cannot carry its presentation metadata to the outer result.
+
+The canonical value is execution-local under the [canonical tool output contract](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md). Replay therefore uses `output.presentationMeta(args, value)` to persist this tagged payload with `tool/result.meta`:
+
+```ts ignore-check
+interface TaskSurfacePresentationMeta {
+  kind: 'dsh/task-surface'
+  version: 1
+  surfaceId: string
+  model: TaskSurfaceModelV1
+}
+```
+
+The tool keeps a generic [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md). The keyed Web row reads the tagged metadata already retained on `ToolResultNode`; no new render-intent arm or presentation registry is required. Clients without Task Surface support render the ordinary result content.
+
+The Web plugin statically registers one keyed `conversation.chat.toolview` entry for `show_task_surface`, following the [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) and [slot registration](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md) contracts. The row renders a compact summary when settled and expands the declarative panel inline. The model does not choose a conversation tab, details column, modal, pixel position, or z-index. A later placement change remains a renderer decision and does not alter logged models.
+
+## Submission contract
+
+The Task Surface domain exposes three operations through the Host transport. `submit` is the only one that admits a user message:
+
+```ts ignore-check
+type TaskSurfaceSubmissionId = string & { readonly __brand: 'TaskSurfaceSubmissionId' }
+type TaskSurfaceDismissalId = string & { readonly __brand: 'TaskSurfaceDismissalId' }
+
+interface TaskSurfaceService {
+  getActive(input: { sessionId: SessionId; surfaceId: string }): Promise<GetActiveTaskSurfaceResult>
+  submit(input: SubmitTaskSurfaceRequest): Promise<SubmitTaskSurfaceResult>
+  dismiss(input: DismissTaskSurfaceRequest): Promise<DismissTaskSurfaceResult>
+}
+
+interface SubmitTaskSurfaceRequest {
+  sessionId: SessionId
+  surfaceId: string
+  submissionId: TaskSurfaceSubmissionId
+  values: Record<string, JsonValue>
+  note?: string
+}
+
+type SubmitTaskSurfaceResult =
+  | { accepted: true; messageId: MessageId }
+  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' }
+
+type GetActiveTaskSurfaceResult =
+  | { active: true; callId: CallId; surfaceId: string; model: TaskSurfaceModelV1 }
+  | { active: false; reason: 'not-open' }
+
+interface DismissTaskSurfaceRequest {
+  sessionId: SessionId
+  surfaceId: string
+  dismissalId: TaskSurfaceDismissalId
+}
+
+type DismissTaskSurfaceResult =
+  | { dismissed: true; eventSeq: number }
+  | { dismissed: false; reason: 'not-open' | 'stale' }
+```
+
+The Host resolves the exact successful `show_task_surface` occurrence, revalidates the submitted values against its persisted model, and admits the response through the normal Session queue. The response becomes a user-role message with a merge-extensible source:
+
+```ts ignore-check
+interface TaskSurfaceCorrelation {
+  version: 1
+  submissionId: TaskSurfaceSubmissionId
+  callId: CallId
+  surfaceId: string
+  values: Record<string, JsonValue>
+}
+
+interface TaskSurfaceUserMessageSource {
+  kind: 'user'
+  rpcId: RpcId
+  taskSurface: TaskSurfaceCorrelation
+}
+```
+
+The browser-safe domain package owns `TaskSurfaceCorrelation` and its branded `submissionId`. ApiProxy owns the transport augmentation that combines it with `rpcId`. Keeping `kind: 'user'` preserves the ordinary user bubble and prompt semantics while the extra field provides durable correlation. The message content is a product-formatted readable summary: panel title, labels and submitted values, plus the optional note. The model receives that same text. The structured source is not a second hidden instruction.
+
+The product shell owns collapse and dismiss. Collapse is local view state and sends nothing. `taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` appends one `task-surface/dismissed` Session event and does not start a turn; the exact event closes the projection and updates the transcript row. Retries reuse `dismissalId` and return the original result without appending another event.
+
+Submission is transactional at the client boundary. The panel disables submit while admission is in flight and clears the persisted draft only after the matching user message becomes durable. A rejection keeps the values editable and shows the returned reason. Double clicks and transport retries reuse `submissionId`; the Host admits one user message for one accepted Surface.
+
+There is a short interval between queue admission and the durable `user/message`. The generic queued-message DTO therefore retains `Message.source`. A queued message with matching Task Surface correlation keeps the panel disabled; if that queue item is discarded, the pending state clears and the draft becomes editable again. The Host holds a process-local single-flight claim for the same interval, then releases it on commit, rejection, or discard. The queue is coordination state, not a second durable lifecycle record.
+
+## Lifecycle and recovery
+
+The Session log is the authority. A small `taskSurface` unit in the existing [Session projection system](../architecture/2026-07-27-session-projection-and-command-log.md) folds successful surface result metadata and later user-message sources into this state:
+
+```ts ignore-check
+interface TaskSurfaceProjection {
+  active: { callId: CallId; surfaceId: string } | null
+}
+```
+
+One Session has at most one open Task Surface. A successful result opens it. A matching Task Surface user message or dismissal event closes it. A later ordinary user message also closes it as an explicit bypass; another `show_task_surface` call fails until one of those events closes the active occurrence. Rewind and fork derive their active occurrence by folding the resulting log; no separate Surface database participates.
+
+The full model remains on its `tool/result.meta`; the projection carries only the active identity. When that result is outside the loaded history window, `taskSurface.getActive({ sessionId, surfaceId })` reads the exact occurrence from the Session log and returns `{ callId, surfaceId, model }` after revalidating the metadata. A missing or closed occurrence returns `not-open`. Refresh and reconnect therefore do not depend on the active result fitting in the history tail and do not duplicate the model into every projection baseline.
+
+The Web plugin keeps unsubmitted values in a bounded, per-Session persisted slot store keyed by `surfaceId`; they never enter the Session log, prompt, or long-term memory. Submitted values live in the accepted user message, so losing a browser draft cannot erase a conclusion.
+
+## Package boundaries and dependencies
+
+The capability is split where ownership changes:
+
+| Package | Responsibility |
+|---|---|
+| `packages/task-surface/task-surface` | Browser-safe model/types and correlation, parser, limits, submission validator/formatter, Session event extension, projection unit, and Host service contract |
+| `packages/task-surface/tool-task-surface` | `show_task_surface`, canonical output, presentation metadata, generic render intent, active-Surface check, and `concludeTurn()` behavior |
+| `packages/client/ui-task-surface` | Static keyed tool row, declarative Web renderer, per-Session draft store, and submit client |
+| `packages/host/apiproxy` | Typed active-read/submit/dismiss transport, user-source augmentation, and queued-source carriage; delegates validation and admission to the Task Surface service |
+
+The implementation depends on the existing message log, canonical tool output, tagged render intents, Session projection, per-Session declared slot stores, and slot lifecycle. It does not depend on runtime Client Plugin creation. The generated Client Plugin workflow may use Task Surface to present a review form, but neither protocol owns or activates the other.
+
+## Delivery stages
+
+1. Land the model/parser, projection unit, `show_task_surface`, presentation metadata, static Web row, and generic fallback with read-only blocks.
+2. Add fields, persisted drafts, Host-validated submit/dismiss, queued-source carriage, and visible user-message admission.
+3. Add only component kinds justified by real tasks and two consumers or a clear generic fallback. A separate explicit user action may start the generated Plugin authoring workflow, but it creates a candidate; it never promotes code directly.
+
+## Alternatives considered
+
+**Add product-specific triggers and panels.** Rejected because every new task shape would couple agent behavior to a shipped product component. Product code should define one admitted component vocabulary and placement policy; the agent chooses among it explicitly.
+
+**Render arbitrary HTML, CSS, or JavaScript from the tool call.** Rejected because it turns a temporary interaction into executable Client Plugin code without the build, preview, evaluation, approval, or rollback lifecycle that code requires.
+
+**Extend `userInteraction.ask()` with a large form.** Rejected for this contract. `ask()` is a blocking request/response operation used when a running tool cannot continue without a short answer. A Task Surface ends the turn, may remain open across refreshes, and submits its result as the next visible user turn.
+
+**Register one dynamic `conversation.view` per call.** Rejected because the view ledger is global while its render scope is per Session, and because transient task identity would become registration identity. One static keyed toolview keeps occurrence data in the logged call where it belongs.
+
+**Keep the model only in the canonical tool value.** Rejected because canonical values are not persisted. Replay requires the normalized model in `presentationMeta`.
+
+**Store the panel in long-term memory.** Rejected because layout and draft state are not the reusable fact. Memory may retain the submitted user conclusion under existing memory policy.
+
+## Acceptance criteria
+
+- A real model in `native` or `both` mode can call one stable `show_task_surface` schema, the call ends its turn, and a capable Web client renders the same normalized model live and after replay; `code`-only mode does not advertise it.
+- Submitting produces exactly one visible user message per `submissionId`, starts the next turn through normal queue admission, and retains exact occurrence correlation while keeping `source.kind: 'user'`; dismissing records one log event and starts no turn.
+- Refresh, reconnect, Session switching, fork, and rewind produce the lifecycle state implied by the log; `getActive` recovers a model outside the history tail, and no panel leaks across Sessions.
+- Unsupported versions, malformed metadata, and absent client capability fall back to readable tool-result content with the ordinary-message bypass; nested calls and calls made while another Surface is active fail without opening a Surface.
+- The parser enforces IDs, union shapes, field values, and configured byte/count limits before the panel becomes actionable.
+- Keyboard-only operation, focus restoration, accessible names, narrow layouts, both themes, and zh/en product chrome are covered by component tests.
+- Keyless browser composition covers show, edit, retry after rejected admission, queued/discarded submission, durable submit, dismiss, refresh recovery, and double-submit idempotency.
+- Prefix snapshots show one stable tool definition regardless of the task-specific model; only the call arguments and later user conclusion vary.
+- Unloading the Web plugin disposes its row and draft stores through the owning Fiber without changing the durable transcript.
+
+## Risks
+
+The first component set may be either too small for useful tasks or broad enough to become a weak application framework. Usage evidence should decide additions; v1 has no expression language or network behavior.
+
+Large tables and Markdown can still create expensive DOM even inside byte limits. The renderer must virtualize or truncate where needed while preserving a readable fallback and explicit counts.
+
+A product-formatted submission can become verbose when many fields are filled. The formatter needs a deterministic compact form and must preserve every submitted value without repeating the complete display model.
+
+Browser-local draft persistence can retain sensitive unsubmitted text. The store needs the stated byte bound, per-Session keys, explicit clearing after acceptance, and the same storage posture as the existing conversation draft.
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
new file mode 100644
index 0000000000..38e6787ee5
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
@@ -0,0 +1,232 @@
+# Agent Note: 用于结构化会话交互的 Task Surface
+
+Status: proposed
+
+[English](2026-08-04-task-surface.md) | 中文
+
+## 问题
+
+有些任务很难通过交替发送文本消息来完成。比较多个选项、调整计划顺序、审阅表格，或填写一小组关联字段，都更适合在一次结构化交互中处理。目前，agent（智能体）可以描述这类交互，但若不增加永久的产品组件或生成可执行的客户端插件代码，就无法要求 Web 客户端渲染这类交互。
+
+这两种变通方案的职责归属都不合理。产品专用组件要求每种任务形态都新增触发方式并发布新版本。对于只需一个轮次的表单，生成代码所拥有的权限和生命周期成本都远超实际需要。这样做还会把展示界面而非用户结论变成持久产物。
+
+目前缺少这样一份契约：用有界、可回放的描述来定义临时 UI，并让它只属于一个会话和一次工具调用实例。产品应当负责校验、放置、交互机制和提交；agent 应当负责特定任务的文案、数据，以及从受支持组件中作出选择。
+
+## 提案
+
+新增 **Task Surface**：一种由普通 Web 客户端插件渲染、带版本的声明式模型。面向模型提供一个稳定工具 `show_task_surface`，用于发布该模型。调用成功后，当前轮次结束。用户编辑并提交渲染出的面板；Host 将提交内容记录为一条普通的可见用户消息，并开始下一轮。
+
+同时满足以下条件时，Task Surface 是默认的结构化 UI 路径：
+
+- 交互属于当前会话和当前任务；
+- 行为可以由已声明的组件集合表达；
+- 不需要后台执行或新增运行时权限；
+- 有价值的持久结果是用户提交的结论，而不是面板本身。
+
+这里定义的是一个触发方式，不是一组产品启发式规则。agent 会显式调用 `show_task_surface`。用户可以通过普通语言要求 agent 使用 Task Surface。产品不会根据工具名称或任务主题打开专用面板；重复使用也不会自动把 Task Surface 转为插件。
+
+简短的阻塞式问题仍由 [`ask_user_question`](../../implemented/feature/2026-07-29-ask-question-web-presentation.md) 处理。纯文本说明仍留在聊天中。跨会话导航、后台行为、新服务或持久自定义 UI 则属于 Generated Client Plugin 工作流。
+
+## 声明式模型
+
+`TaskSurfaceModelV1` 使用 JSON。它包含内容块、输入字段和一个提交标签；不包含代码、回调、选择器、HTML、CSS、可执行产物的 URL，也不包含表达式语言。该类型与核心会话中现有的 `SurfaceManager`/`SurfaceOp` 消息归约类型无关；Task Surface 是一套产品交互协议。
+
+```ts ignore-check
+interface TaskSurfaceModelV1 {
+  version: 1
+  title: string
+  description?: string
+  sections: TaskSurfaceSection[]
+  fields?: TaskSurfaceField[]
+  submit: { label: string }
+}
+
+interface TaskSurfaceSection {
+  id: string
+  title?: string
+  layout?: 'stack' | 'grid'
+  columns?: 2 | 3
+  blocks: TaskSurfaceBlock[]
+}
+
+type TaskSurfaceBlock =
+  | { kind: 'markdown'; text: string }
+  | { kind: 'metrics'; items: { label: string; value: string; detail?: string }[] }
+  | { kind: 'table'; columns: { id: string; label: string }[]; rows: Record<string, string | number | boolean | null>[] }
+  | { kind: 'diff'; path?: string; before: string | null; after: string; language?: string }
+  | { kind: 'notice'; tone: 'neutral' | 'info' | 'warning'; text: string }
+
+type TaskSurfaceField =
+  | { kind: 'text'; id: string; label: string; multiline?: boolean; required?: boolean; initial?: string }
+  | { kind: 'choice'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string }
+  | { kind: 'multi-choice'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string[] }
+  | { kind: 'toggle'; id: string; label: string; initial?: boolean }
+  | { kind: 'order'; id: string; label: string; options: TaskSurfaceOption[]; initial?: string[] }
+
+interface TaskSurfaceOption { id: string; label: string; detail?: string }
+```
+
+渲染器控制字体排印、间距、响应式布局、焦点顺序、键盘行为和主题 token。`grid` 是布局提示：可用宽度无法容纳所要求的列数时，渲染器会将其折叠。Markdown 使用产品支持的 Markdown 子集。遇到未知版本或联合类型分支时，系统使用通用工具结果回退，而不是只解释其中一部分。
+
+版本 1 有意不支持条件字段、客户端数据获取、图表、文件上传和任意事件处理器。新增任何块或字段类型都属于协议变更，必须在同一变更中加入解析器、渲染器、无障碍行为、回退方式和回放 fixture（测试前置数据）。
+
+Task Surface 服务通过受 schema 校验的配置定义限制。初始默认值为：规范化模型不超过 64 KiB、块不超过 64 个、字段不超过 32 个、表格行不超过 200 行、提交内容不超过 32 KiB。模型内的 ID 必须唯一；字段值必须符合其声明；未知字段会被拒绝。这些限制约束日志、DOM 和提示词成本，但不改变协议。
+
+## 工具与呈现契约
+
+`show_task_surface` 接收 `{ model: TaskSurfaceModelV1 }`。Host 解析并规范化完整模型；若该会话已有一个打开的 Task Surface，则拒绝调用；否则生成 `surfaceId`，并返回带规范化模型的规范值 `{ surfaceId, model }`。`presentationMeta` 持久化 `value.model`，使投影器和执行器不会对规范化结果产生分歧。Native 结果会指明该 Surface，并说明客户端无法渲染面板时，可以通过普通消息绕过它。随后工具调用 `exec.concludeTurn()`，防止 agent 越过所要求的人工检查点继续执行。
+
+工具定义设置 `exclusive: true`，并且只会组装到同时挂载 Host 服务和 Web 渲染器的 Web profile 中。版本 1 支持 `native` 和 `both` 工具模式；仅支持 `code` 的 profile 不会向模型公布该工具，因为 Code Mode 分发属于嵌套调用，无法把呈现元数据传到外层结果。
+
+根据[规范工具输出契约](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
+
+```ts ignore-check
+interface TaskSurfacePresentationMeta {
+  kind: 'dsh/task-surface'
+  version: 1
+  surfaceId: string
+  model: TaskSurfaceModelV1
+}
+```
+
+该工具保留通用 [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md)。带 key 的 Web 行读取 `ToolResultNode` 上已经保留的带标签元数据，无需新增 render-intent 分支或呈现注册表。不支持 Task Surface 的客户端会渲染普通结果内容。
+
+Web 插件遵循 [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) 和 [slot 注册](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md)契约，为 `show_task_surface` 静态注册一个带 key 的 `conversation.chat.toolview` 条目。结算后，该行显示简洁摘要，并在行内展开声明式面板。模型不能选择会话标签页、详情栏、模态框、像素位置或 z-index。以后即使改变放置位置，也只是渲染器的决策，不会改变日志中记录的模型。
+
+## 提交契约
+
+Task Surface 领域通过 Host 传输层公开三个操作。只有 `submit` 会接纳用户消息：
+
+```ts ignore-check
+type TaskSurfaceSubmissionId = string & { readonly __brand: 'TaskSurfaceSubmissionId' }
+type TaskSurfaceDismissalId = string & { readonly __brand: 'TaskSurfaceDismissalId' }
+
+interface TaskSurfaceService {
+  getActive(input: { sessionId: SessionId; surfaceId: string }): Promise<GetActiveTaskSurfaceResult>
+  submit(input: SubmitTaskSurfaceRequest): Promise<SubmitTaskSurfaceResult>
+  dismiss(input: DismissTaskSurfaceRequest): Promise<DismissTaskSurfaceResult>
+}
+
+interface SubmitTaskSurfaceRequest {
+  sessionId: SessionId
+  surfaceId: string
+  submissionId: TaskSurfaceSubmissionId
+  values: Record<string, JsonValue>
+  note?: string
+}
+
+type SubmitTaskSurfaceResult =
+  | { accepted: true; messageId: MessageId }
+  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' }
+
+type GetActiveTaskSurfaceResult =
+  | { active: true; callId: CallId; surfaceId: string; model: TaskSurfaceModelV1 }
+  | { active: false; reason: 'not-open' }
+
+interface DismissTaskSurfaceRequest {
+  sessionId: SessionId
+  surfaceId: string
+  dismissalId: TaskSurfaceDismissalId
+}
+
+type DismissTaskSurfaceResult =
+  | { dismissed: true; eventSeq: number }
+  | { dismissed: false; reason: 'not-open' | 'stale' }
+```
+
+Host 解析出 `show_task_surface` 的确切成功调用实例，依据其已持久化模型重新校验提交值，并通过普通会话队列接纳响应。该响应成为一条用户角色消息，并使用可合并扩展的消息来源：
+
+```ts ignore-check
+interface TaskSurfaceCorrelation {
+  version: 1
+  submissionId: TaskSurfaceSubmissionId
+  callId: CallId
+  surfaceId: string
+  values: Record<string, JsonValue>
+}
+
+interface TaskSurfaceUserMessageSource {
+  kind: 'user'
+  rpcId: RpcId
+  taskSurface: TaskSurfaceCorrelation
+}
+```
+
+浏览器安全的领域包拥有 `TaskSurfaceCorrelation` 及其带品牌类型的 `submissionId`。ApiProxy 拥有传输扩展，负责将其与 `rpcId` 组合。保留 `kind: 'user'` 可维持普通用户消息气泡和提示词语义，额外字段则提供持久关联信息。消息内容是由产品格式化的可读摘要，包括面板标题、标签和提交值，以及可选备注。模型接收相同的文本。结构化来源不是第二条隐藏指令。
+
+产品外壳负责收起和关闭。收起属于本地视图状态，不会发送任何内容。`taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` 追加一个 `task-surface/dismissed` 会话事件，但不启动轮次；该精确事件会关闭投影并更新 transcript（文本记录）中的对应行。重试会复用 `dismissalId` 并返回原始结果，不会再追加一个事件。
+
+客户端边界上的提交具有事务性。接纳进行期间，面板会禁用提交；只有匹配的用户消息持久化后，才会清除已持久化的草稿。若请求被拒绝，则保留值供用户继续编辑，并显示返回的原因。双击和传输重试会复用 `submissionId`；对于一个已接受的 Surface，Host 只会接纳一条用户消息。
+
+队列接纳与 `user/message` 持久化之间存在一个短暂区间。因此，通用排队消息 DTO 会保留 `Message.source`。带有匹配 Task Surface 关联信息的排队消息会使面板维持禁用状态；如果该队列项被丢弃，待处理状态会清除，草稿恢复为可编辑状态。在同一区间，Host 会持有一个进程内 single-flight 占用，并在消息提交持久化、接纳被拒或队列项被丢弃时释放。队列属于协调状态，并不是第二份持久生命周期记录。
+
+## 生命周期与恢复
+
+会话日志是真源。现有[会话投影系统](../architecture/2026-07-27-session-projection-and-command-log.md)中的一个小型 `taskSurface` 单元会折叠成功调用的 Surface 结果元数据和后续用户消息来源，得到以下状态：
+
+```ts ignore-check
+interface TaskSurfaceProjection {
+  active: { callId: CallId; surfaceId: string } | null
+}
+```
+
+一个会话最多只能有一个打开的 Task Surface。成功的结果会打开它；匹配的 Task Surface 用户消息或关闭事件会将其关闭。后续的普通用户消息也会将其关闭，这是一条显式的绕过路径；在以上任一事件关闭活动调用实例前，再次调用 `show_task_surface` 都会失败。回退和 fork 会通过折叠相应日志推导出活动调用实例，不会使用独立的 Surface 数据库。
+
+完整模型仍存放在对应的 `tool/result.meta` 中；投影只携带活动身份。当该结果超出已加载的历史窗口时，`taskSurface.getActive({ sessionId, surfaceId })` 会从会话日志中读取确切调用实例，重新校验元数据后返回 `{ callId, surfaceId, model }`。调用实例不存在或已经关闭时返回 `not-open`。因此，刷新和重新连接不要求活动结果位于历史尾段，也无需把模型复制到每一个投影基线中。
+
+Web 插件将未提交值保存在一个有界、按会话持久化的 slot store 中，并以 `surfaceId` 为 key；这些值永远不会进入会话日志、提示词或长期记忆。已提交值存放在接纳的用户消息中，因此即使浏览器草稿丢失，也不会抹去结论。
+
+## 包边界与依赖
+
+该能力按职责变化处分包：
+
+| 包 | 职责 |
+|---|---|
+| `packages/task-surface/task-surface` | 浏览器安全的模型／类型和关联信息、解析器、限制、提交校验器／格式化器、会话事件扩展、投影单元，以及 Host 服务契约 |
+| `packages/task-surface/tool-task-surface` | `show_task_surface`、规范输出、呈现元数据、通用 render intent、活动 Surface 检查和 `concludeTurn()` 行为 |
+| `packages/client/ui-task-surface` | 静态带 key 的工具行、声明式 Web 渲染器、按会话划分的草稿 store，以及提交客户端 |
+| `packages/host/apiproxy` | 类型化的活动 Surface 读取／提交／关闭传输、用户消息来源扩展和排队来源传递；将校验与接纳委托给 Task Surface 服务 |
+
+该实现依赖现有的消息日志、规范工具输出、带标签的 render intent、会话投影、按会话作用域声明的 slot store 和 slot 生命周期，不依赖在运行时创建客户端插件。Generated Client Plugin 工作流可以使用 Task Surface 展示审阅表单，但两个协议都不拥有或激活另一个协议。
+
+## 交付阶段
+
+1. 实现模型／解析器、投影单元、`show_task_surface`、呈现元数据、静态 Web 行，以及带只读块的通用回退。
+2. 增加字段、持久化草稿、经 Host 校验的提交／关闭、排队来源传递，以及可见用户消息接纳。
+3. 只增加有实际任务依据，并且拥有至少两个消费方或明确通用回退的组件类型。一个单独的显式用户操作可以启动生成式插件编写工作流，但只会创建候选项，绝不会直接推广代码。
+
+## 考虑过的替代方案
+
+**增加产品专用触发方式和面板。**不予采用，因为每种新任务形态都会把 agent 行为与已发布的产品组件耦合。产品代码应当定义一套接纳的组件词汇和放置策略；agent 则显式地从中选择。
+
+**从工具调用中渲染任意 HTML、CSS 或 JavaScript。**不予采用，因为这会把临时交互变成可执行的客户端插件代码，却不具备代码所需的构建、预览、评估、批准或回滚生命周期。
+
+**使用大型表单扩展 `userInteraction.ask()`。**本契约不采用这种做法。`ask()` 是一种阻塞式请求／响应操作，适用于正在运行的工具必须先获得简短答案才能继续执行的情况。Task Surface 会结束当前轮次，可以在刷新后继续保持打开，并把结果提交为下一条可见用户消息。
+
+**每次调用都注册一个动态 `conversation.view`。**不予采用，因为视图账本是全局的，而其渲染作用域按会话划分；同时，临时任务身份会变成注册身份。单个静态带 key 的 toolview 会将调用实例数据保留在归属它的已记录调用中。
+
+**只在规范工具值中保留模型。**不予采用，因为规范值不会持久化。回放要求将规范化模型写入 `presentationMeta`。
+
+**将面板存入长期记忆。**不予采用，因为布局和草稿状态不是可复用事实。现有记忆策略可以保留用户提交的结论。
+
+## 验收标准
+
+- 在 `native` 或 `both` 工具模式下，真实模型可以调用一个稳定的 `show_task_surface` schema；调用结束当前轮次；具备相应能力的 Web 客户端在实时运行和回放后都能渲染同一份规范化模型；仅支持 `code` 的模式不会向模型公布该工具。
+- 每个 `submissionId` 的提交操作恰好生成一条可见用户消息，通过普通队列接纳开始下一轮，并在保留 `source.kind: 'user'` 的同时维持对确切调用实例的关联；关闭操作记录一条日志事件，且不启动轮次。
+- 刷新、重新连接、会话切换、fork 和回退都生成日志所决定的生命周期状态；`getActive` 可以恢复历史尾段之外的模型，任何面板都不会泄漏到其他会话。
+- 不受支持的版本、格式错误的元数据以及客户端能力缺失时，系统回退到带普通消息绕过路径的可读工具结果内容；嵌套调用以及已有另一个活动 Surface 时发起的调用都无法打开 Surface，并以失败结束。
+- 解析器会在面板可交互前强制校验 ID、联合类型形态、字段值以及配置的字节数和数量限制。
+- 组件测试覆盖纯键盘操作、焦点恢复、无障碍名称、窄屏布局、两种主题，以及中英文产品界面。
+- 无密钥浏览器组合测试覆盖显示、编辑、接纳被拒后的重试、排队／丢弃提交、持久提交、关闭、刷新恢复和双重提交幂等性。
+- 前缀快照表明：无论任务特定模型如何变化，都只存在一个稳定的工具定义；只有调用参数和后续用户结论发生变化。
+- 卸载 Web 插件时，其所属 Fiber 会对工具行和草稿 store 执行 dispose（资源释放），但不会改变持久 transcript。
+
+## 风险
+
+第一批组件可能小到无法满足实际任务，也可能大到足以演变成一个粗糙的应用框架。是否新增组件应由使用证据决定；v1 不提供表达式语言或网络行为。
+
+即使设置了字节限制，大型表格和 Markdown 仍可能生成开销较高的 DOM。渲染器必须按需虚拟化或截断内容，同时保留可读回退和明确计数。
+
+填写字段较多时，由产品格式化的提交消息可能过长。格式化器需要使用确定性的紧凑格式，保留每一个提交值，同时避免重复完整显示模型。
+
+浏览器本地持久化的草稿可能保留敏感的未提交文本。store 需要遵守规定的字节上限、使用按会话划分的 key、在提交成功后显式清除，并采用与现有会话草稿相同的存储策略。

From 652f3b61bfa8124f3115a4827624ee8936f3c8a7 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Wed, 5 Aug 2026 00:56:18 -0700
Subject: [PATCH 035/516] docs: tighten Task Surface lifecycle contract

---
 .../feature/2026-08-04-task-surface.i18n.yaml |   4 +-
 .../feature/2026-08-04-task-surface.md        | 127 ++++++++++++-----
 .../feature/2026-08-04-task-surface.zh.md     | 129 +++++++++++++-----
 3 files changed, 187 insertions(+), 73 deletions(-)

diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml b/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
index 36e7d8c5d6..fec93e2c36 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.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 .agents/notes/proposed/feature/2026-08-04-task-surface.md
-2026-08-04-task-surface.md: 780d5d884c83ab47535fff95efcd80b0b7f0181f
-2026-08-04-task-surface.zh.md: 38e6787ee5a4d86261e79c66d99f81614bdb5871
+2026-08-04-task-surface.md: 0d79d7b830689a269d1aede937fba6aa647ea483
+2026-08-04-task-surface.zh.md: 7960c02dc3c112a8cd1ff626274dfac1f01f1bdb
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
index 780d5d884c..0d79d7b830 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.md
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
@@ -44,11 +44,14 @@ interface TaskSurfaceModelV1 {
 interface TaskSurfaceSection {
   id: string
   title?: string
-  layout?: 'stack' | 'grid'
-  columns?: 2 | 3
+  layout?: TaskSurfaceLayout
   blocks: TaskSurfaceBlock[]
 }
 
+type TaskSurfaceLayout =
+  | { kind: 'stack' }
+  | { kind: 'grid'; columns: 2 | 3 }
+
 type TaskSurfaceBlock =
   | { kind: 'markdown'; text: string }
   | { kind: 'metrics'; items: { label: string; value: string; detail?: string }[] }
@@ -66,7 +69,9 @@ type TaskSurfaceField =
 interface TaskSurfaceOption { id: string; label: string; detail?: string }
 ```
 
-The renderer controls typography, spacing, responsive layout, focus order, keyboard behavior, and theme tokens. `grid` is a layout hint: it collapses when the available width cannot support the requested columns. Markdown uses the product's supported Markdown subset. Unknown versions or union arms use the generic tool-result fallback instead of partial interpretation.
+The renderer controls typography, spacing, responsive layout, focus order, keyboard behavior, and theme tokens. An absent layout means `stack`; a `grid` layout owns its column count and collapses when the available width cannot support it. Unknown versions or union arms use the generic tool-result fallback instead of partial interpretation.
+
+The `markdown` block reuses `MarkdownText` with an explicit model-URL policy. `MarkdownText` gains `remoteImages: 'render' | 'alt-only'`, preserving `render` as its ordinary default; Task Surface always passes `alt-only`, so image syntax renders only its alt text. Raw HTML and embedded media remain omitted, automatic link previews are absent, and no model-supplied URL is dereferenced without explicit user activation. Ordinary HTTP(S) links may still navigate when the user chooses them. Fixed application assets such as syntax-highlighting chunks remain under the product's normal loading policy.
 
 Version 1 deliberately omits conditional fields, client-side data fetching, charts, file uploads, and arbitrary event handlers. A new block or field kind is a protocol change with a parser, renderer, accessibility behavior, fallback, and replay fixture in the same change.
 
@@ -76,62 +81,83 @@ Limits are schema-backed configuration on the Task Surface service. The initial
 
 `show_task_surface` accepts `{ model: TaskSurfaceModelV1 }`. The Host parses and normalizes the complete model, rejects the call when that Session already has an open Task Surface, mints `surfaceId`, and returns canonical `{ surfaceId, model }` with the normalized model. `presentationMeta` persists `value.model`, so the projector and executor cannot disagree about normalization. The Native result names the Surface and explains that an ordinary message bypasses it when the client cannot render the panel. The tool then calls `exec.concludeTurn()` so the agent does not continue past the requested human checkpoint.
 
-The tool definition sets `exclusive: true`, and the tool is composed only in Web profiles that mount both the Host service and Web renderer. Version 1 supports `native` and `both` tool modes; a `code`-only profile does not advertise it because Code Mode dispatch is nested and cannot carry its presentation metadata to the outer result.
+The tool definition omits `isConcurrencySafe`. Under the existing tool-registry contract, omission classifies every call as an exclusive ordering barrier; no new `ToolDefinition` field is introduced. The tool is composed only in Web profiles that mount both the Host service and Web renderer. Version 1 supports `native` and `both` tool modes; a `code`-only profile does not advertise it because Code Mode dispatch is nested and cannot carry its presentation metadata to the outer result.
 
-The canonical value is execution-local under the [canonical tool output contract](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md). Replay therefore uses `output.presentationMeta(args, value)` to persist this tagged payload with `tool/result.meta`:
+The browser-safe domain package imports the type-only `Branded` primitive from `@deepseek-ai/dsh-brand` and owns all three Task Surface IDs. The canonical value is execution-local under the [canonical tool output contract](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md). Replay therefore uses `output.presentationMeta(args, value)` to persist this tagged payload with `tool/result.meta`:
 
 ```ts ignore-check
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+type TaskSurfaceId = Branded<'TaskSurfaceId'>
+type TaskSurfaceSubmissionId = Branded<'TaskSurfaceSubmissionId'>
+type TaskSurfaceDismissalId = Branded<'TaskSurfaceDismissalId'>
+
 interface TaskSurfacePresentationMeta {
   kind: 'dsh/task-surface'
   version: 1
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   model: TaskSurfaceModelV1
 }
 ```
 
 The tool keeps a generic [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md). The keyed Web row reads the tagged metadata already retained on `ToolResultNode`; no new render-intent arm or presentation registry is required. Clients without Task Surface support render the ordinary result content.
 
-The Web plugin statically registers one keyed `conversation.chat.toolview` entry for `show_task_surface`, following the [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) and [slot registration](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md) contracts. The row renders a compact summary when settled and expands the declarative panel inline. The model does not choose a conversation tab, details column, modal, pixel position, or z-index. A later placement change remains a renderer decision and does not alter logged models.
+The Web plugin has two static Session-scoped registrations under the [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) and [slot registration](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md) contracts. A keyed `conversation.chat.toolview` entry for `show_task_surface` renders the durable transcript occurrence as a compact summary and read-only replay. One `TaskSurfaceDock` entry in the existing `conversation.input.dock` is the only actionable mount: it reads the active projection, calls `getActive` for the exact identity, and owns fields, drafts, submit, and dismiss. Because the Dock is independent of transcript pagination, an active Surface remains actionable when its `ToolResultNode` is outside the loaded history window.
+
+The Dock follows the existing composer-chain fallback semantics. Any `conversation.composer` takeover hides the fallback composer stack, including `TaskSurfaceDock`, without unmounting it; the same draft owner reappears when the takeover resolves. A takeover does not receive Task Surface actions or create another editor.
+
+The model does not choose a conversation tab, dock order, details column, modal, pixel position, or z-index. A later placement change remains a renderer decision and does not alter logged models. The transcript row never becomes a second editor, so one Surface cannot acquire competing draft or submission owners.
 
 ## Submission contract
 
 The Task Surface domain exposes three operations through the Host transport. `submit` is the only one that admits a user message:
 
 ```ts ignore-check
-type TaskSurfaceSubmissionId = string & { readonly __brand: 'TaskSurfaceSubmissionId' }
-type TaskSurfaceDismissalId = string & { readonly __brand: 'TaskSurfaceDismissalId' }
+type TaskSurfaceSubmissionPhase = 'queued' | 'claiming'
+
+interface TaskSurfacePendingSubmission {
+  submissionId: TaskSurfaceSubmissionId
+  messageId: MessageId
+  phase: TaskSurfaceSubmissionPhase
+}
 
 interface TaskSurfaceService {
-  getActive(input: { sessionId: SessionId; surfaceId: string }): Promise<GetActiveTaskSurfaceResult>
+  getActive(input: { sessionId: SessionId; surfaceId: TaskSurfaceId }): Promise<GetActiveTaskSurfaceResult>
   submit(input: SubmitTaskSurfaceRequest): Promise<SubmitTaskSurfaceResult>
   dismiss(input: DismissTaskSurfaceRequest): Promise<DismissTaskSurfaceResult>
 }
 
 interface SubmitTaskSurfaceRequest {
   sessionId: SessionId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   submissionId: TaskSurfaceSubmissionId
   values: Record<string, JsonValue>
   note?: string
 }
 
 type SubmitTaskSurfaceResult =
-  | { accepted: true; messageId: MessageId }
-  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' }
+  | { accepted: true; messageId: MessageId; phase: 'queued' }
+  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' | 'submission-pending' }
 
 type GetActiveTaskSurfaceResult =
-  | { active: true; callId: CallId; surfaceId: string; model: TaskSurfaceModelV1 }
+  | {
+      active: true
+      callId: CallId
+      surfaceId: TaskSurfaceId
+      model: TaskSurfaceModelV1
+      pending: TaskSurfacePendingSubmission | null
+    }
   | { active: false; reason: 'not-open' }
 
 interface DismissTaskSurfaceRequest {
   sessionId: SessionId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   dismissalId: TaskSurfaceDismissalId
 }
 
 type DismissTaskSurfaceResult =
   | { dismissed: true; eventSeq: number }
-  | { dismissed: false; reason: 'not-open' | 'stale' }
+  | { dismissed: false; reason: 'not-open' | 'stale' | 'submission-pending' }
 ```
 
 The Host resolves the exact successful `show_task_surface` occurrence, revalidates the submitted values against its persisted model, and admits the response through the normal Session queue. The response becomes a user-role message with a merge-extensible source:
@@ -141,7 +167,7 @@ interface TaskSurfaceCorrelation {
   version: 1
   submissionId: TaskSurfaceSubmissionId
   callId: CallId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   values: Record<string, JsonValue>
 }
 
@@ -152,13 +178,31 @@ interface TaskSurfaceUserMessageSource {
 }
 ```
 
-The browser-safe domain package owns `TaskSurfaceCorrelation` and its branded `submissionId`. ApiProxy owns the transport augmentation that combines it with `rpcId`. Keeping `kind: 'user'` preserves the ordinary user bubble and prompt semantics while the extra field provides durable correlation. The message content is a product-formatted readable summary: panel title, labels and submitted values, plus the optional note. The model receives that same text. The structured source is not a second hidden instruction.
+The `session/queue` wire item already carries the complete `Message`. The client projection is explicitly extended to retain its source instead of dropping the correlation:
 
-The product shell owns collapse and dismiss. Collapse is local view state and sends nothing. `taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` appends one `task-surface/dismissed` Session event and does not start a turn; the exact event closes the projection and updates the transcript row. Retries reuse `dismissalId` and return the original result without appending another event.
+```ts ignore-check
+interface QueuedMessage {
+  id: InboxItemId
+  messageId: MessageId
+  placement: 'queued' | 'steering'
+  source: MessageSource
+  content: readonly ContentBlock[]
+  preview: string
+  text: string | null
+}
+```
 
-Submission is transactional at the client boundary. The panel disables submit while admission is in flight and clears the persisted draft only after the matching user message becomes durable. A rejection keeps the values editable and shows the returned reason. Double clicks and transport retries reuse `submissionId`; the Host admits one user message for one accepted Surface.
+The browser-safe domain package owns `TaskSurfaceId`, the submission and dismissal IDs, `TaskSurfaceCorrelation`, and the pending-submission shape. ApiProxy owns the transport augmentation that combines the correlation with `rpcId`. Keeping `kind: 'user'` preserves the ordinary user bubble and prompt semantics while the extra field provides durable correlation. The message content is a product-formatted readable summary: panel title, labels and submitted values, plus the optional note. The model receives that same text. The structured source is not a second hidden instruction.
 
-There is a short interval between queue admission and the durable `user/message`. The generic queued-message DTO therefore retains `Message.source`. A queued message with matching Task Surface correlation keeps the panel disabled; if that queue item is discarded, the pending state clears and the draft becomes editable again. The Host holds a process-local single-flight claim for the same interval, then releases it on commit, rejection, or discard. The queue is coordination state, not a second durable lifecycle record.
+The product shell owns collapse and dismiss. Collapse is local view state and sends nothing. When no submission is pending, `taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` appends one `task-surface/dismissed` Session event and does not start a turn; the exact event closes the projection and updates the Dock and transcript row. Retries reuse `dismissalId` and return the original result without appending another event. Dismiss is disabled while a submission is `queued` or `claiming`, and the Host rejects such a request with `submission-pending`.
+
+Submission is transactional at the client boundary. Acceptance returns the exact `messageId` in phase `queued`; the Dock disables every mutation through both `queued` and `claiming` and clears the persisted draft only after the matching user message becomes durable. A rejection keeps the values editable and shows the returned reason. Double clicks and transport retries reuse `submissionId` and return the first result; another submission ID receives `submission-pending` while the first is live. The Host admits one user message for one accepted Surface.
+
+The Task Surface service records accepted submission coordination as `pending.phase: 'queued'`, while the client can correlate the still-present queue row through its retained `source`. When the Agent dequeues that occurrence for ordinary prompt admission, the service synchronously changes the same pending record to `claiming` before ApiProxy publishes the ordinary queue snapshot without the claimed row. The service keeps that process-local claim across asynchronous admission and reconnect until a matching durable `user/message` is published or the Agent reports a terminal discard.
+
+The matching `user/message` closes the durable projection and clears the claim. Rejection, cancellation, or disposal before durability reports the discard, clears the claim, and leaves the Surface open. The Dock never interprets queue-row disappearance as either outcome: it re-reads `getActive`; `pending.phase: 'claiming'` stays disabled, `pending: null` restores the draft, and `not-open` closes the Dock. `getActive` joins the log-derived active occurrence with this one process-local pending record. The record is coordination state, not a second durable authority; after a Host restart, an uncommitted claim is absent and the still-open logged Surface becomes editable again.
+
+`session.updateQueue` rejects `edit` and `steer` for a Task Surface-correlated row. Editing would separate formatted content from its source-carried structured values, and steering would persist a `steering/message` that does not satisfy the submission lifecycle. `remove` is allowed while the row is queued; it reports the discard and restores the open Surface. Once claimed, the row has left the generic queue and queue mutations return `queue-item-not-found`. The Task Surface service holds one single-flight pending record until commit or discard.
 
 ## Lifecycle and recovery
 
@@ -166,13 +210,13 @@ The Session log is the authority. A small `taskSurface` unit in the existing [Se
 
 ```ts ignore-check
 interface TaskSurfaceProjection {
-  active: { callId: CallId; surfaceId: string } | null
+  active: { callId: CallId; surfaceId: TaskSurfaceId } | null
 }
 ```
 
-One Session has at most one open Task Surface. A successful result opens it. A matching Task Surface user message or dismissal event closes it. A later ordinary user message also closes it as an explicit bypass; another `show_task_surface` call fails until one of those events closes the active occurrence. Rewind and fork derive their active occurrence by folding the resulting log; no separate Surface database participates.
+One Session has at most one open Task Surface. A successful result opens it. A matching Task Surface user message or dismissal event closes it. A later ordinary user message also closes it as an explicit bypass; another `show_task_surface` call fails until one of those events closes the active occurrence. Rewind and fork derive their active occurrence by folding the resulting log; transient queue phase is not copied, and no separate Surface database participates.
 
-The full model remains on its `tool/result.meta`; the projection carries only the active identity. When that result is outside the loaded history window, `taskSurface.getActive({ sessionId, surfaceId })` reads the exact occurrence from the Session log and returns `{ callId, surfaceId, model }` after revalidating the metadata. A missing or closed occurrence returns `not-open`. Refresh and reconnect therefore do not depend on the active result fitting in the history tail and do not duplicate the model into every projection baseline.
+The full model remains on its `tool/result.meta`; the projection carries only the active identity. `TaskSurfaceDock` exists independently of history rows and reacts to that identity. `taskSurface.getActive({ sessionId, surfaceId })` reads the exact occurrence from the Session log, revalidates its metadata, joins the Task Surface service's pending coordination record, and returns `{ callId, surfaceId, model, pending }`. A missing or closed occurrence returns `not-open`. Refresh and reconnect therefore recover an actionable Surface and its same-process pending phase even when the result is outside the history tail, without copying the model into every projection baseline.
 
 The Web plugin keeps unsubmitted values in a bounded, per-Session persisted slot store keyed by `surfaceId`; they never enter the Session log, prompt, or long-term memory. Submitted values live in the accepted user message, so losing a browser draft cannot erase a conclusion.
 
@@ -182,17 +226,22 @@ The capability is split where ownership changes:
 
 | Package | Responsibility |
 |---|---|
-| `packages/task-surface/task-surface` | Browser-safe model/types and correlation, parser, limits, submission validator/formatter, Session event extension, projection unit, and Host service contract |
+| `packages/core/agent` and `packages/core/agent-loop` | Generic terminal outcome for a claimed next-turn inbox occurrence, allowing a Host observer to distinguish durable admission from discard without Task Surface-specific types |
+| `packages/task-surface/task-surface` | Browser-safe model, branded IDs, correlation and pending types, parser, limits, submission validator/formatter, Session event extension, projection unit, and Host service contract |
 | `packages/task-surface/tool-task-surface` | `show_task_surface`, canonical output, presentation metadata, generic render intent, active-Surface check, and `concludeTurn()` behavior |
-| `packages/client/ui-task-surface` | Static keyed tool row, declarative Web renderer, per-Session draft store, and submit client |
-| `packages/host/apiproxy` | Typed active-read/submit/dismiss transport, user-source augmentation, and queued-source carriage; delegates validation and admission to the Task Surface service |
+| `packages/client/runtime` | Generic queued-message `source` projection and Session-scoped active-projection access |
+| `packages/client/ui-primitives` | Task Surface-agnostic `MarkdownText.remoteImages` policy, including the `alt-only` image branch and URL-policy tests |
+| `packages/client/ui-task-surface` | Static actionable `TaskSurfaceDock`, read-only keyed transcript row, declarative Web renderer that consumes the Task Surface model and `MarkdownText` in `alt-only` mode, per-Session draft store, and submit client |
+| `packages/host/apiproxy` | Typed active-read/submit/dismiss transport, user-source augmentation and carriage, queue-action restrictions, and routing of claim and terminal outcomes; delegates validation, pending coordination, and admission to the Task Surface service |
+
+`ui-task-surface` depends on the browser-safe Task Surface domain, client connection and runtime, locale, `ui-conversation` for the declared slot contracts, `ui-slots` for registration, and `ui-primitives`; `ui-primitives` does not depend on Task Surface. ApiProxy depends on the Task Surface service contract and the generic AgentLoop terminal outcome. Core Agent packages do not import Task Surface types.
 
 The implementation depends on the existing message log, canonical tool output, tagged render intents, Session projection, per-Session declared slot stores, and slot lifecycle. It does not depend on runtime Client Plugin creation. The generated Client Plugin workflow may use Task Surface to present a review form, but neither protocol owns or activates the other.
 
 ## Delivery stages
 
-1. Land the model/parser, projection unit, `show_task_surface`, presentation metadata, static Web row, and generic fallback with read-only blocks.
-2. Add fields, persisted drafts, Host-validated submit/dismiss, queued-source carriage, and visible user-message admission.
+1. Land the model/parser, `MarkdownText` model-URL policy, projection unit, `show_task_surface`, presentation metadata, read-only Web row, static `TaskSurfaceDock`, active retrieval, and generic fallback with read-only blocks.
+2. Add fields, persisted drafts, Host-validated submit/dismiss, branded correlation, client queued-source carriage, Task Surface `queued`/`claiming` coordination, claimed-occurrence terminal reporting, queue-action restrictions, and visible user-message admission.
 3. Add only component kinds justified by real tasks and two consumers or a clear generic fallback. A separate explicit user action may start the generated Plugin authoring workflow, but it creates a candidate; it never promotes code directly.
 
 ## Alternatives considered
@@ -203,7 +252,7 @@ The implementation depends on the existing message log, canonical tool output, t
 
 **Extend `userInteraction.ask()` with a large form.** Rejected for this contract. `ask()` is a blocking request/response operation used when a running tool cannot continue without a short answer. A Task Surface ends the turn, may remain open across refreshes, and submits its result as the next visible user turn.
 
-**Register one dynamic `conversation.view` per call.** Rejected because the view ledger is global while its render scope is per Session, and because transient task identity would become registration identity. One static keyed toolview keeps occurrence data in the logged call where it belongs.
+**Register one dynamic `conversation.view` per call.** Rejected because the view ledger is global while its render scope is per Session, and because transient task identity would become registration identity. One static Session-scoped Dock owns interaction, and one static keyed row summarizes the logged occurrence; neither registration uses occurrence identity.
 
 **Keep the model only in the canonical tool value.** Rejected because canonical values are not persisted. Replay requires the normalized model in `presentationMeta`.
 
@@ -212,21 +261,29 @@ The implementation depends on the existing message log, canonical tool output, t
 ## Acceptance criteria
 
 - A real model in `native` or `both` mode can call one stable `show_task_surface` schema, the call ends its turn, and a capable Web client renders the same normalized model live and after replay; `code`-only mode does not advertise it.
-- Submitting produces exactly one visible user message per `submissionId`, starts the next turn through normal queue admission, and retains exact occurrence correlation while keeping `source.kind: 'user'`; dismissing records one log event and starts no turn.
-- Refresh, reconnect, Session switching, fork, and rewind produce the lifecycle state implied by the log; `getActive` recovers a model outside the history tail, and no panel leaks across Sessions.
+- The static `TaskSurfaceDock` is the only editor and remains actionable for an active result outside the loaded history window; the keyed toolview remains a read-only transcript summary and replay. A composer takeover hides the still-mounted Dock, preserves its draft, and reveals the same owner after release.
+- Submitting produces exactly one visible user message per `submissionId`, starts the next turn through normal queue admission, and retains exact branded occurrence correlation while keeping `source.kind: 'user'`; dismissing records one log event and starts no turn.
+- The queued client row retains the correlated message source. `getActive` exposes `queued` or `claiming` across same-process reconnect; commit closes the projection, while explicit discard clears pending state and leaves the Surface open. Queue-row disappearance alone changes no UI state. Edit and steer are rejected, and remove succeeds only before claim.
+- Refresh, reconnect, Session switching, fork, and rewind produce the lifecycle state implied by the log; `getActive` recovers the model and pending phase outside the history tail, and no panel, pending state, or draft leaks across Sessions.
 - Unsupported versions, malformed metadata, and absent client capability fall back to readable tool-result content with the ordinary-message bypass; nested calls and calls made while another Surface is active fail without opening a Surface.
-- The parser enforces IDs, union shapes, field values, and configured byte/count limits before the panel becomes actionable.
+- Wire schemas validate ID strings and domain APIs expose the branded ID types throughout. The model parser enforces tagged layout shapes, field values, and configured byte/count limits before the panel becomes actionable. Browser tests show image syntax becomes alt text, raw HTML and embedded media do not render, and no model-supplied URL is requested before explicit user activation.
 - Keyboard-only operation, focus restoration, accessible names, narrow layouts, both themes, and zh/en product chrome are covered by component tests.
-- Keyless browser composition covers show, edit, retry after rejected admission, queued/discarded submission, durable submit, dismiss, refresh recovery, and double-submit idempotency.
+- Keyless browser composition covers show, Dock and read-only-row ownership, off-window recovery, edit, retry after rejected admission, queued-to-claiming transition, discard, durable handoff without an editable gap, forbidden queue actions, dismiss, reconnect, and double-submit idempotency.
 - Prefix snapshots show one stable tool definition regardless of the task-specific model; only the call arguments and later user conclusion vary.
-- Unloading the Web plugin disposes its row and draft stores through the owning Fiber without changing the durable transcript.
+- Unloading the Web plugin disposes its Dock, row, and draft stores through the owning Fiber without changing the durable transcript.
 
 ## Risks
 
 The first component set may be either too small for useful tasks or broad enough to become a weak application framework. Usage evidence should decide additions; v1 has no expression language or network behavior.
 
+The Task Surface Markdown policy gives up inline images, media, and automatic link previews. Ordinary links remain useful, but only an explicit user activation may navigate or start a request.
+
 Large tables and Markdown can still create expensive DOM even inside byte limits. The renderer must virtualize or truncate where needed while preserving a readable fallback and explicit counts.
 
 A product-formatted submission can become verbose when many fields are filled. The formatter needs a deterministic compact form and must preserve every submitted value without repeating the complete display model.
 
+Holding a process-local claim until durable handoff adds a terminal-state invariant. Every admission exit must produce either the matching `user/message` or an explicit discard; otherwise a reconnect could retain a disabled Dock indefinitely.
+
 Browser-local draft persistence can retain sensitive unsubmitted text. The store needs the stated byte bound, per-Session keys, explicit clearing after acceptance, and the same storage posture as the existing conversation draft.
+
+The Dock and transcript row show the same occurrence in different roles. Keeping the row read-only and the Dock as the sole mutation owner prevents conflicting drafts at the cost of a second compact representation while the Surface is active.
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
index 38e6787ee5..7960c02dc3 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
@@ -44,11 +44,14 @@ interface TaskSurfaceModelV1 {
 interface TaskSurfaceSection {
   id: string
   title?: string
-  layout?: 'stack' | 'grid'
-  columns?: 2 | 3
+  layout?: TaskSurfaceLayout
   blocks: TaskSurfaceBlock[]
 }
 
+type TaskSurfaceLayout =
+  | { kind: 'stack' }
+  | { kind: 'grid'; columns: 2 | 3 }
+
 type TaskSurfaceBlock =
   | { kind: 'markdown'; text: string }
   | { kind: 'metrics'; items: { label: string; value: string; detail?: string }[] }
@@ -66,7 +69,9 @@ type TaskSurfaceField =
 interface TaskSurfaceOption { id: string; label: string; detail?: string }
 ```
 
-渲染器控制字体排印、间距、响应式布局、焦点顺序、键盘行为和主题 token。`grid` 是布局提示：可用宽度无法容纳所要求的列数时，渲染器会将其折叠。Markdown 使用产品支持的 Markdown 子集。遇到未知版本或联合类型分支时，系统使用通用工具结果回退，而不是只解释其中一部分。
+渲染器控制字体排印、间距、响应式布局、焦点顺序、键盘行为和主题 token。未指定布局时使用 `stack`；`grid` 布局自带列数，可用宽度无法容纳时会折叠。遇到未知版本或联合类型分支时，系统使用通用工具结果回退，而不是只解释其中一部分。
+
+`markdown` 块复用 `MarkdownText`，并显式指定模型 URL 策略。`MarkdownText` 新增 `remoteImages: 'render' | 'alt-only'`，普通场景仍默认使用 `render`；Task Surface 始终传入 `alt-only`，因此图片语法只渲染替代文本。原始 HTML 和嵌入式媒体仍会被省略，不生成自动链接预览；未经用户显式操作，不会解引用模型提供的任何 URL。普通 HTTP(S) 链接仍可在用户选择后导航。语法高亮分片等固定应用资源继续遵循产品的常规加载策略。
 
 版本 1 有意不支持条件字段、客户端数据获取、图表、文件上传和任意事件处理器。新增任何块或字段类型都属于协议变更，必须在同一变更中加入解析器、渲染器、无障碍行为、回退方式和回放 fixture（测试前置数据）。
 
@@ -76,62 +81,83 @@ Task Surface 服务通过受 schema 校验的配置定义限制。初始默认
 
 `show_task_surface` 接收 `{ model: TaskSurfaceModelV1 }`。Host 解析并规范化完整模型；若该会话已有一个打开的 Task Surface，则拒绝调用；否则生成 `surfaceId`，并返回带规范化模型的规范值 `{ surfaceId, model }`。`presentationMeta` 持久化 `value.model`，使投影器和执行器不会对规范化结果产生分歧。Native 结果会指明该 Surface，并说明客户端无法渲染面板时，可以通过普通消息绕过它。随后工具调用 `exec.concludeTurn()`，防止 agent 越过所要求的人工检查点继续执行。
 
-工具定义设置 `exclusive: true`，并且只会组装到同时挂载 Host 服务和 Web 渲染器的 Web profile 中。版本 1 支持 `native` 和 `both` 工具模式；仅支持 `code` 的 profile 不会向模型公布该工具，因为 Code Mode 分发属于嵌套调用，无法把呈现元数据传到外层结果。
+工具定义省略 `isConcurrencySafe`。根据现有工具注册表契约，省略该字段会将每次调用归类为独占排序屏障，无需新增 `ToolDefinition` 字段。该工具只会组装到同时挂载 Host 服务和 Web 渲染器的 Web profile 中。版本 1 支持 `native` 和 `both` 工具模式；仅支持 `code` 的 profile 不会向模型公布该工具，因为 Code Mode 分发属于嵌套调用，无法把呈现元数据传到外层结果。
 
-根据[规范工具输出契约](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
+浏览器安全的领域包从 `@deepseek-ai/dsh-brand` 以仅类型方式导入 `Branded` 原语，并拥有全部三个 Task Surface ID。根据[规范工具输出契约](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
 
 ```ts ignore-check
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+type TaskSurfaceId = Branded<'TaskSurfaceId'>
+type TaskSurfaceSubmissionId = Branded<'TaskSurfaceSubmissionId'>
+type TaskSurfaceDismissalId = Branded<'TaskSurfaceDismissalId'>
+
 interface TaskSurfacePresentationMeta {
   kind: 'dsh/task-surface'
   version: 1
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   model: TaskSurfaceModelV1
 }
 ```
 
 该工具保留通用 [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md)。带 key 的 Web 行读取 `ToolResultNode` 上已经保留的带标签元数据，无需新增 render-intent 分支或呈现注册表。不支持 Task Surface 的客户端会渲染普通结果内容。
 
-Web 插件遵循 [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) 和 [slot 注册](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md)契约，为 `show_task_surface` 静态注册一个带 key 的 `conversation.chat.toolview` 条目。结算后，该行显示简洁摘要，并在行内展开声明式面板。模型不能选择会话标签页、详情栏、模态框、像素位置或 z-index。以后即使改变放置位置，也只是渲染器的决策，不会改变日志中记录的模型。
+Web 插件按照 [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) 和 [slot 注册](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md)契约，提供两个静态的会话作用域注册项。一个以 `show_task_surface` 为 key 的 `conversation.chat.toolview` 条目将持久 transcript（文本记录）调用实例渲染为简洁摘要和只读回放。现有 `conversation.input.dock` 中的一个 `TaskSurfaceDock` 条目是唯一可操作的挂载点：它读取活动投影，针对确切身份调用 `getActive`，并拥有字段、草稿、提交和关闭操作。Dock 与 transcript 分页相互独立，因此即使 `ToolResultNode` 位于已加载历史窗口之外，活动 Surface 仍可操作。
+
+Dock 遵循现有 composer chain 的回退语义。任何 `conversation.composer` 接管都会隐藏包括 `TaskSurfaceDock` 在内的回退 composer 栈，但不会将其卸载；接管结束后，同一个草稿所有者会重新出现。接管方不会获得 Task Surface 操作，也不会创建另一个编辑器。
+
+模型不能选择会话标签页、Dock 顺序、详情栏、模态框、像素位置或 z-index。以后即使改变放置位置，也只是渲染器的决策，不会改变日志中记录的模型。transcript 行绝不会成为第二个编辑器，因此同一个 Surface 不会出现相互竞争的草稿或提交所有者。
 
 ## 提交契约
 
 Task Surface 领域通过 Host 传输层公开三个操作。只有 `submit` 会接纳用户消息：
 
 ```ts ignore-check
-type TaskSurfaceSubmissionId = string & { readonly __brand: 'TaskSurfaceSubmissionId' }
-type TaskSurfaceDismissalId = string & { readonly __brand: 'TaskSurfaceDismissalId' }
+type TaskSurfaceSubmissionPhase = 'queued' | 'claiming'
+
+interface TaskSurfacePendingSubmission {
+  submissionId: TaskSurfaceSubmissionId
+  messageId: MessageId
+  phase: TaskSurfaceSubmissionPhase
+}
 
 interface TaskSurfaceService {
-  getActive(input: { sessionId: SessionId; surfaceId: string }): Promise<GetActiveTaskSurfaceResult>
+  getActive(input: { sessionId: SessionId; surfaceId: TaskSurfaceId }): Promise<GetActiveTaskSurfaceResult>
   submit(input: SubmitTaskSurfaceRequest): Promise<SubmitTaskSurfaceResult>
   dismiss(input: DismissTaskSurfaceRequest): Promise<DismissTaskSurfaceResult>
 }
 
 interface SubmitTaskSurfaceRequest {
   sessionId: SessionId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   submissionId: TaskSurfaceSubmissionId
   values: Record<string, JsonValue>
   note?: string
 }
 
 type SubmitTaskSurfaceResult =
-  | { accepted: true; messageId: MessageId }
-  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' }
+  | { accepted: true; messageId: MessageId; phase: 'queued' }
+  | { accepted: false; reason: 'not-open' | 'stale' | 'invalid-submission' | 'submission-pending' }
 
 type GetActiveTaskSurfaceResult =
-  | { active: true; callId: CallId; surfaceId: string; model: TaskSurfaceModelV1 }
+  | {
+      active: true
+      callId: CallId
+      surfaceId: TaskSurfaceId
+      model: TaskSurfaceModelV1
+      pending: TaskSurfacePendingSubmission | null
+    }
   | { active: false; reason: 'not-open' }
 
 interface DismissTaskSurfaceRequest {
   sessionId: SessionId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   dismissalId: TaskSurfaceDismissalId
 }
 
 type DismissTaskSurfaceResult =
   | { dismissed: true; eventSeq: number }
-  | { dismissed: false; reason: 'not-open' | 'stale' }
+  | { dismissed: false; reason: 'not-open' | 'stale' | 'submission-pending' }
 ```
 
 Host 解析出 `show_task_surface` 的确切成功调用实例，依据其已持久化模型重新校验提交值，并通过普通会话队列接纳响应。该响应成为一条用户角色消息，并使用可合并扩展的消息来源：
@@ -141,7 +167,7 @@ interface TaskSurfaceCorrelation {
   version: 1
   submissionId: TaskSurfaceSubmissionId
   callId: CallId
-  surfaceId: string
+  surfaceId: TaskSurfaceId
   values: Record<string, JsonValue>
 }
 
@@ -152,13 +178,31 @@ interface TaskSurfaceUserMessageSource {
 }
 ```
 
-浏览器安全的领域包拥有 `TaskSurfaceCorrelation` 及其带品牌类型的 `submissionId`。ApiProxy 拥有传输扩展，负责将其与 `rpcId` 组合。保留 `kind: 'user'` 可维持普通用户消息气泡和提示词语义，额外字段则提供持久关联信息。消息内容是由产品格式化的可读摘要，包括面板标题、标签和提交值，以及可选备注。模型接收相同的文本。结构化来源不是第二条隐藏指令。
+`session/queue` 线上的条目已经携带完整 `Message`。客户端投影会显式扩展以保留其来源，不再丢失关联信息：
 
-产品外壳负责收起和关闭。收起属于本地视图状态，不会发送任何内容。`taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` 追加一个 `task-surface/dismissed` 会话事件，但不启动轮次；该精确事件会关闭投影并更新 transcript（文本记录）中的对应行。重试会复用 `dismissalId` 并返回原始结果，不会再追加一个事件。
+```ts ignore-check
+interface QueuedMessage {
+  id: InboxItemId
+  messageId: MessageId
+  placement: 'queued' | 'steering'
+  source: MessageSource
+  content: readonly ContentBlock[]
+  preview: string
+  text: string | null
+}
+```
 
-客户端边界上的提交具有事务性。接纳进行期间，面板会禁用提交；只有匹配的用户消息持久化后，才会清除已持久化的草稿。若请求被拒绝，则保留值供用户继续编辑，并显示返回的原因。双击和传输重试会复用 `submissionId`；对于一个已接受的 Surface，Host 只会接纳一条用户消息。
+浏览器安全的领域包拥有 `TaskSurfaceId`、提交和关闭 ID、`TaskSurfaceCorrelation`，以及待处理提交的形态。ApiProxy 拥有传输扩展，负责将关联信息与 `rpcId` 组合。保留 `kind: 'user'` 可维持普通用户消息气泡和提示词语义，额外字段则提供持久关联信息。消息内容是由产品格式化的可读摘要，包括面板标题、标签和提交值，以及可选备注。模型接收相同的文本。结构化来源不是第二条隐藏指令。
 
-队列接纳与 `user/message` 持久化之间存在一个短暂区间。因此，通用排队消息 DTO 会保留 `Message.source`。带有匹配 Task Surface 关联信息的排队消息会使面板维持禁用状态；如果该队列项被丢弃，待处理状态会清除，草稿恢复为可编辑状态。在同一区间，Host 会持有一个进程内 single-flight 占用，并在消息提交持久化、接纳被拒或队列项被丢弃时释放。队列属于协调状态，并不是第二份持久生命周期记录。
+产品外壳负责收起和关闭。收起属于本地视图状态，不会发送任何内容。没有待处理提交时，`taskSurface.dismiss({ sessionId, surfaceId, dismissalId })` 会追加一个 `task-surface/dismissed` 会话事件，但不启动轮次；该精确事件会关闭投影，并更新 Dock 和 transcript 行。重试会复用 `dismissalId` 并返回原始结果，不会再追加事件。提交处于 `queued` 或 `claiming` 阶段时，关闭操作会被禁用，Host 也会以 `submission-pending` 拒绝这类请求。
+
+客户端边界上的提交具有事务性。接纳成功会返回处于 `queued` 阶段的确切 `messageId`；在 `queued` 和 `claiming` 两个阶段中，Dock 会禁用所有变更，并且只有匹配的用户消息持久化后，才会清除已持久化的草稿。若请求被拒绝，则保留值供用户继续编辑，并显示返回的原因。双击和传输重试会复用 `submissionId` 并返回第一次调用的结果；只要第一次提交仍在处理中，另一个提交 ID 就会收到 `submission-pending`。对于一个已接受的 Surface，Host 只会接纳一条用户消息。
+
+Task Surface 服务将已接受提交的协调状态记录为 `pending.phase: 'queued'`，客户端则可通过仍在队列中的行所保留的 `source` 关联它。当 Agent 从队列取出该调用实例进行普通提示词接纳时，服务会先同步把同一份待处理记录改为 `claiming`，然后 ApiProxy 才发布不再包含已认领行的普通队列快照。服务会在异步接纳和重新连接期间一直保留这份进程内认领状态，直到匹配的持久 `user/message` 发布，或 Agent 报告终态丢弃。
+
+匹配的 `user/message` 会关闭持久投影并清除认领状态。在持久化之前发生拒绝、取消或 dispose（资源释放）时，系统会报告丢弃、清除认领状态，并让 Surface 保持打开。Dock 绝不会把队列行消失解读为其中任一结果，而会重新读取 `getActive`：`pending.phase: 'claiming'` 会维持禁用状态，`pending: null` 会恢复草稿，`not-open` 会关闭 Dock。`getActive` 会把由日志推导的活动调用实例与这唯一一份进程内待处理记录合并。该记录属于协调状态，不是第二个持久权威来源；Host 重启后，未提交的认领状态不复存在，日志中仍然打开的 Surface 会恢复为可编辑状态。
+
+对于带有 Task Surface 关联信息的行，`session.updateQueue` 会拒绝 `edit` 和 `steer`。编辑会让格式化内容与消息来源所携带的结构化值脱节，而 steering（中途引导）会持久化一条不符合提交生命周期的 `steering/message`。该行仍在队列中时允许 `remove`；它会报告丢弃并恢复为打开的 Surface。行被认领后即已离开通用队列，队列变更会返回 `queue-item-not-found`。Task Surface 服务会持有一份 single-flight 待处理记录，直至提交或丢弃。
 
 ## 生命周期与恢复
 
@@ -166,33 +210,38 @@ interface TaskSurfaceUserMessageSource {
 
 ```ts ignore-check
 interface TaskSurfaceProjection {
-  active: { callId: CallId; surfaceId: string } | null
+  active: { callId: CallId; surfaceId: TaskSurfaceId } | null
 }
 ```
 
-一个会话最多只能有一个打开的 Task Surface。成功的结果会打开它；匹配的 Task Surface 用户消息或关闭事件会将其关闭。后续的普通用户消息也会将其关闭，这是一条显式的绕过路径；在以上任一事件关闭活动调用实例前，再次调用 `show_task_surface` 都会失败。回退和 fork 会通过折叠相应日志推导出活动调用实例，不会使用独立的 Surface 数据库。
+一个会话最多只能有一个打开的 Task Surface。成功的结果会打开它；匹配的 Task Surface 用户消息或关闭事件会将其关闭。后续的普通用户消息也会将其关闭，这是一条显式的绕过路径；在以上任一事件关闭活动调用实例前，再次调用 `show_task_surface` 都会失败。回退和 fork 会通过折叠相应日志推导出活动调用实例；瞬态队列阶段不会被复制，也不会有独立的 Surface 数据库参与其中。
 
-完整模型仍存放在对应的 `tool/result.meta` 中；投影只携带活动身份。当该结果超出已加载的历史窗口时，`taskSurface.getActive({ sessionId, surfaceId })` 会从会话日志中读取确切调用实例，重新校验元数据后返回 `{ callId, surfaceId, model }`。调用实例不存在或已经关闭时返回 `not-open`。因此，刷新和重新连接不要求活动结果位于历史尾段，也无需把模型复制到每一个投影基线中。
+完整模型仍存放在对应的 `tool/result.meta` 中；投影只携带活动身份。`TaskSurfaceDock` 独立于历史行存在，并会响应该身份。`taskSurface.getActive({ sessionId, surfaceId })` 会从会话日志中读取确切调用实例，重新校验其元数据，合并 Task Surface 服务的待处理协调记录，并返回 `{ callId, surfaceId, model, pending }`。调用实例不存在或已经关闭时返回 `not-open`。因此，即使结果位于历史尾段之外，刷新和重新连接仍能恢复可操作的 Surface 及其同进程待处理阶段，而无需把模型复制到每一个投影基线中。
 
 Web 插件将未提交值保存在一个有界、按会话持久化的 slot store 中，并以 `surfaceId` 为 key；这些值永远不会进入会话日志、提示词或长期记忆。已提交值存放在接纳的用户消息中，因此即使浏览器草稿丢失，也不会抹去结论。
 
 ## 包边界与依赖
 
-该能力按职责变化处分包：
+该能力在职责变化处拆分为多个包：
 
 | 包 | 职责 |
 |---|---|
-| `packages/task-surface/task-surface` | 浏览器安全的模型／类型和关联信息、解析器、限制、提交校验器／格式化器、会话事件扩展、投影单元，以及 Host 服务契约 |
+| `packages/core/agent` 和 `packages/core/agent-loop` | 为已认领的下一轮 inbox 调用实例提供通用终态结果，让 Host 观察方无需使用 Task Surface 专用类型，即可区分持久接纳和丢弃 |
+| `packages/task-surface/task-surface` | 浏览器安全的模型、带品牌类型的 ID、关联和待处理类型、解析器、限制、提交校验器／格式化器、会话事件扩展、投影单元，以及 Host 服务契约 |
 | `packages/task-surface/tool-task-surface` | `show_task_surface`、规范输出、呈现元数据、通用 render intent、活动 Surface 检查和 `concludeTurn()` 行为 |
-| `packages/client/ui-task-surface` | 静态带 key 的工具行、声明式 Web 渲染器、按会话划分的草稿 store，以及提交客户端 |
-| `packages/host/apiproxy` | 类型化的活动 Surface 读取／提交／关闭传输、用户消息来源扩展和排队来源传递；将校验与接纳委托给 Task Surface 服务 |
+| `packages/client/runtime` | 通用排队消息 `source` 投影和会话作用域的活动投影访问 |
+| `packages/client/ui-primitives` | 与 Task Surface 无关的 `MarkdownText.remoteImages` 策略，包括 `alt-only` 图片分支和 URL 策略测试 |
+| `packages/client/ui-task-surface` | 静态且可操作的 `TaskSurfaceDock`、带 key 的只读 transcript 行、消费 Task Surface 模型并以 `alt-only` 模式使用 `MarkdownText` 的声明式 Web 渲染器、按会话划分的草稿 store，以及提交客户端 |
+| `packages/host/apiproxy` | 类型化的活动 Surface 读取／提交／关闭传输、用户消息来源扩展与传递、队列操作限制，以及认领和终态结果的路由；将校验、待处理协调和接纳委托给 Task Surface 服务 |
+
+`ui-task-surface` 依赖浏览器安全的 Task Surface 领域包、客户端连接与运行时、locale、`ui-conversation` 所声明的 slot 契约、用于注册的 `ui-slots`，以及 `ui-primitives`；`ui-primitives` 不反向依赖 Task Surface。ApiProxy 依赖 Task Surface 服务契约和通用 AgentLoop 终态结果。核心 Agent 包不导入 Task Surface 类型。
 
 该实现依赖现有的消息日志、规范工具输出、带标签的 render intent、会话投影、按会话作用域声明的 slot store 和 slot 生命周期，不依赖在运行时创建客户端插件。Generated Client Plugin 工作流可以使用 Task Surface 展示审阅表单，但两个协议都不拥有或激活另一个协议。
 
 ## 交付阶段
 
-1. 实现模型／解析器、投影单元、`show_task_surface`、呈现元数据、静态 Web 行，以及带只读块的通用回退。
-2. 增加字段、持久化草稿、经 Host 校验的提交／关闭、排队来源传递，以及可见用户消息接纳。
+1. 实现模型／解析器、`MarkdownText` 模型 URL 策略、投影单元、`show_task_surface`、呈现元数据、只读 Web 行、静态 `TaskSurfaceDock`、活动 Surface 读取，以及带只读块的通用回退。
+2. 增加字段、持久化草稿、经 Host 校验的提交／关闭、带品牌类型的关联信息、客户端排队来源传递、Task Surface `queued`/`claiming` 协调、已认领调用实例的终态报告、队列操作限制，以及可见用户消息接纳。
 3. 只增加有实际任务依据，并且拥有至少两个消费方或明确通用回退的组件类型。一个单独的显式用户操作可以启动生成式插件编写工作流，但只会创建候选项，绝不会直接推广代码。
 
 ## 考虑过的替代方案
@@ -203,7 +252,7 @@ Web 插件将未提交值保存在一个有界、按会话持久化的 slot stor
 
 **使用大型表单扩展 `userInteraction.ask()`。**本契约不采用这种做法。`ask()` 是一种阻塞式请求／响应操作，适用于正在运行的工具必须先获得简短答案才能继续执行的情况。Task Surface 会结束当前轮次，可以在刷新后继续保持打开，并把结果提交为下一条可见用户消息。
 
-**每次调用都注册一个动态 `conversation.view`。**不予采用，因为视图账本是全局的，而其渲染作用域按会话划分；同时，临时任务身份会变成注册身份。单个静态带 key 的 toolview 会将调用实例数据保留在归属它的已记录调用中。
+**每次调用都注册一个动态 `conversation.view`。**不予采用，因为视图账本是全局的，而其渲染作用域按会话划分；同时，临时任务身份会变成注册身份。一个静态的会话作用域 Dock 负责交互，一个静态带 key 的行概述已记录的调用实例；两个注册项都不使用调用实例身份。
 
 **只在规范工具值中保留模型。**不予采用，因为规范值不会持久化。回放要求将规范化模型写入 `presentationMeta`。
 
@@ -212,21 +261,29 @@ Web 插件将未提交值保存在一个有界、按会话持久化的 slot stor
 ## 验收标准
 
 - 在 `native` 或 `both` 工具模式下，真实模型可以调用一个稳定的 `show_task_surface` schema；调用结束当前轮次；具备相应能力的 Web 客户端在实时运行和回放后都能渲染同一份规范化模型；仅支持 `code` 的模式不会向模型公布该工具。
-- 每个 `submissionId` 的提交操作恰好生成一条可见用户消息，通过普通队列接纳开始下一轮，并在保留 `source.kind: 'user'` 的同时维持对确切调用实例的关联；关闭操作记录一条日志事件，且不启动轮次。
-- 刷新、重新连接、会话切换、fork 和回退都生成日志所决定的生命周期状态；`getActive` 可以恢复历史尾段之外的模型，任何面板都不会泄漏到其他会话。
+- 静态 `TaskSurfaceDock` 是唯一的编辑器，即使活动结果位于已加载历史窗口之外也仍可操作；带 key 的 toolview 始终是 transcript 的只读摘要和回放。composer 接管会隐藏仍处于挂载状态的 Dock、保留其草稿，并在接管释放后重新显示同一个所有者。
+- 每个 `submissionId` 的提交操作恰好生成一条可见用户消息，通过普通队列接纳开始下一轮，并在保留 `source.kind: 'user'` 的同时维持带品牌类型的确切调用实例关联；关闭操作记录一条日志事件，且不启动轮次。
+- 客户端排队行保留已关联的消息来源。`getActive` 可在同一进程的重新连接前后公开 `queued` 或 `claiming`；提交会关闭投影，显式丢弃则会清除待处理状态并让 Surface 保持打开。队列行消失本身不会改变任何 UI 状态。系统会拒绝编辑和 steering，且移除操作只能在认领前成功。
+- 刷新、重新连接、会话切换、fork 和回退都生成日志所决定的生命周期状态；`getActive` 可以恢复历史尾段之外的模型和待处理阶段，任何面板、待处理状态或草稿都不会泄漏到其他会话。
 - 不受支持的版本、格式错误的元数据以及客户端能力缺失时，系统回退到带普通消息绕过路径的可读工具结果内容；嵌套调用以及已有另一个活动 Surface 时发起的调用都无法打开 Surface，并以失败结束。
-- 解析器会在面板可交互前强制校验 ID、联合类型形态、字段值以及配置的字节数和数量限制。
+- 线上的 schema 会校验 ID 字符串，领域 API 始终公开带品牌类型的 ID。模型解析器会在面板可交互前强制校验带标签的布局形态、字段值，以及配置的字节数和数量限制。浏览器测试证明：图片语法会变成替代文本，原始 HTML 和嵌入式媒体不会渲染，而且在用户显式操作前不会请求模型提供的 URL。
 - 组件测试覆盖纯键盘操作、焦点恢复、无障碍名称、窄屏布局、两种主题，以及中英文产品界面。
-- 无密钥浏览器组合测试覆盖显示、编辑、接纳被拒后的重试、排队／丢弃提交、持久提交、关闭、刷新恢复和双重提交幂等性。
+- 无密钥浏览器组合测试覆盖显示、Dock 与只读行的职责归属、窗口外恢复、编辑、接纳被拒后的重试、从 `queued` 到 `claiming` 的转换、丢弃、没有可编辑空档的持久交接、禁止的队列操作、关闭、重新连接和双重提交幂等性。
 - 前缀快照表明：无论任务特定模型如何变化，都只存在一个稳定的工具定义；只有调用参数和后续用户结论发生变化。
-- 卸载 Web 插件时，其所属 Fiber 会对工具行和草稿 store 执行 dispose（资源释放），但不会改变持久 transcript。
+- 卸载 Web 插件时，其所属 Fiber 会对 Dock、工具行和草稿 store 执行 dispose，但不会改变持久 transcript。
 
 ## 风险
 
 第一批组件可能小到无法满足实际任务，也可能大到足以演变成一个粗糙的应用框架。是否新增组件应由使用证据决定；v1 不提供表达式语言或网络行为。
 
+Task Surface 的 Markdown 策略舍弃行内图片、媒体和自动链接预览。普通链接仍有用，但只有用户显式操作后，才可以导航或发起请求。
+
 即使设置了字节限制，大型表格和 Markdown 仍可能生成开销较高的 DOM。渲染器必须按需虚拟化或截断内容，同时保留可读回退和明确计数。
 
 填写字段较多时，由产品格式化的提交消息可能过长。格式化器需要使用确定性的紧凑格式，保留每一个提交值，同时避免重复完整显示模型。
 
+在完成持久交接之前一直持有进程内认领状态，会新增一项终态不变量。每条接纳退出路径都必须产生匹配的 `user/message` 或显式丢弃，否则重新连接可能会让 Dock 永久处于禁用状态。
+
 浏览器本地持久化的草稿可能保留敏感的未提交文本。store 需要遵守规定的字节上限、使用按会话划分的 key、在提交成功后显式清除，并采用与现有会话草稿相同的存储策略。
+
+Dock 和 transcript 行以不同角色展示同一个调用实例。将工具行保持为只读，并让 Dock 成为唯一的变更所有者，可以避免草稿冲突，但代价是 Surface 活动期间会出现第二份简洁表示。

From 70cf4a147145a8de4714140dd0e2d7b33c1d04f3 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 5 Aug 2026 18:26:07 +0800
Subject: [PATCH 036/516] test(web): follow master's icon-only add-provider
 button

The merge restored the icon variant of the Models add button; its
accessible name no longer carries the `+` text prefix.
---
 apps/web/tests/models-settings.e2e.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 33e27628b0..694f268c59 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -58,7 +58,7 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     await dialog.getByText('填入各提供方的 API 密钥即可使用其模型。').waitFor({ timeout: 10_000 })
     // The dormant pi-ai adapter contributes its whole installed catalog; no
     // provider is configured yet, so the page is one add button.
-    const add = dialog.getByRole('button', { name: '+ 添加提供方' })
+    const add = dialog.getByRole('button', { name: '添加提供方' })
     await add.waitFor({ timeout: 10_000 })
     // The button enables once the dormant catalog lands in the join.
     await expect.poll(async () => add.isEnabled(), { timeout: 10_000 }).toBe(true)

From d8d487236f656869428250cc0895afa859001e4b Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 5 Aug 2026 18:36:32 +0800
Subject: [PATCH 037/516] test(cli): mount the never-dispose plugin through
 --config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The headless shutdown probe needs a plugin that refuses to dispose, so
the second Ctrl+C has something to force past. Writing it to the Harness
home stopped working when the personal composition layer was deleted:
nothing is discovered there, the plugin never mounted, and the first
signal drained cleanly — leaving the second PTY action to time out.
---
 apps/cli/tests/headless-shutdown.e2e.ts | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/apps/cli/tests/headless-shutdown.e2e.ts b/apps/cli/tests/headless-shutdown.e2e.ts
index 81089b3598..4ca8fdc0e5 100644
--- a/apps/cli/tests/headless-shutdown.e2e.ts
+++ b/apps/cli/tests/headless-shutdown.e2e.ts
@@ -66,7 +66,10 @@ async function runHeadlessPtySmoke(): Promise<string> {
   try {
     const home = join(cwd, '.dsh')
     await mkdir(home, { recursive: true })
-    await writeFile(join(home, 'config.yaml'), [
+    // The overlay is named, not discovered: nothing is auto-loaded from the
+    // Harness home, and `-p` takes `--config` for exactly this reason.
+    const overlay = join(cwd, 'never-dispose.cordis.yml')
+    await writeFile(overlay, [
       '- insert:',
       '    - id: never-dispose',
       `      name: '${neverDisposePlugin}'`,
@@ -74,7 +77,7 @@ async function runHeadlessPtySmoke(): Promise<string> {
     ].join('\n'))
     const launch = resolveExampleLaunch({
       srcBin: dshBinScript,
-      configArgs: ['-p', 'never complete'],
+      configArgs: ['-p', 'never complete', '--config', overlay],
       tsconfigPath,
       env: {
         DSH_HOME: home,

From 598f9719f4e27b6d5e37478fb20a85214956fd0d Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 10:23:26 +0800
Subject: [PATCH 038/516] refactor(landlock-run): unify workspace release
 (review round 1)

---
 .../feature/2026-07-06-sandbox.i18n.yaml      |   4 +-
 .../implemented/feature/2026-07-06-sandbox.md |  12 +-
 .../feature/2026-07-06-sandbox.zh.md          |  12 +-
 ...6-in-repository-landlock-release.i18n.yaml |   6 +
 ...26-08-06-in-repository-landlock-release.md |  42 +++
 ...08-06-in-repository-landlock-release.zh.md |  42 +++
 .github/workflows/landlock-run-release.yml    | 170 +++++++++
 .github/workflows/landlock-run.yml            |  42 ++-
 .github/workflows/sandbox.yml                 |  27 +-
 THIRD_PARTY_NOTICES.md                        |   4 +-
 knip.json                                     |   1 +
 native/README.i18n.yaml                       |   4 +-
 native/README.md                              |  10 +-
 native/README.zh.md                           |  10 +-
 native/landlock-run/AGENTS.md                 |   2 +-
 native/landlock-run/docs/release.md           |  36 +-
 native/landlock-run/pnpm-lock.yaml            | 345 ------------------
 native/landlock-run/pnpm-workspace.yaml       |   8 -
 native/landlock-run/scripts/bump-release.mjs  |  11 +-
 .../landlock-run/scripts/commit-release.mjs   |  10 +-
 native/landlock-run/scripts/repo.mjs          |   4 +-
 .../landlock-run/scripts/verify-release.mjs   |  16 +-
 package.json                                  |   2 +
 packages/bash/bash-sandbox/package.json       |   2 +-
 packages/bash/bash-sandbox/tsconfig.json      |   3 +
 .../examples/agent-spine-demo/package.json    |   2 +-
 .../examples/agent-spine-demo/tsconfig.json   |   3 +
 packages/sandbox/sandbox-local/package.json   |   2 +-
 .../sandbox-local/tests/landlock.e2e.ts       |   2 +-
 .../sandbox-local/tests/packed-install.e2e.ts |  35 +-
 packages/sandbox/sandbox-local/tsconfig.json  |   3 +
 pnpm-lock.yaml                                | 103 +++---
 pnpm-workspace.yaml                           |  11 +-
 scripts/check-workspace-constraints.ts        |  32 +-
 scripts/clean.spec.ts                         |  16 +-
 scripts/clean.ts                              |   9 +-
 scripts/gen-third-party-notices.spec.ts       |   4 +-
 scripts/gen-third-party-notices.ts            |  16 +-
 tsconfig.base.json                            |   1 +
 tsconfig.host.json                            |   1 +
 40 files changed, 535 insertions(+), 530 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
 create mode 100644 .agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
 create mode 100644 .github/workflows/landlock-run-release.yml
 delete mode 100644 native/landlock-run/pnpm-lock.yaml
 delete mode 100644 native/landlock-run/pnpm-workspace.yaml

diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 7f15a55333..5f8dfa4e65 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: aed5ac1ceb02130ce97a8c83c0f77869fdc32146
-2026-07-06-sandbox.zh.md: db95b1a5b7a7cae1e0fcdd8deba9dcb6ad020a67
+2026-07-06-sandbox.md: 69a3f1bd181bc06d9a176fa45b1e091991cfa682
+2026-07-06-sandbox.zh.md: eeca55b61da24df215f7a9b7ba8dbf9ab2387f20
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index aed5ac1ceb..69a3f1bd18 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -64,7 +64,7 @@ Left open, for the phase that needs them: whether network restriction arrives as
 
 The launcher is a ~300-line C program (plain C11 over the raw Landlock UAPI — no libraries beyond a statically linked musl, so the audit surface is that one file plus the kernel's stable syscall contract): `--ro <path>` / `--rw <path>` grants, `--`, the wrapped argv; it installs the ruleset on itself and `exec`s (rulesets are inherited across `execve`, and it sets `no_new_privs` before restricting); `--probe` enforces a maximal ruleset in a short-lived child and exits 0 only when the kernel actually enforces; every launcher failure exits 125 without running the child and prints a fatal `landlock-run:` line. A successfully exec'd child may also return 125, so status alone is not launcher evidence. An older ABI prints the exact `landlock-run: partial enforcement (older Landlock ABI)` notice before it executes the child, so that line is not fatal evidence.
 
-The Landlock launcher source and package workspace live at `native/landlock-run`, next to the harness consumers. The standalone [`node-addon-landlock-run`](https://github.com/deepseek-harness/node-addon-landlock-run) repository is the release mirror used to pack and publish the npm package family; `native/README.md` owns the export procedure. Platform binaries are selected by npm, and the entry package owns path resolution, probing, CLI flags, the fatal prefix, and the partial-enforcement notice while the harness maps sandbox modes to grants. Versioning the entry point with its binaries keeps probe parsing and launch syntax aligned.
+The Landlock launcher source and package family live at `native/landlock-run`, next to the harness consumers and inside the root pnpm workspace. The [in-repository Landlock release decision](../process/2026-08-06-in-repository-landlock-release.md) owns the shared lockfile, native build, pack rehearsal, and npm publication boundary. Platform binaries are selected by npm, and the entry package owns path resolution, probing, CLI flags, the fatal prefix, and the partial-enforcement notice while the harness maps sandbox modes to grants. Versioning the entry point with its binaries keeps probe parsing and launch syntax aligned.
 
 Backend profiles share the mode contract but differ in necessary host grants. Landlock and Seatbelt allow only `/dev/null` in read-only mode; workspace-write also permits their required host temp roots. Each wrap carries backend-specific denial signatures. Landlock reports partial enforcement on older ABIs that cannot govern every operation, while successful bwrap and Seatbelt profiles report full enforcement.
 
@@ -118,7 +118,7 @@ fs/web/todo execute in-process, so their sandbox semantics are policy at their s
 ### Testing
 
 - **Unit:** pin platform selection and profiles, direct provider-argv handoff, spawn-level failures with invalid-workdir controls, missing/non-executable/missing-interpreter evidence, malformed-runner negative controls, confined `BASH_ENV` ordering, structured runner classification (including partial-Landlock notice-only child outcomes, gated fatal evidence, child exits 126/127, and foreground/background parity), per-call mode/root resolution, per-process facts, escalation validation and outcomes, permission preset folding and write-through, and runtime-context ordering and materialization.
-- **Keyless real-runner:** exercise bwrap, Landlock, and Seatbelt against real filesystem effects at provider and bash-consumer layers; one real Cordis context concurrently drives two project sessions through shipped bash and fs tools, proving own-root success and sibling-root denial. Packed-install coverage proves the registry launcher remains executable. CI rejects a silent all-skip.
+- **Keyless real-runner:** exercise bwrap, Landlock, and Seatbelt against real filesystem effects at provider and bash-consumer layers; one real Cordis context concurrently drives two project sessions through shipped bash and fs tools, proving own-root success and sibling-root denial. Packed-install coverage installs the current checkout's native tarballs and proves the launcher remains executable and byte-identical. CI rejects a silent all-skip.
 - **With-key:** start the real ACP composition in read-only mode, let a model-driven bash write hit the runner's denial marker, then drive the bridge answerer and disk effect through granted and rejected workspace-write retries; unavailable credentials or runners self-skip.
 - **Snapshot:** pin the atomic current-policy context and both scripted approval branches. A real ACP example scenario places its session under the user home while the deployment fallback points at `/tmp`, then pins both the workspace-write runtime-context message and a successful deployment-selected mutation; this distinguishes session-root resolution from the process fallback without depending on runner-specific denial text. A POSIX fake partial-Landlock provider pins direct bash `false` as an ordinary child result and a missing provider executable as foreground/background infrastructure failure through the assembled app. Other snapshots start unconfined so unrelated fixtures remain platform-independent.
 
@@ -134,9 +134,9 @@ Each phase gets its full design when picked up, validated against the code at th
 
 - **Command-string heuristic preflight** — rejected: cannot understand expansion/subprocesses/symlinks; the strict attempt (run it, let the kernel decide) is the only trustworthy denial signal.
 - **Functionally probe even a platform's sole backend** — rejected: probing arbitrates between candidates; with one there is nothing to decide, and probe cost taxes the first confined command of every session (prohibitive for heavy future backends). The runner's own exec-time fail-closed refusal plus structured `runnerFailureRules` classification carries the safety property instead.
-- **Commit the built launcher binaries** — rejected: a binary in a diff is unreviewable and churns history; reviewed source + native CI builds + the launcher repo's byte-pinned publish rehearsal keep bytes out of every tree.
+- **Commit the built launcher binaries** — rejected: a binary in a diff is unreviewable and churns history; reviewed source + native CI builds + the main repository's byte-pinned publish rehearsal keep bytes out of every tree.
 - **Compile the launcher on install** — rejected: pushes a C toolchain onto every consumer; a fallback that exists only where a compiler happens to be is not a fallback.
-- **Cross-compile both architectures from one builder** — rejected: requires carrying a pinned cross toolchain (rustup targets, zig, or a container image) solely to rebuild two ~70 KB binaries; per-architecture native runners already exist and each builds its own platform package (the `node-addon-require-builtin` model, the launcher repo's own pipeline).
+- **Cross-compile both architectures from one builder** — rejected: requires carrying a pinned cross toolchain (rustup targets, zig, or a container image) solely to rebuild two ~70 KB binaries; per-architecture native runners already exist and each builds its own platform package (the `node-addon-require-builtin` model, retained by the main repository's native pipeline).
 - **No fallback (bwrap or fail closed)** — rejected: concentrates failure on the hosts a sandbox matters most, degrading to `danger-full-access` by resignation.
 - **Keep the mechanism inside `dsh-bash-sandbox`** — rejected: blocks the existing second consumer, makes future phases read mode out of a bash plugin's config, and cannot express escalation.
 - **Config-fixed mode on the provider** — rejected: one mode per process; cannot serve concurrent consumers with different policies nor the one-shot widened retry.
@@ -175,7 +175,7 @@ Costs and accepted limits:
 - **The Seatbelt rung leans on Apple's deprecated-but-shipped `sandbox-exec` CLI.** As darwin's sole candidate it is selected without probing, so a future removal under a usable workdir surfaces as a runner-attributable spawn failure and an executable refusal through its fatal signature — both become `SANDBOX_UNAVAILABLE`, and the command never runs; fail closed, never open.
 - **Landlock confinement is only as complete as the running kernel's ABI.** Reported as `enforcement: 'partial'` rather than refused — the deliberate trade that keeps the fallback available on older-kernel hosts.
 - **Runner attribution uses an in-band protocol.** Exit status plus stderr cannot cryptographically identify the writer, so a confined child can mimic a fatal runner line and status to cause an availability/diagnostic false attribution. The conjunction and exact notice exclusion reduce accidental matches; this is not a sandbox bypass because the child is already confined.
-- **The launcher arrives as a registry dependency.** Trusted through its own repository's release pipeline (reviewed C source, native CI builders, byte-pinned publish rehearsal) plus this repo's version pin — the real-kernel e2e legs are what vouch for behavior through the installed bytes.
+- **The launcher is a workspace dependency in source and an npm dependency after publication.** The main repository tests reviewed C source, native CI builds, and byte-pinned local tarballs together before publishing the same package family; the real-kernel e2e legs vouch for behavior through those installed bytes.
 - **The model may over-ask.** Escalating without denial grounding, or picking `danger-full-access` where `workspace-write` suffices: the description steers and the enum forces the ladder, but the human prompt is the actual gate; the `approval/asked` reasons make over-asking auditable, and a `prepend` policy answerer can auto-reject patterns a deployment never wants.
 - **The advertised target set is static while the effective mode is per-session** (schemas are registry-global) — a session already at the widest mode is still offered the fields. Harmless by construction: the strict-wider check at execution, not the enum, is the safety boundary — a non-widening request fails with its own text and never prompts anyone.
 - **A granted escalation is not a working sandbox.** An unavailable backend still fails closed even for a granted escalation to a confining mode — at `confine()` when the platform has no chain or every probe fails, through the spawn channel when the selected executable cannot start, or through a structured rule when a started runner refuses — while a granted `danger-full-access` run never touches the provider at all: there the grant, not the probe, is the authority.
@@ -187,7 +187,7 @@ Costs and accepted limits:
 - **A command came back with `[sandbox: file access denied under read-only mode]` — did it fail?** It RAN, and the kernel refused a file effect: the denial is a result fact orthogonal to exit code. The teaching forbids retrying around it; the one sanctioned move is the same command retried once with an escalation request.
 - **How is a BROKEN sandbox told apart from a failing command?** Any provider-argv spawn rejection proves the confined launch never started, but it identifies a broken runner only when the caller-owned workdir is usable and Node reports attributable `ENOENT` or `EACCES` for that argv[0]. A bare `syscall: 'spawn'` without an exact error path and all other rejections remain ordinary command-start errors. After a process starts, runner failure outranks denial only when one `runnerFailureRules` entry matches both its optional exit-code gate and a fatal stderr line after exact informational exclusions. Foreground failures throw structured `SANDBOX_UNAVAILABLE` with spawn or matched-line detail; an asynchronously rejected or settled background task stamps `sandbox.runnerFailed` and renders its own marker. A `SubprocessService` that synchronously throws the same provenanced `ENOENT`/`EACCES` shape makes background start throw the structured error; other synchronous errors propagate unchanged. A Landlock partial-enforcement notice plus an ordinary child failure remains a command result.
 - **What happens on a platform with no backend — Windows today?** `confine()` throws the fail-closed `SANDBOX_UNAVAILABLE` and the command never spawns; `win32` is a reserved EMPTY chain, pinned by test to fail closed identically until a Windows runner fills it (§ Deferred phases).
-- **`bwrap` is installed on my host but unusable (disabled unprivileged userns, an LSM denying `mount`) — what happens?** The chain probe is functional — it builds and enforces a real profile rather than checking `--version` — so a present-but-unusable `bwrap` fails its probe, selection falls to the registry-installed Landlock launcher, and the verdict is cached for the provider's lifetime.
+- **`bwrap` is installed on my host but unusable (disabled unprivileged userns, an LSM denying `mount`) — what happens?** The chain probe is functional — it builds and enforces a real profile rather than checking `--version` — so a present-but-unusable `bwrap` fails its probe, selection falls to the packaged Landlock launcher, and the verdict is cached for the provider's lifetime.
 - **Does the sandbox restrict network or process visibility?** No — `SandboxMode` claims FILE effects only; the bwrap profile deliberately does not unshare pid, and no backend claims network. Whether network restriction becomes its own knob is left open in § The seam.
 - **Which tools actually run confined?** OS subprocesses through `ctx.bash` — the bash tools, and hook commands transitively — plus the filesystem tools (`read`/`write`/`edit`) through the sandboxed `ctx.fs` provider (the [cross-family fs sandbox RFC](2026-07-14-cross-family-fs-sandbox.md)): bash confines via the OS runner, fs via an in-process path fence, both keying off the same `ctx.sandboxPolicy` mode. web/todo stay in-process and unfenced (web's only effect is network, outside the file-effect mode vocabulary).
 - **Does a granted escalation persist?** No. The grant is consumed by the exact foreground or background call that asked; every neighboring call keeps its own effective mode. A later background denial surfaces through `task_output` and may ground a new exact-command retry.
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index db95b1a5b7..eeca55b61d 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -64,7 +64,7 @@ OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还
 
 launcher 是一个约 300 行的 C 程序（纯 C11，直接使用 Landlock UAPI——除静态链接的 musl 外无其他库，因此审计面仅为该文件加内核的稳定 syscall 契约）：`--ro <path>` / `--rw <path>` 授权，`--`，被包装的 argv；它为自身安装规则集并执行 `exec`（规则集跨 `execve` 继承，且它在限制前设置 `no_new_privs`）；`--probe` 在一个短生命周期子进程中强制最大规则集，仅当内核确实强制时才以 0 退出；所有 launcher 失败都会以 125 退出且不运行子进程，并打印一行致命的 `landlock-run:` 诊断。成功完成 exec 的子进程也可能返回 125，因此仅凭退出状态不能作为 launcher 失败的证据。较旧的 ABI 会在执行子进程之前打印精确的 `landlock-run: partial enforcement (older Landlock ABI)` 通知，因此该行不是致命证据。
 
-Landlock launcher 源码和包工作区位于 `native/landlock-run`，与 harness 消费方同仓。独立的 [`node-addon-landlock-run`](https://github.com/deepseek-harness/node-addon-landlock-run) 仓库是用于打包并发布 npm 包族的发布镜像；导出流程归 `native/README.md` 所有。平台二进制由 npm 选择，入口包拥有路径解析、探测、CLI 参数、致命前缀和部分强制执行通知，而 harness 将沙箱模式映射为授权。将入口点与其二进制一起版本化，使探测解析和启动语法保持对齐。
+Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 消费方同仓，并属于根 pnpm workspace。[仓库内 Landlock 发布决策](../process/2026-08-06-in-repository-landlock-release.md)负责共享锁文件、原生构建、打包演练和 npm 发布边界。平台二进制由 npm 选择，入口包拥有路径解析、探测、CLI 参数、致命前缀和部分强制执行通知，而 harness 将沙箱模式映射为授权。将入口点与其二进制一起版本化，使探测解析和启动语法保持对齐。
 
 后端 profile 共享模式契约但在必要的主机授权上有所不同。Landlock 和 Seatbelt 在 read-only 模式下仅允许 `/dev/null`；workspace-write 还允许各自所需的主机临时目录根。每次包装携带后端特定的拒绝签名。Landlock 在较旧的 ABI 无法管控所有操作时报告 partial enforcement，而成功的 bwrap 和 Seatbelt profile 报告 full enforcement。
 
@@ -118,7 +118,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 ### 测试
 
 - **单元测试：** 固定平台选择和 profile、直接交接提供方返回的 argv、带有无效 workdir 对照的 spawn 层失败、runner 缺失／不可执行／解释器缺失证据、格式错误 runner 阴性对照、受约束的 `BASH_ENV` 求值顺序、结构化 runner 分类（包括只有部分强制执行通知的子进程结果、带门控的致命证据、子进程退出码 126／127，以及前台／后台一致性）、按调用的模式/根目录解析、按进程事实、升级验证和结果、权限 preset fold 和写入透传，以及运行时上下文排序与具体化。
-- **Keyless 真实 runner：** 在提供方和 bash 消费方层面对 bwrap、Landlock 和 Seatbelt 执行真实文件系统效果测试；一个真实 Cordis 上下文通过已交付的 bash 和 fs 工具并发驱动两个项目会话，证明在自身根目录写入成功、在兄弟根目录写入被拒绝。打包安装测试证明注册表 launcher 保持可执行。CI 拒绝静默全跳过。
+- **Keyless 真实 runner：** 在提供方和 bash 消费方层面对 bwrap、Landlock 和 Seatbelt 执行真实文件系统效果测试；一个真实 Cordis 上下文通过已交付的 bash 和 fs 工具并发驱动两个项目会话，证明在自身根目录写入成功、在兄弟根目录写入被拒绝。打包安装测试会安装当前 checkout 的原生 tarball，并证明 launcher 保持可执行且字节完全一致。CI 拒绝静默全跳过。
 - **With-key：** 以只读模式启动真实 ACP 组合，让模型驱动的 bash 写入命中 runner 的拒绝标记，再通过已授权与被拒绝的 workspace-write 重试驱动 bridge 应答器和磁盘效果；不可用的凭证或 runner 自动跳过。
 - **快照：** 固定原子化的当前策略上下文和两个脚本化的 approval 分支。一个真实 ACP 示例场景把会话放在用户主目录下，同时让部署后备根目录指向 `/tmp`，然后固定 workspace-write 运行时上下文消息与一次成功的、由部署选定的变更；这能区分会话根目录解析与进程后备值，而不依赖 runner 特定的拒绝文本。一个模拟 Landlock 部分强制执行行为的 POSIX 提供方会在组装后的应用中固定直接执行 bash `false` 时仍得到普通子进程结果，并固定提供方可执行文件缺失时在前台／后台均为基础设施失败。其他快照以无约束启动，使无关 fixture（测试前置数据）保持平台无关。
 
@@ -134,9 +134,9 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 
 - **命令字符串启发式预检**：否决。无法理解展开/子进程/符号链接；严格尝试（运行它，让内核决定）是唯一可信的拒绝信号。
 - **即使平台仅有一个后端也功能性探测**：否决。探测用于在候选者之间仲裁；只有一个时无需决策，且探测开销对每个会话的首次约束命令征税（对未来重量级后端而言代价过高）。runner 自身执行时的失败关闭拒绝加结构化 `runnerFailureRules` 分类承载了安全属性。
-- **提交构建好的 launcher 二进制**：否决。diff 中的二进制不可审查且膨胀历史；经审查的源码 + 原生 CI 构建 + launcher 仓库的字节固定发布演练使二进制远离所有代码树。
+- **提交构建好的 launcher 二进制**：否决。diff 中的二进制不可审查且膨胀历史；经审查的源码 + 原生 CI 构建 + 主仓库的字节固定发布演练使二进制远离所有代码树。
 - **安装时编译 launcher**：否决。将 C 工具链强加给每个消费方；仅在碰巧有编译器时才存在的备选不是备选。
-- **从一个构建器交叉编译两种架构**：否决。仅为重建两个约 70 KB 的二进制就需要携带一个固定的交叉工具链（rustup targets、zig 或容器镜像）；每架构的原生 runner 已存在，各自构建自己的平台包（`node-addon-require-builtin` 模式，launcher 仓库自己的流水线）。
+- **从一个构建器交叉编译两种架构**：否决。仅为重建两个约 70 KB 的二进制就需要携带一个固定的交叉工具链（rustup targets、zig 或容器镜像）；每架构的原生 runner 已存在，各自构建自己的平台包（`node-addon-require-builtin` 模式，由主仓库的原生流水线保留）。
 - **无备选（bwrap 或失败关闭）**：否决。将失败集中在沙箱最重要的主机上，最终因放弃而降级到 `danger-full-access`。
 - **将机制保留在 `dsh-bash-sandbox` 内部**：否决。阻塞既有的第二个消费方，使未来阶段从一个 bash 插件的配置中读取模式，且无法表达升级。
 - **提供方上的配置固定模式**：否决。每进程一个模式；无法服务具有不同策略的并发消费方，也无法表达一次性放宽重试。
@@ -175,7 +175,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 - **Seatbelt 层级依赖 Apple 已弃用但仍交付的 `sandbox-exec` CLI。** 作为 darwin 的唯一候选，它无需探测即被选中，因此在 workdir 可用时，未来移除会表现为可归因于 runner 的 spawn 失败，可执行文件拒绝则通过其致命签名体现——两者都会变为 `SANDBOX_UNAVAILABLE`，且命令绝不会运行；失败关闭，绝不开放。
 - **Landlock 约束的完整度取决于运行内核的 ABI。** 报告为 `enforcement: 'partial'` 而非拒绝——这是有意的权衡，使备选在旧内核主机上仍可用。
 - **Runner 归因使用带内协议。** 退出状态与 stderr 无法以密码学方式识别写入者，因此受限子进程可以模仿 runner 的致命诊断行和状态，造成可用性或诊断误归因。多项证据的合取与精确通知排除减少了意外匹配；这不是沙箱绕过，因为子进程已经受到限制。
-- **launcher 作为注册表依赖到达。** 通过其自身仓库的发布流水线（经审查的 C 源码、原生 CI 构建器、字节固定的发布演练）加上本仓库的版本固定获得信任——真实内核 e2e 测试环节会验证安装产物的实际行为。
+- **launcher 在源码中是 workspace 依赖，发布后是 npm 依赖。** 主仓库会在发布同一个包家族之前，一起测试经审查的 C 源码、原生 CI 构建和字节固定的本地 tarball；真实内核 e2e 测试环节会验证这些安装字节的实际行为。
 - **模型可能过度请求。** 在没有拒绝依据的情况下升级，或在 `workspace-write` 足够时选择 `danger-full-access`：描述引导且枚举强制阶梯，但人的提示词是实际门控；`approval/asked` 原因使过度请求可审计，且 `prepend` 策略应答器可以自动拒绝部署永远不想要的模式。
 - **公布的目标集是静态的，而有效模式是按会话的**（schema 是注册表全局的）——已处于最宽模式的会话仍被提供这些字段。构造上无害：执行时的严格放宽检查（而非枚举）是安全边界——非放宽请求以自身文本失败且不提示任何人。
 - **授权的升级不等于可工作的沙箱。** 不可用的后端即使对授权升级到约束模式也仍然失败关闭——平台没有链或所有探测失败时在 `confine()` 阶段失败，所选可执行文件无法启动时通过 spawn 通道失败，已启动的 runner 拒绝时则通过结构化规则失败——而授权的 `danger-full-access` 运行根本不触及提供方：此时授权（而非探测）是权威。
@@ -187,7 +187,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 - **一个命令返回了 `[sandbox: file access denied under read-only mode]`——它失败了吗？** 它运行了，内核拒绝了一个文件操作：拒绝是与退出码正交的结果事实。相关指令禁止通过绕过限制来重试；唯一被认可的动作是以升级请求重试同一命令一次。
 - **如何区分损坏的沙箱与失败的命令？** 提供方 argv 的任何 spawn 拒绝都能证明受限启动从未开始，但只有在调用方拥有的 workdir 可用，且 Node 为该 argv[0] 报告可归因的 `ENOENT` 或 `EACCES` 时，才能据此判定 runner 损坏。没有精确错误路径的裸 `syscall: 'spawn'` 和其他所有拒绝仍是普通的命令启动错误。进程启动后，只有当 `runnerFailureRules` 中某一条目同时匹配其可选退出码门控，以及排除整行精确信息性行后的一行致命 stderr 诊断时，runner 失败才会优先于拒绝。前台失败会抛出结构化的 `SANDBOX_UNAVAILABLE`，并附带 spawn 错误或匹配行作为详细信息；遭异步拒绝或已结算的后台任务则盖章 `sandbox.runnerFailed` 并渲染自己的标记。如果 `SubprocessService` 同步抛出同样带有来源信息的 `ENOENT`／`EACCES` 形态，后台启动会抛出该结构化错误；其他同步错误原样传播。Landlock 部分强制执行通知加上普通子进程失败时，仍返回命令结果。
 - **在没有后端的平台上会发生什么——今天的 Windows？** `confine()` 抛出失败关闭的 `SANDBOX_UNAVAILABLE`，命令永不 spawn；`win32` 是保留的空链，由测试固定为同样失败关闭，直到 Windows runner 填充它（§ 延迟阶段）。
-- **`bwrap` 已安装在我的主机上但不可用（禁用了非特权 userns、LSM 拒绝 `mount`）——会发生什么？** 链探测是功能性的——它构建并强制一个真实 profile 而非检查 `--version`——因此存在但不可用的 `bwrap` 探测失败，选择落到注册表安装的 Landlock launcher，结论在提供方生命周期内缓存。
+- **`bwrap` 已安装在我的主机上但不可用（禁用了非特权 userns、LSM 拒绝 `mount`）——会发生什么？** 链探测是功能性的——它构建并强制一个真实 profile 而非检查 `--version`——因此存在但不可用的 `bwrap` 探测失败，选择落到已打包的 Landlock launcher，结论在提供方生命周期内缓存。
 - **沙箱限制网络或进程可见性吗？** 不——`SandboxMode` 仅声称文件操作；bwrap profile 刻意不 unshare pid，没有后端声称网络。网络限制是否成为自己的旋钮留在 § seam 中开放。
 - **哪些工具实际在约束下运行？** 通过 `ctx.bash` 的 OS 子进程——bash 工具及传递性的钩子命令——再加上通过沙箱化 `ctx.fs` 提供方运行的文件系统工具（`read`/`write`/`edit`，见[跨工具族 fs 沙箱 Agent Note](2026-07-14-cross-family-fs-sandbox.md)）：bash 通过 OS runner 约束，fs 通过进程内路径围栏约束，二者都以同一个 `ctx.sandboxPolicy` 模式为键。web/todo 仍在进程内且不受限制（web 的唯一效果是网络，不在文件效果模式词汇内）。
 - **授权的升级会持久化吗？** 不会。授权由发起请求的确切前台或后台调用消费；每个相邻调用保留自己的有效模式。后续的后台拒绝通过 `task_output` 呈现，并且可以作为一次新的精确命令重试的依据。
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
new file mode 100644
index 0000000000..3ce0e0d5e1
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.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/process/2026-08-06-in-repository-landlock-release.md
+2026-08-06-in-repository-landlock-release.md: f682078250adde8d56a4270e9d01ce4b1cd1bee9
+2026-08-06-in-repository-landlock-release.zh.md: 4950d80d87afd18c5605f4f5bca56b8d85564fc2
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
new file mode 100644
index 0000000000..f682078250
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
@@ -0,0 +1,42 @@
+# Agent Note: In-repository Landlock release
+
+Status: implemented
+
+English | [中文](2026-08-06-in-repository-landlock-release.zh.md)
+
+## Problem
+
+The `node-addon-landlock-run` source already lives beside its DeepSeek Harness consumers under `native/landlock-run`, but it previously kept a separate pnpm workspace and lockfile and depended on a standalone repository for npm publication. Harness packages consumed a fixed registry version, so one pull request could change the launcher contract and its consumer without testing those changes together. The source repository's native workflow could rehearse the package, but it did not publish the artifact it tested.
+
+The mirror also duplicated release coordination: export the source, update another lockfile, run another release workflow, publish the native family, then return to this repository to bump registry dependencies. That split made source-to-binary provenance, rollback, and security-fix coordination harder without changing what npm users actually needed.
+
+The consolidation must preserve platform selection. The public distribution is deliberately one JavaScript entry package plus separate Linux x64 and arm64 binary packages; merging repository ownership does not imply putting every binary into one tarball or publishing every DeepSeek Harness package at the launcher version.
+
+## Decision
+
+`native/landlock-run` and `native/landlock-run/packages/*` belong to the repository's root pnpm workspace and use the root `pnpm-lock.yaml`. Harness consumers declare `node-addon-landlock-run` with `workspace:*`, so development, type checking, builds, and pull-request tests resolve the entry package from the same checkout. The root TypeScript project graph builds that entry package before consumers, and the repository cleaner owns its direct `lib/` output.
+
+The public npm boundary remains three packages with one launcher-family version: `node-addon-landlock-run`, `node-addon-landlock-run-linux-x64`, and `node-addon-landlock-run-linux-arm64`. The entry package retains both platform packages as `optionalDependencies`; their `os` and `cpu` manifest fields let npm install only the compatible package. Repository constraints allow public publication only for those three names, require `publishConfig.access: public`, and require their versions to match the private launcher workspace root. Other repository workspaces remain private under the existing constraint.
+
+The main repository owns both native CI and publication. `Landlock Run` runs for relevant pull requests and `master` pushes and builds each platform on its matching native runner. The manually dispatched `Landlock Run Release` workflow builds both platform binaries, transfers them as workflow artifacts, assembles and verifies the complete package family, packs immutable npm tarballs, installs and exercises those tarballs, and only then permits the protected publish job. Platform tarballs publish before the entry tarball that optionally depends on them. Publication uses `landlock-run-vX.Y.Z` tags so launcher releases cannot collide with other release families in the monorepo; prereleases use the npm `next` dist-tag.
+
+The sandbox packed-install rehearsal no longer permits the npm registry to supply the launcher. It packs the current checkout's entry and matching native package alongside the harness dependency closure, installs those local tarballs into an external plain-Node consumer, and proves that the installed launcher is executable, byte-identical to the native build, and the correct ELF architecture before testing confinement or fail-closed behavior.
+
+## Alternatives considered
+
+- **Keep the standalone repository as a release mirror** — rejected because it preserves the split lockfiles, source export, stale-registry test window, and cross-repository release sequence after the source of record has already moved here.
+- **Publish one npm package containing every platform binary** — rejected because users would download binaries they cannot run and npm could no longer use package-level `os`/`cpu` filtering. Repository ownership and npm package layout are separate choices.
+- **Give the launcher the root DeepSeek Harness version and publish the complete monorepo recursively** — rejected because this change owns one three-package public family, not the independent `@deepseek-ai/*` baseline. The [artifact-first npm baseline proposal](../../proposed/process/2026-08-04-artifact-first-npm-baseline-publication.md) explicitly keeps native workspaces outside its target set.
+- **Cross-compile both binaries in one release job** — rejected because the checked-in package matrix already assigns each architecture a native GitHub runner and avoids adding a cross-toolchain trust surface.
+
+## Consequences
+
+Launcher protocol, TypeScript entry code, native source, harness consumption, and publish-path tests can change in one pull request and resolve from one lockfile. A release tag now identifies the source, consumer integration, build instructions, and tarballs tested by the main repository. The standalone mirror is no longer part of the release path and can be archived after the first successful in-repository publication.
+
+npm consumers keep the same install command and package names. A supported Linux host downloads the entry package and its matching architecture package; the other architecture package is skipped. An unsupported host receives no platform binary and follows the existing deterministic fail-closed probe path.
+
+The implementation touches more files than a dependency-line edit because the repository must also own workspace constraints, TypeScript build order, cleanup, CI triggers, release tags, lockfile generation, packed-install provenance, release documentation, and generated notices. The behavioral boundary stays narrow: it changes only the Landlock package family and its three direct workspace consumers, not the version or publication state of other DeepSeek Harness packages.
+
+The main repository's `npm-publish` environment must authorize npm trusted publishing or provide `NPM_TOKEN`; moving workflow code cannot configure those external settings. npm still publishes packages sequentially and offers no cross-package transaction, so a failed publish can leave a partial version. Because npm rejects an already-published name and version, an operator must inspect the registry and publish only the missing tarballs rather than rerunning the workflow unchanged. Linux x64 and arm64 runners remain the authoritative binary and real-kernel checks; a macOS checkout can verify the entry package and unsupported-platform behavior but cannot replace those jobs.
+
+This note supersedes only the release-mirror and registry-pinned source-development statements in the [sandbox Agent Note](../feature/2026-07-06-sandbox.md); that note continues to own sandbox behavior, runner selection, and enforcement semantics.
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
new file mode 100644
index 0000000000..4950d80d87
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
@@ -0,0 +1,42 @@
+# Agent Note: 仓库内 Landlock 发布
+
+Status: implemented
+
+[English](2026-08-06-in-repository-landlock-release.md) | 中文
+
+## 问题
+
+`node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器契约及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
+
+发布镜像还造成重复的发布协调工作：导出源码、更新另一份锁文件、运行另一套发布工作流、发布原生包家族，然后回到本仓库更新注册表依赖。npm 用户的实际需求并未改变，这种拆分却增加了从源码到二进制的溯源、回滚和安全修复协调难度。
+
+此次整合必须保留平台选择机制。公开分发有意采用一个 JavaScript 入口包，并为 Linux x64 和 arm64 分别提供二进制包；合并仓库归属并不意味着要把所有二进制文件放进同一个 tarball，也不意味着要按照启动器版本发布所有 DeepSeek Harness 包。
+
+## 决策
+
+`native/landlock-run` 和 `native/landlock-run/packages/*` 属于仓库根 pnpm workspace，并使用根 `pnpm-lock.yaml`。Harness 消费方将 `node-addon-landlock-run` 声明为 `workspace:*`，因此开发、类型检查、构建和 PR 测试都会从同一个 checkout 解析入口包。根 TypeScript 项目图会先构建该入口包，再构建消费方；仓库清理器负责清理其直接生成的 `lib/` 输出目录。
+
+公开 npm 分发边界仍由 3 个包组成，它们共用一个启动器包家族版本：`node-addon-landlock-run`、`node-addon-landlock-run-linux-x64` 和 `node-addon-landlock-run-linux-arm64`。入口包继续通过 `optionalDependencies` 声明两个平台包；它们在 manifest（元数据清单）中的 `os` 和 `cpu` 字段让 npm 只安装兼容的包。仓库约束只允许公开发布这 3 个包名，要求设置 `publishConfig.access: public`，并要求其版本与私有启动器 workspace 根包一致。仓库中的其他 workspace 仍受现有约束保护，保持私有状态。
+
+主仓库同时负责原生 CI 和发布。`Landlock Run` 会为相关 PR 和 `master` 推送运行，并在各自匹配的原生 runner 上构建每个平台包。手动触发的 `Landlock Run Release` 工作流会构建两个平台的二进制文件，将其作为工作流产物传递，组装并验证完整的包家族，打包出内容不可变的 npm tarball，安装并实际运行这些 tarball，之后才允许受保护的发布作业执行。发布顺序是平台 tarball 在前，最后发布将它们列为可选依赖的入口 tarball。发布使用 `landlock-run-vX.Y.Z` tag，避免启动器版本与 monorepo 中其他发布家族发生冲突；预发布版本使用 npm 的 `next` dist-tag。
+
+沙箱打包安装演练不再允许 npm 注册表提供启动器。它会将当前 checkout 的入口包、匹配的原生包和 harness 依赖闭包一起打包，把这些本地 tarball 安装到仓库外部的纯 Node 消费方中，并在测试约束效果或失败闭合行为之前，证明所安装的启动器可执行、与原生构建产物字节完全一致，且具有正确的 ELF 架构。
+
+## 曾考虑的替代方案
+
+- **保留独立仓库作为发布镜像**：不予采纳，因为在权威源码已经迁入本仓库后，这仍会保留拆分的锁文件、源码导出、测试使用陈旧注册表版本的时间窗，以及跨仓库发布序列。
+- **发布一个包含所有平台二进制文件的 npm 包**：不予采纳，因为用户会下载无法在其主机上运行的二进制文件，而且 npm 无法再利用包级 `os`／`cpu` 筛选。仓库归属与 npm 包布局是两个彼此独立的选择。
+- **让启动器使用 DeepSeek Harness 根版本，并递归发布整个 monorepo**：不予采纳，因为本次改动负责的是一个由 3 个包组成的公开包家族，而不是独立的 `@deepseek-ai/*` 基线。[产物优先的 npm 基线提案](../../proposed/process/2026-08-04-artifact-first-npm-baseline-publication.md)明确将原生 workspace 排除在其目标集合之外。
+- **在一个发布作业中交叉编译两个二进制文件**：不予采纳，因为仓库内已提交的包矩阵已经为每种架构分配了原生 GitHub runner，无需再把交叉工具链纳入信任边界。
+
+## 后果
+
+同一个 PR 可以同时修改启动器协议、TypeScript 入口代码、原生源码、harness 消费方式和发布路径测试，并从同一份锁文件解析这些内容。发布 tag 现在标识源码、消费方集成、构建指令，以及主仓库测试过的 tarball。第一次成功从本仓库发布后，独立镜像便不再属于发布路径，可以归档。
+
+npm 消费方继续使用相同的安装命令和包名。受支持的 Linux 主机会下载入口包及与其架构匹配的包，并跳过另一架构的包。不受支持的主机不会收到平台二进制文件，并继续沿用现有的确定性失败闭合探测路径。
+
+实现涉及的文件比只修改一行依赖更多，因为仓库还必须负责 workspace 约束、TypeScript 构建顺序、清理、CI 触发条件、发布 tag、锁文件生成、打包安装来源证明、发布文档和生成的第三方声明。行为边界仍然很窄：此次改动只影响 Landlock 包家族及其 3 个直接 workspace 消费方，不改变其他 DeepSeek Harness 包的版本或发布状态。
+
+主仓库的 `npm-publish` 环境必须授权 npm trusted publishing，或提供 `NPM_TOKEN`；只迁移工作流代码无法配置这些外部设置。npm 仍会按顺序发布各个包，且不提供跨包事务，因此发布失败可能留下只完成了一部分的版本。由于 npm 会拒绝已经发布的同名同版本包，操作人员必须检查注册表并只发布缺失的 tarball，而不能原样重新运行工作流。Linux x64 和 arm64 runner 仍提供权威的二进制构建与真实内核检查；macOS checkout 可以验证入口包和不受支持平台上的行为，但不能取代这些作业。
+
+本说明仅取代[沙箱 Agent Note](../feature/2026-07-06-sandbox.md)中有关发布镜像和开发源码时依赖注册表固定版本的表述；该 Agent Note 仍负责沙箱行为、runner 选择和强制执行语义。
diff --git a/.github/workflows/landlock-run-release.yml b/.github/workflows/landlock-run-release.yml
new file mode 100644
index 0000000000..dca6c9eed1
--- /dev/null
+++ b/.github/workflows/landlock-run-release.yml
@@ -0,0 +1,170 @@
+# Build and publish the node-addon-landlock-run package family from the
+# harness source of record. Rehearsal and publication consume the same packed
+# tarballs; each native binary is built on its matching architecture.
+name: Landlock Run Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Publish packed tarballs to npm. Must run from a landlock-run-v* tag.
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  # Stable/prerelease dist-tags are shared registry state; serialize release
+  # runs so two versions cannot race the final tag assignment.
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+defaults:
+  run:
+    working-directory: native/landlock-run
+
+jobs:
+  matrix:
+    name: Matrix
+    runs-on: ubuntu-24.04
+    outputs:
+      prebuilds: ${{ steps.matrix.outputs.prebuilds }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - id: matrix
+        run: echo "prebuilds=$(node ./scripts/github-matrix.mjs release-prebuild)" >> "$GITHUB_OUTPUT"
+
+  build-prebuilds:
+    name: ${{ matrix.package }}
+    needs: matrix
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.matrix.outputs.prebuilds) }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          package_json_file: package.json
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --filter node-addon-landlock-run-workspace... --frozen-lockfile
+
+      - name: Install musl toolchain
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -yq musl-tools
+
+      - name: Build native binaries
+        run: pnpm build:native
+
+      - name: Verify binary metadata
+        run: node ./scripts/verify-launcher-binary.mjs ${{ matrix.dir }}
+
+      - name: Upload prebuild artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: native/landlock-run/${{ matrix.dir }}/bin/*
+          if-no-files-found: error
+          retention-days: 7
+
+  pack:
+    name: Pack npm tarballs
+    needs: build-prebuilds
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          package_json_file: package.json
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --filter node-addon-landlock-run-workspace... --frozen-lockfile
+
+      - name: Build TypeScript
+        run: pnpm build:ts
+
+      - name: Verify release version
+        run: node ./scripts/verify-release.mjs
+        env:
+          RELEASE_PUBLISH: ${{ inputs.publish }}
+
+      - name: Download prebuild artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: prebuild-*
+          path: native/landlock-run/.release/prebuild-artifacts
+
+      - name: Assemble and verify prebuilds
+        run: node ./scripts/assemble-prebuilds.mjs .release/prebuild-artifacts
+
+      - name: Verify release payload
+        run: node ./scripts/verify-release.mjs --prebuilds
+        env:
+          RELEASE_PUBLISH: ${{ inputs.publish }}
+
+      - name: Pack release tarballs
+        run: node ./scripts/pack-release.mjs dist/npm
+
+      - name: Verify packed install
+        run: node ./scripts/verify-packed-install.mjs dist/npm
+        env:
+          NALR_REQUIRE_LANDLOCK: 1
+
+      - name: Upload npm tarballs
+        uses: actions/upload-artifact@v4
+        with:
+          name: npm-tarballs
+          path: native/landlock-run/dist/npm/*
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish to npm
+    if: inputs.publish
+    needs: pack
+    runs-on: ubuntu-24.04
+    environment: npm-publish
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Download npm tarballs
+        uses: actions/download-artifact@v4
+        with:
+          name: npm-tarballs
+          path: native/landlock-run/dist/npm
+
+      - name: Publish tarballs
+        run: |
+          version="${GITHUB_REF#refs/tags/landlock-run-v}"
+          tag_args=()
+          case "$version" in *-*) tag_args=(--tag next);; esac
+          while IFS= read -r tarball; do
+            npm publish "dist/npm/${tarball}" --access public "${tag_args[@]}"
+          done < dist/npm/publish-order.txt
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/.github/workflows/landlock-run.yml b/.github/workflows/landlock-run.yml
index dad9638761..391e1eeae1 100644
--- a/.github/workflows/landlock-run.yml
+++ b/.github/workflows/landlock-run.yml
@@ -1,15 +1,27 @@
-# Manually-dispatched CI for the landlock-run source of record
-# (native/landlock-run). A separate workflow from ci.yml on purpose: the
-# subtree is a self-contained pnpm workspace with its own gates, exercised on
-# demand — per-architecture native legs (build + behavioral tests + pack
-# rehearsal on real kernels) plus one darwin leg proving the documented
-# degradation on hosts without a platform package. Legs derive from the
-# subtree's checked-in package matrix (scripts/github-matrix.mjs). Packing
-# for npm happens in the release mirror (node-addon-landlock-run) after an
-# export — see native/README.md; this workflow never packs for release.
+# CI for the landlock-run packages under native/landlock-run. A separate
+# workflow from ci.yml keeps the native OS/architecture matrix independent of
+# the harness Node matrix. Release assembly and publication use the companion
+# Landlock Run Release workflow.
 name: Landlock Run
 
 on:
+  pull_request:
+    paths:
+      - '.github/workflows/landlock-run.yml'
+      - '.github/workflows/landlock-run-release.yml'
+      - 'native/landlock-run/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'pnpm-workspace.yaml'
+  push:
+    branches: [master]
+    paths:
+      - '.github/workflows/landlock-run.yml'
+      - '.github/workflows/landlock-run-release.yml'
+      - 'native/landlock-run/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'pnpm-workspace.yaml'
   workflow_dispatch:
 
 concurrency:
@@ -52,16 +64,16 @@ jobs:
 
       - uses: pnpm/action-setup@v4
         with:
-          package_json_file: native/landlock-run/package.json
+          package_json_file: package.json
 
       - uses: actions/setup-node@v4
         with:
           node-version: 24
           cache: pnpm
-          cache-dependency-path: native/landlock-run/pnpm-lock.yaml
+          cache-dependency-path: pnpm-lock.yaml
 
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: pnpm install --filter node-addon-landlock-run-workspace... --frozen-lockfile
 
       - name: Install musl toolchain
         run: |
@@ -103,16 +115,16 @@ jobs:
 
       - uses: pnpm/action-setup@v4
         with:
-          package_json_file: native/landlock-run/package.json
+          package_json_file: package.json
 
       - uses: actions/setup-node@v4
         with:
           node-version: 24
           cache: pnpm
-          cache-dependency-path: native/landlock-run/pnpm-lock.yaml
+          cache-dependency-path: pnpm-lock.yaml
 
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: pnpm install --filter node-addon-landlock-run-workspace... --frozen-lockfile
 
       - name: Build TypeScript
         run: pnpm build:ts
diff --git a/.github/workflows/sandbox.yml b/.github/workflows/sandbox.yml
index 939ca2f6ab..2dfaf0e175 100644
--- a/.github/workflows/sandbox.yml
+++ b/.github/workflows/sandbox.yml
@@ -3,9 +3,8 @@
 # .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md.
 # A separate workflow from ci.yml because the axis is different — these jobs
 # fan out over OS×runner (kernel capabilities), not node versions. The Landlock
-# launcher arrives from the registry with `pnpm install` (the npm package family
-# `node-addon-landlock-run`, built and released from its own repository), so
-# these legs exercise the true consumer path — nothing is compiled here.
+# launcher is built from native/landlock-run on each Landlock leg and installed
+# from the same tarballs the main-repository release workflow publishes.
 name: Sandbox
 
 on:
@@ -30,7 +29,7 @@ jobs:
   # an OS×runner matrix — bwrap and Landlock on Linux (separate legs: the
   # Landlock files force the bwrap rung off, so each leg proves exactly one
   # rung; Landlock twice, once per architecture, each confining through the
-  # registry-installed launcher), Seatbelt on macOS (sandbox-exec ships with
+  # locally built launcher), Seatbelt on macOS (sandbox-exec ships with
   # the OS). One node
   # version only: kernel confinement does not vary by node, and ci.yml's
   # node matrix already covers the node axis.
@@ -80,6 +79,14 @@ jobs:
           sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 \
             || echo "apparmor userns knob absent — the functional probe decides"
 
+      - name: Build Landlock launcher for this architecture
+        if: matrix.runner == 'landlock'
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -yq musl-tools
+          pnpm --dir native/landlock-run run build:ts
+          pnpm --dir native/landlock-run run build:native
+
       # The unit suite runs on ubuntu in `checks`; this is the one darwin leg
       # in the workflow, so run it here too — the platform-dependent unit
       # expectations (Seatbelt path canonicalization: /tmp IS /private/tmp)
@@ -105,14 +112,10 @@ jobs:
           # the very platform that exists to prove it) is a failure, not a pass.
           echo "$out" | grep -qE 'Test Files[[:space:]]+2 passed \(2\)'
 
-      # Publish-path rehearsal, Landlock legs only (the pack gates need built
-      # lib/). The e2e packs the workspace closure, installs the tarballs
-      # into a throwaway consumer — npm pulling `node-addon-landlock-run`
-      # and its platform package from the registry, the true consumer path —
-      # and confines through the INSTALLED launcher, asserting it executable
-      # apart (a mode-stripped binary must not masquerade as a non-enforcing
-      # kernel). Same no-silent-skip guard as above.
-      - name: Build packages (lib/ for the pack rehearsal)
+      # Publish-path rehearsal, Landlock legs only. Build the launcher on its
+      # native architecture, then install the local native and harness tarballs
+      # together so registry state cannot mask source/package drift.
+      - name: Build packages for the pack rehearsal
         if: matrix.runner == 'landlock'
         run: pnpm run build
 
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 7d2e257ea9..aa73dba8d9 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -170,6 +170,6 @@ Direct dependencies of the `pyproject.toml` manifests, plus `uv` as the developm
 | --- | --- | --- |
 | [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) | MIT | invoked by `scripts/build-exe-for-python-sdk.ts` to assemble the single-file SDK runtime executable |
 
-## First-party sibling releases
+## First-party native packages
 
-`node-addon-landlock-run` (and its platform packages) is released from a DeepSeek Harness sibling repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party.
+`node-addon-landlock-run` (and its platform packages) is built and released from this repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party.
diff --git a/knip.json b/knip.json
index dfb8058d7c..60853c6517 100644
--- a/knip.json
+++ b/knip.json
@@ -5,6 +5,7 @@
   ],
   "ignoreBinaries": [
     "bwrap",
+    "musl-gcc",
     "python3",
     "sandbox-exec",
     "taskkill"
diff --git a/native/README.i18n.yaml b/native/README.i18n.yaml
index a55273be29..31a86ebe73 100644
--- a/native/README.i18n.yaml
+++ b/native/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 native/README.md
-README.md: a79d9ca5747d4c4fbfa50745b3eece07b96aea58
-README.zh.md: 708430c0a087e5a9da1dae6fd078cb477db65d9b
+README.md: 51c8da7b57df15e65b8e431ee18ce6cebb89d54b
+README.zh.md: baf530157c6731893a66aea301c6dd962592defc
diff --git a/native/README.md b/native/README.md
index a79d9ca574..51c8da7b57 100644
--- a/native/README.md
+++ b/native/README.md
@@ -2,12 +2,10 @@
 
 English | [中文](README.zh.md)
 
-Source of record for `node-addon-landlock-run`, the Landlock self-restrict-then-exec launcher consumed by the harness. The [`landlock-run/` workspace](landlock-run/README.md) owns its architecture, package family, platform support, development workflow, and release procedure. The standalone repository is a release mirror.
+Native source and public packages maintained with DeepSeek Harness. The [`landlock-run/` workspace](landlock-run/README.md) owns the Landlock self-restrict-then-exec launcher consumed by the harness, including its architecture, three-package npm family, platform support, development workflow, and [release procedure](landlock-run/docs/release.md).
 
-## Release mirror
+## Workspace and release boundary
 
-| Directory | Mirror repo | Last exported release | Commit |
-|---|---|---|---|
-| `landlock-run/` | https://github.com/deepseek-harness/node-addon-landlock-run | `v0.0.1` | `614f7fd7dc11e6eaceefba9e7ff1fbe28b51ba22` |
+`landlock-run/` and its packages belong to the repository's root pnpm workspace and lockfile. Harness consumers use the current workspace entry package during development and CI, so a launcher contract change and its consumer update can land and be tested together.
 
-The subtree is a self-contained pnpm workspace and is not part of the harness workspace. The [launcher release reference](landlock-run/docs/release.md) owns the export and publication workflow. The mirror must not diverge: port any direct mirror hotfix back here before the next export.
+The main repository's `Landlock Run` workflow builds and tests each supported architecture. `Landlock Run Release` assembles those native artifacts, packs and verifies the three npm tarballs, then optionally publishes them under one launcher version. The entry package retains platform packages as npm optional dependencies, so npm still installs only the package matching the user's operating system and CPU.
diff --git a/native/README.zh.md b/native/README.zh.md
index 708430c0a0..baf530157c 100644
--- a/native/README.zh.md
+++ b/native/README.zh.md
@@ -2,12 +2,10 @@
 
 [English](README.md) | 中文
 
-`node-addon-landlock-run` 的真源；它是供 harness 使用、先施加 Landlock 自限再执行命令的启动器。[`landlock-run/` workspace](landlock-run/README.md)负责其架构、包家族、平台支持、开发工作流和发布流程。独立仓库是发布镜像。
+与 DeepSeek Harness 一同维护的原生源码和公开包。[`landlock-run/` workspace](landlock-run/README.md)负责 harness 使用的 Landlock 自限后执行启动器，包括其架构、由三个包组成的 npm 包家族、平台支持、开发工作流和[发布流程](landlock-run/docs/release.md)。
 
-## 发布镜像
+## Workspace 与发布边界
 
-| 目录 | 镜像仓库 | 最近导出的版本 | Commit |
-|---|---|---|---|
-| `landlock-run/` | https://github.com/deepseek-harness/node-addon-landlock-run | `v0.0.1` | `614f7fd7dc11e6eaceefba9e7ff1fbe28b51ba22` |
+`landlock-run/` 及其包属于仓库根 pnpm workspace，并共用根锁文件。开发和 CI 中的 harness 消费方直接使用当前 workspace 的入口包，因此启动器契约变更与消费方更新可以在同一个改动中落地并一起测试。
 
-该子树是自包含的 pnpm workspace，不属于 harness workspace。[启动器发布参考](landlock-run/docs/release.md)负责导出和发布工作流。镜像不得发生分歧：下次导出前，必须把任何直接施加于镜像的热修复移植回此处。
+主仓库的 `Landlock Run` 工作流为每个受支持架构构建并测试。`Landlock Run Release` 汇集这些原生产物，打包并验证三个 npm tarball，随后可选择以同一个启动器版本发布。入口包继续将平台包声明为 npm 可选依赖，因此 npm 仍然只会安装与用户操作系统和 CPU 匹配的包。
diff --git a/native/landlock-run/AGENTS.md b/native/landlock-run/AGENTS.md
index 31e12e177c..6742ff81d4 100644
--- a/native/landlock-run/AGENTS.md
+++ b/native/landlock-run/AGENTS.md
@@ -1,6 +1,6 @@
 # AGENTS.md
 
-This workspace builds `landlock-run`, a Landlock self-restrict-then-exec launcher: a small, auditable confinement binary distributed as prebuilt per-platform npm packages, plus the thin JS entry package that resolves it and speaks its CLI contract. The source of record is the `deepseek-harness` repository's `native/landlock-run/`; the `node-addon-landlock-run` repository is the release mirror this tree is exported to for packing and publishing (procedure: `native/README.md` in the harness repo). Make changes in the source of record, never only in the mirror.
+This directory builds `landlock-run`, a Landlock self-restrict-then-exec launcher: a small, auditable confinement binary distributed as prebuilt per-platform npm packages, plus the thin JS entry package that resolves it and speaks its CLI contract. It belongs to the repository's root pnpm workspace and lockfile. The main repository owns native CI, tarball assembly, verification, and npm publication; keep package-family changes coordinated with harness consumers in the same repository.
 
 ## Pre-release stance
 
diff --git a/native/landlock-run/docs/release.md b/native/landlock-run/docs/release.md
index e1ea65c411..a95cffd47f 100644
--- a/native/landlock-run/docs/release.md
+++ b/native/landlock-run/docs/release.md
@@ -4,45 +4,45 @@ Pre-1.0: treat this as a release checklist, not a stability policy.
 
 ## Versioning
 
-One version across every package in the repo. Use the bump helper:
+The launcher workspace root and its three public packages share one version. Run the bump helper from the repository root:
 
 ```sh
-pnpm release:bump patch          # or minor / major / x.y.z
+pnpm --dir native/landlock-run release:bump patch          # or minor / major / x.y.z
 ```
 
-It updates the root and every `packages/*` manifest, refreshes the lockfile (`--ignore-scripts --lockfile-only`), and runs `release:verify`. Explicit versions accept full semver including prereleases (`pnpm release:bump 0.0.0-test.0`); the publish workflow puts prerelease versions under the `next` dist-tag, so `latest` never points at a test build. Keep `workspace:*` dependencies in source; pnpm converts them to concrete versions during pack.
+It updates `native/landlock-run/package.json` and every `native/landlock-run/packages/*` manifest, refreshes the repository root lockfile (`--ignore-scripts --lockfile-only`), and runs `release:verify`. Explicit versions accept full semver including prereleases (`pnpm --dir native/landlock-run release:bump 0.0.0-test.0`); the publish workflow puts prerelease versions under the `next` dist-tag, so `latest` never points at a test build. Keep `workspace:*` dependencies in source; pnpm converts them to concrete versions during pack.
 
-Version bumps are normal source changes: open a release PR (or commit) with the manifests and lockfile, merge it, then create the matching `vX.Y.Z` tag from that commit. The publish workflow validates that the tag matches every package version.
+Version bumps are normal source changes: open a release PR (or commit) with the launcher manifests and root lockfile, merge it, then create the matching `landlock-run-vX.Y.Z` tag from that commit. The namespace avoids colliding with release tags for other package families in the repository. The publish workflow validates that the tag matches every launcher package version.
 
 ```sh
-pnpm release:commit patch        # bump + stage + commit in one command
-git tag v0.0.2
+pnpm --dir native/landlock-run release:commit patch        # bump + stage + commit in one command
+git tag landlock-run-v0.0.2
 ```
 
 ## Preflight
 
 ```sh
 pnpm install --frozen-lockfile
-pnpm build:ts
-pnpm typecheck
-pnpm test:entry
+pnpm --dir native/landlock-run build:ts
+pnpm --dir native/landlock-run typecheck
+pnpm --dir native/landlock-run test:entry
 ```
 
 On a Linux host, also rehearse the pack path locally:
 
 ```sh
-pnpm build:native
-pnpm test:launcher
-node ./scripts/pack-release.mjs .release/npm --current-platform-only
-node ./scripts/verify-packed-install.mjs .release/npm --current-platform-only
+pnpm --dir native/landlock-run build:native
+pnpm --dir native/landlock-run test:launcher
+node native/landlock-run/scripts/pack-release.mjs native/landlock-run/.release/npm --current-platform-only
+node native/landlock-run/scripts/verify-packed-install.mjs native/landlock-run/.release/npm --current-platform-only
 ```
 
 ## Publish
 
-Use the `Release` workflow so every binary is built on its matching native runner:
+Use the main repository's `Landlock Run Release` workflow so every binary is built on its matching native runner:
 
 1. Run it with `publish=false` (from the release commit) to build all platform binaries, assemble and verify the payloads, pack the tarballs in publish order, rehearse the packed install, and upload the `npm-tarballs` artifact for inspection.
-2. Create and push the `vX.Y.Z` tag matching the package versions.
+2. Create and push the `landlock-run-vX.Y.Z` tag matching the package versions.
 3. Run the same workflow from that tag with `publish=true`.
 
 The workflow publishes only from the final packed tarballs, in `publish-order.txt` order (platform packages before the entry that optionally depends on them). It supports npm trusted publishing through GitHub OIDC; without it, provide an `NPM_TOKEN` secret in the `npm-publish` environment. Packages publish with `--access public`.
@@ -50,9 +50,9 @@ The workflow publishes only from the final packed tarballs, in `publish-order.tx
 Manual local fallback (current platform's packages only) — always through `pack-release.mjs`, never `pnpm publish` directly (pnpm's pack path strips the launcher's executable bit; see [packaging.md](packaging.md)):
 
 ```sh
-node ./scripts/pack-release.mjs dist/npm --current-platform-only
-node ./scripts/verify-packed-install.mjs dist/npm --current-platform-only
-while IFS= read -r tarball; do npm publish "dist/npm/${tarball}" --access public; done < dist/npm/publish-order.txt
+node native/landlock-run/scripts/pack-release.mjs native/landlock-run/dist/npm --current-platform-only
+node native/landlock-run/scripts/verify-packed-install.mjs native/landlock-run/dist/npm --current-platform-only
+while IFS= read -r tarball; do npm publish "native/landlock-run/dist/npm/${tarball}" --access public; done < native/landlock-run/dist/npm/publish-order.txt
 ```
 
 Do not commit `.npmrc` files with tokens or registry overrides.
diff --git a/native/landlock-run/pnpm-lock.yaml b/native/landlock-run/pnpm-lock.yaml
deleted file mode 100644
index dd309fb046..0000000000
--- a/native/landlock-run/pnpm-lock.yaml
+++ /dev/null
@@ -1,345 +0,0 @@
-lockfileVersion: '9.0'
-
-settings:
-  autoInstallPeers: true
-  excludeLinksFromLockfile: false
-
-importers:
-
-  .:
-    devDependencies:
-      '@types/node':
-        specifier: ^26.0.1
-        version: 26.0.1
-      node-addon-landlock-run:
-        specifier: workspace:*
-        version: link:packages/entry
-      tsx:
-        specifier: ^4.20.6
-        version: 4.23.0
-      typescript:
-        specifier: ^6.0.3
-        version: 6.0.3
-
-  packages/entry:
-    optionalDependencies:
-      node-addon-landlock-run-linux-arm64:
-        specifier: workspace:*
-        version: link:../linux-arm64
-      node-addon-landlock-run-linux-x64:
-        specifier: workspace:*
-        version: link:../linux-x64
-
-  packages/linux-arm64: {}
-
-  packages/linux-x64: {}
-
-packages:
-
-  '@esbuild/aix-ppc64@0.28.1':
-    resolution: {integrity: sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==}
-    engines: {node: '>=18'}
-    cpu: [ppc64]
-    os: [aix]
-
-  '@esbuild/android-arm64@0.28.1':
-    resolution: {integrity: sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [android]
-
-  '@esbuild/android-arm@0.28.1':
-    resolution: {integrity: sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==}
-    engines: {node: '>=18'}
-    cpu: [arm]
-    os: [android]
-
-  '@esbuild/android-x64@0.28.1':
-    resolution: {integrity: sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [android]
-
-  '@esbuild/darwin-arm64@0.28.1':
-    resolution: {integrity: sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [darwin]
-
-  '@esbuild/darwin-x64@0.28.1':
-    resolution: {integrity: sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [darwin]
-
-  '@esbuild/freebsd-arm64@0.28.1':
-    resolution: {integrity: sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [freebsd]
-
-  '@esbuild/freebsd-x64@0.28.1':
-    resolution: {integrity: sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [freebsd]
-
-  '@esbuild/linux-arm64@0.28.1':
-    resolution: {integrity: sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [linux]
-
-  '@esbuild/linux-arm@0.28.1':
-    resolution: {integrity: sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==}
-    engines: {node: '>=18'}
-    cpu: [arm]
-    os: [linux]
-
-  '@esbuild/linux-ia32@0.28.1':
-    resolution: {integrity: sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==}
-    engines: {node: '>=18'}
-    cpu: [ia32]
-    os: [linux]
-
-  '@esbuild/linux-loong64@0.28.1':
-    resolution: {integrity: sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==}
-    engines: {node: '>=18'}
-    cpu: [loong64]
-    os: [linux]
-
-  '@esbuild/linux-mips64el@0.28.1':
-    resolution: {integrity: sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==}
-    engines: {node: '>=18'}
-    cpu: [mips64el]
-    os: [linux]
-
-  '@esbuild/linux-ppc64@0.28.1':
-    resolution: {integrity: sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==}
-    engines: {node: '>=18'}
-    cpu: [ppc64]
-    os: [linux]
-
-  '@esbuild/linux-riscv64@0.28.1':
-    resolution: {integrity: sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==}
-    engines: {node: '>=18'}
-    cpu: [riscv64]
-    os: [linux]
-
-  '@esbuild/linux-s390x@0.28.1':
-    resolution: {integrity: sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==}
-    engines: {node: '>=18'}
-    cpu: [s390x]
-    os: [linux]
-
-  '@esbuild/linux-x64@0.28.1':
-    resolution: {integrity: sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [linux]
-
-  '@esbuild/netbsd-arm64@0.28.1':
-    resolution: {integrity: sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [netbsd]
-
-  '@esbuild/netbsd-x64@0.28.1':
-    resolution: {integrity: sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [netbsd]
-
-  '@esbuild/openbsd-arm64@0.28.1':
-    resolution: {integrity: sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [openbsd]
-
-  '@esbuild/openbsd-x64@0.28.1':
-    resolution: {integrity: sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [openbsd]
-
-  '@esbuild/openharmony-arm64@0.28.1':
-    resolution: {integrity: sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [openharmony]
-
-  '@esbuild/sunos-x64@0.28.1':
-    resolution: {integrity: sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [sunos]
-
-  '@esbuild/win32-arm64@0.28.1':
-    resolution: {integrity: sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [win32]
-
-  '@esbuild/win32-ia32@0.28.1':
-    resolution: {integrity: sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==}
-    engines: {node: '>=18'}
-    cpu: [ia32]
-    os: [win32]
-
-  '@esbuild/win32-x64@0.28.1':
-    resolution: {integrity: sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [win32]
-
-  '@types/node@26.0.1':
-    resolution: {integrity: sha512-fc3KiUoBt6kie0N9bIW3E47vZsuaMf0PM2AaUpLCLT0s/LvX1nxAim6Fc049cNxODPpGm6qRAuUOB86SkRuPQw==}
-
-  esbuild@0.28.1:
-    resolution: {integrity: sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==}
-    engines: {node: '>=18'}
-    hasBin: true
-
-  fsevents@2.3.3:
-    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
-    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
-    os: [darwin]
-
-  tsx@4.23.0:
-    resolution: {integrity: sha512-eUdUIaCr963q2h5u3+QwvYp0+eqPvn+egeqZUm0hwERCqqx1E3kK5ehbGCvqSE5MQAULr67ww0cA3jKc3YkM1w==}
-    engines: {node: '>=18.0.0'}
-    hasBin: true
-
-  typescript@6.0.3:
-    resolution: {integrity: sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==}
-    engines: {node: '>=14.17'}
-    hasBin: true
-
-  undici-types@8.3.0:
-    resolution: {integrity: sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==}
-
-snapshots:
-
-  '@esbuild/aix-ppc64@0.28.1':
-    optional: true
-
-  '@esbuild/android-arm64@0.28.1':
-    optional: true
-
-  '@esbuild/android-arm@0.28.1':
-    optional: true
-
-  '@esbuild/android-x64@0.28.1':
-    optional: true
-
-  '@esbuild/darwin-arm64@0.28.1':
-    optional: true
-
-  '@esbuild/darwin-x64@0.28.1':
-    optional: true
-
-  '@esbuild/freebsd-arm64@0.28.1':
-    optional: true
-
-  '@esbuild/freebsd-x64@0.28.1':
-    optional: true
-
-  '@esbuild/linux-arm64@0.28.1':
-    optional: true
-
-  '@esbuild/linux-arm@0.28.1':
-    optional: true
-
-  '@esbuild/linux-ia32@0.28.1':
-    optional: true
-
-  '@esbuild/linux-loong64@0.28.1':
-    optional: true
-
-  '@esbuild/linux-mips64el@0.28.1':
-    optional: true
-
-  '@esbuild/linux-ppc64@0.28.1':
-    optional: true
-
-  '@esbuild/linux-riscv64@0.28.1':
-    optional: true
-
-  '@esbuild/linux-s390x@0.28.1':
-    optional: true
-
-  '@esbuild/linux-x64@0.28.1':
-    optional: true
-
-  '@esbuild/netbsd-arm64@0.28.1':
-    optional: true
-
-  '@esbuild/netbsd-x64@0.28.1':
-    optional: true
-
-  '@esbuild/openbsd-arm64@0.28.1':
-    optional: true
-
-  '@esbuild/openbsd-x64@0.28.1':
-    optional: true
-
-  '@esbuild/openharmony-arm64@0.28.1':
-    optional: true
-
-  '@esbuild/sunos-x64@0.28.1':
-    optional: true
-
-  '@esbuild/win32-arm64@0.28.1':
-    optional: true
-
-  '@esbuild/win32-ia32@0.28.1':
-    optional: true
-
-  '@esbuild/win32-x64@0.28.1':
-    optional: true
-
-  '@types/node@26.0.1':
-    dependencies:
-      undici-types: 8.3.0
-
-  esbuild@0.28.1:
-    optionalDependencies:
-      '@esbuild/aix-ppc64': 0.28.1
-      '@esbuild/android-arm': 0.28.1
-      '@esbuild/android-arm64': 0.28.1
-      '@esbuild/android-x64': 0.28.1
-      '@esbuild/darwin-arm64': 0.28.1
-      '@esbuild/darwin-x64': 0.28.1
-      '@esbuild/freebsd-arm64': 0.28.1
-      '@esbuild/freebsd-x64': 0.28.1
-      '@esbuild/linux-arm': 0.28.1
-      '@esbuild/linux-arm64': 0.28.1
-      '@esbuild/linux-ia32': 0.28.1
-      '@esbuild/linux-loong64': 0.28.1
-      '@esbuild/linux-mips64el': 0.28.1
-      '@esbuild/linux-ppc64': 0.28.1
-      '@esbuild/linux-riscv64': 0.28.1
-      '@esbuild/linux-s390x': 0.28.1
-      '@esbuild/linux-x64': 0.28.1
-      '@esbuild/netbsd-arm64': 0.28.1
-      '@esbuild/netbsd-x64': 0.28.1
-      '@esbuild/openbsd-arm64': 0.28.1
-      '@esbuild/openbsd-x64': 0.28.1
-      '@esbuild/openharmony-arm64': 0.28.1
-      '@esbuild/sunos-x64': 0.28.1
-      '@esbuild/win32-arm64': 0.28.1
-      '@esbuild/win32-ia32': 0.28.1
-      '@esbuild/win32-x64': 0.28.1
-
-  fsevents@2.3.3:
-    optional: true
-
-  tsx@4.23.0:
-    dependencies:
-      esbuild: 0.28.1
-    optionalDependencies:
-      fsevents: 2.3.3
-
-  typescript@6.0.3: {}
-
-  undici-types@8.3.0: {}
diff --git a/native/landlock-run/pnpm-workspace.yaml b/native/landlock-run/pnpm-workspace.yaml
deleted file mode 100644
index 22299bfea0..0000000000
--- a/native/landlock-run/pnpm-workspace.yaml
+++ /dev/null
@@ -1,8 +0,0 @@
-packages:
-  - packages/*
-
-# pnpm 10+ blocks any dependency shipping an install/build script until it is
-# explicitly reviewed here. Deny by default; esbuild (tsx's bundled native
-# binary) genuinely needs its script.
-allowBuilds:
-  esbuild: true
diff --git a/native/landlock-run/scripts/bump-release.mjs b/native/landlock-run/scripts/bump-release.mjs
index 29a7777379..55033eed09 100644
--- a/native/landlock-run/scripts/bump-release.mjs
+++ b/native/landlock-run/scripts/bump-release.mjs
@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * Bump every package (workspace root + packages/*) to one version, refresh
- * the lockfile, and verify. Usage: `pnpm release:bump <major|minor|patch|x.y.z>`.
+ * Bump the launcher workspace root and packages/* to one version, refresh the
+ * repository lockfile, and verify. Usage: `pnpm release:bump <major|minor|patch|x.y.z>`.
  */
 
 import fs from 'node:fs';
@@ -11,14 +11,15 @@ import { packageDirs, readJson, root } from './repo.mjs';
 
 const bump = process.argv[2];
 const releaseTypes = new Set(['major', 'minor', 'patch']);
+const repositoryRoot = path.resolve(root, '../..');
 
 function writeJson(file, value) {
   fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
 
-function run(command, args) {
+function run(command, args, cwd = root) {
   const result = spawnSync(command, args, {
-    cwd: root,
+    cwd,
     stdio: 'inherit',
     env: { ...process.env, CI: 'true' },
   });
@@ -84,7 +85,7 @@ for (const file of files) {
   console.log(`${file}: ${targetVersion}`);
 }
 
-run('pnpm', ['install', '--ignore-scripts', '--lockfile-only']);
+run('pnpm', ['install', '--ignore-scripts', '--lockfile-only'], repositoryRoot);
 run('node', ['./scripts/verify-release.mjs']);
 
 console.log(`Release version bumped to ${targetVersion}`);
diff --git a/native/landlock-run/scripts/commit-release.mjs b/native/landlock-run/scripts/commit-release.mjs
index b7bf3e513b..1b1c78bce5 100644
--- a/native/landlock-run/scripts/commit-release.mjs
+++ b/native/landlock-run/scripts/commit-release.mjs
@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 /**
  * Bump, stage, and commit a release in one command:
- * `pnpm release:commit <major|minor|patch|x.y.z>`. The tag stays manual —
- * create it from the merged release commit.
+ * `pnpm release:commit <major|minor|patch|x.y.z>`. The namespaced tag stays
+ * manual — create it from the merged release commit.
  */
 
 import path from 'node:path';
@@ -35,8 +35,8 @@ run('git', [
   'add',
   'package.json',
   'packages/*/package.json',
-  'pnpm-lock.yaml',
+  '../../pnpm-lock.yaml',
 ]);
-run('git', ['commit', '-m', `release: ${version}`]);
+run('git', ['commit', '-m', `release(landlock-run): ${version}`]);
 
-console.log(`Committed release ${version}. Create the tag manually: git tag v${version}`);
+console.log(`Committed release ${version}. Create the tag manually: git tag landlock-run-v${version}`);
diff --git a/native/landlock-run/scripts/repo.mjs b/native/landlock-run/scripts/repo.mjs
index 8032d3da37..db5ffaf28d 100644
--- a/native/landlock-run/scripts/repo.mjs
+++ b/native/landlock-run/scripts/repo.mjs
@@ -12,10 +12,10 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const root = fileURLToPath(new URL('..', import.meta.url));
-export const packagesRoot = path.join(root, 'packages');
+const packagesRoot = path.join(root, 'packages');
 
 /** ELF `e_machine` (offset 18, little-endian) per platform-package `cpu` value. */
-export const E_MACHINE = { x64: 62, arm64: 183 };
+const E_MACHINE = { x64: 62, arm64: 183 };
 
 export function readJson(file) {
   return JSON.parse(fs.readFileSync(file, 'utf8'));
diff --git a/native/landlock-run/scripts/verify-release.mjs b/native/landlock-run/scripts/verify-release.mjs
index e812b34a14..ff3917b4b5 100644
--- a/native/landlock-run/scripts/verify-release.mjs
+++ b/native/landlock-run/scripts/verify-release.mjs
@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 /**
  * Release verification. Always: every published package carries one shared
- * version, and — when running from a tag or publishing — the `vX.Y.Z` tag
- * matches it. With `--prebuilds`: every platform package's declared
+ * version, and — when running from a tag or publishing — the
+ * `landlock-run-vX.Y.Z` tag matches it. With `--prebuilds`: every platform package's declared
  * binaries exist with the right ELF architecture (run after
  * `assemble-prebuilds.mjs` or a local `build:native`).
  */
@@ -10,6 +10,8 @@
 import path from 'node:path';
 import { packageDirs, platformDirs, readJson, root, verifyPlatformBinaries } from './repo.mjs';
 
+const TAG_PREFIX = 'refs/tags/landlock-run-v';
+
 function verifyVersions() {
   const packages = packageDirs().map((dir) => ({
     dir,
@@ -26,13 +28,13 @@ function verifyVersions() {
   const version = packages[0].manifest.version;
   const ref = process.env.GITHUB_REF || '';
   const publish = process.env.RELEASE_PUBLISH === 'true';
-  if (publish && !ref.startsWith('refs/tags/v')) {
-    throw new Error('publishing requires running the workflow from a v* tag');
+  if (publish && !ref.startsWith(TAG_PREFIX)) {
+    throw new Error('publishing requires running the workflow from a landlock-run-v* tag');
   }
-  if (ref.startsWith('refs/tags/v')) {
-    const tagVersion = ref.slice('refs/tags/v'.length);
+  if (ref.startsWith(TAG_PREFIX)) {
+    const tagVersion = ref.slice(TAG_PREFIX.length);
     if (tagVersion !== version) {
-      throw new Error(`tag/version mismatch: tag v${tagVersion}, packages ${version}`);
+      throw new Error(`tag/version mismatch: tag landlock-run-v${tagVersion}, packages ${version}`);
     }
   }
 
diff --git a/package.json b/package.json
index 7bd84db93a..8340580e6d 100644
--- a/package.json
+++ b/package.json
@@ -10,6 +10,8 @@
   "workspaces": [
     "vendor/*",
     "packages/*/*",
+    "native/landlock-run",
+    "native/landlock-run/packages/*",
     "apps/*",
     "website"
   ],
diff --git a/packages/bash/bash-sandbox/package.json b/packages/bash/bash-sandbox/package.json
index e3d3c3deb3..6a29c3f6c8 100644
--- a/packages/bash/bash-sandbox/package.json
+++ b/packages/bash/bash-sandbox/package.json
@@ -41,6 +41,6 @@
     "@deepseek-ai/dsh-sandbox-local": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "cordis": "^4.0.0-rc.7",
-    "node-addon-landlock-run": "0.0.0-test.0"
+    "node-addon-landlock-run": "workspace:*"
   }
 }
diff --git a/packages/bash/bash-sandbox/tsconfig.json b/packages/bash/bash-sandbox/tsconfig.json
index fcd79e0296..7a7d67f0cb 100644
--- a/packages/bash/bash-sandbox/tsconfig.json
+++ b/packages/bash/bash-sandbox/tsconfig.json
@@ -14,6 +14,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../../native/landlock-run/packages/entry"
+    },
     {
       "path": "../../util/brand"
     },
diff --git a/packages/examples/agent-spine-demo/package.json b/packages/examples/agent-spine-demo/package.json
index a4b18b9c0c..b9f817d6e5 100644
--- a/packages/examples/agent-spine-demo/package.json
+++ b/packages/examples/agent-spine-demo/package.json
@@ -84,7 +84,7 @@
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-workspace-context": "workspace:^",
-    "node-addon-landlock-run": "0.0.0-test.0",
+    "node-addon-landlock-run": "workspace:*",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
diff --git a/packages/examples/agent-spine-demo/tsconfig.json b/packages/examples/agent-spine-demo/tsconfig.json
index 6a0091a6f6..f245e9f4d0 100644
--- a/packages/examples/agent-spine-demo/tsconfig.json
+++ b/packages/examples/agent-spine-demo/tsconfig.json
@@ -17,6 +17,9 @@
     {
       "path": "../../../vendor/schemastery"
     },
+    {
+      "path": "../../../native/landlock-run/packages/entry"
+    },
     {
       "path": "../../llm/llm"
     },
diff --git a/packages/sandbox/sandbox-local/package.json b/packages/sandbox/sandbox-local/package.json
index 2683ab3654..f7004c4d5c 100644
--- a/packages/sandbox/sandbox-local/package.json
+++ b/packages/sandbox/sandbox-local/package.json
@@ -31,7 +31,7 @@
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
-    "node-addon-landlock-run": "0.0.0-test.0",
+    "node-addon-landlock-run": "workspace:*",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
diff --git a/packages/sandbox/sandbox-local/tests/landlock.e2e.ts b/packages/sandbox/sandbox-local/tests/landlock.e2e.ts
index f5ecbc67f9..6e2faecc6b 100644
--- a/packages/sandbox/sandbox-local/tests/landlock.e2e.ts
+++ b/packages/sandbox/sandbox-local/tests/landlock.e2e.ts
@@ -10,7 +10,7 @@ import { launcherPath } from 'node-addon-landlock-run'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 
 /**
- * Keyless backend integration through `confine()` and the registry `landlock-run` launcher, with
+ * Keyless backend integration through `confine()` and the workspace `landlock-run` launcher, with
  * bwrap forced off. Tests assert real world effects; consumer coverage lives in dsh-bash-sandbox.
  * Skips when the platform package or enforcing kernel is unavailable. HOME-based workspaces avoid
  * Landlock's wholesale `/tmp` grant, so workspace-write proves the workspace-root grant itself.
diff --git a/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts b/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
index a032e1add7..caf0a32c68 100644
--- a/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
+++ b/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
@@ -7,20 +7,22 @@ import { fileURLToPath } from 'node:url'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 
 /**
- * Keyless publish-path rehearsal. It packs the package and workspace peers, installs those exact
- * tarballs in an external plain-Node consumer, and lets npm resolve the registry Landlock launcher
- * plus its platform package. No tsx, path mapping, or workspace resolution can hide missing files,
- * dependency errors, or lost executable modes.
+ * Keyless publish-path rehearsal. It packs the provider, its workspace peers, and the current
+ * repository's Landlock entry/platform packages, then installs those exact tarballs in an external
+ * plain-Node consumer. No registry copy, tsx, path mapping, or workspace resolution can hide
+ * missing files, dependency errors, or lost executable modes.
  *
  * The installed launcher must match the host architecture, remain executable, and either confine a
  * real process with bwrap disabled or fail closed on a non-enforcing kernel. Skips off Linux or
- * before `pnpm run build`; launcher byte provenance belongs to its upstream release pipeline.
+ * before the harness and native packages are built.
  */
 
 const packageDir = fileURLToPath(new URL('..', import.meta.url))
 const repoRoot = fileURLToPath(new URL('../../../..', import.meta.url))
+const nativeDir = join(repoRoot, 'native/landlock-run')
+const sourceLauncher = join(nativeDir, 'packages', `linux-${process.arch}`, 'bin', 'landlock-run')
 
-/** The closure the consumer needs: the package and its transitive `@deepseek-ai` peers; the launcher family arrives from the registry. */
+/** The harness closure the consumer needs; native tarballs are packed through their mode-preserving release script. */
 const WORKSPACE_CLOSURE = [
   'packages/sandbox/sandbox-local',
   'packages/sandbox/sandbox',
@@ -36,6 +38,8 @@ const E_MACHINE = { x64: 62, arm64: 183 }[process.arch as 'x64' | 'arm64']
 const packable = process.platform === 'linux'
   && E_MACHINE !== undefined
   && existsSync(join(packageDir, 'lib', 'index.js'))
+  && existsSync(join(nativeDir, 'packages/entry/lib/index.js'))
+  && existsSync(sourceLauncher)
 
 let consumerDir = ''
 let workDir = ''
@@ -57,7 +61,20 @@ describe.skipIf(!packable)('sandbox-local: packed-tarball distribution (publish-
     consumerDir = mkdtempSync(join(tmpdir(), 'dsh-packed-consumer-'))
     workDir = mkdtempSync(join(tmpdir(), 'dsh-packed-work-'))
 
-    // Pack each closure member with the exact bytes publish would upload.
+    const nativePackDest = join(packDest, 'native')
+    const nativePack = spawnSync('node', ['./scripts/pack-release.mjs', nativePackDest, '--current-platform-only'], {
+      cwd: nativeDir,
+      encoding: 'utf8',
+      timeout: 120_000,
+    })
+    expect(nativePack.status, `native pack failed:\n${nativePack.stdout}\n${nativePack.stderr}`).toBe(0)
+
+    const nativeTarballs = readFileSync(join(nativePackDest, 'publish-order.txt'), 'utf8')
+      .trim()
+      .split('\n')
+      .map(tarball => join(nativePackDest, tarball))
+
+    // Pack each harness closure member with the exact bytes publish would upload.
     const tarballs: string[] = []
     for (const pkg of WORKSPACE_CLOSURE) {
       const pack = spawnSync('pnpm', ['pack', '--pack-destination', packDest], {
@@ -69,6 +86,7 @@ describe.skipIf(!packable)('sandbox-local: packed-tarball distribution (publish-
       const lines = pack.stdout.trim().split('\n')
       tarballs.push(lines[lines.length - 1] as string)
     }
+    tarballs.push(...nativeTarballs)
 
     // Peer ranges resolve to the tarballs; Cordis is pinned to their peer range. Do not omit optional
     // dependencies because the launcher selects its OS/CPU package through one.
@@ -124,12 +142,13 @@ describe.skipIf(!packable)('sandbox-local: packed-tarball distribution (publish-
     await Promise.all([consumerDir, workDir].filter(Boolean).map(dir => rm(dir, { recursive: true, force: true })))
   })
 
-  it('installs the registry launcher for this host: present, EXECUTABLE, right ELF arch', () => {
+  it('installs this checkout\'s launcher for the host: present, executable, byte-identical, and right ELF arch', () => {
     const installed = join(consumerDir, 'node_modules', `node-addon-landlock-run-linux-${process.arch}`, 'bin', 'landlock-run')
     expect(existsSync(installed), 'platform package missing from the installed tree').toBe(true)
     // A tarball or extraction step that strips the mode bit would leave the
     // probe failing exactly like a non-enforcing kernel — assert it apart.
     expect(() => { accessSync(installed, constants.X_OK) }, 'installed launcher is not executable').not.toThrow()
+    expect(readFileSync(installed), 'installed launcher bytes').toEqual(readFileSync(sourceLauncher))
     expect(readFileSync(installed).readUInt16LE(18), 'ELF e_machine').toBe(E_MACHINE)
   })
 
diff --git a/packages/sandbox/sandbox-local/tsconfig.json b/packages/sandbox/sandbox-local/tsconfig.json
index 608f0e9568..7a41ffc5fd 100644
--- a/packages/sandbox/sandbox-local/tsconfig.json
+++ b/packages/sandbox/sandbox-local/tsconfig.json
@@ -17,6 +17,9 @@
     {
       "path": "../../../vendor/schemastery"
     },
+    {
+      "path": "../../../native/landlock-run/packages/entry"
+    },
     {
       "path": "../../llm/llm"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 01a5a2f64c..feedce51c0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -851,6 +851,34 @@ importers:
         specifier: workspace:*
         version: link:../packages/context/workspace-context
 
+  native/landlock-run:
+    devDependencies:
+      '@types/node':
+        specifier: ^26.0.1
+        version: 26.1.2
+      node-addon-landlock-run:
+        specifier: workspace:*
+        version: link:packages/entry
+      tsx:
+        specifier: ^4.20.6
+        version: 4.22.4
+      typescript:
+        specifier: ^6.0.3
+        version: 6.0.3
+
+  native/landlock-run/packages/entry:
+    optionalDependencies:
+      node-addon-landlock-run-linux-arm64:
+        specifier: workspace:*
+        version: link:../linux-arm64
+      node-addon-landlock-run-linux-x64:
+        specifier: workspace:*
+        version: link:../linux-x64
+
+  native/landlock-run/packages/linux-arm64: {}
+
+  native/landlock-run/packages/linux-x64: {}
+
   packages/acp/acp:
     dependencies:
       '@agentclientprotocol/sdk':
@@ -986,8 +1014,8 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
       node-addon-landlock-run:
-        specifier: 0.0.0-test.0
-        version: 0.0.0-test.0
+        specifier: workspace:*
+        version: link:../../../native/landlock-run/packages/entry
 
   packages/bash/pwsh-local:
     dependencies:
@@ -1306,7 +1334,7 @@ importers:
         version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       vitest:
         specifier: ^4.1.8
-        version: 4.1.8(@opentelemetry/api@1.9.1)(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
+        version: 4.1.8(@opentelemetry/api@1.9.1)(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
     devDependencies:
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
@@ -2939,8 +2967,8 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
       node-addon-landlock-run:
-        specifier: 0.0.0-test.0
-        version: 0.0.0-test.0
+        specifier: workspace:*
+        version: link:../../../native/landlock-run/packages/entry
 
   packages/examples/cli-demo:
     devDependencies:
@@ -4219,8 +4247,8 @@ importers:
   packages/sandbox/sandbox-local:
     dependencies:
       node-addon-landlock-run:
-        specifier: 0.0.0-test.0
-        version: 0.0.0-test.0
+        specifier: workspace:*
+        version: link:../../../native/landlock-run/packages/entry
       schemastery:
         specifier: ^3.18.0
         version: link:../../../vendor/schemastery
@@ -5464,7 +5492,7 @@ importers:
         version: link:../loader-smoke
       vitest:
         specifier: ^4.1.8
-        version: 4.1.8(@opentelemetry/api@1.9.0)(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
+        version: 4.1.8(@opentelemetry/api@1.9.0)(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
     devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
@@ -9113,6 +9141,9 @@ packages:
   '@types/node@25.9.3':
     resolution: {integrity: sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg==}
 
+  '@types/node@26.1.2':
+    resolution: {integrity: sha512-Vu4a5UFA9rIIFJ7rB/Vaafh9lrCQszopTCx6KjFboXTGQbPNasehVR5TEiithSDGyd1DEiUByggTZsg8jukeIg==}
+
   '@types/picomatch@3.0.2':
     resolution: {integrity: sha512-n0i8TD3UDB7paoMMxA3Y65vUncFJXjcUf7lQY7YyKGl6031FNjfsLs6pdLFCy2GNFxItPJG8GvvpbZc2skH7WA==}
 
@@ -11011,22 +11042,6 @@ packages:
   node-addon-api@7.1.1:
     resolution: {integrity: sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==}
 
-  node-addon-landlock-run-linux-arm64@0.0.0-test.0:
-    resolution: {integrity: sha512-oJsXcC33qKl9mWYx0n9YPJ2pUAoY39PoIX0Gx4lDrSCTEvENFrEaODAsQYNY+eEGpn9YMN7E+FOftvea3/1FqQ==}
-    engines: {node: '>=20'}
-    cpu: [arm64]
-    os: [linux]
-
-  node-addon-landlock-run-linux-x64@0.0.0-test.0:
-    resolution: {integrity: sha512-eXvdfnH/UV55MTZzroKvM3CD68SP5OlCsuth908YOcJOnn0LPD5KJjmBz6ToDlBYjF52NNK62+g7TvmUWjbKWQ==}
-    engines: {node: '>=20'}
-    cpu: [x64]
-    os: [linux]
-
-  node-addon-landlock-run@0.0.0-test.0:
-    resolution: {integrity: sha512-c5qopltRonjW6+VinXYMp4FVi9Sxf8eQEb/9G82EksQQ+JC4CDprv+ko5URWmtyZ3wD4GFdeRTyw1AG5yCwJhQ==}
-    engines: {node: '>=20'}
-
   node-addon-native-custom-loader@0.1.4:
     resolution: {integrity: sha512-DreegO6EoC1JHWYBv3j8Miwp2Zl/CyBeNyoeyCbnEdjyYFEulR4Gcb3wj9fXF7KMDY0ZJ5MWwHcXP8GVNyScnA==}
     engines: {node: '>=20'}
@@ -11815,6 +11830,9 @@ packages:
   undici-types@7.24.6:
     resolution: {integrity: sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==}
 
+  undici-types@8.3.0:
+    resolution: {integrity: sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==}
+
   undici@7.28.0:
     resolution: {integrity: sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==}
     engines: {node: '>=20.18.1'}
@@ -14189,6 +14207,10 @@ snapshots:
     dependencies:
       undici-types: 7.24.6
 
+  '@types/node@26.1.2':
+    dependencies:
+      undici-types: 8.3.0
+
   '@types/picomatch@3.0.2': {}
 
   '@types/prop-types@15.7.15': {}
@@ -14344,13 +14366,13 @@ snapshots:
     optionalDependencies:
       vite: 8.0.16(@types/node@22.20.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)
 
-  '@vitest/mocker@4.1.8(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))':
+  '@vitest/mocker@4.1.8(vite@8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))':
     dependencies:
       '@vitest/spy': 4.1.8
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)
+      vite: 8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)
 
   '@vitest/pretty-format@4.1.8':
     dependencies:
@@ -16476,17 +16498,6 @@ snapshots:
 
   node-addon-api@7.1.1: {}
 
-  node-addon-landlock-run-linux-arm64@0.0.0-test.0:
-    optional: true
-
-  node-addon-landlock-run-linux-x64@0.0.0-test.0:
-    optional: true
-
-  node-addon-landlock-run@0.0.0-test.0:
-    optionalDependencies:
-      node-addon-landlock-run-linux-arm64: 0.0.0-test.0
-      node-addon-landlock-run-linux-x64: 0.0.0-test.0
-
   node-addon-native-custom-loader@0.1.4: {}
 
   node-addon-require-builtin-darwin-arm64@0.1.4:
@@ -17398,6 +17409,8 @@ snapshots:
 
   undici-types@7.24.6: {}
 
+  undici-types@8.3.0: {}
+
   undici@7.28.0: {}
 
   unicorn-magic@0.3.0: {}
@@ -17533,7 +17546,7 @@ snapshots:
       tsx: 4.22.4
       yaml: 2.9.0
 
-  vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0):
+  vite@8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0):
     dependencies:
       lightningcss: 1.32.0
       picomatch: 4.0.4
@@ -17541,7 +17554,7 @@ snapshots:
       rolldown: 1.0.3
       tinyglobby: 0.2.17
     optionalDependencies:
-      '@types/node': 25.9.3
+      '@types/node': 26.1.2
       esbuild: 0.28.1
       fsevents: 2.3.3
       jiti: 2.7.0
@@ -17635,10 +17648,10 @@ snapshots:
     transitivePeerDependencies:
       - msw
 
-  vitest@4.1.8(@opentelemetry/api@1.9.0)(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)):
+  vitest@4.1.8(@opentelemetry/api@1.9.0)(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.8
-      '@vitest/mocker': 4.1.8(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
+      '@vitest/mocker': 4.1.8(vite@8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
       '@vitest/pretty-format': 4.1.8
       '@vitest/runner': 4.1.8
       '@vitest/snapshot': 4.1.8
@@ -17655,7 +17668,7 @@ snapshots:
       tinyexec: 1.2.4
       tinyglobby: 0.2.17
       tinyrainbow: 3.1.0
-      vite: 8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)
+      vite: 8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
@@ -17695,10 +17708,10 @@ snapshots:
     transitivePeerDependencies:
       - msw
 
-  vitest@4.1.8(@opentelemetry/api@1.9.1)(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)):
+  vitest@4.1.8(@opentelemetry/api@1.9.1)(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.8
-      '@vitest/mocker': 4.1.8(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
+      '@vitest/mocker': 4.1.8(vite@8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
       '@vitest/pretty-format': 4.1.8
       '@vitest/runner': 4.1.8
       '@vitest/snapshot': 4.1.8
@@ -17715,7 +17728,7 @@ snapshots:
       tinyexec: 1.2.4
       tinyglobby: 0.2.17
       tinyrainbow: 3.1.0
-      vite: 8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)
+      vite: 8.0.16(@types/node@26.1.2)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@opentelemetry/api': 1.9.1
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index fec185b114..66510d89ec 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,6 +1,10 @@
 packages:
   - vendor/*
   - packages/*/*
+  # The Landlock launcher is developed with its harness consumers but keeps
+  # its native build and publication scripts under native/landlock-run.
+  - native/landlock-run
+  - native/landlock-run/packages/*
   # Product assemblies over the package tier; apps/cli owns the `dsh` bin.
   - apps/*
   - website
@@ -46,14 +50,7 @@ allowBuilds:
   # restores the executable bit on node-pty's macOS spawn helper.
   '@deepseek-ai/dsh-pty-local@file:packages/pty/pty-local': true
 
-# The Landlock launcher family is our own sibling-repo release, consumed
-# fresh (hours old at each coordinated bump) — the release-age quarantine
-# would block every such bump, so the family is exempted BY NAME, not by
-# pinned version.
 minimumReleaseAgeExclude:
-  - node-addon-landlock-run
-  - node-addon-landlock-run-linux-arm64
-  - node-addon-landlock-run-linux-x64
   # Cordis release candidates are source-vendored and pinned in vendor/README.md
   # during the same-day sync that updates package manifests and the lockfile.
   - '@cordisjs/plugin-loader@1.0.0-rc.5'
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 6bd613c2ea..32e2096aa9 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -15,6 +15,8 @@ const root = resolve(import.meta.dirname, '..')
 const workspaceGlobs = [
   { dir: 'vendor', depth: 1 },
   { dir: 'packages', depth: 2 },
+  { dir: 'native', depth: 1 },
+  { dir: 'native/landlock-run/packages', depth: 1 },
   { dir: 'apps', depth: 1 },
 ] as const
 const vendoredPackages = new Set([
@@ -28,6 +30,11 @@ const vendoredPackages = new Set([
   '@cordisjs/plugin-hmr',
   '@cordisjs/plugin-logger-console',
 ])
+const publicLandlockPackages = new Set([
+  'node-addon-landlock-run',
+  'node-addon-landlock-run-linux-arm64',
+  'node-addon-landlock-run-linux-x64',
+])
 
 const localArtifactDirs = new Set(['node_modules'])
 const appPackageFiles: Readonly<Record<string, readonly string[]>> = {
@@ -55,6 +62,7 @@ interface PackageManifest {
     | undefined
   >
   files?: string[]
+  publishConfig?: { access?: string }
   peerDependencies?: Record<string, string>
   devDependencies?: Record<string, string>
 }
@@ -71,6 +79,8 @@ function readJson(path: string): PackageManifest {
 
 const rootManifest = readJson(join(root, 'package.json'))
 const repositoryVersion = rootManifest.version
+const landlockWorkspaceManifest = readJson(join(root, 'native/landlock-run/package.json'))
+const landlockVersion = landlockWorkspaceManifest.version
 
 /** Repo-relative dirs holding a package.json, walked to the configured depth. */
 function packageDirs(base: string, depth: number): string[] {
@@ -161,8 +171,19 @@ function usesEmittedTreeDefaults(manifest: PackageManifest): boolean {
 function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
   const errors: string[] = []
   const label = manifest.name ?? dir
+  const isLandlockPackageDir = dir.startsWith('native/landlock-run/packages/')
+  const isPublicLandlockPackage = isLandlockPackageDir
+    && manifest.name !== undefined
+    && publicLandlockPackages.has(manifest.name)
 
-  if (manifest.private !== true) {
+  if (isPublicLandlockPackage) {
+    if (manifest.private === true) {
+      errors.push(`${label}: published Landlock package must not set "private": true`)
+    }
+    if (manifest.publishConfig?.access !== 'public') {
+      errors.push(`${label}: published Landlock package must set publishConfig.access to "public"`)
+    }
+  } else if (manifest.private !== true) {
     errors.push(`${label}: package.json must set "private": true`)
   }
 
@@ -187,6 +208,15 @@ function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
     }
   }
 
+  if (isLandlockPackageDir) {
+    if (!isPublicLandlockPackage) {
+      errors.push(`${label}: unexpected package in the public Landlock package family`)
+    }
+    if (manifest.version !== landlockVersion) {
+      errors.push(`${label}: package.json version must match Landlock workspace version ${landlockVersion ?? '(missing)'}`)
+    }
+  }
+
   if (dir.startsWith('packages/') && manifest.name?.startsWith('@deepseek-ai/dsh-')) {
     const peer = manifest.peerDependencies?.cordis
     const dev = manifest.devDependencies?.cordis
diff --git a/scripts/clean.spec.ts b/scripts/clean.spec.ts
index 0a46764d9a..aada0667ef 100644
--- a/scripts/clean.spec.ts
+++ b/scripts/clean.spec.ts
@@ -18,10 +18,10 @@ function write(path: string, content = ''): void {
   writeFileSync(path, content)
 }
 
-function addProject(root: string, path: string): void {
+function addProject(root: string, path: string, outDir = 'lib/types'): void {
   write(join(root, 'tsconfig.json'), JSON.stringify({ files: [], references: [{ path }] }))
   write(join(root, path, 'tsconfig.json'), JSON.stringify({
-    compilerOptions: { composite: true, outDir: 'lib/types' },
+    compilerOptions: { composite: true, outDir },
     include: ['src'],
   }))
   write(join(root, path, 'src/index.ts'), 'export {}\n')
@@ -60,6 +60,18 @@ describe('RepositoryCleaner', () => {
     expect(existsSync(join(root, 'products/shell/lib'))).toBe(true)
   })
 
+  it('removes the native Landlock entry output that emits directly to lib', async () => {
+    const root = fixture()
+    const entry = 'native/landlock-run/packages/entry'
+    addProject(root, entry, 'lib')
+    write(join(root, entry, 'lib/index.js'))
+
+    await new RepositoryCleaner(root).clean()
+
+    expect(existsSync(join(root, entry, 'lib'))).toBe(false)
+    expect(existsSync(join(root, entry, 'src/index.ts'))).toBe(true)
+  })
+
   it('refuses project outputs reached through a symlink outside the repository', async () => {
     const root = fixture()
     const externalProject = fixture()
diff --git a/scripts/clean.ts b/scripts/clean.ts
index fff158c458..1224fe8420 100644
--- a/scripts/clean.ts
+++ b/scripts/clean.ts
@@ -114,6 +114,7 @@ export class RepositoryCleaner {
     const outputs = new Set<string>()
     const pending = [join(this.root, 'tsconfig.json')]
     const visited = new Set<string>()
+    const nativeEntryOutput = join(this.root, 'native/landlock-run/packages/entry/lib')
 
     while (pending.length > 0) {
       const nextConfigPath = pending.pop()
@@ -125,10 +126,14 @@ export class RepositoryCleaner {
       const parsed = parseConfig(configPath)
       if (parsed.options.outDir !== undefined) {
         const typesDirectory = resolve(parsed.options.outDir)
-        if (basename(typesDirectory) !== 'types') {
+        const outputDirectory = basename(typesDirectory) === 'types'
+          ? dirname(typesDirectory)
+          : typesDirectory === nativeEntryOutput
+            ? typesDirectory
+            : undefined
+        if (outputDirectory === undefined) {
           throw new Error(`clean: expected TypeScript outDir to end in /types: ${repositoryPath(this.root, typesDirectory)}`)
         }
-        const outputDirectory = dirname(typesDirectory)
         this.assertRepositoryTarget(outputDirectory)
         outputs.add(outputDirectory)
       }
diff --git a/scripts/gen-third-party-notices.spec.ts b/scripts/gen-third-party-notices.spec.ts
index f31cca6879..6db1f6ea8d 100644
--- a/scripts/gen-third-party-notices.spec.ts
+++ b/scripts/gen-third-party-notices.spec.ts
@@ -247,13 +247,13 @@ describe('isPermissive', () => {
 
 describe('manifestPatterns', () => {
   it('derives globs from the declared members, so a new member area is read', () => {
-    expect(manifestPatterns(['packages/*/*', 'tools/*'], ['packages/*'])).toEqual([
+    expect(manifestPatterns(['packages/*/*', 'tools/*', 'native/landlock-run', 'native/landlock-run/packages/*'])).toEqual([
       'package.json',
       'packages/*/*/package.json',
       'tools/*/package.json',
-      'examples/*/package.json',
       'native/landlock-run/package.json',
       'native/landlock-run/packages/*/package.json',
+      'examples/*/package.json',
     ])
   })
 })
diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts
index 0d41953e4b..d7e0c26a5f 100644
--- a/scripts/gen-third-party-notices.ts
+++ b/scripts/gen-third-party-notices.ts
@@ -39,10 +39,7 @@ const DEV_ONLY_AREAS = [
   'native/',
 ] as const
 
-/**
- * First-party packages released from sibling repositories under the project's
- * own license: reachable from workspace manifests but not third-party.
- */
+/** First-party public native packages: reachable at runtime but not third-party. */
 const FIRST_PARTY = new Set([
   'node-addon-landlock-run',
   'node-addon-landlock-run-linux-arm64',
@@ -119,16 +116,13 @@ function readManifest(rel: string): Manifest {
  * here, so a new member area (`tools/*`) is read the day it is declared.
  * @returns one glob per manifest-bearing location, repository-relative.
  */
-export function manifestPatterns(rootMembers: readonly string[], nativeMembers: readonly string[]): string[] {
+export function manifestPatterns(rootMembers: readonly string[]): string[] {
   return [
     'package.json',
     ...rootMembers.map(member => `${member}/package.json`),
     // The demo leaves join the workspace through `examples/package.json`, so
     // their own manifests are members of nothing and no glob above reaches them.
     'examples/*/package.json',
-    // `native/landlock-run` is a nested workspace with its own lock file.
-    'native/landlock-run/package.json',
-    ...nativeMembers.map(member => `native/landlock-run/${member}/package.json`),
   ]
 }
 
@@ -149,7 +143,7 @@ function workspaceMembers(rel: string): string[] {
  * would silently push dev-area manifests into the runtime tier.
  */
 function loadWorkspaceManifests(): { manifests: Map<string, Manifest>; names: Set<string> } {
-  const patterns = manifestPatterns(workspaceMembers('pnpm-workspace.yaml'), workspaceMembers('native/landlock-run/pnpm-workspace.yaml'))
+  const patterns = manifestPatterns(workspaceMembers('pnpm-workspace.yaml'))
   const manifests = new Map<string, Manifest>()
   const names = new Set<string>()
   for (const pattern of patterns) {
@@ -591,9 +585,9 @@ ${python.map(dep => `| [\`${dep.name}\`](${dep.repo}) | ${dep.license} | ${dep.r
 | --- | --- | --- |
 ${BUILD_TIME_TOOLS.map(tool => `| [\`${tool.name}\`](${tool.repo}) | ${tool.license} | ${tool.role} |`).join('\n')}
 
-## First-party sibling releases
+## First-party native packages
 
-\`node-addon-landlock-run\` (and its platform packages) is released from a DeepSeek Harness sibling repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party.
+\`node-addon-landlock-run\` (and its platform packages) is built and released from this repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party.
 `
 }
 
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 9ba9ba5d84..634464cb9b 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -38,6 +38,7 @@
       "@cordisjs/plugin-timer": ["./vendor/timer/src"],
       "@cordisjs/plugin-hmr": ["./vendor/hmr/src"],
       "@cordisjs/plugin-logger-console": ["./vendor/logger-console/src"],
+      "node-addon-landlock-run": ["./native/landlock-run/packages/entry/src/index.ts"],
       "@deepseek-ai/dsh-invariants": ["./packages/support/invariants/src/index.ts"],
       "@deepseek-ai/dsh-typert-registry": ["./packages/typert/registry/src/index.ts"],
       "@deepseek-ai/dsh-typert-loader": ["./packages/typert/loader/src/index.ts"],
diff --git a/tsconfig.host.json b/tsconfig.host.json
index c13d480a46..f6b125339a 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -156,6 +156,7 @@
     { "path": "./packages/bash/bash-env" },
     { "path": "./packages/bash/pwsh-local" },
     { "path": "./packages/bash/tool-pwsh" },
+    { "path": "./native/landlock-run/packages/entry" },
     { "path": "./packages/sandbox/sandbox" },
     { "path": "./packages/sandbox/sandbox-local" },
     { "path": "./packages/sandbox/sandbox-policy" },

From d3aa337c26806d14e45faf1319bb3d2ceada6cd5 Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 10:52:46 +0800
Subject: [PATCH 039/516] fix(landlock-run): close release integration gaps
 (review round 2)

---
 ...2026-07-27-dependabot-version-updates.i18n.yaml |  4 ++--
 .../2026-07-27-dependabot-version-updates.md       | 10 +++++-----
 .../2026-07-27-dependabot-version-updates.zh.md    | 10 +++++-----
 ...6-07-30-generated-third-party-notices.i18n.yaml |  4 ++--
 .../2026-07-30-generated-third-party-notices.md    |  2 +-
 .../2026-07-30-generated-third-party-notices.zh.md |  2 +-
 .github/dependabot.yml                             | 14 --------------
 THIRD_PARTY_NOTICES.md                             |  2 +-
 native/landlock-run/packages/entry/package.json    |  5 +++++
 .../landlock-run/packages/linux-arm64/package.json |  5 +++++
 .../landlock-run/packages/linux-x64/package.json   |  5 +++++
 scripts/check-workspace-constraints.ts             | 12 ++++++++++--
 scripts/gen-third-party-notices.ts                 |  8 ++++----
 13 files changed, 46 insertions(+), 37 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.i18n.yaml
index 07c742c518..316c31771e 100644
--- a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.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 .agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
-2026-07-27-dependabot-version-updates.md: 725649652c5b91ba4897d03b548b9aa5c3694c21
-2026-07-27-dependabot-version-updates.zh.md: 6400ba8ed94bf138fcece90e5d7ff82886d33ed1
+2026-07-27-dependabot-version-updates.md: 5d42563788d9f1e72da65c8e9750d6b1ecba06a5
+2026-07-27-dependabot-version-updates.zh.md: 4847059944e7e35de5719a6cbfd3d5b133467ccb
diff --git a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
index 725649652c..5d42563788 100644
--- a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
+++ b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
@@ -6,23 +6,23 @@ English | [中文](2026-07-27-dependabot-version-updates.zh.md)
 
 ## Problem
 
-Maintained registry and GitHub Actions dependencies need a regular update path. Adopting every release immediately increases exposure to compromised releases and early regressions, while leaving updates entirely manual lets dependency drift accumulate. Vendored Cordis sources and independently locked workspaces also cannot be treated as one undifferentiated package tree.
+Maintained registry and GitHub Actions dependencies need a regular update path. Adopting every release immediately increases exposure to compromised releases and early regressions, while leaving updates entirely manual lets dependency drift accumulate. Vendored Cordis sources cannot be treated like registry dependencies, and workspaces sharing one lockfile must be updated through the same package tree.
 
 ## Decision
 
-The default branch carries [`.github/dependabot.yml`](../../../../.github/dependabot.yml) with weekly version-update checks for the root pnpm workspace, the independently locked `native/landlock-run` pnpm workspace, the `python/sdk` uv project, and GitHub Actions. Every entry sets `cooldown.default-days` to `30`, so a version release becomes eligible only after it is at least 30 days old and is proposed on the next weekly check.
+The default branch carries [`.github/dependabot.yml`](../../../../.github/dependabot.yml) with weekly version-update checks for the root pnpm workspace, including `native/landlock-run`, the `python/sdk` uv project, and GitHub Actions. Every entry sets `cooldown.default-days` to `30`, so a version release becomes eligible only after it is at least 30 days old and is proposed on the next weekly check. The [in-repository Landlock release decision](2026-08-06-in-repository-landlock-release.md) owns the shared-workspace boundary.
 
-The root pnpm version-update scan excludes `vendor/**`, whose source and manifests move only through the [vendoring procedure](../../../../vendor/README.md), and `native/landlock-run/**`, which its dedicated entry owns. GitHub applies `exclude-paths` only to version updates; a security pull request that touches a vendored manifest is replaced through the vendoring procedure instead of being merged as generated. Dependabot pull requests receive the repository's `cleanup` kind and `area/infra` area labels, run the normal pull-request checks, and remain subject to maintainer review; this automation does not merge them.
+The root pnpm version-update scan excludes `vendor/**`, whose source and manifests move only through the [vendoring procedure](../../../../vendor/README.md). GitHub applies `exclude-paths` only to version updates; a security pull request that touches a vendored manifest is replaced through the vendoring procedure instead of being merged as generated. Dependabot pull requests receive the repository's `cleanup` kind and `area/infra` area labels, run the normal pull-request checks, and remain subject to maintainer review; this automation does not merge them.
 
 Repository settings enable dependency vulnerability alerts and Dependabot security updates. GitHub does not apply version-update cooldowns to those security updates, so security fixes remain eligible immediately. A generated pnpm security pull request can still fail the repository's lockfile release-age verification when dependency resolution selects unrelated fresh transitive versions; that pull request waits or is narrowed instead of weakening the policy. The repository's coordinated fresh-release exceptions are not copied into Dependabot's cooldown exclusions: automated version updates use the uniform 30-day wait, while an explicitly reviewed manual update can still follow its owning release procedure.
 
-The pnpm entries keep both workspaces on their pinned pnpm 11 instead of introducing an automation-only downgrade. The current Dependabot updater installs the version requested by `packageManager` and reads both workspaces' lockfile format `9.0`; the provider-run update job remains the integration check.
+The pnpm entry keeps the unified workspace on its pinned pnpm 11 instead of introducing an automation-only downgrade. The current Dependabot updater installs the version requested by the root `packageManager` and reads the root lockfile format `9.0`; the provider-run update job remains the integration check.
 
 ## Alternatives considered
 
 - **Immediate version updates.** Rejected because they remove the requested release-age quarantine and make the project an early consumer of every upstream release.
 - **Automatic merging after CI.** Rejected because dependency changes can alter runtime, build, and release behavior; the normal review decision remains part of accepting an update.
-- **One recursive npm scan.** Rejected because it could admit vendored manifests or conflate the root and native lockfiles. Explicit exclusions and a dedicated native entry preserve their ownership boundaries.
+- **A separate native npm scan.** Rejected because the Landlock manifests belong to the root workspace and lockfile; splitting their update would recreate an ownership boundary the package manager no longer has. The root scan excludes only vendored manifests.
 - **Renovate or a scheduled agent.** Both can propose aged updates, but Dependabot is the requested service and the repository's CI already recognizes its pull requests as an untrusted dependency source.
 - **Cooldown exemptions for coordinated fresh releases.** Rejected for the automated path because those releases require an explicit synchronization or model-catalog decision rather than a generic update proposal.
 
diff --git a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md
index 6400ba8ed9..4847059944 100644
--- a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md
@@ -6,23 +6,23 @@ Status: implemented
 
 ## 问题
 
-来自包注册表的依赖与 GitHub Actions 依赖都需要定期更新机制。每个新版本一经发布便立即采用，会增加受到遭入侵的版本和早期回归影响的风险；但完全依靠手动更新，又会导致依赖版本差距持续扩大。以源码形式纳入仓库的 Cordis 与各自维护独立锁文件的工作区，也不能不加区分地视为同一棵包树。
+来自包注册表的依赖与 GitHub Actions 依赖都需要定期更新机制。每个新版本一经发布便立即采用，会增加受到遭入侵的版本和早期回归影响的风险；但完全依靠手动更新，又会导致依赖版本差距持续扩大。以源码形式纳入仓库的 Cordis 不能当作注册表依赖处理，而共用一份锁文件的工作区必须通过同一棵包树更新。
 
 ## 决策
 
-默认分支包含 [`.github/dependabot.yml`](../../../../.github/dependabot.yml)，其中为根 pnpm 工作区、独立维护锁文件的 `native/landlock-run` pnpm 工作区、`python/sdk` uv 项目和 GitHub Actions 配置了每周一次的版本更新检查。每个更新项都将 `cooldown.default-days` 设为 `30`，因此某个版本只有在发布至少 30 天后才符合更新条件，并会在下一次每周检查时生成更新提案。
+默认分支包含 [`.github/dependabot.yml`](../../../../.github/dependabot.yml)，其中为包含 `native/landlock-run` 的根 pnpm 工作区、`python/sdk` uv 项目和 GitHub Actions 配置了每周一次的版本更新检查。每个更新项都将 `cooldown.default-days` 设为 `30`，因此某个版本只有在发布至少 30 天后才符合更新条件，并会在下一次每周检查时生成更新提案。[仓库内 Landlock 发布决策](2026-08-06-in-repository-landlock-release.md)负责共享工作区边界。
 
-根 pnpm 工作区的版本更新扫描排除 `vendor/**`，其中的源码和 manifest（元数据清单）只能通过 [vendoring 流程](../../../../vendor/README.md)变更；扫描还排除由专用更新项负责的 `native/landlock-run/**`。GitHub 仅将 `exclude-paths` 用于版本更新；如果安全更新 PR（Pull Request）涉及随源码纳入仓库的 manifest，则改由 vendoring 流程处理，以替代自动生成的 PR，而不会将其原样合并。Dependabot PR 会获得仓库的 `cleanup` 类型标签和 `area/infra` 区域标签，运行常规 PR 检查，并且仍须由维护者评审；该自动化不会合并这些 PR。
+根 pnpm 工作区的版本更新扫描排除 `vendor/**`，其中的源码和 manifest（元数据清单）只能通过 [vendoring 流程](../../../../vendor/README.md)变更。GitHub 仅将 `exclude-paths` 用于版本更新；如果安全更新 PR（Pull Request）涉及随源码纳入仓库的 manifest，则改由 vendoring 流程处理，以替代自动生成的 PR，而不会将其原样合并。Dependabot PR 会获得仓库的 `cleanup` 类型标签和 `area/infra` 区域标签，运行常规 PR 检查，并且仍须由维护者评审；该自动化不会合并这些 PR。
 
 仓库设置已启用依赖项漏洞警报和 Dependabot 安全更新。GitHub 不会对这些安全更新应用版本更新冷却期，因此安全修复仍可立即进入更新流程。如果依赖解析还选中了其他刚发布的传递依赖，pnpm 安全更新 PR 仍可能无法通过仓库的锁文件发布时长校验；此类 PR 应等待隔离期结束或缩小更新范围，不得因此放宽政策。仓库为协调刚发布版本而设置的例外，不会纳入 Dependabot 的冷却期排除项：自动版本更新统一等待 30 天；经过明确评审的手动更新仍可遵循相应的发布流程。
 
-pnpm 更新项让两个工作区继续使用已固定的 pnpm 11，不会仅为了自动化而降级版本。当前 Dependabot 更新器会安装 `packageManager` 指定的版本，并读取两个工作区使用的 `9.0` 锁文件格式；由提供方运行的更新任务仍作为集成检查。
+pnpm 更新项让统一工作区继续使用已固定的 pnpm 11，不会仅为了自动化而降级版本。当前 Dependabot 更新器会安装根 `packageManager` 指定的版本，并读取根锁文件的 `9.0` 格式；由提供方运行的更新任务仍作为集成检查。
 
 ## 考虑过的替代方案
 
 - **立即进行版本更新。** 不采用，因为这会取消所要求的版本发布后隔离期，使项目在每个上游版本的发布初期就采用该版本。
 - **CI 通过后自动合并。** 不采用，因为依赖变更可能改变运行时、构建和发布行为；是否接受更新仍须经过常规评审决策。
-- **使用一次递归 npm 扫描。** 不采用，因为它可能将随源码纳入仓库的 manifest 纳入更新范围，或混淆根工作区与 native 工作区的锁文件。显式排除项和专用 native 更新项可维持各自的归属边界。
+- **为 native 配置独立的 npm 扫描。** 不采用，因为 Landlock manifest 属于根工作区和根锁文件；拆分更新会重建一个包管理器已不存在的归属边界。根扫描仅排除随源码纳入的 manifest。
 - **Renovate 或定期运行的 agent（智能体）。** 二者都能为发布已满一定时长的版本提出更新，但所要求的服务是 Dependabot，而且仓库 CI 已将其 PR 视为不可信的依赖来源。
 - **为需协调的刚发布版本设置冷却期豁免。** 自动化路径不采用，因为此类版本需要明确的同步决策或模型目录决策，不能由通用更新提案代替。
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
index d65dae2802..afe8cdba57 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.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 .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
-2026-07-30-generated-third-party-notices.md: e480954d29d5dc09ef8ecd4069059a1f0c8b1043
-2026-07-30-generated-third-party-notices.zh.md: 78ba7250e797c57048078d1b4f62b7a9a5d9d561
+2026-07-30-generated-third-party-notices.md: 6a95953bc551cb38ca1d9aaa51a2041deadd1b08
+2026-07-30-generated-third-party-notices.zh.md: 9d48d3b39de76d5f4fbc1e2e9593a933b08583c8
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
index e480954d29..6a95953bc5 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
@@ -24,7 +24,7 @@ The file discloses **direct** dependencies only. The complete npm closure with p
 
 The runtime tier deliberately covers **every mountable plugin**, not just what the CLI, Web UI, and Python runtime load by default. `scripts/install.sh` installs the repository itself, so a user's `cordis.yml` can mount any plugin package; `@modelcontextprotocol/sdk` and the OpenTelemetry packages reach real users even though no default assembly imports them. Under-disclosure is the costly direction for a legal notice.
 
-The manifest set is derived from the `packages:` members each `pnpm-workspace.yaml` declares — the root one and the nested Landlock workspace's — so a new member area is read the day it is declared rather than the day someone remembers to extend a list. License and repository metadata come from the installed pnpm stores, both the root one and the Landlock workspace's, so the generator requires an installed tree and fails loud when a package resolves to neither, rather than emitting an empty cell. `OVERRIDES` carries the packages whose published manifest cannot answer — Rust-built npm bins that omit `license`, and the `modelcontextprotocol/servers` packages whose repository is mid MIT→Apache-2.0 relicensing, so their effective terms are per-contribution. A runtime dependency whose license is not on the permissive list is a hard error: shipping copyleft is a distribution decision, not something a regenerated table may absorb silently. Vendored packages are cross-checked against `vendor/README.md` and rejected if any is not MIT, and `pnpm-workspace.yaml`'s `patchedDependencies` are listed under the runtime table because pnpm applies those patches at install time — shipped artifacts carry modified copies of `@earendil-works/pi-tui` and `node-pty`, and the patch files are the record of what changed.
+The manifest set is derived from the `packages:` members the root `pnpm-workspace.yaml` declares, including the Landlock workspace and its public packages, so a new member area is read the day it is declared rather than the day someone remembers to extend a list. License and repository metadata come from the root workspace's installed pnpm store and package-local link farms, so the generator requires an installed tree and fails loud when a package resolves to neither, rather than emitting an empty cell. `OVERRIDES` carries the packages whose published manifest cannot answer — Rust-built npm bins that omit `license`, and the `modelcontextprotocol/servers` packages whose repository is mid MIT→Apache-2.0 relicensing, so their effective terms are per-contribution. A runtime dependency whose license is not on the permissive list is a hard error: shipping copyleft is a distribution decision, not something a regenerated table may absorb silently. Vendored packages are cross-checked against `vendor/README.md` and rejected if any is not MIT, and `pnpm-workspace.yaml`'s `patchedDependencies` are listed under the runtime table because pnpm applies those patches at install time — shipped artifacts carry modified copies of `@earendil-works/pi-tui` and `node-pty`, and the patch files are the record of what changed.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
index 78ba7250e7..9d48d3b39d 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 运行时层刻意覆盖**所有可挂载的插件**，而不止 CLI、Web UI 与 Python 运行时默认加载的那些。`scripts/install.sh` 安装的就是仓库本身，用户的 `cordis.yml` 可以挂载任何插件包；`@modelcontextprotocol/sdk` 与 OpenTelemetry 系列即使没有任何默认装配引入，也会触达真实用户。对法务披露而言，披露不足才是代价更高的那个方向。
 
-清单集合由两个 `pnpm-workspace.yaml`——根工作区与嵌套的 Landlock 工作区——各自声明的 `packages:` 成员派生，因此新增成员区域在声明当天就会被读取，而不必等谁想起来去补一份列表。许可证与仓库地址取自已安装的 pnpm store，根 store 与 Landlock 工作区的 store 都会查；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布清单答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。运行时依赖的许可证若不在宽松清单内即为硬失败：交付 copyleft 是一项分发决策，不该被一次重新生成悄悄吸收。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列在运行时表格之后，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。
+清单集合由根 `pnpm-workspace.yaml` 声明的 `packages:` 成员派生，其中包括 Landlock 工作区及其公开包，因此新增成员区域在声明当天就会被读取，而不必等谁想起来去补一份列表。许可证与仓库地址取自根工作区已安装的 pnpm store 和包本地链接场；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布清单答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。运行时依赖的许可证若不在宽松清单内即为硬失败：交付 copyleft 是一项分发决策，不该被一次重新生成悄悄吸收。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列在运行时表格之后，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。
 
 ## Testing
 
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 81052d7c08..524d7912e2 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -6,20 +6,6 @@ updates:
     exclude-paths:
       # Vendored Cordis sources follow vendor/README.md instead of registry updates.
       - "vendor/**"
-      # This independently locked pnpm workspace has its own update entry below.
-      - "native/landlock-run/**"
-    schedule:
-      interval: "cron"
-      cronjob: "0 4 * * *"
-      timezone: "Asia/Shanghai"
-    cooldown:
-      default-days: 30
-    labels:
-      - "cleanup"
-      - "area/infra"
-
-  - package-ecosystem: "npm"
-    directory: "/native/landlock-run"
     schedule:
       interval: "cron"
       cronjob: "0 4 * * *"
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index aa73dba8d9..6ff3f6f8ea 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -7,7 +7,7 @@ DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the th
 
 This file lists **direct** dependencies declared by the workspace. It is generated from the workspace manifests by `scripts/gen-third-party-notices.ts`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and `scripts/gen-third-party-notices.spec.ts` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run `pnpm run verify-third-party-notices` for the standalone check.
 
-The complete npm transitive closure, with exact pinned versions, is recorded in [`pnpm-lock.yaml`](pnpm-lock.yaml) — inspect it with `pnpm licenses list`. The Python closure is recorded in [`python/sdk/uv.lock`](python/sdk/uv.lock), and the Landlock launcher workspace keeps its own in [`native/landlock-run/pnpm-lock.yaml`](native/landlock-run/pnpm-lock.yaml).
+The complete npm transitive closure, including the Landlock launcher workspace, is recorded with exact pinned versions in [`pnpm-lock.yaml`](pnpm-lock.yaml) — inspect it with `pnpm licenses list`. The Python closure is recorded separately in [`python/sdk/uv.lock`](python/sdk/uv.lock).
 
 ## Vendored source (`vendor/`)
 
diff --git a/native/landlock-run/packages/entry/package.json b/native/landlock-run/packages/entry/package.json
index f05e81f06b..56345b2847 100644
--- a/native/landlock-run/packages/entry/package.json
+++ b/native/landlock-run/packages/entry/package.json
@@ -3,6 +3,11 @@
   "version": "0.0.1",
   "type": "module",
   "description": "Landlock self-restrict-then-exec launcher for sandboxing subprocesses on Linux: per-platform prebuilt static binaries plus the JS seam that resolves, probes, and speaks their CLI contract",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-harness/deepseek-harness.git",
+    "directory": "native/landlock-run/packages/entry"
+  },
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "exports": {
diff --git a/native/landlock-run/packages/linux-arm64/package.json b/native/landlock-run/packages/linux-arm64/package.json
index 0067f77c8b..af5467cead 100644
--- a/native/landlock-run/packages/linux-arm64/package.json
+++ b/native/landlock-run/packages/linux-arm64/package.json
@@ -2,6 +2,11 @@
   "name": "node-addon-landlock-run-linux-arm64",
   "version": "0.0.1",
   "description": "Prebuilt landlock-run Landlock launcher binary for linux-arm64 (static musl) — resolved as a file path by node-addon-landlock-run, never imported",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-harness/deepseek-harness.git",
+    "directory": "native/landlock-run/packages/linux-arm64"
+  },
   "os": [
     "linux"
   ],
diff --git a/native/landlock-run/packages/linux-x64/package.json b/native/landlock-run/packages/linux-x64/package.json
index 8ea60b636c..375d05332a 100644
--- a/native/landlock-run/packages/linux-x64/package.json
+++ b/native/landlock-run/packages/linux-x64/package.json
@@ -2,6 +2,11 @@
   "name": "node-addon-landlock-run-linux-x64",
   "version": "0.0.1",
   "description": "Prebuilt landlock-run Landlock launcher binary for linux-x64 (static musl) — resolved as a file path by node-addon-landlock-run, never imported",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-harness/deepseek-harness.git",
+    "directory": "native/landlock-run/packages/linux-x64"
+  },
   "os": [
     "linux"
   ],
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 32e2096aa9..0a446d77f8 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -35,6 +35,7 @@ const publicLandlockPackages = new Set([
   'node-addon-landlock-run-linux-arm64',
   'node-addon-landlock-run-linux-x64',
 ])
+const repositoryUrl = 'git+https://github.com/deepseek-harness/deepseek-harness.git'
 
 const localArtifactDirs = new Set(['node_modules'])
 const appPackageFiles: Readonly<Record<string, readonly string[]>> = {
@@ -63,6 +64,7 @@ interface PackageManifest {
   >
   files?: string[]
   publishConfig?: { access?: string }
+  repository?: { type?: string; url?: string; directory?: string }
   peerDependencies?: Record<string, string>
   devDependencies?: Record<string, string>
 }
@@ -89,12 +91,12 @@ function packageDirs(base: string, depth: number): string[] {
       .filter(entry => entry.isDirectory())
       .filter(entry => !localArtifactDirs.has(entry.name))
       .filter(entry => existsSync(join(root, base, entry.name, 'package.json')))
-      .map(entry => join(base, entry.name))
+      .map(entry => `${base}/${entry.name}`)
   }
   return readdirSync(join(root, base), { withFileTypes: true })
     .filter(entry => entry.isDirectory())
     .filter(entry => !localArtifactDirs.has(entry.name))
-    .flatMap(group => packageDirs(join(base, group.name), depth - 1))
+    .flatMap(group => packageDirs(`${base}/${group.name}`, depth - 1))
 }
 
 function workspaceManifests(): WorkspaceManifest[] {
@@ -183,6 +185,12 @@ function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
     if (manifest.publishConfig?.access !== 'public') {
       errors.push(`${label}: published Landlock package must set publishConfig.access to "public"`)
     }
+    const expectedDirectory = dir
+    if (manifest.repository?.type !== 'git'
+      || manifest.repository.url !== repositoryUrl
+      || manifest.repository.directory !== expectedDirectory) {
+      errors.push(`${label}: published Landlock package repository must use ${repositoryUrl} with directory ${expectedDirectory} for trusted publishing`)
+    }
   } else if (manifest.private !== true) {
     errors.push(`${label}: package.json must set "private": true`)
   }
diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts
index d7e0c26a5f..e56cce670a 100644
--- a/scripts/gen-third-party-notices.ts
+++ b/scripts/gen-third-party-notices.ts
@@ -191,8 +191,8 @@ export function virtualManifest(virtual: string, name: string): VirtualManifest
 function installedMetadata(name: string): { license: string; repo: string } {
   const override = OVERRIDES[name]
   let manifest: (Manifest & { license?: string; repository?: string | { url?: string }; homepage?: string }) | undefined
-  // The nested Landlock workspace installs into its own store, so a package
-  // only that workspace depends on is unreachable from the root one.
+  // Workspace-local link farms can expose a dependency that is not linked at
+  // the repository root; both are backed by the root workspace's lockfile.
   for (const store of ['node_modules', 'native/landlock-run/node_modules']) {
     const direct = resolve(root, store, name, 'package.json')
     if (existsSync(direct)) {
@@ -208,7 +208,7 @@ function installedMetadata(name: string): { license: string; repo: string } {
   const rawRepo = typeof manifest?.repository === 'string' ? manifest.repository : manifest?.repository?.url ?? manifest?.homepage
   const repo = override?.repo ?? normalizeRepo(rawRepo)
   if (license === undefined || repo === undefined) {
-    throw new Error(`gen-third-party-notices: cannot resolve ${license === undefined ? 'license' : 'repository'} for ${name}; run \`pnpm install\` (or, for a Landlock-only dependency, \`pnpm --dir native/landlock-run install\`), or add an OVERRIDES entry.`)
+    throw new Error(`gen-third-party-notices: cannot resolve ${license === undefined ? 'license' : 'repository'} for ${name}; run \`pnpm install\`, or add an OVERRIDES entry.`)
   }
   return { license, repo }
 }
@@ -544,7 +544,7 @@ DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the th
 
 This file lists **direct** dependencies declared by the workspace. It is generated from the workspace manifests by \`scripts/gen-third-party-notices.ts\`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and \`scripts/gen-third-party-notices.spec.ts\` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run \`pnpm run verify-third-party-notices\` for the standalone check.
 
-The complete npm transitive closure, with exact pinned versions, is recorded in [\`pnpm-lock.yaml\`](pnpm-lock.yaml) — inspect it with \`pnpm licenses list\`. The Python closure is recorded in [\`python/sdk/uv.lock\`](python/sdk/uv.lock), and the Landlock launcher workspace keeps its own in [\`native/landlock-run/pnpm-lock.yaml\`](native/landlock-run/pnpm-lock.yaml).
+The complete npm transitive closure, including the Landlock launcher workspace, is recorded with exact pinned versions in [\`pnpm-lock.yaml\`](pnpm-lock.yaml) — inspect it with \`pnpm licenses list\`. The Python closure is recorded separately in [\`python/sdk/uv.lock\`](python/sdk/uv.lock).
 
 ## Vendored source (\`vendor/\`)
 

From 32864c026cbfc7a36d875d1bee87b8c28bba0a78 Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 11:11:57 +0800
Subject: [PATCH 040/516] fix(clean): remove native build state (review round
 3)

---
 scripts/clean.spec.ts | 4 +++-
 scripts/clean.ts      | 5 +++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/scripts/clean.spec.ts b/scripts/clean.spec.ts
index aada0667ef..c724453283 100644
--- a/scripts/clean.spec.ts
+++ b/scripts/clean.spec.ts
@@ -60,16 +60,18 @@ describe('RepositoryCleaner', () => {
     expect(existsSync(join(root, 'products/shell/lib'))).toBe(true)
   })
 
-  it('removes the native Landlock entry output that emits directly to lib', async () => {
+  it('removes the native Landlock entry output and solution build info', async () => {
     const root = fixture()
     const entry = 'native/landlock-run/packages/entry'
     addProject(root, entry, 'lib')
     write(join(root, entry, 'lib/index.js'))
+    write(join(root, 'native/landlock-run/tsconfig.tsbuildinfo'))
 
     await new RepositoryCleaner(root).clean()
 
     expect(existsSync(join(root, entry, 'lib'))).toBe(false)
     expect(existsSync(join(root, entry, 'src/index.ts'))).toBe(true)
+    expect(existsSync(join(root, 'native/landlock-run/tsconfig.tsbuildinfo'))).toBe(false)
   })
 
   it('refuses project outputs reached through a symlink outside the repository', async () => {
diff --git a/scripts/clean.ts b/scripts/clean.ts
index 1224fe8420..68e4ff4e71 100644
--- a/scripts/clean.ts
+++ b/scripts/clean.ts
@@ -72,6 +72,11 @@ export class RepositoryCleaner {
     for (const entry of await readdir(this.root, { withFileTypes: true })) {
       if (entry.isFile() && entry.name.endsWith('.tsbuildinfo')) targets.add(join(this.root, entry.name))
     }
+    await this.addIfPresent(
+      targets,
+      join(this.root, 'native/landlock-run/tsconfig.tsbuildinfo'),
+      canonicalRoot,
+    )
 
     // The root project-reference graph is the source of truth for live build targets.
     // Each emitting project declares lib/types as outDir; its parent lib also owns

From 10c1d77a4f3842812293d138a4e447356149ab5b Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 13:50:48 +0800
Subject: [PATCH 041/516] fix(landlock-run): address release review feedback

---
 .../implemented/feature/2026-07-06-sandbox.i18n.yaml   |  4 ++--
 .../notes/implemented/feature/2026-07-06-sandbox.md    |  2 +-
 .../notes/implemented/feature/2026-07-06-sandbox.zh.md |  2 +-
 .github/workflows/landlock-run-release.yml             | 10 ++++++++--
 native/landlock-run/docs/release.md                    |  2 +-
 packages/bash/bash-sandbox/tests/landlock.e2e.ts       |  6 +++---
 .../sandbox/sandbox-local/tests/packed-install.e2e.ts  |  6 ++++--
 7 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 5f8dfa4e65..b927bf9f72 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: 69a3f1bd181bc06d9a176fa45b1e091991cfa682
-2026-07-06-sandbox.zh.md: eeca55b61da24df215f7a9b7ba8dbf9ab2387f20
+2026-07-06-sandbox.md: de00453eace87ef89e7e05bfe20e1ff956ee4d19
+2026-07-06-sandbox.zh.md: db84e9b3872fb5807720c75310c9ee58f2b9fdb7
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index 69a3f1bd18..de00453eac 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -128,7 +128,7 @@ Each phase gets its full design when picked up, validated against the code at th
 
 - **Second consumer** — `subagent-acp` optionally confines child agents (per-call policy; unconfined default — a child agent must write its own persistence).
 - **More environments** — an environment-coherent capability group example (e.g. bash+fs against one container).
-- **Windows chain** — `PLATFORM_CHAINS.win32` is reserved and empty (fail-closed); filling it means a confinement runner from the AppContainer/restricted-token family, shipped from its own repository on the `node-addon-landlock-run` template, plus its profile dialect, denial signatures, and runner-failure rules. Wrapping the third-party landstrip runner instead was [considered and rejected](../../rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md) — not battle-tested enough for a security invariant.
+- **Windows chain** — `PLATFORM_CHAINS.win32` is reserved and empty (fail-closed); filling it means a confinement runner from the AppContainer/restricted-token family, shipped from the main repository under `native/` following the `node-addon-landlock-run` template, plus its profile dialect, denial signatures, and runner-failure rules. Wrapping the third-party landstrip runner instead was [considered and rejected](../../rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md) — not battle-tested enough for a security invariant.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index eeca55b61d..db84e9b387 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -128,7 +128,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 
 - **第二个消费方**——`subagent-acp` 可选地约束子 agent（按调用策略；默认无约束——子 agent 必须写入自己的持久化）。
 - **更多环境**——环境一致的能力组示例（如 bash+fs 对一个容器）。
-- **Windows 链**——`PLATFORM_CHAINS.win32` 保留为空（失败关闭）；填充它意味着来自 AppContainer/restricted-token 家族的约束 runner，从其自己的仓库按 `node-addon-landlock-run` 模板交付，加上其 profile 方言、拒绝签名和 runner 失败规则。改为包装第三方 landstrip runner 的方案[经考虑后已驳回](../../rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md)——它所经受的实战检验还不足以承载安全不变式。
+- **Windows 链**——`PLATFORM_CHAINS.win32` 保留为空（失败关闭）；填充它意味着来自 AppContainer/restricted-token 家族的约束 runner，由主仓库在 `native/` 下按 `node-addon-landlock-run` 模板交付，加上其 profile 方言、拒绝签名和 runner 失败规则。改为包装第三方 landstrip runner 的方案[经考虑后已驳回](../../rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md)——它所经受的实战检验还不足以承载安全不变式。
 
 ## 曾考虑的替代方案
 
diff --git a/.github/workflows/landlock-run-release.yml b/.github/workflows/landlock-run-release.yml
index dca6c9eed1..c69ebbe5ee 100644
--- a/.github/workflows/landlock-run-release.yml
+++ b/.github/workflows/landlock-run-release.yml
@@ -158,6 +158,14 @@ jobs:
           name: npm-tarballs
           path: native/landlock-run/dist/npm
 
+      - name: Configure npm token fallback
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [[ -n "$NPM_TOKEN" ]]; then
+            echo "NODE_AUTH_TOKEN=$NPM_TOKEN" >> "$GITHUB_ENV"
+          fi
+
       - name: Publish tarballs
         run: |
           version="${GITHUB_REF#refs/tags/landlock-run-v}"
@@ -166,5 +174,3 @@ jobs:
           while IFS= read -r tarball; do
             npm publish "dist/npm/${tarball}" --access public "${tag_args[@]}"
           done < dist/npm/publish-order.txt
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/native/landlock-run/docs/release.md b/native/landlock-run/docs/release.md
index a95cffd47f..353a489c2c 100644
--- a/native/landlock-run/docs/release.md
+++ b/native/landlock-run/docs/release.md
@@ -45,7 +45,7 @@ Use the main repository's `Landlock Run Release` workflow so every binary is bui
 2. Create and push the `landlock-run-vX.Y.Z` tag matching the package versions.
 3. Run the same workflow from that tag with `publish=true`.
 
-The workflow publishes only from the final packed tarballs, in `publish-order.txt` order (platform packages before the entry that optionally depends on them). It supports npm trusted publishing through GitHub OIDC; without it, provide an `NPM_TOKEN` secret in the `npm-publish` environment. Packages publish with `--access public`.
+The workflow publishes only from the final packed tarballs, in `publish-order.txt` order (platform packages before the entry that optionally depends on them). A current-platform rehearsal can still query npm for metadata about an incompatible optional platform package; that package cannot supply the host launcher, which comes from the matching local tarball. Publishing every platform package before the entry ensures a public entry version never points ahead of its platform packages. The workflow supports npm trusted publishing through GitHub OIDC; without it, provide an `NPM_TOKEN` secret in the `npm-publish` environment. Packages publish with `--access public`.
 
 Manual local fallback (current platform's packages only) — always through `pack-release.mjs`, never `pnpm publish` directly (pnpm's pack path strips the launcher's executable bit; see [packaging.md](packaging.md)):
 
diff --git a/packages/bash/bash-sandbox/tests/landlock.e2e.ts b/packages/bash/bash-sandbox/tests/landlock.e2e.ts
index 0c5cfbe563..7579292fe1 100644
--- a/packages/bash/bash-sandbox/tests/landlock.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/landlock.e2e.ts
@@ -13,14 +13,14 @@ import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 
 /**
  * KEYLESS consumer-integration proof: the REAL `LocalSandboxProvider` (bwrap
- * rung forced off, so the npm-distributed `landlock-run` confines) underneath the
+ * rung forced off, so the workspace `landlock-run` launcher confines) underneath the
  * REAL `SandboxBashExecutor`, driven through the executor's public run/start
  * paths. Verifies the WORLD (files exist or don't) plus the stamped result
  * facts; the backend-only confinement proofs live with
  * `@deepseek-ai/dsh-sandbox-local`.
  *
- * Self-skips when the running kernel does not enforce Landlock; the
- * launcher binary itself arrives with `pnpm install` (`node-addon-landlock-run`).
+ * Self-skips when the running kernel does not enforce Landlock. CI builds the launcher from
+ * `native/landlock-run` before running this file.
  */
 
 const probe = spawnSync(launcherPath(), ['--probe'], { timeout: 5_000, encoding: 'utf8' })
diff --git a/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts b/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
index caf0a32c68..612751e6da 100644
--- a/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
+++ b/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
@@ -9,8 +9,10 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 /**
  * Keyless publish-path rehearsal. It packs the provider, its workspace peers, and the current
  * repository's Landlock entry/platform packages, then installs those exact tarballs in an external
- * plain-Node consumer. No registry copy, tsx, path mapping, or workspace resolution can hide
- * missing files, dependency errors, or lost executable modes.
+ * plain-Node consumer. The host launcher comes from the exact local tarballs, so no registry copy,
+ * tsx, path mapping, or workspace resolution can hide missing files, dependency errors, or lost
+ * executable modes. npm may still query registry metadata for an incompatible optional platform
+ * package that cannot supply the host launcher.
  *
  * The installed launcher must match the host architecture, remain executable, and either confine a
  * real process with bwrap disabled or fail closed on a non-enforcing kernel. Skips off Linux or

From bb920b32e004926157b3d4e842d9d419b2b1f5ad Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 13:59:05 +0800
Subject: [PATCH 042/516] feat(web): add dedicated skill tool row

---
 .../2026-08-06-web-skill-tool-row.i18n.yaml   |   6 +
 .../feature/2026-08-06-web-skill-tool-row.md  |  29 +++
 .../2026-08-06-web-skill-tool-row.zh.md       |  29 +++
 apps/web/tests/skill-tool-row.e2e.ts          |  80 +++++++
 .../snapshots/skill-tool-row/ui.expected.md   |  48 ++++
 apps/web/tsconfig.json                        |   1 +
 .../client/ui-primitives/src/icons/index.tsx  |  14 ++
 .../client/ui-primitives/tests/icons.spec.tsx |   4 +-
 packages/client/ui-skill/README.i18n.yaml     |   4 +-
 packages/client/ui-skill/README.md            |   4 +
 packages/client/ui-skill/README.zh.md         |   4 +
 packages/client/ui-skill/package.json         |  20 +-
 .../ui-skill/src/client/SkillRow.module.css   | 212 ++++++++++++++++++
 .../client/ui-skill/src/client/SkillRow.tsx   | 174 ++++++++++++++
 packages/client/ui-skill/src/client/index.ts  |  26 ++-
 .../client/ui-skill/src/client/locales.ts     |  23 ++
 .../ui-skill/tests/browser-plugin.spec.ts     |  69 +++++-
 .../client/ui-skill/tests/skill-row.spec.tsx  | 152 +++++++++++++
 packages/client/ui-skill/tsconfig.json        |   9 +
 pnpm-lock.yaml                                |  24 ++
 tsconfig.host.json                            |   1 +
 21 files changed, 921 insertions(+), 12 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
 create mode 100644 apps/web/tests/skill-tool-row.e2e.ts
 create mode 100644 apps/web/tests/snapshots/skill-tool-row/ui.expected.md
 create mode 100644 packages/client/ui-skill/src/client/SkillRow.module.css
 create mode 100644 packages/client/ui-skill/src/client/SkillRow.tsx
 create mode 100644 packages/client/ui-skill/src/client/locales.ts
 create mode 100644 packages/client/ui-skill/tests/skill-row.spec.tsx

diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
new file mode 100644
index 0000000000..8186444a8d
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.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-08-06-web-skill-tool-row.md
+2026-08-06-web-skill-tool-row.md: b1d76c411d7ccc839616ddcce9fee18716489bf5
+2026-08-06-web-skill-tool-row.zh.md: c16a9b84d75c641b0fdd8778ff56c331c2c81546
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
new file mode 100644
index 0000000000..b1d76c411d
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
@@ -0,0 +1,29 @@
+# Agent Note: Web skill tool row
+
+Status: implemented
+
+English | [中文](2026-08-06-web-skill-tool-row.zh.md)
+
+## Problem
+
+The Web transcript renders `skill` calls through the generic fallback row, so a loaded instruction set looks like an unknown tool call even though Skill is a first-class product concept. The generic row also exposes the JSON argument envelope beside the result, adding noise around the one identity users need: the loaded skill name.
+
+## Decision
+
+`ui-skill` registers a component under the existing `conversation.chat.toolview` keyed slot with key `skill`. The component owns its row chrome from the public `ToolRowProps` contract, matching the independent registrant posture used by the Bash sample instead of importing conversation-private components.
+
+The collapsed row uses a 16-pixel document-and-sparkle glyph and the Bash row's neutral hierarchy: tertiary glyph, secondary `Skill` title, caption separator, and tertiary skill name. Running, failed, and interrupted calls retain the transcript's shimmer, error dot and first-line summary, and warning dot semantics. A settled call expands through the whole summary row into a 260-pixel bounded `Instructions` card containing the exact durable result text; the existing trajectory `Inspect` handoff remains available below the card.
+
+The row derives every visible value from the logged call/result slice. It reads the skill name from the recorded `name` argument and the instructions from durable result content, and never joins the current skill catalog for descriptions or provider metadata. The existing ACP `skill-load` recording is seeded through the real Web persistence and composition path for a keyless interaction and accessibility snapshot.
+
+## Alternatives considered
+
+- Keep the generic tool row and add only a `skill` color selector in `ui-conversation`. This leaves the redundant input envelope and generic expanded body in place, and makes the conversation package own a domain-specific visual rule.
+- Add a new `skill` value to the host tool render-intent union. The keyed client slot already identifies this tool without changing the wire contract, so a new cross-boundary presentation value adds protocol and snapshot surface without enabling another consumer.
+- Export the conversation package's private `ToolRow` component for reuse. Client packages intentionally expose contracts rather than cross-package components; exporting it would couple independent feature packages to conversation implementation details.
+
+## Consequences
+
+`ui-skill` now depends on the public conversation toolview contract, locale and primitive packages, and React in addition to its reference-source dependencies. It owns a small copy of the disclosure-row chrome, so future global interaction changes must update this registrant alongside the Bash sample and conversation rows.
+
+Cold replay stays deterministic when the installed skill catalog changes, and the transcript remains compact until instructions are explicitly expanded. The dedicated card intentionally shows the tool's complete framed output rather than extracting only `<skill_instructions>`, preserving exactly what reached the model and avoiding a second parser for the skill result format.
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
new file mode 100644
index 0000000000..c16a9b84d7
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: Web skill 工具行
+
+Status: implemented
+
+[English](2026-08-06-web-skill-tool-row.md) | 中文
+
+## 问题
+
+Web transcript（文本记录）通过通用后备行渲染 `skill` 调用，使已加载的指令集看起来像一次未知工具调用，尽管 Skill（技能）已是产品中的一等概念。通用行还会在结果旁暴露 JSON 参数的外层结构，围绕用户真正需要的唯一标识增加了噪声：已加载的 skill 名称。
+
+## 决策
+
+`ui-skill` 在现有的 `conversation.chat.toolview` 键控 slot 下注册 key 为 `skill` 的组件。该组件基于公开的 `ToolRowProps` 契约自行实现行 chrome，沿用 Bash 示例的独立注册方姿态，而不导入 conversation 私有组件。
+
+收起的行使用 16 像素的文档与闪光组合图标，并沿用 Bash 行的中性色层级：图标采用三级色，`Skill` 标题采用二级色，分隔符采用 caption 色，skill 名称采用三级色。运行、失败和中断调用分别沿用 transcript 的扫光、错误状态点加首行摘要，以及警告状态点语义。已结算调用可以通过整个摘要行展开一个高度上限为 260 像素的 `Instructions` 卡片，其中原样呈现持久化结果文本；用于跳转至 trajectory 的现有 `Inspect` 入口仍保留在卡片下方。
+
+该行的所有可见值均派生自已记录的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
+
+## 考虑过的替代方案
+
+- 保留通用工具行，只添加一个 `skill` 颜色选择器，并将其放在 `ui-conversation` 中。该方案仍会保留多余的输入外层结构和通用展开体，也会让 conversation 包拥有特定领域的视觉规则。
+- 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 无需更改协议契约即可识别该工具，因此新的跨边界呈现值只会增加协议与快照表层，却没有为其他消费方提供新能力。
+- 导出 conversation 包的私有 `ToolRow` 组件供复用。客户端包刻意对外暴露契约而非跨包组件；导出该组件会使独立功能包耦合到 conversation 的实现细节。
+
+## 后果
+
+除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 契约、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
+
+即使已安装的 skill 目录发生变化，冷回放仍具有确定性；在用户显式展开指令前，transcript 保持紧凑。专用卡片有意显示工具完整封装的输出，而不是只提取 `<skill_instructions>`，从而原样保留模型实际收到的内容，也避免为 skill 结果格式再引入一个解析器。
diff --git a/apps/web/tests/skill-tool-row.e2e.ts b/apps/web/tests/skill-tool-row.e2e.ts
new file mode 100644
index 0000000000..af6c941bcd
--- /dev/null
+++ b/apps/web/tests/skill-tool-row.e2e.ts
@@ -0,0 +1,80 @@
+// Web e2e scenario: the real skill-load recording, seeded cold through the
+// persistence seam, renders through ui-skill's keyed toolview without a model
+// call. The disclosure proves replay-stable naming and exact durable output.
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import {
+  assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts,
+  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const FIXTURE = fileURLToPath(new URL('../../../examples/acp-agent/tests/snapshots/skill-load/session.jsonl', import.meta.url))
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/skill-tool-row', import.meta.url))
+const UI_EXPECTED = fileURLToPath(new URL('./snapshots/skill-tool-row/ui.expected.md', import.meta.url))
+const MODE = webSnapshotMode()
+const SEED_ID = 'skill-tool-row-web-e2e'
+const PROMPT = 'Load the snapshot-skill skill with the skill tool, then reply DONE.'
+
+describe.skipIf(MODE === 'record')('web e2e: dedicated Skill tool row', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    const fixture = await readFile(FIXTURE, 'utf8')
+    expect(fixtureUserPrompts(fixture)).toEqual([PROMPT])
+    scaffold = await launchWebScaffold({})
+    await seedSession(scaffold, fixture, SEED_ID)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+
+    const groupRow = page.locator('[role="treeitem"]').first()
+    await groupRow.waitFor({ timeout: 15_000 })
+    await groupRow.click()
+    const sessionRow = page.locator('[role="treeitem"]').nth(1)
+    await sessionRow.waitFor({ timeout: 10_000 })
+    await sessionRow.click()
+    await page.locator('[data-tool="skill"]').waitFor({ timeout: 15_000 })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it('expands the loaded skill to its exact recorded instructions', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-skill-tool-row'))
+    const call = page.locator('[data-tool="skill"]')
+    const row = call.getByRole('button', { name: 'Skill snapshot-skill' })
+    await expect.poll(() => row.getAttribute('aria-expanded')).toBe('false')
+    expect(await call.getByText('snapshot-skill', { exact: true }).count()).toBe(1)
+
+    await row.click()
+    await expect.poll(() => row.getAttribute('aria-expanded')).toBe('true')
+    await call.getByText('Instructions', { exact: true }).waitFor()
+    const output = call.locator('pre')
+    await output.waitFor()
+    expect(await output.textContent()).toContain('<skill_content name="snapshot-skill">')
+    expect(await output.textContent()).toContain('Follow these snapshot-only instructions.')
+    expect(await output.evaluate(element => getComputedStyle(element.parentElement!).maxHeight)).toBe('260px')
+
+    const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
+      .replace(/\b\d{1,2}\/\d{1,2}(?= \{\{clock\}\})/g, '{{date}}')
+      .split(SEED_ID).join('{{seededId}}')
+    await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  }, 60_000)
+
+  it('keeps its snapshot inventory closed', async () => {
+    await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md'])
+  })
+})
diff --git a/apps/web/tests/snapshots/skill-tool-row/ui.expected.md b/apps/web/tests/snapshots/skill-tool-row/ui.expected.md
new file mode 100644
index 0000000000..7a51aae904
--- /dev/null
+++ b/apps/web/tests/snapshots/skill-tool-row/ui.expected.md
@@ -0,0 +1,48 @@
+- banner:
+  - navigation "Session hierarchy":
+    - button "Load the snapshot-skill skill with" [disabled]
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- text: Load the snapshot-skill skill with the skill tool, then reply DONE. {{date}} {{clock}}
+- button "Copy":
+  - img
+- button "Branch into a new conversation" [disabled]:
+  - img
+- text: Available only on the last message of a completed turn
+- button "Context injection @deepseek-ai/dsh-system-prompt":
+  - img
+  - img
+  - text: Context injection @deepseek-ai/dsh-system-prompt
+- button "Context injection skill-catalog":
+  - img
+  - img
+  - text: Context injection skill-catalog
+- button "Think Load the requested skill.":
+  - img
+  - img
+  - text: Think Load the requested skill.
+- button "Skill snapshot-skill" [expanded]:
+  - img
+  - text: Skill snapshot-skill
+- region "Instructions": "Instructions <skill_content name=\"snapshot-skill\"> <skill_resources> Base directory for this skill: {{cwd}}/.dsh/skills/snapshot-skill Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed. </skill_resources> <skill_instructions> Follow these snapshot-only instructions. Resolve referenced resources relative to this skill directory. </skill_instructions> </skill_content>"
+- button "Inspect"
+- button "Think The skill is loaded.":
+  - img
+  - img
+  - text: Think The skill is loaded.
+- paragraph: DONE
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: {{date}} {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
+- textbox "Message the agent"
+- button "Commands":
+  - img
+- 'button "Access mode, current: Workspace Write"': Workspace Write
+- button "Select model":
+  - text: Select model
+  - img
+- button "Send message" [disabled]
+- text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 280 tok · Output 30 tok
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index dd5fe879e7..9e395e49ad 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -62,6 +62,7 @@
     "tests/startup-auto-selection.e2e.ts",
     "tests/subagent-conversation.e2e.ts",
     "tests/bash-abort-row.e2e.ts",
+    "tests/skill-tool-row.e2e.ts",
     "tests/chat-scroll-fixture.ts",
     "tests/chat-scroll-contract.e2e.ts",
     "tests/chat-long-interactions.e2e.ts",
diff --git a/packages/client/ui-primitives/src/icons/index.tsx b/packages/client/ui-primitives/src/icons/index.tsx
index 71e647a3e9..b0b76e164b 100644
--- a/packages/client/ui-primitives/src/icons/index.tsx
+++ b/packages/client/ui-primitives/src/icons/index.tsx
@@ -750,6 +750,20 @@ export const IconSparkle16 = ({ size = 16, className }: IconProps) => (
   </svg>
 )
 
+/** skill_outline_16 (skill tool-row glyph; document instructions + sparkle) */
+export const IconSkillOutline16 = ({ size = 16, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M12.5113 15.4067C12.4395 15.6249 12.1308 15.6249 12.059 15.4067L11.643 14.1416C11.454 13.567 11.0033 13.1164 10.4288 12.9274L9.16369 12.5113C8.94544 12.4395 8.94544 12.1308 9.16369 12.059L10.4288 11.643C11.0033 11.454 11.454 11.0033 11.643 10.4288L12.059 9.16369C12.1308 8.94544 12.4395 8.94544 12.5113 9.16369L12.9274 10.4288C13.1164 11.0033 13.567 11.454 14.1416 11.643L15.4067 12.059C15.6249 12.1308 15.6249 12.4395 15.4067 12.5113L14.1416 12.9274C13.567 13.1164 13.1164 13.567 12.9274 14.1416L12.5113 15.4067Z"
+      fill="currentColor"
+    />
+    <path
+      d="M9.02246 0.546878C9.9822 0.546878 10.7564 0.545403 11.374 0.612307C12.0042 0.680586 12.5515 0.826244 13.0273 1.17188C13.3052 1.37376 13.5501 1.61868 13.752 1.89649C14.0975 2.37225 14.2432 2.91984 14.3115 3.54981C14.3784 4.16727 14.377 4.94206 14.377 5.90137V8.51367C13.9611 8.29533 13.5071 8.13985 13.0273 8.06055V5.90137C13.0273 4.9121 13.0259 4.22322 12.9688 3.69532C12.9129 3.18044 12.8098 2.89782 12.6592 2.69043C12.5406 2.52724 12.3966 2.38326 12.2334 2.26465C12.026 2.11404 11.7437 2.0109 11.2285 1.95508C10.7005 1.89789 10.0122 1.89649 9.02246 1.89649H6.55371C5.56395 1.89649 4.87569 1.89787 4.34766 1.95508C3.83242 2.01092 3.55022 2.11398 3.34278 2.26465C3.17953 2.38329 3.03564 2.52719 2.91699 2.69043C2.76642 2.89782 2.66325 3.18042 2.60742 3.69532C2.55027 4.22322 2.54883 4.9121 2.54883 5.90137V10.0986C2.54883 11.0878 2.55031 11.7768 2.60742 12.3047C2.66326 12.8196 2.76642 13.1032 2.91699 13.3105C3.03558 13.4736 3.17966 13.6178 3.34278 13.7363C3.5502 13.8869 3.83265 13.9901 4.34766 14.0459C4.87568 14.1031 5.56398 14.1035 6.55371 14.1035H8.08399C8.27443 14.6025 8.55077 15.0585 8.89551 15.4541H6.55371C5.59402 15.4541 4.81976 15.4546 4.20215 15.3877C3.57204 15.3194 3.02468 15.1738 2.54883 14.8281C2.27111 14.6263 2.02606 14.3813 1.82422 14.1035C1.47883 13.6278 1.33293 13.08 1.26465 12.4502C1.19783 11.8327 1.19922 11.0579 1.19922 10.0986V5.90137C1.19922 4.94206 1.1978 4.16727 1.26465 3.54981C1.33295 2.91984 1.47867 2.37225 1.82422 1.89649C2.02613 1.61864 2.27098 1.37379 2.54883 1.17188C3.02472 0.826181 3.57197 0.6806 4.20215 0.612307C4.81976 0.545393 5.594 0.546877 6.55371 0.546878H9.02246ZM9.19629 9.14649H4.5459V7.84571H9.19629V9.14649ZM11.0303 6.10645H4.5459V4.80567H11.0303V6.10645Z"
+      fill="currentColor"
+    />
+  </svg>
+)
+
 /** ic_ds_question_outline_14 (figma extract): ring + question glyph. */
 export const IconQuestionOutline14 = ({ size = 14, className }: IconProps) => (
   <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
diff --git a/packages/client/ui-primitives/tests/icons.spec.tsx b/packages/client/ui-primitives/tests/icons.spec.tsx
index 9877b7df1f..92f0d3cc37 100644
--- a/packages/client/ui-primitives/tests/icons.spec.tsx
+++ b/packages/client/ui-primitives/tests/icons.spec.tsx
@@ -16,8 +16,8 @@ const icons = Object.fromEntries(
 const iconNames = Object.keys(icons)
 
 describe('ic_ds_ icon set', () => {
-  it('exports the full P-I set (46 deepsuite + 17 figma extracts + the hand-authored sparkle)', () => {
-    expect(iconNames.length).toBe(64)
+  it('exports the full P-I set (46 deepsuite + 17 figma extracts + two hand-authored product glyphs)', () => {
+    expect(iconNames.length).toBe(65)
   })
 
   it.each(iconNames)('%s renders an svg with currentColor fills and no hardcoded palette', (name) => {
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index 059a5d8986..d23f68ee85 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/client/ui-skill/README.md
-README.md: fc83ae47dc83e72d60f382892aa678989902d217
-README.zh.md: e103db812d2a21f7f211bc843ec0cd31d1dc2c1e
+README.md: 2280c9302dbc46cff723752f88c47940f98417d5
+README.zh.md: 0e9344ff63139f77461b02b48e18b0e94e54c223
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index fc83ae47dc..2280c9302d 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -8,6 +8,10 @@ A failed `skill.list` throws from `candidates`, which the slash shell logs and f
 
 The `/client` export surface is the plugin body (`apply`/`inject`) only; the source object is internal to the registration effect.
 
+## Skill tool row
+
+The browser plugin also registers a keyed `skill` toolview in `conversation.chat.toolview`. A collapsed row renders the 16-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from the logged call/result slice, never from the current catalog, so cold replay remains stable even when installed skills or their descriptions change.
+
 ## Model Experience
 
 ### Skill reference text in the user prompt
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index e103db812d..0e9344ff63 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -8,6 +8,10 @@ skill（技能）引用 source 的浏览器端：把 `/` 触发的 `skill` sourc
 
 `/client` 导出表层只有插件主体（`apply`／`inject`）；source 对象是注册 effect 的内部实现。
 
+## skill 工具行
+
+浏览器插件还会把一个 key 为 `skill` 的 toolview 注册进 `conversation.chat.toolview`。收起的行以与 Bash 行相同的中性色层级显示 16 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自已记录的调用／结果片段，绝不读取当前 skill 目录，因此即使已安装的 skill 或其描述发生变化，冷回放仍保持稳定。
+
 ## 模型体验
 
 ### 用户提示词中的 skill 引用文本
diff --git a/packages/client/ui-skill/package.json b/packages/client/ui-skill/package.json
index 20d61cdb53..c9d2dd4ed8 100644
--- a/packages/client/ui-skill/package.json
+++ b/packages/client/ui-skill/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-skill",
-  "description": "Skill reference source: '/' menu candidates from skill.list, inserts <skill>name</skill> references",
+  "description": "Web skill references and the dedicated skill tool row",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -25,6 +25,8 @@
   "dshClient": {
     "inject": [
       "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-locale",
+      "@deepseek-ai/dsh-client-ui-conversation",
       "@deepseek-ai/dsh-client-ui-slash"
     ],
     "platform": "web"
@@ -36,19 +38,31 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-client-connection": "^0.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slash": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slash": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
-    "cordis": "^4.0.0-rc.7"
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "files": [
     "lib/index.js",
diff --git a/packages/client/ui-skill/src/client/SkillRow.module.css b/packages/client/ui-skill/src/client/SkillRow.module.css
new file mode 100644
index 0000000000..05c3388aa9
--- /dev/null
+++ b/packages/client/ui-skill/src/client/SkillRow.module.css
@@ -0,0 +1,212 @@
+/* Skill toolview: Bash-matched summary row plus a bounded instructions disclosure. */
+
+.card {
+  display: flex;
+  flex-direction: column;
+}
+
+.row {
+  position: relative;
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  height: 24px;
+  min-width: 0;
+}
+
+.row[data-expandable] {
+  cursor: pointer;
+}
+
+.card[data-state='running'] .row::after {
+  content: '';
+  position: absolute;
+  inset: 0 auto 0 0;
+  width: 300px;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    color-mix(in srgb, var(--dsw-alias-bg-base) 60%, transparent) 55%,
+    transparent 100%
+  );
+  animation: dsh-skill-row-sweep 2.6s ease-out infinite;
+  pointer-events: none;
+}
+
+@keyframes dsh-skill-row-sweep {
+  0% { left: -300px; }
+  90%, 100% { left: 100%; }
+}
+
+.leading {
+  position: relative;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-right: 6px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.chevron {
+  color: var(--dsw-alias-label-secondary);
+}
+
+.iconIdle {
+  display: inline-flex;
+  opacity: 1;
+  transition: opacity 100ms ease;
+}
+
+.chevronHover {
+  position: absolute;
+  inset: 0;
+  margin: auto;
+  opacity: 0;
+  transition: opacity 100ms ease;
+}
+
+.row:hover .iconIdle {
+  opacity: 0;
+}
+
+.row:hover .chevronHover {
+  opacity: 1;
+}
+
+.title {
+  flex: none;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.separator {
+  flex: none;
+  width: 2px;
+  height: 2px;
+  border-radius: 1px;
+  margin: 0 8px;
+  background: var(--dsw-alias-label-caption);
+}
+
+.summary {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.errorSummary {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.bodyWrap {
+  display: flex;
+  flex-direction: column;
+}
+
+.instructionsCard {
+  display: flex;
+  flex-direction: column;
+  max-height: 260px;
+  margin: 4px 0 4px 4px;
+  overflow: hidden;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 12px;
+  background: var(--dsw-alias-markdown-code-block);
+}
+
+.instructionsHeader {
+  flex: none;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+  background: var(--dsw-alias-markdown-code-block-banner);
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 16px;
+  color: var(--dsw-alias-label-caption);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.instructions {
+  min-height: 0;
+  margin: 0;
+  padding: 10px 12px 12px;
+  overflow: auto;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font: var(--dsw-font-markdown-code-block-small);
+  color: var(--dsw-alias-label-secondary);
+}
+
+.instructions[data-error] {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.instructions::-webkit-scrollbar-thumb {
+  border: 2px solid transparent;
+  background-clip: padding-box;
+  border-radius: 6px;
+}
+
+.instructions::-webkit-scrollbar-track {
+  margin: 6px 0;
+}
+
+.inspectButton {
+  display: inline-flex;
+  align-self: flex-start;
+  align-items: center;
+  gap: 4px;
+  margin: 4px 0 2px 4px;
+  padding: 2px 8px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 999px;
+  background: var(--dsw-alias-bg-base);
+  color: var(--dsw-alias-label-secondary);
+  font-size: 11px;
+  line-height: 16px;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 100ms ease;
+}
+
+.card:hover .inspectButton,
+.inspectButton:focus-visible {
+  opacity: 1;
+}
+
+.inspectButton:hover {
+  background: var(--dsw-alias-interactive-bg-hover-solid);
+  color: var(--dsw-alias-label-primary);
+}
+
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .card[data-state='running'] .row::after {
+    animation: none;
+    display: none;
+  }
+
+  .iconIdle,
+  .chevronHover,
+  .inspectButton {
+    transition: none;
+  }
+}
diff --git a/packages/client/ui-skill/src/client/SkillRow.tsx b/packages/client/ui-skill/src/client/SkillRow.tsx
new file mode 100644
index 0000000000..c847678e4a
--- /dev/null
+++ b/packages/client/ui-skill/src/client/SkillRow.tsx
@@ -0,0 +1,174 @@
+// Skill toolview registrant: a domain-owned row over the keyed toolview hole.
+// The compact accent row keeps loaded instructions scannable in the transcript;
+// the exact durable tool output remains available in a bounded disclosure card.
+
+import { useState, type KeyboardEvent, type ReactNode } from 'react'
+import {
+  IconChevronDownOutline14, IconSkillOutline16, StateDot,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import css from './SkillRow.module.css'
+
+/** Skill row lifecycle derived solely from the durable call slice. */
+type SkillRowState = 'running' | 'ok' | 'error' | 'stopped'
+
+/** Full row props: the toolview runtime share plus this package's locale seat. */
+type SkillRowProps = ToolRowProps & PropsLocale<'skill'>
+
+/** Compact, replay-stable view model for the dedicated row. */
+interface SkillRowModel {
+  readonly name: string
+  readonly output: string | null
+  readonly errorSummary: string | null
+  readonly state: SkillRowState
+}
+
+/** First physical line for the collapsed error summary and malformed-args fallback. */
+function firstLine(text: string): string {
+  const newline = text.indexOf('\n')
+  return newline === -1 ? text : text.slice(0, newline)
+}
+
+/** Skill names are the only call argument the compact row presents. */
+function skillName(argsRaw: string, callId: string): string {
+  try {
+    const parsed = JSON.parse(argsRaw) as unknown
+    if (typeof parsed === 'object' && parsed !== null) {
+      const name = (parsed as Record<string, unknown>).name
+      if (typeof name === 'string' && name !== '') return firstLine(name)
+    }
+  } catch {
+    // Streaming can expose a truncated JSON prefix; its first line is still
+    // more useful than replacing the call with an unrelated catalog lookup.
+  }
+  return argsRaw === '' ? callId : firstLine(argsRaw)
+}
+
+/** Flatten the durable result exactly like the generic row's text fallback. */
+function resultText(block: ToolRowProps['block']): string | null {
+  if (!('kind' in block)) return null
+  const parts: string[] = []
+  for (const item of block.content) {
+    parts.push(item.type === 'text' ? item.text : JSON.stringify(item, null, 2))
+  }
+  if (parts.length === 0 && block.error !== undefined) {
+    parts.push(`${block.error.name}: ${block.error.code}`)
+  }
+  return parts.join('\n') || null
+}
+
+/** Derive display state without consulting the live skill catalog. */
+function skillRowModel(block: ToolRowProps['block']): SkillRowModel {
+  const settled = 'kind' in block
+  const argsRaw = (settled ? block.call?.argsRaw : block.argsRaw) ?? ''
+  const state: SkillRowState = !settled
+    ? 'running'
+    : block.error?.code === 'interrupted'
+      ? 'stopped'
+      : block.isError ? 'error' : 'ok'
+  const output = resultText(block)
+  return {
+    name: skillName(argsRaw, block.callId),
+    output,
+    errorSummary: state === 'error' && output !== null ? firstLine(output) : null,
+    state,
+  }
+}
+
+/** State substitution for the collapsed leading slot. */
+function leadingFor(state: SkillRowState): ReactNode {
+  switch (state) {
+    case 'error': return <StateDot state="error" />
+    case 'stopped': return <StateDot state="warning" />
+    default: return <IconSkillOutline16 />
+  }
+}
+
+/** Visually hidden state copy for the colour-only lifecycle cues. */
+function stateStatus(state: SkillRowState, t: SkillRowProps['t']): string | null {
+  switch (state) {
+    case 'running': return t('row.running')
+    case 'error': return t('row.failed')
+    case 'stopped': return t('row.stopped')
+    default: return null
+  }
+}
+
+/** Inspect affordance glyph shared with the transcript's other tool rows. */
+function IconInspect() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden>
+      <path d="M16 8L10.8571 12V10.552L14.1383 8L10.8571 5.448V4L16 8ZM5.14286 10.552L1.86171 8L5.14286 5.448V4L0 8L5.14286 12V10.552ZM9.02514 4L5.59657 12H6.84057L10.2691 4H9.02514Z" fill="currentColor" />
+    </svg>
+  )
+}
+
+/**
+ * Render one `skill` tool call as an accent summary and instructions disclosure.
+ * @param props - keyed toolview payload plus the skill locale seat.
+ * @returns the dedicated skill row.
+ */
+export function SkillRow({ block, inspect, t }: SkillRowProps) {
+  const model = skillRowModel(block)
+  const [expanded, setExpanded] = useState(false)
+  const expandable = model.output !== null
+  const open = expanded && expandable
+  const status = stateStatus(model.state, t)
+  const summary = model.errorSummary ?? model.name
+  const ariaLabel = status === null ? `Skill ${summary}` : `${status} Skill ${summary}`
+  const toggleExpand = (): void => {
+    setExpanded(value => !value)
+  }
+  const toggleFromKeyboard = (event: KeyboardEvent<HTMLDivElement>): void => {
+    if (!expandable || (event.key !== 'Enter' && event.key !== ' ')) return
+    event.preventDefault()
+    toggleExpand()
+  }
+  const leading = open
+    ? <IconChevronDownOutline14 className={css.chevron} />
+    : expandable
+      ? (
+        <>
+          <span className={css.iconIdle}>{leadingFor(model.state)}</span>
+          <IconChevronDownOutline14 className={`${css.chevron} ${css.chevronHover}`} />
+        </>
+      )
+      : leadingFor(model.state)
+  return (
+    <div className={css.card} data-tool="skill" data-state={model.state}>
+      <div
+        className={css.row}
+        data-expandable={expandable || undefined}
+        role={expandable ? 'button' : undefined}
+        tabIndex={expandable ? 0 : undefined}
+        aria-expanded={expandable ? open : undefined}
+        aria-label={expandable ? ariaLabel : undefined}
+        onClick={expandable ? toggleExpand : undefined}
+        onKeyDown={expandable ? toggleFromKeyboard : undefined}
+      >
+        <span className={css.leading}>{leading}</span>
+        {status !== null ? <span className={css.visuallyHidden}>{status}</span> : null}
+        <span className={css.title}>Skill</span>
+        <span className={css.separator} aria-hidden />
+        <span className={model.errorSummary === null ? css.summary : `${css.summary} ${css.errorSummary}`}>
+          {summary}
+        </span>
+      </div>
+      {open ? (
+        <div className={css.bodyWrap}>
+          <section className={css.instructionsCard} aria-label={t('row.instructions')}>
+            <div className={css.instructionsHeader}>{t('row.instructions')}</div>
+            <pre className={css.instructions} data-error={model.state === 'error' || undefined}>{model.output}</pre>
+          </section>
+          {inspect !== undefined ? (
+            <button type="button" className={css.inspectButton} onClick={inspect}>
+              <IconInspect />
+              Inspect
+            </button>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  )
+}
diff --git a/packages/client/ui-skill/src/client/index.ts b/packages/client/ui-skill/src/client/index.ts
index c23f15b770..9631125801 100644
--- a/packages/client/ui-skill/src/client/index.ts
+++ b/packages/client/ui-skill/src/client/index.ts
@@ -19,10 +19,24 @@
  * not kill the prewarm other consumers will hit, so it carries its own
  * abort (fired only on invalidation/teardown) while a candidates caller
  * with an aborted signal just returns early.
+ *
+ * This browser half also owns the `skill` keyed toolview: a replay-stable
+ * accent row derived only from each logged call/result slice.
  */
 import type { ConnectionHandle, SessionId, SkillEntry } from '@deepseek-ai/dsh-client-connection/client'
 import type { ClientContext, ISessions } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SlashServiceContract, SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
+// Type-only: pulls the locale plugin's Context merge (ctx.locale).
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import { SkillRow } from './SkillRow.tsx'
+import { en, NS, zh, type SkillKey } from './locales.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** The dedicated skill tool row's copy. */
+    skill: SkillKey
+  }
+}
 
 /** One session's catalog fetch: the shared promise plus its own abort handle. */
 interface CatalogFetch {
@@ -32,14 +46,20 @@ interface CatalogFetch {
   settled?: readonly SkillEntry[]
 }
 
-/** Required services: slash registry, routed sessions, and the wire face. */
-export const inject = ['slash', 'connection', 'sessions']
+/** Required services: reference source faces plus the tool-row and locale registries. */
+export const inject = ['slash', 'connection', 'sessions', 'slots', 'locale']
 
 /**
- * Client plugin body: register the '/' skill source over the root wire face.
+ * Client plugin body: register the '/' source, dictionaries, and keyed tool row.
  * @param ctx - client root context.
  */
 export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-skill: dictionaries')
+  ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register(
+    { name: 'conversation.chat.toolview', key: 'skill', locale: NS },
+    SkillRow,
+  ))
+
   const skills = (ctx.get('connection') as ConnectionHandle).api.skills
   const sessions = ctx.get('sessions') as ISessions
   // Session-keyed catalog cache; single-flight per key. Plugin-closure state:
diff --git a/packages/client/ui-skill/src/client/locales.ts b/packages/client/ui-skill/src/client/locales.ts
new file mode 100644
index 0000000000..53746397bc
--- /dev/null
+++ b/packages/client/ui-skill/src/client/locales.ts
@@ -0,0 +1,23 @@
+/** `skill` namespace dictionaries for the dedicated tool row. */
+
+/** Dictionary namespace owned by this plugin. */
+export const NS = 'skill'
+
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export const zh = {
+  'row.running': '正在加载 skill',
+  'row.failed': 'skill 加载失败',
+  'row.stopped': 'skill 加载已中止',
+  'row.instructions': '说明',
+} satisfies Record<string, string>
+
+/** The skill namespace key union. */
+export type SkillKey = keyof typeof zh
+
+/** English dictionary, checked complete against the zh key set. */
+export const en = {
+  'row.running': 'Loading skill',
+  'row.failed': 'Skill load failed',
+  'row.stopped': 'Skill load stopped',
+  'row.instructions': 'Instructions',
+} satisfies Record<SkillKey, string>
diff --git a/packages/client/ui-skill/tests/browser-plugin.spec.ts b/packages/client/ui-skill/tests/browser-plugin.spec.ts
index 72a7d6f7a6..3febb36efb 100644
--- a/packages/client/ui-skill/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts
@@ -1,5 +1,6 @@
 /**
- * ui-skill browser half: source registration (duplicate-name proof) +
+ * ui-skill browser half: source and keyed toolview registration +
+ * locale dictionaries + source duplicate-name proof +
  * fiber-teardown removal (HMR safety) against the real SlashService, then
  * the source behavior contract driven directly on the captured source with
  * real ClientSessionContext projections — sessionId addressing, the
@@ -16,6 +17,7 @@ import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { SlashService } from '@deepseek-ai/dsh-client-ui-slash/client'
 import type { ClientSessionContext, SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
 import { apply, inject } from '../src/client/index.ts'
+import { SkillRow as SkillToolRow } from '../src/client/SkillRow.tsx'
 
 type SkillRow = { name: string; description: string; whenToUse?: string }
 type ListResult =
@@ -23,6 +25,38 @@ type ListResult =
   | { ok: false; error: { code: string; message: string; details: object } }
 type ListFn = (payload: object, signal?: AbortSignal) => Promise<{ result: ListResult }>
 
+interface PresentationRegistration {
+  name: string
+  key?: string
+  locale?: string
+}
+
+interface PresentationCapture {
+  registration?: PresentationRegistration
+  component?: unknown
+  dictionaries: Array<{ namespace: string; dictionaries: unknown }>
+}
+
+/** Provide the presentation registries and capture the plugin's registrations. */
+function providePresentation(ctx: Context): PresentationCapture {
+  const capture: PresentationCapture = { dictionaries: [] }
+  ctx.provide('locale', {
+    register(namespace: string, dictionaries: unknown) {
+      capture.dictionaries.push({ namespace, dictionaries })
+      return () => {}
+    },
+  })
+  ctx.provide('slots', {
+    inject(_name: string, factory: () => unknown) { factory() },
+    register(registration: PresentationRegistration, component: unknown) {
+      capture.registration = registration
+      capture.component = component
+      return () => {}
+    },
+  })
+  return capture
+}
+
 /** Boot the plugin over fake slash/connection faces; returns the captured source and its ctx. */
 async function bench(list: ListFn, addressed?: SessionId) {
   const ctx = new Context()
@@ -34,6 +68,7 @@ async function bench(list: ListFn, addressed?: SessionId) {
       ? { parentSessionId: sid('parent'), childSessionId: id, mode: 'continuable' as const }
       : undefined,
   })
+  providePresentation(ctx)
   await ctx.plugin({ inject: [...inject], apply }).await()
   return { ctx, source: captured! }
 }
@@ -65,7 +100,36 @@ const req = (query: string, signal?: AbortSignal) =>
 
 describe('apply', () => {
   it('declares the services it binds', () => {
-    expect(inject).toEqual(['slash', 'connection', 'sessions'])
+    expect(inject).toEqual(['slash', 'connection', 'sessions', 'slots', 'locale'])
+  })
+
+  it('registers the dedicated skill row and its locale dictionaries', async () => {
+    const ctx = new Context()
+    ctx.provide('slash', { registerSource: () => () => {} })
+    ctx.provide('connection', { api: { skills: { list: listOk(CATALOG) } } })
+    ctx.provide('sessions', { subagentAddress: () => undefined })
+    const presentation = providePresentation(ctx)
+    await ctx.plugin({ inject: [...inject], apply }).await()
+    expect(presentation.registration).toEqual({
+      name: 'conversation.chat.toolview', key: 'skill', locale: 'skill',
+    })
+    expect(presentation.component).toBe(SkillToolRow)
+    expect(presentation.dictionaries).toEqual([{
+      namespace: 'skill', dictionaries: {
+        zh: {
+          'row.running': '正在加载 skill',
+          'row.failed': 'skill 加载失败',
+          'row.stopped': 'skill 加载已中止',
+          'row.instructions': '说明',
+        },
+        en: {
+          'row.running': 'Loading skill',
+          'row.failed': 'Skill load failed',
+          'row.stopped': 'Skill load stopped',
+          'row.instructions': 'Instructions',
+        },
+      },
+    }])
   })
 
   it('registers the "/" skill source; disposal frees the name (HMR safety)', async () => {
@@ -74,6 +138,7 @@ describe('apply', () => {
     ctx.provide('sessions', {})
     await ctx.plugin(SlashService).await()
     ctx.provide('connection', { api: { skills: { list: listOk(CATALOG) } } })
+    providePresentation(ctx)
     const fiber = ctx.plugin({ inject: [...inject], apply })
     await fiber.await()
     const slash = ctx.get('slash') as SlashService
diff --git a/packages/client/ui-skill/tests/skill-row.spec.tsx b/packages/client/ui-skill/tests/skill-row.spec.tsx
new file mode 100644
index 0000000000..2dacf0a036
--- /dev/null
+++ b/packages/client/ui-skill/tests/skill-row.spec.tsx
@@ -0,0 +1,152 @@
+// @vitest-environment jsdom
+// Dedicated skill tool row: replay-stable naming, lifecycle states, disclosure,
+// keyboard operation, exact output, and the trajectory Inspect handoff.
+
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import { SkillRow } from '../src/client/SkillRow.tsx'
+import { zh } from '../src/client/locales.ts'
+
+type SkillRowProps = Parameters<typeof SkillRow>[0]
+
+const t: SkillRowProps['t'] = makeTranslate(zh, commonZh)
+
+afterEach(cleanup)
+
+function settled(over: Partial<ToolResultNode> = {}): ToolResultNode {
+  return {
+    kind: 'tool-result',
+    seq: 3,
+    time: 3_000,
+    callId: 'call-skill',
+    call: { name: 'skill', argsRaw: '{"name":"dsh-manage-issues"}' },
+    callTime: 2_000,
+    content: [{ type: 'text', text: 'Follow the issue workflow.\nKeep project fields in sync.' }],
+    isError: false,
+    callView: null,
+    resultView: null,
+    ...over,
+  }
+}
+
+function running(argsRaw = '{"name":"dsh-manage-issues"}'): RunningToolCall {
+  return {
+    callId: 'call-skill', name: 'skill', argsRaw, turn: 1, step: 1, time: 2_000, callView: null,
+  }
+}
+
+function props(block: SkillRowProps['block'], inspect?: () => void): SkillRowProps {
+  return {
+    callId: block.callId,
+    toolName: 'skill',
+    block,
+    openFile: vi.fn(),
+    inspect,
+    t,
+  } as unknown as SkillRowProps
+}
+
+describe('SkillRow', () => {
+  it('renders a compact Bash-shaped summary and discloses the exact instructions', () => {
+    const inspect = vi.fn()
+    const view = render(<SkillRow {...props(settled(), inspect)} />)
+    const row = screen.getByRole('button', { name: 'Skill dsh-manage-issues' })
+    expect(row.getAttribute('aria-expanded')).toBe('false')
+    expect(view.container.querySelector('[data-tool="skill"]')?.getAttribute('data-state')).toBe('ok')
+    expect(view.container.querySelector('[data-tool="skill"] svg')?.getAttribute('width')).toBe('16')
+    expect(screen.queryByLabelText('说明')).toBeNull()
+
+    fireEvent.click(row)
+    expect(row.getAttribute('aria-expanded')).toBe('true')
+    const card = screen.getByLabelText('说明')
+    expect(card.textContent).toBe('说明Follow the issue workflow.\nKeep project fields in sync.')
+    expect(view.container.textContent).not.toContain('{"name":"dsh-manage-issues"}')
+    fireEvent.click(screen.getByRole('button', { name: 'Inspect' }))
+    expect(inspect).toHaveBeenCalledTimes(1)
+
+    fireEvent.click(row)
+    expect(row.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('supports Enter and Space while ignoring unrelated keys', () => {
+    render(<SkillRow {...props(settled())} />)
+    const row = screen.getByRole('button')
+    fireEvent.keyDown(row, { key: 'Escape' })
+    expect(row.getAttribute('aria-expanded')).toBe('false')
+    fireEvent.keyDown(row, { key: 'Enter' })
+    expect(row.getAttribute('aria-expanded')).toBe('true')
+    fireEvent.keyDown(row, { key: ' ' })
+    expect(row.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('keeps a running call compact and announces its state', () => {
+    const view = render(<SkillRow {...props(running())} />)
+    const row = view.container.querySelector('[data-tool="skill"] > div')!
+    expect(row.getAttribute('role')).toBeNull()
+    expect(view.container.textContent).toContain('正在加载 skill')
+    expect(view.container.textContent).toContain('dsh-manage-issues')
+    expect(view.container.querySelector('svg [fill="currentColor"]')).not.toBeNull()
+  })
+
+  it('uses the first failure line in the summary and exposes the full error', () => {
+    const view = render(<SkillRow {...props(settled({
+      content: [{ type: 'text', text: 'SkillError: missing resource\nCheck SKILL.md.' }],
+      isError: true,
+      error: { name: 'SkillError', code: 'missing' },
+    }))} />)
+    const row = screen.getByRole('button', { name: 'skill 加载失败 Skill SkillError: missing resource' })
+    expect(view.container.querySelector('[data-tool="skill"]')?.getAttribute('data-state')).toBe('error')
+    expect(row.textContent).not.toContain('Check SKILL.md.')
+    fireEvent.click(row)
+    const output = view.container.querySelector('pre')!
+    expect(output.textContent).toBe('SkillError: missing resource\nCheck SKILL.md.')
+    expect(output.getAttribute('data-error')).toBe('true')
+  })
+
+  it('renders stopped, structured, and structured-error durable outcomes', () => {
+    const stoppedView = render(<SkillRow {...props(settled({
+      error: { name: 'InterruptedError', code: 'interrupted' },
+    }))} />)
+    expect(stoppedView.container.textContent).toContain('skill 加载已中止')
+    expect(stoppedView.container.querySelector('[data-state="warning"]')).not.toBeNull()
+    cleanup()
+
+    const structuredView = render(<SkillRow {...props(settled({
+      content: [{ type: 'reasoning', text: 'structured instruction note' }],
+    }))} />)
+    fireEvent.click(screen.getByRole('button'))
+    expect(structuredView.container.textContent).toContain('"type": "reasoning"')
+    cleanup()
+
+    render(<SkillRow {...props(settled({
+      content: [],
+      isError: true,
+      error: { name: 'SkillError', code: 'missing' },
+    }))} />)
+    const errorRow = screen.getByRole('button', { name: 'skill 加载失败 Skill SkillError: missing' })
+    fireEvent.click(errorRow)
+    expect(screen.getAllByText('SkillError: missing')).toHaveLength(2)
+  })
+
+  it('falls back to durable args or call id when the skill name is unavailable', () => {
+    const invalid = render(<SkillRow {...props(running('{"name":\n'))} />)
+    expect(invalid.container.textContent).toContain('{"name":')
+    cleanup()
+
+    const scalar = render(<SkillRow {...props(running('"raw-name"'))} />)
+    expect(scalar.container.textContent).toContain('"raw-name"')
+    cleanup()
+
+    const emptyName = render(<SkillRow {...props(running('{"name":""}'))} />)
+    expect(emptyName.container.textContent).toContain('{"name":""}')
+    cleanup()
+
+    const blank = render(<SkillRow {...props(settled({ call: null, content: [] }))} />)
+    expect(blank.container.textContent).toContain('call-skill')
+    expect(blank.container.querySelector('[role="button"]')).toBeNull()
+    expect(blank.container.textContent).not.toContain('正在加载 skill')
+  })
+})
diff --git a/packages/client/ui-skill/tsconfig.json b/packages/client/ui-skill/tsconfig.json
index 318a44906a..f83486aa36 100644
--- a/packages/client/ui-skill/tsconfig.json
+++ b/packages/client/ui-skill/tsconfig.json
@@ -14,9 +14,18 @@
     {
       "path": "../connection"
     },
+    {
+      "path": "../locale"
+    },
     {
       "path": "../runtime"
     },
+    {
+      "path": "../ui-conversation"
+    },
+    {
+      "path": "../ui-primitives"
+    },
     {
       "path": "../ui-slash"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 34c8d60cf9..09d0384667 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1942,9 +1942,21 @@ importers:
       '@deepseek-ai/dsh-client-connection':
         specifier: workspace:^
         version: link:../connection
+      '@deepseek-ai/dsh-client-locale':
+        specifier: workspace:^
+        version: link:../locale
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../runtime
+      '@deepseek-ai/dsh-client-test-runtime':
+        specifier: workspace:^
+        version: link:../test-runtime
+      '@deepseek-ai/dsh-client-ui-conversation':
+        specifier: workspace:^
+        version: link:../ui-conversation
+      '@deepseek-ai/dsh-client-ui-primitives':
+        specifier: workspace:^
+        version: link:../ui-primitives
       '@deepseek-ai/dsh-client-ui-slash':
         specifier: workspace:^
         version: link:../ui-slash
@@ -1954,9 +1966,21 @@ importers:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
+      '@testing-library/react':
+        specifier: ^16.1.0
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+      react-dom:
+        specifier: ^18.2.0
+        version: 18.3.1(react@18.3.1)
 
   packages/client/ui-slash:
     dependencies:
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 4fcf71b680..1a0f4698f7 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -49,6 +49,7 @@
     "apps/web/tests/startup-auto-selection.e2e.ts",
     "apps/web/tests/subagent-conversation.e2e.ts",
     "apps/web/tests/bash-abort-row.e2e.ts",
+    "apps/web/tests/skill-tool-row.e2e.ts",
     "apps/web/tests/chat-scroll-fixture.ts",
     "apps/web/tests/chat-scroll-contract.e2e.ts",
     "apps/web/tests/chat-long-interactions.e2e.ts",

From 1ed5dc81d249a7d391fc9c03da3898fad0706517 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 14:22:54 +0800
Subject: [PATCH 043/516] docs: refresh module graph

---
 docs/module-graph.md | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index 0e2e7e0c37..369441ff51 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -452,11 +452,6 @@ flowchart TD
   pkg_client_ui_layout --> pkg_client_ui_slots
   pkg_client_ui_layout --> pkg_client_ui_theme
   pkg_client_ui_layout --> pkg_invariants
-  pkg_client_ui_skill --> pkg_client_connection
-  pkg_client_ui_skill --> pkg_client_runtime
-  pkg_client_ui_skill --> pkg_client_ui_slash
-  pkg_client_ui_skill --> pkg_client_ui_slots
-  pkg_client_ui_skill --> pkg_invariants
   pkg_code_runtime_worker --> pkg_code_runtime
   pkg_code_runtime_worker --> pkg_invariants
   pkg_code_runtime_worker --> pkg_session
@@ -834,6 +829,14 @@ flowchart TD
   pkg_client_ui_goal --> pkg_client_ui_slots
   pkg_client_ui_goal --> pkg_goal
   pkg_client_ui_goal --> pkg_invariants
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_locale
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_conversation
+  pkg_client_ui_skill --> pkg_client_ui_primitives
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_invariants
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compact
   pkg_session_reference --> pkg_invariants
@@ -1149,7 +1152,6 @@ flowchart TD
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
-| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
@@ -1224,6 +1226,7 @@ flowchart TD
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |

From ee0e33e10f5be46a5854935459ae029c3c9496a1 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 14:31:19 +0800
Subject: [PATCH 044/516] test(web): refresh markdown snapshots

---
 apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md     | 2 +-
 .../tests/snapshots/markdown-inline-code-links/ui.expected.md   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md b/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md
index 68a4df5603..187ab25e8c 100644
--- a/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md
+++ b/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md
@@ -40,7 +40,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}}
 - textbox "Message the agent"
 - button "Commands":
   - img
diff --git a/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md b/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md
index 059849223c..19efa06238 100644
--- a/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md
+++ b/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md
@@ -31,7 +31,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}}Ran for {{duration}}
+- text: {{clock}} Ran for {{duration}}
 - textbox "Message the agent"
 - button "Commands":
   - img

From e0e84d265a24b397663507bf8e9d97c1777a033d Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 14:40:08 +0800
Subject: [PATCH 045/516] refactor(web): deduplicate skill disclosure leading

---
 .../client/ui-skill/src/client/SkillRow.tsx   | 24 +++++++++++--------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/packages/client/ui-skill/src/client/SkillRow.tsx b/packages/client/ui-skill/src/client/SkillRow.tsx
index c847678e4a..be1084ec39 100644
--- a/packages/client/ui-skill/src/client/SkillRow.tsx
+++ b/packages/client/ui-skill/src/client/SkillRow.tsx
@@ -85,6 +85,19 @@ function leadingFor(state: SkillRowState): ReactNode {
   }
 }
 
+/** Leading disclosure slot: state icon at rest, chevron on hover or while open. */
+function disclosureLeading(state: SkillRowState, open: boolean, expandable: boolean): ReactNode {
+  if (open) return <IconChevronDownOutline14 className={css.chevron} />
+  const icon = leadingFor(state)
+  if (!expandable) return icon
+  return (
+    <>
+      <span className={css.iconIdle}>{icon}</span>
+      <IconChevronDownOutline14 className={`${css.chevron} ${css.chevronHover}`} />
+    </>
+  )
+}
+
 /** Visually hidden state copy for the colour-only lifecycle cues. */
 function stateStatus(state: SkillRowState, t: SkillRowProps['t']): string | null {
   switch (state) {
@@ -125,16 +138,7 @@ export function SkillRow({ block, inspect, t }: SkillRowProps) {
     event.preventDefault()
     toggleExpand()
   }
-  const leading = open
-    ? <IconChevronDownOutline14 className={css.chevron} />
-    : expandable
-      ? (
-        <>
-          <span className={css.iconIdle}>{leadingFor(model.state)}</span>
-          <IconChevronDownOutline14 className={`${css.chevron} ${css.chevronHover}`} />
-        </>
-      )
-      : leadingFor(model.state)
+  const leading = disclosureLeading(model.state, open, expandable)
   return (
     <div className={css.card} data-tool="skill" data-state={model.state}>
       <div

From 22c70870742bd69590863c769a5beee684bf8e77 Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 14:41:17 +0800
Subject: [PATCH 046/516] fix(landlock-run): publish under deepseek scope

---
 .../feature/2026-07-06-sandbox.i18n.yaml      |  4 ++--
 .../implemented/feature/2026-07-06-sandbox.md |  2 +-
 .../feature/2026-07-06-sandbox.zh.md          |  2 +-
 ...2-win32-in-process-folder-dialog.i18n.yaml |  4 ++--
 ...26-08-02-win32-in-process-folder-dialog.md |  2 +-
 ...08-02-win32-in-process-folder-dialog.zh.md |  2 +-
 ...6-in-repository-landlock-release.i18n.yaml |  4 ++--
 ...26-08-06-in-repository-landlock-release.md | 14 ++++++-----
 ...08-06-in-repository-landlock-release.zh.md | 14 ++++++-----
 .github/workflows/landlock-run-release.yml    |  6 ++---
 .github/workflows/landlock-run.yml            |  4 ++--
 AGENTS.md                                     |  2 +-
 THIRD_PARTY_NOTICES.md                        |  2 +-
 native/landlock-run/README.i18n.yaml          |  4 ++--
 native/landlock-run/README.md                 | 12 +++++-----
 native/landlock-run/README.zh.md              | 12 +++++-----
 native/landlock-run/docs/architecture.md      |  6 ++---
 native/landlock-run/docs/naming.md            |  6 ++---
 native/landlock-run/docs/packaging.md         |  6 ++---
 native/landlock-run/docs/release.md           |  2 ++
 native/landlock-run/docs/support-matrix.md    |  4 ++--
 native/landlock-run/package.json              |  4 ++--
 .../packages/entry/README.i18n.yaml           |  4 ++--
 native/landlock-run/packages/entry/README.md  |  6 ++---
 .../landlock-run/packages/entry/README.zh.md  |  6 ++---
 .../landlock-run/packages/entry/package.json  |  6 ++---
 .../landlock-run/packages/entry/src/index.ts  |  4 ++--
 native/landlock-run/packages/entry/src/main.c |  2 +-
 .../packages/linux-arm64/README.i18n.yaml     |  4 ++--
 .../packages/linux-arm64/README.md            |  6 ++---
 .../packages/linux-arm64/README.zh.md         |  6 ++---
 .../packages/linux-arm64/package.json         |  4 ++--
 .../packages/linux-x64/README.i18n.yaml       |  4 ++--
 .../landlock-run/packages/linux-x64/README.md |  6 ++---
 .../packages/linux-x64/README.zh.md           |  6 ++---
 .../packages/linux-x64/package.json           |  4 ++--
 .../scripts/verify-packed-install.mjs         |  6 ++---
 native/landlock-run/test/entry.test.js        |  4 ++--
 native/landlock-run/test/launcher.test.js     |  2 +-
 packages/bash/bash-sandbox/package.json       |  2 +-
 .../bash/bash-sandbox/tests/landlock.e2e.ts   |  2 +-
 .../tests/partial-landlock.spec.ts            |  2 +-
 .../examples/agent-spine-demo/package.json    |  2 +-
 .../tests/multi-project-sandbox.e2e.ts        |  2 +-
 .../sandbox/sandbox-local/README.i18n.yaml    |  4 ++--
 packages/sandbox/sandbox-local/README.md      |  2 +-
 packages/sandbox/sandbox-local/README.zh.md   |  2 +-
 packages/sandbox/sandbox-local/package.json   |  2 +-
 packages/sandbox/sandbox-local/src/index.ts   |  2 +-
 .../sandbox/sandbox-local/src/profiles.ts     |  2 +-
 .../sandbox-local/tests/landlock.e2e.ts       |  2 +-
 .../sandbox/sandbox-local/tests/local.spec.ts |  2 +-
 .../sandbox-local/tests/packed-install.e2e.ts |  7 +++---
 pnpm-lock.yaml                                | 24 +++++++++----------
 scripts/check-workspace-constraints.ts        | 13 ++++++----
 scripts/gen-third-party-notices.ts            |  8 +++----
 tsconfig.base.json                            |  2 +-
 57 files changed, 146 insertions(+), 134 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index b927bf9f72..7294f47357 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: de00453eace87ef89e7e05bfe20e1ff956ee4d19
-2026-07-06-sandbox.zh.md: db84e9b3872fb5807720c75310c9ee58f2b9fdb7
+2026-07-06-sandbox.md: 583b388815cd9b2b9cf94ce393839169ce3ffac3
+2026-07-06-sandbox.zh.md: e435b671a42ca5c3ea4f6800bf91d6e006da35d3
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index de00453eac..583b388815 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -128,7 +128,7 @@ Each phase gets its full design when picked up, validated against the code at th
 
 - **Second consumer** — `subagent-acp` optionally confines child agents (per-call policy; unconfined default — a child agent must write its own persistence).
 - **More environments** — an environment-coherent capability group example (e.g. bash+fs against one container).
-- **Windows chain** — `PLATFORM_CHAINS.win32` is reserved and empty (fail-closed); filling it means a confinement runner from the AppContainer/restricted-token family, shipped from the main repository under `native/` following the `node-addon-landlock-run` template, plus its profile dialect, denial signatures, and runner-failure rules. Wrapping the third-party landstrip runner instead was [considered and rejected](../../rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md) — not battle-tested enough for a security invariant.
+- **Windows chain** — `PLATFORM_CHAINS.win32` is reserved and empty (fail-closed); filling it means a confinement runner from the AppContainer/restricted-token family, shipped from the main repository under `native/` following the `@deepseek-ai/node-addon-landlock-run` template, plus its profile dialect, denial signatures, and runner-failure rules. Wrapping the third-party landstrip runner instead was [considered and rejected](../../rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md) — not battle-tested enough for a security invariant.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index db84e9b387..e435b671a4 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -128,7 +128,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 
 - **第二个消费方**——`subagent-acp` 可选地约束子 agent（按调用策略；默认无约束——子 agent 必须写入自己的持久化）。
 - **更多环境**——环境一致的能力组示例（如 bash+fs 对一个容器）。
-- **Windows 链**——`PLATFORM_CHAINS.win32` 保留为空（失败关闭）；填充它意味着来自 AppContainer/restricted-token 家族的约束 runner，由主仓库在 `native/` 下按 `node-addon-landlock-run` 模板交付，加上其 profile 方言、拒绝签名和 runner 失败规则。改为包装第三方 landstrip runner 的方案[经考虑后已驳回](../../rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md)——它所经受的实战检验还不足以承载安全不变式。
+- **Windows 链**——`PLATFORM_CHAINS.win32` 保留为空（失败关闭）；填充它意味着来自 AppContainer/restricted-token 家族的约束 runner，由主仓库在 `native/` 下按 `@deepseek-ai/node-addon-landlock-run` 模板交付，加上其 profile 方言、拒绝签名和 runner 失败规则。改为包装第三方 landstrip runner 的方案[经考虑后已驳回](../../rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md)——它所经受的实战检验还不足以承载安全不变式。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
index 2ec7925a3e..b98c2bee56 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.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 .agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
-2026-08-02-win32-in-process-folder-dialog.md: 91a1ed0d7b1c1938a5e038ce36f1ca90bf3c9e82
-2026-08-02-win32-in-process-folder-dialog.zh.md: 6b90dc1c5fa0042b3e2bcbea8ed554f1f0ea2acf
+2026-08-02-win32-in-process-folder-dialog.md: 5389293605169ce5ca269a127de5f609b8b7dd11
+2026-08-02-win32-in-process-folder-dialog.zh.md: ef81bc1f65b2859de1eb60f74f79e4869da4746b
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
index 91a1ed0d7b..5389293605 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
@@ -14,7 +14,7 @@ The Windows directory picker's primary tier was a spawned PowerShell script arou
 
 ## Alternatives considered
 
-- **A prebuilt native helper (`native/` family like `node-addon-landlock-run`).** Rejected: a mirror repository, an npm package family, MSVC provisioning, and a release handoff — all to ship ~150 lines of C the repository cannot exercise on CI (no real-Windows lane); koffi delivers the same COM surface with zero new supply chain.
+- **A prebuilt native helper (`native/` family like `@deepseek-ai/node-addon-landlock-run`).** Rejected: another npm package family, MSVC provisioning, and a Windows build/release lane — all to ship ~150 lines of C the repository cannot currently exercise on CI (no real-Windows lane); koffi delivers the same COM surface with zero new supply chain.
 - **An N-API in-process addon.** Rejected for the same CI/toolchain reasons plus owned C++ for STA threading and message pumping that a child process + koffi express in TypeScript.
 - **Keep PowerShell primary and probe versions.** Rejected: the picker stays hostage to shell packaging (6 vs 7, Store aliases, profiles), and 5.1's legacy dialog remains the floor wherever pwsh is absent; the fallback-trigger widening alone was accepted into the fallback tier instead.
 - **Blocking the main thread for the modal call.** Rejected outright: the web host must keep serving RPC while the dialog is open.
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
index 6b90dc1c5f..ef81bc1f65 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
@@ -14,7 +14,7 @@ Windows 目录选择器的主层此前是围绕 WinForms `FolderBrowserDialog` 
 
 ## 考虑过的替代方案
 
-- **预编译原生助手（`native/` 家族，如 `node-addon-landlock-run`）。** 否决：镜像仓库、npm 包家族、MSVC 供给和发布交接——只为交付约 150 行 CI 无法执行的 C（没有真 Windows 通道）；koffi 以零新增供应链提供同一 COM 面。
+- **预编译原生助手（`native/` 家族，如 `@deepseek-ai/node-addon-landlock-run`）。** 否决：再增加一个 npm 包家族、MSVC 供给和 Windows 构建／发布通道——只为交付约 150 行目前无法在 CI 中执行的 C（现有 CI 没有真 Windows 通道）；koffi 以零新增供应链提供同一 COM 面。
 - **N-API 进程内插件。** 否决：同样的 CI／工具链原因，另加需要自有 C++ 处理 STA 线程与消息泵，而子进程 + koffi 用 TypeScript 就能表达。
 - **保留 PowerShell 为主层并探测版本。** 否决：选择器仍被 shell 打包形态挟持（6 与 7、Store 别名、profile），且没有 pwsh 的机器地板仍是 5.1 的旧版对话框；仅把回退触发条件的拓宽吸收进回退层。
 - **在主线程上阻塞模态调用。** 直接否决：对话框打开期间 web 宿主必须继续服务 RPC。
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
index 3ce0e0d5e1..2a4a389174 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.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 .agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
-2026-08-06-in-repository-landlock-release.md: f682078250adde8d56a4270e9d01ce4b1cd1bee9
-2026-08-06-in-repository-landlock-release.zh.md: 4950d80d87afd18c5605f4f5bca56b8d85564fc2
+2026-08-06-in-repository-landlock-release.md: 3ae9e9c3c50a1d0202a345e419cb2b7079e29ffa
+2026-08-06-in-repository-landlock-release.zh.md: 9f2233f6ae95620d7221f83648b5dc9b4cf8c7d2
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
index f682078250..3ae9e9c3c5 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
@@ -6,17 +6,19 @@ English | [中文](2026-08-06-in-repository-landlock-release.zh.md)
 
 ## Problem
 
-The `node-addon-landlock-run` source already lives beside its DeepSeek Harness consumers under `native/landlock-run`, but it previously kept a separate pnpm workspace and lockfile and depended on a standalone repository for npm publication. Harness packages consumed a fixed registry version, so one pull request could change the launcher contract and its consumer without testing those changes together. The source repository's native workflow could rehearse the package, but it did not publish the artifact it tested.
+The `@deepseek-ai/node-addon-landlock-run` source already lives beside its DeepSeek Harness consumers under `native/landlock-run`, but it previously kept a separate pnpm workspace and lockfile and depended on a standalone repository for npm publication. Harness packages consumed a fixed registry version, so one pull request could change the launcher contract and its consumer without testing those changes together. The source repository's native workflow could rehearse the package, but it did not publish the artifact it tested.
 
 The mirror also duplicated release coordination: export the source, update another lockfile, run another release workflow, publish the native family, then return to this repository to bump registry dependencies. That split made source-to-binary provenance, rollback, and security-fix coordination harder without changing what npm users actually needed.
 
+The existing unscoped npm names are owned by the standalone publisher account rather than the `@deepseek-ai` organization. Moving only the workflow would therefore leave publication dependent on a personal credential outside the repository's release ownership.
+
 The consolidation must preserve platform selection. The public distribution is deliberately one JavaScript entry package plus separate Linux x64 and arm64 binary packages; merging repository ownership does not imply putting every binary into one tarball or publishing every DeepSeek Harness package at the launcher version.
 
 ## Decision
 
-`native/landlock-run` and `native/landlock-run/packages/*` belong to the repository's root pnpm workspace and use the root `pnpm-lock.yaml`. Harness consumers declare `node-addon-landlock-run` with `workspace:*`, so development, type checking, builds, and pull-request tests resolve the entry package from the same checkout. The root TypeScript project graph builds that entry package before consumers, and the repository cleaner owns its direct `lib/` output.
+`native/landlock-run` and `native/landlock-run/packages/*` belong to the repository's root pnpm workspace and use the root `pnpm-lock.yaml`. Harness consumers declare `@deepseek-ai/node-addon-landlock-run` with `workspace:*`, so development, type checking, builds, and pull-request tests resolve the entry package from the same checkout. The root TypeScript project graph builds that entry package before consumers, and the repository cleaner owns its direct `lib/` output.
 
-The public npm boundary remains three packages with one launcher-family version: `node-addon-landlock-run`, `node-addon-landlock-run-linux-x64`, and `node-addon-landlock-run-linux-arm64`. The entry package retains both platform packages as `optionalDependencies`; their `os` and `cpu` manifest fields let npm install only the compatible package. Repository constraints allow public publication only for those three names, require `publishConfig.access: public`, and require their versions to match the private launcher workspace root. Other repository workspaces remain private under the existing constraint.
+The public npm boundary is three organization-owned packages with one launcher-family version: `@deepseek-ai/node-addon-landlock-run`, `@deepseek-ai/node-addon-landlock-run-linux-x64`, and `@deepseek-ai/node-addon-landlock-run-linux-arm64`. The entry package retains both platform packages as `optionalDependencies`; their `os` and `cpu` manifest fields let npm install only the compatible package. Repository constraints allow public publication only for those three names, require `publishConfig.access: public`, and require their versions to match the private launcher workspace root. The former unscoped names are not release targets of this repository; other repository workspaces remain private under the existing constraint.
 
 The main repository owns both native CI and publication. `Landlock Run` runs for relevant pull requests and `master` pushes and builds each platform on its matching native runner. The manually dispatched `Landlock Run Release` workflow builds both platform binaries, transfers them as workflow artifacts, assembles and verifies the complete package family, packs immutable npm tarballs, installs and exercises those tarballs, and only then permits the protected publish job. Platform tarballs publish before the entry tarball that optionally depends on them. Publication uses `landlock-run-vX.Y.Z` tags so launcher releases cannot collide with other release families in the monorepo; prereleases use the npm `next` dist-tag.
 
@@ -26,17 +28,17 @@ The sandbox packed-install rehearsal no longer permits the npm registry to suppl
 
 - **Keep the standalone repository as a release mirror** — rejected because it preserves the split lockfiles, source export, stale-registry test window, and cross-repository release sequence after the source of record has already moved here.
 - **Publish one npm package containing every platform binary** — rejected because users would download binaries they cannot run and npm could no longer use package-level `os`/`cpu` filtering. Repository ownership and npm package layout are separate choices.
-- **Give the launcher the root DeepSeek Harness version and publish the complete monorepo recursively** — rejected because this change owns one three-package public family, not the independent `@deepseek-ai/*` baseline. The [artifact-first npm baseline proposal](../../proposed/process/2026-08-04-artifact-first-npm-baseline-publication.md) explicitly keeps native workspaces outside its target set.
+- **Give the launcher the root DeepSeek Harness version and publish the complete monorepo recursively** — rejected because this change owns one three-package public family, not the independent `@deepseek-ai/dsh-*` baseline. The [artifact-first npm baseline proposal](../../proposed/process/2026-08-04-artifact-first-npm-baseline-publication.md) explicitly keeps native workspaces outside its target set.
 - **Cross-compile both binaries in one release job** — rejected because the checked-in package matrix already assigns each architecture a native GitHub runner and avoids adding a cross-toolchain trust surface.
 
 ## Consequences
 
 Launcher protocol, TypeScript entry code, native source, harness consumption, and publish-path tests can change in one pull request and resolve from one lockfile. A release tag now identifies the source, consumer integration, build instructions, and tarballs tested by the main repository. The standalone mirror is no longer part of the release path and can be archived after the first successful in-repository publication.
 
-npm consumers keep the same install command and package names. A supported Linux host downloads the entry package and its matching architecture package; the other architecture package is skipped. An unsupported host receives no platform binary and follows the existing deterministic fail-closed probe path.
+npm consumers install `@deepseek-ai/node-addon-landlock-run`; the old unscoped package names are not silently redirected. A supported Linux host downloads the scoped entry package and its matching architecture package; the other architecture package is skipped. An unsupported host receives no platform binary and follows the existing deterministic fail-closed probe path.
 
 The implementation touches more files than a dependency-line edit because the repository must also own workspace constraints, TypeScript build order, cleanup, CI triggers, release tags, lockfile generation, packed-install provenance, release documentation, and generated notices. The behavioral boundary stays narrow: it changes only the Landlock package family and its three direct workspace consumers, not the version or publication state of other DeepSeek Harness packages.
 
-The main repository's `npm-publish` environment must authorize npm trusted publishing or provide `NPM_TOKEN`; moving workflow code cannot configure those external settings. npm still publishes packages sequentially and offers no cross-package transaction, so a failed publish can leave a partial version. Because npm rejects an already-published name and version, an operator must inspect the registry and publish only the missing tarballs rather than rerunning the workflow unchanged. Linux x64 and arm64 runners remain the authoritative binary and real-kernel checks; a macOS checkout can verify the entry package and unsupported-platform behavior but cannot replace those jobs.
+The first scoped release must use an `@deepseek-ai` organization token through the `npm-publish` environment's `NPM_TOKEN`, because npm cannot configure trusted publishing until a package exists. After bootstrap, all three packages must authorize this repository's release workflow before the fallback token can be removed. npm still publishes packages sequentially and offers no cross-package transaction, so a failed publish can leave a partial version. Because npm rejects an already-published name and version, an operator must inspect the registry and publish only the missing tarballs rather than rerunning the workflow unchanged. Linux x64 and arm64 runners remain the authoritative binary and real-kernel checks; a macOS checkout can verify the entry package and unsupported-platform behavior but cannot replace those jobs.
 
 This note supersedes only the release-mirror and registry-pinned source-development statements in the [sandbox Agent Note](../feature/2026-07-06-sandbox.md); that note continues to own sandbox behavior, runner selection, and enforcement semantics.
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
index 4950d80d87..9f2233f6ae 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
@@ -6,17 +6,19 @@ Status: implemented
 
 ## 问题
 
-`node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器契约及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
+`@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器契约及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
 
 发布镜像还造成重复的发布协调工作：导出源码、更新另一份锁文件、运行另一套发布工作流、发布原生包家族，然后回到本仓库更新注册表依赖。npm 用户的实际需求并未改变，这种拆分却增加了从源码到二进制的溯源、回滚和安全修复协调难度。
 
+现有的非 scoped npm 包名归独立发布账号所有，而不属于 `@deepseek-ai` 组织。因此，仅迁移工作流仍会让发布依赖仓库发布归属之外的个人凭证。
+
 此次整合必须保留平台选择机制。公开分发有意采用一个 JavaScript 入口包，并为 Linux x64 和 arm64 分别提供二进制包；合并仓库归属并不意味着要把所有二进制文件放进同一个 tarball，也不意味着要按照启动器版本发布所有 DeepSeek Harness 包。
 
 ## 决策
 
-`native/landlock-run` 和 `native/landlock-run/packages/*` 属于仓库根 pnpm workspace，并使用根 `pnpm-lock.yaml`。Harness 消费方将 `node-addon-landlock-run` 声明为 `workspace:*`，因此开发、类型检查、构建和 PR 测试都会从同一个 checkout 解析入口包。根 TypeScript 项目图会先构建该入口包，再构建消费方；仓库清理器负责清理其直接生成的 `lib/` 输出目录。
+`native/landlock-run` 和 `native/landlock-run/packages/*` 属于仓库根 pnpm workspace，并使用根 `pnpm-lock.yaml`。Harness 消费方将 `@deepseek-ai/node-addon-landlock-run` 声明为 `workspace:*`，因此开发、类型检查、构建和 PR 测试都会从同一个 checkout 解析入口包。根 TypeScript 项目图会先构建该入口包，再构建消费方；仓库清理器负责清理其直接生成的 `lib/` 输出目录。
 
-公开 npm 分发边界仍由 3 个包组成，它们共用一个启动器包家族版本：`node-addon-landlock-run`、`node-addon-landlock-run-linux-x64` 和 `node-addon-landlock-run-linux-arm64`。入口包继续通过 `optionalDependencies` 声明两个平台包；它们在 manifest（元数据清单）中的 `os` 和 `cpu` 字段让 npm 只安装兼容的包。仓库约束只允许公开发布这 3 个包名，要求设置 `publishConfig.access: public`，并要求其版本与私有启动器 workspace 根包一致。仓库中的其他 workspace 仍受现有约束保护，保持私有状态。
+公开 npm 分发边界由 3 个归组织所有的包组成，它们共用一个启动器包家族版本：`@deepseek-ai/node-addon-landlock-run`、`@deepseek-ai/node-addon-landlock-run-linux-x64` 和 `@deepseek-ai/node-addon-landlock-run-linux-arm64`。入口包继续通过 `optionalDependencies` 声明两个平台包；它们在 manifest（元数据清单）中的 `os` 和 `cpu` 字段让 npm 只安装兼容的包。仓库约束只允许公开发布这 3 个包名，要求设置 `publishConfig.access: public`，并要求其版本与私有启动器 workspace 根包一致。原先的非 scoped 包名不属于本仓库的发布目标；仓库中的其他 workspace 仍受现有约束保护，保持私有状态。
 
 主仓库同时负责原生 CI 和发布。`Landlock Run` 会为相关 PR 和 `master` 推送运行，并在各自匹配的原生 runner 上构建每个平台包。手动触发的 `Landlock Run Release` 工作流会构建两个平台的二进制文件，将其作为工作流产物传递，组装并验证完整的包家族，打包出内容不可变的 npm tarball，安装并实际运行这些 tarball，之后才允许受保护的发布作业执行。发布顺序是平台 tarball 在前，最后发布将它们列为可选依赖的入口 tarball。发布使用 `landlock-run-vX.Y.Z` tag，避免启动器版本与 monorepo 中其他发布家族发生冲突；预发布版本使用 npm 的 `next` dist-tag。
 
@@ -26,17 +28,17 @@ Status: implemented
 
 - **保留独立仓库作为发布镜像**：不予采纳，因为在权威源码已经迁入本仓库后，这仍会保留拆分的锁文件、源码导出、测试使用陈旧注册表版本的时间窗，以及跨仓库发布序列。
 - **发布一个包含所有平台二进制文件的 npm 包**：不予采纳，因为用户会下载无法在其主机上运行的二进制文件，而且 npm 无法再利用包级 `os`／`cpu` 筛选。仓库归属与 npm 包布局是两个彼此独立的选择。
-- **让启动器使用 DeepSeek Harness 根版本，并递归发布整个 monorepo**：不予采纳，因为本次改动负责的是一个由 3 个包组成的公开包家族，而不是独立的 `@deepseek-ai/*` 基线。[产物优先的 npm 基线提案](../../proposed/process/2026-08-04-artifact-first-npm-baseline-publication.md)明确将原生 workspace 排除在其目标集合之外。
+- **让启动器使用 DeepSeek Harness 根版本，并递归发布整个 monorepo**：不予采纳，因为本次改动负责的是一个由 3 个包组成的公开包家族，而不是独立的 `@deepseek-ai/dsh-*` 基线。[产物优先的 npm 基线提案](../../proposed/process/2026-08-04-artifact-first-npm-baseline-publication.md)明确将原生 workspace 排除在其目标集合之外。
 - **在一个发布作业中交叉编译两个二进制文件**：不予采纳，因为仓库内已提交的包矩阵已经为每种架构分配了原生 GitHub runner，无需再把交叉工具链纳入信任边界。
 
 ## 后果
 
 同一个 PR 可以同时修改启动器协议、TypeScript 入口代码、原生源码、harness 消费方式和发布路径测试，并从同一份锁文件解析这些内容。发布 tag 现在标识源码、消费方集成、构建指令，以及主仓库测试过的 tarball。第一次成功从本仓库发布后，独立镜像便不再属于发布路径，可以归档。
 
-npm 消费方继续使用相同的安装命令和包名。受支持的 Linux 主机会下载入口包及与其架构匹配的包，并跳过另一架构的包。不受支持的主机不会收到平台二进制文件，并继续沿用现有的确定性失败闭合探测路径。
+npm 消费方改为安装 `@deepseek-ai/node-addon-landlock-run`；原先的非 scoped 包名不会被静默重定向。受支持的 Linux 主机会下载 scoped 入口包及与其架构匹配的包，并跳过另一架构的包。不受支持的主机不会收到平台二进制文件，并继续沿用现有的确定性失败闭合探测路径。
 
 实现涉及的文件比只修改一行依赖更多，因为仓库还必须负责 workspace 约束、TypeScript 构建顺序、清理、CI 触发条件、发布 tag、锁文件生成、打包安装来源证明、发布文档和生成的第三方声明。行为边界仍然很窄：此次改动只影响 Landlock 包家族及其 3 个直接 workspace 消费方，不改变其他 DeepSeek Harness 包的版本或发布状态。
 
-主仓库的 `npm-publish` 环境必须授权 npm trusted publishing，或提供 `NPM_TOKEN`；只迁移工作流代码无法配置这些外部设置。npm 仍会按顺序发布各个包，且不提供跨包事务，因此发布失败可能留下只完成了一部分的版本。由于 npm 会拒绝已经发布的同名同版本包，操作人员必须检查注册表并只发布缺失的 tarball，而不能原样重新运行工作流。Linux x64 和 arm64 runner 仍提供权威的二进制构建与真实内核检查；macOS checkout 可以验证入口包和不受支持平台上的行为，但不能取代这些作业。
+第一次发布 scoped 包时，必须通过 `npm-publish` 环境的 `NPM_TOKEN` 使用 `@deepseek-ai` 组织 token，因为 npm 只有在包已经存在后才能配置 trusted publishing。完成 bootstrap 后，必须让 3 个包都授权本仓库的发布工作流，才能移除后备 token。npm 仍会按顺序发布各个包，且不提供跨包事务，因此发布失败可能留下只完成了一部分的版本。由于 npm 会拒绝已经发布的同名同版本包，操作人员必须检查注册表并只发布缺失的 tarball，而不能原样重新运行工作流。Linux x64 和 arm64 runner 仍提供权威的二进制构建与真实内核检查；macOS checkout 可以验证入口包和不受支持平台上的行为，但不能取代这些作业。
 
 本说明仅取代[沙箱 Agent Note](../feature/2026-07-06-sandbox.md)中有关发布镜像和开发源码时依赖注册表固定版本的表述；该 Agent Note 仍负责沙箱行为、runner 选择和强制执行语义。
diff --git a/.github/workflows/landlock-run-release.yml b/.github/workflows/landlock-run-release.yml
index c69ebbe5ee..7d78e98bc6 100644
--- a/.github/workflows/landlock-run-release.yml
+++ b/.github/workflows/landlock-run-release.yml
@@ -1,4 +1,4 @@
-# Build and publish the node-addon-landlock-run package family from the
+# Build and publish the @deepseek-ai/node-addon-landlock-run package family from the
 # harness source of record. Rehearsal and publication consume the same packed
 # tarballs; each native binary is built on its matching architecture.
 name: Landlock Run Release
@@ -58,7 +58,7 @@ jobs:
           cache-dependency-path: pnpm-lock.yaml
 
       - name: Install dependencies
-        run: pnpm install --filter node-addon-landlock-run-workspace... --frozen-lockfile
+        run: pnpm install --filter @deepseek-ai/node-addon-landlock-run-workspace... --frozen-lockfile
 
       - name: Install musl toolchain
         run: |
@@ -97,7 +97,7 @@ jobs:
           cache-dependency-path: pnpm-lock.yaml
 
       - name: Install dependencies
-        run: pnpm install --filter node-addon-landlock-run-workspace... --frozen-lockfile
+        run: pnpm install --filter @deepseek-ai/node-addon-landlock-run-workspace... --frozen-lockfile
 
       - name: Build TypeScript
         run: pnpm build:ts
diff --git a/.github/workflows/landlock-run.yml b/.github/workflows/landlock-run.yml
index 391e1eeae1..6379c8cdc1 100644
--- a/.github/workflows/landlock-run.yml
+++ b/.github/workflows/landlock-run.yml
@@ -73,7 +73,7 @@ jobs:
           cache-dependency-path: pnpm-lock.yaml
 
       - name: Install dependencies
-        run: pnpm install --filter node-addon-landlock-run-workspace... --frozen-lockfile
+        run: pnpm install --filter @deepseek-ai/node-addon-landlock-run-workspace... --frozen-lockfile
 
       - name: Install musl toolchain
         run: |
@@ -124,7 +124,7 @@ jobs:
           cache-dependency-path: pnpm-lock.yaml
 
       - name: Install dependencies
-        run: pnpm install --filter node-addon-landlock-run-workspace... --frozen-lockfile
+        run: pnpm install --filter @deepseek-ai/node-addon-landlock-run-workspace... --frozen-lockfile
 
       - name: Build TypeScript
         run: pnpm build:ts
diff --git a/AGENTS.md b/AGENTS.md
index a42f39084a..79d35f97fe 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -39,7 +39,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   support/     dev/test infrastructure
   util/        zero-dependency utilities
 python/      Python SDK and bundled runtime (see python/README.md)
-native/      node-addon-landlock-run source of record (see native/README.md)
+native/      @deepseek-ai/node-addon-landlock-run source of record (see native/README.md)
 examples/    Runnable cordis.yml leaves over packages/examples bundles (see examples/AGENTS.md)
 .agents/     Agent workflows and Agent Notes (`notes/`)
 docs/        architecture, generated catalogs, postmortems, cookbook (see docs/AGENTS.md)
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 6ff3f6f8ea..e6907730fe 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -172,4 +172,4 @@ Direct dependencies of the `pyproject.toml` manifests, plus `uv` as the developm
 
 ## First-party native packages
 
-`node-addon-landlock-run` (and its platform packages) is built and released from this repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party.
+`@deepseek-ai/node-addon-landlock-run` (and its platform packages) is built and released from this repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party.
diff --git a/native/landlock-run/README.i18n.yaml b/native/landlock-run/README.i18n.yaml
index bdcf985216..c204d571cf 100644
--- a/native/landlock-run/README.i18n.yaml
+++ b/native/landlock-run/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 native/landlock-run/README.md
-README.md: 19cc18830b90609f648cfb2ce1ee509ad9fe381b
-README.zh.md: 5d3c1c2cd692bb87d5a759a0a6f9628a3f065863
+README.md: fcb8e8249e6728d925fd08c938a780b155d3d4ac
+README.zh.md: 8206ab8074d8d80fb9b11cff436bbd10e6dc34dd
diff --git a/native/landlock-run/README.md b/native/landlock-run/README.md
index 19cc18830b..fcb8e8249e 100644
--- a/native/landlock-run/README.md
+++ b/native/landlock-run/README.md
@@ -1,4 +1,4 @@
-# node-addon-landlock-run
+# @deepseek-ai/node-addon-landlock-run
 
 English | [中文](README.zh.md)
 
@@ -9,15 +9,15 @@ The first tool is **`landlock-run`** — a self-restrict-then-exec [Landlock](ht
 ## Install
 
 ```sh
-npm install node-addon-landlock-run
+npm install @deepseek-ai/node-addon-landlock-run
 ```
 
 Published packages use an entry package plus platform optional packages:
 
 ```text
-node-addon-landlock-run
-node-addon-landlock-run-linux-x64
-node-addon-landlock-run-linux-arm64
+@deepseek-ai/node-addon-landlock-run
+@deepseek-ai/node-addon-landlock-run-linux-x64
+@deepseek-ai/node-addon-landlock-run-linux-arm64
 ```
 
 npm's `os`/`cpu` fields make installers fetch only the matching platform package. There is no install-time build fallback on purpose: on a host without a platform package the resolved path never exists, the probe reports `unusable`, and the consumer falls closed.
@@ -25,7 +25,7 @@ npm's `os`/`cpu` fields make installers fetch only the matching platform package
 ## Usage
 
 ```js
-import { grantArgs, launcherPath, probe } from 'node-addon-landlock-run';
+import { grantArgs, launcherPath, probe } from '@deepseek-ai/node-addon-landlock-run';
 
 const launcher = launcherPath();
 if (probe(launcher) !== 'unusable') {
diff --git a/native/landlock-run/README.zh.md b/native/landlock-run/README.zh.md
index 5d3c1c2cd6..8206ab8074 100644
--- a/native/landlock-run/README.zh.md
+++ b/native/landlock-run/README.zh.md
@@ -1,4 +1,4 @@
-# node-addon-landlock-run
+# @deepseek-ai/node-addon-landlock-run
 
 [English](README.md) | 中文
 
@@ -9,15 +9,15 @@
 ## 安装
 
 ```sh
-npm install node-addon-landlock-run
+npm install @deepseek-ai/node-addon-landlock-run
 ```
 
 已发布包由一个入口包和可选平台包组成：
 
 ```text
-node-addon-landlock-run
-node-addon-landlock-run-linux-x64
-node-addon-landlock-run-linux-arm64
+@deepseek-ai/node-addon-landlock-run
+@deepseek-ai/node-addon-landlock-run-linux-x64
+@deepseek-ai/node-addon-landlock-run-linux-arm64
 ```
 
 npm 的 `os`/`cpu` 字段使安装器只拉取匹配的平台包。系统有意不提供安装时构建回退：在没有对应平台包的宿主上，解析后的路径绝不存在，探测会报告 `unusable`，消费方以失败闭合方式处理。
@@ -25,7 +25,7 @@ npm 的 `os`/`cpu` 字段使安装器只拉取匹配的平台包。系统有意
 ## 用法
 
 ```js
-import { grantArgs, launcherPath, probe } from 'node-addon-landlock-run';
+import { grantArgs, launcherPath, probe } from '@deepseek-ai/node-addon-landlock-run';
 
 const launcher = launcherPath();
 if (probe(launcher) !== 'unusable') {
diff --git a/native/landlock-run/docs/architecture.md b/native/landlock-run/docs/architecture.md
index e6974f4e50..b462b40635 100644
--- a/native/landlock-run/docs/architecture.md
+++ b/native/landlock-run/docs/architecture.md
@@ -6,8 +6,8 @@ This repository owns confinement *mechanism*, not policy: consumers (agent harne
 
 The family is one entry package plus per-platform binary packages:
 
-- **Entry package** (`node-addon-landlock-run`): ESM JavaScript. Owns the tool's CLI contract — path resolution (`launcherPath`), the functional probe (`probe`), grant-argv construction (`grantArgs`), and the contract constants. Ships the C source in its tarball for auditability. Lists every platform package as an `optionalDependency`.
-- **Platform packages** (`node-addon-landlock-run-linux-{x64,arm64}`): one prebuilt static binary under `bin/`, a `prebuilds.json` declaring it, and no JavaScript at all. npm's `os`/`cpu` fields select the matching one at install time; the entry package resolves it to a file path — there is nothing to import.
+- **Entry package** (`@deepseek-ai/node-addon-landlock-run`): ESM JavaScript. Owns the tool's CLI contract — path resolution (`launcherPath`), the functional probe (`probe`), grant-argv construction (`grantArgs`), and the contract constants. Ships the C source in its tarball for auditability. Lists every platform package as an `optionalDependency`.
+- **Platform packages** (`@deepseek-ai/node-addon-landlock-run-linux-{x64,arm64}`): one prebuilt static binary under `bin/`, a `prebuilds.json` declaring it, and no JavaScript at all. npm's `os`/`cpu` fields select the matching one at install time; the entry package resolves it to a file path — there is nothing to import.
 
 Because the contract parser and the binary version together in one family, probe-parsing drift against the binary is structurally impossible — the failure mode the split exists to prevent.
 
@@ -15,7 +15,7 @@ There is no shared loader package: platform packages have nothing to load. If a
 
 ## Resolution and availability
 
-`launcherPath()` resolves `node-addon-landlock-run-<platform>-<arch>` and returns `<package>/bin/landlock-run`. When the package is not resolvable it returns a deterministic fallback path inside the entry package's own `node_modules` that simply never exists. Existence is deliberately unchecked either way: `probe()` is the single availability signal, and a missing binary probes `unusable` exactly like an unenforcing kernel. Consumers get one degradation path, not two.
+`launcherPath()` resolves `@deepseek-ai/node-addon-landlock-run-<platform>-<arch>` and returns `<package>/bin/landlock-run`. When the package is not resolvable it returns a deterministic fallback path inside the entry package's own `node_modules` that simply never exists. Existence is deliberately unchecked either way: `probe()` is the single availability signal, and a missing binary probes `unusable` exactly like an unenforcing kernel. Consumers get one degradation path, not two.
 
 The probe is functional — the launcher builds and enforces a real maximal ruleset in a short-lived child — because version checks would miss a kernel that has the syscalls but refuses enforcement.
 
diff --git a/native/landlock-run/docs/naming.md b/native/landlock-run/docs/naming.md
index 9de9f0b95f..a1f2665654 100644
--- a/native/landlock-run/docs/naming.md
+++ b/native/landlock-run/docs/naming.md
@@ -2,11 +2,11 @@
 
 ## npm packages
 
-The public package family is unscoped, using the `node-addon-landlock-run` package prefix; platform packages append platform information only:
+The public package family belongs to the `@deepseek-ai` scope and uses the `node-addon-landlock-run` package prefix; platform packages append platform information only:
 
 ```text
-node-addon-landlock-run
-node-addon-landlock-run-<platform>
+@deepseek-ai/node-addon-landlock-run
+@deepseek-ai/node-addon-landlock-run-<platform>
 ```
 
 Platform suffixes carry no libc component (binaries are static musl) and no variant component — variants stay inside `prebuilds.json` and binary filenames.
diff --git a/native/landlock-run/docs/packaging.md b/native/landlock-run/docs/packaging.md
index 9a1be47b2a..ec459eb655 100644
--- a/native/landlock-run/docs/packaging.md
+++ b/native/landlock-run/docs/packaging.md
@@ -5,9 +5,9 @@ The package family uses the same broad shape as native packages such as esbuild:
 ## Published packages
 
 ```text
-node-addon-landlock-run
-node-addon-landlock-run-linux-x64
-node-addon-landlock-run-linux-arm64
+@deepseek-ai/node-addon-landlock-run
+@deepseek-ai/node-addon-landlock-run-linux-x64
+@deepseek-ai/node-addon-landlock-run-linux-arm64
 ```
 
 Unsupported platforms are intentionally absent from `optionalDependencies` — see [support-matrix.md](support-matrix.md).
diff --git a/native/landlock-run/docs/release.md b/native/landlock-run/docs/release.md
index 353a489c2c..d5eec50b6e 100644
--- a/native/landlock-run/docs/release.md
+++ b/native/landlock-run/docs/release.md
@@ -47,6 +47,8 @@ Use the main repository's `Landlock Run Release` workflow so every binary is bui
 
 The workflow publishes only from the final packed tarballs, in `publish-order.txt` order (platform packages before the entry that optionally depends on them). A current-platform rehearsal can still query npm for metadata about an incompatible optional platform package; that package cannot supply the host launcher, which comes from the matching local tarball. Publishing every platform package before the entry ensures a public entry version never points ahead of its platform packages. The workflow supports npm trusted publishing through GitHub OIDC; without it, provide an `NPM_TOKEN` secret in the `npm-publish` environment. Packages publish with `--access public`.
 
+The three scoped package names must be bootstrapped with an `@deepseek-ai` organization token through the `NPM_TOKEN` fallback: npm [requires a package to exist before a trusted publisher can be configured](https://docs.npmjs.com/cli/v11/commands/npm-trust/). After the first release creates all three packages, configure each package to trust `landlock-run-release.yml` in this repository with the `npm-publish` environment, then remove the fallback token when organization policy permits it.
+
 Manual local fallback (current platform's packages only) — always through `pack-release.mjs`, never `pnpm publish` directly (pnpm's pack path strips the launcher's executable bit; see [packaging.md](packaging.md)):
 
 ```sh
diff --git a/native/landlock-run/docs/support-matrix.md b/native/landlock-run/docs/support-matrix.md
index 96d02b3cf6..e60ad201c1 100644
--- a/native/landlock-run/docs/support-matrix.md
+++ b/native/landlock-run/docs/support-matrix.md
@@ -4,8 +4,8 @@
 
 | Platform package | GitHub runner (builder of record) | Notes |
 |---|---|---|
-| `node-addon-landlock-run-linux-x64` | `ubuntu-24.04` | static musl — glibc and musl distros alike |
-| `node-addon-landlock-run-linux-arm64` | `ubuntu-24.04-arm` | static musl — glibc and musl distros alike |
+| `@deepseek-ai/node-addon-landlock-run-linux-x64` | `ubuntu-24.04` | static musl — glibc and musl distros alike |
+| `@deepseek-ai/node-addon-landlock-run-linux-arm64` | `ubuntu-24.04-arm` | static musl — glibc and musl distros alike |
 
 Enforcement additionally requires a kernel with Landlock enabled (5.13+). The negotiated ABI level decides the probe verdict: every access this build knows governed → `full`; an older ABI governing a subset → `partial` (still confined for everything it supports); Landlock absent or disabled → `unusable`, and the launcher refuses to run commands at all. The probe — not the kernel version — is the authority: a kernel built without Landlock, or with the LSM disabled, probes `unusable` regardless of its version.
 
diff --git a/native/landlock-run/package.json b/native/landlock-run/package.json
index 6fe3f7eff9..0fb9b3ddfb 100644
--- a/native/landlock-run/package.json
+++ b/native/landlock-run/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "node-addon-landlock-run-workspace",
+  "name": "@deepseek-ai/node-addon-landlock-run-workspace",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -22,7 +22,7 @@
     "release:verify-packed-install": "node ./scripts/verify-packed-install.mjs"
   },
   "devDependencies": {
-    "node-addon-landlock-run": "workspace:*",
+    "@deepseek-ai/node-addon-landlock-run": "workspace:*",
     "@types/node": "^26.0.1",
     "tsx": "^4.20.6",
     "typescript": "^6.0.3"
diff --git a/native/landlock-run/packages/entry/README.i18n.yaml b/native/landlock-run/packages/entry/README.i18n.yaml
index 47d33e0d70..7c67f49670 100644
--- a/native/landlock-run/packages/entry/README.i18n.yaml
+++ b/native/landlock-run/packages/entry/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 native/landlock-run/packages/entry/README.md
-README.md: e402cdfe71c4eb81b977a21955fe3fff6bf55fd3
-README.zh.md: e4fcd33a256b51c815cdd1c6771be328bc46f138
+README.md: fff722428c5d213d9fcce0ee87a1d48cdc189884
+README.zh.md: f462fbe3cb0cb8d1d83b4d6b1d8e2f61e88ff69c
diff --git a/native/landlock-run/packages/entry/README.md b/native/landlock-run/packages/entry/README.md
index e402cdfe71..fff722428c 100644
--- a/native/landlock-run/packages/entry/README.md
+++ b/native/landlock-run/packages/entry/README.md
@@ -1,11 +1,11 @@
-# node-addon-landlock-run
+# @deepseek-ai/node-addon-landlock-run
 
 English | [中文](README.zh.md)
 
 Landlock self-restrict-then-exec launcher for confining subprocesses on Linux: this entry package resolves the per-platform prebuilt binary, runs its functional enforcement probe, and builds its grant argv — consumers never spell launcher flags or parse launcher output themselves.
 
 ```js
-import { grantArgs, launcherPath, probe } from 'node-addon-landlock-run';
+import { grantArgs, launcherPath, probe } from '@deepseek-ai/node-addon-landlock-run';
 
 const launcher = launcherPath();
 if (probe(launcher) !== 'unusable') {
@@ -15,4 +15,4 @@ if (probe(launcher) !== 'unusable') {
 
 The launcher installs a Landlock ruleset on itself and `exec`s the wrapped command; the ruleset is inherited across `execve`, so the whole process tree runs confined. Everything not granted is denied, and launcher failures exit `125` without running the command — fail-closed, never fail-open. The binary contract is pinned in the repo's `docs/cli-contract.md`; the C source rides this tarball (`src/main.c`) for audit.
 
-Platform packages (`os`/`cpu`-selected optional dependencies, no JavaScript inside): `node-addon-landlock-run-linux-x64`, `node-addon-landlock-run-linux-arm64`. On hosts without one, `launcherPath()` returns a deterministic nonexistent path and `probe()` reports `'unusable'` — there is deliberately no install-time compile fallback.
+Platform packages (`os`/`cpu`-selected optional dependencies, no JavaScript inside): `@deepseek-ai/node-addon-landlock-run-linux-x64`, `@deepseek-ai/node-addon-landlock-run-linux-arm64`. On hosts without one, `launcherPath()` returns a deterministic nonexistent path and `probe()` reports `'unusable'` — there is deliberately no install-time compile fallback.
diff --git a/native/landlock-run/packages/entry/README.zh.md b/native/landlock-run/packages/entry/README.zh.md
index e4fcd33a25..f462fbe3cb 100644
--- a/native/landlock-run/packages/entry/README.zh.md
+++ b/native/landlock-run/packages/entry/README.zh.md
@@ -1,11 +1,11 @@
-# node-addon-landlock-run
+# @deepseek-ai/node-addon-landlock-run
 
 [English](README.md) | 中文
 
 用于在 Linux 上限制子进程的 Landlock「先限制自身、再执行」启动器：此入口包定位对应平台的预构建二进制文件，运行功能性强制执行探测，并构建其授权 argv。消费方无需自行拼写启动器标志或解析启动器输出。
 
 ```js
-import { grantArgs, launcherPath, probe } from 'node-addon-landlock-run';
+import { grantArgs, launcherPath, probe } from '@deepseek-ai/node-addon-landlock-run';
 
 const launcher = launcherPath();
 if (probe(launcher) !== 'unusable') {
@@ -15,4 +15,4 @@ if (probe(launcher) !== 'unusable') {
 
 启动器在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此整个进程树都在限制下运行。未授予的一切都被拒绝；启动器失败时以 `125` 退出且不运行命令：采用失败闭合策略，绝不在失败时放行。二进制契约锁定在仓库的 `docs/cli-contract.md` 中；C 源码作为 `src/main.c` 随该 tarball 分发，便于审计。
 
-平台包（由 `os`/`cpu` 选择的可选依赖，内部不含 JavaScript）：`node-addon-landlock-run-linux-x64`、`node-addon-landlock-run-linux-arm64`。在缺少对应包的宿主上，`launcherPath()` 返回一个固定但不存在的路径，`probe()` 报告 `'unusable'`；系统有意不提供安装时编译回退。
+平台包（由 `os`/`cpu` 选择的可选依赖，内部不含 JavaScript）：`@deepseek-ai/node-addon-landlock-run-linux-x64`、`@deepseek-ai/node-addon-landlock-run-linux-arm64`。在缺少对应包的宿主上，`launcherPath()` 返回一个固定但不存在的路径，`probe()` 报告 `'unusable'`；系统有意不提供安装时编译回退。
diff --git a/native/landlock-run/packages/entry/package.json b/native/landlock-run/packages/entry/package.json
index 56345b2847..1614df5ad2 100644
--- a/native/landlock-run/packages/entry/package.json
+++ b/native/landlock-run/packages/entry/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "node-addon-landlock-run",
+  "name": "@deepseek-ai/node-addon-landlock-run",
   "version": "0.0.1",
   "type": "module",
   "description": "Landlock self-restrict-then-exec launcher for sandboxing subprocesses on Linux: per-platform prebuilt static binaries plus the JS seam that resolves, probes, and speaks their CLI contract",
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "node-addon-landlock-run-linux-arm64": "workspace:*",
-    "node-addon-landlock-run-linux-x64": "workspace:*"
+    "@deepseek-ai/node-addon-landlock-run-linux-arm64": "workspace:*",
+    "@deepseek-ai/node-addon-landlock-run-linux-x64": "workspace:*"
   }
 }
diff --git a/native/landlock-run/packages/entry/src/index.ts b/native/landlock-run/packages/entry/src/index.ts
index 7a4349a5ca..ec909f928a 100644
--- a/native/landlock-run/packages/entry/src/index.ts
+++ b/native/landlock-run/packages/entry/src/index.ts
@@ -53,7 +53,7 @@ export interface LauncherGrants {
 
 /**
  * Path of the launcher binary for this host: resolved from the per-platform
- * npm package `node-addon-landlock-run-<platform>-<arch>` (npm's
+ * npm package `@deepseek-ai/node-addon-landlock-run-<platform>-<arch>` (npm's
  * `os`/`cpu` fields make installers fetch only the matching one). When the
  * package is not resolvable — a platform without one, or an install that
  * skipped the optional dependency — the returned fallback path points inside
@@ -69,7 +69,7 @@ export interface LauncherGrants {
 export function launcherPath(
   resolvePackageJson: (specifier: string) => string = createRequire(import.meta.url).resolve,
 ): string {
-  const platformPackage = `node-addon-landlock-run-${process.platform}-${process.arch}`
+  const platformPackage = `@deepseek-ai/node-addon-landlock-run-${process.platform}-${process.arch}`
   try {
     return join(dirname(resolvePackageJson(`${platformPackage}/package.json`)), 'bin', LAUNCHER_BIN)
   } catch {
diff --git a/native/landlock-run/packages/entry/src/main.c b/native/landlock-run/packages/entry/src/main.c
index af3c2eb3f0..e4e1f5c17e 100644
--- a/native/landlock-run/packages/entry/src/main.c
+++ b/native/landlock-run/packages/entry/src/main.c
@@ -31,7 +31,7 @@
  * linked statically), so the whole audit surface is this file plus the
  * kernel's stable syscall contract. Built natively per architecture by
  * `scripts/build.ts` into the per-platform npm packages
- * (`node-addon-landlock-run-linux-{x64,arm64}`); the argv grammar,
+ * (`@deepseek-ai/node-addon-landlock-run-linux-{x64,arm64}`); the argv grammar,
  * exit codes, and report lines are pinned in `docs/cli-contract.md`.
  */
 
diff --git a/native/landlock-run/packages/linux-arm64/README.i18n.yaml b/native/landlock-run/packages/linux-arm64/README.i18n.yaml
index f7e057193c..fc5c8f9b11 100644
--- a/native/landlock-run/packages/linux-arm64/README.i18n.yaml
+++ b/native/landlock-run/packages/linux-arm64/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 native/landlock-run/packages/linux-arm64/README.md
-README.md: e5117988cf0bae2227edaa041700c2f75753899c
-README.zh.md: e502b0239b5ed862af579b21e36b8c47d7d6107e
+README.md: dfcc9e97dc1393a42ff4b89ac009cdfd31e1497b
+README.zh.md: 350044e92f1d0247222cc16c82f03588ed0154c9
diff --git a/native/landlock-run/packages/linux-arm64/README.md b/native/landlock-run/packages/linux-arm64/README.md
index e5117988cf..dfcc9e97dc 100644
--- a/native/landlock-run/packages/linux-arm64/README.md
+++ b/native/landlock-run/packages/linux-arm64/README.md
@@ -1,9 +1,9 @@
-# node-addon-landlock-run-linux-arm64
+# @deepseek-ai/node-addon-landlock-run-linux-arm64
 
 English | [中文](README.zh.md)
 
-Prebuilt `bin/landlock-run` Landlock launcher for linux-arm64 — a static musl binary compiled natively (no cross toolchain) from the C source shipped in [`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run). npm's `os`/`cpu` fields select this package at install time; the entry package resolves it to a file path — it ships no JavaScript and is never imported.
+Prebuilt `bin/landlock-run` Landlock launcher for linux-arm64 — a static musl binary compiled natively (no cross toolchain) from the C source shipped in [`@deepseek-ai/node-addon-landlock-run`](https://www.npmjs.com/package/@deepseek-ai/node-addon-landlock-run). npm's `os`/`cpu` fields select this package at install time; the entry package resolves it to a file path — it ships no JavaScript and is never imported.
 
 The binary is git-ignored and rides the npm tarball via the `files` list; the `prepack` gate refuses to pack when it is missing or has the wrong ELF architecture, and the release pipeline byte-pins the packed binary against the CI build it came from. Static musl linking means one binary for glibc and musl distros alike — hence no libc suffix in the name.
 
-Sibling: `node-addon-landlock-run-linux-x64`.
+Sibling: `@deepseek-ai/node-addon-landlock-run-linux-x64`.
diff --git a/native/landlock-run/packages/linux-arm64/README.zh.md b/native/landlock-run/packages/linux-arm64/README.zh.md
index e502b0239b..350044e92f 100644
--- a/native/landlock-run/packages/linux-arm64/README.zh.md
+++ b/native/landlock-run/packages/linux-arm64/README.zh.md
@@ -1,9 +1,9 @@
-# node-addon-landlock-run-linux-arm64
+# @deepseek-ai/node-addon-landlock-run-linux-arm64
 
 [English](README.md) | 中文
 
-面向 linux-arm64 的预构建 `bin/landlock-run` Landlock 启动器：一个由 [`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) 包所附的 C 源码原生编译而成的静态 musl 二进制文件（不使用交叉工具链）。npm 的 `os`/`cpu` 字段在安装时选择此包；入口包将其定位到文件路径。该包不包含 JavaScript，也绝不会被导入。
+面向 linux-arm64 的预构建 `bin/landlock-run` Landlock 启动器：一个由 [`@deepseek-ai/node-addon-landlock-run`](https://www.npmjs.com/package/@deepseek-ai/node-addon-landlock-run) 包所附的 C 源码原生编译而成的静态 musl 二进制文件（不使用交叉工具链）。npm 的 `os`/`cpu` 字段在安装时选择此包；入口包将其定位到文件路径。该包不包含 JavaScript，也绝不会被导入。
 
 该二进制文件被 git 忽略，并通过 `files` 列表进入 npm tarball；如果文件缺失或 ELF 架构错误，`prepack` 门禁会拒绝打包，发布流水线则会按字节核验打包的二进制文件与其来源 CI 构建产物一致。静态 musl 链接使同一个二进制文件同时适用于 glibc 和 musl 发行版，因此名称中没有 libc 后缀。
 
-同级包：`node-addon-landlock-run-linux-x64`。
+同级包：`@deepseek-ai/node-addon-landlock-run-linux-x64`。
diff --git a/native/landlock-run/packages/linux-arm64/package.json b/native/landlock-run/packages/linux-arm64/package.json
index af5467cead..14190e4765 100644
--- a/native/landlock-run/packages/linux-arm64/package.json
+++ b/native/landlock-run/packages/linux-arm64/package.json
@@ -1,7 +1,7 @@
 {
-  "name": "node-addon-landlock-run-linux-arm64",
+  "name": "@deepseek-ai/node-addon-landlock-run-linux-arm64",
   "version": "0.0.1",
-  "description": "Prebuilt landlock-run Landlock launcher binary for linux-arm64 (static musl) — resolved as a file path by node-addon-landlock-run, never imported",
+  "description": "Prebuilt landlock-run Landlock launcher binary for linux-arm64 (static musl) — resolved as a file path by @deepseek-ai/node-addon-landlock-run, never imported",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/deepseek-harness/deepseek-harness.git",
diff --git a/native/landlock-run/packages/linux-x64/README.i18n.yaml b/native/landlock-run/packages/linux-x64/README.i18n.yaml
index 7050c110ef..cb0022b138 100644
--- a/native/landlock-run/packages/linux-x64/README.i18n.yaml
+++ b/native/landlock-run/packages/linux-x64/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 native/landlock-run/packages/linux-x64/README.md
-README.md: 68b5dfc9b6f437a387c3792ee047a1f11630aca0
-README.zh.md: 3b9578a7eb78dfc05977795ca521cf3a881e9f1a
+README.md: d08cc0c4abbc74f64c5d1075dea796427211bd8f
+README.zh.md: ed6839aa6230b16b82c67a716fc0a4128e5a977c
diff --git a/native/landlock-run/packages/linux-x64/README.md b/native/landlock-run/packages/linux-x64/README.md
index 68b5dfc9b6..d08cc0c4ab 100644
--- a/native/landlock-run/packages/linux-x64/README.md
+++ b/native/landlock-run/packages/linux-x64/README.md
@@ -1,9 +1,9 @@
-# node-addon-landlock-run-linux-x64
+# @deepseek-ai/node-addon-landlock-run-linux-x64
 
 English | [中文](README.zh.md)
 
-Prebuilt `bin/landlock-run` Landlock launcher for linux-x64 — a static musl binary compiled natively (no cross toolchain) from the C source shipped in [`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run). npm's `os`/`cpu` fields select this package at install time; the entry package resolves it to a file path — it ships no JavaScript and is never imported.
+Prebuilt `bin/landlock-run` Landlock launcher for linux-x64 — a static musl binary compiled natively (no cross toolchain) from the C source shipped in [`@deepseek-ai/node-addon-landlock-run`](https://www.npmjs.com/package/@deepseek-ai/node-addon-landlock-run). npm's `os`/`cpu` fields select this package at install time; the entry package resolves it to a file path — it ships no JavaScript and is never imported.
 
 The binary is git-ignored and rides the npm tarball via the `files` list; the `prepack` gate refuses to pack when it is missing or has the wrong ELF architecture, and the release pipeline byte-pins the packed binary against the CI build it came from. Static musl linking means one binary for glibc and musl distros alike — hence no libc suffix in the name.
 
-Sibling: `node-addon-landlock-run-linux-arm64`.
+Sibling: `@deepseek-ai/node-addon-landlock-run-linux-arm64`.
diff --git a/native/landlock-run/packages/linux-x64/README.zh.md b/native/landlock-run/packages/linux-x64/README.zh.md
index 3b9578a7eb..ed6839aa62 100644
--- a/native/landlock-run/packages/linux-x64/README.zh.md
+++ b/native/landlock-run/packages/linux-x64/README.zh.md
@@ -1,9 +1,9 @@
-# node-addon-landlock-run-linux-x64
+# @deepseek-ai/node-addon-landlock-run-linux-x64
 
 [English](README.md) | 中文
 
-面向 linux-x64 的预构建 `bin/landlock-run` Landlock 启动器：一个由 [`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) 包所附的 C 源码原生编译而成的静态 musl 二进制文件（不使用交叉工具链）。npm 的 `os`/`cpu` 字段在安装时选择此包；入口包将其定位到文件路径。该包不包含 JavaScript，也绝不会被导入。
+面向 linux-x64 的预构建 `bin/landlock-run` Landlock 启动器：一个由 [`@deepseek-ai/node-addon-landlock-run`](https://www.npmjs.com/package/@deepseek-ai/node-addon-landlock-run) 包所附的 C 源码原生编译而成的静态 musl 二进制文件（不使用交叉工具链）。npm 的 `os`/`cpu` 字段在安装时选择此包；入口包将其定位到文件路径。该包不包含 JavaScript，也绝不会被导入。
 
 该二进制文件被 git 忽略，并通过 `files` 列表进入 npm tarball；如果文件缺失或 ELF 架构错误，`prepack` 门禁会拒绝打包，发布流水线则会按字节核验打包的二进制文件与其来源 CI 构建产物一致。静态 musl 链接使同一个二进制文件同时适用于 glibc 和 musl 发行版，因此名称中没有 libc 后缀。
 
-同级包：`node-addon-landlock-run-linux-arm64`。
+同级包：`@deepseek-ai/node-addon-landlock-run-linux-arm64`。
diff --git a/native/landlock-run/packages/linux-x64/package.json b/native/landlock-run/packages/linux-x64/package.json
index 375d05332a..43c092d17b 100644
--- a/native/landlock-run/packages/linux-x64/package.json
+++ b/native/landlock-run/packages/linux-x64/package.json
@@ -1,7 +1,7 @@
 {
-  "name": "node-addon-landlock-run-linux-x64",
+  "name": "@deepseek-ai/node-addon-landlock-run-linux-x64",
   "version": "0.0.1",
-  "description": "Prebuilt landlock-run Landlock launcher binary for linux-x64 (static musl) — resolved as a file path by node-addon-landlock-run, never imported",
+  "description": "Prebuilt landlock-run Landlock launcher binary for linux-x64 (static musl) — resolved as a file path by @deepseek-ai/node-addon-landlock-run, never imported",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/deepseek-harness/deepseek-harness.git",
diff --git a/native/landlock-run/scripts/verify-packed-install.mjs b/native/landlock-run/scripts/verify-packed-install.mjs
index 60f225a9d2..928fff50f7 100644
--- a/native/landlock-run/scripts/verify-packed-install.mjs
+++ b/native/landlock-run/scripts/verify-packed-install.mjs
@@ -31,7 +31,7 @@ import { entryDirs, packageDirs, platformDirs, readJson, root } from './repo.mjs
 const args = process.argv.slice(2);
 const currentPlatformOnly = args.includes('--current-platform-only');
 const tarballDir = path.resolve(args.find((arg) => !arg.startsWith('--')) || path.join(root, 'dist', 'npm'));
-const entryPackageName = 'node-addon-landlock-run';
+const entryPackageName = '@deepseek-ai/node-addon-landlock-run';
 
 function tarballName(manifest) {
   if (manifest.name.startsWith('@')) {
@@ -180,10 +180,10 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { grantArgs, launcherPath, probe } from 'node-addon-landlock-run';
+import { grantArgs, launcherPath, probe } from '@deepseek-ai/node-addon-landlock-run';
 
 const requireLandlock = process.env.NALR_REQUIRE_LANDLOCK === '1';
-const platformPackage = 'node-addon-landlock-run-' + process.platform + '-' + process.arch;
+const platformPackage = '@deepseek-ai/node-addon-landlock-run-' + process.platform + '-' + process.arch;
 const resolved = launcherPath();
 assert.ok(path.isAbsolute(resolved), 'launcherPath must be absolute');
 assert.ok(resolved.includes(path.join(...platformPackage.split('/'))), 'launcherPath must point into the platform package: ' + resolved);
diff --git a/native/landlock-run/test/entry.test.js b/native/landlock-run/test/entry.test.js
index 2e2cfe8f17..2b535559a2 100644
--- a/native/landlock-run/test/entry.test.js
+++ b/native/landlock-run/test/entry.test.js
@@ -15,7 +15,7 @@ import {
   grantArgs,
   launcherPath,
   probe,
-} from 'node-addon-landlock-run';
+} from '@deepseek-ai/node-addon-landlock-run';
 
 // --- constants are part of the CLI contract ---
 assert.equal(LAUNCHER_BIN, 'landlock-run');
@@ -31,7 +31,7 @@ assert.deepEqual(
 assert.deepEqual(grantArgs({ readWrite: ['/a'], readOnly: ['/b'] }), ['--ro', '/b', '--rw', '/a']);
 
 // --- launcherPath: resolves the platform package next to its package.json ---
-const platformPackage = `node-addon-landlock-run-${process.platform}-${process.arch}`;
+const platformPackage = `@deepseek-ai/node-addon-landlock-run-${process.platform}-${process.arch}`;
 const resolvedViaSeam = launcherPath((specifier) => {
   assert.equal(specifier, `${platformPackage}/package.json`);
   return path.join('/fake-install', specifier);
diff --git a/native/landlock-run/test/launcher.test.js b/native/landlock-run/test/launcher.test.js
index 55385d2156..a78501cd4a 100644
--- a/native/landlock-run/test/launcher.test.js
+++ b/native/landlock-run/test/launcher.test.js
@@ -22,7 +22,7 @@ import {
   grantArgs,
   launcherPath,
   probe,
-} from 'node-addon-landlock-run';
+} from '@deepseek-ai/node-addon-landlock-run';
 
 const FATAL_PREFIX = 'landlock-run: ';
 const PARTIAL_NOTICE = 'landlock-run: partial enforcement (older Landlock ABI)';
diff --git a/packages/bash/bash-sandbox/package.json b/packages/bash/bash-sandbox/package.json
index 6a29c3f6c8..a771acb1d3 100644
--- a/packages/bash/bash-sandbox/package.json
+++ b/packages/bash/bash-sandbox/package.json
@@ -41,6 +41,6 @@
     "@deepseek-ai/dsh-sandbox-local": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "cordis": "^4.0.0-rc.7",
-    "node-addon-landlock-run": "workspace:*"
+    "@deepseek-ai/node-addon-landlock-run": "workspace:*"
   }
 }
diff --git a/packages/bash/bash-sandbox/tests/landlock.e2e.ts b/packages/bash/bash-sandbox/tests/landlock.e2e.ts
index 7579292fe1..7255ee43c9 100644
--- a/packages/bash/bash-sandbox/tests/landlock.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/landlock.e2e.ts
@@ -5,7 +5,7 @@ import { homedir, tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { launcherPath } from 'node-addon-landlock-run'
+import { launcherPath } from '@deepseek-ai/node-addon-landlock-run'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
diff --git a/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts b/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
index 23546e5d92..b578716c43 100644
--- a/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
+++ b/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
@@ -9,7 +9,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { LAUNCHER_FAILURE_EXIT } from 'node-addon-landlock-run'
+import { LAUNCHER_FAILURE_EXIT } from '@deepseek-ai/node-addon-landlock-run'
 import { SANDBOX_UNAVAILABLE, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
diff --git a/packages/examples/agent-spine-demo/package.json b/packages/examples/agent-spine-demo/package.json
index b9f817d6e5..e6c6ce351d 100644
--- a/packages/examples/agent-spine-demo/package.json
+++ b/packages/examples/agent-spine-demo/package.json
@@ -84,7 +84,7 @@
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-workspace-context": "workspace:^",
-    "node-addon-landlock-run": "workspace:*",
+    "@deepseek-ai/node-addon-landlock-run": "workspace:*",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
diff --git a/packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts b/packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts
index 46f3f56dc3..53722aa7e5 100644
--- a/packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts
+++ b/packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts
@@ -15,7 +15,7 @@ import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import type { ToolResult } from '@deepseek-ai/dsh-tools'
-import { launcherPath } from 'node-addon-landlock-run'
+import { launcherPath } from '@deepseek-ai/node-addon-landlock-run'
 import * as agentSpine from '../src/index.ts'
 
 const bwrapUsable = spawnSync('bwrap', [
diff --git a/packages/sandbox/sandbox-local/README.i18n.yaml b/packages/sandbox/sandbox-local/README.i18n.yaml
index 43fb941975..cbc1e9ad55 100644
--- a/packages/sandbox/sandbox-local/README.i18n.yaml
+++ b/packages/sandbox/sandbox-local/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/sandbox/sandbox-local/README.md
-README.md: f6a1cc2b3e454e0670a564151d41182ec515bdcf
-README.zh.md: 18b66af350932fc8d5c4f184d0e7fa049f910250
+README.md: 23d3a32451c105c71c0a7399ed051288b70753f3
+README.zh.md: 165a6fc88a9fdd219c3ddb016cdf415504556d8c
diff --git a/packages/sandbox/sandbox-local/README.md b/packages/sandbox/sandbox-local/README.md
index f6a1cc2b3e..23d3a32451 100644
--- a/packages/sandbox/sandbox-local/README.md
+++ b/packages/sandbox/sandbox-local/README.md
@@ -12,7 +12,7 @@ Policy is per call; the provider stores only the mechanism and cached runner ver
 
 The Seatbelt profile is allow-default with `(deny file-write*)` plus write allow-lists, so exactly the mode's promised file effects are governed: `read-only` grants the `/dev/null` literal alone; `workspace-write` adds the workspace root, `/tmp`, and the per-user darwin temp dir (`os.tmpdir()` — the platform's real temp area for mkstemp-family tools), every root canonicalized because Seatbelt matches resolved paths (`/tmp` IS `/private/tmp`). Apple marks the `sandbox-exec` CLI deprecated but ships it on every macOS; the functional probe is what fails closed if that ever changes.
 
-[`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) supplies the platform launcher, functional probe, and CLI argument vocabulary. This provider owns only mode-to-grant mapping and runner selection. Keeping path resolution and probe parsing with the versioned binary prevents contract drift.
+[`@deepseek-ai/node-addon-landlock-run`](https://www.npmjs.com/package/@deepseek-ai/node-addon-landlock-run) supplies the platform launcher, functional probe, and CLI argument vocabulary. This provider owns only mode-to-grant mapping and runner selection. Keeping path resolution and probe parsing with the versioned binary prevents contract drift.
 
 ```yaml
 - id: sandbox
diff --git a/packages/sandbox/sandbox-local/README.zh.md b/packages/sandbox/sandbox-local/README.zh.md
index 18b66af350..165a6fc88a 100644
--- a/packages/sandbox/sandbox-local/README.zh.md
+++ b/packages/sandbox/sandbox-local/README.zh.md
@@ -12,7 +12,7 @@
 
 Seatbelt profile 默认允许，但带 `(deny file-write*)` 和写入 allow-list，因此恰好约束相应模式承诺的文件操作：`read-only` 只授予 `/dev/null` 字面路径；`workspace-write` 另加工作区根目录、`/tmp` 和逐用户 darwin 临时目录（`os.tmpdir()`，即平台供 mkstemp 家族工具使用的真实临时区域）。每个根目录都经过规范化，因为 Seatbelt 匹配解析后的路径（`/tmp` 就是 `/private/tmp`）。Apple 将 `sandbox-exec` CLI（命令行界面）标为 deprecated，但所有 macOS 系统仍会提供它；若情况发生变化，功能探测会使执行被拒绝。
 
-[`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run)提供平台 launcher、功能探测和 CLI 参数词汇。该提供方只负责模式到授权的映射与 runner 选择。把路径解析和探测解析保留在带版本的 binary 中，可防止契约漂移。
+[`@deepseek-ai/node-addon-landlock-run`](https://www.npmjs.com/package/@deepseek-ai/node-addon-landlock-run)提供平台 launcher、功能探测和 CLI 参数词汇。该提供方只负责模式到授权的映射与 runner 选择。把路径解析和探测解析保留在带版本的 binary 中，可防止契约漂移。
 
 ```yaml
 - id: sandbox
diff --git a/packages/sandbox/sandbox-local/package.json b/packages/sandbox/sandbox-local/package.json
index f7004c4d5c..eace2ef08c 100644
--- a/packages/sandbox/sandbox-local/package.json
+++ b/packages/sandbox/sandbox-local/package.json
@@ -31,7 +31,7 @@
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
-    "node-addon-landlock-run": "workspace:*",
+    "@deepseek-ai/node-addon-landlock-run": "workspace:*",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts
index 64e92d9bf2..7e9405d14b 100644
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -12,7 +12,7 @@ import {
   LAUNCHER_FAILURE_EXIT,
   launcherPath as landlockLauncherPath,
   probe as defaultProbeLandlock,
-} from 'node-addon-landlock-run'
+} from '@deepseek-ai/node-addon-landlock-run'
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { assertNever } from '@deepseek-ai/dsh-llm'
diff --git a/packages/sandbox/sandbox-local/src/profiles.ts b/packages/sandbox/sandbox-local/src/profiles.ts
index cee0f00852..5b76390319 100644
--- a/packages/sandbox/sandbox-local/src/profiles.ts
+++ b/packages/sandbox/sandbox-local/src/profiles.ts
@@ -4,7 +4,7 @@
  * @module @deepseek-ai/dsh-sandbox-local/profiles
  */
 
-import { grantArgs as landlockGrantArgs } from 'node-addon-landlock-run'
+import { grantArgs as landlockGrantArgs } from '@deepseek-ai/node-addon-landlock-run'
 import { writableRoots } from '@deepseek-ai/dsh-sandbox'
 import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 
diff --git a/packages/sandbox/sandbox-local/tests/landlock.e2e.ts b/packages/sandbox/sandbox-local/tests/landlock.e2e.ts
index 6e2faecc6b..ff4947a4ca 100644
--- a/packages/sandbox/sandbox-local/tests/landlock.e2e.ts
+++ b/packages/sandbox/sandbox-local/tests/landlock.e2e.ts
@@ -6,7 +6,7 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
-import { launcherPath } from 'node-addon-landlock-run'
+import { launcherPath } from '@deepseek-ai/node-addon-landlock-run'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 
 /**
diff --git a/packages/sandbox/sandbox-local/tests/local.spec.ts b/packages/sandbox/sandbox-local/tests/local.spec.ts
index 74d4c2a8a1..b1b8b2c4a8 100644
--- a/packages/sandbox/sandbox-local/tests/local.spec.ts
+++ b/packages/sandbox/sandbox-local/tests/local.spec.ts
@@ -12,7 +12,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import { LAUNCHER_FAILURE_EXIT } from 'node-addon-landlock-run'
+import { LAUNCHER_FAILURE_EXIT } from '@deepseek-ai/node-addon-landlock-run'
 import { SANDBOX_UNAVAILABLE, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import {
diff --git a/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts b/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
index 612751e6da..5f4fa5a3bb 100644
--- a/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
+++ b/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
@@ -23,6 +23,7 @@ const packageDir = fileURLToPath(new URL('..', import.meta.url))
 const repoRoot = fileURLToPath(new URL('../../../..', import.meta.url))
 const nativeDir = join(repoRoot, 'native/landlock-run')
 const sourceLauncher = join(nativeDir, 'packages', `linux-${process.arch}`, 'bin', 'landlock-run')
+const platformPackageName = `@deepseek-ai/node-addon-landlock-run-linux-${process.arch}`
 
 /** The harness closure the consumer needs; native tarballs are packed through their mode-preserving release script. */
 const WORKSPACE_CLOSURE = [
@@ -108,7 +109,7 @@ describe.skipIf(!packable)('sandbox-local: packed-tarball distribution (publish-
       import { spawnSync } from 'node:child_process'
       import { existsSync } from 'node:fs'
       import { Context } from 'cordis'
-      import { launcherPath } from 'node-addon-landlock-run'
+      import { launcherPath } from '@deepseek-ai/node-addon-landlock-run'
       import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
       const ctx = new Context()
       await ctx.plugin(LocalSandboxProvider, {})
@@ -145,7 +146,7 @@ describe.skipIf(!packable)('sandbox-local: packed-tarball distribution (publish-
   })
 
   it('installs this checkout\'s launcher for the host: present, executable, byte-identical, and right ELF arch', () => {
-    const installed = join(consumerDir, 'node_modules', `node-addon-landlock-run-linux-${process.arch}`, 'bin', 'landlock-run')
+    const installed = join(consumerDir, 'node_modules', ...platformPackageName.split('/'), 'bin', 'landlock-run')
     expect(existsSync(installed), 'platform package missing from the installed tree').toBe(true)
     // A tarball or extraction step that strips the mode bit would leave the
     // probe failing exactly like a non-enforcing kernel — assert it apart.
@@ -156,7 +157,7 @@ describe.skipIf(!packable)('sandbox-local: packed-tarball distribution (publish-
 
   it('the installed provider resolves the launcher INSIDE the consumer node_modules platform package', () => {
     expect(verdict.launcher)
-      .toBe(join(consumerDir, 'node_modules', `node-addon-landlock-run-linux-${process.arch}`, 'bin', 'landlock-run'))
+      .toBe(join(consumerDir, 'node_modules', ...platformPackageName.split('/'), 'bin', 'landlock-run'))
   })
 
   it('confines through the installed launcher (enforcing kernel) or fails closed (non-enforcing) — never unconfined', async () => {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ef10b7c2d7..a93b757791 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -853,12 +853,12 @@ importers:
 
   native/landlock-run:
     devDependencies:
+      '@deepseek-ai/node-addon-landlock-run':
+        specifier: workspace:*
+        version: link:packages/entry
       '@types/node':
         specifier: ^26.0.1
         version: 26.1.2
-      node-addon-landlock-run:
-        specifier: workspace:*
-        version: link:packages/entry
       tsx:
         specifier: ^4.20.6
         version: 4.22.4
@@ -868,10 +868,10 @@ importers:
 
   native/landlock-run/packages/entry:
     optionalDependencies:
-      node-addon-landlock-run-linux-arm64:
+      '@deepseek-ai/node-addon-landlock-run-linux-arm64':
         specifier: workspace:*
         version: link:../linux-arm64
-      node-addon-landlock-run-linux-x64:
+      '@deepseek-ai/node-addon-landlock-run-linux-x64':
         specifier: workspace:*
         version: link:../linux-x64
 
@@ -1010,12 +1010,12 @@ importers:
       '@deepseek-ai/dsh-subprocess-local':
         specifier: workspace:^
         version: link:../../subprocess/subprocess-local
+      '@deepseek-ai/node-addon-landlock-run':
+        specifier: workspace:*
+        version: link:../../../native/landlock-run/packages/entry
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
-      node-addon-landlock-run:
-        specifier: workspace:*
-        version: link:../../../native/landlock-run/packages/entry
 
   packages/bash/pwsh-local:
     dependencies:
@@ -2969,12 +2969,12 @@ importers:
       '@deepseek-ai/dsh-workspace-context':
         specifier: workspace:^
         version: link:../../context/workspace-context
+      '@deepseek-ai/node-addon-landlock-run':
+        specifier: workspace:*
+        version: link:../../../native/landlock-run/packages/entry
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
-      node-addon-landlock-run:
-        specifier: workspace:*
-        version: link:../../../native/landlock-run/packages/entry
 
   packages/examples/cli-demo:
     devDependencies:
@@ -4255,7 +4255,7 @@ importers:
 
   packages/sandbox/sandbox-local:
     dependencies:
-      node-addon-landlock-run:
+      '@deepseek-ai/node-addon-landlock-run':
         specifier: workspace:*
         version: link:../../../native/landlock-run/packages/entry
       schemastery:
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 0a446d77f8..dabd0f7805 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -31,10 +31,14 @@ const vendoredPackages = new Set([
   '@cordisjs/plugin-logger-console',
 ])
 const publicLandlockPackages = new Set([
-  'node-addon-landlock-run',
-  'node-addon-landlock-run-linux-arm64',
-  'node-addon-landlock-run-linux-x64',
+  '@deepseek-ai/node-addon-landlock-run',
+  '@deepseek-ai/node-addon-landlock-run-linux-arm64',
+  '@deepseek-ai/node-addon-landlock-run-linux-x64',
 ])
+/** Deliberate source payloads whose exact bytes are part of the package's audit surface. */
+const publicationSourceAllowlist: Readonly<Record<string, readonly string[]>> = {
+  '@deepseek-ai/node-addon-landlock-run': ['src/main.c'],
+}
 const repositoryUrl = 'git+https://github.com/deepseek-harness/deepseek-harness.git'
 
 const localArtifactDirs = new Set(['node_modules'])
@@ -200,8 +204,9 @@ function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
   }
 
   if (manifest.name?.startsWith('@deepseek-ai/')) {
+    const allowedSources = publicationSourceAllowlist[manifest.name] ?? []
     for (const file of manifest.files ?? []) {
-      if (isForbiddenPublicationFile(file)) {
+      if (isForbiddenPublicationFile(file) && !allowedSources.includes(file)) {
         errors.push(`${label}: package.json files must not publish ${JSON.stringify(file)}`)
       }
     }
diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts
index e56cce670a..04ea0cf8eb 100644
--- a/scripts/gen-third-party-notices.ts
+++ b/scripts/gen-third-party-notices.ts
@@ -41,9 +41,9 @@ const DEV_ONLY_AREAS = [
 
 /** First-party public native packages: reachable at runtime but not third-party. */
 const FIRST_PARTY = new Set([
-  'node-addon-landlock-run',
-  'node-addon-landlock-run-linux-arm64',
-  'node-addon-landlock-run-linux-x64',
+  '@deepseek-ai/node-addon-landlock-run',
+  '@deepseek-ai/node-addon-landlock-run-linux-arm64',
+  '@deepseek-ai/node-addon-landlock-run-linux-x64',
 ])
 
 /**
@@ -587,7 +587,7 @@ ${BUILD_TIME_TOOLS.map(tool => `| [\`${tool.name}\`](${tool.repo}) | ${tool.lice
 
 ## First-party native packages
 
-\`node-addon-landlock-run\` (and its platform packages) is built and released from this repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party.
+\`@deepseek-ai/node-addon-landlock-run\` (and its platform packages) is built and released from this repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party.
 `
 }
 
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 634464cb9b..2965a1f794 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -38,7 +38,7 @@
       "@cordisjs/plugin-timer": ["./vendor/timer/src"],
       "@cordisjs/plugin-hmr": ["./vendor/hmr/src"],
       "@cordisjs/plugin-logger-console": ["./vendor/logger-console/src"],
-      "node-addon-landlock-run": ["./native/landlock-run/packages/entry/src/index.ts"],
+      "@deepseek-ai/node-addon-landlock-run": ["./native/landlock-run/packages/entry/src/index.ts"],
       "@deepseek-ai/dsh-invariants": ["./packages/support/invariants/src/index.ts"],
       "@deepseek-ai/dsh-typert-registry": ["./packages/typert/registry/src/index.ts"],
       "@deepseek-ai/dsh-typert-loader": ["./packages/typert/loader/src/index.ts"],

From a7c035285b810c8287e9b2028e0731da565340c7 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 14:50:21 +0800
Subject: [PATCH 047/516] revert: leave markdown snapshots unchanged

---
 apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md     | 2 +-
 .../tests/snapshots/markdown-inline-code-links/ui.expected.md   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md b/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md
index 187ab25e8c..68a4df5603 100644
--- a/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md
+++ b/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md
@@ -40,7 +40,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}} Ran for {{duration}}
+- text: {{clock}}Ran for {{duration}}
 - textbox "Message the agent"
 - button "Commands":
   - img
diff --git a/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md b/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md
index 19efa06238..059849223c 100644
--- a/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md
+++ b/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md
@@ -31,7 +31,7 @@
   - img
 - button "Branch into a new conversation":
   - img
-- text: {{clock}} Ran for {{duration}}
+- text: {{clock}}Ran for {{duration}}
 - textbox "Message the agent"
 - button "Commands":
   - img

From 4e8067e8d52deec3d0320a9f5d4135034d74a976 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Thu, 6 Aug 2026 14:57:30 +0800
Subject: [PATCH 048/516] refactor(telemetry): replay feedback sessions without
 buffering

---
 ...3-session-telemetry-otel-revival.i18n.yaml |   4 +-
 ...26-07-23-session-telemetry-otel-revival.md |   6 +-
 ...07-23-session-telemetry-otel-revival.zh.md |   6 +-
 ...feedback-gated-session-telemetry.i18n.yaml |   4 +-
 ...-08-05-feedback-gated-session-telemetry.md |  12 +-
 ...-05-feedback-gated-session-telemetry.zh.md |  12 +-
 ...6-buffer-free-feedback-telemetry.i18n.yaml |   6 +
 ...26-08-06-buffer-free-feedback-telemetry.md |  29 +++
 ...08-06-buffer-free-feedback-telemetry.zh.md |  29 +++
 docs/config-catalog.md                        |   2 +-
 docs/cordis-catalog/events.md                 |   9 +-
 docs/event-producer-consumer.md               |   2 +-
 .../cordis/tool-cordis/src/api-catalog.ts     |   2 +-
 .../session-telemetry-otel/README.i18n.yaml   |   4 +-
 .../session-telemetry-otel/README.md          |   8 +-
 .../session-telemetry-otel/README.zh.md       |   8 +-
 .../session-telemetry-otel/src/index.ts       |  19 +-
 .../session-telemetry-otel/tests/otel.spec.ts |   2 +-
 .../session-telemetry/README.i18n.yaml        |   4 +-
 .../telemetry/session-telemetry/README.md     |  12 +-
 .../telemetry/session-telemetry/README.zh.md  |  12 +-
 .../session-telemetry/src/coordinator.ts      | 180 ++++++++----------
 .../telemetry/session-telemetry/src/index.ts  |  20 +-
 .../session-telemetry/tests/telemetry.spec.ts |  78 +++++---
 24 files changed, 270 insertions(+), 200 deletions(-)
 create mode 100644 .agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.i18n.yaml
 create mode 100644 .agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md
 create mode 100644 .agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.zh.md

diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index 3f487762d6..ecb7ca1588 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.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 .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
-2026-07-23-session-telemetry-otel-revival.md: dcbff9757cbb730b66f456535fbd7ae471b6ffd1
-2026-07-23-session-telemetry-otel-revival.zh.md: c3a098041795fa92bb4e0dd421ca09be94907cb8
+2026-07-23-session-telemetry-otel-revival.md: f83128e8bf62e0718e59912c16c4e449855aaa1a
+2026-07-23-session-telemetry-otel-revival.zh.md: 6f955cc9e1b44ed4a558515c4904b46a9cec585f
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
index dcbff9757c..f83128e8bf 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
@@ -12,9 +12,9 @@ Every deployment that wants harness sessions in an observability stack must hand
 
 `packages/telemetry/` revives the two reviewed packages under the SDK stance — the harness provides the capability, the deployment configures where records go and owns what leaves in them:
 
-- **`@deepseek-ai/dsh-session-telemetry`** — the seam. `TelemetryBackend` (`emit`/`flush?`/`shutdown`), the service-registered `Telemetry` form, and `TelemetryCoordinator` owning capture: adoption with cursor read-back, the per-append firehose (project → `structuredClone` → redact → `emit`, zero I/O), the fixed first-chunk-per-(turn, step) projection, the `agent/error` relay, and dispose-time `shutdown` records.
+- **`@deepseek-ai/dsh-session-telemetry`** — the seam. `TelemetryBackend` (`emit`/`flush?`/`shutdown`), the service-registered `Telemetry` form, and `TelemetryCoordinator` owning capture: live adoption with cursor read-back and the per-append firehose (project → `structuredClone` → redact → `emit`, zero I/O), buffer-free on-demand replay from the canonical log, the fixed first-chunk-per-(turn, step) projection, the live `agent/error` relay, and live dispose-time `shutdown` records.
 - **The `telemetry/record` waterfall** — the delta over the branch version and the seam's redaction extension point. Every record passes it before reaching any backend; the seam ships NO rules of its own — the innermost `next()` is a pass-through, deployments mount their rules as listeners (stacking by transforming `next()`'s return value), and a throwing rule withholds the record fail-closed. Redaction applies to the exported copy only; the canonical log is never rewritten.
-- **`@deepseek-ai/dsh-session-telemetry-otel`** — the reference backend: OTel JS SDK log pipeline (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter), configured verbatim through `exporter`/`processor` passthroughs. Its default `FULL` mode requires `exporter.url`; the later [feedback-gated telemetry decision](2026-08-05-feedback-gated-session-telemetry.md) adds `FEEDBACK_ONLY` and `DISABLED` delivery modes without moving the redaction or backend boundary.
+- **`@deepseek-ai/dsh-session-telemetry-otel`** — the reference backend: OTel JS SDK log pipeline (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter), configured verbatim through `exporter`/`processor` passthroughs. Its default `FULL` mode requires `exporter.url`; the later [feedback-gated telemetry decision](2026-08-05-feedback-gated-session-telemetry.md) adds `FEEDBACK_ONLY` and `DISABLED` delivery modes without moving the redaction or backend boundary, while [buffer-free feedback replay](../simplification/2026-08-06-buffer-free-feedback-telemetry.md) avoids a second in-memory copy of the session prefix.
 
 The boundary axiom holds: the harness's aspect ends at `emit()`. Batching, retry, queueing, and loss policy are the reporting SDK's, configured through passthroughs — delivery is best-effort (at-most-once across a crash), which the READMEs state plainly.
 
@@ -34,4 +34,4 @@ The boundary axiom holds: the harness's aspect ends at `emit()`. Batching, retry
 
 ## Consequences
 
-A deployment adds one `cordis.yml` entry with an OTLP endpoint and gets its session stream in any OTel-compatible stack. `FULL` preserves that behavior by default, `FEEDBACK_ONLY` withholds records until feedback releases a prefix, and `DISABLED` constructs no reporting pipeline; removing the entry remains a silent opt-out, while the disabled mode keeps the local feedback warning. A rule-free deployment exports records exactly as captured — including any credentials embedded in file contents or command output — so a deployment crossing a trust boundary must mount `telemetry/record` listeners, and both READMEs state this plainly. Where rules are mounted, exported bodies can differ from canonical log bytes, so receivers must not treat telemetry as a byte-exact replica; the log remains the source of truth. Crash durability is explicitly out of scope until the outbox decision above is revisited.
+A deployment adds one `cordis.yml` entry with an OTLP endpoint and gets its session stream in any OTel-compatible stack. `FULL` preserves that behavior by default, `FEEDBACK_ONLY` replays a canonical-log prefix when feedback is recorded, and `DISABLED` constructs no reporting pipeline; removing the entry remains a silent opt-out, while the disabled mode keeps the local feedback warning. A rule-free deployment exports records exactly as captured — including any credentials embedded in file contents or command output — so a deployment crossing a trust boundary must mount `telemetry/record` listeners, and both READMEs state this plainly. Where rules are mounted, exported bodies can differ from canonical log bytes, so receivers must not treat telemetry as a byte-exact replica; the log remains the source of truth. Crash durability is explicitly out of scope until the outbox decision above is revisited.
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index c3a0980417..6f955cc9e1 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 `packages/telemetry/` 以 SDK 立场复活这两个经过评审的包——harness 提供能力，部署方配置上报去向并对导出内容负责：
 
-- **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的收养、逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、固定的每 (turn, step) 首 chunk 投影、`agent/error` 转发、以及 dispose 时的 `shutdown` 记录。
+- **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的实时收养与逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、从权威日志进行的无缓冲按需回放、固定的每 (turn, step) 首 chunk 投影、实时 `agent/error` 转发，以及实时 dispose 时的 `shutdown` 记录。
 - **`telemetry/record` waterfall** —— 相对分支版本的增量，也是该 seam 的脱敏扩展点。每条记录抵达任何 backend 前必经此处；seam 自身不带任何规则——最内层 `next()` 原样透传，部署方以监听器挂载自己的规则（通过变换 `next()` 的返回值堆叠），抛异常的规则将该记录 fail-closed 扣下。脱敏只作用于导出副本；canonical log 永不改写。
-- **`@deepseek-ai/dsh-session-telemetry-otel`** —— 参考 backend：OTel JS SDK 日志管线（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter），经 `exporter`/`processor` passthrough 原样配置。其默认 `FULL` 模式要求 `exporter.url`；后续的[反馈门控遥测决策](2026-08-05-feedback-gated-session-telemetry.md)增加了 `FEEDBACK_ONLY` 与 `DISABLED` 投递模式，但未移动脱敏或后端边界。
+- **`@deepseek-ai/dsh-session-telemetry-otel`** —— 参考 backend：OTel JS SDK 日志管线（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter），经 `exporter`/`processor` passthrough 原样配置。其默认 `FULL` 模式要求 `exporter.url`；后续的[反馈门控遥测决策](2026-08-05-feedback-gated-session-telemetry.md)增加了 `FEEDBACK_ONLY` 与 `DISABLED` 投递模式，但未移动脱敏或后端边界，而[无缓冲反馈回放](../simplification/2026-08-06-buffer-free-feedback-telemetry.md)避免在内存中创建会话前缀的第二份副本。
 
 边界公理保持不变：harness 的职责止于 `emit()`。批处理、重试、排队与丢失策略属于 reporting SDK，经 passthrough 配置——投递是尽力而为（崩溃时至多一次），README 对此如实陈述。
 
@@ -34,4 +34,4 @@ Status: implemented
 
 ## Consequences
 
-部署方在 `cordis.yml` 加一个带 OTLP endpoint 的条目即可把会话流接入任何 OTel 兼容体系。`FULL` 默认保留该行为，`FEEDBACK_ONLY` 在反馈释放前暂存记录前缀，`DISABLED` 则不构造上报流水线；删除条目仍是静默退出方式，而禁用模式会保留本地反馈警告。未挂载规则的部署导出的记录与捕获时完全一致，包括文件内容与命令输出中内嵌的任何凭据。因此，跨信任边界的部署必须挂载 `telemetry/record` 监听器，两个 README 对此如实陈述。挂载规则后，导出的 body 可能与 canonical log 字节不同，接收端不得把遥测当作字节精确副本；日志仍是真源。崩溃持久性在上述 outbox 决定重启前明确不在范围内。
+部署方在 `cordis.yml` 加一个带 OTLP endpoint 的条目即可把会话流接入任何 OTel 兼容体系。`FULL` 默认保留该行为，`FEEDBACK_ONLY` 在记录反馈时回放权威日志前缀，`DISABLED` 则不构造上报流水线；删除条目仍是静默退出方式，而禁用模式会保留本地反馈警告。未挂载规则的部署导出的记录与捕获时完全一致，包括文件内容与命令输出中内嵌的任何凭据。因此，跨信任边界的部署必须挂载 `telemetry/record` 监听器，两个 README 对此如实陈述。挂载规则后，导出的 body 可能与 canonical log 字节不同，接收端不得把遥测当作字节精确副本；日志仍是真源。崩溃持久性在上述 outbox 决定重启前明确不在范围内。
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
index d12ad78728..7909316acd 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.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 .agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
-2026-08-05-feedback-gated-session-telemetry.md: 21a9028c603f3faaec39b2ddb8ef14644d6c84d4
-2026-08-05-feedback-gated-session-telemetry.zh.md: ea94c743b962a93a5fc64bdc2e4ed103aadecc99
+2026-08-05-feedback-gated-session-telemetry.md: 25cc17f75629f72d7351eb0537d72b700c84411f
+2026-08-05-feedback-gated-session-telemetry.zh.md: b0e84e60e27fa20f66113c11db62026583a27a19
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
index 21a9028c60..25cc17f756 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
@@ -13,23 +13,21 @@ Session telemetry originally has one mounted behavior: every accepted record ent
 `@deepseek-ai/dsh-session-telemetry-otel` exposes three uppercase `mode` values:
 
 - `FULL` is the default and preserves immediate delivery to the configured OTel pipeline.
-- `FEEDBACK_ONLY` captures redacted copies in memory and releases the pending session prefix when `feedback/record` is appended. The released prefix includes the feedback event itself. Records appended after that event form another withheld prefix until another feedback event releases them.
+- `FEEDBACK_ONLY` reads the canonical session log when `feedback/record` is appended and hands over the unreleased prefix through that exact event. Records appended after that boundary remain local until another feedback event.
 - `DISABLED` constructs no exporter, processor, or logger provider. A `feedback/record` listener prints that nothing is shared and the feedback remains local.
 
-The generic telemetry coordinator owns the delivery distinction as `immediate` or `held`. Both paths project, clone, and run `telemetry/record` listeners at capture time. Immediate delivery sends the accepted record to the backend and advances the session's handoff cursor. Held delivery retains the accepted record per session without moving that cursor. `release(session)` submits the retained records in order, contains each backend failure independently, advances the cursor only for submitted records, and removes the released prefix.
+The generic telemetry coordinator owns `live` and `on-demand` capture. Live capture projects, clones, redacts, and hands each event to the backend on the session firehose. On-demand capture registers no continuous capture listeners; `captureSession(session, throughSeq)` reads the canonical log from the handoff cursor through an inclusive boundary, then projects, clones, redacts, and hands over that prefix. The cursor advances only for handed-over records. The [buffer-free replay decision](../simplification/2026-08-06-buffer-free-feedback-telemetry.md) owns why the on-demand path uses the canonical log instead of copied records.
 
-The OTel feedback listener is registered after the coordinator's session listener. Cordis therefore gives the coordinator the feedback append first, then the OTel listener releases a prefix that already contains that event. `exporter.url` is required in `FULL` and `FEEDBACK_ONLY`; `DISABLED` does not validate or use exporter configuration.
+The OTel feedback listener passes the feedback event's sequence to `captureSession()`. `Session.append` commits the event before publishing `session/event`, so replay includes that feedback but cannot extend past its boundary. `exporter.url` is required in `FULL` and `FEEDBACK_ONLY`; `DISABLED` does not validate or use exporter configuration.
 
 ## Alternatives considered
 
 **Open a session permanently after its first feedback.** Rejected because later work would be shared without another feedback act and the plugin would need additional open-session state. Releasing one pending prefix per feedback has the smaller state machine and the narrower sharing boundary.
 
-**Buffer after `TelemetryCoordinator.emit()` in the OTel backend.** Rejected because the coordinator would advance its handoff cursor before a record became eligible for upload. A plugin rebuild would then lose the only retained copy and incorrectly treat the prefix as handed off.
-
-**Replay the canonical session log when feedback arrives.** Rejected because replay would repeat projection and redaction, exclude telemetry operation records that are not session events, and require more lifecycle state to distinguish previously released prefixes.
+**Retain capture-time redacted records until feedback.** Rejected because it duplicates an unbounded session prefix even though the canonical log already owns the events. It preserves capture-time redaction policy and operational records, but those properties do not justify the memory cost for a mode defined as uploading the session log after feedback.
 
 **Use an unmounted plugin as the disabled state.** That remains the silent opt-out, but it cannot warn when feedback is recorded. The explicit disabled mode lets a deployment keep one configuration shape and communicate that the local feedback did not leave the process.
 
 ## Consequences
 
-`FULL` remains source- and wire-compatible with the original default. `FEEDBACK_ONLY` retains deep-copied, already-redacted records in process memory until feedback or session collection; a crash before release uploads nothing from that prefix. A clean shutdown after the last feedback is part of the new withheld suffix, so feedback-only streams do not carry a reliable shutdown or crash signal. Each later feedback releases the suffix accumulated since the previous one. `DISABLED` can omit `exporter.url`, does no reporting work, and keeps feedback only in the canonical session log.
+`FULL` remains source- and wire-compatible with the original default. `FEEDBACK_ONLY` adds no telemetry-owned per-event buffer before feedback; a crash before feedback uploads nothing from that prefix. Replay applies the redaction policy mounted when feedback is recorded and excludes operational records that do not exist in the canonical log. Feedback-only streams therefore carry neither `agent-error` nor `shutdown` records, and shutdown absence is not a crash signal. Each later feedback captures the suffix accumulated since the previous boundary. `DISABLED` can omit `exporter.url`, does no reporting work, and keeps feedback only in the canonical session log.
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
index ea94c743b9..b0e84e60e2 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
@@ -13,23 +13,21 @@ Status: implemented
 `@deepseek-ai/dsh-session-telemetry-otel` 公开三个大写的 `mode` 值：
 
 - `FULL` 是默认值，保留向已配置 OTel 流水线的即时投递。
-- `FEEDBACK_ONLY` 在内存中捕获已脱敏副本，并在追加 `feedback/record` 时释放待处理的会话前缀。已释放前缀包含反馈事件本身。在该事件之后追加的记录会形成另一个暂存前缀，直到下一个反馈事件将其释放。
+- `FEEDBACK_ONLY` 在追加 `feedback/record` 时读取权威会话日志，并交接截至该事件的未释放前缀。该边界后追加的记录会留在本地，直到另一个反馈事件。
 - `DISABLED` 不构造导出器、处理器或日志提供方。`feedback/record` 监听器会输出警告，说明什么都不会共享，且反馈仍留在本地。
 
-通用遥测协调器以 `immediate` 或 `held` 的形式拥有这两种投递方式。两条路径都会在捕获时进行投影、深拷贝，并运行 `telemetry/record` 监听器。即时投递把已接受记录发送到后端，并推进会话的 handoff 游标。暂存投递按会话保留已接受记录，且不移动该游标。`release(session)` 按顺序提交保留的记录，独立隔离每个后端失败，仅为已提交的记录推进游标，并移除已释放前缀。
+通用遥测协调器拥有 `live` 与 `on-demand` 捕获。实时捕获在会话 firehose 上投影、深拷贝、脱敏每个事件，并将其交给后端。按需捕获不注册持续捕获监听器；`captureSession(session, throughSeq)` 从 handoff 游标起读取权威日志，直至含边界的指定序列号，然后投影、深拷贝、脱敏并交接该前缀。游标只为已交接记录推进。[无缓冲回放决策](../simplification/2026-08-06-buffer-free-feedback-telemetry.md)说明了按需路径为何使用权威日志而非记录副本。
 
-OTel 反馈监听器在协调器的会话监听器之后注册。因此，Cordis 先将反馈追加交给协调器，再由 OTel 监听器释放已包含该事件的前缀。`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填；`DISABLED` 不校验也不使用导出器配置。
+OTel 反馈监听器把反馈事件的序列号传给 `captureSession()`。`Session.append` 在发布 `session/event` 前已提交该事件，因此回放会包含该反馈，但不会超过其边界。`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填；`DISABLED` 不校验也不使用导出器配置。
 
 ## 考虑过的替代方案
 
 **会话在首次反馈后永久开放。** 已否决，因为后续工作会在用户未再次提交反馈的情况下被共享，而且插件需要额外的会话开放状态。每次反馈只释放一个待处理前缀，状态机更小，共享边界也更窄。
 
-**在 OTel 后端的 `TelemetryCoordinator.emit()` 之后缓冲。** 已否决，因为协调器会在记录具备上传资格前推进 handoff 游标。插件重建后，唯一保留的副本会丢失，而协调器会错误地将该前缀视为已交接。
-
-**反馈到达时回放权威会话日志。** 已否决，因为回放会重复执行投影与脱敏，排除不属于会话事件的遥测运维记录，且需要更多生命周期状态才能区分已释放前缀。
+**反馈前保留捕获时已脱敏记录。** 已否决，因为权威日志已拥有这些事件，该方案仍会复制无上限的会话前缀。它能保留捕获时的脱敏策略与运维记录，但对于一个定义为「反馈后上传会话日志」的模式，这些性质不足以证明该内存成本合理。
 
 **以不挂载插件表示禁用状态。** 这仍然是静默退出方式，但无法在记录反馈时输出警告。显式禁用模式让部署方可以保持同一种配置形态，并说明本地反馈未离开进程。
 
 ## 后果
 
-`FULL` 与原有默认值保持源码及协议兼容。`FEEDBACK_ONLY` 会在进程内存中保留已深拷贝且已脱敏的记录，直到收到反馈或会话被回收；释放前发生崩溃时，该前缀不上传任何内容。上次反馈之后的干净关闭属于新的暂存后缀，因此仅反馈的流不携带可靠的关闭或崩溃信号。每个后续反馈都会释放从上一个反馈开始累积的后缀。`DISABLED` 可省略 `exporter.url`，不执行任何上报工作，并仅在权威会话日志中保留反馈。
+`FULL` 与原有默认值保持源码及协议兼容。`FEEDBACK_ONLY` 在反馈前不增加遥测自有的逐事件缓冲；反馈前发生崩溃时，该前缀不上传任何内容。回放使用记录反馈时挂载的脱敏策略，并排除权威日志中不存在的运维记录。因此，仅反馈的流既不携带 `agent-error` 记录，也不携带 `shutdown` 记录，而缺少 shutdown 不是崩溃信号。每个后续反馈都会捕获从上一个边界起累积的后缀。`DISABLED` 可省略 `exporter.url`，不执行任何上报工作，并仅在权威会话日志中保留反馈。
diff --git a/.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.i18n.yaml
new file mode 100644
index 0000000000..9f6288ac04
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.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-08-06-buffer-free-feedback-telemetry.md
+2026-08-06-buffer-free-feedback-telemetry.md: 008bebdcb59f7ef4fe49f8e731aad77861368d5c
+2026-08-06-buffer-free-feedback-telemetry.zh.md: 7052e075921f4470864f5ea1c4aed5cf6201becf
diff --git a/.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md b/.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md
new file mode 100644
index 0000000000..008bebdcb5
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md
@@ -0,0 +1,29 @@
+# Agent Note: Buffer-free feedback telemetry
+
+Status: implemented
+
+English | [中文](2026-08-06-buffer-free-feedback-telemetry.zh.md)
+
+## Problem
+
+Feedback-only telemetry must upload the session-log prefix only after recorded feedback. Retaining a deep-copied, redacted record for every projected event until that trigger duplicates the canonical session log and grows without a bound for a long-lived session that never records feedback.
+
+## Decision
+
+The telemetry coordinator provides `live` and `on-demand` capture. On-demand capture registers no session, flush, or operational-event listeners and retains no projected records. `captureSession(session, throughSeq?)` reads the canonical session log after the handoff cursor through an optional inclusive sequence boundary, applies the fixed projection, deep-copies each accepted event, runs the current `telemetry/record` waterfall, and hands the result to the backend.
+
+`FEEDBACK_ONLY` invokes that method with the `feedback/record` event's sequence. The append is already committed when `session/event` listeners run, so the replay contains the feedback event and cannot include a later suffix. The existing handoff cursor distinguishes later replays without another pending-record index.
+
+Because on-demand capture reads only the canonical log, it emits no `agent-error` or `shutdown` operational records. Redaction is evaluated at feedback time rather than append time. The [feedback mode decision](../feature/2026-08-05-feedback-gated-session-telemetry.md) owns the public sharing behavior; this note owns its buffer-free realization.
+
+## Alternatives considered
+
+**Retain capture-time redacted records.** This preserves the exact redaction policy and operational records observed when each event occurs, but duplicates the unbounded session prefix. The mode promises feedback-triggered session-log upload, not capture-time policy snapshots or pre-feedback operational telemetry.
+
+**Retain session event references or sequence numbers.** Rejected because the canonical log already supplies both order and identity. A second index saves payload copies but adds lifecycle state without enabling any required behavior.
+
+**Write a durable pre-feedback spool.** Deferred until a deployment requires crash recovery before feedback. It adds storage, cleanup, and confidentiality policy to a mode whose intended behavior is to upload nothing when the process exits before feedback.
+
+## Consequences
+
+A no-feedback session consumes no telemetry-owned memory proportional to its event count; the canonical session log remains the only pre-feedback copy. Feedback handling performs projection, cloning, and redaction synchronously before the backend's non-blocking enqueue, so its cost scales with the unreleased prefix. A redaction-policy change before feedback affects that replay, and a crash before feedback uploads nothing. Later feedback processes only events beyond the handoff cursor.
diff --git a/.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.zh.md b/.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.zh.md
new file mode 100644
index 0000000000..7052e07592
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 无缓冲反馈遥测
+
+Status: implemented
+
+[English](2026-08-06-buffer-free-feedback-telemetry.md) | 中文
+
+## 问题
+
+仅反馈遥测必须只在记录反馈后上传会话日志前缀。若在触发前为每个已投影事件保留一份已深拷贝、已脱敏的记录，就会复制权威会话日志；对于长期运行但从不记录反馈的会话，这份副本会无限增长。
+
+## 决策
+
+遥测协调器提供 `live` 与 `on-demand` 捕获。按需捕获不注册会话、flush 或运维事件监听器，也不保留投影记录。`captureSession(session, throughSeq?)` 从 handoff 游标之后读取权威会话日志，直至可选的序列号边界（含边界），应用固定投影、深拷贝每个已接受事件、运行当前的 `telemetry/record` waterfall（瀑布式事件），并将结果交给后端。
+
+`FEEDBACK_ONLY` 以 `feedback/record` 事件的序列号调用该方法。`session/event` 监听器运行时，追加已经提交，因此回放包含该反馈事件，且无法包含后续后缀。现有 handoff 游标可区分后续回放，无需另一个待处理记录索引。
+
+按需捕获只读取权威日志，因此不会发出 `agent-error` 或 `shutdown` 运维记录。脱敏在反馈时而非追加时求值。[反馈模式决策](../feature/2026-08-05-feedback-gated-session-telemetry.md)规定公开的共享行为；本记录规定其无缓冲实现。
+
+## 考虑过的替代方案
+
+**保留捕获时的已脱敏记录。** 该方案会保留每个事件发生时观察到的确切脱敏策略与运维记录，但也会复制无上限的会话前缀。该模式承诺在反馈触发后上传会话日志，而非保留捕获时策略快照或反馈前运维遥测。
+
+**保留会话事件引用或序列号。** 已否决，因为权威日志已同时提供顺序与身份。第二个索引可以省去载荷副本，但会增加生命周期状态，且无法实现任何必需行为。
+
+**写入持久化的反馈前 spool。** 推迟到有部署要求反馈前的崩溃恢复时再实现。该方案会为一个预期在进程于反馈前退出时不上传任何内容的模式增加存储、清理与保密策略。
+
+## 后果
+
+没有反馈的会话不会消耗随事件数量增长的遥测自有内存；权威会话日志仍是反馈前的唯一副本。反馈处理会在后端非阻塞入队前同步执行投影、深拷贝与脱敏，因此其开销随未释放前缀增长。反馈前的脱敏策略变更会影响该次回放，而反馈前发生崩溃时什么都不上传。后续反馈只处理 handoff 游标之后的事件。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 0c4fb632c1..a4ddedab35 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1189,7 +1189,7 @@ export type TelemetryMode = typeof TELEMETRY_MODES[number]
 
 Depends on: `BatchLogRecordProcessorOptions` (`@opentelemetry/sdk-logs`) · `OTLPExporterNodeConfigBase` (`@opentelemetry/otlp-exporter-base`)
 
-Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:54`](../packages/telemetry/session-telemetry-otel/src/index.ts)
+Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:55`](../packages/telemetry/session-telemetry-otel/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title`
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index d159fa0a53..a416a17d46 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -830,7 +830,7 @@ Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/syst
 
 ### `telemetry/record` — waterfall
 
-Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
 
 ```ts cordis-catalog
 /**
@@ -844,8 +844,9 @@ Transform one outbound record before it reaches the backend. This waterfall is t
  * `next()` replaces everything beneath. Dispatched synchronously on the
  * capture hot path inside the coordinator's containment: a throwing
  * listener withholds that one record (fail-closed) and never reaches the
- * agent loop. Redaction applies to the exported copy only; the canonical
- * session log is never rewritten.
+ * agent loop. Live capture dispatches at append time; on-demand capture
+ * dispatches while reading the canonical log. Redaction applies to the
+ * exported copy only; the canonical session log is never rewritten.
  * @param record - the candidate record, already the coordinator's own deep
  *   copy; listeners return a (possibly new) record and must not mutate it.
  * @mode waterfall
@@ -853,7 +854,7 @@ Transform one outbound record before it reaches the backend. This waterfall is t
 'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
 ```
 
-Source: [`packages/telemetry/session-telemetry/src/index.ts:42`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/telemetry/session-telemetry/src/index.ts:43`](../../packages/telemetry/session-telemetry/src/index.ts)
 
 ## `tools/*`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 4ccc19f305..82000e7f9a 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -45,7 +45,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:131`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
-| `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:42`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - |
+| `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:43`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:156`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
 | `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:138`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
 | `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:113`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`timeout-policy`](../packages/timeout/timeout-policy) |
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index d4061261db..2298c9b4c6 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -1340,7 +1340,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'telemetry/record',
     mode: 'waterfall',
     signature: '\'telemetry/record\'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord',
-    jsDoc: '/**\n * Transform one outbound record before it reaches the backend. This\n * waterfall is the seam\'s redaction extension point. It ships NO rules\n * of its own: the\n * innermost `next()` passes the record through unchanged, and with no\n * listener mounted records reach the backend as captured, so exported\n * data is exactly as clean as the rules a deployment mounts. Listeners\n * stack by transforming `next()`\'s return value; returning without\n * `next()` replaces everything beneath. Dispatched synchronously on the\n * capture hot path inside the coordinator\'s containment: a throwing\n * listener withholds that one record (fail-closed) and never reaches the\n * agent loop. Redaction applies to the exported copy only; the canonical\n * session log is never rewritten.\n * @param record - the candidate record, already the coordinator\'s own deep\n *   copy; listeners return a (possibly new) record and must not mutate it.\n * @mode waterfall\n */',
+    jsDoc: '/**\n * Transform one outbound record before it reaches the backend. This\n * waterfall is the seam\'s redaction extension point. It ships NO rules\n * of its own: the\n * innermost `next()` passes the record through unchanged, and with no\n * listener mounted records reach the backend as captured, so exported\n * data is exactly as clean as the rules a deployment mounts. Listeners\n * stack by transforming `next()`\'s return value; returning without\n * `next()` replaces everything beneath. Dispatched synchronously on the\n * capture hot path inside the coordinator\'s containment: a throwing\n * listener withholds that one record (fail-closed) and never reaches the\n * agent loop. Live capture dispatches at append time; on-demand capture\n * dispatches while reading the canonical log. Redaction applies to the\n * exported copy only; the canonical session log is never rewritten.\n * @param record - the candidate record, already the coordinator\'s own deep\n *   copy; listeners return a (possibly new) record and must not mutate it.\n * @mode waterfall\n */',
     summary: 'Transform one outbound record before it reaches the backend.',
   },
   {
diff --git a/packages/telemetry/session-telemetry-otel/README.i18n.yaml b/packages/telemetry/session-telemetry-otel/README.i18n.yaml
index 6557557b8c..84e2447fd8 100644
--- a/packages/telemetry/session-telemetry-otel/README.i18n.yaml
+++ b/packages/telemetry/session-telemetry-otel/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/telemetry/session-telemetry-otel/README.md
-README.md: fab2461477b2174bded42ed6f05ae55c7c5f697c
-README.zh.md: ab0191188836e03434adbce527d31b62ead848a3
+README.md: 7fc5572614a5bdba312ba97b52606032ef8f5394
+README.zh.md: 3160b67c8225fb87d5e7be2e43453ef40496fba9
diff --git a/packages/telemetry/session-telemetry-otel/README.md b/packages/telemetry/session-telemetry-otel/README.md
index fab2461477..7fc5572614 100644
--- a/packages/telemetry/session-telemetry-otel/README.md
+++ b/packages/telemetry/session-telemetry-otel/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — the only entry a deployment loads. Its `mode` decides whether the seam hands records over immediately, releases them only at recorded feedback, or keeps telemetry local. Uploading modes compose the OTel JS SDK as-is (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP log exporter) and map each handed-over record onto `logger.emit()`, under two instrumentation scopes: ledger records on `@deepseek-ai/dsh-session-telemetry-otel`, operational records on `@deepseek-ai/dsh-session-telemetry-otel/ops`. Resource identity (`service.name`/`service.version`) comes from `dsh-llm`'s `APP_IDENTITY`, the same source the attribution headers use.
+The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — the only entry a deployment loads. Its `mode` decides whether the seam follows session events live, replays the canonical log only at recorded feedback, or keeps telemetry local. Uploading modes compose the OTel JS SDK as-is (`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP log exporter) and map each handed-over record onto `logger.emit()`, under two instrumentation scopes: ledger records on `@deepseek-ai/dsh-session-telemetry-otel`, operational records on `@deepseek-ai/dsh-session-telemetry-otel/ops`. Resource identity (`service.name`/`service.version`) comes from `dsh-llm`'s `APP_IDENTITY`, the same source the attribution headers use.
 
 ## Config
 
@@ -21,14 +21,14 @@ The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — th
 | `mode` | Behavior |
 |---|---|
 | `FULL` | Default. Each projected record, including lifecycle ops records, is handed to the OTel SDK immediately. |
-| `FEEDBACK_ONLY` | Each `feedback/record` releases the redacted, projected session prefix through that event. Later records wait for another feedback event and remain local if none arrives. |
+| `FEEDBACK_ONLY` | Each `feedback/record` replays, projects, and redacts the canonical session-log suffix through that event. Later records wait for another feedback event and remain local if none arrives. |
 | `DISABLED` | No coordinator, provider, processor, or exporter is constructed. No telemetry record leaves the process. A `feedback/record` logs `session telemetry is DISABLED; nothing will be shared and this feedback remains local`; the event remains in the local session log. |
 
 `exporter.url` is required in `FULL` and `FEEDBACK_ONLY`, has no default, and must parse as `http(s)`; it is optional and unused in `DISABLED`. Uploading modes also reject a non-positive-integer `processor.maxExportBatchSize`, which the SDK accepts but then hangs on at shutdown. Everything else is the SDK's option shape, owned and documented by the SDK, and both blocks pass through whole: every `OTLPExporterNodeConfigBase` field (`headers`, `timeoutMillis`, `compression`, `keepAlive`, …) reaches the exporter, and batching, export cadence (`scheduledDelayMillis`), retry, queue bounds, and loss policy under sustained failure are the SDK's documented behavior, tuned through the `processor` passthrough. The backend deliberately implements no `flush()`: the batch processor is the only flusher in the process, which is what makes `shutdown()`'s drain complete.
 
 ## What leaves the machine
 
-In uploading modes, records carry the complete `event.data` as the seam's `telemetry/record` waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (`request/header`), todo text, compaction summaries, hook `stderrSummary`, feedback text, and the session `cwd` (a local path). The seam ships no redaction rules: with no `telemetry/record` listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see [the seam README](../session-telemetry/README.md#the-redact-waterfall)). Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry. `DISABLED` does not construct the SDK pipeline or hand any capture to a backend.
+In uploading modes, records carry the complete `event.data` as the seam's `telemetry/record` waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (`request/header`), todo text, compaction summaries, hook `stderrSummary`, feedback text, and the session `cwd` (a local path). The seam ships no redaction rules: with no `telemetry/record` listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see [the seam README](../session-telemetry/README.md#the-redact-waterfall)). `FULL` runs redaction at append time; `FEEDBACK_ONLY` retains no telemetry copy and runs the currently mounted rules when feedback triggers canonical-log replay. Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry. `DISABLED` does not construct the SDK pipeline or hand any capture to a backend.
 
 ## Field mapping
 
@@ -46,4 +46,4 @@ None; this package neither assembles nor sends a provider request.
 
 - **Upstream experimental tree** — `@opentelemetry/sdk-logs` is still published from the upstream experimental tree; SDK API churn lands here and only here — the seam contract does not move.
 - **No live-collector coverage** — every test exports to a local mock collector; the keyless Loader-composition e2e (`tests/loader-composition.e2e.ts`) covers the wire shape on every run, and behavior against a real OTLP deployment (auth, TLS, throttling) is the SDK exporter's documented territory.
-- **Feedback-only memory** — each session retains deep-copied, redacted projected records in memory until feedback releases them or the session becomes unreachable. There is no durable pre-feedback spool; a crash before feedback uploads nothing.
+- **Feedback-time snapshot** — `FEEDBACK_ONLY` retains no telemetry-owned copy before feedback. It reads and redacts the current canonical log when feedback is recorded; a crash before feedback uploads nothing, and policy changes before feedback affect what that replay exports.
diff --git a/packages/telemetry/session-telemetry-otel/README.zh.md b/packages/telemetry/session-telemetry-otel/README.zh.md
index ab01911888..3160b67c82 100644
--- a/packages/telemetry/session-telemetry-otel/README.zh.md
+++ b/packages/telemetry/session-telemetry-otel/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[遥测（telemetry）seam](../session-telemetry/) 的 OpenTelemetry 后端，也是部署方唯一要加载的条目。其 `mode` 决定 seam 是立即交接记录、仅在记录反馈时释放记录，还是将遥测留在本地。上传模式会原样组合 OTel JS SDK（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP 日志导出器），把每条已交接记录映射到 `logger.emit()`，并使用两个插桩作用域（instrumentation scope）：ledger 记录挂在 `@deepseek-ai/dsh-session-telemetry-otel` 下，运维记录挂在 `@deepseek-ai/dsh-session-telemetry-otel/ops` 下。资源身份（`service.name`/`service.version`）来自 `dsh-llm` 的 `APP_IDENTITY`，与归因标头同源。
+[遥测（telemetry）seam](../session-telemetry/) 的 OpenTelemetry 后端，也是部署方唯一要加载的条目。其 `mode` 决定 seam 是实时跟随会话事件、仅在记录反馈时回放权威日志，还是将遥测留在本地。上传模式会原样组合 OTel JS SDK（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP 日志导出器），把每条已交接记录映射到 `logger.emit()`，并使用两个插桩作用域（instrumentation scope）：ledger 记录挂在 `@deepseek-ai/dsh-session-telemetry-otel` 下，运维记录挂在 `@deepseek-ai/dsh-session-telemetry-otel/ops` 下。资源身份（`service.name`/`service.version`）来自 `dsh-llm` 的 `APP_IDENTITY`，与归因标头同源。
 
 ## 配置
 
@@ -21,14 +21,14 @@
 | `mode` | 行为 |
 |---|---|
 | `FULL` | 默认值。每条已投影记录都立即交给 OTel SDK，包括生命周期运维记录。 |
-| `FEEDBACK_ONLY` | 每个 `feedback/record` 都会释放截至该事件的已脱敏、已投影会话前缀。后续记录等待下一个反馈事件；如果没有后续反馈，则留在本地。 |
+| `FEEDBACK_ONLY` | 每个 `feedback/record` 都会回放权威会话日志中截至该事件的后缀，并进行投影与脱敏。后续记录等待下一个反馈事件；如果没有后续反馈，则留在本地。 |
 | `DISABLED` | 不构造协调器、提供方、处理器或导出器。没有遥测记录会离开进程。`feedback/record` 会记录 `session telemetry is DISABLED; nothing will be shared and this feedback remains local`；该事件留在本地会话日志中。 |
 
 `exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填，无默认值，且必须能解析为 `http(s)`；在 `DISABLED` 中可省略且不使用。上传模式也会拒绝不是正整数的 `processor.maxExportBatchSize`，SDK 虽会接受该值，但随后会在关闭时挂起。其余全部是 SDK 自己的选项形态，由 SDK 拥有并在 SDK 文档中说明，两个配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是 SDK 的文档化行为，经 `processor` 透传调优。该后端刻意不实现 `flush()`：批处理器是进程内唯一执行 flush 的组件，`shutdown()` 的排空正因如此才是完整的。
 
 ## 哪些数据会离开本机
 
-在上传模式中，记录携带完整的 `event.data`，内容以 seam 的 `telemetry/record` waterfall（瀑布式事件）返回的结果为准：用户与 assistant 消息内容、工具参数与工具结果（命令输出、文件内容）、完整的系统提示词与工具 schema（`request/header`）、todo 文本、压缩（compaction）摘要、钩子的 `stderrSummary`、反馈文本，以及会话 `cwd`（一个本地路径）。seam 不带任何脱敏规则：未挂载 `telemetry/record` 监听器时，导出的就是捕获原样的副本，因此向可信边界之外导出的部署方要挂载自己的规则（见 [seam README](../session-telemetry/README.md#the-redact-waterfall)）。无论如何，提供方凭据都不会出现：适配器的 API key 是构造函数参数而非会话事件，因此它们在结构上就不存在于日志中，也就不存在于遥测中。`DISABLED` 不会构造 SDK 流水线，也不会将任何捕获内容交给后端。
+在上传模式中，记录携带完整的 `event.data`，内容以 seam 的 `telemetry/record` waterfall（瀑布式事件）返回的结果为准：用户与 assistant 消息内容、工具参数与工具结果（命令输出、文件内容）、完整的系统提示词与工具 schema（`request/header`）、todo 文本、压缩（compaction）摘要、钩子的 `stderrSummary`、反馈文本，以及会话 `cwd`（一个本地路径）。seam 不带任何脱敏规则：未挂载 `telemetry/record` 监听器时，导出的就是捕获原样的副本，因此向可信边界之外导出的部署方要挂载自己的规则（见 [seam README](../session-telemetry/README.md#the-redact-waterfall)）。`FULL` 在追加时运行脱敏；`FEEDBACK_ONLY` 不保留遥测副本，而是在反馈触发权威日志回放时运行当时挂载的规则。无论如何，提供方凭据都不会出现：适配器的 API key 是构造函数参数而非会话事件，因此它们在结构上就不存在于日志中，也就不存在于遥测中。`DISABLED` 不会构造 SDK 流水线，也不会将任何捕获内容交给后端。
 
 ## 字段映射
 
@@ -46,4 +46,4 @@ seam 记录 → SDK 日志记录：`time` → `timestamp`/`observedTimestamp`；
 
 - **上游实验性源码树**：`@opentelemetry/sdk-logs` 仍从上游实验性（experimental）源码树发布；SDK API 的变动只会落在本包，也仅落在本包；seam 契约不动。
 - **无真实 collector 覆盖**：所有测试都导出到本地 mock collector；无密钥的 Loader 组合 e2e（`tests/loader-composition.e2e.ts`）在每次运行中都覆盖协议格式（wire format）形态，而面对真实 OTLP 部署的行为（认证、TLS、限流）属于 SDK 导出器文档的职责范围。
-- **仅反馈模式的内存占用**：每个会话都会在内存中保留已深拷贝、已脱敏的投影记录，直到反馈将其释放或会话变得不可达。反馈前不存在持久化 spool；如果在反馈前崩溃，则什么都不上传。
+- **反馈时快照**：`FEEDBACK_ONLY` 在反馈前不保留遥测自有副本。记录反馈时，它读取并脱敏当前的权威日志；反馈前发生崩溃时什么都不上传，而反馈前的策略变更会影响该次回放的导出内容。
diff --git a/packages/telemetry/session-telemetry-otel/src/index.ts b/packages/telemetry/session-telemetry-otel/src/index.ts
index cb0ee71fc7..908f0f90fb 100644
--- a/packages/telemetry/session-telemetry-otel/src/index.ts
+++ b/packages/telemetry/session-telemetry-otel/src/index.ts
@@ -7,7 +7,8 @@
  * boundary axiom, everything downstream of that call (batching, retry,
  * queueing, loss policy) is the SDK's documented behavior, configured
  * verbatim through the `exporter`/`processor` passthroughs. This package owns
- * only whether capture is immediate, feedback-released, or disabled.
+ * only whether capture is live, feedback-triggered from the canonical log, or
+ * disabled.
  *
  * @module @deepseek-ai/dsh-session-telemetry-otel
  */
@@ -19,7 +20,7 @@ import type {} from '@deepseek-ai/dsh-command-feedback'
 import {
   Telemetry,
   TelemetryCoordinator,
-  type TelemetryDelivery,
+  type TelemetryCapture,
   type TelemetryRecord,
   type TelemetrySeverity,
 } from '@deepseek-ai/dsh-session-telemetry'
@@ -161,13 +162,13 @@ export class TelemetryOtel extends Telemetry {
     })
     this.ledger = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel', version)
     this.ops = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel/ops', version)
-    const delivery: TelemetryDelivery = mode === 'FULL' ? 'immediate' : 'held'
-    const coordinator = new TelemetryCoordinator(ctx, this, delivery)
+    const capture: TelemetryCapture = mode === 'FULL' ? 'live' : 'on-demand'
+    const coordinator = new TelemetryCoordinator(ctx, this, capture)
     if (mode === 'FEEDBACK_ONLY') {
-      // The coordinator listener is registered first, so a feedback event
-      // enters the held prefix before this listener releases that exact prefix.
+      // Session.append commits before publishing `session/event`, so the
+      // canonical log already includes this feedback record when replay begins.
       ctx.on('session/event', (session, event) => {
-        if (event.type === 'feedback/record') coordinator.release(session)
+        if (event.type === 'feedback/record') coordinator.captureSession(session, event.seq)
       })
     }
   }
@@ -206,8 +207,8 @@ export class TelemetryOtel extends Telemetry {
    * quiesce. With no concurrent `forceFlush()` in the process (see above),
    * shutdown's internal drain is complete — everything handed to the SDK
    * before this call is exported before the exporter closes. In `FULL`, that
-   * includes dispose-time `shutdown` markers; held suffixes never reach the
-   * SDK. Awaited (and error-contained) by the coordinator's disposer. A
+   * includes dispose-time `shutdown` markers; `FEEDBACK_ONLY` creates no ops
+   * records. Awaited (and error-contained) by the coordinator's disposer. A
    * disabled backend resolves immediately.
    * @returns resolves when the SDK pipeline has quiesced.
    */
diff --git a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
index 18c466f7aa..9b7e4119b7 100644
--- a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
+++ b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
@@ -206,7 +206,7 @@ describe('TelemetryOtel wire', () => {
     expect(start?.record.severityNumber).toBe(13)
   })
 
-  it('holds each session suffix until the next feedback event', async () => {
+  it('replays each session suffix only at the next feedback event', async () => {
     const { url, captures } = await mockCollector()
     const ctx = new Context()
     await ctx.plugin(SessionStore)
diff --git a/packages/telemetry/session-telemetry/README.i18n.yaml b/packages/telemetry/session-telemetry/README.i18n.yaml
index da3a62e2fd..ee9c7288b1 100644
--- a/packages/telemetry/session-telemetry/README.i18n.yaml
+++ b/packages/telemetry/session-telemetry/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/telemetry/session-telemetry/README.md
-README.md: d38433a728c699c7fb3cc0512bb6a2d977dd4cc6
-README.zh.md: 3a86b01321fc7dfd33d39530ee7fa38a6ee1f2dc
+README.md: 67d95bcc62bbf6783f8dcd11f0236d8c926b557b
+README.zh.md: 1ee0e0eb14bb06c8ac669cd417f2ee2ce46ca430
diff --git a/packages/telemetry/session-telemetry/README.md b/packages/telemetry/session-telemetry/README.md
index d38433a728..67d95bcc62 100644
--- a/packages/telemetry/session-telemetry/README.md
+++ b/packages/telemetry/session-telemetry/README.md
@@ -2,23 +2,23 @@
 
 English | [中文](README.zh.md)
 
-The telemetry seam: the capture side of session-event reporting, behind a backend contract any reporting SDK satisfies with zero bending. Capture can hand each redacted record over immediately or hold a per-session prefix for an explicit release. The boundary axiom that shapes everything here: **this package's aspect ends at `emit()`** — batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md) and [feedback-gated delivery](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md).
+The telemetry seam: the capture side of session-event reporting, behind a backend contract any reporting SDK satisfies with zero bending. Capture can follow live session events or replay a canonical session-log prefix on demand. The boundary axiom that shapes everything here: **this package's aspect ends at `emit()`** — batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md), [feedback-gated delivery](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md), and [buffer-free feedback replay](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md).
 
 ## The backend contract
 
-`TelemetryBackend` is three members: `emit(record)` (MUST be a non-blocking enqueue — it runs synchronously on the `session/event` hot path, either at capture or held-prefix release), optional `flush()` (a turn-boundary hint, fire-and-forget; most backends leave it unimplemented and let their SDK's batching cadence govern export timing — an implementer owns the interaction between concurrent flushes and `shutdown()`'s drain), and `shutdown()` (the lifecycle forward: drain-and-quiesce, awaited at dispose). `Telemetry` is its service-registered form under the `telemetry` context key — one implementation per context, duplicate load throws. A backend composes `TelemetryCoordinator` with `immediate` delivery or `held` delivery and calls `release(session)` at its owning trigger.
+`TelemetryBackend` is three members: `emit(record)` (MUST be a non-blocking enqueue — it runs synchronously on the `session/event` hot path or during an explicit canonical-log replay), optional `flush()` (a turn-boundary hint, fire-and-forget; most backends leave it unimplemented and let their SDK's batching cadence govern export timing — an implementer owns the interaction between concurrent flushes and `shutdown()`'s drain), and `shutdown()` (the lifecycle forward: drain-and-quiesce, awaited at dispose). `Telemetry` is its service-registered form under the `telemetry` context key — one implementation per context, duplicate load throws. A backend composes `TelemetryCoordinator` with `live` capture or `on-demand` capture and calls `captureSession(session, throughSeq?)` at its owning trigger.
 
 ## Capture points
 
-The coordinator registers, all through the composing fiber's effects: `session/created` (adopt: record the header, read the log back through the projection from the construction boundary — constructor seeds from fork/resume never re-emit on the firehose and never re-export), `session/event` (project, deep-copy, redact, then hand off or hold; zero I/O), `session/flush` (forward the optional `flush()` hint and return void — the loop's awaited parallel must never wait on telemetry), `session/disposed` (capture the session's `shutdown` operational record at its termination edge, then retire it), `agent/error` (the one live-bus relay; the session event vocabulary intentionally has no operational-error record), a dispose effect (capture shutdown for each still-live session, then await the backend's `shutdown()`; failures warn instead of throwing), and an adoption sweep of `ctx.sessions.list()` (a hot reload does not replay `session/created`). Immediate delivery hands lifecycle records over; held delivery leaves any suffix after the last release local, including its later shutdown marker.
+In `live` mode the coordinator registers, all through the composing fiber's effects: `session/created` (adopt: record the header, read the log back through the projection from the construction boundary — constructor seeds from fork/resume never re-emit on the firehose and never re-export), `session/event` (project, deep-copy, redact, then hand off; zero I/O), `session/flush` (forward the optional `flush()` hint and return void — the loop's awaited parallel must never wait on telemetry), `session/disposed` (capture the session's `shutdown` operational record at its termination edge, then retire it), `agent/error` (the one live-bus relay; the session event vocabulary intentionally has no operational-error record), a dispose effect (capture shutdown for each still-live session, then await the backend's `shutdown()`; failures warn instead of throwing), and an adoption sweep of `ctx.sessions.list()` (a hot reload does not replay `session/created`). In `on-demand` mode it registers only the dispose effect: `captureSession()` reads the canonical log through an optional inclusive sequence boundary, while flush hints and operational events remain local.
 
 ## The redact waterfall
 
-Every record passes the `telemetry/record` waterfall immediately after projection — the seam's scrubbing extension point. The seam ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Held delivery stores only the waterfall result, so later policy removal cannot expose the original capture. Redaction applies to the outbound copy only; the canonical session log is never rewritten.
+Every record passes the `telemetry/record` waterfall immediately after projection — the seam's scrubbing extension point. The seam ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Live capture runs the waterfall at append time; on-demand capture runs it while replaying the canonical log, using the rules mounted at that time. Redaction applies to the outbound copy only; the canonical session log is never rewritten.
 
 ## The handoff cursor
 
-A module-scope `WeakMap<Session, seq>` marks the highest seq HANDED OFF (not delivered) per session. Immediate delivery advances it at capture; held delivery advances it only when `release(session)` hands that record to the backend. An unreleased prefix therefore survives a coordinator reload through deterministic re-adoption instead of disappearing with its in-memory copy. On re-adoption the coordinator re-hands only events past the cursor (events at or below it still rebuild the chunk-projection state); a missing cursor safely degrades to a re-hand from the session's construction boundary (`Session.firstLiveSeq` — seq 0 for a session born in this process), absorbed by receiver-side dedupe on `(session.id, event.seq)`. Constructor seeds never re-export: a resumed session's history shipped from the previous process under the same id, and a fork's inherited prefix lives in the parent's stream (receivers stitch on `session.parent_id` + `session.seed_length`). The accepted cost, consistent with at-most-once delivery: a resume does not backfill records a previous process failed to deliver — a deployment with a backfill requirement needs the deferred outbox, not replay. This is a deliberate, narrow exception to the registrations-are-effects discipline: entries die with their sessions, the value is a monotonic watermark, and losing it is never an error.
+A module-scope `WeakMap<Session, seq>` marks the highest seq HANDED OFF (not delivered) per session. Live capture advances it at append time; on-demand capture advances it only while `captureSession()` hands a requested prefix to the backend. An uncaptured prefix remains solely in the canonical log, so a coordinator reload adds no telemetry-owned recovery state. On replay the coordinator re-hands only events past the cursor (events at or below it still rebuild the chunk-projection state); a missing cursor safely degrades to a re-hand from the session's construction boundary (`Session.firstLiveSeq` — seq 0 for a session born in this process), absorbed by receiver-side dedupe on `(session.id, event.seq)`. Constructor seeds never re-export: a resumed session's history shipped from the previous process under the same id, and a fork's inherited prefix lives in the parent's stream (receivers stitch on `session.parent_id` + `session.seed_length`). The accepted cost, consistent with at-most-once delivery: a resume does not backfill records a previous process failed to deliver — a deployment with a backfill requirement needs the deferred outbox, not replay. This is a deliberate, narrow exception to the registrations-are-effects discipline: entries die with their sessions, the value is a monotonic watermark, and losing it is never an error.
 
 ## The fixed chunk projection
 
@@ -40,4 +40,4 @@ None; this package neither assembles nor sends a provider request.
 
 - **Best-effort delivery** — the cursor marks handed-off, not delivered; a session torn down inside a reload window cannot be re-adopted; whatever sits in a backend queue at crash time is lost. A durable outbox (spool, per-sink cursors, at-least-once) is deferred until a deployment states a crash-loss requirement — see [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md).
 - **No built-in redaction rules** — with no `telemetry/record` listener mounted, records leave the process exactly as captured, including any credentials embedded in file contents or command output; a deployment exporting to a shared collector owns its rule set.
-- **Held prefixes duplicate memory** — held delivery retains one deep-copied, redacted record per projected event until release or session collection. It adds no durable outbox and intentionally trades memory for a simple no-upload-before-trigger boundary.
+- **On-demand redaction uses current state** — uncaptured events exist only in the canonical session log. A later `captureSession()` deep-copies and redacts their current values with the policy mounted at that time; there is no capture-time telemetry snapshot or durable pre-capture spool.
diff --git a/packages/telemetry/session-telemetry/README.zh.md b/packages/telemetry/session-telemetry/README.zh.md
index 3a86b01321..1ee0e0eb14 100644
--- a/packages/telemetry/session-telemetry/README.zh.md
+++ b/packages/telemetry/session-telemetry/README.zh.md
@@ -2,23 +2,23 @@
 
 [English](README.md) | 中文
 
-遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端契约之后，任何上报 SDK 都无需变形即可满足该契约。捕获侧可立即交接每条已脱敏记录，也可按会话暂存一个前缀，等待显式释放。塑造本包（package）一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)与[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)。
+遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端契约之后，任何上报 SDK 都无需变形即可满足该契约。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包（package）一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
 
 ## 后端契约
 
-`TelemetryBackend` 只有三个成员：`emit(record)`（必须是非阻塞入队；它会在捕获或暂存前缀释放时，于 `session/event` 热路径上同步执行）、可选的 `flush()`（轮次边界提示，触发后不等待结果；多数后端不实现它，而由其 SDK 的批处理节奏决定导出时机；并发 flush 与 `shutdown()` 的排空之间的交互由实现方自行负责）、以及 `shutdown()`（生命周期转发点：排空并完全停稳，在 dispose（资源释放）时被等待）。`Telemetry` 是它注册在 `telemetry` 上下文键下的服务形态：每个上下文只允许一个实现，重复加载会抛出异常。后端以 `immediate` 或 `held` 投递模式组合 `TelemetryCoordinator`，并在自身所属的触发器中调用 `release(session)`。
+`TelemetryBackend` 只有三个成员：`emit(record)`（必须是非阻塞入队；它在 `session/event` 热路径或显式权威日志回放期间同步执行）、可选的 `flush()`（轮次边界提示，触发后不等待结果；多数后端不实现它，而由其 SDK 的批处理节奏决定导出时机；并发 flush 与 `shutdown()` 的排空之间的交互由实现方自行负责）、以及 `shutdown()`（生命周期转发点：排空并完全停稳，在 dispose（资源释放）时被等待）。`Telemetry` 是它注册在 `telemetry` 上下文键下的服务形态：每个上下文只允许一个实现，重复加载会抛出异常。后端以 `live` 或 `on-demand` 模式组合 `TelemetryCoordinator`，并在自身所属的触发器中调用 `captureSession(session, throughSeq?)`。
 
 ## 捕获点
 
-协调器的全部注册都经由组合方 fiber 的 effect 完成：`session/created`（收养：记录 header，并经投影从构造边界起回读日志；来自 fork 或恢复的构造函数种子绝不会在 firehose 上再次发出，也绝不会再次导出）、`session/event`（投影、深拷贝、脱敏，再交接或暂存；零 I/O）、`session/flush`（转发可选的 `flush()` 提示并返回 void；循环所等待的并行任务绝不能等待遥测）、`session/disposed`（在会话自身的终止边缘捕获该会话的 `shutdown` 运维记录，然后将其退役）、`agent/error`（唯一的实时总线转发；会话事件词汇有意不包含运维错误记录）、一个 dispose effect（捕获每个仍存活会话的 shutdown，再等待后端的 `shutdown()`；失败只发出警告而不抛出），以及对 `ctx.sessions.list()` 的收养扫描（热重载不会重放 `session/created`）。即时投递会交接生命周期记录；暂存投递会将上次释放后的任何后缀留在本地，包括随后的 shutdown 标记。
+在 `live` 模式中，协调器的全部注册都经由组合方 fiber 的 effect 完成：`session/created`（收养：记录 header，并经投影从构造边界起回读日志；来自 fork 或恢复的构造函数种子绝不会在 firehose 上再次发出，也绝不会再次导出）、`session/event`（投影、深拷贝、脱敏，再交接；零 I/O）、`session/flush`（转发可选的 `flush()` 提示并返回 void；循环所等待的并行任务绝不能等待遥测）、`session/disposed`（在会话自身的终止边缘捕获该会话的 `shutdown` 运维记录，然后将其退役）、`agent/error`（唯一的实时总线转发；会话事件词汇有意不包含运维错误记录）、一个 dispose effect（捕获每个仍存活会话的 shutdown，再等待后端的 `shutdown()`；失败只发出警告而不抛出），以及对 `ctx.sessions.list()` 的收养扫描（热重载不会重放 `session/created`）。在 `on-demand` 模式中，协调器只注册 dispose effect：`captureSession()` 读取权威日志，直至可选的序列号边界（含边界）；flush 提示与运维事件留在本地。
 
 ## 脱敏 waterfall（瀑布式事件）
 
-每条记录在投影后立即经过 `telemetry/record` waterfall，这是该 seam 的脱敏扩展点。seam 自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。暂存投递只保留 waterfall 的结果，因此后续移除策略也无法暴露捕获时的原始内容。脱敏只作用于外发副本；权威会话日志永不改写。
+每条记录在投影后立即经过 `telemetry/record` waterfall，这是该 seam 的脱敏扩展点。seam 自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。实时捕获在追加时运行 waterfall；按需捕获则在回放权威日志时使用当时挂载的规则运行 waterfall。脱敏只作用于外发副本；权威会话日志永不改写。
 
 ## handoff 游标
 
-一个模块作用域的 `WeakMap<Session, seq>` 记录每个会话已交接（而非已投递）的最高 seq。即时投递在捕获时推进游标；暂存投递只有在 `release(session)` 将记录交给后端时才推进游标。因此，重建协调器后会通过确定性重新收养恢复未释放的前缀，而不会随其内存副本一同消失。重新收养时，协调器只重新交接游标之后的事件（游标及其之前的事件仍用于重建分片投影状态）；游标缺失时安全退化为从会话构造边界起的重新交接（`Session.firstLiveSeq`，对在本进程中诞生的会话即 seq 0），由接收端基于 `(session.id, event.seq)` 的去重吸收。构造函数种子绝不会再次导出：恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀则位于父会话的流中（接收端基于 `session.parent_id` + `session.seed_length` 拼接）。由此接受的代价与至多一次（at-most-once）投递一致：恢复不会回填上一个进程未能投递的记录；有回填要求的部署需要的是已推迟的 outbox，而不是回放。这是对「注册即 effect」纪律的一次有意且范围极窄的例外：条目随其会话消亡，值是单调水位线，丢失它绝不是错误。
+一个模块作用域的 `WeakMap<Session, seq>` 记录每个会话已交接（而非已投递）的最高 seq。实时捕获在追加时推进游标；按需捕获只有在 `captureSession()` 将请求的前缀交给后端时才推进游标。未捕获的前缀只留在权威日志中，因此协调器重载不会增加遥测自有的恢复状态。回放时，协调器只重新交接游标之后的事件（游标及其之前的事件仍用于重建分片投影状态）；游标缺失时安全退化为从会话构造边界起的重新交接（`Session.firstLiveSeq`，对在本进程中诞生的会话即 seq 0），由接收端基于 `(session.id, event.seq)` 的去重吸收。构造函数种子绝不会再次导出：恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀则位于父会话的流中（接收端基于 `session.parent_id` + `session.seed_length` 拼接）。由此接受的代价与至多一次（at-most-once）投递一致：恢复不会回填上一个进程未能投递的记录；有回填要求的部署需要的是已推迟的 outbox，而不是回放。这是对「注册即 effect」纪律的一次有意且范围极窄的例外：条目随其会话消亡，值是单调水位线，丢失它绝不是错误。
 
 ## 固定分片投影
 
@@ -40,4 +40,4 @@
 
 - **尽力而为的投递**：游标标记的是已交接而非已投递；在重载窗口内被拆除的会话无法重新收养；崩溃时留在后端队列中的内容会丢失。持久化 outbox（spool、每 sink 游标、at-least-once）推迟到有部署方提出明确的崩溃丢失要求时再实现；见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)。
 - **不内置脱敏规则**：未挂载 `telemetry/record` 监听器时，记录以捕获时的原样离开进程，包括文件内容或命令输出中内嵌的任何凭据；向共享 collector 导出的部署方自行负责其规则集。
-- **暂存前缀会重复占用内存**：暂存投递会为每个已投影事件保留一份深拷贝且已脱敏的记录，直到释放或回收会话。它不增加持久化 outbox，而是有意以内存换取简单的「触发前不上传」边界。
+- **按需脱敏使用当前状态**：未捕获的事件只存在于权威会话日志中。后续的 `captureSession()` 会使用当时挂载的策略，深拷贝并脱敏其当前值；不存在捕获时的遥测快照或持久化的捕获前 spool。
diff --git a/packages/telemetry/session-telemetry/src/coordinator.ts b/packages/telemetry/session-telemetry/src/coordinator.ts
index 710e9b81f9..9e32ae0693 100644
--- a/packages/telemetry/session-telemetry/src/coordinator.ts
+++ b/packages/telemetry/session-telemetry/src/coordinator.ts
@@ -1,13 +1,15 @@
 /**
- * Capture coordinator: the seam's upstream half. Subscribes to the session
- * firehose plus the one live-bus relay (`agent/error`), applies the fixed
- * chunk projection, builds logical records, runs each through the
+ * Capture coordinator: the seam's upstream half. Live capture subscribes to
+ * the session firehose plus the one live-bus relay (`agent/error`). Both
+ * capture paths apply the fixed chunk projection, build logical records, and
+ * run each through the
  * `telemetry/record` waterfall (deployment-mounted redaction rules;
- * pass-through when none), then hands the result to the backend immediately
- * or holds it for explicit release. Every synchronous handler is
- * self-contained so a failing backend can never starve other subscribers
- * (cordis `emit` is stop-on-throw) or touch the agent loop. Composed by a
- * backend in its constructor.
+ * pass-through when none), then hands the result to the backend. Live capture
+ * follows the session firehose; on-demand capture replays the canonical log
+ * only when requested. Every synchronous handler is self-contained so a
+ * failing backend can never starve other subscribers (cordis `emit` is
+ * stop-on-throw) or touch the agent loop. Composed by a backend in its
+ * constructor.
  *
  * @module @deepseek-ai/dsh-session-telemetry/coordinator
  */
@@ -17,11 +19,11 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { TelemetryBackend, TelemetryRecord, TelemetrySeverity } from './index.ts'
 
-/** Whether capture hands records over immediately or holds them for an explicit release. */
-export type TelemetryDelivery = 'immediate' | 'held'
+/** Whether capture follows live events or reads the canonical log only when requested. */
+export type TelemetryCapture = 'live' | 'on-demand'
 
-/** One redacted record waiting at the capture boundary. */
-interface PendingRecord {
+/** One projected record ready for backend handoff. */
+interface ProjectedRecord {
   readonly record: TelemetryRecord
   /** Ledger cursor advanced only after the backend accepts this record. */
   readonly seq?: number
@@ -43,16 +45,17 @@ const handoffCursor = new WeakMap<Session, number>()
 /**
  * Install the telemetry capture side onto a context for one backend.
  *
- * Registers the persistence-coordinator listener set plus the `agent/error`
- * relay, all through `ctx.effect()`/`ctx.on()` on the composing fiber, and
- * sweeps already-live sessions (a hot reload does not replay
+ * Live capture registers the persistence-coordinator listener set plus the
+ * `agent/error` relay, all through `ctx.effect()`/`ctx.on()` on the composing
+ * fiber, and sweeps already-live sessions (a hot reload does not replay
  * `session/created`). A `session/disposed` captures the session's `shutdown`
  * operational record at its own termination edge and retires it from the
- * adopted set. Immediate delivery hands that marker over; held delivery keeps
- * it local without another explicit release. Disposal captures the same
- * marker for sessions still alive, then awaits the backend's `shutdown()`; a
- * failure there warns instead of throwing — best-effort reporting must not
- * fail application teardown.
+ * adopted set. On-demand capture registers none of those continuous listeners;
+ * {@link captureSession} reads the canonical log explicitly and never creates
+ * operational records. Disposal captures shutdown markers for live-adopted
+ * sessions, then awaits the backend's `shutdown()`; a failure there warns
+ * instead of throwing — best-effort reporting must not fail application
+ * teardown.
  */
 export class TelemetryCoordinator {
   /**
@@ -63,56 +66,55 @@ export class TelemetryCoordinator {
   private readonly adopted = new Set<Session>()
   /** Per session, the `turn:step` keys whose first chunk already shipped; rebuilt from the log on re-adoption. */
   private readonly chunkSeen = new WeakMap<Session, Set<string>>()
-  /** Redacted records retained until {@link release}; weak keys do not extend session lifetime. */
-  private readonly held = new WeakMap<Session, PendingRecord[]>()
-
   /**
    * @param ctx - the composing backend's context; listeners bind to its fiber.
    * @param backend - the backend receiving records; owned elsewhere, never disposed here beyond `shutdown()` forwarding.
-   * @param delivery - immediate handoff, or held delivery released explicitly per session.
+   * @param capture - follow live events, or wait for explicit canonical-log capture.
    */
   constructor(
     private readonly ctx: Context,
     private readonly backend: TelemetryBackend,
-    private readonly delivery: TelemetryDelivery = 'immediate',
+    capture: TelemetryCapture = 'live',
   ) {
-    ctx.on('session/created', (session) => {
-      this.adopt(session)
-    })
-    // Capture the shutdown marker at the session's own termination edge.
-    // Immediate delivery preserves crash classification; held delivery does
-    // not let a later lifecycle edge extend a user-released prefix. Then
-    // retire the only strong reference owned by this coordinator.
-    ctx.on('session/disposed', (session) => {
-      this.contain(() => {
-        if (!this.adopted.delete(session)) return
-        this.submit(session, { record: this.redact(shutdownRecord(session)) })
+    if (capture === 'live') {
+      ctx.on('session/created', (session) => {
+        this.adopt(session)
       })
-    })
-    ctx.on('session/event', (session, event) => {
-      this.contain(() => {
-        this.capture(session, event)
+      // Capture the shutdown marker at the session's own termination edge,
+      // then retire the only strong reference owned by this coordinator.
+      ctx.on('session/disposed', (session) => {
+        this.contain(() => {
+          if (!this.adopted.delete(session)) return
+          this.deliver(session, { record: this.redact(shutdownRecord(session)) })
+        })
       })
-    })
-    // Parallel listeners are awaited by the loop at turn end; returning void
-    // (not the SDK's flush promise) is the turn-latency contract.
-    ctx.on('session/flush', (session) => {
-      this.contain(() => {
-        this.hintFlush(session)
+      ctx.on('session/event', (session, event) => {
+        this.contain(() => {
+          this.captureEvent(session, event)
+        })
       })
-    })
-    ctx.on('agent/error', (agent, turn, step, error) => {
-      this.contain(() => {
-        this.relayAgentError(agent, turn, step, error)
+      // Parallel listeners are awaited by the loop at turn end; returning void
+      // (not the SDK's flush promise) is the turn-latency contract.
+      ctx.on('session/flush', (session) => {
+        this.contain(() => {
+          this.hintFlush(session)
+        })
       })
-    })
+      ctx.on('agent/error', (agent, turn, step, error) => {
+        this.contain(() => {
+          this.relayAgentError(agent, turn, step, error)
+        })
+      })
+      for (const session of ctx.sessions.list()) {
+        this.adopt(session)
+      }
+    }
     ctx.effect(() => async () => {
       // Sessions still adopted here are alive through whole-application
-      // teardown, so capture the marker before the backend quiesces. Held
-      // delivery intentionally leaves it local without another release.
+      // teardown, so capture the marker before the backend quiesces.
       for (const session of this.adopted) {
         this.contain(() => {
-          this.submit(session, { record: this.redact(shutdownRecord(session)) })
+          this.deliver(session, { record: this.redact(shutdownRecord(session)) })
         })
       }
       try {
@@ -121,24 +123,27 @@ export class TelemetryCoordinator {
         this.ctx.logger.warn(`telemetry: backend shutdown failed: ${String(error)}`)
       }
     }, 'telemetry capture')
-    for (const session of ctx.sessions.list()) {
-      this.adopt(session)
-    }
   }
 
   /**
-   * Hand the records currently held for one session to the backend in capture order.
-   * Records captured after this call form a new held prefix. Backend failures remain
-   * contained per record and do not starve later records in the same release.
-   * @param session - session whose pending capture prefix may leave the process.
+   * Project and hand over the canonical session-log suffix after the handoff
+   * cursor, optionally stopping at an inclusive sequence boundary. Redaction
+   * runs during this call, so an on-demand caller retains no copied records
+   * before requesting capture and uses the policy mounted at that time.
+   * Backend and policy failures remain contained per event and do not starve
+   * later events in the same replay.
+   * @param session - session whose current canonical-log prefix may be handed over.
+   * @param throughSeq - optional last sequence included in this capture.
    */
-  release(session: Session): void {
-    const pending = this.held.get(session)
-    if (pending === undefined) return
-    this.held.delete(session)
-    for (const record of pending) {
+  captureSession(session: Session, throughSeq?: number): void {
+    const cursor = handoffCursor.get(session) ?? session.firstLiveSeq - 1
+    // Containment is PER EVENT: one rejected record is withheld fail-closed
+    // while the rest of the historical replay proceeds.
+    for (const event of session.events) {
+      if (throughSeq !== undefined && event.seq > throughSeq) break
       this.contain(() => {
-        this.deliver(session, record)
+        if (event.seq <= cursor) this.track(session, event)
+        else this.captureEvent(session, event)
       })
     }
   }
@@ -161,17 +166,7 @@ export class TelemetryCoordinator {
   private adopt(session: Session): void {
     if (this.adopted.has(session)) return
     this.adopted.add(session)
-    const cursor = handoffCursor.get(session) ?? session.firstLiveSeq - 1
-    // Containment is PER EVENT, matching the firehose: one rejected record
-    // is withheld fail-closed while the rest of the historical replay
-    // proceeds — wrapping the whole loop would let a single failure silently
-    // skip the remainder of the log on an already-adopted session.
-    for (const event of session.events) {
-      this.contain(() => {
-        if (event.seq <= cursor) this.track(session, event)
-        else this.capture(session, event)
-      })
-    }
+    this.captureSession(session)
   }
 
   /** Feed the chunk projection without handing off — the ≤cursor half of re-adoption. */
@@ -181,8 +176,8 @@ export class TelemetryCoordinator {
     }
   }
 
-  /** Project and redact one event, then submit it under the delivery policy. */
-  private capture(session: Session, event: SessionEvent): void {
+  /** Project, redact, and hand one event to the backend. */
+  private captureEvent(session: Session, event: SessionEvent): void {
     if (event.type === 'assistant/chunk') {
       const key = `${event.data.turn}:${event.data.step}`
       const seen = this.seen(session)
@@ -193,14 +188,14 @@ export class TelemetryCoordinator {
       if (seen.has(key)) return
       seen.add(key)
     }
-    this.submit(session, {
+    this.deliver(session, {
       record: this.redact({
         channel: 'ledger',
         time: event.time,
         severity: severityOf(event),
         attributes: identityOf(session, event),
-        // The live event object is mutable and the backend serializes later;
-        // append-time validation guarantees this clone cannot throw.
+        // The canonical event object is mutable and the backend serializes
+        // later; append-time validation guarantees this clone cannot throw.
         body: structuredClone(event.data),
       }),
       seq: event.seq,
@@ -212,26 +207,15 @@ export class TelemetryCoordinator {
    * passes the record through unchanged — the seam ships no rules; exported
    * data is as clean as the listeners a deployment mounts. Callers run inside
    * {@link contain}, so a throwing rule withholds the record instead of
-   * reaching the loop (fail-closed). Held delivery stores only this result, so
-   * a later policy reload cannot expose the pre-redaction capture.
+   * reaching the loop (fail-closed). On-demand capture invokes this waterfall
+   * while reading the canonical session log, not when the event was appended.
    */
   private redact(record: TelemetryRecord): TelemetryRecord {
     return this.ctx.waterfall('telemetry/record', record, () => record)
   }
 
-  /** Hold one redacted record or deliver it immediately under the configured policy. */
-  private submit(session: Session, pending: PendingRecord): void {
-    if (this.delivery === 'held') {
-      let records = this.held.get(session)
-      if (records === undefined) this.held.set(session, records = [])
-      records.push(pending)
-      return
-    }
-    this.deliver(session, pending)
-  }
-
   /** Hand one redacted record to the backend, then advance its ledger cursor. */
-  private deliver(session: Session, pending: PendingRecord): void {
+  private deliver(session: Session, pending: ProjectedRecord): void {
     this.backend.emit(pending.record)
     if (pending.seq !== undefined) handoffCursor.set(session, pending.seq)
   }
@@ -244,7 +228,7 @@ export class TelemetryCoordinator {
   /** Relay one `agent/error` bus emission as an `agent-error` operational record. */
   private relayAgentError(agent: Agent, turn: number, step: number, error: unknown): void {
     const detail = errorDetail(error)
-    this.submit(agent.session, {
+    this.deliver(agent.session, {
       record: this.redact({
         channel: 'ops',
         time: Date.now(),
diff --git a/packages/telemetry/session-telemetry/src/index.ts b/packages/telemetry/session-telemetry/src/index.ts
index 914ef96a95..0198df3140 100644
--- a/packages/telemetry/session-telemetry/src/index.ts
+++ b/packages/telemetry/session-telemetry/src/index.ts
@@ -4,9 +4,9 @@
  * The seam owns the CAPTURE side of session-event reporting — which records
  * exist (the chunk projection), what they carry (the logical record), when
  * they are captured (adoption, the per-append firehose, lifecycle
- * forwarding), immediate versus explicitly released handoff, and the HMR
+ * forwarding), live versus on-demand canonical-log capture, and the HMR
  * cursor. Everything downstream of
- * {@link Telemetry.emit} — batching, retry, queueing, loss policy — is the
+ * {@link Telemetry.emit} — batching, retry, queueing, and loss policy — is the
  * reporting SDK's territory and is deliberately not modelled here. The
  * design and its trade-offs are pinned in
  * .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md.
@@ -33,8 +33,9 @@ declare module 'cordis' {
      * `next()` replaces everything beneath. Dispatched synchronously on the
      * capture hot path inside the coordinator's containment: a throwing
      * listener withholds that one record (fail-closed) and never reaches the
-     * agent loop. Redaction applies to the exported copy only; the canonical
-     * session log is never rewritten.
+     * agent loop. Live capture dispatches at append time; on-demand capture
+     * dispatches while reading the canonical log. Redaction applies to the
+     * exported copy only; the canonical session log is never rewritten.
      * @param record - the candidate record, already the coordinator's own deep
      *   copy; listeners return a (possibly new) record and must not mutate it.
      * @mode waterfall
@@ -95,8 +96,8 @@ export interface TelemetryBackend {
   /**
    * Hand one record to the backend's pipeline. MUST be a non-blocking
    * enqueue — the coordinator calls this synchronously from the
-   * `session/event` hot path, either at capture or while releasing a held
-   * prefix, so anything slower than a queue push would tax the agent loop.
+   * `session/event` hot path or an explicit canonical-log capture, so anything
+   * slower than a queue push would tax the agent loop or feedback handling.
    * Errors thrown here are contained by the coordinator and logged; they
    * never reach the loop.
    * @param record - the logical record to report; owned by the backend after the call.
@@ -123,9 +124,8 @@ export interface TelemetryBackend {
    * coordinator emits its dispose-time `shutdown` markers immediately before
    * calling this). Awaited by the coordinator's dispose; a rejection is
    * logged as a warning and never fails application teardown.
-   * The coordinator captures dispose-time shutdown markers immediately
-   * before this call; immediate delivery enqueues them, while held delivery
-   * leaves an unreleased suffix local.
+   * The coordinator captures dispose-time shutdown markers immediately before
+   * this call for live capture; on-demand capture creates no ops records.
    * @returns resolves when the backend's pipeline has quiesced.
    */
   shutdown(): Promise<void>
@@ -158,4 +158,4 @@ export abstract class Telemetry extends Service implements TelemetryBackend {
   abstract shutdown(): Promise<void>
 }
 
-export { TelemetryCoordinator, type TelemetryDelivery } from './coordinator.ts'
+export { TelemetryCoordinator, type TelemetryCapture } from './coordinator.ts'
diff --git a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts b/packages/telemetry/session-telemetry/tests/telemetry.spec.ts
index d913e6a742..f368e80979 100644
--- a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts
+++ b/packages/telemetry/session-telemetry/tests/telemetry.spec.ts
@@ -13,7 +13,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import {
   TelemetryCoordinator,
   type TelemetryBackend,
-  type TelemetryDelivery,
+  type TelemetryCapture,
   type TelemetryRecord,
 } from '../src/index.ts'
 
@@ -61,7 +61,7 @@ class FakeBackend implements TelemetryBackend {
 
 async function setup(
   backend: FakeBackend = new FakeBackend(),
-  delivery: TelemetryDelivery = 'immediate',
+  capture: TelemetryCapture = 'live',
 ) {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
@@ -70,7 +70,7 @@ async function setup(
     name: 'fake-telemetry',
     inject: ['sessions'],
     apply: (inner: Context) => {
-      coordinator = new TelemetryCoordinator(inner, backend, delivery)
+      coordinator = new TelemetryCoordinator(inner, backend, capture)
     },
   })
   return { ctx, backend, coordinator, fiber }
@@ -178,23 +178,24 @@ describe('TelemetryCoordinator capture', () => {
   })
 })
 
-describe('TelemetryCoordinator held delivery', () => {
-  it('releases one pending prefix at a time without handing later records over early', async () => {
-    const { ctx, backend, coordinator } = await setup(new FakeBackend(), 'held')
-    const session = liveSession(ctx, 'held-prefix')
+describe('TelemetryCoordinator on-demand capture', () => {
+  it('captures one canonical-log prefix at a time without following later events', async () => {
+    const { ctx, backend, coordinator } = await setup(new FakeBackend(), 'on-demand')
+    const session = liveSession(ctx, 'on-demand-prefix')
     appendTurn(session)
+    const firstBoundary = session.events[1]!.seq
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
     expect(backend.records).toEqual([])
 
-    coordinator.release(session)
+    coordinator.captureSession(session, firstBoundary)
     expect(backend.ledger().map(record => record.attributes['event.type'])).toEqual([
       'turn/start',
       'user/message',
     ])
 
-    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
     expect(backend.ledger()).toHaveLength(2)
-    coordinator.release(session)
-    coordinator.release(session)
+    coordinator.captureSession(session)
+    coordinator.captureSession(session)
     expect(backend.ledger().map(record => record.attributes['event.type'])).toEqual([
       'turn/start',
       'user/message',
@@ -202,38 +203,42 @@ describe('TelemetryCoordinator held delivery', () => {
     ])
   })
 
-  it('stores the capture-time redacted copy rather than re-running policy at release', async () => {
-    const { ctx, backend, coordinator } = await setup(new FakeBackend(), 'held')
+  it('runs the currently mounted redaction policy during canonical-log capture', async () => {
+    const { ctx, backend, coordinator } = await setup(new FakeBackend(), 'on-demand')
+    const session = liveSession(ctx, 'on-demand-redacted')
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     const disposeRule = ctx.on('telemetry/record', (_record, next) => ({
       ...next(),
       body: { scrubbed: true },
     }))
-    const session = liveSession(ctx, 'held-redacted')
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+
+    coordinator.captureSession(session)
+    expect(backend.ledger()[0]!.body).toEqual({ scrubbed: true })
     disposeRule()
 
-    coordinator.release(session)
-    expect(backend.ledger()[0]!.body).toEqual({ scrubbed: true })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    coordinator.captureSession(session)
+    expect(backend.ledger()[1]!.body).toEqual({ turn: 1, reason: { kind: 'completed' } })
   })
 
-  it('contains each backend failure independently while releasing a batch', async () => {
+  it('contains each backend failure independently while replaying a prefix', async () => {
     const backend = new FakeBackend()
     backend.rejectSeq = 1
-    const { ctx, coordinator } = await setup(backend, 'held')
+    const { ctx, coordinator } = await setup(backend, 'on-demand')
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
-    const session = liveSession(ctx, 'held-failure')
+    const session = liveSession(ctx, 'on-demand-failure')
     appendTurn(session)
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
 
-    coordinator.release(session)
+    coordinator.captureSession(session)
     expect(backend.ledger().map(record => record.attributes['event.seq'])).toEqual([0, 2])
     expect(warn).toHaveBeenCalled()
   })
 
-  it('rebuilds an unreleased prefix after coordinator reload', async () => {
+  it('captures a pending prefix after coordinator reload without retained records', async () => {
     const first = new FakeBackend()
-    const { ctx, fiber } = await setup(first, 'held')
-    const session = liveSession(ctx, 'held-reload')
+    const { ctx, fiber } = await setup(first, 'on-demand')
+    const session = liveSession(ctx, 'on-demand-reload')
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     await fiber.dispose()
     expect(first.records).toEqual([])
@@ -241,15 +246,34 @@ describe('TelemetryCoordinator held delivery', () => {
     const second = new FakeBackend()
     let coordinator!: TelemetryCoordinator
     await ctx.plugin({
-      name: 'fake-telemetry-after-held-reload',
+      name: 'fake-telemetry-after-on-demand-reload',
       inject: ['sessions'],
       apply: (inner: Context) => {
-        coordinator = new TelemetryCoordinator(inner, second, 'held')
+        coordinator = new TelemetryCoordinator(inner, second, 'on-demand')
       },
     })
-    coordinator.release(session)
+    coordinator.captureSession(session)
     expect(second.ledger().map(record => record.attributes['event.seq'])).toEqual([0])
   })
+
+  it('registers no continuous capture, flush, or ops listeners', async () => {
+    const { ctx, backend, coordinator, fiber } = await setup(new FakeBackend(), 'on-demand')
+    const redact = vi.fn((_record: TelemetryRecord, next: () => TelemetryRecord) => next())
+    ctx.on('telemetry/record', redact)
+    const session = liveSession(ctx, 'on-demand-ledger-only')
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    await ctx.parallel('session/flush', session)
+    const agent = { id: 'agent-1', session } as Agent
+    ctx.emit('agent/error', agent, 1, 1, new Error('local only'))
+    expect(backend.flush).not.toHaveBeenCalled()
+    expect(backend.records).toEqual([])
+    expect(redact).not.toHaveBeenCalled()
+
+    coordinator.captureSession(session)
+    expect(redact).toHaveBeenCalledTimes(1)
+    await fiber.dispose()
+    expect(backend.records.map(record => record.channel)).toEqual(['ledger'])
+  })
 })
 
 describe('TelemetryCoordinator adoption', () => {

From c6f8055388feda7b5298e5d03fb9b9f46fa778cf Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Thu, 6 Aug 2026 15:03:52 +0800
Subject: [PATCH 049/516] docs(telemetry): update capture vocabulary

---
 packages/telemetry/README.i18n.yaml | 4 ++--
 packages/telemetry/README.md        | 2 +-
 packages/telemetry/README.zh.md     | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/telemetry/README.i18n.yaml b/packages/telemetry/README.i18n.yaml
index cd3be8d155..fba4bd4339 100644
--- a/packages/telemetry/README.i18n.yaml
+++ b/packages/telemetry/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/telemetry/README.md
-README.md: 0adf140a19bd6ab19c4d4139d4ebdae941c0d1b0
-README.zh.md: 57988732e36d105ebcc48adcdab9344a6cccb525
+README.md: ddac6c6cdc5a7326190283fbe232b6985deb4927
+README.zh.md: 6863ca56d4f63fccb60eb3c92acd1e70b25e27dd
diff --git a/packages/telemetry/README.md b/packages/telemetry/README.md
index 0adf140a19..ddac6c6cdc 100644
--- a/packages/telemetry/README.md
+++ b/packages/telemetry/README.md
@@ -6,5 +6,5 @@ Outbound session reporting: the telemetry seam plus its OpenTelemetry backend. T
 
 | Package | Role |
 |---|---|
-| [`@deepseek-ai/dsh-session-telemetry`](session-telemetry/) | The seam: capture points, projection, redaction, immediate or held handoff, cursor, ops signals, and the minimal backend contract (`emit`/`flush?`/`shutdown`). |
+| [`@deepseek-ai/dsh-session-telemetry`](session-telemetry/) | The seam: capture points, projection, redaction, live or on-demand capture, cursor, ops signals, and the minimal backend contract (`emit`/`flush?`/`shutdown`). |
 | [`@deepseek-ai/dsh-session-telemetry-otel`](session-telemetry-otel/) | The backend a deployment loads: `FULL`, `FEEDBACK_ONLY`, or `DISABLED` policy around the OTel JS SDK log pipeline. |
diff --git a/packages/telemetry/README.zh.md b/packages/telemetry/README.zh.md
index 57988732e3..6863ca56d4 100644
--- a/packages/telemetry/README.zh.md
+++ b/packages/telemetry/README.zh.md
@@ -6,5 +6,5 @@
 
 | 包（package） | 职责 |
 |---|---|
-| [`@deepseek-ai/dsh-session-telemetry`](session-telemetry/) | seam 本体：捕获点、投影、脱敏、即时或暂存交接、游标、运维信号，以及最小后端契约（`emit`/`flush?`/`shutdown`）。 |
+| [`@deepseek-ai/dsh-session-telemetry`](session-telemetry/) | seam 本体：捕获点、投影、脱敏、实时或按需捕获、游标、运维信号，以及最小后端契约（`emit`/`flush?`/`shutdown`）。 |
 | [`@deepseek-ai/dsh-session-telemetry-otel`](session-telemetry-otel/) | 部署方要加载的后端：围绕 OTel JS SDK 日志流水线实施 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 策略。 |

From b10368a8d53d8cafb1ee991c4b1b9519b8271403 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Thu, 6 Aug 2026 15:34:36 +0800
Subject: [PATCH 050/516] refactor(telemetry): strongly type sharing mode

---
 ...feedback-gated-session-telemetry.i18n.yaml |  4 +--
 ...-08-05-feedback-gated-session-telemetry.md |  2 +-
 ...-05-feedback-gated-session-telemetry.zh.md |  2 +-
 docs/config-catalog.md                        |  8 ++++--
 .../tests/gen-config-catalog.spec.ts          | 23 ++++++++++++++++
 .../session-telemetry-otel/README.i18n.yaml   |  4 +--
 .../session-telemetry-otel/README.md          |  2 ++
 .../session-telemetry-otel/README.zh.md       |  2 ++
 .../session-telemetry-otel/src/index.ts       | 26 ++++++++++++-------
 .../session-telemetry-otel/tests/otel.spec.ts | 18 ++++++++-----
 scripts/gen-config-catalog.ts                 |  9 ++++---
 11 files changed, 73 insertions(+), 27 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
index 7909316acd..331b2e97c6 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.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 .agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
-2026-08-05-feedback-gated-session-telemetry.md: 25cc17f75629f72d7351eb0537d72b700c84411f
-2026-08-05-feedback-gated-session-telemetry.zh.md: b0e84e60e27fa20f66113c11db62026583a27a19
+2026-08-05-feedback-gated-session-telemetry.md: 00a8f23fa6bf69f10277ad0d9f2513a0df73de16
+2026-08-05-feedback-gated-session-telemetry.zh.md: 888ce48abe7a5ce2212c152730f8203f5747ef41
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
index 25cc17f756..00a8f23fa6 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
@@ -10,7 +10,7 @@ Session telemetry originally has one mounted behavior: every accepted record ent
 
 ## Decision
 
-`@deepseek-ai/dsh-session-telemetry-otel` exposes three uppercase `mode` values:
+`@deepseek-ai/dsh-session-telemetry-otel` exposes the string-valued `TelemetryMode` enum to TypeScript callers and accepts the same three uppercase `mode` values in serialized configuration:
 
 - `FULL` is the default and preserves immediate delivery to the configured OTel pipeline.
 - `FEEDBACK_ONLY` reads the canonical session log when `feedback/record` is appended and hands over the unreleased prefix through that exact event. Records appended after that boundary remain local until another feedback event.
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
index b0e84e60e2..888ce48abe 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-`@deepseek-ai/dsh-session-telemetry-otel` 公开三个大写的 `mode` 值：
+`@deepseek-ai/dsh-session-telemetry-otel` 向 TypeScript 调用方公开以字符串为值的 `TelemetryMode` 枚举，并在序列化配置中接受相同的三个大写 `mode` 值：
 
 - `FULL` 是默认值，保留向已配置 OTel 流水线的即时投递。
 - `FEEDBACK_ONLY` 在追加 `feedback/record` 时读取权威会话日志，并交接截至该事件的未释放前缀。该边界后追加的记录会留在本地，直到另一个反馈事件。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a4ddedab35..a2f82d2bec 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1184,12 +1184,16 @@ export interface Config {
 }
 
 /** Session-sharing policy selected by {@link Config.mode}. */
-export type TelemetryMode = typeof TELEMETRY_MODES[number]
+export enum TelemetryMode {
+  FULL = 'FULL',
+  FEEDBACK_ONLY = 'FEEDBACK_ONLY',
+  DISABLED = 'DISABLED',
+}
 ```
 
 Depends on: `BatchLogRecordProcessorOptions` (`@opentelemetry/sdk-logs`) · `OTLPExporterNodeConfigBase` (`@opentelemetry/otlp-exporter-base`)
 
-Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:55`](../packages/telemetry/session-telemetry-otel/src/index.ts)
+Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:63`](../packages/telemetry/session-telemetry-otel/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title`
 
diff --git a/packages/examples/agent-spine-demo/tests/gen-config-catalog.spec.ts b/packages/examples/agent-spine-demo/tests/gen-config-catalog.spec.ts
index 65a6f6b9ff..ae4966fd12 100644
--- a/packages/examples/agent-spine-demo/tests/gen-config-catalog.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/gen-config-catalog.spec.ts
@@ -160,6 +160,29 @@ export function apply(ctx: Context, config: Config): void {}
     expect(entries[0]?.refs).toEqual([{ alias: 'Remote', imported: 'Remote', specifier: '@fix/dep' }])
   })
 
+  it('pastes an enum referenced by the config type', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+/** Fixture mode. */
+export enum Mode {
+  A = 'a',
+  B = 'b',
+}
+/** Fixture config. */
+export interface Config {
+  /** The mode. */
+  mode?: Mode
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))
+    expect(entries[0]?.pastes?.map(p => p.text)).toEqual([
+      '/** Fixture config. */\nexport interface Config {\n  /** The mode. */\n  mode?: Mode\n}',
+      "/** Fixture mode. */\nexport enum Mode {\n  A = 'a',\n  B = 'b',\n}",
+    ])
+  })
+
   it('hard-errors on a referenced type name that resolves nowhere', () => {
     expect(() => collectConfigCatalog(make({
       'src/index.ts': `import type { Context } from 'cordis'
diff --git a/packages/telemetry/session-telemetry-otel/README.i18n.yaml b/packages/telemetry/session-telemetry-otel/README.i18n.yaml
index 84e2447fd8..5a6bd9bc9d 100644
--- a/packages/telemetry/session-telemetry-otel/README.i18n.yaml
+++ b/packages/telemetry/session-telemetry-otel/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/telemetry/session-telemetry-otel/README.md
-README.md: 7fc5572614a5bdba312ba97b52606032ef8f5394
-README.zh.md: 3160b67c8225fb87d5e7be2e43453ef40496fba9
+README.md: 01d803236329afbe65e2d92960928441aaff301c
+README.zh.md: 8adf4a3c11b95dc302f8afd0dc79e99433e50f22
diff --git a/packages/telemetry/session-telemetry-otel/README.md b/packages/telemetry/session-telemetry-otel/README.md
index 7fc5572614..01d8032363 100644
--- a/packages/telemetry/session-telemetry-otel/README.md
+++ b/packages/telemetry/session-telemetry-otel/README.md
@@ -24,6 +24,8 @@ The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — th
 | `FEEDBACK_ONLY` | Each `feedback/record` replays, projects, and redacts the canonical session-log suffix through that event. Later records wait for another feedback event and remain local if none arrives. |
 | `DISABLED` | No coordinator, provider, processor, or exporter is constructed. No telemetry record leaves the process. A `feedback/record` logs `session telemetry is DISABLED; nothing will be shared and this feedback remains local`; the event remains in the local session log. |
 
+Programmatic TypeScript configuration uses the exported `TelemetryMode` enum (`TelemetryMode.FULL`, `TelemetryMode.FEEDBACK_ONLY`, or `TelemetryMode.DISABLED`); raw string literals are not assignable. Serialized Cordis configuration continues to use the string values shown above.
+
 `exporter.url` is required in `FULL` and `FEEDBACK_ONLY`, has no default, and must parse as `http(s)`; it is optional and unused in `DISABLED`. Uploading modes also reject a non-positive-integer `processor.maxExportBatchSize`, which the SDK accepts but then hangs on at shutdown. Everything else is the SDK's option shape, owned and documented by the SDK, and both blocks pass through whole: every `OTLPExporterNodeConfigBase` field (`headers`, `timeoutMillis`, `compression`, `keepAlive`, …) reaches the exporter, and batching, export cadence (`scheduledDelayMillis`), retry, queue bounds, and loss policy under sustained failure are the SDK's documented behavior, tuned through the `processor` passthrough. The backend deliberately implements no `flush()`: the batch processor is the only flusher in the process, which is what makes `shutdown()`'s drain complete.
 
 ## What leaves the machine
diff --git a/packages/telemetry/session-telemetry-otel/README.zh.md b/packages/telemetry/session-telemetry-otel/README.zh.md
index 3160b67c82..8adf4a3c11 100644
--- a/packages/telemetry/session-telemetry-otel/README.zh.md
+++ b/packages/telemetry/session-telemetry-otel/README.zh.md
@@ -24,6 +24,8 @@
 | `FEEDBACK_ONLY` | 每个 `feedback/record` 都会回放权威会话日志中截至该事件的后缀，并进行投影与脱敏。后续记录等待下一个反馈事件；如果没有后续反馈，则留在本地。 |
 | `DISABLED` | 不构造协调器、提供方、处理器或导出器。没有遥测记录会离开进程。`feedback/record` 会记录 `session telemetry is DISABLED; nothing will be shared and this feedback remains local`；该事件留在本地会话日志中。 |
 
+程序化 TypeScript 配置使用导出的 `TelemetryMode` 枚举（`TelemetryMode.FULL`、`TelemetryMode.FEEDBACK_ONLY` 或 `TelemetryMode.DISABLED`）；原始字符串字面量不可赋值。序列化后的 Cordis 配置继续使用上表所示的字符串值。
+
 `exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填，无默认值，且必须能解析为 `http(s)`；在 `DISABLED` 中可省略且不使用。上传模式也会拒绝不是正整数的 `processor.maxExportBatchSize`，SDK 虽会接受该值，但随后会在关闭时挂起。其余全部是 SDK 自己的选项形态，由 SDK 拥有并在 SDK 文档中说明，两个配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是 SDK 的文档化行为，经 `processor` 透传调优。该后端刻意不实现 `flush()`：批处理器是进程内唯一执行 flush 的组件，`shutdown()` 的排空正因如此才是完整的。
 
 ## 哪些数据会离开本机
diff --git a/packages/telemetry/session-telemetry-otel/src/index.ts b/packages/telemetry/session-telemetry-otel/src/index.ts
index 908f0f90fb..95991cb932 100644
--- a/packages/telemetry/session-telemetry-otel/src/index.ts
+++ b/packages/telemetry/session-telemetry-otel/src/index.ts
@@ -39,11 +39,19 @@ import { resourceFromAttributes } from '@opentelemetry/resources'
 // version (same pattern as dsh-llm's attribution identity).
 const { version } = createRequire(import.meta.url)('../package.json') as { version: string }
 
-/** Supported session-sharing policies for the OTel backend. */
-export const TELEMETRY_MODES = ['FULL', 'FEEDBACK_ONLY', 'DISABLED'] as const
-
 /** Session-sharing policy selected by {@link Config.mode}. */
-export type TelemetryMode = typeof TELEMETRY_MODES[number]
+export enum TelemetryMode {
+  FULL = 'FULL',
+  FEEDBACK_ONLY = 'FEEDBACK_ONLY',
+  DISABLED = 'DISABLED',
+}
+
+/** Supported session-sharing policies for runtime configuration validation. */
+export const TELEMETRY_MODES = [
+  TelemetryMode.FULL,
+  TelemetryMode.FEEDBACK_ONLY,
+  TelemetryMode.DISABLED,
+] as const
 
 const DISABLED_FEEDBACK_WARNING = 'session telemetry is DISABLED; nothing will be shared and this feedback remains local'
 
@@ -81,7 +89,7 @@ export interface Config {
  * axiom (and silently drop every field not re-declared).
  */
 export const Config: z<Config> = z.object({
-  mode: z.union(TELEMETRY_MODES).default('FULL'),
+  mode: z.union(TELEMETRY_MODES).default(TelemetryMode.FULL),
   exporter: z.any(),
   processor: z.any(),
 })
@@ -109,8 +117,8 @@ export class TelemetryOtel extends Telemetry {
 
   constructor(ctx: Context, config: Config) {
     super(ctx)
-    const mode = config.mode ?? 'FULL'
-    if (mode === 'DISABLED') {
+    const mode = config.mode ?? TelemetryMode.FULL
+    if (mode === TelemetryMode.DISABLED) {
       this.provider = undefined
       this.ledger = undefined
       this.ops = undefined
@@ -162,9 +170,9 @@ export class TelemetryOtel extends Telemetry {
     })
     this.ledger = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel', version)
     this.ops = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel/ops', version)
-    const capture: TelemetryCapture = mode === 'FULL' ? 'live' : 'on-demand'
+    const capture: TelemetryCapture = mode === TelemetryMode.FULL ? 'live' : 'on-demand'
     const coordinator = new TelemetryCoordinator(ctx, this, capture)
-    if (mode === 'FEEDBACK_ONLY') {
+    if (mode === TelemetryMode.FEEDBACK_ONLY) {
       // Session.append commits before publishing `session/event`, so the
       // canonical log already includes this feedback record when replay begins.
       ctx.on('session/event', (session, event) => {
diff --git a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
index 9b7e4119b7..26118e4672 100644
--- a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
+++ b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
@@ -5,7 +5,7 @@
  * for the default-exported Service class.
  */
 
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { createServer, type Server } from 'node:http'
 import { once } from 'node:events'
 import { gunzipSync } from 'node:zlib'
@@ -13,7 +13,7 @@ import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { recordFeedback } from '@deepseek-ai/dsh-command-feedback'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import TelemetryOtel, { Config } from '../src/index.ts'
+import TelemetryOtel, { Config, TelemetryMode } from '../src/index.ts'
 
 interface Capture {
   headers: import('node:http').IncomingHttpHeaders
@@ -211,7 +211,7 @@ describe('TelemetryOtel wire', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const fiber = await ctx.plugin(TelemetryOtel, {
-      mode: 'FEEDBACK_ONLY',
+      mode: TelemetryMode.FEEDBACK_ONLY,
       exporter: { url },
     })
     const session = ctx.sessions.create(SessionId('feedback-only'), { meta: {} })
@@ -236,7 +236,7 @@ describe('TelemetryOtel wire', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const fiber = await ctx.plugin(TelemetryOtel, {
-      mode: 'FEEDBACK_ONLY',
+      mode: TelemetryMode.FEEDBACK_ONLY,
       exporter: { url },
     })
     const session = ctx.sessions.create(SessionId('no-feedback'), { meta: {} })
@@ -249,7 +249,7 @@ describe('TelemetryOtel wire', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
-    const fiber = await ctx.plugin(TelemetryOtel, { mode: 'DISABLED' })
+    const fiber = await ctx.plugin(TelemetryOtel, { mode: TelemetryMode.DISABLED })
     const session = ctx.sessions.create(SessionId('disabled'), { meta: {} })
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     recordFeedback(session, 'local report')
@@ -284,12 +284,18 @@ describe('TelemetryOtel wire', () => {
 })
 
 describe('TelemetryOtel config fails loud', () => {
+  it('exposes modes through the nominal enum', () => {
+    expectTypeOf<Config['mode']>().toEqualTypeOf<TelemetryMode | undefined>()
+    expectTypeOf<'FULL'>().not.toExtend<TelemetryMode>()
+    expectTypeOf<TelemetryMode.FULL>().toExtend<TelemetryMode>()
+  })
+
   it.each([
     [{}, /exporter\.url is required/],
     [{ exporter: { url: '' } }, /exporter\.url is required/],
     [{ exporter: { url: 'not a url' } }, /not a valid URL/],
     [{ exporter: { url: 'ftp://collector' } }, /must be http\(s\)/],
-    [{ mode: 'FEEDBACK_ONLY' }, /exporter\.url is required/],
+    [{ mode: TelemetryMode.FEEDBACK_ONLY }, /exporter\.url is required/],
     [{ mode: 'INVALID' }, /INVALID/],
     // The SDK accepts a non-positive batch size but its shutdown drain then
     // splices empty batches forever — dispose would hang, so reject at load.
diff --git a/scripts/gen-config-catalog.ts b/scripts/gen-config-catalog.ts
index b4c20d596a..920688df6d 100644
--- a/scripts/gen-config-catalog.ts
+++ b/scripts/gen-config-catalog.ts
@@ -126,12 +126,13 @@ function loadFile(abs: string, rel: string, cache: Map<string, FileCtx>): FileCt
 }
 
 /** A type declaration a paste can contain. */
-type TypeDecl = ts.InterfaceDeclaration | ts.TypeAliasDeclaration
+type TypeDecl = ts.InterfaceDeclaration | ts.TypeAliasDeclaration | ts.EnumDeclaration
 
-/** Find an interface/type-alias declaration by name in a file, or null. */
+/** Find a pasteable type declaration by name in a file, or null. */
 function findTypeDecl(ctx: FileCtx, name: string): TypeDecl | null {
   for (const stmt of ctx.sf.statements) {
-    if ((ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt)) && stmt.name.text === name) return stmt
+    if ((ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt) || ts.isEnumDeclaration(stmt))
+      && stmt.name.text === name) return stmt
   }
   return null
 }
@@ -207,7 +208,7 @@ function checkMemberDocs(ctx: FileCtx, decl: TypeDecl, violations: string[]): vo
     else ts.forEachChild(type, (n) => { walkNested(n, path) })
   }
   if (ts.isInterfaceDeclaration(decl)) walkMembers(decl.members, decl.name.text)
-  else walkNested(decl.type, decl.name.text)
+  else if (ts.isTypeAliasDeclaration(decl)) walkNested(decl.type, decl.name.text)
 }
 
 /** Cross-file resolution context for the schema-path check. */

From 928c99876e8e3a66a730f759236525f7944a4a0f Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Wed, 5 Aug 2026 21:50:44 +0800
Subject: [PATCH 051/516] feat: add optional dsh badge skill provider

---
 ...26-08-06-bundled-dsh-badge-skill.i18n.yaml |   6 +
 .../2026-08-06-bundled-dsh-badge-skill.md     |  25 +++
 .../2026-08-06-bundled-dsh-badge-skill.zh.md  |  25 +++
 apps/cli/composition.md                       |   3 +
 apps/cli/config/base.cordis.yml               |   4 +
 apps/cli/package.json                         |   1 +
 apps/cli/tests/dsh-badge.snapshot.ts          | 173 ++++++++++++++++++
 apps/cli/tests/fixtures/dsh-badge/cordis.yml  |   9 +
 .../fixtures/dsh-badge/default.cordis.yml     |   6 +
 apps/cli/tests/fixtures/dsh-badge/snapshot.ts |  53 ++++++
 docs/capability-seams.md                      |   4 +-
 docs/config-catalog.md                        |   1 +
 docs/module-graph.md                          |   4 +
 knip.json                                     |   3 +-
 packages/skill/README.i18n.yaml               |   4 +-
 packages/skill/README.md                      |   1 +
 packages/skill/README.zh.md                   |   1 +
 packages/skill/skill-badge/README.i18n.yaml   |   6 +
 packages/skill/skill-badge/README.md          |  22 +++
 packages/skill/skill-badge/README.zh.md       |  22 +++
 .../skill/skill-badge/assets/dsh-badge.md     |  31 ++++
 .../skill/skill-badge/assets/dsh-badge.png    | Bin 0 -> 12339 bytes
 packages/skill/skill-badge/package.json       |  37 ++++
 packages/skill/skill-badge/src/index.ts       |  60 ++++++
 packages/skill/skill-badge/src/invariant.ts   |  30 +++
 .../skill-badge/tests/skill-badge.spec.ts     |  40 ++++
 packages/skill/skill-badge/tsconfig.json      |  14 ++
 pnpm-lock.yaml                                |  15 ++
 scripts/check-workspace-constraints.ts        |   1 +
 scripts/gen-doc-graphs.ts                     |   2 +-
 .../verify-package-readme-model-experience.ts |   1 +
 tsconfig.host.json                            |   1 +
 vitest.snapshot.config.ts                     |   1 +
 33 files changed, 601 insertions(+), 5 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
 create mode 100644 apps/cli/tests/dsh-badge.snapshot.ts
 create mode 100644 apps/cli/tests/fixtures/dsh-badge/cordis.yml
 create mode 100644 apps/cli/tests/fixtures/dsh-badge/default.cordis.yml
 create mode 100644 apps/cli/tests/fixtures/dsh-badge/snapshot.ts
 create mode 100644 packages/skill/skill-badge/README.i18n.yaml
 create mode 100644 packages/skill/skill-badge/README.md
 create mode 100644 packages/skill/skill-badge/README.zh.md
 create mode 100644 packages/skill/skill-badge/assets/dsh-badge.md
 create mode 100644 packages/skill/skill-badge/assets/dsh-badge.png
 create mode 100644 packages/skill/skill-badge/package.json
 create mode 100644 packages/skill/skill-badge/src/index.ts
 create mode 100644 packages/skill/skill-badge/src/invariant.ts
 create mode 100644 packages/skill/skill-badge/tests/skill-badge.spec.ts
 create mode 100644 packages/skill/skill-badge/tsconfig.json

diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
new file mode 100644
index 0000000000..bdc103ef46
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.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-08-06-bundled-dsh-badge-skill.md
+2026-08-06-bundled-dsh-badge-skill.md: afe0b21d64a414a9e78ef55459a42c0d3817e3fd
+2026-08-06-bundled-dsh-badge-skill.zh.md: de1ec989570b07987b12f0a291c84643aa5531fd
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
new file mode 100644
index 0000000000..afe0b21d64
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
@@ -0,0 +1,25 @@
+# Agent Note: Bundled dsh badge skill
+
+Status: implemented
+
+English | [中文](2026-08-06-bundled-dsh-badge-skill.zh.md)
+
+## Problem
+
+DeepSeek Harness has an official attribution badge skill, but keeping it only in a developer's personal skill directory makes it unavailable to other DSH installations and gives the shipped application no explicit opt-in point.
+
+## Decision
+
+`@deepseek-ai/dsh-skill-badge` is a native Cordis plugin that registers one immutable bundled provider on `ctx.skills`. The provider owns the `dsh-badge` summary, instruction body, and PNG resource base; `dsh-tool-skill` remains the sole owner of model-facing catalog and loader rendering.
+
+The shipped CLI composition declares `skill-badge` as disabled. Enabling that existing row is the explicit opt-in; disabled installations advertise no badge skill and gain no model-visible content.
+
+The provider uses the bundled rank after project, custom, and user filesystem sources, so a user-owned `dsh-badge` definition can override it through the ordinary registry precedence contract. Provider disposal removes the contribution through the registry-owned effect.
+
+## Alternatives considered
+
+A Codex marketplace plugin was rejected because it would install into a different runtime and would not participate in DSH's `ctx.skills` seam. Mounting `dsh-skill-local` over the packaged files was rejected because filesystem discovery, parsing, and watching add lifecycle machinery that an immutable single-skill provider does not need.
+
+## Consequences
+
+The badge instructions and source PNG are versioned with DSH and resolve through a packaged directory resource base. The provider has no configuration surface. Package tests pin provider lifecycle and the official PNG bytes, while a keyless assembled-application snapshot pins the enabled catalog and loaded skill body.
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
new file mode 100644
index 0000000000..de1ec98957
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
@@ -0,0 +1,25 @@
+# Agent Note: 内置 dsh 徽章 skill
+
+Status: implemented
+
+[English](2026-08-06-bundled-dsh-badge-skill.md) | 中文
+
+## 问题
+
+DeepSeek Harness 已有官方署名徽章 skill（技能），但如果它只保存在某位开发者的个人 skill 目录中，其他 DSH 安装实例便无法使用，交付的应用也没有显式的选择加入点。
+
+## 决策
+
+`@deepseek-ai/dsh-skill-badge` 是一个原生 Cordis 插件，会在 `ctx.skills` 上注册一个不可变的内置提供方。该提供方负责 `dsh-badge` 的摘要、指令正文和 PNG 资源基底；`dsh-tool-skill` 仍是面向模型的目录与 loader 渲染的唯一归属方。
+
+交付的 CLI（命令行界面）组合将 `skill-badge` 声明为禁用。启用这个现有配置行就是显式选择加入；禁用它的安装实例不会公开任何徽章 skill，也不会获得任何模型可见内容。
+
+该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank，因此用户自有的 `dsh-badge` 定义可通过注册表的常规优先级契约覆盖它。提供方释放时，注册表拥有的 effect 会移除该贡献。
+
+## 曾考虑的替代方案
+
+未采用 Codex marketplace 插件，因为它会安装到不同的运行时，无法参与 DSH 的 `ctx.skills` seam。未采用使用 `dsh-skill-local` 挂载随包文件的方案，因为文件系统发现、解析和监视会引入不必要的生命周期机制，而不可变的单一 skill 提供方并不需要这些机制。
+
+## 后果
+
+徽章指令和源 PNG 随 DSH 一同纳入版本管理，并通过以随包目录为基础的资源基底解析。该提供方没有配置面。包测试固定提供方生命周期和官方 PNG 的字节内容；无密钥的组装应用快照则固定启用后的目录和已加载的 skill 正文。
diff --git a/apps/cli/composition.md b/apps/cli/composition.md
index 28f58bcf4d..8edf39a07a 100644
--- a/apps/cli/composition.md
+++ b/apps/cli/composition.md
@@ -72,6 +72,8 @@ flowchart LR
   cfg --> plugin_dsh_base_skill
   plugin_dsh_base_skill_local["skill-local<br/>@deepseek-ai/dsh-skill-local"]
   cfg --> plugin_dsh_base_skill_local
+  plugin_dsh_base_skill_badge["skill-badge<br/>@deepseek-ai/dsh-skill-badge"]
+  cfg --> plugin_dsh_base_skill_badge
   plugin_dsh_base_tool_skill["tool-skill<br/>@deepseek-ai/dsh-tool-skill"]
   cfg --> plugin_dsh_base_tool_skill
   plugin_dsh_base_commands["commands<br/>@deepseek-ai/dsh-commands"]
@@ -182,6 +184,7 @@ flowchart LR
 | `workspace-context` | `@deepseek-ai/dsh-workspace-context` |
 | `skill` | `@deepseek-ai/dsh-skill` |
 | `skill-local` | `@deepseek-ai/dsh-skill-local` |
+| `skill-badge` | `@deepseek-ai/dsh-skill-badge` |
 | `tool-skill` | `@deepseek-ai/dsh-tool-skill` |
 | `commands` | `@deepseek-ai/dsh-commands` |
 | `goal` | `@deepseek-ai/dsh-goal` |
diff --git a/apps/cli/config/base.cordis.yml b/apps/cli/config/base.cordis.yml
index dddf2fc1b5..f5f39a6ae5 100644
--- a/apps/cli/config/base.cordis.yml
+++ b/apps/cli/config/base.cordis.yml
@@ -204,6 +204,10 @@
 - id: skill-local
   name: '@deepseek-ai/dsh-skill-local'
 
+- id: skill-badge
+  name: '@deepseek-ai/dsh-skill-badge'
+  disabled: true
+
 - id: tool-skill
   name: '@deepseek-ai/dsh-tool-skill'
 
diff --git a/apps/cli/package.json b/apps/cli/package.json
index 4ba1da7e86..dfe35e6159 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -92,6 +92,7 @@
     "@deepseek-ai/dsh-session-title-first-message-llm": "workspace:^",
     "@deepseek-ai/dsh-settings-local": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-badge": "workspace:^",
     "@deepseek-ai/dsh-skill-local": "workspace:^",
     "@deepseek-ai/dsh-spill-local": "workspace:^",
     "@deepseek-ai/dsh-spill-policy": "workspace:^",
diff --git a/apps/cli/tests/dsh-badge.snapshot.ts b/apps/cli/tests/dsh-badge.snapshot.ts
new file mode 100644
index 0000000000..d78f4c743d
--- /dev/null
+++ b/apps/cli/tests/dsh-badge.snapshot.ts
@@ -0,0 +1,173 @@
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+const binScript = fileURLToPath(new URL('./fixtures/dsh-badge/snapshot.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('./fixtures/dsh-badge/cordis.yml', import.meta.url))
+const defaultConfigPath = fileURLToPath(new URL('./fixtures/dsh-badge/default.cordis.yml', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+const badgeAssetsPath = fileURLToPath(new URL('../../../packages/skill/skill-badge/assets/', import.meta.url))
+
+describe('dsh badge assembled snapshot', () => {
+  it('advertises and loads the opt-in bundled skill through the shipped app', async () => {
+    const disabled = await runLoaderSmoke({
+      label: 'disabled dsh badge skill snapshot',
+      tempDirPrefix: 'headless-snapshot-dsh-badge-disabled-',
+      binScript,
+      libBinScript: binScript,
+      configPath: defaultConfigPath,
+      tsconfigPath,
+    })
+    const enabled = await runLoaderSmoke({
+      label: 'dsh badge skill snapshot',
+      tempDirPrefix: 'headless-snapshot-dsh-badge-',
+      binScript,
+      libBinScript: binScript,
+      configPath,
+      tsconfigPath,
+    })
+    const disabledSnapshot = JSON.parse(disabled.stdout) as unknown
+    const enabledSnapshot = JSON.parse(
+      enabled.stdout.replaceAll(badgeAssetsPath, '{{badgeAssetsPath}}'),
+    ) as unknown
+
+    expect(disabled.stderr).toBe('')
+    expect(enabled.stderr).toBe('')
+    expect(disabledSnapshot).toMatchInlineSnapshot(`
+      {
+        "result": {
+          "content": [
+            {
+              "text": "Error: skill "dsh-badge" is unknown or no longer available",
+              "type": "text",
+            },
+          ],
+          "error": {
+            "message": "skill "dsh-badge" is unknown or no longer available",
+          },
+          "isError": true,
+        },
+      }
+    `)
+    expect(enabledSnapshot).toMatchInlineSnapshot(`
+      {
+        "catalog": [
+          {
+            "text": "<system-reminder>
+      A skill is a reusable set of task-specific instructions. The following skills are available in this session:
+
+      <available_skills>
+      - \`dsh-badge\`: Add the official “powered by dsh” badge to documents, pull requests, merge requests, and other content produced with DeepSeek Harness. Use whenever creating a pull request or merge request. Also use when the user asks for a dsh badge, powered-by-dsh attribution, or a reusable dsh badge asset or snippet.
+      </available_skills>
+
+      If the user names a skill, or the task clearly matches a skill's description, call the \`skill\` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.
+      </system-reminder>",
+            "type": "text",
+          },
+        ],
+        "result": {
+          "content": [
+            {
+              "text": "<skill_content name="dsh-badge">
+      <skill_resources>
+      Base directory for this skill: {{badgeAssetsPath}}
+      Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.
+      </skill_resources>
+
+      <skill_instructions>
+      # dsh Badge
+
+      Add the official “powered by dsh” badge without recreating or restyling it.
+
+      ## Assets
+
+      - Local PNG: [\`dsh-badge.png\`](dsh-badge.png), 726×120 source image; render at 121×20
+      - Shields.io image URL: \`https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white\`
+      - Project URL: \`https://github.com/deepseek-harness/deepseek-harness\`
+
+      ## Markdown
+
+      Use this linked badge in Markdown:
+
+      \`\`\`markdown
+      [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+      \`\`\`
+
+      If attribution should not be linked, use:
+
+      \`\`\`markdown
+      ![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)
+      \`\`\`
+
+      ## Usage rules
+
+      - For GitHub or GitLab Markdown, use the Shields.io URL and link it to the project URL unless the user asks for an unlinked image.
+      - For Feishu and other systems that import remote images unreliably, upload \`dsh-badge.png\` from this skill directory instead of generating another badge.
+      - Preserve the badge's 121×20 dimensions and aspect ratio.
+      - Place the badge at the end of the attributed document or section unless the user specifies another position.
+      - Do not substitute another color, logo, label, or project URL.
+
+      </skill_instructions>
+      </skill_content>",
+              "type": "text",
+            },
+          ],
+          "isError": false,
+          "value": {
+            "content": "# dsh Badge
+
+      Add the official “powered by dsh” badge without recreating or restyling it.
+
+      ## Assets
+
+      - Local PNG: [\`dsh-badge.png\`](dsh-badge.png), 726×120 source image; render at 121×20
+      - Shields.io image URL: \`https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white\`
+      - Project URL: \`https://github.com/deepseek-harness/deepseek-harness\`
+
+      ## Markdown
+
+      Use this linked badge in Markdown:
+
+      \`\`\`markdown
+      [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+      \`\`\`
+
+      If attribution should not be linked, use:
+
+      \`\`\`markdown
+      ![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)
+      \`\`\`
+
+      ## Usage rules
+
+      - For GitHub or GitLab Markdown, use the Shields.io URL and link it to the project URL unless the user asks for an unlinked image.
+      - For Feishu and other systems that import remote images unreliably, upload \`dsh-badge.png\` from this skill directory instead of generating another badge.
+      - Preserve the badge's 121×20 dimensions and aspect ratio.
+      - Place the badge at the end of the attributed document or section unless the user specifies another position.
+      - Do not substitute another color, logo, label, or project URL.
+      ",
+            "name": "dsh-badge",
+            "provider": "dsh-badge",
+            "resourceBase": {
+              "kind": "directory",
+              "path": "{{badgeAssetsPath}}",
+            },
+          },
+        },
+        "summary": {
+          "description": "Add the official “powered by dsh” badge to documents, pull requests, merge requests, and other content produced with DeepSeek Harness. Use whenever creating a pull request or merge request. Also use when the user asks for a dsh badge, powered-by-dsh attribution, or a reusable dsh badge asset or snippet.",
+          "invocation": {
+            "modelInvocable": true,
+            "userInvocable": true,
+          },
+          "name": "dsh-badge",
+          "provider": "dsh-badge",
+          "resourceBase": {
+            "kind": "directory",
+            "path": "{{badgeAssetsPath}}",
+          },
+          "source": "bundled",
+        },
+      }
+    `)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})
diff --git a/apps/cli/tests/fixtures/dsh-badge/cordis.yml b/apps/cli/tests/fixtures/dsh-badge/cordis.yml
new file mode 100644
index 0000000000..b3bfdb1b04
--- /dev/null
+++ b/apps/cli/tests/fixtures/dsh-badge/cordis.yml
@@ -0,0 +1,9 @@
+- id: skill-badge
+  disabled: false
+
+- id: skill-local
+  config:
+    watch: false
+
+- id: telemetry-otel
+  disabled: true
diff --git a/apps/cli/tests/fixtures/dsh-badge/default.cordis.yml b/apps/cli/tests/fixtures/dsh-badge/default.cordis.yml
new file mode 100644
index 0000000000..ac3e48441a
--- /dev/null
+++ b/apps/cli/tests/fixtures/dsh-badge/default.cordis.yml
@@ -0,0 +1,6 @@
+- id: skill-local
+  config:
+    watch: false
+
+- id: telemetry-otel
+  disabled: true
diff --git a/apps/cli/tests/fixtures/dsh-badge/snapshot.ts b/apps/cli/tests/fixtures/dsh-badge/snapshot.ts
new file mode 100644
index 0000000000..99379b4fe4
--- /dev/null
+++ b/apps/cli/tests/fixtures/dsh-badge/snapshot.ts
@@ -0,0 +1,53 @@
+import { fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
+import { agentEvents, Inbox, type Agent } from '@deepseek-ai/dsh-agent'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import { boot, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-skill'
+import type {} from '@deepseek-ai/dsh-tools'
+
+const overlayPath = process.argv[2]
+if (overlayPath === undefined) throw new Error('dsh-badge snapshot requires an overlay path')
+const baseConfigPath = fileURLToPath(new URL('../../../config/base.cordis.yml', import.meta.url))
+const ctx = await boot('dsh-badge-snapshot', baseConfigPath, loadOverlayPatches('dsh-badge-snapshot', overlayPath))
+
+try {
+  const agentId = SessionId('dsh-badge-snapshot')
+  const session = ctx.sessions.create(agentId, { meta: { cwd: process.cwd() } })
+  const agent: Agent = {
+    ctx: new Context(),
+    id: agentId,
+    options: {},
+    session,
+    inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+    status: 'idle',
+    send: () => {},
+    followup: () => {},
+    steer: () => {},
+    inject: () => { throw new Error('dsh-badge snapshot must receive the catalog at the step boundary') },
+    cancel: () => {},
+    runMaintenance: task => task(new AbortController().signal),
+    whenIdle: () => Promise.resolve(),
+  }
+  const decision = await agentEvents(ctx, agent).waterfall(
+    'agent/pre-step',
+    [],
+    { turn: 1, step: 1, signal: new AbortController().signal },
+    () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
+  )
+  const catalog = decision.kind === 'enter'
+    ? decision.messages.find(message => message.role === 'user'
+      && message.source.kind === 'skill-catalog')?.content
+    : undefined
+  const summary = (await ctx.skills.list()).find(skill => skill.name === 'dsh-badge')
+  const result = await ctx.tools.execute({
+    callId: CallId('dsh-badge-snapshot'),
+    name: 'skill',
+    arguments: { name: 'dsh-badge' },
+    signal: new AbortController().signal,
+  })
+  process.stdout.write(`${JSON.stringify({ catalog, summary, result })}\n`)
+} finally {
+  await ctx.fiber.dispose()
+}
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index cb24cee7d5..a5f20b5349 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -89,6 +89,7 @@ flowchart LR
   svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"]
   pkg_skill["skill"]
   svc_skills["ctx.skills<br/>Skill provider registry"]
+  pkg_skill_badge["skill-badge"]
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
@@ -219,6 +220,7 @@ flowchart LR
   pkg_settings --> svc_settings
   pkg_settings_local --> svc_settings
   pkg_skill --> svc_skills
+  pkg_skill_badge --> svc_skills
   pkg_skill_local --> svc_skills
   pkg_spill --> svc_spillStore
   pkg_spill_local --> svc_spillStore
@@ -373,7 +375,7 @@ flowchart LR
 | `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
-| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
+| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index ffa3d5bdd4..449addad8a 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2362,6 +2362,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-session` ([`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts))
 - `@deepseek-ai/dsh-session-checkpoint-policy` — requires `llm` · `sessionPersistence` · `sessions` · `tools` ([`packages/session-persistence/session-checkpoint-policy/src/index.ts`](../packages/session-persistence/session-checkpoint-policy/src/index.ts))
 - `@deepseek-ai/dsh-session-projection` ([`packages/session-projection/session-projection/src/index.ts`](../packages/session-projection/session-projection/src/index.ts))
+- `@deepseek-ai/dsh-skill-badge` — requires `skills` ([`packages/skill/skill-badge/src/index.ts`](../packages/skill/skill-badge/src/index.ts))
 - `@deepseek-ai/dsh-storage` ([`packages/storage/storage/src/index.ts`](../packages/storage/storage/src/index.ts))
 - `@deepseek-ai/dsh-subagent` ([`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts))
 - `@deepseek-ai/dsh-subprocess-local` ([`packages/subprocess/subprocess-local/src/index.ts`](../packages/subprocess/subprocess-local/src/index.ts))
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 0e2e7e0c37..7f3f68603f 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -56,6 +56,7 @@ flowchart TD
   end
   subgraph group_skill["packages/skill"]
     pkg_skill["skill"]
+    pkg_skill_badge["skill-badge"]
     pkg_skill_local["skill-local"]
     pkg_tool_skill["tool-skill"]
   end
@@ -303,6 +304,8 @@ flowchart TD
   pkg_llm --> pkg_brand
   pkg_llm --> pkg_invariants
   pkg_llm --> pkg_timeout
+  pkg_skill_badge --> pkg_invariants
+  pkg_skill_badge --> pkg_skill
   pkg_client_connection --> pkg_host_webserver
   pkg_client_connection --> pkg_invariants
   pkg_client_hmr --> pkg_client_modules
@@ -1106,6 +1109,7 @@ flowchart TD
 | [`typert-generator`](../packages/typert/generator) | `typert` | [`invariants`](../packages/support/invariants) |
 | [`typert-registry`](../packages/typert/registry) | `typert` | [`invariants`](../packages/support/invariants) |
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout) |
+| [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/support/invariants), [`skill`](../packages/skill/skill) |
 | [`client-connection`](../packages/client/connection) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-locale`](../packages/client/locale) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
diff --git a/knip.json b/knip.json
index dfb8058d7c..8d10010644 100644
--- a/knip.json
+++ b/knip.json
@@ -622,7 +622,8 @@
     "apps/cli": {
       "entry": [
         "tests/**/*.spec.ts",
-        "tests/**/*.e2e.ts"
+        "tests/**/*.e2e.ts",
+        "tests/**/*.snapshot.ts"
       ],
       "project": [
         "src/**/*.ts",
diff --git a/packages/skill/README.i18n.yaml b/packages/skill/README.i18n.yaml
index 2d424c61dd..74875f2aa3 100644
--- a/packages/skill/README.i18n.yaml
+++ b/packages/skill/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/skill/README.md
-README.md: d10049ac3e741350fddb42f430b70f063da1d12d
-README.zh.md: 67f2da6f75edecd180ff861122c6392684ed9bdb
+README.md: 533904859ad998de4f371a073fde98b68660097b
+README.zh.md: 1fad581cc61a05251f671577dcb7edab37281283
diff --git a/packages/skill/README.md b/packages/skill/README.md
index d10049ac3e..533904859a 100644
--- a/packages/skill/README.md
+++ b/packages/skill/README.md
@@ -7,6 +7,7 @@ This family discovers reusable agent instructions and exposes them to the model
 | Package | Role | ctx key |
 |---|---|---|
 | [`skill/`](skill/README.md) | Defines skill provider registration and lookup | `ctx.skills` |
+| [`skill-badge/`](skill-badge/README.md) | Contributes the optional bundled dsh badge skill | registers on `ctx.skills` |
 | [`skill-local/`](skill-local/README.md) | Discovers skills from local filesystems | registers on `ctx.skills` |
 | [`tool-skill/`](tool-skill/README.md) | Publishes the skill catalog and model-facing loader | registers on `ctx.tools` |
 
diff --git a/packages/skill/README.zh.md b/packages/skill/README.zh.md
index 67f2da6f75..1fad581cc6 100644
--- a/packages/skill/README.zh.md
+++ b/packages/skill/README.zh.md
@@ -7,6 +7,7 @@
 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | [`skill/`](skill/README.md) | 定义 skill 提供方注册和查找 | `ctx.skills` |
+| [`skill-badge/`](skill-badge/README.md) | 贡献可选的内置 dsh 徽章 skill | 注册到 `ctx.skills` |
 | [`skill-local/`](skill-local/README.md) | 从本地文件系统发现 skill | 注册到 `ctx.skills` |
 | [`tool-skill/`](tool-skill/README.md) | 发布 skill 目录和面向模型的 loader | 注册到 `ctx.tools` |
 
diff --git a/packages/skill/skill-badge/README.i18n.yaml b/packages/skill/skill-badge/README.i18n.yaml
new file mode 100644
index 0000000000..4dda53481c
--- /dev/null
+++ b/packages/skill/skill-badge/README.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 packages/skill/skill-badge/README.md
+README.md: 49b38023a7c110bb52bb351668905c702e251216
+README.zh.md: bf7eb0d7d4c0552c07f9cdf5665f8a20df829483
diff --git a/packages/skill/skill-badge/README.md b/packages/skill/skill-badge/README.md
new file mode 100644
index 0000000000..49b38023a7
--- /dev/null
+++ b/packages/skill/skill-badge/README.md
@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-skill-badge
+
+English | [中文](README.zh.md)
+
+Optional bundled skill provider that contributes `dsh-badge` to `ctx.skills`. The skill supplies the official “powered by dsh” Markdown snippets and the packaged PNG for systems that cannot import a remote image reliably.
+
+Mount the plugin to enable the provider. It has no configuration. The shipped CLI composition includes the plugin as `disabled: true`; users must explicitly enable its `skill-badge` row before the skill enters a catalog.
+
+The provider exposes its packaged `assets/` directory as the skill resource base. `dsh-badge.png` is the 726×120 source asset, and consumers render it at 121×20.
+
+## Model Experience
+
+Indirectly, through `@deepseek-ai/dsh-tool-skill`, which renders the catalog entry and selected skill body.
+
+#### KV Cache effect
+
+Disabled by default, the plugin changes no request. When enabled, its catalog entry and any loaded body change the provider KV prefix at their insertion points.
+
+## Known Limitations and Deferred Work
+
+- The provider contributes one fixed skill and has no runtime customization.
+- Remote Markdown uses Shields.io; use the packaged PNG when the target cannot fetch remote images reliably.
diff --git a/packages/skill/skill-badge/README.zh.md b/packages/skill/skill-badge/README.zh.md
new file mode 100644
index 0000000000..bf7eb0d7d4
--- /dev/null
+++ b/packages/skill/skill-badge/README.zh.md
@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-skill-badge
+
+[English](README.md) | 中文
+
+可选的内置 skill（技能）提供方，向 `ctx.skills` 贡献 `dsh-badge`。该 skill 提供官方「powered by dsh」Markdown 片段和随包分发的 PNG，供无法可靠导入远程图片的系统使用。
+
+挂载该插件即可启用提供方。它没有配置。交付的 CLI（命令行界面）组合以 `disabled: true` 包含该插件；用户必须显式启用其 `skill-badge` 配置行，该 skill 才会进入目录。
+
+该提供方将随包分发的 `assets/` 目录作为 skill 资源基底公开。`dsh-badge.png` 是尺寸为 726×120 的源图资源，消费方以 121×20 的尺寸渲染。
+
+## 模型体验
+
+通过 `@deepseek-ai/dsh-tool-skill` 间接影响模型；该包会渲染目录条目和所选 skill 的正文。
+
+#### KV Cache 影响
+
+该插件默认禁用，不会改变任何请求。启用后，其目录条目和任何已加载正文都会在各自插入点改变提供方的 KV 前缀。
+
+## 已知限制与暂缓事项
+
+- 该提供方只贡献一个固定 skill，不提供运行时自定义。
+- 远程 Markdown 使用 Shields.io；当目标环境无法可靠获取远程图片时，请使用随包分发的 PNG。
diff --git a/packages/skill/skill-badge/assets/dsh-badge.md b/packages/skill/skill-badge/assets/dsh-badge.md
new file mode 100644
index 0000000000..9905de1ed9
--- /dev/null
+++ b/packages/skill/skill-badge/assets/dsh-badge.md
@@ -0,0 +1,31 @@
+# dsh Badge
+
+Add the official “powered by dsh” badge without recreating or restyling it.
+
+## Assets
+
+- Local PNG: [`dsh-badge.png`](dsh-badge.png), 726×120 source image; render at 121×20
+- Shields.io image URL: `https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white`
+- Project URL: `https://github.com/deepseek-harness/deepseek-harness`
+
+## Markdown
+
+Use this linked badge in Markdown:
+
+```markdown
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+```
+
+If attribution should not be linked, use:
+
+```markdown
+![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)
+```
+
+## Usage rules
+
+- For GitHub or GitLab Markdown, use the Shields.io URL and link it to the project URL unless the user asks for an unlinked image.
+- For Feishu and other systems that import remote images unreliably, upload `dsh-badge.png` from this skill directory instead of generating another badge.
+- Preserve the badge's 121×20 dimensions and aspect ratio.
+- Place the badge at the end of the attributed document or section unless the user specifies another position.
+- Do not substitute another color, logo, label, or project URL.
diff --git a/packages/skill/skill-badge/assets/dsh-badge.png b/packages/skill/skill-badge/assets/dsh-badge.png
new file mode 100644
index 0000000000000000000000000000000000000000..bf91ecca9790971072e946b56c01bbf99e26abd4
GIT binary patch
literal 12339
zcmdUVV|N`5+jg8C+qN1vb{Z#btj4zO2D`ECrg788wrw`HZ71*ay4U+7o-bLmX0Hs+
zIdvdh>5DW9A|WCK1O$q#jD!jV1k^lm><NMb{%Su{(n3I>L&!>qsd;9dWW#%6&n*qC
z=fQ(QFvZWsL_wb!0+qz+rzMhNKu}Oe;IeN)l+Kb?ny`>KNPR&cVI_7bL3r5Zj$#?)
z?6sogH<;w#+t)=}7GA%*m|IxXkJ)<$D3azla_E@vjq<%WWZmx^EY&fwBloZ={Akp-
zWoJiL<~GLvZiN3Gf%k*he+N|%DdfQK$URyR^63A5G5YY02K4U)8*V3N$iEZ#NQMaA
z|4u}~R>J&uq8~~t=-&xs6UhHNmyw}mXJ?mB`B19Y!u>BK$XMvkO1PAo<+?bGYV;bv
zwKluKmp<O!PkUpT6}nAZci=Xk`~Hq>0gtsdAD;jIV>_Ta2!_F+-S_qB_IUn}PL;9b
zreZV^kN@qQ=B<JLpRZgXycd-=@7v1C%BU#h|3ckA5mE^=l*!}Z>+35nE<Th%!-e*@
zBjCN(YG$QfF<&Y=tE0hT{q4A-gZ97hzbH7$#=SgVYnG}MI`0lAGpa{~g$>^0EtKnh
z5~N{fKK(`V5@cd*Z0x#bJrF~pTKt9UD(@nQH{cw2AY<dLcE9H^qcn7CkFyng_E}~g
zhqYb^aY#sa<s3n;S!M$FFa!ofJZj0N;$0QO)w*~v_NXG?S$6qM`PAt$_7MyiCJ-dr
zTi|}W)E9v>BS_vsqPd3p*?cU+>|zjjoYHpz`;|smBwX92+QX~e5z~a9l98wc96JMK
z0V~aJK(1jqX7D%&8+JmtjVOw|n)-gcNMO-xc0HPvUA-FPS^uElnwA!4+>c)<`sVW$
zuFYP+CGdmkiW1FJPI^TDc;)HmpGpJ92-84#fJ?SYgk$cgs;H>Ey<96&N$-uOtJ<H~
zS(K7+APe$TbiDD~l3Nn~FM;!8%`gj$`ywWUpKTYb&4$oIz+eKwD<CN4Z?knanh)k{
z{?DgabYJ2G2)S)}JueJH(KJ-&|4ZZienN!lCYOEvHt+a#QBjy9qmdM5Db#lFTWe3x
z#=Tthr*vMYtrF$@@hm>77Y0VgUyhsIlf;uMV;Njb`mK%EiWU<&H2-}**DBGV&c{Gc
z=0}1DY7Pz#_p_D5yFr)z@umcF2ukQYGZ4l=z~xxxN2{N?2$>lfa{n^1=K#|Zfy4GM
zo5JQ!06B?NEU6te77C^W3;oX`;7foJafXwb7A`h>m^8~3&Sc~eUx_LH-R+VSGMU_w
z4n`_~*J`PjA&3FUhB@uE>VWq*I26Kz4#kNaq2q;$TpkB~j?QwumazY-R}ZQ|TA>BF
zZmrcPNO=E92Gyb@R)e)UNRjs!&L-$fyx^zpgQ@)DFWHp;dnJT8m{PS;l@9;cK}vL~
zK&sw37T3eW!{r7CI<hL?N9X_LISFI}c`zIbWtrD*vZiinoI}TJif>mum2@NJfBgiX
z0v(f@f<jDWozqYhJo`&s-d<5o?rLbB?RsyF>c2Z7Z+IXi02vDuoa!W-^(_5u5!;s(
z7CrBa4Y8{r$w=JS%K@_9|5_2`3yauNoekXyp&4_N^KKBUga!q7rrmUbY$z%TW$eRI
zSw#x7j?{nA#qT+fbk?b}mK2jZTWNZ~j15po=h$5^2vBb@0OD}FU=W(wt3Dh?%VWQi
z#$_{KZ?{ZuIhZ5l1AJaG?}NOpzDT@km*=}vd3Q`KtoQ5O_lJ6an|j;DpZWR6b7h*q
z5fm&UZ$0l9Ma2%FNOnh36|;B)kCEReS6e&|+o=_E1i7qd9Z$NoCQ)^R8-+D1^!sS|
zop%O-7j^P;y+Z_%I#!ecA#Si=oi3CY7^e{wB#!-Nf^?inr}%ca>;T;R`f<EAY=_%&
z@`vx^75H=oNY@vGECCNxGHX*j@J62LPyz}O_iwdQ%$(1HtOsZZ2zadef^J9HQkXZP
z&v!<bWM0=wuNi9RVuf0pqtT8%*HeW|u4g}A_Y;_RKfd1cH1D=VTi}3)lYjieVQBuX
zLY{RMs@&e{$|ZEYJ#Ow_a{Bu<wFd7XM$v)m%O4}=Uj%=!qkm9hB(X-7zos`8vwU$}
zfLtDjcBK)`lp^Zuz%1~8ee&$5r}ui?O$ExM&8P>?jjAXx9E%Q>RIt%(Bt>csMn92&
z(>zPqF9Qlnm-l*q0*~<d=5U+1@&`n-$N3sia6ltO3N<PyQ_6#)jRne+hK6P=TL3SS
z%nM%lESxUKa;33KSD*XChu@Y{KObOo|CXxKjmpLehq)IP783Zn_-@{>2N*PYOxSu>
zCL|`Jw13(k&u(!$-g`N}+#Zky3hkmU&dFtOv<udwzEhFg^*~7h$29GidYSv-H0%?V
zH0q^TFbji90mwf*JiP0^)$5wJnUdJb{N5sm%?Qez!)-*zp{*|9-G7tq23|%b6uBEa
z=KbfyMv-XLR{L+gmXs9?0)lX#Xu7ZN)?519=9{TUb7eg{odV}T_5#BIcm$gBPCd)z
z`ctY{LCW*IXhpRJgphju27A2=x?mo=CG6PXRvuh65Hg&uXp|tj3(x~z&RWi+Kp1H%
zX2VI!4Wdx|WqdyU`LV(gMiQ$~b{~y<L5QD+Q-071Fy8)(%v}AHl=NiKFidR9re3iw
zC1P8j&HHIh=_h?%v??Z{`7h#y7YD5t|HQi&v5vDEyJu!qOs`M*UuT;NRqCKt1x!`6
zNFzQdB#)>>J`IoQ+`Q6$ZJu`@n`9{u?Cij#2I-Moe@7;OGC8}R5W!no_^qAKDyE{U
zYE)`C&L&Lqgy_ZLf=Nb(#zz^6Mu1<9U%=MS{IwPYN0Sb3kni_=7b|p^*5%Cbpz%ki
zAto|Xr``7vi2g>h(=(<*e;T=bGGn2=1kBh2S17is0gKi&ja(9&RvoPKXI?IP{Ou=b
zgBBoD(r!^m(f$NC;d(d%W2=ZGpIsJ7PaNIufmX=pE+iIF8nFV59HbE9pkNTRu_h+7
zd3<;y#C4Ihu}v;S0TO;XpbGZU7!hT=JzhXVg{FenteXKw^tVN5^YDlW!jG15Z)>Qi
z<Ofq;lRlgJZpW+IKrieJgq~xrv!3Hvn=o^H2AV0=ij6NKnEV3r=CDL?8isE7ZR5r3
za0>T9`Ht+TVABxv4=XrVWlX|wO3_fkrV_EwFZ97JGpsFEeQ-J|9O*Pgh_|N&Y7FOZ
zgSvc&RWR0fl^kz=I?j$KR9n&rLCWebkFrWrd7t1*;;d$h%uG#riP*iZNs-AI%)@#@
z(NyCCt@hF_a;6k&++g7d|MIi-T8w8QJm-u;l;H_eYuTD&wxSEC@w**$x^i-Gc6G7H
z#|69|8<;};9gD*dr)ph?LuwE$jK47(#ILHVnh?6rf+wQgjt^XhqvhBmeUKa!K&J_0
zM$%4X&fI4(sH_}_BG`7cOox&KCDQ8)TTN5<$_-MZ3kiAOkSB^V6D*2TbZ$I(ocyh_
zStz$I&d~XhhQTUjsbv6uxtUR%WIAf=a@wW17kNJ6yaGk}cb~Qc{h~jbh+#I2QQSeW
zA}NfzM({uxErLb9LNFgYoP1(1Cpu%c5b80xic=w~KMp%MM``IJttz<|=OL`wsH@JE
zY&Efn9J<$szZUxuB+|9`DFiEnXo43IAMnenHH>WAp3ho5jkEPvLdpEKu4Nt?f|UXc
zr-N)3et;P#3uF^-Zd@gZqdH))mdh&If2rEdGsj`z>tL`t61jH%M%&g|4e}T77abI}
z?=3i}f)QKby5R3_>rDEA-w;gwBN2Vmdpnw^RTk7KadlENvE?_2gf33V=UgBrok}}-
z-#8T(px5d-wIT0#xG{=;=5qig#^-fqI+26d_^CgJ1X!zhvv-&ef<I?+BczsjUGE{`
zvD_&14QrB~pI0%BFb<~{Tuv~g*+73P<hbcyPx3XwmSIdP>RL_W=o9j^DhjaN*xuWT
z$-T&j!H9AW$tqUNWg*-9$in_rEb^n}WTzT;iQ+fTjXpesUgF@P2O!er$PB%f3=iMh
zN)}@b;rBf0k;C8=B+C_yc=eo+-k#Ur6ClZ5*=SRkG{3xIeeVV;iI~?BBF67P9yBZt
zMigW3+=mS9aAaHCtXt3z_WC0tCw^^2s1a}-76u9#jpkiuj~|InLqKlVjU#^`?0A1`
zS=OZB0GEWW#3=SQWj#ddG}tHCLX#;1V|Moufs~eBK4fT6@S<Jtc2*UX81Jzm(0Vn@
zR9!0>3-rp=Yu(8KM_H2MV0dYNPp6UZXk@5UR!YiUIzRG7F2d7dFY}Zb!EaEibvzjp
z6^+#v5PNR)oURViQor`t!AN-iZ;$(V;)7fwFBid%eHS-f&FGk`QQttQ`~}UhEGjTX
z3<Y7JVuYTgAQsB$0R3VrhV*c}g}0CeiWwTE64AYmCIuhncle^~h1|J$vf}ZXisyqD
zvt{r|l2h<SG9{wY6sXV~hmk~5Kj=qnnTX!!VkE010gF9^W=tv2`fRCG3u;{5gL06B
zv~=0~@jS9~lqHB?N=mBUdJa*1Eq;3s#d9z*G4WDZigLK}5j}p2Z=)NGgndIS=!p)Q
zf4baYvg9JAwE_8Ed!^b;er!@}z1<J!e0II&L4K^qXswRG(p#qSCt)2@3~Mwj%w3Fb
zcid0W7l-9Z*zajHTR?Mv+wnPun2(ZPe2}n#5Nal2@-<5|gFK_?-8t$xi1leQ@6(Y|
zHf>rBm|D0RNz9kHJT~qPO4`uam~yf0rcoH3I4HFpSY%OUrD?^G2j%zS7qOy4QHW@d
zV-5Tt&DL7If}W4UNCwUi%)=12pnjo!;|iK#ueM%|?__Gor`zDLU#ynoEDDAfoR2wa
zLFE214m1bIKD1!?U#p9xI5@C)dcZQaBZjt60Q5IdW25&3u>EYUviX)0VMJa6Yc)AW
zFYyUhs|XmI^#=F`Em&54-pgy$&CI(Un*}yfsxzTUf0xo_DT+Lglxf5j1}3tW@G7ca
z%TGT}5T{^Nm+B>B5;CGa(K~y-(!P4IzTT9bHWVl{Z5NobN0iA6Eio+8P~DV%87_y$
z6%c=+7YlKke3-_M;xJh3vJK25Si`siDG-Gf@Xzy8%0zWx;Qlfp2(ox^XD*xI^MBzj
zg7@NrSyb=V5U7j>1|sFCJ1~lRJ{-7z4+Ay_bcT=O+LWeo8Alv-2n%FYXyP>L_Wz#?
zP|&N~3GpH+T4oX0A&mMK1k>fa$ITH<AH`JjHw@;I9C16X238ZmLDMITHMb^@7bw4V
zn=licW=oWh%3~V5x5DXY71Bg$<8P(q<Pd2cd<iTqLl;px)U>ql74$<8KKl6tJTI@q
z5Cr1+Uk%Z9^Sh@5u(mrdOqkX)kKg^I5db>31x(P2-+WOZS;hh2^}8koF~PEq<YtFd
z$Q#B}z&=<sc#FvY^>!fxZ*w%A^B_g!?SZP>!Woydm;VHj*HW*Ij~FKirc|qnl9X5#
z9Aik`d6BrDE*>GRV@h}rMX+Gi54DWDK!p;;C6m}DTaSjPyn1vqJtJpt;w7;8Sfc*>
zZ=*lan6BZ>{ZkifwLg=;?XJA?z@D5h^zfP0@Vp+;pG5_O-?fD{+Onk<6yFav*q2A3
zlPY~)r*KA;bcLQ4$2d<7UbHe4v@$lkR$>{jdKUL{1Ik65o1jwKYUZJ$(9$p*K~$s?
zq=Dy#f;l9Hj_!_htvA#18Bd?a0LX7Knnuymi-n0fNP-U!_9Cf)lE{g9bA;;Xd$`=*
z-HD~k^;LNXJ7bo_yP}6&>%Jm<s%h<3?Sw{v`txCQk=G0a3ch9hlFffRB~6A9?HE2%
z#`8IF1H-#741?+is}te_wt|V{KDpNS7C0eDw=gS3Pn;EmpoY;Zt<^toju5f1A*q$#
zpgc$~Z>(>f$=CXqo$c4-0&ok?Ju;wi#6J8;sTg8llQuX)GxLmF_q*3yyoFr|`yvY8
zSws13Id-N%iibzn8|)~AvUWobsrq5mFAw8s`}Y3!CNx99!|GYM*@!o?$jMHbKTBBg
z+|P(JXCT>^L$%_?uln?xv?S)6Oc92vT@9YiF&do!+GN_jtuso(5}Foq*9|aHrsaj)
zMLK)XmSqOe4iWL=0ifAuqf=|SX&K0A_;hpl4?3m~Y<HKw!Ks1@aH4R6tK4}5ceUX^
zb-V=;zNmlEegKA|VOu;qTh@>f-rv`!5p4E+&?U*=Ggzdf!gO$GXqo1*VKYwAr?HP1
zT)@=+_SEqJ^@K%4jMn|)y+2MOBScc84o60DY(h1y^lw&M5)KNZ%}09x%z~wMqa%f{
zttoy<9F2SmDEdkMhGZlGEM-aixsO=<$FgEN2Q1Whm<nA>jVZt(Trp7L=3g@sci6A;
z=PB0+$Dvl6c9j^rH)Yk;+Wm}wV)F@So?1raV)6PB#0x&Zlz}FbFHBvp8`Cr2vNrf!
ztZlF;)n+G<Wqj~J#c)F=8!DNuf4pb%uVXl?$H(t!O25MX-q)@%-(=@LM(z5IP;mk@
z*Ev)>!A+n0Gnz!trr@ae2Ve^t+Z*a8`mk@;2{-K(P8<{nM#)7?hqPy2ETibCA^f|3
zbyIN;3MA7x9Sw!ok*V*S{C$0u#pi-p=7rHc$*LF8q#9=DcRj{KYB>*3G9U&jG~oyG
zbohlwFrNO!?-b~l$L^v8$J|b2U?bZ@<bwg=!j!B^U^e+XPAdECaY*+D`>_mfz+3A}
znrP{9@xz8YQZ~FFhp=!?RG@{N%yrPWxBHIw&v~C>PSVwdLi$zrEoa=X$gUVyl4f!u
z>#5AGU)qJ%>*os;1CI4CTO_@5(l&^IFzm>Fq2IQ|<>efRCbDR4rCp4)LM7%!Kl}W*
z?g$=Wj;zdG<bySWJRzt_jPJzrWAOeV<Z3c4_d<NJ`njXo(tL-qp`NPt9;vWyL*X|d
z>t~q{LivO6pFYX-xawd?RGw2Lp|HH-@OqqO#aSV-#xHVJIdXNSJJb*VN(3k$B<39E
z(LmR@d`<qtpI4^g@<tll<^($mDkau_yU~HlEU1w=R*rw-PM`ukgIJ@*L!0Mh^}#Kk
z(Wm7iue?{{J=4mNh<2VzYAWSExY~o)#Mrs$N(ht>4MGt5yX+?Y_^wt7ZD*iYbygKU
zxY^AjT26fJL;`W!b(Rb`kYgibHZ}<fGc|&7O7eOas1gJwgl-ggLLyKo3<g-KQYwM8
za18DBj)0C!t*90GTbeMF25dJZ;i;O88dEf(lK03+llu9T)RsaJ&OX2)38IP(!}9Af
zs|LX(_xJ+TREtA{TvrcG3->B6-s5H{Sx8Dr2|d*<1r;Ub&P{2YyhL;<Ws~Umj8s6g
zXs0X#x?b^D^RbzYofVoY*lll9qiXbjdoo7;J!Z&>{&1Da03k6hMnGUsPkgfT;j~aH
znJ|t-;}AY*B}CVW)Ndz=Ck$D0DE2D4=awh=U_*kl^5;5x45<*KmI;33?pG>Q0MZuU
z8Ii*T8*-a-Y**onq4D9uCEDyTR>4K4Sy3u3i>H(sFsT1Z+BlUKxzvKk7s1p0)TQOI
z6Fc*YD9-3}cY;B<Du*tp?R*p)UoZ<0H;6eRCGM(=B3+_UA0u9l=`uScPljp;^P=~C
zm`IZ&ZUh<$7YY@YjkVQ-M43R$!tvy$WI6q@WU-*O_~2{?hU)NGP(zm_3mlUN7`;)z
z**LoFcA`3U>u;6G4#SnrtpHq+s8M08Nr%Q*Fs#WqK@f&9yCZWWBR@+kXRE=JOC>SR
z)gKu4WaR^zH(@+YoH#ISq3Og{>x4&Sawx5l0RLxGX%JNQlb5Gw#?Ehx;AL_cw9Q8j
zk0Ko2!*@o+jPUZ$$5Zeo$&KDQsRGwzhY1YXGb(jE184&f)KQj|fozKprgOwU1pz*i
zn8!XVj=vcC!yjgy`Vt+(cz}GaHt6uTH)t^#Kpl48fJ5*~EjJhN!YSjyl&CLXDPp9;
zro`5jUPy3>$m5us<HI2F;P)Y}!mkUD)r!h83wNNzu5=QBA8EE5PGZ;*fNF9I^kwlo
zjf-`h>k7&KMt@*)0RzF8DZLi^bq|=4XEVjI%@d+VwbpY0Yu4_3n-EIsEu&QqdZyly
zYMoXl%<Rd&3}7BA*cp{<MT^ADh`=jUeoZFg;j~FQm8&HYOlf+!s}J4OHb}@3lWb*v
zJd}SqfSvkXTHJx(g?$m%@wk`S@6qY~bXdIWH?o2|P3}`y_~Q>~3&puoyKOO<&})ya
z&Z6y`V0|;!4N6h4Xh4ZgWw*y}ZNaWqlsSJGe9H_$I(}={+~-U9e;;F$^U=kO?CACT
zOIl;Ix3yvB(1_O7_O{zyT*88Q1;Fm_=qkb1hCDTWLtehtY(&1_8J9${nVLKsZeeAR
zUsGNqC`3LiueFugl~du4JaT$Dl#ON<0WkK@rhFY++YgVZ5~gpD69I&R_&vm<s&0=K
ze|-T?-}$*4;QCZGB);r9axD*iZ{$g5cTPYT)(qfTn4MJ<gO!q&9?AbzMjy2oaEa<{
z9fXb<L`Fl?H}=yf0A3EN={dY(qHj(wg(eI>^Vpo-6k&_r=J*bbjxNrQ#`~_jYtZvf
zEzw18EU0s0&J0_S<8wOUbCmQPn>6$B6=``)#~!uE5l1g(sc-5+cz9GZiItXV;!e$4
ztq9`W9^2MUABtIwl9KX9UOAnHkMD6iR)pK%H<nbW{pD(;Va<D_${iz6<#ih%CO5?}
z;^Rb9$TOgc2}zJ5XFWA4<^%W4ne2N|f_R|V@w$p(B~>c)h4uqBi!pH75sr=7>PEJ!
zH(;HJz(eVr#ib;FgR?~UvP+B*DD#_sFNMMI`90NU4IeQwsN1i%dexW^T~AW#5{it&
zIZ9VVFLNSAW_Orw(L8k95zX{=FuBmt|M9a*3&r;zh3!Iy_anD(0>p~NhD834K7g<i
zeO?jC*E6>znx4$0se&tcN7=X<J{CS<L)%<;OCgrQWm9Bds_`eISxX)Oj&n30XO;2c
zW3;09uTe22PPfDd(0_3@MR$t^4Mqb1bB@)_9Pu;5Io-|-pX0_iG!x45HMtb0HOrL`
zQSoimLpe!|QK2#2GUAAMFwwfMTs!ky{Dax@#G>UyEY)XNsKt{PL-lu`OU*v@skK#5
zV%+$$7TVvAa-1GY!EgKy4sbC7Pz;4U`opWC4WaIYaol2!g<`JoYFM~ognTNC*=BN}
z^BB_@V_6z9z&%s(inq!tP5S;>rj)7v^wWComvtb$CUxRE3{br=U5!y%QJlT1P0nVU
zA6LD_(Bp!tF}9E#YrvM=g|=^i@WKv3!!b1w61woLSN(~^>tm0JB^yMu%l?-eQHn@n
zRJ1N5<W~x0D1fRYRl7lh<0$W;Z<YpQU%9tf&ggzFmVEDyWiCRji%>t(n7J5hq^##w
zXDLI@bzLt-f1j6}$$}efFUEVs9;M9nyCZna_@G4g6+Rd<r1mCoF(KO;NLeMmr;2W7
zT+FOFf>LzIqgP2M%8Vnin7$HlBs!SSCUk{Darp^c8%)py{U9JV7bsXmxUMBoMk!+4
zzfI++GHezGC?Axq#l&EQrn<&2J0C{GVTTy+Xr~0O?b;0LQT%%D*6`}NGCBRI?=>bC
zerOpTEi7(*-iC?|pcw=hTP_=}{@&ifWQbN%AXV&F_li1iYTQr14mV@7>g!svvxv2_
ztL!ci66=7UGerXY_bF9i%x1AVh`~-jI#~K`DZ`*2e;%Iy#2X#l$HaFC`5^WeiP8X4
zRY%P3Z>3n+63FNuKZ^vG`f=4@w=9(x{z2?&r@CG4aHyu%pUAIr@U9zMrvalLuXt(i
zLyg#v#;@7S{3*XQemo;~Xoh-lMWT`L&+a=VqKUjr8vdRI<@!G{nCV5}GBfUzHZwvq
z?!zJSVHL$0*sv{&TGZfE0jb;FjNfaVWzuGWDWPBa$G|~2t?Ed3XDGRi+!>@(GaAU`
zD7zb-I!6RC#1f~Z8+p7Fk%FU2pJod=81rf1a2e&J`}aTh^7Rw#b!IZvvdSf&YMw_h
zwmcB3t!8M)?gj^CsE~|52d3M;y*%z98KRu5wPjYbT#Zv*JT)djId8=PLxofaMWgH!
zz9c?nb``$cCdY%C>ufN3q!`Qqg~0|ECKNp!O_=V{ny0yIWqev1eeI82m>=93x`!-r
zW{1I8O=0nicE5JyN-qfc@ASWSV_Cnh0#YFM!WO^m{1VTH5^KlOp+>Rw-}(D%)q07}
zKEp}>!X+OU6%_@DL>kwMcFXn2_X`)8f|6IHmF9suo`BAlRA>co`;$L8JBKhS`1zM=
zT;l-EV`TR)3b4Ag;D+MCq%?c?i<d~!)%4E!vj;WhCL|a;)@V01lYC6kRph4rHjn)h
z7H4@yJ0vXqC9wAtq(CU=7!)e6UuRJe^D_gWOh<gI__D|l5D>)oxO8dPW{GNvJ;lc5
zCv1W<#7>oY1H#)MzUY3{`la=Q39KbgUVo_9?%Px*afWB$t6YL|B1GnU5tw?s1Skr}
zm-_n@kZ>Mu2q^IU=^x?INU>MY_+0jGeh(AdvhqP#_<AK>&_pg_obYASM?q8ILTk!(
z1;GkMcE`PLfoAw+dh{S5&?f)+0_uO#13X9}`p(_y@>ScxbYY|}et!e85aU@bpryqC
zNEO(bNLh^XIG~tFPl)IQ#L4L|2TcP%8=1z)NWyFrDLLBX?VEPgu3DF8bse`}!Ux8Y
zPm)FAvCh9>>8_jfN3o}2Pv=X=0!S%}kV`ILK*sVBP+{VVJ0-@ibX?uf*YxNS6H-!&
zI9;|;&z9=sEp6w1CBuUS=B6y+0sO*c?{B4Hty!ET?$<mfHy_mp!tC|5<}9+~3uk3v
z89!|=>KX!`5{w&C;#e`1OO8%;9|&x8(|!p21-c(s)g^Su9=JmUiAsim_dzV>p3Ht)
z77K;(c|#XM1Xd`#7C6q-TB-J^=Th1)<kX-=ntG<1YCzHjJ{TP|FS19;L#b+UI{@7I
z+s^=bttH~^z~yqQ52(1f>W?7*A<ki7MBJ2F4XGbtlyM7ic9kdRv#kfb3lYFk5OwW-
z>-xHi<$m&a)7`IvII;`xlZYCbA>&!Q?IK5)e26y8*Ts=ScHRm|XgDRqE;YJhnA_83
z%{7SyY&Omu|0gTWkz}V^(?iv2Q(5V)ASXu6@+{a8c_0Pm+Tu@e!~~aVq0nx>qY#Bi
zdD%>$GfUG}TEVZzS6eM}vs=)1AxxFEC9FHfJ?2s+TT6M!&5<|%{_FfoyQ*0z21P9f
zA&6BztSF`<s?vB1F2U;lCq4o&Qs}Z5s~lCo(l8KyZlXvr_pDw@Lq@e!h32nl(ES#`
z<l3i_^)Qj2r%ab=vTl2orYYz6UdiUMb8)HPRUCYyP?sUbXvMS7XG0CqLM~!)^J3Qu
zDdO%Dn@AGj;o!g|ZO5b$9AXKMJ&Knm^?E*Su$lWM83<dm8iB(k^CYaKM(XfK36P_*
zka~ZPn_FdQylr#^qs&K1+d2)#Q8={SYJ~CUX3duC>5$G(wg{FhAG>EG1&zbyW{~d>
zb3LgKr<5wE^K;V$e+<jJA7B(B&9nVZ*MCK0b%m6kIRW;nZLcxMQKlHmOaJ|OgBryD
z1n^6GuQ&<DfSCJ~S?{pYsBC#S|7Tg?ymi|eH;cn8qBNTpeK%ec21X=p!K_9K>+jQc
ze{|x2>mU~u4ZLI8<Ub90LEmRA3=sewv;X)Tm`~Y4y?S|Al!3k<wVn;a`at-KFizE$
zQ<U0u8|^;=?ha=LJlVBZvH`Dx??o5<>+}8n<1e@1PWzPWPnUfFL61a%iGw5A|81fJ
zU?<VZfC6&Q%=NiBQ08MIVE>_M;HS=Fm=EVoIMsH)=EEv1tdGzxAsptv&4H~*AH^<K
z(skP4dZ==R9ToV*7y$IghSiiYL<|kP>A$?jo!f|NVg3vB%1QcUzgnN7nwE}GFUC)|
z4rT)A{rDM+<f^%UNyhd^MrYQ;FA6*R)3#`97V~8ByCIfa2_|L)fD>^QHvnPPF>MbL
z;Qh;ioSFJ5IT!8u30V~1d&kvDuvx(4%ogaU-q0SJopIURc7(7z_%m|?ul(PL$SEi&
zxVgCjTMOVZ>Cr}lmXnZxdE*C^W^TKs!OU;u&PJ7$zxPgi>iQ;QS=|9GehdT>#)#Q9
z>iIroBfviAh0YpGCGn-m1!Dbs*ODA}CJI(2)8TiFbz88T?&J1A>^47A4S5z*m{6VN
z6x0<xGxOLSi(rfo%r#y--rue-mw^p)6Ic=}Vp<)D9zm(Qn?@f^rXwOF6Um5WWF^)o
zQS*rt<Xy_heZ3lm0JbuW1s>sNjMSg6b#fMDlqKj{F^-T<?v^3ndkU54!nfI0gdZYu
zy!HruBgV}G0gDXQmi-%a3?;>EnEiLwaGwbHe*|U*IC4@Jecu~U1(pFDfdj3e!<rx~
z63oW*kWUwHrxxT0+l9c@%J_b&@9E5bsjh6{Xj=jf$uE7k!Y^FA^LG3`@%E)s(lEM&
z3wgpMNrACUg|{Irehtb3!qb1E6MAyW0GV0{6f4hJXvz*7+t>H8&A9}Oq%wdDvo0Is
zbKR<#lNXzsP&D)Fvx%gP>S|^5c-neIg*p|@)mnx?X8jDqF*g|5wVBPl1#kqke2t9M
zJ_2|UDK$@Ejm#+fx;K$40?0>ABqlskLY5%Gog?>>6a*~VPLNB>8Jr1Ilpykb$J-MV
znEc^Q=p@dM;-*kOm2J~#qaWtm;aIX;Sa`46*$9CCP{$%BRCu~Adv4Ds^Pu;bL1Lp=
z7o{5-xQuEb9>ROc8F&b>;Hu=&V0wfimoa0UqL(3FE!E+{D$-!la~9pkN<f6T%5_9S
zrzQ7ccv2JK^;=02cmMHgB#8k_4OfsKt`+YheJBr0p)hu_>jXS7=EQ&C9ODvbEJ{xu
zDt(N;;SFRfN|8|>$<>y!zytOT%Zi__qHjva!r?=lrGTQ)Ew)qvFun8}9U<SvV>-{e
zC)M($P&6-Tk)_ubEZ1r*(1bN-(nE^LBmcZT@7U<99!2Ql)mg*7(5J1k8WfIba%c`4
zN=@uPYG^KP*y+p;#5zBt(vTJwm|9{i7c!+U4}|RJhdI8`qpAHMoJ#uay>h-}`IK6(
zquonkmLw{V9(4|&^bp!fhRL-8S*(!G{n2zP&HEYlb3;suE2x0q8*U*eHwh$s7%Jrb
zs4ppHnibyz?R}U38d8mZ0TljQwBT*{Di>AtTy{(GX|XasrhI|G)8)aK_<JYc8^Ap_
zC|KD_;Ti&NG&QKFI#(`-{>dEHH;9nnY=^wvSsI*pwA@fp#)q$2`jZ6F8$GGF&3_Y&
zr#mM%z?V|}sU1472@!{}QO?iJ)iyh|$Nus4etowcgL)$(x!&Z$QvwHQ2w&Pa0L}9o
zM8a}S=U3f8q*Ts(3j!gfq4H!i2r?`|bg<h@Z^OyYCG|FSI!A}ulB`E6+njww%lvdC
z+W_Li=jhJeAl|MAR7JR#cYXkVgucI?2fPCWCg8O}<lDlB!T92T*@x$*pA0l!fF8R!
zSyZ(g`0%`BQ{i{N>S6i~*g^%%$O2y2R|duPy)~e)n9IZA`Rps#42gYerr5=~bNp(t
z#$3^F=v67~y!4{RGl}5c1<PYAxEmYXC!V0;QAJxanTHP%1t0A3nE2pAfn^}kYm)BL
z&aXu|3EU|XD8HGmkh<9Dl>eg9IPQthFj8g5+I9~%kDEln7cpn8`kZd!vY_~$o7phv
zgT9r{zfdo%cE5j#XmeC=_#>U)&HDZA6@zAu4;j}QNx&4YF^tUr!6?Kzq@bI%{Q>IJ
zQKeB&l<6bI(&{kk$`m9LwNF1F2n2l#(j8yKsl>)({(1u-Ztqqyn6=Glp0#f#tpGzV
zb!D4nh#rEjTV)JR)p@l1!bxg+YtwHmI4Ft3>v}Lb7*DlaZx@*sWYMzMogb{<U^ap~
zLZ{|==v1+p)_aQU&cz8bh5zl9H3IB{(Vn<YqnQrve1Nsim!1GRFCDNM1-!rBdqgRc
z1VZ^C`*o@jSn37>W!{Z<+(V+{7)~Auo2owV63DyQn9WhXoO5bLDdOru3DDRxA8yKf
z;&^QTn3U>eVIEG!K!GNIzcie-L=!HbtkP*|^V<V@p5q`IF>jnNif(qL1p5R<3ECoL
zYPHF>8;myF^WE{n#Dk7{xh~%z%^={0T==6CD&qo}A~E2nhDHROwt87RUV@wkMvkg(
zG*g6K74FYgiMVYK>a_%<)T01H6>AEQ`1Ln{IBAXLN5MLGU_{&&jp^I)+sT+Gg+QqS
z7C!Yd4KdMy{{EkML*bnqah74PRBw%d0J))E@Gbm;PT=-v&StTi<|nn3dvsUX#etaD
zMtkO|LmDd}<y3iHn**?QJKWQvSAoL1?R?rFN)BpU5wMCG+KZ_j3g(yw{B~@@{h;M|
zI8AfK;EbsG^=k(4;kcabbMzfa^=*KHm2$3gbI!rW2U$TmB+X@apISmp!mUiVhbr|y
zqE&85QgwqH85v9qmVI!`_n92`kxjW(?Fp`ha>-Ir_!PfgE}5ibh`T-#<KgYsk9PqI
zG(b<X7BqeZ^;ZC)QL#Lk$`76S8WarwiJQf|fJ9;XV#lBs+Jm1O^cV=pd?sIi=`^rx
zX~3TDOysUtLBJFg6c~#46<ef(14toWA)~eGtkqXAbcuTjE?EWp4&67bWWIcnYUr&)
z6c^AJRmNViTyeUoeF*@zY}68#tjPQr-f>uqokV)f6(6AMlmki~OLl${U6F+@yDy?G
z^i3K1(hAOfn^ZKRa=_+a0t`xg3m9mGBdjh75%3z|NsOjbTZIZo_KEti<z3Z>P2YW`
z)Prx0o_JV7ufoR3jNQCx{MCGZ@JwQPzAe4uAuh}@f<-!cgt71^2bSFbyky(vdq>GN
zc!wvjncJzeHLe|IIo6oincAJ-zc*o#ktx2x2SP}g5_gzL^vHbuDS?0tFByT|r50g?
z-O~jt0CciDTeFaNM<y}AmJCCVTl_h*NZ%Q@@Oi~$;<1<JkRULLT!9S>+vmY>D_6*e
zTd)nVpw_-~h#Fb6zP~*m{h7<-uC8ZFFv2eaoJZXW4!m(6X33DZsl)0qLKNM02IBz>
z-3b7>9LhdWbw`x6g7u{VW1_t1O))T}#7%I&NSKL7{#YLJEF*y#2ed+T==q5?j&5KD
z$79hwxV~ZeZj`oB>~=igO`nmKMI0fZ%%+|2Bas{xbtxS%VFKi0hz#K9RbYNo`26{^
zoZM1_1KDg;>ahsHcO&s6Vm@cU_9|s*iU-0Hgeiq_as)UI6!!}sH8r(#4l_oL-(mQl
zfyE99n_j8WanocVhEGF3OUP%Qf@=~gu%ZT<;1hDs3fV`iX$g9JAD}z{LK(dW240L=
zY&NSZ-#|4P@P9f@0~Vq@GvLZ6_~t>Oaq<7`-%(D0p*RHgJ21;{{bvNeUsC+%>#ioR
zMuO2dH8|DpWfKnkXA4)*$ag)QuCrOdCFH|MM&SO>2X4w`iuaG4xj$c5M8;D1&m=yi
z0z4!+3(FTvU0}SkE5vnSQYSS6kqJS-3XxhP2g1q~@lzp3P}>r@o}>c*yH-#LE_dc>
z!@B=JFX%!+Vd14{R|w4F|2(U-8~^95=bi765D@S0krg5=fb}2lAGU{vxIv*wUZ)@5
Q1kOOnN`8?j7dH(0e_HocYybcN

literal 0
HcmV?d00001

diff --git a/packages/skill/skill-badge/package.json b/packages/skill/skill-badge/package.json
new file mode 100644
index 0000000000..b9dc53d9a5
--- /dev/null
+++ b/packages/skill/skill-badge/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-skill-badge",
+  "description": "Bundled dsh badge skill provider for DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "assets",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-skill": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/skill/skill-badge/src/index.ts b/packages/skill/skill-badge/src/index.ts
new file mode 100644
index 0000000000..27cfd29354
--- /dev/null
+++ b/packages/skill/skill-badge/src/index.ts
@@ -0,0 +1,60 @@
+/**
+ * Bundled `dsh-badge` skill provider.
+ *
+ * @module @deepseek-ai/dsh-skill-badge
+ */
+
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import type { Context } from 'cordis'
+import type {
+  SkillCandidate,
+  SkillDefinition,
+  SkillProvider,
+} from '@deepseek-ai/dsh-skill'
+
+const PROVIDER_NAME = 'dsh-badge'
+const BUNDLED_RANK = 600
+const SKILL_BODY_URL = new URL('../assets/dsh-badge.md', import.meta.url)
+const RESOURCE_BASE = {
+  kind: 'directory',
+  path: fileURLToPath(new URL('../assets/', import.meta.url)),
+} as const
+const INVOCATION = { modelInvocable: true, userInvocable: true } as const
+const DESCRIPTION = 'Add the official “powered by dsh” badge to documents, pull requests, merge requests, and other content produced with DeepSeek Harness. Use whenever creating a pull request or merge request. Also use when the user asks for a dsh badge, powered-by-dsh attribution, or a reusable dsh badge asset or snippet.'
+const CANDIDATE: SkillCandidate = {
+  name: 'dsh-badge',
+  description: DESCRIPTION,
+  invocation: INVOCATION,
+  provider: PROVIDER_NAME,
+  source: 'bundled',
+  resourceBase: RESOURCE_BASE,
+  rank: BUNDLED_RANK,
+  locator: SKILL_BODY_URL,
+}
+
+const provider: SkillProvider = {
+  name: PROVIDER_NAME,
+  list: () => Promise.resolve([CANDIDATE]),
+  async get(_candidate): Promise<SkillDefinition> {
+    return {
+      name: CANDIDATE.name,
+      description: CANDIDATE.description,
+      invocation: CANDIDATE.invocation,
+      provider: CANDIDATE.provider,
+      source: CANDIDATE.source,
+      resourceBase: RESOURCE_BASE,
+      content: await readFile(SKILL_BODY_URL, 'utf8'),
+    }
+  },
+}
+
+/** Cordis plugin name. */
+export const name = 'skill-badge'
+/** Service required by the bundled provider. */
+export const inject = ['skills']
+
+/** Register the bundled `dsh-badge` provider on `ctx.skills`. */
+export function apply(ctx: Context): void {
+  ctx.skills.registerProvider(() => provider)
+}
diff --git a/packages/skill/skill-badge/src/invariant.ts b/packages/skill/skill-badge/src/invariant.ts
new file mode 100644
index 0000000000..c087d5917f
--- /dev/null
+++ b/packages/skill/skill-badge/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-skill-badge`.
+ * @module @deepseek-ai/dsh-skill-badge/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-skill-badge'
+
+/** Cordis companion plugin name. */
+export const name = 'skill-badge-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the package owns one immutable provider registration,
+ * while the skill registry owns registration uniqueness and lifecycle checks.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/skill/skill-badge/tests/skill-badge.spec.ts b/packages/skill/skill-badge/tests/skill-badge.spec.ts
new file mode 100644
index 0000000000..e4d62f1c89
--- /dev/null
+++ b/packages/skill/skill-badge/tests/skill-badge.spec.ts
@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import SkillService from '@deepseek-ai/dsh-skill'
+import * as SkillBadge from '@deepseek-ai/dsh-skill-badge'
+
+describe('dsh-skill-badge', () => {
+  it('registers and disposes the bundled badge skill', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SkillService)
+    const fiber = await ctx.plugin(SkillBadge)
+    const resourcePath = fileURLToPath(new URL('../assets/', import.meta.url))
+
+    expect(await ctx.skills.list()).toEqual([{
+      name: 'dsh-badge',
+      description: 'Add the official “powered by dsh” badge to documents, pull requests, merge requests, and other content produced with DeepSeek Harness. Use whenever creating a pull request or merge request. Also use when the user asks for a dsh badge, powered-by-dsh attribution, or a reusable dsh badge asset or snippet.',
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: 'dsh-badge',
+      source: 'bundled',
+      resourceBase: { kind: 'directory', path: resourcePath },
+    }])
+    const loaded = await ctx.skills.get('dsh-badge')
+    expect(loaded?.content).toContain('Preserve the badge\'s 121×20 dimensions')
+    expect(loaded?.resourceBase).toEqual({ kind: 'directory', path: resourcePath })
+
+    await fiber.dispose()
+    expect(await ctx.skills.list()).toEqual([])
+  })
+
+  it('ships the official 726×120 PNG unchanged', async () => {
+    const image = await readFile(new URL('../assets/dsh-badge.png', import.meta.url))
+    expect(image.readUInt32BE(16)).toBe(726)
+    expect(image.readUInt32BE(20)).toBe(120)
+    expect(createHash('sha256').update(image).digest('hex')).toBe(
+      'f2c4f5ec9cbe847c0c763545c4d839efa8485bc74203733d0a0e8259f233c653',
+    )
+  })
+})
diff --git a/packages/skill/skill-badge/tsconfig.json b/packages/skill/skill-badge/tsconfig.json
new file mode 100644
index 0000000000..cf6642f69e
--- /dev/null
+++ b/packages/skill/skill-badge/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../skill" },
+    { "path": "../../support/invariants" }
+  ]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 208e43aa5f..ad6bd2250b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -365,6 +365,9 @@ importers:
       '@deepseek-ai/dsh-skill':
         specifier: workspace:^
         version: link:../../packages/skill/skill
+      '@deepseek-ai/dsh-skill-badge':
+        specifier: workspace:^
+        version: link:../../packages/skill/skill-badge
       '@deepseek-ai/dsh-skill-local':
         specifier: workspace:^
         version: link:../../packages/skill/skill-local
@@ -4846,6 +4849,18 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/skill/skill-badge:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-skill':
+        specifier: workspace:^
+        version: link:../skill
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/skill/skill-local:
     dependencies:
       chokidar:
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 6bd613c2ea..750abbc902 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -105,6 +105,7 @@ const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
   '@deepseek-ai/dsh-client-ui-theme': ['lib/styles'],
   '@deepseek-ai/dsh-helper': ['lib/assets'],
   '@deepseek-ai/dsh-pty-local': ['scripts/ensure-spawn-helper.mjs'],
+  '@deepseek-ai/dsh-skill-badge': ['assets'],
   '@deepseek-ai/dsh-scripts': [
     'lib/dev/tsdown-config.js',
     'lib/local-plugin-loader-hooks.js',
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 1dd7973fd5..98ef82bb8e 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -287,7 +287,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'skill',
     title: 'Skill provider registry',
     mode: 'seam',
-    implementations: ['skill-local'],
+    implementations: ['skill-badge', 'skill-local'],
     consumers: ['tool-skill'],
     note: 'Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies.',
   },
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 041972cb9f..e66e9a73d7 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -111,6 +111,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/telemetry/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers no model surface.' },
   'packages/telemetry/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers no model surface.' },
   'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' },
+  'packages/skill/skill-badge': { kind: 'indirect', reason: 'The bundled provider delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-skill.' },
   'packages/spill/spill': { kind: 'indirect', reason: 'The storage seam delegates model rendering to spill consumers.' },
   'packages/spill/spill-local': { kind: 'indirect', reason: 'The storage backend delegates model rendering to spill consumers.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 4fcf71b680..8c11b48a46 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -135,6 +135,7 @@
     { "path": "./packages/ui/permission" },
     { "path": "./packages/core/tools" },
     { "path": "./packages/skill/skill" },
+    { "path": "./packages/skill/skill-badge" },
     { "path": "./packages/skill/skill-local" },
     { "path": "./packages/skill/tool-skill" },
     { "path": "./packages/ui/tool-ask-user" },
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index 455ecfb4d4..426ebedd8e 100644
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -49,6 +49,7 @@ export default defineConfig({
       // The assembled Web snapshot executes generated client bundles; source
       // mode remains the zero-build path, while lib mode requires a prior build.
       ...(process.env.DSH_EXAMPLE_MODE === 'lib' ? ['apps/web/tests/**/*.snapshot.ts'] : []),
+      'apps/cli/tests/**/*.snapshot.ts',
       'examples/*/tests/**/*.snapshot.ts',
       'packages/sdk/*/tests/**/*.snapshot.ts',
     ],

From c92a1da8135829d86e719e7defdb5f591601e81f Mon Sep 17 00:00:00 2001
From: Jiaying Ding <silver.ding@deepseek.com>
Date: Thu, 6 Aug 2026 16:10:18 +0800
Subject: [PATCH 052/516] fix(ui): update hero headline copy

---
 packages/client/ui-conversation/src/client/locales.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index 9ba5ed3876..eec25939b3 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -44,7 +44,7 @@ export const zh = {
   'access.confirm.acknowledge': '我已了解风险，并愿意继续',
   'access.confirm.cancel': '取消',
   'access.confirm.enable': '启用 Full access',
-  'hero.headline': '开始构建吧',
+  'hero.headline': '探索未知之境',
   'hero.preview': '预览版',
   'hero.chooseWorkspace': '选择工作区',
   'session.hierarchy': '会话层级',
@@ -184,7 +184,7 @@ export const en = {
   'access.confirm.acknowledge': 'I understand the risks and want to continue',
   'access.confirm.cancel': 'Cancel',
   'access.confirm.enable': 'Enable Full access',
-  'hero.headline': 'Let\'s start building',
+  'hero.headline': 'Into the unknown',
   'hero.preview': 'Preview',
   'hero.chooseWorkspace': 'Choose workspace',
   'session.hierarchy': 'Session hierarchy',

From 9db4372af80230b9c4be533d068bb07005eddd6b Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Thu, 6 Aug 2026 16:15:58 +0800
Subject: [PATCH 053/516] fix: align feedback package publication files

---
 packages/feedback/command-feedback/package.json | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/feedback/command-feedback/package.json b/packages/feedback/command-feedback/package.json
index 25bc8446c3..535c438a63 100644
--- a/packages/feedback/command-feedback/package.json
+++ b/packages/feedback/command-feedback/package.json
@@ -21,9 +21,7 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {

From c6b581b4e8069de5cc5594427274f0468b58aaf4 Mon Sep 17 00:00:00 2001
From: Jiaying Ding <silver.ding@deepseek.com>
Date: Thu, 6 Aug 2026 16:26:53 +0800
Subject: [PATCH 054/516] test(ui): update hero headline expectations

---
 .../client/ui-conversation/tests/skeleton.spec.tsx     | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx
index b2828bcc80..858cbe5b7b 100644
--- a/packages/client/ui-conversation/tests/skeleton.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx
@@ -218,7 +218,7 @@ function mount(
 describe('Hero chrome', () => {
   it('renders the English preview badge through the hero locale seat', () => {
     const view = render(<HeroShell t={makeTranslate(en, commonEn)} />)
-    expect(view.getByText('Let\'s start building')).toBeTruthy()
+    expect(view.getByText('Into the unknown')).toBeTruthy()
     expect(view.getByText('Preview')).toBeTruthy()
   })
 })
@@ -282,7 +282,7 @@ describe('ConversationRoot resident composer', () => {
     const header = b.view.container.querySelector('header')
     expect(host).not.toBeNull()
     expect(header?.getAttribute('aria-hidden')).toBe('true')
-    expect(b.view.getByText('开始构建吧')).toBeTruthy()
+    expect(b.view.getByText('探索未知之境')).toBeTruthy()
     expect(b.view.getByText('预览版')).toBeTruthy()
     expect(b.view.queryByTestId('view-chat')).toBeNull()
     // The same machine-backed textarea is live in the hero, and the
@@ -306,7 +306,7 @@ describe('ConversationRoot resident composer', () => {
     const b = mount(conversationSnapshot({ composerPhase: 'blank', blank: true, openState: 'loading' }))
     const root = b.view.container.querySelector('[data-phase]')
     expect(root?.getAttribute('data-phase')).toBe('settling')
-    expect(b.view.queryByText('开始构建吧')).toBeNull()
+    expect(b.view.queryByText('探索未知之境')).toBeNull()
   })
 
   it('settling phase: a session the list has no row for settles conservatively', () => {
@@ -331,7 +331,7 @@ describe('ConversationRoot resident composer', () => {
     // blank the column for the history round-trip.
     const root = b.view.container.querySelector('[data-phase]')
     expect(root?.getAttribute('data-phase')).toBe('hero')
-    expect(b.view.getByText('开始构建吧')).toBeTruthy()
+    expect(b.view.getByText('探索未知之境')).toBeTruthy()
     expect(b.view.getByRole('textbox')).toBeTruthy()
   })
 
@@ -349,7 +349,7 @@ describe('ConversationRoot resident composer', () => {
     expect(after.value).toBe('kept across flip')
     expect(b.chat.store.getSnapshot().draft).toBe('kept across flip')
     expect(b.view.container.querySelector('[data-conversation-scroll]')?.contains(after)).toBe(true)
-    expect(b.view.queryByText('开始构建吧')).toBeNull()
+    expect(b.view.queryByText('探索未知之境')).toBeNull()
     expect(b.view.getByTestId('view-chat')).toBeTruthy()
   })
 

From ccb0842cfcc23ca11a89c136761e355eb0c94741 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Thu, 6 Aug 2026 16:27:27 +0800
Subject: [PATCH 055/516] fix(telemetry): fail closed outside full mode

---
 ...feedback-gated-session-telemetry.i18n.yaml |  4 +-
 ...-08-05-feedback-gated-session-telemetry.md |  6 +-
 ...-05-feedback-gated-session-telemetry.zh.md |  6 +-
 docs/config-catalog.md                        |  2 +-
 .../session-telemetry-otel/README.i18n.yaml   |  4 +-
 .../session-telemetry-otel/README.md          |  2 +
 .../session-telemetry-otel/README.zh.md       |  2 +
 .../session-telemetry-otel/src/index.ts       | 91 +++++++++++++------
 .../session-telemetry-otel/tests/otel.spec.ts | 64 ++++++++++++-
 9 files changed, 139 insertions(+), 42 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
index 331b2e97c6..4255886987 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.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 .agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
-2026-08-05-feedback-gated-session-telemetry.md: 00a8f23fa6bf69f10277ad0d9f2513a0df73de16
-2026-08-05-feedback-gated-session-telemetry.zh.md: 888ce48abe7a5ce2212c152730f8203f5747ef41
+2026-08-05-feedback-gated-session-telemetry.md: 7d923a7e4cf61e8d1119187564b87e4cbb2065b7
+2026-08-05-feedback-gated-session-telemetry.zh.md: 2862162c0c36e5194846c7e1c7bbc24230ce90aa
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
index 00a8f23fa6..7d923a7e4c 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
@@ -18,7 +18,7 @@ Session telemetry originally has one mounted behavior: every accepted record ent
 
 The generic telemetry coordinator owns `live` and `on-demand` capture. Live capture projects, clones, redacts, and hands each event to the backend on the session firehose. On-demand capture registers no continuous capture listeners; `captureSession(session, throughSeq)` reads the canonical log from the handoff cursor through an inclusive boundary, then projects, clones, redacts, and hands over that prefix. The cursor advances only for handed-over records. The [buffer-free replay decision](../simplification/2026-08-06-buffer-free-feedback-telemetry.md) owns why the on-demand path uses the canonical log instead of copied records.
 
-The OTel feedback listener passes the feedback event's sequence to `captureSession()`. `Session.append` commits the event before publishing `session/event`, so replay includes that feedback but cannot extend past its boundary. `exporter.url` is required in `FULL` and `FEEDBACK_ONLY`; `DISABLED` does not validate or use exporter configuration.
+Mode resolution is a closed, fail-before-setup check: an unknown direct-construction value fails before transport configuration is read. Only `FULL` exposes the public service's `emit()` path to the SDK pipeline. `FEEDBACK_ONLY` gives its on-demand coordinator a private backend capability; its listener passes an event to `captureSession()` only when the exact `feedback/record` object is already stored at `session.events[event.seq]`. `Session.append` commits that object before publishing `session/event`, so replay includes the feedback but cannot extend past its boundary. `DISABLED` creates neither the capability nor the SDK pipeline and does not inspect exporter configuration.
 
 ## Alternatives considered
 
@@ -26,8 +26,10 @@ The OTel feedback listener passes the feedback event's sequence to `captureSessi
 
 **Retain capture-time redacted records until feedback.** Rejected because it duplicates an unbounded session prefix even though the canonical log already owns the events. It preserves capture-time redaction policy and operational records, but those properties do not justify the memory cost for a mode defined as uploading the session log after feedback.
 
+**Temporarily allow public `emit()` calls during feedback replay.** Rejected because a redaction listener or another reentrant caller could enqueue an unrelated record while the flag was open. A private backend capability makes authorization structural and keeps the public service closed throughout replay.
+
 **Use an unmounted plugin as the disabled state.** That remains the silent opt-out, but it cannot warn when feedback is recorded. The explicit disabled mode lets a deployment keep one configuration shape and communicate that the local feedback did not leave the process.
 
 ## Consequences
 
-`FULL` remains source- and wire-compatible with the original default. `FEEDBACK_ONLY` adds no telemetry-owned per-event buffer before feedback; a crash before feedback uploads nothing from that prefix. Replay applies the redaction policy mounted when feedback is recorded and excludes operational records that do not exist in the canonical log. Feedback-only streams therefore carry neither `agent-error` nor `shutdown` records, and shutdown absence is not a crash signal. Each later feedback captures the suffix accumulated since the previous boundary. `DISABLED` can omit `exporter.url`, does no reporting work, and keeps feedback only in the canonical session log.
+`FULL` remains source- and wire-compatible with the original default. `FEEDBACK_ONLY` adds no telemetry-owned per-event buffer before feedback; direct service calls and non-canonical feedback events upload nothing, and a crash before feedback uploads nothing from that prefix. Replay applies the redaction policy mounted when feedback is recorded and excludes operational records that do not exist in the canonical log. Feedback-only streams therefore carry neither `agent-error` nor `shutdown` records, and shutdown absence is not a crash signal. Each later feedback captures the suffix accumulated since the previous boundary. `DISABLED` can omit `exporter.url`, does no reporting work, and keeps feedback only in the canonical session log.
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
index 888ce48abe..2862162c0c 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 通用遥测协调器拥有 `live` 与 `on-demand` 捕获。实时捕获在会话 firehose 上投影、深拷贝、脱敏每个事件，并将其交给后端。按需捕获不注册持续捕获监听器；`captureSession(session, throughSeq)` 从 handoff 游标起读取权威日志，直至含边界的指定序列号，然后投影、深拷贝、脱敏并交接该前缀。游标只为已交接记录推进。[无缓冲回放决策](../simplification/2026-08-06-buffer-free-feedback-telemetry.md)说明了按需路径为何使用权威日志而非记录副本。
 
-OTel 反馈监听器把反馈事件的序列号传给 `captureSession()`。`Session.append` 在发布 `session/event` 前已提交该事件，因此回放会包含该反馈，但不会超过其边界。`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填；`DISABLED` 不校验也不使用导出器配置。
+模式解析采用封闭式检查，并在设置前失败：通过直接构造传入未知值时，会在读取传输配置前失败。只有 `FULL` 向 SDK 流水线开放公共服务的 `emit()` 路径。`FEEDBACK_ONLY` 向其按需协调器提供私有后端能力；其监听器向 `captureSession()` 传递事件的唯一条件，是该事件与那个 `feedback/record` 对象身份完全相同，且该对象已存储于 `session.events[event.seq]`。`Session.append` 在发布 `session/event` 前已提交该对象，因此回放包含该反馈，但不会越过其边界。`DISABLED` 既不创建该能力，也不创建 SDK 流水线，并且不检查导出器配置。
 
 ## 考虑过的替代方案
 
@@ -26,8 +26,10 @@ OTel 反馈监听器把反馈事件的序列号传给 `captureSession()`。`Sess
 
 **反馈前保留捕获时已脱敏记录。** 已否决，因为权威日志已拥有这些事件，该方案仍会复制无上限的会话前缀。它能保留捕获时的脱敏策略与运维记录，但对于一个定义为「反馈后上传会话日志」的模式，这些性质不足以证明该内存成本合理。
 
+**在反馈回放期间临时允许公开 `emit()` 调用。** 已否决，因为在标志开启期间，脱敏监听器或另一个可重入调用方可能将无关记录入队。私有后端能力使授权成为结构性保证，并确保公共服务在整个回放过程中保持关闭。
+
 **以不挂载插件表示禁用状态。** 这仍然是静默退出方式，但无法在记录反馈时输出警告。显式禁用模式让部署方可以保持同一种配置形态，并说明本地反馈未离开进程。
 
 ## 后果
 
-`FULL` 与原有默认值保持源码及协议兼容。`FEEDBACK_ONLY` 在反馈前不增加遥测自有的逐事件缓冲；反馈前发生崩溃时，该前缀不上传任何内容。回放使用记录反馈时挂载的脱敏策略，并排除权威日志中不存在的运维记录。因此，仅反馈的流既不携带 `agent-error` 记录，也不携带 `shutdown` 记录，而缺少 shutdown 不是崩溃信号。每个后续反馈都会捕获从上一个边界起累积的后缀。`DISABLED` 可省略 `exporter.url`，不执行任何上报工作，并仅在权威会话日志中保留反馈。
+`FULL` 与原有默认值保持源码及协议兼容。`FEEDBACK_ONLY` 在反馈前不增加遥测自有的逐事件缓冲；直接服务调用与非权威反馈事件均不上传任何内容，且反馈前发生崩溃时，该前缀也不上传任何内容。回放使用记录反馈时挂载的脱敏策略，并排除权威日志中不存在的运维记录。因此，仅反馈的流既不携带 `agent-error` 记录，也不携带 `shutdown` 记录，而缺少 shutdown 不是崩溃信号。每个后续反馈都会捕获从上一个边界起累积的后缀。`DISABLED` 可省略 `exporter.url`，不执行任何上报工作，并仅在权威会话日志中保留反馈。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a2f82d2bec..c386ee4e6b 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1193,7 +1193,7 @@ export enum TelemetryMode {
 
 Depends on: `BatchLogRecordProcessorOptions` (`@opentelemetry/sdk-logs`) · `OTLPExporterNodeConfigBase` (`@opentelemetry/otlp-exporter-base`)
 
-Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:63`](../packages/telemetry/session-telemetry-otel/src/index.ts)
+Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:83`](../packages/telemetry/session-telemetry-otel/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title`
 
diff --git a/packages/telemetry/session-telemetry-otel/README.i18n.yaml b/packages/telemetry/session-telemetry-otel/README.i18n.yaml
index 5a6bd9bc9d..ec7fddf6b4 100644
--- a/packages/telemetry/session-telemetry-otel/README.i18n.yaml
+++ b/packages/telemetry/session-telemetry-otel/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/telemetry/session-telemetry-otel/README.md
-README.md: 01d803236329afbe65e2d92960928441aaff301c
-README.zh.md: 8adf4a3c11b95dc302f8afd0dc79e99433e50f22
+README.md: af177dc86bc30a7b17e34e3c8c3592326b9026f2
+README.zh.md: 9a3ad628bb7d480a1c4cd8346669ad8ebbd6258f
diff --git a/packages/telemetry/session-telemetry-otel/README.md b/packages/telemetry/session-telemetry-otel/README.md
index 01d8032363..af177dc86b 100644
--- a/packages/telemetry/session-telemetry-otel/README.md
+++ b/packages/telemetry/session-telemetry-otel/README.md
@@ -26,6 +26,8 @@ The OpenTelemetry backend for [the telemetry seam](../session-telemetry/) — th
 
 Programmatic TypeScript configuration uses the exported `TelemetryMode` enum (`TelemetryMode.FULL`, `TelemetryMode.FEEDBACK_ONLY`, or `TelemetryMode.DISABLED`); raw string literals are not assignable. Serialized Cordis configuration continues to use the string values shown above.
 
+Upload authorization is positive and fail-closed. An unknown direct-construction mode fails before transport configuration is read. Only `FULL` accepts direct `ctx.telemetry.emit()` calls. `FEEDBACK_ONLY` gives its on-demand coordinator a private backend capability and treats only the exact `feedback/record` object already stored at `session.events[event.seq]` as consent; an independently emitted bus value is ignored. `DISABLED` never constructs the SDK pipeline, even when exporter options are present.
+
 `exporter.url` is required in `FULL` and `FEEDBACK_ONLY`, has no default, and must parse as `http(s)`; it is optional and unused in `DISABLED`. Uploading modes also reject a non-positive-integer `processor.maxExportBatchSize`, which the SDK accepts but then hangs on at shutdown. Everything else is the SDK's option shape, owned and documented by the SDK, and both blocks pass through whole: every `OTLPExporterNodeConfigBase` field (`headers`, `timeoutMillis`, `compression`, `keepAlive`, …) reaches the exporter, and batching, export cadence (`scheduledDelayMillis`), retry, queue bounds, and loss policy under sustained failure are the SDK's documented behavior, tuned through the `processor` passthrough. The backend deliberately implements no `flush()`: the batch processor is the only flusher in the process, which is what makes `shutdown()`'s drain complete.
 
 ## What leaves the machine
diff --git a/packages/telemetry/session-telemetry-otel/README.zh.md b/packages/telemetry/session-telemetry-otel/README.zh.md
index 8adf4a3c11..9a3ad628bb 100644
--- a/packages/telemetry/session-telemetry-otel/README.zh.md
+++ b/packages/telemetry/session-telemetry-otel/README.zh.md
@@ -26,6 +26,8 @@
 
 程序化 TypeScript 配置使用导出的 `TelemetryMode` 枚举（`TelemetryMode.FULL`、`TelemetryMode.FEEDBACK_ONLY` 或 `TelemetryMode.DISABLED`）；原始字符串字面量不可赋值。序列化后的 Cordis 配置继续使用上表所示的字符串值。
 
+上传授权采用显式许可，且为 fail-closed。通过直接构造传入未知模式时，会在读取传输配置前失败。只有 `FULL` 接受对 `ctx.telemetry.emit()` 的直接调用。`FEEDBACK_ONLY` 向其按需协调器提供私有后端能力，并且仅在 `feedback/record` 对象已经存储于 `session.events[event.seq]` 且对象身份完全相同时，才将其视为同意；独立发出的总线值会被忽略。即使存在导出器选项，`DISABLED` 也绝不会构造 SDK 流水线。
+
 `exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填，无默认值，且必须能解析为 `http(s)`；在 `DISABLED` 中可省略且不使用。上传模式也会拒绝不是正整数的 `processor.maxExportBatchSize`，SDK 虽会接受该值，但随后会在关闭时挂起。其余全部是 SDK 自己的选项形态，由 SDK 拥有并在 SDK 文档中说明，两个配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是 SDK 的文档化行为，经 `processor` 透传调优。该后端刻意不实现 `flush()`：批处理器是进程内唯一执行 flush 的组件，`shutdown()` 的排空正因如此才是完整的。
 
 ## 哪些数据会离开本机
diff --git a/packages/telemetry/session-telemetry-otel/src/index.ts b/packages/telemetry/session-telemetry-otel/src/index.ts
index 95991cb932..f380d97549 100644
--- a/packages/telemetry/session-telemetry-otel/src/index.ts
+++ b/packages/telemetry/session-telemetry-otel/src/index.ts
@@ -20,7 +20,7 @@ import type {} from '@deepseek-ai/dsh-command-feedback'
 import {
   Telemetry,
   TelemetryCoordinator,
-  type TelemetryCapture,
+  type TelemetryBackend,
   type TelemetryRecord,
   type TelemetrySeverity,
 } from '@deepseek-ai/dsh-session-telemetry'
@@ -54,6 +54,26 @@ export const TELEMETRY_MODES = [
 ] as const
 
 const DISABLED_FEEDBACK_WARNING = 'session telemetry is DISABLED; nothing will be shared and this feedback remains local'
+const NON_CANONICAL_FEEDBACK_WARNING = 'session telemetry ignored a feedback event absent from the canonical session log'
+const DROP_RECORD: TelemetryBackend['emit'] = () => {}
+
+/** Resolve the default and reject unknown runtime values before transport setup. */
+function resolveMode(mode: TelemetryMode | undefined): TelemetryMode {
+  const resolved = mode ?? TelemetryMode.FULL
+  switch (resolved) {
+    case TelemetryMode.FULL:
+    case TelemetryMode.FEEDBACK_ONLY:
+    case TelemetryMode.DISABLED:
+      return resolved
+    default:
+      return assertNever(resolved)
+  }
+}
+
+/** Fail closed when direct construction bypasses the runtime config schema. */
+function assertNever(value: never): never {
+  throw new Error(`session-telemetry-otel: unsupported mode ${JSON.stringify(value)}`)
+}
 
 /**
  * Plugin configuration: one sharing policy plus two verbatim SDK option
@@ -111,17 +131,15 @@ export class TelemetryOtel extends Telemetry {
   static inject = ['sessions']
   static Config = Config
 
+  private readonly directEmit: TelemetryBackend['emit']
   private readonly provider: LoggerProvider | undefined
-  private readonly ledger: Logger | undefined
-  private readonly ops: Logger | undefined
 
   constructor(ctx: Context, config: Config) {
+    const mode = resolveMode(config.mode)
     super(ctx)
-    const mode = config.mode ?? TelemetryMode.FULL
     if (mode === TelemetryMode.DISABLED) {
+      this.directEmit = DROP_RECORD
       this.provider = undefined
-      this.ledger = undefined
-      this.ops = undefined
       ctx.on('session/event', (_session, event) => {
         if (event.type === 'feedback/record') ctx.logger.warn(DISABLED_FEEDBACK_WARNING)
       })
@@ -168,37 +186,50 @@ export class TelemetryOtel extends Telemetry {
         }),
       ],
     })
-    this.ledger = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel', version)
-    this.ops = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel/ops', version)
-    const capture: TelemetryCapture = mode === TelemetryMode.FULL ? 'live' : 'on-demand'
-    const coordinator = new TelemetryCoordinator(ctx, this, capture)
-    if (mode === TelemetryMode.FEEDBACK_ONLY) {
-      // Session.append commits before publishing `session/event`, so the
-      // canonical log already includes this feedback record when replay begins.
-      ctx.on('session/event', (session, event) => {
-        if (event.type === 'feedback/record') coordinator.captureSession(session, event.seq)
+    const ledger = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel', version)
+    const ops = this.provider.getLogger('@deepseek-ai/dsh-session-telemetry-otel/ops', version)
+    const enqueue: TelemetryBackend['emit'] = (record) => {
+      const logger: Logger = record.channel === 'ops' ? ops : ledger
+      logger.emit({
+        timestamp: record.time,
+        observedTimestamp: record.time,
+        ...SEVERITY[record.severity],
+        // JSON-serializable by the seam's contract (validated at Session.append),
+        // which is exactly the AnyValue subset.
+        body: record.body as AnyValue,
+        attributes: record.attributes,
       })
     }
+    const backend: TelemetryBackend = {
+      emit: enqueue,
+      shutdown: () => this.shutdown(),
+    }
+    if (mode === TelemetryMode.FULL) {
+      this.directEmit = enqueue
+      new TelemetryCoordinator(ctx, backend, 'live')
+      return
+    }
+    this.directEmit = DROP_RECORD
+    const coordinator = new TelemetryCoordinator(ctx, backend, 'on-demand')
+    ctx.on('session/event', (session, event) => {
+      if (event.type !== 'feedback/record') return
+      // Consent is the committed record, not an independently emitted bus value.
+      if (session.events[event.seq] !== event) {
+        ctx.logger.warn(NON_CANONICAL_FEEDBACK_WARNING)
+        return
+      }
+      coordinator.captureSession(session, event.seq)
+    })
   }
 
   /**
-   * Map one seam record onto the SDK logger for its channel — a synchronous
-   * enqueue into the batch processor's queue. Direct calls are no-ops in
-   * `DISABLED`, where no coordinator or SDK pipeline exists.
-   * @param record - the logical record handed over by the coordinator.
+   * Hand a direct service record to the SDK only in `FULL`. Direct calls are
+   * no-ops in `FEEDBACK_ONLY` and `DISABLED`; feedback replay uses a private
+   * backend capability created only for the canonical feedback listener.
+   * @param record - the logical record offered directly to the service.
    */
   emit(record: TelemetryRecord): void {
-    const logger = record.channel === 'ops' ? this.ops : this.ledger
-    if (logger === undefined) return
-    logger.emit({
-      timestamp: record.time,
-      observedTimestamp: record.time,
-      ...SEVERITY[record.severity],
-      // JSON-serializable by the seam's contract (validated at Session.append),
-      // which is exactly the AnyValue subset.
-      body: record.body as AnyValue,
-      attributes: record.attributes,
-    })
+    this.directEmit(record)
   }
 
   // The seam's optional flush() hint is deliberately NOT implemented. The
diff --git a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
index 26118e4672..f7b3a007c9 100644
--- a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
+++ b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
@@ -105,6 +105,13 @@ describe('TelemetryOtel wire', () => {
     const session = ctx.sessions.create(SessionId('wire'), { meta: { cwd: '/tmp/w' } })
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'boom' } })
+    ctx.telemetry.emit({
+      channel: 'ledger',
+      time: Date.now(),
+      severity: 'info',
+      attributes: { 'session.id': 'wire', 'event.type': 'manual', 'event.seq': 99 },
+      body: { direct: true },
+    })
     await fiber.dispose()
 
     expect(captures.length).toBeGreaterThan(0)
@@ -128,6 +135,7 @@ describe('TelemetryOtel wire', () => {
     const end = ledger.find(r => r.record.attributes?.some(a => a.key === 'event.type' && a.value.stringValue === 'turn/end'))
     expect(end?.record.severityNumber).toBe(17)
     expect(end?.record.severityText).toBe('ERROR')
+    expect(eventTypes(captures)).toContain('manual')
 
     expect(ops).toHaveLength(1)
     expect(ops[0]!.record.attributes).toContainEqual({ key: 'telemetry.op', value: { stringValue: 'shutdown' } })
@@ -214,6 +222,16 @@ describe('TelemetryOtel wire', () => {
       mode: TelemetryMode.FEEDBACK_ONLY,
       exporter: { url },
     })
+    ctx.on('telemetry/record', (_record, next) => {
+      ctx.telemetry.emit({
+        channel: 'ledger',
+        time: Date.now(),
+        severity: 'info',
+        attributes: { 'session.id': 'feedback-only', 'event.type': 'direct-bypass', 'event.seq': 99 },
+        body: { mustStayLocal: true },
+      })
+      return next()
+    })
     const session = ctx.sessions.create(SessionId('feedback-only'), { meta: {} })
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     recordFeedback(session, 'first report')
@@ -231,25 +249,48 @@ describe('TelemetryOtel wire', () => {
     expect(allRecords(captures).some(({ scope }) => scope.endsWith('/ops'))).toBe(false)
   })
 
-  it('sends no request when feedback-only mode ends without feedback', async () => {
+  it('ignores direct emits and non-canonical feedback in feedback-only mode', async () => {
     const { url, captures } = await mockCollector()
     const ctx = new Context()
     await ctx.plugin(SessionStore)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
     const fiber = await ctx.plugin(TelemetryOtel, {
       mode: TelemetryMode.FEEDBACK_ONLY,
       exporter: { url },
     })
     const session = ctx.sessions.create(SessionId('no-feedback'), { meta: {} })
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    ctx.telemetry.emit({
+      channel: 'ledger',
+      time: Date.now(),
+      severity: 'info',
+      attributes: { 'session.id': 'no-feedback', 'event.type': 'direct', 'event.seq': 99 },
+      body: { mustStayLocal: true },
+    })
+    ctx.emit('session/event', session, {
+      type: 'feedback/record',
+      seq: session.events.length,
+      time: Date.now(),
+      data: { text: 'not committed' },
+    })
     await fiber.dispose()
+
+    expect(warn).toHaveBeenCalledWith(
+      'session telemetry ignored a feedback event absent from the canonical session log',
+    )
     expect(captures).toEqual([])
   })
 
-  it('boots disabled without exporter config and warns when feedback stays local', async () => {
+  it('constructs no disabled transport even when exporter options are present', async () => {
+    const { url, captures } = await mockCollector()
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
-    const fiber = await ctx.plugin(TelemetryOtel, { mode: TelemetryMode.DISABLED })
+    const fiber = await ctx.plugin(TelemetryOtel, {
+      mode: TelemetryMode.DISABLED,
+      exporter: { url },
+      processor: { maxExportBatchSize: 0 },
+    })
     const session = ctx.sessions.create(SessionId('disabled'), { meta: {} })
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     recordFeedback(session, 'local report')
@@ -268,6 +309,7 @@ describe('TelemetryOtel wire', () => {
     await fiber.dispose()
     recordFeedback(session, 'after disposal')
     expect(warn).toHaveBeenCalledTimes(1)
+    expect(captures).toEqual([])
   })
 
   it('defaults direct construction to full delivery', async () => {
@@ -306,6 +348,22 @@ describe('TelemetryOtel config fails loud', () => {
     await ctx.plugin(SessionStore)
     await expect(ctx.plugin(TelemetryOtel, config as Config)).rejects.toThrow(message)
   })
+
+  it('rejects an unknown direct mode before reading transport config', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    let exporterRead = false
+    const config = {
+      mode: 'INVALID',
+      get exporter() {
+        exporterRead = true
+        throw new Error('transport config was read')
+      },
+    } as unknown as Config
+
+    expect(() => new TelemetryOtel(ctx, config)).toThrow(/unsupported mode "INVALID"/)
+    expect(exporterRead).toBe(false)
+  })
 })
 
 describe('dsh-session-telemetry-otel real-load-path guard', () => {

From 4f595311f793bf2759243aefd31901bfc9c72aac Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Thu, 6 Aug 2026 16:32:46 +0800
Subject: [PATCH 056/516] test: include feedback in Web command catalog
 snapshot

---
 .../tests/snapshots/lifecycle-chrome/command-menu.expected.md    | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/web/tests/snapshots/lifecycle-chrome/command-menu.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/command-menu.expected.md
index 1da9b9a45e..7b18ab188b 100644
--- a/apps/web/tests/snapshots/lifecycle-chrome/command-menu.expected.md
+++ b/apps/web/tests/snapshots/lifecycle-chrome/command-menu.expected.md
@@ -1,6 +1,7 @@
 - listbox "Trigger suggestions":
   - text: Commands
   - option "compact Compact older conversation history" [selected]
+  - option "feedback record feedback about this session"
   - option "goal set or view the goal for a long-running task"
   - option "permission Switch the permission preset (sandbox mode + approval policy)"
   - option "plan Enter or leave plan mode"

From a667d2cd64fcc213e97d7c12c2aaf6f3e8c6c0b0 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 17:21:13 +0800
Subject: [PATCH 057/516] fix(web): address skill row review feedback

---
 .../2026-08-06-web-skill-tool-row.i18n.yaml   |  4 +-
 .../feature/2026-08-06-web-skill-tool-row.md  |  6 +--
 .../2026-08-06-web-skill-tool-row.zh.md       |  6 +--
 packages/client/connection/src/client/api.ts  |  2 +-
 .../client/connection/src/client/fixture.ts   | 43 +++++++++------
 .../client/connection/src/client/index.ts     |  2 +-
 packages/client/runtime/README.i18n.yaml      |  4 +-
 packages/client/runtime/README.md             |  2 +-
 packages/client/runtime/README.zh.md          |  2 +-
 .../client/session-history/history-fold.ts    | 16 ++++--
 .../src/client/sessions/conversation.ts       |  6 +--
 .../runtime/src/client/sessions/session.ts    | 12 +++--
 .../src/client/sessions/transcript-adapter.ts | 26 +++++++--
 packages/client/runtime/tests/fake-api.ts     |  4 +-
 .../client/runtime/tests/history-fold.spec.ts | 14 +++++
 packages/client/runtime/tests/session.spec.ts | 17 ++++++
 .../runtime/tests/transcript-adapter.spec.ts  | 16 ++++++
 .../src/client/chat/ToolRow.tsx               | 13 +----
 .../client/contract/terminal-card-model.ts    | 11 ++--
 .../src/client/toolviews/bash-sample.tsx      |  6 +--
 .../ui-conversation/tests/chat-view.spec.tsx  |  4 +-
 .../client/ui-primitives/src/icons/index.tsx  |  7 +++
 .../client/ui-primitives/tests/icons.spec.tsx |  4 +-
 packages/client/ui-skill/README.i18n.yaml     |  4 +-
 packages/client/ui-skill/README.md            |  2 +-
 packages/client/ui-skill/README.zh.md         |  2 +-
 .../client/ui-skill/src/client/SkillRow.tsx   | 31 +++++------
 packages/client/ui-skill/src/invariant.ts     |  7 +--
 .../ui-skill/tests/browser-plugin.spec.ts     | 44 ++++++++-------
 .../client/ui-skill/tests/skill-row.spec.tsx  |  6 +--
 packages/host/apiproxy/README.i18n.yaml       |  4 +-
 packages/host/apiproxy/README.md              |  2 +-
 packages/host/apiproxy/README.zh.md           |  2 +-
 packages/host/apiproxy/src/api-proxy.ts       | 54 +++++++++++++++----
 packages/host/apiproxy/src/api/index.ts       |  2 +-
 .../host/apiproxy/src/api/sessions.schema.ts  | 12 ++++-
 packages/host/apiproxy/src/api/sessions.ts    | 18 +++++--
 .../apiproxy/tests/api-proxy-view.spec.ts     | 41 ++++++++++++++
 .../host/apiproxy/tests/rpc-schemas.spec.ts   | 10 +++-
 39 files changed, 326 insertions(+), 142 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
index 8186444a8d..237338a7e6 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.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 .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
-2026-08-06-web-skill-tool-row.md: b1d76c411d7ccc839616ddcce9fee18716489bf5
-2026-08-06-web-skill-tool-row.zh.md: c16a9b84d75c641b0fdd8778ff56c331c2c81546
+2026-08-06-web-skill-tool-row.md: bebcf658de33d133ffea8eb190fb4e8e63bf82ff
+2026-08-06-web-skill-tool-row.zh.md: 9377829aab1cb6b347cb837dafe7e7e4afb63868
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
index b1d76c411d..bebcf658de 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
@@ -14,16 +14,16 @@ The Web transcript renders `skill` calls through the generic fallback row, so a
 
 The collapsed row uses a 16-pixel document-and-sparkle glyph and the Bash row's neutral hierarchy: tertiary glyph, secondary `Skill` title, caption separator, and tertiary skill name. Running, failed, and interrupted calls retain the transcript's shimmer, error dot and first-line summary, and warning dot semantics. A settled call expands through the whole summary row into a 260-pixel bounded `Instructions` card containing the exact durable result text; the existing trajectory `Inspect` handoff remains available below the card.
 
-The row derives every visible value from the logged call/result slice. It reads the skill name from the recorded `name` argument and the instructions from durable result content, and never joins the current skill catalog for descriptions or provider metadata. The existing ACP `skill-load` recording is seeded through the real Web persistence and composition path for a keyless interaction and accessibility snapshot.
+The row derives every visible value from the logged call/result slice. It reads the skill name from the recorded `name` argument and the instructions from durable result content, and never joins the current skill catalog for descriptions or provider metadata. Because a history page can contain a `tool/result` after its `tool/call` fell outside the window, the generic `HistoryEntry` envelope now carries the paired call's name, exact arguments JSON, and event time on result entries. The Host derives this transient annotation and the result render intent from the complete log; the runtime prefers an in-window call and otherwise materializes the same `ToolResultNode.call` and `callTime` from the annotation. An orphan result still has `call: null`, and a call-side render intent remains unavailable when its event is outside the page. The existing ACP `skill-load` recording is seeded through the real Web persistence and composition path for a keyless interaction and accessibility snapshot.
 
 ## Alternatives considered
 
 - Keep the generic tool row and add only a `skill` color selector in `ui-conversation`. This leaves the redundant input envelope and generic expanded body in place, and makes the conversation package own a domain-specific visual rule.
-- Add a new `skill` value to the host tool render-intent union. The keyed client slot already identifies this tool without changing the wire contract, so a new cross-boundary presentation value adds protocol and snapshot surface without enabling another consumer.
+- Add a new `skill` value to the host tool render-intent union. The keyed client slot already identifies this tool; the cross-page fix belongs to the generic history pairing envelope used by every tool rather than a skill-specific presentation value.
 - Export the conversation package's private `ToolRow` component for reuse. Client packages intentionally expose contracts rather than cross-package components; exporting it would couple independent feature packages to conversation implementation details.
 
 ## Consequences
 
 `ui-skill` now depends on the public conversation toolview contract, locale and primitive packages, and React in addition to its reference-source dependencies. It owns a small copy of the disclosure-row chrome, so future global interaction changes must update this registrant alongside the Bash sample and conversation rows.
 
-Cold replay stays deterministic when the installed skill catalog changes, and the transcript remains compact until instructions are explicitly expanded. The dedicated card intentionally shows the tool's complete framed output rather than extracting only `<skill_instructions>`, preserving exactly what reached the model and avoiding a second parser for the skill result format.
+Cold replay stays deterministic across pagination and when the installed skill catalog changes, and the transcript remains compact until instructions are explicitly expanded. The generic pairing annotation also prevents other keyed tool rows and result presenters from changing identity at a page boundary without persisting duplicate data. The dedicated card intentionally shows the tool's complete framed output rather than extracting only `<skill_instructions>`, preserving exactly what reached the model and avoiding a second parser for the skill result format.
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
index c16a9b84d7..9377829aab 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
@@ -14,16 +14,16 @@ Web transcript（文本记录）通过通用后备行渲染 `skill` 调用，使
 
 收起的行使用 16 像素的文档与闪光组合图标，并沿用 Bash 行的中性色层级：图标采用三级色，`Skill` 标题采用二级色，分隔符采用 caption 色，skill 名称采用三级色。运行、失败和中断调用分别沿用 transcript 的扫光、错误状态点加首行摘要，以及警告状态点语义。已结算调用可以通过整个摘要行展开一个高度上限为 260 像素的 `Instructions` 卡片，其中原样呈现持久化结果文本；用于跳转至 trajectory 的现有 `Inspect` 入口仍保留在卡片下方。
 
-该行的所有可见值均派生自已记录的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
+该行的所有可见值均派生自已记录的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。由于 history 页可能包含 `tool/result`，而与之配对的 `tool/call` 已落在窗口外，通用 `HistoryEntry` envelope 现在会在结果条目上携带配对调用的名称、精确的 arguments JSON 和事件时间。Host 从完整日志派生这份瞬时注解和结果渲染意图；runtime 优先使用窗口内调用，否则从该注解物化出相同的 `ToolResultNode.call` 和 `callTime`。无配对结果仍为 `call: null`；调用事件位于页面外时，调用侧渲染意图仍不可用。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
 
 ## 考虑过的替代方案
 
 - 保留通用工具行，只添加一个 `skill` 颜色选择器，并将其放在 `ui-conversation` 中。该方案仍会保留多余的输入外层结构和通用展开体，也会让 conversation 包拥有特定领域的视觉规则。
-- 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 无需更改协议契约即可识别该工具，因此新的跨边界呈现值只会增加协议与快照表层，却没有为其他消费方提供新能力。
+- 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 已经能够识别该工具；跨页修复属于所有工具共用的通用 history 配对 envelope，而不是 skill 专用的呈现值。
 - 导出 conversation 包的私有 `ToolRow` 组件供复用。客户端包刻意对外暴露契约而非跨包组件；导出该组件会使独立功能包耦合到 conversation 的实现细节。
 
 ## 后果
 
 除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 契约、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
 
-即使已安装的 skill 目录发生变化，冷回放仍具有确定性；在用户显式展开指令前，transcript 保持紧凑。专用卡片有意显示工具完整封装的输出，而不是只提取 `<skill_instructions>`，从而原样保留模型实际收到的内容，也避免为 skill 结果格式再引入一个解析器。
+无论跨越分页，还是已安装的 skill 目录发生变化，冷回放都保持确定性；在用户显式展开指令前，transcript 保持紧凑。通用配对注解还可防止其他键控工具行和结果 presenter 在分页边界改变身份，同时无需持久化重复数据。专用卡片有意显示工具完整封装的输出，而不是只提取 `<skill_instructions>`，从而原样保留模型实际收到的内容，也避免为 skill 结果格式再引入一个解析器。
diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts
index 6f29b2dda0..de15a9c67f 100644
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -7,7 +7,7 @@
 
 export type {
   ApiProxy, SessionsApi, SessionSearchItem, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
-  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
+  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, HistoryToolCall, ToolEventView,
   DirectoryEntry, DirectoryListing,
   WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 20af221f2d..5a7367acd0 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -29,7 +29,7 @@ import type {
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import { deriveEventMessage, foldSurface } from '@deepseek-ai/dsh-session/surface'
 import type {
-  ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
+  ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HistoryToolCall, HostFrame, MuxFrame, RpcReceipt,
   ModelProviderGroup, ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
   ToolCallView, ToolEventView, ToolResultView, WorkspaceId, WorkspaceView,
 } from './api.ts'
@@ -661,25 +661,33 @@ function presentResult(name: string, argsRaw: string, resultText: string): ToolR
   }
 }
 
-/** Host-side viewFor mirror: tool/call presents from its own args; tool/result back-scans the log for the paired call. */
+/** Full-log tool/result pair used by the fixture history envelope and presenter mirror. */
+function pairedHistoryCall(event: SessionEvent, log: readonly SessionEvent[]): HistoryToolCall | undefined {
+  if (event.type !== 'tool/result') return undefined
+  const callId = String(event.data.message.source.callId)
+  for (let i = log.length - 1; i >= 0; i--) {
+    const candidate = log[i]
+    /* v8 ignore next -- dense-array guard: i stays within [0, log.length),
+    so the undefined arm needs a sparse log no code path builds. */
+    if (candidate !== undefined && candidate.type === 'tool/call' && String(candidate.data.callId) === callId) {
+      return { name: candidate.data.name, arguments: candidate.data.arguments, time: candidate.time }
+    }
+  }
+  return undefined
+}
+
+/** Host-side viewFor mirror: tool/call presents from its own args; tool/result uses its full-log pair. */
 function viewFor(event: SessionEvent, log: readonly SessionEvent[]): ToolEventView | undefined {
   if (event.type === 'tool/call') {
     const view = presentCall(event.data.name, event.data.arguments)
     return view === undefined ? undefined : { for: 'call', view }
   }
   if (event.type === 'tool/result') {
-    const callId = String(event.data.message.source.callId)
-    for (let i = log.length - 1; i >= 0; i--) {
-      const candidate = log[i]
-      /* v8 ignore next -- dense-array guard: i stays within [0, log.length),
-      so the undefined arm needs a sparse log no code path builds. */
-      if (candidate !== undefined && candidate.type === 'tool/call' && String(candidate.data.callId) === callId) {
-        const resultText = event.data.message.content[0].content.map(b => (b.type === 'text' ? b.text : '')).join('')
-        const view = presentResult(candidate.data.name, candidate.data.arguments, resultText)
-        return view === undefined ? undefined : { for: 'result', view }
-      }
-    }
-    return undefined // cross-page unpaired: documented default
+    const call = pairedHistoryCall(event, log)
+    if (call === undefined) return undefined
+    const resultText = event.data.message.content[0].content.map(b => (b.type === 'text' ? b.text : '')).join('')
+    const view = presentResult(call.name, call.arguments, resultText)
+    return view === undefined ? undefined : { for: 'result', view }
   }
   return undefined
 }
@@ -1044,7 +1052,12 @@ function pageOf(
   }
   const events = log.slice(start, end).map((event): HistoryEntry => {
     const view = viewFor(event, log)
-    return view === undefined ? { event } : { event, view }
+    const call = pairedHistoryCall(event, log)
+    return {
+      event,
+      ...view === undefined ? {} : { view },
+      ...call === undefined ? {} : { call },
+    }
   })
   return { events, hasMore: start > 0 }
 }
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index 67b47b06c6..83e9722a49 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -13,7 +13,7 @@ import { isLoopbackHostname } from '../loopback-hostname.ts'
 // ---- Contract re-exports (browser-safe apiproxy channels + core types) ----
 export type {
   ApiProxy, SessionsApi, SessionSearchItem, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
-  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
+  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, HistoryToolCall, ToolEventView,
   DirectoryEntry, DirectoryListing,
   ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 23c867e4c0..ef94a8834c 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: 8ac29a4258bbd7456b20c61e547d48c570e84d27
-README.zh.md: 0e065e43ecc571e68d3976d2100eb43959cb2e3d
+README.md: 3d981392ce0314f41fe84bc1adb2b9484a6a5989
+README.zh.md: c05bdb6ebb33c0ffa47e2b54fb1b3d9d25f2fa6d
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index 8ac29a4258..3d981392ce 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -34,7 +34,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 ## The human transcript
 
-`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
+`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. A paged `tool/result` first pairs against an in-window `tool/call`, then against the Host-carried complete-log call annotation; `ToolResultNode.call` is null only for a truly orphaned durable result, so a page boundary cannot change keyed toolview dispatch, argument-derived labels, or duration. The call-side render intent remains null when its event is outside the window, while the result intent is already computed by the Host from the complete pair. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
 
 Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text comes from the checkpoint's `compact/summary` provenance; a window cut that left the provenance outside makes the row non-expandable rather than empty, and a later page that supplies it resolves the text. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 0e065e43ec..c05bdb6ebb 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -34,7 +34,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 面向人的 transcript（文本记录）
 
-`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并以相同身份落成 `user/message` 时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
+`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。分页得到的 `tool/result` 会先与窗口内的 `tool/call` 配对，再与 Host 携带的完整日志调用注解配对；只有持久结果确实没有配对调用时，`ToolResultNode.call` 才为 null，因此分页边界无法改变键控 toolview 分派、由参数派生的标签或耗时。调用事件位于窗口外时，调用侧渲染意图仍为 null，而结果侧渲染意图已经由 Host 基于完整配对计算完成。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并以相同身份落成 `user/message` 时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
 
 由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时该行不可展开而非空白，后续补上溯源的分页会解析出文本。性能契约：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
 
diff --git a/packages/client/runtime/src/client/session-history/history-fold.ts b/packages/client/runtime/src/client/session-history/history-fold.ts
index d792fd2b76..83a09d3163 100644
--- a/packages/client/runtime/src/client/session-history/history-fold.ts
+++ b/packages/client/runtime/src/client/session-history/history-fold.ts
@@ -362,7 +362,8 @@ export function projectConversationHistory(
   let contextGeneration = 0
 
   for (const [index, event] of events.entries()) {
-    const view = entries[index]?.view
+    const entry = entries[index]
+    const view = entry?.view
     if (event.type === 'tool/call') {
       callIndex.set(String(event.data.callId), {
         name: event.data.name,
@@ -370,8 +371,17 @@ export function projectConversationHistory(
         time: event.time,
         callView: view?.for === 'call' ? view.view : null,
       })
-    } else if (event.type === 'tool/result' && view?.for === 'result') {
-      resultViews.set(event.seq, view.view)
+    } else if (event.type === 'tool/result') {
+      const callId = String(event.data.message.source.callId)
+      if (!callIndex.has(callId) && entry?.call !== undefined) {
+        callIndex.set(callId, {
+          name: entry.call.name,
+          argsRaw: entry.call.arguments,
+          time: entry.call.time,
+          callView: null,
+        })
+      }
+      if (view?.for === 'result') resultViews.set(event.seq, view.view)
     }
     if (isSurfaceEvent(event) && event.surfaceOp !== 'append') {
       contextGeneration++
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index d24b963d6b..14bd0dc9ed 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -155,16 +155,16 @@ export interface TurnErrorNode {
   code?: string
 }
 
-/** A tool result paired (when in-window) with its call head. */
+/** A tool result paired with its durable call head when the Host can resolve it. */
 export interface ToolResultNode {
   kind: 'tool-result'
   seq: number
   /** Unix epoch ms from the tool/result session event. */
   time: number
   callId: string
-  /** Call head backfilled from the in-window tool/call; null when window truncation left the call outside (card head shows callId). */
+  /** Call head from the window or history envelope; null only when the durable log has no pair (card head shows callId). */
   call: { name: string; argsRaw: string } | null
-  /** Unix epoch ms of the paired tool/call when the call is still in-window; used for call-row duration. */
+  /** Unix epoch ms of the paired tool/call; null when the durable log has no pair. */
   callTime: number | null
   content: readonly ContentBlock[]
   isError: boolean
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 776f4494fd..e663af8bf6 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -5,7 +5,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { LlmRetryEventData } from '@deepseek-ai/dsh-llm-retry/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type {
-  HistoryEntry, IApiClient, MessageId, MuxFrame, QueueAction, RpcError,
+  HistoryEntry, HistoryToolCall, IApiClient, MessageId, MuxFrame, QueueAction, RpcError,
   RpcId, RpcResponse, RpcResult, SessionId, SubagentAddress, ToolEventView,
 } from '@deepseek-ai/dsh-client-connection/client'
 // Value import from the inline-safe wire layer (not the connection plugin):
@@ -85,6 +85,8 @@ export class Session implements SessionFace {
   /** Wire views aligned with `events` by index (envelope-level annotations; undefined = no view).
    *  Kept parallel rather than merged so `events` stays the raw log slice (model-visible ⟺ logged). */
   private views: (ToolEventView | undefined)[] = []
+  /** Host-carried call metadata aligned with result entries when the call event is outside the page. */
+  private historyCalls: (HistoryToolCall | undefined)[] = []
   private baseSeq = 0
   private hasMore = false
   private openState: OpenState = 'cold'
@@ -381,10 +383,11 @@ export class Session implements SessionFace {
       }
       this.events = [...older.map(e => e.event), ...this.events]
       this.views = [...older.map(e => e.view), ...this.views]
+      this.historyCalls = [...older.map(e => e.call), ...this.historyCalls]
       /* v8 ignore next -- the ?? arm needs older[0] undefined, but the empty-page branch above already returned. */
       this.baseSeq = older[0]?.event.seq ?? this.baseSeq
       this.hasMore = result.value.hasMore
-      this.transcript.reset(this.events, this.views) // prepend forces a rebuild (the window grew at the head)
+      this.transcript.reset(this.events, this.views, this.historyCalls) // prepend forces a rebuild (the window grew at the head)
       this.rebuildDerivedFromWindow()
     } catch (error) {
       console.error('[web-runtime] loadOlder failed:', error)
@@ -411,6 +414,7 @@ export class Session implements SessionFace {
     this.openError = null
     this.events = []
     this.views = []
+    this.historyCalls = []
     this.baseSeq = 0
     // Superseded, not settled: the baseline replay re-sends still-pending requested frames verbatim
     // (same rpcId), re-minting fresh waits; a stale reference's respond() still reaches the host.
@@ -644,9 +648,10 @@ export class Session implements SessionFace {
   private installWindow(entries: HistoryEntry[], hasMore: boolean, projections?: ProjectionsBaseline): void {
     this.events = entries.map(e => e.event)
     this.views = entries.map(e => e.view)
+    this.historyCalls = entries.map(e => e.call)
     this.baseSeq = this.events[0]?.seq ?? 0
     this.hasMore = hasMore
-    this.transcript.reset(this.events, this.views)
+    this.transcript.reset(this.events, this.views, this.historyCalls)
     this.rebuildDerivedFromWindow()
     if (projections !== undefined) this.projections.seed(projections)
     const buffered = this.liveBuffer
@@ -661,6 +666,7 @@ export class Session implements SessionFace {
     if (tailSeq !== null && event.seq <= tailSeq) return // replay overlap, drop
     this.events.push(event)
     this.views.push(view)
+    this.historyCalls.push(undefined)
     this.transcript.append(event, view)
     this.handoffPendingSteering(event)
     this.applyEventSideEffects(event, view)
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index 306571b2bf..b1d952b804 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -19,7 +19,9 @@ import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 // `sessions: ISessions` (TS2717, the one-program-per-side rule in
 // docs/development.md).
 import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
-import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type {
+  HistoryToolCall, ToolCallView, ToolEventView, ToolResultView,
+} from '@deepseek-ai/dsh-client-connection/client'
 import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
 import { toAssistantBlocks } from './conversation.ts'
 import { contextForm, contextProvenance } from './context-provenance.ts'
@@ -213,8 +215,13 @@ export class TranscriptAdapter {
    * and re-project the transcript.
    * @param events - the new window contents (seq-ascending).
    * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
+   * @param calls - host-carried result pairs aligned with `events` by index.
    */
-  reset(events: readonly SessionEvent[], views?: readonly (ToolEventView | undefined)[]): void {
+  reset(
+    events: readonly SessionEvent[],
+    views?: readonly (ToolEventView | undefined)[],
+    calls?: readonly (HistoryToolCall | undefined)[],
+  ): void {
     this.rev++
     this.eventIndex = new Map()
     this.callIdx = new Map()
@@ -228,7 +235,7 @@ export class TranscriptAdapter {
       /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
       if (event === undefined) continue
       this.eventIndex.set(event.seq, event)
-      this.indexCall(event, views?.[i])
+      this.indexCall(event, views?.[i], calls?.[i])
       this.indexCommand(event)
       if (this.steeringHistory.apply(event)) steeringSeqs.add(event.seq)
       indexAssistantStepTiming(this.stepTimings, event)
@@ -338,9 +345,20 @@ export class TranscriptAdapter {
     return true
   }
 
-  private indexCall(event: SessionEvent, view?: ToolEventView): void {
+  private indexCall(event: SessionEvent, view?: ToolEventView, pairedCall?: HistoryToolCall): void {
     if (event.type === 'tool/result') {
       if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
+      const callId = String(event.data.message.source.callId)
+      if (!this.callIdx.has(callId) && pairedCall !== undefined) {
+        this.callIdx.set(callId, {
+          name: pairedCall.name,
+          argsRaw: pairedCall.arguments,
+          turn: event.data.turn,
+          step: event.data.step,
+          time: pairedCall.time,
+          callView: null,
+        })
+      }
       return
     }
     if (event.type !== 'tool/call') return
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
index e50574d102..b13e27f3c4 100644
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -3,7 +3,7 @@
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
-  ClientResponse, CommandDescriptor, HostFrame, IApiClient, ModelTarget, MuxFrame,
+  ClientResponse, CommandDescriptor, HistoryEntry, HostFrame, IApiClient, ModelTarget, MuxFrame,
   RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId, SessionModels, SessionSearchItem, SkillEntry,
   WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
@@ -68,7 +68,7 @@ export class FakeApiClient implements IApiClient {
   onRename: (payload: unknown) => Promise<RpcResponse<{ title: string; seq: number }>> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 }))
   onFork: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
-  => Promise<RpcResponse<{ events: never[]; hasMore: boolean }>> =
+  => Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean }>> =
     () => Promise.resolve(ok({ events: [], hasMore: false }))
 
   onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
diff --git a/packages/client/runtime/tests/history-fold.spec.ts b/packages/client/runtime/tests/history-fold.spec.ts
index 083bdc3566..f9b40bdb7c 100644
--- a/packages/client/runtime/tests/history-fold.spec.ts
+++ b/packages/client/runtime/tests/history-fold.spec.ts
@@ -53,6 +53,20 @@ describe('projectConversationHistory', () => {
     }])
   })
 
+  it('projects a paged tool result from its host-carried call pair', () => {
+    const result = ev.toolResult(50, 3, 'outside-call', '已加载 skill')
+    const projection = projectConversationHistory([{
+      event: result,
+      call: { name: 'skill', arguments: '{"name":"dsh-code-review"}', time: 40 },
+    }])
+    expect(projection.eventNodes).toMatchObject([{
+      kind: 'tool-result',
+      call: { name: 'skill', argsRaw: '{"name":"dsh-code-review"}' },
+      callTime: 40,
+      callView: null,
+    }])
+  })
+
   it('projects a high-sequence history window without synthesizing its unloaded prefix', () => {
     const baseSeq = 400_000
     const events = [
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index c288c044ee..02753fe09e 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -53,6 +53,23 @@ describe('open', () => {
     expect(snapshot.turnEnds.get(3)).toBe(15)
   })
 
+  it('installs host-carried call metadata for a result-only tail page', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => Promise.resolve(ok({
+      events: [{
+        event: ev.toolResult(50, 3, 'outside-call', '已加载 skill'),
+        call: { name: 'skill', arguments: '{"name":"dsh-code-review"}', time: 40 },
+      }],
+      hasMore: true,
+    }))
+    await session.open()
+    expect(session.getSnapshot().nodes).toMatchObject([{
+      kind: 'tool-result',
+      call: { name: 'skill', argsRaw: '{"name":"dsh-code-review"}' },
+      callTime: 40,
+    }])
+  })
+
   it('is idempotent: concurrent opens share one history call, reopening when open is a no-op', async () => {
     const { api, session } = makeSession()
     await Promise.all([session.open(), session.open()])
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
index 031acf1780..99b4cdf261 100644
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ b/packages/client/runtime/tests/transcript-adapter.spec.ts
@@ -365,6 +365,22 @@ describe('TranscriptAdapter', () => {
     expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null })
   })
 
+  it('materializes a paged tool-result from its host-carried call pair', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset(
+      [ev.toolResult(50, 3, 'outside-call', '已加载 skill')],
+      [undefined],
+      [{ name: 'skill', arguments: '{"name":"dsh-code-review"}', time: 40 }],
+    )
+    expect(adapter.nodes()[0]).toMatchObject({
+      kind: 'tool-result',
+      callId: 'outside-call',
+      call: { name: 'skill', argsRaw: '{"name":"dsh-code-review"}' },
+      callTime: 40,
+      callView: null,
+    })
+  })
+
   it('materializes a tool-result error field when present', () => {
     const adapter = new TranscriptAdapter()
     adapter.reset([
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
index 71cf69cc5f..ac48604fc9 100644
--- a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
@@ -23,7 +23,7 @@
 import { useEffect, useRef, useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
 import clsx from 'clsx'
 import {
-  CodeBlock, DiffBlock, ReadBlock, SearchBlock, StateDot, TerminalBlock, WebBlock,
+  CodeBlock, DiffBlock, IconInspectOutline12, ReadBlock, SearchBlock, StateDot, TerminalBlock, WebBlock,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { WebBlockProps } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
@@ -99,15 +99,6 @@ export interface ToolRowProps {
   inspect?: (() => void) | undefined
 }
 
-/** The Inspect pill's code glyph (user-supplied 16×16), fill follows text color. */
-function IconInspect() {
-  return (
-    <svg width="12" height="12" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden>
-      <path d="M16 8L10.8571 12V10.552L14.1383 8L10.8571 5.448V4L16 8ZM5.14286 10.552L1.86171 8L5.14286 5.448V4L0 8L5.14286 12V10.552ZM9.02514 4L5.59657 12H6.84057L10.2691 4H9.02514Z" fill="currentColor" />
-    </svg>
-  )
-}
-
 /** Leading-slot state substitution: the tool icon yields to the terminal state
  *  semantic (error = red, interrupted = amber halo). Running keeps the icon —
  *  the row sweep (CSS on data-state) carries the in-flight signal. */
@@ -319,7 +310,7 @@ export function ToolRow({
               className={css.inspectButton}
               onClick={inspect}
             >
-              <IconInspect />
+              <IconInspectOutline12 />
               Inspect
             </button>
           )}
diff --git a/packages/client/ui-conversation/src/client/contract/terminal-card-model.ts b/packages/client/ui-conversation/src/client/contract/terminal-card-model.ts
index 8a0c887990..b1c4cbe757 100644
--- a/packages/client/ui-conversation/src/client/contract/terminal-card-model.ts
+++ b/packages/client/ui-conversation/src/client/contract/terminal-card-model.ts
@@ -168,11 +168,12 @@ function collapse(body: string, rooted: boolean, separator = '/'): string {
  *   returns a generic fenced card for an execution error or a background
  *   start, whose text and error styling the generic path preserves.
  *
- * Window truncation can drop the call head from a settled result (see
- * `ToolResultNode.call`/`callView` in dsh-client-runtime), leaving a terminal
- * result with no call side. That still renders: the command falls back to the
- * result view's replacement title, then to an empty command (the prompt line
- * draws bare), and the prompt shows no cwd.
+ * Window truncation can drop the call event and its call-side view from a
+ * settled result (see `ToolResultNode.callView` in dsh-client-runtime), leaving
+ * a terminal result with no presentation call side even though the history
+ * envelope preserves its name and arguments. That still renders: the command
+ * falls back to the result view's replacement title, then to an empty command
+ * (the prompt line draws bare), and the prompt shows no cwd.
  * @param block - RunningToolCall or ToolResultNode off the snapshot caches.
  * @param sessionCwd - the session workspace root, which resolves an omitted or
  *   relative view cwd (see {@link resolveTerminalCwd}); absent leaves both unresolved.
diff --git a/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx b/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx
index 54e021639f..adf4ac4355 100644
--- a/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx
+++ b/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx
@@ -17,7 +17,7 @@ import { useState, type KeyboardEvent } from 'react'
 import type { Context } from 'cordis'
 import clsx from 'clsx'
 import {
-  IconApiOutline14, IconChevronDownOutline14, StateDot, TerminalBlock,
+  IconApiOutline14, IconChevronDownOutline14, IconInspectOutline12, StateDot, TerminalBlock,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ToolRowProps } from '../contract/slots.ts'
@@ -153,9 +153,7 @@ export function BashRow({ toolName, block, sessionId, useSessions, inspect, t }:
             )}
           {inspect !== undefined && (
             <button type="button" className={css.inspectButton} onClick={inspect}>
-              <svg width="12" height="12" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden>
-                <path d="M16 8L10.8571 12V10.552L14.1383 8L10.8571 5.448V4L16 8ZM5.14286 10.552L1.86171 8L5.14286 5.448V4L0 8L5.14286 12V10.552ZM9.02514 4L5.59657 12H6.84057L10.2691 4H9.02514Z" fill="currentColor" />
-              </svg>
+              <IconInspectOutline12 />
               Inspect
             </button>
           )}
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index b7ca8dd149..e83c82130d 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -282,12 +282,12 @@ describe('chat-flow derivation', () => {
 })
 
 describe('ChatView', () => {
-  it('a windowless tool result (call head truncated) renders with an empty tool name', () => {
+  it('an orphan tool result renders through the generic fallback', () => {
     const h = makeHarness({
       nodes: [{ ...toolResult(3, 'w1'), call: null }],
     })
     const view = render(<h.ChatView {...h.props} />)
-    // classifyTool('') → others; the summary slot falls back to the callId.
+    // No durable call exists for this id, so the summary falls back to callId.
     expect(view.container.querySelector('[data-variant="others"]')).not.toBeNull()
     expect(view.getByText('w1')).toBeTruthy()
   })
diff --git a/packages/client/ui-primitives/src/icons/index.tsx b/packages/client/ui-primitives/src/icons/index.tsx
index b0b76e164b..5b99a0e71c 100644
--- a/packages/client/ui-primitives/src/icons/index.tsx
+++ b/packages/client/ui-primitives/src/icons/index.tsx
@@ -750,6 +750,13 @@ export const IconSparkle16 = ({ size = 16, className }: IconProps) => (
   </svg>
 )
 
+/** inspect_outline_12 (shared tool-row trajectory affordance glyph) */
+export const IconInspectOutline12 = ({ size = 12, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden>
+    <path d="M16 8L10.8571 12V10.552L14.1383 8L10.8571 5.448V4L16 8ZM5.14286 10.552L1.86171 8L5.14286 5.448V4L0 8L5.14286 12V10.552ZM9.02514 4L5.59657 12H6.84057L10.2691 4H9.02514Z" fill="currentColor" />
+  </svg>
+)
+
 /** skill_outline_16 (skill tool-row glyph; document instructions + sparkle) */
 export const IconSkillOutline16 = ({ size = 16, className }: IconProps) => (
   <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
diff --git a/packages/client/ui-primitives/tests/icons.spec.tsx b/packages/client/ui-primitives/tests/icons.spec.tsx
index 92f0d3cc37..678eb9754e 100644
--- a/packages/client/ui-primitives/tests/icons.spec.tsx
+++ b/packages/client/ui-primitives/tests/icons.spec.tsx
@@ -16,8 +16,8 @@ const icons = Object.fromEntries(
 const iconNames = Object.keys(icons)
 
 describe('ic_ds_ icon set', () => {
-  it('exports the full P-I set (46 deepsuite + 17 figma extracts + two hand-authored product glyphs)', () => {
-    expect(iconNames.length).toBe(65)
+  it('exports the full P-I set (46 deepsuite + 17 figma extracts + three product glyphs outside those sets)', () => {
+    expect(iconNames.length).toBe(66)
   })
 
   it.each(iconNames)('%s renders an svg with currentColor fills and no hardcoded palette', (name) => {
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index d23f68ee85..5c50d22b89 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/client/ui-skill/README.md
-README.md: 2280c9302dbc46cff723752f88c47940f98417d5
-README.zh.md: 0e9344ff63139f77461b02b48e18b0e94e54c223
+README.md: ba9f1faae0f70a0f7bed4641e02703cc26bcb692
+README.zh.md: f8210a885d201cbdc89d7a34704a819e80463d2c
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index 2280c9302d..ba9f1faae0 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -10,7 +10,7 @@ The `/client` export surface is the plugin body (`apply`/`inject`) only; the sou
 
 ## Skill tool row
 
-The browser plugin also registers a keyed `skill` toolview in `conversation.chat.toolview`. A collapsed row renders the 16-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from the logged call/result slice, never from the current catalog, so cold replay remains stable even when installed skills or their descriptions change.
+The browser plugin also registers a keyed `skill` toolview in `conversation.chat.toolview`. A collapsed row renders the 16-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from the logged call/result slice, using the history envelope's host-carried durable pair when pagination left the call event outside the window; it never reads the current catalog, so cold replay remains stable across page cuts and when installed skills or their descriptions change.
 
 ## Model Experience
 
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 0e9344ff63..f8210a885d 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -10,7 +10,7 @@ skill（技能）引用 source 的浏览器端：把 `/` 触发的 `skill` sourc
 
 ## skill 工具行
 
-浏览器插件还会把一个 key 为 `skill` 的 toolview 注册进 `conversation.chat.toolview`。收起的行以与 Bash 行相同的中性色层级显示 16 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自已记录的调用／结果片段，绝不读取当前 skill 目录，因此即使已安装的 skill 或其描述发生变化，冷回放仍保持稳定。
+浏览器插件还会把一个 key 为 `skill` 的 toolview 注册进 `conversation.chat.toolview`。收起的行以与 Bash 行相同的中性色层级显示 16 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自已记录的调用／结果片段；分页将调用事件留在窗口外时，则使用 history envelope 中由 Host 携带的持久配对。该行绝不读取当前 skill 目录，因此冷回放在跨分页时，以及已安装的 skill 或其描述发生变化时均保持稳定。
 
 ## 模型体验
 
diff --git a/packages/client/ui-skill/src/client/SkillRow.tsx b/packages/client/ui-skill/src/client/SkillRow.tsx
index be1084ec39..076da55d52 100644
--- a/packages/client/ui-skill/src/client/SkillRow.tsx
+++ b/packages/client/ui-skill/src/client/SkillRow.tsx
@@ -4,7 +4,7 @@
 
 import { useState, type KeyboardEvent, type ReactNode } from 'react'
 import {
-  IconChevronDownOutline14, IconSkillOutline16, StateDot,
+  IconChevronDownOutline14, IconInspectOutline12, IconSkillOutline16, StateDot,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
@@ -45,7 +45,8 @@ function skillName(argsRaw: string, callId: string): string {
   return argsRaw === '' ? callId : firstLine(argsRaw)
 }
 
-/** Flatten the durable result exactly like the generic row's text fallback. */
+/** Flatten durable result blocks under the generic tool-row text contract.
+ *  Keep aligned with ui-conversation's contract/tool-call-model.ts `resultText`. */
 function resultText(block: ToolRowProps['block']): string | null {
   if (!('kind' in block)) return null
   const parts: string[] = []
@@ -108,15 +109,6 @@ function stateStatus(state: SkillRowState, t: SkillRowProps['t']): string | null
   }
 }
 
-/** Inspect affordance glyph shared with the transcript's other tool rows. */
-function IconInspect() {
-  return (
-    <svg width="12" height="12" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden>
-      <path d="M16 8L10.8571 12V10.552L14.1383 8L10.8571 5.448V4L16 8ZM5.14286 10.552L1.86171 8L5.14286 5.448V4L0 8L5.14286 12V10.552ZM9.02514 4L5.59657 12H6.84057L10.2691 4H9.02514Z" fill="currentColor" />
-    </svg>
-  )
-}
-
 /**
  * Render one `skill` tool call as an accent summary and instructions disclosure.
  * @param props - keyed toolview payload plus the skill locale seat.
@@ -129,7 +121,6 @@ export function SkillRow({ block, inspect, t }: SkillRowProps) {
   const open = expanded && expandable
   const status = stateStatus(model.state, t)
   const summary = model.errorSummary ?? model.name
-  const ariaLabel = status === null ? `Skill ${summary}` : `${status} Skill ${summary}`
   const toggleExpand = (): void => {
     setExpanded(value => !value)
   }
@@ -138,18 +129,20 @@ export function SkillRow({ block, inspect, t }: SkillRowProps) {
     event.preventDefault()
     toggleExpand()
   }
+  const disclosureProps = expandable ? {
+    role: 'button' as const,
+    tabIndex: 0,
+    'aria-expanded': open,
+    onClick: toggleExpand,
+    onKeyDown: toggleFromKeyboard,
+  } : {}
   const leading = disclosureLeading(model.state, open, expandable)
   return (
     <div className={css.card} data-tool="skill" data-state={model.state}>
       <div
         className={css.row}
         data-expandable={expandable || undefined}
-        role={expandable ? 'button' : undefined}
-        tabIndex={expandable ? 0 : undefined}
-        aria-expanded={expandable ? open : undefined}
-        aria-label={expandable ? ariaLabel : undefined}
-        onClick={expandable ? toggleExpand : undefined}
-        onKeyDown={expandable ? toggleFromKeyboard : undefined}
+        {...disclosureProps}
       >
         <span className={css.leading}>{leading}</span>
         {status !== null ? <span className={css.visuallyHidden}>{status}</span> : null}
@@ -167,7 +160,7 @@ export function SkillRow({ block, inspect, t }: SkillRowProps) {
           </section>
           {inspect !== undefined ? (
             <button type="button" className={css.inspectButton} onClick={inspect}>
-              <IconInspect />
+              <IconInspectOutline12 />
               Inspect
             </button>
           ) : null}
diff --git a/packages/client/ui-skill/src/invariant.ts b/packages/client/ui-skill/src/invariant.ts
index 241482a306..9246466cd1 100644
--- a/packages/client/ui-skill/src/invariant.ts
+++ b/packages/client/ui-skill/src/invariant.ts
@@ -15,9 +15,10 @@ export const name = 'client-ui-skill-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: a single slash-source registration whose disposal is
- * proven by the HMR-safety spec — it emits no cordis events and owns no
- * cross-plugin mutable state.
+ * No runtime invariant: the slash source, locale dictionaries, and keyed
+ * toolview are registry-owned registrations whose disposal is proven by the
+ * HMR-safety spec. They emit no cordis events and own no cross-plugin mutable
+ * state.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/client/ui-skill/tests/browser-plugin.spec.ts b/packages/client/ui-skill/tests/browser-plugin.spec.ts
index 3febb36efb..9b047a3713 100644
--- a/packages/client/ui-skill/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts
@@ -14,6 +14,7 @@
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { SlashService } from '@deepseek-ai/dsh-client-ui-slash/client'
 import type { ClientSessionContext, SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
 import { apply, inject } from '../src/client/index.ts'
@@ -25,33 +26,28 @@ type ListResult =
   | { ok: false; error: { code: string; message: string; details: object } }
 type ListFn = (payload: object, signal?: AbortSignal) => Promise<{ result: ListResult }>
 
-interface PresentationRegistration {
-  name: string
-  key?: string
-  locale?: string
-}
-
 interface PresentationCapture {
-  registration?: PresentationRegistration
-  component?: unknown
+  slots: SlotsService
   dictionaries: Array<{ namespace: string; dictionaries: unknown }>
+  localeDisposed: boolean
 }
 
 /** Provide the presentation registries and capture the plugin's registrations. */
 function providePresentation(ctx: Context): PresentationCapture {
-  const capture: PresentationCapture = { dictionaries: [] }
+  const slots = new SlotsService(ctx)
+  slots.register({
+    name: 'root',
+    children: { 'conversation.chat.toolview': { kind: 'keyed', scope: 'session' } },
+  } as never, () => null)
+  const capture: PresentationCapture = {
+    slots,
+    dictionaries: [],
+    localeDisposed: false,
+  }
   ctx.provide('locale', {
     register(namespace: string, dictionaries: unknown) {
       capture.dictionaries.push({ namespace, dictionaries })
-      return () => {}
-    },
-  })
-  ctx.provide('slots', {
-    inject(_name: string, factory: () => unknown) { factory() },
-    register(registration: PresentationRegistration, component: unknown) {
-      capture.registration = registration
-      capture.component = component
-      return () => {}
+      return () => { capture.localeDisposed = true }
     },
   })
   return capture
@@ -110,10 +106,10 @@ describe('apply', () => {
     ctx.provide('sessions', { subagentAddress: () => undefined })
     const presentation = providePresentation(ctx)
     await ctx.plugin({ inject: [...inject], apply }).await()
-    expect(presentation.registration).toEqual({
-      name: 'conversation.chat.toolview', key: 'skill', locale: 'skill',
-    })
-    expect(presentation.component).toBe(SkillToolRow)
+    const entry = presentation.slots.entries('conversation.chat.toolview')[0]
+    expect(entry?.options).toMatchObject({ key: 'skill' })
+    expect(entry?.locale).toBe('skill')
+    expect(entry?.component).toBe(SkillToolRow)
     expect(presentation.dictionaries).toEqual([{
       namespace: 'skill', dictionaries: {
         zh: {
@@ -138,7 +134,7 @@ describe('apply', () => {
     ctx.provide('sessions', {})
     await ctx.plugin(SlashService).await()
     ctx.provide('connection', { api: { skills: { list: listOk(CATALOG) } } })
-    providePresentation(ctx)
+    const presentation = providePresentation(ctx)
     const fiber = ctx.plugin({ inject: [...inject], apply })
     await fiber.await()
     const slash = ctx.get('slash') as SlashService
@@ -153,6 +149,8 @@ describe('apply', () => {
     // …and fiber teardown releases it.
     await fiber.dispose()
     expect(() => slash.registerSource(rival)).not.toThrow()
+    expect(presentation.slots.entries('conversation.chat.toolview')).toHaveLength(0)
+    expect(presentation.localeDisposed).toBe(true)
   })
 })
 
diff --git a/packages/client/ui-skill/tests/skill-row.spec.tsx b/packages/client/ui-skill/tests/skill-row.spec.tsx
index 2dacf0a036..4143b4a7a2 100644
--- a/packages/client/ui-skill/tests/skill-row.spec.tsx
+++ b/packages/client/ui-skill/tests/skill-row.spec.tsx
@@ -53,7 +53,7 @@ describe('SkillRow', () => {
   it('renders a compact Bash-shaped summary and discloses the exact instructions', () => {
     const inspect = vi.fn()
     const view = render(<SkillRow {...props(settled(), inspect)} />)
-    const row = screen.getByRole('button', { name: 'Skill dsh-manage-issues' })
+    const row = screen.getByRole('button', { name: 'Skilldsh-manage-issues' })
     expect(row.getAttribute('aria-expanded')).toBe('false')
     expect(view.container.querySelector('[data-tool="skill"]')?.getAttribute('data-state')).toBe('ok')
     expect(view.container.querySelector('[data-tool="skill"] svg')?.getAttribute('width')).toBe('16')
@@ -97,7 +97,7 @@ describe('SkillRow', () => {
       isError: true,
       error: { name: 'SkillError', code: 'missing' },
     }))} />)
-    const row = screen.getByRole('button', { name: 'skill 加载失败 Skill SkillError: missing resource' })
+    const row = screen.getByRole('button', { name: 'skill 加载失败SkillSkillError: missing resource' })
     expect(view.container.querySelector('[data-tool="skill"]')?.getAttribute('data-state')).toBe('error')
     expect(row.textContent).not.toContain('Check SKILL.md.')
     fireEvent.click(row)
@@ -126,7 +126,7 @@ describe('SkillRow', () => {
       isError: true,
       error: { name: 'SkillError', code: 'missing' },
     }))} />)
-    const errorRow = screen.getByRole('button', { name: 'skill 加载失败 Skill SkillError: missing' })
+    const errorRow = screen.getByRole('button', { name: 'skill 加载失败SkillSkillError: missing' })
     fireEvent.click(errorRow)
     expect(screen.getAllByText('SkillError: missing')).toHaveLength(2)
   })
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 8ee0d81334..22342f8a24 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 00b9ea075af7eb55041d48ceb3a1363e9de90397
-README.zh.md: e62e3fa99c2908afeca85b7182701f6fcdf19de9
+README.md: 7f5d7b50cf86e251b73e2e67e38939827bd7eb13
+README.zh.md: 71b40929e065981c08a2d2b4fb1e941cbef687ff
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 00b9ea075a..7f5d7b50cf 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -12,7 +12,7 @@ The layering/protocol decisions are recorded in the [GUI layering and RPC protoc
 
 Question responses are validated against their pending request before the first answer claims it. A multi-select item may carry both requested option labels in `selected` and non-empty `custom` text; a single-select item must use one or the other. Duplicate labels, unknown labels, mismatched ids, incomplete batches, and empty custom text are rejected as `bad-response`.
 
-`session.history` reads an attached Session in memory or inspects a cold log through persistence without resuming or publishing an Agent, then pages on append-origin message boundaries. `maxMessages` counts `user/message` and `assistant/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it.
+`session.history` reads an attached Session in memory or inspects a cold log through persistence without resuming or publishing an Agent, then pages on append-origin message boundaries. `maxMessages` counts `user/message` and `assistant/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it. A `tool/result` entry additionally carries its paired call's name, exact arguments JSON, and event time as a transient history annotation derived from the complete log, so a page cut cannot erase keyed toolview dispatch, argument-derived summaries, or duration. Result render intents use that same complete-log pair; an orphan result or malformed arguments still soft-fall to the generic presentation path.
 
 `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index e62e3fa99c..71b40929e0 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -12,7 +12,7 @@
 
 首个回答认领待处理请求之前，系统会对照该请求校验问题响应。多选题的回答项可以同时携带 `selected` 中的请求选项标签与非空 `custom` 文本；单选题的回答项必须二选一。标签重复、标签未知、id 不匹配、批次不完整以及自定义文本为空都会以 `bad-response` 拒绝。
 
-`session.history` 按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
+`session.history` 按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。`tool/result` 条目还会携带其配对调用的名称、精确的 arguments JSON 和事件时间，作为从完整日志派生的瞬时 history 注解，因此分页切分无法抹掉键控 toolview 分派、由参数派生的摘要或耗时。结果渲染意图使用完整日志中的同一配对；无配对结果或参数损坏时，仍会软降级到通用呈现路径。
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 928ecc7b55..5b9511de93 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -26,7 +26,7 @@ import {
 // Type-only: brings the `ctx.tools` Context merge into this program (viewFor reads presenters).
 import type {} from '@deepseek-ai/dsh-tools'
 import type {
-  ApiProxy, CredentialView, GoalRef, HistoryEntry, HostFrame, ModelCatalogFailure, ModelProviderGroup,
+  ApiProxy, CredentialView, GoalRef, HistoryEntry, HistoryToolCall, HostFrame, ModelCatalogFailure, ModelProviderGroup,
   ModelReasoning, MuxFrame, QuestionResponsePayload, SessionProjectionsBlock, SessionSearchItem,
   QueuedInboxItem, SessionSummary, SettingsNamespaceView, SubagentAddress, ToolEventView,
   WorkspaceId, WorkspaceView,
@@ -408,9 +408,9 @@ function matchesQuestions(payload: QuestionResponsePayload, pending: PendingQues
  * Compute the render intent for a tool/call or tool/result event through the
  * presenters registered at this moment; every other event type gets none. A
  * result's presenter needs its call's parsed args — `argsFor` supplies them
- * (live: the per-session call table; history: an in-page backscan), returning
- * undefined when the pairing is unavailable (e.g. the call fell off the page),
- * which soft-falls to no view. Presenter or JSON.parse throws also soft-fall:
+ * (live: the per-session call table; history: the full-log pairing index),
+ * returning undefined when the pairing is unavailable, which soft-falls to no
+ * view. Presenter or JSON.parse throws also soft-fall:
  * the client's documented default (generic JSON card) covers every miss.
  */
 function viewFor(ctx: Context, event: SessionEvent, argsFor: (callId: string) => unknown): ToolEventView | undefined {
@@ -442,10 +442,8 @@ function viewFor(ctx: Context, event: SessionEvent, argsFor: (callId: string) =>
 }
 
 /**
- * Resolve a tool/result's call pairing by scanning a window of events backwards
- * for the matching tool/call. Used by the history path (the page is the
- * window — a cross-page pairing soft-falls to no view) and by live-path table
- * misses after a reconnect-eviction.
+ * Resolve a tool/result's call pairing by scanning a live session backwards
+ * for the matching tool/call after the open-call table missed.
  */
 function backscanArgs(events: readonly SessionEvent[], callId: string): { name: string; args: unknown } | undefined {
   for (let i = events.length - 1; i >= 0; i--) {
@@ -463,6 +461,34 @@ function backscanArgs(events: readonly SessionEvent[], callId: string): { name:
   return undefined
 }
 
+/** Index durable call metadata once so every history result keeps its pair across page cuts. */
+function historyCallIndex(events: readonly SessionEvent[]): ReadonlyMap<string, HistoryToolCall> {
+  const calls = new Map<string, HistoryToolCall>()
+  for (const event of events) {
+    if (event.type !== 'tool/call') continue
+    calls.set(String(event.data.callId), {
+      name: event.data.name,
+      arguments: event.data.arguments,
+      time: event.time,
+    })
+  }
+  return calls
+}
+
+/** Parse one indexed history pair for a result presenter, soft-falling malformed arguments. */
+function historyArgs(
+  calls: ReadonlyMap<string, HistoryToolCall>,
+  callId: string,
+): { name: string; args: unknown } | undefined {
+  const call = calls.get(callId)
+  if (call === undefined) return undefined
+  try {
+    return { name: call.name, args: JSON.parse(call.arguments) }
+  } catch {
+    return undefined
+  }
+}
+
 /** Render one detached history page through the same presenter path as ordinary history. */
 function historyPage(
   ctx: Context,
@@ -471,10 +497,18 @@ function historyPage(
   maxMessages: number | undefined,
 ): { events: HistoryEntry[]; hasMore: boolean } {
   const page = paginate(events, beforeSeq, maxMessages ?? DEFAULT_MAX_MESSAGES)
+  const calls = historyCallIndex(events)
   return {
     events: page.events.map((event) => {
-      const view = viewFor(ctx, event, callId => backscanArgs(page.events, callId))
-      return { event, ...view === undefined ? {} : { view } }
+      const view = viewFor(ctx, event, callId => historyArgs(calls, callId))
+      const call = event.type === 'tool/result'
+        ? calls.get(String(event.data.message.source.callId))
+        : undefined
+      return {
+        event,
+        ...view === undefined ? {} : { view },
+        ...call === undefined ? {} : { call },
+      }
     }),
     hasMore: page.hasMore,
   }
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index 4f10d92853..697e5bdeae 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -36,7 +36,7 @@ export interface ApiProxy {
 
 // ---- Domain interfaces and payload entities ----
 export type {
-  HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
+  HistoryEntry, HistoryToolCall, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
   ModelReasoningEffort, ModelTarget, QueueAction, SessionModels, SessionProjectionsBlock, SessionSearchItem,
   SessionsApi, SessionSummary,
 } from './sessions.ts'
diff --git a/packages/host/apiproxy/src/api/sessions.schema.ts b/packages/host/apiproxy/src/api/sessions.schema.ts
index 9f9c4329e6..f47289e77b 100644
--- a/packages/host/apiproxy/src/api/sessions.schema.ts
+++ b/packages/host/apiproxy/src/api/sessions.schema.ts
@@ -11,7 +11,7 @@ import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 import type {
-  HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
+  HistoryEntry, HistoryToolCall, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
   ModelReasoningEffort, ModelTarget, SessionProjectionsBlock, SessionSearchItem, SessionSummary,
 } from './sessions.ts'
 import type { ToolEventView } from './events.ts'
@@ -193,10 +193,18 @@ export const toolEventViewSchema = z.discriminatedUnion('for', [
   z.object({ for: z.literal('result'), view: z.looseObject({ card: z.string() }) }),
 ]) as unknown as z.ZodType<ToolEventView>
 
-/** One session.history item: the session event plus its optional host-computed tool view. */
+/** Paired tool/call metadata carried with a paged tool/result. */
+export const historyToolCallSchema: z.ZodType<Wire<HistoryToolCall>> = z.object({
+  name: z.string(),
+  arguments: z.string(),
+  time: z.number(),
+})
+
+/** One session.history item: raw event plus optional host-computed tool annotations. */
 export const historyEntrySchema: z.ZodType<Wire<HistoryEntry>> = z.object({
   event: sessionEventSchema,
   view: toolEventViewSchema.optional(),
+  call: historyToolCallSchema.optional(),
 }) as unknown as z.ZodType<Wire<HistoryEntry>>
 
 /**
diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts
index 18315eef19..2a6da96db9 100644
--- a/packages/host/apiproxy/src/api/sessions.ts
+++ b/packages/host/apiproxy/src/api/sessions.ts
@@ -26,14 +26,26 @@ declare module '@deepseek-ai/dsh-llm' {
   }
 }
 
+/** Paired tool/call metadata carried beside a paged result whose call may be outside the page. */
+export interface HistoryToolCall {
+  /** Registered tool name used for keyed presentation dispatch. */
+  name: string
+  /** Exact durable arguments JSON from the paired tool/call. */
+  arguments: string
+  /** Unix epoch ms of the paired tool/call event. */
+  time: number
+}
+
 /**
- * One history page entry: the raw event plus the optional host-computed render
- * intent (same semantics as the mux frame's `view` slot — a pagination-time
- * derivation, never persisted).
+ * One history page entry: the raw event plus optional host-computed render
+ * intent and result pairing. Both annotations are pagination-time derivations,
+ * never persisted; `call` preserves a tool/result's identity when its call
+ * event lies outside this page.
  */
 export interface HistoryEntry {
   event: SessionEvent
   view?: ToolEventView
+  call?: HistoryToolCall
 }
 
 /**
diff --git a/packages/host/apiproxy/tests/api-proxy-view.spec.ts b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
index 43083545db..3b19a26b5e 100644
--- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
@@ -231,9 +231,50 @@ describe('mux live view computation', () => {
       ]))
     expect(byKey.get('tool/call:h-term')?.view).toEqual({ for: 'call', view: { card: 'terminal', title: 'ls' } })
     expect(byKey.get('tool/result:h-term')?.view).toEqual({ for: 'result', view: { card: 'terminal', output: 'done' } })
+    expect(byKey.get('tool/result:h-term')?.call).toEqual({
+      name: 'term', arguments: '{"cmd":"ls"}', time: byKey.get('tool/call:h-term')?.event.time,
+    })
     expect('view' in (byKey.get('tool/result:h-orphan') ?? {})).toBe(false)
+    expect('call' in (byKey.get('tool/result:h-orphan') ?? {})).toBe(false)
     expect('view' in (byKey.get('tool/result:h-bad') ?? {})).toBe(false)
+    expect(byKey.get('tool/result:h-bad')?.call?.arguments).toBe('{broken')
     expect('view' in (byKey.get('tool/result:h-plain') ?? {})).toBe(false)
+    expect(byKey.get('tool/result:h-plain')?.call?.name).toBe('plain')
+  })
+
+  it('carries a result pair and computes its view when the call is outside the history page', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const session = ctx.sessions.create()
+    ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
+    session.append('turn/start', { turn: 1 })
+    const call = session.append('tool/call', {
+      turn: 1, step: 1, callId: CallId('cross-page'), name: 'term', arguments: '{"cmd":"tail"}',
+    })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    session.append('turn/start', { turn: 2 })
+    appendUserText(session, 'newer message cuts the page')
+    const result = session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        callId: CallId('cross-page'),
+        content: [{ type: 'text', text: 'late result' }],
+        isError: false,
+      }),
+    }, { surfaceOp: 'append' })
+
+    const response = await api.sessions.history({
+      rpcId: RpcId('t-hist-cross-page'),
+      payload: { sessionId: session.id, maxMessages: 1 },
+    })
+    if (!response.result.ok) throw new Error('unreachable')
+    const entries = response.result.value.events
+    expect(entries.some(entry => entry.event.seq === call.seq)).toBe(false)
+    const entry = entries.find(candidate => candidate.event.seq === result.seq)
+    expect(entry).toMatchObject({
+      call: { name: 'term', arguments: '{"cmd":"tail"}', time: call.time },
+      view: { for: 'result', view: { card: 'terminal', output: 'done' } },
+    })
   })
 
   it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
index b65861c1ae..3a76dd9b07 100644
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -190,10 +190,16 @@ describe('sessions domain schemas', () => {
     expect(sessionHistoryRequestSchema.parse({ sessionId: 's1', beforeSeq: 3, maxMessages: 5 }).beforeSeq).toBe(3)
     expect(() => sessionHistoryRequestSchema.parse({ sessionId: 's1', maxMessages: 0 })).toThrow()
     expect(sessionHistoryValueSchema.parse({
-      events: [],
+      events: [{
+        event: { type: 'tool/result', seq: 3, time: 30, data: {} },
+        call: { name: 'skill', arguments: '{"name":"review"}', time: 20 },
+      }],
       hasMore: false,
       modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-    }).hasMore).toBe(false)
+    })).toMatchObject({
+      events: [{ call: { name: 'skill', arguments: '{"name":"review"}', time: 20 } }],
+      hasMore: false,
+    })
     expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
     expect(sessionModelsValueSchema.parse({
       current: { provider: 'deepseek-official', model: 'deepseek-v4-flash', reasoningEffort: 'max' },

From ab94a2f7d6463ba640af5866c4b28908d5dde3b0 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Thu, 6 Aug 2026 17:39:43 +0800
Subject: [PATCH 058/516] refactor(telemetry): centralize the default mode

---
 docs/config-catalog.md                               |  2 +-
 .../telemetry/session-telemetry-otel/src/index.ts    | 12 ++++--------
 .../session-telemetry-otel/tests/otel.spec.ts        |  4 +++-
 3 files changed, 8 insertions(+), 10 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index c386ee4e6b..46766c2640 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1193,7 +1193,7 @@ export enum TelemetryMode {
 
 Depends on: `BatchLogRecordProcessorOptions` (`@opentelemetry/sdk-logs`) · `OTLPExporterNodeConfigBase` (`@opentelemetry/otlp-exporter-base`)
 
-Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:83`](../packages/telemetry/session-telemetry-otel/src/index.ts)
+Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:79`](../packages/telemetry/session-telemetry-otel/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title`
 
diff --git a/packages/telemetry/session-telemetry-otel/src/index.ts b/packages/telemetry/session-telemetry-otel/src/index.ts
index f380d97549..36429448c6 100644
--- a/packages/telemetry/session-telemetry-otel/src/index.ts
+++ b/packages/telemetry/session-telemetry-otel/src/index.ts
@@ -46,12 +46,8 @@ export enum TelemetryMode {
   DISABLED = 'DISABLED',
 }
 
-/** Supported session-sharing policies for runtime configuration validation. */
-export const TELEMETRY_MODES = [
-  TelemetryMode.FULL,
-  TelemetryMode.FEEDBACK_ONLY,
-  TelemetryMode.DISABLED,
-] as const
+/** Default session-sharing policy for schema and direct construction. */
+export const DEFAULT_TELEMETRY_MODE = TelemetryMode.FULL
 
 const DISABLED_FEEDBACK_WARNING = 'session telemetry is DISABLED; nothing will be shared and this feedback remains local'
 const NON_CANONICAL_FEEDBACK_WARNING = 'session telemetry ignored a feedback event absent from the canonical session log'
@@ -59,7 +55,7 @@ const DROP_RECORD: TelemetryBackend['emit'] = () => {}
 
 /** Resolve the default and reject unknown runtime values before transport setup. */
 function resolveMode(mode: TelemetryMode | undefined): TelemetryMode {
-  const resolved = mode ?? TelemetryMode.FULL
+  const resolved = mode ?? DEFAULT_TELEMETRY_MODE
   switch (resolved) {
     case TelemetryMode.FULL:
     case TelemetryMode.FEEDBACK_ONLY:
@@ -109,7 +105,7 @@ export interface Config {
  * axiom (and silently drop every field not re-declared).
  */
 export const Config: z<Config> = z.object({
-  mode: z.union(TELEMETRY_MODES).default(TelemetryMode.FULL),
+  mode: z.union(Object.values(TelemetryMode)).default(DEFAULT_TELEMETRY_MODE),
   exporter: z.any(),
   processor: z.any(),
 })
diff --git a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
index f7b3a007c9..f95af8db16 100644
--- a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
+++ b/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
@@ -13,7 +13,7 @@ import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { recordFeedback } from '@deepseek-ai/dsh-command-feedback'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import TelemetryOtel, { Config, TelemetryMode } from '../src/index.ts'
+import TelemetryOtel, { Config, DEFAULT_TELEMETRY_MODE, TelemetryMode } from '../src/index.ts'
 
 interface Capture {
   headers: import('node:http').IncomingHttpHeaders
@@ -330,6 +330,8 @@ describe('TelemetryOtel config fails loud', () => {
     expectTypeOf<Config['mode']>().toEqualTypeOf<TelemetryMode | undefined>()
     expectTypeOf<'FULL'>().not.toExtend<TelemetryMode>()
     expectTypeOf<TelemetryMode.FULL>().toExtend<TelemetryMode>()
+    expect(DEFAULT_TELEMETRY_MODE).toBe(TelemetryMode.FULL)
+    expect(Config({}).mode).toBe(DEFAULT_TELEMETRY_MODE)
   })
 
   it.each([

From 6515988ec7264331dc89b5746dea7e7a7ae51059 Mon Sep 17 00:00:00 2001
From: Jiaying Ding <silver.ding@deepseek.com>
Date: Thu, 6 Aug 2026 17:40:48 +0800
Subject: [PATCH 059/516] Update startup-auto-selection.e2e.ts

---
 apps/web/tests/startup-auto-selection.e2e.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/tests/startup-auto-selection.e2e.ts b/apps/web/tests/startup-auto-selection.e2e.ts
index f3a953c1e6..141a5b427c 100644
--- a/apps/web/tests/startup-auto-selection.e2e.ts
+++ b/apps/web/tests/startup-auto-selection.e2e.ts
@@ -103,7 +103,7 @@ describe('web e2e: startup auto-selection', () => {
     // seat with `visibility:hidden`, which Playwright reports as not visible).
     await page.waitForSelector(ROOT_PHASE, { timeout: 15_000 })
     expect(await page.locator(ROOT_PHASE).first().getAttribute('data-phase')).toBe('hero')
-    expect(await page.getByText("Let's start building").isVisible()).toBe(true)
+    expect(await page.getByText("Into the unknown").isVisible()).toBe(true)
     expect(await page.locator('textarea').first().isVisible()).toBe(true)
 
     releaseHistory()

From 9bb0aecb92a22a2472b76e5eb551dd4906164ee9 Mon Sep 17 00:00:00 2001
From: Jiaying Ding <silver.ding@deepseek.com>
Date: Thu, 6 Aug 2026 17:41:54 +0800
Subject: [PATCH 060/516] Update hmr-live.e2e.ts

---
 apps/web/tests/hmr-live.e2e.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/web/tests/hmr-live.e2e.ts b/apps/web/tests/hmr-live.e2e.ts
index df81a10402..385a516e7d 100644
--- a/apps/web/tests/hmr-live.e2e.ts
+++ b/apps/web/tests/hmr-live.e2e.ts
@@ -75,8 +75,8 @@ it('hot-reloads a real client-plugin source edit without refreshing the page', a
   if (!existsSync(binPath)) throw new Error('HMR browser test needs the built dsh bin; run pnpm run build first')
   const originalSource = await readFile(sourcePath)
   const originalBundle = await readFile(bundlePath)
-  const oldText = "Let's start building"
-  const sourceNeedle = "'hero.headline': 'Let\\'s start building'"
+  const oldText = "Into the unknown"
+  const sourceNeedle = "'hero.headline': 'Into the unknown'"
   const newText = `HMR UPDATED ${'x'.repeat(80)}`
   const updatedSource = originalSource.toString().replace(sourceNeedle, `'hero.headline': '${newText}'`)
   if (updatedSource === originalSource.toString()) throw new Error(`HMR source lacks ${JSON.stringify(sourceNeedle)}`)

From 9a9bfbf306bbf5f0c57cabf18c33f9a2d1ce7bb0 Mon Sep 17 00:00:00 2001
From: Jiaying Ding <silver.ding@deepseek.com>
Date: Thu, 6 Aug 2026 17:51:23 +0800
Subject: [PATCH 061/516] Update lifecycle-chrome.e2e.ts

---
 apps/web/tests/lifecycle-chrome.e2e.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index 8c81f55810..f37f02b6af 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -152,7 +152,7 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
     }
     // The blank frame renders the hero, not the resident composer: the
     // headline plus the guidance placeholder are the empty state's anchors.
-    await expect.poll(() => page.getByText("Let's start building", { exact: false }).count(), { timeout: 15_000 }).toBe(1)
+    await expect.poll(() => page.getByText("Into the unknown", { exact: false }).count(), { timeout: 15_000 }).toBe(1)
     const input = page.locator('textarea').first()
     await input.waitFor({ timeout: 10_000 })
     if (MODE !== 'record') {

From c22337a71e237b7ec617fbb65c3fe6d49c76f968 Mon Sep 17 00:00:00 2001
From: Jiaying Ding <silver.ding@deepseek.com>
Date: Thu, 6 Aug 2026 17:59:42 +0800
Subject: [PATCH 062/516] Update hero.expected.md

---
 apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md
index 728dc768f8..ad060c5d59 100644
--- a/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md
+++ b/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md
@@ -20,7 +20,7 @@
 - button "Settings":
   - img
   - text: Settings
-- text: Let's start building Preview
+- text: Into the unknown Preview
 - button "Choose workspace":
   - img
   - text: workspace

From 342229dc14fa90a418fd47b16312db4a051afdb5 Mon Sep 17 00:00:00 2001
From: Jiaying Ding <silver.ding@deepseek.com>
Date: Thu, 6 Aug 2026 18:02:23 +0800
Subject: [PATCH 063/516] Update plan-active.expected.md

---
 .../tests/snapshots/lifecycle-chrome/plan-active.expected.md    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md
index 6b4d7633e5..ce2ce36af0 100644
--- a/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md
+++ b/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md
@@ -20,7 +20,7 @@
 - button "Settings":
   - img
   - text: Settings
-- text: Let's start building Preview
+- text: Into the unknown Preview
 - button "Choose workspace":
   - img
   - text: workspace

From 2e943a16432e4572c87783efc43d0d7272daa64d Mon Sep 17 00:00:00 2001
From: Jiaying Ding <silver.ding@deepseek.com>
Date: Thu, 6 Aug 2026 18:31:44 +0800
Subject: [PATCH 064/516] Update details-session-lifecycle.e2e.ts

---
 apps/web/tests/details-session-lifecycle.e2e.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/tests/details-session-lifecycle.e2e.ts b/apps/web/tests/details-session-lifecycle.e2e.ts
index cb6c9ba914..5317c39009 100644
--- a/apps/web/tests/details-session-lifecycle.e2e.ts
+++ b/apps/web/tests/details-session-lifecycle.e2e.ts
@@ -121,7 +121,7 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S
     expect(await page.getByText('Details', { exact: true }).isVisible()).toBe(false)
 
     await page.getByRole('button', { name: /^(?:New session|新.*会话)$/ }).last().click()
-    await page.getByText("Let's start building", { exact: false }).waitFor({ timeout: 15_000 })
+    await page.getByText("Into the unknown", { exact: false }).waitFor({ timeout: 15_000 })
     await expect.poll(() => detailsTrack(page), { timeout: 5_000 }).toBe(0)
     expect(await page.getByText('Details', { exact: true }).isVisible()).toBe(false)
 

From 4dede454ed6ca776e7efa9ff5e57491348be5d26 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Thu, 6 Aug 2026 18:54:53 +0800
Subject: [PATCH 065/516] fix: address dsh badge review feedback

---
 .../feature/2026-07-05-skill-system.i18n.yaml        |  4 ++--
 .../implemented/feature/2026-07-05-skill-system.md   |  6 ++++--
 .../feature/2026-07-05-skill-system.zh.md            |  6 ++++--
 .../2026-08-06-bundled-dsh-badge-skill.i18n.yaml     |  4 ++--
 .../feature/2026-08-06-bundled-dsh-badge-skill.md    |  4 ++--
 .../feature/2026-08-06-bundled-dsh-badge-skill.zh.md |  6 +++---
 apps/cli/tests/dsh-badge.snapshot.ts                 |  4 +++-
 apps/cli/tests/fixtures/dsh-badge/snapshot.ts        |  2 +-
 docs/config-catalog.md                               |  2 +-
 docs/cordis-catalog/events.md                        |  2 +-
 docs/cordis-catalog/services.md                      |  2 +-
 docs/core-data-structures/skills.i18n.yaml           |  4 ++--
 docs/core-data-structures/skills.md                  |  8 +++++---
 docs/core-data-structures/skills.zh.md               |  8 +++++---
 docs/event-producer-consumer.md                      |  2 +-
 packages/skill/skill-badge/src/index.ts              | 12 ++++++------
 packages/skill/skill-local/src/index.ts              |  4 ++--
 packages/skill/skill/src/index.ts                    |  3 +++
 18 files changed, 48 insertions(+), 35 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index 6bb4aac193..a98beff699 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.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 .agents/notes/implemented/feature/2026-07-05-skill-system.md
-2026-07-05-skill-system.md: dd2fb1d22949f55ea7cb2c9f280e7cfbfcbbb226
-2026-07-05-skill-system.zh.md: 96656a8e1dfc2ae1ce7301ba29e7739349b6aab6
+2026-07-05-skill-system.md: a998d70ec934aed4bf7ce32aa711abd47b508a1d
+2026-07-05-skill-system.zh.md: 4fa7c4fd657c2f41f16b30679ec95e61a75f8a0c
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
index dd2fb1d229..a998d70ec9 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
@@ -14,9 +14,11 @@ DeepSeek Harness uses the same primitive so project-specific review, plugin-auth
 
 `@deepseek-ai/dsh-skill` is the pure provider registry (`ctx.skills`), `@deepseek-ai/dsh-skill-local` is the shipped local filesystem provider, and `@deepseek-ai/dsh-tool-skill` owns the durable session catalog and model-facing loader tool. `dsh-agent-spine-demo` loads the registry, local provider, and consumer by default so TUI, headless, and ACP apps get the same behavior while embedded or remote providers contribute skills without changing the registry or consumer. Its `skills` config forwards `registry`, `local`, and `tool` branches to those owners.
 
+Dedicated packaged providers can contribute immutable skills without filesystem discovery. The shipped CLI declares `@deepseek-ai/dsh-skill-badge` disabled by default; enabling its composition row contributes the official badge instructions through the same registry and consumer ([decision](2026-08-06-bundled-dsh-badge-skill.md)).
+
 Provider plugins register synchronously during `apply()`. Provider membership is direct effect-owned state: registration and disposal invalidate completed catalogs synchronously, and discovery reads the current provider map on demand rather than observing registry-change events. Provider catalogs return ranked candidates from awaited `list()` calls, where remote providers perform initialization, authentication, and discovery while honoring the lookup abort signal. The registry validates each candidate, resolves same-name skills first-wins by rank, provider registration order, and provider-local order, then sorts summaries by skill name for deterministic consumers. It caches only completed catalog snapshots and retries when a provider/runtime revision changes during discovery, so an unload cannot freeze a stale, unresolvable skill into a session catalog. Runtime `ctx.skills.register(...)` remains a convenience for embedded in-process skills and uses project-over-user priority; `runtime` is reserved as the registry-owned provider name.
 
-The local provider scans cwd-sensitive project roots, custom roots, and user roots in first-wins rank order: project `.dsh`, project `.agents`, `customSkillDirs`, user `.dsh`, then user `.agents`. The user `.dsh/skills` scan skips `.system` so a system-owned directory is not treated as normal user content. DeepSeek Harness does not ship built-in system skills; embedded or remote providers supply additional skills when configured.
+The local provider scans cwd-sensitive project roots, custom roots, and user roots in first-wins rank order: project `.dsh`, project `.agents`, `customSkillDirs`, user `.dsh`, then user `.agents`. The user `.dsh/skills` scan skips `.system` so a system-owned directory is not treated as normal user content. The local provider does not synthesize built-in system skills; configured bundled roots and dedicated providers supply additional skills.
 
 Each skill is either `<name>/SKILL.md` or `<name>.md` with YAML frontmatter. `name` and `description` are required; `whenToUse`, `metadata`, `disable-model-invocation`, and `user-invocable` are optional. Names are kebab-case. The invocation fields project into a typed nested policy as defined by the [independent model and user invocation decision](2026-07-28-skill-invocation-policy.md); the parser rejects the old camel-case spellings. YAML frontmatter is parsed with the `yaml` package instead of `js-yaml` or a hand-written parser: `yaml` is the already-declared modern parser for this package's limited frontmatter needs, and a narrow parser would either reject valid YAML users expect to work or grow into an unreviewed YAML subset.
 
@@ -48,7 +50,7 @@ The data structures and catalog/tool contract are documented in [skills.md](../.
 
 The agent-core spine includes one catalog contributor, one local provider, and one model-facing tool. Skill discovery is cwd-sensitive, so callers that create agents with different session cwd values can observe different project skill overrides by design.
 
-The catalog is deterministic for a fixed root set and runtime registration revision, but disk changes are not watched; discovery is memoized until runtime registration invalidates the cache or the process restarts.
+The catalog is deterministic for a fixed root set and runtime registration revision. The local provider watches configured roots and invalidates completed catalogs after relevant disk changes; runtime registration and provider disposal also invalidate them.
 
 ## Deferred
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 96656a8e1d..4fa7c4fd65 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -14,9 +14,11 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 `@deepseek-ai/dsh-skill` 是纯提供方注册表（`ctx.skills`），`@deepseek-ai/dsh-skill-local` 是随附的本地文件系统提供方，`@deepseek-ai/dsh-tool-skill` 负责持久化会话目录与面向模型的 loader 工具。`dsh-agent-spine-demo` 默认加载注册表、本地提供方和消费方，使 TUI、headless 与 ACP（Agent Client Protocol）应用获得相同行为，同时嵌入式或远程提供方可在不修改注册表或消费方的前提下贡献 skill。其 `skills` 配置将 `registry`、`local` 和 `tool` 分支分别转发给对应的所有者。
 
+专用的随包提供方可以贡献不可变的 skill，无需文件系统发现。交付的 CLI（命令行界面）默认将 `@deepseek-ai/dsh-skill-badge` 声明为禁用；启用其组合配置行，就会通过同一个注册表和消费方贡献官方徽章指令（见[决策](2026-08-06-bundled-dsh-badge-skill.md)）。
+
 提供方插件在 `apply()` 期间同步注册。提供方成员资格是由直接 effect 持有的状态：注册与 dispose（资源释放）同步地使已完成的目录失效，发现操作按需读取当前提供方映射而非监听注册表变更事件。提供方目录从等待的 `list()` 调用返回排序后的候选项，远程提供方在此过程中执行初始化、认证和发现，同时遵守查找的 abort 信号。注册表校验每个候选项，按排名、提供方注册顺序和提供方内部顺序以先到先得方式解决同名 skill 冲突，然后按 skill 名称排序摘要以保证消费方获得确定性结果。它仅缓存已完成的目录快照，并在发现过程中提供方/运行时修订版本发生变化时重试，因此卸载操作不会将一个陈旧且不可解析的 skill 冻结到会话目录中。运行时 `ctx.skills.register(...)` 仍作为嵌入式进程内 skill 的便捷方式保留，使用 project 优先于 user 的优先级；`runtime` 保留为注册表拥有的提供方名称。
 
-本地提供方按先到先得的排名顺序扫描 cwd 敏感的项目根目录、自定义根目录和用户根目录：项目 `.dsh`、项目 `.agents`、`customSkillDirs`、用户 `.dsh`，然后是用户 `.agents`。用户 `.dsh/skills` 扫描跳过 `.system`，以免系统拥有的目录被当作普通用户内容处理。DeepSeek Harness 不随附内置系统 skill；嵌入式或远程提供方在配置后提供额外 skill。
+本地提供方按先到先得的排名顺序扫描 cwd 敏感的项目根目录、自定义根目录和用户根目录：项目 `.dsh`、项目 `.agents`、`customSkillDirs`、用户 `.dsh`，然后是用户 `.agents`。用户 `.dsh/skills` 扫描跳过 `.system`，以免系统拥有的目录被当作普通用户内容处理。本地提供方不会合成内置系统 skill；已配置的 bundled 根目录和专用提供方会提供额外 skill。
 
 每个 skill 是 `<name>/SKILL.md` 或带 YAML frontmatter 的 `<name>.md`。`name` 和 `description` 为必填；`whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable` 为可选。名称采用 kebab-case。调用字段会投影到类型化的嵌套策略中，具体由[模型与用户独立调用决策](2026-07-28-skill-invocation-policy.md)定义；解析器会拒绝旧的驼峰拼写。YAML frontmatter 使用 `yaml` 包（package）解析，而非 `js-yaml` 或手写解析器：`yaml` 是本包有限 frontmatter 需求已声明的现代解析器，窄解析器要么拒绝用户预期可用的合法 YAML，要么膨胀为一个未经评审的 YAML 子集。
 
@@ -48,7 +50,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 agent-core 主干包含一个目录贡献者、一个本地提供方和一个面向模型的工具。Skill 发现是 cwd 敏感的，因此以不同会话 cwd 值创建 agent 的调用方可以按设计观察到不同的项目 skill 覆盖。
 
-目录对于固定的根目录集合和运行时注册修订版本是确定性的，但不监视磁盘变化；发现结果被缓存，直到运行时注册使缓存失效或进程重启。
+目录对于固定的根目录集合和运行时注册修订版本是确定性的。本地提供方会监视已配置的根目录，并在发生相关磁盘变化后使已完成的目录失效；运行时注册和提供方释放也会使其失效。
 
 ## 延后
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
index bdc103ef46..222ed1ebbe 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.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 .agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
-2026-08-06-bundled-dsh-badge-skill.md: afe0b21d64a414a9e78ef55459a42c0d3817e3fd
-2026-08-06-bundled-dsh-badge-skill.zh.md: de1ec989570b07987b12f0a291c84643aa5531fd
+2026-08-06-bundled-dsh-badge-skill.md: 512f67ca347ca311a1f80fef932f6af8c91b0fe9
+2026-08-06-bundled-dsh-badge-skill.zh.md: 88fcadf66944cb91419441be3916ae04968be663
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
index afe0b21d64..512f67ca34 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-06-bundled-dsh-badge-skill.zh.md)
 
 ## Problem
 
-DeepSeek Harness has an official attribution badge skill, but keeping it only in a developer's personal skill directory makes it unavailable to other DSH installations and gives the shipped application no explicit opt-in point.
+The [Cordis tutorial](../../../../docs/cordis-tutorial/index.md) uses an official “powered by dsh” badge across its pages, but the shipped CLI has no reusable instructions or explicit opt-in provider for applying the same attribution elsewhere.
 
 ## Decision
 
@@ -18,7 +18,7 @@ The provider uses the bundled rank after project, custom, and user filesystem so
 
 ## Alternatives considered
 
-A Codex marketplace plugin was rejected because it would install into a different runtime and would not participate in DSH's `ctx.skills` seam. Mounting `dsh-skill-local` over the packaged files was rejected because filesystem discovery, parsing, and watching add lifecycle machinery that an immutable single-skill provider does not need.
+**Mount packaged files through `dsh-skill-local`.** Rejected because filesystem discovery, parsing, and watching add lifecycle machinery that an immutable single-skill provider does not need.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
index de1ec98957..88fcadf669 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
@@ -6,19 +6,19 @@ Status: implemented
 
 ## 问题
 
-DeepSeek Harness 已有官方署名徽章 skill（技能），但如果它只保存在某位开发者的个人 skill 目录中，其他 DSH 安装实例便无法使用，交付的应用也没有显式的选择加入点。
+[Cordis 教程](../../../../docs/cordis-tutorial/index.md)的各个页面都使用官方「powered by dsh」徽章，但交付的 CLI（命令行界面）既没有用于在其他位置应用同样署名的可复用指令，也没有可显式选择加入的提供方。
 
 ## 决策
 
 `@deepseek-ai/dsh-skill-badge` 是一个原生 Cordis 插件，会在 `ctx.skills` 上注册一个不可变的内置提供方。该提供方负责 `dsh-badge` 的摘要、指令正文和 PNG 资源基底；`dsh-tool-skill` 仍是面向模型的目录与 loader 渲染的唯一归属方。
 
-交付的 CLI（命令行界面）组合将 `skill-badge` 声明为禁用。启用这个现有配置行就是显式选择加入；禁用它的安装实例不会公开任何徽章 skill，也不会获得任何模型可见内容。
+交付的 CLI 组合将 `skill-badge` 声明为禁用。启用这个现有配置行就是显式选择加入；禁用它的安装实例不会公开任何徽章 skill（技能），也不会获得任何模型可见内容。
 
 该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank，因此用户自有的 `dsh-badge` 定义可通过注册表的常规优先级契约覆盖它。提供方释放时，注册表拥有的 effect 会移除该贡献。
 
 ## 曾考虑的替代方案
 
-未采用 Codex marketplace 插件，因为它会安装到不同的运行时，无法参与 DSH 的 `ctx.skills` seam。未采用使用 `dsh-skill-local` 挂载随包文件的方案，因为文件系统发现、解析和监视会引入不必要的生命周期机制，而不可变的单一 skill 提供方并不需要这些机制。
+**通过 `dsh-skill-local` 挂载随包文件。** 否决，因为文件系统发现、解析和监视会引入生命周期机制，而不可变的单一 skill 提供方并不需要这些机制。
 
 ## 后果
 
diff --git a/apps/cli/tests/dsh-badge.snapshot.ts b/apps/cli/tests/dsh-badge.snapshot.ts
index d78f4c743d..abd66e6f79 100644
--- a/apps/cli/tests/dsh-badge.snapshot.ts
+++ b/apps/cli/tests/dsh-badge.snapshot.ts
@@ -34,6 +34,7 @@ describe('dsh badge assembled snapshot', () => {
     expect(enabled.stderr).toBe('')
     expect(disabledSnapshot).toMatchInlineSnapshot(`
       {
+        "catalog": null,
         "result": {
           "content": [
             {
@@ -46,6 +47,7 @@ describe('dsh badge assembled snapshot', () => {
           },
           "isError": true,
         },
+        "summary": null,
       }
     `)
     expect(enabledSnapshot).toMatchInlineSnapshot(`
@@ -169,5 +171,5 @@ describe('dsh badge assembled snapshot', () => {
         },
       }
     `)
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS * 2)
 })
diff --git a/apps/cli/tests/fixtures/dsh-badge/snapshot.ts b/apps/cli/tests/fixtures/dsh-badge/snapshot.ts
index 99379b4fe4..0bf4a92c8b 100644
--- a/apps/cli/tests/fixtures/dsh-badge/snapshot.ts
+++ b/apps/cli/tests/fixtures/dsh-badge/snapshot.ts
@@ -47,7 +47,7 @@ try {
     arguments: { name: 'dsh-badge' },
     signal: new AbortController().signal,
   })
-  process.stdout.write(`${JSON.stringify({ catalog, summary, result })}\n`)
+  process.stdout.write(`${JSON.stringify({ catalog: catalog ?? null, summary: summary ?? null, result })}\n`)
 } finally {
   await ctx.fiber.dispose()
 }
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 449addad8a..0cfc956221 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1372,7 +1372,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/skill/skill/src/index.ts:170`](../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:173`](../packages/skill/skill/src/index.ts)
 
 ## `@deepseek-ai/dsh-skill-local`
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 5044b0e5ce..cd54572d91 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -670,7 +670,7 @@ A skill provider, runtime contribution, or provider-backed catalog may have chan
 'skills/change'(): void
 ```
 
-Source: [`packages/skill/skill/src/index.ts:188`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:191`](../../packages/skill/skill/src/index.ts)
 
 ## `subagent/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index b3d81d61b9..2df5bbeb0a 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -1897,7 +1897,7 @@ async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefiniti
 
 Types: [SkillCatalogSnapshot](../core-data-structures/skills.md) · [SkillDefinition](../core-data-structures/skills.md) · [SkillLookupOptions](../core-data-structures/skills.md) · [SkillProvider](../core-data-structures/skills.md) · [SkillProviderControl](../core-data-structures/skills.md) · [SkillRegistration](../core-data-structures/skills.md) · [SkillSummary](../core-data-structures/skills.md)
 
-Source: [`packages/skill/skill/src/index.ts:209`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:212`](../../packages/skill/skill/src/index.ts)
 
 ## `ctx.spillStore` — `SpillStore` (abstract seam)
 
diff --git a/docs/core-data-structures/skills.i18n.yaml b/docs/core-data-structures/skills.i18n.yaml
index ea1c7a28bb..d0ce7b7574 100644
--- a/docs/core-data-structures/skills.i18n.yaml
+++ b/docs/core-data-structures/skills.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 docs/core-data-structures/skills.md
-skills.md: 16e6fb649f9db4d7be47468adf0bf8a00df428c3
-skills.zh.md: 7d69b84f7be200b795e7a58eb3de1f029a8024f5
+skills.md: d862cbc07135680c2377b4c8c82c80d055344221
+skills.zh.md: 3f8c034ec2aa24b4acdbbc1e2ac27717c21649d5
diff --git a/docs/core-data-structures/skills.md b/docs/core-data-structures/skills.md
index 16e6fb649f..d862cbc071 100644
--- a/docs/core-data-structures/skills.md
+++ b/docs/core-data-structures/skills.md
@@ -2,9 +2,9 @@
 
 English | [中文](skills.zh.md)
 
-The [skill capability family](../../packages/skill) is split across three packages: the registry ([dsh-skill](../../packages/skill/skill), `ctx.skills`) merges provider catalogs; the local provider ([dsh-skill-local](../../packages/skill/skill-local)) scans and watches project/custom/user directories; the consumer ([dsh-tool-skill](../../packages/skill/tool-skill)) owns the initial and replacement catalogs plus the model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
+The [skill capability family](../../packages/skill) includes the registry ([dsh-skill](../../packages/skill/skill), `ctx.skills`), the local provider ([dsh-skill-local](../../packages/skill/skill-local)), the optional packaged badge provider ([dsh-skill-badge](../../packages/skill/skill-badge)), and the consumer ([dsh-tool-skill](../../packages/skill/tool-skill)). The registry merges provider catalogs; providers contribute local or packaged skills; the consumer owns the initial and replacement catalogs plus the model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
 
-Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts), [`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts), and [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts).
+Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts), [`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts), [`packages/skill/skill-badge/src/index.ts`](../../packages/skill/skill-badge/src/index.ts), and [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts).
 
 ## Provider registry
 
@@ -72,7 +72,9 @@ The shipped local provider scans roots in rank order:
 | 500 | `user-agents` | `<agentsHome>/skills` |
 | 600 | `bundled` | `Config.bundledSkillDir` when configured |
 
-The project root is the nearest ancestor containing `.git`; without one, the current cwd is used. When `ctx.fs` is available, the git-root walk probes `.git` through the filesystem service so remote or sandboxed workspaces do not fall back to the host filesystem boundary. The user DSH root skips its `.system` child. The local provider does not ship built-in system skills; deployments supply built-ins through another provider.
+The project root is the nearest ancestor containing `.git`; without one, the current cwd is used. When `ctx.fs` is available, the git-root walk probes `.git` through the filesystem service so remote or sandboxed workspaces do not fall back to the host filesystem boundary. The user DSH root skips its `.system` child. The local provider does not synthesize built-in system skills; deployments supply packaged skills through configured bundled roots or dedicated providers.
+
+`dsh-skill-badge` registers one immutable `bundled` candidate at `BUNDLED_SKILL_RANK` and exposes its packaged asset directory through `resourceBase`. The shipped CLI declares the plugin disabled, so enabling its composition row is an explicit opt-in.
 
 Chokidar watches existing roots for direct bundle/flat-entry additions and removals plus direct skill-entry changes. A missing root is followed one absent path segment at a time from its nearest existing ancestor until Chokidar can attach. Resource files below a bundle are not catalog changes. Model-facing `write` and `edit` observations synchronously invalidate the provider when their target is catalog-relevant, while the host watcher covers IDE, Git, shell, and external-process mutations. Watcher failures make the current observation incomplete without hiding readable candidates from direct loads; project-scoped watchers use a configured bounded LRU.
 
diff --git a/docs/core-data-structures/skills.zh.md b/docs/core-data-structures/skills.zh.md
index 7d69b84f7b..3f8c034ec2 100644
--- a/docs/core-data-structures/skills.zh.md
+++ b/docs/core-data-structures/skills.zh.md
@@ -2,9 +2,9 @@
 
 [English](skills.md) | 中文
 
-[skill（技能）能力族](../../packages/skill) 拆分为三个包：注册表（[dsh-skill](../../packages/skill/skill)，`ctx.skills`）合并各提供方的目录；本地提供方（[dsh-skill-local](../../packages/skill/skill-local)）扫描并监视项目、自定义和用户目录；消费方（[dsh-tool-skill](../../packages/skill/tool-skill)）拥有初始目录和替换目录，以及面向模型的 `skill` 工具。skill 是可选的指令而非会话事件，因此其词汇定义在此处而非 [core.md](core.md)。
+[skill（技能）能力族](../../packages/skill) 包含注册表（[dsh-skill](../../packages/skill/skill)，`ctx.skills`）、本地提供方（[dsh-skill-local](../../packages/skill/skill-local)）、可选的随包徽章提供方（[dsh-skill-badge](../../packages/skill/skill-badge)）和消费方（[dsh-tool-skill](../../packages/skill/tool-skill)）。注册表合并各提供方的目录；提供方贡献本地或随包 skill；消费方拥有初始目录和替换目录，以及面向模型的 `skill` 工具。skill 是可选的指令而非会话事件，因此其词汇定义在此处而非 [core.md](core.md)。
 
-源码：[`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts)、[`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts) 与 [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts)。
+源码：[`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts)、[`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts)、[`packages/skill/skill-badge/src/index.ts`](../../packages/skill/skill-badge/src/index.ts) 与 [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts)。
 
 ## 提供方注册表
 
@@ -72,7 +72,9 @@ interface SkillProviderControl {
 | 500 | `user-agents` | `<agentsHome>/skills` |
 | 600 | `bundled` | 配置了 `Config.bundledSkillDir` 时使用该目录 |
 
-项目根目录为包含 `.git` 的最近祖先目录；找不到时使用当前 cwd。当 `ctx.fs` 可用时，git-root 向上查找通过文件系统服务探测 `.git`，使远程或沙箱工作区不会回退到宿主文件系统边界。用户 DSH 根目录会跳过其 `.system` 子目录。本地提供方不附带内置系统 skill；部署方通过另一个提供方提供内置 skill。
+项目根目录为包含 `.git` 的最近祖先目录；找不到时使用当前 cwd。当 `ctx.fs` 可用时，git-root 向上查找通过文件系统服务探测 `.git`，使远程或沙箱工作区不会回退到宿主文件系统边界。用户 DSH 根目录会跳过其 `.system` 子目录。本地提供方不会合成内置系统 skill；部署方通过已配置的 bundled 根目录或专用提供方提供随包 skill。
+
+`dsh-skill-badge` 在 `BUNDLED_SKILL_RANK` 注册一个不可变的 `bundled` 候选项，并通过 `resourceBase` 公开其随包资产目录。交付的 CLI（命令行界面）将该插件声明为禁用，因此启用其组合配置行即为显式选择加入。
 
 Chokidar 会监视现有根目录中直属 bundle 和平铺条目的添加与移除，以及直属 skill 条目的变更。缺失的根目录会从最近的现有祖先开始，逐个跟踪缺失路径段，直至 Chokidar 可以附加。bundle 下的资源文件变更不属于目录变更。面向模型的 `write` 和 `edit` 观测会在目标路径相关时同步使提供方目录失效，而宿主 watcher 覆盖 IDE、Git、shell 和外部进程产生的变更。watcher 失败会使当前观测不完整，但不会在直接加载时隐藏可读候选项；项目作用域 watcher 使用按配置设限的 LRU。
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 2377ca0d69..bdf52f0bc5 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -36,7 +36,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:104`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:150`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:137`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
-| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:188`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
+| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:191`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:160`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:134`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
diff --git a/packages/skill/skill-badge/src/index.ts b/packages/skill/skill-badge/src/index.ts
index 27cfd29354..9cff2070fb 100644
--- a/packages/skill/skill-badge/src/index.ts
+++ b/packages/skill/skill-badge/src/index.ts
@@ -7,14 +7,14 @@
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import type { Context } from 'cordis'
-import type {
-  SkillCandidate,
-  SkillDefinition,
-  SkillProvider,
+import {
+  BUNDLED_SKILL_RANK,
+  type SkillCandidate,
+  type SkillDefinition,
+  type SkillProvider,
 } from '@deepseek-ai/dsh-skill'
 
 const PROVIDER_NAME = 'dsh-badge'
-const BUNDLED_RANK = 600
 const SKILL_BODY_URL = new URL('../assets/dsh-badge.md', import.meta.url)
 const RESOURCE_BASE = {
   kind: 'directory',
@@ -29,7 +29,7 @@ const CANDIDATE: SkillCandidate = {
   provider: PROVIDER_NAME,
   source: 'bundled',
   resourceBase: RESOURCE_BASE,
-  rank: BUNDLED_RANK,
+  rank: BUNDLED_SKILL_RANK,
   locator: SKILL_BODY_URL,
 }
 
diff --git a/packages/skill/skill-local/src/index.ts b/packages/skill/skill-local/src/index.ts
index d6df41237e..71ed3be21d 100644
--- a/packages/skill/skill-local/src/index.ts
+++ b/packages/skill/skill-local/src/index.ts
@@ -21,6 +21,7 @@ import { parse as parseYaml } from 'yaml'
 import type { FileSystem, FsDirEntry, FsTarget } from '@deepseek-ai/dsh-fs'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import {
+  BUNDLED_SKILL_RANK,
   isSkillName,
   type SkillCandidate,
   type SkillDefinition,
@@ -40,7 +41,6 @@ const USER_AGENTS_RANK = 500
 const DEFAULT_WATCH_STABILITY_THRESHOLD_MS = 200
 const DEFAULT_WATCH_POLL_INTERVAL_MS = 100
 const DEFAULT_WATCH_MAX_PROJECTS = 128
-const BUNDLED_RANK = 600
 
 export const name = 'skill-local'
 export const inject = ['skills']
@@ -256,7 +256,7 @@ export class LocalSkillProvider implements SkillProvider {
       )
     }
     if (this.bundledSkillDir !== undefined) {
-      roots.push({ path: this.bundledSkillDir, source: 'bundled', rank: BUNDLED_RANK, trustedHost: true })
+      roots.push({ path: this.bundledSkillDir, source: 'bundled', rank: BUNDLED_SKILL_RANK, trustedHost: true })
     }
     return roots
   }
diff --git a/packages/skill/skill/src/index.ts b/packages/skill/skill/src/index.ts
index 32f7112542..139b72bc8a 100644
--- a/packages/skill/skill/src/index.ts
+++ b/packages/skill/skill/src/index.ts
@@ -19,6 +19,9 @@ const MAX_COLLECT_ATTEMPTS = 2
 const RUNTIME_PROVIDER = 'runtime'
 const RUNTIME_RANK = 250
 
+/** Standard precedence rank for packaged skill providers and local bundled roots. */
+export const BUNDLED_SKILL_RANK = 600
+
 /**
  * Return whether a string is a valid kebab-case skill name.
  * @param name - candidate skill name to validate.

From 318142ebe9aaef1bcf27c3949f8f59b1557c21e4 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 19:21:04 +0800
Subject: [PATCH 066/516] docs(user): add a model-provider configuration guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The guide tier said how to compose plugins with `cordis.yml` but never how to
reach a provider other than DeepSeek, so the two things a person actually does
— give a catalog provider its key from the Models page, and declare a gateway
the installed catalog does not ship — had no home outside package READMEs.

The new page covers both entry points and the relationship between them: the
Models page and `$DSH_HOME/settings.yaml` write one document, over a
`llm-pi-ai` adapter that mounts dormant until that document names routes. It
carries the settings shape, catalog replacement and its capacity fallbacks,
credential references, and the four failures a misconfigured route produces,
and links the generated config catalog for exhaustive fields.

It sits between Quick start and Configuration in the guide sidebar, which is
where a reader hits the question.
---
 docs/user/guide/providers.i18n.yaml  |   6 ++
 docs/user/guide/providers.md         | 113 +++++++++++++++++++++++++++
 docs/user/guide/providers.zh.md      | 113 +++++++++++++++++++++++++++
 docs/user/guide/quickstart.i18n.yaml |   4 +-
 docs/user/guide/quickstart.md        |   1 +
 docs/user/guide/quickstart.zh.md     |   1 +
 website/docs.ts                      |  10 ++-
 7 files changed, 245 insertions(+), 3 deletions(-)
 create mode 100644 docs/user/guide/providers.i18n.yaml
 create mode 100644 docs/user/guide/providers.md
 create mode 100644 docs/user/guide/providers.zh.md

diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
new file mode 100644
index 0000000000..04b27adb51
--- /dev/null
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
+providers.md: 2ae1093699d8eb26171a2403db155113d84e437e
+providers.zh.md: 6ce513c659140ed18716bd5c8f75c428ad981f2b
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
new file mode 100644
index 0000000000..2ae1093699
--- /dev/null
+++ b/docs/user/guide/providers.md
@@ -0,0 +1,113 @@
+# Configure model providers
+
+English | [中文](providers.zh.md)
+
+Harness ships with DeepSeek and mounts a generic multi-provider adapter alongside it, for the providers in pi-ai's installed catalog — Anthropic, OpenAI, and the rest — and for any OpenAI-compatible gateway or self-hosted server. You have two entry points: the **Models** page in the web UI, and `$DSH_HOME/settings.yaml`. Both write the same document, and a change takes effect on the next request without a restart.
+
+## Where providers come from
+
+`cordis.yml` decides which **adapters** are installed; the settings document decides which **providers** run. The shipped composition carries two LLM adapters:
+
+- `llm-deepseek` serves the `deepseek-official` route, the one available out of the box.
+- `llm-pi-ai` mounts **dormant**: zero routes and no extra entries in the model picker until an `llm-pi-ai:` settings section supplies provider profiles, at which point those routes register live and drop again when the section empties.
+
+Adding a provider therefore rarely means editing `cordis.yml` — writing settings is enough, and that is exactly what the Models page does.
+
+## Configure from the web UI
+
+Start `pnpm run dsh web` and open **Settings → Models**.
+
+**Give DeepSeek its key.** The DeepSeek card carries one API-key field; fill it in, save, and the provider is ready.
+
+**Add a provider from the installed catalog.** Choose **Add provider**, pick one of pi-ai's catalog providers (anthropic, openai, and so on), and enter that provider's API key. The endpoint, protocol, and model catalog all come from the catalog; the key is the only thing you owe.
+
+**Add a custom provider.** Choose **Add a custom provider** for a route the catalog does not ship — a company gateway, a self-hosted server, or a provider newer than the installed catalog. It asks for a Provider ID (the lowercase identifier that names the route in requests and as its credential), a base URL, a protocol, and at least one model.
+
+**Let the endpoint report its models.** Expand **Model catalog** and choose **Fetch available models**: the interrogation asks the endpoint **the form currently shows** — including a base URL edited but not yet saved and a key typed but not yet stored — and offers what it reports as candidates to pick from. A route the installed catalog describes is answered from that catalog with no network call. Adopting a candidate only writes rows into the draft; nothing is stored until you save.
+
+Keys are write-only: the page only ever holds a redacted descriptor, never the literal secret. A key you enter is stored in `$DSH_HOME/.env`, and the profile records only the variable name that references it.
+
+## settings.yaml for advanced configuration
+
+The document lives at `$DSH_HOME/settings.yaml` (`$DSH_HOME` defaults to `~/.dsh`). The Models page writes this file, and you can edit it directly; neither source outranks the other.
+
+```yaml
+llm-deepseek:
+  reasoningEffort: high
+
+llm-pi-ai:
+  providers:
+    # Catalog route: endpoint, protocol, and models come from pi-ai; you supply
+    # the credential.
+    openai:
+      apiKeyEnv: OPENAI_API_KEY
+
+    # Also a catalog route, moved to a private proxy, with its catalog narrowed
+    # to one model and that model's capacity corrected. Every unset field still
+    # comes from the catalog.
+    anthropic:
+      apiKeyEnv: ANTHROPIC_API_KEY
+      baseURL: https://proxy.example.com:8443
+      reasoning: high
+      models:
+        - id: claude-sonnet-4-5
+          contextWindow: 200000
+
+    # Hand-declared route: pi-ai ships nothing under this key, so the profile
+    # supplies the whole provider.
+    acme-gateway:
+      displayName: Acme Gateway
+      apiKeyEnv: ACME_GATEWAY_API_KEY
+      api: openai-completions
+      baseURL: https://gateway.acme.example/v1
+      models:
+        - id: acme-large
+          name: Acme Large
+          contextWindow: 65536
+          maxTokens: 4096
+```
+
+A settings section merges over the matching `cordis.yml` configuration **per provider**, so you can override one field of one route and leave the rest as the composition set them.
+
+A profile the adapter could not serve is refused **where it is written**: a hand-declared route needs `api`, `baseURL`, and at least one model, and a profile missing any of them fails naming the offending route and model rather than being stored and quietly disabling the whole namespace. When an already-stored document is broken by an external edit, settings keeps the last good value and warns.
+
+## The model catalog
+
+A profile's `models` list *replaces* that route's installed catalog rather than extending it; omitting it or leaving it empty serves the catalog unchanged. Each entry defaults its unset fields from the installed model of the same `id`, so narrowing a route to two models, correcting one capacity, or adding a model newer than the installed catalog are each a one-line edit.
+
+Only the four fields the harness consumes are configurable: `id`, `name`, `contextWindow`, and `maxTokens`. Pricing and input modalities have no consumer, and reasoning is not per-model configurable at all — it rides the installed catalog entry.
+
+A model neither the entry nor the catalog sizes takes the route's `defaultContextWindow` (262,144) and `defaultMaxTokens` (32,768). Both are guesses by construction, which is why they are route fields: a deployment whose gateway serves smaller models corrects them once.
+
+Model ids are not lifecycle configuration. Requesting a model the route does not configure fails with `UNKNOWN_MODEL` before any provider request goes out.
+
+## Credentials
+
+Prefer `apiKeyEnv`: it is a *reference* resolved per request, so no secret enters the configuration file. A literal `apiKey` is the escape hatch. Omitting both is what leaves a route unauthenticated, which for a catalog route means pi-ai's own environment discovery. A reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` rather than falling through to whatever unrelated key the environment happens to hold.
+
+References resolve from `$DSH_HOME/.env` — what the Models page's key fields write — and from the matching environment variable when no credential service is mounted. One credential serves every model on its route.
+
+## Point an agent at the new provider
+
+A configured route appears in the web model picker and can be switched at any time. To change the default, edit the `agent-loop` entry's `provider` and `model` in `cordis.yml`:
+
+```yaml
+- id: agent-loop
+  name: '@deepseek-ai/dsh-agent-loop'
+  config:
+    agents:
+      - id: main
+        provider: acme-gateway
+        model: acme-large
+```
+
+## Troubleshooting
+
+- **`MISSING_CREDENTIAL`** — the variable the profile's `apiKeyEnv` names holds no value. Store the key once through the Models page, or export the variable.
+- **`UNKNOWN_MODEL`** — the requested model is not in the route's configured catalog. Add it to `models`, or use an id the catalog already carries.
+- **`settings-rejected`** — the written profile cannot be served, and the message names the route and model. For a hand-declared route, check that `api`, `baseURL`, and `models` are all present.
+- **Fetching available models answers 401** — the endpoint refused the interrogation. Check the key; if the base URL points at an Anthropic-style gateway, note that the interrogation reads only the OpenAI-compatible `GET /models`, so enter the models by hand instead.
+
+## Exact field reference
+
+The complete fields, types, and defaults each plugin currently supports live in the generated [plugin configuration catalog](../../config-catalog.md). Each adapter's own semantics belong to its README: [`dsh-llm-pi-ai`](../../../packages/llm/llm-pi-ai/README.md) and [`dsh-llm-deepseek`](../../../packages/llm/llm-deepseek/README.md). For `cordis.yml` itself, see [Configuration](./config.md).
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
new file mode 100644
index 0000000000..6ce513c659
--- /dev/null
+++ b/docs/user/guide/providers.zh.md
@@ -0,0 +1,113 @@
+# 配置模型提供方
+
+[English](providers.md) | 中文
+
+Harness 出厂就带 DeepSeek，同时挂着一个通用的多提供方适配器，用来接入 Anthropic、OpenAI 这类内置目录里的提供方，或任何 OpenAI 兼容的网关与自建服务。你有两个入口：Web 界面的**模型**页，以及 `$DSH_HOME/settings.yaml`。两者写的是同一份文档，改完下一次请求即生效，不用重启。
+
+## 提供方从哪里来
+
+`cordis.yml` 决定装了哪些**适配器**，settings 文档决定跑哪些**提供方**。出厂组合里有两个 LLM 适配器：
+
+- `llm-deepseek` 提供 `deepseek-official` 路由，是默认可用的那个。
+- `llm-pi-ai` 以**休眠**状态挂载：零路由，模型选择器里也不会多出条目，直到 settings 里的 `llm-pi-ai:` 段落给出 provider profile，路由才注册上来；段落清空则一并撤下。
+
+因此新增一个提供方通常不需要改 `cordis.yml`，写 settings 就够了——而模型页做的正是这件事。
+
+## 在 Web 界面里配置
+
+启动 `pnpm run dsh web`，打开**设置 → 模型**。
+
+**填 DeepSeek 的密钥。** DeepSeek 卡片上只有一个 API 密钥输入框，填好保存即可开始用。
+
+**添加内置目录里的提供方。** 点**添加提供方**，从 pi-ai 内置目录中选一个（anthropic、openai 等），填入该提供方的 API 密钥。端点、协议和模型目录都由内置目录提供，你只需要给密钥。
+
+**添加自定义提供方。** 点**添加自定义提供方**，用于内置目录没有的路由——公司网关、自建服务，或比内置目录更新的提供方。需要填 Provider ID（请求里点名它、也作为凭据名的小写标识）、API 地址、协议，以及至少一个模型。
+
+**让端点自己报模型。** 展开**模型目录**后点**获取可用模型**，会按你**当前表单里**的地址与密钥去问端点（地址改了但没保存、密钥刚输入还没存下，都算数），把它报告的模型列成候选让你勾选。内置目录里的路由直接由目录作答，不联网。采纳只是把行写进草稿，最终还是你点保存才落盘。
+
+密钥是只写的：页面拿到的永远是脱敏描述符，不是明文。写入的密钥存进 `$DSH_HOME/.env`，profile 里只记录引用它的变量名。
+
+## settings.yaml：进阶配置
+
+文档位于 `$DSH_HOME/settings.yaml`（`$DSH_HOME` 默认是 `~/.dsh`）。模型页写的就是这个文件，你也可以直接编辑它——两个来源没有主次之分。
+
+```yaml
+llm-deepseek:
+  reasoningEffort: high
+
+llm-pi-ai:
+  providers:
+    # Catalog route: endpoint, protocol, and models come from pi-ai; you supply
+    # the credential.
+    openai:
+      apiKeyEnv: OPENAI_API_KEY
+
+    # Also a catalog route, moved to a private proxy, with its catalog narrowed
+    # to one model and that model's capacity corrected. Every unset field still
+    # comes from the catalog.
+    anthropic:
+      apiKeyEnv: ANTHROPIC_API_KEY
+      baseURL: https://proxy.example.com:8443
+      reasoning: high
+      models:
+        - id: claude-sonnet-4-5
+          contextWindow: 200000
+
+    # Hand-declared route: pi-ai ships nothing under this key, so the profile
+    # supplies the whole provider.
+    acme-gateway:
+      displayName: Acme Gateway
+      apiKeyEnv: ACME_GATEWAY_API_KEY
+      api: openai-completions
+      baseURL: https://gateway.acme.example/v1
+      models:
+        - id: acme-large
+          name: Acme Large
+          contextWindow: 65536
+          maxTokens: 4096
+```
+
+settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上，所以你可以只覆盖某个路由的一个字段，其余保持组合里的样子。
+
+一份服务不了的 profile 会在**写入处**被拒绝：手工声明的路由必须给出 `api`、`baseURL` 和至少一个模型，缺了会带着路由名和模型名报错，而不是存下来再让整个命名空间静默失效。已经存好的文档被外部改坏时，settings 会保留上一次的好值并告警。
+
+## 模型目录
+
+`models` 是**替换**该路由的内置目录，不是往里追加；省略或留空则原样使用内置目录。每个条目会从同 `id` 的内置模型继承自己没写的字段，所以「收窄到两个模型」「更正一个容量」「加一个比内置目录更新的模型」都是一行编辑。
+
+可配置的只有 harness 会消费的四个字段：`id`、`name`、`contextWindow`、`maxTokens`。定价与输入模态没有消费方，推理能力也不按模型配置——它随内置目录条目走。
+
+两处容量都没给出的模型，取路由级兜底 `defaultContextWindow`（262144）与 `defaultMaxTokens`（32768）。这两个数按定义就是猜测，所以它们是路由字段：网关服务的模型更小时改一次即可。
+
+模型 id 不是生命周期配置：请求一个该路由没有配置的模型，会在任何网络请求之前以 `UNKNOWN_MODEL` 失败。
+
+## 凭据
+
+优先用 `apiKeyEnv`——它是一个**引用**，每次请求时解析，密钥本身不进配置文件；`apiKey` 字面量是应急出口。两者都不给，才表示这个路由不带认证，对内置目录路由意味着交给 pi-ai 自己的环境发现。给了引用却解析不到，请求会以 `MISSING_CREDENTIAL` 失败，而不是退回去用环境里碰巧存在的某个不相干的 key 计费。
+
+引用解析自 `$DSH_HOME/.env`（模型页的密钥输入框写的就是它），没有挂载凭据服务时则直接读同名环境变量。一份凭据供该路由上的所有模型使用。
+
+## 让 agent 用上新提供方
+
+配好的路由会出现在 Web 的模型选择器里，随时可切。要改默认值，就在 `cordis.yml` 里改 `agent-loop` 那条的 `provider` 与 `model`：
+
+```yaml
+- id: agent-loop
+  name: '@deepseek-ai/dsh-agent-loop'
+  config:
+    agents:
+      - id: main
+        provider: acme-gateway
+        model: acme-large
+```
+
+## 排错
+
+- **`MISSING_CREDENTIAL`** — profile 里的 `apiKeyEnv` 指向的变量没有值。用模型页存一次密钥，或导出该环境变量。
+- **`UNKNOWN_MODEL`** — 请求的模型不在该路由配置的目录里。把它加进 `models`，或改用目录里已有的 id。
+- **`settings-rejected`** — 写入的 profile 服务不了，错误信息会点名具体的路由和模型。手工声明的路由检查 `api`、`baseURL`、`models` 是否齐全。
+- **获取可用模型返回 401** — 端点拒绝了这次探测。检查密钥；若地址指向的是 Anthropic 风格网关，注意探测只读 OpenAI 兼容的 `GET /models`，此时手工填写模型即可。
+
+## 精确字段参考
+
+每个插件当前支持的完整字段、类型与默认值见自动生成的[插件配置目录](../../config-catalog.md)。两个适配器各自的语义由它们的 README 负责：[`dsh-llm-pi-ai`](../../../packages/llm/llm-pi-ai/README.md) 与 [`dsh-llm-deepseek`](../../../packages/llm/llm-deepseek/README.md)。`cordis.yml` 本身的写法见[配置文件](./config.md)。
diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml
index 2cf494f71a..74fd06f83d 100644
--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.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 docs/user/guide/quickstart.md
-quickstart.md: 199b3f092159fa6fbaf3ae298151487c924ac6f1
-quickstart.zh.md: 9327ed646ba211bcce6426beb6bf76fca50acbf6
+quickstart.md: 8a9ed716d9395448aadfb97d0935bd42ee06e6c1
+quickstart.zh.md: 3652b0453f870640b278ce6f1355e67e85983ffe
diff --git a/docs/user/guide/quickstart.md b/docs/user/guide/quickstart.md
index 199b3f0921..8a9ed716d9 100644
--- a/docs/user/guide/quickstart.md
+++ b/docs/user/guide/quickstart.md
@@ -57,5 +57,6 @@ headless-agent uses the `@deepseek-ai/dsh-cli-demo` app. `dsh web` instead compo
 
 ## Next steps
 
+- [Model providers](./providers.md) — reach providers beyond DeepSeek, and custom gateways
 - [Configuration](./config.md) — understand the `cordis.yml` format
 - [Develop a plugin](../develop/basic/) — build your own tool or backend
diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md
index 9327ed646b..3652b0453f 100644
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -57,5 +57,6 @@ headless-agent 使用 `@deepseek-ai/dsh-cli-demo` app。`dsh web` 则组合 [`ap
 
 ## 下一步
 
+- [配置模型提供方](./providers.md) — 接入 DeepSeek 之外的提供方与自定义网关
 - [配置文件](./config.md) — 了解 `cordis.yml` 的格式
 - [开发插件](../develop/basic/) — 编写自己的 tool 或后端
diff --git a/website/docs.ts b/website/docs.ts
index 8d42ae3209..2b9c4654c4 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -130,13 +130,21 @@ const homeAndGuide = pairedPages([
     section: { root: '入门', en: 'Guide' },
     order: 2,
   },
+  {
+    source: 'docs/user/guide/providers.md',
+    route: 'guide/providers.md',
+    label: { root: '配置模型提供方', en: 'Model providers' },
+    sidebar: { root: 'zh-guide', en: 'en-guide' },
+    section: { root: '入门', en: 'Guide' },
+    order: 3,
+  },
   {
     source: 'docs/user/guide/config.md',
     route: 'guide/config.md',
     label: { root: '配置文件', en: 'Configuration' },
     sidebar: { root: 'zh-guide', en: 'en-guide' },
     section: { root: '入门', en: 'Guide' },
-    order: 3,
+    order: 4,
   },
 ])
 

From 87d0fc6fc42d1fe1afa244b40e1bd4faead658f0 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Thu, 6 Aug 2026 04:31:34 -0700
Subject: [PATCH 067/516] cleanup: drop leftovers from the retired HTTP-serving
 revision

---
 packages/client/connection/src/client/fixture.ts    |  1 -
 packages/client/connection/src/index.ts             |  3 +--
 .../client/connection/tests/client-apply.spec.ts    |  1 -
 packages/client/connection/tests/node-half.spec.ts  | 13 +++++--------
 .../client/runtime/src/client/workspaces/service.ts |  1 -
 packages/client/test-runtime/src/workspaces.ts      |  1 -
 .../src/client/chat/Deliverables.tsx                |  3 +--
 7 files changed, 7 insertions(+), 16 deletions(-)

diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 0549fc1160..9f091b26c5 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2362,7 +2362,6 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       })
       return Promise.resolve({ accepted: true })
     },
-
   }
 }
 
diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts
index 03f8aaa257..ed4af2d21f 100644
--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -13,7 +13,7 @@ export { API_PATH } from './api-path.ts'
 /** Stable Cordis plugin name. */
 export const name = 'client-connection'
 
-/** Services required before mounting the routes. */
+/** Services required before mounting the route. */
 export const inject = ['httpServer', 'apiProxy']
 
 /** Plugin config: the deployment's non-loopback serving authorities. */
@@ -96,5 +96,4 @@ export function apply(ctx: Context, config?: ConnectionConfig): void {
     },
   }
   ctx.effect(() => ctx.httpServer.register(route), 'client-connection: /api route')
-
 }
diff --git a/packages/client/connection/tests/client-apply.spec.ts b/packages/client/connection/tests/client-apply.spec.ts
index f9fe1c1b71..6892dc7721 100644
--- a/packages/client/connection/tests/client-apply.spec.ts
+++ b/packages/client/connection/tests/client-apply.spec.ts
@@ -62,5 +62,4 @@ describe('connection client apply', () => {
     }
     expect(seen.some(u => u.includes('/api/'))).toBe(true)
   })
-
 })
diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts
index 216484ad67..08c65de2ba 100644
--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -30,15 +30,11 @@ function fakeRequest(headers: Record<string, string>, url = `${API_PATH}/session
 }
 
 /** Response recorder compatible with both the fence's short-circuit and the bridge. */
-function fakeResponse(): { response: ServerResponse; state: { status?: number; body?: unknown; headers?: Record<string, string> } } {
-  const state: { status?: number; body?: unknown; headers?: Record<string, string> } = {}
+function fakeResponse(): { response: ServerResponse; state: { status?: number; body?: unknown } } {
+  const state: { status?: number; body?: unknown } = {}
   const response = Object.assign(new EventEmitter(), {
     writableEnded: false,
-    writeHead(value: number, headers?: Record<string, string>) {
-      state.status = value
-      if (headers !== undefined) state.headers = headers
-      return this
-    },
+    writeHead(value: number) { state.status = value; return this },
     write() { return true },
     end(this: { writableEnded: boolean }, value?: unknown) {
       if (value !== undefined) state.body = value
@@ -72,7 +68,8 @@ describe('connection node half', () => {
 
   it('registers the /api prefix route and removes it with the fiber', async () => {
     const { routes, dispose } = await mounted()
-    expect(routes).toMatchObject([{ kind: 'prefix', path: API_PATH }])
+    expect(routes).toHaveLength(1)
+    expect(routes[0]).toMatchObject({ kind: 'prefix', path: API_PATH })
     await dispose()
     expect(routes).toHaveLength(0)
   })
diff --git a/packages/client/runtime/src/client/workspaces/service.ts b/packages/client/runtime/src/client/workspaces/service.ts
index c0eb46fcf9..a0a76670f2 100644
--- a/packages/client/runtime/src/client/workspaces/service.ts
+++ b/packages/client/runtime/src/client/workspaces/service.ts
@@ -239,7 +239,6 @@ export class WorkspacesService implements IWorkspaces {
     }
   }
 
-
   /**
    * Rename a Workspace.
    * @param workspaceId - target workspace.
diff --git a/packages/client/test-runtime/src/workspaces.ts b/packages/client/test-runtime/src/workspaces.ts
index 95f6574405..7e626a3660 100644
--- a/packages/client/test-runtime/src/workspaces.ts
+++ b/packages/client/test-runtime/src/workspaces.ts
@@ -98,7 +98,6 @@ export class TestWorkspaces implements IWorkspaces {
     await (this.stubs.get('openPath')?.(path) as Promise<void> | undefined)
   }
 
-
   /**
    * Directory picker (recorded). The default cancels (null); stub to select.
    * @returns the picked path, or null.
diff --git a/packages/client/ui-conversation/src/client/chat/Deliverables.tsx b/packages/client/ui-conversation/src/client/chat/Deliverables.tsx
index 0a0160b486..7d62e23401 100644
--- a/packages/client/ui-conversation/src/client/chat/Deliverables.tsx
+++ b/packages/client/ui-conversation/src/client/chat/Deliverables.tsx
@@ -2,8 +2,7 @@
 // from the mutation tools' follow-along locations (see turnDeliverables), never
 // from the closing prose, so the answer carries its own output whether or not
 // the model remembered to name it. Clicking one goes through the same openFile
-// the tool rows use — in the browser that is a new tab served from the session
-// workspace, and outside it the Host's own opener.
+// the tool rows use — the Host's own opener, on the Host machine.
 
 import type { ChatViewSlotProps } from '../contract/slots.ts'
 import css from './Deliverables.module.css'

From a231b56eba22681e0015b6339f2116381584308b Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 19:58:31 +0800
Subject: [PATCH 068/516] docs(user): show the Models page in the provider
 guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The page told a reader to open Settings → Models and named the two buttons,
which is thin help for someone who has never seen the page. Two screenshots
per language carry it instead: the Models page with its provider card and both
add actions, and the custom-provider form with the fields it asks for.

They are the first images under docs/. The projector rewrites a
repository-relative image to a raw.githubusercontent URL pinned at the built
commit, so nothing is copied into the site bundle, and the pairing gate takes
no signature from image nodes — which is what lets each language carry its own
localized capture.
---
 docs/user/guide/providers-custom-form.png    | Bin 0 -> 58692 bytes
 docs/user/guide/providers-custom-form.zh.png | Bin 0 -> 57720 bytes
 docs/user/guide/providers-models-page.png    | Bin 0 -> 75818 bytes
 docs/user/guide/providers-models-page.zh.png | Bin 0 -> 70021 bytes
 docs/user/guide/providers.i18n.yaml          |   4 ++--
 docs/user/guide/providers.md                 |   4 ++++
 docs/user/guide/providers.zh.md              |   4 ++++
 7 files changed, 10 insertions(+), 2 deletions(-)
 create mode 100644 docs/user/guide/providers-custom-form.png
 create mode 100644 docs/user/guide/providers-custom-form.zh.png
 create mode 100644 docs/user/guide/providers-models-page.png
 create mode 100644 docs/user/guide/providers-models-page.zh.png

diff --git a/docs/user/guide/providers-custom-form.png b/docs/user/guide/providers-custom-form.png
new file mode 100644
index 0000000000000000000000000000000000000000..bbbedde794dcf1f5b55fc7b9418ff7bca3e0cfde
GIT binary patch
literal 58692
zcmeFYXH-*N*fyvSR=_SIAYelT1VnmQ6p@ZV=uME`dnYOa0tydBdXe5cA+#hS2-0g3
zAVBCPlu$xTorBN3-|v}k*8G_@Yvo7IKD(cL-{rcm9jT?Ebcvpo{?w^cmz3YU(mr+S
zjNPeIbQTx>0ZM3hx<8*fb@i0;s~5U{85`5*gKn;Tq|qh{XV_rAPg7jjs@pmn57U+j
z^Mu8C)ezr9l4&KmYEfWwL_k(!{`#Ry=r^`;3#X@rhcOSe@J1E+(=^}1xNvLzk;>2Y
z7s&p`D979V0~(l#73o3Y!A81|ACQ5YAqd2D75W_QN)0fBQx@CqpC$TTlc}CYu$3?J
zdv-kscex%R&Yrwmd1TF<d_A#u)2)LP?-!a-1%XslOrK2r!(Ld|=7HbTjv9-!1dkAp
zu;EF4H@PTox&50N1a8;pSW@yyQ3m$TWhE7l_&ic!;Pg3e1h#7I{b`{5=lRgugu3*~
z2hEo?oSiq}C_RRg>T+-5<7Hfu`2vEN-J{0N041}b-7D+O`mKLv7Y|9w>VGR$-~2*;
zt7##{FOfQP_sL1o(W&UIhxq#0F$IUe(<^rK;+23jG#sz_-#K~zM0M`XwQj1dlAE^0
zJP-7w$bupE4SQS3_sjQAo@Tv#3Ur=IoK-OW*ZAc5!_!i)XNSUPLv^G}E}j%LkIZm<
zRn-W*aPn}qt%J+g?J;gm<K*d7nXo`piOb)CIUY+lQ9`n&Po{oqdKXHXKFtyEcWKi)
zb{?dQe;W+RhCOn~IH~c2`}C(9Cw~ZPIo<Xr8*?h)mD}H*ZeRFY_bOf6-|;Q)N}RlY
z&Ul9Vq}G>@vww#Wy85@DyXXGvrsMhl#m1jMB4=jIjP-3#I$f!)W63BjE%n)&1ZiuJ
zpink*LG@NE17Xaj&jJrx<;gp-?(oIM$OQAo!)W4h6^;7wL_QcVyYS7S5U{yJ1gU-9
zwRL!G?0x4$E-rrKX2QZ@&_>i!vav+03}LptpnzLsyVsnG8_g!_$_U!qIRza|tcX@y
zv<0oZ@&jF2Jbh#5wi^I5rxC@ogSU>q?8s%~3zE%IgZc>K5<X<bHFMxIDzwBVuetO!
z9hR~M_4M#~LdcF5Ftfm=2{hZ~oJ=UA?mBZuT6#LZnbe*x2D7C~T6S!6sU|V9OD+DS
zhNfe&CMG7iaq^@IK_C3&-d;9ML|C|8C9#V$aDIGef%T|IAO6Y>XD&YD*8asdf>Yki
zqhD12M6`cO^0~LIDalhKGt=OEP%L#f8L_(Kw}GJUz)94#Y$^l-*<V7I(WrRZoUJ^G
zlVK&S>E11%rJI1NR$ilQ-~kn<j}U5y&IIg<!*?LtV-K^5i`=vzEN9>Lf~HK9)rv-0
zwjXRJJp6T;{1Js(TU(oylw<}|v9E^1b9&|NTL)L_1`JG1gYRDb0uF$cn2juD6B}Y|
z74QYY@AtLU)zy8=hB7%&tiYhFhMzu-T4~A*&&*VQjJ&}eM3bl0_1Y&17&rS3bJ-jf
zfCMAHA?9lflCf?J{lkKWbqDGcW%*&*>P;+o*3q1{%+#x|mL}u8n`qB$-g=afP3|*Z
zM`3PkOt%cSHV`^43NOb<<Hf9If*ehc%5}?W6i%w&Qj}xo*UYDZ17!CF?*7!4*+495
zC9f++v9;uWL~6UO+}`o5Q7d`3OP*T7!rYhk%$vv+EfBojhDhta$wXZNhcvj&ak0w#
z_Yl%u;QMIAaRpPvmt#)J07A4maktOVvrr>lDCE~-x@(j3QYlClu~^fUeYCBFPZbL;
zG^_RBTb`+0KqGd<ZCtA0yGDe0`|#zeY{~|6UkZoMzX}VQA-ki|0!I0VX;0mI=DCt7
z<Q2phmhlFc>4O46up)zeaOV?Bme}S${3Dg7Eu;n%u$9j<u8-;Be>0nj(3u~RSA?I9
zw4`s)C<q#9zUMpZZE2r!Sr06nLd;A~W|j@MvI_kt{#;LQZ+n+KX~PpsJivzQi}0LU
zT>*qcop$4L#7k?hJtIuq1Es#_I-@1by!hZb2J;by_97Yo-9=aMA*m?a|6r{s`?hd^
z*HMQ}77q^(9^SI!ncbp~R6poLP@q^zAM&_3VrL)Yg6I{1m$ANI=u{_`R8~^uv6L8O
z-uAKUMC}p^vsJ(DP%jmrL?N$6$R7<wY~gmfs$j%PH2mNaNz;c5L|&Kh-P%y%3|6Dl
zlqWfPF@G79rG4_RYQeXT&cvH;-Gwczz}@g^;;3;|kJX_$FfA4@e@Kp&C(nTmrwwQa
z;a9*%d2`-g5N~gztnYmKayv(P!Zv-YNFzF6=XO+IxoPJd&$hj^@xzUE%c@B_qSPn`
zwuSlmiwuV$%5)sDN<wS3s)GBFhDu}T7I2VEbaeJcv#CMDxr)iA&F}yGn~R{e;Ei&!
zY8@RMMYop(!9vn}s&omDG-_84DqO)`52G?RHVS$LjDxy!VWb1tF0PDswajSY0q60!
zj;5TMfx+z>MnL<>k&Xko)oz3Lk@}LE1IRM-i3aDEP8#t2r{Go*+M~b17?Su+C+8jg
z_mSwn?0O5dX`pjP8MwBbT$fGy^lKzT(ld#_r93~M0709fcULuOD|l*1Pogp_=T7|m
ze0){VCYw=8iB6H3-&|iq!$EoZ1|W;-;xk9Fw4=c`<6$$iX%uSNC)<ZyZZh!}>)l%c
zCA5-hR8E?G(WA3jy@KX?#>OOES(VFl^S(6pxJAG`mrPF81nZS_FL_in?)Cu7MDmuK
z?iH5q>-u{ScFFH=2y1@3EhIyQoCCIdKKaY6?kzpcQ~%wYjvrv#^D4p?%|D*DtKJe!
z6Sv(046{8*LT39X9leI4qN4e6Px5{dg1mJ4MuyyRq~@!{R@$LH!hbPNsX{B)pa~Z?
zocB6)hept(6-(6EY^F!uqJOF>zyGS^nXaCmS@ZiHbLwtUe*Qzs-nuynC!2jVHYw@|
zy0P1X)0f}x)}&$(l;~7#a5L#8=Uer-a4d#wmeE$yTCVop<_dX9vsb{}rqd24w-c#Z
z6|%&n7(Eztz`!;W!Z$DQ3~9%7^H!zNagblXnk!mJT-^7VNx$3#qH>L}c?oY<Hn}%Z
zXIoV`_H$k_`PKOpH%C-C1xuqqSg75xU_Z2}?<AO*?ix(00tY`Na`pH3bCSlp`dx^J
zU=liT>o|pl25c*CMV=N`TB?yDv6DI&<g(QBCu^(4*b&&sANtqbV|5h$!&q*Mdc6OK
z$by9jN3h(M4bVM0TGBUjCy&p~FDQjj%4m@Jyf4=0LI?|-<B<xwp*trAMPA;#y+<bS
za4R}w6HGZgRClOV&^)4yE6F)sp)JT$LuCzBRC+d{(+=TSFu05fia1^t-xzz?^H!cR
zq4_%IcFwzk3m_In#3C9&wDt;F-ISUMQR*704BDwDm2BV&F|LSd-0&oH<{2F)Wi_H*
zCxMAkk!GHJQ3+{Y*n4E`($uY?9zKH4RTV(}L^)#sqs~N`6hQyA3*TRz;U>vt*Aqk>
zXZy2cdl|{2^0eO4WV2c<3>tGs($eTQFRmOAwl9cVH*cDF?EJPlLZZ!LkJkUa_wpA$
zIDY3wXZlA5ft0w6j62k#$OI{)b0{Rr(7k1SOZq`)agW{aC?*@fm6$&+7Xekt+?UNP
zRC{IJZ)tZa;K8NxfVKKrg5_fgp7UnD(-6H_A1?t6yYJMs9c~yoDc$93NH-2ymG<#>
z^erWtH}%u8&1}CoHtI+x+3^zaVF-Hn({N0;Zl!#rJAawC^OeZGbzgB4Fa-~$DZ%vZ
z*CI88adi`hhI`C7#94h)h-FV=_s(EZWBwSUT86~%l82(^Q~#cad}AWz_4yCyH4k`|
zR5hd3VmW-P4nOg3=>{{)&cMT*x?<RUXZ($xun60fOXI!~t7BAx#i!gTlq)g@CMLDs
z>tdq~)%ma5+i<mImCeui_(pMY?6~GB_R&K1XbwYd6Q^_3V{__KB=>!`*OlPFP!<XQ
z-S-{Y%_e`P3wr(Sg09xku&;u#vGFS<AG$rCv$68TKcf2P&MJL?Dy=FH*_Ws8k&?~b
zmyl?aBB^4D6&(=B{#<7a%jnV>E2%Dh5Xdl6)McYlpevRgEfj+N7<vutA<>)ycU|`*
zv9o{MQDgq1SA9@oRW=iXan_5)t+T0d-}3kOFI?vR)wp9?Ze+dEA}%7r`$&;Io&eI<
zS8A>9{i{U+_^vT8L|kUi)vo37$4}JxPS%&8PVup76C&iv4Y|4V$INDaB;Xjf?o~Qu
zi-cerHnWfWR>0&1&Kdu%O(9!LUxc2v(d5#Zf=s07#Dt`tB|E<SW26PT&&!aLsls)=
z(XEXP=oWTaA17pKGMto&K&F8BLfd%c<!QUsn9An-=Gu&mjI=aX_AB4MeOp_L3m)}t
za!5^OhZtbV%V=(ml-oP#h66DupWnk+7U7-~Z~5Hw`=1hemzr^<eCn?DnsUcu{Lrbf
z=|u3+0w<VKHk)Trg`iG?$z3$t*HU+4p5OhU;6otzKyR38BS*RAsO}WIqkbrgvay0N
zXtAll;%URNA=fqCSf$<r4g%CQ`_|8EApaU)yqWOR_iy698>p~bbN5E&&iD>y$=X<S
z66|;Sid@%=yIoo+sBH3LQHw8L(reYt#U;kScDrAE`le<}BZG~ac<gOd`aqVf^n4Xi
zBPOK#-`p5qeTU|KRQib<e7ENMu&$;Hyk;SWmaJbz-FFSaEQwsY^i7^POuHi;Vj@2$
z-u#uF&50j1GLl<-b?5rtnS8$|hOMjO2&(zs#`FWFm{&5f5YN-Bzi5*7BOUj0Omg}f
z>_-Ey-4GWQExF&zC}<WG`Q2^U`EsxvcD;xrMr1nbWj1=)CH`=}2UKS64}rmCC3X*P
z$GSc%^bK!LHZx=2;SPf)n+He&-kLN?HrDLT$xKgQznO93Pm+81`nC}i40!yvyRp6f
z8sOy_j%K(XZNEdCgEJ{b3{s?cIPK&4cJo?KbY;ZLD|hLOu9HFf=F+}1zW`?ph%@YE
zdnMTi4tx+yrBA!*Wmi#uaIK>@(?svN(evvdm-RRQ0M-iK_wut7`0$X17U5-+51E>3
z@~rqwnvthOPwzDE#9~Rdpwsqu`T3o3V~vw95B%8ybMKl})1soVNf1#d==ipXRMn-o
zWK#(%j+*%Mnh=A+XS}}vW1f(fR{D`dB@_W(!9`j^Eow#17ymg@hcLS22n0tTgp(UD
zcTxASwBX;Jjt&kElarIcM;<VCg)K$(3UZ1CjSoLi^4S<aUbTu{*VHS1iK9`e;KDF(
zS@FPu4BKpmgN=hwPHJ&&EpDXuR#_u$CNLd**dqV_{rgvh^RpgJ0*IiA!H@&(8Dif5
zU;zw#M_yxt!RyA@)}#37y1Lr$wN${w<ux@KF1WVt5VtS4b;WYFSSdaINZyW+m-L$*
z%4qTwFlro<`L!<%CT%(!LrWw=2;((?IoRxEb1|s*8-~LI&5dA0q`q05!j;dI1<nvx
zE)xx(2KiaUdgYahMu*?E1*%Na=Kf1eE$N>*X-DVn?RO5yGb`S@l#%8B^!~iSr5KDA
zG(?1OOK_%kx1=a*heQE3)K<UTAmq5#y2q)il{g8w0ZQNQ*mF$WtgNoy28`HJksQVF
z>_Q;oXel<B&>qb!$RXx54i6>)&aS+jkjOVn<0Cr%ldTR}v~zN3xW4rBW9VTJIU(W-
z=a$Q-8mlhq0ThuYM5(v2si>&nBpq>s@?%o`7QbA>QV*~}3+dQeg;;G0o<@YTn46hV
zCkBJt1csCvEsvMvDc!MqySp1grPSsn)F?gWaQcu`CdK(h*BtBCmFep}@kncKF)o6W
zu`25Ahg5OeeLg~UVX_|Vwp>jqLa)5>HC?iRA$hy~N*GN!I$)2#Ey)#a61>kz9rBj$
zTs?N2mOt(ue5JXEtO_~CQwMz)3?CX-p@#Jg4JB>2{`qaOH@Lr!{p#oS9q?a(=$D$|
zO}u=aYaEDg`WKOIlSPQ5--CT9gK7)vsAeW=?+6Hh|6qgGF?#yCbO#*^vApJn?p30|
zfxC)0BZ?H(Z4Rb36(M%MRWaRsCAVz1I+Wv!4Ms-`$}z{Kbu8?VsZd1I@iN=q-ri=M
zzJNJ(H4ogsfs1>=D=UB8VFjl7VnK{`fzn#)WA*krh(j3dFj;<@IV<h`+^@5&l3=P#
zOH${O#Qv+izP_*Lw`hA^@*%P3HsaDYYkQMr39}U2g1D?4yTfs-*uD(^kFu{ZE3}|P
z>B96Dvo(y=Int1ELm#6f+v}o2j{L$x>aixck#d09h)@E&Zj5WoeyVNO*Kz4NIYLeg
z^)MN6!Q7hX@e^_cf+Wvp9yFtI0`ELWsM>u?s3<5<+-K{GWlsK{tbSWOWVxInDrz2=
zvIT?_qN2zJZnf3jYtM&u>uSKX)7Brl6S%p!xPE8A8!87De0(Pc)O&$Y-(!BUdt;*<
z2)1k@rn$a9HPy=>8ymYL<@H!l9^A1#XM0qQ?x?b|vRa7CQ=<F$v*Y58Ul>imcP|GV
z{d^eAbV5Q#<0O=!TiiIqO}NBA1pNO{cRxpcANX@>*5rSnn(JtG$$^aaxu+EI4lG9E
zq?T}(?Ei`1{8#z^HbV3N2;TYsM&ksg3ulasf=*zRQ(o=P!PQ8#IQcM^T2xcABb?o6
zOC;FKYMPju?hQSNwVy5Jt4fi0*Lng3&4%84(Y8jCKkBYo=o0-mHT7Mm#GQd_55fUa
zav_fK<SE704#dMqS9C%8j<XbJjMX`ASJmDD(-u*;9mTzhkI)_1At!j3=TguyLpGbF
z$7hz~)dfx1A(b?jAemWN-q$xZmBCP`nJ&HZD>3or3BdOpp`zvH;N&DiS2|atghC=W
zCm}1x%=*FeR-CEwt})(XeOfN*&zdS5e7bX^D_#^<K#)!X;GeFsga*HMXwF+><1&+G
zZ_ELAR>(oSFILiZAnau2AE*gKg#j8xd(qjnuPiPOE&>7qhI`9WRcKNXiPNk3j;HNl
z!*u~J$>TC}a;tZxd&_io<H`e@#+;lvK#`Iz-_Z^l=_D^?Q?>Q=1CK{~{{p6zhdFKb
zll45Kg&H+9V5p7X(E`+18Zj=4RE5}CHoT~@@>p?5l6jz(=D#+tNQ5o-Lpl66lrPEb
z_w51kHxMc`p6v7w`HZE3d%JtPx6D0;`Kn;<i>pG}gUN}B`Eg}tA=cQBbpB0EoK2(w
zaR4gniZShq;Y4hum8r@6yS%)-Dea5Lf-SIAIv1$p{O5}|xMR|VoC7>O;!`cqm9kZ>
zJK^VCU_0U0idG^rrF~(|HWlYw5KGJNUPg=|k+kEs2*Th}Z<2bt)I?S}Y#IP0e8pN@
zYHDkx9ta2Tc0}q|H0DMyO|;;DvN>X(2ne`1I%bQwlM}lWY}B${utV15IXFVZKizg9
z1@1<bso2eek$8Fe5FYpyC4$bcCa3OsA~Bp<A2u~JLmla@3L+*P8UTwvMQoqIgIrht
zy{GrIxSmr`fJNS=JUlvD)dxRQrn@)E=EwowWf3;?tV1&v2jBoD4_R~g^_WLCrzfd9
z;ZevML$-HIsAK-)TH8VR^Sjmdi==Bc?<vxFhh;-U!<SL?`-2S)ViX;^y_F1~1muFI
zT!nwy++?#6|48Sd7?_;Lx#ht$GjTMNjRy}=S6b4=)|K{X%V>CfT%1d+KC5muPoH2T
ztxc)H31jn`Xhf>xCaeR{4~5@YRWoA>?rEzUJ*W|XvXX(0i7OgF&|&kV`p4a%Ab-Ur
zok1CK`}xoII*)8u78%(`;ygq4NTkHH42_lA-Xyhbxe6G>855J~T4{{%#Zu)dOD{lm
z5_e+C%lqtgiZ-Sof$I&M;?r)KvYN0duV|>nj8lJ3i=q+jK>Cp=5BZ77Q}EcIYose2
zlhyAQvN`=82Ux=JbXR1{Ps0}C6`5C7RyZZRR)2pN%zVN}>&H{Kk%HLu9lu{iVBdwp
zTiLGEsfmToZ|b`bODy|w`oKxncH2ERidL2S^cYyr2Vt+I(1iHD!b35~=liPHE@22o
z*2$&;qzZAK3lk5-TkGDwP^1%|_M?1H78HG8+n17*5l`+Zt8$&m{ZVg)>SGY`m?Qi5
zyy4bJ%9Jq_1DyR-ZKT$+A(Uao7n9wHE8$@9{wFK-`!Pfio1U3jF}F5aIFK1U7fW5S
z%^b}z%16j-|6AJo=qo2FY%ru}%=g<Jp`gX>IeE(Os>>X5yIY-yw@f|W9+6@E{MpB2
zUF~=+oOzzow=uoiU)Op5u3)i#;Cl98k;zW9IYkfofVdLIJn%K;x&PW^SrwzEy2s+U
z5M`jZ7owBkKDv)iwXs)<;Sjd6>CcFZ&nW*`f$<qnaGrphA|kG^O}0BLT3atYGMV<<
z6n!Mh67_P}6p2Kk^w47t7QdPFQ^ww_X_*eD46{lE5$rlt2`IYcv~ml6LnRd_2dCN-
z2_Zy$MoDar*Q~E&iIpsR{NH4$@zKm?;C|$_8_YKsi;9YrzKS&29aX=(wqPo-GIZ}{
z>>XK$`0qd>fahz;mUVB#CSPUi6g`N`83P}s2fa3&mNwINIQQCH&J!i(pu3pzpi9aH
zGTCg^6}Qm!i{>>udygU)u;JIC+R3;*8q&+h+xOfkAniYG^RT(Z%+JiD$wcKEfa<~l
z7w?*=>by_W{Z0Tg9~rs9`k430mn_e>@8F+w+-*1F&hD-7NU+O!yxLbNm6q~beG?oE
zo3S&Cy@HW--+k4^C|%~_^fI^eCUbJiNAGoUFG=Xg$jBEVfudg4H(fEz=^xAcp8VDB
zU?4%!)7M9yUy*YT&(v7?_nzW4c5Z^2V0U+SWoc>UI&O>IQ&ls>1&9ZG@*{gxRn(24
z_(rdt+=`r-jYsMk|E4F5wzn+W_>v)o4JbmZZCOcV5OyjfrXeW1btSKxr^x#q^Y;0S
zn7X0sBWJjw7+K3Bt^YMNt8BpHs<2~mAuI3MqWB@_x7SoO6VGzr79HWp>nS+9w+w&=
z`}~-Oh)+7(=Zdm0Ylb<2sZzEEtk*JBR5V|y$pq+j;TD&dHEzqJq%bHrWXqt~efI0x
zsJ6EDe+FT$-23vdxYg_PfhLdnW#17|btmR-e}7-ESa@rD=h35043ze>t$m5<d+BT%
zJCZ^1^Sk!&w5%TU;Qepg;bH3P{f^iGKFj%>mk}uu2QE_tvyN<^&6yS#%DDv8^#w|W
zF(+U^_!4jHKQXsCNjt4_uNb%i*rbn-p3mK@M}RUIhd62)8>bJhU}~K)p;u%b&boT?
zwpw)7Z?6HtfEbX?0is0zv5|5Hn~w5`w~a<#?$vZVp%Jm<r8WeIY=GL1J%ELP8}Wlo
zOy95F;IlNXc`}a7Dh)6*+4l&38Oqce+e_<AcctK6Lk?%#W3yIEJvRD|DIwM`_Uf$H
z8@RKAh$mhHo_56S%tG0pEYttWF5G#7Fbru9Q0d$Pxx~d+dJjVm0C>LummIRQj(x=C
zPo{pDPoU;M-(M085omq@2ZWA^IXUrrvax&psPI<f=5qYVNNB`m*Qt6#c@-skUScqs
z9qOaEc4i~ewQ(ygZE_MS-bx}zmk|<@(~W_wTxn^cT58bmwduk`=89d-kb~aU9f9P%
z24hzMdae0;6lfV%ZQb;s`@u`m*@0G@#-u~e^3qCF%CApk<%CCOaKZ?=wRLrkxi6DK
z5FRYyeIzVwg&X79X$`|{Qa6g^b^wP4j_^)5D;^WcFWx>db{**N-}E3}!Ft=ie%(pj
zXJbuI>$`7lV|@~!j&Mc);@lE>p14~3OqhvBFhz)x8@A_B>-nGX^bC)WIc3)ImX+#u
zJ#%~8w!W_i0`c9nwzlrfFo38bk)rDT>P?bO^!9&Un!Vpm?EmF0PY=`#+&fV-cX$3@
z&3FFqIK(dNPLBJ>K^1b~z!og$g)`*8j;KLW`<#~)yGAl!cOEUiyzalHUjnk~zt^4Z
zcZ^OJb2apVp|*BnL3!QWlQY~%J|00HQTyjK#)=RXZS8omkG)HORqM~%$<T@sGJj^d
z1$*MlxfiDu==3bPq$JMTS-n5{A1vS>YG-&j;0{zc7#SJa*ep*(eLWdsfJsFQIGjM*
zuQb>_P-bmy?Xr@B=PQNKg!@)jFJY*Og`LHvrMHNah2IUKzX<|?fZ(|_Sb6Y|+WQ}G
zOx(219Ez((@jyTXplu!cl_w`s0$tKsQdn3B;0zNy4}|&NZKAIe#Ef8_;pYkp6B84s
zrcAU?($yd2v=X&`Xjy;#6?Q*-P5j;o7-ZBsb8sLQ+m-jd9;k6@mT_@$@v+Hc%g1&G
z7vsLn=09287vp1H2Iho5nbRy|Y5+GyZ%AvZ`kWa6-a#e(*g!@`tgsg+tyh^{pvKqQ
zabMZ!oPUPu{KOv~8)azN>ggq&$o?rxhs@L)_Xkh6ziZHOWEf#43DR6#VXp&D-Vx)p
z6F!9_S)|S#z{*dfP?M!tWo6~RpN_zHLqu)$ww8<I2MF|hdv@2tUkbzz^QP&xS5^vL
zKjCqrKgl^U$QuVHyeEBe-YKL>(tgVK+y4wrXwr<P5>849(mF2_J`CJDC-XNY|MQfx
z0kc>AkCQ<0!~b5^{wJN=JEW)|hVt=!EFZsU_ld%}8a8{TET^VGy_<(Wb@pV-ydn$#
zuJC_R0wlW9aFC-()-)p{V~jCo(p11UzAJOX-P$JKOFXy^3W3)s-XKvzVlm$n7d4a*
z@(TbrY6sGwj~284@l^i7>=nC!s+pXA{7&Puk$B+O|9&Q^p*h?J=KZra{^ee`n&#H7
zx@ddzxvD{QArz^A3l_D;t+`Gbe|+xN#+ojwgJ^%pWnVF>BQmJNkev*ii}D#KK7KQ6
z@4R!97)p-wlC<G)<!LA;H9LVrj!#{ysDB=rG0A>80<+okMqNcy)#o$polc#m>Z*qn
z{qD2-x8S+WZ$00rsz;4m8YTCn&Hi(9vC#3NG+M-O@Ou?Ry=?jLe0?EtIB*S0`L$bm
zj=~cV9)6(f9PH`V;LlPy3O(UU42iF3yJ;(E4Np;vqNbgl;e|G3O$DHuwz)4)?&~8(
zcqGSZx-U%RFMZ=*vsa#Ld!DMo@<8P3<0>aDiPe-DwBC~A-tpv~$A|+i4U`5o&y^|U
zJexPQQU668)F5Qvp=B`?8*iZZT17*z6v^FlotqcO^l<~s%jRdy`fMbD>7V{z=QY5}
zG8mP2eXR{vZz&%SVm4>#v%ib|iQElPpE}+;U1wci_>%tFW_Myx-_+zwccCDL$2ws)
zY+wFJPCf~Uto<enTP{yT-lF#ie>4<}Qsnug(HixoZ4<kNe<mR+23h6mDa(HZtd)@L
z`AC9iJLTbzfOE+Dhk;Yn=g+@CgzTFYT=?F=pjov#<d={p;_gO#=&Pz~oB#!d?RP%P
zrr!x0W_kd+M65{3j|45~>SOOP8maT2=KGOs_o(!6yD^isg#MD^HU8MwrMT{_(4O^2
zqV|{9N|cG4j*j|HT0G`Ws*3*BVr7TCrEF>r&(<rOnPG9uCC(!pNkRcF6^T#Oc88<*
zMD2UZwSsm1&LG2i%bc_fJX$i0g4L}&ek^mEOr*V*{^Vetc{yU{&$^@PmG$=uZ~Ga~
zl$DV`Za-bPbhaX~y18*zYdX;*F6ou9mt<xD$k|TG?q0+#8$fY@=p170RL=4v@4qe&
zNkB8Fg~te-e0kS_)Y<&_=AOM09_6!5MZD4RG9?;CIuO2@fsv-1a!XdnFns|YXmM2M
z7<(8ln(T6D5A`cCkS~AQE8;iWQPQ0?QfmZqEdE+~#u8CQ&9Bz=sD17Il>Um3o3<oe
z<|a%#ep>OE9VEmNtIDHr`lawNKL25|nah5-q0y!HwuLsfg&9W4^^0G4Au}#~>IrvL
z*mLsp-z=!b(BHHEzTd|Bu*mAoJ3Xc4okoSZerG)u!5U*>-hb?S`F>>G%1~gaV$A1X
z+iwV0QmT7clF6n8GAO0!5JymTY|HkXsTCElytV!#i$V`ch{d-V6rfe1!roT)_NL<b
zCklc%o3VDs(%>zs_+8VS^3SJ-mrKew)}6X-!s0`jRG6<F;@<e^IaE(&FCGw$9?%lw
zu7{*+Jr49rT-)rhe5~+T(x8pEP{(!hYUv;C3z3z*BbF&BJ2ThC^v?GqVYvz&&kS;U
zYPO}pPOwQmS*<4`I<K)$^2t_20oTjM4{m(CFIJvpj_Ihkce>mQrLUYc(R*s^<MjSF
zKmWm>caqom3fSKjzV%L(9npQ9`uf9M-)(hGY1tDQ&hv!p%eDkLi5u0qPOsI<pHnL4
z49hv2%JNq9dUto+KL4Z5;#m$;_4l2{8?LeTmmybma^#6Fe8Mxe8mdp|pH5Rg3s01{
zz`1_0(Rbd2RRq{X<gTVY4$K$a5a1bI)rc&f#@1Y(yk?X+_TE=%_oAxdBXj#YiG?>3
zHfh_xHLh&RjT#9CsZ6c`Hqhd3h7}BVR)Nd=ckF?My#HzN-67O1Lw`$O{@EQu<=c#?
zZPOV1vkQvC__AUxCfu^Xr;GRaD~eQ(f$z&-#7uN<GAt=1waj|jzkI=4lJ2dng7dl3
zSqDtYwOauFM>ov=w5aC|r<;9=+<?k9HZp2o&(qe4SAe{B0kKT@a;4((1n6>Z85lnr
zW43gw*>907EgaaS7ke`Hey(C)O<HzTZTQ4K5C@xXW;C}HaDPJ7HRnNnZ)Dyh1+%fX
zn7%=F8U&}=`p)%F^dCt;L4zBtSsbW8^!r2$ePx~t5V88eVCP2?sczN|xi@WYCZ!om
zd1yo*kFJT@@aLHA&zE0S)l?lJsQ1IC2Da$crDb7|P@5COv#P)H+D$t^!qCiivMDv|
z;wSb>N%q3rh4+fVM;$&%THh4ox!os}UCVHnVOBmi%+oRF6)MiOGc6X9=u8KDTy$&&
z5hz&ifd?Gbuqqw}Hs0@ZdBq%zPGV|!J$D-PqPVinQ6Ww{`_{|-5F2mp1X*N`$~|Y!
zO;#ZJsTo$4XsM}Ktf>II%g@y~RXJqoxaNpUdqAXBD;&P!;XG%&4rxfgguGdr((}Xk
zgr!G-dOnaSx$6@DJVYblRqV{>+qw3T$693yzf)y>8uSV9QmqlZM7DPs&w{dd)R{JJ
zt>ek^$}Gd1)8ke87~an7;gbTqGaWR-OyYa!Kkprj7b2ENrTaZwGNas<YZ~}-d;)li
zu(~!`i3RrISGr?TDlkYzJ{9Dz5)WnfvYLtHMdeG7QHDm7fyI2!^3x{{#W{p$p63P6
z=x7{gZg%L{b<njr#%X)2%$bYEjeuJ2S)Hap2DRe>i5j@PK5uLJ+-mim)-~`*)T`JH
zWCK0(g;$-tqsFhdmx~X~>Yr|`p8thj-fV1J(_MYmUMh`S{UWoW@eme0;kCS6d12V}
zF6&(IdMeh70g&qtAKhHeaN8E+9yB+<Qlt<oT@XU4FCaquIVxY>RPKHk{U++&PYGfB
z>OTs^ST-CKbQG?0q_!DXNgb=(=+o7~YQLQx8XDW_z|8LXv$Yz<t!h96TPixPr75fG
zmLckI#!jd#m%y*ppEAl@Z2)JQMnFqDd2)raE^4p>L<M8@iD`~u!t^woO*6ZArgDl8
zKn55Ee5RkLB*Z@@@VJpErxn9c1C?{SFWhTu<%o|syL;XU36@-z-9qW6)JJew8-s52
zol@q|M~JW1azgTbb$uK*%L7LKNd}1(%e|trhq+1>)7R&c)t2bFvP;tn=Mx}ZDvm0>
z4*R!^qFXa6IZ-!h4Yi+Q>o0Mfqvux9qgF2m<=ASU&0Z`s&^AL_h%-0=-o?An^>Gx(
zG-tEnhw!0tZ4Gnm;-ba%QL`cVcBARF5<y8_Ykgzv)Y$P=<Ng=Xx@HqYFMC9lm5<d$
zZ6?o}is4S&z=5GAckwUR6}qOMsJC%4HHN~xBBZkPidSpfLqAP1j$(b)i@#JIy;J%J
ziYY-D(f#xav`G60*L4ji`0Mh0e@XjbRY#-Q+)sUJ&5uS~wd!<Z{``6KR>Sd|1Iu`X
z^Y^$c%TmWu$8^GiyL1GT_mp*F{Kmkbvi>>8gNC%%AEMl-1Kui{>QNz2s&b=4)C|;R
zW%VQ#ykGUdRX<|v?^$sibtx@&0M5;aRGcU*+Q-}%X<fQnwqCBUR+PzcBBz~_o@~J{
zTmmXE){~{F8kcV>c+`#R_TW7NmOlS#Wdxb8a`CRDkLA}k#y>anA^!B%uSm%$O$>kS
z+S1K;PlZ9!u*7!cceYvCc-}Dt0_BUH*yr_m!eE{=<5FfJ)uUcjrhh43-od6#B)1=g
znH9a)pZ^HS%(Idr*VU5pE~<-Q!I2rGEgh=k1^Rx=!|q*@LR!h>$glO_?}{L>!89^7
zpOHVZYvEZhYI+x#?<w0qKmfYl;u26$*sKBoUz{%cH@HqSm8dgg+~E(89)e&G{iN0A
zv+y?<`8PxO3ox=DzI7#PmO7-@TRsS1eno>^!SsZrIVXchlDy71{xqS3-3zYRoHTTI
zkpkuMI2IK6(eIwizkdxFE7VX~IWlBraoLb=ZEC&I@ZLRmNUP>W)ZjxhD%rwyfwEIr
zDnZ{sth;m8e{DFHAgbA<zP5}ik#j2JxSvE#TvQwKteLOM)Or6*RM*s}>pajWfnh73
zb7Mq1eiB3WxpHH9Cg=Ix+qZQ`=SddgZ%0wZr579KRh51Aj!t|&#ydS}p_w@UU5}A6
z2R00b!j$9E_R>_tiwtT%+r(1R9T_-)zx&o0@9g9tB&5xDkDIUmFG)h}(<hzk2aRWD
z%)PRdHC460sd$^#IiyZvq>1%=ji$iS(z8+VBEhbF@<CwpA31*}PZ6#xzXpbUZorMA
za|D8*_BF<%P!oZuhTs(sNd}M5Sf`PX*EaBNlozg6sR>LQ&ap*efVK(x$zx}bGxY9K
z^+#~1mSTb-XNIJ+hIRszROOqKB%ht@m6^Tl4>NV=0f@rmEFUCDF8ja8t`s7A^i}JI
z)VZ+_=eeQW<E|gk>ky#DsUPO4KjxHKw+BXmxXXWvT@>JrJO3Bf-BA3Rlr-z9KE35B
zFCm#R01ynH-_<fVcLip0>bbnowU_Sg?i^DK4|z&T^op;4Q~67wrYOwiHZ@J0#F+fo
z+PX_riWV&jbiBR2e-RB&zKI+B*_;AhcQ=oQt%Ab0?^jDoN;HzoAP{8v$q_k4NVN?6
z71q0?qUN3Oy?S=hO+xtDvpbg~(CY;=CsD|A>|+&O5Qs;wIG0EEf$(WxahAxy&&8u_
zJ%9d;J@@qVR8$P}*Je8Dszdpn!drzBWq;)o9-(gpMkOnqy6?{cM4=`p2ZqSjANe0F
z0H$7+2C#xtQ->fYyX7XJ9aCIY<?7&|{Vf5rsi8Xf#x3TJms_pEcSkw%XlT=f$hfM8
zh6WJ-s;G>lwU`K;;E6xaXZ`vl-?6e+64fnJr3?`Sb|rEREc46of=0O5=UN@rX!MD=
ze7Jq5jWu~}tV5|V1}bmd){QE?FoD~HLP?Z1-M?J*=fx3{MWb_GP4O~B!EULtfsp^$
z=PzPnSbz>r{r@>nU=vMf+gE7lU&p;Gd$J_5D(Qed<!MOyD9Z!xY#GCY&NOIgnWIw7
zZJW$Xjx#1e3QN5`{8m9hL3k{-h4yo~A0rNjHs#hjY^1zp)iKlC+1TS-$FaWt#`-Q(
zR<JzCA3sC4(Df~{$$5|oCS`Hms$Dw0!D%8Z^Lr|g3(BGCg3tgbBQ3#t$?A3NhJVis
zKV3qLY2X2ju<KZ2&vWeGB&#_wIoaTW#8J*)R!@_dVYLWdd=+s9Q{y?<f`_koN$py)
zf1|_Ec^_2-J5mldTj&{fb#!#fKS$HZH||kKC5Wn@;Qw$29080_;+3vw)h7>8a}Sgb
zIVBoxu^$(@tX#>&@N>Zdu^jR)nU?@ICcc$4Q?u|}+Gq13CvBi5J=@=BiDV3A7Zl*<
zt9tqX>Vho+S7Nt;WL=r}!Nw#^)3^_RXuJ|_#{M+YoiOh1ycpj3nt`H{E#W-=QYof0
z!{aIk6UC)nnhi*91+8QrT57BvLLFN+XX*x7{r)b7kB<*61aLB(GeMli?fBWbyvgN$
zvnp?~4lp(HD$V{5<+n4}t2$^wNl6ooLgq2g;(Hy-Dr(dB*z_TXkY%H&oeZ%<7(l+!
zrjVeG@!^9%0BqJ&XUmkFks@YYEBox~g>vk6%(*1920zr<(fEXf{v#IQ!kgI=LOz5y
zv0YY|o@Q6=`yNhLeH;wgwNh55qxzV-WPE1HIL|oHk;?g#^K+hM+ms|84)x!fVyI|)
z7{}eb*Vhci`h(YFChBaSH2dX*$*t{fTeW9JZZ*uz%FuqOUZmHMFb42MeCy^T$A5<v
zGYdNleZYYoM|=VZ5lb~|khh~_dg;K*AZ%#PZ5&|rvFz@|PFZukd9LbsuKXi<x>NaU
zoBz+*zKpfg<QEdWHhn3joR0r0Z$xgj&O7d`Rij-Qf{{yeUE#7frk!DJ{?r%A7c_2<
z>Ao$&N={77{k<6Trn>ERhDO#C>44Tn;0{Fvyy5KwrLU}_09K!Kz~23vi@U*TTFz<w
zUm%xUZ$5uWGB={6VL2NuCkmP+9AdFej(9*?iqum@T&8Xd7s6n{D+97X(z?{u>2cp6
zr*Od7xKQ56=;$wI3(|q9QY^D(wp3Gbv752mQDf!RAhMM&#`-X-r?kS@H}SiE@w5Em
z$6$arzNS<33i`36ynM385&Fo*&WZOAkVxW9kzCNV5;it9rNm^mXl6V?-(Ol;wsSEO
zP3~n9O1<AfGHw8Xdp{UF?m_rB7FliMM>eEy4Gj&+dWbDIsY;lG|B+uE`vHf90e0x$
z%s9!AUnz#neXA~yV3T$alrCc%tk63PzmcNeO_GK{mOMksI#+hWcpY0(QBhV_f!;1W
zY_Pj1Qf+yxU3cHL0;^?g4DMFk1B?NXq_GQTOaG+b<LIz%X3%6r*B)^tRhF+2+pCe}
zI@MZmR~|g~Nix`MZ0o@FXi5)OzEGOCtJIYO*pr?fgWA>kFFbs_r3V`rU$S51=n|`t
z(|97!jXc*K#xwr}v;g^ss3_dx``DS_jg;Xzaj%0`_gr=vKfl8nidE;=G$Ch|qaz^K
z4RM84K+FQx?hAK1_1$|(ztZ32HVCIE#oUp9tCtj)CFXIo?e8hbC_mmTZ2{c05l0{>
ze(p8U-$i*|sB(ta-|oNz2dO}+Lo-dnWu)VxO|7q(OJ#9!hPZ9g<%R8JPPrhjl`R-i
zVzAZ1=;%o94iZp$*r6c_-vKq#OW%%0iBNGMH)$f_*!gA7^w4E~zoC^#G>XO4&G!H_
zevOT3-|EK3j!hrtTQ`ABviQ8jMRj~IxHo1u%7eYnFf|oOo)@ZR-F9y|U~@!^iiz<X
z2E7e5CdHTr#;{9o9r$&|vI+YhJYjz;^;yhy!e_BKrpCsZ773_OPWeXxZC*)!G|Fbc
z16W6WG@G2$8^Y<5I)I*V-aC9OwW#{3pP!?D`POgnDNZ>LwFn*MweF4bukYF;%$^22
zsPvRb=eJ1n&dc~JRznSp9B|8rP<BZl6I$OuUxr+8?dAM!$YrcKK&~BLX<qDzWUw8m
z)}$J>E&MJZ)=K!4KNRJ%9$UR8)fq+4upw!;Q@;Z+kt+rRJ1hYuh##7J0Az_<?|S8+
z$)3B57blgj8QWkE*riTs$0xl0dRq+OaBx)4tx90wp8DS2nK1=IR<Ch%9PS*|@{v+9
z4K5gefDYKx1KcoZwj3Y2XFBkd_=<TY6%_^9F>ZyM26{Cnt@^<aa5^ob121<rvaWiO
zU8ms-i;=ZarMU91Uw`G2Cxivx;5TF*`So_?JRqjn9SzOpsrR?xW45hVG476n#~(u@
zAm0f&x3zVPbN_r@D+1l@0N2VwxS&p>zDk~|(YKaAv5cypf8!o?46z)Yk@P7)dT-eD
zi0{dtY$<PT0*{D7#~ia~`$4ODK%ptZ8xv#on~U{NZ$GM5Jxk=Cv~+LQ-K@G7eXih_
z)^&$su6%rg=xPn-z2*La-u^Y0wt1S?VQW|5Ou%#&*pl7V9k=P9r{8rPlNorKQ&JlQ
zGS>RnclcA&GM_frBG8;iuu4T$lU>g1&jy3w8+G+>e#u9^6F;7<eoCMZVw;(GPum;c
zv0Qg{{B`6Go${)X^mR<%nt}j?auFGcHBtyEW||eS<xYOemc1xvUI)8~R4}i(EOoI?
zDV8Z6oRkc*(*s;Dfc@gLiP!OzcGq6;wlPG!%bWT0b!@Hs$%mMtuIvB}n#h7?()YFc
zeQJ_3Fifz<cmx@C2!+?!WL{?2)6D!JGPo)2Gaa&iDU~Jl;C&j#QxIOhn<{78-L0Ia
zmYof-Xs{j&-gBO1uEhviTNj%&J{FzsGTB;CT|L|GJB`{?XE3scRVB&fcI=TE1o6}0
zpN#s6`WzBo1`+s-31%P32s5YpU!M-4TUrwu_+oY7hDYTHg8sa|see=I#%$XIBR^rM
z!M!MJ)js`&k1v(#&+2Z2+_ViQCni)s!;Sjfe&WU3lsSdJ4WnQBx#5y2Y_R<eFfLjN
z!9c(FpeGZAM8?YQWccJ7t^)*R=b765EooQ&Kl1y9^umKO&{{%=a^Tk<PrS=itJB*2
zv8QcUoqO(De&KIbWsR5%8i1wlTv>jPX;XIBwF-jknVR@n^&8u~H(X_B%9cOKk-o|C
zOJ8#S!*HqWHo6Po=t`U2ZgxKgSPH9&rI8>`yX1rz4(ZC5MqEW-JhZL7A%$KorgKaA
za1P{Y;j%BT6u_n4XPZGDnEOo3Z<$SS7+ILMYOzq_y0TDRqZ`khovpKgJ5h>CVX`|l
z3tWS+?Rc1<kt6#!8y4fytBx-DYNy#i`<a8ou?F9(2s#FFNeOFrJ>S_Gaja_E%~8r8
zy60T=L**RW1Va8an*RP(hIZl^6pRuhHiqP@ypX+->5Cm*dz-NKD#zaYNy#G27aszP
zhLP@f_@Ckn0d8FJUb1t{knq>WS^=bS#Cl9RVd7%8X2;uWD@}Z96PCh)Db%Bc!ICpp
zualDXi-%;vGaK8}ws^tJ@oYb$r0~ehpUL34?8DiND;y*EUIEj3w~#LT7ZYlpL-6R!
z8u-?hlGa=g+@kVwHn-+EO$J{1FlG}kR`5Oqav;BNX56sVNJ(OAHW4&EeCq|Jm0ZZd
zqRoPrfb%Vvb-?|$3n`6v5qn_V?7Dw5I5&Dv4Z~iy1Ck3|TSBV^haC9}{-;g|a8236
zTzEsdh5udIqc$18H`a~oRfg}j7(f$aavOYQrTclO16hbcQ#hS!hkZwB1+Ggkv)c}#
zF8cNc*)Ljx?$El$0#tF*s+`)v^yNn#dl1XBdur>z<rQR?NxS`;{ftM|BTT*jdO@@x
z>TF)tGMG4r-V6WMWFBA^cb+4lHK!)WN;*-0)o*5dtB|b{))V49Xd5blpePnKMsS3T
z2&CJu^SqhzYe$+27*xrP$>Mjipk{<)?tuk<jh$@qfWVBh@P&SF*Yr4I-_}eW9$@K}
zUfrKBMINMfoSANMK}fb*KA@V4jWbrx=C2E=s880aCO=`7c1gr64gdZF+#I<h;b*tc
z=UU$Ak;>!*`Cf4Sows_0My=03l2a3TU(RjJ<|p{AMLshXhX^ji2tDhQ%EXm<)mx>k
zs?0^-f9)fWI&=mB4z=&A4wGOz2m?s#wv^Ks;SPFsqNY4lTPajSeDslKPj^4+I&SQT
z=T2U%?EZu%)(ZZ)-meNqEqv56zpKivaXUFJz7&5Yb0CH}xwSQ*-x+G+I-}6l4=9%W
z^~b$cjcUvqgj;RQ@EW~r@rr$Kbmh~8wV|N-5@v$;vtVK(;Q8WqV^QnCH4xm?;Z$^)
z3v7)zBW7hxJ7`f+mpWZyAsa%ri&z@lMeLx6;wU(itb3JMT8|G4%bM@Bd$fQyZa(4u
zQkpor#7{hUGBGX((<ASN=AV3WMRqrT;H$Wa@BWc{n`f@69D}$wK;&EKD%~b7jt*Yo
z;cX@jq>I+BRQ@{{M0>4ec|4gczp{56vX7Bp%RUU*x)GpEK!uRIR|He!te5*(q}GAN
zH)3~^l|LLlC`XBm9Um<>J!}||Ymc~O8ZcoAGFgo;($3YW1z3+s0_ACpS81JVY^GgE
zrg^qXM1b1r{mM$$64n=3PpN01)wL~<QNFFYpR#$B)QUi}AH4G7T8jgg`cg`N*$4bx
zpiqtzIa;I+iqv6nTVhgeKTK2kOneTIPQ`KsNtH8`MWGJEzZnWOQWH~Cb1GmS`;JnM
z2p|{3-h5zG6|~00Kl8+NI73z^`8LF_d8^SGGf<S}PvtWwJ9W&%svRJdN#w%+U;$CH
zygRF(^X5OP6cE3F<O~Wl+cKfpa?|o&a_QSK?=55%Tqt<*ePB1p2fTa?3TWv~GI?e{
z^0|KOrYW=TJJamUsf;@<26@7<rITL2x5C#ewIyGVW=j|zZ0wcY^yvJ`BI~$J5I~D$
z(KQw}zg7)I?ppK4<mVR_mzO_F>bd1wZdk?FGVR<hF=#4l(BuH=-9!yb_z)g5aYBYs
z<)#StQIcX<*rXh4jiegUv0=z;M_OF6mS$(iP6<|;R9s0Dr~x>mGN3#5?=G`T?h@J7
zfmTIz|0=8SdY3R3sWPhA9lv9KMvz1%>EH91YIKSAN^8<sU~OESKQ3h$)sNL!AchCv
zCYbZMQCXnVs?w`b*2xa%OALHwhjR4I13i(wRW{bv;oQ!AUN5xFK~j_$R#6##etxb}
z76mn-!FpNaCLEKgB8uyGZti`O+m}5pnRV{Z`sQFATYmM1pb2XgxhSwyHv;x9PbDy$
z*4HJPy8A(H+7TOM%tdc%0rOJce)f^4HLKgb%rTl*9Y@H$T_W6MQ-JRmM>}iXWqIcH
z=hNt@h731G$GEoGVpy?_-w-?02&TR07amX&1QghPUcU3pwZ*HQ>s3A7-Kf)^+uQF<
zWsp3I*jj&gJOsEWAww!?nZPa3#uEm4MR|n#G6Qoi+k>JvC+f@v^}nLgc1P~W>501o
zuC&hZ&Y~={lGv3*<r_AGSp|pMzw;_>*WO<@J-3RCkXq)z`>!jmBX@2U`3<naWCm3C
zr@gu=#7k`qBCvc_RmhG(nU>O$CPRpGsXjVLH@$Sh<eoYcBeS^(HpID#-YK-_ZovHr
z`dd}4&9CX2<%B$!y~1+G#%_Mk@($KFKQM0C9J)BBR#K`>k@G1Z3)#$hsRSx0+iT=~
zz8P2QI3fUqa-WYoc!TY$R(tWN^eQy8q-#Nssp3=rR~DUh+&a1fEN<zaA%Iqr^Gc_d
zK1;|=V`<tg(D&YX4N4$740mgAUI`v^h0n3}H|VXD5AAF4ja|2BBTt~seZR+~m-nf`
zlIgir1sTk!`aZQfjh9(7+oHp7;&k52)d%FQSHgF5!#wLeYd5=571$rO(;XKVLJP?E
zUJ{f?xeu1vs*p(c%q{iM$|L&;-4CNbz0oEmyL#cc;nC6hG;vcfBzUJ2h55GZCPlc$
zD(mq1mUfF~a*6J2wN%xpK~B6$_3E<M=WtWyd!_<KVqd85d5tqPB2sH3>eLV$Si3n@
zyYReq@FTU`Elz9K`<0Z^=xx#Ff!~vKxayXdV`9`HeBQT<7jr`Wfv}lahO71d=NbQ-
zSPs6mO+X#-52}lslno}rFV-_Q^R}+WTXe~tzrwyY2a@*P1W_UnmMg@~i<0f)>bIp{
z37UE+gI3d0msVAi>4N1-L9s>GKk(jbFJtX!eNX(#BZM_-vD(ToWaiH(N(jF!Y`Wb-
z#aVn*79K<15>_`2ZcpsKK@c*p2`ah8GoCZGozwf0|077=LZ5N+H6v$bs5-V#>bdTF
zar9Sj^_>HZ%b0j&<;a>Q+Qd5yu1L5A5bq8c%mH1-bk-}(AR;2>rRhM5$U8FN+WrWA
z@jI<^Aa)T>cYZ&xv%b6VT1<>cFm}qL9YXxFA2j`N`E>a|>$|;znWB#2180mh`oYIc
zZE{8`Dyo4g&KWC}93p|hg(e|C5r>4*r$r2l`X=xWdI)#D;5oK5OlwnJl?hz8w-A4J
zFRa-X8xkDn2*d(9+tp(}qcghR^(Aa?4}@E^*=#4rEHbq_t|8s))l$dWQ93(sTwxZ}
zjNi#7`Bu*{{9^}m#8rq6i#wn|?AO<XbD^W!JpZ0&Uhe7LXD96PRVk@eO}^c<>^D?`
z4=@HFrF6-R9;lV90TjA1pWcC<v42wH+&Q9b4?q8C-~Tgg#X1!6w!jnc;RFr6;<Sq!
zf`VUG_b5m!s4jU(zHHa<98b?9sKpqAw?D1j2}Z19Ov+s0;wybw)@Kvk7KLTzB`17b
zx?`*i7*aW>;`i#MN<Y?oQVO{eeFKk<+PDG{F!bssXAFsF!tWHRrTMjc^VLfYn-gVM
z-?ewvnK$RT+M1$=H1r{{lKD!EoQ0!nV>~w?G0jieYf!_sp+^V`x)S^2bD_+S`P9o#
zE8@g52l{v${}1NgGpfn;Yxi~O!h!`Gpj4Fw2na~;#R7<QlF*Babg7|N=?DVSrArNj
zCMAR#M0&3Yz4u;2Xn}L%djI?Ean9Id?6b%F;e2xp1)n^*%bfF?^LMTOx;nW~LsV`a
zn-%+1!+~FM3WkU-hUn2PcA_WljxA`3kY`w8rnU0J%PI<7IIBJtVeos>N2@bZbqY2!
z4LO^g6BI+2qhH)ll<)5bndmTq;h`|4&V$Nim$VXb7oF@CwdsiyNHe;PtFkYzk~WEi
zl~s7e<9oAo2z5V~K>yR#-<p)Kb-pFjo259+eEcYDa#GGkN<M9{mzid6D=f}YwHL9q
zeWV8_3$#J#U_nAcYq5$C$9!r{1D)%BN?G2a1@2}{*d+W;*58oA`i#>7Qz`X4PF=Sz
zPs)iQ1%GExf|E_)L`09i;`+-F8fd*azUhl{oRVC&lGK5du2m1;_rNc%RlU+-G;}se
zlCjYIDcHKO`RAm=({-LIR9Gtew-n0ivix=<qpuE$n3qt}Fb#ePi~fYruw*|T-;0oF
zwjOAik^tZWSEuO1cc4c+RreP+MOR8X=iS`GuDR^wJ8xxN3G3+Q?0=AQ2dv&Qytg+M
z8#vgWw(wLnoqj?}=7jwuWt<L1Y<{*ekk|eZ6!=gv*=@wwc&O*y>h<W>-`e%&YFRAr
zVD`;bORVz4t+q*5?AV!3=HumKQ}U+}sM#T9yz5p9b9?<Ozcx>;mcXjlE^>0@Ht7S|
z;dP&kw9t+O<oV^TY%kL={(&_r`yE0ce@!%C)JXTXW~Q1JmFP=54QU!*)|sd3=4`{=
zZafORgpEmh@!{ki35263`g70=6v|$BbXC~qz=@W5no{AWyEHV0D!+g7XX^AU?5gsK
za$=y#SHxF=qmJaKF8;<^uu<u#p&5z$-5b~H)*a%my?xm~8ub#d8K{wAVr)CMBAh<)
zWX7`e%e`hz-K5+9E`7~A!TD=Z6wUMd2eoQrsVFr=+k=m+T;}%Dg#Jj2?vJ(Kbqm?r
z?{s#nJ*(AeL<agVsj2^2*h>Cw8-OG6^yFYLLPlU~V?ChKO21HS=|7jCi#|-<e-eT`
zfha#X38j{pF6Ep_`~8wwfXpds-YfgXpM4`O%Z2%+<Hh?6j=iNSsQvxF)vT4mdakT#
zET%so3n+j;RmjX>D)c-a2bJjf{qW|nE0NeC8(M;9@{OA6G$bnsRZe^QGw;{z=~ACo
zum@`0ExCYH4Ybrna(?Bg<*~c@YH|{Z+H=OU?8f0ny}A}N!R)nFrYO1c#&P?rNM<D(
z1nb0fcmPVgGK&PR8OPB!;Cq%MYByeqmeFv|7QN%a8K3}j$a+|skEZT)6a5{B-A3I!
znBDDiJKNVh_)`C-`wgn?+4^qacBK}mfa^lkNAC*L@z<ak%YD867Msiqo|nJAPOGov
z+C26`TO(=`d*gb2JN>pueY#fcKYE_C`CB-bV=@|?sQp8}<e15YzE2HrEJ$^|zj$;R
zWM9?Oo9r2y!J`he9Q^29seV3j)I448)Ya*l`mpp;w&5cZQu;E$>u|BPcq%}}suE6^
z2xI|;*q8UB;;z#~GKIPt&$?DV*gHO^Q|5ml#_H7WQ7bwslkg<%i2#&k-qOONpKC;y
z)=G4-Aemg6Hl!~6@Q{xW#oW#ob!|Po@-wZw178Z^_wND>C+TkKxZTybyI~YiID}Q1
z<VR}}49iD8AMGbaBBjgj^WHYLYri+vH(lQlL-n%euk|kn5V@s)ewaU<_Cx+Y;Sg7-
zvGq3|`JJtO_22dRqRL>Tv=t1vyUi>wHU|{Mgwk+5J7w}V_88MjrM88dj?swvp-sH<
zr<jFzd~bKRmIbiqWQz7}U-cUL;E^w%!Y>8W1~m=0HH}tKiUmWl{QnHSE|CyHuJ3yE
zUc=G6lky86eL?Tm`H#y-M`NGwlcz_zcPewZD^Jod{DA8oWTs7cWFPP2sluE>(SrDu
z>O0-X3-i(*k(D%c_l%mBC*5093z1t?<NrBoI}W*A1pby;Sky>DSh3mlzM)4j$b<>-
z^JW=mtiFZ+)RKtGg32O2k!4!cH5q#u;&cxA-iJ@diVPeN6s)HAET~Rxg2eN`leBaP
zuhP^QZ=RxY7CoZrXCLWBw5F;y$^nl6w<co!#+Zhvk(zs-$5;_<WytS%TPu~~nJz{}
z$}k#BO+H_@Ts7Pk&HxTiosE`DV(-TTQ_c@f$33kpPmDM4F0cyEr7bR)kTgd8j#2=r
zZPgQr&FxQr!#~?Q|C(D|9O;C(&ff?#bML^9SA&Uz^yVN1GN>z|DO>XDAbwf!Xje}!
zN7vzr-8k2bQm=vujhg-~W{7R^OZ2Lpkk?_UR_fgokO}QI#oM<jQcpN5NoZZq%mL%k
zU&|kjX!oXQvV~q^NQSF-?^LluNtEzcpc*+}H4>LtTn{iUWFgPU%*k?saiogEZ#p_J
zFPMD6M9>yIDZQbayq-Qepc8`3&E0g6P*Y2G;5+)NByQ}K6(X)P3r@77YtzX2c2$UK
znZ;x#f!hipn&;9eRAS7sr7b2LIjh!)LE~!E38<>Vr5B>i+9j%ox)!b8)uK|gY%zkh
zYTf}Zzg&)!LYNhkMeiW1`VCLPMb@3*`d&>f3#)WgreC^h?~UclnseIRTb&UM+a1;4
z%uIUVQrOZ|G$In@JU@>xgSs52Zj26^leySeH?kz}N^ee}3s;9mFOL4;4)lf?Em^+l
zC))Wo^<>6&e1*h51W8{0lwDrA-AdG#fG`?ra<gJnlGP;X^<h`Z!MCt66$jGIcB$ps
zis7og;zr%I8__;Ap=%n(w|QQ;yRZ4Q?lopeQAv1o0Eq_wd+wXW<eBwrHnXH!%kopR
zq*E~Nq~%s^H(BQcCTUg?YafTffO%e5Fomtm-leCng2&;W*Lt}>SS(r_V|wozJ?BKS
z(rtQf^~R4>jwP<e@nqek=I3Q(6k=pFJ@a~HWi|8>FCbIP#HB0Tx3fAFhzTg?+AvSM
z({+-a%w-Vd-9O=eOrB^bC6DbA5*lXkPf_u`s;=rX)7zYai~9&l-m^`iDxK1{)?th_
zWeW;b1;-t6x$em6ie-OuhBJzhTg&f>Xfs)HyTN?nAW$&2J<(_dQikK^Fqm_z1JwYt
zorY^_zZ*pz@p<h&2(E!{Z7r8Iky*TZDjMhf44qKV&6D@Ipe?X1(Um~^yw0>6bE(cX
zC2J3=ydkLMQ1eY?v9-q|@ww$%qEN{b#I5z_>S_!j{@a6X`XFPX?+<s!;fQzbmFacd
zlG}B!WLQ~|xax}2snmM(qzj~DZD4U0Fw@l5$2}!E)k(UR8u_6B8SyVWFr1;ZF#-|+
zYu!D7bZffz6){$c`x{X5xZqLT21oaa*;-1}>q|wmpuMkbZKCRIL&P$)z+*E3vrgF`
zR9I1QC~x*)=44+0`^be;3bj=DJ+K?E35w~*+x*!R1R7RtY3kQ?t$VE+cbxONTE@zF
z|H<2KDlbYO%+m#OldPVi1H_>JpldX(DTKBPJ~+`+PwLHgoJD=j^|bO=WK2X~Zoogj
z)KryLk5672IhOfa8drZ<j?gSo6r+(12ZSrx=<42UVvLMZu~mC;spE)F?XsHFCT&n(
zEw-)`rL8*Zjms>+=uN5;ZEaehPu1;E6#INqqj6THz7IQsksoR>6Q%SL_%C6;DTQIQ
zWPHM#tA;EA6>Mm}9j)}ki%W%jP$=}r&0I30*UT?f)$R<>3`6^61Qee$vbu(Y^@Ag5
znwbTe=A+N19=k8^>v;8Oi#Tqmn8owk_u&Wi$i>B325?{juqmL`S!#q#;4gI_Ey?Jg
z71nHLDLSs=YT;_$k-ha5xr>x5KZ44Wuq&b@H(6M};>&Q~Ql*5+SATxpc-`gp<;Klp
zOwaG9#1&R27z`EUSQ(Q?)t*dka`PI>bh&te=V;CpQ?1(9<+c0K5nMu7TCctE`$Q{o
z1SV0RU_~Vk_uxQZC!-brWa$u=gKo~J7!v(8`^s^GDw$U?xvukpk=)AjP;vkES(7(?
z0fpqcZoS=7*B6&<PfIxSSUGctPEO0_)pd;UDH9u%eq#MfwlG8c_bOgkW*d)V^TieK
zH?Ll$t4XBgdq5!Y{^g>xHIM8oGfvddP1jq|?CCetx*m5B5(^gilP5ZZgI>E5=u3sW
z*ZfU=9IML@dhWn|AkCCpLtJ&E@noyEZ*9I5So;cm<ExOPG<Y&0Ff=?9Zr~8>E_T&k
zGPYpOK;o~~{gG9x)8*3uSYXl1@gE8PS7w<L)t>b<()IJ=PRn}G<s6>^3JVp5cNe?(
zJFl<1k_PyT|H{(Nw-#<d&DDtg2!6Skm98?XsXld!CTL6$oFbJUwTk)p__c|~pDFk<
zX4zUq_cO@a<iFC32+y#p%Lp7HWD*Yq6um0mr?VCdEp115<lZgvMu-0`u(mON{6s4+
zNzl1Zw3s2$bp7G@OH{d_ZFtvKHZCSn*g0ZZ+p2K+alTR*$y(_0kikiL|AsZTVo4)g
zDPB?{Q&krVImyk<<>U;0X0tN)WBrGB_#vW;PFVeE`|v#gL(sFe`I(y*A780aGnBOa
z7Y%zCT%8Q6OVR6^{Px@U`1<WmH~qEY5{VDvsK&Q1iPEn{1zYUEgz)BH{Su>JHEKAK
z7a@ZcrH!{_P~TOvLmwC@iZ_Q+$Vi0CYRkfVhOty*{}r|bB=Va!+>i;Q;xhg1bQ2md
zK5IGhh>uS|CQoiMbhNnV+6&mLJ9wUeSrg?!+7d>>+AyWfjn#TR?65=86&sKI(y}tM
zXr;u7@z9Gai9Pr3<hoAUzlf#gKPBGnTsyK5agh3|?zN&sCi;o)T2BecA3GJqtI{mz
zf-&KypT!4sEo)3J*;F?&yx$c0MpE{dK%jTzex%}GM`<pg47pFjYS92nld0|xPga-f
z?AFRvNb^P=)&^L9c~~Zq-UDS>Ft7d2ru7SGBk&(QQH&FOK}l_==K&wTd@P#zZ5O29
z68jB23H-J6-7n*tf931o%``Q%hiF9{b8%H!Sxt6?MTe?R_wMO&lNIl_>zo)GE;N`B
z6g?PhK08{9WPe|Cb!kWbm4OdO$WTpuM>6f2AU=d|^%kAzCna1@&(>T&r%7vA;sgs^
zUW<QTHd?SAT|)Y?yHJPLUEiwqQ>jVT!>`DlOGMa3+MiOWm!0bJo^{8!_A(DKH?EKS
z6}xteSNYho9ek{Dto+nSch<xe9Z(nPq``Sox%bnipCb26K8gE<jDd}8PN-y6cE+pu
zWn*<|&i5+W1(Nz+_?!6s7Ds^^eK!|%IW<ojY}Q)ULMI+6+rv0|nm;TcaLZ!2vQtkc
zS|ZtHzmcc5U*PwcGV{wY3A~%ddQP!ln-H1!NqL#i;OI87@_jv15}O*vPRsmQEH#<6
zDdZt-uFMXP*yr>{=Z%%R*5YDyJ#7PH#8li_#ndhgl%*dKKOdSzHidO}boBIMjMj7N
zRi)w(Defw+Z+X6CE31-cvOe5j8%MitP6)c{C-NL$Bzl}S#^#Cy`v^b4)e<+nvN>w)
z@h%<TRglk}7b+<0>(_DlBBjxK8i%%I-6{`6XGG6azZcl$kqpnHcK!Oo{Okcssvdud
zXf`psCt|jxf+wdb;`HdOnlGWgTX*MxqC99dWP*<#j&LDt83>j#>VI8K;OZ(Qx4?qh
z`1I)&dPrlum@0iK@rutwd!0O)e(6=)`led_w9YslIVlujVv@?EN=`~D8dF6+JFEE{
zEZ9Yz2Peu_PR5Xfd8>8Ex_6-St)76&_Iyf<N1<q^f7aY*Ck^WsImGcN^<m<f?(c8j
zx+az&LHNyzC<*4zi{+?X^1hz6Ty?fUU2wR{ptSt;WcQ4iL`tAT%kaq@Q9#AIY0(o8
zPFvoyL3IG=MqNQ+{iFh6pCW9zHiX7m{Y(?j71pz=#W&T8?=*~3^J8iaM_Z=rQRuhr
zZBU7XxbPx3O&t_=cR@!(UAyr6-r_O6TE4o6-bT?(UsIDb`w0LEEe9pVt^L;QSFbHz
zSihNIXAfaZ6ZX2t+ztjuhj0t%ln{0vV|iDrT{T1GByrnIg~5Mu&dB_2^hG{&FlW3K
zrN7<q!V0;1b-5Y-o{~hN%i(l=z|!j+PCD9;pj9kU#5D^`EgUl8MC2n#>}3ykrAyy(
z6ijLkC0~8^bFWXzD$(O;DK><{qT_qGmV&#{DM7#!`mNtXV)qKg&7L$W1DUWs=lu{q
zD~r)GgSnPF>VC<MG__pm(yU{v8bti&DX+_3;76qhhZJ<92<XUg*M6-?Lul${?T!~R
zSS_OkOL}anm%*M2nN!f4NZFB)pY{c-#LdHPRXH6mL+7d$K-^EN0@WE%QqNwE)zpmZ
zM<{(MKPs46{+9M6`pf3=Zhg9R=$oB#m_0;&(t5h%At+H_P1)%PGlRWYy<}4G4R0kP
z7RPVVhg%ncX7%b_6;H(us;b&@^DyYLIX%M2%r`7Y1TPL^2f^U_D%$fv?!C&3_j<{S
zSF-|&z$-LXFX7a9PG~7I5Kc)HJ&aXJm;Q&D(Ui)9BZ+*mJB;{G1CQu`Z8ZR?s0Q&2
z>;7_JA6`8_RQ%`2MfE}ry5{36WFGD;qI)g(ga<(5o2gM+@YVP)x2nwxG29<qqC22c
zho`uA!`r{(C>!7cjew638?8<!Y&S<Bi2b<mEi%b{?ZAdMQ=MIZAJkxNxb*eN#EvpJ
zqE<4H14+p-$YArz3x&Jud~7i(_v%>w6=F*nm=qt>g2XC-&e^uXnjNYFZha0O79OQI
z(Z|)sC0q<LW}pgr7+ZUq&Vk^l{Fus7xOZ3%`<^1~JhM@A3`6#h?d<ICB^6MW1ygiE
zSjJZFxyt#6PV0gO6{uNX%m78dL;wErp~3yd!Ju1szv~MtCHrl;=4Dos`4?pY<+9hH
zx%5udO&3gm;VNO>?9Xmp-n9jl%lp-!bR3PcvUnh5o2?pY$|&N#GFN2tHv;V1<`8Q5
z@{AmqT|bR8R*$b=Yxu&A&FV_#D>-<bV;f)7d1dL<_&hE+`P2WsivebWf3gC^a@a2|
zRDa)f;U}x*xLbg#Vd!)fO&+zZI0e$Xi0w(abEV;yGZ2zU=<ROX3u!V#Xgx=820;IR
zVtG>D%OvPGIrZ`B%9zb)i129ck-ca3ASLaQu+Qps1_p+SE6UHbD+PrZO?Qt+U)_}R
z4zuqw-RNVa3{VeTezj!7T!XUo@vidV?F1ESfJq6*e9r$_)(p4-VDA4_VWG46<f+fX
zQ9xV*x5n$;?T7t{r4r=JrtO)TaaV8MmzkLeUEAJ^on>Sxdb+_i>oL@JRAPEMACRwK
zkrAr%3Q~h5CpoFve<xlyUdgMpI9Aj(!p#>g>9rpjJ)*z@FjwX+L_rnJwPfD$8jKgL
zbupd3lGq3<q!V&EZ|zW9x+V%BiZGO^q2m$Sppd^SXkISq*5bsaD;+RtDFRz8CzeHT
zvVl01klM8-py!DNja931Bc++=&=XROwn8uS?b9*x?sfFU)^8-Xu`%=b6=Y?_`xbw{
zv3kRkq(c=kgCi(b&~&CXa<;PQvB%NE*;W#|ru+!z9vy!xo>?j0sj;}xe2}D@oj3}c
z3z}~)E-422mzJtaA8!=v)0Qfy>5H(0q5h?NN84fUZ?KyqKUqh#QZ1bU0}T#jRs->>
zCgIsjf?6kw1sh-KxL)cfg0~9yG?w_p`fOz>#2H?z5TLfTdwRMLXv7Kis@I>J4Q$DA
z#7`P>fGh2qB9Bo6c?q5fWC%7Wdzm>wd>&3Tf#^Het7i7ZrqOxkbRW<POm1~Gb!vS#
zXcj@rKo_)&P2M{(?7rYge$^{H%IvFcS*f;&22Dl1v9X7zZJnK()h4N3iPLb%e$~Rt
z{OVwB`iG*RdvK#G<{e#g<u#|3xpp>Y$6aD0f=9jhG4n#Lg4_qjsz26-BFu57j|uAn
z3ZaN+y2WoYe|#?tIWso|*b@?G=So&&r={gt*PHI1g+47p>PgSMKWb)zQy0v5{=PY=
zpYN=u220Q_9Mlsu_m3G1QaYJD1wzj%0d3`G6>Ro=Wq%-dsNx{PkMy#q^HMLk_!<H#
ztNy2pZ_Lm@I<%#$?URKSy+pwvD*aMJ?~rHy#IZUYUQ!U8*m?=?l9i5Iwl+C+U*%Ty
zQlJcQ!{Dl`6X{$on1A}zM^33r5#;Ozi5{7Vp-6h>vZ2%=T2v?6H7sl}(sC0Y5~ukP
z<a^ulp8nMA@umkEoa(u?_~SGxJ*!|+2ltH=8J0Jcg0o}pH6wyr`uT_g&Ko9Yn;<Ic
z>}0Rpvy6E=*>K(^v^3)v%%ORk%Wz9FAE~JD#a!Xo4Ql1K>8>jqvhh2W-js6yhch%b
zPIk^Tk<ZV!VEwXxqBo+ZMTfmh$TyvNNcT%OXm`x8AJ3qxc+?=X$xrZJz4+plLHe@G
zzzUm1<lMX30QZzvWLnzV_`|mfvZ1?2!MJQq1aU3z#W799_Zgx4`6cczO-#43SnT55
zNBoIo$^O2>dfn1y`2-!BAB$aL)Fd9wr?D?v?9VS45gxZToT1VbRCIOCg_DZAG#sh<
zyNG>^<Z;l&Z%L8vOqt$J7$U0IuJ5WZ9fYpiV~s#&@2Jf=B1vPl{bufXzq<Y6;~HY(
zt;9O&#0xiU#iAnbN`^~IZ8bGDxr*Bwn>xua{ihc2TIs@rjwjytx~PEwb>YG_>s!3l
zmp@wr3d}q?OvK@GN{@iYn8x`S|C<Zm_ddfrMyZ95UQ=<o4e_b#z6TQ%H$>xC{#r_}
zJaWMvel+@+_<oYQ#{QtC$lt%|<Yerzl%Ee`oM#5Ar`Ee*#n!?ZSWAC3@m?41+Fuv$
z`u~|zzrbZ(^k*>RznNKoKH_@e{}g!t|I;77Y;SF5x&H?mVO>^{UuOn1M^VD>Hh_t8
z!^;u0E-h?@Gk`vS%}b6G4s!3`{{in`PyxIJ%$ZNhzyQuSY`a`cXjt=*1VCVP1l>oV
z2%h4N)$x#oi(bC~&kFxLagE0O9WO60Xk8p7#aZ(G@i*v+{+k2=RuAa;4Gf22u~*3G
zRU}zipPlS6Z$1?I;B=s0sAV%>(p~!;Fx|c6&S!Qm+z#{Q$5Qi|&B4_5?$D6_4JuUo
zpobVR2p5d3G@TF0Ja<X}261BBpn2#XXQG6<#Gh4=XmRbPB8bo69EpZ!a6kJBKv(V8
zryDChB;s&5P&1sGB(9@D&-@>h$OHK<+r`@eca|LHkzG_|Lzr*}lJe%KF(-f_TTsf?
zcQqg+i-AsG`ZEAO)-Sd{4ke&JfeTS}vgf(m(zkF1X+Wctl9sL%tJ_}}(f8a{xaqcV
zk5GD`rKeMI)H7WlqR=VjM-r>!*6ZyI2ksOdB)R$d?x3_C2C!wx&)VO}(F=VT8eoBN
zXbDaxPjQl+0zP@cBhIr|j^lLOBhAT9N3VxltH;K|#@vk^chBnGJxzD`yA!$GThpWp
zYl@7zC)}HZgW+&ngnXRSI*ctM;z>V1v?rh~CJQow_W_N#yt$a$a%L=mVK@kN1KIfm
zWVNQN(J*M}1M#&=^8$XDa}{AtmpHP@$jHpi!_yQ-TXl{)g5SoT*6bgRfKd(bg@%GY
zgtiP>O8FFFfT=nk2y*+JMAXBNSrVEz4_hYBYCUmVuA4PhR}cVdG+squ^%#O6T~@vz
zlHJ`qwOl)rE04rn307l!r^XWQ-Q`6Foh>UPR5i+%8W}TdPsi!k#5<$?_SYqpH8q{r
zv1~4S86f)~JNpG*p~6B6-X0G+va731ck5mSY*x<l$FdEDNx7J<01BJg)JSe&M^{&w
ze(vpZfQ~E8rVY7URkZob3oN+bC*A?{u5RN;H)*Y)lh&Xu86@wXi&mI|&JWT@Zh!-S
z@_A+^2US2;fEP*N_XO~JIx#coo+!P`99PMwV(kQzZcL&3;RNVvm!bD;`<j=V%f`Vm
zjB+Ia+-T-lA_V=-l+SZdqW0%;>re$e)+5<-TdKxw?K{``g4}w+_q38h9TkBTM<Tu5
zrT)I?wPEJFzcFg1+8?d{tO|TH$e3Zzttowa=a*lWwwY57_XTPxxQLsZ$8Z;bHkRY0
z7BSibQwx(Gi@G(9yPO47LbeAT4|yuJzk^u;&`PM2lLLBh<8#%rEfJ-A4I<P6>tm?n
ze7u!X0>ATq-aGSpfC#ENlD2+dwmwwxv6peb9lbe}IdDJz(f&;>>Pgq`W$OvMdV7$F
zO`tu`{2eFq3vyuWgYjsbZqXh$PiG}s;QK)7TCtq5-g5?_;SzI#9!!;`Yy7N-!SgK1
zN~#0izt9OHOvg#*QIHP7KGu{T!7TbDP7nWLtgI;E)DiU5`*lYHy+P|&4~8cO2dkY|
z6$HLhn(>_O4Aw%-s8pflCp(4)&7mqgZg{)^Xr4b^ojl#P!fa!Id%K;FksU}<J?pli
z60?m`Rd986H86lURaIGQmst*OuH~(13%4J&Njyw>JGnPOVaSesmYJ31tF&oF@SK+;
zP|PiwIvthf1PPzv>*>vlW$0az0aH*lJ)3F3U$Z_emJ24m&iDMo!Sk9EdJKURfNPHT
z=|Dvt2-o%gw_xNUF|4A37UL8*gg`%WkAA)ephQj{jKnI4RI)@ev)=UB)IY0V#j|b=
z)q%+iU6i$y6iKXOsLFg;A(pVSGI+lT+6Y?k?ud8eaAmcJN9qCoRD+<!yeK~(A3cc6
z4l)HGIB`%<j#CzPUn%t@hHa`tp>#sF10K_mZj7?7ZhD3L@<jLiB8kAr*85i|sKmjx
z63Sf9$!4B;<1qWrUVJ2!U-!P{+e@CF0f3_Bm6fF<TAJiZxXlHM*^UhrIgUB(f|&V!
zc>Emb$>+^!RrYHQny*`cgVPx4vAm%hMFG`Kr;m*PT3R}A?Ov1Vl!i@_m?}y@?I+!*
zl<~68Me}hK^8qv)oco$K54hZ%oMgNK257d4<SgfnK^PPtPtl~P(A06A<2l&SjCXcv
z1RVByeriWBDSS7%ywDYAp*~-s(^Zu2V{xJw6FUlt&#$yT)rpM10lUnhb6Y32UMB31
z_sJFPyBr&2cJ}j2ra7kL3OvWZ<3M~3L8*cd-3@X{3HzP7?b&992NGRlcK0pzTEg!b
zfJu<|mqB|elB01YoE08QBc`PbNq@^qG~P(y?%eu%xVtC{n$g$SPr=^rP7!D(-N*ct
z8J0c#cnap91iuOrdtqu%vzO3?nT#K*Co)S*OUpA#iz;M=EV`53jog0G2Y$DG)BA19
z(?$3=uBEf}7JZ6Y8GJD}AwIsn-KXl^>VA@JYwI+`@+NF=xiDV(ufFq{MscUha@N8w
zq8gFuSEG_AEUZ=M`zXbCTbq;Jvhu3k&b)k%dRscaeszW~j#-amSy;mPfLns!9RvUS
z_RvPqgPj&I1psx^pq;q<Sss6uT!oMjnDZH`vO0^g7?rmkDQ5r9#iW#ce?s>)ndnB#
z`lj`3|6kxx0JnxqeHAr8zUTi1QPncLeE*xC&Y^8=Klq&>|NIj#ZPoES^^Qc^$=f%7
z?@f2zU~>b2(=%|T*VW4aked6}RI2+i8BTz=8kFWz>t!&2L0F;G{TRiE%DULB2GKUZ
zY-?M2lfTMg^AKz0Sx7|(>jf&bMaPng>2eP8O4TMO8Q_vi$yWo|B?%&_%7JY{FsTa+
z7m&zwt#&W&pPqPnrUz!f5pwPW{Ku??xrL0(j3{-rrwW=xW<-fq4X|s8<1#QiNP*_e
z-)O9Otn%Xi`AP6u@VJiU_SF-7cyq_rn2-(1np(o)YXx6+R@nk@XaO^9IG{t*iP|~s
zWc0I!gITAqRQ6itHGtP=^bTO0$2(6zyb=}P*Qa_my@`pui!))D;1m!R?8I0vFoa3;
z_RWmexLT>&+5%RuYQ!RF4bmWHRHyYpf&SEq1(g&)y{s%bg1zw2la_V?<%}nWWManP
z(Js)-8`r`EnUh@{`WFa%=LM5q??W;93g>nlxR7bUbw(E%nFL?Qs-FWkj{=wV-3>yz
z9g)reLg#8=u~k=|lfyDiq<<}_N3&-6qLo#Y4~re7zqR_gD<&d>d)510$565RF-}=T
zjL1{j`!0ocb1nD-7#NwJRlus9aX*Fw{^1>qi*j$@4uZBr`gz%Z&(60dArOc`WR679
zOWNjj38$rBUYF)m>E-}svsv8M(acQAovfPJRVCuE_Eu5xXe4%%mdB-(e2qKRy)$7o
zucuQ5^cjEojwvsn!_<m`fwJOWz|;rMF!Qnc?ANe@!`(ycec(pt8wRQ<+G<kB{Rqnb
z{q(R|V!SZEhy$T7=sD3un9v7Q&V`iSV^mV|_~HZ-TX>(G0`$yYo}G+G%U@j6kJWcr
zP8K_kk^|*5AM}LVs~1Z-3SfQJoYe)GubLqglR!6O@Oj`ib%`alZW&A|NgNJyrZ*cK
z8G3-IOFr>AW-(UZeSYWCF`0|D*6Fc~1Q-EjX=xX+DbB;BzVHN5Ci${yc+Fe4rGila
zzn(>2RXr$j1^!JIZ6SmDqxDrfrPikaahih!21>_13(IywtE<%aYrrIz>sHV7(lU66
zh`2aSefqr3wvLwX{Psw!XK_gh%nt=4m#^ACAxfN<{FVoL8_sapFgD)!FG4zCc6!Wh
zh-`W;O#^1)GP4L<Rc7PrP5fqTLL@P~YU7+>_L&S>f`fLiJFs2Orke#tlU3KVEzb{G
zOe%JVRhu4i^R6&qnED`ShxnOOVcHNl4Z6?!1$0~$_Vy^d5)X%!JVhlqyEB*?5#WG!
zTS*SXkDd8WNbzZb!M^^FAcA_U0CX*!c7{X$J+zUC=LQXrsN=rhI6h>;7=S^UWArK;
z8eYQs4UG*wc4q0d%YR6$qCQdTmrf;zxn=+S`HPg_Jr8EK<0Kl(u6cr<JaN&}EBJHq
zD6>%WYA?nElY^;&HT*4F)j8XWC#RMB`SxTIN4}R&XZ6omcz9l20-jY`3XD$~3(6-O
zfcF;Ymf5ae$uUmRC$^bW9du2)x!Wz(6<<oNu6}9C!^~W@IOVti#w%7<%vM*pxw&oO
zwwI6A&)-y?)lbpp9Cc{aCXD2bLm*ZTr1(I{2@%q?SLlpKS(&~Y8DIfm(FW+>jGy_f
zCd(dxpR&dXGyC*EDw<9T0pp%SMQ}7QxbhbBFZ>Dq@<L+RRYi9+*rnif(n_t&aTRwV
zfaMGnZ(vuJ4&R|eB%fnUp=ze@z(8ZKqa>c8F$-9jJ(iLJAwf$=%fG(`(N+I%N=jVK
zvzNK`=ch^kKU$^zH)M|G`6c<-#a-0V$@;p7=cC(Oe{!&QnzsV_m+b^~3;qc^l`HOI
zJ)irx=LaBDib8Z|<GK3)@OumWC@ZTHQ{3fWayt=Pm{FZEkntChr}T&gjFyf3%@Nyv
zey?3<HzO;1yNk9f_HI3bzWPrsz+U;5-xZRpH#NRQFHPOQdO%H0H8L_%iZnGfjf;yj
zX5&8pSwZ!uFR+7y=l&4;jqBSP2!sgDwaz;rX$$%qaucs*9M&8e8!JP+3;ylr0~Tcf
zH9(b>A@>;p)gavKiA|lXb51Hou@(%415>uU`W2VKKb+D*P$A;u;};f;3=v;D@_bSH
zay_Facq(eDsCd8}wS~j~HS;@?RC($3GMbB&GU!3pr0?Hv07QG+Wps2@lrBu|&z=35
z=UZfCx^-$`>W}w~uK_Bs_{ZRAp2>IcOuBzygghTtlJ>M;0LTNC)0eA?6AM!oQ1A)&
zE}y@^ANu9vmQpuzc`R>~{zazvSMB7Yxs7lV;4J?aJ7U+Gp)uswFLmLYPS$1?=KY(1
z=S_7^g1WFI^HzbBO3irb!4RSNvWB*Kt_PsZ|8Y9(DU|Pdo@yXjk^dKNg6@VVU0Cz^
ztNiRS?{MW_$Tiwa$I`e9y8*&#N<;7*@D~@{tiPWwo?JTPMSzD`5NAI+N8eoN*_6Mj
za8Wqm!PdX4^wK}?b$fcf|E$yh&Em<H*HUP8YEEWRYixLOA^`a_zE;pJnWTRshtK%O
z^-oH@SPmF*eEi2$30hBp`^l}?{$*PsNW^%ntZt#)qubd?)4tDzDE9YtvcV%8WaZ<E
ze>R9UouIKdL_1+}v=29~Z@$WoZjVcfi%+I_7;?X04^ie&JG%adV)=v6Rg>lNR%ZXF
zStNk|v19n>pAexqUKjWLL!sq6oDbEaGJB-v$<E&oMu^e}@^<fyA#)}Z_AMX(Vd5<r
zO9!n3eb{nT{J-9fJu-{3g)XhK8}I!zWm88JSE#jJOa{(@92aWrPxp`rvrO-?y}sfR
z$zMow6Ghps(laPzFprf5CTwW<8mER8aKa;EaQmMnrnbu?L^%{@ZIfb{bIlR}Be7pK
zlDj{0bcBeC*EZL7t&$jG0n92kp2qbc0Z;#!&Q)`ZT~ygI(JP}zBn!c~iWXC_a4+#r
z8D0Ns34iJWld|_&NRLM+Q`0BsWe;v9=0P*t{NH{5gg+XgiJ8AvW8g^qnBAtBi@;;4
zT*kCS9p4s<u$#?n#hHij?o#MimHF`7Iv64A?<7i-f7YV3nAq=$H+y@m)SJLKu=`%l
zx=-@gx~-{r+{hipfb*mL#>GXL;~Z-_0>PAfwO}gs^Yq#?2e$0&1G+l_(AS)WW?P4f
zSOt=MQHA-bt+6SQ6m;agA-18a0A&E<ENW(Zz*~yq<wxIO@7QVR-Su67sElWSy1gBW
ze8Se!{$}-){E|bJ)(ZKew<BCirkJU)djP@Gx3{I|)zjgVJG@a?V9}?YsI?u#-&wb6
z(b=sKHuNYOdviJ(1aCwWS0hvz8-u;jZd<&xAv=$rO))A}SKHJ?C5EtPVTglDNFB!A
z8J5jiel3-h7BAM+AtUsb8aF?qVgNpw;Bgmv5r7MMeO=hqY2RptC4~W;kacuIQVbQc
zvR7_}N?X4AVceQcvfg-VpPK<niTnjJS5`q*)i1o*OEt#qO&c5aee%T62Uv!AY{*-x
z_<U9rlsIE6%%_BHeVPb`@;&|My9=T;DuY!fedaZ!gtIb8o&m2-&fRrjX7G|+XFWcQ
zHB^T~-P~MT!5zM3^wUUR%UVhitI47tH}H`{Nkw@zyCKtYK>q$a=ro1cE{?yJJ9-5Z
z1tquV)y{_+!hDeVya63wKX$Tyf1aRqKl^@SDQ5biJk%>|AR`29#x&a0zu2W;rK`Uv
z$m1^8q=AZnLuKld$fS4V_<};?1|1XRGnc&r*dq>3%HNbPJY_H3J@z3X2KL;|E3p;!
zr}${kL=pS;@U8MWIq(({Nqv2n+r>$Sk+f57`YnuO|7H9YvFOCS-agi{xb3!UT6bZy
zudgtBS{F}!Kp+^kw^htoTNKbd8O^je<QkdHh+dNJ>4SQX7T=5tm8_B?qm8cogPw=3
zv5@^8<-B)~Hj#JtF-hG1z0#=8i>W4qb1*a86(u8WmKVz*icy26M--E$=oIV#pLrM6
z(~kCm_Rcq*&)N9|-Jknlc`4?y&abpzn)VnH<|?`@u{<dqUVY>G=TfnOv0)D)#>aEd
z@t!NrP@H<1N@Fk!ksyhO>Q1O-<fW};Xk@;Q!p2nt04aH*TOD=C2>{*2S7UnQXiRM!
z?>=x3h|o(;j>$m&1EUybfTi-9X;{X>m2YZf7iXh#C7homi{ufw?LQ#JgND@F6jRGQ
z5#EqTLy-Z4r1o4^2&Pw>Yyxcg$TF4%|MN|CcS^L{tD$s_^lulWO>yusj88#K=2^lA
z$=7e5uW6*M+{smv|8-UW>$_JNWj*f44MwMN69)GhuIh4>I8#`kuvz+Tyxx(q=$p%)
zU|IW4NyIED@R7N4u(RhI#oWnZal17VX0gqFju?7w-G!z?ysHp}QfyX0{_^wc*!zgB
zEIk+rQo<p>78JYMMj+bnR^OS}))lPMzM4`fmdx>_<DP4DF(68(1$sDY=0t?YK(#k-
zTIEyX6bmWqTF0?Z@YW(R6s>mty#<Ze**`!C_TplDE|kPuy^&@1YR-JTm#spB4svPT
zQKB0YAEm%!{FqF#0(Fp@^pWQIuPSjd2}xPXDw9(d*BRq_Y6SF1Sh0&A4YQ<WE;<UN
zzPa||9vgsb+n8Om7rA3BrsQH)><w`;7mF<91?Uh}$C*uy7uT~IgUhd&N)8iJr4U)x
z?gee<m)TMKAqBAQ0`l05EG5#eFD%X5%vQ@SKkFVG_KGF#220D=HB9yKFN2Gc-S#?2
z5!Gj0k$|f;R#)b9%Xq6<6Ee7F@g)yyQ<WquYY8hGidJOOZJ1<#U07OnsH8SvidPuC
zpZt!@O{;S1u35<dPC)z8uUiNb=ZCtNt0kWvRLo{KpFhUs0cY~W4mdQwhewaW#eK=^
ziP}@c%%^AB7m*y$D=^3;&Gw0=zWE@Y&cXeSqs8HkP8=zg@@CkITUyoPqEQAT%>FX7
z=c9MOVTB{hjfF)yjr2jD^+CnsHq1>tA7vE6MwcJcf}Q;Cwn(9HKz7dR((>bUB`i1c
zBB@x!(+5oH+Igm3x(+s$O2hT{Onn4y`Pr%)4Z!0XR#%Uhp7gK#n&uDEAY~!H;A9<_
z-Y2}ud8R>5!FRSLGqcZGrPi~U&h>}DhT8o{FsC4=II9T5r7@l{<Ft1#;7RuBB7iMA
z!(Q1<y55p$P7g@ahpAw1b1`WMz(zl1ZB7g2D+Z)j)v^|qq7JKEqn90Yq7{?Y_bwyD
zd^akCm34UCe~|sHzDU%<+UxFFWWUzZQbW+YV8MI)rRlgqg6JvvEbIX-v;4FJ8|0^z
zP)Yxb&CXm|v|A45tXpWYU&d<bM>)JIlF|}IfelGmNtfTel@%oWMGg|9&Y#UMo64||
zz{E_#pbUV#k?3?XOSnYzLeHxiZb#m@gda3DYk}439g)_kPeD;xAK1&i+4D2!?Zq6|
zJp4<?OW&hd6xDF%uJLr;J_;PKw6jq8<MXyRlo_ePw|cu4zDb9;H*Y^qlr?3RU>?6C
zBV$Xdh^$e;sTziQK=G+FRYA*43`<JAcNqB?TbJ#gs++iA>HV6o)#Nnao25uv>$so7
zIdtfoQ`RRE|0_$N?~{VAChz=1<EQF>2S6feLJve*S7~=!bS?h!<0TFSFWQKdaQEHk
z%=bzaU}bF)RnaRnL+|v&6b%aOZ4>~C-+3Z0INEh+ewbCEt|r~K^>`SG36#)$x_*Do
z&`Fq{B=?9-D)pZ*HVFZ-H0`U}fEIk35om~Dg87>ql?t+YmwtP7y=1M*WiM1~VCsee
z3^sg+gTdlLieW~1TBF=%hY@Wm2YXKTqxNN*>{25WO0a`?VR~xWPr9Ck@rP2F{+Of%
zj}RD;USuli5?_XesxK3^rt9-xbnJZ{)NQsz&Z_3ACdun5#y{-eAS=D19WJEnZYGsg
zAw(N0cua&4!;lqGIO!XmMR#9DOT6{ppxYdwy81TVV!iGFDfm_oM6{B?J>c!02(v&p
z)tkjpc;ZnO+WkFSQ+dP@W;sH18<T|8m%p+KAa(+hGn=h7o-Bx77NPS^$n4!el{o;_
z9nF|TCb!8e>HHys-S(Q|ec-IEm1~}`F0;Du5g}~yCtFAq11ux2cPZnGX2X-qc1z9S
zzp5-xyh29{#yE@>9kjHJo6nJI7k=MdDuMq7fx7C#Re+%@faCY00q>EmNEISlA6%@<
z!AyRxR7sNE=gm`I`gwWiSM3XcjKy8CvGsK^dBk@f)r*;1k?{|_mF#r}IJ<W8yn&s=
ze;tPQazR3w%VT#V8-(bVN?WHig@ga*V71&Y>LYolk}lqGvfe2dF-rtV)St+Di8<&2
zJ9`}>xpI8b!`fC5oLsG5l0Pt*iGQ<!4^RAO{AWeWn`Kp1A^FOTRMCp(ALGdHw-k`m
zu@40<Yk_<Q60O);_ZG3Tvf_&`IgkCP+zfyFU5<!^BzF1wQn5W&g+P+d1C?COb6oC)
zC7wo7zw5E>(cf2?*xuK*PFov&{3u9st8h@R=1)R|QHjb%B31L0r64ZSSqv&<5(>)J
zq?pM5=<x6yFJQbA6hyk4@rQ6882QpS%~v&YCqfnSfol0-Xj7IEo7ahlr@^aNuC57c
zd|+OhhbPtie6dgIWYDPS>rW00WKaQrilmt2@F|+`rKyj8tb=YC3M+Vt>CadIlaGjq
z0RBIGjukrRDb{B)Q9lyT!0tr|d8D&mq?tZ=75DnjoP0q(d&A<YAtHvN@cdf7z$NI-
z#{p1uVe+(Ao@L&V`LH|1*hMQV!m&@zzloqS8C(%jzii9syr&;wua-poH*4~tq2)RM
z1^->%=>H7~|No&Y`+wvAjE=rNdDhXy8uOo8K%G)3twezr@OA652^~vJ3}*;X0&ZB-
z-p;oI>Z$ThiM1XY`uY;?BLlADJE<JZ2g976Fjbci1KBG2M<>8aMQc8OB)&fjF6e)s
zBJ?4T%kT1{5+l9aT=#g01FezbHr+CRsxv;afHG-dkp3{c(CViQYX}W6`UFxRm{dLj
zKGacBb48akoBWyB9pEMC(QEPXKKFR}lK6{@xZDgwjw+9Uw2AqkDF-}q2uWzaW+@)`
zNc5=V`Np*_`{$|P!?=eJ2_C2YM&&t0&Vw7{n^vQGFj$T0ZVWJm(uL!ran8m-=K~#0
zArJS_C?Kikxx>d>i+2PD^VQ8%9sXpjH(Wq*Bfa@66)33^yG{GEfTLfK=W#bZaFtpg
zDLJmbp}73e6vC`jd?qwr3|h9fJ&9Y)K<u=1v)a{l925RN`t*E*Kfg<rn3jpiREU4B
z$fsyHPkzS}`M;EsB|dQ1PSye~6bPzLpldH+{sF+EHGH`jqg&Q6AGAhD%d0*?4GwNd
zSpP^(wHa7afiNjlzB?Lt{3<A~;k?Ypp}E&$pu{gA0F3EH%?93_@5x_N4#4jS^Z_h8
zIw?eb8ZDYVy+UWXR&Ab*DZuPCd~p=85O-SI0uK$C*hl{U5~s_YU^?ZezJ?|&a}YG1
zwl9hkTl4bdU90s@)6Wk5ih~XpyOOH*c29yiJ=WU^p}_y-?K9W9HdfYa=ZDv?DMx-E
zh^y-{u+$Q@-cknT_#^Xz;$}1oCAPOU`&Plvj|6~jKFkG917O$0aJlJX!MIhvrz@DH
zD>3fmhG0&cv@)4$PQVOG3Lo4booRR+nuP2SvO8!oH^+^+)#Hu0VS2>>hYZQW!Q%e^
z)*;!vf`a8bB|Y>)&rgtdJ#r@2BSi*-oSwU`JY!=6P(77iz!o!Xn*-zjtkpA_dDSz&
zm955OIjc&ue=1*M@Fz<Uw^)&I+tdf0K7@6#cUKVkqh+fE;4kx?$qfKMV>$Gq5)<9_
zmbM4x?z{Rci5<VRw^uMSYKq+;>UiiSH{GD;w`-gGaxVYnB9Zz|Hio}lE~qn&Rk(JW
z7Z&#Z>>F89N&j<K_~@mXCpv75k#jZ8+Nwj<z>960w~ga^%hx;J34o7^-=A9&HfoxK
zf|Y7;kr|VKAvK7_j;>FFkzqv2)*zj@?LWL81+og#YDNpcNp{r=wA>GtxXgdiNa*b>
zUZLZz&&S}#T?ui3vGs779&^lrh`e(9JR)BF?0cCxpnf~E+Y@&KU51KLhti7LnFJ$4
z?js!5RZ&W>DdBkhP2eI0RAy7l{S}E!Cbj`;U$MIC3OFDq0l)9l8c(7lOcwAVJ^FmF
zF-YGaOOXZTKIiPkFZrX6OpMF{XQr#TcYe{QNYncrd4B=0-7!ErK9L6M;65bfKtqv#
z{oFg_GyK&{pZ+~S=Tk_yD{gc+9}A$8<DkpB2pH~xPQX&2CUhKJx<V$g)l>iWwOF?@
zCjpHv^jOD(zGsr>M3Xt-y95pgH{fH}!ONIQD{!CXQBC>IJjWs&m_2UKHfddY_eKSn
zS<;IAMF(JWqoK4^8ZN_k|JasT-x4~mSpnUYznN1!x)yiW$I;z?BXp|>CoAY$aM1wB
zl+ypu%YfENAkNoSR#pba7MAbqw1Y`vI3d~n_!cPnPaSN}L^8Jno3}WCR1>kR(!4h}
zXZJelKLVNgrPI&-cRoEsIQ7@xWnv^jtHSK<9q&Qa2Ys1#U!Udt_&K#g-ro7MZ(M@t
zd6qg-0;=xL(;aaR{jb4Wy5KVgT-hwqB0@s4bvc;Sy06ZTvrL&;KnV6csM^f%<tu3K
zZV$PoXmqQD<9jOoO?nZB6D5L#)6B==gjF1{M75_2Lp+k;WMHUCP32-{c3t@TP;GO5
zVF7&g6qK<}H50(hC9rm-CMvMwqgXeyn3((Fe0#F%`^*(gsgoS1?uYXOSCBH1*mVsw
zM(FF)f0YNP5w`(Qbe9M%cNl&{AiC~E&;n7fpZx=6x=TU)PD*b8<oRGq-A{f;h322k
zN@Z3EKobRuXZ@nGs%j;$fg(OdXpSd{vuh{;V@IHs!x~afJkEmI)a@1d8-wO|GGh&m
zE{hbM!(@=j|CTPjf%zCr9X5J%0;I&qu>Fnkv$j<$jZ_Z?dGT-?gXWm1WaS?t823f6
zrjis9{|a17cf|!7k)TQZB}xqF5X6<(jn0mapD&5BpIoehF9Wov;iQb+p<(RCaEVg1
z3W0c7r)`BveY7`_1s21^*;GBs9tA-tmTl&*fIeP!r`>#e@@QBgrl_oO(51EUoO77d
zVmG%`BmhSAoZHnD(z$@<W7?Qji82SEk>2KH=!)whcF?l&bR_UvJXOLzz2F1lZy+p#
z!~D+&GxkX@${D6|Iy>k-!_|wu47vwQ8`HD$lW0Wk4i?Xj%~LovM52;o7VLz`1Md5d
zS;n67I&>^qdG4AUwGB>a>;mA|_i50w&*&Th@EGpmAgt;GrcS+E{?1lbPK46{I{x}$
z&0%(SJuA6je>l9j_7GJ#H{WOi=;hkS!TM*4e9(myu*Pn0jpCvAn7^L=HkL?=kH1^f
z#$zOZ3~bKsiDPPNi27&5<DmC+VT-P3ger&1Rp)!1DI&*_^k?7CkKCzGf(Z(EXfQW8
zW9MTziMYX9GXxXp3|<?=xD|STL#6@~si^q-)EmSx1SH+%My=bjVZ1Gv2jGZ><ec}m
zDFzq-^4KI1C-B75xbh&4gy1&!3fv)7YV47!k+$uIaujFl0=0BJe6kJ>`-8PRjefg}
ztR|YN4xgF$a(2vG)8sI2n~P6WA!IrngZ6`Z>0Y3#Y*A0c@O%kB*t-jz9T3nfL?bJi
zBsi5|s$xnxW{Jf+wqc`@DJhiO&$F$)B!9ZUv(VL*mX@|uR3wA!OQMtl!szTp#zBan
zx?ci*&4t8G(5Uw(rmve?BOw1&qkU-V{v;*;n}vGGe}De}%pmB0?}zIwk}UGYQwsl$
znlE{Mo;-i#3+=XoiT`ulECjxj{F1s&0@?|f5bB+W5f?sK|0DM{s5r`=KhbY0!-a94
zF_Y=$Qc5aT=^P!+Wc_a}e?ddd^(QR8HZzhu&&T$u=u=6PUvKkXUqMLznjGrs!QrxC
z3UYGo9UY?D;peFIUllK}Au$+CP7c6KTZVyiW_<dMNhq+=Q~mhqQ}&=R=)$kA7F~%w
ze}o1luQZ_Gp-?as=kmk2FE{RgxvtnIcN1@a1lDDIWMt$)+qo0+g+*bkAa-DYS3rPG
z#PFjLV;)h<dqO&QaH!|UKom$m5)$Oh&Odn1m7u$%_mN*!%9R_Q6Pf;z1c7Pr;ONA}
z!nRXs#2@)5(JL{L#_zh+4U(H|kMG_|j3TL-Fp{c2f2R2J|0?k@WHV!ulq!fC_e<`z
z^$!0PtMs>Wa_Iu+1``*EzkxdZK_kh=;0MS_Ne_qsy4}Cr(bo2_E|T&+fSSef@5`7z
zU>^lB*G}+2WMuTbITu1CB~;B+dwvSP0-jT`e7{DtwDBS=EPs5TK6@B?`vV23&En?I
z{rz_byH2A2DphP~k?$tJzG_II`0{s&fg+dR$#Q@8piljt#3KCxLI^wrH^H<w<-CCO
z*~8e(<Zh2p1Hh=CKkI`>*H*nlDeTVw{67q&9{n+}`d{Tu{_rf3ohByz;KI&X8^bJS
z?Zv7Q7b~Eeu=BAn9+uJ$46N;zl`=Z(Jf!~|^0}d3MxLIx{r$WlLeu!!?VrG(fcINc
z+>EVF2oMAlN4w(s<l%DWuOM<IgT_gl(6PLHD_onjqpbem6!yU3?6U;rLwfmqi*?~&
zR8-n|r#&;*J&f>h{~THRfZ{e6qRBQmI6s%nxp`bDSTWYp8r4;l0Uk_y`s6R8BqPK)
zU~3vaUxE^h9<eN!)}%|$o8P3MVL+x{4xK0{68a8>b3^X#f8<IOfQld|TV>rPbbt&*
z4!gPVlTsq~23V@YaPce5(W7>#(REvghlzHYx{bw>T08HqD>~TlJjnr7+YZSH<`=FC
zln1NS)l@x~?ZOj!<Q4+g;a%z`g-FvI-=fc><6j|Hd_q|)rS%bnveNkN0phzY$keiE
zgqRv9$wjZW6=|Xglkn7a+kTKNeJ)vdE3gr!9B%B4nroRca`Ym7;JZfJCr(p@4`I&=
zF>x?5b1(`jgsXus&A3-clT<yfV~=xigTU-O#u^8{5|JbX>xZ^ns*_Vm?IpFHeTTEw
zAQv9YQ;GC(`s(i%O{<P2gO0^d1mi~6JGz(4f9k?U2S!GcW8yQ0SH#R#<F&O$d28C|
z<z;t31-QJbVz>rVmuqNlYC(2zi7t$-b(WOhcC|BU8-ptdPVm~G7S9PB?s=disf!>u
zjV-ezcPRJ2F2Mn}hdU*GK?8hFz%#++3xgdqEIR>nUw!EE`FFg4vSP`}HhX^Q4jj^9
zZenKoiImUf#@}Nc>Sjyh^~PA-LSf!DOKU9k>rbTY(j{m<xAxHvx&d7O4W)e3NF~>o
zRnj8$v$zF7v-U-o4vg_CVOz-OjC|?I_}Rb2$n35a;}=X5vWq|i$A*1C{j@_Bw`ycx
zf5dvFc)pXAz4bNJvTeHXkAB;DjMxsG=eK~AsP+WuxR#M{I$K9~k5|V1)V3y|?u2H4
zEzS5^8hVQy<+DN+kK((Snl2?Pl2+fkbtp(1+LOFv>eBw+bk#6}89~SjHxoS;PON|_
zv6=A452r5hkc$;LnClWvMHB;qZav@tg_zHEvtw+rPbH#Y1ET`s+44E`^C>`Kakz4s
zopsM~g8I(Ys)KwR)?JjZ?k}~+KgITxY9|fD2FNYRg<<8;7uD4~JQ}GtdU~?Vr`bWJ
zaBpxcv(Js!@E~*ho%arkkN0o~-uL@DA$1P-qt95+LCX#mQBl{*Vd>8q@i5Tj01E5R
zm{~KG+c1Yjv9@&|H#C?1rxw7QYr2!FAhn1b>EEF46<(2P&xv&!qpg$9owPlw9J+25
zHXyGE9YB>OuPn(s{{Xt4p}7UU2m=cx%T2Qng@x>C83k{CG@5T~R%n_|3(4&EJ~90@
z(PESy7h=Gf>QVZCk@ucKQFh_BAVvfPBnt?r<gAjj3Ia{eNLF&rbW4*|1Oy3^CFdL^
zL(?EhB<GxS1_@1U=)3v8b57k`H8XXlZq==+8h+XKn|8nZ+4~9WS!-9PXeY?UJhLi6
zM*}G;#`%KGG6DNyl3=FH%uRXEJH1}~9i7CdkNj4emIa#+dFU%)YLQ~N<8Z{Xsj}|d
zx*@7K&O|qO?pK#Cy(Y<lxj`p|yP({+UA)|FeCoLa^ihCTja%AOU$aFP`<(^W-sG^s
zv5rlDbrIfvC&x`+5*i%@=~@GU1vJL%iw(var_!nJzLMOPF71xE%fofePB*2=%$wl-
zEI-0is@pC0j7Z#8((aLo(0e24LStaIevmJ%$r9HQg!@8smXC~zt)6_@Em-?!_kv^G
zVu`h?#-nO>x^#~a^?}l#lR3_fK^H)7EPv*}Kd3goJg8jqTUj$66ey-$vDIe#<9=g{
z&L4eE&z?^$!{o93uKz*d%X=}bn#VM{4`~uVe|pmU(hSaA{hExRDL|aDwz4~0{=Rw#
z2~yhJvoxKav*rdL&xmH89H$1iwt%x`Xq*~^iM^%7FRzF&rWfx}c=JZ{QhL6=M#Shr
zZm(29;iq{$fx8!M97D&f-DMP-1sODHywtRbQLlGYa&QCwN>qN)(rR;pStP3T1Ww$X
z)X~-9^oIsG$Fk8@67goShT6RJ!50tCtpzfae15t<R&SbZem*^w#G}hsb;=Kds9Qg&
zq}h~Y^so~XvC1`_TgLZ4-i-ep^<?6>DU~<tM;c?rl72~*r=a>k&X1@^)8$un=jM@Q
zWEi(@n~91q$?v%AwDHrba>&)_GYFGA<KO*~$D{q7%uwA$onOiqW~)|YAWA6x&Btg;
zST_c$_1(G%1??=356kau&KX{PAv95}ATR6%cK44>^Wf#NndSf09;f`Gai0JsPGReB
z`ZVA@u3??0ogcC42Vc7Azugj&5Y|+yIvaw_h?Li3{hteayO-3$RdMnQ%M4c<!FufR
zyh0;eS~klXp+XDyEXt{<@68lJ#I$gcN)PK$HrU&nzQ9ju?rLS@Vu$-l*J+v!JnvK4
z+oS@u^f!+A4)?0)ToC&4vjooYK)JcJmHU>-=KE1^r(?>Cc*b*6=?0$4JJ{hO{M_T9
zTTLq7hlwmDJVH$kITC!NiOsO@WVrH80?v2l-UI?pX?IELCzUQ{mF}7uxr}`sa^>=8
zyZy!7gtryUzKI$7?Wq{Zl_tHHvJrEcQs_%!v0l47WhzV~sS$2$xQkN-N=p4ydFv$t
zm0c%iwHsMxmAHg_l|4ZMR70e?5AjKtvrg=~0)`R;$jm3gHL0Z>EH-;8$d6Y?Qe59f
zB^Evx_~RB`r`OZ-`uM`yB?;ggTIDi3(#U<aPT-X#_y8=*xG{VbR5@8Si6@ji{5NnX
zpd7#IiW9im%}E}}&6PKNTxEDY4Wr)P;^wammy2Go3C7<u4T>Pz+k&Q4iJ>NmB+F#*
zyYL;Tv(;*>e{1xH8WNES+)CObzGU7ydTB=fl8gq(*AS7wV9bHD8hAW~EbPWv8WH?O
zMNi8VVK<w!piS{CWbO3intmTfv~+SDQleCTXaq{sXQjmbvi-6;G&jcKPxGqMR@e4Y
zszgIqt~A$9;;a+52$6Sr&j{;qH#;ki#v{G*OT49S+9fR!siu!v5Ne@(gx5VS+X?q~
zlNZH3jez`UjWN>jpo^-Navrtj9KtHX?P(?`Zdq)rtJ>V+)*^kX7wL1PnKhB59-Fb`
zoAsRr{$@5=WlkUIT!Q}L3qPJuS_P}FgZ#kFyKe{tj@52FKR0)USv;w%H1drMax&18
zo)~M}Nl@PI$hVGvy34w$_Ln@gH2JPA6OFqPw|)Hn>g<o@(ujf$>8Gq6BW6zJ0i%`%
zFL(ki7JR#g2CZXqx@3-i6s3{A*M6I)+u@osFi1&wGwnSxZ}s~lTW8AB6N7}!px0+?
z$!nM&ZKKWO)fHA<al9kr)5PLgtR?Id$0`V8?2lY02ujL<mIQ*k>e|`5vGcPh*t|M@
zCn|2WxCZuT%ekEI)M8o&-neB^X4p}P(UreSpBoc>Kd~E@DUX~PqbWJ4)KyJ*E=H=e
zbKB;&gSQCsS~%+0ylW`mhzo3_en-Q|Ld!>-qZ~n8Wnhjvo9rp=OwGUlyt;`rr4ZlE
zDO+@YV<$sG#NJVEv#zd##Fh)jMjuD)2_tOTIeStY<QZ@AEIqe-i}1@@%!hS9^VGER
zsdYzaHLmV!n8hEB?|3MJF>_-JdHGU%PR`+61)ss@+`*3N^F`D|SV7SJFIOrO_zmwU
zZhd-JcYqyVm(Qts1NnS-!x&VuNfO~)NmE&vd=(2<qV8E7B+4oT%f)4|J}qQobQKSk
zIi?Q7LrxxK7g_PjaC<2Jb#-Cbx;G|=(pR1e@Uqh}faUFpyJ1h}jlz2jjUJDNSOD+L
zw@HXRk$9p{EA~kbhc9t3Za*|6a@jn`>iqn!gI;MuO_fU1K*3^aK7H8>b%XuNSDU*y
zN=Y<PNmb<vH1aUB_1)j>$l+nWJG~t5COLQ0<p&p<tCfSmF?O5rEmTWcOdi&S^9H=x
z>A#Qe6R8GkY2@eH+Xn8ri%+VoLa7iAVmqWHgz(*uQ^m)svZZkSlD~DNSrgNRfDBDX
z8h&Cha?&2NN3AR%Q)Z<@6`c0TUP8xfd~9-<hAdMx7OO(!b06{F^X+6Fg;d40T_%v*
zUf=%_WsmB&?}=ifhrid#iu6|KyUp34rM{H5SQfMg)Jsjod-4Jn&1G70hHgb~MjaUz
z%~X_cmR)MP*{OT65a;H<+E-XveH<W(Nh!?z)~Mjn{_AsnFjv=9eB{#6avbsIn;G7g
zp(%IC%NswwKCJI+-+0zTBso+02I@O7NxltJ;=a${B0mDh-otzGttdoaZ|)Hii|y+e
z-v`Z6WkN*B?<3`Rs8YiucJk2+*=0E$gO%^+y{RMP;}Ihx86oF3T_+)-ra40+Bd7D!
z0d?`)$CY5j=7e|IWizULkLBGIBMENZ;Z%Hgk`t?REkyZjohY$x#DIk9Vi6u|ccvjs
z$e2Rv$FBKu#BVdzdNaX9{8<iSF`Fj$Y5d<fEoIIb4pY~aU~}Wn-A>{GybP)L0-Zq}
zp>(v><%r4Pdu;IqPi2MLfwt*!O_W~+`Zzv2n<37dh%9|lvV+ZYil4vo2O`;@%uHr@
z&6UEQXE362g-<eaXwfRi!i_&fJ#<~O{Q2Rqi5<xb<4$4cruxhx^<~Y<#czs{TQ%?1
zV0{LgsP{%Pu2Qs0M4Wtl5QL<}L|k5WlHt0}?;{CNM!bt~DbYsGZk}0tr(P6X?&O@@
zv?%9+^qmmpJxq!m86eUTwd<~9w~r?vd+kP=bBE2vqLF;iRgP9^fUA!7_ii<3-PX+_
z^FFhauSKR~foGn`8lFy#r&ez98JkfGDg&pXP<YN*Q5?{a7ab^?Z>9^R?%lop^z`jG
z0K=>6nW6sJdirQ+V~eTWEF`eQpc8prV3AcWr}TkEJW~gk>4=uT%-v+dCGqX8(3q^5
zqXUQYQ67AZ@Z?6;fD%|e6L0md&6`p^c8m3Sl=f(F&?MG)6(@7y^N37k)8{g|edsM_
zP5Z>cTmXans`NgaOrtdm9vz(_kLH{q73h%+QBbdT#3g2OSf7bbQn>svs_|y9tn;pg
z##RCCIb16V61%h$C*{g$k<3%@X|s+CPNeZ1Sy8AYLA2k(VOKiX;i2oWq-F6HSA45O
zw0QFfm(D_fv*Tz~an|0U{y9oMB&`#leYjk|)mDQt3wD3bY%<e4zOy*_bJk8_^k66f
zosJHT=<9ACL`AG3Z+@|uUHQ@bu9K3lIf<0Vuc0T8crvOl>iFKiqMFX`=r9<Yw36J2
z|15s9K_%=l`E{=Rm(Zdofzq)T1)rPZf<Os%vI@!%*AW#$!`bxo2eretI8OKF!<A_K
z{BV_hVRT?h_DJHDuFlXy!y1jB<I~OIP<Vg|qgf@uj*YxGsLrd|*vqb&7}V^0ApOeT
zKTlgV?n=si=I7w%A_*Vck&RmrZrM{N0+c$%qul#jX0KLefPiA1ebC;qNuEN$r<_K&
zx~j0*byG9s=m1B(Hy>}6C5e>{LO=8?Zu&eDq7-m7ylfX@8Ela(H%$w#C?L~ZGJP6j
zn6<)7DOkg;t1I8N1<!rPJEi}rY532Zs9sd_VkBQ@-K72dZwoA-*Gld!dx6A6L7{+V
zWyETRA7KegLD7l-W|?sEs;M6>G&6emwV%Yt8bZAWAFFV-{LjjJe0qHvvd{`z1;wBV
zuAkZ$lgpkoLSn98jgS5K!_AGIqd;!t*?LmniC~_}TfMPD=j5Q^Y$<WzLVKM_(2KRX
znipYZ(1lG26|#t+SAYW_|MrcZrcSQoBSY!FJ_uo>l@#OBQ3V6iuhzX~dN=)Mmb>2-
z>8#ZcuN{f{!Mu!`jUW#DyHjy)K9`1V`v8SNwyrq!>=4R^y=I>EMl@)w|1^J+DH^3|
zw|K8i!MM8%qW)aC&dBynQm9Ctr(JgT8#7B1*^1CNcjA~kx1vS6BvH=2Dif35?~hE}
zi&Qk#WO#$v3KNt%iuySPh%|ZgMFtBhSgl`gv>pARfKym#N$Z*^QdCN6SrCpf)zrNv
z493M2cman4FTjnvxTC^_PZ`<o-CBD2on=Sn0#X+5Yeg8BkYwE`Iu87dcx!Y8*JS1~
ziH8Sb<wE<tq5tQ)36%u|Bte*4Ky0<kqq0N<F}%kbyg~AQ_p)4AZx{G^_r2F#LL!4;
zY=7Oxh*{rC^(vku;yyIcKkn_2(|oSmW-r3WI<*Y*4{(exe9Ya#+hIdEqmiMV`z}9_
z{`^+|3iR-0c44<Vto{deT)Knfiv>1e6~B@U+_{W^H3IHVTCFHP>kq|p9R}G<>_5mN
z@qF<p(KdgdzrOmoTF5ahS%Ra>O6H>Mh9DoER%92+d^{BTGMi!N{>%hl#j}E~_5<ke
z#^L4l`Qe|C3=fmBLS9Kf^74lu4$IRhSl#|v)@)d^{`=jkj-FO7ck9<U%ic*Q=rjI2
zR#L*j9Shz&pUIf;&BclIl)D@V2uEBdPq<OQVCj)#rOh1W8qoQHV~*~=;PPVTE3X;J
zz6T2~JgAVShNo)xKv{Htdfw93y6Uc)qFb~#A)WZNaKY;&9T-R@wbCmpM~$(b<*F1Y
z82`?l%@G@C=%6gub}A^JLM9^~fBWFvyHCQWdpEj^p4L)bb)=sZ{!q1B=`1~_$w*hL
z;KrT&^+#DS2fhLl7<=AJm9gqAOHVzIXDoL;Za<ng*A9BBO8^_kHy2ac)=>OLwjIh{
z&^0sAa`>&VUo}maXlM-TBlfZo*iE0tSw<Z<dtth!Q%->F{?Gr+1t?bP5$xoN7pwMN
z=oV<{lG~mO8p}dOQ%FIK<*llwmOdv`>puGOJk?cZ*5#A9xsy?wzP4KZ6kD=kLd&<J
zqO=@p9pnaOGwuwzCT;%FpI(I!Z*NO4lfSE!WQK@BuR+8~)va|}<DB2^6RN1Vt>PC&
z^4Y9O)-j?p5?wXeP1HXVFY67x#t$yfcGGgqbu3cXyzF+{za5@~DDPLT-<n{O*Xmi-
zKwA&Lh>F|D-wu-cyoRNwSMlAU*maw9p2s%pTIol_gq9*Kc9s6U1e~NCoD5Pjy~?YF
z2bgjg-CxC#3rxGR`4E3nMHHup@*U>KU!U#<-kM(gRiy1>STa_0Vu&%Uej4=jbC6yM
zF77=p(pSf`<xw-yRXU0X7={4<9~EL7vT_TkiZD?nWgw@hWPRFjD75AR9*^kj6Qvdx
zjft=I2QSH@;*#qn8Z)PtG^vj^uHXat8U>7EsNAmmhA9qx;t6oUIO6r9*mtYoGKs3L
z{=jRr%v|KnK04F;AP}G30!J!&yY6pBY(qVcuBsdsS`@Y4c^kiuZc!=k=&!fZP3zfp
zthrP~-{fI5>p(AOeqrcR74k;Wh_)+04dk4g2Mp{7H&FW*DZM0?P_DioFWW$QqE(e|
zEGN(CxdVZ!hQ|6K9CT>h_rEJrxy14$i`i${M)U@sH2UHd#aK6ZoR9vC`yY<CC+K|}
zD=J(WV~o8Cs)a*O;7DBK?z#2tTp%e+9JcBWjucdobyQ<}Eu+vTDoA<%Y6+^(75h)E
z0oA#qb#b#5ZTjg4HgiUYPj*Plf(keRE7dUXRSW6GvBq;kC8njOAa!^5+JDcGdg?#4
zp@G)EuthgPa>f#RaKuyk%*$D?&r(qy{`$m85_UUriGd^VDyCmeDr5Z`C6j6>TT?o9
zNz*)1Lu9jmPYKQ{%y{}u>CT-yPFw$CsARMJ@#17<OJ%23jJaw1o)D9epziuk?PwWY
zr^m5|<6CiYDDL_`5no|qv<EjH(ks$RQd)Bq%)Q2GW98BW5}%!&5wmCZN7*V4v~9fx
zA)?Zi#UORzC}~{j)Xv4po_2}GbpjqsHR8b&)z@l~%Zw1keIZ%pEOyRvcBf?&VB3}x
zO?GzA1Fbr&tWIA4=$KN`cM$O>6amNuo04?KbJhu}wMRsI^O?7UY`9{F-d7i3Z!<D5
zyyYM-pWrB&e)o*!`VOIRV)FVMT(R<U3Y)0-%yVOiLa;Js{~12$2`Zy!5D`iu_~%J@
z*U@CLt*xgr*}lqiDow0^IEe;#4&b7OB@&wd;JqHKKg${0I=bsS!GMX2zB}^w-x?Ny
z3$OY0eX#Iv|5GjK|F_`u|G$sYcVr3x1Vj<z9itFjf7-mg&2jz1z9gf1EC^`8ywG0)
z`Sl=OF`TsU`3AYz4sMnYyMD1|lyORspZPqBOzPL9(R=+3urOMH!bt1#IX~0>7R$w#
z(5)<bPIzYkbjBGV&5IPqccA}VcLZFQ^KGfDqLc`16>$4i8cbD%cb$5QyHOG)J~%tO
z^DTzs!uxljNc-$y`kTXf&w!yP-{N}ASN^JNnfstOd^%eH4h1B6Pd@nPawa5u^UM1m
z$T<zD&~8mB-`Me$UKxnMsGyS%Fj2~^Y+SQ7?uY0*c#QPO7xri*Y&JP^NJD7*j5NiR
zInEI=gA2y`QJQ78=gDZHj<%Xw{?LXJ9lwURLA`67RGxLr-eje`04hf>mPGlX<4APu
z+=t5%x%p@1ckn3wvDXJ4`^AEJRyp!Hp_15yiDGNl%oCb6qsO}w^yhp>J2MEyt<fpi
z_IQm|q?#m;dCzRAmAbj~@7yjK`<W`cRYD2CiP3?M;nX9bhFf1i?Fw{H*J>M!bSuqe
z?7=ns358co-EJUe8k|v+A=CnP<24<Yysq2*X(sJZu{t+pS-}sjsa-2@n?;6_c8|Z6
zm|Dl77|s_?9exzN4lyL2Pu)3fMvG(DI=iN3>fE}NXoO`|Y$=@|8~0ybVrvx{Ae>sV
z0sAb#<5XGA<iq-QXArP&`Y+DiuGgx5(y@8dYLS={eMXYY^J9p-{ML9wk`$<1apkKz
z5(^0_GCs7OO5Qp=%ltrgc?-7Nt%rajzr^@`i&2O_c;$F?b?b~>tGLc&yC+G+Em;4w
zJ;mn?-Bset{VK^(@KH(qRkl>#{DC_Hig|G&pwnVk9sHc?Qe<>#zmw`S-u9HwOK&v0
zli+6_3J!hIvr9tX#$sJf4xF7WhnzX#)$>v*hN;8Ff~7}fVVrDS5lPQZPTT<vvUjhJ
zh5v5A`WV;_upU!6;Va3<a&mKXk8Pol9w$*o7pN`zCabp25w$vqf<myjSk<C&ZBK7!
zzN$5DCpXLK-zDYD2G{AIUJ0hA#X8kjVR!HnmBw06ve9#1C#L4+U${6_*9uA+cZPpT
zR&yl{4Gtx&n06_+lQ|%HAZn5IF;9H4<*4>+y0i;*IiH(f`iJZ(p8W-SLos%sOp{bS
zv*{{q`rdsQr~O2t!N(`gGTEhcx&n@hKaoJoGG+Qh2Lo?~S`EPuV~SjS5~@A=W~-SM
z8<wi{rmDrH4b;+SY#fxngTin83)B8zTuCBwtXBIGS!$Z+-m8R^8yh)^p2mv*j$ICn
zebWh^Bmz_Tc`g!svNLlr)YlmCpv-jRAW~WQNoVx-1j1n`rs&1MPf3p~Ee85ZvDF_y
z*Gsbq54AmkGzoz2DO`6i3h!J{YKPT5b$vfk4@L(NMQ3SG?5;lh5q~#bL?8AFd9CMd
zcGHU0F}@`>?>n>VC|gl$+?*-MX=Q^5W|^67-qcZy|5K92j+xKst2cCzmOkI94uvQw
zY2CDvp*`L9F=FH7ygVK1^WB+jJcGs;jhjDP2gHZMd}n{;1^2()=o808Xry~52uM6k
zOgFk-vOlu4l?X|_dbQvma#bD?x-%q`6d4~6;uHxqn$jQv8;4&$mYYt%`}5RJ%tQM3
zFY}7nr40+SnKT<4yz1O`o|1?-!~8i}m0d^Uasr~O058dtYPAI1Y^IU3wZx+2`3k!W
zf;WHx@x7{3xI!Y&q5|JS?h78%N=Z}WvEmu7u_kFxz3MaVaZHVg<klPF?%(>b9zN|5
zDq+*oNs|oet?NzuLDs2e;+1~ITl*~Y!JLz{U-W@ym;Q>>{C2(EEZ>{FmNOd8&!-%+
zy>gVWFZLk8lwNISGj&ic>$Z2#cpYeGnbO<}Vu1MqGJvqCAFp{dwX`DpZ>OudsDAqz
z{inbtX2^Exc*nXd-|(6Kn`2wciS)Q>xdj#hZsmvwhTpf&&aTcl^}cY%B_%ORRKCr*
zHtEOKPWP4YE}J@*_LVMA59by10u__q);R9}<?+`%|JCok5*QeByfc;L+WfHr>A_wZ
zoirjvtTf)8n0+Px8d5xtfElf4xrN-79FHgq9=0=0w~{r+v5udS`aINIZx9qypM)T^
zS8j!aj&wpUl6yi3D4l+pm6n!Qk@~fp@t{)hP7aNTvu_3_t1DK9tMuJMx}5Kj)8+Yn
zyhkQX3g#~5iP@Dl_lWXY`t_bFyjKku4o^-tylg?iz2I<NZ|_%5W?QP-vkdg=1H{{}
zRW)qO-*Wg&{0QPJ(5xwBQf%f2WKjS7_DI1y%qT&zHXrhSoj{0>RjR<ri3D`FdkSe$
z@}*$3NY78K)NO0jZn8paGkRwCtLO{IF)p7FS#u^vtCJIvY(*O!rLuu=*v=$!tnp<l
zUf^(cPm>vRZ#HR&SLCR8hU|&@%oDKZv9f9<6q#zz?*2i^-sxUbAEweh`j030z#H&A
z{4(WR>>sHUdxNY(-u0+RNuS*slzHXXigydfjE3gji8SX08ZBUn<s>P3s`NB}__^IA
z%O`0(YX@X%n|$n~?UgT~WJ_{Gx)k(r<73wab0HyX=0KyhtKG<Tb<nDgu692(ONW?e
zPkO81-2U_HJeG`{%)i*QGk|W!Z4M&_bexlanL%wTuEDHWszEZ2y4BvkMdNhLp*vH|
z2ZniBt~mNo=)xi+@z1E5Q@dHZIfV=Ry#_C?Seupn5r;+*9VUiGe9@ImOThEf*Z^RH
z5el<O=%#qSEryssEwM#!_ZNnh$uL$*6Jj2Z>UwRBjnm=7)A=JdKzE7-uOM7H*?#?d
z(~F<bOMhkY3unv?p9}1~dZYwuY5Jv0<B&fAL9yxj{3|u}vgjxUPgrNw&XgH`8~;>d
zicehQyR>PMzsn>eLFyr+|E%Y7`+^$EJN)*~9_Cv=o-J{pqg<CSGT*5~sYR<97rK`x
zf)%mv2cMqz5!~xpQ4;L<D@%$2Qf}~DNob^<_hk=`d3nbc3i31p!JslDew<w@?TLiD
zUbqYp>zs}_Ev<}Q?AEH=^*Qe9&<B09YwSzFY&kS`DLbpF{Y_U^ix+Y0|20nq77)?%
z&MxLg3Ae*hJ0Or5^yN8Xrg(Owc;~q<cG9E&+(5sob^AsRZRpl{W+}MtOxETP1)Lx4
zqV_F}WIyVZI;uYU99gse`7m>k&*nIcAV3m_cZ(XnIiEjyu9^Sl+bS#=xv^&CGgUJ%
zCvO10+ZxVW>Q~3+>$tyn-)W<bBEAPlKDLB~lT#Coy+>2G6%-!(=fGyHc&f|}!SJZ#
z-3}1*7|2MlRUVfM-SbJ*$T#mszrr=Mw(gWw-kK>Gdqa^(Jt=|wkHre#z$(r_$XX$h
z*KB{#Ow9>?x<~k@L_Ea-b9GBDl``o``p$<Vg5@>p`{zd$u04z+-}>Yt0_(eWpnEgb
zjXFx|J)Eq>ZEcj4l<^kqZyNuZZzEsl+!6^Sg_F2MMC9|z{}8KdvV|zHMRt(7k4(yC
z-H|Fc{nuDjLV&Sc&(M$3A@kSvi$xV$?2-uGo6ytMwdRkjxpxgC{J2hI@UH`J{Yesa
zebmca|9<BEw*%q7@ljXf380_*S4RL`;J<(3|HZ)%qy1N*wfgq4V@vyRFYy%Z8(70J
zN+95HgZnnwMqs*uf0@f%H~0cE_@LgfWN5)rm<AW?F_SA!vvD{_78p>S)yH`TH^vV6
zh<MZ2-uUQp`{xNg2g-=1cOZ(aT-n#&L-yhZHQvpNB-A-ejm809@32<AZ)D#ZCnqZ_
zH+QU0b7VvW*rHF_NU@Ax5l8iy1M&ArhrD1Wb!X=?rS>&|yQu_z9D|WxOw9Q5oO5Ic
zV1j~p;b0jnihnpfJe;ww_LPsdRb23;!1_2DXyh1CuVKs{Gu7JKdUWJUKy~Be>GvS@
z_wUnY>|?i06(L!@gjg>*TQ^da&nyrXnNn(zZN?pc{(xqqm(zb_iaq~!#%dir;h<~V
zJOcwvm0l!GOe6?sSGRu=w@l}72kQY$Z8Mhe{TWLPq3QK#R75{VdbV#kj<2u-8g2z^
zMXdhE!*!9<o!Dib9PHo<Op8Q`kDwSU4G>i(M%~B4|6|G9Df3fp|0jSkrBfWvFCW5z
z2%TYxvZA6Ui0I^y_r7>?T(Ah=z)~Rr(f96wb8Y3@n&YQfyrK}rgHMGTo`Sco{RdIO
zXvB=O4Sxa|*01+3FJEd&B;LS!85JxS>@Ir6&8Nr|c@s<U{=<+fWp7jqB^H(x>uOU6
zb<MkbV|uqgwtSh)Y3~|I1TQ!cg#IYB$@#{OU+-UEGJRWp0EQ*o?Ms3+U;4TLMBmn*
z=mA~j|BJ~=71yCIF1WRQD1LUtbBAme^KKLA<M9riKoT|n<D?yZ$X#;^c-pREQjQga
z(J>RzZ`nBh#7>cO>aygPr!OulB_R;{Tm^jYL;jUGI5@bZX5Bs2-p3OZlKzS3BNQoY
z&mGVImXmYoGm!8!TpWKP3Dy4i8~Dh|_Cq``$bfm!uqlN=tmWhiv^dSu4W^)(+2^Pc
zZ6gVEpN!Fm{gpq6YagoGyu8-y0(u=ph05K|`7M<*bjiCGaFU~NZhtO-yEzgjad~uJ
zvkyd0-Y*+)BTv!HbY3;41E06IZSPoGHuhd}#<zK&xfKJ?WRtKdFC3z%D0GroUNmZY
zXW#hQLw`aEq?tT{z?&A2<$?A-5llLasX_13xa`*%g+979vJd16Qj>w@r#hYP9db9E
zPYTAJPF)geMJ6qC>AYkz^xRm{HuN$8jt8nK_Yo0T(CL&e*TIp~b#4hg<~9TA?v37F
z4)qJ?z#V>W+W`Td`r<cky-I7oU6i(MRRo2hr#naxfxxTxkL=zM0?3zziLES0vUvqX
zL=3Wmfo)i%I82mP)=z`*YKzE%pz$pGc~AVx7p_(3S}q!QKLydhzvfIe_mtp!u|}&`
z;(LS{1N~VpYXcc2kK8vHql+=VggIBwJbL5#Y+&1eu7irbS)>xR@KG~fAEDkhz*fJl
zbDhY`A-J0II$^0S`>-ET%~XH5*6io*j?k^No+xpcySfZR9>*83i&<G;gwl{OD}jqa
z?d^-l)}k+=ll@Q1Oz8WLYcZc1ON<)5Tfg!+P<wPy7<r<0jy4XOBO@b1CA@!`gk7nN
z@fGCOoSv;2q4(QU1RN%wmi+X=TnWs%nt&deeBD0aHDM07eMS_cPh9&`KLNHq4+NA?
zaDYVswstBo7caKfzB2^_xtxh@b}l;i6|z`BAaW;`(rcvhK%m^a<!+nLZ#36gvSE^h
zS!ZU&utwZ>0k6&|!WRjqO7W*q<aP=rkA-3a|7G>u8qK&*s`{Ez4xz{nP@^t%#c=DC
zxo*m&aOl*z_Qdn`Bna#cATKB_?o*3x%H5Gksk9jryX<cCZOk8#y&7*O$IE7l_B6gP
zv2;}Y=@8VHUK%{YF+ef!CAsY00YPbS{Z?b&rA2p$z?WWkbYPAl{A@%iN!WY;jM?J8
zgw4sW*n2{E7xY%F5&sL@?9A-)UUBXNR%hpUK)@}jc!w>ZWuWj4b=;5BW4*(x9}){Y
zux8q)O;*i%4qtl1?P^d}BHrg47L3g^u$lc+ldyHyy7@#rZdz7(L-<CULnEJIUahkD
z<@Tzc{kKG)?Vp$8KMo9mu={I^VqK)JVdeI0sUM@8=LIVE;Cp{uOYg&<mII4hC5^{l
zmawOVk3;(rYHEcN-DvSAO`gBw*0!grxsQso6%&*$R@vP}o{rJi9&Oqb$3CX2s~?Hy
zD8Qw@qcx(bd^f&DCXuH0()Vui)4hfcQ#Buu<8c9NJMsG=e?G-{-tfRRqYoQ-IT%J9
z_nl2Lxulc6Jm0$pu$CXC0e{%z_b++*a_&GFJpQHy%-F-mo69U_AD&oCOZ$J$2=?4_
z=|lS9B^{!DQt*3}-seI7qy%}YKd5D^+XPFoddQWE80A|duO2sIE5LqQg4m5`jhwq&
zSrh6Lz092CKmUaBSWj@sc_R+E_dX2g+B_o2i3%3KFx~9l%ekDp<)bc737hds@$8|i
zD;?WHI(7FPkP>6<)_84Gq<EocjvTJ8=5M`-m@T*1ThR`V>C{|SuRoaFikwa0i2l+i
zacOx~UkjQ<mp(;tXZxIZtw#`wp_Myc!;yx@gEH!KMn`LObDo!3QuMW3VA=36LF>th
zg<I6_93xEAVI|3766bv>-spuH7?VE#ff|Hf&0l!uXu-_PtjQ0yyehY$p!RA@t7sRw
zW<Qa+G1Sn2aX6{6o6;huc0bGQNvM_*Z%e@=pLN;0tezHKopNZ1=QF9>W^^|w^RaI*
z+t$=J;-;MMV5YsW>gA|C=@mhr*@2ayIv6SDELNaZ)UdItr&n!{n#aswTDted&(>QK
zeowR1z9!zzEhuK?U{kA*eT~>YP%XPWsJc2_2ry+Vb8tYeFl7v!ZcWeaHmvoptIwuV
z&Uvw0N$oSES6>ueWoBh*mS0Woq)1%-@Hs51Ht^i{D_g@PVi0Ifd^+zs;y)ky#4mtk
zw96{`!`vl?*+YT+3Ka{2I{Spfmf!%)J`6H2*Z1QLlk8#GG_Y1@Qxfx-RG9hb2Xb8<
zAVPEfq>Y>+_Ka5a-p2hv&$b@+i3kWbf}o}TkUJt?`St7O#0eg_>t1oMHoKDCd@u&%
zg*yACu0$Yi3W99kfcud*s)LiwRM;U3Ntp2^Wx0>xD~!hYG{Ouu^`wua6Wxk4Z&FUm
zc|npW3k5r{wC}d3wNH|fQJieJB;G$aV>I%<3KVt$G4d^J{QVF0%A!|aO?~@g`Oouh
zauhN4<E2BUrgVuqTR|Xargt|99)Fu~f~?$JiBL?-?svBiF(&He1!%$S_|m>4<UXIb
zHCm*sEPvtD+ufhB1VYJ3r0e{z8<2a4YnN1_zZ8mcPl04dn5_PNE^adt94xt10{XTr
z@5}SMd+^hgum*AadWN{^odiyD`EhtA8r7v-E=fHBiK#JNCKFHDn|A5-_UX)=NB;?m
z<Z$^NXThysBdhh4@s+!zFP@Jeik?rb;S}wnhQaA=yhy&7O+b5J9Pf~GC(>1IJ!MyN
zn~;bY!OWFoa1Aim+hbRWix~tW6Tu@{E%UV4ljuR+Ul)wmLR+jM$m2zSq&a6=Tz`(r
z2y35(TC6|H6JaI8-n)b3S?H1Hs?E)hR&lzCm6}ZjYl9g78V*C_NZrjy0~YOwMnd*v
zLz*{Sz5jyBcKg**8n&c*B=N(%M!s2}r*4L`#b#ZE1mTSLke8ttycz7>Ms8j{9LQs3
z(c@eN^xqa+%DjLgBXR-}NeKUH*{@e06Zq|Mdqu(0MKi^}wqlPjuV@T*s1@iH`s{^*
z_U3j=9$nXN#K75w`Yb-RV~P+u7_nRL_3PtRR}8oInyjL<+9!qjgU)a7*GMaECtlCU
z10zWS8&Ro6M`tIlqT=Fbyk2!?|0I51UOrYbZk4CIozVqR_tY}*Y%pE`g|LSNjE&~K
z=dWn9H0-X>cQzSqnCtn(dHDiWwGEvH-caPSt6CR~UdSAy8!;%2@$Tm)Xqm`PI_uru
zq^7t{qj%sXw2;R%N}k#1lv@ksZR9e($;5F$62WhmNM-jAGr&5ug+?*~#7G4%L`3jX
z7*>2=fDEHUXCXB^Rbi#>mT9>0KqsF(oF~gV{KpR#k}meoL({d5(J?Wdt*NhW(Z|v`
zdipRrMvQ<t+OjLWTar_gJDhw&#My=3S1Yqy0R!QPfZ8%Lj&J~%BXd)8BW%VyH&M`K
zm7^9!e;!#qWXYb3KXrJr<%y&(-L&3?b^P559twEF#o+<r%#_+4C%Gjf>u)`n8K{fc
zn#0tTB7~vqsY+7G#tb*MzkJmUEbpUAYgn$_8fDc4sd<H3zBmQuM-q<@W|y!}Ew~J-
z6!MC6_fo`>9*~U}w&tagt)Vov;Fn=l8*04pK8PaBR}K`!4XHmOW@Yg+&v{%q%4z0!
z?fDn{p3&qMIGKN04qjO_SAUV-Sc>-*qX5ie+_QXQI!*H8&x%?1K&4GAqkPO=-yx6~
z7zu<#GWh@rp7&h{c3lb%gF24FaNW1%f||PV7?4JMIi4!h>`MxXDS7KY|LYUbIma;p
zl-NbYezAt$C?kw_)gVGTQ3#!pw^uMEa#JKtyN_0mbXaV(*g%g@+CMzaXH6+dt5Bb^
z)}%Z^%RO+sRZ6}Up5MJAR;PXC58av6O!_X6YZ1m~)HP~1wLH25l{oEh2|ww@*9WS+
z#h@K^H`=vmSik5*naqa_TR9sSUl!0v4hhUDOaWF(1K8X}YoszEa7rST#jXB)Zz|HO
zRKt1`ZfW`=p%~$<VEIP(>X-?6aqPa9oB_ha^U)gLp-;E2NOCh%iAD*ya!q7>6k8S?
zqoSkzXeWokQ)m1<7~?W~fTPs(`FDfY#YmvC#D#vIuIY`|Q~{QOiCP|qZpG^E3lr~X
zc`4Q8{N&{dv?r!vQ$=+-FZqi=mhqluzGV9`@%`a8V^C8Fjqa`1z1*ubrA5is=5LpL
z7-LdO)aWs`87nF=aLh+t4N#|F7JUE8cR7W*_O`Ot8Mfli2igzl53!S-53U>0KQx`;
zg7V#WarC=`+<~#&35fWR_y-J<Cm<yajOd}|bQ3F3zO$E?m(O}hGTN!bNN>ydEcsr+
z{q4!hf_%4pSf#alX-mzBwI=hj$Fy8|%-Gh*7Ah(K;kr!(mgDXj1?2s!r=NoT5w079
z6;@SIj|YbaSFese*3I<totN;(3>>fAqi4ys9iEJEPDqr+z9zg|;9q9~!#+058s^{4
z`vgXsFCZHvYaJERp8<BMe{%tL6J>Q!`X(4>MS#@z^O%n7lwGuLVBggS$hvq$&a$$w
zobFyw9<E;Q4=Fcp|LKWt#65FArStKbzq%lOgkoTVK&iZ<8+$r(=zJbRX@SA#$^e7s
z>k|5~KfzZpmiS>2CmgTP5GlQ%vK>VO)z^3WsrWlJnif?7@6oLVwIc0t^*=29<MAc5
zikGJ(5XBdv7}T23dkZ=U<L11EnZ=9Sd^jo<yf(86pNH}_3!+$-Zx?SOK%?my)0B!%
zxT)g1_SNNOmY+YZM>gfw9Hwg^V#!6Y62lQueI%O`91hR2C>t>lJyDhh6)5(S?{pm=
zJQkOKht)B<m2eaf<~*!BPh4z~<;esDSJ6B&aQHUXO9j5&)d$Qeo)N<P7O8%^5A&3A
z?H2DQJIgI24>4~a2)P`ta&A7cYjQe+Fel|IaTwNX1bz}KzwF62^Q4<7Ul^-(AygVU
zQxS98oNsbQIFGOeDu<t3f$gaTdG$L$o$y$Uj&$5aDaWNPNRErW-uv>d8{;kP<n-3x
zz}{h+T75cy*Iv7&Tl6K5h@zujHnui5Hy7zuv+)r@ku&+cf3Ct^#TL64xEmZxKef}1
zJems32sUND?tlIXj7J^#)OWGtXD-(!)<$o$y-A}zZ>P5&SS<^Wl@dP&l0f1bgE-$`
z9sWpg(7ZV_etx`D)EmW(8Yx~;7P~BYm+>{#$U8~Iv0vpZ@5nl5;CsGo*5OKRL(*}Q
znh#gwwi+t}l4rL)F47D?hfuC{s%m2n!`rLuXR>>R4!alf@~&FCf6sd7Olmy)v*0-G
z+4Z(<Zu`kT*y`1cSN*9SaJQJM-KMJALF+CP{CNF+C6o5yI8OkfHbu>4C}O1HTbiNw
z3ZHvdZ{z%8fBEJ}3zdrtY&ZWLt6p*|Z2xKkxVkzPDa;Z^p8J~P1~EatO6)uKAe#R8
z&}zB~QZMAKe;vU86+YjzX+$6R0JuN|E?C~qP9v2YFMFkQ=94{kg~ie>DuVO7W_DFG
zN|O065g?yLnTk2SsDCanQ}<z?xb~#6PmFq!=VkJ1;>lU02X`&NF6Jm|dss}_GJ;^U
zZZ&=@%YP^nV*XYhxsFc_ji2^D+^NtuqRt_hSgGtzJZqtB>4OSx9!|El)4;ZQlqK?R
z3+vB$^?7|G=Zv9Y^doYAGiC@g0VI{cCF~KPsgH@;P65p3kdIM<@Ew%Nbtn}`N6f*<
zGV8e11Il@^o9&sfx!&&Jkr5uf3QO_5urq;~7sn^=KC<=UNX{uC_)(?bn>Qe1<WRqF
zjUtTI;8{V!LZmb5iw-uulP(gdQa~o3{_O8Qb8-aC4#cu)G7}(z)JpoWYJ@RFK$AqR
z_&AqLkUk*dlk1EYbDW}qb<jyZy8!h9omr7M%PF9G+u#L2Ls+fyOXBSi9MU9l%+V5$
zOd>sB%9cYt#6Ll;CHypV*5k~Kp3Y-=p_6t5J=Z77cW?lH<~l9^MsoSj_j^VVzo$R6
zRF3JB)s=!PTpZD#og1<7Xd8GXiN4X&8U;)Gum=LR$G@Lc9W_biwz87qeO?>9MCX3w
zbhd9qC?EjJn$V5Gv;Fof_o<z$Eu@xDsQQsTwTHaD{cerGY@+DOt+Q|%O?`cizN}LO
z&0FBy7#eCjE~sM@!k19mS+`GG2+LPwHkl8a8IAHz8cv&iOeX8)<%Bn^Hn<y(%D%jZ
zyfQO8euuIGsy#>f$AV%b{b`bh?q_!<J^|OCRe~6ggp<6(U=tY&_IQVr8In5mowbyc
zZXQhdo$Jii#V2+q2mMB2*MKj9s4MryeHj@eucTH~SMfte>bU~#KBUL7{oGGUoYwp?
zLoWzO*1UYgcODe^J$Szn<K=X$L%(d}okyITm#0&n*eG%OF__y;Gn0T-(o0}x%Oq?E
z$RCajgVyomUzaDBYjesnT+<mICm64@+WUTHb_b-^))D!`OJQO!Y<?eE!g(|pMMN$x
z_8MqF_QhKJm)%r#*Lew**UFfY7g2q^vKah4571{HI90OyNA)uBK{TbHZHaW|p@J?S
z#+zde;rn1OQ00DVTRk<R@i@)wI^Z|!di&uh+$Y%Ml8jZ1jACkdn86HLJ^Ki@;5PtW
zq;*>%BboCqfN}eDMx=+t$1fLoo+RNc&3#a`E2Lo9TU|@>68+Hs5;a*VmrC{?wH3B;
zMfofhL)VCTdPBK6!4}=@_l<$CW9;@pri%}dm-4)xbxs-VoCSSLO;5?lPdzv*EQ!L7
zjTjlT0DpGrge@mJJ|HAmGfZNCSf0CaGEco-Vh!W%i1#gs-+uf@c=!OQZsmz<Vn~U9
zF0-0OO;_zack7T3XW$02dt$c~2Ji)gUHPMXE<2Nz9w7BomXN;D4F$0d2Ib<_pjD)+
zrT!(4;(y9Yw5<_BU;XKt%CgU|&#BWTn>*f{OG!Wsz2mKL7~>jGM^XW7k-5ujRF0}&
z5b7#?XRgi-U<K^9PLv5`%Iifjl*t>EKZPgBu|Co(XGmypM+LhgM$nz2YL=V8C1s%i
za1&s#ih(x*Z;$A!RL-Wzzy6Ars`ZSb=`+ccPSDLO{J0)lvQZ29IV-_8a}C)VM$j*)
z{KFshmGxf+WXrGWjt3*{jQU$|jE#-W&CNN^xl#>*RB0!5RAN*n*4L1hwOf>+0>QA_
z^8`>vc^NtY@Y^~c0KVb3E$subQkk5woUAO6lzuGyyhL#0mR<kww>vkms1k28XD$9$
zium1MfnAqceO#>hXY)`*bPyqEn0Sx{lEfzSowA_Ha|7$q-C;u0$cap_Q0Ia)bX+ht
zyVA<a3NBXas}7l;LmN>z8R7F_^Tlr!72G(2mkTwm9ZuNt-@yVM-(kjQZ%3U%!T!ca
z6b4<6X_aDhbiDV58O!qJ!4uo+3z58hx-Rg9@c#uRrY~_Di|Why6Als_9P+cbAandu
zv2|mvx3yIY*#w?)#HZ>8mJ<_QBe=%1hb#ghVS@+oU&2YV)|CLS5YX~!1_x^qBJK<-
z1}jV2xQZR4q`hFLNhM!|Rrnh^l<KORHrrS4%{3Y!Z_;Bu&R%ZO5_e|ggBV5(x4wdd
z*AZG=(OujcKDGr47yBPNS5p3FW@bi_UXfvc{PDd{FQG?EON)t&Ib+~Ql<mqPm<YPx
zV2)}xu|sO~l>%mpX-i|je}DJ$ZMS(j`WvYJkz&0p`V){Z@N2~x5(q&WMtaJdK@>7E
zf>>B?!&praM$9jHsPli6Tdo|kiAe$#z*89b-pP4f?a8+Zbr+*88N=A+-Nee}Oi~Iu
z5oVoBP&`P{xlR^mE`a1c_<OV}sCv!a{l8Zw`frz}{=a*phtU}wdxxvs1`W-oFJ@d@
zDz9_?SW-DRK3_*=?aDta%cCo7Cl=GNcMDwO(4RlA8Gg`-3Ezk!Ef7|}sr>&05(~3V
zhWE`P3&si+WuF1l0=80l_ns0SIfoj_KyQ*eP*|}WtFl{uA)caaAbp!z%G<jsow2JS
z<@r|c&*}=x0a3xZ1=l~u<~)JdBn2-o!L$MFQQu;?@UQCT``V)K=A;%UiQtRaef8<g
zAtj@5n67sR(3OaALrQ_GSrLc64y*j@+rA8LLkP8kvNoUqbQ7N0Xz}kX0Z_I`7R{am
z0|ay<`^t68c@gJUaoxcIbxEV{YL^^2hd!`jaO!p&Vlgv2i7QE%fJW5uI57o~CTJJw
zOd%}7*2ns*!Tw#O=P>uvWGP!w&WnYG1ARKg-6^&rG@-~{yY7j+diP@*;V=ivC2W09
zpA@+zj2Z~LZB8I<N`EtImUPf5pjaEkk#GXxmF0f2x|v-ZlDWh4dQi8PaO-~wLTRj*
z^b})3ku$q*8=RvRj<%+l0XwV71@y(GMGu~gHGHB<Y;5h2)s6mat<uS%Sikc8*C+Hs
z4k3OvAb^1ZrC0XGtK$n0zJfGDfp*E+fsc{I1^Sy_wVgVJEaYb=8n{N7qps;vw_<}v
zZ&ZAxv-S`u;auN%iDGQN!gb={;J_J&`M>a0)gZ%OHMPU18&*{F*1o*F%vCr^4I8)-
zW4{|KE%q9=3z=YZP6ehyZr-Y@12qD3F-4tL@nV|?;g}D9uWU+aK{bUvw(D~B3+!Y^
zB9#m3i7{D$_9Y_^Na`ldy0km(<gDdldy}qrLaY!YecwoUqTyOEje6k~!IGE9Nz5|6
zs&&WU%0P*fb8j}Mo>{s{z_A>SU{dkE0}|<CVF-{kh~0+?$<W-!GwnGAZWb0G$6;4J
z>v{lTuCSc7{pED|d)Cv$+}vLy4kU|_b#E~yVVaRsWn}EWVJJ9KtuZ3-2FUDfX<t79
zRpn{OHe-<O___r9#<;lGun<tuND@A8QI3+?ijIonGHCFeKE<)G)+3hRGZc%SjHuvW
zNP-DC%*2c^9PUoFn`dHH@>MqXKd7l#N5oMk#>GcCqdzX8PweN2rmu<(MA*p~nWDc4
zPXNv0evIJtFaL|^iFePFf6ztvcfC?(18yn<Xw#^}c*XmnRbYXDeCLl0;1H_@cn+l`
zg5$Z!VczqguDUy~<vC@GHg*Cd$BO4355Z==ZN@8IyE?Z)9xFC*g<U&=g!uKIF6}*8
z=Ms*{sHoi27EKJF4M=x1AWL&qigfb2c)P47!Tb4-rwDDbN|O+D7oE+c^Px?&V*i;(
zf=9tc>;1b_j_%=PiRklz!3Hlxq|!rR2M$>TTE&J%O5F*K^V8+hUuL7LZDNI=+}J?u
zS!kaBo$)vZ{(=_M`O)Tkh^(Vv62Q<=iT)*R^BJGT^>e;nlO0V1)dA@lJq(cHZ5|D-
zL?;daD9wLjh^U37lKA6#)H?D^B=2cXnS`>QM6IpvqP>3;?t}?tdz{!eAqLqArl>z0
zK*Zp#_+C+cTSHrDY=KqYuMN2%Kk;uaKx~|=&zApWW5@<96l#_c^9+DFf&2T}W!P5E
z_4^i7Yh@M8Yu^Yw>=R;t?)Y7=e|iox4stCg$w=bjr-TkRVE!iX7e${#+wBApk9vJ1
zFzH3($FmpeboH3o?rvXfTywsT3f)L~Ik};sAvmhP;a3!CEQ4UtTuoj@q3whm#tBX{
zS&b(qbiLBPG@%GvePCE}($^+$n(k3utfocf+S!pN0h@-G>q_aCI{qZ4z`-$>fBo88
zcN2fikW-oS)7lP<IW{&Hn?mLAdfI||&HAmw1L&o=Lj(GQ=<IwqSgo>ivN~+^E8!uN
zjEf&a|KaEl<p7Su)~Lhx=1_%4Q`O4LNPuwapndVvai2JlPVSN0X8+aa!`|>fpj6>`
z+=lsl7(hUqIkuH`li%tf;DWt)vci1le5}3ka-lti%do2ZonXZr13V9VRnglgpMl-C
zslVDGskiYOjpkSr*q#Qru6BZuYVtkU8>{Zq#nI-UnsnRBV#{hB*vP@3sCVx=h%Nwy
z(-H$j74vPX&@TSqI?v?`bqT{NV?T6eRyM$b2Mn>o%rbLA>TFHN<uY53S`t%+H)v-N
zjLeMxz;r_&19wd*sW|J?t?@eOPU6v6dBSIa#K|&bhrV*9aLqT;4r_SIUJ$6@iQcdf
zIV7kW76GWkYse$Otz>@-0{(ZLLUz+FW%v16gs+9<ol47rdb2L_&7+T3?QGXmB9!AA
z=JA>B)U#o6aWQ?-xL_ncJlRlDvJum8x(TeOaC8|YhFUFyjUr*!Cpi6j&?p=cHFz`M
z$aW%#4B$T&E1u*;T+{G;q$kWk3&$N_1_S73kwLXmcGfiShkn-Usqm4Wpeawu8@*3a
zX(gpJv<)(D77*EgS`HpL3ATf;k}nce9V`K!c}t74#~ff7K)a5t)IV%YSor%jSX|&g
zuz0QiPXpiIX;8&atvJ^j7>2cPq0T%Fua^%j(l<FnTPR^<(>wkSAM>nN8**LSa*}^R
zZ%9B3;55EIB=uG7V-E5TH91Mk{{<^k@A+-QHpbxHwJ!+%R7k@xxx6LipBGDBZ7_(+
ze*BKZ*sw^G=qc`C1%ZI>i~8Yfhchb5KPdS6cq%-I%D;UH`P|ZxtU^LMIp1tTzuGuP
z{CTTu964tDA`U1K=5Ygm5bJC5?I1MTvwDhiB-YeMPW09r^ykRsEMmQ%(@acE**Q7w
zjWu_{aj8Ee|7WO7$ke`#6P(K3J&TbsBA$a>URwHY-ZhHtC8uoE_m@xF9^z0CKOb(u
zae9z5zw9aqdM6?~7`WB0Z~0MJR#`dL@d=USXMbV}V3HAcXb2EeE&oDfzyX`GMIs$V
zxA6n1<+j`C1%<Y+hH?QJ)cU_FAchY^qyrzyy_x=62?CFlu`OpIfS|Ot&cB`xSSTrE
zO?WH5(e^i`{{qNxJj%odU!~GQtRqs>G`@t6i^me1tk_pi$M=~3^R70dsd$I`iPWVT
ze~Z%kobtpeTu(@>VfKuH6ie{M6tkLfH??IUZS~eaLlA`LUar;uY>Zb2C^&dB`Q_0+
zhl^CcCJ9)50B(H!@d3S)&8v1I*Xw_$egZ)c_@laRG5f#&Xekp)Z)6qMwZSG3cb~Nb
z=lUsBTtb)xqbCir%z8ItpC<%w<OSjqP`}}qfy50h?N`|+t11RuHXD051xhk;;H3F{
z7cTGk{*IrC;US8M5E|=&8`Np~l%BK0bhxIzY-WS29AUchkA(~?W#E9=%rKx_KaeqY
zihf^#X;7WR3GscD2!K6<<hPyKJ0BG<OSx#u*G*&3O_WxTFSr(vM1(fK2pii{r--?R
zY+-%<`5TsNs4ExE$C&X`DaRH<)Iy%?k*Ujh*I7LY^7cUU3soMu7D?jg*LeOBUpu?R
z)HoudbK4j<-++@XSwfx*>X7o@-As$V>pQ!&uZ<^WnDWZVfVPt1A!C_;Pm~M|3rl!_
zJoE)6D(3b-7T-!^fO<fZ93;6>##3a?sB%bJDF+$t>@3Y+6P%E<DgS4-?uL#R!?{kH
zR&Puw76$c6tU~Lim11S?E;2<v;ba`J6&_Yi{bL@h>iyR??(&RrQwnZv{Q0b(>)<RZ
z;ziDFEFV<s8V}X|Kyvk<5n>(LiSoH@@oC!^<gtQ}l&ZT7k}aQGm@#PARhBj1x|0>&
z_t2ExDN1Ns4T)pmYbyzfD;VBo<32gfOg8CH=()PW4!2<`JF9-Rsy!(xIiowl+%$Xt
zQ|v~>uOS98onwW(nGJ4A_xhfMY-^~oO5XDhmITum49rY_Xk*Bv$)nQK#<ombmRCd!
zP@WM9^-I{e@+(?b3@?TvUhhTZu(P_=%+NZ#YiE+><CrkUJxj=&(F4E1N9oP4_)3N)
z+B6njzqCJpUuJP@kh)KKFiB%i$)d;J8yD^&iM`Tfr7XL21EPpHp+K;YX58)#bdLSN
z@PxNZDSCfDjgfuyF~r0N5-6(OMwM@C^6vhlJ|=1{war3TQbYaCJw*z5L|CESiMQVR
z@t>Bio#Gb=_M<GCX$@GdZA3#*=>KT#%EFq+valjxgCO0JrCG!VLm&xjWHZRfo(0(w
zi0lXw&_D|!pnxsNA_6T)5{Rq<0VRR3jUdW4X%-0qOdvrKMQnwZRYAc9S*C*1-!~8Q
zG&A*54^_A7-g8ggQ~$a5|F068W%+;^wKMtY%4$>SntB7Yyj~9pqP#Ob&Z(WmMv`A?
zg&i2G;UC)=Eo{5?)vEsm*l2)&kw3LFpK)nDji{xuYP6G`m*hP|deNhDg3zEC0W4PA
zqf&o#2k8uil}#9NZ%jWtuB_p?K7(G?s%ylrRm=i3qi`&L1_w=akW%xzCpRd^s#`G7
z$)#%Yy9>iHrwlo%@`05)8gED+u7fzvxeU88$lDcg7F2@`7OMWzT(Uu?Y!a0jZpIm{
z+`EBd42OKF;g__;$b`z$qiF`pPq=F}#DdKVgj5s)&rq#@^6*2F6Ctno+}eKi5`E(%
z1Y0q3d*qI!_J)}!%VNDqG5`2bqTYfXX6|oM0J(yYo{pn%ZjXZPkKm3`rOSb=na9`5
zwfvvj+*^EG0@fb2^VwaQg`Gsv_tCBr5Gl=SOwBdA@Q&wA5*up5rO18>7B@JFIG4YY
z^Xm;^%9D5g^a_J|okw?u`WomTz+sFu`obV}YB?MiipCl*PM+3%`(a;NRW2%+vk95y
zkc9RW6W9D)J8c*F{I~%zrx9Yiy6!VH#?CUO8gs*h5fr#1;m=ZxJC7jIG_HM47kc#0
zf8vy$+j!>tgDkM_e7tn(0&Q~&27@=ZAxH|v0;Mp7aCTaJ9Y4A^kwo4aH->8&=WvE;
zU%aJ0|0J~*LG7)@NX@D0X*?o27b3eHzI9@ApHgw`BD`*{uDF)kpK=eZlGY5R5rggK
zPx9*82V@in{)lj#s<%rkm8c}IqMNa>6YRIkHkd%zfS^+R@l(zX%uKG)<v(>!G^|W9
z1$Y+KDq*SeW)qppja`DS+}(DctM$W5<rS3rjsgYh2({ucQ}%I8#!PYr0;8L&Y)d)e
z%9`|?r^g>X&%0arQhj`aEY(eJ*>K?c1^Rs;8jUx`C1eFVChu2s*vSVXS6QRQO50q4
zQ(mgA2{w<GK=(>H775kR;u%=1_?s{>uFx;3^{kQUnsUjMrmhgf(>>M!Z0>ImZ<sR8
zaTsIxHGMVqz7Inc+AF9yqsd2GDnpIUl{bB+U#ki~k5R-y8%HN1;4w=td}>WcDc|G1
zsA)3JM@;n?#)WC(DeYX+`I?b?f3Q>ZQfTuY71w}N*dE?<lg><hk)pDRcjw64Hj=x&
z)C`>Qrn;Hx%FdTV_?m97s?@uc{vZz)dF)7oZ5MW5N|f^Z{W<C~kO$0zeiY=LE-C-$
z#s-xQZ$C-TTMi(~Z~mP<>WLQ}g7Ti8o*l<F9Tje0%YE1AG&299Xn1-BO~Os21{1yE
zmP~xf?c~yUg2#^$QyuxMItqF1I<FBxt&C$)*Dl?BEa#Wfv8sv3SL?`a*4&Vprs&R$
zScSGv>G)duKpw=Fk6j9W!|a=$V>oqM$@6<Jzt`v6=yjnTq#do<sa}McCIUZ9KRiq}
zzJq_R0a8E#&A+*0Hr{gPQg3oaQ$Kiy^_^p>Red{i?9he-YW=SsO2NO9c$?96%57Y%
z)9S=AmHBenq+eUM=pQp3en#+U*6m27+=P0D2FN}-PlA4?*-q(8GRkYbJlso2q*a#U
z&qw0q?&5=>P#%g;nCrskjR(ujE2zILU=SRu4)+PokiaDR(C!f1mpxUfccs68Q*EYv
zb^`2V*~!K8?W|cBIguxg#Uvg+QFtHu{UcCw9mp$Zg%GR3*yu3FeOy5~!P@3(s6p>y
zI5U77bt7YY(qF8*VjT{KK9VmPgxJ16D6{lj#pF`Xj2@u+Y<2eXJG1oav<A3P^2yjX
z#V5$cvd7W#rDKQeJcQ=Te_X~SXR8$3Sg2JC8?a9&7+-(5VGT+b+|L(Ki_c|mat6$=
zgt#$YF?#$OPN#?8D9l}xs9RR>wOYwBGJNgPo6X9c`Kvk6=!Ub_&s)6~k$Q(DdWoes
z$KuHTv5R{7cl+z&o9S!WcmpEbMd|9A?F61*Ue_Oz^Q+~$!cd!S0*^7Y41V5v6zL$p
zzi!>fKoEsDK`|sgz@V3)vZ(rJ#QoWisidOd`#fr`L)nNGQFp<u>EqItX&jxa=^Qh9
z^)Gjx0-M}oUK^MnL+M}nc!woWCJb^0(D|(u{^mmU_XqA*Kf}XfmMmN~XM4|>d)8K4
ztTGw6Ra_Aqe0oet13nsXELZk+DD7f<d~3<XB2>4f#!nW<%I9TL9tEi-mX(29X~8#v
zv%sx;4r?Ny3qX3p!&Ub}Wa3DnTb2=e{p!OqYAxD{rt4`{?Dg|d#b(3iuCkujKJ}V1
z7R5`izGeyk_BI!_Z2xK3<J`iozRvnkw;|RVv!MS|cfe}=J$7~^nI^b)fs88*salu}
zr3f@kq_td|zbicqmKz*sfUTnD)axn`F^@-5I>Egh_^ZD^4VZZm;HuJMiHLM@+2XGH
zXbFgwS_<-c80Y>8pUSZ@!Jp3_WW)dgt7^EIou%ZVstO)v6u}xR1G$K%5>Tq9s(o<i
zfU2Kvpm`T>M=^EDv&30DQ8Lf;9q*fEt1nhh2B5X9di!Gc>=Adv*jc-yu$t)(eHymG
z7}RkuD4Udmyp!+NY)1_lXKciG1i2U{pbyiT5NQbgBscBn9C79YY7bWR7}~HO?c`qM
zgAOJi!QjUW#;^u!-Uk3S9*AQ+0ju_MmnL>@ggd&af*^A0sb21iwMm==eG9^GIU6(k
zi@JO$hrErQSaX^G0C47RjEk-!#%kqDA6S`gvCmS((trO{vx$6!2q3|u;B4C?MeyQ*
zfy)c9+ZlroDw+Cm@_>~(X^R;%<Tg-2<pqdiR2;zx$D{bE4rR0WyPh0RrO~t>0@AZs
z-HXx*)6qyj5AC`BO;0l|1N~*Q@Z0W+L-y`rk1cWXOlEkpA*i6@L=5X+ap`dKXyB7s
zm_f@rHwns7tdkJvd=&Mx8h}*NbAMUaLWrMsVH&BdG6*E4bc;z~z)Par6(<A4h0$e?
z_WUU2>j^{@G(+khM47YD*nLD4?yS03dTZWz0%*ax{!84JjO1_)pJxoWpNvbnUK)N&
z^4mQCIuW-?2b~1~M10Bcp(~c++D_L^FH?0@4(-0?#`H4!h3n_WlOMHbID=<Ch90AF
zs{j-3vFeCwdxf=sf0OZ?_Tbbuw;b3TP(pM;1Z+-)P<9{rAG!Klw^S1&0kMIQOUb~d
zo#Wx(aL*x=AoNS#;k|#DOF0HrfOIO{qDAP+)d1`Z(4DI^FZ6f=+y?(lXQ}N9ytTFU
z%Z*x*JiR%N@x}%M0_n#8;%jpYq?D170kB0DV`~gVO1XPTPC;p@2U6JI-;JVx9!^z`
z&awzK!14%lH9?8!x**#w1Hhsg3b=FFmU}&K79bvgS$7IPOV*g!Ll$DcZf|`R!aYP7
z(uxYU1AwLg9EZW-uO1x1@1kq9xQ@vYGAQT1uRjSOj$pCA0ium8lKRk5so&TmnH2uH
zQ`nZi<ES1BbLjQo3%S$L&ll(RCID0d#jM_NQ!d=>N15Gh1ids>A|i=9O$JfoJ0Ofs
zPtc*aqlqU@?Gx9|TlkLS?0g@X?g9>3WMZ$Dk<oVU?9`~4d!%%fV`_9;yE*`oT=I6U
zDUKYR{kJ@T$<=T2(cNmdL_f3t1<wa4^gnTX{{OQ!-8%rl-q~5{JH7x^PEs_u?Az0>
VNAUC%3!fJ?5@YXdS7&o3`JaP0h|&N6

literal 0
HcmV?d00001

diff --git a/docs/user/guide/providers-custom-form.zh.png b/docs/user/guide/providers-custom-form.zh.png
new file mode 100644
index 0000000000000000000000000000000000000000..2c4812033145261e312c3e79348c38a4cd3d514b
GIT binary patch
literal 57720
zcmdqIXIN8P7%u2J7LKCektQ9LA~n)Gs7P<pL_&#3lioWaDhdM9ODF-POPAh*(t9t`
zdkZDB5JEyS8_(SNai4jfdFIaiy1yW6@4eRAYkli0@B8l1ms-kqZZX`ta^=b$Rh1XI
zSFT)pcjd~}H~;(%w2+v3K3%zT_loL^XZk*f-FdP%Og3rQ!)YXHBGw<>-08X^5viAE
zruzQr`=@MG!wb?9`x3o66cYb1KPSJLgKc+3NNBmPEcl~qip{)o_Zrc#)0oMkl32bH
zzD<1S-R$Y<>E!7I0%3#HFTC;cagL`M+x^=&J|3A|z|0wd@vk8KZ<{M&=GjT~)q}zw
zGRNJqf2FbKeY<ga4H{?3703QKZu-sEmYx&?qDd}ek#+d;%2I&2U@AYYyK<riD}r56
z)q3>5*72CLcpix!1*a(Z4*aqSv3UDN(7d%MJGucbB5^(FnX2ZWVFRA1cnNXROFeXT
zIl^Bx%h0|G-29&MUeUx`vE-Fat}l8yoR`nDYM42%=p4Qc(tC2BUGy)Y<?LtdQ|hmc
zSM?f~a+HGpo6S|e!00BgUp)$TmuvdI&c%aM0vAAJdldDj+dNf?*e}$$a#0D@H!A|Q
zm;K)TmpKL;6c_c^gUesvnpH+rDYY^W?ymir9a|W6+BinT&*fHh%H?&on5R#p)H}PW
z|NICJQ@4il?C)z`{<>1aFObYFemS$Jw_?-!f3abm{!Ak0<A-mO?V8S)SJ)(PYHqOo
zx_NnjY~1jRjz9nD-uxGF*}^7zQ&Z{A<$uxl{<~+CP2x|74A;0Wn^l6Au3i4Mz5Cz&
zcRo^G{>*vi@@FKGfBwuQ`o{nL!`av%y~os}eoCfEr+*EPuMPW|J-NSIFHR10Apyq(
zx}0wh1<JXOj@y?ty3W?@fyIp~z2?`r$JTdRkjIN)@81<xeVh9v0v3sdmK2#8*X({I
z-{_e-T6b2mzVY{mLW*~`wyNbDVPRp(l^X$jJBt!7OW#u5&rfVIU=kMA@|ADHt8t<q
zO<ICgX-Rpa#wlThI7vE_vt9Qgdteej$)b#Q3<6t7p<L;9@7_uHqQ=h-SF4<aupcGY
z*VlEOz!jF;lt_r7iAizV^@7a+)B>J8qWgr#(9HKx@puJ}+jEAA2ecnZR$9ZcAnm%?
zMB1s)IIf8omK)1$%Csha$%%t7U?$L0<Pf|6$udmlVUHTc>dy~XTMjX0JxnmRZ)WNg
z4wi!4v<1nYo)|C}{q5io5;1CHV*^51`IYM2FygSk9(B1#(dNx_e+OFNj(U65lI!r<
ztTo`0G{4gL1UtLJI9b162+2lo^r>I7JboG^kS-6Jew&+nA%O7zkf<9NxWGz0Xq<H>
zMN@x4o=%j3AVfbiGpCck4H69G&ksqx?FNQsxPvy>gi!ao+r@E4RL`dYYka#b>y%&T
z`@gOtkAA{oXW6W*l5T6;`56}nA?R^nO7AISzuw4aC9T1-r3*uQdwE0;cZG+VPiHDD
zwVPJL`dTmpu&89*5{Naxd)*%_Me<qu7pHc*^-+C8{;=KR@Hkg)_0VV6tMOb%?e!v|
zmV|8sIy(!cTEr8vFk)qf5{N)7oUmKT3XkKg8Ydphw_L<T&Cv)SA7m;_nZoo?Tyoes
zaty}r`u6FpGe1B7M1z`8=B{(t^?l-RWfJE1>OBNYz=7eEsdve=gIY}vhsNc(9DGE7
zM~j9g-y6LUcaUk(6_xL^lA{_|b$h1DcFdcI_op+Hzyf2j#w2HuS}&Yijw3B|x>)>I
zX6$J}4FnCkMyz3T8K*$XRL4@z=f<|&G%9o%44;}(hZfEl8Eh3ElEF`uL9-vJt9dZV
zKbV+3TnE7pQ%OYU%R}zMvYl4ycML*y|NgLJ`7w~>k1kVd?tlN+MTY;WZOO4y^B%=b
zx5MKd6w0abLW{darLz&}SAdsS@0g>La1cUr??^DjUl7YkEiixk4#v-)KZEPUF#FQH
zR?h<wBDQb)XIO|`^6c+=UMN6!)|KQ5%Ta;&#>I6@8+j6;GNyyL2@8A-0dqCu_j_gi
zPkY;G;1D_M{w=+HEdzc1?kIza650Djg+*dcbKmo1%`#HHmlQ?xBV>Fl2CT<`H@K2B
zF8ym81jD%p2Aa)uq@*wvgfq4}2vIVMY3#`OzHP;Ibab$ie$T^*eGpTDDQ6fSkA{&N
zV?sJ3nUAN30yn%{@CsH|>%1UPJ>G(KqV?ir{2Mv2Boas^k8_XpNM`BmO_dHM<XbO!
zb8O9<CtF^P)$EqX4=rv4p1Nau0OQyxCu1deo(O?jnqDB^rk`yb(H!OGO_iF8S{}Sf
zPI?kZ*pw&LpBegMCZ-~pBp=S6CJ)UOdG<HeyNd#EutaD*cy}`Z*9Qq8gmNJUH<U@Z
zGCZ2J3t0O@O6d9rkhq9Q04gp6@x;6-<#;PQsxVY~zm7l9pe^JM{3u03e`<VpzEPXA
zGm6y^tQ(t<z});Bcq>Q-p`Gh(dLxYVL7h%uH1-TI<j3UimWLBuzO`s2OF0$>bPO#b
zE%LABe{5~tG7AUh@{?=;cNdYfag2#H&7e9AVhsRwWOHzEU}5|2@^~D{S0<edhDjw|
z^h7<RTwhxw?B<ggapesSe%rcGjqty&o`b;gZ{8d>?w>~o^t8JVwH$PS0*%J9r>=@G
z_(1#LR#$t*YQMEkmvMcrz7ipxsI1iVCBDA2aeqc9TdC&-6nf!}JT^_P^H|QUUGysQ
z8{fo0_jb;8Qv81*8s)ueQ;baXb8^RbJ$kWo2&PMCbarJYZRzCDU(Q@Cc~oG7@|v#9
zd1VHvDz{z{#ji}ksw!LaqG@9zF@blH;`4JQixuN5i{6X*fM-*-D=cD#5kf%$%fw8D
zV0M#T)+iYi7B4ExHgAji$-;3Q4v~2bVK%8NtU%dANU+0WE=|N^h>+{bnko%KDT>K=
zwxssEvZ(<4mR4IZWmLaL-})&2*2c!Y%NTX=VN&{+?R*1f#z>ED^W8bWm9Y~N*O{cu
zn9Af_;-gL;)h%w_|2;{WjFKh(yhcaY=p1E;JOTW;vfBuWu%t{WdlGVHrIjv&36UqL
za<U6S&)U3g=^vP*c_AbvN5_)He?2`tkLI0fl^4~;Gw0?^oW249?ftO<y2^vjM5rYw
z8|AsCr5VSieSU!sWE6Iv+Mnl<n0M<N$Y>!|f;Z<cMxx|Sh9OZbvgf_A94+S)&MZDl
z>Vo8iB^Xh;S3>Bpyb;YJ^X_GcVX@;vQ++{?>vk@=QWT5l?p9`1pYl`%dr#BxskD%w
zdF$Ek?rsF5xUH<xsn&eDPg`&V6_=)F^MRhWY-Z`kWsDw_Z>B=9_-$#=ix#E>;WROJ
zR96+mT#wZuGvZ5x$ex8u%Xz?uHt~xYM2GRMm??<2>Dma^uq1Fh*U&QS$G0WM#WTAu
zLwp?RVms!MGV+3T5!`I8$##GDjH=}ThhMK&Q&Y1ZMCj<~91bay4lyJw8muklRZPXq
zRx)=&3(R4&>^RdoVQQ!OxHL+FNsHT37I6MxZ2i(lN%@OK)*|UPxr3im!4&jBh^FQb
zNEm@5Pu_z!iXeD3S65dQhDpZf-9+IeqpsqO4`*$xMD`esogY!KU8kE`LWh~sP8q^B
zS|_hzvTIxA*>)?5#!e|RzG|&jlV!%F86l|8?V^OsEav_3Byh?Wpx(JToXJVDHeQ5m
zPtWQQ3g*ZR$m`e9Vh3NO(S+dzD4uxM6=EVV#U<y9E>bs(wVB5!<Fzs-ozta#k8-pF
zSJJ7qNq|4c07-<R^V4U6L>sx|?MC_25u0@AtA~)2*1!ysj}LqE=;&xu(_E5)V({46
z>)9lqks7D@^GXu_bINHQ7)?Am-*IM=^LwF57W6>0+-<$LQGTIe;4|)e%f((<HT$dT
zdFYuv<O20w=Mj~Fg%G`gOT|l9U`v1Eio8FL)wWz@BvMd64p^X|u{1Mn(AVUvTZ=tY
zhLP~{y@mt=2)a$acy1li&~UL?OIrO&4C-49&}$v#lEZD6TXcQr4F|F&;t@PVH|om|
zC_Xaj_i0=P;VduJDLS<F6`!-6+xXO!>Yhr3zU$dRO!y`!I+TQsDC5vj<{sCdD)l)o
zNlHdpHwp^#@@VzJQv~*=K-0GrGKYE9%@RV17kDmpO|Zmn!Occl^*<3;4=}@Y=)P}B
z>e&U+s&66sCih4`LQ-MpFQx25z;6y{iZ52!3@tdC+ikE0l4dR2;+0LFU_U0Ho4p4_
z4e8eC2zzMQRF+dCyP41OXXn73Ss@#Ax~YxinzxtJ;MPdC6uy{Rw00m>JVVOh0Tnr&
zfJ%9=inGE#=Fi^0MqkTcZVO?I*j9G^=Z3;z?dOPcJ50*?xnFXUkgr?o%20&3S<6<%
zwc5P2C*~g~&0~9sXCaF~wC{a0>q3DIM8%QQn#7)lde37r{pA9^U%i?H9PPJ{dQ})k
zF}vlHdvPgde%tHK{#fO}{=pt%lyfe3<Upg#ej^%DAkpL6H!uL?ClO{!h1&L$#m%dy
zvsDyl_(f7Cr<|*HA@U1LS-#_=o0s{tgfm9V#m{j&cAvq(S+!0&nO5tix)~JHU|$wt
z^aeF<%X&V{JTpBFoaU<#9QcXd-KG|KLKI>SQ6_V+K8_92ZIfiLG{3lklk?abPQszf
z!2FOHRt}@wJ6a<-x3J0heR<$Q*FLdZyak8$YBaT$JN->X!laSB>P^IoG+QlEqQySP
z{01~l?-oAW$$Ygm;pYeY{Pb{&{p0D9bawhqcc<}daoUQ30ZSjs_U7vKc3zp4VYx{7
zu^s0+UlQ@^Q8smTX9Q!>=eC|8O5%B85uNkQc!xB%fx#<gSuc$->|1RObH}ad2f{Xk
zUjj7K#H#h|1Gh3;x?Q8cR{3LD5>ndF4lS%wtyXv;7b$B$skPxv=gy0SycA-uVM|u-
znhUDUO~tl|k?bScrJoapN&uA?k_>rdAo^tf0t@pR{`LV_acsbf9`B+*WQSAQYu6-T
z?@kL5<7`l3yZc+PtckF4B%TO8UL<LHlF!vTlkSKw9L=KxhqfIirMBzo%=D>ZU6AJ!
zWy<hM<iThB`sas`sEgx&OWGm<=M8H)%gu|TbOQW&;QeHI_l<sZz^1%a>z)^EB`%}%
z`*)R^8{8TNMXCGv{$^XWt-nx{rLR%)Wr2%m@yjn-*w9R^sHhwh$ZPn(aok4+tA^q!
zlJ85pePU0RmOsf%b*|S06TBC2%e-ZED>buD6Ae7nw@OTK3vHD0N9T;rFOK?c<e=zU
z<iyP0ULS<GlBEcT;y#qA^r+JYZVkbpM?LxSgqTJ-T#xo`dYQUMARPk(OdkYwsAMOq
zmG8dSfMF$Wbs-Zi3qOkd4=kXxDK7C-76^*tjcu=TIS-@1gI>^vy3IFuUS?Wm7nK=!
z!ts!-g&pIHOvUOVVX`(O@SHw5UBY#x7Ks@c2XQG1i(2A-yU<Wv+A;*N<=E(NX=%X0
zByEVd=#4F2pwX}SXt~K`FUD6X1J-vMz4rVpaBeu=s8XZmysDhKrlux{Q40cr;7grP
zw5m-Sh!q5zlv>+Vj=W<Mwypx#l^3YKZIdS+cK-?rd056#T?`=}(Fs<=d*ZnGp_qgW
z;_fDlu&NL%z7{HUIIIAx-#`_iFHZ6|OeMsvgS2ZSu9W&!T^uOO>tNGkd7>9LNi$O|
z<wx@gJCmh)eN1w0FNDm^%u1sN;`SVDoes$eRC*Ne9?+xJA?Llp2k)uwB_mHdK<%L8
z<BSW3*&1fugxC(C%$S0Z&JD9Oh!G^Lv$jm8H?+UE_k7+N=2$tc+k|MZ%(z%273g3D
zQpEp&4ug>34O)02HzaVWXh`O`c+$6aF>tmFhUwdqG&J#zxW=Abhe=G$c3uY3Bho>L
z{KY=D1#rwB4)f<f{9%MPwAD(rRUh)KgAAP2YjT0dl7ND(Ws`~()IFqqdXgsXO(asn
z0)RmN_lKvJ8&fT(1_`QWMip!Ri}+_=UZ)?fl5s$6&rPisOG-+bmphFu{Z4m{K*$5c
zuQz8Gti+R5Rua44okM|^w<Fmk9|^xf<$dDWtaGztH8_fCvaIEN&>M+|w-7ZskB*Pc
z0=GL<7``3?1)KMrYd$TD&c)}=j0DGMTi@-nfOUJjr~ib)Ddh>Z;UKl>&w)f(%WGu7
z=Xs|}qmo81bPV%IE4C8c;^gT?ruGG}oTsc4(lq%YEawU}vQX*9j(N95D3&W=s}c)6
z|4<g-cz&`iPr_+uZ>A1xTn4)g{2a7s0fIS|M(-{(+h7-<69xv{W>&p9J$5TA;R1t0
zLx#UpSK9N@&Da_HGF2$dSkQJfXYt}xe37uxB7c%EFHdZbJ36VTsPIQ$Snl-ZYe@PY
z>02%r=;c$e$~9FKf@5FDwH?aKpCK9amX84s^NZscs2aK^OHFzI<u(5Z_Ly#^PJMtW
zy0bicgc45z_C78*@4#sgf7T^`+WjbMV{?6CVyYl{Vq#)vvSg|?b0;H8E^AajD=qB|
z$a?R~b~)9OwzXkwmw3|>A#o&ZjFPw+q7D~`3!Q@V?{#lYXxSVa7=jW*JHpF=`j6n%
zpWTArL+9QzSZI;i^Giuhwa<~z)zdRHM7uQx$hAzZV(<aKq605RbKwH_#T=5rM-#c~
z5dS@lHVhS)#@ww{P*w&zTUO4~Ol#OW684TfuZ58kXZI2r20mVgn;_rC^xnr~S$!}Q
zxs);oxn~Jy0dk>&q7$M60`RH5)83&#9LVLc;}}Q+v*3hLcuR#J#;$0B(|`}t&U&%c
zbwPIfY!{lL+ME_!0bn|dfMdo7$B#c0=2(L66Ng9#WQ*G6XaV?6OA8(f&uOED_gFGW
zJM}BeA1(iN^#*`fUis<EpZy=ebe@HTvi<?4y084dLZbdZ!C3#hJ`8?LedN>h2X<sP
zpOpK}M6o#(cv!TNxZ#h+{caDX(gm4777xz!hPnZGh>t<mF6T0KEd@PL__Ym#5tk0B
zxGW!nK!yW?_rC_+xN~3hZF~FSYA^+J7A6)-Mlm@t)z_Z5Cp~(DtG27s9?Ozk=d$lm
zvg!D{YJGYW5)G7qr@}#Gl)Azhfv2A}jcZ<jtVL3ej*r5^ZgFWNp1604G|rb^!jW6A
z=x=Ea3=G&k=aGp?*3{GlkS@~-k7-$NnB{3PJ=i&kz20%|cV1^Fj?VOZngu~FL(1gW
z%O^r(d#=i?3c2OwI&RxFd(!FthwGG!zFo!iV?eySa%G+?+Z6LvY4rj-UzBHTQVP^;
z&G-eL+S!XJn4Gl;y|q?GsTE@08b5l0wS`7ZJ0LeLSars<@{gB(Dc~tt63^Jlj?pBa
zs)B;U3U#_mW4+R#suVQ#>E<fuS5`Wl>*UvMI*7+|6zrVbcE9Cf(7*W};{0*wH{m?Z
z2!c;f2VD==d(od%V3Q6Hr85HyS)XkE3c6wUry~UrC54WzNx)%Ky)zOsIAYP&Y*sd5
zmyq1I;NwpE71W`q$Xb6K>Am0&+Z>$l(ni#srWEPR+!cV^ca_SLQ83NHmcC6p0Q)w+
zHS&m4GwEHW(Zt`t(m{{Yye(G}8B1Bm<>Yr~s{K0}d97AzQk@xwTbc@b4!bR)`l8?<
z6A5#|@9wuBp1KUoc-l`ne=jK+8t9{!_B$~!6i_RFgg<2suvz!#(oR3YU$p=Vb8)Z!
zoKUJqbROI=|FaR=TKnFdP`dtfj>abMMPka#3@C6P`D{Mkg|@%t_p*zC>8TRiU7w2x
zad}K=l<j}7jE*XtYH2bV3sPHZ@6mgtd>g(EY|7qrrMB*XF}exAdkiY*FcGLti9Q-H
zgJHQu$3M9hu2fMQcSh1*;D!Qc944_US=|fGc%T;P{AK+1Z4b(G$7&si!>wCgtSPrF
zg5-PKcj@;8D*R4ybXIA04dn$oVzzC01FWR25UTywhC8V&xJ`=~)+y&XK1c<zED#r7
zUoRPhi@m||`-GSKV$(v~aUN+paB|+@&VI5(3u(66sR<iPkoMXGj#CW#CBnYsa1!WZ
z=U}Hxb)lx7y=gc#jyxFU1=c9#iIc-Kb92(sB;t4&!kRd4DZ)S}kR<QA^6C9h3v{y-
z`>JH2mh@Ae1**}@cO&S5yu5SknJW+=r)!{H5mOLGqkI|DJK^FslO9G26`DXPo~EXG
zFHj&!*uQ(}85sq$S)*6mBa)v?pt<inOqQ6V(ak&9veg<J8ygft34-ondJ9n@#G_ge
zblIIYoWl<XlrMfw3)8~+QTGMs?8?>5HFsVqgiypRtzpi!((UeKUGB`FE{KdvRftjC
zG4W;rsKdh{E`(N~Zmq`HDV~iwx!!C3#!Vg}*VQ{yrmoYub{jdWR1RLVsk{pdO$HxF
z2MhE#`})bPhho2aG*lE;R1`KfY4CGfJ@zb{CAa2c);2-u4}Bv0Yp8Dse?%u|`0^#&
z7!}vo3`r<pGMLmFt3ij+Y?7ZzuT{1Z1!*^5z5rz!M0STs#$^exfi4B*$kN3h+gZNu
z*;D9KpZ$xquI#dxC^LnS+lkpZiW~s%b>)gp&v(qdvMJvB6>k`!GG2MD%XTcUosZ4e
z_He@RMLwtN$(bw8%*2FRRkJr@%Cx8<7pPK929l+$V&|>nLLFzlm1t)hEJ6ZUCBDJJ
z`oane3k~WT%nwC*M7i&Utb`QWJ2(_Ozl#s$rQ_EvP^IUnPB&MuTInvg5Y&!=@7Is#
zY#UTe#{V9j%lhNdDCkQhfU*hyp^Vg+lE|ZJNo*nq)$OMgS<njb^Y`@hgeDibjr{!U
z>f4P}jZWhFMHGv4UTne-aLK*SoYM+Vd?Zj5XpqBWYtX-QKZomp-MF+2zK1?=#3CZ@
z3$c3*j;xlz!H%=_$6KMRBb3ZC9<PzC(t!^*xZC{BoLVMCMeQC+a~WUO=EKZF^9CR(
zP_hQ6>c4SZnoUPXeQ$Zx0X(;(|K^P#04KM~Du&n+Qu@vlR9vK{Y5m&~)0ONJ%#wck
zsOP%UQXXgD+m@s0QWB1=8}oU!YfFEWcu?uEh;Od-=-IuUKvmzIdZnZDuW*;8h^_4Q
zS!kTyLwOM7{~VeDaddRFPwLMfuNryB2LgrDOFR(uRWmn#W@-x6%PR67=aA)4?1+(E
z?fjb9#9m-K8<_?-2^gt4c<KclC>|a@jYA&A>m^ZQB4ULx*oO=ZZy~kce^i4Ox#UiD
zQk&=RdS$-pez)~GJ(@=%d0^w&Rs1FObEQE6@YBPYK_Tg;%Ay4?Rb8ZLkbFE!9osz6
z4-bMKx#!f0*i3$12TZsDsw^R~O(&7NpP&D^%*xK#Tv5YC%D`31dO1@8?4AGp`@8Y(
zWw5g`j##+5Joq7wQ|rg<-ep{Uzdvjrq~I~|BlG+VIk1iszy1DAt#NRbU;_I*+26wP
zaPBR_mX<OfO^8<OE~T)D-%|Vvpt(gcy@tg;Tn!fH>f!e5cyt%vTnnte!4@4Hk@}Wp
zrrBn(aKhdI-1n7#wni4ye+-roH1owhzr<yqif>!|vIU~fb=>vLms{v4f<1P>Ik07M
z2jeu4yeRL=m^|r2oNK0wJn+K-`TuPOktcWmDKzHSOq1buWL9dOP^3d${lY5cb~4hH
zF5$IX*PeetMtQNftZZjzXF;3zrTSf_+<1DtU!s72+p>q<xu?l5AOevnDKFN`xiaL^
zzDszWe*E>#@)@SubM|yI9d>w`DnLlY?@aW*9>8IvU={mA!VGKrk#5wb>FVpBeIA0I
z!&`98<M2RizPxcs;+rSzhpH^GPcfhI@>KG77Xf<%5Lp8Q(-O~b8R>5L67jUc?-Cwo
z-N1^htB=N9qrnj~XPs?%w?923hrsqk??gn{PnJR|Jdy)w=x9X6L<@8$>Rc`8s#(RF
z8@mPM&r%n=hQyP<)-Je><sO43FD=3&Lyi_v<?`=#I2N{%mVjoJaQR+}G}}1g<);_6
zKCyzE>FSy=wGa@=V~~Jt8t#s@_4P<r`O-%qbFozUiyr^<z*8KsC4E#Jq6u(J<6dGa
zfU(^ZAT3kQ$E2n<`e9}^5^1YdeQ~~UNX@}0j!toLt{_Aut8b_;PDRppw7s6LpNH@9
zC9`(LgIB>lTz#j~ZU>dqIqI(SYtL(HVnY3K@6eEX;}890)D9!qgkSNq;=R#7smx|L
zlKDT5_UifXrMs71MEm})khrNDyW9T*3;6$)4gR0g=*r320JE~G%{w>#{`KZD^{qci
z&o|o}K_l-(?rU-uDH1E~ntO-mR!034p4>mFn`epo<F4L|+!iyhRZj$(LD#qncva0}
z$JwclEPSwguZj#PKJ-}rkpw&)``fRq>RWz9-qg3-_gL7Uc7IAVN~X}teEDN~`viYc
zQ3NOye0_bJY3MH<@(E4sHzo>Yb@gz4NI$K*mR97i=n<xvktOz+^6BkpXw7RrfYTcP
zBQ5YiTnlSxkjfb1nt&tbnlx^N^<U@eQP)zA3m5`OP(Hr?0M|c<5yC~29~^uG-p4V`
zEe?{mxR??;5vuSX(8|x@Y@9dK*MIRxHZXks9tZnN6+xxe&o6F^Iz7K(`B=htZvW{|
z=knK<T$gOs6$x^H<hv)p{#IppSm+_uFV%`~vwN}cUYnR`lw2kpKaF%fxo`r{6jp*K
zkA?n4%n4iw74GgjC<R?UJ<Q*4UHRg63BS`x6$_v?cr(0%xgXI<AOu`a^GZW#Lw!tp
z#LFSNG(Q;$93c?rR6Dz!a|x?`V^p<^{gzq%IWir}UlM|Y%Hf=<!GET-^@``+_u-N3
zelR8ZwUYyz^4EV1aqE?JW%@h)t*vRgQNPzuWPbQ{?yFx1x>^cSh>)k-#WhM|d|Y&=
zYz5O<fY$d;`8*=@_nES~g8oPgPNKiwd8SM$1zh@HRUgb<p##T_G5-_nK&$7KXmA;4
z?uIN~8<^fbRCnvG`6GRJ|7ol6^8NlVWkZDAq`}ZCM%q|L4)Sx8GD$<JsKcQ$>Bw!b
zC(*ke8fhKH$8`G!zjfS%UCk`tw3qsckQw9~vRsk#JYg;P;{&4w{<0-XFkjxBgS}IY
zCjZ9iSt>%ncRM<7x^<_gubd-5$H+WxY!7q3Ze{go-P5Y4_!Kl_lo^dQ9}qCI9ey)h
zTrnl-Wwe<b0U8u#xC6F{OmHxBgjQ-?`}@~H`O&M%YnH7JVu{onFUr(t-^I4AB#K@K
z6fV;ay#o~+mb15YK)+XxdTCR>29K`HB}J4KI46o)+89|xChe*_1|k2-Rg|pw?C4(z
zabL&atfoHxiry^<=&|p?c2gDYAdX%VZqfMWGcXH4t2^rRPP;B;A6qF%Y6SZOl`)y4
zY>~!`K<99Eci(_}jJJb-bGn%-gtLcqM~&WvgKR3fxMmrcZ?o&EcK)ONsn9;{9t9YV
zJ>O{xEE9iek~BZO7CRZR#vR+Wrv6b!=b2Z3xLS>l?TeV7Y>?RYBlo?}I3qAzB~ik3
zHToZFoKD4u+137ma@BwI8CmT}@sUitH!V>0C8-RzuY;q4xcv;=o@yCNTQ1iaQWiXV
z<PSDWp)=BmjRG69G0|m5y|*kpuu~9}RHg`*QLNAeAlJ$qKA1!|cg6dF9;C{xFm|)h
zFXxAp*QjpfZ_q}`C?4??TppqM+@Wh+H)VKks-!*R;TH>+ynjnICTC<hk@`W&Uf>=%
zvk)Yg)95v1!S2+D!0(hHGMQ@JH2MWi2f1J1-s>HzTJb|4k-{V(`>xvOIanqAA#Y4W
zNQXmwvhHy7<A<}4gmX`*je@GC4D4b>*DQ_J8>d*Kf3uYY^q7vu!~63*%`}_!ayhHf
zy8bbAv7WtxH(ywN9c1BErRBkON2=S!avZl|zHj}*LsnQg$!*@_Ak@3xC&WY6dyYwS
zd>8rR<+M@uFE-HH>A8E>jpXR>d7LM122ZG&t>>1%Sw$6g7=+mC#fDp|TYl!u)=8hZ
zANa`f5gyxT=*h)>wO9I~y4r9o&)fd}+PdattNUA*)Zu&{upqVt>i%+lPW=2*dVCe&
zimyu9`i66kCGLt9VW?snQ<K=aha3zB(zm9<KU%vtsyF2r$$x_&Q3sslHq(4G1`)cG
z(P9nk(cL?}3ilGV48&CKD77lEOQ=dCrI?y`#oUcl?YTSO3aW-hzkk3RgML+{nqKM|
zJOfUC+}+31U70ZrcQDpaEvf8MODzAar!2v(nj<)~@?6EBM4^n0{?7Wvk+E=82Q`JW
zb+z76yo$3@=u@{fj&C*OTFVje+w97td#8%Z%GDf3j$|*@Uh7`Oop30FMg_GO9(h)+
z&&RA!1jy<of2}YdaDr&K#KQHe%XfF%nYn?G@Lpg`I7s34<33iQZ;z#JK1R(vu;uli
z^{cR5Ui<cWOtHUODvM2C-5F~<;8X@W%{1{pv3kC|J2I0O#ZIgE@Dn?kCP*;NSI4F<
zn&SaGGLa)S(=WSzz8sX2s77~>=55V0a=NapGD7Iqc)8lMx0zre;@by3@^-s!hT|*+
z|4_TXvBIw>eV2<U{T{&k%YXu&x7j}##OJCm=6~?MH7PAt{5k)l^@?r{gO|E#SF#Hv
zD`YNCfNdL&I46Afi#c`883V74rhQr!yx+R|_yjc27g410+o2poo8XnR%mU%mb<f#j
zO<ui)y&I<lBTT%qL*`Yh^WA$B3suyc=9~U~Z-n{!SeX2)0>$S#0USI+V~m~&@hA_j
z(8qTj=E-~?S$bDEY)r0EB~<7mW82>DK5f<Md*SS*b+)J1jLCxMWL)}pzvrxs1|Vvu
z0(HVaTdQlIKW0WRvKq^T-sXQ(?oq0T5Lu=g)V}{|rC=)I`%5~O4T0cW4_FqHUj-VJ
zw2dK0Sasqva)VpO(CUm7x|8hqx7D0bGHJJB-Ecs@=%1rzUh$#AjmCjJNj3chca<dy
z)WDKpRU2HSWX(;lSgNMGp8e^=OR?9H8a{k4pq1;5yrsG}V%yB*R^?j@euWw7sJ!o&
z(SJT4bUoh^e$xI=O@g$PzvzfjSW{`G<hGKUsM5};RNQBAi&z}946qbDGTf&s<Wc8$
zxm8u~9!XwxDuZ0-qAAtqP;34Ai36T5y6H2nu*Ykie(>FoneWTGrLh%`7GC?^vF`bV
zwzk>KQ*l{fJdYyezX*0&{a4}zflhXoe?xzYW<R5m;<0BMAy=;Wq|aBJ*l)$<YsBr{
z%}cw+ao<aZdY|KdN!4Sn`)W;vDj5ykr+rASUC<^5w+i{b+Qn0?!qsqAR8#d`HjLu?
zy-z6!Cz>#JOpmq7y!M_};(#uzz^$Icm|7(@gCi|PbbNby%0benqfZWv$oaej>%K{G
zk@~ltq~X@77pijO{yVt8QBSKsk?YmpCciuh`;+1y<3!pG?mg!252YWGzDp<fQ2hFl
z>UW98*+DO0si@=E{K?Rsyy{-;6RPaP=%?!#`_O$O>c#0Yy)K>s+F-nZTGRH~y#Jn9
z<uw(E&k~s-{@HQAb@mGhPh(^4x{UPZ3q>oGmQh9j&!dk?6DgWE{dCl5w8GTy)ux!5
z6>;#+X@e|<=p85JCjX)V7H|`Z6qNYX(5{H0Jj6abYNvVlb(z<(>NMzwqP^3h8l&uV
zwyAY3>Skup)k#l8*k1$7sn0rO*ro5uR{|3PkWa><@pts+9XcPhPM$b0leO-6*P1PP
zaC#Kj7BE*+ykPO<h;0g!@<6SW-ak}e;~BBoDM0_X80o{nVhEa?e*wW&^cG{bju;c@
za~M|tp%ctf{ky>NozpuvPrTI=l;YJ7-->03BPr(_VTF0;FDP?gMZ<GZ{Gu2w8}%J#
zXAJ&WYQEypVUUye>Fb*cJ{;+FX0U0ma49uZDN@k#s%6v)o>+Z{c|R^pPs2ur24NXU
zC~>yxu|$92%h;WHBD!10pz$0t)|dI;L3_IRk5=I?=G(#SJZCe(!Et{pT9rH^K4gu_
zus75$pj_O4MWgZevhnn!=obA?J3&wXkkamw#5EcYY21vOcEvA)YOR8h?iXI0jTCBs
zl@zmUyM1QQXb4V>ONi*=W#B1fSm&?=g^^P&78k5`sf{_?7Qt?_BUCDGDS2*^FUG00
z#Fe$jqNHqcjNh=`kG)!i&X&I`&(bh+#m2|r^b~Jjxvi?PaNQTgXRW7!s{E|(6+vOB
zKC9_qb*DmgqI!^;+mM5!$5~e}u9nR_Uk=#gB|c0<(KGf3Rb~UDSuoWgW7b@0nS-iN
zVV|zD#M7=99wHfAH3LFfV^rRVF|O;BkbO6&)Hi&J6Z+H@{^eTCO6zWEuIThq#b{G-
z9_>W)%U9fz55=bhBnRlGgny8C@rZYo_KIR6_>Zgv8Oh?S&8#eIlhtpzvj^4B$xYmR
z`OxHtV}@Hr@nP+H!q!6wPqB4%ltHjdL^sXUXYCjR-{wHyR67&`e8%v^z%0%%rWRyW
zuW<{i>FC+PbiNH7n{PHJ$$eYu;cg5AoD+tccih+><a}o{2IFqR;fUcf3Bz8xBWl~t
zqH%UdSJl5eu1m^_n^d>o=FXK!o&PJru$7&kdc!7d;4bXQBviIS4#vjj%cpA?+Fr56
zjM^<99n;a#ic{cG`Bj&&ZTo`4Fng@zd5W5*E+`g}-N~f=<9VZE#2c23$cmYddI1G$
zVimBKfSb03RUC|<GF~HnR0t;2i9NSF@iiZ3wPR1sWi~9K9=wsL1@Ro?zJu{Rf-e31
z02Ys7XVbJ3ZTBL}$XZl2NY8>$#MR^RTbUep<4Z(R{eK)Mt;IET(oUB@yC7d>-D@om
zn;Q^YR&Zm#<9EG(e2i>#hrBy=;+F!Kl}Ha5$eV3lqp0rztK%Xd?TLyH0P*om`spq*
z))_s2-qm?1r%*OzNf@PrRvqs9=x{S_Hxoq^Y+bbo{Ll$gr#)4HG*oN3+P~#%4~hg8
zupKBLPpyY>g)cdnA}N9SZ_%2l!b<yUjIR>kSbn<cxd-UZ$!-)>`N;n^9bbDlF1pox
zwksxF>kOnfPlqx~d`sh`v|Y`$OfB5m?iSyqBxhl9%fjd+3-AL;wbi~{%jOrQkjDCs
z?6)~gpIQkHm(|jiAizbOKXsvRLT<^##W^N~sX^n^3pGAG-AVGIt?aQAT;H5t#iOBj
zuYG)$kg~=WPrV-Sgz_?>%DPd$ZzRitxUFRI_`7iOyBV*v9!oy{QRiuP*4xk~vSYI5
zC@XWM+zgAiBXIxO`?znJpA|wT+x&>vTR(GF%S-sXNvLXq&)gL+>&B;S-yp{sA4V$u
zo3?F*wiWryriw0u+0)u1+=>6ELZCJS%DH6z^SbL!wf~jQPPre0J7!jca)A=8BFUIn
zE3oAc4)@;a;lFLGBWQa&G3>>X<r9XISH_R2-Le?X0h#-M-v~%B{b7ncsAvS)o$e0?
z*&{y5@~V^5jXajR9CVBJo`8t}e3Dk&56t;7PA5!Dta(cx0?8<MoxHq`DATWtzL`4U
zBx21Dc;1+V1S^r`0J)5r%W!yQODL4)o`43Yo^`J#xbtJ&uQ&Yz1ETkDJJqH(T$Y9J
zOJg4E7#ebwKfk3ZS?^0<*Pz-n$NwTiNzchCU8ByVG$n<>GoR;AS8O-`1<GmBOIRR2
zS<5dhv%VwO>gALB4qj4M|7zK_^YZdCGgHD|3e%oK*d<$+U8<_8R62Sb#B4U#tR<8!
zr6g>ZS5l^STpLXa+tLTDD`zi(h0{4pA=}FV<PO;RuC+CpmBlBGU!>%mzXfXk{<Bp<
zzXuZBZfxw*zA{dKs_M}vTQu<E;(q14NjSP>iF!HipY7utS3kUYsh#j=DL*ME2{YVL
zitDk9Ar*tmP!~&owDy}4H>@wmdH?^QuK%C$l>a>lQH@37DGb1UmR(*MOug>64)4ga
znk)z#17K4CCL8GO9c?JAuU8y<&KajFZD?RPC18wvc>kZogaj{wQ3XUP``0@Sh7x=G
zomZt`i`r>Gmrylm+-!Z3r#Y(>#qa?1pv(X;%GA_s&xKJdXBG(`pZ=|w86$se^Mohn
z&ed~xqse~BthY#QRXjDFtt=XG&eV%!ybTV+nnw29m$evy!Lg@MI0trL`iaBVo1o&u
z;^r2=lG!~0Zthp|`!mhXXyVnY=UDM%u(&7bLr^1j7ql}q<RIqll17uS?L1fIxfQ)X
z-70Y4*K9xKSXf-j0uTzV*S+@VDt%{9Kh8BF5Dt3?y4yFPa<DG>PyGC)&3K9i+4PSe
z2^4a<g@t~L9~2~~r^Qk=cYeHld@{4cyQV$4^y{h~-{kM#9tQ_8h+@8?2?o;E>0ToR
zlN5UfZHaMDO%Ej9qD%V(1ll=Mrn@rC>qi<o*>A=#n%1N87)$Ae{q&V-<pK#glfDYU
zw*it$qrV^Ei2!N{U=F_5l|Xl~ct(a4-Qq60>KC<i^G-u?+VajdV5i3I^R2{)s<*j+
zrM#7$o;EtlwQ3(UZKPzDl5!=SManBOh-k}TOkO2kB&L>zS8X(#K~9A3L}-r2KHf3p
z(VW=ASyyr^R!Xl}c5FXVj=cW&Gg}@$qjSHG?Ow*xX6v<Xb1>H>5wk-9=#}QrHCH<$
zQv@BuM6wN$wRug&i%B~3(Osib-f|%<QJXzBkRK@nwR0ZLP57G`Lf?uB5h>m^PP2kO
zFAK%K|E{zl9a80QKt#kxW6f~H6e_M*B2n#e11hZVp4|BFwbzwi*-RPb7D`2u{@8uE
z*na=E9)IGb{9Axki%Al+I(pIAoUMs!Q;u}}U6=d)hs(^kDi}0f0Sy`2VV3vuaB_0$
zSBO<ufHar(EGJ0>npEUF&(|Ec_h^w+5z;nZwzjTo$~Zz3vC|mLW#o|9VQ9*N)2TUK
zH%yd74AjoYp0s6uc7N_@+DuTC^4S{h(aX1rL<rVz?l<0(Qye`S$?hs^TB!)k<**x!
zvEW);4F8yVB;|>;zUbta_TEeOUS_IJt7wrb>jHEcBymYZzE+x?k<Lg~26Q-2D>>=F
zz0QX8m(lKuulqz)1$iTOUlTui3~G4d$rrx}#W9Fm>*r^&UHN8sQhsclul34d7OA%*
zW82q7mhYpB_uCD%(c^m(a5g;aT>k(7ghukT(oO~&i&$W&dTFO-!6VAGU`^w-#a8N_
z7+5PP-TTAjaZYlDJvy*pBZ5V=X>};J^W@Xv>Z=kXETAb^4BWYc^YtAi66aY-3@vK_
zS(s3^B{^m4Z=g)!S!GWLIh+eGlOv7B770Kkta@LRbnzJz6Pcp7B;oz3sZ^yNJ+=-w
zIqRwg0eG$FZc>ac(nW&Vx8AfMKP`9RoJnoWvGup$J!eZ<6f_E^X5=gHi-F=P`N3OS
zBXU~bOKZ$#dZ{|O&U|*|T_o<`=I~$H7%*OsNENk6nJn4pPpOCE_eJf+HPS_phGCt$
z)304dK9@C@KewZpGIO`;&jwaJVVvEDDww@2PGA33FPXtkPEQ<XqMgl0y`Shs@1<{(
zs$Tw$-ViN#d;(?`b}$?_Bm?W>7cYeHaz9mlR*lTeEYB=2HA9N_TC&|8ZiQL0XLZ+y
zW-5?zNuM>IJX+E?liZb%?5MQENZkaxZ}!Kt0t(26Py0z$mRE1w*_HR{wUq1-b9w5k
z{L0uE0#Y_hPbxN{znv=U?iaSiZZHN=$rC4)H#lNHPzeYJ{Em(^T)T2bwou#a_Sv{B
z>-O1pXC7zQBJuDw866;wGJQhIq9&)NZbz098efA=2&1u6M9f;H_gsKN%lCbkv3#w;
zp3uEOPRB!l47HVgIvKFCww;uG2NU7OV8GDm7AS`qBR@LM!jqedIBT_3#B!7&56ikT
z62$ymU6)siKv8DMno>XlJpeHJ_eYUO(Zyprx9TP9S&^%Wn`S<Wlw!-mNbu0_a*Nuk
z76V?*84)2_fP!PvghidA<=KywBj54+YNkj$11tJtnd7mBeRXC8rorYniHLa^ZenTz
zzfcD0QGog8)aP>e(R*$Y4~7>lQocgY3Hj2aQ(Fxkh8;tMHU&y9V>7k1S?~QsuhX1R
zRdNuwits#|68Ju=mE5MeoR9`cQMA(#XL>e5^!`;>69_jPr#TIlp~89E^uwfnbR^Sq
z^^RC~I|m&=#l&jEj`ow%OQYm*0S2C!tB@v;bx-w<c!^o1oORwOL>X-T_~sO!B72WM
zb`jficFQ;5O_KNWZfn-Z+%kUn(gi?UCAN$v7#L{F<Fowq0|(UAZee=uRAb@`I5Kkf
z9~c=J@h2$Z{NGj@RaYK#raG(N^d4!&p`Zw1o8W6Q;S+B~jo0uS{Il8!8BG1q+*oyF
z1#80vrz-d+Yb?XIf6-))PboXcw3sNrO+hTbR~yEV3UOtLX@n~%uE*gO>6!raV!)zH
zYt9{;Cb%hQK|3j>L9}goGkCisZtWVOM11i85M7ka)^RuJJk}Ic<r5_D!%eZ=(#qF1
z?CBZ*M5#)}KCSTYYF9*LkBpnp*<@-NT&B`);5^l-&U&={5T#%KP}%IG9_gs!PzS>y
zxx-|8+qc;))Un5GaObcai%J38&oX)(D!MNQ+9Zh7SlX|5Wv#S!TRBe{h~^g+Qk5#F
zyf^|B>hm{Q`O$_9$FwT-3eCzp;!eJs^Vo_0L|V8=x|>_Yl(R$0kV>V2*V@ky3M^5E
z1N1WQmVRW;2ly%oHRC0jB;C#&YrBE3-dfDZs>92e#GR_9#%9!ozhCDFP-{hqJQLDz
zD5?!Iyaj}thk@2ll0;^Ae^(nXd=3|A`ev_~IbaM(?g#M&@EGmqYi)NeR@z;s%%Gnq
zOW1EIk$6l!mYGz8IfJ+xAnU{nvRr*3ul}t$1fn|tccGT_P-Ek_NB%<iS+|V{`@T}@
zd9&~*TV}Qi>+tE5mA<l)0GQ{Rf&?k6Uf4!M(`WhREj$IvGczzZ7jwsk__c0cKok9X
zmPu9^pv}cM6e?Cq5|pD*&A!UDo{f7DGXY4<bqc0&^#LUdrJaZ)GMf%#^!~K>)0KUi
za9Z|$2e~qILawt4Dry0I<tbW9IVf&+Z@c^Rt*)rF@#o;M@%UjN6Uf$UuLLz^aUu`u
z{iSCykKZ1A`^$UYRo&KDnPB#SgcLyLnUbT&d%}R^h=N|m<!J3h6!DR8jY~9yg5F~)
z#7TgA602@U4Ld)6BuLH&J7&g(5r9`B2O*@3FcZ8y8NT}*{JC7|egf87Yuv2$J2fiN
z(mrSJQ0}#T3$J5b0R6*eyG^i<wAX%24tq&?Qrsbz)~jxK3eshNcmIyo=F#TM$>U{d
zX9Eih6ThD1nW;u}N#a${>D*&I6Y7)RB0!QZdlz>I$WgPAvDfK_k|)58;qh#5scEU(
zhvMHfxsJWEy`!BWW)v9zgUdNiV_aP1o!|MqgJ5mmP9cf`hqN7g<yrD&O}6@C^eA15
z!^@tMMQU_zj!9mA;U{r^(IEjSjg}t?3S+rYe1KN`uge#F_l5)r%2K_Y;=Z`e4op!p
zc;r#U!QrV-L=9fOVg?xMpC8(QqmkzSt3OE@yEpY{U~*4-jdvq+YW9|>pd2xVQjvsg
zsb4V-9f)BCGCl>ULciYJvhX9(YR}2j2YQ7rh25N12YWjC_XCN2i?)85+t!%X%r@nn
zI0Q?fnn$Vf-<5=FUl<15qjiLRQDIdPZVCxp7p<Lb-l|Z)b>yE}`{W8+Ch(Q!n<sUC
zd%>YpoisGGIj=Q{1%Sx4I-_Cp(cx9qI}9>Us7H&J`+lVj4048K|M>9+lX9o$m8iq-
zH@+p@dYlwrQJN1(6sn$zoOURbeW87BY;<Z-%dnBz+DkLDJPeO*+NYf>B>{4PGGS*e
z{&>RB)XaxgR`%hh^j=Ld0JYw1L@82I>*(tzWwlJ7rZoceb<Wr5VpjdYz}@O2xQR>|
zWSnNNcXSHVU3FHdD0sX+0QFwyDY=^CS>e>Cl>FLfyCddbH7$fhwa2vEG|_bxto-PQ
z(NJN_%O-b%`|C-N*X>S)kjPTw7Tet|otSa<2zgsqwT4JDho{DKvR;H7z9&xokAp^D
z>gwM&S^{+2`h-4N!Vp*0i=2O^fBzP7_<eT*8NUSRlZ1}m5ok;p#hnePF3xF+me>cz
z&f4+6sfNxjkVU1hzhi>`eH5~;Xj<#Odv@4xegoI`uDS~Um02bL5VdI~%lxu*xM1df
zER)~ppepJ%nsca|8oOfCdVOt8UDMOlQ`1yabKo#8-x6JQ0Qxw!8DUhha<bjfaK5sV
zrSm96c?jNc4hSpP6_O5KT5hJ_e82;U3AS4(fC!Odwy5Q|y|k*`IS5~b8esMyuQnL-
zofpcf@=cC>S&B%Z-A+aSmYCM+>^!;orf9Mh-aJ|6m<o$QkpFJ7noSyc6uzp2j;B0b
zxFB19GKi1^xKV_#5CdXutr;;=R$Pq4Z0zXrZP<-;$;==vymP$%6%5>chtnP7YMW}2
zX6XALSirG}h)C~rqh*m$vZiizUBks)RUzdBAwXV9WBX$;P1ya#Sud^a-@Wj}$dPXa
znaz<I5*#{DgkVoeLiXOZB}1K!yoT!GdcD^L3$`<&WPy*HbP=_Y+o~KLWE1hVulwUT
zBcseTK92n)US!)S#htzkBU*Q9A)=Q=>^H`f%5xY}ncND+&3*1m{D2V*j_gEGF?+^_
ztqaRp12dS^oK|isBO{}jxJJzKus}jay7at%DU`xu0h@#o5fS5uLhAz(OB>wGEjMP-
z$Xa`>T!E${WFwPu`7TSxa!-B+e92>Ph1X(X;8XtZJK&G$Z*(JnS7?^qf6-~%<a9_A
zn6V(~-T{1U+l6jgrS+dxLe~1t|56Caos3~be&cOnn_%3;;DuqNpfB5cT*{;~RK@x|
z#0Er0+?x7RC*9h3^zo>=fR=F}>}Z?LBDexbz6<VjLKc$!;yWrIpvRBI7iIl+>zY<?
z;xT&*m9U=C$$Le7-<0r4GPciK0?V)Ka`*B1o3gH>kNRlaKP`ANimAJ#$k+xD$^yPN
z5t<$Zk<Gh}RfCX6DJhQ>F}xti{mLYQ!Xq6*#pmOJJTDT15>JF%%F{G%pYwXSR+<#_
zqS~+s7ZSxXcA_T+SI&5Q*42_8fBX-eKZ!M2Pd{KI{@LTX9+%E4Zrz*k#lLa$MwL!&
zg`zv_gcw4BKA9#(ACP6JvBb4_ikr5)25d?luqle*F0T7>0V=4DJk8|CB!t5}(qjL*
zu%1UTJmq~r%S9sNt=OruidgJQ+>Q2_M}CXmo|AgJv))fSXd3<<y`_I=auZ^*f=QRu
zVHi`-@m5XM9jrO!<xLY6_F@w%7|$)WZ9mCrAPHx5_YC-=lIbEj82%w*)}4C{Pnc{S
zVL0-PP(q#ilv&22G!zy8sjS)^yRfBKSnY|?mOFlK>pH?*J0G8Hyd#mqlq%+23Fa3J
zDzWLWKbHLJyO=%oh`(>sEWiN8;yoAWo@28c^QbFloohCFcje5Ic!Y&@4msG`_6*q@
zTEtTp+Q};O+7+1;tb84he<;|Wo|{k3E$qp@bKWdBTknyw$~RpsR#|WA;wJI+o_xj1
zJven%b-JMEQBGJ`VOry<$_H0K7S&E72A?c_Gj!wBxX+(IWaeYL{bgBURWFW~rN(TK
zS*3a1L8{B_iGOD?y<RqHa(&IR%Ue+Pfz1*RFCdm4u72?NR`{*+>K6I*03kd_y~V;f
zH<fbaeFl2(z?DzsfXw=J`P=ngtRbtM+exr}*)96#WqiJ?fXFr$>4ZFN=zfX6^4|T0
z5=o#BXQ9bz;`t8Mk&`Uvb<!=1r|8D5j`TR^JmMm_xx2?=ZmQaoh(Rcsi!kp6US1H8
zg2*||Z3SM;V6M&9*`^X0y#^A(9ZrQwc}fh|;1DlWwr^$6z|p4n`)fB<ZusnB#I2;u
zkZ;YEoeHQGZh6?f-fG65Di_`z%h%NM4>JsPD(L<<@wKjzft8>!6-8)`9p*fAwX3kE
zPEC`g)~54>o4)bEHlWj8s}@M{{xyqk0^yDI^olmbMYn5pVr#1b(H42jHu*+A>s&GU
zVA_!R8Z^pi2mq0^WskEK(X66w?G2u(O>zZfc=kfou~$3~j!?{j*Bt>BA9rV4e>e)k
zy*Up@p62zfrwIEiq5hp{%<EVe;Ny$__`2fynngfjP`xK&v1n@eEe}hY+p*?U``1*^
zXDeKDIEb&ztnxwL3)tDg2r4CqX0YML#WBdn{NYq=$Ce?um?!rr-}-O@KI>Q$ky^`e
zyVJfD9Dh(-R}2Ytuv4!LTuYtNqJ0q;bsijHymqDxF_{vTm1=LADuNeC<Ka9TPNupR
zO}IS!b-v}W+68=<g?7)TnOq#*K&r6wK4PJPTlfmw=l<*YsFaz`PEOlmYGu>C=>C&!
zJ$4Dlg@#8)E~9Aj(P1C4)mP~0T6tbxb+ENtI=-GRF<`B9c74}V6_4D&Q!<Te*^Tmj
zX_-+QQ!aMe%i8erA52?XJH|nLY(tq)wtAeNjuLs@Y4LXUI}d-U(ul8lcs`Ct)$9Hr
z?7ekR)o&F4X`@mK2uKLhUD8s5#3iLf>Y{Xar;-9vm$=d*-O|mK=F*Lq?#>HH!#?<(
z-~P3~o!!};*_qw_({cFRPd(4)ocB5B^{x%RQl3z8nQ~qP7zma(edatJvy1$mFUQU#
z;krLnqRTsMYSwG#TZTqx>Y~aG*y2ThG6=CWrAbIHGoLA&sdmA~MED!Z?9~mr>V~u4
ztLfad$V+((0evUxSlC!tB|d7pzYkednD4-!{619EUaM_gHr{O*d%Tm*O$d70*_$N5
zI)CYFG;j6V86s4PvIM#2fM8Zy2}Hyrnl3E$waNP`40?eHybI94>vNrrpw*^ZQPdRf
zS{|$Gce-e7n6{X0l9(J0J9sYY>*nuiDfNxtVRoaNun*qCO!0_^&8XBQcP9oXTLROi
z$76L`U6oGZT|mM!8wCAqaY*gD6(4Nix^<ZSZNHiMP}Tf?b_&niFg|{}=IYK5bev1v
z9XrD3L0He%ux440_vsCSs-h13u8-$-sYT=dGS{r8yO<-9#fcZ;GV^NYedti17N_xy
zYAd2!KU|F1_;bD8L0j~8XESJij`87%crjWWuSi_3c8yleX4Z4vA1${?^w|%{+{Sno
z8NEiYl$`R)<1C?qbX8BtWi;WaU*sAsy;HBA@N39XL|2nmGGZ;NH-r3_^JO6D4qqE2
z8q%t9xAN48k9$$qE{3`K#LSaIH0?N7Rhal_&*9?jxzWXt3aZ>l`><yS2Kz2|f$zRn
z93h*}(01q88zjL|q8S1VsP%OdJ$E<cW|b_%V~vNjVPv>27j=eL0Yk>H_noB7GuS70
zt7hGYe|$-9#2!I`+1sDosyO6=RKprjyY)YVg&G6opc_6@BM$O2k%R3ozQ@)dh*P24
z_}f`%nUW`toNP$C4F-*g7}V1(S6=46eDb)f$MQLteh3kL*9FuJ_Utm0d4=`vpTd0h
z`j3^KGE1u5PF)$ygsf}9Y%#E|^1U2-KMdNFU&!3sx$)nzlG#R`<GU9@f1fS`j!P)&
zRaO{9;$iq`{&>M_yV8Yr(xMVg{MFj2Y7QR-*N4w5UT@%NWmW4ZEZGLDD<~)mTpta=
zjPUeX--kX{RIw3oEB$G4yd^6K<zCs6XpVkbNi&XsOdl2FUdt)UK?u#Q$E017z_;2l
z_noZ6{ZltE;t<gjT!VPeeR?!o>$N)5fMHkxL=hEq>?=%ygj;huacOfjChN{yBfI6V
zK6y%C3ncMcp+Ss*s<BWyTt9s%FwYv+ZEO<infW33-lJ2#b>HeQ*0VY#_GplN7yTeC
zTdvJ7_B`Cr&V<?as>5wijk;RxoarPVSXO|L13%i-@l$`s%te=!0F9z6n6`GQ(@t#5
zW@6H)ui)~Y{~kXivn^vg)ZDuUTJ?$1pJuNlFmP!bJBoUZ8<yMK?ET>l`(xRnPF3YC
zP*=Cy+KAp52>!Au;skAB-+WXwX`|?DCAQg^B)EOh9^RPgo}0UbUzk+{-Tb`v<#CU(
z98Knjmfp8=BS~NDL>wJBh=*#sOofIyHXKr0fLzC-TPZGL24~lzT&855DpuNfCh-6_
zVZ!<7tLI;w7lNhNzdxOBnawK;60#<-dk_ix1`xh@P+L?4l^sBBN7&{RW<3{O(sghM
z9Y#&mbmL#q$b^(tIpsK1tfiiUnvn}odU$_-RH&GF>F~E;eQ`2S{u`aoD;oai9tH55
z1XINB=k&7gkrQ_5c!co2d=IR`>Ff_m<yTm^+FcBs57l!EuSA1z;j<KKeB7Z4g)8R<
zW6!bf8?1ENlzW;%ET{8u?~Az3{WeTD?g&-<tT6vg>jUwmsOrL(i&Bc$&f<Bw=xnjR
zcW;ZF$b{|vJ<ZNOJ0<d3PT(E9Md;xU6|;CzH<Hf$O7o+l=6f6cb9o6;n5p<^FPW95
zD|=^PJ{=t;Vz&@Ork*(M+(N4%N1lsXAL?LfD4ljqIg8EA%tTK{>05P#rwTbQw3eiI
zkhZk3wHa4gqbgM!@kBNaC>kU{uy&V=ASt8qrHNZ+c#JzG+SDFTjpP`VE#!!k1YPC2
zMlHq=2>0Zg%U<lN-9NhOx?Vs*q7WIH_z~mNyb5NUK$Max>3X;pJTDQ{`Yno8;fr#5
z;O<OA|Kfh@w>$7i%L7RwXr%sa9zq>HSbIlVKf-=tDHlvR^`r<>t9&ID@HAbDqwZoZ
zW_v~aZJf1{%iY-e=Wx*@B<xYpV7`s1JZQ?^bF!$KaxEPE7}I`uz|O`9Y6q<J0`qz6
z@G%z8lT;-c6up!A(4kzr2EE5x4H4Wlen>aH<fyPetzL6;%u3L9?N@7kqD}pK-3s>S
zW+-%3#v@X4d!SsOPVD7;&NDkN!JSQ`lln%yVk=lcm{{v9voHnZ5H6dYEyHxK_Q@KH
z-MZZhQhkxDxOe^1u|E*|qwF*~{a3a}9-Th`%OXd6KS4oQ{o1ZhIDD@#X9CJbgQ!PK
zN%yO%ZQ1d@PS1Z5<v=AX$4`63Gw4dX&@_7i>E=g~=W-~eiWpt|89WL*6ApijiFZgs
zEaJFVdz83Lblt_wCikaM49^K-x8)hsf?9J}T3v2Gw(RMa^E^!wq@}6Rg(`w64bI+_
z_-dOOM2c%xF7ngR`tkAAiL^+@%In0$#h|B3Z-%Oq^uJ<#&-JdzL}$6Pnp^pqwB{7s
ztkvub-MW<=8$3sIJyfijKWlEblN3+x6L(R^Z{NCi7Xvq0NPQ6XsgCMmzBF*qla3!L
zx-oQ>a#I_koZc9@YP^eK1Rk|iYq2@VxL>>M2zVa48VVf}eES4Q0Ik6xQPll9w|+Ss
zL*3k!bV^w^dysvw%5{ZtJyp9id1)>Pi@^4INM|6jnY@6#?X}y6W3%$0{)EH+(jh`f
z!(6|OR<df^zJ=N9E`IllZsXdJMjT6bDZ-;|8B?X;Q{UF}Hpvp!SeN&W#p`@#4gAL5
z5(Wm@)+JQDHZ$I9A1(e`;NX(}GTIEMo>w#AAi+!N*(nt{6o_%LTK32v3H#g;_S~s$
z8Ezb4qfdQ%4t%uY0=JyTq3Q&qd$H!<n@p29tPf$CHe|TCUeEViRoR!8S7wgVw9DC^
za~aP0;@}cT7Ia5<EZ$^lh9gNdUO8&m!<O5*O<e{|W@sql5N&a=(ie=lTX0V<7@m6a
zCrDN2YUJH4gNLAn)Yi1O^Y--Y&=l8e>vswQ4rz)X4wHmEj=P^H?Jpkf_#7RDspQF4
zU$z9|#L~PnYd$g5Xi$vjvXh-sFWBU@^mbX!yMM6iWLuE%&`n!)>aDiO5Yl(JAb!~L
z{Y{n+)hd+_nK3t(p=e7pT6=P-Pm}vil3lO(df6;l^<5-Iu6dWEmG0&5+slAuM9QiE
zRqY;y#{!BmnvO>374iPkaDT@IXwh(2rt=-%;33TjQ-43henzqo{+;8~w|n#gh)X>s
zFzfhVUqF#>^!R3e@$S28W@Rlcs_ka6lNhVRulKoL@$mtSS{a^*#kI&~!ijQlrNhau
zm!&CSw#+4?DbI4MTzx|~w760HXneNDq90Ua$3{nW?d>AI^*bM_!xMY6QW{mLq?r`)
z@nRl^lZ&RDQMkIPnJd8XcdC~IzX!&U4f$c<SfMI)`_3yj14r8RdF0XzKsEO+Mk_St
zXW+v`JiZMvBcsvqWDh|n>GayO+V-q5WePQ==GwC}x}cfl_K#aDn7C&Hs{{I65Q0?x
zPg_Zvuc-Z`<&c~4tI(o?yjs_p`*_zs;Rs6PX_T>vgMopny#8#}b>s*WwP^Tr9;!BM
zPmDu$iUDUA^3!OLu#gMu9D!iAkhgp8jTu|PY@-9bzNRdTwxKx3eY0={YkGNou8A7$
zb-4CaYZY>!%XFGa+lI-WOmQ#}9G$JpT6A)X9<R>!i%zos^`Qs9V{^Qohnt&#kY>k-
zvcgW&a&gRxoPuj<3!9X8DerI95xzYyecMS$nX!CmDr1@&PNQH1zUm{my@g@l-n;~L
zli6YCQ@xX^hA2_5!DG7zV9Eisp8%DvlKd=E0Ze!fpjN|4ICV%GJ&q|pIHG7_7#Ybl
z*|UNtQ%YV7>Go8^+mB}dlwVFK6*a7c488R_BPAg@-g?bpxcA#X`{xl;?_5(*1eqMC
zR?Nj_o&6|@6GGSQ518*&PdMLDJV@~N8vhffU5SK@4W>&;P54ZAP8h6q=I7-py-!Nv
zR6r0#)1<l)^@Z!vJ;9>ER2;(dvKgHKMQ0)+qG|8VusrC~#XM$q2ag6)Uh7BqCE#q;
z40KnJN!m{bwD-+?W_@Pq7gp=0Qu4aY6>K^>Z~|BYiaRU7IN%GPl^Qr9YrUatM8!tm
zW&bA*V$a3is^Slh>#L&Y$hDL&VBj1iJu=<J<>jt30S@Ki0&ZG1#T{6+UV8)cYcEpn
zpPn)Tw2RBEc7@e>kqk+UTIEv3__D#lV4XF){0zkh{q}R9d0-ogqm|7^6iT>WwI|oU
zkiSxib<7&p@Q*oP5@y<+O{0!`Zr}WK!7)=UWJ#&&VnL4Sg(%y8Cq5dI!ezFQ#X7mP
zEA^l~N>!MH)mZMrs<C$9{@lP*FGniIlza+$MPhm%X8pL+bLxnWp7j~r*zRQ!I~BwS
zYcT2Q>><5-jD3rr6g*HC!fsYRU6;c@C2Zf~jCm6?Uuvsp6(kG}8Sc7DlRLH5<hQY2
zGqmf(s3a`Ou8nT;$`~B_q9Et^IOM!1ztdXm8+kvCzmax0U@mS@)|<6GZI(0a=Choj
zGFfI%;G?&X57}zt(a`z3W}t+q-0F?+I+Wmq7h8hCI3NQ6_L3@*RO)M{d~>L7B|vwi
zg3=IkeyZz6%}E;xDfy#RwlujEsH!SG#&-K=Q6I#fGqzs3YQ}Mz)TXh_?qDorIJ+3J
zvvE;>SjD;R3z`7PAMv@nPuH9ZeA_$o>TlfZ0)=mSr3B*3Zf423@mWvlzUpIkcK8-3
zKJV%!<j4^3E<I`}OHGoB7cel-u$Wbcvy+Kl$p>;Kz8>+9&8p1E8uF&aZ?EF*qBWF#
z;&s)gk?LWGl-{jnMcx0{4b_`JI3?0^kPN9T6`X`6N4v84?_3Idd7Zw7C1)umW;j74
ztIY=y7i5nW?LEu)6nd7=K@vy%`ba5d)3`r{t=s0$FM+#Fkm>xqoE!-vRFPIgV_M1n
z1~a?dUjbB^ORDFt-dL>#T^XYY!O_~DE4`9>{oatuGc;}bjOXG4n~N#NEk_-?+6`=S
zuAFX-k+--?F`$BAD^x{5LauP?Rzt3-qIj@7QNicr)BH)|(EE+Ouh32^!{yHzS~)%V
z-yJX&%*v`PP}0EZncy=K<E-$rwA7oZC%(jaItx@Hb%l0&)X(iFPPScU;8KA}1(yq#
zsXK$`yv}2Ca?rBLt*At0EtZub*u8ZA6VKby=Op1|VW9F|1g(SqRSZ!h(sg~a5#_u*
z2*huORX>eJ#7dNpNX5y9WV$=0M3;7f;L~J&?+r2ZAd9=)t~XA4L+KK>Ntx<nS)jt3
zRL{D5EEfr%XXra@DvU>v30SsiGmpzfy&ERX>Q+=CMO7M@04PrXs&1|2X(69p@rqn%
zSy`+KqdubKf|Zr5_9t^R+AOM27xeIS7dNKZE|t5yFB0@#$cTB;(LSxjG7)V1o4HeI
zpm}Fzc6j@>^X{aN7}wGijWF-976MA)X#LT|dYtgFlb2X$`4WDq$?omb!@Sp>R)6Z-
zjLYb@P@6|*;N!x^qr`ZL#PA;9@glERm4sVO7UAOZe-sM}j~(d^Pv&P-7Mf32nGtf|
z^1t}|tQ;Z684dNaa?{jYcN$+axL|SH4$JJGxj3ZX1*3$*EDpzZvRRBexg5{yeB_q&
z_G@bcm8k<=4Cg0m-OV28{<%V9ArR984YagvLl1;Kmri{D65)_NnpKlkJfC)7bQ&^^
z92*5FE%?ebsNuDy_NDT<^!4d_jNAMXazeM(SH7d)Mu1M0u18t|<WODJ;R@36_Gl~H
zwlEYWHa$w*X<d=K3`r)u@QeG`NN*`n2CWgNXPwx)av`C3IP-fmc@>;4e1e`Qf6nvA
zyPnor@5k;V1&AAAG&56}#sGcV@b@eckODS?=hRfxa*FQ24ZIIeg4bwVK3=B<R&H96
zw4{F_=Xd3||ItGiZJ7vK6ptNp$b`Lh8a=#T2!s{xjEsyd{VBDo<33z=F+bT$3oWkI
zQO6<Dbq;Qw#wM-mJeFI`YZ_dPKpg$`K%*KL&~h}CqJLY<RCY;T)2X{dq{dD`UJY8Z
zUS%tVA?6gse-JEW{H(UVT=^a~HS4|FfSp)LNJP};k{d!t;bHcvdtSlys<F;nX<7Y!
zF^Y1Pz%YQ1r7_Q9k^6;!yAG50jbw6MyVx)2CcCSYI65z4U>$LVk>STjG*My^F}tg=
zOczYZGg{$b-2e67;>VK|MLZejor$vRxlfuZ&8uw(D=+wMT~9-*FmM<&yjU{D5*FwT
ztgE~^VZ$ggFEbtP(6*Sw;hh7PH#brXtoOkoyV84ltOs||gCR?Mc^e7M)e~wQ17~h=
z_4$(1u3DJazB07D#;0O1QM<vVcdg$PC?uYB>30@?GBAjai5b<~(j3l~O;eYJJN~)*
zIb{s938H9#sIw1ivn<i-?PVKp^uox@<af2@b9@E*UcjaTCcnfumQ3v}XKS>tSjl)j
zZKYFQn=kDtO&>&E*d8BGgZNTZ+}mevt;7H&fEu(D=aRTM)%6=>P{`4?)+u0<je7VJ
zo8**8aGt+=$UoU<FaQs01~iD(S`>%$AguS*4LZWT_cJr22F?0s8bJw3-mn?)dAg}N
z9ooN<xDAJeQj5w?_N^Y>L?>CB#SqR`-|l6Y&qSD13)sRlou1X?hDV0@tHpzDl}z9>
zNK74h`Q&=L7STz0IWa4_y>TCV?RRQ&7!Z1934_SGkDy*az076iCT&fg4*Fe8ea^>}
z4xjPcKjC_k<bLVEQ2)ZlPI+E|56b*fbL^LKZ@XVmMCa<8JCn_FZ11aVLaHt2F9<b4
z?{S!Ev41Z%$zG&ag!to}+y&pKW!AV^YY5jl4p~euF@P}&f?UHdrfrEa!8>;-p;z1a
zPuY^+$0*-;_PHu87RCo0Hvt4Lg@~Z#+FSsfuE>tH(R^^0!fl~J-69a1oS;T$qxada
z^-Qg<%5ac1f>R{3^TBw~L0-q|bfuMvLG&U>=VF!2nvYU1cXPQ*_1v7|J+GEotI;6=
z$sxjnBR`@r*&w3LL7suL9zKOgLu+fZxS>=6r_81AmY*0a$%Gu$D2&?;W6HGbZGoJP
zNYoV9uCj)=<XZ>Se;Ou40*sn`u+W*cYp1`{CZCa!kpk%Ao2uqS7fo(gb`!CFIGaFg
zK)n{zDH;{70%ahoGsPq9hi8d4^d2%-hSPSNVOl5bAJo+=E_zY*Ms-P7kzF%K<GRVV
zTS-5gJvCKIrQJ?`$;?DAxY7L4&=^lCDtLVFQpH$JR~|rg*>|U_a|Sh+ic>w!l2@HQ
z^ml9ssjn1u5=0*S(8U3@G3k*3U#?HMfE_DbK;)~c=-hX87h^fbYBNFrpp)gdN7hV`
z{=O5;a&eO0F+P)^{Yu15Uz&ZV-=@y=<YXUzvU2mT)*s7Cz>xSVGAT&sc}FBLsU@!R
zt6(nsIjx<f)&q_9>Bd+3L#=iIQIT7eAFT?Dnh`<wUjP!w@`YVSrNiHlP|R$l<e{d3
z?uiHTsu=-xmrfc;fr*ipLrB?Gt_k$rFn)Vj@bi=TpKjYyIQ*b$l4KfD;Bz*DM8410
z`ZKNgQ#?dE)0^tZ-!OtiT-XgM9y4=EX6}CdM=s=Xs9IL++0qw@Ale+6cs9-5ru<?Z
zHNDv-yQ&#0snY$)-8F;O?zo=ExIxoPwp|m1<=AzgUL4u)eU^ex&m8{ZHB@hw;Th<@
zk2@2L&{K5v_cf5BEqu$vSCu5B`7&)MaI*;Vw<Ja{RT6U*vA^=V;s~3GAMynDaH3c*
zw>%qvrcJ$zC@Qe}LI6gE1Oi;Nl|<D=%KPyV+17@?3EiP}+;sj_VaBH)TjA3LX2-au
zb=5fq1tS!ZG^CO51g*L<M$-R4mW@UeoT4Z&G0~uDLwoZxAg=WqQwTbKJu`qt!uh<n
z*6OETX)txI((}=KEPb6X?H!~rexxiNP8J){kf5ohGPIA-+7FS_Vo!|@Id))g{25?l
z&uU`3lmRI%iUsXc05cZRcvezh0P<9s9hGvuzwM7%h0elj`^tV$A~LEu&NBLQp0=#^
zg$d`Qo8^kl*E{nat@!N)0!l1TwdoZ%a3S&Tpn76)>vM{UsiFv$MSoOT%9lMeUWw{>
z)3wHY(`5=6U<YK&9iW%WJ*+o)x)FTOp2dPRH{9$lQd7+7i!0Pxk%-M;&$Yh7$q7lq
zEvxJ0S8hkmeC*!PkEm|lK7t}n@?d4Aa*Xz_F55GFj%&ZIBPc+#AF_1PVCM(bb&;Hf
ziZi`cgpZjP#NoYyoZ@DjYQ}Ey7^xeQZDjoiXh%x2-_g*5ZOw=XZ%mz%(a{7<t*zLI
z4^I2jl=1k_E`!c58MlsgM`u<unViWI2PJQ4QHYgDs#3V@#CDY4m$j=P(EKrEsPxw@
zTJ`D(JM4C<XhuK=LG(g|l*?s`?6!Caso5?WWg7*&Ti9`J&QPwMX2$v@q8pEAv>a*L
z)4e%WNB0aSgLwC-R)D;&%vovcD`BIarkR~GMu%C<ERoag?*ydjd{QDWDtMgiC*I=K
zP4H;;ptinwKCH5yWW3Gq?TN{l458&gtv@)86>z?IYo}~yW>ylHbm8PwqtzY`vEBUw
zqIO*W-Pe4^*V&F>#{54m;IMONV;cLGOreV}zCO1A8NfJ3mPH7A5z*b!ZQo@CP<_My
zfh0J{y6JKMpONGL-`U&#zfa5mpIq~&v4O1GtiJ%5#lpe>C_iI4Q7sjH2dADO&F${*
z2OZt?qJiRRJ|b6!){1?SM18F6?Ee_uhYInSig--kC()@+8;r9j8+QT5i1XF-i~f8$
zxLL9t5WkjJmouU5yT{i6?-7y89~GVKHC>@$K~AZZn_pa9SeT!mU!0dKKo$N1_ud^?
z-A>JUOX=_ZMf$O#NlJXcwMx6;f&J+3(y@i1<rJ)Rvs3V}?k}3SH_U*7SiV!c<N=#J
zc~U(zRaSv3Io8N$BYqW+jo0C<{P}P;Acr1RjO*z&QhAqvm&wQk`$0>%Zr!pp<EPl8
z&Fp_OC1vhu`7@wom45yCijmONH0OG<<y!u4PMc*sk3sF&b4_RM5a~pc#G8sdnV`Me
zCBr(K=5Nvg#PzoviXdE4rdccAd|Un`07G$^vFrXi-*SMqAHDP1d7}xbUr~?Vu-Laq
z6f$ex`_%FuM57-1Q1LFtUnO$lynF{0A*N?(N;3{sV+!Dc_qH(EE6b}5&lcQ>;$jFo
z*c~=TazPN<`4)H(9A1FNs_U%|(ax?eSgg?5AN(3O0o82za3L*SUC<|F$Fo1N*}bTd
zn3^j6&pP4EAN<m_`-NE|tNNqP)nhYZo888{a_|Q4xw)4LxCWXOi1Q*K$hEQ4WoD#a
zE@*IZx{q{%Z>5x|A&y+-)vBJS=J2rcRp)$*!3z+<!e@8c*_i%;FAncFJV{~#z+!iG
z4&sYx3JTa<hBui2XzCELA5ZZ*k1KZd7;L^TwHW_$f_CO&dG|UezZlLn9<*EE@{!|h
z@#>$FMFpH7d4PLYX{^)TA%E?He0z;XgOV~Rs+zkaS||Ty;{}23fq-^m=B^~#r2yUo
zvDpF4rge#`S*k&*wmSg85^-^`e{veDJ_^*Ep<4651@Y!Fw!u;k#=WpPH7ylSK#KxB
zNSCo1da4cUyf!H3W9c2T0lirvq}&ZZj9NNEvoNmTYXy2VWeQpZOPtRCc1D0*+vnn7
z)^K5kv{<hSN+EAE5yQyD!|Ji9fcyv=2*|l@e;4U`7%3vWGxzU4xEZ_R=Q|R&B@r~V
zt+hxphxHUgYqziq^Fh#t_ehkeFF86f`jz*^htct!GmGNq96zpK^&?z?mU45~Rdl*a
zQ7^o<f&sXtuGe{&UR1<<>Fdd}l_g^$LV`|zmX(83c{&4Vk%)8Zv~{AOk-dV|^mf%u
zMx3YDY2u5Bs)7R0#sm^K!@jTcF^S-0K8vIi`3|>4h!|IBsj|!+pW^p{g7))Q<{*~#
z^hU%48tU)Oz0riQ{eWdlU-P@!*S&BA5fa5~<3q#?5A%*9-D}rFJ@b{%SC^ufxgHA^
z3SD4<NHk*H`Eq?WgG<XF3x{8KAiQ*i2_6SXg^_8hsS#fn07@AT2wZR9RSjc)2+m?I
zX$Z3^H!JJ?CM>EYNO&)^pWZX4q-1~c`tq*AE{5x7C)+aznrlEp9Wms}r3jN+^gSh-
zb-i2|d9H+cyklVwiY-mYOz#^J8?aDzn3-P_hx^D^F-iubobSt+n3&lL$ts{P@ZTb)
z<|0b!F+Nz`t*cU1LiTkH_4&ql0iJ8p))qncJ-;SkzhLvH+GsJW7bjb_H>P%sm2Y}L
z)H4&v%3;tM{gPI!r~7~Fn5l=AL@tvimut`=-G*n=$L|sKOQUWM?9~V1+SHf@lfU-$
zB1CyWOmzcnyP2>0EJEeb1Tp8wr~4L>5x%PDzWis<VAw>y&he@Zy|`&pU*pj~Gng)|
zTXkYyA?D;1R)*625c#7jadOdZj}JisUZhw!`$lSpV;KM$Wv6-p7Tfh~<CR#C#FZ_g
z(Ju&xBJ!GCgvugR^W$}sgeW%dn-{yGsn=U4B?eTYUA*0SvT|}6-`+#V`c1hTPP*{m
zlTM3A<2w_D5dtZxaH7k@`IbOgvrT}1!VbfJ<Z?4K_FJGc$LOu9!LS~M_fi`i{&pn^
zz^qR*vT7?PXV&wWPD_6N<SP9=+>bb!oxR>iSIq?LO@g@vr6m5EPm5UuqZw%uL11=C
zhR5u@FPRhfa=zaudg=%b%f$0oP*v^V;p4kL*v|%tQ$n`y?4k**aS=X;Y|+SS=SwNn
zEU5W(_v|lrycNwX&_jHZ2<mDD66L?0(d%s>lOk!QCCCjDV-k(!Q}bXF<{c5Ke=01h
z<grL1KRyZI*&IV2g9!+r9?)q^D1Vv<z$Ek;`dM*(ttGlOc<^%5y87=1;A3kR-pIk>
z6nt5wrDvC;77uX9_I?wIz%8wysk?~Ab5YJ$6h3HFdpoGTYbP1mY^(4acFtK8*SG`S
zGbn;QwhLyMcaog^%A*}H5qYg9O4o+&|9j$%loHRf<yQOQhIo$yu8vMrn?7=EquJ}x
zd4w;p^#MnZ6IcDcI)#wqTe_9r<Y;$V4QL|+JKr(jlnuIQ4>h}_Tpojl{cO>*E1(mv
zOJcIKGBS=e3qNvD`O0hs>R}~Dlf0VOne+Clt)m)H5xeG-SY{36A$a0HZL;%wzVoU#
zQV6&gfCi)+>dXKU0Qtnrx7Y1dE6^#bC&i%^Hv)j7ti>eGW!Hi|-X?n1p2)o9@y7eh
zQuN3svJ0ez%T)2MPV1X6)K3c7P-Ly2Djb_^08w7P6w*zET9gun+oQl9ZnOYscZ;bX
z-o4{+-J^{EQ|^}k?^Dd)`OX#(v=pSe%-`3l{XKVl4rkM512A+QJfHC_@X8iz)<Nmm
zv|S;dob)pwScpBLF|#so$tLh?`gO9APuP=6bUl!0vpH^b#LiACYHiuPs`yx1<lk)J
zfQBI(e{f<EVkblra~H8Y%orCXJ}~~`r1`#s@wDq@1t;$PJ6}MD_j^neST|e4+s#{y
z7!YSzaAr4DX<G8#3n%_$WMe|2_ChL`OCL*U8=j~ry*6TaClhm}154)xr(N^CQ}2t`
z;4HeJo2!{if(JLfWXjJY4<GaA0C+60Q*^(T3zci+<K`vfca@<d!?}DR+uN&nl%7Fe
z@x8OVn;Aqy_%;n?przI<zIw4zdo<ZxA}#VUJ;?Y+o7<~%sBTN8e9+Xa@Ln_y7DV!*
zM{+}KE>~SDc5FMW`1%tByas-M*^oxCJ!$w2>e}pj<$JKumF3mdf0LhmZt)Kl!I!Af
z`m)_0*J`HJ%3<X96ySimgZ&~x6Oi3+7?MW%0KXQ5OTm+PGp+U>_j1+`A>fwRY+k|3
z$JZSJhU9=272@V@r#x6+Lu6=V5@zG^{=qjgPMt=?9vTKj7Cx|m3+27Zh#S+32w!{!
zq|V}Ta6fJxJ_Wz8LN1sXMXY8AA$a!8du7HW!xP`l^yJqk5DtQ%P^+55X?YnFzi|M3
z&UNKX#IDi((=Ilp(hbmATp#qS!f4RJcf2k7BTE{Kg4c9F>}J;yqcAkZaf#ndCsQ<0
zHHelcRsg`kWn>Yf>~?E#v~&b{Ke9JP#L2wW=+2k9go?A?bUFnRy$|n*4@{jDwgH2?
z)S)z6F@-=FQBq<zd%IzE{xh132lfx|)R<#~@gK4G^SAK-kV{@q|F`X;{wD$O|1qzr
z|8sxLVbRdLdgSgk^O5oi7KomI+`MnM5{x;B!=(HM4NJ9_MDxe;v3gnA3i<B&y@{CI
z-mm@#y^?A9i0@oy$XLjCC~ga@g)PxS6u4fB2D;1wEY|Xq@A7p2W`DU^e;mtVx=)z8
zV|P)`zq#WtZyF!FK1cBQeqypBV35`&Bqt}s;p5s-PjBwO-pfZ|;Pqw<`3T5+OG`_{
zSkHT(0*@lR=ZVQUD3j1O6#)A3x}g+_bwGaP<mZD&t>T45_I4Zo=mgPs{gNX$^0=U&
zpt-rZhv>hT#Yx2ucv{)k=)gdWBKp;s532+_b=~-uqpW%9<hG=w<bOVAx|GV|cLE3u
zXmn&+-!0M^iUs;ccWmR_yC4jebXK|9#y*$5`|yEbUYsiM9yTjAfQ!*!)=skp2j1||
z62Sl8N}^SFf$idP(^#7dv*R}*w};r%yZZW!xo<*^ThjnrCD%GIu^^?ixeso^g9d2C
zplMHk|G(4xk(iT63YmI%<T;qz;TPS%3kQY-$%^hbe_0!qLHCG6OB=An#)sU$&#p!T
zKF~j&*XNr-b}*^aRdDo6Obpitoa?_cwKn4243@fqmAxzsy5Dj)-(;&%?dDJ-{39n0
zO(}>()d&oFr)0v#8$iRYHRn9>=r2t#!I=EbKgDp7f1WrV{`hyO|LOE~cF(@+B|S4K
zvjthxN4{@y#E;FamFng<5|egRW5fE4BmV8g+D9eIM;BKgof=d(>xX`lg$nFPu6+@E
zM-?{a_C6G4xnqh3FCNcPFB(7*LI?lEris!pp5DDJaHq7wx_Fj!W~CG+R9ASUU}@)e
z`Q-=lE%D7^Yc(k_0l}_w71J~sz7YNaPuzSnv7(Qesk86Zq+n@Ay}LrPs!Fu{WPve!
z5^f0z7Je^R_nBT(hPR(Rp0P;LsN}n^74?|hvu;umE?!cJo|{XZE>Pkv&FmXS=y_uh
z6%{#Uu`y`Mw<lTVkGUabKX7J@si`mSRW3Iq#JudaE{lm>lIrJt9%g=y{owL16qZV(
z`E11max3&jIkfL6?&JT^0s=VQI=|;eZGjv688=+yc@oWYM+2c>TD`PmDS|lAVno)P
z4aqm@gOOHB&-%5dpt&UR3-0^Ka2$qixNOW;>EvR5o|EjyXwPTYj+e`xUktK0@Qd_P
zL|n!G%Q_F%#zs}eUluma+w)IrReM0q?1~sqGZg@ttE`Rs84V+Cn`lC1Ic<}?dJ?P+
zf+F^dk|h9FJ0R)B1sHcthEA~#Z)Ap(dQ<3v<aA?W;0E9>Dwfo5DO$O<hW_*|D8k-;
zH~t5<5FiBgF$!xjrlq;LS-K+{q{HO(jWWX+8V~(zKOOFd+k0F9rVGzpb(=m@SASgV
z(7+P<^ln>#z`kVmM+P<B)kxMJWa$d%o--GJzl>WRe(U8^xkikM_Adj?L_Cl}<n}%?
z0snn|d1ZI%)<1pZNB)_i!Gu094#Vc!+!GZ`2rs{XYs7$N5R+fi6JeZ`RvLqoI|Tqp
z!L#DuPZYUE)wHf=WMKEk`B03Y^fr%^B2p5iIR^Wg<i81D9pf!0RT9@9THhG6JADvK
zG!oRUpkkq7ASpADXJHz*-uYPFR=@lP!|<b9WFTxkk3@Q}z)!X32PPi0OAh_5{Z+b#
z%rrzlrDfgPwwmTn&D0F+r;gjm;FfYc{iHRc0xY3?@78kEYaU1&<CB4o_^;vSFTGeq
z%HFacrEe*RPG)0d??tGjz<TIJo$IA;I3tu&saT3lkt^sE!CG4mGwxEY-dtwIJT+Rz
zwn)z>h?5{ZXm$+TqQ9$D)(fH%R#mI4|BdP1vt<*cgqA&C$X2BgkFN44!9Y1nB5keE
zXfZ$ED6wDKJL^i;45MFFRNxnEXV#;eAbD(~6^h#hZBv|#Gr_~yusWJ}N2{JdV&mwN
za{j8)TI4Qn7yOKK#kq>nwZS`=9O*CpSg9$pWZOP>#3GWFovr5|7&IvWfI+{3a!+{S
zLI1FPgD`Owv(Q|19v9>bgJ?fnK$fCabb4Dl9gU;<7=M@C0Tl|eVH}22)ob2YT2+UL
z?y<3VU-BrmqXs8-%keE(!Z4qZ$%yL0+6hS)_0ZJer!Y1wa*yzFqR8I0kJz%}ie=r*
zQH%q;Tu{Y0b(QErQ~9x=clzoVft@QA)%7YmFb(+UrDKerWzpS>Hukk;Wd)o~kZ|7~
z_$uKN3Of)Q9u9s;Y<6@NBZwcGHalR}`I#yf^G?$Mau^$r{=qT(H>kWykbelleA>@E
zM!>lvfCzu}Ekmh-_uZ)MP;RDIi3>Kl=;Cpx+<ez=UB*7fGt>3aBZ2#FCHH^YUJat{
zw<@rE!ClOuJa=>&UQftE4|ziD*s2=EQF-4@o;M39=xc{g!lR8w|6MXf@3A7@3$osn
z+n4CD<Sm!ggZt(iiJ4N|IrWtDcVG?|Uw*JeI<M6vk!hz7Z$A#A^3Zt~<vKR76f)%u
z!6a%_yWcbMWs>3k#TT)kTrq0#B;?i*5xU{{%><g)qkNUz+!ZkdE7haP30raZNR!BM
z6j`DFMXW|%jQkMq$d51YrxN(N(9<YOV~#^%taDg;A~AbcWt>>^c6&5|NMkIP(6CRu
z`I=71=#SL**&y#>t%^z3k+K@sL-pm%@PSc+nGxcOqcg800EBFsi<gOm8yvV_2DoXS
zeR>qgLa5rjS#21-bQ|KXqV#G=`yY!2W=+h(W)Ol|nmI<JPR`RRj&XYV#x3M+-~~;(
zH-_KYvP8m*Btf-kWM8Q)8*EhelzHW4FarSEVH~q>&9WmX*}ILm19h0px>j)wCt3H?
zS7Qm5JDGWdRP{VX8y?0I>lP`J{Y%aU&s1z-BWeUMp8sU?oc)87XY~+nVZVhGJjtDV
zIhqz8AyCAdJ~$tOz>H}nHK+=oqaWpfcu58Xhgzyg%WAWA<G9Srd40O!YJDaE#~NyG
z!yhGQ`vk9a#bXkJB2b3kD6HQ^*+*}5!pGy4`;17J<We>*_f3W6oohHmU!!a{z-P~&
z58`F)FjO^U&LbD+;Ni)*a~}&Fk@9BolvkQ7VR&rv@Ya;u!Yd6mjz{<^Ws<%k?y6|z
zE$U$$OrkpbyJZPC#H~mp3yAdnH#)}`ves^JD2|e|n2PU1A-?Z4G1|4BT%Ioz5gF3g
zjdgDC=i^wm1tgPNiOUSYs3Jxh-D@#*LbQ)%mtF-)-zlFQ(vi>9e+d`3`LgQ{)9)^h
z>_=57fK^;-uOO3;sdq)QOd<#KwoZGO*Jy=q1*EI2J+XN$+0vBgY|?T^-?Tob%xHO9
zB!~Oq!Colshau}Kf@PCs=d9N^8_eggfZ&$FoguEs1t^E+;+YQ^+miAu<*PFY;A&n{
z&EE)$#m}%!`gN|B_Rp5Pe+=uX`F<NTmEkpgYhBqpe`x5!(sti{>x|05^?*hM2_?mT
zAbnEG>~L-scj~rYdvJ5sGFdi&NGVX_6#I99LZQ+#<10;YPC36uv((|T652rGq%`O2
z2%ihdySQSf&-JZ8t^&-6EG+HYaP4N^SXZ&T|7zMQ=+iB|fv-{qfYaS_mXr3CmTvv_
z?8QNPuQ6MX4XYSr6oQCEI=+X0LCS9NhStkSTZ>qfd~aS{jEAv)<R&>v+|a^fp*&FE
zmV?rFTlZFi;c;;F*24gT_Hvo{(X`Bhf_Ig(Sv0Zgd)Q=CKxS=h?Qf%s@36vNKr1D5
za{me}qi)?Ik4jTM5`VcvdGkzvBpR`p9=h6c5g)-HKJdFq-2w0T88?8&DhprVnYZxx
zPbsg}1zd!39Bc;LxEqj>{F#v&)TV!i_6FVa8zZuRb$CJ?3_|bE8CI^f)YVM?$K9!o
zeM~}V5fQ;Sy$DoZ>q7q1OYeU{d2R4ptO#iYZXRmt*e|-tv|P&ygi`ai|7;ru6x3QH
zt3UDM7TMwbWx0$iRe78K?*;s!EmIAGXf5rjH8YTYNihnd4u7h8c?t75-iV8~asPL7
zjo#S~=^;(KdV8ZE!MoK}RnvFWZl2&Ra+;UoKm9Z4kaDmDu3?B0CwEnKIo9I`e!Yq&
zlyh+1-oC!R?(Vgjo3mOArIF?*3y+H<%)McrZzWA(t$vlqpl8+5IdB)YhRZqqDMML0
z*G-#ObfqNzm$dxGNbwK&_<ejc7B9M1FIo+BAZW%v_Ysm}zeg{L<8MeG(NXv>N+x;G
zumJonPdi7>&<)R$s66pr{+CE?<o=g0>^*e2;qY*2vZ7PfH`N;`{(-6I$U1)CYzY6~
zEcyg$p3k{?orc84#i3rAV7(Axn7=a#49S37!{^(}<9Z$nAxA8F`_5KY)4)6=OED$J
zGTtQBCpR~Dy%}?*Q~y7GYu%4H3D|u&>3UrP58>$h*`TqcaI%W8iaQ(HA6GaTP9_`|
zYozov$$4u+U03&&ek;d+A3_(eCw{6zNL~dT6K|+B(8m8Qy7F<L*n@VE8$}(szx;S}
z7jbmm7-#!D_u=Ih5dvmpD0pM<QvQL38p!1W=1U`xXkgBg4)-}j5%F4~^ea9fj+3tk
z1b2`4Gzy?)JIyr?J6C(j|Lehl5oZ|F(_|sHjlC#pYGBr>M@R5D*XXUG_{iv}%~btS
zg^`Wt`c*#;89yc0?6zIEK1lF3IeB<0GBauaT{3QpJVv${<uAMLxXy^pF&kOpB&zlZ
za);BO0cUD57MA9qw|`*5iIj%=^6c2>VgugzZy-J6BM`>+qP8bp0L4b)6>;Nv>a1*o
zr-8vD=sIM@2W`hx^z_m<0lh7>)6sUK!J~K>WeJ?Vaaes03IPCQ#(PtNE}9XAUhIfS
z<hbhj^%#^2UbzkVBQCa|Y9ec~No}gFOU6ERgj38`SQN`wPg$R`*#WFf(e>xjb=B;4
zHj>B4s_1N{tHsx|(L^c-RB%zi1hMX)@#0d}1&(yIs-t6L$QxrFSa!qZj%+-%-1hcA
zVT9iXAjlvSQM<tLpwY7Ff={D<dTOfP;W&jLeW)!u>6K&W69};ScrhZlxHo73rbJlL
ziz|hbOBQ3_%%bLKo|`S7=L1`aiW^43;Ici^B^vobM~&t=(v%~o4K%xz*d4_GM6Gu*
zox*|vavs26lum}QvBQ9#`)(Ly-!B=!efiu-o8E+6wzruqQKbWd?|Yy%x-WeNW&nk=
zze-e_AfQPRm?pSyy=5TaDqoH-4+(v&zHbhYSKbJpx!<=z2Q8S85wb(8smG>xI&V$U
z>P0PwhCBuXfM<^u+rjwZZn2L~tEnYxXxIy3*?=4c?J5DXa4@_aK_<dd@2O1rMCN3u
zTce&;&)mIdO&Qm7|KBz)HVdHa<wl#l5EiL)yNwYfdhy%yVL%iPkT!n}#=gn*BGPjq
zjmONa+pgw#U_1}T9)Hqz?EOJQ&!_EYH`{k%hw-9m(Nh#VRd)>hC{f4_Hqta!psS~%
zBjj-AsDK!P?ADl6mcL+TR6)Y!Z+hB%hyC{rZ0fJHjv@^?{>k)i^yy8IqhZq5&W@n=
z(|mH6s|q}f?gy(RR$11W&P?GHWt8Tf0b0aO*-mD=AV56fo<L$R)95cy!kaoMiRkKC
zwrRj`kOv$0Zrl=)ex}nTD<ANI(Nl1t+q~Ij`RR!(<a3K{{`iO?n9Nqn&CC_Oy=T4;
zx}RuL;Ha4iB=>4pTAg1~TyGtmW{iOeH^c1$YzmRXj_ZTz^<m)gAivVeIkb9&bn!4T
z*XJ~}P@qdc!~3_SL}(qJWgh|8*!dE|ECpeFSMYQzZLXWZqXq6{L`2WpL^lKAP&YTE
z3J-aWuZ(@C^zPXJxCIquV^Jl$iphDAyC{?{?u}RFt+R5h2ie%bul}AdK;T#!X0@!p
z!zbmntaU>9UH=a)V56%WUxd@WHK2gyyfcdWMtlE=wg2K5=>9#P@zAqRmWRjL9&3Zc
z&D~`J=2D>J2e8ue*Fkx)js2H(OS}J#r-d0@ukxLOcEQ-yvQeOQgG}e<kyhcDVMJVP
zTzOX35G(+bZSdxlJSmMBZe}GH+BXSJDs~V4&gAg`lOjPd@;Gna8QH|CM8;*<Igln%
z{^Fg6#_>fcJ5a^1e0&Zs4ZFd{yw>;Hnw6cIg3C3Mpbn31@%Y>YfMDE!@NayWqx|m<
z9w^fJs&WwPAk50-<&!u>8Vk6+Hb$<&YbKsH00xs6{8X#*b90YQkCf3+x1)-3OgX2`
zn?hMIHYu<t^>Y9FZ5=F*NQ%V7MA}V(#6%<aw#nTtxI6(7(SJ&_Gzc|3j<;R7*T=bf
zlSEjr27#5Voq-fsHa@_s2r$mP`mqJ8JllX9Us);ex4JZ~&;o<@o=sb*eL2Mh4iQmy
zjjPZe0dMpTS<6{4`Nk>=A$+lx#j2eS=Zlw5mkuN5DJ2b*zDdY!ak}2xs-%a>)ynXG
zKKZr|))QEZU?K&gF1yLe#1lsT%6%sZHJqhTGHE#&Av-FkfVHN_rZ<QSuuI*?Lks$s
zgSRg$Y;89*w73BH?Ga#}JbyJ|Jj@=m@Sqy}z;Cx3b+2P_y3{I2{u_lTFY4>eaF(JQ
zI)2r+X%6hB9&G%`gk@UL`E^sVJb35qT<Hm1N`KL$UhMU{rK_vGhYZTo$;!%&j2W*2
zius0yyKzzjXfsgNR?QaN4W=z-Ez>?yTXEcQsI;7h>Z;>wx(;PL5>CLqSxt`YH*Ol|
zzh48(5MU`ZInw>T7ud}1B4E?U>qNL$D+5vKS{*u7CmU@Vdbu}$u}011LXqu&0zCsX
zNXv=(%+fr;`8%L&RlT$jsxrmuGF4q7DM?OFrvLl1{XY?X_Dx$ZdGUC*S=#q_sdVKo
zh5x=^OlYy!@ALnYC;z&eZ`pu@1B=%u|Cx1Q|361<{Qvzo{(t|Cn@sNivj2uu>htjW
znzqgTGgd-XXt=`bSsuZuFJc_8yUnXAJp8nDpj90<72oYeZ(-byr$^|cL$jWjFZf#C
zd=|C53_|4zmQV_GePHkY+*sIOZmjbHD7cIE9u)`4+<c_uY$(*p%k{)0>v)QXe^0!k
z_M4UtFqZDFSpGGgZdx4mF<IVZQH{P3R2vmslH<K`R$ZfAJ;1ij6j|KAFE1tGT_k*^
z{OBc2%#tvgz`5KZn453Ze{^DJItozA*ReakbE)-5!7ZHEAr&0`DJ8E%=j&gNDxX@H
zIbSYr;NG*?NZK%9_f6sg%eG<F6Gw5#I=T#4f^mMbg$-{Ev0xfa_EpRgm|3^eJc}4F
zrYnfUYOt{Pot<~=_9qj=uX&W5AyT5-cZxT$Ns=I8NDDSw>$zq>hj4T2_S9?_4^MNE
z3W}t2n!R!_7^@b2fOy)(neizswiBbVoZ%)yU9(zsXv<{};pW?}{Ig<QDt14~kLvyq
zo2Nc`?~76Ca!U4m%KjZIZ6M!>v2R2d+L}e@?l0eI`Z1~>7pDmg?==-t{hC|k0L<ik
zPE^ohlpiz~-yL+z+TVS1X;_)SKC5eOV-(i-9c9VFXenHxJN{?k;C^XYL8+EoSUVlO
zV->y(VuxvSWPe#=w9eL!ZLQIyP@@<Fap?znAk6G8jm0xBHZ->O_P#@hD-E?e@@|qc
ztgf>XI)qQdh;|Zk{?>AcG8?OxQY$D{0f{r4xLHFbAZWcT@h8s5^cLD6K6?lRlr0om
z3l#KI%G!pf@OBP~AIB?X73}3p7kBOAj`6Nx=xjXT3=-#US^g_Yar*EGr)x0!Sqf^H
zu(%!{J=U4{iL-m2r+e`0jv1pxw3Do4Q8@$O*};>S+Q4{YQ~r-f+4M{Eztz)cb=Dlj
zJ;timaXj>sgt<q^@bQsNZHAyC2J2gbC`F!1X^67*VcJ?})Oa&IF1Kk7n7edgKvet*
zNWHFpc>c66E382k-eu|{9a(Zj4n7PJWrdX+JV^QmN?IQuB2=N8&{wARhxQJZ0?F$c
z6H&*43AJiU&hN;%j{@^%b58=6t*q?JJr<YJsVImQ0onMogY>KgT*f;m&+aXoXC!Z?
zC*+Eey*Cu=<6M-K&t%2Zw4CT!E~N?2lpOp&Ll3e1eXt%VM8(?&YLg@nRmTLnI%yjZ
zG(Z2n4tJPOxw=Fz53Uu$jyhq3+3iR7mVup3J#7GLFznpc-a&S=teWz5V?hR+EqIsG
z`5+3dj-H?b5Vc}i$9jB5D;pcTlsm0<$|0W6=M=VGL>lE4!;VsP3u&7ou{1mu-ae)+
z-H(bdg$?s4h|I=+>7&6tNxE&O-Mt@dNQ0DwJuv!IHBK?C0+*poT-`U9JVgx(NRLq`
z(%?t=72qTY@<*|P;~jhIi7g~0Fm@<d<p~MXzvg|`$vNIJfumQNNlRbsT|4nK#M4{+
zr9g($d^%GqCy(k(GE1W5oyz*8USnjqtV^l%#>3Sr+-KxM=!7d}EO#x@=(G(j6GH}p
zisw+9AJrUnX~<E6#tRmAb^9zz!8XY;>h=868MhT|><VxGWg>c!Qo4~Q@Lb%>s8Vg+
ze2g%c=V-7LVHZXoOWUdxcirNa1gX7LZr}P{lM!*BUSOB)wAJ|4s?2hWd0bYSU<8}h
z+D5H0BSUUmm+V1CL;houAy-yb>tyy`F2AOX1cZuY)QW4y$rDlYByQ})&4!^J_=<Pj
zG}9=nOLaW6Mcj(zb?L=gATVt#^){<94j>I3Vv5ZR=qbpxd0|=h*7u7lJLQ^{tl9bB
zT_TF4!`}l<VwqC(<IVRmF0+*0msysP;7L4lTR4{K9mga`o!yR!g%rxln$Oqj49{H!
zm_s03r!{X--=%_P1a~#2v@pJghpN~|#g$t|jK~|pjl_M{jlBw*nFK^G(bS1db<{Tg
z8K|{68b)rsjf}Y`myz`KWkY0qRc()QlX9pjZQ`~HECcJwVRadM3>a_X)OzjWBc+cL
zpVkQNH|5e!odd&%+K^||#4{(hl5GsMbebx>D&c<AQ>E~9A_&P)sg2!c8W@K|L7`7h
zIb;%G-(PAI2RkGSq6gK|l=NW=J|=z&IPk6zyzAvx?2~lbrh^V<Vod(_LPpd^#uq`^
zm2YreQD+^0^m!7e=6wrmjiS}I1?>&W!x7_83x(w-A7_+~qwQh3M#3tBp->fYC}fm=
zLdE5c2)61Al;@0C#xR7p)f<_Fruo6uLu(l(dxpGu+U(*ATdI(qJ!)2=BLjZM0K<60
z=`Vorl$P&f=B>TL35iz5Qv)6|6FwD3y-~f9g(}ZpnyE{ZEYDAlYcb^|s?~<72~dSK
ze@}>AP_Ta)y>UV?O&7OP`nGsazAT1CYy9~OUEP(D5&DOUIN38kJ(gTZbQC4MQq-7>
z>uZTp#R@mrhn|GNSwhQ<G>TzrIj9zo^ZBz?Nq5}9gT!S=r|7OnQ5I)q%}tDF*h9^q
zAU-dnub5ym>3-3#J)e|LIKRg!RwFR##ylvaF7$LbDJ;ebP%EM3(j%Fj*9w{G=g6u`
zskNj#q6|T=Y<O{n1==%a<Ya3fikRVX7)E5Qv$K<!&B6(m)zo-oT}@3LA@xy!n-dll
zJhYHhM1E>ox&kUS)KTg<U+a_d5|PliIK@IV6yH>1u{ZA2yv?1=W+McyA7n*cBta}J
z!6Sq_oH?}PxyM?;YE@ffue#+5Vhxyg#nWh+-RC=dQGFHrtRSZTdDNhM6tXBtBuUZ>
z)#IC`C@bgxtMc58Kks2i0*tfRg172*3VQ0z@_mU11d_+t(eJC(+B1^L5!6FdSQQPj
z7ZO_MVwt>RkI6G7YdA6K>tJu8YP`l`n%+H%5IL=*$`B+k(*F?Z>`p72u*jLn6y}=y
z-fTM}LYRy$vyEbUSc&xqj&J_uW?t`CV3)*;vOEo$&9$tX83~^{mBrkx%kzF~^V!{L
zbeIKn%egh{a#!q~zrZKR^v+B;8qAM13Te?@q#@qi)n!nlU}J_9GSWSB+3qA-nn;I_
zpJP;#M+0*y%V3g>nMH*?X3AaV9&|z;RbYf#&zF!v6u3D|ktwLFDO>D!qnAH(#hB}i
zxrg{bsVJ%L?1L@rf&N9?+DfHVUa_`cH1{GNVLH`n8#PhtTf%$`)8LvchL@Lk;W<$c
zsMG{Y%WbUlPB$iqwbi=Sv8g{*B;fJ#sUAwn$rNT#lNQ@VbYxf3&$GIZ3`P<>W&8lq
zgkWdSn}uSe?UmQ(6f|YI)L==@yhe<KG@s^CA73jcvXbK0WGI9u$*T6UDILP{8rYD$
zl1{XEx9}Qw&5e5=+MqwZtKiD5UEB5Mpb5=v3}l*TqY*+^R#X2_iEE1dp_9APSrQ6{
zs3`Y~^LKucJ&&MC>uVe@>_?xKSGRn}?^U$|70Lf*1i}lV?&Yr$Au4vWLFQ>|y<wnx
z)Dv7=mHd2DezPyph|c1Z^h5#FModADR4wG?2G@6BKr;Uld~H4mdTjQOVI~y>cPkJ!
z)J?^I%h1|GS_dYc(beFc8Ya8HjpDW8AV}606i>;aOR{Q_k`Benr_?sJ#*D{XYEExC
zRo^;vJ)F>Tu2zi~q9LW0q<2~mog}T%Rkx(X3hXf3+mOKWKXiPCRY8*%Cv&$!Kxj?h
z(MI@Ll1fz{b>VgG-bY8ykve?ub?4+;p^wX^=l#}?JzA*OGfAw|RHdOuJYgnlOF56?
zXi^PN{ks)2i-w)&8^+38B{mZKb-p-*HQBw5omsaBRPZ^Sfev3)x(<{q@z4mbjBnHf
z$BYG<kjJG)Zb8G_<3Yg(L8Rf<W;n6}fce@zQX(RQ+?gBU71ONalN<d2t4NFPg&z(L
zjNl2@eSW@fM>GoyC-m~%V&bnj`d`?4&#0)jwp);+2!aY8P>`UA<b23EC?XU{0afIv
zl5@^UK}2#Wg5*p=kt9njL68h01xOB(GX+Hscj0-z9;3(T?t5>K{{FQ;txeV5Yp?ah
z`OI19Ea&>Yr$UEX;GCUWqd<*8woM?1iG3I&>@DUdO(&|l=9Jv|%L|)d;1TVGx1}&9
z|12QE37u`t7HbxUt;EQg)`@lnqqZX%W(2PuWw=s3Dl01&tz+O(wy0W5q3|2}SLa05
zjMCT5i15^`Yqlg>!heB4=20yK!Y+pv98M0W3epLMV)I@w?|As4=IQ%PEt?Y)m-3oY
z;Gs)q)*Z-$cZybuSlwpE^J20CG|Jw_@jb)4IBLdpNP~{~Kb@EC*2!Yi`B80Oft20*
zO<NsAmM^v{SYAzQYG+|_a&8w-{W+#=kC$5Ay=}+Aw*1?xqqCDQ&e-QoG=>QqwSETC
z<2It5KwjpIKtZ;#Yc-+94~lUWwDP&e)$Uilsf}4-C>PIT>ZXsZ$sC^C=u&a9&e;;f
z8Zcy-<P64HG+(sNWicb9YHw{<dlBNUSx!1eALcb@$w?8ARhhi&^zahh9|D2-vP1wJ
z)>Z$H9JG{Wqlcwr&jDMm^d<J1I{XX4@T@~#(`zU|eK4xFyUf9x(j_25e9a;Z9BQ`i
zU1Ym73?WZ`vT>9soPGWj(S@So&9&qXdfX)npg(535Q^B%s13`6Db#nlxV!gnvJ|Zt
zPfX6MX-VE;<@i{*%y_G|ZcIoNTk$M@NbIMIiuF1*i)c1{>O00DYVnhTVXSab4X9Wj
zDGEP2F5Ueefmd39N%K-@;%*$}y&fZv_y~Fg@wKwe#MlaT>872ga4LUVV20LDrVG5%
z;!kY+SdYgpWKPv)pFBxo#JN8I84g;74?h+&`1ZyM3J<>}o}-p)kjX3ENQ_VqjFm@N
zP#Oh?gilaNyS&>lTdVQzRSU(mHBLkIsq#V<D#S~_B*zl7^P#IV3{S_Cb)_ckLbh*E
z`YKIY#5{exKhgT(bhXebJ|R}@sO3u*2`n04n@;Kigsp39%%c5+wTvVETb=G<CUnyA
z^>F|2h8@G&15RbWZZx%?itCy6CNfc38lYEx5T*{aKwM=M6Z~(_(au9eb3fHzw-jjd
z!4wF`<=v-Son>r~=%$u;P2-meDl}B(MXu$Q(9X;sGFsZ9Qm6|{?FJbY3L5FlxW^#F
z9VRMy5M7ORf$z9xMc$E0%uBNVsA5JlR#DdsoumSL#eYIG1%^0K$qO9Jeg!4NVbCqN
zoCs@MdPVdoqTWE`G$4u>qQd97O5y(Vmc6=fp{V}kk5-1B_Tm?zYS_?0`y^Ue^-J6A
zhF4vV32CvyVqRvpO&3IJha0i(I&wKD-`#@qZpk-$w@)s<46!k(IQ_(y=3D0L^-f(n
zUr28rl}5`dihPW|Hof!lG4++|n+%<!6d|(HmGX`<*C1sXM}ougGiry(rIGYkyqF;2
z7+xX_?g0S96e=j}iJe4dphi<AbSHk$PJM|pE3bdg&~X0N7>S}TvU-S9ldXj~^MA^%
zTZIVly@%<>6|J%V%$GKpa%s%ISXd>n-0#_ni(l&Cq<w^hW)wtFn?4<HaJ|E&3`yRO
znSd4kb$tTu5=l$vnboZuypc2RaST%RPWsp!TRy5c#LrKvAuj?YF!KlPF5ltqOeF8^
zH-R`|s(M?jd6ygNb}^drk&&D$JTxFnY>DiFx*T`DE4PY-&e&retw=qL*@Kh&>$PMF
zY4O2N8aR2_O__9}Y<yg@iU;RNMk{o;mvV#b-5AB$Xzu%7pXa7M-eO8oha+d2v>r-o
zMB8jielk^_;3<c1S9c#{yCA%eL%nzw?sh4vM_!H2^m{Jv2||Ce+SoWj#8r~RQF2mW
z{9iBZ``bkt+%e<&>qRrC+3&X%0V_!Jv670<0=9W3^bx;TguEcHq5E<SKl%E*YPyvQ
z!h|u4+&?qb2cm<s3GalZo<?zt0qn1Gd7pAqh7NY`@Fy(~M;C&iX^ke|5IWuhG9}*H
zc?}ak1LLqNT%OIFAC~OA6qII4{9=CkHX&jqS}@OZ)Xyij7WWlQ=z0|QfcPb&r)KcF
z(|3mnF>Kq>1lDQ}2D26jwJt7t+Eu;7B+Sc14bV)L3#tO|hr+0NdCu6spG|Izf50E6
zFR^`ZeP3UBj^>4&G<BWROX*g%Z(%)euuI)yiy<+3x8?1~n6`}<pcNGa!*mq|k2$a|
zz9QIGo5G{6=1%&E$@1DturYBQ{qdQlB<lMUjKTF^SXnlQ#BqkTcM3Du!@KO?*B=0z
zRCndxx5P6zpg$WC1V$C<3SQ)OtQ}6wuNXx(4L)Ts^;uZD$-@vPDX}#>ca<qPxcW5=
zu-E3otQM$#{u3W${QY|L(B|5Qm&cywr5<XOeC<ZFxvd&LnW5A2mOi8pwFN#Gzmn0p
zh<+#cQxW<pSwNCw{A87;P#QJ!g7rbHpb~{5uT{WCoPhJd?FNeBDP^~sMgbnOcj`*x
z51K2A{LyD^wTrf4{yH^BvluUh-}1(Z8ePOpRRw*jg^(IWl-2jR_Rvnhc6S2!;rP#1
zWBTvK&qp{r7|FsltcW`TQ#&P-pLw;k6^@WQ@0*+scgU`##;hmSJ1jKBG>*LWJGLr%
z@=iX|939(8GU6q6VTgP{^~B2-HC+&O|1}H1o4##s`6F%&ll4sls`3t*BSo!&IxG*}
zM3)lskwqzt#|k-`d?CpUt{HEqnYuo?sXLa~{%XR=Mz>FjF1M``j1gESc1-@r&+i{2
zYo<~ge|kJ$L$9qi%t}sHFz+1KSP!KCg1sR@E+IUlF~=8gAKk<K{g?NbiTLM#kC8ZI
zZkVwtY{V&s<&$<KX6$S#I9@*CIxCDueWbQ-Xs~-c62vfL3OkD#Po&VWi2w3CaV_EL
zbRqYa+S;M6TS>O!_K8SAV<rO{Om*T-&0`AT*rv|~+UpRyxVcWa@XC<TVP2ATh1<Ti
zs|jXl#jJ?O$DN^spF!4Qt|uGyO)e^+vH0jTSS%SAW}ds7{P~2jY<ldkOn4hKX{O~J
zYQV7KjqWoPN1A#9XV<oAYJeYoLV3zz5ipA4Mv^|GoSU4ver3ZrkB1Uya05ST9q5qL
z$Sr%CnaO?mYZ}>+Dir70CnGe3U2kGM9-E)zywM+cn7X@8-W~+T<}BIJ{CF0S_aWS(
z?^x&p1<Ejcca>A8m!V>JJ?CZatLcA&!<Y971FYUk$)2WYE-sJX+LLxjqJKcFp((EJ
z&c`KDlit@IEFmlL@BtM_H8Z2SRa5wKN#~}_2_6bj-@%%8VpzL?kZ=L%DaFL({)c7r
zu~;G55{e;UJqUt(HV;+<kAln<yJL?<$7*a&2`kR2t(v~SBr!0I+zd3Z<9iU1beebT
zJ)wA_R+X9~_ywxC`3r%mq7K4f3mco8Hv+GQY~W=E<GX*+=dnm)acOVIW%qvroqIE|
z8Z!1o_}Aj&<9{A;u(D#jU{OZjO2&6vUa88G4iSo-enm1X_q5IWfh$Gi0kz|QfoS+v
z&)tBm)gLJQRQEFc_qF|__G^G&sF&hgk*0RyU-U;U?CH0kd*9&ymkMIL7AI3ur+xt0
z6QNneb&pt-mgGOso6rYj!nc=O1fi|zd89;Kasr`$+K2T)?{6h4(b4O-N2Di&%$mey
zBb0f>hDS%uZBkvq4dN|x+~+oFHLFyb{NZKDY$$7DYD%TdoH2lOy8_wa)xUfLz5&q{
zm*j*<C<n@A51gHy?+^q|Z02wMff`veDgvkhq&WH+9BP+N4;SX^`~Lwp|J}W(ub1ZA
zQnM)qm(r0&2Npx^ta=CexBtG^5_J2pEy#O&(|%<@(ogzwD<b=goZR2>O&W1chlZxr
zF8P+4hzseir?(9(mB?>4rZ4@?lW5P~l^5l(?Xx8neDhye*xi3&5_nG@|BKqk|97VR
z<J;M*H;(uBe_CtT{%x&2m-#br`}Y6cA3I18ARW=r2ZudJ0RaJ6cR;T1hmBk9(JC$O
zcLLH<OS>K%jn>=E#TkAV8drTohnFIc0*CggD)R?YZEGpx(bl+R*WWD4hBY>FZ9xiO
zy!O&ar)hR$hE_S9wH(X$hJ~lodDm;DFU~l8E+##13E508?0Q@Q)$tsI3~*K|$RRLj
zgzIycX60nP-M4@2qgk|wfuD5m|8hicjWwvGZM%8D@W1>vu^sU%sZQ_e9`0)GEB4yX
zlpD8os=;<F$E&)~blzWDdFwnq%Nj2dbnjJ+kqsvi1ZE8rap~4trVZvPSy?F_9q~#>
z>Q&ez4ZiX@DC~&;v@%^X@$C@VMKe}yeYkFq_TDydw{RUd`mR#-iA#&5VZYJ&1E*2B
zlRtE8W&68?%cUfB#Ea?bneEYa97~l&{?#*l<dA<X!lnILTlqPeC|Iu%6!Mz(%zxDa
zOnb1#U`SH7;b+h`JTWDu)?*dh1<#*yAAP8tEI`udUT479YazfcSnD{n6knuSbR`29
zv;Hut;d|sMlR&0*V*lnuHP_`=v%X|0hnXq+#`E;1f`T7*GnMAs+3iZUAtB$m8?+6(
zG_**(56?+!ZKi5o&CNIadiA`Q$d%hOi%t7?rI|)(cBL}xcPmV@Qf^Uj7ycs><YF^p
zH>+cgpRX7n(E5x>XpfRJHhll!l;KhRcKZJQ2gPd0N(JSZtg!p`)bieGF~#~pS`xqc
z<s&JlnP$$q_jb%<Huniw1~dJdPPdw;=2-2fP^LNi`@F^-kdM0P*KlOy=3;!t<YBJo
z9_3aKF{jn~!KM?}w?8+u%RJIzxjBxLlOu_E!Qg0d60W0^z=b~h8RjBpVES9!ZR1Cw
zaqti2kS7KWE+-xs%8KY4VH8FV)1r#i$|<}Yje6fGjeHqKsix`=#Onq^B)tpx-A&BQ
z%(qp*oc=Htzpl>ioIu{OJbO^R{MYvg>OwGoz?5T6=_wzU$c>m~bmp#G2{4@E7jxfY
zyisMVcfF-hIYpBgywSHF<m<DHmhz?IRo321mgnZZshbWWnq>woo;fE<D={&H*`9k~
zX54PPQKygy%y+!1?tcFG7F+0;&4^_+Golc@G$*wVAHfrGBB+6wd%e@IJg2=&LvN*r
zw04^S2_R&9JHxr9ZrP&xoe+&LR7@>kC^VkKS4*GSQZ*e4L-fuh#+Ps-!QQ<BEaUAm
z=eKmNx|G~}q>QPQKLo>5H6?nslZ~cx+3kYF&?k~jS@_6JalX9RoWcs)d(bs$r<f3L
zIv@2?y2is&uyGQo;3n>!u5aE1cnuk?k)Cb;Kt_KRvOOu@5naCXFq;4geJDO|6XNDQ
znC!Y<?|OWyTteJz?KzgkbOj&#$iQnW&)xnhHkPdG0Tq?OBA|quTJ%~(2`;JxsSA3)
z&OCPyJi!%ZB%?mN8;yVyj>Ybo)^|E8IK;ln#}^A}px`lhL_L!WL6CbNM2G1r6C;N#
zy${!z$PvscT67!>TmxsDq)e*j*2t^J{V2<O2fF6xwK-8+%|sv;e%RR=y}(fS#!?U}
zLQ}!R;qClc)?h-YB))!U*=Vo%;=sGQ+)(Ya_wzUN?+8|`j*<jC$B`NSbzHxuo~Hh)
zJXIFf=Sb`cz!mYG9E$72X5DL};5J0{C!t@dy?&k5IK)37qWs6E1izt7#RA@GJ7U^+
zOp&*{D-;%6VlW|dr1Rjm`rr5Oizbw4?_PY2F)Y(^Qg~5Y+Wi_~QRT79r=uHXH{~Pc
z|Mc}^kueei7W4qiXh~qilZ5y80gxztdZ+3F+1*w~&fL8ox2TdKsArdsY0v^o_V3AL
zb?Xq}(r<iDwADKz`Fs285O~J`L<6vcOu{@oT!PhSIp5FuE=GwE7)zsnzO%kFjuiM-
zR{v~M-~E$jnIXqwrcj9<6BEl7PiTaRa*B}XPWZ)FUTEwOH<K-0z&Xc6X`q^xc71?K
zOkuhhzg?%&-~LCYpWA_-Cnox-ImgwS&%<vA4rR+Y#G?8^1@v~`?KEx6!E7cl##y}c
zE~}A|lfrp@qy)O^4T}oDz4$pkF78ZZ%RFginBzyJ&$kaUWfBl&t3633RYzicmZIVD
zELrgoZN1uU)gl!QL~w?C|LnH^k>%QclBMN4fnN<;QTre6{A&i-UbI*)_xA!I4r-`J
zQ{CbDP=H(*$89Lf!G_dMFF(dIaPSvv)9W;W_o~WCQVibyP_S@N$-1)1$uE`&{aX78
zW`VEUq$Wa5EkAPfgo&U^iQHvS2iP@vu{6HrfjU6*9Iuo)Dc})()i8N%*A9SFr>h~i
z2E;qwRKK4QTrTr$aNC@2;8AMT*jwuBmiX+sx5T9@pq0(g^i(ztD!%bE42)5}emb|r
zH4!J{U`0c%3M0D-B?xSWcN~z-o$POEjAb)EW@2Up5@eVZ-I9X^#A*2XDrJ%#n0{T5
zyh1k1OoqxiU{B9)CF1M$x^7|0eRK-tUwr?qBB`gVTmNb>7Tdyx^2+#C>6qh!`<QRZ
zZ=M(z2gslfHZSd{x4771tbtyv(#yux59{oD{gJ%}bdj{KV@#9>tG?M{=9~36bfmO{
z#mK=!alZ$rm6LkG)mOcIyz+ZtrC#g8HdTZT!??A<rn4p?y*I&b@16`~Gbx?7nB6YV
z&Cdr;AGl^EW`cCr4}%t}+p(O>ZVjfb7JM2_(TCDU06lIq<&|l4j2gC<Iy-`wjapah
z*1Hg;u3H{#`-fj#1pi1%yZW)VL~VSQ>WME<WKr=ukAYX2U<4DOSydz78!^8mPDmkB
z5y!>-=q)a`5nR*eN+70-Z}LZr%{etpRNFdFi^`fb;(w0Gks{^f>N@z^<UZrM-sgL|
zpTO(imv-5OG@`gK`X9dmm`yehIQ7aEnZ?{}?5j0XW$MjchODlanLNcoSJZ3sl`{nW
zTb?96a5>NcD5bR3T@PemDib*~LTxi#Yx*oG3={Gf@}S|cRQzCh!+#N1i>BcpS>DUb
z%a`(*kyK6*7_krl!e^#v__aQkt1}M-%s6#wUj7?+2t>X?I;GYfw#YA@7)428igkv9
z!V>*17Dp978z0>ny_1-_2V^>Jrs}7d0!~-&NUVn|aZ8|E7dws7CuaNi6Aiqq&<GZ2
zIy<GSAF#Zobxzt=ii#Gw>e<XHX;PkR0!E+Fb@(M5!3H301LlytTs&%MkgerS0y})q
zOd0UhvR8Y4191(f0fogU?mclg3+bKkAr5bwfvu^vyu2E_VOaj~`U&nQchf?4c&R~m
zcpOs(ze#lO<$Q|0`{ua87<bs!H%CG{jN7jcrIWAI3?kO%-PWAAyIFo-9@xqShxJqG
z=ck9>N{xNVLc{CUcR3Tw^vCkxNEF@t-tkDO0l);C|JmDTARGjJemp#k0%!f&)gsC0
zGyM0*t^bpt*K1K>&r9M_S;zL?@i`!h_q&0osz(iSwqXlbv7DzD{6I=MGtz>#9lEHn
zb9!!<*t6-zhWEDM$EWvWoH~l&F@l$G;<FTTT&XNGk~{Gq4b+cW2y{ztilssS!owu+
zs5TuokixDBvPSrHbyJqS1d!s)nl}$q6_w5-v$KJ>JZ71+svfry@*}?S)*>3;w00sa
zENoGWy{RQSIy!T3$M+VV3|G5=NS8`h<dcRoJpkPJ`SWK1&tEcCU6l5AcBNoY!Kjdo
z%+_c38lI|nIT)%-4BZHFvMtw!!C=2E@$ufsvO|xLkD*9-1w5N8L`)hFuljC|ztm!e
zt-Kl-Ev_6(O-@#{y7u-{Oqu@id^}yrf|7P~=<si)zwl%t+E_*E47fAO+Ft$BDLqY$
z_joB6!(-Hn)!;Ph1aVM77C6wy5krek-74vpmX=@=diJC0I@F2Fs1sXV4C18Zk8%!9
zqSu4fbV@Wy6barkD3p!%Xq7wdSX1HQsT*Me;e|8XyI-nxZDFw3Yj`5r7=%pcs1utU
z3m%@;6L608U{6K?^uQ4RErSXS;X}_sh)xA}CMYK<67SLEWGg^@AMdN0%=t6TfB%0q
zo^|i|nzR-5ZGszk4)=bnU!MVZcz$rN`2~b5{yXpKQ|<r8izKtkcqDD^d<`#?Ir~v6
z=6BR8XvE1A;SxEMW%2M-8Pou<_iYYwi5K|88wdXmL;o))PxHN$Mt;8ib(B8RON2KF
zeQ~&z;76V|ZNUujE1$&eFM=oyPI{ert^npDhL&J|F(qU7oEGaL2xejuy{E5VHyor%
zK2mw}rgbS|{UtNvnp_?3K-~Z6^#+xBs+8Tv1194BM?U@8a$%-#x^s7ZPY=}I9@Tmu
z+SNfJ%5ZSFaH@`>ED#~RN;75CY>ggGK%F9JH_4-Nwp=(m<56^GkS699ZJjgttKOC4
z>VS4I1;8Z+Ed(mfp_gkt1I)^28c)-b1-%cvx1)~M*6q7zaDZvZ_i|HMiIT_SN9Mb0
zw3hz8$CYB={4R|nf!ACkX<_RJ&aGd1d$O$!|3-QC&?*6`RD&hlO}IVgZ~;D`?=Z)d
z5q?s&_L^_DHH_Q$ppFtmuB!4No4reC=(`!=KJ9D7{K#`ZL&JonPKlti4a_Kjr@kUg
z%j8~(H-7dy>pW#}=0fBEX**Ffv3UUK7Y;YZekY{Zueo=3nZEElI8HR~xB%9+@^Hp`
z!j8x5JfhaD_fxs$UIGRaw?##DIO#lEcn&SxVG9kVHS)vZKGFG2*1PIKLTZ6Wmkqw%
zd|snRBdAD92Qpf2I=A?j5(mE+Dhhxo>Dl4T@|mD}x?$P+kLL58IW5wLvkKzGOPp{H
za^O>)+h%>5I6rVxh?v36V*Y`~qxoAsx4qX^%@euw{7zPplGvR<#S%`Piv66J3{L$j
zi^DC+zGT78u^f4z5@Gk{qMjHidXzga7pP@`_>6&{AB5qFIJc1`^UhE%|EhtUsB`OY
zAMOC&_`1_l@$Zojh5hEAd;TWUw9b%XkvzxvV`M9diEkNsZ${`;`b|{07BzNEH+j$a
zO>luIxyVLz0wCpQddg5d8d5`lT|bd_n2{{e9iElR>FqUOkUF#Y-m3#LDuI+fY(*JJ
zM}T;tWwoxX@dqRCz_UJ^UtiRSXnE1{en_ol|6?$N3@|qIbSH^MercLKo0V#Gqg^LS
ze6Hi~iO4U{tnK<QQr$Ku(j<3^3F*F+wc^k&s}+MYerT7mifZdoA;8J0wA>#^aEI2f
zZ<shz8U&91bM2QO>`;RW7r(l1-^yc-_c6Zx$i=N=))5@RSqIu%1~^8+H1`WR4y_V)
z|Iwndv+WT*JCcmOUZACMJR-h1Uj6X&_hBGGMy309Gau=(Lz}mjA#ZW-ONjDvs`t}l
zq=JgQi1GM6!TSaJ+*&!zTqbWY9dvzZ!u|^#8F8K;@sU7#@~)J;;kPvR8FB9edqq*w
zN&jtr73so3i)YT<%`TsSt{hfL`oiKp%y}m2c<w-ai(4A4RhDk#f9(1Ddqk^wsbM9^
z{fnph0-0RHFBe%n6^?q}1%BW*Y+T4sv0Ir~&K2LT7e3=o;c^6wn#>5tAJKaiTn=!-
z|EdL4R({*I`t^D4y-`P3hnk;gtWsIS1v63h+;4JnauYSvnrj^EC>EOJz~FSf3moZ+
zKg#EXAn<9^ScU89*_lsXY9Gz$NRgHbv!VBS-?EVhgbZ6R$Pxd|P#Q`4zyXlACU|~q
z%wa>Y6o_&?e=;V0dH#NMor_<4q?d3TjYv*L&5AIfPbH3iFw8j{dgB&%Hq@B~iH_kh
zM#SAbp{3weVALnK!5xf@8u;ftPk#UYJq?%%>EV$&Kd(*VY2Ha47dk2TKRX@WCGVC-
zWoGUqTbH`mO~Uw2=1vFUEGkDG#!&@%;iq&S+I~x<bU;zvz7FT+Nlb)yIPE<8i>^6E
zV0YC2e2;f5cDj~ly}Rgx(jw{%-gv&{o#A^Cq)z5XySI5(=bWpZ_5C`V(aTf;QJ)2L
z#!-|BeTgOq@9M;$5tpIJ_Nb9xtOcWc6YijaF8oNLkO9l-KI4pjY2vbe(hI*#lC(ZS
zW`sAs`L!7PBKNlI$XFooyRw1qW@d`3FJVvj%=!SG&0n4na+Wjf3Il1i%^2*%od#?&
zmtIYRe`wGx3dy4%IY1R}{m7_8IfYMcB({-9N4j>#akP4Lijiuz&O9Ss(m8q3d#35#
zSweigYlp#MoKgSUu(e&odH+&h%K08$6f{F@_0%3+w>hH6sHG6lv^2iHcZ)bqficU#
zaZwO^vS@rhKz^AJ)LGxO7df%-bx!Ae;WOKUu9aH6p3G<2nEN+V^bSo=l@|mGEq!xb
zttSn#6Clsqz|*w<MrZHV@+FhMQXpYQ2|oXH4-cA5%4w-rhgAB6RL7X_C~C%hYpmLL
zX`f9+;(`Y<h(NwPM{60v9nR`@Kddv}3>qMsF)uqQ1avEyXOmi~3x`_A_cfWDk9;se
zl&N&dMlhIDOHiUhUxx{p&EU-g=XuSidOjCF>gdvQGU{AqlhUg*UD8`c+&I(5p=YGh
z2BSy@UzR@abtZdd()b)0NeKo4Lt+xy0Z}8^JDYJpa*#%a66qo+wV@5(w$@VB{?&9E
zQZdML>v*+edpK#rePcy>_IAd=<p#fsqR>r$>u+UEuUp$7*9p^^^bWF;s!K&|r|Mn5
zu9`!3qBVGJ*V=Y`hx1>iG4HAn)kGn<_>*>yea=rZn*Gi{#4Rl7@FPELKdiMLwbM}&
z6%~!WyEJglP!*V@t435jhs=ok@_?Ghl$;1p@iPfSdmea__gh}`(ke}d7dIh%N#ZqN
zc7m@b20OZ4Y5rcg0>SAx_PGd@@dkhgECa|(0kls$<oj)Er>!eDO%EfBBNY%h0uBtd
zx*IWS7;~axadDkg>I|^%SK9$xarUvPronOO&|EQH*V^SFR%xyWy_2ov5BzI*oC~8U
z{~1o9EuQXLD<K*SJaXf)o0C&4{>BdJ-yKoFvbv8>9R>}=)FYf6mYbqgUif*8nI@{&
z++_z128_CoRw^Sw_=QlkjES*;gdouv?d4geO74p}w+8fum&<X7)Wx>{2P8Aom%NL?
zk6+(m0PDF<^ZZxl3jC}nX`-{t(_cBH!ANF$qJ=SJMr_FHka=f<SJGn7ET24US6JPX
zFXXdJ$|<t^Di(upmJhfZ_-o@K%5PSF&^t-`U-*o@)FPP>&OsxFne>*8e2*=Y?rdG@
zbNbInvZP_Wk3;XT(H3?out$f~&iLi@^2z}Zs5bhu#&*K2H&tUvXKl2ME<L$Tj?y3#
zdRt<>cL$S8>k~-ks8ym{62~A|&$o#l5L@pJestR;y>KYMCnv7EF9R(jX}Z}N_2NB}
z*|86JGp8=OwP$hTDBMYm;N?tWIuHNeh~9N?L^qw)QmH{!(wfmL;D&l`C!l4It#ul_
zZWOM5VUo+eath6aWzX|>FpTb9Dxw-!gh8seb|0o*eBzfE5|00>Mi<yUGx7PgtgBK}
ztFlR<Zd?YN#;vgSC*&L?1V~Zm3l|YuKHgV=gzC4-+K?X6Ba>>^^%_3+G>;W}ZuV;P
zul>Ef*r!E}RaIY~a>lxC$jNEk-t&-v;ZQsCE*A#SR590NefQO$b*)Rp1CpovRcz#W
zH*=;_DfEpijs;gX-YpXL=)!KXEoyCawMa648wU2jWD2+C`zEPjyv8yI8YkVR0P4+7
zVPwnc{OZ0v>my}a?82Vi>UBa7Zu_35s$Wb?vD`4@)@#-;EYU5?*rJ-sb<r_1D?qgM
zrzL@vp@)&PC|`gSw+I>{LUO0!jE{{q$Q*gMdW6f=0mP4(!lNxzVv^@8*-AJPdY@zk
zQ}}yh#&4i^Qp2oy(86XY-}QJG@FbTT2j?jz1_ca(Dg-8EK<ae9qg*<kYFqMG{j0Hx
zMN{g+cuNYTB9w&o+=yD;EJwaI@E%07SU(<tfUBxLe!Y=s)WI>lv!u7(xIdE!S`I7G
zEi;i9ifPkS`b1OpZfdBf2F4}2)#}D3R28c;%?1siTpn*!eurAqD^xqIUEfYLe(8Wa
zjpITFggOP#PC`tzQr@=d1gJT0;=C@8w^_Pp#92Hpen@&Bn3<YF>NTxON7j+C=+Ntg
z@F2omaeMUUs1b{ax%tfHSJ?rn!`9iS=7;O<-5@R>Y1HArp?WXm1wqc-_Y}K3WePnr
z)8-j|J}t+~S21j9ySqbo7ZI%t(~Ste&Dm$;HFq!qAQEwObUZ3m26v5F=kVKx5yZ^i
zW4ACd-_~OJezubXtHa*7o2H3WA1F0wuy5LotlL}C63eDuEJQ(|J$-kIi-ZWnBs35^
z`Lz1p_pOF%s`0P8Y710>5V`d@B;?(IE?-nVQs4A|?hNxH;-onAH7K|g7&w4qFt~;~
z)uR8~dj2Q_$R?s;F0qT@7obqyd3FIxAGnbep5~QjH##JV6lQ$R+XcUsX;mV8kiO@`
z%Rqe&2C|HMZSD>gV>V8p@|`OK&yTNEtoa;2d+<D|`ztV)?0WfLT9x^PV&N>z%qViK
zxLuG=&-S5p^|)KS&5AtZU$bYocw$-uo?jcI-U4%oAh^xNkBLo{SRO#Ps!YI=^nfBO
zP);w{DOL5qRcP0B5>tJznP2-p=6-|lmjm|P8b=jklCTfmQjgi56spx&4xz>)-b+>Q
zJR+lClV>JR6L(d&ViH<M8Z^{o_#Z$F4X1Ov;7k2!!rlkl;{5!JWzPVl=Ax|Qk*{`(
zBY<I>Am>I2##6(Ow^H~zUSGp|D|T<DrBLnU9RjR<<yFZpfez5?>oPffh6nPUw%?~1
zH>Ig+ZAu4ovn-=jR8!p&K{o9lboYj{24{SE0DR*2<&mvfQchGZnd>W5HUrhOwHs_P
z0#=g>Kv8PADBeneG=13p{6hp*sirjhN!R#nsIrQRR<<#2P4IsIOqFG2y|mtoT00F1
zeMt^SMMcFR`HF|l+NBvlR>Hcp8SteX=0j61&h~h~O!ZQG;suK{3K}H>Rd9=ah8TSH
zSnw~ryBfPwwAn^zI3^^hg~G~I!S$If`RFAE-ZLZaKOKPOueBLNZT+Me=aycKLkx#7
zDJ8I}{p0*1bF9i{CUJXgrz2IAFrUO*OVaVg64`}A4Hq#<#iI{vXD&Ssn@F3fd^5L?
z-_BAyH%xJ8X*%f6fzAc$*6PfqI+GX}zAi^*d-VrgRnx%k)!f~I2cDDd?d{dtPUK^r
zC+%%&E`2PfgN%aA%kMYt`W=ZSjdFXINdDL~1!X+E=XySb$nOy}X%seYhv-Bj9h%~M
zL8phmRZwy%93KocFUl{^4$1u!T>?yUjz=c8)dQw}dF^+qns-N?SdC&q^vi}}eX?*U
zy|ho~kgv}!F=6Sdppn~pjMe|m@)EYzAFrj)Z7R%GJ>@#uWa@PSp;}(EE<GJUsMt@`
z7^Lw7y3O3&uXbkcQ_dMcwW4j&Y09s|KrwSHaPe%fUoCrSNzaaBNZAfp4;AV2;+HO)
zKbd%WvqC#as3f!>It(<C7Wh(ry9z<EF$Nxkd2{l^MGb;xW?SR%V-gR49_j9N^O@#i
z=l&)cZoqfQ;hcCp3q{^{12|GVnK*E^$mk+H&^nd*6}w_*^)w)hTyAWXfZPBHkk?Wj
zC7`;FyX~>layr00%CB34Qfi#G{$M2h8VH0u3AV|+JRY6Yvu|+jip_J{E-GuJo#vNG
ze@3ROsX1brXe8>_`n=k`X39{&3S&NM<d48OtPLx148h7y2uLK9O8p;7&w(^ZOL%Ot
z=_Sy{{xR!pP+Bh`yc@!D;I$jH9QP`Co$!&5$L>5+MRx8#PqtS+(Acwaa|<QCtetV2
z)rVF1HJ{D%6GfBB+kaUd8LRY19MQMH0_MTcZnMoXaiO2j!D@%4<)E0i8BnBM?oaWb
zc<6o(66`h_oe8X1Fe#cIo%z+O+Ha>tTtiwP)|Z&!j~ZQHG>&&a>`0X!KB{uxmg))~
zkT`AhvARyMPdd|6s!^1%))vNd?mktI!{%yKg-0EnKve8m*|bK!P90A3_}|Xj0Es@u
z@rFsZX-|Trmx~steca{P^$kamaf+RbEH%)}4j_^TlxruMQ&M2xVvcgBy%+C)OZUTu
zggzQRLi0#TZ*+rI_71eUNbX}E6VTeO$AJRGmy7Y87MRP)>)u-I9$MY3v}x;wXXpuT
z-Q3)~=+JFz(h|c$$5!nM;*dzHy&Rhk>0=DP6HzLuF#pi@q5H~@izMWw^P%Lsy(UfH
za5!$tcl2RWQqs2n&K#&DaZ&211qB6R^%XNGp3Z}irt_5ej?{V8U!Zpv88@4+l0i>d
zn9)g-=#w{n`hC6ZMYU&QoC_=#KJBr`Mf5E;AT%s3Yi;OsyLqal`+Q&BJl*p<n3(3~
zaKOeDI>l&P@TM@i7akh&ZeZmf`TgT_2Ba!?=EE)#e;N5oo)pbeA%tzU$(x^be>^zx
zJV-)*Fmlgn!*P_>zcBQvwF9Qnbn{mooaj3WROI1ToA-9RZ#zWc`_b`o`BlW>x0J~K
zE;*T6Q1Nn9nhvq4q|8((+pUUVKKltmm9o*I{Cp6P13P@=f9acbHp`tRet9+&Rl&xo
zgg~mo5$bvAo+n*EZ&?#5ENe<FU;$`Qk6tGl<-6UOY&H(&yd0m?y5zI7S=pCzT?twS
zd19S8rt|?!41r<P_*>^b5YKrCh_91cK(%5Oe4L&B{MV`rs!--xPiK@AD}pO$u8@V!
z|FWqzZ(m*8LJN+F!%3a&oQLt0+Occ_OKSxR1*R^yayi+?3ko4p-73;lqVs|7!{5E=
zv6dG{-`tURR?5;FG>K}S6nh=38AxA6wbMpurLTw`W*)!6?Dp8?1@mj3KSj|4Fn2l-
zG0F6Tva)NPw6^E5=R3n&%E@in=UQqp#x(P1S^rfFSnf}AYiNSV{N~g9jxta8z38i*
zwj3?pY(4gW=n-_|Mv9P~qO!8>V0N8)2Fi~(L>qgrB7U-Bkti6E*o|nc0y`bqGghOV
zLab7xTRTu~J}_<2;MQe@f|}Q)rlx*9c2-hK5wzBo`#T?cn^wRDoMquDmv1y>4_5*{
z1JMFpUbi`_P-EBj^5Q%xslmm|U|qB18P|AGbV`b~Kr%`yoL#?aG^+6e#2U3$!xeUy
z3l0(!P2vvk%@wVx4r*@T&Hf@kY*-6Ia7{r4rTL@oC3_u8l_v+<)_}NDoK5X<OlBxK
zYUJ1%ax+FrutTfzw`Uw?B~P=!PZifOy8kQJqAVl1`3j+hsWX19bw$pH_mTZSfR?*C
zfIgiP=}<yW5yr&D#YOE)smcNroENSue%8H@H|V(ULw_Cbu6*`1Z8nhAz-+6isE|sV
zli<xN>>m4^9&8R-RCjf;T@|s@3$#+JT7)dtx&rX<<Wuok7H9vDf^i!6k1s&Ol@%0&
z-;S<pkobvS$9roP>gDj0a3FlasqWst#b==hcdovv29%fsFJ#&ab90~ng-5G~)z|=y
zvS(#iNJrJ{pr%Y+0vbp02?^tyZlF5-ywIo}l*#8F{3&)*Y<Bihgpo~(zRxDdqkW2H
z+HfHdD?}OffZ*}u&EKh2Fc-cXp-@jx&s1rAyvUn4C2i)H%#}V|pgo(({AS-C+5Tp5
z%>}fc&&_G@?iyop97e5TX^~E#^8!l#v$=y7pok<$9nrIx4PasAj7D|fAGj(g|NV0s
zdEj<bZ<SBz$rcSWF^`+HuDWc^pp7K2GvGZ&E%azMJ244f^*P$ESV=LF-_<tM-*j#t
ziid{!H2+r{<BWp@PmO-27Hr!uU$ohwKms8-y7Q0={659{Y%ab#^{&SxHxfSedccG)
zsn0BDko7Wq-9-%aT{y6LYou6^^}K-%j54BONn8{sQP=StK1Iqnz`CS&V$&w=60hNX
zBvzhHWD5)G#K-$OC;p~|t&KxE!b{RGV_=)~Ocw=u21+?G^Gz?h4_^eHnX7|?_D~f2
zFVSwK6D{i>=B58np;7;n7Sn$tDC>Xkmsjqyc1Na(CvqC3BM{zGJ4F#MWCiJ}eHIlx
z6&i$WlZEa7AeBVi9vZb2e*R&os;cVe=l66jTn7!dYmLQpqj9j?eJLSODPilPkTUPa
zB*lIqNFCqqmJJ;G-lx}mv80zr#-*3;@Z0s<zmSyQN5oM7z7%P{`2}`@GYP-ef!`d>
z>u1ivBoBSuR?MJwrMb*W7C&<bFV01?j&W;wo|5V3qIL0-a#mKTKb`ne+IO>6z8#T&
zGsur^UKIt74~<E+M3{wnw&O=<VtM&&E16LIcL-#Q$aSmihQxA|5<#JVXV=(|w$@~f
zFQ?^b10E&s<=1Y*mp7~gM{x<Wj4rw*Ce^u&5xdSe@EU(xzC1iO#}Fa9JaF+^v?tMv
zJzB+J*ML@a3d7x03Qp}}=4@az?Wbx=G<p&iJK_=&P{z+Ko-HgbaT(V8VB;(gr(ESh
z1S7j=V3&BCpE^QOu*!C5sei(rBm)tjc0TlFm(s|?(97%FkKV>cAHnp9BMS^l(7L;^
z5wwKW&pExCvfRra%{d=zO(^}r=*_DY0|ww_y+#|Im8F0nCHC7;`iB#>G#(>V?+Rgg
znV%ho61e_PIINviI74h4+52JC^x5X2v{tEMleGCI1L+hGj<ripI^uNkP<q+Wag6C4
zy2??_5Z0b8d^RQUW)-^_dtx$g6eT%XY)O9A2Kvg&^}mF;>O-8SgUlHjCGSgrOXsu2
z?v3TN986pE)9Z`#ho>2STX|;z0pfNIg=*hi{4H0Hmq`HQ$pok+%m6SzK27QQQUkB^
zGM8#VJX2kQ=-jQ{<1-ME$Ao}JG)h4^FYkgcf_0KR>dzh^Y5zk5wNA1*p6;o8NyTq2
zP8&IFJqo#2ctPf6Vp3%>?bFepmLg=YX{B&2MZZk9@&ycWFGdWI`5eIq#L`MTE_XY*
zg!K=ngBkeiUC;OT${72*IsubD${=MV2YovCGmIxL8*V|rx5N`25dSjO;aQlV^~eXF
z8JqGd&?ryi=5~|X-QNQS9`EfD<<KnS-=^)TVZOotN1)Y{T(hh-MDWWLDLrPd!!^sB
z6Q`wq=U$0MK7;Pkk$ruAL#tK7hQf{BFKR)E=L!;m$+Jdr`zARv6axZrP0ZCs+OoR}
zIJBK0rR>uV2GXl;AzmaG06z63ltt%e4O{W^)pz%$OExGu=+;?946VkUsNfQfc{t<N
z32^J90)ink7oRF^Pu)E4fcS(mS!aRuV!p_pf|GdPTLG%re2~n6Ilo>;=Qpgk?f2Pj
z^JH))s_tNoW4HzEc)yB1V?Q+dF*+0A2%F5yOi&{&4As;^XQ!Wv@QZLsETopZ!lvW<
ztNi~#2PwY{MAU=XrUP5skar}%CHeTipNT-TF+WW?PSSqXCf^!MjBoN>7h?KBTUHH|
zH7s-Q-UnjNx|eVoVXJ$|mlwed!{cg~en@?n7Eg*Woz~&eoR0lf-+A1q;rVU>&r+We
z>mcj?li^PQYUo~U*mMvWlcCKuLb%n?uz>*Vxv4u;Uf*_IM>xSU&3?+#c*DfQ<NrJV
zs~V)K-d$@MG$+Ta@4U|lY5~x85NVBt-rtUTz;-Ner3~<a?1BI^eX;xFI)K_auFO^f
ziAjNz20H!HuSCg=f_X?`pOp*m()xKm!A;N#^BkCNS{Jg5a}nO@9Wv>U`t6rMshVca
zh9lHf#5DflsGeoL-$4D*Yn~wuI`JRGmU{>*fNTM_awR2YuFC>PboixfE2Hc9@?If%
zZ1M*qS2+NNjHhPj;+o1p81p3?`W$OCOg-{T)XX`5y)m#>)w9?;oxwm}qFWQaerrIw
z40Kn*hX@&&nG3E<(H>j+eKt-HkF%C{+yxS$h10GFU->~!_%%#j0FY#n`iGvKUAsEu
zGPI$u9f%)2UD!L8_dhhY$ZuMa@zSZX=$d_cox|r9D-YW{--X^1y;`xnZ3yfp%&OpX
z=8k_^lg<MPDMg~^A_hp3hcGz&;%JYjjt!T`_Zz%Fmy@>_Yn?P@(zy)BTaw;RPR_Ez
z=YE&{y)RwsJJlB4>I3XcR&c^IYFB%>4gKH-5_C&tyG+1KSR~}suKLnC>+)t`>-vC%
zY?{!6h=`vwR#pw9`Y<P$SKtYWyc!7Cpc{h>IeJ<}f(`{gqg%{PO&5=p&a+~4Bl6X9
z_8C)3D&!1+lDVP%Z0<{OH#2Cu*p!Wsk@Oimu9R6hxi=N3_ljN@C<+q$$AN~|P|y`_
zUPk|;ngi@`h@3LrJ+j^FYSz`iZvw!4r+szEN`Xt%Tzc1+B5V&LY?%B9Bj@;b8{KlJ
z>W+2Cdz3{jY)qnZ-01L(qtjHhnEQsqUc_jSv<bkdI!zU6MeRru$$As5RlS2BQtzMa
zTrb5m9RY0NVrUN!krCzyf?!ceD!p2bkHY0Qp@1xIE;f&EunyjVHO+fOMHMBDv$3>X
z4UkjnCPdb2pbeAtqfT7|zRi6({%%c!DWj|}YFl@$(+A=@y|N~s$$IVYKMK%DZ;S!j
zuiejk5?KDV7DVMMs9L{oFT7vRYUdkD)+eGz&6GBNl$N~Y)U8l|l0Y`VC}=xYU-DSn
z(MtJ`_ldk;ULaC9_1zU9Z11#rAFMP(TjQsI)&oJIBAa99s!RWcZGVF81htSwCjQUN
z5<hLxTYr`^%*(;4L9$1)I5s5m;e;NkWIbChux;CZ4>%U{0W7zJQ-sT?nO$6*#l>0A
z;j(_?d<>r7SFl9pBXyZvy>62IYt`rEI1!|(FLGXwZb|YXy|tfnvat=WUtbsH;V}Yv
zCEnfOf00$k%j7EJw8LWYww=E2Gh<o46MXyzc85a)%`2?j39D5Y3;;KKH%$ZM1j>!b
z^rJ*CiTI<lo-#@<9p)rOzT8O(Uzy9-i3R|n0^R`KAM{j?$~O7bBX>c<OF?%(Q+L3;
z^3FW1+<YLt+4t1NVpKC{&<23Xx6XoK0-!z3q-wSP#bFmFC^%eZw7nqJ^e5(VT=Xaw
z8SVr)&Uki3bh9tYv-f9ulXo?>?NtCk8`Y7Lmc~Wy6-eLo`ud-<*hv2$6jZr|JjvC~
zI7a+8;P?MGL&bQ8zV%&?#z*LZ<-<gv#rWsZRPRN+C>pk^5=$F=d`T70p!l2Bja@!q
zX4}0%->w#bg@ALsDZu<%NGSmp`5pvMxuuMr5WvFU**7~OOcU`!=f)pY6u3@q_r`(Z
z-hY5m?+J<S@@2JY0<v|>!WlJnbr|f4{qPkis)pe{)z#Ow-GZq8n^B;6z|zsvKg|iT
zjQnWn5Zk%JTG8VTniyBmqeO5io_Yp;=;Wk+*(k?w;``@%oY&<x0uT#%PrS4A^*9sa
z0AliAU5GaELJ=TnBAy2Af`-)Oe%eG+<RD{ems#0kF(yJOa5x+SDv%(Zc$)nlpP22t
z!k6feSqI7=-#xg&Qrok*7ysZkfhXcBBEX~l5Eplkh?0z#(Snut@32`$oga%%iUKc{
zlyXL{MlojpDRgD2OUR^mlnrSHaH&LohX?V)R(Uj6AHEgK8eM04!%F!3Mb#Ce>E!%T
zlwQ#=GZPaV9`QYP_W!B{fJ;^7F$ka$!5ZN=$o5~jsLG_Yeee+;h906!CJ+~x#ZW(x
z_gp7rlw%aY8vnc#u{?r1f-cYF4MX@cc<x@@CJ4L=tMFVE%Saii!3T#SajbiUG({a7
zjei2)NII)aQUCpcrF*#9+($^ctEpmeIke<QTc+r9%)c<c=a63AALWD(uRi*}8!h=*
zIlHizxYf_j`ndu1XvryYql>+_p9^KF_e|&FLLzwRK5oyv{e}){1$Cv<hGNODFnv)^
zl3JEENgTNGw-#ZQrCyIzAdnDr+j5ar_-JC9bz<iN*Y4&3hgEb!fqF{LFN2N!PA0DQ
zWD7yI4&lnK*+cP0ro0Nph!51lakb);Oj7=Dp0yV_&RpE|EH<<XFqD_O2X0tC$m14t
zTE>Krio<t|tSI-{lR}74Ll~`HVba2a_*xz#>o6kDVuV%EFpFOptz9;hq}<`xaA4rQ
zm)Ea}`_wcRq%m1EWR)zW$i@$sVuL8_mgHBEa=c+e37nYoUcuo}Y+C{FSJo3I1xKc*
zJ{P{CZfLXs*I4o^UfsSAO=E8I<?_hkd`6wPwQ`8tPYb78p?SK)U!KNti^-8fT-<_t
z7P&1kj|)TJMBeMe5{H_8dQUF<>z@)$YoRq|=BB4cEyjDd(kimU34C3rtCOMZ`cT(S
zj^cl26o#Q`o&8+I89XZYE>H`biT=gKo<v`-wy6W=W7I4oQ|1%-*)Po1H_P2G>2E|Y
zMZn_&tC_o?T|!~?-k%mSKHzL&Tx^`g5;Z4dkVjii-eCrYAu597LuDrzfN+FSC@Ga|
z3cY-mDfTk-nbaXY6SZKH0tuwd9?=RtGKfvq-%5U{!}wSJS>d<bC5E6J_BC&;<HjUH
zYtCS;2Qg~2^p+RByPe9UqW#(;d`zbo+!!dPM9sRq60gS^)H1T*>phJdCwti?<ZRJ=
z&x(3PX)@6^af7is=A<xWc#>H~3F2USzw-r}v##I$7s7>-ScnA4BG^v7E2q=@VF!<a
zP3>n)F106|jA3Y<WwpwcPAC@;b|=1~xWL2)5pO^t$noxsK`QMrKO$EgtY?d{km(-S
zZI4OX<sD+*#OUXWFfe6eOo}#t_+4M~S$uW;tQ&6nh#LrLyzLxmRL@|P*D&7}hupx1
z*B!Te2DL|UjHhilhy)BjXo7OAK5I=MS}oTN*8nOegZj-_hMul2XN8a5{pG@_&9FEH
zW*vq3mulsD%w)y+ssu{PH71MqAW!aWR<M@2&s;q7e9`sUvP;ubJ$pEpEin@tNcXPz
zt8P^sSS7s3XS*)pi29*KlklHEzZ#lYwaW?}4r3ToR=t|+F0<q@1-;CH3jjuArvh<H
z&r$Q$b4`az_I_W-4SNnk3@gdPow4`$4Af~wMKoAj-oz!cv<t9F4wvqxsfwF-viET~
zbYEh$@*X{5T37CNzu`6tPADdgamjSEwx_yL7oxoOt!LYO<tFW`MSf}=S=ZG;n*DTF
zxCK(PVPIEga=kEE0T#=Sz(kt#Oj`+2Sfs%|z^-c`_7|{G!&U;Z6(&PQ><UC9YcJwd
zy{|WXGZh*hi-Ep#b8b;!E|-7y5ue4=2(~sjVr3-mDZci%{v(yHxj6TQK1GW7M8@^*
zxq}6WDNolMB>|QRPHcdwq_+~I;Qf<pOl&zOTuGKZP5_Y{=RZi;tt_MzWV_oMWfa@s
zzR?e`kf3m9IEl{!q0DP>f+rov3Mc0x3-o?F8MG()o8(9fesR}v^$47*y8f<3FZ)qB
zTx<CrtOroN89vGM0(oiVo7&uac}vfxc6=_rS;->v%ZLZ+Fps$gw;Z<nxT9%Jl>W&h
zuvR_}dS~cQ7O_S*F2N8@q@<K5!(wl>oKD=2Q8!cRA(kdNi3WyY)`A=?SRW0{h}}QY
z#z!fr%^#56;3IZepVV=1AX%BZV%3{`U>n47DY^A9ST@J!21c#-Zcy=;R`eWmudc-r
z>3FD>Bi&jc*buR-;Ss6P!ZiNeR~i@puqS08mQ__U;%#o-%fuYVCLWk6d0?0Bi^0E*
z-(SP&vYkL);0Pvm3w@8TP3@6zi=N@}_q9ZRG~MXp-uEgJ>)-_|b=P?J?^K_b(h-<J
z%qEtYP$c!yWtO=kF6DMj+gCedvLvfPk*5@_o-dt}ZBCRNoJ1zsG!9~lm^~@i)~g;-
zr!r<JsQ-iUF%n0f%2aOaZiAEg#C5s8N>+uOlLx+36wj*jWwJ;rs5tsbu%4m+H?Mb^
z+Xqh)dsS{0;adq%H$k~|!^R%h*^M?|OEXL{Z2H~(=k>vT@L6z;wXxiMhf5qSk-rpo
zdQmO5E+xrfCQn@6!dE(}GG=(9U{<W3?F}KBHv&vpfWAZ#WX-@Wm_yyZP_Ww0jF;*e
z)yvk{+!mR{n@E;n)yhReK9#4B_Y|m*p_N=3$|F&lIWfW@QNRD|x>7<d&yBntgCoXS
zNPO2OTTC|m9Me`z>uuNk&E$txg5{NWGM4edM}GbL>FeP~UHo}@p)W#4*xq4@uiKtH
z(}>G`?);BP9fFK2crPxivPGBFRyF1oFGSJtUIUy%TCNN~ekX-V3f%#J!UG|yX%<PX
z+*dSUy(<#94Gce<o7Xb~UXwey%z8bTF^u8bTB*Ak!ca3(J&!mv6$c~xbMhYCr)z;!
zJRN$$mX%_q)pTM>WHvN&r%XvnsV6sVJcdb$sUvgrL%rpC;83h*?n<0`5kri+)q?6F
z-tCNxSAvQT#BJ=gqi;}Og53S;5b#2iK7nF;@!laO$Y9ssy-KET?s3Os!8PurE?qYx
ziAs)NQF@fzTYP4G?aoMG2vqdf($kUU>5bMOZ)JMLfAq=jYW=zyuyhx^E|KoGA<tA4
zg@kaCfv7|URR-Op92f3~=3U@oz$xU>3@abm#L>2#?=P@bIBmq=-chGWjgzJMVJSeJ
z2IUAOCx00{w52i~)5t#4(s)lqx67&``A!8{XqaSrsF;9)x>7~bw;Wv$D_Foed$;sI
zK9R+LfjMZX$yV1@Gw*HAbUArym9BEZ?i8?KFb=Cl`EIr)+3Vp8_#vz?g|0q#fnu!`
zDZ=Sk^zY}U@#SB;;$X$ep>BjP%j}DAYA-dSg*gf#(`opv_+h*lY^kAQfPVMA%(z#t
z!oE~yzwcEwfD)^FR}eFe3)+3U*L=6Ol2OD_0nv09Cvo-rUk4c?1L5U8>keSBAfsNb
z)J;Uh!Kfqv!KrNfMC<kPE`~7-pC+;4`3EL#lsCl`n$pnc)pqsQa+$@7V0BAO+OEl*
zDY1xJe5y$dHb%;WyAXQ_OklhXj}vfk*i%-;c`zd+R#M|r*`iwi^U)+z*~@8I22`qy
zI4V5*p(wb8NFi{Fa~<gQep(G|eRch;W;oa~a#PV@$3xL6z)^|pS<sz%V2rQDV=A!N
zFzdnRP@u3DN>+S7m^*QTM!~clRG3;4Xs8Q0H^;ReA0u^sy)$8lh`{J>rI`t*;<I-p
z4ND7Zid5$_7X67Z=b!r6)GaMhHjt!$W_{i*MfU9F_v@z^$QNQ)`ZBf<LY)@wn=oBS
zVPkcgx&kLOYG`pP(byjI7^1Z~BnEi`i~1i^UZrEYl6!jMq@a`+4`sHAh+lb;Z6XBP
zoh=~$D4F?g&ZX$HZ7H*t)<q>vZabOf>*myPGlfHR&JrbH;k#0NsT$Kt&E+TLZLTb@
z%WBzo&*(tHg_F*kir*}~n)h$nwAm^dp@nmTGVBju@T)zpwY6)h%rVbuP#%`(?w|kX
z^gEugz@_d<o-0J>{Y|ibBQpEww1BI9DVtd5&z1J@wVJyv(Kh<X-+w6$Jhx|uKKS?x
zm}q$~32mMD%5T#8uGmJmC)c#TAH1Apl6AS*edF^F=eJagOqw-&?+MkP+e~IyfO`=g
z%Ey1~3leHCIr#Q7SGV(|^`E$yp6|N)dMoecoLjHnR;hEYO{~3r?~M~@Z1pB?RqN2X
zj7)n!HTlbLT-w4j;X#Oy&WRaG`=z5-2JP$JaqH;8_v;rN-f>=j=l8i)vz7(bXXe!v
z25y)HEaa{f1&cOr+cHHMbluB?7ezd5>ZQW*!aj}%&wjh)@ISjeA=%bO$}=U1J2-6f
z!nmxY-YOr7FT0NMPTE}j_TGb)v9Fh_MQHQ8a)u>~wwtw1Zrx&0VktB~%EU7?YegCF
zWz{Dw^Ou>$Y&@+kzVz9ZI_aQn;Jz1aU#)hbt~q(@S#BA<c470l>u;yonU(dLW9>Hy
z`wO7Kfx;&<xcq`v+}Qctp`N4L@`A~s*P1t_%fjw_xP016ZQ_HF-OCERHh5fJ;aKFi
z@9@h{5|3)u8~awMf6w|{<-KR3-wqX1ll}K~xu=(`+SYV}ciN9r>x(;gyY}tpe`myc
z&N#;WuMj9c4~tI+wnkR=vc>*b*?48Pk#kc(=XrfbPhP)G8`rrpt#wmY?fY<f?WsS<
z*kW6Ix2^V^=a=QHsyc1fHZ}WOEAm}dE<BWA{b`kdN4B@gZN9S}z^0h*2HonL6FHX!
z=sPZU%s0DO02(%O7wlbpW2H+l@W%QW^UO=Yi9Vp^ySBl$Uo6seTPno&9eC~wL%{PS
zF%#hS5|e|@fBs&5aexgd#$dXLjo0_f?=IK>oK43MK(^^$v7E1eAt-uvXI1=0;1uFq
zy@DzGk3R;FmM!qB+}pVM*@}hAtAHkbX>%yIo_=~M$RLNgLCtLkGXfUr0K0<=>;nq5
zG&Lbw`aF&l>}Gz>boKRPdyC91QHw8zL`7w7zYXrluTahc-tn@~lC7^$D6QL-Q|zLK
z703%KgoX6xoI7Bdd3A?iE^tgLO4Dj4lk0Nek`q7h6)?bl>_aEegkzZW<bcITT40ln
zwbdZU1Y`?otHiu0*>z*e>?t!?)qCA$&zP~|Vn&Rfcqwpp6F38?9H?Y&9-h=HG7Gp}
z$<Sh#r|9AbA{A<D^$ahn3HvQC2F^0Snz;(3biphY7mq0uu7Ji5f^*6)1%tQ9wEd~u
zzj(!o=h_puX92ehZJV(VbW}dWM~|YGyLtM0degcl$F1M4rgF@}{fL!?=D|m^jz2E5
zocoHeT5a;l95dhuMCEhn2t>i1$r~OZW*e`HZ$2tC``_bK;B?cHNur83PlEP&0f9iH
zT0r5(h$Q)$d^Ue4a``F7bxw%uzYpB#&b$(MI4UsO6WT4;hAqDOvWM;G`4uvO?snke
zoCAS<$G}sKR6C?WVrj}Ppna{LE{-8U+JTm*JrEcz`VY(l|NqC@U)}?B2ph;j%nXh$
V2}{D{Yioca44$rjF6*2UngBln29f{(

literal 0
HcmV?d00001

diff --git a/docs/user/guide/providers-models-page.png b/docs/user/guide/providers-models-page.png
new file mode 100644
index 0000000000000000000000000000000000000000..f3ffe6e90f6768c31a6816ff7728488eff70a893
GIT binary patch
literal 75818
zcmdqJWmr^e`#y{TZb3k$q&F(vEjb7R(jAgYH_|YqA|N0j-QA6ZbVzr14Glwg!~AbV
z_w)PyetXw(@P(PR*1gt!<$0dh_{vI)qN5U^A|WB6i@kj#kA#FGfP{2U=byXaKR;PQ
zOpuTsBZ<9vt>_rHIfLwiWk~v9H*>pSSOU#!P|(U}VSAf}L$A?Aw|kriPfrL%x1zeb
z8k<TfPh@6h>xvR{S}-J{R7%1F=J1YRhB2~h+1g?0Y}qMch}Z7?Q7-cG@^Xm2JjH7n
znX&%<{)UEz_V#uGZEXp4b$=t1^|du7u!!G>;{YlenuNHxU(5dfzIAh!tgLJj!)vK;
z)I#K41A5}*(dth+bHrQN*x9AN1@v@F_Vo17)6uc9u|4~Hg)ACk<_UP%L7K0=fq{X(
zzFfQT4@_Y`Y=a*$$*S2Yk0gxmL@0*R`W399%XW;8j!v{p3^sng^XK#iiNInSTIOp*
z6O;ADwjeAlEb4}om;U7)IwLIy<P+q>Yz-kM*23=c7@`B=b#+>vDBIG3fu-w@{@z|o
z7+0sIr3G8JrL}csdD+<5Sgt*N`k6%jr0)BUfC3}CfPeskit4F}3Fg12IL0@(wfT5?
zEiWw%^S0_d#aFhA5$zCB(bv}(78b@`SwSbLK$B|!`}Mgpc^Nu#^5ub4QG9&-$;nA}
zxFQu>OOBccIgTdt9@7@MJ@@3~)>K(pX{p}dvv#2+*b-7w=>PmfMMJZYT2r$A6n(qE
z5l^tv6~$Nm>YRiGJ>0J4&EKy(vdg+0?#?%T{rXSB2PGbU`7C5*Vf4boqeHcF3w<M_
z|5k&PAndEu<c+?ywPiU|r3AJsJw3gkpf_imtB)ElG)7fTO-)g8X>D$9V+se3^Y{9S
zjSUS+Hmkk%_V(CRa(T@;1;x0k#RE7y9B)tZ)qWP0mFfTeDpFr+Mh1A5;C0|Ud-k?N
zUa1<Z6SGJ!m6rcUTG|^4g%aI13@8-(-xdgb;Naj85fS0En5JT27#$px=WPlZ@+wL>
z%*o1XZ|^TM9b<S~`1kTj1cygQJocM!=bs`=S+i1Arro2f?4zTlrKO`QEiPUk|8cKH
z_rGf=sZnXH_a}R%r<1oxp&F<nkX5bQObunGv?fM!$1?14O|&;3|Gl(_f{KdeKnk+H
zD(cTB=+pN~Y_u|k-QAM0oF^ateg{ch5I@4#SIo+4&xVyw&O=EIsw6M3qo+4sV6I+T
zd*hwI5Au|XY^7XfZf<UD0VV!SDESi=W8>_M41){%t^aHO9`bT)!v&f=s7W+^MZ>hv
zq;Fvn_C_#_)SvhMTuFd_V06@Crphi`RrsJCvxusOhKkB)VWhdC!Q-zRAPp0sCJ}I2
zXsD{b4Gx>eU%IdAvX%=yGK-Io`_Iz^=xuCmOMm=Gek;Chq%wF1x94SNRcBZ1#ayxH
zpL-$6iq_QDIx&&Qe&EA;AMTHXgTrny{Z>IC^nZ7HNKc>djZP@f)PhCR;d6~vbb1e%
zP-|;zK|#U)-aAHRMTIO=i>OUxcToaZ&C{77q8`_n|D4E!dv$9|Q(nGN)CP}*&aMMO
zRa^YyM@EwW|8B(f;>8P7Q`6ah{P_a%hrJH{P=TkAkdXX$lR0GL{-jU+|M>f|<|0}f
zQuMk82OG!Rzy5cLnty>=Wn^RsdbGT3Yk10DZ!-S<e;>+jZ*P;6llOi5Buq8L!p{Dq
zsObIQ_khG079Jk{=@Yp6hM0$NbVRD>y}uiRBzq??Fc4dHZ+|HFaYW>hBFf*hlJ0J9
zZFMz2!z_B!RIdKc#KeT<??*^Dz|r(AEUsTR&@eJGQd3(Mi6UPA{Zy6=0|Uc_%0bRU
zczvYgf38H+G&&kVsj?1yiGqTHfPmn?XBW_yeXnn3COIDt1$O0C$@Rb0F@rdYt>s(w
zSnb`r|8sv`W8-(q${AvJaKryI2@gN;&`Hixy1FkOc_9B?4b4{_S|K4JseAYC{du&c
zqUS#b2M3FbS={=VJyask6~Z!ioz0n1%7PkcrT8@Y{(MiCx-%0b1T<9CHIjEYHQq}Z
zrD1yT^>vUk`fFoi2s|fW$EpmqkN@2wMGu;-iHV8I%F0G;baZq%S9t{mBR|2DtlFmB
z{F)jKBkQ*(V2i?5<;i5e88Bg|>VEoE4Byx=H8D2%YfAWvx_uoT$!mU`yvfbtGBQCa
zwDk0fFXzjIp5%K+F|{-|r&UzEf<O{O=sHW*-Y38GZ&Q5~CN3%}s-RA|N__j!-$j)6
zHa9mx?4bcBM~IIvM;vm;<32sJuI^%Eqae4IpPyfGaWU0FI(67Fi|kWwWMh*LHGh`y
zT~<pgAtFKq$C{!bQ9+4l07qciwiy)_m8zA7fk9eErmwG$la*CyOf5YLE11AsR#Q{+
z&kOrkx=>zTJ_|)!{{=G&l2R~zYx9<OcTW#9jdG71OO~>{{PT%VShs7`QU_)brX|N0
zoHGr!*vJuCme0$}3l4|d3K*N1sHv*{>zGY88DfH6z<PUz<CYu_GZ$B7X{n;Rdh8&r
zV&xr^&lu#LMc`@HWWn<Y^5hW+{@r-Q5z+A27$-ZsK2p*n7bZGXFOaI4NR*}iMf@=?
zId*W79D^6NcV(Zmva)jL-CXCfuI#;kivBFo0qiC+GO|k%2?~;UOIyPN9+jS~=6@fX
z)@bDy6a+FzBb9x^pyjSud%P&d>}m4)&k}aeX=rJ?+S}hR1WG?EBTkAiGBFt>6G7&l
zX2Nwk`nTaWx;nZpudK*>>%V`Wl$zRvlr-8;mQh$J<D)Jujp3Oi<dN<I;`6Pe2rNIe
zGX|!Nf>hSs-u~5BL6@yD$2*d`frg%5N=7D=l}<rvZ|@;7&l!~McpdVd>AdXsJv{tU
z5B+EcQBY9Uc>j@ouqKe&gdR|ovr7I?(eV}!lim3@6cQ=A{4I?c-nF{m%#*x{oj5L=
zi0r7cjnM}_Uu5SyM@*ehwhV9I3Jo12V^H!LjsWq3kGh2gL#|M@{no>O9_c9AUY(;u
zpDW<UNZwQvy-pW1_a0!1NvCD8kdawU9TVHe?zJ8!x?LtlMBpl*a64SU(C73EDL^e1
zptoA-j(BaNMt~zJ`7PEFD$ZwOd<MfY%%`Kr|9xAJ92z>hwDoWhmWyMw^$qm-+%8{H
zGk0`OPIhz*3^#xI)VQ#S#bG(IzT?ix!*k(7T9?XgY;WJ2H({yZb+Usa0oT=G%xp+X
zl7YmpZcH7O$UqDjKW}=c`@-B#YGG3K5I4j~Qz}`a`FslbFEX;7x`UrGB^h}f1M?z@
z2CrYgmXizq`I95p6^~Iff$PHjg;3Mh6i2!Fl*lhbIVii!(la#~LiO0*cy1P)q^dj0
zZ{9SY`YH$t?TASa4-Iwo_2FG>T<s8WKN~H)8XFz;9#PfPQ$*bHbUIrL_5|fpc>Jml
zsr$+&wK0bHlbtF0qqS43#m}BX(((MPI;TY>d{uwkK&i!tPfnc0dVV3jK7xVAX}@&o
zO%7HqtD$naMctzWAHfK>dnlqJA}j+;V&2)=DF#@Ey$O6SOH?=%QbdS-WhPFuahD?k
zFEUP;lk?9{pYG(UTXUMJsZB1lxXXXoI3|X<U6CgqG<x~3_G&-l(s49@pepIokMngz
z$|F5LUAQnRI9lw}aDwI(PDha=G(0v|f;9SP$mFAuI6r$bI(m9yW|O?{T1Q($7wz-+
zg6A<8bW^vz?r+al=IeLiUXo4bu^RS#$obXZ|Gs0v>({4i82zb;lvKcND$AnLM^>%B
zK5m;MYoe|l92!ck+WY>?b4^QI8*vC{Z4&u*J>QndtaW5#4y*GN#I<BBv@w(s7WH!2
z8jPl}-<oV0D>p6F;+rhDY*U<#W;G<_*iVtsFgZW9(v4w1a@(0H-{7y+!7)>{u{nsg
z?AhHj<}g|Mc>H|Vv!EBHH)Ao_ns)LU`>h<EFtzydfkcK1DvFk!kg)oD;#VK3czHiZ
zLe5T`&a_<^c=b$8g*dstt=1vtGkVmGJI~PYET=0bGNerZghNzN05Z_ikAOI=QYcsA
zy-cfoeLBRb7{zV3Kc?;WdH^XgAvk!iDX9Lk<QxWb(|$WLcd}a7m89ds7HhTG`j!L1
z%+5SfZb<1YhK-8@QpZRroOq<BvhU0$a{}$TLsN*h+jVg5E8G5oWYM<wVq(4-2Aa(*
zyiE%~6qmP(6gg^jXr}INWF(R@8W|aNNAoGzqr_Z~L>_pp*sBz1<QvI>5<kpKv&NR|
z)ytQ(w6WQb&T*cz9g+}ByG%E)cJ}qvyCZ(hcnEYzhoSoU`qo0Xpw`wbxAF7w1J%6N
zp2Fv;Dc2{pRR63^WuBx!+^_~|bxcgoHy9xpBy8V1Ay=2V{Q`HEQr3L7`3N}PCn?fY
zf3UN)je1r1-cC5!UNt99i#go<Q~39&b~KFRV~`1~SAYEYF<WhD2!(Qo$H&L(89JWs
z4h-sdmG6v`PcZe3m2XUy7#^*U2w6+REckY2++~%ODJ1b(Z0{q;8fRy>M|(_tFi4~K
zR_G{xIBQloc8qR!_%mo7UW_xR*oUYTXc1nQ{?hw6M~voAsaxe<J?HLTc<F;mug(T>
zF@gvi*I%EvrFW@-<bC$2CkD!>cIxbp+p}CZ6w7&q%b;d`IBs>F855(Ht4!~Hy>}5o
zuWmM7x*RGa+%p7%*N%_4w!+->8Jd6OCC=l=Q4}PO399ejv74`7&3rD@7fpI_6VE)x
zM2(H9XU2B@R5!*fQ($9+Y#+7Dti3k>rD4-=*{>(zb#dI8y#fIku~Th%W}7pYckPfL
zBvUd`GP{3LFJYJNe6kH+hnJa5=p5%oD<X%wlBqR9a>wo?Kgi9^w%eLakF`|E!4eDP
zOAL-an=sT~BV1DmTv>J4X!s>`h*eh*7#OJ%iaG1vH#r$Yom5oxacrB<2ZPwx*SG9P
znep~eo=P8y^~L!cJ~x-^%NBn;MlUa)a`T}oh0H)(R%VWfIK!cpe72^jffrNdmgU9=
z5nU<;-acMq4!ID=xrX^BAJh`ptDeuGUU`5?DtFdbAF(w~O<;0XjSQ3ZiZm&<fg!%m
zuI%f(i!(&$qyuZ@b6ufRlG3>8c5bl%n*97c=*c#hUFT9m(i{%0G8D>@a52l{@^g_=
zdV8Xz(AfdToGL2DA3san5?Ja2#mSag%IAcQS6CfXqTv~NGG3VaGTHWBU10vSm?C*f
z5EJ!%JWK9Hj-qtjD=o+RJD*;6MdW|=_s6n~UW+c7&G@`q<#6wABqO5QYEeW!f7i%#
z$nZ_<*Pq`iqu;H9!0xc!E~<+6cAMtnnDmvy_GLWJ_2Gc6(U?VV+`Dkhf0a7C^%v&z
zNg;vPhoM2!)9WSTd=9W&61O$6jK_9K`}V3d30hCsM>Yc_f1r8s*SM^X+Nr3hC<|kA
z)t-%R`Vr99o@`IS+z!I~m4CXnG03O3pb-&mdfwgMgnaziIn1ew9C2NyxA4VEG3kZn
zToR>WiYTTaU82_4kJpjfjOy2%I7XtdA`7X$S=Ysdg>+m&+7dH(h?Q>JTPf}O4?_<~
z-RK<3Gsfttshtp>L0OWkfm!XMjY5Y%u77;A60Yr`-nhDUht+YVHagt@opcL-e*5;V
zriM4CWLWPR95;W`+eg&pYUC0V5~V)C8%8V}Hn*_3>Ap&lSZq3$fN$AD&|k0JM=}FB
zUBjXXta9vWnV!DfjK=Df?qidEWwWxG#k}aWKoP}eb*b&nfO{>O^uA>%Hb;1>+?<5P
z?4{QW#ioT3Dg}k17e2=d#Z5Fy8XCOT!{Y~d4B`ctICW<x*B3kWlw7MFp_y%giS1*e
zQK7SQzKcHOp)5Js`Ret17YO<a=+Wf-3sJ8lG6f15jbg{-C5|vP{CYx_nVFg55*woU
z4F%<pm`m-eU@eE~FJhF^aUpT_x<1E>^|9QpA|Qo2JM7G1;W1txOzqSqo{c`r-nI^F
zv0b0ecXJ(^avM9tp2te23!zzbc~0+x*-*cpIHK)Z>%oz|bdfG#G8SmgYo3;7);<1E
z-tx8MOln(T5Fw<a+%(eF+2LW3JPN1I(lgY;mysRKcd$lAy(Yfkq(0v5Dy$3EaKn=6
zQ=kl5hr@rMDi(jp?jI?CKyKO=NMv?$xNa`w6Ts_m-8f25cyYA#qPwuYPKB?OPeDO}
znuaC&z~8PDJx3986Yjla_fb7SnsnNoBg;kY)Tfk6XdR;EmXbA-Y!iU-*9LrhboR&=
z<Lam!^5v}B9?ttwz@0yia4gxCCq}S5VZoGdxTI{^9W|1tw5VuKVQpn?EomJ3BWx*b
zK(|!^Dl9|F;`o@@$KL+vRLGVg7O~8ESp8|~GE+J};o{n-(KzthIJv3Lu#e=D>S}FK
z2Ea1pCthyX%jG-nr@o2EYqkBB#Iy)44%c%<66C?;{f^87Dhu7;=C-T0V7DLh$Rj*D
zyyf0qklDozOxNk5Y%Db5Yj}+_dnbsc5~rOSzKhGsAuHzKY6pu{0{kA<4~^Iza>{~&
zf|-)ep6hRJ$`@pY!;-6vfDPb2oEDRfj4vsvDLEZBD|{1O&zZgS#U3)R_Qs{zrDkm(
zI32u8&st|&-8!MFP0=uznH-UO5@exKE&0K(u8v<{z-3o|8&t`q{G~^0N(`F3grtOJ
zmVLdmwa$ZtX;oU%(gnjIcnoS!agI(KuK5m0UNmmIU-YO*PD|dD%`V>lt9@@oy$<ZP
z2uBN(S!Sp-bBvT$UH5R(Rg{&LX(JGJ5Vp1Xt2rgw$e~>KlPk<T0|w2i%acxbT$hWZ
zi6P3n_bkdyM*JuSMK8~47^yAKk0MEpb<Av=f9A(#1>zGxcZ94?-$HG7L^f&+j%a9{
z*^L`vpZjYhaLu=(OJEs?e#Zd;grg!NylH(KK`{4ZD1&}HkHc0(OybXxoq9%%iyg>(
z(DndIW@c1$G_uc^%Q9Oha?8vdLS^Of<Jz1Bp9DoVWlp_|r*+tH9EAynFFmmrY$i)q
zJF~7dpv?Ta(O)UCDlO!Lv3Im3_{)B|FFoLTb{f;kURPJwb>Z|0S$(FYYj=fjShD=t
z2?ST}%bQF}8pLJjnrvomiBM*NOK)La3?qKZfV7M=4Gx7&wA<Vq83i{T-&q(<@(}6_
zqE-hUHIV9vrrsICe`Q7zUmta<mas8u{&-SpP>9s^GJ017HF-9QKU_NLGP(BRxG&*=
zftahfP_V6`c$wDG2?WeA^n<Y!JbEgswUKJ~_usQh=Ic#I?bpXY{VqBiHZoW4D9h_S
zWps2_!F})K#0STYh>Cj2^%nQ40Ajbkw1X)3Kun~Ho{Z+JU)b;9V-wYwoxu`aF3A%4
zoqKsECb%Fjh?yxHgFWhd4-N}=)+cji-2Eb21BrEMnN42RW=FHauwy*WPT5jFW`f9$
z$DjpjtHQLh-d{pK)SNd(UX_!lzdxE3GY5ysc+sce<oO4ruEo~NkeWX9=!0J8u)<oz
zwetZ#B1{InW^tVBSyz-(7`p2Is&+`^zq$+au_v3ez3K)4oshTN=_N*7J-|qKWmW8X
zI{Eo>(j{hr!5HQITrd}{avSDe1Y#BdMhV9XpTuAUkg$i){B*rQ*I6+8s)R=#f?X;%
zqHe8YE7|S5QzykW_w`BBX;_^rRQ;XW@!H5q=SXhpFE~0tg9c4D;2XZMLg=#Pr~WBe
zwL`s^S4%_>AvLDX0*SDtWTJtN8Ovh+JIi|3NPe9TOj<s^tGQ3L@jP}*?id8G{v{)u
z50zOZhFI+n$?)f_Ddm)YSk4)&Q&D1MYS8IBCMROC{Ss5fP5duNn>RILdVap^M+8Y{
z(P<*KQv#3s{1qnuzVYm2ZSrcfm;$wnFZ5D%+va3*2JwnJ2DP-!5?1xD_=uW#bz?N|
zc-QFda!5!>*#<`ux9G&yICHAk_52N<nYgD_Avs;E9Cgq=VbkcG=6N>bu(EsT2l2;!
z9=DO+Pc8D#bz2ZA<pf@QZxkVC!PQlHB79}4jP`dG>@oIqXH_l~$-g`+Mci_E#8E;*
zf?riW#_>|;PVFIZH%cxqmef877W;ao>jg%lVA+O8!@p2pP{xJC4Goq2upDEMv<;}N
zmS^O&ZvNN-p`Mu6#S(q<rr2+$hPvw8_~rzw6O=rP!@P4Z)yM7Xh%yH<n22pC`{hkp
zPT@*lXk5U0!ojM)HEq3md3wZjrHyFzlL{kLta39QC5MflMrXCqV<XCe+0VX&zXAx@
zKaYI#FDX%kwlvR#*Ilj9lGQG#{WN=Rr#eXxZaLyN{nRp@tHf~sP@Ktn>0_dSl)s<f
z-Fu1nuxO5??^;&zJienP%7u?)16&Kmwah$P5)4$UxVg`ey?AGp_745B&Cuv5NG#%5
z^4{6Z^0}UWTRIF23ls7Q>JRWu)#i@)66ZfvZ3$sKT$>Ge>X6+s$Ypg|@dM^U%PmLp
z%5gU`(fvEIX_0aOKC7Au>K2tIx5LWT%cd9CJa;kuVJ{NrR}<?ZHL+V7V$03YA3h9^
zvCuV_dh!a=lmK!6w0eG*o3_VMm;2AYXgN7KmC?Qdc&VgDpNy0g4#RtLT7bc_(n|0m
zSaq+43wLNP1sUgFC?VfR*@sZSPGV1s{Jy1(OGG4i;;?<HkS`ncR*90oG5DpQni0A&
zS)L9rOXyUXWU;tA=f57KZK)sbO)%G-#avuS_z+0xpR4Ti(q;}GWjpd+!Ry|YWE5kv
zpX|MBGZ}u9y8oe(g@yIr-Mb13^6;T<0K#LJ*XL?o3nr=wGp+*2%bjyB5TV)e<3JyR
zH+%nOx!RQMYo(bJEqRmmb=$jCjE2j0JaH~ZSr#5G&G@6+@l!_i6V(ogY=umxHcl~6
z3stx+QncJe=6|rf{9kwS<wRGUkTSk}`EoD_B|Od~yg-Xjy{bdn;iDsqUxZ%yN4LuR
z6#PZBRj=N5;r8g?qvJMJuwGrIBp}&{)OOEIHJz?t4hvRF?Roh-G1r8gMlGaGjwxWB
z2j53QKH#9XM&>n_(mgN}O7li1Xz%T&1c*7n^9TtEk@=;HPrbJE#5BK2s7pw21SzOE
zyV0_eh&i&EWwo236Lh|_5q<DLQ*-9<@UWu7@k5$!N@^}`Ek8T_XY@<IfV>1P2FZ}J
zGMwCKzm#s^GcJflnIICc4t~X2693l=J*vMj=6c^uaj9CTfF@?x%w)Z6HaaioLQ83+
z=Aj<?o>iga6s>q6Dk_?Op+uI6B6q_=4AgmGE4FZTh<fulo@cB;6XLe;GRQ2tf^%~&
zxe1e$yTJ#gJDKRh81<ql2r`tv@1<a-5qT$~wzhT}etvGvt&67F8Ow2GfRmIYzRjeH
zhB!5E?|%Yc;HawkML_&4Y}#(E-)-sZe7;)QE$6jMu*kj|b6*vhU)bcEw&wdv1n>8@
z--p59j?_F24bd}{78lQO781I5y}@Id_r~2qqh8rW+E03oUR9MQlVf#l4WKOegm|kf
z%Jm@=jyCs`GbpH8X>*g31SBN728(fNqZB!LKkmxPzWur>BtNrFBbPpGyqq(V=z5K;
zZ&T}hvN=#&9U7Vn`nhahu}p@U&YUR&AA9d_-yTig(JSYG(E@;Y++TU>f&>N~;XgNd
zYcgyf(}+;qd$a*?!TZ<^L&m`tiSEZ@vLAOZNL{)K@%0T?Hz&(tAE+9`jg{0ghLsRn
z_@(R^#M2jBpAqr=t`VfqY-J#>{aZWX2;g1kM=A$C82H`4EoiQ+*|ZlBD>z5Tvdu}a
z??n`<R@$r<a2iUE1shW|HAg0<h(;S7ZrqVaciEn)W}NyIe8RZ5zrQf#q(W%JdSEf*
z^3L33ppo*sb;aD{iPuR9(fLj`1LB>gP#YQEA7WTC=H}+grZN5xIx219)&Q$pLX)%G
z87|S?c`UU@N$dRK4M_ual+IPP2sZ5UatKo)Q!>Pb>xGa|=Vs0rqEy(1^gPLT_#@}0
zaS25SgEFJI`HnMty`NxNN9{@yQ${t7p(+jc*9#jbcH?5hF$_vk(d*2Q59Luky_`@m
z2`U`tcZ$n}-7k+XEFlNhu46PBZ%P8+LCk{*A3s(d;4Rk7Lzd#@bFhFBJheUX*{R=v
z6&5b_5zo&*8Oo@y{IF<n3mFxXCnMwLexeSg1Q7Tv`ahSusWQvGyT5!AL9$PBdbx-h
znA3TQx)Wl*`7~W~R;De$+TNOlmDQPun4Tx0yU8aAKz(@l_#I)%l|fYb<8``}$U-4Q
zJ23bDbkmbhp5FTvzkdCi9UNo<6fVFh<R!){O)+z?meQ3rlsPy?F-drDZuv5^53#>N
z$Y~+o)9w6*-{tVFNtLXtTfya}3zVMb5I!SeU6lx<=P!uX(`6trAkR$Wb@<^zyERcF
zWAYFEIh&;)VK!SNes|UO$Z_3CO4Z{|slxFg<{9JXeMMiAqZR#VP*iOnh4CtNn6<Ww
z+(S8B)F)eDX66`moouTR_FqxRl#ZyCQd}kO{EG#|a_F}b4mnj)MAqh+*PJk7AyDNs
zH0T^i_`S8s*U;<u3`arb(MaO0RcE{Hd9u2{B}C{ni>Iwz=k>e9n^S5r?Zr`I!(N&n
z*!4Vtr8ch6tGk1)1kfS#WHgAwgF^M67ODHwC$qskIww3kz35Qx$tNSS*IH+N1)9!T
zjVx9Rjvo?0avZ!`V_tlbn)1aLJLzzJ#&Z1Y0341liI0LwvIe-J9ru%=zLkggpt?UM
zWHms!k0NLG()MU!Luja}vC%8ja<b+K#%_9abd)I>({6&L<XCP#k(QY$S~y<%uImJ}
z&R3X_W8+!q2n5mVV(LBI?LtR@`m;BVi&nD6_N;RshZe_~ePFj!ODab8!%@BI7hhmS
zmK}t+Ia+)J?b?9K#eSz;H~#4!iY&I{S?7pl-Ia7!sDYlIWE`7RSi&Px8oQZRymaLg
zKDV_ID?CB6S{8QZU~_}?bNmPzd$Mm|znTrKcd)-6%hM9BwiLEOoiB)v&Sn~D%bX}P
z9edYPU~)F?Pd)r=gy8`Ok$@pNMPMx?meYNHr(V3L$acc-y;FQ5?O^jzNyk_Mwz2E+
z8J^^&f7?v;9eVYj?{E9On0exUKq$R*{-M~kn&=u55>sWr1w}2o)+{N|oC5qg2MAkZ
z1+cf$xadag=96JgiCxBtBbg3`A%la`@zsFE{rb76E3$C^Eb_XtBD$HX0Tko&Kr#Wk
zJwfJx@<^3b5t1jt!7fbELHsV-@8}Z%3+1pgJzC;WZ@0m@Jz1M+8p)7tY<x(AUD)qm
z$7&eC1mO4XfI#2mlc{1m9#jVcHrsmZWfL8pr{qs=3droM457n_vBIm96EA<GBO~+Z
z3e9ovBh%8dQk4QV`iacG)>i0xm>64M`@mwAE!<3{P)pVERr*uVu*R;3pw>;78izv8
zPfH-U472430iWY75`NTbn>P3HeljmFWI)`6*g)CL-W#d}-K7J-W_ApheRme8VGWr>
zbg2$#c6Wvxkn&r-17fRew<W9ldt%)byS9gaH2LYfGmpsTUXTz&ZM8!&YLv*MwTNF8
zl^Y|EO)D<feaU(Dexz_mJQLH6uMXgvirDW#Bq!p7#zn%vP)d?=>oH*#oqD0w>KCYq
zC*K%*^jcWHu%Y_=KV!p}mZts8VxobY{w7BJ9isQ{d9JPHj8v35b82&2!EiVk)JqKF
zLp_@aEhSfV@#WLXocrnu>#mizu^6?gTvXzmKt&*v!1j85fZr9mhvctUmm+k_^8-@R
z);5dgO*lcP(aT&xC1JZ15I;o*TD9Hj(f)bF?YLI7`*`F#%=KhT?uBT(>+{+*NbdFZ
zUS=Zo@xlwzcj~}>;cYKOF(PAZ1{z@iD3(d&Uv${u*y$6F9-}06RTWeBF-d~1&GPX8
zM0W~+NF@B$VZPNRhk%)ABfZWnEM(+b-KoFcT$>Zvuo>D>mi@>yqV)ii;FZO66zK1Z
zxnDEBDgV|jSs&{bp{$$`KqyD#blEIMVMG4Q%l$GVIoWA$E*Z#3SmnAfOT6k4lNsiw
z;(^#iwd(=!p+}D%xt-3h0${ajz=G9zR9(CKB2Q`KSe`L6H@DjAYSQVTzRLBYH($M6
zU1?JB^K*&G$=vI+lZA8%fL<pr%PyDOtV)x*UnWog8rBL^n><-dN)?jP)U55D&3g{V
z$?U|BP&;C9em8Y}autNVw{IQU8^4xi<KPe)_em$7)1Zc2quu7J%H8J?Npn}2OPR$K
zGdp{@Z{I7*K+-4PojNIK_9!xOufofbh&b)L{gx44)nTY3B@Qe4=U;wW&ghw#(3I)G
z7*1ge<T43@XXpLNecwFY;QQg9JQFtCf=Iro^4C_tFB$8#eqLJAl$wm}5BsJ{wp!LR
zF5yY0mBSqtbC}|vZ*B8Aqy6HDUzqx7EQP-{Vmby0b@)qR;~9*-sIL^Qt#ZLK=Nv;1
z9oqXT5pP`(^~hm`5_O|vFuK!&LVd|gMya>`n)8$8w}C@V4A7k7kFPe(fe0w<)7`+V
ztgPm=m!`C|czBUOR8{^T3<+D2+K8@T#Nm@uk%^Q~?u`9sX?a=rjR-dv_a5xXRLnqG
z8G!ZS>B}}e#RH@M0XUi!MNr*nm7vY`lW7oR>!T1OAQ`;d-5M(n@<TC`S4hpVDtn+Q
z4i1^Vk9KxW+f+xO;*E}u23iKxI$Wi`>~(Xsk_eA7smcog3rQ<0<07XPM+=$D^45m9
z`VGszV~p_A^4h(s+#!azg*f=secY432-E};6#@>Uxy?;%Vq&bPPoH8FJwFUT+M3kw
zZ@ANFLyfpzJkidO#<D|_e*5;&c(%&PCh>-392j{nC=<`!^gtrj77obF5EnT<K0fZF
z-GuH#<4VrM&GF<~PtT^}bcrucjt|~jtRLb_!(I*g)iS%9oNUji(r2mk*-wr3T%BX4
zq<Z=4PIjpzG^^Y8s@1GH(Ci{f$O9gdy06Y1aR;kS37~u1K#H{7EGHKfM9ky1H@Hl>
z0nuj}q`lb}kFkh?0tR8G!=Z}eyL34+O4w>jpWTuzhuejMxw0E!%|oFhELgg_SS?y!
zIp5{!=}iE+T@YC=BVw=u$yI*KVV-Jh?B%GJ3rNl`*XPT=c?Nkc*wLZZw1Ae+V8Syr
z%-9dB-r2kMY&@MQ%g?Ha(vkz+rdVlH3MKA{SsE|7`~Z@_U=Kh~-S{o}cZMW_FSn)~
z)+l%kGXse^%rzLpH!+A=PW#CH`Oi-kpwC;B$}MIxVwWC;X>CnaD;z(&-t$2O;9sQm
z5vL2UGHTd<EQ*Z#FkVDPt6cCj;uydQ7FXv-`ehmK6m}FS0~yY2-~hOB`X($Y-4?i2
ze{E7%9*IYaB{%AAXF40hbzvd!Z|#-MD&t$t7oLrUGLW;c7Pkz(mP*aF<Q-*n=O=>k
z%xr8?>>K%s?q^$D4l6f&hEi_C`nn0FOhTR8q5;tE{iZQZy9CMx=35!DWeu+$@Hnhj
zSho~=lc3{B7QRaO&_elg_gElDz)nWqmPNB>EhvzfhwgOyA}UIC0-u2GW8%eZHCAg-
z_>`OVe%iyH7<SDn+q3I?56BC@h!2e9MO*g9oZ%9m75A+VRgZnTa>ixQ*aY3}3n5#n
zJ5m9L9Kqh+t=pPY)KjxR%|*>Lh%AvavfowXVeB57)$H%+(@qqF{yrsT0cf+l$~Dx^
zmvYKY`a~RooKGg6_jtq7eRInFUtV6pXVwXyKUx-2B)aSeuWx?7b!I`?vd`L9K<m~u
zJstO}Ywn<r|3_Kb)qZYa5DAYoC%>G8glX?)G+NzN)g<5j<lf!nEO>uzS3+j7P#3je
zy2wXE8XlC0u(|Kwc^tMgUQ!ww=*LD!tEsD(S&WGP`k8IZ4I~2G3=F;F<53AIr%qfz
zsRV>GPZRy5@07xU0Eo&cl`p9FUzp3qOb8^B#j4$IdC;lyK-TSKZoX+LO%D?jlc)NR
zvQHo{FOQCz+IJfsdA%BFo<^q_kfJ>yB_*{{ftbntl9P)`>NQjEu5BCt#<Ea^gv8E?
zk0<MAV`Jm+up%nHnVH!-O9Pa>hUm`dhOhJn7NrzDmb*Y$G0@LFXBPs&Xsm$m)Z;K!
zB=FQQJVizDR=qTL>Npst^$;)lu7_GkT%3l6MqV>5WsP!wjjUaCZ0u0bQ_#z1P63Gn
zDHrtHQ`&hsMD-orR_Qr7PBdUHZhHz@Va4Fl{(d05?Cj~$N0K$Aq645X24|Yeh$pTp
z&DM%k{q;Q`Y>97YJKNhLkZ*59McZ0iA7Viq-M2Zl`~Ijtl-jD<nE?}THyZqSu1pZ$
zN?aVZNlqDPWfV2vzFmuRm_0bDr#+Da6+$26VhLbqx2jr?b#T|7?rudDmGYlITLtEj
zI+fJaV!*>FD;wzO?B9Jb;5I?l0DahBSLfQ+>*3J==t4f1-J*)LafviB1;#?@c<z1(
z)2;s`8L+Uh0BtVQGhC0sy=0&WJpx;RuZVY-?zc@LJr)xaqo$z|WG58x1>%8&gM%mN
zV?;6Dw^|#IuRxpS?Jc6Er3JFvBsbFVW8ycqRB}*Z9~@$hM<yurf0RFSzCaw7V~vN0
zXZl-;B-;{uM_?p8EG#WOeV`V|SBS-*sTHg|et#=kXkc~Bq|C7f)(5{)6KDC|h^)R+
zVT=O#g6G#yEPu5=NXA@TT<_k!Q|t%IBo-Dy1v(_*u!xAkPeNym;Xs-TL}U0=5C1;P
z_f(+tVr4DK%KF*~v^&_k$%NPf!kwL+#U&*+Ha6LL`T6ELIw|StEdow|S0doGe{hhk
zrX?>gs1I~mAR|<%C@AP6{Y#Qvo0Q~%fmM|WVP|It_kutBkYx5($~4Di-3%^#n#kLc
zQdKpnU=)X3c#r#jXJU$?N_+l4#CL)65G>)5$%DU(bL7wA#l^*yw~OBfkS9J86DWt0
zQ&WY48D>)Tb@Km{VJRtSXmso5{U5Czw%VREYCcoHQv6?`6xcc%^xCl7cZq}~kWThT
z8wEZH_eMgy-C86hMS{O~M?#V{{=4@7zn>680T9jb@(+tEpdpw2H8thDqRy(?lc!!k
z(AO7)DisT@KQfSt{NwCXz!DlvX_%Seh3Q?66aD?WAgs#m`d(lX)i@0WMLHj^ZEsA4
zkJN$g$qe=*6xH=2ZIrhGq=o&PHkavNzI%6Yf4}f7{`;y(yD{Pt66#fEUb}`T7Io&6
zrEc3L;6IQ=P6$8$Cxo$%jy&g|?>B5b(gptT6)a3Hcp{J(LYAg-yK}OfH|F_ubE2B@
z1?xd&31Dh(i5Db+nHxj-S6)`ONQk#xkvv6L2e^CF?P*CCH+JBtvsJZP8f8YL@D~dx
zm@N9B;N--mpbD(=y=;GrL?kJ{OITuJ;c3a`4hk<6TUkx5Glz<u{Rj{txnl(iqsjr9
z5<rYs?T+}A2+Ie-=k{&w3VwL(faExnotvwmD&*DQ?+jGic}7$Yot_*PligiM>l4Z>
zPjP!How|Oqn~t4bz;Gx`i~vkEWw_GK36inu0M^MCPtnJL1%T>bX9foL0<BWr*|~(X
zGmkR$wV!*T2F}x`G?IWyjpEiHjGJK1ZphIAFdZP^fJXL-ASa&TD#+QO?zIF#@>a<z
z5HEyA2UaELQ3eP-t%9^CqdyiYL1mcDWZORX(|k&iO&tn7{~D}28+-9d4`BKDL&;5|
zDCi`|^*ioMPSI%~LdrlcbU?``2o(kjR)@{$kt*{C9U!U|7mEhq%M?;YYcX4y=7C=H
zcxzO`1iI`W!>fO8nCL#g>L5|vp{l1i3;+@y+jS^>ALoy0t={Zn(WiSC2L|Fm4p<1@
z(}&aJYy}FXQX=teDhY0f>$?aAA)!>E3;UrADPzE6F=2X%-$;Ol0ik|oGXlx=g4o&F
zIUlZVZ!HTi*VNPiCLhS4J6wgu>skX69ap;FU1z4JFJ}e6FsNfsm3x87PtHwY(EoiN
z+khFlKLvw`x4Ek{4)j`80C9UE@@Nsg5Xk;o17p9($Nw>#b=;dMk&&Oz_u*2Nf~3>+
z!k$a060NDcx(c8Slj$kTfZ?nJ@Rb$`x86s`@v9d;m~`ih<%DAluu8j`j)7oE>BoVm
zAd@zh=;$uGUAR7B%+1X$RIB7=x%>sNcLuFjSOi2&7MoG+Sy}#(3|+1*?qhkiF3U8G
z?z`91J|~`tcV!EJ%&4(nUZ|_BW@8t=YNoC|H=A`i<}J5`J;5z=nMf>+gAakSn)?jq
zuAIPaHQe9tk+Hh8v^`z<M>IZ65Bv}5xdH{mScSZ_H00$Y7{C7h8xXxKC8%g=)%Q-s
zwJiD@T;bXhlHUTnM5)iz>bJG&>FFsfvdRE+*eEphbEmzlYjN4K?%Mh=E4Zqv>aq`1
zYLRr;si4%f)(%!S-V3RBbUNKl)^<PgTB<s;-zwe>f;l?%CAd;kQ|HN(C7(EcTBrdH
z_*?#^6=io&`P3thS!aldi2m5>tpf|<OM&h)%8}{>sF~jKgQZIE4K+Vpq)}@O&mDV;
z73z4_wu5Mkr4uumoi>~trmk^WY9B~RNugX$ZF5Y{E+4xA-k`WGVzerBy8EYRGeB*&
zybN?Ew6S?oF|UC7FVVNDOvop&NSuq8m?lAabFxI;qttTD9>9X|(P{^oKSo-9W2C%f
zX%h0k_Z*XG90ru$DVeZ3S5YcwXXlQ1(Wr#za2#CR-mW`$KGpQ62-{TlrF`reZhm85
z^_UeTaJK#3@A03W)64X=)(~M6HPVdaDA9t{tVP0QvYDCaYPB_aw6LJ_CxoQj2B`)Q
zH{Qg_a)if{?Do^9a+!i9IKZ%K1U`i3=LbwX5peE*j{%x(vX>^)6;{G%c-B;vg{rEm
zM#kobCKmM0SglK-vD67?VPiYp=o7BN$D{uU+yw}Ymew{o-p_pp>cD6CI4!r4QS0%I
zX~?|ASgtdl!r+&CR#)rhsxsSF^xW7OUISW5#R1+B%=Apdepe9@ZzkYjl_`{9`<3_o
z{Jy&+`+Xzjv<JvQEc+2|Mt??y%knxV<a%?chJE=R8Cmk5QmfY($n70XI+w&Gt~ENF
z^9u}mTtdZw5duAypSR^IV6mL$t!yQQ4|v^(=-KOi-@qCGQL1v-Oyz{0Bq@1K_|k2!
z5w^_#qasaJLV?Y?#+*+*!{e7H${_u#mwG_m28!2uy9;SIH-7i8*F;Q4Yd}-_zv&da
ze?Vesa9<yD08V=V#FaZU)iO>}8>9JO=BJz%^Tfx;dEp#U2?+^dVS47~^gJ?awHJcX
zeeX?l1kqM&|M8@?fW15+o5ulAE9j}R3JOX^$^Zxt7x4l_Fh~o9up%o^c1vE4)*<#*
zXL!nQ1@Io+Ul_h1A@x1>w$?6pOJ#DonEQ1PXvb;XQ-WkzlZmjg=^PT0lK$0VVqvkh
z$?fZEY~Q|ixLoF^Wnl>kNfp;(W@Ox%ZxYSJ1$uA$?P05<ocagoL=Bl5^=|R<^ndKs
z=eL~-SyP>8yPXBd<hh*M7bvu0G_s?vx*wr?iOaLzzmM{8jB|6Wyf82jgYjf%ED{f7
zx69gn(riOHH8$toYDp5mh%c(<0}GJl-janKCA7MWPZp7d8v5arKtDF9PrGIh0_ue5
z#UZ>0t+LXof{pCA{R}hTm``8-;9$(F4@6i&+S0*TIMXvTR5Z|SEOs_F5PCf$g@kr$
z5x?3(@Rc<*F2k}du|cu-4wRHpq2KUXZw3=0>o3=1J$*3Hq~bs?#eZft3&5Sk3qNeg
z)y@SeIVn92&H1)Fr2Ar_OV~e>PHR7N=Ag9!WTQ-#%&90VETEO8K9hBGyB^J#sX~W3
zvSE+j79L3!?;n8(ZhWKPs##*3ml2N9wj!-T%q9!@?4aD2cWUd^1m(=;_z$5)5t2v-
z%@wRl2Uzq_u|C?ojOYU&fcPRVNZoW6j+H|xWLP;k)+f^?bmT)o<_Bfyg9pwrq88tT
z3mtdo<^`<!ns4yfA}gCrY2p}1D5xm3s%**k;r%-Rw^iS^dqgf3%dHP2;efmXe)K{l
z06v?q?t`%f_$Crw#|r(8V=$%0Ked|Z)_CijxB167?C8{f%X<3~`DO$oh?G<07bVb4
zY)@92?}x#8&48Mn*JdS8F{lPm3T{^;F4>fBr@yAhD=GlUegG*cF2*F`?(PCk3uGEs
z&dU(%dq7&9KU4ivDvmdxJX%~@dbZjDGV^jZ8fXI?(CR+)=^Cn74z=3t)SbKrvBcgU
zBi+(AH15}M^HO0wE}G|u+xmJK-<Iq?(s$kUVaogh??)th78V7kSowK*7@M#IAln6M
zXtE<&fDqYRz|I#j5kvj`-=S|cHC+ct>+>(2qnApChlf!PcN~uP&sKU|X`F;jO*e!d
z9A6(Uo@{ShgbcxzsJwaH4j<D;<F;V;7g~}+D+f|VCa0#vq#bNOKI7Kg^+GfJuJwC0
z4QR>AT3WqGNJ+TOEiIt!1T@9u_~a`t?x>g;n*F@f(=Y8=RG_Cs*|tz3HmBj>U;t<v
zC1u-9(a-?^0)HhSqdLC2IPsSd=j9`ejfwixcH%wwQ<j2F$zr>C<Uhy%w}v8y!kG&U
zA0XeqkLu20zHY8#*8TUwbKwX3$f`hfpxuoynK=)TAIg+TJil^)t#54nk?w<d>Xj89
z8Ceq9ISgk7s<MAil7UjT;9afX-{z-*c8MIV2(UdoV4{EqWC#~v6&X^s*)As*4GZM%
z>1k=QXSXVvTc#P@emBRl<1Ss|N<LtvvWhHv){})Epbder$qLjriXW})kLzvz8+mKU
z6->XE2e|hw9(!Vbm$baRZ`YC%GMMPKqFzAdV>wkNX0j5T+7{1k7lWFR5YQtjm7P>j
z!2fa118gIZi2YFe9ve%Dhi7T1(g%k2Y9m5IL)|aWRA{<gPs~Bbd>i0EhlZxe*`Nk=
zr_(2pu=wp2WyE3jVg?0;{18wrIv;P7K6yfR5ti;w9}R+#LWpQk;|<qVclE$AQ<$B-
z3=HM5nNF61>B>-wz|7%qwHyFU0UVvE*P<w9nfa9W-#0dV7e`8+L92?6vz7n=**{)9
z&>y0uAi>#a{vibLl<%%<@eZq6wf6DUO)?O~WRBFu2%=yfj+1<U_ZlE-_S-2qBwSDp
zH8q0Y%8{GxT$UTaRc%yN@xk2M8BgZREdb;J20o2nDF~9678?5OtRVWTmz!sPj*gz_
zE;q0RV+RAj$XIDvd3klZBFsgDh%<e_@Z3+c*>OqUs!LkTzrX@g5=NE|8Xc;yBlKuA
zmenLgE4V<D8!#8)z86<plVv_54WRCJf(ncE#7}YZBQ`^iw<ft?jdSiD60v=30P@e1
z?b+nqTtKUwbYv#}XIHXMl^zw@`-M^v6UWQ&Uwe#<XOg-%qfOaw>Wzd)L~yuYk4a94
z_<yFUbbVHBcc58!C_@7Zk%RLi!rOEYo;vI`&b_>glbs>g7eU^DzQpOV+3lYv6B3Pz
zQ6Dm2D++FtiOVyRR#zvqWMrh_b=m!{G&bvc!OFs#z1t-NS=-o9VVf%YAO!qSVIJtc
zJNTg&$MHZFY%*J%FU8kJG0Xo#G>8YfSz(6P3s^V|5*C-<sU0~md$0r)u<+5;a?eoH
z%-)%mI>ZMZosj8B23lI4kGuUvPg416V<slK%8W+rkK=$w+f#4#@-(#1_^eAMFKr)C
zVnF4(vc57<A*Rsb1iBwkw9iNVz>488g>NqKgYt=S#a(!#?`Cgrj`cX2z)$RUliyq~
zFpK;|mDP4<F#T~EgJVu-K3mQ@pO{ZX7iv|{79#$okd7R^zQD|lc<t!}#v~@1$6wLx
z%Prevq^0TU>6sX1fu=%S8dj&f+WpR2c_$SUhFI@ne3|J2rV79Sz(~@ki_soJ=OcJx
zLIT5CR<>^kfK%0fnvs>oovgSC7>5nNv9miOp5i#!oDj0s3DR-}f>}QEN$enRbkJlc
z%CK>8K#A~MyErY+YuPu<CpNgi^x<WRNz2^pdtTJf?)?Qv);$2HetqrWT78o88O#aT
z7^cN46LUe$F28itm;p|4^moHf%_#yOu2ct17Y;)lWN3KGUr7^8T!sg@0$8dIV+)gX
zvM*;F2v>!?1Htr42KggW{!+V*Q8F?zAArj_t}*ddf#zkgEda-0<xT`(KYj!UhnI~s
z?=4Q28plV6+nw$P>vthCPBw<};L$^rRB=xe1P_KvvX~4Gvu10dRh8A6)%LDn8myEY
z)YO5bJk!lX3Q^GyRM81Jl1{UoY)E5ZQ&aw<0h9`gyT$|D92~uqlTd&I1EQ?BxYT8L
z7fs+5;x863-zY3$0jmQu+V;oYVrqBlsBTJ|--ql2w&?ZbX+QY{KIdb(>tc%;?`#E1
z34ZYp=!`B$%Xp-&r~Ei>=VxFN=PDjGZ0BtYmFZ~SB79^`?nQ2-7PDMxj-q&B*4*;Q
z7bQ(e$;~gm3RKVb0WY%}m=DyGY{AL~n^6Nm+~{x+k-yV(RRlC&A^2E;p>nXvt#{vH
z00XD|>8{m3fiwzoedv#vL4wq)hneibfgdfwM+_6)cy|tD&fauJQG6pED~B}zB%4{6
za=Oyav%X;Nm#5E70d(4C2?k|DhEBF1-xCr(n3z<VceUcu#~k>E*@Jd%GDFj+qT<xX
zu<zl2`A&dXwuQN<y&UG!f|l7A7Y?OjV+-?rfdhsQ#LeS~h_gRl1Rnk?)i_jtzK*7>
z`4F@zb6Z>V7e-*nt&X?x5ojBe*gD6@jjqnw<*5f3gzKlKrU3RC$K&wYz5{Z#3jwOZ
z**NBSJQ6Rjhgd3KMN8I)e|Q3YAZRvB$G%oc%74av3Y9ULFXb<W<KVMfztND?(>uKf
zPJ4uo&h4=N#!Et_;O{W62X~quebHNTVnXnX0dOr9QBmuZ;NT}Sc(}M?Js>Q1qSZW9
zLXVE=tUP_cNYRt#oxSk9aT{Q*a`S6H7Hwg9#tML2%66ja+czGi1Lgul6buW+#KcI&
zim&RI3MgQOe(UaDTYJV&&cn01klv-ZHeDII$t~O6wwk%j>1=OI%wzjqs*uLef&t3&
zP=?3s7A!_W8b-%KFT!;>;bXLgKacNnbY|yrpVtw1->)qZS%1+>6tjOp>i=0tFe+;&
z*>;RW8&&|6cu9?zkjomAWou>nqeP505`6rY90r<o<{5?VLom74$qzkkm#YF;Iq`b{
z2CwrH4q8zx2;`)teL>*k;k5}>p%ZeFQ*=}ckkvarr*}t<rQ(|TnLwYbXe;>*)}wy1
z4eJ9xU(wmw+uhA;efaEe&dRa@H2)b4eZ0hw6vxcmd^T>+dpH$a4a{JB0Yd(GCp_2B
zUm_#{g_E=fqGGZFV4Ev2^<izj9~fUfn|M)>X{f7g2R0D=D8(U-^}RfxTMr9IjMbQe
z7!J8SWyR7i3G$5%NzcgG_ZiK5r!pV`fHo1XFuhPJ<XBN40ooNbGt(gN0+!FOFb=wY
zgWfoyI}y{ON*{;aZyfSH_$y=sY3f?7>Kk4Jofg%FQC|YzjS7|Dj4Pd^@eoX4rUUFq
zo^@k=ok8t%3aEOsYd-FUjO1P$j4W&`C*I9_zvs9s4^;i+h;M#Ry)=5IrO(gL6=f9^
zSeg34-1O0&@$sH0X*+){C~LH3WcPDE`?0dIEg^RvEonXY&Ikic6Sa3rQ@KG8z&EU{
zZ8u@{g|X_cHmo*SSh`^FB+>0`3yc~5&521C**YF}2i~Mu=mg6%nGTGVtTm968NgH0
zYuD{}Pm};0uC7jV*3}t9nBLlu<W*9=N+`waU%%Yk%HP?QS<I}1P^wa>Sr4Gs&hT!h
zy%eK2ITTXY)oDoq0aDV^6<`oQ|DghhIw7IfN7=#sNJMSOAgzkZSnL?1sR@6H^DAy{
zCaafiH}CJ}SpQC=<<&ni;kykQAux=i$QD!{Ip(+QK7)zAU+=05`fVV6j53<bY5&)%
ziyCiFCwH~h0mi|B8-RsqlBri@nF7RU3W>i+4FF<9qsFs!A5_&Z?r0On?*O9#z4kI=
zj|m+>X-Dbhx;dRkW98vESo$`R&#E5(@d|->g%%{!)^G3{rX7FAcLA=49jo&G`6y^;
z{+KQI%)n^D^-y0O$Q=>!tAJXXe<8wZmD%`?74|eEh=}X+wyutjS1=qIQ0GI2H6z(J
z<&5>`-b!O2=)&Dr3uas@pn$>=t35x=T;7?jRS6b`!~NP_*P4A5K75$}Z(n-BzOd`<
zCUKanDa@bxh8p(9>9Y$+%r$Y?t&b;r^KBaRK)b*+FOKq633T`Se3%}n+6NM`4Ztr?
zT!7jHotWQGdw-{p+#d)cy(mGOz6Ut;j7CslyB=&gfYC7UqcPZ;U>xEbKIaDjhk-r4
zp@2t@27Gn^X(xyl$8ptTx52?17?|M;rYH|vA7GG({7{oLGwajh!+sYQ7$}`7opP)L
zLF`|A^7OH`w$6@=i<7hj3X%?QZ<PP@Bn!_}C3&AauQJSJGl8PN1HRZAcs755jDs#F
zE!Ty2P(NE~TD~b%f4z^Diw|_OLzF@8rvsFra;<`HaknT*4$}{Ckum=O{7#>)nb{$z
zVL*u&4&AQlg8-surqpQz(3^uj&EpkCS#KRj!Ib94O;rm<Q}e-O$k7G_h^bB>*yQ>V
z5fOlP#x~wlnk+HpsZIGTaj}$&X*pXXER)Eq&rLru+Ul(x_;I-X2`=sm7@B-=1Ni?w
z1c(({aKU3Vk9@YQkBG0cn>yBVJvTI5ZRZaQj-IIA5vYWZoFLTa;1f|JQOU`_a>BbJ
z=`{z7KHN)Kd?O;fN90$W09v8h8aF#2qOwk`b{rr*s6U+^Rc2d(8YtuPNdV;wm@3MY
zCW_}UN6p25@uCSd!$1KMt$of!PVO}b#tUizq^ebEn+zm`evCO%v7@EpV6u8-bQH|t
z0?rc`jJ|63SBu#G{cQ-wFEKPh9j-@{N2X&1GxZ22wP|_=dOkid0gE#WwP`J^zocS6
zxS7NN@-!M*Wqkva&NnJOHfBo$MSNb&=2J}iT|GVMj~<~ue8^tTWI3G`41&poT%W#N
z0XAvkV>~=V1A~>#%{M>r6mkIC321rLBA~kkt%1o?E;%U9Q)pj*gU6^saQS~-lLQbf
zhb#}(*y$-^;{b7OTj6#aaH@n8xQ(4%t<A=*z8$=D50w@P-1qTdP(R2|-`t$fd|i)+
zr#d8LAuVkQ;L#FdV#)9an44SE*)RSkiQ7|xvxf{fryK;fg_?XYHA|p4|NFST3-3Mf
zOiWU)$-bS4;X~zowe5+rrt$xN;sOcur^{$X|K!^^I=<0xsbOlF?d=^IL5}SBdlAQ@
zny~*$5u_Ua;oJHBn+2l^{rz!<8^Z5@U&><puV_O`8oU9<ZVwOf|9gVeO$#fa1cb1D
z0TM-}Y@ky`z9;(=FdC_CeX>CB8mamJm^;gdD7UcPgKj`cB?Li0QKUhnq#L9eQd+tM
zq`ON%x*LWV7`i(oRJuhvB!;e`>nykK_dVx7IDAxe=9zh(weEG_*Y&&jwbYm*a}4kL
zi%d*RTpVwFi38Y;t9gG(Tig3RJ#;CWDWVw1W8)rqtx9WaYw1lN12M^`>p0ms^c`jB
zQq^~H6^q;h{dUhV=5esCr<#-N)D6)wbB1<j1N%;#j@=x#iWim5STM1|0P_Yh-N1hr
z#f2Koc6}yQ-hV{Q`7HLXSJYJOPPJg&jkjGIt(mz&RjIo|b~;yA(_hhSBd4$u%jR=M
zJk?G0p`bnquZgdU_0REd0St+8<(OFI$V?uYK!KJ<4Gqn5=|D*dG_-}Bz~}9L(?aLn
zCA`jsps}mCgTg>f9sdXlI0(oBKefH~rC%}YL%!E;Z3d`n`ufjq?*Xy<4_lwS;sFL{
zjDnUH5#eh6$R~n2VCWu|v@%tn4Hlof-D!ND0-VeOujw20?{Z0E@QP>P1EC&eU0}mw
zFg<ZG{&Q6l5+*KUDyv6|;(ilC9wJoNKjZ>S(|HjHGq!@{<>eTLNoztPBDN8{KD?Gx
zm9s5RZ4WAzx1L@4OVR43A$}!b_)%v*p?#R`*KtRHZKCX_<?|OvVc8F9fL#T{wR-Gh
zfT;fZi-_1%l4VH3#3X-uT63E^HwA`JH#zFf%gHe`_z;(nA-spRp&I{AOGD8|oNQpW
z9}J3{OTk^zZV6`p;c#Xme$7tGd1a-s(z$x^z>^)#XYFuq%n}zj@jG`!>F<~S6N7^Q
zYSXdNQOY23LSkY{UfZBisp?G3$WP5Xly4`V{qrvC4P1PzB_m@u_aFyB*sH4vcMbJ2
z=Cl!?PZOY{+O+i~HbqxuE%)A&pun;Ez=(s5e2mh*g$Zuq<{t%a!+FZQ=qz{V>A!S!
zfq^{(9~C_>%{PF0iaFnE;&C>c)U+^=m*1VgD@jE~Nh#?1qhq#zZXh02NcF{wmt!rd
zMSTp9%bGuyU9II6mqSFI(N)DRMejOa`J<tf@oEP?Kta*HL#Teh?3ELQS6TiF$XM1r
zz2Ut8pl}w23Oa-;t*(8Us6s@bMt@~X@C>~MC6ySo)TqpS(NMCY>dyj{O_>$-k)OU8
z8?SoR?FmFggoKB24Nrpe)b?ye$;!LFbr#(aw<ocwso!pAYu2AqZs%C8;||K>c6<;Q
z?{?lrS9%be5e?DQG_f$4E%((*RU4o)iuU-ep&6KQQqGovfyd)R=|VI4!}B*UIWxSv
zC<GjQW^3ezzVo@9z3~nWtIFBNp0u8I+ke&HF67-c?Ay`R(Lr_VleHM-j&z_WBYQlW
zYB5on9Gl}mJ~pJ+OnUrg`pbN2lMT&Opv})_|6Sf%n_p@RfeH<tG*4+)GD1QQqI^Bg
zSN;7&Hw1WTP6sv!N=g`$@7%c~ZX2JROji=)94oQTtldCH!Z_0|{SaBY)$}HC)?Fx*
zP8kl?1b<0+(9qV@Ogi0})6u!^DHFR&F{ra%kdv1h7-Gr7*+RTusFlOgBC}j-n7I6o
zVEX5upkYrXyU^(9=<xWwCU?)we7TG!_>A)o>{wPxF2_#I3HSE<_oQf12ZtN7B>^_J
zzP;Mp&hk(F{U6+jU%r&EE@dv!yr6w^Pe#Jzhp*_jf>&8K3ZdkA6fI;AWGSg438`U;
z@$qx}O$6lRWQkF4FSEmI^1^FWFP%!jc+Xf*<cog+RgC*f^1*89xY$R8k47a$DFb42
z_}zJOd3Jn}2age3Bi4Hpxe#%yQ$%|%lf<cp#uRv>K+6qGJyN)imXiw!HDB)pd)4jc
z=jJEG#c6724)>R6U8uAUB5lV8g|vco{RRaAqp3ubJ;!-~P=e)RAL8QSVIX0W5133=
z`k5xWmB9^hUAZg2XvB$m-pUc|a8}EVq3bV0!p-XRF*6GZ7YZXN1m#$SZAx@f6TUn<
zH7_yuoz~QJI71?SOo4qQ1f!(M<=pL^n31L?I=M6M$+2dgg*9DOl@w&3Z~y`o(|1;h
zGfT|94%MB@@zuI}dSRC+ONrTXAi4DL@na3JiXrpC3debL0$+g=U@kjGaQ@c|u-277
zsB%!Ht2E+yhlm=P93$iQh#DU|-R4b;O`Z9k<2%0ZS7^Qw9GQ{ZG5qEFbGR7g<7*k|
z%krWyw(F*z^}<oXvKR`<Z@O)^Ve*7XNJ?sIBM<LLtK?MXN=7F=H8)L*?KJDz7a8}&
zqN?ZD1coQu)`eZ^SM%4w4p7k3B;z;uG)qz3bV|`X(3its;yI%x>#>^5d*gd?;r2XO
z%I2!SxVUKYs)GuOa0E8&ovkTQca|O&Mbp;jNPDp(@n%bSQITF7nPe9j5%Rnq89=Du
z_MDyOS~NGWP|EZL54QPOivh6{3JQ@g8y1R>2%<>KNQIr~5DODrq*#rlKzb_zmS?J1
zIb5cIw{)p(poE#392ODsD^QK;C?G`TK)1=(5?Wt(Pf`zaLqhe_V`ZBC#>bL+-shv5
z>^6;ii>wzv`e2}kt6p7elK(PUV+uGMRP>`VgS6Y?<I|Zm#<I97t;aZfj<Zk2x!@JU
zTCs4IF}G2ARTb)AmNWgAZ6tvmXen<WqFdE5&73Nd`zXK){ODdjRUG$@igaI{$Yn))
z*V9vYa6jbugVnnUh-&a|;h^Y@n#Q$*8J<R)D{l#rDjBUI{wRYT0wD!=x#xX|BlD%F
zexx(tNiHenW7VUG^f%8xbdHa+H$pgp1=;_Z|Ap$jpTET(;50SM9^30X=V8B1qM@S;
zbb?H?2GAjQ5fbKuaUq6;4LrKG5LP`qeMt0nj*3pMBpqK&T2gv?mHiMZ{DE{S{oF2k
z5ccN6OqH!@Pco6<Cwi*wWMnI+^%Na;r3CAvxq{xg+=_2O1H6Tt12AQ6kxcT57m~PS
zKkFf)g?SK)y4yw8C57qoYIVhy-CFNOWX~@n!RT1n&=G6W8+hedxJY%#FA25kj_R3h
z-j6D0u}=3J`7y(?q`m4&(|;ZfXG?ON%;38}2a2>KynDOjz6rw>F`e02S&E0%5}AZ^
z1y7CaL(>Z3)ygCJIc(_SAL2%LdCyjK)+;<PCH4fdQ&}CGgYwr>j<o`wgtig${F5*L
z#1LX0l=q$PVk4D)rt0?7zAmj#eofv3Q$&`R%2HxVGW3Ba<<i^;8I0V=X)S6P1DPzH
zL14u1d{jxFkyj-4g<4stUp+>WucIFsGMpysK^liyj(7uwDeiv*J@(D#$z8B}M=Bec
z>Zs&F?x&OwZ*q0QtWkxtm1)95!W43^`Z{Jm^GB9PLUNl7Pf?c^@~f*I8b@TBSsne1
z@N>J;n|1lgT4~+<=XFO#d6cpqKXJ>%?AT+EW0$h3gN?D>YBYtM$llOgKNsP0+g(KU
ze1}H3011o?Qi3z_o{U-^Y&54oB{2QebV89Ud7gQ`9E+bG?dP`_PQn@G<^CQ8MLH0u
z$FeLCb#52w4U%<03yO>6kF*dl9n#CUV44u;Cv7}{BsX3<K{I7LpHqR22MoG3k;mdW
zrJ9<2=K^wie$IQ~$wITT+DRBl{o(8gfR0c~&JC>6Gs|TP`0l8v5{u`?p(8wv>%?qv
zW#zrKiQ0KyVT!A}Qm_5(((?-mX2%K|_=_=h*%3a4)XiZ&UZ*|SarT7S=ETpE*093D
z`<_-fEvG*7PbXZ$v2hSEM>RH;q1g&cL8efP8?dd8k59-Fej-V#*X<>H?!sX%cDlCg
z^se~;a(t(F`@=|`75p(hLkqBzFO(Z&s6swi6&KzS5{$vZ(`j{!g{jN6@XgKX6v~S)
zoS6@7$c>!dY{Y&W+newhr1vxeb(&;EI#h%}0dIPSk+I)w!G-XV>u$#?Mq~$zcH=Zm
zy-r%qrQ_$rI1imxyL6L$z3sqEq@!addmA(p$z?Mm$MFR8-hklsSVw1kVxprX$Inlc
z&IL+ncM*3`W6R2zp*w<}d%WJsr|jmq6GSODTXkCwir!Z~w#T?s4Fxf^j_bOb^$Kh@
zZptdz{Pw$4a=HAs^VgDbx+6=nkmpuUc%H~-w!A%VnY+aGKJ=|JvgCkQk-vFiA!=%4
zD&t;X6sD}^B=6$#LR_AZ(R!}J`7i(yBZp7Bv%EpH(@)qxk}4;s;Ekm9+w4cSu9U9-
zLXh0xSHqDFygz3ks^{Qnpc2;Va?X=ZkiuVfFn1oNPTR6fT()mL`W?)+oS3G`%&A#)
z8ssf^AqR_M)iw&Ld=Z!!xa2Z&GB5%NuWjdpDeZhHo9eL>J*0q`M7H9dl`0Rj*$`~5
zsi44Y$oKiG@hV}%$@Y9;EoWdP;Xm3fyOQh4Ef^7lNu1d+JNvWB)r)66_DB<Rdq}bD
zLn9B5<>aG8TFq&11j*_m^5H%E(XCOfEN5_z+#IXEzZ2Eqdj9Ysgv;i9tO2<gO(2SX
zQeqUJ(d25m$5?U}v(YRkiE3=+pdxL;tiSZIStzq<91#GC6h8<~EefNugnkz+dqN(6
z^)8D%=tsZ_b*M^5S1{Q%gYv`{hO#ChA-=SJV_m(iv99iyobr#o9f-WTy;&~9X|bg)
z+JbX=dA4DB@fq$H$kq=&;u`n_b;OTIU-yZxL#=pEfrz$^#?{@G^P_#<5w{gaFTqAI
zL4zQhijCx4%_(3C>S9safZ;oj;E~Miun6rb>>A8_;R-|6pmapc%3yK3FWE_3kOmI2
zEhP1WY1H598kg}rwTjT*o^47(0;zmd-D4QYOi!5gbNXG$OnrK*<UCQG!F#A?RD;VP
zO`GcU)RZ(1m%QWqix%}+=l8EXJy!_QpX_YR?5E&p6)H*VQBk{x+7d1g+rR||nv?FN
zxN&8(2ej&qI%^c}ieII&Uc(u41tk^IvQq>JP7lqlsxifg=;7?vpa#7|3@>ftwt_yW
zQBe>U_I2f-IWP>8S>p{|?5rERxR;t9!-!d40ADDQoa~+9_ztz1X_n7>zt_DE?d=R=
z;@wcrxws9ecurl!gQUw8VA%8?sj+uoa!ah9N(IFkCHpGl-azt~1(A4x*Kn=Z2b>R2
z2;fEgo4u<=ljb+Ot?3LKHDX1*UC;f10y#fF$3J}~$3gqUd~Gm26sb$=^pIx+%+0Gm
zj5tiRk<ragH9JnGC6DF$)sjM^BI;U5*|Q?QjWG!=;jVHNO<Lt|#u~MaY?6!FL2eLc
zdN%z9*?hy*6}3>DN`ncW3r1S9&4oJH@P&VETVV+61PR?u7+BC}0~8cwWMGK!S~Aan
zz#_kz8fdcSIZ)8}mahLxCruE}#?U%!dM^7p%{d?V>!mLVB_)orUnv|Kv%W9(q)4fB
z0bxVk-n2rQ42$&n^955g471H0spw#Dp;s+>nwqN^bPLhbwbswHoBcS+nO<?RM2=SQ
zI{SlD9Du!^dvzEJ+nVz5HrV&_E33N0pdWql!y|SwJ$6AIS)it{VI?Ahzq1r0r)egb
zt)Bhv)ic(R<<HV?ulP?1nX;n%sLZqVo~5&=rIRO?o+S$0lcs)gmvNdwjJzHj2Q-#M
zpWVs)Iou-P`7+LFMC$X8X5%9hqLNX2E}Nb7JR-f<<WH+RhjqnZiaq^-Q2R#MPrwsk
zV`Nl1%z+hz?as|=6KW8M-?$ntuL;gL?ZVi&t*Cis10<xXX~tx3o2;?W6t<Id*0~Y;
zxp>yoxfLP;^X+r-@*RZYd3mP82OOGEVj5UndULWfL8v=Lprq1MhWOgxPpNt%Llp71
zy>=@<&8Ni+Um3j@%=V=xe~6qa(X0yLB9EWOotS~py~{O}+a%5bD>p(pizAKCD=s4g
zk?Ck}Z*{RORtFx?Q4Lm3<_r-al*{5H=^{tbwM07FueOoVH&VZN*((s}RhLNmKCm_Q
zkT$@JQ+<&m^K(H*m%rIPBAW<{d;Cq#`pZ9_R4O<)+e2Qp7%aC^G>>){6~~;#<tsFu
z0kZB<z}xY!OH-8lg)w{<XYa|$$uD9yDIauM6nigFsLGWUK)>_C_Se+Y5@7|h@u&@C
zaC~G)<{QTdxRi>TQE|aKR3*a8FP|h18Y}fnQtDc9DD~$XUT(|{B1uQ0c|?fP{ZP#_
zv2MZFFD>E|y1Gj6a@TU-8_d(#3%b~>*?*fY{AZ$2sY`C2_H7L5ov%N?oBezb!33vP
zsbl7R6_FIi<JJN-?$aHv4bS@<sx^4fPynG2uY|tU$c~RMSOBxNQk4bjx(jALzL+PX
zJJ#>tf}W9;z4Tb_A+a;pWW>(QtAjJ)xVVFmILIig_<gJamiVe_>y2M@W89D{{4a#@
zO8vqL(U?{kCwp?4Smbm|(U4*Thg@Z=w2*Hxv1#%)Y51(u&4!XV#=TEZWmR|5LkCGj
z+`8}2d@E@!QXwPAxEjsR`WZ%dchz4h$6&;^7o$C97L}GRtC5E&2#@?}z#Z+Xd^y@g
zBj}qZ3mOKg8s~)4&6v5ZFgJe5P(!+iTFzCyYSWY5k@y=A!kdK|Svk31<a~1({BIec
zi-KjK<i1iQ6)^HqN#t?6SoHOLHxd3s;O*P8H$0=RMklWrMQZDsl$;K~hLes;`E%}F
z2kXbMjR|62T}z*IC58!BsA5qT?oL3n$0V?$)7z$b>C@efXLxBo-9CoKzECLphj}m}
z)BB1dT?t5gd`5qZA`3|89mFxqY)nH9qt~H(^&ZXG4Wi`Sq28nGhTd=aS2m%F<U;L7
zxbxI<NwlQdYO{|^HpUi)p65^;Jzl|;kzLr>*$io|74RS&v<T`*w?Lldkofu0pMbq5
z{!!~O?VAEb2vUxp=cRo8NTOY6EQ0GJg~xE>u?YumIq3IrSx*6~;0tR)Hl<A(hYLu0
zBn8!}e}3pAg{Ecvn?5O`tM5O@uA?kioUiT@QA*1ScbLuz%`2`Fk{o<qgM>TZrxPKu
zUHMtq8<}rGDP{-AI=#3qA1tUgpFh_^%{jHEr>K)55&IkhuZPO%8(L92F9MLXnB=2C
znEpeBJNaE*F9h1gAG}YSjd+jO#i7dM_u`Vtj*xwvfHL>s!0xrPZ*A=(1q^1LhMPA$
z2@|9Zrf`cr6?xnfC1qOBSHVC2X;+?j<G`44f=U?l5B%As8&Sr-YaelhHxE+yyH)(!
z(~NiLFy)46UKw@Ao@OTCs%d<+{V-i;LtA}eBJfb`;z8$gim}ogqow7vun5aSpByU8
zo1<Qg9_Wg?Q<vw<h@bFjuCx={2Ff%^Q3!?fOz^3GVs2b|8m^Q;T*i3hqi3gL17%`6
zbPQGsiGav8B;vuJH*7y(EP+~d5}~O#e_2D|t&7A%RuGuJ_;v-pZ+?WxJ(Mzz3)0io
zbxM^Dx`YI~ujp%10e;+m!#1lY=|1mmXQ-q^?1c5G@}{#@#(VOp<Vd;r+^(us64~cj
zeOsll+FAiM|42l9A$|kn<AtwIQpq$h(!yES2yMuP+B&feQS9gCNR>l{^}cP8HP6a4
z6A>pC&y}n0zTPlx5Ksb=s6Xt$oiBGU#y_GIgXWi<mUDO5FBqf~qp#Klm|WI~xO<cA
z?Cp&ch0ck8)u2(@2#9}){9J85M}@rUoSkh3y`eM#=L%mfPa2xwi&A+zmI-y$tE&7t
z1#23{X=?|<7cXB<dL%}P)U4K)Xla8}>!xjgj4_}N{ZxMa)={NVs)ieWBCIm9rG|`3
zm}Po8X34>(Tun#68AmU>UKOIYE#;&7<?1jW78b0K@0k(l`EvEfUvhiul?wAhDY^3=
ze;hcKTL0q2vS;Ih$A>zRnNBGdzg)>EgtsV<xcaLKIYBlpq;Je?V+dM}diw>*FKB!$
z4l9q2p7N$rWzIHBJJm{$&ucWoW%BV7^A%krG0X`RApYb6C<#re4C!~xok8mp>Jwrb
z)?DQzp12*C2NnoE{p>6CUG6kB|Ag4Iv|d8Bk$1n;5)^8sL_}i7`Ff{&HYjs^+8<n`
zOH>l;m%kZu+f`s}MkOpdtE#G~ly$Gwcd2n!DO}Uk7CpTn41oB#cJ2*=cE***^5!-m
zr4FE={A(Waffu@>(Q%zhaY5S`howzouY2m?h?$Ruk?2Tz<kqgY`FH;L$2)CXrUxf-
zKxRRNX4DK3m6E!@_o93AL7;MTSl2H^5>Bc!-%*rH906PuJ#aR$MTm$-BP=TgcOrm^
zslTveajIT_AlL?WCWR1nSRSAH^7`(=+8Y0PR#j!ywe>=Y8Fvh2wIAhU0<Ogr9@~CU
zanm(qDePOn-`6<^Bu!6$qE#2OfFWn=kyu_{uurNR=c&lSxVJ&30tMaq<Rp^IxkCk+
zp$B!@1RR8;lao2km4=s`BF@=7yq^fWc-fQHKTfcP1|yh;*YF!30I87b>$ce<*nO?0
z7*9G5j*>$x%h8Bzez%|9eUs*$`T2Qc;T9P{<q^&|yXy2%2})eAJQ0v$K;xkwT)Z--
zzf4}~hN=cikfI7B%-k+iHFmsmm*6+^YX!dUo|xsdqX6zN-u-FaSw9rApQ$d;rAnR1
zIs)0=#JPiIe?D29o0v5q;v3;-8e_4&0+wmy4E8nI!J_^f8)Mm-1Y9GYP*;U>>HQiw
zvMSa~uXhfzkw^2H+;weMoCj}xop^XpsyUGO`e<dWzX<g7RLQgPQ5GA1Pie+EmMl-d
zFZr){wfs_5ltE)gz0r<y8|IQ(>Ts&CJpk=TWL{OpH*eJ7hzLZJm#r=91m+57*W%=M
zj%vv-WN1h*4!)O5V)NJL+$Pj7Kyz?WI!N#>+^8mG(<TTVebQ$B1n*v{`jFb@>yr+Q
zxmGI%NlEu9*b$zl-d^&WVW@}E6IFQ$9LlaD9K!uTNxs4UUZ^JZoJW%bp~OZhdaKO-
zkPh?BgG{-Nf@#sZBryK`=*GYbi8L%|l_X1^Ut77K<C@vj$oGj*xW^D6V}=W*F+Jm&
zB~ynx0C@iu|8q88Udi37slx<On}&jdq}Ta_hXNYU>fEef%WT}8qowpXqrE!#m9+o;
zo5LbT@NC=d(+~aMpT+AP7QfWpmRFr|$k>gl%<*IkQGiVoM-;SFIdCM%^7h1Aa=D(i
zgOw&A;05R~Q!p!kcD!1dlGKmZ;dOqiFtpg2%;5R-1<#a#3t@)h7qoX~mNYNatp2Iq
z{&3DTiO|cO<r^W<{TizCs*aSGdxykfu+3rB?JdHS0x*UGs;M){o*n%AZ3=YKdP?RU
zDJ{&;xgR4)A5lo%N=OPs<X=Cd=GYle#&Woz;PCiJJ*fmVvgm2RV6~aDZ&;Yu;EGeW
zb*c^ZGF_&Oa!q8v8Tk3TCng;+3=i}=b99J`t$Gm>EShljdZ6e#(!Y7Tzt>90mTR%+
zfqKX4%!@$9l1qIOaX#QhSaT#&y;mT?<?$Wm<-GO7=*Yt9myIIHT}g}`7;?!nIiW1O
zFU6xHWn+Lkj&dk$lLD`k3h`|}H#g3nnE8_3l4@c@$yQ=n$ImOEtbiMj@><g3Y(+XQ
z?)#K#z}j0o?w>OUGR-6T^&8IXqw!>MXWI1+j>A3z#nyOK;=_+*<QU*)iyvF5r^ayl
z#E73%XV*RF{uJ|~p$~YkbFZ7FFO{hK2V`ezt%bRGLif<oGr64$v$7VyS19idCV#OA
z9(AUVH=x~pp9lOuaSD=yheciqr7hIF+|y$lv|tQ3c%uI>S{54nG(8xk!EB_-hA=7A
zZ#KP|Y;Gtb6nICGE`)gcnvEmcEl$rrMpax~(%Qm;=N2t5!@zSHUKh(nfbnkG^5G+8
zimuDg46nru`N_!iE9?Y$r%qL6c<HZyh}>!(sC5#)Pj7QL20H{ErFg)s`|x-ln1s^e
zkviQ$8E+hoQR)#)Ps{Ka`5a&WNtNm0Z6gEedFuMpE8Wcw36V8?0y37Se=aTtSzKti
zHERp&2cxLVuHQ<-M|rIBLRmTnx;EmSW4~6`J?un3tVm;c+}m<8j1D0n<NlBpQo(9f
zknWCaBy|;|P(vty0=%3=0%qa@m7y8noOILf)pC{@8ab+?q)E@wt#PH1n2_-D#mk;S
zg|^ZoW<F;5h<N6t`_JP{jeDk43Af`#HB_A!2CtO-J5u3&{%;>%A+k21vnf>{jqYPa
zmxLDxq(#ws-<Y{(riY!q30FS3%zFV<4KpF1t}$3Xu%)*UQ?u`#F0}9;r)wlV(})uh
z68IW5s``sj$6Y4Bx}$q4BqX>V3}=m?8UDB7cHNiwL6Q;&sO7VS6eu#b9@?&zd+j5m
zrV4t2f#R3A6vnD?(Nec5J=~Jw-@YFBh1ZCnsvSGoVPV<3H@P{`yX@04a&yO<<oHM-
zM0D@V$k@-f(t%p@1Tsx#JXBHBlJgqEW5e(9)?46}v4fQ^;~f-Th2Nf3i?Csxw{U~^
zAB<KQZ*JVyX1lSIWlF>)#LKi>e62Bcg?1VOux9upB6|9JUvqNCz*iK7+F@x;AH|&(
zXMWKP9V!Ohd9F`I3FTm7;ul}LJXkH_N{adC6NV#{1wnMJ#_0CFQ-^OI3qZO+?u?-X
zZgzZ6U*AH-mXFbkC8nDL?pJS+zWozl?Cg(z6fcNSIz;u8tPEX$r!{_8XG=EcC%P-c
zuZ}3w&lZYhZw)gU!MOUcT9VyFwzndpD(qDuh}zQBavAw5BwTOfu;$ES*ge{fmXley
zRsoU6Fu5VO^Rq^;)|Qe|R>#a#{Ts%Jy=zD$?ldZH-{*4qt&bPm;xAh}Ql`cpuAWo3
z11~ZjIX@kTV4#C~*`+EHAE}=%;4ZwG4J5jtp*M2L?|Q*k^fRaY-gNU8mlce(a$MA-
zE}I9|+A5+RR)lW6qav*`0={j;+<|ooXuC1QO9hl^H%Vm<f;N0W-;t^+$KYs9qtX0C
z9By^_Cty<`pMMwgOPviHE9?_~UAtXbpnM@Z`bCTT#p{DS6XzX%!iRK?Q3enQYr09@
z&TMKzLN*MhHDSCv@BVi4HRI#Q$*{psxU^)JMbckqVpMk0n>Cb2+6a;MXl*xHi7<>d
zUHw&rB$n6Q*CXPx@0{zPpZRIKv|yIpaWcc-L3(MOORD;?88t<v&+Gz1f3*?+4iyFd
z+ltWq1EHn)LEA%|Ysx}5J}Fh8uy}sINmLKn*L@bJFM0u~@um7apyfR0zW+(@K4>0(
z-#eKjZ#t!UNv+JG6kP<P>*yVYW|ZJuGq+g(a=K8qcE17tOj%k)uO2j1h(YH(axyk4
zNmftRX8sUn_wB^$McE7EQ{?EOJKhtbTKoxn1lEP&>h&_|16tC|nVf7g8xv~cGBrrA
z^2j|6M}Pbl-)nKX%;jZ*7tcQrlFu|Yz8P7U*F)OO-CtDqgIS2ab9u3PPsJ*q^2V5@
z{$@5(cJ{7#IOp+==r;<1&<C5(2<a$zs4&I)W#tGTM`?Xm9?WQCbg(yEUNlF3dIrE)
zD%o=l>rYj=rMu0ZD|4_2Jd38M0RwI5%5DS8m*BSS(5V`-x-+*?PsDYw%1|8n&L{X6
zWIp24Pj7_Tk1;IA5lu)|CqetmaQ=Ygt;45o%%(IL3(VxnE@HI=u)zaM<wt~sLG$kA
zp6ji^eh;^cB;kCUlu6~!S(3tLdm{Z9wJn8YRS&sd+Jdo)TQ91x0R$Wb#$8+r=?(3v
zF2i4?q@|}C4OzsKkqHboHA{&1l$lXt6?aNvj25V-$y|43k2j~u95h0B<11C{LQCnV
zlh2!S2Ab?oQ8h^yX6P*QRiXu0rWct9<vBKF)hDVPN|=*xr6Nb=x7IeP&RY@hvOa$m
ze3~Th48SmUWxDG2JJZ!4CPdiR7OycP!IbH|k5a~4r`};EqNVye7<;=f_@k1C)|m8Y
zvgFmCI`+<82hwci-ddeY!~-ydc*0YV>DO0yBEP#j^+|*>G|6V+zES8g<qA3uLKKyX
z`X=sj%v6#=c1z*5Qc*x$hG4oKGp;EIRMf*xIaL^QXX1{@^$%x#JHNT&*$#cZ#hH6s
zR<pgwky^VO<BlqZf`X<GOjs@@BkC>QlU9WYNGQe2aLR6YSZmV}gY37iuLlf>@F$#~
zyffK2U#Gls>Y5JM+Q5*ynD6Nlq*GQ+6O3;4h$P{OqQmnfTjQ_*R8UbTbj&+1BgiXE
zI)79nu`e<Px}Gx}SYQ)i(DFArCZuKB`GV>i(w+LK$zxS>Uc-mx9+<w_%nVq3ZrxU5
z?9Q0X&uT4VQ$<HK*$KV>$k8}N`_L-y?5t~x%SJgsc<EszO+m&hla;6%vRX*VVtIWD
zP9A-=zAJz7CO)Vtqj=AD?FB0{=9(0(Vo#Dwcuy1uzWw;hL&KGbVMJ)tql*t=9+JQr
z%4icK!n<t}cF3WlY!eKw`;wiW3Ab`Tq0HBOFjpWU%|V*2Kknnz;=&uYzBxC>CBgUh
zaW{{OFw`+81;51;zRJTrt=H_KV`p;l&qnwdI$@32Jx`$;mb;#w(m!0Z(7_D-3T~=R
zPAN7tk*D0Wy`84zysM-l$;CrUTL-$ps+KgLAM0OyFpjB}RkFj}S+5=%mV2{|2yvL!
zsIW*k%Qv<BT_$FA#R?Px{mp3j$rHE-CesZ%a*K}ppH#-_1%!Ac7{P0OSlz@yiX=Q*
zGvC<onB@s2_2hMaUn8aQ_x?raA;#HUNPTULskI>?No`CiQZheN#M(Voj1G58D4n1l
z6GV-RIkGm}-5oO0LRO4oTq~x%X_{2`x)l~~6PUxnIi~Z-B~PM6<K$FpX>`uR^TX|=
zXM$%prDkLd<}q;5-i3AsoJeJJ{D|_sHmd-FJU3qMJ+`;5&Q9_Xfep#ao%3TD!ZeLw
zP`p1B;YR}ub@Px4tF1@KO+qFqV~F%DWFwQ?EfQIUW1Q|#1zOWP5-{RMnD-^(gQ3CI
zf|SBp^hWp1^gk#pyubBhHJ{+3rh__-r;E?7UrN7u21I^;dI5A7TFYU%H8s?#%D)GE
zZHS{#u8H=U8uN+#cm-;!2)M7;T;7>atMc^BRIjdjYEGsSO(dn~%`(x2giMXKu6uTU
zHs}P~wGECY8freB$fMI+93k?I-JL5+tt>TgQlIsXYW<<!Ds+)Bn`<lDHsdV1%a53Z
zna=6aK$OZTbO`Wcb0{R0t0nbTT~mZ6?)Pe#b)x?hsK^l%jHXhyZ$6!?99&DJGrQS9
zne6Y`!fhkR?{xS9thY?Dc#kBAAf~3l0{l&MZxYxBIQ6%`kD0P4lIzy;hN#C%kdkix
z)|6d@M8zoTl!`X}2t8GSzWFd(9~~T-4o%FmAQI<O>4v7mfs#hr%4nVPb-4{VpgU;i
z=H^2vB)Q;vkf%RO<z(O*Kx?0f5lwY*x+9#Oy1;Y`hKpW`uWYsAOVej&da>`wHSHEG
z`46QvAt)a(YUdB<_>xUr&^N41fhtf|PWH<BQW^JqQDHUz21$0JV(#cnrK|F^z1i*O
zaG5NQ&kykqM2SqKt!T-M{4M7hjA2SpY59=}p#z3UY<&D!moc)J^D?~7A0+i{2fn>7
z+tg@OOWamlh(8g1$&zQWxZ8`@Gu>1`O|W;a!&3vZk_jeDzYCmcU=(>pqNw&&YgAR=
z-}!XsgTA%b+7<OuuP2g)l$>zl9(z$;?AV|v>Z2m*BZdgh!-9wY8?a9+Mi2(g`T4Or
zncznPa^?%Ah?=;{oY4)>i#S^(Z`Yhp*5`i4`O;XwW4GEL$g*q|hW8iLFKOSf({M%B
zg5<OU<{AsG1R&Y$hU|RmxYuyk9?0NExCBEv5g0p~q(1ot1!r~QeFzzgHUWOkI;87v
ze;g@Da3Ljo*tzbNn5SpGL99+-n3IS+)OQT3^)`8=T778NDR2tiR=xOMaF~!0Eqq*;
zvMqRieoji7Vi)X|y?XTHBhubYPFI8-`jH!Ou^=lQn^3(&<*{V50K=+vbOy(d59lIV
zH6V>*nH*NKz!RaLl^3c=#Kq5Fm0R64+M)erI9!*CmxhLcAy}RcnNUQ`H}WW_Wu$lX
zFtDo?6xMNhG0F}c`_8b^d~0iKO)_B%)uB;%`AQ@5a(NZ`5F0TWhCkE0e&sx8f@x0&
zBO5NG$rM3-MBe=MYtTe%Xi-*#vmFnOk%<Wi9D7^q4o|~(9tS>oo=!5vR^N$MoEVH(
zd=NNyh`v1j2PKR7JMQW8tP3W}@|=_3Q&Gshi2=ffB=U*Il48cB4uqtQKm?<Tyr`(Z
z*QokOm3%O+R^foV?i9pS1jki+yrh_sIY_39gLnuQ`}@DORau9nv@MI?Dms=*OFr?w
z55d-~!sHCJ%zqiG<`6Ic->Mfh?d7b>FH_VJ6aQ&2e2ddMr@x}L$Q~S!^C)ocd$yA`
zs@Ytf(UUjF7yU|4^Adw<#b-dfIC8IKNS;*TgWSffppW>dC@$UN{1Hpf+3PIFl)lK&
zeF+PU#0G*pq@ho2&fUDLD}1VqaQ@AyX)|+kll7I^1H48LRrX4X>tch$<wFf{+6IVS
zpz6~A^0CN}@LzZDYG@__rKF#)1>ks~>}!+H)JeUS4gKWd(Yc2^2Mo7hxE|<xH9My*
ziA~;)f&#pzes_zPmq(XlVn!<uUq>H~!V<4gd`L&L%Ir3wd-kN87Mdw3z|)AWD+tcv
zgn?$3mJJP!*c3k{8$6A&I2VB?*oApy;@Q{8!zRzkTWdvW3ky&c=c%)g{P;RO(cK{0
zq=p$W4@8(bFj#O<DGCZp81bu5ylAR{;@#ri)ZNs1*eIK!3Hd>_3HcEb2^W3bFBw!s
zf$KPZC6ib8O#!Y4XvV5`vyc}QR}=x^uJMGqk9b*pqF&q(iwZUh%cqRe+Sbw&88`E1
zf7HG%I1?a%lDSd9Szi|w%77A|^)jLYiF9~i@JA2qvsn~|QdC{c$iPeaOAEDt6vxq#
z;JK%xWA0zaSJtQne>*)h-9YbP(Uxs3iV!O>Tz?I6(@Y^*{u_*^qP~Ov4lS^o+Z7EP
zMI|-bw-lH8%U|U(TsnP%6d-F@!nSAc@Vx&kTlSHLm!K5o=7Q{lc9{U&pUW{yf2G=4
zZWh$-04g)o-(!lhuhi4q1M^S(D_t%iS;cs_y2{8#Q-;fIeGjEqJlIN2p5pH-DYAkD
zQ6Sm^Bxe$o<^XBwzQaST|6Y$CV&|i(rkkPnt_x)`PdxY)sp22!g^x7&oA}H~I7@q9
zIPOyO9rljDmJA|jKMK}B8Hz5>IhwffC+MFyA!JO;)=p1PuaB}X-Tt3*0xp^iWWo^E
zyFTi7aQ~vc6v<O$rF#1`Y^CV_-#?bN^i@^)j4O#!7Po9*^xvn9ANS~ed;+u-YhRj<
zS(qN@&$mY}Y_4-prtjmxYaew?T#)Dc`$zGiG*&rixr3_|`Kb8k>U}~L4SWK>lA@Fm
zJ{kY>Ygtrr#P8#CD$v^*&@edu{8_=hJhXSKW<{v`7GH$_dkqnDRJFP9J%a!p?ey{O
zM}7V1R}d|&nXxL{ur;Re&*3D0{w)ehv!<>e3IoWwIa-q=X3_l=5+NlcQ)DC$)=f#8
zZ-ePgpUHR!fvf62(YjA!re;G-<Ndr`Q#NB@3DK@L8;R}=E~<#RzBu*v-o3Qm1q45M
z-zato>7P$`v0Hf#g#mCZ4!c5t3-U_Ao%b@M#ocN9XHWN3_m>f2EiJ92Dgf|$$@7w)
zesgp+3?`oz8WO%V79Re2vQ%rP|64GsP|g34!Bn%Ls6RR}@FXKCfY44eKfGjsCewq*
zZ1^b-PWZY&MRD==_odFZ>kF+9+KktQWo2!i>k(jBSEUY-lIrn8!zy^?Hcq>jFQ-wn
zJ=?(Wbg{H4^)jwdnWVkyKS8|@y`m|-`3N+Suf=VB&Ka1F*&Gmx;-d^eOfK+oIEw%#
zKbX#|E+@wX02XD`-j$@hAK%}`0Yr~%vWRUY)e*qc$Y*k<uX)>l#a6Qf7^phyDUrH@
z0$Md4kl&O~oyP6{Kd$V87ewS;*C#tO4uS?N-%l63GgZ?89;s=sB{3zX)_m;i)?{fF
zX;?@^gU9)6A__@~a1z!ugUa4@L6`TpfmrK>AYk+_?F2}f(N(I^)Ik4u?(%Y>XAo{O
z)CHuGZK+&^QHhz~;%InYUUURv4W(Q4tuZzG{0}fJD@cXC-C)_bp@SkYoPvMz>fBzH
zv>?o+)!|^dp4D)7uI<~ck#vpm(OR!*J-`GZS``1YVW9M8L3Qq-;Q_Fe;RPA+#k7DV
zDv+)ad_s;Lj=egV92@I?ycy4sSoVb5?hW9oPNY<s0s?S1s3FzaJM9UW|GO0x)8Odu
zETB!LtvbJcEmQKjM8(8(NHV}e08%yr7dJ-dC^Rh0(7-SzHinvb5rnvIZ+l!I%>m{o
z|3x^NJFpmIprKjKH16a?3dHa#0K-}IbIBwZl(M;|mB=$)O-;Aut`J}l3F7yNi%BuC
zw$@!3uv+=_5Zt(v<8i<y8Xr&2>*jE@HlVMsFCHkqi!+OXP4dR8!$pnN4YQ>S@T4gC
zJ(8lM^$jh@D#iQg#_~B1kVc`|C5^V7UqQAP8XCIsx{-U7M7T*acTUU-?%ylR;w*5$
zVvG!;xCQBTi0J2WbHGsUuOKTWpRYwdWHD8_T7U2h1BbNQ;M@+gJV{9|>6Pt#^N{oI
z&x3jQy&m!f3&4K?&MEmpaMwA)Y1>l-Z^Lx()!9B1HvwsRk1{NQQG+VA{u=o!64-Ny
zZkm~D-A_v$w<fDFJ-EGZ05&T?Fo!A!QERi%>aBJ=R#U{{o)K^s;Jn}o(z<v%;>Zjx
zPj@eGf+;WX5dZ7_4uv~E12jU)S0A6wfd-W!)R00_Fn{~yi#NID<w8jyNp-R+#1wp9
z>1n_$OMZ+*zAJhB#%ys&@H#Fg#tuC1H+RwB@@wkqwmSBy(SN2CY=trqF>BXH!PGr3
zPj*K0ER{3!g?)vInYG{8oxPg-P+YR^eV(^+<$kig1iGzb`G8lkH=Hf1VzdHQGTbL`
z_Jz?B&9ocrs1?eBaLEBLVrzNRt#9uK@D=*sxl89f(`qRBJW`@qiLd1~7uW4!5z9>7
zo>201_!ifXQXNqO!3#tur_~HdyZ&EOZT2XtnubQQV*We0a3{LM)<{mUp91VEkdCb6
z>;A(|I>>ahYt;uI$BpIgZ;?5G#Vir=#CG+NXbMKj_woICrLjs9pD~Cj^zNilN@KTM
zc`GRii}x<eqHf|cdu7s3a-#_Pc4b|z35ki5AQlH;y$WY@r3l>2_wwhlT6Nk@W1ke<
zY)@5zC5wS*-gB=7T<T#668Z4C#AhPB54S%)b17tUEBCBE1doO5OcAB`MWN|XhKIo|
z>a|v#Ilo2M_iAJ{2r_6rUrYTTx14;zrs}<JX1zx3Sj&46nXi_{3&&z<6ilQ!^gF~F
z+q|wXa)KjsDW<6?@+=qIeL+Gsu#!pfwenIc9<6ykJ06y#^!!<AEJOcczFI2DWn(lC
z^opbh5}5TsNY<BJso2Zo*s*w<^!f(1nOZB5(#*#GTKjN4Qw7Atx$iHc7Ll~MJ-2nT
zOGvXeHg??YIQMB6`VVu5qL>K0TbM1x7fZpEATqpS)6Uj0`Lvr@w$Ln@oYxWBkx(+E
zZS_ikIRmc&yx)Hs6#9Dy8&}sQ0|C?gJExD5y87O94FeH~vWmfvJ?n}Ze$aTjzyGn^
zIZEd}Fhl0%uNbXsH#vo40#Zb5`oh2*@bm>>0^4@6!TkJu^Zo#r9_Y;cA)o-i6|uBx
z(*pr3XUF|^-y-!g5Dm~|liA8y%Q@sZAJ3rvQXxeQ4QyLr-3Ls8a?Mv>S7&{R%sX>c
zr@tZvM<yrN3F`KK>Z+-&t?tZKYp^v8Nq<sUM8k_jw=*>xE`P=Xg5x!2-YGwOaVF(M
z?R*pTdJOQ3!M0FXZul)?C5~_kW@KXg+SZ2}sT5~yZqDsEJ?>~ZIahDnStm0IOa?XJ
z!3AsqtC`w(_h`^^`uE32GY{?>a3<n`9)#Y&-9XpVb9=eV+X#sm1MYnwO~=5%Ak)&~
z<^3I=(L)1qs(SyWuK5WWanss@x9L!Fr-d*u6@y*^9TShk{xE_y$GoEQZ0EmTfHc@F
z!KU<c3^&Lw4+cB(D+()`eH;KHSROY&c=U2J53#KI<?8jA@|cqAGXVjwzO{kkJCPIu
zM)4PieP!D_PdKgSNr)ah_6<dHJ*g@$Ct-IP*0LE~St9-W_J!sYH_$l<zAEe=p4{vt
z>g5<hH-;_^I&#Q)owVEZ?-Ef6xSWCSN%<KA8^bmv=~d@)cNmLq^IJ6OrbkSgU2&44
zqJ{u%RDH#y#d(CXwbB#YBh~Zr>&v?sxCID}prD}UsHC_RCYzwHTru5OuiRe4N~~JI
z6O2zl@GkEN3mZG*g&Uhmzu7Yih>SE?0DwOTlqb&`U&y5jgj)mrT&u@MOlIc7@zx~p
zEKHW@IIkh6a8fzH?~LC2dku<YVBZAsm%mPbFH~Tu8F?;Qs@rt(hQ4=UL5~FAa{h|O
zU(54!&JPeN-wL$Y8V&(S5J)-IcLVu({up@ry=-p%Kl5Y~(Sa&|wq>STqpD<iX-4w%
z6VPo}A5ktY&S2Me`*_>>(NRzeZ&&cK*4%V&3~>tkK`u%dK2HNyv-e)>IN=tI1u`^P
z>by5!{8jT4<QeNTup@<o@HpYEs_n8o02XBXuYfBc0O=gOZD&v0K%yd8+805^p@7;;
z?tKeZ5Noj1ftw<nkCgR5Xb*7ti8271t8uXjEw#>ice0F<ACh!41fP)ojZ}3DA%G5O
z)rtj3f(1D+<m=ZI#dBrttuUVJIS{V2i|u?RKDIScw2nj`dIR>DEMKv^msjidRh`XT
zjMsfKOH<+z`@47VBq>e(oc1{E0URCY{K^F;!T%}?MRoAuj*kAwzr6ChQ@8=f{_}FF
zwU(3eB(yEQ?sqAsqI#5HE+CImU+F_Dq7MLSV7~Pi%je7aB6WrQ4_6lc!Fc4F%|@&Q
zI$GsbVMQ{l3XiF*(VR}Ur{<cRW%wNeo(RYWe(}dRLO088s6SQ)1;eDCCpCv)%b54=
zbsaSE&Bw)dkc*p30T5CY9Cj;NsCV(m`M%TF8gz$N7=8sQv05h=k&Vm32Rdmw|5emN
zIuL-^uH%D#pk-srIphZAiQvWlbKQuLh=)*0rFZY5lAe-MhaMI`wrTB&3%6r;c0Tp<
zyQ8Ua!af9_EuN}sa@dd#1Rz4UUte(|b12ykT#mrp_4?{)s1V?dQcu?g<2^#8Vri81
z!9us-ecQIUxCo|1fS!DD1RU&zrdkRo)Fwm8V-<$qfaSAcuSGH}JS05(xA&TOFf;Rw
zZ3ifVmY07uo;j5mQG0rLTwPs(oX>+P(@X%1ItZy2>g}U-%dxvfz59P(6l*yxHng3Z
ziOH%T!Rmc;tlk-f!;qZ(O-R-t&Ou&ME0`EF3^O(+2C$ctD#J5h-GKa3R@=5V5K<%P
z>=inL*inokBqXU{oI(2x^r~F2x*p2Bx(0*Q1rRP4qmV4<eFLicQk|w+>m8oP<dhT>
zqfa9I1O%}-TU;kwlZpJ~uRjB4A_(C+udgr^-3#<OUrm(tIBo|gU+JuZ4@O4SPCJ^?
zNP3Om>sBNQs{ufBNk%@&PW5l`PY!eigeYBWW_}*K@$Wa+m;dpAd>WxprgAqVLRk1d
z5e2{7c$;1u*nf2!U7{slDJ?HAKVs4B?*ktl2z+_aTW5W#p`pbJQ7-PVX*~~`@Y5F!
z1~rJXJ}BtG{Ta&FJv_V!zLRutOZtLndSAZZ!OS4sq<^|*OZKx|?i#G$a-%ZO@LTxU
zBj=)(4OQ^8oo>(lTG@VaOZ^%9R;MW;qhpc@l*ydrEnR2#32-U7sgSM3T`X-k7n7rT
z6ciN5P1XulUsTjQYHA=A_h!8MwVvr69s2X{l7wOrPfAJKvZgdzm0Ss`;p1<V-h>hc
zmDSbAg9BT8o2-(OiQgZx)y!xYA_=kEI`?9s8!%K%2Qv6wM|0!i2=%E3+RTqk@}+4F
z!XhJqJGusFd(_M3?Ul2^odPVaZV6z@58|+uQ3hmDDUFS4Yip7CF*r4ZD%#pl9zGNf
zyg1%cPU>FdFf=#m`unzY+2e7`-zq5`b_BNV%`}ze=8D-h+HfsQ6lG%Tw}N{DERazi
zDhusCr_Kc1Gj&6KGXNy5`hT7JHc@}X2EuaFcpNu3Cjdm84-^`GAklny7+@Jg^YW+(
zxa1n$Pnn5;eSFRPAaI`%n7sA8FT+E=eFe{l0g9sde;{NbB7hf9SYGqIIS1vhtLsq$
zQ*-Jw6cxPxsL6_GWtu*!@7~qBj;(E{0YpN|`NhR+lmgWM?AKYCx;5bR6!)9F`0r1_
zoje_NdAV>pI?TH$@ruVqYOTxCeZ9TXeY8m8YnHEneoG}XC5fkPGV6AHs!zcjHK8%Z
z&D`}d=p~?$k8jsV(y12SqgH>@_V2;Dz0db{`6d@vnW`}dTgE?z5oaK=F3<1q4x?j@
z()b>V?lT9)s!1(~tt|j~|5@E#dg2p8yyIDzM@GlTN0l@msU*fde$NV6YR!Wf9MtM@
zI)A~9>R1yFh?Cb}-}P>bd`DR%I&`BL2N(ymKyi`<%zxjiu6~?;d>o+cn-#V2>0rjI
z2~UiVzem}}bj88j1k1{mpUB^8ZofAt6i?N=S2ttCEB?`Y^R_e{TGTA6>FKgbVL3q|
zLc&LXUvv^()lXVlFCy9-{90ilD-&qTxTp><U1^5<h;OJuY+3(a#Q-5u%M<l7r8N>R
zo@q^N6y5t}6H9=C9)$e+-n3MnDP6Y)^kSFm*8Og}luxdIT+6Bb^Gy3pCT;5VODF&S
zbW>VOIq&);J|X|U$ug8jYf<oEgXrJO^XXNO03Xdmex3A01pa4~r(wAIJW*3y+4c3g
z*ppBG`S+LJf2NmI5jTKK_n<xsRKIXD3qae)&k;T2kjkd3r)P%DRsDHIfOJ@;kBPa<
z2!-W@_dUGRoXgI^fp}n27Hoh$`{xk2&lqnNkavX=Mnbk(Sd{bpS-VUSt`>nP|A`x|
z>2_Yd663$GD5L|ra*zRAHPA2vWd$4O`0s{UcIV0Q<IYmhSo`zd`SSAM?{whtC}Cz6
z1!S9BuTfm2NFF0b^!s$l;I0yX_D`23m8!<v9*gkOh(~klD@3nQ6s-ukw#+7%r-abr
z6XO4TDJW6dDHD0qC6!7+d4<^-$+3D7SQB>(UN}O6_4o%Sw>z-Ry#6pC6z}(zvyZD5
zMaq|y;i!Hd_>7}lR4RqSf`x<Qs7&BL$<#t+Z2W2bPtS*5MGbBjUcLz(i)w64DXb9o
z5{BpsKhrcoEw}@Y>t#hbu%ZE788d=EU#Q}JqGI-mxdJW~)gKchgMBRhEQ|&y`^&>$
z-fm1-+P4UE_x{(KQISPskaOhuz^0mngA@-Jzzhow3zZ4Aee4eCNZ=Am@(Ocu@@{xc
z)eU}|x_|#DhD<i1B?#&0guiB-cP^~2uddI{tuAhs&3!TnxCoDM9HA1omIX!TAW6);
z#p$k&>Ycw&wGj1#_fk319GesW{zt$6ulw3hfXn>P&;R$7^%QU#%-RHtAK1r0>`!%d
z^-nBtM3eCs^()-(CO%3_Py4gOH$(qbDTZ1B4BlLuo&`YLH^%1~x46}YlX2{h!4fkv
zDBP#O((876bJtf`7^Dow$H$vnS^^6A&zTv^i|WE~QrGfE$K#9RqxC`MrS!T5lYc*?
z{mtLpaz%!Y=TywP_3wJH0XWG}BJ$?yNCD7hr}})B;R{~3hCMNDFK8YS5zP^S#QHtT
zwp&i4?@#~S$bZ=T7Ks%V50_T`{C>wo=nf7JYFzK7fFSjoCbv8g2dnG~_E<irt2Zol
z=3~=EA&J0E^Uft8GgI%~I~QHu`E70+8rX{=5PIo8q0{Wa!NAreddUeu3fmk`*I!HG
z;>OjOJU@IW*3hA2Vrn5HNsEdSlZ>jXgPG<8b%=5|a0?5c0ys0c*&3ZT%&d&12!QL4
zlrr;Yl{+!eL8%dCpHj}Zde+IMKEj#ZRNn|O-*^nR%vYSOyR#MK|E_D)zajpLO(w0!
zKQJi!iEbDf8If&d<=`L=q8o=ZK`4MSti^U4p%2ip`5l940)1l)fae*A<qZ<=v-TCi
zd8|Vmq|4vL_JUgd5CkWIVaHDfCcZ;kJ0)q*z8&~!xdSM}<G+$5!byLY^C+pQIV~<$
z0I?4}$Y$W-`H6)GajUVqoChPj->6lfSXF!`D0usIU`FL0Zp%WRvb!45q|F%sXM&Sw
z6CCwX3vHm@4^Fi|+h*K7b-)HKPzKeS)l9W+>xYeE4VweH-$8ii>w5IAnABnbM+D%n
zvaG7<dM;{UGA16G!RMGl4D#OorKm^jZ_rSJJekm55WV)BzALTCig`y#Nr|LgIYded
zI2oC_3=r+7^Ilb=mp?j0pFP8)ZK<rRO=I^W<X_od5h4IBCe1VUnu=QM?U8bL*+iqb
zy^PEefV};?nkl0Ge&qKJ0JH9DWhHK|=~U6R^XmXehN{TU_FcgyT=*~zoJwm<9`z2O
zR}8qB@)>;kSM|1bELX6ztG26)89*a0*zd$!aNZvFnyDo(y1h=!5J!!TuQ}e&_6JQD
zW2<XfSoztRi>}!eG;g-<=vU+dV4(+Nehmtm&}C(Q_DmnZs6pYGnUwU_8)$iIt;gKf
zK0lswcQ6diuJJr70rWuV*EdJ&LtA4_T>k1JA_lMLn%;0XHuA{u$0a3+oyw8AzdbhH
zo-bi5N_Z(pIuibSN%gT10(Z~8K|x_5ljhmwhB6GmB(X3t!3A)9`1xRI1Q;Qb+1Ar|
zJT>j4&CC$Zu6pyWJ8eb>B87RX<~J)VM!hiwfJO>%oHH1B6gPX>xw-L0YMCG#c+vMd
z##hsDNP<Ql*!|D3)&ZKD;nHa_8_)Q^UI4)Tj><W?sV;y5ZZzsyC%}ya&{f-l2l{Ot
z$oCR(+BQ4k1DG(wuMz7u`&(sgB5ud@Kxzkbx5wi4<g)L^(@0Ub%KA3~$wlLLP3NKy
zwnz{f3TULVt1^i!Qt0oF+OAT91;CSieQ|Pfc!FE+eu^0R6}JtV^nLU5yCC^EL0d(2
zef{RjKDn)}4N#i77D@rG2w;sHH=K(=+aEwm_u6ik1aGgHKATL`9>=z7#yKUEc;6g+
zqm<?tfxnGcW8~s;{!JBb0bN(|A<*fbsA{o0o*v1O1W6$R=SVi7GG4H5jc?XAQTuUr
zKNi48R}+s+0nd9v*1}?Xhu2rC2O1>!LoI<x>mo^=@1wi4MM|5uqMh_>D=rXqX=*Cj
z<i=?y`A^tqk0*rqDH$2Y@3Z!{w-=YUjr4D1X$gok7rnW@13M?sNrZ$*)m`0HQXU0o
zL^EF|O?Hmg>@k|}K|v>^_|ZT_Nm{cJ+_>>IfdF0hrON7p(8D|eN~P%w(8qp$R2ct<
zySECfv+1@(iNP0wB!NKi1b3I<B)Ge~ySqcM0KpdS?(S|O!QI^@xVv>N{{8pvbDlmI
zebL?fIqQmK>058rtWk50ImWFE&>aa4y|7X37Y+;&t;2eom7YJ6@2=|dI_F~$ldjI%
zc4k;;=-AkVy<LT)UD;M<nXUKN^bxvp;Z^GFm3I-WtQiL-8sdN%J)7F<M8v{EL&ce#
zGv8!SvcC9&+-`q7rS-l~u@rRF)>_VqnEbx)&ifl4?rOXp56Bc%nlm$VE{s;ONuSRa
zJAQQM`6DjO?>1H#vS<N5hWjKD5fSsG0`P@kJm%x2f=*$T0Dzd6`A;l%23{1sw1y+K
zxQDHXfJelvJ6vj=8vpIv+Yx}6%wTxo<?W-ZyM{*dP+1=)39Ow8Sz5hD3xT{V(65Zn
zV7xg634VagEq`~9$T4u+oRLyF>_m~d4I%+~!rjIFz4%Hwv~#%mifSN{r`}*^yqMu!
z7(+#l>D^L5aj_zZ2lw)&l=k1@_P&^hKbfiE-jA5i*S!X3U(106_v1TOEY)it|E-M;
zaj>{ZN#lA?TjN*^FT@lWfB>Xw?coR5{UAvp1Oy};#<H;ac(SSK=0hpqvhf(X8V7hr
zK>YAvtgvxB2{m7>d6VQ0gBlmoq?wumq(yuKqw0Nq7iq}JbB1@;^G|=BP1jweh2Nrd
zh0)VJ&~)^6ch5WiH4>@#`#cty$bg6+_KSej19P}GHaJ*TUNb>&OV4t)LiHmG6&>03
zWOAc|Ld==~^3-GrWk<%m`Q_q^>}-7?+*ByzQtf)!-ZfJG3suFl;c&E`7YNZ@M_u{8
zoc+|41c3;!kWbG|WWs=4_tDu;u?MN~H4^j7*=qAYV~u4$^0I!f8;B<g!79njdDoCP
zx5FXgp6`#zithF(X8!)o=fdAh;Rh33v9Ojq2n)A_k|NaT>&YX<$0yg?!U<H-pD@KZ
zCiJXCBO`m5(-cmKp;f%p{l@e`eSjAas#4km`9mNW)G%Vc)N<MiQy6smrl_b`u}BHz
zmO<S@0fa}@vSm-X7N?bpw^{&alqxry-2AL{^5>@;*q~6ncG?HxOzt;l7|eP?u_ehw
z=<*XEL?tA+?1UKUV<R)yGW<M+nAI}M_CQADT6ZNQDQTWpFtmxz9Wzo|PL6RugoVs2
z^922r%k_4DrpUm?)&|Ii3d{rvzF@&i%>jMZfNBH8bAi29b_uon>!|gp@fQJMV+Px!
z`R+cj7B?;pVY)g)NzETWqM8_(%;wm?(H;Z>J*dflx3}#t_xHeN)rTDX<BRRZ=y9as
z&yWyooIOHx(bt&zVn9ZQ@xsW+LK_VQ#qo3!r`PBL=L@|@|39BiSZxp9XDb4%#p%`v
z&e>oJE?pqkIV^;Y#?&sxQJM+A(oB%4<h%`)a^Zhtwz6h!to<%E+;0Cy++~4RFbo-s
zBQ2v)Os2ESbm;5sKOF%`>$-UqKbXm~6(=VZ_UCHsZ0tx$Nq_zb0tO_#e!+@HhbLx)
zn4Za#Gqs{!rYv_B^G#y~{FO+ch0_{KpdppR8ljoAnemUI58S!EwM|xFG$UFg5aF5g
zhJ1nVo>x=<JC^lwr?Z&-63^e*$oS%LtTKbd-*-OuOhi*N?3-|-OHGuaw2AX}@3|{7
zu5_LV9tso+d8zmm0+GZfA=n#9m3(09bo9+mtiRbcBZe5H5-cpvvo|eA<^ys`VyQI?
z7VjXyZ6kXB^%s-%e>DC<LW)T$$;_-Y?r6YauK~465gR8;_-Kd2MF#7WC@yz6LZW;0
z4te`OAcx<TNK<Vx0nrdO@$iV|9l1lNVZf+5HyHBRTJ;N-d$_BVTyowrSI|W-)fnm-
zNKew?d0a$2FfuZlo}0PYUszaN41JGAEOPvic>OnUEGiAC$O<V($LGH;_Iy!$6SXGw
z(`IFKVm^sPJf2jA&EtfU%49nH0U+iy(%;?P!@2p6sVNJjh^)>xN#kt8HRl$ib*8bQ
z08pV$f^s(^?sQm8YEsgwV_)hJue0p<ni2Wg(Z1OBhYv>O$!t~ov-K~U`5Yu9<TY=4
zCw8mc9BXgxT`tS2%hRW_Yq|BLxG6+~kB;(gk$<gQQ1{M~e#`jvL))h?N@KzE>c{g>
zDyiB&w=7nUnc{{zI+QAO)_v7$B!f{=Kadbr5JjY!82JLD8~puiJ}&tg5xmhi7pHoV
z;wMwJuvpAz$Url{zd1WH-r>h;Z{u0&D?Cnna5s8=dBB;4L9Q}UadN_3oQRA?-v)#^
zKtl>=xp1VwfIA;X)q0*e6!uGD4L^s*dUzMi_sXiu$3XBD8|tzC^CO+e1sN*Kusgt}
z8X74rEgte)v2J<N1gyH3afykl%BmzJM1b)R8kFein9*=Eq|$)bgWWA~9b5p;?H4$Y
zyHll_K%!g_0RZL>!Jo6uws425iu)`ThKF1$83Es;#>YuSQ8W{zdVvh_=pWus(y-7f
zDy_bd*jqnqbvDOvGfRHeHZb9T{2=XN4Gs>Dd>=_BU<^d;*6l>xl9I9U{QO7=i5de5
zT0v*3%T!6pU{tX1pfGDU=zaq*3&?jm{d2z5XTML#O2RqYqMk_5B?0d)0XA_bB^317
zPtN8olalO9oX+g<t#)Q=&r$5#O+Uv!lP2UN8=A3=1?2}UXATAhRL!fw1vujeX#!a3
z%|8YBTpDNIHAlt*$`J57W=OL{v&0x#`Aw2dzbi!B$dCxS!uJv8swyjsCD0}?e{X0|
z;U6;Jq1vK<b#PFEPOUC1CZ_!~^oh`;T$7Nu_tz$^bH+9i@%vI@u^B0%A#ur}wE5hE
zQ&9<PR|h+jukPqude*81M`dN31BrcuJblOen|)ofx#1u~xzQI}oTdg033V=0nr%1x
z3nsCIW%V8qtfh!5eMwNrGH1%P*FeQZX#gzWoF7vG-$?TVK!*?*1ZRUTBI3YBvOhqO
z-%7Y=^=lWIpLOBkFTU+WBU&ey+;+(T+xI|HENDwC$BaMD$iM{u3<Xt5C5XC8upa3#
z@}#;m1Pd0{e{aUKuB9-zF|p9cos%IxV)KKW@vIl<&RzwYj~GKOv2quCTIOnEVrp7e
zq*QvVR}nygmCC%U#9hq4JVN>r5RX}<n{*TuY)WvAjP)fFLp7uWpDBEI>Waa})%bL)
ztVqbtPC`V)l)74y@oiR0Y#h7vClqV*m_v`ONBFN`VNbrDqDjII)6w6Q{u!&t_Uz%x
z&Z^>*osS3#Km~^!8L^@}56N%3q;LUSm#-M;m{Yh9ZI26Sa&LjT&k;;vujTJ6;TK5`
z=5t~RjQJVY=ZI%<9PTccTpp`0KeRj;e60lAER$)c$tNbN<dZKz2D|4%Dk&iWv)Ib!
z#Pb-tRp2v9*ao4aF<Fmf1?xi*z_{>RV&c&VW&H!|YIxzAjI`_|f<_DzjRB=8B^Fvz
zMoLb6aZXpZ3Aur}d5($Uo@7^}XPwunBofKRS~ZOMWGtx;1_($kG#|7^n12R_#H#<O
zS8kEotdF~MBv0u!l!{r;g4aB#=i_ZvZ~i)`{BaQ%I;VCJKw{Jj-2j}3-2P(s^1)u<
zwUNwn;6xR8xKC+!_;WaZhK@#_m@YQ4h5CCGiU!=I=xQcQ^cX<?xV<nZ|A>WkebtSZ
z-vHnoN1F@kMV<?Vf$piE2Pl3Nv_v3tyFIRjaRH%v$y&1+1v$C1&BV%3JZ>F@;_&Yb
zjBn4c`i6#RC@3OvDmYmV<Fz4I8y8j8)v(BWB+Y3jHaB*NXJ>?4cDDA$i%t3StOEn$
z6waTiX=qYglirq$Jd9<_-U3+yV7`NbgN23rE*b)H0D=4HM>lBYIz<p|k41yk2NGyy
z^D}z2uo%Owm*s1@hx3S8>Ya0i<+SRc&e&NMSaDitdRP0FfY%3<Yg}?Go>Ab1_I9_0
zlZBOE?S#xsh@>ImvOO$I$F;Pi80sREz`4$5u{E&yz4B|k#L;<Lnte}8^CK{`dRQMD
za;jGxN|}^gON2$7FD@<yrITMB1R(22MVT^IoDbG%gVV7L@Eq~>_Fn%TnVV8IY&^Q&
z^Mjixn@G1yTx-=k+(NAtpZ$RS^*;#9uNqy>3u<)$0$%q67&R(3R*~_aS~W1)a&8YF
zFV%T?w4|hHUs)YCT|VR>?iN(N6-Jf$h>0m>6C0DFZG0?t$lM!tl7h39$ihB4F=21*
zP~=w5ku^5q`H+-kW=leBB1&Y!tEW%4@H%u9Us2Jp!G3!jm>TT?O*b8#H3EDBEM_ak
zyX@@{EG!IteZ$1W_>-codKbIH(do>u%EmJzYv8h3Esc#ehAvtilyY*2qq!G4C)rqu
zn24Ar+7~5uK64$#7l(Y1#dTr5u)|V#ooyVYA+5car@guPsGk`~?@kU~oq&-^?h6BB
zUkv=BfeJE%;Q+|k=&w>cao?XcALTVP+#Id&I$syp8XO-7z64cVi}AX^#Kx{Ty0rq9
z)-1rm`pmaRYL>uq_(sEGBI6ZJTteKDzapsc08^k;v&Vd(8O~%nd29oIE*MZ$Cnj@p
z6KqsW%$v2LR-xwK1)d6H{dTH#R&<3h{6ddKH;G|vo)`Ty{J}A0n9ChI0lf&OMC|@i
zf#ne?DHdRxvw@rmEdpj~g!BkTyz-qSmNgp6{g;}uG9i<}x~rE7m1$`_HaZ|9;sf{?
zn+VOGslq>3qY@)UhqBYeZE#0EZLCso=j1A0XPf_#p6V#G%AX-^PoL2{#ne4s-UX)$
zkP*pNcX{;IjaKWHL>tOISn`ykc2*YbG|K!F*yV_xuu1mH({Y53E?$xwwFKBPY^A&a
zJ!G-7kmp=~flW!io(sQG;u9Al&mEdUk!l2<gwzO3@=8*1;o)!JyVSu<sQo(^Ktr%5
zOr)%-`B>T-GwwQT5_r2eCi(mTR;}J;f2Vpkv+E}ohm%y|WbqgSJ+)@b-4Kv<PFpEv
zSt`1?drl(Q1(IE0AubdeN&@k2;0cGz?Lp7Z9)N2yS%iVt8<fa$SP2T3vcJn54<A5H
zNFtu2r`fx)IoW-DEw8OD4S4=+tpAXq!oo`Ii6l{Q{i9H<Lg#c;mX(#IFB;qRrxU20
zGaIjBprBL&LuMCs;)6#f?Yl1ubU<O5$dfvO?HrN(vD`|!FNO+u-2E!Zc4jCAfnb-#
zLi%j%X#2x1X>py^anN2rm0JSP1#`b_=~(MTV4!oRzfyGj_UoWI03Mz%Gm+t#PxOtg
zp<!2E-rpAip-4C!JRj4@KYhCTy=@CL3@w}KludfNB$B{>_+hmG^sRt?E0DX{URW2F
zY@TmwqMCCsH8T2%$Dr2jLOKx?`VLWVb7$vwF6qN47uO;<^$lv)=@{t9XmVU|px6@(
z%s4J9ebdp29mF9QiE?Xn5R(v2pW?LoI~^y@yWzkbHIe3V53XUX(x?L{C8lr(Uxa{O
zDH)Hc?v7+f4>>ej2HBts(v&&Rztex;`H-FIt+sE14h12s+?3*wdNE0XL4|ocpbPDD
z@hts=s*=<C#IDB^mB<7S8v1AXuS2c!zmfsFVns^L$-IbwaXa9j0>qPXx!mMHzG)!Q
z!!9yGyZyVR%h{gB{`ITV)}&gKi5*p-6bk(0Y#OqoCt3>?PZ~I<>Seo%RhgSl59Wa*
z^7M2apfmA17=!G`<7KKmgg_EtcT%ajCgb~~cbTMonZJVq6rRK1GFvEF>Y8?tPc$l)
z)-J{KzWeyc+_Lp_@mN=IPyZ%|?AOFZy=~V8I*lf$)lnR<+DJ|o|MpErz#v9a_Hf$w
zYCQ|J=O7ShTmwG<cm()+!vO&bQ&9@rQ*iwCU~P3USB2+IEX>bG#F%#69c%`z?=dAx
z=88j;Jeo9QtVC3tKHn2tnq8#miRzJngj;WKAG6u4g|V@Pwgnmv){raB#rDL)jd2&7
zsVM~j>S4cr)gDZnS_;zWi)-sR@uBMT;36*gu8SVWI@na@Zs2ixm<&C1+=YN7?C(w@
zFcLt)r|Rgq#3*>g2KM5x(z-7c<OUcFX)g9gqRHCYhPBqqzN$Lz0fSBMPo%$l+CKw_
zW@;{PE-pd1TMu^^dVQ?n)~QhSThNvmd*9p%0;;Ge1u=6?UY?SqWNo5lZcqxK@l55V
z-!{XAIqb7)DGvE_h57!@idrA9F;|i4?SXDlX)(rbxBImSFw6EbYBIk}mi~ywLhZ+x
zBEG!@DPtBE7U10wwE$R!Dbdl{^SQe_f6sQuNJv;%C@Guj>f$7`ywXIcsQY3cShaW_
z6Z$<@*M(E^0b_OVzTUR4S7dt#lAHLaHt`U`?>Q_Y((GGVd3vPH+tEP)fxOSJp}7t(
zF5d5cM-W5v*vDtkmRZp9Zk7vxb`cS=&>ugpEI&6i0LGN^^`%XInI(Xx(h<^fag5gA
z^(xasab`7J9e~IUF*o<p&>@(l1VDURX@YfnDl_b-ObYPOj2f>Rt*E##SG7MF54Ayq
zhcq>Fg#3KK(rg0la?OAPq%0!?&*>*aD3T164vmlZ(zY2TeQrvk20_<~G|0XW(2!bL
zTVoEF=4Sprhm(~V#pQypEThF6E>$!ZHs)K`P56c-wZzkE8jJMpl%ga;@CB9mepHm4
zi#mK5L{`T551WJ0Sha1JNfRT=rDWD8$fBr=fQycfje$W-Ns2`yb8&;?E+s~}pYLLB
z049scC$(`&Rn@-sbPcO+ca@fi^z;y&4#n-=T~^i^&_X`q@l7)8YP54U0d1~OP*Eh7
zaO)>fEDj8;tS#NzBjkiAN*y(W_N1XsT$xOZ1w@3w5AI4KWIxwrjV^5+Z3hPWL^IE*
z85lSTd=^p7y|sB^m6RV?WK{LWb>Zs)r4t)F<z*Vk&wW7ukexjyOCQPiI>%+mLLHOY
zs?mOny4Y|RWR=XS9=^7xqxLhMTKs}eAq|ypiS8fLiJ8`40u6K;npUr74&Y@6+ze16
zA$cN)>+7WQsili|cP8#~N{tRocn?igRgCoX<SZ;xJu^My>#Ug;W8Bzbc-%-xuLHv*
zjg}7<vjTJR3Az-|L-h3Z1-tmhnj<qalhvC|kh?T&!8u%v_faV!K7q6X^Uoh5(3uQG
zglA`Gqle;SV<q1~@&n7wTF_h$S5`7f<`;I5apuEHU-(ghu8+=6f#@P$ZS8mFbb!OP
zWw9utq4M5+62xg2mxkW`F2&cg<DlFDa`QzO(ng|*!2r^PGSc`xr*w%ak63v#PX$FJ
zCW$R6)UrfSNuRXQJo>{;g(Y#0PmbpOL()O%SF(Ad2b7%!83hyq!r~~Bk~z;w3up_q
z)ClYU=7OFGzmivgqAtk7znNtp-taL)jg4)#*WLK0h>9xpu|b6J=O+a?kSfm>&{GUo
z{_uhZI>LFZPg2*=KmXrW&(I%nG&?devX&WUTCk@1?8C<D9<BELKR7rOn2t|xSmtm4
zbO2uDTn}pv_w+w`t_93L*#En41<e0bP5ysbe*XXGZ)ks<X+(x0DR2*4Bk8fIxqKC~
z=!!yy-~0xD`t4V_z2-}s(jiy#sYU5`(&fX!`0()GMIy+XFS9B2T?Y<`ogei+b((3<
zh&#ZY+{eYTvr|Q4XbkpS4zm7>{E%k)Z;Ht<)4$m$e=+~fGO-K!H)X#;0Gv^u9_j?3
zo&tS%mAv~8Ljazse=}YF_kCP7%qy5Lo>ZFUHus(4;D}PYM6Uo{4Q=&-;5WJ*w6*)-
zd9u+lFcbn-mL&IsQ28n7q-=SZY@`oE5ajbUB_MJ#QEJu5><pQ$w!lF_+2?vZi?^LD
z*0e-oeB7!x6uJJZ+ZATHP{T>uT?D<p<s^P^&0GLhs8GeTxm|U)+}~m`8%f#WHZGJ5
z5U9PtCnB=n*TmYSx!QPWJS>tg%rSLKA(Av;NEFV2en8SA7?!r$B8A=A^Idh%5|!qX
zX_&rj{z^bIKetAhk#`a3JZN@REKwm)o^V~`^0<0%H670b9bMqEhK2*#VXh`?%-I3^
z1rfHx>%o0v2zavzWy$y60rX;-->kxX=pwzfE2!zZJHXQIq})@$WcozexWY5hdgf(m
zoG*KtBYtzSQ~q~~Xl7<cwZ`0XD#w0i%Ia&Q!}-o6XIxyJ>k#e+V!pAlZ0-<w720H;
z!u<|K09Ht@g#k9VwazhwdtH{0vQV|u0({b3mB~uMDG+gI+D`0o(6<CS>_b3YQBg@s
z>S+5njk$yB++?xK<zD*J1r+81XwMaum{@CliiYvm>g#P@ULJ7>X7ABXWvNhhwh*vo
zshHa@&>;-C(V8botTh9+I~a^<r4-F<2~lS^s)zUGX4fNGy77PlS8I`Yzi?UFa((ge
z0<H=JAODyB9dK!ky=xiQO`dZ+m~Sv|6f4juPI#J{me47R2OJJ{wYAfI`2Z(7f}7pW
zh~_Yn*>YfDfV1#i&p@x+wff4*ryZbZ5|T@wur54yj|>&Jd7sM#qWA=6E>2GOc@h-8
zLKC@ChlT1Xj?;A@r~6U1)*|`t?z<${Jur*WGq0gerjEJ<2%)dfy&8+zBIfc(_m9ni
z1ajyI95I6hb@aLTUJImM@PBngSJI^sO1(F}ulCTLQN(v1OL4!|PZM4fD0og8a~IYn
z`Ni!@$jxp3#pMDH&WHU3M#F=!{Cwkg?^Z77?OkhwX$s^S(rvqt9G9$3&CJ9=!7z+_
zV9H?EZpBaKdyV#(!BhovqB*cUqaUvCcvW%(j!<9{^Q#%dc$EqfR+-jjP8GbFtDWlP
z6A)lDU;QV&cRGlcg2MH_Gh~hHp$Z%eA(<d`ly?Fd-y0j^T55dcaZ}s#xm?6S!P(~m
z-S5-cV}91<<t4xa>>a>Jc4C}ye`g;+H9UVzzJ&38NsmJ>&z1zvzosBea@`BB(jtvU
ziA8Z@-CGAwI7u98qgLCg6m{1NpmN{Y`5RT;Wbl%^Klw6}dCx^7JxftnAjE7NA*{Du
zrze%xdh{Z>Q4cJM!=S)xL6>Nd+FAWAj4@s3T*yk=?LI1CC`BZzpE5lBcH^IVKoO`}
z10le8+gJsM+C0S<a{|~AXF^Ay4Gy{r6%|UYUn(gSnxBlvmqf%X$IrGUFzv!3?rH9Q
zFPRtd^?k`=GJdog%%(Y9l3d_5pjvD4f<mFB!K_>BQdlq)cLJ6$@5cCn<_~p>-JVjW
zKcZfm``l#v*RRfKeVyW}F6Vzsum@hVkQHb`gVGTZ^wtOd{>>{G38`8+#|qv)HknAM
z{sXIo!(Mf`R2#;OZNyA6o~O|sI>&^#GeuK{hRbH>^zhv;WM|59q9EH;=4^Y@m$N~A
zzQO*@W%eF(<H)j+nMUSKe%G6Xfla_TEm5mBSnC{kuhj!DD<h-tmK%zL3ccPdSP;Fh
zd?!7m5b)Rtf6rVE>TjQLgMKN9-Cmuq8h_%#1TgH=Xm048J80Yrz2oSkuxv?=kGS5L
zicEFeTbZ7gMf|w7rqj{U0U{6RG6kxy?w#@g!b(3cN^ZQ=+gdl9-ZSEcs;gfPRzknB
zt?@6AEo~Yys4UjFj76w2nb8?;djQI$ww?=)Q#hb+K;CpRU*sLC9ug9K(9fVI{XN8!
zk@p<pS8g(3g_^=r3C@)n+XCs{+wX#**y=4h*-b?XiKcoW=->}HaQ!<Mkdc|O&TcW&
zAig`${AM2xI?`9~!PPn~0jo5625fhAb*Hbl8L|ZUzldHyyqR_%ARmR~Gjc+()Va*^
z5U|C>lIV8Xr>?-k3Nxe=+#OA^n~Qa@j@N7U*}3nWe$~q6md=&6>)kXqh5sXFO8aGd
zw+CVsFP8I$I#25HX+cS`CA@v^by=)Yslb}TZDcZ4BVNv6SC@A0@VcI!0kmbz6zIQ^
z4+NqQm5zrkA&Iq=>Ma@C9kA&34st0F^SXms(-y!|>BtcWmft@sluk}4(c)22aO@Yl
zO*s@svt_&dTB%3;!TiHO!z_3jT|;Oj)i5YuFLh)tG9AfK{>$y!Y6F_%i%0%mz0%nD
z*+4#ns4MWNtE;CCxYq&-@A*H!O3>|FRvM%y3jXw2xd=35DS|z-*~QNDZUs)gS-*a~
zK)w=el(SY_66pVmRzyAv7K$*-k~TJ{s3M>Iz5&B!V7lz&<RoTiM~2MfwzhwHiTC9#
zF7CzZ=_ArVX<SfjXr=KQ@wI}>FCsXYWlM+>KWjACoWFP?VKc-V91<fno)!aB2^$QI
zq4wh4E8tYQ(4rfF5D*XmD)s8nXT8FpC}Qx}>YrBA<i@Eyjr|%`3wR`WpnL|Rmo7jj
zUX`?F)7j4iWI^}M0$cUKCeITRX%QqjfVo2gVFtXAXZvh2uu&TNf#AXRe;cg)&!7|)
z&odZu#jhS79$#AqOsZ%092&)+20#YZXT*r{qd2i`+MS_-71UWN`nN%)GME`L98Z_Z
z-@R{MD6d?sP`_1Nf%p~wixNH6D-dDwUOF_Y+fWFX>hV0-q4BnZHwEEG_GCfFfQL1M
zqRafSbz@^ob$#_K^(O>apA$>ieG_<?J3$GH>`8A(Bk7E?vY(%y%(}0?zW^Vf)f?!y
z@oW?J^!E4n_w+=}6Mv$m1?ux!dE>i3hQqb8Nx<#6lhB7%vUx+qP9fWy($>~CJ*~8(
z3cV0g_WCp-zzrrP4R2fq8t2i@U(;)0f>pq6q=2XzZ_5h_f$fdsiB;-ViI4uyhU_ys
zYDw^$jZ$cYCfRdvbx?>wrEPC-r=z1|RE8cFq>!Fol*>>=*=jB%2*qRCJ$;obZ$RxL
zyG$Cq0!HfD$jFF|_2<}+HtFeiPvIbS9t*I6qE(5?%ge``p^!l8s|qKjbL<<$M>8QI
z@F|P2v56Fiprm)^3ccnwis#RtufOL_Zkaz~0oS;!?~q8vy`;m4NkBmGw4XT%^YQtr
z8Fg>?FFcZKgDLA3`vDcL*VW33HsmP~IYneCf*&BEX?OJj8vHAMeShxEk~jbl{f$i`
zjl;v#Y<D7FfQl47u~Ucf{^Q3y=re7F&!1xphdPX`C_)FJ&&;9GM&Upn`qZ-gtZhbB
zFj6bDJfx9xp4)x;uWw3r$el-Kw<c-(7Y_fza<!kCVYKqEf5H5(<8u}8t6;Wb_mbR1
zJ+!sb$nYtJp!ai&3tY!={@(oE9=7QAY21q!83eqjb_ARZG!$Jr)w4U3Kj}V-BvDZj
zun<s4!hZLef1~5WIt+sRKk)FhXv%eI!wCr~1TW~M)4iV&%NMALewDCjDN1@eQf$FJ
zefY0$swvr0*D@a7@;dYwKSKXuj(T64X13=L9T81&h)+VpP5E1GH0k<PZfH^0=fO%;
zqZbevXFW;gMD;{vSm=JYYzW4U=P(0bq)7L}TdDLCgg5ZT@q;cr5i9M)Cx!5l!@VAC
zYQ2NyQSY_t>lD)>^$N;{6HLj%qm81A^SGgR-{?O+;roZdS1OT`kv&G$Y$ij><_?kN
zRcf?fNO>}N!y<sRlt~OFHHLzg7u^?9Dd+%sgyjNS!SbugG4Z>CKmMjnYlG8%%H@Qo
zL1C|_ZrXbLsfVD=XI`hsOl2_391)sU1(Am))+@aS-CUH{uVUN^U*dav=j8o(YrDL}
z>6vS|DKfjdBfhOC62tr!2jjioL!(jIoV-FP|M!oA=J<`AZF=ypk$(PzOs!J>ce+Q+
z+}c))M*t`iWPfT+qa~ci#zRrqo9u;;l&uW*$PhJ9(2&sZ?$NW;^fBXAknnJ@@X$`5
zu&C^ltDG5;bRJ>KGGwdy+KE2b(_B+sA*tq`$KGnt@>0@zM7zSU!j>u&u&PxDb|MV-
z=+ra+$UmzP_Rc8_|1{H4@hjs)QSUD!#%}+fsoHhddK5<1)gI%S6Y57ooy>0wBt2dF
z`dc4RmCOfmuuxIoVxVFFy|B!23xH;LkKn<L{~|eU#!Ph>4)g6fSx;rv@%wY3v+zX4
zPu~1j+g#Cl1+HIKF>4y^-%@YOkM{ihKDH}8$W;knQ3M$$lnahZT0LZyEdBaEHBwpm
zL^*d#O2={S*`R|%g|_lcjLum2PqVJdyLonRNHtM%zugk9auY2JHwnwqePQzK`1fx!
zgu1Ue#~N!c4&^_vU8GDHL~+`3u*%kZ)>cH+i7a+}8<=f;sZ`OZXMRwxJ@e{|Oy%>#
ziz#Z;$aRSt5&ZhUo(@GZkeJ8~1<n3)T_V!{o>E-&1CtJ=P+lm3*y#-bBuSQF2gLr&
zM$Z?FOBgHM*ByOE!bCtq_`66xB`6T|sn>2O!;doHB-behBeJk{HBK?J#U~IMNAU5i
zXt#g<>P;VRNCsL^Bg1!{Y-043_{TmgC$1Buw*xLTXvGoG&6i|Gcw;Xo+uK9&gMz*%
zf{1mDD87s7gs(S$|Mi>K@ULU2n0hZvC!%CVZ3(3!BMNlP6mA38#gyfhe$2e%z(6=)
zRVO3NgU}pIFTd@AH9arGMt1Hmk9$-e$^Tiz+%?7GaySz1nXBlXgK7Ovpq9-JL)lry
zg=lHET=#`og{Xd?{;hs$pSQz(;g`ApyzalruE_+*5GK@+FYv`RzE?t1FW`xUBVv8g
z9U3#^6DRY;b6`nzSGLK83~apw3we5)s)FPubO_Y;_rCW(OaJUGOhQixCoIuNJu4&D
z*~K4VTpd10I<G7)3}L$d6t+i3G9{fTY=feBo*h+%T^x{K7k4x~#vqD@@(!0$Q+yO9
zP^EWqzLb!;QT>AN+;fv%KfM|+YTtU_p~w1U%(lYzRJZqoma!%?ZP_=?u0IhPMC_v!
zGpQ461oO6ZGuJjn(WlDKO19K{%~sOC&U(j`RXBu@n%^noK)biwf}i3<Xi7J!u}sL-
zkBpFd!VH@~q?qx7kXM2)+J3#Sq;+%<yj%%QP(EnpGuGpzi%2KiW-W2}e(>%4^S(F@
zvaPWjy$(WG$X*8nqIJo9HF+@wHO7yB-oR7I3>2uCU9ISDhaQwyP;H0?&;Jn!NH%vN
zsz^Q-SL$9`;$-}t1fpq=^hnXxPra|j%(8VXCJe&lTSBGqMHRI~iKjvw)i0<bGahF0
zqzoc)T-Ti%%mNEP>&+lT1x%LJIe=Z=Aj@W(j)jC#go1W@F{Npl5`5KSA;&012wJ?b
zmYmVKnriuJ?6)^YHV^TB8|cPAV+>iDc!jL!u79kHe>D(nf|!y?eb8n6*emTVgil^v
zNqz~_w?0kYwMe?5><f8W->P@ZP)Q{iW@v<r7e$-5>KvY>*p-YE(34J<pwS~eS>RI7
z)?l+`@-jj5$kEYQpF<D)G%rVKV3vMXqEQ@Inb11zU}z{`*d1-FudiCwz<;2oUMXt!
z?(IpKZ}v}4fqGy6IN8xk&V(#|_KtV2)zpeH)rFOX#dn^+5DN`}jiE}R@Eeg!;mWQ0
zA+kyyR!VamnOOn(t?J-f-mKgcI-U}s6h(=Ju0CRT4R8@r^Jv3qSQsKrO?5tVc(m?_
z%fgA4Ev~6@7@K-!@y~z7D{5%GT9V`VX2ls?X5_L_@)PmB=;sI#qcYaHYr?OJm>K6e
z>l(3wg-e7Cu~A`0>Y6jj5#i}J1gL>dRXaiudFL$Yk}Mh$67D8n!&7Io;vOS}e`x&z
z5_ox=hS4Nz2F_`F$Ip^70^|1WjP&ifRLio?>+t^4<37!~Mlk1KQq<@oGG`^M8K#rz
zlzF_+8+K#HJ0kp(Jj#+^QoqkJA`9%g5W*$|-&*I@EAQGZwf(`1Fv$i{)L(v&Lzy*3
z=LKc4a_UL8)Rrv?xIZ(j*PCr#KRhk`O$`P7;n4TR#FM#(aVIW&ZMwnzfH}km$im5n
z$?pvUEiCNSMY@ejBg5|Y;9xbI=KIDvLFtnH9>)tl4Lc$g&diMSO0(Quo_pP_;<$*7
z82g6c!n!yemAj4g&Av;>00m{0^I4H5YZVDU8mh`ErC<Iw>n2a+Et1{75(cTO<f%UE
zzvjRQNOvtCc3NO6cCP%r>%OeYF;rn-++SGRcKw>$_>m?*C=yMp{*td`0*RtVGdHN#
z%`QSo<km>I^w+n3e$8XLT$hyI!RkDbtsPlSX5PL6i7Y+kg@(mgZ1Of%u2x?hRS3g>
z4r!Zby$jl9Hx1$5Fn!VZPi)f&K}3-tyE7;MrXViAGPf$j{f+exN=e9-w(d7ebGA2u
z9^3Kt{A;;UXGvpWZMTiD6EA4LzK(+rI@?Q$h|g`}EA)^T*=3!|DoS#bxBn@?%VcOO
zl{i3+5#y?o&o4bQn4p6z+S4yg!mz=!g}M#D|3A#G;l{h?rr<h)I30&3@~9Z*R;BC7
zxQNAc2m)zCi3~T{QZsXtnx(*kkRUV^4$`AfE@+aq2AHZR5gZ~WU%Mz--^X@!vF*I=
zf$h!}P03(-K}lMcqrYy_946=w*ErQipE@WDk*!p770!rRAKz=LEHamaFFscjvNA5-
zswxuXnq6%kqJo?0C?DMPJsBb<qMBpkBF9%M%(JIw>N}?VHI}XiP{y{NKnp`E`D{ZO
z<-gVj{z2?>uSKF{XheMF`YiS%emC}~_MqL@E&%WkwMJIuxw!F-28s!Lg1bRxNQJ9-
zC|#lDCRTTnQZ}4+cZO|VH{EFj$?0L?boeE`zpH0b17@<<dmM~aaLY^qas<-_GKI~W
zQZm6brt>`K=j6Y00d+gpD_xP5a(>3qVdL?uSb-B&;?YidCWT}@4kDlAt9UO>%5BmZ
z2&2S=ZLyzU;+WEYTu=R4j<c0|91aC<8hnTVrJEj?uV|-lwxYn-=6#bXz&w6eGRvZp
z_j%i&kN@=qeu#jj!_0oKSHE`-gpC~;!Aj2rcaET4L5@$T94Akd2L%Nq!~Pr1NOTk7
zL;)JsfrfM;e$|D~`;g@FTU#oW{+@wa*UH<glW?g+xwYXlY{d{-*3AlCBHvM@mKt6C
zFC3J43g<$_bOzG@u?%WI?#X*FBf>;ekW87XfBHZ{#l*j83i3gNWDaohW|Ty0Z;BP1
zV_~`*>!WW4330`vy{GerkIK>*2KVxA^=x0t<j^zfM*RgCcLV_0ZrhW=v|*D-b=4Rg
zSB0m0reU|<{mwZoG*G?;74v=3nJ+P5x4`+dOUVdI&}$TSt+Qh&hssHhmY2~p3b4=Z
z(_tbI$rF5s3oPlKuAceVPMG!`8kOYxA)0X!@rBqS58n~TBiPWbpwUCB=jpjkK9Lx{
z&nmg1&z^O5TkV|u#d-R6`R~wV{V$7Jth@vpVn2xQw4Pvocv@Rs9PLHigEjO63SyQV
z^d+E29s^p;eP+1GK#$nLG#5ADs5WAhp)z*Er>`l9Q8Oal;tx1scsi~L__Xg(f)mtW
z_q7sF!BLXv7id(G?=y)mL<BJ6gkk>cD;OGvc<f79pe*yR6P-N3Qf%)3K6pKU{$hiZ
zhDH)PH@p;$(J{R@c{ZSDi?+V!FC-?~$SEo1z*8{GL^gri<w{X&&co2$L=fG_5Chxr
z1&g8n{{MJ>mdIbt;%cQM?KODw?RVa9QI$3{(O|#;IP_CfTi@I)7>mVv@CPH&G-Sk>
z;Da4q2549tPw5bzS4QaQ^lwp7DPysE9|3>MOVZcZ_oH|YAb}OfJ^eVF$UgY`I@)-#
z2jzPa=t(r}BSI$-Bk^eukBt@Nq=bIa20`q5&>&-@tj&no@r&TD?2-anCc6q6F@i@9
z3-_L%p9kVBD#Z#<`2~IAr^EPm^tu8><JxfTYlyeVGnhMZ35%2hKITL!c8Wd|swjLC
zP~XP?RVw-<*{1(_>K%~RVr6B8%)Na1(%0Wl@x-3bNT_TS1#Flexu89Dqv$L#)v~8=
zV8X)&kl4Qa_zW0SM)43w3PZ2s$knD?%NE$<4fXX^DpB^1Fa&=7LipPZso*Zg2Mn#$
zA9C)t(eA@yJtZ{J2{({Jg7LBqYPa5EC(J5fYX*Ci7rBD`vlvnDc^R_qTIFKq#5L;R
zr$g{oWZF*wpAkKJxL!{K`Rp?^tyiQlJR6XVyk1cP=<s|A7>=NY{s9B?U#P_OKg$~Z
zA1J`Rk%ECKWpg?E@icat1<I8%CnV$lkzDX9!2o;Aa~MxZWMb~qfDyfcX8gW^==t>c
zFIg=7zciBnUzO3VpY!t^e)MH?`)Hyq&`};le+Ca@6&fyw52Yg#G0_go)k-9L!93m|
z;$8Omn$I~R)axy0`@rS*MkgdNJI^9ud}K`1jO+}FYSA|^Xa-fy8P=KF(B^dc!Wd|V
z>B}WF5J;{oQ-W@~QpMVm6Ms;qT6$EvnH$xIWEts-5zFqYRI^oCvZQ(9fvVS_Bj7El
z)|$t9Pnb?Bcz6*B%HE!VoUu$pt?gw>)VLgmQmZio2pQnVB11#0I}nV)3wxwI9!_^X
zXll03^e@n%r)TJrywZ8}esMrhtgzeuo6mWFq1JN`G1JG#Cz_`DelY;lKN1*C?7GZZ
z3Jcz1V2qSXmbOk>*6A(7Y)H1;YA;r7c!E^?WAhbWm@p^-CZ7%HVbtx0&S5g;9bzsu
z$Oi+ixPDgd<=;tpXwcY#rag}Wd2G}EK)4SgB`M;xXZA0k<v39Mp;s%lSO`UTFq+Dd
zH!|vO_X$9|znBAMLKgFxlSx-RuJh>*h&5?y&p;m#au}#olAEaC30gUk@yPkqDs|yj
z9=%8SJ4%>dt5Rj53l8qpg6Ad9)8K|dYq3t6T3X9Ewe#Z@`nFUZvz3mi<fTgwN(I@9
zpy|Wy?}IB4=#?*4aZ^%?E4o``w>%sx%oSs^S^v9PJoi+XNy>eyh^Ff+t&w<?o6m&?
zjd$GaUuK`+qUyES?;#r4rri?ywA0>Id^VlBkB*P7Hv5wbq{t^bhvLrFM~`*ScPDX}
z?S9<enNB{OZ|zLbTMgmV)+<iU);agxAYvioaN+OfM@wZ&?9aZqy?ld=JeDJo%(csR
z(gXT2F}Oel8xAil);pMHXS5s?2$=|Tv&?21%r8L=`f@)kBm~GEmp6gR^5(-fS$_VK
zL^Ab@SOo01=qQy}wcIs_)5bluz;1E*WQ8{~GsB#DZghh}p;Va!Pa)IgoHzsv5tp&8
zIrBz%No=sY-)yAm+N-6xnhvG)ikyU|)|WH)pkW{F5_p!+5*RP9bOgM4Q!JjyXtG#j
zysJ<Q3c8#z6)NVQpsHnap0K_?e)OZvKs*5fb6PSvq(d;2TD@j<c%_3xlDO;7pNWF#
z;YLBwKW6IOACnw;+BLcXimwvlqQz)<G;;*5{mlVRGgyG1$mXzDXQS|Y?82?N!5+x-
zR5(6*<89G&_xF!(CNUXW7%2&P(Jhy-TSyN+{33SWHBy;wl}wGHN~k|91P)T?e<#h4
zEn5$#>qTp5iP>_TPl<V95g8K)a1$L@^-e(DuV#PRgK}Hx9FythY-h2?e)swf+QDKi
z3pKIBSv7&0ZLjyO`*wwT<0UaJo1T=v3X>_b@o1f7DK0Sz3zPu2%miIq6d#7l2;n2J
zzrs@QS$z$`oCqHLRNoOYrRm7Ho%d1(Vr_&taDn%w?6IvqBV>^9<7|t2u1(hG+)kmh
zPcvPRrAMoQN&*7guE7P<$&%Ln7%WU?qffe^&CBZVu(o-D9`!6{0+Yp_%6j)mmgC~1
zlxZLF=;#<xr^-=ZhA8ZXqvSAUjGOsPD7qT0dncu`2v#Zt(%`;zV3^`&w^OAI269|L
zgt5|fXpuJ{blziE3Dg)uqUh*t<@B;Z(Z=C0Vpu$yrzP3cX(GWs5^yfS?5y_eDHJ$2
zLFTqfr6?HdPr6V3O*adzMCm!0PTt$E#f=o0DU@ii>(BlK&_Gs`kU|uxt6;*k6fDUD
z3r?90Wy-^_+uzl?z?TyA%F#Y<`Aw<0^B<;gRz-A$;Y?k`b-I6{py<0F@(B#=ohfa-
zFa)JU=4#mhq!MR`{TTw+Y8AD+aSVpoQYB}TQ~FB187kFU?&EHs1MMXs)VSnw`9d*x
zWW4GO=zk$$a2)-O(5={1VL|~n4gKz}uapqmE+m4{b_^|$k7eGYPaIUep~2t?78-#*
zhav2y-yY<v)=JEvOWMJr{NkiP8m{1HP^3z%thSx9plSxJJ;|j-P9mhaX2-)Q<4PdR
zV>tNmP#%C6E}U6X->X9w$6-I)vmV7}Z=%WS7WcCV4KKI&>-%hE?gzQiLO=^&<ZNWI
zoLs*Oj4YfgnyYaS&{G0r02Km3$I8}JRff+io8>Go69+s?H14NvLI4;mZ9NA*HnVBo
z_o|Gh2{9?heZTkxBSXy>8{}6Zlf|NLp^JbRZB#uw-vv55-LEI~3MXdEd0iEY@vjq>
z#8P(V6$f1Hb}`Y>YYmrLQa2yn_O1etQHU2k57lkrs#q28>P19L3Fmf3>t#VD&hc=e
z)@B2<xb%zx^4suad>evSZ8T!`J6iGgpHA#AaaU`1uONs0arf#0Z)OAh{YedpN&_|B
zh_<86R>0oIWI4-s(H0~hs!pdn={PbX4LSy+XMi-)WP|-K*t!6vf%y9L!Sw)gNxOxK
z$(%>yc`(y>*>%m`m#V1F+T<{xqVJ5hkzl|36L#&WkGfd1bg^Wi5zuL<R-%5(x6-IC
zmO9dy;|f=ErO-;Z1o!CeO;(#0Dh!;SoPf5Eld(HZ{Do280m#xrxTPU8oCf>q4&deX
z$w2oZX5E@~>tN5v`;$I@a&X(*u%JhQ+Ifbe%dQYS>j^7if!;c^&TVELK;D<*0^Lal
z&S6168+5MpXX8NV2w1|daae!_m^?8N{r&s-w3fAFht0H4&d7+bBYyO{BQ6cyN{><t
zvspCi7hQbfh;P*mc(ds4Ilp)hNBC-YK3`YKDDM`3L|XcC-q}?uoIu?KlyY}_4spc9
zqCSbqd{p!w&C~YT(sWV=-7y?WB3>Jd%Mz?}Ga<Kn-?J3ohpV&fs7zgzwpjD2fDXaB
z)0)I;7Xf>dsRG$TuoZexVv$*^0#3;&S}L7uC;}g!0Eg9~y0o-(D3#gF>aRDmt>*`~
zx!f65QAWEp<`9jZHYP=NvUhPcek@B)9Yb$CqoYZH37<dPYM*@Jl-WX!`o+<JZdW(b
zRE+sd#UGOER8a#K^G<B4HYh8n35fG$Bn|K{T)Oc&)!oHAHeBm9v)OYv@CyU#O8{=2
zBD+iltT5H%Avi^xoH*>wZ_Hl5U+Gy1_bx1LYEle4nC%_}s-gjcb&8W?X7lS;B#sQ`
z3;)gqjF*V-1~+_pkPq<nJ=<HPA|?I1+|K*?Yl}NQF}Qbk@b|JXUPHzh3c+XtHa51z
z?hO1V!SvL?V!jx$&V<7`b}}C{PHX~dks4?#F``{9=qqipsmoF{RO|455sI|QZr>!;
z$HxdxE~BIyKYib$AUjizrn|dRHOmaD<rqiG4v@2}1ATUtW9xDi{nWKC$vpZ*_QPBN
z<X*zTi6(5`{L?cfGd8NPrPb<jP`r*QDx}bwVq>5;`|+Bx$5BsfI=o%QB|D<3@NnBI
z*KV^-7Oz2nZpnQI5ZC$!qttf_+-isFYj?*>_C-pgY!%P;$3*9}(%mv0id7B-!O^rx
zo3|^KB$-N{2@aVRN%>pIPRW^w?Zk%;HP;EE;p=E*V%)**Zo81Z(fmxerLQk;q1p&-
zqEJ8*{dM(q;e>%=C_G1fZX+67CTPJh{{%oOHM4^A+^hXL>TCD>2@`iv|4(GJ7|&3y
z1acoD6|$WNwUxFuRn!e86K8wrO$NX6$#vn7iCxY%HSSZBonNtG-Sj*J{=5-9tr`wr
z{`nK(b-Ub5(Nf*<mS1ac8=`K>gbBAXQj)|la9FWfmdd!rpB?**oRYFK404@3AiQuY
zXw+Jm%fnXe0^SGMuM7tsJZ4U~0Sj#=Pud57gSya6fm^`h2-qCZT;}3pr|7C4*q?vT
zNJBmw>!#<MnFvPBGZGG&jk)x%1TALB`vzwYnaVXk93*05TyE>tM-8WX`93r#3Yo35
z9(g+YlmCDwC`!u8jxr@l4rZ&_yUkiQ3n*v~X0w03F<JTk1p-Lj!nzygh**qur;~{W
z{SO+?e=N9O^op`3<_eQr&t%8GgiB3_jVUC!*qPv@`0?shd}c-li2lf_5`Jn3{uKr?
z`e0w5o?80iQV+bJQzst=H;z^aX1xlxY=-p1Qf7Z;>6VnP&1iar>`cgG2uYm}-(R|M
zIv4EqK$&KyBdbfGT0L8B%xTw6q{4E?oVee;?G6oRBGXxfQw&7S6tr!X^DG}9-YJOm
z7fjqndcyLfJKp=)Z7<cv4w$IdIR#QyYp)SI_Xu6*0EZVU-D)N<9nvVDLR{6ENmpnx
zWP9Fq3MT}Une?{8ekZA*$7cO#1hN_N8;}gh4SD}~ijiWXd_czr*!QGff$H*ryUhId
z0tzH&n^_nrOnVMJ_vSp8SKtm_|3g|F_aiuP1eSi3A=pAb=JeVND9ZJA0UIo0u{-=B
z9neJ=e`|}(L^qOKK)+zu5tp{?S>;tZw<l10MNCYtf+Zv>=~&va@i8(cy_cAaOM<=#
zg(Q;2e6h*#&>N@Gp?9-bwN-oSfD@V1s<dd*h*5x_KPM+gxYzcN)ezTUwRpkBkYuSC
zab&r{z)RtKBs{9k)cN#|fZ$N<FKL!bT%4e3q}=q0n1;<}rvzz?uWXf+kifB?*!a&K
zKRqZ*F+*da0n(b4lU=%0XMB|QjE-)Ef6Mu{85s~`q?%Q#J-JVP+pj;d0eBR&%Sm3m
zo)QhtF{Sn)Q86jZx|^2(NO4#lEiby?CNi04h@fF%fw~p7_Y@#G;zmj&aTr&#=~UmG
z?~rQ(Vx*=!!}atrN`<XO!wMU3gy3-x*Ep<>jt-#dOZ67)Bw1WJ0CXtmwNYTIATY7I
zc5}YHP#TswcJ@cq<8dYTx*~S6NSy^t5&CM61z<$^hmXJh(mNZ^rkk*h&FU!pPWMOX
z&26fh&T2Y}g}Q$Im`S{Gb*EkpQ2t}yo<7d*Q&i*HlNnNjCd)|C*#LK2GhfRkdwX$T
zXJc=`eKl6oI3m1}$@FpbM)Po@GLfP&KR*1^VGkJ@Nu=yNi@|Lu4sP%xm}j%C%ypNQ
z)ZTx>MPZFPwk;NHOerLVg^!hZ)eX6-fhfl%SJNNMR+<S|HykahE9a5U0aZet`umvj
zKQ%6*LV4N_4wXdL5nWjzno?_)%eaQ7*l_I7wHw)?1_PDC#M_d=o}PQ%8G3nGC=|V~
zx1V#E`p9|~i?D--x%2l01?QR^6SaBj9=p}@I`?T>QIXjUuCs8{24?=gbI<m?V1uMg
zs4mE<=ZfztoTS9YvUvQ8Ejd^ZBPMdEU$G5iC5nzbq@cMpF9c}s(n3A@G*!((q6T`7
zZ}NUhXHslOe;h6iLlfGc^VItF8}J3OtJwjpbel{%Y`xmSibuu9c9Y&3Ea6u}M9v*b
zpo$3UPl6=eTxVI%pHdE_7Akl?Y$zVO(H^vIlN<|Mo!*Xa^v*;T$@guRu<B;wP(9N}
zq<Byx8u6bn8SA{<pW*$M3Ib}+6cVmj)DVPlH`XusQE5|2IN)MmN7rrI*9vI&s&M}$
zC~26NAM5oo)8O73yVr~KP&pFKsnpIid$bgdb!YT|^4&<1OSsTJew;4e<)<$L$D`7g
zWPDA*i_Q{GR}v4pZN1k_VH^O<k>1(@IxJ9Q{@nNttKQ^XC9qAeZK7BnunzGF2&iK2
zkh!nVv~)6<x60Q@Iwj*s=S~;qodLn7#J=-)lF9SyzKlQbN$N>Vp^IGb{(7qy9O}>p
zSo#EOPTz06c&R^^a^H%s;jupeAkB65WAi&BB(upgJe=}ZaIeG@=|o#9_ImpJDb2GG
ziqvbrvhKFjD=tHC0r_{3z+QG=1p8v8^(4>%J2}33E!-6fbW8X(3@S6l6+Aq=nR(Am
zCM+7SJHx|U+0_mK7n!K_{`0BjOog}xqz@Gp)z{C@zO`<*;)7>H=^f<R{pH?bqG5T{
z!=x)%<HzOY6;Wu%2-w3k{Zs<Rb2-s&RS0ej`Uy?I{+qr#-nz<c#;yOaY3q%_$pNP;
zpkptDhlkJ4tC_!h&EC0am3)$2N-Q}xnwmdm*wd%G<C*HJU~1<)lkGD$I`#+}85bqr
ztP{nnxCr>8T{2oO7HKXmmhcn)!)^nd(A{sRita@<-h0fLF+1b2uJ#%;7!)#`^LSc=
zwx^iVFV^(Vy;bo`1NY?;#R+8j#yx{3rYB!Za_M>%7Hqf74?SoPeg{UDHg8WG+e9%i
z;K)ydK$uxtlGb{=V=|Lb-@_>RzIG{=I#LmUql3m>By*X8gx3JaK*&XUFM3Tadn*oG
zt_x0JXLL_2od#ylw=uR=Voy&juWoirk}ub|aT7@&t6-6LxNR>k1w)BB?+>>?!NM4c
zu@9+#Xb3Q%cwv!2h7raq7Mjhz6fV%IRG~=GFec1$T5rEazdPwW;Z_voSPv@s)zP6+
zYXUBjVt$O`b9<!QK~`z&g5z@9@3#;QAR=md)?Ek)mK)^;Gc~!XZgLr^oUWH3(D(G|
z(f9UuP~#L;6WB%=5wo*zh3WUnj*YI*8H?{TqT3&Qe5<8Wxmn72d$GB`j)~ykV86p?
zK5BH7=AC`{Ow$@oG=+J&;6M&CLQwh|8CkPjM<3{5h!kYDtMlpcJ+^?Z=D(XQ5%g|z
z1G>3Dg~elyxa(`x43rvv9v#~iRg4?Icb$vtX$R=c0O5cp1k>2l{7|5Oy3nA(SmvpD
z`B1+zUSfZlT<gj0nDWw7Wt~J;wZ@FjteXhPY+Gv@4*2@2TH@ZW-KB=%ibIA6nx~v+
zX4x&8okMMjAQ<&{QSgwE`jZpw6Uf=lRS(L<YT-nQylnkN<sAC<T%#gL?HRbU0R5^=
zmGKYQr~ssmnU=K3xbEPCfnWaM&yaHVqRp9@ghlciXt*vOqmYQ0Oet`^m%(OrVPqwe
z*U53Q-|0-*e&z|$AR@vE{_#&(P!PGhL~(F7XdVS*>T0fKQ9$|9W8lDNm=b}6;sl2V
zQ9Bgi3c(O+GLW#45VHw5h?3d%u80Z?NB2|E(|?N&eyL<^Yzz)9aB#6TEEScN`jO9H
zyjWY+5goeKyX;lynGJG~D>W}G$~x0k6tHn4I*alyE29k)eso>i=M6v-O<*+`7YY-u
zu-w3N)ACviMs4&1SM#OTcW19C1?G*{Qa+%PeGxRDuG$_OYKijhqrqac;?XqE@=XWK
z?a^7|MVHeMoY`7g=(|d{soFALe+GnM)kbD>lL@geHjLYic$@e2F7_ZdM1|HDn#@iW
z;}$;)#%_{Il@z=w%?1z?yq3~o(WDxHC-BVD5R{pGD-_u?-Dns_;jg**XRrqPI#tHc
zFTKbC=`@O8K)_(MeC<S2i$`l8WP2vXj_gbCz-xw~TCaIJAlm~TQf$qyl&YZ73q1bM
zw$c0-%Zx(@;D2w=5Ojp8Kd=GvY~p|c=K!_mwE2#kA!E0vz?iYXmX%i|8y*g;jb2|&
zv0!NLBd)jzn*$};cDFQ!5U|Hl*a|&5DoeosoG$R~`(0R*$wbjagMFb&wF#Nr&vuJi
z3Ya4j)_P|sN@R;kO-<d>t41Tgi_B7LmjGPc<Tb(|wc3MHO*Cp?TXPJ&7$&X@<qH*F
zz@A}!N%IUq!XXTn+xq_BiM2@3bh{Uqae6cn&5(RMIcfL1v5yNM5nutHyz|Lyh+mLi
z>F3Yj4Bi-@DH_p2fal^*HuZ@6Z|%KjR8xEOEsA;o6%`9bx&=hKf*?o<h=3FU=^d3W
zO+#-1j|C~x1JY4II!KdF0F^3TKspMc*H8n2ycNzl_dmuP?|r!6?uWa-IMnQ&oxOi$
ztvTnK>-Ne_GCjXZHM^LYK0dO%yu8+D?-T>FC9M7>x)x{wY1%_xqAMOqzaKwT@@mmj
zg3~FQEy3TkPZHU6*YeXk^O<!wu4zi&yLa#Y{kJ`mgF9eJU9+{j;I+N1d64%o^^Ka;
z+Kxrc>Aocd@_)wh?r&D(*mfD{ULqqSGo@p3IcA+Mh(lal95Mbe;iitcd0LXK8J}V8
z9|RG<GTm-SqYB+ZMupT6gW#B+j)1wK{vA>dGO`WnhM3^s;D&~y3}=oXk6M-c$n&~*
zrk3;AvG#N4&Up?;#*5fT&pyQmB4`79bF4x$l2Jv_&_jvT)i)*Z+#~PuJpfbx=_v>-
zfmQ`LRaRFUxu^>J_KIy++Fic<0W`u&l<ZFK>v?74o(n9mg*+C!6<AR_GW%Kxb`q6%
zC>d9OZ6{)=q@*MxQ%fRBsi~=`G*^=r7Z-DLdE?s|FItDZdzUvvIc8yQKIS%ljEbI5
z<9hs&{XO5+dN05Sl}M!~q#GjL1iGQ20dRLdlYpS0)B+yUu(#^2$j6Ug+<R37R$oW8
zw13rjb+(s{R9bbKye{r8f1c`y*{^g+ypx>`YgKkDFNu30n?Uf=wY6N}WUmp7fB9!}
zQnA4MoAs^MWppBM)gAnl;^0zt&wiovU{~9la1->)#S&mWTF+?haKdYX!><!NHI<ge
zK8%)RXTQbIuUa3&&Kw2j4q2A9IK(6taCa-Pg|bO{sz62X-HNnNpIXll%n2DM9jxyj
zuUqMQbr$Algg!4_z(aFz=ec`bD_SKWyh!kL>)8uThGL=DjEdY_-ZM3x7uHHh3p4e>
z%V7?Dv}r$3|F6Xk-O|0%*AgjG#mCDlAt<Qv0SOP!+{%jKbYuCByXm%nsa5BgvcHM^
zD34=6aPZFK<?RP?w{)~$NRdVc8QH<z1$Cnyo?@}L8`(<D4%8=4M$2BJY{<~o6BHC|
z8gmw!L({kL*WjZK!2p8ha5#~X)q=UnlVW{%%w}e0wAuGnRDxS*CT4pjVTQ=d$kZpg
zjYD;Y6nViAxW7tnj|s?p#(Dj-Hj^dahdxW!o84}i1O-jTzSO?I&})3=6>|s_4P%dW
z9xPOhM-x6x91HR_CJ@$%+Ne-S0pOVM@i<dKVeu9{`>nauidHCA<z`_aQWWXrG*x%K
zz~GDbcj(xXIw5pHD*n2-KK?f99_cI)qW@kj=j4@;xN$>WhVqAHG4mOh-7fcTFtz+J
zVde<G3+MRnjR^p0RcJu<PF}NI=;jO6=HE9MgOS!#WLyGxn*#!@D?B^D0uj3W2QGy;
zQr!gUaD+q>fMLP2V3R(eTY1I*s>GGM6eY)|XdSD6uL!^7ZdWd-&L&(uB>Kqe;$fS%
z7s+X%Im^hHogxG?d+5Rm0N}M=x5uvUgNHjU_jg#vEc|(VNwtx1tTI-OCM~JRg9$o~
zGZ(zyG3<?&dJWn~r3S=p1SbE27T&~XQy4@v0*BKAa;9sXoK2Qx<P>qB34n7%MfJ{v
zF@HL_^=h;I_BgAGidN=5C=E=wY4!=H{O`{w06D*AM@Iv#vx>O%P(61UFi+RDD!(g7
zU&q}0_eRcCjhcidJE~J;o6aRLUlLP6er_ENyn#UYuKnRSiFRm-80Y@Awa!eNLb`9V
z)i>4E5>-Xe!b!K|D<xQ)o?(;XP1dgQ+ywl~WlSG(oLv3l2lBmb0+^I)C0B!#!GvVT
zb5NWxzsP4;$t%=LHCmS}Tj^S3J@qyxPh??IO(HK_RbGA?&}-nGG6|<Z^-Vg)J_swW
zyKLr^Y-~KAlv*B3)qVNqL8Z%z%k#3Nck#E_B&Leil2xyRzGQ~fKh|fn4@S!RJKPbz
zGHy4X21w^M(SHgR*v3kpj~1o|XeT`saqQoSHgu@8S$vnB-EO*Cj3X_kq+{i?Xm1#<
zZ<Z^S);E9A^?4}0si((y?f&xVED?v19T>1R%asd}k&(2m(&8%7I7&U`s1-%)&52{%
z19_SX8r>gc{jZC*Cu5}XBqI(u{OI*~>EJp2^;ewAH7pYqJwGF?76zV`^^eL4xX0sQ
zev7lf5UVFL228zNRykstPbtUnu?bEU@fm)(o)FM-xz4f-J2R70Tw)6ljn@|Ucw`s%
zl|Mg^9g#N`*Qi%?tz|xXD6}Dcn@NiBICM(Ustu2h-fB(_RUSIe$au#Ccbo0q-e*Tl
z?P<na*1exL-``B-R3&IV$%S4Nvi{WLuEU8DpSThNTtA;YdGe>e0aR&b(+s?;)ET2@
zmbktG#*M1?Ge1md+4xH%{#_zWV1!~vtvC8Crims#``|4mxO%X+vN1oHI(zE8ndJHp
z&DK~q@BQ|&lU5)5(8Ysx^Sp_o&+p=szG<H~XsLT}d;E*j4FBLz_&~7wv+M-f6rTU)
zX&3S=TPYhaSa}Lrg`B$YENs3y5n)+{`r#t{RFr#;fLj+}jXW@_m=9NAt8$)QwQM)s
zTI`!y_FCSDrB{xJ&1ZkJ?5aYD=j?9<3wMCuiTf*5vivO9f}lOv&KhTu1ZvT}Fqvn3
zzbP5T==Aj$zcIf<PswXu+|S<5gBy+}io+f|tLOBcFbButMQjJZ82dl|TCjucNrS#w
z+7+!Vk5~{U40A1|R|~==oL7K#fRfbR;8;ORtrL02p|S=OFQjQAS?Lyu!1@eDIhNTO
zB)dN%xn%FoUZsW**B!v`ujE4{c7o#N??$FZ!p7u?546}DtI(!k=i+I@Och-7;kPZ{
z%NGw!<R<ErhGsrYt;Bt475l65d<yABlV#pWrqFAP;p=Q}j(Slq%g<%;1zx7UPzI@C
zh}}UIhZzcWpe#^>n|sx1WCku8%Y((+RV&j6m9qnC2$q#32WC<CN8lU>yG1lZeubsh
z)2G=YsGQzvHWXnxUXcZw4DF0$BzZR0bPP~rC`Q&Y3O}79ns`7SUDa7_*3{8fP_D6e
z=L*CtVqzXkLoTFB)TJ`hz5LUb4-H(z^5#eM#ZZ6Bagu!bJs)!zgsc#IKQy5?lHGXz
z(wlej64OxvJyp7D3_E|?6p5Z&b4{#1zl5{w<3(_lxYjmGW5J)2SHOw0kM0B&b^NV4
zr|mmFYin!tZZ(+-q07_~JJ03}--EbgvFO7)Mq$G2<eFSY2!oJ;)DvhA(G=q0>!#gt
zxr-Jmxk-<!TAJ#!_s>_Wo!U7iFQ6S!w3HR}L#cG0^R6eSFK<+d71UNP0Eg+_ddijk
zFH-|-(;XhOA1HxZJ<zLMtp9U25FDy+nmL4N*KA>Q>G%j9TZ^%7qaIcDj{sfu-JSFG
z(9-u@$a4euSDJVLbn3hS=7%p9O~1Fbz_YFvE4Z{=wc?bl-%!frSgqKTLvfl>0{?BY
zh{F_hbM1?v<B8+P^<a~ORWP0VAwK@>ZtZU9U)rz+sE5oxjjo1fMUJDD81qL_#k#o>
z!3>g0Jv;%IlHGB!%aXez&u1istUA67FWDQEv2NFUedot@7&>mvjy-r%G`vz?rO;Wc
zCb_?eqxEgwVRF29wMh>B6gS0%GXd3%YT_MFm584jIozTiI4$fkP7<jBhqRbAt%tYP
zG3AAQr4sA0MZ0LHG$B*fUG7`AoG0oICZ!0{cRB0{ujx%LUbwLC3vNK^ZPB!JbV{hH
zS{O@D;qiV_#f$LrsxUb{jOjRcF1!G<Hr)utjf&67>6~T`RvY6TTk2-J2Ws(+3q#HQ
zc?R!l)*6YmtACn6C<9wEEOxNy-fvWnK(6zZaj@Qr3Jbg8)c7+_*!Jl<HDJ#V;`^y3
z39}_Oz2YXne!pSL*G1n|W@_tw)wRuXgXA?jb{n`Z&ygf^6?*tU+&SHSAVzgH@(Pa}
z+Z8a_Sa=(rYN6YfZ1}|?QN*Vaup(C9#c-bdi>R68G9N+I-%VF=)RV92O;PLcViC6;
z2L%rxRgM=bwhCP)dSSmqf|@)2xiIaW(b`PwKINHPnWn_RHva<s;(i|uBFYD<-^|4`
zI^U;zPl)>bGZ59!xSICY-FZH8?onTE>{%8TA04XJEnb72^=0E>1mpGxo|>LhjH1$F
zhO72NC0Vn76Fm;ZbUo86<~}i%z5s%tQeHJ-rvmvC+<9@z0-m|Q1De>tOUSn=gg#%d
z_AXPg=O$wwV>cyR^^8)%t*Z(qLf$(Tf}gFspJ?lslyv7~R7W_}n4fQ=1#f&EM5zne
zZZWqEL1avMX4bUl@1_tI%;r{A$wn&{t83E7t!?Z%7xpoTu)FXCZX#T*0^2VRrkdtL
z6nBW>QBPW<Y;e%m=c`1cvdOd&K4P-Tr>8$ub>wi)U8fFpZ?3{ovDD;wu`AKiuv|zz
z&CVh|eN!<aNW^}~JvcZZARr_#;su};wq`v-f;vDwAKTyEJbm&c?ma?O)V(LIa|VT&
z*=1_9Hbd!`tBZLtuNb9$kDdM1eG_T++$IhK?tjUDX-CMmCkPJ<YcymbqWLvLbY5Lm
zHh6}|(Vmy^2#(q$EH3`U7!Qlc(c^zNB?pE?x!=!u2zZ#Gb~cx0M$VPI<3tC9XdmYi
z<^F{S#}9Aa<k1aAbl)}a?m%d2rz(~$wFDANxzvwE&24SNB{u7(3j=Hjl!R<V#*g4{
z-@bCR8^M<O1i=9@HJ@ZnmqF&f$42u*`xJ;OvrnC2mB>s`(;{p;b<!tRK6#z`QAa}~
z!tU|r{FtwU@k4`2nXiMoaXC79aXA+}O)p9gb$9o{RAm*b@fU_R35%mSGhy{H_am-T
zew_Uq#wwrd>mm1mOB^;z63$S_-=8<Eq-Q?tcVxfw;-jT;jPLhk;M+XIy?7c>K6_wR
z(9FNP)`V}pJ$3dvf>a#~$Li74ZtGHRHgY`xn0TxvikxQhzkKgY<$7&y0x|k{@27SM
zsCZo|Lg}ose@J?yC!pjXPs*Qe6ZFMFz4xP@v;w7Ad+_r^GeCdaJ}ZESp-)$iw`>Df
zK&E*LxGlgQ*z2PaRZNj!9;9pH@*SEU={rLwuWg#Dj?pSLd;4{|cFCi>x@?B5TZ_+g
zvr#pkmoHzgsHn&`2W4$I*#fT3pEO%D-gOUAci@-30v@0pwf?QyOkrl<;JW_I8OsV~
zpw)Q*R#LN#K-#WPt`~91$Yrw`dcY~G2<=2DgT~3Q*z&Hq79>qk^^c&-R9d!QX7h1-
zX~A$X0Z4v+0KSCw6UCj4^oiWhBceGH?G-k$I?Jf-9PRDLp2)sF-MDs3`*OE}r0*S0
zqnWlrr$0|k(24uz^-h8(fRVXI`_$CbA06y$n#whFk_nfU`sPqh!OuL+46`OG=mW}0
zJn%o&orDmT!w0KTzmWPbicc8{E#V1*+*h&V%8RyS9$gcs_O}|-2{)bk$7;NCw1Y7C
zPw`Wo2wei#9Qsr>zR`BTWG}RQey32g#x|yEJ0G@V>toQ$5o0&oCHP|{Q<s*7CC?>H
z3(Kv3tj(YHn|!jAO4;ah-R>-1ljry@Wq;@8kt~2B0FzjMKLkPclYuPqln6^`{+iQ#
zB@Yw^Mk81Frh;1a;{L+|d|(*NtH79^Y2TZh&nbwqk0i@69hW*Ewv2f82!<KDb7$l1
z?1g`7$jPefGLA&QlB)6Cj(B0yYf007$p{`XvH5Cf&3cE|oDIX!d!P-jt@P#SV&=1X
zBrQ!`cYpiI#h;CS=<Qui=akEPIs3hc{VrtG#Qo6pp=4u$W$qOKK`GBLtKU&yX4LER
z(b>;<J}G}*mCMRg*sL-4V}YS#l@Je)q2)!%`Js<NZp%Lle@Wyk(>L9L#ucA@EZmF*
z<~5uT{QUgRu<(byIL*}dGvlC4lR2@}w)4u*A!=0@*X3pLzWo9Ux_@&xsuJcjYv~C-
zB5I2vfYyA!Z2b95VVaqo)&0(9_xV^WDk>`3yLTHyYGjxgXle88(F!V&@$q|`1Ex7A
zt9Ive(8X12YK^}0H*NYC#Yo!|l|c1upcci(3LERPd)UV`JG!9nW(SbUu-<sK+8mzh
zT}CY#RYeiK;(2!9NmfEaLPRA3G~Mygt5WdUQt1Fq;t(`6^(8LYgoekQu5nH)?oZlk
zzE6F7%zYmwy`+5Y>iEpUKn~}zoIu00%<n-l>>MmPh8e15K~*N6b7x(4=U&xL`X`oO
z_%9S%*v$sF61+Sx7Hr-VDD0xkUeWIuwIqo?^brnD&d&Yc{-}Kl!rC4iZYHm63>=VC
zAIuMzm5F@48Y%_T><mNnE8EF8@2(cG7~6d<EOr@4EVErYV(PtSp_sC@GG4&U!p9Qc
z?zKB-WnOMSECQi$uVn~;6V3$A^I!9JoUklzBQ<vTlS@4JS+~bw%kOC`up6x`1)rMQ
zS#pdXq^JtX7W5|WA8_x&ud*oisv-EoPUWO|eCmA9u>#gRE=zhbuxlVTCXT5|;@zFB
z5Km5=5O%13{G*(DJmxoWhpnvqm0utUP`ya(-ZYc9JuLx*!P=sb+NjR}iy$b+Harjq
zX|2*9>uh?hn(IQ>Ye9YljS>6c_eBZdm(R}9{kvmVOC!&wc5A7Jt;`3HEU@})JXZ8I
z@mX?Fe9P*yxYm^HUIc<surXPi%<wFR{Assyy>rxk@^ro&EIw{nbWCT`{wTyKSTwL&
z;o+Bm-v<LmdQ%nXuN;*v&8F9??=$z3daTA3dWiPt`mCkLU}@>;XXa_D6(buV%&PM_
zfEA%;Z8wKBngpomTa`sb*+oV9B#q-eH??)8R_lDSHJTqsytKG=vF+R=Vf&#pm?I{>
zXFvR<abB5A;hu1D)F7RJ$rUfXt@X@@1E2*R@rn56XVx@!=}2^SiATv=k-tJ{g^aD&
z?C)JB$2h6YVd^p80f(}Tw6t<M{6fJdgxhbqi($8vd`7GpS~a%{x;q}8DBv%RXZSC`
zmi==PYd4kdJq;0bvLMzl55XJo2$UjE4~+{3f+~OPqe8qq(-V&L`m<FNcg#Zjv$5`(
zMz9s8=|WU*-T!0GYV+1tjb;U3{P%B$jum288rH&O_-Z09S#HeQ&g|dNEusj;LtB99
z)aPtpY$j(NMxGQ}&uN1<DB{3+q-v#hDRr^n`qB+@a>^X!+;B!HP6SxDq_{Z9dA_Ir
zuq-v0@!qaEWhCYOe$jhdk^D9J)q<Mk&D&$G9UZQ64>82TjqDr+x}`PatB<WQ2Qfe5
zgcXkR+J{5!h+>Mov71k~Wm5XDN|*Tl$I-kTFS2my^)Ce;9yF;hcg&MbFry<Ez6z1V
zZob!I?>~L2q^|x9S`^_5L1DACIK;Q|;qhbW#ADNww#JZ}Yz7?bHI_V6Ol{7K4{nO9
z&v#ZIpZLsp+W|T=`!wQVGI~s{p40Tpl6gr1I8rte+WhG8dfdEOSdVS}Oh>GA|8d$3
zEp;F1xoG|I)QI=Ol7Txr@gk#$9mvEhz)Mx}TOfZA#upRYo6#)YJDsPNAo?LMO~3b(
zPP{f9SNah%u4$rZne9N(^bh>OCqoC#+FRRugD`Wnr05tmI-d0^0EBrME1U@+JJlNI
zSomvcE3l-ECkWWT=7n6ktZ;Q%lU6GrrI<v~&kx)=wP~lwT3{HaYsc~UFH2S`$jig7
z%WYgVXlFIt(EX%PE6uQEd6YkTLy1C)Fl&ZY2013`*OBN$VhQwAhU_ILZ^bXQqIB#F
z)bamZOnW(@+fHPAuGg?W3#_XPYIloH@#^D-=lg7<1U8q3n+E1S|F2C|KBqepL}@8z
z`cT=<%53yO<jG3`29T4Rg-TUBw6|jV^X+;oT>xZSC;B|ZzaL+A{THPf01FSs(~Sgg
zD)eV(<ueZe!Ioi|dX#nYqKIAQR+qHoeOK;gf$Nim*W{46(=IYp%fFk4yb~x|(<;|d
zXb+cbijl!<z>;cF#)G-{Ki(=kS~@y9mX`A1=nP^XnvI#AwMiY@$M^1;yStZXzZY|=
z#mtQDMX>=R7#I=&w(uned9B-0dv=7ddNib8(6U(*>U-gscmM-IJ~iv}=S#P5>&jS7
zrQG-Apv?R;hc5pU_!~N>=%9G{Bz=en`{+m$m-(NCJv}@uq*_!s+#~BBy?y&O>;>o^
z$P>HIC;_{Gi-2B}Djzf?@KYCB4{c=NgVnsZZv8Yr`FSvRV>+J)DLRz`)k$w&y}B*{
z%9TH35+PmN=A3Q$I;i0Pa9a>P;*!v@`g(eqDaVkP1Z#}<mDX2$B~vHNI`<d!vE%<D
zMq~6K6gYqWY4LDGWTd@F{9SZ}?1cNDq@p&NaM{%AY?#N}V_s!{cQ!AB1oAb`5h||z
z#(#4`eH|HE{%$0}TlrCnn3R;shrs67L~s*^o!Hy$68j}4uXVm4x`XTq`<lItgXtWB
zca5$2FVe~~&YpjCWL5kSRzl13i-AR@L$UtLm$IM&qRGCiq!jo)!b*@_3nZ<NZd@OS
z{r#fIA`U{->+Wi)@~3?hwq?!DUu8RcQhok!D$oWfLvOZV3NsTE2k1t2H@&U7Ic!7e
z%nRn@<LSCrxCL>=Cz5p(e<EuG-ySF8f;tD&8UGz&)Z~Btbx(Z3#KOYDQdIn$LV7q$
zQevWo`kVK^NP2MZT$|o&ur4O4nF$gvSFJ^cHVQ-XTTgQ5gJZ%FIHHFSy9F;j27cwF
z@u1ex!Iq*N3;(uf=2}sMb~@-Mb$$nGh|O1bU$;0c_LhY<*lfHY2MU4`co1pyXFcAm
z2otU<fTro`bx+X#O^EJ$3WjlC01&4zb5;o+U=w$jU#I7FU#<5S5-O(YFu8Yc=hca1
z@Uu16<^uWBe-w{4n1gcY6%OW}&;9nTQOBV45(c_13&?zEcMxKHaGr+ZufH<0KLb_?
z5d6)xuFL;$Go75M{xn51?LLyz73ue6u&ZQ&7xbeP{XgiasVQg*8{htEf}=>tBBnJ2
zJ<21l@9LtRuG>1u)~|-x@5-^Fel57rT{B$GHa&m2rswiMPgNRwlkpv(LcmbDT6DIw
zNIfUG>(HHUua<UAT~rxNFEX>(ZdHvo&db)avs=79?(OpR^Z-v(y|LTqO+ZB@oIbMy
z_dMZt_<mC;fquJsHTCmn={FBP`GJCb;*pQA{vBN?IkdF2G{}41`ml*leajr{=BZt2
z(WYCCYbEyQ?J0i{CBX}G8Oie??n>u`=T4@5I6b5hNF<Wo8y;3GgBiJa_iY{hshOD>
zF`I65w{_s#x5rPP*7g+kt^a$##LH}Ni{)fSsr~SD7ANb<a6v&22|@ms@~*rRlRkKb
zr_B=4#};jV(;y<fEbgA?qe4C4N3h1q`>%k`gn|_+Dxr&~l*a8uh9Rn2g{>Sqvzp?|
z0N0Y(noZR;x@lCVK&pt#J|rys&a`~Dfvz4xariyE2OndliwDgG88~{8sl>ETf6V>$
zh>AVQe-pfQe{cd020<_TocN4ub2Xc90<rgRISfBo7Hb}`gW)RV1hN8E&dn3`N~GET
zFNHT7%hS?YrneZ#qoYP)af6aPF|`6ssfdN5m%ZYz0wi*DrU1mSXBb5vO{B<xC0@i|
zI*C;ObAf~lQ%LP6xeX0><J+%&{esa)vxTL!J|e`|<8`H_{qE_`Sdf=MlLctz&B>~y
zq5|pg8UlCiypW(^U&U2H!H=qml`d-g$&<zhwp}SQ?(XmJ41kE{UqYA6uLp=iLDGf|
zhji1w%hdlrpN?@dkt#V%pR48k=^wzlLO7(H$;hJa!r!4Jjd1FpBqEAbrkl-*KP;3z
z{LjNtrXr8pC4E=Qy*t&`f4I;1jo*w_A(7u?>PJ~jZb53es-V?CTCe?{%&j8>ltsx7
z-YWegdEoUi;XnMqKPb66FAR<@s+Th46ss3?NSD~5tWfWnaT<oI*`2I9>3`<O4&|uH
zb<%03({<8^xBjeWor7fZM5I0YNDwD_mvm~_t7hvcW%hJkqlzP|w)HZWFQp9K4{gCL
z!rQJ?h-#1w!Rp4z=k}~fhCF264~Q{xq@SPI{U}A~kmf+~G&5WO^!ZA|+CWaGWILB=
zs-8mnXkGIA_7~S8QB}3bo4=M^!K}X3vKXt6JA5)bM_v|VCn|7{c;Ie#;tA{qym%4R
zMG^v&Fc3^3tFGQ9wsDX2pQ~C>7G|oRNxI~OH_gS1XD>brap5MBXy4leu3zUZIed+x
zruQA7JmL-|{AB5XDf*uIN5w;ShflcU!L`(G^9bEKv7eS*$KU}(1(@qan6)^5nj|J1
z)|btO*0*HVC_A`>IQN>|`RDnOk<AX_&o&%lLSR93NOF_z;eX#G>i<Mf*#8l;kSwec
z0!CY`C1`gc=m&mz*iIz0Wa2>NKP+HyexP85QR>+QnPzOO)+fPD?>KJ69&n>FsuV9}
z=9oC>|NZw7?urhQ2wcg$)W8XrKPM-s7Xgi9YHDifng}O!YT?wNOG{60@iRIG;(jPO
zfY1xLv2@NTFbIrs`Z&cc{&FPtA(@|V#JD^@FJ_N6pG~pi)Z2gn@GJA>IHK<A>I&w1
zq-rJkKOdk$L^?I;OzJxV6&<7`o<<hMbm77Utg(Y;b3rw1jUZoAoV&DL!oeLF8tPWs
zor8qW`$fzaPu($uQLJ7KId@7*ic{GeK5&F?PF%XcsR}^>-=!38@!6EAqhwLxs!I9A
z4VuS~Owd$tg-1mE*<DX?U^_#WsRHN(9*>7cnsh;O+E<kL$)xdG+AZ4W;JOoGXtWDq
zXAQjIoM!2n$x<%BM)mvmZ=IaYUxj9agM--`>c}Hxt$9jH`6o#suxS1fh>R>Qfy@Ba
z1QWzc0PtgBVQp<Co4YOKWSQlyycOKb2{sGI$)v8_&M)1fKXKv&gas$b{E$HX--=b?
zR7=`$5toA7@YB^YXu;BwCaJN3LENYV)F)zL@~X=~45<;fQz>gi`c#>gDtrnSCo%=u
zQ$wauta_RBEPelh3Eh*wKWXXg41N1n9cCnzvk9{M)mgvfh@CNrmtYyFvn+<Tfeh~&
zL3ie%J0=Y`xyoW1Wi*!FWPj98DJ(kL6|$O&uPFdHiimAepEwa7L<&H$9HcK9Uz2OW
z8k6oYyzgl{Xj4Jp!0E~J7g<6O#8^@5C$Ji`nI}`>`R~NJDf1VA3TGk|hSQR(7evld
zJWWT*I*wh7<N}5vkcrD#>-9r;n%?bI95DkA4`3yQ(s~>#149;kIYVB`TC0y8>Gg1|
zK54<a{FJ7caGQ$03%g(aqvJrB!ulCJXqT^BVDjC|Bm=%v>x?7Xs1~|-)~z(}zXDF1
z75vdN|1#lnxL!euN6WsylUbgDr$9QS3;rQZcEb82-?o^8_hJIohCY(y$pY&Y4^$X*
zeUOEh178D=(GW>mk;P%|!03U+X}s6-eAdKd!r_G*c{pMOV3S%EN1hH#N&++ERmlP)
z3erg7e&=wEcNd<5o1IAfQL>ct+Mj1XkZx6wg--H+3eHJxKyVgmW{`uuvurX4{o$@O
zAqyfN7%NWxQp)`QnpHxv(3B)72#%0F<0p-Dzki}lGO|kf3#6@~&L6;jn$stakj<R&
zi8dm6AdxQZ4AZzy>@HjxIQpGL5Xg9_-M_D17YmV6zJ8S|#T~c#`zu0Z*(W)4v6I_u
zWE<et;5S~V$9wX6{8#_bQ%tDzQ+9foPk{O=jgR@Pyae*ZxvG3Y_-a0X8v#5OLlO9r
zQzP#C?*X<`p9umWM{0c$bL{9b6OXyqP|Ah22nX?DIpp=i*}A^-Elsp3h$tiU3iIwh
zVwjDH<2xE<4gjU82eyw&++>H~MC6{lLQ{2}4cte`QmAf^dK)_1Z4NJ&E29TS*hrn_
zV?YfI`JGOV_H@j^Sk2x~4|Bq+&S~%M{a}XTYd)I~80htjT@x4mfyv||%QQk0CrxYR
z{2~Z@6*Im>vpMmVYN+PR7UaKM7=*iA2j4Q^GOFBSWG?-LzGA6B{Rp4otpN&y1nAJ@
z^QQ?DkvIN%ZO~VevmiKFg<POJ(71STB=eyx`Jp2#nYLqVR960Po8Al_tvVo@@fP)=
z%5(zEfaj6VN=HQ=4V-{$fHU*L*XL|)JmTVp^~z%&d+j!wwfnY9*@7a&O=2?tzIkn4
z0RhLYgcb8TYv-u8an+=3^_z*}Zj~uM;^eckC6PxD0wAPgQ@PfgB6IBNKz{l&)^4j7
z*jwvXem>Lib09z=VsP+}+00B#f1cpQQ&p}@CS}V4<YXBSk%=)oYm|P)V6j-Y@|QT5
z^zB*~k;@EHgd!-z*o4#}aZZW=se0p>v+b}eeSdau3UHAm6%e%0(3mb8v@5pqbsPN5
z6DQ(mjFE|ydFhWLv}8c7{JfpS){f>^0nF18h2-YdgZ;gg%Dr0fsfDTx(=j&BsX|b&
zp=+Dd3Ti8UH^xK#@>tO(f?FQy`@9bj0?sSl3L?1<`||W|D;%axshao-#E-~LqvzPS
z5tY0Z`2JywH`|Dd8T%E`LmRJYA}1cDDB(OCz?nSf{qXi6?hK1S<>r<+^dtJ91g*38
zyPGEWPM6;kG5PY@Fm#OQ^Bdq8GuGl3i;S%gFpIsm7WW4*!~)$FRNvE|Nuq01<XRUw
z20U5@5C>SpG(DW*K4=ThFrh3aKk;F$2tyCeOg!<v3Zd5$`;^YG+#wKrO{3Tdo~Iex
zl=7LJCKnv5wKx2C`v%6s#x?Nie3ca7nZDn105n{vBFGI)P-B!PNSj2@(^!RrPw|d>
z)59&xLe)6TfO-AxaZiQ4bwG4_b+Fx$HGNO_m-i~J%7;WJ>ZDqZ_S*}T|H-zs{PA8}
zPj7ZDU>UK8<1>Gmo)%VcZFm)%R$yGr2k?sa)qMNz>^z!!92$|h8p|DD%;&nkzFxY7
zH=8T^@gw*4n782@3l!Jfh}F7Wp}0?@3SQIIrdzD-;bJT10++1C*QW#a*NJ21z9^Bk
zb<j<O4qkWN*Mu;GOnc^6;p9-j&heSzAK3kEM07`j@E$hiz*Zzar~|Rml-y{9fC}ho
zKEo+cG(`gUke?PBR(xmalwR@EzNa2OdrMP;#T_3pXiR?rfG@_A*WN+JanQYo$d9@2
zVv6NG+TY)F`rWxMdFO!}-xZHoBfK?iq*slEpjzLhIsNNMXDEkP#J~)=7ysTHgw#!j
z$)lcp$s)PAjzCT&Zz9xS_H}AOS%UM}_PASt$hE6iW#bV70-Zh`uu5$#-M$Wc@}5(2
zB=27R-b&_q0AUQvZPqOZ-h(f6i*kMt-F{JuYT{7-8uCG=PbRZ^MM-35PveX}?@5$e
zK9pIAy*a9y^NNj#<kiS6z{C<@WHhgQunoSat3judB<M1|k<}i5o2N}_s?29KtPP0K
z5(GAeINOa!9Nh9HWF-4+V!!1Z3n1IMFoi`tf6E4{*_E0OJxrCa42}BnrzIoVW%T`E
zscl*H^!>BKZet3QW1#^7&-40A-!6D~l#L)G_p({NXV2kl^AQ}e5izgS*HODRe_pLY
zxvg-^X0gEc*3H`^yc}^NCU<2$;72Wwx{Y}*6A#wM_Sh=v!dG|-VD4cEJyi259bbN-
z<F$vjf@{{^crDkM-o0+`?Vy@(%gRPu1=WnLgcB!{O7Fp_P^uQTUQN&E`_a*%s;U~j
zFJ{%TU2LfeVkPHx#li*KUET^(0+y+S9M@32gDojg*mh|3;5q1SN(w8k0rJp&uuECe
zGP?MO_)4V$1^b-}%WrRA9NU{Q<Q1GLnG<R<@{MeN%2$c1sO##<fnB2<7uW_VW~p1J
ziT*vQ?f&6qEh`(4DT7cV+pw(TZB79rh=`Sx<^fTE5HDh!ub5wT&}d4(&upBA>9lBz
zR*Tzk$xvmXJk8wo#hz(^{LKiO<$3#cF~vN?j1Z#=pctFX1zWHq!Lh|yops>>lkK*@
z*-B>^T29q?ZiTIDiTUz*UgNup1xeg|(Ho5~Myh{f`^y%8b#--x4;V>4oA3jHJO8dr
zp%K5-#;RF<v8x->$f0KGjA8-UIbc0gAgjLo;R9xWYmeSkRY~d2wT!lP-(8t&9=sge
z>1x-KnY|`A0rd+B3bIwl)c!rLtfr>>m);JiDRC#pEc}UL%Cqr(YHq8`$gl4~Q8#aW
zi?Kg{f1z){1OcL{un%9|9LAZ?K6?|?3cG8_MKOSt@U=K0DeJB}klvD0p`yd&bOaZ1
zIdp^#*+R@$i_7FqS3@N)AJa8<`Tmt!vMcSm8GaeJet_dC=rCPfw=KZnTiXO$e*#q%
zySH4kH}G8<c#_lj_4oozaA;8Ei%$>Y%XK#YC>L1I^{qaRIeoDUW7c#AdN1mg&+4`q
zO=$~V{_tyJu77x?Xef83dVgBZ_zsvytdDL>?Enb@;*-jhl-1!D%{L}@riN?_z;GjA
zN(y8p{T+!_Y3j>>_%ol=rodiz9rxa2QCyhfG4g&s(D;t=^_$mECpS$OlSH3CnJOJ<
zp%bzD_3VdB>h8v}i=dc(&({;lJ_k)b7SvK3vp^v6RMLFU4~6^yz|#r0hzMrku?y$V
z(@a!9FLN5mkNCtYhRnA48rNrwr7%-07PcKK0Wdh*=$bfFu#pRv)_}7Xd5zmD6X~zh
z=w<Y^dG28L=IvI=)#m26D>FZklDU;?$zw>AM@v{6?~t)V)oAJ4gzIfKA5R%|)sCvI
z*AB#8Ds>##YUL5YtTs@w`u?%87pWS)l5SY~)CFpb)_oHeJbM7oIQHfgtMjIC>K4q;
zaUW{bejhz+P_sz04c5@HmY=gVKOBM?)l@8Nt@ro}CY~!JduYc2m=^q}!kXQU81a1F
zcjd0wKm>q0QR|jf35sn2jv!-JuuPMDVWJu`I$-+KEEK`PxgmIC`Q>(g`IB-Hjr=AD
z%zi)g?LB}Jw2ynxyxr&FvRB(vPM@2FPzpNK44mUFyI)<PNQ>P2MJ+{mI}*0Na|uts
z`E}cAYOC~UwSPn#efHM&cn0i@dTH#*-gjh<zTMqiXpg(8ozu!b^u^}tk$VMW`x+V=
z?0>=yY0`7+*Ipu!KYxE!fMHo1FWIYYru-*hZ>4JckAoyf5X1Hw=Y>Y!+*WMW%1o<Q
z)famsM01h7ffQ~_d_|GrayQ!hwI#HausT+$x$ZoB>3i&+C+vQkpgwA=OLQCAnkSm{
z%YSj`dkO=B>8Il=oTjw;v)aRnt6M_k65bpqfFNFf5poJV51`}lfu!dq`u_c%oScGM
z95lJ_Ia8=IKbB`0lRr9Do@-E38GJ-XEYP@x8R1SGU1$n+Wy>Ny(S3tu%VWNTuU((+
z$bvp6BB)i4m%t8sb=FWfA1sb!O}5_--Q2kpXiPGzu3OQ|G&pq|)bW+uwUnKr@e1_k
zS)~XQ#$xr_R*t>X?FOkYZ4(|q>ulbE8^~lM{!>rP%#0_YwCghGH^Ei#&Z)|mzl9vz
z>Iou-N6Lk6w&hvkDcR1S7qsb_VP%;eK@I1@LfEA$+u2Hgfzw@rvkGV^WbYnm`_cB%
zIoCoB*O2(BaFY`iXlUQ1+T`Z3VlQ~&9iSlp)CdgNlzam7`$@!sx@tSNtu<>sU6z8U
zseSb^ZV58}X#u^7+5+>HrLh_X3i;4l9rSz#o@#2p-_XG|QQr3Bm8+P8`E^#wJ<l{<
z4-XGyn=S?DuFjG4MGLV+!nhOitMBgyxuPhqpz~{>tbNXSx*&B5_nMoqzr7jiD@MoF
zG7JN};Nv96jfiC1fb?j7LlaLw4k2rqMsY{X@9r`6yMbV{@IbIAEmaXDB^m}<#bu;|
zZO5OP;Z5%N&FC2J;u9BGFnDC>%y;^O$(wWIL{CqAAT5t>{_bLNfZVa%y%mgta>1?N
zzaK})J@qk`#I3$0ISi}}*BVy=^qae9Tf<!pK@sJt*_m*YET<2@(4$qB?FI}$ayOC8
z14d^bVt9>id2PAje1a(SXsS@JNxG;^LCsGpnjyW*Z;)y|!pPML8Du=HYLBLK2bYB$
zho)u&6#qmh^E2o<YsZ{sF>p@%avwTz%tOzKkt;FT#WZYezTI-hfguAOZV-=Qvs=s}
zMxOC|MsCHJ(s9qYg%=Y(+Aj2Fl(|ywSk2hAdPv^z{$(-m+(u5nq*f6Up{|Gq3#!X`
zJpRi5MjFo9ybI4?a7ObRM<*`LuBKacvdYoVjig5+w|*Bnj-x^qL2#x)rk>r3Uqj@`
zwO$r!3@@_jJEpw0-ifhhN=4JK$_JOv$B-iqZn&x9dw8(9j_C=b$`5wu<3Aeb#XN+P
zOdZZlQ!s5{;j>|X)uWX2E?$J*=dHgNrAeIUCbI=}{m|hv^i+A;lU8_Vv`Sq+D)raW
zXwLg5_le(^3FL^jszpLjr89r!{g{rB@P*rU*Y5;887NSP9Cu;>G!+QoEIA%XBBz=Y
z-NbgU??ZFT?3j`JB%X7AvBhHxA_I#@-}-bbLSrI#KE#}f1)X16WX2dwf&4Y5#M`k<
zB6jMF`l!2i-@Si-QCBx>IjF>;ujtolYwd;|ji{1r(2ABz6+T$#C;s{z_x+aV9p~B4
z-1w^d6C72}FcpXF7%K+FE#^yJ2ccXXJ5u^CF-dwxaihPmMNRV1`!?`#_Cjvp!sawF
zA!9!gByi2cNG0&^-o&|lQ%wCNZ?$E(iQSP|P3`>y-JwvTKA*;&`1UV8dm+NM10dx>
z7&jyZ2X6#BZ&MmYHEg~VcoBkoQMFv|vpnL#shZ$EQSVP&AEzgUD0#!*L8hGzvX4Ps
z<kZI3v#?t{Ts*~Rn8fG{AWZ03YYws4Gb(7%ZY%R6PjI?O6;C$vcZc>@PDQ`^JRir9
zZMXEQ`8?-zLr1O89RU|Kw}O>V5VDgH?Ye@#%!f5m%gQC5xR07MA)5<*nkJhI1<F&e
z3@K`NcbS$N3xc*DC1MT?Frewq8$N@zKL00^P%v7}r_=lC0q{IaQkJlgTzSVtkGap4
z!>t&3?Li=mK-p8M@Cy@C&U@X!0K$`)+9M$7j}U_W?m;K(Xz4UJ6&-=sZ4td5t^rAB
zbno&xUDGV3bbGXscwer*H~n3?vMH#}9je=45Ylc59NVRUvdf+}!Htw`6p`n56NWh`
z>QC>9WW^g(2Q+uxtQO_gf)P8k?BerHY_(o%>AEO_O|5tT6qhEJW75lc#dX-e%;-6O
zwJ4Wej6;seT0<ki!_ymy49vcFpt+bNVY~?1%h%kogyF5@pC_*V7qc>stHypj-Fzam
zTIs#j{CelUGE=^0RkYdkRSuDUQO~K&ruR_t)-sAqRS2a+5MzgYXo~Nj$cZrgWbj9G
zxFXz&=G?i<D~bxrBV>8+<kOr)-gR47yG{u^*6inx9Q1XhmG0FYqueOaX&7~+x6gqh
z6R6dJWi+Tm-I?g`pIkXi_&#$X(5EiC-7@mQQ-g+d@`;cc>IP#D0x1%VkXV}%nnWaC
zI+l3HWpOZ70VI|mQ&UOZU`#i=9_v~^$WzWRrr^BBsv&jNV<g7ZJ320Ix0gW9qeG}L
zZ&?ZOKf`DI#mJ;nY8^Dr4S}M@BllbM7JJVcb6DO3g7h9rZ;@^(+9Z+R$s$F&?N3f~
z{Q{t0hai{mQ}y19+G?tEsNI%sj1BD0%NXL=M<I#bUl+hZ4+e+tvT3I^r#(O!+8s*T
zIyt4*1sa0I2?bukAQaF0OAjP&0<KJ7>;|(tG!%mtVNY4`NHZS(l6~r_C=UU`!<=6$
zSH6gO5jJ;-{oSegXrVcni|wtg(ea%bOoB#UjiFBV=-e;XRvfKsHDBC=6-D>Ek;Yn{
zYHZRRDN}bGwK@*>6yWIlzjb2NJCesk8*5f>mV(&@eobIVspI9=#t-8vS0L`71k&Z&
z(8+b=dZ4P3B3Is)riuzg4GJyF4Iz-C>@-jbI1W~BrpFLD%{t!W%2Df}LesG`H8wzO
zbcpek?uJ5I)WH|kmB!5C+~7;H#lu`!O!MOwhHYZV?E5v}y-gAXwi|Z`YlxkFh0W~$
zcrQ_kC5p=LG?NIO@$Xi2PGHE-{Kp~=LkaQmhK+JcZW9yrPZp>k@{nhO(vElBFOx>A
zcxGPql_b59TpX!T&R;W60m1z8B!}|+&nzIW$NnZqD06cbx5O@ktTbV567<yB`@Z|F
zf8u_SaCxzsrsg1l<?PeBhHiA7fk(YxMJ!Z5R74zDVeS`#8eU6TaT&A18VaCyQ;ANr
zmEGN6Rc>n7MSRXL(?|L(lx(Pt1Io#%GGiu9Ol@lY^zW+*fgMI0WtDp838!n#yM`ST
zJ>5Slh(CD8L1a_g%7w~?{!IJLxj#R?&I^aEoqr{4-6gGkg~;Vv<+k$aK@V%n37R0l
zCH=TlHoLl){^WCv(k**Fi~-*-@#zE!Z6+8*3te664CQ-cdy)qB>|hnX(VQx$+w&cN
zovp%RfAwmpmx{sKj8cWAy46awq2spuk6th<I#?kxQ?oesR+f%@;A>OjuP|3nE2fq2
zhQ1lCZX+IL$So`H!LG}!R3WUw8e)bwt+!tkRL%z$jdaFTwX-CKW_fOw-ZpaU7Dmpw
z>?OL{4n!_bm2W&tQo*eLY0Ez|YCP3Y1ZWp-sLCz*Xa{?{;t}-bq-ls;ptcgz$55$*
zd+7GMBl~7%ES)^n+hddxo*^-81SZEytSRvTlZ=X63A8TVu<uN&k@Ir%oEhDgXk-RY
z3;-~uKzGg@s#u@l#RJV=!)?=YuHuDr20VWtaB=5wwG%U@wTTkn%_5>iBP3e=*n_Qd
zpHI7>G!{(+t;4pAmupt)KWdKqtQ_NV@;61H`<`lN()_oS+3jsD^*Z>qWj#||Z|1`F
z>5AP^Ox*h_k+)zZw$yL%tXXXT-R;rJsj_kGvL`e<Pp}VVbuu$B@Prb<CMD0USya<f
zSxa41R&Nq&+7wW^hzm`i=WR^}#MO4mz+ztXt8t!zFb6(DvlGj65EThtg1La?idz2o
zRkGn+p|?Amy4_aJDyF#qw1*ygE+G}%7Te1Jl8R5rYaIxGG#hQWqKA2$I)WhnSwAr(
z94bD@iJT{ZQ(I*1uE9aI!_QbIL2GbaO9Z?Uh#f%E6!T@xUxMId#0Il+;E%#vJcNq%
zAbwm+)8x~B6;Tvnr|)V$x*#jDQH=4Y3gJ&9ljB&mg|d;6T{q>6V{+-@Tst*Ndusws
zSH6RDTjbVG#U7it`yh_iAoxoCzHF$(wK8eQp<0X12grT$-a}7mQeL>wWQ5Q`Avtb_
zFX>m>;S=3PbJCfX^SH#F%cYsh*Ymwxlkzj1c2>hl<r&t-*^I*3ZLE=h&n4}#?%-!$
z=TFGu3Mko-&OUu9GB2t4tykhOzvp%}Cpo>hAWzldwEuCH8u1I`i)gA#Rr9{{TWINn
zJFL?_Yv0)ew9LyvfSrt*KcQVg$oPf!Udj<bP#-@Y=4)f-Sg9Qn;(9AGB1G{Up5SW|
z_M{AgzE8#8!B<-!0A385$5nB~4hK<E!mBR#NhOhg1sUxM5`WNpe|wuV6`h(uXa|94
zcZX(Un?JP|p-{oZcQQ{d2!)O@`q+$p<@#oOQ`fY5eR&VmjM~I%F#=ARIQqptKH)fO
zW6j;8f;EwUyAKmDS!{b-p)I6nTrJwLy!&A{bcfDQ2yU&gR8`Gi__A6~J!Wh8<;|(M
zu^La*#_v6lG7mJo4w~Z76)j@GS(IiuVm2E&UQ*B*E7?}Bj&3`F@dE^r&jGQ~9=zXk
zYpr;Vgn23##5>j)cldq%+E7Aw!EM|{LH*e(K=m_)Y=CqNo9)t66k@!#lNKDy6+bmL
zHQ9Ea(F{>|Sr$dhodWb+A{+NQDT<)sh~Fg;_xB2$k_|xa)z!uiYSB~2PyJ-o+U^*3
zL~RYuKyO5T<r6*W$}?(BzRr`s4B20Y>%J{^h|00AO1ld(w5d3KR6cRLRT)Zga?`kt
zD_sYkzOX4fYpI%yge+b{=OB3|naSzv17z{zsmuj-P21rw?Q3RD9K4zx?h7xs$Db!x
z$OTQ)8~>Dh@(l_LsF{|JpTxWu{T;~j#@2MJtrJmYw?hkPiaQ}7!=ef}G$S>vEttvO
z9#`Quvz(DbX)l5vd#1*1ymDrY654L+n-rDF{{6C7)$01y0){mxPUG6S4SLR1aXL<N
zt#ehQQWmYZ7-q){9J>t@m#4mIc?DPITn=!bp5r90R9JB+KJ1v;Yer0q<Qe+jwz5=A
zOloDoL#u`{=iYY)iN1U_l^_ZE9z+L#fOKNb%)vfMog3-Z02}|1O-Vvp2+=&j^~f`w
zsVhru0#dyWU)s>Yu8e%+2Ki2nW9~kR$`zHNH4YosT|@vM;HmnUzJ5d=$!4gU3N8R!
zTYxHU{P9&bNOQ^2Ilm6uR)Trki{74``M#Vs+ED>2RFo|fxz<Ug{B>y#K*SuwKRVQ4
zryVh|klPF48KROOoN#9RSs?JC^MRS8x|P{43t0<E7IBlz1jNqWqfs4+;tvkCayXOS
ze_U-YU+5S%_5O`GFOt=}^gb;mRuFHCXAr2g)Ne^{^Nn$qt<CaQI5Ev$ldUf#6Zk$I
zBhb(IvZ|TV=U_17Je7PU>$Taf7RV)qK0Syo$St+#g|;cGToIP-@9CDj6P{q#bDro*
zJpl-IY3R=1Vq$U7D#oIaxil29EA5qggb@2XxMulCoyW9av8p>nZ?w;@!QMFc6Z?eW
z*Jsp&eb3D(hh{FjCr|#gM7AL53>z=XscLVpARe`JIu4~3=3EFXT0lJeJn{mApDsks
zXT1{xUtRE!wH5oB`zZMmGCa(E_OsDgUzVm}RX>ia;+^+w*N0beC&2HJe=^$2(z4}D
zjL)wW86PB1LSA6ZDRv!DOi)rP-jmT12i8q38AHVG94?R%$@M@j_2=qqqSm#^)6&wI
zRU~N6Gmn(mL<&uxi!fartjU0iGia`}h=F}UNpaxw<CjI=nk_GL`x~AZYEIA0C?9bn
z?3_4Z1oKlHPg@W*PG5z*PR(-1?&J;Or@uZkbMj@1`b3M9Nb8h)g@refR(cd4vuA5<
z6~Wex@ebPOT!nw`DETIx*o*uLi(uu1$ZTGum5GT}>HT~6+=17pCBuB^948_VgJU4L
zQ*?Z@|9+C#D(d8{^;6%+x>}RL>Y(bp&N<8CK_2n;Dnj-z$sE}eL>W+<fU1PO3g=}<
z{w%56@MuWU#5S8B0&IzZEdyp0_+Khva9KVHTq%jzRt1G9jbAYh0|NsS6BDT)q1GKG
z{<?AX#iMfnki&42^E*b8#K(_1Jw2U^@jS5FEU+5~lT<5yooV7+K+2zke*lKLZiStL
zqs8lP!=Pk4J(*uNNfkf_`5DHnP!C?n%o!lK$qtPNF1{md0AZ|69>jV`diOr=memJC
zg7+%dJZ2bjp=ERm?QMf@O$U+^LTM5WnB3uc&5qB()t|u6bc%wU%uhg39||^wwQv5<
zrvRhhVW~J3#%2-UE+2FX_;iwnjaHVVPf(#1sPL|r);1?Qcmou4UB&AN_~YbVGL*k9
zaOCOXi;CJ8Ip{%S;hsK)BX2z<n02ALAe2QM8vcqZ%zimUTr)snn5UC-l&sE*mo5mo
z^(LqK1zc&uc8ss08X`eIL@P9*_1<{~!UocZ1cijqF_jJJBr5!<K(vtw^tr2Ji*2{`
z=xlB6u|MVrx6<*n)Y8hTO&a_;vTu--4+S1&Q#g{!=b+hKP)<RiO&au|a5c)3EAszu
zIRPn?(F_j{$5rvVU4)whZN?ZK95giS-{0ZRlP;&`Q8R`6msO8}8^T_b)zXS`RbwI}
zOFWb?@WEH1_z(!w1?|6pgFgz-p$-8ThPP~zDv9B`a^)_GgcsFS$|w6rB?YyVNH|~p
z93WU+TwD|{FM~37KypHZBn8M9RL(z1()L=E4TrKya>tOm_<<4^`2FG-xYf8g?qeV~
zsja0T(fV3O7STquO(0;AZaGaUwimNqQc?mc7mzP>^nj8U%P1WfQC==u5s>E{43An}
z25p4YW`<y(jthh>`A2efa=NWm?%)4MDiPIQXx0Rk4%r}=h_&A(=@zg$92~lGpj)UL
zhX;gJx`aSrV4m+5$WoDI8bmNxoTRFX{7W$#NfK$as#0_4R=|(<<E;3=LPL{wn*L5p
zGRTOIfW~SPYG0I<m3!6f?!lnC{`!n^J~HKk8`<hqCB@mfxjB$_3!a68mX;&ZI^_r%
zO1a|z3i3Hvdk&&r-Ov9Ex?E~$lO8#Zav6uN7)kGE1HKT1+P0Ni!fcxwCOAvK_*1{q
z2#8m%U90T0yTu3qTh3`Abe4(*w`ON(7A{@@Ll}An6M=>jxy8oJ%$xpFDp^#u<vZw}
z&{<JNGdeBW@-V;E<BoGyjXFG!FeN&rhsuKJru_D|$n}G|I_bo+4$?g!+&a)k7Wdfx
zaTg%#Ds}o)<^iu9j{hu1Kw|cPwl?hl-reEa4zKM0Q}uViMn*;?TCU+F;S&_3E%6u`
Ya=+%P*uA?xr1z{Sr+P2{?xVl|9|=c9`v3p{

literal 0
HcmV?d00001

diff --git a/docs/user/guide/providers-models-page.zh.png b/docs/user/guide/providers-models-page.zh.png
new file mode 100644
index 0000000000000000000000000000000000000000..b5d1f4597ca57fe96fdd7305f2b52d972c8d2efb
GIT binary patch
literal 70021
zcmdSB<y(|n8#jyv8`!|!h$2!VC9NQ!q=*O%(lO+KDBazmh-^BCF6kZ=h8P%9r8|Zi
zy1P4`1$aNl@qBpyfcN^u0avU#&vpJ{;jbVkNks6F00#$$NLuQR5)KaTD;%6#`hVR7
zzbWI6FvY?72S@sin2K}aD)x>Z8D`}7mVXtg_)W3T%oT1nnAbf@c`CV8<0xgTZ&3v6
zWKK?>zoz0xe5t4!=NGiEGUua%kZ)gjxE%<(&9|?vu9~kW`Pp^GS`DLQb8jCV9ia@u
zvm1Z^9vL4W@9gZXudnYM9Bk<AeI1*irJ=zB+5oOYgn^;q{Os&Uvy9BlOk*iJdiq8c
zKmV^v{{{?)R4RS5w_~HzP%ZjeSy>sGo*o!jlAmveG#zMfZzsEc!2>q7;D)`3ou4KQ
zOiWCSjMB}F-$UOBlNz$j(SKJ`q)_v{qwcCx#DIz*dBn)Yg%A*N7|T;tzJA!+FS4Lj
zN8E#glG1H&d7!yj3cr}4Md{=ti$UhRjBmNZIF1aW4PG5ZC6~sgrA4Vbfr~_=4KVkv
zA0G?OGx=y_BolP+{{86aXv6pK>FA)peycMXB;RV&vuCVYSzMePO%)4%$or?YDvTI}
zZms>25(EM{`oJ#1+{h|(kkink3WLGa)YN#PQ1FQn&X3pc&r!-V`}y;ycD3^}I=cGa
z-XB6f1W29l5OTdG321;}{5}|SHkmd#YQc)i%0B~|GcxvE|HB9QWT7}XJhOAVC`z?{
zcAb&-wXt=3YK|@fmj0HAZ8^mM`U@3;QttLs4ZdMv|L``l+PSNw(Wpx}RR2JJH^CGY
zqS5Hfr2?+8ccl4Wi6{pPG<Fty(kUn??%%(km6Ziq!s;iv6QNtj#>NT?*f%thuKTNE
zu6M4U@zx(29(Gt6EPNaMko1XkK}HnJM!1+j61rS0=3+UTg^Y=b`QPgU{QaeO<~y)h
ztbCFHV~diB-`$7Am-m_)$jOEHR=UJ+CRv!9{~5*9pF+aI)KpZ&)B;gSNfz(lD{lYY
zR`*XsT5mpR1)kdpjW8+_cH^oQsehYWSX9|BJ)VlVEsM+Z#Ao*wyN}uY+#FbUsH!Tb
zrCyEcXV(qJd2$y&M!;!(b$*`7Mj4-{zzf{EgJiqdMdvA^T~8b>+T2UTuilFD%D~ig
z1m$4XQVba)S$XTNs-nz`wzaXb9LUT3(<zmIT8a}B6MvMHSjD}+cU%2e2K432m&C;T
z)PnY@8-JD%YuHa&i_tRVj~@{@d56(izustrr9MADpCsV;oQLPnI`t-C{HEL#Le1#S
zD$>Z!VJeo~+_5&6OJ7oU>$;N>>YAEmW*AOrdJf;$TkQA<Zf@>)UMoW*qwMSU;=teD
z%wdv^|7d6kVK6BE^a)2M={V2T0U>}iWBb!3#-08B{oUOtsn$tz=<$u{=d8`B?Hw)T
zY?;sX9Tl>tr>FgTdDdSYl)d4Ia5#J*L;8cAo!y`DtKeW~XMf0N{-i!CUSWyzn7>Ym
ze0F|bKtN!yPz!oJA2^ouw6wJNS^dLf4m<^vH=;EeyL!`9+wNbcDR5bjg3K{DJDXEd
zX~x5@j3tkNxwyJYb!T4x8K*qS$H&Ld&u;`@=7_nBdmsy{)ZE!=*`E{sXV_0A-90>z
zNyTKchI<=S>JjFZm8y33)(Y3pdtdwqo-ZjW;j2@!U#MeU^c*Pu_P-~yA3iq@i;T4E
zqf&p(%>l;FbRh3fSk-y8g2ma{DL0A_W}7iC+Nn_UPmA?#SEJF4#Y$}#W4=#Cbxr@w
zY~5e|1sXi^;)=HlJ}-@8vF#ll|MxHI>gp9J)c9Y;+dDgUwzj4NA5R}$w=YPlP!rjo
zJ4SeuT@j7?Uwk|u;^N}st>o@#YXi4)|KD|ilTP;uo}Qlm1)2p`&49Mf|Gv;%QBfh~
ztormzHx?`VXW)Z^5)!mvu;j|y>PlcQxVq?-3pIIN_?+zR^=`6X|LOsqf8pxdTF2Vz
z>UFqnrnL4pcXWVnE2pRu1o<q9GRP~YaPX3;h~OjIEeb5IZ?hhi7J<jb#f68{b$wKQ
z+o_lQL^>LYM8e^4p@i7jCplEM&K=ZL)PL@#lqQP+(Gee?SNM#Fhphs_&yR833^(Hb
zcP2a~1+hlO+y$Z~LI^@9EB<iEthqcZHEnogBwj04>&aC^C(FX97#JBP(%6uKp$uw#
ze0-!j8tT?Ami-Lxp7(VRzIgf408C+awoC-0OSF4o#K+uc(Vqznz-4LD!gc%dCElZA
zH$!G;XUE30S+q1Y1zx;phF5+TjQ0JSp8mnmFw4C}LqkJaS~@}w5<DA0!1~{*dOJs~
z)!$doLZVYrXvxW$pZTRp3o}eULZK4WO+J47C=~=xN}{HvO-W8(pPp`b)J;GqN^$pP
z>fqqu^@_=%ih%w4`BSQh&H#_-juYY|kwl+W^S}UH<9n-ogji%^A{F*V;#DV8Z_drl
zNxL#aCrCenDed0MV{LA44+;&9L5z=$Rcj(mZ*$EtNcO(b*Sn5Em7A5DAt5219UaKh
z(x}~lN9oI9TsqtZATJ*Ef)%{vrz&?_{p#H+1Z&M=T3T90Mn-p3Lj@?Jf5r^tseTYC
z*nV_zl~z)fq@3xN;9tlypsLY<fq{uQU^HyGpFF|)vsPGPwzjr!-+mRi6Y-h#UD7QX
zwAi=LKOWaz#Z&6%Tod2iT$Wo+kC?p^ac#MC;<7$-)BXA5W6&=~28Ji`Qy<z#h~HaU
zax(jn&HmKm-2U+l8l>*-ev09#^;r6~0G1&E7aVbFucx=Am7`o0lAbQED8mJ-j!F(M
ziV6)z%KG5$T`&9RO3KQNjS*}bY;0_Iy2B#t2M75$I5-#?f7REEiLp>@==_zQmi9IX
zb<iG{I^PlBk#ZqvVP%EJ1>K^7Ap<6wKOcD!Q+3zoWMbXM?6&(&GTl$l;x|SruS4in
z-x(`6w^9*OSXg+;^NtP(Ia|xv`1sb!`nuj;?s2*=exX!o=dB1bIXv8bRQ5zTz2tSv
zg0vuzfDEXkqvM=BV%%lpOxLhOP2pw&pGDmHp|Z5JK_cVXn$x(T=jofNV>T$FHH})(
ziRGS{9RAB^4AW7OZ!TN^PeZ*AZjlCBe|k2zr>E!p_wV$Q6IJFdY5QxV6y`$uKc8Y_
zP7Y}Q3kp(#tZH|gkjGFSJl`|x(HyiGtLQ1B)<P1Y4pu$(S6|A@hblAQ?2kV@{PI>d
z{yP0HO3BDX8o9Z-WscRH?Ynt-)k@NMO0h)F&PH{2D`f8GVRF`2XEUN}54Ts$Fh%$J
z4l5T7-A~p?aLFAu#vK;J>QTHukd1z!PcnOobVe6a5^UNGn?h)Hi><@+^V{$?YO|wy
zYtHZtJ$JB`b_?X3hcYk-!4#<cOiWnjii@o^7$yw6Xt3~rM+uODilp?vVmNiiixtJa
zYI}Vj;E~Xv969XUV-*8zo-V&EW+)n|ap*(O{KmVJ1g9O(dG-OysXJ0;L5Vg5m5JTL
zSd?@q+UoNc1jJuMQ!^(!E3Hz{TPPtu-qfr=X8Ey2W<lC@e9`mp@NjW;jf|kUaY@$4
zOAdCrYT0XowYh7Lew&%PVAipBnX!nd@$w0GVVB<9$kT%fvyhY*8t-OUBAGkl&+_Xf
zY^Msy^{9m(7Mtuu<7Eq{)(E*QM`bYFWezGwB2}LcPgEZf&eE5f4l7waJvb2UU)j=%
z2s2w7aS%NdlG)EzO#cco$-$1%c%44mGr0I9&hWXyno}Y7wyl2iQaHFk8AmCoLi5ss
zCh7c(5Be<4cSpe9ShoQ=>qfzAn7Epq9b;5pq(erp*MB2AM>T(b8Qz9VOyjsU%_uM5
zrHMRG+GS;B)#T_eP!wlLAx=WY#g9Mm$aBO-%pz@+MJ;?57aur;mvM82R^eU^isfVS
z(`|NqUnTtM>FJvx)P4C;IUryC96$eE*wwFv&2^`I?mTs5gyb^v+yUEhV=3M)ePLhr
zEq?Q{=c!(`^BoDfyq*F&4ty5c%;AY-<E|&@Ux6`+L;`zrP#)2<)xiHY^G$C_zb}H-
zWR!Q9eZ!#a*K!}|zkk0qoK2fMXH|0s`y9a!^Fq2haJjggxqi8=ehY6G<5;O#VH~c+
z4XPv2(@l#mn1`<G(SRyj3=1QZ)iIcu1b(wYv=&sNZ;tiFi;tVBpCFlvx7cmmZnDb|
z61p^f`S}JvBbrM`CE{-xSp-NHAh&#U`1Rs}n>XVa77Hy@-~SmYf3bO14tB{ASBr9S
z+7toE(Hn`SP=2s`2mkk9e|~#c7ne5v<uG~Yo!%JCl&NRQ%{A5FeBIaAC!Z+9Xh3MU
zGu8ODRUF~57w@o)$uBoL*l$QM9qNYupj&H8@rs*UU(eD?k7$>=S@2C9Pd@Q!&F0%u
zy1=-&Tz&n=v>mS_jTb%NN=lyfSpN!2ZEtBgT3XOBJ*xZUvwgatyF*1yof#Gt#n6RE
zLfy;P+}b**<$+ljrsTI|HJt%KOVDX88Kjh=B2HY&-Hi!(qP$Yigp(=;oW5+)w3;!r
zQK(Q%b+!^kj-Q;|y**_p-w}I+R_-SiX>NAxZr+zqm^B-`+v;hC9S_-{>;r`@ot@{4
zk@5rEb)RkpXg(9>&|w)#)HTX9A{(AOn7D{PTcKhJLOZo9%L~I)cqq*%uXZ7Yxfb8N
zH*^sjQP%wlV)CLptK%LgNUpAAVNAM_6$=0>IznD=E7ur|Dy_HD$n^E~ceZWilSB#~
zSHnIF2@Z{(93Dowo9(S&b`B1-N}c`7vQ+b<SNP5UCJ<n&k519GbD^N7PPgbTHMy%H
z;Y4`jMpMnjRQB|QL4CvH6N}2Ksuf&y7M9%Fjx%xArl6W<eSJkbcWw-Vd_3X4Le28U
z*RO3Sx^T4LT6P8PG{L!JaeHnzEb>j~{iEjj`EvSb7MHIErAu(z?Az+D44;zSFG_b7
zxTJ=Mhh2K#oQ0_qmuenv=f`c~Z<(To)7=ihHk`LdI?Tj8F+F}8)z`0s)*Op+Sm;b~
zvbOFfw7IIkR0H0SLMod`M4s-Q*La-d%sEZC)q?fyK<cD5dXcsBGjnp%61&k;(;q$X
zI&>Wi;e~B@ZJ<9C*O=_w2X*;qxg~1uK9hWWce#}n@^pAXw@ACvb!qy}fSC&a(2GZt
zhsyF@54<KSm{Ssq2Ay48m-(EJ;Fz@ZbXr&Icu<6;NmKG!aK<XQ?M;~3CrB62lVIbW
zCS3B{Z$!V+{sk(NYc3$HJhFt5jcsNBwmPJRoBe|vf^6pRV$Z{^g$5@C)ieE}N3!y4
z{)Q9IJ8LpAp9hW+wWr#YP?Mt*Ufu8d@XMV~<f5U?bPjB#rnd^9FpsnLxJQ{E?{jIe
zhE9)4u~u7k$z3lJ)w%h3*7%pnQMTRarO}J=i|)QYyWc$WEEh=WyG>P<l`R9u*|c62
zt{o#4LqoX-@<*p_2uO{u#|cUGZg0K>2ijBk_2=3mtn0mjNgtB&$l`Yd1JC<gjf{lo
zZwz+oR0X#FsyUi>bBVrXY^~`eojc#5`{)j30%hFH*u+JUzkl4bnWbE1rd(dhP#U+*
zDM{Lt^F?|R(VQwv7lC1xi$sRyS^aX^EsE&yY-oTDuDaX)s!qA54=gj$f>dvAVWBIf
zRv`iAv3c%BYJPA0^K73NLWBGt>w=u}u;RYo^Y@pK3<y&(Pl@us)dq_1U*-%2gWMZx
zFVl%;`U|x%C=rno!>%|12T1c=8?;Cp-T<2Q<mkT87#5F&Pl(6$&6}S~b+5oqoGgqY
zN1|X|EUJWFwE*p(@*NzI!<;*FyWN#YB?{FmA^KcCOYk>_UG2`WawdBEnU%N+DS`b4
zyDn4aUnI3O-;95I!c8+~IdYl(T^q*aBn;Glr@&a8#{PMYAK`g)<VV-|_UqTLo;*AG
z=V!+c&6y<KSLTWEh-nCji96eyRoD`E&GIa)+dTd8{ryE8JTfO&XURz2YlMVvT`z7i
z13dK~9y~lHq<kTPfiiN^J(sDYrLC>Xb}tXsHZ=5NPs1r3os?9T9?42a*YoSw@T41u
zcIk^Jiv^al(;Yl-{c(wwYmZxH0+^Tss*m29Ch(^3&))RfT?}_Mb8&Sh6J@YF-j&QA
z6J0BRX=l{#tZCIl>($xT+Uj~ZpRAk*fa#LF&^=mOQJ3B?q8IT9wa&A%uIA<(64ApH
zK6IYYg{pVvgVy4V-ork&UoXJQ)b&`J^2^Gdn`2Wmm1lwn2Y001@oEWGJD5-Pm7Zk~
zD-ep(a#_G$fGTxS_4m)8d3Wpx1C3JL>L&w8>uYxQ6RwMS_<cP9GZ5;P%S|bsN3-c9
zBjr|5us16~NvY7SgyfuM#>0bpC*|XwP@0jLgJ8;&zR-y!zKZ*<g>q{nxEP%hLu@>9
zB`V^j?Q^~6?tgt(CQc^sw!8DSznj}2V8ZY;BAVyjRceK_UgvY+k~BY%$brE&v4ow`
zF_3mHtJO_S%xiI{)uERr(}&C{&e{nt507|bNDe1UbA3ml&e_oyPwSK{JBz=DKCsX?
zjZaRtoLz$JC*FwG-I*Wx;aa62Oh*@!;_muYNnh0cKsJG|Fi;ca+|s+bxgx<4?C&2=
zHaMB~kT>tH-ql>IEJwY)N2%v~+wb{-)jbM|xuvD4<z>z7dnda~Yk7UXth|g4gR8of
ze7n@orM##n;&_bsEJk_}x+z(*7u4nby%V~K;emY2a(`|*nft4fu&}W9_IGI98<ND!
z120}Kk*xH&u5@5%V+ABwMy%{Eo+KLGGc+{Z-)`d)IqK&L72Vn$n=mw6nYfrt@9r+{
z5;<$uOF;sXQJG2p^t42tQ@19qaJ9FxFDrP(vg@|kg@t$KY2<rpS9o$b%Ti)+a4-nx
zR%%!BhW^r0yM@k}JP+x3^yX;^;3&(@qr<{BkH|A)bBV9w)nRsFAtt*qMB8?K1Z~vR
zsUzsP8s$w-_w2h-K23_p@mA`mTM&mP)O&HiX7Lm5N0YIjR5?CyTPWn;)$B~DeRZ<{
zR0DEglg}vxgcFAbYBiIbfGK#n`x_Rj+f|@i1#@&P6ZnqGgP~Cn|D+c-w!_=^e(@_n
z410fWfvWd(2XSPZ%Zb@jqL;Lq=bzYH_vjKQkz+G0v@%@Q#h9(*8{em-%-4#Gjm<Gu
zx`TF=P7R>F?<o27882L!S5&v97Twnp(?Lz4ry6mxk+Q0jKgf}wLrBDUjl&kh73k&D
zXL(eYq~+zUhAJu<Sd=V>fA|WOn-18{Z8JhDb*k;9lUFbZL{!W6J+?WQ(?gqWc9x+K
zi-cQUiARSsT~R+kl6dxvm!;;Dl75QUe#=rF&xY5gVqcc5K&jQi&@M9|2R%>E6O<VJ
zN1axwoF?A*1lF7%Q@SjIZOSEC*bc&y-?~@;WnC^<v#l8(8j^B_hsS9g)_nOrAM$sx
zfWzuP&dY~A-rg(+<X>`q@Q6-#BSUvbv}-**y2GZnOPs8Wt%lPir1?hE3`Qdo$0D+>
z5zW}U4*J%+deZTmKWF+@2KSaG5Qyw-N#28H$eowDaVgniKHRwK^j}FL9gvMH4BC-R
z1sb)i2D~=YhfOpd6|uOWK3{=Db)k^Aj;mc0UMoHMUG$-HR#O|a|NdL~vF9cU2}$O2
zQ#Uu!)3EcPjer0B7v%rZELp&KYAy{53J5%zOT|?;5Rq?{-bnUo6^*Q*bouHaiK}jF
z3V2j;8V;>PT2UL@v#-Hc=p)p)$Fm9d6KdX4PwSCej6&Z*czm$*Tq$8@X69$eAd`N2
zxgJwl6?XmuWCbB1VP?U&XMRSmY_2)B3_Cbj=8zu^i7U{mt&yJjy}Wi4+0cLxeEITT
z$sj-<BS?$U;%`<{61pD3JE5W%tcE&hI=6C_e6<b@(Thj_wuACaGK6XzR2G?0@y|_8
zhqI59KJ2fFKDsgJeSQXWpL&@&t+G$V7Wgd&mTLna_rMS4X+)Ly{Ufrot4tzvSj-T!
zQFCy9>f&X*;<P%3baxTEcq=2*wiGI?*-%&rLl%4y|Lg2j>kriI-mg;%YCqZ`|NOa=
zm{Q>9@854(B4rcGnj7mrGX)1~tVGI-l$U)MvDX7__Q55hQZg2B(J>n=yjUxrfRhTk
z?I$waGIg129pKG_dhG;b3JMGFrSIwz(LIlavG7mCbQ|*&2nyB#DpCsV>fqxeK3F)h
zc}5~Cymj~iQZGy(PUHCzHKNyWXp@}Gxc2;TDLZ9!badi}27u{T<V9UaztCerL9J&@
zfQ{ry=7@Fo=x_cPqS0}B+}4x+c3G8}>UrrQlJxG~!1!To=U~~Pba&<_C2msOv(1^V
z3%3jLqYPS)Lr+AqFpbBmjsIU|=GgrmdC^kyDZ~TXJ%-8-@xPEu@RG<rfaZ1|v(9uC
zuNUL6adNJMR-SL~$PdJ98(i=i?R$R`@9pc;^_t-zAvv(rsS0`EVr6e%%3i2dzAk80
ztFaw?afETdDyY1<zXQr=At)$l8gCG5Xy=(wWp(ih)D9%HA}TCwW@c<|Zh~kCPsy~v
zKa5iD@F*2DYRaVgJic6SZ<+U3L2^`LK~&vbTTF`cb{zU-pWmd{dA}efp4WmEuEl3{
zco^ALb9|g2;(=EUvZcJpmh)87g;k66<E}XhQ%z0O(!lZn8{kXGEkDds3?`B3>7X4g
z`WL^GbHQA9_Mk{<3sAk#)?PR+m-=N0oo!_U+7zLUW;MXWJMrDQuy=IiJlZ!p+fJ{l
zI^jr=7RXwgy6#sixPJa*;OFOOW^Nj*u8tY~k)##!w!O8LwWbjR#_M!&bffjow$nr>
z`vAw$ZhO*6Q)g1u9xHhJ{08)&fjBKP_o3$ICs;ZKt#b3o1prVf#wOXgYSoja#{dC<
zDIDFzoZcBN-v~?J1tlQ*q*H6;h7alAXg~s-9q+r?A4f)fJOjy&M9BIgJyb{=P_z2C
zXLrN6F#Y{1f-If}Y|^fo-1C30gy0w7>`IIqxWN4PpA^dm*fb7{y&`A+rT>a1+da)r
z@t|Y=B!EVpvV)FBj+d^NtCRq&#rPs&;2rg4gyRTDe9HiwWwp{g4jU8GJfe1fbYwVL
z*hxfGv{o)@#FdE8e9V4(mIWYM8Mgep%yO;1#kIA%Q)|s4Li>l2Y-$Cz_V!_fv!FO&
zoh!bm6LTR$mKp@!XM+~eJT*2xJKpP$58B-o_Y0N!Ccoj<A75E};j+}r$nxc@Z_5tK
zVWsi8Z(6gYGG?UA!;ftF`0!l<pDIC<d}7p0iT&{QmoK;R^WKI~oi~e<Jp5ZDV|(%(
zOL(9Cc>jd9CYeQE6f0=B8!7+JYNXVEJ4LBV7h85z2}y?K2Jtm=ALFoz>YiOJXRJ0f
zHl~-Ams>`zVCai<Ym2mIrl!^x7jvR|Q|lYA3F1}=Q8B}};u5x*Sl-H55LNOeKYnDa
zuCJfh^`GoL)UI+|YYY|XsWI<PJ?}qZCLa&U%rtO5+yhEO$I%{nihx7Z_R&()#_wP>
z6!F6dA!7QzeNj;|6n7O{E(-Q(%@6we(+il>a6j7qefF2Ov(2A;{7O%#JkMMYJIJ?v
zrAz8~jArTPKr+w0F$gO2Siyr(FgzlHGfM!TK=aiKV>#3{G-Q(m3|gb4%`k;2M;%T(
z<m^F#fm#)lTyvrh3AYLgR?S_SNVA}<7GD|J3@JJiEt!rk7~cFg`CZZ_GnwZx{QZMp
zrJbRhi%TBY-N*>T&eMHRMuv<2<BOpd__*n|QNx&xR4T~o&}v3#5`fAgGEA!yUfTa0
zzdBPP{p}u4w){04ZrsdRHd22%uI)+1ohh|pad4COmOYnQpK<^ws}d3txdwK2f%+&l
zom!fyd9}6ZyBsZWhmUVEvSYF%zlA(%X<>2OU*9{}$=4|PI{sL?fW5tAwA?Ct?CsXp
z7PDO9YEQZw#oIUQqh7Cm2vtU71{oL_*kM0ZM3ORyB+yB-mPD7bOIs@oGqdE`aUK)_
zOBPGY{9(Ve{WbVu^iy=Nfb(Ye-hco7+ZddQ2vx*W|Mu;D;i#j6kI}QU?~>;S<ATd6
z-ZRW{oUrPT^$ovlxlKkxA3QTZ^_Us=x=2^fme1$i7N>UGi1nj!PX%;<1UitfPQZb?
zu1bw#POZrI>+w;!+F!+2LF5axU?5LwYH3xWP^@(wKoA9C4(OgB)2s`@&*0;LyXDYC
z!XL=gjBL~#xz09EMbLHuuCiyEkyL7>EQ)GtCRB8FEH^#PpQjdZ3!$P%@5;5JZ>y7t
zK9`;5z<=SiK5_>5n9{((A{|5-)pP4t_-=ZITD4*XK#B0dBk3QMPk#Pg^1$*6CZrOy
zwY3EX1Vk8tEH<z3mD9h7p^lrEcW-yM+5(GMfB0ME%VrzG5Tdt-p|u;ZDKY9wUKuYb
zFO!cp2ITE-6HStk$!Az?D*%es7xj{DF^K+g<a@xndYx}2q*b~#1TDZ6SVu6ro+1v*
zWY+*2nVFFR6cQjGP(<H6r3W&cpx`KAj>pGgfKPVwhKI!(TN+wgU2Lp6k(!_nYDp54
zl0peGs{h9YGzHP{+BA6l3L;W@{%p``;_MJpeKbFB=tsP&EQzuluik4)@ls?R*_EVS
z8Z9rs+BtK!AJfwVNiZofu~jHRaGl$<zyv7#OG~+_yFtQrtnbcmn~zjy9tfi$<M((#
zh8sH~)DdvH7Nm0Am-U{pJPrHjF&mpq8ouw&H>&k&9Kx$Por#H$kB^NtHZ@(Ino>M8
z{G20TYi9?<ubu7f#c(Li>6fe9a-2z3hek#q=KqqDXQvWG-hCx^>m`L0qSfd6J>HNh
zpqiVQ0CgN57M7X{2?!1C>g<f}dnJc^XYQ5v)zG~%uyJtU<>8T$kqHbAHXu%6m8h{i
z0vmDP-0iTwS7Jv`@viVZ4*Urhm;C1-@J2hk9iSFUCw`l>jERiA3v{6_z(j9n^5AP8
z{d<j^6qcrEX23fbo2_kZzW?~4WPQ-u-X4X}`Yc09NqL02r*iv`uwv;K6%_?0j|KDu
zh*I76R@NgE64-RVGr*M`!S-KX4pk8Qv(_tQfx>+E?p=@`$vP|u7=P<q4`b<oUI^qf
zUS8E!U`&vclLKubU?skB-Rg2xS69>*YH)*68MwZG4>tlYxa0H?Ulr)avxIOX7ZXcM
zkdU8DWPJ{Jdp#y~UXLW`L2o^BnKUB2V^4iLHGaRXDLD0#I?w4S{Nk=bOiT;}4gyxZ
zKVP{Zs$}Q_{rl%lGFT7y#!P@|1L#l;?omd^-KwmAx_a&gXf@LycuY*TNIuyEygn}}
z<4h45<6m!}<wSqpgcI~|#^hSX)a(D#ZJhsq{?vXCCuamq7@$fr^b8D4-oO7={=DYZ
zXEGrnA)vbUw}SEw0B@z@l9HX>-D}Yr?oXqRlZV>yI?PpDLv0_Pg^Ch!T42k3g!rt+
z(+Y(=1QZJ00oNBWY^!EMh72F~z_VW;Nr!HDUgaJY)!n+A-VmFu>CCb<L3p)CUAPZ0
zyU0pQceHeb$Al0QXJy^F_-(zvS_z67uoACAAn$U5x(~YPLv<=`RXO~=e$Dee5ItS=
zOYu}|V_{)2eZNqI1yo#b(P1xP*TLGT7K`83U8c415-7pR!MbU0#`mjy@CbanK`u$a
zV|~m8-3lnfxo=PkT3WBe&41V0Vuv1B43Cd{{`~K~lGM9*BQ>Dp(AL&=-CfM$#MW3y
z>MKQ%F>L-QVT;w2@wgHv$Szmov9^vj0G0i=rlzJ~C6iH6triv(474V$t^$sq1$ZGq
zt}}&}em{3gO^JzF7<*Zg`H%DbyO<*3%<kfE2u*s_LB+ysZlBWOYGkOpyZcqi@u~+b
zEfvKW&N~b9^AI|w`M2e{fIzxrey6%bJ^OIg0j%v=&~<0@wW>Kc1zU#c9AK1Bb}66u
zirvC%KeH&i&VcWLz?zo>w60&jek~2U?;pi%hXE>1WM?n|kq-y)xO{uraNckv8f;Of
zne3`pc?%u{^3&h{g@lNJ=_FViDT}+nY?x*Wz~K-?F9uVtRv3@cdf~Y0?CDuU_WCtv
zK5s5dE+D=wqxyRL8vy3EvDs28{!wN+Sekp)j3-}k2w&afHQar&XZYEuGx4S8bOsra
z$ojf5Py!Ck!;Mj|$@5&2Xm>LJ+P46w&{w$BXO$}OMsdYnZ&KLfc%|@#$+ikoq1F?f
z?niP}W_Z888ln`>?Qfc4e@PP+uTwf9_`YaXnj){h`IPvw>!pW>hrtPa`2b2F$SgN&
z55_6Lww<P?TkF{fwyCET#@iYAE-o%gFYem!H;1Py8TV$`RFzruX957tY{lUVs^ymg
zFQn=l8^y1p{=sYSJE;(@GIt3;mS~=z`=uQ3E@4X~omhaeAO{Xg4Z;_W1vvxaoVuK*
zJs4e&Z}+q0+@y$#4TX04E50A(!J9%;6mAtbjk`8BHA!B*lPnkv54=ooO5ft8sOUw#
z9}O1y!K@>mw-jDtc)?1NSpd>Kzr{#e^v2S_PV`z*QWAD-EJM$-bHeCy!YV!yGT^9U
zd<n@zX^6UOfL90X6zGdjco@W)(@l0W0Jmh?(#pc%NgV&el}h3HYS|{1FNPW>y0BQC
zO1S97p)7(4luDP4@y_c|x#69+JR>iv{Jau=Y&&vG85k}?sa_r*Q(7%7Eabye+)t<A
zZRCNjr<+**U*;G6OMP6`hXI=FqvfGW+_|~A%d;A<w~>HJV<EencKOmeozTm)kpqw%
zmsZ(pg7mi`>Obt`$R6@;d(2MZc>zWrsL+GB>OeAL%?cf8iOderjEaa5Sg-MqcxzHN
zW(~M_Hb%RNL+Pr6RV27dN|YB`NP)=oC#_u0bsC7n7?`Unfw0@Y@nAvjLp}c(n7ils
zX9*gb^|cYCVs?#YjeDk0RBuUnx!c@aOtQ!N9WAW{7q4?pE}07bY&mMiI!Ir)nq2&I
zvFou2028D7e4)JZlToMCR4#K?iU4&^p_8Md=iD6mXqgE$ZHhvbLU#6l&CS5opsd`d
z$!oUEVQX#u<dhR|fCU=qu4;~sz!k7}AALBz1L6XRsGp2J7r_Ykb~latbH1T+tWw5-
zRNh@?@8GaDTHcl6KXWD2=j2_kZwWik6P@IQ=O$xS2g0Zu(ax(qegh3HcO@NGc6N4F
zc#YX_s0H3X2a1dm<ZYQ%u_q|QwuP+DKl?|n$254%{662EaavAuTpKw@yZT-Q#v#}g
zz4MHlC&k3Xj8fe7U8f|VMKB^lLN0Au;H2x60;*t{e70Xy5l{sN^4+dnN8SVy-gi=2
z0U^@>sM-lZL;EQSyZQDcfHQs-RGIYMcX^<_yCq3$ENJaN;Dw0WS|$8t4na4js@Lex
z0mu+wa@5j9`(R89tOlGMf~&4Mm}1V?Fd85UK@1|?Svfh27&t)X5MTv-JGqzly;8mW
zXu$H&cc1!W8f=w@y85DOr*836p;MG)2cSFS`7F{f1+pt@D6X}&HIL<f#enF<2vSN)
zwmX7?f=>M9`oKpsbj9>2sDjF;PIkRAJ4UFK3)E>MhnpX+Y;rDu5YTl$8UU-uV$=x;
zl^f?QkpaW~bvMrD6yN!{?2rp>&GG~o$~mnutY0<@M>vZBC-pBI8=LeE^hO|8t(vaq
zaf=@y8P6Q{y8u57Jc&U4Sf7&2%Ff7Oy?nyE^$iI-&eKP%tfuFuzM@_69zaRf+&MNw
z<n-l)J`iCS<pN<(3w%vlKkSErE05OGc*LhK3$+w<qrJ0}7{AiJ&B-6QDF}fBXrW8D
z!r%nu;6XrQb!i>)uA%|O$=Jt<^IJfR?mH%;1U1gULpQf75>aQb)>;1%K6*)F{%6lz
z41e4COG`g{_Keo!bSXx+gUV}Ss3}`?5bQ(GD;zmWJ(@Tfz4{zh_?u^<J8p(h6+jV1
zS8GP~Z}GowOfoUcCu^2CCdI?z;^W5wx*iu6bm(In05~e-4wdWSH@ptuh3z21TR1;o
z01)<iE0ahE1?t$xhQpKdgL6M%TLaPWY(1g^TuEt~C=|+be@PM`nYG~Z@$piVHf4E{
zqK-;Xe|!{#NJMsA4WGhZEFizxa1?wmu_Hf4fogu1K&Yye)PJ*TmrmP>=5OMDqh%H!
zOd;iJm*bt|3=+cC_0-h<y3oY&R;0fsn*X1ls+2cg$Hqoo(im$pUS6Wil9E?72M&%?
zk|0+dL`KGKZI2&xC>wTGYN9;hwLuMhO8>hhTyTT)i*mMbsqLJpParUtJ~P_qx=Kkn
zIO~s{)V%@Qxv%))xAZr_fpiI<1l882M9C+<INEEs0-!(R^kDfO7UihOTL1k+lNQo6
zcMP9Xw{luJJLGEEajc;gjW-LT3rC~{=zRe=2PpKN7VzwD`_Z_(BOo245_MG1H5R?#
zKAD5Us;tI_;&i><8yIA&0f}HCTrxYxnh@m31pcDF{C6@kly(~)5RCzZ?#8H9&0u~a
zU=bEz&P$o(DPAC*5hAvyBvURa+{wYyc>a^)e6GJa2?z;mtxg#-3+{6s<^y)<x^J)I
z9_&%611uhRpG&98Q3rSws)GVUp?&!`&Q6xHp!&cZLrBgw{KFvs`QjMTFR-LU1t2D3
z3U23Bbh?hVcGR{BFx_TnH#JBEa%opr=#A6T(9kHEn7p4_pNE|W{8+e5xZk8BnS5h_
z#bONreU^NHLmJ?g>z1V7Jx*JU>g(wyy!iVX8eTh@NHx!;OWyk1QWlX}w7OaV0J@;y
zOJD_(Ee!8M8m<XoAAUE(tbh6W^V6+kGk&C77wm}Cz~OolQwxI1@dh`%PWRe_76>rF
z6K%B;9ZZ_EIMDR__x=+969$HiP1XqyK|7#=K#son`i7=FT>=Fg(Zhb-64y)s7GOS%
zGBI)Su^}|VN?Lcx?Dyl0Qex^Bj}{E8cc*ve=Z|gP+u8;=CAorBM~OkOoQ5<?hR8u6
z=Q9T{$C0K>91++spP3DeJEqgZ7b@g=`qSeslf;`hfRFyziKtzy*=P)X7jp)*1`<4C
zs?<@>?I=6}$JOHZ*ogqT7%pAQVU$N(G>4=4Xu%*b{W%ZhU{MbF7Fv9!3D~}DuUB>7
z*<!d%H~t#-nhXPU05!>r*_oO2>-dQB58tl?)F7gM*YuL#a62e$Sc0d;-81X^%8Njs
zN8f(#8kp?9OyQ3P>PKpnI4Da75hrf#=z}#;YwOMKDYFY$X2N?AnCPwf(eQ9ZnHY|X
z?Z7T=?L^Uw>3oEdr&hMynk?mDnMofimIL^n9wzFvwHHi|nt<|fwR$`)sJ&gE?}_xK
zNQO)N5Ouu4D=&Pu8Y=33vJpT*0jYl_LyJ|2Q01`v9~ZFddgze(vDC(B>a!()^_|x}
zsf(pB@!soK=IL)3;mt?cud6g5ftBWx#T6>$1(gMjh`xP2Zc4JvY`15oJ2)h8pG)(p
ze*XhN$AFN=f+~Rqk7V_1;zA@5D4L*FsYIz&xgTwVdNi^^7BRP`I6CS!x1HJeHt3;<
zdyb`twY3-tum3<)FEGn}kwGRLC*8SC)tCP-P^GWEcHRLWf^H0c_6_W>ETVBa{1%Z7
z#ob#Rw-_nS1)C?Z=k@kxwlxJ&WJZPh_?-R73~cXc2OHV!+}2%YdU|@K%*o!$4B*Fr
zgbr~XC^U<y@o?J!sHUpaq>srL@0J=3u;>G^a%5=8*i0@-gxY!j(pU?026%6n(0ZS|
z2)pT08=^WnCFP?2WJ5ze7HId^nMFbE_X9nk0cs}$xB^rajm$Ba>y!(AaYnKAR>U@*
z`fDeg8K`cDHgaUMT9H%-MD_Fvq9)e$;^Q1&uPmasw>Q~q%78`ag+<=D``R*t2AFyY
zi>96)u?8Tjk&@m8hA3V^!764NuXk5fE>6yE@W~`WC%I%we$&Nu*sSpRIjqDHm;k}#
zMB4(xUADYesaI_cu9mBd%Q3H&=ko3n;R4qa_=n#?*(;c;XR@lcw%cZiT8(VSHFDUY
z6EOm5hOro`$juqx;pQF_G9@eOYH0~y*r%?Fjg4L8P_k;vkresx`gNM6EU?To;;B66
z=@#WX^B4Cc29m;I3o{KytEUT5348)lQc_)R$AkO((ecuEnRiz(k{<LM0(<bZT(^k$
zc+I|(`)CwrvS>PG&UJ61!k*!(18hV@sO14%kRYxc7Q1V#eVisvCc&yV)m<N|l%d%G
z%cxIYSg~U3{1zVLaQN#LzQQPOe~y2$wPt|rba64&gJn3*@$2E@qA`APUZrXR;MU6O
z2lAnT_{Com5<ZDJf^h}H4=G1nLc$UUkRO1lp)cS4Y_HsLZ9HA;uJf`p2+5Bzz_%72
z7P|;URUqR46uPHYT3qaWlu2HbeAKZu!#qpJn{+`@$uc}#VROJLA?US!nv6bK#vm~1
zl1`cGpltb*+m|Rlc=OK0Wvdlwa`?vRdU!OIb-2o43MW!!5vKh)od0(1t^BLxxw7UY
zSZW1*vFW<?3)<gM!jr7n`mxih)@yUB3B@aVc8CSlr>QO^I)mDaStCYh;iJ(?NVANr
zEQjF<upb+BC9-PkmV2gO0<;wjSq<U04BK0HL<9M&K#T{M=6KDA?0s3_6P|F9{85P2
z^*E~R6D8Ue+Ft}@`*t^Q@%{KwGHc+##f603EZ`EoP+=KyyEp+dw_8)tWqtl91|fPu
zH`G9S1iSNh_oLRCCizQIraxENKE_iR94XkGr$h)}XxDcTh#nt;kU7&Pn7G)Cgn9EC
zb&mCY`lR&0ZQ}uO5<=n*`HY_$PvRim*H4cCd$9NLU7~$0tfNIao06AhW)wc0kEqVz
zC^x|<I*DeFiylSySxKwSt&FC|;sP@MbjmMfk5yb;eD0{LcD_)fq-c|sMELm{pZv-7
zPP8rp;=|u*+*A1`I}6x{b-3yX2nZq;z7ly1>_U2O^8;}M<+`R>_x*$GX!yWDLxNRJ
zR@7znHTy04(t^-cdk8_)ht>OlBPj#G4E-DEt)Qy?N^(-}*Wcrf<6u1Ql_OvK2{7o@
z1|``kuCF7+d;)>xjgctI`8yDcM<6~Qgy3Exw(s5r{YeudZy#Rzi^!494Gl`kg}io=
zW-nimwMzkeeJ17wKR=Y?LE>I@n$Xrydo1w6*5&Dpo&<J@_V67}Hilm8;K+n{QxWaG
zc#s$Zx!>|WCVRTP4`G#pfq7_D!bwDrXGJfXuhRGAx?aYO!Kw{3;y%i0Bd@#};Zl-R
z<(MMma6G!<>Ac+XnR40V{1+6|1yAmLAUWH6c(6Jwo+NzcLn3lMw?Ioq9~q<j53{tb
z{p!$GgN&UW;ri<*v>Yrf(pEi3y%UNyqtU_m`1l=XT7YW2L-o?w!S3c0Tq2q>pi6?P
z;9hM~Ev5iXMpZD@8pk8{Cln-}{>E83^p9LV6a&UwKU!A>tK2VYq<Yd*9p&S|45|C0
z#4at(@?8wfIes6w!p^7L5Mb$&b7=^G0J=mcDxbsC*9Z1ZlukmVAF1|L6_tspsYTb{
zL-^@JWA>MIKAJzDJ2!#cu>p{BvED?t>(p@{QG2NkqXN|m)ESplft~i!#&h}>Xdr9m
z7I3Zb{{<>&UDVX*Mh%pZr}q5EX0M2cYc22sZB(C#viSM>nyu6xo<?>i2`uvhV)cBv
zt&2%EnRSk<Hu>dAOiC1Fa${p*dbJ?B<VQ)l)x^}|WcOBznD2DMuRu^*`9l9DX34P!
zqlrOSO=Yq{3xOqtrn@#p;FS{8{#|<rwIIAVa%?#}#mM7mpuHuMNkCwH$lTTSIKirx
z-gg1;IMG@Uo~C-?`~8zF<e+(-GoSE(_`8^xR^V|L$LZNIWq`xaAfx1EY!whrPpd6X
z94RSBlZC59_kPX*za`I*Gr*`F3A}>T51ePEyp>*#dn|B(MdnV)n?I3y4$@pH5kPS>
zT_XJd{Lal)J6OjWo^5}a%G4^e3=9pum^?cm@G3pSBaY^%vvqRv+V)>c@!A?VBN3`_
zo)RJ?3<PIBOh`mXA3hueTPqN!Cu|8<1}y*(+Kujz3%@?J<xQXu(npd25&^4noStQA
zaatb8H!BVXC|LA-(?Yt;@o3vX8j&%noL#m}%VH|$io{b}8RUSsk^vsunJEXzF3W9T
zy}x|2xH{snLhG`+HC%hT`!lkuV50bYS@}Vtt`|$opslSPH#ZNY_kVlkUmzC<?{=4B
z-S#0<1DNsdwI&rl5a0ohC9P`?v&}ugFkgLIeTmiD;(1LMc@^CBz+ps4?sGaiy7b>;
zm}(7W3vX~TOkgF37LSOcM*mkHutjreR~TDam0Q>AuCK2%4o?<;6NkL`vbj2J_h-ph
zUS@yyp>AO0rxvhxp2_L}xT<y`83xg4xnE|9W%4c35g?%ul440IF5V2L<d=Ehl?=@9
z<7WE$X=BS+Bt4#)o7=(ifVh*1ic0_a8D7-q1m-dY)+XSZSxEL`0cw~@<Zsj-Sd%I4
zyJD9nb96+^M)jFtOLqB0wLyM{ZMnJQ?4shI^8E3GrNZeNu#$lzHM}9`*^K>4(**yz
z&%uNP&_ycL?Cp0!MS%Rc^rInA<ZPBc)15(qQq%@wZe9>|5nul5bz+L=X$`cChLf{1
znTBS>FoH<<V(f2Z$-r#OT@UwVsc$f}EA>b@4=?WkcG3xmt8sBGE#W1RkxCGXrKMl|
z;Ji`f0$!GIVnV`6d!KyG-u%jl1W+h1IRha0vjZt}2ON`mY5e{@#-JROZ&6wRq~nv2
za7pw0-#(al&jG!vYNL8@Ul5RZT<R5z-BXQ%WfnHp#Tc!qu-GB1I&kpu7XOLch1W)O
zwO_axX|Qbkws!`U$52Svp!X+0Y9?!_J&$9eL&tgO!Gx$rIa@R!0u!vNv!cO}1NZj$
zB<{@2%)%)jlz>a*B2mdTq1+s9gjj~*#^Bzj0;TK^GB7H&7wZYY2$r`8sDMCnuA|)&
zuDO|J5z!ZGpMcNZ;8%dERqe?*aD-_WTTcOF!gI^j2b7cv`s1#%|4lJcy*^wr(!CaX
zapnv&03|iQ#0<n)r^&icb_<+943{;Xo}Tgf+zCUGoz?=L9>A8p5%9_rQ&&a}IKYBr
zz-<9az@c2_CSvLlwz)7+o;H7we<LA*<+ofFv_jMI%8+w88~)zende&M*DD4GZPUNj
zBqt|>1DJ*Y4;s#AWijPdS63${f|EyMV~L4C-EJ>vkLJ*9UWnj0J#AZ!it4|A?n(dl
zZ?-8*A-=N~07pmEwIn4ZQ$)SQSYks=bLyjkU4DCYWmIoGrIz1(F(DzL%Ht&Dh>*Nc
zr%D8zYr7A?`}|Iqh{<q+ZYyASsGp`@>~K|=dN%&1=n}c;th%W3YR$l-b$`{%uYm&l
zh&UceZUVN-t5%3s$a!%EQCm4TPSan2beizA<KaPOIV22Xs~l9X;R>WBBZqR9A{&5v
zof=yS0<&}2FjB_I;tZr#$siPz0325pcHB)>`bJFk;)Pzf0>1tJ#^~iSvXiWdi^INf
z`Wpa%GmiCNjJqx5GSkL1T)Iz2R;)O6Q8}>`HLeHLVX?6l=1XY;NW%4$!%nvivq*X)
zqlItcxaf;>H@T1yT#Uzt7p;)s3<WYJzJPIsHU5SV(Df69T=Z*eJP70`kwzOe0KipA
z^p(r#BW|5I0`vw^JNy-+%XUvpq{98$?1PgU1q?%Gqh)K$1?m7qk-SS%N`D)in7Epg
zv#7h!e(Bphu7x5N2a$nFJ@+|a)9dqUDnn${)POz(2MD6V<KmcYRb7q(&c9n=^D_4h
zy+|J{8CsWvKT%Oo<VFL-T=?_6FKnPj9T(lJ?@SU5uC-d_u;O(Vc&eaZ08YQ;qBDW6
zJ~It@*mbW97<xN8{+u*?k}1euNBaNG(7?RmQBgvs?L+jEA<F~h7Ndqoy}v?2h_AEZ
zC5Hp^&NMbuB_Srpul3Z?QZ9KLe963Zty~@2!|@ix0zc#R?v}dz^v~Sl(EkxCad6WA
z-=CZq=u_&$@b6zfq4KE2Y1~Efl5JPf>qZf2b#$}~36BMul-V7e^RDoZ4iCFlRIy}+
zM?|o)#mB{g<1~3Hi8+h08=j}Ui>tm&!S3LYYZP}&OH16&$!G7GY|S!b*p!n^Qmyfk
zFJV1zo*Qr-<n!iZ%!iyN|BK14@<F4^hO;;X9oJqebPNo)v?#I!g933)@St@WY_!in
zIR}w1+uT8TX;+htmD-3aE1!9FULL%dTA1ies$JZ`ltQr6`=`Gq8QawGlB&8J5OGSb
zCnPj4A6hqnqxAs&<wlg5kKVIh&8SL9IIVnAts*xvV8+*KrRMpt)ys4+v3Ag6NC{zS
z!QAxN%N6swvF6Bg|A;VVq;#9h)2yBjs&<YR^W^0<Q^9DJe!z&lWK!ZX^3}8xer($l
zq3SQ);^1MbdwRC?KQ4gn9>=Nc&v5U%q^VUEF96j$xvms_(L;jc6r7PkRw-q+sI_sw
zBO-EUdfLv;7Oo`V$-QYmIb6rHfJ?M!*A`eu8Zl`y9KfrgF`P_eSysje_Bq~U?Nt_E
zR~e6!#?{rt#Ayt*psRCX{6L^4>(NN&WLw0^Ze?~=*|zIPm5(3o-@eU)$-F!_S)zcj
zNHaaSN6nE>`@%lM=ztTl<oi`8G$e$VKXSLXV6!)@4LWm|l+h<gX$iiWyOtE4%!#L_
z^mQ4QNvuIkE1Vn_Hk6l{QlD9Sfy_Bfc4_n@wzhHXtr;se(R%aIUNM+amgaeCxhAZ_
zS>ml>biJWC-rm6Prhmf~?+x&GPu7P|WHB@V?wORJstU?B_6Qsee8$285*f>lm$BQ~
z;w<^&Xp}1^Pouy0lrmuSGdtRWKDe~h{)i4!Fs16O=>GciX;Mr3@xf?Idwaw~DCY4k
zCj2ZOi1mL0PR1+qSzciX$v11`ZjZPSI%t#wV0W#Zz!^&Kgo0x?@sFkFyd~O^Z95^@
z6JjcnJS{6z{p0RicLRqtF`a8bL7H_nUpwxwHGt7!R4DnaLPPvj2{^y<oWsg<a}1M#
zKr>pV1mSwgs9Mx$=7!;}P|>Hy|7L3!*tShfLmak{6-*gjrmLE}yVAF!v<biE7vg9P
z{z*huzt}iDA2T~#E~eun!{{BkfD&<9;N6UwIE{kY8|QddmUtyVD?Y?W2M6!j$%|$|
zS>j?&l|Cw3ST$C*!1KRBzW*rs;h+m~b=cDk&!3%}Gik##Gz1>MLG`pGPLR)zu_khS
z<A=GFZEn51YY*#XJIdtG(S<r4l=eTBN+#kQ7}axkfBlU1B6`<$s=L^_Wuuf!xvzKj
zXtk11u}9+V7aJRV(>D4WO-MK_nFeV(s1V?=JJbSBAt2q)Tr-4d0oWRsDU^ml)SgR6
zp1xNxV_;ezt@3l+>oe-i0`fumG^W7+w)(cD%Sk8tV0U#SSNxKG9vc7}$|MuMKcMq%
zT;a<S2yNvh9kqLQzKDVE9zX%uaiA<?*Q%Tk$73ev(aUD|+?gB`C=Re|L#DpwF<%a}
z3`d67Vf%&8-VQlOtusqT?7hC;UioA|G>5?5g*7?`Bt%kgtGgZ04z4Y$zBY}0Eap?6
zxolK0L?^evr7d7Tt8U$V4`0|!<$yI$!`^=NYsctoPF;uMa?IMV4`v@`)^tkb)--XO
zzFT5zWJo_P!;;Z%4$78{P;oxk*K-5Xnr51Z@18Q&C_aDxbJ`%^VFioLldegP1{wlQ
ztgY^pLkvQboSYo-fP1T^$Mseppp?9h_PQE4vazD$YRs+L6(0@Wt;*IKY-sY@LMB3$
zq&~8@L}~FtEmTZ5yQ%SC&~;gi0uw5i;kmj>R++<zr3+b+*K`jaK`3u@<k$ov7nVt7
zif_4$*;yKBe09(W1}ra$%^^wHNl~pQKPn~EmJO77Kg8DBI;lso+;tJ6%C^ZXgST;)
zoERg&$WYoY-BDL&3h8L;XanX2vVp-t!`3g~P0#AVY=@*oP;XkntY2ws69}xd;IkNg
zfYC&*-@vgx04juc!kDOu`BW?LKff(<)AiU|`a$%>Y!oFS)eKLyBj>Xm5pis{&MbKR
zIK7_}YI~-37_WAZoVM0;hOaWmtPkb8t^2}t^^3MVh-MROA;lJOFyww;?K^npk~V!V
zaJDt;$4h^GVw0@ddD4XJwgv*QJc*M<3{{I-{|3K^2%QL>qP}E{U{rwJrnUD^C8fV!
zIR1#mVWZ~}w*Ug#V-l=Hc2^?Y2tRo?0%jGExw#U)tjTz=c`K4Yo;DiP$6~Sa)EjAo
z5siCO**rv?0_pfH4D~`z=V_Mce&aUVFGQY>gn^GQ@cc6~echE&yn_^KxLT+ef-5xl
zdF;;WzeO^S<wvzN{9^0W{X6<Wkq!Ms+Q=J;U%>a-MrSdQrguBDu<+AXHb~00I2;5I
z4y&2I-n7BP^J|b~f4+)JTf#Hi)YH_^xL;HNEf1lRUTbTV49(8ULYnqe$67{!f8fz1
zml!QRB6qhX*D?;qatBTC1{u$ec3OM+=>1^bIa*lQ@;1Wuv&C4oPVW>AR^Y7Uw=7<(
zY~-|o5&7xUj&~hG=Ndh7Jo+Q`^)M}P06mZF(t*MZjYaWnG{a-H9f7Iii|<5#ZvDWo
z%2{OvBATItR%Ca{0vDuJq0Cd5oXeM8;~eP3^$*yFr9#(}9E=E+7#WxfVI_*aY?a>T
zLv@=!Veh9f1M3o%mHfERTJB}#=K6yJA(o*WKEm2jpS{_|SmJMs+rDS_m7^YcG8Y*K
zS8aInwgxe+#b?p0pam<npYsi*8@VTXyh^#2X7k}ID5zf@Wt%0ipG`(0h%6P9e5U<E
z?ng&O6<}NHQtfUXW9`~17YvL_@ik%Kuq*z13`pm1BqW>8&oOB%cbiO&eic2jod>SZ
zhS;GO_^!+S=T3j;GALB-uWs}dmM}0$6uM367iV}zum?ThR<H`Uw6rBxuF^f?w@UkM
zAun|NYKm`#&ph0abj*HzNUjpiP}fV{;J!a5fnTh7$j@b3on7I|@$Tm3KSf#B5u`AG
zRBz+%UcYI2l>fNvyN!)0mr#p3@<Z5wlwySb8YL*{GHP;cT0x<N3#8kefKr~jfQS0>
z!d5I(PCA_!KPp47b7N;uEga`H!gev$Q$kivC-#jF+RgFA4GSb^Cz0*RkC{<7Lz1+s
z-UqJQMZT@!HC35Fd0=RF?u$M>62ZEm8JQTR4U}wcM+Z3s%DA{i35cp{><&D!@mM#K
zCwFFS5*=<8q`k)TM@6Nr30l8kWK@md<;53pJnbK(=Kl)GZOpyTrDb8bZ^eJtLGD1+
z3!%Hy^=_Fb+5L^IV_qdnNXSBIs{Do1dBhi%8lvUB)o~4$xQ0f)xoHi4Q6McUSGhfj
z_oQ8xVlz>ws7*>_1y)dlML(x)`}$%CzA)nrU{i~b?<p`zpN1~=w$%L};@<Kv%JqBy
z#)6FqZWTmYrKF`xzyujex=WB|=uSmMKstsHP+;hi4go=>ySqCE9J+rC_vd^63pY>n
zCE(O`o##5&I*#|DmaF*o33&2RpCrS}@zSH&pZA(AY3lCQ{rWYx^eqBQQoL!NWu(9I
zGS7to#imob(v6p%VXSJ4Xi3_NZW3;>GVJme#Zs8|X8BGm-!o1-d@<RZl8r+7DSV|9
z81NL%3YQMGk8h?4x|Mzr-IXUZ+_*krGq(}$_`FEr-`5{9mJ19MMkbW8s%U+mL!{6%
zT3E7!s5w&=7@OcGaiWKtL^<sJlM6zF+M`aGFh62(BAPkazBJTx<IGXA>x6lpyKCUJ
z@QG3g7;L*tbAwEIL{@Foac#J0<4ZExRmOvNsn>QLOS1=&#}1fd&Xf-s{Nw~g6@?b_
zBiq~C(WmXWyBpeV1MX&SdmE!t-O}%i-;A;|HSy6$by1*UH}k+%<uD>*#V0S_7|S+6
zcBK&|wsbUiQ;DXTh-Z-Ka4IgI+KdP%N_rY@id(HrF*T>QScg1ftMDA4qAzprAL)H-
z+>d?xOoE;!Q@QA{_=u5MhZD-nwaJC$AZKR(TX8OR8fDm!5V=RN{Jy6uyH;>5d<&GL
zj(Zb6w#BWEDUUhbn{Zy->bD#&<>u$lmti?8FW<Kwj!Ty~aTOh}at!}yeURm_Cr8dw
z(MGd{0^M@U1ksXHNHV?)%$`!p>J-y`l9ON0eUaozQ{q`ynryJ>k0S(GBAk7I;W5$z
z3*G8?JqH)Fcw)Xbfv{4>nYN2j4hy&7`m>+)ff{k4p{c~#U#%|T`Mrx&l>Kc7E7C-k
zEVF95WA4X~8E~pF*Tjf9r)C6wq85B!#+{iuq5AA+q!+`oTxV0LK{mU>q7N!UCLw5I
zph4Ve0XQtygRo(}A{kcG6a*<noMa@O2<SzL5p~ZWo$a!GD=Uh4*fg~QN6|O`6m%SO
z2mPu0c>#U3pszWXUbIVRrgYQF$kL$N{$SGXOsj7(5o0_59m@L5jqz+v`LFTOT6)=o
zLxs`gdd)_#@ke6AXe-?3$*Ws;N^>=fx2^J`7mr27n1zgvhr%4p&f+QAv<hdiQP2*!
zK7dQ}yUjOM0Z(2-UAZNLM-pd`N+8uFxU>#;1&`J8IxBvB-$7P9zvbspwSV=ruhszI
zC5=Bs8K2i`;Q2*XhoX7OKe9=JER3~DMopv5y~cbNBMdf=)6MckDjfnoe$3G<3trnw
z+Cnj;rxsguyTcL_PTrI$Y^bMOT^ADm9yzJ}uh#C;fI5F*9~VD=Z=xP_mSK*pJk5u@
z(UKm%)>b#6Qzrhp%YadqWxl|9*lb5U;)RRJ%JXru?LbDq7qYYUJ2$JzKChpS`AYe2
z{D2!y%13d{63V5ZL5EB~sToFxro=il{Z}`)I<8I2SE|(^ivh~3k?)qjWjSq($ZOlr
zn`NX{!!+ghHG3HZBD$7Bkl!gkVteIR^W$|XL4A8&=D2^=6Ot#oyWfJO&zsrzT+h^3
zrRwDJQh($0r>)0OiJf14g`C>{j+Ix8rS;DCr)%iQ`?M*uGq<2F^8XYd>NOo6sjdB4
zsvNWV^^#^8b}*q<oCljL21OacZH~$B4(Z9u`8;O7rW)ejx{=KI=`N7x$Vu~zF&T`1
z$TcJ7)&^x^bTmKiwK$Uo>K4zHU{S?J3qa?f+~eqYe<)mPyvkS?`ut(81`mf>_>R}b
zoE~~LMqZy*Gq=HTDa<=RpJxiTg@)n@E%qtm>#>T7VfNT3MAYo%m$X--PhA7&dV{K*
zeodz|8h0k3qN3Oi(#RL#9TXOrLpVBiRHuAcDV2NqGBQS-YdCc-Qm$sdbkl9wC_lic
z@VMSGpjpdMyCnWAMmU=LN4VN^S-NJGHiC6&TZCDi_BvK7?t)~S@n-ZpW_&}u>r2@l
zE;CAcP4n3|n-2!goB}F$;!DZaVl$Zk86-FnGF+U09;F+h(<ljw<_~pKIS=u@uTAuU
z)3E4p5$$aIu+uDU9Zo&{ny@0;a8f-*<!aq>7C*zhAFr~v=*^n?9O>>jyRZ&|029S5
z+6#=bi9)?!warWRULP1Z!F_0a&a3%pk(28Y7=tImv*tQo)knI~HvBI5=BcL)bU&Qd
zVZc8X_T<uGq_uVh?toN2oku9~+SD}8`q*PzLYKKEn_KPM;%};ylcTk|7UmX+OO&b|
zs&&LNVbP%r4%>@z8mzjc?W?%hla-1il`P4^((2~w$dXkjrrn0Hc~6gcwLv}fUEQEW
z{3@LBqNV;6UQug4n^U2$^?R%j|KcAIkcpYk6jrZ7teokT$<JImc<N@q+LtmKRMF7z
zi4waycJRcw(`uwJMK>vNWVb)7LiEp4aq;$cOpKaj+}u`6{xhe`89uT!l$l;Tztage
zIy-AmZ)Dmnz8^K%{&>$<>~zD6t<siPiHS^*MkPmwqgGS^g*p1aUckZBAkU@A?Uzl-
zZa=|}YmHwp*R-U99InZZ!O7M{1#1f}ckX*GHGLzDFXct{>Gf^a`Klh+ord3>!1-zv
zwDMbeCU2Cs<jx|;<?L_R^Mk(I%0%JAdz_MPo$u?fF%&=xnLX~K%867@hW@2>Y3oJa
z@d5BDAZ!_*!w0nY_XE<>)(#+-DD_xORKQbvvN+dMZSxcNrr`Rx*V2CTkHqn+$a~(v
zO%igPiPWlLFsT&o&%pGf?cD6Ri$soyuJ~z%`2ki43KEU7ZI1qid7($VyfRd4iX%s>
z&5RmQ$s{kE(1uBX$=ythL+~QJpQMw88K&O@I5WI9J`k?JUeWNI5o9357(evH<6I^D
zY2U!Qn?PEL<2zb3`e^1&LPo+C7KDkEq$fV^94dQ#*g?#}$L{H8)Ri=0p>p$=#dwY8
zu1p8s!P+z2U1eiKR1y2selr}vW$*Bt?T#Jb5mD`6x4VM$=yoDN+7n?|BPrRe>$Mjc
zk@EABBEsW%L*VB9)})IEQz;VHqUCaxB-1bX%=vLFemZUsv+k`jB3yrdYKzr<aAIQK
zUqNt%Wgvf5(Ve@@EU!I|2YeLJMEfxwd@ex_{1k9#UZ>y_NH_ip@r;Yg{~9;|4Zn8R
z*Q)>c7ICvKa#IwP0xr{owE0?u)vj#Yurrt$`&EjTR5@b4BuGiU^T{5p--Qit`gKz&
zm7C+*2%~CPNwvA_V7LS!Mf^;Cj^bP6y*1$>Sb9y9;x&816cJC{7nmwO`TAD)_;~oZ
ziWd69y%>o|!v(z){vY)5ZF~5PWD&9hHPZXWn<?(XGUWV`CZ@YqTXbPAh9idKM~|4#
zwtpx{h(?DBdAOapIuuX7OBJ*2r@BSq1nY-bXClHBY^IjOIuGq)BO(l@C!Wz0lag{w
zYDjsVgoWFVG~pE&7OsqEo5!oL6>A?P8@%SX8Yd$s_uN?0hkY-u%zAi)Fn<1Ww#vF=
zD(=yBO2Ic?DrF4ZEQ*{&wmEa3$(%O+0nP6`5uF#O>}OWn;H=0#%@FyhsiS&yC^QW_
zKZ{I$H=Q;AIxVGooLk+UbsQJ4Z1jLB%MgQ0noxU(^42XDc`Vzl32{OSo*ptG?fP#K
z&{vav4s!PwJ@MgMPT;P-DQ4L%9oBoCbVT83HYt8F2MQC1<-VGI!B)8>LASMirV56(
z<_gX<xx5Gp-kiyA9`W@FK6IX0>mrDH)HA<J?6|toC39aN_>sskUQtIoWXBr`BP3-M
z39@<l4}dIiU|v_ay={;FmFRZJS<*Y;T~ob{E2u)vYvH=|*8jx|T-zMaxE;4YTeEA!
zP8l(1XdyuhQ`Cmby1PgDx^#t{Q-`fXR$4fon(d>0>Id!deBHUIbtw&d=7%q<b5rXa
z=)?LFO%4uR@bM+#AQnO`%ygt@Y02xjUBDGW5>>wCFOlASFPvNJemA)9IzLx`aY4D)
z8p#~)ENAjpxqmVGClzJ%QV+_y1mV(Ar>TNRABZrzSpIg7_I&ZdVFadEl{(0MbyQ8$
zrMwD2Zxj}HT@YOr1S6<#aTHuH?`CLbo;XZ;{{FPV^3_t<Q7W4GM)+m56)I->W9=fO
zUHkxB<U39Mp@A&*>I?_Vz<&m4?<Ys+s->7PuqYw!vVQ*}mUGO;D=*z)MwC<3VM%xa
zRMzLdqH9~*n=y~3b$kM$22Pp4&7->*oD>igWM`MXkX=#tJvo*;<Ez!l7AZTGfPJwh
zis*Na`5RL*+k-5v+lPIB@>UhoJ*$QKs~-i1u+h288~8#28_J^k#zFGI>#L4a;>NM%
z`|rOLk<M|+_553sCP_O9=Vv$PayUp5*AR)h97>Ce8)e^aCy@J?k{k9aWiv4qjb7D3
zw@SU>PJLN+rlFwlgg-;Co$a8HoPuH%mKEj~zzK`a_Gq3Bh%?mg9=k4Iq1-^Ho`|74
zyh*n#^Ml9vaZ*M`%<7FWul#Wy+x@$i)g#Yx=PnFn{wNCPm%Kc%v~aLP-yVr0CA#xl
z3e|s9PLei3Tli2if3A(S^8_#I9UVRUW}6^BRk4IlxAY`66-5<PV+kJ)!YeW+wS5jn
z&H6<|s#?0u`+MX@mzKWWY7Cx?QPy6+7!evn_vAxq9h4DqaU_&Hii)=c6RvK^dFq7y
zQAu(GW+&MlR#O85^zk6wuH{%$Sq$#*u%HxDDDes%MSoRM;uEtu)aTDy&OZtde@e=A
zJ`{)^o~ph}NX~6$(w^*v&>y6YW<RTn>7U25UHi3Mcj?IN>_PMOBD7c0t@Mul!`sq#
zooAG$4hUWl-IJD*<5uGsHi4eP_@#i#>p6)DReL~0P`sHgEFlUe0P}zKE_mzP{P_dj
zRsQmqy+xVN>8^(dvM_CL^eXa$?5rf^vKk!bttN`Yq`J#!w=G}EB?o|DJ%g%bAaAme
zO&`?zH$BINUDe`MuAJPxdNIdK+--fNT9=Cntw(K7z?(<T`?_F6S2E%IBfw~Och|M7
zG_Wp1&z{a^sXryVx;jCD9H1=bgH{9Ck!^X_QsZy^s4>Xja9L~Z|Gu7}$jxB4HRGzs
zYc-<A1#PvDO%JMZr0%Cf^WyAyH7VS(KYwF(^0>iWZl!%$T54=(Io0U+%X=gND(6A+
z6FvD0(UlY<g`Y2BtNZd-drKVxvGxy#OASI&8Jn4yR$vUC#cw|H@~O0-JS;(^H*P39
zllZp@Ia#C!warNnthS>fBa>078HyF=x-B<eO0may=*m{e)gH?-5ke1f8}rmTJv7N>
zqP=d+KO&ueB%(KebE&ny&feCx&dGkMiPPoI*eO&6sMFYgb1l}^VKhJqC$5-Ct>cwd
zek6cAEvE;!*DAc+nwyhuG_O`adPJ92YijN<87AKyUa(r7vMU!f097=|bA%jBQdB2X
zZJt4gb9m8?lwD9z$k}Bg#x&d4i`&we{eZh4Mk^Cdy5~*ybKepL$aG-ZQ%tIwnQ8j=
z$>OzARu?=x{40jSge!ynt0_t;m8wuQgj}Z7E%LOJKl!dSqMrBM#M!xdqtD1-YvUhb
z{)Fs#pu_@V@rc(-A-#0ZSl1)JOvS=tETm{*AY0S8XP*;s&=h4jU6no_o}g{R87pMt
z=5y!}XqvK%Q&{|9!}97pxpUK(8mZ{q=<MxE2Qy)TA*nZsMzg;|<od$75fn38HMZ?~
z@z4f?<En-_*^)HR`str2o3fJa?Q4?xbV1=`S?UquBey(<LN7eS+f%i|W=JLf(45$k
z4=0x_@3U2~#fH?jIXKvOI*%AyUXqmh$vgWmeK>ba44jmst#|JapMIN7hng}qQWGiw
z&|o!o{XXNqr*R-Tb$>b^b4Q3*7}JyKA<3|zdc-`in>VlYAUN#hq3iQh%I1*|$<<S>
zs`kPI%HiBk7U8_?wzHH>QN$caQ{&1t2D|3?AykHv-u?M<a^tn8xXl}_Q%OXErt|kE
z<Bo?dmM5h<)Jk+@4P0RSJ%yBj?GSKD*^AJ_B&-tkTzgr;pj0L8JecKjmii5M6lML-
zbmosQCwL*CMQq~LoJK?cn^4F}XX0=!le?1Nz6$LoaXousMnT#KN?@@CHg+>pf?6Z&
ztE;&DWHBX+S!s5$=3m!!t8b^pe{A;aS+6q;P4V%;5c8eu0gu%+CnNjl7}H^9LDGx&
z9QFQ*?Koy`DPyqcnOraf-nW9{S1q}cw7O>tGW7NW_H>U=SXUa_*$~^4i7VUd0Spve
z+`TjoG2!8rE~~PVmVgTAUF}lJq&r+5%S<SWFi=n^)XArDF*P@*WtxVb2nDajm-bZq
zJwaZ!b~xE?P@{~<&4!tK6~-fVI^zI}@FIfu8jaAGO`VhDRT}zh#;PahlRO~7#_^ly
zM1~wcjY5DI^{h4Di#d)`BH^BFjkyCZz+JQu#lHLR@QZMFHrA)VioL^jg&Ew`a~aI~
zDqN$y+Ib-LR3U$5ph=UXzl|A9lJqJx*mCq+RgCbX4DK1p))!K$%L5^ld@pZG;%Bk4
zwvCpUW|jfJy0p?p1e?ngr}*M^PQ8@K*m%pMbP8|=-2dx6fdvC*kI$a{1TRIZiFh+p
zTo{7sirr1$u^3$jT5T&G61EcK=SudUctQi&eYhV>QkJ^5i=)4ky%6Sq#%~Tbm6gf#
zL9DVlzr}<~$_JFDzts}Mvhp;6hW7ljyA2zUbfUKQjs!2ewoR{+fbGFy3xOO9+Gf-G
zN3gbAmD74^(2G1RLKxImq^e$@5c|6M@V-d6-AOevf_S9NT>01+S!$$}TB7XYrk9Dk
zTPsmRwXW<c8_Yn(UAyDuhR{oQEHfSN$<N4ipF0lAc5SXe8hfLOu0&b9Uf3(5^K;d2
zm~|x#S5%lEoSsI02@IWMaNDI?gPsd?;i41}U6<8tA4Xx9?d0~<?M_F^-&9%oxRwc6
zB6-c-J2464<Ai6CpA%Yy3CgpxrOs-qVSo6p_a^`va(vian%mU(jD3rWB3$r0XbwoE
zZql)hk7qN@Gl(VGeORbR=^aL|A}~2+d1?8dUs!I$og8j6yL0#!Y_5iXAt@=T@M7mt
zJ6j2qGhghBut3^;_5WGiCyBY})8R+loh|<f`iU{kvrx`Z{dHdzBY&#wghL~=t?bFT
zIHAWpwx^>*g*~rW)m~nn^JYGA(G5w%xqGTH`PJK>CX#>sN`)(;<&Dnl2SV4KC5^t@
zaP_%s<o#sF?bIw-tINEF5N=j_^D2Gss*u}PgQIwcFJbS0D;VG0n=y`ImL_W2O>hHM
zpS`dqwB-HVcq_6{_7?T!^1mAus`jYC5$gzupK<JMbvYxII?8Fs(o)2W(9hpIMpZ^o
zD}=L%n~z^|p*!?btB(xzq2`P>x=G&9$VkjhGBSQo*6vbG+&oc1mYWMA(RqK#Mlc0;
zyDB}VEYLqlF`%YDLE&L+oYSAJ%qYcpmD6yCJdGm#KRwE{e%CA04n}(lp7<}2sw!eN
zCyKwmpZnzT-1vEV-q?37ZpBMti|+K3&pD3=Mm!@euU*N<`W0{TIFhpanpC+XW~`J=
zUS(m3-&Rz(tXMVPbwIieYuMU`8OR2b2b15iM^2vp{DY65$IhN0RQhJ>9&~bVpLcSB
z21-a5Y}%Lc#K+Zv&7mQ#WYa27m`j#Da_)6=-*#Gd`S<VfW>+Ue*_i}gPG{y}W8%$n
z0}o93{;Hhm=4cWDeO#Dwnrvlf;eFhis93GdMzg#FdIfv|M};!YSDna&)`<Mv@q!mU
z*|<BaD>|GAR{_WEP2GiK7p8q|L;GkTKJERKWTy?0FD4D_<AwRruFK|DR=Uy@{v7@G
z&qzp7Um~TAjGhRoln+Yk!<yDlu*dg*y#U*;0RNY9Jje$U3>+LAbIaV&)KkIez`PWd
zuN7f6);l|3Cq@FuRhFf-gVng$1)%lPNm=o2cNJ_3)^ddEqA8VKmN7c*Q}6d+2?M#i
z)z8j$7#hBpXjRPx#ZIm(%ZJ<aRYenI?U&u>JCBsGs!gq}&+-*c%bPjJD%_IZuUTrA
zb!prGQD_2fhenxMcO^P$!n#`%YwbkAZI*#-kNvV`3{zRxgNQ=?UcLhYLH)Ii*SJJd
z#U~9cowrMhH!0QV?dhi8yFZYS@LQ0H|6J>QE>(aL|B59$9FnP^srOi!j#La+!U0BK
zTAI<>IWP>D>Yyhz7@_8ebGnH8+)!8DNnqTCm6rZ4`c~D}l5bjxK{UeHXl(~pHnw>U
z<nEZujT`dN%BywiE9lW-SNXC-QPyI&7`)D|b#0>9AsvuKocv8J6$XuR%{v8@0Z&fc
zR>9&}K*Mdj1d|jRA=|dr*4`=9{n(N3zO8g2OFfz6Y>X2MJmZaX!|l1{_hRv`<2`tj
z+@WvZy77R8MR-Z8&V38+4R(gQ;?hzql%YMvx6;AJ!2<IYPcGZ=?4LE?ABi9Y&Z-kX
zeUcVr>`bh(o>urcg5ObJ4<sbF#ypP{38HRG^&)Wx2|T~H9M<N7mHyn^Q8!stSgayP
z(WVg}Y<CeK=*jXvU(=ty0hjjg#R4qe`H)0mbC<n!ope43IlQ1@vR@gbNhgHT4hWG8
zeJHi}JgS(JN$|~R@Hl8>qE4(POC4e*=GMiW4O>gK74C3lBw0M4cyZd%cDSB@grSlr
z+k5cfgF7XEnOQGQjqa|#-l>RK$DzmSuE@FnZ0wwi@WUGh`7O2mt#9l=G|?Ap(&t*i
z9K9-puQgI)It&f*+qe05rb3C0p!a9Xw4~Cm%-*@ShTsX1dHNZDR{UhQ@hK>eVDJsa
z0!z*4Z-2$NznwmS4?qR+*eX&+ud4!NCG)r7?5*>fw7HM&)oR~YOBF}|Qk6)lI@BO?
z=)NyB@py+w(_k786-b1XRz*&(cJ_ztRhcbKiN;?o-6~Z@B;0otrSgtDO)yF()~~s8
z2iQ*R{niqQ9+_LeHWgW3CR-_<JU<g!k=gHlC%?ZB6{LIXLOZ#XH+{uWzxmgaY8D%T
z_$Mwd2ZOZtcbNMHr{Ipc$^i#@W#kJ_-hc%<tt!vfKN0EkJP~)cHI^J+aQ|D9QPS7^
z+a6|cFB*S6h{L#nlEEy5`GCHqc^Eo8uyahF2uR3|fZ%j#cO~57b%SEa0}?hF?t}`3
zv~Kspi1@Pgz8uT@UX*j!TNiSL=M;;P{mB`+hjl+C=+o_-vIolbFQFsn7{5#$^?dzU
zdlSno=Df6Y5Ll<Mi^bmI%kY}+P{%gr8XWOST$H60aeV4Yg$+$Dk;})R<3gomQ)M(A
zn>M<8dS3U5MJP1u$_oAi*wUku{ND*e#mmsG$3K&ejyNU^<1R8dDm9a3?8K71e8jj@
zW{d~k)pOFu51I3O=$m<x>+(dA+agk1XvI<5WU@30rswl4gVds~$Iz0Qeuis;_pzBi
z_Oe>Q!hi$FepvgL=qfIHL7yWKl^g8uf3hBOh4upx>jIHEXszU1?lB1p(#>U|quzWp
zT5+v#1_x6_xqj~g6;>fn!_p#Wp3|kiS}Hn!pk`2)AbMm3l#lA_nwqh3vGazlXCzvB
zt@oH0s_)-VHl)2N0#lYW{>*50|7K8l*|YIjz<{b3Lz7PxMMgrh)p-2d_6hrPf9jtU
zf{+2FQ93$?ET=jGf{;)aFPAFlv;`&+*SZujR3=o=RWmdHxGLbtMa!+omlz&yE42Cf
zmjX7(ZLso1=M70Ugn&X0RR6BG{y>d<Fks%vf~K29DY(LVR<v;Z##$b_BiL66D;RhM
zEQsQVdo+>V*UkIPOv?U2KuDmt`~Vr>^O);NbLt$6N@L!NBXmuUBUzPsbid7I5w0BY
zn9YrXWX*Dt9)LC+!9jr>iv_>xU%#GBPByqI%cQ6{EYj@r^yk%!<>A+tq~zqT69)c6
za2<uCDl3&4wq?0AbqbhXpr%JiOW59Xc^R;>i~*^sMtgsW2Cu517Iqo34*F~9_O@44
z>hTMn{;VIg95d5L-g9HE(y%s`laM&*Un&iIz6QlTUdZL=5{=Ap&&FZALbR?yx^p``
z-24>BQ2^RgM|ss)KY2jz@t_a~%z?vX{;Zvewa&-COb^zu3Zf~g2iWdn!nyp6>V)yM
zT;bg{;o`HYZWXp;ILT(ql+o|?QB7#ZeAWmsQegA{5n#&TbpaPfhaOBxAY9U_pMlwW
z7Oz5SaWNevrc4n5uK?$)=ff)pn3=ARYj0eAH9w8n-7J>WEL|6J7MR+ry&Xg*SZo^c
zjx5l;KkHuR0Q5p&HIZc!sTgzJf9vm+KWYy{{Ofx&NUovEs9KM2q}t))=gp%G^nuHP
z*{?4Oy%E`iPv;8(nyc;Rz{uIY?U$Y?Kyn9qO7DejMRc7N``spzrTRc2WN196M?}__
zA7f;TFXF!Bon&;vUNPNou5VTxnUqv(F;DK#2a}(;he+reP2W=mU4T^dq`lvB{EOm5
z6iR(=(B5t?sh*(Q2JstBUu{TT+aC>+a>~o=Qq828WtY`py@t-VoG&b(-o9Z={p;85
zN%2Be|6{raXwRsw+ZW09UddN%EOosB9rCs?@7WO)wt5v5|K<})o&<1|&eiQqFLi3K
zH@L1@w!IboGV|5OS8QO2oSN&FB--TN3%}QlD!t)qo7q-g@_s_hai7XT=(pm&$lf6v
z?zt<q?6N&1*}O3qH23v$?YGw(I^*;Ce(zJU;uz!rbOX;X1X@))hi*)WUscsFcQZ!b
z7u>-L_wQ9JzvIx=F7hlQ*3$kwUu7~qm_xUBKlCTNmo>D!zq@T*0F}hINOxKp3Q|%%
zNet5suR0x<@)FbjrwXn0Vmb%$!(C;G7S^4j{(ZqokEr&48T9sr(0X0&qc;2vrYn|H
z$LwK#C#onhuA4)alNEdE!?pa#p~v_61Ydh#mh-?xF6`&;%1w&nog7<eJU_WATxvy2
zYFcLD4z-wn#9P`Agnc^EuwAS;@;rziD&IHbzn;>oQErI-{`<X6N`Tpy@UF$d$wlaQ
zif#XR?n79*K9mq2Zw!5a{JfCM%4VdWKyyhaz+(0>REwf@{&n;(c|pNKWX&(VE41|4
z!$V^{2`*j3TX0OtQZ18(H;z~)vedluls#c&m6v;IJGKa0VK1@R{B@{kZ))nTM?ghS
zbj;(txASqjFS-4>>B6~(RI@GU@+-*6*-3w5T@om%Ru22vo3CM<SOoiS3fXUrWM)*L
ziDj@EgP9Vt)cEdj`p@ckokwpv1VS3K;nrU5V9VIrax@F<?``BFuRreMy3F6hj})?u
zKs^0?xU<Tav8dRFX(oHn{IMc-cv~W^MM_;;G{OD;0UL4e6INK1g@jZzS~fr&WVHFC
zMkn!#i<YaaICy_AKSucfW~5s%#k~S6F$wQ4wI1l+xcOVPI2!*fFL%aIpIg*&?gl-g
zE%K!qlPSu5Jic^o(|qE&ZLua&@ifa~vP6|AvXmzI_@IZuX8xXT^n{j!tx?O3&|3nW
zoXx|{-|W&Iq25%2vM}L4yp-~b=}#n3gxoltz4v~2xZ=uLOcE+d^{!ai{nK_r?}rgy
z9(=rEV0Va9gA^>a$oURvHjTY`nGe0hXD4_f1#}rLZ7m(lF*pLM7p$w`htxG<;MvDu
zYsdczo}D5`VQlY)MgxQ0hzaLZm~SAubRhcp7SFlDeM;6Q{$kGYJ2FY`UapUMI4OF`
z{@=iU@XxpN@8UFUI9^t(aB-1rUT(9xa)*LjQIQc(Q&CajZ}f||eD*dDi!dWUlVFfA
z)y0NpK>l}6G}M1)n)v(B4cWGraz3@KMHXMX;%#GBP*hr2{2!p`AtDWdzE^z_L)@H6
zhV}VRko^!5MWP2mKH)kSoc=wiGg_Qu{`(~EBq8t%uvqLZ#U2tIr^wVu`-4CK`%Y}Y
zbx6dC`W0C`YHjxnheXP=RFcW`KUuhV+RUY#?N4oEV~?)<pnAZ_&%q|5`1g7Jh*7fk
zjzT3RCB~w0$_<+3Vu&LDK2nN8-31j_Aymze1R2kIQ!@Mdzy7*AVFA|)mOQVFQT1>a
zVn6<crQnFC+y`1;4&{{}+HaG%&wu@gvy!2ARBTi(PC3h_-Cy|7o$Ge!cXNv@!-5r8
zy{j&Y{RP2z|H&wzR#P9oCU6nMJUndp9|IxfmHq`4B>Q0H4{ds3KPB?>|51;a+2S94
zB=sKaB@FZNf0kD9<ob&_-@n6a(tc0F`}c8QD(QK@FeaSJs}K3_*XWqpf3&0*;aaOs
zOAwy_$itf?xAo?GRWFrSZKnM9%>1ts6d*$)=OPUnFJA1t46Q&@7RWw<gpr;~WePkA
zy#HJ=I8G?xyFUT~0uuQ*^2e*3e02zd0s~pn&=Bw9WVwMHuMDZR`mXB0@qa%q8gYD;
zoPqdOQjSt_D~iKwr(bn-Adl^*EC5hV8o0Sv_%rgAGK`Zv_#QnvE}Qf$0z7qYEw$&#
zA4clEy)Cc3YNwJYtM8|-Q?cBW9%tI^<h)S<yIY-Npd1uE+3sCfa8lzJ8hbLPwbcL5
z`D@$XAhX)N*WDQ@83A<FepL8{o#nxFDO8@QgFEDL6c!ivm7dc%s&Bi_w?v7!Iav)C
z)AO(@F%RZzmO1SuPA;4dB)^eD&wLhgz}hy=kA2pvJ_MtRBBPwp(CDg)PNlsha}jqD
zArctO&)_8~B7ZkFE`DoFBh5<^-YZ+mSZbv4`V2#z^RKb-PdrEE)~EHU__x9%2wWXp
zTwQARXQaT(40t&1p`rSEkY83}mxi+!&GV~kkn1A=q-JG(1PhZXcCI-vnibho?yrEK
z=c{wH1>qls-%-iST)WeFG$s^U)sD)EUdPK4z`rO-bKApcS2-xQLQb9(inV$k{N|%7
zgasNU7N*HDmnp^4{yrfbC3-N2dhGP0%v^WoAa-GQ$N;n`^jh70efCXVUp<a?j^-DW
zY7Z9Ti;Ih`AfV%Ch!}I!U1lybKtNUUPESv}^1dGK@ls?4vaqE$ul1C7bnaDGzZ1Si
ze$%b(Ub#JrE?u1k!^KZ`M8`TNkli!Cu|1$mvP_DKdINT||2+#%cotVKUvAo3;xsU7
zi}@Ov2w`AtR1zZp*9%aT6QiP_*c;UKqJCukDwC4XgMwYH{1uyo`17Vb;FcZl@K1E{
zId3F5`E=ldoe>2{@K@$$eK}vXSLWteuQQcbmOr>c)&8BF-z>-E9kUA`H>aZRe+F44
z8+de3jkZxZ9PfXdOEtu6ER?2A2oHCi+tg=DMW-{(M}&oavs~pX0sRqkCs?vdOAA$`
zBcJ%-X6^uLKiXJAq7nE!rmDqG4`Ob%PUic{Y191gnt$^;XUoeRBjmh1gZ^f);W6K@
z3hr2WY_}b>fZg`i4(4X%IueDmYm{0TnV1fM9o&=avizI0{~h0tER}YTg|=AW+Std7
zoV0P<eEWvPVE$Xda9Uc1tn{29Z4XjnmKGKU%5-bthI7F5sjm+xsUZ+6rzc0d>*Hm}
zabOFmp=SX8CwjD2Waa|6Xdtfj(s+%Hv><X_R&&b$sHWVuQsi}_oG9#sIi3;whWZHZ
z%l(v)zQW4GLbTMSVCtx+NMs!wQ7?CouIDm+NnOl0gV7Sp?Eig$k`3f~rj?pIOT)9S
z`#W2UosGYKvBrq$QY$PkU@+R*(Z0UErIrBnGf^|KS1QKfLN?l~blHSl&9Z2(89M;o
zFebVybdMQsX6M(0*F$bXGS$!>_vN0<2*%ZcY;z;CeFlH^;bGN$Es*u4A>Wv3tQ5X!
zwKu=WL!59OZP`_-4Y@3TpUkT_WDeJJVDJr|dbg8G2M7WbwqFX>AiG7y7V>()tT(NF
zAOF?|BC5mL>tZjx(Mq37%m*@j!ADnWHjZ$DD^yC0$L<^HZFi<}-P#)0C=3!4h+>s*
zwW|5k09iw#hx-vwNi?^D_Y{A&5qP@o3BszDcO^gn&u^_vcJ%L407=z7`_M!S4h}dg
z_nWI;x_GhUaw6C=x=KNOhaAZ<1?H>SU>>*)Ee#A(l!9x|PBqycosHRLtK<(PXnSrX
zitO%wV2ls>Sgupv)6$X!ZZd_JvWOb{<?!n2lcq4*wswLVq8;}43u#7XAl`&8Z|07S
zOXnMarTS~8$qzNyC0Ld5Rh=9hl$m9_hQGjzM0{azi;9ar99hlxI9e|oL310my=pN8
z=PhX85`-KSdb3|&1KaQM&wGFOLmZ5NIF;V|co9D!gWEFO-}~Q!Yot)G&K-T9Rkt!n
za+YB^b{X}Iy%xKY%~7*ie;iCT&(?<qI);t4HBb4>&g!(B*hz8S3&_Q?TRa8#>3Ah`
z85SI9D>ZE$Eq`G@AkW50Au4#+fh)2%W=G?``8GE<SAhX296BEByy!6qCwXKw@jXQJ
z^yRukf4Wl=7(SbWOU&#H&W{{k@^*THc*3M5!>T%-f_Lx!7#wuk-wbQXeJ&xPTVeZK
zTy6C7l?2I`FRk~i%ML+6^Y^{NabhtbEWlbFpMkM$qSotdd$|{Hn`UZx-lcU1ytDjo
zu!c;Ka%9&V-A)p<;l5wzheRR)646aW;eHatk4tptq1QwZM*HUnB3@oj-g2a4-gKS<
zh}gyp^nD^ydga8<46T58+p@E{dDIXDK)m4;MxU$yRT<iyYL{4LSPhJ=P;uepx2R5l
zYZoB_p1VrN^_AIK#cUNeIgWgCUbB^XQIHgG)EotC5D{FD-&)OwJ6DUT43wyr<CQx*
zgOgneX$VK)YmlWhemXek%&s9vg5YzP%A>0~v{JT1S0p7(7=c^!_$bNC=#61t=4^^4
z#|E}rf<{wKqv^=V=#9g2&x?fU8UVO}iLR}aqiI)KMn)LYENi{I{#(bUkjBZl_vcB^
zx9-n;xtfd&45HX3+VCUy-RAVcr}-pE+U5?BPTunc+{gEmT}_3T2x%cVOit<B*jRNa
z98&L^4nj%>I<o)Ag-glzQyei9Y%c0aqSYLJTB43?<rubq9O&tOm09+xuxb^9HyJ#F
zrV~!8u*H*1)lMzUeEIvSZR&FOP^+yp3Aj-6m~?qxxHJG8_1TZN*{XSzVxEuK*kmlX
zV3f;H=DJbsbe&2lwaPVuK?ba>kQ`~Y3bCw$7DLu(X`sru?JX-hM@~kupn7|HcbG#c
zMOi!h&HMflqELd<u2z<dv+MsnvJW_E2@Co>^+%>{ef+M4`6ZLlIWs(b2t%}ihBTX$
zh5)1Fy_2Iob5($jd+t^k`w>y>9%ko5P8uf=PIHrXTGzPn)FRTQO#!DgeTV|A3f#T8
zst0a6X6J^MrLTTEE<4KWt)#ln)0<y^B5u4+Hkfl6t2StFzvd+aWZ}<(c4_~uF4n5t
zJvgoPJqn4v++5o$Ah<m~K5;O2r`R9(lW8}PC1H}Q@M;091bTPkaJOnhK|$eYZ-avD
z1``MD1}TxslQkZM15Rsw&EqF&7^UgKpR$x<U!$|(7ASnfQmstRi_AIV0(%J;vjWq*
zxSHR;ei8F3x;=IO{=dgBgU8P{?M(xDmR6Nf`zNwah(;vs?HL<8J^*w0;c_~f(v?k#
ze-)OxSG_C}c#VG4o<O*QWv0smuy9`|=r<vpPN!UN`e1AEL~~zEYwf5b@x+`{s$a06
z6gk;I`CrZZg_&FVQ_nB|Tl0eK?8vbpoAApdllv<r*=BWs94?z^=|Qj=8od#J@q#I8
zS!1ch#-K4#)T2_OlRAP??qIf4jDp8x6Nq&X1H%F>hyQQae0eEnqS`H_!s!z+z@Y_9
zrhXVFx)^n0#z*jT?S1|HyiWQD%>;oM9PcQ3VDjUJ({(5G7Z#O;QLEZqrC{({I+zaz
z-{E`o@Zl>*w}rvUmv6wde|o&i(OeMCs?O!OHbgb*^nX{*ty>Ps+t@&VIThxS`YQyY
z$D7aAE%5;Ts8MR6Ui&s5P}&g03j5O+lS<L?-Xatx{SKeSkU?*{T<jx31_p6WruDNp
zemSNxKtt#fRk*JW*+BWt#HwCt2-JdZ`R+oKL%8Q*)vPqQ^9E1!bSWi@MHNv2mt~0P
z?$Vb!AGkz-Mr6<^cC^+zGs$xI?p;VC5G{;~Qs!*easPvk&edRkOmA&x^WW)fKcCFO
zn?5-?x%L<iPw=|u=9UKb*7_BN-}Zs|{Rp@aOYA^zl#-I^&kZBagvCVxS$RPP@-uum
zu8cz71}m@r@&0W#!t|HvatVi!r9?!-UOozcitewN=S%80?owSB0ax^mIf16`SKf&K
zQIa3xHc;!04>?PN2V8S^W72E-_+WE$GcuBxo4e>7<pdE<JzycY#dsBS;sn+DAn%{h
zEI`5}dG5w0$5LdwY%L&OIIs7s(%!#cdvq$SsW}QC)$fMi*JwEFyX*c$vmnRHZQ3Wz
zMNifg@xK$dXEgkJ{~Uc^Kv0-u@&&;I?*9r1Z_aY=i#g$LJ5j3ec_v3MwkPEiabJGL
z_dgz;fpysxwb<C$t<yNv=kT%Q7lDZ)Zp=6>=kjd$(z}K!g_+Kk|K(QRxdewi$SWlw
z_Py}%s*qFP^S6*W@O|tN{t3Zp%GdMX@czTu{ZKineeO&;N>~>HrqdYGDh^!WOz3-@
z5ydR0kTrHOT<g!?`C;ux!jluyJ&M7Hf>-3i^<yQ&-xzr=?kZ)J<FxkCp;m>b*zb#(
zq0L%bIy#!0|DK$uh*0tA2dW2almtLj3B20+4w()oR$?5du&m>h=s83o%ik3q!)}YF
z4H4#S$ZERx9v=H;|FJx<LX8cLIBTH?0f@pFLp8yQiUE~q2B(hD`m0rsdHMMjamHR`
zO@#;nAX<brV*C6i`=Kqz?mmZQ+~|m1FRQ=E+A3`K550G?ng)apl^kDs4!+mFONsIa
zt;_Rs6J*?HDr(+uUMH({;S-c=Hg#4Y+PwjqqT=`;|5jOAWgx+3FDu~lY(q=W(+k$B
z846;HP~!A}Qy2$FIa=#qvNN@Mcu83!-n3KfDh{3<5dHG^c30AG@Z!#fZ%NBYTja7q
zgFxWmUi^e$S@MH)>HmKJ;bCA3{J{I5l71?C0&yJQW;r#_CPaT|LPA8N2;TW-{aAi(
z<|TU=v4L{kh3NOHrF?Mm$LL{i<=tm0zN|Vd*l;vRcK%e5+y*tzv!-yQhSbz;g`Z9l
zy+I-w#Prc-O-3`0=RZ&$+wEANwT~kuFftkw#})c-`Ol`#f#wPEOmZyAd~mtq-vV|_
zc34obL9i2nzN`jh#Ngf1tKPx^#}?Tgl#U=ZIRB6IULx~2b=Z{=-t=wl((9JF@XG$d
z6Q(#AW>)@SbNb@^5bu5V*+z#wmL;lTq~&R%Vh<NFPJ_&h5lbuL*j(?u?G_fyzwp}b
zHMmqLRiJX<Vv3JtNK0L`OL6`2AoljP{Swan*ZewPj?O=P9O7qOtlWyT<SB~FZnUHg
z?7@!8W+peS(;sqkJ2)0*n=MB*wbClU&;-XDvRKKr8FNNCO`7`pehqiCi_o&L(MBYy
zd2>GGl()#uwa8(MV)hsPd+oovM*H2Q(xYgi30+tc^+v<h$Q3S+sajewamoCwwi8^!
zrvH$S-pORsFM2H#O4Zq8)-4ExJYeZJezRz3N8vWbSNM>>sQ6)7Vd2Bvmf<K|k-ymf
zFL#tH@uH)_lV_;5GK5}R8w0i17ywr;9*mJ*%XnavR{#9ez{u=1#Kr2%&ofjq<NgN-
zC-%XSO43rY)Bf8X!SQ}=ZTI;6J;1@a!~4H8#{Z9hgLG`~9w5mRT(8whm$iiKo_R5B
zJOAXBMEuBlXc}lh6Y>0p{-F)p3moR(^}d0sIT~nHQy|>~w4u6EHKIZ0aBssL4jp5r
zr53}LX8kLGTh#sT%mjp_o}NNLHhOxtr;9u+v6&TbSuZ)8s!I@dL`*j`CjQ+b#;Rc^
z`bFWg-}|+RlByV7$RM9>2=<tdLP0iql<?bM%1MBEYKxs*Q89Y+CZS8M#{D<&Df!&@
zU;SNan91RNR$`Zs!222v%r^rAgMM3E+m<!mMF`V48ypscyv7IO8()E;Tws%;ft;+-
z-tzBzaO?ki0Y>fB-ygAG@uP&8jUMzAG$xiq#BNaCI_dK1jjS5SR3Am$j1YD*+nAZj
zQPKxkBG4-=N7K;h>3+6VPzIjQHE!IXue~c)n<hiS-^UIkPC<`D3jhJAII4tTv>`Gt
z)pjuP1l*Oo73ppzW_bwH%L!Hg{%f7=aWqh~vl?ag8x*uBN7n^~1RYm<<YAR~eC6Cn
z-?Fnr8}jIAje7(II|Rg>9G~n>LWh8j!{^<*G||ne4?E^?vLT@@wOn=Ntp;-Y5w^AS
z0})xWc4S1v*1W2&*U1jQ!YOnCXg=?H`}_ObsuI+=^9nJiDYJNyq7hY~kOvt+Ly(6^
z)F>SXht<v`1-q|SbRq1HPPuU-FT!;o2k$=k9nMMpF!WV;DJLgpFYx#(2o5Vjv=rG;
z_e=t^N{FbgKCtwrw_=_~`K1e=U-*x&%&@=5v4-}rx`W9i#&4t6ZS9*xUmOt2-H-n;
z{?56NFR!Geghb{kaG@>pwOM$1OES>V3{fWd`GK%oCZAX)c(W&vqu6{<rDb}0a1S$@
zuhbPR`R~8CZl&Oyef$&<zKxKr=%)Sf=;YVW1mTiib|Jfk@2RR7Y9yG6Sprx3^5~-=
z?jl$7(9PAE$F#4Yc%whhfd!(xA%^9=qI!7ooIQWm0Kgn-DykxjVOyrNKa1ZXybwx4
z*|N94_`TZW#jGaW9V+diX!t-#AsfqOQ@{TQ*XmdmyPM>GI6P9anz~tsx8bxrW;$K}
z`@H8d5boVP{?nlEqdugXE==3>ekp*2vTR?z+|fJ70yLicr{7W<Q>RR<bQh=;f$4e7
zWxg9gk`2KW^XQTihpOFmYLBI_ZmxU4Z{FRVmY|kGFfV=DI$X`)-58Xs)4q3~OC!+(
zMq;^|5?1nthLMl>&3j&2J(?A%u4H=ClcWAujfnG?cD_0JkdyNOKwo9Z;W&W5K;Ow_
zD>{tU&-@&sDtfpy3uLVRT>Pt7U3dEVFJ27pJU*1F&W+0QfE))yNrjg(GO?%ox4h1(
zcPC%S%L7){4PxfJ@^#P@8N8+=&b<rm3PTm<i|_IGNKOUX<M^T^rVo2OLo+fmrhiI6
zl3V{kQ{8a2dD)|y<C(1^3`O=BLRz}5{D>igW;3^Jg08wU9>#jDMdrMh4EPm!1IM(a
z_`A=y2n;dQN1I6iAlch8uK_+Q)5dU>1pg1$lc2J`E@<@#LFleIX3+`z%YSE;A5mCj
z*xVDxYYu!>g35SiOSgXhNp~;EgHu%<)Ddw5rXW~K7dOLFz#X#Kk&whWTcKX$+0$Xv
z|8+d*n?|^!pkNKQo}hEtp_>_z>B!2<>(Fx2+qa!16F=bLx|gRjZVohM_#owEWnKQD
zQPqz`Tz6O0+eSgGAQK~?E|WjuJi7zYY-&tNLqp}>2I<Mk1VX3I<y9r7y*(vM{-Xx3
zXM<_PsHkqSHRhI<IVA{9fHsQ!^Nls^e0F;0<=>5raI6@}RBQz}s#zYtFBh0tAk2Av
zd3hpDIS^R?DUEUs4Zi?N)QqcHw(C^j)HSLHj<)9Bw_!KrIc@#~@9tu#`!x=E%c?5m
zbnz!O=;g!K9;-P!i;DxFzkjtaZ+>07S1&|R1OzZ(CgbDgUmeNx`R)rMZ}Sfyv{Ct|
zBPG@p=H?qCyw&FYO2+!C2|`pb|7S&Tr}7BQ*&+~i)`JjD-nW}qVYgS)*H>J=@0=;<
zzC9FMw21CXF=yPF-5B?RORhrEuhf+rqg!LU-WFSA^T!|J>TPxUGnV_C%HAS<z$^e@
z2-BegPtcJ?#b2KS4K-GKac<7pwOlnHGn~UjRRY%lGZic($0#_F_TjKR<;Fqm9MR0k
zG3_7nsg;=d0*@<FB8c+O{%kMabux$$Ifdp01X&kaO^UuT&xe{XJ(%h?o5o%FxbN<#
z2gVRI#^u_kR>1{~$!ZJ7m6N?}Ht0!=ttRS>mRX`~>zsca5C}P~3{|`BspM*wSoT(C
zkS$478FY%A)i*~lq94BgRj^Teq!Q%W5L~TFJqy^#jt<YcZ_8Cqn9XgjN2bmi8Y7WR
zigHOrk=WJz>cjnQi72f9$4^=XCcch6d0<yazv%OUXxXaZ+Z=hTN?vnkr>ZW3vS{PS
zz1juXM5`t8(a)K|zSCWEZ9rO5w7@ILNQS}`F!ul&VP|2{e45>^>1ek4vpzpb)DGG6
z-YtRhti9mo&6}!u>NK~st$m~buL_8zz`A=k#R#dp1{>2IO(!+z(&^54y<#0@i<>gw
zDv~X)ssh1ROHX0>H7VP&H!La;DG_u>s6c7CzmUZ1TwR<Sc7j^Oj0=@njUsX@sBhfE
zd(H+e*yd+f0mFmBS)KVkwg3LP1B@s64>1mFT`Dpgux<DUd_qo7O7s8d5hk)#n!l8|
zS1s_xi-sVO;;i=pWYbT`V-c`P3}YJDMlW6JG*gXKoY`;gy?0L)muSfVE)n?5zx04<
z;fGiAWT!6M^JQGM+Oy2t3&%p5gdR!&lHxY@6fu&ndsz7*F#4E6FRHLQy2`IHM9eck
zO*IQz=8)W&4ZSTfrj3abRSG>wSMP{DX)X4nmgi>mH{FFTq+<|iWi<%xxv-ypP8;1a
zPKxO9Z%a!{yyjPp7P8jYPx?{1OO9IM1#8RciN`>1gpS8xj^^G}F<#`;!ooso=S_Y5
zsnp|<Yz{FXT%z3-6ctqSM(z$HXeSTZG!G$&p6mvh2Ucn7kWf=vX2<I7O{!Z}uIu80
ztk7b^?&MmT8+h>YSd8wDr_1712nd&14Qh;XZMLcV%UW1iV3vn-L6uc_B6aWHXz9jq
zxl4RXijPw+d1ZXmWf`tCM@tPp)4r~fI4Kj8eek%_rKnf9j>EXUM7|a5Y;@ITBgOI?
ziQ~CBtiW!$1cQI;&5x;UA&&%JxY0@N4}{0D=~l@0ung<1MtdUrv$R7#3R!O!eBX%M
zp^zY=(CX7>pf}K{Jhl@2Cq?|4{NgK)dxELqIxf!TPAgq$rB1n@KDB}O$8l|}%zRH&
zuquv^J;qBLnpAu2ATAWN-&X_6fsm6~zRBUkmaRz1**TecuzgeT*?Y@bT4l1P6%B!O
zz?PEEKf*i5Q=8_1kN&NY{q|4=0jiC)4R2>du`dAPKq9tV1_s2RHk0>P({+aT*>=|W
z7<cMMzEZAXIIsDlK2-gC5iXLBU2%@6u`$XLYc`(kwc&S(3_3bG0E+B2pR81t;uRS#
za*`V!SzYNbl9&$j-U}wny?yc0C5Kf29G@N<U}k<3G{T+i<jRU41x*4`)0UGHylcS$
zhx{K{)`Kl4Yo4vw^p#ptxNuYhn3ITLWMd+m_`ZbI;Wi_ft=Ryu?z!B|nDnZ}a_`iK
zDU&H&@fvlXTs;-k3UR#O&xO3eM-MM}aD{22HfYdlgc)C>lUkcD+t$W0{A4dzSI(Bw
zU*2(jI4RCHg(c#-6xei7GC`E08IlIN{!f9}t9f{|v(YQn6AJ8#rF9=lO>mpJ+HcHE
zFSF|hg~+YzKf`U=O-V5brWDC54g0>_(r>P?G+q>+s;Us$?zleoRidl|dmEJPXpdD$
z!)e*2=*#CX(6!=_lXKBM*auyiy;JsWO85D(11a3=C_~Ge_aybVoAl9${0{B%2Ny!u
zI-B%;+$s7{&tP#@D=>&lG^gOVY;9)RH*G?`3@|fN2~`6PnYvj<dMKr#<#5l~Q*9-s
zmgu;+(l?q<LQ3DBxRq^NvE$Wsbd<VmF@Qn`#r9dm?Fl(?Nw&+u!TM+kxuCl>IOh2H
z1`1yn83k#Uur_^hFt&vG!{aw!ASU1#C3|-3CK%?jeG3Y#Oa8ragVS}p+E+EK{7GU&
zcsN|-a7vIG)p3%aZNOc?Kr)uY-sZ>PfO9M^1oT9tq&SAXzo=bhAKmCjbG*@2_Y6=x
z0OPYhd+THN>tAAG9<%N0)@W80zx}8KA6DIO3U0m6a$|;uC^UP=;$C(BlH6-FPkS7G
zZ3c>HCFZAw&!5~GtkyIhKUJ~4?CQ92^QP^KvNte^QZg+5^}tf2q$?No3l35nfv9)1
z$;qqc_iG{B@t_Z;En!;HW$3xPqmCH=z(B~JQh1i(HJK-&Iv!nEtk}2<q?CbR!Sg1_
z&$!Laf5zRmN{);-$Adx?XUd2OLS9|{FjX?p?oD?yJkt0mSOj82f+)s$R3j_@(6^pO
z@9qUtGsmJ7$OrRD-M{8)mWHxQmgy+);V<8(zZDeRJ-Ubu)sFgHT<Ro)-)awJrEHl*
z0TrTmnVFLEtA|Hq<uWjSbO6IRDH&PH`8v#Xu2%F~?#t{ot2;@;Vd2}IWYKT_5TFjU
zpeMFTJ*9)WnO<9KeHuINE6>dj6|U%3_GKw&*Ap5Fi@5D5Eh?fySF0cuYWj$Vp7b9g
zBK1=D-_Ti9NxObiHGCI8?n_qJZKM)Hd<zEJP*$rmB|$IrPW$Q0f6!%3{lAAHNVa`V
zDNO!KlG1BdheK=a?l{Rtdf!alP6?)$lUEshP;%t^o%XUCa59RE?hem2VbT7aP&|9N
zWNhpzvY4?V_)q~`!XQJQDCA&tkX5p?a>$dRTc*;!!tQGn$1$zhdf_|ujm+ViVwv)T
zqF>DXasz2s2?@nW?$A-h^5}okai!PP{BDm{_?Y7J^UGV0e%n-|#<6k2F_EtJab==}
z?*><J)o#Sy(sTk6T>Yeje0YQ+II?=_F)b~Tm(axajjf9CKE8@Qr*hTWuk<mMbY<-X
z;oDPEp05AdK5?47twYbq->AhMiXdb{jOwVG#7x`BjdZ*!F&lSfjfqH^1-g2&%O1_#
z!BpKdGjHXU>od+Nmt-4>)**F6OUX@BnBsTn>B*txSh3_)tLhUZ#J;d;fXC+^AG;1#
z0P;@8PhT+ub9Q)oX~}C=aEIDAz=)mEM>EjBCagWvoSvSZbeM}zh5v`G1E;mu<DIm(
zuvCnQDxSFR6@M!gbr4!oux_Gn-(KuVQ}2D(Z8>tB{oaa=M$4nZv~~A>-0$Un%2VTq
z26|J1VA>1THyPTgr?7F59E|SQYTIP&SIQz}M%XKbSvg5vQLJ4Tqia+bu7(jj4w3@;
z9{ZiFTIFg9LK0kI_k3`(qY}@g5z6^G<8U~cw55d;Axp+9W6Br3RdhT#Q=ZlsYHG9E
z0$_N0d*d((2niKim^!DeoO&E(T^RT+McP_wkeJ9n!f(>`rI==}0&*5MkL@6XsOR{A
z0IWIGp8MZ|C<ZGcnNnX3kCJ@a2eoHsYb(p6H*RLd)}g8Y*9#bt>7~mo8!aj>zQbqu
z<@5t~Ykst(=o<*jYxCr?RZam}RVhTeC7uP4yq)#p>A25gu&b~1WS;bAe+9ASyJvZz
zOIjZ(5)+t%+`pfF*Wew?O^CE?%h1P-ClMuoz4^tHf)6PIUjNTrp6&4_tI$uUcGXju
z-c2()L;k9pV5g;hCTcqEt(*|tQrDrADG(f2#m|6ZdVA>B-mnD`8Y3e-mOUAcxpB5H
zb8~XJxVZou@%N4m|9i(8v_|K0)NB_*_)>aEqu8IIe5*^>uZO^iY-%cWXlTf+AIX`M
zS-kGBK2gmGgj<MTDYM;*rVz1@<E`SHm6Jtwc+4^~$N7g6QH`lOPdM3N`y@+VrMT`C
zuB)LswEOD2y$wKX@It2E^3|E=$=t!oS+x@u;xE!K(R;gLm&v?NILnkMy6Nxvg8!4w
z$>t9}vL8u4&Tt?<(!S-MJsu2!$Q~=sq_yh2sYRvL4pPd~7+J&<-K=+_&oRhDpD8-F
zEFi5sg8qX0j>b@cviZ~h$KG3pMcKV?qxcwD7$B&mw6rK8C4zKH3=Knfr!<O)w8RYE
zJ;cyMqcjXicPZUHbnG=ezyG`6y^r_9{;=cS``GuF=kOU|*1guc*1F=n&a<h|U#oty
z7bVm&qw%gX{fYr3FQ_yQGpV@cUd?SbA0Hi$@|uIQOgL9pRjC}FpeW!#5NapS-OW{`
zt+}<i6?9F1unFhgi3OyWigxoGQQo0?xe{@7E3hY<H7*%>YYk(jhN<i@usw6`Px?K=
zu||OgBcS3Ta56dvvLS)Sx2MG^>X6z%)s5GD@OJrGJ9Sv@9)TIanQ&P5=X?2z&9#QG
zX}W8J{7m0BQ^q^-I-VHL^2rJ(i}F9~^BK;y0HN=8Sa(TCF6eZ;yTIeHh*&7pu7O*%
z(QNM?vMrN7dGcicZ(H(mT?<>Ov9y7!$MM35)MFaqI1E~THGdBTDVM8xu~Ixa1FN`%
zal?phQboDY2jJ!eWD9)?CvRNaT3SHF#R9T5o-4T>`i0tf=&r7Qi|1Yf!WzbghRZ6(
zCML-ZwhBn2-YSQ{-^_AAq^+dzhE=uIT{?!5$z%3+^@BDWnE}<TT6c#n=<bAaFeQw<
zHK&8x43{YYZWVheq()t849PKJ)}qqVZ|$y;x`OnycA<MCU0a14ajKMq@-8eK96QNu
zqOi!wQp4lbnM;if7n<@x$u=PV0fd1l+eEO*tp%(Aka8g&C?aRab#}D}fBz2D*0?DD
zwu+V%6aX3R-}x8vNZKJZTivJK<__SxtOI3{^~xQP8M2xw)b<c=1T{C4?h^<eF;LO?
z`x-R@T=zQrg;h{^#B2;?1LO*j1)Hw4a{y3FX7j!@KOj}NI;0A%->ScZ&z`SV4DeM=
zhw`zLKT$%UB#hLmvtJ!tnemE`k5K$!?&{_SuB6;9z5_Iy-~$q_*Nlv-r(0gPAKqIV
zD>W%KmIa*sss$P>TY09f-m(d=bQm-e!7bypH#C_0Q0f>6Kmk~YQyBRa?6uiYnyYR5
zg0Fw5)c(MBGT*SIMzO_VePf6w%Cgwy@|O|QNGJt&f5%GeJQOrafPVhSaD`VjRcX17
zd5ap^p@%T05f!Amp#G@t#tjI){4MM8>ZajgK;oFaY~|XNwE<Yz$17Jsi@J~rTMQti
z21cyN#>rxJ(P#v4b_A^<{l)?j=GymIV%qZocE?<{W2V|jx&efUKx4zf&K{8+>#oD_
zOf0U%9`g;TmVv16DeNU?y^ofcPHfr*6NfjqNv3C8q^DPpSta9t^1`Cy^Tu#_WHmg2
zB=16p?O1zG3~%sP7-7p$i+Y+sz>-SA*emD#S9b&myAAgMlNa1qX$n11-YX#ni_Th8
z@$mSPaD80IGWrYKmf)v<w*!^{v6J>V^gzYe4PX?G<{r*)TTe<Lr#m}WM|eubL#nx7
zzFgk^OTF7`vAtPibGYdsA3I@DchQ>HaQ6Ci84!v47*t~bn5p6Sg?e3us?*xI(XX=x
zpi&bHT5SO>IS>}e*dEqES!34np^hd=j2oenDO_8~8S#*MRbdXv{J~x+>Bf2>d^a_K
zR$@>AY{x)o+%DiJjkWu1M>e;$nrdn9Xjw##CQ1&)n&`YW)o`+f2h=G!%|D5WhyWtL
z^8LemL6ziWgz0?z#Q;w(*&zu6yzaQY>>B_0nmh{+;WRhChETF`(`+uFy!HH@;m<F$
zOrYiSe6wu~WP--V0N-I-a|^wM?VA)E8_6uk!&DvZWKdubywCt?X3%!9pfT#?w6A|z
zfB5O_P0{bBraGZ>x2J43+0<&&jPYEV9^N7F{ZJ@zYcNO8(`py8iz?jER;mCTk?@7Q
zVFU$eGN)$dr=q6^2__AY6(w|PHst$o3v=mkF$-ETLAbd&P~)%okMn`Ef!G6WAQb`v
zO!=gDN;N74pdER8?eQ)K^x*Ooc~fMj;gJuz?DWGxj;i6(Os*h~lbM+rbU=Uz8FZVt
zW7ahWH9+n)goNv@`^9YkLLMLmjoPB7dd*13Tk+wPE5e=;d(s*jZ`JMrWh;oJvs|d+
zvGdlL`*N>doz$Jj{QUetiDahK<Y9;P^rv%(iwn1Jo~EWc-ujFnEhh#f>Vd3nx#B-x
zHU+9Lf$AUt(lE-O%Eoi&#f~rcQJe7Z$>``5)^;5)745GNIV`F|+vQg4M1h%#g^)fb
zCB-KsWKcb=4g$r~)?o7UriU}UgmK$BWfUTz@<7Tyohto<u<*sy_i~KqVaVxmHpPBp
zy%AbftI9+4ZX~_z;06)EBxU>JKG3;`Ckt}o_Vdei24eAm2{ThQ&)Dg>lV(8@=<^1I
z04`8${}rl`jMgOlMF-MV3D@6y=_wM>RMtv^a8+43IG>6kB0~-^xlW%fN)BX(*wj@=
z{5CW)l5C`nm+fia-pLjCq)TCwc>1ulxmmmNQ?3T*2w;X-T%7-=RnN$2k7KoA>F&6d
zzu}c>KG{Cf*#DZ2PGwrPF?~5kZLF9zapG`!IP<<ufoUtf)FXyuS}YvnH7@{(kGEEX
zJ|)n<l0{OSc!!rhD30S`XnGJ-ZPHW<R)Mfa2WS!A5Rm5bgcTIXZj5sR64`nFa6;O8
zupNGM132J^e%dKG=$jV)&}1>3uajMIA)}Lhy@w8XwpJi1JzM~I1C{R8=hNZ0=5pGf
zaOOa{Iayfb`fHk-kG|eG{%C&#5CX1m9&E{2fi6tgk35iK&?vXQky2leDJ?CToi&0r
z=X|*_PzGAC@I2QjKugv^srH15`J1uJfzLwtUFF*r*tF4Pahc~q$k%}BC<4GwCoSFc
zag!7T20+C-TtUHJ5?WJ%n#OpHjpw<nMK;<rbgN_w_H=jGc^pfD`+S49JTcLleXZi`
zX&cblx!#jd<t5OF67n_fj)NO69)W~*M#j8F>d1T*NZf`H525+V+>a$gso6u$qBDa^
zl_Z_1`S|E5Df>D)eu0YD5!}pd1)q|KkB8{@2w=TetMO9uJ;8|GC&}6L{mMeLxCr>f
zTh>1q8^cN2O-$M}$*1+FHKIL6ii>x^bxz0^ihO3D1CkWLQHtuMPc0y2?I^Y88K@<{
zQ)I{@j(d8!T?WX;b1W;kh6CC4Zc~E#VO0zg+Mwgv{dE%7r$fsi)}b06bihk2WftY!
zMw5#b*3!R0gRo`L*P-#9Pex2mNjtJhXljzUMrCBK`%ZU1!ULw8KZ=5HjdyPhZ)tum
zd-Hwj7AO+9y(x+QA<b}|4a{;Bg$pJ4V(|R;(s>480LnbWDqO4UbBkGLD4+1%TqTRy
zqdpatR?aQ#Pj5r@@Lg~qzY{qF_^|(;^lIe_-~$4J*nj-LR4W;Tb^jk5Jy3ssKjeTJ
zFZVH^*Eg7>lP9$?GgD|RmrLNK%{v-KZf$5wV^_>)0+0scY#IZ%6I2xa)(G$;0nREm
zIT<=JQDa99^<Coy*iT;G<zdUoGT8_uXmSjz;rUr@%kXLX%unjEhsUZ+B0sjuiQ`iO
za4kMHWA)c@NAf2=%J@Poh6^<eKK1<&x_)baE#31u$y0jZqMHwH2L=QT4XfrY#wEfC
z2}o22H7hGCuV7Ihv9i7&R|)}=ejuL*@H2B-41dD306vs}ps>qzbZoy^C#Wf#XZrbx
zPVttn4I!6i@?(R7O07=;W&JHuL2EO;<4sNE)ap5*1ryT<D9;A8w6q!-8m~gg`MeZa
zm^DhYP#5W!b?HPv(zPv&#C?wu2qy7oV%PuuG00cH&jgUGoH!YPN(OO?7D&6>#-E*e
zl!x>ZiD+q^^%>A}Sx%k}?u%Ot<`fq6w0He5#%i420SSrAV)3k%VL-ZzRI4&>F8Y;}
zL_XembaaE0?sO%Z2XHR;P1H4sUk~(t>fjJmQJ}dxEFvNXz7l-(OF<Au=V*c8L_CaQ
zq@LgL?N42w%%RFun=N-YqNrV1b4CVG?g16+@ch+y3NN>VTzbd7EXDBVPPx%>1e?p|
zxI5#kS9Dy9$0o@Df*#>v-qJZ#bFfLl=VrJhM+RQj%F?on<sxzNd^CU{qF(YZ>}hfy
zr1aYr;0E;=TX!!^NpS#Ok^otPFKsneE%4_k0B}NpdysIb9@P5*6<UA&`e>^5p0TWP
z&+!K?`{nk&R9{@i%)SO28&|+oQg=S>e<vUy?A@79w7-dt*9BO5(D_#H%;I?QrR5=@
z#lA?R1vL>x4uOJsb#q7Vi1>Jv@rD?~5x0$sj2kRDIh$M0!&vNJ6wm@zTmdGnNbhPr
zKarw(Sg48G07Xo^`@Bq&A3IRJ{WA?fU}wl;gjJ_HBP!yC$*#vq*K<iENWBwtTOQSD
zS%Sv5M>vuqLdxTsTUpsAwFmusfR5w%G}+|%l=E`quz^M;5*|r6xun@J{Y6w-Jmi_N
z5oYU8^L5;ZqN3u`sd9<qCckg2SkC||dL3<w@&q{i;$-3yn+w88NdqDJd)kPc<@uHO
z44_uk*wK+IR9F3!^(J6_FH^n--`?N<fwKlm@?iULMl$lK8|}f#6ip|pVSc}J-h-}k
z1F`$iGD}x2t=ibwmB9`I&7)J#?T#fN31@d_Ck)`=lo2e6r1yY4u<dzkH?YHMl4!$?
z%%x<7s{vrMdhcm@f!a3ByR59Ni;M0BBY+L2`N`{aA_LUQLqcRbP>~5yG(DTv)|s-%
z=HFB9K!23#v=`(&t&F71$0@wK1syYVb)4zNvn2^y5pzV@GPO2~E`qmiCTbRa>d4rc
z8*J^4=k_eU2m-a%0Kl)%(E;2<nh6kTbfBB&W_YUBEv;r;_p&sptS4)YK;7aBT^02Z
zyPv3>&U8VPN4ma2*sc2$7^qZ+)A|u;MCOgMr3S1?(ZZ}uH@OM&v!fK9oew}EDWkW}
zB6?LvXZ(c1D=G6Jb9KCGU^~?pc%iiOaVTBM(+aCB8Dc^A-xRnH$l>3mY9h@i59a5>
zZr!?d{&r1OlVrjq$xZ9BTSmr^ubOa?=nQoq%#_bvT?8mVihFnfz{|~2m2&Go;Q~8H
zN5HxINSJK+h9(M#QM;YZcTjl6(egxrbFcyGkQoJ>U>&!E*n^Gn`^zIslgB~#h*-MY
z+oRkhk-+;-@;nJRZ4FgX$_89(pz`w8{qL6yOVEKI9cRR(+VLQ2UVC@%Zk89D=h7?e
zYQ21XVMU6=i2j>?^ZGsz&(=J;B;hYN9}@<p<>)VSvvb<oT6dA<_L#VakwR58I0(#z
z`tt$~L#+BMQx&B^l7_vwSOu;^;j!y#Z(p)Wr9?20iB`>B2oBx{t|7x9CYPnB>Dzrd
z8JX3w^mvf18UM4S-au=*`RXOh0$}yoi0o-ld5T$?Vxs4((WNJh#F8b=P*GC;dwAPl
z#clR#Z<+v%0~iCk4A#NGt(ZYA{?7?!!^&3F$~yB&@KkA`D$+U|G(Df3GG#_Z#q94q
zh0>cX_9)&><0z#IA+D-?yER=SucH(8z1IRdh0YU46`G@SmFQMj?>2Y|aIwmrz6OjP
z8m2iKa+0zgGCjQ>Wl?Mm7b;gbNZ^&l&yJUWv=Vj%3(|-O>QLsdewq&;M7MMVhD!W0
zGo!QpCDq#&0lelSx$YFlHf{XytyhF)N!?bzLWZwYaq8`UOSK}Lz?c2atQ8hb^as-<
zX}V9D)IP>3LJ)z9A}wMjWA*VYE3TK_ruQdCBi4UMY%Oh~6T4*SI&7i86J`?n`2`9p
zD{~x{<ivr})m%HZzJBMo65fr$U$L<~<jA&$>^@!7zBE^14-bexvD2^H*#ngK_?$O2
zjuvJ?YEGJsJk!d22r<-e#MJpfpF>Pc>{fl}iX%L}{1J91tonc(S6FyW@a4Be9u8jP
zhC8?o+U3TFn*z^IU(?Q;PgKZOJ*@!B!aqKYBVJT}+Rs_eX%C6_a(+wJLQAUwByD17
zyd4^1E-|P)kXC!GHyQIYnpvkrhCGZHp{n~(+<QwjvX3Tg@%#6m*Q&~<{mxI4Y=3><
z`{yC1<qJ@eXSr&t_$UZ&+D9JbVM{d_!A@ZiCNXi9t`4QQMdcp4)lECiAd$~>Z>nmT
z2l9KJ9M{gy&fb}0m6Vsp*x2(Va>aN5wS~I}tmk|1Xk>nHgwQ|@PeT(+dJCsguk2sg
zNB#D-7e`(bCpG0omic)g<CtH``R-kzbarUT_W20~?W&?|Y=)}$d0oNJk$>_8uqY!O
zpWc+4L^wBQfJ|44$A?thgVK9|&A10jJ71#VeQsp|1_>ch*3hW-XhC^fO$;*&Xu~q?
zcg(JJ*I+01#dqMxy=Y%|Zj&eBMhlM=CK?=2oOdEk!l(sf&WqdT)DO=e;t}aujTQk6
zciW|7JaPuA;yj#&gb!}twnmwt*%~^9CCyf*4h5AJ70rudT(-uTEZlC1II%`EQKjX3
zbfD2!Aj^+7w~!-wI4=^SqQ;eDsy2StfUZUhOvGAYeTno^=z_}lI>6U^7FA}5z?C8*
zPf1;Z2UfId9jp3G6Wo?I#y@G!cB4!@8!qTODrnG=*+7<wgy&2PTMkWG`5q9e=q7xR
z8RzX0nM+rnvwz(;K9H-cK*%bDhkv;BaI(h5Ciz_(XyWhFePuaQY=9Zxs&-jhl}9S8
z50n<poNuSYbuu$E$-O7puNGtVGm#ojqujHKp9omb63dS-sW!=T=5Moxri1UN{~E1z
zeRE0d-xLdj(cXJ(?67CNg8i-cO6e#fHLyn-A6%^sj<USXHTcz80Y2r$8tT=f{VxU+
zEM6hFj;{XK`;q_hr&BDzAGmsY{~J7V84K~ddK^Rkg+=4wRR3T0=Yl@s_<UP%d`l|l
z-?nk^sa6Lmes$6)-tz4;<#;Ab7o>h+pl}<DGskP5+Znaus+qd#e@ywOs&2!X2{plT
zSPLnpR1^`F%*wp_v7c)gDQnsl7<0Q4l>LcOv0BE<*Re8JGp(%d2yvb`73A`7Vuj)6
zzJGTA7UA@L4Xe92jpCAKz7?M%YF@U8in2ya2PS}A*3r=?>s0Ji<RsCktK^kuWQf?u
z-!A0=aigwjubYUBV^lu@@C)^_DX%kE`6+4{!b;jKxq$3^@ATCgbxZnD0SMfRW2g2u
zXxjgl|8be+XBvQ9eGQyf(QqRqBTIzC#oVs;l}ZLaCFD--$0Mevj9OUFLE=;0^lTax
zgDwE{M?^-hlso_<NqLaLNJ$vz{U$%HXhQ-^f=8)`8k@9^9<ziuieabjy#Ng@t>l6*
z;+bOKN4)^BgkR)0Lq;t#?eo9~eic^+vMOoePaCG#ce^L_>(x0^(XZ$l91x&4d4<dt
zdi?k?CFDNF#)*0o>vI2a6(IL-vgRNrz{kJB9^a7k@TgVh$f*8{*C2-7g^vv7qNT~x
z)6$mtZ-YU+_zq+R1HYZ1`X8%Y8NHTVHopcl(bc9D%7k!~Nr|fkfVEGtuR&XXi|IE0
z_Y=a$3h;STSZEQJH$!M~#|?(GLt;H(pOpT^fPO|YJ#0AiMTSH^{P+sseIwC1oBuwp
z9sSRLdt6M38=Vm^-73Mafam|fPG63jn45}J|EOCIX^8LM9FJFzfoUpFtT-+ljk&gD
za%F!}v?rhEFkV!HB&r2j^0>A*`(H(7w;7E=e6H>AR*N;dZNXU;6*iCvvw$skuGpI_
z5oTsL=Mpoq7Dq?%&a=@n(6Q1f`k`_pO52py9bFfqG`i>@(!=^S=#7A&f-{ay^t<=0
z@HkQuz1dcLFz%0cz^>}$lvJE&?^j&tDR0({<uO`;HB*ST94N-Wp>KH0$)GYMBdirA
zlv~@_KY12$JCcEM_Yd1sXOsCF0bJ7@csN9@TP3ouw^~%O3bxAz?4i#zXO&{jho!W(
z-0B?`?)??->RbFvnK9ovR4*JhoZSx=)C9<Fr1WJh%V_C36T*#HSnXnhTQk0zLf-5|
z=smw*b(40?Rg`6bKql4f22Dp?`KWPejYbB&@<3(Biv1E{RJ%1ke(ZJUH^d<daFF4?
z?I1#n>}F$z5g4(H56){^FeqfU<=#2|3R{$+&3s@*$%J}oTUV>_Cp!WO-6^+Ur2Vdp
zT{#5Sl-;6K)iji~xHe(KFX^e>8*T|%Y0~9+Pv}T~gFT}taMFw<MW}0dh^gr5DU4ZI
zB<Xdat(;8)x*6D23fx`{C%|<&gcXVfXc@8)Q#8Q?&JOOi)~8;w@UpKGyD5uiJ7VdS
zwvidCT<#lUNf9qPbYC{~ud%H0tI4`^A1{qoaU=U>$J-)%pw{o%!xkE9rKgMfw|{@!
z!4?2<u8t(PefcB>r|8!m79Jle+~*9a3Fgwz)?~##lnz#Us;hJqC9t|^*lXdHhDT+n
zX&Qh2%4R>G;zAP@)lKn=Fq$_aQvbnGYFc{NXQ7A;rwB#KY8t52Z0(}i9Xf;U56QvI
zd8E*PN`9i?GKilVj0~y8t1iqed}HKyMie8_F4G+Na#(}MU=L@vsHjIQ-e7x7eu<cG
zjyXDSyE!tP=N-Q{PY8#*yJ}e)O6Go0gazjdca)m<GkxrT?%D>nO>JWY9OmSZ7p4zg
z%eWn>ph$jaN=llHy$`+$jd=7FQcN2~N>7heYXpP{7D3fs5&^9=kr8USInAv1irK?2
zn3;LldEaD9L<o7SN*&jpmfTw)qm`DC3=UUqX%Qi2q)|Vv_x^|Hv(vK^GBDJi*TBK%
z<7JlEN3*u$hIT`lvG~w9_w_RcNK;YCjGcy6W&{LsNY_&f1yB9$>}0YICxS+z2EOUp
z^G*rbe5FlRKi21Ty{FE~$YbjR$sIKf@~Ca3if>veoDlgeO!8Mp&P+!r_bmD#w~VrE
zzLvICoKVdQm~r>OEUh)VtD-aALqif-7OlE|siwt+6Fs3H@Wb><^Y!*MtSvA|s#!W`
z8*<PYjNM)XlWCl57g5wKqJB3xvm=0Aqi6`>s^2m~jCV`2hUQC0H(NkRu9@;Y#kWZf
z%b>vf;}U8{1AE75>;cI%_aktm>!aJ|IEQl|rg)H9eP#1+f+R1>?HbV%M1|2TAx1ab
znO;iDeGd%_k_rxkKV)7STZ!05^lA@_ps8Y`^UH|F6eA3nyq3M=pe^F6ydk=Oj#Nrq
z+miUNZVNa#Ro`dREbN@bL1CI~Rq}a@k{XOuVUHm$52Lne$41r)=o0YXR0$aU3ISQ}
z<tL9bR&JLss)oaF2h5fUq9&BI^rOophLXGw-lMX01`f;^)Fv-H-*B!l*bVEui>Z8`
zSJ){I@2Ia(J@zwlpq3JWRb0L}G#X17At8KD2{m8Rv1mz$tzFYt5%fo`{`!rziI><p
zWMMfB2tZ_<M}2+adXqNk+~DDz@BdI!b~L<p2#ml_BQS>(z(za4OSP(Lu_}EYqB{<4
z82IqdXv%-(0<;9o@M`ogWoHeA9_T2~=4krR@`P9DatsSV2gE8-F|vgIV-Xl|5I@M)
zgcHo6i4D!xXi=T*5s%QZs%mkhuj&j$z7|9FL^|#!*00<vcfF4`COJE7|9t(&^NU2G
zl7u>SKe-t`?0u2*1o%43;WwzjInUEbb1ad`_avH^Kk57*X88=BcZK<U@gk~D&;DpV
zcv%%QZ-oC#!Uv*dDUWcTt|N}HN%j04bAFw<BY>uaeWd=OZther%V5=I3VNZB_dJtk
zgWDj*Lq;80-WB1CR@q>g|N4Y*VquS4Iwbl&TEj3BQ+$nO?*6S0UnMVs`xJ~jMx3{p
zUWq=7AF-Td$Id3F5Z12eZL6b@oV|s?9_qcXQ}QRNpep)<yA0~v4}BIW)H^nI+VhlI
zV3_BQFgytBb9k+&mW-i7z?6pN9!e1LrhrV{F=H&*Ptue&S8L34Gc(lCVIvd@7a)u>
zlBbI-)}PBIj@UEccs7rQ2mQR8ZzK*!CMP^18!i9%rJ}Y`v8D+I$B%}SM#qAFR<=+M
zab*|_cH(aHVwXC-<Z=2x8iJCA^B6|o*Mle_Wy0ON=q%2C6r<Glpxv8l2VX0fPiiyU
zMnYwX^baT`-f{6N_NUF_yX!)0?P*@!^;orcCw&m@L9;-T_D&#k)1XUSJQn>$aOSXN
zOdDJem&+LYTM+~Xo#lK?2UbJXH^fB6+B+DSO9-F9vNmUYuw8ramw|`kLoO*cP%Rp9
znag!gPeaO5Ib#f*<ruiM>#A7jy1i@HV<Uk-Wt@-ejXIL@TPnWthA3zDrBM`^=>Itx
zeHL^>&1eTc^_*-w<R7!TGscKF1I#S-@Ae)tLaFohq1KQ>lC1omP8LR#*hHK6VkCar
z!dY|6*@y_JVp2g%vM$I%wSSw4sib=QmsD;fD;&bI`>#zrZ^j;ZIYeNKaX_rYT%Z+@
zp|EC#<N88}j?;%@NzW))uE8@Tz*);HFRr!@;!T_ISc3w6Tye-X__%lDJKtZrub&$&
zRgSiw$b`L|k$49?otZ>fa^%Id$Gj{}_!@!lpI#C^Nc&p)d)VFJu73uY7D!a<XYXAf
zX@728Gd12=Sa*EohO%JYNhKo=;xmGq#!G~GynPzNqM~u>2M;4?kl`RC9!-jePBNFX
z&V}=7U$*c<%AYVXIDLxLzYlX#vP>d^E-4fuD4{Aqe$g4ft3^!nOzB1zT}vml>Xv%v
z(*&|2g3Pa;7tZFaC=(mwR1r&-c-kA}%{r^QEbH71smbVtt9%#&dr!%V1$3)xt=hhw
z)Oec~B687F!FyB99)N7>qR!)?W)TEww7OvJOEmvvxN{18>JY43?Q9K1{J2&%bt!Z6
zB`(`Y3PT1yK^nnqI*o3`!;f}(hF|O>3PdZGUplnZM@D$K@{>pQsoB|!d3PF}q4IRA
zCZ*l^jt>!z^Z8i2H!1L+#`->uxL1~s-Ut_ITCu;}TaH&NTArcog1mZ5T1X0Ar<Ih=
zBv_TaLH$d`S;tPtOOlLkYTzH{JK6dMj1L<uolVqvRr*t|!EH=EeB0)x>X7g4bGWWu
z4>6-LE8){x{4Uix8lfw_Tc7cDnK$@eR(Wy6Ko0m?oI!Hcew-BXs$<%SttidsBv#?C
zUiR<GLj~_tIj?spIZ?68X4#bOg11o|Qo7bEqM0U5mdUkL4{qQ68<E9XW3e<!<8PH9
znX2QzjJPF(3`b7xTMW^dKF(+nF2<U}V2hBB9*z$kBjal-;K4nkNQC19(b2SFG0Dah
z;D9z<ga6X~9u_iqp==eEsmdctKJ)RTS%=-w7BgQ=H=V1bO6ZX0T*q$NqALC;$eU1D
z!)1Cy>EB;c7DJgH)Iki`mnd&5&;{1Nn>fg5aZI!G!+Z6;#g5?fkBT0S9+pmIlQfbY
zoh;Hw89IZ~!K3R3;!$LVD6l{M2NGiqWaR_ikmr!W=e20L{F$4TC%Ah}Ux|pvN?ZM&
z#rGF+T1}Zd_*5Xu)$zQpem?A~D>Vn(-TO92g4t+yfd<9}k4Rubric(xQ3ZD^&W3QV
z;lGqrFD*L)zRjJ617kv|ZxBx+B`#FT*2crP`!(w?uEEhG?-@$|){MBq(i?kM#!c7A
z!?Gh}ldks=F7J3cAlu^Op^Ebs>O^E_!*Ngu0kfOMbOpA9@U}DvZF=X;6oP(5iyhAr
zAb;r=O`wG%e}0!rV=71mJTg3-JcTL-zv8K7fKOa%UmzDP9+6)*KN^E*${l?s&G`X(
zGs2g&<kF6&l{W)Yg2*(^-9a4CSVn9qu4LiID_tmWn9a@B2<QO0gbdndQOUOua~G*1
zwatX~2juc&4N)S-<Bzt)sLxM;tLM{+HDrQC3?k9}@_Cy8FT&E+CA$e0ZiU%;L}qrt
zCe1~2O=XI%PpMu^lck@)VK+$H>VX5n79M@Ef{bGbRmFR`Z1f86d+L1PI<*-@`$|jY
z;Eg4%S?sFpBuKBTDWA>!f$k!e_Sko^UuXLPYq36tBt)ehk9tj|+!>i@e%MzD;47Pf
zZdy7G4sdbk8!%`2jGY^LN|$z!Djcp$PP4M`3@-%2UrBQsjXzZ=S5`A*+7B^<bidoN
zQ`k8*fiMKH?|!Mg+w{4mP3&Yzr!0mV1i9hZ?_+%a%;oy~N(P4V+>f0-Xjq#{fyUK_
zyImpRe$Z~9XdietGiJGZf8sXTw+S4dAAb(8+tDZG-b5g_0rW=fFYYI(>|1Y!v3~LU
z0#ib~4@cdX*tZZe-VX`KN~nO?ba`^KgrPm;TT%R_KQ@}|GGrtPnfPmaRpGkLm_3kt
zQQ-KM5Nx{JCAS^MEPc2%P5lG0r^cgiWr5$u^i}k}UHu;Ej{H65Xmlp{1m}fBMxY*Q
z!ibXU3;67#;H~sN{eXS9I+Z-g)nI;@Lhk2UKYMl^eCVyv*Vj2x87+2|eEA~G_!Ojr
zR%celDzS}-e?aU6Z!Zy30~!6@t3xA&ysXoYSwu`s(&>XA1$JBk%gd(e9rKR7<@(r$
zVVqSN1fgQpt5})8V`oy>P4fNO{npCLx8MpX9W(X6av7~N7{lY^nTGDB_dO$dO7Sfn
zYK9HXm4n5UK!t-j3JwR5wVEkw><{B`(!p-$N=dlUR>3k<|BktSG)PeZ8$wCZTnVpz
zZs*BU!m24&273U)ot<l{9>l)lM*_vLB8>uobd8u05fN!_ZsoKUprYfITDfzL$fs!F
z=Qa2)=ZVwXb&zY=pyz)58X&zo^@}C$7`~3hCKY^&=wUa*!kYdTjafR^Xv0Ee^uGs&
zR;W>t)GxijUZN%69u{%zx-&h8Pffqwy2^$~vPVrFhlX0`3n9U~q=a*-_$(|%X)^ws
zP3qh%xmwfh?i=9p3#N-~VZJQR5z9n@4yS84#PBDgAv(lYt3%NEz7hM{I3Vf<^LzFD
z-<t^gpC?Vn0_Nt6`PQ_+Rmw~_*9fh`n9%zV_HqGFwehxF9mtnSO6LA6@{S-PAj{nU
z3R0L?&;LJv|D&uaHqDupRn&X(OPnG*GaG15>PtzLAVB(Z@9%opp|K(9P|ecM$dkP4
z6RR}}02btR-TpaVE5So5mp$;9gd`6;w<#Lf+h{*u{c!4=Y&>9K>)}6FhCHNGQs<j&
zxR_QkEq|~))1&(;XI!(~ZKH<5gXUg$T;}21*=>8x2K6cg1g+vv-cLuR-+<p{Tw2FJ
z$LTs_QCM56b&Gp$h#R#vs<0En>uf1#-PJ-kB6vO-#KTjC;8IjlvQF>_!Fv6@BG_ag
z!5qd-wLqQe9{oPgZ~fxId0N(Ji-lEAm~~)42)qqwwpZ;f($mtZRQCkXlR{a&?hY<h
z8emH(ZNC$@JYUs#);QbQ0g?6bQtmn5uy=63JUUtavu*3o$j<I=bXO<COXg3zu}=%D
z_4VV23(n&6MTgJ6d<nEMWMM4azy5@XsPlp)jyotIAUyl@b!lKw(7?dJ?A)vek`bVO
zLqkHWrkS;qfby>4I+`P%;Q|cYC+jQIC!E`N;-`{gV_hXCDiG5Z7Z+`N13CwSFdS)3
zwGzvg{spM&3ARFz=8zqFku8_Kmd=xmF!wC~qz;J><y(xgzouelW+s#hc}=}w(aO0v
zs}S~Xr)<dlT=yU$V2%~DbujQPWY_f7GhWBH`IGFL<>szy-I36w<8L(3p88iCy8&~2
zPV0a;V#hOd&0)Q7yd=YB=5jk7G0fBSn}2t^<N*2x>b{m8LLx7?F#oQNj9PxA@bqHC
zWoBzIwaJK}^WA7xvbUFO>)Mr5ABjzo{#tV6%?9jUzqM-$>-81=5Bzi8_WV^iwV*Ii
z#T5}18?rTtpQ^wd3NjT&Gn@UUPtF8|=&jbZGETsNEVvdtAeeaC5+-PM=5;RLMmi*|
ziM**6F)Jzx+06oV))A=t&^@-gv%`uFKm&Dvt9E>RvtG6Q067MFE?3{zpO~+VmkYKx
z&P<@tbAdK0*5kFJM1Y^742Ex+Te7He^J=6@*bA6auOeo{xvebP<OWj{KDS)`u%gur
zxBmcU-+@iJv}t?qx78FP6A?S*o)T?d{a?9&gLh}6k+9mJCOsC$h=%TX6setvi`4>v
zEdZ77vyqvJcX8*%&4zb&c1{nBHpk*A<9VG{KMrY%h-nm7pOwJ!h7<S=Qz{mbRukpz
z3<50LAZaT6WniVV8yzj^YW|UtfxS2-#TIPLU5<C}bk>Ngx}RDy%&52qT<v#9?0(;l
z?OsIF2fHtnb9)^xpk5fO0p`2lz~Fpi-1w<N;jN>0ZLHe$R0hz+r}v(cd41xxT6S?I
zed9J5zg6qr`9o;@kCLF(WX6WKBQj}-l!cD&Bq|cu44s)-aWkks%5Q!?<0tEn$5|!)
zfQK==sF#?GjCPA~G_$z>@93M-l1=w*1@+3~6N`a<MNl{ZTR9l`7s6B`&s79~1_S@$
ztTgAOYx~d7utIL)5R+t1$JRWX&GB+gMZ~m#yXhLRjSH7K!%J(ylaq&_YAJT{4|Egb
z)}U3(VcQ+<?_x8ASeTips5?FY$e`mJJ!H;st`BKh7SXKth&*A5iEoTn>vqeeqkoTR
zJ5@2~pI-R8OrNLpKU~?;a^3O`Q|7FhrA=q!-;7Dejt*xETc-Ya$L$+t^4<U~Kf)L{
ztW9a<BqygG5D;k--4`>+Y|?<NetF!K>^l2cJ?HIBy&mc?OP6JA2WCveAGD4@XnxEi
ztBHE;Sr!PFuU_(9ivH8%+MAy(Kn;ZE=Xjk7GDFoq$KhL|ljD}oXTCDQ^<JUtawj|4
zcnik#G7=KY{Z)|&8PFuA;tXo-`>Fn<X^8jY!eDGExmYQuM~u;WQ??sJ3vtv#fm}IC
zWD<-~NlA3~oNMO3JYKqKy~~K{TbDN!!cW`ZKd&CAZEjNyE<B?#b~`vWbAR(1&a7#-
z`{(oLc+v+;6Q$Ft^_!o8-PBCp3lVGj>+doE_r5%r_isvNIb3u9QZVQ|s<*+|>alz5
zpUk~}=Fn3y)_EdvLSo{yF`1jk_OnDIXxD?<<e25eJokp$#sh)<{M2k1AJ7M}_wcwP
zCG5T0gQho))q3RJjhc^}LirA!LFl7(?88Y5;>Z%@mNd6&Rl6UAhr=UJ5}#GJu3^lt
zsf1BKJnT79B>+_UTXyr0K_B78`kpH|HTh<@H!oz9yU+EZ#&G8Q0vl0*dk>|EorW?3
z#&<m*zKe^6EzAs7L-GJPtP{$)<-XWE06P271!s0m-yV9-q$RL4oH2SYs7QTP-K4>;
zcrOpuA?0CdayuRx@jiE2)2z>ubV3)=yh2>Q*u<Xq8D;ZF24NU(UqmT;I-AFAY?tTh
z>zPj$!?GjLiB9f@zW`rQF*^Y(>8*7w1^kS8L)Q)s*EMT4Pgf70k2XMCaHJz+V&0zB
zmgc!`B*?#G8*Lz<0^jUIhvjV|{_;!L76ecWoG&5cFC1>FATlx>yQ`gcCEX5|Q&(Ad
zc~3ggbo@K}4xl<eU{ddl4jCblZFQMG{W!rpJL&Kbu0ApVkW?J3xi^BI&RU(VzB+e6
zop!`cNTk7S$rwKjP+M7u=$fg*F3+(cQmFG4lS<r+tJjW3WBP+fye`kfB!Z0QkCzf{
z&+HI#i)?C!fv+H?z7q>7L*unZK^dwgy_rgF_VG#Xc5W@jquG-O4Mg4X5Qm@p`(>bT
z?`e0!1oUCv=y(dSvnyE4I(ByWRy(bwnM;xkfc~d>e+q6;yi0QV?cJTL<2lFTx;|Z}
zX)YxNVT=A`y%5LwzZ(_{OWnx^ssQW>?EQYOx1p@fqJ2@0NKWR8;?&3XOSC9-)xAR;
zR6B0IwLhw&@YvshPE=S}00u+;^{zL{+KK$1e%w%Fs#hPoY_2ymGn(tP8QVpJiz3QT
z>Dzt8qF+STlv7*5(7NqqQ`p8tbS`!)aByNPfx<#ENRb(WlbGP4il4icss)AiHymrG
zcF@R%4q@=L6hvz|3Qbg4p$lZB3reb#QVc?Q%~whY)yH_o2Pm)ODqD6ry?1|eP;S|$
zMKoSv<p2y_@a$+n8rfBAw_6UNHpm76>0y_(@k}NEgCSDNH*eMsE^BJy$O40;uObP$
z@7ObvwsHmb_Ht4Wm$bPq4#(m=Opqs0Zo#6rY&PBocYns_D`s$TaJXJ!)M9O<prPS(
z+P})x^@4LiCyD1%ug@EK!ESx_k?j|2_0Y=;|56IqKjc9zRPt=~%U?Xz)oYwLyzEYb
zfn(CIsHvf`TFIWCCn%w%wcg>2t6JJLn<-r|Om!7^<zj=nAGh7yAo4eF-c0^|E(}DG
zq<gwLllD3$%c2I|<U~wSeDg6g`C6F*0-K}h54Wa0589G73Wh;Tl+9$B>weBXgw31G
z@ZOCu!OI9g!OQXC0t*xMAJ5hT1LnZm1tiuucPIsH6joY#0B{|qjh$HL&Yhj1t(2=(
z5yGyD2c;BpohyDsY3dc^fjDfBq<-(hA6UdKU%lC*VsF6bfJ@<d)*q}IwmG%7Ub^~P
z4c2X}2>=<=@WS?vZb*HWd^+p1X*74K9)K&pJKCO0=CbbU?DPW1Vx2qY*{6O<vT;=2
zr$^wtH!tn@0@q3W)VPz#dlBgj4)gQUo}~#7O>})_Q?cXmh{;0%0ZR7NIC;oNwe4ZP
zEtS#_Q@4(<uH0p8OnOA~a;FkheB7OurVjIXkDZ5Bp<WCm=ZMPyPt9^mO7Gn}Sij|=
z;029jWJM1+KNcN%L2VlN#NCgLOL-biImXB$$nIow@xpdPlri0?ykXD7y6y{kHD{5-
z&2;gQeQwXdu%H^t#!P%0PmU$f+T2g!J^m7)R?42gO}PX|fSAac>Zav|YtWE6?4~-8
z`TX|WDJfI<FdXWoU1h!jJn%A4nkR2Gy8xMW(<<lM@a55fPb6Sxau>F@SImT#y6zd@
zpT$P0q*3=LLvKB@mXfk!+_&V?G*%g=B>X0d^et$(+?fm-0Kk-v5v{Q*C2>Ign#-WH
z70C=-6%0Jy`iF;<W^!cw=}va?W$nV#Xf))!574;m9cUW<4Z3;nDXYdhbSBrpUkCtH
z-tK;vf<n|xwJ*9+Glg0ZMMXrxitBuMBwZ+G>jlN1q*DqxS;>0Kvr*7~@4@RbeYoa5
zNX60z!h*+3i4#>yxat=eRKb=v2mJ)MMC~tK@CN~{%qxD%cNf4*|J}uSFJpJ_-hq*^
zI`d-FI2i(Q0Ng_SR!$puQdHDS`S?uk8r%7Q6V5l;`xK<)O+N#-?=c}EVbnfj?;xK|
z(0+)W4q;7`-HdM-T+@szzK7Ipwf1IEVGKuKvQEHYR20BCO7+rR8`}g7pX*cc(a;yi
z;pI8)e{FA&r^>FWj0-0lgsRsXR*6Wokvj}Zp3Chck;=ltXRlo6B5?r*$9QZP85Ah}
zEwK*jB6^Io^nmXacxRv`@#tNx_VlDFhx67r=4dW##jg2rN&d!Ix%3jB&FM^>(+rDx
zH9sFcDktaVJ61UuhGQ}nFCsJCb`@3NopU`rNBY7rH6w#EO$KXF7;ymp(aYA;(7mak
zqjPbR+{t@_$G;*HnOm*bK4pEli&X7wRH$={S~H1`g$)4|)KCm*=RyQ7iZSSCXY~{F
zHPpq0NgkYKc2*x^RXLSZ_x$+~E`S78fL%le*k3uX7rXP5^AG}J6w|RZzg<q&Jb4B>
z$%IRHY_j5Z#(#i6a*_A0aPcXhS6F_&X2cE+WWCye0bM=+&x3pZ=gDdOk7DxwQ$|OW
zdNtSYL#jL`tx;`rc9&=-`C9U!(coLhVSW2-={7u#;$*=G>tlO+J(>sWu*>QA@M0UN
zSZh*U$qzuvl~4RZOUqKaFHLlhh-JQE9*K?8DW>Znc`A1?2LIb!OZmL*Tg!LWC}~d4
z2z}9GHD;orW=Z8ruk$b{i%zX!M+u8&MNU=<;E$(I=0A#x^xxl{(o_^3deST+&L9A;
zp-0YFo8zN{hN%&1><llTiW;r|!T<+bX^M?{7sZLY2j{%K7rESReYr$DYWhk{?EC{K
zXR`NBiz<{wy~5H}PA=3u4x|Kd@rd6#E}MOj7t~%M!6xTkU!~0kMa;}{hs=k@H6=F<
z0?z1<!z-mYITa5N>FsnN@ar)$k9T%<`uh5$4rzSc*EU>qKIv%yE*f4n$K~FOP(Euu
zgXNEzs@OC~`@bWt`?=hy9}pZ85)vG28CV4o#s6n?;{X_re^a3cy9x;AtThc>`IC4k
zymy=D<ToeFrOATb_LtcgLMP;Sa~t}x=~7ce@E1WTF7PWK=o(;+R)SMgb>VMHIA%T&
z`#dvfS<&3qwzd)Pg&CR^C-+>BhI&D8Yrs)nGZ#AHcCeni{}t<JJ_oM}V9K!QXp>SH
zf^Mj;FzKI(I8pI7;F&Ry*}f%pk*!+-{j>^y=e@aS9Optt*0NJ6{@1yQn%nsV^wksP
z{QFEn(jq7%1oAfnG**DvXwELa8zd~ES`+EyFDP3>l8??01#`9?c7IT^)oyDE3)l8z
z@d^KVkK6P1RUkkpJEG&{#Qb@-hNz%vjEwwa&qE9T14uhkiJP_>F6}yKqsjBBb%sQM
z2GWe@VPb{Vcus2;3MY?U339b*iKC~idwzFD?1LGW0jz{Q`%=$B#Ewtw@#mH24NcHy
z3V7Ck(?m@Y1(*{Cn05erY@*jm?2Jc^qMrBFgyQ(T0@n=a5txHaFE7Uo4k{B))6_;r
zzQ}Hz!?c@)N2U|^zUkrT)@!86E0^%A1O0zNtkp*gs>UyGq}-$QDf;jf8<)L=PA~<S
z8B(&c>byKdGqNj&52f4(><D;oI6H(cK?>pD9)Z8RMrbzjH*g=SAM*h=4acp2D1DWw
z_3r<-d3i~4$jCP_hXL~Lv@|p?*O5g<MU|E9rmwQHGX326^96y-aqyd-v<-+T@Q$D!
z?@$J94-o9HZvBgQ43Q)$(&}dlq6IJvMSBe@>h$?19RYXEnxY$p*GBE;B$14?^d@It
z18(~H-Tlw|+eXI6ukBQV?Zm*qa2FyWC&v{_)!FLU)1i?1*O3=lxw_hLaiW=e*Zbml
zWN1W-K0NQP`+v<{M07Mr-*ob}WoCWbNbu!M4OwBOmy%QU@~Xf4neWnOHE@CH38LI`
zrNn)+O5RW4%EEBoR~Eq-IA4AU6nP_N-i!+jH$q8q-Vp|ew+AQ*mD>-kx=hDre!Tt$
z>M1K1eb?r!feE|XFSMSVd?N@933?OXeV0?WSZ&@h*IQoukpQ5ayUTen7%88-{U4O)
z?Ry}HZ;e8ma<m-dKOg*&z?%N+WwxAL%H0Uya};VGCJKiX=#)B-^&2q;gJJ{r&p+_e
zL5`T0cLK~c{|D$$U_v3FD^u^4)BVW5BT|W?NBH7Wcq#j_|N9O<e<3R?N5QU_dCbnv
zez*Jy$Z&Q`s3|LFtZod*FJ0`Sk$20>jL<|pPFGmSt8cK^L83;ZYia1{7zZVR;q!Nz
zMMdVW{@QRB+?7y6(ICRaDLiGsD6vI5@c8&@NlFH^t+B_m0REP{PM`~wmj0uhfq-~p
z9Ov2;8J`Q|An3W|Gww-BZ^XYcZk#_aOiIV1Y+l(9iC9jbl@4i0n$+1BB&!tYyx9*f
zwW-2X*w+ve-Lfh|ydS?aC}*5lpi!p*fS+3HE*7fVg2&_EzuzYOXRcNI1l>cjRdvcb
zBmrlE7B(tMT<~1YQ}3NSo(T{9g`R(zJ~O}ga+9t8?YU1)3w?9L<t87ZRi#ivz<K=$
zgrjx54q|{_x(r6bZC!1#Iz|8Rx&4&W$k8Eadl)U!`=FdbyS)HN>;RJ`|6Et9{JWjX
zyNo=a?THr*I~fWl-XA^iHyA5fV2l#e{-l>JM<x#CSRGr^F?Cr^1!R2&vN}#v^CZgM
z2`-yF;MN$eu!=XQK}REV_Kt1(|Kma6f~~R$nFeflDI>=YB@SL^J8joDi6|&g00cF(
z{v#@CwA4iYQYk>27m&c)&9%Py&A;aNG>H!rrDSMiFSQG2X^;qZT8uR*v+-8r6n9_E
zHMw{9UX9CE;TKuClrep~x9e1lj8a3>oi?f}<0Z`BS>xa8kV9j45d47hGo;GUQC0`S
z{u7{g2`_OY<Kp_an(F}|9*ra#De{X(FDMFO{oMwyb3lh*(0KnpOQ@UW<a)1VS#>GV
zWg2j3S6ozMBBa|6mir7AyQ0tI|4}8HUrM%L?KKY_0C{P_<N1cqA=qa1v22IU82hEu
zE$_E_jTwMg+`M^vZ=%BNjZvqS%QO#WSkoq6;Is+x0J8^Yv1!<o+nTNe4QhG9@9mlH
z6wOBsv;5Sk@bJ4!D;W*KXsY9>Q;IW}zzXa0^XXIaoK@Pb+H<kYj>S003?Qf}MyOhi
z)d~%D@hm-n?qIkXbBI_^BEU6swQ&Qdp6U*<*yieJY2}|SEG*`h_;mGWIayq0{e*!g
zpX@}p)rd@K+LzDyO+Ws592l6-1fuLwxcF>Ec9KWhRO$w~>wa-Zq)kx_OVhVRPV4p2
zs$|c4b4;AejHmbhvI3!C*u2z;wo6?t8qfskb9^)Gvfv5v^SgOa{lJ%Sbtj&+#uC`q
zF#{{>0kW&RJCWO42*Q?&;L}l12*08C+2VfZj~|cN?x|RWx2-8~66_PH>HlpMb&;$3
z;P?DLCN6}wM!CbdsTwU`$0}0?goU}EV`8%tcpcGjmVqn*3No^dnSH>T3IxBa9HOP5
zZ^yXtj}t(QzSB$)g~Xj9kmvW>WyluTnOAD^PgX6K9Ru{NfS9vE+hvM#s>VqvRgaP2
zuX7FQ1OFEN+#w5)cLUM!nY5ow5K(sz@81188D$r~7!K3++=b!bdegzOr^%-a(a_UG
zj`j`byjJRL1vz6*yygc|UBb7q)Be`fYy;Y5TxxDPRqX_`TsSOfz%86Cvn%B%cb$I>
zsasvmLna8?Seu(84$40G9{^2}@#vsM)p2V3#^yV!+D<JY+*(LsNxoRQY^9-opfdt_
zIc0Zh6>(Ugwu71RzAX5{LP>cs?cQljUOV@@hM2pq|Lck2>LZqa9d=w67K_^o-qr7c
zMo0DKXWVo7(o%=cjo$7NMi7Q*y6><5g;tqGvi)2whWcOt9lJY!l4P{(VA4q`0<?dC
zoZ3X0nUb0*Oi;ZP&@#F*mycbZtR=TE&i17ru8&!aH3%Bmnpus_6CgA|p+u3=VLUfG
zxNaX`y?r||GA{3L?}gH4B@jLFy!hgW{=grsis!d)xJvLJvr5TaV8-k9enm|^ml>^7
zXzaf^Royv<Y&a*Xv>#ZMjgWU*nH*~{-djx0maA)9!vI<kOe!wLZA-oi`yqtg9GwdP
zZfgk1DTd-v<>Ghh2bcB=u=ICBN{QF=f!cr(Yi@3CkKmyrM6<?u?W7}t(Z3EU>Erb2
za5IuM{*Ue3tVte7(gDa#Aeh($|K!m?Jm&k_Af{h84Og)UEAaeD8PdI`0*<<D82}b?
zJUt)-%=*wj52h~e6jhvz7@C-DO~v;C(vqJ-leF$}JbMdkg*AG^`G<gD53{(2gp+u^
zqol0=;LnIFSTZK%eY~JbD5c?0!Rwd~ic-p{JCmjIpxreeQ6L!*;Cl;C8M6&S$@a^y
zN#1%OOEocX2C7wT&v<5ikSCipTOXe3`mO(WgUh_BhS%%&ih*IJOzD#3Ky!`cnFKx@
zFd%owdmqTV9}dWq%omG?QKL6__V)(_k3Sv6NVj?JVYuh$<=p1VV?R^tka>2omri>r
zLH;hWXv*;{I1)-ZZ3#b%6Z;UY<<S>wa=(1clERB)sh|BRuJw4yLiA@}`8!$;BZ)5e
zpT9l=?6#V~;1I^GA!GxGU*`@t&>nzpql^<|3!KJ#OA+Ij^OU|e)jMv-suzEn#uyDt
zun|0XehPiCcscl8>Cr8~?zc2cD-EuxDR36=?w3|2qYZk<1sFF$ra>I&thhIcYZd7q
z2f}6wiTMqG^y9JM<x4+pd~|=}2^rb>_6MU6VcOist(8ZWpqvJ-XE^@J!r}r0^t94`
zE$=mW@uW{@3hJL$S4@C3Svd?qAS^}-^Y)wgZ7&4~=z{^18>ygP#My_uA077_*o$HS
zc@TJPdw02%@8!ombNyxO3OMgV`K5?~%#CnRi~YD+wsN%tV4<D%_8tZ~z1+Ngsq^?-
zZW#9O?x36}Ce~WoQ@0(ym47RGJ{Z}+^<nK#726(;_Ce^olN_4{9Y9)Ss7a4Uir>F4
z#s2-OqaFvB!1vc5j2mQm13k)Zu$Xs|4MMJh%AS>M(9Qwp^1e9pC$IIMu5|@|)KU^3
zGc9c<!hn3buI3D;Sq0oVm4b%~M<Y>}H5NOwnF}gOp2M+`bdcA7JV#iK<`!l?HO=>>
zi$f-P4O;V(z1ih8H;3|;+_&nLtZ_;Z_uuATwmH0uGTnkbf0I4QGqhmOa045Gf#*+(
z(JNxu1hw!~5VoWR4tpESX-xOxJvP$g*&sF+wMq#Ke@+k`twMK!92bz6Vzj-VKR-X;
zRO6Coewj8Kk?eIM=@&8V+WYZT%xYz2#m`TL&=Trdo-x}AusBJB4NwT%N`Iz9G;1PL
zVKTQ(eFb1Q%I2Y{qX1q3h(kev<Tt-T4nhSeH!XPU?mcC$#Z)jLgxWiluP`%LYxSBq
z#2RJpgOjIS<2<769&)*|DNvK_wi+8)6H>oSb*D(jZDj#CC8W-3H3X+gAG_H>Qiax_
zb#ZBlO}#e92n`?a)Twjl+<dX=L=Kp(+)k3cFEWXn+mbyF&L6Iw%Tu$!xpk6bfeb)+
zIQysV6jkFcQumb@oBHE}zvm`*CW{TSD{M~-P#IZSAann4DXj9(Uw`tCoJtys2x6)K
zXi4BaAdb-FNi>rDF=nX(RLzo{`$V6fBwLS{RrTYn6*Y}x_=>kspp|sDC0*QN;IWF)
zbnQ)$)#d{_Y-cMl@<CUvvwdT{=qkhGqvUDt86e}l5*-@<)~@lbYc;60g5o-A#u>e@
zYRsymC3(G2(<WJ;<2f?k!*@vIN##Wr2{PGjBoR`#vi*0d16l=hSoC;p*H6eeO1x{h
zdgH$q9J0i)C%ly4@H-qwIxP?Ixv4fR1r20%%)wN3$SeCd9KociV(>3zTvL_8h}623
z4W8L5URofl%!g~Xkm{u>_llYaK!|4FydACMQE1cfnGjc`=l5@N?u(K@|B{IfSdvG8
zIN*6tlryojJKlq8DW(ah6w4V?|3@T)w2YYhC*#YPF~_SG79;s24lA_dKV%|&YIhbj
zOMsC?vq9PI=f5L#YJk%SipcNQi=2V~V*cj@*>GHO`d2`CF4y5+zHvyO=}T}nW}2}{
zta3PAKJFxa&?d`0^ZKwfEL+~)>!@9UlYbn%85-Jxc^XW*(}^Bf{C!UKB&2|GDEL3%
z6H<<{1W~k>aQBKM@VX9@xi8N^(xvQL3~<6cR|nk<|DOF_GC$=%`qNax!%mr+QnX!|
z>vFg;fpS_?fstE{mqpL-?4sG2Mur*c)Jx~W_$m-RKcH$y-6JzO9}!@f-zZ%8xwsBO
zMocQqhjzb_*!=G9W<f#HejW-Q*$(<W<-ZthLQQjJ>KW(VC%R>a#f;(n`ICz0N!u53
z_gY6bm(}#yl*<fy7x0_&Ij?GLhD6{KuvO}cB+s4hZ;e1<-O;E|i+RZB_rIwc*VgJ@
zG;&XS>@CJ$9!|TLGKPLF*K7J_Q?DHh<eh)Dhc9rE*)@ae*_k4QBKO)YyODYWveqYj
zt2yb)*UhJE$NVX3M@rkmf&I>haL*JvCi7)Y4%Mh4f!81-D_J*-un^vFi2P{!Co&iJ
zzhWl%JhNDO$BN@8{v=)wV#M?*g~uz;6Q=Q!roR#r-?ye}R7U`jn$w#8Yq3eUiH$^F
zm+GaYnsPEO>(Ni=c-$S0-P}{74Ko4a6ho)+AWA=px51h=P&F!^42OCY=O>Sk78|6c
zr^AxkLHzc=H22j}QN3-ug9svu`2&;`1w_)KB^8lwP+|~i5Rjo86~&@UX{13ydPGX3
z1w^_9W+(}17-GJAqwjm(wa!21to5Cke^_f`v-k7t{XF-5UDthIme<exI&t3#0%C}$
zsIHwff}@KQepdik!ENwq4gz<rVm&l^#I07=(rOQOqd!;xum114t*L~V&`{5%xAxSB
zKK@`44!~U1dJ7;IGUg25pv5~lEdbiCsQ895i{<9?xxvyrJ)HzwgTW%(`OzZF&dF*q
z&{sfgZ2#<8PZ)WuV=YyfX@KY3sRR$RKH({et*%Zet*^p`cI?GLAhqbWGS$++Bw_m@
zD-}~XNfsA-+wIMpSL#kz!G?&OA|E%@MjS5$5C_&LL&v35=kki^IEcGE+OQXBcs4zM
zR+Dt1J#FX8US_Soe}7(!R0K>fH8=l#!cgTW{m=clzKw%hqCai9BJ<up>c@jFuwg@Z
zA!3Gai~h;lZ1=CGi%jKv&tq(>jODF#o4<DwX9$8`gcfw33+}}j>}Ofz0(N_D8}Y*@
z>nZ$OmI&5%jnVO9H~E{(Y3|E(i&fKIUg_@Dd=U{I{&{21AArVP-<gO>fQ!TzcaDf}
zJFYvlS7lgzfXRRoK;`snEG$N=GN!fF=5vGTbYEeE%ld+}4nS_}`!r|ITB?%!5A$ZK
z)^()ORX>q2ly~R1_?`GJPm!;e?Gdi=B!sf=5MxYwT`@e8&-!S~YUz}gfai7!9h1*4
zVXbu3-u!3uHUDE;EaxCIPmWa-PR&wQo^yF1E$wNPr1h-t>2a~~CD)>|9Cq)K0{mNJ
zl}0`eRetA<E+W12`n|{2;xXG;%8Jd+vdau8g?~X2wx@L8@zD6+;&b+hi#gUEc~DC%
z@J0b#Qo&C3?grD3lKB+5(_D;#vuQE5FJ1;P3Oc`8*DOeakmYWLl@cV~&GY^5@2wcs
zwuy}Yu5HO-zG3qF#mU-YJf!7u9&N$~pB%N}guiEhrcp47bC7&pcNM%du?|(LEUI_!
zZo<xLZf14~N(baO`YXK}R3vN~TU&C<GP71eRriKR&pY$XrwX7HuMq1)fJWSdDC$>_
zSGu&__r%8mp|t`cH#?&*o<hy$r4*%Y7{O3Kdc?uWS)hA_%}q{8Nh>28x^bm<h6D$n
z0oY`A7623IMN~}b#6Mq0+a~7nma^jQG`YNoHAkbyWn`vMiO>V>%I&9W)_$p~7csM}
z6<0ZKius=s1+$CeU@e-YjO42qRiCl_D|KtLxL#jhcgc|N+B1<$zt{3#zYfYXC-R3i
zIfCurrLHEP(jo5u_<ju^RK!|b$LhEJ_@VwxH#BV0xg2+}ehX9WF0wIX)WGQSL7Ior
z;akUECTH!5zqij%^UG((Cnl%^@@H>}S{^=pnDdS;7Vkq@>^Nvsnsxc#SQMN(yM|xG
z1TQbIcE%N91I&-}=f8Cjl|SkDTwE73s;(xX<Y!M;P>!ZF{ud}00;WwtGTPaI5M+=D
ztM%L$tokvu=A-eC)x%lhaORi4;nF#MkksCmZE*b@9~;XM)R3&oBP@e?|GAm#qLOkP
zWfmkj1`e%Sl>Fx|LXXT`&d+C|Jo$j{BPcybI*d>lpK2Cja4zf*jf_lFC3|@UEI|x-
z&8L;a51JS^sN5}Z&6MsYKgw|V*Sugr{d3#L|LhAT!C<Oy|DmUFP(KM)*Q>5WYHHBT
zs);h9skOCu(1u;(7BmN`xv!d}rh3<Py?+W|mjucP%hA33t(8hxgmtKt?MP@0{&aL2
zlNm>V*W?<D!U)|Q?PrvfM~<*ngle!}<aC^gxTAQ-)oJq0?ZXzUeB$B@t%B$&oW);w
z$LQku^XHp-*RwJjb*Jf57`!pk082w=9~=4rQuY_HC@(#mN;qPv*z-@*VYjVROGc3*
zo!@^KEWhN&#>TH-S?>ksvkMAFkvNCvIi$u?3bPc%2EVoVcvthO&=!uxWym{Q8YK**
zK9%Mst?_*l3eh+FIfX>|a6B{{T8>sc35g%o_n&u4hiqMdT^O9dO7{l3m`Ei!|MsQf
z)pZ0@72O;e&d=b@+ZrpJ>{E4GEBV0*m;VIAS<9AOhfWQ#rl(xLTX@01UWnlo&h0Z(
zatEsv`qnK!tD{xKy#}@@{Z9_PywtfOjuu3Mbsm_#N%0H(-J>OCSwG0Bs0haJoEpVV
z;-EXI>kTGq0bEP7P9z_%p`r4V*jM%PdEs_9K9C)$6w36GppGQO^|_4DCj4Tl_`&io
zXcnZ~un2c_TtVY`E?sJC{>IHo`8x37GC%%5jzrm=0gdj>THQUqy;Xqr1k24WqaJoN
z4#%{gfs4zRWBW6!N?ksTzI%5XBW&7l^6Cyu`>P*1vRU^p@$eMu<^Ts2Q7m<>MbKtb
zDlcmT%ov6o7QFy!juGi&bkbZDT`1fAT6vK}>_6b~3^e3hexgi4dRq@Za3nl6e#q@#
zYqZkwo-4WIABf+<>cz2XV##xP#ym)juvsI**%KnmWDjxjQMwy<W{_q7FU!LatQq-Q
zMlGaayWRC}=$eIG<cKb3x8JZW9}iE2EKkJg+fT0u@bV&M@|QWh!oJVP-7AcDTYon9
zf!is6`g_tY#0ZWH*xGP3EZLG5_K7%2D!GV$v%;<S3B+6$Ho_G>ZuYPyj(6H9F;=PN
z$HUtzt~ZqZYnf|b0vrkAce(LZW`l^8y3cN}X}qx}GX>DYr~5kOTU1Qfe}5}%JL686
zkspOSJuzf|TSzR~k&CRg-N;JQ2@>FV%67Hj<)k+L4(A5+lJLAYnT??I{ABZk%+9ly
zE&@83*}&-W#w0H55+WJ9y}uawiiF7*eZ9*Y)iSZvSTH4Fn@W00^XwbqmCbl?mbv5D
z-Q|!i4{Wy`Bmq;oaj^9bXssJApL3?6(bY1B3AF1>vl;Z+%bQc%>x3Aptn6-g7a}nH
zGXN;x+5asX*EiomRk><E+NpV8D-SRY@F^g)gje@>qtr{%B$9ulAzv%xzf4@%|FW;u
zbpDT9z`GbVnBdZnBVW%-fu9!(A@5w>FSn4ScD!o|@%@QF3%~sXM*J{$ddbP)`{>q%
zeQ|t7xOg^#vVTF^Qo&0T@vB<>a$j|lBFzZ-h41bi8M%a&lGE_SYnWa8^Q}4AQfg$2
z8EbhUu+K^O2E}LJK@OvH%de@?(GNM)xx*nH99pcYI$c93zv7HLucZ>iJ|ob1V$z-B
zJDjre2*2%De#eWbNDA*tX3SLS-tr|oH*}VYoV*qpjuR#4dCZa*MAI%GrbTh&q?gvt
zXu{j56Uy9B$C5Idl(%yfou@;B3SV};Ay9r3Ik@DR%bV`U1R`GMz|nt7EQf(2=f=)u
z<Zwb6XQ`gUTE~7pnHsJmd<uhQP>w=A@qHT7&tMd2@!;ux$ps#?+AVl(_yF}NKX^#~
z2Uqt&<o=Gp(f%-~hpMK3kdLk_u_t$!gjT&^?=sJ4fYHb}*_6-P5IXv;fVlFfZ<GW%
zbMiU|R_pZHv<mk>dm6~>il4IhAy<sRF^B|o|Mh>aF~@%kJN|bQN1^^#yO0!9kfDT5
z<OOwXs!S)u#OMLBvgF!4?+iApgs4)x(KhXpf{2`lVsA^D+bg@R0#>h_IVwNOf$eMF
z|3E1lCxYnmGC~LEd4Z9GwX**qgcfpgas%!`K?hKNr!O5@URg1fnnkI>t_uq_L>FOl
zGl$t|QPp{J;rjgM!J^kFQTY;EHsPc0Si>=5NVt_GG<1UBavk=C4H8`240xkTZjUE@
z{dz0)c(^{w7vqS=bR#IFrnEP`%fis5AWV$3H=c*)^#N41to$KtI**!~u5NTy5IQ*-
zcL1d+lfb59gWMZ<d3kxrRAOw8=%FN^hKLS=gBRcgCr<_lOCExAN__69j_IZ>JaM2}
z0+)6R47`YzVGGR1P!@MU26xQ=!i5X9wx!wRx0=XM88P*o*x9FWYc&5uO$`l+K|sd7
zdgK`D`%6F>p%|!iu)=P%61em3a~xO{%BhEgO-HN)5VYo56f`d@2nL7rstHPz?*JD!
z_qUc74J!3$RSXFPqAUuz1na9_j3no7;p&Tfh+v#agK%mnUlFiohO#3dqLLOGWZ^6*
zUXgQQpFj<iWLZmlJG3f-X+X+@)_~*VN|nnv^feVm;GjZnxW1GWEJGZ>UPuv-pd?RA
zBR>}0zuhH&_s=`~*Pdi%&O@OrC}DKrEG6HDZjQiyf<j4GPb`_3n4Afy2Xk~c%^FGM
zmvO4$`ZcKy?FUg*=OiS2z!MweFGYen@enfuR0B`M<1b&NsacWP`hHlZiCQ07c0vZ{
zOLTL1qq61RXj7mpUV*M5!tOcdlA~sY8eF$DPZ^uecbFy$S;)iCd4jyW$_W9+B&b6q
zVNJ;8)CK$_k~M;iWfIL$DAzOx5#^U08hXkNWXP(}U*nDT_k(zG0c0LY4t~T@is+sr
zr4Yp^)R+~XJxX5K{{e!?vw%@HviNuT;GE=nQIfS3+D+65yZj|^NaaOfpxOD0C`nQZ
zdHb7ikrtOf@z@^4NbI-Bf#=^{282kkWcn3_+)`u@JAg{O^xeFv?%V>rDVYHoJOFH_
z=H{^0MjsfC+`r_&ZmU*sLV}Zv7YMy0mhSK#X5;$X#Blv2=(uri?ha#OVxlCBo4Zsd
zIWqZlZ){1q>k;Y54JLSi5=puXr<0K1TxO&ZEBcddLvNvu{rVsZ<e4BtNp>c+hrZrl
zqbNW&#rpT17J!4O;Sr2!We<X<5AL2c-%wb{{sd1b)HL1GGEz|WO8Pqplk$fzCZnc(
zyLD5(kmA{AZzizOBD)9ykHPlj8u*Il!fx>g3rLrqd~?m8iVkCypF3$I5W}Ff7pt63
zS#spI!42rWXERv3-K*~~zm}e0zpg?rK)xV=Z!0&!XLVa^@(42odMtP(+EtNkk&#hS
zWF258yB?mV<*X?$P8^e6j~1Gtq`t8%Iy&X&ZFAhFYW$a-W`$eD2w#=H=UB#Tm-&I5
z*;km;pHks+rG`lS;@-SD>h=&ipdWaWUR1QY&D_)S<zoW_;|F^y+{g^z`FwYwAik-0
z1d@^S=l3oZ1EU-W;3f9?A!uOi@vF5rYv7a7L>fG!r5A++E%Btp%?Xu)pG&R>dN)L7
zg<^7w2)&iNlfN36JQTH{tNE5`Q)ue#<fRdhG=dIT<N~VEiqFk0*;)Pt{%j5o4q80-
zxFdN?z1^1Tq84H?<p);%LVw+t=~s*B1qC+rGy~D5PR)g?m8tk^a~%!wu4~=Bhhn=7
zyMqqi1vT<oc3xyS+F{r{p$%4A>Wz@l?8L-;AL3~!E8r5Nz_Y7z?cb}zwmOpeO-}3m
zwQXU~s3g36rdj+m?!&?WBy3ynsOR>a10NVW4Figu(@Fu-$jNT&o}S<5c=QCk16)Qc
zz0~DEe!Uc78)0pTb+dL6$`byv8f6&L;Ls+#9b96g)p%pIdRHNe*T<63qGRCZCNKZ$
zfaB9Ymy)@&v!fyr!)0i)Q}!_{lJ#&_+OMIM7WT%VozGiGoEHY5E&NKBb69EQw5*nb
z^V_B7)yGejLo{~Bi)MP!4qA0yxCF@(WuKX6YP9G?tEZUL`+Xr$1gDzDlb~(=<T!LN
z)9I*~LtjIoM7Vq%SQzRq6gW+vHD4Sk_E<1yW(J@dBYXL*l05TddyL);;Uukok?T^Z
z75XhWL)Q2gnvM-*=cy-keKhvx;;mAgWl_gdd^V**DJgVvidJqfY-1CAPL@puN$eH%
zKLpSzX8p&i6<TO+u8>neDs=RBdD=+wF<c{)tXARL-u41^VIaHvF)JH;<;wc6^jP<L
zuMG(y*YDK}!{ubQ5qbH}!!8Bis|+QyE{4ZQ3L{JEv@Y;swBLw3U({$@0#=KE^#G8O
z4=tC;7V?eLhwhB<fQbO1cj*+C6CBva0oK<3WC`?l>XQ_@ufOa*o0bj+NmRB2&z?GK
zG`K!5IP}P2ZTs%)=I4%XTM_T**O||!#AfGy8ZXjNQ9~u_C}qs`6<MyV@F`}OtyFrw
zi^$y&{a{d@MfeW&M*`N7xmJAFt||OTkQZ!vw^Nn5abpc<EX&|s=99`T0Zfk|aj~Q&
zugrZWREFktU6tGqu1lW>N+mu3Oq*q-W;=dg1_E8*ktVSbl}XPs_qAx2o8&q}pB$U6
zx-ndJRaH6$y5hIAm)o8ROxLf^i!PrY-{s<oYy=9U`AfZ0Oyv&7KDA+{KiS`B3+VpM
zW*4qL3G(>~l^dp4-$81ItN-9r8b*FJcU9HLZZIv2y&-nXs$Yn^SKli&D*=EyJXd9I
zQ#@wyGeNBVESMczaf51~gi3kJR95(uOaK=5K<k=a)iv<ssmwF;KRnUUW22dNh}r$t
zt9*GuOM|P-?$aGE<`u<6kAQ7p+6v^*^nH|;&+-^DuQR6%`R&aV;t+T}@$d^Ma-)0E
zf+yfQ+na3&KWl@+?WzNV%-S<&@#aUx!~_JiX+}I2pAIgT6%O@~koq4K7h8a0JAI*c
z;_Bn=MX~j_$-64%?OP`G-*iYf0CZXdYw=q@qc6sL>M|V{oy)I2Vn0u+sp%z4jopn8
z`IrY=hI#xI&G^c-^$*(%KB|M^QBfCzqR=8E438T0=wsGrt#ixA>WP-t0ydj0A|kpp
zB1Lvpo-;bsqYr>L4iei-89G}zv971pS_IWbB>ZUsk_WHf5Q}2OL#a-_LPOW}YF#Ww
zYmG#k1Hoiyxb<0O>IrKSOir41ME9pPzvntt)|oGFVy6rlu8i+o2ojRsx?0&^C=vPW
zG1La!_y^Cvs<OWuKuz)I*(;(X2KME{7*UsTzoosALjo~gKkyMj=0HCzHX3UA50s4^
znimmbV-tQ990=H32o!6HC@|ipfyk@WW>DLfGd0&hWMjr5mN@f?(&;(K4#q<KTX+K*
zk2Qd4x>lvT0u(bpcp&}L_Q<49E~iH8T_%a0d~};H_v&o_O?s7HGp^RQwqrx-iTU~C
z5FF;n-zzqS?t?syc-K6%7}vti?s17mW1v1bhbgB?*l4YCGs78`lmY1GrE?nl;4)fH
ztnrt4w_@}&4LEc0rOo7dP*<nwWIf!gF@?63ipt7N?gUHf<1*O8T~tV#clv{6)?-zV
z<xJ?NO6YentJoO%P+DZf{cZ9^3%fGKkom~YmdA$Ks^~{M_%HaG(A1W_z3s(`pvBWd
z(*7@kUU$;)o)P{cvG+nhDJ`WqxFKScyLa+l6#YPYtn=+uhsQcMb9;*w5Sit?wC4}g
z(-5L+?cU9iIepRKp6%7lCGZReqRs{o^7df)u0xCMA|Poc9!ut90={~*&C`@HL+m*V
z#o<{#$>Zav+};EQY51bmFiDfq^8F{R_G>2w6pGzn#<Fb@`7a$i;9o%L*f3w}echw2
z06PEYpfzk?Rofdk92EDOUlYXHugcJB>(Z&)9&kcZTwi5GY6Xglo4FC~Lcd~5M?H7D
zG*lw92QM=De66b8Av<E|HSdId;t4xy(M&eJC%fys_qNS1hxQvFHc6ii;@h~NN`9WN
z*XrEtsF9MiCfSUGG=Acs0%P)zHDWow#D@C$*5z%B7F}k_%!gm=c6*z?Oj{p2L0vK0
zJPX*l!Hb4EdzL^|#8lFe_0~<x_ofYY;8x)=gO6U+?@nuB53I82B0E*n*z0CV;K~wU
zt-)@k(c|*67zc_hdE`2Q$b!><s>L6qUP-b{>vgYZ#dfGqK}$^4_WjAfPrqb(O7oS8
zh$yIN-27e}gvQJWVWXHJI~rPwzr2LWlmW8of-cpq#@6+wUW1iyh3yG~p17zZQ#ukW
zA<mYevEg%u6Fr<PHI=VNa`be{ThZM;&i+iCK_9nA7oiDdKeOj%NQVUj+*>P?e5y&|
zQ98~{WhZ2(EpC20aX-oEdPl)TdV)Y>LRP5-^F52+h3`7%nxQX-og3mH+&?bn>a((&
zZu$>Mam0Quv5mNcoEOYf%3<FNQ(;n{5#Jcu@bz=w-HziRQf4W02zE@b-oqf#wCLHh
zXP5il%N!x=s)xNn4;*i^ay-`OI%q113;v9v&f3L#Q_6ACf_7<E6FqviC2w0dhBkcl
zPaJ2uaVMK)XKTuk7VY@5)vSECL=WU`Qa|@J76IE^7%nvT@!WfHM11Gx@Xh1GDOne$
zws|GP!ieS9I|z&i*{VZtnwpxHTBr#;YX4F9+G<S~TkNqyY_5OiHP_+)hTJ%V?<*vk
zxt<!nKI{EMvl}4y$sHjyo>NrC@Ee3P^0TrG)X@fHjkOhyco6-WdvvN)FqmZ^Xtnfx
zMt6^!aXEpc2BggB?)Vh%u)Om18h<7%Vc=J)qczlAVHpv5pLyHGW*2!a8&%r_hY;Xm
zu5aF%tZM{R6}i}T0_lPPki6Xwy_TMt^D%jaWTn#EzGa}N6@^%!IJ;U!d}|IYltVmz
z(gu7|<z#`V6$CBN_EofAa5QYlD^7f#40|kc7z&KXoqEw;odLZ%BJp(+E*&rkuXCM9
zmo_Lf3;P|!y+L8Y7b7(0H?h4rMUnRsUEv<xYPMCRu2$u`dQSKYxREDGKa5$F-my!t
za=y07k$C0r7$8jD;nVfqkEV)$Rf^vCW!u}FX#eu%3m{qyk5toj-+2!6gB-oUcGxAE
z_mj!k6TSl;BTa`tul0zUNG;bG2Z^OkHlz$4v_kr1__E)J<s~9-;L!?Csb#5iLlE<J
z--Y8%UzkC_+%bLS=JTWRD;?VdZR)RGce~HZGCOq*!@ck|Or>gL@6hofmqoX!IE{t3
z<<3#VTPjKlYkBtN`pXts)@-a?Tnc*Mt*k+h4*dRQLBY~V+0FT=R$Z>Avfu#*R14=S
z)cQemU}DrC$_LJET*FWmzcw#eE%BTJb)8!2{TxNyAtukw&UP?wZoH|Z@BNN49)O^G
zc2!qg8!cme_S}Bpb=usglx!*`SXjE+^-AufIJFPEbmLSZ?#cns4W)VkbeqdtLn;v0
zo43bv<$k_RgN|Fm6lRIKJ1#i-*4Ssetnr6U@!fqJe1Zr9qXY=cW?d@RqqCtY@D5Mu
zFiUCXl;@6IoqQvK*(bb#NtS8GaAH+U8v5mB3G4wa38CXs-RCW2IVmyg>o*^E9wZ)v
z3Nm0JL1f-CPaN}SZi*vbiFy+l$m^q^PhWQHU|`>PR9xI{9qr1liUY<0XW#LjkGS`%
zO0-(nCpNVu(%gLanzgGsMxB33K8qO>Hw=p=m_TV22SGmOIq{PdmBH2=Sbx519%lOd
zk*DOxRBIyR<B?4!)|v3`2n}!O=S2uq)l3~kd0l@e71S&*#$x<?PUmyN$PE7(8H|5n
zG|L^hdsJ-3-WmtxnoS3P0vhBjruq9}%-~Lke;n`BM3C5fs-L=4*irF~6*quqOEz1`
z3a31Wata<>_U7?r`&op2ur7kF`Ne>Ny*Q!oG_t61(zo-MWMs@0c+_+8S#~}i6<brr
zYHfpdu-JB3cUE~|uSMrW@R22Axr4lozhnPL<0&e^-Mpb@dGj2~IY}t~Dz)PMDzW|H
zAzfyrmx`*E1GZUNL8~we;t#D0WPYU0fpi1#rId&Kqg%e)+<KMLp@|S&YK!EJclRo<
z%St@HZRj{gc0o3SE;!$E@=X*Uo!I0SZ5mK2GjEfFKJC29Hr;JJS)2E1d3n}Q0eg72
z)4b_VOj`l8EC9&cEA0{>=iBW#wAd64N{RJnwCPR74}&fQ{a&10as}_*n7DH17Nr3w
z#}(Nk(5nblwm;cQXsL6oGai^<Pw*LeaGlO$V|K=H1`|0flQ+-P`IuCNlZS^<7~@)X
zdYh>yNdcRqE+#tmHH`ci!|#~}=1hX+$mcDpUc+>&%zK5iyc>9?vK#U0b&BeA{>gLF
zH+W0ZR$i0hFB8wvJ!@+T#8et!<@YpyTkr&tQ!(6~=_$7E)%sMqc(@^(PIR|OW3hZ=
z0rD1y&eqbD^mI9NPq|ATQ0oL=zW)*7o^Vd#){zWbUKcIIExlKxCG;vL>@`Oj@>bse
z`T_$EHMv+`i7H9k*k-oPj}1(P?yUphI>hYu^(1u=79@pOb6&yVsc6Zbe_;W}q`7?a
zfd!A>Lnm5Io5n+(;(B%H;|~JzLcb?@Z8gPf=b^*?x%@Js$z*nP@s?H&FuG)coa4^r
zIWjVG+oLQ)h30uJ^CBrWdRpK=PAqf!wFnh~A@X<l%lqd9phGUz<e6&8992xxF-Np>
zcxS4@RHw37>T^*(!gBVg_n>a;F?C6cd8~5A`Cxaj>H}S%hP_wes-qS?D4o^-e)#ro
zrD>$%tiAn5Q1TVBPd$cg6R~JCN{^?#D@m$Xx*&>Ggh07AP@*!Z#0+vRc$(x@RG0<k
zK2(ccIDft#EixG*%bc*XbP>X^keFOr!>jA~D047jETldz>e1Ga^(Df~(z2i0+)=TJ
zG9IR-*?4>1KSEE!_KWw;*=8qVE~8KOfGgx}$HjIUd5Gm(07+O`;}&+GCG*;Lrmg9`
zrrGpBYs$>t?;U+q$gS_aWvWh<Vb&fBp&SBjNnS|8N!##a3zBu(;~}Ycp>i21<trqh
ztN~R4$zH)ZLla0IIrn^2(*qer9WC-^fdX3O(Opd~(bv@U+zk*E+xXTA5--&?N$g?G
zI_Prb8(6WnF4`=}>F?9ZmG=!gCmHiqq>N9WQa>DGEkB>TefFkG)UTBwGar3>aRAvu
zH%5u7H1%(=LXRq1C$s$y7H55iymxtXi*^Nf?NDx%)sJo+gE3-^<GuN`7Xu$1rbv&A
za~D6Wj;RM~M-k%U6zyx?<E+?r{oRvD7!5a8sa3bSvhJD(@ThKzDhe8saky=cL=yhB
zg5>ykpD`IXMa4V8qgydVml(>&K*Gxraw`_xFTEtJ3NOTG5-(oqhbk%IBs=19iD<BN
z!kl(b{ELI_h8}5E5s%|KLW>qs*DLgD2<%1sXjsurGz8?7RSm5%LJ$U7#U7L%@t-*w
z6^Q+6TUxc%Gl+MNSy@Vlf)fPrX=jop&*kIbP?cg_yZ@^PR{Y)L_wE*&&BxePoGzOQ
z9JKS8uG!x8aZ#zz=&o-imTP6HLm?RJqvzb25fy+M0kW(R$z5SA@1*h8Zf|P}NdlES
zR-@22eu_;&5#n;+XELucRar7|N(&C9in)yRdyAD9rPLJ_zrDi028|<|ilMh@8f6xg
zfiRA4q`0lnHeRX#jq*y>=G=37cApAQxx9F><s+25RpYZ)q5|7NW?U?bJsbzHBrI>|
z=1d@vxbzlo-MYHEi))KhRfg`cf8)`mU6LTd*P2nd{YJ=eS9G=M8SR_vbOBJqBKEr^
zt6}2ZmE<{fZwM8dE7nVMOvSD?4_}Qdy`Q8{*e2pab-Vj=V5bb~RjJgr{XN3Jwg3R#
zhbLn>rRH+@TMJGSOPd$)0!?vapbEUi{|e-Q;qnTpd{LijUW6n!f09<L)NacWIbl;h
z;I3?ZybFMLtJKUW#<h<g8}XuPI|<7H%H0s&Y?xK>;J?_Est8XFjh$-Gbl0oeYgmGu
z=(;=fn^-sUXI#gBaVy<fWY3W>0L5t~0aK$Sh~_h2T;ZEs6HX$AsfcNOWYJsW5PWO}
zRY$)07X+!Pzu&U(lH?_n9&h}S+EV#e&~U+X#D1Gcs{#iFe2vtzAi#2jpn~6S<Y8m5
z6sDCkPsF^hf8dyk#L5t08G1z)Xxq@a3Xf}(Z9L`Ub3dG_&W50Uc9pcQ4JgifCwMOR
zFH;*f)Yp$Z+I4~wu94s{mGb*t(;xwqUqEHM2ZufCY&A9XnKf|H7Gc|Y>7`QUF-ugc
z*dBp$2aIQeIR3Wq7Vyi@<3w*<yS9>%?A~ItLRuN8saDi^)#Ud%vg@bhdAsBR$GQ$(
zB|PhT4SOF=?d)*UKUb_AOZy^iU1-*tTfR=`#>wmou^_ujrCM{c_eCl??>#rTuL~;m
z7eA9?gcuS$3H@Bx(7R*)YXi{`ta#(b4jFGGShPPBQ0R9AQr6II%?UQfa^houCZF+3
zTmEIUuUgnfvRv;rD<vXL#-V*LR)?Fm8N&j>vJd%?lA>a`Li^H019-1A*A>;=54Of9
z2s{i{TC%qv5HBD$-6U7YF$T;+z4eTkRhOa9?tH@V4mc#cZ-z9O7!itSxoKYOqw~;(
z+UWC(Y-==8Eo`*A$l~#{A$V~4u>(tv!N%}1p6h^1@ZhleuNSXhhqc(^W4!eOVUfFm
zCpL>*(09V)o5T~muX+q^wxC^?*ygpSsF>eHhlWlY3&@5?4%`AIZTgVf@O?ILszrdt
ztytQi%IVqc+zcy0>`+u5pWqH(`HnnRY=KCSu<OTwnhZCfoBKr~epf0rtg=O1)OoI`
zQQ)=ALXnEk7Io%*5D5FEIvq!Sk4aN^4!<BHdHcCice|clyKaF=re_Upf{y_2LW0E%
zpsJ}T_lee0@Ls$`oYwSGp1vq-@S27vIyD_irf<p0ynaCu=J_TxRQ<|*Nn#6oWHJ9>
zDW3zV6PsF!c^@yY$sUy;zT#q!_$7OGdUImiv(z~i^oH#f`LJt-;+sY<r60v^)zcSU
zS-T|o_!FWVIY$BIf_CL=KFvBRs#5Qj)>&Pub_HF75UF(~+U#Svfw=cdYiX@)U?~0M
zz%-WhP%O@8On53bE+TIDvs-`PX((rL0_6bC3O(r9+vS1dbY6DqJ<1>?8R2wz3GKAz
zv`5R%&iXC(iWs!HYI&+g`{oA7Q1;T>t1jp0vwfYnH}q;XA!=l9H4f&WD{kAiAi+fG
z2&S;4a`dH_PM-b}C?0b+2{C}eLdOe*x;$<{f30HMDz8`i<1I<?ZiJVR4$%d4qFooh
z?va9XCTlTwP8IY3edpRwjiDX^VZDSaaTp|N@`l@RGX*jVUU{Sh=&ND8xDttE{xgSu
zwKm8YD}E1M%QDN2^Q?^(PSDgRZj27%mKMqv!izG7(g68rOklN#D7CNX-uWm)RtK;`
zwbQceC|x`}AnmNYuAw6F%ekEGceIev&Zd1-T6%gmX~<>S1IZn<0nvg!k3Z`_h|8<g
z1%#sn0ZoiEY$oJT7PBRGqr5@>+C5L`zEfxNcoJrYV0&H#QU5s7VJpczd~NPU(cQKi
zD{r`X6L8F$T9ht6Imxkr2}=C_SqtSEMMU;lg-*i|YYi;M1`vU3?PutOC>NWxvQw{K
z1_T;{V1iEM@Sq`a0<<G1U01fC_Q_F%5wqy@J&^<x!7UpW!R)hRS!!#5&-<ZrzSJBH
zqajVf(-d@$1%G<1&(RWRf}LV08#H&2@FC2YA38?o+TK-gMG42b^RXeJZ0UIu-Z?v5
z(+*TT%&zOW^V?17@ouwC4LD^Ft-MhBMfLvRthk|}z*n#4`V0Lvc{nSkj&=nLglKp@
zFH6HoxAG?y+yvRk76Nm_3b6e&hSYs-=^`!PJ<i7i_sru@mZ4vTp1o#RzWhp#|3+ZA
z6fm;T^~!nd(H$ck!KDu%JrDT@sXQt^ZqIK8OvQO9$F)3x0A2g)2l`wh-&*pJUt4z-
zj*<+C>HMugw_u6TW#B0z+1D}fO;$z*Bo@&Jfa^mcYZmfKwEoj4!Y^1{_7n*!k(0oU
zeFJ5$D9OfuHi7Sqrtpf?2deFaGxSWveFX0HKdCdL2HR4E;X8&La$1_=+}xRfomC+2
zG{s&sA(SF%r%}hvd+`2SMRqrnW7_b}_gC~e)0x+hPoEx^2g1>j<=_ctTxlOTRV)^O
z^bGjH&~Sc;7qYw&dXtJBsA3LC+bBfUse+kJgBorI9fjinJgv62&rIG~<HJhVNNSj%
z#-78e|GnrZCnWoljsb^zIaDmu9ihJeQjPbJiYve7wm4BxU#G(t&O7SuV?!DsuK`;R
zAbIQIvPLb+IM4i>UoC?H^Gk+K9nd0SYHDi#OIF2M=ct}3Amk`YiW~bR5XM=k;4b$v
zQcOB{Yy>#Qws~h-TG|$AN5`TpLFAG%$V!2Wh4~q4G`R|rp(bhI)nRcuSakmOEBgPL
z{nY>k!E!mb%NcNbfUosEFg6C>J+(|tYM-;tOpMa6G5u4i9}3MvVva)Rv;i?26v{CW
z=*<%)$Z7LKOQ-<O11QO`eYRQ!A!SgK-z`=ILDz;%-;*?Tj0^|LSDh)S0gtg)p+~7Q
z1M3VvQ{+!s!11l?!cX;oaq;d5Ie=et2a=ns+cza8<qzvRPfbHJ3Hyz-uC8vzFBHOc
z6RaCUv-glHned@U!P!1;-`d-epbYv1gQZtV7fA{SNJ=AO`Z&KL!@Sm2&8D+^1qz~f
zKvtl@SUvAdA5c%jqq}d=A=wHV>h>8&0VslE*<M8`^4Sk+^0@>=BSkFJ=gmAU#1JT8
zGca96#e+(;m&4%rxIc@ZV$FOm0~3@XEEcZsgh)d0O;q!ZjdyJN@fTF6$e)5p!lllx
zupfjOYp3av!)7JbhGri-0}ZsBS9(cqNl8gT-61#N@KF5Q%r0VqlI#o3CW2`5rGHU+
z=m|Ncb3jD!3m}u53O7<W38KYlc<`}tv3zHtC8%;|wIv$5o>*0U6=Q0Ln~u~)fG)sh
zu%tV(|BrCwP=oeXD+J#*{WFg8_UCknz)!1-Ogq%u%k%ClPEv7Jx@<aBh-SlS+zWJ|
z!?NDHG0kWEq5CYw+>497yJm&=rYcro6wiI*$A)G<M>@UkzdrSt+>Y6=1VBl;A~T1)
z{{M92`F|t&`ETsF`ch+l7Dm?=@f3u=|2LYE&J#i1LL_odJdlI`NRIqxQj~(XyNru>
Sw>7+jl9N%sl`DP!$$tSSuJy+N

literal 0
HcmV?d00001

diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 04b27adb51..8a3f518eca 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
-providers.md: 2ae1093699d8eb26171a2403db155113d84e437e
-providers.zh.md: 6ce513c659140ed18716bd5c8f75c428ad981f2b
+providers.md: c555e62d5343ccc758c0c6e699d30ffec229f2df
+providers.zh.md: 6c4154c86db3d95c6b083519533954fc4cc90e45
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index 2ae1093699..c555e62d53 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -17,12 +17,16 @@ Adding a provider therefore rarely means editing `cordis.yml` — writing settin
 
 Start `pnpm run dsh web` and open **Settings → Models**.
 
+![The Models page: the DeepSeek card, with Add provider and Add a custom provider below it](providers-models-page.png)
+
 **Give DeepSeek its key.** The DeepSeek card carries one API-key field; fill it in, save, and the provider is ready.
 
 **Add a provider from the installed catalog.** Choose **Add provider**, pick one of pi-ai's catalog providers (anthropic, openai, and so on), and enter that provider's API key. The endpoint, protocol, and model catalog all come from the catalog; the key is the only thing you owe.
 
 **Add a custom provider.** Choose **Add a custom provider** for a route the catalog does not ship — a company gateway, a self-hosted server, or a provider newer than the installed catalog. It asks for a Provider ID (the lowercase identifier that names the route in requests and as its credential), a base URL, a protocol, and at least one model.
 
+![The custom provider form: Provider ID, display name, base URL, API protocol, and API key](providers-custom-form.png)
+
 **Let the endpoint report its models.** Expand **Model catalog** and choose **Fetch available models**: the interrogation asks the endpoint **the form currently shows** — including a base URL edited but not yet saved and a key typed but not yet stored — and offers what it reports as candidates to pick from. A route the installed catalog describes is answered from that catalog with no network call. Adopting a candidate only writes rows into the draft; nothing is stored until you save.
 
 Keys are write-only: the page only ever holds a redacted descriptor, never the literal secret. A key you enter is stored in `$DSH_HOME/.env`, and the profile records only the variable name that references it.
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index 6ce513c659..6c4154c86d 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -17,12 +17,16 @@ Harness 出厂就带 DeepSeek，同时挂着一个通用的多提供方适配器
 
 启动 `pnpm run dsh web`，打开**设置 → 模型**。
 
+![模型页：DeepSeek 卡片，以及添加提供方与添加自定义提供方两个入口](providers-models-page.zh.png)
+
 **填 DeepSeek 的密钥。** DeepSeek 卡片上只有一个 API 密钥输入框，填好保存即可开始用。
 
 **添加内置目录里的提供方。** 点**添加提供方**，从 pi-ai 内置目录中选一个（anthropic、openai 等），填入该提供方的 API 密钥。端点、协议和模型目录都由内置目录提供，你只需要给密钥。
 
 **添加自定义提供方。** 点**添加自定义提供方**，用于内置目录没有的路由——公司网关、自建服务，或比内置目录更新的提供方。需要填 Provider ID（请求里点名它、也作为凭据名的小写标识）、API 地址、协议，以及至少一个模型。
 
+![自定义提供方表单：Provider ID、显示名称、API 地址、API 协议、API 密钥](providers-custom-form.zh.png)
+
 **让端点自己报模型。** 展开**模型目录**后点**获取可用模型**，会按你**当前表单里**的地址与密钥去问端点（地址改了但没保存、密钥刚输入还没存下，都算数），把它报告的模型列成候选让你勾选。内置目录里的路由直接由目录作答，不联网。采纳只是把行写进草稿，最终还是你点保存才落盘。
 
 密钥是只写的：页面拿到的永远是脱敏描述符，不是明文。写入的密钥存进 `$DSH_HOME/.env`，profile 里只记录引用它的变量名。

From 2426be893a7200bcd3d508ab30704d370a8c61c2 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 20:21:17 +0800
Subject: [PATCH 069/516] fix(scripts): let the documentation site carry its
 own images
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An image the manifest does not publish was rewritten to a raw.githubusercontent
URL, which serves a private repository to nobody: raw answers 404 unauthenticated,
and a github.com session does not authenticate it. Every image on the site was
broken for every reader, and no gate could say so — link checking asks whether
the file exists in the repository, not whether a site reader can fetch it.

The projector now copies a referenced image into the generated tree beside the
page and points the reference at it, so Vite bundles it like any other site
asset and repository visibility cannot reach the published page. The copy lands
beside the page so one relative URL is right from both locale trees and a page's
assets leave with the page; two sources projecting onto one path throw rather
than letting the last copy win.

Canonical Markdown keeps writing ordinary repository-relative paths, so the same
file still renders when read in the repository.

The guide this was found through is renamed to its subject: 配置模型.
---
 ...8-06-doc-site-carries-its-images.i18n.yaml |  6 +++
 .../2026-08-06-doc-site-carries-its-images.md | 39 ++++++++++++++++++
 ...26-08-06-doc-site-carries-its-images.zh.md | 39 ++++++++++++++++++
 docs/user/guide/providers.i18n.yaml           |  4 +-
 docs/user/guide/providers.md                  |  2 +-
 docs/user/guide/providers.zh.md               |  2 +-
 docs/user/guide/quickstart.i18n.yaml          |  4 +-
 docs/user/guide/quickstart.md                 |  2 +-
 docs/user/guide/quickstart.zh.md              |  2 +-
 scripts/project-doc-site.spec.ts              | 35 +++++++++++++++-
 scripts/project-doc-site.ts                   | 41 ++++++++++++++++---
 website/docs.ts                               |  2 +-
 12 files changed, 163 insertions(+), 15 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
 create mode 100644 .agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md

diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
new file mode 100644
index 0000000000..75018c8374
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.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/process/2026-08-06-doc-site-carries-its-images.md
+2026-08-06-doc-site-carries-its-images.md: 21593c2cadb6b2aaf52350ab61156ad892bc4163
+2026-08-06-doc-site-carries-its-images.zh.md: 54aee878a9d0f16d1fe3b219da7b248fb5148fa3
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
new file mode 100644
index 0000000000..21593c2cad
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
@@ -0,0 +1,39 @@
+# Agent Note: The documentation site carries its own images
+
+Status: implemented
+
+English | [中文](2026-08-06-doc-site-carries-its-images.zh.md)
+
+## Problem
+
+`scripts/project-doc-site.ts` rewrote every repository-relative target that the publication manifest does not publish into a GitHub URL, and for an image that meant `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`. Nothing in the site build copies files: `srcDir` is the disposable `.generated` tree, VitePress sets no `publicDir` (its default, `<srcDir>/public`, is inside the tree the projector deletes on every run), and only Markdown is written there.
+
+That works only for a public repository. This one is private, and `raw.githubusercontent.com` answers 404 to an unauthenticated request — a browser session on github.com does not authenticate it either, since GitHub's own UI serves private blobs through separately signed URLs. Every image on the site was therefore broken for every reader, and no gate said so: `verify-md-links` and the projector check that the target file *exists in the repository*, which is a different question from whether a site reader can fetch it.
+
+## Decision
+
+`rewriteMarkdown` takes an optional `placeImage(absPath): string`. When a page references an image the manifest does not publish as a page, the projector copies that file into the generated tree beside the page and rewrites the reference to `./<basename>`; Vite then bundles it like any other site asset. Nothing about repository visibility can reach the published page.
+
+The copy lands beside the page rather than in a shared asset directory. Each locale's route tree gets its own copy, so one relative URL is correct from both `guide/` and `en/guide/` without computing per-locale prefixes, and a page's assets are removed with the page when the manifest drops it. Two sources that would project onto one path throw, in the same spirit as the existing duplicate-route check, rather than letting whichever copied last win.
+
+`placeImage` is optional because `rewriteMarkdown` is also called directly by its spec, where no generated tree exists. Without it the old GitHub-raw behavior stands, which keeps that seam honest: the fallback is still the correct answer for a consumer that only rewrites text.
+
+Canonical Markdown keeps writing ordinary repository-relative image paths, so the same file renders on GitHub and on the site. No document carries a site-absolute URL to satisfy VitePress.
+
+## Alternatives considered
+
+**Set `publicDir` outside `.generated` and reference site-absolute URLs.** Fewer moving parts in the projector, but every image reference would then be broken when the same Markdown is read in the repository, and canonical docs are read both ways.
+
+**Host images on the assets branch, as demo GIFs already are.** That branch exists to keep large binaries out of the main history, and its raw URLs have exactly the same visibility problem. It remains the right home for recordings; it does not solve this.
+
+**Wait for the repository to become public.** It would fix the symptom without making the site self-contained, and the site would silently depend on GitHub's availability and rate limits for every image.
+
+## Consequences
+
+Images in published documentation now work regardless of who is reading or whether the repository is public, and the site build has no runtime dependency on GitHub for them. The generated tree grows by one copy of each referenced image per locale — the four screenshots in the model-provider guide add roughly 270 KB per locale.
+
+Images referenced from *unpublished* documents are untouched: they still resolve to GitHub raw, and still fail for a private repository. Nothing consumes them today, and a document that is not on the site has no site build to carry its assets.
+
+## Testing
+
+`scripts/project-doc-site.spec.ts` covers the placer receiving the resolved absolute path and the returned URL landing in the Markdown, a published page link still resolving to its route when a placer is present, and the unchanged GitHub-raw fallback when no placer is supplied. `pnpm docs:check` builds the site with the model-provider guide's screenshots and fails on a missing source; the copied files and their `./<basename>` references were verified in `website/.generated` and in a running `docs:dev` (`naturalWidth > 0` in both locales).
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
new file mode 100644
index 0000000000..54aee878a9
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: 文档站点自带图片
+
+Status: implemented
+
+[English](2026-08-06-doc-site-carries-its-images.md) | 中文
+
+## Problem
+
+`scripts/project-doc-site.ts` 会把发布清单未收录的仓库相对目标一律改写成 GitHub 地址，对图片而言就是 `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`。站点构建不拷贝任何文件：`srcDir` 是用完即弃的 `.generated` 树，VitePress 没有设置 `publicDir`（其默认值 `<srcDir>/public` 恰好位于投影每次运行时删除的那棵树里），而写进去的只有 Markdown。
+
+这只对公开仓库成立。本仓库是私有的，而 `raw.githubusercontent.com` 对未认证请求一律回 404——github.com 上的登录会话也不能认证它，因为 GitHub 自家界面是用另一套单独签名的地址提供私有 blob 的。于是站点上的每一张图片对每一位读者都是坏的，却没有任何门禁能说出来：`verify-md-links` 与投影校验的是目标文件**在仓库里是否存在**，那与站点读者能否取到它是两个问题。
+
+## Decision
+
+`rewriteMarkdown` 新增可选的 `placeImage(absPath): string`。当页面引用了一张清单未作为页面发布的图片时，投影把该文件复制进生成树中该页面的旁边，并把引用改写为 `./<basename>`；随后 Vite 会像处理其他站点资源一样打包它。仓库可见性再也影响不到已发布页面。
+
+副本落在页面旁边，而不是某个共享资源目录。每个 locale 的路由树各持一份副本，因此同一个相对 URL 在 `guide/` 与 `en/guide/` 下都正确，无需按 locale 计算前缀；清单撤下某页时，它的资源也随之消失。两个来源若会投影到同一路径则抛错——与既有的重复路由检查同一个立场——而不是让最后拷贝的那个静默胜出。
+
+`placeImage` 之所以可选，是因为 `rewriteMarkdown` 也被它自己的 spec 直接调用，而那里并不存在生成树。不传它时保持原有的 GitHub raw 行为，这也让该接缝保持诚实：对只改写文本的消费方而言，这个回退仍是正确答案。
+
+正本 Markdown 照旧写普通的仓库相对图片路径，因此同一份文件在 GitHub 上和站点上都能正常显示。没有任何文档为了迁就 VitePress 而写站内绝对 URL。
+
+## Alternatives considered
+
+**把 `publicDir` 设到 `.generated` 之外，并使用站内绝对 URL。** 投影这边的活动部件更少，但同一份 Markdown 在仓库中阅读时，每一处图片引用都会是坏的，而正本文档是两种方式都要读的。
+
+**把图片放到 assets 分支，就像演示 GIF 那样。** 那个分支的存在是为了让大体积二进制不进主线历史，而它的 raw 地址有着完全相同的可见性问题。它仍然是录屏的正确归宿；但它解决不了这件事。
+
+**等仓库转为公开。** 那只是消除症状，不会让站点自给自足，而且每一张图片都会让站点隐式依赖 GitHub 的可用性与限流。
+
+## Consequences
+
+已发布文档中的图片，现在无论谁在阅读、无论仓库是否公开都能显示，站点构建也不再为图片依赖 GitHub 的运行时可达性。生成树会为每个 locale 各增加一份被引用图片的副本——配置模型指南里的四张截图，每个 locale 约 270 KB。
+
+**未发布**文档引用的图片不受影响：它们仍解析到 GitHub raw，对私有仓库仍然失败。今天没有任何消费方用到它们，而不在站点上的文档也没有站点构建可以承载其资源。
+
+## Testing
+
+`scripts/project-doc-site.spec.ts` 覆盖：placer 收到解析后的绝对路径且其返回的 URL 落进 Markdown、存在 placer 时已发布页面的链接仍解析到自己的路由、以及不传 placer 时不变的 GitHub raw 回退。`pnpm docs:check` 会带着配置模型指南的截图构建站点，并在来源缺失时失败；被拷贝的文件及其 `./<basename>` 引用已在 `website/.generated` 与运行中的 `docs:dev` 里核实（两个 locale 均 `naturalWidth > 0`）。
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 8a3f518eca..324bcfb5c3 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
-providers.md: c555e62d5343ccc758c0c6e699d30ffec229f2df
-providers.zh.md: 6c4154c86db3d95c6b083519533954fc4cc90e45
+providers.md: d96cab0fa09583d81d98863169819fdd78d636e7
+providers.zh.md: d413fec2f9d703e31e82e50fcbe83b24bd58ee39
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index c555e62d53..d96cab0fa0 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -1,4 +1,4 @@
-# Configure model providers
+# Configure models
 
 English | [中文](providers.zh.md)
 
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index 6c4154c86d..d413fec2f9 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -1,4 +1,4 @@
-# 配置模型提供方
+# 配置模型
 
 [English](providers.md) | 中文
 
diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml
index 74fd06f83d..257f4919cc 100644
--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.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 docs/user/guide/quickstart.md
-quickstart.md: 8a9ed716d9395448aadfb97d0935bd42ee06e6c1
-quickstart.zh.md: 3652b0453f870640b278ce6f1355e67e85983ffe
+quickstart.md: e81e0ff57384156ee2963d4788519d2384c362ea
+quickstart.zh.md: 9755da8bf078c817f9c2a00134360b5169c536bf
diff --git a/docs/user/guide/quickstart.md b/docs/user/guide/quickstart.md
index 8a9ed716d9..e81e0ff573 100644
--- a/docs/user/guide/quickstart.md
+++ b/docs/user/guide/quickstart.md
@@ -57,6 +57,6 @@ headless-agent uses the `@deepseek-ai/dsh-cli-demo` app. `dsh web` instead compo
 
 ## Next steps
 
-- [Model providers](./providers.md) — reach providers beyond DeepSeek, and custom gateways
+- [Configure models](./providers.md) — reach providers beyond DeepSeek, and custom gateways
 - [Configuration](./config.md) — understand the `cordis.yml` format
 - [Develop a plugin](../develop/basic/) — build your own tool or backend
diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md
index 3652b0453f..9755da8bf0 100644
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -57,6 +57,6 @@ headless-agent 使用 `@deepseek-ai/dsh-cli-demo` app。`dsh web` 则组合 [`ap
 
 ## 下一步
 
-- [配置模型提供方](./providers.md) — 接入 DeepSeek 之外的提供方与自定义网关
+- [配置模型](./providers.md) — 接入 DeepSeek 之外的提供方与自定义网关
 - [配置文件](./config.md) — 了解 `cordis.yml` 的格式
 - [开发插件](../develop/basic/) — 编写自己的 tool 或后端
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 185acf2db5..c6402d7fc8 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -93,7 +93,7 @@ describe('rewriteMarkdown', () => {
     })).toBe('[B](./reference-root/b.md)\n')
   })
 
-  it('uses raw GitHub content for unpublished images', () => {
+  it('uses raw GitHub content for unpublished images when nothing places them', () => {
     const { root, pages } = fixture()
     expect(rewriteMarkdown('![logo](../packages/logo.svg)\n', {
       locale: 'en',
@@ -105,6 +105,39 @@ describe('rewriteMarkdown', () => {
     })).toBe('![logo](https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/abc123/packages/logo.svg)\n')
   })
 
+  it('hands an image to the placer and uses the URL it returns', () => {
+    // A raw GitHub URL cannot serve a private repository, so the site build
+    // carries images itself; the placer is what puts them there.
+    const { root, pages } = fixture()
+    const placed: string[] = []
+    expect(rewriteMarkdown('![logo](../packages/logo.svg)\n', {
+      locale: 'en',
+      sourcePath: 'docs/a.md',
+      route: 'en/a.md',
+      pages,
+      repoRoot: root,
+      repositoryRef: 'abc123',
+      placeImage: (absPath) => {
+        placed.push(absPath.split('/').pop() ?? '')
+        return './logo.svg'
+      },
+    })).toBe('![logo](./logo.svg)\n')
+    expect(placed).toEqual(['logo.svg'])
+  })
+
+  it('leaves a published page link to the route even when a placer exists', () => {
+    const { root, pages } = fixture()
+    expect(rewriteMarkdown('[B](b.md)\n', {
+      locale: 'en',
+      sourcePath: 'docs/a.md',
+      route: 'en/a.md',
+      pages,
+      repoRoot: root,
+      repositoryRef: 'abc123',
+      placeImage: () => { throw new Error('a page link must not be placed as an asset') },
+    })).toBe('[B](./reference/b.md)\n')
+  })
+
   it('does not rewrite Markdown-looking text inside code fences', () => {
     const { root, pages } = fixture()
     const source = '```md\n[B](b.md)\n```\n'
diff --git a/scripts/project-doc-site.ts b/scripts/project-doc-site.ts
index 592bbcfdee..ef821bd00e 100644
--- a/scripts/project-doc-site.ts
+++ b/scripts/project-doc-site.ts
@@ -5,8 +5,8 @@
  * tier, while this adapter rewrites cross-source links for the public site.
  */
 
-import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, extname, posix, relative, resolve, sep } from 'node:path'
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, posix, relative, resolve, sep } from 'node:path'
 import { fromMarkdown } from 'mdast-util-from-markdown'
 import { gfmFromMarkdown } from 'mdast-util-gfm'
 import { gfm } from 'micromark-extension-gfm'
@@ -38,6 +38,15 @@ export interface RewriteMarkdownOptions {
   pages: DocsPage[]
   repoRoot: string
   repositoryRef: string
+  /**
+   * Place one referenced image beside the projected page and return the URL to
+   * reach it from that page. A GitHub raw URL cannot serve this repository —
+   * `raw.githubusercontent.com` answers 404 for a private one, and no reader of
+   * the site is authenticated to it — so an image travels into the generated
+   * tree and Vite bundles it like any other site asset. Omitted by callers that
+   * only rewrite text, which then leave images pointing at the repository.
+   */
+  placeImage?: (absPath: string) => string
 }
 
 function repoPath(absPath: string, repoRoot: string): string {
@@ -222,9 +231,11 @@ export function rewriteMarkdown(source: string, options: RewriteMarkdownOptions)
       ? options.locale === 'root' ? 'en' : 'root'
       : options.locale
     const page = published.get(targetPath)?.get(targetLocale)
-    const nextUrl = page === undefined
-      ? githubTarget(absPath, line, suffix, options.repositoryRef, options.repoRoot, node.type === 'image')
-      : routeTarget(options.route, page.route, suffix)
+    const nextUrl = page !== undefined
+      ? routeTarget(options.route, page.route, suffix)
+      : node.type === 'image' && options.placeImage !== undefined
+        ? options.placeImage(absPath)
+        : githubTarget(absPath, line, suffix, options.repositoryRef, options.repoRoot, node.type === 'image')
 
     const start = node.position?.start.offset
     const end = node.position?.end.offset
@@ -299,6 +310,8 @@ export function docsSourceFiles(): string[] {
 /** Rebuild the disposable VitePress source tree from the publication manifest. */
 export function projectDocs(): void {
   const routes = new Set<string>()
+  /** Projected asset path to the source it came from, for collision detection. */
+  const assets = new Map<string, string>()
   const repositoryRef = process.env.GITHUB_SHA ?? 'master'
   rmSync(generatedRoot, { recursive: true, force: true })
 
@@ -319,6 +332,24 @@ export function projectDocs(): void {
       pages: docsPages,
       repoRoot: root,
       repositoryRef,
+      placeImage: (absPath) => {
+        // Beside the page that references it, under its own basename: each
+        // locale's route tree gets its own copy, so one relative URL is correct
+        // from both. Two sources that would land on one name are a collision
+        // rather than a silent overwrite of whichever copied last.
+        const name = basename(absPath)
+        const target = resolve(dirname(output), name)
+        const claimed = assets.get(target)
+        if (claimed !== undefined && claimed !== absPath) {
+          throw new Error(
+            `project-doc-site: ${repoPath(absPath, root)} and ${repoPath(claimed, root)}`
+            + ` both project to ${relative(generatedRoot, target).split(sep).join('/')}.`,
+          )
+        }
+        assets.set(target, absPath)
+        copyFileSync(absPath, target)
+        return `./${name}`
+      },
     })
     writeFileSync(output, addProjectionFrontmatter(projectedPageContent(projected, page), page))
   }
diff --git a/website/docs.ts b/website/docs.ts
index 2b9c4654c4..7bc2225865 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -133,7 +133,7 @@ const homeAndGuide = pairedPages([
   {
     source: 'docs/user/guide/providers.md',
     route: 'guide/providers.md',
-    label: { root: '配置模型提供方', en: 'Model providers' },
+    label: { root: '配置模型', en: 'Configure models' },
     sidebar: { root: 'zh-guide', en: 'en-guide' },
     section: { root: '入门', en: 'Guide' },
     order: 3,

From 9ff7eb84f0c3c3ab28ca888db056fb703e2a3ea8 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 20:35:02 +0800
Subject: [PATCH 070/516] docs: propose API key format validation

---
 ...-08-06-api-key-format-validation.i18n.yaml |   6 ++
 .../2026-08-06-api-key-format-validation.md   | 101 ++++++++++++++++++
 ...2026-08-06-api-key-format-validation.zh.md | 101 ++++++++++++++++++
 3 files changed, 208 insertions(+)
 create mode 100644 .agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
 create mode 100644 .agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.md
 create mode 100644 .agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.zh.md

diff --git a/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
new file mode 100644
index 0000000000..f62a18e0eb
--- /dev/null
+++ b/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.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/proposed/bug-fix/2026-08-06-api-key-format-validation.md
+2026-08-06-api-key-format-validation.md: dc19baa8b697998df2892f0840a35a8232cc92de
+2026-08-06-api-key-format-validation.zh.md: 28073660b1d4868fecf5ce419726d6d997383392
diff --git a/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.md
new file mode 100644
index 0000000000..dc19baa8b6
--- /dev/null
+++ b/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.md
@@ -0,0 +1,101 @@
+# Agent Note: Validate API key format before it reaches an HTTP header
+
+Status: proposed
+
+English | [中文](2026-08-06-api-key-format-validation.zh.md)
+
+## Problem
+
+An API key holding characters no HTTP header value can carry is accepted by every configuration surface and fails only when a request is built, far from the field that caused it.
+
+Paste a key containing an emoji, CJK text, or a full-width punctuation mark into the web Models page and the save reports success. The first turn then fails with `Cannot convert argument to a ByteString because the character at index 7 has a value of 55357 which is greater than 255` — the index and code point are UTF-16 internals with no action attached, and they disclose the code point of one character of the key. `llm-deepseek` produces this because `fetch` builds the `Bearer` header inside the `try` at [adapter.ts](../../../../packages/llm/llm-deepseek/src/adapter.ts), whose `catch` labels every failure `TRANSPORT`; that label is in `DEFAULT_RETRYABLE_CODES`, so a permanent, deterministic fault is also retried three times.
+
+`llm-pi-ai` is worse on the same input. Its discovery probe builds the same header with a bare `fetch` in [discovery.ts](../../../../packages/llm/llm-pi-ai/src/discovery.ts) and wraps every failure as `could not reach <url>`, so a local key fault is reported as an unreachable network. The probe is reachable from the unsaved draft: `ProviderEditor` puts the typed `keyDraft` into its probe request, so the model-listing button sends an illegal key before anything is stored.
+
+Whitespace passes every check. `ProviderEditor` tests `keyDraft.length` and `resolveAdapterOptions` tests `config.apiKey.length`, so a key of three spaces stores and then authenticates as `Bearer` plus blanks. `llm-pi-ai` rejects an empty literal `apiKey` in `resolveProfiles`, but applies no check whatsoever to a credential- or environment-sourced key — which is the path the Models page writes, and therefore the path users actually take.
+
+Sources: deepseek-harness#1594 and #1595; dsh-external#247, #249, #266, and #210.
+
+## Proposal
+
+One rule defines a legal key: **after trimming, non-empty, and every character within `[\x21-\x7E]`** — printable ASCII, space excluded.
+
+This single predicate covers every input the sources list: empty, leading and trailing whitespace, interior whitespace, C0 control characters, emoji, CJK text, and full-width punctuation. It is also exactly the constraint that produced the ByteString failure, so the two issues close on one definition rather than on two coincidentally related fixes.
+
+A second, narrower rule catches a pasted environment line: reject input matching `^[A-Z][A-Z0-9_]*=` or wrapped in matching quotes. Restricting the prefix to upper-case keeps real keys clear of it — `sk-` forms break the identifier match at the hyphen.
+
+### Invariants belong at every layer; heuristics belong where the human is
+
+The charset rule is an invariant. A non-ASCII character *cannot* travel in a header value for any provider, so enforcing it in the browser, in each resolver, and on every credential read is consistent by construction rather than by agreement.
+
+The shape rule is a guess about how people paste, so it runs **only in the browser**. `llm-pi-ai` fronts OpenAI, Anthropic, and arbitrary hand-declared gateways whose key formats this repository does not own; a gateway issuing a key shaped like `TENANT1=abc` would, if the rule ran in the resolver, be locked out with no escape — the settings page would refuse it and a hand-written `.env` would be rejected on read. Confining the heuristic to the surface where the paste happens keeps the environment as the way through.
+
+### Absence is a configuration state, not a missing key
+
+"No API key" means three different things here, and only one of them is an error. The rule applies to a value that was *provided*; deciding whether one was provided at all stays with each caller.
+
+**Omitted.** A profile naming neither `apiKey` nor `apiKeyEnv` is authenticated by something other than a harness-held key. `routeAuth` in [provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) keeps the installed catalog provider's own auth precisely so provider-native ambient discovery survives, and `openai-codex` — shipped in that catalog — authenticates through OAuth and refuses an explicit key outright. `namesCredential` exists to carry this distinction. In `llm-deepseek`, an absent `apiKey` likewise falls through to `apiKeyEnv`. Omission is never validated.
+
+**A blank field in the web UI.** The key input opens empty even for a provider whose key is already stored — the `keyStored` copy reads "Configured — enter a new value to replace" — so blank means *keep what is stored*. `ProviderEditor` already skips `credentials.set` entirely when the draft is empty, and that stays a no-op: a blank field must never block submit, or editing a base URL would demand re-entering the key.
+
+**Provided, but empty or whitespace-only.** This is the one error, because the user expressed an intent to set a key and supplied nothing. `llm-pi-ai` already words it correctly in `resolveProfiles` — *has an empty apiKey; omit it to use ambient authentication* — and that shape, naming the legitimate alternative rather than just refusing, is what the other surfaces adopt.
+
+`normalizeApiKey` therefore takes `string`, never `string | undefined`.
+
+### Where the rule lives
+
+`normalizeApiKey` is a new module of the `dsh-llm` seam, beside [attribution.ts](../../../../packages/llm/llm/src/attribution.ts), which already owns shared header concerns. Both adapters depend on the seam and both need the rule, so it has two current consumers rather than a speculative one. It returns the trimmed value or a reason (`empty`, `illegalCharacters`).
+
+The client cannot import it: client packages reference only client packages, so `packages/client/ui-models` mirrors the predicate and owns the localized messages, exactly as `validateDeepSeekModels` mirrors the host's `catalogModel` schema today. Each side names the other in a comment.
+
+### What each surface does
+
+| Surface | Change |
+|---|---|
+| `dsh-llm` | Add `normalizeApiKey`; add `INVALID_CREDENTIAL`, deliberately outside `DEFAULT_RETRYABLE_CODES`. |
+| `llm-deepseek` `resolveAdapterOptions` | Normalize a present `apiKey`, throwing beside the existing beyond-schema bounds; use the trimmed value. An absent one still falls through to `apiKeyEnv`. Closes dsh-external#210. |
+| `llm-deepseek` `resolveApiKey` | Normalize what the credentials seam or environment returns; reject with `INVALID_CREDENTIAL` naming the Models page, never echoing the key. |
+| `llm-pi-ai` `resolveProfiles` | Widen the existing emptiness check to the shared rule, keeping its "omit it to use ambient authentication" wording. |
+| `llm-pi-ai` `resolveApiKey` | Normalize the credential and environment paths, which are unchecked today. A profile naming no credential still returns `undefined` untouched, so ambient and OAuth routes are unaffected. |
+| `llm-pi-ai` `discoverModels` | Normalize before building the header, so an illegal key stops reporting as an unreachable endpoint. A probe carrying no key stays unauthenticated as it is today. |
+| `ui-models` | Mirror the charset rule, add the shape heuristic, trim `keyDraft` before probe and `credentials.set`, and fix the `stringAt` emptiness test. A blank field remains a no-op that submits; a field holding only whitespace is a field-level failure, so typed input is never silently discarded. Gate submit and show the failure on the field, matching the existing `modelFailure` pattern. |
+
+`ProviderEditor` serves both the DeepSeek and pi-ai layouts, so one client change covers both providers.
+
+`credentials-local` is deliberately untouched. It stores credentials generally, and printable-ASCII is a constraint of HTTP headers rather than of credential storage; its existing refusal of values no dotenv style can represent stays as it is.
+
+## Alternatives considered
+
+**A `.pattern()` on the `apiKey` schema field.** Vendored schemastery supports it, and the pattern would serialize to the browser with the rest of the namespace schema — one rule, delivered rather than mirrored. It loses because a pattern cannot trim first: `cordis.yml` would then reject a padded key while `.env` tolerated one, and the resolver would disagree with the schema about the same string. Validating in `resolveAdapterOptions` keeps every surface trim-then-validate, and that function is already where this package re-judges bounds the schema cannot express.
+
+**A validation module shared by client and host.** Rejected by the source-plane layout: client packages reference only client packages plus `vendor/cordis` and `support/invariants`, and widening that to reach a host package would collide the two `Context` merges the split exists to keep apart. Mirroring a one-line predicate with a test on each side is the established shape here.
+
+**Sniffing the `TypeError` in the adapter's `catch`.** This would classify the ByteString failure after the fact, leaving the header construction itself unguarded. It depends on the wording of a Node error message, so it degrades silently across runtime versions, and it cannot help `llm-pi-ai`, whose header is built inside the pi-ai SDK. Refusing the key before handing it over works for both adapters and for the discovery probe.
+
+**Enforcing in `credentials-local.set`.** It would catch every writer at once, including a hand-edited file. It loses because that provider stores credentials of every kind, and a rule derived from HTTP header encoding does not belong to it.
+
+**Running the shape heuristic in the resolvers too.** Symmetric, and it would stop a pasted environment line written directly into `.env`. Rejected for the lockout described above: a false positive in a resolver leaves the user no working path, while a false positive in the browser leaves the environment open.
+
+**Probing the provider at save time to prove the key works.** It would close the complaint the sources actually open with — a save that reports success and fails at the first turn. Rejected as out of scope and, on today's code, unbuildable: `discoverModels` short-circuits to the installed catalog before any network call for exactly the providers pi-ai ships catalogs for, so it verifies nothing about the key, and the DeepSeek card has no probe at all. A verifier's value is distinguishing "key rejected" from "cannot reach", which is the distinction this note makes reliable; building it first would produce a verifier unable to tell its own outcomes apart. Comparable products also do not verify on save, so a blocking network call at save time would be an unexpected behavior rather than a missing one.
+
+## Acceptance criteria
+
+- The browser, both resolvers, and both credential reads accept and reject the same *provided* strings: whitespace-only, padded, interior-space, C0 control, emoji, CJK, and full-width inputs are refused; a printable-ASCII key is accepted, trimmed.
+- A profile naming no credential still resolves to no key, and a route authenticating through the installed provider's own ambient discovery or OAuth keeps working untouched.
+- A blank key field saves the rest of the card without writing a credential; a field holding only whitespace fails on the field instead of being silently dropped.
+- A rejected key names the API key field in the web UI and blocks submit; nothing is written to settings or credentials.
+- A key that reaches a resolver illegally fails as `INVALID_CREDENTIAL` with a message naming where to fix it, containing no part of the key, and is not retried.
+- `llm-pi-ai` discovery reports an illegal key as a key fault, not as an unreachable endpoint.
+- A legal key still travels the existing `credentials.set` path unchanged.
+
+## Risks
+
+The shape heuristic can refuse a real key. Upper-case-identifier-then-`=` and matched surrounding quotes are shapes no known provider issues, and the rule runs only in the browser, so a user who hits it can still set the credential through the environment. The residual cost is a confusing refusal for a key nobody has yet reported.
+
+Restricting to printable ASCII is stricter than the transport requires: a header value may carry `\x80`–`\xFF`. Admitting latin-1 would let `é` through to return an opaque 401 instead of a local, explained refusal, so the stricter rule is deliberate. A provider that issues latin-1 keys would need this rule widened.
+
+The charset predicate exists twice, once per source plane. The layout forbids sharing it, and the duplication gate may flag the pair; each side carries its own test and names its twin.
+
+The costliest way to get this wrong is to treat absence as invalidity. A rule applied to `undefined` would break every route authenticating through ambient discovery or OAuth — `openai-codex` cannot take a key at all — and a blank field that blocked submit would make editing any other setting demand re-entering the key. Both belong in the tests, not only in this note.
+
+Keys already stored by an earlier build are read through `resolveApiKey`, so an illegal stored value begins failing at resolution rather than at request time. That is the intent — the diagnosis improves — but it moves the failure earlier for anyone currently holding one.
diff --git a/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.zh.md
new file mode 100644
index 0000000000..28073660b1
--- /dev/null
+++ b/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -0,0 +1,101 @@
+# Agent Note: 在 API Key 进入 HTTP header 之前校验其格式
+
+Status: proposed
+
+[English](2026-08-06-api-key-format-validation.md) | 中文
+
+## Problem
+
+一个含有 HTTP header value 无法承载的字符的 API Key,会被每一层配置界面接受,直到构造请求时才失败——离引发它的那个字段已经很远。
+
+把含 emoji、中文或全角标点的 Key 粘进 Web 模型设置页,保存会报成功。第一轮对话随即失败于 `Cannot convert argument to a ByteString because the character at index 7 has a value of 55357 which is greater than 255`——其中的下标与码点是 UTF-16 内部细节,不附带任何可执行动作,却泄露了 Key 中某一个字符的码点。`llm-deepseek` 之所以产出这句,是因为 `fetch` 在 [adapter.ts](../../../../packages/llm/llm-deepseek/src/adapter.ts) 的 `try` 内部构造 `Bearer` header,而那个 `catch` 把一切失败都标为 `TRANSPORT`;该标签又在 `DEFAULT_RETRYABLE_CODES` 之中,于是一个永久且确定的故障还会被重试三次。
+
+同样的输入在 `llm-pi-ai` 上更糟。它的探测路径在 [discovery.ts](../../../../packages/llm/llm-pi-ai/src/discovery.ts) 里用裸 `fetch` 构造同一个 header,并把一切失败包装成 `could not reach <url>`,于是一个本地的 Key 故障被报成网络不可达。这条探测在保存之前就够得着:`ProviderEditor` 把用户输入的 `keyDraft` 直接放进探测请求,所以「获取模型列表」按钮会在任何东西落盘之前就把非法 Key 发出去。
+
+空白字符能通过每一道检查。`ProviderEditor` 判的是 `keyDraft.length`,`resolveAdapterOptions` 判的是 `config.apiKey.length`,于是三个空格构成的 Key 会被存下,随后以 `Bearer` 加若干空格去认证。`llm-pi-ai` 在 `resolveProfiles` 中拒绝空的字面量 `apiKey`,却对来自凭据或环境的 Key 完全不做检查——而那正是模型设置页写入的路径,也就是用户真正走的路径。
+
+来源:deepseek-harness#1594 与 #1595;dsh-external#247、#249、#266、#210。
+
+## Proposal
+
+一条规则定义什么是合法 Key:**trim 之后非空,且每个字符都落在 `[\x21-\x7E]`**——可打印 ASCII,不含空格。
+
+这一个断言覆盖了来源列出的全部输入:空值、首尾空白、中间空白、C0 控制字符、emoji、中文、全角标点。它同时正是造成 ByteString 失败的那条约束,所以两个 issue 收敛于同一个定义,而不是两个恰好相关的修复。
+
+第二条更窄的规则用于识别整行粘贴的环境变量:拒绝匹配 `^[A-Z][A-Z0-9_]*=` 或首尾成对引号的输入。把前缀限定为全大写可以让真实 Key 与之绝缘——`sk-` 这类形态会在连字符处中断标识符匹配。
+
+### 不变量属于每一层,启发式属于人所在的那一层
+
+字符集规则是不变量。非 ASCII 字符对任何 provider 都**不可能**在 header value 中传输,因此在浏览器、在各个 resolver、在每一次凭据读取上执行它,是结构上的一致而非约定上的一致。
+
+形状规则是对人如何粘贴的猜测,因此**只在浏览器中运行**。`llm-pi-ai` 前面挂着 OpenAI、Anthropic 以及任意手工声明的网关,本仓库并不掌握它们的 Key 格式;若这条规则运行在 resolver 中,一个签发形如 `TENANT1=abc` 的网关会让用户被彻底锁死、无路可走——设置页拒绝它,手写的 `.env` 在读取时同样被拒。把启发式限制在粘贴动作发生的那一层,环境变量便始终是那条出路。
+
+### 「没有 Key」是一种配置状态,不是缺失
+
+在这里,「没有 API Key」意味着三件完全不同的事,其中只有一件是错误。规则作用于**已提供**的值;至于究竟有没有提供,由各个调用方自行判断。
+
+**未指定。** 既不写 `apiKey` 也不写 `apiKeyEnv` 的 profile,是由 harness 所持有的 Key 之外的东西来鉴权的。[provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) 中的 `routeAuth` 保留内置 catalog provider 自身的鉴权,正是为了让 provider 原生的 ambient 发现得以存活;而该 catalog 附带的 `openai-codex` 通过 OAuth 鉴权,并会直接拒绝一个显式的 Key。`namesCredential` 的存在就是为了承载这一区分。在 `llm-deepseek` 中,缺省的 `apiKey` 同样会回落到 `apiKeyEnv`。未指定的情形永不参与校验。
+
+**Web UI 中留空的输入框。** 即便某个 provider 的 Key 已经存好,该输入框也是空着打开的——`keyStored` 的文案写的是「已配置——输入新值以替换」——所以留空意味着*保持已存储的值*。`ProviderEditor` 在草稿为空时本就完全跳过 `credentials.set`,这一点保持不变:留空绝不能拦截提交,否则改一个 base URL 都得重新输一遍 Key。
+
+**已提供,但为空或纯空白。** 这是唯一的错误,因为用户表达了设置 Key 的意图却什么都没给。`llm-pi-ai` 在 `resolveProfiles` 中的措辞本就是对的——*has an empty apiKey; omit it to use ambient authentication*——这种指明合法替代路径而非单纯拒绝的形态,正是其他界面要采用的。
+
+因此 `normalizeApiKey` 接受 `string`,而绝非 `string | undefined`。
+
+### 规则住在哪里
+
+`normalizeApiKey` 是 `dsh-llm` seam 的新模块,与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则,因此它拥有两个当前消费者而非一个预设消费者。它返回 trim 后的值,或一个原因(`empty`、`illegalCharacters`)。
+
+客户端无法引入它:client 包只 reference client 包,因此 `packages/client/ui-models` 镜像这个断言并持有本地化文案,正如今天 `validateDeepSeekModels` 镜像 host 侧的 `catalogModel` schema。两侧在注释中互相指名。
+
+### 各个界面各做什么
+
+| 界面 | 改动 |
+|---|---|
+| `dsh-llm` | 新增 `normalizeApiKey`;新增 `INVALID_CREDENTIAL`,刻意不进 `DEFAULT_RETRYABLE_CODES`。 |
+| `llm-deepseek` `resolveAdapterOptions` | 归一化已提供的 `apiKey`,与既有的超出 schema 的边界检查并排抛错;使用 trim 后的值。缺省的 `apiKey` 仍照旧回落到 `apiKeyEnv`。关闭 dsh-external#210。 |
+| `llm-deepseek` `resolveApiKey` | 归一化凭据 seam 或环境返回的值;以 `INVALID_CREDENTIAL` 拒绝,消息指明模型设置页,绝不回显 Key。 |
+| `llm-pi-ai` `resolveProfiles` | 把既有的空值检查扩展为这条共享规则,并保留其「omit it to use ambient authentication」的措辞。 |
+| `llm-pi-ai` `resolveApiKey` | 归一化今天完全未受检的凭据与环境路径。不指定任何凭据的 profile 仍原样返回 `undefined`,ambient 与 OAuth 路由不受影响。 |
+| `llm-pi-ai` `discoverModels` | 在构造 header 之前归一化,使非法 Key 不再被报成端点不可达。不带 Key 的探测照旧保持未鉴权。 |
+| `ui-models` | 镜像字符集规则,加入形状启发式,在探测与 `credentials.set` 之前 trim `keyDraft`,并修正 `stringAt` 的空值判断。留空的输入框仍是可以提交的空操作;只含空白的输入框则以字段级失败呈现,使已输入的内容绝不被静默丢弃。按既有 `modelFailure` 的模式拦截提交并在字段上呈现失败。 |
+
+`ProviderEditor` 同时服务 DeepSeek 与 pi-ai 两种布局,因此一处客户端改动覆盖两个 provider。
+
+`credentials-local` 刻意不动。它存储各类凭据,而可打印 ASCII 是 HTTP header 的约束而非凭据存储的约束;它既有的、拒绝任何 dotenv 样式都无法表示的值的行为保持原样。
+
+## Alternatives considered
+
+**在 `apiKey` schema 字段上加 `.pattern()`。** vendor 中的 schemastery 支持它,且该 pattern 会随命名空间 schema 一同序列化到浏览器——一条规则,投递而非镜像。它落败于 pattern 无法先行 trim:那样 `cordis.yml` 会拒绝带首尾空白的 Key 而 `.env` 却容忍,resolver 与 schema 会对同一个字符串给出分歧。在 `resolveAdapterOptions` 中校验可以让每一层都是 trim-then-validate,而该函数本就是本包重新裁定 schema 无法表达的边界之处。
+
+**由 client 与 host 共享一个校验模块。** 被 source plane 布局否决:client 包只 reference client 包外加 `vendor/cordis` 与 `support/invariants`,把它放宽到够得着 host 包会撞上这一分割本就要隔开的两份 `Context` 合并。在两侧各镜像一行断言并各配一份测试,是此处的既定形态。
+
+**在适配器的 `catch` 中嗅探 `TypeError`。** 这只是事后归类 ByteString 失败,header 构造本身仍无防护。它依赖 Node 错误消息的措辞,因而会随运行时版本静默失效;它也帮不到 `llm-pi-ai`——后者的 header 构造在 pi-ai SDK 内部。在交出 Key 之前就拒绝,则对两个适配器与探测路径同时有效。
+
+**在 `credentials-local.set` 中执行。** 它能一次性拦住所有写入方,包括手工编辑的文件。它落败于该 provider 存储各种类型的凭据,而一条源自 HTTP header 编码的规则并不属于它。
+
+**让形状启发式也在 resolver 中运行。** 更对称,且能拦住直接写进 `.env` 的整行环境变量。因上文所述的锁死风险而否决:resolver 中的一次误判会让用户无路可走,浏览器中的一次误判则仍留有环境变量这条路。
+
+**在保存时探测 provider 以证明 Key 可用。** 它能关掉来源真正开篇抱怨的那件事——保存报成功、第一轮才失败。因超出范围而否决,且在今天的代码上无法建成:对 pi-ai 恰好自带 catalog 的那些 provider,`discoverModels` 会在任何网络调用之前短路到内置 catalog,因而对 Key 什么都验证不了;而 DeepSeek 卡片根本没有探测。验证器的价值在于分清「Key 被拒」与「无法连通」,而这正是本 Agent Note 要让其变得可靠的区分;先建验证器只会得到一个分不清自身结果的验证器。同类产品也不在保存时验证,因此保存时的阻断式网络调用会是一个意外行为,而非一处缺失。
+
+## Acceptance criteria
+
+- 浏览器、两个 resolver 与两处凭据读取接受与拒绝同一组**已提供**的字符串:纯空白、带首尾空白、含中间空格、C0 控制字符、emoji、中文、全角输入均被拒绝;可打印 ASCII 的 Key 被接受并 trim。
+- 不指定任何凭据的 profile 仍解析为「没有 Key」,通过内置 provider 自身的 ambient 发现或 OAuth 鉴权的路由原样可用。
+- 留空的 Key 输入框可以保存卡片其余部分而不写入凭据;只含空白的输入框则以字段级失败呈现,而不是被静默丢弃。
+- 被拒绝的 Key 在 Web UI 中定位到 API Key 字段并拦截提交;settings 与凭据均不写入。
+- 非法抵达 resolver 的 Key 以 `INVALID_CREDENTIAL` 失败,消息指明修复位置、不含 Key 的任何片段,且不被重试。
+- `llm-pi-ai` 的探测把非法 Key 报为 Key 故障,而非端点不可达。
+- 合法 Key 仍沿既有 `credentials.set` 路径原样通过。
+
+## Risks
+
+形状启发式可能拒绝一个真实的 Key。全大写标识符接 `=`、以及首尾成对引号,都是已知 provider 不会签发的形态,且该规则只在浏览器中运行,因此撞上它的用户仍可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
+
+限定为可打印 ASCII 比传输本身的要求更严:header value 是可以承载 `\x80`–`\xFF` 的。放行 latin-1 会让 `é` 通过并换回一个语焉不详的 401,而不是一次本地的、有解释的拒绝,因此从严是刻意的。若某个 provider 签发 latin-1 的 Key,这条规则需要放宽。
+
+字符集断言存在两份,每个 source plane 一份。布局禁止共享它,重复检测门禁可能会标记这一对;两侧各自带测试并在注释中指名其孪生体。
+
+把这件事做错的最大代价,是把「未指定」当成「非法」。一条施加到 `undefined` 上的规则会打断每一条依赖 ambient 发现或 OAuth 鉴权的路由——`openai-codex` 根本无法接受 Key——而一个会拦截提交的空输入框,则会让改动任何其他设置都必须重新输入 Key。这两点都应落在测试里,而不只是写在本 Agent Note 中。
+
+早先版本已存下的 Key 会经 `resolveApiKey` 读取,因此一个非法的既存值将从解析时开始失败,而非到请求时才失败。这正是意图所在——诊断变好了——但对当前正持有这类值的人而言,失败点提前了。

From 5b842895a8749f17224263b361ad3696200944cc Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 20:43:50 +0800
Subject: [PATCH 071/516] feat(llm): define the legal API key shape in the seam

---
 packages/llm/llm/src/api-key.ts        | 41 +++++++++++++++
 packages/llm/llm/src/error.ts          |  9 ++++
 packages/llm/llm/src/index.ts          | 34 ++++++++++++-
 packages/llm/llm/tests/api-key.spec.ts | 70 ++++++++++++++++++++++++++
 4 files changed, 153 insertions(+), 1 deletion(-)
 create mode 100644 packages/llm/llm/src/api-key.ts
 create mode 100644 packages/llm/llm/tests/api-key.spec.ts

diff --git a/packages/llm/llm/src/api-key.ts b/packages/llm/llm/src/api-key.ts
new file mode 100644
index 0000000000..85d0b1ed60
--- /dev/null
+++ b/packages/llm/llm/src/api-key.ts
@@ -0,0 +1,41 @@
+/**
+ * The one definition of a well-formed provider API key, shared by every
+ * adapter that puts one in an HTTP header.
+ * @module @deepseek-ai/dsh-llm/api-key
+ */
+
+/**
+ * Characters an HTTP header value carries verbatim and every known provider
+ * key uses: printable ASCII, space excluded. A key outside this set cannot
+ * reach any provider — `fetch` refuses to build the header — so this is a
+ * transport invariant rather than one provider's policy. Latin-1 is excluded
+ * deliberately: a header could carry it, but no provider issues it, and
+ * admitting it trades a local explained refusal for an opaque 401.
+ */
+const LEGAL_API_KEY = /^[\x21-\x7E]+$/
+
+/** Why a supplied API key cannot be used. */
+export type ApiKeyRejection = 'empty' | 'illegalCharacters'
+
+/** The verdict on one supplied API key. */
+export type ApiKeyCheck =
+  | { readonly ok: true; readonly value: string }
+  | { readonly ok: false; readonly reason: ApiKeyRejection }
+
+/**
+ * Judge one *supplied* API key, trimming surrounding whitespace first.
+ *
+ * Trimming is silent because a padded key has one unambiguous reading; every
+ * other defect is reported. Absence is a configuration state this function
+ * never sees — a profile naming no credential authenticates through the
+ * provider's own ambient discovery or OAuth — so callers decide whether a
+ * value was supplied before asking.
+ * @param raw - the key exactly as configured, stored, or typed.
+ * @returns the trimmed key, or why it cannot be used.
+ */
+export function normalizeApiKey(raw: string): ApiKeyCheck {
+  const value = raw.trim()
+  if (value.length === 0) return { ok: false, reason: 'empty' }
+  if (!LEGAL_API_KEY.test(value)) return { ok: false, reason: 'illegalCharacters' }
+  return { ok: true, value }
+}
diff --git a/packages/llm/llm/src/error.ts b/packages/llm/llm/src/error.ts
index fbb8bccca5..9ff193f1f8 100644
--- a/packages/llm/llm/src/error.ts
+++ b/packages/llm/llm/src/error.ts
@@ -38,6 +38,15 @@ export const QUOTA_EXCEEDED_CODE = 'QUOTA'
  */
 export const EMPTY_RESPONSE_CODE = 'EMPTY_RESPONSE'
 
+/**
+ * Canonical provider-neutral code for a credential that was supplied but
+ * cannot be used — malformed rather than absent. Distinct from
+ * `MISSING_CREDENTIAL` because the fix differs: correct the stored value
+ * rather than supply one. Deliberately outside the default retryable set —
+ * a malformed credential fails identically on every attempt.
+ */
+export const INVALID_CREDENTIAL_CODE = 'INVALID_CREDENTIAL'
+
 /** Structured codes and plain phrases that explicitly name a context bound being exceeded. */
 const STRUCTURED_CONTEXT_OVERFLOW = new RegExp(
   String.raw`(?:^|[^a-z0-9])context[\s_-](?:length|window)[\s_-]`
diff --git a/packages/llm/llm/src/index.ts b/packages/llm/llm/src/index.ts
index 74ca171f64..287bfc2f34 100644
--- a/packages/llm/llm/src/index.ts
+++ b/packages/llm/llm/src/index.ts
@@ -25,13 +25,15 @@ import type { ResolvedRetryPolicy } from './retry-policy.ts'
 import type { ProviderRequestId } from './brand.ts'
 import { callConfigEquals, deepFreeze } from './call-config.ts'
 import type { LlmCallConfig, LlmCallConfigAdapterDefaults } from './call-config.ts'
-import { HarnessError } from './error.ts'
+import { HarnessError, INVALID_CREDENTIAL_CODE } from './error.ts'
 import { normalizeLlmFailure } from './adapter-failure.ts'
+import { normalizeApiKey } from './api-key.ts'
 
 export * from './attribution.ts'
 export * from './brand.ts'
 export * from './never.ts'
 export * from './error.ts'
+export * from './api-key.ts'
 export * from './types.ts'
 export * from './message.ts'
 export * from './retry-policy.ts'
@@ -122,6 +124,36 @@ export class LlmError extends HarnessError {
   }
 }
 
+/**
+ * Accept one supplied credential, or refuse it as unusable.
+ *
+ * A stored key arrives from the credentials seam, a `.env` line, or a shell
+ * export, all of which pick up surrounding whitespace, so trimming is silent.
+ * Anything else fails here rather than inside `fetch`, whose ByteString
+ * refusal names a UTF-16 code point instead of the setting to change. The key
+ * never enters the message: `ref` names where to fix it, and echoing any part
+ * of a secret into a log or a UI is the failure this diagnosis avoids.
+ *
+ * Lives beside {@link LlmError} rather than in `./api-key.ts` so the predicate
+ * module stays dependency-free; both adapters share this one diagnosis instead
+ * of keeping near-identical local copies.
+ * @param raw - the credential exactly as supplied.
+ * @param pkg - the refusing package name, prefixed to the diagnostic.
+ * @param ref - the credential reference the value resolved through.
+ * @returns the trimmed, usable key.
+ */
+export function assertUsableApiKey(raw: string, pkg: string, ref: string): string {
+  const checked = normalizeApiKey(raw)
+  if (checked.ok) return checked.value
+  throw new LlmError(
+    checked.reason === 'empty'
+      ? `${pkg}: the API key stored as ${ref} is blank; re-enter it on the web Models page`
+      : `${pkg}: the API key stored as ${ref} contains characters no HTTP header can carry;`
+        + ' re-enter it on the web Models page, pasting the raw key only',
+    INVALID_CREDENTIAL_CODE,
+  )
+}
+
 /** One model call whose config and adapter registration were resolved together. */
 export interface PreparedLlmCall {
   /** Detached, deep-frozen config with any adapter-owned default materialized. */
diff --git a/packages/llm/llm/tests/api-key.spec.ts b/packages/llm/llm/tests/api-key.spec.ts
new file mode 100644
index 0000000000..a04a103fb9
--- /dev/null
+++ b/packages/llm/llm/tests/api-key.spec.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import { assertUsableApiKey, INVALID_CREDENTIAL_CODE, normalizeApiKey } from '@deepseek-ai/dsh-llm'
+
+describe('normalizeApiKey', () => {
+  it('accepts a printable-ASCII key unchanged', () => {
+    expect(normalizeApiKey('sk-0123456789abcdef')).toEqual({ ok: true, value: 'sk-0123456789abcdef' })
+  })
+
+  it('trims surrounding whitespace before judging', () => {
+    expect(normalizeApiKey('  sk-abc\t\n')).toEqual({ ok: true, value: 'sk-abc' })
+  })
+
+  it.each([
+    ['an empty string', ''],
+    ['spaces only', '   '],
+    ['a tab only', '\t'],
+  ])('rejects %s as empty', (_label, raw) => {
+    expect(normalizeApiKey(raw)).toEqual({ ok: false, reason: 'empty' })
+  })
+
+  it.each([
+    ['an emoji', 'sk-\u{1F600}abc'],
+    ['CJK text', 'sk-你好'],
+    ['full-width punctuation', 'sk-abc，'],
+    ['an interior space', 'sk-abc def'],
+    ['a C0 control character', 'sk-abc\x01'],
+    ['a latin-1 character', 'sk-café'],
+  ])('rejects %s as illegal characters', (_label, raw) => {
+    expect(normalizeApiKey(raw)).toEqual({ ok: false, reason: 'illegalCharacters' })
+  })
+
+  it('accepts the printable-ASCII boundary characters', () => {
+    expect(normalizeApiKey('!~')).toEqual({ ok: true, value: '!~' })
+  })
+
+  it('publishes a code distinct from a missing credential', () => {
+    expect(INVALID_CREDENTIAL_CODE).toBe('INVALID_CREDENTIAL')
+  })
+})
+
+describe('assertUsableApiKey', () => {
+  it('returns the trimmed key when it is usable', () => {
+    expect(assertUsableApiKey('  sk-abc  ', 'llm-deepseek', 'DEEPSEEK_API_KEY')).toBe('sk-abc')
+  })
+
+  it('refuses a blank stored credential, naming the reference', () => {
+    expect(() => assertUsableApiKey('   ', 'llm-deepseek', 'DEEPSEEK_API_KEY'))
+      .toThrow(/llm-deepseek: the API key stored as DEEPSEEK_API_KEY is blank/)
+  })
+
+  it('refuses an unusable stored credential with the invalid-credential code', () => {
+    try {
+      assertUsableApiKey('sk-\u{1F600}', 'llm-pi-ai', 'ACME_API_KEY')
+      expect.fail('an illegal key must throw')
+    } catch (error) {
+      expect((error as { code: string }).code).toBe(INVALID_CREDENTIAL_CODE)
+      expect((error as Error).message).toContain('llm-pi-ai')
+      expect((error as Error).message).toContain('ACME_API_KEY')
+    }
+  })
+
+  it('never echoes the key it refuses', () => {
+    try {
+      assertUsableApiKey('sk-\u{1F600}supersecret', 'llm-deepseek', 'DEEPSEEK_API_KEY')
+      expect.fail('an illegal key must throw')
+    } catch (error) {
+      expect((error as Error).message).not.toContain('supersecret')
+    }
+  })
+})

From 88f5de57559d76fdcefd6d79621c466534c9996d Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 20:57:30 +0800
Subject: [PATCH 072/516] docs: regenerate cordis catalog and event graph for
 shifted index.ts lines

---
 docs/cordis-catalog/events.md   | 4 ++--
 docs/cordis-catalog/services.md | 2 +-
 docs/event-producer-consumer.md | 4 ++--
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 44e0727101..b8eae843cc 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -493,7 +493,7 @@ The provider topology changed: an adapter registered or unregistered routes, or
 'llm/adapters-updated'(): void
 ```
 
-Source: [`packages/llm/llm/src/index.ts:71`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
 
 ### `llm/stream` — waterfall
 
@@ -517,7 +517,7 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 
 Types: [GenerateOptions](../core-data-structures/core.md) · [LlmService](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:60`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
 
 ## `session/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 896c17fb56..6b30d80751 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -941,7 +941,7 @@ stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 
 Types: [AdapterRegistrationHandle](../core-data-structures/core.md) · [DirectoryRegistrationHandle](../core-data-structures/core.md) · [GenerateOptions](../core-data-structures/core.md) · [LlmAdapter](../core-data-structures/llm-streaming.md) · [LlmCallConfig](../core-data-structures/core.md) · [LlmConfigurableProvider](../core-data-structures/core.md) · [LlmDiscoveredModel](../core-data-structures/core.md) · [LlmModelDiscoveryRequest](../core-data-structures/core.md) · [LlmModelInfo](../core-data-structures/core.md) · [LlmProviderInfo](../core-data-structures/core.md) · [LlmResolvedModelInfo](../core-data-structures/core.md) · [PreparedLlmCall](../core-data-structures/llm-streaming.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:255`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:287`](../../packages/llm/llm/src/index.ts)
 
 ## `ctx.permission` — `PermissionService`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 3de02d1b4c..b2d8feaa1d 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -28,8 +28,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:141`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:71`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
-| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:60`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
+| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
+| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:73`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
 | `session/event` | `emit` | [`packages/core/session/src/index.ts:95`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |

From b6b57ceda3c4b1a71b8741361b538699e2bcd2f3 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 20:57:43 +0800
Subject: [PATCH 073/516] docs(llm): document the invalid-credential code

---
 packages/llm/llm/README.i18n.yaml | 4 ++--
 packages/llm/llm/README.md        | 5 +++++
 packages/llm/llm/README.zh.md     | 5 +++++
 3 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 5e4daa179b..efdb8ea511 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
-README.md: ca34ffdeaafdbe061e030c80997b7234ce36a1bd
-README.zh.md: 1f95d3cd641126e129f94fe31269454a1bcce972
+README.md: 618d5f9f7c69c3ff2b420ae3fec96604802bf1be
+README.zh.md: 4b99c477eae694d1315d90920e835fcfde3b571a
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index ca34ffdeaa..618d5f9f7c 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -63,6 +63,10 @@ Streaming is a raw chunk protocol (`block-start`, `text-delta`, `reasoning-delta
 
 Every product adapter sends application identity on provider HTTP requests. `attributionHeaders(identity?)` builds the standard `User-Agent`, defaulting to public `APP_IDENTITY`; white-label deployments may replace but not suppress it. Adapters verify the wire header directly or through their library hook. See [the attribution Agent Note](../../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md).
 
+### API key validation (`api-key.ts`)
+
+Every adapter that puts a credential in an HTTP header judges it the same way before use. `normalizeApiKey(raw)` trims surrounding whitespace, then accepts any non-empty printable-ASCII value (`/^[\x21-\x7E]+$/`, space excluded) or reports why not as an `ApiKeyRejection` (`'empty'` | `'illegalCharacters'`), both carried in the `ApiKeyCheck` result. Absence is never judged: a caller decides whether a value was supplied before asking, since a profile naming no credential authenticates through the provider's own ambient discovery or OAuth.
+
 ### Classes
 
 - `LlmAdapter` — abstract base class for provider adapters. The only required method is `stream()`.
@@ -73,6 +77,7 @@ Every product adapter sends application identity on provider HTTP requests. `att
 - `CONTEXT_WINDOW_EXCEEDED_CODE` — the provider-neutral code both DeepSeek adapters use when a request exceeds the model context window, regardless of thrown-HTTP versus in-band finish delivery. `isContextWindowExceededError(detail)` is their shared conservative classifier for OpenAI-compatible provider detail.
 - `QUOTA_EXCEEDED_CODE` — the non-transient provider-neutral code for exhausted account quota, balance, credits, budget, or usage limits. `isQuotaExceededError(detail)` keeps those failures distinct from request-rate limits.
 - `EMPTY_RESPONSE_CODE` — the provider-neutral code both adapters use for a degenerate provider completion: a terminal `stop` that carried no content blocks at all. Classified as an error finish (not a successful empty message) because the attempt produced nothing durable; `dsh-llm-retry` retries it by default.
+- `INVALID_CREDENTIAL_CODE` — the provider-neutral code for a credential that was supplied but cannot be used: malformed rather than absent, so the fix is to correct the stored value rather than supply one — the distinction from `MISSING_CREDENTIAL`. Deliberately excluded from the default retryable set, since a malformed credential fails identically on every attempt. `assertUsableApiKey(raw, pkg, ref)` throws `LlmError` with this code, the one shared diagnosis every adapter uses for an unusable stored credential.
 
 ### Real adapters
 
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 1f95d3cd64..4b99c477ea 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -63,6 +63,10 @@
 
 每个产品适配器都会在提供方 HTTP 请求上发送应用身份。`attributionHeaders(identity?)` 构建标准 `User-Agent`，默认为公开 `APP_IDENTITY`；白标部署可以替换它，但不能抑制它。适配器会直接验证 wire 标头，或通过自身库 hook 验证。详见 [归因 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
 
+### API 密钥校验（`api-key.ts`）
+
+每个要把凭据放进 HTTP 标头的适配器，使用前都以同一套规则校验它。`normalizeApiKey(raw)` 先去除首尾空白，再接受任意非空的可打印 ASCII 值（`/^[\x21-\x7E]+$/`，不含空格），否则以 `ApiKeyRejection`（`'empty'` | `'illegalCharacters'`）说明拒绝原因，二者一并包含在 `ApiKeyCheck` 结果中。缺失从不参与校验：调用方会在询问之前自行判断是否提供了值——未点名凭据的 profile 会转由提供方自身的环境发现或 OAuth 完成认证。
+
 ### 类
 
 - `LlmAdapter`：提供方适配器的抽象基类。唯一必需方法是 `stream()`。
@@ -73,6 +77,7 @@
 - `CONTEXT_WINDOW_EXCEEDED_CODE`：当请求超过模型上下文窗口时，无论通过 HTTP 异常抛出还是带内 finish 交付，两个 DeepSeek 适配器都使用的提供方无关 code。`isContextWindowExceededError(detail)` 是它们针对 OpenAI 兼容提供方详细信息的共享保守分类器。
 - `QUOTA_EXCEEDED_CODE`：帐户配额、余额、点数、预算或用量限制耗尽时使用的非短暂提供方无关 code。`isQuotaExceededError(detail)` 使这些失败与请求速率限制保持区分。
 - `EMPTY_RESPONSE_CODE`：两个适配器都使用的提供方无关 code，用于表示退化的提供方生成结果：一个未携带任何内容块的终止 `stop`。它会被分类为错误 finish（而非成功空消息），因为尝试未产生持久内容；`dsh-llm-retry` 默认重试它。
+- `INVALID_CREDENTIAL_CODE`：已提供但无法使用的凭据所用的提供方无关 code——格式错误而非缺失，修复方式是改正已存储的值而非补供一个，这正是它与 `MISSING_CREDENTIAL` 的区别。它被刻意排除在默认可重试集合之外：格式错误的凭据每次尝试都会以同样方式失败。`assertUsableApiKey(raw, pkg, ref)` 会以该 code 抛出 `LlmError`，是每个适配器判定已存储凭据不可用时共用的诊断。
 
 ### 真实适配器
 

From a48b84c001c885b2dc209bbcef2f6b87a03cc7c4 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 21:14:39 +0800
Subject: [PATCH 074/516] fix(scripts): only publish images the repository
 owns, and keep their suffix

Review found four real gaps in the image placement this PR introduced.

Link rewriting only needs a target to exist, but publication copies its bytes
onto the site: a reference reaching out of the tree through `../..` or a
symlink would put a build-machine file on a published page. Only a regular
file whose real path stays inside the repository is copied now, and anything
else fails the projection naming the page and the target.

A placed reference kept none of its `?query` or `#fragment`, which the GitHub
branch has always carried and which decides what an SVG view fragment or a
Vite query means. The suffix rides along again, and the file name is
percent-encoded because the destination is a Markdown inline target.

Page outputs and placed images now claim projected paths from one map, so the
"fail loud rather than overwrite" invariant covers a page and an image landing
on one path, not only two images. `docsSourceFiles()` reports placed images, so
replacing a screenshot re-projects under `docs:dev` instead of serving the
previous copy until something touches the page.

The guide said to set `agent-loop`'s `agents` to change the default model,
which does nothing for `dsh web`: that default is `api-gateway`'s, and the
shipped composition leaves `agents` empty. It also promised that a catalog
provider needs only an API key, which is false for Bedrock, Vertex, Azure, and
Codex. Both are corrected.

The projection note and the doc-site skill carried the superseded "a
repository image becomes a raw GitHub URL" rule; both now describe what ships.
---
 ...13-documentation-site-projection.i18n.yaml |   4 +-
 ...026-07-13-documentation-site-projection.md |   2 +-
 ...-07-13-documentation-site-projection.zh.md |   2 +-
 ...8-06-doc-site-carries-its-images.i18n.yaml |   4 +-
 .../2026-08-06-doc-site-carries-its-images.md |   8 +-
 ...26-08-06-doc-site-carries-its-images.zh.md |   8 +-
 .agents/skills/dsh-doc-site-sync/SKILL.md     |   1 +
 docs/user/guide/providers.i18n.yaml           |   4 +-
 docs/user/guide/providers.md                  |  17 +--
 docs/user/guide/providers.zh.md               |  17 +--
 scripts/project-doc-site.spec.ts              |  56 +++++++++-
 scripts/project-doc-site.ts                   | 105 ++++++++++++++----
 12 files changed, 178 insertions(+), 50 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml
index 74ded5f605..7fa4d3fbba 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.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 .agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
-2026-07-13-documentation-site-projection.md: 2452c9dfa53e05061446df2fe650f3b4d6428c01
-2026-07-13-documentation-site-projection.zh.md: 6f1c79ac502a04714cd77f680108dbff035b048c
+2026-07-13-documentation-site-projection.md: f19d9b309aa22821a75086dc07ee302097631ba0
+2026-07-13-documentation-site-projection.zh.md: cc5e94e709f0639fd35ad81165b199cc5c9effc0
diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
index 2452c9dfa5..f19d9b309a 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
@@ -18,7 +18,7 @@ Canonical Markdown remains in the repository tier that owns it. Product-facing g
 
 Locale home projections retain only the canonical YAML frontmatter. The repository-facing body can keep its H1 and bilingual source links, while the VitePress home theme owns the rendered hero and features and the site navigation owns locale switching.
 
-The projector parses Markdown links without reserializing the document. A link to another published source becomes a site-relative route; a link to an unpublished repository file becomes a GitHub source link; a repository image becomes a raw GitHub URL. Missing relative targets fail projection. Unit tests pin these transformations, and `docs:check` runs the projector tests plus a production VitePress build as part of `doc-sync` and the parallel documentation gates.
+The projector parses Markdown links without reserializing the document. A link to another published source becomes a site-relative route; a link to an unpublished repository file becomes a GitHub source link; a repository image is copied into the generated tree and referenced from there ([why](2026-08-06-doc-site-carries-its-images.md)). Missing relative targets fail projection. Unit tests pin these transformations, and `docs:check` runs the projector tests plus a production VitePress build as part of `doc-sync` and the parallel documentation gates.
 
 `website/AGENTS.md` is the only maintained Markdown file in the website subtree. The projector test enumerates tracked and unignored files and rejects any other website Markdown, so site-specific locale, route, API, or generated source copies cannot bypass the publication manifest.
 
diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
index 6f1c79ac50..cc5e94e709 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 各 locale 的首页投影只保留权威 YAML frontmatter。面向仓库的正文可以保留其 H1 和双语源文件链接，而 VitePress 首页主题负责渲染 hero 与功能区，网站导航负责切换 locale。
 
-投影器解析 Markdown 链接，但不会重新序列化文档。指向另一个已发布源文件的链接会变成站内相对路由；指向未发布仓库文件的链接会变成 GitHub 源文件链接；仓库图片会变成 GitHub raw URL。相对目标不存在时，投影会失败。单元测试会锁定这些转换行为，`docs:check` 则运行投影器测试和 VitePress 生产构建，并将二者纳入 `doc-sync` 和并行文档门禁。
+投影器解析 Markdown 链接，但不会重新序列化文档。指向另一个已发布源文件的链接会变成站内相对路由；指向未发布仓库文件的链接会变成 GitHub 源文件链接；仓库图片会被拷贝进生成树并从那里引用（[原因](2026-08-06-doc-site-carries-its-images.md)）。相对目标不存在时，投影会失败。单元测试会锁定这些转换行为，`docs:check` 则运行投影器测试和 VitePress 生产构建，并将二者纳入 `doc-sync` 和并行文档门禁。
 
 `website/AGENTS.md` 是网站子树中唯一维护的 Markdown 文件。投影器测试会枚举所有已跟踪文件和未被忽略的未跟踪文件，并拒绝网站中的任何其他 Markdown，因此网站专用的 locale、路由、API 或生成源文件副本无法绕过发布 manifest。
 
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
index 75018c8374..32b51699e2 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.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 .agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
-2026-08-06-doc-site-carries-its-images.md: 21593c2cadb6b2aaf52350ab61156ad892bc4163
-2026-08-06-doc-site-carries-its-images.zh.md: 54aee878a9d0f16d1fe3b219da7b248fb5148fa3
+2026-08-06-doc-site-carries-its-images.md: 9109808874579b79d85c2e22b0987110f41ddc42
+2026-08-06-doc-site-carries-its-images.zh.md: d601112e8870150c363d8533e85ef86e7f3f8ffc
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
index 21593c2cad..9109808874 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
@@ -14,7 +14,11 @@ That works only for a public repository. This one is private, and `raw.githubuse
 
 `rewriteMarkdown` takes an optional `placeImage(absPath): string`. When a page references an image the manifest does not publish as a page, the projector copies that file into the generated tree beside the page and rewrites the reference to `./<basename>`; Vite then bundles it like any other site asset. Nothing about repository visibility can reach the published page.
 
-The copy lands beside the page rather than in a shared asset directory. Each locale's route tree gets its own copy, so one relative URL is correct from both `guide/` and `en/guide/` without computing per-locale prefixes, and a page's assets are removed with the page when the manifest drops it. Two sources that would project onto one path throw, in the same spirit as the existing duplicate-route check, rather than letting whichever copied last win.
+The copy lands beside the page rather than in a shared asset directory. Each locale's route tree gets its own copy, so one relative URL is correct from both `guide/` and `en/guide/` without computing per-locale prefixes, and a page's assets are removed with the page when the manifest drops it. One map claims every projected path — pages and images alike — so a second source for one path throws, in the same spirit as the existing duplicate-route check, rather than letting whichever wrote last win.
+
+Only a regular file whose real path stays inside the repository is copied; anything else fails the projection naming the page and the target. Link rewriting needs to know a target *exists*, but publication copies its bytes onto the site, so a reference escaping the repository — through `../..` or a symlink out of the tree — would put a build-machine file on a published page. The reference's `?query` or `#fragment` rides along to the placed URL exactly as the GitHub branch has always carried it, and the file name is percent-encoded because the destination is a Markdown inline target.
+
+`docsSourceFiles()` reports the placed images alongside the Markdown, so the dev server's watcher re-projects when a screenshot is replaced instead of serving the previous copy until something touches the page.
 
 `placeImage` is optional because `rewriteMarkdown` is also called directly by its spec, where no generated tree exists. Without it the old GitHub-raw behavior stands, which keeps that seam honest: the fallback is still the correct answer for a consumer that only rewrites text.
 
@@ -36,4 +40,4 @@ Images referenced from *unpublished* documents are untouched: they still resolve
 
 ## Testing
 
-`scripts/project-doc-site.spec.ts` covers the placer receiving the resolved absolute path and the returned URL landing in the Markdown, a published page link still resolving to its route when a placer is present, and the unchanged GitHub-raw fallback when no placer is supplied. `pnpm docs:check` builds the site with the model-provider guide's screenshots and fails on a missing source; the copied files and their `./<basename>` references were verified in `website/.generated` and in a running `docs:dev` (`naturalWidth > 0` in both locales).
+`scripts/project-doc-site.spec.ts` covers the placer receiving the resolved absolute path and the returned URL landing in the Markdown, a placed reference keeping its fragment, a published page link still resolving to its route when a placer is present, and the unchanged GitHub-raw fallback when no placer is supplied. `publishableImage` is covered directly: a regular file inside the repository resolves, while a symlink whose target escapes it, a path outside it, and a directory are all refused. `pnpm docs:check` builds the site with the model-provider guide's screenshots and fails on a missing source; the copied files and their `./<basename>` references were verified in `website/.generated` and in a running `docs:dev` (`naturalWidth > 0` in both locales).
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
index 54aee878a9..d601112e88 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
@@ -14,7 +14,11 @@ Status: implemented
 
 `rewriteMarkdown` 新增可选的 `placeImage(absPath): string`。当页面引用了一张清单未作为页面发布的图片时，投影把该文件复制进生成树中该页面的旁边，并把引用改写为 `./<basename>`；随后 Vite 会像处理其他站点资源一样打包它。仓库可见性再也影响不到已发布页面。
 
-副本落在页面旁边，而不是某个共享资源目录。每个 locale 的路由树各持一份副本，因此同一个相对 URL 在 `guide/` 与 `en/guide/` 下都正确，无需按 locale 计算前缀；清单撤下某页时，它的资源也随之消失。两个来源若会投影到同一路径则抛错——与既有的重复路由检查同一个立场——而不是让最后拷贝的那个静默胜出。
+副本落在页面旁边，而不是某个共享资源目录。每个 locale 的路由树各持一份副本，因此同一个相对 URL 在 `guide/` 与 `en/guide/` 下都正确，无需按 locale 计算前缀；清单撤下某页时，它的资源也随之消失。一张表登记所有被投影的路径——页面与图片一视同仁——同一路径出现第二个来源就抛错，与既有的重复路由检查同一个立场，而不是让最后写入的那个静默胜出。
+
+只有真实路径位于仓库内的普通文件才会被拷贝，其余一律让投影失败并点名页面与目标。链接改写只需要知道目标**存在**，但发布是把它的字节拷上站点，因此一个逃出仓库的引用——经由 `../..` 或指向树外的符号链接——会把构建机上的文件放到已发布页面上。引用自带的 `?query` 或 `#fragment` 会随安置后的 URL 一同保留，与 GitHub 分支一贯的做法一致；文件名做百分号编码，因为目标位于 Markdown 内联目标的位置。
+
+`docsSourceFiles()` 会连同被安置的图片一起上报，于是替换截图时开发服务器的 watcher 会重新投影，而不是一直服务旧副本直到有人碰一下页面。
 
 `placeImage` 之所以可选，是因为 `rewriteMarkdown` 也被它自己的 spec 直接调用，而那里并不存在生成树。不传它时保持原有的 GitHub raw 行为，这也让该接缝保持诚实：对只改写文本的消费方而言，这个回退仍是正确答案。
 
@@ -36,4 +40,4 @@ Status: implemented
 
 ## Testing
 
-`scripts/project-doc-site.spec.ts` 覆盖：placer 收到解析后的绝对路径且其返回的 URL 落进 Markdown、存在 placer 时已发布页面的链接仍解析到自己的路由、以及不传 placer 时不变的 GitHub raw 回退。`pnpm docs:check` 会带着配置模型指南的截图构建站点，并在来源缺失时失败；被拷贝的文件及其 `./<basename>` 引用已在 `website/.generated` 与运行中的 `docs:dev` 里核实（两个 locale 均 `naturalWidth > 0`）。
+`scripts/project-doc-site.spec.ts` 覆盖：placer 收到解析后的绝对路径且其返回的 URL 落进 Markdown、被安置的引用保留其 fragment、存在 placer 时已发布页面的链接仍解析到自己的路由、以及不传 placer 时不变的 GitHub raw 回退。`publishableImage` 另有直接覆盖：仓库内的普通文件被接受，而目标逃出仓库的符号链接、仓库外的路径与目录一律拒绝。`pnpm docs:check` 会带着配置模型指南的截图构建站点，并在来源缺失时失败；被拷贝的文件及其 `./<basename>` 引用已在 `website/.generated` 与运行中的 `docs:dev` 里核实（两个 locale 均 `naturalWidth > 0`）。
diff --git a/.agents/skills/dsh-doc-site-sync/SKILL.md b/.agents/skills/dsh-doc-site-sync/SKILL.md
index 4d88d3f04f..3f93a6560a 100644
--- a/.agents/skills/dsh-doc-site-sync/SKILL.md
+++ b/.agents/skills/dsh-doc-site-sync/SKILL.md
@@ -46,6 +46,7 @@ Write normal repository-relative Markdown links in canonical docs. The projector
 
 - A target present in the manifest becomes a site-relative route.
 - An existing target outside the manifest becomes a GitHub source link, including supported line suffixes.
+- An image is the exception: its file is copied into the generated tree and referenced from there, so the site serves it regardless of repository visibility. It must be a regular file inside the repository.
 - External URLs, site-absolute URLs, email links, and fragment-only links remain unchanged.
 - A missing repository-relative target fails projection instead of silently producing a broken link.
 
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 324bcfb5c3..665eae8457 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
-providers.md: d96cab0fa09583d81d98863169819fdd78d636e7
-providers.zh.md: d413fec2f9d703e31e82e50fcbe83b24bd58ee39
+providers.md: 66b6cf25c61a252fbd10a85f8c79c246eeae8abe
+providers.zh.md: a2c33c90be971e09ab29e2355ca6a7ae6f947c39
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index d96cab0fa0..66b6cf25c6 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -23,6 +23,8 @@ Start `pnpm run dsh web` and open **Settings → Models**.
 
 **Add a provider from the installed catalog.** Choose **Add provider**, pick one of pi-ai's catalog providers (anthropic, openai, and so on), and enter that provider's API key. The endpoint, protocol, and model catalog all come from the catalog; the key is the only thing you owe.
 
+That holds for providers that authenticate with an API key. The catalog also carries Bedrock, Vertex, Azure, and Codex, which need AWS credentials and a region, an ADC project, an `api-version`, and OAuth respectively: filling in the key field alone will not make them work. Those authenticate through pi-ai's own environment discovery, with credentials prepared the way each one requires.
+
 **Add a custom provider.** Choose **Add a custom provider** for a route the catalog does not ship — a company gateway, a self-hosted server, or a provider newer than the installed catalog. It asks for a Provider ID (the lowercase identifier that names the route in requests and as its credential), a base URL, a protocol, and at least one model.
 
 ![The custom provider form: Provider ID, display name, base URL, API protocol, and API key](providers-custom-form.png)
@@ -93,18 +95,19 @@ References resolve from `$DSH_HOME/.env` — what the Models page's key fields w
 
 ## Point an agent at the new provider
 
-A configured route appears in the web model picker and can be switched at any time. To change the default, edit the `agent-loop` entry's `provider` and `model` in `cordis.yml`:
+A configured route appears in the web model picker and can be switched at any time, which is how most people use it.
+
+A new session's default model comes from the `api-gateway` entry (`@deepseek-ai/dsh-host-apiproxy`) and its `provider` and `model`, which ship as `deepseek-official` and `deepseek-v4-flash`. To change that default, override the entry in `$DSH_HOME/config.yaml`:
 
 ```yaml
-- id: agent-loop
-  name: '@deepseek-ai/dsh-agent-loop'
+- id: api-gateway
   config:
-    agents:
-      - id: main
-        provider: acme-gateway
-        model: acme-large
+    provider: acme-gateway
+    model: acme-large
 ```
 
+A patch replaces that entry's whole `config`, so write out every key it needs to keep. A composition you assemble yourself — headless, for instance — sets `agent-loop`'s `agents` instead.
+
 ## Troubleshooting
 
 - **`MISSING_CREDENTIAL`** — the variable the profile's `apiKeyEnv` names holds no value. Store the key once through the Models page, or export the variable.
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index d413fec2f9..a2c33c90be 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -23,6 +23,8 @@ Harness 出厂就带 DeepSeek，同时挂着一个通用的多提供方适配器
 
 **添加内置目录里的提供方。** 点**添加提供方**，从 pi-ai 内置目录中选一个（anthropic、openai 等），填入该提供方的 API 密钥。端点、协议和模型目录都由内置目录提供，你只需要给密钥。
 
+只对以 API 密钥认证的提供方成立。目录里也有 Bedrock、Vertex、Azure、Codex：它们分别需要 AWS 凭据与区域、ADC 项目配置、`api-version`、OAuth，只填密钥框不会让它们工作——这类提供方靠 pi-ai 自己的环境发现认证，凭据按各自的原生方式准备。
+
 **添加自定义提供方。** 点**添加自定义提供方**，用于内置目录没有的路由——公司网关、自建服务，或比内置目录更新的提供方。需要填 Provider ID（请求里点名它、也作为凭据名的小写标识）、API 地址、协议，以及至少一个模型。
 
 ![自定义提供方表单：Provider ID、显示名称、API 地址、API 协议、API 密钥](providers-custom-form.zh.png)
@@ -93,18 +95,19 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 ## 让 agent 用上新提供方
 
-配好的路由会出现在 Web 的模型选择器里，随时可切。要改默认值，就在 `cordis.yml` 里改 `agent-loop` 那条的 `provider` 与 `model`：
+配好的路由会出现在 Web 的模型选择器里，随时可切，这也是最常用的方式。
+
+新会话的默认模型来自 `api-gateway` 那条（`@deepseek-ai/dsh-host-apiproxy`）的 `provider` 与 `model`，出厂值是 `deepseek-official` 与 `deepseek-v4-flash`。要改默认值，就在 `$DSH_HOME/config.yaml` 里覆盖该条：
 
 ```yaml
-- id: agent-loop
-  name: '@deepseek-ai/dsh-agent-loop'
+- id: api-gateway
   config:
-    agents:
-      - id: main
-        provider: acme-gateway
-        model: acme-large
+    provider: acme-gateway
+    model: acme-large
 ```
 
+补丁会整体替换该条的 `config`，所以要把这条需要保留的键一并写出。自行组装的 `cordis.yml`（例如 headless）改的则是 `agent-loop` 的 `agents`。
+
 ## 排错
 
 - **`MISSING_CREDENTIAL`** — profile 里的 `apiKeyEnv` 指向的变量没有值。用模型页存一次密钥，或导出该环境变量。
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index c6402d7fc8..6770381526 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -1,12 +1,14 @@
 /** Tests for the documentation website projection adapter. */
 
 import { execFileSync } from 'node:child_process'
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { docsPages, type DocsPage } from '../website/docs.ts'
-import { addProjectionFrontmatter, projectedPageContent, rewriteMarkdown } from './project-doc-site.ts'
+import {
+  addProjectionFrontmatter, projectedPageContent, publishableImage, rewriteMarkdown,
+} from './project-doc-site.ts'
 
 const roots: string[] = []
 const repositoryRoot = resolve(import.meta.dirname, '..')
@@ -63,6 +65,32 @@ describe('website source layout', () => {
   })
 })
 
+describe('publishableImage', () => {
+  it('accepts a regular file inside the repository', () => {
+    const { root } = fixture()
+    const real = realpathSync(join(root, 'packages/logo.svg'))
+    expect(publishableImage(join(root, 'packages/logo.svg'), realpathSync(root))).toBe(real)
+  })
+
+  it('refuses a target whose real path escapes the repository', () => {
+    // Publication copies the bytes onto the site, so a reference reaching a
+    // build-machine file must not be treated as an image the repository owns.
+    const { root } = fixture()
+    const outside = mkdtempSync(join(tmpdir(), 'dsh-doc-site-outside-'))
+    roots.push(outside)
+    writeFileSync(join(outside, 'secret.png'), 'not really a png\n')
+    symlinkSync(join(outside, 'secret.png'), join(root, 'packages/linked.png'))
+
+    expect(publishableImage(join(root, 'packages/linked.png'), realpathSync(root))).toBeUndefined()
+    expect(publishableImage(join(outside, 'secret.png'), realpathSync(root))).toBeUndefined()
+  })
+
+  it('refuses a directory', () => {
+    const { root } = fixture()
+    expect(publishableImage(join(root, 'packages'), realpathSync(root))).toBeUndefined()
+  })
+})
+
 describe('rewriteMarkdown', () => {
   it('maps published pages and pins unpublished source links', () => {
     const { root, pages } = fixture()
@@ -107,7 +135,9 @@ describe('rewriteMarkdown', () => {
 
   it('hands an image to the placer and uses the URL it returns', () => {
     // A raw GitHub URL cannot serve a private repository, so the site build
-    // carries images itself; the placer is what puts them there.
+    // carries images itself; the placer is what puts them there. The stand-in
+    // derives its URL the way the real one does, so a placer that stopped
+    // returning the basename would fail here rather than pass on a constant.
     const { root, pages } = fixture()
     const placed: string[] = []
     expect(rewriteMarkdown('![logo](../packages/logo.svg)\n', {
@@ -118,13 +148,29 @@ describe('rewriteMarkdown', () => {
       repoRoot: root,
       repositoryRef: 'abc123',
       placeImage: (absPath) => {
-        placed.push(absPath.split('/').pop() ?? '')
-        return './logo.svg'
+        const name = absPath.split('/').pop() ?? ''
+        placed.push(name)
+        return `./${name}`
       },
     })).toBe('![logo](./logo.svg)\n')
     expect(placed).toEqual(['logo.svg'])
   })
 
+  it('keeps a placed image\u2019s query or fragment', () => {
+    // An SVG view fragment and a Vite query both change what the reference
+    // means, and the GitHub branch has always carried them.
+    const { root, pages } = fixture()
+    expect(rewriteMarkdown('![logo](../packages/logo.svg#view)\n', {
+      locale: 'en',
+      sourcePath: 'docs/a.md',
+      route: 'en/a.md',
+      pages,
+      repoRoot: root,
+      repositoryRef: 'abc123',
+      placeImage: absPath => `./${absPath.split('/').pop() ?? ''}`,
+    })).toBe('![logo](./logo.svg#view)\n')
+  })
+
   it('leaves a published page link to the route even when a placer exists', () => {
     const { root, pages } = fixture()
     expect(rewriteMarkdown('[B](b.md)\n', {
diff --git a/scripts/project-doc-site.ts b/scripts/project-doc-site.ts
index ef821bd00e..02a64b023a 100644
--- a/scripts/project-doc-site.ts
+++ b/scripts/project-doc-site.ts
@@ -5,7 +5,9 @@
  * tier, while this adapter rewrites cross-source links for the public site.
  */
 
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import {
+  copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync,
+} from 'node:fs'
 import { basename, dirname, extname, posix, relative, resolve, sep } from 'node:path'
 import { fromMarkdown } from 'mdast-util-from-markdown'
 import { gfmFromMarkdown } from 'mdast-util-gfm'
@@ -234,7 +236,9 @@ export function rewriteMarkdown(source: string, options: RewriteMarkdownOptions)
     const nextUrl = page !== undefined
       ? routeTarget(options.route, page.route, suffix)
       : node.type === 'image' && options.placeImage !== undefined
-        ? options.placeImage(absPath)
+        // The suffix rides along exactly as the GitHub branch keeps it: an SVG
+        // view fragment or a Vite query changes what the reference means.
+        ? `${options.placeImage(absPath)}${suffix}`
         : githubTarget(absPath, line, suffix, options.repositoryRef, options.repoRoot, node.type === 'image')
 
     const start = node.position?.start.offset
@@ -302,19 +306,78 @@ export function projectedPageContent(markdown: string, page: DocsPage): string {
   return markdown.slice(0, closing + closingDelimiter.length)
 }
 
-/** Canonical Markdown files watched by the local VitePress dev server. */
+/**
+ * The repository file one image reference resolves to, or `undefined` when the
+ * target is not a local file this build may publish.
+ * @param absPath - resolved image target.
+ * @param repoRoot - repository root every published image must stay inside.
+ * @returns the file's real path, or `undefined` when it must not be copied.
+ *
+ * Only a regular file whose real path stays inside the repository qualifies.
+ * Publication copies the bytes into the site, so a reference escaping the
+ * repository — `../../.ssh/id_rsa`, or a symlink pointing out of the tree —
+ * would put a build-machine file on the site; `existsSync` alone, which is all
+ * link resolution needs, does not answer that.
+ */
+export function publishableImage(absPath: string, repoRoot: string): string | undefined {
+  const real = realpathSync(absPath)
+  const inside = real === repoRoot || real.startsWith(`${repoRoot}${sep}`)
+  return inside && statSync(real).isFile() ? real : undefined
+}
+
+/** Every local image a published page references, resolved to its repository file. */
+function referencedImages(): string[] {
+  const found = new Set<string>()
+  for (const page of docsPages) {
+    const sourceAbs = resolve(root, page.source)
+    if (!existsSync(sourceAbs)) continue
+    rewriteMarkdown(readFileSync(sourceAbs, 'utf8'), {
+      sourcePath: page.source,
+      locale: page.locale,
+      route: page.route,
+      pages: docsPages,
+      repoRoot: root,
+      repositoryRef: 'master',
+      placeImage: (absPath) => {
+        const real = publishableImage(absPath, root)
+        if (real !== undefined) found.add(real)
+        return ''
+      },
+    })
+  }
+  return [...found]
+}
+
+/**
+ * Files watched by the local VitePress dev server: every canonical Markdown
+ * source, plus the images they publish. Without the images, replacing a
+ * screenshot leaves the previous copy in the generated tree until something
+ * touches the Markdown beside it.
+ */
 export function docsSourceFiles(): string[] {
-  return [...new Set(docsPages.map(page => resolve(root, page.source)))]
+  return [...new Set([...docsPages.map(page => resolve(root, page.source)), ...referencedImages()])]
 }
 
 /** Rebuild the disposable VitePress source tree from the publication manifest. */
 export function projectDocs(): void {
   const routes = new Set<string>()
-  /** Projected asset path to the source it came from, for collision detection. */
-  const assets = new Map<string, string>()
+  /** Projected path to the repository file that claimed it, pages and images alike. */
+  const claimed = new Map<string, string>()
   const repositoryRef = process.env.GITHUB_SHA ?? 'master'
   rmSync(generatedRoot, { recursive: true, force: true })
 
+  /** Reserve one projected path, refusing a second source for it. */
+  const claim = (target: string, sourceAbs: string): void => {
+    const holder = claimed.get(target)
+    if (holder !== undefined && holder !== sourceAbs) {
+      throw new Error(
+        `project-doc-site: ${repoPath(sourceAbs, root)} and ${repoPath(holder, root)}`
+        + ` both project to ${relative(generatedRoot, target).split(sep).join('/')}.`,
+      )
+    }
+    claimed.set(target, sourceAbs)
+  }
+
   for (const page of docsPages) {
     if (routes.has(page.route)) throw new Error(`project-doc-site: duplicate route ${JSON.stringify(page.route)}.`)
     routes.add(page.route)
@@ -323,6 +386,9 @@ export function projectDocs(): void {
       throw new Error(`project-doc-site: source ${JSON.stringify(page.source)} does not exist or is not a file.`)
     }
     const output = resolve(generatedRoot, page.route)
+    // Claimed before the images are placed: a page and an image landing on one
+    // path would otherwise overwrite each other in whichever order they ran.
+    claim(output, sourceAbs)
     mkdirSync(dirname(output), { recursive: true })
     const markdown = readFileSync(sourceAbs, 'utf8')
     const projected = rewriteMarkdown(markdown, {
@@ -333,22 +399,23 @@ export function projectDocs(): void {
       repoRoot: root,
       repositoryRef,
       placeImage: (absPath) => {
-        // Beside the page that references it, under its own basename: each
-        // locale's route tree gets its own copy, so one relative URL is correct
-        // from both. Two sources that would land on one name are a collision
-        // rather than a silent overwrite of whichever copied last.
-        const name = basename(absPath)
-        const target = resolve(dirname(output), name)
-        const claimed = assets.get(target)
-        if (claimed !== undefined && claimed !== absPath) {
+        const real = publishableImage(absPath, root)
+        if (real === undefined) {
           throw new Error(
-            `project-doc-site: ${repoPath(absPath, root)} and ${repoPath(claimed, root)}`
-            + ` both project to ${relative(generatedRoot, target).split(sep).join('/')}.`,
+            `project-doc-site: ${page.source} references image ${repoPath(absPath, root)},`
+            + ' which is not a regular file inside the repository.',
           )
         }
-        assets.set(target, absPath)
-        copyFileSync(absPath, target)
-        return `./${name}`
+        // Beside the page that references it, under its own basename: each
+        // locale's route tree gets its own copy, so one relative URL is correct
+        // from both.
+        const name = basename(real)
+        const target = resolve(dirname(output), name)
+        claim(target, real)
+        copyFileSync(real, target)
+        // Encoded because the destination is a Markdown inline target, where an
+        // unescaped space would end it early.
+        return `./${encodeURI(name)}`
       },
     })
     writeFileSync(output, addProjectionFrontmatter(projectedPageContent(projected, page), page))

From f00a44fd449f221e5548c1b040d9bc9264bafa44 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Thu, 6 Aug 2026 06:21:19 -0700
Subject: [PATCH 075/516] refactor(web): move the produced-files row into its
 own plugin package

ui-conversation now owns only the conversation.chat.turnTail hole; the row,
its derivation, and its copy live in @deepseek-ai/dsh-client-ui-deliverables,
composed in or out by one cordis.yml line.
---
 ...6-07-31-web-workspace-file-links.i18n.yaml |   4 +-
 .../2026-07-31-web-workspace-file-links.md    |   2 +-
 .../2026-07-31-web-workspace-file-links.zh.md |   2 +-
 apps/cli/config/web.cordis.yml                |   5 +
 apps/cli/package.json                         |   1 +
 docs/config-catalog.md                        |   1 +
 knip.json                                     |  10 +
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +-
 packages/client/ui-conversation/README.zh.md  |   2 +-
 .../ui-conversation/src/client/apply.ts       |   1 +
 .../src/client/chat/AssistantMarkdown.tsx     |  17 +-
 .../src/client/chat/ChatView.tsx              |  10 +-
 .../src/client/chat/Deliverables.tsx          |  53 -----
 .../src/client/chat/chat-flow.ts              |  77 --------
 .../src/client/contract/slots.ts              |  31 ++-
 .../ui-conversation/src/client/index.ts       |   2 +-
 .../ui-conversation/src/client/locales.ts     |   6 -
 .../ui-conversation/tests/chat-view.spec.tsx  |  93 +--------
 .../client/ui-deliverables/README.i18n.yaml   |   6 +
 packages/client/ui-deliverables/README.md     |  21 ++
 packages/client/ui-deliverables/README.zh.md  |  21 ++
 packages/client/ui-deliverables/package.json  |  65 +++++++
 .../src/client/ProducedFiles.module.css}      |   0
 .../src/client/ProducedFiles.tsx              |  61 ++++++
 .../ui-deliverables/src/client/index.ts       |  42 ++++
 .../ui-deliverables/src/client/locales.ts     |  21 ++
 .../src/client/turn-deliverables.ts           |  78 ++++++++
 .../ui-deliverables/src/css-modules.d.ts      |   6 +
 packages/client/ui-deliverables/src/index.ts  |   9 +
 .../client/ui-deliverables/src/invariant.ts   |  32 +++
 .../tests/produced-files.spec.tsx             | 183 ++++++++++++++++++
 packages/client/ui-deliverables/tsconfig.json |  30 +++
 .../client/ui-deliverables/tsdown.config.ts   |   3 +
 pnpm-lock.yaml                                |  34 ++++
 .../verify-package-readme-model-experience.ts |   1 +
 tsconfig.base.json                            |   1 +
 tsconfig.client.json                          |   1 +
 38 files changed, 685 insertions(+), 253 deletions(-)
 delete mode 100644 packages/client/ui-conversation/src/client/chat/Deliverables.tsx
 create mode 100644 packages/client/ui-deliverables/README.i18n.yaml
 create mode 100644 packages/client/ui-deliverables/README.md
 create mode 100644 packages/client/ui-deliverables/README.zh.md
 create mode 100644 packages/client/ui-deliverables/package.json
 rename packages/client/{ui-conversation/src/client/chat/Deliverables.module.css => ui-deliverables/src/client/ProducedFiles.module.css} (100%)
 create mode 100644 packages/client/ui-deliverables/src/client/ProducedFiles.tsx
 create mode 100644 packages/client/ui-deliverables/src/client/index.ts
 create mode 100644 packages/client/ui-deliverables/src/client/locales.ts
 create mode 100644 packages/client/ui-deliverables/src/client/turn-deliverables.ts
 create mode 100644 packages/client/ui-deliverables/src/css-modules.d.ts
 create mode 100644 packages/client/ui-deliverables/src/index.ts
 create mode 100644 packages/client/ui-deliverables/src/invariant.ts
 create mode 100644 packages/client/ui-deliverables/tests/produced-files.spec.tsx
 create mode 100644 packages/client/ui-deliverables/tsconfig.json
 create mode 100644 packages/client/ui-deliverables/tsdown.config.ts

diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index 2b75bc2eff..e38447bf37 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.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 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
-2026-07-31-web-workspace-file-links.md: da99426ecb5ca81dcc110bbd4d5c1218390ae4bd
-2026-07-31-web-workspace-file-links.zh.md: 91aa94c6fe253c64125eb31fd15973a5aaff1a8f
+2026-07-31-web-workspace-file-links.md: 5bac48286c0d9066154a649f418b2f9c2df36539
+2026-07-31-web-workspace-file-links.zh.md: 2b2802ad00bbf4eb84d7ad81bca3b4a0838092c9
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
index da99426ecb..5bac48286c 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
@@ -14,7 +14,7 @@ Two distinct defects sat behind that. The transcript never said what a turn had
 
 ## Decision
 
-**A finished turn ends with the files it produced.** `turnDeliverables` reads them off the mutation tools' own follow-along `locations` — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a turn's output is listed whether or not the closing message named it, and a new mutation tool joins by declaring what it does rather than by being added to a list. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row. The row renders under the closing assistant's body and above its IconActions, keyed to the seq `assistantActionsSeqs` already elects.
+**A finished turn ends with the files it produced.** The row is its own plugin, `@deepseek-ai/dsh-client-ui-deliverables`, registered into the `conversation.chat.turnTail` hole the chat view renders between a closing message's body and its IconActions — ui-conversation owns the hole and the owner currency (nodes, closing seq, `openFile`), the plugin owns every policy. `producedForClosing` reads the paths off the mutation tools' own follow-along `locations` — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a turn's output is listed whether or not the closing message named it, and a new mutation tool joins by declaring what it does rather than by being added to a list. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row. One cordis.yml line composes the surface in or out; the unregistered hole renders nothing.
 
 **The path link reads as a link.** Underlined at rest, not only on hover. This is the smaller half of the diff and the larger half of the fix.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index 91aa94c6fe..2b2802ad00 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决定
 
-**完成的一轮以它产出的文件收尾。** `turnDeliverables` 从改写工具自身的跟随文件 `locations` 中读出它们——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，这一轮的产出都会被列出；新的改写工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。该行渲染在收尾 assistant 正文之下、其 IconActions 之上，键控到 `assistantActionsSeqs` 早已选出的那个 seq。
+**完成的一轮以它产出的文件收尾。** 该行是独立插件 `@deepseek-ai/dsh-client-ui-deliverables`，注册进 chat 视图在收尾消息正文与其 IconActions 之间渲染的 `conversation.chat.turnTail` 空位——ui-conversation 拥有空位与 owner 通货（节点、收尾 seq、`openFile`），插件拥有全部策略。`producedForClosing` 从改写工具自身的跟随文件 `locations` 中读出路径——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，这一轮的产出都会被列出；新的改写工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。cordis.yml 中的一行即可把该交互面组合进来或去掉；未注册的空位什么也不渲染。
 
 **路径链接读得出是链接。** 静止状态下就带下划线，而不只在悬停时。这是本次改动中更小的那一半，却是修复中更大的那一半。
 
diff --git a/apps/cli/config/web.cordis.yml b/apps/cli/config/web.cordis.yml
index daf597916e..62731fd51e 100644
--- a/apps/cli/config/web.cordis.yml
+++ b/apps/cli/config/web.cordis.yml
@@ -141,6 +141,11 @@
     - id: ui-conversation
       name: '@deepseek-ai/dsh-client-ui-conversation'
 
+    # Turn tail: the produced-files row under each closing assistant message.
+    # Remove this entry to turn the surface off; the tail hole renders empty.
+    - id: ui-deliverables
+      name: '@deepseek-ai/dsh-client-ui-deliverables'
+
 
     - id: ui-workspace
       name: '@deepseek-ai/dsh-client-ui-workspace'
diff --git a/apps/cli/package.json b/apps/cli/package.json
index 4ba1da7e86..58b92bc41d 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -30,6 +30,7 @@
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-command": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-deliverables": "workspace:^",
     "@deepseek-ai/dsh-client-ui-goal": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
     "@deepseek-ai/dsh-client-ui-model": "workspace:^",
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 89f1529387..710022c11c 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2376,6 +2376,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-client-runtime` ([`packages/client/runtime/src/index.ts`](../packages/client/runtime/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-command` ([`packages/client/ui-command/src/index.ts`](../packages/client/ui-command/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-conversation` ([`packages/client/ui-conversation/src/index.ts`](../packages/client/ui-conversation/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-deliverables` ([`packages/client/ui-deliverables/src/index.ts`](../packages/client/ui-deliverables/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-goal` ([`packages/client/ui-goal/src/index.ts`](../packages/client/ui-goal/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-layout` ([`packages/client/ui-layout/src/index.ts`](../packages/client/ui-layout/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-model` ([`packages/client/ui-model/src/index.ts`](../packages/client/ui-model/src/index.ts))
diff --git a/knip.json b/knip.json
index dfb8058d7c..b16e085723 100644
--- a/knip.json
+++ b/knip.json
@@ -127,6 +127,16 @@
         "tests/**/*.tsx"
       ]
     },
+    "packages/client/ui-deliverables": {
+      "entry": [
+        "tests/**/*.spec.tsx"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "src/**/*.tsx",
+        "tests/**/*.tsx"
+      ]
+    },
     "packages/client/web-react": {
       "entry": [
         "tests/**/*.spec.tsx"
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index f1e7c35db7..7c0fd0e42a 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 674cbe7ddf6f2ddc64c337cbebb4ee553e1e3f96
-README.zh.md: d3e8475c7670c57575aa8eeecbf29646c6672c2f
+README.md: 8e31a41ad682dfa21d22c93673b17954a784dd4f
+README.zh.md: 05b3eeb3185166a1f16596a206ef4111a50e789d
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 674cbe7ddf..8e31a41ad6 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -50,7 +50,7 @@ The chat stats line takes its token accounting from the generic token-meter `tok
 
 `src/client/` is organized by domain. `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations and composed props, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` directories import contract files and never each other. `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components and the store factory stay internal and reach the page through apply's slot registrations.
 
-A finished turn ends with the files it produced. `chat-flow.ts`'s `turnDeliverables` reads them off the mutation tools' own follow-along `locations` — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a turn's output is listed whether or not the closing message named it, and a new mutation tool joins by declaring what it does rather than by being added to a list. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row. The row renders under the closing assistant's body and above its IconActions, keyed to the same seq `assistantActionsSeqs` elects. It shows six chips (basename, full path as the title) plus an explicit remainder count, and each chip opens through the same `openFile` the tool rows use.
+A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost.
 
 ## Model Experience
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index d3e8475c76..05b3eeb318 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -50,7 +50,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 `src/client/` 按领域组织。`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明与组合后的 props、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/` 目录只导入 contract 文件，彼此之间从不互相导入。`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件与 store factory 保持内部，经 apply 的 slot 注册抵达页面。
 
-完成的一轮以它产出的文件收尾。`chat-flow.ts` 的 `turnDeliverables` 从改写工具自身的跟随文件 `locations` 中读出它们——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，这一轮的产出都会被列出；新的改写工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。该行渲染在收尾 assistant 正文之下、其 IconActions 之上，键控到 `assistantActionsSeqs` 选出的同一个 seq。它展示六枚 chip（文本为文件名，完整路径作为 title），外加一个显式的剩余计数，每枚 chip 都经由工具行所用的同一个 `openFile` 打开。
+完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。
 
 ## 模型体验
 
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 6bc9068cfc..8eb78139c4 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -303,6 +303,7 @@ export function apply(ctx: Context): void {
     children: {
       'conversation.chat.toolview': { kind: 'keyed', scope: 'session' },
       'conversation.chat.commandview': { kind: 'keyed', scope: 'session' },
+      'conversation.chat.turnTail': { kind: 'list', scope: 'session' },
     },
     store: chatStore,
     inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ChatViewInjected => {
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index 77cd3316d8..d6b6504bd0 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -9,13 +9,12 @@
 // only when the node is also the completed turn's transcript tail. Think /
 // tool-head-only nodes stay chrome-free.
 
-import { memo, useMemo } from 'react'
+import { memo, useMemo, type ReactNode } from 'react'
 import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
 import {
   IconThinkOutline14, JsonBlock, MarkdownText,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
-import { Deliverables } from './Deliverables.tsx'
 import { MessageIconActions } from './MessageIconActions.tsx'
 import { ToolRow } from './ToolRow.tsx'
 import css from './AssistantMarkdown.module.css'
@@ -39,11 +38,9 @@ export interface AssistantMarkdownProps {
   seq?: number | undefined
   /** Fork the session through this finalized message's completed turn when eligible. */
   onFork?: ((seq: number) => void) | undefined
-  /** Files the closing turn produced, listed under the body; omitted for a
-   *  mid-turn assistant and for a turn that wrote nothing. */
-  produced?: readonly string[] | undefined
-  /** Opens one produced file; omitted wherever `produced` is. */
-  openFile?: ((path: string) => void) | undefined
+  /** Turn-tail content (the chat view's turnTail hole, rendered by the
+   *  owner); omitted for a mid-turn assistant. */
+  tail?: ReactNode | undefined
   /** The message is not the transcript tail of a completed turn. */
   forkUnavailable?: boolean | undefined
   /** The owning view's locale seat, passed down as a plain prop. */
@@ -92,7 +89,7 @@ function ThinkRow({ text, running, t }: { text: string; running: boolean; t: Ass
 }
 
 export const AssistantMarkdown = memo(function AssistantMarkdown({
-  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, produced, openFile, t,
+  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, tail, t,
 }: AssistantMarkdownProps) {
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
@@ -130,9 +127,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
         })}
         {interrupted && <span className={css.stopped}>{t('message.stopped')}</span>}
       </div>
-      {showActions && produced !== undefined && openFile !== undefined && (
-        <Deliverables paths={produced} openFile={openFile} t={t} />
-      )}
+      {showActions && tail}
       {showActions && (
         <MessageIconActions
           text={copyText(blocks)}
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index 725a7403e2..3e0015ed20 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -30,7 +30,7 @@ import type {
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
-import { assistantActionsSeqs, deriveChatFlow, messageBranchSeqs, runningTurnStartTime, turnDeliverables, type ChatFlowItem } from './chat-flow.ts'
+import { assistantActionsSeqs, deriveChatFlow, messageBranchSeqs, runningTurnStartTime, type ChatFlowItem } from './chat-flow.ts'
 import { AssistantMarkdown } from './AssistantMarkdown.tsx'
 import { GenericCommandCard } from './GenericCommandCard.tsx'
 import { GenericToolCard } from './GenericToolCard.tsx'
@@ -361,9 +361,6 @@ export function ChatView({
   // Only the last content assistant of each turn owns IconActions; mid-turn
   // text (before tools) omits `time` so AssistantMarkdown stays chrome-free.
   const actionSeqs = useMemo(() => assistantActionsSeqs(nodes), [nodes])
-  // Produced files per closing assistant: derived from the mutation tools'
-  // locations, so a turn's output is listed whether or not the model named it.
-  const produced = useMemo(() => turnDeliverables(nodes), [nodes])
   const branchSeqs = useMemo(() => messageBranchSeqs(nodes, turnEnds), [nodes, turnEnds])
   const runningTurnStart = useMemo(() => runningTurnStartTime(turnTimings), [turnTimings])
   const turnMetrics = useMemo(() => deriveTurnMetrics(nodes), [nodes])
@@ -621,8 +618,9 @@ export function ChatView({
           seq={node.seq}
           onFork={forkAt}
           forkUnavailable={!branchSeqs.has(node.seq)}
-          produced={produced.get(node.seq)}
-          openFile={openFile}
+          tail={actionSeqs.has(node.seq)
+            ? renderSlot('conversation.chat.turnTail', { nodes, seq: node.seq, openFile })
+            : undefined}
           t={t}
         />
       )
diff --git a/packages/client/ui-conversation/src/client/chat/Deliverables.tsx b/packages/client/ui-conversation/src/client/chat/Deliverables.tsx
deleted file mode 100644
index 7d62e23401..0000000000
--- a/packages/client/ui-conversation/src/client/chat/Deliverables.tsx
+++ /dev/null
@@ -1,53 +0,0 @@
-// Deliverables: the produced-file row a finished turn ends with. The paths come
-// from the mutation tools' follow-along locations (see turnDeliverables), never
-// from the closing prose, so the answer carries its own output whether or not
-// the model remembered to name it. Clicking one goes through the same openFile
-// the tool rows use — the Host's own opener, on the Host machine.
-
-import type { ChatViewSlotProps } from '../contract/slots.ts'
-import css from './Deliverables.module.css'
-
-/** Files past this stay counted but unlisted: a refactor turn must not bury the answer. */
-const SHOWN = 6
-
-/** Trailing path segment, the part that identifies the file at a glance. */
-function basename(path: string): string {
-  const at = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
-  return at === -1 ? path : path.slice(at + 1)
-}
-
-/**
- * Render one turn's produced files as openable chips.
- * @param props - the turn's paths (tool order, already deduped), the chat
- * view's file opener, and the owning view's locale seat.
- * @returns The row, or `null` when the turn produced nothing.
- */
-export function Deliverables({ paths, openFile, t }: {
-  paths: readonly string[]
-  openFile: (path: string) => void
-  t: ChatViewSlotProps['t']
-}) {
-  if (paths.length === 0) return null
-  const shown = paths.slice(0, SHOWN)
-  const hidden = paths.length - shown.length
-  return (
-    <div className={css.root}>
-      <span className={css.label}>{t('produced.label')}</span>
-      {shown.map(path => (
-        <button
-          key={path}
-          type="button"
-          className={css.file}
-          // The full path is the disambiguator when two turns produce files
-          // that share a basename; the chip itself stays short.
-          title={path}
-          aria-label={t('produced.open', { name: path })}
-          onClick={() => { openFile(path) }}
-        >
-          {basename(path)}
-        </button>
-      ))}
-      {hidden > 0 && <span className={css.more}>{t('produced.more', { count: String(hidden) })}</span>}
-    </div>
-  )
-}
diff --git a/packages/client/ui-conversation/src/client/chat/chat-flow.ts b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
index 7d5e5100f6..57d2ac1bb0 100644
--- a/packages/client/ui-conversation/src/client/chat/chat-flow.ts
+++ b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
@@ -32,21 +32,6 @@ function rendersNothing(node: ConversationNode): boolean {
       || ((b.kind === 'text' || b.kind === 'reasoning') && b.text.trim() === ''))
 }
 
-/**
- * Paths a call view reports having created or changed, by render intent rather
- * than tool name: a diff card, or a generic card whose kind is `edit` (the
- * shape `str_replace_editor`'s insert presents). Every other card produces
- * nothing to open — a read looked, a delete removed, a terminal ran.
- */
-function producedPaths(view: ToolResultNode['callView']): readonly string[] {
-  if (view === null) return []
-  if (view.card === 'diff') return (view.locations ?? []).map(location => location.path)
-  if (view.card === 'generic' && view.kind === 'edit') {
-    return (view.locations ?? []).map(location => location.path)
-  }
-  return []
-}
-
 /**
  * Seq set of assistants that own IconActions: the last content-text assistant
  * in each turn. Mid-turn narration (text before tools) stays chrome-free.
@@ -62,68 +47,6 @@ export function assistantActionsSeqs(nodes: readonly ConversationNode[]): Readon
   return new Set(lastByTurn.values())
 }
 
-/**
- * Files each turn produced, keyed by the assistant seq that closes it — the
- * same anchor {@link assistantActionsSeqs} elects, so the row lands under the
- * message that reports the work rather than after some mid-turn narration.
- *
- * The source is the mutation tools' own follow-along `locations`, not the
- * closing prose: a produced file must be listed whether or not the model
- * remembered to name it. A mutation is recognized by render intent, not by
- * tool name — a diff card, or a generic card whose `kind` is `edit` (the shape
- * `str_replace_editor`'s insert presents) — so a new mutation tool joins by
- * declaring what it does. Reads contribute nothing (looking at a file does not
- * produce it), and neither do deletes (there is nothing left to open) or
- * failed calls. Paths keep first-seen order and appear once, so a file written
- * and then edited in the same turn is one entry.
- *
- * Accumulation resets on the turn boundary, not merely at the closing
- * assistant: a turn that mutates files and then ends without content text
- * (interrupted mid-tool, or a turn whose last text precedes its last tool
- * result) must not spill its paths into the next turn's row, nor leave `seen`
- * suppressing a file the next turn legitimately rewrites.
- * @param nodes - snapshot nodes (surface order).
- * @returns Per-closing-seq produced paths; a turn that produced none is absent.
- */
-export function turnDeliverables(nodes: readonly ConversationNode[]): ReadonlyMap<number, readonly string[]> {
-  const closing = assistantActionsSeqs(nodes)
-  const byClosingSeq = new Map<number, readonly string[]>()
-  let pending: string[] = []
-  let seen = new Set<string>()
-  let turn: number | undefined
-  for (const node of nodes) {
-    if (node.kind === 'tool-result') {
-      if (node.isError) continue
-      for (const path of producedPaths(node.callView)) {
-        if (seen.has(path)) continue
-        seen.add(path)
-        pending.push(path)
-      }
-      continue
-    }
-    // Tool results carry no turn of their own, so the boundary is read off the
-    // nodes that do. A user message opens a turn without reporting a number,
-    // which is why the tracked turn goes back to undefined there: the next
-    // node to report one is stating the current turn, not entering a new one.
-    if (node.kind === 'user') {
-      turn = undefined
-      pending = []
-      seen = new Set()
-    } else if ('turn' in node) {
-      if (turn !== undefined && node.turn !== turn) {
-        pending = []
-        seen = new Set()
-      }
-      turn = node.turn
-    }
-    if (node.kind !== 'assistant' || !closing.has(node.seq)) continue
-    if (pending.length > 0) byClosingSeq.set(node.seq, pending)
-    pending = []
-    seen = new Set()
-  }
-  return byClosingSeq
-}
-
 /**
  * Exact start time of the latest in-window turn without a matching end time.
  * @param turnTimings - In-window turn timings in event order.
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index a84b4a3bf0..1246433a33 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -3,7 +3,7 @@ import type { ReactNode, RefObject } from 'react'
 import type {
   InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook,
 } from '@deepseek-ai/dsh-client-ui-slots'
-import type { CommandNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { CommandNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { ComposerKeyboard, EditSelection, InputActions, InputNotice, InputState } from '../input/contract.ts'
 import type { createChatStore } from '../stores.ts'
@@ -46,6 +46,15 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * registration, and a domain upgrades by registering one row component.
      */
     'conversation.chat.commandview': { kind: 'keyed'; scope: 'session'; owner: CommandRowOwnerProps }
+    /**
+     * The chat view's turn-tail hole: rendered between a closing assistant
+     * message's body and its IconActions footer, once per turn (the render
+     * site elects the closing seq). Declared by the chat view entry; feature
+     * plugins (ui-deliverables' produced-files row) derive what they show
+     * from the owner currency, and an unregistered hole renders nothing —
+     * composing such a plugin out of cordis.yml turns its surface off.
+     */
+    'conversation.chat.turnTail': { kind: 'list'; scope: 'session'; owner: TurnTailOwnerProps }
     /**
      * The composer takeover chain: entries are selector-routed replacements
      * of the default InputBar. Declared by this package's 'conversation'
@@ -150,6 +159,24 @@ export interface ConvViewOwnerProps {
   onInspectDone?: () => void
 }
 
+/**
+ * Owner currency of the chat view's turn-tail hole: the finalized snapshot
+ * and the closing assistant's anchor. Registrants derive their own facts
+ * from the nodes (the owner never pre-chews a feature's vocabulary), and
+ * open files through the same opener the tool rows use.
+ */
+export interface TurnTailOwnerProps {
+  /** Finalized snapshot nodes in surface order. */
+  nodes: readonly ConversationNode[]
+  /** The closing assistant's seq — the anchor the tail renders under. */
+  seq: number
+  /**
+   * Open a filesystem path through the Host (tool-row semantics; the chat
+   * view resolves relative paths against the session cwd).
+   */
+  openFile: (path: string) => void
+}
+
 /**
  * Owner share of a per-view toolview slot: the call material the rendering
  * view supplies per row. Uniform across views — the trajectory/waterfall
@@ -480,7 +507,7 @@ export interface ChatViewInjected {
 
 /** Full chat-view component props: runtime & the declared toolview/commandview holes' render share & store & injected & locale seat. */
 export type ChatViewSlotProps =
-  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.toolview' | 'conversation.chat.commandview'>
+  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.toolview' | 'conversation.chat.commandview' | 'conversation.chat.turnTail'>
   & PropsStore<ChatStore> & ChatViewInjected & PropsLocale<'conversation'>
 
 /**
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index ac5f6574c8..725868d57a 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -17,7 +17,7 @@ export type {
   ComposerChainProps, ConversationInjected,
   ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps,
   ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps,
-  EmptyWorkspaceOwnerProps, ToolRowOwnerProps, ToolRowProps,
+  EmptyWorkspaceOwnerProps, ToolRowOwnerProps, ToolRowProps, TurnTailOwnerProps,
 } from './contract/slots.ts'
 // Export discipline: packages/client/AGENTS.md.
 
diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index b489bb29a1..9ba5ed3876 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -85,9 +85,6 @@ export const zh = {
   'message.unknownSurface': '未知 surface 事件：{type}',
   'message.unknownBlock': '未知内容块',
   'message.stopped': '已停止',
-  'produced.label': '产物',
-  'produced.more': '还有 {count} 个',
-  'produced.open': '打开 {name}',
   'message.branch': '在新对话中分支',
   'message.branchUnavailable': '仅可从已完成轮次的最后一条消息分支',
   'message.retry.active': '正在重试模型请求',
@@ -228,9 +225,6 @@ export const en = {
   'message.unknownSurface': 'Unknown surface event: {type}',
   'message.unknownBlock': 'Unknown content block',
   'message.stopped': 'Stopped',
-  'produced.label': 'Produced',
-  'produced.more': '{count} more',
-  'produced.open': 'Open {name}',
   'message.branch': 'Branch into a new conversation',
   'message.branchUnavailable': 'Available only on the last message of a completed turn',
   'message.retry.active': 'Retrying model request',
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index dc3e6f5241..4da138d1b5 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -20,7 +20,7 @@ import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts
 import { createChatStore } from '../src/client/stores.ts'
 import { ChatView } from '../src/client/chat/ChatView.tsx'
 import { zh } from '../src/client/locales.ts'
-import { assistantActionsSeqs, deriveChatFlow, flowKeys, messageBranchSeqs, runningTurnStartTime, turnDeliverables } from '../src/client/chat/chat-flow.ts'
+import { assistantActionsSeqs, deriveChatFlow, flowKeys, messageBranchSeqs, runningTurnStartTime } from '../src/client/chat/chat-flow.ts'
 import { formatRunDuration } from '../src/client/chat/message-chrome.ts'
 
 afterEach(() => {
@@ -242,93 +242,6 @@ describe('chat-flow derivation', () => {
     expect([...seqs].sort((a, b) => a - b)).toEqual([5, 7])
   })
 
-  it('turnDeliverables attributes each turn’s written files to the assistant that closes it', () => {
-    const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
-      ...toolResult(seq, callId, 'write'),
-      callView: {
-        card: 'diff', title: `Write ${paths[0] ?? ''}`,
-        diffs: paths.map(path => ({ path, oldText: null, newText: 'x' })),
-        locations: paths.map(path => ({ path })),
-      },
-    })
-    const produced = turnDeliverables([
-      user(1, 'build it'),
-      assistant(2, 'writing', 1),
-      wrote(3, 'a', 'out/index.html'),
-      // Same file touched twice in one turn is one deliverable, in first-seen order.
-      wrote(4, 'b', 'out/app.css', 'out/index.html'),
-      // A read is not a deliverable; a failed write has no file to open.
-      { ...toolResult(5, 'c', 'read'), callView: { card: 'generic', title: 'Read x', locations: [{ path: 'x.ts' }] } },
-      { ...wrote(6, 'd', 'out/broken.html'), isError: true },
-      assistant(7, 'done', 1),
-      user(8, 'again'),
-      assistant(9, 'second turn', 2),
-    ])
-    expect(produced.get(7)).toEqual(['out/index.html', 'out/app.css'])
-    // A turn that produced nothing is absent, not an empty row.
-    expect(produced.has(9)).toBe(false)
-    // Nothing at all written: no entries.
-    expect(turnDeliverables([user(1, 'hi'), assistant(2, 'hello', 1)]).size).toBe(0)
-  })
-
-  it('turnDeliverables counts a generic edit and never spills across the turn boundary', () => {
-    const inserted = (seq: number, callId: string, path: string): ToolResultNode => ({
-      ...toolResult(seq, callId, 'str_replace_editor'),
-      // str_replace_editor's insert mutates behind a generic card, so the
-      // discriminant is the render intent, not the card shape alone.
-      callView: { card: 'generic', title: `insert ${path}`, kind: 'edit', locations: [{ path }] },
-    })
-    const wrote = (seq: number, callId: string, path: string): ToolResultNode => ({
-      ...toolResult(seq, callId, 'write'),
-      callView: {
-        card: 'diff', title: 'Write', diffs: [{ path, oldText: null, newText: 'x' }], locations: [{ path }],
-      },
-    })
-    const produced = turnDeliverables([
-      user(1, 'insert a line'),
-      inserted(2, 'i', 'notes.md'),
-      assistant(3, 'inserted', 1),
-      // Turn 2 mutates and then ends with no content text (interrupted, or its
-      // last text preceded the tool): its paths must not ride into turn 3.
-      user(4, 'now rewrite it'),
-      wrote(5, 'w', 'leaked.txt'),
-      user(6, 'and again'),
-      wrote(7, 'w2', 'notes.md'),
-      assistant(8, 'done', 3),
-    ])
-    expect(produced.get(3)).toEqual(['notes.md'])
-    // Turn 3 lists only its own file — and `seen` did not suppress the rewrite
-    // of a path an earlier turn already touched.
-    expect(produced.get(8)).toEqual(['notes.md'])
-    expect([...produced.values()].flat()).not.toContain('leaked.txt')
-  })
-
-  it('renders the produced files under the closing message and opens one on click', () => {
-    const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
-      ...toolResult(seq, callId, 'write'),
-      callView: {
-        card: 'diff', title: 'Write',
-        diffs: paths.map(path => ({ path, oldText: null, newText: 'x' })),
-        locations: paths.map(path => ({ path })),
-      },
-    })
-    // Seven files: six chips plus an explicit remainder — the row bounds what
-    // it shows and says so rather than dropping the rest silently.
-    const paths = ['deep/a.html', 'b.css', 'c.ts', 'd.ts', 'e.ts', 'f.ts', 'g.ts']
-    const h = makeHarness({
-      nodes: [user(1, 'build it'), wrote(2, 'w', ...paths), assistant(3, 'done', 1)],
-    })
-    const view = render(<h.ChatView {...h.props} />)
-    expect(view.getByText('产物')).toBeTruthy()
-    // Chips carry the basename; the full path stays reachable as the title.
-    const chip = view.getByRole('button', { name: '打开 deep/a.html' })
-    expect(chip.textContent).toBe('a.html')
-    expect(view.queryByRole('button', { name: '打开 g.ts' })).toBeNull()
-    expect(view.getByText('还有 1 个')).toBeTruthy()
-    fireEvent.click(chip)
-    expect(h.openFile).toHaveBeenCalledWith('deep/a.html')
-  })
-
   it('runningTurnStartTime selects the latest turn/start without a turn/end', () => {
     expect(runningTurnStartTime(new Map([
       [1, { startTime: 1_000, endTime: 5_000 }],
@@ -790,7 +703,9 @@ describe('ChatView', () => {
     // Count renderSlot invocations: the memo boundary holds when CallRow does
     // not re-render, so the row's renderSlot call count freezes during chunks.
     let rowRenders = 0
-    h.props.renderSlot = ((_key: string, _owner: object) => {
+    h.props.renderSlot = ((key: string, _owner: object) => {
+      // The turnTail hole renders through the same share; only tool rows count here.
+      if (key !== 'conversation.chat.toolview') return null
       rowRenders += 1
       return <div data-testid="counting-row" />
     })
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
new file mode 100644
index 0000000000..ee4c23c18c
--- /dev/null
+++ b/packages/client/ui-deliverables/README.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 packages/client/ui-deliverables/README.md
+README.md: b8b0ea2ef1cbc9b18b905fc08b41278f403ef043
+README.zh.md: a16535b8a8d3625ca1cf90e88c6d9dca742d916b
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
new file mode 100644
index 0000000000..b8b0ea2ef1
--- /dev/null
+++ b/packages/client/ui-deliverables/README.md
@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-client-ui-deliverables
+
+English | [中文](README.zh.md)
+
+Produced-files feature owner: registers the deliverables row a finished turn ends with into the chat view's `conversation.chat.turnTail` hole. All policy lives here; removing this plugin's line from cordis.yml removes the surface entirely, and the owning view renders an empty hole at zero cost.
+
+`producedForClosing` derives one turn's produced files from the tail hole's owner currency — the finalized snapshot nodes and the closing assistant's seq. The vocabulary is the mutation tools' own follow-along `locations`, never the closing prose: a produced file is listed whether or not the model remembered to name it. A mutation is recognized by render intent, not tool name — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a new mutation tool joins by declaring what it does. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row.
+
+`ProducedFiles` renders the row between the closing message's body and its IconActions footer: a quiet label, up to six chips (basename text, full path as the `title`), and an explicit remainder count past the cap. Each chip opens through the owner-supplied `openFile` — the same Host opener the tool rows use, with the chat view resolving relative paths against the session cwd. Design rationale: the [workspace file links Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md).
+
+## Model Experience
+
+None, as the row is a pure client derivation over already-logged tool metadata and nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends provider requests.
+
+## Known Limitations and Deferred Work
+
+- **Prose mentions stay inert.** An inline-code file name in the closing message does not open the file yet; linking it to the same `locations` vocabulary is the stacked follow-up.
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
new file mode 100644
index 0000000000..a16535b8a8
--- /dev/null
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-client-ui-deliverables
+
+[English](README.md) | 中文
+
+产物文件的功能属主：把"完成的一轮以其产出文件收尾"的产物行注册进 chat 视图的 `conversation.chat.turnTail` 空位。全部策略都在本包内；从 cordis.yml 中删去本插件那一行即可整体移除该交互面，属主视图以零成本渲染一个空的空位。
+
+`producedForClosing` 从 tail 空位的 owner 通货——定稿的快照节点与收尾 assistant 的 seq——推导一轮产出的文件。词表是改写工具自身的跟随 `locations`，绝不是收尾正文：无论模型是否记得点名，产出文件都会被列出。改写按渲染意图识别而非工具名——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此新的改写工具靠声明自己做了什么加入。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。
+
+`ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个安静的标签、至多六枚 chip（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每枚 chip 经由 owner 提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
+
+## 模型体验
+
+无。该行是对已记录工具元数据的纯客户端派生，这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **正文提及仍是死文本。**收尾消息里以行内代码写出的文件名尚不能点击打开；把它接到同一份 `locations` 词表是 stacked 的后续工作。
diff --git a/packages/client/ui-deliverables/package.json b/packages/client/ui-deliverables/package.json
new file mode 100644
index 0000000000..0b5318499b
--- /dev/null
+++ b/packages/client/ui-deliverables/package.json
@@ -0,0 +1,65 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-deliverables",
+  "description": "Produced-files turn tail: the deliverables row a finished turn ends with",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-locale",
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-ui-conversation"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-locale": "^0.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ]
+}
diff --git a/packages/client/ui-conversation/src/client/chat/Deliverables.module.css b/packages/client/ui-deliverables/src/client/ProducedFiles.module.css
similarity index 100%
rename from packages/client/ui-conversation/src/client/chat/Deliverables.module.css
rename to packages/client/ui-deliverables/src/client/ProducedFiles.module.css
diff --git a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
new file mode 100644
index 0000000000..609a688586
--- /dev/null
+++ b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
@@ -0,0 +1,61 @@
+// ProducedFiles: the produced-file row a finished turn ends with. The paths
+// come from the mutation tools' follow-along locations (see
+// producedForClosing), never from the closing prose, so the answer carries
+// its own output whether or not the model remembered to name it. Clicking one
+// goes through the same openFile the tool rows use — the Host's own opener,
+// on the Host machine.
+
+import { useMemo } from 'react'
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { producedForClosing } from './turn-deliverables.ts'
+import type { NS } from './locales.ts'
+import css from './ProducedFiles.module.css'
+
+/** Files past this stay counted but unlisted: a refactor turn must not bury the answer. */
+const SHOWN = 6
+
+/** Trailing path segment, the part that identifies the file at a glance. */
+function basename(path: string): string {
+  const at = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
+  return at === -1 ? path : path.slice(at + 1)
+}
+
+/** Full props: the turn-tail owner currency plus this plugin's locale seat. */
+export type ProducedFilesProps = TurnTailOwnerProps & PropsLocale<typeof NS>
+
+/**
+ * Render one turn's produced files as openable chips.
+ * @param props - the tail hole's owner currency (snapshot nodes, the closing
+ * assistant's seq, the chat view's file opener) and the locale seat.
+ * @returns The row, or `null` when the turn produced nothing.
+ */
+export function ProducedFiles({ nodes, seq, openFile, t }: ProducedFilesProps) {
+  // Per-closing-message derivation over the windowed snapshot: O(nodes) on
+  // node-identity change only, which is the same cadence the owning view
+  // re-derives its own flow at.
+  const paths = useMemo(() => producedForClosing(nodes, seq), [nodes, seq])
+  if (paths.length === 0) return null
+  const shown = paths.slice(0, SHOWN)
+  const hidden = paths.length - shown.length
+  return (
+    <div className={css.root}>
+      <span className={css.label}>{t('produced.label')}</span>
+      {shown.map(path => (
+        <button
+          key={path}
+          type="button"
+          className={css.file}
+          // The full path is the disambiguator when two turns produce files
+          // that share a basename; the chip itself stays short.
+          title={path}
+          aria-label={t('produced.open', { name: path })}
+          onClick={() => { openFile(path) }}
+        >
+          {basename(path)}
+        </button>
+      ))}
+      {hidden > 0 && <span className={css.more}>{t('produced.more', { count: String(hidden) })}</span>}
+    </div>
+  )
+}
diff --git a/packages/client/ui-deliverables/src/client/index.ts b/packages/client/ui-deliverables/src/client/index.ts
new file mode 100644
index 0000000000..536c019b01
--- /dev/null
+++ b/packages/client/ui-deliverables/src/client/index.ts
@@ -0,0 +1,42 @@
+/**
+ * Deliverables plugin, browser half: registers the produced-files row into
+ * the chat view's turn-tail hole. All policy lives here — the derivation
+ * from the mutation tools' `locations`, the chip cap, and the copy — so
+ * composing this plugin out of cordis.yml removes the surface entirely; the
+ * owning view renders an empty hole at zero cost.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import { ProducedFiles } from './ProducedFiles.tsx'
+import { en, NS, zh, type DeliverablesKey } from './locales.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** Produced-files row copy. */
+    'deliverables': DeliverablesKey
+  }
+}
+
+export { ProducedFiles, type ProducedFilesProps } from './ProducedFiles.tsx'
+export { producedForClosing } from './turn-deliverables.ts'
+
+/** Required services for the tail-slot registration and its dictionaries. */
+export const inject = ['slots', 'locale']
+
+/**
+ * Client plugin body: register the dictionaries and the turn-tail entry.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-deliverables: dictionaries')
+  ctx.slots.inject(
+    'conversation.chat.turnTail',
+    () => ctx.slots.register({
+      name: 'conversation.chat.turnTail',
+      id: 'produced-files',
+      order: 0,
+      locale: NS,
+    }, ProducedFiles),
+  )
+}
diff --git a/packages/client/ui-deliverables/src/client/locales.ts b/packages/client/ui-deliverables/src/client/locales.ts
new file mode 100644
index 0000000000..aa51aa75a7
--- /dev/null
+++ b/packages/client/ui-deliverables/src/client/locales.ts
@@ -0,0 +1,21 @@
+/** `deliverables` namespace dictionaries. */
+
+/** Dictionary namespace owned by this plugin. */
+export const NS = 'deliverables'
+
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export const zh = {
+  'produced.label': '产物',
+  'produced.more': '还有 {count} 个',
+  'produced.open': '打开 {name}',
+}
+
+/** English dictionary (same key set). */
+export const en: Record<DeliverablesKey, string> = {
+  'produced.label': 'Produced',
+  'produced.more': '{count} more',
+  'produced.open': 'Open {name}',
+}
+
+/** Union of this namespace's dictionary keys. */
+export type DeliverablesKey = keyof typeof zh
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
new file mode 100644
index 0000000000..faa0455b37
--- /dev/null
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -0,0 +1,78 @@
+/**
+ * Pure derivation of one turn's produced files from finalized snapshot
+ * nodes. Client-only and model-free: the vocabulary is the mutation tools'
+ * own follow-along `locations`, never the closing prose.
+ */
+import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+
+/**
+ * Paths a call view reports having created or changed, by render intent rather
+ * than tool name: a diff card, or a generic card whose kind is `edit` (the
+ * shape `str_replace_editor`'s insert presents). Every other card produces
+ * nothing to open — a read looked, a delete removed, a terminal ran.
+ */
+function producedPaths(view: ToolResultNode['callView']): readonly string[] {
+  if (view === null) return []
+  if (view.card === 'diff') return (view.locations ?? []).map(location => location.path)
+  if (view.card === 'generic' && view.kind === 'edit') {
+    return (view.locations ?? []).map(location => location.path)
+  }
+  return []
+}
+
+/**
+ * Files produced by the turn the assistant at `seq` closes — the anchor the
+ * render site elects, so the row lands under the message that reports the
+ * work rather than after some mid-turn narration.
+ *
+ * The source is the mutation tools' own follow-along `locations`, not the
+ * closing prose: a produced file must be listed whether or not the model
+ * remembered to name it. A mutation is recognized by render intent, not by
+ * tool name — a diff card, or a generic card whose `kind` is `edit` (the shape
+ * `str_replace_editor`'s insert presents) — so a new mutation tool joins by
+ * declaring what it does. Reads contribute nothing (looking at a file does not
+ * produce it), and neither do deletes (there is nothing left to open) or
+ * failed calls. Paths keep first-seen order and appear once, so a file written
+ * and then edited in the same turn is one entry.
+ *
+ * Accumulation resets on the turn boundary — a user message, or a node
+ * reporting a different turn number — so a turn that mutates files and then
+ * ends without content text cannot spill its paths into the next turn's row,
+ * nor leave the dedup set suppressing a file the next turn legitimately
+ * rewrites. Tool results carry no turn of their own; the boundary is read off
+ * the nodes that do, and a user message resets the tracked turn to undefined
+ * because the next node to report one is stating the current turn, not
+ * entering a new one.
+ * @param nodes - snapshot nodes (surface order).
+ * @param seq - the closing assistant's seq (the render site's anchor).
+ * @returns Produced paths in first-seen order; empty when the turn wrote nothing.
+ */
+export function producedForClosing(nodes: readonly ConversationNode[], seq: number): readonly string[] {
+  let pending: string[] = []
+  let seen = new Set<string>()
+  let turn: number | undefined
+  for (const node of nodes) {
+    if (node.kind === 'tool-result') {
+      if (node.isError) continue
+      for (const path of producedPaths(node.callView)) {
+        if (seen.has(path)) continue
+        seen.add(path)
+        pending.push(path)
+      }
+      continue
+    }
+    if (node.kind === 'user') {
+      turn = undefined
+      pending = []
+      seen = new Set()
+    } else if ('turn' in node) {
+      if (turn !== undefined && node.turn !== turn) {
+        pending = []
+        seen = new Set()
+      }
+      turn = node.turn
+    }
+    if (node.kind === 'assistant' && node.seq === seq) return pending
+  }
+  return []
+}
diff --git a/packages/client/ui-deliverables/src/css-modules.d.ts b/packages/client/ui-deliverables/src/css-modules.d.ts
new file mode 100644
index 0000000000..bc5e482353
--- /dev/null
+++ b/packages/client/ui-deliverables/src/css-modules.d.ts
@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'
diff --git a/packages/client/ui-deliverables/src/index.ts b/packages/client/ui-deliverables/src/index.ts
new file mode 100644
index 0000000000..012876cc2d
--- /dev/null
+++ b/packages/client/ui-deliverables/src/index.ts
@@ -0,0 +1,9 @@
+/**
+ * Deliverables plugin, node half. Pure UI plugin: the empty apply exists so
+ * the plugin appears in the host cordis.yml / Loader; the browser half ships
+ * via exports["./client"], discovered through the package.json dshClient
+ * declaration.
+ */
+
+/** Host plugin body — no host-side behavior for this surface plugin. */
+export function apply(): void {}
diff --git a/packages/client/ui-deliverables/src/invariant.ts b/packages/client/ui-deliverables/src/invariant.ts
new file mode 100644
index 0000000000..39c39591cf
--- /dev/null
+++ b/packages/client/ui-deliverables/src/invariant.ts
@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-deliverables`.
+ * @module @deepseek-ai/dsh-client-ui-deliverables/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-deliverables'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-deliverables-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: one slot registration and one dictionary
+ * registration, both effect-owned with disposal proven by the HMR-safety
+ * spec — the plugin emits no cordis events and owns no cross-plugin mutable
+ * state.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
new file mode 100644
index 0000000000..e5d92424a3
--- /dev/null
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -0,0 +1,183 @@
+// @vitest-environment jsdom
+/**
+ * ui-deliverables browser half: the derivation contract of
+ * `producedForClosing` over finalized snapshot nodes, the row's rendering
+ * and opener wiring, and the plugin registrations' fiber-teardown removal
+ * (HMR safety) against the real SlotsService.
+ */
+import { Context } from 'cordis'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  AssistantMessageNode, ConversationNode, ToolResultNode, UserMessageNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { apply as applyLocale } from '@deepseek-ai/dsh-client-locale/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { ProducedFiles } from '../src/client/ProducedFiles.tsx'
+import { producedForClosing } from '../src/client/turn-deliverables.ts'
+import { apply, inject } from '../src/client/index.ts'
+import { apply as applyNode } from '../src/index.ts'
+import { apply as applyInvariant } from '../src/invariant.ts'
+import { zh } from '../src/client/locales.ts'
+
+afterEach(cleanup)
+
+const user = (seq: number, text: string): UserMessageNode => ({
+  kind: 'user',
+  seq,
+  time: seq * 1000,
+  content: [{ type: 'text', text }] as never,
+  source: null,
+})
+const assistant = (seq: number, text: string, turn = 1): AssistantMessageNode => ({
+  kind: 'assistant', seq, time: seq * 1_000, turn, step: 1, blocks: [{ kind: 'text', text }],
+})
+const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode => ({
+  kind: 'tool-result', seq, time: seq * 1_000, callId,
+  call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` },
+  callTime: seq * 1_000 - 500,
+  content: [], isError: false, callView: null, resultView: null,
+})
+const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
+  ...toolResult(seq, callId, 'write'),
+  callView: {
+    card: 'diff', title: `Write ${paths[0] ?? ''}`,
+    diffs: paths.map(path => ({ path, oldText: null, newText: 'x' })),
+    locations: paths.map(path => ({ path })),
+  },
+})
+
+describe('producedForClosing derivation', () => {
+  it('attributes each turn’s written files to the assistant that closes it', () => {
+    const nodes: ConversationNode[] = [
+      user(1, 'build it'),
+      assistant(2, 'writing', 1),
+      wrote(3, 'a', 'out/index.html'),
+      // Same file touched twice in one turn is one deliverable, in first-seen order.
+      wrote(4, 'b', 'out/app.css', 'out/index.html'),
+      // A read is not a deliverable; a failed write has no file to open.
+      { ...toolResult(5, 'c', 'read'), callView: { card: 'generic', title: 'Read x', locations: [{ path: 'x.ts' }] } },
+      { ...wrote(6, 'd', 'out/broken.html'), isError: true },
+      assistant(7, 'done', 1),
+      user(8, 'again'),
+      assistant(9, 'second turn', 2),
+    ]
+    expect(producedForClosing(nodes, 7)).toEqual(['out/index.html', 'out/app.css'])
+    // A turn that produced nothing yields the empty list, and so does an
+    // anchor the window does not contain.
+    expect(producedForClosing(nodes, 9)).toEqual([])
+    expect(producedForClosing([user(1, 'hi'), assistant(2, 'hello', 1)], 2)).toEqual([])
+    expect(producedForClosing(nodes, 999)).toEqual([])
+  })
+
+  it('counts a generic edit and never spills across the turn boundary', () => {
+    const inserted = (seq: number, callId: string, path: string): ToolResultNode => ({
+      ...toolResult(seq, callId, 'str_replace_editor'),
+      // str_replace_editor's insert mutates behind a generic card, so the
+      // discriminant is the render intent, not the card shape alone.
+      callView: { card: 'generic', title: `insert ${path}`, kind: 'edit', locations: [{ path }] },
+    })
+    const nodes: ConversationNode[] = [
+      user(1, 'insert a line'),
+      inserted(2, 'i', 'notes.md'),
+      assistant(3, 'inserted', 1),
+      // Turn 2 mutates and then ends with no content text (interrupted, or its
+      // last text preceded the tool): its paths must not ride into turn 3.
+      user(4, 'now rewrite it'),
+      wrote(5, 'w', 'leaked.txt'),
+      user(6, 'and again'),
+      wrote(7, 'w2', 'notes.md'),
+      assistant(8, 'done', 3),
+    ]
+    expect(producedForClosing(nodes, 3)).toEqual(['notes.md'])
+    // Turn 3 lists only its own file — and the dedup set did not suppress the
+    // rewrite of a path an earlier turn already touched.
+    expect(producedForClosing(nodes, 8)).toEqual(['notes.md'])
+    expect(producedForClosing(nodes, 8)).not.toContain('leaked.txt')
+  })
+
+  it('resets on a turn-number change and skips turnless, viewless, and locationless nodes', () => {
+    const nodes: ConversationNode[] = [
+      user(1, 'go'),
+      // A turnless surface node neither tracks nor resets the boundary.
+      { kind: 'unknown', seq: 1.5, time: 1_500, type: 'x', data: null },
+      wrote(2, 'w', 'turn-one.txt'),
+      // A view-less result (window truncation) and cards without locations
+      // contribute nothing rather than crashing the walk.
+      toolResult(3, 'plain'),
+      { ...toolResult(4, 'nl', 'write'), callView: { card: 'diff', title: 'Write', diffs: [] } },
+      { ...toolResult(5, 'ge', 'str_replace_editor'), callView: { card: 'generic', title: 'insert', kind: 'edit' } },
+      assistant(6, 'mid narration', 1),
+      // Turn number advances with no user message in the window (truncated
+      // history): the accumulator must reset all the same.
+      assistant(7, 'closing', 2),
+    ]
+    expect(producedForClosing(nodes, 6)).toEqual(['turn-one.txt'])
+    expect(producedForClosing(nodes, 7)).toEqual([])
+  })
+})
+
+describe('ProducedFiles row', () => {
+  const t = makeTranslate(zh)
+
+  it('renders capped chips with the full path reachable and opens one on click', () => {
+    // Seven files: six chips plus an explicit remainder — the row bounds what
+    // it shows and says so rather than dropping the rest silently.
+    const paths = ['deep/a.html', 'b.css', 'c.ts', 'd.ts', 'e.ts', 'f.ts', 'g.ts']
+    const openFile = vi.fn<(path: string) => void>()
+    const nodes: ConversationNode[] = [user(1, 'build it'), wrote(2, 'w', ...paths), assistant(3, 'done', 1)]
+    const view = render(<ProducedFiles nodes={nodes} seq={3} openFile={openFile} t={t} />)
+    expect(view.getByText('产物')).toBeTruthy()
+    // Chips carry the basename; the full path stays reachable as the title.
+    const chip = view.getByRole('button', { name: '打开 deep/a.html' })
+    expect(chip.textContent).toBe('a.html')
+    expect(chip.getAttribute('title')).toBe('deep/a.html')
+    expect(view.queryByRole('button', { name: '打开 g.ts' })).toBeNull()
+    expect(view.getByText('还有 1 个')).toBeTruthy()
+    fireEvent.click(chip)
+    expect(openFile).toHaveBeenCalledWith('deep/a.html')
+  })
+
+  it('a turn that produced nothing renders no row at all', () => {
+    const nodes: ConversationNode[] = [user(1, 'hi'), assistant(2, 'hello', 1)]
+    const view = render(<ProducedFiles nodes={nodes} seq={2} openFile={() => {}} t={t} />)
+    expect(view.container.firstChild).toBeNull()
+  })
+})
+
+describe('package shells', () => {
+  it('the node half mounts inert and the invariant companion registers ownership', async () => {
+    // The node half is deliberately inert; mounting it must simply not throw.
+    applyNode()
+    const registered: string[] = []
+    const ctx = new Context()
+    ctx.provide('invariants')
+    ctx.set('invariants', {
+      register: (pkg: string) => { registered.push(pkg); return () => {} },
+    } as never)
+    const dispose = await applyInvariant(ctx)
+    expect(registered).toEqual(['@deepseek-ai/dsh-client-ui-deliverables'])
+    expect(dispose).toBeTypeOf('function')
+  })
+})
+
+describe('plugin registration', () => {
+  it('registers the tail entry and fiber disposal removes it', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SlotsService).await()
+    // The owning view's child declaration, stood up by a bench root entry.
+    ctx.slots.register({
+      name: 'root',
+      children: { 'conversation.chat.turnTail': { kind: 'list', scope: 'session' } },
+    } as never, () => null)
+    await ctx.plugin({ inject: ['slots'], apply: applyLocale }).await()
+
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(ctx.slots.entries('conversation.chat.turnTail')).toHaveLength(1)
+
+    await fiber.dispose()
+    expect(ctx.slots.entries('conversation.chat.turnTail')).toHaveLength(0)
+  })
+})
diff --git a/packages/client/ui-deliverables/tsconfig.json b/packages/client/ui-deliverables/tsconfig.json
new file mode 100644
index 0000000000..3fa938986f
--- /dev/null
+++ b/packages/client/ui-deliverables/tsconfig.json
@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../locale"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-conversation"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/ui-deliverables/tsdown.config.ts b/packages/client/ui-deliverables/tsdown.config.ts
new file mode 100644
index 0000000000..ce1a8cefcc
--- /dev/null
+++ b/packages/client/ui-deliverables/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-deliverables', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 208e43aa5f..e50fa70b2a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -179,6 +179,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-conversation':
         specifier: workspace:^
         version: link:../../packages/client/ui-conversation
+      '@deepseek-ai/dsh-client-ui-deliverables':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-deliverables
       '@deepseek-ai/dsh-client-ui-goal':
         specifier: workspace:^
         version: link:../../packages/client/ui-goal
@@ -1440,6 +1443,37 @@ importers:
         specifier: ^18.2.0
         version: 18.3.1
 
+  packages/client/ui-deliverables:
+    dependencies:
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+    devDependencies:
+      '@deepseek-ai/dsh-client-locale':
+        specifier: workspace:^
+        version: link:../locale
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../runtime
+      '@deepseek-ai/dsh-client-test-runtime':
+        specifier: workspace:^
+        version: link:../test-runtime
+      '@deepseek-ai/dsh-client-ui-conversation':
+        specifier: workspace:^
+        version: link:../ui-conversation
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/client/ui-goal:
     devDependencies:
       '@deepseek-ai/dsh-client-connection':
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 041972cb9f..cb7ffb7460 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -61,6 +61,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-conversation': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-deliverables': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-slash': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-command': { kind: 'indirect', reason: 'The dispatch paths trigger the host command.execute RPC; each command handler\'s host package owns any model-visible effect.' },
   'packages/client/ui-model': { kind: 'indirect', reason: 'Selection routes session.selectModel; the host snapshots the target at the next prompt-assembly boundary and owns the model-visible effect.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 9ba9ba5d84..94e08da920 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -151,6 +151,7 @@
       "@deepseek-ai/dsh-client-ui-layout": ["./packages/client/ui-layout/src"],
       "@deepseek-ai/dsh-client-ui-sidebar": ["./packages/client/ui-sidebar/src"],
       "@deepseek-ai/dsh-client-ui-conversation": ["./packages/client/ui-conversation/src"],
+      "@deepseek-ai/dsh-client-ui-deliverables": ["./packages/client/ui-deliverables/src"],
       "@deepseek-ai/dsh-client-ui-slash": ["./packages/client/ui-slash/src"],
       "@deepseek-ai/dsh-client-ui-command": ["./packages/client/ui-command/src"],
       "@deepseek-ai/dsh-client-ui-model": ["./packages/client/ui-model/src"],
diff --git a/tsconfig.client.json b/tsconfig.client.json
index e1d4088061..03a2b8bb59 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -56,6 +56,7 @@
     { "path": "./packages/client/ui-layout" },
     { "path": "./packages/client/ui-sidebar" },
     { "path": "./packages/client/ui-conversation" },
+    { "path": "./packages/client/ui-deliverables" },
     { "path": "./packages/client/ui-workspace" },
     { "path": "./packages/client/ui-slash" },
     { "path": "./packages/client/ui-command" },

From 7aedc02ae32b1f049dfe8a5ca5a61f43a7748837 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Thu, 6 Aug 2026 06:39:08 -0700
Subject: [PATCH 076/516] docs: regenerate module graph for ui-deliverables

---
 docs/module-graph.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index 3ad8ef0b7e..70f2570aa1 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -159,6 +159,7 @@ flowchart TD
     pkg_client_test_runtime["client-test-runtime"]
     pkg_client_ui_command["client-ui-command"]
     pkg_client_ui_conversation["client-ui-conversation"]
+    pkg_client_ui_deliverables["client-ui-deliverables"]
     pkg_client_ui_goal["client-ui-goal"]
     pkg_client_ui_layout["client-ui-layout"]
     pkg_client_ui_model["client-ui-model"]
@@ -840,6 +841,11 @@ flowchart TD
   pkg_client_ui_command --> pkg_client_ui_slash
   pkg_client_ui_command --> pkg_client_ui_slots
   pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_deliverables --> pkg_client_locale
+  pkg_client_ui_deliverables --> pkg_client_runtime
+  pkg_client_ui_deliverables --> pkg_client_ui_conversation
+  pkg_client_ui_deliverables --> pkg_client_ui_slots
+  pkg_client_ui_deliverables --> pkg_invariants
   pkg_client_ui_goal --> pkg_client_connection
   pkg_client_ui_goal --> pkg_client_locale
   pkg_client_ui_goal --> pkg_client_runtime
@@ -1243,6 +1249,7 @@ flowchart TD
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |

From 5514dd2bd6409d076bfa963a1c835fdd97e3f61b Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 21:39:57 +0800
Subject: [PATCH 077/516] fix(llm-deepseek): refuse an API key no header can
 carry

---
 docs/config-catalog.md                        |  6 +++-
 packages/llm/llm-deepseek/src/index.ts        | 27 +++++++++++++----
 .../llm/llm-deepseek/tests/adapter.spec.ts    | 30 +++++++++++++++++++
 .../llm-deepseek/tests/dynamic-config.spec.ts | 21 ++++++++++++-
 4 files changed, 77 insertions(+), 7 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 89f1529387..a3e63d994d 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -642,7 +642,11 @@ Requires: `llm`
  * reasoning effort resolves to `high`.
  */
 export interface Config {
-  /** Literal API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
+  /**
+   * Literal API key; prefer {@link apiKeyEnv} so no secret enters configuration files. Trimmed
+   * and format-checked by {@link resolveAdapterOptions}; a value no HTTP header can carry fails
+   * there rather than inside `fetch`.
+   */
   apiKey?: string
   /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
   apiKeyEnv?: string
diff --git a/packages/llm/llm-deepseek/src/index.ts b/packages/llm/llm-deepseek/src/index.ts
index cd2bb9a24e..6aaab15573 100644
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/packages/llm/llm-deepseek/src/index.ts
@@ -13,7 +13,7 @@
 
 import type { Context } from 'cordis'
 import z from 'schemastery'
-import { LlmError, resolveRetryPolicy, RetryPolicySchema } from '@deepseek-ai/dsh-llm'
+import { assertUsableApiKey, LlmError, normalizeApiKey, resolveRetryPolicy, RetryPolicySchema } from '@deepseek-ai/dsh-llm'
 import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import { deepEqualJson, installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
@@ -58,7 +58,11 @@ const DEFAULT_MODELS: DeepSeekCatalogModel[] = [
  * reasoning effort resolves to `high`.
  */
 export interface Config {
-  /** Literal API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
+  /**
+   * Literal API key; prefer {@link apiKeyEnv} so no secret enters configuration files. Trimmed
+   * and format-checked by {@link resolveAdapterOptions}; a value no HTTP header can carry fails
+   * there rather than inside `fetch`.
+   */
   apiKey?: string
   /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
   apiKeyEnv?: string
@@ -174,8 +178,21 @@ export function resolveAdapterOptions(config: Config): ResolvedDeepSeekOptions {
       `llm-deepseek: streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`,
     )
   }
+  // An absent apiKey is not a failure: it falls through to apiKeyEnv below.
+  // A supplied one must be usable, so a malformed literal fails here beside
+  // the other beyond-schema bounds instead of inside `fetch`.
+  let apiKey: string | undefined
+  if (config.apiKey !== undefined) {
+    const checked = normalizeApiKey(config.apiKey)
+    if (!checked.ok) {
+      throw new Error(checked.reason === 'empty'
+        ? 'llm-deepseek: apiKey is empty; omit it to resolve the key from apiKeyEnv'
+        : 'llm-deepseek: apiKey contains characters no HTTP header can carry; paste the raw key only')
+    }
+    apiKey = checked.value
+  }
   return {
-    ...config.apiKey !== undefined && config.apiKey.length > 0 ? { apiKey: config.apiKey } : {},
+    ...apiKey === undefined ? {} : { apiKey },
     apiKeyEnv: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
     baseURL: config.baseURL ?? process.env.DEEPSEEK_BASE_URL ?? PUBLIC_BASE_URL,
     defaults: {
@@ -223,12 +240,12 @@ export function apply(ctx: Context, config: Config): void {
     const credentials = ctx.get('credentials')
     if (credentials !== undefined) {
       const hit = await credentials.resolve(ref)
-      if (hit !== undefined) return hit.value
+      if (hit !== undefined) return assertUsableApiKey(hit.value, 'llm-deepseek', ref)
     } else {
       // Without the seam, keep the historical ambient fallback so a plain
       // cordis.yml composition works from the environment alone.
       const ambient = process.env[ref]
-      if (ambient !== undefined && ambient.length > 0) return ambient
+      if (ambient !== undefined && ambient.length > 0) return assertUsableApiKey(ambient, 'llm-deepseek', ref)
     }
     throw new LlmError(
       `llm-deepseek: no API key for provider route "${PROVIDER}"; store ${ref} through the credentials`
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index 9d104ace08..56ac3eb138 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -991,3 +991,33 @@ describe('plugin registration and config', () => {
     expect(ctx.llm.listProviders()).toEqual([])
   })
 })
+
+describe('API key format', () => {
+  it('trims a padded literal apiKey', () => {
+    expect(resolveAdapterOptions({ apiKey: '  sk-abc  ' }).apiKey).toBe('sk-abc')
+  })
+
+  it('leaves an omitted apiKey absent so apiKeyEnv still resolves it', () => {
+    expect(resolveAdapterOptions({}).apiKey).toBeUndefined()
+  })
+
+  it('rejects a literal apiKey of whitespace only', () => {
+    expect(() => resolveAdapterOptions({ apiKey: '   ' }))
+      .toThrow(/apiKey is empty; omit it/)
+  })
+
+  it('rejects a literal apiKey no header can carry', () => {
+    expect(() => resolveAdapterOptions({ apiKey: 'sk-\u{1F600}' }))
+      .toThrow(/no HTTP header can carry/)
+  })
+
+  it('never echoes the key in the rejection', () => {
+    const secret = 'sk-\u{1F600}supersecret'
+    expect(() => resolveAdapterOptions({ apiKey: secret })).toThrow()
+    try {
+      resolveAdapterOptions({ apiKey: secret })
+    } catch (error) {
+      expect((error as Error).message).not.toContain('supersecret')
+    }
+  })
+})
diff --git a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
index 11df9e1d81..e593e3a61d 100644
--- a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
@@ -3,7 +3,7 @@ import { Context } from 'cordis'
 import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import LlmService from '@deepseek-ai/dsh-llm'
+import LlmService, { INVALID_CREDENTIAL_CODE } from '@deepseek-ai/dsh-llm'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import { CredentialsLocal } from '@deepseek-ai/dsh-credentials-local'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
@@ -103,6 +103,25 @@ describe('request-level dynamic configuration', () => {
     expect(server.headers[0]?.authorization).toBe('Bearer sk-arrived')
   })
 
+  it('rejects a stored credential no header can carry, never echoing it in the failure', async () => {
+    vi.stubEnv('DEEPSEEK_API_KEY', '')
+    const dir = await home()
+    const { ctx } = await boot(dir, { baseURL: 'http://127.0.0.1:1' })
+    const secret = 'sk-\u{1F600}supersecret'
+
+    // The real credentials seam (the path the web Models page writes through),
+    // not a hand-built stub: this package's own dynamic-config harness already
+    // boots one, and round-tripping the value through its actual store/read
+    // path is stronger evidence than a canned in-memory return would be.
+    await ctx.credentials.set(KEY_REF, secret)
+    const result = await prompt(ctx)
+    expect(result.finish).toMatchObject({ kind: 'error', failure: { code: INVALID_CREDENTIAL_CODE } })
+    if (result.finish.kind !== 'error') throw new Error('expected an error finish')
+    expect(result.finish.failure.message).not.toContain(secret)
+    expect(result.finish.failure.message).not.toContain('supersecret')
+    expect(result.finish.failure.message).not.toContain('ByteString')
+  })
+
   it('advertises a live settings catalog without re-registration', async () => {
     const dir = await home()
     const { ctx } = await boot(dir, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })

From b1660ab8a447c66ae9c3356bc60640b5cab3e10e Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 21:40:06 +0800
Subject: [PATCH 078/516] docs(llm-deepseek): document the invalid-credential
 refusal

---
 packages/llm/llm-deepseek/README.i18n.yaml | 4 ++--
 packages/llm/llm-deepseek/README.md        | 2 +-
 packages/llm/llm-deepseek/README.zh.md     | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/llm/llm-deepseek/README.i18n.yaml b/packages/llm/llm-deepseek/README.i18n.yaml
index 3eb54a7a9f..6daba653f8 100644
--- a/packages/llm/llm-deepseek/README.i18n.yaml
+++ b/packages/llm/llm-deepseek/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/llm/llm-deepseek/README.md
-README.md: 0cd265cadb2b2a619613761062ab2cef209bec83
-README.zh.md: 1883b054277adfd6c3d02b2a76ead9b3f8b0138f
+README.md: 51d5cf6a7049a2b1257ce3e9a284e777d3bdcdbc
+README.zh.md: cc059a6011f7dc1ee0ab93dbd822de4b540b7e66
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index 0cd265cadb..51d5cf6a70 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -53,7 +53,7 @@ The same exact-model result exposes ordered `off`, `high`, and `max` efforts und
 Connection facts are not frozen at load. `resolveAdapterOptions` is the one explicit resolve step from raw config to validated facts, and the adapter re-reads them through a thunk **once per operation**: base URL, catalog, request defaults, and idle budget all take effect on the next request, while an in-flight stream keeps the facts it started with. Two optional seams feed that thunk:
 
 - **`ctx.settings`** — the plugin registers the `llm-deepseek` namespace with this same `Config` schema and its `cordis.yml` entry as the composition `base`, so a `llm-deepseek:` section in the user settings document overrides any field without a restart. Without a mounted settings service the entry config alone drives the adapter, unchanged. A live settings snapshot that passes the schema but fails a beyond-schema bound (a duplicate catalog id, a broken thinking/effort pair) keeps the last good facts and logs the failure; the entry config itself still fails plugin load.
-- **`ctx.credentials`** — the API key resolves per stream call, from the *same* resolved snapshot that supplies the endpoint: a non-empty literal `apiKey` wins, then `apiKeyEnv` through the credential seam (`$DSH_HOME/.env` under the live environment), then — only without a mounted seam — the raw environment variable. Because credential facts travel with the connection facts, a settings snapshot the resolver rejects contributes neither its endpoint nor its key: the whole previous generation keeps serving. A request with no key anywhere fails with `MISSING_CREDENTIAL` naming every configuration entry point, while the route stays registered and the catalog stays browsable — first-run onboarding is "browse models, store the key, prompt again", with no restart between.
+- **`ctx.credentials`** — the API key resolves per stream call, from the *same* resolved snapshot that supplies the endpoint: a non-empty literal `apiKey` wins, then `apiKeyEnv` through the credential seam (`$DSH_HOME/.env` under the live environment), then — only without a mounted seam — the raw environment variable. Because credential facts travel with the connection facts, a settings snapshot the resolver rejects contributes neither its endpoint nor its key: the whole previous generation keeps serving. Every key is trimmed and format-checked before use — a literal `apiKey` at connection-facts resolution (plugin load, or the next settings snapshot), a stored or ambient value at request time — so a value no HTTP header can carry is refused there instead of surfacing as an opaque `fetch` `TypeError`; the request-time check throws `LlmError('INVALID_CREDENTIAL')` naming the failing entry point but never any part of the key. A request with no key anywhere fails with `MISSING_CREDENTIAL` naming every configuration entry point, while the route stays registered and the catalog stays browsable — first-run onboarding is "browse models, store the key, prompt again", with no restart between.
 
 The one registration-captured fact is the retry policy: when its resolved value changes, the plugin re-registers the route in place (same adapter instance, one synchronous section), so `ctx.llm.providerRetryPolicy('deepseek-official')` always reports the current policy.
 
diff --git a/packages/llm/llm-deepseek/README.zh.md b/packages/llm/llm-deepseek/README.zh.md
index 1883b05427..cc059a6011 100644
--- a/packages/llm/llm-deepseek/README.zh.md
+++ b/packages/llm/llm-deepseek/README.zh.md
@@ -53,7 +53,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
 连接事实不在加载时冻结。`resolveAdapterOptions` 是从原始配置到已校验事实的唯一显式 resolve 步骤，适配器经由一个 thunk **每操作重读一次**：base URL、catalog、请求默认值与 idle 预算都在下一次请求生效，进行中的流则保持其起始事实。两个可选 seam 供给该 thunk：
 
 - **`ctx.settings`**——插件用同一份 `Config` schema 注册 `llm-deepseek` namespace，并以其 `cordis.yml` 条目为组合 `base`，因此用户设置文档中的 `llm-deepseek:` 分节可以免重启覆盖任何字段。未挂载 settings 服务时，仅由 entry 配置驱动适配器，行为不变。存活 settings 快照若通过 schema 却违反 schema 之外的约束（重复的 catalog id、无法成立的 thinking／推理强度组合），则保留最后可用事实并记录失败；entry 配置本身仍会使插件加载失败。
-- **`ctx.credentials`**——API 密钥按每次 stream 调用解析，取自与端点*同一*份解析后的快照：非空的字面 `apiKey` 优先，其次经凭据 seam 解析 `apiKeyEnv`（活跃环境之下的 `$DSH_HOME/.env`），最后——仅在未挂载 seam 时——读取原始环境变量。由于凭据事实与连接事实同行，被 resolver 拒绝的 settings 快照既不贡献自己的端点，也不贡献自己的密钥：整个先前世代继续服务。任何地方都没有密钥的请求以 `MISSING_CREDENTIAL` 失败，并点名每个配置入口，同时路由保持注册、catalog 保持可浏览——首次运行的上手流程就是「浏览模型、存入密钥、再次发起提示」，中间无需任何重启。
+- **`ctx.credentials`**——API 密钥按每次 stream 调用解析，取自与端点*同一*份解析后的快照：非空的字面 `apiKey` 优先，其次经凭据 seam 解析 `apiKeyEnv`（活跃环境之下的 `$DSH_HOME/.env`），最后——仅在未挂载 seam 时——读取原始环境变量。由于凭据事实与连接事实同行，被 resolver 拒绝的 settings 快照既不贡献自己的端点，也不贡献自己的密钥：整个先前世代继续服务。每个密钥在使用前都会被去除首尾空白并校验格式——字面 `apiKey` 在连接事实解析时（插件加载或下一次 settings 快照）校验，已存储的值或环境变量值则在请求时校验——因此 HTTP 标头无法承载的值会在这一步被拒绝，而不是以语义不明的 `fetch` `TypeError` 形式浮现；请求时校验会抛出 `LlmError('INVALID_CREDENTIAL')`，点名失败的入口，但绝不透露密钥的任何部分。任何地方都没有密钥的请求以 `MISSING_CREDENTIAL` 失败，并点名每个配置入口，同时路由保持注册、catalog 保持可浏览——首次运行的上手流程就是「浏览模型、存入密钥、再次发起提示」，中间无需任何重启。
 
 唯一在注册期捕获的事实是重试策略：其解析值变化时，插件原地重新注册该路由（同一适配器实例、一个同步区段），因此 `ctx.llm.providerRetryPolicy('deepseek-official')` 始终报告当前策略。
 

From 48fd9b70ea99af5974314590a3d283fee2a5182e Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 21:43:40 +0800
Subject: [PATCH 079/516] docs: drop the notes for changes master now owns
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The profile-json entry and the personal composition layer were both
settled on master by its profile restructure — the first removed with
`app-cli-entry.ts`, the second deliberately restored as
`$DSH_HOME/cordis.patch.yml`. Neither is this branch's change any more,
so the notes claiming them go, and the prose they edited returns to
master's.
---
 ...tree-boot-and-transport-layering.i18n.yaml |  4 +--
 ...config-tree-boot-and-transport-layering.md |  4 +--
 ...fig-tree-boot-and-transport-layering.zh.md |  4 +--
 ...-08-04-remove-profile-json-entry.i18n.yaml |  6 ----
 .../2026-08-04-remove-profile-json-entry.md   | 32 -------------------
 ...2026-08-04-remove-profile-json-entry.zh.md | 32 -------------------
 6 files changed, 6 insertions(+), 76 deletions(-)
 delete mode 100644 .agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.i18n.yaml
 delete mode 100644 .agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md
 delete mode 100644 .agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
index a32146cbc6..2c1f309a79 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.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 .agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
-2026-07-24-web-config-tree-boot-and-transport-layering.md: e4dd8b50fe565deecb6e64d307305c66af50c001
-2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 17d0cf6c7169fd38f9b5abd0650ec2377eaf5865
+2026-07-24-web-config-tree-boot-and-transport-layering.md: 88f94b1f58ae7a3451c7772f4a9ff7d6564254c0
+2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 5f03dfbb8e5eaeeb52076584721e70ea66a292df
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
index e4dd8b50fe..88f94b1f58 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
@@ -16,7 +16,7 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)
 
 **Boot glue is a class pair.** `AppCLIEntry` (apps/cli) and `AppWebEntry` (the shell kernel) hold only what must exist independently of cordis: argv facts, the composed patch set, the parsed boot manifest, the module system instance, loading-page handles — everything else lives in plugins. `AppCLIEntry.run()` is three stages: layered env (ambient > cwd `.env` > `$DSH_HOME/.env`, closing the defect above) → patch composition → Loader include boot plus the activation audit. `AppWebEntry.run()` mirrors it browser-side: parse `window.__DSH_BOOT__` into a `BootManifest` (two views: npm-package rows for the module table, cordis-plugin rows for entry composition; malformed wire throws), build the module system, render the loading page, prefetch the `immediately` tier in parallel with Context/Loader setup, **await the prefetch before creating entries** (materialization is `tree.import`'s synchronous require, unprotected by fiber inject waiting; cross-package require edges such as i18n → runtime/client need every immediately-tier factory registered first — an empirically found 10–25% boot race otherwise), adopt the modules entry, create the graph rows, settle, sweep.
 
-**Config sources have one declaration place each.** yml static values are engineering defaults; CLI flags map onto the `webserver` row; env values enter through yml `!!js` expressions. This decision also introduced a profile json (`./.dsh-tmp-profile/config.json`) as the user-config source, mapped through a static `PROFILE_MAPPINGS` table onto target rows; it never gained a writer and is [now removed](../simplification/2026-08-04-remove-profile-json-entry.md), leaving flags and the assembly fact below as the only patch sources. Patches replace a row's config wholesale, so the entry class re-reads the yml row's static values (bypass parse) and merges overrides on top. The resolved frontend `distIndex` rides the same patch channel — an assembly fact, not user config.
+**Config sources have one declaration place each.** yml static values are engineering defaults; the profile json (`./.dsh-tmp-profile/config.json`, read-only, never created, cwd-anchored until the `$DSH_HOME` migration) is user config mapped through a static `PROFILE_MAPPINGS` table onto target rows (`provider`/`model` → the `api-gateway` row, `persistenceRoot` → the jsonl row); CLI flags map onto the `webserver` row with a field set disjoint from the json's; env values enter through yml `!!js` expressions, never through the mapping table. Patches replace a row's config wholesale, so the entry class re-reads the yml row's static values (bypass parse) and merges overrides on top. An unmapped json key fails loud. The resolved frontend `distIndex` rides the same patch channel — an assembly fact, not user config.
 
 **The transport splits five ways.** `dsh-host-apiproxy` upgraded to the gateway plugin (`api-gateway` row): default-exports `ApiProxyService`, config `{provider, model}`, provides `ctx.apiProxy`, transport-agnostic and registers no routes — `createApiProxy` moved here from the retired runtime package. `dsh-host-webserver` shrank to a plain route-registration plugin: `HttpServerService` provides `ctx.httpServer` (`register(route) → disposer` with duplicate-pattern throw, `tapIndex` transforms applied in registration order, `port`), listens on activation, per-request failures answer 400 and log without exiting, and knows no harness concepts. The connection node half owns the binding: it injects both services and registers `toFetchHandler(ctx.apiProxy)` under the `/api` prefix — future IPC carriers swap connection's transport while the gateway stays untouched. The modules node half (`ClientModuleHostService`, providing `ctx.clientModuleHost`) owns the graph: incremental per-package scanning (no full-rescan code path — `internal/plugin` marks the fiber's entry name dirty, a flush reconciles each name against live entries, package metadata including negative verdicts is cached forever, re-hashing is reachable only through `rebuilt(id)`), the bundle route, the index tap, and `onRebuilt`/`onGraphChanged` notification. The hmr node half owns dev reload: `fs.watchFile` stat-polling driven by `onGraphChanged` membership, and the `/plugins/events` SSE route.
 
@@ -25,7 +25,7 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)
 ## Consequences
 
 - Recomposing a web deployment is a yml/patch edit; the retired pieces (`mountWebPlugins`, `CLIENT_PACKAGES`, `createHostWebPluginRegistry`, `startWebServer`, the webserver's graph/SSE/api knowledge) are deleted.
-- Headless boots the same composition through the same entry (landed in the stacked follow-up): port 0 is its only surface difference, the model face gains `ask_user_question`/workspace context/model titles per the unification ruling, and `bootHost`/`startHost` retired with the `dsh-host-runtime` package. IPC carriers remain a recorded deferral; the profile write path and the `$DSH_HOME` profile relocation were dropped with the profile json itself.
+- Headless boots the same composition through the same entry (landed in the stacked follow-up): port 0 is its only surface difference, the model face gains `ask_user_question`/workspace context/model titles per the unification ruling, and `bootHost`/`startHost` retired with the `dsh-host-runtime` package. The profile write path, the `$DSH_HOME` profile relocation, and IPC carriers remain recorded deferrals.
 - A TypeScript pitfall worth remembering: a `declare module 'cordis'` augmentation in a file with **no cordis import** is demoted to a standalone module declaration and silently shatters the program-wide `Context` merge (`ctx.on`/`ctx.effect` vanish across the program). Anchor with `import type {} from 'cordis'`.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
index 17d0cf6c71..5f03dfbb8e 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 **boot 胶水由两个类组成。** `AppCLIEntry`（apps/cli）与 `AppWebEntry`（壳内核）只持有那些必须独立于 cordis、提前存在的东西：argv 事实、合成的 patch 集、解析出的 boot manifest（元数据清单）、模块系统实例、loading 页句柄——其余一律进插件。`AppCLIEntry.run()` 三段：分层 env（ambient > cwd `.env` > `$DSH_HOME/.env`，顺手关掉上述缺陷）→ patch 合成 → Loader include boot 加 activation audit。`AppWebEntry.run()` 在浏览器侧镜像它：把 `window.__DSH_BOOT__` 解析成 `BootManifest`（双视角：npm 包行给模块表、cordis 插件行给 entry 组合；畸形 wire 大声抛）、建模块系统、渲染 loading 页、immediately 层预取与 Context/Loader 准备并行、**create entry 之前等预取齐**（物化是 `tree.import` 的同步 require，不受 fiber inject 等待保护；i18n → runtime/client 这类跨包 require 边要求 immediately 层工厂全部注册完——否则有实测 10–25% 的 boot 竞态）、收编 modules entry、逐一创建图行、settle、sweep。
 
-**每个配置源有唯一声明位置。** yml 静态值是工程默认；CLI（命令行界面）flags 映射到 `webserver` 行；env 值经 yml `!!js` 表达式进入。本决策当时还引入了 profile json（`./.dsh-tmp-profile/config.json`）作为用户配置源，经静态 `PROFILE_MAPPINGS` 表映射到目标行；它始终没有获得写入方，[现已删除](../simplification/2026-08-04-remove-profile-json-entry.md)，patch 来源只剩 flags 与下述装配事实。patch 整体替换行 config，故 entry 类旁路 parse 重读 yml 行静态值再叠加覆盖。解析出的前端 `distIndex` 走同一 patch 通道——装配事实，不是用户配置。
+**每个配置源有唯一声明位置。** yml 静态值是工程默认；profile json（`./.dsh-tmp-profile/config.json`，只读、绝不创建、暂锚 cwd 直至 `$DSH_HOME` 迁移）是用户配置，经静态 `PROFILE_MAPPINGS` 表映射到目标行（`provider`/`model` → `api-gateway` 行，`persistenceRoot` → jsonl 行）；CLI（命令行界面）flags 映射到 `webserver` 行、字段集与 json 不相交；env 值经 yml `!!js` 表达式进入，绝不进映射表。patch 整体替换行 config，故 entry 类旁路 parse 重读 yml 行静态值再叠加覆盖。未映射的 json 键 fail loud。解析出的前端 `distIndex` 走同一 patch 通道——装配事实，不是用户配置。
 
 **传输五分。** `dsh-host-apiproxy` 升格网关插件（`api-gateway` 行）：默认导出 `ApiProxyService`，config `{provider, model}`，provide `ctx.apiProxy`，传输无关、不注册路由——`createApiProxy` 从已退役的运行时包迁入。`dsh-host-webserver` 缩成朴素路由注册插件：`HttpServerService` provide `ctx.httpServer`（`register(route) → disposer`、重复 pattern 即抛、`tapIndex` 按注册序应用、`port`），激活即 listen，单请求失败答 400 并记日志，不退出进程，不认识任何 harness 概念。connection node 半拥有绑定：inject 两个服务，把 `toFetchHandler(ctx.apiProxy)` 注册在 `/api` 前缀下——将来 IPC 载体只换 connection 的传输，网关零改动。modules node 半（`ClientModuleHostService`，provide `ctx.clientModuleHost`）拥有图：单包增量扫描（无全量重扫路径——`internal/plugin` 把 fiber 的 entry 名标脏，flush 逐名对账 live entries，包括否定结论在内的包元数据会永久缓存，重哈希唯一入口 `rebuilt(id)`）、bundle 路由、index tap、`onRebuilt`/`onGraphChanged` 通知。HMR node 半拥有开发期重载：`fs.watchFile` stat 轮询、watch 集合跟随 `onGraphChanged`、`/plugins/events` SSE 路由。
 
@@ -25,7 +25,7 @@ Status: implemented
 ## 后果
 
 - 重组一个 web 部署 = 改 yml/patch；退役件（`mountWebPlugins`、`CLIENT_PACKAGES`、`createHostWebPluginRegistry`、`startWebServer`、webserver 的图/SSE/api 知识）全部删除。
-- headless 已在 stacked 后续轮迁入同一组合同一入口：唯一面差异是 port 0，模型面按统一裁决获得 `ask_user_question`/workspace context/模型标题，`bootHost`/`startHost` 随 `dsh-host-runtime` 包退役。IPC 载体仍为挂账项；profile 写入路径与 profile 迁 `$DSH_HOME` 已随 profile json 本身一并放弃。
+- headless 已在 stacked 后续轮迁入同一组合同一入口：唯一面差异是 port 0，模型面按统一裁决获得 `ask_user_question`/workspace context/模型标题，`bootHost`/`startHost` 随 `dsh-host-runtime` 包退役。profile 写入路径、profile 迁 `$DSH_HOME`、IPC 载体仍为挂账项。
 - 一个值得记住的 TypeScript 坑：`declare module 'cordis'` augmentation 所在文件若**没有任何 cordis import**，会被降级成独立 module declaration，无声打散全程序的 `Context` merge（`ctx.on`/`ctx.effect` 全程序消失）。用 `import type {} from 'cordis'` 锚定。
 
 ## 考虑过的替代方案
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.i18n.yaml
deleted file mode 100644
index 5059240ce9..0000000000
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-08-04-remove-profile-json-entry.md
-2026-08-04-remove-profile-json-entry.md: 90d90adc8c4a6828f3ce49253150d09527a8304a
-2026-08-04-remove-profile-json-entry.zh.md: 60646a0ffc76ec967fef57f54ff0865b3c842754
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md
deleted file mode 100644
index 90d90adc8c..0000000000
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Agent Note: Removing the profile-json config entry
-
-Status: implemented
-
-English | [中文](2026-08-04-remove-profile-json-entry.zh.md)
-
-## Problem
-
-`./.dsh-tmp-profile/config.json` was the user-configuration plane of the [web config-tree boot](../architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md): a read-only JSON object under the invoking directory, mapped by a static `PROFILE_MAPPINGS` table onto three fields across two rows. Its write path and its relocation to the Harness home were recorded there as deferrals, and neither arrived. Nothing in the product ever created or edited the file, no test exercised it, and no user documentation named it — the format existed only as a reader.
-
-Meanwhile the fields it mapped acquired owners elsewhere. `provider` and `model` are the api-gateway's default route for created and resumed agents, which a session's own picker overrides per agent; `persistenceRoot` is an assembly fact of the shipped composition. Typed user preferences became `$DSH_HOME/settings.yaml` under the [user-settings seam](../architecture/2026-07-28-user-settings-seam.md). What remained was a third user-configuration format, anchored to the invoking directory and behind a hand-maintained mapping table, that nothing wrote.
-
-## Decision
-
-`PROFILE_DIR`, `PROFILE_FILE`, `ProfileMapping`, `PROFILE_MAPPINGS`, and `readProfile()` are deleted along with the patch source that consumed them. `AppCLIEntry` composes its patches from CLI flags and the resolved frontend `distIndex` only; the layers around it — shipped base, surface overlay, and the `--config` overlay — are unchanged.
-
-A `.dsh-tmp-profile/config.json` on disk is now ignored completely. There is no migration, no replacement format, and no deprecation diagnostic: the file never had a producer, so there is no installed base to carry forward, and the [pre-release stance](../../../../AGENTS.md) rejects compatibility shims.
-
-## Alternatives considered
-
-**Keep the reader until typed settings own `provider`/`model`.** Rejected because the gap is not real: with no writer, the file gave users no way to pin a default route either, so keeping it preserves an unproduced format rather than a capability.
-
-**Relocate it to `$DSH_HOME`, the deferral the original note recorded.** Rejected because that deferral assumed the write path would arrive with it. Moving a file nothing writes only moves the dead entry, and the Harness home already has an owner for typed user preferences.
-
-**Report the file through a deprecation diagnostic when it exists.** Rejected because a diagnostic for a format the product never produced would advertise it to users who have never seen it.
-
-## Consequences
-
-- Given up: no file-based way to pin `provider`, `model`, or `persistenceRoot` without editing yml or passing `--config`. A persistent default route needs a typed settings namespace owned by whoever creates sessions; `persistenceRoot` stays an assembly fact.
-- Bought: one fewer user-configuration format, one less input anchored to the invoking directory, and a patch composition whose only remaining sources are CLI flags and an assembly fact — the fail-loud mapping table goes with it.
-- The [web config-tree boot note](../architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md) is only partially superseded: its composition, boot-glue, transport, and export decisions stand. Both notes stay cross-linked, and its profile facts were rewritten in place.
-- Absence is verified by repo-wide search: `.dsh-tmp-profile`, `PROFILE_MAPPINGS`, and `readProfile` have no remaining match.
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md
deleted file mode 100644
index 60646a0ffc..0000000000
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-profile-json-entry.zh.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Agent Note: 删除 profile-json 配置入口
-
-Status: implemented
-
-[English](2026-08-04-remove-profile-json-entry.md) | 中文
-
-## Problem
-
-`./.dsh-tmp-profile/config.json` 曾是 [web 配置树启动](../architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md)的用户配置面：调用目录下的一个只读 JSON 对象，经静态 `PROFILE_MAPPINGS` 表映射到两个行上的三个字段。它的写路径以及迁往 Harness home 的计划都记在那条 Note 里作为延后项，两者都没有落地。产品中从未有任何代码创建或编辑该文件，没有测试覆盖它，也没有用户文档提到它——这个格式只存在读取方。
-
-与此同时，它映射的字段各自有了别处的归属。`provider` 与 `model` 是 api-gateway 为新建和恢复的 agent 提供的默认路由，会话自己的选择器可按 agent 覆盖它；`persistenceRoot` 是交付组合的装配事实。类型化的用户偏好则由 [user-settings seam](../architecture/2026-07-28-user-settings-seam.md) 下的 `$DSH_HOME/settings.yaml` 承接。剩下的只是第三个用户配置格式：锚定在调用目录、藏在一张手工维护的映射表后面，而且没有任何东西写它。
-
-## Decision
-
-`PROFILE_DIR`、`PROFILE_FILE`、`ProfileMapping`、`PROFILE_MAPPINGS` 和 `readProfile()` 连同消费它们的那个 patch 来源一并删除。`AppCLIEntry` 现在只从 CLI 标志和解析出的前端 `distIndex` 合成 patch；它周围的各层——交付基座、surface overlay、以及 `--config` overlay——保持不变。
-
-磁盘上的 `.dsh-tmp-profile/config.json` 现在被完全忽略。没有迁移、没有替代格式、也没有弃用诊断：该文件从来没有生产方，因此不存在需要承接的存量，而[未发布阶段的立场](../../../../AGENTS.md)拒绝兼容垫片。
-
-## Alternatives considered
-
-**保留读取方，直到类型化 settings 接管 `provider`/`model`。** 否决，因为这个缺口并不真实存在：既然没有写入方，该文件同样没有给用户任何钉住默认路由的途径，保留它保住的是一个无人生产的格式，而不是一项能力。
-
-**按原 Note 记录的延后项，把它迁到 `$DSH_HOME`。** 否决，因为那条延后项的前提是写路径会随之到来。搬动一个没人写的文件只是搬动了这个死入口，而 Harness home 已经有了类型化用户偏好的归属者。
-
-**文件存在时通过弃用诊断报告它。** 否决，因为为一个产品从未生产过的格式给出诊断，等于向从没见过它的用户宣传它。
-
-## Consequences
-
-- 放弃的：不再有基于文件、无需编辑 yml 或传 `--config` 就能钉住 `provider`、`model` 或 `persistenceRoot` 的途径。持久的默认路由需要一个由会话创建方拥有的类型化 settings namespace；`persistenceRoot` 仍是装配事实。
-- 换来的：少一个用户配置格式，少一个锚定在调用目录的输入，以及一处仅剩 CLI 标志与装配事实两个来源的 patch 合成——那张 fail-loud 映射表随之消失。
-- [web 配置树启动 Note](../architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md) 只被部分取代：它关于组合、启动胶水、传输与导出的决策仍然成立。两条 Note 保持互链，其中与 profile 相关的事实已就地改写。
-- 缺席由全仓搜索验证：`.dsh-tmp-profile`、`PROFILE_MAPPINGS` 与 `readProfile` 均无残留匹配。

From 45d78c92722155922a87e16a69d7bfe40d5c4eda Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 22:12:50 +0800
Subject: [PATCH 080/516] fix(llm-pi-ai): refuse an unusable API key before the
 header is built

---
 docs/config-catalog.md                        |  8 +++-
 packages/llm/llm-pi-ai/src/config.ts          | 23 ++++++++--
 packages/llm/llm-pi-ai/src/discovery.ts       | 26 ++++++++++-
 packages/llm/llm-pi-ai/src/index.ts           |  4 +-
 packages/llm/llm-pi-ai/tests/config.spec.ts   | 24 ++++++++++
 .../llm/llm-pi-ai/tests/discovery.spec.ts     | 45 ++++++++++++++++++-
 6 files changed, 119 insertions(+), 11 deletions(-)
 create mode 100644 packages/llm/llm-pi-ai/tests/config.spec.ts

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a3e63d994d..6c860cbd9d 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -704,7 +704,11 @@ export interface Config {
 
 /** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */
 export interface PiAiProviderProfile {
-  /** Literal provider credential; prefer {@link apiKeyEnv}. With both absent pi-ai uses its provider-native ambient discovery. */
+  /**
+   * Literal provider credential; prefer {@link apiKeyEnv}. With both absent pi-ai uses its
+   * provider-native ambient discovery. Trimmed and format-checked by {@link resolveProfiles}; a
+   * value no HTTP header can carry fails there rather than inside `fetch`.
+   */
   apiKey?: string
   /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */
   apiKeyEnv?: string
@@ -776,7 +780,7 @@ export interface PiAiModelProfile {
 
 Depends on: `CacheRetention` (`@earendil-works/pi-ai`) · `ModelThinkingLevel` (`@earendil-works/pi-ai`) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) · `ThinkingBudgets` (`@earendil-works/pi-ai`) · `Transport` (`@earendil-works/pi-ai`)
 
-Source: [`packages/llm/llm-pi-ai/src/config.ts:122`](../packages/llm/llm-pi-ai/src/config.ts)
+Source: [`packages/llm/llm-pi-ai/src/config.ts:126`](../packages/llm/llm-pi-ai/src/config.ts)
 
 ## `@deepseek-ai/dsh-llm-replay`
 
diff --git a/packages/llm/llm-pi-ai/src/config.ts b/packages/llm/llm-pi-ai/src/config.ts
index 7473dbb7ae..7e8374ab9f 100644
--- a/packages/llm/llm-pi-ai/src/config.ts
+++ b/packages/llm/llm-pi-ai/src/config.ts
@@ -19,7 +19,7 @@ import z from 'schemastery'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
-import { resolveRetryPolicy, RetryPolicySchema } from '@deepseek-ai/dsh-llm'
+import { normalizeApiKey, resolveRetryPolicy, RetryPolicySchema } from '@deepseek-ai/dsh-llm'
 import type { ResolvedRetryPolicy, RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
 import { resolveRouteModels } from './catalog.ts'
 import type { PiAiModelProfile } from './catalog.ts'
@@ -38,7 +38,11 @@ export type { PiAiModelProfile } from './catalog.ts'
 
 /** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */
 export interface PiAiProviderProfile {
-  /** Literal provider credential; prefer {@link apiKeyEnv}. With both absent pi-ai uses its provider-native ambient discovery. */
+  /**
+   * Literal provider credential; prefer {@link apiKeyEnv}. With both absent pi-ai uses its
+   * provider-native ambient discovery. Trimmed and format-checked by {@link resolveProfiles}; a
+   * value no HTTP header can carry fails there rather than inside `fetch`.
+   */
   apiKey?: string
   /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */
   apiKeyEnv?: string
@@ -220,8 +224,18 @@ export function resolveProfiles(
   for (const [provider, source] of entries) {
     rejectRemovedFields(provider, source)
     if (provider.length === 0) throw new Error('llm-pi-ai: provider names must be non-empty')
-    if (source.apiKey !== undefined && source.apiKey.trim().length === 0) {
-      throw new Error(`llm-pi-ai: provider "${provider}" has an empty apiKey; omit it to use ambient authentication`)
+    // Omission selects the installed provider's own auth — ambient discovery
+    // or OAuth — so only a supplied key is judged.
+    let apiKey: string | undefined
+    if (source.apiKey !== undefined) {
+      const checked = normalizeApiKey(source.apiKey)
+      if (!checked.ok) {
+        throw new Error(checked.reason === 'empty'
+          ? `llm-pi-ai: provider "${provider}" has an empty apiKey; omit it to use ambient authentication`
+          : `llm-pi-ai: provider "${provider}" has an apiKey containing characters no HTTP header can carry;`
+            + ' paste the raw key only')
+      }
+      apiKey = checked.value
     }
     if (source.baseURL !== undefined && source.baseURL.length === 0) {
       throw new Error(`llm-pi-ai: provider "${provider}" has an empty baseURL`)
@@ -252,6 +266,7 @@ export function resolveProfiles(
     const { apiKeyEnv, retryPolicy, models: _models, displayName: _displayName, ...rest } = source
     resolved.set(provider, {
       ...rest,
+      ...apiKey === undefined ? {} : { apiKey },
       provider,
       displayName,
       ...apiKeyEnv === undefined ? {} : { apiKeyEnv: credentialRef(apiKeyEnv) },
diff --git a/packages/llm/llm-pi-ai/src/discovery.ts b/packages/llm/llm-pi-ai/src/discovery.ts
index bff2c9a7ca..014c9c2f3e 100644
--- a/packages/llm/llm-pi-ai/src/discovery.ts
+++ b/packages/llm/llm-pi-ai/src/discovery.ts
@@ -22,7 +22,7 @@
  * @module dsh-llm-pi-ai/discovery
  */
 
-import { LlmError } from '@deepseek-ai/dsh-llm'
+import { INVALID_CREDENTIAL_CODE, LlmError, normalizeApiKey } from '@deepseek-ai/dsh-llm'
 import type { LlmDiscoveredModel, LlmModelDiscoveryRequest } from '@deepseek-ai/dsh-llm'
 import { attributionHeaders } from '@deepseek-ai/dsh-llm'
 import { catalogModels } from './catalog.ts'
@@ -161,6 +161,25 @@ function readListing(body: unknown): LlmDiscoveredModel[] {
   return models
 }
 
+/**
+ * Accept one probe key, or refuse it before the header is built. Without this
+ * the `fetch` below would throw a ByteString `TypeError` that this function's
+ * catch reports as `could not reach <url>` — blaming the network for a local,
+ * deterministic fault.
+ * @param raw - the key typed into the form or read from storage.
+ * @returns the trimmed, usable key.
+ */
+function usableProbeKey(raw: string): string {
+  const checked = normalizeApiKey(raw)
+  if (checked.ok) return checked.value
+  throw new LlmError(
+    checked.reason === 'empty'
+      ? 'this provider\'s API key is blank; enter it on the Models page, or clear it to probe unauthenticated'
+      : 'this provider\'s API key contains characters no HTTP header can carry; paste the raw key only',
+    INVALID_CREDENTIAL_CODE,
+  )
+}
+
 /**
  * Interrogate one draft provider endpoint for the models it advertises.
  * @param request - the endpoint, protocol, and one-shot credential to use.
@@ -216,7 +235,10 @@ export async function discoverModels(
   // stored one is only asked for here, past the catalog short-circuit and the
   // protocol check, so a route answered from the registry costs no credential
   // lookup — and no diagnostic about a credential it never needed.
-  const apiKey = request.apiKey ?? await storedApiKey?.()
+  // A probe carrying no key stays unauthenticated, which is how a route that
+  // relies on the provider's own ambient discovery is meant to be asked.
+  const supplied = request.apiKey ?? await storedApiKey?.()
+  const apiKey = supplied === undefined ? undefined : usableProbeKey(supplied)
   let response: Response
   try {
     response = await fetch(url, {
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index 0d058e94ac..c30fd3db6f 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -43,7 +43,7 @@
  */
 
 import type { Context } from 'cordis'
-import { LlmError } from '@deepseek-ai/dsh-llm'
+import { assertUsableApiKey, LlmError } from '@deepseek-ai/dsh-llm'
 import type { AdapterRegistrationHandle, DirectoryRegistrationHandle, LlmConfigurableProvider } from '@deepseek-ai/dsh-llm'
 import { deepEqualJson, installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { PiAiAdapter } from './adapter.ts'
@@ -145,7 +145,7 @@ export function apply(ctx: Context, config: Config): void {
       // Without the seam, read exactly the named variable so a plain
       // cordis.yml composition works from the environment alone.
       : process.env[ref]
-    if (hit !== undefined && hit.length > 0) return hit
+    if (hit !== undefined && hit.length > 0) return assertUsableApiKey(hit, 'llm-pi-ai', ref)
     throw new LlmError(
       `llm-pi-ai: no credential for provider route "${provider}"; its profile resolves ${ref}, which is not`
       + ` set — store ${ref} through the credentials service (the web Models page writes it) or export it,`
diff --git a/packages/llm/llm-pi-ai/tests/config.spec.ts b/packages/llm/llm-pi-ai/tests/config.spec.ts
new file mode 100644
index 0000000000..90f8487ad8
--- /dev/null
+++ b/packages/llm/llm-pi-ai/tests/config.spec.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { resolveProfiles } from '../src/config.ts'
+
+describe('API key format', () => {
+  it('trims a padded literal apiKey into the resolved profile', () => {
+    const resolved = resolveProfiles({ openai: { apiKey: '  sk-abc  ', baseURL: 'https://acme.test' } })
+    expect(resolved.get('openai')?.apiKey).toBe('sk-abc')
+  })
+
+  it('keeps an omitted apiKey absent so ambient authentication still applies', () => {
+    const resolved = resolveProfiles({ openai: { baseURL: 'https://acme.test' } })
+    expect(resolved.get('openai')?.apiKey).toBeUndefined()
+  })
+
+  it('still tells an empty apiKey to omit itself', () => {
+    expect(() => resolveProfiles({ openai: { apiKey: '   ', baseURL: 'https://acme.test' } }))
+      .toThrow(/omit it to use ambient authentication/)
+  })
+
+  it('rejects an apiKey no header can carry', () => {
+    expect(() => resolveProfiles({ openai: { apiKey: 'sk-\u{1F600}', baseURL: 'https://acme.test' } }))
+      .toThrow(/no HTTP header can carry/)
+  })
+})
diff --git a/packages/llm/llm-pi-ai/tests/discovery.spec.ts b/packages/llm/llm-pi-ai/tests/discovery.spec.ts
index 916700fbbf..63b43ecdab 100644
--- a/packages/llm/llm-pi-ai/tests/discovery.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/discovery.spec.ts
@@ -1,6 +1,6 @@
 import { createServer } from 'node:http'
 import type { IncomingMessage, Server, ServerResponse } from 'node:http'
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { userAgent } from '@deepseek-ai/dsh-llm'
 import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
@@ -12,6 +12,9 @@ const servers: Server[] = []
 const touchedEnv: string[] = []
 
 afterEach(async () => {
+  // A no-op when the test never stubbed `fetch`; only 'probe key format'
+  // below installs one.
+  vi.unstubAllGlobals()
   for (const name of touchedEnv.splice(0)) Reflect.deleteProperty(process.env, name)
   await Promise.all(servers.splice(0).map(server => new Promise(resolve => server.close(resolve))))
 })
@@ -311,3 +314,43 @@ describe('draft-provider model discovery', () => {
       .rejects.toMatchObject({ code: 'NO_DISCOVERY' })
   })
 })
+
+describe('probe key format', () => {
+  it('reports an illegal probe key as a credential fault, not an unreachable endpoint', async () => {
+    await expect(discoverModels({
+      baseURL: 'https://acme.test',
+      api: 'openai-completions',
+      apiKey: 'sk-\u{1F600}',
+    })).rejects.toMatchObject({ code: 'INVALID_CREDENTIAL' })
+  })
+
+  it('reports a blank probe key as a credential fault too', async () => {
+    // A cleared form field arrives as '', not an absent key; it must fail the
+    // same way a typed-in illegal key does, rather than probing unauthenticated.
+    await expect(discoverModels({
+      baseURL: 'https://acme.test',
+      api: 'openai-completions',
+      apiKey: '',
+    })).rejects.toMatchObject({ code: 'INVALID_CREDENTIAL' })
+  })
+
+  it('leaves a probe with no key unauthenticated', async () => {
+    // The file's other cases capture headers through a real local HTTP server
+    // (`listingServer`); this one has no route or stored key to resolve, so
+    // the smallest real double is a `fetch` stub, scoped to this test and
+    // unstubbed by the shared `afterEach` above.
+    const requests: RequestInit[] = []
+    vi.stubGlobal('fetch', async (_url: string | URL, init?: RequestInit) => {
+      requests.push(init ?? {})
+      return new Response(JSON.stringify({ data: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+    })
+
+    await discoverModels({ baseURL: 'https://acme.test', api: 'openai-completions' })
+
+    const headers = new Headers(requests[0]?.headers)
+    expect(headers.has('authorization')).toBe(false)
+  })
+})

From 665b5697bb46d87b85c832dec2689685f37edbd7 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 22:13:02 +0800
Subject: [PATCH 081/516] docs(llm-pi-ai): document the invalid-credential
 refusal

---
 packages/llm/llm-pi-ai/README.i18n.yaml | 4 ++--
 packages/llm/llm-pi-ai/README.md        | 4 ++--
 packages/llm/llm-pi-ai/README.zh.md     | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index b4e9cffabb..bd322be07f 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: af0e952dd8dbd9767b98229ee6b87262007d6738
-README.zh.md: f8a19999f08aa8a6963874d57bf74370797b951c
+README.md: 0dcf15d6caf365a1f8e75088cb363eaa6560a6ec
+README.zh.md: 79be5d320c0f4411f7cf8a0bd72c887048929dcb
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index af0e952dd8..0dcf15d6ca 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -67,7 +67,7 @@ Resolution still fails loud, naming the offending route and model, when a route
 
 The adapter reads its profiles through a thunk **once per operation** instead of freezing them at construction. The plugin registers the `llm-pi-ai` namespace on the optional `ctx.settings` seam with this same `Config` schema and its `cordis.yml` entry as the composition `base`, and because `providers` is a dict, the base and the user's `llm-pi-ai:` settings section merge **per provider**: a user can add a route, override one field of a composition route, or point a route at another proxy, all effective on the next request with no restart. Without a mounted settings service the entry config alone drives the adapter, unchanged.
 
-Credentials resolve per stream call: a non-empty literal `apiKey` wins, then `apiKeyEnv` through the optional `ctx.credentials` seam (`$DSH_HOME/.env` under the live environment; exactly that variable without a mounted seam). A profile naming no credential at all — and only that case — defers to pi-ai's ambient discovery. The route set and each route's captured retry policy are the registration-level facts: when either changes, the plugin replaces its registration atomically (same adapter instance, candidate set validated first), so a route another adapter already owns leaves the previous routes serving and reverting to a working configuration re-applies. Provider key order never counts as a change. A section this adapter could not serve is refused where it is written — the registered `validate` resolves the whole profile set, so `ctx.settings.mutate` rejects with the resolver's own error (the wire surface reports it as `settings-rejected`) and nothing is stored. A stored section that becomes unserviceable some other way — an external edit of `settings.yaml` — keeps the namespace's last good value at the settings seam and warns. The entry config itself still fails plugin load, and a route the llm registry refuses (one another adapter family already owns) is logged while the previously registered routes keep serving.
+Credentials resolve per stream call: a non-empty literal `apiKey` wins, then `apiKeyEnv` through the optional `ctx.credentials` seam (`$DSH_HOME/.env` under the live environment; exactly that variable without a mounted seam). A profile naming no credential at all — and only that case — defers to pi-ai's ambient discovery. Every key is trimmed and format-checked before use — a literal `apiKey` when profiles resolve (plugin load, or the next settings snapshot), a value `apiKeyEnv` resolves at request time — so a value no HTTP header can carry is refused there instead of surfacing as an opaque `fetch` `TypeError`; the request-time refusal throws `LlmError('INVALID_CREDENTIAL')` naming the failing route and credential reference but never any part of the key. The route set and each route's captured retry policy are the registration-level facts: when either changes, the plugin replaces its registration atomically (same adapter instance, candidate set validated first), so a route another adapter already owns leaves the previous routes serving and reverting to a working configuration re-applies. Provider key order never counts as a change. A section this adapter could not serve is refused where it is written — the registered `validate` resolves the whole profile set, so `ctx.settings.mutate` rejects with the resolver's own error (the wire surface reports it as `settings-rejected`) and nothing is stored. A stored section that becomes unserviceable some other way — an external edit of `settings.yaml` — keeps the namespace's last good value at the settings seam and warns. The entry config itself still fails plugin load, and a route the llm registry refuses (one another adapter family already owns) is logged while the previously registered routes keep serving.
 
 The adapter exposes each configured route's models through `ctx.llm.listModels(provider)`. This is provider-neutral selector metadata read from the same pi-ai `Models` collection the request path uses, so discovery does not create a second model registry. `ctx.llm.resolveModelInfo(provider, model)` performs that exact descriptor lookup once and returns its identity, context window, configured output cap, and selectable thinking levels, keeping authoritative metadata on the route-owning adapter rather than its consumers. A model's **configured** `maxTokens` becomes the seam's `defaultMaxTokens`, so a request that names no output cap carries the one the deployment chose; a value inherited from the installed catalog is the model's output *capability* and never becomes a request default on its own.
 
@@ -85,7 +85,7 @@ The plugin offers `ctx.llm.registerModelDiscovery('llm-pi-ai', …)`, which answ
 
 A request naming a route the **installed catalog ships is answered from that catalog**, with no network call: pi-ai's registry is the authoritative list for its own providers, and it carries the context windows and output caps a listing endpoint would not disclose. Such a route needs no `baseURL` at all. Only a route the catalog does not describe — a gateway, a self-hosted server — is interrogated over the wire, and one that names no endpoint is told to set one or enter its models by hand.
 
-A draft carries the credential the user typed, if any; a route that already stored one shows a configuration surface only a redacted descriptor, so the interrogation supplies that route's own credential — resolved exactly as a request to it would, `apiKey` then `apiKeyEnv` — rather than going out unauthenticated and reporting the endpoint's 401 as a wrong key. A typed key wins, being the one under test. Resolution happens only on the path that reaches the network, so a catalog route answers without touching credentials at all.
+A draft carries the credential the user typed, if any; a route that already stored one shows a configuration surface only a redacted descriptor, so the interrogation supplies that route's own credential — resolved exactly as a request to it would, `apiKey` then `apiKeyEnv` — rather than going out unauthenticated and reporting the endpoint's 401 as a wrong key. A typed key wins, being the one under test. Resolution happens only on the path that reaches the network, so a catalog route answers without touching credentials at all. A supplied or stored probe key is trimmed and format-checked the same way, so a value no HTTP header can carry is refused immediately as `LlmError('INVALID_CREDENTIAL')` instead of reaching `fetch`, where it would surface as an opaque `ByteString` failure indistinguishable from an unreachable endpoint.
 
 Interrogation reads `openai-completions` and `openai-responses`, whose `GET /models` shape with bearer auth is the one a gateway, a self-hosted server, and the official endpoints all agree on. Azure is excluded despite its OpenAI lineage — it authenticates with an `api-key` header and requires an `api-version` query — and Codex uses OAuth; every other protocol answers `DISCOVERY_UNSUPPORTED` so the surface falls back to hand-entry instead of an authentication failure being reported as a provider with no models. The `baseURL` is treated as a prefix rather than a URL to resolve against, so a deployment path such as `https://gateway.example/openai/v1` keeps its segments.
 
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index f8a19999f0..79be5d320c 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -67,7 +67,7 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 适配器经由一个 thunk **每操作读取一次** profile，而非在构造期冻结。插件在可选的 `ctx.settings` seam 上用同一份 `Config` schema 注册 `llm-pi-ai` namespace，并以其 `cordis.yml` 条目为组合 `base`；由于 `providers` 是字典，base 与用户的 `llm-pi-ai:` settings 分节**按提供方**合并：用户可以新增路由、覆盖组合路由的单个字段，或把路由指向另一个 proxy，全部在下一次请求生效，无需重启。未挂载 settings 服务时，仅由 entry 配置驱动适配器，行为不变。
 
-凭据按每次 stream 调用解析：非空的字面 `apiKey` 优先，其次经可选的 `ctx.credentials` seam 解析 `apiKeyEnv`（活跃环境之下的 `$DSH_HOME/.env`；未挂载 seam 时恰好读取该环境变量）。只有完全没有点名任何凭据的 profile——仅限这一种情况——才交给 pi-ai 的环境发现。路由集合与每条路由捕获的重试策略是注册级事实：两者任一变化时，插件都会原子地替换自己的注册（同一适配器实例，候选集合先经校验），因此某条路由若已被另一适配器占有，先前的路由会继续服务，而改回可用配置时注册会重新生效。提供方键的顺序绝不算作变化。本适配器无法服务的分节会在写入处被拒——注册的 `validate` 会解析整份 profile 集合，因此 `ctx.settings.mutate` 以 resolver 自身的错误拒绝（协议面将其报为 `settings-rejected`），什么都不会存储。已存储分节若因其他途径变得不可服务——比如外部编辑了 `settings.yaml`——则由 settings seam 保留该 namespace 最后可用的值并告警。entry 配置本身仍会使插件加载失败；而 llm 注册表拒绝的路由（已被另一适配器族占有的那种）会被记录下来，先前注册的路由继续服务。
+凭据按每次 stream 调用解析：非空的字面 `apiKey` 优先，其次经可选的 `ctx.credentials` seam 解析 `apiKeyEnv`（活跃环境之下的 `$DSH_HOME/.env`；未挂载 seam 时恰好读取该环境变量）。只有完全没有点名任何凭据的 profile——仅限这一种情况——才交给 pi-ai 的环境发现。每个密钥在使用前都会被去除首尾空白并校验格式——字面 `apiKey` 在 profile 解析时（插件加载，或下一次 settings 快照）校验，`apiKeyEnv` 解析出的值则在请求时校验——因此 HTTP 标头无法承载的值会在这一步被拒绝，而不是以语义不明的 `fetch` `TypeError` 形式浮现；请求时的拒绝会抛出 `LlmError('INVALID_CREDENTIAL')`，点名失败的路由与凭据引用，但绝不透露密钥的任何部分。路由集合与每条路由捕获的重试策略是注册级事实：两者任一变化时，插件都会原子地替换自己的注册（同一适配器实例，候选集合先经校验），因此某条路由若已被另一适配器占有，先前的路由会继续服务，而改回可用配置时注册会重新生效。提供方键的顺序绝不算作变化。本适配器无法服务的分节会在写入处被拒——注册的 `validate` 会解析整份 profile 集合，因此 `ctx.settings.mutate` 以 resolver 自身的错误拒绝（协议面将其报为 `settings-rejected`），什么都不会存储。已存储分节若因其他途径变得不可服务——比如外部编辑了 `settings.yaml`——则由 settings seam 保留该 namespace 最后可用的值并告警。entry 配置本身仍会使插件加载失败；而 llm 注册表拒绝的路由（已被另一适配器族占有的那种）会被记录下来，先前注册的路由继续服务。
 
 适配器通过 `ctx.llm.listModels(provider)` 公开每条已配置路由的模型。这是从请求路径所用的同一个 pi-ai `Models` 集合读取的提供方无关 selector 元数据，因此发现不会创建第二个模型注册表。`ctx.llm.resolveModelInfo(provider, model)` 会执行一次精确 descriptor 查找，并返回其身份、上下文窗口、已配置输出上限和可选思考级别，让权威元数据保留在拥有路由的适配器上，而非消费方。模型**已配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`，因此未点名输出上限的请求会携带部署选定的那一个；而从已安装 catalog 继承来的值是模型的输出**能力**，绝不会自行变成请求默认值。
 
@@ -85,7 +85,7 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 点名了**已安装 catalog 所提供路由**的请求，直接由该 catalog 作答，完全不联网：pi-ai 的注册表才是它自家提供方的权威列表，且携带列表端点不会公布的上下文窗口与输出上限。这类路由根本不需要 `baseURL`。只有 catalog 未描述的路由——网关、自建服务——才会经协议层询问；若它也没给端点，则会被告知去设置一个或手工填写模型。
 
-草稿携带的是用户当下键入的凭据（如果有）；已经存好凭据的路由，在配置界面上只呈现一个脱敏描述符，因此询问会自行取用该路由的凭据——解析方式与向它发请求时完全一致，先 `apiKey` 后 `apiKeyEnv`——而不是不带认证发出去、再把端点的 401 报成密钥不对。键入的密钥优先，因为那正是被测试的那一把。解析只发生在真正要联网的路径上，因此 catalog 路由作答时完全不会触碰凭据。
+草稿携带的是用户当下键入的凭据（如果有）；已经存好凭据的路由，在配置界面上只呈现一个脱敏描述符，因此询问会自行取用该路由的凭据——解析方式与向它发请求时完全一致，先 `apiKey` 后 `apiKeyEnv`——而不是不带认证发出去、再把端点的 401 报成密钥不对。键入的密钥优先，因为那正是被测试的那一把。解析只发生在真正要联网的路径上，因此 catalog 路由作答时完全不会触碰凭据。用户提供或已存储的探测密钥也会经过同样的去除空白与格式校验：HTTP 标头无法承载的值会被立即以 `LlmError('INVALID_CREDENTIAL')` 拒绝，而不会传到 `fetch`——否则会呈现为一个和端点不可达难以区分的、语义不明的 `ByteString` 失败。
 
 询问只读 `openai-completions` 与 `openai-responses`，它们「`GET /models` + bearer 认证」的形状是网关、自建服务与官方端点三方一致认可的那一种。Azure 尽管出身 OpenAI 也被排除——它用 `api-key` 标头认证并要求 `api-version` 查询参数——Codex 则走 OAuth；其余协议一律以 `DISCOVERY_UNSUPPORTED` 回答，让界面回退到手工填写，而不是把认证失败报成一个没有模型的提供方。`baseURL` 按前缀而非待解析 URL 处理，因此 `https://gateway.example/openai/v1` 这类部署路径会保留其路径段。
 

From cf9eade39d5019ccbbd90e0f1a969274074ea691 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 22:30:43 +0800
Subject: [PATCH 082/516] feat(web): refuse an unusable API key on the field
 that holds it

---
 .../src/client/CustomProviderCard.tsx         |  14 ++-
 .../ui-models/src/client/ProviderEditor.tsx   |  19 +++-
 .../client/ui-models/src/client/apiKey.ts     |  50 +++++++++
 .../client/ui-models/src/client/locales.ts    |   6 ++
 .../ui-models/tests/components.spec.tsx       |  50 +++++++++
 .../ui-models/tests/provider-form.spec.tsx    | 102 ++++++++++++++++++
 6 files changed, 233 insertions(+), 8 deletions(-)
 create mode 100644 packages/client/ui-models/src/client/apiKey.ts

diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index b4c655472a..a252d99586 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -18,6 +18,7 @@
 import { useState } from 'react'
 import type { ReactNode } from 'react'
 import type { IApiClient } from '@deepseek-ai/dsh-client-connection/client'
+import { apiKeyFailure } from './apiKey.ts'
 import { EditorFooter } from './EditorFooter.tsx'
 import { validateDeepSeekModels } from './DeepSeekModelsEditor.tsx'
 import { ModelListEditor } from './ModelListEditor.tsx'
@@ -80,8 +81,14 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
   // bad row is named by its position here too. Capacities have route-level
   // fallbacks; what a route cannot default is at least one model.
   const modelFailure = validateDeepSeekModels(models)
+  const keyFailure = apiKeyFailure(keyDraft)
+  // The typed key with paste whitespace removed. A blank field yields an empty
+  // string, which the create path reads as "no key supplied" — a route may
+  // legitimately authenticate through the provider's own ambient discovery.
+  const keyValue = keyDraft.trim()
   const ready = route.length > 0 && !routeInvalid && !routeTaken
     && baseURL.length > 0 && models.length > 0 && modelFailure === undefined
+    && keyFailure === undefined
   // The one blocked gate worth a line under the form. The route id is omitted
   // because its own field already explains itself, and a satisfied card says
   // nothing at all rather than printing an empty paragraph.
@@ -112,8 +119,8 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
       expectedRevision: openedAt,
     })
     if (!response.result.ok) return response.result.error.message
-    if (keyDraft.length > 0) {
-      const stored = await api.credentials.set({ ref: keyRef, value: keyDraft })
+    if (keyValue.length > 0) {
+      const stored = await api.credentials.set({ ref: keyRef, value: keyValue })
       // The profile landed; saying the key did not is the only honest report,
       // and the row is now editable so the key can be entered again there.
       if (!stored.result.ok) return stored.result.error.message
@@ -208,6 +215,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           disabled={disabled}
           onChange={(event) => { setKeyDraft(event.target.value) }}
         />
+        {keyFailure === undefined ? null : <p className={styles['error']}>{t(keyFailure)}</p>}
       </div>
       <ModelListEditor
         models={models}
@@ -216,7 +224,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           settingsNs: NS,
           baseURL,
           api: protocol,
-          ...keyDraft.length === 0 ? {} : { apiKey: keyDraft },
+          ...keyValue.length === 0 ? {} : { apiKey: keyValue },
         }}
         api={api}
         t={t}
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx
index f48572cc58..f33791eab5 100644
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -22,6 +22,7 @@ import {
 import {
   DeepSeekModelsEditor, modelDrafts, validateDeepSeekModels,
 } from './DeepSeekModelsEditor.tsx'
+import { apiKeyFailure } from './apiKey.ts'
 import { EditorFooter } from './EditorFooter.tsx'
 import { ModelListEditor } from './ModelListEditor.tsx'
 import { deriveKeyRef, messageOf } from './store.ts'
@@ -163,7 +164,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
 
   const stringAt = (source: unknown, key: string): string | undefined => {
     const value = getPath(source, [key])
-    return typeof value === 'string' && value.length > 0 ? value : undefined
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined
   }
   const setField = (key: string, next: string | undefined): void => {
     setDraft(current => next === undefined ? deletePath(current, [key]) : setPath(current, [key], next))
@@ -172,6 +173,12 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
   // The model list is validated by the same per-row checker for both families,
   // so a bad row is named by its position rather than by a blanket message.
   const modelFailure = validateDeepSeekModels(getPath(draft, ['models']))
+  const keyFailure = apiKeyFailure(keyDraft)
+  // What a probe or a write must carry: the typed key with paste whitespace
+  // removed. A blank field yields an empty string, which both call sites read
+  // as "no key supplied" rather than as a key — that is how a card whose
+  // provider already has a stored key is edited without re-entering it.
+  const keyValue = keyDraft.trim()
   // What the form currently shows, which is what an interrogation must ask:
   // an edited-but-unsaved endpoint, and a key typed but not yet stored.
   const probeApi = stringAt(draft, 'api') ?? stringAt(fallback, 'api')
@@ -183,7 +190,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
     provider: props.provider,
     ...probeBaseURL === undefined ? {} : { baseURL: probeBaseURL },
     ...probeApi === undefined ? {} : { api: probeApi },
-    ...keyDraft.length === 0 ? {} : { apiKey: keyDraft },
+    ...keyValue.length === 0 ? {} : { apiKey: keyValue },
   }
   /**
    * The write for this card, or a failure message. Every edit travels as
@@ -226,8 +233,8 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
           : response.result.error.message
       }
     }
-    if (keyDraft.length > 0) {
-      const stored = await api.credentials.set({ ref: keyRef, value: keyDraft })
+    if (keyValue.length > 0) {
+      const stored = await api.credentials.set({ ref: keyRef, value: keyValue })
       if (!stored.result.ok) return stored.result.error.message
     }
     setKeyDraft('')
@@ -313,6 +320,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
             disabled={disabled || keyLocked}
             onChange={(event) => { setKeyDraft(event.target.value) }}
           />
+          {keyFailure === undefined ? null : <p className={styles['error']}>{t(keyFailure)}</p>}
         </div>
         <details className={styles['customized']}>
           <summary className={styles['customizedSummary']}>{t('customized')}</summary>
@@ -396,7 +404,8 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
       <EditorFooter
         t={t}
         busy={busy}
-        submitDisabled={disabled || layout === 'unknown' || modelFailure !== undefined}
+        submitDisabled={disabled || layout === 'unknown' || modelFailure !== undefined
+          || keyFailure !== undefined}
         submitLabel="apply"
         submitBusyLabel="applying"
         onCancel={() => { props.onClose(false) }}
diff --git a/packages/client/ui-models/src/client/apiKey.ts b/packages/client/ui-models/src/client/apiKey.ts
new file mode 100644
index 0000000000..a9d5bb3d32
--- /dev/null
+++ b/packages/client/ui-models/src/client/apiKey.ts
@@ -0,0 +1,50 @@
+/**
+ * Browser-side judgement of a typed API key.
+ * @module @deepseek-ai/dsh-client-ui-models/apiKey
+ */
+
+/**
+ * Twin of `normalizeApiKey` in `@deepseek-ai/dsh-llm`: printable ASCII, space
+ * excluded. Client packages reference only client packages, so the charset
+ * rule is mirrored here rather than imported; keep the two in step, as
+ * `validateDeepSeekModels` is kept in step with the host's `catalogModel`.
+ */
+const LEGAL_API_KEY = /^[\x21-\x7E]+$/
+
+/**
+ * A pasted `NAME=value` environment line. Restricted to an upper-case
+ * identifier so a real key cannot match: `sk-` forms break at the hyphen.
+ * This heuristic runs only here — a resolver applying it could lock a user
+ * out of a gateway whose key legitimately takes this shape, with the
+ * environment refusing it too and no way through.
+ */
+const ENV_LINE = /^[A-Z][A-Z0-9_]*=/
+
+/** Copy key naming why a typed key cannot be saved. */
+export type ApiKeyFailureKey = 'keyBlank' | 'keyIllegalCharacters' | 'keyLooksWrapped'
+
+/** Whether a value is wrapped in one matching pair of quotes. */
+function isQuoted(value: string): boolean {
+  const first = value[0]
+  if (first !== '"' && first !== '\'' && first !== '`') return false
+  return value.length > 1 && value.endsWith(first)
+}
+
+/**
+ * Judge the key input's current value.
+ *
+ * An empty field is not a failure: every card opens with it empty even when a
+ * key is already stored, where it means keep that one. A field holding only
+ * whitespace is a failure rather than an empty field, so typed input is never
+ * silently discarded.
+ * @param draft - the key input's current value, untrimmed.
+ * @returns the copy key for a field-level failure, or `undefined` to allow submit.
+ */
+export function apiKeyFailure(draft: string): ApiKeyFailureKey | undefined {
+  if (draft.length === 0) return undefined
+  const value = draft.trim()
+  if (value.length === 0) return 'keyBlank'
+  if (ENV_LINE.test(value) || isQuoted(value)) return 'keyLooksWrapped'
+  if (!LEGAL_API_KEY.test(value)) return 'keyIllegalCharacters'
+  return undefined
+}
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index 19463d98fa..fbfc85c7f1 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -46,6 +46,9 @@ export const en = {
   addModel: 'Add model',
   removeModel: 'Delete model',
   modelsEmpty: 'No models will be shown in the selector. Unlisted IDs can still be sent directly.',
+  keyBlank: 'Enter the API key, or leave the field empty to keep the stored one.',
+  keyIllegalCharacters: 'This API key contains characters that cannot be sent. Paste the raw key only.',
+  keyLooksWrapped: 'Paste only the key itself — not a NAME=value line, and without surrounding quotes.',
   modelIdRequired: 'Model ID is required.',
   modelIdDuplicate: 'Model ID must be unique.',
   modelNameInvalid: 'Display name cannot be empty.',
@@ -130,6 +133,9 @@ export const zh: typeof en = {
   addModel: '添加模型',
   removeModel: '删除模型',
   modelsEmpty: '模型选择器中将不显示任何模型；目录外 ID 仍可直接发送。',
+  keyBlank: '请输入 API 密钥；留空则保持已存储的密钥。',
+  keyIllegalCharacters: '该 API 密钥含有无法发送的字符。请只粘贴原始密钥。',
+  keyLooksWrapped: '请只粘贴密钥本身——不要带 NAME=value 整行，也不要带引号。',
   modelIdRequired: '模型 ID 不能为空。',
   modelIdDuplicate: '模型 ID 不能重复。',
   modelNameInvalid: '显示名称不能为空。',
diff --git a/packages/client/ui-models/tests/components.spec.tsx b/packages/client/ui-models/tests/components.spec.tsx
index aa9082e7dd..d9034ecd44 100644
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -11,6 +11,7 @@ import { pathOps } from '../src/client/ProviderEditor.tsx'
 import {
   DeepSeekModelsEditor, formatCapacity, modelDrafts, parseCapacity, validateDeepSeekModels,
 } from '../src/client/DeepSeekModelsEditor.tsx'
+import { apiKeyFailure } from '../src/client/apiKey.ts'
 import { deriveKeyRef, ModelsSettingsStore } from '../src/client/store.ts'
 import type { ProviderRow } from '../src/client/store.ts'
 import { en } from '../src/client/locales.ts'
@@ -1080,3 +1081,52 @@ describe('ModelsSection', () => {
     expect(failure).toBe('connection lost')
   })
 })
+
+describe('apiKeyFailure', () => {
+  it('treats a blank field as no failure — it means keep the stored key', () => {
+    expect(apiKeyFailure('')).toBeUndefined()
+  })
+
+  it.each([
+    ['a printable-ASCII key', 'sk-0123456789'],
+    ['a padded key, which the caller trims', '  sk-abc  '],
+    ['the printable-ASCII boundary characters', '!~'],
+    ['a hyphenated key carrying an equals sign', 'sk-ABC=xyz'],
+  ])('accepts %s', (_label, draft) => {
+    expect(apiKeyFailure(draft)).toBeUndefined()
+  })
+
+  it.each([
+    ['spaces', '   '],
+    ['a tab', '\t'],
+  ])('fails a field holding only %s instead of silently dropping it', (_label, draft) => {
+    expect(apiKeyFailure(draft)).toBe('keyBlank')
+  })
+
+  it.each([
+    ['an emoji', 'sk-\u{1F600}'],
+    ['CJK text', 'sk-你好'],
+    ['full-width punctuation', 'sk-abc，'],
+    ['an interior space', 'sk-abc def'],
+    ['a C0 control character', 'sk-abc\x01'],
+    ['a latin-1 character', 'sk-café'],
+  ])('fails %s as illegal characters', (_label, draft) => {
+    expect(apiKeyFailure(draft)).toBe('keyIllegalCharacters')
+  })
+
+  it.each([
+    ['a pasted environment line', 'DEEPSEEK_API_KEY=sk-abc'],
+    ['double quotes', '"sk-abc"'],
+    ['single quotes', '\'sk-abc\''],
+    ['backticks', '`sk-abc`'],
+  ])('fails %s as wrapped', (_label, draft) => {
+    expect(apiKeyFailure(draft)).toBe('keyLooksWrapped')
+  })
+
+  it('needs a matching closing quote before it calls a value wrapped', () => {
+    // A lone quote and an unbalanced one are legal printable ASCII, so the
+    // heuristic leaves them alone rather than guessing at a paste error.
+    expect(apiKeyFailure('"')).toBeUndefined()
+    expect(apiKeyFailure('"a')).toBeUndefined()
+  })
+})
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 99e85b0d10..a167710153 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -862,4 +862,106 @@ describe('hand-declared providers', () => {
     await waitFor(() => { expect(screen.queryByText(en.customTitle)).toBeNull() })
     expect(screen.getByRole('button', { name: en.customAdd })).toBeTruthy()
   })
+
+  it('refuses an unusable key on the field and blocks creation', () => {
+    const { mutate, set } = mountCard()
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme-gateway' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://gateway.acme.example/v1' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'acme-large' } })
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'sk-\u{1F600}' } })
+
+    // A hand-declared route reaches the same judgement as an edited one, so a
+    // key that no header can carry never becomes a profile plus a bad secret.
+    expect(screen.getByText(en.keyIllegalCharacters)).toBeTruthy()
+    expect(buttonNamed(en.create).disabled).toBe(true)
+    expect(mutate).not.toHaveBeenCalled()
+    expect(set).not.toHaveBeenCalled()
+  })
+
+  it('creates without a key when the route authenticates some other way', async () => {
+    const { set, onClose } = mountCard()
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'ambient-gateway' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://gateway.acme.example/v1' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'acme-large' } })
+    fireEvent.click(screen.getByText(en.create))
+
+    await waitFor(() => { expect(onClose).toHaveBeenCalledWith(true) })
+    expect(set).not.toHaveBeenCalled()
+  })
+})
+
+describe('API key field', () => {
+  it('submits with a blank key field without writing a credential', async () => {
+    const { mutate, set } = await mountSection()
+    openEditor('openai')
+
+    // The field opens empty even for a provider whose key is stored, where it
+    // means "keep that one" — so editing anything else must not require it.
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://moved.example/v1' } })
+    expect(buttonNamed(en.apply).disabled).toBe(false)
+    fireEvent.click(screen.getByText(en.apply))
+
+    await waitFor(() => { expect(mutate).toHaveBeenCalled() })
+    expect(set).not.toHaveBeenCalled()
+  })
+
+  it('blocks submit and names the field when the key holds only whitespace', async () => {
+    const { mutate, set } = await mountSection()
+    openEditor('openai')
+
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: '   ' } })
+
+    expect(screen.getByText(en.keyBlank)).toBeTruthy()
+    expect(buttonNamed(en.apply).disabled).toBe(true)
+    expect(mutate).not.toHaveBeenCalled()
+    expect(set).not.toHaveBeenCalled()
+  })
+
+  it('blocks submit when the key contains characters no header can carry', async () => {
+    const { set } = await mountSection()
+    openEditor('openai')
+
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'sk-\u{1F600}' } })
+
+    expect(screen.getByText(en.keyIllegalCharacters)).toBeTruthy()
+    expect(buttonNamed(en.apply).disabled).toBe(true)
+    expect(set).not.toHaveBeenCalled()
+  })
+
+  it('blocks submit when a whole NAME=value line was pasted', async () => {
+    await mountSection()
+    openEditor('openai')
+
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'OPENAI_API_KEY=sk-abc' } })
+
+    expect(screen.getByText(en.keyLooksWrapped)).toBeTruthy()
+    expect(buttonNamed(en.apply).disabled).toBe(true)
+  })
+
+  it('trims a padded key before storing it', async () => {
+    const { set } = await mountSection()
+    openEditor('openai')
+
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: '  sk-abc  ' } })
+    expect(buttonNamed(en.apply).disabled).toBe(false)
+    fireEvent.click(screen.getByText(en.apply))
+
+    await waitFor(() => { expect(set).toHaveBeenCalled() })
+    expect((set.mock.calls[0]?.[0] as { value: string }).value).toBe('sk-abc')
+  })
+
+  it('carries the trimmed key into an interrogation, not the padded draft', async () => {
+    const { discover } = await mountSection()
+    openEditor('openai')
+
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: '  sk-abc  ' } })
+    fireEvent.click(screen.getByRole('button', { name: en.fetchModels }))
+
+    await waitFor(() => { expect(discover).toHaveBeenCalled() })
+    expect(firstProbe(discover)).toMatchObject({ apiKey: 'sk-abc' })
+  })
 })

From a89c26b6110420ff59582528839d01230c970e9a Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 22:42:56 +0800
Subject: [PATCH 083/516] test(web): pin the API key field refusal end to end

---
 ...-08-06-api-key-format-validation.i18n.yaml |   6 +
 .../2026-08-06-api-key-format-validation.md   | 105 ++++++++++++++++++
 ...2026-08-06-api-key-format-validation.zh.md | 105 ++++++++++++++++++
 ...-08-06-api-key-format-validation.i18n.yaml |   6 -
 .../2026-08-06-api-key-format-validation.md   | 101 -----------------
 ...2026-08-06-api-key-format-validation.zh.md | 101 -----------------
 apps/web/tests/models-settings.e2e.ts         |  19 ++++
 7 files changed, 235 insertions(+), 208 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
 delete mode 100644 .agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
 delete mode 100644 .agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.md
 delete mode 100644 .agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.zh.md

diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
new file mode 100644
index 0000000000..42b42a591a
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.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-08-06-api-key-format-validation.md
+2026-08-06-api-key-format-validation.md: 9ec247cb2ba2578158759ec1115c5d3a95778cc4
+2026-08-06-api-key-format-validation.zh.md: 63c6a8c17ee93b4b68eb3505d5499756e9fb2401
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
new file mode 100644
index 0000000000..9ec247cb2b
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
@@ -0,0 +1,105 @@
+# Agent Note: Validate API key format before it reaches an HTTP header
+
+Status: implemented
+
+English | [中文](2026-08-06-api-key-format-validation.zh.md)
+
+## Problem
+
+An API key holding characters no HTTP header value can carry was accepted by every configuration surface and failed only when a request was built, far from the field that caused it.
+
+Pasting a key containing an emoji, CJK text, or a full-width punctuation mark into the web Models page reported a successful save. The first turn then failed with `Cannot convert argument to a ByteString because the character at index 7 has a value of 55357 which is greater than 255` — the index and code point are UTF-16 internals with no action attached, and they disclose the code point of one character of the key. `llm-deepseek` produced this because `fetch` builds the `Bearer` header inside the `try` in [adapter.ts](../../../../packages/llm/llm-deepseek/src/adapter.ts), whose `catch` labels every failure `TRANSPORT`; that label is in `DEFAULT_RETRYABLE_CODES`, so a permanent, deterministic fault was also retried three times.
+
+`llm-pi-ai` was worse on the same input. Its discovery probe builds the same header with a bare `fetch` in [discovery.ts](../../../../packages/llm/llm-pi-ai/src/discovery.ts) and wrapped every failure as `could not reach <url>`, so a local key fault was reported as an unreachable network. The probe is reachable from the unsaved draft: `ProviderEditor` puts the typed `keyDraft` into its probe request, so the model-listing button sent an illegal key before anything was stored.
+
+Whitespace passed every check. `ProviderEditor` tested `keyDraft.length` and `resolveAdapterOptions` tested `config.apiKey.length`, so a key of three spaces stored and then authenticated as `Bearer` plus blanks. `llm-pi-ai` rejected an empty literal `apiKey` in `resolveProfiles`, but applied no check whatsoever to a credential- or environment-sourced key — the path the Models page writes, and therefore the path users actually take.
+
+Sources: deepseek-harness#1594 and #1595; dsh-external#247, #249, #266, and #210.
+
+## Decision
+
+One rule defines a legal key: **after trimming, non-empty, and every character within `[\x21-\x7E]`** — printable ASCII, space excluded.
+
+This single predicate covers every input the sources list: empty, leading and trailing whitespace, interior whitespace, C0 control characters, emoji, CJK text, and full-width punctuation. It is also exactly the constraint that produced the ByteString failure, so the two issues close on one definition rather than on two coincidentally related fixes.
+
+A second, narrower rule catches a pasted environment line: input matching `^[A-Z][A-Z0-9_]*=` or wrapped in matching quotes is refused. Restricting the prefix to upper-case keeps real keys clear of it — `sk-` forms break the identifier match at the hyphen.
+
+### Invariants belong at every layer; heuristics belong where the human is
+
+The charset rule is an invariant. A non-ASCII character *cannot* travel in a header value for any provider, so enforcing it in the browser, in each resolver, and on every credential read is consistent by construction rather than by agreement.
+
+The shape rule is a guess about how people paste, so it runs **only in the browser**. `llm-pi-ai` fronts OpenAI, Anthropic, and arbitrary hand-declared gateways whose key formats this repository does not own; a gateway issuing a key shaped like `TENANT1=abc` would, if the rule ran in the resolver, be locked out with no escape — the settings page would refuse it and a hand-written `.env` would be rejected on read. Confining the heuristic to the surface where the paste happens keeps the environment as the way through.
+
+### Absence is a configuration state, not a missing key
+
+"No API key" means three different things here, and only one of them is an error. The rule applies to a value that was *provided*; deciding whether one was provided at all stays with each caller.
+
+**Omitted.** A profile naming neither `apiKey` nor `apiKeyEnv` is authenticated by something other than a harness-held key. `routeAuth` in [provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) keeps the installed catalog provider's own auth precisely so provider-native ambient discovery survives, and `openai-codex` — shipped in that catalog — authenticates through OAuth and refuses an explicit key outright. `namesCredential` carries this distinction. In `llm-deepseek`, an absent `apiKey` likewise falls through to `apiKeyEnv`. Omission is never validated.
+
+**A blank field in the web UI.** The key input opens empty even for a provider whose key is already stored — the `keyStored` copy reads "Configured — enter a new value to replace" — so blank means *keep what is stored*. `ProviderEditor` skips `credentials.set` entirely when the draft is empty, and that stays a no-op: a blank field never blocks submit, or editing a base URL would demand re-entering the key.
+
+**Provided, but empty or whitespace-only.** This is the one error, because the user expressed an intent to set a key and supplied nothing. `llm-pi-ai` already worded it correctly in `resolveProfiles` — *has an empty apiKey; omit it to use ambient authentication* — and that shape, naming the legitimate alternative rather than just refusing, is what the other surfaces adopt.
+
+`normalizeApiKey` therefore takes `string`, never `string | undefined`.
+
+### Where the rule lives
+
+`normalizeApiKey` is a module of the `dsh-llm` seam, beside [attribution.ts](../../../../packages/llm/llm/src/attribution.ts), which already owns shared header concerns. Both adapters depend on the seam and both need the rule, so it has two current consumers rather than a speculative one. It returns the trimmed value or a reason (`empty`, `illegalCharacters`).
+
+Both adapters also need the identical "refuse a stored credential" diagnosis, differing only by package prefix. `LlmError` is declared in the seam's `index.ts`, so `assertUsableApiKey(raw, pkg, ref)` lives there beside it and neither adapter carries a local copy. The predicate module stays dependency-free: importing `LlmError` into `api-key.ts` would cycle with `index.ts`'s re-export of it.
+
+The client cannot import any of this: client packages reference only client packages, so `packages/client/ui-models` mirrors the predicate in its own `apiKey.ts` and owns the localized messages, exactly as `validateDeepSeekModels` mirrors the host's `catalogModel` schema. Each side names the other in a comment.
+
+### What each surface does
+
+| Surface | Behavior |
+|---|---|
+| `dsh-llm` | Owns `normalizeApiKey`, `assertUsableApiKey`, and `INVALID_CREDENTIAL_CODE`, which is deliberately outside `DEFAULT_RETRYABLE_CODES`. |
+| `llm-deepseek` `resolveAdapterOptions` | Normalizes a present `apiKey`, throwing beside the other beyond-schema bounds; uses the trimmed value. An absent one falls through to `apiKeyEnv`. |
+| `llm-deepseek` `resolveApiKey` | Normalizes what the credentials seam or environment returns, rejecting with `INVALID_CREDENTIAL` naming the Models page and never echoing the key. |
+| `llm-pi-ai` `resolveProfiles` | Applies the shared rule, keeping its "omit it to use ambient authentication" wording, and writes the trimmed value into the resolved profile. |
+| `llm-pi-ai` `resolveApiKey` | Normalizes the credential and environment paths. A profile naming no credential still returns `undefined`, so ambient and OAuth routes are unaffected. |
+| `llm-pi-ai` `discoverModels` | Normalizes before building the header, so an illegal key is a credential fault rather than an unreachable endpoint. A probe carrying no key stays unauthenticated. |
+| `ui-models` | Mirrors the charset rule, adds the shape heuristic, trims `keyDraft` before probe and `credentials.set`, and fixes the `stringAt` emptiness test. A blank field remains a no-op that submits; a field holding only whitespace is a field-level failure. Submit is gated and the failure renders on the field, matching the existing `modelFailure` pattern. |
+
+`ProviderEditor` serves both the DeepSeek and pi-ai layouts, so one client change covers both providers. `CustomProviderCard` carries the same judgement for a hand-declared route.
+
+`credentials-local` is deliberately untouched. It stores credentials generally, and printable-ASCII is a constraint of HTTP headers rather than of credential storage; its existing refusal of values no dotenv style can represent stands as it was.
+
+## Alternatives considered
+
+**A `.pattern()` on the `apiKey` schema field.** Vendored schemastery supports it, and the pattern would serialize to the browser with the rest of the namespace schema — one rule, delivered rather than mirrored. It lost because a pattern cannot trim first: `cordis.yml` would then reject a padded key while `.env` tolerated one, and the resolver would disagree with the schema about the same string. Validating in `resolveAdapterOptions` keeps every surface trim-then-validate, and that function is already where this package re-judges bounds the schema cannot express.
+
+**A validation module shared by client and host.** Rejected by the source-plane layout: client packages reference only client packages plus `vendor/cordis` and `support/invariants`, and widening that to reach a host package would collide the two `Context` merges the split exists to keep apart. Mirroring a one-line predicate with a test on each side is the established shape here.
+
+**A per-adapter thrower in each of `llm-deepseek` and `llm-pi-ai`.** The first plan gave each adapter its own, differing only by the package prefix in the message, with a duplication-gate exemption to excuse the pair. Rejected before implementation: `LlmError` is declared in the seam, so the seam can own the diagnosis outright, and an exemption there would have hidden exactly the duplication it was covering for.
+
+**Sniffing the `TypeError` in the adapter's `catch`.** This would classify the ByteString failure after the fact, leaving the header construction itself unguarded. It depends on the wording of a Node error message, so it degrades silently across runtime versions, and it cannot help `llm-pi-ai`, whose request header is built inside the pi-ai SDK. Refusing the key before handing it over works for both adapters and for the discovery probe.
+
+**Enforcing in `credentials-local.set`.** It would catch every writer at once, including a hand-edited file. It lost because that provider stores credentials of every kind, and a rule derived from HTTP header encoding does not belong to it.
+
+**Running the shape heuristic in the resolvers too.** Symmetric, and it would stop a pasted environment line written directly into `.env`. Rejected for the lockout described above: a false positive in a resolver leaves the user no working path, while a false positive in the browser leaves the environment open.
+
+**Probing the provider at save time to prove the key works.** It would close the complaint the sources actually open with — a save that reports success and fails at the first turn. Rejected as out of scope and, on the code as it stood, unbuildable: `discoverModels` short-circuits to the installed catalog before any network call for exactly the providers pi-ai ships catalogs for, so it verified nothing about the key, and the DeepSeek card has no probe at all. A verifier's value is distinguishing "key rejected" from "cannot reach", which is the distinction this change makes reliable; building it first would have produced a verifier unable to tell its own outcomes apart. Comparable products also do not verify on save, so a blocking network call there would be an unexpected behavior rather than a missing one.
+
+## Consequences
+
+A malformed key is refused at the field that holds it, and a malformed stored key fails as `INVALID_CREDENTIAL` with a message naming where to fix it and no fragment of the key. Because that code sits outside `DEFAULT_RETRYABLE_CODES`, a deterministic credential fault is no longer retried three times as a transport blip. `llm-pi-ai` discovery reports an illegal probe key as a credential fault instead of an unreachable endpoint.
+
+The shape heuristic can refuse a real key. Upper-case-identifier-then-`=` and matched surrounding quotes are shapes no known provider issues, and the rule runs only in the browser, so a user who hits it can still set the credential through the environment. The residual cost is a confusing refusal for a key nobody has yet reported.
+
+Restricting to printable ASCII is stricter than the transport requires: a header value may carry `\x80`–`\xFF`. Admitting latin-1 would let `é` through to return an opaque 401 instead of a local, explained refusal, so the stricter rule is deliberate. A provider that issues latin-1 keys would need this rule widened.
+
+The charset predicate exists twice, once per source plane. The layout forbids sharing it; each side carries its own test and names its twin.
+
+Keys already stored by an earlier build are read through `resolveApiKey`, so an illegal stored value fails at resolution rather than at request time. The diagnosis improves, but the failure moves earlier for anyone currently holding one.
+
+The costliest way to get this wrong would have been to treat absence as invalidity: a rule applied to `undefined` breaks every route authenticating through ambient discovery or OAuth, and a blank field that blocked submit makes editing any other setting demand re-entering the key. Both are pinned by tests rather than left to care.
+
+## Testing
+
+`packages/llm/llm/tests/api-key.spec.ts` drives `normalizeApiKey` and `assertUsableApiKey` over the whole input table — empty, whitespace-only, padded, interior-space, C0 control, emoji, CJK, full-width, latin-1, and the printable-ASCII boundary — and pins that a refusal carries `INVALID_CREDENTIAL` and no part of the key.
+
+`packages/llm/llm-deepseek/tests/` covers the literal-config path in `adapter.spec.ts` and the stored-credential path end to end in `dynamic-config.spec.ts`, through the real credentials seam rather than a stub. `packages/llm/llm-pi-ai/tests/` covers `resolveProfiles` — including that the trimmed value reaches the resolved profile, which the `...rest` spread would otherwise discard — and the discovery probe, including that a probe with no key sends no `authorization` header.
+
+`packages/client/ui-models/tests/` pins `apiKeyFailure` over the same table plus the paste-shape cases, and drives both cards: a blank field submits without writing a credential, a whitespace-only field fails on the field, an illegal or wrapped key blocks submit, a padded key is trimmed before `credentials.set` and before an interrogation, and a hand-declared route can be created with no key at all.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
new file mode 100644
index 0000000000..63c6a8c17e
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -0,0 +1,105 @@
+# Agent Note: 在 API Key 进入 HTTP header 之前校验其格式
+
+Status: implemented
+
+[English](2026-08-06-api-key-format-validation.md) | 中文
+
+## Problem
+
+一个含有 HTTP header value 无法承载的字符的 API Key，曾被每一层配置界面接受，直到构造请求时才失败——离引发它的那个字段已经很远。
+
+把含 emoji、中文或全角标点的 Key 粘进 Web 模型设置页，保存会报成功。第一轮对话随即失败于 `Cannot convert argument to a ByteString because the character at index 7 has a value of 55357 which is greater than 255`——其中的下标与码点是 UTF-16 内部细节，不附带任何可执行动作，却泄露了 Key 中某一个字符的码点。`llm-deepseek` 之所以产出这句，是因为 `fetch` 在 [adapter.ts](../../../../packages/llm/llm-deepseek/src/adapter.ts) 的 `try` 内部构造 `Bearer` header，而那个 `catch` 把一切失败都标为 `TRANSPORT`；该标签又在 `DEFAULT_RETRYABLE_CODES` 之中，于是一个永久且确定的故障还会被重试三次。
+
+同样的输入在 `llm-pi-ai` 上更糟。它的探测路径在 [discovery.ts](../../../../packages/llm/llm-pi-ai/src/discovery.ts) 里用裸 `fetch` 构造同一个 header，并把一切失败包装成 `could not reach <url>`，于是一个本地的 Key 故障被报成网络不可达。这条探测在保存之前就够得着：`ProviderEditor` 把用户输入的 `keyDraft` 直接放进探测请求，所以「获取模型列表」按钮会在任何东西落盘之前就把非法 Key 发出去。
+
+空白字符能通过每一道检查。`ProviderEditor` 判的是 `keyDraft.length`，`resolveAdapterOptions` 判的是 `config.apiKey.length`，于是三个空格构成的 Key 会被存下，随后以 `Bearer` 加若干空格去认证。`llm-pi-ai` 在 `resolveProfiles` 中拒绝空的字面量 `apiKey`，却对来自凭据或环境的 Key 完全不做检查——而那正是模型设置页写入的路径，也就是用户真正走的路径。
+
+来源：deepseek-harness#1594 与 #1595；dsh-external#247、#249、#266、#210。
+
+## Decision
+
+一条规则定义什么是合法 Key：**trim 之后非空，且每个字符都落在 `[\x21-\x7E]`**——可打印 ASCII，不含空格。
+
+这一个断言覆盖了来源列出的全部输入：空值、首尾空白、中间空白、C0 控制字符、emoji、中文、全角标点。它同时正是造成 ByteString 失败的那条约束，所以两个 issue 收敛于同一个定义，而不是两个恰好相关的修复。
+
+第二条更窄的规则用于识别整行粘贴的环境变量：匹配 `^[A-Z][A-Z0-9_]*=` 或首尾成对引号的输入会被拒绝。把前缀限定为全大写可以让真实 Key 与之绝缘——`sk-` 这类形态会在连字符处中断标识符匹配。
+
+### 不变量属于每一层，启发式属于人所在的那一层
+
+字符集规则是不变量。非 ASCII 字符对任何 provider 都**不可能**在 header value 中传输，因此在浏览器、在各个 resolver、在每一次凭据读取上执行它，是结构上的一致而非约定上的一致。
+
+形状规则是对人如何粘贴的猜测，因此**只在浏览器中运行**。`llm-pi-ai` 前面挂着 OpenAI、Anthropic 以及任意手工声明的网关，本仓库并不掌握它们的 Key 格式；若这条规则运行在 resolver 中，一个签发形如 `TENANT1=abc` 的网关会让用户被彻底锁死、无路可走——设置页拒绝它，手写的 `.env` 在读取时同样被拒。把启发式限制在粘贴动作发生的那一层，环境变量便始终是那条出路。
+
+### 「没有 Key」是一种配置状态，不是缺失
+
+在这里，「没有 API Key」意味着三件完全不同的事，其中只有一件是错误。规则作用于**已提供**的值；至于究竟有没有提供，由各个调用方自行判断。
+
+**未指定。** 既不写 `apiKey` 也不写 `apiKeyEnv` 的 profile，是由 harness 所持有的 Key 之外的东西来鉴权的。[provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) 中的 `routeAuth` 保留内置 catalog provider 自身的鉴权，正是为了让 provider 原生的 ambient 发现得以存活；而该 catalog 附带的 `openai-codex` 通过 OAuth 鉴权，并会直接拒绝一个显式的 Key。`namesCredential` 承载着这一区分。在 `llm-deepseek` 中，缺省的 `apiKey` 同样会回落到 `apiKeyEnv`。未指定的情形永不参与校验。
+
+**Web UI 中留空的输入框。** 即便某个 provider 的 Key 已经存好，该输入框也是空着打开的——`keyStored` 的文案写的是「已配置——输入新值以替换」——所以留空意味着*保持已存储的值*。`ProviderEditor` 在草稿为空时完全跳过 `credentials.set`，这一点保持不变：留空绝不拦截提交，否则改一个 base URL 都得重新输一遍 Key。
+
+**已提供，但为空或纯空白。** 这是唯一的错误，因为用户表达了设置 Key 的意图却什么都没给。`llm-pi-ai` 在 `resolveProfiles` 中的措辞本就是对的——*has an empty apiKey; omit it to use ambient authentication*——这种指明合法替代路径而非单纯拒绝的形态，正是其他界面所采用的。
+
+因此 `normalizeApiKey` 接受 `string`，而绝非 `string | undefined`。
+
+### 规则住在哪里
+
+`normalizeApiKey` 是 `dsh-llm` seam 的一个模块，与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则，因此它拥有两个当前消费者而非一个预设消费者。它返回 trim 后的值，或一个原因（`empty`、`illegalCharacters`）。
+
+两个适配器同样都需要那句完全相同的「拒绝一个已存储凭据」的诊断，差别仅在包名前缀。`LlmError` 声明在 seam 的 `index.ts` 中，因此 `assertUsableApiKey(raw, pkg, ref)` 就住在它旁边，两个适配器都不再各留一份。断言模块本身保持零依赖：把 `LlmError` 引入 `api-key.ts` 会与 `index.ts` 对它的再导出成环。
+
+客户端无法引入其中任何一个：client 包只 reference client 包，因此 `packages/client/ui-models` 在自己的 `apiKey.ts` 中镜像这个断言并持有本地化文案，正如 `validateDeepSeekModels` 镜像 host 侧的 `catalogModel` schema。两侧在注释中互相指名。
+
+### 各个界面各做什么
+
+| 界面 | 行为 |
+|---|---|
+| `dsh-llm` | 拥有 `normalizeApiKey`、`assertUsableApiKey` 与 `INVALID_CREDENTIAL_CODE`，后者刻意不进 `DEFAULT_RETRYABLE_CODES`。 |
+| `llm-deepseek` `resolveAdapterOptions` | 归一化已提供的 `apiKey`，与其他超出 schema 的边界检查并排抛错；使用 trim 后的值。缺省的 `apiKey` 回落到 `apiKeyEnv`。 |
+| `llm-deepseek` `resolveApiKey` | 归一化凭据 seam 或环境返回的值，以 `INVALID_CREDENTIAL` 拒绝，消息指明模型设置页，绝不回显 Key。 |
+| `llm-pi-ai` `resolveProfiles` | 施加这条共享规则，保留其「omit it to use ambient authentication」的措辞，并把 trim 后的值写进解析后的 profile。 |
+| `llm-pi-ai` `resolveApiKey` | 归一化凭据与环境路径。不指定任何凭据的 profile 仍返回 `undefined`，ambient 与 OAuth 路由不受影响。 |
+| `llm-pi-ai` `discoverModels` | 在构造 header 之前归一化，使非法 Key 成为凭据故障而非端点不可达。不带 Key 的探测保持未鉴权。 |
+| `ui-models` | 镜像字符集规则，加入形状启发式，在探测与 `credentials.set` 之前 trim `keyDraft`，并修正 `stringAt` 的空值判断。留空的输入框仍是可以提交的空操作；只含空白的输入框则是字段级失败。提交受拦截，失败呈现在字段上，与既有的 `modelFailure` 模式一致。 |
+
+`ProviderEditor` 同时服务 DeepSeek 与 pi-ai 两种布局，因此一处客户端改动覆盖两个 provider。`CustomProviderCard` 为手工声明的路由承载同一套判定。
+
+`credentials-local` 刻意不动。它存储各类凭据，而可打印 ASCII 是 HTTP header 的约束而非凭据存储的约束；它既有的、拒绝任何 dotenv 样式都无法表示的值的行为保持原样。
+
+## Alternatives considered
+
+**在 `apiKey` schema 字段上加 `.pattern()`。** vendor 中的 schemastery 支持它，且该 pattern 会随命名空间 schema 一同序列化到浏览器——一条规则，投递而非镜像。它落败于 pattern 无法先行 trim：那样 `cordis.yml` 会拒绝带首尾空白的 Key 而 `.env` 却容忍，resolver 与 schema 会对同一个字符串给出分歧。在 `resolveAdapterOptions` 中校验可以让每一层都是 trim-then-validate，而该函数本就是本包重新裁定 schema 无法表达的边界之处。
+
+**由 client 与 host 共享一个校验模块。** 被 source plane 布局否决：client 包只 reference client 包外加 `vendor/cordis` 与 `support/invariants`，把它放宽到够得着 host 包会撞上这一分割本就要隔开的两份 `Context` 合并。在两侧各镜像一行断言并各配一份测试，是此处的既定形态。
+
+**在 `llm-deepseek` 与 `llm-pi-ai` 中各留一个抛错 helper。** 最初的计划正是各留一份，差别仅在消息中的包名前缀，并配一个重复检测豁免来放行这一对。在实现之前即被否决：`LlmError` 声明在 seam 中，因此 seam 完全可以自己拥有这句诊断，而那里的一个豁免恰恰会掩盖它本要遮掩的重复。
+
+**在适配器的 `catch` 中嗅探 `TypeError`。** 这只是事后归类 ByteString 失败，header 构造本身仍无防护。它依赖 Node 错误消息的措辞，因而会随运行时版本静默失效；它也帮不到 `llm-pi-ai`——后者的请求 header 构造在 pi-ai SDK 内部。在交出 Key 之前就拒绝，则对两个适配器与探测路径同时有效。
+
+**在 `credentials-local.set` 中执行。** 它能一次性拦住所有写入方，包括手工编辑的文件。它落败于该 provider 存储各种类型的凭据，而一条源自 HTTP header 编码的规则并不属于它。
+
+**让形状启发式也在 resolver 中运行。** 更对称，且能拦住直接写进 `.env` 的整行环境变量。因上文所述的锁死风险而否决：resolver 中的一次误判会让用户无路可走，浏览器中的一次误判则仍留有环境变量这条路。
+
+**在保存时探测 provider 以证明 Key 可用。** 它能关掉来源真正开篇抱怨的那件事——保存报成功、第一轮才失败。因超出范围而否决，且在当时的代码上无法建成：对 pi-ai 恰好自带 catalog 的那些 provider，`discoverModels` 会在任何网络调用之前短路到内置 catalog，因而对 Key 什么都验证不了；而 DeepSeek 卡片根本没有探测。验证器的价值在于分清「Key 被拒」与「无法连通」，而这正是本次改动让其变得可靠的区分；先建验证器只会得到一个分不清自身结果的验证器。同类产品也不在保存时验证，因此保存时的阻断式网络调用会是一个意外行为，而非一处缺失。
+
+## Consequences
+
+格式错误的 Key 在持有它的那个字段上就被拒绝；格式错误的已存储 Key 以 `INVALID_CREDENTIAL` 失败，消息指明修复位置且不含 Key 的任何片段。由于该 code 位于 `DEFAULT_RETRYABLE_CODES` 之外，一个确定性的凭据故障不再被当作瞬时传输抖动重试三次。`llm-pi-ai` 的探测把非法 Key 报为凭据故障，而非端点不可达。
+
+形状启发式可能拒绝一个真实的 Key。全大写标识符接 `=`、以及首尾成对引号，都是已知 provider 不会签发的形态，且该规则只在浏览器中运行，因此撞上它的用户仍可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
+
+限定为可打印 ASCII 比传输本身的要求更严：header value 是可以承载 `\x80`–`\xFF` 的。放行 latin-1 会让 `é` 通过并换回一个语焉不详的 401，而不是一次本地的、有解释的拒绝，因此从严是刻意的。若某个 provider 签发 latin-1 的 Key，这条规则需要放宽。
+
+字符集断言存在两份，每个 source plane 一份。布局禁止共享它；两侧各自带测试并在注释中指名其孪生体。
+
+早先版本已存下的 Key 会经 `resolveApiKey` 读取，因此一个非法的既存值将从解析时开始失败，而非到请求时才失败。诊断变好了，但对当前正持有这类值的人而言，失败点提前了。
+
+把这件事做错的最大代价，会是把「未指定」当成「非法」：一条施加到 `undefined` 上的规则会打断每一条依赖 ambient 发现或 OAuth 鉴权的路由，而一个会拦截提交的空输入框，则会让改动任何其他设置都必须重新输入 Key。这两点都由测试钉住，而不是仅仰赖谨慎。
+
+## Testing
+
+`packages/llm/llm/tests/api-key.spec.ts` 以整张输入表驱动 `normalizeApiKey` 与 `assertUsableApiKey`——空值、纯空白、带首尾空白、含中间空格、C0 控制字符、emoji、中文、全角、latin-1，以及可打印 ASCII 的边界字符——并钉住一次拒绝携带 `INVALID_CREDENTIAL` 且不含 Key 的任何部分。
+
+`packages/llm/llm-deepseek/tests/` 在 `adapter.spec.ts` 中覆盖字面量配置路径，在 `dynamic-config.spec.ts` 中经真实凭据 seam（而非 stub）端到端覆盖已存储凭据路径。`packages/llm/llm-pi-ai/tests/` 覆盖 `resolveProfiles`——包括 trim 后的值确实到达解析后的 profile，否则会被 `...rest` 展开丢弃——以及探测路径，包括不带 Key 的探测不会发出 `authorization` 标头。
+
+`packages/client/ui-models/tests/` 以同一张表加上形状用例钉住 `apiKeyFailure`，并驱动两张卡片：留空的输入框可提交且不写入凭据、只含空白的输入框在字段上失败、非法或被包裹的 Key 拦截提交、带首尾空白的 Key 在 `credentials.set` 与探测之前被 trim，以及手工声明的路由可以完全不带 Key 创建。
diff --git a/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
deleted file mode 100644
index f62a18e0eb..0000000000
--- a/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/proposed/bug-fix/2026-08-06-api-key-format-validation.md
-2026-08-06-api-key-format-validation.md: dc19baa8b697998df2892f0840a35a8232cc92de
-2026-08-06-api-key-format-validation.zh.md: 28073660b1d4868fecf5ce419726d6d997383392
diff --git a/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.md
deleted file mode 100644
index dc19baa8b6..0000000000
--- a/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Agent Note: Validate API key format before it reaches an HTTP header
-
-Status: proposed
-
-English | [中文](2026-08-06-api-key-format-validation.zh.md)
-
-## Problem
-
-An API key holding characters no HTTP header value can carry is accepted by every configuration surface and fails only when a request is built, far from the field that caused it.
-
-Paste a key containing an emoji, CJK text, or a full-width punctuation mark into the web Models page and the save reports success. The first turn then fails with `Cannot convert argument to a ByteString because the character at index 7 has a value of 55357 which is greater than 255` — the index and code point are UTF-16 internals with no action attached, and they disclose the code point of one character of the key. `llm-deepseek` produces this because `fetch` builds the `Bearer` header inside the `try` at [adapter.ts](../../../../packages/llm/llm-deepseek/src/adapter.ts), whose `catch` labels every failure `TRANSPORT`; that label is in `DEFAULT_RETRYABLE_CODES`, so a permanent, deterministic fault is also retried three times.
-
-`llm-pi-ai` is worse on the same input. Its discovery probe builds the same header with a bare `fetch` in [discovery.ts](../../../../packages/llm/llm-pi-ai/src/discovery.ts) and wraps every failure as `could not reach <url>`, so a local key fault is reported as an unreachable network. The probe is reachable from the unsaved draft: `ProviderEditor` puts the typed `keyDraft` into its probe request, so the model-listing button sends an illegal key before anything is stored.
-
-Whitespace passes every check. `ProviderEditor` tests `keyDraft.length` and `resolveAdapterOptions` tests `config.apiKey.length`, so a key of three spaces stores and then authenticates as `Bearer` plus blanks. `llm-pi-ai` rejects an empty literal `apiKey` in `resolveProfiles`, but applies no check whatsoever to a credential- or environment-sourced key — which is the path the Models page writes, and therefore the path users actually take.
-
-Sources: deepseek-harness#1594 and #1595; dsh-external#247, #249, #266, and #210.
-
-## Proposal
-
-One rule defines a legal key: **after trimming, non-empty, and every character within `[\x21-\x7E]`** — printable ASCII, space excluded.
-
-This single predicate covers every input the sources list: empty, leading and trailing whitespace, interior whitespace, C0 control characters, emoji, CJK text, and full-width punctuation. It is also exactly the constraint that produced the ByteString failure, so the two issues close on one definition rather than on two coincidentally related fixes.
-
-A second, narrower rule catches a pasted environment line: reject input matching `^[A-Z][A-Z0-9_]*=` or wrapped in matching quotes. Restricting the prefix to upper-case keeps real keys clear of it — `sk-` forms break the identifier match at the hyphen.
-
-### Invariants belong at every layer; heuristics belong where the human is
-
-The charset rule is an invariant. A non-ASCII character *cannot* travel in a header value for any provider, so enforcing it in the browser, in each resolver, and on every credential read is consistent by construction rather than by agreement.
-
-The shape rule is a guess about how people paste, so it runs **only in the browser**. `llm-pi-ai` fronts OpenAI, Anthropic, and arbitrary hand-declared gateways whose key formats this repository does not own; a gateway issuing a key shaped like `TENANT1=abc` would, if the rule ran in the resolver, be locked out with no escape — the settings page would refuse it and a hand-written `.env` would be rejected on read. Confining the heuristic to the surface where the paste happens keeps the environment as the way through.
-
-### Absence is a configuration state, not a missing key
-
-"No API key" means three different things here, and only one of them is an error. The rule applies to a value that was *provided*; deciding whether one was provided at all stays with each caller.
-
-**Omitted.** A profile naming neither `apiKey` nor `apiKeyEnv` is authenticated by something other than a harness-held key. `routeAuth` in [provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) keeps the installed catalog provider's own auth precisely so provider-native ambient discovery survives, and `openai-codex` — shipped in that catalog — authenticates through OAuth and refuses an explicit key outright. `namesCredential` exists to carry this distinction. In `llm-deepseek`, an absent `apiKey` likewise falls through to `apiKeyEnv`. Omission is never validated.
-
-**A blank field in the web UI.** The key input opens empty even for a provider whose key is already stored — the `keyStored` copy reads "Configured — enter a new value to replace" — so blank means *keep what is stored*. `ProviderEditor` already skips `credentials.set` entirely when the draft is empty, and that stays a no-op: a blank field must never block submit, or editing a base URL would demand re-entering the key.
-
-**Provided, but empty or whitespace-only.** This is the one error, because the user expressed an intent to set a key and supplied nothing. `llm-pi-ai` already words it correctly in `resolveProfiles` — *has an empty apiKey; omit it to use ambient authentication* — and that shape, naming the legitimate alternative rather than just refusing, is what the other surfaces adopt.
-
-`normalizeApiKey` therefore takes `string`, never `string | undefined`.
-
-### Where the rule lives
-
-`normalizeApiKey` is a new module of the `dsh-llm` seam, beside [attribution.ts](../../../../packages/llm/llm/src/attribution.ts), which already owns shared header concerns. Both adapters depend on the seam and both need the rule, so it has two current consumers rather than a speculative one. It returns the trimmed value or a reason (`empty`, `illegalCharacters`).
-
-The client cannot import it: client packages reference only client packages, so `packages/client/ui-models` mirrors the predicate and owns the localized messages, exactly as `validateDeepSeekModels` mirrors the host's `catalogModel` schema today. Each side names the other in a comment.
-
-### What each surface does
-
-| Surface | Change |
-|---|---|
-| `dsh-llm` | Add `normalizeApiKey`; add `INVALID_CREDENTIAL`, deliberately outside `DEFAULT_RETRYABLE_CODES`. |
-| `llm-deepseek` `resolveAdapterOptions` | Normalize a present `apiKey`, throwing beside the existing beyond-schema bounds; use the trimmed value. An absent one still falls through to `apiKeyEnv`. Closes dsh-external#210. |
-| `llm-deepseek` `resolveApiKey` | Normalize what the credentials seam or environment returns; reject with `INVALID_CREDENTIAL` naming the Models page, never echoing the key. |
-| `llm-pi-ai` `resolveProfiles` | Widen the existing emptiness check to the shared rule, keeping its "omit it to use ambient authentication" wording. |
-| `llm-pi-ai` `resolveApiKey` | Normalize the credential and environment paths, which are unchecked today. A profile naming no credential still returns `undefined` untouched, so ambient and OAuth routes are unaffected. |
-| `llm-pi-ai` `discoverModels` | Normalize before building the header, so an illegal key stops reporting as an unreachable endpoint. A probe carrying no key stays unauthenticated as it is today. |
-| `ui-models` | Mirror the charset rule, add the shape heuristic, trim `keyDraft` before probe and `credentials.set`, and fix the `stringAt` emptiness test. A blank field remains a no-op that submits; a field holding only whitespace is a field-level failure, so typed input is never silently discarded. Gate submit and show the failure on the field, matching the existing `modelFailure` pattern. |
-
-`ProviderEditor` serves both the DeepSeek and pi-ai layouts, so one client change covers both providers.
-
-`credentials-local` is deliberately untouched. It stores credentials generally, and printable-ASCII is a constraint of HTTP headers rather than of credential storage; its existing refusal of values no dotenv style can represent stays as it is.
-
-## Alternatives considered
-
-**A `.pattern()` on the `apiKey` schema field.** Vendored schemastery supports it, and the pattern would serialize to the browser with the rest of the namespace schema — one rule, delivered rather than mirrored. It loses because a pattern cannot trim first: `cordis.yml` would then reject a padded key while `.env` tolerated one, and the resolver would disagree with the schema about the same string. Validating in `resolveAdapterOptions` keeps every surface trim-then-validate, and that function is already where this package re-judges bounds the schema cannot express.
-
-**A validation module shared by client and host.** Rejected by the source-plane layout: client packages reference only client packages plus `vendor/cordis` and `support/invariants`, and widening that to reach a host package would collide the two `Context` merges the split exists to keep apart. Mirroring a one-line predicate with a test on each side is the established shape here.
-
-**Sniffing the `TypeError` in the adapter's `catch`.** This would classify the ByteString failure after the fact, leaving the header construction itself unguarded. It depends on the wording of a Node error message, so it degrades silently across runtime versions, and it cannot help `llm-pi-ai`, whose header is built inside the pi-ai SDK. Refusing the key before handing it over works for both adapters and for the discovery probe.
-
-**Enforcing in `credentials-local.set`.** It would catch every writer at once, including a hand-edited file. It loses because that provider stores credentials of every kind, and a rule derived from HTTP header encoding does not belong to it.
-
-**Running the shape heuristic in the resolvers too.** Symmetric, and it would stop a pasted environment line written directly into `.env`. Rejected for the lockout described above: a false positive in a resolver leaves the user no working path, while a false positive in the browser leaves the environment open.
-
-**Probing the provider at save time to prove the key works.** It would close the complaint the sources actually open with — a save that reports success and fails at the first turn. Rejected as out of scope and, on today's code, unbuildable: `discoverModels` short-circuits to the installed catalog before any network call for exactly the providers pi-ai ships catalogs for, so it verifies nothing about the key, and the DeepSeek card has no probe at all. A verifier's value is distinguishing "key rejected" from "cannot reach", which is the distinction this note makes reliable; building it first would produce a verifier unable to tell its own outcomes apart. Comparable products also do not verify on save, so a blocking network call at save time would be an unexpected behavior rather than a missing one.
-
-## Acceptance criteria
-
-- The browser, both resolvers, and both credential reads accept and reject the same *provided* strings: whitespace-only, padded, interior-space, C0 control, emoji, CJK, and full-width inputs are refused; a printable-ASCII key is accepted, trimmed.
-- A profile naming no credential still resolves to no key, and a route authenticating through the installed provider's own ambient discovery or OAuth keeps working untouched.
-- A blank key field saves the rest of the card without writing a credential; a field holding only whitespace fails on the field instead of being silently dropped.
-- A rejected key names the API key field in the web UI and blocks submit; nothing is written to settings or credentials.
-- A key that reaches a resolver illegally fails as `INVALID_CREDENTIAL` with a message naming where to fix it, containing no part of the key, and is not retried.
-- `llm-pi-ai` discovery reports an illegal key as a key fault, not as an unreachable endpoint.
-- A legal key still travels the existing `credentials.set` path unchanged.
-
-## Risks
-
-The shape heuristic can refuse a real key. Upper-case-identifier-then-`=` and matched surrounding quotes are shapes no known provider issues, and the rule runs only in the browser, so a user who hits it can still set the credential through the environment. The residual cost is a confusing refusal for a key nobody has yet reported.
-
-Restricting to printable ASCII is stricter than the transport requires: a header value may carry `\x80`–`\xFF`. Admitting latin-1 would let `é` through to return an opaque 401 instead of a local, explained refusal, so the stricter rule is deliberate. A provider that issues latin-1 keys would need this rule widened.
-
-The charset predicate exists twice, once per source plane. The layout forbids sharing it, and the duplication gate may flag the pair; each side carries its own test and names its twin.
-
-The costliest way to get this wrong is to treat absence as invalidity. A rule applied to `undefined` would break every route authenticating through ambient discovery or OAuth — `openai-codex` cannot take a key at all — and a blank field that blocked submit would make editing any other setting demand re-entering the key. Both belong in the tests, not only in this note.
-
-Keys already stored by an earlier build are read through `resolveApiKey`, so an illegal stored value begins failing at resolution rather than at request time. That is the intent — the diagnosis improves — but it moves the failure earlier for anyone currently holding one.
diff --git a/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.zh.md
deleted file mode 100644
index 28073660b1..0000000000
--- a/.agents/notes/proposed/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Agent Note: 在 API Key 进入 HTTP header 之前校验其格式
-
-Status: proposed
-
-[English](2026-08-06-api-key-format-validation.md) | 中文
-
-## Problem
-
-一个含有 HTTP header value 无法承载的字符的 API Key,会被每一层配置界面接受,直到构造请求时才失败——离引发它的那个字段已经很远。
-
-把含 emoji、中文或全角标点的 Key 粘进 Web 模型设置页,保存会报成功。第一轮对话随即失败于 `Cannot convert argument to a ByteString because the character at index 7 has a value of 55357 which is greater than 255`——其中的下标与码点是 UTF-16 内部细节,不附带任何可执行动作,却泄露了 Key 中某一个字符的码点。`llm-deepseek` 之所以产出这句,是因为 `fetch` 在 [adapter.ts](../../../../packages/llm/llm-deepseek/src/adapter.ts) 的 `try` 内部构造 `Bearer` header,而那个 `catch` 把一切失败都标为 `TRANSPORT`;该标签又在 `DEFAULT_RETRYABLE_CODES` 之中,于是一个永久且确定的故障还会被重试三次。
-
-同样的输入在 `llm-pi-ai` 上更糟。它的探测路径在 [discovery.ts](../../../../packages/llm/llm-pi-ai/src/discovery.ts) 里用裸 `fetch` 构造同一个 header,并把一切失败包装成 `could not reach <url>`,于是一个本地的 Key 故障被报成网络不可达。这条探测在保存之前就够得着:`ProviderEditor` 把用户输入的 `keyDraft` 直接放进探测请求,所以「获取模型列表」按钮会在任何东西落盘之前就把非法 Key 发出去。
-
-空白字符能通过每一道检查。`ProviderEditor` 判的是 `keyDraft.length`,`resolveAdapterOptions` 判的是 `config.apiKey.length`,于是三个空格构成的 Key 会被存下,随后以 `Bearer` 加若干空格去认证。`llm-pi-ai` 在 `resolveProfiles` 中拒绝空的字面量 `apiKey`,却对来自凭据或环境的 Key 完全不做检查——而那正是模型设置页写入的路径,也就是用户真正走的路径。
-
-来源:deepseek-harness#1594 与 #1595;dsh-external#247、#249、#266、#210。
-
-## Proposal
-
-一条规则定义什么是合法 Key:**trim 之后非空,且每个字符都落在 `[\x21-\x7E]`**——可打印 ASCII,不含空格。
-
-这一个断言覆盖了来源列出的全部输入:空值、首尾空白、中间空白、C0 控制字符、emoji、中文、全角标点。它同时正是造成 ByteString 失败的那条约束,所以两个 issue 收敛于同一个定义,而不是两个恰好相关的修复。
-
-第二条更窄的规则用于识别整行粘贴的环境变量:拒绝匹配 `^[A-Z][A-Z0-9_]*=` 或首尾成对引号的输入。把前缀限定为全大写可以让真实 Key 与之绝缘——`sk-` 这类形态会在连字符处中断标识符匹配。
-
-### 不变量属于每一层,启发式属于人所在的那一层
-
-字符集规则是不变量。非 ASCII 字符对任何 provider 都**不可能**在 header value 中传输,因此在浏览器、在各个 resolver、在每一次凭据读取上执行它,是结构上的一致而非约定上的一致。
-
-形状规则是对人如何粘贴的猜测,因此**只在浏览器中运行**。`llm-pi-ai` 前面挂着 OpenAI、Anthropic 以及任意手工声明的网关,本仓库并不掌握它们的 Key 格式;若这条规则运行在 resolver 中,一个签发形如 `TENANT1=abc` 的网关会让用户被彻底锁死、无路可走——设置页拒绝它,手写的 `.env` 在读取时同样被拒。把启发式限制在粘贴动作发生的那一层,环境变量便始终是那条出路。
-
-### 「没有 Key」是一种配置状态,不是缺失
-
-在这里,「没有 API Key」意味着三件完全不同的事,其中只有一件是错误。规则作用于**已提供**的值;至于究竟有没有提供,由各个调用方自行判断。
-
-**未指定。** 既不写 `apiKey` 也不写 `apiKeyEnv` 的 profile,是由 harness 所持有的 Key 之外的东西来鉴权的。[provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) 中的 `routeAuth` 保留内置 catalog provider 自身的鉴权,正是为了让 provider 原生的 ambient 发现得以存活;而该 catalog 附带的 `openai-codex` 通过 OAuth 鉴权,并会直接拒绝一个显式的 Key。`namesCredential` 的存在就是为了承载这一区分。在 `llm-deepseek` 中,缺省的 `apiKey` 同样会回落到 `apiKeyEnv`。未指定的情形永不参与校验。
-
-**Web UI 中留空的输入框。** 即便某个 provider 的 Key 已经存好,该输入框也是空着打开的——`keyStored` 的文案写的是「已配置——输入新值以替换」——所以留空意味着*保持已存储的值*。`ProviderEditor` 在草稿为空时本就完全跳过 `credentials.set`,这一点保持不变:留空绝不能拦截提交,否则改一个 base URL 都得重新输一遍 Key。
-
-**已提供,但为空或纯空白。** 这是唯一的错误,因为用户表达了设置 Key 的意图却什么都没给。`llm-pi-ai` 在 `resolveProfiles` 中的措辞本就是对的——*has an empty apiKey; omit it to use ambient authentication*——这种指明合法替代路径而非单纯拒绝的形态,正是其他界面要采用的。
-
-因此 `normalizeApiKey` 接受 `string`,而绝非 `string | undefined`。
-
-### 规则住在哪里
-
-`normalizeApiKey` 是 `dsh-llm` seam 的新模块,与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则,因此它拥有两个当前消费者而非一个预设消费者。它返回 trim 后的值,或一个原因(`empty`、`illegalCharacters`)。
-
-客户端无法引入它:client 包只 reference client 包,因此 `packages/client/ui-models` 镜像这个断言并持有本地化文案,正如今天 `validateDeepSeekModels` 镜像 host 侧的 `catalogModel` schema。两侧在注释中互相指名。
-
-### 各个界面各做什么
-
-| 界面 | 改动 |
-|---|---|
-| `dsh-llm` | 新增 `normalizeApiKey`;新增 `INVALID_CREDENTIAL`,刻意不进 `DEFAULT_RETRYABLE_CODES`。 |
-| `llm-deepseek` `resolveAdapterOptions` | 归一化已提供的 `apiKey`,与既有的超出 schema 的边界检查并排抛错;使用 trim 后的值。缺省的 `apiKey` 仍照旧回落到 `apiKeyEnv`。关闭 dsh-external#210。 |
-| `llm-deepseek` `resolveApiKey` | 归一化凭据 seam 或环境返回的值;以 `INVALID_CREDENTIAL` 拒绝,消息指明模型设置页,绝不回显 Key。 |
-| `llm-pi-ai` `resolveProfiles` | 把既有的空值检查扩展为这条共享规则,并保留其「omit it to use ambient authentication」的措辞。 |
-| `llm-pi-ai` `resolveApiKey` | 归一化今天完全未受检的凭据与环境路径。不指定任何凭据的 profile 仍原样返回 `undefined`,ambient 与 OAuth 路由不受影响。 |
-| `llm-pi-ai` `discoverModels` | 在构造 header 之前归一化,使非法 Key 不再被报成端点不可达。不带 Key 的探测照旧保持未鉴权。 |
-| `ui-models` | 镜像字符集规则,加入形状启发式,在探测与 `credentials.set` 之前 trim `keyDraft`,并修正 `stringAt` 的空值判断。留空的输入框仍是可以提交的空操作;只含空白的输入框则以字段级失败呈现,使已输入的内容绝不被静默丢弃。按既有 `modelFailure` 的模式拦截提交并在字段上呈现失败。 |
-
-`ProviderEditor` 同时服务 DeepSeek 与 pi-ai 两种布局,因此一处客户端改动覆盖两个 provider。
-
-`credentials-local` 刻意不动。它存储各类凭据,而可打印 ASCII 是 HTTP header 的约束而非凭据存储的约束;它既有的、拒绝任何 dotenv 样式都无法表示的值的行为保持原样。
-
-## Alternatives considered
-
-**在 `apiKey` schema 字段上加 `.pattern()`。** vendor 中的 schemastery 支持它,且该 pattern 会随命名空间 schema 一同序列化到浏览器——一条规则,投递而非镜像。它落败于 pattern 无法先行 trim:那样 `cordis.yml` 会拒绝带首尾空白的 Key 而 `.env` 却容忍,resolver 与 schema 会对同一个字符串给出分歧。在 `resolveAdapterOptions` 中校验可以让每一层都是 trim-then-validate,而该函数本就是本包重新裁定 schema 无法表达的边界之处。
-
-**由 client 与 host 共享一个校验模块。** 被 source plane 布局否决:client 包只 reference client 包外加 `vendor/cordis` 与 `support/invariants`,把它放宽到够得着 host 包会撞上这一分割本就要隔开的两份 `Context` 合并。在两侧各镜像一行断言并各配一份测试,是此处的既定形态。
-
-**在适配器的 `catch` 中嗅探 `TypeError`。** 这只是事后归类 ByteString 失败,header 构造本身仍无防护。它依赖 Node 错误消息的措辞,因而会随运行时版本静默失效;它也帮不到 `llm-pi-ai`——后者的 header 构造在 pi-ai SDK 内部。在交出 Key 之前就拒绝,则对两个适配器与探测路径同时有效。
-
-**在 `credentials-local.set` 中执行。** 它能一次性拦住所有写入方,包括手工编辑的文件。它落败于该 provider 存储各种类型的凭据,而一条源自 HTTP header 编码的规则并不属于它。
-
-**让形状启发式也在 resolver 中运行。** 更对称,且能拦住直接写进 `.env` 的整行环境变量。因上文所述的锁死风险而否决:resolver 中的一次误判会让用户无路可走,浏览器中的一次误判则仍留有环境变量这条路。
-
-**在保存时探测 provider 以证明 Key 可用。** 它能关掉来源真正开篇抱怨的那件事——保存报成功、第一轮才失败。因超出范围而否决,且在今天的代码上无法建成:对 pi-ai 恰好自带 catalog 的那些 provider,`discoverModels` 会在任何网络调用之前短路到内置 catalog,因而对 Key 什么都验证不了;而 DeepSeek 卡片根本没有探测。验证器的价值在于分清「Key 被拒」与「无法连通」,而这正是本 Agent Note 要让其变得可靠的区分;先建验证器只会得到一个分不清自身结果的验证器。同类产品也不在保存时验证,因此保存时的阻断式网络调用会是一个意外行为,而非一处缺失。
-
-## Acceptance criteria
-
-- 浏览器、两个 resolver 与两处凭据读取接受与拒绝同一组**已提供**的字符串:纯空白、带首尾空白、含中间空格、C0 控制字符、emoji、中文、全角输入均被拒绝;可打印 ASCII 的 Key 被接受并 trim。
-- 不指定任何凭据的 profile 仍解析为「没有 Key」,通过内置 provider 自身的 ambient 发现或 OAuth 鉴权的路由原样可用。
-- 留空的 Key 输入框可以保存卡片其余部分而不写入凭据;只含空白的输入框则以字段级失败呈现,而不是被静默丢弃。
-- 被拒绝的 Key 在 Web UI 中定位到 API Key 字段并拦截提交;settings 与凭据均不写入。
-- 非法抵达 resolver 的 Key 以 `INVALID_CREDENTIAL` 失败,消息指明修复位置、不含 Key 的任何片段,且不被重试。
-- `llm-pi-ai` 的探测把非法 Key 报为 Key 故障,而非端点不可达。
-- 合法 Key 仍沿既有 `credentials.set` 路径原样通过。
-
-## Risks
-
-形状启发式可能拒绝一个真实的 Key。全大写标识符接 `=`、以及首尾成对引号,都是已知 provider 不会签发的形态,且该规则只在浏览器中运行,因此撞上它的用户仍可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
-
-限定为可打印 ASCII 比传输本身的要求更严:header value 是可以承载 `\x80`–`\xFF` 的。放行 latin-1 会让 `é` 通过并换回一个语焉不详的 401,而不是一次本地的、有解释的拒绝,因此从严是刻意的。若某个 provider 签发 latin-1 的 Key,这条规则需要放宽。
-
-字符集断言存在两份,每个 source plane 一份。布局禁止共享它,重复检测门禁可能会标记这一对;两侧各自带测试并在注释中指名其孪生体。
-
-把这件事做错的最大代价,是把「未指定」当成「非法」。一条施加到 `undefined` 上的规则会打断每一条依赖 ambient 发现或 OAuth 鉴权的路由——`openai-codex` 根本无法接受 Key——而一个会拦截提交的空输入框,则会让改动任何其他设置都必须重新输入 Key。这两点都应落在测试里,而不只是写在本 Agent Note 中。
-
-早先版本已存下的 Key 会经 `resolveApiKey` 读取,因此一个非法的既存值将从解析时开始失败,而非到请求时才失败。这正是意图所在——诊断变好了——但对当前正持有这类值的人而言,失败点提前了。
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 1d9117dc85..0468e0e9d1 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -75,6 +75,25 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     await compareOrRefreshGolden(EMPTY_EXPECTED, snapshot, MODE)
   }, 60_000)
 
+  it('refuses a key no HTTP header can carry before anything is written', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-models-illegal-key'))
+    const dialog = page.getByRole('dialog', { name: '设置' })
+    const key = dialog.getByLabel('API 密钥')
+    const save = dialog.getByRole('button', { name: '保存', exact: true })
+
+    // The paste that used to save cleanly and then fail the first turn with a
+    // ByteString TypeError now names the field that holds it.
+    await key.fill('sk-\u{1F600}minimax')
+    await dialog.getByText('该 API 密钥含有无法发送的字符。请只粘贴原始密钥。').waitFor({ timeout: 10_000 })
+    await expect.poll(async () => save.isEnabled(), { timeout: 10_000 }).toBe(false)
+
+    // Clearing it restores submit: an empty field means "keep what is stored",
+    // never a refusal, or editing any other setting would demand the key.
+    await key.fill('')
+    await expect.poll(async () => save.isEnabled(), { timeout: 10_000 }).toBe(true)
+    expect(await dialog.getByText('该 API 密钥含有无法发送的字符。请只粘贴原始密钥。').count()).toBe(0)
+  }, 60_000)
+
   it('stores the key under the derived reference and the route registers live', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-models-add'))
     const dialog = page.getByRole('dialog', { name: '设置' })

From 8f2168303b246d2f4a988b29dbaae3e5794b2c5a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 6 Aug 2026 23:00:01 +0800
Subject: [PATCH 084/516] feat(web): add install metadata

---
 ...06-resolved-theme-color-metadata.i18n.yaml |  6 +++
 ...026-08-06-resolved-theme-color-metadata.md | 31 +++++++++++++++
 ...-08-06-resolved-theme-color-metadata.zh.md | 31 +++++++++++++++
 .../2026-08-06-web-install-manifest.i18n.yaml |  6 +++
 .../2026-08-06-web-install-manifest.md        | 39 +++++++++++++++++++
 .../2026-08-06-web-install-manifest.zh.md     | 39 +++++++++++++++++++
 apps/web/index.html                           |  1 +
 apps/web/public/manifest.webmanifest          | 16 ++++++++
 apps/web/tests/pwa-manifest.e2e.ts            | 27 +++++++++++++
 apps/web/tests/settings-chrome.e2e.ts         | 36 ++++++++++++++---
 packages/client/ui-layout/README.i18n.yaml    |  4 +-
 packages/client/ui-layout/README.md           |  2 +-
 packages/client/ui-layout/README.zh.md        |  2 +-
 .../ui-layout/src/client/theme-presenter.ts   | 26 ++++++++++---
 packages/client/ui-layout/tests/apply.spec.ts | 10 ++++-
 .../ui-layout/tests/theme-presenter.spec.ts   | 36 +++++++++++++++--
 .../host/frontend-static/README.i18n.yaml     |  4 +-
 packages/host/frontend-static/README.md       |  2 +-
 packages/host/frontend-static/README.zh.md    |  2 +-
 packages/host/frontend-static/src/index.ts    |  1 +
 .../tests/frontend-static.spec.ts             |  8 +++-
 21 files changed, 305 insertions(+), 24 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-web-install-manifest.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
 create mode 100644 apps/web/public/manifest.webmanifest
 create mode 100644 apps/web/tests/pwa-manifest.e2e.ts

diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
new file mode 100644
index 0000000000..7550af746a
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.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-08-06-resolved-theme-color-metadata.md
+2026-08-06-resolved-theme-color-metadata.md: 2f7a6f0bde5e75aeb6769939cae54d5319aa5bae
+2026-08-06-resolved-theme-color-metadata.zh.md: a6d530f841d5c744fc88831f9cb685d1ab5027b6
diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.md b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.md
new file mode 100644
index 0000000000..2f7a6f0bde
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.md
@@ -0,0 +1,31 @@
+# Agent Note: Resolved theme color metadata
+
+Status: implemented
+
+English | [中文](2026-08-06-resolved-theme-color-metadata.zh.md)
+
+## Problem
+
+The web client can resolve its theme independently of the operating-system preference, so a single manifest `theme_color` or media-qualified static metadata can disagree with an explicit Light or Dark selection. Browser chrome around an installed or ordinary page then need not match the app surface even though the layout presenter already owns the resolved document palette.
+
+## Decision
+
+The ui-layout `ThemePresenter` owns one `<meta name="theme-color">` alongside its root `color-scheme`, dark-palette attribute, and inline token writes. After applying a resolved snapshot's palette and token overrides, the presenter reads the body's computed `background-color` into the metadata element and inserts that single node into the document head. Subsequent snapshots update the same node, and disposal removes it.
+
+The rendered body background remains the color authority. The PWA manifest carries no static `theme_color` or `background_color`, and `ThemeDefinition` gains no second color field that could drift from the token palette. This also lets a registered theme's base-background token reach browser UI through the same application path as its page surface.
+
+## Verification
+
+The presenter unit contract covers light and dark computed colors, node reuse, and disposal. The ui-layout composition test covers initial insertion, event-driven reuse, and fiber cleanup. The Web browser settings scenario drives Light, Dark, System, operating-system changes, and reload through the shipped composition, asserting one metadata element whose content equals the computed body background with no console errors. The metadata change has no rendered accessibility-tree output, so the existing scenario golden remains unchanged.
+
+## Alternatives considered
+
+**Set `theme_color` in the manifest.** A manifest provides one app-wide value, so either built-in palette can disagree with it; the manifest deliberately omits the field.
+
+**Declare light and dark metadata with `prefers-color-scheme` media queries.** Media queries follow the operating system, not an explicit in-app selection, and therefore cannot represent the resolved preference.
+
+**Add a `themeColor` field to every `ThemeDefinition`.** A separate value gives custom themes an independent browser-chrome choice, but duplicates the base-background color and permits the page and surrounding UI to drift. A distinct field can be introduced if a supported theme needs that intentional difference.
+
+## Consequences
+
+Supporting browsers update surrounding UI after the client applies its initial resolved snapshot and after every theme change; browsers without `theme-color` support ignore the metadata. Because the value comes from computed presentation, the client must keep a concrete body background. The presenter creates and removes its own node, while unrelated head metadata remains untouched.
diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
new file mode 100644
index 0000000000..a6d530f841
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 基于解析后主题的颜色元数据
+
+Status: implemented
+
+[English](2026-08-06-resolved-theme-color-metadata.md) | 中文
+
+## 问题
+
+Web 客户端可以独立于操作系统偏好解析主题，因此 manifest（元数据清单）中单一的 `theme_color` 值或带媒体条件的静态元数据可能与显式选择的 Light 或 Dark 不一致。此时，无论是已安装页面还是普通页面，其周围的浏览器界面都未必与应用界面一致，尽管布局呈现器已经拥有解析后的 document 调色板。
+
+## 决策
+
+ui-layout 的 `ThemePresenter` 拥有一个 `<meta name="theme-color">`，与根元素上的 `color-scheme`、深色调色板属性和内联 token 写入并列。在应用解析后快照的调色板与 token 覆盖值之后，呈现器读取 body 计算样式中的 `background-color`，写入该元数据元素，再将该节点插入 document head。后续快照会更新同一节点，资源释放时则移除它。
+
+渲染后的 body 背景仍是颜色真源。PWA manifest 不包含静态 `theme_color` 或 `background_color`，`ThemeDefinition` 也不新增可能与 token 调色板偏离的第二个颜色字段。这样一来，注册主题的基础背景 token 也能通过页面界面使用的同一条应用路径作用于浏览器界面。
+
+## 验证
+
+呈现器的单元测试契约覆盖浅色和深色模式下的计算颜色、节点复用及资源释放。ui-layout 组合测试覆盖初始插入、事件驱动的复用和 fiber 清理。Web 浏览器设置场景通过实际交付的组合依次驱动 Light、Dark、System、操作系统偏好变化和重新加载，并断言页面始终只有一个元数据元素，其内容等于计算后的 body 背景且控制台无错误。这项元数据变更不会出现在渲染后的无障碍树输出中，因此场景现有的预期输出保持不变。
+
+## 曾考虑的替代方案
+
+**在 manifest 中设置 `theme_color`。** manifest 只能提供一个适用于整个应用的值，因此任一内置调色板都可能与之不一致；manifest 有意省略该字段。
+
+**用 `prefers-color-scheme` 媒体查询声明浅色和深色元数据。** 媒体查询跟随操作系统，而非应用内显式选择，因此无法表示解析后的偏好。
+
+**为每个 `ThemeDefinition` 添加 `themeColor` 字段。** 单独的值可让自定义主题独立选择浏览器界面配色，但会复制基础背景色，并允许页面与周围的浏览器界面发生偏离。如果受支持的主题需要这种有意差异，可以再引入独立字段。
+
+## 后果
+
+支持该元数据的浏览器会在客户端应用初始解析后快照及之后每次主题变化时更新周围界面；不支持 `theme-color` 的浏览器会忽略这项元数据。由于该值来自计算后的呈现结果，客户端必须确保 body 始终有明确的背景色。呈现器会创建并移除自己的节点，head 中无关的元数据则保持不变。
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
new file mode 100644
index 0000000000..d13ede02d2
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.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-08-06-web-install-manifest.md
+2026-08-06-web-install-manifest.md: d400c6e586f4b735fa8e3dcc4899c97e45ac89c1
+2026-08-06-web-install-manifest.zh.md: a7fee0248261e8d0597bb773d4f390973147337b
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.md b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.md
new file mode 100644
index 0000000000..d400c6e586
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.md
@@ -0,0 +1,39 @@
+# Agent Note: Web install manifest metadata
+
+Status: implemented
+
+English | [中文](2026-08-06-web-install-manifest.zh.md)
+
+## Problem
+
+The Web build has a document title and favicon but no manifest from which a browser can discover a stable installed identity, launch boundary, or installed presentation. Adding that metadata can also imply capabilities the app does not provide: a service worker suggests an offline contract, while a single language or palette value misrepresents a bilingual UI with resolved light and dark themes.
+
+## Decision
+
+The Web entry links `/manifest.webmanifest`, which Vite copies from `apps/web/public/` into the production build. The manifest names the product `DeepSeek Harness`, gives installed chrome the compact name `DSH`, and fixes `id`, `start_url`, and `scope` at `/`. It requests `display: "fullscreen"` so supporting browsers can give the installed editor-like surface the available display area while leaving ordinary tabs unchanged; browsers may apply user overrides or fall back to another display mode. Its icon entry reuses `/favicon.svg` as an SVG of size `any` and purpose `any`.
+
+This follows code-server's fullscreen choice without copying its `window-controls-overlay` display override. DSH has no custom title bar or layout around native window controls, so such an override would supersede fullscreen without owning the required safe layout.
+
+The manifest deliberately has no `lang`, `theme_color`, or `background_color`. The product surface is bilingual rather than owned by one manifest language, and either static color can disagree with one of the resolved app palettes. Theme metadata therefore remains outside the install manifest.
+
+This feature adds no service worker, cache policy, or offline fallback. The manifest supplies install metadata only; browser eligibility and install affordances remain browser policy. The shipped [`dsh-frontend-static`](../../../../packages/host/frontend-static/README.md) fallback recognizes `.webmanifest` as `application/manifest+json` so the same asset is valid through the shipped HTTP composition rather than only in Vite's output directory.
+
+## Verification
+
+The built-Web test parses the emitted manifest and pins the complete metadata object, including the human-visible name, compact name, icon, root identity, launch boundary, and display mode, while also verifying that the production `index.html` retains the link. The `dsh-frontend-static` real Loader composition test serves a `.webmanifest` fixture and pins its `application/manifest+json` media type.
+
+## Alternatives considered
+
+**Add a service worker and call the app offline-capable.** Rejected because caching the shell without defining session transport, invalidation, failure behavior, and upgrade semantics would create a misleading partial offline contract.
+
+**Declare one `lang`.** Rejected because no single language describes the bilingual product surface; omission avoids claiming that one locale owns the installed experience.
+
+**Choose one static background and theme color.** Rejected because the app resolves light and dark palettes at runtime, so either fixed value is knowingly wrong for one supported state.
+
+**Ship raster and maskable icon variants immediately.** Rejected until a supported installation target demonstrates a requirement the existing scalable favicon cannot meet. New variants remain an additive manifest change rather than a prerequisite for exposing the current identity.
+
+**Assert only root and display fields in the built artifact.** Rejected because dropping or changing the product name, compact name, or icon is also a shipped install regression. The test intentionally requires an explicit edit whenever any manifest metadata changes.
+
+## Consequences
+
+Supporting browsers can discover a stable root-scoped installed identity and fullscreen preference without the application promising offline behavior. Deploying this build below a path prefix requires revisiting the absolute link, identity, launch, scope, and icon URLs together. Browser-specific icon requirements may add variants later, and every intentional metadata change updates the exact built-artifact contract.
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
new file mode 100644
index 0000000000..a7fee02482
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: Web 安装 manifest 元数据
+
+Status: implemented
+
+[English](2026-08-06-web-install-manifest.md) | 中文
+
+## 问题
+
+Web 构建产物已有文档标题和 favicon，却没有可供浏览器发现稳定安装身份、启动边界或安装后呈现方式的 manifest（元数据清单）。添加这类元数据也可能暗示应用并不具备的能力：service worker 会让人以为应用提供离线契约，而单一语言或调色板取值会错误描述这个能够解析浅色与深色主题的双语 UI。
+
+## 决策
+
+Web 入口链接 `/manifest.webmanifest`，Vite 会将其从 `apps/web/public/` 复制到生产构建产物。manifest 将产品命名为 `DeepSeek Harness`，为安装后的浏览器界面提供简称 `DSH`，并把 `id`、`start_url` 和 `scope` 固定为 `/`。它请求 `display: "fullscreen"`，使支持这一模式的浏览器能够把可用显示区域交给安装后的编辑器式界面，同时不改变普通标签页；浏览器可以应用用户覆盖设置，或回退到其他显示模式。其图标条目复用 `/favicon.svg`，将它作为尺寸为 `any`、用途为 `any` 的 SVG。
+
+这一选择沿用了 code-server 的全屏方案，但没有照搬其 `window-controls-overlay` 显示覆盖项。DSH 没有自定义标题栏，也没有围绕原生窗口控件安排布局，因此使用这类覆盖项会在未落实所需安全布局的情况下取代全屏模式。
+
+manifest 有意不包含 `lang`、`theme_color` 或 `background_color`。产品界面支持双语，并不由 manifest 中的单一语言定义；任一静态颜色值都可能与应用解析后的一套调色板不一致。因此，主题元数据仍放在安装 manifest 之外。
+
+该功能不添加 service worker、缓存策略或离线回退。manifest 只提供安装元数据；是否具备安装资格、是否提供安装入口仍由浏览器策略决定。实际交付的 [`dsh-frontend-static`](../../../../packages/host/frontend-static/README.md) 回退将 `.webmanifest` 识别为 `application/manifest+json`，因此同一资产经实际交付的 HTTP 组合提供时同样有效，而不只在 Vite 输出目录中有效。
+
+## 验证
+
+Web 构建产物测试解析输出的 manifest，并固定完整的元数据对象，包括面向用户显示的名称、简称、图标、根路径身份、启动边界和显示模式，同时验证生产构建的 `index.html` 仍保留该链接。`dsh-frontend-static` 的真实 Loader 组合测试提供一个 `.webmanifest` fixture（测试前置数据），并固定其 `application/manifest+json` 媒体类型。
+
+## 曾考虑的替代方案
+
+**添加 service worker，并宣称应用支持离线。** 不予采纳，因为只缓存应用外壳，却不定义会话传输、失效策略、失败行为和升级语义，会形成具有误导性的不完整离线契约。
+
+**声明单一的 `lang`。** 不予采纳，因为没有任何一种语言足以描述双语产品界面；省略该字段可避免声称安装后的体验由某一种区域设置独占。
+
+**选择一组静态背景色和主题色。** 不予采纳，因为应用会在运行时解析浅色和深色调色板，因此选择任一固定值，都是明知它与其中一种受支持状态不符。
+
+**立即交付光栅和可遮罩图标变体。** 在某个受支持的安装目标证明现有可缩放 favicon 无法满足其要求之前，不予采纳。新变体只是对 manifest 的增量扩展，并非公开当前身份的前提。
+
+**只断言构建产物中的根路径字段和显示字段。** 不予采纳，因为产品名称、简称或图标被删除或更改，同样属于已交付安装体验的回归。任何 manifest 元数据发生变化时，测试都有意要求显式改动。
+
+## 后果
+
+支持这一机制的浏览器可以发现以根路径为作用域的稳定安装身份和全屏偏好，而应用无需承诺离线行为。在路径前缀下部署该构建产物时，必须同时重新审视绝对路径的 manifest 链接，以及身份、启动、作用域和图标 URL。日后可能因浏览器特有的图标要求而新增变体；每一项有意的元数据变更都会同步更新精确的构建产物契约。
diff --git a/apps/web/index.html b/apps/web/index.html
index c9fc7d124c..a14de72d40 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -3,6 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="manifest" href="/manifest.webmanifest" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>DeepSeek Harness</title>
   </head>
diff --git a/apps/web/public/manifest.webmanifest b/apps/web/public/manifest.webmanifest
new file mode 100644
index 0000000000..20a428fee6
--- /dev/null
+++ b/apps/web/public/manifest.webmanifest
@@ -0,0 +1,16 @@
+{
+  "id": "/",
+  "name": "DeepSeek Harness",
+  "short_name": "DSH",
+  "start_url": "/",
+  "scope": "/",
+  "display": "fullscreen",
+  "icons": [
+    {
+      "src": "/favicon.svg",
+      "sizes": "any",
+      "type": "image/svg+xml",
+      "purpose": "any"
+    }
+  ]
+}
diff --git a/apps/web/tests/pwa-manifest.e2e.ts b/apps/web/tests/pwa-manifest.e2e.ts
new file mode 100644
index 0000000000..696e1c7797
--- /dev/null
+++ b/apps/web/tests/pwa-manifest.e2e.ts
@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import { expect, it } from 'vitest'
+
+const DIST_ROOT = fileURLToPath(new URL('../dist', import.meta.url))
+
+it('ships install metadata with the built web application', async () => {
+  const index = await readFile(join(DIST_ROOT, 'index.html'), 'utf8')
+  expect(index).toContain('<link rel="manifest" href="/manifest.webmanifest" />')
+
+  const manifest: unknown = JSON.parse(await readFile(join(DIST_ROOT, 'manifest.webmanifest'), 'utf8'))
+  expect(manifest).toEqual({
+    id: '/',
+    name: 'DeepSeek Harness',
+    short_name: 'DSH',
+    start_url: '/',
+    scope: '/',
+    display: 'fullscreen',
+    icons: [{
+      src: '/favicon.svg',
+      sizes: 'any',
+      type: 'image/svg+xml',
+      purpose: 'any',
+    }],
+  })
+})
diff --git a/apps/web/tests/settings-chrome.e2e.ts b/apps/web/tests/settings-chrome.e2e.ts
index 43500585d8..e6b10664af 100644
--- a/apps/web/tests/settings-chrome.e2e.ts
+++ b/apps/web/tests/settings-chrome.e2e.ts
@@ -1,7 +1,8 @@
 // Web e2e scenarios: the settings surface — the modal shell (trigger, nav,
 // section switching, both close paths), the Appearance preference row (the
 // real theme gesture — click 深色 and the whole cascade runs: ThemeService preference -> localStorage dsh.theme
-// -> theme/change -> ui-layout's presenter -> body attribute -> alias token)
+// -> theme/change -> ui-layout's presenter -> body attribute -> alias token +
+// browser theme-color metadata)
 // the Language row (settings-scoped localization + persisted dsh.locale),
 // the busy-state Enter preference, plus Permission as the persisted default
 // for subsequently created sessions.
@@ -154,17 +155,37 @@ describe('web e2e: settings modal and General preferences', () => {
 
   it('flips the theme through the Appearance cubes and persists across reload', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-settings-appearance'))
-    const readState = async (): Promise<{ attr: boolean; token: string; stored: string | null }> =>
-      await page.evaluate(() => ({
+    interface ThemeState {
+      attr: boolean
+      background: string
+      stored: string | null
+      themeColor: string | null
+      themeColorCount: number
+      token: string
+    }
+    const readState = async (): Promise<ThemeState> => await page.evaluate(() => {
+      const metas = document.head.querySelectorAll<HTMLMetaElement>('meta[name="theme-color"]')
+      const computed = getComputedStyle(document.body)
+      return {
         attr: document.body.hasAttribute('data-ds-dark-theme'),
-        token: getComputedStyle(document.body).getPropertyValue('--dsw-alias-bg-base').trim(),
+        background: computed.backgroundColor,
         stored: localStorage.getItem('dsh.theme'),
-      }))
+        themeColor: metas[0]?.content ?? null,
+        themeColorCount: metas.length,
+        token: computed.getPropertyValue('--dsw-alias-bg-base').trim(),
+      }
+    })
+    const expectThemeColorSynchronized = (state: ThemeState): void => {
+      expect(state.themeColorCount).toBe(1)
+      expect(state.background).not.toBe('rgba(0, 0, 0, 0)')
+      expect(state.themeColor).toBe(state.background)
+    }
     // Pin the OS scheme to light so the default `system` preference resolves
     // light and the dark flip below is unambiguously the gesture's doing.
     await page.emulateMedia({ colorScheme: 'light' })
     const light = await readState()
     expect(light.attr).toBe(false)
+    expectThemeColorSynchronized(light)
 
     await page.getByRole('button', { name: '设置', exact: true }).click()
     const dialog = page.getByRole('dialog', { name: '设置' })
@@ -179,6 +200,7 @@ describe('web e2e: settings modal and General preferences', () => {
     expect(dark.attr).toBe(true)
     expect(dark.stored).toBe('dark')
     expect(dark.token).not.toBe(light.token)
+    expectThemeColorSynchronized(dark)
     await page.keyboard.press('Escape')
 
     // Reload: the preference survives boot (restore + presenter initial apply).
@@ -190,6 +212,7 @@ describe('web e2e: settings modal and General preferences', () => {
     const reloaded = await readState()
     expect(reloaded.attr).toBe(true)
     expect(reloaded.stored).toBe('dark')
+    expectThemeColorSynchronized(reloaded)
 
     // `system` follows the emulated OS scheme (dark stays dark, light clears).
     await page.getByRole('button', { name: '设置', exact: true }).click()
@@ -197,12 +220,15 @@ describe('web e2e: settings modal and General preferences', () => {
     await systemCube.click()
     await expect.poll(() => systemCube.getAttribute('aria-pressed'), { timeout: 5_000 }).toBe('true')
     await expect.poll(async () => (await readState()).attr, { timeout: 5_000 }).toBe(false)
+    expectThemeColorSynchronized(await readState())
     await page.emulateMedia({ colorScheme: 'dark' })
     await expect.poll(async () => (await readState()).attr, { timeout: 5_000 }).toBe(true)
+    expectThemeColorSynchronized(await readState())
     // Restore for the specs that follow: light preference beats the emulated
     // dark OS scheme, leaving the shared page in the light default.
     await page.getByRole('dialog', { name: '设置' }).getByRole('button', { name: '浅色' }).click()
     await expect.poll(async () => (await readState()).attr, { timeout: 5_000 }).toBe(false)
+    expectThemeColorSynchronized(await readState())
     await page.keyboard.press('Escape')
     expect(tripwire.pageErrors).toEqual([])
   }, 90_000)
diff --git a/packages/client/ui-layout/README.i18n.yaml b/packages/client/ui-layout/README.i18n.yaml
index 8b5aff5db5..d04c06b3da 100644
--- a/packages/client/ui-layout/README.i18n.yaml
+++ b/packages/client/ui-layout/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/client/ui-layout/README.md
-README.md: 5cb8f01efb2e18109e917225dbce088ea77394af
-README.zh.md: 6559fe595a6219b139fe46cf046906fa63636f64
+README.md: fa60520a20ac8a7f25d494879c68efb06a28998f
+README.zh.md: 6ca04c56c29a55f84fc7a6399a7feeb81d249899
diff --git a/packages/client/ui-layout/README.md b/packages/client/ui-layout/README.md
index 5cb8f01efb..fa60520a20 100644
--- a/packages/client/ui-layout/README.md
+++ b/packages/client/ui-layout/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shell plugin: three-column AppFrame (drag handles and concession chain) plus the `ctx.layout` panel-geometry service; it registers into the runtime-owned `root` slot and declares `sidebar`, `conversation`, `details`, and `conversation.empty`. The sidebar resize boundary is an invisible hit strip, while the details boundary retains its floating pill; only details shrinks during concession and then auto-closes. A closed sidebar retains a 56px control rail while details closes to zero width. The package also seats the theme presenter: it consumes resolved `ctx.theme` snapshots and projects them onto the document (`html { color-scheme }` for native UA chrome, `body[data-ds-dark-theme]` from the active color scheme, plus the theme's alias tokens as inline variables on body).
+Shell plugin: three-column AppFrame (drag handles and concession chain) plus the `ctx.layout` panel-geometry service; it registers into the runtime-owned `root` slot and declares `sidebar`, `conversation`, `details`, and `conversation.empty`. The sidebar resize boundary is an invisible hit strip, while the details boundary retains its floating pill; only details shrinks during concession and then auto-closes. A closed sidebar retains a 56px control rail while details closes to zero width. The package also seats the theme presenter: it consumes resolved `ctx.theme` snapshots and projects them onto the document (`html { color-scheme }` for native UA chrome, `body[data-ds-dark-theme]` from the active color scheme, the theme's alias tokens as inline variables on body, and one owned `<meta name="theme-color">` whose content follows the computed body background). Measuring after palette and token application keeps the rendered background as the single color authority; disposing the presenter removes its metadata node with its other global writes.
 
 AppFrame always mounts the conversation and details columns; a connected Session renders through `SessionProvider`. The transient layout store starts the sidebar at its default width and details closed, and it never reads or writes `localStorage`. Hero and other unselected states also derive a zero rendered details width without changing that stored preference. AppFrame retains the last non-blank Session id across those states: the first Session remains closed, an explicit details action opens the contract default width, returning to the same Session restores its unchanged width, and selecting a different Session closes details before paint. The conversation owner share is empty, while the sidebar owner share contains only `collapsed` and `width`; registrants obtain business data from standard hooks and actions from their own inject faces.
 
diff --git a/packages/client/ui-layout/README.zh.md b/packages/client/ui-layout/README.zh.md
index 6559fe595a..6ca04c56c2 100644
--- a/packages/client/ui-layout/README.zh.md
+++ b/packages/client/ui-layout/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏的缩放边界是不可见命中条带，详情栏边界则保留其浮动胶囊；让步期间只有详情栏会收缩并随后自动关闭。关闭的侧边栏仍保留 56px 控制栏，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量）。
+外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏的缩放边界是不可见命中条带，详情栏边界则保留其浮动胶囊；让步期间只有详情栏会收缩并随后自动关闭。关闭的侧边栏仍保留 56px 控制栏，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量，同时拥有一个 `<meta name="theme-color">`，其内容随计算后的 body 背景色更新）。在应用调色板和 token 后进行测量，可确保渲染后的背景保持为唯一颜色真源；呈现器在资源释放时会移除其自有的元数据节点，并一并清除其写入的其他全局状态。
 
 AppFrame 始终挂载会话栏和详情栏；已连接 Session 通过 `SessionProvider` 渲染。布局 store 是瞬时状态，侧边栏以默认宽度启动，详情栏则保持关闭，且该 store 从不读写 `localStorage`。hero 和其他未选中状态也会将详情栏的渲染宽度派生为零，但不会改变存储的宽度偏好。AppFrame 会跨越这些状态保留最后一个非 blank 会话 id：首个会话保持关闭；显式打开详情栏的操作会使用契约默认宽度；返回同一会话时恢复其未改变的宽度；选择不同会话时，详情栏会在绘制前关闭。会话 owner share 为空，侧边栏 owner share 只包含 `collapsed` 和 `width`；注册方通过标准钩子获取业务数据，并从各自的 inject 接口获取操作。
 
diff --git a/packages/client/ui-layout/src/client/theme-presenter.ts b/packages/client/ui-layout/src/client/theme-presenter.ts
index 07dc663c54..87e3592798 100644
--- a/packages/client/ui-layout/src/client/theme-presenter.ts
+++ b/packages/client/ui-layout/src/client/theme-presenter.ts
@@ -1,10 +1,11 @@
 /**
  * Global theme DOM applier: projects the resolved ThemeSnapshot onto the
  * document — `html { color-scheme }` for native UA chrome (scrollbars, form
- * controls), `body[data-ds-dark-theme]` for the token palette, and the active
- * theme's alias-token overrides as inline CSS variables on body. Pure DOM
- * writes, no React involvement; the presenter only ever retracts what it wrote
- * itself, so foreign attributes and inline styles survive apply/dispose.
+ * controls), `body[data-ds-dark-theme]` for the token palette, the active
+ * theme's alias-token overrides as inline CSS variables on body, and one
+ * presenter-owned `meta[name="theme-color"]` for surrounding browser UI. Pure
+ * DOM writes, no React involvement; the presenter only ever retracts what it
+ * wrote itself, so foreign attributes, metadata, and inline styles survive.
  */
 import type { ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
 
@@ -15,12 +16,22 @@ export const DARK_ATTRIBUTE = 'data-ds-dark-theme'
 export class ThemePresenter {
   /** Token names this presenter wrote in the last apply (its retraction set). */
   private appliedTokens: string[] = []
+  /** The single metadata node this presenter inserts and removes. */
+  private readonly themeColorMeta: HTMLMetaElement
+
+  /** Create the presenter-owned metadata node before the first snapshot arrives. */
+  constructor() {
+    this.themeColorMeta = document.createElement('meta')
+    this.themeColorMeta.name = 'theme-color'
+  }
 
   /**
    * Project a snapshot onto the document: set root `color-scheme` and the body
    * palette attribute from `active.colorScheme` (never the id — `system` is
    * resolved upstream), then replace the previously applied token variables
-   * with `active.tokens`.
+   * with `active.tokens`. Browser theme-color metadata follows the computed
+   * body background after those writes, so the rendered palette remains the
+   * color authority.
    * @param snapshot - resolved theme snapshot from ctx.theme.
    */
   apply(snapshot: ThemeSnapshot): void {
@@ -35,14 +46,17 @@ export class ThemePresenter {
       body.style.setProperty(name, value)
       this.appliedTokens.push(name)
     }
+    this.themeColorMeta.content = getComputedStyle(body).backgroundColor
+    if (!this.themeColorMeta.isConnected) document.head.append(this.themeColorMeta)
   }
 
-  /** Retract everything this presenter wrote: root color-scheme, the palette attribute, and all applied token variables. */
+  /** Retract root color-scheme, the palette attribute, token variables, and the owned metadata node. */
   dispose(): void {
     document.documentElement.style.removeProperty('color-scheme')
     const body = document.body
     body.removeAttribute(DARK_ATTRIBUTE)
     for (const name of this.appliedTokens) body.style.removeProperty(name)
     this.appliedTokens = []
+    this.themeColorMeta.remove()
   }
 }
diff --git a/packages/client/ui-layout/tests/apply.spec.ts b/packages/client/ui-layout/tests/apply.spec.ts
index 903591163c..af85c1c5ae 100644
--- a/packages/client/ui-layout/tests/apply.spec.ts
+++ b/packages/client/ui-layout/tests/apply.spec.ts
@@ -7,7 +7,7 @@
 // coverage gate still requires exercised.
 
 import { Context } from 'cordis'
-import { describe, expect, it, vi } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { apply as themeApply, inject as themeInject, ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
@@ -15,6 +15,10 @@ import { apply, inject, LayoutService } from '@deepseek-ai/dsh-client-ui-layout/
 import { apply as nodeApply } from '@deepseek-ai/dsh-client-ui-layout'
 import * as invariant from '@deepseek-ai/dsh-client-ui-layout/invariant'
 
+beforeEach(() => {
+  document.head.querySelectorAll('meta[name="theme-color"]').forEach((node) => { node.remove() })
+})
+
 async function bench() {
   const ctx = new Context()
   const slotsFiber = ctx.plugin(SlotsService)
@@ -65,13 +69,17 @@ describe('ui-layout client apply', () => {
     // Initial getter application: jsdom has no matchMedia, system resolves light.
     expect(document.documentElement.style.colorScheme).toBe('light')
     expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(false)
+    const themeColorMeta = document.head.querySelector<HTMLMetaElement>('meta[name="theme-color"]')
+    expect(themeColorMeta).not.toBeNull()
     const theme = ctx.get('theme') as ThemeService
     theme.setTheme('dark')
     expect(document.documentElement.style.colorScheme).toBe('dark')
     expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(true)
+    expect(document.head.querySelector('meta[name="theme-color"]')).toBe(themeColorMeta)
     await fiber.dispose()
     expect(document.documentElement.style.colorScheme).toBe('')
     expect(document.body.hasAttribute('data-ds-dark-theme')).toBe(false)
+    expect(themeColorMeta?.isConnected).toBe(false)
     // Listener is off: further theme changes no longer reach the document.
     theme.setTheme('light')
     theme.setTheme('dark')
diff --git a/packages/client/ui-layout/tests/theme-presenter.spec.ts b/packages/client/ui-layout/tests/theme-presenter.spec.ts
index a14d781e5f..36a4975fc9 100644
--- a/packages/client/ui-layout/tests/theme-presenter.spec.ts
+++ b/packages/client/ui-layout/tests/theme-presenter.spec.ts
@@ -1,40 +1,68 @@
 // @vitest-environment jsdom
 // ThemePresenter behavior account: root color-scheme and the palette attribute
 // follow active.colorScheme only, token variables replace the previous apply's
-// set, and dispose retracts everything the presenter wrote.
+// set, theme-color metadata follows the rendered body background, and dispose
+// retracts everything the presenter wrote.
 
-import { beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import type { ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
 import { DARK_ATTRIBUTE, ThemePresenter } from '@deepseek-ai/dsh-client-ui-layout/src/client/theme-presenter.ts'
 
+const LIGHT_THEME_COLOR = 'rgb(255, 255, 255)'
+const DARK_THEME_COLOR = 'rgb(21, 21, 23)'
+
 function snapshot(colorScheme: 'light' | 'dark', tokens: Record<string, string> = {}): ThemeSnapshot {
   // The presenter must key off colorScheme, not the id — keep them distinct.
   const active = { id: `${colorScheme}-test`, colorScheme, tokens }
   return { preference: colorScheme, active, themes: [active], revision: 1 }
 }
 
+function clearThemePresentation(): void {
+  document.head.querySelectorAll('meta[name="theme-color"], style[data-theme-presenter-test]').forEach((node) => { node.remove() })
+}
+
+function themeColorMeta(): HTMLMetaElement | null {
+  return document.head.querySelector<HTMLMetaElement>('meta[name="theme-color"]')
+}
+
 beforeEach(() => {
+  clearThemePresentation()
   document.documentElement.style.removeProperty('color-scheme')
   document.body.removeAttribute(DARK_ATTRIBUTE)
   document.body.removeAttribute('style')
+  const style = document.createElement('style')
+  style.dataset.themePresenterTest = ''
+  style.textContent = `
+    body { background-color: ${LIGHT_THEME_COLOR}; }
+    body[${DARK_ATTRIBUTE}] { background-color: ${DARK_THEME_COLOR}; }
+  `
+  document.head.append(style)
 })
 
+afterEach(clearThemePresentation)
+
 describe('ThemePresenter', () => {
   it('light scheme sets root color-scheme and leaves the dark attribute absent', () => {
     const presenter = new ThemePresenter()
     presenter.apply(snapshot('light'))
     expect(document.documentElement.style.colorScheme).toBe('light')
     expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(false)
+    expect(themeColorMeta()?.content).toBe(LIGHT_THEME_COLOR)
   })
 
-  it('dark scheme sets root color-scheme and the attribute; switching to light clears both', () => {
+  it('dark scheme sets root color-scheme, the attribute, and metadata; switching to light updates one node', () => {
     const presenter = new ThemePresenter()
     presenter.apply(snapshot('dark'))
+    const meta = themeColorMeta()
     expect(document.documentElement.style.colorScheme).toBe('dark')
     expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(true)
+    expect(meta?.content).toBe(DARK_THEME_COLOR)
     presenter.apply(snapshot('light'))
     expect(document.documentElement.style.colorScheme).toBe('light')
     expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(false)
+    expect(themeColorMeta()).toBe(meta)
+    expect(meta?.content).toBe(LIGHT_THEME_COLOR)
+    expect(document.head.querySelectorAll('meta[name="theme-color"]')).toHaveLength(1)
   })
 
   it('applies tokens as inline variables and clears the previous set on theme change', () => {
@@ -52,10 +80,12 @@ describe('ThemePresenter', () => {
     document.body.style.setProperty('--foreign', 'kept')
     const presenter = new ThemePresenter()
     presenter.apply(snapshot('dark', { '--dsw-alias-bg': '#111' }))
+    const meta = themeColorMeta()
     presenter.dispose()
     expect(document.documentElement.style.colorScheme).toBe('')
     expect(document.body.hasAttribute(DARK_ATTRIBUTE)).toBe(false)
     expect(document.body.style.getPropertyValue('--dsw-alias-bg')).toBe('')
     expect(document.body.style.getPropertyValue('--foreign')).toBe('kept')
+    expect(meta?.isConnected).toBe(false)
   })
 })
diff --git a/packages/host/frontend-static/README.i18n.yaml b/packages/host/frontend-static/README.i18n.yaml
index 07d337775e..9d757aaf6c 100644
--- a/packages/host/frontend-static/README.i18n.yaml
+++ b/packages/host/frontend-static/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/host/frontend-static/README.md
-README.md: c3a831abb1060b59e1802d38d5407a29d24e3bb3
-README.zh.md: d4dc71763280a3c88c73de50f63f2615570c7182
+README.md: 82ba5a2cd0937e2c24505648aa1e3daec6bf2ece
+README.zh.md: 1130aa7cc241ee5245fceaba0ef66fcf95871e67
diff --git a/packages/host/frontend-static/README.md b/packages/host/frontend-static/README.md
index c3a831abb1..82ba5a2cd0 100644
--- a/packages/host/frontend-static/README.md
+++ b/packages/host/frontend-static/README.md
@@ -16,4 +16,4 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **The starter MIME table is minimal** — extensions beyond the vite-emitted set fall back to `application/octet-stream`; extend the table when an asset class actually ships.
+- **The starter MIME table is minimal** — it covers the Vite-emitted asset set plus the shipped PWA manifest; other extensions fall back to `application/octet-stream` until an asset class actually ships.
diff --git a/packages/host/frontend-static/README.zh.md b/packages/host/frontend-static/README.zh.md
index d4dc717632..1130aa7cc2 100644
--- a/packages/host/frontend-static/README.zh.md
+++ b/packages/host/frontend-static/README.zh.md
@@ -16,4 +16,4 @@ Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`）
 
 ## 已知限制与延期工作
 
-- **初始 MIME 表很精简**：vite 输出集合以外的扩展名会回退到 `application/octet-stream`；实际发布新的资产类别时再扩展该表。
+- **初始 MIME 表很精简**：它覆盖 Vite 输出的资产集合及实际交付的 PWA manifest；其他扩展名在相应资产类别实际发布前都会回退到 `application/octet-stream`。
diff --git a/packages/host/frontend-static/src/index.ts b/packages/host/frontend-static/src/index.ts
index 4d5032c2d2..8bd5b829c1 100644
--- a/packages/host/frontend-static/src/index.ts
+++ b/packages/host/frontend-static/src/index.ts
@@ -41,6 +41,7 @@ const MIME: Record<string, string> = {
   '.svg': 'image/svg+xml',
   '.json': 'application/json',
   '.map': 'application/json',
+  '.webmanifest': 'application/manifest+json',
 }
 
 /**
diff --git a/packages/host/frontend-static/tests/frontend-static.spec.ts b/packages/host/frontend-static/tests/frontend-static.spec.ts
index e35e54bb05..4f5fa0d2c7 100644
--- a/packages/host/frontend-static/tests/frontend-static.spec.ts
+++ b/packages/host/frontend-static/tests/frontend-static.spec.ts
@@ -36,6 +36,7 @@ async function loadComposition(): Promise<Context> {
   await writeFile(distIndex, '<head></head><body>shell</body>')
   await writeFile(join(dist, 'app.js'), 'export {}')
   await writeFile(join(dist, 'blob.bin'), 'BLOB')
+  await writeFile(join(dist, 'manifest.webmanifest'), '{}')
   const configPath = join(root, 'cordis.yml')
   await writeFile(configPath, [
     "- name: '@deepseek-ai/dsh-host-webserver'",
@@ -92,8 +93,13 @@ describe('real Loader composition', () => {
     const server = loaded.httpServer
     const port = server.port
 
-    // Real asset with its MIME type; a live rebuild is served on the next read.
+    // Real assets with their MIME types; a live rebuild is served on the next read.
     expect(await request(port, '/app.js')).toMatchObject({ status: 200, type: 'text/javascript; charset=utf-8', body: 'export {}' })
+    expect(await request(port, '/manifest.webmanifest')).toMatchObject({
+      status: 200,
+      type: 'application/manifest+json',
+      body: '{}',
+    })
     await writeFile(join(root!, 'dist', 'app.js'), 'export const rebuilt = true')
     expect(await request(port, '/app.js')).toMatchObject({ status: 200, body: 'export const rebuilt = true' })
 

From 6b75bb0425bad75fdaa9cb7a1be932ee8276b758 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 6 Aug 2026 23:15:08 +0800
Subject: [PATCH 085/516] fix(web): say the API key format is wrong rather than
 naming the characters

---
 apps/web/tests/models-settings.e2e.ts           | 4 ++--
 packages/client/ui-models/src/client/locales.ts | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 0468e0e9d1..e5e7d09c5f 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -84,14 +84,14 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     // The paste that used to save cleanly and then fail the first turn with a
     // ByteString TypeError now names the field that holds it.
     await key.fill('sk-\u{1F600}minimax')
-    await dialog.getByText('该 API 密钥含有无法发送的字符。请只粘贴原始密钥。').waitFor({ timeout: 10_000 })
+    await dialog.getByText('该 API 密钥格式错误，请检查。').waitFor({ timeout: 10_000 })
     await expect.poll(async () => save.isEnabled(), { timeout: 10_000 }).toBe(false)
 
     // Clearing it restores submit: an empty field means "keep what is stored",
     // never a refusal, or editing any other setting would demand the key.
     await key.fill('')
     await expect.poll(async () => save.isEnabled(), { timeout: 10_000 }).toBe(true)
-    expect(await dialog.getByText('该 API 密钥含有无法发送的字符。请只粘贴原始密钥。').count()).toBe(0)
+    expect(await dialog.getByText('该 API 密钥格式错误，请检查。').count()).toBe(0)
   }, 60_000)
 
   it('stores the key under the derived reference and the route registers live', async () => {
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index fbfc85c7f1..0d50c03e63 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -47,7 +47,7 @@ export const en = {
   removeModel: 'Delete model',
   modelsEmpty: 'No models will be shown in the selector. Unlisted IDs can still be sent directly.',
   keyBlank: 'Enter the API key, or leave the field empty to keep the stored one.',
-  keyIllegalCharacters: 'This API key contains characters that cannot be sent. Paste the raw key only.',
+  keyIllegalCharacters: 'This API key is not in a valid format. Please check it.',
   keyLooksWrapped: 'Paste only the key itself — not a NAME=value line, and without surrounding quotes.',
   modelIdRequired: 'Model ID is required.',
   modelIdDuplicate: 'Model ID must be unique.',
@@ -134,7 +134,7 @@ export const zh: typeof en = {
   removeModel: '删除模型',
   modelsEmpty: '模型选择器中将不显示任何模型；目录外 ID 仍可直接发送。',
   keyBlank: '请输入 API 密钥；留空则保持已存储的密钥。',
-  keyIllegalCharacters: '该 API 密钥含有无法发送的字符。请只粘贴原始密钥。',
+  keyIllegalCharacters: '该 API 密钥格式错误，请检查。',
   keyLooksWrapped: '请只粘贴密钥本身——不要带 NAME=value 整行，也不要带引号。',
   modelIdRequired: '模型 ID 不能为空。',
   modelIdDuplicate: '模型 ID 不能重复。',

From 1019f149c4e4ad2b75d7c9a15e0976ceaa05e7c7 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 11:02:38 +0800
Subject: [PATCH 086/516] =?UTF-8?q?fix(web,llm):=20address=20review=20?=
 =?UTF-8?q?=E2=80=94=20document=20the=20card=20contract,=20pin=20the=20hos?=
 =?UTF-8?q?t=20diagnosis,=20gate=20the=20probe?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/cordis-catalog/services.md               |  2 +-
 .../headless-agent/tests/headless.snapshot.ts | 40 +++++++++++++++++++
 .../stream-json.expected.jsonl                | 12 ++++++
 packages/client/ui-models/README.i18n.yaml    |  4 +-
 packages/client/ui-models/README.md           |  2 +-
 packages/client/ui-models/README.zh.md        |  2 +-
 .../src/client/CustomProviderCard.tsx         |  8 +++-
 .../ui-models/src/client/ModelListEditor.tsx  | 13 +++++-
 .../ui-models/src/client/ProviderEditor.tsx   |  2 +-
 .../client/ui-models/src/client/locales.ts    |  2 +
 .../ui-models/tests/provider-form.spec.tsx    | 13 ++++++
 .../llm/llm-pi-ai/tests/discovery.spec.ts     |  6 ++-
 packages/llm/llm/src/index.ts                 | 11 +++--
 packages/llm/llm/tests/api-key.spec.ts        |  2 +-
 14 files changed, 104 insertions(+), 15 deletions(-)
 create mode 100644 examples/headless-agent/tests/snapshots/invalid-credential/stream-json.expected.jsonl

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 6b30d80751..d71619b7d9 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -941,7 +941,7 @@ stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 
 Types: [AdapterRegistrationHandle](../core-data-structures/core.md) · [DirectoryRegistrationHandle](../core-data-structures/core.md) · [GenerateOptions](../core-data-structures/core.md) · [LlmAdapter](../core-data-structures/llm-streaming.md) · [LlmCallConfig](../core-data-structures/core.md) · [LlmConfigurableProvider](../core-data-structures/core.md) · [LlmDiscoveredModel](../core-data-structures/core.md) · [LlmModelDiscoveryRequest](../core-data-structures/core.md) · [LlmModelInfo](../core-data-structures/core.md) · [LlmProviderInfo](../core-data-structures/core.md) · [LlmResolvedModelInfo](../core-data-structures/core.md) · [PreparedLlmCall](../core-data-structures/llm-streaming.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:287`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
 
 ## `ctx.permission` — `PermissionService`
 
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index eb39254dac..9de860d2b5 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -31,6 +31,10 @@ const retryScenarioDir = join(snapshotsDir, 'provider-retry')
 const retryConfigPath = fileURLToPath(new URL('../retry.cordis.snapshot.yml', import.meta.url))
 const credentialsScenarioDir = join(snapshotsDir, 'missing-credential')
 const credentialsConfigPath = fileURLToPath(new URL('../credentials.cordis.snapshot.yml', import.meta.url))
+// Same keyless composition as the missing-credential scenario: the endpoint is
+// never dialed either way, because a supplied-but-unusable key fails credential
+// resolution exactly where an absent one does.
+const invalidCredentialScenarioDir = join(snapshotsDir, 'invalid-credential')
 const ralphScenarioDir = join(snapshotsDir, 'ralph-loop')
 const ralphConfigPath = fileURLToPath(new URL('../ralph.cordis.snapshot.yml', import.meta.url))
 const startupFailureConfigPath = fileURLToPath(new URL('./fixtures/startup-activation-error/cordis.yml', import.meta.url))
@@ -254,6 +258,42 @@ describe('headless stream-json snapshots', () => {
     expect(normalized).toContain('as a last resort')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
+  it('logs actionable invalid-credential guidance through the one-shot app', async () => {
+    const streamExpected = join(invalidCredentialScenarioDir, 'stream-json.expected.jsonl')
+    let runCwd = ''
+    const result = await runLoaderSmoke({
+      label: 'invalid-credential headless stream-json snapshot',
+      tempDirPrefix: 'headless-snapshot-invalid-credential-',
+      binScript,
+      configPath: credentialsConfigPath,
+      binArgs: ['--config', credentialsConfigPath, '--output-format', 'stream-json', 'say pong'],
+      tsconfigPath,
+      env: {
+        // A key that exists but no HTTP header can carry — the paste this
+        // change exists for. Before it, `fetch` refused to build the header
+        // and the turn ended on a retried ByteString TypeError.
+        DEEPSEEK_API_KEY: 'sk-\u{1F600}pasted-from-a-chat-window',
+        DEEPSEEK_BASE_URL: '',
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      prepare: (cwd) => { runCwd = cwd },
+    })
+
+    expect(result.stderr).toBe('')
+    const normalized = normalizeHeadlessStream(result.stdout, runCwd)
+    if (refreshing) await writeFile(streamExpected, normalized)
+    expect(normalized).toBe(await readFile(streamExpected, 'utf8'))
+    // The durable failure names the reference to correct and the writer that
+    // usually owns it, and stays true in a composition that mounts no Models
+    // page at all.
+    expect(normalized).toContain('the API key resolved from DEEPSEEK_API_KEY contains characters')
+    expect(normalized).toContain('the web Models page writes it')
+    // Neither the key nor the transport-level symptom it used to produce may
+    // reach the user: the code point of one character is still the key.
+    expect(normalized).not.toContain('pasted-from-a-chat-window')
+    expect(normalized).not.toContain('ByteString')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
   it('logs the model default and a dynamic next-step reasoning effort', async () => {
     const result = await runLoaderSmoke({
       label: 'reasoning effort headless stream-json snapshot',
diff --git a/examples/headless-agent/tests/snapshots/invalid-credential/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/invalid-credential/stream-json.expected.jsonl
new file mode 100644
index 0000000000..f521487e42
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/invalid-credential/stream-json.expected.jsonl
@@ -0,0 +1,12 @@
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"agent/inbox/spliced","seq":0,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"say pong"}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"}]}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/start","seq":1,"time":0,"data":{"turn":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"agent/inbox/spliced","seq":2,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":4,"time":0,"data":{"content":[{"type":"text","text":"say pong"}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"session/title","seq":5,"time":0,"data":{"title":"say pong","messageSeqs":[4],"source":{"kind":"fallback"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/header","seq":6,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/context","seq":7,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":1000000}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"llm-deepseek: the API key resolved from DEEPSEEK_API_KEY contains characters no HTTP header can carry; set DEEPSEEK_API_KEY to the raw key alone (the web Models page writes it)","code":"INVALID_CREDENTIAL"}}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":9,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":10,"time":0,"data":{"turn":1,"reason":{"kind":"error","error":{"message":"llm-deepseek: the API key resolved from DEEPSEEK_API_KEY contains characters no HTTP header can carry; set DEEPSEEK_API_KEY to the raw key alone (the web Models page writes it)","code":"INVALID_CREDENTIAL"}}}}}
+{"type":"result","sessionId":"{{sessionId}}","output":""}
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index ae296a91aa..3db62f6c31 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/client/ui-models/README.md
-README.md: b55914197e472edec8a8b6d4d3e02036d1697728
-README.zh.md: ca93c3d5a2a85fffb22707f8389f1e979468e2ec
+README.md: e3328bb5fd2cf812b05dc26bf534226818132631
+README.zh.md: 20e40cc571a9123b50dfb28565c5562937e03189
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index b55914197e..e3328bb5fd 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -8,7 +8,7 @@ Rows are the *configured* providers (their profile resolves in the owning namesp
 
 The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured literal `apiKey` secret sidecar or configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
 
-Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, the same shape the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
+Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, the same shape the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. A typed API key is judged on its own field the same way: after trimming, it must be non-empty and every character must be printable ASCII (`[\x21-\x7E]`), which is exactly what an HTTP header value can carry — the twin of `normalizeApiKey` in `@deepseek-ai/dsh-llm`, mirrored here because the source-plane split forbids importing it. A field holding only whitespace fails rather than being silently dropped, and a value shaped like a pasted `NAME=value` environment line or wrapped in matching quotes fails too; that paste-shape heuristic runs only in the browser, since a false positive in a resolver would leave the environment refusing the key as well. An empty field is not a failure at all: it means keep the stored key on an editor card, and authenticate some other way on a create card. A refused key blocks both the write and the endpoint interrogation, so the page never spends a round trip to be told what the field already says. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
 
 ## Model list and endpoint interrogation
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index ca93c3d5a2..20e40cc571 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -8,7 +8,7 @@
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
-每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，与 pi-ai 提供方表单采用的形态相同。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
+每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，与 pi-ai 提供方表单采用的形态相同。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。键入的 API 密钥同样在它自己的字段上被判定：trim 之后必须非空，且每个字符都是可打印 ASCII（`[\x21-\x7E]`）——这正是 HTTP 标头值所能承载的范围，是 `@deepseek-ai/dsh-llm` 中 `normalizeApiKey` 的孪生体，因源码平面分割禁止直接引入而在此镜像。只含空白的输入框会失败，而不是被静默丢弃；形如整行粘贴的 `NAME=value` 环境变量或首尾成对引号包裹的值也会失败——该粘贴形状启发式只在浏览器中运行，因为 resolver 中的一次误判会连带让环境变量这条路也拒绝该密钥。留空则完全不是失败：在编辑卡片上它意味着保持已存储的密钥，在新建卡片上则意味着以其他方式鉴权。被拒绝的密钥会同时拦截写入与端点探测，因此页面不会白花一次往返去换取字段上已经写明的答案。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
 
 ## 模型列表与端点询问
 
diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index a252d99586..a610f2f140 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -215,7 +215,12 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           disabled={disabled}
           onChange={(event) => { setKeyDraft(event.target.value) }}
         />
-        {keyFailure === undefined ? null : <p className={styles['error']}>{t(keyFailure)}</p>}
+        {/* A create card has no stored key to keep, so the blank case says
+            what a blank field means here instead: this route may authenticate
+            through the provider's own ambient discovery or OAuth. */}
+        {keyFailure === undefined
+          ? null
+          : <p className={styles['error']}>{t(keyFailure === 'keyBlank' ? 'keyBlankNew' : keyFailure)}</p>}
       </div>
       <ModelListEditor
         models={models}
@@ -226,6 +231,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           api: protocol,
           ...keyValue.length === 0 ? {} : { apiKey: keyValue },
         }}
+        probeBlocked={keyFailure === 'keyBlank' ? 'keyBlankNew' : keyFailure}
         api={api}
         t={t}
         disabled={disabled}
diff --git a/packages/client/ui-models/src/client/ModelListEditor.tsx b/packages/client/ui-models/src/client/ModelListEditor.tsx
index e60c8c24ed..b2966568ae 100644
--- a/packages/client/ui-models/src/client/ModelListEditor.tsx
+++ b/packages/client/ui-models/src/client/ModelListEditor.tsx
@@ -74,6 +74,13 @@ export interface ModelListEditorProps {
   onReset?: () => void
   /** Endpoint facts for the fetch action. */
   probe: ProbeTarget
+  /**
+   * Copy key naming why the fetch action is unavailable, or `undefined` when
+   * it is. The card owns this because the key it would send is judged there:
+   * asking with a key the form has already refused spends a round trip to be
+   * told what the field already says.
+   */
+  probeBlocked?: keyof typeof en | undefined
   /** Wire face the fetch action calls. */
   api: Pick<IApiClient, 'llm'>
   /** Section copy. */
@@ -314,8 +321,10 @@ export function ModelListEditor(props: ModelListEditorProps): ReactNode {
         <button
           type="button"
           className={styles['linkButton']}
-          disabled={disabled || busy || !askable}
-          title={askable ? undefined : t('fetchNeedsBaseUrl')}
+          disabled={disabled || busy || !askable || props.probeBlocked !== undefined}
+          title={props.probeBlocked !== undefined
+            ? t(props.probeBlocked)
+            : askable ? undefined : t('fetchNeedsBaseUrl')}
           onClick={() => { void fetchModels() }}
         >
           {busy ? t('fetching') : t('fetchModels')}
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx
index f33791eab5..79ac122c83 100644
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -371,7 +371,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                   defaultMaxTokens={typeof defaultMaxTokens === 'number' ? defaultMaxTokens : undefined}
                 />
               )
-              : <ModelListEditor {...catalogProps} probe={probe} api={api} />}
+              : <ModelListEditor {...catalogProps} probe={probe} probeBlocked={keyFailure} api={api} />}
           </div>
         </details>
       </>
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index 0d50c03e63..85f7c14f97 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -47,6 +47,7 @@ export const en = {
   removeModel: 'Delete model',
   modelsEmpty: 'No models will be shown in the selector. Unlisted IDs can still be sent directly.',
   keyBlank: 'Enter the API key, or leave the field empty to keep the stored one.',
+  keyBlankNew: 'Enter the API key, or leave the field empty if this provider authenticates another way.',
   keyIllegalCharacters: 'This API key is not in a valid format. Please check it.',
   keyLooksWrapped: 'Paste only the key itself — not a NAME=value line, and without surrounding quotes.',
   modelIdRequired: 'Model ID is required.',
@@ -134,6 +135,7 @@ export const zh: typeof en = {
   removeModel: '删除模型',
   modelsEmpty: '模型选择器中将不显示任何模型；目录外 ID 仍可直接发送。',
   keyBlank: '请输入 API 密钥；留空则保持已存储的密钥。',
+  keyBlankNew: '请输入 API 密钥；若该提供方以其他方式鉴权，可以留空。',
   keyIllegalCharacters: '该 API 密钥格式错误，请检查。',
   keyLooksWrapped: '请只粘贴密钥本身——不要带 NAME=value 整行，也不要带引号。',
   modelIdRequired: '模型 ID 不能为空。',
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index a167710153..13c1511bb2 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -954,6 +954,19 @@ describe('API key field', () => {
     expect((set.mock.calls[0]?.[0] as { value: string }).value).toBe('sk-abc')
   })
 
+  it('blocks the interrogation too, rather than spending a round trip on a refused key', async () => {
+    const { discover } = await mountSection()
+    openEditor('openai')
+
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'sk-\u{1F600}' } })
+
+    // The host would refuse this before building the header anyway; asking is
+    // a round trip to be told what the field already says.
+    expect(buttonNamed(en.fetchModels).disabled).toBe(true)
+    expect(buttonNamed(en.fetchModels).title).toBe(en.keyIllegalCharacters)
+    expect(discover).not.toHaveBeenCalled()
+  })
+
   it('carries the trimmed key into an interrogation, not the padded draft', async () => {
     const { discover } = await mountSection()
     openEditor('openai')
diff --git a/packages/llm/llm-pi-ai/tests/discovery.spec.ts b/packages/llm/llm-pi-ai/tests/discovery.spec.ts
index 63b43ecdab..85221e7ca2 100644
--- a/packages/llm/llm-pi-ai/tests/discovery.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/discovery.spec.ts
@@ -325,8 +325,10 @@ describe('probe key format', () => {
   })
 
   it('reports a blank probe key as a credential fault too', async () => {
-    // A cleared form field arrives as '', not an absent key; it must fail the
-    // same way a typed-in illegal key does, rather than probing unauthenticated.
+    // The Models page omits `apiKey` entirely for a cleared field rather than
+    // sending '', so this pins the contract for every other caller: a supplied
+    // key is judged, and only an absent one probes unauthenticated. '' means
+    // "I have a key" and is answered as the empty key it is.
     await expect(discoverModels({
       baseURL: 'https://acme.test',
       api: 'openai-completions',
diff --git a/packages/llm/llm/src/index.ts b/packages/llm/llm/src/index.ts
index 287bfc2f34..0d1f23af19 100644
--- a/packages/llm/llm/src/index.ts
+++ b/packages/llm/llm/src/index.ts
@@ -145,11 +145,16 @@ export class LlmError extends HarnessError {
 export function assertUsableApiKey(raw: string, pkg: string, ref: string): string {
   const checked = normalizeApiKey(raw)
   if (checked.ok) return checked.value
+  // The Models page is named as the writer it usually is, not as the only one:
+  // the same value can arrive from a hand-edited .env or a shell export in a
+  // composition that mounts no credentials seam at all, where directing the
+  // user to a page that deployment does not serve would be a dead end.
   throw new LlmError(
     checked.reason === 'empty'
-      ? `${pkg}: the API key stored as ${ref} is blank; re-enter it on the web Models page`
-      : `${pkg}: the API key stored as ${ref} contains characters no HTTP header can carry;`
-        + ' re-enter it on the web Models page, pasting the raw key only',
+      ? `${pkg}: the API key resolved from ${ref} is blank; set ${ref} to the raw key`
+        + ' (the web Models page writes it) or export it in the launching environment'
+      : `${pkg}: the API key resolved from ${ref} contains characters no HTTP header can carry;`
+        + ` set ${ref} to the raw key alone (the web Models page writes it)`,
     INVALID_CREDENTIAL_CODE,
   )
 }
diff --git a/packages/llm/llm/tests/api-key.spec.ts b/packages/llm/llm/tests/api-key.spec.ts
index a04a103fb9..783b054b9b 100644
--- a/packages/llm/llm/tests/api-key.spec.ts
+++ b/packages/llm/llm/tests/api-key.spec.ts
@@ -45,7 +45,7 @@ describe('assertUsableApiKey', () => {
 
   it('refuses a blank stored credential, naming the reference', () => {
     expect(() => assertUsableApiKey('   ', 'llm-deepseek', 'DEEPSEEK_API_KEY'))
-      .toThrow(/llm-deepseek: the API key stored as DEEPSEEK_API_KEY is blank/)
+      .toThrow(/llm-deepseek: the API key resolved from DEEPSEEK_API_KEY is blank/)
   })
 
   it('refuses an unusable stored credential with the invalid-credential code', () => {

From ec1111f18e4b7c3c87773a485133896078033c3b Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 11:04:02 +0800
Subject: [PATCH 087/516] docs: keep the API key Agent Note current with the
 review fixes

---
 .../bug-fix/2026-08-06-api-key-format-validation.i18n.yaml  | 4 ++--
 .../bug-fix/2026-08-06-api-key-format-validation.md         | 6 ++++--
 .../bug-fix/2026-08-06-api-key-format-validation.zh.md      | 6 ++++--
 3 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index 42b42a591a..2ffa228261 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.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 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
-2026-08-06-api-key-format-validation.md: 9ec247cb2ba2578158759ec1115c5d3a95778cc4
-2026-08-06-api-key-format-validation.zh.md: 63c6a8c17ee93b4b68eb3505d5499756e9fb2401
+2026-08-06-api-key-format-validation.md: a0a99bfcace5422ed021d684c5d5aae48c197af7
+2026-08-06-api-key-format-validation.zh.md: b6dc836cbc7bc828f343d9d376dab6e5c3d424ee
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
index 9ec247cb2b..a0a99bfcac 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
@@ -60,7 +60,7 @@ The client cannot import any of this: client packages reference only client pack
 | `llm-pi-ai` `resolveProfiles` | Applies the shared rule, keeping its "omit it to use ambient authentication" wording, and writes the trimmed value into the resolved profile. |
 | `llm-pi-ai` `resolveApiKey` | Normalizes the credential and environment paths. A profile naming no credential still returns `undefined`, so ambient and OAuth routes are unaffected. |
 | `llm-pi-ai` `discoverModels` | Normalizes before building the header, so an illegal key is a credential fault rather than an unreachable endpoint. A probe carrying no key stays unauthenticated. |
-| `ui-models` | Mirrors the charset rule, adds the shape heuristic, trims `keyDraft` before probe and `credentials.set`, and fixes the `stringAt` emptiness test. A blank field remains a no-op that submits; a field holding only whitespace is a field-level failure. Submit is gated and the failure renders on the field, matching the existing `modelFailure` pattern. |
+| `ui-models` | Mirrors the charset rule, adds the shape heuristic, trims `keyDraft` before probe and `credentials.set`, and fixes the `stringAt` emptiness test. A blank field remains a no-op that submits; a field holding only whitespace is a field-level failure. Submit **and the endpoint interrogation** are both gated, so a refused key never spends a round trip to be told what the field already says, and the failure renders on the field, matching the existing `modelFailure` pattern. |
 
 `ProviderEditor` serves both the DeepSeek and pi-ai layouts, so one client change covers both providers. `CustomProviderCard` carries the same judgement for a hand-declared route.
 
@@ -102,4 +102,6 @@ The costliest way to get this wrong would have been to treat absence as invalidi
 
 `packages/llm/llm-deepseek/tests/` covers the literal-config path in `adapter.spec.ts` and the stored-credential path end to end in `dynamic-config.spec.ts`, through the real credentials seam rather than a stub. `packages/llm/llm-pi-ai/tests/` covers `resolveProfiles` — including that the trimmed value reaches the resolved profile, which the `...rest` spread would otherwise discard — and the discovery probe, including that a probe with no key sends no `authorization` header.
 
-`packages/client/ui-models/tests/` pins `apiKeyFailure` over the same table plus the paste-shape cases, and drives both cards: a blank field submits without writing a credential, a whitespace-only field fails on the field, an illegal or wrapped key blocks submit, a padded key is trimmed before `credentials.set` and before an interrogation, and a hand-declared route can be created with no key at all.
+`packages/client/ui-models/tests/` pins `apiKeyFailure` over the same table plus the paste-shape cases, and drives both cards: a blank field submits without writing a credential, a whitespace-only field fails on the field, an illegal or wrapped key blocks submit and the interrogation alike, a padded key is trimmed before `credentials.set` and before an interrogation, and a hand-declared route can be created with no key at all.
+
+The user-visible terminal state is pinned where it is actually assembled: `examples/headless-agent/tests/headless.snapshot.ts` runs the one-shot app against a stored key no header can carry, over the same keyless composition its missing-credential sibling uses, and records that the turn ends on `INVALID_CREDENTIAL` with an actionable message carrying neither the key nor the word `ByteString`. A package test could not have shown that, and the web e2e covers only the browser half.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index 63c6a8c17e..b6dc836cbc 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -60,7 +60,7 @@ Status: implemented
 | `llm-pi-ai` `resolveProfiles` | 施加这条共享规则，保留其「omit it to use ambient authentication」的措辞，并把 trim 后的值写进解析后的 profile。 |
 | `llm-pi-ai` `resolveApiKey` | 归一化凭据与环境路径。不指定任何凭据的 profile 仍返回 `undefined`，ambient 与 OAuth 路由不受影响。 |
 | `llm-pi-ai` `discoverModels` | 在构造 header 之前归一化，使非法 Key 成为凭据故障而非端点不可达。不带 Key 的探测保持未鉴权。 |
-| `ui-models` | 镜像字符集规则，加入形状启发式，在探测与 `credentials.set` 之前 trim `keyDraft`，并修正 `stringAt` 的空值判断。留空的输入框仍是可以提交的空操作；只含空白的输入框则是字段级失败。提交受拦截，失败呈现在字段上，与既有的 `modelFailure` 模式一致。 |
+| `ui-models` | 镜像字符集规则，加入形状启发式，在探测与 `credentials.set` 之前 trim `keyDraft`，并修正 `stringAt` 的空值判断。留空的输入框仍是可以提交的空操作；只含空白的输入框则是字段级失败。提交**与端点探测**同时受拦截，因此被拒绝的密钥不会白花一次往返去换取字段上已经写明的答案；失败呈现在字段上，与既有的 `modelFailure` 模式一致。 |
 
 `ProviderEditor` 同时服务 DeepSeek 与 pi-ai 两种布局，因此一处客户端改动覆盖两个 provider。`CustomProviderCard` 为手工声明的路由承载同一套判定。
 
@@ -102,4 +102,6 @@ Status: implemented
 
 `packages/llm/llm-deepseek/tests/` 在 `adapter.spec.ts` 中覆盖字面量配置路径，在 `dynamic-config.spec.ts` 中经真实凭据 seam（而非 stub）端到端覆盖已存储凭据路径。`packages/llm/llm-pi-ai/tests/` 覆盖 `resolveProfiles`——包括 trim 后的值确实到达解析后的 profile，否则会被 `...rest` 展开丢弃——以及探测路径，包括不带 Key 的探测不会发出 `authorization` 标头。
 
-`packages/client/ui-models/tests/` 以同一张表加上形状用例钉住 `apiKeyFailure`，并驱动两张卡片：留空的输入框可提交且不写入凭据、只含空白的输入框在字段上失败、非法或被包裹的 Key 拦截提交、带首尾空白的 Key 在 `credentials.set` 与探测之前被 trim，以及手工声明的路由可以完全不带 Key 创建。
+`packages/client/ui-models/tests/` 以同一张表加上形状用例钉住 `apiKeyFailure`，并驱动两张卡片：留空的输入框可提交且不写入凭据、只含空白的输入框在字段上失败、非法或被包裹的 Key 同时拦截提交与探测、带首尾空白的 Key 在 `credentials.set` 与探测之前被 trim，以及手工声明的路由可以完全不带 Key 创建。
+
+用户可见的终态则钉在它真正被组装的位置：`examples/headless-agent/tests/headless.snapshot.ts` 让 one-shot 应用在一个 HTTP 标头无法承载的已存密钥下运行，复用其 missing-credential 兄弟场景的同一套无密钥 composition，并记录该轮以 `INVALID_CREDENTIAL` 结束、消息可操作且既不含密钥也不含 `ByteString` 字样。包级测试无法证明这一点，而 web e2e 只覆盖了浏览器那一半。

From a7d374426803c73d281f8f3fb84882e3458cdde0 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 11:16:20 +0800
Subject: [PATCH 088/516] test(web): cover the create card's blank-key copy
 substitution

---
 .../ui-models/tests/provider-form.spec.tsx     | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 13c1511bb2..85125919b5 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -880,6 +880,24 @@ describe('hand-declared providers', () => {
     expect(set).not.toHaveBeenCalled()
   })
 
+  it('tells a whitespace-only key what a blank field means on a create card', () => {
+    const { mutate } = mountCard()
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme-gateway' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://gateway.acme.example/v1' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'acme-large' } })
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: '   ' } })
+
+    // There is no stored key to keep here, so the blank case says the thing
+    // that is true of a route being declared: it may authenticate elsewhere.
+    expect(screen.getByText(en.keyBlankNew)).toBeTruthy()
+    expect(screen.queryByText(en.keyBlank)).toBeNull()
+    expect(buttonNamed(en.fetchModels).title).toBe(en.keyBlankNew)
+    expect(buttonNamed(en.create).disabled).toBe(true)
+    expect(mutate).not.toHaveBeenCalled()
+  })
+
   it('creates without a key when the route authenticates some other way', async () => {
     const { set, onClose } = mountCard()
 

From 5a422337f8fa3c1664b392360593c9fece75abe2 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 11:35:23 +0800
Subject: [PATCH 089/516] fix(web): silence the stale gate hint, clear
 whitespace fields, narrow the paste heuristic

---
 ...-08-06-api-key-format-validation.i18n.yaml |  4 +--
 .../2026-08-06-api-key-format-validation.md   |  2 +-
 ...2026-08-06-api-key-format-validation.zh.md |  2 +-
 .../src/client/CustomProviderCard.tsx         |  4 +++
 .../ui-models/src/client/ProviderEditor.tsx   |  7 ++++-
 .../client/ui-models/src/client/apiKey.ts     | 14 +++++----
 .../ui-models/tests/components.spec.tsx       |  2 ++
 .../ui-models/tests/provider-form.spec.tsx    | 31 +++++++++++++++++++
 8 files changed, 55 insertions(+), 11 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index 2ffa228261..ae2d1d5934 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.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 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
-2026-08-06-api-key-format-validation.md: a0a99bfcace5422ed021d684c5d5aae48c197af7
-2026-08-06-api-key-format-validation.zh.md: b6dc836cbc7bc828f343d9d376dab6e5c3d424ee
+2026-08-06-api-key-format-validation.md: 4666f6197dbed060d00c77fdd6b87842141c10f4
+2026-08-06-api-key-format-validation.zh.md: 75c98bd29cf009e69ceb450432f540e3f49d99d0
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
index a0a99bfcac..4666f6197d 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
@@ -86,7 +86,7 @@ The client cannot import any of this: client packages reference only client pack
 
 A malformed key is refused at the field that holds it, and a malformed stored key fails as `INVALID_CREDENTIAL` with a message naming where to fix it and no fragment of the key. Because that code sits outside `DEFAULT_RETRYABLE_CODES`, a deterministic credential fault is no longer retried three times as a transport blip. `llm-pi-ai` discovery reports an illegal probe key as a credential fault instead of an unreachable endpoint.
 
-The shape heuristic can refuse a real key. Upper-case-identifier-then-`=` and matched surrounding quotes are shapes no known provider issues, and the rule runs only in the browser, so a user who hits it can still set the credential through the environment. The residual cost is a confusing refusal for a key nobody has yet reported.
+The shape heuristic can refuse a real key. The first draft matched any upper-case identifier followed by `=`, which review showed was broader than intended: an all-upper-case base64 key ending in padding (`ABCD==`) matched an assignment it does not resemble. Requiring a non-`=` character after the separator excludes padding, since base64 only ever pads at the end. What remains — an upper-case name, one `=`, then a value — is a shape no known provider issues, and the rule runs only in the browser, so a user who still hits it can set the credential through the environment. The residual cost is a confusing refusal for a key nobody has yet reported.
 
 Restricting to printable ASCII is stricter than the transport requires: a header value may carry `\x80`–`\xFF`. Admitting latin-1 would let `é` through to return an opaque 401 instead of a local, explained refusal, so the stricter rule is deliberate. A provider that issues latin-1 keys would need this rule widened.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index b6dc836cbc..75c98bd29c 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -86,7 +86,7 @@ Status: implemented
 
 格式错误的 Key 在持有它的那个字段上就被拒绝；格式错误的已存储 Key 以 `INVALID_CREDENTIAL` 失败，消息指明修复位置且不含 Key 的任何片段。由于该 code 位于 `DEFAULT_RETRYABLE_CODES` 之外，一个确定性的凭据故障不再被当作瞬时传输抖动重试三次。`llm-pi-ai` 的探测把非法 Key 报为凭据故障，而非端点不可达。
 
-形状启发式可能拒绝一个真实的 Key。全大写标识符接 `=`、以及首尾成对引号，都是已知 provider 不会签发的形态，且该规则只在浏览器中运行，因此撞上它的用户仍可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
+形状启发式可能拒绝一个真实的 Key。最初的写法匹配任意「全大写标识符接 `=`」，评审指出其覆盖面比预期更宽：一个以 padding 结尾的全大写 base64 Key（`ABCD==`）会命中它并不像的赋值形态。要求分隔符之后必须是非 `=` 字符即可排除 padding——base64 的 padding 只出现在末尾。剩下的形态（大写名称、一个 `=`、然后是值）是已知 provider 不会签发的，且该规则只在浏览器中运行，因此仍撞上它的用户可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
 
 限定为可打印 ASCII 比传输本身的要求更严：header value 是可以承载 `\x80`–`\xFF` 的。放行 latin-1 会让 `é` 通过并换回一个语焉不详的 401，而不是一次本地的、有解释的拒绝，因此从严是刻意的。若某个 provider 签发 latin-1 的 Key，这条规则需要放宽。
 
diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index a610f2f140..032a056144 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -93,6 +93,10 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
   // because its own field already explains itself, and a satisfied card says
   // nothing at all rather than printing an empty paragraph.
   const hint = failure !== undefined || ready
+    // The key field prints its own failure directly beneath itself, so a card
+    // blocked only by the key stays silent here rather than answering with the
+    // next unmet gate — which is satisfied, and reads as a second, false fault.
+    || keyFailure !== undefined
     ? undefined
     : baseURL.length === 0
       ? t('customNeedsBaseUrl')
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx
index 79ac122c83..d72c71cc76 100644
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -167,7 +167,12 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
     return typeof value === 'string' && value.trim().length > 0 ? value : undefined
   }
   const setField = (key: string, next: string | undefined): void => {
-    setDraft(current => next === undefined ? deletePath(current, [key]) : setPath(current, [key], next))
+    // A value of nothing but whitespace is cleared, not stored: `stringAt`
+    // already reports it as absent, so the field would otherwise render empty
+    // while the draft still carried the spaces into `settings.yaml`, where
+    // both adapters would accept that non-empty string as a real value.
+    const value = next === undefined || next.trim().length === 0 ? undefined : next
+    setDraft(current => value === undefined ? deletePath(current, [key]) : setPath(current, [key], value))
   }
 
   // The model list is validated by the same per-row checker for both families,
diff --git a/packages/client/ui-models/src/client/apiKey.ts b/packages/client/ui-models/src/client/apiKey.ts
index a9d5bb3d32..5fd1d22ee6 100644
--- a/packages/client/ui-models/src/client/apiKey.ts
+++ b/packages/client/ui-models/src/client/apiKey.ts
@@ -12,13 +12,15 @@
 const LEGAL_API_KEY = /^[\x21-\x7E]+$/
 
 /**
- * A pasted `NAME=value` environment line. Restricted to an upper-case
- * identifier so a real key cannot match: `sk-` forms break at the hyphen.
- * This heuristic runs only here — a resolver applying it could lock a user
- * out of a gateway whose key legitimately takes this shape, with the
- * environment refusing it too and no way through.
+ * A pasted `NAME=value` environment line. Two narrowings keep real keys clear
+ * of it: the name must be upper-case, so `sk-` forms break at the hyphen, and
+ * the `=` must be followed by something other than another `=`, so base64
+ * padding on an all-upper-case key (`ABCD==`) is not mistaken for an
+ * assignment. This heuristic runs only here — a resolver applying it could
+ * lock a user out of a gateway whose key legitimately takes this shape, with
+ * the environment refusing it too and no way through.
  */
-const ENV_LINE = /^[A-Z][A-Z0-9_]*=/
+const ENV_LINE = /^[A-Z][A-Z0-9_]*=[^=]/
 
 /** Copy key naming why a typed key cannot be saved. */
 export type ApiKeyFailureKey = 'keyBlank' | 'keyIllegalCharacters' | 'keyLooksWrapped'
diff --git a/packages/client/ui-models/tests/components.spec.tsx b/packages/client/ui-models/tests/components.spec.tsx
index d9034ecd44..7228d472cd 100644
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -1092,6 +1092,8 @@ describe('apiKeyFailure', () => {
     ['a padded key, which the caller trims', '  sk-abc  '],
     ['the printable-ASCII boundary characters', '!~'],
     ['a hyphenated key carrying an equals sign', 'sk-ABC=xyz'],
+    ['an all-upper-case key ending in base64 padding', 'ABCD=='],
+    ['an all-upper-case key ending in one padding character', 'MNOPQRST='],
   ])('accepts %s', (_label, draft) => {
     expect(apiKeyFailure(draft)).toBeUndefined()
   })
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 85125919b5..5d505386e6 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -880,6 +880,22 @@ describe('hand-declared providers', () => {
     expect(set).not.toHaveBeenCalled()
   })
 
+  it('stays silent about the other gates when only the key is refused', () => {
+    mountCard()
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme-gateway' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://gateway.acme.example/v1' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'acme-large' } })
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'sk-\u{1F600}' } })
+
+    // Route, endpoint, and models are all satisfied, so answering with the
+    // next unmet gate would print a second, false fault beside the real one.
+    expect(screen.getByText(en.keyIllegalCharacters)).toBeTruthy()
+    expect(screen.queryByText(en.customNeedsModels)).toBeNull()
+    expect(screen.queryByText(en.customNeedsBaseUrl)).toBeNull()
+  })
+
   it('tells a whitespace-only key what a blank field means on a create card', () => {
     const { mutate } = mountCard()
 
@@ -927,6 +943,21 @@ describe('API key field', () => {
     expect(set).not.toHaveBeenCalled()
   })
 
+  it('clears a whitespace-only base URL instead of writing the spaces', async () => {
+    const { mutate } = await mountSection()
+    openEditor('openai')
+
+    // The field renders this as empty, so the draft must agree: storing the
+    // spaces would hand both adapters a non-empty string they accept as a URL.
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: '   ' } })
+    fireEvent.click(screen.getByText(en.apply))
+
+    await waitFor(() => { expect(mutate).toHaveBeenCalled() })
+    const ops = firstMutate(mutate).ops
+    expect(ops.some(op => op.op === 'set' && op.path.includes('baseURL'))).toBe(false)
+    expect(ops.some(op => op.op === 'unset' && op.path.includes('baseURL'))).toBe(true)
+  })
+
   it('blocks submit and names the field when the key holds only whitespace', async () => {
     const { mutate, set } = await mountSection()
     openEditor('openai')

From 716361844c8616a24f38373d9d8d4e80e44752c1 Mon Sep 17 00:00:00 2001
From: Jiaying Ding <silver.ding@deepseek.com>
Date: Fri, 7 Aug 2026 11:54:45 +0800
Subject: [PATCH 090/516] style(web): use single quotes in hero expectations

---
 apps/web/tests/details-session-lifecycle.e2e.ts | 2 +-
 apps/web/tests/hmr-live.e2e.ts                  | 2 +-
 apps/web/tests/lifecycle-chrome.e2e.ts          | 2 +-
 apps/web/tests/startup-auto-selection.e2e.ts    | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/web/tests/details-session-lifecycle.e2e.ts b/apps/web/tests/details-session-lifecycle.e2e.ts
index 5317c39009..3bd781a5ee 100644
--- a/apps/web/tests/details-session-lifecycle.e2e.ts
+++ b/apps/web/tests/details-session-lifecycle.e2e.ts
@@ -121,7 +121,7 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S
     expect(await page.getByText('Details', { exact: true }).isVisible()).toBe(false)
 
     await page.getByRole('button', { name: /^(?:New session|新.*会话)$/ }).last().click()
-    await page.getByText("Into the unknown", { exact: false }).waitFor({ timeout: 15_000 })
+    await page.getByText('Into the unknown', { exact: false }).waitFor({ timeout: 15_000 })
     await expect.poll(() => detailsTrack(page), { timeout: 5_000 }).toBe(0)
     expect(await page.getByText('Details', { exact: true }).isVisible()).toBe(false)
 
diff --git a/apps/web/tests/hmr-live.e2e.ts b/apps/web/tests/hmr-live.e2e.ts
index 385a516e7d..1e8e81909f 100644
--- a/apps/web/tests/hmr-live.e2e.ts
+++ b/apps/web/tests/hmr-live.e2e.ts
@@ -75,7 +75,7 @@ it('hot-reloads a real client-plugin source edit without refreshing the page', a
   if (!existsSync(binPath)) throw new Error('HMR browser test needs the built dsh bin; run pnpm run build first')
   const originalSource = await readFile(sourcePath)
   const originalBundle = await readFile(bundlePath)
-  const oldText = "Into the unknown"
+  const oldText = 'Into the unknown'
   const sourceNeedle = "'hero.headline': 'Into the unknown'"
   const newText = `HMR UPDATED ${'x'.repeat(80)}`
   const updatedSource = originalSource.toString().replace(sourceNeedle, `'hero.headline': '${newText}'`)
diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index e9afa95872..90587e9e4c 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -159,7 +159,7 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
     }
     // The blank frame renders the hero, not the resident composer: the
     // headline plus the guidance placeholder are the empty state's anchors.
-    await expect.poll(() => page.getByText("Into the unknown", { exact: false }).count(), { timeout: 15_000 }).toBe(1)
+    await expect.poll(() => page.getByText('Into the unknown', { exact: false }).count(), { timeout: 15_000 }).toBe(1)
     const input = page.locator('textarea').first()
     await input.waitFor({ timeout: 10_000 })
     if (MODE !== 'record') {
diff --git a/apps/web/tests/startup-auto-selection.e2e.ts b/apps/web/tests/startup-auto-selection.e2e.ts
index 7ef43d2861..c93ed04a40 100644
--- a/apps/web/tests/startup-auto-selection.e2e.ts
+++ b/apps/web/tests/startup-auto-selection.e2e.ts
@@ -145,7 +145,7 @@ describe('web e2e: startup auto-selection', () => {
     // seat with `visibility:hidden`, which Playwright reports as not visible).
     await page.waitForSelector(ROOT_PHASE, { timeout: 15_000 })
     expect(await page.locator(ROOT_PHASE).first().getAttribute('data-phase')).toBe('hero')
-    expect(await page.getByText("Into the unknown").isVisible()).toBe(true)
+    expect(await page.getByText('Into the unknown').isVisible()).toBe(true)
     expect(await page.locator('textarea').first().isVisible()).toBe(true)
 
     releaseHistory()

From 09d1b0d27ff43687970d7b70049dae7843ce8ae4 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 12:50:23 +0800
Subject: [PATCH 091/516] test(web): align skill snapshot with turn actions

---
 apps/web/tests/snapshots/skill-tool-row/ui.expected.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/apps/web/tests/snapshots/skill-tool-row/ui.expected.md b/apps/web/tests/snapshots/skill-tool-row/ui.expected.md
index 7a51aae904..fc1f23d484 100644
--- a/apps/web/tests/snapshots/skill-tool-row/ui.expected.md
+++ b/apps/web/tests/snapshots/skill-tool-row/ui.expected.md
@@ -7,9 +7,6 @@
 - text: Load the snapshot-skill skill with the skill tool, then reply DONE. {{date}} {{clock}}
 - button "Copy":
   - img
-- button "Branch into a new conversation" [disabled]:
-  - img
-- text: Available only on the last message of a completed turn
 - button "Context injection @deepseek-ai/dsh-system-prompt":
   - img
   - img

From f2d1a29636cd0f818468342ad7e16827f7c9bb0f Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 13:23:19 +0800
Subject: [PATCH 092/516] feat(apiproxy): make the default model a user setting
 the picker writes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The route a new session starts from was frozen into the gateway's
composition entry, so switching models in a conversation reached only that
conversation and every later session went back to the shipped default.

The gateway now owns an `api-gateway` settings section: the entry is the
base layer and the user document layers over it, so `session.selectModel`
records an accepted switch as the default for the next session. The write
is wholesale rather than a merge — switching to a model with no reasoning
effort has to clear a stored one — and a storage failure is reported
without undoing the switch, which already applies to its own session.

`targetFor` now resolves its tiers on every read instead of seeding once:
an explicit selection, else the session's own logged request header, else
the live default. That is what keeps a session that has run a turn deriving
its route from its log forever after, while a session still blank — New
Session reuses one rather than minting another — starts from a default
saved after it was created.
---
 packages/host/apiproxy/src/api-proxy.ts       |  80 ++++++++++----
 packages/host/apiproxy/src/index.ts           |  89 +++++++++++++--
 .../apiproxy/tests/api-proxy-approval.spec.ts |   4 +-
 .../apiproxy/tests/api-proxy-blank.spec.ts    |   2 +-
 .../apiproxy/tests/api-proxy-cold.spec.ts     |  22 ++--
 .../apiproxy/tests/api-proxy-commands.spec.ts |   2 +-
 .../apiproxy/tests/api-proxy-config.spec.ts   |   2 +-
 .../apiproxy/tests/api-proxy-fork.spec.ts     |   3 +-
 .../apiproxy/tests/api-proxy-models.spec.ts   | 101 +++++++++++++++++-
 .../tests/api-proxy-projections.spec.ts       |   2 +-
 .../apiproxy/tests/api-proxy-question.spec.ts |   2 +-
 .../apiproxy/tests/api-proxy-rename.spec.ts   |   2 +-
 .../apiproxy/tests/api-proxy-search.spec.ts   |   2 +-
 .../tests/api-proxy-subagents.spec.ts         |   2 +-
 .../apiproxy/tests/api-proxy-view.spec.ts     |  10 +-
 .../tests/api-proxy-workspace.spec.ts         |   3 +-
 .../host/apiproxy/tests/rpc-schemas.spec.ts   |   2 +-
 .../todo/tool-todo/tests/projection.spec.ts   |   2 +-
 18 files changed, 274 insertions(+), 58 deletions(-)

diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 19fb0fe8a2..709c63e4d0 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -8,7 +8,7 @@ import { mkdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Context } from 'cordis'
 import { installAgentLlmTarget } from '@deepseek-ai/dsh-agent'
-import type { Agent, AgentLlmTarget, AgentLlmTargetRef, AgentStatus } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentLlmTarget, AgentLlmTargetRef, AgentOptions, AgentStatus } from '@deepseek-ai/dsh-agent'
 import { createUserMessage, freezeMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import { errorChain } from '@deepseek-ai/dsh-llm'
 import type { MessageSource } from '@deepseek-ai/dsh-llm'
@@ -329,8 +329,19 @@ function directoryError(error: unknown): RpcError {
 
 /** Resolved Host routing and project-directory defaults consumed by the API implementation. */
 export interface ApiProxyDefaults {
-  provider: string
-  model: string
+  /**
+   * The route a session starts from when its own log names none. Read on
+   * every access rather than captured, so a default saved during this process
+   * reaches the sessions that have not run a turn yet.
+   */
+  defaultTarget: () => AgentLlmTarget
+  /**
+   * Record a selection as the new default. Absent when the deployment stores
+   * no user settings, in which case a switch stays process-local. A rejection
+   * is reported and swallowed: the switch already applies to its own session,
+   * and undoing it because storage failed would be the worse outcome.
+   */
+  persistDefaultTarget?: (target: AgentLlmTarget) => Promise<void>
   /** Default project directory for new sessions whose create request carries no cwd. */
   cwd: string
   /** Parent directory for name-created workspaces. */
@@ -720,7 +731,11 @@ function changedWorkspaceView(workspaceId: string, value: unknown): WorkspaceVie
  * @returns the ApiProxy implementation.
  */
 export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
-  const agentOptions = { provider: defaults.provider, model: defaults.model }
+  /** The seed route each create/resume declares; re-read so it never goes stale. */
+  const agentOptions = (): AgentOptions => {
+    const { provider, model } = defaults.defaultTarget()
+    return { provider, model }
+  }
   type WebLlmTargetRef = AgentLlmTargetRef & { current: AgentLlmTarget }
   const targets = new WeakMap<Agent, WebLlmTargetRef>()
   /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
@@ -735,24 +750,39 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
 
   /**
    * Install or return the session-local target that prompt assembly snapshots.
-   * Seed order: latest logged request/header, else the host default routing.
-   * There is no create-time per-session override tier on this wire — if one
-   * returns (a create-options contribution), it must fold in between the two.
+   *
+   * Precedence, resolved on EVERY read rather than seeded once: a selection
+   * made in this process, else the session's own latest logged request/header,
+   * else the live host default. Re-reading is what keeps the two tiers honest
+   * in both directions — a session that has run a turn derives its route from
+   * its log forever after, so changing the default never retargets it; and a
+   * session still blank (New Session reuses one rather than minting another)
+   * starts from a default saved after it was created. There is no create-time
+   * per-session override tier on this wire — if one returns (a create-options
+   * contribution), it must fold in between the selection and the log.
    */
   function targetFor(agent: Agent): WebLlmTargetRef {
     const installed = targets.get(agent)
     if (installed !== undefined) return installed
-    const logged = agent.session.requestHeader()?.config
+    let picked: AgentLlmTarget | undefined
     const target: WebLlmTargetRef = {
-      current: logged === undefined
-        ? { provider: defaults.provider, model: defaults.model }
-        : {
+      get current(): AgentLlmTarget {
+        if (picked !== undefined) return picked
+        // Incrementally folded by the session, so a per-step read costs
+        // O(new events) rather than a rescan.
+        const logged = agent.session.requestHeader()?.config
+        if (logged === undefined) return defaults.defaultTarget()
+        return {
           provider: logged.provider,
           model: logged.model,
           ...logged.reasoningEffort === undefined
             ? {}
             : { reasoningEffort: logged.reasoningEffort },
-        },
+        }
+      },
+      set current(next: AgentLlmTarget) {
+        picked = next
+      },
       assembled: undefined,
     }
     installAgentLlmTarget(agent.ctx, target)
@@ -1023,7 +1053,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           }
           const handle = await ctx.agents.resume({
             resumeSessionId: sessionId,
-            agentOptions,
+            agentOptions: agentOptions(),
             setup: installTarget,
           })
           return handle.agent
@@ -1140,7 +1170,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           }
           return (await ctx.agents.resume({
             resumeSessionId: sessionId,
-            agentOptions,
+            agentOptions: agentOptions(),
             setup: installTarget,
           })).agent
         }
@@ -1152,7 +1182,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         }
         return (await ctx.agents.create({
           sessionId,
-          agentOptions,
+          agentOptions: agentOptions(),
           meta: { cwd },
           setup: installTarget,
         })).agent
@@ -1692,6 +1722,17 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
               : { reasoningEffort: resolved.reasoningEffort },
           }
           targetFor(found.agent).current = selected
+          // A switch is also how this deployment's default is chosen: the next
+          // session created without one of its own starts here. Sessions that
+          // have already logged a route are unaffected — they derive from
+          // their own log (see targetFor).
+          try {
+            await defaults.persistDefaultTarget?.(selected)
+          } catch (error: unknown) {
+            ctx.logger.warn(
+              `api-proxy: the model switch applies to this session but was not saved as the default: ${String(error)}`,
+            )
+          }
           return ok(request, { selected: { ...selected } })
         } catch (error: unknown) {
           return err(request, {
@@ -1794,7 +1835,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
               parentSession: source.id,
               seedLength: cut,
             },
-            agentOptions,
+            agentOptions: agentOptions(),
             setup: installTarget,
           })
         } catch (error: unknown) {
@@ -2179,13 +2220,16 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     host: {
       describe(request) {
         // TODO(step2): version should read apps/cli's package.json; placeholder for now.
+        const route = defaults.defaultTarget()
         return Promise.resolve(ok(request, {
           version: '0.0.1',
           // Same source as session.create's fallback: the UI's default project
           // must match where an unspecified-cwd session actually lands.
           cwd: defaults.cwd,
-          provider: defaults.provider,
-          model: defaults.model,
+          // Read live for the same reason: this is what the NEXT session will
+          // start from, so a saved default has to be what it reports.
+          provider: route.provider,
+          model: route.model,
           attachedSessions: ctx.agents.list().length,
         }))
       },
diff --git a/packages/host/apiproxy/src/index.ts b/packages/host/apiproxy/src/index.ts
index e279575ff4..34ce49fc77 100644
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -6,11 +6,20 @@
  * (api-proxy.ts: createApiProxy + the ApiProxyService gateway plugin providing
  * `ctx.apiProxy`). Transport-agnostic by design: this package registers no
  * routes — physical carriers wrap `ctx.apiProxy` themselves.
+ *
+ * The gateway also owns the `api-gateway` settings section: the route a
+ * session starts from when its own log names none. The composition entry is
+ * the shipped default and the section layers the user's choice over it, so
+ * switching models in a conversation is what sets the default for the next
+ * one. Sessions that have already logged a route are never retargeted by it.
  */
 
 import { resolve } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
+import type { AgentLlmTarget } from '@deepseek-ai/dsh-agent'
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import type { ApiProxy } from './api/index.ts'
 import { createApiProxy } from './api-proxy.ts'
 
@@ -29,16 +38,62 @@ declare module 'cordis' {
   }
 }
 
-/** Gateway plugin config: host-level agent routing and Workspace creation root. */
-export interface Config {
-  /** Default provider route for created/resumed agents. */
+/**
+ * The settings namespace carrying the user's default route. Named for the
+ * gateway rather than for the package, because this key is what a person reads
+ * and writes in `settings.yaml`; the row id in a composition happens to match
+ * but does not determine it.
+ */
+export const API_GATEWAY_SETTINGS_NAMESPACE = settingsNamespace('api-gateway')
+
+/**
+ * The user-settable slice of the gateway config: the route a session starts
+ * from when its own log names none. `workspaceRoot` is deliberately not part
+ * of it — that is a launcher fact, not a preference.
+ */
+export interface DefaultRouteSettings {
+  /** Default provider route for created agents. */
   provider: string
   /** Default model id. */
   model: string
+  /** Default reasoning effort; absence preserves the adapter/provider default. */
+  reasoningEffort?: string
+}
+
+/** Gateway plugin config: host-level agent routing and Workspace creation root. */
+export interface Config extends DefaultRouteSettings {
   /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
   workspaceRoot?: string
 }
 
+/**
+ * The default-route fields, as fresh schema instances. Both the plugin config
+ * and the settings section are built from this one call, so the section stays
+ * a subset of the config structurally rather than by a comment two people have
+ * to keep true.
+ */
+function defaultRouteFields(): { [K in keyof Required<DefaultRouteSettings>]: z<string> } {
+  return {
+    provider: z.string().required(),
+    model: z.string().required(),
+    reasoningEffort: z.string(),
+  }
+}
+
+/** Schema of the settings section. */
+const DefaultRouteSchema: z<DefaultRouteSettings> = z.object(defaultRouteFields())
+
+/** Project the stored/composed section onto the agent-facing target shape. */
+function routeTarget(settings: DefaultRouteSettings): AgentLlmTarget {
+  return {
+    provider: settings.provider,
+    model: settings.model,
+    ...settings.reasoningEffort === undefined
+      ? {}
+      : { reasoningEffort: ReasoningEffortId(settings.reasoningEffort) },
+  }
+}
+
 /**
  * The API gateway service: implements the ApiProxy contract over the composed
  * host context and provides it as `ctx.apiProxy`. The Host cwd is the default
@@ -51,8 +106,7 @@ export class ApiProxyService extends Service implements ApiProxy {
   ]
 
   static Config: z<Config> = z.object({
-    provider: z.string().required(),
-    model: z.string().required(),
+    ...defaultRouteFields(),
     workspaceRoot: z.string(),
   })
 
@@ -72,9 +126,32 @@ export class ApiProxyService extends Service implements ApiProxy {
   constructor(ctx: Context, config: Config) {
     super(ctx, 'apiProxy')
     const cwd = process.cwd()
-    const api = createApiProxy(ctx, {
+    // The composition entry is the shipped default; the settings section
+    // layers the user's own choice over it, and a deployment without a
+    // settings provider simply keeps the entry.
+    const entry: DefaultRouteSettings = {
       provider: config.provider,
       model: config.model,
+      ...config.reasoningEffort === undefined ? {} : { reasoningEffort: config.reasoningEffort },
+    }
+    let route: () => DefaultRouteSettings = () => entry
+    installSettingsSection(ctx, API_GATEWAY_SETTINGS_NAMESPACE, DefaultRouteSchema, entry, {
+      setSource: (current) => {
+        route = current
+      },
+      // Nothing registration-level derives from the default: every consumer
+      // reads it through the thunk at the moment it needs a route.
+      onChange: () => {},
+    })
+    const api = createApiProxy(ctx, {
+      defaultTarget: () => routeTarget(route()),
+      // Wholesale, never a merge: switching to a model with no reasoning
+      // effort must clear a stored one, and a merged patch would strand it
+      // for the next session to fail on. The section holds no secrets, so
+      // there is nothing a replace can collaterally drop.
+      persistDefaultTarget: async (target) => {
+        await ctx.get('settings')?.replace(API_GATEWAY_SETTINGS_NAMESPACE, target)
+      },
       cwd,
       workspaceRoot: resolve(config.workspaceRoot ?? cwd),
     })
diff --git a/packages/host/apiproxy/tests/api-proxy-approval.spec.ts b/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
index 4833667583..e6555898cd 100644
--- a/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
@@ -27,7 +27,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
   await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(ApprovalService)
-  const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+  const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
   return { ctx, api }
 }
 
@@ -217,7 +217,7 @@ describe('approval pending registry', () => {
     await ctx.plugin(ApprovalService)
     let api!: ApiProxy
     const fiber = ctx.plugin(Object.assign((fiberCtx: Context) => {
-      api = createApiProxy(fiberCtx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+      api = createApiProxy(fiberCtx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     }, { inject: ['sessions', 'agents', 'userInteraction', 'approval'] }))
     await fiber.await()
     const abort = new AbortController()
diff --git a/packages/host/apiproxy/tests/api-proxy-blank.spec.ts b/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
index 4f8637068e..4943c051bb 100644
--- a/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
@@ -35,7 +35,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy; attach: (sessio
   await ctx.plugin(AgentRegistry)
   return {
     ctx,
-    api: createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }),
+    api: createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
     attach: (session) => {
       ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
     },
diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
index 78a67ef642..4b6337ede8 100644
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -62,7 +62,7 @@ describe('sessions.list cold merge', () => {
         return undefined
       },
     })
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const response = await api.sessions.list(request({}))
     expect(response.result.ok).toBe(true)
@@ -90,7 +90,7 @@ describe('attached updatedAt excludes end-seed', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(UserInteractionService)
     await ctx.plugin(AgentRegistry)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     // Old work, resumed just now: the log tail would report the pickup.
     const worked = 1_000_000
@@ -148,7 +148,7 @@ describe('cold history recovery view', () => {
       inspect: (id: SessionId, signal?: AbortSignal) => coordinator.inspect(id, signal),
       locate: () => undefined,
     } as never)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const history = await api.sessions.history(request({ sessionId, beforeSeq: 2, maxMessages: 10 }))
     if (!history.result.ok) throw new Error('history failed')
@@ -216,7 +216,7 @@ describe('subagent ownership fence', () => {
       locate: () => undefined,
     } as never)
     const resume = vi.spyOn(ctx.agents, 'resume')
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const history = await api.sessions.history(request({ sessionId }))
     expect(history.result.ok).toBe(true)
@@ -275,7 +275,7 @@ describe('subagent ownership fence', () => {
     // instead of answering `agent-busy`.
     const resume = vi.spyOn(ctx.agents, 'resume')
       .mockRejectedValue(new Error('registry unavailable in this bench'))
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const prompt = await api.sessions.prompt(request({
       sessionId,
@@ -316,7 +316,7 @@ describe('subagent ownership fence', () => {
     })
     const startingChild = { id: startingSession.id, session: startingSession, status: 'idle', ctx } as Agent
     ctx.agents.enter(startingChild, parent)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const stopped = await api.sessions.cancel(request({ sessionId: originChild.id }))
     expect(stopped.result.ok).toBe(false)
@@ -362,7 +362,7 @@ describe('subagent ownership fence', () => {
     const followup = vi.fn()
     const agent = { id: session.id, session, status: 'idle', ctx, followup } as unknown as Agent
     ctx.agents.register(agent)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const response = await api.sessions.prompt(request({
       sessionId: agent.id,
@@ -380,7 +380,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const listed = await api.sessions.list(request({}))
     expect(listed.result.ok).toBe(true)
@@ -405,7 +405,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
       list: () => Promise.resolve([]),
       inspect,
     } as never)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const response = await api.sessions.history(request({ sessionId: sid('session-missing') }))
     expect(response.result.ok).toBe(false)
@@ -431,7 +431,7 @@ describe('sessions.prompt synchronous rejection', () => {
       followup: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
       steer: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
     } as unknown as Agent)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     for (const mode of ['queue', 'steer'] as const) {
       const response = await api.sessions.prompt(request({
@@ -475,7 +475,7 @@ describe('sessions.prompt synchronous rejection', () => {
       ctx.agents.register(child)
       throw new Error('session id already published')
     })
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const models = await api.sessions.models(request({ sessionId }))
     expect(models.result.ok).toBe(false)
diff --git a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
index 1ab33897e3..55781a3e77 100644
--- a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
@@ -25,7 +25,7 @@ import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
 import { createApiProxy } from '../src/api-proxy.ts'
 
-const DEFAULTS = { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }
+const DEFAULTS = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
 
 function request<P>(payload: P): RpcRequest<P> {
   return { rpcId: RpcId(`req-${String(nextRpc++)}`), payload }
diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
index 54235c0218..c13a66eaec 100644
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -24,7 +24,7 @@ import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
 import { createApiProxy } from '../src/api-proxy.ts'
 
-const DEFAULTS = { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }
+const DEFAULTS = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
 
 let nextRpc = 1
 function request<P>(payload: P): RpcRequest<P> {
diff --git a/packages/host/apiproxy/tests/api-proxy-fork.spec.ts b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
index 83955f2d8b..fb6f8cdfed 100644
--- a/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
@@ -82,8 +82,7 @@ function liveAgent(
 }
 
 const api = (ctx: Context) => createApiProxy(ctx, {
-  provider: 'default-provider',
-  model: 'default-model',
+  defaultTarget: () => ({ provider: 'default-provider', model: 'default-model' }),
   cwd: '/tmp',
   workspaceRoot: '/tmp',
 })
diff --git a/packages/host/apiproxy/tests/api-proxy-models.spec.ts b/packages/host/apiproxy/tests/api-proxy-models.spec.ts
index c2dfdae7a7..7a9f2b2f86 100644
--- a/packages/host/apiproxy/tests/api-proxy-models.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-models.spec.ts
@@ -125,7 +125,7 @@ describe('Web session model selection', () => {
       model: 'private-preview',
       reasoningEffort: ReasoningEffortId('max'),
     })
-    const api = createApiProxy(ctx, { provider: 'deepseek-official', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const catalog = expectValue(await api.sessions.models(request({ sessionId })))
     expect(catalog.current).toEqual({
@@ -160,7 +160,7 @@ describe('Web session model selection', () => {
 
   it('accepts an advisory-unlisted model, rejects an unavailable provider, and switches only after the next assembly', async () => {
     const { ctx, agent, sessionId } = await harness()
-    const api = createApiProxy(ctx, { provider: 'deepseek-official', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
     const signal = new AbortController().signal
 
@@ -225,4 +225,101 @@ describe('Web session model selection', () => {
       .toEqual({ provider: 'deepseek-official', model: 'private-preview', reasoningEffort: 'max' })
     await ctx.fiber.dispose()
   })
+
+  it('reads the host default live for a session whose log names no route', async () => {
+    const { ctx, sessionId } = await harness()
+    let stored = { provider: 'deepseek-official', model: 'deepseek-chat' }
+    const api = createApiProxy(ctx, {
+      defaultTarget: () => stored,
+      cwd: '/tmp',
+      workspaceRoot: '/tmp',
+    })
+
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-chat' })
+    // The default moving after the session exists still reaches it: New
+    // Session reuses a blank session rather than minting another, so a seed
+    // captured at creation would show the superseded model there.
+    stored = { provider: 'deepseek-official', model: 'deepseek-reasoner' }
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
+    expect(expectValue(await api.host.describe(request({}))))
+      .toMatchObject({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps a session that logged a route on it when the host default moves', async () => {
+    const { ctx, sessionId } = await harness({
+      provider: 'deepseek-official',
+      model: 'deepseek-chat',
+    })
+    let stored = { provider: 'deepseek-official', model: 'deepseek-chat' }
+    const api = createApiProxy(ctx, {
+      defaultTarget: () => stored,
+      cwd: '/tmp',
+      workspaceRoot: '/tmp',
+    })
+
+    stored = { provider: 'duplicate', model: 'same' }
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-chat' })
+    await ctx.fiber.dispose()
+  })
+
+  it('saves an accepted selection as the default and survives a storage failure', async () => {
+    const { ctx, sessionId } = await harness()
+    const saved: unknown[] = []
+    let reject = false
+    const api = createApiProxy(ctx, {
+      defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }),
+      persistDefaultTarget: (target) => {
+        saved.push(target)
+        return reject ? Promise.reject(new Error('read-only document')) : Promise.resolve()
+      },
+      cwd: '/tmp',
+      workspaceRoot: '/tmp',
+    })
+
+    expectValue(await api.sessions.selectModel(request({
+      sessionId, provider: 'deepseek-official', model: 'deepseek-reasoner', reasoningEffort: 'max',
+    })))
+    expect(saved).toEqual([
+      { provider: 'deepseek-official', model: 'deepseek-reasoner', reasoningEffort: 'max' },
+    ])
+
+    // A refused selection never becomes anyone's default.
+    await api.sessions.selectModel(request({ sessionId, provider: 'missing', model: 'model' }))
+    expect(saved).toHaveLength(1)
+
+    // Storage failing is not the selection failing: the switch already applies
+    // to this session, so the call still succeeds.
+    reject = true
+    const stillAccepted = expectValue(await api.sessions.selectModel(request({
+      sessionId, provider: 'deepseek-official', model: 'deepseek-chat',
+    })))
+    expect(stillAccepted.selected).toEqual({ provider: 'deepseek-official', model: 'deepseek-chat', reasoningEffort: 'high' })
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-chat', reasoningEffort: 'high' })
+    await ctx.fiber.dispose()
+  })
+
+  it('serves a session and its catalog when the stored default names a route that is gone', async () => {
+    const { ctx, sessionId } = await harness()
+    const api = createApiProxy(ctx, {
+      // What a Models-page removal leaves behind: the settings document still
+      // names the route the user last picked, and nothing serves it.
+      defaultTarget: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
+      cwd: '/tmp',
+      workspaceRoot: '/tmp',
+    })
+
+    const catalog = expectValue(await api.sessions.models(request({ sessionId })))
+    // Passed through rather than repaired: matching no group is precisely what
+    // makes the composer seat prompt for a selection instead of naming a model
+    // the deployment cannot reach.
+    expect(catalog.current).toEqual({ provider: 'deleted-gateway', model: 'deleted-model' })
+    expect(catalog.groups.flatMap(group => group.models.map(model => `${group.id}/${model.id}`)))
+      .not.toContain('deleted-gateway/deleted-model')
+    await ctx.fiber.dispose()
+  })
 })
diff --git a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
index a1775a8025..c9cb212004 100644
--- a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
@@ -68,7 +68,7 @@ function seedMessages(session: Session, count: number): void {
   }
 }
 
-const api = (ctx: Context) => createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+const api = (ctx: Context) => createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
 describe('session.history projections block', () => {
   it('serves the unit value on the tail page with asOfSeq = last event seq', async () => {
diff --git a/packages/host/apiproxy/tests/api-proxy-question.spec.ts b/packages/host/apiproxy/tests/api-proxy-question.spec.ts
index e8eaae813f..ee5747039f 100644
--- a/packages/host/apiproxy/tests/api-proxy-question.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-question.spec.ts
@@ -13,7 +13,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
   await ctx.plugin(UserInteractionService)
   return {
     ctx,
-    api: createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }),
+    api: createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
   }
 }
 
diff --git a/packages/host/apiproxy/tests/api-proxy-rename.spec.ts b/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
index 15c7361024..2f93cdd9b3 100644
--- a/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
@@ -68,7 +68,7 @@ function liveAgent(ctx: Context, id: string, turns: number): Session {
   return session
 }
 
-const api = (ctx: Context) => createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+const api = (ctx: Context) => createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
 describe('sessions.rename', () => {
   it('accepts through the composed title service: normalized user-source event, echoed seq', async () => {
diff --git a/packages/host/apiproxy/tests/api-proxy-search.spec.ts b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
index 57bb05df4f..15a4ae3bf3 100644
--- a/packages/host/apiproxy/tests/api-proxy-search.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
@@ -27,7 +27,7 @@ vi.mock('node:fs/promises', async (importOriginal) => {
 })
 
 const sid = (value: string): SessionId => value as SessionId
-const defaults = { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }
+const defaults = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
 
 function request(query: string): RpcRequest<{ query: string }> {
   return { rpcId: RpcId(`search-${query}`), payload: { query } }
diff --git a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
index c761484da5..feb9ecb073 100644
--- a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
@@ -88,7 +88,7 @@ function bench(options: {
   ctx.provide('sessionProjections', { snapshot, restore, onChanged: () => () => {} })
   ctx.provide('userInteraction', { registerProvider: () => () => {} })
   const api = createApiProxy(ctx, {
-    provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp',
+    defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp',
   })
   return { api, getAgent, listChildren, inspect, snapshot, restore, followup, parent }
 }
diff --git a/packages/host/apiproxy/tests/api-proxy-view.spec.ts b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
index 43083545db..4490c71bc2 100644
--- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
@@ -105,7 +105,7 @@ async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: num
 describe('mux live view computation', () => {
   it('attaches the three standard card views, omits view without a presenter, soft-falls on throw', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux'), payload: {} }, abort.signal)
     const collected = collect(stream, 9, abort)
@@ -170,7 +170,7 @@ describe('mux live view computation', () => {
 
   it('serves history entries with call/result views, backscan pairing, and soft-falls', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const session = ctx.sessions.create()
     // history resolves the agent first; a live structural stub is enough (only
     // .session is read on this path).
@@ -238,7 +238,7 @@ describe('mux live view computation', () => {
 
   it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const session = ctx.sessions.create()
     ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
     session.append('turn/start', { turn: 1 })
@@ -287,7 +287,7 @@ describe('mux live view computation', () => {
 
   it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux3'), payload: {} }, abort.signal)
 
@@ -308,7 +308,7 @@ describe('mux live view computation', () => {
 
   it('pairs a result after turn/end via the in-memory backscan fallback', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux2'), payload: {} }, abort.signal)
     const collected = collect(stream, 4, abort)
diff --git a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
index af315ffcd0..aa560bdf58 100644
--- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
@@ -100,8 +100,7 @@ async function harness(
   // object per harness mirrors the seam's stability contract.
   ctx.provide('directoryPicker', { capability: () => picker } as never)
   const api = createApiProxy(ctx, {
-    provider: 'test',
-    model: 'test-model',
+    defaultTarget: () => ({ provider: 'test', model: 'test-model' }),
     cwd: workspaceRoot,
     workspaceRoot,
     ...extras.openPath === undefined ? {} : { openPath: extras.openPath },
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
index b65861c1ae..040fe56ff5 100644
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -274,7 +274,7 @@ describe('sessions domain schemas', () => {
 describe('host domain schemas', () => {
   it('validates describe request/value', () => {
     expect(hostDescribeRequestSchema.parse({})).toEqual({})
-    const value = hostDescribeValueSchema.parse({ version: '1', cwd: '/x', provider: 'p', model: 'm', attachedSessions: 2 })
+    const value = hostDescribeValueSchema.parse({ version: '1', cwd: '/x', defaultTarget: () => ({ provider: 'p', model: 'm' }), attachedSessions: 2 })
     expect(value.attachedSessions).toBe(2)
     expect(hostDescribeValueSchema.parse({ version: '1', cwd: '/x', attachedSessions: 0 }).provider).toBeUndefined()
   })
diff --git a/packages/todo/tool-todo/tests/projection.spec.ts b/packages/todo/tool-todo/tests/projection.spec.ts
index f1932b9955..08cb7d3216 100644
--- a/packages/todo/tool-todo/tests/projection.spec.ts
+++ b/packages/todo/tool-todo/tests/projection.spec.ts
@@ -45,7 +45,7 @@ async function harness(withTodoTool: boolean): Promise<Bench> {
   if (withTodoTool) await ctx.plugin(ToolTodo, { allowParallelInProgress: true })
   const session = ctx.sessions.create()
   ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
-  const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+  const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
   return {
     ctx,
     session,

From e0f9f7a6e66de81c2cc4fdff2a707212e73575f1 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 13:25:46 +0800
Subject: [PATCH 093/516] fix(ui-models): let a hand-declared route set its
 reasoning effort
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The create card omitted the provider-level effort the editor card offers
for the same namespace, so a route declared through 添加自定义提供方 gained
a setting the moment it was reopened for editing — one the creating user
was never shown.

Both cards now render one shared control. The field, its vocabulary, and
the inherit-means-absent rule live with the control rather than in the
editor, which is what stops the two from drifting apart again.
---
 .../src/client/CustomProviderCard.tsx         | 14 ++++
 .../ui-models/src/client/ProviderEditor.tsx   | 42 +++--------
 .../src/client/ReasoningEffortField.tsx       | 71 +++++++++++++++++++
 .../ui-models/tests/provider-form.spec.tsx    | 34 +++++++++
 4 files changed, 130 insertions(+), 31 deletions(-)
 create mode 100644 packages/client/ui-models/src/client/ReasoningEffortField.tsx

diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index b4c655472a..4bd14d1179 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -22,6 +22,7 @@ import { EditorFooter } from './EditorFooter.tsx'
 import { validateDeepSeekModels } from './DeepSeekModelsEditor.tsx'
 import { ModelListEditor } from './ModelListEditor.tsx'
 import type { ModelDraft } from './ModelListEditor.tsx'
+import { EFFORT_FIELD, ReasoningEffortField } from './ReasoningEffortField.tsx'
 import { deriveKeyRef, messageOf } from './store.ts'
 import type { en } from './locales.ts'
 import styles from './ModelsSection.module.css'
@@ -69,6 +70,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
   const [baseURL, setBaseURL] = useState('')
   const [protocol, setProtocol] = useState(protocols[0] ?? '')
   const [keyDraft, setKeyDraft] = useState('')
+  const [effort, setEffort] = useState<string | undefined>(undefined)
   const [models, setModels] = useState<readonly ModelDraft[]>([])
   const [busy, setBusy] = useState(false)
   const [failure, setFailure] = useState<string | undefined>(undefined)
@@ -101,6 +103,9 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
       apiKeyEnv: keyRef,
       api: protocol,
       baseURL,
+      // Inherit is the field being absent, not an empty string: the schema
+      // types it as an effort name, and an empty one would fail the write.
+      ...effort === undefined ? {} : { [EFFORT_FIELD['pi-ai']]: effort },
       models: models.map(model => ({ ...model })),
     }
     const response = await api.settings.mutate({
@@ -209,6 +214,15 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           onChange={(event) => { setKeyDraft(event.target.value) }}
         />
       </div>
+      {/* The same control the editor card shows for this namespace: a route
+          declared here and edited there must offer the same profile. */}
+      <ReasoningEffortField
+        family="pi-ai"
+        value={effort ?? ''}
+        onChange={setEffort}
+        t={t}
+        disabled={disabled}
+      />
       <ModelListEditor
         models={models}
         onChange={setModels}
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx
index f48572cc58..d25047ff65 100644
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -24,24 +24,14 @@ import {
 } from './DeepSeekModelsEditor.tsx'
 import { EditorFooter } from './EditorFooter.tsx'
 import { ModelListEditor } from './ModelListEditor.tsx'
+import { EFFORT_FIELD, ReasoningEffortField } from './ReasoningEffortField.tsx'
+import type { EffortFamily } from './ReasoningEffortField.tsx'
 import { deriveKeyRef, messageOf } from './store.ts'
 import type { en } from './locales.ts'
 import styles from './ModelsSection.module.css'
 
 /** Per-adapter-family curated field sets (unknown namespaces get the hint alone). */
-type EditorLayout = 'deepseek' | 'pi-ai' | 'unknown'
-
-/** Reasoning vocabularies per layout; the empty option means "inherit". */
-const EFFORT_CHOICES: Record<'deepseek' | 'pi-ai', readonly string[]> = {
-  deepseek: ['off', 'high', 'max'],
-  'pi-ai': ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'],
-}
-
-/** The draft key the effort select edits, per layout. */
-const EFFORT_FIELD: Record<'deepseek' | 'pi-ai', string> = {
-  deepseek: 'reasoningEffort',
-  'pi-ai': 'reasoning',
-}
+type EditorLayout = EffortFamily | 'unknown'
 
 /** The public DeepSeek endpoint shown as the deepseek base-URL placeholder. */
 const DEEPSEEK_PUBLIC_BASE_URL = 'https://api.deepseek.com'
@@ -279,7 +269,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
    * family as a parameter is what makes `EFFORT_FIELD` total here: an
    * unknown namespace never reaches this body.
    */
-  const curatedFields = (family: 'deepseek' | 'pi-ai'): ReactNode => {
+  const curatedFields = (family: EffortFamily): ReactNode => {
     const effortField = EFFORT_FIELD[family]
     const customModels = getPath(draft, ['models'])
     const modelsOverridden = hasPath(draft, ['models'])
@@ -333,23 +323,13 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                 }}
               />
             </div>
-            <div className={styles['field']}>
-              <span className={styles['fieldLabel']}>{t('effort')}</span>
-              <select
-                className={`${styles['input']} ${styles['selectInput']}`}
-                value={stringAt(draft, effortField) ?? ''}
-                aria-label={t('effort')}
-                disabled={disabled}
-                onChange={(event) => {
-                  setField(effortField, event.target.value === '' ? undefined : event.target.value)
-                }}
-              >
-                <option value="">{t('effortInherit')}</option>
-                {EFFORT_CHOICES[family].map(choice => (
-                  <option key={choice} value={choice}>{choice}</option>
-                ))}
-              </select>
-            </div>
+            <ReasoningEffortField
+              family={family}
+              value={stringAt(draft, effortField) ?? ''}
+              onChange={(effort) => { setField(effortField, effort) }}
+              t={t}
+              disabled={disabled}
+            />
             {/* Both families edit the same rows through the same contract; only
                 the extras differ — DeepSeek's inherited capacities, pi-ai's
                 endpoint interrogation. */}
diff --git a/packages/client/ui-models/src/client/ReasoningEffortField.tsx b/packages/client/ui-models/src/client/ReasoningEffortField.tsx
new file mode 100644
index 0000000000..10b696a4ea
--- /dev/null
+++ b/packages/client/ui-models/src/client/ReasoningEffortField.tsx
@@ -0,0 +1,71 @@
+/**
+ * The provider-level reasoning-effort select, shared by every card that writes
+ * a provider profile. It lives here rather than inside one card because both
+ * write the SAME field of the same profile: a route declared without this
+ * control and then edited with it would offer a setting the creating user was
+ * never given, which is exactly the drift that put it here.
+ *
+ * The value is the profile's own default effort, applied to every model on the
+ * route unless a request names one; the empty option means "inherit", which on
+ * the wire is the field being absent rather than an empty string.
+ */
+
+import type { ReactNode } from 'react'
+import type { en } from './locales.ts'
+import styles from './ModelsSection.module.css'
+
+/** The adapter families that expose a provider-level effort, and their vocabularies. */
+export type EffortFamily = 'deepseek' | 'pi-ai'
+
+/** Reasoning vocabularies per family; the empty option means "inherit". */
+export const EFFORT_CHOICES: Record<EffortFamily, readonly string[]> = {
+  deepseek: ['off', 'high', 'max'],
+  'pi-ai': ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'],
+}
+
+/** The profile key each family's effort lives under. */
+export const EFFORT_FIELD: Record<EffortFamily, string> = {
+  deepseek: 'reasoningEffort',
+  'pi-ai': 'reasoning',
+}
+
+/** Props of {@link ReasoningEffortField}. */
+export interface ReasoningEffortFieldProps {
+  /** Which vocabulary to offer. */
+  family: EffortFamily
+  /** Current value; the empty string is the inherit option. */
+  value: string
+  /** Receives the chosen effort, or undefined for inherit. */
+  onChange: (effort: string | undefined) => void
+  /** Section copy. */
+  t: (key: keyof typeof en) => string
+  /** Disable the control (busy or read-only). */
+  disabled: boolean
+}
+
+/**
+ * Render the provider-level reasoning-effort select.
+ * @param props - family vocabulary, current value, change sink, copy, and disabled state.
+ * @returns the labelled select.
+ */
+export function ReasoningEffortField(
+  { family, value, onChange, t, disabled }: ReasoningEffortFieldProps,
+): ReactNode {
+  return (
+    <div className={styles['field']}>
+      <span className={styles['fieldLabel']}>{t('effort')}</span>
+      <select
+        className={`${styles['input']} ${styles['selectInput']}`}
+        value={value}
+        aria-label={t('effort')}
+        disabled={disabled}
+        onChange={(event) => { onChange(event.target.value === '' ? undefined : event.target.value) }}
+      >
+        <option value="">{t('effortInherit')}</option>
+        {EFFORT_CHOICES[family].map(choice => (
+          <option key={choice} value={choice}>{choice}</option>
+        ))}
+      </select>
+    </div>
+  )
+}
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 99e85b0d10..b35302f78a 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -652,6 +652,40 @@ describe('hand-declared providers', () => {
     expect(set).toHaveBeenCalledWith({ ref: 'ACME_GATEWAY_API_KEY', value: 'gw-key' })
   })
 
+  it('offers the same reasoning effort the editor does, and omits it when inherited', async () => {
+    const { mutate, onClose } = mountCard()
+    const declare = (): void => {
+      fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+      fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+      fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+      fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'acme-large' } })
+    }
+    declare()
+
+    // The vocabulary is the namespace's, not DeepSeek's — a route declared
+    // here is edited by the pi-ai layout, which offers exactly these.
+    const select = screen.getByLabelText(en.effort) as HTMLSelectElement
+    expect([...select.options].map(option => option.value))
+      .toEqual(['', 'off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
+
+    fireEvent.change(select, { target: { value: 'high' } })
+    fireEvent.click(screen.getByText(en.create))
+    await waitFor(() => { expect(onClose).toHaveBeenCalledWith(true) })
+    expect(firstMutate(mutate).ops[0]).toMatchObject({
+      path: ['providers', 'acme'],
+      value: { reasoning: 'high' },
+    })
+
+    // Inherit is the field being absent: an empty string would fail the schema
+    // that types this as an effort name.
+    cleanup()
+    const second = mountCard()
+    declare()
+    fireEvent.click(screen.getByText(en.create))
+    await waitFor(() => { expect(second.onClose).toHaveBeenCalledWith(true) })
+    expect(firstMutate(second.mutate).ops[0].value).not.toHaveProperty('reasoning')
+  })
+
   it('names the blocked gate under the form, and nothing once it is satisfied', () => {
     mountCard()
     fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })

From 7a76365585aac59a8c3ad8f7554cb104162ddf02 Mon Sep 17 00:00:00 2001
From: Yif <877193178@qq.com>
Date: Fri, 7 Aug 2026 13:27:15 +0800
Subject: [PATCH 094/516] feat(web): restyle hero preview badge and grow
 wide-sidebar settings icon
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hero Preview tag becomes a superscript mono pill riding the title's
top-right (r24, bordered, business-tertiary fill), colored by the new
--dsw-alias-label-primary-bluish alias over --dsw-static-blue-900 — the
first design-owner-approved addition under the token-sheet authority
exception recorded in the ui-theme README. The expanded sidebar trigger
now uses the native 16px settings icon instead of the 14px asset.
---
 .../src/client/skeleton/HeroShell.module.css  | 22 +++++++++++--------
 .../ui-settings-general/src/client/chrome.tsx |  4 ++--
 packages/client/ui-theme/README.i18n.yaml     |  4 ++--
 packages/client/ui-theme/README.md            |  2 +-
 packages/client/ui-theme/README.zh.md         |  2 +-
 .../ui-theme/src/styles/design-platform.css   |  4 ++++
 6 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css b/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css
index 3166a81565..0e730a5b30 100644
--- a/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css
@@ -24,12 +24,12 @@
 }
 
 /* figma 34:10411: fish + title, gap 10, centered; 26/32 wt500. The preview
-   badge is a product addition outside that source and aligns to the title. */
+   badge is a product addition outside that source: a mono superscript pill
+   riding the title's top-right. */
 .headline {
   display: grid;
-  grid-template-columns: 34px auto;
+  grid-template-columns: 34px auto auto;
   column-gap: 10px;
-  row-gap: 4px;
   align-items: center;
   justify-content: center;
   font-size: 26px;
@@ -44,13 +44,17 @@
 }
 
 .previewBadge {
-  grid-row: 2;
-  grid-column: 2;
-  justify-self: start;
-  padding: 0 4px;
-  border-radius: 4px;
+  grid-row: 1;
+  grid-column: 3;
+  align-self: start;
+  margin-top: 2px;
+  margin-left: -3px;
+  padding: 1px 7px 0;
+  border: 1px solid var(--dsw-alias-interactive-bg-hover);
+  border-radius: 24px;
   background: var(--dsw-alias-state-business-tertiary);
-  color: var(--dsw-alias-label-primary);
+  color: var(--dsw-alias-label-primary-bluish);
+  font-family: var(--ds-font-family-code);
   font-size: 12px;
   line-height: 18px;
   font-weight: 500;
diff --git a/packages/client/ui-settings-general/src/client/chrome.tsx b/packages/client/ui-settings-general/src/client/chrome.tsx
index 28af15ab2f..9698d90868 100644
--- a/packages/client/ui-settings-general/src/client/chrome.tsx
+++ b/packages/client/ui-settings-general/src/client/chrome.tsx
@@ -4,7 +4,7 @@
  * The shell renders the surrounding chrome (button, nav heading row) and
  * reads each entry's `label` option for aria text.
  */
-import { IconSettingsOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconSettingsOutline14, IconSettingsOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import css from './chrome.module.css'
 
@@ -22,7 +22,7 @@ export type HeaderContentProps = PropsRuntime<'settings.header'> & PropsLocale<'
 export function TriggerContent({ wide, t }: TriggerContentProps) {
   return (
     <>
-      <IconSettingsOutline14 size={wide ? 14 : 18} />
+      {wide ? <IconSettingsOutline16 size={16} /> : <IconSettingsOutline14 size={18} />}
       {wide && <span className={css.triggerLabel}>{t('trigger')}</span>}
     </>
   )
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index 76bcbaf608..eb915bff8d 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/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/client/ui-theme/README.md
-README.md: 88e21fe214ec806b101050949690283d811be36d
-README.zh.md: ba781ba89a62292928a7b05ab94ea1cd930b4f50
+README.md: 648213b258169b2e8869a93d058fcc65aece175e
+README.zh.md: b807ebd66253c91dc8b79f01ac4d3b2335682001
diff --git a/packages/client/ui-theme/README.md b/packages/client/ui-theme/README.md
index 88e21fe214..648213b258 100644
--- a/packages/client/ui-theme/README.md
+++ b/packages/client/ui-theme/README.md
@@ -21,4 +21,4 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **Third-party themes are a surface, not a product** — registering one means overriding same-named alias variables; no validation exists that an override set is complete.
-- **The token sheets are the sole color authority** — values absent from cssdesign (for example the design's #4176E6 tab blue) are deliberately not appended; the nearest semantic token wins (arbitrated 2026-07-22).
+- **The token sheets are the sole color authority** — values absent from cssdesign (for example the design's #4176E6 tab blue) are deliberately not appended; the nearest semantic token wins (arbitrated 2026-07-22). Design-owner-approved additions are the exception and enter as a static step plus a semantic alias in the same change (`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`, 2026-08-07).
diff --git a/packages/client/ui-theme/README.zh.md b/packages/client/ui-theme/README.zh.md
index ba781ba89a..b807ebd662 100644
--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -21,4 +21,4 @@
 ## 已知限制与暂缓事项
 
 - **第三方主题是表层，不是产品**：注册主题意味着覆盖同名别名变量；目前不会验证一组覆盖是否完整。
-- **token 样式表是颜色值的唯一权威来源**：会有意不补入 cssdesign 中缺失的值（例如设计中的 #4176E6 标签页蓝色）；一律采用最接近的语义 token（裁定于 2026-07-22）。
+- **token 样式表是颜色值的唯一权威来源**：会有意不补入 cssdesign 中缺失的值（例如设计中的 #4176E6 标签页蓝色）；一律采用最接近的语义 token（裁定于 2026-07-22）。设计负责人批准的新增值是例外：须在同一变更中以一个 static 梯度值加一个语义 alias 的形式进入（`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`，2026-08-07）。
diff --git a/packages/client/ui-theme/src/styles/design-platform.css b/packages/client/ui-theme/src/styles/design-platform.css
index 3e8710822e..00d9d7106b 100644
--- a/packages/client/ui-theme/src/styles/design-platform.css
+++ b/packages/client/ui-theme/src/styles/design-platform.css
@@ -17,6 +17,7 @@ body {
   --dsw-static-blue-600: rgb(37, 99, 235);
   --dsw-static-blue-75: rgb(229, 240, 255);
   --dsw-static-blue-800: rgb(30, 64, 175);
+  --dsw-static-blue-900: rgb(14, 48, 116);
   --dsw-static-blue-950: rgb(23, 37, 84);
   --dsw-static-deepseek-100: rgb(228, 237, 253);
   --dsw-static-deepseek-200: rgb(211, 226, 255);
@@ -92,6 +93,7 @@ body[data-ds-dark-theme] {
   --dsw-static-blue-600: rgb(37, 99, 235);
   --dsw-static-blue-75: rgb(229, 240, 255);
   --dsw-static-blue-800: rgb(30, 64, 175);
+  --dsw-static-blue-900: rgb(14, 48, 116);
   --dsw-static-blue-950: rgb(23, 37, 84);
   --dsw-static-deepseek-100: rgb(228, 237, 253);
   --dsw-static-deepseek-200: rgb(211, 226, 255);
@@ -197,6 +199,7 @@ body {
   --dsw-alias-interactive-bg-hover: rgba(38, 49, 72, 0.06);
   --dsw-alias-label-caption: var(--dsw-static-neutral-bluish-400);
   --dsw-alias-label-dimmed: var(--dsw-static-neutral-bluish-200);
+  --dsw-alias-label-primary-bluish: var(--dsw-static-blue-900);
   --dsw-alias-label-primary-dimmed: var(--dsw-static-neutral-bluish-950);
   --dsw-alias-label-primary-foreground: var(--dsw-static-neutral-bluish-00);
   --dsw-alias-label-primary-inverted: var(--dsw-static-neutral-bluish-00);
@@ -287,6 +290,7 @@ body[data-ds-dark-theme] {
   --dsw-alias-interactive-bg-hover: rgba(255, 255, 255, 0.08);
   --dsw-alias-label-caption: var(--dsw-static-neutral-bluish-600);
   --dsw-alias-label-dimmed: var(--dsw-static-neutral-bluish-750);
+  --dsw-alias-label-primary-bluish: var(--dsw-static-neutral-bluish-50);
   --dsw-alias-label-primary-dimmed: var(--dsw-static-neutral-bluish-100);
   --dsw-alias-label-primary-foreground: var(--dsw-static-neutral-bluish-1000);
   --dsw-alias-label-primary-inverted: var(--dsw-static-neutral-bluish-800);

From 0cb922199d6c5341558640bb6f8a19bb1123b2e9 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 13:26:40 +0800
Subject: [PATCH 095/516] fix(apiproxy): open config files through Windows on
 WSL

---
 .../2026-07-30-web-config-plane.i18n.yaml     |  4 +-
 .../2026-07-30-web-config-plane.md            |  2 +-
 .../2026-07-30-web-config-plane.zh.md         |  2 +-
 ...-07-28-tool-call-file-open-in-os.i18n.yaml |  4 +-
 .../2026-07-28-tool-call-file-open-in-os.md   |  5 +-
 ...2026-07-28-tool-call-file-open-in-os.zh.md |  5 +-
 .../ui-settings-general/README.i18n.yaml      |  4 +-
 packages/client/ui-settings-general/README.md |  2 +-
 .../client/ui-settings-general/README.zh.md   |  2 +-
 packages/host/apiproxy/README.i18n.yaml       |  4 +-
 packages/host/apiproxy/README.md              |  2 +-
 packages/host/apiproxy/README.zh.md           |  2 +-
 .../host/apiproxy/src/native-path-opener.ts   | 45 ++++++++++--
 .../apiproxy/tests/native-path-opener.spec.ts | 71 ++++++++++++++++++-
 14 files changed, 128 insertions(+), 26 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
index 8ec7ff129e..b4b1fb5110 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.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 .agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
-2026-07-30-web-config-plane.md: 11554077d1848dcdf59b896dd9c29a39fd2f55d4
-2026-07-30-web-config-plane.zh.md: 527c2de8155a56789358b801f9c374e16c81931b
+2026-07-30-web-config-plane.md: 0b18cee414df23a2ed8a8b43b76dc06403804691
+2026-07-30-web-config-plane.zh.md: e70c2a47970f943e49393b099c4fcea58dc0fbdc
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
index 11554077d1..0b18cee414 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
@@ -16,7 +16,7 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer
 
 **`describe()` grows layers and structural secret redaction.** `SettingsDescriptor` carries `base`/`user` beside the effective value, so the form marks "overridden" by presence in the user layer, not value inequality (an override *equal* to the base is still an override). `describe({ redactSecrets: true })` — mandatory at every wire face — strips `role('secret')` subtrees from all three layers via a pure structural walk of the schema (object/dict/array containers; a secret-role subtree is one opaque leaf) and enumerates the stripped slots as `{path, set}`, so a page can render write-only inputs without ever receiving a value.
 
-**The Host identifies and opens the local settings document.** The settings seam exposes optional `documentPath` provider metadata and a `prepareDocument()` operation; `settings-local` returns its fully resolved custom or `$DSH_HOME/settings.yaml` filename and exclusively creates an absent empty document with owner-only permissions, while non-file providers retain the base `undefined`. The loopback-only `settings.describe` response carries only the boolean `hasDocument` capability beside the redacted namespace views. `ui-settings-general` registers a `settings.action` entry only on loopback pages, shows it only after the metadata confirms that a provider-owned local document can be prepared, and invokes pathless `settings.openDocument`; the Host resolves the provider path again before a text-document handoff (`open -t` on macOS so an arbitrary YAML file association cannot redirect the gesture, `xdg-open` on Linux, and `Invoke-Item` on Windows). Generic workspace paths retain the existing default-application handoff. The browser neither derives `$DSH_HOME` nor receives a filesystem target; remote pages make no privileged settings read for this action.
+**The Host identifies and opens the local settings document.** The settings seam exposes optional `documentPath` provider metadata and a `prepareDocument()` operation; `settings-local` returns its fully resolved custom or `$DSH_HOME/settings.yaml` filename and exclusively creates an absent empty document with owner-only permissions, while non-file providers retain the base `undefined`. The loopback-only `settings.describe` response carries only the boolean `hasDocument` capability beside the redacted namespace views. `ui-settings-general` registers a `settings.action` entry only on loopback pages, shows it only after the metadata confirms that a provider-owned local document can be prepared, and invokes pathless `settings.openDocument`; the Host resolves the provider path again before a text-document handoff (`open -t` on macOS so an arbitrary YAML file association cannot redirect the gesture, `xdg-open` on desktop Linux, `Invoke-Item` on Windows, and `wslpath -w` followed by that Windows handoff on WSL). Generic workspace paths retain the existing default-application handoff. The browser neither derives `$DSH_HOME` nor receives a filesystem target; remote pages make no privileged settings read for this action.
 
 **The llm seam declares configurability and announces topology.** `registerConfigurableProviders()` is an all-or-nothing, fiber-scoped directory of `{provider, displayName, settingsNs, settingsPath}` — the addressing a config page needs to open the right settings subtree for a route that may not exist yet; `listConfigurableProviders()` merges with live routes in the wire handler so undeclared live routes still report active. The zero-payload `'llm/adapters-updated'` event fires from all four registration/unregistration commit points with contained listener dispatch (INVARIANT rethrow), following the settings/commands precedent. `llm-deepseek`'s route renamed to `deepseek-official` because the pi-ai catalog legitimately owns `deepseek` as an aggregator entry; pre-release stance, no alias.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
index 527c2de815..e70c2a4797 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
@@ -16,7 +16,7 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 **`describe()` 增加分层与结构化 secret 脱敏。**`SettingsDescriptor` 在生效值之外携带 `base`/`user`，表单据此按「字段是否出现在用户层」来标记「已覆盖」，而非按值是否不等（与 base *相等*的覆盖仍然是覆盖）。`describe({ redactSecrets: true })`——在每个 wire 面都强制启用——经由对 schema 的纯结构遍历（object/dict/array 容器；secret 角色子树整体是一个不透明叶节点）从全部三层剥除 `role('secret')` 子树，并把剥除的槽位枚举为 `{path, set}`，页面因此不必收到任何值就能渲染只写输入框。
 
-**Host 识别并打开本地设置文档。** settings seam 暴露可选的 `documentPath` 提供方元数据和 `prepareDocument()` 操作；`settings-local` 返回已完全解析的自定义文件名或 `$DSH_HOME/settings.yaml` 文件名，并在文档缺失时以仅属主可访问的权限独占创建空文档，非文件提供方则保留基类的 `undefined`。仅限回环访问的 `settings.describe` 响应会在脱敏 namespace 视图旁只携带布尔型 `hasDocument` 能力。`ui-settings-general` 只在回环页面注册一条 `settings.action` 条目，只有元数据确认可准备好一份由提供方持有的本地文档后才显示，并调用无路径参数的 `settings.openDocument`；Host 会在文本文档交接前再次解析提供方路径（macOS 上使用 `open -t`，使任意 YAML 文件关联无法重定向这次操作；Linux 上使用 `xdg-open`；Windows 上使用 `Invoke-Item`）。通用 Workspace 路径仍保留现有的默认应用交接。浏览器既不推导 `$DSH_HOME`，也不会收到文件系统目标；远程页面不会为这项操作发起特权 settings 读取。
+**Host 识别并打开本地设置文档。** settings seam 暴露可选的 `documentPath` 提供方元数据和 `prepareDocument()` 操作；`settings-local` 返回已完全解析的自定义文件名或 `$DSH_HOME/settings.yaml` 文件名，并在文档缺失时以仅属主可访问的权限独占创建空文档，非文件提供方则保留基类的 `undefined`。仅限回环访问的 `settings.describe` 响应会在脱敏 namespace 视图旁只携带布尔型 `hasDocument` 能力。`ui-settings-general` 只在回环页面注册一条 `settings.action` 条目，只有元数据确认可准备好一份由提供方持有的本地文档后才显示，并调用无路径参数的 `settings.openDocument`；Host 会在文本文档交接前再次解析提供方路径（macOS 上使用 `open -t`，使任意 YAML 文件关联无法重定向这次操作；桌面 Linux 上使用 `xdg-open`；Windows 上使用 `Invoke-Item`；WSL 上先执行 `wslpath -w`，再使用同一 Windows 交接）。通用 Workspace 路径仍保留现有的默认应用交接。浏览器既不推导 `$DSH_HOME`，也不会收到文件系统目标；远程页面不会为这项操作发起特权 settings 读取。
 
 **llm seam 声明可配置性并公布拓扑。**`registerConfigurableProviders()` 是一个全有或全无、以 fiber 为作用域的目录，条目为 `{provider, displayName, settingsNs, settingsPath}`——这正是配置页要为一条可能尚不存在的路由打开正确设置子树时所需要的寻址；`listConfigurableProviders()` 在 wire 处理器里与存活路由合并，未声明的存活路由因此仍报告为激活。零负载的 `'llm/adapters-updated'` 事件从全部四个注册／注销提交点触发，listener 派发带异常隔离（INVARIANT 重抛），沿用 settings/commands 的先例。`llm-deepseek` 的路由重命名为 `deepseek-official`，因为 pi-ai catalog 名正言顺地拥有 `deepseek` 这个聚合器条目；依预发布立场，不设别名。
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml
index 9b8d037c43..a702f1511f 100644
--- a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.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 .agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.md
-2026-07-28-tool-call-file-open-in-os.md: a2c9b52507d32c2d851f811f0ecdd878a60b1e1c
-2026-07-28-tool-call-file-open-in-os.zh.md: 725db61869383711042d85cc1508b00eb1b196b6
+2026-07-28-tool-call-file-open-in-os.md: 73f5091888ab2506eab50b827e74c5120394b127
+2026-07-28-tool-call-file-open-in-os.zh.md: c1bc93c472aae8be8cee3bab6cd02f556abca494
diff --git a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.md b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.md
index a2c9b52507..73f5091888 100644
--- a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.md
+++ b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.md
@@ -12,12 +12,13 @@ Chat tool rows treated the whole summary line as a click target that opened the
 
 File-tool path summaries (`read` / `write` / `edit` args carrying `path` or `file_path`) render as hover-underline links with a pointer cursor. Clicking the path calls `host.openPath` through `WorkspacesService.openPath`, resolving relative paths against the session cwd. File-link rows disable args expand (leading icon is inert); whole-row click, row hover fill, and the click-to-open-details gesture are removed from tool rows (including bash and todo registrations). The details panel and its inject surface remain for programmatic selection; rows no longer drive them.
 
-`host.openPath` is a privileged unary RPC accepted only from loopback, same-origin browser requests (same carrier guard as `host.pickDirectory`). Platform adapters open without a shell: `open` on macOS, PowerShell `Invoke-Item` on Windows, `xdg-open` on Linux. The opener is injectable for tests. URL-only read args (`web_fetch`) are not file links.
+`host.openPath` is a privileged unary RPC accepted only from loopback, same-origin browser requests (same carrier guard as `host.pickDirectory`). Platform adapters open without a shell: `open` on macOS, PowerShell `Invoke-Item` on Windows, and `xdg-open` on desktop Linux. WSL is a separate host shape despite Node reporting `linux`: the adapter recognizes its environment or Microsoft kernel release, translates the Linux path with `wslpath -w`, and passes the resulting Windows/UNC path to the same PowerShell handoff. The opener's platform facts and command runner are injectable for tests. URL-only read args (`web_fetch`) are not file links.
 
 ## Alternatives considered
 
 - Keep row-click details and add a separate file affordance — rejected; the product ask replaces the row gesture with the file link.
 - Open files inside an in-app preview — rejected; the ask is the OS default application.
+- Treat WSL as desktop Linux — rejected; a WSL process reports `linux`, but a Linux desktop association is optional while its ordinary operator desktop and browser live on Windows.
 - Reuse `host.pickDirectory`'s timeout exemption — unnecessary; path open hand-off completes quickly under the normal unary deadline.
 
 ## Consequences
@@ -26,5 +27,5 @@ Clicking a file path in a tool row opens that path on the host. Non-file tool ro
 
 ## Risks
 
-- Linux hosts without `xdg-open` fail the RPC; the chat row stays silent while the host returns an internal error.
+- Desktop Linux hosts without `xdg-open`, and WSL hosts without working Windows interop (`wslpath` plus `powershell.exe`), fail the RPC; the chat row stays silent while the host returns an internal error.
 - Relative paths without a session cwd are forwarded verbatim and may fail on the host.
diff --git a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md
index 725db61869..c1bc93c472 100644
--- a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md
@@ -12,12 +12,13 @@ Status: implemented
 
 文件工具的路径摘要（`read`／`write`／`edit` 参数中的 `path` 或 `file_path`）渲染为悬停下划线链接并使用 pointer 光标。点击路径会经 `WorkspacesService.openPath` 调用 `host.openPath`，相对路径以会话 cwd 为基准解析。带文件链接的行关闭参数展开（左侧图标不可点）；工具行（含 bash 与 todo 注册）去掉整行点击、整行悬停底色，以及点击打开 details 的手势。details 面板及其 inject 面仍保留供程序化选择；工具行不再驱动它们。
 
-`host.openPath` 是特权一元 RPC，仅接受来自回环地址且同源的浏览器请求（与 `host.pickDirectory` 相同的载体守卫）。平台适配器不经 shell 打开：macOS 为 `open`，Windows 为 PowerShell `Invoke-Item`，Linux 为 `xdg-open`。打开器可在测试中注入。仅含 URL 的 read 参数（`web_fetch`）不是文件链接。
+`host.openPath` 是特权一元 RPC，仅接受来自回环地址且同源的浏览器请求（与 `host.pickDirectory` 相同的载体守卫）。平台适配器不经 shell 打开：macOS 为 `open`，Windows 为 PowerShell `Invoke-Item`，桌面 Linux 为 `xdg-open`。尽管 Node 将 WSL 报告为 `linux`，WSL 仍是一种独立的宿主形态：适配器根据其环境或 Microsoft 内核 release 识别它，用 `wslpath -w` 转换 Linux 路径，并将所得 Windows/UNC 路径交给同一 PowerShell 交接。打开器的平台信息和命令运行器可在测试中注入。仅含 URL 的 read 参数（`web_fetch`）不是文件链接。
 
 ## 考虑过的替代方案
 
 - 保留整行点击打开 details，另加文件入口 — 否决；产品要求用文件链接替换整行手势。
 - 在应用内预览文件 — 否决；要求是操作系统默认应用。
+- 将 WSL 当作桌面 Linux — 否决；WSL 进程报告 `linux`，但 Linux 桌面文件关联并非必有，而其常规用户桌面和浏览器位于 Windows 上。
 - 复用 `host.pickDirectory` 的超时豁免 — 不必要；打开路径的交接在常规一元截止时间内即可完成。
 
 ## 后果
@@ -26,5 +27,5 @@ Status: implemented
 
 ## 风险
 
-- 没有 `xdg-open` 的 Linux 宿主会使 RPC 失败；聊天行保持静默，宿主返回内部错误。
+- 没有 `xdg-open` 的桌面 Linux 宿主，以及 Windows 互操作（`wslpath` 加 `powershell.exe`）不可用的 WSL 宿主，会使 RPC 失败；聊天行保持静默，宿主返回内部错误。
 - 没有会话 cwd 时相对路径会原样转发，可能在宿主侧失败。
diff --git a/packages/client/ui-settings-general/README.i18n.yaml b/packages/client/ui-settings-general/README.i18n.yaml
index 9fe338ea47..9c61e62c48 100644
--- a/packages/client/ui-settings-general/README.i18n.yaml
+++ b/packages/client/ui-settings-general/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/client/ui-settings-general/README.md
-README.md: 29e48d193d24644f37d219b4df44a8fedf062e53
-README.zh.md: 17ebc9e8ab273aae0e7ea4c764da569da6d9f49f
+README.md: ab27e073dc76335efc619f56365d1705007f7ef2
+README.zh.md: 18bbecf67f51ae63bfacd4ba78437bea95b50bee
diff --git a/packages/client/ui-settings-general/README.md b/packages/client/ui-settings-general/README.md
index 29e48d193d..ab27e073dc 100644
--- a/packages/client/ui-settings-general/README.md
+++ b/packages/client/ui-settings-general/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Settings ownerless-copy and product-onboarding plugin: registers everything on the Settings surface that belongs to no single feature — the shell's trigger/header/close chrome content, the local configuration-file action, the General section and its `settings.general.item` slot, the `settings` dictionaries, and the first ordered welcome step. Feature-owned rows (Permission, Language, Appearance), sections (Models), and conditional onboarding steps stay with their feature packages.
 
-A loopback browser loads the provider's `hasDocument` capability through `settings.describe` and renders **Open configuration file** only when the Host confirms that a provider-owned local document can be prepared. The action sends the pathless, loopback-only `settings.openDocument` request; the Host resolves the provider path again, materializes an absent document, and hands it to a native text editor (`open -t` on macOS, bypassing a browser file association; the desktop file association on Linux and Windows). Open failures keep the action available and render a localized error. Reopening the dialog or reconnecting refreshes availability after a transient read failure or Host topology change. Remote browsers never register the action and never issue the privileged settings read.
+A loopback browser loads the provider's `hasDocument` capability through `settings.describe` and renders **Open configuration file** only when the Host confirms that a provider-owned local document can be prepared. The action sends the pathless, loopback-only `settings.openDocument` request; the Host resolves the provider path again, materializes an absent document, and hands it to a native text editor (`open -t` on macOS, bypassing a browser file association; the desktop file association on Linux and Windows; Windows association after `wslpath -w` translation on WSL). Open failures keep the action available and render a localized error. Reopening the dialog or reconnecting refreshes availability after a transient read failure or Host topology change. Remote browsers never register the action and never issue the privileged settings read.
 
 `src/onboarding-copy.ts` is the single editable owner of the complete notice plus `WELCOME_NOTICE_VERSION`; both supported GUI locales intentionally render the same Chinese copy. The Host half registers `ui-onboarding` in the user-settings seam. A loopback browser compares `welcomeNoticeVersion` for exact equality and writes the current value only after Continue succeeds. The path mutation is idempotent across tabs and preserves sibling settings, while `host/settings-changed` makes an externally acknowledged notice advance without a reload. A non-loopback browser cannot access the privileged settings API: it still presents the notice, but Continue advances only the current browser process and a reload presents the notice again. A different version deliberately presents the notice again. The welcome page preserves every authored paragraph, gives the requested clause in the final paragraph the sole emphasis, initially focuses the title, and has no close, Escape, mask-click, or secondary path. None of its copy or acknowledgement enters a Session log or model request. The notice identifies `DSH_TELEMETRY_DISABLED=1` as the telemetry opt-out.
 
diff --git a/packages/client/ui-settings-general/README.zh.md b/packages/client/ui-settings-general/README.zh.md
index 17ebc9e8ab..18bbecf67f 100644
--- a/packages/client/ui-settings-general/README.zh.md
+++ b/packages/client/ui-settings-general/README.zh.md
@@ -4,7 +4,7 @@
 
 设置界面无特定功能归属的文案与产品引导插件：在设置界面注册所有不属于单一功能的内容，包括外壳的触发器、标题栏与关闭控件内容、本地配置文件操作，「通用」分区及其 `settings.general.item` slot、`settings` 字典，以及第一个有序欢迎步骤。归具体功能所有的行（「权限」、「语言」、「外观」）、分区（「模型」）和条件式首次使用引导步骤仍由各自的功能包提供。
 
-回环浏览器通过 `settings.describe` 加载提供方的 `hasDocument` 能力，且只有在 Host 确认可准备好一份由提供方持有的本地文档时才渲染**打开配置文件**。该操作发送无路径参数且仅限回环访问的 `settings.openDocument` 请求；Host 会再次解析提供方路径、在文档缺失时将其创建出来，并交给原生文本编辑器（macOS 上使用 `open -t`，绕过浏览器文件关联；Linux 和 Windows 上使用桌面文件关联）。打开失败时该操作仍可使用，并渲染本地化错误。临时读取失败或 Host 拓扑变化后，重新打开对话框或重新连接会刷新可用性。远程浏览器从不注册该操作，也从不发起这项特权 settings 读取。
+回环浏览器通过 `settings.describe` 加载提供方的 `hasDocument` 能力，且只有在 Host 确认可准备好一份由提供方持有的本地文档时才渲染**打开配置文件**。该操作发送无路径参数且仅限回环访问的 `settings.openDocument` 请求；Host 会再次解析提供方路径、在文档缺失时将其创建出来，并交给原生文本编辑器（macOS 上使用 `open -t`，绕过浏览器文件关联；Linux 和 Windows 上使用桌面文件关联；WSL 上经 `wslpath -w` 转换后使用 Windows 文件关联）。打开失败时该操作仍可使用，并渲染本地化错误。临时读取失败或 Host 拓扑变化后，重新打开对话框或重新连接会刷新可用性。远程浏览器从不注册该操作，也从不发起这项特权 settings 读取。
 
 `src/onboarding-copy.ts` 是完整通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源；GUI 支持的两种 locale 都有意渲染同一份中文文案。宿主端在 user-settings seam 中注册 `ui-onboarding`。loopback 浏览器会比较 `welcomeNoticeVersion` 是否精确相等，仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等，并会保留同级设置；`host/settings-changed` 则让页面在通知被外部确认后，无需重新加载即可推进。非 loopback 浏览器不能访问受保护的 settings API：它仍会显示通知，但「继续」只推进当前浏览器进程，重新加载后会再次显示通知。版本不同时，系统也会有意重新显示通知。欢迎页保留原文的每个段落，仅强调最后一段中指定的句段，初始焦点落在标题上，并且没有关闭操作、Escape、点击遮罩或次要操作路径。其文案和确认状态均不会进入会话日志或模型请求。通知明确以 `DSH_TELEMETRY_DISABLED=1` 作为遥测关闭方式。
 
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 38c79f4617..77fa4afe7d 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 0963476a767801b465a6ead24feb0ecc9988b5f5
-README.zh.md: e3634c5f92f3a3723eb3c14e39223d9d9550c6f9
+README.md: 395e0d5085878e230fdf7de49a0ca47745bdc270
+README.zh.md: 2ef34f7d6e7ae031dd5f847dfa13827fe4550839
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 0963476a76..395e0d5085 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -32,7 +32,7 @@ A stale continuation discards every partial result, deduplication entry, and cur
 
 Directory picking delegates to the composed `ctx.directoryPicker` backend ([the directory-picker seam](../directory-picker/README.md)); a method called outside the composed capability's kind fails with `directory-picker-unavailable` (the client needs no advertisement — the composed picker package's own client half renders the matching interaction). Under `native`, `host.pickDirectory` opens one native chooser and returns its selected path (`null` on cancel); this user-paced method does not use the default 30-second unary timeout, while caller/connection aborts still propagate to the native process. Under `browse`, `host.listDirectory` returns one name-sorted directory level with breadcrumb ancestry, a `home` anchor, and host-owned `hidden` flags (absent path = home directory), and `host.createDirectory` creates one validated child segment; the backend's typed failures map 1:1 onto the `directory-unreadable`/`directory-exists`/`directory-create-failed` codes. The browser carrier's prefix-wide trust fence (dsh-client-connection) covers all of these like every other `/api` request.
 
-`host.openPath` opens a filesystem path with the operating system's default application (`open` on macOS, `Invoke-Item` on Windows, `xdg-open` on Linux). The browser carrier applies the same loopback, same-origin restriction as `host.pickDirectory`.
+`host.openPath` opens a filesystem path with the operating system's default application (`open` on macOS, `Invoke-Item` on Windows, and `xdg-open` on desktop Linux). WSL translates the Linux path through `wslpath -w` and hands the resulting Windows/UNC path to Windows `Invoke-Item` instead of assuming a Linux desktop association. The browser carrier applies the same loopback, same-origin restriction as `host.pickDirectory`.
 
 The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the browser's user-selected model-reference path, so it returns only skills that are both model-invocable and user-invocable; this domain has no direct skill-loading RPC. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index e3634c5f92..2ef34f7d6e 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -32,7 +32,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 目录选择委托给组合的 `ctx.directoryPicker` 后端（[目录选择 seam](../directory-picker/README.md)）；调用组合能力 kind 之外的方法会以 `directory-picker-unavailable` 失败（客户端不需要广播——组合的选择器包自己的 client half 渲染匹配的交互）。在 `native` 下，`host.pickDirectory` 打开一个原生选择器并返回选中路径（取消为 `null`）；该方法需等待用户完成操作，不使用默认的 30 秒一元调用超时，而调用方与连接的中止仍会传播至原生进程。在 `browse` 下，`host.listDirectory` 返回一个按名称排序的目录层级，携带面包屑祖先链、`home` 锚点与宿主判定的 `hidden` 标志（不带路径即家目录），`host.createDirectory` 创建一个经校验的子段；后端的类型化失败 1:1 映射为 `directory-unreadable`／`directory-exists`／`directory-create-failed` 错误码。浏览器载体的前缀级信任栅栏（dsh-client-connection）像覆盖其他所有 `/api` 请求一样覆盖上述全部方法。
 
-`host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，Linux 为 `xdg-open`）。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。
+`host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，桌面 Linux 为 `xdg-open`）。WSL 会通过 `wslpath -w` 转换 Linux 路径，并将所得 Windows/UNC 路径交给 Windows `Invoke-Item`，而非假定存在 Linux 桌面文件关联。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。
 
 `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于浏览器中由用户选择的模型引用路径，因此仅返回模型和用户均可调用的 skill；该领域没有直接加载 skill 的 RPC。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
 
diff --git a/packages/host/apiproxy/src/native-path-opener.ts b/packages/host/apiproxy/src/native-path-opener.ts
index a9fdd56bc4..fa7ae5d081 100644
--- a/packages/host/apiproxy/src/native-path-opener.ts
+++ b/packages/host/apiproxy/src/native-path-opener.ts
@@ -1,5 +1,6 @@
 /** Cross-platform native path and text-document openers used by the local GUI carrier. */
 
+import { release as osRelease } from 'node:os'
 import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
 
 /** Testable command boundary; native implementations never invoke a shell. */
@@ -8,6 +9,10 @@ export type PathOpenerRunner = NativeCommandRunner
 /** Injectable platform facts for deterministic adapter tests. */
 export interface PathOpenerInternals {
   platform?: NodeJS.Platform
+  /** Kernel release override used to distinguish WSL from desktop Linux. */
+  osRelease?: string
+  /** WSL environment marker override used with the kernel release. */
+  env?: Readonly<Partial<Record<'WSL_DISTRO_NAME' | 'WSL_INTEROP', string>>>
   run?: PathOpenerRunner
 }
 
@@ -19,6 +24,36 @@ function powershellLiteral(path: string): string {
   return `'${path.replace(/'/g, "''")}'`
 }
 
+/** Whether one environment marker is set to a non-empty value. */
+function present(value: string | undefined): boolean {
+  return value !== undefined && value !== ''
+}
+
+/** Distinguish WSL from desktop Linux using its process and kernel markers. */
+function isWsl(internals: PathOpenerInternals): boolean {
+  const env = internals.env ?? process.env
+  if (present(env.WSL_DISTRO_NAME) || present(env.WSL_INTEROP)) return true
+  return (internals.osRelease ?? osRelease()).toLowerCase().includes('microsoft')
+}
+
+/** Open one Windows-resolvable path through its registered desktop application. */
+async function openWindowsPath(path: string, signal: AbortSignal, run: PathOpenerRunner): Promise<void> {
+  await run('powershell.exe', [
+    '-NoProfile',
+    '-Command',
+    `Invoke-Item -LiteralPath ${powershellLiteral(path)}`,
+  ], signal)
+}
+
+/** Translate a WSL path before handing it to the Windows desktop. */
+async function openWslPath(path: string, signal: AbortSignal, run: PathOpenerRunner): Promise<void> {
+  const translated = await run('wslpath', ['-w', path], signal)
+  signal.throwIfAborted()
+  const windowsPath = translated.stdout.replace(/[\r\n]+$/, '')
+  if (windowsPath === '') throw new Error('wslpath returned no Windows path')
+  await openWindowsPath(windowsPath, signal, run)
+}
+
 /** Dispatch one shell-free platform command for the requested open intent. */
 async function openNativePathWithIntent(
   path: string,
@@ -35,15 +70,15 @@ async function openNativePathWithIntent(
   }
 
   if (platform === 'win32') {
-    await run('powershell.exe', [
-      '-NoProfile',
-      '-Command',
-      `Invoke-Item -LiteralPath ${powershellLiteral(path)}`,
-    ], signal)
+    await openWindowsPath(path, signal, run)
     return
   }
 
   if (platform === 'linux') {
+    if (isWsl(internals)) {
+      await openWslPath(path, signal, run)
+      return
+    }
     await run('xdg-open', [path], signal)
     return
   }
diff --git a/packages/host/apiproxy/tests/native-path-opener.spec.ts b/packages/host/apiproxy/tests/native-path-opener.spec.ts
index 236de1c9a7..0c6c327273 100644
--- a/packages/host/apiproxy/tests/native-path-opener.spec.ts
+++ b/packages/host/apiproxy/tests/native-path-opener.spec.ts
@@ -14,6 +14,7 @@ const { execFileMock } = vi.hoisted(() => ({ execFileMock: vi.fn<ExecFileMock>()
 
 vi.mock('node:child_process', () => ({ execFile: execFileMock }))
 
+import { release as osRelease } from 'node:os'
 import { describe, expect, it, vi } from 'vitest'
 import { openNativePath, openNativeTextFile, type PathOpenerRunner } from '../src/native-path-opener.ts'
 
@@ -34,10 +35,58 @@ describe('native path opener', () => {
 
   it('uses the Linux desktop association for text documents', async () => {
     const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
-    await openNativeTextFile('/tmp/settings.yaml', signal(), { platform: 'linux', run })
+    await openNativeTextFile('/tmp/settings.yaml', signal(), {
+      platform: 'linux', osRelease: '6.8.0-generic', env: {}, run,
+    })
     expect(run).toHaveBeenCalledWith('xdg-open', ['/tmp/settings.yaml'], expect.any(AbortSignal))
   })
 
+  it.each([
+    ['distribution marker', { WSL_DISTRO_NAME: 'Ubuntu' }, '6.8.0-generic'],
+    ['interop marker', { WSL_INTEROP: '/run/WSL/123_interop' }, '6.8.0-generic'],
+    ['kernel release', {}, '5.15.153.1-microsoft-standard-WSL2'],
+  ])('hands WSL text documents to the Windows desktop from the %s', async (_label, env, osRelease) => {
+    const requestSignal = signal()
+    const run = vi.fn<PathOpenerRunner>(async command => command === 'wslpath'
+      ? { stdout: '\\\\wsl.localhost\\Ubuntu\\home\\test user\\settings.yaml\r\n', stderr: '' }
+      : { stdout: '', stderr: '' })
+    await openNativeTextFile('/home/test user/settings.yaml', requestSignal, {
+      platform: 'linux', osRelease, env, run,
+    })
+    expect(run.mock.calls).toEqual([
+      ['wslpath', ['-w', '/home/test user/settings.yaml'], requestSignal],
+      [
+        'powershell.exe',
+        [
+          '-NoProfile',
+          '-Command',
+          "Invoke-Item -LiteralPath '\\\\wsl.localhost\\Ubuntu\\home\\test user\\settings.yaml'",
+        ],
+        requestSignal,
+      ],
+    ])
+  })
+
+  it('rejects an empty WSL path translation before invoking Windows', async () => {
+    const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '\r\n', stderr: '' }))
+    await expect(openNativeTextFile('/home/test/settings.yaml', signal(), {
+      platform: 'linux', osRelease: '6.8.0-generic', env: { WSL_DISTRO_NAME: 'Ubuntu' }, run,
+    })).rejects.toThrow('wslpath returned no Windows path')
+    expect(run).toHaveBeenCalledOnce()
+  })
+
+  it('does not invoke Windows when the request aborts during WSL path translation', async () => {
+    const abort = new AbortController()
+    const run = vi.fn<PathOpenerRunner>(async () => {
+      abort.abort(new Error('closed'))
+      return { stdout: '\\\\wsl.localhost\\Ubuntu\\home\\test\\settings.yaml\n', stderr: '' }
+    })
+    await expect(openNativeTextFile('/home/test/settings.yaml', abort.signal, {
+      platform: 'linux', osRelease: '6.8.0-generic', env: { WSL_DISTRO_NAME: 'Ubuntu' }, run,
+    })).rejects.toThrow('closed')
+    expect(run).toHaveBeenCalledOnce()
+  })
+
   it('opens with Windows Invoke-Item and escapes single quotes', async () => {
     const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
     await openNativePath("C:\\work\\o'reilly.txt", signal(), { platform: 'win32', run })
@@ -60,7 +109,10 @@ describe('native path opener', () => {
 
   it('opens with Linux xdg-open', async () => {
     const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
-    await openNativePath('/tmp/a.txt', signal(), { platform: 'linux', run })
+    await openNativePath('/tmp/a.txt', signal(), {
+      platform: 'linux', osRelease: '6.8.0-generic',
+      env: { WSL_DISTRO_NAME: '', WSL_INTEROP: '' }, run,
+    })
     expect(run).toHaveBeenCalledWith('xdg-open', ['/tmp/a.txt'], expect.any(AbortSignal))
   })
 
@@ -71,7 +123,9 @@ describe('native path opener', () => {
 
   it('uses the current process platform when no platform override is supplied', async () => {
     const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
-    await openNativePath('/tmp/platform-default.txt', signal(), { run })
+    await openNativePath('/tmp/platform-default.txt', signal(), {
+      osRelease: '6.8.0-generic', env: {}, run,
+    })
     const expected = process.platform === 'win32'
       ? 'powershell.exe'
       : process.platform === 'linux'
@@ -80,6 +134,17 @@ describe('native path opener', () => {
     expect(run.mock.calls[0]?.[0]).toBe(expected)
   })
 
+  it('samples ambient WSL markers and kernel release when no fact overrides are supplied', async () => {
+    const ambientWsl = [process.env.WSL_DISTRO_NAME, process.env.WSL_INTEROP]
+      .some(value => value !== undefined && value !== '')
+      || osRelease().toLowerCase().includes('microsoft')
+    const run = vi.fn<PathOpenerRunner>(async command => command === 'wslpath'
+      ? { stdout: 'C:\\settings.yaml\n', stderr: '' }
+      : { stdout: '', stderr: '' })
+    await openNativePath('/tmp/ambient-facts.yaml', signal(), { platform: 'linux', run })
+    expect(run.mock.calls[0]?.[0]).toBe(ambientWsl ? 'wslpath' : 'xdg-open')
+  })
+
   it('runs the default command adapter without a shell and preserves command failures', async () => {
     execFileMock.mockImplementationOnce((_command, _args, _options, callback) => {
       callback(null, '', '')

From 1f853d85cd33fd91c56e34c98831adbb48f5410d Mon Sep 17 00:00:00 2001
From: fz <fz@dsh.dev>
Date: Thu, 6 Aug 2026 11:09:09 +0800
Subject: [PATCH 096/516] Attribute reader scroll input through the
 observed-top ledger

ChatView's bottom-follow recognized only wheel gestures as reader input,
so touch panning, scrollbar dragging, and keyboard paging could not leave
the bottom of a streaming transcript. Replace the wheel listener with
device-agnostic attribution: a scroll position deviating from the
observed-top ledger of the last delivered or written scrollTop is reader
input. Adds keyboard-paging and touch-style fling e2e scenarios (red under
the old implementation) and the bilingual Agent Note triplet.
---
 ...cky-composer-conversation-scroll.i18n.yaml |   4 +-
 ...-29-sticky-composer-conversation-scroll.md |   6 +-
 ...-sticky-composer-conversation-scroll.zh.md |   6 +-
 ...-attribution-observed-top-ledger.i18n.yaml |   6 +
 ...-scroll-attribution-observed-top-ledger.md |  37 +++++
 ...roll-attribution-observed-top-ledger.zh.md |  37 +++++
 ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml |   4 +-
 .../2026-07-24-web-gui-browser-e2e-lane.md    |   2 +-
 .../2026-07-24-web-gui-browser-e2e-lane.zh.md |   2 +-
 apps/web/tests/chat-scroll-contract.e2e.ts    | 145 ++++++++++++++++++
 .../src/client/chat/ChatView.tsx              |  45 ++----
 .../ui-conversation/tests/chat-view.spec.tsx  |  22 +--
 12 files changed, 262 insertions(+), 54 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md

diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
index b849211296..fdb487f16b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.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 .agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
-2026-07-29-sticky-composer-conversation-scroll.md: d3fed7a9d0b1f39f9551fbd85e0f83515b1a2690
-2026-07-29-sticky-composer-conversation-scroll.zh.md: 2beee34d3bb68832d14b7607b43aa11e1425d53d
+2026-07-29-sticky-composer-conversation-scroll.md: 8657080078e475d6e90f17a6c0f8cb5b2fb1555d
+2026-07-29-sticky-composer-conversation-scroll.zh.md: a588903adf51c6fcdd01f851d4f5e6570f695242
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
index d3fed7a9d0..8657080078 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
@@ -14,7 +14,7 @@ The active conversation column split scrolling: the chat (and trajectory) view o
 
 Session stats live on `'conversation.composer.dock'` (above `'conversation.input.dock'`). The InputBar textarea, when inside the host, chains `wheel` with `{ passive: false }`: while the capped textarea can still scroll in that direction it keeps the native gesture; only at its own edge does it `preventDefault` and apply `deltaY` to the host.
 
-Chat history prepend follows reader intent through stable rendered node/call identities rather than whole-scrollport height deltas. `ChatView` records the first visible `data-chat-anchor-key` and its top relative to the scrollport when paging starts, reselects the currently visible stable anchor after every reader scroll while the request is in flight, and compensates by that row's post-prepend rectangle delta. Reaching the bottom or appending the reader's own message cancels the paging anchor, so a late page cannot pull the view away from the newest content. Bottom follow is stored state rather than raw scroll geometry. A passive wheel listener takes its pre-input baseline from the last main-thread-delivered or programmatically written `scrollTop`, because Chromium may advance compositor geometry before delivering the event; the current non-negative floor excludes a concurrent layout clamp from reader movement. A scroll without matching wheel movement re-pins while following and only refreshes the semantic position while reading. ChatView's single `ResizeObserver` follows streaming, tool disclosure, and draft resize only while bottom ownership remains pinned, without a second per-chunk scroll write.
+Chat history prepend follows reader intent through stable rendered node/call identities rather than whole-scrollport height deltas. `ChatView` records the first visible `data-chat-anchor-key` and its top relative to the scrollport when paging starts, reselects the currently visible stable anchor after every reader scroll while the request is in flight, and compensates by that row's post-prepend rectangle delta. Reaching the bottom or appending the reader's own message cancels the paging anchor, so a late page cannot pull the view away from the newest content. Bottom follow is stored state rather than raw scroll geometry; how reader input is recognized — device-agnostic deviation from the observed-top ledger of the last delivered or written `scrollTop` — is owned by the [reader-scroll-attribution note](2026-08-06-reader-scroll-attribution-observed-top-ledger.md). ChatView's single `ResizeObserver` follows streaming, tool disclosure, and draft resize only while bottom ownership remains pinned, without a second per-chunk scroll write.
 
 ## Alternatives considered
 
@@ -26,8 +26,8 @@ Chat history prepend follows reader intent through stable rendered node/call ide
 
 **Keep StatsLine inside ChatView below the message column.** Rejected: outside the sticky composer it would scroll away while the input stayed pinned.
 
-**Model every browser scroll input source.** Rejected for this narrow fix: the reproduced desktop path uses wheel/trackpad input. Pointer/touch scrolling, native-scrollbar dragging, keyboard scrolling, focus navigation, and nested overflow ownership remain outside the provenance model instead of adding a general input state machine.
+**Model every browser scroll input source.** Rejected for this narrow fix: the reproduced desktop path uses wheel/trackpad input. Pointer/touch scrolling, native-scrollbar dragging, keyboard scrolling, focus navigation, and nested overflow ownership were left outside the provenance model instead of adding a general input state machine. The [reader-scroll-attribution note](2026-08-06-reader-scroll-attribution-observed-top-ledger.md) later closed this deferral by generalizing attribution through the observed-top ledger, still without an input state machine.
 
 ## Consequences
 
-Wheel over the footer scrolls the transcript; the visible layout is a fixed header, scrolling transcript, and sticky bottom composer. Stats appear on every active view tab. Nested view scrollers under the host are suppressed so sticky Turn headers in Trajectory stick to the column host. Concurrent history, streaming, tool expansion, and composer reflow preserve wheel/trackpad scroll decisions, including Chromium's compositor-first delivery and stream-finalization clamp/regrow. Other browser scroll inputs do not change follow ownership under this narrow provenance rule. No session → blank Hero and Hero → active both keep the same textarea DOM node and InputHub draft.
+Wheel over the footer scrolls the transcript; the visible layout is a fixed header, scrolling transcript, and sticky bottom composer. Stats appear on every active view tab. Nested view scrollers under the host are suppressed so sticky Turn headers in Trajectory stick to the column host. Concurrent history, streaming, tool expansion, and composer reflow preserve reader scroll decisions, including Chromium's compositor-first delivery and stream-finalization shrink clamp. Follow ownership extends to every reader input under the [reader-scroll-attribution note](2026-08-06-reader-scroll-attribution-observed-top-ledger.md). No session → blank Hero and Hero → active both keep the same textarea DOM node and InputHub draft.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md
index 2beee34d3b..a588903adf 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 会话统计挂在 `'conversation.composer.dock'`（位于 `'conversation.input.dock'` 之上）。InputBar 的 textarea 在宿主内以 `{ passive: false }` 链式处理 `wheel`：在限高 textarea 仍能沿该方向滚动时保留原生手势；仅在自身边缘才 `preventDefault` 并将 `deltaY` 施加到宿主。
 
-Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图，而不是使用整个滚动容器的高度差。分页开始时，`ChatView` 记录第一个可见的 `data-chat-anchor-key` 及其相对滚动容器的顶部位置；请求在途期间，每次读者滚动都会重新选择当前可见的稳定锚点；页面到达后则按该行矩形的前后差值补偿。到达底部或追加读者自己的消息会取消分页锚点，因此迟到的页面不能把视图从最新内容拉走。贴底跟随采用存储状态，而不是原始滚动几何状态。passive wheel 监听器以最近一次由主线程交付或由程序写入的 `scrollTop` 作为输入前基线，因为 Chromium 可能先推进合成器几何状态，之后才交付事件；当前使用的非负下限不会将并发的布局钳制计入读者移动。没有对应滚轮／触控板输入位移的滚动，在跟随状态下会重新贴底，在阅读状态下则只刷新语义位置。`ChatView` 的单个 `ResizeObserver` 只会在贴底所有权仍保持时跟随流式输出、工具展开与草稿尺寸变化，且每个 chunk 不会触发第二次滚动写入。
+Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图，而不是使用整个滚动容器的高度差。分页开始时，`ChatView` 记录第一个可见的 `data-chat-anchor-key` 及其相对滚动容器的顶部位置；请求在途期间，每次读者滚动都会重新选择当前可见的稳定锚点；页面到达后则按该行矩形的前后差值补偿。到达底部或追加读者自己的消息会取消分页锚点，因此迟到的页面不能把视图从最新内容拉走。贴底跟随采用存储状态，而不是原始滚动几何状态；读者输入如何被识别——即以与设备无关的方式偏离由最近一次交付或写入的 `scrollTop` 构成的 observed-top ledger——由[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)负责。`ChatView` 的单个 `ResizeObserver` 只会在贴底所有权仍保持时跟随流式输出、工具展开与草稿尺寸变化，且每个 chunk 不会触发第二次滚动写入。
 
 ## Alternatives considered
 
@@ -26,8 +26,8 @@ Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图
 
 **把 StatsLine 留在 ChatView 消息列下方。** 否决：落在 sticky 编辑器之外会随内容滚走，而输入区仍钉在底部。
 
-**为每一种浏览器滚动输入来源建模。** 此次窄范围修复不采用：已复现的桌面端路径使用滚轮／触控板输入。指针／触控滚动、拖动原生滚动条、键盘滚动、焦点导航与嵌套 overflow 所有权仍不纳入输入来源模型，也不为此新增通用输入状态机。
+**为每一种浏览器滚动输入来源建模。** 此次窄范围修复不采用：已复现的桌面端路径使用滚轮／触控板输入。指针／触控滚动、拖动原生滚动条、键盘滚动、焦点导航与嵌套 overflow 所有权当时被留在输入来源模型之外，也未为此新增通用输入状态机。[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)后来通过 observed-top ledger 泛化了归因，补上了这一延后事项，且仍未引入输入状态机。
 
 ## Consequences
 
-在页脚上滚轮会滚动 transcript；可见布局是固定标题栏、可滚动 transcript 与 sticky 底部编辑器。统计出现在每一个活跃视图标签上。宿主下的嵌套视图 scroller 被抑制，因而 Trajectory 的 sticky Turn 标题贴在列宿主上。并发历史加载、流式输出、工具展开与编辑器重排会保留滚轮／触控板的滚动决定，包括 Chromium 先推进合成器几何状态再交付事件，以及流收尾阶段滚动位置受钳制后滚动容器重新增长的情况。在这条窄范围的输入来源规则下，其他浏览器滚动输入不会改变贴底跟随所有权。无 session → blank Hero 与 Hero → active 都保持同一 textarea DOM 节点以及 InputHub 草稿。
+在页脚上滚轮会滚动 transcript；可见布局是固定标题栏、可滚动 transcript 与 sticky 底部编辑器。统计出现在每一个活跃视图标签上。宿主下的嵌套视图 scroller 被抑制，因而 Trajectory 的 sticky Turn 标题贴在列宿主上。并发历史加载、流式输出、工具展开与编辑器重排会保留读者的滚动决定，包括 Chromium 先推进合成器几何状态再交付事件，以及流收尾阶段的收缩钳制。贴底跟随所有权依据[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)扩展到每一种读者输入。无 session → blank Hero 与 Hero → active 都保持同一 textarea DOM 节点以及 InputHub 草稿。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
new file mode 100644
index 0000000000..1c861833cf
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.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-08-06-reader-scroll-attribution-observed-top-ledger.md
+2026-08-06-reader-scroll-attribution-observed-top-ledger.md: 2dcd0178e4216d4d3e2edcd3bfcc05b63606c333
+2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: ffb03fdb68c9cb040e311077dd698b310a033fdd
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
new file mode 100644
index 0000000000..2dcd0178e4
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
@@ -0,0 +1,37 @@
+# Agent Note: Reader scroll attribution through the observed-top ledger
+
+Status: implemented
+
+English | [中文](2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md)
+
+## Problem
+
+ChatView's bottom-follow recognized only wheel/trackpad gestures as reader input: while pinned to the floor, a scroll event without matching wheel movement was treated as programmatic and snapped back. Touch panning, native-scrollbar dragging, and keyboard paging therefore could not leave the bottom of a streaming transcript — on a phone the tail was effectively locked. That wheel-only provenance was a deliberate deferral in the [sticky-composer note](2026-07-29-sticky-composer-conversation-scroll.md), which rejected a general input state machine "for this narrow fix" and left every other scroll source outside the model.
+
+## Decision
+
+Reader input is no longer identified by device. ChatView keeps an observed-top ledger (`observedTopRef`): the last `scrollTop` either delivered on the main thread or written by the component, recorded synchronously at every programmatic write site — bottom follow, open restore, prepend anchoring, resize follow, and scroll delivery itself. When a scroll event arrives, a position that deviates from `min(ledger, floor)` by more than half a pixel is reader input; a position on the ledger (a delayed programmatic delivery) or exactly on the shrunken floor (a browser clamp after content shrank) preserves the current ownership state. Ownership then changes only through reader input under the existing threshold rule: within `FOLLOW_THRESHOLD` of the floor re-pins, beyond it releases follow and shows Back to bottom. The wheel listener and its epoch bookkeeping are deleted; the component listens to `scroll` alone, so wheel, touch, scrollbar, keyboard, and any future input source are covered by one rule.
+
+## Contract change: coalesced shrink-plus-regrow clamps
+
+A shrink clamp whose layout regrows within the same rendering update before the clamp's scroll event is delivered is geometrically indistinguishable from reader input, so it now reads as the reader and releases follow (Back to bottom recovers). Realistic React-commit-driven shrink and regrow is still absorbed: the layout-effect follow re-pins and re-records the ledger per commit, and a shrink-only clamp lands exactly on `min(ledger, floor)`. Only a non-React reflow that shrinks and regrows inside one update mis-attributes. The previous wheel model kept following in that raced case; the unit contract was rewritten to the absorbed-shrink-only guarantee in the same change.
+
+## Testing
+
+Unit specs in `packages/client/ui-conversation/tests/chat-view.spec.tsx` pin the ledger contract directly: a `readerScroll` helper delivers a position the component never wrote, programmatic deliveries land on the ledger, and the stream-finalization shrink clamp keeps following. Two scenarios in `apps/web/tests/chat-scroll-contract.e2e.ts` extend the [browser e2e lane](../testing/2026-07-24-web-gui-browser-e2e-lane.md): keyboard paging over a settled transcript and a touch-style momentum fling against paced streaming, both red under the wheel-only implementation and green under the ledger.
+
+The lane's Chromium cannot synthesize any non-wheel device scrolling, which bounds what the e2e can drive for real: `Input.synthesizeScrollGesture` with a touch source and hand-rolled `Input.dispatchTouchEvent` sequences deliver DOM events but never move a scroller (headless and headed-under-Xvfb alike); the `default` gesture source synthesizes wheel events; and compositor scrollbars ignore synthetic mouse input entirely, with a gutter visible only when `--hide-scrollbars` is removed. Keyboard is the one working non-wheel primitive, so it carries the real-input-pipeline proof, and the fling scenario replays touch's signature — per-frame decaying displacements the component never authored — through the scrollport directly.
+
+## Alternatives considered
+
+**Keep the wheel-only model.** Rejected: it is the defect. Touch, scrollbar, and keyboard readers cannot take ownership away from a streaming tail, and each newly supported device would need its own carve-out.
+
+**Enumerate input devices.** Adding `touchstart`/`pointerdown`/`keydown` listeners beside the wheel epoch was the obvious extension. Rejected: native-scrollbar dragging exposes no input event to latch before its scrolls arrive, device lists rot as browsers add sources, and every listener would need its own compositor-delivery grace window — the input state machine the sticky-composer note already declined to build.
+
+**Absorb the coalesced shrink-plus-regrow clamp with heuristics.** Floor-mismatch grace windows or deferred rAF re-checks could keep the raced clamp from reading as the reader. Rejected: streaming rewrites the floor at chunk pace (24 ms) against ~16 ms frames, so any grace window either swallows genuine touch input during streaming — reopening the bug this change fixes — or is too short to cover the race it targets. The mis-attribution is accepted and recoverable instead.
+
+**Drive real touch and scrollbar devices in e2e.** Rejected by the environment, not by preference: every synthesis path (CDP touch gestures, touch event sequences, synthetic mouse on classic scrollbars, headed under Xvfb) was probed and cannot scroll; the details live in Testing above.
+
+## Consequences
+
+Every reader input owns bottom-follow uniformly, with less code: the wheel listener, its epoch counter, and the pre-input baseline bookkeeping are gone, and attribution rides state the component already maintained. The sticky-composer note's layout, wheel chaining, and prepend-anchoring decisions are untouched and remain authoritative; its narrow provenance rule is superseded by this note. The cost is the contract change above — a coalesced non-React shrink-plus-regrow clamp now pauses follow until the reader returns to the floor or presses Back to bottom — traded for touch, scrollbar, and keyboard correctness during streaming. The e2e lane gains non-wheel coverage only within what its browser can synthesize; if gesture synthesis starts working in a future Chromium, the fling emulation can be replaced by real touch strokes without changing the asserted contract.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
new file mode 100644
index 0000000000..ffb03fdb68
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 经由 observed-top ledger 的读者滚动归因
+
+Status: implemented
+
+[English](2026-08-06-reader-scroll-attribution-observed-top-ledger.md) | 中文
+
+## 问题
+
+ChatView 的贴底跟随此前只把滚轮／触控板手势识别为读者输入：钉在底部（floor）期间，一个没有对应滚轮位移的滚动事件会被视为程序化滚动并被拉回底部。因此触控平移、拖动原生滚动条与键盘翻页都无法离开流式 transcript（文本记录）的底部，在手机上尾部实际上被锁死。这种仅认滚轮的输入来源判定是 [sticky-composer 笔记](2026-07-29-sticky-composer-conversation-scroll.md)中有意的暂缓：该笔记拒绝为「此次窄范围修复」建立通用输入状态机，把其余所有滚动来源都留在模型之外。
+
+## 决策
+
+读者输入不再依据设备来识别。ChatView 维护一份 observed-top ledger（`observedTopRef`）：即最近一次由主线程交付、或由组件自身写入的 `scrollTop`，并在每一个程序化写入点（贴底跟随、打开时恢复、前置锚定、尺寸变化跟随以及滚动交付本身）同步记录。滚动事件到达时，偏离 `min(ledger, floor)` 超过半像素的位置即为读者输入；落在 ledger 上的位置（迟到的程序化交付），或恰好落在收缩后底部上的位置（内容收缩后的浏览器钳制），则维持当前的所有权状态。此后所有权只经由读者输入、按既有阈值规则变化：位置距底部在 `FOLLOW_THRESHOLD` 以内则重新贴底，超出则释放跟随并显示「回到底部」。滚轮监听器及其 epoch 簿记已删除；组件只监听 `scroll`，因此滚轮、触控、滚动条、键盘以及未来任何输入来源都由同一条规则覆盖。
+
+## 契约变更：收缩与重新增长被合并的钳制
+
+如果一次收缩钳制的布局在同一次渲染更新内、赶在该钳制的滚动事件交付之前重新增长，那么这个事件在几何上与读者输入无法区分，因此它现在会被判读为读者并释放跟随（可经「回到底部」恢复）。现实中由 React 提交（commit）驱动的收缩与重新增长仍会被吸收：layout effect 中的跟随会在每次提交后重新贴底并重新记录 ledger，而仅收缩的钳制会恰好落在 `min(ledger, floor)` 上。只有在同一次更新内先收缩再重新增长的非 React 重排会被误归因。旧的滚轮模型在这种竞态情形下会保持跟随；单元测试契约已在同一变更中改写为只吸收纯收缩的保证。
+
+## 测试
+
+`packages/client/ui-conversation/tests/chat-view.spec.tsx` 中的单元测试直接钉住 ledger 契约：`readerScroll` 辅助函数交付一个组件从未写入过的位置，程序化交付落在 ledger 上，流收尾阶段的收缩钳制保持跟随。`apps/web/tests/chat-scroll-contract.e2e.ts` 中的两个场景扩展了[浏览器 e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)：在已停稳的 transcript 上做键盘翻页，以及对着按节奏推进的流式输出做一次触控式惯性快滑（momentum fling）；两者在仅认滚轮的实现下均为红、在 ledger 下均为绿。
+
+该车道的 Chromium 无法合成任何非滚轮的设备滚动，这限定了 e2e 能真实驱动的范围：触控来源的 `Input.synthesizeScrollGesture` 与手工构造的 `Input.dispatchTouchEvent` 序列都能交付 DOM 事件，却从不移动滚动容器（无头模式与 Xvfb 下的有头模式皆然）；`default` 手势来源合成的是滚轮事件；合成器滚动条则完全无视合成的鼠标输入，且只有移除 `--hide-scrollbars` 后才能看到滚动条槽。键盘是唯一可用的非滚轮原语，因此由它承担真实输入流水线的证明；快滑场景则把触控的特征（组件从未写入过的逐帧衰减位移）直接回放进滚动容器。
+
+## 曾考虑的替代方案
+
+**保留仅认滚轮的模型。** 否决：它本身就是缺陷所在。触控、滚动条与键盘读者无法从流式尾部夺走所有权，而每种新支持的设备都需要单独开一个特例。
+
+**逐一枚举输入设备。** 在滚轮 epoch 旁边加挂 `touchstart`/`pointerdown`/`keydown` 监听器是最显而易见的扩展。否决：拖动原生滚动条在其滚动事件到达之前不暴露任何可供锁存的输入事件；设备清单会随浏览器新增输入来源而逐渐腐化；而且每个监听器都需要自己的合成器交付宽限窗口——这正是 sticky-composer 笔记当初就拒绝构建的那个输入状态机。
+
+**用启发式吸收收缩与重新增长被合并的钳制。** 针对底部失配的宽限窗口，或推迟到 rAF 的复查，本可让这种竞态下的钳制不被判读为读者。否决：流式输出以分片节奏（24 ms）改写底部，而帧间隔约 16 ms，因此任何宽限窗口要么会在流式输出期间吞掉真实的触控输入（重新打开本次变更所修复的缺陷），要么短到盖不住它想针对的竞态。转而接受这一误归因，它是可恢复的。
+
+**在 e2e 中驱动真实的触控与滚动条设备。** 否决来自环境，而非偏好取舍：每条合成路径（CDP 触控手势、触控事件序列、经典滚动条上的合成鼠标、Xvfb 下的有头模式）都逐一试过，均无法滚动；细节见上文「测试」一节。
+
+## 后果
+
+每种读者输入现在都以同一方式拥有贴底跟随，而代码更少：滚轮监听器、它的 epoch 计数器以及输入前基线簿记均已移除，归因搭载在组件本就维护的状态之上。sticky-composer 笔记中的布局、滚轮链式处理与前置锚定决策原样保留，仍为权威；其窄范围的输入来源规则由本笔记取代。代价就是上文的契约变更：一次收缩与重新增长被合并的非 React 钳制现在会暂停跟随，直到读者回到底部或按下「回到底部」；以此换来流式输出期间触控、滚动条与键盘的正确性。e2e 车道获得的非滚轮覆盖仅限其浏览器能够合成的范围；若手势合成在未来某个 Chromium 版本中开始可用，可以在不改变所断言契约的前提下，把快滑模拟替换为真实的触控划动。
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
index 638e91a016..5f9a220dc5 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.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 .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
-2026-07-24-web-gui-browser-e2e-lane.md: f8519a9622d2f7216226a695db95dbebdbf24ea1
-2026-07-24-web-gui-browser-e2e-lane.zh.md: 294f3e840e0242d9a0d9c53ac510d44d3b0d100f
+2026-07-24-web-gui-browser-e2e-lane.md: 095ad9055c8462ecec67609ed9af55df2a2d7adb
+2026-07-24-web-gui-browser-e2e-lane.zh.md: eb20ee378eb5154bafcb7a448202c66dacda9199
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
index f8519a9622..095ad9055c 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
@@ -42,7 +42,7 @@ The typecheck plane split is structural: the host scaffold, its support module,
 
 ### Coverage contract
 
-The lane covers three behavior families. Live-turn scenarios pin ordinary tool execution, cancellation, non-retryable failure, transient retry, resident questions, and mid-turn steering; synchronization uses durable events, `whenIdle()`, or an explicit replay marker rather than delays. Cold-history scenarios seed through the real persistence API and cover history rendering, sidebar search, trajectory and waterfall views, and tool details without model calls. Browser-lifecycle scenarios cover first-send workspace materialization, reload recovery, layout reset, theme and locale preferences, and workspace create/rename/view operations. Each family asserts the browser surface and the authoritative host state; a stray model call or under-consumed fixture fails teardown. The required lane additionally carries an 88-turn synthetic Chat scroll contract mixing wrapped Markdown, fenced code, and paired bash calls/results. Real wheel, composer, tool, tab, session, and viewport interactions assert a named settled row's top relative to the transcript scrollport and distance from the true bottom across concurrent history prepend plus paced streaming, pinned/away streaming, tool-disclosure offscreen cycles, expanded-history view/session remount, width reflow, immediate pinned remount, composer resize, and textarea wheel chaining; it deliberately pins neither DOM cardinality nor absolute `scrollTop`, so the same contract can qualify a virtualized implementation. A separate interaction contract over the same fixture pins heterogeneous-row order, independent adjacent tool disclosure, exact user-message clipboard content, a turn-bounded message fork, source/child isolation, and a real follow-up turn in the child; wheel input only navigates to semantic targets and carries no geometry expectation. A short live-history contract starts from a blank workspace and drives consecutive composer turns, including real bash call/result rounds and a paced long final response, pinning one session identity, exact per-turn event ownership, browser echo uniqueness, and composer recovery without timing thresholds.
+The lane covers three behavior families. Live-turn scenarios pin ordinary tool execution, cancellation, non-retryable failure, transient retry, resident questions, and mid-turn steering; synchronization uses durable events, `whenIdle()`, or an explicit replay marker rather than delays. Cold-history scenarios seed through the real persistence API and cover history rendering, sidebar search, trajectory and waterfall views, and tool details without model calls. Browser-lifecycle scenarios cover first-send workspace materialization, reload recovery, layout reset, theme and locale preferences, and workspace create/rename/view operations. Each family asserts the browser surface and the authoritative host state; a stray model call or under-consumed fixture fails teardown. The required lane additionally carries an 88-turn synthetic Chat scroll contract mixing wrapped Markdown, fenced code, and paired bash calls/results. Real wheel, composer, tool, tab, session, and viewport interactions assert a named settled row's top relative to the transcript scrollport and distance from the true bottom across concurrent history prepend plus paced streaming, pinned/away streaming, tool-disclosure offscreen cycles, expanded-history view/session remount, width reflow, immediate pinned remount, composer resize, and textarea wheel chaining; real keyboard paging and a touch-style fling emulation additionally pin wheel-free bottom-follow ownership ([reader-scroll-attribution note](../bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md)); it deliberately pins neither DOM cardinality nor absolute `scrollTop`, so the same contract can qualify a virtualized implementation. A separate interaction contract over the same fixture pins heterogeneous-row order, independent adjacent tool disclosure, exact user-message clipboard content, a turn-bounded message fork, source/child isolation, and a real follow-up turn in the child; wheel input only navigates to semantic targets and carries no geometry expectation. A short live-history contract starts from a blank workspace and drives consecutive composer turns, including real bash call/result rounds and a paced long final response, pinning one session identity, exact per-turn event ownership, browser echo uniqueness, and composer recovery without timing thresholds.
 
 ### CI stance
 
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
index 294f3e840e..eb20ee378e 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
@@ -42,7 +42,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 ### 覆盖契约
 
-该车道覆盖三类行为。实时轮次场景钉住普通工具执行、取消、不可重试失败、瞬态重试、常驻提问与轮次中途 steering；同步依赖持久事件、`whenIdle()` 或显式回放标记，而不使用延时。冷历史场景通过真实持久化 API 播种，在不调用模型的情况下覆盖历史渲染、侧栏搜索、Trajectory 与 Waterfall 视图及工具详情。浏览器生命周期场景覆盖首次发送时物化工作区、重新加载恢复、布局重置、主题与语言偏好，以及工作区的创建、重命名和视图操作。每类场景都断言浏览器表面和权威的 host 状态；离群的模型调用或未耗尽的 fixture 会使拆卸失败。必需车道还包含一份合成的 88 轮 Chat 滚动契约，其中混合了换行 Markdown、围栏代码以及成对的 bash 调用/结果。真实 wheel、输入框、工具、tab、会话与 viewport 交互会在并发历史前插加带节奏流式输出、贴底/离底流式输出、工具 disclosure 离屏循环、扩展历史后的视图/会话重新挂载、宽度重排、贴底后立即重新挂载、输入框尺寸变化以及 textarea wheel 链场景中，断言一个具名已结算行相对 transcript scrollport 的顶部位置和到真实底部的距离；它刻意不钉 DOM 基数或绝对 `scrollTop`，因此同一契约可以验收虚拟化实现。另一份基于同一 fixture 的交互契约钉住异构行顺序、相邻工具 disclosure 的独立状态、用户消息剪贴板内容的精确值、以轮次为边界的消息 fork、源会话/子会话隔离，以及子会话中的一次真实追问轮次；wheel 输入只用于导航到语义目标，不承载几何预期。一份简短的实时历史契约从空白工作区开始，连续驱动输入框轮次，其中包括真实的 bash 调用/结果轮次和一段带节奏的长篇最终响应；它钉住单一会话身份、每轮事件的精确归属、浏览器回显唯一性与输入框恢复，不设置时间阈值。
+该车道覆盖三类行为。实时轮次场景钉住普通工具执行、取消、不可重试失败、瞬态重试、常驻提问与轮次中途 steering；同步依赖持久事件、`whenIdle()` 或显式回放标记，而不使用延时。冷历史场景通过真实持久化 API 播种，在不调用模型的情况下覆盖历史渲染、侧栏搜索、Trajectory 与 Waterfall 视图及工具详情。浏览器生命周期场景覆盖首次发送时物化工作区、重新加载恢复、布局重置、主题与语言偏好，以及工作区的创建、重命名和视图操作。每类场景都断言浏览器表面和权威的 host 状态；离群的模型调用或未耗尽的 fixture 会使拆卸失败。必需车道还包含一份合成的 88 轮 Chat 滚动契约，其中混合了换行 Markdown、围栏代码以及成对的 bash 调用/结果。真实 wheel、输入框、工具、tab、会话与 viewport 交互会在并发历史前插加带节奏流式输出、贴底/离底流式输出、工具 disclosure 离屏循环、扩展历史后的视图/会话重新挂载、宽度重排、贴底后立即重新挂载、输入框尺寸变化以及 textarea wheel 链场景中，断言一个具名已结算行相对 transcript scrollport 的顶部位置和到真实底部的距离；真实键盘翻页与触摸式惯性滑动模拟额外钉住不依赖 wheel 的贴底跟随所有权（[读者滚动归因笔记](../bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md)）；它刻意不钉 DOM 基数或绝对 `scrollTop`，因此同一契约可以验收虚拟化实现。另一份基于同一 fixture 的交互契约钉住异构行顺序、相邻工具 disclosure 的独立状态、用户消息剪贴板内容的精确值、以轮次为边界的消息 fork、源会话/子会话隔离，以及子会话中的一次真实追问轮次；wheel 输入只用于导航到语义目标，不承载几何预期。一份简短的实时历史契约从空白工作区开始，连续驱动输入框轮次，其中包括真实的 bash 调用/结果轮次和一段带节奏的长篇最终响应；它钉住单一会话身份、每轮事件的精确归属、浏览器回显唯一性与输入框恢复，不设置时间阈值。
 
 ### CI 立场
 
diff --git a/apps/web/tests/chat-scroll-contract.e2e.ts b/apps/web/tests/chat-scroll-contract.e2e.ts
index 6509055036..0c75afb4e7 100644
--- a/apps/web/tests/chat-scroll-contract.e2e.ts
+++ b/apps/web/tests/chat-scroll-contract.e2e.ts
@@ -40,6 +40,11 @@ const LIVE_TOOL_FIRST = 'CHAT_SCROLL_TOOL_STREAM_FIRST'
 const LIVE_TOOL_DONE = 'CHAT_SCROLL_TOOL_STREAM_DONE'
 const TOOL_READY_FILE = '.chat-scroll-tool-ready'
 const TOOL_RELEASE_FILE = '.chat-scroll-tool-release'
+const INPUTS_SESSION_ID = 'chat-scroll-inputs-e2e'
+const FLING_SESSION_ID = 'chat-scroll-fling-e2e'
+const LIVE_FLING_PROMPT = 'CHAT_SCROLL_FLING_USER Keep streaming while I fling back through older output.'
+const LIVE_FLING_FIRST = 'CHAT_SCROLL_FLING_STREAM_FIRST'
+const LIVE_FLING_DONE = 'CHAT_SCROLL_FLING_STREAM_DONE'
 
 const HISTORY_FIXTURE = createChatScrollFixture({
   markerPrefix: 'HISTORY',
@@ -58,6 +63,10 @@ const RESTORE_FIXTURE_B = createChatScrollFixture({
   title: 'CHAT_SCROLL_RESTORE_B comparison session',
   turns: 32,
 })
+const INPUTS_FIXTURE = createChatScrollFixture({
+  markerPrefix: 'INPUTS',
+  title: 'CHAT_SCROLL_INPUTS non-wheel reader input session',
+})
 
 interface ScrollGeometry {
   readonly distanceFromBottom: number
@@ -273,6 +282,34 @@ async function wheelTranscript(page: Page, deltaY: number): Promise<void> {
   await nextPaint(page)
 }
 
+/**
+ * Touch-style momentum fling over the transcript. Headless Chromium in the
+ * test lane cannot synthesize device scrolling (Input.synthesizeScrollGesture
+ * and Input.dispatchTouchEvent both deliver DOM events without moving any
+ * scroller, and compositor scrollbars ignore synthetic mouse input), so the
+ * fling replays the signature a real pan leaves on the scrollport: per-frame
+ * decaying displacements the component never authored, carrying no wheel
+ * events. Wheel-sign semantics: positive deltaY reads downward.
+ */
+async function flingTranscript(page: Page, deltaY: number): Promise<void> {
+  await page.locator('[data-conversation-scroll]').evaluate(async (host, delta) => {
+    const direction = Math.sign(delta)
+    let remaining = Math.abs(delta)
+    // Fast launch decaying toward a floor speed, like a released finger. The
+    // floor stays above the follow threshold so contended frames (streaming
+    // writes racing the fling) still deviate far enough to read as input.
+    let velocity = Math.max(120, remaining / 8)
+    while (remaining > 0) {
+      const step = Math.min(velocity, remaining)
+      host.scrollTop += direction * step
+      remaining -= step
+      velocity = Math.max(48, velocity * 0.9)
+      await new Promise<void>(resolve => requestAnimationFrame(() => { resolve() }))
+    }
+  }, deltaY)
+  await nextPaint(page)
+}
+
 async function wheelToHistoryStart(page: Page): Promise<void> {
   for (let attempt = 0; attempt < 12; attempt += 1) {
     if ((await scrollGeometry(page)).scrollTop <= 1) break
@@ -683,4 +720,112 @@ describe('web e2e: long Chat scroll contract', () => {
       assertClean(world)
     })
   }, 180_000)
+
+  // Keyboard is the only non-wheel device this lane's Chromium can drive for
+  // real (see flingTranscript for the probe results on touch and scrollbars),
+  // so it stands in for the whole hardware input pipeline here.
+  it.skipIf(MODE === 'record')('keyboard paging owns bottom-follow without wheel input', async () => {
+    await withScrollWorld({
+      failureShot: 'web-e2e-chat-scroll-keyboard',
+      seeds: [{ fixture: INPUTS_FIXTURE, id: INPUTS_SESSION_ID }],
+    }, async (world) => {
+      await openSeed(
+        world.page,
+        INPUTS_FIXTURE,
+        INPUTS_FIXTURE.markers.assistant(INPUTS_FIXTURE.turns),
+      )
+      await expectBottom(world.page)
+      const backToBottom = world.page.getByRole('button', { name: 'Back to bottom', exact: true })
+
+      // Focus rides the last seeded tool row (a tabbable button whose keydown
+      // handler passes scrolling keys through). End first normalizes the
+      // focus-driven scrollIntoView back to the floor.
+      const lastToolRow = world.page.locator(
+        `[data-chat-call-id="chat-scroll-${String(INPUTS_FIXTURE.turns).padStart(3, '0')}-1"] [data-sample="bash"]`,
+      )
+      await lastToolRow.focus()
+      await world.page.keyboard.press('End')
+      await expectBottom(world.page)
+      await expect.poll(() => backToBottom.count(), { timeout: 10_000 }).toBe(0)
+      for (let press = 0; press < 3; press += 1) {
+        await world.page.keyboard.press('PageUp')
+        await nextPaint(world.page)
+      }
+      await backToBottom.waitFor({ timeout: 10_000 })
+      await expect.poll(async () => (await scrollGeometry(world.page)).distanceFromBottom, { timeout: 10_000 })
+        .toBeGreaterThan(100)
+      await world.page.keyboard.press('End')
+      await expectBottom(world.page)
+      await expect.poll(() => backToBottom.count(), { timeout: 10_000 }).toBe(0)
+      assertClean(world)
+    })
+  }, 180_000)
+
+  it.skipIf(MODE === 'record')('touch-style fling scrolling owns streaming bottom-follow without wheel input', async () => {
+    await withScrollWorld({
+      failureShot: 'web-e2e-chat-scroll-fling-stream',
+      replay: [
+        replayEntry(toolStream()),
+        replayEntry(textStream(LIVE_FLING_FIRST, LIVE_FLING_DONE, 240)),
+      ],
+      seeds: [{ fixture: INPUTS_FIXTURE, id: FLING_SESSION_ID }],
+    }, async (world) => {
+      const readyPath = join(world.scaffold.workspaceCwd, TOOL_READY_FILE)
+      const releasePath = join(world.scaffold.workspaceCwd, TOOL_RELEASE_FILE)
+      await openSeed(world.page, INPUTS_FIXTURE, INPUTS_FIXTURE.markers.assistant(INPUTS_FIXTURE.turns))
+      const backToBottom = world.page.getByRole('button', { name: 'Back to bottom', exact: true })
+      const settled = world.scaffold.whenTurnSettled(60_000)
+      let released = false
+      try {
+        const composer = world.page.locator('textarea:enabled').last()
+        await composer.fill(LIVE_FLING_PROMPT)
+        await world.page.getByRole('button', { name: 'Send message', exact: true }).click()
+        await expect.poll(() => fileExists(readyPath), { timeout: 15_000 }).toBe(true)
+        await expectBottom(world.page)
+
+        // Fling away while the turn is mid-flight: the scroll burst alone must
+        // release bottom ownership, exactly like a wheel scroll would, even
+        // while streaming keeps re-asserting the floor between frames.
+        await flingTranscript(world.page, -900)
+        await backToBottom.waitFor({ timeout: 10_000 })
+        const awayAnchor = await visibleFlowAnchor(world.page)
+        const chunksBeforeRelease = world.events.filter(event => event.type === 'assistant/chunk').length
+        await writeFile(releasePath, 'release\n')
+        released = true
+        await expect.poll(
+          () => world.events.some(event => event.type === 'tool/result'),
+          { timeout: 15_000 },
+        ).toBe(true)
+        await expect.poll(
+          () => world.events.filter(event => event.type === 'assistant/chunk').length,
+          { timeout: 15_000 },
+        ).toBeGreaterThan(chunksBeforeRelease + 5)
+        await expectSameFlowTop(world.page, awayAnchor)
+
+        // Fling back to the floor: re-pin must come from the reader's scroll
+        // itself, and follow must then own the still-streaming tail. The
+        // retry loop chases the floor that streaming keeps pushing down.
+        for (let attempt = 0; attempt < 8; attempt += 1) {
+          if ((await scrollGeometry(world.page)).distanceFromBottom <= 1) break
+          await flingTranscript(world.page, 1_600)
+        }
+        await expectBottom(world.page)
+        await expect.poll(() => backToBottom.count(), { timeout: 10_000 }).toBe(0)
+        const chunksAtRepin = world.events.filter(event => event.type === 'assistant/chunk').length
+        await expect.poll(
+          () => world.events.filter(event => event.type === 'assistant/chunk').length,
+          { timeout: 15_000 },
+        ).toBeGreaterThan(chunksAtRepin + 5)
+        await expectBottom(world.page)
+      } finally {
+        if (!released) await writeFile(releasePath, 'release\n').catch(() => {})
+      }
+
+      await settled
+      await expect.poll(() => world.page.locator('[data-streaming="true"]').count(), { timeout: 15_000 }).toBe(0)
+      await world.page.getByText(LIVE_FLING_DONE, { exact: false }).last().waitFor({ timeout: 15_000 })
+      await expectBottom(world.page)
+      assertClean(world)
+    })
+  }, 180_000)
 })
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index 6058efca98..09433e4085 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -372,9 +372,6 @@ export function ChatView({
   const [atBottom, setAtBottom] = useState(true)
   /** Last position delivered or written on the main thread. */
   const observedTopRef = useRef(0)
-  /** Pre-input position for the current wheel gesture. */
-  const wheelStartRef = useRef<number | null>(null)
-  const wheelEpochRef = useRef(0)
   /** Paging anchor: semantic row/position at click, updated by reader scrolls
    * while the request is pending and restored after the prepend lands. */
   const anchorRef = useRef<PagingAnchor | null>(null)
@@ -394,8 +391,6 @@ export function ChatView({
   const followSig = `${openState}:${firstSeq}:${lastKey}:${nodes.length}:${running ? 1 : 0}:${runningCalls.length}:${lastSteeringId ?? ''}`
 
   const toBottom = (el: HTMLElement): void => {
-    wheelStartRef.current = null
-    wheelEpochRef.current += 1
     anchorRef.current = null
     el.scrollTop = el.scrollHeight
     observedTopRef.current = el.scrollTop
@@ -472,17 +467,19 @@ export function ChatView({
     /* v8 ignore next -- ref-null guard: the handler only fires while mounted. */
     if (local === null) return
     const el = scrollerOf(local)
-    // Only wheel input may make raw scroll geometry change follow ownership.
-    // Browser clamping and delayed programmatic scroll events otherwise have
-    // the same event shape and must preserve the current ownership state.
+    // Only reader input may make raw scroll geometry change follow ownership:
+    // a delivered position that deviates from the observed-top ledger (every
+    // programmatic write records itself there synchronously). This covers
+    // wheel, touch, scrollbar, and keyboard alike without naming devices.
+    // Browser shrink-clamps land exactly on the floor min and delayed
+    // programmatic deliveries land on the ledger itself, so both preserve
+    // the current ownership state.
     const floor = Math.max(0, el.scrollHeight - el.clientHeight)
-    const wheelStart = wheelStartRef.current
-    const movedByWheel = wheelStart !== null
-      && Math.abs(el.scrollTop - Math.min(wheelStart, floor)) > 0.5
-    const isAtBottom = movedByWheel
+    const movedByReader = Math.abs(el.scrollTop - Math.min(observedTopRef.current, floor)) > 0.5
+    const isAtBottom = movedByReader
       ? floor - el.scrollTop <= FOLLOW_THRESHOLD + 1
       : atBottomRef.current
-    if (!movedByWheel && isAtBottom) {
+    if (!movedByReader && isAtBottom) {
       toBottom(el)
       return
     }
@@ -501,34 +498,18 @@ export function ChatView({
     observedTopRef.current = el.scrollTop
   }
 
-  // Bind scroll and the wheel provenance needed to distinguish reader input
-  // from layout-driven scrolls on the resolved scrollport once per mount.
+  // Bind the scroll listener on the resolved scrollport once per mount;
+  // reader-input attribution rides the observed-top ledger, not per-device
+  // input listeners.
   useEffect(() => {
     const local = listRef.current
     /* v8 ignore next -- ref-null guard: effect runs after the list node commits. */
     if (local === null) return
     const el = scrollerOf(local)
     const onScroll = (): void => { onScrollRef.current() }
-    const onWheel = (event: WheelEvent): void => {
-      if (event.ctrlKey || event.deltaY === 0) return
-      const startTop = observedTopRef.current
-      const floor = Math.max(0, el.scrollHeight - el.clientHeight)
-      const canMove = event.deltaY < 0 ? startTop > 1 : startTop < floor - 1
-      if (!canMove) return
-      wheelStartRef.current = startTop
-      const epoch = ++wheelEpochRef.current
-      requestAnimationFrame(() => {
-        requestAnimationFrame(() => {
-          if (wheelEpochRef.current === epoch) wheelStartRef.current = null
-        })
-      })
-    }
     el.addEventListener('scroll', onScroll, { passive: true })
-    el.addEventListener('wheel', onWheel, { capture: true, passive: true })
     return () => {
-      wheelStartRef.current = null
       el.removeEventListener('scroll', onScroll)
-      el.removeEventListener('wheel', onWheel, true)
     }
   }, [])
 
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index 2369e8f1d6..ae0340f8a4 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -158,9 +158,9 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
   return { set, ChatView, props, openDetails, openFile, loadOlder, inspectCall, chatScroll, forkAt, setSelection }
 }
 
-/** Simulate reader input before the browser delivers the host scroll event. */
+/** Simulate reader input (any device): a delivered position that deviates
+ * from the observed-top ledger of programmatic writes. */
 function readerScroll(element: HTMLElement, top: number): void {
-  fireEvent.wheel(element, { deltaY: top < element.scrollTop ? -120 : 120 })
   element.scrollTop = top
   fireEvent.scroll(element)
 }
@@ -939,7 +939,7 @@ describe('ChatView', () => {
     expect(view.queryByLabelText('回到底部')).toBeNull()
   })
 
-  it('keeps following when a delayed clamp scroll arrives after layout regrows', () => {
+  it('keeps following when a stream-finalization shrink clamp delivers its scroll', () => {
     const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] })
     const view = render(<h.ChatView {...h.props} />)
     const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
@@ -947,12 +947,12 @@ describe('ChatView', () => {
     scroller.scrollTop = 700
     fireEvent.scroll(scroller)
 
-    // The wheel cannot move farther down. A stream-finalization shrink clamps
-    // the old position, then reflow grows the layout before scroll delivery.
-    fireEvent.wheel(scroller, { deltaY: 120 })
-    metrics.setLayout(1_040, 500)
+    // Stream finalization shrinks the column: the browser clamps the pinned
+    // position onto the new floor and delivers a scroll event. The clamp
+    // lands exactly on the ledger's floor min, so it is not reader input.
+    metrics.setLayout(800, 700)
     fireEvent.scroll(scroller)
-    expect(scroller.scrollTop).toBe(740)
+    expect(scroller.scrollTop).toBe(500)
     expect(view.queryByLabelText('回到底部')).toBeNull()
     expect(h.chatScroll.read()).toBeNull()
 
@@ -961,7 +961,7 @@ describe('ChatView', () => {
     expect(scroller.scrollTop).toBe(900)
   })
 
-  it('uses the last delivered top when compositor scrolling precedes passive wheel delivery', () => {
+  it('uses the last delivered top when compositor scrolling precedes scroll delivery', () => {
     const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] })
     const view = render(<h.ChatView {...h.props} />)
     const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
@@ -969,8 +969,10 @@ describe('ChatView', () => {
     scroller.scrollTop = 700
     fireEvent.scroll(scroller)
 
+    // Chromium advances compositor geometry before delivering the event:
+    // attribution must compare against the observed-top ledger, never a
+    // baseline sampled from already-moved raw geometry.
     scroller.scrollTop = 500
-    fireEvent.wheel(scroller, { deltaY: -200 })
     fireEvent.scroll(scroller)
     expect(view.getByLabelText('回到底部')).toBeTruthy()
   })

From 96795972040151c756323d8bf05504d387aadb8a Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 13:49:47 +0800
Subject: [PATCH 097/516] feat(ui-models): tag the provider rows this
 deployment declared
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A row's stored profile could not tell a hand-declared gateway from a
shipped provider whose models someone narrowed — both look identical from
outside the adapter — so the Models page had no way to mark the routes a
deployment added itself.

The directory entry now carries `declared`, answered by the owning adapter
against its own installed catalog, and the page renders a Custom tag from
it. Absence stays "this adapter draws no such distinction" rather than
"shipped", so a route no adapter claims is labelled neither way.

Also records the default-route work's Agent Note and the e2e evidence for
all three changes: the composer switch writing the section, and the Models
page declaring a route with its own reasoning effort.
---
 ...default-model-follows-the-picker.i18n.yaml |   6 +
 ...-08-07-default-model-follows-the-picker.md |  33 +++++
 ...-07-default-model-follows-the-picker.zh.md |  33 +++++
 apps/web/tests/default-model.e2e.ts           | 115 ++++++++++++++++++
 apps/web/tests/models-settings.e2e.ts         |  45 ++++++-
 .../models-settings/declared.expected.md      |  30 +++++
 apps/web/tsconfig.json                        |   1 +
 docs/config-catalog.md                        |  22 +++-
 docs/core-data-structures/core.i18n.yaml      |   4 +-
 docs/core-data-structures/core.md             |   9 ++
 docs/core-data-structures/core.zh.md          |   9 ++
 .../client/connection/src/client/fixture.ts   |   7 +-
 packages/client/ui-models/README.i18n.yaml    |   4 +-
 packages/client/ui-models/README.md           |   4 +-
 packages/client/ui-models/README.zh.md        |   4 +-
 .../src/client/ModelsSection.module.css       |  14 +++
 .../ui-models/src/client/ModelsSection.tsx    |   6 +
 .../client/ui-models/src/client/locales.ts    |   2 +
 .../ui-models/tests/provider-form.spec.tsx    |  52 +++++++-
 .../cordis/tool-cordis/src/api-catalog.ts     |   2 +-
 packages/host/apiproxy/README.i18n.yaml       |   4 +-
 packages/host/apiproxy/README.md              |  12 +-
 packages/host/apiproxy/README.zh.md           |  12 +-
 packages/host/apiproxy/src/api-proxy.ts       |   9 +-
 packages/host/apiproxy/src/api/llm.schema.ts  |   1 +
 packages/host/apiproxy/src/api/llm.ts         |   6 +
 packages/host/apiproxy/src/index.ts           |  37 +++---
 packages/llm/llm-pi-ai/README.i18n.yaml       |   4 +-
 packages/llm/llm-pi-ai/README.md              |   2 +-
 packages/llm/llm-pi-ai/README.zh.md           |   2 +-
 packages/llm/llm-pi-ai/src/index.ts           |  14 ++-
 packages/llm/llm-pi-ai/tests/catalog.spec.ts  |  11 +-
 .../llm-pi-ai/tests/dynamic-config.spec.ts    |   1 +
 packages/llm/llm/README.i18n.yaml             |   4 +-
 packages/llm/llm/README.md                    |   2 +-
 packages/llm/llm/README.zh.md                 |   2 +-
 packages/llm/llm/src/types.ts                 |   9 ++
 tsconfig.host.json                            |   1 +
 38 files changed, 479 insertions(+), 56 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
 create mode 100644 apps/web/tests/default-model.e2e.ts
 create mode 100644 apps/web/tests/snapshots/models-settings/declared.expected.md

diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
new file mode 100644
index 0000000000..ba3917c8b7
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.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-08-07-default-model-follows-the-picker.md
+2026-08-07-default-model-follows-the-picker.md: 5174b224a17728b65f7fd69d7f72388d50e8e825
+2026-08-07-default-model-follows-the-picker.zh.md: 6ead561b928572a479f2c7b19e409b3845363ed6
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
new file mode 100644
index 0000000000..5174b224a1
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
@@ -0,0 +1,33 @@
+# Agent Note: the default model follows the picker
+
+Status: implemented
+
+English | [中文](2026-08-07-default-model-follows-the-picker.zh.md)
+
+## Problem
+
+The route a new session started from was frozen into the gateway's composition entry (`api-gateway` in the web-app bundle patch). Switching models in a conversation reached that conversation only: the next session went back to the shipped default, and the only way to change it was to hand-edit a `cordis.yml` row and restart. There was no user-settings tier between the composition and the per-session choice.
+
+## Decision
+
+`ApiProxyService` registers its `{provider, model, reasoningEffort?}` slice as the `api-gateway` settings section: the composition entry is the `base` layer and `settings.yaml` layers the user's choice over it. `workspaceRoot` stays outside the section — a launcher fact, not a preference. The section schema is picked out of `static Config` rather than restated, because the configuration-catalog generator reads that literal statically and a spread breaks it.
+
+`session.selectModel` records an accepted switch as the new default. There is no separate gesture: switching models in the composer IS how the default is chosen. The write is `replace`, not `update` — switching to a model with no reasoning effort has to clear a stored one, and a merged patch would strand it for the next session to fail on. A storage failure is logged without undoing the switch, which already applies to its own session, and a deployment with no settings provider keeps the entry with the switch staying process-local.
+
+`ApiProxyDefaults` carries `defaultTarget()` and `persistDefaultTarget()` closures instead of flat `provider`/`model` fields, so `createApiProxy` needs no knowledge of the settings seam.
+
+`targetFor` resolves its tiers on **every** read rather than seeding a ref once: an explicit selection in this process, else the session's own latest logged `request/header`, else the live default. Both directions depend on the re-read. A session that has run a turn derives from its log forever after, so changing the default never retargets it. A session still blank starts from a default saved after it was created — which matters because New Session reuses a blank session rather than minting another, so a creation-time seed would show the superseded model in exactly the flow the feature exists for.
+
+The stored route is not validated against the registry. A default naming a route the Models page has since removed still reaches `session.models` as `current`, matching no advertised group — which is what makes the composer seat's existing fallback prompt for a selection instead of naming a model the deployment cannot reach.
+
+## Consequences
+
+`ApiProxyDefaults` changed shape, updating ~40 test construction sites. `host.describe` now reports the live default rather than a captured one, which is what it always meant. `settings.yaml` gains an `api-gateway:` section the moment a user switches models; the `api-gateway` namespace is deliberately NOT added to the gateway's exposed-namespace allowlist, so the Settings page neither reads nor writes it — the model picker is its editor.
+
+## Alternatives considered
+
+- **Falling back to the composition entry when the stored route is unregistered.** Rejected: the composer would then name the shipped DeepSeek model instead of prompting, which is both a silent switch to a provider the user did not pick and the opposite of the requested behavior.
+- **Validating and clearing a stale default.** Rejected: catalog membership is advisory by design (`buildModelCatalog` documents it), so an adapter may serve a model its own catalog stopped advertising; self-healing would break that deliberate case.
+- **A `settings.update` merge patch.** Rejected: it cannot clear `reasoningEffort`, so a switch from a reasoning model to a plain one leaves an effort the next session fails on.
+- **Persisting only from blank sessions.** Rejected: the most informative switch is the one made mid-conversation after seeing a model underperform, and that one would never be saved.
+- **A separate "set as default" affordance.** Rejected for now: it adds a second gesture for what every comparable product infers from the switch itself. The cost is that a temporary switch in an old session also moves the default.
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
new file mode 100644
index 0000000000..6ead561b92
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 默认模型跟随选择器
+
+Status: implemented
+
+[English](2026-08-07-default-model-follows-the-picker.md) | 中文
+
+## 问题
+
+新会话的起始路由被冻结在网关的组合条目里（web-app bundle patch 中的 `api-gateway` 行）。在一段对话里切换模型只影响这段对话：下一个会话又回到出厂默认，而要改这个默认值，唯一的办法是手工编辑一条 `cordis.yml` 行并重启。组合层与每会话选择之间没有用户设置这一层。
+
+## 决定
+
+`ApiProxyService` 把自己的 `{provider, model, reasoningEffort?}` 切片注册为 `api-gateway` 设置段：组合条目是 `base` 层，`settings.yaml` 把用户的选择叠加其上。`workspaceRoot` 留在段外——它是启动器事实，不是偏好。段 schema 从 `static Config` 里挑出来而不是重述一遍，因为配置目录生成器是静态读取那个字面量的，展开语法会让它失败。
+
+`session.selectModel` 把被接受的切换记录为新的默认值。没有另一个单独的手势：在输入框切模型**就是**选定默认值的方式。写入用 `replace` 而非 `update`——切到一个不支持推理的模型必须清掉已存的等级，而合并补丁会把它滞留下来，让下一个会话在它上面失败。存储失败只记日志，不撤销这次切换（它对自己所在的会话已经生效）；没有设置提供方的部署保留组合条目，切换只停留在进程内。
+
+`ApiProxyDefaults` 改为携带 `defaultTarget()` 与 `persistDefaultTarget()` 两个闭包，而不是扁平的 `provider`／`model` 字段，这样 `createApiProxy` 不需要知道设置这条缝的存在。
+
+`targetFor` 在**每一次**读取时解析各级，而不是只在创建时种一次 ref：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是活的默认值。两个方向都依赖这次重新读取。已经跑过一轮的会话此后永远从自己的日志推导，改默认值不会重定向它；而仍然空白的会话会用上它创建之后才保存的默认值——这一点很关键，因为新建会话是复用空白会话而不是再开一个，创建时种下的值恰好会在这个功能存在的意义所在的流程里显示已被取代的模型。
+
+存下来的路由不做注册表校验。默认值指向一条模型页已经删除的路由时，它照样作为 `current` 送到 `session.models`，匹配不到任何已公布的分组——而这正是让输入框选择器已有的回退提示重新选择、而不是显示一个部署根本够不着的模型的原因。
+
+## 影响
+
+`ApiProxyDefaults` 形状变了，约 40 处测试构造点随之更新。`host.describe` 现在报告的是活的默认值而非捕获的快照，这本就是它一直想表达的含义。用户一旦切换模型，`settings.yaml` 就会多出一个 `api-gateway:` 段；`api-gateway` 这个 namespace 刻意**没有**加进网关的暴露名单，因此设置页既不读也不写它——模型选择器就是它的编辑器。
+
+## 考虑过的替代方案
+
+- **存下来的路由未注册时回落到组合条目。** 否决：那样输入框会显示出厂的 DeepSeek 模型而不是提示选择，既是静默切到用户没选的提供方，也与要求的行为正好相反。
+- **校验并清空失效的默认值。** 否决：目录成员关系按设计是咨询性的（`buildModelCatalog` 有注释说明），适配器可以服务一个自己目录已不再公布的模型；自动修复会破坏这个刻意保留的情形。
+- **用 `settings.update` 合并补丁。** 否决：它清不掉 `reasoningEffort`，于是从推理模型切到普通模型会留下一个等级，让下一个会话在它上面失败。
+- **只在空白会话里持久化。** 否决：最有信息量的切换恰恰是对话到一半发现模型不行时做的那一次，而它永远存不下来。
+- **单独做一个「设为默认」的入口。** 目前否决：同类产品都从切换本身推断的事情，它却要多一个手势。代价是在老会话里的临时切换也会移动默认值。
diff --git a/apps/web/tests/default-model.e2e.ts b/apps/web/tests/default-model.e2e.ts
new file mode 100644
index 0000000000..0ba81e3ca0
--- /dev/null
+++ b/apps/web/tests/default-model.e2e.ts
@@ -0,0 +1,115 @@
+// Web e2e scenario: switching models in the composer is how this deployment's
+// default is chosen. The gesture writes the `api-gateway` settings section, a
+// session created afterwards starts from it, and a session that already logged
+// a route keeps deriving from its own log — the tier order the gateway
+// resolves on every read.
+// Zero model calls: the switch is settings/llm-domain traffic only, so there
+// is no fixture and a stray stream would fail loud on the open seam. A second
+// route is declared host-side (not through the UI, which has its own
+// scenario) purely so the picker has somewhere to switch to: the keyless
+// replay catalog publishes a single model.
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { launchWebScaffold, watchConsole, type WebScaffold } from './scaffold.ts'
+import { ZH_BROWSER_LOCALE, connectFreshWorkspaceZh, saveFailureShot } from './support.ts'
+
+/** The route declared for this scenario, and the model the switch lands on. */
+const ROUTE = 'acme-gateway'
+const MODEL = 'acme-large'
+
+describe('web e2e: the composer model switch is the default for later sessions', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  /** Create one session and its agent through the same wire face the browser uses. */
+  const createSession = async (sessionId: string): Promise<string> => {
+    const response = await scaffold.ctx.apiProxy.sessions.create({
+      rpcId: `default-model-create-${sessionId}` as never,
+      payload: { sessionId: SessionId(sessionId), cwd: scaffold.workspaceCwd },
+    })
+    if (!response.result.ok) throw new Error(`session.create failed: ${response.result.error.message}`)
+    return response.result.value.sessionId
+  }
+
+  /** The route the gateway reports for one session, through the real wire face. */
+  const currentOf = async (sessionId: string): Promise<unknown> => {
+    const response = await scaffold.ctx.apiProxy.sessions.models({
+      rpcId: `default-model-${sessionId}` as never,
+      payload: { sessionId: SessionId(sessionId) },
+    })
+    if (!response.result.ok) throw new Error(`session.models failed: ${response.result.error.message}`)
+    return response.result.value.current
+  }
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    // A second route so the picker has two models. Declared through the
+    // settings seam rather than the Models page: this scenario is about the
+    // composer, and the declaring flow is covered by models-settings.e2e.
+    await scaffold.ctx.settings.update(settingsNamespace('llm-pi-ai'), {
+      providers: {
+        [ROUTE]: {
+          displayName: 'Acme Gateway',
+          api: 'openai-completions',
+          baseURL: 'https://gateway.acme.example/v1',
+          models: [{ id: MODEL, name: 'Acme Large' }],
+        },
+      },
+    })
+    browser = await chromium.launch()
+    page = await browser.newPage({ viewport: { width: 1680, height: 1000 }, locale: ZH_BROWSER_LOCALE })
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    // The composer's seats only exist once a workspace is connected: without
+    // one the input is the locked placeholder and no session scope is open.
+    await connectFreshWorkspaceZh(page, scaffold.workspaceCwd)
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it('writes the switched model as the default and leaves a logged session alone', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-default-model'))
+    // A session that has already run a turn, spelled as the fact a turn
+    // leaves behind: its own logged route.
+    const loggedId = await createSession('default-model-logged')
+    scaffold.ctx.sessions.get(SessionId(loggedId))?.append('request/header', {
+      header: { config: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } },
+      reason: 'initial',
+    })
+
+    const trigger = page.getByRole('button', { name: /^选择模型/ })
+    await trigger.waitFor({ timeout: 15_000 })
+    await trigger.click()
+    await page.getByRole('menuitem', { name: /模型/ }).click()
+    await page.getByRole('menuitemradio', { name: 'Acme Large' }).click()
+
+    // The switch is what sets the default: the gateway's own settings section
+    // now names it, beside the provider profiles the Models page writes.
+    await expect.poll(
+      async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'),
+      { timeout: 10_000 },
+    ).toContain('api-gateway:')
+    const document = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
+    expect(document).toContain(`provider: ${ROUTE}`)
+    expect(document).toContain(`model: ${MODEL}`)
+
+    // A session created after the switch starts from it...
+    expect(await currentOf(await createSession('default-model-after')))
+      .toEqual({ provider: ROUTE, model: MODEL })
+    // ...while the one holding a logged route keeps deriving from its log.
+    expect(await currentOf(loggedId))
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    expect(tripwire.pageErrors).toEqual([])
+  }, 60_000)
+})
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 1d9117dc85..7fc31fab7c 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -25,6 +25,7 @@ import { ZH_BROWSER_LOCALE, saveFailureShot } from './support.ts'
 const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/models-settings', import.meta.url))
 const EMPTY_EXPECTED = join(SNAPSHOT_DIR, 'empty.expected.md')
 const CONFIGURED_EXPECTED = join(SNAPSHOT_DIR, 'configured.expected.md')
+const DECLARED_EXPECTED = join(SNAPSHOT_DIR, 'declared.expected.md')
 const DELETE_EXPECTED = join(SNAPSHOT_DIR, 'delete.expected.md')
 const MODE = webSnapshotMode()
 
@@ -114,10 +115,47 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
+  it('declares a route the adapter does not ship, with its own reasoning effort', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-models-declare'))
+    const dialog = page.getByRole('dialog', { name: '设置' })
+    const declare = dialog.getByRole('button', { name: '添加自定义提供方' })
+    await expect.poll(async () => declare.isEnabled(), { timeout: 10_000 }).toBe(true)
+    await declare.click()
+    await dialog.getByLabel('Provider ID').fill('acme-gateway')
+    await dialog.getByLabel('显示名称').fill('Acme Gateway')
+    await dialog.getByLabel('API 地址').fill('https://gateway.acme.example/v1')
+    // The create card offers the same provider-level effort the editor card
+    // does for this namespace; a route declared without it would gain the
+    // control only on reopening.
+    await dialog.getByLabel('推理强度').selectOption('high')
+    await dialog.getByRole('button', { name: '添加模型' }).click()
+    await dialog.getByLabel('模型 ID 1').fill('acme-large')
+    await dialog.getByRole('button', { name: '创建提供方', exact: true }).click()
+
+    const row = dialog.getByText('Acme Gateway', { exact: true }).first()
+    await row.waitFor({ timeout: 10_000 })
+    const document = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
+    expect(document).toContain('acme-gateway:')
+    expect(document).toContain('reasoning: high')
+
+    // The tag follows the adapter's installed catalog: this route is in no
+    // catalog, while minimax-cn is — even though both now have profiles.
+    const rowCard = (name: string) => dialog.locator('li').filter({ hasText: name }).first()
+    await expect.poll(async () => rowCard('Acme Gateway').getByText('自定义').count(), { timeout: 10_000 }).toBe(1)
+    expect(await rowCard('minimax-cn').getByText('自定义').count()).toBe(0)
+
+    const snapshot = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(DECLARED_EXPECTED, snapshot, MODE)
+    expect(tripwire.pageErrors).toEqual([])
+  }, 60_000)
+
   it('confirms provider deletion before removing its settings profile', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-models-delete'))
     const settingsDialog = page.getByRole('dialog', { name: '设置' })
-    await settingsDialog.getByRole('button', { name: '删除', exact: true }).click()
+    // Two rows carry a delete action now that a route is also declared; this
+    // scenario is about minimax-cn, so it names its own row.
+    const minimaxRow = settingsDialog.locator('li').filter({ hasText: 'minimax-cn' }).first()
+    await minimaxRow.getByRole('button', { name: '删除', exact: true }).click()
     const deleteDialog = page.getByRole('dialog', { name: '删除模型提供方？' })
     await deleteDialog.waitFor({ timeout: 10_000 })
     const snapshot = await captureStableAria(
@@ -129,7 +167,7 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
 
     await deleteDialog.getByRole('button', { name: '取消', exact: true }).click()
     expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).toContain('minimax-cn:')
-    await settingsDialog.getByRole('button', { name: '删除', exact: true }).click()
+    await minimaxRow.getByRole('button', { name: '删除', exact: true }).click()
     await page.getByRole('dialog', { name: '删除模型提供方？' })
       .getByRole('button', { name: '删除提供方', exact: true }).click()
     await expect.poll(
@@ -147,6 +185,7 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
   }, 60_000)
 
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
-    await assertFixtureInventory(SNAPSHOT_DIR, ['configured.expected.md', 'delete.expected.md', 'empty.expected.md'])
+    await assertFixtureInventory(SNAPSHOT_DIR,
+      ['configured.expected.md', 'declared.expected.md', 'delete.expected.md', 'empty.expected.md'])
   })
 })
diff --git a/apps/web/tests/snapshots/models-settings/declared.expected.md b/apps/web/tests/snapshots/models-settings/declared.expected.md
new file mode 100644
index 0000000000..3aa3d64cc9
--- /dev/null
+++ b/apps/web/tests/snapshots/models-settings/declared.expected.md
@@ -0,0 +1,30 @@
+- dialog "设置":
+  - navigation:
+    - text: 设置
+    - button "通用设置":
+      - img
+      - text: 通用设置
+    - button "模型":
+      - img
+      - text: 模型
+  - button "打开配置文件"
+  - button "关闭":
+    - img
+    - text: 关闭
+  - heading "模型" [level=2]
+  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - list:
+    - listitem:
+      - text: minimax-cn
+      - button "编辑"
+      - button "删除"
+    - listitem:
+      - text: Acme Gateway 自定义
+      - button "编辑"
+      - button "删除"
+  - button "添加提供方":
+    - img
+    - text: 添加提供方
+  - button "添加自定义提供方":
+    - img
+    - text: 添加自定义提供方
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 7d509957ad..b74eacdeb0 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -37,6 +37,7 @@
     "tests/details-session-lifecycle.e2e.ts",
     "tests/settings-chrome.e2e.ts",
     "tests/models-settings.e2e.ts",
+    "tests/default-model.e2e.ts",
     "tests/onboarding-deepseek-config.e2e.ts",
     "tests/remote-welcome.e2e.ts",
     "tests/workspace-management.e2e.ts",
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index ad27aac3b9..f1c37f97c4 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -578,17 +578,27 @@ Requires: `agents` · `directoryPicker` · `llm` · `sessions` · `subagents` ·
 
 ```ts config-catalog
 /** Gateway plugin config: host-level agent routing and Workspace creation root. */
-export interface Config {
-  /** Default provider route for created/resumed agents. */
-  provider: string
-  /** Default model id. */
-  model: string
+export interface Config extends DefaultRouteSettings {
   /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
   workspaceRoot?: string
 }
+
+/**
+ * The user-settable slice of the gateway config: the route a session starts
+ * from when its own log names none. `workspaceRoot` is deliberately not part
+ * of it — that is a launcher fact, not a preference.
+ */
+export interface DefaultRouteSettings {
+  /** Default provider route for created agents. */
+  provider: string
+  /** Default model id. */
+  model: string
+  /** Default reasoning effort; absence preserves the adapter/provider default. */
+  reasoningEffort?: string
+}
 ```
 
-Source: [`packages/host/apiproxy/src/index.ts:33`](../packages/host/apiproxy/src/index.ts)
+Source: [`packages/host/apiproxy/src/index.ts:64`](../packages/host/apiproxy/src/index.ts)
 
 ## `@deepseek-ai/dsh-host-directory-picker-browse`
 
diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml
index 5600da9e54..a048f4e43d 100644
--- a/docs/core-data-structures/core.i18n.yaml
+++ b/docs/core-data-structures/core.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 docs/core-data-structures/core.md
-core.md: 52e77be89d939eefa2b42ef5586c5798e194a303
-core.zh.md: 5f0134a4c8b3dead49830b41f62e8b7238327cfa
+core.md: eb96988abe096455c4f24ac220a6da3f266e690d
+core.zh.md: 7334b3d3a5bd088f5467a72d7357f87c4c745487
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index 52e77be89d..eb96988abe 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -313,6 +313,15 @@ interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it — a gateway or self-hosted server it ships nothing about.
+   * Absent means the adapter draws no such distinction; false means it does
+   * and this route is one of its own. Only the adapter can answer: a stored
+   * profile is how a user-added route AND a corrected shipped one both look
+   * from outside.
+   */
+  declared?: boolean
 }
 ```
 
diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md
index 5f0134a4c8..7334b3d3a5 100644
--- a/docs/core-data-structures/core.zh.md
+++ b/docs/core-data-structures/core.zh.md
@@ -319,6 +319,15 @@ interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it — a gateway or self-hosted server it ships nothing about.
+   * Absent means the adapter draws no such distinction; false means it does
+   * and this route is one of its own. Only the adapter can answer: a stored
+   * profile is how a user-added route AND a corrected shipped one both look
+   * from outside.
+   */
+  declared?: boolean
 }
 ```
 
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index dc2f8c5967..9559b5e198 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2500,8 +2500,11 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       providers: request => ok(request, {
         providers: [
           { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [], active: true },
-          { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'], active: true },
-          { provider: 'anthropic', displayName: 'anthropic', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'anthropic'], active: false },
+          { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'], active: true, declared: false },
+          { provider: 'anthropic', displayName: 'anthropic', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'anthropic'], active: false, declared: false },
+          // One hand-declared route, so a surface reading this fixture meets
+          // the tagged shape rather than only the shipped one.
+          { provider: 'acme-gateway', displayName: 'Acme Gateway', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'acme-gateway'], active: true, declared: true },
         ],
       }),
       models: request => ok(request, { groups: fixtureModelGroups(), failures: [] }),
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index ae296a91aa..ba7816421b 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/client/ui-models/README.md
-README.md: b55914197e472edec8a8b6d4d3e02036d1697728
-README.zh.md: ca93c3d5a2a85fffb22707f8389f1e979468e2ec
+README.md: ea3efd5b0a7ee3599fda74cd9a361222170c473d
+README.zh.md: 96290d6e56f36d485ea3e0b661197eda4cc40c09
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index b55914197e..ea3efd5b0a 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Models settings plugin: the provider configuration page and official-DeepSeek conditional onboarding step. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time, without presenting route liveness as provider status.
 
-Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), `reasoningEffort` (deepseek) or `reasoning` (pi-ai), and the direct DeepSeek adapter's advisory model catalog. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and a localized confirmation dialog must complete before the page submits that destructive unset.
+Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), `reasoningEffort` (deepseek) or `reasoning` (pi-ai), and the direct DeepSeek adapter's advisory model catalog. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and a localized confirmation dialog must complete before the page submits that destructive unset. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
 
 The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured literal `apiKey` secret sidecar or configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
 
@@ -16,7 +16,7 @@ A pi-ai profile's `models` list is edited on the card: one row per model showing
 
 **Fetch available models** asks `llm.discoverModels` about the endpoint the form **currently shows**, including a base URL edited but not yet saved and a key typed but not yet stored, so adding a provider is one pass instead of save-then-return. The reply opens a picker rather than being written: candidates already configured start unchecked, so adopting a selection never overwrites a capacity the user corrected. A provider that cannot be interrogated is a detour, not a dead end — the adapter's own message appears beside the rows, which stay editable by hand.
 
-**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts.
+**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts. The card offers the same provider-level reasoning effort the editor card does for this namespace, from one shared control: both write the same profile field, so a route declared without it would have gained the setting only on being reopened.
 
 ## Model Experience
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index ca93c3d5a2..96290d6e56 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -4,7 +4,7 @@
 
 模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。
 
-行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可以询问提供方它服务什么。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），另有 `reasoningEffort`（deepseek）或 `reasoning`（pi-ai），以及直接 DeepSeek 适配器的建议性模型目录。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），而且必须先在本地化对话框中确认，页面才会提交这次破坏性的 unset。
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可以询问提供方它服务什么。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），另有 `reasoningEffort`（deepseek）或 `reasoning`（pi-ai），以及直接 DeepSeek 适配器的建议性模型目录。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），而且必须先在本地化对话框中确认，页面才会提交这次破坏性的 unset。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
@@ -16,7 +16,7 @@ pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，
 
 **获取可用模型**会针对表单**当前显示**的端点调用 `llm.discoverModels`，包括已修改但尚未保存的 API 地址和已键入但尚未存储的密钥，因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路——适配器自己的消息会显示在各行旁边，而这些行仍可手工编辑。
 
-**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。
+**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。这张卡片提供与编辑器卡片在该 namespace 下相同的提供方级推理等级，两者共用同一个控件：它们写的是同一个 profile 字段，若声明时没有它，这个设置就会等到重新打开编辑时才凭空出现。
 
 ## 模型体验
 
diff --git a/packages/client/ui-models/src/client/ModelsSection.module.css b/packages/client/ui-models/src/client/ModelsSection.module.css
index a4d4d04121..ca99d6d4e9 100644
--- a/packages/client/ui-models/src/client/ModelsSection.module.css
+++ b/packages/client/ui-models/src/client/ModelsSection.module.css
@@ -72,6 +72,20 @@
   color: var(--dsw-alias-label-primary);
 }
 
+/* Reads as an annotation on the name, not as a second name: caption size and
+   the secondary label tone, so it never competes with the row's own title.
+   `rowActions` keeps the `margin-left: auto`, which is what holds the tag
+   beside the name instead of letting it drift across the row. */
+.rowTag {
+  flex: none;
+  padding: 1px 6px;
+  border: 1px solid var(--dsw-alias-border-l3);
+  border-radius: 4px;
+  font-size: 11px;
+  line-height: 16px;
+  color: var(--dsw-alias-label-secondary);
+}
+
 .rowActions {
   display: inline-flex;
   align-items: center;
diff --git a/packages/client/ui-models/src/client/ModelsSection.tsx b/packages/client/ui-models/src/client/ModelsSection.tsx
index a69d11dd6c..a883bb293b 100644
--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-models/src/client/ModelsSection.tsx
@@ -205,6 +205,12 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
             <li key={row.entry.provider} className={styles['rowCard']}>
               <div className={styles['rowHead']}>
                 <span className={styles['rowName']}>{row.entry.displayName}</span>
+                {/* Only the adapter can tell a hand-declared route from a
+                    shipped one it also has a stored profile for, so the tag
+                    follows its answer and stays off when it gives none. */}
+                {row.entry.declared === true
+                  ? <span className={styles['rowTag']}>{t('customTag')}</span>
+                  : null}
                 <span className={styles['rowActions']}>
                   <button
                     type="button"
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index 19463d98fa..1689c6eab4 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -65,6 +65,7 @@ export const en = {
   fetchAdopt: 'Add selected',
   customAdd: 'Add a custom provider',
   customTitle: 'Custom provider',
+  customTag: 'Custom',
   customRoute: 'Provider ID',
   customRouteHint: 'Lowercase identifier that uniquely names this provider in requests and as its credential name.',
   customRouteInvalid: 'Use lowercase letters, digits, and dashes.',
@@ -149,6 +150,7 @@ export const zh: typeof en = {
   fetchAdopt: '添加所选',
   customAdd: '添加自定义提供方',
   customTitle: '自定义提供方',
+  customTag: '自定义',
   customRoute: 'Provider ID',
   customRouteHint: '小写标识，在请求中唯一标识该提供方，并用于派生凭据名。',
   customRouteInvalid: '只能使用小写字母、数字和短横线。',
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index b35302f78a..289cf30867 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -66,6 +66,8 @@ function scriptedFace(options: {
   providers?: Record<string, unknown>
   /** User layer, when it differs from the effective section. */
   userProviders?: Record<string, unknown>
+  /** Routes the adapter reports as hand-declared; the rest come back as shipped. */
+  declaredRoutes?: readonly string[]
   discover?: ReturnType<typeof vi.fn>
   mutate?: ReturnType<typeof vi.fn>
   set?: ReturnType<typeof vi.fn>
@@ -86,6 +88,7 @@ function scriptedFace(options: {
           settingsNs: 'llm-pi-ai',
           settingsPath: ['providers', provider],
           active: true,
+          declared: options.declaredRoutes?.includes(provider) ?? false,
         })),
       }))),
       models: vi.fn(() => Promise.resolve(ok({ groups: [], failures: [] }))),
@@ -599,6 +602,53 @@ describe('endpoint interrogation', () => {
   })
 })
 
+describe('provider rows', () => {
+  it('tags the routes the adapter declared, and only those', async () => {
+    await mountSection({
+      providers: {
+        openai: { apiKeyEnv: 'OPENAI_API_KEY' },
+        'acme-gateway': { apiKeyEnv: 'ACME_GATEWAY_API_KEY', baseURL: 'https://acme.test/v1' },
+      },
+      declaredRoutes: ['acme-gateway'],
+    })
+
+    const rowOf = (provider: string): HTMLElement => {
+      const row = screen.getByText(provider).closest('li')
+      if (row === null) throw new Error(`no row for ${provider}`)
+      return row
+    }
+    expect(rowOf('acme-gateway').textContent).toContain(en.customTag)
+    // `openai` carries a stored profile too — the tag follows the adapter's
+    // catalog, not the presence of settings, so it stays off here.
+    expect(rowOf('openai').textContent).not.toContain(en.customTag)
+  })
+
+  it('shows no tag when the adapter draws no catalog distinction', async () => {
+    const scripted = scriptedFace({ providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY' } } })
+    scripted.face.llm.providers = vi.fn(() => Promise.resolve(ok({
+      providers: [{
+        provider: 'openai',
+        displayName: 'openai',
+        settingsNs: 'llm-pi-ai',
+        settingsPath: ['providers', 'openai'],
+        active: true,
+      }],
+    }))) as never
+    const controller = new ModelsSettingsStore(scripted.face as unknown as WireFace)
+    await controller.load()
+    render(<ModelsSection
+      controller={controller}
+      useSnapshot={bindSnapshotSelector(controller.store)}
+      api={scripted.face as never}
+      t={t}
+    />)
+
+    // Absent is "unknown", never "shipped": an adapter that answers nothing
+    // must not have its routes labelled either way.
+    expect(screen.queryByText(en.customTag)).toBeNull()
+  })
+})
+
 describe('hand-declared providers', () => {
   function mountCard(overrides: Partial<Parameters<typeof CustomProviderCard>[0]> = {}) {
     const scripted = scriptedFace()
@@ -683,7 +733,7 @@ describe('hand-declared providers', () => {
     declare()
     fireEvent.click(screen.getByText(en.create))
     await waitFor(() => { expect(second.onClose).toHaveBeenCalledWith(true) })
-    expect(firstMutate(second.mutate).ops[0].value).not.toHaveProperty('reasoning')
+    expect(firstMutate(second.mutate).ops[0]).not.toHaveProperty('value.reasoning')
   })
 
   it('names the blocked gate under the form, and nothing once it is satisfied', () => {
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 63c1a491e1..f3ebe32b86 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -2099,7 +2099,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'LlmConfigurableProvider',
-    declaration: 'export interface LlmConfigurableProvider {\n    provider: string;\n    displayName: string;\n    settingsNs: string;\n    settingsPath: readonly string[];\n}',
+    declaration: 'export interface LlmConfigurableProvider {\n    provider: string;\n    displayName: string;\n    settingsNs: string;\n    settingsPath: readonly string[];\n    declared?: boolean;\n}',
   },
   {
     name: 'LlmDiscoveredModel',
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 38c79f4617..a5e9fd2aef 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 0963476a767801b465a6ead24feb0ecc9988b5f5
-README.zh.md: e3634c5f92f3a3723eb3c14e39223d9d9550c6f9
+README.md: 38f18995f2982db2c5a48971d7d044448e5adc8c
+README.zh.md: c444ed6b7485b6ddca059c5edf7f30828bd96ab7
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 0963476a76..38f18995f2 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -2,7 +2,17 @@
 
 English | [中文](README.zh.md)
 
-The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers such as HTTP wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml).
+The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, reasoningEffort?, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers such as HTTP wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml).
+
+## The default route (`api-gateway` settings section)
+
+`{provider, model, reasoningEffort?}` is also the gateway's user-settings section, registered under `api-gateway`: the composition entry is the `base` layer and `settings.yaml` layers the user's own choice over it. `workspaceRoot` is deliberately outside the section — a launcher fact, not a preference.
+
+A session resolves its route from three tiers, re-read on every access rather than seeded once: a selection made in this process, else the session's own latest logged `request/header`, else this default. Re-reading is what makes both directions hold — a session that has run a turn derives its route from its log forever after, so changing the default never retargets it, while a session still blank (New Session reuses one rather than minting another) starts from a default saved after it was created.
+
+`session.selectModel` records an accepted switch as the new default, which is how the default is chosen in practice: there is no separate gesture. The write replaces the section wholesale rather than merging, because switching to a model with no reasoning effort has to clear a stored one; a storage failure is logged without undoing the switch, which already applies to its own session. A deployment with no settings provider keeps the composition entry and a switch stays process-local.
+
+The stored route is not validated against the registry, in either direction. A default naming a route the Models page has since removed still reaches `session.models` as the session's `current` — matching no advertised group, which is precisely what makes a selector prompt for a replacement instead of naming a model the deployment cannot reach. Repairing it silently would also break the deliberate converse: an adapter may serve a model its catalog does not advertise.
 
 ## Contract layer (`/api`)
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index e3634c5f92..c444ed6b74 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -2,7 +2,17 @@
 
 [English](README.md) | 中文
 
-所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml)。
+所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, reasoningEffort?, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml)。
+
+## 默认路由（`api-gateway` 设置段）
+
+`{provider, model, reasoningEffort?}` 同时是网关的用户设置段，注册在 `api-gateway` 之下：组合条目是 `base` 层，`settings.yaml` 把用户自己的选择叠加其上。`workspaceRoot` 刻意不在段内——它是启动器事实，不是偏好。
+
+会话按三级解析自己的路由，且每次读取都重新解析，而不是只在创建时种一次：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是这个默认值。重新解析正是让两个方向都成立的原因——已经跑过一轮的会话此后永远从自己的日志推导路由，改默认值不会重定向它；而仍然空白的会话（新建会话会复用一个，而不是再开一个）则会用上它创建之后才保存的默认值。
+
+`session.selectModel` 会把被接受的切换记录为新的默认值，实践中默认值就是这样选定的，没有另一个单独的手势。写入是整段替换而非合并，因为切到一个不支持推理的模型必须清掉已存的等级；存储失败只记日志，不会撤销这次切换——它对自己所在的会话已经生效。没有设置提供方的部署保留组合条目，切换只停留在进程内。
+
+存下来的路由不做注册表校验，两个方向都不做。默认值指向一个已在模型页删除的路由时，它照样作为会话的 `current` 送到 `session.models`——匹配不到任何已公布的分组，而这恰恰是让选择器提示重新选择、而不是显示一个部署根本够不着的模型的原因。静默修复它还会破坏刻意保留的反面情形：适配器可以服务一个自己目录未公布的模型。
 
 ## 契约层（`/api`）
 
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 709c63e4d0..aaa2d68a44 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -26,7 +26,8 @@ import {
 // Type-only: brings the `ctx.tools` Context merge into this program (viewFor reads presenters).
 import type {} from '@deepseek-ai/dsh-tools'
 import type {
-  ApiProxy, CredentialView, GoalRef, HistoryEntry, HostFrame, ModelCatalogFailure, ModelProviderGroup,
+  ApiProxy, ConfigurableProviderView, CredentialView, GoalRef, HistoryEntry, HostFrame,
+  ModelCatalogFailure, ModelProviderGroup,
   ModelReasoning, MuxFrame, QuestionResponsePayload, SessionProjectionsBlock, SessionSearchItem,
   QueuedInboxItem, SessionSummary, SettingsNamespaceView, SubagentAddress, ToolEventView,
   WorkspaceId, WorkspaceView,
@@ -2558,15 +2559,17 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         const active = new Set(registered.map(provider => provider.id))
         const directory = ctx.llm.listConfigurableProviders()
         const declared = new Set(directory.map(entry => entry.provider))
-        const views = directory.map(entry => ({
+        const views: ConfigurableProviderView[] = directory.map(entry => ({
           provider: entry.provider,
           displayName: entry.displayName,
           settingsNs: entry.settingsNs,
           settingsPath: [...entry.settingsPath],
           active: active.has(entry.provider),
+          ...entry.declared === undefined ? {} : { declared: entry.declared },
         }))
         // Routes registered without a directory declaration still appear —
-        // they exist and serve models — just with no settings address.
+        // they exist and serve models — just with no settings address. No
+        // adapter claimed them, so nothing can say whether they are shipped.
         for (const provider of registered) {
           if (declared.has(provider.id)) continue
           views.push({
diff --git a/packages/host/apiproxy/src/api/llm.schema.ts b/packages/host/apiproxy/src/api/llm.schema.ts
index 6ded8c32ac..7c8b0e6397 100644
--- a/packages/host/apiproxy/src/api/llm.schema.ts
+++ b/packages/host/apiproxy/src/api/llm.schema.ts
@@ -16,6 +16,7 @@ export const configurableProviderViewSchema = z.object({
   settingsNs: z.string(),
   settingsPath: z.array(z.string()),
   active: z.boolean(),
+  declared: z.boolean().optional(),
 }) satisfies z.ZodType<Wire<ConfigurableProviderView>>
 
 /** llm.providers request payload. */
diff --git a/packages/host/apiproxy/src/api/llm.ts b/packages/host/apiproxy/src/api/llm.ts
index edd85a52b2..29cda6cf78 100644
--- a/packages/host/apiproxy/src/api/llm.ts
+++ b/packages/host/apiproxy/src/api/llm.ts
@@ -22,6 +22,12 @@ export interface ConfigurableProviderView {
   settingsPath: string[]
   /** Whether the route is currently registered (its models are requestable). */
   active: boolean
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it. Absent when the adapter draws no such distinction, so a
+   * surface must treat absence as "unknown", not as "shipped".
+   */
+  declared?: boolean
 }
 
 /** Llm-domain unary methods (the map keys llm.* of RpcMethodMap). */
diff --git a/packages/host/apiproxy/src/index.ts b/packages/host/apiproxy/src/index.ts
index 34ce49fc77..cb2f88f436 100644
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -66,22 +66,23 @@ export interface Config extends DefaultRouteSettings {
   workspaceRoot?: string
 }
 
-/**
- * The default-route fields, as fresh schema instances. Both the plugin config
- * and the settings section are built from this one call, so the section stays
- * a subset of the config structurally rather than by a comment two people have
- * to keep true.
- */
-function defaultRouteFields(): { [K in keyof Required<DefaultRouteSettings>]: z<string> } {
-  return {
-    provider: z.string().required(),
-    model: z.string().required(),
-    reasoningEffort: z.string(),
-  }
-}
+/** The config fields the settings section carries; the rest stay launcher-owned. */
+const DEFAULT_ROUTE_FIELDS = ['provider', 'model', 'reasoningEffort'] as const
 
-/** Schema of the settings section. */
-const DefaultRouteSchema: z<DefaultRouteSettings> = z.object(defaultRouteFields())
+/**
+ * The settings section's schema, picked out of the plugin config rather than
+ * restated. The config stays a plain literal because the configuration-catalog
+ * generator reads it statically; picking from it is what keeps the section a
+ * subset of it as both evolve.
+ * @param config - the plugin config schema to pick from.
+ * @returns the section schema over {@link DEFAULT_ROUTE_FIELDS}.
+ */
+function defaultRouteSchema(config: z<Config>): z<DefaultRouteSettings> {
+  const fields = Object.fromEntries(
+    DEFAULT_ROUTE_FIELDS.map(field => [field, config.dict?.[field]]),
+  )
+  return z.object(fields) as z<DefaultRouteSettings>
+}
 
 /** Project the stored/composed section onto the agent-facing target shape. */
 function routeTarget(settings: DefaultRouteSettings): AgentLlmTarget {
@@ -106,7 +107,9 @@ export class ApiProxyService extends Service implements ApiProxy {
   ]
 
   static Config: z<Config> = z.object({
-    ...defaultRouteFields(),
+    provider: z.string().required(),
+    model: z.string().required(),
+    reasoningEffort: z.string(),
     workspaceRoot: z.string(),
   })
 
@@ -135,7 +138,7 @@ export class ApiProxyService extends Service implements ApiProxy {
       ...config.reasoningEffort === undefined ? {} : { reasoningEffort: config.reasoningEffort },
     }
     let route: () => DefaultRouteSettings = () => entry
-    installSettingsSection(ctx, API_GATEWAY_SETTINGS_NAMESPACE, DefaultRouteSchema, entry, {
+    installSettingsSection(ctx, API_GATEWAY_SETTINGS_NAMESPACE, defaultRouteSchema(ApiProxyService.Config), entry, {
       setSource: (current) => {
         route = current
       },
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index b4e9cffabb..641ad62a9c 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: af0e952dd8dbd9767b98229ee6b87262007d6738
-README.zh.md: f8a19999f08aa8a6963874d57bf74370797b951c
+README.md: 3eee22198320dbbaf4b53e7d4339f1292f3fa36e
+README.zh.md: 3871ab046147f57b442ea8018482080e04567150
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index af0e952dd8..3eee221983 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -49,7 +49,7 @@ Configure credentials, the model catalog, and deployment-specific transport sett
             maxTokens: 4096
 ```
 
-The dict shape makes duplicate routes unrepresentable, and the pre-release array shape (with per-profile `provider` fields) fails load with migration directions. `providers` may also be empty or omitted entirely: the adapter then mounts **dormant** — zero routes, no extra catalog entries — and registers routes the moment the `llm-pi-ai:` settings section supplies profiles, dropping them again when it empties. Dormant or not, the plugin declares every installed catalog provider in the configurable-provider directory (`ctx.llm.listConfigurableProviders()`, settings path `providers.<provider>`), joined with every route the current profiles declare, so configuration surfaces can offer the full catalog before any route exists and can still address a hand-declared one. Which adapters exist is composition; which providers run can be entirely the user's settings document. Registration with `ctx.llm` is atomic: a collision with any provider route already owned by another adapter fails plugin loading without registering the remaining routes. Model ids are not lifecycle config; a model the route does not configure fails before any provider request with `LlmError('UNKNOWN_MODEL')`.
+The dict shape makes duplicate routes unrepresentable, and the pre-release array shape (with per-profile `provider` fields) fails load with migration directions. `providers` may also be empty or omitted entirely: the adapter then mounts **dormant** — zero routes, no extra catalog entries — and registers routes the moment the `llm-pi-ai:` settings section supplies profiles, dropping them again when it empties. Dormant or not, the plugin declares every installed catalog provider in the configurable-provider directory (`ctx.llm.listConfigurableProviders()`, settings path `providers.<provider>`), joined with every route the current profiles declare, so configuration surfaces can offer the full catalog before any route exists and can still address a hand-declared one. Each entry carries `declared`: whether pi-ai ships nothing under that key. It follows the installed catalog, never the settings document, because narrowing a shipped provider's models stores a profile too and that route is still one pi-ai knows — only the adapter can tell the two apart, which is why the directory answers rather than leaving a surface to infer it. Which adapters exist is composition; which providers run can be entirely the user's settings document. Registration with `ctx.llm` is atomic: a collision with any provider route already owned by another adapter fails plugin loading without registering the remaining routes. Model ids are not lifecycle config; a model the route does not configure fails before any provider request with `LlmError('UNKNOWN_MODEL')`.
 
 ## Catalog resolution
 
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index f8a19999f0..3871ab0461 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -49,7 +49,7 @@
             maxTokens: 4096
 ```
 
-字典形状使重复路由无法表示，发布前的数组形状（每个 profile 携带 `provider` 字段）会加载失败并给出迁移指引。`providers` 也可以为空或整体省略：适配器将以**休眠**姿态挂载——零路由、模型选择器不多一条——一旦 `llm-pi-ai:` settings 分节提供了 profile 就即时注册路由，分节清空时随之撤销。无论是否休眠，插件都会在可配置提供方目录（`ctx.llm.listConfigurableProviders()`，settings 路径 `providers.<provider>`）中声明每个已安装 catalog 提供方，并与当前 profile 声明的每条路由取并集，因此配置界面既能在任何路由存在之前就提供完整 catalog，也能寻址一条手工声明的路由。哪些适配器存在归组合面；哪些提供方在运行可以完全交给用户的设置文档。向 `ctx.llm` 注册具有原子性：如果与另一适配器已拥有的任何提供方路由冲突，插件会加载失败，不注册剩余路由。模型 id 不是生命周期配置；路由未配置的模型会在发起任何提供方请求前以 `LlmError('UNKNOWN_MODEL')` 失败。
+字典形状使重复路由无法表示，发布前的数组形状（每个 profile 携带 `provider` 字段）会加载失败并给出迁移指引。`providers` 也可以为空或整体省略：适配器将以**休眠**姿态挂载——零路由、模型选择器不多一条——一旦 `llm-pi-ai:` settings 分节提供了 profile 就即时注册路由，分节清空时随之撤销。无论是否休眠，插件都会在可配置提供方目录（`ctx.llm.listConfigurableProviders()`，settings 路径 `providers.<provider>`）中声明每个已安装 catalog 提供方，并与当前 profile 声明的每条路由取并集，因此配置界面既能在任何路由存在之前就提供完整 catalog，也能寻址一条手工声明的路由。每个条目都带上 `declared`：pi-ai 在这个键下是否什么都没有。它跟随已安装 catalog 而非设置文档，因为收窄一个内置提供方的模型同样会存下 profile，而那条路由仍然是 pi-ai 认识的——只有适配器分得清两者，所以由目录直接给出答案，而不是留给界面去猜。哪些适配器存在归组合面；哪些提供方在运行可以完全交给用户的设置文档。向 `ctx.llm` 注册具有原子性：如果与另一适配器已拥有的任何提供方路由冲突，插件会加载失败，不注册剩余路由。模型 id 不是生命周期配置；路由未配置的模型会在发起任何提供方请求前以 `LlmError('UNKNOWN_MODEL')` 失败。
 
 ## Catalog 解析
 
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index 0d058e94ac..b2b62dc627 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -92,11 +92,21 @@ function registrationFacts(profiles: ReadonlyMap<string, ResolvedPiAiProviderPro
 function directoryEntries(
   profiles: ReadonlyMap<string, ResolvedPiAiProviderProfile>,
 ): LlmConfigurableProvider[] {
+  const catalog = new Set(catalogProviderIds())
   const entries = new Map<string, LlmConfigurableProvider>()
   const declare = (provider: string, displayName: string): void => {
-    entries.set(provider, { provider, displayName, settingsNs: NS, settingsPath: ['providers', provider] })
+    entries.set(provider, {
+      provider,
+      displayName,
+      settingsNs: NS,
+      settingsPath: ['providers', provider],
+      // Membership of the installed catalog, not of the settings document:
+      // narrowing a shipped provider's models stores a profile too, and that
+      // route is still one pi-ai knows.
+      declared: !catalog.has(provider),
+    })
   }
-  for (const provider of catalogProviderIds()) declare(provider, provider)
+  for (const provider of catalog) declare(provider, provider)
   for (const [provider, profile] of profiles) declare(provider, profile.displayName)
   return [...entries.values()]
 }
diff --git a/packages/llm/llm-pi-ai/tests/catalog.spec.ts b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
index 49805b65b3..2afbb87ec0 100644
--- a/packages/llm/llm-pi-ai/tests/catalog.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
@@ -124,13 +124,22 @@ describe('hand-declared providers', () => {
   it('joins the configurable-provider directory so a settings surface can reach it', async () => {
     const server = await mockServer([])
     const ctx = await harness(gateway(`${server.url}/v1`))
+    const directory = ctx.llm.listConfigurableProviders()
 
-    expect(ctx.llm.listConfigurableProviders()).toContainEqual({
+    expect(directory).toContainEqual({
       provider: 'acme-gateway',
       displayName: 'Acme Gateway',
       settingsNs: 'llm-pi-ai',
       settingsPath: ['providers', 'acme-gateway'],
+      // Nothing in the installed catalog answers for this route, which is what
+      // configuration surfaces mark as a route this deployment declared.
+      declared: true,
     })
+    // Membership of the catalog, not of the settings document: a shipped
+    // provider carries a stored profile the moment anyone corrects it.
+    expect(directory.filter(entry => entry.declared).map(entry => entry.provider))
+      .toEqual(['acme-gateway'])
+    expect(directory.find(entry => entry.provider === 'deepseek')?.declared).toBe(false)
   })
 
   it('sizes a model the catalog cannot describe from the route\u2019s own fallbacks', () => {
diff --git a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
index 3416dc15dc..3a810daa77 100644
--- a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
@@ -68,6 +68,7 @@ describe('request-level dynamic profiles', () => {
       displayName: 'openai',
       settingsNs: 'llm-pi-ai',
       settingsPath: ['providers', 'openai'],
+      declared: false,
     })
     await ctx.settings.update(NS, {
       providers: { deepseek: { apiKeyEnv: 'PI_DYNAMIC_KEY', baseURL: server.url } },
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 5e4daa179b..9322ff4b11 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
-README.md: ca34ffdeaafdbe061e030c80997b7234ce36a1bd
-README.zh.md: 1f95d3cd641126e129f94fe31269454a1bcce972
+README.md: 47fb73cd710a269bc0ac768ef475b56c99b98929
+README.zh.md: b46ecf8ad1904630094b2c2b22ea421a406f4d79
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index ca34ffdeaa..47fb73cd71 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -13,7 +13,7 @@ An adapter registry plus a single streaming call surface, interceptable via a wa
 - `ctx.llm.registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle` Register one adapter instance for the given provider routes. Registration is all-or-nothing, and is disposed with the calling fiber. The returned disposer also carries `replace(providers)`: the candidate route set is validated in full before anything moves, so a conflict with another adapter leaves the current routes registered and serving, and the swap itself is one synchronous section with no observable gap. `replace([])` is legal — a registration holding zero routes — unlike an empty initial registration.
 - `ctx.llm.listProviders(): LlmProviderInfo[]` Describe registered provider routes in registration order.
 - `ctx.llm.registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle` Declare provider routes an adapter plugin can activate through configuration — registered or dormant — each naming its owning settings namespace and the path to its profile inside that section. All-or-nothing (`INVALID_DIRECTORY`/`DUPLICATE_DIRECTORY`), disposed with the calling fiber. The handle also carries `replace(entries)`: the candidate set is validated in full before anything moves, so an entry another registration already declares leaves the current set intact, and an empty array is legal there. A plugin whose declared set follows its configuration must use `replace` rather than disposing and re-registering — the latter strands the directory empty whenever the new set is refused.
-- `ctx.llm.listConfigurableProviders(): LlmConfigurableProvider[]` List the declared directory in declaration order; configuration surfaces merge it with `listProviders()` to mark each entry live or dormant.
+- `ctx.llm.listConfigurableProviders(): LlmConfigurableProvider[]` List the declared directory in declaration order; configuration surfaces merge it with `listProviders()` to mark each entry live or dormant. An entry may carry `declared` — whether the owning adapter knows that route only because configuration named it. Only the adapter can answer, so absence means "this adapter draws no such distinction", never "shipped".
 - `ctx.llm.registerModelDiscovery(settingsNs: string, discover): () => void` Offer to interrogate provider endpoints for the settings namespace this plugin owns. One offer per namespace (`INVALID_DISCOVERY`/`DUPLICATE_DISCOVERY`), disposed with the calling fiber.
 - `ctx.llm.listModelDiscoveryNamespaces(): string[]` List the namespaces that can interrogate an endpoint, so a surface offers the action only where it works.
 - `ctx.llm.discoverModels(settingsNs: string, request: LlmModelDiscoveryRequest): Promise<LlmDiscoveredModel[]>` Ask one endpoint which models it advertises.
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 1f95d3cd64..b46ecf8ad1 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -13,7 +13,7 @@
 - `ctx.llm.registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle` 为给定提供方路由注册一个适配器实例。注册要么全部成功，要么全部不生效，并且会随调用 fiber 一起 dispose（资源释放）。返回的释放器还携带 `replace(providers)`：候选路由集合会在任何东西变动之前完整校验，因此与另一适配器冲突时，当前路由保持注册且继续服务，而替换本身是一个同步区段，不存在可观察的空档。`replace([])` 合法——一个持有零条路由的注册——这与空的初始注册不同。
 - `ctx.llm.listProviders(): LlmProviderInfo[]` 按注册顺序描述已注册提供方路由。
 - `ctx.llm.registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle` 声明适配器插件可通过配置激活的提供方路由——无论已注册还是休眠——每个条目指明其所属 settings namespace，以及 profile 在该分节内的路径。要么全部成功，要么全部不生效（`INVALID_DIRECTORY`/`DUPLICATE_DIRECTORY`），并随调用 fiber dispose。该句柄还带 `replace(entries)`：候选集合会先被整体校验，因此其中若有条目已被另一个注册声明，当前集合原封不动；此处允许传空数组。声明集合随配置变化的插件必须使用 `replace`，而不是先 dispose 再重新注册——后者会在新集合被拒时让目录整个落空。
-- `ctx.llm.listConfigurableProviders(): LlmConfigurableProvider[]` 按声明顺序列出已声明的目录；配置界面将其与 `listProviders()` 合并，为每个条目标注存活或休眠。
+- `ctx.llm.listConfigurableProviders(): LlmConfigurableProvider[]` 按声明顺序列出已声明的目录；配置界面将其与 `listProviders()` 合并，为每个条目标注存活或休眠。条目可携带 `declared`——拥有该路由的适配器是否只因配置点名才知道它。只有适配器能回答，因此缺席意味着「这个适配器不作此区分」，绝不等于「内置」。
 - `ctx.llm.registerModelDiscovery(settingsNs: string, discover): () => void` 为本插件拥有的 settings namespace 提供「询问提供方端点」的能力。每个 namespace 只能有一个（`INVALID_DISCOVERY`/`DUPLICATE_DISCOVERY`），并随调用 fiber dispose。
 - `ctx.llm.listModelDiscoveryNamespaces(): string[]` 列出可以询问端点的 namespace，让界面只在可用之处提供该动作。
 - `ctx.llm.discoverModels(settingsNs: string, request: LlmModelDiscoveryRequest): Promise<LlmDiscoveredModel[]>` 询问某个端点它公布了哪些模型。
diff --git a/packages/llm/llm/src/types.ts b/packages/llm/llm/src/types.ts
index 4980b74405..959190bbbb 100644
--- a/packages/llm/llm/src/types.ts
+++ b/packages/llm/llm/src/types.ts
@@ -137,6 +137,15 @@ export interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it — a gateway or self-hosted server it ships nothing about.
+   * Absent means the adapter draws no such distinction; false means it does
+   * and this route is one of its own. Only the adapter can answer: a stored
+   * profile is how a user-added route AND a corrected shipped one both look
+   * from outside.
+   */
+  declared?: boolean
 }
 
 /**
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 5772905a9e..4823d5fb84 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -9,6 +9,7 @@
   },
   "include": [
     "apps/web/tests/scaffold.ts",
+    "apps/web/tests/default-model.e2e.ts",
     "apps/web/tests/support.ts",
     "apps/web/tests/scaffold-hermetic.e2e.ts",
     "apps/web/tests/core-web-profile.snapshot.ts",

From 768e2e866fa7681107aff90e055e023c44116957 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 13:56:42 +0800
Subject: [PATCH 098/516] fix(web): keep skill row pairing client-local

---
 .../2026-08-06-web-skill-tool-row.i18n.yaml   |  4 +-
 .../feature/2026-08-06-web-skill-tool-row.md  |  6 +--
 .../2026-08-06-web-skill-tool-row.zh.md       |  6 +--
 packages/client/connection/src/client/api.ts  |  2 +-
 .../client/connection/src/client/fixture.ts   | 43 ++++++---------
 .../client/connection/src/client/index.ts     |  2 +-
 packages/client/runtime/README.i18n.yaml      |  4 +-
 packages/client/runtime/README.md             |  2 +-
 packages/client/runtime/README.zh.md          |  2 +-
 .../client/session-history/history-fold.ts    | 16 ++----
 .../src/client/sessions/conversation.ts       |  6 +--
 .../runtime/src/client/sessions/session.ts    | 12 ++---
 .../src/client/sessions/transcript-adapter.ts | 26 ++-------
 packages/client/runtime/tests/fake-api.ts     |  4 +-
 .../client/runtime/tests/history-fold.spec.ts | 14 -----
 packages/client/runtime/tests/session.spec.ts | 17 ------
 .../runtime/tests/transcript-adapter.spec.ts  | 16 ------
 .../client/contract/terminal-card-model.ts    | 11 ++--
 .../ui-conversation/tests/chat-view.spec.tsx  |  4 +-
 packages/client/ui-skill/README.i18n.yaml     |  4 +-
 packages/client/ui-skill/README.md            |  3 +-
 packages/client/ui-skill/README.zh.md         |  3 +-
 packages/host/apiproxy/README.i18n.yaml       |  4 +-
 packages/host/apiproxy/README.md              |  2 +-
 packages/host/apiproxy/README.zh.md           |  2 +-
 packages/host/apiproxy/src/api-proxy.ts       | 54 ++++---------------
 packages/host/apiproxy/src/api/index.ts       |  2 +-
 .../host/apiproxy/src/api/sessions.schema.ts  | 12 +----
 packages/host/apiproxy/src/api/sessions.ts    | 18 ++-----
 .../apiproxy/tests/api-proxy-view.spec.ts     | 41 --------------
 .../host/apiproxy/tests/rpc-schemas.spec.ts   | 10 +---
 31 files changed, 79 insertions(+), 273 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
index 237338a7e6..a9ee64e640 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.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 .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
-2026-08-06-web-skill-tool-row.md: bebcf658de33d133ffea8eb190fb4e8e63bf82ff
-2026-08-06-web-skill-tool-row.zh.md: 9377829aab1cb6b347cb837dafe7e7e4afb63868
+2026-08-06-web-skill-tool-row.md: 6583062f38b0e9cff059fa4477313ff6a5bdd2aa
+2026-08-06-web-skill-tool-row.zh.md: 3d5c4b712896c2cf41df3ec913c597f7f791486c
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
index bebcf658de..6583062f38 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
@@ -14,16 +14,16 @@ The Web transcript renders `skill` calls through the generic fallback row, so a
 
 The collapsed row uses a 16-pixel document-and-sparkle glyph and the Bash row's neutral hierarchy: tertiary glyph, secondary `Skill` title, caption separator, and tertiary skill name. Running, failed, and interrupted calls retain the transcript's shimmer, error dot and first-line summary, and warning dot semantics. A settled call expands through the whole summary row into a 260-pixel bounded `Instructions` card containing the exact durable result text; the existing trajectory `Inspect` handoff remains available below the card.
 
-The row derives every visible value from the logged call/result slice. It reads the skill name from the recorded `name` argument and the instructions from durable result content, and never joins the current skill catalog for descriptions or provider metadata. Because a history page can contain a `tool/result` after its `tool/call` fell outside the window, the generic `HistoryEntry` envelope now carries the paired call's name, exact arguments JSON, and event time on result entries. The Host derives this transient annotation and the result render intent from the complete log; the runtime prefers an in-window call and otherwise materializes the same `ToolResultNode.call` and `callTime` from the annotation. An orphan result still has `call: null`, and a call-side render intent remains unavailable when its event is outside the page. The existing ACP `skill-load` recording is seeded through the real Web persistence and composition path for a keyless interaction and accessibility snapshot.
+The row derives every visible value from a paired call/result slice in the current runtime window. It reads the skill name from the recorded `name` argument and the instructions from durable result content, and never joins the current skill catalog for descriptions or provider metadata. If pagination leaves the call outside the window, the result has no tool identity and remains on the generic fallback rather than extending the history wire contract. The existing ACP `skill-load` recording is seeded through the real Web persistence and composition path for a keyless interaction and accessibility snapshot.
 
 ## Alternatives considered
 
 - Keep the generic tool row and add only a `skill` color selector in `ui-conversation`. This leaves the redundant input envelope and generic expanded body in place, and makes the conversation package own a domain-specific visual rule.
-- Add a new `skill` value to the host tool render-intent union. The keyed client slot already identifies this tool; the cross-page fix belongs to the generic history pairing envelope used by every tool rather than a skill-specific presentation value.
+- Add a new `skill` value to the host tool render-intent union. The keyed client slot already identifies this tool when its call is in the runtime window, so a new cross-boundary presentation value adds protocol and snapshot surface without enabling another consumer.
 - Export the conversation package's private `ToolRow` component for reuse. Client packages intentionally expose contracts rather than cross-package components; exporting it would couple independent feature packages to conversation implementation details.
 
 ## Consequences
 
 `ui-skill` now depends on the public conversation toolview contract, locale and primitive packages, and React in addition to its reference-source dependencies. It owns a small copy of the disclosure-row chrome, so future global interaction changes must update this registrant alongside the Bash sample and conversation rows.
 
-Cold replay stays deterministic across pagination and when the installed skill catalog changes, and the transcript remains compact until instructions are explicitly expanded. The generic pairing annotation also prevents other keyed tool rows and result presenters from changing identity at a page boundary without persisting duplicate data. The dedicated card intentionally shows the tool's complete framed output rather than extracting only `<skill_instructions>`, preserving exactly what reached the model and avoiding a second parser for the skill result format.
+Cold replay stays deterministic when the installed skill catalog changes, and the transcript remains compact until instructions are explicitly expanded. A result-only history page intentionally uses the generic fallback; keeping this edge case generic preserves the existing history protocol and confines the feature to client presentation. The dedicated card intentionally shows the tool's complete framed output rather than extracting only `<skill_instructions>`, preserving exactly what reached the model and avoiding a second parser for the skill result format.
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
index 9377829aab..3d5c4b7128 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
@@ -14,16 +14,16 @@ Web transcript（文本记录）通过通用后备行渲染 `skill` 调用，使
 
 收起的行使用 16 像素的文档与闪光组合图标，并沿用 Bash 行的中性色层级：图标采用三级色，`Skill` 标题采用二级色，分隔符采用 caption 色，skill 名称采用三级色。运行、失败和中断调用分别沿用 transcript 的扫光、错误状态点加首行摘要，以及警告状态点语义。已结算调用可以通过整个摘要行展开一个高度上限为 260 像素的 `Instructions` 卡片，其中原样呈现持久化结果文本；用于跳转至 trajectory 的现有 `Inspect` 入口仍保留在卡片下方。
 
-该行的所有可见值均派生自已记录的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。由于 history 页可能包含 `tool/result`，而与之配对的 `tool/call` 已落在窗口外，通用 `HistoryEntry` envelope 现在会在结果条目上携带配对调用的名称、精确的 arguments JSON 和事件时间。Host 从完整日志派生这份瞬时注解和结果渲染意图；runtime 优先使用窗口内调用，否则从该注解物化出相同的 `ToolResultNode.call` 和 `callTime`。无配对结果仍为 `call: null`；调用事件位于页面外时，调用侧渲染意图仍不可用。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
+该行的所有可见值均派生自当前 runtime 窗口中已配对的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。如果分页将调用留在窗口外，结果便没有工具身份，并继续使用通用后备路径，而不是扩展 history 协议契约。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
 
 ## 考虑过的替代方案
 
 - 保留通用工具行，只添加一个 `skill` 颜色选择器，并将其放在 `ui-conversation` 中。该方案仍会保留多余的输入外层结构和通用展开体，也会让 conversation 包拥有特定领域的视觉规则。
-- 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 已经能够识别该工具；跨页修复属于所有工具共用的通用 history 配对 envelope，而不是 skill 专用的呈现值。
+- 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 在调用位于 runtime 窗口内时已经能够识别该工具，因此新的跨边界呈现值只会增加协议和快照表层，却不会支持其他消费方。
 - 导出 conversation 包的私有 `ToolRow` 组件供复用。客户端包刻意对外暴露契约而非跨包组件；导出该组件会使独立功能包耦合到 conversation 的实现细节。
 
 ## 后果
 
 除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 契约、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
 
-无论跨越分页，还是已安装的 skill 目录发生变化，冷回放都保持确定性；在用户显式展开指令前，transcript 保持紧凑。通用配对注解还可防止其他键控工具行和结果 presenter 在分页边界改变身份，同时无需持久化重复数据。专用卡片有意显示工具完整封装的输出，而不是只提取 `<skill_instructions>`，从而原样保留模型实际收到的内容，也避免为 skill 结果格式再引入一个解析器。
+即使已安装的 skill 目录发生变化，冷回放仍保持确定性；在用户显式展开指令前，transcript 保持紧凑。仅含结果的 history 页有意使用通用后备路径；让这个边缘情况保持通用呈现，可以保留现有 history 协议，并将该功能限定在客户端呈现层。专用卡片有意显示工具完整封装的输出，而不是只提取 `<skill_instructions>`，从而原样保留模型实际收到的内容，也避免为 skill 结果格式再引入一个解析器。
diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts
index de15a9c67f..6f29b2dda0 100644
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -7,7 +7,7 @@
 
 export type {
   ApiProxy, SessionsApi, SessionSearchItem, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
-  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, HistoryToolCall, ToolEventView,
+  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
   DirectoryEntry, DirectoryListing,
   WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index bacbacdd23..dc2f8c5967 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -29,7 +29,7 @@ import type {
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import { deriveEventMessage, foldSurface } from '@deepseek-ai/dsh-session/surface'
 import type {
-  ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HistoryToolCall, HostFrame, MuxFrame, RpcReceipt,
+  ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
   ModelProviderGroup, ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
   ToolCallView, ToolEventView, ToolResultView, WorkspaceId, WorkspaceView,
 } from './api.ts'
@@ -664,33 +664,25 @@ function presentResult(name: string, argsRaw: string, resultText: string): ToolR
   }
 }
 
-/** Full-log tool/result pair used by the fixture history envelope and presenter mirror. */
-function pairedHistoryCall(event: SessionEvent, log: readonly SessionEvent[]): HistoryToolCall | undefined {
-  if (event.type !== 'tool/result') return undefined
-  const callId = String(event.data.message.source.callId)
-  for (let i = log.length - 1; i >= 0; i--) {
-    const candidate = log[i]
-    /* v8 ignore next -- dense-array guard: i stays within [0, log.length),
-    so the undefined arm needs a sparse log no code path builds. */
-    if (candidate !== undefined && candidate.type === 'tool/call' && String(candidate.data.callId) === callId) {
-      return { name: candidate.data.name, arguments: candidate.data.arguments, time: candidate.time }
-    }
-  }
-  return undefined
-}
-
-/** Host-side viewFor mirror: tool/call presents from its own args; tool/result uses its full-log pair. */
+/** Host-side viewFor mirror: tool/call presents from its own args; tool/result back-scans the log for the paired call. */
 function viewFor(event: SessionEvent, log: readonly SessionEvent[]): ToolEventView | undefined {
   if (event.type === 'tool/call') {
     const view = presentCall(event.data.name, event.data.arguments)
     return view === undefined ? undefined : { for: 'call', view }
   }
   if (event.type === 'tool/result') {
-    const call = pairedHistoryCall(event, log)
-    if (call === undefined) return undefined
-    const resultText = event.data.message.content[0].content.map(b => (b.type === 'text' ? b.text : '')).join('')
-    const view = presentResult(call.name, call.arguments, resultText)
-    return view === undefined ? undefined : { for: 'result', view }
+    const callId = String(event.data.message.source.callId)
+    for (let i = log.length - 1; i >= 0; i--) {
+      const candidate = log[i]
+      /* v8 ignore next -- dense-array guard: i stays within [0, log.length),
+      so the undefined arm needs a sparse log no code path builds. */
+      if (candidate !== undefined && candidate.type === 'tool/call' && String(candidate.data.callId) === callId) {
+        const resultText = event.data.message.content[0].content.map(b => (b.type === 'text' ? b.text : '')).join('')
+        const view = presentResult(candidate.data.name, candidate.data.arguments, resultText)
+        return view === undefined ? undefined : { for: 'result', view }
+      }
+    }
+    return undefined // cross-page unpaired: documented default
   }
   return undefined
 }
@@ -1055,12 +1047,7 @@ function pageOf(
   }
   const events = log.slice(start, end).map((event): HistoryEntry => {
     const view = viewFor(event, log)
-    const call = pairedHistoryCall(event, log)
-    return {
-      event,
-      ...view === undefined ? {} : { view },
-      ...call === undefined ? {} : { call },
-    }
+    return view === undefined ? { event } : { event, view }
   })
   return { events, hasMore: start > 0 }
 }
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index 83e9722a49..67b47b06c6 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -13,7 +13,7 @@ import { isLoopbackHostname } from '../loopback-hostname.ts'
 // ---- Contract re-exports (browser-safe apiproxy channels + core types) ----
 export type {
   ApiProxy, SessionsApi, SessionSearchItem, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
-  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, HistoryToolCall, ToolEventView,
+  ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
   DirectoryEntry, DirectoryListing,
   ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index ef94a8834c..23c867e4c0 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: 3d981392ce0314f41fe84bc1adb2b9484a6a5989
-README.zh.md: c05bdb6ebb33c0ffa47e2b54fb1b3d9d25f2fa6d
+README.md: 8ac29a4258bbd7456b20c61e547d48c570e84d27
+README.zh.md: 0e065e43ecc571e68d3976d2100eb43959cb2e3d
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index 3d981392ce..8ac29a4258 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -34,7 +34,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 ## The human transcript
 
-`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. A paged `tool/result` first pairs against an in-window `tool/call`, then against the Host-carried complete-log call annotation; `ToolResultNode.call` is null only for a truly orphaned durable result, so a page boundary cannot change keyed toolview dispatch, argument-derived labels, or duration. The call-side render intent remains null when its event is outside the window, while the result intent is already computed by the Host from the complete pair. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
+`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
 
 Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text comes from the checkpoint's `compact/summary` provenance; a window cut that left the provenance outside makes the row non-expandable rather than empty, and a later page that supplies it resolves the text. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index c05bdb6ebb..0e065e43ec 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -34,7 +34,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 面向人的 transcript（文本记录）
 
-`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。分页得到的 `tool/result` 会先与窗口内的 `tool/call` 配对，再与 Host 携带的完整日志调用注解配对；只有持久结果确实没有配对调用时，`ToolResultNode.call` 才为 null，因此分页边界无法改变键控 toolview 分派、由参数派生的标签或耗时。调用事件位于窗口外时，调用侧渲染意图仍为 null，而结果侧渲染意图已经由 Host 基于完整配对计算完成。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并以相同身份落成 `user/message` 时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
+`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并以相同身份落成 `user/message` 时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
 
 由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时该行不可展开而非空白，后续补上溯源的分页会解析出文本。性能契约：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
 
diff --git a/packages/client/runtime/src/client/session-history/history-fold.ts b/packages/client/runtime/src/client/session-history/history-fold.ts
index 83a09d3163..d792fd2b76 100644
--- a/packages/client/runtime/src/client/session-history/history-fold.ts
+++ b/packages/client/runtime/src/client/session-history/history-fold.ts
@@ -362,8 +362,7 @@ export function projectConversationHistory(
   let contextGeneration = 0
 
   for (const [index, event] of events.entries()) {
-    const entry = entries[index]
-    const view = entry?.view
+    const view = entries[index]?.view
     if (event.type === 'tool/call') {
       callIndex.set(String(event.data.callId), {
         name: event.data.name,
@@ -371,17 +370,8 @@ export function projectConversationHistory(
         time: event.time,
         callView: view?.for === 'call' ? view.view : null,
       })
-    } else if (event.type === 'tool/result') {
-      const callId = String(event.data.message.source.callId)
-      if (!callIndex.has(callId) && entry?.call !== undefined) {
-        callIndex.set(callId, {
-          name: entry.call.name,
-          argsRaw: entry.call.arguments,
-          time: entry.call.time,
-          callView: null,
-        })
-      }
-      if (view?.for === 'result') resultViews.set(event.seq, view.view)
+    } else if (event.type === 'tool/result' && view?.for === 'result') {
+      resultViews.set(event.seq, view.view)
     }
     if (isSurfaceEvent(event) && event.surfaceOp !== 'append') {
       contextGeneration++
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index 14bd0dc9ed..d24b963d6b 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -155,16 +155,16 @@ export interface TurnErrorNode {
   code?: string
 }
 
-/** A tool result paired with its durable call head when the Host can resolve it. */
+/** A tool result paired (when in-window) with its call head. */
 export interface ToolResultNode {
   kind: 'tool-result'
   seq: number
   /** Unix epoch ms from the tool/result session event. */
   time: number
   callId: string
-  /** Call head from the window or history envelope; null only when the durable log has no pair (card head shows callId). */
+  /** Call head backfilled from the in-window tool/call; null when window truncation left the call outside (card head shows callId). */
   call: { name: string; argsRaw: string } | null
-  /** Unix epoch ms of the paired tool/call; null when the durable log has no pair. */
+  /** Unix epoch ms of the paired tool/call when the call is still in-window; used for call-row duration. */
   callTime: number | null
   content: readonly ContentBlock[]
   isError: boolean
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index e663af8bf6..776f4494fd 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -5,7 +5,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { LlmRetryEventData } from '@deepseek-ai/dsh-llm-retry/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type {
-  HistoryEntry, HistoryToolCall, IApiClient, MessageId, MuxFrame, QueueAction, RpcError,
+  HistoryEntry, IApiClient, MessageId, MuxFrame, QueueAction, RpcError,
   RpcId, RpcResponse, RpcResult, SessionId, SubagentAddress, ToolEventView,
 } from '@deepseek-ai/dsh-client-connection/client'
 // Value import from the inline-safe wire layer (not the connection plugin):
@@ -85,8 +85,6 @@ export class Session implements SessionFace {
   /** Wire views aligned with `events` by index (envelope-level annotations; undefined = no view).
    *  Kept parallel rather than merged so `events` stays the raw log slice (model-visible ⟺ logged). */
   private views: (ToolEventView | undefined)[] = []
-  /** Host-carried call metadata aligned with result entries when the call event is outside the page. */
-  private historyCalls: (HistoryToolCall | undefined)[] = []
   private baseSeq = 0
   private hasMore = false
   private openState: OpenState = 'cold'
@@ -383,11 +381,10 @@ export class Session implements SessionFace {
       }
       this.events = [...older.map(e => e.event), ...this.events]
       this.views = [...older.map(e => e.view), ...this.views]
-      this.historyCalls = [...older.map(e => e.call), ...this.historyCalls]
       /* v8 ignore next -- the ?? arm needs older[0] undefined, but the empty-page branch above already returned. */
       this.baseSeq = older[0]?.event.seq ?? this.baseSeq
       this.hasMore = result.value.hasMore
-      this.transcript.reset(this.events, this.views, this.historyCalls) // prepend forces a rebuild (the window grew at the head)
+      this.transcript.reset(this.events, this.views) // prepend forces a rebuild (the window grew at the head)
       this.rebuildDerivedFromWindow()
     } catch (error) {
       console.error('[web-runtime] loadOlder failed:', error)
@@ -414,7 +411,6 @@ export class Session implements SessionFace {
     this.openError = null
     this.events = []
     this.views = []
-    this.historyCalls = []
     this.baseSeq = 0
     // Superseded, not settled: the baseline replay re-sends still-pending requested frames verbatim
     // (same rpcId), re-minting fresh waits; a stale reference's respond() still reaches the host.
@@ -648,10 +644,9 @@ export class Session implements SessionFace {
   private installWindow(entries: HistoryEntry[], hasMore: boolean, projections?: ProjectionsBaseline): void {
     this.events = entries.map(e => e.event)
     this.views = entries.map(e => e.view)
-    this.historyCalls = entries.map(e => e.call)
     this.baseSeq = this.events[0]?.seq ?? 0
     this.hasMore = hasMore
-    this.transcript.reset(this.events, this.views, this.historyCalls)
+    this.transcript.reset(this.events, this.views)
     this.rebuildDerivedFromWindow()
     if (projections !== undefined) this.projections.seed(projections)
     const buffered = this.liveBuffer
@@ -666,7 +661,6 @@ export class Session implements SessionFace {
     if (tailSeq !== null && event.seq <= tailSeq) return // replay overlap, drop
     this.events.push(event)
     this.views.push(view)
-    this.historyCalls.push(undefined)
     this.transcript.append(event, view)
     this.handoffPendingSteering(event)
     this.applyEventSideEffects(event, view)
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index b1d952b804..306571b2bf 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -19,9 +19,7 @@ import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 // `sessions: ISessions` (TS2717, the one-program-per-side rule in
 // docs/development.md).
 import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
-import type {
-  HistoryToolCall, ToolCallView, ToolEventView, ToolResultView,
-} from '@deepseek-ai/dsh-client-connection/client'
+import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
 import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
 import { toAssistantBlocks } from './conversation.ts'
 import { contextForm, contextProvenance } from './context-provenance.ts'
@@ -215,13 +213,8 @@ export class TranscriptAdapter {
    * and re-project the transcript.
    * @param events - the new window contents (seq-ascending).
    * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
-   * @param calls - host-carried result pairs aligned with `events` by index.
    */
-  reset(
-    events: readonly SessionEvent[],
-    views?: readonly (ToolEventView | undefined)[],
-    calls?: readonly (HistoryToolCall | undefined)[],
-  ): void {
+  reset(events: readonly SessionEvent[], views?: readonly (ToolEventView | undefined)[]): void {
     this.rev++
     this.eventIndex = new Map()
     this.callIdx = new Map()
@@ -235,7 +228,7 @@ export class TranscriptAdapter {
       /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
       if (event === undefined) continue
       this.eventIndex.set(event.seq, event)
-      this.indexCall(event, views?.[i], calls?.[i])
+      this.indexCall(event, views?.[i])
       this.indexCommand(event)
       if (this.steeringHistory.apply(event)) steeringSeqs.add(event.seq)
       indexAssistantStepTiming(this.stepTimings, event)
@@ -345,20 +338,9 @@ export class TranscriptAdapter {
     return true
   }
 
-  private indexCall(event: SessionEvent, view?: ToolEventView, pairedCall?: HistoryToolCall): void {
+  private indexCall(event: SessionEvent, view?: ToolEventView): void {
     if (event.type === 'tool/result') {
       if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
-      const callId = String(event.data.message.source.callId)
-      if (!this.callIdx.has(callId) && pairedCall !== undefined) {
-        this.callIdx.set(callId, {
-          name: pairedCall.name,
-          argsRaw: pairedCall.arguments,
-          turn: event.data.turn,
-          step: event.data.step,
-          time: pairedCall.time,
-          callView: null,
-        })
-      }
       return
     }
     if (event.type !== 'tool/call') return
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
index b13e27f3c4..e50574d102 100644
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -3,7 +3,7 @@
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
-  ClientResponse, CommandDescriptor, HistoryEntry, HostFrame, IApiClient, ModelTarget, MuxFrame,
+  ClientResponse, CommandDescriptor, HostFrame, IApiClient, ModelTarget, MuxFrame,
   RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId, SessionModels, SessionSearchItem, SkillEntry,
   WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
@@ -68,7 +68,7 @@ export class FakeApiClient implements IApiClient {
   onRename: (payload: unknown) => Promise<RpcResponse<{ title: string; seq: number }>> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 }))
   onFork: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
-  => Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean }>> =
+  => Promise<RpcResponse<{ events: never[]; hasMore: boolean }>> =
     () => Promise.resolve(ok({ events: [], hasMore: false }))
 
   onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
diff --git a/packages/client/runtime/tests/history-fold.spec.ts b/packages/client/runtime/tests/history-fold.spec.ts
index f9b40bdb7c..083bdc3566 100644
--- a/packages/client/runtime/tests/history-fold.spec.ts
+++ b/packages/client/runtime/tests/history-fold.spec.ts
@@ -53,20 +53,6 @@ describe('projectConversationHistory', () => {
     }])
   })
 
-  it('projects a paged tool result from its host-carried call pair', () => {
-    const result = ev.toolResult(50, 3, 'outside-call', '已加载 skill')
-    const projection = projectConversationHistory([{
-      event: result,
-      call: { name: 'skill', arguments: '{"name":"dsh-code-review"}', time: 40 },
-    }])
-    expect(projection.eventNodes).toMatchObject([{
-      kind: 'tool-result',
-      call: { name: 'skill', argsRaw: '{"name":"dsh-code-review"}' },
-      callTime: 40,
-      callView: null,
-    }])
-  })
-
   it('projects a high-sequence history window without synthesizing its unloaded prefix', () => {
     const baseSeq = 400_000
     const events = [
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index 02753fe09e..c288c044ee 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -53,23 +53,6 @@ describe('open', () => {
     expect(snapshot.turnEnds.get(3)).toBe(15)
   })
 
-  it('installs host-carried call metadata for a result-only tail page', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => Promise.resolve(ok({
-      events: [{
-        event: ev.toolResult(50, 3, 'outside-call', '已加载 skill'),
-        call: { name: 'skill', arguments: '{"name":"dsh-code-review"}', time: 40 },
-      }],
-      hasMore: true,
-    }))
-    await session.open()
-    expect(session.getSnapshot().nodes).toMatchObject([{
-      kind: 'tool-result',
-      call: { name: 'skill', argsRaw: '{"name":"dsh-code-review"}' },
-      callTime: 40,
-    }])
-  })
-
   it('is idempotent: concurrent opens share one history call, reopening when open is a no-op', async () => {
     const { api, session } = makeSession()
     await Promise.all([session.open(), session.open()])
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
index 99b4cdf261..031acf1780 100644
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ b/packages/client/runtime/tests/transcript-adapter.spec.ts
@@ -365,22 +365,6 @@ describe('TranscriptAdapter', () => {
     expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null })
   })
 
-  it('materializes a paged tool-result from its host-carried call pair', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(
-      [ev.toolResult(50, 3, 'outside-call', '已加载 skill')],
-      [undefined],
-      [{ name: 'skill', arguments: '{"name":"dsh-code-review"}', time: 40 }],
-    )
-    expect(adapter.nodes()[0]).toMatchObject({
-      kind: 'tool-result',
-      callId: 'outside-call',
-      call: { name: 'skill', argsRaw: '{"name":"dsh-code-review"}' },
-      callTime: 40,
-      callView: null,
-    })
-  })
-
   it('materializes a tool-result error field when present', () => {
     const adapter = new TranscriptAdapter()
     adapter.reset([
diff --git a/packages/client/ui-conversation/src/client/contract/terminal-card-model.ts b/packages/client/ui-conversation/src/client/contract/terminal-card-model.ts
index b1c4cbe757..8a0c887990 100644
--- a/packages/client/ui-conversation/src/client/contract/terminal-card-model.ts
+++ b/packages/client/ui-conversation/src/client/contract/terminal-card-model.ts
@@ -168,12 +168,11 @@ function collapse(body: string, rooted: boolean, separator = '/'): string {
  *   returns a generic fenced card for an execution error or a background
  *   start, whose text and error styling the generic path preserves.
  *
- * Window truncation can drop the call event and its call-side view from a
- * settled result (see `ToolResultNode.callView` in dsh-client-runtime), leaving
- * a terminal result with no presentation call side even though the history
- * envelope preserves its name and arguments. That still renders: the command
- * falls back to the result view's replacement title, then to an empty command
- * (the prompt line draws bare), and the prompt shows no cwd.
+ * Window truncation can drop the call head from a settled result (see
+ * `ToolResultNode.call`/`callView` in dsh-client-runtime), leaving a terminal
+ * result with no call side. That still renders: the command falls back to the
+ * result view's replacement title, then to an empty command (the prompt line
+ * draws bare), and the prompt shows no cwd.
  * @param block - RunningToolCall or ToolResultNode off the snapshot caches.
  * @param sessionCwd - the session workspace root, which resolves an omitted or
  *   relative view cwd (see {@link resolveTerminalCwd}); absent leaves both unresolved.
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index f0ed99da14..2369e8f1d6 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -285,12 +285,12 @@ describe('chat-flow derivation', () => {
 })
 
 describe('ChatView', () => {
-  it('an orphan tool result renders through the generic fallback', () => {
+  it('a windowless tool result (call head truncated) renders with an empty tool name', () => {
     const h = makeHarness({
       nodes: [{ ...toolResult(3, 'w1'), call: null }],
     })
     const view = render(<h.ChatView {...h.props} />)
-    // No durable call exists for this id, so the summary falls back to callId.
+    // classifyTool('') → others; the summary slot falls back to the callId.
     expect(view.container.querySelector('[data-variant="others"]')).not.toBeNull()
     expect(view.getByText('w1')).toBeTruthy()
   })
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index 5c50d22b89..57a1ff1676 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/client/ui-skill/README.md
-README.md: ba9f1faae0f70a0f7bed4641e02703cc26bcb692
-README.zh.md: f8210a885d201cbdc89d7a34704a819e80463d2c
+README.md: a9506fe563b94fb4d1f9afd882216e023b0c2d13
+README.zh.md: 6af5d3eb8820dacc2ab569be8b830481dd45fb9a
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index ba9f1faae0..a9506fe563 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -10,7 +10,7 @@ The `/client` export surface is the plugin body (`apply`/`inject`) only; the sou
 
 ## Skill tool row
 
-The browser plugin also registers a keyed `skill` toolview in `conversation.chat.toolview`. A collapsed row renders the 16-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from the logged call/result slice, using the history envelope's host-carried durable pair when pagination left the call event outside the window; it never reads the current catalog, so cold replay remains stable across page cuts and when installed skills or their descriptions change.
+The browser plugin also registers a keyed `skill` toolview in `conversation.chat.toolview`. A collapsed row renders the 16-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from a paired call/result slice in the current runtime window, never from the current catalog, so replay remains stable when installed skills or their descriptions change.
 
 ## Model Experience
 
@@ -30,6 +30,7 @@ Append-only: the reference is part of a new user message appended after the reus
 
 ## Known Limitations and Deferred Work
 
+- **Result-only history pages use the generic row** — keyed dispatch needs the paired call in the runtime window; pagination that leaves the call outside has no tool identity. This client presentation feature does not extend the history wire contract to recover it.
 - **Non-deterministic skill loading** — the reference is a collaboration cue, not a guarantee; the model may ignore it. The rework path when hit rate proves insufficient (a host-side `context/skill-reference` guidance package, or full-text injection) sits in the design ledger; the wire text shape would not change.
 - **First keystroke may race the prewarm** — the scope-birth warm launches the catalog fetch, but a menu opened before it settles shows no skill candidates for that keystroke. Accepted by design: skill references do not participate in enter adjudication, so nothing correctness-bearing waits on the catalog.
 - **Text is the truth** — the reference is plain draft text; a hand-typed identical token is the same reference. Chip visuals derive from the lexicon scan; no occurrence identity or position tracking (componentized chips are a ledger item).
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index f8210a885d..6af5d3eb88 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -10,7 +10,7 @@ skill（技能）引用 source 的浏览器端：把 `/` 触发的 `skill` sourc
 
 ## skill 工具行
 
-浏览器插件还会把一个 key 为 `skill` 的 toolview 注册进 `conversation.chat.toolview`。收起的行以与 Bash 行相同的中性色层级显示 16 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自已记录的调用／结果片段；分页将调用事件留在窗口外时，则使用 history envelope 中由 Host 携带的持久配对。该行绝不读取当前 skill 目录，因此冷回放在跨分页时，以及已安装的 skill 或其描述发生变化时均保持稳定。
+浏览器插件还会把一个 key 为 `skill` 的 toolview 注册进 `conversation.chat.toolview`。收起的行以与 Bash 行相同的中性色层级显示 16 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自当前 runtime 窗口中已配对的调用／结果片段，绝不读取当前 skill 目录，因此即使已安装的 skill 或其描述发生变化，回放仍保持稳定。
 
 ## 模型体验
 
@@ -30,6 +30,7 @@ skill（技能）引用 source 的浏览器端：把 `/` 触发的 `skill` sourc
 
 ## 已知限制与暂缓事项
 
+- **仅含结果的 history 页使用通用行**：键控分派要求配对调用位于 runtime 窗口内；分页将调用留在窗口外时，结果没有工具身份。这项客户端呈现功能不会为了恢复该身份而扩展 history 协议契约。
 - **skill 加载具有非确定性**：引用是协作线索，不是保证；模型可能忽略它。针对命中率不足情况的返工路径（host 侧 `context/skill-reference` 引导包，或全文注入）记录在设计台账中；协议中的文本形态不会改变。
 - **首次击键可能与预热竞速**：scope 创建时的预热会启动目录拉取，但目录落定之前打开的菜单，在那次击键下不会显示 skill 候选。这是设计上接受的取舍：skill 引用不参与回车裁决，因此没有任何攸关正确性的环节等待目录。
 - **文本是唯一依据**：引用是普通的草稿文本；手动键入的相同 token 就是同一个引用。chip 视觉由 lexicon 扫描派生；没有 occurrence 身份或位置跟踪（组件化 chip 是台账事项）。
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index f587ca109e..38c79f4617 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: bd8ad485980348a23054d5446d292ef0c24536dd
-README.zh.md: 7906ca224930736f335dcbdedc63b6af3019c070
+README.md: 0963476a767801b465a6ead24feb0ecc9988b5f5
+README.zh.md: e3634c5f92f3a3723eb3c14e39223d9d9550c6f9
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index bd8ad48598..0963476a76 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -12,7 +12,7 @@ The layering/protocol decisions are recorded in the [GUI layering and RPC protoc
 
 Question responses are validated against their pending request before the first answer claims it. A multi-select item may carry both requested option labels in `selected` and non-empty `custom` text; a single-select item must use one or the other. Duplicate labels, unknown labels, mismatched ids, incomplete batches, and empty custom text are rejected as `bad-response`.
 
-`session.history` reads an attached Session in memory or inspects a cold log through persistence without resuming or publishing an Agent, then pages on append-origin message boundaries. `maxMessages` counts `user/message` and `assistant/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it. A `tool/result` entry additionally carries its paired call's name, exact arguments JSON, and event time as a transient history annotation derived from the complete log, so a page cut cannot erase keyed toolview dispatch, argument-derived summaries, or duration. Result render intents use that same complete-log pair; an orphan result or malformed arguments still soft-fall to the generic presentation path.
+`session.history` reads an attached Session in memory or inspects a cold log through persistence without resuming or publishing an Agent, then pages on append-origin message boundaries. `maxMessages` counts `user/message` and `assistant/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it.
 
 `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index 7906ca2249..e3634c5f92 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -12,7 +12,7 @@
 
 首个回答认领待处理请求之前，系统会对照该请求校验问题响应。多选题的回答项可以同时携带 `selected` 中的请求选项标签与非空 `custom` 文本；单选题的回答项必须二选一。标签重复、标签未知、id 不匹配、批次不完整以及自定义文本为空都会以 `bad-response` 拒绝。
 
-`session.history` 按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。`tool/result` 条目还会携带其配对调用的名称、精确的 arguments JSON 和事件时间，作为从完整日志派生的瞬时 history 注解，因此分页切分无法抹掉键控 toolview 分派、由参数派生的摘要或耗时。结果渲染意图使用完整日志中的同一配对；无配对结果或参数损坏时，仍会软降级到通用呈现路径。
+`session.history` 按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 998e8d3ac5..19fb0fe8a2 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -26,7 +26,7 @@ import {
 // Type-only: brings the `ctx.tools` Context merge into this program (viewFor reads presenters).
 import type {} from '@deepseek-ai/dsh-tools'
 import type {
-  ApiProxy, CredentialView, GoalRef, HistoryEntry, HistoryToolCall, HostFrame, ModelCatalogFailure, ModelProviderGroup,
+  ApiProxy, CredentialView, GoalRef, HistoryEntry, HostFrame, ModelCatalogFailure, ModelProviderGroup,
   ModelReasoning, MuxFrame, QuestionResponsePayload, SessionProjectionsBlock, SessionSearchItem,
   QueuedInboxItem, SessionSummary, SettingsNamespaceView, SubagentAddress, ToolEventView,
   WorkspaceId, WorkspaceView,
@@ -408,9 +408,9 @@ function matchesQuestions(payload: QuestionResponsePayload, pending: PendingQues
  * Compute the render intent for a tool/call or tool/result event through the
  * presenters registered at this moment; every other event type gets none. A
  * result's presenter needs its call's parsed args — `argsFor` supplies them
- * (live: the per-session call table; history: the full-log pairing index),
- * returning undefined when the pairing is unavailable, which soft-falls to no
- * view. Presenter or JSON.parse throws also soft-fall:
+ * (live: the per-session call table; history: an in-page backscan), returning
+ * undefined when the pairing is unavailable (e.g. the call fell off the page),
+ * which soft-falls to no view. Presenter or JSON.parse throws also soft-fall:
  * the client's documented default (generic JSON card) covers every miss.
  */
 function viewFor(ctx: Context, event: SessionEvent, argsFor: (callId: string) => unknown): ToolEventView | undefined {
@@ -442,8 +442,10 @@ function viewFor(ctx: Context, event: SessionEvent, argsFor: (callId: string) =>
 }
 
 /**
- * Resolve a tool/result's call pairing by scanning a live session backwards
- * for the matching tool/call after the open-call table missed.
+ * Resolve a tool/result's call pairing by scanning a window of events backwards
+ * for the matching tool/call. Used by the history path (the page is the
+ * window — a cross-page pairing soft-falls to no view) and by live-path table
+ * misses after a reconnect-eviction.
  */
 function backscanArgs(events: readonly SessionEvent[], callId: string): { name: string; args: unknown } | undefined {
   for (let i = events.length - 1; i >= 0; i--) {
@@ -461,34 +463,6 @@ function backscanArgs(events: readonly SessionEvent[], callId: string): { name:
   return undefined
 }
 
-/** Index durable call metadata once so every history result keeps its pair across page cuts. */
-function historyCallIndex(events: readonly SessionEvent[]): ReadonlyMap<string, HistoryToolCall> {
-  const calls = new Map<string, HistoryToolCall>()
-  for (const event of events) {
-    if (event.type !== 'tool/call') continue
-    calls.set(String(event.data.callId), {
-      name: event.data.name,
-      arguments: event.data.arguments,
-      time: event.time,
-    })
-  }
-  return calls
-}
-
-/** Parse one indexed history pair for a result presenter, soft-falling malformed arguments. */
-function historyArgs(
-  calls: ReadonlyMap<string, HistoryToolCall>,
-  callId: string,
-): { name: string; args: unknown } | undefined {
-  const call = calls.get(callId)
-  if (call === undefined) return undefined
-  try {
-    return { name: call.name, args: JSON.parse(call.arguments) }
-  } catch {
-    return undefined
-  }
-}
-
 /** Render one detached history page through the same presenter path as ordinary history. */
 function historyPage(
   ctx: Context,
@@ -497,18 +471,10 @@ function historyPage(
   maxMessages: number | undefined,
 ): { events: HistoryEntry[]; hasMore: boolean } {
   const page = paginate(events, beforeSeq, maxMessages ?? DEFAULT_MAX_MESSAGES)
-  const calls = historyCallIndex(events)
   return {
     events: page.events.map((event) => {
-      const view = viewFor(ctx, event, callId => historyArgs(calls, callId))
-      const call = event.type === 'tool/result'
-        ? calls.get(String(event.data.message.source.callId))
-        : undefined
-      return {
-        event,
-        ...view === undefined ? {} : { view },
-        ...call === undefined ? {} : { call },
-      }
+      const view = viewFor(ctx, event, callId => backscanArgs(page.events, callId))
+      return { event, ...view === undefined ? {} : { view } }
     }),
     hasMore: page.hasMore,
   }
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index 697e5bdeae..4f10d92853 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -36,7 +36,7 @@ export interface ApiProxy {
 
 // ---- Domain interfaces and payload entities ----
 export type {
-  HistoryEntry, HistoryToolCall, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
+  HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
   ModelReasoningEffort, ModelTarget, QueueAction, SessionModels, SessionProjectionsBlock, SessionSearchItem,
   SessionsApi, SessionSummary,
 } from './sessions.ts'
diff --git a/packages/host/apiproxy/src/api/sessions.schema.ts b/packages/host/apiproxy/src/api/sessions.schema.ts
index f47289e77b..9f9c4329e6 100644
--- a/packages/host/apiproxy/src/api/sessions.schema.ts
+++ b/packages/host/apiproxy/src/api/sessions.schema.ts
@@ -11,7 +11,7 @@ import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 import type {
-  HistoryEntry, HistoryToolCall, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
+  HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
   ModelReasoningEffort, ModelTarget, SessionProjectionsBlock, SessionSearchItem, SessionSummary,
 } from './sessions.ts'
 import type { ToolEventView } from './events.ts'
@@ -193,18 +193,10 @@ export const toolEventViewSchema = z.discriminatedUnion('for', [
   z.object({ for: z.literal('result'), view: z.looseObject({ card: z.string() }) }),
 ]) as unknown as z.ZodType<ToolEventView>
 
-/** Paired tool/call metadata carried with a paged tool/result. */
-export const historyToolCallSchema: z.ZodType<Wire<HistoryToolCall>> = z.object({
-  name: z.string(),
-  arguments: z.string(),
-  time: z.number(),
-})
-
-/** One session.history item: raw event plus optional host-computed tool annotations. */
+/** One session.history item: the session event plus its optional host-computed tool view. */
 export const historyEntrySchema: z.ZodType<Wire<HistoryEntry>> = z.object({
   event: sessionEventSchema,
   view: toolEventViewSchema.optional(),
-  call: historyToolCallSchema.optional(),
 }) as unknown as z.ZodType<Wire<HistoryEntry>>
 
 /**
diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts
index 2a6da96db9..18315eef19 100644
--- a/packages/host/apiproxy/src/api/sessions.ts
+++ b/packages/host/apiproxy/src/api/sessions.ts
@@ -26,26 +26,14 @@ declare module '@deepseek-ai/dsh-llm' {
   }
 }
 
-/** Paired tool/call metadata carried beside a paged result whose call may be outside the page. */
-export interface HistoryToolCall {
-  /** Registered tool name used for keyed presentation dispatch. */
-  name: string
-  /** Exact durable arguments JSON from the paired tool/call. */
-  arguments: string
-  /** Unix epoch ms of the paired tool/call event. */
-  time: number
-}
-
 /**
- * One history page entry: the raw event plus optional host-computed render
- * intent and result pairing. Both annotations are pagination-time derivations,
- * never persisted; `call` preserves a tool/result's identity when its call
- * event lies outside this page.
+ * One history page entry: the raw event plus the optional host-computed render
+ * intent (same semantics as the mux frame's `view` slot — a pagination-time
+ * derivation, never persisted).
  */
 export interface HistoryEntry {
   event: SessionEvent
   view?: ToolEventView
-  call?: HistoryToolCall
 }
 
 /**
diff --git a/packages/host/apiproxy/tests/api-proxy-view.spec.ts b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
index 3b19a26b5e..43083545db 100644
--- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
@@ -231,50 +231,9 @@ describe('mux live view computation', () => {
       ]))
     expect(byKey.get('tool/call:h-term')?.view).toEqual({ for: 'call', view: { card: 'terminal', title: 'ls' } })
     expect(byKey.get('tool/result:h-term')?.view).toEqual({ for: 'result', view: { card: 'terminal', output: 'done' } })
-    expect(byKey.get('tool/result:h-term')?.call).toEqual({
-      name: 'term', arguments: '{"cmd":"ls"}', time: byKey.get('tool/call:h-term')?.event.time,
-    })
     expect('view' in (byKey.get('tool/result:h-orphan') ?? {})).toBe(false)
-    expect('call' in (byKey.get('tool/result:h-orphan') ?? {})).toBe(false)
     expect('view' in (byKey.get('tool/result:h-bad') ?? {})).toBe(false)
-    expect(byKey.get('tool/result:h-bad')?.call?.arguments).toBe('{broken')
     expect('view' in (byKey.get('tool/result:h-plain') ?? {})).toBe(false)
-    expect(byKey.get('tool/result:h-plain')?.call?.name).toBe('plain')
-  })
-
-  it('carries a result pair and computes its view when the call is outside the history page', async () => {
-    const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
-    const session = ctx.sessions.create()
-    ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
-    session.append('turn/start', { turn: 1 })
-    const call = session.append('tool/call', {
-      turn: 1, step: 1, callId: CallId('cross-page'), name: 'term', arguments: '{"cmd":"tail"}',
-    })
-    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    session.append('turn/start', { turn: 2 })
-    appendUserText(session, 'newer message cuts the page')
-    const result = session.append('tool/result', {
-      turn: 1, step: 1,
-      message: createToolResultMessage({
-        callId: CallId('cross-page'),
-        content: [{ type: 'text', text: 'late result' }],
-        isError: false,
-      }),
-    }, { surfaceOp: 'append' })
-
-    const response = await api.sessions.history({
-      rpcId: RpcId('t-hist-cross-page'),
-      payload: { sessionId: session.id, maxMessages: 1 },
-    })
-    if (!response.result.ok) throw new Error('unreachable')
-    const entries = response.result.value.events
-    expect(entries.some(entry => entry.event.seq === call.seq)).toBe(false)
-    const entry = entries.find(candidate => candidate.event.seq === result.seq)
-    expect(entry).toMatchObject({
-      call: { name: 'term', arguments: '{"cmd":"tail"}', time: call.time },
-      view: { for: 'result', view: { card: 'terminal', output: 'done' } },
-    })
   })
 
   it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
index 3a76dd9b07..b65861c1ae 100644
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -190,16 +190,10 @@ describe('sessions domain schemas', () => {
     expect(sessionHistoryRequestSchema.parse({ sessionId: 's1', beforeSeq: 3, maxMessages: 5 }).beforeSeq).toBe(3)
     expect(() => sessionHistoryRequestSchema.parse({ sessionId: 's1', maxMessages: 0 })).toThrow()
     expect(sessionHistoryValueSchema.parse({
-      events: [{
-        event: { type: 'tool/result', seq: 3, time: 30, data: {} },
-        call: { name: 'skill', arguments: '{"name":"review"}', time: 20 },
-      }],
+      events: [],
       hasMore: false,
       modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-    })).toMatchObject({
-      events: [{ call: { name: 'skill', arguments: '{"name":"review"}', time: 20 } }],
-      hasMore: false,
-    })
+    }).hasMore).toBe(false)
     expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
     expect(sessionModelsValueSchema.parse({
       current: { provider: 'deepseek-official', model: 'deepseek-v4-flash', reasoningEffort: 'max' },

From 72618f29b5573de77c6ba1f79c4f8b079c098523 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 13:57:52 +0800
Subject: [PATCH 099/516] fix(ui-models): stop the create card pinning a
 reference on a blank key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Master's credential-lifecycle work taught the editor card that a pi-ai
profile names `apiKeyEnv` only when a key is actually stored, so a route
left blank keeps its provider-native auth path. The create card kept
writing the derived reference unconditionally, so a route declared for a
credential chain or ADC was born pointing at a reference nothing sets —
and now rendered a red missing-key dot for it.

Both cards apply one rule. The obsolete assertion moves with the behavior
(the with-key case is covered by the neighbouring test), and the merged
Models e2e golden shows the declared route unmarked rather than flagged.
---
 .../tests/snapshots/models-settings/declared.expected.md | 9 +++++----
 packages/client/ui-models/README.i18n.yaml               | 4 ++--
 packages/client/ui-models/README.md                      | 2 +-
 packages/client/ui-models/README.zh.md                   | 2 +-
 .../client/ui-models/src/client/CustomProviderCard.tsx   | 9 +++++++--
 packages/client/ui-models/tests/provider-form.spec.tsx   | 4 +++-
 6 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/apps/web/tests/snapshots/models-settings/declared.expected.md b/apps/web/tests/snapshots/models-settings/declared.expected.md
index 3aa3d64cc9..df47e186c3 100644
--- a/apps/web/tests/snapshots/models-settings/declared.expected.md
+++ b/apps/web/tests/snapshots/models-settings/declared.expected.md
@@ -16,12 +16,13 @@
   - list:
     - listitem:
       - text: minimax-cn
-      - button "编辑"
-      - button "删除"
+      - img "API 密钥已配置"
+      - button "编辑 minimax-cn": 编辑
+      - button "删除 minimax-cn": 删除
     - listitem:
       - text: Acme Gateway 自定义
-      - button "编辑"
-      - button "删除"
+      - button "编辑 Acme Gateway (acme-gateway)": 编辑
+      - button "删除 Acme Gateway (acme-gateway)": 删除
   - button "添加提供方":
     - img
     - text: 添加提供方
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index 6f7c8deba3..01bf1be683 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/client/ui-models/README.md
-README.md: 9d1fbdddd1ad9ec4c073dd1c0ca4ac7124c1b876
-README.zh.md: ff740bc6d1096901cbcc33772aff09deafeb53a4
+README.md: fdd27478be25d4352462c2db0fc7eead1d1aee77
+README.zh.md: c0fd66b003593e7a535e28751f1f6d0ee80dfac1
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index 35e71c0dc0..fdd27478be 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -16,7 +16,7 @@ A pi-ai profile's `models` list is edited on the card: one row per model showing
 
 **Fetch available models** asks `llm.discoverModels` about the endpoint the form **currently shows**, including a base URL edited but not yet saved and a key typed but not yet stored, so adding a provider is one pass instead of save-then-return. The reply opens a picker rather than being written: candidates already configured start unchecked, so adopting a selection never overwrites a capacity the user corrected. A provider that cannot be interrogated is a detour, not a dead end — the adapter's own message appears beside the rows, which stay editable by hand.
 
-**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts. The card offers the same provider-level reasoning effort the editor card does for this namespace, from one shared control: both write the same profile field, so a route declared without it would have gained the setting only on being reopened.
+**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts. The card records the conventional `apiKeyEnv` reference only when a key is typed, the same rule the editor applies, so a route declared for provider-native authentication is not born pointing at a reference nothing will ever set. The card offers the same provider-level reasoning effort the editor card does for this namespace, from one shared control: both write the same profile field, so a route declared without it would have gained the setting only on being reopened.
 
 ## Model Experience
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index bc90540815..c0fd66b003 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -16,7 +16,7 @@ pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，
 
 **获取可用模型**会针对表单**当前显示**的端点调用 `llm.discoverModels`，包括已修改但尚未保存的 API 地址和已键入但尚未存储的密钥，因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路——适配器自己的消息会显示在各行旁边，而这些行仍可手工编辑。
 
-**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。这张卡片提供与编辑器卡片在该 namespace 下相同的提供方级推理等级，两者共用同一个控件：它们写的是同一个 profile 字段，若声明时没有它，这个设置就会等到重新打开编辑时才凭空出现。
+**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。这张卡片提供与编辑器卡片在该 namespace 下相同的提供方级推理等级，两者共用同一个控件：它们写的是同一个 profile 字段，若声明时没有它，这个设置就会等到重新打开编辑时才凭空出现。
 
 ## 模型体验
 
diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index 4bd14d1179..ffdc57baf0 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -98,9 +98,14 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
   /** Perform the create, returning a failure message or undefined. */
   const createOnce = async (): Promise<string | undefined> => {
     const keyRef = deriveKeyRef(route)
+    const storesKey = keyDraft.trim().length > 0
     const profile = {
       ...displayName.length === 0 ? {} : { displayName },
-      apiKeyEnv: keyRef,
+      // The profile names the conventional reference only when this card is
+      // about to store a key, matching the editor: a route declared with the
+      // key left blank keeps its provider-native auth path (a credential
+      // chain, ADC) instead of resolving a reference nothing ever sets.
+      ...storesKey ? { apiKeyEnv: keyRef } : {},
       api: protocol,
       baseURL,
       // Inherit is the field being absent, not an empty string: the schema
@@ -117,7 +122,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
       expectedRevision: openedAt,
     })
     if (!response.result.ok) return response.result.error.message
-    if (keyDraft.length > 0) {
+    if (storesKey) {
       const stored = await api.credentials.set({ ref: keyRef, value: keyDraft })
       // The profile landed; saying the key did not is the only honest report,
       // and the row is now editable so the key can be entered again there.
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 0a207d0a01..67def367bc 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -899,8 +899,10 @@ describe('hand-declared providers', () => {
 
     await waitFor(() => { expect(onClose).toHaveBeenCalledWith(true) })
     // No display name configured means none stored; the route id is the name.
+    // No key typed means no reference either, matching the editor: the route
+    // keeps its provider-native auth path instead of resolving a reference
+    // nothing ever sets. The with-key case is covered above.
     expect(firstMutate(mutate).ops[0]?.value).toEqual({
-      apiKeyEnv: 'ACME_API_KEY',
       api: 'anthropic-messages',
       baseURL: 'https://acme.test/v1',
       models: [{ id: 'm' }],

From 0823a3484a6279171e9552696ea39be55ec250c7 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 14:03:11 +0800
Subject: [PATCH 100/516] fix(web): report a wrapped paste as the same API key
 format failure

---
 .../2026-08-06-api-key-format-validation.i18n.yaml   |  4 ++--
 .../bug-fix/2026-08-06-api-key-format-validation.md  |  2 +-
 .../2026-08-06-api-key-format-validation.zh.md       |  2 +-
 packages/client/ui-models/README.i18n.yaml           |  4 ++--
 packages/client/ui-models/README.md                  |  2 +-
 packages/client/ui-models/README.zh.md               |  2 +-
 packages/client/ui-models/src/client/apiKey.ts       | 12 +++++++++---
 packages/client/ui-models/src/client/locales.ts      |  2 --
 packages/client/ui-models/tests/components.spec.tsx  |  4 ++--
 .../client/ui-models/tests/provider-form.spec.tsx    |  2 +-
 10 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index ae2d1d5934..d5418088d7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.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 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
-2026-08-06-api-key-format-validation.md: 4666f6197dbed060d00c77fdd6b87842141c10f4
-2026-08-06-api-key-format-validation.zh.md: 75c98bd29cf009e69ceb450432f540e3f49d99d0
+2026-08-06-api-key-format-validation.md: c85d03119565a25abb37a0d32550d46796148134
+2026-08-06-api-key-format-validation.zh.md: 84e5458675995d2454fa4becc5e6466f511c4932
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
index 4666f6197d..c85d031195 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
@@ -22,7 +22,7 @@ One rule defines a legal key: **after trimming, non-empty, and every character w
 
 This single predicate covers every input the sources list: empty, leading and trailing whitespace, interior whitespace, C0 control characters, emoji, CJK text, and full-width punctuation. It is also exactly the constraint that produced the ByteString failure, so the two issues close on one definition rather than on two coincidentally related fixes.
 
-A second, narrower rule catches a pasted environment line: input matching `^[A-Z][A-Z0-9_]*=` or wrapped in matching quotes is refused. Restricting the prefix to upper-case keeps real keys clear of it — `sk-` forms break the identifier match at the hyphen.
+A second, narrower rule catches a pasted environment line: input matching `^[A-Z][A-Z0-9_]*=[^=]` or wrapped in matching quotes is refused. Restricting the prefix to upper-case keeps real keys clear of it — `sk-` forms break the identifier match at the hyphen — and requiring a non-`=` character after the separator keeps base64 padding clear of it too. It reports the same format failure as an illegal character rather than its own message: the reader's next move is identical either way, so a separate line would name a cause without changing what to do.
 
 ### Invariants belong at every layer; heuristics belong where the human is
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index 75c98bd29c..84e5458675 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 这一个断言覆盖了来源列出的全部输入：空值、首尾空白、中间空白、C0 控制字符、emoji、中文、全角标点。它同时正是造成 ByteString 失败的那条约束，所以两个 issue 收敛于同一个定义，而不是两个恰好相关的修复。
 
-第二条更窄的规则用于识别整行粘贴的环境变量：匹配 `^[A-Z][A-Z0-9_]*=` 或首尾成对引号的输入会被拒绝。把前缀限定为全大写可以让真实 Key 与之绝缘——`sk-` 这类形态会在连字符处中断标识符匹配。
+第二条更窄的规则用于识别整行粘贴的环境变量：匹配 `^[A-Z][A-Z0-9_]*=[^=]` 或首尾成对引号的输入会被拒绝。把前缀限定为全大写可以让真实 Key 与之绝缘——`sk-` 这类形态会在连字符处中断标识符匹配——而要求分隔符之后必须是非 `=` 字符，则让 base64 的 padding 也与之绝缘。它报出的是与非法字符相同的那条格式失败，而不是自己的一句：读到它的人下一步动作完全一样，因此单列一句只会点出一个原因，却不改变该怎么做。
 
 ### 不变量属于每一层，启发式属于人所在的那一层
 
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index 3db62f6c31..ca475596fd 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/client/ui-models/README.md
-README.md: e3328bb5fd2cf812b05dc26bf534226818132631
-README.zh.md: 20e40cc571a9123b50dfb28565c5562937e03189
+README.md: a9799916a91cb7416765c387b59c9172fa477666
+README.zh.md: e73100fa7d23a4025dffe471615401617a4af811
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index e3328bb5fd..a9799916a9 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -8,7 +8,7 @@ Rows are the *configured* providers (their profile resolves in the owning namesp
 
 The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured literal `apiKey` secret sidecar or configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
 
-Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, the same shape the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. A typed API key is judged on its own field the same way: after trimming, it must be non-empty and every character must be printable ASCII (`[\x21-\x7E]`), which is exactly what an HTTP header value can carry — the twin of `normalizeApiKey` in `@deepseek-ai/dsh-llm`, mirrored here because the source-plane split forbids importing it. A field holding only whitespace fails rather than being silently dropped, and a value shaped like a pasted `NAME=value` environment line or wrapped in matching quotes fails too; that paste-shape heuristic runs only in the browser, since a false positive in a resolver would leave the environment refusing the key as well. An empty field is not a failure at all: it means keep the stored key on an editor card, and authenticate some other way on a create card. A refused key blocks both the write and the endpoint interrogation, so the page never spends a round trip to be told what the field already says. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
+Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, the same shape the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. A typed API key is judged on its own field the same way: after trimming, it must be non-empty and every character must be printable ASCII (`[\x21-\x7E]`), which is exactly what an HTTP header value can carry — the twin of `normalizeApiKey` in `@deepseek-ai/dsh-llm`, mirrored here because the source-plane split forbids importing it. A field holding only whitespace fails rather than being silently dropped, and a value shaped like a pasted `NAME=value` environment line or wrapped in matching quotes is refused as the same format failure; that paste-shape heuristic runs only in the browser, since a false positive in a resolver would leave the environment refusing the key as well. An empty field is not a failure at all: it means keep the stored key on an editor card, and authenticate some other way on a create card. A refused key blocks both the write and the endpoint interrogation, so the page never spends a round trip to be told what the field already says. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
 
 ## Model list and endpoint interrogation
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index 20e40cc571..e73100fa7d 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -8,7 +8,7 @@
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
-每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，与 pi-ai 提供方表单采用的形态相同。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。键入的 API 密钥同样在它自己的字段上被判定：trim 之后必须非空，且每个字符都是可打印 ASCII（`[\x21-\x7E]`）——这正是 HTTP 标头值所能承载的范围，是 `@deepseek-ai/dsh-llm` 中 `normalizeApiKey` 的孪生体，因源码平面分割禁止直接引入而在此镜像。只含空白的输入框会失败，而不是被静默丢弃；形如整行粘贴的 `NAME=value` 环境变量或首尾成对引号包裹的值也会失败——该粘贴形状启发式只在浏览器中运行，因为 resolver 中的一次误判会连带让环境变量这条路也拒绝该密钥。留空则完全不是失败：在编辑卡片上它意味着保持已存储的密钥，在新建卡片上则意味着以其他方式鉴权。被拒绝的密钥会同时拦截写入与端点探测，因此页面不会白花一次往返去换取字段上已经写明的答案。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
+每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，与 pi-ai 提供方表单采用的形态相同。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。键入的 API 密钥同样在它自己的字段上被判定：trim 之后必须非空，且每个字符都是可打印 ASCII（`[\x21-\x7E]`）——这正是 HTTP 标头值所能承载的范围，是 `@deepseek-ai/dsh-llm` 中 `normalizeApiKey` 的孪生体，因源码平面分割禁止直接引入而在此镜像。只含空白的输入框会失败，而不是被静默丢弃；形如整行粘贴的 `NAME=value` 环境变量或首尾成对引号包裹的值，会以同一条格式失败被拒绝——该粘贴形状启发式只在浏览器中运行，因为 resolver 中的一次误判会连带让环境变量这条路也拒绝该密钥。留空则完全不是失败：在编辑卡片上它意味着保持已存储的密钥，在新建卡片上则意味着以其他方式鉴权。被拒绝的密钥会同时拦截写入与端点探测，因此页面不会白花一次往返去换取字段上已经写明的答案。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
 
 ## 模型列表与端点询问
 
diff --git a/packages/client/ui-models/src/client/apiKey.ts b/packages/client/ui-models/src/client/apiKey.ts
index 5fd1d22ee6..5e3aa692c8 100644
--- a/packages/client/ui-models/src/client/apiKey.ts
+++ b/packages/client/ui-models/src/client/apiKey.ts
@@ -22,8 +22,14 @@ const LEGAL_API_KEY = /^[\x21-\x7E]+$/
  */
 const ENV_LINE = /^[A-Z][A-Z0-9_]*=[^=]/
 
-/** Copy key naming why a typed key cannot be saved. */
-export type ApiKeyFailureKey = 'keyBlank' | 'keyIllegalCharacters' | 'keyLooksWrapped'
+/**
+ * Copy key naming why a typed key cannot be saved. A wrapped paste reports the
+ * same format failure as an illegal character: the reader's next move is the
+ * same either way — look at the key and paste it again — so naming the two
+ * causes apart would spend the field's one line on a distinction that changes
+ * nothing about what to do.
+ */
+export type ApiKeyFailureKey = 'keyBlank' | 'keyIllegalCharacters'
 
 /** Whether a value is wrapped in one matching pair of quotes. */
 function isQuoted(value: string): boolean {
@@ -46,7 +52,7 @@ export function apiKeyFailure(draft: string): ApiKeyFailureKey | undefined {
   if (draft.length === 0) return undefined
   const value = draft.trim()
   if (value.length === 0) return 'keyBlank'
-  if (ENV_LINE.test(value) || isQuoted(value)) return 'keyLooksWrapped'
+  if (ENV_LINE.test(value) || isQuoted(value)) return 'keyIllegalCharacters'
   if (!LEGAL_API_KEY.test(value)) return 'keyIllegalCharacters'
   return undefined
 }
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index 85f7c14f97..336bf498f5 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -49,7 +49,6 @@ export const en = {
   keyBlank: 'Enter the API key, or leave the field empty to keep the stored one.',
   keyBlankNew: 'Enter the API key, or leave the field empty if this provider authenticates another way.',
   keyIllegalCharacters: 'This API key is not in a valid format. Please check it.',
-  keyLooksWrapped: 'Paste only the key itself — not a NAME=value line, and without surrounding quotes.',
   modelIdRequired: 'Model ID is required.',
   modelIdDuplicate: 'Model ID must be unique.',
   modelNameInvalid: 'Display name cannot be empty.',
@@ -137,7 +136,6 @@ export const zh: typeof en = {
   keyBlank: '请输入 API 密钥；留空则保持已存储的密钥。',
   keyBlankNew: '请输入 API 密钥；若该提供方以其他方式鉴权，可以留空。',
   keyIllegalCharacters: '该 API 密钥格式错误，请检查。',
-  keyLooksWrapped: '请只粘贴密钥本身——不要带 NAME=value 整行，也不要带引号。',
   modelIdRequired: '模型 ID 不能为空。',
   modelIdDuplicate: '模型 ID 不能重复。',
   modelNameInvalid: '显示名称不能为空。',
diff --git a/packages/client/ui-models/tests/components.spec.tsx b/packages/client/ui-models/tests/components.spec.tsx
index 7228d472cd..5bb2da387c 100644
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -1121,8 +1121,8 @@ describe('apiKeyFailure', () => {
     ['double quotes', '"sk-abc"'],
     ['single quotes', '\'sk-abc\''],
     ['backticks', '`sk-abc`'],
-  ])('fails %s as wrapped', (_label, draft) => {
-    expect(apiKeyFailure(draft)).toBe('keyLooksWrapped')
+  ])('fails %s as a format failure', (_label, draft) => {
+    expect(apiKeyFailure(draft)).toBe('keyIllegalCharacters')
   })
 
   it('needs a matching closing quote before it calls a value wrapped', () => {
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 5d505386e6..11271561b8 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -987,7 +987,7 @@ describe('API key field', () => {
 
     fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'OPENAI_API_KEY=sk-abc' } })
 
-    expect(screen.getByText(en.keyLooksWrapped)).toBeTruthy()
+    expect(screen.getByText(en.keyIllegalCharacters)).toBeTruthy()
     expect(buttonNamed(en.apply).disabled).toBe(true)
   })
 

From bb43ff4f37aad13729f03568f595b0415aed083d Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 15:26:42 +0800
Subject: [PATCH 101/516] feat(ui): make a session that cannot send refuse to
 accept one
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A default naming a route the Models page has since removed left the
composer saying 选择模型 while the input still accepted a message, which
then failed inside the adapter mid-turn.

`session.prompt` now refuses with `model-unavailable` before opening a
turn. That is the enforcement boundary: the method stays callable no
matter what a client disables. `session.models` reports the same fact as
`routable`, and ui-model pushes a block through the new
`ctx.conversation.blocks` registry so the bar renders the disabled
textarea it already renders without a workspace, carrying the blocker's
own reason. The push direction is forced — ui-model already depends on
ui-conversation, so ui-conversation cannot read it back.

The gate is `routable`, not "matches no advertised group": catalog
membership is advisory, so a route serving a model it stopped advertising
is missing from the groups yet perfectly usable, and `null` before the
first load never blocks so a slow Host cannot lock a working composer.

The scaffold gains a route-only adapter for fixture-less keyless
scenarios. Registering zero providers is a test artifact — every product
composition mounts one — and the goldens that froze the seat's fallback
label now show the model those scenarios actually route to.
---
 ...default-model-follows-the-picker.i18n.yaml |   4 +-
 ...-08-07-default-model-follows-the-picker.md |  12 +-
 ...-07-default-model-follows-the-picker.zh.md |  12 +-
 apps/web/tests/default-model.e2e.ts           |  67 +++++++++--
 apps/web/tests/default-model.overlay.yml      |   8 ++
 apps/web/tests/message-actions.e2e.ts         |   2 +-
 apps/web/tests/scaffold.ts                    |  54 +++++++++
 apps/web/tests/seeded-history.e2e.ts          |   8 +-
 .../snapshots/bash-abort-row/ui.expected.md   |   4 +-
 .../lifecycle-chrome/plan-active.expected.md  |   4 +-
 .../markdown-cjk-strong/ui.expected.md        |   4 +-
 .../snapshots/markdown-images/ui.expected.md  |   4 +-
 .../markdown-inline-code-links/ui.expected.md |   4 +-
 .../snapshots/math-rendering/ui.expected.md   |   4 +-
 .../snapshots/message-actions/ui.expected.md  |   4 +-
 .../seeded-history/command-row.expected.md    |   4 +-
 .../snapshots/seeded-history/ui.expected.md   |   4 +-
 docs/config-catalog.md                        |  27 ++---
 .../client/connection/src/client/fixture.ts   |   3 +
 packages/client/connection/tests/fake-api.ts  |   1 +
 packages/client/runtime/tests/fake-api.ts     |   1 +
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +
 packages/client/ui-conversation/README.zh.md  |   2 +
 .../ui-conversation/src/client/apply.ts       |  16 ++-
 .../src/client/contract/slots.ts              |   9 +-
 .../src/client/input/blocks.ts                |  77 +++++++++++++
 .../ui-conversation/src/client/service.ts     |  16 ++-
 .../src/client/skeleton/ConversationRoot.tsx  |  13 ++-
 .../tests/service-orchestration.spec.ts       |   3 +
 .../ui-conversation/tests/skeleton.spec.tsx   |  28 +++++
 packages/client/ui-model/README.i18n.yaml     |   4 +-
 packages/client/ui-model/README.md            |   2 +
 packages/client/ui-model/README.zh.md         |   2 +
 .../client/ui-model/src/client/directory.ts   |  23 +++-
 packages/client/ui-model/src/client/index.ts  |   6 +-
 .../client/ui-model/src/client/locales.ts     |   2 +
 .../client/ui-model/src/client/service.ts     |  28 ++++-
 .../ui-model/tests/browser-plugin.spec.ts     |  73 +++++++++++-
 .../ui-model/tests/model-select.spec.tsx      |   1 +
 packages/client/ui-models/README.i18n.yaml    |   4 +-
 packages/client/ui-models/README.md           |   2 +-
 packages/client/ui-models/README.zh.md        |   2 +-
 .../src/client/CustomProviderCard.tsx         |  80 +++++++------
 .../ui-models/tests/provider-form.spec.tsx    |  61 +++++++++-
 packages/host/apiproxy/README.i18n.yaml       |   4 +-
 packages/host/apiproxy/README.md              |   6 +-
 packages/host/apiproxy/README.zh.md           |   6 +-
 packages/host/apiproxy/src/api-proxy.ts       |  56 ++++++++-
 .../host/apiproxy/src/api/sessions.schema.ts  |   1 +
 packages/host/apiproxy/src/api/sessions.ts    |   9 ++
 packages/host/apiproxy/src/index.ts           |  76 ++++++------
 .../apiproxy/tests/api-proxy-config.spec.ts   |  21 +++-
 .../tests/api-proxy-default-route.spec.ts     | 108 ++++++++++++++++++
 .../apiproxy/tests/api-proxy-models.spec.ts   |  31 +++++
 .../apiproxy/tests/client-handler.spec.ts     |   1 +
 .../host/apiproxy/tests/fetch-carrier.spec.ts |   1 +
 .../host/apiproxy/tests/rpc-schemas.spec.ts   |   7 +-
 58 files changed, 859 insertions(+), 163 deletions(-)
 create mode 100644 apps/web/tests/default-model.overlay.yml
 create mode 100644 packages/client/ui-conversation/src/client/input/blocks.ts
 create mode 100644 packages/host/apiproxy/tests/api-proxy-default-route.spec.ts

diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
index ba3917c8b7..40eb59e98f 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.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 .agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
-2026-08-07-default-model-follows-the-picker.md: 5174b224a17728b65f7fd69d7f72388d50e8e825
-2026-08-07-default-model-follows-the-picker.zh.md: 6ead561b928572a479f2c7b19e409b3845363ed6
+2026-08-07-default-model-follows-the-picker.md: 4142b3aea6a807001831df62c2038ddf57bbd6ad
+2026-08-07-default-model-follows-the-picker.zh.md: c3566567781edac12cd9269d63f86528139c8796
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
index 5174b224a1..4142b3aea6 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
@@ -10,7 +10,7 @@ The route a new session started from was frozen into the gateway's composition e
 
 ## Decision
 
-`ApiProxyService` registers its `{provider, model, reasoningEffort?}` slice as the `api-gateway` settings section: the composition entry is the `base` layer and `settings.yaml` layers the user's choice over it. `workspaceRoot` stays outside the section — a launcher fact, not a preference. The section schema is picked out of `static Config` rather than restated, because the configuration-catalog generator reads that literal statically and a spread breaks it.
+`ApiProxyService` registers its `{provider, model, reasoningEffort?}` slice as the `api-gateway` settings section: the composition entry is the `base` layer and `settings.yaml` layers the user's choice over it. `workspaceRoot` stays outside the section — a launcher fact, not a preference. `reasoningEffort` is the mirror case: it lives in the section but NOT in the plugin config, because the seam merges the user layer over the composition entry per field and an absent key cannot override a present one. A composition-set effort would therefore survive every later switch to a model without one — precisely the stranding the wholesale `replace` exists to prevent. Effort is a per-model fact anyway; a deployment default for it belongs on the adapter profile, which resolves per model.
 
 `session.selectModel` records an accepted switch as the new default. There is no separate gesture: switching models in the composer IS how the default is chosen. The write is `replace`, not `update` — switching to a model with no reasoning effort has to clear a stored one, and a merged patch would strand it for the next session to fail on. A storage failure is logged without undoing the switch, which already applies to its own session, and a deployment with no settings provider keeps the entry with the switch staying process-local.
 
@@ -24,6 +24,16 @@ The stored route is not validated against the registry. A default naming a route
 
 `ApiProxyDefaults` changed shape, updating ~40 test construction sites. `host.describe` now reports the live default rather than a captured one, which is what it always meant. `settings.yaml` gains an `api-gateway:` section the moment a user switches models; the `api-gateway` namespace is deliberately NOT added to the gateway's exposed-namespace allowlist, so the Settings page neither reads nor writes it — the model picker is its editor.
 
+## Follow-up: blocking a session that cannot send
+
+A default naming a route the Models page has since removed leaves the composer saying "Select model" while the input still accepts a message, which then fails inside the adapter mid-turn. Two changes close it.
+
+The Host refuses. `session.prompt` checks whether an adapter serves the session's route and answers `model-unavailable` before opening a turn. This is the enforcement boundary: a client that disables its composer is an affordance, and the method stays callable regardless.
+
+The composer goes inert. `session.models` reports `routable`, and ui-model pushes a block through the new `ctx.conversation.blocks` registry; the bar renders the same disabled textarea it already renders without a workspace, with the blocker's own localized reason as the placeholder. The push direction is forced — ui-model already depends on ui-conversation, so ui-conversation cannot read it back.
+
+The gate is `routable`, NOT "the current target matches no advertised group". Catalog membership is advisory by design: a route serving a model it stopped advertising is absent from the groups yet perfectly usable, and blocking there would break a supported configuration (a narrowed `models` list over a live route). `routable` is also three-valued on the client — `null` before the first load or after a failed one never blocks, so a slow or unreachable Host cannot lock a working composer.
+
 ## Alternatives considered
 
 - **Falling back to the composition entry when the stored route is unregistered.** Rejected: the composer would then name the shipped DeepSeek model instead of prompting, which is both a silent switch to a provider the user did not pick and the opposite of the requested behavior.
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
index 6ead561b92..c356656778 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决定
 
-`ApiProxyService` 把自己的 `{provider, model, reasoningEffort?}` 切片注册为 `api-gateway` 设置段：组合条目是 `base` 层，`settings.yaml` 把用户的选择叠加其上。`workspaceRoot` 留在段外——它是启动器事实，不是偏好。段 schema 从 `static Config` 里挑出来而不是重述一遍，因为配置目录生成器是静态读取那个字面量的，展开语法会让它失败。
+`ApiProxyService` 把自己的 `{provider, model, reasoningEffort?}` 切片注册为 `api-gateway` 设置段：组合条目是 `base` 层，`settings.yaml` 把用户的选择叠加其上。`workspaceRoot` 留在段外——它是启动器事实，不是偏好。`reasoningEffort` 则是镜像的一例：它在段里、但**不在**插件配置里，因为 seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键。组合层设的推理等级因此会在此后每一次切到不支持推理的模型时继续存活——正是整段 `replace` 想要杜绝的那种滞留。何况推理等级本就是按模型的事实，它的部署级默认值属于适配器 profile，那里是按模型解析的。
 
 `session.selectModel` 把被接受的切换记录为新的默认值。没有另一个单独的手势：在输入框切模型**就是**选定默认值的方式。写入用 `replace` 而非 `update`——切到一个不支持推理的模型必须清掉已存的等级，而合并补丁会把它滞留下来，让下一个会话在它上面失败。存储失败只记日志，不撤销这次切换（它对自己所在的会话已经生效）；没有设置提供方的部署保留组合条目，切换只停留在进程内。
 
@@ -24,6 +24,16 @@ Status: implemented
 
 `ApiProxyDefaults` 形状变了，约 40 处测试构造点随之更新。`host.describe` 现在报告的是活的默认值而非捕获的快照，这本就是它一直想表达的含义。用户一旦切换模型，`settings.yaml` 就会多出一个 `api-gateway:` 段；`api-gateway` 这个 namespace 刻意**没有**加进网关的暴露名单，因此设置页既不读也不写它——模型选择器就是它的编辑器。
 
+## 后续：让发不出消息的会话禁止输入
+
+默认值指向一条模型页已删除的路由时，编辑器显示「选择模型」，输入框却仍接受消息，然后这一轮在适配器内部失败。两处改动关掉这个口子。
+
+宿主拒绝。`session.prompt` 检查是否有适配器服务该会话的路由，在开启轮次之前就以 `model-unavailable` 应答。这是执行边界：客户端禁用编辑器只是提示性设计，这个方法始终可被调用。
+
+编辑器变惰性。`session.models` 报告 `routable`，ui-model 经新的 `ctx.conversation.blocks` 注册表推送一个 block；输入栏渲染的仍是它在没有 Workspace 时就会渲染的那个禁用 textarea，只是把抬起方自己的本地化理由作为 placeholder。推送方向是被迫的——ui-model 本就依赖 ui-conversation，因此 ui-conversation 读不回去。
+
+闸门是 `routable`，**不是**「当前目标匹配不到任何已公布分组」。目录成员关系按设计是咨询性的：一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用，在那里阻断会破坏一种受支持的配置（对一条活着的路由收窄 `models` 列表）。`routable` 在客户端还是三值的——首次加载之前或加载失败之后的 `null` 绝不阻断，因此慢的或够不着的宿主锁不死一个本来能用的编辑器。
+
 ## 考虑过的替代方案
 
 - **存下来的路由未注册时回落到组合条目。** 否决：那样输入框会显示出厂的 DeepSeek 模型而不是提示选择，既是静默切到用户没选的提供方，也与要求的行为正好相反。
diff --git a/apps/web/tests/default-model.e2e.ts b/apps/web/tests/default-model.e2e.ts
index 0ba81e3ca0..9ff6198c3a 100644
--- a/apps/web/tests/default-model.e2e.ts
+++ b/apps/web/tests/default-model.e2e.ts
@@ -4,11 +4,14 @@
 // a route keeps deriving from its own log — the tier order the gateway
 // resolves on every read.
 // Zero model calls: the switch is settings/llm-domain traffic only, so there
-// is no fixture and a stray stream would fail loud on the open seam. A second
-// route is declared host-side (not through the UI, which has its own
-// scenario) purely so the picker has somewhere to switch to: the keyless
-// replay catalog publishes a single model.
+// is no fixture and a stray stream would fail loud on the open seam. Both
+// routes are declared host-side (not through the UI, which has its own
+// scenario) through the pi-ai adapter the shipped tree already mounts: a
+// fixture-less scaffold registers no adapter at all, so the routes the
+// picker offers — and the one the composer must start on — have to come from
+// somewhere, and settings profiles are the product's own way to add them.
 import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
@@ -18,7 +21,13 @@ import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { launchWebScaffold, watchConsole, type WebScaffold } from './scaffold.ts'
 import { ZH_BROWSER_LOCALE, connectFreshWorkspaceZh, saveFailureShot } from './support.ts'
 
-/** The route declared for this scenario, and the model the switch lands on. */
+/** Points the shipped `api-gateway` default at this scenario's own route. */
+const OVERLAY = fileURLToPath(new URL('./default-model.overlay.yml', import.meta.url))
+
+/** The route this scenario starts on, patched over the shipped default. */
+const START_ROUTE = 'origin-gateway'
+const START_MODEL = 'origin-large'
+/** The route the switch lands on, which then becomes the saved default. */
 const ROUTE = 'acme-gateway'
 const MODEL = 'acme-large'
 
@@ -49,12 +58,19 @@ describe('web e2e: the composer model switch is the default for later sessions',
   }
 
   beforeAll(async () => {
-    scaffold = await launchWebScaffold({})
-    // A second route so the picker has two models. Declared through the
-    // settings seam rather than the Models page: this scenario is about the
-    // composer, and the declaring flow is covered by models-settings.e2e.
+    scaffold = await launchWebScaffold({ extraOverlayPath: OVERLAY })
+    // Two routes so the picker has somewhere to start and somewhere to go.
+    // Declared through the settings seam rather than the Models page: this
+    // scenario is about the composer, and the declaring flow is covered by
+    // models-settings.e2e.
     await scaffold.ctx.settings.update(settingsNamespace('llm-pi-ai'), {
       providers: {
+        [START_ROUTE]: {
+          displayName: 'Origin Gateway',
+          api: 'openai-completions',
+          baseURL: 'https://gateway.origin.example/v1',
+          models: [{ id: START_MODEL, name: 'Origin Large' }],
+        },
         [ROUTE]: {
           displayName: 'Acme Gateway',
           api: 'openai-completions',
@@ -84,7 +100,7 @@ describe('web e2e: the composer model switch is the default for later sessions',
     // leaves behind: its own logged route.
     const loggedId = await createSession('default-model-logged')
     scaffold.ctx.sessions.get(SessionId(loggedId))?.append('request/header', {
-      header: { config: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } },
+      header: { config: { provider: START_ROUTE, model: START_MODEL } },
       reason: 'initial',
     })
 
@@ -108,8 +124,35 @@ describe('web e2e: the composer model switch is the default for later sessions',
     expect(await currentOf(await createSession('default-model-after')))
       .toEqual({ provider: ROUTE, model: MODEL })
     // ...while the one holding a logged route keeps deriving from its log.
-    expect(await currentOf(loggedId))
-      .toEqual({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    expect(await currentOf(loggedId)).toEqual({ provider: START_ROUTE, model: START_MODEL })
+    expect(tripwire.pageErrors).toEqual([])
+  }, 60_000)
+
+  it('goes inert when the route the default names stops being served', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-default-model-blocked'))
+    const box = page.locator('textarea[data-input-phase], textarea').first()
+    await expect.poll(async () => box.isEnabled(), { timeout: 10_000 }).toBe(true)
+
+    // What removing the provider on the Models page leaves behind: the saved
+    // default still names the route, and nothing serves it any more.
+    // `replace`, not `update`: a merge patch of `{providers: {}}` leaves every
+    // stored profile in place.
+    await scaffold.ctx.settings.replace(settingsNamespace('llm-pi-ai'), { providers: {} })
+
+    await expect.poll(async () => box.isEnabled(), { timeout: 15_000 }).toBe(false)
+    expect(await box.getAttribute('placeholder')).toBe('当前模型不可用，请先选择模型')
+
+    // The block is an affordance; the refusal is the Host's. A client that
+    // never disabled anything still cannot start a turn on a dead route.
+    const refused = await scaffold.ctx.apiProxy.sessions.prompt({
+      rpcId: 'default-model-refused' as never,
+      payload: {
+        sessionId: SessionId(await createSession('default-model-refusal')),
+        mode: 'queue' as const,
+        content: [{ type: 'text' as const, text: 'hi' }],
+      },
+    })
+    expect(refused.result).toMatchObject({ ok: false, error: { code: 'model-unavailable' } })
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 })
diff --git a/apps/web/tests/default-model.overlay.yml b/apps/web/tests/default-model.overlay.yml
new file mode 100644
index 0000000000..540e4891d6
--- /dev/null
+++ b/apps/web/tests/default-model.overlay.yml
@@ -0,0 +1,8 @@
+# The fixture-less web scaffold registers no adapter, so the shipped
+# deepseek-official default would be a route nothing serves — which the
+# composer now correctly refuses to type into. This scenario declares its own
+# pi-ai routes and starts the default on one of them.
+- id: api-gateway
+  config:
+    provider: origin-gateway
+    model: origin-large
diff --git a/apps/web/tests/message-actions.e2e.ts b/apps/web/tests/message-actions.e2e.ts
index 6149a66df1..6c4f450529 100644
--- a/apps/web/tests/message-actions.e2e.ts
+++ b/apps/web/tests/message-actions.e2e.ts
@@ -126,7 +126,7 @@ describe('web e2e: message IconActions and clocks on settled history', () => {
 
   it.skipIf(MODE === 'record')('matches the conversation aria golden with IconActions and clocks', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-message-actions-aria'))
-    await page.getByRole('button', { name: 'Select model', exact: true })
+    await page.getByRole('button', { name: /^Select model, current/ })
       .waitFor({ timeout: 10_000 })
     // Keep a footer focused so opacity-hidden actions stay in the a11y tree
     // as an active/focused control during the capture.
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index c84b25a332..1db06f59ef 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -45,6 +45,10 @@ import {
   WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE, WELCOME_NOTICE_VERSION,
 } from '@deepseek-ai/dsh-client-ui-settings-general'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type {
+  LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk,
+} from '@deepseek-ai/dsh-llm'
 import type { ReplayHandle } from '@deepseek-ai/dsh-llm-replay'
 import { installLlmReplay, parseSessionLog } from '@deepseek-ai/dsh-llm-replay'
 import SessionStore, {
@@ -93,6 +97,46 @@ const REPLAY_PROVIDERS = [{
   models: [{ id: 'deepseek-v4-flash', name: 'DeepSeek-V4-Flash', contextWindow: 128_000 }],
 }]
 
+/**
+ * The routes a shipped composition always has, with no ability to stream.
+ * A fixture-less keyless scenario issues no model calls, but its tree must
+ * still answer `listProviders()` — surfaces legitimately gate on whether any
+ * adapter serves a session's route, and an empty registry is a test artifact,
+ * not a product state.
+ */
+class RouteOnlyAdapter extends LlmAdapter {
+  constructor(private readonly providers: typeof REPLAY_PROVIDERS) {
+    super()
+  }
+
+  override providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: this.providers.find(entry => entry.id === provider)?.name ?? provider }
+  }
+
+  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
+    return Promise.resolve((this.providers.find(entry => entry.id === provider)?.models ?? [])
+      .map(model => ({ provider, id: model.id, name: model.name })))
+  }
+
+  override resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo> {
+    const listed = this.providers.find(entry => entry.id === provider)?.models
+      .find(entry => entry.id === model)
+    return Promise.resolve({
+      provider,
+      id: model,
+      name: listed?.name ?? model,
+      ...listed?.contextWindow === undefined ? {} : { contextWindow: listed.contextWindow },
+    })
+  }
+
+  override async *stream(): AsyncIterable<StreamChunk> {
+    throw new Error(
+      'web e2e scaffold: a model call was issued by a scenario that declared no replay fixture'
+      + ' — pass replayFixture, or keep the scenario free of model calls',
+    )
+  }
+}
+
 function replayProviders(contextWindow: number | undefined): typeof REPLAY_PROVIDERS {
   if (contextWindow === undefined) return REPLAY_PROVIDERS
   return REPLAY_PROVIDERS.map(provider => ({
@@ -390,6 +434,16 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
         ...(options.replayChildFixtures === undefined ? {} : { childFiles: options.replayChildFixtures }),
         ...(options.paceMs === undefined ? {} : { paceMs: options.paceMs }),
       })
+    } else if (mode !== 'record' && options.deepSeekMissingCredential !== true) {
+      // No fixture and no shipped adapter would leave the tree with ZERO
+      // provider routes — a state no product composition has, and one the
+      // composer now correctly refuses to type into. Register the same routes
+      // a fixture would, with streaming that still fails loud: the scenario
+      // issues no model calls, and one that slipped in must not pass quietly.
+      ctx.effect(() => ctx.llm.registerAdapter(
+        replayProviders(options.replayContextWindow).map(provider => provider.id),
+        new RouteOnlyAdapter(replayProviders(options.replayContextWindow)),
+      ), 'web e2e scaffold: route-only adapter')
     }
   } catch (error) {
     if (process.cwd() !== originalCwd) process.chdir(originalCwd)
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index f9ef1055d1..799503ef1c 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -280,10 +280,10 @@ describe('web e2e: seeded history renders through cold resume', () => {
 
   it.skipIf(MODE === 'record')('matches the historical conversation aria golden', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-seeded-aria'))
-    // This scenario deliberately leaves the LLM seam open to prove zero
-    // model calls. History still restores the routed id, but without an
-    // advertised catalog row the selector prompts for a listed replacement.
-    await page.getByRole('button', { name: 'Select model', exact: true })
+    // This scenario issues zero model calls — the scaffold's route-only
+    // adapter serves the catalog and refuses to stream — so history restores
+    // the routed id and the seat resolves it against an advertised row.
+    await page.getByRole('button', { name: /^Select model, current/ })
       .waitFor({ timeout: 10_000 })
     const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
       .split(SEED_ID).join('{{seededId}}')
diff --git a/apps/web/tests/snapshots/bash-abort-row/ui.expected.md b/apps/web/tests/snapshots/bash-abort-row/ui.expected.md
index d626830553..94b8bf80e9 100644
--- a/apps/web/tests/snapshots/bash-abort-row/ui.expected.md
+++ b/apps/web/tests/snapshots/bash-abort-row/ui.expected.md
@@ -23,8 +23,8 @@
 - button "Commands":
   - img
 - 'button "Access mode, current: Workspace Write"': Workspace Write
-- button "Select model":
-  - text: Select model
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
 - text: 1 turns · 1 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 10 tok · Output 10 tok
diff --git a/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md
index 6b4d7633e5..968083919a 100644
--- a/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md
+++ b/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md
@@ -30,8 +30,8 @@
   - img
 - 'button "Access mode, current: Workspace Write"': Workspace Write
 - button "Plan mode on, press to turn off": Plan
-- button "Select model":
-  - text: Select model
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
 - text: Details
diff --git a/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md b/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md
index 5a182175ee..dd566c17d5 100644
--- a/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md
+++ b/apps/web/tests/snapshots/markdown-cjk-strong/ui.expected.md
@@ -42,8 +42,8 @@
 - button "Commands":
   - img
 - 'button "Access mode, current: Workspace Write"': Workspace Write
-- button "Select model":
-  - text: Select model
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
 - text: 1 turns · 1 steps LLM {{duration}} Input 0 tok · Output 0 tok
diff --git a/apps/web/tests/snapshots/markdown-images/ui.expected.md b/apps/web/tests/snapshots/markdown-images/ui.expected.md
index b7d39d5ac0..21e84e000d 100644
--- a/apps/web/tests/snapshots/markdown-images/ui.expected.md
+++ b/apps/web/tests/snapshots/markdown-images/ui.expected.md
@@ -21,8 +21,8 @@
 - button "Commands":
   - img
 - 'button "Access mode, current: Workspace Write"': Workspace Write
-- button "Select model":
-  - text: Select model
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
 - text: 1 turns · 1 steps LLM {{duration}} Input 0 tok · Output 0 tok
diff --git a/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md b/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md
index cc255cf0b0..221294ad6b 100644
--- a/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md
+++ b/apps/web/tests/snapshots/markdown-inline-code-links/ui.expected.md
@@ -33,8 +33,8 @@
 - button "Commands":
   - img
 - 'button "Access mode, current: Workspace Write"': Workspace Write
-- button "Select model":
-  - text: Select model
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
 - text: 1 turns · 1 steps LLM {{duration}} Input 0 tok · Output 0 tok
diff --git a/apps/web/tests/snapshots/math-rendering/ui.expected.md b/apps/web/tests/snapshots/math-rendering/ui.expected.md
index 18bc3b791f..4880d108e0 100644
--- a/apps/web/tests/snapshots/math-rendering/ui.expected.md
+++ b/apps/web/tests/snapshots/math-rendering/ui.expected.md
@@ -37,8 +37,8 @@
 - button "Commands":
   - img
 - 'button "Access mode, current: Workspace Write"': Workspace Write
-- button "Select model":
-  - text: Select model
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
 - text: 1 turns · 1 steps LLM {{duration}} Input 0 tok · Output 0 tok
diff --git a/apps/web/tests/snapshots/message-actions/ui.expected.md b/apps/web/tests/snapshots/message-actions/ui.expected.md
index 0adabf54d8..38430d636e 100644
--- a/apps/web/tests/snapshots/message-actions/ui.expected.md
+++ b/apps/web/tests/snapshots/message-actions/ui.expected.md
@@ -45,8 +45,8 @@
 - button "Commands":
   - img
 - 'button "Access mode, current: Workspace Write"': Workspace Write
-- button "Select model":
-  - text: Select model
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
 - text: 2 turns · 3 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 7.8K tok · Output 103 tok
diff --git a/apps/web/tests/snapshots/seeded-history/command-row.expected.md b/apps/web/tests/snapshots/seeded-history/command-row.expected.md
index 6e8d1eb0f7..fe58587913 100644
--- a/apps/web/tests/snapshots/seeded-history/command-row.expected.md
+++ b/apps/web/tests/snapshots/seeded-history/command-row.expected.md
@@ -44,8 +44,8 @@
 - button "Commands":
   - img
 - 'button "Access mode, current: Read Only"': Read Only
-- button "Select model":
-  - text: Select model
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
 - text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 15.8K tok · Output 135 tok
diff --git a/apps/web/tests/snapshots/seeded-history/ui.expected.md b/apps/web/tests/snapshots/seeded-history/ui.expected.md
index d0ce89bc90..ce2921eac2 100644
--- a/apps/web/tests/snapshots/seeded-history/ui.expected.md
+++ b/apps/web/tests/snapshots/seeded-history/ui.expected.md
@@ -42,8 +42,8 @@
 - button "Commands":
   - img
 - 'button "Access mode, current: Workspace Write"': Workspace Write
-- button "Select model":
-  - text: Select model
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
 - text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 98% Input 15.8K tok · Output 135 tok
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 7842c1a477..97b4f8fb8d 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -577,28 +577,29 @@ Source: [`packages/hooks/hooks-codex/src/index.ts:44`](../packages/hooks/hooks-c
 Requires: `agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
 
 ```ts config-catalog
-/** Gateway plugin config: host-level agent routing and Workspace creation root. */
-export interface Config extends DefaultRouteSettings {
-  /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
-  workspaceRoot?: string
-}
-
 /**
- * The user-settable slice of the gateway config: the route a session starts
- * from when its own log names none. `workspaceRoot` is deliberately not part
- * of it — that is a launcher fact, not a preference.
+ * Gateway plugin config: host-level agent routing and Workspace creation root.
+ *
+ * `reasoningEffort` is deliberately absent, so the section carries one field
+ * the composition cannot. The seam resolves a section by MERGING the user
+ * layer over the composition entry per field, and an absent key cannot
+ * override a present one — so a composition-set effort would survive every
+ * later switch to a model that has none, and strand it for the next session
+ * to fail on. Effort is a per-model fact anyway: a deployment default belongs
+ * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
+ * which resolves per model rather than per gateway.
  */
-export interface DefaultRouteSettings {
+export interface Config {
   /** Default provider route for created agents. */
   provider: string
   /** Default model id. */
   model: string
-  /** Default reasoning effort; absence preserves the adapter/provider default. */
-  reasoningEffort?: string
+  /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
+  workspaceRoot?: string
 }
 ```
 
-Source: [`packages/host/apiproxy/src/index.ts:64`](../packages/host/apiproxy/src/index.ts)
+Source: [`packages/host/apiproxy/src/index.ts:67`](../packages/host/apiproxy/src/index.ts)
 
 ## `@deepseek-ai/dsh-host-directory-picker-browse`
 
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 9559b5e198..59b8ff9313 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -1975,6 +1975,9 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       models: request => ok(request, {
         current: modelTargets.get(request.payload.sessionId)
           ?? { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+        // The fixture's routes all serve; a surface exercising the blocked
+        // posture drives it through its own stub.
+        routable: true,
         groups: fixtureModelGroups(),
         failures: [],
       }),
diff --git a/packages/client/connection/tests/fake-api.ts b/packages/client/connection/tests/fake-api.ts
index e5eb42695d..cc1062843e 100644
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -59,6 +59,7 @@ export class FakeApiClient implements IApiClient {
 
   onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
     current: { provider: 'deepseek-official', model: 'deepseek-chat' },
+    routable: true,
     groups: [],
     failures: [],
   }))
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
index e50574d102..b6f2884837 100644
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -73,6 +73,7 @@ export class FakeApiClient implements IApiClient {
 
   onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
     current: this.defaultModel,
+    routable: true,
     groups: [{
       id: 'deepseek-official',
       name: 'DeepSeek',
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index f5ad20c3fc..3af7b2fd75 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: a75f25d8669cd688795842a655106e0e27bb7173
-README.zh.md: f0d744c31020730857d210d75749b907dbffca08
+README.md: 392f9956b33df88a5e9664a58de27d85fc0457d1
+README.zh.md: 6b0429a302475f84a7ce9b1cdc9fd47d90d6dba3
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index a75f25d866..392f9956b3 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -8,6 +8,8 @@ Compaction renders as one collapsed row at the checkpoint's flow position withou
 
 The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
 
+Another plugin can make one session's composer inert through `ctx.conversation.blocks`: it sets a block carrying its own localized reason, and the bar renders the same disabled textarea with that reason as the placeholder — the no-workspace posture, reused. The push direction is the constraint, not a preference: the plugins that know a session cannot send (ui-model, when no adapter serves its route) already depend on this package, so this package cannot read them. A block is an affordance only; the Host refuses a prompt it cannot route regardless of what any client disables. The no-workspace state wins when both hold, because picking a workspace is the earlier prerequisite.
+
 The view ring is a slot: the strict session-body registration declares the session-scoped `'conversation.view'` list in its `children` table, that body renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from registration options (`id`/`order`/`label`). The chat view is this package's own entry; plugins such as ui-trajectory contribute tabs through `ctx.slots.register`, and each view owns its chrome.
 
 Approvals take over the composer through the chain this package declares: `ApprovalPanel` registers as a selector-routed `'conversation.composer'` entry (the ui-question pattern) and occupies the composer in place of the InputBar while an approval wait is pending (amber strip, justification headline, paired command line from the running call's args, one-shot refuse/allow). The `PendingApproval` domain face in `contract/slots.ts` owns the wire encoding — the `ApprovalResponsePayload` value with the audit correlation — over the runtime's `PendingWait` carrier; the broadcast `approval/resolved` frame settles the wait and restores the composer. The runtime manager projects every approval or question wait through `SessionSummary.pendingInteraction`, including sessions never instantiated; `ui-workspace` owns its sidebar presentation. Pending waits leave the message flow entirely: questions (ui-question) and approvals (ApprovalPanel) both answer through the composer takeover, so no display-only placeholder card remains. The composer's bottom-row Access seat mounts `PermissionSelect`, fed by the host-computed `permissions` projection through the standard-kit `useProjection` (key absence hides the chip); the chip opens a Menu-primitive dropdown whose kebab-case preset names render as title-case labels. Safe preset picks submit `/permission <preset>` immediately through the bar's injected `command` callback, while `danger-full-access` is presented as `Full access` and first opens an in-page Modal risk confirmation. The enabling action stays disabled until the user checks the acknowledgement; cancel, Escape, close, and mask click submit nothing.
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index f0d744c310..6b0429a302 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -8,6 +8,8 @@
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
+别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的 prompt。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
+
 视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 6bc9068cfc..78dc94fbfa 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -15,6 +15,8 @@ import { resolveToolPath } from './contract/tool-call-model.ts'
 import { createChatStore } from './stores.ts'
 import { ConversationService } from './service.ts'
 import type { IConversation } from './service.ts'
+import { ComposerBlockRegistry } from './input/blocks.ts'
+import type { ComposerBlock } from './input/blocks.ts'
 import { InputHub } from './input/hub.ts'
 import { ComposerSubmissionPolicy } from './input/submission-policy.ts'
 import { InputBar } from './skeleton/InputBar.tsx'
@@ -54,6 +56,11 @@ const ABSENT_NOTICES = {
   getSnapshot: (): InputNotice | null => null,
   subscribe: () => () => {},
 }
+/** No session, therefore nothing to block; same one-identity rule as above. */
+const ABSENT_BLOCK = {
+  getSnapshot: (): ComposerBlock | undefined => undefined,
+  subscribe: () => () => {},
+}
 const EMPTY_LEXICON: ReadonlyMap<'/' | '@', readonly string[]> = new Map()
 const ABSENT_LEXICON = {
   getSnapshot: () => EMPTY_LEXICON,
@@ -133,6 +140,12 @@ export function apply(ctx: Context): void {
   // ctx.conversation.input by the service below sharing this one instance).
   const inputHub = new InputHub(ctx)
 
+  // The composer-block registry: a plugin that knows a session cannot send —
+  // ui-model, when no adapter serves the session's route — raises a block
+  // here, and the bar reads its own session's store. It cannot flow the other
+  // way: this package must not import the plugins that would know.
+  const composerBlocks = new ComposerBlockRegistry()
+
   // Decision 19/20: the input machine feeds every session-scope slot
   // component through the standard provide channel — the 'input' hook plus
   // the two public actions. Materialization is the shell creation trigger
@@ -167,6 +180,7 @@ export function apply(ctx: Context): void {
       'conversation.hero.workspace': { kind: 'single', scope: 'root' },
     },
     inject: (sessionId: SessionId | undefined): ConversationInjected => ({
+      hooks: { composerBlock: sessionId === undefined ? ABSENT_BLOCK : composerBlocks.storeFor(sessionId) },
       selectWorkspace: async (workspaceId) => {
         const nextId = await workspaces.connectWorkspace(workspaceId)
         if (sessionId !== undefined && nextId !== sessionId) {
@@ -351,7 +365,7 @@ export function apply(ctx: Context): void {
   // registers itself as `conversation` and lives on its own child fiber.
   // Presentation registrants depend directly on their slot declarations;
   // this service remains only where conversation actions are required.
-  ctx.plugin(ConversationService, { input: inputHub })
+  ctx.plugin(ConversationService, { input: inputHub, blocks: composerBlocks })
 
   // The bash sample rides the same declaration seam, in third-party posture
   // (ToolRow-matching Bash · {description} chrome).
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index a84b4a3bf0..4c3a1546c9 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -5,6 +5,7 @@ import type {
 } from '@deepseek-ai/dsh-client-ui-slots'
 import type { CommandNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { ComposerBlock } from '../input/blocks.ts'
 import type { ComposerKeyboard, EditSelection, InputActions, InputNotice, InputState } from '../input/contract.ts'
 import type { createChatStore } from '../stores.ts'
 import type { ComposerSubmitGesture, InputSubmitMode } from './composer-submission.ts'
@@ -223,6 +224,12 @@ export interface ConversationInjected {
    * When a blank session is already current, carry its draft to the target.
    */
   selectWorkspace: (workspaceId: WorkspaceId) => Promise<void>
+  /**
+   * Framework-bound sources. `composerBlock` is this session's block when a
+   * plugin raised one; the reason is the blocker's own localized copy, which
+   * the root renders as the inert composer's placeholder.
+   */
+  hooks: { composerBlock: ObservableSnapshot<ComposerBlock | undefined> }
 }
 
 /** Business callbacks injected into the strict Session body seat. */
@@ -356,7 +363,7 @@ export type ConversationSlotProps =
     | 'conversation.input.left' | 'conversation.input.right'
     | 'conversation.hero.workspace'
   >
-  & ConversationInjected
+  & InjectFace<ConversationInjected>
   & PropsLocale<'conversation'>
 
 /** Full strict-session body props: per-session store, view ring, and draft mirror. */
diff --git a/packages/client/ui-conversation/src/client/input/blocks.ts b/packages/client/ui-conversation/src/client/input/blocks.ts
new file mode 100644
index 0000000000..3d30f54094
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/input/blocks.ts
@@ -0,0 +1,77 @@
+/**
+ * Composer blocks: the one way another plugin stops a session's input.
+ *
+ * The composer cannot read the plugins that would know — the dependency runs
+ * ui-model → ui-conversation, never back — so a blocker pushes here and the
+ * bar reads its own session's store. A block carries the localized reason it
+ * exists, because the plugin that raised it owns that copy; the composer only
+ * knows how to render an inert textarea with a placeholder, exactly as it
+ * already does for a session with no workspace.
+ *
+ * This is an affordance, not enforcement: the Host refuses a prompt it cannot
+ * route regardless of what any client disables.
+ */
+
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Why one session's composer is inert. */
+export interface ComposerBlock {
+  /**
+   * Localized placeholder replacing the composer's own, owned by the plugin
+   * that raised the block.
+   */
+  readonly reason: string
+}
+
+/** The registry face other plugins reach through `ctx.conversation.blocks`. */
+export interface ComposerBlocks {
+  /**
+   * Raise or clear this session's block. Idempotent: setting a block equal to
+   * the current one, or clearing an absent one, notifies nobody.
+   * @param sessionId - the session whose composer is affected.
+   * @param block - the block to raise, or undefined to clear it.
+   */
+  set(sessionId: SessionId, block: ComposerBlock | undefined): void
+  /**
+   * The store the composer subscribes to for one session. Created on first
+   * read from either side, so a blocker may raise a block before the session's
+   * composer mounts and the composer still sees it.
+   * @param sessionId - the session to observe.
+   * @returns that session's block store (undefined value = not blocked).
+   */
+  storeFor(sessionId: SessionId): SnapshotStore<ComposerBlock | undefined>
+  /**
+   * Drop one session's store. The session scope's disposer calls this; a
+   * blocker never needs to.
+   * @param sessionId - the session being torn down.
+   */
+  forget(sessionId: SessionId): void
+}
+
+/** The per-session composer-block registry (one instance per plugin fiber). */
+export class ComposerBlockRegistry implements ComposerBlocks {
+  private readonly stores = new Map<SessionId, SnapshotStore<ComposerBlock | undefined>>()
+
+  /** @inheritdoc */
+  set(sessionId: SessionId, block: ComposerBlock | undefined): void {
+    const store = this.storeFor(sessionId)
+    const current = store.getSnapshot()
+    if (current?.reason === block?.reason) return
+    store.set(block)
+  }
+
+  /** @inheritdoc */
+  storeFor(sessionId: SessionId): SnapshotStore<ComposerBlock | undefined> {
+    const existing = this.stores.get(sessionId)
+    if (existing !== undefined) return existing
+    const created = createSnapshotStore<ComposerBlock | undefined>(undefined)
+    this.stores.set(sessionId, created)
+    return created
+  }
+
+  /** @inheritdoc */
+  forget(sessionId: SessionId): void {
+    this.stores.delete(sessionId)
+  }
+}
diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts
index decca00e01..be088d61ef 100644
--- a/packages/client/ui-conversation/src/client/service.ts
+++ b/packages/client/ui-conversation/src/client/service.ts
@@ -14,6 +14,7 @@ import type { Context } from 'cordis'
 // method) instead of the standalone helper.
 import type { ISessions, SessionFace, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { QueueAction, QueueItemId } from './contract/queue.ts'
+import type { ComposerBlocks } from './input/blocks.ts'
 import type { InputService } from './input/contract.ts'
 
 /**
@@ -24,6 +25,11 @@ import type { InputService } from './input/contract.ts'
 export interface IConversation {
   /** The per-session input machine registry (InputService face). */
   readonly input: InputService
+  /**
+   * The per-session composer-block registry: how a plugin the composer
+   * cannot import makes a session's input inert with its own reason.
+   */
+  readonly blocks: ComposerBlocks
   /**
    * Send a prompt into the caller scope's session (queued turn).
    * @param text - prompt text, sent verbatim as one text block.
@@ -53,16 +59,20 @@ export interface IConversation {
 export class ConversationService extends Service implements IConversation {
   /** The per-session input machine registry (InputService face, design §5.2). */
   readonly input: InputService
+  /** The per-session composer-block registry. */
+  readonly blocks: ComposerBlocks
 
   /**
    * @param ctx - owning root context (the plugin apply context; the service
    * registers itself and follows that fiber's lifetime).
-   * @param config - carries the InputService instance constructed by the
-   * plugin apply (the same InputHub the slot inject factories close over).
+   * @param config - carries the InputService and composer-block registry
+   * constructed by the plugin apply (the same instances the slot inject
+   * factories close over).
    */
-  constructor(ctx: Context, config: { input: InputService }) {
+  constructor(ctx: Context, config: { input: InputService; blocks: ComposerBlocks }) {
     super(ctx, 'conversation')
     this.input = config.input
+    this.blocks = config.blocks
   }
 
   /**
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
index bc5f7bdc01..377b4de3ec 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
@@ -13,7 +13,7 @@ import css from './ConversationRoot.module.css'
 export type ConversationRootProps = ConversationSlotProps
 
 export function ConversationRoot({
-  sessionId, useSession, useSessions, useWorkspaces, useInput,
+  sessionId, useSession, useSessions, useWorkspaces, useInput, useComposerBlock,
   renderSlot, renderSlotChain, selectWorkspace, t,
 }: ConversationRootProps) {
   const openState = useSession(s => s.openState)
@@ -24,6 +24,9 @@ export function ConversationRoot({
   const cwd = useSessions(s => sessionId === undefined ? undefined : s.byId[sessionId]?.cwd)
   const summaryBlank = useSessions(s => sessionId === undefined ? undefined : s.byId[sessionId]?.blank)
   const workspaces = useWorkspaces(s => s)
+  // A plugin this package cannot import (ui-model) says this session cannot
+  // send; its reason is already localized by whoever raised it.
+  const composerBlock = useComposerBlock(block => block)
 
   const [pickerOpen, setPickerOpen] = useState(false)
   const [pendingWorkspaceId, setPendingWorkspaceId] = useState<WorkspaceId | undefined>()
@@ -126,11 +129,17 @@ export function ConversationRoot({
   // bar is ONE session-maybe slot rendered unconditionally — inert is a prop,
   // not a different tree, so the textarea DOM survives the transition.
   const inert = sessionId === undefined || (hero && chipTitle === undefined)
+  // A raised block is the same inert posture with the blocker's own reason:
+  // one disabled textarea, never a second tree. The no-workspace state wins
+  // when both hold — picking a workspace is the earlier prerequisite.
+  const blocked = !inert && composerBlock !== undefined
   const inputBar = renderSlot('conversation.composer.bar', {
     variant: hero ? 'hero' : 'composer',
     ...(inert
       ? { disabled: true, placeholder: t('placeholder.workspace') }
-      : hero ? { placeholder: t('placeholder.hero') } : {}),
+      : blocked
+        ? { disabled: true, placeholder: composerBlock.reason }
+        : hero ? { placeholder: t('placeholder.hero') } : {}),
     overlay: renderSlot('conversation.input.overlay', {}),
     leftItems: zone === undefined ? null : renderSlot('conversation.input.left', zone),
     rightItems: zone === undefined ? null : renderSlot('conversation.input.right', zone),
diff --git a/packages/client/ui-conversation/tests/service-orchestration.spec.ts b/packages/client/ui-conversation/tests/service-orchestration.spec.ts
index ebd51f8408..0dd742a5fe 100644
--- a/packages/client/ui-conversation/tests/service-orchestration.spec.ts
+++ b/packages/client/ui-conversation/tests/service-orchestration.spec.ts
@@ -7,6 +7,7 @@ import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
 import { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { ComposerBlockRegistry } from '../src/client/input/blocks.ts'
 import { InputHub } from '../src/client/input/hub.ts'
 
 async function bench() {
@@ -23,6 +24,7 @@ async function bench() {
   // factories); the bench passes its own instance explicitly.
   const fiber = runtime.ctx.plugin(ConversationService, {
     input: new InputHub(runtime.ctx),
+    blocks: new ComposerBlockRegistry(),
   })
   await fiber.await()
   const root = runtime.ctx.get('conversation') as ConversationService
@@ -86,6 +88,7 @@ describe('ConversationService', () => {
     const bare = new Context()
     await bare.plugin(ConversationService, {
       input: new InputHub(bare),
+      blocks: new ComposerBlockRegistry(),
     }).await()
     const orphan = bare.get('conversation') as ConversationService
     await expect(orphan.send('x')).rejects.toThrow(/sessions service unavailable/)
diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx
index ba2e75f5f7..e0872f1539 100644
--- a/packages/client/ui-conversation/tests/skeleton.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx
@@ -91,6 +91,8 @@ function mount(
     omitSummaryRow?: boolean
     /** Classify the selected child as a subagent instead of an ordinary fork. */
     summaryOrigin?: 'subagent'
+    /** A composer block another plugin raised for this session. */
+    composerBlock?: { reason: string }
   } = {},
 ) {
   const root = sid('root')
@@ -224,6 +226,7 @@ function mount(
     useSessions: bindSnapshotSelector(sessions),
     useWorkspaces: bindSnapshotSelector(workspaces),
     useProjection: (() => undefined),
+    useComposerBlock: select => select(options.composerBlock),
     useInput,
     inputActions,
     renderSlot,
@@ -248,6 +251,31 @@ describe('Hero chrome', () => {
 })
 
 describe('ConversationRoot resident composer', () => {
+  it('renders the composer inert with the blocker\u2019s own reason', () => {
+    const b = mount(conversationSnapshot(), undefined, undefined, {
+      composerBlock: { reason: 'select a model first' },
+    })
+    const box = b.view.getByRole('textbox') as HTMLTextAreaElement
+    // One disabled textarea with the blocker's placeholder, never a second
+    // tree: the DOM survives the block being raised and cleared.
+    expect(box.disabled).toBe(true)
+    expect(box.placeholder).toBe('select a model first')
+    fireEvent.keyDown(box, { key: 'Enter' })
+    expect(b.sink).not.toHaveBeenCalled()
+  })
+
+  it('lets the no-workspace posture win over a block', () => {
+    // Picking a workspace is the earlier prerequisite; naming a model first
+    // would send the user somewhere they cannot act yet.
+    const b = mount(conversationSnapshot({ composerPhase: 'blank' }), [], undefined, {
+      summaryBlank: true,
+      composerBlock: { reason: 'select a model first' },
+    })
+    const box = b.view.getByRole('textbox') as HTMLTextAreaElement
+    expect(box.disabled).toBe(true)
+    expect(box.placeholder).not.toBe('select a model first')
+  })
+
   it('keeps composer text in the machine, mirrors to the chat store, and submits through the sink', () => {
     const b = mount(conversationSnapshot())
     const box = b.view.getByRole('textbox')
diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml
index 69ec84f418..25020ab686 100644
--- a/packages/client/ui-model/README.i18n.yaml
+++ b/packages/client/ui-model/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/client/ui-model/README.md
-README.md: 5f9fc65939eb747d916fa5609423d3186d1fefde
-README.zh.md: 3ed8db3095d96e48813cf5b15a206ebf4c894950
+README.md: 5a6f998476629566d35af32efa5d8bc5072a872b
+README.zh.md: 2bb22c55f1ae5af59f21e254804329d288806a90
diff --git a/packages/client/ui-model/README.md b/packages/client/ui-model/README.md
index 5f9fc65939..5a6f998476 100644
--- a/packages/client/ui-model/README.md
+++ b/packages/client/ui-model/README.md
@@ -6,6 +6,8 @@ Model selection plugin, browser half: TWO entries over ONE per-session directory
 
 The Host-reported provider/model/reasoning target is the single selection fact, but it is echoed only when the exact route remains in the advertised groups; removing that catalog row leaves the routable target intact while the trigger prompts `Select model`, no stale row is synthesized, and no Effort row is shown until the user picks an advertised model. Directory loads and selections share a generation counter so an older response never overwrites a newer one; a connection reset drops every resident projection and repulls the Host-restored target before display. Provider-local metadata failures list inline while usable groups stay selectable, and selection failures retain the prior target and directory.
 
+When the Host reports that no adapter serves the session's route (`session.models.routable`), this plugin raises a composer block through `ctx.conversation.blocks` and the input goes inert with this plugin's own copy; recovering clears it without a reload. It follows `routable` and nothing else: a `null` — before the first load, or after one failed — never blocks, or a slow Host would lock a working composer, and catalog membership never blocks either, because a route serving a model it stopped advertising is missing from the groups yet perfectly usable. The trigger's own `Select model` fallback still covers that case, which is display, not a gate.
+
 Directories are per-session, resolved lazily through `ctx.models.directoryFor(sessionId)`, and disposed with the session scope. Addressed subagent sessions expose neither entry, and their directory rejects loads, selections, and reconnect refreshes, because ordinary Agent-bound model RPCs would activate persisted child history outside the direct-parent continuation seam.
 
 The `/client` export surface is the plugin body (`apply`/`inject`), `ModelService`, `ModelDirectory` with its state shape, and the seat's injected face type.
diff --git a/packages/client/ui-model/README.zh.md b/packages/client/ui-model/README.zh.md
index 3ed8db3095..2bb22c55f1 100644
--- a/packages/client/ui-model/README.zh.md
+++ b/packages/client/ui-model/README.zh.md
@@ -6,6 +6,8 @@
 
 Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择事实，但只有当该精确路由仍在已公布分组中时才会回显；删除该目录行会保留仍可路由的目标，但触发器会提示 `Select model`，系统不会合成陈旧行，且在用户选择已公布的模型之前不会显示 Effort 行。目录加载与选择共享一个代次计数器，旧响应不会覆盖新结果；连接重置会丢弃所有常驻目录投影，并在显示前重新拉取 Host 恢复的目标。各提供方的元数据获取失败会内联列出，同时可用分组仍可选择；选择失败会保留先前的目标和目录。
 
+当宿主报告没有适配器服务该会话的路由（`session.models.routable`）时，本插件经 `ctx.conversation.blocks` 抬起一个编辑器 block，输入框随之变为惰性并显示本插件自己的文案；恢复后无需重新加载即自动清除。它只跟随 `routable`：`null`（首次加载之前，或加载失败之后）绝不阻断，否则一个慢的宿主就会锁死一个本来能用的编辑器；目录成员关系同样不阻断，因为一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用。触发器自己的 `Select model` 回退仍然覆盖那种情形——那是显示，不是闸门。
+
 目录按会话惰性解析（`ctx.models.directoryFor(sessionId)`），随会话作用域一并释放。已寻址 subagent 会话不公开任一入口，其目录会拒绝加载、选择与重新连接刷新，因为绑定到 agent（智能体）的普通模型 RPC 会在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
 `/client` 导出面为插件本体（`apply`/`inject`）、`ModelService`、`ModelDirectory` 及其状态形状、slot 注入面类型。
diff --git a/packages/client/ui-model/src/client/directory.ts b/packages/client/ui-model/src/client/directory.ts
index c98549bae8..8432cf1b77 100644
--- a/packages/client/ui-model/src/client/directory.ts
+++ b/packages/client/ui-model/src/client/directory.ts
@@ -15,6 +15,14 @@ import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 export interface ModelDirectoryState {
   /** Target the host reports for the next assembled step; null before the first load. */
   current: ModelTarget | null
+  /**
+   * Whether an adapter serves the current target's route, as the host reports
+   * it — null before the first load, which is NOT the same as blocked. Read
+   * this rather than "current matches no group": catalog membership is
+   * advisory, so a route serving a model it stopped advertising is missing
+   * from the groups yet perfectly usable.
+   */
+  routable: boolean | null
   /** Successfully loaded provider groups (last good load). */
   groups: readonly ModelProviderGroup[]
   /** Provider-local failures from the last load; usable groups stay usable. */
@@ -29,7 +37,7 @@ export interface ModelDirectoryState {
 export class ModelDirectory {
   /** The shared snapshot both entries render from (uSES-safe store). */
   readonly store: SnapshotStore<ModelDirectoryState> = createSnapshotStore<ModelDirectoryState>({
-    current: null, groups: [], failures: [], status: 'idle', error: null,
+    current: null, routable: null, groups: [], failures: [], status: 'idle', error: null,
   })
 
   /** Latest operation wins; an older response never overwrites a newer one. */
@@ -65,9 +73,10 @@ export class ModelDirectory {
       this.store.update((s) => { s.status = 'error'; s.error = `${result.error.code}: ${result.error.message}` })
       throw new Error(`session.models failed: ${result.error.code}: ${result.error.message}`)
     }
-    const { current, groups, failures } = result.value
+    const { current, routable, groups, failures } = result.value
     this.store.update((s) => {
       s.current = current
+      s.routable = routable
       s.groups = groups
       s.failures = failures
       s.status = 'ready'
@@ -102,7 +111,14 @@ export class ModelDirectory {
       this.store.update((s) => { s.status = 'error'; s.error = `${result.error.code}: ${result.error.message}` })
       throw new Error(`session.selectModel failed: ${result.error.code}: ${result.error.message}`)
     }
-    this.store.update((s) => { s.current = result.value.selected; s.status = 'ready'; s.error = null })
+    // The Host validated the route before accepting it, so a selection that
+    // landed is by construction one it can serve.
+    this.store.update((s) => {
+      s.current = result.value.selected
+      s.routable = true
+      s.status = 'ready'
+      s.error = null
+    })
   }
 
   /**
@@ -115,6 +131,7 @@ export class ModelDirectory {
     ++this.generation
     this.store.update((s) => {
       s.current = null
+      s.routable = null
       s.groups = []
       s.failures = []
       s.status = 'idle'
diff --git a/packages/client/ui-model/src/client/index.ts b/packages/client/ui-model/src/client/index.ts
index 0dde4778e1..68a82bd20a 100644
--- a/packages/client/ui-model/src/client/index.ts
+++ b/packages/client/ui-model/src/client/index.ts
@@ -105,14 +105,16 @@ export const inject = ['command', 'connection', 'locale', 'sessions', 'slots']
  * @param ctx - client root context.
  */
 export function apply(ctx: ClientContext): void {
-  ctx.plugin(ModelService)
-
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-model: dictionaries')
 
   // Non-slot faces (the command description, the popup option builder) read
   // through the bound translate; the seat component reads the standard seat.
   const t = ctx.locale.bind(NS)
 
+  // The composer-block reason is this plugin's own copy, read at raise time so
+  // a locale change reaches the next publish.
+  ctx.plugin(ModelService, { blockReason: () => t('blocked.composer') })
+
   // Entry 1: the /model popupSelect over the shared directory. The command
   // description is registry-held text: it reads t() once at registration and
   // refreshes only on re-registration, not on locale change.
diff --git a/packages/client/ui-model/src/client/locales.ts b/packages/client/ui-model/src/client/locales.ts
index f2b8bf1f01..2200eee56b 100644
--- a/packages/client/ui-model/src/client/locales.ts
+++ b/packages/client/ui-model/src/client/locales.ts
@@ -25,6 +25,7 @@ export const zh = {
   'action.reload': '重新加载',
   'warning.groupLoad': '{name} 加载失败：{message}',
   'empty.models': '没有可用的模型。',
+  'blocked.composer': '当前模型不可用，请先选择模型',
   'empty.efforts': '当前模型未提供推理等级。',
 } satisfies Record<string, string>
 
@@ -48,5 +49,6 @@ export const en = {
   'action.reload': 'Reload',
   'warning.groupLoad': '{name} failed to load: {message}',
   'empty.models': 'No models available.',
+  'blocked.composer': 'This model is unavailable — select one to continue',
   'empty.efforts': 'This model provides no reasoning effort levels.',
 } satisfies Record<ModelKey, string>
diff --git a/packages/client/ui-model/src/client/service.ts b/packages/client/ui-model/src/client/service.ts
index 5506bf13a5..c2a8741464 100644
--- a/packages/client/ui-model/src/client/service.ts
+++ b/packages/client/ui-model/src/client/service.ts
@@ -36,11 +36,16 @@ export class ModelService extends Service {
 
   private readonly live: LiveState = { directories: new Map() }
 
+  /** Localized composer-block copy; this plugin owns the string it raises. */
+  private readonly blockReason: () => string
+
   /**
    * @param ctx - owning root context (the service registers itself as `models`).
+   * @param config - the bound translator for this plugin's own dictionary.
    */
-  constructor(ctx: Context) {
+  constructor(ctx: Context, config: { blockReason: () => string }) {
     super(ctx, 'models')
+    this.blockReason = config.blockReason
     ctx.on('connection/reset', () => {
       for (const directory of this.live.directories.values()) directory.resetConnected()
     })
@@ -74,6 +79,27 @@ export class ModelService extends Service {
       () => sessions.subagentAddress(sessionId) === undefined,
     )
     live.directories.set(sessionId, directory)
+    // The composer cannot read this plugin (the dependency runs one way), so
+    // the block is pushed: the Host says whether an adapter serves the
+    // session's route, and only a definite `false` makes the input inert.
+    // `null` — before the first load, or after one failed — must not, or a
+    // slow or unreachable Host would lock a working composer.
+    const conversation = this.ctx.get('conversation')
+    if (conversation !== undefined) {
+      const publish = (): void => {
+        conversation.blocks.set(sessionId, directory.store.getSnapshot().routable === false
+          ? { reason: this.blockReason() }
+          : undefined)
+      }
+      publish()
+      actx.effect(() => {
+        const stop = directory.store.subscribe(publish)
+        return () => {
+          stop()
+          conversation.blocks.set(sessionId, undefined)
+        }
+      }, 'ui-model: composer block')
+    }
     actx.effect(() => () => {
       directory.dispose()
       live.directories.delete(sessionId)
diff --git a/packages/client/ui-model/tests/browser-plugin.spec.ts b/packages/client/ui-model/tests/browser-plugin.spec.ts
index 5f3ac64add..4fbeca5600 100644
--- a/packages/client/ui-model/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-model/tests/browser-plugin.spec.ts
@@ -17,6 +17,7 @@ import type { ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
 import type { CommandContribution, SelectOption } from '@deepseek-ai/dsh-client-ui-command/client'
 import type { ModelSelectInjected } from '../src/client/slots.ts'
 import { apply, inject } from '../src/client/index.ts'
+import { zh } from '../src/client/locales.ts'
 
 const sid = (k: string): SessionId => k as SessionId
 
@@ -59,7 +60,9 @@ async function bench() {
   ctx.provide('connection', { api: { sessions: {
     models: () => {
       calls.models += 1
-      return Promise.resolve({ result: { ok: true as const, value: { current, groups: GROUPS, failures: [] } } })
+      return Promise.resolve({
+        result: { ok: true as const, value: { current, routable, groups: GROUPS, failures: [] } },
+      })
     },
     selectModel: (payload: { provider: string; model: string; reasoningEffort?: string }) => {
       calls.select += 1
@@ -73,6 +76,15 @@ async function bench() {
       return Promise.resolve({ result: { ok: true as const, value: { selected: current } } })
     },
   } } })
+  // Whether the Host reports an adapter for the current route; the composer
+  // block follows this, never catalog membership.
+  let routable = true
+  const blocks = new Map<SessionId, { reason: string } | undefined>()
+  ctx.provide('conversation', {
+    blocks: {
+      set: (id: SessionId, block: { reason: string } | undefined) => { blocks.set(id, block) },
+    },
+  })
   let contribution: CommandContribution | undefined
   ctx.provide('command', {
     register(c: CommandContribution) {
@@ -115,6 +127,8 @@ async function bench() {
     hostCurrent: () => current,
     setHostCurrent: (target: ModelTarget) => { current = target },
     address: (id: SessionId) => { addressed.add(id) },
+    setRoutable: (next: boolean) => { routable = next },
+    blockOf: (key: string) => blocks.get(sid(key)),
   }
 }
 
@@ -217,6 +231,63 @@ describe('ui-model dual entry', () => {
     expect(face2.directory).not.toBe(face1.directory)
   })
 
+  it('blocks the composer only once the Host reports the route unservable', async () => {
+    const b = await bench()
+    b.mint('s1')
+    const face = b.seat().inject!(sid('s1'))
+
+    // Before the first load nothing is known. `null` is not `false`: a slow
+    // or unreachable Host must never lock a working composer.
+    expect(b.blockOf('s1')).toBeUndefined()
+    face.load()
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(b.blockOf('s1')).toBeUndefined()
+
+    b.setRoutable(false)
+    b.ctx.emit('models/changed')
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(b.blockOf('s1')?.reason).toBe(zh['blocked.composer'])
+
+    // Recovering clears it without a reload of the surface.
+    b.setRoutable(true)
+    b.ctx.emit('models/changed')
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(b.blockOf('s1')).toBeUndefined()
+  })
+
+  it('never blocks on catalog membership alone', async () => {
+    const b = await bench()
+    b.mint('s1')
+    const face = b.seat().inject!(sid('s1'))
+    // A model the route serves but no longer advertises: the seat prompts for
+    // a selection, the composer stays usable. Blocking here would break a
+    // supported configuration (a narrowed `models` list over a live route).
+    b.setHostCurrent({ provider: 'deepseek-official', model: 'unlisted' })
+    face.load()
+    await Promise.resolve()
+    await Promise.resolve()
+    const snapshot = face.directory.getSnapshot()
+    expect(snapshot.groups.flatMap(group => group.models.map(model => model.id))).not.toContain('unlisted')
+    expect(b.blockOf('s1')).toBeUndefined()
+  })
+
+  it('clears its block when the session scope goes', async () => {
+    const b = await bench()
+    const scope = b.mint('s1')
+    b.setRoutable(false)
+    const face = b.seat().inject!(sid('s1'))
+    face.load()
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(b.blockOf('s1')).toBeDefined()
+
+    await scope.fiber.dispose()
+    expect(b.blockOf('s1')).toBeUndefined()
+  })
+
   it('an unknown session fails loud at the seat inject', async () => {
     const b = await bench()
     expect(() => b.seat().inject!(sid('ghost'))).toThrow(/resolved no scope/)
diff --git a/packages/client/ui-model/tests/model-select.spec.tsx b/packages/client/ui-model/tests/model-select.spec.tsx
index 45df8ab38e..75a0622ed6 100644
--- a/packages/client/ui-model/tests/model-select.spec.tsx
+++ b/packages/client/ui-model/tests/model-select.spec.tsx
@@ -32,6 +32,7 @@ const reasoning = {
 function state(overrides: Partial<ModelDirectoryState> = {}): ModelDirectoryState {
   return {
     current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+    routable: true,
     groups: [{
       id: 'deepseek-official',
       name: 'DeepSeek',
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index 01bf1be683..21e32891eb 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/client/ui-models/README.md
-README.md: fdd27478be25d4352462c2db0fc7eead1d1aee77
-README.zh.md: c0fd66b003593e7a535e28751f1f6d0ee80dfac1
+README.md: fe8e9851978ebd900fa43eb28f52a5a803501b63
+README.zh.md: c11ec125c6bf896c32db74161a263ee2b73c88be
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index fdd27478be..fe8e985197 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -16,7 +16,7 @@ A pi-ai profile's `models` list is edited on the card: one row per model showing
 
 **Fetch available models** asks `llm.discoverModels` about the endpoint the form **currently shows**, including a base URL edited but not yet saved and a key typed but not yet stored, so adding a provider is one pass instead of save-then-return. The reply opens a picker rather than being written: candidates already configured start unchecked, so adopting a selection never overwrites a capacity the user corrected. A provider that cannot be interrogated is a detour, not a dead end — the adapter's own message appears beside the rows, which stay editable by hand.
 
-**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts. The card records the conventional `apiKeyEnv` reference only when a key is typed, the same rule the editor applies, so a route declared for provider-native authentication is not born pointing at a reference nothing will ever set. The card offers the same provider-level reasoning effort the editor card does for this namespace, from one shared control: both write the same profile field, so a route declared without it would have gained the setting only on being reopened.
+**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts. The card records the conventional `apiKeyEnv` reference only when a key is typed, the same rule the editor applies, so a route declared for provider-native authentication is not born pointing at a reference nothing will ever set. When the profile write lands but the key write fails, the provider already exists: the card settles the fields describing it, retries the credential alone — re-running the profile write would carry the revision that write just superseded, so the Host would answer `settings-conflict` and the key could never be stored from here — and reports the created provider even if the user then cancels. The card offers the same provider-level reasoning effort the editor card does for this namespace, from one shared control: both write the same profile field, so a route declared without it would have gained the setting only on being reopened.
 
 ## Model Experience
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index c0fd66b003..c11ec125c6 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -16,7 +16,7 @@ pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，
 
 **获取可用模型**会针对表单**当前显示**的端点调用 `llm.discoverModels`，包括已修改但尚未保存的 API 地址和已键入但尚未存储的密钥，因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路——适配器自己的消息会显示在各行旁边，而这些行仍可手工编辑。
 
-**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。这张卡片提供与编辑器卡片在该 namespace 下相同的提供方级推理等级，两者共用同一个控件：它们写的是同一个 profile 字段，若声明时没有它，这个设置就会等到重新打开编辑时才凭空出现。
+**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。这张卡片提供与编辑器卡片在该 namespace 下相同的提供方级推理等级，两者共用同一个控件：它们写的是同一个 profile 字段，若声明时没有它，这个设置就会等到重新打开编辑时才凭空出现。
 
 ## 模型体验
 
diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index ffdc57baf0..a83e2bb2fe 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -74,7 +74,15 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
   const [models, setModels] = useState<readonly ModelDraft[]>([])
   const [busy, setBusy] = useState(false)
   const [failure, setFailure] = useState<string | undefined>(undefined)
+  /**
+   * The profile write landed. Only the key write can still be outstanding, so
+   * the fields that describe the provider are settled and the retry path is
+   * the credential alone.
+   */
+  const [committed, setCommitted] = useState(false)
   const disabled = props.readOnly || busy
+  /** Everything but the key stops being editable once the provider exists. */
+  const profileDisabled = disabled || committed
 
   const routeInvalid = route.length > 0 && !ROUTE_PATTERN.test(route)
   const routeTaken = taken.includes(route)
@@ -98,34 +106,42 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
   /** Perform the create, returning a failure message or undefined. */
   const createOnce = async (): Promise<string | undefined> => {
     const keyRef = deriveKeyRef(route)
-    const storesKey = keyDraft.trim().length > 0
-    const profile = {
-      ...displayName.length === 0 ? {} : { displayName },
-      // The profile names the conventional reference only when this card is
-      // about to store a key, matching the editor: a route declared with the
-      // key left blank keeps its provider-native auth path (a credential
-      // chain, ADC) instead of resolving a reference nothing ever sets.
-      ...storesKey ? { apiKeyEnv: keyRef } : {},
-      api: protocol,
-      baseURL,
-      // Inherit is the field being absent, not an empty string: the schema
-      // types it as an effort name, and an empty one would fail the write.
-      ...effort === undefined ? {} : { [EFFORT_FIELD['pi-ai']]: effort },
-      models: models.map(model => ({ ...model })),
+    const normalizedKey = keyDraft.trim()
+    const storesKey = normalizedKey.length > 0
+    if (!committed) {
+      const profile = {
+        ...displayName.length === 0 ? {} : { displayName },
+        // The profile names the conventional reference only when this card is
+        // about to store a key, matching the editor: a route declared with the
+        // key left blank keeps its provider-native auth path (a credential
+        // chain, ADC) instead of resolving a reference nothing ever sets.
+        ...storesKey ? { apiKeyEnv: keyRef } : {},
+        api: protocol,
+        baseURL,
+        // Inherit is the field being absent, not an empty string: the schema
+        // types it as an effort name, and an empty one would fail the write.
+        ...effort === undefined ? {} : { [EFFORT_FIELD['pi-ai']]: effort },
+        models: models.map(model => ({ ...model })),
+      }
+      const response = await api.settings.mutate({
+        ns: NS,
+        ops: [{ op: 'set', path: ['providers', route], value: profile }],
+        // `taken` is a snapshot too, so the id check alone cannot see a route
+        // declared after this card opened; the revision makes that race a
+        // `settings-conflict` instead of a write over the other profile.
+        expectedRevision: openedAt,
+      })
+      if (!response.result.ok) return response.result.error.message
+      // The provider now exists. A retry after the key write below fails must
+      // not re-run this mutate: the revision it holds is the one this write
+      // just superseded, so the Host would answer `settings-conflict` and the
+      // key could never be stored from this card at all.
+      setCommitted(true)
     }
-    const response = await api.settings.mutate({
-      ns: NS,
-      ops: [{ op: 'set', path: ['providers', route], value: profile }],
-      // `taken` is a snapshot too, so the id check alone cannot see a route
-      // declared after this card opened; the revision makes that race a
-      // `settings-conflict` instead of a write over the other profile.
-      expectedRevision: openedAt,
-    })
-    if (!response.result.ok) return response.result.error.message
     if (storesKey) {
-      const stored = await api.credentials.set({ ref: keyRef, value: keyDraft })
+      const stored = await api.credentials.set({ ref: keyRef, value: normalizedKey })
       // The profile landed; saying the key did not is the only honest report,
-      // and the row is now editable so the key can be entered again there.
+      // and the retry above now goes straight back to this write.
       if (!stored.result.ok) return stored.result.error.message
     }
     return undefined
@@ -163,7 +179,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           value={route}
           placeholder="acme-gateway"
           aria-label={t('customRoute')}
-          disabled={disabled}
+          disabled={profileDisabled}
           onChange={(event) => { setRoute(event.target.value) }}
         />
       </div>
@@ -178,7 +194,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           value={displayName}
           placeholder={route.length === 0 ? t('customDisplayName') : route}
           aria-label={t('customDisplayName')}
-          disabled={disabled}
+          disabled={profileDisabled}
           onChange={(event) => { setDisplayName(event.target.value) }}
         />
       </div>
@@ -190,7 +206,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           value={baseURL}
           placeholder="https://gateway.example/v1"
           aria-label={t('baseUrl')}
-          disabled={disabled}
+          disabled={profileDisabled}
           onChange={(event) => { setBaseURL(event.target.value) }}
         />
       </div>
@@ -200,7 +216,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           className={styles['input']}
           value={protocol}
           aria-label={t('customApi')}
-          disabled={disabled}
+          disabled={profileDisabled}
           onChange={(event) => { setProtocol(event.target.value) }}
         >
           {protocols.map(choice => <option key={choice} value={choice}>{choice}</option>)}
@@ -226,7 +242,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
         value={effort ?? ''}
         onChange={setEffort}
         t={t}
-        disabled={disabled}
+        disabled={profileDisabled}
       />
       <ModelListEditor
         models={models}
@@ -239,7 +255,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
         }}
         api={api}
         t={t}
-        disabled={disabled}
+        disabled={profileDisabled}
       />
       {failure !== undefined ? <p className={styles['error']}>{failure}</p> : null}
       {/* Only the gates with something to say render; the route-id gate has its
@@ -251,7 +267,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
         submitDisabled={disabled || !ready}
         submitLabel="create"
         submitBusyLabel="creating"
-        onCancel={() => { props.onClose(false) }}
+        onCancel={() => { props.onClose(committed) }}
         onSubmit={() => { void create() }}
       />
     </div>
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 67def367bc..5d359c2476 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -650,8 +650,11 @@ describe('provider rows', () => {
 })
 
 describe('hand-declared providers', () => {
-  function mountCard(overrides: Partial<Parameters<typeof CustomProviderCard>[0]> = {}) {
-    const scripted = scriptedFace()
+  function mountCard(
+    overrides: Partial<Parameters<typeof CustomProviderCard>[0]> = {},
+    wire: Parameters<typeof scriptedFace>[0] = {},
+  ) {
+    const scripted = scriptedFace(wire)
     const onClose = vi.fn()
     render(
       <CustomProviderCard
@@ -736,6 +739,60 @@ describe('hand-declared providers', () => {
     expect(firstMutate(second.mutate).ops[0]).not.toHaveProperty('value.reasoning')
   })
 
+  it('retries only the key after the profile landed, and reports the provider on cancel', async () => {
+    const set = vi.fn()
+      .mockResolvedValueOnce(fail('credential store is read-only', 'credential-rejected'))
+      .mockResolvedValueOnce(ok({}))
+    const { mutate, onClose } = mountCard({}, { set })
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: '  gw-key  ' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
+    fireEvent.click(screen.getByText(en.create))
+
+    // The profile landed; only the key failed. The card says so and stays open.
+    await waitFor(() => { expect(screen.getByText('credential store is read-only')).toBeTruthy() })
+    expect(onClose).not.toHaveBeenCalled()
+    expect(mutate).toHaveBeenCalledTimes(1)
+    // The key is stored trimmed, matching the editor.
+    expect(set).toHaveBeenNthCalledWith(1, { ref: 'ACME_API_KEY', value: 'gw-key' })
+
+    // The provider exists now, so the fields describing it are settled and
+    // only the key can still be corrected.
+    expect(screen.getByLabelText<HTMLInputElement>(en.customRoute).disabled).toBe(true)
+    expect(screen.getByLabelText<HTMLInputElement>(en.baseUrl).disabled).toBe(true)
+    expect(screen.getByLabelText<HTMLInputElement>(en.keyInput).disabled).toBe(false)
+
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'gw-key-2' } })
+    fireEvent.click(screen.getByText(en.create))
+    await waitFor(() => { expect(onClose).toHaveBeenCalledWith(true) })
+    // Re-running the profile write would carry the revision this card's own
+    // first write superseded, so the Host would answer settings-conflict and
+    // the key could never be stored from here at all.
+    expect(mutate).toHaveBeenCalledTimes(1)
+    expect(set).toHaveBeenNthCalledWith(2, { ref: 'ACME_API_KEY', value: 'gw-key-2' })
+  })
+
+  it('reports the created provider when cancelled after its profile landed', async () => {
+    const set = vi.fn().mockResolvedValue(fail('nope', 'credential-rejected'))
+    const { onClose } = mountCard({}, { set })
+
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'gw-key' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
+    fireEvent.click(screen.getByText(en.create))
+    await waitFor(() => { expect(screen.getByText('nope')).toBeTruthy() })
+
+    // Walking away leaves a real provider behind; reporting no change would
+    // leave the page without the row it now has.
+    fireEvent.click(screen.getByText(en.cancel))
+    expect(onClose).toHaveBeenCalledWith(true)
+  })
+
   it('names the blocked gate under the form, and nothing once it is satisfied', () => {
     mountCard()
     fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index a5e9fd2aef..cc4fff8e24 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 38f18995f2982db2c5a48971d7d044448e5adc8c
-README.zh.md: c444ed6b7485b6ddca059c5edf7f30828bd96ab7
+README.md: 9e01423a36803477cb07d944e058fc388b5e72fd
+README.zh.md: d4df79d7d8850c466f1ccc4c53097a15739013ea
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 38f18995f2..9e01423a36 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -10,7 +10,9 @@ The API gateway every client shape shares: the TS contract (`src/api/`, zero Nod
 
 A session resolves its route from three tiers, re-read on every access rather than seeded once: a selection made in this process, else the session's own latest logged `request/header`, else this default. Re-reading is what makes both directions hold — a session that has run a turn derives its route from its log forever after, so changing the default never retargets it, while a session still blank (New Session reuses one rather than minting another) starts from a default saved after it was created.
 
-`session.selectModel` records an accepted switch as the new default, which is how the default is chosen in practice: there is no separate gesture. The write replaces the section wholesale rather than merging, because switching to a model with no reasoning effort has to clear a stored one; a storage failure is logged without undoing the switch, which already applies to its own session. A deployment with no settings provider keeps the composition entry and a switch stays process-local.
+`session.selectModel` records an accepted switch as the new default, which is how the default is chosen in practice: there is no separate gesture. What it stores is the RESOLVED target, so an adapter-materialized default effort is pinned as the user saw it and a later adapter-default change does not silently move stored defaults. The write replaces the section wholesale rather than merging, because switching to a model with no reasoning effort has to clear a stored one; a storage failure is logged without undoing the switch, which already applies to its own session. A deployment with no settings provider keeps the composition entry and a switch stays process-local.
+
+The section's `reasoningEffort` has no counterpart in the plugin config, deliberately: the seam merges the user layer over the composition entry per field, so an absent key cannot override a present one and a composition-set effort would survive every later switch to a model without one. A deployment default for effort belongs on the adapter profile, which resolves per model.
 
 The stored route is not validated against the registry, in either direction. A default naming a route the Models page has since removed still reaches `session.models` as the session's `current` — matching no advertised group, which is precisely what makes a selector prompt for a replacement instead of naming a model the deployment cannot reach. Repairing it silently would also break the deliberate converse: an adapter may serve a model its catalog does not advertise.
 
@@ -30,7 +32,7 @@ Session titles ride the generic projection pair like every other domain — the
 
 `session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged provider/model/reasoning target, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale.
 
-Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target separately from provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. The current target may be absent from the groups and is never injected as a synthetic row; clients can prompt for a replacement without turning the directory into a routing whitelist. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`.
+Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target separately from provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. The current target may be absent from the groups and is never injected as a synthetic row; clients can prompt for a replacement without turning the directory into a routing whitelist. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`. `session.models` additionally reports `routable`: whether an adapter currently serves the current target's route, which is deliberately NOT derivable from the groups — a route serving a model it stopped advertising is absent from them yet perfectly usable, while a route whose adapter is gone can serve nothing. `session.prompt` refuses on that same fact with `model-unavailable` rather than spending the pre-step path to fail inside an adapter; a client that disables its composer is an affordance, and this method stays callable regardless.
 
 Pending queued input is a live control-plane contract, not conversation history. The gateway derives the complete `next-turn` queue from durable `agent/inbox/spliced` mutations and broadcasts authoritative `session/queue` snapshots after each change and on reconnect; pending `next-step` steering stays outside this Web projection. Within `next-step`, user-origin messages carry the `steering` placement while injected context (approval notices, task completion, attached snapshots) carries `context` and is not surfaced until claimed. The message-local `agent/inbox/inserted`, `claimed`, and `discarded` notifications remain available to lifecycle observers but do not build the queue view. `session.updateQueue` addresses one `MessageId`; edit and remove mutate the attached Agent through `Inbox.splice()`. A claim's pure deletion splice wins races before pre-step admission, so a later operation returns `queue-item-not-found`. `session.cancel` aborts only the active turn and preserves pending inbox work; after cancellation reaches quiescence and the closing turn flushes, AgentLoop claims the next waking message in FIFO order, and the browser never resends or promotes it. Queue operations never resume a cold session, and the client never infers retirement from turn or status events.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index c444ed6b74..d4df79d7d8 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -10,7 +10,9 @@
 
 会话按三级解析自己的路由，且每次读取都重新解析，而不是只在创建时种一次：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是这个默认值。重新解析正是让两个方向都成立的原因——已经跑过一轮的会话此后永远从自己的日志推导路由，改默认值不会重定向它；而仍然空白的会话（新建会话会复用一个，而不是再开一个）则会用上它创建之后才保存的默认值。
 
-`session.selectModel` 会把被接受的切换记录为新的默认值，实践中默认值就是这样选定的，没有另一个单独的手势。写入是整段替换而非合并，因为切到一个不支持推理的模型必须清掉已存的等级；存储失败只记日志，不会撤销这次切换——它对自己所在的会话已经生效。没有设置提供方的部署保留组合条目，切换只停留在进程内。
+`session.selectModel` 会把被接受的切换记录为新的默认值，实践中默认值就是这样选定的，没有另一个单独的手势。它存下来的是**解析后**的目标，因此适配器实体化出来的默认推理等级会按用户当时看到的样子钉住，日后适配器改了自己的默认值也不会悄悄移动已存的默认路由。写入是整段替换而非合并，因为切到一个不支持推理的模型必须清掉已存的等级；存储失败只记日志，不会撤销这次切换——它对自己所在的会话已经生效。没有设置提供方的部署保留组合条目，切换只停留在进程内。
+
+设置段里的 `reasoningEffort` 在插件配置中刻意没有对应字段：seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键，因此组合层设的推理等级会在此后每一次切到不支持推理的模型时继续存活。推理等级的部署级默认值属于适配器 profile，那里是按模型解析的。
 
 存下来的路由不做注册表校验，两个方向都不做。默认值指向一个已在模型页删除的路由时，它照样作为会话的 `current` 送到 `session.models`——匹配不到任何已公布的分组，而这恰恰是让选择器提示重新选择、而不是显示一个部署根本够不着的模型的原因。静默修复它还会破坏刻意保留的反面情形：适配器可以服务一个自己目录未公布的模型。
 
@@ -30,7 +32,7 @@
 
 `session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的提供方／模型／推理（reasoning）目标及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。
 
-会话模型路由属于会话领域契约。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。
+会话模型路由属于会话领域契约。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。`session.models` 还会报告 `routable`：当前目标的路由是否有适配器在服务。这一点刻意不由分组推导——一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用；而适配器已经消失的路由什么都服务不了。`session.prompt` 依据同一个事实以 `model-unavailable` 拒绝，而不是把整条 pre-step 路径走完再在适配器内部失败；客户端禁用输入框只是提示性设计，这个方法始终可被调用。
 
 待处理的 queued 输入属于实时控制平面契约，而非对话历史。网关根据持久 `agent/inbox/spliced` 变更派生完整的 `next-turn` 队列，并在每次变更后及重连时广播权威 `session/queue` 快照；待处理的 `next-step` steering（中途引导）不进入此 Web 投影。在 `next-step` 内，用户来源的消息携带 `steering` placement，而注入上下文（审批通知、任务完成、附加快照）携带 `context`，领取前不对外呈现。面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知仍供生命周期观察方使用，但不用于构建队列视图。`session.updateQueue` 通过 `MessageId` 寻址单个项；编辑和移除经已挂载 Agent 的 `Inbox.splice()` 修改队列。claim 的纯删除 splice 会在 pre-step 准入前赢得竞态，因此之后的操作返回 `queue-item-not-found`。`session.cancel` 仅中止活动轮次并保留待处理 inbox 工作；取消达到完全停稳且结束中的轮次完成 flush 后，AgentLoop 按 FIFO 顺序认领下一条可唤醒消息，浏览器绝不重发或提升它。队列操作绝不恢复冷会话，客户端也绝不根据轮次或状态事件推断某项已退出队列。
 
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index aaa2d68a44..2a54e2c113 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -74,6 +74,14 @@ import { openNativePath, openNativeTextFile } from './native-path-opener.ts'
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
 
+/**
+ * The settings namespace carrying the user's default route. Named for the
+ * gateway rather than for the package, because this key is what a person reads
+ * and writes in `settings.yaml`; the row id in a composition happens to match
+ * but does not determine it.
+ */
+export const API_GATEWAY_SETTINGS_NAMESPACE = settingsNamespace('api-gateway')
+
 /** Non-model settings namespaces intentionally served to the Web client. */
 const WEB_SETTINGS_NAMESPACES = ['permission'] as const
 
@@ -337,9 +345,11 @@ export interface ApiProxyDefaults {
    */
   defaultTarget: () => AgentLlmTarget
   /**
-   * Record a selection as the new default. Absent when the deployment stores
-   * no user settings, in which case a switch stays process-local. A rejection
-   * is reported and swallowed: the switch already applies to its own session,
+   * Record a selection as the new default. Either absent, or a closure that
+   * may itself decline — the gateway plugin always passes one, and it no-ops
+   * when the deployment mounts no settings provider or when the write races
+   * service teardown. A switch then stays process-local. A rejection is
+   * reported and swallowed: the switch already applies to its own session,
    * and undoing it because storage failed would be the worse outcome.
    */
   persistDefaultTarget?: (target: AgentLlmTarget) => Promise<void>
@@ -1330,6 +1340,19 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     }
   }
 
+  /**
+   * Whether an adapter currently serves this route, and therefore whether a
+   * session pointed at it can start a turn. Catalog membership cannot answer
+   * it: an adapter may serve a model its own catalog stopped advertising, so
+   * a route missing from the groups is not the same as one nothing serves.
+   * A composition with no llm registry at all cannot judge and says yes —
+   * the dispatch it would have refused fails on its own terms.
+   */
+  function routeServed(provider: string): boolean {
+    const llm = ctx.get('llm')
+    return llm === undefined || llm.listProviders().some(entry => entry.id === provider)
+  }
+
   /** Missing-service report shared by the settings domain (skills-domain stance). */
   function settingsAbsent(): RpcError {
     return { code: 'internal', message: 'settings service is absent: this deployment does not mount a settings provider (e.g. @deepseek-ai/dsh-settings-local) in its composition', details: {} }
@@ -1700,7 +1723,8 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         if ('error' in found) return err(request, found.error)
         const current = targetFor(found.agent).current
         const { groups, failures } = await buildModelCatalog(ctx)
-        return ok(request, { current: { ...current }, groups, failures })
+        const routable = routeServed(current.provider)
+        return ok(request, { current: { ...current }, routable, groups, failures })
       },
 
       async selectModel(request) {
@@ -1868,6 +1892,20 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         const found = await agentFor(sessionId)
         if ('error' in found) return err(request, found.error)
         const agent = found.agent
+        // A route no adapter serves cannot start a turn, and letting it try
+        // spends the whole pre-step path to fail inside the adapter with a
+        // message about registration. Refusing here names the model the
+        // session is pointed at while the draft is still in the composer.
+        // This is the enforcement boundary: a client that disables its input
+        // is an affordance, and this method stays callable regardless.
+        const target = targetFor(agent).current
+        if (!routeServed(target.provider)) {
+          return err(request, {
+            code: 'model-unavailable',
+            message: `no adapter serves provider "${target.provider}"; select a model for this session`,
+            details: { provider: target.provider, model: target.model },
+          })
+        }
         // The rpcId rides MessageSource into user/message (merge declaration in api/sessions.ts; provisional correlation).
         const source: MessageSource = { kind: 'user', rpcId: request.rpcId }
         try {
@@ -2758,8 +2796,14 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             queue.push(frame({ type: 'host/settings-changed', ns: name }))
             // A provider's own settings carry its model catalog and endpoint,
             // so a change there invalidates the model list even when the route
-            // set is untouched — `llm/adapters-updated` alone misses it.
-            if (modelProviderNamespaces().has(name)) queue.push(frame({ type: 'host/models-changed' }))
+            // set is untouched — `llm/adapters-updated` alone misses it. The
+            // gateway's own section is the other such source: it names the
+            // route every session with no logged one resolves to, so an
+            // externally edited default (another tab, a hand-edited
+            // settings.yaml) has to reach an open selector too.
+            if (modelProviderNamespaces().has(name) || name === String(API_GATEWAY_SETTINGS_NAMESPACE)) {
+              queue.push(frame({ type: 'host/models-changed' }))
+            }
           }),
           ctx.on('credentials/updated', (ref) => {
             queue.push(frame({ type: 'host/credentials-changed', ref: String(ref) }))
diff --git a/packages/host/apiproxy/src/api/sessions.schema.ts b/packages/host/apiproxy/src/api/sessions.schema.ts
index 9f9c4329e6..80e64fb12a 100644
--- a/packages/host/apiproxy/src/api/sessions.schema.ts
+++ b/packages/host/apiproxy/src/api/sessions.schema.ts
@@ -225,6 +225,7 @@ export const sessionModelsRequestSchema = z.object({
 /** session.models response value. */
 export const sessionModelsValueSchema = z.object({
   current: modelTargetSchema,
+  routable: z.boolean(),
   groups: z.array(modelProviderGroupSchema),
   failures: z.array(modelCatalogFailureSchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.models'>>>
diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts
index 18315eef19..2e795928ec 100644
--- a/packages/host/apiproxy/src/api/sessions.ts
+++ b/packages/host/apiproxy/src/api/sessions.ts
@@ -117,6 +117,15 @@ export interface ModelCatalogFailure {
 export interface SessionModels {
   /** Target selected for the session's next assembled step. */
   current: ModelTarget
+  /**
+   * Whether an adapter currently serves `current.provider`, and therefore
+   * whether this session can start a turn at all. Deliberately NOT derivable
+   * from `groups`: catalog membership is advisory, so a route serving a model
+   * it stopped advertising is absent from the groups yet perfectly usable,
+   * while a route whose adapter is gone can serve nothing. A surface that
+   * blocks input must read this rather than the groups.
+   */
+  routable: boolean
   /** Successfully loaded provider groups. */
   groups: ModelProviderGroup[]
   /** Provider-local failures; successful groups remain usable. */
diff --git a/packages/host/apiproxy/src/index.ts b/packages/host/apiproxy/src/index.ts
index cb2f88f436..1a6e0be281 100644
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -19,16 +19,16 @@ import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import type { AgentLlmTarget } from '@deepseek-ai/dsh-agent'
 import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
-import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { installSettingsSection } from '@deepseek-ai/dsh-settings'
 import type { ApiProxy } from './api/index.ts'
-import { createApiProxy } from './api-proxy.ts'
+import { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from './api-proxy.ts'
 
 export type * from './api/index.ts'
 export { RpcId } from './api/rpc.ts'
 export { toFetchHandler } from './fetch/handler.ts'
 export { AbstractApiClient, InProcessApiClient } from './fetch/client.ts'
 export type { IApiClient } from './fetch/client.ts'
-export { createApiProxy } from './api-proxy.ts'
+export { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from './api-proxy.ts'
 export type { ApiProxyDefaults } from './api-proxy.ts'
 
 declare module 'cordis' {
@@ -39,17 +39,9 @@ declare module 'cordis' {
 }
 
 /**
- * The settings namespace carrying the user's default route. Named for the
- * gateway rather than for the package, because this key is what a person reads
- * and writes in `settings.yaml`; the row id in a composition happens to match
- * but does not determine it.
- */
-export const API_GATEWAY_SETTINGS_NAMESPACE = settingsNamespace('api-gateway')
-
-/**
- * The user-settable slice of the gateway config: the route a session starts
- * from when its own log names none. `workspaceRoot` is deliberately not part
- * of it — that is a launcher fact, not a preference.
+ * The `api-gateway` settings section: the route a session starts from when its
+ * own log names none. `workspaceRoot` is deliberately not part of it — that is
+ * a launcher fact, not a preference.
  */
 export interface DefaultRouteSettings {
   /** Default provider route for created agents. */
@@ -60,29 +52,36 @@ export interface DefaultRouteSettings {
   reasoningEffort?: string
 }
 
-/** Gateway plugin config: host-level agent routing and Workspace creation root. */
-export interface Config extends DefaultRouteSettings {
+/**
+ * Gateway plugin config: host-level agent routing and Workspace creation root.
+ *
+ * `reasoningEffort` is deliberately absent, so the section carries one field
+ * the composition cannot. The seam resolves a section by MERGING the user
+ * layer over the composition entry per field, and an absent key cannot
+ * override a present one — so a composition-set effort would survive every
+ * later switch to a model that has none, and strand it for the next session
+ * to fail on. Effort is a per-model fact anyway: a deployment default belongs
+ * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
+ * which resolves per model rather than per gateway.
+ */
+export interface Config {
+  /** Default provider route for created agents. */
+  provider: string
+  /** Default model id. */
+  model: string
   /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
   workspaceRoot?: string
 }
 
-/** The config fields the settings section carries; the rest stay launcher-owned. */
-const DEFAULT_ROUTE_FIELDS = ['provider', 'model', 'reasoningEffort'] as const
-
 /**
- * The settings section's schema, picked out of the plugin config rather than
- * restated. The config stays a plain literal because the configuration-catalog
- * generator reads it statically; picking from it is what keeps the section a
- * subset of it as both evolve.
- * @param config - the plugin config schema to pick from.
- * @returns the section schema over {@link DEFAULT_ROUTE_FIELDS}.
+ * Schema of the `api-gateway` section, exported because it IS that section's
+ * contract — the shape anything reading or writing `settings.yaml` addresses.
  */
-function defaultRouteSchema(config: z<Config>): z<DefaultRouteSettings> {
-  const fields = Object.fromEntries(
-    DEFAULT_ROUTE_FIELDS.map(field => [field, config.dict?.[field]]),
-  )
-  return z.object(fields) as z<DefaultRouteSettings>
-}
+export const DEFAULT_ROUTE_SCHEMA: z<DefaultRouteSettings> = z.object({
+  provider: z.string().required(),
+  model: z.string().required(),
+  reasoningEffort: z.string(),
+})
 
 /** Project the stored/composed section onto the agent-facing target shape. */
 function routeTarget(settings: DefaultRouteSettings): AgentLlmTarget {
@@ -109,7 +108,6 @@ export class ApiProxyService extends Service implements ApiProxy {
   static Config: z<Config> = z.object({
     provider: z.string().required(),
     model: z.string().required(),
-    reasoningEffort: z.string(),
     workspaceRoot: z.string(),
   })
 
@@ -132,13 +130,9 @@ export class ApiProxyService extends Service implements ApiProxy {
     // The composition entry is the shipped default; the settings section
     // layers the user's own choice over it, and a deployment without a
     // settings provider simply keeps the entry.
-    const entry: DefaultRouteSettings = {
-      provider: config.provider,
-      model: config.model,
-      ...config.reasoningEffort === undefined ? {} : { reasoningEffort: config.reasoningEffort },
-    }
+    const entry: DefaultRouteSettings = { provider: config.provider, model: config.model }
     let route: () => DefaultRouteSettings = () => entry
-    installSettingsSection(ctx, API_GATEWAY_SETTINGS_NAMESPACE, defaultRouteSchema(ApiProxyService.Config), entry, {
+    installSettingsSection(ctx, API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA, entry, {
       setSource: (current) => {
         route = current
       },
@@ -150,8 +144,10 @@ export class ApiProxyService extends Service implements ApiProxy {
       defaultTarget: () => routeTarget(route()),
       // Wholesale, never a merge: switching to a model with no reasoning
       // effort must clear a stored one, and a merged patch would strand it
-      // for the next session to fail on. The section holds no secrets, so
-      // there is nothing a replace can collaterally drop.
+      // for the next session to fail on. This clears it because the entry
+      // below the user layer carries no effort to re-inherit — the reason
+      // `Config` deliberately has no such field. The section holds no
+      // secrets, so there is nothing a replace can collaterally drop.
       persistDefaultTarget: async (target) => {
         await ctx.get('settings')?.replace(API_GATEWAY_SETTINGS_NAMESPACE, target)
       },
diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
index c13a66eaec..86a77f4af2 100644
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -22,7 +22,7 @@ import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepsee
 import type { HostFrame } from '../src/api/index.ts'
 import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
-import { createApiProxy } from '../src/api-proxy.ts'
+import { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from '../src/api-proxy.ts'
 
 const DEFAULTS = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
 
@@ -398,6 +398,25 @@ describe('settings domain', () => {
     expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'permission' }])
   })
 
+  it('invalidates the model catalog when the gateway default route changes', async () => {
+    const ctx = await harness()
+    const route = ctx.settings.register(API_GATEWAY_SETTINGS_NAMESPACE, z.object({
+      provider: z.string().required(),
+      model: z.string().required(),
+    }), { base: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } })
+    const api = createApiProxy(ctx, DEFAULTS)
+    // The gateway's own section names the route every session with no logged
+    // one resolves to, so an externally edited default — another tab, a
+    // hand-edited settings.yaml — has to reach an open selector as well.
+    const frames = await collectHost(api, ['host/settings-changed', 'host/models-changed'], 2, async () => {
+      await route.replace({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
+    })
+    expect(frames).toEqual([
+      { type: 'host/settings-changed', ns: 'api-gateway' },
+      { type: 'host/models-changed' },
+    ])
+  })
+
   it('maps a stale expectedRevision to settings-conflict carrying both revisions', async () => {
     const ctx = await harness()
     ctx.settings.register(NS, AdapterConfig)
diff --git a/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts b/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts
new file mode 100644
index 0000000000..996cea5da2
--- /dev/null
+++ b/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts
@@ -0,0 +1,108 @@
+/**
+ * The `api-gateway` settings section over a REAL settings provider: the
+ * composition entry as the base layer, the wholesale replace the gateway
+ * persists with, and the fallback when the provider detaches. The other model
+ * specs drive hand-rolled `defaultTarget`/`persistDefaultTarget` closures, so
+ * this is the only place the layering itself is exercised.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { Settings, installSettingsSection } from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import { API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA } from '../src/index.ts'
+import type { DefaultRouteSettings } from '../src/index.ts'
+
+/** The smallest real provider: one in-memory document, always writable. */
+class MemorySettings extends Settings {
+  doc: Record<string, unknown> = {}
+
+  get writable(): boolean {
+    return true
+  }
+
+  protected load(): Promise<Record<string, unknown>> {
+    return Promise.resolve(structuredClone(this.doc))
+  }
+
+  protected persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
+    this.doc = { ...this.doc, [ns]: structuredClone(section) }
+    return Promise.resolve()
+  }
+}
+
+/** Mount the gateway's own section wiring over a live provider. */
+async function boot(entry: DefaultRouteSettings) {
+  const ctx = new Context()
+  const fiber = ctx.plugin(MemorySettings)
+  await fiber.await()
+  let route: () => DefaultRouteSettings = () => entry
+  const consumer = ctx.plugin(function section(child: Context) {
+    installSettingsSection(child, API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA, entry, {
+      setSource: (current) => { route = current },
+      onChange: () => {},
+    })
+  })
+  await consumer.await()
+  const settings = ctx.get('settings')
+  if (settings === undefined) throw new Error('settings provider did not mount')
+  return { ctx, fiber, consumer, settings, read: () => route() }
+}
+
+describe('the api-gateway default-route section', () => {
+  it('resolves the composition entry until the user layer overrides it', async () => {
+    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+
+    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
+    })
+    expect(bench.read()).toEqual({
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
+    })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('clears a stored effort when the next switch has none', async () => {
+    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
+    })
+    expect(bench.read().reasoningEffort).toBe('high')
+
+    // The whole reason the gateway persists with `replace` rather than a merge
+    // patch — and the reason `Config` carries no effort for the base layer to
+    // re-inherit here. A stranded effort would fail the next session's first
+    // request against a model that does not support it.
+    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
+      provider: 'acme-gateway', model: 'acme-plain',
+    })
+    expect(bench.read()).toEqual({ provider: 'acme-gateway', model: 'acme-plain' })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('layers a hand-written partial section over the entry', async () => {
+    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    // Someone editing settings.yaml by hand may name only the model. The
+    // entry supplies the provider, which is what makes this legal — and is
+    // exactly why an effort in the entry could never be cleared, so there
+    // is none to inherit.
+    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, { model: 'deepseek-reasoner' })
+    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('falls back to the composition entry when the provider detaches', async () => {
+    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
+      provider: 'acme-gateway', model: 'acme-large',
+    })
+    expect(bench.read().provider).toBe('acme-gateway')
+
+    // A deployment that loses its settings provider keeps serving the route it
+    // was composed with rather than the one it can no longer read.
+    await bench.fiber.dispose()
+    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    await bench.ctx.fiber.dispose()
+  })
+})
diff --git a/packages/host/apiproxy/tests/api-proxy-models.spec.ts b/packages/host/apiproxy/tests/api-proxy-models.spec.ts
index 7a9f2b2f86..818260504c 100644
--- a/packages/host/apiproxy/tests/api-proxy-models.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-models.spec.ts
@@ -303,6 +303,37 @@ describe('Web session model selection', () => {
     await ctx.fiber.dispose()
   })
 
+  it('refuses a prompt no adapter can route, and reports it on the directory', async () => {
+    const { ctx, sessionId } = await harness()
+    const api = createApiProxy(ctx, {
+      defaultTarget: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
+      cwd: '/tmp',
+      workspaceRoot: '/tmp',
+    })
+
+    // The client disabling its input is an affordance; this method stays
+    // callable, so the refusal has to live here.
+    const refused = await api.sessions.prompt(request({
+      sessionId, mode: 'queue' as const, content: [{ type: 'text' as const, text: 'hi' }],
+    }))
+    expect(refused.result).toMatchObject({
+      ok: false,
+      error: { code: 'model-unavailable', details: { provider: 'deleted-gateway', model: 'deleted-model' } },
+    })
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).routable).toBe(false)
+
+    // An advisory-unlisted model on a live route is NOT this: the route
+    // serves it, so the prompt goes through and nothing blocks.
+    expectValue(await api.sessions.selectModel(request({
+      sessionId, provider: 'deepseek-official', model: 'unlisted-but-served',
+    })))
+    const catalog = expectValue(await api.sessions.models(request({ sessionId })))
+    expect(catalog.routable).toBe(true)
+    expect(catalog.groups.flatMap(group => group.models.map(model => model.id)))
+      .not.toContain('unlisted-but-served')
+    await ctx.fiber.dispose()
+  })
+
   it('serves a session and its catalog when the stored default names a route that is gone', async () => {
     const { ctx, sessionId } = await harness()
     const api = createApiProxy(ctx, {
diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts
index 490e0ad7f1..ebd56ee551 100644
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -45,6 +45,7 @@ function scriptedApi(overrides: {
       }),
       models: r => ok(r, {
         current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+        routable: true,
         groups: [],
         failures: [],
       }),
diff --git a/packages/host/apiproxy/tests/fetch-carrier.spec.ts b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
index bcccfdd52e..22e1650f5b 100644
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -64,6 +64,7 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
             ok: true,
             value: {
               current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+              routable: true,
               groups: [],
               failures: [],
             },
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
index 040fe56ff5..28f9138502 100644
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -197,6 +197,7 @@ describe('sessions domain schemas', () => {
     expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
     expect(sessionModelsValueSchema.parse({
       current: { provider: 'deepseek-official', model: 'deepseek-v4-flash', reasoningEffort: 'max' },
+      routable: true,
       groups: [{
         id: 'deepseek-official',
         name: 'DeepSeek',
@@ -274,8 +275,10 @@ describe('sessions domain schemas', () => {
 describe('host domain schemas', () => {
   it('validates describe request/value', () => {
     expect(hostDescribeRequestSchema.parse({})).toEqual({})
-    const value = hostDescribeValueSchema.parse({ version: '1', cwd: '/x', defaultTarget: () => ({ provider: 'p', model: 'm' }), attachedSessions: 2 })
-    expect(value.attachedSessions).toBe(2)
+    const value = hostDescribeValueSchema.parse({
+      version: '1', cwd: '/x', provider: 'p', model: 'm', attachedSessions: 2,
+    })
+    expect(value).toMatchObject({ provider: 'p', model: 'm', attachedSessions: 2 })
     expect(hostDescribeValueSchema.parse({ version: '1', cwd: '/x', attachedSessions: 0 }).provider).toBeUndefined()
   })
 

From 8e57dd1dac85be4430ff6a214f8951d875dfbbcd Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 16:15:10 +0800
Subject: [PATCH 102/516] fix(web): render Skill icon at 14px

---
 .../feature/2026-08-06-web-skill-tool-row.i18n.yaml           | 4 ++--
 .../implemented/feature/2026-08-06-web-skill-tool-row.md      | 2 +-
 .../implemented/feature/2026-08-06-web-skill-tool-row.zh.md   | 2 +-
 packages/client/ui-skill/README.i18n.yaml                     | 4 ++--
 packages/client/ui-skill/README.md                            | 2 +-
 packages/client/ui-skill/README.zh.md                         | 2 +-
 packages/client/ui-skill/src/client/SkillRow.tsx              | 2 +-
 packages/client/ui-skill/tests/skill-row.spec.tsx             | 2 +-
 8 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
index a9ee64e640..3be2c476e5 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.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 .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
-2026-08-06-web-skill-tool-row.md: 6583062f38b0e9cff059fa4477313ff6a5bdd2aa
-2026-08-06-web-skill-tool-row.zh.md: 3d5c4b712896c2cf41df3ec913c597f7f791486c
+2026-08-06-web-skill-tool-row.md: fcf5c3b5b61c94b0823fe54624c3dc906c520348
+2026-08-06-web-skill-tool-row.zh.md: bef36df44d97af3993c9760a6b6d3add7b7c932c
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
index 6583062f38..fcf5c3b5b6 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
@@ -12,7 +12,7 @@ The Web transcript renders `skill` calls through the generic fallback row, so a
 
 `ui-skill` registers a component under the existing `conversation.chat.toolview` keyed slot with key `skill`. The component owns its row chrome from the public `ToolRowProps` contract, matching the independent registrant posture used by the Bash sample instead of importing conversation-private components.
 
-The collapsed row uses a 16-pixel document-and-sparkle glyph and the Bash row's neutral hierarchy: tertiary glyph, secondary `Skill` title, caption separator, and tertiary skill name. Running, failed, and interrupted calls retain the transcript's shimmer, error dot and first-line summary, and warning dot semantics. A settled call expands through the whole summary row into a 260-pixel bounded `Instructions` card containing the exact durable result text; the existing trajectory `Inspect` handoff remains available below the card.
+The collapsed row uses a 14-pixel document-and-sparkle glyph and the Bash row's neutral hierarchy: tertiary glyph, secondary `Skill` title, caption separator, and tertiary skill name. Running, failed, and interrupted calls retain the transcript's shimmer, error dot and first-line summary, and warning dot semantics. A settled call expands through the whole summary row into a 260-pixel bounded `Instructions` card containing the exact durable result text; the existing trajectory `Inspect` handoff remains available below the card.
 
 The row derives every visible value from a paired call/result slice in the current runtime window. It reads the skill name from the recorded `name` argument and the instructions from durable result content, and never joins the current skill catalog for descriptions or provider metadata. If pagination leaves the call outside the window, the result has no tool identity and remains on the generic fallback rather than extending the history wire contract. The existing ACP `skill-load` recording is seeded through the real Web persistence and composition path for a keyless interaction and accessibility snapshot.
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
index 3d5c4b7128..bef36df44d 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
@@ -12,7 +12,7 @@ Web transcript（文本记录）通过通用后备行渲染 `skill` 调用，使
 
 `ui-skill` 在现有的 `conversation.chat.toolview` 键控 slot 下注册 key 为 `skill` 的组件。该组件基于公开的 `ToolRowProps` 契约自行实现行 chrome，沿用 Bash 示例的独立注册方姿态，而不导入 conversation 私有组件。
 
-收起的行使用 16 像素的文档与闪光组合图标，并沿用 Bash 行的中性色层级：图标采用三级色，`Skill` 标题采用二级色，分隔符采用 caption 色，skill 名称采用三级色。运行、失败和中断调用分别沿用 transcript 的扫光、错误状态点加首行摘要，以及警告状态点语义。已结算调用可以通过整个摘要行展开一个高度上限为 260 像素的 `Instructions` 卡片，其中原样呈现持久化结果文本；用于跳转至 trajectory 的现有 `Inspect` 入口仍保留在卡片下方。
+收起的行使用 14 像素的文档与闪光组合图标，并沿用 Bash 行的中性色层级：图标采用三级色，`Skill` 标题采用二级色，分隔符采用 caption 色，skill 名称采用三级色。运行、失败和中断调用分别沿用 transcript 的扫光、错误状态点加首行摘要，以及警告状态点语义。已结算调用可以通过整个摘要行展开一个高度上限为 260 像素的 `Instructions` 卡片，其中原样呈现持久化结果文本；用于跳转至 trajectory 的现有 `Inspect` 入口仍保留在卡片下方。
 
 该行的所有可见值均派生自当前 runtime 窗口中已配对的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。如果分页将调用留在窗口外，结果便没有工具身份，并继续使用通用后备路径，而不是扩展 history 协议契约。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
 
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index 57a1ff1676..ca4bc68ebf 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/client/ui-skill/README.md
-README.md: a9506fe563b94fb4d1f9afd882216e023b0c2d13
-README.zh.md: 6af5d3eb8820dacc2ab569be8b830481dd45fb9a
+README.md: f70bd2780f255cd8e0c64acb3da3863e10c4fa9d
+README.zh.md: 6eb6cbd3ae196a540e161a3a23f9df2136824f2e
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index a9506fe563..f70bd2780f 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -10,7 +10,7 @@ The `/client` export surface is the plugin body (`apply`/`inject`) only; the sou
 
 ## Skill tool row
 
-The browser plugin also registers a keyed `skill` toolview in `conversation.chat.toolview`. A collapsed row renders the 16-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from a paired call/result slice in the current runtime window, never from the current catalog, so replay remains stable when installed skills or their descriptions change.
+The browser plugin also registers a keyed `skill` toolview in `conversation.chat.toolview`. A collapsed row renders the 14-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from a paired call/result slice in the current runtime window, never from the current catalog, so replay remains stable when installed skills or their descriptions change.
 
 ## Model Experience
 
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 6af5d3eb88..6eb6cbd3ae 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -10,7 +10,7 @@ skill（技能）引用 source 的浏览器端：把 `/` 触发的 `skill` sourc
 
 ## skill 工具行
 
-浏览器插件还会把一个 key 为 `skill` 的 toolview 注册进 `conversation.chat.toolview`。收起的行以与 Bash 行相同的中性色层级显示 16 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自当前 runtime 窗口中已配对的调用／结果片段，绝不读取当前 skill 目录，因此即使已安装的 skill 或其描述发生变化，回放仍保持稳定。
+浏览器插件还会把一个 key 为 `skill` 的 toolview 注册进 `conversation.chat.toolview`。收起的行以与 Bash 行相同的中性色层级显示 14 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自当前 runtime 窗口中已配对的调用／结果片段，绝不读取当前 skill 目录，因此即使已安装的 skill 或其描述发生变化，回放仍保持稳定。
 
 ## 模型体验
 
diff --git a/packages/client/ui-skill/src/client/SkillRow.tsx b/packages/client/ui-skill/src/client/SkillRow.tsx
index 076da55d52..65b474825a 100644
--- a/packages/client/ui-skill/src/client/SkillRow.tsx
+++ b/packages/client/ui-skill/src/client/SkillRow.tsx
@@ -82,7 +82,7 @@ function leadingFor(state: SkillRowState): ReactNode {
   switch (state) {
     case 'error': return <StateDot state="error" />
     case 'stopped': return <StateDot state="warning" />
-    default: return <IconSkillOutline16 />
+    default: return <IconSkillOutline16 size={14} />
   }
 }
 
diff --git a/packages/client/ui-skill/tests/skill-row.spec.tsx b/packages/client/ui-skill/tests/skill-row.spec.tsx
index 4143b4a7a2..05b84ceda5 100644
--- a/packages/client/ui-skill/tests/skill-row.spec.tsx
+++ b/packages/client/ui-skill/tests/skill-row.spec.tsx
@@ -56,7 +56,7 @@ describe('SkillRow', () => {
     const row = screen.getByRole('button', { name: 'Skilldsh-manage-issues' })
     expect(row.getAttribute('aria-expanded')).toBe('false')
     expect(view.container.querySelector('[data-tool="skill"]')?.getAttribute('data-state')).toBe('ok')
-    expect(view.container.querySelector('[data-tool="skill"] svg')?.getAttribute('width')).toBe('16')
+    expect(view.container.querySelector('[data-tool="skill"] svg')?.getAttribute('width')).toBe('14')
     expect(screen.queryByLabelText('说明')).toBeNull()
 
     fireEvent.click(row)

From 5a90eb41fb1bc83417dc6de1573507b8b497dc25 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 16:45:50 +0800
Subject: [PATCH 103/516] fix(ui-models): three faults the running app surfaced
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**A hand-declared route must not offer a reasoning effort.** The earlier
commit read the create card's missing control as drift and added one. It
is the other way round: such a model has no reasoning capability — pi-ai's
installed catalog is what supplies one, and it ships nothing under the
route — so `resolveModel` throws UNSUPPORTED_REASONING_EFFORT for every
model on it and the whole provider drops out of the picker. Verified
against the adapter, not inferred. The create card no longer offers it and
the editor withholds it on the directory's `declared` bit, which is the
real bug: that control has always been wrong for these routes.

**A blocked composer locked the way out of the block.** Reusing the
no-workspace inert posture disabled the model seat along with everything
else, so the bar asked for a model while preventing the one control that
picks one. A block now rides its own `blocked` owner prop: the textarea,
send, commands, plan seat, and access chip all lock, and the model seat
alone stays live.

**A Provider ID could derive an illegal credential reference.** The card
accepted a digit-leading id, whose derived `123_API_KEY` then failed at
the credential seam with a raw regular expression the user cannot act on.
The id must now start with a letter, and a test pins the relation between
the two rules rather than the regex.
---
 ...default-model-follows-the-picker.i18n.yaml |  4 +-
 ...-08-07-default-model-follows-the-picker.md |  2 +-
 ...-07-default-model-follows-the-picker.zh.md |  2 +-
 apps/web/tests/default-model.e2e.ts           |  9 ++
 apps/web/tests/models-settings.e2e.ts         | 11 ++-
 .../client/ui-conversation/README.i18n.yaml   |  4 +-
 packages/client/ui-conversation/README.md     |  2 +-
 packages/client/ui-conversation/README.zh.md  |  2 +-
 .../src/client/contract/slots.ts              |  8 ++
 .../src/client/skeleton/ConversationRoot.tsx  |  5 +-
 .../src/client/skeleton/InputBar.tsx          | 12 ++-
 .../ui-conversation/tests/skeleton.spec.tsx   | 21 ++++-
 packages/client/ui-models/README.i18n.yaml    |  4 +-
 packages/client/ui-models/README.md           |  2 +-
 packages/client/ui-models/README.zh.md        |  2 +-
 .../src/client/CustomProviderCard.tsx         | 33 ++++----
 .../ui-models/src/client/ModelsSection.tsx    |  4 +
 .../ui-models/src/client/ProviderEditor.tsx   | 35 ++++++--
 .../src/client/ReasoningEffortField.tsx       | 17 ++--
 .../client/ui-models/src/client/locales.ts    |  8 +-
 .../ui-models/tests/provider-form.spec.tsx    | 83 ++++++++++++-------
 21 files changed, 179 insertions(+), 91 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
index 40eb59e98f..f513e90666 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.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 .agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
-2026-08-07-default-model-follows-the-picker.md: 4142b3aea6a807001831df62c2038ddf57bbd6ad
-2026-08-07-default-model-follows-the-picker.zh.md: c3566567781edac12cd9269d63f86528139c8796
+2026-08-07-default-model-follows-the-picker.md: d20f0ab8b8c8bd19f596e6ef73f0a58d96c24d38
+2026-08-07-default-model-follows-the-picker.zh.md: 0d2821cb63407fe766e6fe3d36de31d9fc6f1c13
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
index 4142b3aea6..d20f0ab8b8 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
@@ -30,7 +30,7 @@ A default naming a route the Models page has since removed leaves the composer s
 
 The Host refuses. `session.prompt` checks whether an adapter serves the session's route and answers `model-unavailable` before opening a turn. This is the enforcement boundary: a client that disables its composer is an affordance, and the method stays callable regardless.
 
-The composer goes inert. `session.models` reports `routable`, and ui-model pushes a block through the new `ctx.conversation.blocks` registry; the bar renders the same disabled textarea it already renders without a workspace, with the blocker's own localized reason as the placeholder. The push direction is forced — ui-model already depends on ui-conversation, so ui-conversation cannot read it back.
+The composer goes inert. `session.models` reports `routable`, and ui-model pushes a block through the new `ctx.conversation.blocks` registry; the bar renders the same disabled textarea it already renders without a workspace, with the blocker's own localized reason as the placeholder — except the model seat, which a block deliberately leaves live, because choosing a model is how the user clears it. The push direction is forced — ui-model already depends on ui-conversation, so ui-conversation cannot read it back.
 
 The gate is `routable`, NOT "the current target matches no advertised group". Catalog membership is advisory by design: a route serving a model it stopped advertising is absent from the groups yet perfectly usable, and blocking there would break a supported configuration (a narrowed `models` list over a live route). `routable` is also three-valued on the client — `null` before the first load or after a failed one never blocks, so a slow or unreachable Host cannot lock a working composer.
 
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
index c356656778..0d2821cb63 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 宿主拒绝。`session.prompt` 检查是否有适配器服务该会话的路由，在开启轮次之前就以 `model-unavailable` 应答。这是执行边界：客户端禁用编辑器只是提示性设计，这个方法始终可被调用。
 
-编辑器变惰性。`session.models` 报告 `routable`，ui-model 经新的 `ctx.conversation.blocks` 注册表推送一个 block；输入栏渲染的仍是它在没有 Workspace 时就会渲染的那个禁用 textarea，只是把抬起方自己的本地化理由作为 placeholder。推送方向是被迫的——ui-model 本就依赖 ui-conversation，因此 ui-conversation 读不回去。
+编辑器变惰性。`session.models` 报告 `routable`，ui-model 经新的 `ctx.conversation.blocks` 注册表推送一个 block；输入栏渲染的仍是它在没有 Workspace 时就会渲染的那个禁用 textarea，只是把抬起方自己的本地化理由作为 placeholder——唯独模型 seat 被 block 刻意保留可用，因为用户正是靠选模型来解除它。推送方向是被迫的——ui-model 本就依赖 ui-conversation，因此 ui-conversation 读不回去。
 
 闸门是 `routable`，**不是**「当前目标匹配不到任何已公布分组」。目录成员关系按设计是咨询性的：一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用，在那里阻断会破坏一种受支持的配置（对一条活着的路由收窄 `models` 列表）。`routable` 在客户端还是三值的——首次加载之前或加载失败之后的 `null` 绝不阻断，因此慢的或够不着的宿主锁不死一个本来能用的编辑器。
 
diff --git a/apps/web/tests/default-model.e2e.ts b/apps/web/tests/default-model.e2e.ts
index 9ff6198c3a..24ee5a1616 100644
--- a/apps/web/tests/default-model.e2e.ts
+++ b/apps/web/tests/default-model.e2e.ts
@@ -153,6 +153,15 @@ describe('web e2e: the composer model switch is the default for later sessions',
       },
     })
     expect(refused.result).toMatchObject({ ok: false, error: { code: 'model-unavailable' } })
+
+    // The way out stays open. Locking the model seat with everything else
+    // would leave the composer asking for the one thing it prevents.
+    const seat = page.getByRole('button', { name: /^选择模型/ })
+    expect(await seat.isEnabled()).toBe(true)
+    await seat.click()
+    await page.getByRole('menuitem', { name: /模型/ }).click()
+    await page.getByRole('menuitemradio').first().click()
+    await expect.poll(async () => box.isEnabled(), { timeout: 15_000 }).toBe(true)
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 })
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 49b177c66d..6ebdbc1d3a 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -175,7 +175,7 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
-  it('declares a route the adapter does not ship, with its own reasoning effort', async () => {
+  it('declares a route the adapter does not ship, without a reasoning control', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-models-declare'))
     const dialog = page.getByRole('dialog', { name: '设置' })
     const declare = dialog.getByRole('button', { name: '添加自定义提供方' })
@@ -184,10 +184,10 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     await dialog.getByLabel('Provider ID').fill('acme-gateway')
     await dialog.getByLabel('显示名称').fill('Acme Gateway')
     await dialog.getByLabel('API 地址').fill('https://gateway.acme.example/v1')
-    // The create card offers the same provider-level effort the editor card
-    // does for this namespace; a route declared without it would gain the
-    // control only on reopening.
-    await dialog.getByLabel('推理强度').selectOption('high')
+    // No reasoning effort anywhere for a hand-declared route: its models carry
+    // no reasoning capability, so a profile effort would make every model on
+    // the route fail to resolve and drop the provider out of the picker.
+    expect(await dialog.getByLabel('推理强度').count()).toBe(0)
     await dialog.getByRole('button', { name: '添加模型' }).click()
     await dialog.getByLabel('模型 ID 1').fill('acme-large')
     await dialog.getByRole('button', { name: '创建提供方', exact: true }).click()
@@ -196,7 +196,6 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     await row.waitFor({ timeout: 10_000 })
     const document = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
     expect(document).toContain('acme-gateway:')
-    expect(document).toContain('reasoning: high')
 
     // The tag follows the adapter's installed catalog: this route is in no
     // catalog, while minimax-cn is — even though both now have profiles.
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 3af7b2fd75..40a885262e 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 392f9956b33df88a5e9664a58de27d85fc0457d1
-README.zh.md: 6b0429a302475f84a7ce9b1cdc9fd47d90d6dba3
+README.md: ee8a4d240cdc326d158749ae8935ec99bb420d9f
+README.zh.md: 64ac1d15e20a8b60a39a8beb9ae7695543250026
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 392f9956b3..ee8a4d240c 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -8,7 +8,7 @@ Compaction renders as one collapsed row at the checkpoint's flow position withou
 
 The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
 
-Another plugin can make one session's composer inert through `ctx.conversation.blocks`: it sets a block carrying its own localized reason, and the bar renders the same disabled textarea with that reason as the placeholder — the no-workspace posture, reused. The push direction is the constraint, not a preference: the plugins that know a session cannot send (ui-model, when no adapter serves its route) already depend on this package, so this package cannot read them. A block is an affordance only; the Host refuses a prompt it cannot route regardless of what any client disables. The no-workspace state wins when both hold, because picking a workspace is the earlier prerequisite.
+Another plugin can make one session's composer inert through `ctx.conversation.blocks`: it sets a block carrying its own localized reason, and the bar renders the same disabled textarea with that reason as the placeholder — the no-workspace posture, reused. The push direction is the constraint, not a preference: the plugins that know a session cannot send (ui-model, when no adapter serves its route) already depend on this package, so this package cannot read them. The model seat is the one control a block leaves live — every block this contract has is cleared by choosing a model, so locking it too would leave the composer asking for the only thing it prevents. A block is an affordance only; the Host refuses a prompt it cannot route regardless of what any client disables. The no-workspace state wins when both hold, because picking a workspace is the earlier prerequisite.
 
 The view ring is a slot: the strict session-body registration declares the session-scoped `'conversation.view'` list in its `children` table, that body renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from registration options (`id`/`order`/`label`). The chat view is this package's own entry; plugins such as ui-trajectory contribute tabs through `ctx.slots.register`, and each view owns its chrome.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 6b0429a302..64ac1d15e2 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -8,7 +8,7 @@
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
-别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的 prompt。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
+别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份契约里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的 prompt。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
 
 视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 4c3a1546c9..84fb39cec8 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -265,6 +265,14 @@ export interface ConversationSessionHeaderInjected {
 export interface ComposerBarOwnerProps {
   /** Hero = empty-state centered card; composer = resident bottom bar. */
   variant: 'hero' | 'composer'
+  /**
+   * A block another plugin raised for this session: the bar refuses input and
+   * shows the blocker's reason as the placeholder, but — unlike `disabled` —
+   * keeps the model seat live. Every block this contract has is one the user
+   * clears by choosing a model, so locking that seat too would leave the
+   * composer telling them to do the one thing it prevents.
+   */
+  blocked?: { readonly reason: string }
   /**
    * Inert no-workspace state: the bar renders its normal DOM fully disabled
    * (textarea, add, send) so the workspace pick transitions in place instead
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
index 377b4de3ec..8440dacd94 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
@@ -138,7 +138,10 @@ export function ConversationRoot({
     ...(inert
       ? { disabled: true, placeholder: t('placeholder.workspace') }
       : blocked
-        ? { disabled: true, placeholder: composerBlock.reason }
+        // `blocked`, not `disabled`: the bar refuses input either way, but a
+        // block keeps the model seat live because choosing a model is how the
+        // user clears it.
+        ? { blocked: composerBlock, placeholder: composerBlock.reason }
         : hero ? { placeholder: t('placeholder.hero') } : {}),
     overlay: renderSlot('conversation.input.overlay', {}),
     leftItems: zone === undefined ? null : renderSlot('conversation.input.left', zone),
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 131f63c49d..7b24c09684 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -37,7 +37,8 @@ export type InputBarProps = ComposerBarProps
 export function InputBar({
   useSession, useInput, inputActions, keyboard, resolveSubmitMode, toggleCommandMenu, stop, command, t,
   renderSlot, useNotices, useLexicon, useMenuLauncher,
-  useProjection, sessionId, variant, disabled: inert = false, placeholder, accessory, overlay, leftItems, rightItems, footer,
+  useProjection, sessionId, variant, disabled: inert = false, blocked, placeholder,
+  accessory, overlay, leftItems, rightItems, footer,
 }: InputBarProps) {
   const input = useInput(s => s)
   const notice = useNotices(s => s)
@@ -86,8 +87,13 @@ export function InputBar({
   // inert no-workspace state, or the machine faces absent (no session). The
   // transient machine locks (adjudicating pending / submitting) render
   // read-only — the draft stays visible and focused, keystrokes drop.
-  const disabled = removed || inert || !live
+  const disabled = removed || inert || !live || blocked !== undefined
   const locked = disabled
+  // The model seat is the ONE control a block leaves live: every block this
+  // contract has is cleared by choosing a model, so locking it too would leave
+  // the composer asking for the only thing it prevents. The other reasons to
+  // be disabled do lock it — there is no session to choose a model for.
+  const modelSeatLocked = removed || inert || !live
   const machineBusy = input?.phase === 'adjudicating' || input?.phase === 'submitting'
 
   // Scroll the draft scrollport the minimum that brings `caret` into view — the
@@ -512,7 +518,7 @@ export function InputBar({
           </div>
           <div className={css.trailing}>
             {rightItems}
-            {renderSlot('conversation.input.model', { locked })}
+            {renderSlot('conversation.input.model', { locked: modelSeatLocked })}
             <ContextMeter useProjection={useProjection} t={t} />
             {/* {machineBusy && <span className={css.pending} data-input-pending aria-label="处理中" />} */}
             <Tooltip label={primaryLabel} side="top" delayMs={500}>
diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx
index e0872f1539..bcd8f25e73 100644
--- a/packages/client/ui-conversation/tests/skeleton.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx
@@ -120,9 +120,14 @@ function mount(
   const stop = vi.fn()
   const open = vi.fn()
   const slotCalls: string[] = []
+  /** Owner share handed to the two composer tool-row seats, per render. */
+  const seatOwners: { key: string; owner: unknown }[] = []
   let pickerOwner: unknown
   const renderSlot = ((key: string, owner: object, opts?: { only?: string }) => {
     slotCalls.push(key)
+    if (key === 'conversation.input.model' || key === 'conversation.input.plan') {
+      seatOwners.push({ key, owner })
+    }
     if (key === 'conversation.hero.workspace') { pickerOwner = owner; return null }
     if (key === 'conversation.session.header') {
       return (
@@ -200,7 +205,12 @@ function mount(
           stop={stop}
           command={() => Promise.resolve(true)}
           t={t}
-          renderSlot={(() => null) as InputBarProps['renderSlot']}
+          renderSlot={((key: string, seatOwner: object) => {
+            // The bar's own seats: recorded so a case can assert what share
+            // each tool-row control received.
+            seatOwners.push({ key, owner: seatOwner })
+            return null
+          }) as InputBarProps['renderSlot']}
           {...bar}
         />
       )
@@ -236,7 +246,7 @@ function mount(
   }
   const view = render(<ConversationRoot {...props} />)
   return {
-    view, chat, sink, retargetWorkspace, session, slotCalls, open,
+    view, chat, sink, retargetWorkspace, session, slotCalls, seatOwners, open,
     pickerOwner: () => pickerOwner,
     rerender: () => { view.rerender(<ConversationRoot {...props} />) },
   }
@@ -262,6 +272,13 @@ describe('ConversationRoot resident composer', () => {
     expect(box.placeholder).toBe('select a model first')
     fireEvent.keyDown(box, { key: 'Enter' })
     expect(b.sink).not.toHaveBeenCalled()
+
+    // The model seat stays live. Locking it too would leave the composer
+    // asking for the one thing it prevents — every block this contract has is
+    // cleared by choosing a model.
+    const seat = (key: string) => b.seatOwners.filter(call => call.key === key).at(-1)?.owner
+    expect(seat('conversation.input.model')).toEqual({ locked: false })
+    expect(seat('conversation.input.plan')).toEqual({ locked: true })
   })
 
   it('lets the no-workspace posture win over a block', () => {
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index 0dbea8d48c..e2b9e45f9d 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/client/ui-models/README.md
-README.md: 1d9c98dfd1e0cec0fa4cb33df9ffe2640be8be05
-README.zh.md: d3437c6f13be49ea73d6b3a51bee664b32521e01
+README.md: dec43de43899ef99e74b1fd73ffb4bf3c4e97b3e
+README.zh.md: c17eb611f071c4054d12d36acb2de8a94fa95a20
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index 1d9c98dfd1..dec43de438 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -16,7 +16,7 @@ A pi-ai profile's `models` list is edited on the card: one row per model showing
 
 **Fetch available models** asks `llm.discoverModels` about the endpoint the form **currently shows**, including a base URL edited but not yet saved and a key typed but not yet stored, so adding a provider is one pass instead of save-then-return. The reply opens a picker rather than being written: candidates already configured start unchecked, so adopting a selection never overwrites a capacity the user corrected. A provider that cannot be interrogated is a detour, not a dead end — the adapter's own message appears beside the rows, which stay editable by hand.
 
-**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts. The card records the conventional `apiKeyEnv` reference only when a key is typed, the same rule the editor applies, so a route declared for provider-native authentication is not born pointing at a reference nothing will ever set. When the profile write lands but the key write fails, the provider already exists: the card settles the fields describing it, retries the credential alone — re-running the profile write would carry the revision that write just superseded, so the Host would answer `settings-conflict` and the key could never be stored from here — and reports the created provider even if the user then cancels. The card offers the same provider-level reasoning effort the editor card does for this namespace, from one shared control: both write the same profile field, so a route declared without it would have gained the setting only on being reopened.
+**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. The id must start with a lowercase letter, because it is also the stem of the derived credential reference and a reference is a POSIX shell identifier: a digit-leading id otherwise passes every check this card makes and then fails at the credential seam with a raw regular expression. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts. The card records the conventional `apiKeyEnv` reference only when a key is typed, the same rule the editor applies, so a route declared for provider-native authentication is not born pointing at a reference nothing will ever set. When the profile write lands but the key write fails, the provider already exists: the card settles the fields describing it, retries the credential alone — re-running the profile write would carry the revision that write just superseded, so the Host would answer `settings-conflict` and the key could never be stored from here — and reports the created provider even if the user then cancels. Neither this card nor the editor offers a reasoning effort for such a route: a hand-declared model carries no reasoning capability — pi-ai's installed catalog is what supplies one, and it ships nothing under this route — so a profile effort makes `resolveModel` throw for every model on the route and drops the whole provider out of the picker. The editor withholds the control on the directory's `declared` bit for exactly that reason; a route the adapter ships keeps it.
 
 ## Model Experience
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index d3437c6f13..c17eb611f0 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -16,7 +16,7 @@ pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，
 
 **获取可用模型**会针对表单**当前显示**的端点调用 `llm.discoverModels`，包括已修改但尚未保存的 API 地址和已键入但尚未存储的密钥，因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路——适配器自己的消息会显示在各行旁边，而这些行仍可手工编辑。
 
-**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。这张卡片提供与编辑器卡片在该 namespace 下相同的提供方级推理等级，两者共用同一个控件：它们写的是同一个 profile 字段，若声明时没有它，这个设置就会等到重新打开编辑时才凭空出现。
+**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上以一条用户无从下手的原始正则失败。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。这类路由在两张卡片上都不提供推理等级：手工声明的模型没有推理能力——能力来自 pi-ai 的已安装 catalog，而它在这条路由下什么都没有——因此 profile 级等级会让该路由上每个模型的 `resolveModel` 抛错，整个提供方从选择器里消失。编辑器正是依据目录的 `declared` 位收起这个控件；适配器自带的路由则保留它。
 
 ## 模型体验
 
diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index 14511864ad..f8dd6ca3f8 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -13,6 +13,14 @@
  * The three fields a hand-declared route cannot default — endpoint, protocol,
  * and at least one model — are required here rather than at load, so the
  * failure names the field while the user is still looking at it.
+ *
+ * There is deliberately no reasoning-effort control. A hand-declared model
+ * carries no reasoning capability — pi-ai's installed catalog is what supplies
+ * one, and it has nothing under this route — so a profile effort here makes
+ * `resolveModel` throw UNSUPPORTED_REASONING_EFFORT for every model on the
+ * route, which drops the whole provider out of the model picker. The editor
+ * card hides the control for the same reason once the directory reports the
+ * route as declared.
  */
 
 import { useState } from 'react'
@@ -23,7 +31,6 @@ import { EditorFooter } from './EditorFooter.tsx'
 import { validateDeepSeekModels } from './DeepSeekModelsEditor.tsx'
 import { ModelListEditor } from './ModelListEditor.tsx'
 import type { ModelDraft } from './ModelListEditor.tsx'
-import { EFFORT_FIELD, ReasoningEffortField } from './ReasoningEffortField.tsx'
 import { deriveKeyRef, messageOf } from './store.ts'
 import type { en } from './locales.ts'
 import styles from './ModelsSection.module.css'
@@ -31,8 +38,15 @@ import styles from './ModelsSection.module.css'
 /** The settings namespace a hand-declared provider is written into. */
 const NS = 'llm-pi-ai'
 
-/** A route id usable as a settings key and as the stem of a credential name. */
-const ROUTE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+/**
+ * A route id usable as a settings key AND as the stem of a credential name.
+ * The leading letter is the second half of that: `deriveKeyRef` uppercases the
+ * id and replaces every non-alphanumeric run with `_`, and a credential
+ * reference is a POSIX shell identifier, which cannot start with a digit. A
+ * digit-leading id passes every check this card makes and then fails at the
+ * credential seam with a raw regular expression the user cannot act on.
+ */
+const ROUTE_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
 
 /** Props of {@link CustomProviderCard}. */
 export interface CustomProviderCardProps {
@@ -71,7 +85,6 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
   const [baseURL, setBaseURL] = useState('')
   const [protocol, setProtocol] = useState(protocols[0] ?? '')
   const [keyDraft, setKeyDraft] = useState('')
-  const [effort, setEffort] = useState<string | undefined>(undefined)
   const [models, setModels] = useState<readonly ModelDraft[]>([])
   const [busy, setBusy] = useState(false)
   const [failure, setFailure] = useState<string | undefined>(undefined)
@@ -128,9 +141,6 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
         ...storesKey ? { apiKeyEnv: keyRef } : {},
         api: protocol,
         baseURL,
-        // Inherit is the field being absent, not an empty string: the schema
-        // types it as an effort name, and an empty one would fail the write.
-        ...effort === undefined ? {} : { [EFFORT_FIELD['pi-ai']]: effort },
         models: models.map(model => ({ ...model })),
       }
       const response = await api.settings.mutate({
@@ -251,15 +261,6 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           ? null
           : <p className={styles['error']}>{t(keyFailure === 'keyBlank' ? 'keyBlankNew' : keyFailure)}</p>}
       </div>
-      {/* The same control the editor card shows for this namespace: a route
-          declared here and edited there must offer the same profile. */}
-      <ReasoningEffortField
-        family="pi-ai"
-        value={effort ?? ''}
-        onChange={setEffort}
-        t={t}
-        disabled={profileDisabled}
-      />
       <ModelListEditor
         models={models}
         onChange={setModels}
diff --git a/packages/client/ui-models/src/client/ModelsSection.tsx b/packages/client/ui-models/src/client/ModelsSection.tsx
index 9cbfba9a5a..0d1060978d 100644
--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-models/src/client/ModelsSection.tsx
@@ -54,6 +54,8 @@ interface EditorTarget extends ProviderIdentity {
   settingsPath: readonly string[]
   /** Writable credential identified under this page's conventional reference. */
   credentialRef?: string
+  /** Directory passthrough: the owning adapter ships nothing under this route. */
+  declared?: boolean
 }
 
 /** Values that vary around the shared provider-editor rendering. */
@@ -71,6 +73,7 @@ function renderProviderEditor({ target, ...props }: ProviderEditorRenderProps):
       provider={target.provider}
       displayName={target.displayName}
       settingsPath={target.settingsPath}
+      {...target.declared === undefined ? {} : { declared: target.declared }}
       {...props}
     />
   )
@@ -137,6 +140,7 @@ function targetOf(row: ProviderRow): EditorTarget {
     settingsNs: row.entry.settingsNs,
     settingsPath: row.entry.settingsPath,
     ...credentialRef === undefined ? {} : { credentialRef },
+    ...row.entry.declared === undefined ? {} : { declared: row.entry.declared },
   }
 }
 
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx
index 9b86db062a..3e6b26658f 100644
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -7,8 +7,10 @@
  * a key is entered; a blank key materializes a reference-free profile for
  * provider-native authentication);
  * the collapsed 自定义设置 area carries the per-family extras (`baseURL` for
- * both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, and
- * DeepSeek's id/name/context-window model catalog). Everything else stays
+ * both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai —
+ * withheld for a hand-declared route, whose models have no reasoning
+ * capability to configure — and DeepSeek's id/name/context-window model
+ * catalog). Everything else stays
  * owned by `settings.yaml`. Profile edits land as minimal `settings.mutate`
  * path ops against the stored section — the card reads the redacted
  * descriptor, so it names only the fields it can see and a stored literal
@@ -55,6 +57,13 @@ export interface ProviderEditorProps {
   api: Pick<IApiClient, 'settings' | 'credentials' | 'llm'>
   /** Section copy. */
   t: (key: keyof typeof en) => string
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it. Such a route's models carry no reasoning capability, so the
+   * effort control is withheld; absent means the adapter draws no such
+   * distinction and the control shows.
+   */
+  declared?: boolean
   /** Disable writes (read-only settings provider). */
   readOnly: boolean
   /** Close the editor; `changed` reports whether an Apply committed. */
@@ -352,13 +361,21 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                 }}
               />
             </div>
-            <ReasoningEffortField
-              family={family}
-              value={stringAt(draft, effortField) ?? ''}
-              onChange={(effort) => { setField(effortField, effort) }}
-              t={t}
-              disabled={disabled}
-            />
+            {/* A hand-declared route's models carry no reasoning capability
+                (pi-ai's installed catalog is what supplies one, and it has
+                nothing under such a route), so a profile effort would make
+                `resolveModel` throw for every model on it and drop the whole
+                provider out of the picker. Offering the control at all would
+                be offering a way to break the route. */}
+            {props.declared === true ? null : (
+              <ReasoningEffortField
+                family={family}
+                value={stringAt(draft, effortField) ?? ''}
+                onChange={(effort) => { setField(effortField, effort) }}
+                t={t}
+                disabled={disabled}
+              />
+            )}
             {/* Both families edit the same rows through the same contract; only
                 the extras differ — DeepSeek's inherited capacities, pi-ai's
                 endpoint interrogation. */}
diff --git a/packages/client/ui-models/src/client/ReasoningEffortField.tsx b/packages/client/ui-models/src/client/ReasoningEffortField.tsx
index 10b696a4ea..a129637135 100644
--- a/packages/client/ui-models/src/client/ReasoningEffortField.tsx
+++ b/packages/client/ui-models/src/client/ReasoningEffortField.tsx
@@ -1,13 +1,14 @@
 /**
- * The provider-level reasoning-effort select, shared by every card that writes
- * a provider profile. It lives here rather than inside one card because both
- * write the SAME field of the same profile: a route declared without this
- * control and then edited with it would offer a setting the creating user was
- * never given, which is exactly the drift that put it here.
+ * The provider-level reasoning-effort select: the profile's own default
+ * effort, applied to every model on the route unless a request names one. The
+ * empty option means "inherit", which on the wire is the field being absent
+ * rather than an empty string.
  *
- * The value is the profile's own default effort, applied to every model on the
- * route unless a request names one; the empty option means "inherit", which on
- * the wire is the field being absent rather than an empty string.
+ * It carries the per-family vocabulary and field name so the editor's two
+ * layouts cannot spell them differently. Only routes the adapter ships get
+ * this control at all — a hand-declared model has no reasoning capability to
+ * configure, and a profile effort over one makes its whole route fail to
+ * resolve — so the create card renders nothing here by construction.
  */
 
 import type { ReactNode } from 'react'
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index 67e48c3890..9809c61283 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -77,8 +77,8 @@ export const en = {
   customTitle: 'Custom provider',
   customTag: 'Custom',
   customRoute: 'Provider ID',
-  customRouteHint: 'Lowercase identifier that uniquely names this provider in requests and as its credential name.',
-  customRouteInvalid: 'Use lowercase letters, digits, and dashes.',
+  customRouteHint: 'Lowercase identifier, starting with a letter, that uniquely names this provider in requests and as its credential name.',
+  customRouteInvalid: 'Start with a lowercase letter; then lowercase letters, digits, and dashes.',
   customRouteTaken: 'A provider already uses this ID.',
   customDisplayName: 'Display name',
   customApi: 'API protocol',
@@ -172,8 +172,8 @@ export const zh: typeof en = {
   customTitle: '自定义提供方',
   customTag: '自定义',
   customRoute: 'Provider ID',
-  customRouteHint: '小写标识，在请求中唯一标识该提供方，并用于派生凭据名。',
-  customRouteInvalid: '只能使用小写字母、数字和短横线。',
+  customRouteHint: '以小写字母开头的标识，在请求中唯一标识该提供方，并用于派生凭据名。',
+  customRouteInvalid: '需以小写字母开头，之后可用小写字母、数字和短横线。',
   customRouteTaken: '已有提供方使用了这个 ID。',
   customDisplayName: '显示名称',
   customApi: 'API 协议',
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 95bfda4bb0..831353bc5c 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -9,7 +9,7 @@ import { ModelsSection } from '../src/client/ModelsSection.tsx'
 import type { ModelsSectionInjected } from '../src/client/ModelsSection.tsx'
 import { CustomProviderCard } from '../src/client/CustomProviderCard.tsx'
 import { formatCapacity, parseCapacity } from '../src/client/DeepSeekModelsEditor.tsx'
-import { ModelsSettingsStore, protocolChoices } from '../src/client/store.ts'
+import { ModelsSettingsStore, deriveKeyRef, protocolChoices } from '../src/client/store.ts'
 import { en } from '../src/client/locales.ts'
 
 afterEach(cleanup)
@@ -705,38 +705,35 @@ describe('hand-declared providers', () => {
     expect(set).toHaveBeenCalledWith({ ref: 'ACME_GATEWAY_API_KEY', value: 'gw-key' })
   })
 
-  it('offers the same reasoning effort the editor does, and omits it when inherited', async () => {
-    const { mutate, onClose } = mountCard()
-    const declare = (): void => {
-      fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
-      fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
-      fireEvent.click(screen.getByRole('button', { name: en.addModel }))
-      fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'acme-large' } })
-    }
-    declare()
+  it('offers no reasoning effort at all, in either card, for a hand-declared route', async () => {
+    mountCard()
+    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    // A hand-declared model carries no reasoning capability — pi-ai's
+    // installed catalog is what supplies one, and it ships nothing under this
+    // route — so a profile effort makes `resolveModel` throw
+    // UNSUPPORTED_REASONING_EFFORT for every model on it and drops the whole
+    // provider out of the picker. Offering the control would be offering a way
+    // to break the route.
+    expect(screen.queryByLabelText(en.effort)).toBeNull()
+    cleanup()
 
-    // The vocabulary is the namespace's, not DeepSeek's — a route declared
-    // here is edited by the pi-ai layout, which offers exactly these.
-    const select = screen.getByLabelText(en.effort) as HTMLSelectElement
+    // The editor card withholds it for the same route for the same reason...
+    await mountSection({
+      providers: { 'acme-gateway': { apiKeyEnv: 'ACME_GATEWAY_API_KEY', baseURL: 'https://acme.test/v1' } },
+      declaredRoutes: ['acme-gateway'],
+    })
+    openEditor('acme-gateway')
+    expect(screen.queryByLabelText(en.effort)).toBeNull()
+    cleanup()
+
+    // ...and keeps it for a route the adapter actually ships, whose models do
+    // carry the capability.
+    await mountSection({ providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY' } } })
+    openEditor('openai')
+    const select = screen.getByLabelText<HTMLSelectElement>(en.effort)
     expect([...select.options].map(option => option.value))
       .toEqual(['', 'off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
-
-    fireEvent.change(select, { target: { value: 'high' } })
-    fireEvent.click(screen.getByText(en.create))
-    await waitFor(() => { expect(onClose).toHaveBeenCalledWith(true) })
-    expect(firstMutate(mutate).ops[0]).toMatchObject({
-      path: ['providers', 'acme'],
-      value: { reasoning: 'high' },
-    })
-
-    // Inherit is the field being absent: an empty string would fail the schema
-    // that types this as an effort name.
-    cleanup()
-    const second = mountCard()
-    declare()
-    fireEvent.click(screen.getByText(en.create))
-    await waitFor(() => { expect(second.onClose).toHaveBeenCalledWith(true) })
-    expect(firstMutate(second.mutate).ops[0]).not.toHaveProperty('value.reasoning')
   })
 
   it('retries only the key after the profile landed, and reports the provider on cancel', async () => {
@@ -793,6 +790,32 @@ describe('hand-declared providers', () => {
     expect(onClose).toHaveBeenCalledWith(true)
   })
 
+  it('refuses a route id whose derived credential reference would be illegal', () => {
+    mountCard()
+    const routeField = screen.getByLabelText(en.customRoute)
+    fireEvent.change(routeField, { target: { value: 'https://acme.test/v1' } })
+
+    // A digit-leading id used to pass every check this card makes and then
+    // fail at the credential seam with a raw regular expression: the
+    // reference derives as `123_API_KEY`, and a credential reference is a
+    // POSIX shell identifier, which cannot start with a digit.
+    fireEvent.change(routeField, { target: { value: '123' } })
+    expect(screen.getByText(en.customRouteInvalid)).toBeTruthy()
+    expect(buttonNamed(en.create).disabled).toBe(true)
+
+    fireEvent.change(routeField, { target: { value: 'a1' } })
+    expect(screen.queryByText(en.customRouteInvalid)).toBeNull()
+  })
+
+  it('derives a reference the credential seam accepts for every id it admits', () => {
+    // The two rules have to stay in step; this is the relation, checked
+    // directly rather than through the DOM.
+    const CREDENTIAL_REF = /^[A-Za-z_][A-Za-z0-9_]*$/
+    for (const id of ['a', 'ds', 'a1', 'acme-gateway', 'x-1-y', 'zz9']) {
+      expect(CREDENTIAL_REF.test(deriveKeyRef(id))).toBe(true)
+    }
+  })
+
   it('names the blocked gate under the form, and nothing once it is satisfied', () => {
     mountCard()
     fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })

From 135064c8314dc7875bb1d1a17bb2c85a7ab1448e Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 17:02:05 +0800
Subject: [PATCH 104/516] fix(ui-models): stop the shared hint contradicting a
 filled-in field
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The line under the create form names the one blocked gate worth naming,
and its fallback arm reads "no models yet". An unmet Provider ID gate fell
through to that arm, so a card with two models listed right above it was
told it needed one. The key gate was already excluded for this reason; the
route gate was assumed excluded because its field explains itself, and was
not.

Tightening the route rule in the previous commit is what made this easy to
hit — a digit-leading id now fails the gate — but the fallthrough predates
it and fires for an empty or taken id just the same.
---
 .../src/client/CustomProviderCard.tsx         |  7 +++++--
 .../ui-models/tests/provider-form.spec.tsx    | 20 +++++++++++++++++++
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index f8dd6ca3f8..e27bd3c6bd 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -112,14 +112,17 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
   const ready = route.length > 0 && !routeInvalid && !routeTaken
     && baseURL.length > 0 && models.length > 0 && modelFailure === undefined
     && keyFailure === undefined
-  // The one blocked gate worth a line under the form. The route id is omitted
-  // because its own field already explains itself, and a satisfied card says
+  // The one blocked gate worth a line under the form. A satisfied card says
   // nothing at all rather than printing an empty paragraph.
   const hint = failure !== undefined || ready
     // The key field prints its own failure directly beneath itself, so a card
     // blocked only by the key stays silent here rather than answering with the
     // next unmet gate — which is satisfied, and reads as a second, false fault.
     || keyFailure !== undefined
+    // Same for the route id, and it must be tested rather than assumed: the
+    // fallback arm below reads "no models yet", so an unmet route gate used to
+    // fall through to it and contradict the filled-in list right above.
+    || route.length === 0 || routeInvalid || routeTaken
     ? undefined
     : baseURL.length === 0
       ? t('customNeedsBaseUrl')
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 831353bc5c..7d8f2efe27 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -790,6 +790,26 @@ describe('hand-declared providers', () => {
     expect(onClose).toHaveBeenCalledWith(true)
   })
 
+  it('never contradicts a filled-in field with the next gate\u2019s copy', () => {
+    mountCard()
+    const routeField = screen.getByLabelText(en.customRoute)
+    fireEvent.change(routeField, { target: { value: '2' } })
+    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.click(screen.getByRole('button', { name: en.addModel }))
+    fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
+
+    // The route field explains itself right under the input; the shared line
+    // must stay silent rather than falling through to "no models yet" while
+    // the list above plainly has one.
+    expect(screen.getByText(en.customRouteInvalid)).toBeTruthy()
+    expect(screen.queryByText(en.customNeedsModels)).toBeNull()
+
+    // Fixing the route hands the line back to the gate that is actually unmet.
+    fireEvent.change(routeField, { target: { value: 'acme' } })
+    expect(screen.queryByText(en.customNeedsModels)).toBeNull()
+    expect(buttonNamed(en.create).disabled).toBe(false)
+  })
+
   it('refuses a route id whose derived credential reference would be illegal', () => {
     mountCard()
     const routeField = screen.getByLabelText(en.customRoute)

From 2efce69d7921a0b2e1610f15d6efb5344b3b5b83 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 17:15:27 +0800
Subject: [PATCH 105/516] fix(client): route turn-tail through chain selector

---
 .../ui-conversation/src/client/apply.ts       |  2 +-
 .../src/client/chat/AssistantMarkdown.tsx     | 14 ++++-----
 .../src/client/chat/ChatView.tsx              |  6 ++--
 .../src/client/contract/slots.ts              | 11 ++++---
 .../ui-conversation/tests/chat-view.spec.tsx  |  4 ++-
 .../src/client/ProducedFiles.tsx              | 29 +++++++------------
 .../ui-deliverables/src/client/index.ts       |  4 +--
 .../src/client/turn-deliverables.ts           | 11 +++++++
 .../tests/produced-files.spec.tsx             | 15 ++++------
 9 files changed, 48 insertions(+), 48 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 8eb78139c4..24325c714e 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -303,7 +303,7 @@ export function apply(ctx: Context): void {
     children: {
       'conversation.chat.toolview': { kind: 'keyed', scope: 'session' },
       'conversation.chat.commandview': { kind: 'keyed', scope: 'session' },
-      'conversation.chat.turnTail': { kind: 'list', scope: 'session' },
+      'conversation.chat.turnTail': { kind: 'chain', scope: 'session' },
     },
     store: chatStore,
     inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ChatViewInjected => {
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index 687e1ae86c..bc1c6c7e32 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -9,12 +9,13 @@
 // their branch action is enabled only when the node is also the completed
 // turn's transcript tail. Think / tool-head-only nodes stay chrome-free.
 
-import { memo, useMemo, type ReactNode } from 'react'
+import { memo, useMemo } from 'react'
 import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
+import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import {
   IconThinkOutline14, JsonBlock, MarkdownText,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatViewSlotProps, TurnTailOwnerProps } from '../contract/slots.ts'
 import { hasContentText } from './chat-flow.ts'
 import { MessageIconActions } from './MessageIconActions.tsx'
 import { ToolRow } from './ToolRow.tsx'
@@ -40,9 +41,8 @@ export interface AssistantMarkdownProps {
   seq?: number | undefined
   /** Fork the session through this finalized message's completed turn when eligible. */
   onFork?: ((seq: number) => void) | undefined
-  /** Turn-tail content (the chat view's turnTail hole, rendered by the
-   *  owner); omitted for a mid-turn assistant. */
-  tail?: ReactNode | undefined
+  /** Turn-tail slot dispatch share and owner currency; omitted for a mid-turn assistant. */
+  turnTail?: (Pick<PropsRenderSlots<'conversation.chat.turnTail'>, 'renderSlotChain'> & { owner: TurnTailOwnerProps }) | undefined
   /** The message is not the transcript tail of a completed turn. */
   forkUnavailable?: boolean | undefined
   /** The owning view's locale seat, passed down as a plain prop. */
@@ -86,7 +86,7 @@ function ThinkRow({ text, running, t }: { text: string; running: boolean; t: Ass
 }
 
 export const AssistantMarkdown = memo(function AssistantMarkdown({
-  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, tail, t,
+  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, turnTail, t,
 }: AssistantMarkdownProps) {
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
@@ -124,7 +124,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
         })}
         {interrupted && <span className={css.stopped}>{t('message.stopped')}</span>}
       </div>
-      {showActions && tail}
+      {showActions && turnTail?.renderSlotChain('conversation.chat.turnTail', turnTail.owner)}
       {showActions && (
         <MessageIconActions
           text={copyText(blocks)}
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index ee43ff080d..b0907f5a80 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -335,7 +335,7 @@ function StreamingTail({ useSession, t }: {
  * render through the declared keyed hole's renderSlot share).
  */
 export function ChatView({
-  useSession, useSessions, useStore, renderSlot, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt, t,
+  useSession, useSessions, useStore, renderSlot, renderSlotChain, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt, t,
 }: ChatViewSlotProps) {
   const nodes = useSession(s => s.nodes)
   const turnTimings = useSession(s => s.turnTimings)
@@ -600,8 +600,8 @@ export function ChatView({
           seq={node.seq}
           onFork={forkAt}
           forkUnavailable={!branchSeqs.has(node.seq)}
-          tail={actionSeqs.has(node.seq)
-            ? renderSlot('conversation.chat.turnTail', { nodes, seq: node.seq, openFile })
+          turnTail={actionSeqs.has(node.seq)
+            ? { renderSlotChain, owner: { nodes, seq: node.seq, openFile } }
             : undefined}
           t={t}
         />
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 1246433a33..89f7986dba 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -47,14 +47,13 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      */
     'conversation.chat.commandview': { kind: 'keyed'; scope: 'session'; owner: CommandRowOwnerProps }
     /**
-     * The chat view's turn-tail hole: rendered between a closing assistant
+     * The chat view's turn-tail chain: rendered between a closing assistant
      * message's body and its IconActions footer, once per turn (the render
-     * site elects the closing seq). Declared by the chat view entry; feature
-     * plugins (ui-deliverables' produced-files row) derive what they show
-     * from the owner currency, and an unregistered hole renders nothing —
-     * composing such a plugin out of cordis.yml turns its surface off.
+     * site elects the closing seq). Entries derive a match from the owner
+     * currency before mounting, so presentation components never mount only
+     * to return null; an all-declined chain renders nothing.
      */
-    'conversation.chat.turnTail': { kind: 'list'; scope: 'session'; owner: TurnTailOwnerProps }
+    'conversation.chat.turnTail': { kind: 'chain'; scope: 'session'; owner: TurnTailOwnerProps }
     /**
      * The composer takeover chain: entries are selector-routed replacements
      * of the default InputBar. Declared by this package's 'conversation'
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index f2bb8709d7..b8cd94de52 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -130,6 +130,8 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
   const chat = createChatStore().create()
   const renderSlot = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
     opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlot']
+  const renderSlotChain = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
+    opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlotChain']
   // SessionProvider seat arrives with the session-scope child declaration;
   // ChatView never invokes it (render-prop pass-through stub).
   const SessionProviderStub: ChatViewSlotProps['SessionProvider'] = ({ children }) => <>{children(SID)}</>
@@ -144,6 +146,7 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     useStore: bindSnapshotSelector(chat),
     actions: chat.actions,
     renderSlot,
+    renderSlotChain,
     SessionProvider: SessionProviderStub,
     openDetails,
     openFile,
@@ -733,7 +736,6 @@ describe('ChatView', () => {
     // not re-render, so the row's renderSlot call count freezes during chunks.
     let rowRenders = 0
     h.props.renderSlot = ((key: string, _owner: object) => {
-      // The turnTail hole renders through the same share; only tool rows count here.
       if (key !== 'conversation.chat.toolview') return null
       rowRenders += 1
       return <div data-testid="counting-row" />
diff --git a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
index 609a688586..ab85869de2 100644
--- a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
+++ b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
@@ -1,14 +1,11 @@
 // ProducedFiles: the produced-file row a finished turn ends with. The paths
-// come from the mutation tools' follow-along locations (see
-// producedForClosing), never from the closing prose, so the answer carries
-// its own output whether or not the model remembered to name it. Clicking one
-// goes through the same openFile the tool rows use — the Host's own opener,
-// on the Host machine.
+// come pre-matched by the turn-tail chain from the mutation tools'
+// follow-along locations, never from the closing prose. Clicking one goes
+// through the same openFile the tool rows use — the Host's own opener, on the
+// Host machine.
 
-import { useMemo } from 'react'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { producedForClosing } from './turn-deliverables.ts'
 import type { NS } from './locales.ts'
 import css from './ProducedFiles.module.css'
 
@@ -21,21 +18,17 @@ function basename(path: string): string {
   return at === -1 ? path : path.slice(at + 1)
 }
 
-/** Full props: the turn-tail owner currency plus this plugin's locale seat. */
-export type ProducedFilesProps = TurnTailOwnerProps & PropsLocale<typeof NS>
+/** Matched paths plus the opener and locale seats needed to present them. */
+export type ProducedFilesProps = Pick<TurnTailOwnerProps, 'openFile'> & {
+  matched: readonly string[]
+} & PropsLocale<typeof NS>
 
 /**
  * Render one turn's produced files as openable chips.
- * @param props - the tail hole's owner currency (snapshot nodes, the closing
- * assistant's seq, the chat view's file opener) and the locale seat.
- * @returns The row, or `null` when the turn produced nothing.
+ * @param props - selector-matched paths, the chat view's file opener, and the locale seat.
+ * @returns The produced-files row.
  */
-export function ProducedFiles({ nodes, seq, openFile, t }: ProducedFilesProps) {
-  // Per-closing-message derivation over the windowed snapshot: O(nodes) on
-  // node-identity change only, which is the same cadence the owning view
-  // re-derives its own flow at.
-  const paths = useMemo(() => producedForClosing(nodes, seq), [nodes, seq])
-  if (paths.length === 0) return null
+export function ProducedFiles({ matched: paths, openFile, t }: ProducedFilesProps) {
   const shown = paths.slice(0, SHOWN)
   const hidden = paths.length - shown.length
   return (
diff --git a/packages/client/ui-deliverables/src/client/index.ts b/packages/client/ui-deliverables/src/client/index.ts
index 536c019b01..6dc7bc4b84 100644
--- a/packages/client/ui-deliverables/src/client/index.ts
+++ b/packages/client/ui-deliverables/src/client/index.ts
@@ -10,6 +10,7 @@ import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import { ProducedFiles } from './ProducedFiles.tsx'
 import { en, NS, zh, type DeliverablesKey } from './locales.ts'
+import { selectProducedFiles } from './turn-deliverables.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -34,8 +35,7 @@ export function apply(ctx: ClientContext): void {
     'conversation.chat.turnTail',
     () => ctx.slots.register({
       name: 'conversation.chat.turnTail',
-      id: 'produced-files',
-      order: 0,
+      select: selectProducedFiles,
       locale: NS,
     }, ProducedFiles),
   )
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index faa0455b37..a3ddf40b59 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -4,6 +4,7 @@
  * own follow-along `locations`, never the closing prose.
  */
 import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 /**
  * Paths a call view reports having created or changed, by render intent rather
@@ -76,3 +77,13 @@ export function producedForClosing(nodes: readonly ConversationNode[], seq: numb
   }
   return []
 }
+
+/**
+ * Claim the turn-tail chain only when its closing turn produced files.
+ * @param owner - Turn-tail owner currency for the closing assistant.
+ * @returns Produced paths as the component's match, or null to decline before mount.
+ */
+export function selectProducedFiles({ nodes, seq }: TurnTailOwnerProps): readonly string[] | null {
+  const paths = producedForClosing(nodes, seq)
+  return paths.length === 0 ? null : paths
+}
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index e5d92424a3..49e41ebd86 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -15,7 +15,7 @@ import type {
 import { apply as applyLocale } from '@deepseek-ai/dsh-client-locale/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { ProducedFiles } from '../src/client/ProducedFiles.tsx'
-import { producedForClosing } from '../src/client/turn-deliverables.ts'
+import { producedForClosing, selectProducedFiles } from '../src/client/turn-deliverables.ts'
 import { apply, inject } from '../src/client/index.ts'
 import { apply as applyNode } from '../src/index.ts'
 import { apply as applyInvariant } from '../src/invariant.ts'
@@ -64,6 +64,8 @@ describe('producedForClosing derivation', () => {
       assistant(9, 'second turn', 2),
     ]
     expect(producedForClosing(nodes, 7)).toEqual(['out/index.html', 'out/app.css'])
+    expect(selectProducedFiles({ nodes, seq: 7, openFile: () => {} })).toEqual(['out/index.html', 'out/app.css'])
+    expect(selectProducedFiles({ nodes, seq: 9, openFile: () => {} })).toBeNull()
     // A turn that produced nothing yields the empty list, and so does an
     // anchor the window does not contain.
     expect(producedForClosing(nodes, 9)).toEqual([])
@@ -126,8 +128,7 @@ describe('ProducedFiles row', () => {
     // it shows and says so rather than dropping the rest silently.
     const paths = ['deep/a.html', 'b.css', 'c.ts', 'd.ts', 'e.ts', 'f.ts', 'g.ts']
     const openFile = vi.fn<(path: string) => void>()
-    const nodes: ConversationNode[] = [user(1, 'build it'), wrote(2, 'w', ...paths), assistant(3, 'done', 1)]
-    const view = render(<ProducedFiles nodes={nodes} seq={3} openFile={openFile} t={t} />)
+    const view = render(<ProducedFiles matched={paths} openFile={openFile} t={t} />)
     expect(view.getByText('产物')).toBeTruthy()
     // Chips carry the basename; the full path stays reachable as the title.
     const chip = view.getByRole('button', { name: '打开 deep/a.html' })
@@ -138,12 +139,6 @@ describe('ProducedFiles row', () => {
     fireEvent.click(chip)
     expect(openFile).toHaveBeenCalledWith('deep/a.html')
   })
-
-  it('a turn that produced nothing renders no row at all', () => {
-    const nodes: ConversationNode[] = [user(1, 'hi'), assistant(2, 'hello', 1)]
-    const view = render(<ProducedFiles nodes={nodes} seq={2} openFile={() => {}} t={t} />)
-    expect(view.container.firstChild).toBeNull()
-  })
 })
 
 describe('package shells', () => {
@@ -169,7 +164,7 @@ describe('plugin registration', () => {
     // The owning view's child declaration, stood up by a bench root entry.
     ctx.slots.register({
       name: 'root',
-      children: { 'conversation.chat.turnTail': { kind: 'list', scope: 'session' } },
+      children: { 'conversation.chat.turnTail': { kind: 'chain', scope: 'session' } },
     } as never, () => null)
     await ctx.plugin({ inject: ['slots'], apply: applyLocale }).await()
 

From daac50c84ce3637bffbdeac350cac0a6ef0beb76 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 17:19:26 +0800
Subject: [PATCH 106/516] fix(client): name turn-tail selector owner

---
 .../client/ui-deliverables/src/client/turn-deliverables.ts     | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index a3ddf40b59..c9754d1da4 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -83,7 +83,8 @@ export function producedForClosing(nodes: readonly ConversationNode[], seq: numb
  * @param owner - Turn-tail owner currency for the closing assistant.
  * @returns Produced paths as the component's match, or null to decline before mount.
  */
-export function selectProducedFiles({ nodes, seq }: TurnTailOwnerProps): readonly string[] | null {
+export function selectProducedFiles(owner: TurnTailOwnerProps): readonly string[] | null {
+  const { nodes, seq } = owner
   const paths = producedForClosing(nodes, seq)
   return paths.length === 0 ? null : paths
 }

From 2dc1406dfdd67b11fbfec1aca2f485f2cd6f71f6 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 17:36:08 +0800
Subject: [PATCH 107/516] feat(ui-models): drop the provider-scoped reasoning
 effort, and red-flag a bad route id
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**Reasoning effort leaves the provider cards entirely.** It is a per-MODEL
capability and the models under one provider disagree about which levels
they accept: setting `anthropic` to `max` made six of its eight models
throw UNSUPPORTED_REASONING_EFFORT, and because the catalog build catches
per provider, the whole provider vanished from the picker behind one error
row. A provider-scoped control can only ever be set to a value some of its
models reject.

The composer's model picker already offers each model its own levels, and
a switch there now records provider, model, and effort together as the
next session's default — so the setting has a better home at the right
granularity. The profile field stays in `settings.yaml` for a deployment
that knows its route; only the control is gone, from both cards and both
adapter families. Two `components.spec` cases used the control as the
vehicle for their op assertions and now use `baseURL`, which is what they
were actually testing.

**A rejected Provider ID now reads as a fault.** It shared the neutral
hint paragraph with the field's guidance, so the copy telling the user
what they got wrong looked like advice. Reuses the existing `.error`
style, matching the split the key field already makes.
---
 apps/web/tests/models-settings.e2e.ts         | 18 ++---
 .../models.expected.md                        |  6 --
 packages/client/ui-models/README.i18n.yaml    |  4 +-
 packages/client/ui-models/README.md           |  4 +-
 packages/client/ui-models/README.zh.md        |  4 +-
 .../src/client/CustomProviderCard.tsx         | 20 +++---
 .../ui-models/src/client/ModelsSection.tsx    |  4 --
 .../ui-models/src/client/ProviderEditor.tsx   | 39 +++-------
 .../src/client/ReasoningEffortField.tsx       | 72 -------------------
 .../client/ui-models/src/client/locales.ts    |  4 --
 .../ui-models/tests/components.spec.tsx       | 24 +++----
 .../ui-models/tests/provider-form.spec.tsx    | 49 +++++++------
 12 files changed, 70 insertions(+), 178 deletions(-)
 delete mode 100644 packages/client/ui-models/src/client/ReasoningEffortField.tsx

diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 6ebdbc1d3a..d539c391c0 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -159,23 +159,23 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     const dialog = page.getByRole('dialog', { name: '设置' })
     await dialog.getByRole('button', { name: '编辑 minimax-cn' }).click()
     await dialog.getByText('自定义设置').click()
-    const effort = dialog.getByLabel('推理强度')
-    await effort.waitFor({ timeout: 10_000 })
-    await effort.selectOption('high')
+    const url = dialog.getByLabel('API 地址')
+    await url.waitFor({ timeout: 10_000 })
+    await url.fill('https://gateway.minimax.example/v1')
     await dialog.getByRole('button', { name: '保存', exact: true }).click()
     // The editor closes back to the row; the fold's write merged into the
     // stored profile beside the reference.
-    await expect.poll(async () => dialog.getByLabel('推理强度').count(), { timeout: 10_000 }).toBe(0)
+    await expect.poll(async () => dialog.getByLabel('API 地址').count(), { timeout: 10_000 }).toBe(0)
     await dialog.getByText('已保存 minimax-cn。', { exact: true }).waitFor({ timeout: 10_000 })
     const document = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
-    expect(document).toContain('reasoning: high')
+    expect(document).toContain('baseURL: https://gateway.minimax.example/v1')
     expect(document).toContain('apiKeyEnv: MINIMAX_CN_API_KEY')
     const snapshot = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(CONFIGURED_EXPECTED, snapshot, MODE)
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
-  it('declares a route the adapter does not ship, without a reasoning control', async () => {
+  it('declares a route the adapter does not ship', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-models-declare'))
     const dialog = page.getByRole('dialog', { name: '设置' })
     const declare = dialog.getByRole('button', { name: '添加自定义提供方' })
@@ -184,9 +184,9 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     await dialog.getByLabel('Provider ID').fill('acme-gateway')
     await dialog.getByLabel('显示名称').fill('Acme Gateway')
     await dialog.getByLabel('API 地址').fill('https://gateway.acme.example/v1')
-    // No reasoning effort anywhere for a hand-declared route: its models carry
-    // no reasoning capability, so a profile effort would make every model on
-    // the route fail to resolve and drop the provider out of the picker.
+    // No reasoning effort on a provider card at all: effort is a per-model
+    // capability, the models under one provider disagree about it, and a
+    // switch in the composer already records provider+model+effort together.
     expect(await dialog.getByLabel('推理强度').count()).toBe(0)
     await dialog.getByRole('button', { name: '添加模型' }).click()
     await dialog.getByLabel('模型 ID 1').fill('acme-large')
diff --git a/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md b/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md
index 45790a8f33..931caf0acb 100644
--- a/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md
+++ b/apps/web/tests/snapshots/onboarding-deepseek-config/models.expected.md
@@ -25,12 +25,6 @@
         - text: 自定义设置 API 地址
         - textbox "API 地址":
           - /placeholder: https://api.deepseek.com
-        - text: 推理强度
-        - combobox "推理强度":
-          - option "默认" [selected]
-          - option "off"
-          - option "high"
-          - option "max"
         - region "模型目录":
           - text: 模型目录 已自定义模型目录
           - button "恢复默认模型"
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index e2b9e45f9d..5d579d3b51 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/client/ui-models/README.md
-README.md: dec43de43899ef99e74b1fd73ffb4bf3c4e97b3e
-README.zh.md: c17eb611f071c4054d12d36acb2de8a94fa95a20
+README.md: cf4e50630339c4055e9ae2df37246b814af06966
+README.zh.md: 2b9158fa4419bf07f496fce47c938744f2a4233f
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index dec43de438..cf4e506303 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Models settings plugin: the provider configuration page and official-DeepSeek conditional onboarding step. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time, without presenting route liveness as provider status.
 
-Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a literal key or referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), `reasoningEffort` (deepseek) or `reasoning` (pi-ai), and each adapter's model catalog. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
+Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a literal key or referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint) and each adapter's model catalog. Reasoning effort is deliberately NOT among them: it is a per-model capability and the models under one provider disagree about which levels they accept, so a provider-scoped control could only be set to a value some of them reject — which took the whole provider out of the model picker. The composer's model picker offers each model its own levels, and a switch there records provider, model, and effort together as the default for the next session. The profile field stays in `settings.yaml` for a deployment that knows its route. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
 
 The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured literal `apiKey` secret sidecar or configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
 
@@ -16,7 +16,7 @@ A pi-ai profile's `models` list is edited on the card: one row per model showing
 
 **Fetch available models** asks `llm.discoverModels` about the endpoint the form **currently shows**, including a base URL edited but not yet saved and a key typed but not yet stored, so adding a provider is one pass instead of save-then-return. The reply opens a picker rather than being written: candidates already configured start unchecked, so adopting a selection never overwrites a capacity the user corrected. A provider that cannot be interrogated is a detour, not a dead end — the adapter's own message appears beside the rows, which stay editable by hand.
 
-**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. The id must start with a lowercase letter, because it is also the stem of the derived credential reference and a reference is a POSIX shell identifier: a digit-leading id otherwise passes every check this card makes and then fails at the credential seam with a raw regular expression. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts. The card records the conventional `apiKeyEnv` reference only when a key is typed, the same rule the editor applies, so a route declared for provider-native authentication is not born pointing at a reference nothing will ever set. When the profile write lands but the key write fails, the provider already exists: the card settles the fields describing it, retries the credential alone — re-running the profile write would carry the revision that write just superseded, so the Host would answer `settings-conflict` and the key could never be stored from here — and reports the created provider even if the user then cancels. Neither this card nor the editor offers a reasoning effort for such a route: a hand-declared model carries no reasoning capability — pi-ai's installed catalog is what supplies one, and it ships nothing under this route — so a profile effort makes `resolveModel` throw for every model on the route and drops the whole provider out of the picker. The editor withholds the control on the directory's `declared` bit for exactly that reason; a route the adapter ships keeps it.
+**Add a custom provider** declares a route pi-ai does not ship. It is its own card rather than the editor with extra fields, because the route id is being chosen here and the settings address does not exist until it is: one `settings.mutate` sets the whole profile at `providers.<route>`, and the key travels separately through `credentials.set` under the same `<ROUTE>_API_KEY` derivation an existing provider uses. What a hand-declared route cannot default gates the create button — a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model — so the failure names the field while the user is still looking at it. The id must start with a lowercase letter, because it is also the stem of the derived credential reference and a reference is a POSIX shell identifier: a digit-leading id otherwise passes every check this card makes and then fails at the credential seam with a raw regular expression. Capacities do not gate it: the adapter's fallbacks size a model the endpoint described by id alone, which is what most listings return. The protocol choices are read out of the namespace's own schema rather than a wire field or a constant, so they cannot drift from the ones the adapter accepts. The card records the conventional `apiKeyEnv` reference only when a key is typed, the same rule the editor applies, so a route declared for provider-native authentication is not born pointing at a reference nothing will ever set. When the profile write lands but the key write fails, the provider already exists: the card settles the fields describing it, retries the credential alone — re-running the profile write would carry the revision that write just superseded, so the Host would answer `settings-conflict` and the key could never be stored from here — and reports the created provider even if the user then cancels.
 
 ## Model Experience
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index c17eb611f0..2b9158fa44 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -4,7 +4,7 @@
 
 模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。
 
-行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可以询问提供方它服务什么。只有确认字面密钥或引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），另有 `reasoningEffort`（deepseek）或 `reasoning`（pi-ai），以及各适配器自己的模型目录。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可以询问提供方它服务什么。只有确认字面密钥或引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），以及各适配器自己的模型目录。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会让整个提供方从模型选择器里消失。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
@@ -16,7 +16,7 @@ pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，
 
 **获取可用模型**会针对表单**当前显示**的端点调用 `llm.discoverModels`，包括已修改但尚未保存的 API 地址和已键入但尚未存储的密钥，因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路——适配器自己的消息会显示在各行旁边，而这些行仍可手工编辑。
 
-**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上以一条用户无从下手的原始正则失败。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。这类路由在两张卡片上都不提供推理等级：手工声明的模型没有推理能力——能力来自 pi-ai 的已安装 catalog，而它在这条路由下什么都没有——因此 profile 级等级会让该路由上每个模型的 `resolveModel` 抛错，整个提供方从选择器里消失。编辑器正是依据目录的 `declared` 位收起这个控件；适配器自带的路由则保留它。
+**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上以一条用户无从下手的原始正则失败。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。
 
 ## 模型体验
 
diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index e27bd3c6bd..f055b325a5 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -14,13 +14,11 @@
  * and at least one model — are required here rather than at load, so the
  * failure names the field while the user is still looking at it.
  *
- * There is deliberately no reasoning-effort control. A hand-declared model
- * carries no reasoning capability — pi-ai's installed catalog is what supplies
- * one, and it has nothing under this route — so a profile effort here makes
- * `resolveModel` throw UNSUPPORTED_REASONING_EFFORT for every model on the
- * route, which drops the whole provider out of the model picker. The editor
- * card hides the control for the same reason once the directory reports the
- * route as declared.
+ * There is deliberately no reasoning-effort control, here or on the editor
+ * card: effort is a per-MODEL capability, and the models under one provider
+ * disagree about it, so a provider-scoped control can only be set to a value
+ * some of them reject. The composer's model picker offers each model its own
+ * levels instead.
  */
 
 import { useState } from 'react'
@@ -206,9 +204,11 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           onChange={(event) => { setRoute(event.target.value) }}
         />
       </div>
-      <p className={styles['advancedHint']}>
-        {routeInvalid ? t('customRouteInvalid') : routeTaken ? t('customRouteTaken') : t('customRouteHint')}
-      </p>
+      {/* A rejected id reads as a fault, not as guidance — the same split the
+          key field below already makes between its failure and its hint. */}
+      {routeInvalid || routeTaken
+        ? <p className={styles['error']}>{t(routeInvalid ? 'customRouteInvalid' : 'customRouteTaken')}</p>
+        : <p className={styles['advancedHint']}>{t('customRouteHint')}</p>}
       <div className={styles['field']}>
         <span className={styles['fieldLabel']}>{t('customDisplayName')}</span>
         <input
diff --git a/packages/client/ui-models/src/client/ModelsSection.tsx b/packages/client/ui-models/src/client/ModelsSection.tsx
index 0d1060978d..9cbfba9a5a 100644
--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-models/src/client/ModelsSection.tsx
@@ -54,8 +54,6 @@ interface EditorTarget extends ProviderIdentity {
   settingsPath: readonly string[]
   /** Writable credential identified under this page's conventional reference. */
   credentialRef?: string
-  /** Directory passthrough: the owning adapter ships nothing under this route. */
-  declared?: boolean
 }
 
 /** Values that vary around the shared provider-editor rendering. */
@@ -73,7 +71,6 @@ function renderProviderEditor({ target, ...props }: ProviderEditorRenderProps):
       provider={target.provider}
       displayName={target.displayName}
       settingsPath={target.settingsPath}
-      {...target.declared === undefined ? {} : { declared: target.declared }}
       {...props}
     />
   )
@@ -140,7 +137,6 @@ function targetOf(row: ProviderRow): EditorTarget {
     settingsNs: row.entry.settingsNs,
     settingsPath: row.entry.settingsPath,
     ...credentialRef === undefined ? {} : { credentialRef },
-    ...row.entry.declared === undefined ? {} : { declared: row.entry.declared },
   }
 }
 
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx
index 3e6b26658f..ff23e35b63 100644
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -7,10 +7,12 @@
  * a key is entered; a blank key materializes a reference-free profile for
  * provider-native authentication);
  * the collapsed 自定义设置 area carries the per-family extras (`baseURL` for
- * both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai —
- * withheld for a hand-declared route, whose models have no reasoning
- * capability to configure — and DeepSeek's id/name/context-window model
- * catalog). Everything else stays
+ * both families and DeepSeek's id/name/context-window model catalog).
+ * Reasoning effort is deliberately absent: it is a per-MODEL capability, and
+ * the models under one provider disagree about it, so a provider-scoped
+ * control can only be set to a value some of them reject. The composer's
+ * model picker offers each model its own levels; `settings.yaml` keeps the
+ * profile field for a deployment that knows its route. Everything else stays
  * owned by `settings.yaml`. Profile edits land as minimal `settings.mutate`
  * path ops against the stored section — the card reads the redacted
  * descriptor, so it names only the fields it can see and a stored literal
@@ -29,14 +31,12 @@ import {
 import { apiKeyFailure } from './apiKey.ts'
 import { EditorFooter } from './EditorFooter.tsx'
 import { ModelListEditor } from './ModelListEditor.tsx'
-import { EFFORT_FIELD, ReasoningEffortField } from './ReasoningEffortField.tsx'
-import type { EffortFamily } from './ReasoningEffortField.tsx'
 import { deriveKeyRef, messageOf } from './store.ts'
 import type { en } from './locales.ts'
 import styles from './ModelsSection.module.css'
 
 /** Per-adapter-family curated field sets (unknown namespaces get the hint alone). */
-type EditorLayout = EffortFamily | 'unknown'
+type EditorLayout = 'deepseek' | 'pi-ai' | 'unknown'
 
 /** The public DeepSeek endpoint shown as the deepseek base-URL placeholder. */
 const DEEPSEEK_PUBLIC_BASE_URL = 'https://api.deepseek.com'
@@ -57,13 +57,6 @@ export interface ProviderEditorProps {
   api: Pick<IApiClient, 'settings' | 'credentials' | 'llm'>
   /** Section copy. */
   t: (key: keyof typeof en) => string
-  /**
-   * Whether the owning adapter knows this route only because configuration
-   * declared it. Such a route's models carry no reasoning capability, so the
-   * effort control is withheld; absent means the adapter draws no such
-   * distinction and the control shows.
-   */
-  declared?: boolean
   /** Disable writes (read-only settings provider). */
   readOnly: boolean
   /** Close the editor; `changed` reports whether an Apply committed. */
@@ -303,8 +296,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
    * family as a parameter is what makes `EFFORT_FIELD` total here: an
    * unknown namespace never reaches this body.
    */
-  const curatedFields = (family: EffortFamily): ReactNode => {
-    const effortField = EFFORT_FIELD[family]
+  const curatedFields = (family: 'deepseek' | 'pi-ai'): ReactNode => {
     const customModels = getPath(draft, ['models'])
     const modelsOverridden = hasPath(draft, ['models'])
     const models = modelDrafts(modelsOverridden ? customModels : inheritedModels())
@@ -361,21 +353,6 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                 }}
               />
             </div>
-            {/* A hand-declared route's models carry no reasoning capability
-                (pi-ai's installed catalog is what supplies one, and it has
-                nothing under such a route), so a profile effort would make
-                `resolveModel` throw for every model on it and drop the whole
-                provider out of the picker. Offering the control at all would
-                be offering a way to break the route. */}
-            {props.declared === true ? null : (
-              <ReasoningEffortField
-                family={family}
-                value={stringAt(draft, effortField) ?? ''}
-                onChange={(effort) => { setField(effortField, effort) }}
-                t={t}
-                disabled={disabled}
-              />
-            )}
             {/* Both families edit the same rows through the same contract; only
                 the extras differ — DeepSeek's inherited capacities, pi-ai's
                 endpoint interrogation. */}
diff --git a/packages/client/ui-models/src/client/ReasoningEffortField.tsx b/packages/client/ui-models/src/client/ReasoningEffortField.tsx
deleted file mode 100644
index a129637135..0000000000
--- a/packages/client/ui-models/src/client/ReasoningEffortField.tsx
+++ /dev/null
@@ -1,72 +0,0 @@
-/**
- * The provider-level reasoning-effort select: the profile's own default
- * effort, applied to every model on the route unless a request names one. The
- * empty option means "inherit", which on the wire is the field being absent
- * rather than an empty string.
- *
- * It carries the per-family vocabulary and field name so the editor's two
- * layouts cannot spell them differently. Only routes the adapter ships get
- * this control at all — a hand-declared model has no reasoning capability to
- * configure, and a profile effort over one makes its whole route fail to
- * resolve — so the create card renders nothing here by construction.
- */
-
-import type { ReactNode } from 'react'
-import type { en } from './locales.ts'
-import styles from './ModelsSection.module.css'
-
-/** The adapter families that expose a provider-level effort, and their vocabularies. */
-export type EffortFamily = 'deepseek' | 'pi-ai'
-
-/** Reasoning vocabularies per family; the empty option means "inherit". */
-export const EFFORT_CHOICES: Record<EffortFamily, readonly string[]> = {
-  deepseek: ['off', 'high', 'max'],
-  'pi-ai': ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'],
-}
-
-/** The profile key each family's effort lives under. */
-export const EFFORT_FIELD: Record<EffortFamily, string> = {
-  deepseek: 'reasoningEffort',
-  'pi-ai': 'reasoning',
-}
-
-/** Props of {@link ReasoningEffortField}. */
-export interface ReasoningEffortFieldProps {
-  /** Which vocabulary to offer. */
-  family: EffortFamily
-  /** Current value; the empty string is the inherit option. */
-  value: string
-  /** Receives the chosen effort, or undefined for inherit. */
-  onChange: (effort: string | undefined) => void
-  /** Section copy. */
-  t: (key: keyof typeof en) => string
-  /** Disable the control (busy or read-only). */
-  disabled: boolean
-}
-
-/**
- * Render the provider-level reasoning-effort select.
- * @param props - family vocabulary, current value, change sink, copy, and disabled state.
- * @returns the labelled select.
- */
-export function ReasoningEffortField(
-  { family, value, onChange, t, disabled }: ReasoningEffortFieldProps,
-): ReactNode {
-  return (
-    <div className={styles['field']}>
-      <span className={styles['fieldLabel']}>{t('effort')}</span>
-      <select
-        className={`${styles['input']} ${styles['selectInput']}`}
-        value={value}
-        aria-label={t('effort')}
-        disabled={disabled}
-        onChange={(event) => { onChange(event.target.value === '' ? undefined : event.target.value) }}
-      >
-        <option value="">{t('effortInherit')}</option>
-        {EFFORT_CHOICES[family].map(choice => (
-          <option key={choice} value={choice}>{choice}</option>
-        ))}
-      </select>
-    </div>
-  )
-}
diff --git a/packages/client/ui-models/src/client/locales.ts b/packages/client/ui-models/src/client/locales.ts
index 9809c61283..7d75e1de11 100644
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -35,8 +35,6 @@ export const en = {
   customized: 'Customized settings',
   baseUrl: 'Base URL',
   baseUrlDefault: 'Provider default',
-  effort: 'Reasoning effort',
-  effortInherit: 'Default',
   models: 'Models',
   modelsInherited: 'Using the adapter defaults',
   modelsCustomized: 'Customized model catalog',
@@ -130,8 +128,6 @@ export const zh: typeof en = {
   customized: '自定义设置',
   baseUrl: 'API 地址',
   baseUrlDefault: '提供方默认',
-  effort: '推理强度',
-  effortInherit: '默认',
   models: '模型目录',
   modelsInherited: '正在使用适配器默认模型',
   modelsCustomized: '已自定义模型目录',
diff --git a/packages/client/ui-models/tests/components.spec.tsx b/packages/client/ui-models/tests/components.spec.tsx
index 931410fb35..88eab4b998 100644
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -92,13 +92,12 @@ function wireNamespaces(): SettingsNamespaceView[] {
       value: {
         apiKeyEnv: 'DEEPSEEK_API_KEY',
         baseURL: 'https://base',
-        reasoningEffort: 'high',
         defaultContextWindow: 1_000_000,
         maxTokens: 256_000,
         models: DEFAULT_DEEPSEEK_MODELS,
       },
       base: { defaultContextWindow: 1_000_000, maxTokens: 256_000, models: DEFAULT_DEEPSEEK_MODELS },
-      user: { reasoningEffort: 'high' },
+      user: { baseURL: 'https://base' },
       applies: 'live',
       secrets: [{ path: ['apiKey'], set: false }],
       revision: 0,
@@ -729,16 +728,16 @@ describe('ModelsSection', () => {
     // user layer and replaced it wholesale, deleting any stored literal key.
     const { replace, update, mutate } = await mountSection()
     fireEvent.click(screen.getByText(en.customized))
-    const effort = screen.getByLabelText<HTMLSelectElement>(en.effort)
-    expect(effort.value).toBe('high')
-    fireEvent.change(effort, { target: { value: '' } })
+    const url = screen.getByLabelText<HTMLInputElement>(en.baseUrl)
+    expect(url.value).toBe('https://base')
+    fireEvent.change(url, { target: { value: '' } })
     fireEvent.click(screen.getByText(en.apply))
     await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
     expect(replace).not.toHaveBeenCalled()
     expect(update).not.toHaveBeenCalled()
     expect(mutate.mock.calls[0]?.[0]).toEqual({
       ns: 'llm-deepseek',
-      ops: [{ op: 'unset', path: ['reasoningEffort'] }],
+      ops: [{ op: 'unset', path: ['baseURL'] }],
       expectedRevision: 0,
     })
   })
@@ -795,17 +794,16 @@ describe('ModelsSection', () => {
     const urls = screen.getAllByLabelText<HTMLInputElement>(en.baseUrl)
     expect(urls).toHaveLength(2)
     expect((urls[1] as HTMLInputElement).value).toBe('https://proxy')
-    const effort = screen.getAllByLabelText<HTMLSelectElement>(en.effort)
-    fireEvent.change(effort[effort.length - 1] as HTMLSelectElement, { target: { value: 'xhigh' } })
+    fireEvent.change(urls[1] as HTMLInputElement, { target: { value: 'https://proxy/v2' } })
     fireEvent.click(screen.getAllByText(en.apply)[1] as HTMLElement)
     await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
-    // Only the edited field travels: apiKeyEnv, baseURL and headers were
-    // already stored with these values, so no op restates them — and the
-    // profile's stored literal apiKey, absent from the redacted view the card
-    // read, is named by nothing at all.
+    // Only the edited field travels: apiKeyEnv and headers were already stored
+    // with these values, so no op restates them — and the profile's stored
+    // literal apiKey, absent from the redacted view the card read, is named by
+    // nothing at all.
     expect(mutate.mock.calls[0]?.[0]).toEqual({
       ns: 'llm-pi-ai',
-      ops: [{ op: 'set', path: ['providers', 'openai', 'reasoning'], value: 'xhigh' }],
+      ops: [{ op: 'set', path: ['providers', 'openai', 'baseURL'], value: 'https://proxy/v2' }],
       expectedRevision: 0,
     })
   })
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 7d8f2efe27..7e5ef5f36e 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -705,35 +705,24 @@ describe('hand-declared providers', () => {
     expect(set).toHaveBeenCalledWith({ ref: 'ACME_GATEWAY_API_KEY', value: 'gw-key' })
   })
 
-  it('offers no reasoning effort at all, in either card, for a hand-declared route', async () => {
+  it('scopes each card to fields a provider can actually own', async () => {
+    // Reasoning effort used to sit here. It is a per-MODEL capability and the
+    // models under one provider disagree about it, so a provider-scoped
+    // control could only be set to a value some of them reject — which took
+    // the whole provider out of the picker. The composer's model picker owns
+    // the choice, and a switch there records provider+model+effort together.
+    const fields = () => [...document.querySelectorAll('input,select')]
+      .map(el => el.getAttribute('aria-label')).filter(Boolean)
+
     mountCard()
     fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
-    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
-    // A hand-declared model carries no reasoning capability — pi-ai's
-    // installed catalog is what supplies one, and it ships nothing under this
-    // route — so a profile effort makes `resolveModel` throw
-    // UNSUPPORTED_REASONING_EFFORT for every model on it and drops the whole
-    // provider out of the picker. Offering the control would be offering a way
-    // to break the route.
-    expect(screen.queryByLabelText(en.effort)).toBeNull()
+    expect(fields()).toEqual([en.customRoute, en.customDisplayName, en.baseUrl, en.customApi, en.keyInput])
     cleanup()
 
-    // The editor card withholds it for the same route for the same reason...
-    await mountSection({
-      providers: { 'acme-gateway': { apiKeyEnv: 'ACME_GATEWAY_API_KEY', baseURL: 'https://acme.test/v1' } },
-      declaredRoutes: ['acme-gateway'],
-    })
-    openEditor('acme-gateway')
-    expect(screen.queryByLabelText(en.effort)).toBeNull()
-    cleanup()
-
-    // ...and keeps it for a route the adapter actually ships, whose models do
-    // carry the capability.
     await mountSection({ providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY' } } })
     openEditor('openai')
-    const select = screen.getByLabelText<HTMLSelectElement>(en.effort)
-    expect([...select.options].map(option => option.value))
-      .toEqual(['', 'off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
+    fireEvent.click(screen.getByText(en.customized))
+    expect(fields()).toEqual([en.keyInput, en.baseUrl])
   })
 
   it('retries only the key after the profile landed, and reports the provider on cancel', async () => {
@@ -827,6 +816,20 @@ describe('hand-declared providers', () => {
     expect(screen.queryByText(en.customRouteInvalid)).toBeNull()
   })
 
+  it('styles a rejected route id as a fault and its guidance as a hint', () => {
+    mountCard()
+    const routeField = screen.getByLabelText(en.customRoute)
+    // Same split the key field makes: what the user got wrong reads as a
+    // fault, what they have yet to do reads as guidance.
+    expect(screen.getByText(en.customRouteHint).className).toMatch(/advancedHint/)
+
+    fireEvent.change(routeField, { target: { value: '2' } })
+    expect(screen.getByText(en.customRouteInvalid).className).toMatch(/error/)
+
+    fireEvent.change(routeField, { target: { value: 'openai' } })
+    expect(screen.getByText(en.customRouteTaken).className).toMatch(/error/)
+  })
+
   it('derives a reference the credential seam accepts for every id it admits', () => {
     // The two rules have to stay in step; this is the relation, checked
     // directly rather than through the DOM.

From fe505e1e91ce7dcd2fda1c3c3a45eaa92abb2b60 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Fri, 7 Aug 2026 03:02:10 -0700
Subject: [PATCH 108/516] feat(web): a prose mention of a produced file opens
 it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The chatFileMentions service (provided by ui-deliverables beside its
turn-tail entry, reached via ctx.get) resolves inline-code tokens in the
closing message against the turn's produced locations: exact path or
unique basename links, ambiguity and unknowns stay inert. MarkdownText
gains the optional fileMentions seam — settled renders only, never
inside anchors.
---
 ...6-08-07-web-inline-file-mentions.i18n.yaml |   6 +
 .../2026-08-07-web-inline-file-mentions.md    |  28 +++
 .../2026-08-07-web-inline-file-mentions.zh.md |  28 +++
 apps/web/tests/produced-file-mentions.e2e.ts  | 162 ++++++++++++++++++
 apps/web/tsconfig.json                        |   1 +
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +-
 packages/client/ui-conversation/README.zh.md  |   2 +-
 .../ui-conversation/src/client/apply.ts       |   1 +
 .../src/client/chat/AssistantMarkdown.tsx     |  29 +++-
 .../src/client/chat/ChatView.tsx              |   4 +-
 .../src/client/contract/slots.ts              |  32 ++++
 .../ui-conversation/src/client/index.ts       |   1 +
 .../ui-conversation/tests/chat-view.spec.tsx  |  41 +++++
 .../client/ui-deliverables/README.i18n.yaml   |   4 +-
 packages/client/ui-deliverables/README.md     |   4 +-
 packages/client/ui-deliverables/README.zh.md  |   4 +-
 .../src/client/ProducedFiles.tsx              |   7 +-
 .../ui-deliverables/src/client/index.ts       |  25 ++-
 .../src/client/turn-deliverables.ts           |  43 +++++
 .../tests/produced-files.spec.tsx             |  47 ++++-
 .../client/ui-primitives/README.i18n.yaml     |   4 +-
 packages/client/ui-primitives/README.md       |   2 +-
 packages/client/ui-primitives/README.zh.md    |   2 +-
 packages/client/ui-primitives/src/index.ts    |   2 +-
 .../src/markdown/MarkdownText.module.css      |  20 +++
 .../src/markdown/MarkdownText.tsx             |  26 ++-
 .../ui-primitives/src/markdown/render.tsx     |  51 +++++-
 .../tests/markdown-render-units.spec.tsx      |   1 +
 .../ui-primitives/tests/markdown.spec.tsx     |  43 +++++
 tsconfig.host.json                            |   1 +
 31 files changed, 584 insertions(+), 43 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
 create mode 100644 apps/web/tests/produced-file-mentions.e2e.ts

diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
new file mode 100644
index 0000000000..e8fe387234
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.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-08-07-web-inline-file-mentions.md
+2026-08-07-web-inline-file-mentions.md: 79c6bddd500dc0b68bf64f3c4bea114ca41b4b62
+2026-08-07-web-inline-file-mentions.zh.md: ddc54d3b43570b19fb23c1c9c8079ef4ca65f8fa
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
new file mode 100644
index 0000000000..79c6bddd50
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
@@ -0,0 +1,28 @@
+# Agent Note: inline-code file mentions open the file they name
+
+Status: implemented
+
+English | [中文](2026-08-07-web-inline-file-mentions.zh.md)
+
+> Scope: linking inline-code tokens in the closing message's prose to the files the turn produced. Not in scope: recognizing paths in plain prose, linking files the turn did not produce, and mentions in streaming or mid-turn messages.
+
+## Problem
+
+The produced-files row lists a turn's output, but the closing message usually also *names* the file in prose — as inline code, like `` `deepseek-homepage.html` `` — and that mention was inert text. The reader's eye lands on the sentence first; the affordance sat one row below it.
+
+## Decision
+
+**A prose mention links only when it matches a produced file.** The [produced-files decision](2026-07-31-web-workspace-file-links.md) rejected linkifying the closing message because rendering must not depend on the model spelling a path recognizably; that holds. The row remains the authoritative, prose-independent account. This feature adds a second consumer of the same `locations` vocabulary: `producedFileMentions` resolves an inline-code token by exact path, or by being exactly the basename of exactly one produced path. A basename two paths share stays inert rather than guessing, and a token naming nothing the turn wrote stays inert — a mention link can never 404.
+
+**The renderer owns no vocabulary, and the provider is the deliverables plugin.** `MarkdownText` takes an optional `MarkdownFileMentions` resolver and consults it for inline-code tokens — after URL promotion, which wins, and never inside an anchor, where a button cannot nest. What names a file is decided behind the optional `chatFileMentions` service ui-conversation reaches via `ctx.get`: ui-deliverables provides it beside its turn-tail chain entry, so one cordis.yml line composes the row and the prose links in or out together, and ui-primitives gains no session concepts. Mentions apply to settled renders only — the streaming cache must not bake in handlers that could go stale, and the vocabulary is not final until the turn closes. The consumer memoizes the resolver on the closing seq rather than the growing transcript, so a settled message's cached parse survives stream appends.
+
+## Alternatives considered
+
+- **Path-shaped regex over all prose** — links `package.json` mentioned abstractly and examples that were never written; every false positive is a click that opens nothing or the wrong file. The vocabulary approach cannot produce a dead link.
+- **Linking suffix matches (`out/index.html` mentioned as `index.html` in a subdirectory listing)** — deferred; exact path and unique basename cover the observed closing-message shapes, and a wider matcher can loosen later without breaking the seam.
+- **Resolving in ui-primitives against a passed path list** — puts matching policy in the generic renderer, where other consumers would inherit it unasked. The resolver seam keeps policy with the owner.
+- **Threading the vocabulary through the turn-tail chain** — the chain is a render dispatch below the message; mentions decorate markdown inside it, which only data reaching MarkdownText can do. The optional service is that data path, and its absence is the off state.
+
+## Consequences
+
+The mention and the row are two affordances for one fact, styled alike (underlined at rest, full path as `title`). `apps/web/tests/produced-file-mentions.e2e.ts` pins the assembled behavior with a built write-turn seed: unique basename links, ambiguous and unknown tokens stay inert; it does not click, for the produced-files restraint (the opener launches a real application). Mentions in mid-turn narration stay inert even for files the turn later produces, because the vocabulary attaches to the closing message only. The window-prepend edge — a window that starts mid-turn later gaining earlier same-turn writes — leaves a mention unlinked until remount, never wrongly linked.
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
new file mode 100644
index 0000000000..ddc54d3b43
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
@@ -0,0 +1,28 @@
+# Agent Note：行内代码文件提及可打开其命名的文件
+
+Status: implemented
+
+[English](2026-08-07-web-inline-file-mentions.md) | 中文
+
+> 范围：把收尾消息正文中的行内代码 token 链接到本轮产出的文件。不在范围内：识别普通正文中的路径、链接本轮未产出的文件，以及流式或轮次中途消息里的提及。
+
+## 问题
+
+产物行列出了一轮的输出，但收尾消息通常也会在正文里*点名*文件——以行内代码形式，如 `` `deepseek-homepage.html` ``——而这个提及是死文本。读者的视线先落在句子上；可点击的交互却在下面一行。
+
+## 决定
+
+**正文提及只在与产出文件对得上时才成为链接。**[产物行的决定](2026-07-31-web-workspace-file-links.md)否决过"把收尾消息链接化"，理由是渲染不能依赖模型把路径写得可识别；这一点不变。产物行仍是权威的、不依赖正文的记录。本特性只是给同一份 `locations` 词表增加第二个消费者：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析。两条路径共享的 basename 保持死文本而不猜测，命名了本轮没写过的文件的 token 同样保持死文本——提及链接永远不会 404。
+
+**渲染器不持有词表，提供方是 deliverables 插件。**`MarkdownText` 接受可选的 `MarkdownFileMentions` 解析器，对行内代码 token 询问它——URL 提升优先于解析器，且绝不在锚点内部（按钮不能嵌套在链接里）。什么算文件名的决定藏在 ui-conversation 经 `ctx.get` 触达的可选 `chatFileMentions` service 背后：ui-deliverables 在其 turn-tail chain 注册项旁提供该 service，因此 cordis.yml 中的一行同时把产物行和正文链接组合进来或去掉，ui-primitives 不引入任何会话概念。提及只作用于已定稿的渲染——流式缓存不能烘进可能过期的 handler，而且词表在轮次收尾前并不最终。消费方按收尾 seq 而非不断增长的 transcript 记忆化解析器，因此已定稿消息的缓存解析在流式追加中得以保留。
+
+## 考虑过的替代方案
+
+- **对全部正文跑路径形状的正则**——会把随口提到的 `package.json` 和从未写过的示例都链接上；每个误报都是一次打开空无或错误文件的点击。词表方案不可能产生死链。
+- **链接后缀匹配（子目录列表里把 `out/index.html` 写作 `index.html`）**——暂缓；精确路径加唯一 basename 已覆盖观察到的收尾消息形态，之后放宽匹配器不会破坏这道 seam。
+- **在 ui-primitives 里对传入的路径列表做解析**——把匹配策略放进通用渲染器，其他消费方会被动继承。解析器 seam 让策略留在持有者手里。
+- **经由 turn-tail chain 传递词表**——chain 是消息下方的渲染派发；提及要装饰的是消息内部的 markdown，只有抵达 MarkdownText 的数据才做得到。可选 service 就是那条数据通路，它的缺席即关闭态。
+
+## 后果
+
+提及与产物行是同一事实的两个交互面，样式一致（静止即下划线，完整路径作为 `title`）。`apps/web/tests/produced-file-mentions.e2e.ts` 用构造的写入轮 seed 钉住组装后的行为：唯一 basename 成链，歧义与未知 token 保持死文本；它不驱动点击，沿用产物行的克制（opener 会启动真实应用）。轮次中途叙述里的提及即使命名了本轮后来产出的文件也保持死文本，因为词表只挂在收尾消息上。窗口前插的边界——从轮次中途开始的窗口后来补入了同轮更早的写入——只会让提及在重挂载前暂不成链，绝不会错链。
diff --git a/apps/web/tests/produced-file-mentions.e2e.ts b/apps/web/tests/produced-file-mentions.e2e.ts
new file mode 100644
index 0000000000..badd9b845e
--- /dev/null
+++ b/apps/web/tests/produced-file-mentions.e2e.ts
@@ -0,0 +1,162 @@
+// Web e2e scenario: inline-code file mentions in the closing prose. Cold-seeds
+// a built write turn (zero model calls) whose closing message names the written
+// file three ways: by unique basename (links), ambiguously (stays inert), and
+// as a file the turn never touched (stays inert). Package tests cover the
+// resolver in isolation; only the assembled application shows a real write's
+// locations reaching the prose as an opener. The click itself is not driven
+// here: it hands the path to the Host's opener, which would launch a real
+// application on the machine running the suite (the produced-files restraint).
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { CallId, createAssistantMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-title'
+import {
+  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const MODE = webSnapshotMode()
+const SEED_ID = 'produced-file-mentions-web-e2e'
+const DONE = 'FILE_MENTION_DONE'
+
+/** One-part text content for a built message. */
+function text(value: string): { type: 'text'; text: string }[] {
+  return [{ type: 'text', text: value }]
+}
+
+/** The files the built turn writes; `notes.md` is named in prose but never written. */
+const WRITES = ['site/report.html', 'a/style.css', 'b/style.css']
+
+/** Build a settled write turn whose closing prose mentions files in inline code. */
+function mentionFixture(): string {
+  const session = Session.create(SessionId('produced-file-mentions-source'))
+  const eventTimeOrigin = new Date().setHours(12, 0, 0, 0)
+  session.append('turn/start', { turn: 1 })
+  const user = session.append('user/message', createUserMessage({
+    content: [{ type: 'text', text: 'Write the report page and both stylesheets.' }],
+    source: { kind: 'user' },
+  }), { surfaceOp: 'append' })
+  session.append('session/title', {
+    title: 'Produced file mentions',
+    messageSeqs: [user.seq],
+    source: { kind: 'fallback' },
+  })
+  session.append('step/start', { turn: 1, step: 1 })
+  const calls = WRITES.map((path, index) => ({
+    path,
+    callId: CallId(`file-mention-${String(index)}`),
+    args: JSON.stringify({ file_path: path, content: `content of ${path}\n` }),
+  }))
+  session.append('assistant/message', {
+    turn: 1,
+    step: 1,
+    message: createAssistantMessage({
+      content: calls.map(call => ({
+        type: 'tool-call' as const,
+        id: call.callId,
+        name: 'write',
+        arguments: call.args,
+      })),
+      source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+    }),
+  }, { surfaceOp: 'append' })
+  for (const call of calls) {
+    const source = session.append('tool/call', {
+      turn: 1,
+      step: 1,
+      callId: call.callId,
+      name: 'write',
+      arguments: call.args,
+    })
+    session.append('tool/result', {
+      turn: 1,
+      step: 1,
+      message: createToolResultMessage({
+        callId: call.callId,
+        content: text(`Created ${call.path}`),
+        isError: false,
+      }),
+    }, { surfaceOp: 'append', sourceEventSeqs: [source.seq] })
+  }
+  session.append('step/start', { turn: 1, step: 2 })
+  session.append('assistant/message', {
+    turn: 1,
+    step: 2,
+    message: createAssistantMessage({
+      content: [{
+        type: 'text',
+        text: [
+          'Wrote `report.html` plus two `style.css` copies; `notes.md` untouched.',
+          '',
+          DONE,
+        ].join('\n'),
+      }],
+      source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+    }),
+  }, { surfaceOp: 'append' })
+  session.append('step/end', { turn: 1, step: 2 })
+  session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+  return [
+    JSON.stringify({
+      type: 'session',
+      version: SESSION_FORMAT_VERSION,
+      id: '{{sessionId}}',
+      createdAt: 0,
+      cwd: '{{cwd}}',
+    }),
+    ...session.events.map(event => JSON.stringify({
+      ...event,
+      time: eventTimeOrigin + event.seq * 1_000,
+    })),
+    '',
+  ].join('\n')
+}
+
+describe('web e2e: inline-code mentions of produced files', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    await seedSession(scaffold, mentionFixture(), SEED_ID)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it.skipIf(MODE === 'record')('links the unique mention and leaves ambiguous and unknown code inert', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-produced-file-mentions'))
+    const groupRow = page.locator('[role="treeitem"]').first()
+    await groupRow.waitFor({ timeout: 15_000 })
+    await groupRow.click()
+    const sessionRow = page.locator('[role="treeitem"]').nth(1)
+    await sessionRow.waitFor({ timeout: 10_000 })
+    await sessionRow.click()
+    await expect.poll(() => page.getByText(DONE, { exact: true }).count(), { timeout: 15_000 }).toBe(1)
+
+    // Exactly one prose mention links: `report.html` resolves to the written
+    // path; the shared `style.css` basename and unwritten `notes.md` stay code.
+    const mentions = page.locator('[class*="markdown"] code button')
+    await expect.poll(() => mentions.count(), { timeout: 10_000 }).toBe(1)
+    expect(await mentions.first().innerText()).toBe('report.html')
+    expect(await mentions.first().getAttribute('aria-label')).toBe('Open site/report.html')
+    expect(await mentions.first().getAttribute('title')).toBe('site/report.html')
+    // The turn still ends with its produced-files row (all three writes).
+    expect(await page.getByText('Produced', { exact: true }).count()).toBe(1)
+
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  }, 90_000)
+})
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 1418cf2aa6..a147ddbcb8 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -61,6 +61,7 @@
     "tests/shipped-composition.e2e.ts",
     "tests/startup-auto-selection.e2e.ts",
     "tests/produced-files.e2e.ts",
+    "tests/produced-file-mentions.e2e.ts",
     "tests/goal-bar.e2e.ts",
     "tests/subagent-conversation.e2e.ts",
     "tests/bash-abort-row.e2e.ts",
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index fdd1c41b80..2518ef28c8 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: d708621dbeb99615b0864e6977c8d2f387ae5265
-README.zh.md: e2cf9c3b32c86c2da39f09e4804c2ac69a3569f7
+README.md: 6182fa1281eec50f8898634cb466291b6ef1f5ff
+README.zh.md: 8b110ec7713dcda5972d0ea0d9a8042301906d99
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index d708621dbe..6182fa1281 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -50,7 +50,7 @@ The chat stats line takes its token accounting from the generic token-meter `tok
 
 `src/client/` is organized by domain. `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations and composed props, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` directories import contract files and never each other. `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components and the store factory stay internal and reach the page through apply's slot registrations.
 
-A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost.
+A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` seam — an absent service leaves the prose inert.
 
 ## Model Experience
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index e2cf9c3b32..8b110ec771 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -50,7 +50,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 `src/client/` 按领域组织。`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明与组合后的 props、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/` 目录只导入 contract 文件，彼此之间从不互相导入。`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件与 store factory 保持内部，经 apply 的 slot 注册抵达页面。
 
-完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。
+完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。收尾正文经由同一个开关参与其中：chat 视图向可选的 `chatFileMentions` service（ctx.get；由同一插件提供）索取收尾消息的行内代码词表，并把结果接进 MarkdownText 的 `fileMentions` seam——service 缺席时正文保持死文本。
 
 ## 模型体验
 
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 24325c714e..48a0558f34 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -313,6 +313,7 @@ export function apply(ctx: Context): void {
           actions.select(target)
           layout.openDetails()
         },
+        fileMentions: owner => ctx.get('chatFileMentions')?.forClosing(owner),
         openFile: (path) => {
           const cwd = sessions.list.getSnapshot().byId[sessionId]?.cwd
           void workspaces.openPath(resolveToolPath(cwd, path)).catch(() => {
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index bc1c6c7e32..8bb7f8aea4 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -15,7 +15,8 @@ import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import {
   IconThinkOutline14, JsonBlock, MarkdownText,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps, TurnTailOwnerProps } from '../contract/slots.ts'
+import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ChatViewSlotProps, ChatViewInjected, TurnTailOwnerProps } from '../contract/slots.ts'
 import { hasContentText } from './chat-flow.ts'
 import { MessageIconActions } from './MessageIconActions.tsx'
 import { ToolRow } from './ToolRow.tsx'
@@ -43,6 +44,8 @@ export interface AssistantMarkdownProps {
   onFork?: ((seq: number) => void) | undefined
   /** Turn-tail slot dispatch share and owner currency; omitted for a mid-turn assistant. */
   turnTail?: (Pick<PropsRenderSlots<'conversation.chat.turnTail'>, 'renderSlotChain'> & { owner: TurnTailOwnerProps }) | undefined
+  /** Prose file-mention factory (the injected face); omitted wherever `turnTail` is. */
+  fileMentions?: ChatViewInjected['fileMentions'] | undefined
   /** The message is not the transcript tail of a completed turn. */
   forkUnavailable?: boolean | undefined
   /** The owning view's locale seat, passed down as a plain prop. */
@@ -86,11 +89,25 @@ function ThinkRow({ text, running, t }: { text: string; running: boolean; t: Ass
 }
 
 export const AssistantMarkdown = memo(function AssistantMarkdown({
-  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, turnTail, t,
+  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, turnTail,
+  fileMentions, t,
 }: AssistantMarkdownProps) {
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
   const codeLabels = useMemo(() => ({ copyLabel: t('copy'), copiedLabel: t('copied') }), [t])
+  // Mention vocabulary for the closing prose. Keyed on the anchor seq, not the
+  // growing transcript: a settled turn's produced files are final, and a
+  // fresh identity per append would discard MarkdownText's cached parse for
+  // every settled closing message on every stream chunk. The window-prepend
+  // edge (a mid-turn window start later gaining earlier same-turn writes)
+  // leaves a mention unlinked until remount — never a wrong link.
+  const owner = turnTail?.owner
+  const mentions: MarkdownFileMentions | undefined = useMemo(
+    () => (owner === undefined ? undefined : fileMentions?.(owner)),
+    // Deliberately not `owner`: its identity changes per append while the
+    // seq-addressed vocabulary it yields does not.
+    [fileMentions, owner?.seq],
+  )
   const last = blocks.length - 1
   // Tool-call heads render as tool rows in the chat view's grouping pass, so
   // a node that is only those heads (or empty) would paint an empty root
@@ -107,7 +124,13 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
         {blocks.map((block, i) => {
           switch (block.kind) {
             case 'text': return (
-              <MarkdownText key={i} text={block.text} streaming={streaming} codeLabels={codeLabels} />
+              <MarkdownText
+                key={i}
+                text={block.text}
+                streaming={streaming}
+                codeLabels={codeLabels}
+                fileMentions={mentions}
+              />
             )
             case 'reasoning': return <ThinkRow key={i} text={block.text} running={streaming && i === last} t={t} />
             // Grouped into tool rows by ChatView; hasVisible above skips an empty shell.
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index b0907f5a80..c8ad485013 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -335,7 +335,8 @@ function StreamingTail({ useSession, t }: {
  * render through the declared keyed hole's renderSlot share).
  */
 export function ChatView({
-  useSession, useSessions, useStore, renderSlot, renderSlotChain, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt, t,
+  useSession, useSessions, useStore, renderSlot, renderSlotChain, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt,
+  fileMentions, t,
 }: ChatViewSlotProps) {
   const nodes = useSession(s => s.nodes)
   const turnTimings = useSession(s => s.turnTimings)
@@ -603,6 +604,7 @@ export function ChatView({
           turnTail={actionSeqs.has(node.seq)
             ? { renderSlotChain, owner: { nodes, seq: node.seq, openFile } }
             : undefined}
+          fileMentions={actionSeqs.has(node.seq) ? fileMentions : undefined}
           t={t}
         />
       )
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 89f7986dba..7e811da7a1 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -4,6 +4,7 @@ import type {
   InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook,
 } from '@deepseek-ai/dsh-client-ui-slots'
 import type { CommandNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { ComposerKeyboard, EditSelection, InputActions, InputNotice, InputState } from '../input/contract.ts'
 import type { createChatStore } from '../stores.ts'
@@ -158,6 +159,30 @@ export interface ConvViewOwnerProps {
   onInspectDone?: () => void
 }
 
+/**
+ * Optional prose file-mention provider, consumed via `ctx.get('chatFileMentions')`
+ * (optional-service convention): the chat view asks it for a closing message's
+ * inline-code vocabulary and threads the result into MarkdownText. Absent
+ * service — the providing plugin composed out of cordis.yml — turns the
+ * surface off; the prose renders inert code.
+ */
+export interface ChatFileMentions {
+  /**
+   * Mention vocabulary for the closing message the owner currency names.
+   * @param owner - Turn-tail owner currency (nodes, closing seq, opener).
+   * @returns The resolver MarkdownText consumes, or undefined when the turn
+   * produced nothing worth linking.
+   */
+  forClosing(owner: TurnTailOwnerProps): MarkdownFileMentions | undefined
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** Prose file-mention provider (ui-deliverables); reach via ctx.get — optional. */
+    chatFileMentions: ChatFileMentions
+  }
+}
+
 /**
  * Owner currency of the chat view's turn-tail hole: the finalized snapshot
  * and the closing assistant's anchor. Registrants derive their own facts
@@ -502,6 +527,13 @@ export interface ChatViewInjected {
   }
   /** Fork through the completed turn ending at the eligible message `seq`, then open the child. */
   forkAt: (seq: number) => void
+  /**
+   * Prose file-mention vocabulary for one closing message, from the optional
+   * {@link ChatFileMentions} service (resolved lazily per call, so composing
+   * the provider in or out takes effect live). Undefined when the service is
+   * absent or the turn produced nothing worth linking.
+   */
+  fileMentions: (owner: TurnTailOwnerProps) => MarkdownFileMentions | undefined
 }
 
 /** Full chat-view component props: runtime & the declared toolview/commandview holes' render share & store & injected & locale seat. */
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index 725868d57a..3ce8b64053 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -13,6 +13,7 @@ export type {
 export type { ToolCallBlock } from './contract/tool-call-model.ts'
 export type { ConversationKey } from './locales.ts'
 export type {
+  ChatFileMentions,
   ChatStore, ChatViewInjected, ChatViewSlotProps, CommandRowOwnerProps, CommandRowProps, ComposerBarInjected,
   ComposerChainProps, ConversationInjected,
   ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps,
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index b8cd94de52..cb11a1a5fd 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -154,6 +154,8 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     inspectCall,
     chatScroll,
     forkAt,
+    // Absent-service default; mention tests override with a real resolver.
+    fileMentions: () => undefined,
     // Mirrors the real lookup chain (conversation namespace, then common).
     t: makeTranslate(zh, commonZh),
   }
@@ -248,6 +250,45 @@ describe('chat-flow derivation', () => {
     expect([...assistantActionsSeqs(nodes, new Map([[1, 5]]))]).toEqual([5])
   })
 
+  it('threads the injected file-mention vocabulary into the closing prose only', () => {
+    const wrote = (seq: number, callId: string, path: string): ToolResultNode => ({
+      ...toolResult(seq, callId, 'write'),
+      callView: {
+        card: 'diff', title: 'Write', diffs: [{ path, oldText: null, newText: 'x' }], locations: [{ path }],
+      },
+    })
+    const h = makeHarness({
+      nodes: [
+        user(1, 'build it'),
+        assistant(2, 'writing `report.html` now', 1),
+        wrote(3, 'w', 'site/report.html'),
+        assistant(4, 'Wrote `report.html`; `notes.md` untouched.', 1),
+      ],
+      turnEnds: new Map([[1, 4]]),
+    })
+    // Stub provider mirroring the real service: only produced files resolve.
+    h.props.fileMentions = owner => ({
+      resolve: (value) => {
+        if (value !== 'report.html') return undefined
+        return {
+          open: () => { h.openFile(`for-seq-${String(owner.seq)}/site/report.html`) },
+          label: '打开 site/report.html',
+          title: 'site/report.html',
+        }
+      },
+    })
+    const view = render(<h.ChatView {...h.props} />)
+    // Exactly one live mention: the closing message links, the mid-turn
+    // narration stays inert code, and the unknown file resolves to nothing.
+    const mentions = view.container.querySelectorAll('code button')
+    expect(mentions).toHaveLength(1)
+    const mention = view.getByRole('button', { name: '打开 site/report.html' })
+    expect(mention.getAttribute('title')).toBe('site/report.html')
+    fireEvent.click(mention)
+    // The vocabulary was built from the closing message's own owner currency.
+    expect(h.openFile).toHaveBeenCalledWith('for-seq-4/site/report.html')
+  })
+
   it('runningTurnStartTime selects the latest turn/start without a turn/end', () => {
     expect(runningTurnStartTime(new Map([
       [1, { startTime: 1_000, endTime: 5_000 }],
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index ee4c23c18c..3d25f13e1a 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/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/client/ui-deliverables/README.md
-README.md: b8b0ea2ef1cbc9b18b905fc08b41278f403ef043
-README.zh.md: a16535b8a8d3625ca1cf90e88c6d9dca742d916b
+README.md: d6695f155907e7d92b35556588687b3f95e55b88
+README.zh.md: be360a5a1fbe8d904cedf104b28f64f1b0567d6b
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index b8b0ea2ef1..d6695f1559 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -8,6 +8,8 @@ Produced-files feature owner: registers the deliverables row a finished turn end
 
 `ProducedFiles` renders the row between the closing message's body and its IconActions footer: a quiet label, up to six chips (basename text, full path as the `title`), and an explicit remainder count past the cap. Each chip opens through the owner-supplied `openFile` — the same Host opener the tool rows use, with the chat view resolving relative paths against the session cwd. Design rationale: the [workspace file links Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md).
 
+The closing prose carries the same vocabulary. This plugin provides the `chatFileMentions` service the chat view consults per closing message: `producedFileMentions` resolves an inline-code token by exact path, or by being exactly the basename of exactly one produced path — a basename two paths share stays inert rather than guessing, so a mention link can never open the wrong file or 404. A resolved mention renders as the same underlined opener the row's chips are, with the full path as its `title`, and mentions never render inside anchors or streaming text. Decision record: the [inline file mentions Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md).
+
 ## Model Experience
 
 None, as the row is a pure client derivation over already-logged tool metadata and nothing here reaches a model request.
@@ -18,4 +20,4 @@ None; this package neither assembles nor sends provider requests.
 
 ## Known Limitations and Deferred Work
 
-- **Prose mentions stay inert.** An inline-code file name in the closing message does not open the file yet; linking it to the same `locations` vocabulary is the stacked follow-up.
+- **Mention matching is exact path or unique basename only.** A suffix mention (`out/index.html` written as `index.html` resolves; `deep/out/index.html` written as `out/index.html` does not) stays inert; widening the matcher is deferred until a real closing-message shape needs it.
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index a16535b8a8..be360a5a1f 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -8,6 +8,8 @@
 
 `ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个安静的标签、至多六枚 chip（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每枚 chip 经由 owner 提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
 
+收尾正文承载同一份词表。本插件提供 chat 视图按收尾消息查询的 `chatFileMentions` service：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析——两条路径共享的 basename 保持死文本而不猜测，因此提及链接永远不会打开错误的文件或 404。解析成功的提及渲染为与产物行 chip 相同的下划线 opener，完整路径作为其 `title`；提及绝不会渲染在锚点内部或流式文本里。决策记录：[行内文件提及 Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md)。
+
 ## 模型体验
 
 无。该行是对已记录工具元数据的纯客户端派生，这里没有任何内容进入模型请求。
@@ -18,4 +20,4 @@
 
 ## 已知限制与暂缓事项
 
-- **正文提及仍是死文本。**收尾消息里以行内代码写出的文件名尚不能点击打开；把它接到同一份 `locations` 词表是 stacked 的后续工作。
+- **提及匹配只认精确路径或唯一 basename。**后缀式提及（`out/index.html` 写作 `index.html` 可解析；`deep/out/index.html` 写作 `out/index.html` 则不行）保持死文本；放宽匹配器等真实的收尾消息形态需要时再做。
diff --git a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
index ab85869de2..0baff2872a 100644
--- a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
+++ b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
@@ -6,18 +6,13 @@
 
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { basename } from './turn-deliverables.ts'
 import type { NS } from './locales.ts'
 import css from './ProducedFiles.module.css'
 
 /** Files past this stay counted but unlisted: a refactor turn must not bury the answer. */
 const SHOWN = 6
 
-/** Trailing path segment, the part that identifies the file at a glance. */
-function basename(path: string): string {
-  const at = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
-  return at === -1 ? path : path.slice(at + 1)
-}
-
 /** Matched paths plus the opener and locale seats needed to present them. */
 export type ProducedFilesProps = Pick<TurnTailOwnerProps, 'openFile'> & {
   matched: readonly string[]
diff --git a/packages/client/ui-deliverables/src/client/index.ts b/packages/client/ui-deliverables/src/client/index.ts
index 6dc7bc4b84..816cdff520 100644
--- a/packages/client/ui-deliverables/src/client/index.ts
+++ b/packages/client/ui-deliverables/src/client/index.ts
@@ -1,16 +1,18 @@
 /**
  * Deliverables plugin, browser half: registers the produced-files row into
- * the chat view's turn-tail hole. All policy lives here — the derivation
- * from the mutation tools' `locations`, the chip cap, and the copy — so
- * composing this plugin out of cordis.yml removes the surface entirely; the
- * owning view renders an empty hole at zero cost.
+ * the chat view's turn-tail chain, and provides the `chatFileMentions`
+ * service that links inline-code mentions of produced files in the closing
+ * prose. All policy lives here — the derivation from the mutation tools'
+ * `locations`, the mention matching, the chip cap, and the copy — so
+ * composing this plugin out of cordis.yml removes both surfaces entirely;
+ * the owning view renders an empty chain and inert prose at zero cost.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
-import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import { ProducedFiles } from './ProducedFiles.tsx'
 import { en, NS, zh, type DeliverablesKey } from './locales.ts'
-import { selectProducedFiles } from './turn-deliverables.ts'
+import { producedFileMentions, producedForClosing, selectProducedFiles } from './turn-deliverables.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -39,4 +41,15 @@ export function apply(ctx: ClientContext): void {
       locale: NS,
     }, ProducedFiles),
   )
+  // The prose side of the same vocabulary: the chat view reaches this face
+  // via ctx.get, so its absence — this plugin composed out — is the off state.
+  const t = ctx.locale.bind(NS)
+  const mentions: ChatFileMentions = {
+    forClosing(owner) {
+      const paths = producedForClosing(owner.nodes, owner.seq)
+      if (paths.length === 0) return undefined
+      return producedFileMentions(paths, owner.openFile, path => t('produced.open', { name: path }))
+    },
+  }
+  ctx.provide('chatFileMentions', mentions)
 }
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index c9754d1da4..4316ddf8e6 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -4,6 +4,7 @@
  * own follow-along `locations`, never the closing prose.
  */
 import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 /**
@@ -88,3 +89,45 @@ export function selectProducedFiles(owner: TurnTailOwnerProps): readonly string[
   const paths = producedForClosing(nodes, seq)
   return paths.length === 0 ? null : paths
 }
+
+/**
+ * Trailing path segment, the part that identifies the file at a glance.
+ * @param path - Slash- or backslash-separated path.
+ * @returns The final segment, or the whole string when separator-free.
+ */
+export function basename(path: string): string {
+  const at = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
+  return at === -1 ? path : path.slice(at + 1)
+}
+
+/**
+ * File-mention vocabulary over one turn's produced paths, for the closing
+ * message's prose: an inline-code token opens the file it names. A token
+ * resolves by exact path, or by being exactly the basename of exactly one
+ * produced path — a basename two paths share stays inert rather than
+ * guessing, so a mention link can never open the wrong file or 404.
+ * @param paths - The turn's produced paths (tool order, already deduped).
+ * @param openFile - The chat view's file opener.
+ * @param label - Localizes the accessible open-label for a resolved path.
+ * @returns The resolver MarkdownText consumes; the full path rides `title`,
+ * the same disambiguator the row's chips carry.
+ */
+export function producedFileMentions(
+  paths: readonly string[],
+  openFile: (path: string) => void,
+  label: (path: string) => string,
+): MarkdownFileMentions {
+  return {
+    resolve(value) {
+      const path = paths.includes(value) ? value : onlyPathWithBasename(paths, value)
+      if (path === undefined) return undefined
+      return { open: () => { openFile(path) }, label: label(path), title: path }
+    },
+  }
+}
+
+/** The single produced path whose basename is exactly `value`, else undefined. */
+function onlyPathWithBasename(paths: readonly string[], value: string): string | undefined {
+  const matches = paths.filter(path => basename(path) === value)
+  return matches.length === 1 ? matches[0] : undefined
+}
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index 49e41ebd86..65af40d642 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -13,9 +13,10 @@ import type {
   AssistantMessageNode, ConversationNode, ToolResultNode, UserMessageNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply as applyLocale } from '@deepseek-ai/dsh-client-locale/client'
+import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { ProducedFiles } from '../src/client/ProducedFiles.tsx'
-import { producedForClosing, selectProducedFiles } from '../src/client/turn-deliverables.ts'
+import { basename, producedFileMentions, producedForClosing, selectProducedFiles } from '../src/client/turn-deliverables.ts'
 import { apply, inject } from '../src/client/index.ts'
 import { apply as applyNode } from '../src/index.ts'
 import { apply as applyInvariant } from '../src/invariant.ts'
@@ -141,6 +142,33 @@ describe('ProducedFiles row', () => {
   })
 })
 
+describe('producedFileMentions resolver', () => {
+  const label = (path: string) => `打开 ${path}`
+
+  it('resolves exact paths and unique basenames; ambiguity and unknowns stay unresolved', () => {
+    const opened: string[] = []
+    const resolver = producedFileMentions(
+      ['out/index.html', 'a/style.css', 'b/style.css'],
+      (path) => { opened.push(path) },
+      label,
+    )
+    // Unique basename resolves to its full path; the full path rides title.
+    const byBasename = resolver.resolve('index.html')
+    expect(byBasename?.label).toBe('打开 out/index.html')
+    expect(byBasename?.title).toBe('out/index.html')
+    byBasename?.open()
+    expect(opened).toEqual(['out/index.html'])
+    // An exact path resolves even when its basename is ambiguous.
+    const exact = resolver.resolve('a/style.css')
+    expect(exact?.title).toBe('a/style.css')
+    // A basename two paths share stays unresolved rather than guessing,
+    // and so does a token naming nothing the turn wrote.
+    expect(resolver.resolve('style.css')).toBeUndefined()
+    expect(resolver.resolve('notes.md')).toBeUndefined()
+    expect(basename('a\\b\\c.txt')).toBe('c.txt')
+  })
+})
+
 describe('package shells', () => {
   it('the node half mounts inert and the invariant companion registers ownership', async () => {
     // The node half is deliberately inert; mounting it must simply not throw.
@@ -172,7 +200,24 @@ describe('plugin registration', () => {
     await fiber.await()
     expect(ctx.slots.entries('conversation.chat.turnTail')).toHaveLength(1)
 
+    // The prose face is live while the plugin is: a produced turn yields a
+    // resolver whose matches open through the owner-supplied opener.
+    const opened: string[] = []
+    const owner = {
+      nodes: [user(1, 'go'), wrote(2, 'w', 'site/report.html'), assistant(3, 'done', 1)],
+      seq: 3,
+      openFile: (path: string) => { opened.push(path) },
+    }
+    const service = (ctx as unknown as { get(name: string): ChatFileMentions | undefined }).get('chatFileMentions')
+    const mentions = service?.forClosing(owner)
+    mentions?.resolve('report.html')?.open()
+    expect(opened).toEqual(['site/report.html'])
+    // A turn that produced nothing yields no vocabulary at all.
+    expect(service?.forClosing({ ...owner, nodes: [user(1, 'hi'), assistant(2, 'ok', 1)], seq: 2 })).toBeUndefined()
+
     await fiber.dispose()
     expect(ctx.slots.entries('conversation.chat.turnTail')).toHaveLength(0)
+    // Fiber teardown retracts the service: the consumer's ctx.get sees the off state.
+    expect((ctx as unknown as { get(name: string): unknown }).get('chatFileMentions')).toBeUndefined()
   })
 })
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 47cebf796f..f7598d7a90 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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/client/ui-primitives/README.md
-README.md: 7571cb48424b650a1aaa5222b33a3ee14faa69b4
-README.zh.md: fa0c3f24023ec8c1eb77553bfe191801b6698687
+README.md: a5f35c9a41008921c6a1e3a4de3fd3f38af926c0
+README.zh.md: 54c70ed29e73e196a9be60ddb794c12187dbe0c5
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 7571cb4842..a5f35c9a41 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -10,7 +10,7 @@ Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/
 
 ## Markdown rendering
 
-`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. A narrow micromark extension lets asterisk strong emphasis ending in punctuation close before adjacent CJK text, where prose normally omits the whitespace CommonMark requires; single-asterisk emphasis, non-CJK adjacency, escapes, code, and math retain upstream parsing. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. Inline code whose complete value is an absolute HTTP(S) URL keeps its code styling and gains the same safe external anchor; commands, partial URLs, other schemes, and fenced code remain inert. While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail behind them re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply ([mechanism and DOM-parity contract](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)). `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
+`MarkdownText` renders GFM and `$…$`, `$$…$$`, `\(…\)`, and `\[…\]` TeX math from untrusted assistant output through React elements, with math typeset by KaTeX and trusted commands disabled; block-level same-line `$$…$$` is display math, including `\tag{}`. A narrow micromark extension lets asterisk strong emphasis ending in punctuation close before adjacent CJK text, where prose normally omits the whitespace CommonMark requires; single-asterisk emphasis, non-CJK adjacency, escapes, code, and math retain upstream parsing. It omits raw HTML, neutralizes relative and non-HTTP(S)/mailto links, opens HTTP(S) links with safe external-link attributes, and renders absolute HTTP(S) images without a referrer; relative paths, absolute local paths, `file:` URLs, and unsupported schemes retain their alt text. Inline code whose complete value is an absolute HTTP(S) URL keeps its code styling and gains the same safe external anchor; commands, partial URLs, other schemes, and fenced code remain inert. An optional `fileMentions` resolver lets the owning view link inline code that names a real file: the token keeps code styling and gains a button wired to the resolved opener, with the resolver's accessible label and full-path `title`. The renderer never guesses at what looks like a path — an unresolved token stays inert, mentions apply to settled renders only (the streaming cache must not bake in handlers that could go stale), and a token inside an anchor stays inert because a button cannot nest there. While a reply streams, `MarkdownText` parses incrementally: all but the trailing two blocks freeze as cached React elements and only the source tail behind them re-parses per chunk, so per-chunk work tracks the tail instead of the whole reply ([mechanism and DOM-parity contract](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)). `MessageText` remains the literal-text primitive for user-authored content. `extractMarkdownPlainText` removes Markdown presentation markup for compact labels while preserving raw HTML as literal text. Element spacing, responsive images, tables, links, and inline code use the same `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` tokens as deepsuite `@deepseek/md`. Fenced blocks render through `CodeBlock` (language banner, copy control, shiki for the registered grammars).
 
 ## Terminal output
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index fa0c3f2402..54c70ed29e 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -10,7 +10,7 @@
 
 ## Markdown 渲染
 
-`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性契约](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
+`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有视图把命名真实文件的行内代码变成链接：token 保留代码样式并获得接到所解析 opener 的按钮，带解析器给出的无障碍标签与完整路径 `title`。渲染器绝不猜测什么长得像路径——未解析的 token 保持原样，提及只作用于已定稿的渲染（流式缓存不能烘进可能过期的 handler），锚点内部的 token 也保持原样，因为按钮不能嵌套在链接里。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性契约](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
 
 ## 终端输出
 
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index fe0235c496..30a1dae402 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -40,7 +40,7 @@ export { CodeBlock } from './markdown/CodeBlock.tsx'
 export type { CodeBlockProps } from './markdown/CodeBlock.tsx'
 export { JsonBlock } from './markdown/JsonBlock.tsx'
 export { MarkdownText } from './markdown/MarkdownText.tsx'
-export type { MarkdownCodeLabels } from './markdown/MarkdownText.tsx'
+export type { MarkdownCodeLabels, MarkdownFileMentions } from './markdown/MarkdownText.tsx'
 export { MessageText } from './markdown/MessageText.tsx'
 export { extractMarkdownPlainText } from './markdown/plain-text.ts'
 export type { MarkdownPlainTextMode, MarkdownPlainTextOptions } from './markdown/plain-text.ts'
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
index 7e31857053..19375be18e 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
@@ -241,3 +241,23 @@
   background: var(--dsw-alias-bg-base);
   object-fit: contain;
 }
+
+/* Inline file mention: a real file named in prose is the same affordance as a
+   tool row's path link, so it reads the same — underlined at rest. */
+.fileMention {
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  font: inherit;
+  color: var(--dsw-alias-label-secondary);
+  text-decoration: underline;
+  text-decoration-color: var(--dsw-alias-label-quaternary);
+  text-underline-offset: 3px;
+  cursor: pointer;
+}
+
+.fileMention:hover {
+  color: var(--dsw-alias-label-primary);
+  text-decoration-color: currentColor;
+}
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.tsx b/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
index bb4b62514c..4dff78d784 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.tsx
@@ -19,20 +19,25 @@ import {
   collectReferenceTargets, createReferenceTargets, renderBlocks, renderFootnoteSection,
   wrapBlockChildren,
 } from './render.tsx'
-import type { MarkdownCodeLabels, MarkdownRenderContext, ReferenceTargets } from './render.tsx'
+import type { MarkdownCodeLabels, MarkdownFileMentions, MarkdownRenderContext, ReferenceTargets } from './render.tsx'
 import 'katex/dist/katex.min.css'
 import css from './MarkdownText.module.css'
 
-export type { MarkdownCodeLabels } from './render.tsx'
+export type { MarkdownCodeLabels, MarkdownFileMentions } from './render.tsx'
 
 /** One settled full render: parse with math, resolve references, append the footnote section. */
-function renderSettled(text: string, codeLabels: MarkdownCodeLabels | undefined): ReactNode[] {
+function renderSettled(
+  text: string,
+  codeLabels: MarkdownCodeLabels | undefined,
+  fileMentions: MarkdownFileMentions | undefined,
+): ReactNode[] {
   const root = parseGfmWithMath(text)
   const targets = createReferenceTargets()
   collectReferenceTargets(root.children, targets)
   const context: MarkdownRenderContext = {
     streaming: false,
     codeLabels,
+    fileMentions,
     targets,
     footnoteOrder: [],
     footnoteCounts: new Map(),
@@ -96,6 +101,7 @@ class StreamingRenderer {
       const frozenContext: MarkdownRenderContext = {
         streaming: true,
         codeLabels: this.codeLabels,
+        fileMentions: undefined,
         targets: frameTargets,
         footnoteOrder: this.frozenFootnoteOrder,
         footnoteCounts: this.frozenFootnoteCounts,
@@ -113,6 +119,7 @@ class StreamingRenderer {
     const tailContext: MarkdownRenderContext = {
       streaming: true,
       codeLabels: this.codeLabels,
+      fileMentions: undefined,
       targets: frameTargets,
       footnoteOrder: [...this.frozenFootnoteOrder],
       footnoteCounts: new Map(this.frozenFootnoteCounts),
@@ -137,28 +144,33 @@ class StreamingRenderer {
  * the finalize swap) and parses incrementally across chunks; `codeLabels`
  * forwards localized copy-button labels to fence CodeBlocks — pass a
  * reference-stable object (memoized per locale revision), because a new
- * identity discards the streaming render cache mid-message.
+ * identity discards the streaming render cache mid-message. `fileMentions`
+ * links inline-code tokens its resolver recognizes as real files; this is
+ * the single streaming gate — it applies to settled renders only, because a
+ * streaming message's vocabulary is not final and frozen cached elements
+ * must not bake in handlers that could go stale.
  * @returns A GFM document with TeX math rendered through KaTeX; raw HTML,
  * relative links, and unsafe protocols are disabled, while absolute HTTP(S)
  * images render directly.
  */
-export const MarkdownText = memo(function MarkdownText({ text, streaming = false, codeLabels }: {
+export const MarkdownText = memo(function MarkdownText({ text, streaming = false, codeLabels, fileMentions }: {
   text: string
   streaming?: boolean
   codeLabels?: MarkdownCodeLabels | undefined
+  fileMentions?: MarkdownFileMentions | undefined
 }) {
   const streamRef = useRef<StreamingRenderer | null>(null)
   const streamLabelsRef = useRef<MarkdownCodeLabels | undefined>(codeLabels)
   const children = useMemo(() => {
     if (!streaming) {
       streamRef.current = null
-      return renderSettled(text, codeLabels)
+      return renderSettled(text, codeLabels, fileMentions)
     }
     if (streamRef.current === null || streamLabelsRef.current !== codeLabels) {
       streamRef.current = new StreamingRenderer(codeLabels)
       streamLabelsRef.current = codeLabels
     }
     return streamRef.current.render(text)
-  }, [text, streaming, codeLabels])
+  }, [text, streaming, codeLabels, fileMentions])
   return <div className={css.markdown}>{children}</div>
 })
diff --git a/packages/client/ui-primitives/src/markdown/render.tsx b/packages/client/ui-primitives/src/markdown/render.tsx
index 4ac8b4dbc1..452e0fc475 100644
--- a/packages/client/ui-primitives/src/markdown/render.tsx
+++ b/packages/client/ui-primitives/src/markdown/render.tsx
@@ -99,6 +99,21 @@ export function collectReferenceTargets(
   }
 }
 
+/**
+ * File-mention affordance for inline code: the owner resolves an authored
+ * token to the file it names, using its own vocabulary of real files — the
+ * renderer never guesses at what looks like a path.
+ */
+export interface MarkdownFileMentions {
+  /**
+   * Resolve one inline-code token.
+   * @param value - The authored token, exactly as written.
+   * @returns The opener with its accessible label and full-path title, or
+   * undefined when the token names no known file — it then stays inert code.
+   */
+  resolve(value: string): { open: () => void; label: string; title: string } | undefined
+}
+
 /**
  * One render pass's state: immutable options and targets plus the footnote
  * numbering accumulated in document order while references render.
@@ -108,6 +123,10 @@ export interface MarkdownRenderContext {
   readonly streaming: boolean
   /** Localized fence copy-button labels. */
   readonly codeLabels: MarkdownCodeLabels | undefined
+  /** Inline-code file mentions; absent wherever no opener vocabulary exists. */
+  readonly fileMentions: MarkdownFileMentions | undefined
+  /** Inside an anchor's children: interactive mentions must not nest there. */
+  readonly inLink?: boolean
   /** Reference targets visible to this pass. */
   readonly targets: ReferenceTargets
   /** Footnote identifiers in first-reference order; a footnote's number is its 1-based index here. */
@@ -217,7 +236,27 @@ function renderNode(node: Md.RootContent, key: Key, context: MarkdownRenderConte
       // authored text, not a parsed destination, so no normalizeUri: port,
       // path, and query render unchanged.
       const href = inlineCodeHttpUrl(value)
-      return <code key={key}>{href === undefined ? value : renderSafeLink(href, [value], 'link')}</code>
+      if (href !== undefined) return <code key={key}>{renderSafeLink(href, [value], 'link')}</code>
+      // A token the owner's file-mention vocabulary recognizes opens that
+      // file; the resolver, not this renderer, decides what names a file.
+      // Inside an anchor the token stays inert — a button cannot nest there.
+      const mention = context.inLink === true ? undefined : context.fileMentions?.resolve(value)
+      if (mention !== undefined) {
+        return (
+          <code key={key}>
+            <button
+              type="button"
+              className={css.fileMention}
+              title={mention.title}
+              aria-label={mention.label}
+              onClick={mention.open}
+            >
+              {value}
+            </button>
+          </code>
+        )
+      }
+      return <code key={key}>{value}</code>
     }
     case 'html':
       // No HTML parser enters the pipeline: raw HTML stays literal text.
@@ -236,7 +275,7 @@ function renderNode(node: Md.RootContent, key: Key, context: MarkdownRenderConte
     case 'table':
       return renderTable(node, key, context)
     case 'link':
-      return renderAnchor(node.url, renderChildren(node.children, context), key)
+      return renderAnchor(node.url, renderChildren(node.children, { ...context, inLink: true }), key)
     case 'linkReference':
       return renderLinkReference(node, key, context)
     case 'image':
@@ -460,14 +499,14 @@ function renderLinkReference(
   context: MarkdownRenderContext,
 ): ReactNode {
   const definition = context.targets.definitions.get(node.identifier.toUpperCase())
-  const children = renderChildren(node.children, context)
   if (definition === undefined) {
     // The grammar only emits references whose definitions exist somewhere in
     // the same parse, but incremental segments and hand-built trees may still
-    // present unresolved ones: revert to the bracketed source text.
-    return <Fragment key={key}>{'['}{children}{referenceSuffix(node)}</Fragment>
+    // present unresolved ones: revert to the bracketed source text — which is
+    // not an anchor, so mentions inside it stay live.
+    return <Fragment key={key}>{'['}{renderChildren(node.children, context)}{referenceSuffix(node)}</Fragment>
   }
-  return renderAnchor(definition.url, children, key)
+  return renderAnchor(definition.url, renderChildren(node.children, { ...context, inLink: true }), key)
 }
 
 function renderImageReference(
diff --git a/packages/client/ui-primitives/tests/markdown-render-units.spec.tsx b/packages/client/ui-primitives/tests/markdown-render-units.spec.tsx
index 48dd03f5c5..48f59c7479 100644
--- a/packages/client/ui-primitives/tests/markdown-render-units.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown-render-units.spec.tsx
@@ -20,6 +20,7 @@ function makeContext(): MarkdownRenderContext {
   return {
     streaming: false,
     codeLabels: undefined,
+    fileMentions: undefined,
     targets: createReferenceTargets(),
     footnoteOrder: [],
     footnoteCounts: new Map(),
diff --git a/packages/client/ui-primitives/tests/markdown.spec.tsx b/packages/client/ui-primitives/tests/markdown.spec.tsx
index 5066e32cd2..89ffd32346 100644
--- a/packages/client/ui-primitives/tests/markdown.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown.spec.tsx
@@ -148,6 +148,49 @@ describe('MarkdownText', () => {
     expect(container.querySelector('pre code a')).toBeNull()
   })
 
+  it('links inline code through the file-mention resolver: URL first, settled only, never inside links', () => {
+    const opened: string[] = []
+    const fileMentions = {
+      resolve: (value: string) => value === 'index.html' || value === 'out/index.html'
+        ? { open: () => { opened.push(value) }, label: 'Open out/index.html', title: 'out/index.html' }
+        : undefined,
+    }
+    const source = [
+      '`index.html`',
+      '`other.css`',
+      '`https://example.com/`',
+      // Inside an anchor the mention stays inert code: a button cannot nest there.
+      '[see `out/index.html`](https://example.com/doc)',
+      '[ref `out/index.html`][target]',
+      '[target]: https://example.com/ref',
+      '```',
+      'index.html',
+      '```',
+    ].join('\n\n')
+    const { container } = render(<MarkdownText text={source} fileMentions={fileMentions} />)
+
+    const mention = screen.getByRole('button', { name: 'Open out/index.html' })
+    expect(mention.closest('code')).not.toBeNull()
+    // The full path rides title, the same disambiguator the row's chips carry.
+    expect(mention.getAttribute('title')).toBe('out/index.html')
+    fireEvent.click(mention)
+    expect(opened).toEqual(['index.html'])
+    // Exactly one live mention: the two inside anchors declined, and an
+    // unresolved token plus fenced code stay inert.
+    expect(container.querySelectorAll('code button')).toHaveLength(1)
+    expect(container.querySelectorAll('a code button, a button')).toHaveLength(0)
+    expect(screen.getByText('other.css').closest('button')).toBeNull()
+    // URL promotion wins before the resolver sees a token.
+    expect(screen.getByText('https://example.com/').closest('a')).not.toBeNull()
+
+    // Streaming renders keep mentions off — the one gate lives here: cached
+    // frozen elements must not bake in handlers that could go stale.
+    const streamed = render(
+      <MarkdownText text={'`index.html`\n\nmore\n\n'} streaming fileMentions={fileMentions} />,
+    )
+    expect(streamed.container.querySelector('button')).toBeNull()
+  })
+
   it('exposes the CJK strong syntax as a micromark extension needing CommonMark attention markers', () => {
     const extension = cjkFriendlyStrong()
     expect(cjkFriendlyStrong()).toBe(extension)
diff --git a/tsconfig.host.json b/tsconfig.host.json
index ad2b5e32f1..d4f7eb8650 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -49,6 +49,7 @@
     "apps/web/tests/goal-bar.e2e.ts",
     "apps/web/tests/startup-auto-selection.e2e.ts",
     "apps/web/tests/produced-files.e2e.ts",
+    "apps/web/tests/produced-file-mentions.e2e.ts",
     "apps/web/tests/subagent-conversation.e2e.ts",
     "apps/web/tests/bash-abort-row.e2e.ts",
     "apps/web/tests/skill-tool-row.e2e.ts",

From f3049e5663c74c9a33ea4934049ec5438d2e259f Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 18:07:15 +0800
Subject: [PATCH 109/516] fix(llm-pi-ai): describing a model must not fail on a
 bad profile level
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`resolveModel` validated the profile's reasoning level against the exact
model and threw when it did not fit. That call builds the model catalog,
and the catalog build catches per PROVIDER — so one mis-set field took the
whole provider out of every picker behind a single error row, hiding even
the models that do support the level. Measured: `anthropic` set to `max`
threw for six of its eight models.

Describing what a model can do now reports an unusable profile level as no
default rather than throwing; the request path still refuses it, which is
where a bad configuration belongs. The existing spec asserted the old
throw and now asserts both halves of that split.

Known gap, left deliberately: a model that cannot take the route's level
still fails its first request while the picker shows 「Default」 for it,
because the request path keeps using the profile level as the fallback.
Reaching that needs a hand-written `settings.yaml` — the Models page no
longer writes the field — and the error names the model and the level, so
selecting a supported level is a way out. Closing it properly means giving
`AgentOptions` a `reasoningEffort` so compositions without a model picker
keep an entry point, then dropping the provider-scoped field altogether;
that is its own change.
---
 packages/llm/llm-pi-ai/README.i18n.yaml      |  4 ++--
 packages/llm/llm-pi-ai/README.md             |  2 +-
 packages/llm/llm-pi-ai/README.zh.md          |  2 +-
 packages/llm/llm-pi-ai/src/adapter.ts        | 25 +++++++++++++++++++-
 packages/llm/llm-pi-ai/tests/adapter.spec.ts | 15 ++++++++++--
 5 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 6ea82781de..b57043a84d 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: a8686aa6f26095a9dd40c447aa0d0f61f7bc5412
-README.zh.md: 8f190097b543fe1d0324daa37a162cdc91d3e2dc
+README.md: 97bd629adedda9d63fee730bc31129b0c22cc704
+README.zh.md: 71d45b590f48f4b8162ae329b58b5ff4a9eb13b1
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index a8686aa6f2..97bd629ade 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -73,7 +73,7 @@ The adapter exposes each configured route's models through `ctx.llm.listModels(p
 
 A model that carries reasoning metadata exposes pi-ai's ordered `getSupportedThinkingLevels(model)` result without filtering or normalization, including `off` and the model-specific availability of `xhigh` or `max`. The Harness exposes each canonical pi-ai level as an opaque ID; provider/model wire spellings remain inside pi-ai's `thinkingLevelMap`.
 
-A model **without** that metadata — every hand-declared one, and a catalog model pi-ai marks as non-reasoning — exposes no `reasoning` at all. pi-ai reports such a model as supporting the single level `off`, but `off` is translated to *omitting* the reasoning option, which is byte-for-byte the request that naming no effort already produces: selecting it could not disable anything, so a provider whose own default is to think would keep thinking with `off` shown as selected. Reporting the capability as unavailable leaves a surface offering the provider's default and nothing that misrepresents it. The profile `reasoning` value, including `off`, is the deployment default when configured; omitting it preserves the provider default. Per-request `GenerateOptions.reasoningEffort` takes precedence, and any explicit value absent from the exact model capability fails with `UNSUPPORTED_REASONING_EFFORT` before network I/O instead of being clamped. pi-ai's common stream options represent `off` by omitting `reasoning`.
+A model **without** that metadata — every hand-declared one, and a catalog model pi-ai marks as non-reasoning — exposes no `reasoning` at all. pi-ai reports such a model as supporting the single level `off`, but `off` is translated to *omitting* the reasoning option, which is byte-for-byte the request that naming no effort already produces: selecting it could not disable anything, so a provider whose own default is to think would keep thinking with `off` shown as selected. Reporting the capability as unavailable leaves a surface offering the provider's default and nothing that misrepresents it. The profile `reasoning` value, including `off`, is the deployment default when configured; omitting it preserves the provider default. Per-request `GenerateOptions.reasoningEffort` takes precedence, and a level absent from the exact model capability fails the REQUEST with `UNSUPPORTED_REASONING_EFFORT` before network I/O instead of being clamped. Describing a model never fails that way: the models under one provider disagree about which levels they accept, so `resolveModel` reports a profile level the exact model cannot take as no default at all rather than throwing. A throw there would take the whole provider out of every model catalog built over it — one mis-set profile field hiding even the models that do support the level — so a bad configuration surfaces where it is acted on, not where it is described. pi-ai's common stream options represent `off` by omitting `reasoning`.
 
 Supported profile fields are `apiKey`, `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `defaultContextWindow`, `defaultMaxTokens`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
 
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index 8f190097b5..71d45b590f 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -73,7 +73,7 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 携带推理元数据的模型会公开 pi-ai 有序的 `getSupportedThinkingLevels(model)` 结果，不经筛选或规范化，其中包括 `off`，以及模型对 `xhigh` 或 `max` 的特定支持。Harness 将每个规范 pi-ai 级别公开为不透明 ID；提供方／模型在协议格式中的表示仍保留在 pi-ai 的 `thinkingLevelMap` 中。
 
-**没有**这份元数据的模型——每一个手工声明的模型，以及 pi-ai 标记为不具备推理能力的 catalog 模型——完全不公开 `reasoning`。pi-ai 会把这类模型报告为只支持 `off` 一档，但 `off` 会被翻译成*省略* reasoning 选项，而那与「不点名任何档位」产出的请求逐字节相同：选它关不掉任何东西，于是自身默认就在思考的提供方，会在界面显示 `off` 被选中的同时继续思考。把该能力报告为不可用，界面就只剩提供方默认这一项，不会再出现自相矛盾的控件。配置 profile 的 `reasoning` 值（包括 `off`）在存在时是部署默认值；省略它会保留提供方默认值。每次请求的 `GenerateOptions.reasoningEffort` 优先；任何未出现在确切模型能力中的显式值都会在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败，而不会被自动调整。pi-ai 的通用流选项通过省略 `reasoning` 表示 `off`。
+**没有**这份元数据的模型——每一个手工声明的模型，以及 pi-ai 标记为不具备推理能力的 catalog 模型——完全不公开 `reasoning`。pi-ai 会把这类模型报告为只支持 `off` 一档，但 `off` 会被翻译成*省略* reasoning 选项，而那与「不点名任何档位」产出的请求逐字节相同：选它关不掉任何东西，于是自身默认就在思考的提供方，会在界面显示 `off` 被选中的同时继续思考。把该能力报告为不可用，界面就只剩提供方默认这一项，不会再出现自相矛盾的控件。配置 profile 的 `reasoning` 值（包括 `off`）在存在时是部署默认值；省略它会保留提供方默认值。每次请求的 `GenerateOptions.reasoningEffort` 优先；未出现在确切模型能力中的档位会让**请求**在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败，而不会被自动调整。**描述**一个模型则从不这样失败：同一提供方下各模型接受的档位并不一致，因此 `resolveModel` 对该模型拿不下的 profile 档位报告为「没有默认值」，而不是抛错。在那里抛错会让整个提供方从任何基于它构建的模型目录中消失——一个配错的 profile 字段连支持该档位的模型也一并藏起来——所以坏配置暴露在被执行处，而不是被描述处。pi-ai 的通用流选项通过省略 `reasoning` 表示 `off`。
 
 受支持的 profile 字段是 `apiKey`、`apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`defaultContextWindow`、`defaultMaxTokens`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs` 和 `retryPolicy`。每个 profile 的可选重试策略都会与该提供方路由一同捕获；省略时使用有界的常规默认值。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。若已配置标头中有同名项，则以 Harness 应用归因为准。
 
diff --git a/packages/llm/llm-pi-ai/src/adapter.ts b/packages/llm/llm-pi-ai/src/adapter.ts
index 365c3901a5..e974cdff7c 100644
--- a/packages/llm/llm-pi-ai/src/adapter.ts
+++ b/packages/llm/llm-pi-ai/src/adapter.ts
@@ -94,6 +94,29 @@ function profileOptions(
   }
 }
 
+/**
+ * The profile default this exact model can actually take, for DESCRIBING it.
+ * A configured level the model does not support yields none rather than
+ * throwing: `resolveModel` builds the model catalog, and a catalog that fails
+ * takes its whole provider out of every picker — so one mis-set profile field
+ * would hide every model on the route, including the ones that support the
+ * level. The request path still refuses, which is where a bad configuration
+ * belongs: describing what a model can do must not fail because a deployment
+ * asked it for something it cannot.
+ * @param model - the resolved model descriptor.
+ * @param effort - the profile's configured level, if any.
+ * @returns the level when this model supports it, otherwise undefined.
+ */
+function describableReasoningLevel(
+  model: Model<Api>,
+  effort: ReasoningEffortIdType | ModelThinkingLevel | undefined,
+): ModelThinkingLevel | undefined {
+  if (effort === undefined) return undefined
+  return getSupportedThinkingLevels(model).some(level => level === effort)
+    ? effort as ModelThinkingLevel
+    : undefined
+}
+
 /** Validate an explicit Harness/profile effort without invoking pi-ai's clamp. */
 function resolveReasoningLevel(
   model: Model<Api>,
@@ -229,7 +252,7 @@ export class PiAiAdapter extends LlmAdapter {
       const snapshot = this.current()
       const profile = this.profileOf(snapshot, provider)
       const resolvedModel = this.modelOf(snapshot, provider, model)
-      const defaultLevel = resolveReasoningLevel(resolvedModel, profile.reasoning)
+      const defaultLevel = describableReasoningLevel(resolvedModel, profile.reasoning)
       // Only a cap the deployment configured is a request default; the
       // catalog's `maxTokens` sizes the model and stops there.
       const configuredMaxTokens = profile.configuredMaxTokens.get(model)
diff --git a/packages/llm/llm-pi-ai/tests/adapter.spec.ts b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
index a9c4335a92..0184ca05cc 100644
--- a/packages/llm/llm-pi-ai/tests/adapter.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
@@ -372,13 +372,24 @@ describe('provider profile lifecycle', () => {
     await expect(supported.llm.resolveModelInfo('deepseek', 'deepseek-v4-flash'))
       .resolves.toMatchObject({ reasoning: { defaultEffort: ReasoningEffortId('max') } })
 
+    // A profile level this model cannot take DESCRIBES as no default rather
+    // than failing: resolveModelInfo builds the model catalog, and a catalog
+    // that throws takes its whole provider out of every picker — one mis-set
+    // field would hide every model on the route, including the ones that do
+    // support the level. The request path below is where it is refused.
     const unsupported = new Context()
     await unsupported.plugin(LlmService)
     await unsupported.plugin(LlmPiAi, {
       providers: { deepseek: { reasoning: 'medium' } },
     })
-    await expect(unsupported.llm.resolveModelInfo('deepseek', 'deepseek-v4-flash'))
-      .rejects.toMatchObject({ code: 'UNSUPPORTED_REASONING_EFFORT' })
+    const described = await unsupported.llm.resolveModelInfo('deepseek', 'deepseek-v4-flash')
+    expect(described.reasoning?.defaultEffort).toBeUndefined()
+    expect(described.reasoning?.efforts.length).toBeGreaterThan(0)
+    await expect(assemble(unsupported, {
+      provider: 'deepseek', model: 'deepseek-v4-flash', messages: [],
+    })).resolves.toMatchObject({
+      finish: { kind: 'error', failure: { code: 'UNSUPPORTED_REASONING_EFFORT' } },
+    })
 
     const disabled = new Context()
     await disabled.plugin(LlmService)

From b1074e60ab64f7a99e21ab3cd0bb655d62a9f3c1 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 7 Aug 2026 18:54:50 +0800
Subject: [PATCH 110/516] test(web): re-record the skill-tool-row golden for
 the resolved seat label

Master added this scenario while this branch was open, so its golden froze
the composer seat's "Select model" fallback. The scaffold's route-only
adapter (added here for fixture-less scenarios) makes the seat resolve the
model those scenarios actually route to, which is what the other eight
goldens on this branch already show. Only the two seat lines move.
---
 apps/web/tests/snapshots/skill-tool-row/ui.expected.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/web/tests/snapshots/skill-tool-row/ui.expected.md b/apps/web/tests/snapshots/skill-tool-row/ui.expected.md
index fc1f23d484..15ddf45a0d 100644
--- a/apps/web/tests/snapshots/skill-tool-row/ui.expected.md
+++ b/apps/web/tests/snapshots/skill-tool-row/ui.expected.md
@@ -38,8 +38,8 @@
 - button "Commands":
   - img
 - 'button "Access mode, current: Workspace Write"': Workspace Write
-- button "Select model":
-  - text: Select model
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
   - img
 - button "Send message" [disabled]
 - text: 1 turns · 2 steps LLM {{duration}} · Tool call {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 280 tok · Output 30 tok

From 2da1309836e36320cd2a6818e576feaeb01f5558 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 23:46:43 +0800
Subject: [PATCH 111/516] fix: npm publish for profile

---
 scripts/publish-npm-baseline.ts | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/scripts/publish-npm-baseline.ts b/scripts/publish-npm-baseline.ts
index 92df711f3e..20b9eeaea0 100644
--- a/scripts/publish-npm-baseline.ts
+++ b/scripts/publish-npm-baseline.ts
@@ -463,13 +463,6 @@ class InstalledBundleSmoke {
           + `expected ${this.bundle.manifest.version}`,
         )
       }
-      const config = this.runner.capture(
-        process.execPath,
-        [bin, '--dump-default-config'],
-        consumerRoot,
-        environment,
-      )
-      if (config === '') throw new Error('installed dsh --dump-default-config returned no output')
       this.probeWeb(bin, consumerRoot, environment)
       console.log('publish-npm-baseline: installed dsh entry and Web startup probes passed')
     } finally {

From 7ef39dc4b02795260c483c449b632303f95f6634 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Fri, 7 Aug 2026 05:00:47 -0700
Subject: [PATCH 112/516] refactor(deliverables): reuse the chain claim test
 for the mention vocabulary

---
 packages/client/ui-deliverables/src/client/index.ts | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/client/ui-deliverables/src/client/index.ts b/packages/client/ui-deliverables/src/client/index.ts
index 816cdff520..81b2f61b79 100644
--- a/packages/client/ui-deliverables/src/client/index.ts
+++ b/packages/client/ui-deliverables/src/client/index.ts
@@ -12,7 +12,7 @@ import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-conversation/c
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import { ProducedFiles } from './ProducedFiles.tsx'
 import { en, NS, zh, type DeliverablesKey } from './locales.ts'
-import { producedFileMentions, producedForClosing, selectProducedFiles } from './turn-deliverables.ts'
+import { producedFileMentions, selectProducedFiles } from './turn-deliverables.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -46,8 +46,10 @@ export function apply(ctx: ClientContext): void {
   const t = ctx.locale.bind(NS)
   const mentions: ChatFileMentions = {
     forClosing(owner) {
-      const paths = producedForClosing(owner.nodes, owner.seq)
-      if (paths.length === 0) return undefined
+      // Same claim test the turn-tail chain entry runs: no produced files,
+      // no vocabulary — the two surfaces agree by construction.
+      const paths = selectProducedFiles(owner)
+      if (paths === null) return undefined
       return producedFileMentions(paths, owner.openFile, path => t('produced.open', { name: path }))
     },
   }

From 4c45355012bdc0d86d0fb8abe7e37c56b1e7c351 Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Fri, 7 Aug 2026 05:06:21 -0700
Subject: [PATCH 113/516] style(web): mention chips take the markdown anchor
 language

Link-blue at rest with hover underline, matching URL-promoted inline
code; an at-rest underline collides with monospace descenders inside
the code chip.
---
 ...6-08-07-web-inline-file-mentions.i18n.yaml |  4 ++--
 .../2026-08-07-web-inline-file-mentions.md    |  2 +-
 .../2026-08-07-web-inline-file-mentions.zh.md |  2 +-
 .../client/ui-deliverables/README.i18n.yaml   |  4 ++--
 packages/client/ui-deliverables/README.md     |  2 +-
 packages/client/ui-deliverables/README.zh.md  |  2 +-
 .../src/markdown/MarkdownText.module.css      | 20 ++++++++++---------
 7 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
index e8fe387234..8153420c3d 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.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 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
-2026-08-07-web-inline-file-mentions.md: 79c6bddd500dc0b68bf64f3c4bea114ca41b4b62
-2026-08-07-web-inline-file-mentions.zh.md: ddc54d3b43570b19fb23c1c9c8079ef4ca65f8fa
+2026-08-07-web-inline-file-mentions.md: 581efb5a9eb497e030d19118d52d003b37118108
+2026-08-07-web-inline-file-mentions.zh.md: 25c8ca6e106cd877a4d46a7b1338728e96771fc1
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
index 79c6bddd50..581efb5a9e 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
@@ -25,4 +25,4 @@ The produced-files row lists a turn's output, but the closing message usually al
 
 ## Consequences
 
-The mention and the row are two affordances for one fact, styled alike (underlined at rest, full path as `title`). `apps/web/tests/produced-file-mentions.e2e.ts` pins the assembled behavior with a built write-turn seed: unique basename links, ambiguous and unknown tokens stay inert; it does not click, for the produced-files restraint (the opener launches a real application). Mentions in mid-turn narration stay inert even for files the turn later produces, because the vocabulary attaches to the closing message only. The window-prepend edge — a window that starts mid-turn later gaining earlier same-turn writes — leaves a mention unlinked until remount, never wrongly linked.
+The mention and the row are two affordances for one fact (full path as `title` on both); the mention itself wears the markdown sheet's anchor language — link-blue at rest, hover underline — because an at-rest underline collides with monospace descenders inside the code chip. `apps/web/tests/produced-file-mentions.e2e.ts` pins the assembled behavior with a built write-turn seed: unique basename links, ambiguous and unknown tokens stay inert; it does not click, for the produced-files restraint (the opener launches a real application). Mentions in mid-turn narration stay inert even for files the turn later produces, because the vocabulary attaches to the closing message only. The window-prepend edge — a window that starts mid-turn later gaining earlier same-turn writes — leaves a mention unlinked until remount, never wrongly linked.
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
index ddc54d3b43..25c8ca6e10 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
@@ -25,4 +25,4 @@ Status: implemented
 
 ## 后果
 
-提及与产物行是同一事实的两个交互面，样式一致（静止即下划线，完整路径作为 `title`）。`apps/web/tests/produced-file-mentions.e2e.ts` 用构造的写入轮 seed 钉住组装后的行为：唯一 basename 成链，歧义与未知 token 保持死文本；它不驱动点击，沿用产物行的克制（opener 会启动真实应用）。轮次中途叙述里的提及即使命名了本轮后来产出的文件也保持死文本，因为词表只挂在收尾消息上。窗口前插的边界——从轮次中途开始的窗口后来补入了同轮更早的写入——只会让提及在重挂载前暂不成链，绝不会错链。
+提及与产物行是同一事实的两个交互面（两者都以完整路径作 `title`）；提及本身采用 markdown 样式表的锚点语言——静止为链接蓝、悬停出下划线——因为静止下划线在 code 胶囊里会压住等宽字的下伸部。`apps/web/tests/produced-file-mentions.e2e.ts` 用构造的写入轮 seed 钉住组装后的行为：唯一 basename 成链，歧义与未知 token 保持死文本；它不驱动点击，沿用产物行的克制（opener 会启动真实应用）。轮次中途叙述里的提及即使命名了本轮后来产出的文件也保持死文本，因为词表只挂在收尾消息上。窗口前插的边界——从轮次中途开始的窗口后来补入了同轮更早的写入——只会让提及在重挂载前暂不成链，绝不会错链。
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index 3d25f13e1a..7c2cb356ec 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/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/client/ui-deliverables/README.md
-README.md: d6695f155907e7d92b35556588687b3f95e55b88
-README.zh.md: be360a5a1fbe8d904cedf104b28f64f1b0567d6b
+README.md: 189dedd88fed6914012204118ccdf9bdd0cd3bb2
+README.zh.md: bfcec3c54602533028942ed167b9526eaf3ca959
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index d6695f1559..189dedd88f 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -8,7 +8,7 @@ Produced-files feature owner: registers the deliverables row a finished turn end
 
 `ProducedFiles` renders the row between the closing message's body and its IconActions footer: a quiet label, up to six chips (basename text, full path as the `title`), and an explicit remainder count past the cap. Each chip opens through the owner-supplied `openFile` — the same Host opener the tool rows use, with the chat view resolving relative paths against the session cwd. Design rationale: the [workspace file links Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md).
 
-The closing prose carries the same vocabulary. This plugin provides the `chatFileMentions` service the chat view consults per closing message: `producedFileMentions` resolves an inline-code token by exact path, or by being exactly the basename of exactly one produced path — a basename two paths share stays inert rather than guessing, so a mention link can never open the wrong file or 404. A resolved mention renders as the same underlined opener the row's chips are, with the full path as its `title`, and mentions never render inside anchors or streaming text. Decision record: the [inline file mentions Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md).
+The closing prose carries the same vocabulary. This plugin provides the `chatFileMentions` service the chat view consults per closing message: `producedFileMentions` resolves an inline-code token by exact path, or by being exactly the basename of exactly one produced path — a basename two paths share stays inert rather than guessing, so a mention link can never open the wrong file or 404. A resolved mention keeps its code chip and takes the markdown sheet's link language — link-blue at rest, underlined on hover, exactly like URL-promoted inline code — with the full path as its `title`; mentions never render inside anchors or streaming text. Decision record: the [inline file mentions Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md).
 
 ## Model Experience
 
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index be360a5a1f..bfcec3c546 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -8,7 +8,7 @@
 
 `ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个安静的标签、至多六枚 chip（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每枚 chip 经由 owner 提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
 
-收尾正文承载同一份词表。本插件提供 chat 视图按收尾消息查询的 `chatFileMentions` service：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析——两条路径共享的 basename 保持死文本而不猜测，因此提及链接永远不会打开错误的文件或 404。解析成功的提及渲染为与产物行 chip 相同的下划线 opener，完整路径作为其 `title`；提及绝不会渲染在锚点内部或流式文本里。决策记录：[行内文件提及 Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md)。
+收尾正文承载同一份词表。本插件提供 chat 视图按收尾消息查询的 `chatFileMentions` service：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析——两条路径共享的 basename 保持死文本而不猜测，因此提及链接永远不会打开错误的文件或 404。解析成功的提及保留 code 胶囊并采用 markdown 样式表的链接语言——静止为链接蓝、悬停出下划线，与 URL 提升的行内代码完全一致——完整路径作为其 `title`；提及绝不会渲染在锚点内部或流式文本里。决策记录：[行内文件提及 Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md)。
 
 ## 模型体验
 
diff --git a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
index 19375be18e..b62e66e86e 100644
--- a/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
+++ b/packages/client/ui-primitives/src/markdown/MarkdownText.module.css
@@ -242,22 +242,24 @@
   object-fit: contain;
 }
 
-/* Inline file mention: a real file named in prose is the same affordance as a
-   tool row's path link, so it reads the same — underlined at rest. */
+/* Inline file mention: the same link language this sheet gives anchors (and
+   thereby URL-promoted inline code) — link-blue at rest, underline only on
+   hover/focus. An underline at rest reads badly inside the code chip, where
+   it collides with monospace descenders and the pill background. */
 .fileMention {
   margin: 0;
   padding: 0;
   border: none;
   background: none;
   font: inherit;
-  color: var(--dsw-alias-label-secondary);
-  text-decoration: underline;
-  text-decoration-color: var(--dsw-alias-label-quaternary);
-  text-underline-offset: 3px;
+  color: var(--dsw-alias-state-business-primary);
+  text-decoration: none;
   cursor: pointer;
 }
 
-.fileMention:hover {
-  color: var(--dsw-alias-label-primary);
-  text-decoration-color: currentColor;
+.fileMention:hover,
+.fileMention:focus {
+  outline: none;
+  text-decoration: underline var(--dsw-alias-state-business-primary);
+  text-underline-offset: 3px;
 }

From 55fca161e62ffd7374a823f84cc9b3483e42c31f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:05:04 +0800
Subject: [PATCH 114/516] cleanup(config): remove textual process env audit

The gate treated a literal process.env substring search as repository-wide source-ownership enforcement. It missed equivalent syntax while matching comments and strings, so the allowlist projected a security guarantee the implementation could not provide.

Remove the scanner and its allowlist. Keep the independently useful shipped-config inline tripwire, and narrow both the module contract and bilingual Agent Note to its actual source-shape claim.
---
 ...4-configuration-source-ownership.i18n.yaml |  4 +-
 ...26-08-04-configuration-source-ownership.md |  2 +-
 ...08-04-configuration-source-ownership.zh.md |  2 +-
 scripts/verify-config-source-ownership.ts     | 88 ++-----------------
 4 files changed, 10 insertions(+), 86 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 4288bcae58..38d2409b9d 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: 45ac032db0b60e0c8ce5a8c96ad2cf9cd847e14a
-2026-08-04-configuration-source-ownership.zh.md: e835325b0d87410e6513f08cf0777a1713deb8cd
+2026-08-04-configuration-source-ownership.md: e06dbc85f2307fa8a50fba13000f42306d69d9bf
+2026-08-04-configuration-source-ownership.zh.md: 6c6a128f1279a271f583e0bf4bcd27d0e5b81162
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index 45ac032db0..e06dbc85f2 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -48,7 +48,7 @@ The line is that these take effect with no user action, before any turn, outside
 
 **`packages/util/environment` owns the snapshot**, deliberately as a utility rather than a three-package capability seam. The snapshot is frozen before Cordis starts and injected once by the launcher, so there is no runtime implementation to swap; consumers need types and pure functions, which a `util/` package gives them without depending on a UI package. `environmentOf(ctx)` returns the launcher's snapshot, or the inherited environment as the only layer — an SDK host or bare `cordis.yml` discovered no files, so its single layer really is what it was launched with, and the same trusted lookups keep working there unchanged.
 
-**`verify-config-source-ownership`** keeps both rules: no unregistered `process.env` read under `packages/*/*/src` (26 allowlisted, each with the reason it is a process fact), and no `apiKey`/`baseURL`/`headers` inlined from the environment in shipped Cordis configuration. Removing those inlines is what makes the deployment tier meaningful — with the shipped tree silent on `baseURL`, a present value means a human or deployment set it.
+**`verify-config-source-ownership`** is a narrow tripwire for the ordinary single-line form of an `apiKey`/`baseURL`/`headers` environment inline in shipped Cordis configuration. Removing those inlines is what makes the deployment tier meaningful — with the shipped tree silent on `baseURL`, a present value means a human or deployment set it. Adapters own actual resolution; the gate makes no repository-wide claim about `process.env` access.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index e835325b0d..6c6a128f12 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -50,7 +50,7 @@ inherited process environment      (read-only, wins)
 
 **`packages/util/environment` 拥有该快照**，刻意做成 utility 而不是三包能力 seam。快照在 Cordis 启动前就冻结，并由启动器一次性注入，因此不存在需要切换的运行时实现；消费方需要的只是类型和纯函数，而 `util/` 包能提供这些且不必依赖 UI 包。`environmentOf(ctx)` 返回启动器的快照，或者返回只含继承环境的那一层——SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，它那唯一一层确实就是它被启动时的环境，因此同样的受信查询在那里原样继续工作。
 
-**`verify-config-source-ownership`** 守住这两条规则：`packages/*/*/src` 下没有未登记的 `process.env` 读取（26 处在 allowlist 中，各自写明它为何是进程事实），以及已交付 Cordis 配置中不得从环境内联 `apiKey`/`baseURL`/`headers`。删除这些内联正是「部署层」得以成立的原因——已交付配置树对 `baseURL` 保持沉默之后，「有值」就意味着「人或部署设过它」。
+**`verify-config-source-ownership`** 仅作为一道窄门禁，检查已交付 Cordis 配置中从环境内联 `apiKey`/`baseURL`/`headers` 的普通单行写法。删除这些内联正是「部署层」得以成立的原因——已交付配置树对 `baseURL` 保持沉默之后，「有值」就意味着「人或部署设过它」。实际解析由适配器负责；该门禁不声称覆盖仓库范围内的 `process.env` 访问。
 
 ## Consequences
 
diff --git a/scripts/verify-config-source-ownership.ts b/scripts/verify-config-source-ownership.ts
index 1abf269b83..ffc849bba3 100644
--- a/scripts/verify-config-source-ownership.ts
+++ b/scripts/verify-config-source-ownership.ts
@@ -1,20 +1,8 @@
 /**
- * Gate: every user-facing value has one owner, and no shipped file smuggles a
- * second one in.
- *
- * Two rules, both about the same failure — a value reaching the harness
- * through a path nobody ranked:
- *
- * 1. Production package source does not read `process.env` directly. A
- *    credential belongs to `ctx.credentials`, a user-configurable value to the
- *    environment snapshot plus its owner's resolve step, and a real
- *    process-launch fact to the app bootstrap. Each remaining read is listed
- *    below with the reason it is one of those.
- * 2. Shipped Cordis configuration does not inline a credential or an endpoint
- *    from the environment. Doing so re-creates the layer the snapshot exists
- *    to rank: `apiKey: !!js process.env.X` and `baseURL: !!js process.env.X`
- *    bypass both the credential seam and the endpoint ladder, and a project
- *    file could then decide where a key is sent.
+ * Gate: shipped Cordis configuration does not use the ordinary inline form
+ * for a credential or endpoint from the environment. This narrow source-shape
+ * lint prevents checked-in composition from bypassing the credential seam and
+ * endpoint ladder; adapters remain responsible for actual value resolution.
  * @module scripts/verify-config-source-ownership
  */
 
@@ -23,58 +11,6 @@ import { resolve, sep } from 'node:path'
 
 const ROOT = resolve(import.meta.dirname, '..')
 
-/**
- * Production package sources allowed to read `process.env`, each with the
- * reason it is a process fact rather than a user-configurable value. Adding a
- * row is a deliberate act: state which of the three owners it belongs to and
- * why it cannot go there.
- */
-const ENV_READ_ALLOWLIST: Readonly<Record<string, string>> = {
-  // The environment plane itself.
-  'packages/util/environment/src/index.ts': 'defines the snapshot; the inherited environment is its input',
-  'packages/ui/app-boot/src/index.ts': 'the app bootstrap that builds the snapshot and reads $DSH_SNAPSHOT',
-  'packages/util/paths/src/index.ts': 'resolves $DSH_HOME before any snapshot exists',
-
-  // Process-launch facts owned by the boundary that spawns or is spawned.
-  'packages/subprocess/subprocess/src/index.ts': 'scrubs the parent environment for children',
-  'packages/workflow/workflow-workerthread/src/host.ts': 'passes the parent environment to a worker thread',
-  'packages/ui/tui/src/index.ts': 'reads $COLORTERM, a terminal capability of this process',
-  'packages/lsp/lsp-local/src/index.ts': 'passes the parent environment to a language server it spawns',
-  'packages/cordis/repository-plugin/src/index.ts': 'resolves an MCP manifest against the spawning environment',
-  'packages/host/directory-picker-native/src/win32-dialog-host.ts': 'builds the child environment for the dialog worker it spawns',
-  'packages/host/directory-picker-native/src/win32-dialog-worker.ts': 'the spawned worker reads the title its parent passed on the env channel',
-  'packages/bash/pwsh-local/src/resolve.ts': 'locates pwsh through $ProgramFiles and $SystemRoot, Windows install layout rather than user configuration',
-
-  // Bootstrap-only DSH_* switches, which no discovered file may set.
-  'packages/skill/skill-local/src/index.ts': 'reads $DSH_AGENTS_HOME and $DSH_BUNDLED_SKILL_DIR, both bootstrap-only',
-  'packages/web/web/src/index.ts': 'reads $DSH_WEB_SEARCH_PROVIDER and $DSH_WEB_FETCH_PROVIDER, both bootstrap-only',
-  'packages/host/apiproxy/src/native-path-opener.ts': 'reads the WSL interop markers of this process to pick an opener',
-  'packages/host/directory-picker-auto/src/index.ts': 'reads launch facts (display, SSH) of this process',
-  'packages/host/directory-picker-auto/src/resolve.ts': 'reads launch facts (display, SSH) of this process',
-
-  // Telemetry identity and consent, resolved once per process at bootstrap.
-  'packages/telemetry/session-telemetry-otel/src/user-id.ts': 'derives a machine identity from process facts',
-  'packages/sdk/telemetry/src/consent-resolver.ts': 'reads the SDK bootstrap consent switch',
-  'packages/sdk/telemetry/src/anonymous-id.ts': 'derives a machine identity from process facts',
-
-  // SDK and example bins: their own app bootstrap, outside the product CLI.
-  'packages/sdk/sdk-client/src/client.ts': 'SDK host bootstrap',
-  'packages/sdk/helper/src/features/builtin/provider.ts': 'SDK scaffolding reads the developer environment',
-  'packages/sdk/helper/src/features/builtin/app.ts': 'SDK scaffolding reads the developer environment',
-  'packages/sdk/helper/src/package-managers/package-manager.ts': 'detects the invoking package manager',
-  'packages/sdk/create-sdk/src/create-wizard.ts': 'SDK scaffolding reads the developer environment',
-  'packages/examples/jsonrpc-demo/src/bin.ts': 'demo bin bootstrap',
-  'packages/examples/acp-demo/src/bin.ts': 'demo bin bootstrap',
-
-  // Test and replay infrastructure.
-  'packages/support/loader-smoke/src/index.ts': 'test launcher composing a child environment',
-  'packages/support/llm-replay/src/index.ts': 'replay fixture switch',
-  'packages/support/acp-snapshot/src/launcher.ts': 'snapshot launcher composing a child environment',
-
-  // Browser bundle: `process.env` is replaced at build time, never read at runtime.
-  'packages/client/runtime/src/client/contract/store.ts': 'build-time constant folded by the bundler',
-}
-
 /** Shipped Cordis configuration these rules apply to. */
 const SHIPPED_CONFIG_GLOBS = [
   'apps/*/config/*.yml',
@@ -95,17 +31,6 @@ const INLINE_DENY = /^\s*(apiKey|baseURL|apiKeyEnv|authToken|headers)\s*:\s*!!js
 
 const failures: string[] = []
 
-for (const file of globSync('packages/*/*/src/**/*.ts', { cwd: ROOT })) {
-  const rel = file.split(sep).join('/')
-  if (!readFileSync(resolve(ROOT, rel), 'utf8').includes('process.env')) continue
-  if (rel in ENV_READ_ALLOWLIST) continue
-  failures.push(
-    `${rel}: reads process.env directly. A credential belongs to ctx.credentials, a user-configurable`
-    + ' value to environmentOf(ctx) plus its owner\'s resolve step, and a process-launch fact to the app'
-    + ' bootstrap. If it is genuinely one of those, add it to ENV_READ_ALLOWLIST with the reason.',
-  )
-}
-
 for (const glob of SHIPPED_CONFIG_GLOBS) {
   for (const file of globSync(glob, { cwd: ROOT })) {
     const rel = file.split(sep).join('/')
@@ -126,8 +51,7 @@ if (failures.length > 0) {
   process.exit(1)
 }
 
-const allowed = Object.keys(ENV_READ_ALLOWLIST).length
 process.stdout.write(
-  `verify-config-source-ownership: no unregistered process.env reads (${String(allowed)} allowlisted)`
-  + ' and no credential or endpoint inlined in shipped configuration.\n',
+  'verify-config-source-ownership: no credential or endpoint uses the ordinary inline environment form'
+  + ' in shipped configuration.\n',
 )

From effd8e1ebd5b2146759d80c81bfa8f27b1cfcb3a Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 5 Aug 2026 11:13:52 +0800
Subject: [PATCH 115/516] docs: add TypeRT remote gateway RFC

---
 ...08-02-typert-remote-method-calls.i18n.yaml |   6 +
 .../2026-08-02-typert-remote-method-calls.md  | 489 ++++++++++++++++++
 ...026-08-02-typert-remote-method-calls.zh.md | 489 ++++++++++++++++++
 3 files changed, 984 insertions(+)
 create mode 100644 .agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
 create mode 100644 .agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md
 create mode 100644 .agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md

diff --git a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
new file mode 100644
index 0000000000..cc2f0736d4
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.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/proposed/architecture/2026-08-02-typert-remote-method-calls.md
+2026-08-02-typert-remote-method-calls.md: c3a7a77c583720c3f967de185a089d374f017d81
+2026-08-02-typert-remote-method-calls.zh.md: 9b2fbbd69f1c054cbf6c86f177b743c583be3e8a
diff --git a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md
new file mode 100644
index 0000000000..c3a7a77c58
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md
@@ -0,0 +1,489 @@
+# Agent Note: TypeRT Gateway Targeted Method Calls
+
+Status: proposed
+
+English | [中文](2026-08-02-typert-remote-method-calls.zh.md)
+
+## Problem
+
+The Host API Proxy handles direct method calls, stateful interactions, and Session event streams. These concerns have different lifecycles, routing semantics, and client programming interfaces. Continuing to export all business operations through one package would couple business Services, transport protocols, state machines, and client types.
+
+This proposal addresses only targeted method calls in which one request produces one result. Stateful interactions such as Permission and Approval, as well as Session event streams, do not use this design and will be designed separately.
+
+The contract for a direct method call belongs to the business Service that implements it. Business developers should declare only which methods are remotely callable, without also maintaining a central API interface, routing table, parameter conversion table, client stub, and Zod schema.
+
+The Host and Browser Client use separate TypeScript Programs because each side augments the Cordis `Context` type differently. A Remote projection must not import the complete Host declarations into a consumer or depend on Browser-specific types. If the TUI later reuses this programming interface, it must likewise see only methods marked Remote. TUI integration is outside the current scope, but the implementation boundary must preserve this isomorphic reuse.
+
+## Proposal
+
+A business Service declares callable methods with `@Remote` or `@RemoteContext()` and explicitly joins the Gateway through `bindTypeRTGateway()`. TypeRT generates the Host-local reflection artifact and a platform-independent Remote consumer projection from the Host Program. The Client Program continues to generate its own local reflection artifact independently.
+
+The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. The `.d.ts` exposes only methods marked with a Remote decorator and refers to the business package's single public type symbols. The `.d.ts.map` navigates consumer API methods back to their Host business method implementations. The `.js` carries endpoint, parameter, Context, and Zod information for the same contract. At the assembly layer, the Browser Client mounts the required Remote JS contributions onto the Client API Service. The projection and API abstraction remain platform-independent so that a future TUI can reuse them.
+
+`@deepseek-ai/dsh-host-api-gateway`, located at `packages/host/api-gateway`, provides two symmetric faces: its default entry provides Host `ctx.typertGateway`, while its `/client` entry provides consumer-side `ctx.api`. Each side consumes a locally generated `InvocationDescriptor` from the same model; descriptors are not sent over the wire. The Remote data protocol runs over the single Connection/RPC mechanism through an isolated `/api2` channel. The business calling interface does not change when Connection migrates from HTTP to WebSocket.
+
+## Components and Cordis services
+
+| Component | Cordis service | Responsibility in this proposal |
+|---|---|---|
+| `@deepseek-ai/dsh-type-meta` | Declares only the minimal `ctx.typert` protocol | Decorators, bindings, descriptors, lookup/Context, and the Remote map; no dependency on the compiler, Zod, Connection, or Browser |
+| TypeRT registry | `ctx.typert` | Separately stores reflection for the current environment, imported Remote contributions, lookup providers, and Context providers |
+| TypeRT generator/loader | No new business service | Generates three kinds of `lib` artifacts from the Host/Client Programs and registers the current environment's artifacts with `ctx.typert` |
+| Host API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, invokes methods, and encodes results |
+| Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, RPC envelope, rpcId, serialization, trust, and error transport, while carrying the isolated `/api` and `/api2` channels |
+| Host API Gateway's Client face | `ctx.api` | Mounts Remote contributions, materializes root and scoped APIs, and delegates canonical calls to `ctx.connection.rpc` |
+| Client Remotes | No new service | Serves as the only Remote facade for Client business code, selecting and mounting `/remote` contributions while exposing the Gateway Client face and the selected API declarations |
+| Agent/Session owning packages | Existing domain services | Provide both static interface merges and runtime lookup/Context providers |
+| Business packages such as Goal | Existing business Services | Declare only bindings, Remote methods, and canonical DTOs, and export the generated `/remote` subpath |
+
+The Host Gateway does not depend on concrete implementations of `ctx.agents`, `ctx.sessions`, `ctx.goals`, or `ctx.httpServer`. The Client API does not understand the physical carrier, and Connection does not understand Goal, Agent, lookup, `InvocationDescriptor`, or Client API namespaces.
+
+## Business declarations
+
+Ordinary direct calls use `@Remote`. When migrating to an existing Service or Registry, do not rename or alter existing methods. Add `remoteExport*` entry points at the end of the class and use decorator arguments to declare their short API names. A method explicitly declares every required business object in a top-level parameter position:
+
+```text
+export class GoalService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+
+  create(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
+    // Existing business method remains unchanged.
+  }
+
+  @Remote('create')
+  remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
+    return this.create(agent, request)
+  }
+}
+```
+
+`goals` is an explicit Cordis service key and is the default wire namespace. Override it through an option to `bindTypeRTGateway()` only when the protocol namespace genuinely needs to differ from the service key.
+
+Use `@RemoteContext()` when the Service receiver must be resolved within an isolated kind of Context. Context identity does not enter the business method's parameters:
+
+```text
+export class ScopedGoalService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+
+  @RemoteContext('agent', 'create')
+  remoteExportCreate(request: CreateGoalRequest): Promise<CreateGoalResult> {
+    // Runs against the goals service resolved from the Agent Context.
+  }
+}
+```
+
+An endpoint selects exactly one invocation mode. A flow that needs an explicit `Agent` parameter uses `@Remote`. A flow that first switches to an Agent Context and then resolves a scoped receiver uses `@RemoteContext('agent')`. TypeRT does not infer either mode from the method body or from a missing parameter.
+
+Business packages depend only on the lightweight `@deepseek-ai/dsh-type-meta`. It provides declaration protocols for decorators, `bindTypeRTGateway()`, lookup, Remote Context, and descriptors, without depending on the TypeScript compiler, Zod, HTTP, or the Client runtime.
+
+## Decorators and the explicit Gateway facet
+
+A decorator only states that a method participates in the Remote contract. It performs no runtime type reflection and injects no hidden symbol into a Service constructor. The arguments to `@Remote('create')` and `@RemoteContext('agent', 'create')` are external method names, while the actual member remains named `remoteExportCreate`. The member name becomes the external method name only when no alias is provided. `typertGateway` is the sole explicit marker that a Service has joined the Gateway, making this capability visible on both the business class and its runtime instance.
+
+In SRC mode, the decorator may record the prototype, method name, and invocation mode in a `WeakMap` internal to `dsh-type-meta`. It writes no custom properties to a Service instance, prototype, constructor, or method function.
+
+In LIB mode, the TypeRT compiler performs strict method discovery, type resolution, and descriptor generation. Generation neither rewrites business source nor secretly supplies generated arguments to `bindTypeRTGateway()`.
+
+## Lookup and Remote Context registration
+
+The Gateway has no built-in branches for Agent, Session, or other business objects. Each object-owning package provides both a static declaration and a runtime provider:
+
+```text
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTLookupMap {
+    agent: TypeRTLookup<Agent, SessionId>
+  }
+}
+
+ctx.typert.lookups.register('agent', {
+  parameter: 'agent',
+  wire: 'agentId',
+  resolve: sessionId => resolveAgent(sessionId),
+})
+```
+
+The static declaration tells TypeRT that `Agent` corresponds to `SessionId` on the wire. The runtime provider resolves an `agentId` in a request to the currently live `Agent` object. If either side is missing, the LIB build or the earliest resolvable runtime registration fails immediately.
+
+Lookup objects such as Agent and Session may each occupy only one top-level parameter position. An ordinary JSON request may be passed as another complete parameter, but this proposal does not support `request.agent`, object destructuring, arrays of objects, nested lookups, or searching arbitrary complex structures for IDs.
+
+Remote Context uses a separate merge-extensible map and provider. The Agent package registers an `agent` Context provider that locates the Agent Context from its wire identity and resolves the Service key named by the descriptor from that Context. The Gateway does not know the internal structure of an Agent Context.
+
+The Client also registers an `agent` Context binder. The binder only retrieves a `SessionId` from the Context in which a call occurs; it neither enumerates Scopes nor copies methods into each one. A Cordis Service tracker automatically rebinds a scoped namespace to the current Agent Context.
+
+## InvocationDescriptor
+
+TypeRT, the permissive SRC parser, Host Gateway, and Client API exchange one canonical description:
+
+```text
+InvocationDescriptor {
+  id: '@deepseek-ai/dsh-goal#goals/create'
+  service: 'goals'
+  namespace: 'goals'
+  method: 'create'
+  implementation: 'remoteExportCreate'
+  invocation: direct | { context: 'agent', wire: 'agentId' }
+  scope?: { context: 'agent', wire: 'agentId' }
+  parameters: [
+    { name, wire, source: json | lookup, lookup?, codec }
+  ]
+  result: codec
+  sourceLocation
+}
+```
+
+`method` is the external short name used by the endpoint and Client API; `implementation` is the actual member name on the Host receiver. `implementation` may be omitted when the two names match. A `direct` descriptor retains the original Service instance as the receiver. A Context descriptor first uses the corresponding Context provider to find the scoped Context, then resolves the receiver by the descriptor's service key.
+
+The strict generator writes `scope` only when a direct method has exactly one lookup parameter, a `TypeRTContextMap` declaration with the same name exists, and both use the same wire type symbol. `scope.wire` must identify that lookup parameter. It declares that a consumer may fill this parameter from the Context in which the call occurs, without changing the Host receiver or endpoint. No scoped projection is generated when there are multiple lookups, no Context declaration, or mismatched wire types; a type mismatch is a build error.
+
+Parameter order comes from the method signature. HTTP fields come from parameter names or lookup declarations. The Gateway does not infer optional fields, Context types, lookup types, or missing arguments from request contents, and it does not synthesize business defaults.
+
+A LIB codec contains a Zod schema and a canonical `typeSymbol` consisting of "package + public subpath + export name." An SRC codec is marked only as `src-json`. When the Host and consumer run in different JavaScript realms, each holds its own Zod instances, but both sets are generated from the same TypeRT model and symbol keys.
+
+Descriptors exist only in the local registry on each side. The wire carries only the `/api2` channel, endpoint, and `{ args }` payload. The Host uses its descriptor to decode and invoke the method, while the Client uses its corresponding descriptor to encode arguments and validate the result.
+
+## TypeRT runtime registry
+
+```text
+ctx.typert.local     当前进程自己的 Host 或 Client reflection
+ctx.typert.remotes   消费端显式 mount 的对端 Remote contribution
+ctx.typert.lookups   wire ID 到 Host 活对象的 provider
+ctx.typert.contexts  Host Context resolver 与 Client Context binder
+```
+
+Every registration returns a disposer owned by the caller's Cordis fiber. The Gateway and API Service read the current snapshot before subscribing to changes, so business Services, generated contributions, providers, and consumers can load in any order. When any dependency is disposed, its related endpoints or methods become unavailable immediately.
+
+The registry's Host root entry has the complete `TypeRTService` interface merge. The registry implementation shared by Host and Client lives in a separate module without environment declarations. The registry's `/client` entry imports only that shared implementation and does not pass through the Host root entry, so it cannot bring Host Cordis declarations into the Client Program.
+
+## Canonical types, symbols, and Zod
+
+Remote Client DTS does not copy business DTOs or redeclare structurally identical shadow types. It imports original symbols only from public, type-only subpaths that do not carry Host Cordis merges:
+
+```text
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { CreateGoalRequest, CreateGoalResult } from '@deepseek-ai/dsh-goal/types'
+```
+
+Consequently, `SessionId`, the Agent wire ID, the request, and the result all refer to the same TypeScript declaration in the Host and Browser Client. A future TUI can reuse them without a second set of types. Go to Definition, renames, and Find References for a DTO return to the one source location for the business type instead of stopping at a copy in a generated file.
+
+Remote API methods themselves use declaration-map navigation. TypeRT anchors `InvocationModel.location` to the method-name token of the Host `remoteExport*` method and emits a source-map segment on the corresponding property of the namespace interface. After the TypeScript editor resolves `ctx.api.models.list` to its generated declaration, `typert.remote-client.d.ts.map` takes it to the Host Service's `remoteExportList` entry point. That entry point explicitly calls the existing, unrenamed `list()` method; the map does not misidentify the decorator, class, or full signature as the method definition.
+
+TypeRT generates a wire Zod codec for the same symbol key. The Host Gateway uses it to validate input and encode results, while the Client API may use it to encode arguments and validate responses. If a complex type cannot produce a strict codec, the LIB build fails instead of degrading to `unknown` or unchecked JSON.
+
+Named business types referenced by Remote methods must be exported from public, type-only subpaths. If the only reachable entry also imports Host Services, Cordis `Context` merges, or Host-only implementations, the build fails and requires the business package to provide a safe type entry. Primitives, literals, and simple compositions explicitly supported by TypeRT need no additional names.
+
+A lookup parameter does not expose the `Agent` class to consumers. The Remote projection refers to the canonical ID type in the lookup declaration, such as `SessionId`, while the Host continues to resolve objects through the canonical `Agent` class symbol.
+
+## Three artifact kinds and two TypeScript Programs
+
+The Host and Client still use only two independent TypeScript Programs, but TypeRT generates three semantically distinct kinds of artifacts:
+
+```text
+Host Program
+├─ typert.host.js / typert.host.d.ts
+│  Host 自身的 Service、Event、Object、schema 和 inbound Gateway 信息
+└─ typert.remote-client.js / typert.remote-client.d.ts / typert.remote-client.d.ts.map
+   Host Remote 对任意消费环境的 wire 投影
+
+Client Program
+└─ typert.client.js / typert.client.d.ts
+   Client 自身的 Service、Event、Object 和 schema 信息
+```
+
+`remote-client` is the Host Program's second emitter, not a third Program or the Client's local face. It contains no Host Cordis merge, Service class, Context class, or implementation code, and it does not enter the Host-local reflection registry.
+
+The Host lib build performs strict Host analysis and emits both the Host-local and Remote consumer artifacts. The Client lib then consumes the Remote DTS. The complete order is:
+
+```text
+Host lib build
+→ 生成 typert.host.{js,d.ts}
+→ 生成各业务包 lib/typert.remote-client.{js,d.ts,d.ts.map}
+→ 完成 Client lib 和 typert.client 产物
+→ Vite 构建 Web
+```
+
+The existing top-level `build` still runs `build:lib` before `build:web`, but `build:lib` must complete the Host and Remote artifacts before starting Client TypeScript compilation. A clean build must not depend on stale `.d.ts` files from an earlier build.
+
+## The `/remote` package entry
+
+Every business package that provides Remote methods exports a generated `/remote` subpath:
+
+```text
+"./remote": {
+  "types": "./lib/typert.remote-client.d.ts",
+  "default": "./lib/typert.remote-client.js"
+}
+```
+
+Consumer code selects a capability through the business package itself:
+
+```text
+import goalsRemote from '@deepseek-ai/dsh-goal/remote'
+```
+
+This import brings the `.d.ts` map augmentation into the current TypeScript project while supplying the JS descriptor for the same contract as a value to the runtime. A business package that is not imported does not extend the current project's Remote API types.
+
+The business package's published files must include both `lib/typert.remote-client.d.ts.map` and the `src` file referenced by that map. The generated DTS refers to its adjacent map with `//# sourceMappingURL=typert.remote-client.d.ts.map`; the map source points from `lib` to the business source by a relative path such as `../src/index.ts`. The `/remote` export does not list the map separately; the package `files` field publishes it together with the source.
+
+Code that needs only static types may use `import type {} from '@deepseek-ai/dsh-goal/remote'`. This import is erased at runtime, loads no JS, and cannot trigger runtime registration. An environment that makes real calls must pass the contribution from a normal value import to the API Service.
+
+Workspace resolution for `/remote` must explicitly target generated `lib` artifacts and must not let a general package-to-`src` paths rule redirect it to Host source. Ordinary business imports may continue resolving to SRC or LIB according to each environment's existing rules.
+
+## Strict consumer API types
+
+Remote DTS extends the flat endpoint map, direct namespace interface, namespace map, and scoped map without augmenting the global Cordis `Context`:
+
+```text
+interface TypeRTRemoteNamespace$676f616c73 {
+  create: (
+    agentId: SessionId,
+    request: CreateGoalRequest,
+  ) => Promise<CreateGoalResult>
+}
+
+interface TypeRTRemoteMap {
+  'goals/create': (
+    agentId: SessionId,
+    request: CreateGoalRequest,
+  ) => Promise<CreateGoalResult>
+}
+
+interface TypeRTRemoteNamespaceMap {
+  goals: TypeRTRemoteNamespace$676f616c73
+}
+
+interface TypeRTRemoteContextMap {
+  'agent:goals/create': (
+    request: CreateGoalRequest,
+  ) => Promise<CreateGoalResult>
+}
+```
+
+`TypeRTRemoteMap` preserves canonical endpoint signatures for protocol typing and reflection. The root API type reads `TypeRTRemoteNamespaceMap` directly instead of deriving methods indirectly through a key-remapped mapped type; the TypeScript Language Service cannot reliably navigate such indirect properties through a declaration map. A namespace interface name encodes the namespace's UTF-8 bytes as hexadecimal, so `goals` deterministically becomes `TypeRTRemoteNamespace$676f616c73`. Different packages generate the same interface name for the same namespace and use module augmentation to merge their methods, while `TypeRTRemoteNamespaceMap.goals` always refers to that one type.
+
+TypeRT projects `TypeRTRemoteContextMap` onto a dedicated Scope type according to its Context key. The final programming interface remains:
+
+```text
+api.goals.create(agentId, request)
+agent.goals.create(request)
+```
+
+The Agent Scope supplies its own `SessionId` automatically. A `@Remote` method with an `agent` lookup can therefore generate both root and scoped consumer signatures. A `@RemoteContext('agent')` method also omits a separate Context identity, but generates only the scoped signature. In this phase, only the Client Agent Context gains `goals`; the Root Context does not. A future TUI must preserve the same Scope restriction.
+
+`RemoteApi` remains platform-independent, and the Browser Client uses it as its `ClientApi`. If a future TUI reuses this type, it must likewise access it through a dedicated API object and Agent Scope rather than treating the Host `Context` as a broader Service collection. Public Service methods without Remote markers do not enter the Remote maps.
+
+## Client TypeRT and the API Gateway Client face
+
+TypeRT in a consumer environment maintains both local information and Remote information imported from other environments, but stores them in separate registries:
+
+```text
+TypeRT.local    当前环境自己的反射模型
+TypeRT.remotes  已导入的 Remote contribution
+```
+
+`@deepseek-ai/dsh-client-remotes/client` centrally loads the required Remote contributions:
+
+```text
+import goalsRemote from '@deepseek-ai/dsh-goal/remote'
+import sessionsRemote from '@deepseek-ai/dsh-session/remote'
+
+ctx.api.mount(goalsRemote)
+ctx.api.mount(sessionsRemote)
+```
+
+Client business packages depend only on `@deepseek-ai/dsh-client-remotes/client`, not directly on the Host API Gateway or the runtime entry of each business `/remote`. Client Remotes itself depends on the Gateway Client face and re-exports declarations so the selected Remote map reaches business compilation. Adding or removing a complete Client capability changes only this assembly point.
+
+`ctx.api.mount()` registers a contribution with `TypeRT.remotes`, and its disposer is owned by the Cordis fiber that called the method. Duplicate endpoints, conflicting invocation modes for the same namespace and method, or conflicts between a descriptor and an existing type identity fail immediately.
+
+The API Service materializes each `@Remote` descriptor as a real function on the root `api`. The function constructs named `args` in descriptor parameter order, applies the Client's strict codec, and then calls `ctx.connection.rpc.call('/api2', endpoint, { args })`.
+
+Neither a direct descriptor with `scope` nor a `@RemoteContext` descriptor copies functions into every Agent Scope. The API Service creates one root singleton Cordis Service for each scoped namespace and materializes methods on that Service. When `agent.goals.create()` is called, the Cordis tracker rebinds the Service's `this.ctx` to the current Agent Context. The method then asks the corresponding Context binder for identity from `this.ctx`. A direct scoped projection substitutes this identity at the lookup position named by `scope.wire`; a Context descriptor writes the identity into the receiver's separate wire field. Both issue the same kind of `/api2` call.
+
+```text
+root ctx.api.goals.create(agentId, request)
+  → direct descriptor
+  → ctx.connection.rpc.call('/api2', 'goals/create', { args })
+
+agent.goals.create(request)
+  → tracker 将 namespace Service rebind 到 agent Context
+  → agent binder 从 caller Context 取得 agentId
+  → 用 agentId 补入同一 direct descriptor 的 lookup 参数
+  → ctx.connection.rpc.call('/api2', 'goals/create', { args })
+```
+
+The Root `Context` does not merge the scoped `goals` type; only `AgentContext` gains that property through `RemoteContextApi<'agent'>`. If a caller bypasses the type system and dynamically calls a scoped method from Root, the binder reports an explicit error. If the Client already has a Cordis service with the same name, or two contributions claim the same namespace and method incompatibly, mounting fails instead of overwriting the existing service.
+
+Generated Remote JS contains only descriptors, symbol keys, and codecs; it does not bundle Host Service implementations. The API Service can create real functions from that data, so this proposal does not depend on a JavaScript Proxy. A Proxy remains an implementation option but is not a source of types or reflection.
+
+## Cross-environment isomorphism constraints
+
+Remote API is a consumer capability, not a synonym for Browser API. This phase implements only Browser Client contribution mounting, Connection RPC calls, and Agent Scope association.
+
+Remote DTS, Remote JS, `RemoteApi`, `InvocationDescriptor`, the Remote RPC data protocol, and Context binders must not depend on the DOM, Browser module loaders, or HTTP. Through Connection, the Browser Client encodes descriptor-materialized methods as `/api2` RPC calls.
+
+A future TUI can join the same call abstraction without changing business decorators, Remote maps, or the shape of API calls. The TUI-visible API must still be generated exclusively from `@Remote` and `@RemoteContext`; sharing a process with the Host must not allow it to bypass Remote restrictions and expose Service methods directly.
+
+TUI runtime mounting, carriers, Agent Scope association, and SRC startup wiring are outside this phase.
+
+The Web already depends on build artifacts such as `lib/client.js`, so it requires a complete `build:lib` before startup. After the Host Remote contract changes, developers must rebuild the lib and then start or restart the Web. The first phase does not implement incremental watching of the Remote contract.
+
+## SRC and LIB operating modes
+
+SRC supports local source startup. The `WeakMap` records created by `@Remote` and `@RemoteContext()` provide method names and invocation modes. At runtime, the system reads ordered parameter names from the JavaScript function signature and combines them with registered lookup/Context providers to produce a permissive descriptor.
+
+For example, `@Remote('create') remoteExportCreate(agent, request)` resolves to the external method `create`, implementation member `remoteExportCreate`, and two top-level parameters. Lookup registration rewrites `agent` to the wire field `agentId`, while `request` is passed as a same-named JSON parameter. SRC does not start a `ts.Program`, use a preload or loader hook, generate or rewrite source, or inspect the internal structure of an ordinary JSON object.
+
+A signature that SRC cannot resolve unambiguously fails when the Service mounts. It does not guess at object destructuring, ambiguity caused by default parameters, rest parameters, nested lookups, or complex types.
+
+LIB supports CI, releases, and the prerequisite Web build. TypeRT scans the complete Host project and checks Remote decorators, explicit bindings, service keys, endpoint conflicts, lookup/Context declarations, public-symbol reachability, JSON codecs, and result codecs, then generates strict descriptors.
+
+At runtime, LIB only loads definitions from `lib`; it does not start the TypeScript compiler. The subsequent association of Services, lookup, Context resolution, invocation, and response encoding in the Host Gateway does not depend on whether a descriptor came from permissive SRC parsing or strict LIB generation.
+
+CI and releases use LIB. Moving all repository coverage to LIB is separate follow-up work and does not block this direct-method-call implementation.
+
+## Host Gateway registration
+
+The Host Gateway observes both TypeRT Remote definitions and the Cordis Service lifecycle. When a Service carrying the `typertGateway` facet and a definition with the same service key are both available, the Gateway registers the definition's endpoints. Their arrival order does not matter.
+
+At startup, the Gateway reads the current snapshots of TypeRT definitions and the Cordis reflection store before subscribing to registry changes and `internal/service`. It reconciles definitions, live Services, and bindings by service key, and unregisters endpoints when a Service is replaced or disposed. If a definition, lookup provider, or Context provider is removed, dependent endpoints immediately become unavailable; the Gateway neither retains invalid objects nor degrades to invoking methods with raw IDs.
+
+An ordinary `@Remote` call retains the original Service instance as receiver. After lookups succeed, the Gateway calls the member identified by `implementation ?? method` with parameters in descriptor order.
+
+A `@RemoteContext('agent')` call first asks the Agent Context provider to resolve the wire identity, then reads the descriptor's service key from that Context and invokes the scoped receiver. The business method receives neither a hidden Context parameter nor an Agent ID.
+
+```text
+ctx.typertGateway.invoke({ namespace, method, args })
+→ 查找本地 InvocationDescriptor 与 live receiver
+→ 按参数 descriptor 读取具名 wire 字段
+→ codec 解码普通值或 lookup ID
+→ lookup provider 把 ID 解析为活对象
+→ direct 使用原 Service；context 先解析 scoped Context 和 Service
+→ Reflect.apply(receiver[implementation ?? method], receiver, orderedArgs)
+→ result codec 编码业务结果
+```
+
+`ctx.typertGateway.invoke()` is the carrier-independent Host entry point. It neither creates an rpcId, RPC envelope, nor HTTP response. It returns only the encoded result or raises a Gateway error that the Connection RPC adapter maps for transport.
+
+## The `/api2` call chain
+
+`/api2` is an isolated protocol channel on the single Connection/RPC mechanism, not a transport created by the Gateway. The Gateway registers one local handler with Connection. This phase adds the following general channel capability to the existing HTTP Connection:
+
+```text
+ctx.connection.rpc.handle('/api2', (endpoint, payload) => {
+  const { namespace, method } = parseEndpoint(endpoint)
+  const { args } = parsePayload(payload)
+  return ctx.typertGateway.invoke({ namespace, method, args })
+})
+```
+
+The Connection Host half obtains a handle from the single HTTP Server and reuses the same RPC bridge, request/response envelope, rpcId, serialization, trust, transport errors, and `RpcError`. Its current physical mapping is:
+
+```text
+POST /api2/<namespace>/<method>
+```
+
+The Remote payload is a named JSON object, not a positional array, and does not carry an `InvocationDescriptor`. A normal Goal call has this payload slot:
+
+```json
+{
+  "args": {
+    "agentId": "session-1",
+    "request": {
+      "objective": "finish the migration"
+    }
+  }
+}
+```
+
+The complete path is:
+
+```text
+ctx.api.goals.create(sessionId, request)
+→ Client InvocationDescriptor 编码 { args: { agentId, request } }
+→ ctx.connection.rpc.call('/api2', 'goals/create', { args })
+→ Connection 创建 rpcId 和既有 client-request envelope
+→ 当前 carrier 发送 POST /api2/goals/create
+→ Connection Host half 执行 trust、反序列化和 RPC 分发
+→ /api2 handler 调用 ctx.typertGateway.invoke(...)
+→ Host InvocationDescriptor 解码、lookup、receiver 解析和 Reflect.apply
+→ result codec 编码
+→ Connection 写入既有 RPC result 并回送相同 rpcId
+→ Client result codec 验证并返回 CreateGoalResult
+```
+
+Remote does not define a second-layer `{ ok, value/error }` response. Successful values and Gateway errors use the existing RPC response's `result` directly. The Gateway adapter maps endpoint, schema, lookup, Context, Service, and business-invocation failures to `RpcError`; Connection transports that error.
+
+The Gateway does not handle per-method permissions, caller identity, cancellation, idempotency, or long-lived connection state. This work only extends Connection with general channel registration and invocation capabilities. It does not change existing `/api`, trusted connection, trusted-host, or privileged-method semantics. Connection's WebSocket migration remains separate follow-up work.
+
+## Connection and protocol boundaries
+
+The API Service owns Remote contributions, method materialization, Scope binding, and the correspondence between positional parameters and descriptors. The Gateway owns Host descriptors, lookup, Context, and business invocation. Connection only sends `/api2`, the endpoint, and `{ args }` as one RPC call to the target and returns the existing RPC result; it does not understand Goal, Agent, lookup, descriptors, or Client API types.
+
+`/api` and `/api2` share one Connection, Server, RPC envelope, and connection lifecycle while remaining separate protocols. When Connection migrates from HTTP to WebSocket, `/api2` naturally changes from a physical path to a logical channel. The Remote payload, business decorators, generated DTS, Remote API types, and Agent Scope programming interface remain unchanged.
+
+## Package boundaries
+
+- `@deepseek-ai/dsh-type-meta`: lightweight protocols for decorators, bindings, lookup, Remote Context, and descriptors.
+- TypeRT generator: analyzes Host/Client Programs, generates local faces and Remote consumer projections, and emits canonical symbol/Zod information.
+- TypeRT runtime: separately stores the current environment's local reflection and imported Remote contributions.
+- `@deepseek-ai/dsh-host-api-gateway`: its default entry associates Host definitions with Services, performs lookup, resolves Context receivers, invokes methods, encodes results, and registers an `/api2` handler with Connection; its `/client` entry mounts Remote contributions, creates strict API methods, and delegates calls to `ctx.connection.rpc`. The entries share the Remote protocol but do not import each other's Cordis interface merges.
+- `@deepseek-ai/dsh-client-remotes`: the only Remote facade depended on by Client business code; directly depends on the Gateway Client face, selects `/remote` contributions, and exposes the merged API types to business packages.
+- Connection: owns the single HTTP Server/future WebSocket carrier, RPC envelope, rpcId, serialization, trust, and error transport while carrying the isolated `/api` and `/api2` channels.
+- Business-object packages such as Agent/Session: own lookup, Context providers, canonical ID types, and public type-only entries.
+- Business Service packages: declare bindings, Remote methods, and their request/result types, and export the generated `/remote` subpath.
+
+## Initial implementation scope
+
+The first vertical path implements `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api2 → Host Gateway → GoalService.remoteExportCreate()` and proves that the same direct descriptor with an Agent lookup supports both `ctx.api.goals.create(agentId, request)` and `agentCtx.goals.create(request)`. The scoped-receiver semantics of `@RemoteContext('agent')` remain a separate mode.
+
+This phase implements Connection's general second-channel API and its current HTTP carrier mapping, but not WebSocket migration, the TUI runtime, a TUI carrier, or TUI Agent Scope wiring. This RFC also does not design Permission/Approval state machines, Session event streams, call authorization, cancellation, retries, idempotency, or cross-version protocol compatibility.
+
+## Alternatives considered
+
+**Continue using the central API Proxy package.** This would require business methods, Host routes, and Client interfaces to be declared repeatedly in several locations. It would also keep direct calls, stateful interactions, and event streams tied to the same lifecycle, so this alternative is rejected.
+
+**Perform strict reflection through decorators at runtime.** JavaScript decorators cannot recover erased TypeScript types, public symbol identity, or complete Zod codecs. Injecting a compiler-private symbol into a constructor would also hide the business class's real dependencies, so TypeRT generates strict information at compile time.
+
+**Use a preload, loader hook, or complete `ts.Program` during SRC startup.** This could reuse LIB analysis but would add requirements to every source startup entry. SRC needs only a usable permissive descriptor, so it uses decorator markers, function parameter names, and explicit providers; strict checks remain in the LIB contract pass.
+
+**Hand-write the Client interface.** A hand-written interface cannot guarantee that it contains only Remote-marked methods and can drift from Host signatures, lookup IDs, and Zod schemas. Client types are therefore projected automatically from the Host Program.
+
+**Use a TypeScript language-service/compiler plugin to make the Client understand decorators directly.** This would require editors, Vite, tsc, tsx, and published consumers to install an additional plugin, making integration too invasive. The design instead generates ordinary `.d.ts` files and standard declaration maps.
+
+**Import complete Host DTS into the Client or TUI.** This would pull in Host Services and Cordis interface merges while exposing unmarked methods to consumers. Remote DTS refers only to public, type-only symbols and augments dedicated Remote maps.
+
+**Generate only Remote DTS, without JS.** Types would work, but the runtime could not enumerate endpoints, codecs, and Context modes without a Proxy or another hand-written registry. The same Host projection therefore emits a Remote JS contribution as well.
+
+**Let a top-level `/remote` import register global state implicitly.** The target Cordis Context may not exist when ESM evaluation occurs, and ownership becomes ambiguous across multiple Contexts, HMR, and disposal. A normal value import therefore returns only a contribution, which the environment assembly explicitly mounts through the API Service.
+
+**Create a separate transport, HTTP route, and response envelope for Remote.** This would duplicate the existing Connection's Server ownership, rpcId, serialization, trust, errors, and future WebSocket lifecycle, requiring two RPC stacks to migrate separately. `/api2` instead reuses the single Connection/RPC mechanism as an isolated protocol channel.
+
+## Acceptance criteria
+
+- Goal Service retains its existing business method and adds a remote entry point at the end of the class through an explicit `typertGateway` and `@Remote('create') remoteExportCreate(...)`, without maintaining a second route, codec, or Client method list.
+- One clean `build:lib` generates the Host Remote contract before compiling Host and Client consumers and produces JS, DTS, and a DTS map under the business package's `lib`, importable through `/remote`.
+- After importing `@deepseek-ai/dsh-goal/remote`, a consumer project gets a strict `api.goals.create(...)` type; without the import, that namespace does not enter its types. Go to Definition on `create` follows the declaration map to the Host Service's `remoteExportCreate` implementation.
+- After the Client assembly mounts the JS contribution obtained from the same import, TypeRT can reflect endpoint, parameter, result, lookup, Context, and Zod information, and the API Service creates the calling method without a hand-written stub.
+- Remote DTS, Remote JS, `RemoteApi`, and the descriptor protocol do not depend on Browser-specific capabilities, and the type model cannot expose unmarked Goal Service methods, preserving the boundary required for future isomorphic TUI integration.
+- `agent.goals.*` obtains its call Scope through the Cordis tracker and Context binder. The Root Context has no Agent-only type, and functions are not copied into each Scope.
+- `/api2/goals/create` resolves `agentId` to the canonical Agent object, invokes the original Goal Service receiver, and returns the result through the existing RPC result/error mechanism.
+- `/api2` and `/api` share the single Connection/RPC carrier while remaining protocol-isolated. Remote neither registers an HTTP Server handle directly nor defines a second response envelope.
+- Connection provides general channel registration and invocation capabilities and maps `/api2` to the current HTTP carrier. Existing `/api` behavior and trust semantics remain unchanged.
+- This implementation does not change existing `/api`, Connection/trusted connection, Permission/Approval, or Session event stream behavior.
+
+## Risks
+
+Remote API types depend on generated `lib` declarations. Build orchestration must finish the Host contract pass before compiling Host and Client consumers; an incorrect order makes a clean build depend on stale artifacts.
+
+Source navigation requires a Remote package to publish both its declaration map and the `src` file referenced by the map. If package `files` omits either side, types still compile but consumer navigation stops at the generated DTS. The workspace manifest check must therefore treat both as one publication contract.
+
+The permissive SRC descriptor does not validate the internal structure of ordinary JSON. After a Host Remote signature changes, the Web and strict type consumers must rebuild the lib; the first phase has no incremental contract watcher.
+
+Canonical public types require business DTOs to have type-only entries, which may expose packages whose Host types and implementation entries are currently mixed. The build rejects those boundaries instead of copying types to conceal them.
+
+Type imports and runtime contributions have different effects. `import type {}` extends only the static API. If a real calling environment omits the value contribution, the API Service must fail with an explicit "Remote not mounted" error.
+
+Browser and Host each hold their own Zod instances and cannot compare object identities across realms. Consistency is guaranteed only by canonical symbol keys, the same generated model, and wire behavior.
+
+A consumer may import a Remote contract that is not currently mounted on the Host. The types mean "this protocol capability was selected by the consumer," not that a corresponding Service currently exists in the target process; an unavailable endpoint must fail explicitly at runtime.
+
+Connection's general channel API must suit both the current HTTP carrier and a future WebSocket carrier. If the API exposes `fetch`, an HTTP request, or a route handle to the Gateway/API Service, WebSocket migration will pierce the Remote layer again. Those physical objects must therefore remain internal to Connection.
diff --git a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md
new file mode 100644
index 0000000000..9b2fbbd69f
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -0,0 +1,489 @@
+# Agent Note: TypeRT Gateway 定向方法调用
+
+Status: proposed
+
+[English](2026-08-02-typert-remote-method-calls.md) | 中文
+
+## Problem
+
+Host API Proxy 同时承担直接方法调用、带状态交互和 Session 事件流。三者的生命周期、路由语义和客户端编程界面不同，继续共用一个业务导出包会让业务 Service、传输协议、状态机和客户端类型彼此耦合。
+
+本方案只解决一次请求对应一次结果的定向方法调用。Permission、Approval 等带状态交互以及 Session 事件流不使用本方案，后续分别设计。
+
+直接方法调用的契约属于实现该行为的业务 Service。业务开发者应只声明哪些方法可以远程调用，而不应再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
+
+Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以不同类型合并同名 Cordis `Context`。Remote 投影不能把完整 Host 声明导入消费端，也不能依赖 Browser 专属类型；未来 TUI 若复用这套编程界面，也只能看到 Remote 标记的方法。本期不实现 TUI 接入，但实现边界不得阻断这种同构复用。
+
+## Proposal
+
+业务 Service 通过 `@Remote` 或 `@RemoteContext()` 声明可调用方法，并通过 `bindTypeRTGateway()` 显式加入 Gateway。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
+
+Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client API Service；该投影和 API 抽象保持平台无关，以便未来 TUI 复用。
+
+`@deepseek-ai/dsh-host-api-gateway` 在 `packages/host/api-gateway` 内提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.api`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在唯一 Connection/RPC 机制之上，使用独立 `/api2` channel；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
+
+## 组件和 Cordis 服务
+
+| 组件 | Cordis 服务 | 本方案中的职责 |
+|---|---|---|
+| `@deepseek-ai/dsh-type-meta` | 只声明 `ctx.typert` 的最小协议 | decorator、binding、descriptor、lookup/Context 和 Remote map；不依赖 compiler、Zod、Connection 或 Browser |
+| TypeRT registry | `ctx.typert` | 分开保存当前环境 reflection、导入的 Remote contribution、lookup provider 和 Context provider |
+| TypeRT generator/loader | 无新增业务服务 | 从 Host/Client Program 生成三类 `lib` 产物，并把当前环境产物注册到 `ctx.typert` |
+| Host API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service，解码参数、解析 receiver、调用方法和编码结果 |
+| Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、RPC envelope、rpcId、序列化、trust 和错误传输，并承载 `/api` 与 `/api2` 两个隔离 channel |
+| Host API Gateway 的 Client face | `ctx.api` | mount Remote contribution，实体化根 API 和 scoped API，把规范调用交给 `ctx.connection.rpc` |
+| Client Remotes | 无新增服务 | 作为 Client 业务的唯一 Remote facade，选择并挂载 `/remote` contribution，同时传递 Gateway Client face 和所选 API 的类型声明 |
+| Agent/Session owning 包 | 既有领域服务 | 同时提供静态 interface merge 与运行时 lookup/Context provider |
+| Goal 等业务包 | 既有业务 Service | 只声明 binding、Remote 方法和唯一 DTO，并导出生成的 `/remote` 子路径 |
+
+Host Gateway 不依赖 `ctx.agents`、`ctx.sessions`、`ctx.goals` 或 `ctx.httpServer` 的具体实现。Client API 不理解物理 carrier，Connection 也不理解 Goal、Agent、lookup、`InvocationDescriptor` 或 Client API namespace。
+
+## 业务声明
+
+普通直接调用使用 `@Remote`。迁移到现存 Service 或 Registry 时不重命名、不改变存量方法；类末尾新增 `remoteExport*` 出口，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
+
+```text
+export class GoalService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+
+  create(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
+    // Existing business method remains unchanged.
+  }
+
+  @Remote('create')
+  remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
+    return this.create(agent, request)
+  }
+}
+```
+
+`goals` 是明确的 Cordis service key，并默认作为 wire namespace。只有协议 namespace 确实需要与 service key 不同时，才通过 `bindTypeRTGateway()` 的选项覆盖。
+
+需要在某类隔离 Context 中查找 Service receiver 时使用 `@RemoteContext()`。Context identity 不进入业务方法参数：
+
+```text
+export class ScopedGoalService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+
+  @RemoteContext('agent', 'create')
+  remoteExportCreate(request: CreateGoalRequest): Promise<CreateGoalResult> {
+    // Runs against the goals service resolved from the Agent Context.
+  }
+}
+```
+
+同一个 endpoint 只能选择一种调用模式。需要显式 `Agent` 参数的流程使用 `@Remote`；需要切换到 Agent Context 再解析 scoped receiver 的流程使用 `@RemoteContext('agent')`，两者不会由 TypeRT 根据方法体或参数缺失自动猜测。
+
+业务包只依赖轻量的 `@deepseek-ai/dsh-type-meta`。它提供 decorator、`bindTypeRTGateway()`、lookup、Remote Context 和 descriptor 的声明协议，不依赖 TypeScript compiler、Zod、HTTP 或 Client runtime。
+
+## Decorator 与显式 Gateway facet
+
+Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteContext('agent', 'create')` 的参数是外部方法名，实际成员名保持 `remoteExportCreate`；未给别名时才使用成员名作为外部方法名。`typertGateway` 是 Service 加入 Gateway 的唯一显式标志，使业务类和运行时实例都能直接看出这项能力。
+
+SRC 运行时允许 decorator 在 `dsh-type-meta` 内部的 `WeakMap` 记录 prototype、方法名和调用模式。它不向 Service 实例、prototype、constructor 或方法函数写入自定义属性。
+
+LIB 的严格方法发现、类型解析和 descriptor 生成由 TypeRT compiler 完成。生成过程不改写业务源码，也不向 `bindTypeRTGateway()` 偷注生成参数。
+
+## Lookup 与 Remote Context 注册
+
+Gateway 不内置 Agent、Session 或其他业务对象分支。对象所属包同时提供静态声明和运行时 provider：
+
+```text
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTLookupMap {
+    agent: TypeRTLookup<Agent, SessionId>
+  }
+}
+
+ctx.typert.lookups.register('agent', {
+  parameter: 'agent',
+  wire: 'agentId',
+  resolve: sessionId => resolveAgent(sessionId),
+})
+```
+
+静态声明让 TypeRT 知道 `Agent` 在 wire 上对应 `SessionId`；运行时 provider 负责把请求中的 `agentId` 解析为当前活的 `Agent` 对象。缺少任一侧时，LIB 构建或最早可解析的运行时注册直接失败。
+
+Agent、Session 等 lookup 对象只能各自占据一个顶层参数位置。普通 JSON request 可以作为另一个完整参数传入，但本方案不支持 `request.agent`、对象解构、对象数组、嵌套 lookup 或从任意复杂结构中搜索 ID。
+
+Remote Context 使用独立的 merge-extensible map 和 provider。Agent 包注册 `agent` Context provider，负责用 wire identity 找到 Agent Context，并从该 Context 解析 descriptor 指定的 service key；Gateway 不知道 Agent Context 的内部结构。
+
+Client 侧也注册 `agent` Context binder。binder 只负责从一次调用所在的 Context 取得 `SessionId`；它不枚举 Scope，也不逐个复制方法。scoped namespace 由 Cordis Service tracker 自动 rebind 到当前 Agent Context。
+
+## InvocationDescriptor
+
+TypeRT、SRC 弱解析器、Host Gateway 和 Client API 之间只交换一种规范描述：
+
+```text
+InvocationDescriptor {
+  id: '@deepseek-ai/dsh-goal#goals/create'
+  service: 'goals'
+  namespace: 'goals'
+  method: 'create'
+  implementation: 'remoteExportCreate'
+  invocation: direct | { context: 'agent', wire: 'agentId' }
+  scope?: { context: 'agent', wire: 'agentId' }
+  parameters: [
+    { name, wire, source: json | lookup, lookup?, codec }
+  ]
+  result: codec
+  sourceLocation
+}
+```
+
+`method` 是 endpoint 和 Client API 使用的外部短名，`implementation` 是 Host receiver 上的真实成员名；两者相同时可省略 `implementation`。`direct` descriptor 保留原始 Service 实例作为 receiver。Context descriptor 先通过对应 Context provider 找到 scoped Context，再以 descriptor 的 service key 解析 receiver。
+
+严格生成器只在 direct 方法恰好包含一个 lookup 参数、同名 `TypeRTContextMap` 声明存在且两者使用同一 wire 类型 symbol 时写入 `scope`。`scope.wire` 必须指向该 lookup 参数；它声明消费端可以从调用所在 Context 补入这个参数，不改变 Host receiver 或 endpoint。多个 lookup、缺少 Context 声明或 wire 类型不一致时不生成 scoped 投影，其中类型不一致属于构建错误。
+
+参数顺序来自方法签名，HTTP 字段来自参数名或 lookup 声明。Gateway 不根据请求内容推断可选字段、Context 类型、lookup 类型或缺失参数，也不会合成业务默认值。
+
+LIB codec 带有 Zod schema 和“package + 公共 subpath + export name”的规范 `typeSymbol`；SRC codec 只标记 `src-json`。Host 和消费端运行在不同 JavaScript realm 时会各自持有 Zod 实例，但这些实例由同一 TypeRT 模型和 symbol key 生成。
+
+descriptor 只存在于两端本地 registry。wire 上只有 `/api2` channel、endpoint 和 `{ args }` payload；Host 用自己的 descriptor 解码和调用，Client 用自己的对应 descriptor 编码参数和验证结果。
+
+## TypeRT 运行时 registry
+
+```text
+ctx.typert.local     当前进程自己的 Host 或 Client reflection
+ctx.typert.remotes   消费端显式 mount 的对端 Remote contribution
+ctx.typert.lookups   wire ID 到 Host 活对象的 provider
+ctx.typert.contexts  Host Context resolver 与 Client Context binder
+```
+
+每次注册都返回由调用方 Cordis fiber 持有的 disposer。Gateway 和 API Service 先读取当前快照再订阅变化，因此业务 Service、generated contribution、provider 和消费者可以按任意顺序加载；任一依赖 dispose 后，相关 endpoint 或方法立即失效。
+
+Registry 的 Host 根入口拥有完整 `TypeRTService` interface merge；Host 与 Client 共用的 registry 实现位于无环境声明的独立模块。Registry `/client` 入口只引用该共享实现，不经过 Host 根入口，因此不会把 Host Cordis 声明带入 Client Program。
+
+## 唯一类型、符号与 Zod
+
+Remote Client DTS 不复制业务 DTO，也不重新声明一个结构相同的影子类型。它只从不携带 Host Cordis merge 的公共纯类型 subpath 引用原始符号：
+
+```text
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { CreateGoalRequest, CreateGoalResult } from '@deepseek-ai/dsh-goal/types'
+```
+
+因此 `SessionId`、Agent wire ID、request 和 result 在 Host 与 Browser Client 中都指向同一 TypeScript declaration，未来 TUI 复用时也不需要第二份类型。DTO 的跳转定义、重命名和引用查找回到业务类型的唯一源码位置，而不是停在生成文件中的副本。
+
+Remote API 方法本身使用 declaration map 导航。TypeRT 把 `InvocationModel.location` 固定在 Host 的 `remoteExport*` 方法名 token，并在 namespace interface 的对应属性上写入 source-map segment；TypeScript editor 从 `ctx.api.models.list` 取得生成 declaration 后，再沿 `typert.remote-client.d.ts.map` 跳到 Host Service 的 `remoteExportList` 远程出口。该出口继续显式调用不改名的存量 `list()`，map 不把 decorator、class 或整个签名误当成方法定义位置。
+
+TypeRT 为同一 symbol key 生成 wire Zod codec。Host Gateway 用它校验输入和编码结果，Client API 可以用它编码参数并校验响应；复杂类型无法生成严格 codec 时，LIB 构建失败，不降级为 `unknown` 或无校验 JSON。
+
+Remote 方法引用的命名业务类型必须从纯类型公共 subpath 导出。如果唯一可达入口会带入 Host Service、Cordis `Context` merge 或 Host-only 实现，构建失败并要求业务包提供安全的类型出口。原始值、字面量和 TypeRT 明确支持的简单组合不需要额外命名。
+
+lookup 参数不会把 `Agent` class 暴露给消费端。Remote 投影引用 lookup 声明中的唯一 ID 类型，例如 `SessionId`；Host 内部仍以唯一的 `Agent` class symbol 完成对象解析。
+
+## 三种产物与两个 TypeScript Program
+
+Host 与 Client 仍然只有两个独立 TypeScript Program，但 TypeRT 生成三种性质不同的产物：
+
+```text
+Host Program
+├─ typert.host.js / typert.host.d.ts
+│  Host 自身的 Service、Event、Object、schema 和 inbound Gateway 信息
+└─ typert.remote-client.js / typert.remote-client.d.ts / typert.remote-client.d.ts.map
+   Host Remote 对任意消费环境的 wire 投影
+
+Client Program
+└─ typert.client.js / typert.client.d.ts
+   Client 自身的 Service、Event、Object 和 schema 信息
+```
+
+`remote-client` 是 Host Program 的第二个 emitter，不是第三个 Program，也不是 Client 本地 face。它不包含 Host Cordis merge、Service class、Context class 或实现代码，不进入 Host 本地 reflection registry。
+
+Host lib 构建负责完成严格 Host 分析并产出 Host 本地 artifact 与 Remote 消费端 artifact；Client lib 随后消费 Remote DTS。完整顺序为：
+
+```text
+Host lib build
+→ 生成 typert.host.{js,d.ts}
+→ 生成各业务包 lib/typert.remote-client.{js,d.ts,d.ts.map}
+→ 完成 Client lib 和 typert.client 产物
+→ Vite 构建 Web
+```
+
+现有顶层 `build` 仍表现为先 `build:lib`、再 `build:web`，但 `build:lib` 内部必须先完成 Host 与 Remote artifact，再启动 Client TypeScript 编译。一次干净构建不能依赖上次残留的 `.d.ts`。
+
+## `/remote` 包入口
+
+每个提供 Remote 方法的业务包导出生成的 `/remote` 子路径：
+
+```text
+"./remote": {
+  "types": "./lib/typert.remote-client.d.ts",
+  "default": "./lib/typert.remote-client.js"
+}
+```
+
+消费代码通过业务包本身选择能力：
+
+```text
+import goalsRemote from '@deepseek-ai/dsh-goal/remote'
+```
+
+该 import 让 `.d.ts` 的 map augmentation 进入当前 TypeScript project，同时把同一契约的 JS descriptor 作为值交给运行时。未 import 的业务包不会扩展当前 project 的 Remote API 类型。
+
+业务 package 的发布文件必须同时包含 `lib/typert.remote-client.d.ts.map` 和 map 指向的 `src` 文件。生成 DTS 以 `//# sourceMappingURL=typert.remote-client.d.ts.map` 引用相邻 map；map 中的 source 从 `lib` 相对指向业务源码，例如 `../src/index.ts`。`/remote` export 不单独列出 map，package `files` 负责把它与源码一起发布。
+
+仅需要静态类型时可以使用 `import type {} from '@deepseek-ai/dsh-goal/remote'`；这种 import 在运行时会被擦除，不会加载 JS，也不能触发任何运行时注册。需要真实调用的环境必须把普通 value import 得到的 contribution 交给 API Service。
+
+workspace 对 `/remote` 的解析必须明确指向 `lib` 生成物，不能被通用 package-to-`src` paths 规则带回 Host 源码。普通业务 import 仍可按各环境既有规则解析到 SRC 或 LIB。
+
+## 消费端严格 API 类型
+
+Remote DTS 同时扩展平面 endpoint map、direct namespace interface、namespace map 和 scoped map，而不扩展全局 Cordis `Context`：
+
+```text
+interface TypeRTRemoteNamespace$676f616c73 {
+  create: (
+    agentId: SessionId,
+    request: CreateGoalRequest,
+  ) => Promise<CreateGoalResult>
+}
+
+interface TypeRTRemoteMap {
+  'goals/create': (
+    agentId: SessionId,
+    request: CreateGoalRequest,
+  ) => Promise<CreateGoalResult>
+}
+
+interface TypeRTRemoteNamespaceMap {
+  goals: TypeRTRemoteNamespace$676f616c73
+}
+
+interface TypeRTRemoteContextMap {
+  'agent:goals/create': (
+    request: CreateGoalRequest,
+  ) => Promise<CreateGoalResult>
+}
+```
+
+`TypeRTRemoteMap` 保留规范 endpoint 签名，供协议类型和反射使用。根 API 类型直接读取 `TypeRTRemoteNamespaceMap`，不通过 key-remapped mapped type 间接推导方法；TypeScript Language Service 无法把这种间接属性稳定导航到 declaration map。namespace interface 名由 namespace 的 UTF-8 bytes 编成 hex，`goals` 因而稳定得到 `TypeRTRemoteNamespace$676f616c73`。不同 package 对同一 namespace 生成同名 interface，依靠 module augmentation 合并各自方法，且 `TypeRTRemoteNamespaceMap.goals` 始终引用同一类型。
+
+TypeRT 把 `TypeRTRemoteContextMap` 按 Context key 投影到专用 Scope 类型。最终编程界面保持：
+
+```text
+api.goals.create(agentId, request)
+agent.goals.create(request)
+```
+
+Agent Scope 自动提供自己的 `SessionId`。因此带 `agent` lookup 的 `@Remote` 方法可以同时生成 root 和 scoped 两种消费端签名；`@RemoteContext('agent')` 方法也省略独立的 Context identity，但只生成 scoped 签名。本期只有 Client Agent Context 获得 `goals`，Root Context 不获得该属性；未来 TUI 复用时必须维持相同的 Scope 限制。
+
+`RemoteApi` 保持平台无关，Browser Client 把它作为自己的 `ClientApi`。未来 TUI 若复用该类型，也必须通过专用 API 对象和 Agent Scope 使用它，不能把 Host `Context` 当成更宽的 Service 集合；未标记的 public Service 方法不会进入 Remote maps。
+
+## Client TypeRT 与 API Gateway Client face
+
+一个消费环境的 TypeRT 同时维护本地信息和从其他环境导入的 Remote 信息，但两者存放在不同 registry：
+
+```text
+TypeRT.local    当前环境自己的反射模型
+TypeRT.remotes  已导入的 Remote contribution
+```
+
+`@deepseek-ai/dsh-client-remotes/client` 集中加载需要的 Remote contribution：
+
+```text
+import goalsRemote from '@deepseek-ai/dsh-goal/remote'
+import sessionsRemote from '@deepseek-ai/dsh-session/remote'
+
+ctx.api.mount(goalsRemote)
+ctx.api.mount(sessionsRemote)
+```
+
+Client 业务包只引用 `@deepseek-ai/dsh-client-remotes/client`，不直接依赖 Host API Gateway 或各业务 `/remote` 运行时入口。Client Remotes 自己依赖 Gateway Client face，并通过声明 re-export 把所选 Remote map 传给业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
+
+`ctx.api.mount()` 把 contribution 注册到 `TypeRT.remotes`，并由调用该方法的 Cordis fiber 持有 disposer。endpoint 重复、同一 namespace/method 模式冲突或 descriptor 与现有类型身份冲突时直接失败。
+
+API Service 把 `@Remote` descriptor 实体化为根 `api` 上的真实函数。函数按 descriptor 的位置参数顺序构造具名 `args`，执行 Client strict codec，然后调用 `ctx.connection.rpc.call('/api2', endpoint, { args })`。
+
+带 `scope` 的 direct descriptor 和 `@RemoteContext` descriptor 都不为每个 Agent Scope 复制函数。API Service 为每个 scoped namespace 建立一个 root singleton Cordis Service，并在该 Service 上实体化方法；Cordis tracker 在 `agent.goals.create()` 调用时把 Service 的 `this.ctx` rebind 到当前 Agent Context。方法再通过对应 Context binder 从 `this.ctx` 取得 identity。direct scoped 投影用 identity 替代 `scope.wire` 指定的 lookup 位置，Context descriptor 则把 identity 写入 receiver 的独立 wire 字段；两者都发起同一种 `/api2` 调用。
+
+```text
+root ctx.api.goals.create(agentId, request)
+  → direct descriptor
+  → ctx.connection.rpc.call('/api2', 'goals/create', { args })
+
+agent.goals.create(request)
+  → tracker 将 namespace Service rebind 到 agent Context
+  → agent binder 从 caller Context 取得 agentId
+  → 用 agentId 补入同一 direct descriptor 的 lookup 参数
+  → ctx.connection.rpc.call('/api2', 'goals/create', { args })
+```
+
+Root `Context` 不 merge scoped `goals` 类型；只有 `AgentContext` 通过 `RemoteContextApi<'agent'>` 获得该属性。若调用方绕过类型从 Root 动态调用 scoped 方法，binder 明确报错。若 Client 已有同名 Cordis service，或两个 contribution 冲突占用同一 namespace/method，mount 直接失败，不覆盖现有服务。
+
+生成的 Remote JS 只包含 descriptor、symbol key 和 codec，不打包 Host Service 实现。API Service 可以据此创建真实函数，因此本方案不依赖 JavaScript Proxy；Proxy 可以作为实现选择，但不会成为类型或反射来源。
+
+## 跨环境同构约束
+
+Remote API 是消费端能力，不等同于 Browser API。本期只实现 Browser Client 的 contribution 挂载、Connection RPC 调用和 Agent Scope 关联。
+
+Remote DTS、Remote JS、`RemoteApi`、`InvocationDescriptor`、Remote RPC 数据协议和 Context binder 不得依赖 DOM、Browser module loader 或 HTTP。Browser Client 通过 Connection 把 descriptor 实体化的方法编码为 `/api2` RPC 调用。
+
+未来 TUI 可以在不改变业务 decorator、Remote maps 和 API 调用形状的前提下接入同一调用抽象。届时 TUI 可见的 API 仍只能由 `@Remote` 和 `@RemoteContext` 生成，不能因为它与 Host 同进程就绕过 Remote 限制直接暴露 Service 方法。
+
+TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均不属于本期实现。
+
+Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 契约变化后必须重新执行 lib build，再启动或重启 Web；本方案不在第一阶段实现 Remote contract 的增量 watch。
+
+## SRC 与 LIB 运行模式
+
+SRC 面向本地源码启动。`@Remote` 和 `@RemoteContext()` 的 WeakMap 记录给出方法名和调用模式，运行时从 JavaScript 函数签名读取顺序参数名，并结合已注册 lookup/Context provider 生成弱 descriptor。
+
+例如 `@Remote('create') remoteExportCreate(agent, request)` 解析为外部方法 `create`、实现成员 `remoteExportCreate` 和两个顶层参数；lookup 注册把 `agent` 改写为 wire 字段 `agentId`，`request` 按同名 JSON 参数传递。SRC 不启动 `ts.Program`，不使用 preload、loader hook、源码生成或模块改写，也不检查普通 JSON 对象的内部结构。
+
+SRC 无法明确解析的签名在 Service 挂载时失败。对象解构、默认参数造成的歧义、rest 参数、嵌套 lookup 和复杂类型不做猜测。
+
+LIB 面向 CI、发布和 Web 前置构建。TypeRT 扫描完整 Host project，检查 Remote decorator、显式 binding、service key、endpoint 冲突、lookup/Context 声明、公共符号可达性、JSON codec 和结果 codec，并生成严格 descriptor。
+
+LIB 运行时只加载 `lib` 中的 definition，不启动 TypeScript compiler。Host Gateway 后续的 Service 关联、lookup、Context 解析、调用和响应编码不区分 descriptor 来自 SRC 弱解析还是 LIB 严格生成。
+
+CI 和发布运行 LIB。全仓 coverage 全部切换到 LIB 是独立后续工作，不阻塞本次直接方法调用实现。
+
+## Host Gateway 注册
+
+Host Gateway 同时观察 TypeRT Remote definition 和 Cordis Service 生命周期。当某个带 `typertGateway` facet 的 Service 与同 service key 的 definition 都可用时，Gateway 注册其 endpoint；两者到达顺序不影响结果。
+
+Gateway 启动时先读取 TypeRT definition 和 Cordis reflection store 的当前快照，再订阅 registry change 与 `internal/service`。它按 service key reconcile definition、活 Service 和 binding；Service 被替换或 dispose 时撤销对应 endpoint。definition、lookup provider 或 Context provider 撤销时，依赖它们的 endpoint 立即不可调用，不保留失效对象或降级为原始 ID 调用。
+
+普通 `@Remote` 调用保留原始 Service 实例作为 receiver。lookup 成功后，Gateway 按 descriptor 的参数顺序调用 `implementation ?? method` 指定的成员。
+
+`@RemoteContext('agent')` 调用先由 Agent Context provider 解析 wire identity，再从该 Context 读取 descriptor 的 service key 并调用 scoped receiver。业务方法不会收到隐藏 Context 参数或 Agent ID。
+
+```text
+ctx.typertGateway.invoke({ namespace, method, args })
+→ 查找本地 InvocationDescriptor 与 live receiver
+→ 按参数 descriptor 读取具名 wire 字段
+→ codec 解码普通值或 lookup ID
+→ lookup provider 把 ID 解析为活对象
+→ direct 使用原 Service；context 先解析 scoped Context 和 Service
+→ Reflect.apply(receiver[implementation ?? method], receiver, orderedArgs)
+→ result codec 编码业务结果
+```
+
+`ctx.typertGateway.invoke()` 是 carrier-independent 的 Host 入口。它不创建 rpcId、RPC envelope 或 HTTP response；它只返回编码结果，或产生由 Connection RPC adapter 映射的 Gateway 错误。
+
+## `/api2` 调用链
+
+`/api2` 是唯一 Connection/RPC 机制上的独立协议 channel，不是 Gateway 自建的 transport。Gateway 只向 Connection 注册一个本地 handler；本期在现有 HTTP Connection 中增加这项通用 channel 能力：
+
+```text
+ctx.connection.rpc.handle('/api2', (endpoint, payload) => {
+  const { namespace, method } = parseEndpoint(endpoint)
+  const { args } = parsePayload(payload)
+  return ctx.typertGateway.invoke({ namespace, method, args })
+})
+```
+
+Connection Host half 从唯一 HTTP Server 取得 handle，复用同一 RPC bridge、request/response envelope、rpcId、序列化、trust、transport error 和 `RpcError`。当前物理映射是：
+
+```text
+POST /api2/<namespace>/<method>
+```
+
+Remote payload 使用具名 JSON 对象，不使用位置数组，也不发送 `InvocationDescriptor`。普通 Goal 调用的 payload slot 是：
+
+```json
+{
+  "args": {
+    "agentId": "session-1",
+    "request": {
+      "objective": "finish the migration"
+    }
+  }
+}
+```
+
+完整链路为：
+
+```text
+ctx.api.goals.create(sessionId, request)
+→ Client InvocationDescriptor 编码 { args: { agentId, request } }
+→ ctx.connection.rpc.call('/api2', 'goals/create', { args })
+→ Connection 创建 rpcId 和既有 client-request envelope
+→ 当前 carrier 发送 POST /api2/goals/create
+→ Connection Host half 执行 trust、反序列化和 RPC 分发
+→ /api2 handler 调用 ctx.typertGateway.invoke(...)
+→ Host InvocationDescriptor 解码、lookup、receiver 解析和 Reflect.apply
+→ result codec 编码
+→ Connection 写入既有 RPC result 并回送相同 rpcId
+→ Client result codec 验证并返回 CreateGoalResult
+```
+
+Remote 不定义第二层 `{ ok, value/error }` response。成功值和 Gateway 错误直接使用既有 RPC response 的 `result`；Gateway adapter 负责把 endpoint、schema、lookup、Context、Service 和业务调用失败映射为 `RpcError`，Connection 负责传输该错误。
+
+Gateway 不处理逐方法权限、调用者身份、取消、幂等或长连接状态。本工作只扩展 Connection 的通用 channel 注册和调用能力，不改变现有 `/api`、trusted connection、trusted-host 或 privileged method 语义；Connection/WebSocket 迁移后续独立完成。
+
+## Connection 与协议边界
+
+API Service 负责 Remote contribution、方法实体化、Scope 绑定以及位置参数与 descriptor 的对应。Gateway 负责 Host descriptor、lookup、Context 和业务调用。Connection 只负责把 `/api2`、endpoint 和 `{ args }` 作为一个 RPC 调用发送到目标并返回既有 RPC result；它不理解 Goal、Agent、lookup、descriptor 或 Client API 类型。
+
+`/api` 与 `/api2` 共享唯一 Connection、Server、RPC envelope 和连接生命周期，但保持协议隔离。Connection 从 HTTP 迁移到 WebSocket 时，`/api2` 从物理路径自然变成逻辑 channel；Remote payload、业务 decorator、生成的 DTS、Remote API 类型和 Agent Scope 编程界面都不变化。
+
+## 包边界
+
+- `@deepseek-ai/dsh-type-meta`：轻量 decorator、binding、lookup、Remote Context 和 descriptor 协议。
+- TypeRT generator：分析 Host/Client Program，生成本地 face 和 Remote 消费端投影，并生成规范 symbol/Zod 信息。
+- TypeRT runtime：分别保存当前环境的 local reflection 与导入的 Remote contribution。
+- `@deepseek-ai/dsh-host-api-gateway`：默认入口关联 Host definition 与 Service，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api2` handler；`/client` 入口挂载 Remote contribution，创建严格 API 方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
+- `@deepseek-ai/dsh-client-remotes`：Client 业务唯一依赖的 Remote facade；直接依赖 Gateway Client face，选择 `/remote` contributions，并向业务包传递合并后的 API 类型。
+- Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、RPC envelope、rpcId、序列化、trust 和错误传输，同时承载隔离的 `/api` 与 `/api2` channel。
+- Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
+- 业务 Service 包：声明 binding、Remote 方法及其 request/result 类型，并导出生成的 `/remote` 子路径。
+
+## 首期实现范围
+
+第一条纵向链路实现 `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api2 → Host Gateway → GoalService.remoteExportCreate()`，并证明同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.api.goals.create(agentId, request)` 与 `agentCtx.goals.create(request)`。`@RemoteContext('agent')` 的 scoped receiver 语义继续保留为独立模式。
+
+本期实现 Connection 的通用第二 channel API 及当前 HTTP carrier 映射，但不实现 WebSocket 迁移、TUI runtime、TUI carrier 或 TUI Agent Scope 接线。本 RFC 也不设计 Permission/Approval 状态机、Session 事件流、调用授权、取消、重试、幂等和跨版本协议兼容。
+
+## Alternatives considered
+
+**继续使用中央 API Proxy 包。** 该方案要求业务方法、Host 路由和 Client 接口在多个位置重复声明，也会继续把直接调用、带状态交互和事件流绑在同一生命周期中，因此不采用。
+
+**让 decorator 在运行时完成严格反射。** JavaScript decorator 无法恢复擦除后的 TypeScript 类型、公共符号身份和完整 Zod codec；向 constructor 注入 compiler 私有 symbol 又会隐藏业务类的真实依赖，因此严格信息由 TypeRT compiler 生成。
+
+**SRC 启动时使用 preload、loader hook 或完整 `ts.Program`。** 这能复用 LIB 分析，但增加所有源码启动入口的要求。SRC 只需要可用的弱 descriptor，因此采用 decorator 标记、函数参数名和显式 provider；严格检查留给 LIB contract pass。
+
+**手写 Client interface。** 手写接口不能保证只包含 Remote 标记的方法，也会与 Host 签名、lookup ID 和 Zod schema 漂移，因此 Client 类型从 Host Program 自动投影。
+
+**使用 TypeScript language-service/compiler plugin 让 Client 直接理解 decorator。** 这会让编辑器、Vite、tsc、tsx 和发布消费者都依赖额外插件，接入面过大，因此生成普通 `.d.ts` 和标准 declaration map。
+
+**把完整 Host DTS 导入 Client 或 TUI。** 该方案会带入 Host Service 和 Cordis interface merge，并向消费端暴露未标记方法。Remote DTS 只引用纯类型公共符号并扩展专用 Remote maps。
+
+**只生成 Remote DTS，不生成 JS。** 类型可以成立，但运行时无法枚举 endpoint、codec 和 Context 模式，只能依赖 Proxy 或另一份手写注册表，因此同一次 Host 投影同时生成 Remote JS contribution。
+
+**让 `/remote` 的顶层 import 偷偷注册全局状态。** ESM 求值时未必已有目标 Cordis Context，多个 Context、HMR 和 dispose 也无法明确归属，因此普通 value import 只返回 contribution，由环境 assembly 的 API Service 显式挂载。
+
+**为 Remote 新建独立 transport、HTTP route 和响应信封。** 这会复制现有 Connection 的 Server ownership、rpcId、序列化、trust、错误和未来 WebSocket 生命周期，并让两个 RPC 栈分别迁移，因此 `/api2` 作为独立协议 channel 复用唯一 Connection/RPC 机制。
+
+## Acceptance criteria
+
+- Goal Service 保留既有业务方法，在类末尾通过显式 `typertGateway` 和 `@Remote('create') remoteExportCreate(...)` 新增远程出口，不维护第二份路由、codec 或 Client 方法清单。
+- 一次干净 `build:lib` 先生成 Host Remote contract，再完成 Host 和 Client 消费端编译，并在业务包 `lib` 下产生可通过 `/remote` 导入的 JS、DTS 和 DTS map。
+- 导入 `@deepseek-ai/dsh-goal/remote` 后，消费 project 获得严格的 `api.goals.create(...)` 类型；不导入时该 namespace 不进入类型；从 `create` 跳转定义会通过 declaration map 到达 Host Service 的 `remoteExportCreate` 实现。
+- Client assembly 挂载同一个 import 得到的 JS contribution 后，TypeRT 能反射 endpoint、参数、结果、lookup、Context 和 Zod 信息，API Service 无需手写 stub 即可创建调用方法。
+- Remote DTS、Remote JS、`RemoteApi` 和 descriptor 协议不依赖 Browser 专属能力，且类型模型无法暴露未标记的 Goal Service 方法，为未来 TUI 同构接入保留边界。
+- `agent.goals.*` 通过 Cordis tracker 和 Context binder 取得调用 Scope，Root Context 不获得 Agent-only 类型，且不为每个 Scope 复制函数。
+- `/api2/goals/create` 能把 `agentId` 解析为唯一 Agent 对象，调用原始 Goal Service receiver，并通过既有 RPC result/error 返回结果。
+- `/api2` 与 `/api` 共享唯一 Connection/RPC carrier，但保持协议隔离；Remote 不直接注册 HTTP Server handle，也不定义第二套 response envelope。
+- Connection 提供通用 channel 注册和调用能力，并把 `/api2` 映射到当前 HTTP carrier；现有 `/api` 行为与 trust 语义保持不变。
+- 现有 `/api`、Connection/trusted connection、Permission/Approval 和 Session 事件流行为不因本实现改变。
+
+## Risks
+
+Remote API 类型依赖生成的 `lib` 声明，构建编排必须在 Host 和 Client 消费端编译前完成 contract pass；顺序错误会让干净构建依赖陈旧产物。
+
+源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布契约。
+
+SRC 弱 descriptor 不验证普通 JSON 内部结构。Host Remote 签名变化后，Web 和严格类型消费者必须重新执行 lib build；第一阶段没有增量 contract watch。
+
+公共类型唯一性要求业务 DTO 具有纯类型出口，可能暴露现有包中 Host 类型与实现入口混杂的问题。构建会拒绝这些边界，而不是复制类型掩盖问题。
+
+类型 import 与运行时 contribution 是两种不同效果。`import type {}` 只扩展静态 API；真实调用环境遗漏 value contribution 时，API Service 必须以明确的“Remote 未挂载”错误失败。
+
+Browser 与 Host 各自持有 Zod 实例，不能依赖对象 identity 跨 realm 比较；一致性只由规范 symbol key、同一生成模型和 wire 行为保证。
+
+消费端可以导入 Host 当前未挂载的 Remote contract。类型表示“该协议能力已被消费端选择”，不保证目标进程当前存在对应 Service；运行时 endpoint 不可用必须明确失败。
+
+Connection 的通用 channel API 必须同时适合当前 HTTP carrier 和后续 WebSocket carrier。若接口把 `fetch`、HTTP request 或 route handle 暴露给 Gateway/API Service，WebSocket 迁移会再次穿透 Remote 层，因此这些物理对象必须留在 Connection 内部。

From 64a963da0b42f9cd389d133656f73b1936760c41 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 5 Aug 2026 11:17:47 +0800
Subject: [PATCH 116/516] feat: add TypeRT remote gateway infrastructure

---
 apps/cli/composition.md                       |   9 +
 docs/capability-seams.md                      |   7 +-
 docs/config-catalog.md                        |   8 +-
 docs/cordis-catalog/events.md                 |   8 +-
 docs/cordis-catalog/services.md               |  31 +-
 docs/module-graph.md                          |  14 +-
 package.json                                  |   5 +-
 packages/bundle/base/cordis.patch.yml         |   9 +
 packages/bundle/base/package.json             |   3 +
 .../client/connection/src/client/index.ts     |   7 +
 packages/client/connection/src/client/rpc.ts  |  75 ++
 packages/client/connection/src/index.ts       | 101 +-
 packages/client/connection/src/rpc-host.ts    | 150 +++
 packages/client/connection/src/rpc.ts         |  59 ++
 .../connection/tests/client-apply.spec.ts     |  37 +
 .../client/connection/tests/node-half.spec.ts |  92 +-
 .../client/runtime/tests/client-apply.spec.ts |   3 +
 .../client/runtime/tests/wire-events.spec.ts  |   3 +
 packages/client/tsdown.client.ts              |   7 +-
 .../cordis/tool-cordis/src/api-catalog.ts     |  46 +-
 packages/core/agent/package.json              |   8 +
 packages/core/agent/src/index.ts              |  25 +
 packages/core/agent/tests/agent.spec.ts       |  26 +
 packages/core/agent/tsconfig.json             |   3 +
 packages/core/session/package.json            |   3 +
 packages/core/session/src/index.ts            |  16 +
 packages/core/session/tests/typert.spec.ts    |  26 +
 packages/core/session/tsconfig.json           |   3 +
 packages/host/api-gateway/README.i18n.yaml    |   6 +
 packages/host/api-gateway/README.md           |  36 +
 packages/host/api-gateway/README.zh.md        |  36 +
 packages/host/api-gateway/package.json        |  68 ++
 packages/host/api-gateway/src/client/index.ts | 370 ++++++++
 packages/host/api-gateway/src/index.ts        | 604 ++++++++++++
 packages/host/api-gateway/src/invariant.ts    |  30 +
 packages/host/api-gateway/src/types.ts        |  52 ++
 .../host/api-gateway/tests/client.spec.ts     | 222 +++++
 .../host/api-gateway/tests/gateway.spec.ts    | 795 ++++++++++++++++
 packages/host/api-gateway/tsconfig.json       |  27 +
 packages/host/api-gateway/tsdown.config.ts    |   3 +
 packages/host/apiproxy/src/api/index.ts       |   5 +
 packages/typert/generator/package.json        |   1 +
 packages/typert/generator/src/analyzer.ts     | 869 +++++++++++++++++-
 .../typert/generator/src/cordis-catalog.ts    |   2 +-
 packages/typert/generator/src/emitter.ts      | 538 ++++++++++-
 packages/typert/generator/src/model.ts        |  55 ++
 packages/typert/generator/src/renderer.ts     | 101 +-
 .../typert/generator/src/tsdown-plugin.ts     |  79 +-
 packages/typert/generator/src/workspace.ts    |  42 +-
 .../__snapshots__/type-model.spec.ts.snap     |   5 +
 .../tests/fixtures/remote-model/package.json  |   5 +
 .../remote-model/packages/domain/package.json |   9 +
 .../remote-model/packages/domain/src/index.ts |  19 +
 .../remote-model/packages/domain/src/types.ts |   2 +
 .../packages/domain/tsconfig.json             |  11 +
 .../remote-model/packages/remote/package.json |  24 +
 .../remote-model/packages/remote/src/index.ts |  30 +
 .../remote-model/packages/remote/src/types.ts |  20 +
 .../packages/remote/tsconfig.json             |  14 +
 .../fixtures/remote-model/tsconfig.base.json  |  20 +
 .../fixtures/remote-model/tsconfig.host.json  |   8 +
 .../fixtures/remote-model/type-meta.d.ts      |  45 +
 .../generator/tests/remote-model.spec.ts      | 486 ++++++++++
 .../generator/tests/schema-emitter.spec.ts    | 238 ++++-
 .../generator/tests/tools-catalog.spec.ts     |   2 +-
 .../generator/tests/tsdown-plugin.spec.ts     |  81 ++
 .../typert/generator/tests/type-model.spec.ts |  98 ++
 packages/typert/loader/src/index.ts           |  91 +-
 packages/typert/loader/tests/loader.spec.ts   | 210 +++++
 packages/typert/registry/package.json         |  15 +
 packages/typert/registry/src/client/index.ts  |  15 +
 packages/typert/registry/src/index.ts         | 220 +----
 packages/typert/registry/src/service.ts       | 584 ++++++++++++
 packages/typert/registry/src/types.ts         |   8 +
 packages/typert/registry/tests/typert.spec.ts | 184 +++-
 packages/typert/registry/tsconfig.json        |   3 +
 packages/typert/registry/tsdown.config.ts     |  26 +-
 packages/typert/type-meta/README.i18n.yaml    |   6 +
 packages/typert/type-meta/README.md           |  33 +
 packages/typert/type-meta/README.zh.md        |  33 +
 packages/typert/type-meta/package.json        |  42 +
 packages/typert/type-meta/src/index.ts        | 223 +++++
 packages/typert/type-meta/src/invariant.ts    |  30 +
 packages/typert/type-meta/src/types.ts        | 358 ++++++++
 .../type-meta/tests/fixtures/source-launch.ts |  29 +
 .../typert/type-meta/tests/type-meta.spec.ts  | 132 +++
 packages/typert/type-meta/tsconfig.json       |  21 +
 pnpm-lock.yaml                                |  61 ++
 scripts/client-bundle-purity.spec.ts          |   7 +
 scripts/gen-cordis-catalog.ts                 |   2 +
 scripts/gen-doc-graphs.ts                     |  11 +-
 .../verify-package-readme-model-experience.ts |   2 +
 tsconfig.base.json                            |  10 +-
 tsconfig.client.json                          |   2 +
 tsconfig.host.json                            |   2 +
 tsdown.config.ts                              |   4 +
 tsdown.typert-host.config.ts                  |  20 +
 vitest.config.ts                              |  30 +-
 98 files changed, 7812 insertions(+), 444 deletions(-)
 create mode 100644 packages/client/connection/src/client/rpc.ts
 create mode 100644 packages/client/connection/src/rpc-host.ts
 create mode 100644 packages/client/connection/src/rpc.ts
 create mode 100644 packages/core/session/tests/typert.spec.ts
 create mode 100644 packages/host/api-gateway/README.i18n.yaml
 create mode 100644 packages/host/api-gateway/README.md
 create mode 100644 packages/host/api-gateway/README.zh.md
 create mode 100644 packages/host/api-gateway/package.json
 create mode 100644 packages/host/api-gateway/src/client/index.ts
 create mode 100644 packages/host/api-gateway/src/index.ts
 create mode 100644 packages/host/api-gateway/src/invariant.ts
 create mode 100644 packages/host/api-gateway/src/types.ts
 create mode 100644 packages/host/api-gateway/tests/client.spec.ts
 create mode 100644 packages/host/api-gateway/tests/gateway.spec.ts
 create mode 100644 packages/host/api-gateway/tsconfig.json
 create mode 100644 packages/host/api-gateway/tsdown.config.ts
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/package.json
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/packages/domain/package.json
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/packages/domain/src/index.ts
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/packages/domain/src/types.ts
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/packages/domain/tsconfig.json
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/packages/remote/package.json
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/types.ts
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/packages/remote/tsconfig.json
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/tsconfig.base.json
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/tsconfig.host.json
 create mode 100644 packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
 create mode 100644 packages/typert/generator/tests/remote-model.spec.ts
 create mode 100644 packages/typert/registry/src/client/index.ts
 create mode 100644 packages/typert/registry/src/service.ts
 create mode 100644 packages/typert/type-meta/README.i18n.yaml
 create mode 100644 packages/typert/type-meta/README.md
 create mode 100644 packages/typert/type-meta/README.zh.md
 create mode 100644 packages/typert/type-meta/package.json
 create mode 100644 packages/typert/type-meta/src/index.ts
 create mode 100644 packages/typert/type-meta/src/invariant.ts
 create mode 100644 packages/typert/type-meta/src/types.ts
 create mode 100644 packages/typert/type-meta/tests/fixtures/source-launch.ts
 create mode 100644 packages/typert/type-meta/tests/type-meta.spec.ts
 create mode 100644 packages/typert/type-meta/tsconfig.json
 create mode 100644 tsdown.typert-host.config.ts

diff --git a/apps/cli/composition.md b/apps/cli/composition.md
index 1da393bd06..0246f6163f 100644
--- a/apps/cli/composition.md
+++ b/apps/cli/composition.md
@@ -18,6 +18,12 @@ flowchart LR
   cfg --> plugin_dsh_base_llm
   plugin_dsh_base_session["session<br/>@deepseek-ai/dsh-session"]
   cfg --> plugin_dsh_base_session
+  plugin_dsh_base_typert["typert<br/>@deepseek-ai/dsh-typert-registry"]
+  cfg --> plugin_dsh_base_typert
+  plugin_dsh_base_typert_loader["typert-loader<br/>@deepseek-ai/dsh-typert-loader"]
+  cfg --> plugin_dsh_base_typert_loader
+  plugin_dsh_base_typert_gateway["typert-gateway<br/>@deepseek-ai/dsh-host-api-gateway"]
+  cfg --> plugin_dsh_base_typert_gateway
   plugin_dsh_base_session_title["session-title<br/>@deepseek-ai/dsh-session-title"]
   cfg --> plugin_dsh_base_session_title
   plugin_dsh_base_session_title_llm["session-title-llm<br/>@deepseek-ai/dsh-session-title-first-message-llm"]
@@ -159,6 +165,9 @@ flowchart LR
 | `repository-plugins` | `@deepseek-ai/dsh-repository-plugin` |
 | `llm` | `@deepseek-ai/dsh-llm` |
 | `session` | `@deepseek-ai/dsh-session` |
+| `typert` | `@deepseek-ai/dsh-typert-registry` |
+| `typert-loader` | `@deepseek-ai/dsh-typert-loader` |
+| `typert-gateway` | `@deepseek-ai/dsh-host-api-gateway` |
 | `session-title` | `@deepseek-ai/dsh-session-title` |
 | `session-title-llm` | `@deepseek-ai/dsh-session-title-first-message-llm` |
 | `user-interaction` | `@deepseek-ai/dsh-user-interaction` |
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 6a8f7943c2..18839bf3c2 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -32,6 +32,8 @@ flowchart LR
   pkg_typert_registry["typert-registry"]
   svc_typert["ctx.typert<br/>Runtime type registry"]
   pkg_typert_loader["typert-loader"]
+  pkg_api_gateway["api-gateway"]
+  svc_typertGateway["ctx.typertGateway<br/>TypeRT Host invocation gateway"]
   svc_sessionPersistence["ctx.sessionPersistence<br/>Durable session persistence seam"]
   pkg_session_persistence_jsonl["session-persistence-jsonl"]
   pkg_session_persistence_sqlite["session-persistence-sqlite"]
@@ -171,6 +173,7 @@ flowchart LR
   pkg_acp --> svc_approval
   pkg_agent --> svc_agents
   pkg_agent_loop --> svc_agentLoop
+  pkg_api_gateway --> svc_typertGateway
   pkg_approval --> svc_approval
   pkg_bash --> svc_bash
   pkg_bash_env --> svc_bashEnv
@@ -347,6 +350,7 @@ flowchart LR
   svc_tools --> pkg_tool_subagent
   svc_tools --> pkg_tool_todo
   svc_tools --> pkg_tool_web
+  svc_typert --> pkg_api_gateway
   svc_typert --> pkg_typert_loader
   svc_userInteraction --> pkg_tool_ask_user
   svc_web --> pkg_tool_web
@@ -363,7 +367,8 @@ flowchart LR
 | `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
 | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
-| `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader) | - | Plugins register live zod contributions directly or through dsh-typert-loader; runtime consumers query schemas and reflection metadata at their own edges. |
+| `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), `api-gateway` | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
+| `ctx.typertGateway` | `core` | `api-gateway` | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
 | `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer. |
 | `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index f9fa6e8bb2..5728ac4bed 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -291,7 +291,7 @@ Source: [`packages/examples/cli-demo/src/index.ts:26`](../packages/examples/cli-
 
 ## `@deepseek-ai/dsh-client-connection`
 
-Requires: `httpServer` · `apiProxy`
+Requires: `httpServer`
 
 ```ts config-catalog
 /** Plugin config: the deployment's non-loopback serving authorities. */
@@ -308,7 +308,7 @@ export interface ConnectionConfig {
 }
 ```
 
-Source: [`packages/client/connection/src/index.ts:21`](../packages/client/connection/src/index.ts)
+Source: [`packages/client/connection/src/index.ts:31`](../packages/client/connection/src/index.ts)
 
 ## `@deepseek-ai/dsh-client-hmr`
 
@@ -2548,6 +2548,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts))
 - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts))
 - `@deepseek-ai/dsh-goal-session` — requires `agents` · `goals` · `sessions` ([`packages/goal/goal-session/src/index.ts`](../packages/goal/goal-session/src/index.ts))
+- `@deepseek-ai/dsh-host-api-gateway` — requires `typert` ([`packages/host/api-gateway/src/index.ts`](../packages/host/api-gateway/src/index.ts))
 - `@deepseek-ai/dsh-host-directory-picker-auto` — requires `httpServer` · `loader` ([`packages/host/directory-picker-auto/src/index.ts`](../packages/host/directory-picker-auto/src/index.ts))
 - `@deepseek-ai/dsh-host-directory-picker-native` ([`packages/host/directory-picker-native/src/index.ts`](../packages/host/directory-picker-native/src/index.ts))
 - `@deepseek-ai/dsh-llm` ([`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts))
@@ -2563,6 +2564,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/timeout/timeout-policy/src/index.ts`](../packages/timeout/timeout-policy/src/index.ts))
 - `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/ui/tool-ask-user/src/index.ts`](../packages/ui/tool-ask-user/src/index.ts))
 - `@deepseek-ai/dsh-tool-subagent-control` — requires `tools` · `subagents` ([`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts))
+- `@deepseek-ai/dsh-tool-todo` — requires `tools` ([`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts))
 - `@deepseek-ai/dsh-typert-registry` ([`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts))
 - `@deepseek-ai/dsh-user-interaction` ([`packages/ui/user-interaction/src/index.ts`](../packages/ui/user-interaction/src/index.ts))
 - `@deepseek-ai/dsh-workspace` — requires `storageDomain` · `sessionPersistence` ([`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts))
@@ -2620,4 +2622,6 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))
 - `@deepseek-ai/dsh-telemetry` ([`packages/sdk/telemetry/src/index.ts`](../packages/sdk/telemetry/src/index.ts))
 - `@deepseek-ai/dsh-timeout` ([`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts))
+- `@deepseek-ai/dsh-type-meta` ([`packages/typert/type-meta/src/index.ts`](../packages/typert/type-meta/src/index.ts))
 - `@deepseek-ai/dsh-typert-generator` ([`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts))
+- `@deepseek-ai/dsh-typert-registry` ([`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts))
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 955adbe234..348d334e9f 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -542,7 +542,7 @@ Creation announcement during session publication. A synchronous throw vetoes and
 
 Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/index.ts:73`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:74`](../../packages/core/session/src/index.ts)
 
 ### `session/disposed` — emit
 
@@ -563,7 +563,7 @@ Emitted once when an announced session leaves the store, including publication r
 
 Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/index.ts:83`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:84`](../../packages/core/session/src/index.ts)
 
 ### `session/event` — emit
 
@@ -586,7 +586,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 
 Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/index.ts:95`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
 
 ### `session/flush` — parallel
 
@@ -606,7 +606,7 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
 
 Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/index.ts:104`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:105`](../../packages/core/session/src/index.ts)
 
 ## `settings/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index b2f667681d..0a9af0bae5 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -216,7 +216,7 @@ roots(): Agent[]
 
 Types: [Agent](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
 
 ## `ctx.approval` — `ApprovalService`
 
@@ -1748,7 +1748,7 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId):
 
 Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [PrepareSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/index.ts:800`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:807`](../../packages/core/session/src/index.ts)
 
 ## `ctx.sessionTitle` — `SessionTitleService`
 
@@ -2527,16 +2527,17 @@ Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/i
 
 ## `ctx.typert` — `TypertRegistry`
 
-Registry of generated schemas and package reflection.
+Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
 
 ```ts cordis-catalog
 /**
  * Register one generated contribution atomically for the calling fiber.
- * Duplicate package-face identities or schema keys reject the whole batch.
- * @param contribution - generated schemas and package metadata.
+ * Duplicate package-face identities, schemas, invocation ids, or endpoints
+ * reject the whole batch.
+ * @param contribution - generated schemas, reflection, and Host invocations.
  * @returns the exact effect disposer that removes this contribution.
  */
-register(contribution: TypertContribution): () => void
+register(contribution: TypertContribution): TypeRTDisposer
 
 /**
  * Look up one schema by `<package>#<name>`.
@@ -2584,7 +2585,23 @@ listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
 toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
 ```
 
-Source: [`packages/typert/registry/src/index.ts:67`](../../packages/typert/registry/src/index.ts)
+Source: [`packages/typert/registry/src/service.ts:319`](../../packages/typert/registry/src/service.ts)
+
+## `ctx.typertGateway` — `TypertGatewayService`
+
+Resolve strict generated definitions or conservative SRC markers against current Cordis Services and TypeRT providers.
+
+```ts cordis-catalog
+/**
+ * Invoke one live Remote method through strict generated reflection or SRC markers.
+ * @param request - decoded endpoint and exact named wire arguments.
+ * @returns the validated business result.
+ * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+ */
+async invoke(request: InvokeRemoteRequest): Promise<unknown>
+```
+
+Source: [`packages/host/api-gateway/src/index.ts:94`](../../packages/host/api-gateway/src/index.ts)
 
 ## `ctx.userInteraction` — `UserInteractionService`
 
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 1a7ae5c8d2..fd9ac036a0 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -211,6 +211,7 @@ flowchart TD
   end
   subgraph group_host["packages/host"]
     pkg_frontend_static["frontend-static"]
+    pkg_host_api_gateway["host-api-gateway"]
     pkg_host_apiproxy["host-apiproxy"]
     pkg_host_directory_picker["host-directory-picker"]
     pkg_host_directory_picker_auto["host-directory-picker-auto"]
@@ -272,6 +273,7 @@ flowchart TD
     pkg_session_telemetry_otel["session-telemetry-otel"]
   end
   subgraph group_typert["packages/typert"]
+    pkg_type_meta["type-meta"]
     pkg_typert_generator["typert-generator"]
     pkg_typert_loader["typert-loader"]
     pkg_typert_registry["typert-registry"]
@@ -311,6 +313,7 @@ flowchart TD
   pkg_host_webserver --> pkg_invariants
   pkg_storage --> pkg_invariants
   pkg_subprocess --> pkg_invariants
+  pkg_type_meta --> pkg_invariants
   pkg_typert_generator --> pkg_invariants
   pkg_typert_registry --> pkg_invariants
   pkg_llm --> pkg_brand
@@ -374,6 +377,7 @@ flowchart TD
   pkg_session --> pkg_invariants
   pkg_session --> pkg_llm
   pkg_session --> pkg_scope
+  pkg_session --> pkg_type_meta
   pkg_system_prompt --> pkg_invariants
   pkg_system_prompt --> pkg_llm
   pkg_system_prompt --> pkg_scope
@@ -420,6 +424,9 @@ flowchart TD
   pkg_credentials_local --> pkg_credentials
   pkg_credentials_local --> pkg_invariants
   pkg_credentials_local --> pkg_paths
+  pkg_host_api_gateway --> pkg_client_connection
+  pkg_host_api_gateway --> pkg_invariants
+  pkg_host_api_gateway --> pkg_typert_registry
   pkg_lsp --> pkg_brand
   pkg_lsp --> pkg_invariants
   pkg_lsp --> pkg_llm
@@ -434,6 +441,7 @@ flowchart TD
   pkg_agent --> pkg_scope
   pkg_agent --> pkg_session
   pkg_agent --> pkg_system_prompt
+  pkg_agent --> pkg_type_meta
   pkg_bash --> pkg_invariants
   pkg_bash --> pkg_sandbox
   pkg_bash --> pkg_subprocess
@@ -1154,6 +1162,7 @@ flowchart TD
 | [`host-webserver`](../packages/host/webserver) | `host` | [`invariants`](../packages/support/invariants) |
 | [`storage`](../packages/storage/storage) | `storage` | [`invariants`](../packages/support/invariants) |
 | [`subprocess`](../packages/subprocess/subprocess) | `subprocess` | [`invariants`](../packages/support/invariants) |
+| [`type-meta`](../packages/typert/type-meta) | `typert` | [`invariants`](../packages/support/invariants) |
 | [`typert-generator`](../packages/typert/generator) | `typert` | [`invariants`](../packages/support/invariants) |
 | [`typert-registry`](../packages/typert/registry) | `typert` | [`invariants`](../packages/support/invariants) |
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout) |
@@ -1175,7 +1184,7 @@ flowchart TD
 | [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
-| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
+| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`type-meta`](../packages/typert/type-meta) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`client-ui-models`](../packages/client/ui-models) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
@@ -1186,10 +1195,11 @@ flowchart TD
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`host-api-gateway`](../packages/host/api-gateway) | `host` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`settings-local`](../packages/settings/settings-local) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`settings`](../packages/settings/settings) |
-| [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
+| [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`type-meta`](../packages/typert/type-meta) |
 | [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`subprocess`](../packages/subprocess/subprocess) |
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
diff --git a/package.json b/package.json
index 7bd84db93a..9d0cac6d5e 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,10 @@
   ],
   "scripts": {
     "build": "npm run build:lib && npm run build:web",
-    "build:lib": "tsc -b && tsdown",
+    "build:lib": "npm run build:lib:host && npm run build:lib:client",
+    "build:lib:host": "npm run build:lib:contracts && tsc -b tsconfig.host.json",
+    "build:lib:contracts": "tsc -b packages/typert/generator && tsdown --config tsdown.typert-host.config.ts",
+    "build:lib:client": "tsc -b tsconfig.client.json && tsdown",
     "build:web": "pnpm --filter @deepseek-ai/dsh-frontend run build",
     "clean": "tsx scripts/clean.ts",
     "change-scope": "tsx scripts/change-scope.ts",
diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml
index f0577552cc..0b1cc43a50 100644
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -34,6 +34,15 @@
     - id: session
       name: '@deepseek-ai/dsh-session'
 
+    - id: typert
+      name: '@deepseek-ai/dsh-typert-registry'
+
+    - id: typert-loader
+      name: '@deepseek-ai/dsh-typert-loader'
+
+    - id: typert-gateway
+      name: '@deepseek-ai/dsh-host-api-gateway'
+
     - id: session-title
       name: '@deepseek-ai/dsh-session-title'
       config:
diff --git a/packages/bundle/base/package.json b/packages/bundle/base/package.json
index c6519171ca..2ec17d9c66 100644
--- a/packages/bundle/base/package.json
+++ b/packages/bundle/base/package.json
@@ -49,6 +49,7 @@
     "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-goal-session": "workspace:^",
+    "@deepseek-ai/dsh-host-api-gateway": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
     "@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
@@ -95,6 +96,8 @@
     "@deepseek-ai/dsh-tool-web": "workspace:^",
     "@deepseek-ai/dsh-tool-workflow": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-typert-loader": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",
     "@deepseek-ai/dsh-web": "workspace:^",
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index 67b47b06c6..521e54160e 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -8,7 +8,9 @@ import type { IApiClient } from './api.ts'
 import { ConnectionController, type ConnectionConfig, type ConnectionSinks, type ConnectionState } from './connection.ts'
 import { FixtureApiClient } from './fixture.ts'
 import { WebApiClient } from './web-api-client.ts'
+import { createUnavailableConnectionRpc, createWebConnectionRpc } from './rpc.ts'
 import { isLoopbackHostname } from '../loopback-hostname.ts'
+import type { ClientConnectionRpc } from '../rpc.ts'
 
 // ---- Contract re-exports (browser-safe apiproxy channels + core types) ----
 export type {
@@ -36,6 +38,7 @@ export {
 // Connection loop types are public through ConnectionHandle.start; the
 // controller remains package-internal.
 export type { ConnectionConfig, ConnectionSinks, ConnectionState }
+export type { ClientConnectionRpc } from '../rpc.ts'
 
 
 /** Required services (none — this is the wire root). */
@@ -51,6 +54,8 @@ export interface ConnectionHandle {
   readonly api: IApiClient
   /** Whether the current page authority is loopback; non-browser contexts default to true. */
   readonly isLoopback: boolean
+  /** Generic logical RPC channels over the same Connection transport. */
+  readonly rpc: ClientConnectionRpc
   /**
    * Start the connect/pump/reconnect loop with the consumer's frame sinks.
    * One consumer owns the streams (the runtime object layer); a second call
@@ -70,10 +75,12 @@ export function apply(ctx: Context): void {
   const pageLocation = typeof location === 'undefined' ? undefined : location
   const fixture = pageLocation !== undefined && new URLSearchParams(pageLocation.search).has('fixture')
   const api: IApiClient = fixture ? new FixtureApiClient() : new WebApiClient()
+  const rpc = fixture ? createUnavailableConnectionRpc() : createWebConnectionRpc()
   let started = false
   const handle: ConnectionHandle = {
     api,
     isLoopback: pageLocation === undefined || isLoopbackHostname(pageLocation.hostname),
+    rpc,
     start(sinks, config) {
       if (started) throw new Error('connection: the stream loop is already owned by another consumer')
       started = true
diff --git a/packages/client/connection/src/client/rpc.ts b/packages/client/connection/src/client/rpc.ts
new file mode 100644
index 0000000000..36e16426b2
--- /dev/null
+++ b/packages/client/connection/src/client/rpc.ts
@@ -0,0 +1,75 @@
+/** Browser caller for generic Connection unary RPC channels. */
+
+import {
+  RpcId,
+  serverResponseSchema,
+  type ClientRequest,
+} from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { ClientConnectionRpc } from '../rpc.ts'
+
+const INTERNAL_BASE = 'http://dsh.internal'
+const CHANNEL_PATTERN = /^\/[A-Za-z0-9._~-]+$/
+const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
+
+/**
+ * Create the browser-backed generic RPC caller.
+ * @returns caller that owns request correlation and response-envelope validation.
+ */
+export function createWebConnectionRpc(): ClientConnectionRpc {
+  return {
+    async call(channel, endpoint, payload, signal) {
+      assertTarget(channel, endpoint)
+      const rpcId = RpcId(crypto.randomUUID())
+      const message: ClientRequest = {
+        type: 'client-request',
+        rpcId,
+        method: endpoint,
+        payload,
+      }
+      const response = await globalThis.fetch(
+        new URL(`${channel}/${endpoint}`, resolveBase()),
+        {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(message),
+          ...signal === undefined ? {} : { signal },
+        },
+      )
+      if (!response.ok) {
+        throw new Error(`transport failure for ${channel}/${endpoint}: HTTP ${response.status}`)
+      }
+      const full = serverResponseSchema.parse(await response.json())
+      if (full.rpcId !== rpcId) {
+        throw new Error(`rpcId mismatch for ${endpoint}: sent ${rpcId}, got ${full.rpcId}`)
+      }
+      return full.result
+    },
+  }
+}
+
+/**
+ * Create the fixture-mode caller, where no Host Remote registry exists.
+ * @returns caller that rejects every generic Remote invocation.
+ */
+export function createUnavailableConnectionRpc(): ClientConnectionRpc {
+  return {
+    call(channel, endpoint) {
+      return Promise.reject(new Error(`connection RPC ${channel}/${endpoint} is unavailable in fixture mode`))
+    },
+  }
+}
+
+function resolveBase(): string {
+  const location = (globalThis as { location?: { origin?: string } }).location
+  return location?.origin !== undefined && location.origin !== 'null' ? location.origin : INTERNAL_BASE
+}
+
+function assertTarget(channel: string, endpoint: string): void {
+  const segments = endpoint.split('/')
+  if (!CHANNEL_PATTERN.test(channel)
+    || segments.length === 0
+    || segments.some(segment =>
+      segment === '' || segment === '.' || segment === '..' || !ENDPOINT_SEGMENT_PATTERN.test(segment))) {
+    throw new Error(`connection: invalid RPC target ${JSON.stringify(`${channel}/${endpoint}`)}`)
+  }
+}
diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts
index 2e27a78d70..d8b6ef8846 100644
--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -7,15 +7,25 @@ import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
 import { API_PATH, HOST_EVENTS_PATH, MUX_EVENTS_PATH } from './api-path.ts'
 import { bridge } from './http-bridge.ts'
 import { assertTrustedAuthority, isTrustedApiRequest } from './api-request-trust.ts'
+import { HostConnectionService } from './rpc-host.ts'
 import { rejectWebSocketUpgrade, WebSocketDownlinks } from './websocket-downlink.ts'
 
+export type {
+  ConnectionRpcAuthority,
+  ConnectionRpcHandler,
+  ConnectionRpcHandlerOptions,
+  HostConnectionHandle,
+  HostConnectionRpc,
+} from './rpc.ts'
+export { HostConnectionService } from './rpc-host.ts'
+
 export { API_PATH, HOST_EVENTS_PATH, MUX_EVENTS_PATH } from './api-path.ts'
 
 /** Stable Cordis plugin name. */
 export const name = 'client-connection'
 
-/** Services required before mounting the route. */
-export const inject = ['httpServer', 'apiProxy']
+/** Services required before providing Connection; legacy `/api` attaches when apiProxy is present. */
+export const inject = ['httpServer']
 
 /** Plugin config: the deployment's non-loopback serving authorities. */
 export interface ConnectionConfig {
@@ -83,49 +93,52 @@ export function apply(ctx: Context, config?: ConnectionConfig): void {
   // Config boundary: a malformed entry fails the load loudly here rather than
   // silently authorizing its hostname prefix at request time.
   for (const entry of trustedHosts) assertTrustedAuthority(entry)
-  const apiHandler = toFetchHandler(ctx.apiProxy)
-  const downlinks = new WebSocketDownlinks(ctx.apiProxy)
-  const route: WebRoute = {
-    kind: 'prefix',
-    path: API_PATH,
-    handler: async (req, res) => {
-      const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
-      const method = pathname.startsWith(`${API_PATH}/`)
-        ? pathname.slice(API_PATH.length + 1)
-        : undefined
-      const allowed = method !== undefined && PRIVILEGED_METHODS.has(method)
-        ? isTrustedApiRequest(req, [])
-        : isTrustedApiRequest(req, trustedHosts)
-      if (!allowed) {
-        res.writeHead(403)
-        res.end('forbidden')
-        return
-      }
-      if (req.method === 'GET' && (pathname === MUX_EVENTS_PATH || pathname === HOST_EVENTS_PATH)) {
-        res.writeHead(426, { connection: 'Upgrade', upgrade: 'websocket' })
-        res.end('upgrade required')
-        return
-      }
-      await bridge(req, res, apiHandler)
-    },
-  }
-  ctx.effect(() => ctx.httpServer.register(route), 'client-connection: /api route')
-  const registerDownlink = (
-    path: string,
-    handle: WebUpgradeRoute['handler'],
-  ): void => {
-    ctx.effect(() => ctx.httpServer.registerUpgrade({
-      path,
-      handler: (req, socket, head) => {
-        if (!isTrustedApiRequest(req, trustedHosts)) {
-          rejectWebSocketUpgrade(socket)
+  new HostConnectionService(ctx, trustedHosts)
+  ctx.inject(['apiProxy'], (apiCtx) => {
+    const apiHandler = toFetchHandler(apiCtx.apiProxy)
+    const downlinks = new WebSocketDownlinks(apiCtx.apiProxy)
+    const route: WebRoute = {
+      kind: 'prefix',
+      path: API_PATH,
+      handler: async (req, res) => {
+        const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
+        const method = pathname.startsWith(`${API_PATH}/`)
+          ? pathname.slice(API_PATH.length + 1)
+          : undefined
+        const allowed = method !== undefined && PRIVILEGED_METHODS.has(method)
+          ? isTrustedApiRequest(req, [])
+          : isTrustedApiRequest(req, trustedHosts)
+        if (!allowed) {
+          res.writeHead(403)
+          res.end('forbidden')
           return
         }
-        return handle(req, socket, head)
+        if (req.method === 'GET' && (pathname === MUX_EVENTS_PATH || pathname === HOST_EVENTS_PATH)) {
+          res.writeHead(426, { connection: 'Upgrade', upgrade: 'websocket' })
+          res.end('upgrade required')
+          return
+        }
+        await bridge(req, res, apiHandler)
       },
-    }), `client-connection: ${path} WebSocket`)
-  }
-  ctx.effect(() => () => downlinks.close(), 'client-connection: WebSocket downlinks')
-  registerDownlink(MUX_EVENTS_PATH, (req, socket, head) => { downlinks.handleMux(req, socket, head) })
-  registerDownlink(HOST_EVENTS_PATH, (req, socket, head) => { downlinks.handleHost(req, socket, head) })
+    }
+    apiCtx.effect(() => apiCtx.httpServer.register(route), 'client-connection: /api route')
+    const registerDownlink = (
+      path: string,
+      handle: WebUpgradeRoute['handler'],
+    ): void => {
+      apiCtx.effect(() => apiCtx.httpServer.registerUpgrade({
+        path,
+        handler: (req, socket, head) => {
+          if (!isTrustedApiRequest(req, trustedHosts)) {
+            rejectWebSocketUpgrade(socket)
+            return
+          }
+          return handle(req, socket, head)
+        },
+      }), `client-connection: ${path} WebSocket`)
+    }
+    apiCtx.effect(() => () => downlinks.close(), 'client-connection: WebSocket downlinks')
+    registerDownlink(MUX_EVENTS_PATH, (req, socket, head) => { downlinks.handleMux(req, socket, head) })
+    registerDownlink(HOST_EVENTS_PATH, (req, socket, head) => { downlinks.handleHost(req, socket, head) })
+  })
 }
diff --git a/packages/client/connection/src/rpc-host.ts b/packages/client/connection/src/rpc-host.ts
new file mode 100644
index 0000000000..be9eedca8f
--- /dev/null
+++ b/packages/client/connection/src/rpc-host.ts
@@ -0,0 +1,150 @@
+/** Host registry and HTTP adapter for generic Connection RPC channels. */
+
+import { Context, Service } from 'cordis'
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import {
+  clientRequestSchema,
+  RpcId,
+  type ClientRequest,
+  type RpcError,
+  type RpcId as RpcIdType,
+  type ServerResponse as RpcServerResponse,
+} from '@deepseek-ai/dsh-host-apiproxy/api'
+import { bridge } from './http-bridge.ts'
+import { isTrustedApiRequest } from './api-request-trust.ts'
+import type {
+  ConnectionRpcHandler,
+  ConnectionRpcHandlerOptions,
+  HostConnectionHandle,
+  HostConnectionRpc,
+} from './rpc.ts'
+
+const INVALID_REQUEST_RPC_ID = RpcId('invalid-request')
+const CHANNEL_PATTERN = /^\/[A-Za-z0-9._~-]+$/
+const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
+
+/** Host Connection service whose channel registrations belong to the caller fiber. */
+export class HostConnectionService extends Service implements HostConnectionHandle {
+  /**
+   * Provide the Host half over the active HTTP server.
+   * @param ctx - owning Connection plugin context.
+   * @param trustedHosts - deployment authorities accepted by trusted-host channels.
+   */
+  constructor(ctx: Context, private readonly trustedHosts: readonly string[]) {
+    super(ctx, 'connection')
+  }
+
+  /** Generic channel registry scoped to the Context reading this service. */
+  get rpc(): HostConnectionRpc {
+    const owner = this.ctx
+    return {
+      handle: (channel, handler, options) => this.register(owner, channel, handler, options),
+    }
+  }
+
+  private register(
+    owner: Context,
+    channel: string,
+    handler: ConnectionRpcHandler,
+    options: ConnectionRpcHandlerOptions,
+  ): () => Promise<void> {
+    assertChannel(channel)
+    const trustedHosts = options.authority === 'loopback' ? [] : this.trustedHosts
+    const fetchHandler = rpcFetchHandler(channel, handler)
+    const route: WebRoute = {
+      kind: 'prefix',
+      path: channel,
+      handler: async (req, res) => {
+        if (!isTrustedApiRequest(req, trustedHosts)) {
+          res.writeHead(403)
+          res.end('forbidden')
+          return
+        }
+        await bridge(req, res, fetchHandler)
+      },
+    }
+    return owner.effect(
+      () => owner.httpServer.register(route),
+      `client-connection: ${channel} rpc channel`,
+    )
+  }
+}
+
+function rpcFetchHandler(
+  channel: string,
+  handler: ConnectionRpcHandler,
+): { fetch: typeof fetch } {
+  return {
+    async fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+      const request = input instanceof Request ? input : new Request(input, init)
+      const endpoint = endpointFromPath(channel, new URL(request.url).pathname)
+      if (request.method !== 'POST' || endpoint === undefined) {
+        return new Response('not found', { status: 404 })
+      }
+
+      const mediaType = request.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase()
+      if (mediaType !== 'application/json') {
+        return new Response('content type must be application/json', { status: 415 })
+      }
+
+      let body: unknown
+      try {
+        body = await request.json()
+      } catch {
+        return new Response('body is not JSON', { status: 400 })
+      }
+
+      const envelope = clientRequestSchema.safeParse(body)
+      if (!envelope.success) {
+        const rawId = (body as { rpcId?: unknown } | null)?.rpcId
+        const rpcId = typeof rawId === 'string' ? RpcId(rawId) : INVALID_REQUEST_RPC_ID
+        return errorResponse(rpcId, {
+          code: 'bad-request',
+          message: 'invalid client-request message',
+          details: { issues: envelope.error.issues },
+        })
+      }
+      const message: ClientRequest = envelope.data
+      if (message.method !== endpoint) {
+        return errorResponse(message.rpcId, {
+          code: 'bad-request',
+          message: `method ${JSON.stringify(message.method)} does not match endpoint ${JSON.stringify(endpoint)}`,
+          details: { issues: [] },
+        })
+      }
+
+      try {
+        const result = await handler(endpoint, message.payload, request.signal)
+        return fullResponse(message.rpcId, result)
+      } catch (error) {
+        return new Response(`handler failure: ${String(error)}`, { status: 500 })
+      }
+    },
+  }
+}
+
+function endpointFromPath(channel: string, pathname: string): string | undefined {
+  if (!pathname.startsWith(`${channel}/`)) return undefined
+  const endpoint = pathname.slice(channel.length + 1)
+  const segments = endpoint.split('/')
+  if (segments.length === 0 || segments.some(segment =>
+    segment === '' || segment === '.' || segment === '..' || !ENDPOINT_SEGMENT_PATTERN.test(segment))) {
+    return undefined
+  }
+  return endpoint
+}
+
+function errorResponse(rpcId: RpcIdType, error: RpcError): Response {
+  return fullResponse(rpcId, { ok: false, error })
+}
+
+function fullResponse(rpcId: RpcIdType, result: RpcServerResponse['result']): Response {
+  const body: RpcServerResponse = { type: 'server-response', rpcId, result }
+  return Response.json(body)
+}
+
+function assertChannel(channel: string): void {
+  if (!CHANNEL_PATTERN.test(channel) || channel === '/api') {
+    throw new Error(`connection: invalid or reserved RPC channel ${JSON.stringify(channel)}`)
+  }
+}
diff --git a/packages/client/connection/src/rpc.ts b/packages/client/connection/src/rpc.ts
new file mode 100644
index 0000000000..ab68783724
--- /dev/null
+++ b/packages/client/connection/src/rpc.ts
@@ -0,0 +1,59 @@
+/** Generic unary RPC contracts shared by the Host and Client Connection halves. */
+
+import type { RpcResult } from '@deepseek-ai/dsh-host-apiproxy/api'
+
+/** Trust fence applied before a Host RPC channel reaches its handler. */
+export type ConnectionRpcAuthority = 'trusted-host' | 'loopback'
+
+/** Registration policy for one logical RPC channel. */
+export interface ConnectionRpcHandlerOptions {
+  /** Browser authority accepted by every endpoint in this channel. */
+  readonly authority: ConnectionRpcAuthority
+}
+
+/** Handler invoked after Connection has decoded the transport envelope. */
+export type ConnectionRpcHandler = (
+  endpoint: string,
+  payload: unknown,
+  signal: AbortSignal,
+) => Promise<RpcResult<unknown>>
+
+/** Host registry for logical RPC channels carried by the current transport. */
+export interface HostConnectionRpc {
+  /**
+   * Register one absolute channel prefix and its trust policy.
+   * @param channel - absolute logical channel such as `/api2`.
+   * @param handler - decoded endpoint handler returning the existing RPC result shape.
+   * @param options - channel trust policy.
+   * @returns asynchronous disposer removing the channel and its physical route.
+   */
+  handle(
+    channel: string,
+    handler: ConnectionRpcHandler,
+    options: ConnectionRpcHandlerOptions,
+  ): () => Promise<void>
+}
+
+/** Host `ctx.connection` shape consumed by transport-independent adapters. */
+export interface HostConnectionHandle {
+  /** Generic RPC channel registry. */
+  readonly rpc: HostConnectionRpc
+}
+
+/** Client caller for logical RPC channels carried by the current transport. */
+export interface ClientConnectionRpc {
+  /**
+   * Call one endpoint through an already registered logical channel.
+   * @param channel - absolute logical channel such as `/api2`.
+   * @param endpoint - channel-relative endpoint such as `goals/create`.
+   * @param payload - channel-owned request payload.
+   * @param signal - optional caller cancellation.
+   * @returns the existing RPC success/error result; correlation stays inside Connection.
+   */
+  call(
+    channel: string,
+    endpoint: string,
+    payload: unknown,
+    signal?: AbortSignal,
+  ): Promise<RpcResult<unknown>>
+}
diff --git a/packages/client/connection/tests/client-apply.spec.ts b/packages/client/connection/tests/client-apply.spec.ts
index 524983fb4f..d93844a2b8 100644
--- a/packages/client/connection/tests/client-apply.spec.ts
+++ b/packages/client/connection/tests/client-apply.spec.ts
@@ -203,4 +203,41 @@ describe('connection client apply', () => {
     expect(sockets).toHaveLength(1)
     expect(sockets[0]?.readyState).toBe(FakeWebSocket.CLOSED)
   })
+
+  it('carries generic RPC calls over the isolated channel with rpcId echo validation', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost', search: '' }
+    const handle = await mount()
+    const original = globalThis.fetch
+    const seen: { url: string; body: unknown }[] = []
+    globalThis.fetch = async (input: URL | RequestInfo, init?: RequestInit) => {
+      const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+      if (typeof init?.body !== 'string') throw new TypeError('expected a JSON string request body')
+      const body = JSON.parse(init.body) as { rpcId: string }
+      seen.push({ url, body })
+      return Response.json({
+        type: 'server-response',
+        rpcId: body.rpcId,
+        result: { ok: true, value: { ref: 'goal-1' } },
+      })
+    }
+    try {
+      await expect(handle.rpc.call('/api2', 'goals/create', { args: { agentId: 'agent-1' } }))
+        .resolves.toEqual({ ok: true, value: { ref: 'goal-1' } })
+    } finally {
+      globalThis.fetch = original
+    }
+    expect(seen).toHaveLength(1)
+    expect(seen[0]?.url).toBe('http://dsh.internal/api2/goals/create')
+    expect(seen[0]?.body).toMatchObject({
+      type: 'client-request',
+      method: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    })
+  })
+
+  it('keeps generic Remote calls unavailable in the client-only fixture', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost', search: '?fixture' }
+    const handle = await mount()
+    await expect(handle.rpc.call('/api2', 'goals/create', {})).rejects.toThrow(/unavailable in fixture mode/)
+  })
 })
diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts
index 3015881d2f..af85d4e510 100644
--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -7,8 +7,9 @@ import { describe, expect, it } from 'vitest'
 import type { AddressInfo } from 'node:net'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { RpcId, type ClientRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { HttpServerService, WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver'
-import { API_PATH, apply, HOST_EVENTS_PATH, inject, MUX_EVENTS_PATH } from '../src/index.ts'
+import { API_PATH, apply, HOST_EVENTS_PATH, inject, MUX_EVENTS_PATH, type HostConnectionHandle } from '../src/index.ts'
 
 /** Structural httpServer fake recording both route registries. */
 function fakeHttpServer(
@@ -17,6 +18,9 @@ function fakeHttpServer(
 ): Pick<HttpServerService, 'register' | 'registerUpgrade' | 'tapIndex' | 'port'> {
   return {
     register(route) {
+      if (routes.some(candidate => candidate.kind === route.kind && candidate.path === route.path)) {
+        throw new Error(`duplicate route ${route.path}`)
+      }
       routes.push(route)
       return () => { routes.splice(routes.indexOf(route), 1) }
     },
@@ -36,15 +40,25 @@ function fakeRequest(headers: Record<string, string>, url = `${API_PATH}/session
   return request
 }
 
+/** JSON POST carrying a complete client-request envelope. */
+function fakePost(headers: Record<string, string>, url: string, body: unknown): IncomingMessage {
+  const request = Readable.from([Buffer.from(JSON.stringify(body))]) as unknown as IncomingMessage
+  Object.assign(request, { url, method: 'POST', headers: { 'content-type': 'application/json', ...headers } })
+  return request
+}
+
 /** Response recorder compatible with both the fence's short-circuit and the bridge. */
 function fakeResponse(): { response: ServerResponse; state: { status?: number; body?: unknown } } {
   const state: { status?: number; body?: unknown } = {}
+  const chunks: Buffer[] = []
   const response = Object.assign(new EventEmitter(), {
     writableEnded: false,
     writeHead(value: number) { state.status = value; return this },
-    write() { return true },
+    write(value: string | Uint8Array) { chunks.push(Buffer.from(value)); return true },
     end(this: { writableEnded: boolean }, value?: unknown) {
-      if (value !== undefined) state.body = value
+      if (typeof value === 'string' || value instanceof Uint8Array) chunks.push(Buffer.from(value))
+      else if (value !== undefined) throw new TypeError('fake response only accepts string or Uint8Array bodies')
+      if (chunks.length > 0) state.body = Buffer.concat(chunks).toString()
       this.writableEnded = true
       return this
     },
@@ -173,6 +187,78 @@ describe('connection node half', () => {
     expect(declared.state.status).toBe(404)
     await dispose()
   })
+
+  it('provides a disposable generic RPC channel without requiring apiProxy', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    ctx.provide('httpServer', fakeHttpServer(routes, []) as HttpServerService)
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(routes).toHaveLength(0)
+
+    const connection = ctx.get('connection') as HostConnectionHandle
+    const calls: unknown[] = []
+    const remove = connection.rpc.handle('/api2', async (endpoint, payload) => {
+      calls.push({ endpoint, payload })
+      return { ok: true, value: { accepted: true } }
+    }, { authority: 'trusted-host' })
+    const route = routes.find(candidate => candidate.path === '/api2')
+    expect(route).toBeDefined()
+
+    const request: ClientRequest = {
+      type: 'client-request',
+      rpcId: RpcId('rpc-api2'),
+      method: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }
+    const result = fakeResponse()
+    await route!.handler(fakePost({ host: '127.0.0.1:3080' }, '/api2/goals/create', request), result.response)
+    expect(result.state.status).toBe(200)
+    expect(JSON.parse(String(result.state.body))).toEqual({
+      type: 'server-response',
+      rpcId: 'rpc-api2',
+      result: { ok: true, value: { accepted: true } },
+    })
+    expect(calls).toEqual([{
+      endpoint: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }])
+
+    expect(() => connection.rpc.handle('/api2', async () => ({ ok: true, value: null }), {
+      authority: 'trusted-host',
+    })).toThrow(/duplicate route/)
+    await remove()
+    expect(routes).toHaveLength(0)
+    await fiber.dispose()
+  })
+
+  it('applies the configured trust fence and JSON envelope checks to generic channels', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    ctx.provide('httpServer', fakeHttpServer(routes, []) as HttpServerService)
+    const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.example'] })
+    await fiber.await()
+    const connection = ctx.get('connection') as HostConnectionHandle
+    const remove = connection.rpc.handle('/api2', async () => ({ ok: true, value: null }), {
+      authority: 'trusted-host',
+    })
+    const route = routes[0]!
+
+    const denied = fakeResponse()
+    await route.handler(fakePost({ host: 'other.example' }, '/api2/goals/create', {}), denied.response)
+    expect(denied.state).toMatchObject({ status: 403, body: 'forbidden' })
+
+    const badEnvelope = fakeResponse()
+    await route.handler(fakePost({ host: 'harness.example' }, '/api2/goals/create', {
+      type: 'client-request', rpcId: 'rpc-bad', method: 'other', payload: {},
+    }), badEnvelope.response)
+    expect(JSON.parse(String(badEnvelope.state.body))).toMatchObject({
+      rpcId: 'rpc-bad',
+      result: { ok: false, error: { code: 'bad-request' } },
+    })
+    await remove()
+    await fiber.dispose()
+  })
 })
 
 describe('connection node half over a real HTTP server', () => {
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index e5691a0619..14e51fae8e 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -27,6 +27,9 @@ async function mount(): Promise<Bench> {
   const handle: ConnectionHandle = {
     api,
     isLoopback: true,
+    rpc: {
+      call: () => Promise.reject(new Error('unexpected generic RPC call')),
+    },
     start: (sinks) => {
       bench.sinks = sinks
       return { stop: () => { bench.stopped += 1 } }
diff --git a/packages/client/runtime/tests/wire-events.spec.ts b/packages/client/runtime/tests/wire-events.spec.ts
index 21e7f1fc06..f081eb54c1 100644
--- a/packages/client/runtime/tests/wire-events.spec.ts
+++ b/packages/client/runtime/tests/wire-events.spec.ts
@@ -21,6 +21,9 @@ async function mount(): Promise<Bench> {
   const handle: ConnectionHandle = {
     api,
     isLoopback: true,
+    rpc: {
+      call: () => Promise.reject(new Error('unexpected generic RPC call')),
+    },
     start: (sinks) => {
       bench.sinks = sinks
       return { stop: () => {} }
diff --git a/packages/client/tsdown.client.ts b/packages/client/tsdown.client.ts
index 1e45991080..74facbd69b 100644
--- a/packages/client/tsdown.client.ts
+++ b/packages/client/tsdown.client.ts
@@ -31,6 +31,9 @@ const CSS_VIRTUAL_SUFFIX = '.mjs'
  */
 export const INLINE_SAFE = /^@deepseek-ai\/dsh-(host-apiproxy|session|llm|tools|brand)(\/|$)/
 
+/** Generated descriptor/codec contribution with no shared runtime identity. */
+const GENERATED_REMOTE = /^@deepseek-ai\/dsh-[a-z0-9]+(?:-[a-z0-9]+)*\/remote$/
+
 /**
  * Documented TEMPORARY exemption, not a platform module (hence not in
  * platform.ts): the snapshot-store engine (createSnapshotStore/defineStore/
@@ -126,9 +129,9 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
       resolveId(source: string) {
         if (!source.startsWith('@deepseek-ai/')) return null
         if (CLIENT_EXTERNALS.includes(source)) return null // platform module: external wins
-        if (INLINE_SAFE.test(source)) return null // wire/type layer: inline is the point
+        if (INLINE_SAFE.test(source) || GENERATED_REMOTE.test(source)) return null // wire contribution: inline is the point
         throw new Error(
-          `client bundle purity: "${source}" is not a platform module (CLIENT_EXTERNALS) and not an inline-safe wire layer — `
+          `client bundle purity: "${source}" is not a platform module (CLIENT_EXTERNALS), an inline-safe wire layer, or a generated /remote contribution — `
           + 'cross-plugin value imports are forbidden; collaborate through cordis services (type-only imports are erased and never reach this gate)',
         )
       },
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 2bf1c1b2d9..b8da6049e8 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -1118,11 +1118,11 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'typert',
-    summary: 'Registry of generated schemas and package reflection.',
+    summary: 'Registry of generated schemas, package reflection, invocations, and Remote dependency providers.',
     methods: [
       {
-        signature: 'register(contribution: TypertContribution): () => void',
-        jsDoc: '/**\n * Register one generated contribution atomically for the calling fiber.\n * Duplicate package-face identities or schema keys reject the whole batch.\n * @param contribution - generated schemas and package metadata.\n * @returns the exact effect disposer that removes this contribution.\n */',
+        signature: 'register(contribution: TypertContribution): TypeRTDisposer',
+        jsDoc: '/**\n * Register one generated contribution atomically for the calling fiber.\n * Duplicate package-face identities, schemas, invocation ids, or endpoints\n * reject the whole batch.\n * @param contribution - generated schemas, reflection, and Host invocations.\n * @returns the exact effect disposer that removes this contribution.\n */',
       },
       {
         signature: 'get(key: string): TypertSchemaRecord | undefined',
@@ -1150,6 +1150,16 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'typertGateway',
+    summary: 'Resolve strict generated definitions or conservative SRC markers against current Cordis Services and TypeRT providers.',
+    methods: [
+      {
+        signature: 'async invoke(request: InvokeRemoteRequest): Promise<unknown>',
+        jsDoc: '/**\n * Invoke one live Remote method through strict generated reflection or SRC markers.\n * @param request - decoded endpoint and exact named wire arguments.\n * @returns the validated business result.\n * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.\n */',
+      },
+    ],
+  },
   {
     key: 'userInteraction',
     summary: '`ctx.userInteraction`: one active UI provider plus an `ask()` surface.',
@@ -2057,6 +2067,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'InvariantInstaller',
     declaration: 'export interface InvariantInstaller {\n    (ctx: Context, fail: InvariantFailure): void | Promise<void>;\n    readonly inject?: Inject;\n}',
   },
+  {
+    name: 'InvocationDescriptor',
+    declaration: 'export interface InvocationDescriptor {\n    readonly id: string;\n    readonly service: string;\n    readonly namespace: string;\n    readonly method: string;\n    readonly implementation?: string;\n    readonly invocation: {\n        readonly kind: \'direct\';\n    } | {\n        readonly kind: \'context\';\n        readonly context: string;\n        readonly wire: string;\n        readonly codec: TypeRTCodec;\n    };\n    readonly scope?: {\n        readonly context: string;\n        readonly wire: string;\n    };\n    readonly parameters: readonly InvocationParameterDescriptor[];\n    readonly result: TypeRTCodec;\n    readonly sourceLocation?: InvocationSourceLocation;\n}',
+  },
+  {
+    name: 'InvocationParameterDescriptor',
+    declaration: 'export interface InvocationParameterDescriptor {\n    readonly name: string;\n    readonly wire: string;\n    readonly source: \'json\' | \'lookup\';\n    readonly lookup?: string;\n    readonly codec: TypeRTCodec;\n}',
+  },
+  {
+    name: 'InvocationSourceLocation',
+    declaration: 'export interface InvocationSourceLocation {\n    readonly file: string;\n    readonly line: number;\n    readonly column: number;\n}',
+  },
+  {
+    name: 'InvokeRemoteRequest',
+    declaration: 'export interface InvokeRemoteRequest {\n    readonly namespace: string;\n    readonly method: string;\n    readonly args: Readonly<Record<string, unknown>>;\n}',
+  },
   {
     name: 'JsonSchemaNode',
     declaration: 'export interface JsonSchemaNode {\n    type?: JsonSchemaType;\n    oneOf?: JsonSchemaNode[];\n    properties?: Record<string, JsonSchemaNode>;\n    required?: string[];\n    additionalProperties?: boolean;\n    items?: JsonSchemaNode;\n    enum?: JsonSchemaScalar[];\n    const?: JsonSchemaScalar;\n    description?: string;\n    title?: string;\n    default?: JsonValue;\n    examples?: JsonValue;\n}',
@@ -3037,9 +3063,17 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'TurnEndReasonMap',
     declaration: 'export interface TurnEndReasonMap {\n    completed: {\n        kind: \'completed\';\n    };\n    aborted: {\n        kind: \'aborted\';\n        reason: TurnEndCancelCause;\n    };\n    blocked: {\n        kind: \'blocked\';\n    };\n    error: {\n        kind: \'error\';\n        error: LlmFailure;\n    };\n    \'max-tokens\': {\n        kind: \'max-tokens\';\n    };\n    interrupted: {\n        kind: \'interrupted\';\n    };\n}',
   },
+  {
+    name: 'TypeRTCodec',
+    declaration: 'export type TypeRTCodec = {\n    readonly mode: \'strict\';\n    readonly typeSymbol: string;\n    readonly schema: TypeRTSchema;\n} | {\n    readonly mode: \'src-json\';\n};',
+  },
   {
     name: 'TypertContribution',
-    declaration: 'export interface TypertContribution {\n    readonly package: string;\n    readonly face: TypertFace;\n    readonly schemas: readonly TypertSchema[];\n    readonly model: TypertPackageModel;\n}',
+    declaration: 'export interface TypertContribution {\n    readonly package: string;\n    readonly face: TypertFace;\n    readonly schemas: readonly TypertSchema[];\n    readonly model: TypertPackageModel;\n    readonly invocations?: readonly InvocationDescriptor[];\n}',
+  },
+  {
+    name: 'TypeRTDisposer',
+    declaration: 'export type TypeRTDisposer = () => Promise<void>;',
   },
   {
     name: 'TypertDocTag',
@@ -3077,6 +3111,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'TypertSchema',
     declaration: 'export interface TypertSchema {\n    readonly name: string;\n    readonly schema: z.ZodType;\n}',
   },
+  {
+    name: 'TypeRTSchema',
+    declaration: 'export interface TypeRTSchema<Output = unknown> {\n    parse(value: unknown): Output;\n}',
+  },
   {
     name: 'TypertSchemaFilter',
     declaration: 'export interface TypertSchemaFilter {\n    readonly package?: string;\n    readonly face?: TypertFace;\n}',
diff --git a/packages/core/agent/package.json b/packages/core/agent/package.json
index 2e204bc7f0..9f64d33e75 100644
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -15,12 +15,17 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
@@ -30,6 +35,7 @@
     "@deepseek-ai/dsh-scope": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-type-meta": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
@@ -38,6 +44,8 @@
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index 55cb94d8f9..8f316f75dc 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -12,6 +12,7 @@ import { isPromise } from 'node:util/types'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type { TypeRTContext, TypeRTLookup } from '@deepseek-ai/dsh-type-meta'
 import type { Agent, AgentOptions } from './types.ts'
 
 export * from './types.ts'
@@ -20,6 +21,16 @@ export * from './llm-target.ts'
 export { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from './dispatch.ts'
 export type { AgentEventDispatch, AgentSubjectEvent } from './dispatch.ts'
 
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTLookupMap {
+    agent: TypeRTLookup<Agent, SessionId>
+  }
+
+  interface TypeRTContextMap {
+    agent: TypeRTContext<SessionId>
+  }
+}
+
 declare module 'cordis' {
   interface Context {
     agents: AgentRegistry
@@ -251,6 +262,20 @@ export class AgentRegistry extends Service {
 
   constructor(ctx: Context) {
     super(ctx, 'agents')
+    ctx.inject(['typert'], (typeCtx) => {
+      typeCtx.typert.lookups.register('agent', {
+        parameter: 'agent',
+        wire: 'agentId',
+        hostTypeSymbol: '@deepseek-ai/dsh-agent#Agent',
+        wireTypeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+        resolve: sessionId => this.get(sessionId),
+      })
+      typeCtx.typert.contexts.registerHost('agent', {
+        wire: 'agentId',
+        wireTypeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+        resolve: sessionId => this.get(sessionId)?.ctx,
+      })
+    })
     // The `ctx.agent` DX accessor: default `undefined` on every context, so a
     // plain plugin context reads cleanly instead of hitting the Cordis
     // unknown-property throw. Each Agent.ctx shadows it with an own property
diff --git a/packages/core/agent/tests/agent.spec.ts b/packages/core/agent/tests/agent.spec.ts
index e80d575aeb..643a3a49a6 100644
--- a/packages/core/agent/tests/agent.spec.ts
+++ b/packages/core/agent/tests/agent.spec.ts
@@ -6,6 +6,7 @@ import AgentRegistry, {
   agentEvents,
   Inbox,
 } from '@deepseek-ai/dsh-agent'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 
 import type {
   Agent,
@@ -142,6 +143,31 @@ describe('Inbox', () => {
 })
 
 describe('AgentRegistry', () => {
+  it('contributes Agent lookup and scoped Context providers while TypeRT is live', async () => {
+    const ctx = new Context()
+    const agentFiber = ctx.plugin(AgentRegistry)
+    await agentFiber
+    await ctx.plugin(TypertRegistry)
+    const agent = stubAgent('remote-agent')
+    const disposeAgent = ctx.agents.register(agent)
+
+    const lookup = ctx.typert.lookups.get('agent')
+    expect(lookup).toMatchObject({
+      parameter: 'agent',
+      wire: 'agentId',
+      hostTypeSymbol: '@deepseek-ai/dsh-agent#Agent',
+      wireTypeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+    })
+    expect(lookup?.resolve(agent.id)).toBe(agent)
+    expect(ctx.typert.contexts.getHost('agent')?.resolve(agent.id)).toBe(agent.ctx)
+
+    disposeAgent()
+    expect(lookup?.resolve(agent.id)).toBeUndefined()
+    await agentFiber.dispose()
+    expect(ctx.typert.lookups.get('agent')).toBeUndefined()
+    expect(ctx.typert.contexts.getHost('agent')).toBeUndefined()
+  })
+
   it('registers exact entries, emits lifecycle events, and unregisters on owner disposal', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
diff --git a/packages/core/agent/tsconfig.json b/packages/core/agent/tsconfig.json
index 1561175ed9..31d38b6017 100644
--- a/packages/core/agent/tsconfig.json
+++ b/packages/core/agent/tsconfig.json
@@ -28,6 +28,9 @@
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../typert/type-meta"
     }
   ]
 }
diff --git a/packages/core/session/package.json b/packages/core/session/package.json
index 83be69528e..04aa221573 100644
--- a/packages/core/session/package.json
+++ b/packages/core/session/package.json
@@ -38,6 +38,7 @@
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-scope": "^0.0.1",
+    "@deepseek-ai/dsh-type-meta": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
@@ -45,6 +46,8 @@
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index d250998624..3f73242958 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -13,6 +13,7 @@ import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { Message } from '@deepseek-ai/dsh-llm'
 import { SESSION_FORMAT_VERSION, SessionId } from './types.ts'
+import type { TypeRTLookup } from '@deepseek-ai/dsh-type-meta'
 import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType } from './types.ts'
 import { snapshotJsonValue } from './json.ts'
 import { deriveEventMessage, SurfaceManager } from './surface.ts'
@@ -105,6 +106,12 @@ declare module 'cordis' {
   }
 }
 
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTLookupMap {
+    session: TypeRTLookup<Session, SessionId>
+  }
+}
+
 /** Validate and freeze one detached creation header in place. */
 function validateSessionHeader(id: SessionId, input: unknown): SessionHeader {
   if (input === null || typeof input !== 'object' || Array.isArray(input)) {
@@ -803,6 +810,15 @@ export class SessionStore extends Service {
 
   constructor(ctx: Context) {
     super(ctx, 'sessions')
+    ctx.inject(['typert'], (typeCtx) => {
+      typeCtx.typert.lookups.register('session', {
+        parameter: 'session',
+        wire: 'sessionId',
+        hostTypeSymbol: '@deepseek-ai/dsh-session#Session',
+        wireTypeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+        resolve: sessionId => this.get(sessionId),
+      })
+    })
   }
 
   /**
diff --git a/packages/core/session/tests/typert.spec.ts b/packages/core/session/tests/typert.spec.ts
new file mode 100644
index 0000000000..e1e2b32d68
--- /dev/null
+++ b/packages/core/session/tests/typert.spec.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
+
+describe('Session TypeRT provider', () => {
+  it('contributes live Session lookup in either service load order', async () => {
+    const ctx = new Context()
+    const sessionFiber = ctx.plugin(SessionStore)
+    await sessionFiber
+    await ctx.plugin(TypertRegistry)
+    const session = ctx.sessions.create(SessionId('remote-session'))
+
+    const lookup = ctx.typert.lookups.get('session')
+    expect(lookup).toMatchObject({
+      parameter: 'session',
+      wire: 'sessionId',
+      hostTypeSymbol: '@deepseek-ai/dsh-session#Session',
+      wireTypeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+    })
+    expect(lookup?.resolve(session.id)).toBe(session)
+
+    await sessionFiber.dispose()
+    expect(ctx.typert.lookups.get('session')).toBeUndefined()
+  })
+})
diff --git a/packages/core/session/tsconfig.json b/packages/core/session/tsconfig.json
index 253a1c8793..076ff73d9f 100644
--- a/packages/core/session/tsconfig.json
+++ b/packages/core/session/tsconfig.json
@@ -25,6 +25,9 @@
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../typert/type-meta"
     }
   ]
 }
diff --git a/packages/host/api-gateway/README.i18n.yaml b/packages/host/api-gateway/README.i18n.yaml
new file mode 100644
index 0000000000..2abe47e0d3
--- /dev/null
+++ b/packages/host/api-gateway/README.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 packages/host/api-gateway/README.md
+README.md: 3ef926ace2ee4d6008b1d6c18b1e070fa39bc176
+README.zh.md: 77b8b8a87d5f511000aac5cf9f75ebca5fcdfbca
diff --git a/packages/host/api-gateway/README.md b/packages/host/api-gateway/README.md
new file mode 100644
index 0000000000..3ef926ace2
--- /dev/null
+++ b/packages/host/api-gateway/README.md
@@ -0,0 +1,36 @@
+# @deepseek-ai/dsh-host-api-gateway
+
+English | [中文](README.zh.md)
+
+Two-sided Remote control for Host and Client Cordis environments. The Host entry provides `ctx.typertGateway`, while `@deepseek-ai/dsh-host-api-gateway/client` provides `ctx.api`; both consume the same generated `InvocationDescriptor` contract and leave transport, request correlation, trust, and response envelopes to Connection.
+
+## Host service: `TypertGatewayService` (ctx key: `typertGateway`)
+
+`ctx.typertGateway.invoke()` resolves the current descriptor and Cordis Service for each call, validates exact named arguments, resolves registered object or Context identities, invokes the public business method, and validates its result. Business Services declare participation with `bindTypeRTGateway()` and `@Remote` or `@RemoteContext` from [`dsh-type-meta`](../../typert/type-meta/README.md).
+
+Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use registered `ctx.typert.lookups` providers, while `@RemoteContext` resolves its receiver through a registered Host Context provider. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation.
+
+The Host entry registers the trusted-host `/api2` unary RPC channel when Connection is available. Direct `invoke()` calls preserve business errors; `TypertGatewayError` distinguishes failures owned by dispatch, binding, providers, lookup, Context, arguments, and codecs.
+
+## Client service: `ClientApi` (ctx key: `api`)
+
+`ctx.api.mount()` validates and registers a generated Host-for-Client contribution, then installs concrete direct and scoped methods for the calling Cordis fiber. Duplicate endpoints, namespace collisions, and descriptors without strict generated codecs fail before methods become callable.
+
+Each call validates positional inputs, constructs the descriptor's exact named `args`, and sends it through `ctx.connection.rpc.call('/api2', endpoint, ...)`. The returned value is validated before reaching application code. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls, and makes retained method handles reject.
+
+Generated declaration merges provide the TypeScript API. The Client entry contains no Host Service or Host Cordis interface merge, and method lookup and invocation use ordinary objects and functions rather than a JavaScript Proxy.
+
+## Model Experience
+
+None, as the package dispatches application calls and registers no prompt, tool, or session event.
+
+#### KV Cache effect
+
+No direct effect; invoked business Services own any model-visible result.
+
+## Known Limitations and Deferred Work
+
+- The Connection adapter currently maps dispatch and business failures to the RPC `internal` code with empty details. Structured `TypertGatewayError` categories remain available only to same-process callers.
+- SRC mode supports unique identifier parameters without destructuring, defaults, or rest parameters. It validates JSON safety rather than generated business types and never infers optional fields.
+- Only strict generated contributions can mount on the Client face. SRC markers have no Client codec or type projection.
+- The package dispatches unary methods only. Incremental Session data uses a separate named-stream protocol over the same Connection.
diff --git a/packages/host/api-gateway/README.zh.md b/packages/host/api-gateway/README.zh.md
new file mode 100644
index 0000000000..77b8b8a87d
--- /dev/null
+++ b/packages/host/api-gateway/README.zh.md
@@ -0,0 +1,36 @@
+# @deepseek-ai/dsh-host-api-gateway
+
+[English](README.md) | 中文
+
+为 Host 与 Client 两侧的 Cordis 环境提供 Remote 控制。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-host-api-gateway/client` 则提供 `ctx.api`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将传输、请求关联、信任和响应封装交由 Connection 处理。
+
+## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
+
+每次调用时，`ctx.typertGateway.invoke()` 都会解析当前的描述符和 Cordis 服务，校验具名参数是否完全匹配，解析已注册的对象或 Context 身份标识，调用公开的业务方法，并校验其结果。业务服务调用 `bindTypeRTGateway()` 并使用 [`dsh-type-meta`](../../typert/type-meta/README.md) 提供的 `@Remote` 或 `@RemoteContext` 装饰器，以显式声明接入。
+
+严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用已向 `ctx.typert.lookups` 注册的提供方，`@RemoteContext` 则通过已注册的 Host Context 提供方解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。
+
+Connection 可用时，Host 入口会注册 trusted-host 的 `/api2` 一元 RPC 通道。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 可区分分发、绑定、提供方、查找、Context、参数和编解码器各自负责的故障。
+
+## Client 服务：`ClientApi`（ctx key：`api`）
+
+`ctx.api.mount()` 会校验并注册生成的 Host-for-Client 贡献项，然后为发起调用的 Cordis fiber 安装具体的直接方法和作用域方法。重复端点、命名空间冲突，以及缺少生成的严格编解码器的描述符，都会在方法可调用前报错。
+
+每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api2', endpoint, ...)` 发送。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
+
+生成的声明合并提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
+
+## 模型体验
+
+无，因为该包分发应用调用，不注册任何提示词、工具或会话事件。
+
+#### KV Cache 影响
+
+无直接影响；被调用的业务服务负责产生任何模型可见结果。
+
+## 已知限制与延期工作
+
+- Connection 适配器目前将分发故障和业务故障映射为 RPC 的 `internal` 代码，且不附带详细信息。结构化的 `TypertGatewayError` 类别仅供同进程调用方使用。
+- SRC 模式仅支持名称唯一的标识符参数，不支持解构、默认值或剩余参数。它只校验值能否安全表示为 JSON，不校验生成的业务类型，也绝不会推断可选字段。
+- Client 侧只能挂载严格模式生成的贡献项。SRC 标记不具备 Client 编解码器或类型投影。
+- 该包只分发一元方法。增量会话数据通过同一个 Connection 上独立的具名流协议传输。
diff --git a/packages/host/api-gateway/package.json b/packages/host/api-gateway/package.json
new file mode 100644
index 0000000000..3f3c905f1d
--- /dev/null
+++ b/packages/host/api-gateway/package.json
@@ -0,0 +1,68 @@
+{
+  "name": "@deepseek-ai/dsh-host-api-gateway",
+  "description": "Host dispatcher and Client API for TypeRT Remote invocations",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-typert-registry",
+      "@deepseek-ai/dsh-client-connection"
+    ],
+    "platform": "web",
+    "immediately": true
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-type-meta": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
+    "cordis": "^4.0.0-rc.7",
+    "zod": "^4.4.3"
+  }
+}
diff --git a/packages/host/api-gateway/src/client/index.ts b/packages/host/api-gateway/src/client/index.ts
new file mode 100644
index 0000000000..57116db2cf
--- /dev/null
+++ b/packages/host/api-gateway/src/client/index.ts
@@ -0,0 +1,370 @@
+/**
+ * Client projection of generated TypeRT Remote descriptors. Contributions
+ * install concrete namespace methods; no JavaScript Proxy participates in
+ * lookup, invocation, or type exposure.
+ */
+
+import { Service } from 'cordis'
+import type { Context } from 'cordis'
+import type { ConnectionHandle, RpcError } from '@deepseek-ai/dsh-client-connection/client'
+import type {
+  InvocationDescriptor,
+  TypeRTCodec,
+  TypeRTDisposer,
+  TypeRTRemoteContribution,
+  TypeRTRemoteNamespaceMap,
+} from '@deepseek-ai/dsh-type-meta'
+
+type RemoteMethod = (...args: unknown[]) => Promise<unknown>
+
+interface MountToken {
+  active: boolean
+  readonly abort: AbortController
+}
+
+interface DirectNamespaceRecord {
+  readonly value: Record<string, RemoteMethod>
+  readonly tokens: Map<string, MountToken>
+}
+
+interface ScopedNamespaceRecord {
+  readonly service: ScopedRemoteNamespace
+  readonly tokens: Map<string, MountToken>
+}
+
+interface ScopedProjection {
+  readonly context: string
+  readonly wire: string
+  readonly codec: TypeRTCodec
+  readonly parameterIndex?: number
+}
+
+/** Typed API service augmented by generated direct Remote namespaces. */
+export interface ClientApi extends TypeRTRemoteNamespaceMap {
+  /**
+   * Mount one generated Host-for-Client contribution in the caller's fiber.
+   * @param contribution - explicitly selected Remote package artifact.
+   * @returns disposer withdrawing descriptors and concrete methods together.
+   */
+  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** Generated direct Remote namespaces selected by the Client assembly. */
+    api: ClientApi
+  }
+}
+
+/** Required Client services: the TypeRT registry and the existing Connection carrier. */
+export const inject = ['typert', 'connection']
+
+/**
+ * Install the typed Client API service.
+ * @param ctx - Client Cordis root.
+ */
+export function apply(ctx: Context): void {
+  new ClientApiService(ctx)
+}
+
+class ClientApiService extends Service implements ClientApi {
+  private readonly ownerCtx: Context
+  private readonly direct = new Map<string, DirectNamespaceRecord>()
+  private readonly scoped = new Map<string, ScopedNamespaceRecord>()
+
+  constructor(ctx: Context) {
+    super(ctx, 'api')
+    this.ownerCtx = ctx
+  }
+
+  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer {
+    this.validateContribution(contribution)
+    const callerCtx = this.ctx
+    const disposeRemote = callerCtx.typert.remotes.register(contribution)
+    let disposeMethods: () => void | Promise<void>
+    try {
+      disposeMethods = callerCtx.effect(() => {
+        const installed = contribution.descriptors.map(descriptor => this.install(descriptor))
+        return () => {
+          for (const dispose of installed.reverse()) dispose()
+        }
+      }, `api-gateway.client.mount(${JSON.stringify(contribution.package)})`)
+    } catch (error) {
+      disposeRemote().catch(() => {})
+      throw error
+    }
+    return async () => {
+      await Promise.all([disposeMethods(), disposeRemote()])
+    }
+  }
+
+  private validateContribution(contribution: TypeRTRemoteContribution): void {
+    const direct = new Map<string, Set<string>>()
+    const scoped = new Map<string, Set<string>>()
+    const add = (
+      table: Map<string, Set<string>>,
+      descriptor: InvocationDescriptor,
+      kind: 'direct' | 'scoped',
+    ): void => {
+      const methods = table.get(descriptor.namespace) ?? new Set<string>()
+      if (methods.has(descriptor.method)) {
+        throw new Error(`client api: contribution repeats ${kind} method ${endpointOf(descriptor)}`)
+      }
+      methods.add(descriptor.method)
+      table.set(descriptor.namespace, methods)
+      const live = kind === 'direct'
+        ? this.direct.get(descriptor.namespace)?.tokens
+        : this.scoped.get(descriptor.namespace)?.tokens
+      if (live?.has(descriptor.method) === true) {
+        throw new Error(`client api: ${kind} method ${endpointOf(descriptor)} is already mounted`)
+      }
+    }
+    for (const descriptor of contribution.descriptors) {
+      requireStrictDescriptor(descriptor)
+      if (descriptor.invocation.kind === 'direct') add(direct, descriptor, 'direct')
+      if (scopedProjection(descriptor) !== undefined) add(scoped, descriptor, 'scoped')
+    }
+    for (const namespace of direct.keys()) {
+      if (!this.direct.has(namespace) && namespace in this) {
+        throw new Error(`client api: namespace ${JSON.stringify(namespace)} conflicts with the API service`)
+      }
+    }
+    for (const [namespace, methods] of scoped) {
+      const record = this.scoped.get(namespace)
+      if (record !== undefined) {
+        for (const method of methods) record.service.assertMethodAvailable(method)
+      } else if (this.ownerCtx.reflect.props[namespace] !== undefined) {
+        throw new Error(`client api: scoped namespace ${JSON.stringify(namespace)} conflicts with an existing Context property`)
+      }
+    }
+  }
+
+  private install(descriptor: InvocationDescriptor): () => void {
+    const token: MountToken = { active: true, abort: new AbortController() }
+    const installed: (() => void)[] = []
+    if (descriptor.invocation.kind === 'direct') {
+      installed.push(this.installDirect(descriptor, token))
+    }
+    const projection = scopedProjection(descriptor)
+    if (projection !== undefined) installed.push(this.installScoped(descriptor, projection, token))
+    return () => {
+      if (!token.active) return
+      token.active = false
+      for (const dispose of installed.reverse()) dispose()
+      token.abort.abort()
+    }
+  }
+
+  private installDirect(descriptor: InvocationDescriptor, token: MountToken): () => void {
+    let namespace = this.direct.get(descriptor.namespace)
+    if (namespace === undefined) {
+      namespace = { value: Object.create(null) as Record<string, RemoteMethod>, tokens: new Map() }
+      this.direct.set(descriptor.namespace, namespace)
+      Object.defineProperty(this, descriptor.namespace, {
+        configurable: true,
+        enumerable: true,
+        value: namespace.value,
+      })
+    }
+    namespace.tokens.set(descriptor.method, token)
+    Object.defineProperty(namespace.value, descriptor.method, {
+      configurable: true,
+      enumerable: true,
+      value: (...args: unknown[]) => this.invoke(descriptor, undefined, token, this.ownerCtx, args),
+    })
+    return () => {
+      if (namespace.tokens.get(descriptor.method) !== token) return
+      Reflect.deleteProperty(namespace.value, descriptor.method)
+      namespace.tokens.delete(descriptor.method)
+      if (namespace.tokens.size !== 0) return
+      this.direct.delete(descriptor.namespace)
+      Reflect.deleteProperty(this, descriptor.namespace)
+    }
+  }
+
+  private installScoped(
+    descriptor: InvocationDescriptor,
+    projection: ScopedProjection,
+    token: MountToken,
+  ): () => void {
+    let namespace = this.scoped.get(descriptor.namespace)
+    if (namespace === undefined) {
+      namespace = {
+        service: new ScopedRemoteNamespace(
+          this.ownerCtx,
+          descriptor.namespace,
+          (current, currentProjection, currentToken, caller, args) =>
+            this.invoke(current, currentProjection, currentToken, caller, args),
+        ),
+        tokens: new Map(),
+      }
+      this.scoped.set(descriptor.namespace, namespace)
+    }
+    namespace.tokens.set(descriptor.method, token)
+    namespace.service.install(descriptor, projection, token)
+    return () => {
+      if (namespace.tokens.get(descriptor.method) !== token) return
+      namespace.service.remove(descriptor.method)
+      namespace.tokens.delete(descriptor.method)
+    }
+  }
+
+  private async invoke(
+    descriptor: InvocationDescriptor,
+    projection: ScopedProjection | undefined,
+    token: MountToken,
+    callerCtx: Context,
+    values: readonly unknown[],
+  ): Promise<unknown> {
+    const endpoint = endpointOf(descriptor)
+    if (!token.active) throw new Error(`client api: Remote method ${endpoint} is no longer mounted`)
+    const expected = descriptor.parameters.length - (projection?.parameterIndex === undefined ? 0 : 1)
+    if (values.length !== expected) {
+      throw new Error(
+        `client api: ${endpoint} expected ${String(expected)} argument(s), got ${String(values.length)}`,
+      )
+    }
+    const args: Record<string, unknown> = {}
+    if (projection !== undefined) {
+      const binder = this.ownerCtx.typert.contexts.getClient(projection.context)
+      if (binder === undefined) {
+        throw new Error(`client api: ${endpoint} has no Client Context binder for ${JSON.stringify(projection.context)}`)
+      }
+      const identity = binder.identity(callerCtx)
+      if (identity === undefined) {
+        throw new Error(`client api: ${endpoint} requires a ${JSON.stringify(projection.context)} Context`)
+      }
+      args[projection.wire] = parse(projection.codec, identity, endpoint, projection.wire)
+    }
+    let valueIndex = 0
+    descriptor.parameters.forEach((parameter, parameterIndex) => {
+      if (parameterIndex === projection?.parameterIndex) return
+      args[parameter.wire] = parse(parameter.codec, values[valueIndex], endpoint, parameter.wire)
+      valueIndex += 1
+    })
+    const connection = this.ownerCtx.get('connection') as ConnectionHandle | undefined
+    if (connection === undefined) throw new Error(`client api: ${endpoint} has no active Connection`)
+    const result = await connection.rpc.call('/api2', endpoint, { args }, token.abort.signal)
+    if (!mountActive(token)) throw new Error(`client api: Remote method ${endpoint} was withdrawn during invocation`)
+    if (!result.ok) throw remoteFailure(endpoint, result.error)
+    return parse(descriptor.result, result.value, endpoint, 'result')
+  }
+}
+
+type InvokeRemote = (
+  descriptor: InvocationDescriptor,
+  projection: ScopedProjection,
+  token: MountToken,
+  callerCtx: Context,
+  args: readonly unknown[],
+) => Promise<unknown>
+
+class ScopedRemoteNamespace extends Service {
+  private readonly ownerCtx: Context
+  private readonly methods = new Set<string>()
+
+  constructor(
+    ctx: Context,
+    name: string,
+    private readonly invokeRemote: InvokeRemote,
+  ) {
+    super(ctx, name)
+    this.ownerCtx = ctx
+  }
+
+  assertMethodAvailable(method: string): void {
+    if (method in this) {
+      throw new Error(`client api: scoped method ${JSON.stringify(`${this.name}/${method}`)} conflicts with its namespace service`)
+    }
+  }
+
+  install(descriptor: InvocationDescriptor, projection: ScopedProjection, token: MountToken): void {
+    this.assertMethodAvailable(descriptor.method)
+    const method = descriptor.method
+    Object.defineProperty(this, method, {
+      configurable: true,
+      enumerable: true,
+      value: function (this: ScopedRemoteNamespace, ...args: unknown[]): Promise<unknown> {
+        return this.invokeRemote(descriptor, projection, token, this.ctx, args)
+      },
+    })
+    this.methods.add(method)
+    if (this.methods.size === 1 && this.ownerCtx.get(this.name, false) === undefined) {
+      this.ownerCtx.set(this.name, this)
+    }
+  }
+
+  remove(method: string): void {
+    Reflect.deleteProperty(this, method)
+    this.methods.delete(method)
+    if (this.methods.size === 0) this.ownerCtx.set(this.name, undefined)
+  }
+}
+
+function endpointOf(descriptor: Pick<InvocationDescriptor, 'namespace' | 'method'>): string {
+  return `${descriptor.namespace}/${descriptor.method}`
+}
+
+function mountActive(token: MountToken): boolean {
+  return token.active
+}
+
+function scopedProjection(descriptor: InvocationDescriptor): ScopedProjection | undefined {
+  if (descriptor.invocation.kind === 'context') {
+    return {
+      context: descriptor.invocation.context,
+      wire: descriptor.invocation.wire,
+      codec: descriptor.invocation.codec,
+    }
+  }
+  if (descriptor.scope === undefined) return undefined
+  const lookupParameters = descriptor.parameters
+    .map((parameter, index) => ({ parameter, index }))
+    .filter(candidate => candidate.parameter.source === 'lookup')
+  const selected = lookupParameters.length === 1 ? lookupParameters[0] : undefined
+  if (selected === undefined
+    || selected.parameter.wire !== descriptor.scope.wire
+    || selected.parameter.lookup !== descriptor.scope.context) {
+    throw new Error(
+      `client api: generated Remote ${endpointOf(descriptor)} scope must select its only lookup parameter`,
+    )
+  }
+  return {
+    context: descriptor.scope.context,
+    wire: descriptor.scope.wire,
+    codec: selected.parameter.codec,
+    parameterIndex: selected.index,
+  }
+}
+
+function requireStrictDescriptor(descriptor: InvocationDescriptor): void {
+  const endpoint = endpointOf(descriptor)
+  requireStrictCodec(descriptor.result, endpoint, 'result')
+  for (const parameter of descriptor.parameters) {
+    requireStrictCodec(parameter.codec, endpoint, parameter.wire)
+  }
+  if (descriptor.invocation.kind === 'context') {
+    requireStrictCodec(descriptor.invocation.codec, endpoint, descriptor.invocation.wire)
+  }
+}
+
+function requireStrictCodec(codec: TypeRTCodec, endpoint: string, field: string): void {
+  if (codec.mode !== 'strict') {
+    throw new Error(`client api: generated Remote ${endpoint} field ${JSON.stringify(field)} has no strict codec`)
+  }
+}
+
+function parse(codec: TypeRTCodec, value: unknown, endpoint: string, field: string): unknown {
+  if (codec.mode !== 'strict') {
+    throw new Error(`client api: generated Remote ${endpoint} field ${JSON.stringify(field)} has no strict codec`)
+  }
+  try {
+    return codec.schema.parse(value)
+  } catch (cause) {
+    throw new Error(`client api: ${endpoint} rejected ${JSON.stringify(field)}`, { cause })
+  }
+}
+
+function remoteFailure(endpoint: string, error: RpcError): Error {
+  return new Error(`client api: ${endpoint} failed: ${error.code}: ${error.message}`, { cause: error })
+}
diff --git a/packages/host/api-gateway/src/index.ts b/packages/host/api-gateway/src/index.ts
new file mode 100644
index 0000000000..ccb76e2d48
--- /dev/null
+++ b/packages/host/api-gateway/src/index.ts
@@ -0,0 +1,604 @@
+/**
+ * Live TypeRT Remote dispatch over Cordis Services and registered providers.
+ * Transport, request correlation, and response envelopes belong to Connection.
+ * @module @deepseek-ai/dsh-host-api-gateway
+ */
+
+import { Context, Service, symbols } from 'cordis'
+import {
+  remoteMethods,
+  type InvocationDescriptor,
+  type InvocationParameterDescriptor,
+  type TypeRTCodec,
+  type TypeRTGatewayBinding,
+  type TypeRTLookupProvider,
+} from '@deepseek-ai/dsh-type-meta'
+import type {
+  InvokeRemoteRequest,
+  TypertGateway,
+  TypertGatewayErrorCode,
+} from './types.ts'
+
+export type {
+  InvokeRemoteRequest,
+  TypertGateway,
+  TypertGatewayErrorCode,
+} from './types.ts'
+
+interface GatewayErrorOptions {
+  readonly cause?: unknown
+  readonly field?: string
+}
+
+interface ResolvedBinding {
+  readonly binding: TypeRTGatewayBinding
+  readonly original: object
+}
+
+type ConnectionRpcResult =
+  | { readonly ok: true; readonly value: unknown }
+  | {
+    readonly ok: false
+    readonly error: {
+      readonly code: 'internal'
+      readonly message: string
+      readonly details: Record<never, never>
+    }
+  }
+
+interface HostConnectionLike {
+  readonly rpc: {
+    handle(
+      channel: string,
+      handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<ConnectionRpcResult>,
+      options: { readonly authority: 'trusted-host' | 'loopback' },
+    ): () => Promise<void>
+  }
+}
+
+/** Dispatch failure produced outside the invoked business method. */
+export class TypertGatewayError extends Error {
+  /** Machine-readable failure category. */
+  readonly code: TypertGatewayErrorCode
+  /** Canonical `<namespace>/<method>` endpoint. */
+  readonly endpoint: string
+  /** Affected wire field when the failure is field-specific. */
+  readonly field: string | undefined
+
+  /**
+   * Construct a Gateway failure without embedding boundary values in its message.
+   * @param code - stable failure category.
+   * @param endpoint - canonical Remote endpoint.
+   * @param message - correction-oriented diagnostic without sensitive values.
+   * @param options - optional field and contained cause.
+   */
+  constructor(
+    code: TypertGatewayErrorCode,
+    endpoint: string,
+    message: string,
+    options: GatewayErrorOptions = {},
+  ) {
+    super(`typert gateway: ${endpoint}: ${message}`, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'TypertGatewayError'
+    this.code = code
+    this.endpoint = endpoint
+    this.field = options.field
+  }
+}
+
+/**
+ * Resolve strict generated definitions or conservative SRC markers against
+ * current Cordis Services and TypeRT providers.
+ * @typert service typertGateway
+ */
+export class TypertGatewayService extends Service implements TypertGateway {
+  static inject = ['typert']
+
+  /**
+   * Register the Gateway against the active TypeRT registry.
+   * @param ctx - owning Host Context with TypeRT registry access.
+   */
+  constructor(ctx: Context) {
+    super(ctx, 'typertGateway')
+    ctx.inject(['connection'], (connectionCtx) => {
+      const connection = connectionCtx.get('connection') as unknown as HostConnectionLike
+      connection.rpc.handle(
+        '/api2',
+        (endpoint, payload, signal) => this.dispatchRpc(endpoint, payload, signal),
+        { authority: 'trusted-host' },
+      )
+    })
+  }
+
+  /**
+   * Invoke one live Remote method through strict generated reflection or SRC markers.
+   * @param request - decoded endpoint and exact named wire arguments.
+   * @returns the validated business result.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+   */
+  async invoke(request: InvokeRemoteRequest): Promise<unknown> {
+    const endpoint = endpointOf(request.namespace, request.method)
+    const descriptor = this.resolveDescriptor(request.namespace, request.method, endpoint)
+    assertExactArguments(request.args, descriptor, endpoint)
+    const receiverContext = this.resolveReceiverContext(descriptor, request.args, endpoint)
+    const receiver = receiverContext.get(descriptor.service) as unknown
+    if (!isObject(receiver)) {
+      throw new TypertGatewayError(
+        'service-unavailable',
+        endpoint,
+        `active Service ${JSON.stringify(descriptor.service)} is unavailable`,
+      )
+    }
+    validateBinding(receiver, descriptor.service, descriptor.namespace, endpoint)
+    const args = descriptor.parameters.map(parameter => this.resolveParameter(parameter, request.args, endpoint))
+    const implementation = descriptor.implementation ?? descriptor.method
+    const method = Reflect.get(receiver, implementation) as unknown
+    if (typeof method !== 'function') {
+      throw new TypertGatewayError(
+        'method-unavailable',
+        endpoint,
+        `active Service ${JSON.stringify(descriptor.service)} has no callable method ${JSON.stringify(implementation)}`,
+      )
+    }
+
+    const result = await Reflect.apply(method, receiver, args) as unknown
+    return decode(descriptor.result, result, 'result-invalid', endpoint, 'result')
+  }
+
+  private async dispatchRpc(
+    endpoint: string,
+    payload: unknown,
+    _signal: AbortSignal,
+  ): Promise<ConnectionRpcResult> {
+    return this.invokeRpc(endpoint, payload)
+  }
+
+  private async invokeRpc(endpoint: string, payload: unknown): Promise<ConnectionRpcResult> {
+    try {
+      const segments = endpoint.split('/')
+      const namespace = segments[0]
+      const method = segments[1]
+      if (segments.length !== 2 || namespace === undefined || namespace === '' || method === undefined || method === '') {
+        throw new Error(`invalid Remote endpoint ${JSON.stringify(endpoint)}`)
+      }
+      if (!isObject(payload)
+        || !isPlainObject(payload)
+        || Reflect.ownKeys(payload).length !== 1
+        || !Object.hasOwn(payload, 'args')
+        || !isObject(payload.args)
+        || !isPlainObject(payload.args)) {
+        throw new Error('Remote payload must contain exactly one plain-object args field')
+      }
+      const value = await this.invoke({
+        namespace,
+        method,
+        args: payload.args,
+      })
+      return { ok: true, value }
+    } catch (error) {
+      return rpcFailure(error)
+    }
+  }
+
+  private resolveDescriptor(namespace: string, method: string, endpoint: string): InvocationDescriptor {
+    const strict = this.ctx.typert.local.get(endpoint)
+    if (strict !== undefined) return strict
+    if (this.ctx.typert.local.hasSeen(endpoint)) {
+      throw new TypertGatewayError(
+        'definition-unavailable',
+        endpoint,
+        'its strict definition was withdrawn and SRC fallback is forbidden',
+      )
+    }
+    return this.resolveSrcDescriptor(namespace, method, endpoint)
+  }
+
+  private resolveSrcDescriptor(namespace: string, method: string, endpoint: string): InvocationDescriptor {
+    const candidates: InvocationDescriptor[] = []
+    for (const [serviceKey, definition] of Object.entries(this.ctx.reflect.props)) {
+      if (definition.type !== 'service') continue
+      const receiver = this.ctx.get(serviceKey) as unknown
+      if (!isObject(receiver)) continue
+      const original = originalOf(receiver)
+      const value = Reflect.get(original, 'typertGateway') as unknown
+      if (value === undefined) continue
+      const binding = readBinding(value, original, serviceKey, endpoint)
+      if (binding.namespace !== namespace) continue
+      const marker = remoteMethods(original).find(candidate => (candidate.exportName ?? candidate.method) === method)
+      if (marker === undefined) continue
+      candidates.push(this.srcDescriptor(binding, marker, method, endpoint))
+    }
+    if (candidates.length === 0) {
+      throw new TypertGatewayError('invocation-unavailable', endpoint, 'no active Remote method exports this endpoint')
+    }
+    if (candidates.length > 1) {
+      throw new TypertGatewayError(
+        'ambiguous-endpoint',
+        endpoint,
+        `multiple active Services export this endpoint: ${candidates.map(candidate => candidate.service).sort().join(', ')}`,
+      )
+    }
+    return candidates[0] as InvocationDescriptor
+  }
+
+  private srcDescriptor(
+    binding: TypeRTGatewayBinding,
+    marker: ReturnType<typeof remoteMethods>[number],
+    method: string,
+    endpoint: string,
+  ): InvocationDescriptor {
+    const names = methodParameterNames(binding.service, marker.method, endpoint)
+    const parameters: InvocationParameterDescriptor[] = []
+    const wires = new Set<string>()
+    for (const name of names) {
+      const matches = this.ctx.typert.lookups.keys()
+        .map(key => ({ key, provider: this.ctx.typert.lookups.get(key) }))
+        .filter((entry): entry is { key: string; provider: TypeRTLookupProvider } =>
+          entry.provider?.parameter === name)
+      if (matches.length > 1) {
+        throw new TypertGatewayError(
+          'signature-invalid',
+          endpoint,
+          `parameter ${JSON.stringify(name)} matches multiple lookup providers`,
+          { field: name },
+        )
+      }
+      const match = matches[0]
+      const parameter: InvocationParameterDescriptor = match === undefined
+        ? { name, wire: name, source: 'json', codec: { mode: 'src-json' } }
+        : {
+          name,
+          wire: match.provider.wire,
+          source: 'lookup',
+          lookup: match.key,
+          codec: { mode: 'src-json' },
+        }
+      if (wires.has(parameter.wire)) {
+        throw new TypertGatewayError(
+          'signature-invalid',
+          endpoint,
+          `multiple parameters use wire field ${JSON.stringify(parameter.wire)}`,
+          { field: parameter.wire },
+        )
+      }
+      wires.add(parameter.wire)
+      parameters.push(parameter)
+    }
+
+    let receiver: InvocationDescriptor['invocation'] = { kind: 'direct' }
+    if (marker.invocation.kind === 'context') {
+      const provider = this.ctx.typert.contexts.getHost(marker.invocation.context)
+      if (provider === undefined) {
+        throw new TypertGatewayError(
+          'context-unavailable',
+          endpoint,
+          `Context provider ${JSON.stringify(marker.invocation.context)} is unavailable`,
+        )
+      }
+      if (wires.has(provider.wire)) {
+        throw new TypertGatewayError(
+          'signature-invalid',
+          endpoint,
+          `Context identity conflicts with wire field ${JSON.stringify(provider.wire)}`,
+          { field: provider.wire },
+        )
+      }
+      receiver = {
+        kind: 'context',
+        context: marker.invocation.context,
+        wire: provider.wire,
+        codec: { mode: 'src-json' },
+      }
+    }
+
+    return {
+      id: `src:${binding.serviceKey}#${endpoint}`,
+      service: binding.serviceKey,
+      namespace: binding.namespace,
+      method,
+      ...(marker.method === method ? {} : { implementation: marker.method }),
+      invocation: receiver,
+      parameters,
+      result: { mode: 'src-json' },
+    }
+  }
+
+  private resolveReceiverContext(
+    descriptor: InvocationDescriptor,
+    args: Readonly<Record<string, unknown>>,
+    endpoint: string,
+  ): Context {
+    if (descriptor.invocation.kind === 'direct') return this.ctx
+    const invocation = descriptor.invocation
+    const provider = this.ctx.typert.contexts.getHost(invocation.context)
+    if (provider === undefined) {
+      throw new TypertGatewayError(
+        'context-unavailable',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} is unavailable`,
+      )
+    }
+    if (provider.wire !== invocation.wire
+      || (invocation.codec.mode === 'strict' && provider.wireTypeSymbol !== invocation.codec.typeSymbol)) {
+      throw new TypertGatewayError(
+        'provider-mismatch',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} does not match its strict definition`,
+        { field: invocation.wire },
+      )
+    }
+    const identity = decode(invocation.codec, args[invocation.wire], 'input-invalid', endpoint, invocation.wire)
+    let context: Context | undefined
+    try {
+      context = provider.resolve(identity)
+    } catch (cause) {
+      throw new TypertGatewayError(
+        'context-failed',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} failed`,
+        { cause, field: invocation.wire },
+      )
+    }
+    if (context === undefined) {
+      throw new TypertGatewayError(
+        'context-not-found',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} did not resolve the requested identity`,
+        { field: invocation.wire },
+      )
+    }
+    return context
+  }
+
+  private resolveParameter(
+    parameter: InvocationParameterDescriptor,
+    args: Readonly<Record<string, unknown>>,
+    endpoint: string,
+  ): unknown {
+    const value = decode(parameter.codec, args[parameter.wire], 'input-invalid', endpoint, parameter.wire)
+    if (parameter.source === 'json') return value
+    const key = parameter.lookup
+    if (key === undefined) {
+      throw new TypertGatewayError(
+        'lookup-unavailable',
+        endpoint,
+        `lookup parameter ${JSON.stringify(parameter.name)} has no provider key`,
+        { field: parameter.wire },
+      )
+    }
+    const provider = this.ctx.typert.lookups.get(key)
+    if (provider === undefined) {
+      throw new TypertGatewayError(
+        'lookup-unavailable',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} is unavailable`,
+        { field: parameter.wire },
+      )
+    }
+    if (provider.wire !== parameter.wire
+      || (parameter.codec.mode === 'strict' && provider.wireTypeSymbol !== parameter.codec.typeSymbol)) {
+      throw new TypertGatewayError(
+        'provider-mismatch',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} does not match its strict definition`,
+        { field: parameter.wire },
+      )
+    }
+    let resolved: unknown
+    try {
+      resolved = provider.resolve(value)
+    } catch (cause) {
+      throw new TypertGatewayError(
+        'lookup-failed',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} failed`,
+        { cause, field: parameter.wire },
+      )
+    }
+    if (resolved === undefined) {
+      throw new TypertGatewayError(
+        'lookup-not-found',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} did not resolve the requested identity`,
+        { field: parameter.wire },
+      )
+    }
+    return resolved
+  }
+}
+
+function rpcFailure(error: unknown): ConnectionRpcResult {
+  return {
+    ok: false,
+    error: {
+      code: 'internal',
+      message: error instanceof Error ? error.message : String(error),
+      details: {},
+    },
+  }
+}
+
+function endpointOf(namespace: string, method: string): string {
+  return `${namespace}/${method}`
+}
+
+function validateBinding(
+  receiver: object,
+  serviceKey: string,
+  namespace: string,
+  endpoint: string,
+): ResolvedBinding {
+  const original = originalOf(receiver)
+  const value = Reflect.get(original, 'typertGateway') as unknown
+  if (value === undefined) {
+    throw new TypertGatewayError(
+      'binding-invalid',
+      endpoint,
+      `Service ${JSON.stringify(serviceKey)} has no visible typertGateway binding`,
+    )
+  }
+  return {
+    binding: readBinding(value, original, serviceKey, endpoint, namespace),
+    original,
+  }
+}
+
+function readBinding(
+  value: unknown,
+  original: object,
+  serviceKey: string,
+  endpoint: string,
+  namespace?: string,
+): TypeRTGatewayBinding {
+  if (!isObject(value)
+    || Reflect.get(value, 'service') !== original
+    || Reflect.get(value, 'serviceKey') !== serviceKey
+    || typeof Reflect.get(value, 'namespace') !== 'string'
+    || (namespace !== undefined && Reflect.get(value, 'namespace') !== namespace)) {
+    throw new TypertGatewayError(
+      'binding-invalid',
+      endpoint,
+      `Service ${JSON.stringify(serviceKey)} has an inconsistent typertGateway binding`,
+    )
+  }
+  return value as unknown as TypeRTGatewayBinding
+}
+
+function originalOf(receiver: object): object {
+  const original = Reflect.get(receiver, symbols.original) as unknown
+  return isObject(original) ? original : receiver
+}
+
+function methodParameterNames(service: object, method: string, endpoint: string): readonly string[] {
+  let prototype: object | null = Object.getPrototypeOf(service) as object | null
+  let implementation: ((this: object, ...args: never[]) => unknown) | undefined
+  while (prototype !== null) {
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, method)
+    if (descriptor !== undefined) {
+      if ('value' in descriptor && typeof descriptor.value === 'function') {
+        implementation = descriptor.value as (this: object, ...args: never[]) => unknown
+      }
+      break
+    }
+    prototype = Object.getPrototypeOf(prototype) as object | null
+  }
+  if (implementation === undefined) {
+    throw new TypertGatewayError(
+      'method-unavailable',
+      endpoint,
+      `Remote marker has no prototype method ${JSON.stringify(method)}`,
+    )
+  }
+  const source = Function.prototype.toString.call(implementation)
+  const open = source.indexOf('(')
+  const close = source.indexOf(')', open + 1)
+  if (open < 0 || close < 0) return invalidSignature(endpoint, method)
+  const body = source.slice(open + 1, close).trim()
+  if (body.length === 0) return []
+  const parts = body.split(',').map(part => part.trim())
+  if (parts.at(-1) === '') parts.pop()
+  const names = new Set<string>()
+  for (const part of parts) {
+    if (!/^[$A-Z_a-z][$\w]*$/u.test(part) || names.has(part)) return invalidSignature(endpoint, method)
+    names.add(part)
+  }
+  return [...names]
+}
+
+function invalidSignature(endpoint: string, method: string): never {
+  throw new TypertGatewayError(
+    'signature-invalid',
+    endpoint,
+    `SRC method ${JSON.stringify(method)} must use unique identifier parameters without destructuring, defaults, or rest`,
+  )
+}
+
+function assertExactArguments(
+  args: Readonly<Record<string, unknown>>,
+  descriptor: InvocationDescriptor,
+  endpoint: string,
+): void {
+  if (!isPlainObject(args)) {
+    throw new TypertGatewayError('arguments-invalid', endpoint, 'args must be a plain object')
+  }
+  const expected = new Set(descriptor.parameters.map(parameter => parameter.wire))
+  if (descriptor.invocation.kind === 'context') expected.add(descriptor.invocation.wire)
+  const actual = Reflect.ownKeys(args)
+  const extra = actual.filter(key => typeof key !== 'string' || !expected.has(key))
+  const missing = [...expected].filter(key => !Object.hasOwn(args, key))
+  if (extra.length === 0 && missing.length === 0) return
+  const clauses: string[] = []
+  if (missing.length > 0) clauses.push(`missing ${missing.map(key => JSON.stringify(key)).join(', ')}`)
+  if (extra.length > 0) clauses.push(`unexpected ${extra.map(key => JSON.stringify(String(key))).join(', ')}`)
+  throw new TypertGatewayError('arguments-invalid', endpoint, `args fields do not match the descriptor: ${clauses.join('; ')}`)
+}
+
+function decode(
+  codec: TypeRTCodec,
+  value: unknown,
+  code: 'input-invalid' | 'result-invalid',
+  endpoint: string,
+  field: string,
+): unknown {
+  try {
+    if (codec.mode === 'strict') return codec.schema.parse(value)
+    assertJsonValue(value, new Set())
+    return value
+  } catch (cause) {
+    throw new TypertGatewayError(
+      code,
+      endpoint,
+      code === 'input-invalid'
+        ? `wire field ${JSON.stringify(field)} failed boundary validation`
+        : 'business result failed boundary validation',
+      { cause, field },
+    )
+  }
+}
+
+function assertJsonValue(value: unknown, ancestors: Set<object>): void {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return
+    throw new TypeError('non-finite number is not JSON-safe')
+  }
+  if (!isObject(value)) throw new TypeError(`${typeof value} is not JSON-safe`)
+  if (ancestors.has(value)) throw new TypeError('cyclic value is not JSON-safe')
+  ancestors.add(value)
+  try {
+    if (Array.isArray(value)) {
+      if (Object.getOwnPropertySymbols(value).length > 0 || Object.keys(value).length !== value.length) {
+        throw new TypeError('sparse or decorated array is not JSON-safe')
+      }
+      for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index)) throw new TypeError('sparse array is not JSON-safe')
+        assertJsonValue(value[index], ancestors)
+      }
+      return
+    }
+    if (!isPlainObject(value)) throw new TypeError('non-plain object is not JSON-safe')
+    if (Object.getOwnPropertySymbols(value).length > 0) throw new TypeError('symbol property is not JSON-safe')
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== 'string') throw new TypeError('symbol property is not JSON-safe')
+      const descriptor = Object.getOwnPropertyDescriptor(value, key)
+      if (descriptor === undefined || !descriptor.enumerable || !('value' in descriptor)) {
+        throw new TypeError('non-data property is not JSON-safe')
+      }
+      assertJsonValue(descriptor.value, ancestors)
+    }
+  } finally {
+    ancestors.delete(value)
+  }
+}
+
+function isPlainObject(value: object): value is Record<string, unknown> {
+  if (Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value) as object | null
+  return prototype === null || prototype === Object.prototype
+}
+
+function isObject(value: unknown): value is object {
+  return (typeof value === 'object' && value !== null) || typeof value === 'function'
+}
+
+export default TypertGatewayService
diff --git a/packages/host/api-gateway/src/invariant.ts b/packages/host/api-gateway/src/invariant.ts
new file mode 100644
index 0000000000..65c94b4ac4
--- /dev/null
+++ b/packages/host/api-gateway/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-host-api-gateway`.
+ * @module @deepseek-ai/dsh-host-api-gateway/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-api-gateway'
+
+/** Cordis companion plugin name. */
+export const name = 'host-api-gateway-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: Host calls re-read authoritative Cordis and TypeRT
+ * state, while Client methods and descriptors mutate in one owned effect.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/host/api-gateway/src/types.ts b/packages/host/api-gateway/src/types.ts
new file mode 100644
index 0000000000..eea2bdc4f1
--- /dev/null
+++ b/packages/host/api-gateway/src/types.ts
@@ -0,0 +1,52 @@
+/**
+ * Carrier-independent TypeRT Gateway request, service, and error contracts.
+ * @module @deepseek-ai/dsh-host-api-gateway/types
+ */
+
+/** One Remote method request after a carrier has decoded its envelope. */
+export interface InvokeRemoteRequest {
+  /** Remote namespace selected by the generated descriptor. */
+  readonly namespace: string
+  /** Exported Service method name. */
+  readonly method: string
+  /** Named wire values; fields must exactly match the descriptor. */
+  readonly args: Readonly<Record<string, unknown>>
+}
+
+/** Stable infrastructure and boundary failures emitted before or after business execution. */
+export type TypertGatewayErrorCode =
+  | 'ambiguous-endpoint'
+  | 'arguments-invalid'
+  | 'binding-invalid'
+  | 'context-failed'
+  | 'context-not-found'
+  | 'context-unavailable'
+  | 'definition-unavailable'
+  | 'input-invalid'
+  | 'invocation-unavailable'
+  | 'lookup-failed'
+  | 'lookup-not-found'
+  | 'lookup-unavailable'
+  | 'method-unavailable'
+  | 'provider-mismatch'
+  | 'result-invalid'
+  | 'service-unavailable'
+  | 'signature-invalid'
+
+/** Host dispatcher consumed by Connection adapters. */
+export interface TypertGateway {
+  /**
+   * Invoke one live Remote method without assuming a carrier or response envelope.
+   * @param request - decoded endpoint and named wire arguments.
+   * @returns the validated business result.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+   */
+  invoke(request: InvokeRemoteRequest): Promise<unknown>
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** Host dispatcher for TypeRT Remote calls. */
+    typertGateway: TypertGateway
+  }
+}
diff --git a/packages/host/api-gateway/tests/client.spec.ts b/packages/host/api-gateway/tests/client.spec.ts
new file mode 100644
index 0000000000..be0b12ed51
--- /dev/null
+++ b/packages/host/api-gateway/tests/client.spec.ts
@@ -0,0 +1,222 @@
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import type {
+  InvocationDescriptor,
+  TypeRTContext,
+  TypeRTRemoteContextApi,
+  TypeRTRemoteNamespace,
+} from '@deepseek-ai/dsh-type-meta'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
+import { apply, inject } from '../src/client/index.ts'
+
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTContextMap {
+    fixture: TypeRTContext<string>
+  }
+
+  interface TypeRTRemoteMap {
+    'goals/create': (agentId: string, request: { readonly objective: string }) => Promise<{ readonly ref: string }>
+  }
+
+  interface TypeRTRemoteContextMap {
+    'fixture:goals/create': (request: { readonly objective: string }) => Promise<{ readonly ref: string }>
+    'fixture:goals/rename': (request: { readonly objective: string }) => Promise<{ readonly renamed: boolean }>
+  }
+
+  interface TypeRTRemoteNamespaceMap {
+    goals: TypeRTRemoteNamespace<'goals'>
+  }
+
+}
+
+type FixtureContext = Context & TypeRTRemoteContextApi<'fixture'>
+
+const idSchema = z.string().min(1)
+const requestSchema = z.object({ objective: z.string().min(1) })
+const createResultSchema = z.object({ ref: z.string().min(1) })
+const renameResultSchema = z.object({ renamed: z.boolean() })
+
+function directDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/goals#goals/create',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'create',
+    invocation: { kind: 'direct' },
+    scope: { context: 'fixture', wire: 'agentId' },
+    parameters: [{
+      name: 'agent',
+      wire: 'agentId',
+      source: 'lookup',
+      lookup: 'fixture',
+      codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', schema: idSchema },
+    }, {
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: { mode: 'strict', typeSymbol: '@fixture#CreateRequest', schema: requestSchema },
+    }],
+    result: { mode: 'strict', typeSymbol: '@fixture#CreateResult', schema: createResultSchema },
+  }
+}
+
+function contextDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/goals#goals/rename',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'rename',
+    invocation: {
+      kind: 'context',
+      context: 'fixture',
+      wire: 'agentId',
+      codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', schema: idSchema },
+    },
+    parameters: [{
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: { mode: 'strict', typeSymbol: '@fixture#RenameRequest', schema: requestSchema },
+    }],
+    result: { mode: 'strict', typeSymbol: '@fixture#RenameResult', schema: renameResultSchema },
+  }
+}
+
+async function bench(call: ConnectionHandle['rpc']['call']): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
+  ctx.provide('connection', { rpc: { call } } as unknown as ConnectionHandle)
+  await ctx.plugin({ inject, apply })
+  return ctx
+}
+
+describe('Client TypeRT API', () => {
+  it('mounts concrete direct methods, validates both boundaries, and withdraws retained handles', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })
+    const ctx = await bench(call)
+    let retained: typeof ctx.api.goals.create | undefined
+    const assembly = ctx.plugin(Object.assign(
+      (scope: Context) => {
+        scope.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
+        retained = scope.api.goals.create
+      },
+      { inject: ['api'] },
+    ))
+    await assembly
+
+    await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).resolves.toEqual({ ref: 'goal-1' })
+    expect(call).toHaveBeenCalledWith(
+      '/api2',
+      'goals/create',
+      { args: { agentId: 'agent-1', request: { objective: 'ship' } } },
+      expect.any(AbortSignal),
+    )
+    await expect(ctx.api.goals.create('', { objective: 'ship' })).rejects.toThrow('rejected "agentId"')
+
+    call.mockResolvedValueOnce({ ok: true, value: { ref: 1 } })
+    await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('rejected "result"')
+
+    await assembly.dispose()
+    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect(ctx.get('goals')).toBeUndefined()
+    expect(ctx.typert.remotes.list()).toEqual([])
+    await expect(retained?.('agent-1', { objective: 'ship' })).rejects.toThrow('no longer mounted')
+  })
+
+  it('projects one direct lookup descriptor onto an Agent-scoped alias', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { ref: 'goal-2' } })
+    const ctx = await bench(call)
+    const agentCtx = ctx.extend({ fixtureId: 'agent-2' }) as FixtureContext
+    ctx.typert.contexts.registerClient('fixture', {
+      identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId,
+    })
+    const assembly = ctx.plugin(Object.assign(
+      (scope: Context) => {
+        scope.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
+      },
+      { inject: ['api'] },
+    ))
+    await assembly
+
+    await expect(agentCtx.goals.create({ objective: 'ship scoped' })).resolves.toEqual({ ref: 'goal-2' })
+    expect(call).toHaveBeenCalledWith(
+      '/api2',
+      'goals/create',
+      { args: { agentId: 'agent-2', request: { objective: 'ship scoped' } } },
+      expect.any(AbortSignal),
+    )
+    await expect((ctx as FixtureContext).goals.create({ objective: 'wrong scope' }))
+      .rejects.toThrow('requires a "fixture" Context')
+
+    await assembly.dispose()
+    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect(ctx.get('goals')).toBeUndefined()
+  })
+
+  it('uses the caller Context identity for scoped namespace methods', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { renamed: true } })
+    const ctx = await bench(call)
+    const agentCtx = ctx.extend({ fixtureId: 'agent-2' }) as FixtureContext
+    ctx.typert.contexts.registerClient('fixture', {
+      identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId,
+    })
+    const assembly = ctx.plugin(Object.assign(
+      (scope: Context) => {
+        scope.api.mount({ package: '@fixture/goals', descriptors: [contextDescriptor()] })
+      },
+      { inject: ['api'] },
+    ))
+    await assembly
+
+    await expect(agentCtx.goals.rename({ objective: 'land' })).resolves.toEqual({ renamed: true })
+    expect(call).toHaveBeenCalledWith(
+      '/api2',
+      'goals/rename',
+      { args: { agentId: 'agent-2', request: { objective: 'land' } } },
+      expect.any(AbortSignal),
+    )
+    await expect((ctx as FixtureContext).goals.rename({ objective: 'land' }))
+      .rejects.toThrow('requires a "fixture" Context')
+
+    await assembly.dispose()
+    expect(ctx.get('goals')).toBeUndefined()
+  })
+
+  it('rejects weak descriptors and namespace collisions before registration', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const weak: InvocationDescriptor = {
+      ...directDescriptor(),
+      result: { mode: 'src-json' },
+    }
+
+    expect(() => ctx.api.mount({ package: '@fixture/weak', descriptors: [weak] }))
+      .toThrow('has no strict codec')
+    expect(() => ctx.api.mount({
+      package: '@fixture/conflict',
+      descriptors: [{ ...directDescriptor(), namespace: 'mount' }],
+    })).toThrow('conflicts with the API service')
+    expect(ctx.typert.remotes.list()).toEqual([])
+  })
+
+  it('throws RPC failures with the structured error as its cause', async () => {
+    const rpcError = { code: 'internal' as const, message: 'host failed', details: {} }
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>().mockResolvedValue({ ok: false, error: rpcError }))
+    ctx.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
+
+    let failure: unknown
+    try {
+      await ctx.api.goals.create('agent-1', { objective: 'ship' })
+    } catch (error) {
+      failure = error
+    }
+    expect(failure).toBeInstanceOf(Error)
+    if (!(failure instanceof Error)) throw new Error('expected Client API invocation to fail')
+    expect(failure.message).toContain('internal: host failed')
+    expect(failure.cause).toBe(rpcError)
+  })
+})
diff --git a/packages/host/api-gateway/tests/gateway.spec.ts b/packages/host/api-gateway/tests/gateway.spec.ts
new file mode 100644
index 0000000000..8f7c144f5e
--- /dev/null
+++ b/packages/host/api-gateway/tests/gateway.spec.ts
@@ -0,0 +1,795 @@
+import { createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { describe, expect, it } from 'vitest'
+import { Context, Service, symbols } from 'cordis'
+import { z } from 'zod'
+import { apply as applyConnection, inject as connectionInject } from '@deepseek-ai/dsh-client-connection'
+import type { HttpServerService, WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import {
+  bindTypeRTGateway,
+  Remote,
+  RemoteContext,
+  type InvocationDescriptor,
+  type TypeRTContext,
+  type TypeRTLookup,
+  type TypeRTLookupProvider,
+} from '@deepseek-ai/dsh-type-meta'
+import TypertRegistry, { type TypertContribution } from '@deepseek-ai/dsh-typert-registry'
+import TypertGatewayService, { TypertGatewayError } from '@deepseek-ai/dsh-host-api-gateway'
+
+interface FixtureAgent {
+  readonly id: string
+}
+
+interface MarkedContext extends Context {
+  readonly fixtureScope?: string
+}
+
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTLookupMap {
+    gatewayFixture: TypeRTLookup<FixtureAgent, string>
+    gatewayFixtureAlias: TypeRTLookup<FixtureAgent, string>
+  }
+
+  interface TypeRTContextMap {
+    gatewayFixture: TypeRTContext<string>
+  }
+}
+
+const emptyModel: TypertContribution['model'] = {
+  services: [],
+  events: [],
+  objects: [],
+}
+
+class GoalService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+  readonly calls: string[] = []
+  nextResult: unknown = undefined
+  businessError: Error | undefined
+
+  constructor(ctx: Context) {
+    super(ctx, 'goals')
+  }
+
+  @Remote
+  create(agent: FixtureAgent, request: { readonly title: string }): unknown {
+    this.calls.push('create')
+    return {
+      agentId: agent.id,
+      title: request.title,
+      scope: (this.ctx as MarkedContext).fixtureScope ?? 'root',
+    }
+  }
+
+  @RemoteContext('gatewayFixture')
+  rename(request: { readonly title: string }): unknown {
+    this.calls.push('rename')
+    return { title: request.title, scope: (this.ctx as MarkedContext).fixtureScope ?? 'root' }
+  }
+
+  @Remote
+  passthrough(value: unknown): unknown {
+    this.calls.push('passthrough')
+    return this.nextResult === undefined ? value : this.nextResult
+  }
+
+  @Remote
+  fail(request: unknown): never {
+    void request
+    this.calls.push('fail')
+    throw this.businessError ?? new Error('fixture business failure')
+  }
+
+  strictOnly(request: { readonly title: string }): unknown {
+    this.calls.push('strictOnly')
+    return this.nextResult === undefined ? request : this.nextResult
+  }
+}
+
+type FakeRpcResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly error: { readonly code: 'internal'; readonly message: string; readonly details: object } }
+
+type FakeRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<FakeRpcResult>
+
+class FakeConnectionService extends Service {
+  channel: string | undefined
+  authority: string | undefined
+  handler: FakeRpcHandler | undefined
+
+  constructor(ctx: Context) {
+    super(ctx, 'connection')
+  }
+
+  get rpc() {
+    const owner = this.ctx
+    return {
+      handle: (channel: string, handler: FakeRpcHandler, options: { readonly authority: string }) =>
+        owner.effect(() => {
+          this.channel = channel
+          this.authority = options.authority
+          this.handler = handler
+          return () => {
+            this.channel = undefined
+            this.authority = undefined
+            this.handler = undefined
+          }
+        }),
+    }
+  }
+}
+
+function fakeHttpServer(routes: WebRoute[]): Pick<HttpServerService, 'register' | 'tapIndex' | 'port'> {
+  return {
+    register(route) {
+      if (routes.some(candidate => candidate.kind === route.kind && candidate.path === route.path)) {
+        throw new Error(`duplicate route ${route.path}`)
+      }
+      routes.push(route)
+      return () => { routes.splice(routes.indexOf(route), 1) }
+    },
+    tapIndex: () => () => {},
+    port: 0,
+  }
+}
+
+async function serveRoute(route: WebRoute): Promise<{ readonly origin: string; close(): Promise<void> }> {
+  const server = createServer((request, response) => {
+    void route.handler(request, response)
+  })
+  await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+  const address = server.address() as AddressInfo
+  return {
+    origin: `http://127.0.0.1:${String(address.port)}`,
+    close: () => new Promise<void>((resolve, reject) => {
+      server.close((error) => {
+        if (error === undefined || error === null) resolve()
+        else reject(error)
+      })
+    }),
+  }
+}
+
+class FirstSharedService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'firstShared', { namespace: 'shared' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'firstShared')
+  }
+
+  @Remote
+  run(value: string): string {
+    return value
+  }
+}
+
+class SecondSharedService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'secondShared', { namespace: 'shared' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'secondShared')
+  }
+
+  @Remote
+  run(value: string): string {
+    return value
+  }
+}
+
+class DefaultParameterService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'defaultParameter', { namespace: 'invalid-default' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'defaultParameter')
+  }
+
+  @Remote
+  run(value = 'fallback'): string {
+    return value
+  }
+}
+
+class DestructuredParameterService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'destructuredParameter', { namespace: 'invalid-destructure' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'destructuredParameter')
+  }
+
+  @Remote
+  run({ value }: { readonly value: string }): string {
+    return value
+  }
+}
+
+class RestParameterService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'restParameter', { namespace: 'invalid-rest' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'restParameter')
+  }
+
+  @Remote
+  run(...values: readonly unknown[]): string {
+    return values.map(String).join(',')
+  }
+}
+
+class WrongBindingService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'notWrongBinding', { namespace: 'wrong-binding' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'wrongBinding')
+  }
+
+  @Remote
+  run(value: string): string {
+    return value
+  }
+}
+
+describe('TypertGatewayService', () => {
+  it('invokes a strict direct method with schema decoding and a live lookup', async () => {
+    const { ctx, service } = await setup()
+    const agent = { id: 'agent-1' }
+    registerAgentLookup(ctx, agent)
+    registerStrict(ctx, [createDescriptor()])
+    const caller = ctx.extend({ fixtureScope: 'direct-caller' })
+
+    await expect(caller.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: '  ship  ' } },
+    })).resolves.toEqual({ agentId: 'agent-1', title: 'ship', scope: 'direct-caller' })
+    expect(service.calls).toEqual(['create'])
+  })
+
+  it('resolves strict Remote Context identity without adding a business argument', async () => {
+    const { ctx, service } = await setup()
+    const scoped = ctx.extend({ fixtureScope: 'agent-scope' })
+    ctx.typert.contexts.registerHost('gatewayFixture', contextProvider(scoped))
+    registerStrict(ctx, [renameDescriptor()])
+
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    })).resolves.toEqual({ title: 'land', scope: 'agent-scope' })
+    expect(service.calls).toEqual(['rename'])
+  })
+
+  it('derives SRC direct lookup and JSON parameters from marker and parameter names', async () => {
+    const { ctx } = await setup()
+    const agent = { id: 'agent-1' }
+    registerAgentLookup(ctx, agent)
+    const caller = ctx.extend({ fixtureScope: 'direct-src' })
+
+    await expect(caller.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    })).resolves.toEqual({ agentId: 'agent-1', title: 'ship', scope: 'direct-src' })
+  })
+
+  it('derives SRC Remote Context identity and preserves the scoped Proxy receiver', async () => {
+    const { ctx } = await setup()
+    const scoped = ctx.extend({ fixtureScope: 'agent-src' })
+    ctx.typert.contexts.registerHost('gatewayFixture', contextProvider(scoped))
+
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    })).resolves.toEqual({ title: 'land', scope: 'agent-src' })
+  })
+
+  it('re-reads Service and providers on every strict invocation', async () => {
+    const { ctx, serviceFiber } = await setup()
+    const agent = { id: 'agent-1' }
+    const disposeLookup = registerAgentLookup(ctx, agent)
+    registerStrict(ctx, [createDescriptor()])
+
+    await disposeLookup()
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'lookup-unavailable')
+
+    registerAgentLookup(ctx, agent)
+    await serviceFiber.dispose()
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'service-unavailable')
+  })
+
+  it('re-reads and contains Context providers', async () => {
+    const { ctx } = await setup()
+    const scoped = ctx.extend()
+    const dispose = ctx.typert.contexts.registerHost('gatewayFixture', contextProvider(scoped))
+    registerStrict(ctx, [renameDescriptor()])
+
+    await dispose()
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    }), 'context-unavailable')
+
+    ctx.typert.contexts.registerHost('gatewayFixture', {
+      ...contextProvider(scoped),
+      resolve: () => { throw new Error('provider failed') },
+    })
+    const error = await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    }), 'context-failed')
+    expect(error.cause).toEqual(new Error('provider failed'))
+  })
+
+  it('never downgrades an observed strict endpoint after definition disposal', async () => {
+    const { ctx } = await setup()
+    const dispose = registerStrict(ctx, [passthroughDescriptor()])
+    await dispose()
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: 'would pass through SRC' },
+    }), 'definition-unavailable')
+  })
+
+  it('seeds the no-downgrade guard from definitions present before Gateway startup', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    const dispose = registerStrict(ctx, [passthroughDescriptor()])
+    await ctx.plugin(TypertGatewayService)
+    await ctx.plugin(GoalService)
+    await dispose()
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: 'would pass through SRC' },
+    }), 'definition-unavailable')
+  })
+
+  it('retains the no-downgrade guard across Gateway Service reloads', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    const gatewayFiber = ctx.plugin(TypertGatewayService)
+    await gatewayFiber
+    await ctx.plugin(GoalService)
+    const dispose = registerStrict(ctx, [passthroughDescriptor()])
+    await dispose()
+
+    await gatewayFiber.dispose()
+    await ctx.plugin(TypertGatewayService)
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: 'would pass through SRC' },
+    }), 'definition-unavailable')
+  })
+
+  it('rejects ambiguous SRC endpoints independently of reflection order', async () => {
+    const ctx = await setupGateway()
+    await ctx.plugin(FirstSharedService)
+    await ctx.plugin(SecondSharedService)
+
+    const error = await expectCode(ctx.typertGateway.invoke({
+      namespace: 'shared',
+      method: 'run',
+      args: { value: 'ship' },
+    }), 'ambiguous-endpoint')
+    expect(error.message).toContain('firstShared, secondShared')
+  })
+
+  it('rejects SRC signatures that cannot map one wire field to each position', async () => {
+    const cases = [
+      { plugin: DefaultParameterService, namespace: 'invalid-default', args: { value: 'x' } },
+      { plugin: DestructuredParameterService, namespace: 'invalid-destructure', args: { value: { value: 'x' } } },
+      { plugin: RestParameterService, namespace: 'invalid-rest', args: { values: ['x'] } },
+    ] as const
+    for (const testCase of cases) {
+      const ctx = await setupGateway()
+      await ctx.plugin(testCase.plugin)
+      await expectCode(ctx.typertGateway.invoke({
+        namespace: testCase.namespace,
+        method: 'run',
+        args: testCase.args,
+      }), 'signature-invalid')
+    }
+  })
+
+  it('rejects a SRC parameter matching more than one lookup provider', async () => {
+    const { ctx } = await setup()
+    const provider = agentLookup({ id: 'agent-1' })
+    ctx.typert.lookups.register('gatewayFixture', provider)
+    ctx.typert.lookups.register('gatewayFixtureAlias', provider)
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'signature-invalid')
+  })
+
+  it('requires exact wire fields before invoking business code', async () => {
+    const { ctx, service } = await setup()
+    registerAgentLookup(ctx, { id: 'agent-1' })
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { request: { title: 'ship' } },
+    }), 'arguments-invalid')
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' }, optional: true },
+    }), 'arguments-invalid')
+    expect(service.calls).toEqual([])
+  })
+
+  it('distinguishes strict input and result validation failures', async () => {
+    const { ctx, service } = await setup()
+    registerStrict(ctx, [strictOnlyDescriptor()])
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'strictOnly',
+      args: { request: { title: 1 } },
+    }), 'input-invalid')
+
+    service.nextResult = { title: 1 }
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'strictOnly',
+      args: { request: { title: 'ship' } },
+    }), 'result-invalid')
+  })
+
+  it.each([
+    undefined,
+    Number.NaN,
+    Number.POSITIVE_INFINITY,
+    1n,
+    Symbol('value'),
+    () => 'value',
+    new Date(0),
+    new Map(),
+    [, 'sparse'],
+  ])('rejects non-JSON SRC input %#', async (value) => {
+    const { ctx } = await setup()
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value },
+    }), 'input-invalid')
+  })
+
+  it('rejects cyclic SRC input and non-JSON SRC results', async () => {
+    const { ctx, service } = await setup()
+    const cyclic: { self?: unknown } = {}
+    cyclic.self = cyclic
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: cyclic },
+    }), 'input-invalid')
+
+    service.nextResult = new Date(0)
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: null },
+    }), 'result-invalid')
+  })
+
+  it('validates strict provider identity against generated wire metadata', async () => {
+    const { ctx } = await setup()
+    ctx.typert.lookups.register('gatewayFixture', {
+      ...agentLookup({ id: 'agent-1' }),
+      wire: 'differentAgentId',
+    })
+    registerStrict(ctx, [createDescriptor()])
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'provider-mismatch')
+  })
+
+  it('validates binding identity and active method availability', async () => {
+    const ctx = await setupGateway()
+    await ctx.plugin(WrongBindingService)
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'wrong-binding',
+      method: 'run',
+      args: { value: 'ship' },
+    }), 'binding-invalid')
+
+    await ctx.plugin(GoalService)
+    registerStrict(ctx, [{ ...passthroughDescriptor(), method: 'missing' }])
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'missing',
+      args: { value: 'ship' },
+    }), 'method-unavailable')
+  })
+
+  it('preserves business exception identity after invocation begins', async () => {
+    const { ctx, service } = await setup()
+    const failure = new Error('business identity')
+    service.businessError = failure
+
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'fail',
+      args: { request: { reason: 'fixture' } },
+    })).rejects.toBe(failure)
+  })
+
+  it('reports an absent endpoint without retaining receiver state', async () => {
+    const { ctx } = await setup()
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'absent',
+      args: {},
+    }), 'invocation-unavailable')
+  })
+
+  it('mounts /api2 through an optional Connection and returns existing RPC results', async () => {
+    const ctx = new Context().extend({ fixtureScope: 'rpc-caller' })
+    await ctx.plugin(TypertRegistry)
+    await ctx.plugin(FakeConnectionService)
+    const gatewayFiber = ctx.plugin(TypertGatewayService)
+    await gatewayFiber
+    await ctx.plugin(GoalService)
+    const connection = rawConnection(ctx)
+    expect(connection).toMatchObject({ channel: '/api2', authority: 'trusted-host' })
+
+    registerAgentLookup(ctx, { id: 'agent-1' })
+    registerStrict(ctx, [createDescriptor()])
+    const signal = new AbortController().signal
+    const handler = connection.handler
+    if (handler === undefined) throw new Error('fixture Connection did not retain the /api2 handler')
+    await expect(handler('goals/create', {
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }, signal)).resolves.toEqual({
+      ok: true,
+      value: { agentId: 'agent-1', title: 'ship', scope: 'rpc-caller' },
+    })
+    const invalid = await handler('goals/create', { invalid: true }, signal)
+    expect(invalid).toMatchObject({
+      ok: false,
+      error: { code: 'internal' },
+    })
+    if (invalid.ok) throw new Error('invalid Remote payload unexpectedly succeeded')
+    expect(invalid.error.message).toMatch(/exactly one plain-object args field/)
+
+    await gatewayFiber.dispose()
+    expect(connection.handler).toBeUndefined()
+  })
+
+  it('dispatches a generated invocation through the real /api2 HTTP carrier', async () => {
+    const ctx = new Context().extend({ fixtureScope: 'http-caller' })
+    const routes: WebRoute[] = []
+    ctx.provide('httpServer', fakeHttpServer(routes) as HttpServerService)
+    const connectionFiber = ctx.plugin({ inject: [...connectionInject], apply: applyConnection })
+    await connectionFiber
+    await ctx.plugin(TypertRegistry)
+    const gatewayFiber = ctx.plugin(TypertGatewayService)
+    await gatewayFiber
+    const goalFiber = ctx.plugin(GoalService)
+    await goalFiber
+    const removeLookup = registerAgentLookup(ctx, { id: 'agent-1' })
+    const removeStrict = registerStrict(ctx, [createDescriptor()])
+    expect(routes).toHaveLength(1)
+    const server = await serveRoute(routes[0]!)
+
+    try {
+      const response = await fetch(`${server.origin}/api2/goals/create`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          type: 'client-request',
+          rpcId: 'rpc-http',
+          method: 'goals/create',
+          payload: { args: { agentId: 'agent-1', request: { title: '  ship  ' } } },
+        }),
+      })
+      expect(response.status).toBe(200)
+      await expect(response.json()).resolves.toEqual({
+        type: 'server-response',
+        rpcId: 'rpc-http',
+        result: {
+          ok: true,
+          value: { agentId: 'agent-1', title: 'ship', scope: 'http-caller' },
+        },
+      })
+    } finally {
+      await server.close()
+      await removeStrict()
+      await removeLookup()
+      await goalFiber.dispose()
+      await gatewayFiber.dispose()
+      await connectionFiber.dispose()
+    }
+    expect(routes).toHaveLength(0)
+  })
+})
+
+async function setup(): Promise<{
+  readonly ctx: Context
+  readonly service: GoalService
+  readonly serviceFiber: ReturnType<Context['plugin']>
+}> {
+  const ctx = await setupGateway()
+  const serviceFiber = ctx.plugin(GoalService)
+  await serviceFiber
+  return { ctx, service: rawGoalService(ctx), serviceFiber }
+}
+
+async function setupGateway(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
+  await ctx.plugin(TypertGatewayService)
+  return ctx
+}
+
+function rawGoalService(ctx: Context): GoalService {
+  const receiver = ctx.get('goals') as unknown as GoalService & { [symbols.original]?: GoalService }
+  return receiver[symbols.original] ?? receiver
+}
+
+function rawConnection(ctx: Context): FakeConnectionService {
+  const receiver = ctx.get('connection') as unknown as FakeConnectionService & {
+    [symbols.original]?: FakeConnectionService
+  }
+  return receiver[symbols.original] ?? receiver
+}
+
+function registerStrict(ctx: Context, descriptors: readonly InvocationDescriptor[]): () => Promise<void> {
+  return ctx.typert.register({
+    package: '@fixture/gateway',
+    face: 'host',
+    schemas: [],
+    model: emptyModel,
+    invocations: descriptors,
+  })
+}
+
+function registerAgentLookup(ctx: Context, agent: FixtureAgent): () => Promise<void> {
+  return ctx.typert.lookups.register('gatewayFixture', agentLookup(agent))
+}
+
+function agentLookup(agent: FixtureAgent): TypeRTLookupProvider<FixtureAgent, string> {
+  return {
+    parameter: 'agent',
+    wire: 'agentId',
+    hostTypeSymbol: '@fixture/domain#Agent',
+    wireTypeSymbol: '@fixture/domain#AgentId',
+    resolve: id => id === agent.id ? agent : undefined,
+  }
+}
+
+function contextProvider(context: Context) {
+  return {
+    wire: 'agentId',
+    wireTypeSymbol: '@fixture/domain#AgentId',
+    resolve: (id: string) => id === 'agent-1' ? context : undefined,
+  }
+}
+
+function strictCodec(typeSymbol: string, schema: z.ZodType): InvocationDescriptor['result'] {
+  return { mode: 'strict', typeSymbol, schema }
+}
+
+function createDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/gateway#goals/create',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'create',
+    invocation: { kind: 'direct' },
+    parameters: [
+      {
+        name: 'agent',
+        wire: 'agentId',
+        source: 'lookup',
+        lookup: 'gatewayFixture',
+        codec: strictCodec('@fixture/domain#AgentId', z.string()),
+      },
+      {
+        name: 'request',
+        wire: 'request',
+        source: 'json',
+        codec: strictCodec('@fixture/gateway#CreateRequest', z.object({
+          title: z.string().transform(value => value.trim()),
+        })),
+      },
+    ],
+    result: strictCodec('@fixture/gateway#CreateResult', z.object({
+      agentId: z.string(),
+      title: z.string(),
+      scope: z.string(),
+    })),
+  }
+}
+
+function renameDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/gateway#goals/rename',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'rename',
+    invocation: {
+      kind: 'context',
+      context: 'gatewayFixture',
+      wire: 'agentId',
+      codec: strictCodec('@fixture/domain#AgentId', z.string()),
+    },
+    parameters: [{
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: strictCodec('@fixture/gateway#RenameRequest', z.object({ title: z.string() })),
+    }],
+    result: strictCodec('@fixture/gateway#RenameResult', z.object({
+      title: z.string(),
+      scope: z.string(),
+    })),
+  }
+}
+
+function passthroughDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/gateway#goals/passthrough',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'passthrough',
+    invocation: { kind: 'direct' },
+    parameters: [{
+      name: 'value',
+      wire: 'value',
+      source: 'json',
+      codec: { mode: 'src-json' },
+    }],
+    result: { mode: 'src-json' },
+  }
+}
+
+function strictOnlyDescriptor(): InvocationDescriptor {
+  const value = strictCodec('@fixture/gateway#StrictValue', z.object({ title: z.string() }))
+  return {
+    id: '@fixture/gateway#goals/strictOnly',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'strictOnly',
+    invocation: { kind: 'direct' },
+    parameters: [{ name: 'request', wire: 'request', source: 'json', codec: value }],
+    result: value,
+  }
+}
+
+async function expectCode(
+  promise: Promise<unknown>,
+  code: TypertGatewayError['code'],
+): Promise<TypertGatewayError> {
+  try {
+    await promise
+  } catch (error) {
+    expect(error).toBeInstanceOf(TypertGatewayError)
+    expect(error).toMatchObject({ code })
+    return error as TypertGatewayError
+  }
+  throw new Error(`expected TypertGatewayError ${code}`)
+}
diff --git a/packages/host/api-gateway/tsconfig.json b/packages/host/api-gateway/tsconfig.json
new file mode 100644
index 0000000000..fea39663f7
--- /dev/null
+++ b/packages/host/api-gateway/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../client/connection"
+    },
+    {
+      "path": "../../typert/type-meta"
+    }
+  ]
+}
diff --git a/packages/host/api-gateway/tsdown.config.ts b/packages/host/api-gateway/tsdown.config.ts
new file mode 100644
index 0000000000..1f95a1f2c5
--- /dev/null
+++ b/packages/host/api-gateway/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../../client/tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-host-api-gateway', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index c9dea52f98..cb83c5328d 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -72,6 +72,11 @@ export type {
 // ---- Errors and ids ----
 export { RpcId, transportError } from './rpc.ts'
 export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts'
+export {
+  clientRequestSchema,
+  serverRequestSchema,
+  serverResponseSchema,
+} from './rpc.schema.ts'
 
 // ---- Fixed session-search product bounds ----
 export {
diff --git a/packages/typert/generator/package.json b/packages/typert/generator/package.json
index 3e9d8f7f61..5ffb933214 100644
--- a/packages/typert/generator/package.json
+++ b/packages/typert/generator/package.json
@@ -30,6 +30,7 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
+    "@jridgewell/gen-mapping": "^0.3.13",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index 005b8e2157..5757d7cef5 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -15,6 +15,8 @@ import type {
   EnumMemberModel,
   ExportModel,
   FaceModel,
+  InvocationModel,
+  InvocationParameterModel,
   JsDocTagModel,
   KeywordTypeName,
   MemberBase,
@@ -23,6 +25,8 @@ import type {
   ObjectModel,
   PackageModel,
   ParameterModel,
+  RemoteBoundaryModel,
+  RemoteTypeImportModel,
   SchemaModel,
   ServiceModel,
   SignatureModel,
@@ -122,6 +126,25 @@ interface ModuleIdentity {
   readonly subpath: string
 }
 
+interface StaticLookupDeclaration {
+  readonly key: string
+  readonly hostSymbol: SymbolId
+  readonly wireType: ts.TypeNode
+  readonly site: ts.Node
+}
+
+interface StaticContextDeclaration {
+  readonly key: string
+  readonly wireType: ts.TypeNode
+  readonly site: ts.Node
+}
+
+interface GatewayBinding {
+  readonly service: string
+  readonly namespace: string
+  readonly site: ts.PropertyDeclaration
+}
+
 type ReferenceSite = ts.TypeReferenceNode | ts.ExpressionWithTypeArguments | ts.ImportTypeNode
 
 const EMPTY_DOCUMENTATION: DocumentationModel = { tags: [] }
@@ -453,15 +476,11 @@ export class WorkspaceAnalyzer {
           config: this.caches.config(configPath),
           manifest,
         }
-        const packagePath = slash(relative(this.options.root, packageRoot))
-        const clientPackage = packagePath === 'packages/client' || packagePath.startsWith('packages/client/')
-        if (clientPackage && isDualFacePackage(manifest)) {
+        if (isDualFacePackage(manifest)) {
           registrations.push({ ...registration, face: 'host', exportSubpaths: hostExportSubpaths(manifest) })
           registrations.push({ ...registration, face: 'client', exportSubpaths: clientExportSubpaths(manifest) })
-        } else if (clientPackage) {
-          registrations.push({ ...registration, face: 'client' })
         } else {
-          registrations.push({ ...registration, face: 'host' })
+          registrations.push(registration)
         }
       }
     }
@@ -480,6 +499,7 @@ export class WorkspaceAnalyzer {
         && subpath !== './package.json'
         && subpath !== './typert'
         && subpath !== './client/typert'
+        && subpath !== './remote'
         && !target.endsWith('.json'))
       .map(([, target]) => sourcePathForExport(registration.root, target))
       .filter(existsSync)
@@ -578,6 +598,8 @@ class FaceAnalyzer {
   private readonly nodes = new Map<TypeNodeId, TypeNodeModel>()
   private readonly exportsByPackage = new Map<string, ExportRecord[]>()
   private readonly nodeOrdinals = new Map<string, number>()
+  private staticLookups: readonly StaticLookupDeclaration[] | undefined
+  private staticContexts: ReadonlyMap<string, StaticContextDeclaration> | undefined
 
   constructor(options: FaceAnalyzerOptions) {
     this.root = options.root
@@ -601,6 +623,7 @@ class FaceAnalyzer {
     const packages = this.registrations
       .map(registration => this.analyzePackage(registration))
       .filter(hasPackageSurface)
+    this.validateInvocationIdentity(packages)
     return {
       face: this.face,
       packages,
@@ -634,6 +657,7 @@ class FaceAnalyzer {
         }
       }
     }
+    const explicitServices = this.collectExplicitServices(records)
 
     const objects: ObjectModel[] = []
     const schemas: SchemaModel[] = []
@@ -672,10 +696,14 @@ class FaceAnalyzer {
       root: slash(relative(this.root, registration.root)),
       exports: records.map(record => record.model)
         .sort((left, right) => left.subpath.localeCompare(right.subpath) || left.name.localeCompare(right.name)),
-      services: uniqueBy(services, service => service.key).sort((left, right) => left.key.localeCompare(right.key)),
+      services: uniqueBy([...explicitServices, ...services], service => service.key)
+        .sort((left, right) => left.key.localeCompare(right.key)),
       events: uniqueBy(events, event => event.name).sort((left, right) => left.name.localeCompare(right.name)),
       objects: objects.sort((left, right) => left.export.name.localeCompare(right.export.name)),
       schemas: schemas.sort((left, right) => left.export.name.localeCompare(right.export.name)),
+      invocations: this.face === 'host'
+        ? this.collectInvocations(registration, reachable).sort((left, right) => left.id.localeCompare(right.id))
+        : [],
     }
   }
 
@@ -686,7 +714,7 @@ class FaceAnalyzer {
     const records: ExportRecord[] = []
     for (const [subpath, target] of targets) {
       if (target.includes('*') || subpath === './package.json'
-        || subpath === './typert' || subpath === './client/typert'
+        || subpath === './typert' || subpath === './client/typert' || subpath === './remote'
         // Data exports (bundle patch lists, JSON manifests) carry no TypeScript API.
         || target.endsWith('.json') || target.endsWith('.yml') || target.endsWith('.yaml')) continue
       const sourcePath = sourcePathForExport(registration.root, target)
@@ -849,6 +877,740 @@ class FaceAnalyzer {
     return result
   }
 
+  private collectExplicitServices(records: readonly ExportRecord[]): ServiceModel[] {
+    const result: ServiceModel[] = []
+    const seen = new Set<SymbolId>()
+    for (const record of records) {
+      const tag = typertServiceTag(record.declaration)
+      if (tag === undefined) continue
+      const words = (ts.getTextOfJSDocComment(tag.comment) ?? '').trim().split(/\s+/)
+      if (words.length !== 2 || !isRemoteSegment(words[1] ?? '')) {
+        this.fail(tag, '@typert service requires exactly one nonempty Cordis service key without "/"')
+      }
+      if (!ts.isClassDeclaration(record.declaration)) {
+        this.fail(record.declaration, '@typert service requires an exported class')
+      }
+      const symbol = this.resolveSymbol(record.symbol)
+      const symbolId = this.symbolId(symbol)
+      if (seen.has(symbolId)) continue
+      seen.add(symbolId)
+      const model = this.ensureDeclaration(symbol, record.declaration)
+      result.push({
+        ...documentationOf(record.declaration),
+        key: words[1] as string,
+        symbol: symbolId,
+        export: record.model,
+        members: model.members.filter(exposableMember).map(member => member.id),
+        location: this.location(record.declaration),
+      })
+    }
+    return result
+  }
+
+  private collectInvocations(
+    registration: PackageRegistration,
+    reachable: readonly ts.SourceFile[],
+  ): InvocationModel[] {
+    const result: InvocationModel[] = []
+    for (const sourceFile of reachable) {
+      for (const statement of sourceFile.statements) {
+        if (!ts.isClassDeclaration(statement)) continue
+        const marked = statement.members.flatMap((member) => {
+          const invocation = this.remoteMarker(member)
+          if (invocation === undefined) return []
+          if (!ts.isMethodDeclaration(member)) {
+            this.fail(member, 'Remote decorators require a public instance method')
+          }
+          return [{ method: member, invocation }]
+        })
+        const first = marked[0]
+        if (first === undefined) continue
+        const binding = this.gatewayBinding(statement)
+        if (binding === undefined) {
+          this.fail(first.method, 'Remote methods require readonly typertGateway = bindTypeRTGateway(this, serviceKey)')
+        }
+        for (const { method, invocation } of marked) {
+          result.push(this.invocationModel(registration, binding, method, invocation))
+        }
+      }
+    }
+    return result
+  }
+
+  private invocationModel(
+    registration: PackageRegistration,
+    binding: GatewayBinding,
+    method: ts.MethodDeclaration,
+    invocation:
+      | { readonly kind: 'direct'; readonly exportName?: string }
+      | { readonly kind: 'context'; readonly context: string; readonly exportName?: string },
+  ): InvocationModel {
+    if (visibilityOf(method) !== 'public' || hasModifier(method, ts.SyntaxKind.StaticKeyword)) {
+      this.fail(method, 'Remote decorators require a public instance method')
+    }
+    if (hasModifier(method, ts.SyntaxKind.AbstractKeyword) || method.body === undefined) {
+      this.fail(method, 'Remote methods must have a concrete implementation')
+    }
+    if (!ts.isIdentifier(method.name)) {
+      this.fail(method, 'Remote method names must be identifiers')
+    }
+    if ((method.typeParameters?.length ?? 0) > 0) {
+      this.fail(method, 'generic Remote methods are not supported')
+    }
+    const methodName = method.name.text
+    const exportedMethod = invocation.exportName ?? methodName
+
+    const lookups = this.lookupDeclarations()
+    const lookupByHost = new Map(lookups.map(lookup => [lookup.hostSymbol, lookup]))
+    const parameters: InvocationParameterModel[] = []
+    const wires = new Set<string>()
+    for (const parameter of method.parameters) {
+      if (!ts.isIdentifier(parameter.name)) {
+        this.fail(parameter, 'Remote parameters must use identifier bindings')
+      }
+      if (parameter.dotDotDotToken !== undefined) this.fail(parameter, 'Remote parameters cannot be rest parameters')
+      if (parameter.initializer !== undefined) this.fail(parameter, 'Remote parameters cannot have default values')
+      if (parameter.questionToken !== undefined) this.fail(parameter, 'Remote parameters cannot be optional')
+      if (parameter.name.text === 'this') this.fail(parameter, 'Remote methods cannot declare an explicit this parameter')
+      const authoredType = this.requiredType(parameter, parameter.type, 'parameter')
+      const hostSymbol = this.symbolAtType(authoredType)
+      const lookup = hostSymbol === undefined ? undefined : lookupByHost.get(this.symbolId(hostSymbol))
+      let modeled: InvocationParameterModel
+      if (lookup !== undefined) {
+        if (parameter.name.text !== lookup.key) {
+          this.fail(parameter, `lookup parameter for ${lookup.key} must also be named ${lookup.key}`)
+        }
+        const boundary = this.remoteBoundary(
+          lookup.wireType,
+          `${registration.name}#${binding.namespace}/${exportedMethod}:${lookup.key}Id`,
+          true,
+        )
+        modeled = {
+          name: parameter.name.text,
+          wire: `${lookup.key}Id`,
+          source: 'lookup',
+          lookup: lookup.key,
+          boundary,
+        }
+      } else {
+        if (hostSymbol !== undefined && this.isWorkspaceClass(hostSymbol)) {
+          this.fail(parameter, `non-JSON class parameter ${hostSymbol.name} requires a TypeRTLookupMap entry`)
+        }
+        modeled = {
+          name: parameter.name.text,
+          wire: parameter.name.text,
+          source: 'json',
+          boundary: this.remoteBoundary(
+            authoredType,
+            `${registration.name}#${binding.namespace}/${exportedMethod}:${parameter.name.text}`,
+            false,
+          ),
+        }
+      }
+      if (wires.has(modeled.wire)) this.fail(parameter, `duplicate Remote wire field ${modeled.wire}`)
+      wires.add(modeled.wire)
+      parameters.push(modeled)
+    }
+
+    let receiver: InvocationModel['invocation'] = { kind: 'direct' }
+    if (invocation.kind === 'context') {
+      const context = this.contextDeclarations().get(invocation.context)
+      if (context === undefined) {
+        this.fail(method, `Remote Context ${invocation.context} has no TypeRTContextMap entry`)
+      }
+      const wire = `${invocation.context}Id`
+      if (wires.has(wire)) this.fail(method, `Remote Context wire field ${wire} conflicts with a method parameter`)
+      receiver = {
+        kind: 'context',
+        context: invocation.context,
+        wire,
+        boundary: this.remoteBoundary(
+          context.wireType,
+          `${registration.name}#${binding.namespace}/${exportedMethod}:${wire}`,
+          true,
+        ),
+      }
+    }
+
+    let scope: InvocationModel['scope']
+    if (invocation.kind === 'direct') {
+      const lookupParameters = parameters.filter(parameter => parameter.source === 'lookup')
+      const parameter = lookupParameters.length === 1 ? lookupParameters[0] : undefined
+      const context = parameter?.lookup === undefined
+        ? undefined
+        : this.contextDeclarations().get(parameter.lookup)
+      if (parameter !== undefined && context !== undefined) {
+        const contextBoundary = this.remoteBoundary(
+          context.wireType,
+          `${registration.name}#${binding.namespace}/${exportedMethod}:scope:${context.key}`,
+          true,
+        )
+        if (contextBoundary.typeSymbol !== parameter.boundary.typeSymbol) {
+          this.fail(
+            method,
+            `Remote scope ${context.key} wire type ${contextBoundary.typeSymbol} does not match lookup wire type ${parameter.boundary.typeSymbol}`,
+          )
+        }
+        scope = { context: context.key, wire: parameter.wire }
+      }
+    }
+
+    const resultType = this.remoteResultType(method)
+    return {
+      id: `${registration.name}#${binding.namespace}/${exportedMethod}`,
+      service: binding.service,
+      namespace: binding.namespace,
+      method: exportedMethod,
+      ...(exportedMethod === methodName ? {} : { implementation: methodName }),
+      invocation: receiver,
+      ...(scope === undefined ? {} : { scope }),
+      parameters,
+      result: this.remoteBoundary(
+        resultType,
+        `${registration.name}#${binding.namespace}/${exportedMethod}:result`,
+        false,
+      ),
+      location: this.location(method.name),
+    }
+  }
+
+  private gatewayBinding(declaration: ts.ClassDeclaration): GatewayBinding | undefined {
+    const candidates = declaration.members.filter((member): member is ts.PropertyDeclaration =>
+      ts.isPropertyDeclaration(member) && memberName(member.name) === 'typertGateway')
+    const [property, duplicate] = candidates
+    if (property === undefined) return undefined
+    if (duplicate !== undefined) this.fail(duplicate, 'Service has more than one typertGateway field')
+    if (visibilityOf(property) !== 'public'
+      || hasModifier(property, ts.SyntaxKind.StaticKeyword)
+      || !hasModifier(property, ts.SyntaxKind.ReadonlyKeyword)) {
+      this.fail(property, 'typertGateway must be a public readonly instance field')
+    }
+    if (property.initializer === undefined
+      || !ts.isCallExpression(property.initializer)
+      || !this.isTypeMetaSymbol(property.initializer.expression, 'bindTypeRTGateway')) {
+      this.fail(property, 'typertGateway must call bindTypeRTGateway()')
+    }
+    const call = property.initializer
+    if (call.arguments.length < 2 || call.arguments.length > 3) {
+      this.fail(call, 'bindTypeRTGateway() requires this, service key, and an optional options object')
+    }
+    if (call.arguments[0]?.kind !== ts.SyntaxKind.ThisKeyword) {
+      this.fail(call.arguments[0] ?? call, 'bindTypeRTGateway() first argument must be this')
+    }
+    const serviceArgument = call.arguments[1]
+    if (serviceArgument === undefined) this.fail(call, 'bindTypeRTGateway() service key must be a string literal')
+    const service = stringLiteralValue(serviceArgument)
+    if (service === undefined) this.fail(serviceArgument, 'bindTypeRTGateway() service key must be a string literal')
+    let namespace = service
+    const options = call.arguments[2]
+    if (options !== undefined) {
+      if (!ts.isObjectLiteralExpression(options)) {
+        this.fail(options, 'bindTypeRTGateway() options must be an object literal')
+      }
+      for (const propertyOption of options.properties) {
+        if (!ts.isPropertyAssignment(propertyOption)
+          || memberName(propertyOption.name) !== 'namespace') {
+          this.fail(propertyOption, 'bindTypeRTGateway() only supports a namespace option')
+        }
+        const value = stringLiteralValue(propertyOption.initializer)
+        if (value === undefined) this.fail(propertyOption.initializer, 'Gateway namespace must be a string literal')
+        namespace = value
+      }
+    }
+    if (!isRemoteSegment(service)) this.fail(serviceArgument, 'Gateway service key must be nonempty and must not contain "/"')
+    if (!isRemoteSegment(namespace)) this.fail(options ?? call, 'Gateway namespace must be nonempty and must not contain "/"')
+    return { service, namespace, site: property }
+  }
+
+  private remoteMarker(
+    member: ts.ClassElement,
+  ):
+    | { readonly kind: 'direct'; readonly exportName?: string }
+    | { readonly kind: 'context'; readonly context: string; readonly exportName?: string }
+    | undefined {
+    let found:
+      | { readonly kind: 'direct'; readonly exportName?: string }
+      | { readonly kind: 'context'; readonly context: string; readonly exportName?: string }
+      | undefined
+    for (const decorator of ts.canHaveDecorators(member) ? ts.getDecorators(member) ?? [] : []) {
+      const expression = decorator.expression
+      let marker: typeof found
+      if (this.isTypeMetaSymbol(expression, 'Remote')) {
+        marker = { kind: 'direct' }
+      } else if (ts.isCallExpression(expression)
+        && this.isTypeMetaSymbol(expression.expression, 'Remote')) {
+        if (expression.arguments.length !== 1) this.fail(expression, 'Remote() requires one exported method name')
+        const exportName = stringLiteralValue(expression.arguments[0])
+        if (exportName === undefined || !isRemoteSegment(exportName)) {
+          this.fail(expression.arguments[0] ?? expression, 'Remote() name must be a nonempty string literal without "/"')
+        }
+        marker = { kind: 'direct', exportName }
+      } else if (ts.isCallExpression(expression)
+        && this.isTypeMetaSymbol(expression.expression, 'RemoteContext')) {
+        if (expression.arguments.length < 1 || expression.arguments.length > 2) {
+          this.fail(expression, 'RemoteContext() requires a Context key and optional exported method name')
+        }
+        const context = stringLiteralValue(expression.arguments[0])
+        if (context === undefined || !isRemoteSegment(context)) {
+          this.fail(expression.arguments[0] ?? expression, 'RemoteContext() key must be a nonempty string literal without "/"')
+        }
+        const exportArgument = expression.arguments[1]
+        const exportName = exportArgument === undefined ? undefined : stringLiteralValue(exportArgument)
+        if (exportArgument !== undefined && (exportName === undefined || !isRemoteSegment(exportName))) {
+          this.fail(exportArgument, 'RemoteContext() name must be a nonempty string literal without "/"')
+        }
+        marker = { kind: 'context', context, ...exportName === undefined ? {} : { exportName } }
+      } else {
+        continue
+      }
+      if (found !== undefined) this.fail(decorator, 'a method can have only one Remote invocation decorator')
+      found = marker
+    }
+    return found
+  }
+
+  private remoteResultType(method: ts.MethodDeclaration): ts.TypeNode {
+    const authored = this.requiredType(method, method.type, 'return')
+    if (!ts.isTypeReferenceNode(authored)) return authored
+    const symbol = this.checker.getSymbolAtLocation(authored.typeName)
+    const resolved = symbol === undefined ? undefined : this.resolveSymbol(symbol)
+    const resultType = authored.typeArguments?.[0]
+    if (resolved?.name !== 'Promise' || resultType === undefined || authored.typeArguments?.length !== 1) return authored
+    const declaration = preferredDeclaration(resolved)
+    if (declaration === undefined || !isStandardLibraryFile(declaration.getSourceFile().fileName)) return authored
+    return resultType
+  }
+
+  private lookupDeclarations(): readonly StaticLookupDeclaration[] {
+    if (this.staticLookups !== undefined) return this.staticLookups
+    const byKey = new Map<string, StaticLookupDeclaration>()
+    const byHost = new Map<SymbolId, StaticLookupDeclaration>()
+    for (const declaration of this.typeMetaMapMembers('TypeRTLookupMap')) {
+      if (!ts.isPropertySignature(declaration) || declaration.type === undefined) {
+        this.fail(declaration, 'TypeRTLookupMap entries must be required properties')
+      }
+      const key = memberName(declaration.name)
+      if (!isRemoteSegment(key)) this.fail(declaration.name, 'TypeRTLookupMap key must be nonempty and must not contain "/"')
+      if (!ts.isTypeReferenceNode(declaration.type)
+        || !this.isTypeMetaSymbol(declaration.type.typeName, 'TypeRTLookup')
+        || declaration.type.typeArguments?.length !== 2) {
+        this.fail(declaration.type, 'TypeRTLookupMap values must be TypeRTLookup<Host, Wire>')
+      }
+      const hostType = declaration.type.typeArguments[0]
+      const wireType = declaration.type.typeArguments[1]
+      if (hostType === undefined || wireType === undefined) {
+        this.fail(declaration.type, 'TypeRTLookupMap values must be TypeRTLookup<Host, Wire>')
+      }
+      const host = this.symbolAtType(hostType)
+      if (host === undefined) this.fail(hostType, 'TypeRTLookup Host must be a named type')
+      const entry: StaticLookupDeclaration = {
+        key,
+        hostSymbol: this.symbolId(host),
+        wireType,
+        site: declaration,
+      }
+      if (byKey.has(key)) this.fail(declaration, `duplicate TypeRTLookupMap key ${key}`)
+      if (byHost.has(entry.hostSymbol)) this.fail(declaration, `Host type ${host.name} has more than one TypeRT lookup`)
+      byKey.set(key, entry)
+      byHost.set(entry.hostSymbol, entry)
+    }
+    this.staticLookups = [...byKey.values()]
+    return this.staticLookups
+  }
+
+  private contextDeclarations(): ReadonlyMap<string, StaticContextDeclaration> {
+    if (this.staticContexts !== undefined) return this.staticContexts
+    const result = new Map<string, StaticContextDeclaration>()
+    for (const declaration of this.typeMetaMapMembers('TypeRTContextMap')) {
+      if (!ts.isPropertySignature(declaration) || declaration.type === undefined) {
+        this.fail(declaration, 'TypeRTContextMap entries must be required properties')
+      }
+      const key = memberName(declaration.name)
+      if (!isRemoteSegment(key)) this.fail(declaration.name, 'TypeRTContextMap key must be nonempty and must not contain "/"')
+      if (!ts.isTypeReferenceNode(declaration.type)
+        || !this.isTypeMetaSymbol(declaration.type.typeName, 'TypeRTContext')
+        || declaration.type.typeArguments?.length !== 1) {
+        this.fail(declaration.type, 'TypeRTContextMap values must be TypeRTContext<Wire>')
+      }
+      if (result.has(key)) this.fail(declaration, `duplicate TypeRTContextMap key ${key}`)
+      const wireType = declaration.type.typeArguments[0]
+      if (wireType === undefined) this.fail(declaration.type, 'TypeRTContextMap values must be TypeRTContext<Wire>')
+      result.set(key, {
+        key,
+        wireType,
+        site: declaration,
+      })
+    }
+    this.staticContexts = result
+    return result
+  }
+
+  private typeMetaMapMembers(name: 'TypeRTLookupMap' | 'TypeRTContextMap'): ts.TypeElement[] {
+    const result: ts.TypeElement[] = []
+    for (const sourceFile of this.program.getSourceFiles()) {
+      for (const statement of sourceFile.statements) {
+        if (!ts.isModuleDeclaration(statement)
+          || !ts.isStringLiteral(statement.name)
+          || statement.name.text !== '@deepseek-ai/dsh-type-meta'
+          || statement.body === undefined
+          || !ts.isModuleBlock(statement.body)) continue
+        for (const nested of statement.body.statements) {
+          if (ts.isInterfaceDeclaration(nested) && nested.name.text === name) result.push(...nested.members)
+        }
+      }
+    }
+    return result
+  }
+
+  private remoteBoundary(
+    authoredType: ts.TypeNode,
+    fallbackTypeSymbol: string,
+    requireNamed: boolean,
+  ): RemoteBoundaryModel {
+    const type = this.convertType(authoredType)
+    const codecType = this.resolvedRemoteCodecType(authoredType)
+    const rootSymbol = this.namedWorkspaceType(authoredType)
+    if (rootSymbol !== undefined) {
+      const imported = this.publicRemoteType(rootSymbol, authoredType)
+      return {
+        type,
+        codecType,
+        typeSymbol: `${imported.specifier}#${imported.name}`,
+        imports: [imported],
+      }
+    }
+    if (requireNamed) this.fail(authoredType, 'lookup and Context wire types must be named public types')
+    const imports = new Map<SymbolId, RemoteTypeImportModel>()
+    const visit = (node: ts.Node): void => {
+      if ((ts.isTypeReferenceNode(node) || ts.isImportTypeNode(node))) {
+        const symbol = ts.isTypeReferenceNode(node)
+          ? this.checker.getSymbolAtLocation(node.typeName)
+          : node.qualifier === undefined ? undefined : this.checker.getSymbolAtLocation(node.qualifier)
+        if (symbol !== undefined) {
+          const resolved = this.resolveSymbol(symbol)
+          const declaration = preferredDeclaration(resolved)
+          if (declaration !== undefined
+            && !isStandardLibraryFile(declaration.getSourceFile().fileName)
+            && this.registrationForFile(declaration.getSourceFile().fileName) !== undefined) {
+            const imported = this.publicRemoteType(resolved, node)
+            imports.set(imported.symbol, imported)
+            return
+          }
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(authoredType)
+    return {
+      type,
+      codecType,
+      typeSymbol: fallbackTypeSymbol,
+      imports: [...imports.values()].sort((left, right) =>
+        left.specifier.localeCompare(right.specifier) || left.name.localeCompare(right.name)),
+    }
+  }
+
+  /**
+   * Project one authored Remote boundary through the complete face Program.
+   * Consumer declarations retain the authored alias, while codecs use this
+   * concrete graph so declaration-merged mapped and conditional types are
+   * validated without teaching the compiler-independent emitter TypeScript's
+   * type evaluator.
+   */
+  private resolvedRemoteCodecType(authoredType: ts.TypeNode): TypeNodeId {
+    const completed = new Map<ts.Type, TypeNodeId>()
+    const active = new Map<ts.Type, TypeNodeId>()
+    const recursiveDeclarations = new Map<ts.Type, SymbolId>()
+    const convert = (type: ts.Type): TypeNodeId => {
+      const cached = completed.get(type)
+      if (cached !== undefined) return cached
+      const activeId = active.get(type)
+      if (activeId !== undefined) {
+        if (this.checker.isArrayType(type) || this.checker.isArrayLikeType(type)) {
+          const element = this.checker.getIndexTypeOfType(type, ts.IndexKind.Number)
+          const elementId = element === undefined ? undefined : active.get(element)
+          if (element !== undefined && elementId !== undefined) {
+            return this.addNode(authoredType, {
+              kind: 'array',
+              element: this.resolvedCycleReference(
+                element,
+                authoredType,
+                elementId,
+                recursiveDeclarations,
+              ),
+            })
+          }
+        }
+        return this.resolvedCycleReference(type, authoredType, activeId, recursiveDeclarations)
+      }
+      const id = this.allocateNodeId(authoredType)
+      active.set(type, id)
+      try {
+        const add = (model: TypeNodeInput): TypeNodeId => {
+          this.nodes.set(id, { id, ...model })
+          completed.set(type, id)
+          return id
+        }
+        const flags = type.flags
+        if ((flags & ts.TypeFlags.Any) !== 0) return add({ kind: 'keyword', name: 'any' })
+        if ((flags & ts.TypeFlags.Unknown) !== 0) return add({ kind: 'keyword', name: 'unknown' })
+        if ((flags & ts.TypeFlags.Never) !== 0) return add({ kind: 'keyword', name: 'never' })
+        if ((flags & ts.TypeFlags.String) !== 0) return add({ kind: 'keyword', name: 'string' })
+        if ((flags & ts.TypeFlags.Number) !== 0) return add({ kind: 'keyword', name: 'number' })
+        if ((flags & ts.TypeFlags.BigInt) !== 0) return add({ kind: 'keyword', name: 'bigint' })
+        if ((flags & ts.TypeFlags.Boolean) !== 0) return add({ kind: 'keyword', name: 'boolean' })
+        if ((flags & ts.TypeFlags.ESSymbol) !== 0) return add({ kind: 'keyword', name: 'symbol' })
+        if ((flags & ts.TypeFlags.Undefined) !== 0) return add({ kind: 'keyword', name: 'undefined' })
+        if ((flags & ts.TypeFlags.Void) !== 0) return add({ kind: 'keyword', name: 'void' })
+        if ((flags & ts.TypeFlags.Null) !== 0) return add({ kind: 'literal', value: null, text: 'null' })
+        if ((flags & ts.TypeFlags.StringLiteral) !== 0) {
+          const value = (type as ts.StringLiteralType).value
+          return add({ kind: 'literal', value, text: JSON.stringify(value) })
+        }
+        if ((flags & ts.TypeFlags.NumberLiteral) !== 0) {
+          const value = (type as ts.NumberLiteralType).value
+          return add({ kind: 'literal', value, text: String(value) })
+        }
+        if ((flags & ts.TypeFlags.BigIntLiteral) !== 0) {
+          const value = (type as ts.BigIntLiteralType).value
+          const text = `${value.negative ? '-' : ''}${value.base10Value}n`
+          return add({ kind: 'literal', value: BigInt(`${value.negative ? '-' : ''}${value.base10Value}`), text })
+        }
+        if ((flags & ts.TypeFlags.BooleanLiteral) !== 0) {
+          const value = (type as ts.Type & { readonly intrinsicName?: string }).intrinsicName === 'true'
+          return add({ kind: 'literal', value, text: String(value) })
+        }
+        if (type.isUnionOrIntersection()) {
+          return add({
+            kind: (flags & ts.TypeFlags.Union) !== 0 ? 'union' : 'intersection',
+            types: type.types.map(convert),
+          })
+        }
+        if ((flags & ts.TypeFlags.TypeParameter) !== 0) {
+          this.fail(authoredType, 'Remote codec contains an unresolved type parameter')
+        }
+        if ((flags & ts.TypeFlags.Object) === 0) {
+          this.fail(
+            authoredType,
+            `Remote codec type ${this.checker.typeToString(type, authoredType, ts.TypeFormatFlags.NoTruncation)} has no concrete Zod projection`,
+          )
+        }
+        if (this.checker.isTupleType(type)) {
+          const reference = type as ts.TypeReference
+          const target = reference.target as ts.TupleType
+          const arguments_ = this.checker.getTypeArguments(reference)
+          return add({
+            kind: 'tuple',
+            elements: arguments_.map((argument, index) => {
+              const elementFlags = target.elementFlags[index] ?? ts.ElementFlags.Required
+              return {
+                type: convert(argument),
+                optional: (elementFlags & ts.ElementFlags.Optional) !== 0,
+                rest: (elementFlags & (ts.ElementFlags.Rest | ts.ElementFlags.Variadic)) !== 0,
+              }
+            }),
+          })
+        }
+        if (this.checker.isArrayType(type) || this.checker.isArrayLikeType(type)) {
+          const element = this.checker.getIndexTypeOfType(type, ts.IndexKind.Number)
+          if (element === undefined) this.fail(authoredType, 'Remote codec array has no element type')
+          return add({ kind: 'array', element: convert(element) })
+        }
+        if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) {
+          this.fail(authoredType, 'Remote codec cannot contain callable or constructable values')
+        }
+        const members: MemberModel[] = []
+        for (const property of this.checker.getPropertiesOfType(type)) {
+          const declaration = property.valueDeclaration ?? property.declarations?.[0]
+          const propertyType = this.checker.getTypeOfSymbolAtLocation(property, declaration ?? authoredType)
+          const symbolKey = property.getName()
+          members.push({
+            ...EMPTY_DOCUMENTATION,
+            id: `${id}#${symbolKey}`,
+            name: symbolKey,
+            ...(symbolKey.startsWith('__@') ? { computed: 'symbol' as const } : {}),
+            optional: (property.flags & ts.SymbolFlags.Optional) !== 0,
+            readonly: declaration !== undefined && hasModifier(declaration, ts.SyntaxKind.ReadonlyKeyword),
+            async: false,
+            abstract: false,
+            static: false,
+            visibility: 'public',
+            location: this.location(authoredType),
+            text: '',
+            kind: 'property',
+            type: convert(propertyType),
+          })
+        }
+        for (const [index, info] of this.checker.getIndexInfosOfType(type).entries()) {
+          members.push({
+            ...EMPTY_DOCUMENTATION,
+            id: `${id}#index:${String(index)}`,
+            name: '(index)',
+            optional: false,
+            readonly: info.isReadonly,
+            async: false,
+            abstract: false,
+            static: false,
+            visibility: 'public',
+            location: this.location(authoredType),
+            text: '',
+            kind: 'index',
+            signature: {
+              typeParameters: [],
+              parameters: [{
+                name: 'key',
+                binding: 'identifier',
+                type: convert(info.keyType),
+                optional: false,
+                rest: false,
+                receiver: false,
+              }],
+              returns: convert(info.type),
+            },
+          })
+        }
+        return add({ kind: 'object', members })
+      } finally {
+        active.delete(type)
+      }
+    }
+    return convert(this.checker.getTypeFromTypeNode(authoredType))
+  }
+
+  private resolvedCycleReference(
+    type: ts.Type,
+    site: ts.TypeNode,
+    resolvedType: TypeNodeId,
+    recursiveDeclarations: Map<ts.Type, SymbolId>,
+  ): TypeNodeId {
+    const symbol = type.aliasSymbol ?? type.getSymbol()
+    if (symbol === undefined) this.fail(site, 'Remote codec contains an unnamed recursive type')
+    const resolved = this.resolveSymbol(symbol)
+    const declaration = preferredDeclaration(resolved)
+    if (declaration === undefined || isStandardLibraryFile(declaration.getSourceFile().fileName)) {
+      this.fail(site, `Remote codec recursive type ${resolved.name} has no workspace declaration`)
+    }
+    const owner = this.registrationForFile(declaration.getSourceFile().fileName)
+    if (owner === undefined) this.fail(site, `Remote codec recursive type ${resolved.name} is not owned by this face`)
+    let id = recursiveDeclarations.get(type)
+    if (id === undefined) {
+      id = `${this.symbolId(resolved)}#remote-codec:${resolvedType}`
+      recursiveDeclarations.set(type, id)
+      this.declarations.set(id, {
+        ...EMPTY_DOCUMENTATION,
+        id,
+        package: owner.name,
+        name: `${resolved.name}RemoteCodec`,
+        kind: 'alias',
+        abstract: false,
+        exported: false,
+        location: this.location(declaration),
+        text: '',
+        typeParameters: [],
+        extends: [],
+        implements: [],
+        members: [],
+        type: resolvedType,
+      })
+    }
+    return this.addNode(site, {
+      kind: 'reference',
+      name: `${resolved.name}RemoteCodec`,
+      target: { kind: 'declaration', symbol: id },
+      arguments: [],
+    })
+  }
+
+  private namedWorkspaceType(node: ts.TypeNode): ts.Symbol | undefined {
+    if (!ts.isTypeReferenceNode(node) && !ts.isImportTypeNode(node)) return undefined
+    const symbol = ts.isTypeReferenceNode(node)
+      ? this.checker.getSymbolAtLocation(node.typeName)
+      : node.qualifier === undefined ? undefined : this.checker.getSymbolAtLocation(node.qualifier)
+    if (symbol === undefined) return undefined
+    const resolved = this.resolveSymbol(symbol)
+    const declaration = preferredDeclaration(resolved)
+    if (declaration === undefined
+      || isStandardLibraryFile(declaration.getSourceFile().fileName)
+      || this.registrationForFile(declaration.getSourceFile().fileName) === undefined) return undefined
+    return resolved
+  }
+
+  private publicRemoteType(symbol: ts.Symbol, site: ts.Node): RemoteTypeImportModel {
+    const declaration = preferredDeclaration(symbol)
+    if (declaration === undefined) this.fail(site, `type ${symbol.name} has no declaration`)
+    const registration = this.registrationForFile(declaration.getSourceFile().fileName)
+    if (registration === undefined) this.fail(site, `type ${symbol.name} is not owned by a workspace package`)
+    const candidates: RemoteTypeImportModel[] = []
+    for (const [subpath, target] of packageExportTargets(registration.manifest)) {
+      if (subpath === '.' || subpath === './package.json' || subpath === './typert'
+        || subpath === './client/typert' || subpath === './remote' || target.includes('*')) continue
+      const sourceFile = this.sourceFiles.get(realPath(sourcePathForExport(registration.root, target)))
+      if (sourceFile === undefined) continue
+      const moduleSymbol = this.checker.getSymbolAtLocation(sourceFile)
+      if (moduleSymbol === undefined) continue
+      for (const exported of this.checker.getExportsOfModule(moduleSymbol)) {
+        if (this.resolveSymbol(exported) !== symbol) continue
+        candidates.push({
+          symbol: this.symbolId(symbol),
+          specifier: packageExportSpecifier(registration.name, subpath),
+          name: exported.name,
+        })
+      }
+    }
+    const selected = candidates.sort((left, right) =>
+      left.specifier.localeCompare(right.specifier) || left.name.localeCompare(right.name))[0]
+    if (selected === undefined) {
+      this.fail(site, `Remote boundary type ${symbol.name} must be exported from a public non-root type subpath`)
+    }
+    return selected
+  }
+
+  private isWorkspaceClass(symbol: ts.Symbol): boolean {
+    const declaration = preferredDeclaration(symbol)
+    return declaration !== undefined
+      && ts.isClassDeclaration(declaration)
+      && this.registrationForFile(declaration.getSourceFile().fileName) !== undefined
+  }
+
+  private isTypeMetaSymbol(node: ts.Node, name: string): boolean {
+    const symbol = this.checker.getSymbolAtLocation(node)
+    if (symbol === undefined) return false
+    const resolved = this.resolveSymbol(symbol)
+    if (resolved.name !== name) return false
+    const declaration = preferredDeclaration(resolved)
+    if (declaration === undefined) return false
+    const registration = this.registrationForFile(declaration.getSourceFile().fileName)
+    if (registration?.name === '@deepseek-ai/dsh-type-meta') return true
+    for (let current: ts.Node | undefined = declaration; current !== undefined; current = optionalParent(current)) {
+      if (ts.isModuleDeclaration(current)
+        && ts.isStringLiteral(current.name)
+        && current.name.text === '@deepseek-ai/dsh-type-meta') return true
+    }
+    return false
+  }
+
+  private validateInvocationIdentity(packages: readonly PackageModel[]): void {
+    const endpoints = new Map<string, InvocationModel>()
+    const ids = new Map<string, InvocationModel>()
+    for (const invocation of packages.flatMap(packageModel => packageModel.invocations)) {
+      const endpoint = `${invocation.namespace}/${invocation.method}`
+      const existingEndpoint = endpoints.get(endpoint)
+      if (existingEndpoint !== undefined) {
+        throw new TypertAnalysisError(
+          `typert(${this.face}): ${invocation.location.file}:${String(invocation.location.line)}:${String(invocation.location.column)}: Remote endpoint ${endpoint} conflicts with ${existingEndpoint.id}`,
+        )
+      }
+      const existingId = ids.get(invocation.id)
+      if (existingId !== undefined) {
+        throw new TypertAnalysisError(
+          `typert(${this.face}): ${invocation.location.file}:${String(invocation.location.line)}:${String(invocation.location.column)}: Remote invocation id ${invocation.id} conflicts with ${existingId.id}`,
+        )
+      }
+      endpoints.set(endpoint, invocation)
+      ids.set(invocation.id, invocation)
+    }
+  }
+
   private collectEvents(events: ts.InterfaceDeclaration): EventModel[] {
     const result: EventModel[] = []
     for (const member of events.members) {
@@ -1015,6 +1777,11 @@ class FaceAnalyzer {
   ): MemberModel[] {
     const result: MemberModel[] = []
     for (const member of members) {
+      if (ts.isPropertyDeclaration(member)
+        && memberName(member.name) === 'typertGateway'
+        && member.initializer !== undefined
+        && ts.isCallExpression(member.initializer)
+        && this.isTypeMetaSymbol(member.initializer.expression, 'bindTypeRTGateway')) continue
       const visibility = visibilityOf(member)
       const isStatic = hasModifier(member, ts.SyntaxKind.StaticKeyword)
       if (visibility !== 'public' || isStatic || ts.isConstructorDeclaration(member)) continue
@@ -1045,17 +1812,19 @@ class FaceAnalyzer {
     visibility: MemberVisibility,
     isStatic: boolean,
   ): MemberBase {
-    const name = member.name !== undefined
-      ? memberName(member.name)
-      : ts.isCallSignatureDeclaration(member)
-        ? '(call)'
-        : ts.isConstructSignatureDeclaration(member)
-          ? '(construct)'
-          : '(index)'
+    const identity = member.name !== undefined
+      ? this.memberIdentity(member.name)
+      : {
+        name: ts.isCallSignatureDeclaration(member)
+          ? '(call)'
+          : ts.isConstructSignatureDeclaration(member)
+            ? '(construct)'
+            : '(index)',
+      }
     return {
       ...documentationOf(member),
-      id: `${ownerId}#${name}@${String(member.getStart())}`,
-      name,
+      id: `${ownerId}#${identity.name}@${String(member.getStart())}`,
+      ...identity,
       optional: 'questionToken' in member && member.questionToken !== undefined,
       readonly: hasModifier(member, ts.SyntaxKind.ReadonlyKeyword),
       async: hasModifier(member, ts.SyntaxKind.AsyncKeyword),
@@ -1067,6 +1836,20 @@ class FaceAnalyzer {
     }
   }
 
+  private memberIdentity(name: ts.PropertyName): Pick<MemberBase, 'name' | 'jsonName' | 'computed'> {
+    if (!ts.isComputedPropertyName(name)) return { name: memberName(name) }
+    const expression = name.expression
+    if (ts.isStringLiteral(expression) || ts.isNumericLiteral(expression)
+      || ts.isNoSubstitutionTemplateLiteral(expression)) {
+      return { name: memberName(name), jsonName: expression.text }
+    }
+    const type = this.checker.getTypeAtLocation(expression)
+    return {
+      name: memberName(name),
+      computed: (type.flags & ts.TypeFlags.UniqueESSymbol) !== 0 ? 'symbol' : 'dynamic',
+    }
+  }
+
   private signature(
     node: ts.SignatureDeclarationBase,
     explicitReturn: ts.TypeNode | undefined,
@@ -1570,7 +2353,23 @@ function sourceFileHasSurface(sourceFile: ts.SourceFile): boolean {
       || ts.isInterfaceDeclaration(statement)
       || ts.isTypeAliasDeclaration(statement)
       || ts.isEnumDeclaration(statement))
-      && typertMode(statement) !== undefined) return true
+      && (typertMode(statement) !== undefined || typertServiceTag(statement) !== undefined)) return true
+    if (ts.isClassDeclaration(statement)) {
+      for (const member of statement.members) {
+        if (ts.isPropertyDeclaration(member)
+          && memberName(member.name) === 'typertGateway'
+          && member.initializer !== undefined
+          && ts.isCallExpression(member.initializer)
+          && expressionName(member.initializer.expression) === 'bindTypeRTGateway') return true
+        for (const decorator of ts.canHaveDecorators(member) ? ts.getDecorators(member) ?? [] : []) {
+          const expression = ts.isCallExpression(decorator.expression)
+            ? decorator.expression.expression
+            : decorator.expression
+          const name = expressionName(expression)
+          if (name === 'Remote' || name === 'RemoteContext') return true
+        }
+      }
+    }
     if (!ts.isModuleDeclaration(statement)
       || !ts.isStringLiteral(statement.name)
       || statement.name.text !== 'cordis'
@@ -1588,6 +2387,7 @@ function hasPackageSurface(model: PackageModel): boolean {
     || model.events.length > 0
     || model.objects.length > 0
     || model.schemas.length > 0
+    || model.invocations.length > 0
 }
 
 function isDualFacePackage(manifest: Record<string, unknown>): boolean {
@@ -1599,7 +2399,9 @@ function isDualFacePackage(manifest: Record<string, unknown>): boolean {
 function hostExportSubpaths(manifest: Record<string, unknown>): string[] {
   return packageExportTargets(manifest)
     .map(([subpath]) => subpath)
-    .filter(subpath => subpath !== './client' && !subpath.startsWith('./client/'))
+    .filter(subpath => subpath !== './client'
+      && !subpath.startsWith('./client/')
+      && subpath !== './remote')
 }
 
 function clientExportSubpaths(manifest: Record<string, unknown>): string[] {
@@ -1668,6 +2470,10 @@ function preferredDeclaration(symbol: ts.Symbol): ts.Declaration | undefined {
     ?? symbol.declarations?.[0]
 }
 
+function optionalParent(node: ts.Node): ts.Node | undefined {
+  return (node as ts.Node & { readonly parent?: ts.Node }).parent
+}
+
 function isTypeDeclaration(
   node: ts.Node,
 ): node is ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration | ts.EnumDeclaration {
@@ -1822,6 +2628,11 @@ function typertMode(node: ts.Node): 'object' | 'schema' | undefined {
   return undefined
 }
 
+function typertServiceTag(node: ts.Node): ts.JSDocTag | undefined {
+  return ts.getJSDocTags(node).find(tag => tag.tagName.text === 'typert'
+    && (ts.getTextOfJSDocComment(tag.comment) ?? '').trim().split(/\s+/, 1)[0] === 'service')
+}
+
 function memberName(name: ts.PropertyName | ts.BindingName): string {
   if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name) || ts.isStringLiteral(name)
     || ts.isNumericLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name)) return name.text
@@ -1829,6 +2640,26 @@ function memberName(name: ts.PropertyName | ts.BindingName): string {
   return name.getText()
 }
 
+function stringLiteralValue(node: ts.Node | undefined): string | undefined {
+  return node !== undefined && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+    ? node.text
+    : undefined
+}
+
+function isRemoteSegment(value: string): boolean {
+  return value.length > 0 && !value.includes('/')
+}
+
+function expressionName(node: ts.Expression): string | undefined {
+  if (ts.isIdentifier(node)) return node.text
+  if (ts.isPropertyAccessExpression(node)) return node.name.text
+  return undefined
+}
+
+function packageExportSpecifier(packageName: string, subpath: string): string {
+  return subpath === '.' ? packageName : `${packageName}${subpath.slice(1)}`
+}
+
 function visibilityOf(node: ts.Node): MemberVisibility {
   if ('name' in node && node.name !== undefined && ts.isPrivateIdentifier(node.name as ts.Node)) return 'private'
   if (hasModifier(node, ts.SyntaxKind.PrivateKeyword)) return 'private'
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index 1bcb1ca72a..e5c2c15a00 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -231,7 +231,7 @@ export class CordisCatalogProjector {
       for (const service of packageModel.services) {
         const declaration = this.renderer.declaration(service.symbol)
         if (declaration.kind !== 'class'
-          || !/^packages\/[^/]+\/[^/]+\/src\/index\.ts$/.test(service.location.file)
+          || !/^packages\/[^/]+\/[^/]+\/src\/[^/]+\.ts$/.test(service.location.file)
           || declaration.location.file !== service.location.file) continue
         const doc = parseJsDoc(declaration.jsDoc ?? '').doc
         const source = pointer(declaration.location)
diff --git a/packages/typert/generator/src/emitter.ts b/packages/typert/generator/src/emitter.ts
index 4a09eaad68..3e79780593 100644
--- a/packages/typert/generator/src/emitter.ts
+++ b/packages/typert/generator/src/emitter.ts
@@ -4,11 +4,17 @@
  * @module @deepseek-ai/dsh-typert-generator/emitter
  */
 
+import { Buffer } from 'node:buffer'
+import { posix } from 'node:path'
+import { GenMapping, addMapping, toEncodedMap } from '@jridgewell/gen-mapping'
 import type {
   DocumentationModel,
   FaceModel,
+  InvocationModel,
   MemberModel,
   PackageModel,
+  RemoteBoundaryModel,
+  RemoteTypeImportModel,
   SchemaModel,
   SymbolId,
   TypeDeclarationModel,
@@ -29,6 +35,14 @@ export interface ModelEmitResult {
   readonly exports: readonly string[]
   readonly js: string
   readonly dts: string
+  readonly remote?: RemoteModelEmitResult
+}
+
+/** Host-for-Client Remote contribution generated from the Host Program. */
+export interface RemoteModelEmitResult {
+  readonly js: string
+  readonly dts: string
+  readonly dtsMap: string
 }
 
 interface RuntimeMemberModel {
@@ -92,7 +106,11 @@ export class FaceModelEmitter {
     if (packageModel === undefined) {
       throw new TypertEmitError(`typert emitter(${this.face.face}): package ${packageName} is not modeled on this face`)
     }
-    const schemas = new SchemaEmitter(this.renderer, packageModel.schemas)
+    const schemas = new SchemaEmitter(
+      this.renderer,
+      packageModel.schemas,
+      invocationBoundaryRoots(packageModel.invocations),
+    )
     const schemaArtifact = schemas.emit()
     const runtimeModel = this.runtimeModel(packageModel)
     const js = this.renderJs(packageModel, schemaArtifact, runtimeModel)
@@ -103,6 +121,9 @@ export class FaceModelEmitter {
       exports: packageModel.schemas.map(schema => schema.export.name),
       js,
       dts,
+      ...(this.face.face === 'host' && packageModel.invocations.length > 0
+        ? { remote: this.emitRemote(packageModel) }
+        : {}),
     }
   }
 
@@ -184,6 +205,11 @@ export class FaceModelEmitter {
       lines.push(`    { name: ${quote(schema.exportName)}, schema: ${schema.exportName} },`)
     }
     lines.push('  ],')
+    lines.push('  invocations: [')
+    for (const invocation of packageModel.invocations) {
+      lines.push(`${indent(this.invocationLiteral(invocation, schemas), 4)},`)
+    }
+    lines.push('  ],')
     lines.push(`  model: ${indent(model, 2).trimStart()},`)
     lines.push('}')
     return `${lines.join('\n')}\n`
@@ -215,6 +241,246 @@ export class FaceModelEmitter {
     lines.push('export declare const TYPERT: unknown')
     return `${lines.join('\n')}\n`
   }
+
+  private emitRemote(packageModel: PackageModel): RemoteModelEmitResult {
+    const schemas = new SchemaEmitter(
+      this.renderer,
+      [],
+      invocationBoundaryRoots(packageModel.invocations),
+    ).emit()
+    const lines = [
+      '/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */',
+    ]
+    if (schemas.definitions.length > 0) lines.push('import { z } from \'zod\'', '')
+    lines.push(...schemas.definitions)
+    if (schemas.definitions.length > 0) lines.push('')
+    lines.push('export const TYPERT_REMOTE = {')
+    lines.push(`  package: ${quote(packageModel.name)},`)
+    lines.push('  descriptors: [')
+    for (const invocation of packageModel.invocations) {
+      lines.push(`${indent(this.invocationLiteral(invocation, schemas), 4)},`)
+    }
+    lines.push('  ],')
+    lines.push('}')
+    lines.push('')
+    lines.push('export default TYPERT_REMOTE')
+    const declaration = this.renderRemoteDts(packageModel)
+    return {
+      js: `${lines.join('\n')}\n`,
+      ...declaration,
+    }
+  }
+
+  private invocationLiteral(invocation: InvocationModel, schemas: SchemaArtifact): string {
+    const lines = [
+      '{',
+      `  id: ${quote(invocation.id)},`,
+      `  service: ${quote(invocation.service)},`,
+      `  namespace: ${quote(invocation.namespace)},`,
+      `  method: ${quote(invocation.method)},`,
+    ]
+    if (invocation.implementation !== undefined) {
+      lines.push(`  implementation: ${quote(invocation.implementation)},`)
+    }
+    if (invocation.invocation.kind === 'direct') {
+      lines.push('  invocation: { kind: \'direct\' },')
+    } else {
+      lines.push('  invocation: {')
+      lines.push('    kind: \'context\',')
+      lines.push(`    context: ${quote(invocation.invocation.context)},`)
+      lines.push(`    wire: ${quote(invocation.invocation.wire)},`)
+      lines.push(`    codec: ${indent(strictCodec(
+        invocation.invocation.boundary,
+        schemas.boundary(contextBoundaryKey(invocation)),
+      ), 4).trimStart()},`)
+      lines.push('  },')
+    }
+    if (invocation.scope !== undefined) {
+      lines.push('  scope: {')
+      lines.push(`    context: ${quote(invocation.scope.context)},`)
+      lines.push(`    wire: ${quote(invocation.scope.wire)},`)
+      lines.push('  },')
+    }
+    lines.push('  parameters: [')
+    invocation.parameters.forEach((parameter, index) => {
+      lines.push('    {')
+      lines.push(`      name: ${quote(parameter.name)},`)
+      lines.push(`      wire: ${quote(parameter.wire)},`)
+      lines.push(`      source: ${quote(parameter.source)},`)
+      if (parameter.lookup !== undefined) lines.push(`      lookup: ${quote(parameter.lookup)},`)
+      lines.push(`      codec: ${indent(strictCodec(
+        parameter.boundary,
+        schemas.boundary(parameterBoundaryKey(invocation, index)),
+      ), 6).trimStart()},`)
+      lines.push('    },')
+    })
+    lines.push('  ],')
+    lines.push(`  result: ${indent(strictCodec(
+      invocation.result,
+      schemas.boundary(resultBoundaryKey(invocation)),
+    ), 2).trimStart()},`)
+    lines.push(`  sourceLocation: ${JSON.stringify(invocation.location)},`)
+    lines.push('}')
+    return lines.join('\n')
+  }
+
+  private renderRemoteDts(packageModel: PackageModel): Pick<RemoteModelEmitResult, 'dts' | 'dtsMap'> {
+    const imports = remoteImports(packageModel.invocations)
+    const referenceNames = allocateRemoteImportNames(imports)
+    const grouped = new Map<string, { readonly name: string; readonly local: string }[]>()
+    for (const imported of imports) {
+      const values = grouped.get(imported.specifier) ?? []
+      values.push({
+        name: imported.name,
+        local: referenceNames.get(imported.symbol) as string,
+      })
+      grouped.set(imported.specifier, values)
+    }
+    const lines = [
+      '/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */',
+      'import type {',
+      '  TypeRTRemoteContribution,',
+      '} from \'@deepseek-ai/dsh-type-meta\'',
+    ]
+    const sourceMap = new GenMapping({ file: 'typert.remote-client.d.ts' })
+    for (const [specifier, values] of [...grouped].sort(([left], [right]) => left.localeCompare(right))) {
+      const names = values.sort((left, right) => left.local.localeCompare(right.local)).map(value =>
+        value.name === value.local ? value.name : `${value.name} as ${value.local}`)
+      lines.push(`import type { ${names.join(', ')} } from ${quote(specifier)}`)
+    }
+    lines.push('')
+    lines.push('declare module \'@deepseek-ai/dsh-type-meta\' {')
+    const direct = packageModel.invocations.filter(invocation => invocation.invocation.kind === 'direct')
+    const scoped = packageModel.invocations.filter(invocation =>
+      invocation.invocation.kind === 'context' || invocation.scope !== undefined)
+    if (direct.length > 0) {
+      for (const namespace of uniqueNamespaces(direct)) {
+        lines.push(`  interface ${remoteNamespaceInterface(namespace)} {`)
+        for (const invocation of direct.filter(candidate => candidate.namespace === namespace)) {
+          this.pushRemoteNamespaceSignature(lines, sourceMap, packageModel, invocation, referenceNames)
+        }
+        lines.push('  }')
+      }
+      lines.push('  interface TypeRTRemoteMap {')
+      for (const invocation of direct) {
+        this.pushRemoteSignature(lines, sourceMap, packageModel, invocation, referenceNames, false)
+      }
+      lines.push('  }')
+      lines.push('  interface TypeRTRemoteNamespaceMap {')
+      for (const namespace of uniqueNamespaces(direct)) {
+        lines.push(`    ${quote(namespace)}: ${remoteNamespaceInterface(namespace)}`)
+      }
+      lines.push('  }')
+    }
+    if (scoped.length > 0) {
+      lines.push('  interface TypeRTRemoteContextMap {')
+      for (const invocation of scoped) {
+        this.pushRemoteSignature(lines, sourceMap, packageModel, invocation, referenceNames, true)
+      }
+      lines.push('  }')
+    }
+    lines.push('}')
+    lines.push('')
+    lines.push('export declare const TYPERT_REMOTE: TypeRTRemoteContribution')
+    lines.push('export default TYPERT_REMOTE')
+    lines.push('//# sourceMappingURL=typert.remote-client.d.ts.map')
+    return {
+      dts: `${lines.join('\n')}\n`,
+      dtsMap: `${JSON.stringify(toEncodedMap(sourceMap))}\n`,
+    }
+  }
+
+  private pushRemoteSignature(
+    lines: string[],
+    sourceMap: GenMapping,
+    packageModel: PackageModel,
+    invocation: InvocationModel,
+    referenceNames: ReadonlyMap<SymbolId, string>,
+    scoped: boolean,
+  ): void {
+    const signature = this.remoteSignature(invocation, referenceNames, scoped)
+    const line = `    ${signature}`
+    lines.push(line)
+    const generatedLine = lines.length
+    const keyLength = signature.indexOf(': (')
+    if (keyLength < 0) throw new TypertEmitError(`Remote signature ${invocation.id} has no property delimiter`)
+    const source = remoteDeclarationSource(packageModel, invocation)
+    addMapping(sourceMap, {
+      generated: { line: generatedLine, column: 4 },
+      source,
+      original: { line: invocation.location.line, column: invocation.location.column - 1 },
+      name: invocation.method,
+    })
+    addMapping(sourceMap, {
+      generated: { line: generatedLine, column: 4 + keyLength },
+    })
+  }
+
+  private pushRemoteNamespaceSignature(
+    lines: string[],
+    sourceMap: GenMapping,
+    packageModel: PackageModel,
+    invocation: InvocationModel,
+    referenceNames: ReadonlyMap<SymbolId, string>,
+  ): void {
+    const signature = `${invocation.method}: ${this.remoteFunctionType(invocation, referenceNames, false)}`
+    lines.push(`    ${signature}`)
+    const generatedLine = lines.length
+    const source = remoteDeclarationSource(packageModel, invocation)
+    addMapping(sourceMap, {
+      generated: { line: generatedLine, column: 4 },
+      source,
+      original: { line: invocation.location.line, column: invocation.location.column - 1 },
+      name: invocation.method,
+    })
+    addMapping(sourceMap, {
+      generated: { line: generatedLine, column: 4 + invocation.method.length },
+    })
+  }
+
+  private remoteSignature(
+    invocation: InvocationModel,
+    referenceNames: ReadonlyMap<SymbolId, string>,
+    scoped: boolean,
+  ): string {
+    const context = invocation.invocation.kind === 'context'
+      ? invocation.invocation.context
+      : invocation.scope?.context
+    const key = scoped
+      ? `${context as string}:${invocation.namespace}/${invocation.method}`
+      : `${invocation.namespace}/${invocation.method}`
+    return `${quote(key)}: ${this.remoteFunctionType(invocation, referenceNames, scoped)}`
+  }
+
+  private remoteFunctionType(
+    invocation: InvocationModel,
+    referenceNames: ReadonlyMap<SymbolId, string>,
+    scoped: boolean,
+  ): string {
+    const parameters = invocation.parameters.filter(parameter =>
+      !scoped || invocation.invocation.kind === 'context' || parameter.wire !== invocation.scope?.wire).map(parameter =>
+      `${safeIdentifier(parameter.wire)}: ${this.renderer.renderType(parameter.boundary.type, referenceNames)}`)
+    const result = this.renderer.renderType(invocation.result.type, referenceNames)
+    return `(${parameters.join(', ')}) => Promise<${result}>`
+  }
+}
+
+function remoteDeclarationSource(packageModel: PackageModel, invocation: InvocationModel): string {
+  const relativeSource = posix.relative(packageModel.root, invocation.location.file)
+  if (relativeSource === '' || relativeSource === '..' || relativeSource.startsWith('../') || posix.isAbsolute(relativeSource)) {
+    throw new TypertEmitError(
+      `Remote declaration ${invocation.id} is outside its package root ${packageModel.root}`,
+    )
+  }
+  return posix.join('..', relativeSource)
+}
+
+function uniqueNamespaces(invocations: readonly InvocationModel[]): string[] {
+  return [...new Set(invocations.map(invocation => invocation.namespace))].sort()
+}
+
+function remoteNamespaceInterface(namespace: string): string {
+  return `TypeRTRemoteNamespace$${Buffer.from(namespace, 'utf8').toString('hex')}`
 }
 
 interface SchemaExport {
@@ -226,15 +492,23 @@ interface SchemaExport {
 interface SchemaArtifact {
   readonly definitions: readonly string[]
   readonly exports: readonly SchemaExport[]
+  boundary(key: string): string
+}
+
+interface BoundarySchemaRoot {
+  readonly key: string
+  readonly type: TypeNodeId
 }
 
 class SchemaEmitter {
   private readonly names = new Map<SymbolId, string>()
+  private readonly boundaryNames = new Map<string, string>()
   private readonly declarations: TypeDeclarationModel[]
 
   constructor(
     private readonly renderer: TypeGraphRenderer,
     private readonly schemas: readonly SchemaModel[],
+    private readonly boundaries: readonly BoundarySchemaRoot[],
   ) {
     const declarations = new Map<SymbolId, TypeDeclarationModel>()
     for (const schema of schemas) {
@@ -242,6 +516,11 @@ class SchemaEmitter {
         declarations.set(declaration.id, declaration)
       }
     }
+    for (const boundary of boundaries) {
+      for (const declaration of renderer.declarationClosureForTypes([boundary.type])) {
+        declarations.set(declaration.id, declaration)
+      }
+    }
     this.declarations = renderer.graph.declarations.filter(declaration => declarations.has(declaration.id))
     const identifiers = new Set<string>()
     for (const declaration of this.declarations) {
@@ -252,65 +531,92 @@ class SchemaEmitter {
       identifiers.add(name)
       this.names.set(declaration.id, name)
     }
+    for (const boundary of boundaries) {
+      const base = `${safeIdentifier(boundary.key)}$schema`
+      let name = base
+      let suffix = 2
+      while (identifiers.has(name)) name = `${base}${String(suffix++)}`
+      identifiers.add(name)
+      this.boundaryNames.set(boundary.key, name)
+    }
   }
 
   emit(): SchemaArtifact {
-    const definitions = this.declarations.map((declaration) => {
-      if (declaration.typeParameters.length > 0) {
-        this.fail(declaration.name, 'generic declarations require a schema-factory projection')
-      }
-      return `const ${this.schemaName(declaration.id)} = ${this.declarationSchema(declaration)}`
-    })
+    const definitions = this.declarations.map(declaration => this.declarationDefinition(declaration))
+    for (const boundary of this.boundaries) {
+      definitions.push(`const ${this.boundaryName(boundary.key)} = ${this.typeSchema(boundary.type)}`)
+    }
     const exports = this.schemas.map((model): SchemaExport => ({
       model,
       exportName: safeIdentifier(model.export.name),
-      internalName: this.schemaName(model.symbol),
+      internalName: this.exportSchemaName(model),
     }))
-    return { definitions, exports }
+    return {
+      definitions,
+      exports,
+      boundary: key => this.boundaryName(key),
+    }
   }
 
-  private declarationSchema(declaration: TypeDeclarationModel): string {
+  private declarationDefinition(declaration: TypeDeclarationModel): string {
+    const name = this.schemaName(declaration.id)
+    if (declaration.typeParameters.length === 0) {
+      return `const ${name} = ${this.declarationSchema(declaration, new Map())}`
+    }
+    const parameters = declaration.typeParameters.map((parameter, index) =>
+      [`type${String(index)}$schema`, parameter.id] as const)
+    const substitutions = new Map(parameters.map(([schema, id]) => [id, schema]))
+    return `const ${name} = (${parameters.map(([schema]) => schema).join(', ')}) => ${this.declarationSchema(declaration, substitutions)}`
+  }
+
+  private declarationSchema(
+    declaration: TypeDeclarationModel,
+    substitutions: ReadonlyMap<string, string>,
+  ): string {
     if (declaration.kind === 'enum') {
       this.fail(declaration.name, 'enum declarations have no Zod projection')
     }
     if (declaration.kind === 'alias') {
       if (declaration.type === undefined) this.fail(declaration.name, 'alias has no modeled type')
-      return this.describe(this.typeSchema(declaration.type), declaration)
+      return this.describe(this.typeSchema(declaration.type, substitutions), declaration)
     }
-    const own = this.objectSchema(declaration.members, declaration.name)
+    const own = this.objectSchema(declaration.members, declaration.name, substitutions)
     let result = own
     for (const heritage of declaration.extends) {
-      result = `z.intersection(${this.typeSchema(heritage)}, ${result})`
+      result = `z.intersection(${this.typeSchema(heritage, substitutions)}, ${result})`
     }
     return this.describe(result, declaration)
   }
 
-  private typeSchema(id: TypeNodeId): string {
+  private typeSchema(id: TypeNodeId, substitutions: ReadonlyMap<string, string> = new Map()): string {
     const node = this.renderer.node(id)
     switch (node.kind) {
       case 'keyword': return this.keywordSchema(node.name)
       case 'literal': return `z.literal(${node.text})`
-      case 'parenthesized': return this.typeSchema(node.type)
-      case 'reference': return this.referenceSchema(node)
+      case 'parenthesized': return this.typeSchema(node.type, substitutions)
+      case 'reference': return this.referenceSchema(node, substitutions)
       case 'union': {
         if (node.types.length === 0) return 'z.never()'
-        if (node.types.length === 1) return this.typeSchema(node.types[0] as TypeNodeId)
-        return `z.union([${node.types.map(type => this.typeSchema(type)).join(', ')}])`
+        if (node.types.length === 1) return this.typeSchema(node.types[0] as TypeNodeId, substitutions)
+        return `z.union([${node.types.map(type => this.typeSchema(type, substitutions)).join(', ')}])`
       }
       case 'intersection': {
         const [head, ...tail] = node.types
         if (head === undefined) return 'z.unknown()'
-        return tail.reduce((left, right) => `z.intersection(${left}, ${this.typeSchema(right)})`, this.typeSchema(head))
+        return tail.reduce(
+          (left, right) => `z.intersection(${left}, ${this.typeSchema(right, substitutions)})`,
+          this.typeSchema(head, substitutions),
+        )
       }
-      case 'array': return `z.array(${this.typeSchema(node.element)})`
+      case 'array': return `z.array(${this.typeSchema(node.element, substitutions)})`
       case 'tuple': {
         const fixed = node.elements.filter(element => !element.rest)
         const rest = node.elements.find(element => element.rest)
-        let schema = `z.tuple([${fixed.map(element => this.optional(this.typeSchema(element.type), element.optional)).join(', ')}])`
-        if (rest !== undefined) schema += `.rest(${this.tupleRestSchema(rest.type)})`
+        let schema = `z.tuple([${fixed.map(element => this.optional(this.typeSchema(element.type, substitutions), element.optional)).join(', ')}])`
+        if (rest !== undefined) schema += `.rest(${this.tupleRestSchema(rest.type, substitutions)})`
         return schema
       }
-      case 'object': return this.objectSchema(node.members, id)
+      case 'object': return this.objectSchema(node.members, id, substitutions)
       case 'operator':
       case 'indexed-access':
       case 'conditional':
@@ -326,9 +632,27 @@ class SchemaEmitter {
     }
   }
 
-  private referenceSchema(node: Extract<TypeNodeModel, { kind: 'reference' }>): string {
+  private referenceSchema(
+    node: Extract<TypeNodeModel, { kind: 'reference' }>,
+    substitutions: ReadonlyMap<string, string>,
+  ): string {
     if (node.target.kind === 'declaration') {
-      return `z.lazy(() => ${this.schemaName(node.target.symbol)})`
+      const name = this.schemaName(node.target.symbol)
+      const declaration = this.renderer.declaration(node.target.symbol)
+      if (declaration.typeParameters.length === 0) {
+        if (node.arguments.length > 0) {
+          this.fail(node.name, `non-generic declaration received ${String(node.arguments.length)} type arguments`)
+        }
+        return `z.lazy(() => ${name})`
+      }
+      const arguments_ = this.declarationArguments(node, declaration, substitutions)
+      return `z.lazy(() => ${name}(${arguments_.join(', ')}))`
+    }
+    if (node.target.kind === 'type-parameter') {
+      if (node.arguments.length > 0) this.fail(node.name, 'type parameter reference cannot receive type arguments')
+      const schema = substitutions.get(node.target.parameter)
+      if (schema === undefined) this.fail(node.name, 'type parameter has no schema substitution')
+      return schema
     }
     if (node.target.kind === 'standard') {
       switch (node.target.name) {
@@ -336,13 +660,16 @@ class SchemaEmitter {
         case 'ReadonlyArray': {
           const element = node.arguments[0]
           if (element === undefined) this.fail(node.name, 'array reference has no element type')
-          return this.readonly(`z.array(${this.typeSchema(element)})`, node.target.name === 'ReadonlyArray')
+          return this.readonly(
+            `z.array(${this.typeSchema(element, substitutions)})`,
+            node.target.name === 'ReadonlyArray',
+          )
         }
         case 'Record': {
           const key = node.arguments[0]
           const value = node.arguments[1]
           if (key === undefined || value === undefined) this.fail(node.name, 'Record requires key and value types')
-          return `z.record(${this.typeSchema(key)}, ${this.typeSchema(value)})`
+          return `z.record(${this.typeSchema(key, substitutions)}, ${this.typeSchema(value, substitutions)})`
         }
         case 'Date': return 'z.date()'
         default: this.fail(node.name, `standard type ${node.target.name} has no Zod projection`)
@@ -351,31 +678,97 @@ class SchemaEmitter {
     this.fail(node.name, `${node.target.kind} reference has no Zod projection`)
   }
 
-  private tupleRestSchema(id: TypeNodeId): string {
+  private declarationArguments(
+    node: Extract<TypeNodeModel, { kind: 'reference' }>,
+    declaration: TypeDeclarationModel,
+    substitutions: ReadonlyMap<string, string>,
+  ): string[] {
+    if (node.arguments.length > declaration.typeParameters.length) {
+      this.fail(
+        node.name,
+        `generic declaration accepts ${String(declaration.typeParameters.length)} type arguments but received ${String(node.arguments.length)}`,
+      )
+    }
+    const resolved = new Map(substitutions)
+    const arguments_: string[] = []
+    for (const [index, parameter] of declaration.typeParameters.entries()) {
+      const argument = node.arguments[index]
+      const schema = argument === undefined
+        ? parameter.default === undefined
+          ? this.fail(node.name, `missing type argument ${parameter.name}`)
+          : this.typeSchema(parameter.default, resolved)
+        : this.typeSchema(argument, substitutions)
+      arguments_.push(schema)
+      resolved.set(parameter.id, schema)
+    }
+    return arguments_
+  }
+
+  private tupleRestSchema(id: TypeNodeId, substitutions: ReadonlyMap<string, string>): string {
     const node = this.renderer.node(id)
-    if (node.kind === 'array') return this.typeSchema(node.element)
+    if (node.kind === 'array') return this.typeSchema(node.element, substitutions)
     if (node.kind === 'reference'
       && node.target.kind === 'standard'
       && (node.target.name === 'Array' || node.target.name === 'ReadonlyArray')) {
       const element = node.arguments[0]
       if (element === undefined) this.fail(node.name, 'tuple rest array has no element type')
-      return this.typeSchema(element)
+      return this.typeSchema(element, substitutions)
     }
     this.fail(id, 'tuple rest element must retain an array type')
   }
 
-  private objectSchema(members: readonly MemberModel[], subject: string): string {
+  private objectSchema(
+    members: readonly MemberModel[],
+    subject: string,
+    substitutions: ReadonlyMap<string, string>,
+  ): string {
     const properties: string[] = []
+    const indices: string[] = []
+    let symbolMembers = 0
     for (const member of members) {
       if (member.static || member.visibility !== 'public') continue
+      if (member.computed === 'symbol') {
+        symbolMembers++
+        continue
+      }
+      if (member.computed === 'dynamic') {
+        this.fail(subject, `computed member ${member.name} has no fixed JSON property name`)
+      }
+      if (member.kind === 'index') {
+        const parameter = member.signature.parameters[0]
+        if (member.signature.parameters.length !== 1 || parameter === undefined) {
+          this.fail(subject, 'index signature must have exactly one key parameter')
+        }
+        indices.push(this.readonly(
+          `z.record(${this.typeSchema(parameter.type, substitutions)}, ${this.typeSchema(member.signature.returns, substitutions)})`,
+          member.readonly,
+        ))
+        continue
+      }
       if (member.kind !== 'property') this.fail(subject, `${member.kind} member ${member.name} is not data-schema projectable`)
       const property = this.describe(
-        this.optional(this.readonly(this.typeSchema(member.type), member.readonly), member.optional),
+        this.optional(this.readonly(this.typeSchema(member.type, substitutions), member.readonly), member.optional),
         member,
       )
-      properties.push(`${quote(member.name)}: ${property}`)
+      properties.push(`${quote(member.jsonName ?? member.name)}: ${property}`)
     }
-    return `z.object({${properties.length === 0 ? '' : `\n${properties.map(property => `  ${property},`).join('\n')}\n`}})`
+    if (indices.length > 1) this.fail(subject, 'object type has more than one JSON index signature')
+    // A unique-symbol-only object is a compile-time marker and imposes no JSON shape.
+    if (properties.length === 0 && indices.length === 0 && symbolMembers > 0) return 'z.unknown()'
+    const object = `z.object({${properties.length === 0 ? '' : `\n${properties.map(property => `  ${property},`).join('\n')}\n`}})`
+    const index = indices[0]
+    if (index === undefined) return object
+    if (properties.length === 0) return index
+    return `z.intersection(${object}, ${index})`
+  }
+
+  private exportSchemaName(model: SchemaModel): string {
+    const name = this.schemaName(model.symbol)
+    const declaration = this.renderer.declaration(model.symbol)
+    if (declaration.typeParameters.length > 0) {
+      this.fail(model.export.name, 'generic schema exports require a concrete declaration')
+    }
+    return name
   }
 
   private keywordSchema(name: string): string {
@@ -401,6 +794,12 @@ class SchemaEmitter {
     return name
   }
 
+  private boundaryName(key: string): string {
+    const name = this.boundaryNames.get(key)
+    if (name === undefined) this.fail(key, 'invocation boundary is outside the selected schema roots')
+    return name
+  }
+
   private describe(schema: string, documentation: DocumentationModel): string {
     return documentation.description === undefined ? schema : `${schema}.describe(${quote(documentation.description)})`
   }
@@ -431,6 +830,77 @@ function documentationLiteral(documentation: DocumentationModel): DocumentationM
   }
 }
 
+function invocationBoundaryRoots(invocations: readonly InvocationModel[]): BoundarySchemaRoot[] {
+  const result: BoundarySchemaRoot[] = []
+  for (const invocation of invocations) {
+    if (invocation.invocation.kind === 'context') {
+      result.push({ key: contextBoundaryKey(invocation), type: invocation.invocation.boundary.codecType })
+    }
+    invocation.parameters.forEach((parameter, index) => {
+      result.push({ key: parameterBoundaryKey(invocation, index), type: parameter.boundary.codecType })
+    })
+    result.push({ key: resultBoundaryKey(invocation), type: invocation.result.codecType })
+  }
+  return result
+}
+
+function contextBoundaryKey(invocation: InvocationModel): string {
+  return `${invocation.id}:context`
+}
+
+function parameterBoundaryKey(invocation: InvocationModel, index: number): string {
+  return `${invocation.id}:parameter:${String(index)}`
+}
+
+function resultBoundaryKey(invocation: InvocationModel): string {
+  return `${invocation.id}:result`
+}
+
+function strictCodec(boundary: RemoteBoundaryModel, schema: string): string {
+  return [
+    '{',
+    '  mode: \'strict\',',
+    `  typeSymbol: ${quote(boundary.typeSymbol)},`,
+    `  schema: ${schema},`,
+    '}',
+  ].join('\n')
+}
+
+function remoteImports(invocations: readonly InvocationModel[]): RemoteTypeImportModel[] {
+  const imports = new Map<SymbolId, RemoteTypeImportModel>()
+  const add = (boundary: RemoteBoundaryModel): void => {
+    for (const imported of boundary.imports) {
+      const current = imports.get(imported.symbol)
+      if (current !== undefined
+        && (current.specifier !== imported.specifier || current.name !== imported.name)) {
+        throw new TypertEmitError(`typert Remote emitter: symbol ${imported.symbol} has inconsistent public imports`)
+      }
+      imports.set(imported.symbol, imported)
+    }
+  }
+  for (const invocation of invocations) {
+    if (invocation.invocation.kind === 'context') add(invocation.invocation.boundary)
+    for (const parameter of invocation.parameters) add(parameter.boundary)
+    add(invocation.result)
+  }
+  return [...imports.values()].sort((left, right) =>
+    left.specifier.localeCompare(right.specifier) || left.name.localeCompare(right.name))
+}
+
+function allocateRemoteImportNames(imports: readonly RemoteTypeImportModel[]): ReadonlyMap<SymbolId, string> {
+  const used = new Set(['TypeRTRemoteContribution', 'TYPERT_REMOTE'])
+  const names = new Map<SymbolId, string>()
+  for (const imported of imports) {
+    const base = safeIdentifier(imported.name)
+    let name = base
+    let suffix = 2
+    while (used.has(name)) name = `${base}$remote${String(suffix++)}`
+    used.add(name)
+    names.set(imported.symbol, name)
+  }
+  return names
+}
+
 function packageExportSpecifier(packageName: string, subpath: string): string {
   return subpath === '.' ? packageName : `${packageName}${subpath.slice(1)}`
 }
diff --git a/packages/typert/generator/src/model.ts b/packages/typert/generator/src/model.ts
index c6b7ffbc87..7f15c8407c 100644
--- a/packages/typert/generator/src/model.ts
+++ b/packages/typert/generator/src/model.ts
@@ -94,6 +94,56 @@ export interface SchemaModel extends DocumentationModel {
   readonly type: TypeNodeId
 }
 
+/** One public business type import retained for a generated Remote declaration. */
+export interface RemoteTypeImportModel {
+  readonly symbol: SymbolId
+  readonly specifier: string
+  readonly name: string
+}
+
+/** One strict wire boundary and the public symbols needed to name it. */
+export interface RemoteBoundaryModel {
+  /** Authored public type retained for generated consumer declarations. */
+  readonly type: TypeNodeId
+  /** Checker-resolved projection used only to emit the runtime codec. */
+  readonly codecType: TypeNodeId
+  readonly typeSymbol: string
+  readonly imports: readonly RemoteTypeImportModel[]
+}
+
+/** One ordered business argument projected onto a Remote wire field. */
+export interface InvocationParameterModel {
+  readonly name: string
+  readonly wire: string
+  readonly source: 'json' | 'lookup'
+  readonly lookup?: string
+  readonly boundary: RemoteBoundaryModel
+}
+
+/** One strictly analyzed Host method exported through TypeRT Gateway. */
+export interface InvocationModel {
+  readonly id: string
+  readonly service: string
+  readonly namespace: string
+  readonly method: string
+  readonly implementation?: string
+  readonly invocation:
+    | { readonly kind: 'direct' }
+    | {
+      readonly kind: 'context'
+      readonly context: string
+      readonly wire: string
+      readonly boundary: RemoteBoundaryModel
+    }
+  readonly scope?: {
+    readonly context: string
+    readonly wire: string
+  }
+  readonly parameters: readonly InvocationParameterModel[]
+  readonly result: RemoteBoundaryModel
+  readonly location: SourceLocation
+}
+
 /** Business semantics discovered in one package on one face. */
 export interface PackageModel {
   readonly name: string
@@ -103,6 +153,7 @@ export interface PackageModel {
   readonly events: readonly EventModel[]
   readonly objects: readonly ObjectModel[]
   readonly schemas: readonly SchemaModel[]
+  readonly invocations: readonly InvocationModel[]
 }
 
 /** One explicit import/re-export edge between independently compiled faces. */
@@ -173,6 +224,10 @@ export interface SignatureModel {
 export interface MemberBase extends DocumentationModel {
   readonly id: string
   readonly name: string
+  /** JSON property name when a literal computed key differs from source text. */
+  readonly jsonName?: string
+  /** Non-literal computed keys; symbol keys are erased from JSON schemas. */
+  readonly computed?: 'symbol' | 'dynamic'
   readonly optional: boolean
   readonly readonly: boolean
   readonly async: boolean
diff --git a/packages/typert/generator/src/renderer.ts b/packages/typert/generator/src/renderer.ts
index 8d9a3c4954..5c6fc5cb2b 100644
--- a/packages/typert/generator/src/renderer.ts
+++ b/packages/typert/generator/src/renderer.ts
@@ -81,32 +81,35 @@ export class TypeGraphRenderer {
   /**
    * Render one type expression from the retained source structure.
    * @param id - type node id.
+   * @param references - optional generated names for declaration references.
    * @returns TypeScript type text.
    */
-  renderType(id: TypeNodeId): string {
+  renderType(id: TypeNodeId, references?: ReadonlyMap<SymbolId, string>): string {
     const node = this.node(id)
     switch (node.kind) {
       case 'keyword': return node.name
       case 'literal': return node.text
-      case 'parenthesized': return `(${this.renderType(node.type)})`
+      case 'parenthesized': return `(${this.renderType(node.type, references)})`
       case 'reference': {
         const name = node.target.kind === 'type-parameter'
           ? this.parameterNames.get(node.target.parameter) ?? node.name
-          : node.name
+          : node.target.kind === 'declaration'
+            ? references?.get(node.target.symbol) ?? node.name
+            : node.name
         return node.arguments.length === 0
           ? name
-          : `${name}<${node.arguments.map(argument => this.renderType(argument)).join(', ')}>`
+          : `${name}<${node.arguments.map(argument => this.renderType(argument, references)).join(', ')}>`
       }
-      case 'union': return node.types.map(type => this.renderType(type)).join(' | ')
-      case 'intersection': return node.types.map(type => this.renderType(type)).join(' & ')
+      case 'union': return node.types.map(type => this.renderType(type, references)).join(' | ')
+      case 'intersection': return node.types.map(type => this.renderType(type, references)).join(' & ')
       case 'array': {
-        const element = this.renderType(node.element)
+        const element = this.renderType(node.element, references)
         const wrapped = needsArrayParentheses(this.node(node.element)) ? `(${element})` : element
         return `${wrapped}[]`
       }
       case 'tuple': {
         const elements = node.elements.map((element) => {
-          const type = this.renderType(element.type)
+          const type = this.renderType(element.type, references)
           if (element.name !== undefined) {
             return `${element.rest ? '...' : ''}${element.name}${element.optional ? '?' : ''}: ${type}`
           }
@@ -114,34 +117,34 @@ export class TypeGraphRenderer {
         })
         return `[${elements.join(', ')}]`
       }
-      case 'object': return this.renderObject(node.members)
-      case 'function': return `${this.renderSignatureHead(node.signature)} => ${this.renderType(node.signature.returns)}`
-      case 'constructor': return `${node.abstract ? 'abstract ' : ''}new ${this.renderSignatureHead(node.signature)} => ${this.renderType(node.signature.returns)}`
-      case 'indexed-access': return `${this.renderType(node.object)}[${this.renderType(node.index)}]`
-      case 'operator': return `${node.operator} ${this.renderType(node.type)}`
+      case 'object': return this.renderObject(node.members, references)
+      case 'function': return `${this.renderSignatureHead(node.signature, references)} => ${this.renderType(node.signature.returns, references)}`
+      case 'constructor': return `${node.abstract ? 'abstract ' : ''}new ${this.renderSignatureHead(node.signature, references)} => ${this.renderType(node.signature.returns, references)}`
+      case 'indexed-access': return `${this.renderType(node.object, references)}[${this.renderType(node.index, references)}]`
+      case 'operator': return `${node.operator} ${this.renderType(node.type, references)}`
       case 'conditional': {
-        return `${this.renderType(node.check)} extends ${this.renderType(node.extends)} ? ${this.renderType(node.whenTrue)} : ${this.renderType(node.whenFalse)}`
+        return `${this.renderType(node.check, references)} extends ${this.renderType(node.extends, references)} ? ${this.renderType(node.whenTrue, references)} : ${this.renderType(node.whenFalse, references)}`
       }
-      case 'infer': return `infer ${this.renderTypeParameter(node.parameter, false)}`
+      case 'infer': return `infer ${this.renderTypeParameter(node.parameter, false, references)}`
       case 'mapped': {
         const readonly = node.readonly === 'preserve' ? '' : node.readonly === 'remove' ? '-readonly ' : 'readonly '
         const optional = node.optional === 'preserve' ? '' : node.optional === 'remove' ? '-?' : '?'
         if (node.parameter.constraint === undefined) {
           throw new TypeGraphRenderError(`mapped type parameter ${node.parameter.name} has no constraint`)
         }
-        const parameter = `${node.parameter.name} in ${this.renderType(node.parameter.constraint)}`
-        const nameType = node.nameType === undefined ? '' : ` as ${this.renderType(node.nameType)}`
-        const value = node.value === undefined ? 'unknown' : this.renderType(node.value)
+        const parameter = `${node.parameter.name} in ${this.renderType(node.parameter.constraint, references)}`
+        const nameType = node.nameType === undefined ? '' : ` as ${this.renderType(node.nameType, references)}`
+        const value = node.value === undefined ? 'unknown' : this.renderType(node.value, references)
         return `{ ${readonly}[${parameter}${nameType}]${optional}: ${value} }`
       }
       case 'template-literal': {
-        const spans = node.spans.map(span => `\${${this.renderType(span.type)}}${escapeTemplate(span.text)}`).join('')
+        const spans = node.spans.map(span => `\${${this.renderType(span.type, references)}}${escapeTemplate(span.text)}`).join('')
         return `\`${escapeTemplate(node.head)}${spans}\``
       }
       case 'type-query': {
         const argumentsText = node.arguments.length === 0
           ? ''
-          : `<${node.arguments.map(argument => this.renderType(argument)).join(', ')}>`
+          : `<${node.arguments.map(argument => this.renderType(argument, references)).join(', ')}>`
         return `typeof ${node.expression}${argumentsText}`
       }
       case 'import-type': {
@@ -149,14 +152,14 @@ export class TypeGraphRenderer {
         const imported = `import(${quote(node.module)}${attributes})${node.qualifier === undefined ? '' : `.${node.qualifier}`}`
         const argumentsText = node.arguments.length === 0
           ? ''
-          : `<${node.arguments.map(argument => this.renderType(argument)).join(', ')}>`
+          : `<${node.arguments.map(argument => this.renderType(argument, references)).join(', ')}>`
         return `${node.typeof ? 'typeof ' : ''}${imported}${argumentsText}`
       }
       case 'predicate': {
         const assertion = node.asserts ? 'asserts ' : ''
         return node.type === undefined
           ? `${assertion}${node.parameter}`
-          : `${assertion}${node.parameter} is ${this.renderType(node.type)}`
+          : `${assertion}${node.parameter} is ${this.renderType(node.type, references)}`
       }
       case 'this': return 'this'
       default: return assertNever(node)
@@ -166,34 +169,36 @@ export class TypeGraphRenderer {
   /**
    * Render a callable signature without a member name.
    * @param signature - modeled signature.
+   * @param references - optional generated names for declaration references.
    * @returns parameter list and return type.
    */
-  renderSignature(signature: SignatureModel): string {
-    return `${this.renderSignatureHead(signature)}: ${this.renderType(signature.returns)}`
+  renderSignature(signature: SignatureModel, references?: ReadonlyMap<SymbolId, string>): string {
+    return `${this.renderSignatureHead(signature, references)}: ${this.renderType(signature.returns, references)}`
   }
 
   /**
    * Render one class/interface member as a body-free declaration.
    * @param member - modeled member.
    * @param sourceModifiers - retain source-only modifiers for reflection text.
+   * @param references - optional generated names for declaration references.
    * @returns one-line TypeScript member text.
    */
-  renderMember(member: MemberModel, sourceModifiers = false): string {
+  renderMember(member: MemberModel, sourceModifiers = false, references?: ReadonlyMap<SymbolId, string>): string {
     if (sourceModifiers) return member.text
     const name = renderPropertyName(member.name)
     const optional = member.optional ? '?' : ''
     const readonly = member.readonly ? 'readonly ' : ''
     const abstract = member.abstract ? 'abstract ' : ''
     switch (member.kind) {
-      case 'property': return `${abstract}${readonly}${name}${optional}: ${this.renderType(member.type)}`
-      case 'method': return `${abstract}${name}${optional}${this.renderSignature(member.signature)}`
-      case 'getter': return `${abstract}get ${name}()${this.renderReturn(member.signature)}`
-      case 'setter': return `${abstract}set ${name}${this.renderSignatureHead(member.signature)}`
-      case 'call': return this.renderSignature(member.signature)
-      case 'construct': return `new ${this.renderSignature(member.signature)}`
+      case 'property': return `${abstract}${readonly}${name}${optional}: ${this.renderType(member.type, references)}`
+      case 'method': return `${abstract}${name}${optional}${this.renderSignature(member.signature, references)}`
+      case 'getter': return `${abstract}get ${name}()${this.renderReturn(member.signature, references)}`
+      case 'setter': return `${abstract}set ${name}${this.renderSignatureHead(member.signature, references)}`
+      case 'call': return this.renderSignature(member.signature, references)
+      case 'construct': return `new ${this.renderSignature(member.signature, references)}`
       case 'index': {
-        const parameters = member.signature.parameters.map(parameter => this.renderParameter(parameter)).join(', ')
-        return `${readonly}[${parameters}]: ${this.renderType(member.signature.returns)}`
+        const parameters = member.signature.parameters.map(parameter => this.renderParameter(parameter, references)).join(', ')
+        return `${readonly}[${parameters}]: ${this.renderType(member.signature.returns, references)}`
       }
       default: return assertNever(member)
     }
@@ -290,38 +295,42 @@ export class TypeGraphRenderer {
     return this.graph.declarations.filter(declaration => found.has(declaration.id))
   }
 
-  private renderSignatureHead(signature: SignatureModel): string {
-    return `${this.renderTypeParameters(signature.typeParameters)}(${signature.parameters.map(parameter => this.renderParameter(parameter)).join(', ')})`
+  private renderSignatureHead(signature: SignatureModel, references?: ReadonlyMap<SymbolId, string>): string {
+    return `${this.renderTypeParameters(signature.typeParameters, references)}(${signature.parameters.map(parameter => this.renderParameter(parameter, references)).join(', ')})`
   }
 
-  private renderReturn(signature: SignatureModel): string {
-    return `: ${this.renderType(signature.returns)}`
+  private renderReturn(signature: SignatureModel, references?: ReadonlyMap<SymbolId, string>): string {
+    return `: ${this.renderType(signature.returns, references)}`
   }
 
-  private renderParameter(parameter: ParameterModel): string {
+  private renderParameter(parameter: ParameterModel, references?: ReadonlyMap<SymbolId, string>): string {
     const name = parameter.binding === 'identifier' ? renderPropertyName(parameter.name) : parameter.name
     const optional = parameter.initializer === undefined && parameter.optional && !parameter.rest ? '?' : ''
     const initializer = parameter.initializer === undefined ? '' : ` = ${parameter.initializer}`
-    return `${parameter.rest ? '...' : ''}${name}${optional}: ${this.renderType(parameter.type)}${initializer}`
+    return `${parameter.rest ? '...' : ''}${name}${optional}: ${this.renderType(parameter.type, references)}${initializer}`
   }
 
-  private renderTypeParameters(parameters: readonly TypeParameterModel[]): string {
+  private renderTypeParameters(parameters: readonly TypeParameterModel[], references?: ReadonlyMap<SymbolId, string>): string {
     return parameters.length === 0
       ? ''
-      : `<${parameters.map(parameter => this.renderTypeParameter(parameter, true)).join(', ')}>`
+      : `<${parameters.map(parameter => this.renderTypeParameter(parameter, true, references)).join(', ')}>`
   }
 
-  private renderTypeParameter(parameter: TypeParameterModel, includeDefault: boolean): string {
+  private renderTypeParameter(
+    parameter: TypeParameterModel,
+    includeDefault: boolean,
+    references?: ReadonlyMap<SymbolId, string>,
+  ): string {
     const variance = parameter.variance === undefined ? '' : `${parameter.variance === 'in-out' ? 'in out' : parameter.variance} `
     const constModifier = parameter.const ? 'const ' : ''
-    const constraint = parameter.constraint === undefined ? '' : ` extends ${this.renderType(parameter.constraint)}`
-    const fallback = !includeDefault || parameter.default === undefined ? '' : ` = ${this.renderType(parameter.default)}`
+    const constraint = parameter.constraint === undefined ? '' : ` extends ${this.renderType(parameter.constraint, references)}`
+    const fallback = !includeDefault || parameter.default === undefined ? '' : ` = ${this.renderType(parameter.default, references)}`
     return `${constModifier}${variance}${parameter.name}${constraint}${fallback}`
   }
 
-  private renderObject(members: readonly MemberModel[]): string {
+  private renderObject(members: readonly MemberModel[], references?: ReadonlyMap<SymbolId, string>): string {
     if (members.length === 0) return '{}'
-    return `{ ${members.map(member => `${this.renderMember(member)};`).join(' ')} }`
+    return `{ ${members.map(member => `${this.renderMember(member, false, references)};`).join(' ')} }`
   }
 
   private indexParameters(parameters: readonly TypeParameterModel[]): void {
diff --git a/packages/typert/generator/src/tsdown-plugin.ts b/packages/typert/generator/src/tsdown-plugin.ts
index 9254eeb16d..a5c6ef93e2 100644
--- a/packages/typert/generator/src/tsdown-plugin.ts
+++ b/packages/typert/generator/src/tsdown-plugin.ts
@@ -2,7 +2,7 @@
  * Optional tsdown (rolldown) plugin face of the typert generator. When added
  * to a workspace tsdown config, it runs after each opted-in package bundle is
  * written and re-emits its model-driven face artifact at the package output
- * root. Packages without a Typert export are skipped.
+ * root. Packages without a Typert or Remote export are skipped.
  * @module @deepseek-ai/dsh-typert-generator/tsdown
  */
 
@@ -10,6 +10,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { WorkspaceTypertGenerator } from './workspace.ts'
 import type { WorkspaceEmitResult } from './workspace.ts'
+import type { TypertFace } from './model.ts'
 
 /** The subset of the rolldown output-plugin contract this plugin uses (structural; avoids a rolldown type dependency). */
 interface TypertPlugin {
@@ -17,21 +18,37 @@ interface TypertPlugin {
   writeBundle: (options: { dir?: string }) => void
 }
 
+/** Generation scope selected by a tsdown build phase. */
+export interface TypertPluginOptions {
+  /** Package mode emits only the package being bundled; workspace mode emits every explicit contributor once. */
+  readonly mode?: 'package' | 'workspace'
+  /** Independent TypeScript program faces included in this phase. */
+  readonly faces?: readonly TypertFace[]
+}
+
 /**
  * Create the typert generation plugin for the root tsdown config.
- * @returns a rolldown-compatible plugin that emits `lib/typert.<face>.js` and `.d.ts` for contributing packages.
+ * @param pluginOptions - package/workspace emission mode and independent program faces.
+ * @returns a rolldown-compatible plugin that emits local face and Host-for-Client Remote artifacts.
  */
-export function typertPlugin(): TypertPlugin {
+export function typertPlugin(pluginOptions: TypertPluginOptions = {}): TypertPlugin {
   const artifactsByRoot = new Map<string, readonly WorkspaceEmitResult[]>()
+  const emittedWorkspaces = new Set<string>()
   return {
     name: 'dsh-typert-generator',
-    writeBundle(options) {
+    writeBundle(bundleOptions) {
       // options.dir is the package's absolute outDir (<package>/lib); its
       // nearest package.json owns the bundle even when a custom config writes
       // a nested output such as <package>/lib/dev.
-      if (options.dir === undefined) return
-      const root = workspaceRoot(options.dir)
-      const packageDir = packageRoot(options.dir, root)
+      if (bundleOptions.dir === undefined) return
+      const root = workspaceRoot(bundleOptions.dir)
+      if (emittedWorkspaces.has(root)) return
+      if (pluginOptions.mode === 'workspace') {
+        emitWorkspace(root, pluginOptions.faces)
+        emittedWorkspaces.add(root)
+        return
+      }
+      const packageDir = packageRoot(bundleOptions.dir, root)
       if (packageDir === undefined) return
       const manifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8')) as {
         name?: string
@@ -40,22 +57,54 @@ export function typertPlugin(): TypertPlugin {
       if (manifest.name === undefined || !hasTypertExport(manifest.exports)) return
       let artifacts = artifactsByRoot.get(root)
       if (artifacts === undefined) {
-        artifacts = new WorkspaceTypertGenerator(root).generate()
+        const generator = new WorkspaceTypertGenerator(root)
+        artifacts = pluginOptions.faces === undefined
+          ? generator.generate()
+          : generator.generate(undefined, pluginOptions.faces)
         artifactsByRoot.set(root, artifacts)
       }
-      const output = join(packageDir, 'lib')
-      mkdirSync(output, { recursive: true })
-      for (const artifact of artifacts.filter(candidate => candidate.package === manifest.name)) {
-        writeFileSync(join(output, `typert.${artifact.face}.js`), artifact.js)
-        writeFileSync(join(output, `typert.${artifact.face}.d.ts`), artifact.dts)
-      }
+      emitArtifacts(packageDir, artifacts.filter(candidate => candidate.package === manifest.name))
     },
   }
+
+  function emitWorkspace(root: string, faces: readonly TypertFace[] | undefined): void {
+    const generator = new WorkspaceTypertGenerator(root)
+    const packages = generator.discover(faces)
+      .filter(candidate => hasTypertExport(readManifest(join(root, candidate.root)).exports))
+      .map(candidate => candidate.package)
+    if (packages.length === 0) return
+    for (const artifact of generator.generate(packages, faces)) {
+      emitArtifacts(join(root, artifact.packageRoot), [artifact])
+    }
+  }
+}
+
+function emitArtifacts(packageDir: string, artifacts: readonly WorkspaceEmitResult[]): void {
+  const output = join(packageDir, 'lib')
+  mkdirSync(output, { recursive: true })
+  for (const artifact of artifacts) {
+    writeFileSync(join(output, `typert.${artifact.face}.js`), artifact.js)
+    writeFileSync(join(output, `typert.${artifact.face}.d.ts`), artifact.dts)
+    if (artifact.remote !== undefined) {
+      writeFileSync(join(output, 'typert.remote-client.js'), artifact.remote.js)
+      writeFileSync(join(output, 'typert.remote-client.d.ts'), artifact.remote.dts)
+      writeFileSync(join(output, 'typert.remote-client.d.ts.map'), artifact.remote.dtsMap)
+    }
+  }
+}
+
+function readManifest(packageDir: string): { name?: string; exports?: unknown } {
+  return JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8')) as {
+    name?: string
+    exports?: unknown
+  }
 }
 
 function hasTypertExport(exportsField: unknown): boolean {
   if (exportsField === null || typeof exportsField !== 'object' || Array.isArray(exportsField)) return false
-  return Object.hasOwn(exportsField, './typert') || Object.hasOwn(exportsField, './client/typert')
+  return Object.hasOwn(exportsField, './typert')
+    || Object.hasOwn(exportsField, './client/typert')
+    || Object.hasOwn(exportsField, './remote')
 }
 
 function packageRoot(start: string, workspace: string): string | undefined {
diff --git a/packages/typert/generator/src/workspace.ts b/packages/typert/generator/src/workspace.ts
index 6153a0241a..c79861a796 100644
--- a/packages/typert/generator/src/workspace.ts
+++ b/packages/typert/generator/src/workspace.ts
@@ -9,6 +9,7 @@ import { TypertAnalysisError, WorkspaceAnalyzer } from './analyzer.ts'
 import type { DiscoveredTypertPackage } from './analyzer.ts'
 import { FaceModelEmitter } from './emitter.ts'
 import type { ModelEmitResult } from './emitter.ts'
+import type { TypertFace } from './model.ts'
 
 /** One emitted artifact paired with its source package root. */
 export interface WorkspaceEmitResult extends ModelEmitResult {
@@ -26,20 +27,29 @@ export class WorkspaceTypertGenerator {
   /**
    * Find public package faces that contribute Cordis services/events or
    * explicitly tagged Typert roots.
+   * @param faces - optional independent program faces to inspect.
    * @returns discovered packages in stable package-name order.
    */
-  discover(): DiscoveredTypertPackage[] {
-    return new WorkspaceAnalyzer({ root: this.root }).discoverPackages()
+  discover(faces?: readonly TypertFace[]): DiscoveredTypertPackage[] {
+    return new WorkspaceAnalyzer({
+      root: this.root,
+      ...(faces === undefined ? {} : { faces }),
+    }).discoverPackages()
   }
 
   /**
    * Generate all discovered contributors, or an explicit package subset.
    * @param packages - optional exact package names for a focused pass.
+   * @param faces - optional independent program faces to analyze.
    * @returns one artifact per package face.
    */
-  generate(packages?: readonly string[]): WorkspaceEmitResult[] {
-    const selected = packages ?? this.discover().map(candidate => candidate.package)
-    const workspace = new WorkspaceAnalyzer({ root: this.root, packages: selected }).analyze()
+  generate(packages?: readonly string[], faces?: readonly TypertFace[]): WorkspaceEmitResult[] {
+    const selected = packages ?? this.discover(faces).map(candidate => candidate.package)
+    const workspace = new WorkspaceAnalyzer({
+      root: this.root,
+      packages: selected,
+      ...(faces === undefined ? {} : { faces }),
+    }).analyze()
     const artifacts: WorkspaceEmitResult[] = []
     for (const face of workspace.faces) {
       const emitter = new FaceModelEmitter(face)
@@ -80,6 +90,28 @@ export class WorkspaceTypertGenerator {
         throw new TypertAnalysisError(`typert(${artifact.face}): ${artifact.package} package files must include ${file}`)
       }
     }
+    if (artifact.remote === undefined) return
+    const remoteExpected = {
+      types: './lib/typert.remote-client.d.ts',
+      default: './lib/typert.remote-client.js',
+    }
+    const remoteActual = manifest.exports !== null && typeof manifest.exports === 'object'
+      ? (manifest.exports as Record<string, unknown>)['./remote']
+      : undefined
+    if (!sameExport(remoteActual, remoteExpected)) {
+      throw new TypertAnalysisError(
+        `typert(host): ${artifact.package} must export ./remote as ${JSON.stringify(remoteExpected)}`,
+      )
+    }
+    for (const file of [
+      'lib/typert.remote-client.js',
+      'lib/typert.remote-client.d.ts',
+      'lib/typert.remote-client.d.ts.map',
+    ]) {
+      if (!files.includes(file)) {
+        throw new TypertAnalysisError(`typert(host): ${artifact.package} package files must include ${file}`)
+      }
+    }
   }
 }
 
diff --git a/packages/typert/generator/tests/__snapshots__/type-model.spec.ts.snap b/packages/typert/generator/tests/__snapshots__/type-model.spec.ts.snap
index aad86b0102..bcc28cd8b2 100644
--- a/packages/typert/generator/tests/__snapshots__/type-model.spec.ts.snap
+++ b/packages/typert/generator/tests/__snapshots__/type-model.spec.ts.snap
@@ -17,6 +17,8 @@ export const TYPERT = {
   schemas: [
     { name: 'Payload', schema: Payload },
   ],
+  invocations: [
+  ],
   model: {
     "services": [
       {
@@ -3815,6 +3817,7 @@ exports[`WorkspaceAnalyzer > builds independent face models with an explicit cro
                 "abstract": false,
                 "async": false,
                 "id": "type:packages/host/src/models.ts:123:11#1#['computed']@3756",
+                "jsonName": "computed",
                 "kind": "property",
                 "location": {
                   "column": 5,
@@ -5634,6 +5637,7 @@ exports[`WorkspaceAnalyzer > builds independent face models with an explicit cro
               "symbol": "@fixture/host:packages/host/src/models.ts#Variance",
             },
           ],
+          "invocations": [],
           "name": "@fixture/host",
           "objects": [
             {
@@ -6449,6 +6453,7 @@ exports[`WorkspaceAnalyzer > builds independent face models with an explicit cro
               "symbol": "<external>:../../../../../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/schemas.d.cts#ZodType",
             },
           ],
+          "invocations": [],
           "name": "@fixture/client",
           "objects": [],
           "root": "packages/client",
diff --git a/packages/typert/generator/tests/fixtures/remote-model/package.json b/packages/typert/generator/tests/fixtures/remote-model/package.json
new file mode 100644
index 0000000000..00ac86bdcc
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "@fixture/remote-workspace",
+  "private": true,
+  "type": "module"
+}
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/domain/package.json b/packages/typert/generator/tests/fixtures/remote-model/packages/domain/package.json
new file mode 100644
index 0000000000..bf6b2bd110
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/domain/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "@fixture/domain",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts"
+  }
+}
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/domain/src/index.ts b/packages/typert/generator/tests/fixtures/remote-model/packages/domain/src/index.ts
new file mode 100644
index 0000000000..e5c2850cf2
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/domain/src/index.ts
@@ -0,0 +1,19 @@
+import type { TypeRTContext, TypeRTLookup } from '@deepseek-ai/dsh-type-meta'
+import type { AgentId } from './types.ts'
+
+/** Host-only live Agent object. */
+export class Agent {
+  constructor(readonly id: AgentId) {}
+}
+
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTLookupMap {
+    agent: TypeRTLookup<Agent, AgentId>
+  }
+
+  interface TypeRTContextMap {
+    agent: TypeRTContext<AgentId>
+  }
+}
+
+export type { AgentId } from './types.ts'
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/domain/src/types.ts b/packages/typert/generator/tests/fixtures/remote-model/packages/domain/src/types.ts
new file mode 100644
index 0000000000..944201e82a
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/domain/src/types.ts
@@ -0,0 +1,2 @@
+/** Stable Agent identity crossing the Remote boundary. */
+export type AgentId = string
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/domain/tsconfig.json b/packages/typert/generator/tests/fixtures/remote-model/packages/domain/tsconfig.json
new file mode 100644
index 0000000000..1ddc9b1a60
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/domain/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true
+  },
+  "include": ["src"]
+}
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/remote/package.json b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/package.json
new file mode 100644
index 0000000000..b7e0631a0a
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "@fixture/remote",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    }
+  },
+  "files": [
+    "lib/typert.host.js",
+    "lib/typert.host.d.ts",
+    "lib/typert.remote-client.js",
+    "lib/typert.remote-client.d.ts",
+    "lib/typert.remote-client.d.ts.map"
+  ]
+}
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
new file mode 100644
index 0000000000..816a13a5a7
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
@@ -0,0 +1,30 @@
+import { Remote, RemoteContext, bindTypeRTGateway } from '@deepseek-ai/dsh-type-meta'
+import type { Agent } from '@fixture/domain'
+import type {
+  CreateGoalRequest,
+  CreateGoalResult,
+  RenameGoalRequest,
+  RenameGoalResult,
+} from './types.ts'
+
+/** Remote-only business Service with no Cordis declaration merge. */
+export class GoalService {
+  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+
+  @Remote
+  async create(agent: Agent, request: CreateGoalRequest): Promise<CreateGoalResult> {
+    return { ref: `${agent.id}:${request.title}` }
+  }
+
+  @RemoteContext('agent')
+  rename(request: RenameGoalRequest): RenameGoalResult {
+    return { renamed: request.title.length > 0 }
+  }
+}
+
+export type {
+  CreateGoalRequest,
+  CreateGoalResult,
+  RenameGoalRequest,
+  RenameGoalResult,
+} from './types.ts'
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/types.ts b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/types.ts
new file mode 100644
index 0000000000..88493325f8
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/types.ts
@@ -0,0 +1,20 @@
+/** Input accepted by Goal creation. */
+export interface CreateGoalRequest {
+  readonly title: string
+}
+
+/** Wire-safe Goal creation result. */
+export interface CreateGoalResult {
+  readonly ref: string
+}
+
+/** Input accepted by scoped Goal renaming. */
+export interface RenameGoalRequest {
+  readonly ref: string
+  readonly title: string
+}
+
+/** Wire-safe Goal rename result. */
+export interface RenameGoalResult {
+  readonly renamed: boolean
+}
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/remote/tsconfig.json b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/tsconfig.json
new file mode 100644
index 0000000000..534b3c3d75
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../domain" }
+  ]
+}
diff --git a/packages/typert/generator/tests/fixtures/remote-model/tsconfig.base.json b/packages/typert/generator/tests/fixtures/remote-model/tsconfig.base.json
new file mode 100644
index 0000000000..4aaf57160d
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/tsconfig.base.json
@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "composite": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "ignoreDeprecations": "6.0",
+    "paths": {
+      "@deepseek-ai/dsh-type-meta": ["./type-meta.d.ts"],
+      "@fixture/domain": ["./packages/domain/src/index.ts"],
+      "@fixture/domain/*": ["./packages/domain/src/*"],
+      "@fixture/remote": ["./packages/remote/src/index.ts"],
+      "@fixture/remote/*": ["./packages/remote/src/*"]
+    },
+    "skipLibCheck": true
+  }
+}
diff --git a/packages/typert/generator/tests/fixtures/remote-model/tsconfig.host.json b/packages/typert/generator/tests/fixtures/remote-model/tsconfig.host.json
new file mode 100644
index 0000000000..7797b7ff29
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/tsconfig.host.json
@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.base.json",
+  "files": [],
+  "references": [
+    { "path": "./packages/domain" },
+    { "path": "./packages/remote" }
+  ]
+}
diff --git a/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts b/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
new file mode 100644
index 0000000000..f8e84bbe90
--- /dev/null
+++ b/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
@@ -0,0 +1,45 @@
+declare module '@deepseek-ai/dsh-type-meta' {
+  export interface TypeRTLookup<Host, Wire> {
+    readonly host: Host
+    readonly wire: Wire
+  }
+
+  export interface TypeRTContext<Wire> {
+    readonly wire: Wire
+  }
+
+  export interface TypeRTLookupMap {}
+  export interface TypeRTContextMap {}
+  export interface TypeRTRemoteMap {}
+  export interface TypeRTRemoteContextMap {}
+
+  export type TypeRTRemoteNamespace<Namespace extends string> = {
+    [Endpoint in keyof TypeRTRemoteMap as Endpoint extends `${Namespace}/${infer Method}`
+      ? Method
+      : never]: TypeRTRemoteMap[Endpoint]
+  }
+
+  export interface TypeRTRemoteNamespaceMap {}
+
+  export interface TypeRTRemoteContribution {
+    readonly package: string
+    readonly descriptors: readonly unknown[]
+  }
+
+  export function bindTypeRTGateway<Service extends object>(
+    service: Service,
+    serviceKey: string,
+    options?: { readonly namespace?: string },
+  ): { readonly service: Service; readonly serviceKey: string; readonly namespace: string }
+
+  export function Remote<This extends object, Args extends unknown[], Result>(
+    method: (this: This, ...args: Args) => Result,
+    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
+  ): void
+
+  export function RemoteContext(key: Extract<keyof TypeRTContextMap, string>):
+  <This extends object, Args extends unknown[], Result>(
+    method: (this: This, ...args: Args) => Result,
+    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
+  ) => void
+}
diff --git a/packages/typert/generator/tests/remote-model.spec.ts b/packages/typert/generator/tests/remote-model.spec.ts
new file mode 100644
index 0000000000..90056e673e
--- /dev/null
+++ b/packages/typert/generator/tests/remote-model.spec.ts
@@ -0,0 +1,486 @@
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import ts from 'typescript'
+import { afterEach, describe, expect, it } from 'vitest'
+import { WorkspaceAnalyzer } from '../src/analyzer.ts'
+import type { InvocationModel } from '../src/model.ts'
+import { WorkspaceTypertGenerator } from '../src/workspace.ts'
+
+const fixtureRoot = resolve(import.meta.dirname, 'fixtures/remote-model')
+const temporaryRoots: string[] = []
+
+interface RuntimeSchema {
+  safeParse(value: unknown): { readonly success: boolean }
+}
+
+interface RuntimeDescriptor {
+  readonly id: string
+  readonly parameters: readonly {
+    readonly wire: string
+    readonly codec: { readonly schema: RuntimeSchema }
+  }[]
+  readonly result: { readonly schema: RuntimeSchema }
+}
+
+interface RuntimeRemoteModule {
+  readonly TYPERT_REMOTE: {
+    readonly package: string
+    readonly descriptors: readonly RuntimeDescriptor[]
+  }
+}
+
+interface RemoteDeclarationMap {
+  readonly file: string
+  readonly names: readonly string[]
+  readonly sources: readonly string[]
+}
+
+afterEach(() => {
+  for (const root of temporaryRoots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+describe('Remote model generation', { timeout: 60_000 }, () => {
+  it('discovers a Remote-only package and emits strict direct and Context descriptors', async () => {
+    const generator = new WorkspaceTypertGenerator(fixtureRoot)
+
+    expect(generator.discover()).toEqual([{
+      package: '@fixture/remote',
+      root: 'packages/remote',
+      faces: ['host'],
+    }])
+
+    const [artifact] = generator.generate()
+    expect(artifact).toBeDefined()
+    expect(artifact).toMatchObject({
+      package: '@fixture/remote',
+      face: 'host',
+      packageRoot: 'packages/remote',
+    })
+
+    const model = remotePackage(fixtureRoot)
+    expect(model.services).toEqual([])
+    expect(model.invocations).toHaveLength(2)
+    expect(model.invocations[0]).toMatchObject({
+      id: '@fixture/remote#goals/create',
+      service: 'goals',
+      namespace: 'goals',
+      method: 'create',
+      invocation: { kind: 'direct' },
+      scope: { context: 'agent', wire: 'agentId' },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          boundary: { typeSymbol: '@fixture/domain/types#AgentId' },
+        },
+        {
+          name: 'request',
+          wire: 'request',
+          source: 'json',
+          boundary: { typeSymbol: '@fixture/remote/types#CreateGoalRequest' },
+        },
+      ],
+      result: { typeSymbol: '@fixture/remote/types#CreateGoalResult' },
+    })
+    expect(model.invocations[1]).toMatchObject({
+      id: '@fixture/remote#goals/rename',
+      service: 'goals',
+      namespace: 'goals',
+      method: 'rename',
+      invocation: {
+        kind: 'context',
+        context: 'agent',
+        wire: 'agentId',
+        boundary: { typeSymbol: '@fixture/domain/types#AgentId' },
+      },
+      parameters: [{
+        name: 'request',
+        wire: 'request',
+        source: 'json',
+        boundary: { typeSymbol: '@fixture/remote/types#RenameGoalRequest' },
+      }],
+      result: { typeSymbol: '@fixture/remote/types#RenameGoalResult' },
+    })
+
+    expect(artifact?.js).toContain('invocations: [')
+    expect(artifact?.remote?.dts).toContain(
+      "'goals/create': (agentId: AgentId, request: CreateGoalRequest) => Promise<CreateGoalResult>",
+    )
+    expect(artifact?.remote?.dts).toContain('interface TypeRTRemoteNamespace$676f616c73 {\n    create:')
+    expect(artifact?.remote?.dts).toContain("'goals': TypeRTRemoteNamespace$676f616c73")
+    expect(artifact?.remote?.dts).toContain(
+      "'agent:goals/create': (request: CreateGoalRequest) => Promise<CreateGoalResult>",
+    )
+    expect(artifact?.remote?.dts).toContain(
+      "'agent:goals/rename': (request: RenameGoalRequest) => Promise<RenameGoalResult>",
+    )
+
+    const remoteJs = artifact?.remote?.js
+    if (remoteJs === undefined) throw new Error('Remote fixture emitted no Host-for-Client JavaScript')
+    const executable = remoteJs.replace("from 'zod'", `from ${JSON.stringify(import.meta.resolve('zod'))}`)
+    const generated = await import(`data:text/javascript,${encodeURIComponent(executable)}`) as RuntimeRemoteModule
+    expect(generated.TYPERT_REMOTE.package).toBe('@fixture/remote')
+    const create = generated.TYPERT_REMOTE.descriptors[0]
+    expect(create?.parameters[1]?.codec.schema.safeParse({ title: 'ship' }).success).toBe(true)
+    expect(create?.parameters[1]?.codec.schema.safeParse({ title: 1 }).success).toBe(false)
+    expect(create?.result.schema.safeParse({ ref: 'goal-1' }).success).toBe(true)
+    expect(create?.result.schema.safeParse({ ref: 1 }).success).toBe(false)
+
+    const declarationMap = JSON.parse(artifact?.remote?.dtsMap ?? '') as RemoteDeclarationMap
+    expect(declarationMap).toMatchObject({
+      file: 'typert.remote-client.d.ts',
+      sources: ['../src/index.ts'],
+    })
+    expect(declarationMap.names).toContain('create')
+
+    assertRemoteConsumerTypechecks(artifact?.remote?.dts, artifact?.remote?.dtsMap)
+  })
+
+  it('evaluates declaration-merged mapped and conditional boundaries for codecs without widening consumer types', async () => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/types.ts', source => `${source}
+
+/** Recursive JSON fixture used by the concrete codec projection. */
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json }
+
+/** Merge-extensible operation table represented by concrete fixture entries. */
+export interface GenericRemoteMap {
+  ship: {
+    readonly request: { readonly count: number; readonly meta: Json }
+    readonly result: { readonly accepted: boolean }
+  }
+  cancel: {
+    readonly request: { readonly reason: string }
+    readonly result: { readonly cancelled: boolean }
+  }
+}
+
+type GenericRemoteKey = Extract<keyof GenericRemoteMap, string>
+type RequestOf<K extends GenericRemoteKey> = GenericRemoteMap[K] extends { readonly request: infer Request }
+  ? Request
+  : never
+type ResultOf<K extends GenericRemoteKey> = GenericRemoteMap[K] extends { readonly result: infer Result }
+  ? Result
+  : never
+
+/** Strict request union retained in the generated Client declaration. */
+export type GenericRequest = {
+  [K in GenericRemoteKey]: { readonly kind: K; readonly payload: RequestOf<K> }
+}[GenericRemoteKey]
+
+/** Strict result union retained in the generated Client declaration. */
+export type GenericResult = {
+  [K in GenericRemoteKey]: { readonly kind: K; readonly value: ResultOf<K> }
+}[GenericRemoteKey]
+`)
+    editFile(root, 'packages/remote/src/index.ts', source => source
+      .replace(
+        '  RenameGoalResult,\n',
+        '  RenameGoalResult,\n  GenericRequest,\n  GenericResult,\n',
+      )
+      .replace(
+        '  rename(request: RenameGoalRequest): RenameGoalResult {\n    return { renamed: request.title.length > 0 }\n  }\n}',
+        `  rename(request: RenameGoalRequest): RenameGoalResult {
+    return { renamed: request.title.length > 0 }
+  }
+
+  @Remote
+  dispatch(request: GenericRequest): GenericResult {
+    if (request.kind === 'ship') return { kind: 'ship', value: { accepted: request.payload.count > 0 } }
+    return { kind: 'cancel', value: { cancelled: request.payload.reason.length > 0 } }
+  }
+}`,
+      ))
+
+    const [artifact] = new WorkspaceTypertGenerator(root).generate()
+    expect(artifact?.remote?.dts).toContain(
+      "'goals/dispatch': (request: GenericRequest) => Promise<GenericResult>",
+    )
+    const remoteJs = artifact?.remote?.js
+    if (remoteJs === undefined) throw new Error('generic Remote fixture emitted no Host-for-Client JavaScript')
+    const executable = remoteJs.replace("from 'zod'", `from ${JSON.stringify(import.meta.resolve('zod'))}`)
+    const generated = await import(`data:text/javascript,${encodeURIComponent(executable)}`) as RuntimeRemoteModule
+    const dispatch = generated.TYPERT_REMOTE.descriptors.find(descriptor => descriptor.id.endsWith('/dispatch'))
+    const schema = dispatch?.parameters[0]?.codec.schema
+    expect(schema?.safeParse({ kind: 'ship', payload: { count: 2, meta: { nested: [true, null] } } }).success).toBe(true)
+    expect(schema?.safeParse({ kind: 'ship', payload: { count: '2', meta: {} } }).success).toBe(false)
+    expect(schema?.safeParse({ kind: 'cancel', payload: { reason: 'obsolete' } }).success).toBe(true)
+    expect(schema?.safeParse({ kind: 'unknown', payload: {} }).success).toBe(false)
+    expect(dispatch?.result.schema.safeParse({ kind: 'ship', value: { accepted: true } }).success).toBe(true)
+    expect(dispatch?.result.schema.safeParse({ kind: 'ship', value: { cancelled: true } }).success).toBe(false)
+  })
+
+  it.each([
+    {
+      name: 'missing binding',
+      edit: (source: string) => source.replace("  readonly typertGateway = bindTypeRTGateway(this, 'goals')\n\n", ''),
+      message: 'Remote methods require readonly typertGateway',
+    },
+    {
+      name: 'private method',
+      edit: (source: string) => source.replace('  async create(', '  private async create('),
+      message: 'Remote decorators require a public instance method',
+    },
+    {
+      name: 'static method',
+      edit: (source: string) => source.replace('  async create(', '  static async create('),
+      message: 'Remote decorators require a public instance method',
+    },
+    {
+      name: 'abstract method',
+      edit: (source: string) => source
+        .replace('export class GoalService', 'export abstract class GoalService')
+        .replace(
+          '  async create(agent: Agent, request: CreateGoalRequest): Promise<CreateGoalResult> {\n    return { ref: `${agent.id}:${request.title}` }\n  }',
+          '  abstract create(agent: Agent, request: CreateGoalRequest): Promise<CreateGoalResult>',
+        ),
+      message: 'Remote methods must have a concrete implementation',
+    },
+    {
+      name: 'generic method',
+      edit: (source: string) => source.replace('  async create(', '  async create<Value>('),
+      message: 'generic Remote methods are not supported',
+    },
+    {
+      name: 'destructured parameter',
+      edit: (source: string) => source.replace('request: CreateGoalRequest', '{ title }: CreateGoalRequest'),
+      message: 'Remote parameters must use identifier bindings',
+    },
+    {
+      name: 'rest parameter',
+      edit: (source: string) => source.replace('request: CreateGoalRequest', '...request: [CreateGoalRequest]'),
+      message: 'Remote parameters cannot be rest parameters',
+    },
+    {
+      name: 'default parameter',
+      edit: (source: string) => source.replace(
+        'request: CreateGoalRequest',
+        "request: CreateGoalRequest = { title: '' }",
+      ),
+      message: 'Remote parameters cannot have default values',
+    },
+    {
+      name: 'optional parameter',
+      edit: (source: string) => source.replace('request: CreateGoalRequest', 'request?: CreateGoalRequest'),
+      message: 'Remote parameters cannot be optional',
+    },
+  ])('rejects $name', ({ edit, message }) => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/index.ts', edit)
+
+    expect(() => analyzeRemote(root, false)).toThrow(new RegExp(message))
+  })
+
+  it('rejects a workspace class parameter without a lookup declaration', () => {
+    const root = copyFixture()
+    editFile(root, 'packages/domain/src/index.ts', source => source.replace(
+      '  interface TypeRTLookupMap {\n    agent: TypeRTLookup<Agent, AgentId>\n  }\n\n',
+      '',
+    ))
+
+    expect(() => analyzeRemote(root, false)).toThrow(/non-JSON class parameter Agent requires a TypeRTLookupMap entry/)
+  })
+
+  it('rejects a Remote Context without a static Context declaration', () => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/index.ts', source => source.replace("@RemoteContext('agent')", "@RemoteContext('missing')"))
+
+    expect(() => analyzeRemote(root, false)).toThrow(/Remote Context missing has no TypeRTContextMap entry/)
+  })
+
+  it('rejects a direct scoped projection whose Context and lookup wire symbols differ', () => {
+    const root = copyFixture()
+    editFile(root, 'packages/domain/src/types.ts', source => `${source}\n/** Deliberately distinct Context identity for the failure fixture. */\nexport type OtherAgentId = string\n`)
+    editFile(root, 'packages/domain/src/index.ts', source => source
+      .replace("import type { AgentId } from './types.ts'", "import type { AgentId, OtherAgentId } from './types.ts'")
+      .replace('agent: TypeRTContext<AgentId>', 'agent: TypeRTContext<OtherAgentId>'))
+
+    expect(() => analyzeRemote(root, false)).toThrow(/Remote scope agent wire type .* does not match lookup wire type/)
+  })
+
+  it('rejects duplicate endpoints across Remote services', () => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/index.ts', source => `${source}
+export class DuplicateGoalService {
+  readonly typertGateway = bindTypeRTGateway(this, 'duplicate', { namespace: 'goals' })
+
+  @Remote
+  create(request: CreateGoalRequest): CreateGoalResult {
+    return { ref: request.title }
+  }
+}
+`)
+
+    expect(() => analyzeRemote(root, false)).toThrow(/Remote endpoint goals\/create conflicts/)
+  })
+})
+
+function analyzeRemote(root: string, checkDiagnostics = true): ReturnType<WorkspaceAnalyzer['analyze']> {
+  return new WorkspaceAnalyzer({ root, checkDiagnostics }).analyze()
+}
+
+function remotePackage(root: string): {
+  readonly services: readonly unknown[]
+  readonly invocations: readonly InvocationModel[]
+} {
+  const host = analyzeRemote(root).faces.find(face => face.face === 'host')
+  const packageModel = host?.packages.find(candidate => candidate.name === '@fixture/remote')
+  if (packageModel === undefined) throw new Error('Remote fixture package was not modeled on the host face')
+  return packageModel
+}
+
+function copyFixture(): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-typert-remote-model-'))
+  cpSync(fixtureRoot, root, { recursive: true })
+  temporaryRoots.push(root)
+  return root
+}
+
+function editFile(root: string, relativePath: string, edit: (source: string) => string): void {
+  const path = join(root, relativePath)
+  const source = readFileSync(path, 'utf8')
+  const result = edit(source)
+  if (result === source) throw new Error(`fixture edit made no change to ${relativePath}`)
+  writeFileSync(path, result)
+}
+
+function assertRemoteConsumerTypechecks(dts: string | undefined, dtsMap: string | undefined): void {
+  if (dts === undefined) throw new Error('Remote fixture emitted no Host-for-Client declaration')
+  if (dtsMap === undefined) throw new Error('Remote fixture emitted no Host-for-Client declaration map')
+  const consumerRoot = copyFixture()
+  const declarationPath = join(consumerRoot, 'packages/remote/lib/typert.remote-client.d.ts')
+  const declarationMapPath = `${declarationPath}.map`
+  const consumerPath = join(consumerRoot, 'consumer.ts')
+  mkdirSync(join(consumerRoot, 'packages/remote/lib'), { recursive: true })
+  writeFileSync(declarationPath, dts, { flush: true })
+  writeFileSync(declarationMapPath, dtsMap, { flush: true })
+  assertRemoteConsumerWithoutImportHasNoNamespace(consumerRoot)
+  const consumerSource = `
+import remote from '@fixture/remote/remote'
+import type {
+  TypeRTRemoteContribution,
+  TypeRTRemoteContextMap,
+  TypeRTRemoteMap,
+  TypeRTRemoteNamespaceMap,
+} from '@deepseek-ai/dsh-type-meta'
+import type { CreateGoalResult, RenameGoalResult } from '@fixture/remote/types'
+
+const contribution: TypeRTRemoteContribution = remote
+declare const create: TypeRTRemoteMap['goals/create']
+declare const createScoped: TypeRTRemoteContextMap['agent:goals/create']
+declare const rename: TypeRTRemoteContextMap['agent:goals/rename']
+const created: Promise<CreateGoalResult> = create('agent-1', { title: 'ship' })
+const createdScoped: Promise<CreateGoalResult> = createScoped({ title: 'ship' })
+const renamed: Promise<RenameGoalResult> = rename({ ref: 'goal-1', title: 'land' })
+declare const ctx: { api: TypeRTRemoteNamespaceMap }
+const navigated: Promise<CreateGoalResult> = ctx.api.goals.create('agent-1', { title: 'navigate' })
+void contribution
+void created
+void createdScoped
+void renamed
+void navigated
+`
+  writeFileSync(consumerPath, consumerSource)
+  const configPath = join(consumerRoot, 'tsconfig.consumer.json')
+  writeFileSync(configPath, JSON.stringify({
+    extends: './tsconfig.base.json',
+    compilerOptions: {
+      composite: false,
+      skipLibCheck: false,
+      paths: {
+        '@deepseek-ai/dsh-type-meta': ['./type-meta.d.ts'],
+        '@fixture/domain/types': ['./packages/domain/src/types.ts'],
+        '@fixture/remote/types': ['./packages/remote/src/types.ts'],
+        '@fixture/remote/remote': ['./packages/remote/lib/typert.remote-client.d.ts'],
+      },
+    },
+    files: ['./consumer.ts'],
+  }, null, 2))
+  const config = ts.readConfigFile(configPath, file => ts.sys.readFile(file))
+  if (config.error !== undefined) throw new Error(formatDiagnostics([config.error]))
+  const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, consumerRoot, undefined, configPath)
+  const program = ts.createProgram(parsed.fileNames, parsed.options)
+  const diagnostics = ts.getPreEmitDiagnostics(program)
+  expect(diagnostics, formatDiagnostics(diagnostics)).toEqual([])
+
+  const languageService = ts.createLanguageService({
+    getCompilationSettings: () => parsed.options,
+    getCurrentDirectory: () => consumerRoot,
+    getDefaultLibFileName: options => ts.getDefaultLibFilePath(options),
+    getScriptFileNames: () => parsed.fileNames,
+    getScriptSnapshot: (fileName) => {
+      const source = ts.sys.readFile(fileName)
+      return source === undefined ? undefined : ts.ScriptSnapshot.fromString(source)
+    },
+    getScriptVersion: () => '0',
+    directoryExists: path => ts.sys.directoryExists(path),
+    fileExists: path => ts.sys.fileExists(path),
+    getDirectories: path => ts.sys.getDirectories(path),
+    readDirectory: (path, extensions, exclude, include, depth) =>
+      ts.sys.readDirectory(path, extensions, exclude, include, depth),
+    readFile: path => ts.sys.readFile(path),
+    realpath: path => ts.sys.realpath?.(path) ?? path,
+  })
+  const navigation = 'ctx.api.goals.create'
+  const position = consumerSource.indexOf(navigation) + navigation.lastIndexOf('create') + 1
+  const definitions = languageService.getDefinitionAtPosition(consumerPath, position)
+  const generatedDefinition = definitions?.find(candidate => candidate.fileName === declarationPath)
+  if (generatedDefinition === undefined) {
+    throw new Error(`generated Remote definition not found: ${JSON.stringify(definitions, null, 2)}`)
+  }
+  const sourceMapper = (languageService as unknown as {
+    getSourceMapper(): {
+      tryGetSourcePosition(location: { readonly fileName: string; readonly pos: number }):
+      { readonly fileName: string; readonly pos: number } | undefined
+    }
+  }).getSourceMapper()
+  const definition = sourceMapper.tryGetSourcePosition({
+    fileName: generatedDefinition.fileName,
+    pos: generatedDefinition.textSpan.start,
+  })
+  languageService.dispose()
+  if (definition === undefined || !definition.fileName.endsWith('/packages/remote/src/index.ts')) {
+    throw new Error(`generated Remote definition did not map to its Host source: ${JSON.stringify(definition)}`)
+  }
+  const hostSource = readFileSync(join(consumerRoot, 'packages/remote/src/index.ts'), 'utf8')
+  expect(hostSource.slice(definition.pos, definition.pos + generatedDefinition.textSpan.length)).toBe('create')
+}
+
+function assertRemoteConsumerWithoutImportHasNoNamespace(consumerRoot: string): void {
+  const consumerPath = join(consumerRoot, 'consumer-without-remote.ts')
+  writeFileSync(consumerPath, `
+import type { TypeRTRemoteNamespaceMap } from '@deepseek-ai/dsh-type-meta'
+declare const ctx: { api: TypeRTRemoteNamespaceMap }
+ctx.api.goals.create('agent-1', { title: 'must not compile' })
+`)
+  const configPath = join(consumerRoot, 'tsconfig.consumer-without-remote.json')
+  writeFileSync(configPath, JSON.stringify({
+    extends: './tsconfig.base.json',
+    compilerOptions: {
+      composite: false,
+      skipLibCheck: false,
+      paths: {
+        '@deepseek-ai/dsh-type-meta': ['./type-meta.d.ts'],
+      },
+    },
+    files: ['./consumer-without-remote.ts'],
+  }, null, 2))
+  const config = ts.readConfigFile(configPath, file => ts.sys.readFile(file))
+  if (config.error !== undefined) throw new Error(formatDiagnostics([config.error]))
+  const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, consumerRoot, undefined, configPath)
+  const diagnostics = ts.getPreEmitDiagnostics(ts.createProgram(parsed.fileNames, parsed.options))
+  expect(diagnostics).toHaveLength(1)
+  expect(diagnostics[0]?.code).toBe(2339)
+  expect(ts.flattenDiagnosticMessageText(diagnostics[0]?.messageText ?? '', '\n')).toContain("Property 'goals' does not exist")
+}
+
+function formatDiagnostics(diagnostics: readonly ts.Diagnostic[]): string {
+  return ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+    getCanonicalFileName: file => file,
+    getCurrentDirectory: () => process.cwd(),
+    getNewLine: () => '\n',
+  })
+}
diff --git a/packages/typert/generator/tests/schema-emitter.spec.ts b/packages/typert/generator/tests/schema-emitter.spec.ts
index 7457c4b85f..16ac97b7ca 100644
--- a/packages/typert/generator/tests/schema-emitter.spec.ts
+++ b/packages/typert/generator/tests/schema-emitter.spec.ts
@@ -7,6 +7,7 @@ import type {
   FaceModel,
   KeywordTypeName,
   MemberModel,
+  SignatureMemberModel,
   SignatureModel,
   TypeDeclarationModel,
   TypeNodeModel,
@@ -356,6 +357,149 @@ describe('SchemaEmitter supported projection matrix', () => {
     expect(inheritedSchema.safeParse({ current: 1 }).success).toBe(false)
   })
 
+  it('instantiates generic aliases, nested references, defaults, and recursive declarations', async () => {
+    const box = declaration('Box', 'interface', {
+      typeParameters: [{ id: 'box:value', name: 'Value', const: false }],
+      members: [property('value', 'box:value-reference')],
+    })
+    const wrapper = declaration('Wrapper', 'alias', {
+      typeParameters: [
+        { id: 'wrapper:value', name: 'Value', const: false },
+        { id: 'wrapper:items', name: 'Items', const: false, default: 'wrapper:default-items' },
+      ],
+      type: 'wrapper:box-reference',
+    })
+    const recursive = declaration('Recursive', 'interface', {
+      typeParameters: [{ id: 'recursive:value', name: 'Value', const: false }],
+      members: [
+        property('value', 'recursive:value-reference'),
+        property('next', 'recursive:self-reference', { optional: true }),
+      ],
+    })
+    const schema = await loadSchema(emit([
+      {
+        id: 'root',
+        kind: 'object',
+        members: [
+          property('wrapped', 'root:wrapper-reference'),
+          property('recursive', 'root:recursive-reference'),
+        ],
+      },
+      {
+        id: 'root:wrapper-reference',
+        kind: 'reference',
+        name: 'Wrapper',
+        target: { kind: 'declaration', symbol: 'Wrapper' },
+        arguments: ['string'],
+      },
+      {
+        id: 'root:recursive-reference',
+        kind: 'reference',
+        name: 'Recursive',
+        target: { kind: 'declaration', symbol: 'Recursive' },
+        arguments: ['number'],
+      },
+      {
+        id: 'wrapper:box-reference',
+        kind: 'reference',
+        name: 'Box',
+        target: { kind: 'declaration', symbol: 'Box' },
+        arguments: ['wrapper:items-reference'],
+      },
+      {
+        id: 'wrapper:default-items',
+        kind: 'reference',
+        name: 'ReadonlyArray',
+        target: { kind: 'standard', name: 'ReadonlyArray' },
+        arguments: ['wrapper:value-reference'],
+      },
+      {
+        id: 'wrapper:value-reference',
+        kind: 'reference',
+        name: 'Value',
+        target: { kind: 'type-parameter', parameter: 'wrapper:value' },
+        arguments: [],
+      },
+      {
+        id: 'wrapper:items-reference',
+        kind: 'reference',
+        name: 'Items',
+        target: { kind: 'type-parameter', parameter: 'wrapper:items' },
+        arguments: [],
+      },
+      {
+        id: 'box:value-reference',
+        kind: 'reference',
+        name: 'Value',
+        target: { kind: 'type-parameter', parameter: 'box:value' },
+        arguments: [],
+      },
+      {
+        id: 'recursive:value-reference',
+        kind: 'reference',
+        name: 'Value',
+        target: { kind: 'type-parameter', parameter: 'recursive:value' },
+        arguments: [],
+      },
+      {
+        id: 'recursive:self-reference',
+        kind: 'reference',
+        name: 'Recursive',
+        target: { kind: 'declaration', symbol: 'Recursive' },
+        arguments: ['recursive:value-reference'],
+      },
+      keyword('string', 'string'),
+      keyword('number', 'number'),
+    ], undefined, [box, wrapper, recursive]))
+
+    expect(schema.safeParse({
+      wrapped: { value: ['one', 'two'] },
+      recursive: { value: 1, next: { value: 2 } },
+    }).success).toBe(true)
+    expect(schema.safeParse({
+      wrapped: { value: [1] },
+      recursive: { value: 1 },
+    }).success).toBe(false)
+    expect(schema.safeParse({
+      wrapped: { value: ['one'] },
+      recursive: { value: 'one' },
+    }).success).toBe(false)
+  })
+
+  it('erases unique-symbol nominal members without naming a branding utility', async () => {
+    const nominal = declaration('Nominal', 'alias', {
+      typeParameters: [{ id: 'nominal:brand', name: 'Brand', const: false }],
+      type: 'nominal:intersection',
+    })
+    const symbolMember = {
+      ...property('[TOKEN]', 'nominal:brand-reference', { readonly: true }),
+      computed: 'symbol',
+    } as const
+    const schema = await loadSchema(emit([
+      {
+        id: 'root',
+        kind: 'reference',
+        name: 'Nominal',
+        target: { kind: 'declaration', symbol: 'Nominal' },
+        arguments: ['brand'],
+      },
+      { id: 'brand', kind: 'literal', value: 'Fixture', text: "'Fixture'" },
+      { id: 'nominal:intersection', kind: 'intersection', types: ['string', 'nominal:marker'] },
+      keyword('string', 'string'),
+      { id: 'nominal:marker', kind: 'object', members: [symbolMember] },
+      {
+        id: 'nominal:brand-reference',
+        kind: 'reference',
+        name: 'Brand',
+        target: { kind: 'type-parameter', parameter: 'nominal:brand' },
+        arguments: [],
+      },
+    ], undefined, [nominal]))
+
+    expect(schema.safeParse('fixture-id').success).toBe(true)
+    expect(schema.safeParse(1).success).toBe(false)
+  })
+
   it('classifies every TypeNode kind and executes every supported kind', () => {
     const expected = Object.entries(ZOD_NODE_SUPPORT)
       .filter(([, support]) => support === 'supported')
@@ -373,7 +517,6 @@ describe('SchemaEmitter unsupported projection matrix', () => {
   })
 
   it.each([
-    ['type-parameter', { kind: 'type-parameter', parameter: 'parameter' }],
     ['cross-face', { kind: 'cross-face', face: 'client', package: '@fixture/client', subpath: '.', name: 'Value' }],
     ['external', { kind: 'external', module: 'external', subpath: '.', name: 'Value' }],
   ] as const)('rejects %s references explicitly', (kind, target) => {
@@ -386,7 +529,33 @@ describe('SchemaEmitter unsupported projection matrix', () => {
     }])).toThrow(`typert Zod emitter: Value: ${kind} reference has no Zod projection`)
   })
 
-  it('rejects unsupported standard references, generic declarations, and enums', () => {
+  it('rejects unbound type parameters, incomplete generic applications, and generic schema exports', () => {
+    expect(() => emit([{
+      id: 'root',
+      kind: 'reference',
+      name: 'Value',
+      target: { kind: 'type-parameter', parameter: 'parameter' },
+      arguments: [],
+    }])).toThrow('type parameter has no schema substitution')
+
+    const generic = declaration('Generic', 'interface', {
+      typeParameters: [{ id: 'parameter', name: 'Value', const: false }],
+    })
+    expect(() => emit([{
+      id: 'root',
+      kind: 'reference',
+      name: 'Generic',
+      target: { kind: 'declaration', symbol: 'Generic' },
+      arguments: [],
+    }], undefined, [generic])).toThrow('missing type argument Value')
+
+    const genericRoot = declaration('Root', 'interface', {
+      typeParameters: [{ id: 'root:parameter', name: 'Value', const: false }],
+    })
+    expect(() => emit([], genericRoot)).toThrow('generic schema exports require a concrete declaration')
+  })
+
+  it('rejects unsupported standard references and enums', () => {
     const intrinsic = { id: 'root', kind: 'keyword', name: 'intrinsic' } as unknown as TypeNodeModel
     expect(() => emit([intrinsic]))
       .toThrow('keyword intrinsic has no Zod projection')
@@ -399,17 +568,6 @@ describe('SchemaEmitter unsupported projection matrix', () => {
       arguments: [],
     }])).toThrow('standard type Promise has no Zod projection')
 
-    const generic = declaration('Generic', 'interface', {
-      typeParameters: [{ id: 'parameter', name: 'Value', const: false }],
-    })
-    expect(() => emit([{
-      id: 'root',
-      kind: 'reference',
-      name: 'Generic',
-      target: { kind: 'declaration', symbol: 'Generic' },
-      arguments: [],
-    }], undefined, [generic])).toThrow('generic declarations require a schema-factory projection')
-
     const enumeration = declaration('Enumeration', 'enum', {
       enumMembers: [{ ...documentation, name: 'Value', initializer: "'value'", location }],
     })
@@ -481,6 +639,7 @@ describe('SchemaEmitter unsupported projection matrix', () => {
         }],
         objects: [],
         schemas: [],
+        invocations: [],
       }],
     }
     expect(() => new FaceModelEmitter(eventFace).emit('@fixture/schema'))
@@ -513,6 +672,7 @@ describe('SchemaEmitter unsupported projection matrix', () => {
         }],
         objects: [],
         schemas: [],
+        invocations: [],
       }],
     }
 
@@ -555,7 +715,33 @@ describe('SchemaEmitter unsupported projection matrix', () => {
     expect(artifact.dts).toContain("from '@fixture/schema/secondary'")
   })
 
-  it.each(['method', 'getter', 'setter', 'call', 'construct', 'index'] as const)(
+  it('emits JSON index signatures as record schemas', async () => {
+    const root = declaration('Root', 'interface', {
+      members: [indexMember('key', 'value')],
+    })
+    const schema = await loadSchema(emit([
+      keyword('key', 'string'),
+      keyword('value', 'number'),
+    ], root))
+
+    expect(schema.safeParse({ one: 1, two: 2 }).success).toBe(true)
+    expect(schema.safeParse({ one: '1' }).success).toBe(false)
+  })
+
+  it('rejects more than one JSON index signature', () => {
+    const root = declaration('Root', 'interface', {
+      members: [indexMember('key', 'value'), indexMember('other-key', 'other-value')],
+    })
+
+    expect(() => emit([
+      keyword('key', 'string'),
+      keyword('value', 'number'),
+      keyword('other-key', 'string'),
+      keyword('other-value', 'boolean'),
+    ], root)).toThrow('object type has more than one JSON index signature')
+  })
+
+  it.each(['method', 'getter', 'setter', 'call', 'construct'] as const)(
     'rejects %s members on data-schema objects',
     (kind) => {
       expect(() => emit([
@@ -608,6 +794,10 @@ function property(
   }
 }
 
+function signatureMember(kind: 'index'): SignatureMemberModel
+function signatureMember(
+  kind: Exclude<MemberModel['kind'], 'property' | 'index'>,
+): MemberModel
 function signatureMember(kind: Exclude<MemberModel['kind'], 'property'>): MemberModel {
   return {
     ...documentation,
@@ -626,6 +816,24 @@ function signatureMember(kind: Exclude<MemberModel['kind'], 'property'>): Member
   }
 }
 
+function indexMember(key: string, value: string): SignatureMemberModel {
+  return {
+    ...signatureMember('index'),
+    signature: {
+      typeParameters: [],
+      parameters: [{
+        name: 'key',
+        binding: 'identifier',
+        type: key,
+        optional: false,
+        rest: false,
+        receiver: false,
+      }],
+      returns: value,
+    },
+  }
+}
+
 function declaration(
   name: string,
   kind: TypeDeclarationModel['kind'],
@@ -684,6 +892,7 @@ function emit(
         symbol: 'Root',
         type: 'schema-reference',
       }],
+      invocations: [],
     }],
   }
   return new FaceModelEmitter(face).emit('@fixture/schema').js
@@ -710,6 +919,7 @@ function schemaFace(
         symbol,
         type: 'root',
       }],
+      invocations: [],
     }],
   }
 }
diff --git a/packages/typert/generator/tests/tools-catalog.spec.ts b/packages/typert/generator/tests/tools-catalog.spec.ts
index 29193e66c1..95c1ab09de 100644
--- a/packages/typert/generator/tests/tools-catalog.spec.ts
+++ b/packages/typert/generator/tests/tools-catalog.spec.ts
@@ -62,7 +62,7 @@ describe('model-driven dsh-tools generation', () => {
       TYPE_API.find(type => type.name === 'ToolDefinition'),
     )
 
-    dispose()
+    await dispose()
     expect(ctx.typert.getPackage('@deepseek-ai/dsh-tools', 'host')).toBeUndefined()
   })
 })
diff --git a/packages/typert/generator/tests/tsdown-plugin.spec.ts b/packages/typert/generator/tests/tsdown-plugin.spec.ts
index 9b4057beee..655636aa79 100644
--- a/packages/typert/generator/tests/tsdown-plugin.spec.ts
+++ b/packages/typert/generator/tests/tsdown-plugin.spec.ts
@@ -12,6 +12,11 @@ const generated = vi.hoisted(() => vi.fn(() => [
     exports: [],
     js: 'export const host = true\n',
     dts: 'export declare const host: true\n',
+    remote: {
+      js: 'export const remote = true\n',
+      dts: 'export declare const remote: true\n//# sourceMappingURL=typert.remote-client.d.ts.map\n',
+      dtsMap: '{"version":3}\n',
+    },
   },
   {
     package: '@deepseek-ai/dsh-tools',
@@ -21,10 +26,30 @@ const generated = vi.hoisted(() => vi.fn(() => [
     js: 'export const client = true\n',
     dts: 'export declare const client: true\n',
   },
+  {
+    package: '@fixture/remote-only',
+    packageRoot: 'packages/remote-only',
+    face: 'host' as const,
+    exports: [],
+    js: 'export const local = true\n',
+    dts: 'export declare const local: true\n',
+    remote: {
+      js: 'export const remoteOnly = true\n',
+      dts: 'export declare const remoteOnly: true\n//# sourceMappingURL=typert.remote-client.d.ts.map\n',
+      dtsMap: '{"version":3}\n',
+    },
+  },
+]))
+
+const discovered = vi.hoisted(() => vi.fn(() => [
+  { package: '@deepseek-ai/dsh-tools', root: 'packages/core/tools', faces: ['host'] },
+  { package: '@fixture/ignored', root: 'packages/ignored', faces: ['host'] },
+  { package: '@fixture/remote-only', root: 'packages/remote-only', faces: ['host'] },
 ]))
 
 vi.mock('../src/workspace.ts', () => ({
   WorkspaceTypertGenerator: class {
+    discover = discovered
     generate = generated
   },
 }))
@@ -33,6 +58,7 @@ const { typertPlugin } = await import('../src/tsdown-plugin.ts')
 const roots: string[] = []
 
 afterEach(() => {
+  discovered.mockClear()
   generated.mockClear()
   for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
 })
@@ -80,9 +106,64 @@ describe('typertPlugin', () => {
     expect(readFileSync(join(packageLib, 'typert.host.d.ts'), 'utf8')).toBe('export declare const host: true\n')
     expect(readFileSync(join(packageLib, 'typert.client.js'), 'utf8')).toBe('export const client = true\n')
     expect(existsSync(join(packageLib, 'typert.client.d.ts'))).toBe(true)
+    expect(readFileSync(join(packageLib, 'typert.remote-client.js'), 'utf8')).toBe('export const remote = true\n')
+    expect(readFileSync(join(packageLib, 'typert.remote-client.d.ts'), 'utf8'))
+      .toBe('export declare const remote: true\n//# sourceMappingURL=typert.remote-client.d.ts.map\n')
+    expect(readFileSync(join(packageLib, 'typert.remote-client.d.ts.map'), 'utf8'))
+      .toBe('{"version":3}\n')
     expect(readFileSync(join(root, 'packages/client-tools/lib/typert.client.js'), 'utf8'))
       .toBe('export const client = true\n')
   })
+
+  it('generates a package opted in only through its Remote export', async () => {
+    const root = await workspace()
+    const output = await packageOutput(root, 'remote-only', {
+      name: '@fixture/remote-only',
+      exports: { './remote': './lib/typert.remote-client.js' },
+    })
+
+    typertPlugin().writeBundle({ dir: output })
+
+    const packageLib = join(root, 'packages', 'remote-only', 'lib')
+    expect(generated).toHaveBeenCalledOnce()
+    expect(readFileSync(join(packageLib, 'typert.remote-client.js'), 'utf8'))
+      .toBe('export const remoteOnly = true\n')
+    expect(readFileSync(join(packageLib, 'typert.remote-client.d.ts'), 'utf8'))
+      .toBe('export declare const remoteOnly: true\n//# sourceMappingURL=typert.remote-client.d.ts.map\n')
+    expect(readFileSync(join(packageLib, 'typert.remote-client.d.ts.map'), 'utf8'))
+      .toBe('{"version":3}\n')
+  })
+
+  it('emits every explicit workspace contributor once from a host-only prepass', async () => {
+    const root = await workspace()
+    const trigger = await packageOutput(root, 'generator', { name: '@deepseek-ai/dsh-typert-generator' })
+    await packageOutput(root, 'core/tools', {
+      name: '@deepseek-ai/dsh-tools',
+      exports: { './typert': './lib/typert.host.js' },
+    })
+    await packageOutput(root, 'ignored', { name: '@fixture/ignored' })
+    await packageOutput(root, 'remote-only', {
+      name: '@fixture/remote-only',
+      exports: { './remote': './lib/typert.remote-client.js' },
+    })
+
+    const plugin = typertPlugin({ mode: 'workspace', faces: ['host'] })
+    plugin.writeBundle({ dir: trigger })
+    plugin.writeBundle({ dir: join(root, 'packages/core/tools/lib/dev') })
+
+    expect(discovered).toHaveBeenCalledOnce()
+    expect(discovered).toHaveBeenCalledWith(['host'])
+    expect(generated).toHaveBeenCalledOnce()
+    expect(generated).toHaveBeenCalledWith(
+      ['@deepseek-ai/dsh-tools', '@fixture/remote-only'],
+      ['host'],
+    )
+    expect(readFileSync(join(root, 'packages/core/tools/lib/typert.host.js'), 'utf8'))
+      .toBe('export const host = true\n')
+    expect(readFileSync(join(root, 'packages/remote-only/lib/typert.remote-client.js'), 'utf8'))
+      .toBe('export const remoteOnly = true\n')
+    expect(existsSync(join(root, 'packages/ignored/lib/typert.host.js'))).toBe(false)
+  })
 })
 
 async function workspace(): Promise<string> {
diff --git a/packages/typert/generator/tests/type-model.spec.ts b/packages/typert/generator/tests/type-model.spec.ts
index 923c254d0f..ca37cd1bbe 100644
--- a/packages/typert/generator/tests/type-model.spec.ts
+++ b/packages/typert/generator/tests/type-model.spec.ts
@@ -201,6 +201,53 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
     expect(batched).toEqual(direct)
   })
 
+  it('discovers an explicitly keyed service implementation without a Context merge', () => {
+    const root = copyFixture('explicit-service-')
+    addExplicitServicePackage(root, 'service detached')
+    const analyzer = new WorkspaceAnalyzer({ root })
+
+    expect(analyzer.discoverPackages()).toContainEqual({
+      package: '@fixture/explicit-service',
+      root: 'packages/explicit-service',
+      faces: ['host'],
+    })
+    const model = new WorkspaceAnalyzer({ root, packages: ['@fixture/explicit-service'] }).analyze()
+    const service = model.faces[0]?.packages[0]?.services[0]
+    expect(service).toMatchObject({ key: 'detached', export: { name: 'DetachedService' } })
+  })
+
+  it('prefers an explicitly keyed implementation over its protocol Context merge', () => {
+    const root = copyFixture('explicit-service-protocol-')
+    addExplicitServicePackage(root, 'service detached', true)
+    const model = new WorkspaceAnalyzer({
+      root,
+      packages: ['@fixture/explicit-service'],
+    }).analyze()
+    const service = model.faces[0]?.packages[0]?.services[0]
+
+    expect(service).toMatchObject({
+      key: 'detached',
+      export: { name: 'DetachedService' },
+      location: { file: 'packages/explicit-service/src/index.ts' },
+    })
+  })
+
+  it('rejects an explicit service implementation without one valid key', () => {
+    const missing = copyFixture('explicit-service-missing-')
+    addExplicitServicePackage(missing, 'service')
+    expect(() => new WorkspaceAnalyzer({
+      root: missing,
+      packages: ['@fixture/explicit-service'],
+    }).analyze()).toThrow('@typert service requires exactly one nonempty Cordis service key')
+
+    const invalid = copyFixture('explicit-service-invalid-')
+    addExplicitServicePackage(invalid, 'service bad/key')
+    expect(() => new WorkspaceAnalyzer({
+      root: invalid,
+      packages: ['@fixture/explicit-service'],
+    }).analyze()).toThrow('@typert service requires exactly one nonempty Cordis service key')
+  })
+
   it('indexes authored top-level exports without promoting them to graph roots', () => {
     const declarations = new WorkspaceAnalyzer({ root: fixtureRoot }).indexSourceDeclarations()
     const agent = declarations.find(declaration => declaration.name === 'Agent')
@@ -1178,6 +1225,57 @@ function addSameFacePackage(root: string, specifier: string, importedName: strin
   writeFileSync(aggregatePath, `${JSON.stringify(aggregate, null, 2)}\n`)
 }
 
+function addExplicitServicePackage(root: string, annotation: string, withProtocol = false): void {
+  const packageRoot = join(root, 'packages/explicit-service')
+  mkdirSync(join(packageRoot, 'src'), { recursive: true })
+  writeFileSync(join(packageRoot, 'package.json'), JSON.stringify({
+    name: '@fixture/explicit-service',
+    private: true,
+    type: 'module',
+    exports: {
+      '.': {
+        types: './lib/types/index.d.ts',
+        default: './lib/index.js',
+      },
+    },
+  }, null, 2))
+  writeFileSync(join(packageRoot, 'tsconfig.json'), JSON.stringify({
+    extends: '../../tsconfig.base.json',
+    compilerOptions: { rootDir: 'src', outDir: 'lib/types' },
+    include: ['src'],
+  }, null, 2))
+  if (withProtocol) {
+    writeFileSync(join(packageRoot, 'src/types.ts'), [
+      '/** Public detached Service protocol. */',
+      'export interface DetachedProtocol {',
+      '  /** Report protocol readiness. */',
+      '  ready(): boolean',
+      '}',
+      "declare module 'cordis' {",
+      '  interface Context { detached: DetachedProtocol }',
+      '}',
+      '',
+    ].join('\n'))
+  }
+  writeFileSync(join(packageRoot, 'src/index.ts'), [
+    "import { Service } from 'cordis'",
+    ...(withProtocol ? ["export type { DetachedProtocol } from './types.ts'"] : []),
+    '/**',
+    ' * Service implementation discovered independently of its protocol package.',
+    ` * @typert ${annotation}`,
+    ' */',
+    'export class DetachedService extends Service {',
+    '  /** Report readiness. */',
+    '  ready(): boolean { return true }',
+    '}',
+    '',
+  ].join('\n'))
+  const aggregatePath = join(root, 'tsconfig.host.json')
+  const aggregate = JSON.parse(readFileSync(aggregatePath, 'utf8')) as { references: { path: string }[] }
+  aggregate.references.push({ path: './packages/explicit-service' })
+  writeFileSync(aggregatePath, `${JSON.stringify(aggregate, null, 2)}\n`)
+}
+
 describe('FaceModelEmitter', { timeout: 60_000 }, () => {
   it('emits runnable Zod JavaScript, precise declarations, and runtime package metadata', async () => {
     const model = new WorkspaceAnalyzer({ root: fixtureRoot }).analyze()
diff --git a/packages/typert/loader/src/index.ts b/packages/typert/loader/src/index.ts
index 9485a76f05..fee1098340 100644
--- a/packages/typert/loader/src/index.ts
+++ b/packages/typert/loader/src/index.ts
@@ -135,6 +135,11 @@ export function validateTypertManifest(pkgName: string, exported: unknown): Type
     requireMembers(pkgName, object.members, `object "${object.name as string}"`)
     requireTypes(pkgName, object.types, `object "${object.name as string}"`)
   }
+  if (manifest.invocations !== undefined) {
+    for (const value of requireArray(pkgName, manifest.invocations, 'TYPERT.invocations')) {
+      requireInvocation(pkgName, value)
+    }
+  }
   return manifest as unknown as TypertContribution
 }
 
@@ -184,6 +189,88 @@ function requireTypes(pkgName: string, value: unknown, subject: string): void {
   }
 }
 
+function requireInvocation(pkgName: string, value: unknown): void {
+  const invocation = requireObject(pkgName, value, 'invocation')
+  for (const key of ['id', 'service', 'namespace', 'method'] as const) {
+    requireString(pkgName, invocation, key, 'invocation')
+  }
+  const id = invocation.id as string
+  const receiver = requireObject(pkgName, invocation.invocation, `invocation "${id}" receiver`)
+  if (receiver.kind === 'context') {
+    requireString(pkgName, receiver, 'context', `invocation "${id}" Context receiver`)
+    requireString(pkgName, receiver, 'wire', `invocation "${id}" Context receiver`)
+    requireStrictCodec(pkgName, receiver.codec, `invocation "${id}" Context codec`)
+  } else if (receiver.kind !== 'direct') {
+    throw new Error(`typert-loader: ${pkgName} invocation "${id}" receiver kind must be "direct" or "context"`)
+  }
+  const wires = new Set<string>()
+  const parameters = new Map<string, Record<string, unknown>>()
+  let lookupCount = 0
+  for (const valueParameter of requireArray(pkgName, invocation.parameters, `invocation "${id}" parameters`)) {
+    const parameter = requireObject(pkgName, valueParameter, `invocation "${id}" parameter`)
+    requireString(pkgName, parameter, 'name', `invocation "${id}" parameter`)
+    requireString(pkgName, parameter, 'wire', `invocation "${id}" parameter`)
+    const wire = parameter.wire as string
+    if (wires.has(wire)) {
+      throw new Error(`typert-loader: ${pkgName} invocation "${id}" repeats wire field "${wire}"`)
+    }
+    wires.add(wire)
+    if (parameter.source === 'lookup') {
+      lookupCount += 1
+      requireString(pkgName, parameter, 'lookup', `invocation "${id}" lookup parameter`)
+    } else if (parameter.source === 'json') {
+      if (parameter.lookup !== undefined) {
+        throw new Error(`typert-loader: ${pkgName} invocation "${id}" JSON parameter declares a lookup`)
+      }
+    } else {
+      throw new Error(`typert-loader: ${pkgName} invocation "${id}" parameter source must be "json" or "lookup"`)
+    }
+    parameters.set(wire, parameter)
+    requireStrictCodec(pkgName, parameter.codec, `invocation "${id}" parameter codec`)
+  }
+  if (invocation.scope !== undefined) {
+    if (receiver.kind !== 'direct') {
+      throw new Error(`typert-loader: ${pkgName} invocation "${id}" Context receiver cannot declare a direct scope projection`)
+    }
+    const scope = requireObject(pkgName, invocation.scope, `invocation "${id}" scope`)
+    requireString(pkgName, scope, 'context', `invocation "${id}" scope`)
+    requireString(pkgName, scope, 'wire', `invocation "${id}" scope`)
+    const parameter = parameters.get(scope.wire as string)
+    if (lookupCount !== 1 || parameter?.source !== 'lookup' || parameter.lookup !== scope.context) {
+      throw new Error(
+        `typert-loader: ${pkgName} invocation "${id}" scope wire "${scope.wire as string}" must select its only lookup parameter`,
+      )
+    }
+  }
+  if (receiver.kind === 'context' && wires.has(receiver.wire as string)) {
+    throw new Error(`typert-loader: ${pkgName} invocation "${id}" repeats Context wire field "${receiver.wire as string}"`)
+  }
+  requireStrictCodec(pkgName, invocation.result, `invocation "${id}" result codec`)
+  if (invocation.sourceLocation !== undefined) {
+    const location = requireObject(pkgName, invocation.sourceLocation, `invocation "${id}" sourceLocation`)
+    requireString(pkgName, location, 'file', `invocation "${id}" sourceLocation`)
+    for (const key of ['line', 'column'] as const) {
+      if (!Number.isInteger(location[key]) || (location[key] as number) < 1) {
+        throw new Error(`typert-loader: ${pkgName} invocation "${id}" sourceLocation.${key} must be a positive integer`)
+      }
+    }
+  }
+}
+
+function requireStrictCodec(pkgName: string, value: unknown, subject: string): void {
+  const codec = requireObject(pkgName, value, subject)
+  if (codec.mode !== 'strict') {
+    throw new Error(`typert-loader: ${pkgName} ${subject} must use a strict codec`)
+  }
+  requireString(pkgName, codec, 'typeSymbol', subject)
+  if (typeof codec.schema !== 'object'
+    || codec.schema === null
+    || !('_zod' in codec.schema)
+    || typeof (codec.schema as { parse?: unknown }).parse !== 'function') {
+    throw new Error(`typert-loader: ${pkgName} ${subject} is not backed by a zod v4 schema`)
+  }
+}
+
 /**
  * Scan current Loader entries during activation, then follow entry mounts and
  * unmounts for this plugin's lifetime.
@@ -202,7 +289,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   const configured = new Set((config as ResolvedConfig).packages)
 
   // Registered contributions by entry name; the disposer withdraws the entry's registration.
-  const registered = new Map<string, () => void>()
+  const registered = new Map<string, () => Promise<void>>()
   // In-flight import/register tasks by entry name.
   const pending = new Map<string, Promise<void>>()
   // Artifact paths by package name. Negative verdicts (unresolvable specifier —
@@ -279,7 +366,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
       const dispose = registered.get(entryName)
       if (dispose !== undefined) {
         registered.delete(entryName)
-        dispose()
+        return dispose()
       }
       return undefined
     }
diff --git a/packages/typert/loader/tests/loader.spec.ts b/packages/typert/loader/tests/loader.spec.ts
index 3b126f1e76..1e7e553605 100644
--- a/packages/typert/loader/tests/loader.spec.ts
+++ b/packages/typert/loader/tests/loader.spec.ts
@@ -1,4 +1,5 @@
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -8,6 +9,7 @@ import Loader from '@cordisjs/plugin-loader'
 import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import * as typertLoader from '@deepseek-ai/dsh-typert-loader'
 import { validateTypertManifest } from '@deepseek-ai/dsh-typert-loader'
+import { z } from 'zod'
 
 let root: string | undefined
 let context: Context | undefined
@@ -63,12 +65,45 @@ function typertSource(pkgName: string, entryName: string): string {
   ].join('\n')
 }
 
+function invocationTypertSource(pkgName: string): string {
+  return [
+    'import { z } from \'zod\'',
+    'const Text = z.string()',
+    'export const TYPERT = {',
+    `  package: '${pkgName}',`,
+    '  face: \'host\',',
+    '  schemas: [],',
+    '  model: { services: [], events: [], objects: [] },',
+    '  invocations: [{',
+    `    id: '${pkgName}#goals/create',`,
+    '    service: \'goals\', namespace: \'goals\', method: \'create\',',
+    '    invocation: { kind: \'direct\' },',
+    '    parameters: [{',
+    '      name: \'request\', wire: \'request\', source: \'json\',',
+    `      codec: { mode: 'strict', typeSymbol: '${pkgName}/types#Request', schema: Text },`,
+    '    }],',
+    `    result: { mode: 'strict', typeSymbol: '${pkgName}/types#Result', schema: Text },`,
+    '    sourceLocation: { file: \'src/index.ts\', line: 8, column: 3 },',
+    '  }],',
+    '}',
+    '',
+  ].join('\n')
+}
+
 /** Boot a real Loader over a fixture root; plugin modules resolve from its node_modules. */
 async function boot(): Promise<Context> {
   context = new Context()
   context.baseUrl = pathToFileURL(join(root as string, 'cordis.yml')).href
   await context.plugin(TypertRegistry)
   await context.plugin(Loader)
+  const fixtureRequire = createRequire(context.baseUrl)
+  context.loader.internal = {
+    version: 'v2',
+    async import(specifier: string) {
+      const module: unknown = await import(pathToFileURL(fixtureRequire.resolve(specifier)).href)
+      return module
+    },
+  } as unknown as NonNullable<typeof context.loader.internal>
   // zod must be resolvable from the fixture packages; link the workspace copy.
   await mkdir(join(root as string, 'node_modules'), { recursive: true })
   return context
@@ -105,6 +140,33 @@ describe('typert loader', () => {
     expect(ctx.typert.getPackage('@fixture/nested')).toBeUndefined()
   })
 
+  it('registers a strict invocation into the local registry and withdraws it with the loader', LOADER_TEST_TIMEOUT, async () => {
+    root = await mkdtemp(join(tmpdir(), 'dsh-typert-loader-'))
+    await linkZod(root)
+    await writePackage(root, '@fixture/invocation', {
+      typertSource: invocationTypertSource('@fixture/invocation'),
+    })
+    const ctx = await boot()
+
+    const fiber = mountTypertLoader(ctx, { packages: ['@fixture/invocation'] })
+    await fiber
+
+    const descriptor = ctx.typert.local.get('goals/create')
+    expect(descriptor).toMatchObject({
+      id: '@fixture/invocation#goals/create',
+      invocation: { kind: 'direct' },
+      parameters: [{ wire: 'request', source: 'json' }],
+      sourceLocation: { file: 'src/index.ts', line: 8, column: 3 },
+    })
+    expect(descriptor?.parameters[0]?.codec.mode).toBe('strict')
+    if (descriptor?.parameters[0]?.codec.mode === 'strict') {
+      expect(descriptor.parameters[0].codec.schema.parse('request')).toBe('request')
+    }
+
+    await fiber.dispose()
+    expect(ctx.typert.local.get('goals/create')).toBeUndefined()
+  })
+
   it('fails loud when an explicit package is absent or has no Typert export', LOADER_TEST_TIMEOUT, async () => {
     root = await mkdtemp(join(tmpdir(), 'dsh-typert-loader-'))
     await writePackage(root, '@fixture/plain')
@@ -427,8 +489,156 @@ describe('validateTypertManifest', () => {
       model: { ...complete.model, objects: [{ ...complete.model.objects[0], exportName: '' }] },
     })).toThrow('object has a missing or empty exportName')
   })
+
+  it('validates strict invocation descriptors and accepts legacy manifests without them', () => {
+    const legacy = completeManifest(zodish)
+    expect(validateTypertManifest('pkg', legacy)).toBe(legacy)
+
+    const descriptor = strictInvocation()
+    const manifest = { ...legacy, invocations: [descriptor] }
+    expect(validateTypertManifest('pkg', manifest)).toBe(manifest)
+    const scoped = {
+      ...descriptor,
+      scope: { context: 'agent', wire: 'agentId' },
+      parameters: [{
+        name: 'agent',
+        wire: 'agentId',
+        source: 'lookup',
+        lookup: 'agent',
+        codec: strictCodec('pkg#AgentId'),
+      }, ...descriptor.parameters],
+    }
+    expect(validateTypertManifest('pkg', { ...legacy, invocations: [scoped] }).invocations)
+      .toEqual([scoped])
+
+    expect(() => validateTypertManifest('pkg', { ...legacy, invocations: {} }))
+      .toThrow('TYPERT.invocations must be an array')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{ ...descriptor, invocation: { kind: 'future' } }],
+    })).toThrow('receiver kind must be "direct" or "context"')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{ ...descriptor, result: { mode: 'src-json' } }],
+    })).toThrow('result codec must use a strict codec')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{ ...descriptor, result: { mode: 'strict', typeSymbol: 'pkg#Result', schema: zodish } }],
+    })).toThrow('result codec is not backed by a zod v4 schema')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{
+        ...descriptor,
+        parameters: [{ ...descriptor.parameters[0], source: 'future' }],
+      }],
+    })).toThrow('parameter source must be "json" or "lookup"')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{
+        ...descriptor,
+        parameters: [{ ...descriptor.parameters[0], source: 'lookup' }],
+      }],
+    })).toThrow('lookup parameter has a missing or empty lookup')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{
+        ...descriptor,
+        parameters: [{ ...descriptor.parameters[0], lookup: 'agent' }],
+      }],
+    })).toThrow('JSON parameter declares a lookup')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{
+        ...descriptor,
+        parameters: [descriptor.parameters[0], { ...descriptor.parameters[0], name: 'again' }],
+      }],
+    })).toThrow('repeats wire field "request"')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{
+        ...descriptor,
+        invocation: {
+          kind: 'context',
+          context: 'agent',
+          wire: 'request',
+          codec: strictCodec('pkg#AgentId'),
+        },
+      }],
+    })).toThrow('repeats Context wire field "request"')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{ ...scoped, scope: null }],
+    })).toThrow('scope must be an object')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{ ...scoped, scope: { wire: 'agentId' } }],
+    })).toThrow('scope has a missing or empty context')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{ ...scoped, scope: { context: 'agent' } }],
+    })).toThrow('scope has a missing or empty wire')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{
+        ...scoped,
+        invocation: {
+          kind: 'context',
+          context: 'agent',
+          wire: 'scopeId',
+          codec: strictCodec('pkg#AgentId'),
+        },
+      }],
+    })).toThrow('Context receiver cannot declare a direct scope projection')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{ ...scoped, scope: { context: 'agent', wire: 'missingId' } }],
+    })).toThrow('must select its only lookup parameter')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{
+        ...scoped,
+        parameters: [...scoped.parameters, {
+          name: 'other',
+          wire: 'otherId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: strictCodec('pkg#AgentId'),
+        }],
+      }],
+    })).toThrow('must select its only lookup parameter')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{ ...scoped, scope: { context: 'other', wire: 'agentId' } }],
+    })).toThrow('must select its only lookup parameter')
+    expect(() => validateTypertManifest('pkg', {
+      ...legacy,
+      invocations: [{ ...descriptor, sourceLocation: { file: 'src/index.ts', line: 0, column: 1 } }],
+    })).toThrow('sourceLocation.line must be a positive integer')
+  })
 })
 
+function strictCodec(typeSymbol: string) {
+  return { mode: 'strict', typeSymbol, schema: z.string() }
+}
+
+function strictInvocation() {
+  return {
+    id: 'pkg#goals/create',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'create',
+    invocation: { kind: 'direct' },
+    parameters: [{
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: strictCodec('pkg#Request'),
+    }],
+    result: strictCodec('pkg#Result'),
+    sourceLocation: { file: 'src/index.ts', line: 1, column: 1 },
+  }
+}
+
 function completeManifest(zodish: object) {
   const member = { name: 'member', signature: 'member(): void', kind: 'method' }
   const type = { name: 'Value', declaration: 'export interface Value {}' }
diff --git a/packages/typert/registry/package.json b/packages/typert/registry/package.json
index b543589dc6..e912808293 100644
--- a/packages/typert/registry/package.json
+++ b/packages/typert/registry/package.json
@@ -15,6 +15,10 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
     "./types": {
       "types": "./lib/types/types.d.ts",
       "default": "./lib/types/types.js"
@@ -22,14 +26,25 @@
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
+  "dshClient": {
+    "inject": [],
+    "platform": "web",
+    "immediately": true
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/client.js",
     "lib/types/**/*.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
diff --git a/packages/typert/registry/src/client/index.ts b/packages/typert/registry/src/client/index.ts
new file mode 100644
index 0000000000..e468e78999
--- /dev/null
+++ b/packages/typert/registry/src/client/index.ts
@@ -0,0 +1,15 @@
+/** Browser face of the shared TypeRT runtime registry. */
+
+import type { Context } from 'cordis'
+import { TypertRegistry } from '../service.ts'
+
+/** Required services: none; this is the Client reflection root. */
+export const inject: string[] = []
+
+/**
+ * Install the same registry implementation used by the Host face.
+ * @param ctx - Client Cordis root.
+ */
+export function apply(ctx: Context): void {
+  new TypertRegistry(ctx)
+}
diff --git a/packages/typert/registry/src/index.ts b/packages/typert/registry/src/index.ts
index 91a8383594..3619c02dff 100644
--- a/packages/typert/registry/src/index.ts
+++ b/packages/typert/registry/src/index.ts
@@ -1,12 +1,7 @@
-/**
- * Runtime registry for generated Typert contributions. It owns live Zod
- * instances and generated package reflection, but performs no TypeScript
- * analysis or schema generation.
- * @module @deepseek-ai/dsh-typert-registry
- */
+/** Host entry for the shared TypeRT runtime registry. */
 
-import { Context, Service } from 'cordis'
-import { z } from 'zod'
+import type { z } from 'zod'
+import type { TypeRTDisposer } from '@deepseek-ai/dsh-type-meta'
 import type {
   TypertContribution,
   TypertFace,
@@ -16,204 +11,17 @@ import type {
   TypertSchemaRecord,
 } from './types.ts'
 
-export type {
-  TypertContribution,
-  TypertDocTag,
-  TypertDocumentation,
-  TypertEventModel,
-  TypertFace,
-  TypertMemberModel,
-  TypertObjectModel,
-  TypertPackageFilter,
-  TypertPackageModel,
-  TypertPackageRecord,
-  TypertSchema,
-  TypertSchemaFilter,
-  TypertSchemaRecord,
-  TypertServiceModel,
-  TypertTypeModel,
-} from './types.ts'
+export { default, TypertRegistry, typertEndpoint, typertKey, typertPackageKey } from './service.ts'
+export type * from './types.ts'
 
-declare module 'cordis' {
-  interface Context {
-    typert: TypertRegistry
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTService {
+    register(contribution: TypertContribution): TypeRTDisposer
+    get(key: string): TypertSchemaRecord | undefined
+    resolve(key: string): TypertSchemaRecord
+    list(filter?: TypertSchemaFilter): TypertSchemaRecord[]
+    getPackage(packageName: string, face?: TypertFace): TypertPackageRecord | undefined
+    listPackages(filter?: TypertPackageFilter): TypertPackageRecord[]
+    toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
   }
 }
-
-/**
- * Compose the global key of one generated schema.
- * @param packageName - contributing npm package.
- * @param name - schema export name.
- * @returns `<package>#<name>`.
- */
-export function typertKey(packageName: string, name: string): string {
-  return `${packageName}#${name}`
-}
-
-/**
- * Compose the identity of one package-face model.
- * @param packageName - contributing npm package.
- * @param face - independently compiled face.
- * @returns `<package>#<face>`.
- */
-export function typertPackageKey(packageName: string, face: TypertFace): string {
-  return `${packageName}#${face}`
-}
-
-/**
- * Registry of generated schemas and package reflection.
- * @typert service
- */
-export class TypertRegistry extends Service {
-  private readonly schemas = new Map<string, TypertSchemaRecord>()
-  private readonly packages = new Map<string, TypertPackageRecord>()
-
-  constructor(ctx: Context) {
-    super(ctx, 'typert')
-  }
-
-  /**
-   * Register one generated contribution atomically for the calling fiber.
-   * Duplicate package-face identities or schema keys reject the whole batch.
-   * @param contribution - generated schemas and package metadata.
-   * @returns the exact effect disposer that removes this contribution.
-   */
-  register(contribution: TypertContribution): () => void {
-    const packageRecord = this.validatePackage(contribution)
-    const schemaRecords = this.validateSchemas(contribution)
-    const { schemas, packages } = this
-    const dispose = this.ctx.effect(function* () {
-      packages.set(packageRecord.key, packageRecord)
-      for (const record of schemaRecords) schemas.set(record.key, record)
-      yield () => {
-        packages.delete(packageRecord.key)
-        for (const record of schemaRecords) schemas.delete(record.key)
-      }
-    }, 'typert.register()')
-    // oxlint-disable-next-line typescript/no-misused-promises -- synchronous cleanup; preserve Cordis disposer identity
-    return dispose
-  }
-
-  /**
-   * Look up one schema by `<package>#<name>`.
-   * @param key - global schema key.
-   * @returns the live schema record, or `undefined` when absent.
-   */
-  get(key: string): TypertSchemaRecord | undefined {
-    return this.schemas.get(key)
-  }
-
-  /**
-   * Resolve one required schema.
-   * @param key - global schema key.
-   * @returns the live schema record.
-   * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
-   */
-  resolve(key: string): TypertSchemaRecord {
-    const record = this.schemas.get(key)
-    if (record !== undefined) return record
-    const hash = key.indexOf('#')
-    if (hash <= 0 || hash === key.length - 1) {
-      throw new Error(`typert: invalid schema key "${key}" — expected "<package>#<name>"`)
-    }
-    const packageName = key.slice(0, hash)
-    if ([...this.packages.values()].some(candidate => candidate.package === packageName)) {
-      throw new Error(
-        `typert: cannot resolve "${key}" — package "${packageName}" is registered but contributes no schema named "${key.slice(hash + 1)}"`,
-      )
-    }
-    throw new Error(`typert: cannot resolve "${key}" — package "${packageName}" has no registered contribution`)
-  }
-
-  /**
-   * Enumerate live schemas in registration order.
-   * @param filter - optional package and face restriction.
-   * @returns matching schema records.
-   */
-  list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[] {
-    return [...this.schemas.values()].filter(record => matches(record, filter))
-  }
-
-  /**
-   * Look up generated reflection for one package face.
-   * @param packageName - exact npm package name.
-   * @param face - face to query; defaults to the host runtime.
-   * @returns the live package record, or `undefined` when absent.
-   */
-  getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined {
-    return this.packages.get(typertPackageKey(packageName, face))
-  }
-
-  /**
-   * Enumerate generated package reflection in registration order.
-   * @param filter - optional package and face restriction.
-   * @returns matching package records.
-   */
-  listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[] {
-    return [...this.packages.values()].filter(record => matches(record, filter))
-  }
-
-  /**
-   * Project a live Zod schema to JSON Schema without caching the result.
-   * @param key - global schema key.
-   * @param params - Zod projection parameters.
-   * @returns a fresh JSON Schema document.
-   */
-  toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema {
-    return z.toJSONSchema(this.resolve(key).schema, params)
-  }
-
-  private validatePackage(contribution: TypertContribution): TypertPackageRecord {
-    validateSegment('package name', contribution.package)
-    const face: unknown = contribution.face
-    if (face !== 'host' && face !== 'client') {
-      throw new Error(`typert: invalid face ${JSON.stringify(face)} — expected "host" or "client"`)
-    }
-    const key = typertPackageKey(contribution.package, contribution.face)
-    if (this.packages.has(key)) {
-      throw new Error(`typert: package face "${key}" is already registered`)
-    }
-    return {
-      package: contribution.package,
-      face,
-      key,
-      model: contribution.model,
-    }
-  }
-
-  private validateSchemas(contribution: TypertContribution): TypertSchemaRecord[] {
-    const records: TypertSchemaRecord[] = []
-    const batch = new Set<string>()
-    for (const schema of contribution.schemas) {
-      validateSegment('schema name', schema.name)
-      const key = typertKey(contribution.package, schema.name)
-      if (batch.has(key) || this.schemas.has(key)) {
-        throw new Error(`typert: schema "${key}" is already registered`)
-      }
-      batch.add(key)
-      records.push({
-        ...schema,
-        package: contribution.package,
-        face: contribution.face,
-        key,
-      })
-    }
-    return records
-  }
-}
-
-function matches(
-  record: { readonly package: string; readonly face: TypertFace },
-  filter: { readonly package?: string; readonly face?: TypertFace },
-): boolean {
-  return (filter.package === undefined || record.package === filter.package)
-    && (filter.face === undefined || record.face === filter.face)
-}
-
-function validateSegment(subject: string, value: string): void {
-  if (value.length === 0 || value.includes('#')) {
-    throw new Error(`typert: invalid ${subject} "${value}" — must be nonempty and must not contain "#"`)
-  }
-}
-
-export default TypertRegistry
diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
new file mode 100644
index 0000000000..16160a3860
--- /dev/null
+++ b/packages/typert/registry/src/service.ts
@@ -0,0 +1,584 @@
+/**
+ * Runtime registry for generated TypeRT reflection, Remote invocations, and
+ * dependency-inverted lookup/Context providers. It performs no TypeScript
+ * analysis or schema generation.
+ * @module @deepseek-ai/dsh-typert-registry
+ */
+
+import { Context, Service } from 'cordis'
+import { z } from 'zod'
+import type {
+  InvocationDescriptor,
+  TypeRTClientContextBinder,
+  TypeRTContextMap,
+  TypeRTContextRegistry,
+  TypeRTContextWire,
+  TypeRTDisposer,
+  TypeRTHostContextProvider,
+  TypeRTLocalRegistry,
+  TypeRTLookupHost,
+  TypeRTLookupMap,
+  TypeRTLookupProvider,
+  TypeRTLookupRegistry,
+  TypeRTLookupWire,
+  TypeRTRemoteContribution,
+  TypeRTRemoteRegistry,
+  TypeRTRegistryChange,
+  TypeRTRegistryListener,
+  TypeRTService,
+} from '@deepseek-ai/dsh-type-meta'
+import type {
+  TypertContribution,
+  TypertFace,
+  TypertPackageFilter,
+  TypertPackageRecord,
+  TypertSchemaFilter,
+  TypertSchemaRecord,
+} from './types.ts'
+
+/**
+ * Compose the global key of one generated schema.
+ * @param packageName - contributing npm package.
+ * @param name - schema export name.
+ * @returns `<package>#<name>`.
+ */
+export function typertKey(packageName: string, name: string): string {
+  return `${packageName}#${name}`
+}
+
+/**
+ * Compose the identity of one package-face model.
+ * @param packageName - contributing npm package.
+ * @param face - independently compiled face.
+ * @returns `<package>#<face>`.
+ */
+export function typertPackageKey(packageName: string, face: TypertFace): string {
+  return `${packageName}#${face}`
+}
+
+/**
+ * Compose the endpoint key used by local and Remote invocation registries.
+ * @param descriptor - invocation whose namespace and method form the endpoint.
+ * @returns `<namespace>/<method>`.
+ */
+export function typertEndpoint(descriptor: Pick<InvocationDescriptor, 'namespace' | 'method'>): string {
+  return `${descriptor.namespace}/${descriptor.method}`
+}
+
+interface DescriptorEntry {
+  readonly descriptor: InvocationDescriptor
+  readonly owner: object
+}
+
+interface ProviderEntry<Provider> {
+  readonly provider: Provider
+  readonly owner: object
+}
+
+type ReportObserverError = (change: TypeRTRegistryChange, error: unknown) => void
+
+class ChangeSource {
+  private readonly listeners = new Set<TypeRTRegistryListener>()
+
+  constructor(private readonly report: ReportObserverError) {}
+
+  subscribe(ctx: Context, listener: TypeRTRegistryListener): TypeRTDisposer {
+    const { listeners } = this
+    return ctx.effect(function* () {
+      listeners.add(listener)
+      yield () => { listeners.delete(listener) }
+    }, 'typert registry subscription')
+  }
+
+  emit(change: TypeRTRegistryChange): void {
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(change)
+      } catch (error) {
+        this.report(change, error)
+      }
+    }
+  }
+}
+
+class DescriptorStore {
+  private readonly entries = new Map<string, DescriptorEntry>()
+  private readonly ids = new Map<string, DescriptorEntry>()
+  private readonly history = new Set<string>()
+  private readonly changes: ChangeSource
+
+  constructor(
+    private readonly kind: 'local' | 'remote',
+    report: ReportObserverError,
+  ) {
+    this.changes = new ChangeSource(report)
+  }
+
+  validate(descriptors: readonly InvocationDescriptor[]): void {
+    const endpoints = new Set<string>()
+    const ids = new Set<string>()
+    for (const descriptor of descriptors) {
+      validateInvocation(descriptor)
+      const endpoint = typertEndpoint(descriptor)
+      if (endpoints.has(endpoint) || this.entries.has(endpoint)) {
+        throw new Error(`typert: ${this.kind} endpoint "${endpoint}" is already registered`)
+      }
+      if (ids.has(descriptor.id) || this.ids.has(descriptor.id)) {
+        throw new Error(`typert: ${this.kind} invocation id "${descriptor.id}" is already registered`)
+      }
+      endpoints.add(endpoint)
+      ids.add(descriptor.id)
+    }
+  }
+
+  commit(owner: object, descriptors: readonly InvocationDescriptor[]): void {
+    for (const descriptor of descriptors) {
+      const entry = { descriptor, owner }
+      const endpoint = typertEndpoint(descriptor)
+      this.entries.set(endpoint, entry)
+      this.ids.set(descriptor.id, entry)
+      this.history.add(endpoint)
+    }
+    for (const descriptor of descriptors) {
+      this.changes.emit({ kind: this.kind, key: typertEndpoint(descriptor) })
+    }
+  }
+
+  withdraw(owner: object, descriptors: readonly InvocationDescriptor[]): void {
+    const removed: string[] = []
+    for (const descriptor of descriptors) {
+      const endpoint = typertEndpoint(descriptor)
+      const entry = this.entries.get(endpoint)
+      if (entry?.owner !== owner) continue
+      this.entries.delete(endpoint)
+      if (this.ids.get(descriptor.id) === entry) this.ids.delete(descriptor.id)
+      removed.push(endpoint)
+    }
+    for (const endpoint of removed) this.changes.emit({ kind: this.kind, key: endpoint })
+  }
+
+  get(endpoint: string): InvocationDescriptor | undefined {
+    return this.entries.get(endpoint)?.descriptor
+  }
+
+  hasSeen(endpoint: string): boolean {
+    return this.history.has(endpoint)
+  }
+
+  list(): readonly InvocationDescriptor[] {
+    return [...this.entries.values()].map(entry => entry.descriptor)
+  }
+
+  subscribe(ctx: Context, listener: TypeRTRegistryListener): TypeRTDisposer {
+    return this.changes.subscribe(ctx, listener)
+  }
+}
+
+class RemoteStore {
+  private readonly packages = new Map<string, object>()
+
+  constructor(private readonly descriptors: DescriptorStore) {}
+
+  view(ctx: Context): TypeRTRemoteRegistry {
+    return {
+      register: contribution => this.register(ctx, contribution),
+      get: endpoint => this.descriptors.get(endpoint),
+      list: () => this.descriptors.list(),
+      subscribe: listener => this.descriptors.subscribe(ctx, listener),
+    }
+  }
+
+  private register(ctx: Context, contribution: TypeRTRemoteContribution): TypeRTDisposer {
+    validateSegment('Remote package name', contribution.package)
+    if (this.packages.has(contribution.package)) {
+      throw new Error(`typert: Remote package "${contribution.package}" is already registered`)
+    }
+    this.descriptors.validate(contribution.descriptors)
+    const owner = {}
+    const { packages, descriptors } = this
+    return ctx.effect(function* () {
+      packages.set(contribution.package, owner)
+      descriptors.commit(owner, contribution.descriptors)
+      yield () => {
+        if (packages.get(contribution.package) === owner) packages.delete(contribution.package)
+        descriptors.withdraw(owner, contribution.descriptors)
+      }
+    }, `typert.remotes.register(${JSON.stringify(contribution.package)})`)
+  }
+}
+
+class LookupStore {
+  private readonly providers = new Map<string, ProviderEntry<TypeRTLookupProvider>>()
+  private readonly changes: ChangeSource
+
+  constructor(report: ReportObserverError) {
+    this.changes = new ChangeSource(report)
+  }
+
+  view(ctx: Context): TypeRTLookupRegistry {
+    return {
+      register: <K extends Extract<keyof TypeRTLookupMap, string>>(
+        key: K,
+        provider: TypeRTLookupProvider<
+          TypeRTLookupHost<TypeRTLookupMap[K]>,
+          TypeRTLookupWire<TypeRTLookupMap[K]>
+        >,
+      ) => this.register(ctx, key, provider),
+      get: key => this.providers.get(key)?.provider,
+      keys: () => [...this.providers.keys()],
+      subscribe: listener => this.changes.subscribe(ctx, listener),
+    }
+  }
+
+  private register<Host, Wire>(ctx: Context, key: string, provider: TypeRTLookupProvider<Host, Wire>): TypeRTDisposer {
+    validateSegment('lookup key', key)
+    validateSegment('lookup parameter', provider.parameter)
+    validateWireName('lookup wire field', provider.wire)
+    validateNonempty('lookup Host type symbol', provider.hostTypeSymbol)
+    validateNonempty('lookup wire type symbol', provider.wireTypeSymbol)
+    if (this.providers.has(key)) throw new Error(`typert: lookup "${key}" is already registered`)
+    const owner = {}
+    const entry: ProviderEntry<TypeRTLookupProvider> = { provider, owner }
+    const { providers, changes } = this
+    return ctx.effect(function* () {
+      providers.set(key, entry)
+      changes.emit({ kind: 'lookup', key })
+      yield () => {
+        if (providers.get(key) !== entry) return
+        providers.delete(key)
+        changes.emit({ kind: 'lookup', key })
+      }
+    }, `typert.lookups.register(${JSON.stringify(key)})`)
+  }
+}
+
+class ContextStore {
+  private readonly hosts = new Map<string, ProviderEntry<TypeRTHostContextProvider>>()
+  private readonly clients = new Map<string, ProviderEntry<TypeRTClientContextBinder>>()
+  private readonly changes: ChangeSource
+
+  constructor(report: ReportObserverError) {
+    this.changes = new ChangeSource(report)
+  }
+
+  view(ctx: Context): TypeRTContextRegistry {
+    return {
+      registerHost: <K extends Extract<keyof TypeRTContextMap, string>>(
+        key: K,
+        provider: TypeRTHostContextProvider<TypeRTContextWire<TypeRTContextMap[K]>>,
+      ) => this.registerHost(ctx, key, provider),
+      registerClient: <K extends Extract<keyof TypeRTContextMap, string>>(
+        key: K,
+        binder: TypeRTClientContextBinder<TypeRTContextWire<TypeRTContextMap[K]>>,
+      ) => this.registerClient(ctx, key, binder),
+      getHost: key => this.hosts.get(key)?.provider,
+      getClient: key => this.clients.get(key)?.provider,
+      subscribe: listener => this.changes.subscribe(ctx, listener),
+    }
+  }
+
+  private registerHost<Wire>(ctx: Context, key: string, provider: TypeRTHostContextProvider<Wire>): TypeRTDisposer {
+    validateSegment('Context key', key)
+    validateWireName('Context wire field', provider.wire)
+    validateNonempty('Context wire type symbol', provider.wireTypeSymbol)
+    return this.registerProvider(ctx, this.hosts, 'host-context', key, provider)
+  }
+
+  private registerClient<Wire>(ctx: Context, key: string, binder: TypeRTClientContextBinder<Wire>): TypeRTDisposer {
+    validateSegment('Context key', key)
+    return this.registerProvider(ctx, this.clients, 'client-context', key, binder)
+  }
+
+  private registerProvider<Provider>(
+    ctx: Context,
+    table: Map<string, ProviderEntry<Provider>>,
+    kind: 'host-context' | 'client-context',
+    key: string,
+    provider: Provider,
+  ): TypeRTDisposer {
+    if (table.has(key)) throw new Error(`typert: ${kind} provider "${key}" is already registered`)
+    const entry: ProviderEntry<Provider> = { provider, owner: {} }
+    const { changes } = this
+    return ctx.effect(function* () {
+      table.set(key, entry)
+      changes.emit({ kind, key })
+      yield () => {
+        if (table.get(key) !== entry) return
+        table.delete(key)
+        changes.emit({ kind, key })
+      }
+    }, `typert.contexts.register(${JSON.stringify(key)})`)
+  }
+}
+
+/**
+ * Registry of generated schemas, package reflection, invocations, and Remote
+ * dependency providers.
+ * @typert service typert
+ */
+export class TypertRegistry extends Service implements TypeRTService {
+  private readonly schemas = new Map<string, TypertSchemaRecord>()
+  private readonly packages = new Map<string, TypertPackageRecord>()
+  private readonly localStore: DescriptorStore
+  private readonly remoteStore: RemoteStore
+  private readonly lookupStore: LookupStore
+  private readonly contextStore: ContextStore
+
+  constructor(ctx: Context) {
+    super(ctx, 'typert')
+    const report: ReportObserverError = (change, error) => {
+      ctx.logger.warn(`typert: ${change.kind} observer for "${change.key}" failed`)
+      ctx.logger.warn(error)
+    }
+    this.localStore = new DescriptorStore('local', report)
+    this.remoteStore = new RemoteStore(new DescriptorStore('remote', report))
+    this.lookupStore = new LookupStore(report)
+    this.contextStore = new ContextStore(report)
+  }
+
+  /** Current-environment invocation definitions. */
+  get local(): TypeRTLocalRegistry {
+    const ctx = this.ctx
+    return {
+      get: endpoint => this.localStore.get(endpoint),
+      hasSeen: endpoint => this.localStore.hasSeen(endpoint),
+      list: () => this.localStore.list(),
+      subscribe: listener => this.localStore.subscribe(ctx, listener),
+    }
+  }
+
+  /** Consumer-selected Remote definitions. */
+  get remotes(): TypeRTRemoteRegistry {
+    return this.remoteStore.view(this.ctx)
+  }
+
+  /** Host object lookup providers. */
+  get lookups(): TypeRTLookupRegistry {
+    return this.lookupStore.view(this.ctx)
+  }
+
+  /** Host Context providers and Client Context binders. */
+  get contexts(): TypeRTContextRegistry {
+    return this.contextStore.view(this.ctx)
+  }
+
+  /**
+   * Register one generated contribution atomically for the calling fiber.
+   * Duplicate package-face identities, schemas, invocation ids, or endpoints
+   * reject the whole batch.
+   * @param contribution - generated schemas, reflection, and Host invocations.
+   * @returns the exact effect disposer that removes this contribution.
+   */
+  register(contribution: TypertContribution): TypeRTDisposer {
+    const packageRecord = this.validatePackage(contribution)
+    const schemaRecords = this.validateSchemas(contribution)
+    const invocations = contribution.invocations ?? []
+    this.localStore.validate(invocations)
+    const owner = {}
+    const { schemas, packages, localStore } = this
+    return this.ctx.effect(function* () {
+      packages.set(packageRecord.key, packageRecord)
+      for (const record of schemaRecords) schemas.set(record.key, record)
+      localStore.commit(owner, invocations)
+      yield () => {
+        if (packages.get(packageRecord.key) === packageRecord) packages.delete(packageRecord.key)
+        for (const record of schemaRecords) {
+          if (schemas.get(record.key) === record) schemas.delete(record.key)
+        }
+        localStore.withdraw(owner, invocations)
+      }
+    }, 'typert.register()')
+  }
+
+  /**
+   * Look up one schema by `<package>#<name>`.
+   * @param key - global schema key.
+   * @returns the live schema record, or `undefined` when absent.
+   */
+  get(key: string): TypertSchemaRecord | undefined {
+    return this.schemas.get(key)
+  }
+
+  /**
+   * Resolve one required schema.
+   * @param key - global schema key.
+   * @returns the live schema record.
+   * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
+   */
+  resolve(key: string): TypertSchemaRecord {
+    const record = this.schemas.get(key)
+    if (record !== undefined) return record
+    const hash = key.indexOf('#')
+    if (hash <= 0 || hash === key.length - 1) {
+      throw new Error(`typert: invalid schema key "${key}" — expected "<package>#<name>"`)
+    }
+    const packageName = key.slice(0, hash)
+    if ([...this.packages.values()].some(candidate => candidate.package === packageName)) {
+      throw new Error(
+        `typert: cannot resolve "${key}" — package "${packageName}" is registered but contributes no schema named "${key.slice(hash + 1)}"`,
+      )
+    }
+    throw new Error(`typert: cannot resolve "${key}" — package "${packageName}" has no registered contribution`)
+  }
+
+  /**
+   * Enumerate live schemas in registration order.
+   * @param filter - optional package and face restriction.
+   * @returns matching schema records.
+   */
+  list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[] {
+    return [...this.schemas.values()].filter(record => matches(record, filter))
+  }
+
+  /**
+   * Look up generated reflection for one package face.
+   * @param packageName - exact npm package name.
+   * @param face - face to query; defaults to the host runtime.
+   * @returns the live package record, or `undefined` when absent.
+   */
+  getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined {
+    return this.packages.get(typertPackageKey(packageName, face))
+  }
+
+  /**
+   * Enumerate generated package reflection in registration order.
+   * @param filter - optional package and face restriction.
+   * @returns matching package records.
+   */
+  listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[] {
+    return [...this.packages.values()].filter(record => matches(record, filter))
+  }
+
+  /**
+   * Project a live Zod schema to JSON Schema without caching the result.
+   * @param key - global schema key.
+   * @param params - Zod projection parameters.
+   * @returns a fresh JSON Schema document.
+   */
+  toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema {
+    return z.toJSONSchema(this.resolve(key).schema, params)
+  }
+
+  private validatePackage(contribution: TypertContribution): TypertPackageRecord {
+    validateSegment('package name', contribution.package)
+    const face: unknown = contribution.face
+    if (face !== 'host' && face !== 'client') {
+      throw new Error(`typert: invalid face ${JSON.stringify(face)} — expected "host" or "client"`)
+    }
+    const key = typertPackageKey(contribution.package, contribution.face)
+    if (this.packages.has(key)) {
+      throw new Error(`typert: package face "${key}" is already registered`)
+    }
+    return {
+      package: contribution.package,
+      face,
+      key,
+      model: contribution.model,
+    }
+  }
+
+  private validateSchemas(contribution: TypertContribution): TypertSchemaRecord[] {
+    const records: TypertSchemaRecord[] = []
+    const batch = new Set<string>()
+    for (const schema of contribution.schemas) {
+      validateSegment('schema name', schema.name)
+      const key = typertKey(contribution.package, schema.name)
+      if (batch.has(key) || this.schemas.has(key)) {
+        throw new Error(`typert: schema "${key}" is already registered`)
+      }
+      batch.add(key)
+      records.push({
+        ...schema,
+        package: contribution.package,
+        face: contribution.face,
+        key,
+      })
+    }
+    return records
+  }
+}
+
+function matches(
+  record: { readonly package: string; readonly face: TypertFace },
+  filter: { readonly package?: string; readonly face?: TypertFace },
+): boolean {
+  return (filter.package === undefined || record.package === filter.package)
+    && (filter.face === undefined || record.face === filter.face)
+}
+
+function validateInvocation(descriptor: InvocationDescriptor): void {
+  validateNonempty('invocation id', descriptor.id)
+  validateSegment('invocation service key', descriptor.service)
+  validateWireName('invocation namespace', descriptor.namespace)
+  validateWireName('invocation method', descriptor.method)
+  if (descriptor.implementation !== undefined) {
+    validateWireName('invocation implementation method', descriptor.implementation)
+  }
+  validateCodec(descriptor.result, `${descriptor.id} result`)
+  const wires = new Set<string>()
+  for (const parameter of descriptor.parameters) {
+    validateWireName('parameter name', parameter.name)
+    validateWireName('parameter wire field', parameter.wire)
+    if (wires.has(parameter.wire)) {
+      throw new Error(`typert: invocation "${descriptor.id}" repeats wire field "${parameter.wire}"`)
+    }
+    wires.add(parameter.wire)
+    if (parameter.source === 'lookup') {
+      if (parameter.lookup === undefined) {
+        throw new Error(`typert: invocation "${descriptor.id}" lookup parameter "${parameter.name}" has no lookup key`)
+      }
+      validateSegment('lookup key', parameter.lookup)
+    } else if (parameter.lookup !== undefined) {
+      throw new Error(`typert: invocation "${descriptor.id}" JSON parameter "${parameter.name}" declares a lookup key`)
+    }
+    validateCodec(parameter.codec, `${descriptor.id} parameter ${parameter.name}`)
+  }
+  if (descriptor.scope !== undefined) {
+    if (descriptor.invocation.kind !== 'direct') {
+      throw new Error(`typert: invocation "${descriptor.id}" Context receiver cannot declare a direct scope projection`)
+    }
+    validateSegment('scope Context key', descriptor.scope.context)
+    validateWireName('scope wire field', descriptor.scope.wire)
+    const lookups = descriptor.parameters.filter(candidate => candidate.source === 'lookup')
+    const parameter = lookups.length === 1 ? lookups[0] : undefined
+    if (parameter === undefined || parameter.wire !== descriptor.scope.wire
+      || parameter.lookup !== descriptor.scope.context) {
+      throw new Error(
+        `typert: invocation "${descriptor.id}" scope wire "${descriptor.scope.wire}" must select its only lookup parameter`,
+      )
+    }
+  }
+  if (descriptor.invocation.kind === 'context') {
+    validateSegment('Context key', descriptor.invocation.context)
+    validateWireName('Context wire field', descriptor.invocation.wire)
+    if (wires.has(descriptor.invocation.wire)) {
+      throw new Error(`typert: invocation "${descriptor.id}" repeats wire field "${descriptor.invocation.wire}"`)
+    }
+    validateCodec(descriptor.invocation.codec, `${descriptor.id} Context`)
+  }
+}
+
+function validateCodec(codec: InvocationDescriptor['result'], subject: string): void {
+  if (codec.mode === 'src-json') return
+  validateNonempty(`${subject} type symbol`, codec.typeSymbol)
+  if (typeof codec.schema.parse !== 'function') {
+    throw new Error(`typert: ${subject} strict codec has no parse() method`)
+  }
+}
+
+function validateWireName(subject: string, value: string): void {
+  validateSegment(subject, value)
+  if (value.includes('/')) throw new Error(`typert: invalid ${subject} "${value}" — must not contain "/"`)
+}
+
+function validateSegment(subject: string, value: string): void {
+  if (value.length === 0 || value.includes('#')) {
+    throw new Error(`typert: invalid ${subject} "${value}" — must be nonempty and must not contain "#"`)
+  }
+}
+
+function validateNonempty(subject: string, value: string): void {
+  if (value.length === 0) throw new Error(`typert: invalid ${subject} — must be nonempty`)
+}
+
+export default TypertRegistry
diff --git a/packages/typert/registry/src/types.ts b/packages/typert/registry/src/types.ts
index 2fb29f5024..6ba0e0f1f2 100644
--- a/packages/typert/registry/src/types.ts
+++ b/packages/typert/registry/src/types.ts
@@ -5,6 +5,7 @@
  */
 
 import type { z } from 'zod'
+import type { InvocationDescriptor } from '@deepseek-ai/dsh-type-meta'
 
 /** Independently compiled side that produced a contribution. */
 export type TypertFace = 'host' | 'client'
@@ -82,6 +83,13 @@ export interface TypertContribution {
   readonly face: TypertFace
   readonly schemas: readonly TypertSchema[]
   readonly model: TypertPackageModel
+  /** Host invocation definitions; absent on artifacts generated before Remote support. */
+  readonly invocations?: readonly InvocationDescriptor[]
+}
+
+/** Generated Host contribution with strict Remote invocation definitions. */
+export interface TypertLocalContribution extends TypertContribution {
+  readonly invocations: readonly InvocationDescriptor[]
 }
 
 /** A live schema plus its contribution identity. */
diff --git a/packages/typert/registry/tests/typert.spec.ts b/packages/typert/registry/tests/typert.spec.ts
index 06eb9c107e..a98f99f912 100644
--- a/packages/typert/registry/tests/typert.spec.ts
+++ b/packages/typert/registry/tests/typert.spec.ts
@@ -2,10 +2,27 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { z } from 'zod'
 import TypertRegistry, {
+  typertEndpoint,
   typertKey,
   typertPackageKey,
   type TypertContribution,
 } from '@deepseek-ai/dsh-typert-registry'
+import type {
+  InvocationDescriptor,
+  TypeRTContext,
+  TypeRTLookup,
+  TypeRTRemoteContribution,
+} from '@deepseek-ai/dsh-type-meta'
+
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTLookupMap {
+    fixture: TypeRTLookup<{ readonly id: string }, string>
+  }
+
+  interface TypeRTContextMap {
+    registryFixture: TypeRTContext<string>
+  }
+}
 
 async function makeCtx(): Promise<Context> {
   const ctx = new Context()
@@ -42,6 +59,42 @@ function toolsContribution(schema: z.ZodType = z.object({ name: z.string() })):
   }
 }
 
+function invocation(id = '@fixture/remote#goals/create'): InvocationDescriptor {
+  return {
+    id,
+    service: 'goals',
+    namespace: 'goals',
+    method: 'create',
+    invocation: { kind: 'direct' },
+    parameters: [{
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: { mode: 'src-json' },
+    }],
+    result: { mode: 'src-json' },
+  }
+}
+
+function scopedInvocation(): InvocationDescriptor {
+  return {
+    ...invocation('@fixture/remote#goals/create-scoped'),
+    scope: { context: 'fixture', wire: 'agentId' },
+    parameters: [{
+      name: 'agent',
+      wire: 'agentId',
+      source: 'lookup',
+      lookup: 'fixture',
+      codec: { mode: 'src-json' },
+    }, {
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: { mode: 'src-json' },
+    }],
+  }
+}
+
 describe('TypertRegistry', () => {
   it('registers and queries generated schemas separately from package reflection', async () => {
     const ctx = await makeCtx()
@@ -69,7 +122,7 @@ describe('TypertRegistry', () => {
     const dispose = ctx.typert.register(toolsContribution())
     expect(ctx.typert.getPackage('@deepseek-ai/dsh-tools')).toBeDefined()
 
-    dispose()
+    await dispose()
 
     expect(ctx.typert.get('@deepseek-ai/dsh-tools#ToolInput')).toBeUndefined()
     expect(ctx.typert.getPackage('@deepseek-ai/dsh-tools')).toBeUndefined()
@@ -145,4 +198,133 @@ describe('TypertRegistry', () => {
     expect(projected).toMatchObject({ type: 'object', properties: { name: { type: 'string' } } })
     expect(ctx.typert.toJSONSchema('@deepseek-ai/dsh-tools#ToolInput')).not.toBe(projected)
   })
+
+  it('registers local invocations atomically with generated reflection', async () => {
+    const ctx = await makeCtx()
+    const descriptor = invocation()
+    const contribution = { ...toolsContribution(), invocations: [descriptor] }
+    const changes: string[] = []
+    ctx.typert.local.subscribe((change) => { changes.push(`${change.kind}:${change.key}`) })
+
+    expect(ctx.typert.local.hasSeen('goals/create')).toBe(false)
+    const dispose = ctx.typert.register(contribution)
+
+    expect(typertEndpoint(descriptor)).toBe('goals/create')
+    expect(ctx.typert.local.get('goals/create')).toBe(descriptor)
+    expect(ctx.typert.local.hasSeen('goals/create')).toBe(true)
+    expect(ctx.typert.local.list()).toEqual([descriptor])
+    expect(changes).toEqual(['local:goals/create'])
+
+    await dispose()
+    expect(ctx.typert.local.list()).toEqual([])
+    expect(ctx.typert.local.hasSeen('goals/create')).toBe(true)
+    expect(ctx.typert.getPackage('@deepseek-ai/dsh-tools')).toBeUndefined()
+    expect(changes).toEqual(['local:goals/create', 'local:goals/create'])
+  })
+
+  it('mounts Remote contributions in the calling fiber and withdraws them exactly', async () => {
+    const ctx = await makeCtx()
+    const descriptor = invocation()
+    const contribution: TypeRTRemoteContribution = {
+      package: '@fixture/remote',
+      descriptors: [descriptor],
+    }
+    const changes: string[] = []
+    ctx.typert.remotes.subscribe((change) => { changes.push(`${change.kind}:${change.key}`) })
+    const fiber = ctx.plugin(Object.assign(
+      (child: Context) => { child.typert.remotes.register(contribution) },
+      { inject: ['typert'] },
+    ))
+    await fiber
+
+    expect(ctx.typert.remotes.get('goals/create')).toBe(descriptor)
+    expect(() => ctx.typert.remotes.register(contribution)).toThrow('Remote package')
+
+    await fiber.dispose()
+    expect(ctx.typert.remotes.list()).toEqual([])
+    expect(changes).toEqual(['remote:goals/create', 'remote:goals/create'])
+  })
+
+  it('accepts only a direct scope selecting its unique lookup parameter', async () => {
+    const ctx = await makeCtx()
+    const descriptor = scopedInvocation()
+    const dispose = ctx.typert.remotes.register({ package: '@fixture/scoped', descriptors: [descriptor] })
+    expect(ctx.typert.remotes.get('goals/create')).toBe(descriptor)
+    await dispose()
+
+    const cases: readonly [InvocationDescriptor, string][] = [
+      [{
+        ...descriptor,
+        invocation: {
+          kind: 'context',
+          context: 'fixture',
+          wire: 'scopeId',
+          codec: { mode: 'src-json' },
+        },
+      }, 'Context receiver cannot declare a direct scope projection'],
+      [{ ...descriptor, scope: { context: 'fixture', wire: 'missingId' } }, 'must select its only lookup parameter'],
+      [{
+        ...descriptor,
+        parameters: [...descriptor.parameters, {
+          name: 'other',
+          wire: 'otherId',
+          source: 'lookup',
+          lookup: 'fixture',
+          codec: { mode: 'src-json' },
+        }],
+      }, 'must select its only lookup parameter'],
+      [{ ...descriptor, scope: { context: 'other', wire: 'agentId' } }, 'must select its only lookup parameter'],
+    ]
+    for (const [index, [candidate, message]] of cases.entries()) {
+      expect(() => ctx.typert.remotes.register({
+        package: `@fixture/rejected-${String(index)}`,
+        descriptors: [candidate],
+      })).toThrow(message)
+    }
+    expect(ctx.typert.remotes.list()).toEqual([])
+  })
+
+  it('registers lookup and Context providers without domain branches', async () => {
+    const ctx = await makeCtx()
+    const object = { id: 'agent-1' }
+    const scoped = ctx.extend()
+    const disposeLookup = ctx.typert.lookups.register('fixture', {
+      parameter: 'agent',
+      wire: 'agentId',
+      hostTypeSymbol: '@fixture/agent#Agent',
+      wireTypeSymbol: '@fixture/session#SessionId',
+      resolve: id => id === object.id ? object : undefined,
+    })
+    const disposeHost = ctx.typert.contexts.registerHost('registryFixture', {
+      wire: 'agentId',
+      wireTypeSymbol: '@fixture/session#SessionId',
+      resolve: id => id === object.id ? scoped : undefined,
+    })
+    const disposeClient = ctx.typert.contexts.registerClient('registryFixture', {
+      identity: candidate => candidate === scoped ? object.id : undefined,
+    })
+
+    expect(ctx.typert.lookups.get('fixture')?.resolve('agent-1')).toBe(object)
+    expect(ctx.typert.contexts.getHost('registryFixture')?.resolve('agent-1')).toBe(scoped)
+    expect(ctx.typert.contexts.getClient('registryFixture')?.identity(scoped)).toBe('agent-1')
+
+    await Promise.all([disposeClient(), disposeHost(), disposeLookup()])
+    expect(ctx.typert.lookups.keys()).toEqual([])
+    expect(ctx.typert.contexts.getHost('registryFixture')).toBeUndefined()
+    expect(ctx.typert.contexts.getClient('registryFixture')).toBeUndefined()
+  })
+
+  it('contains change-listener failures and still notifies later listeners', async () => {
+    const ctx = await makeCtx()
+    const warnings: unknown[] = []
+    ctx.logger.warn = ((message: unknown) => { warnings.push(message) }) as typeof ctx.logger.warn
+    let observed = 0
+    ctx.typert.remotes.subscribe(() => { throw new Error('observer failed') })
+    ctx.typert.remotes.subscribe(() => { observed += 1 })
+
+    ctx.typert.remotes.register({ package: '@fixture/remote', descriptors: [invocation()] })
+
+    expect(observed).toBe(1)
+    expect(warnings.map(String)).toContain('Error: observer failed')
+  })
 })
diff --git a/packages/typert/registry/tsconfig.json b/packages/typert/registry/tsconfig.json
index 9966c8ca8a..311dfa4b6d 100644
--- a/packages/typert/registry/tsconfig.json
+++ b/packages/typert/registry/tsconfig.json
@@ -16,6 +16,9 @@
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../type-meta"
     }
   ]
 }
diff --git a/packages/typert/registry/tsdown.config.ts b/packages/typert/registry/tsdown.config.ts
index 144513225b..e494104c4d 100644
--- a/packages/typert/registry/tsdown.config.ts
+++ b/packages/typert/registry/tsdown.config.ts
@@ -1,25 +1,3 @@
-import { defineConfig } from 'tsdown'
+import { clientBundle } from '../../client/tsdown.client.ts'
 
-/** Build the registry and its invariant companion as independent bundles. */
-export default defineConfig([
-  {
-    entry: ['lib/types/index.js'],
-    outDir: 'lib',
-    format: ['esm'],
-    platform: 'node',
-    target: 'es2024',
-    fixedExtension: false,
-    dts: false,
-    clean: false,
-  },
-  {
-    entry: ['lib/types/invariant.js'],
-    outDir: 'lib',
-    format: ['esm'],
-    platform: 'node',
-    target: 'es2024',
-    fixedExtension: false,
-    dts: false,
-    clean: false,
-  },
-])
+export default clientBundle('@deepseek-ai/dsh-typert-registry', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
new file mode 100644
index 0000000000..90d93152b7
--- /dev/null
+++ b/packages/typert/type-meta/README.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 packages/typert/type-meta/README.md
+README.md: 9dd8dadd07b219c7471c8851262958d4d9e96a43
+README.zh.md: 5716f56d988c6d2dd9cd237346c3b02ec9ae7c4e
diff --git a/packages/typert/type-meta/README.md b/packages/typert/type-meta/README.md
new file mode 100644
index 0000000000..9dd8dadd07
--- /dev/null
+++ b/packages/typert/type-meta/README.md
@@ -0,0 +1,33 @@
+# @deepseek-ai/dsh-type-meta
+
+English | [中文](README.zh.md)
+
+Compiler-independent declarations shared by business packages, generated TypeRT artifacts, the Host Gateway, and Client API. This package owns Remote decorators, the explicit Service binding, merge-extensible protocol maps, invocation descriptors, codecs, and provider contracts; it does not run TypeScript analysis or provide a Cordis service.
+
+## Remote declarations
+
+- `@Remote` marks a public instance method for direct invocation on its registered Cordis Service.
+- `@RemoteContext(key)` marks a method whose receiver is selected from a merge-declared scoped Context kind.
+- `bindTypeRTGateway(this, serviceKey, options?)` creates the visible, frozen binding between a Service instance, its exact Cordis key, and its wire namespace.
+- `remoteMethods(service)` returns a detached declaration-order snapshot used by the Gateway's SRC fallback.
+
+Decorator initializers retain markers in a module-private `WeakMap` keyed by the Service prototype. They do not add constructor symbols, prototype properties, parameter metadata, or runtime reflection fields. The Service opts in explicitly through its `typertGateway` binding field.
+
+## TypeRT protocol
+
+Business packages extend `TypeRTLookupMap` and `TypeRTContextMap` to associate Host objects or scoped Contexts with their wire identities. Generated artifacts extend `TypeRTRemoteMap`, `TypeRTRemoteContextMap`, and `TypeRTRemoteNamespaceMap` so Client imports expose only selected Remote methods. `InvocationDescriptor` is the shared runtime form consumed by the registry, Gateway, and Client API.
+
+Lookup and Context packages own both sides of their contract: declaration merging supplies the static association, while runtime providers register identity resolution with `ctx.typert`. Strict codecs carry generated schemas; `src-json` codecs identify the weaker source-launch path.
+
+## Model Experience
+
+None, as this protocol package declares application reflection and registers no model surface.
+
+#### KV Cache effect
+
+No direct effect.
+
+## Known Limitations and Deferred Work
+
+- Decorator markers contain only the method name and direct or Context invocation mode. Parameter, result, lookup, and schema reflection require the TypeRT build pipeline.
+- Remote decorators accept only public, non-static instance methods with string names. SRC execution cannot represent overloaded, destructured, defaulted, or rest-parameter signatures.
diff --git a/packages/typert/type-meta/README.zh.md b/packages/typert/type-meta/README.zh.md
new file mode 100644
index 0000000000..5716f56d98
--- /dev/null
+++ b/packages/typert/type-meta/README.zh.md
@@ -0,0 +1,33 @@
+# @deepseek-ai/dsh-type-meta
+
+[English](README.md) | 中文
+
+该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、Host Gateway 和 Client API 共享。它负责 Remote 装饰器、显式服务绑定、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方契约；它不执行 TypeScript 分析，也不提供 Cordis 服务。
+
+## Remote 声明
+
+- `@Remote` 将公开实例方法标记为可在其注册的 Cordis 服务上直接调用。
+- `@RemoteContext(key)` 标记接收者选自合并声明的作用域 Context 类型的方法。
+- `bindTypeRTGateway(this, serviceKey, options?)` 在服务实例、其准确的 Cordis key 与协议命名空间之间创建可见且冻结的绑定。
+- `remoteMethods(service)` 返回按声明顺序排列、与内部状态分离的快照，供 Gateway 的 SRC 回退路径使用。
+
+装饰器初始化器将标记保存在以服务 prototype 为键的模块私有 `WeakMap` 中。它们不会在构造函数上添加 symbol，也不会添加 prototype 属性、参数元数据或运行时反射字段。服务通过自身的 `typertGateway` 绑定字段显式接入。
+
+## TypeRT 协议
+
+业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联 Host 对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteContextMap` 和 `TypeRTRemoteNamespaceMap`，使 Client 导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、Gateway 和 Client API 使用的共享运行时形式。
+
+查找包与 Context 包同时负责其契约的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
+
+## 模型体验
+
+无，因为该协议包声明应用反射，不注册任何模型接口。
+
+#### KV Cache 影响
+
+无直接影响。
+
+## 已知限制与延期工作
+
+- 装饰器标记仅包含方法名，以及直接调用或 Context 调用模式。参数、结果、查找和 schema 反射需要 TypeRT 构建流水线。
+- Remote 装饰器只接受具有字符串名称的公开、非静态实例方法。SRC 执行无法表示重载签名，以及包含解构参数、默认参数或剩余参数的方法签名。
diff --git a/packages/typert/type-meta/package.json b/packages/typert/type-meta/package.json
new file mode 100644
index 0000000000..2ffcd6c5ed
--- /dev/null
+++ b/packages/typert/type-meta/package.json
@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-type-meta",
+  "description": "Compiler-independent Remote metadata and TypeRT provider protocols",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/typert/type-meta/src/index.ts b/packages/typert/type-meta/src/index.ts
new file mode 100644
index 0000000000..1e79bb2e55
--- /dev/null
+++ b/packages/typert/type-meta/src/index.ts
@@ -0,0 +1,223 @@
+/**
+ * Remote decorators and explicit Gateway bindings backed only by private
+ * module state. Strict reflection remains a TypeRT compiler responsibility.
+ * @module @deepseek-ai/dsh-type-meta
+ */
+
+import type { TypeRTContextMap } from './types.ts'
+
+export type {
+  InvocationDescriptor,
+  InvocationParameterDescriptor,
+  InvocationSourceLocation,
+  TypeRTClientContextBinder,
+  TypeRTCodec,
+  TypeRTContext,
+  TypeRTContextMap,
+  TypeRTContextRegistry,
+  TypeRTContextWire,
+  TypeRTDisposer,
+  TypeRTHostContextProvider,
+  TypeRTLocalRegistry,
+  TypeRTLookup,
+  TypeRTLookupHost,
+  TypeRTLookupMap,
+  TypeRTLookupProvider,
+  TypeRTLookupRegistry,
+  TypeRTLookupWire,
+  TypeRTRemoteContextApi,
+  TypeRTRemoteContextMap,
+  TypeRTRemoteContextNamespace,
+  TypeRTRemoteContribution,
+  TypeRTRemoteMap,
+  TypeRTRemoteNamespace,
+  TypeRTRemoteNamespaceMap,
+  TypeRTRemoteRegistry,
+  TypeRTRegistryChange,
+  TypeRTRegistryListener,
+  TypeRTSchema,
+  TypeRTService,
+} from './types.ts'
+
+/** Options for an explicit Service-to-Gateway binding. */
+export interface TypeRTGatewayBindingOptions {
+  /** Wire namespace; defaults to the Cordis service key. */
+  readonly namespace?: string
+}
+
+/** Visible declaration that one Service participates in TypeRT Gateway export. */
+export interface TypeRTGatewayBinding<Service extends object = object> {
+  readonly service: Service
+  readonly serviceKey: string
+  readonly namespace: string
+}
+
+/** Invocation mode recorded by a Remote method decorator. */
+export type RemoteInvocationMarker =
+  | { readonly kind: 'direct' }
+  | { readonly kind: 'context'; readonly context: string }
+
+/** One decorator marker discovered for a live Service instance. */
+export interface RemoteMethodMarker {
+  /** Public instance method carrying the implementation. */
+  readonly method: string
+  /** Endpoint method when it differs from the implementation member. */
+  readonly exportName?: string
+  readonly invocation: RemoteInvocationMarker
+}
+
+type RemoteMethodDecorator = <This extends object, Args extends unknown[], Result>(
+  method: (this: This, ...args: Args) => Result,
+  context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
+) => void
+
+interface RemoteInitializerContext<This extends object> {
+  readonly private: boolean
+  readonly static: boolean
+  readonly name: string | symbol
+  addInitializer(initializer: (this: This) => void): void
+}
+
+interface StoredRemoteMethodMarker {
+  readonly exportName?: string
+  readonly invocation: RemoteInvocationMarker
+}
+
+const markers = new WeakMap<object, Map<string, StoredRemoteMethodMarker>>()
+
+/**
+ * Bind one visible Service field to a Cordis key and Remote namespace.
+ * @param service - owning Service instance, normally `this`.
+ * @param serviceKey - exact Cordis service key.
+ * @param options - optional distinct wire namespace.
+ * @returns a frozen, inspectable binding with no compiler-injected metadata.
+ */
+export function bindTypeRTGateway<Service extends object>(
+  service: Service,
+  serviceKey: string,
+  options: TypeRTGatewayBindingOptions = {},
+): TypeRTGatewayBinding<Service> {
+  validateName('service key', serviceKey)
+  const namespace = options.namespace ?? serviceKey
+  validateName('namespace', namespace)
+  return Object.freeze({ service, serviceKey, namespace })
+}
+
+/**
+ * Mark one public instance method as a direct Remote invocation.
+ * @param _method - decorated method; retained only by the class itself.
+ * @param context - standard decorator context used to schedule private marking.
+ */
+export function Remote<This extends object, Args extends unknown[], Result>(
+  _method: (this: This, ...args: Args) => Result,
+  context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
+): void
+/**
+ * Mark one public instance method under a distinct exported method name.
+ * @param exportName - Remote endpoint method, without a namespace or slash.
+ * @returns a standard method decorator.
+ */
+export function Remote(exportName: string): RemoteMethodDecorator
+export function Remote<This extends object, Args extends unknown[], Result>(
+  methodOrExportName: string | ((this: This, ...args: Args) => Result),
+  context?: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
+): void | RemoteMethodDecorator {
+  if (typeof methodOrExportName === 'string') {
+    validateName('Remote export name', methodOrExportName)
+    return function <DecoratorThis extends object, DecoratorArgs extends unknown[], DecoratorResult>(
+      _method: (this: DecoratorThis, ...args: DecoratorArgs) => DecoratorResult,
+      decoratorContext: ClassMethodDecoratorContext<
+        DecoratorThis,
+        (this: DecoratorThis, ...args: DecoratorArgs) => DecoratorResult
+      >,
+    ): void {
+      addMarkerInitializer(decoratorContext, { kind: 'direct' }, methodOrExportName)
+    }
+  }
+  if (context === undefined) throw new TypeError('type-meta: Remote decorator context is missing')
+  addMarkerInitializer(context, { kind: 'direct' })
+}
+
+/**
+ * Create a decorator for a method resolved from one scoped Remote Context.
+ * @param key - merge-declared Context key.
+ * @param exportName - optional Remote export name; defaults to the method name.
+ * @returns a standard method decorator that records only private module state.
+ */
+export function RemoteContext(
+  key: Extract<keyof TypeRTContextMap, string>,
+  exportName?: string,
+): RemoteMethodDecorator {
+  validateName('Context key', key)
+  if (exportName !== undefined) validateName('Remote export name', exportName)
+  return function <This extends object, Args extends unknown[], Result>(
+    _method: (this: This, ...args: Args) => Result,
+    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
+  ): void {
+    addMarkerInitializer(context, { kind: 'context', context: key }, exportName)
+  }
+}
+
+/**
+ * Read Remote markers attached to a live Service by decorator initializers.
+ * The returned snapshot cannot mutate the private marker table.
+ * @param service - live Service instance.
+ * @returns markers in class declaration order.
+ */
+export function remoteMethods(service: object): readonly RemoteMethodMarker[] {
+  const prototype = Object.getPrototypeOf(service) as object | null
+  if (prototype === null) return []
+  return [...(markers.get(prototype) ?? [])].map(([method, marker]) => ({ method, ...marker }))
+}
+
+function addMarkerInitializer<This extends object>(
+  context: RemoteInitializerContext<This>,
+  invocation: RemoteInvocationMarker,
+  exportName?: string,
+): void {
+  if (context.private || context.static || typeof context.name !== 'string') {
+    throw new TypeError('type-meta: Remote decorators require a public instance method with a string name')
+  }
+  const method = context.name
+  context.addInitializer(function (this: This) {
+    const prototype = Object.getPrototypeOf(this) as object | null
+    if (prototype === null) {
+      throw new TypeError(`type-meta: cannot mark Remote method "${method}" on an object without a prototype`)
+    }
+    mark(prototype, method, invocation, exportName)
+  })
+}
+
+function mark(
+  prototype: object,
+  method: string,
+  invocation: RemoteInvocationMarker,
+  exportName?: string,
+): void {
+  let table = markers.get(prototype)
+  if (table === undefined) {
+    table = new Map()
+    markers.set(prototype, table)
+  }
+  const marker: StoredRemoteMethodMarker = {
+    ...(exportName === undefined || exportName === method ? {} : { exportName }),
+    invocation: Object.freeze(invocation),
+  }
+  const current = table.get(method)
+  if (current !== undefined) {
+    if (current.exportName === marker.exportName && sameInvocation(current.invocation, invocation)) return
+    throw new Error(`type-meta: Remote method "${method}" has conflicting invocation markers`)
+  }
+  table.set(method, Object.freeze(marker))
+}
+
+function sameInvocation(left: RemoteInvocationMarker, right: RemoteInvocationMarker): boolean {
+  return left.kind === right.kind
+    && (left.kind === 'direct' || (right.kind === 'context' && left.context === right.context))
+}
+
+function validateName(subject: string, value: string): void {
+  if (value.length === 0 || value.includes('/')) {
+    throw new TypeError(`type-meta: ${subject} must be nonempty and must not contain "/"`)
+  }
+}
diff --git a/packages/typert/type-meta/src/invariant.ts b/packages/typert/type-meta/src/invariant.ts
new file mode 100644
index 0000000000..22dc290a1e
--- /dev/null
+++ b/packages/typert/type-meta/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-type-meta`.
+ * @module @deepseek-ai/dsh-type-meta/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-type-meta'
+
+/** Cordis companion plugin name. */
+export const name = 'type-meta-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: decorators retain private immutable declarations and
+ * bindings are frozen values with no independent event stream to cross-check.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/typert/type-meta/src/types.ts b/packages/typert/type-meta/src/types.ts
new file mode 100644
index 0000000000..87ab091075
--- /dev/null
+++ b/packages/typert/type-meta/src/types.ts
@@ -0,0 +1,358 @@
+/**
+ * Compiler-independent TypeRT protocol shared by business packages, generated
+ * Remote artifacts, the Host Gateway, and Client API implementations.
+ * @module @deepseek-ai/dsh-type-meta/types
+ */
+
+import type { Context } from 'cordis'
+
+declare const LOOKUP_HOST: unique symbol
+declare const LOOKUP_WIRE: unique symbol
+declare const CONTEXT_WIRE: unique symbol
+
+/** Type-level association between a Host object and its wire identity. */
+export interface TypeRTLookup<Host, Wire> {
+  readonly [LOOKUP_HOST]: Host
+  readonly [LOOKUP_WIRE]: Wire
+}
+
+/** Extract the Host object associated with one lookup declaration. */
+export type TypeRTLookupHost<Lookup> = Lookup extends TypeRTLookup<infer Host, infer _Wire> ? Host : never
+
+/** Extract the wire identity associated with one lookup declaration. */
+export type TypeRTLookupWire<Lookup> = Lookup extends TypeRTLookup<infer _Host, infer Wire> ? Wire : never
+
+/** Type-level association between a scoped Context kind and its wire identity. */
+export interface TypeRTContext<Wire> {
+  readonly [CONTEXT_WIRE]: Wire
+}
+
+/** Extract the wire identity associated with one scoped Context declaration. */
+export type TypeRTContextWire<ContextType> = ContextType extends TypeRTContext<infer Wire> ? Wire : never
+
+/** Merge-extensible Host object lookup declarations. */
+export interface TypeRTLookupMap {}
+
+/** Merge-extensible scoped Context declarations. */
+export interface TypeRTContextMap {}
+
+/** Merge-extensible direct Remote method signatures generated for consumers. */
+export interface TypeRTRemoteMap {}
+
+/** Merge-extensible scoped Remote method signatures generated for consumers. */
+export interface TypeRTRemoteContextMap {}
+
+/**
+ * Resolve one direct Remote namespace from the generated flat endpoint map.
+ * @template Namespace - wire namespace before the endpoint slash.
+ */
+export type TypeRTRemoteNamespace<Namespace extends string> = {
+  [Endpoint in keyof TypeRTRemoteMap as Endpoint extends `${Namespace}/${infer Method}`
+    ? Method
+    : never]: TypeRTRemoteMap[Endpoint]
+}
+
+/**
+ * Resolve one scoped Remote namespace across every generated Context kind.
+ * The calling Cordis Context supplies the concrete identity at runtime.
+ * @template Namespace - wire namespace between the Context prefix and method.
+ */
+export type TypeRTRemoteContextNamespace<
+  Namespace extends string,
+  ContextKey extends string = string,
+> = {
+  [Endpoint in keyof TypeRTRemoteContextMap as Endpoint extends `${ContextKey}:${Namespace}/${infer Method}`
+    ? Method
+    : never]: TypeRTRemoteContextMap[Endpoint]
+}
+
+type TypeRTRemoteContextNamespaceKey<
+  ContextKey extends string,
+  Endpoint = keyof TypeRTRemoteContextMap,
+> = Endpoint extends `${ContextKey}:${infer Namespace}/${string}` ? Namespace : never
+
+/** Generated scoped Remote namespaces available to one Context kind. */
+export type TypeRTRemoteContextApi<ContextKey extends string> = {
+  [Namespace in TypeRTRemoteContextNamespaceKey<ContextKey>]:
+  TypeRTRemoteContextNamespace<Namespace, ContextKey>
+}
+
+/** Merge-extensible direct namespace surface generated for Client API services. */
+export interface TypeRTRemoteNamespaceMap {}
+
+/** Awaitable disposer returned by Cordis-owned TypeRT registrations. */
+export type TypeRTDisposer = () => Promise<void>
+
+type StringKeyOf<Value> = Extract<keyof Value, string>
+
+/** Minimal runtime-schema capability carried by strict generated codecs. */
+export interface TypeRTSchema<Output = unknown> {
+  /**
+   * Parse and validate one boundary value.
+   * @param value - untrusted boundary value.
+   * @returns the validated value.
+   */
+  parse(value: unknown): Output
+}
+
+/** Codec attached to one invocation parameter or result. */
+export type TypeRTCodec =
+  | {
+    readonly mode: 'strict'
+    readonly typeSymbol: string
+    readonly schema: TypeRTSchema
+  }
+  | {
+    readonly mode: 'src-json'
+  }
+
+/** One ordered business parameter in a Remote invocation. */
+export interface InvocationParameterDescriptor {
+  /** Source-level parameter name. */
+  readonly name: string
+  /** Required key in the wire `args` object. */
+  readonly wire: string
+  /** Whether the value is JSON or requires a registered Host lookup. */
+  readonly source: 'json' | 'lookup'
+  /** Lookup key when `source` is `lookup`. */
+  readonly lookup?: string
+  /** Boundary codec for the wire representation. */
+  readonly codec: TypeRTCodec
+}
+
+/** Source position retained for diagnostics from generated definitions. */
+export interface InvocationSourceLocation {
+  readonly file: string
+  readonly line: number
+  readonly column: number
+}
+
+/** Carrier-independent description of one exported method invocation. */
+export interface InvocationDescriptor {
+  /** Globally stable generated identity. */
+  readonly id: string
+  /** Cordis service key owning the method. */
+  readonly service: string
+  /** Wire namespace, defaulting to the service key. */
+  readonly namespace: string
+  /** Public instance method name. */
+  readonly method: string
+  /** Service member invoked when the exported method name is an alias. */
+  readonly implementation?: string
+  /** Receiver selection mode. */
+  readonly invocation:
+    | { readonly kind: 'direct' }
+    | {
+      readonly kind: 'context'
+      readonly context: string
+      readonly wire: string
+      readonly codec: TypeRTCodec
+    }
+  /** Optional consuming-Context projection for one direct lookup parameter. */
+  readonly scope?: {
+    /** Context kind whose Client binder supplies the identity. */
+    readonly context: string
+    /** Lookup parameter wire field replaced by the Context identity. */
+    readonly wire: string
+  }
+  /** Ordered business parameters. */
+  readonly parameters: readonly InvocationParameterDescriptor[]
+  /** Codec for the resolved method result. */
+  readonly result: TypeRTCodec
+  /** Source declaration used only for diagnostics. */
+  readonly sourceLocation?: InvocationSourceLocation
+}
+
+/** Generated Host contract selected explicitly by a Client assembly. */
+export interface TypeRTRemoteContribution {
+  /** npm package that owns the Remote methods. */
+  readonly package: string
+  /** Consumer-side invocation descriptors generated from that package. */
+  readonly descriptors: readonly InvocationDescriptor[]
+}
+
+/** Runtime resolver for one declared Host object lookup. */
+export interface TypeRTLookupProvider<Host = unknown, Wire = unknown> {
+  /** Source parameter name recognized by the SRC weak parser. */
+  readonly parameter: string
+  /** Wire field replacing the Host object parameter. */
+  readonly wire: string
+  /** Canonical Host type symbol used by strict generation. */
+  readonly hostTypeSymbol: string
+  /** Canonical wire type symbol used by strict generation. */
+  readonly wireTypeSymbol: string
+  /**
+   * Resolve a wire identity to the current live Host object.
+   * @param id - validated wire identity.
+   * @returns the live object, or `undefined` when it is unavailable.
+   */
+  resolve(id: Wire): Host | undefined
+}
+
+/** Host resolver for one scoped Remote Context kind. */
+export interface TypeRTHostContextProvider<Wire = unknown> {
+  /** Wire field carrying the Context identity. */
+  readonly wire: string
+  /** Canonical wire type symbol used by strict generation. */
+  readonly wireTypeSymbol: string
+  /**
+   * Resolve a wire identity to its live scoped Context.
+   * @param id - validated wire identity.
+   * @returns the scoped Context, or `undefined` when unavailable.
+   */
+  resolve(id: Wire): Context | undefined
+}
+
+/** Client resolver for the identity carried by the calling scoped Context. */
+export interface TypeRTClientContextBinder<Wire = unknown> {
+  /**
+   * Read the Remote identity represented by a calling Context.
+   * @param ctx - Context rebound by the Cordis service tracker.
+   * @returns the wire identity, or `undefined` when the Context has the wrong scope.
+   */
+  identity(ctx: Context): Wire | undefined
+}
+
+/** Notification emitted after a TypeRT runtime registry changes. */
+export interface TypeRTRegistryChange {
+  readonly kind: 'local' | 'remote' | 'lookup' | 'host-context' | 'client-context'
+  readonly key: string
+}
+
+/** Listener for one TypeRT runtime registry. */
+export type TypeRTRegistryListener = (change: TypeRTRegistryChange) => void
+
+/** Current-environment invocation definitions. */
+export interface TypeRTLocalRegistry {
+  /**
+   * Look up one invocation by `<namespace>/<method>`.
+   * @param endpoint - canonical endpoint.
+   * @returns the live descriptor, or `undefined` when absent.
+   */
+  get(endpoint: string): InvocationDescriptor | undefined
+  /**
+   * Report whether a strict definition has existed during this TypeRT Service lifetime.
+   * @param endpoint - canonical endpoint.
+   * @returns `true` after the endpoint has been registered at least once, even if withdrawn.
+   */
+  hasSeen(endpoint: string): boolean
+  /** @returns a registration-order snapshot of local descriptors. */
+  list(): readonly InvocationDescriptor[]
+  /**
+   * Observe later local-definition changes.
+   * @param listener - synchronous contained observer.
+   * @returns disposer for this subscription.
+   */
+  subscribe(listener: TypeRTRegistryListener): TypeRTDisposer
+}
+
+/** Consumer-selected Remote contribution registry. */
+export interface TypeRTRemoteRegistry {
+  /**
+   * Register one generated contribution for the calling Cordis fiber.
+   * @param contribution - generated Remote descriptors.
+   * @returns disposer withdrawing the exact contribution.
+   */
+  register(contribution: TypeRTRemoteContribution): TypeRTDisposer
+  /**
+   * Look up one Remote descriptor by endpoint.
+   * @param endpoint - canonical endpoint.
+   * @returns the descriptor, or `undefined` when unmounted.
+   */
+  get(endpoint: string): InvocationDescriptor | undefined
+  /** @returns a registration-order snapshot of Remote descriptors. */
+  list(): readonly InvocationDescriptor[]
+  /**
+   * Observe later Remote contribution changes.
+   * @param listener - synchronous contained observer.
+   * @returns disposer for this subscription.
+   */
+  subscribe(listener: TypeRTRegistryListener): TypeRTDisposer
+}
+
+/** Runtime registry for Host object lookup providers. */
+export interface TypeRTLookupRegistry {
+  /**
+   * Register one provider under its merge-declared key.
+   * @param key - lookup key.
+   * @param provider - owning package's live resolver.
+   * @returns disposer withdrawing the exact provider.
+   */
+  register<K extends StringKeyOf<TypeRTLookupMap>>(
+    key: K,
+    provider: TypeRTLookupProvider<
+      TypeRTLookupHost<TypeRTLookupMap[K]>,
+      TypeRTLookupWire<TypeRTLookupMap[K]>
+    >,
+  ): TypeRTDisposer
+  /**
+   * Look up one provider by runtime key.
+   * @param key - descriptor lookup key.
+   * @returns the live provider, or `undefined` when absent.
+   */
+  get(key: string): TypeRTLookupProvider | undefined
+  /** @returns a snapshot of registered provider keys. */
+  keys(): readonly string[]
+  /**
+   * Observe later lookup changes.
+   * @param listener - synchronous contained observer.
+   * @returns disposer for this subscription.
+   */
+  subscribe(listener: TypeRTRegistryListener): TypeRTDisposer
+}
+
+/** Runtime registry for Host Context resolvers and Client Context binders. */
+export interface TypeRTContextRegistry {
+  /**
+   * Register a Host Context resolver.
+   * @param key - merge-declared Context key.
+   * @param provider - owning package's Host resolver.
+   * @returns disposer withdrawing the exact provider.
+   */
+  registerHost<K extends StringKeyOf<TypeRTContextMap>>(
+    key: K,
+    provider: TypeRTHostContextProvider<TypeRTContextWire<TypeRTContextMap[K]>>,
+  ): TypeRTDisposer
+  /**
+   * Register a Client Context identity binder.
+   * @param key - merge-declared Context key.
+   * @param binder - Client scope identity resolver.
+   * @returns disposer withdrawing the exact binder.
+   */
+  registerClient<K extends StringKeyOf<TypeRTContextMap>>(
+    key: K,
+    binder: TypeRTClientContextBinder<TypeRTContextWire<TypeRTContextMap[K]>>,
+  ): TypeRTDisposer
+  /**
+   * Look up a Host Context resolver.
+   * @param key - descriptor Context key.
+   * @returns the provider, or `undefined` when absent.
+   */
+  getHost(key: string): TypeRTHostContextProvider | undefined
+  /**
+   * Look up a Client Context binder.
+   * @param key - descriptor Context key.
+   * @returns the binder, or `undefined` when absent.
+   */
+  getClient(key: string): TypeRTClientContextBinder | undefined
+  /**
+   * Observe later Context provider changes.
+   * @param listener - synchronous contained observer.
+   * @returns disposer for this subscription.
+   */
+  subscribe(listener: TypeRTRegistryListener): TypeRTDisposer
+}
+
+/** Minimal TypeRT runtime consumed through dependency inversion. */
+export interface TypeRTService {
+  readonly local: TypeRTLocalRegistry
+  readonly remotes: TypeRTRemoteRegistry
+  readonly lookups: TypeRTLookupRegistry
+  readonly contexts: TypeRTContextRegistry
+}
+
+declare module 'cordis' {
+  interface Context {
+    typert: TypeRTService
+  }
+}
diff --git a/packages/typert/type-meta/tests/fixtures/source-launch.ts b/packages/typert/type-meta/tests/fixtures/source-launch.ts
new file mode 100644
index 0000000000..68f886dff1
--- /dev/null
+++ b/packages/typert/type-meta/tests/fixtures/source-launch.ts
@@ -0,0 +1,29 @@
+import {
+  bindTypeRTGateway,
+  Remote,
+  RemoteContext,
+  remoteMethods,
+} from '@deepseek-ai/dsh-type-meta'
+
+class Goals {
+  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+
+  @Remote
+  create(value: string): string {
+    return value
+  }
+
+  @RemoteContext('agent')
+  scoped(value: string): string {
+    return value
+  }
+}
+
+const methods = remoteMethods(new Goals())
+const actual = JSON.stringify(methods)
+const expected = JSON.stringify([
+  { method: 'create', invocation: { kind: 'direct' } },
+  { method: 'scoped', invocation: { kind: 'context', context: 'agent' } },
+])
+if (actual !== expected) throw new Error(`unexpected Remote declarations: ${actual}`)
+process.stdout.write(actual)
diff --git a/packages/typert/type-meta/tests/type-meta.spec.ts b/packages/typert/type-meta/tests/type-meta.spec.ts
new file mode 100644
index 0000000000..1eab5a6ca3
--- /dev/null
+++ b/packages/typert/type-meta/tests/type-meta.spec.ts
@@ -0,0 +1,132 @@
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import {
+  bindTypeRTGateway,
+  Remote,
+  RemoteContext,
+  remoteMethods,
+  type TypeRTContext,
+} from '@deepseek-ai/dsh-type-meta'
+
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTContextMap {
+    metaFixture: TypeRTContext<string>
+  }
+}
+
+describe('type-meta Remote declarations', () => {
+  it('executes standard decorator syntax through the Vitest source transform', () => {
+    class Goals {
+      readonly typertGateway = bindTypeRTGateway(this, 'goals')
+
+      @Remote
+      create(value: string): string {
+        return value
+      }
+
+      @RemoteContext('metaFixture')
+      scoped(value: string): string {
+        return value
+      }
+    }
+
+    const goals = new Goals()
+    expect(remoteMethods(goals)).toEqual([
+      { method: 'create', invocation: { kind: 'direct' } },
+      { method: 'scoped', invocation: { kind: 'context', context: 'metaFixture' } },
+    ])
+  })
+
+  it('executes standard decorator syntax through the TSX source launcher', () => {
+    const fixture = fileURLToPath(new URL('./fixtures/source-launch.ts', import.meta.url))
+    const output = execFileSync(process.execPath, ['--import', 'tsx/esm', fixture], { encoding: 'utf8' })
+    expect(JSON.parse(output)).toEqual([
+      { method: 'create', invocation: { kind: 'direct' } },
+      { method: 'scoped', invocation: { kind: 'context', context: 'agent' } },
+    ])
+  })
+
+  it('keeps decorator markers in private module state', () => {
+    class Goals {
+      readonly typertGateway = bindTypeRTGateway(this, 'goals')
+
+      create(agent: object, request: object): object {
+        return { agent, request }
+      }
+
+      scoped(request: object): object {
+        return request
+      }
+    }
+
+    const initializers: Array<(this: Goals) => void> = []
+    Remote(
+      Reflect.get(Goals.prototype, 'create') as (this: Goals, ...args: unknown[]) => unknown,
+      methodContext('create', initializers),
+    )
+    RemoteContext('metaFixture')(
+      Reflect.get(Goals.prototype, 'scoped') as (this: Goals, ...args: unknown[]) => unknown,
+      methodContext('scoped', initializers),
+    )
+
+    const goals = new Goals()
+    for (const initialize of initializers) initialize.call(goals)
+    expect(goals.typertGateway).toEqual({ service: goals, serviceKey: 'goals', namespace: 'goals' })
+    expect(Object.isFrozen(goals.typertGateway)).toBe(true)
+    expect(remoteMethods(goals)).toEqual([
+      { method: 'create', invocation: { kind: 'direct' } },
+      { method: 'scoped', invocation: { kind: 'context', context: 'metaFixture' } },
+    ])
+    expect(Reflect.ownKeys(Goals)).toEqual(['length', 'name', 'prototype'])
+    expect(Reflect.ownKeys(Goals.prototype)).toEqual(['constructor', 'create', 'scoped'])
+  })
+
+  it('keeps markers idempotent across instances and returns detached snapshots', () => {
+    class Service {
+      run(value: string): string {
+        return value
+      }
+    }
+
+    const initializers: Array<(this: Service) => void> = []
+    Remote(
+      Reflect.get(Service.prototype, 'run') as (this: Service, ...args: unknown[]) => unknown,
+      methodContext('run', initializers),
+    )
+
+    const first = new Service()
+    const second = new Service()
+    for (const initialize of initializers) {
+      initialize.call(first)
+      initialize.call(second)
+    }
+    const snapshot = remoteMethods(first)
+    expect(remoteMethods(second)).toEqual(snapshot)
+    ;(snapshot as unknown as { method: string }[])[0]!.method = 'changed'
+    expect(remoteMethods(first)).toEqual([{ method: 'run', invocation: { kind: 'direct' } }])
+  })
+
+  it('rejects ambiguous binding names', () => {
+    expect(() => bindTypeRTGateway({}, '')).toThrow('service key')
+    expect(() => bindTypeRTGateway({}, 'goals', { namespace: 'api/goals' })).toThrow('namespace')
+  })
+})
+
+function methodContext<This extends object>(
+  name: string,
+  initializers: Array<(this: This) => void>,
+): ClassMethodDecoratorContext<This, (this: This, ...args: unknown[]) => unknown> {
+  return {
+    kind: 'method',
+    name,
+    static: false,
+    private: false,
+    metadata: {},
+    access: {
+      has: object => name in object,
+      get: object => (object as Record<string, unknown>)[name] as (this: This, ...args: unknown[]) => unknown,
+    },
+    addInitializer: (initializer) => { initializers.push(initializer) },
+  }
+}
diff --git a/packages/typert/type-meta/tsconfig.json b/packages/typert/type-meta/tsconfig.json
new file mode 100644
index 0000000000..9966c8ca8a
--- /dev/null
+++ b/packages/typert/type-meta/tsconfig.json
@@ -0,0 +1,21 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1ea3070dfa..45e8ad1803 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -916,6 +916,9 @@ importers:
       '@deepseek-ai/dsh-goal-session':
         specifier: workspace:^
         version: link:../../goal/goal-session
+      '@deepseek-ai/dsh-host-api-gateway':
+        specifier: workspace:^
+        version: link:../../host/api-gateway
       '@deepseek-ai/dsh-llm':
         specifier: workspace:^
         version: link:../../llm/llm
@@ -1054,6 +1057,12 @@ importers:
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
+      '@deepseek-ai/dsh-typert-loader':
+        specifier: workspace:^
+        version: link:../../typert/loader
+      '@deepseek-ai/dsh-typert-registry':
+        specifier: workspace:^
+        version: link:../../typert/registry
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
         version: link:../../ui/user-approval
@@ -2790,6 +2799,12 @@ importers:
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../system-prompt
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../../typert/type-meta
+      '@deepseek-ai/dsh-typert-registry':
+        specifier: workspace:^
+        version: link:../../typert/registry
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -2854,6 +2869,12 @@ importers:
       '@deepseek-ai/dsh-scope':
         specifier: workspace:^
         version: link:../scope
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../../typert/type-meta
+      '@deepseek-ai/dsh-typert-registry':
+        specifier: workspace:^
+        version: link:../../typert/registry
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -3706,6 +3727,31 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/host/api-gateway:
+    dependencies:
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../../typert/type-meta
+    devDependencies:
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../../client/connection
+      '@deepseek-ai/dsh-host-webserver':
+        specifier: workspace:^
+        version: link:../webserver
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-typert-registry':
+        specifier: workspace:^
+        version: link:../../typert/registry
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+
   packages/host/apiproxy:
     dependencies:
       '@deepseek-ai/dsh-agent':
@@ -6096,6 +6142,9 @@ importers:
 
   packages/typert/generator:
     dependencies:
+      '@jridgewell/gen-mapping':
+        specifier: ^0.3.13
+        version: 0.3.13
       typescript:
         specifier: ^6.0.3
         version: 6.0.3
@@ -6140,6 +6189,9 @@ importers:
 
   packages/typert/registry:
     dependencies:
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../type-meta
       zod:
         specifier: ^4.4.3
         version: 4.4.3
@@ -6151,6 +6203,15 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/typert/type-meta:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/ui/app-boot:
     dependencies:
       js-yaml:
diff --git a/scripts/client-bundle-purity.spec.ts b/scripts/client-bundle-purity.spec.ts
index 8b10822bca..fb47f8a9c8 100644
--- a/scripts/client-bundle-purity.spec.ts
+++ b/scripts/client-bundle-purity.spec.ts
@@ -59,6 +59,13 @@ describe('client bundle purity gate', () => {
     expect(resolveId('@deepseek-ai/dsh-brand')).toBeNull()
   })
 
+  it('lets exact generated Remote contributions inline without admitting their package implementation', () => {
+    expect(resolveId('@deepseek-ai/dsh-goal/remote')).toBeNull()
+    expect(() => resolveId('@deepseek-ai/dsh-goal')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-goal/client')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-goal/remote/nested')).toThrow(/purity/)
+  })
+
   it('throws on any other @deepseek-ai leak', () => {
     expect(() => resolveId('@deepseek-ai/dsh-agent')).toThrow(/purity/)
     expect(() => resolveId('@deepseek-ai/dsh-client-web')).toThrow(/purity/)
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index bcf90d1e82..84013225f7 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -276,6 +276,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   TypertPackageRecord: 'registry package record is owned by packages/typert/registry/README.md',
   TypertSchemaFilter: 'registry schema query filter is owned by packages/typert/registry/README.md',
   TypertSchemaRecord: 'registry schema record is owned by packages/typert/registry/README.md',
+  TypeRTDisposer: 'TypeRT lifecycle contract is owned by packages/typert/type-meta/README.md',
   'z.core.JSONSchema.BaseSchema': 'zod projection output is owned by the zod v4 API',
   'z.core.ToJSONSchemaParams': 'zod projection parameters are owned by the zod v4 API',
   InvariantInstaller: 'service-local contribution contract is owned by packages/support/invariants/README.md',
@@ -287,6 +288,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   ThemeTokens: 'service-local token dictionary is owned by packages/client/ui-theme/src/index.ts',
   Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
+  InvokeRemoteRequest: 'gateway invocation contract is owned by packages/host/api-gateway/README.md',
   PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
   PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
   KnobState: 'projection unit state shape is owned by packages/ui/permission/README.md',
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 1c7e2c3a0c..151aadb278 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -140,8 +140,15 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'typert-registry',
     title: 'Runtime type registry',
     mode: 'core',
-    consumers: ['typert-loader'],
-    note: 'Plugins register live zod contributions directly or through dsh-typert-loader; runtime consumers query schemas and reflection metadata at their own edges.',
+    consumers: ['typert-loader', 'api-gateway'],
+    note: 'Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges.',
+  },
+  {
+    key: 'typertGateway',
+    pkg: 'api-gateway',
+    title: 'TypeRT Host invocation gateway',
+    mode: 'core',
+    note: 'Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier.',
   },
   {
     key: 'sessionPersistence',
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 53491b89fb..7e81b30e07 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -125,6 +125,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/support/loader-smoke': { kind: 'none', reason: 'The test harness observes child-process streams without changing live requests.' },
   'packages/support/llm-mock-server': { kind: 'none', reason: 'The test server substitutes provider wire behavior without invoking a real model.' },
   'packages/support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
+  'packages/host/api-gateway': { kind: 'none', reason: 'Remote dispatch infrastructure; invoked business methods own any model-visible effect.' },
+  'packages/typert/type-meta': { kind: 'none', reason: 'Compiler-independent Remote protocol declarations; registers no model surface.' },
   'packages/typert/generator': { kind: 'none', reason: 'The build-time generator runs outside any agent runtime and touches no model request.' },
   'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
   'packages/tasks/tasks-local': { kind: 'indirect', reason: 'The registry backend delegates model rendering to producer plugins and dsh-tool-tasks.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 001158afe0..ce4fca35f9 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -40,6 +40,13 @@
       "@cordisjs/plugin-logger-console": ["./vendor/logger-console/src"],
       "@deepseek-ai/dsh-invariants": ["./packages/support/invariants/src/index.ts"],
       "@deepseek-ai/dsh-typert-registry": ["./packages/typert/registry/src/index.ts"],
+      "@deepseek-ai/dsh-typert-registry/client": ["./packages/typert/registry/src/client/index.ts"],
+      "@deepseek-ai/dsh-host-api-gateway": ["./packages/host/api-gateway/src/index.ts"],
+      "@deepseek-ai/dsh-host-api-gateway/client": ["./packages/host/api-gateway/src/client/index.ts"],
+      "@deepseek-ai/dsh-host-api-gateway/invariant": ["./packages/host/api-gateway/src/invariant.ts"],
+      "@deepseek-ai/dsh-host-api-gateway/types": ["./packages/host/api-gateway/src/types.ts"],
+      "@deepseek-ai/dsh-type-meta": ["./packages/typert/type-meta/src/index.ts"],
+      "@deepseek-ai/dsh-type-meta/types": ["./packages/typert/type-meta/src/types.ts"],
       "@deepseek-ai/dsh-typert-loader": ["./packages/typert/loader/src/index.ts"],
       "@deepseek-ai/dsh-session/invariant": ["./packages/core/session/src/invariant.ts"],
       "@deepseek-ai/dsh-typert-registry/types": ["./packages/typert/registry/src/types.ts"],
@@ -68,7 +75,6 @@
       "@deepseek-ai/dsh-tool-subagent-control/list-agents": ["./packages/subagent/tool-subagent-control/src/list-agents.ts"],
       "@deepseek-ai/dsh-user-approval/types": ["./packages/ui/user-approval/src/types.ts"],
       "@deepseek-ai/dsh-user-interaction/types": ["./packages/ui/user-interaction/src/types.ts"],
-      "@deepseek-ai/dsh-agent/brand": ["./packages/core/agent/src/brand.ts"],
       "@deepseek-ai/dsh-agent/invariant": ["./packages/core/agent/src/invariant.ts"],
       "@deepseek-ai/dsh-scope/invariant": ["./packages/core/scope/src/invariant.ts"],
       "@deepseek-ai/dsh-agent-loop/invariant": ["./packages/core/agent-loop/src/invariant.ts"],
@@ -145,6 +151,8 @@
       "@deepseek-ai/dsh-client-schema-form/invariant": ["./packages/client/schema-form/src/invariant.ts"],
       "@deepseek-ai/dsh-client-web-react": ["./packages/client/web-react/src"],
       "@deepseek-ai/dsh-client-connection": ["./packages/client/connection/src"],
+      "@deepseek-ai/dsh-client-remotes": ["./packages/client/remotes/src"],
+      "@deepseek-ai/dsh-client-remotes/client": ["./packages/client/remotes/src/client/index.ts"],
       "@deepseek-ai/dsh-client-hmr": ["./packages/client/hmr/src"],
       "@deepseek-ai/dsh-client-modules": ["./packages/client/modules/src"],
       "@deepseek-ai/dsh-client-runtime": ["./packages/client/runtime/src"],
diff --git a/tsconfig.client.json b/tsconfig.client.json
index 03a2b8bb59..b0567f762e 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -51,6 +51,8 @@
     { "path": "./packages/client/modules" },
     { "path": "./packages/client/hmr" },
     { "path": "./packages/client/connection" },
+    { "path": "./packages/typert/registry" },
+    { "path": "./packages/host/api-gateway" },
     { "path": "./packages/client/runtime" },
     { "path": "./packages/client/test-runtime" },
     { "path": "./packages/client/ui-layout" },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 79276dfe7e..37c20c0d5c 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -100,7 +100,9 @@
     { "path": "./packages/llm/token-meter" },
     { "path": "./packages/core/session" },
     { "path": "./packages/core/scope" },
+    { "path": "./packages/typert/type-meta" },
     { "path": "./packages/typert/registry" },
+    { "path": "./packages/host/api-gateway" },
     { "path": "./packages/typert/loader" },
     { "path": "./packages/session-persistence/session-persistence" },
     { "path": "./packages/session-persistence/session-checkpoint-policy" },
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 41a490436f..0d503c62d3 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -1,4 +1,5 @@
 import { defineConfig } from 'tsdown'
+import { typertPlugin } from './packages/typert/generator/lib/types/tsdown-plugin.js'
 
 /**
  * JS bundling for vendored Cordis and Harness TypeScript packages.
@@ -27,4 +28,7 @@ export default defineConfig({
   fixedExtension: false,
   dts: false,
   clean: false,
+  // The final pass sees both independent TypeScript faces. Workspace mode
+  // writes only packages that explicitly publish a Typert/Remote subpath.
+  plugins: [typertPlugin({ mode: 'workspace' })],
 })
diff --git a/tsdown.typert-host.config.ts b/tsdown.typert-host.config.ts
new file mode 100644
index 0000000000..8c8ae11dd1
--- /dev/null
+++ b/tsdown.typert-host.config.ts
@@ -0,0 +1,20 @@
+import { defineConfig } from 'tsdown'
+import { typertPlugin } from './packages/typert/generator/lib/types/tsdown-plugin.js'
+
+/**
+ * Host-only TypeRT contract prepass. The generator and its project references
+ * are compiled first; the plugin then analyzes Host source and emits local and
+ * Host-for-Client artifacts before either aggregate consumes Remote subpaths.
+ */
+export default defineConfig({
+  workspace: ['packages/typert/generator'],
+  entry: ['lib/types/{index,invariant}.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+  plugins: [typertPlugin({ mode: 'workspace', faces: ['host'] })],
+})
diff --git a/vitest.config.ts b/vitest.config.ts
index cd37feb300..4c4c668b94 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import tsconfigPaths from 'vite-tsconfig-paths'
 import { resolvePwshPath } from './packages/bash/pwsh-local/src/resolve.ts'
 import { defineConfig } from 'vitest/config'
+import ts from 'typescript'
 import { vitestExecArgv } from './vitest.shared.ts'
 import { COVERAGE_EXEMPT_ENV, coverageExemptHeavySuites } from './scripts/coverage-exempt.ts'
 
@@ -17,6 +18,29 @@ const uncoveredLocationsReporter = fileURLToPath(new URL('./scripts/coverage-unc
 // map applies to every test file. paths must win over package exports so built
 // lib/ never loads a second module-singleton copy.
 const pathsPlugin = (): ReturnType<typeof tsconfigPaths> => tsconfigPaths({ projects: ['./tsconfig.base.json'] })
+const decoratorSyntax = /^\s*@[A-Za-z_$][\w$]*/m
+
+const standardDecoratorPlugin = () => ({
+  name: 'dsh-standard-decorators',
+  enforce: 'pre' as const,
+  transform(code: string, id: string) {
+    const file = id.split('?', 1)[0]!
+    if (!/\.[cm]?tsx?$/.test(file) || !decoratorSyntax.test(code)) return
+    const result = ts.transpileModule(code, {
+      fileName: file,
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2024,
+        module: ts.ModuleKind.ESNext,
+        jsx: file.endsWith('x') ? ts.JsxEmit.ReactJSX : undefined,
+        sourceMap: true,
+      },
+    })
+    return {
+      code: result.outputText.replace(/\n?\/\/# sourceMappingURL=.*$/u, '\n'),
+      map: result.sourceMapText,
+    }
+  },
+})
 
 const windowsUnsupportedPackages = process.platform === 'win32'
   ? [
@@ -88,7 +112,7 @@ const processBoundTests = [
 ]
 
 export default defineConfig({
-  plugins: [pathsPlugin()],
+  plugins: [pathsPlugin(), standardDecoratorPlugin()],
   test: {
     setupFiles: ['./scripts/test-invariants.ts'],
     // .tsx: client component specs (jsdom via per-file @vitest-environment pragma).
@@ -99,7 +123,7 @@ export default defineConfig({
     // always fork.
     projects: [
       {
-        plugins: [pathsPlugin()],
+        plugins: [pathsPlugin(), standardDecoratorPlugin()],
         test: {
           name: 'thread-safe',
           execArgv: vitestExecArgv,
@@ -119,7 +143,7 @@ export default defineConfig({
         },
       },
       {
-        plugins: [pathsPlugin()],
+        plugins: [pathsPlugin(), standardDecoratorPlugin()],
         test: {
           name: 'process-bound',
           execArgv: vitestExecArgv,

From 9a0a9350c44bf20e57c37daace7fb6746e5d9d00 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 5 Aug 2026 23:18:35 +0800
Subject: [PATCH 117/516] fix(typert): satisfy workspace static gates

---
 THIRD_PARTY_NOTICES.md                        |   1 +
 docs/cordis-catalog/services.md               |   2 +-
 knip.json                                     |   3 +-
 packages/client/connection/src/client/rpc.ts  |   1 -
 packages/client/connection/src/http-bridge.ts |   6 +-
 packages/client/connection/src/rpc-host.ts    |  26 +-
 .../connection/tests/client-apply.spec.ts     |  43 +++
 .../connection/tests/http-bridge.spec.ts      |   2 +-
 .../client/connection/tests/node-half.spec.ts |  68 +++-
 packages/host/api-gateway/package.json        |   4 +-
 packages/host/api-gateway/src/client/index.ts |   9 +-
 packages/host/api-gateway/src/index.ts        |  10 +-
 .../host/api-gateway/tests/client.spec.ts     | 138 ++++++++
 .../host/api-gateway/tests/gateway.spec.ts    | 294 ++++++++++++++++++
 packages/typert/generator/src/emitter.ts      |  27 +-
 .../typert/generator/src/tsdown-plugin.ts     |  35 ++-
 .../generator/tests/tsdown-plugin.spec.ts     |   7 +
 packages/typert/registry/src/service.ts       |   7 +
 packages/typert/registry/tests/typert.spec.ts | 149 +++++++++
 packages/typert/type-meta/package.json        |   4 +-
 .../typert/type-meta/tests/type-meta.spec.ts  |  74 +++++
 pnpm-lock.yaml                                |   3 +
 python/sdk-runtime/package.json               |   1 +
 scripts/check-workspace-constraints.ts        |  34 +-
 scripts/dev-web.spec.ts                       |   8 +-
 scripts/dev-web.ts                            |  23 +-
 scripts/publication-payload.spec.ts           |  31 +-
 scripts/publication-payload.ts                |  36 ++-
 scripts/publish-npm-baseline.ts               |  14 +-
 29 files changed, 986 insertions(+), 74 deletions(-)

diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index f70245d49d..e53dd292e4 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -39,6 +39,7 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`@clack/prompts`](https://github.com/bombshell-dev/clack) | MIT |
 | [`@earendil-works/pi-ai`](https://github.com/earendil-works/pi) | MIT |
 | [`@joplin/turndown-plugin-gfm`](https://github.com/laurent22/joplin-turndown-plugin-gfm) | MIT |
+| [`@jridgewell/gen-mapping`](https://github.com/jridgewell/sourcemaps) | MIT |
 | [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) | MIT |
 | [`@opentelemetry/api`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
 | [`@opentelemetry/api-logs`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 0a9af0bae5..41059aebf4 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2585,7 +2585,7 @@ listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
 toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
 ```
 
-Source: [`packages/typert/registry/src/service.ts:319`](../../packages/typert/registry/src/service.ts)
+Source: [`packages/typert/registry/src/service.ts:324`](../../packages/typert/registry/src/service.ts)
 
 ## `ctx.typertGateway` — `TypertGatewayService`
 
diff --git a/knip.json b/knip.json
index 7a3922c8fb..32c9e20dbf 100644
--- a/knip.json
+++ b/knip.json
@@ -200,7 +200,8 @@
     "packages/typert/generator": {
       "entry": [
         "tests/**/*.spec.ts",
-        "tests/fixtures/type-model/**/*.ts"
+        "tests/fixtures/type-model/**/*.ts",
+        "tests/fixtures/remote-model/**/*.ts"
       ],
       "project": [
         "src/**/*.ts",
diff --git a/packages/client/connection/src/client/rpc.ts b/packages/client/connection/src/client/rpc.ts
index 36e16426b2..0c12149d7b 100644
--- a/packages/client/connection/src/client/rpc.ts
+++ b/packages/client/connection/src/client/rpc.ts
@@ -67,7 +67,6 @@ function resolveBase(): string {
 function assertTarget(channel: string, endpoint: string): void {
   const segments = endpoint.split('/')
   if (!CHANNEL_PATTERN.test(channel)
-    || segments.length === 0
     || segments.some(segment =>
       segment === '' || segment === '.' || segment === '..' || !ENDPOINT_SEGMENT_PATTERN.test(segment))) {
     throw new Error(`connection: invalid RPC target ${JSON.stringify(`${channel}/${endpoint}`)}`)
diff --git a/packages/client/connection/src/http-bridge.ts b/packages/client/connection/src/http-bridge.ts
index 319d3e0b0b..88d577bef8 100644
--- a/packages/client/connection/src/http-bridge.ts
+++ b/packages/client/connection/src/http-bridge.ts
@@ -5,6 +5,10 @@
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
+interface FetchHandler {
+  fetch(request: Request): Promise<Response>
+}
+
 /**
  * Bridge one node:http request to the fetch-shaped handler (client close
  * aborts; SSE bodies stream out chunk by chunk).
@@ -12,7 +16,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
  * @param res - node:http response the bridge writes and owns to completion.
  * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
  */
-export async function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: { fetch: typeof fetch }): Promise<void> {
+export async function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: FetchHandler): Promise<void> {
   const abort = new AbortController()
   // Client-disconnect detection MUST hang off the response, not the request:
   // since Node 16, IncomingMessage 'close' fires as soon as the request body is
diff --git a/packages/client/connection/src/rpc-host.ts b/packages/client/connection/src/rpc-host.ts
index be9eedca8f..a6fbdb0264 100644
--- a/packages/client/connection/src/rpc-host.ts
+++ b/packages/client/connection/src/rpc-host.ts
@@ -7,6 +7,7 @@ import {
   RpcId,
   type ClientRequest,
   type RpcError,
+  type RpcErrorDetailsMap,
   type RpcId as RpcIdType,
   type ServerResponse as RpcServerResponse,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -73,10 +74,9 @@ export class HostConnectionService extends Service implements HostConnectionHand
 function rpcFetchHandler(
   channel: string,
   handler: ConnectionRpcHandler,
-): { fetch: typeof fetch } {
+): { fetch(request: Request): Promise<Response> } {
   return {
-    async fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
-      const request = input instanceof Request ? input : new Request(input, init)
+    async fetch(request: Request): Promise<Response> {
       const endpoint = endpointFromPath(channel, new URL(request.url).pathname)
       if (request.method !== 'POST' || endpoint === undefined) {
         return new Response('not found', { status: 404 })
@@ -96,13 +96,7 @@ function rpcFetchHandler(
 
       const envelope = clientRequestSchema.safeParse(body)
       if (!envelope.success) {
-        const rawId = (body as { rpcId?: unknown } | null)?.rpcId
-        const rpcId = typeof rawId === 'string' ? RpcId(rawId) : INVALID_REQUEST_RPC_ID
-        return errorResponse(rpcId, {
-          code: 'bad-request',
-          message: 'invalid client-request message',
-          details: { issues: envelope.error.issues },
-        })
+        return invalidEnvelopeResponse(body, envelope.error.issues)
       }
       const message: ClientRequest = envelope.data
       if (message.method !== endpoint) {
@@ -123,11 +117,21 @@ function rpcFetchHandler(
   }
 }
 
+function invalidEnvelopeResponse(body: unknown, issues: RpcErrorDetailsMap['bad-request']['issues']): Response {
+  const rawId = (body as { rpcId?: unknown } | null)?.rpcId
+  const rpcId = typeof rawId === 'string' ? RpcId(rawId) : INVALID_REQUEST_RPC_ID
+  return errorResponse(rpcId, {
+    code: 'bad-request',
+    message: 'invalid client-request message',
+    details: { issues },
+  })
+}
+
 function endpointFromPath(channel: string, pathname: string): string | undefined {
   if (!pathname.startsWith(`${channel}/`)) return undefined
   const endpoint = pathname.slice(channel.length + 1)
   const segments = endpoint.split('/')
-  if (segments.length === 0 || segments.some(segment =>
+  if (segments.some(segment =>
     segment === '' || segment === '.' || segment === '..' || !ENDPOINT_SEGMENT_PATTERN.test(segment))) {
     return undefined
   }
diff --git a/packages/client/connection/tests/client-apply.spec.ts b/packages/client/connection/tests/client-apply.spec.ts
index d93844a2b8..3ce8b89ecb 100644
--- a/packages/client/connection/tests/client-apply.spec.ts
+++ b/packages/client/connection/tests/client-apply.spec.ts
@@ -235,6 +235,49 @@ describe('connection client apply', () => {
     })
   })
 
+  it('validates generic RPC transport failures, correlation, and targets', async () => {
+    ;(globalThis as Win).location = {
+      hostname: 'harness.example', search: '', origin: 'https://harness.example',
+    }
+    const handle = await mount()
+    const original = globalThis.fetch
+    const abort = new AbortController()
+    globalThis.fetch = vi.fn().mockResolvedValue(new Response('unavailable', { status: 503 }))
+    try {
+      await expect(handle.rpc.call('/api2', 'goals/create', {}, abort.signal))
+        .rejects.toThrow('HTTP 503')
+      expect(globalThis.fetch).toHaveBeenCalledWith(
+        new URL('https://harness.example/api2/goals/create'),
+        expect.objectContaining({ signal: abort.signal }),
+      )
+
+      ;(globalThis as Win).location = { hostname: 'localhost', search: '', origin: 'null' }
+      globalThis.fetch = vi.fn().mockResolvedValue(Response.json({
+        type: 'server-response',
+        rpcId: 'different-rpc',
+        result: { ok: true, value: null },
+      }))
+      await expect(handle.rpc.call('/api2', 'goals/create', {})).rejects.toThrow('rpcId mismatch')
+      const fetch = vi.mocked(globalThis.fetch)
+      expect(fetch.mock.calls[0]?.[0]).toEqual(new URL('http://dsh.internal/api2/goals/create'))
+      expect(fetch.mock.calls[0]?.[1]).not.toHaveProperty('signal')
+    } finally {
+      globalThis.fetch = original
+    }
+
+    for (const [channel, endpoint] of [
+      ['api2', 'goals/create'],
+      ['/api2/path', 'goals/create'],
+      ['/api2', ''],
+      ['/api2', '.'],
+      ['/api2', '..'],
+      ['/api2', 'goals//create'],
+      ['/api2', 'goals/create?unsafe'],
+    ] as const) {
+      await expect(handle.rpc.call(channel, endpoint, {})).rejects.toThrow('invalid RPC target')
+    }
+  })
+
   it('keeps generic Remote calls unavailable in the client-only fixture', async () => {
     ;(globalThis as Win).location = { hostname: 'localhost', search: '?fixture' }
     const handle = await mount()
diff --git a/packages/client/connection/tests/http-bridge.spec.ts b/packages/client/connection/tests/http-bridge.spec.ts
index 4607f32bae..b06834e523 100644
--- a/packages/client/connection/tests/http-bridge.spec.ts
+++ b/packages/client/connection/tests/http-bridge.spec.ts
@@ -28,7 +28,7 @@ describe('HTTP bridge abort', () => {
     let carrierSignal: AbortSignal | undefined
     const pending = bridge(request, response, {
       fetch: async (input) => {
-        const fetchRequest = input as Request
+        const fetchRequest = input
         carrierSignal = fetchRequest.signal
         resolveStarted()
         if (!fetchRequest.signal.aborted) {
diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts
index af85d4e510..1c42a9dc88 100644
--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -47,6 +47,13 @@ function fakePost(headers: Record<string, string>, url: string, body: unknown):
   return request
 }
 
+/** Raw POST for malformed-body and media-type boundary cases. */
+function fakeRawPost(headers: Record<string, string>, url: string, body: string): IncomingMessage {
+  const request = Readable.from([Buffer.from(body)]) as unknown as IncomingMessage
+  Object.assign(request, { url, method: 'POST', headers })
+  return request
+}
+
 /** Response recorder compatible with both the fence's short-circuit and the bridge. */
 function fakeResponse(): { response: ServerResponse; state: { status?: number; body?: unknown } } {
   const state: { status?: number; body?: unknown } = {}
@@ -239,7 +246,10 @@ describe('connection node half', () => {
     const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.example'] })
     await fiber.await()
     const connection = ctx.get('connection') as HostConnectionHandle
-    const remove = connection.rpc.handle('/api2', async () => ({ ok: true, value: null }), {
+    const remove = connection.rpc.handle('/api2', async (endpoint) => {
+      if (endpoint === 'fail') throw new Error('handler broke')
+      return { ok: true, value: null }
+    }, {
       authority: 'trusted-host',
     })
     const route = routes[0]!
@@ -248,14 +258,64 @@ describe('connection node half', () => {
     await route.handler(fakePost({ host: 'other.example' }, '/api2/goals/create', {}), denied.response)
     expect(denied.state).toMatchObject({ status: 403, body: 'forbidden' })
 
-    const badEnvelope = fakeResponse()
+    const methodMismatch = fakeResponse()
     await route.handler(fakePost({ host: 'harness.example' }, '/api2/goals/create', {
       type: 'client-request', rpcId: 'rpc-bad', method: 'other', payload: {},
-    }), badEnvelope.response)
-    expect(JSON.parse(String(badEnvelope.state.body))).toMatchObject({
+    }), methodMismatch.response)
+    expect(JSON.parse(String(methodMismatch.state.body))).toMatchObject({
       rpcId: 'rpc-bad',
       result: { ok: false, error: { code: 'bad-request' } },
     })
+
+    for (const [request, status] of [
+      [fakeRequest({ host: 'harness.example' }, '/api2/goals/create'), 404],
+      [fakePost({ host: 'harness.example' }, '/outside/goals/create', {}), 404],
+      [fakePost({ host: 'harness.example' }, '/api2/goals//create', {}), 404],
+      [fakeRawPost({ host: 'harness.example' }, '/api2/goals/create', '{}'), 415],
+      [fakeRawPost({ host: 'harness.example', 'content-type': 'text/plain' }, '/api2/goals/create', '{}'), 415],
+      [fakeRawPost({ host: 'harness.example', 'content-type': 'application/json; charset=utf-8' }, '/api2/goals/create', '{'), 400],
+    ] as const) {
+      const response = fakeResponse()
+      await route.handler(request, response.response)
+      expect(response.state.status).toBe(status)
+    }
+
+    for (const [body, rpcId] of [
+      [{ rpcId: 'retained-id' }, 'retained-id'],
+      [{ rpcId: 42 }, 'invalid-request'],
+      [null, 'invalid-request'],
+    ] as const) {
+      const response = fakeResponse()
+      await route.handler(fakePost({ host: 'harness.example' }, '/api2/goals/create', body), response.response)
+      expect(JSON.parse(String(response.state.body))).toMatchObject({
+        rpcId,
+        result: { ok: false, error: { code: 'bad-request' } },
+      })
+    }
+
+    const failed = fakeResponse()
+    await route.handler(fakePost({ host: 'harness.example' }, '/api2/fail', {
+      type: 'client-request', rpcId: 'rpc-fail', method: 'fail', payload: {},
+    }), failed.response)
+    expect(failed.state).toMatchObject({ status: 500, body: 'handler failure: Error: handler broke' })
+
+    expect(() => connection.rpc.handle('/api', async () => ({ ok: true, value: null }), {
+      authority: 'loopback',
+    })).toThrow('invalid or reserved RPC channel')
+    expect(() => connection.rpc.handle('api3', async () => ({ ok: true, value: null }), {
+      authority: 'loopback',
+    })).toThrow('invalid or reserved RPC channel')
+
+    const removeLoopback = connection.rpc.handle('/loopback', async () => ({ ok: true, value: null }), {
+      authority: 'loopback',
+    })
+    const loopbackRoute = routes.find(candidate => candidate.path === '/loopback')!
+    const publicResponse = fakeResponse()
+    await loopbackRoute.handler(fakePost({ host: 'harness.example' }, '/loopback/read', {
+      type: 'client-request', rpcId: 'rpc-public', method: 'read', payload: {},
+    }), publicResponse.response)
+    expect(publicResponse.state.status).toBe(403)
+    await removeLoopback()
     await remove()
     await fiber.dispose()
   })
diff --git a/packages/host/api-gateway/package.json b/packages/host/api-gateway/package.json
index 3f3c905f1d..794ae323aa 100644
--- a/packages/host/api-gateway/package.json
+++ b/packages/host/api-gateway/package.json
@@ -43,9 +43,7 @@
     "lib/invariant.js",
     "lib/client.js",
     "lib/types/**/*.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
diff --git a/packages/host/api-gateway/src/client/index.ts b/packages/host/api-gateway/src/client/index.ts
index 57116db2cf..fe8fd9f1b3 100644
--- a/packages/host/api-gateway/src/client/index.ts
+++ b/packages/host/api-gateway/src/client/index.ts
@@ -90,7 +90,8 @@ class ClientApiService extends Service implements ClientApi {
         }
       }, `api-gateway.client.mount(${JSON.stringify(contribution.package)})`)
     } catch (error) {
-      disposeRemote().catch(() => {})
+      /* v8 ignore next -- rollback disposal only rejects if Cordis teardown itself fails while handling the installation error. */
+      Promise.resolve(disposeRemote()).catch(() => {})
       throw error
     }
     return async () => {
@@ -148,6 +149,7 @@ class ClientApiService extends Service implements ClientApi {
     const projection = scopedProjection(descriptor)
     if (projection !== undefined) installed.push(this.installScoped(descriptor, projection, token))
     return () => {
+      /* v8 ignore next -- Cordis effect disposers are idempotent and invoke this cleanup at most once. */
       if (!token.active) return
       token.active = false
       for (const dispose of installed.reverse()) dispose()
@@ -173,6 +175,7 @@ class ClientApiService extends Service implements ClientApi {
       value: (...args: unknown[]) => this.invoke(descriptor, undefined, token, this.ownerCtx, args),
     })
     return () => {
+      /* v8 ignore next -- duplicate live methods are rejected before installation, so no newer token can replace this one. */
       if (namespace.tokens.get(descriptor.method) !== token) return
       Reflect.deleteProperty(namespace.value, descriptor.method)
       namespace.tokens.delete(descriptor.method)
@@ -203,6 +206,7 @@ class ClientApiService extends Service implements ClientApi {
     namespace.tokens.set(descriptor.method, token)
     namespace.service.install(descriptor, projection, token)
     return () => {
+      /* v8 ignore next -- duplicate live methods are rejected before installation, so no newer token can replace this one. */
       if (namespace.tokens.get(descriptor.method) !== token) return
       namespace.service.remove(descriptor.method)
       namespace.tokens.delete(descriptor.method)
@@ -289,9 +293,6 @@ class ScopedRemoteNamespace extends Service {
       },
     })
     this.methods.add(method)
-    if (this.methods.size === 1 && this.ownerCtx.get(this.name, false) === undefined) {
-      this.ownerCtx.set(this.name, this)
-    }
   }
 
   remove(method: string): void {
diff --git a/packages/host/api-gateway/src/index.ts b/packages/host/api-gateway/src/index.ts
index ccb76e2d48..c83772261a 100644
--- a/packages/host/api-gateway/src/index.ts
+++ b/packages/host/api-gateway/src/index.ts
@@ -156,11 +156,10 @@ export class TypertGatewayService extends Service implements TypertGateway {
   private async invokeRpc(endpoint: string, payload: unknown): Promise<ConnectionRpcResult> {
     try {
       const segments = endpoint.split('/')
-      const namespace = segments[0]
-      const method = segments[1]
-      if (segments.length !== 2 || namespace === undefined || namespace === '' || method === undefined || method === '') {
+      if (segments.length !== 2 || segments[0] === '' || segments[1] === '') {
         throw new Error(`invalid Remote endpoint ${JSON.stringify(endpoint)}`)
       }
+      const [namespace, method] = segments as [string, string]
       if (!isObject(payload)
         || !isPlainObject(payload)
         || Reflect.ownKeys(payload).length !== 1
@@ -358,6 +357,7 @@ export class TypertGatewayService extends Service implements TypertGateway {
     const value = decode(parameter.codec, args[parameter.wire], 'input-invalid', endpoint, parameter.wire)
     if (parameter.source === 'json') return value
     const key = parameter.lookup
+    /* v8 ignore next -- registry validation rejects strict descriptors without a key, and SRC derivation always supplies one. */
     if (key === undefined) {
       throw new TypertGatewayError(
         'lookup-unavailable',
@@ -492,11 +492,11 @@ function methodParameterNames(service: object, method: string, endpoint: string)
   const source = Function.prototype.toString.call(implementation)
   const open = source.indexOf('(')
   const close = source.indexOf(')', open + 1)
+  /* v8 ignore next -- standard public class-method syntax always contains a parenthesized parameter list. */
   if (open < 0 || close < 0) return invalidSignature(endpoint, method)
   const body = source.slice(open + 1, close).trim()
   if (body.length === 0) return []
   const parts = body.split(',').map(part => part.trim())
-  if (parts.at(-1) === '') parts.pop()
   const names = new Set<string>()
   for (const part of parts) {
     if (!/^[$A-Z_a-z][$\w]*$/u.test(part) || names.has(part)) return invalidSignature(endpoint, method)
@@ -579,8 +579,8 @@ function assertJsonValue(value: unknown, ancestors: Set<object>): void {
     if (!isPlainObject(value)) throw new TypeError('non-plain object is not JSON-safe')
     if (Object.getOwnPropertySymbols(value).length > 0) throw new TypeError('symbol property is not JSON-safe')
     for (const key of Reflect.ownKeys(value)) {
-      if (typeof key !== 'string') throw new TypeError('symbol property is not JSON-safe')
       const descriptor = Object.getOwnPropertyDescriptor(value, key)
+      /* v8 ignore next -- ownKeys() just returned this key; only a hostile same-process Proxy can delete it between operations. */
       if (descriptor === undefined || !descriptor.enumerable || !('value' in descriptor)) {
         throw new TypeError('non-data property is not JSON-safe')
       }
diff --git a/packages/host/api-gateway/tests/client.spec.ts b/packages/host/api-gateway/tests/client.spec.ts
index be0b12ed51..8c0753f3f9 100644
--- a/packages/host/api-gateway/tests/client.spec.ts
+++ b/packages/host/api-gateway/tests/client.spec.ts
@@ -203,6 +203,144 @@ describe('Client TypeRT API', () => {
     expect(ctx.typert.remotes.list()).toEqual([])
   })
 
+  it('rejects duplicate, live, scoped-service, and Context namespace collisions', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const direct = directDescriptor()
+    const context = contextDescriptor()
+
+    expect(() => ctx.api.mount({
+      package: '@fixture/direct-duplicates',
+      descriptors: [direct, { ...direct, id: '@fixture/goals#goals/create-again' }],
+    })).toThrow('repeats direct method')
+    expect(() => ctx.api.mount({
+      package: '@fixture/scoped-duplicates',
+      descriptors: [context, { ...context, id: '@fixture/goals#goals/rename-again' }],
+    })).toThrow('repeats scoped method')
+
+    const disposeDirect = ctx.api.mount({ package: '@fixture/direct-live', descriptors: [direct] })
+    expect(() => ctx.api.mount({
+      package: '@fixture/direct-conflict', descriptors: [{ ...direct, id: '@fixture/other#goals/create' }],
+    })).toThrow('direct method goals/create is already mounted')
+    await disposeDirect()
+
+    const disposeScoped = ctx.api.mount({ package: '@fixture/scoped-live', descriptors: [context] })
+    expect(() => ctx.api.mount({
+      package: '@fixture/scoped-conflict', descriptors: [{ ...context, id: '@fixture/other#goals/rename' }],
+    })).toThrow('scoped method goals/rename is already mounted')
+    expect(() => ctx.api.mount({
+      package: '@fixture/service-method-conflict',
+      descriptors: [{ ...context, id: '@fixture/goals#goals/remove', method: 'remove' }],
+    })).toThrow('conflicts with its namespace service')
+    await disposeScoped()
+
+    expect(() => ctx.api.mount({
+      package: '@fixture/context-property-conflict',
+      descriptors: [{ ...context, namespace: 'typert' }],
+    })).toThrow('conflicts with an existing Context property')
+
+    const disposeMultipleScoped = ctx.api.mount({
+      package: '@fixture/multiple-scoped',
+      descriptors: [directDescriptor(), contextDescriptor()],
+    })
+    await disposeMultipleScoped()
+  })
+
+  it('rejects weak parameter and Context codecs plus malformed scope projections', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const direct = directDescriptor()
+    const context = contextDescriptor()
+    expect(() => ctx.api.mount({
+      package: '@fixture/weak-parameter',
+      descriptors: [{
+        ...direct,
+        parameters: direct.parameters.map((parameter, index) => index === 0
+          ? { ...parameter, codec: { mode: 'src-json' } }
+          : parameter),
+      }],
+    })).toThrow('has no strict codec')
+    expect(() => ctx.api.mount({
+      package: '@fixture/weak-context',
+      descriptors: [{
+        ...context,
+        invocation: { ...context.invocation, codec: { mode: 'src-json' } },
+      } as InvocationDescriptor],
+    })).toThrow('has no strict codec')
+    expect(() => ctx.api.mount({
+      package: '@fixture/malformed-scope',
+      descriptors: [{ ...direct, scope: { context: 'fixture', wire: 'missingId' } }],
+    })).toThrow('scope must select its only lookup parameter')
+    expect(() => ctx.api.mount({
+      package: '@fixture/ambiguous-scope',
+      descriptors: [{
+        ...direct,
+        parameters: [...direct.parameters, {
+          name: 'other', wire: 'otherId', source: 'lookup', lookup: 'fixture',
+          codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', schema: idSchema },
+        }],
+      }],
+    })).toThrow('scope must select its only lookup parameter')
+  })
+
+  it('validates invocation arity, required binders, live Connection, and mutable descriptor codecs', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })
+    const ctx = await bench(call)
+    const descriptor = directDescriptor()
+    const dispose = ctx.api.mount({ package: '@fixture/goals', descriptors: [descriptor] })
+    const create = ctx.api.goals.create as unknown as (...args: unknown[]) => Promise<unknown>
+
+    await expect(create('agent-1')).rejects.toThrow('expected 2 argument(s), got 1')
+    await expect((ctx as FixtureContext).goals.create({ objective: 'ship' }))
+      .rejects.toThrow('no Client Context binder')
+
+    ;(descriptor.parameters[0] as { codec: { mode: string } }).codec.mode = 'src-json'
+    await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('has no strict codec')
+    ;(descriptor.parameters[0] as { codec: { mode: string } }).codec.mode = 'strict'
+
+    ctx.set('connection', undefined)
+    await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('no active Connection')
+    await dispose()
+  })
+
+  it('withdraws a pending invocation and preserves a direct namespace until its last method leaves', async () => {
+    let resolveCall!: (result: Awaited<ReturnType<ConnectionHandle['rpc']['call']>>) => void
+    const pending = new Promise<Awaited<ReturnType<ConnectionHandle['rpc']['call']>>>((resolve) => {
+      resolveCall = resolve
+    })
+    const call = vi.fn<ConnectionHandle['rpc']['call']>().mockReturnValue(pending)
+    const ctx = await bench(call)
+    const { scope: _scope, ...first } = directDescriptor()
+    const second: InvocationDescriptor = {
+      ...first,
+      id: '@fixture/goals#goals/archive',
+      method: 'archive',
+    }
+    const dispose = ctx.api.mount({ package: '@fixture/goals', descriptors: [first, second] })
+    const invocation = ctx.api.goals.create('agent-1', { objective: 'ship' })
+    await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(1) })
+    await dispose()
+    resolveCall({ ok: true, value: { ref: 'goal-1' } })
+
+    await expect(invocation).rejects.toThrow('withdrawn during invocation')
+    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+  })
+
+  it('rolls back Remote registration when concrete method installation fails', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const defineProperty = Object.defineProperty
+    const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      if (key === 'goals') throw new Error('fixture installation failure')
+      return defineProperty(target, key, attributes)
+    })
+    try {
+      expect(() => ctx.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] }))
+        .toThrow('fixture installation failure')
+      await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
   it('throws RPC failures with the structured error as its cause', async () => {
     const rpcError = { code: 'internal' as const, message: 'host failed', details: {} }
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>().mockResolvedValue({ ok: false, error: rpcError }))
diff --git a/packages/host/api-gateway/tests/gateway.spec.ts b/packages/host/api-gateway/tests/gateway.spec.ts
index 8f7c144f5e..0b550e126d 100644
--- a/packages/host/api-gateway/tests/gateway.spec.ts
+++ b/packages/host/api-gateway/tests/gateway.spec.ts
@@ -229,6 +229,96 @@ class WrongBindingService extends Service {
   }
 }
 
+class ExportedMethodService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'exportedMethod', { namespace: 'exported' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'exportedMethod')
+  }
+
+  @Remote('execute')
+  run(value: string): string {
+    return value
+  }
+}
+
+class EmptyMethodService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'emptyMethod', { namespace: 'empty' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'emptyMethod')
+  }
+
+  @Remote
+  ping(): string {
+    return 'pong'
+  }
+}
+
+class CollidingWireService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'collidingWire', { namespace: 'colliding-wire' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'collidingWire')
+  }
+
+  @Remote
+  run(agent: FixtureAgent, agentId: string): string {
+    return `${agent.id}:${agentId}`
+  }
+}
+
+class ContextWireService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'contextWire', { namespace: 'context-wire' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'contextWire')
+  }
+
+  @RemoteContext('gatewayFixture')
+  run(agentId: string): string {
+    return agentId
+  }
+}
+
+class NoBindingService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'noBinding')
+  }
+
+  run(value: string): string {
+    return value
+  }
+}
+
+class MissingMethodService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'missingMethod', { namespace: 'missing-method' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'missingMethod')
+  }
+
+  @Remote
+  run(value: string): string {
+    return value
+  }
+}
+
+class InheritedMethodBase extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'inheritedMethod', { namespace: 'inherited' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'inheritedMethod')
+  }
+
+  @Remote
+  run(value: string): string {
+    return value
+  }
+}
+
+class InheritedMethodService extends InheritedMethodBase {}
+
 describe('TypertGatewayService', () => {
   it('invokes a strict direct method with schema decoding and a live lookup', async () => {
     const { ctx, service } = await setup()
@@ -284,6 +374,53 @@ describe('TypertGatewayService', () => {
     })).resolves.toEqual({ title: 'land', scope: 'agent-src' })
   })
 
+  it('derives exported, empty, inherited, and distinct-namespace SRC methods', async () => {
+    const ctx = await setupGateway()
+    await ctx.plugin(ExportedMethodService)
+    await ctx.plugin(EmptyMethodService)
+    await ctx.plugin(InheritedMethodService)
+
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'exported', method: 'execute', args: { value: 'ship' },
+    })).resolves.toBe('ship')
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'empty', method: 'ping', args: {},
+    })).resolves.toBe('pong')
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'inherited', method: 'run', args: { value: 'land' },
+    })).resolves.toBe('land')
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'other', method: 'absent', args: {},
+    }), 'invocation-unavailable')
+  })
+
+  it('rejects SRC wire collisions and unavailable Context providers', async () => {
+    const colliding = await setupGateway()
+    await colliding.plugin(CollidingWireService)
+    registerAgentLookup(colliding, { id: 'agent-1' })
+    await expectCode(colliding.typertGateway.invoke({
+      namespace: 'colliding-wire',
+      method: 'run',
+      args: { agentId: 'agent-1' },
+    }), 'signature-invalid')
+
+    const missing = await setup()
+    await expectCode(missing.ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    }), 'context-unavailable')
+
+    const contextCollision = await setupGateway()
+    await contextCollision.plugin(ContextWireService)
+    contextCollision.typert.contexts.registerHost('gatewayFixture', contextProvider(contextCollision.extend()))
+    await expectCode(contextCollision.typertGateway.invoke({
+      namespace: 'context-wire',
+      method: 'run',
+      args: { agentId: 'agent-1' },
+    }), 'signature-invalid')
+  })
+
   it('re-reads Service and providers on every strict invocation', async () => {
     const { ctx, serviceFiber } = await setup()
     const agent = { id: 'agent-1' }
@@ -331,6 +468,58 @@ describe('TypertGatewayService', () => {
     expect(error.cause).toEqual(new Error('provider failed'))
   })
 
+  it('reports Context provider metadata mismatch and unresolved identities', async () => {
+    const { ctx } = await setup()
+    registerStrict(ctx, [renameDescriptor()])
+    const scoped = ctx.extend()
+    const mismatch = ctx.typert.contexts.registerHost('gatewayFixture', {
+      ...contextProvider(scoped),
+      wire: 'differentAgentId',
+    })
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    }), 'provider-mismatch')
+    await mismatch()
+
+    ctx.typert.contexts.registerHost('gatewayFixture', {
+      ...contextProvider(scoped),
+      resolve: () => undefined,
+    })
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    }), 'context-not-found')
+  })
+
+  it('contains lookup provider failures and missing identities', async () => {
+    const { ctx } = await setup()
+    registerStrict(ctx, [createDescriptor()])
+    const throwing = ctx.typert.lookups.register('gatewayFixture', {
+      ...agentLookup({ id: 'agent-1' }),
+      resolve: () => { throw new Error('lookup failed') },
+    })
+    const failure = await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'lookup-failed')
+    expect(failure.cause).toEqual(new Error('lookup failed'))
+    await throwing()
+
+    ctx.typert.lookups.register('gatewayFixture', {
+      ...agentLookup({ id: 'agent-1' }),
+      resolve: () => undefined,
+    })
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'lookup-not-found')
+  })
+
   it('never downgrades an observed strict endpoint after definition disposal', async () => {
     const { ctx } = await setup()
     const dispose = registerStrict(ctx, [passthroughDescriptor()])
@@ -434,6 +623,11 @@ describe('TypertGatewayService', () => {
       method: 'create',
       args: { agentId: 'agent-1', request: { title: 'ship' }, optional: true },
     }), 'arguments-invalid')
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: [] as unknown as Record<string, unknown>,
+    }), 'arguments-invalid')
     expect(service.calls).toEqual([])
   })
 
@@ -492,6 +686,31 @@ describe('TypertGatewayService', () => {
     }), 'result-invalid')
   })
 
+  it('accepts dense JSON and rejects decorated arrays and object properties', async () => {
+    const { ctx } = await setup()
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: [1, { nested: true }] },
+    })).resolves.toEqual([1, { nested: true }])
+
+    const sparseWithExtra = Array(1) as unknown[] & { extra?: boolean }
+    sparseWithExtra.extra = true
+    const symbolArray = [1]
+    Object.defineProperty(symbolArray, Symbol('extra'), { value: true })
+    const symbolObject = { value: true }
+    Object.defineProperty(symbolObject, Symbol('extra'), { value: true })
+    const hidden = {}
+    Object.defineProperty(hidden, 'value', { value: true, enumerable: false })
+    const accessor = {}
+    Object.defineProperty(accessor, 'value', { get: () => true, enumerable: true })
+    for (const value of [sparseWithExtra, symbolArray, symbolObject, hidden, accessor]) {
+      await expectCode(ctx.typertGateway.invoke({
+        namespace: 'goals', method: 'passthrough', args: { value },
+      }), 'input-invalid')
+    }
+  })
+
   it('validates strict provider identity against generated wire metadata', async () => {
     const { ctx } = await setup()
     ctx.typert.lookups.register('gatewayFixture', {
@@ -525,6 +744,61 @@ describe('TypertGatewayService', () => {
     }), 'method-unavailable')
   })
 
+  it('requires a visible binding and supports explicitly provided plain Services', async () => {
+    const ctx = await setupGateway()
+    await ctx.plugin(NoBindingService)
+    registerStrict(ctx, [{
+      ...passthroughDescriptor(),
+      id: '@fixture/gateway#no-binding/run',
+      service: 'noBinding',
+      namespace: 'no-binding',
+      method: 'run',
+    }])
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'no-binding', method: 'run', args: { value: 'ship' },
+    }), 'binding-invalid')
+
+    const plain: {
+      typertGateway?: ReturnType<typeof bindTypeRTGateway>
+      run(value: string): string
+    } = { run: value => value }
+    plain.typertGateway = bindTypeRTGateway(plain, 'plainRemote', { namespace: 'plain' })
+    ctx.provide('plainRemote', plain)
+    ctx.typert.register({
+      package: '@fixture/plain',
+      face: 'host',
+      schemas: [],
+      model: emptyModel,
+      invocations: [{
+        ...passthroughDescriptor(),
+        id: '@fixture/plain#plain/run',
+        service: 'plainRemote',
+        namespace: 'plain',
+        method: 'run',
+      }],
+    })
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'plain', method: 'run', args: { value: 'land' },
+    })).resolves.toBe('land')
+  })
+
+  it('reports a SRC marker whose prototype implementation disappeared', async () => {
+    const ctx = await setupGateway()
+    await ctx.plugin(MissingMethodService)
+    const descriptor = Object.getOwnPropertyDescriptor(MissingMethodService.prototype, 'run')!
+    Object.defineProperty(MissingMethodService.prototype, 'run', {
+      configurable: true,
+      value: 42,
+    })
+    try {
+      await expectCode(ctx.typertGateway.invoke({
+        namespace: 'missing-method', method: 'run', args: { value: 'ship' },
+      }), 'method-unavailable')
+    } finally {
+      Object.defineProperty(MissingMethodService.prototype, 'run', descriptor)
+    }
+  })
+
   it('preserves business exception identity after invocation begins', async () => {
     const { ctx, service } = await setup()
     const failure = new Error('business identity')
@@ -575,6 +849,26 @@ describe('TypertGatewayService', () => {
     if (invalid.ok) throw new Error('invalid Remote payload unexpectedly succeeded')
     expect(invalid.error.message).toMatch(/exactly one plain-object args field/)
 
+    for (const endpoint of ['goals', '/create', 'goals/', 'goals/create/extra']) {
+      const result = await handler(endpoint, { args: {} }, signal)
+      expect(result).toMatchObject({ ok: false, error: { code: 'internal' } })
+      if (result.ok) throw new Error('invalid Remote endpoint unexpectedly succeeded')
+      expect(result.error.message).toContain('invalid Remote endpoint')
+    }
+    for (const payload of [null, [], { args: {}, extra: true }, { only: true }, { args: null }, { args: [] }]) {
+      const result = await handler('goals/create', payload, signal)
+      expect(result).toMatchObject({ ok: false, error: { code: 'internal' } })
+      if (result.ok) throw new Error('invalid Remote payload unexpectedly succeeded')
+      expect(result.error.message).toContain('plain-object args field')
+    }
+
+    const service = rawGoalService(ctx)
+    service.businessError = 'non-error failure' as unknown as Error
+    await expect(handler('goals/fail', { args: { request: null } }, signal)).resolves.toEqual({
+      ok: false,
+      error: { code: 'internal', message: 'non-error failure', details: {} },
+    })
+
     await gatewayFiber.dispose()
     expect(connection.handler).toBeUndefined()
   })
diff --git a/packages/typert/generator/src/emitter.ts b/packages/typert/generator/src/emitter.ts
index 3e79780593..63b1ee7ace 100644
--- a/packages/typert/generator/src/emitter.ts
+++ b/packages/typert/generator/src/emitter.ts
@@ -399,21 +399,9 @@ export class FaceModelEmitter {
     scoped: boolean,
   ): void {
     const signature = this.remoteSignature(invocation, referenceNames, scoped)
-    const line = `    ${signature}`
-    lines.push(line)
-    const generatedLine = lines.length
     const keyLength = signature.indexOf(': (')
     if (keyLength < 0) throw new TypertEmitError(`Remote signature ${invocation.id} has no property delimiter`)
-    const source = remoteDeclarationSource(packageModel, invocation)
-    addMapping(sourceMap, {
-      generated: { line: generatedLine, column: 4 },
-      source,
-      original: { line: invocation.location.line, column: invocation.location.column - 1 },
-      name: invocation.method,
-    })
-    addMapping(sourceMap, {
-      generated: { line: generatedLine, column: 4 + keyLength },
-    })
+    this.pushMappedRemoteSignature(lines, sourceMap, packageModel, invocation, signature, keyLength)
   }
 
   private pushRemoteNamespaceSignature(
@@ -424,6 +412,17 @@ export class FaceModelEmitter {
     referenceNames: ReadonlyMap<SymbolId, string>,
   ): void {
     const signature = `${invocation.method}: ${this.remoteFunctionType(invocation, referenceNames, false)}`
+    this.pushMappedRemoteSignature(lines, sourceMap, packageModel, invocation, signature, invocation.method.length)
+  }
+
+  private pushMappedRemoteSignature(
+    lines: string[],
+    sourceMap: GenMapping,
+    packageModel: PackageModel,
+    invocation: InvocationModel,
+    signature: string,
+    keyLength: number,
+  ): void {
     lines.push(`    ${signature}`)
     const generatedLine = lines.length
     const source = remoteDeclarationSource(packageModel, invocation)
@@ -434,7 +433,7 @@ export class FaceModelEmitter {
       name: invocation.method,
     })
     addMapping(sourceMap, {
-      generated: { line: generatedLine, column: 4 + invocation.method.length },
+      generated: { line: generatedLine, column: 4 + keyLength },
     })
   }
 
diff --git a/packages/typert/generator/src/tsdown-plugin.ts b/packages/typert/generator/src/tsdown-plugin.ts
index a5c6ef93e2..10cba60974 100644
--- a/packages/typert/generator/src/tsdown-plugin.ts
+++ b/packages/typert/generator/src/tsdown-plugin.ts
@@ -1,23 +1,27 @@
 /**
- * Optional tsdown (rolldown) plugin face of the typert generator. When added
- * to a workspace tsdown config, it runs after each opted-in package bundle is
- * written and re-emits its model-driven face artifact at the package output
- * root. Packages without a Typert or Remote export are skipped.
+ * Optional tsdown (rolldown) plugin face of the typert generator. It lowers
+ * standard decorators in TypeScript dependencies before bundling, then emits
+ * model-driven face artifacts at the package output root. Packages without a
+ * Typert or Remote export are skipped.
  * @module @deepseek-ai/dsh-typert-generator/tsdown
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
+import ts from 'typescript'
 import { WorkspaceTypertGenerator } from './workspace.ts'
 import type { WorkspaceEmitResult } from './workspace.ts'
 import type { TypertFace } from './model.ts'
 
-/** The subset of the rolldown output-plugin contract this plugin uses (structural; avoids a rolldown type dependency). */
+/** The subset of the rolldown plugin contract used here (structural; avoids a rolldown type dependency). */
 interface TypertPlugin {
   name: string
+  transform: (code: string, id: string) => { code: string; map: string | undefined } | undefined
   writeBundle: (options: { dir?: string }) => void
 }
 
+const DECORATOR_SYNTAX = /^\s*@[A-Za-z_$][\w$]*/m
+
 /** Generation scope selected by a tsdown build phase. */
 export interface TypertPluginOptions {
   /** Package mode emits only the package being bundled; workspace mode emits every explicit contributor once. */
@@ -27,15 +31,32 @@ export interface TypertPluginOptions {
 }
 
 /**
- * Create the typert generation plugin for the root tsdown config.
+ * Create the decorator-lowering and typert-generation plugin for the root tsdown config.
  * @param pluginOptions - package/workspace emission mode and independent program faces.
- * @returns a rolldown-compatible plugin that emits local face and Host-for-Client Remote artifacts.
+ * @returns a rolldown-compatible plugin that lowers source decorators and emits local and Host-for-Client artifacts.
  */
 export function typertPlugin(pluginOptions: TypertPluginOptions = {}): TypertPlugin {
   const artifactsByRoot = new Map<string, readonly WorkspaceEmitResult[]>()
   const emittedWorkspaces = new Set<string>()
   return {
     name: 'dsh-typert-generator',
+    transform(code, id) {
+      const file = id.split('?', 1)[0] ?? id
+      if (!/\.[cm]?tsx?$/.test(file) || !DECORATOR_SYNTAX.test(code)) return
+      const result = ts.transpileModule(code, {
+        fileName: file,
+        compilerOptions: {
+          target: ts.ScriptTarget.ES2024,
+          module: ts.ModuleKind.ESNext,
+          ...(file.endsWith('x') ? { jsx: ts.JsxEmit.ReactJSX } : {}),
+          sourceMap: true,
+        },
+      })
+      return {
+        code: result.outputText.replace(/\n?\/\/# sourceMappingURL=.*$/u, '\n'),
+        map: result.sourceMapText,
+      }
+    },
     writeBundle(bundleOptions) {
       // options.dir is the package's absolute outDir (<package>/lib); its
       // nearest package.json owns the bundle even when a custom config writes
diff --git a/packages/typert/generator/tests/tsdown-plugin.spec.ts b/packages/typert/generator/tests/tsdown-plugin.spec.ts
index 655636aa79..106b8950ff 100644
--- a/packages/typert/generator/tests/tsdown-plugin.spec.ts
+++ b/packages/typert/generator/tests/tsdown-plugin.spec.ts
@@ -64,6 +64,13 @@ afterEach(() => {
 })
 
 describe('typertPlugin', () => {
+  it('lowers standard decorators in TypeScript source dependencies', () => {
+    const plugin = typertPlugin()
+    expect(plugin.transform('export const value = 1\n', '/workspace/src/plain.ts')).toBeUndefined()
+    expect(plugin.transform('@sealed\nexport class Example {}\n', '/workspace/src/example.ts')?.code)
+      .not.toContain('@sealed')
+  })
+
   it('skips outputs that do not identify a Typert contributor', async () => {
     const plugin = typertPlugin()
     expect(plugin.name).toBe('dsh-typert-generator')
diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
index 16160a3860..4973732fad 100644
--- a/packages/typert/registry/src/service.ts
+++ b/packages/typert/registry/src/service.ts
@@ -149,8 +149,10 @@ class DescriptorStore {
     for (const descriptor of descriptors) {
       const endpoint = typertEndpoint(descriptor)
       const entry = this.entries.get(endpoint)
+      /* v8 ignore next -- duplicate registration is rejected, so no later owner can replace this entry before its effect disposes. */
       if (entry?.owner !== owner) continue
       this.entries.delete(endpoint)
+      /* v8 ignore next -- ids and endpoints are committed and withdrawn together under the same unique owner. */
       if (this.ids.get(descriptor.id) === entry) this.ids.delete(descriptor.id)
       removed.push(endpoint)
     }
@@ -200,6 +202,7 @@ class RemoteStore {
       packages.set(contribution.package, owner)
       descriptors.commit(owner, contribution.descriptors)
       yield () => {
+        /* v8 ignore else -- duplicate package registration is rejected, so this effect remains the package's unique owner. */
         if (packages.get(contribution.package) === owner) packages.delete(contribution.package)
         descriptors.withdraw(owner, contribution.descriptors)
       }
@@ -244,6 +247,7 @@ class LookupStore {
       providers.set(key, entry)
       changes.emit({ kind: 'lookup', key })
       yield () => {
+        /* v8 ignore next -- duplicate registration is rejected, so this effect remains the key's unique owner. */
         if (providers.get(key) !== entry) return
         providers.delete(key)
         changes.emit({ kind: 'lookup', key })
@@ -303,6 +307,7 @@ class ContextStore {
       table.set(key, entry)
       changes.emit({ kind, key })
       yield () => {
+        /* v8 ignore next -- duplicate registration is rejected, so this effect remains the key's unique owner. */
         if (table.get(key) !== entry) return
         table.delete(key)
         changes.emit({ kind, key })
@@ -381,8 +386,10 @@ export class TypertRegistry extends Service implements TypeRTService {
       for (const record of schemaRecords) schemas.set(record.key, record)
       localStore.commit(owner, invocations)
       yield () => {
+        /* v8 ignore else -- duplicate package-face registration is rejected, so this effect remains its unique owner. */
         if (packages.get(packageRecord.key) === packageRecord) packages.delete(packageRecord.key)
         for (const record of schemaRecords) {
+          /* v8 ignore else -- duplicate schema registration is rejected, so this contribution remains each record's unique owner. */
           if (schemas.get(record.key) === record) schemas.delete(record.key)
         }
         localStore.withdraw(owner, invocations)
diff --git a/packages/typert/registry/tests/typert.spec.ts b/packages/typert/registry/tests/typert.spec.ts
index a98f99f912..95f8bc871f 100644
--- a/packages/typert/registry/tests/typert.spec.ts
+++ b/packages/typert/registry/tests/typert.spec.ts
@@ -13,6 +13,7 @@ import type {
   TypeRTLookup,
   TypeRTRemoteContribution,
 } from '@deepseek-ai/dsh-type-meta'
+import { apply as applyClientRegistry, inject as clientRegistryInject } from '../src/client/index.ts'
 
 declare module '@deepseek-ai/dsh-type-meta' {
   interface TypeRTLookupMap {
@@ -222,6 +223,29 @@ describe('TypertRegistry', () => {
     expect(changes).toEqual(['local:goals/create', 'local:goals/create'])
   })
 
+  it('rejects duplicate invocation endpoints and ids atomically', async () => {
+    const ctx = await makeCtx()
+    const first = invocation()
+    ctx.typert.register({ ...toolsContribution(), invocations: [first] })
+
+    expect(() => ctx.typert.remotes.register({
+      package: '@fixture/duplicate-endpoint',
+      descriptors: [invocation('@fixture/remote#first'), invocation('@fixture/remote#second')],
+    })).toThrow('endpoint "goals/create" is already registered')
+    expect(() => ctx.typert.remotes.register({
+      package: '@fixture/duplicate-id',
+      descriptors: [
+        invocation('@fixture/remote#same'),
+        { ...invocation('@fixture/remote#same'), method: 'rename' },
+      ],
+    })).toThrow('invocation id "@fixture/remote#same" is already registered')
+    expect(() => ctx.typert.register({
+      ...toolsContribution(),
+      package: '@fixture/existing-endpoint',
+      invocations: [{ ...first, id: '@fixture/local#other' }],
+    })).toThrow('endpoint "goals/create" is already registered')
+  })
+
   it('mounts Remote contributions in the calling fiber and withdraws them exactly', async () => {
     const ctx = await makeCtx()
     const descriptor = invocation()
@@ -314,6 +338,131 @@ describe('TypertRegistry', () => {
     expect(ctx.typert.contexts.getClient('registryFixture')).toBeUndefined()
   })
 
+  it('publishes provider changes, rejects duplicate providers, and disposes subscriptions', async () => {
+    const ctx = await makeCtx()
+    const changes: string[] = []
+    const disposeLookupSubscription = ctx.typert.lookups.subscribe((change) => {
+      changes.push(`${change.kind}:${change.key}`)
+    })
+    const disposeContextSubscription = ctx.typert.contexts.subscribe((change) => {
+      changes.push(`${change.kind}:${change.key}`)
+    })
+    const lookup = {
+      parameter: 'agent',
+      wire: 'agentId',
+      hostTypeSymbol: '@fixture#Agent',
+      wireTypeSymbol: '@fixture#AgentId',
+      resolve: () => undefined,
+    }
+    const host = {
+      wire: 'agentId',
+      wireTypeSymbol: '@fixture#AgentId',
+      resolve: () => undefined,
+    }
+    const client = { identity: () => undefined }
+    const disposeLookup = ctx.typert.lookups.register('fixture', lookup)
+    const disposeHost = ctx.typert.contexts.registerHost('registryFixture', host)
+    const disposeClient = ctx.typert.contexts.registerClient('registryFixture', client)
+
+    expect(() => ctx.typert.lookups.register('fixture', lookup)).toThrow('already registered')
+    expect(() => ctx.typert.contexts.registerHost('registryFixture', host)).toThrow('already registered')
+    expect(() => ctx.typert.contexts.registerClient('registryFixture', client)).toThrow('already registered')
+    await Promise.all([disposeLookup(), disposeHost(), disposeClient()])
+    expect(changes).toEqual([
+      'lookup:fixture',
+      'host-context:registryFixture',
+      'client-context:registryFixture',
+      'lookup:fixture',
+      'host-context:registryFixture',
+      'client-context:registryFixture',
+    ])
+
+    await Promise.all([disposeLookupSubscription(), disposeContextSubscription()])
+    ctx.typert.lookups.register('fixture', lookup)
+    expect(changes).toHaveLength(6)
+  })
+
+  it('validates every invocation and provider boundary', async () => {
+    const ctx = await makeCtx()
+    const strict = {
+      mode: 'strict' as const,
+      typeSymbol: '@fixture#Value',
+      schema: z.string(),
+    }
+    const strictInvocation: InvocationDescriptor = {
+      ...invocation('@fixture/remote#strict'),
+      implementation: 'remoteExportCreate',
+      parameters: [{ name: 'request', wire: 'request', source: 'json', codec: strict }],
+      result: strict,
+    }
+    const dispose = ctx.typert.remotes.register({ package: '@fixture/strict', descriptors: [strictInvocation] })
+    await dispose()
+
+    const malformed: readonly [InvocationDescriptor, string][] = [
+      [{ ...invocation(), id: '' }, 'invocation id'],
+      [{ ...invocation(), namespace: 'bad/name' }, 'namespace'],
+      [{ ...invocation(), implementation: 'bad/name' }, 'implementation method'],
+      [{
+        ...invocation(),
+        parameters: [
+          ...invocation().parameters,
+          { name: 'other', wire: 'request', source: 'json', codec: { mode: 'src-json' } },
+        ],
+      }, 'repeats wire field'],
+      [{
+        ...invocation(),
+        parameters: [{ name: 'agent', wire: 'agentId', source: 'lookup', codec: { mode: 'src-json' } }],
+      }, 'has no lookup key'],
+      [{
+        ...invocation(),
+        parameters: [{
+          name: 'request', wire: 'request', source: 'json', lookup: 'fixture', codec: { mode: 'src-json' },
+        }],
+      }, 'JSON parameter'],
+      [{
+        ...invocation(),
+        invocation: {
+          kind: 'context', context: 'registryFixture', wire: 'request', codec: { mode: 'src-json' },
+        },
+      }, 'repeats wire field'],
+      [{
+        ...invocation(),
+        result: { mode: 'strict', typeSymbol: '', schema: z.string() },
+      }, 'type symbol'],
+      [{
+        ...invocation(),
+        result: { mode: 'strict', typeSymbol: '@fixture#Broken', schema: {} as z.ZodType },
+      }, 'has no parse'],
+    ]
+    for (const [index, [descriptor, message]] of malformed.entries()) {
+      expect(() => ctx.typert.remotes.register({
+        package: `@fixture/malformed-${String(index)}`,
+        descriptors: [descriptor],
+      })).toThrow(message)
+    }
+
+    expect(() => ctx.typert.lookups.register('bad#key' as 'fixture', {
+      parameter: 'agent',
+      wire: 'agent/id',
+      hostTypeSymbol: '',
+      wireTypeSymbol: '',
+      resolve: () => undefined,
+    })).toThrow('lookup key')
+    expect(() => ctx.typert.lookups.register('fixture', {
+      parameter: 'agent',
+      wire: 'agent/id',
+      hostTypeSymbol: '@fixture#Agent',
+      wireTypeSymbol: '@fixture#AgentId',
+      resolve: () => undefined,
+    })).toThrow('lookup wire field')
+  })
+
+  it('installs the registry through the Client entry without importing the Host entry', async () => {
+    const ctx = new Context()
+    await ctx.plugin({ inject: clientRegistryInject, apply: applyClientRegistry })
+    expect(ctx.typert.list()).toEqual([])
+  })
+
   it('contains change-listener failures and still notifies later listeners', async () => {
     const ctx = await makeCtx()
     const warnings: unknown[] = []
diff --git a/packages/typert/type-meta/package.json b/packages/typert/type-meta/package.json
index 2ffcd6c5ed..e2d7689866 100644
--- a/packages/typert/type-meta/package.json
+++ b/packages/typert/type-meta/package.json
@@ -26,9 +26,7 @@
     "lib/index.js",
     "lib/invariant.js",
     "lib/types/**/*.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
diff --git a/packages/typert/type-meta/tests/type-meta.spec.ts b/packages/typert/type-meta/tests/type-meta.spec.ts
index 1eab5a6ca3..f25c367914 100644
--- a/packages/typert/type-meta/tests/type-meta.spec.ts
+++ b/packages/typert/type-meta/tests/type-meta.spec.ts
@@ -107,6 +107,80 @@ describe('type-meta Remote declarations', () => {
     expect(remoteMethods(first)).toEqual([{ method: 'run', invocation: { kind: 'direct' } }])
   })
 
+  it('supports explicit export names without exposing marker storage', () => {
+    class Service {
+      run(value: string): string {
+        return value
+      }
+
+      scoped(value: string): string {
+        return value
+      }
+    }
+    const initializers: Array<(this: Service) => void> = []
+    Remote('execute')(
+      Reflect.get(Service.prototype, 'run') as (this: Service, ...args: unknown[]) => unknown,
+      methodContext('run', initializers),
+    )
+    RemoteContext('metaFixture', 'inspect')(
+      Reflect.get(Service.prototype, 'scoped') as (this: Service, ...args: unknown[]) => unknown,
+      methodContext('scoped', initializers),
+    )
+    const service = new Service()
+    for (const initialize of initializers) initialize.call(service)
+
+    expect(remoteMethods(service)).toEqual([
+      { method: 'run', exportName: 'execute', invocation: { kind: 'direct' } },
+      { method: 'scoped', exportName: 'inspect', invocation: { kind: 'context', context: 'metaFixture' } },
+    ])
+    expect(remoteMethods({})).toEqual([])
+    const prototypeLess: object = {}
+    Reflect.setPrototypeOf(prototypeLess, null)
+    expect(remoteMethods(prototypeLess)).toEqual([])
+  })
+
+  it('rejects malformed decorator calls and targets', () => {
+    const method: (this: object) => void = function (this: object): void {}
+    expect(() => { (Remote as unknown as (value: typeof method) => void)(method) }).toThrow('context is missing')
+    expect(() => Remote('bad/name')).toThrow('export name')
+    expect(() => RemoteContext('' as 'metaFixture')).toThrow('Context key')
+    expect(() => RemoteContext('metaFixture', 'bad/name')).toThrow('export name')
+
+    for (const context of [
+      { ...methodContext('run', []), private: true },
+      { ...methodContext('run', []), static: true },
+      { ...methodContext('run', []), name: Symbol('run') },
+    ]) {
+      expect(() => { Remote(method, context) })
+        .toThrow('public instance method')
+    }
+  })
+
+  it('rejects prototype-less initialization and conflicting markers', () => {
+    const method: (this: object) => void = function (this: object): void {}
+    const direct: Array<(this: object) => void> = []
+    Remote(method, methodContext('run', direct))
+    const prototypeLess: object = {}
+    Reflect.setPrototypeOf(prototypeLess, null)
+    expect(() => { direct[0]!.call(prototypeLess) }).toThrow('without a prototype')
+
+    class Service {
+      run(): void {}
+    }
+    const conflicting: Array<(this: Service) => void> = []
+    Remote(
+      Reflect.get(Service.prototype, 'run'),
+      methodContext('run', conflicting),
+    )
+    RemoteContext('metaFixture')(
+      Reflect.get(Service.prototype, 'run'),
+      methodContext('run', conflicting),
+    )
+    const service = new Service()
+    conflicting[0]!.call(service)
+    expect(() => { conflicting[1]!.call(service) }).toThrow('conflicting invocation markers')
+  })
+
   it('rejects ambiguous binding names', () => {
     expect(() => bindTypeRTGateway({}, '')).toThrow('service key')
     expect(() => bindTypeRTGateway({}, 'goals', { namespace: 'api/goals' })).toThrow('namespace')
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 45e8ad1803..caf1f8a5ba 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -7077,6 +7077,9 @@ importers:
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../packages/core/tools
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../../packages/typert/type-meta
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
         version: link:../../packages/ui/user-approval
diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json
index 4fd7291633..d8151de3a4 100644
--- a/python/sdk-runtime/package.json
+++ b/python/sdk-runtime/package.json
@@ -93,6 +93,7 @@
     "@deepseek-ai/dsh-tool-web": "workspace:^",
     "@deepseek-ai/dsh-tool-workflow": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",
     "@deepseek-ai/dsh-web": "workspace:^",
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index e0b9344cdf..9be97f53e6 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -7,7 +7,7 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join, relative, resolve } from 'node:path'
-import { isForbiddenPublicationFile } from './publication-payload.ts'
+import { hasTypeRTRemoteNavigation, isForbiddenPublicationFile } from './publication-payload.ts'
 
 const root = resolve(import.meta.dirname, '..')
 // vendor/* is single-level; packages/<group>/<pkg> nests one level deeper
@@ -122,6 +122,7 @@ function sameStringList(actual: readonly string[] | undefined, expected: readonl
 
 function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
   const extras = manifest.name ? packageFileExtras[manifest.name] ?? [] : []
+  const typeRTRemoteNavigation = hasTypeRTRemoteNavigation(manifest)
   return [
     'lib/index.js',
     // Every package publishes its invariant ownership companion as a separate
@@ -145,9 +146,37 @@ function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
     // declarations.
     ...usesEmittedTreeDefaults(manifest) ? ['lib/types/**/*.js'] : [],
     'lib/types/**/*.d.ts',
+    ...hasExportPair(manifest, './typert', './lib/typert.host.d.ts', './lib/typert.host.js')
+      ? ['lib/typert.host.js', 'lib/typert.host.d.ts']
+      : [],
+    ...hasExportPair(manifest, './client/typert', './lib/typert.client.d.ts', './lib/typert.client.js')
+      ? ['lib/typert.client.js', 'lib/typert.client.d.ts']
+      : [],
+    ...typeRTRemoteNavigation
+      ? [
+        'lib/typert.remote-client.js',
+        'lib/typert.remote-client.d.ts',
+        'lib/typert.remote-client.d.ts.map',
+        'src',
+      ]
+      : [],
   ]
 }
 
+/** Whether one conditional export exactly names the generated runtime and declaration pair. */
+function hasExportPair(
+  manifest: PackageManifest,
+  subpath: string,
+  types: string,
+  runtime: string,
+): boolean {
+  const entry = manifest.exports?.[subpath]
+  return typeof entry === 'object'
+    && entry !== null
+    && entry.types === types
+    && entry.default === runtime
+}
+
 /** Runtime target of an export entry: conditional `default`, or the bare-string shorthand. */
 function exportDefault(manifest: PackageManifest, subpath: string): string | undefined {
   const entry = manifest.exports?.[subpath]
@@ -175,8 +204,9 @@ function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
   }
 
   if (manifest.name?.startsWith('@deepseek-ai/')) {
+    const publicationPolicy = { typeRTRemoteNavigation: hasTypeRTRemoteNavigation(manifest) }
     for (const file of manifest.files ?? []) {
-      if (isForbiddenPublicationFile(file)) {
+      if (isForbiddenPublicationFile(file, publicationPolicy)) {
         errors.push(`${label}: package.json files must not publish ${JSON.stringify(file)}`)
       }
     }
diff --git a/scripts/dev-web.spec.ts b/scripts/dev-web.spec.ts
index 2edbc652ab..71576caf9e 100644
--- a/scripts/dev-web.spec.ts
+++ b/scripts/dev-web.spec.ts
@@ -22,13 +22,7 @@ export default defineConfig({
     const bundlePath = join(root, 'lib/client.js')
     await writeFile(sourcePath, 'export const version = "watch-v1"\n')
     bundles = await watchClientPlugins(root, ['.'], 50)
-    await expect.poll(async () => {
-      try {
-        return (await readFile(bundlePath, 'utf8')).includes('watch-v1')
-      } catch {
-        return false
-      }
-    }, { timeout: 10_000 }).toBe(true)
+    expect(await readFile(bundlePath, 'utf8')).toContain('watch-v1')
 
     await new Promise(resolve => setTimeout(resolve, 1_000))
     await writeFile(sourcePath, `export const version = "watch-v2-${'x'.repeat(100)}"\n`)
diff --git a/scripts/dev-web.ts b/scripts/dev-web.ts
index aee7146487..294e38002b 100644
--- a/scripts/dev-web.ts
+++ b/scripts/dev-web.ts
@@ -47,21 +47,40 @@ export function discoverPluginDirs(root = repoRoot): string[] {
  * @param root - repository or fixture root passed to tsdown.
  * @param pluginDirs - workspace-relative package directories to watch.
  * @param pollInterval - optional source-watcher polling interval in milliseconds.
- * @returns live bundles whose async disposers stop every watcher.
+ * @returns live bundles after every watcher has completed its initial build.
  */
 export async function watchClientPlugins(
   root: string,
   pluginDirs: readonly string[],
   pollInterval?: number,
 ): Promise<TsdownBundle[]> {
-  return build({
+  let resolveInitialBuilds: (() => void) | undefined
+  const initialBuilds = new Promise<void>((resolve) => { resolveInitialBuilds = resolve })
+  const initialized = new WeakSet<object>()
+  const readiness: { expectedBuilds?: number; initializedBuilds: number } = { initializedBuilds: 0 }
+  const bundles = await build({
     cwd: root,
     workspace: [...pluginDirs],
     watch: true,
+    hooks: {
+      'build:done': ({ options }) => {
+        if (initialized.has(options)) return
+        initialized.add(options)
+        readiness.initializedBuilds += 1
+        if (
+          readiness.expectedBuilds !== undefined
+          && readiness.initializedBuilds >= readiness.expectedBuilds
+        ) resolveInitialBuilds?.()
+      },
+    },
     ...pollInterval !== undefined
       ? { inputOptions: { watch: { watcher: { usePolling: true, pollInterval } } } }
       : {},
   })
+  readiness.expectedBuilds = bundles.length
+  if (readiness.initializedBuilds >= readiness.expectedBuilds) resolveInitialBuilds?.()
+  await initialBuilds
+  return bundles
 }
 
 const invokedPath = process.argv[1]
diff --git a/scripts/publication-payload.spec.ts b/scripts/publication-payload.spec.ts
index 0f403bee7c..03603ef54d 100644
--- a/scripts/publication-payload.spec.ts
+++ b/scripts/publication-payload.spec.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest'
-import { isForbiddenPublicationFile, validateTarballPayload } from './publication-payload.ts'
+import {
+  hasTypeRTRemoteNavigation,
+  isForbiddenPublicationFile,
+  validateTarballPayload,
+} from './publication-payload.ts'
 
 function validateFixtureTarball(files: readonly string[]): () => void {
   return () => {
@@ -51,4 +55,29 @@ describe('publication payload policy', () => {
       'package/lib/styles/base.css',
     ])).not.toThrow()
   })
+
+  it('allows only the TypeRT declaration map and its navigable source tree when requested', () => {
+    const policy = { typeRTRemoteNavigation: true }
+    expect(isForbiddenPublicationFile('src/index.ts', policy)).toBe(false)
+    expect(isForbiddenPublicationFile('lib/typert.remote-client.d.ts.map', policy)).toBe(false)
+    expect(isForbiddenPublicationFile('lib/types/index.d.ts.map', policy)).toBe(true)
+    expect(() => {
+      validateTarballPayload([
+        'package/lib/typert.remote-client.d.ts.map',
+        'package/src/index.ts',
+      ], 'fixture.tgz', policy)
+    }).not.toThrow()
+  })
+
+  it('recognizes only the canonical Host-for-Client export pair', () => {
+    expect(hasTypeRTRemoteNavigation({
+      exports: {
+        './remote': {
+          types: './lib/typert.remote-client.d.ts',
+          default: './lib/typert.remote-client.js',
+        },
+      },
+    })).toBe(true)
+    expect(hasTypeRTRemoteNavigation({ exports: { './remote': './lib/remote.js' } })).toBe(false)
+  })
 })
diff --git a/scripts/publication-payload.ts b/scripts/publication-payload.ts
index 9c16067fe7..60f37b4f94 100644
--- a/scripts/publication-payload.ts
+++ b/scripts/publication-payload.ts
@@ -1,5 +1,22 @@
 /** Publication payload policy shared by static manifests and packed tarballs. */
 
+/** Publication exceptions required for TypeRT declaration-map navigation. */
+export interface PublicationPayloadPolicy {
+  readonly typeRTRemoteNavigation?: boolean
+}
+
+/** Whether a package manifest exports generated Host-for-Client metadata with source navigation. */
+export function hasTypeRTRemoteNavigation(manifest: unknown): boolean {
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) return false
+  const exportsField = (manifest as Record<string, unknown>).exports
+  if (exportsField === null || typeof exportsField !== 'object' || Array.isArray(exportsField)) return false
+  const remote = (exportsField as Record<string, unknown>)['./remote']
+  if (remote === null || typeof remote !== 'object' || Array.isArray(remote)) return false
+  const entry = remote as Record<string, unknown>
+  return entry.types === './lib/typert.remote-client.d.ts'
+    && entry.default === './lib/typert.remote-client.js'
+}
+
 /** Normalize a package manifest path or npm tarball member to its payload-relative path. */
 function payloadPath(file: string): string {
   const normalized = file.replaceAll('\\', '/').replace(/^\.\/+/, '').replace(/\/+$/, '')
@@ -7,17 +24,30 @@ function payloadPath(file: string): string {
 }
 
 /** Whether a package payload path exposes source or declaration-map intermediates. */
-export function isForbiddenPublicationFile(file: string): boolean {
+export function isForbiddenPublicationFile(
+  file: string,
+  policy: PublicationPayloadPolicy = {},
+): boolean {
   const normalized = payloadPath(file)
+  if (policy.typeRTRemoteNavigation === true
+    && (normalized === 'src'
+      || normalized.startsWith('src/')
+      || normalized === 'lib/typert.remote-client.d.ts.map')) {
+    return false
+  }
   return normalized === 'src'
     || normalized.startsWith('src/')
     || normalized.endsWith('.d.ts.map')
 }
 
 /** Reject source and declaration-map members in a packed npm tarball. */
-export function validateTarballPayload(files: readonly string[], context: string): void {
+export function validateTarballPayload(
+  files: readonly string[],
+  context: string,
+  policy: PublicationPayloadPolicy = {},
+): void {
   for (const file of files) {
-    if (!isForbiddenPublicationFile(file)) continue
+    if (!isForbiddenPublicationFile(file, policy)) continue
     const normalized = payloadPath(file)
     if (normalized === 'src' || normalized.startsWith('src/')) {
       throw new Error(`${context} publishes source file ${file}`)
diff --git a/scripts/publish-npm-baseline.ts b/scripts/publish-npm-baseline.ts
index 20b9eeaea0..4a33f32e1e 100644
--- a/scripts/publish-npm-baseline.ts
+++ b/scripts/publish-npm-baseline.ts
@@ -18,7 +18,7 @@ import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep
 import { createInterface } from 'node:readline/promises'
 import { pathToFileURL } from 'node:url'
 import { parseArgs } from 'node:util'
-import { validateTarballPayload } from './publication-payload.ts'
+import { hasTypeRTRemoteNavigation, validateTarballPayload } from './publication-payload.ts'
 
 const DEFAULT_REGISTRY = 'https://registry.npm.harnessment.com'
 const DEFAULT_OUTPUT_DIRECTORY = '.artifacts/npm-baseline'
@@ -320,7 +320,11 @@ class ReleaseBundle {
         if (expected === undefined || !missingNames.delete(artifact.name)) {
           throw new Error(`unexpected or duplicate packed package: ${artifact.name}`)
         }
-        if (expected.origin === 'harness') validateTarballPayload(artifact.files, tarball)
+        if (expected.origin === 'harness') {
+          validateTarballPayload(artifact.files, tarball, {
+            typeRTRemoteNavigation: hasTypeRTRemoteNavigation(artifact.manifest),
+          })
+        }
         if (artifact.version !== version) {
           throw new Error(`${tarball} has version ${artifact.version}; expected ${version}`)
         }
@@ -394,7 +398,11 @@ class ReleaseBundle {
         throw new Error(`tarball checksum mismatch: ${pkg.tarball}`)
       }
       const artifact = inspectTarball(path, runner)
-      if (pkg.origin === 'harness') validateTarballPayload(artifact.files, pkg.tarball)
+      if (pkg.origin === 'harness') {
+        validateTarballPayload(artifact.files, pkg.tarball, {
+          typeRTRemoteNavigation: hasTypeRTRemoteNavigation(artifact.manifest),
+        })
+      }
       if (artifact.name !== pkg.name || artifact.version !== this.manifest.version) {
         throw new Error(`tarball identity mismatch: ${pkg.tarball}`)
       }

From 41677c3be00557a2a741e03bbf6419956ca0c68e Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 06:02:12 +0800
Subject: [PATCH 118/516] fix(ci): preserve TypeRT contract build order on
 Windows

---
 scripts/wine-windows-gates.sh | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
index 7706a88a4b..1f5de1dcbd 100755
--- a/scripts/wine-windows-gates.sh
+++ b/scripts/wine-windows-gates.sh
@@ -204,11 +204,14 @@ cat "$scratch/logs/smoke.log"
 grep -q '^smoke: win32 x64' "$scratch/logs/smoke.log" || { echo 'wine-windows-gates: Windows Node smoke did not report win32 x64' >&2; exit 1; }
 
 # ---- the two blocking surfaces, concurrently ------------------------------
-# The same shape run-gates gives ci-windows-blocking on native Windows:
-# `build` = tsc -b then tsdown, `production site` = the VitePress build. Both
-# statuses are captured so one failure cannot hide the other's result.
+# The build preserves the face order from package.json: generate Host contracts
+# before either aggregate typecheck, then bundle the completed workspace.
+# Both statuses are captured so one failure cannot hide the other's result.
 build_gate() {
-  wine_node "$scratch/logs/tsc.log" "$tsc_js" -b --pretty false || return $?
+  wine_node "$scratch/logs/contracts-tsc.log" "$tsc_js" -b packages/typert/generator --pretty false || return $?
+  wine_node "$scratch/logs/contracts-tsdown.log" "$tsdown_js" --config tsdown.typert-host.config.ts || return $?
+  wine_node "$scratch/logs/host-tsc.log" "$tsc_js" -b tsconfig.host.json --pretty false || return $?
+  wine_node "$scratch/logs/client-tsc.log" "$tsc_js" -b tsconfig.client.json --pretty false || return $?
   wine_node "$scratch/logs/tsdown.log" "$tsdown_js"
 }
 site_gate() {
@@ -235,7 +238,12 @@ report() {
     for log in "$@"; do tail -n 200 "$log" >&2 || true; done
   fi
 }
-report 'build (tsc -b, tsdown)' "$build_status" "$scratch/logs/tsc.log" "$scratch/logs/tsdown.log"
+report 'build (contract prepass, tsc, tsdown)' "$build_status" \
+  "$scratch/logs/contracts-tsc.log" \
+  "$scratch/logs/contracts-tsdown.log" \
+  "$scratch/logs/host-tsc.log" \
+  "$scratch/logs/client-tsc.log" \
+  "$scratch/logs/tsdown.log"
 report 'production site (vitepress build)' "$site_status" "$scratch/logs/site.log"
 if (( build_status != 0 )); then exit "$build_status"; fi
 exit "$site_status"

From 61c2c15dc46187ec44a8737781e38e656233352c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 5 Aug 2026 13:02:10 +0800
Subject: [PATCH 119/516] refactor(goal): own direct goal operations

---
 packages/goal/goal/src/domain.ts | 29 +------------
 packages/goal/goal/src/index.ts  | 71 ++++++++++++++++++++++++++++++--
 packages/goal/goal/src/types.ts  | 32 ++++++++++++++
 3 files changed, 100 insertions(+), 32 deletions(-)

diff --git a/packages/goal/goal/src/domain.ts b/packages/goal/goal/src/domain.ts
index fec44de2f3..8c8c4de6b6 100644
--- a/packages/goal/goal/src/domain.ts
+++ b/packages/goal/goal/src/domain.ts
@@ -8,22 +8,7 @@
  */
 
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { GoalId, GoalRef, GoalSnapshot } from './types.ts'
-
-/** Whether this live process may automatically continue an active goal. */
-export type GoalActivation = 'armed' | 'disarmed'
-
-/** Current goal projection, including values derived from the session log. */
-export interface GoalView extends GoalSnapshot {
-  /** Highest admitted round number for this goal. */
-  readonly roundsStarted: number
-  /** Epoch milliseconds of the create mutation. */
-  readonly createdAt: number
-  /** Epoch milliseconds of the latest mutation. */
-  readonly updatedAt: number
-  /** Process-local continuation eligibility; never persisted. */
-  readonly activation: GoalActivation
-}
+import type { GoalId, GoalRef, GoalSnapshot, GoalView } from './types.ts'
 
 /** Goal state-changing verbs recorded in the durable source change. */
 export type GoalOperation =
@@ -96,18 +81,6 @@ export interface FoldedGoal {
   readonly lastRef?: GoalRef
 }
 
-/** Input whose omitted round cap is resolved by the service configuration. */
-export interface CreateGoalRequest {
-  readonly objective: string
-  readonly maxGoalRounds?: number
-}
-
-/** Fields changed by an edit; at least one must be present. */
-export interface EditGoalRequest {
-  readonly objective?: string
-  readonly maxGoalRounds?: number
-}
-
 /** Live notification after one durable goal mutation commits. */
 export interface GoalChanged {
   readonly operation: GoalOperation
diff --git a/packages/goal/goal/src/index.ts b/packages/goal/goal/src/index.ts
index 1cd3c6074a..87ea52018e 100644
--- a/packages/goal/goal/src/index.ts
+++ b/packages/goal/goal/src/index.ts
@@ -27,22 +27,23 @@ import {
   GoalId,
 } from './runtime.ts'
 import type {
+  CreateGoalRequest,
+  CreateGoalResult,
+  EditGoalRequest,
+  GoalActivation,
   GoalBlockReason,
   GoalPhase,
   GoalProjection,
   GoalRef,
   GoalSnapshot,
+  GoalView,
 } from './types.ts'
 import type {
-  CreateGoalRequest,
-  EditGoalRequest,
-  GoalActivation,
   GoalChangeMeta,
   GoalChanged,
   GoalClearChangeMeta,
   GoalOperation,
   GoalSnapshotChangeMeta,
-  GoalView,
 } from './domain.ts'
 
 // The pure payload outlet (./types.ts, ONE home of the `goal` projection-key
@@ -568,6 +569,68 @@ export class GoalService extends Service {
       activation: cache.activation,
     }
   }
+
+  /**
+   * Create one Goal through the remote boundary.
+   * @param agent - exact live Agent resolved from the wire identity.
+   * @param request - objective and optional round cap.
+   * @returns the created Goal identity.
+   */
+  remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
+    const view = this.create(agent, request)
+    return { ref: { id: view.id, revision: view.revision } }
+  }
+
+  /**
+   * Edit one Goal through the remote boundary.
+   * @param agent - exact live Agent resolved from the wire identity.
+   * @param ref - expected current revision.
+   * @param request - replacement fields.
+   * @returns the edited Goal view.
+   */
+  remoteExportEdit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView {
+    return this.edit(agent, ref, request)
+  }
+
+  /**
+   * Pause one Goal through the remote boundary.
+   * @param agent - exact live Agent resolved from the wire identity.
+   * @param ref - expected current revision.
+   * @returns the paused Goal view.
+   */
+  remoteExportPause(agent: Agent, ref: GoalRef): GoalView {
+    return this.pause(agent, ref)
+  }
+
+  /**
+   * Resume one Goal through the remote boundary.
+   * @param agent - exact live Agent resolved from the wire identity.
+   * @param ref - expected current revision.
+   * @returns the resumed Goal view.
+   */
+  remoteExportResume(agent: Agent, ref: GoalRef): GoalView {
+    return this.resume(agent, ref)
+  }
+
+  /**
+   * Complete one Goal through the remote boundary.
+   * @param agent - exact live Agent resolved from the wire identity.
+   * @param ref - expected current revision.
+   * @returns the completed Goal view.
+   */
+  remoteExportComplete(agent: Agent, ref: GoalRef): GoalView {
+    return this.complete(agent, ref)
+  }
+
+  /**
+   * Clear one terminal Goal through the remote boundary.
+   * @param agent - exact live Agent resolved from the wire identity.
+   * @param ref - expected current revision.
+   * @returns the committed clear revision.
+   */
+  remoteExportClear(agent: Agent, ref: GoalRef): GoalRef {
+    return this.clear(agent, ref)
+  }
 }
 
 export default GoalService
diff --git a/packages/goal/goal/src/types.ts b/packages/goal/goal/src/types.ts
index 25e22bd5b2..f277e8620c 100644
--- a/packages/goal/goal/src/types.ts
+++ b/packages/goal/goal/src/types.ts
@@ -23,6 +23,23 @@ export interface GoalRef {
   readonly revision: number
 }
 
+/** Input whose omitted round cap is resolved by the service configuration. */
+export interface CreateGoalRequest {
+  readonly objective: string
+  readonly maxGoalRounds?: number
+}
+
+/** Wire-safe acknowledgement of one created goal. */
+export interface CreateGoalResult {
+  readonly ref: GoalRef
+}
+
+/** Fields changed by an edit; at least one must be present. */
+export interface EditGoalRequest {
+  readonly objective?: string
+  readonly maxGoalRounds?: number
+}
+
 /** Durable continuation phase. Activation is process-local and separate. */
 export type GoalPhase =
   | 'active'
@@ -50,6 +67,21 @@ export interface GoalSnapshot extends GoalRef {
   readonly maxGoalRounds: number
 }
 
+/** Whether this live process may automatically continue an active goal. */
+export type GoalActivation = 'armed' | 'disarmed'
+
+/** Current goal projection, including values derived from the session log. */
+export interface GoalView extends GoalSnapshot {
+  /** Highest admitted round number for this goal. */
+  readonly roundsStarted: number
+  /** Epoch milliseconds of the create mutation. */
+  readonly createdAt: number
+  /** Epoch milliseconds of the latest mutation. */
+  readonly updatedAt: number
+  /** Process-local continuation eligibility; never persisted. */
+  readonly activation: GoalActivation
+}
+
 /**
  * The `goal` projection value: the current durable goal with its replay
  * counters, exactly as the latest `goal/change` event carried them.

From 9400926bdfe8320726e64664a36a3cbde6b21b59 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 15:28:54 +0800
Subject: [PATCH 120/516] feat(goal): add TypeRT gateway example

---
 docs/config-catalog.md                        |   3 +-
 docs/cordis-catalog/events.md                 |   2 +-
 docs/cordis-catalog/services.md               |  53 ++-
 docs/event-producer-consumer.md               |   2 +-
 docs/module-graph.md                          | 312 +++++++++++-------
 docs/persistence-catalog.md                   |   2 +-
 knip.json                                     |   9 +
 packages/bundle/web-app/cordis.patch.yml      |   3 +
 packages/bundle/web-app/package.json          |   1 +
 packages/client/remotes/README.i18n.yaml      |   6 +
 packages/client/remotes/README.md             |  22 ++
 packages/client/remotes/README.zh.md          |  22 ++
 packages/client/remotes/package.json          |  55 +++
 packages/client/remotes/src/client/index.ts   |  19 ++
 packages/client/remotes/src/index.ts          |   4 +
 packages/client/remotes/src/invariant.ts      |  24 ++
 .../client/remotes/tests/built-lib.e2e.ts     | 214 ++++++++++++
 packages/client/remotes/tsconfig.json         |  30 ++
 packages/client/remotes/tsdown.config.ts      |   3 +
 packages/client/runtime/package.json          |  10 +-
 .../client/runtime/src/client/agents/scope.ts |  18 +-
 .../runtime/src/client/contract/sessions.ts   |   6 +-
 packages/client/runtime/src/client/index.ts   |  18 +-
 .../runtime/src/client/sessions/service.ts    |   8 +-
 .../client/runtime/tests/client-apply.spec.ts |   3 +
 packages/client/runtime/tsconfig.json         |   9 +
 packages/client/test-runtime/src/sessions.ts  |   8 +-
 .../cordis/tool-cordis/src/api-catalog.ts     |  28 ++
 packages/goal/goal/package.json               |  18 +-
 packages/goal/goal/src/index.ts               |  10 +
 packages/goal/goal/tsconfig.json              |   3 +
 pnpm-lock.yaml                                |  30 ++
 scripts/gen-cordis-catalog.ts                 |   1 +
 scripts/type-equiv.manifest.json              |   6 +-
 .../verify-package-readme-model-experience.ts |   1 +
 tsconfig.client.json                          |   1 +
 36 files changed, 809 insertions(+), 155 deletions(-)
 create mode 100644 packages/client/remotes/README.i18n.yaml
 create mode 100644 packages/client/remotes/README.md
 create mode 100644 packages/client/remotes/README.zh.md
 create mode 100644 packages/client/remotes/package.json
 create mode 100644 packages/client/remotes/src/client/index.ts
 create mode 100644 packages/client/remotes/src/index.ts
 create mode 100644 packages/client/remotes/src/invariant.ts
 create mode 100644 packages/client/remotes/tests/built-lib.e2e.ts
 create mode 100644 packages/client/remotes/tsconfig.json
 create mode 100644 packages/client/remotes/tsdown.config.ts

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 5728ac4bed..08f26479ca 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -495,7 +495,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/goal/goal/src/index.ts:114`](../packages/goal/goal/src/index.ts)
+Source: [`packages/goal/goal/src/index.ts:116`](../packages/goal/goal/src/index.ts)
 
 ## `@deepseek-ai/dsh-headless`
 
@@ -2522,6 +2522,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-agent` ([`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts))
 - `@deepseek-ai/dsh-client-locale` ([`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts))
 - `@deepseek-ai/dsh-client-modules` — requires `httpServer` · `loader` ([`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts))
+- `@deepseek-ai/dsh-client-remotes` ([`packages/client/remotes/src/index.ts`](../packages/client/remotes/src/index.ts))
 - `@deepseek-ai/dsh-client-runtime` ([`packages/client/runtime/src/index.ts`](../packages/client/runtime/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-command` ([`packages/client/ui-command/src/index.ts`](../packages/client/ui-command/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-conversation` ([`packages/client/ui-conversation/src/index.ts`](../packages/client/ui-conversation/src/index.ts))
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 348d334e9f..4ad9797262 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -472,7 +472,7 @@ Goal mutation accepted by one live agent. The matching `goal/change` session eve
 
 Types: [Agent](../core-data-structures/core.md) · [GoalChanged](../core-data-structures/goal.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/goal/goal/src/domain.ts:141`](../../packages/goal/goal/src/domain.ts)
+Source: [`packages/goal/goal/src/domain.ts:114`](../../packages/goal/goal/src/domain.ts)
 
 ## `llm/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 41059aebf4..9f5e66ea36 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -761,11 +761,60 @@ block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
  * @returns the tombstone ref whose revision is one past the cleared snapshot.
  */
 clear(agent: Agent, ref: GoalRef): GoalRef
+
+/**
+ * Create one Goal through the remote boundary.
+ * @param agent - exact live Agent resolved from the wire identity.
+ * @param request - objective and optional round cap.
+ * @returns the created Goal identity.
+ */
+@Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
+
+/**
+ * Edit one Goal through the remote boundary.
+ * @param agent - exact live Agent resolved from the wire identity.
+ * @param ref - expected current revision.
+ * @param request - replacement fields.
+ * @returns the edited Goal view.
+ */
+@Remote('edit') remoteExportEdit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
+
+/**
+ * Pause one Goal through the remote boundary.
+ * @param agent - exact live Agent resolved from the wire identity.
+ * @param ref - expected current revision.
+ * @returns the paused Goal view.
+ */
+@Remote('pause') remoteExportPause(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Resume one Goal through the remote boundary.
+ * @param agent - exact live Agent resolved from the wire identity.
+ * @param ref - expected current revision.
+ * @returns the resumed Goal view.
+ */
+@Remote('resume') remoteExportResume(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Complete one Goal through the remote boundary.
+ * @param agent - exact live Agent resolved from the wire identity.
+ * @param ref - expected current revision.
+ * @returns the completed Goal view.
+ */
+@Remote('complete') remoteExportComplete(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Clear one terminal Goal through the remote boundary.
+ * @param agent - exact live Agent resolved from the wire identity.
+ * @param ref - expected current revision.
+ * @returns the committed clear revision.
+ */
+@Remote('clear') remoteExportClear(agent: Agent, ref: GoalRef): GoalRef
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [CreateGoalRequest](../core-data-structures/goal.md) · [EditGoalRequest](../core-data-structures/goal.md) · [GoalBlockReason](../core-data-structures/goal.md) · [GoalRef](../core-data-structures/goal.md) · [GoalView](../core-data-structures/goal.md)
+Types: [Agent](../core-data-structures/core.md) · [CreateGoalRequest](../core-data-structures/goal.md) · [CreateGoalResult](../core-data-structures/goal.md) · [EditGoalRequest](../core-data-structures/goal.md) · [GoalBlockReason](../core-data-structures/goal.md) · [GoalRef](../core-data-structures/goal.md) · [GoalView](../core-data-structures/goal.md)
 
-Source: [`packages/goal/goal/src/index.ts:181`](../../packages/goal/goal/src/index.ts)
+Source: [`packages/goal/goal/src/index.ts:183`](../../packages/goal/goal/src/index.ts)
 
 ## `ctx.httpServer` — `HttpServerService`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 286c0ee4c2..f5b3a0b99a 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -27,7 +27,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:62`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
-| `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:141`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:73`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index fd9ac036a0..f659e61206 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -156,6 +156,7 @@ flowchart TD
     pkg_client_hmr["client-hmr"]
     pkg_client_locale["client-locale"]
     pkg_client_modules["client-modules"]
+    pkg_client_remotes["client-remotes"]
     pkg_client_runtime["client-runtime"]
     pkg_client_schema_form["client-schema-form"]
     pkg_client_test_runtime["client-test-runtime"]
@@ -300,7 +301,6 @@ flowchart TD
   pkg_loader_smoke --> pkg_invariants
   pkg_base --> pkg_invariants
   pkg_client_modules --> pkg_invariants
-  pkg_client_runtime --> pkg_invariants
   pkg_client_schema_form --> pkg_invariants
   pkg_client_ui_primitives --> pkg_invariants
   pkg_client_ui_slots --> pkg_invariants
@@ -324,22 +324,6 @@ flowchart TD
   pkg_client_hmr --> pkg_client_modules
   pkg_client_hmr --> pkg_host_webserver
   pkg_client_hmr --> pkg_invariants
-  pkg_client_locale --> pkg_client_runtime
-  pkg_client_locale --> pkg_client_ui_primitives
-  pkg_client_locale --> pkg_client_ui_slots
-  pkg_client_locale --> pkg_invariants
-  pkg_client_test_runtime --> pkg_client_runtime
-  pkg_client_test_runtime --> pkg_client_ui_slots
-  pkg_client_test_runtime --> pkg_client_web_react
-  pkg_client_test_runtime --> pkg_host_apiproxy
-  pkg_client_test_runtime --> pkg_invariants
-  pkg_client_ui_settings --> pkg_client_runtime
-  pkg_client_ui_settings --> pkg_client_ui_primitives
-  pkg_client_ui_settings --> pkg_client_ui_slots
-  pkg_client_ui_settings --> pkg_invariants
-  pkg_client_ui_trajectory --> pkg_client_runtime
-  pkg_client_ui_trajectory --> pkg_client_ui_primitives
-  pkg_client_ui_trajectory --> pkg_invariants
   pkg_credentials --> pkg_brand
   pkg_credentials --> pkg_invariants
   pkg_frontend_static --> pkg_host_webserver
@@ -383,43 +367,6 @@ flowchart TD
   pkg_system_prompt --> pkg_scope
   pkg_web --> pkg_invariants
   pkg_web --> pkg_llm
-  pkg_client_ui_models --> pkg_client_connection
-  pkg_client_ui_models --> pkg_client_runtime
-  pkg_client_ui_models --> pkg_client_schema_form
-  pkg_client_ui_models --> pkg_client_ui_primitives
-  pkg_client_ui_models --> pkg_client_ui_slots
-  pkg_client_ui_models --> pkg_client_web_react
-  pkg_client_ui_models --> pkg_invariants
-  pkg_client_ui_question --> pkg_client_locale
-  pkg_client_ui_question --> pkg_invariants
-  pkg_client_ui_settings_general --> pkg_client_connection
-  pkg_client_ui_settings_general --> pkg_client_locale
-  pkg_client_ui_settings_general --> pkg_client_runtime
-  pkg_client_ui_settings_general --> pkg_client_ui_primitives
-  pkg_client_ui_settings_general --> pkg_client_ui_settings
-  pkg_client_ui_settings_general --> pkg_client_ui_slots
-  pkg_client_ui_settings_general --> pkg_client_web_react
-  pkg_client_ui_settings_general --> pkg_invariants
-  pkg_client_ui_sidebar --> pkg_client_locale
-  pkg_client_ui_sidebar --> pkg_client_runtime
-  pkg_client_ui_sidebar --> pkg_client_ui_primitives
-  pkg_client_ui_sidebar --> pkg_client_ui_slots
-  pkg_client_ui_sidebar --> pkg_invariants
-  pkg_client_ui_slash --> pkg_client_locale
-  pkg_client_ui_slash --> pkg_client_runtime
-  pkg_client_ui_slash --> pkg_client_ui_primitives
-  pkg_client_ui_slash --> pkg_client_ui_slots
-  pkg_client_ui_slash --> pkg_invariants
-  pkg_client_ui_theme --> pkg_client_locale
-  pkg_client_ui_theme --> pkg_client_runtime
-  pkg_client_ui_theme --> pkg_client_ui_primitives
-  pkg_client_ui_theme --> pkg_client_ui_slots
-  pkg_client_ui_theme --> pkg_invariants
-  pkg_client_ui_workspace --> pkg_client_locale
-  pkg_client_ui_workspace --> pkg_client_runtime
-  pkg_client_ui_workspace --> pkg_client_ui_primitives
-  pkg_client_ui_workspace --> pkg_client_ui_slots
-  pkg_client_ui_workspace --> pkg_invariants
   pkg_credentials_local --> pkg_atomic_write
   pkg_credentials_local --> pkg_credentials
   pkg_credentials_local --> pkg_invariants
@@ -472,24 +419,17 @@ flowchart TD
   pkg_app_boot --> pkg_invariants
   pkg_app_boot --> pkg_paths
   pkg_app_boot --> pkg_system_prompt
+<<<<<<< HEAD
   pkg_client_ui_layout --> pkg_client_runtime
   pkg_client_ui_layout --> pkg_client_ui_slots
   pkg_client_ui_layout --> pkg_client_ui_theme
   pkg_client_ui_layout --> pkg_invariants
+=======
+>>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
   pkg_code_runtime_worker --> pkg_code_runtime
   pkg_code_runtime_worker --> pkg_invariants
   pkg_code_runtime_worker --> pkg_session
   pkg_code_runtime_worker --> pkg_timeout
-  pkg_host_directory_picker_browse --> pkg_client_locale
-  pkg_host_directory_picker_browse --> pkg_client_runtime
-  pkg_host_directory_picker_browse --> pkg_client_ui_primitives
-  pkg_host_directory_picker_browse --> pkg_client_ui_slots
-  pkg_host_directory_picker_browse --> pkg_client_ui_workspace
-  pkg_host_directory_picker_browse --> pkg_invariants
-  pkg_host_directory_picker_native --> pkg_client_runtime
-  pkg_host_directory_picker_native --> pkg_client_ui_slots
-  pkg_host_directory_picker_native --> pkg_client_ui_workspace
-  pkg_host_directory_picker_native --> pkg_invariants
   pkg_lsp_local --> pkg_brand
   pkg_lsp_local --> pkg_invariants
   pkg_lsp_local --> pkg_llm
@@ -518,6 +458,7 @@ flowchart TD
   pkg_goal --> pkg_scope
   pkg_goal --> pkg_session
   pkg_goal --> pkg_session_projection
+  pkg_goal --> pkg_type_meta
   pkg_bash_local --> pkg_bash
   pkg_bash_local --> pkg_invariants
   pkg_bash_local --> pkg_subprocess
@@ -582,10 +523,6 @@ flowchart TD
   pkg_tmux_context --> pkg_bash
   pkg_tmux_context --> pkg_invariants
   pkg_tmux_context --> pkg_session
-  pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse
-  pkg_host_directory_picker_auto --> pkg_host_directory_picker_native
-  pkg_host_directory_picker_auto --> pkg_host_webserver
-  pkg_host_directory_picker_auto --> pkg_invariants
   pkg_pty --> pkg_agent
   pkg_pty --> pkg_brand
   pkg_pty --> pkg_invariants
@@ -677,6 +614,7 @@ flowchart TD
   pkg_permission --> pkg_session_projection
   pkg_permission --> pkg_settings
   pkg_permission --> pkg_user_approval
+<<<<<<< HEAD
   pkg_client_ui_conversation --> pkg_client_locale
   pkg_client_ui_conversation --> pkg_client_runtime
   pkg_client_ui_conversation --> pkg_client_ui_primitives
@@ -687,6 +625,11 @@ flowchart TD
   pkg_command_feedback --> pkg_commands
   pkg_command_feedback --> pkg_invariants
   pkg_command_feedback --> pkg_session
+=======
+  pkg_client_remotes --> pkg_goal
+  pkg_client_remotes --> pkg_host_api_gateway
+  pkg_client_remotes --> pkg_invariants
+>>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
   pkg_pty_local --> pkg_agent
   pkg_pty_local --> pkg_invariants
   pkg_pty_local --> pkg_pty
@@ -840,6 +783,7 @@ flowchart TD
   pkg_tool_ask_user --> pkg_invariants
   pkg_tool_ask_user --> pkg_tools
   pkg_tool_ask_user --> pkg_user_interaction
+<<<<<<< HEAD
   pkg_client_ui_command --> pkg_client_connection
   pkg_client_ui_command --> pkg_client_locale
   pkg_client_ui_command --> pkg_client_runtime
@@ -869,6 +813,12 @@ flowchart TD
   pkg_client_ui_skill --> pkg_client_ui_slash
   pkg_client_ui_skill --> pkg_client_ui_slots
   pkg_client_ui_skill --> pkg_invariants
+=======
+  pkg_client_runtime --> pkg_client_remotes
+  pkg_client_runtime --> pkg_invariants
+  pkg_client_runtime --> pkg_type_meta
+  pkg_client_runtime --> pkg_typert_registry
+>>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compact
   pkg_session_reference --> pkg_invariants
@@ -1000,42 +950,29 @@ flowchart TD
   pkg_web_app --> pkg_bash_env
   pkg_web_app --> pkg_invariants
   pkg_web_app --> pkg_system_prompt
-  pkg_client_ui_model --> pkg_client_connection
-  pkg_client_ui_model --> pkg_client_locale
-  pkg_client_ui_model --> pkg_client_runtime
-  pkg_client_ui_model --> pkg_client_ui_command
-  pkg_client_ui_model --> pkg_client_ui_conversation
-  pkg_client_ui_model --> pkg_client_ui_primitives
-  pkg_client_ui_model --> pkg_client_ui_slash
-  pkg_client_ui_model --> pkg_client_ui_slots
-  pkg_client_ui_model --> pkg_invariants
-  pkg_client_ui_permission --> pkg_client_connection
-  pkg_client_ui_permission --> pkg_client_locale
-  pkg_client_ui_permission --> pkg_client_runtime
-  pkg_client_ui_permission --> pkg_client_schema_form
-  pkg_client_ui_permission --> pkg_client_ui_command
-  pkg_client_ui_permission --> pkg_client_ui_primitives
-  pkg_client_ui_permission --> pkg_client_ui_slash
-  pkg_client_ui_permission --> pkg_client_ui_slots
-  pkg_client_ui_permission --> pkg_invariants
-  pkg_client_ui_permission --> pkg_permission
-  pkg_client_ui_plan --> pkg_client_connection
-  pkg_client_ui_plan --> pkg_client_locale
-  pkg_client_ui_plan --> pkg_client_runtime
-  pkg_client_ui_plan --> pkg_client_ui_conversation
-  pkg_client_ui_plan --> pkg_client_ui_primitives
-  pkg_client_ui_plan --> pkg_client_ui_slots
-  pkg_client_ui_plan --> pkg_invariants
-  pkg_client_ui_plan --> pkg_plan_mode
-  pkg_client_ui_subagent --> pkg_client_locale
-  pkg_client_ui_subagent --> pkg_client_runtime
-  pkg_client_ui_subagent --> pkg_client_ui_conversation
-  pkg_client_ui_subagent --> pkg_client_ui_primitives
-  pkg_client_ui_subagent --> pkg_client_ui_slash
-  pkg_client_ui_subagent --> pkg_client_ui_slots
-  pkg_client_ui_subagent --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_subagent
-  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_client_locale --> pkg_client_runtime
+  pkg_client_locale --> pkg_client_ui_primitives
+  pkg_client_locale --> pkg_client_ui_slots
+  pkg_client_locale --> pkg_invariants
+  pkg_client_test_runtime --> pkg_client_runtime
+  pkg_client_test_runtime --> pkg_client_ui_slots
+  pkg_client_test_runtime --> pkg_client_web_react
+  pkg_client_test_runtime --> pkg_host_apiproxy
+  pkg_client_test_runtime --> pkg_invariants
+  pkg_client_ui_models --> pkg_client_connection
+  pkg_client_ui_models --> pkg_client_runtime
+  pkg_client_ui_models --> pkg_client_schema_form
+  pkg_client_ui_models --> pkg_client_ui_primitives
+  pkg_client_ui_models --> pkg_client_ui_slots
+  pkg_client_ui_models --> pkg_client_web_react
+  pkg_client_ui_models --> pkg_invariants
+  pkg_client_ui_settings --> pkg_client_runtime
+  pkg_client_ui_settings --> pkg_client_ui_primitives
+  pkg_client_ui_settings --> pkg_client_ui_slots
+  pkg_client_ui_settings --> pkg_invariants
+  pkg_client_ui_trajectory --> pkg_client_runtime
+  pkg_client_ui_trajectory --> pkg_client_ui_primitives
+  pkg_client_ui_trajectory --> pkg_invariants
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1078,6 +1015,36 @@ flowchart TD
   pkg_jsonrpc --> pkg_sdk_protocol
   pkg_jsonrpc --> pkg_session
   pkg_jsonrpc --> pkg_subagent
+  pkg_client_ui_question --> pkg_client_locale
+  pkg_client_ui_question --> pkg_invariants
+  pkg_client_ui_settings_general --> pkg_client_connection
+  pkg_client_ui_settings_general --> pkg_client_locale
+  pkg_client_ui_settings_general --> pkg_client_runtime
+  pkg_client_ui_settings_general --> pkg_client_ui_primitives
+  pkg_client_ui_settings_general --> pkg_client_ui_settings
+  pkg_client_ui_settings_general --> pkg_client_ui_slots
+  pkg_client_ui_settings_general --> pkg_client_web_react
+  pkg_client_ui_settings_general --> pkg_invariants
+  pkg_client_ui_sidebar --> pkg_client_locale
+  pkg_client_ui_sidebar --> pkg_client_runtime
+  pkg_client_ui_sidebar --> pkg_client_ui_primitives
+  pkg_client_ui_sidebar --> pkg_client_ui_slots
+  pkg_client_ui_sidebar --> pkg_invariants
+  pkg_client_ui_slash --> pkg_client_locale
+  pkg_client_ui_slash --> pkg_client_runtime
+  pkg_client_ui_slash --> pkg_client_ui_primitives
+  pkg_client_ui_slash --> pkg_client_ui_slots
+  pkg_client_ui_slash --> pkg_invariants
+  pkg_client_ui_theme --> pkg_client_locale
+  pkg_client_ui_theme --> pkg_client_runtime
+  pkg_client_ui_theme --> pkg_client_ui_primitives
+  pkg_client_ui_theme --> pkg_client_ui_slots
+  pkg_client_ui_theme --> pkg_invariants
+  pkg_client_ui_workspace --> pkg_client_locale
+  pkg_client_ui_workspace --> pkg_client_runtime
+  pkg_client_ui_workspace --> pkg_client_ui_primitives
+  pkg_client_ui_workspace --> pkg_client_ui_slots
+  pkg_client_ui_workspace --> pkg_invariants
   pkg_agent_spine_demo --> pkg_agent
   pkg_agent_spine_demo --> pkg_agent_loop
   pkg_agent_spine_demo --> pkg_bash_env
@@ -1111,6 +1078,22 @@ flowchart TD
   pkg_subagent_dsh_sdk --> pkg_session
   pkg_subagent_dsh_sdk --> pkg_subagent
   pkg_subagent_dsh_sdk --> pkg_subprocess
+  pkg_client_ui_conversation --> pkg_client_locale
+  pkg_client_ui_conversation --> pkg_client_runtime
+  pkg_client_ui_conversation --> pkg_client_ui_primitives
+  pkg_client_ui_conversation --> pkg_client_ui_slash
+  pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_token_meter
+  pkg_client_ui_layout --> pkg_client_runtime
+  pkg_client_ui_layout --> pkg_client_ui_slots
+  pkg_client_ui_layout --> pkg_client_ui_theme
+  pkg_client_ui_layout --> pkg_invariants
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_invariants
   pkg_acp_demo --> pkg_acp
   pkg_acp_demo --> pkg_agent_spine_demo
   pkg_acp_demo --> pkg_app_boot
@@ -1131,6 +1114,72 @@ flowchart TD
   pkg_cli_demo --> pkg_session_persistence_jsonl
   pkg_cli_demo --> pkg_tools
   pkg_cli_demo --> pkg_workspace_context
+  pkg_host_directory_picker_browse --> pkg_client_locale
+  pkg_host_directory_picker_browse --> pkg_client_runtime
+  pkg_host_directory_picker_browse --> pkg_client_ui_primitives
+  pkg_host_directory_picker_browse --> pkg_client_ui_slots
+  pkg_host_directory_picker_browse --> pkg_client_ui_workspace
+  pkg_host_directory_picker_browse --> pkg_invariants
+  pkg_host_directory_picker_native --> pkg_client_runtime
+  pkg_host_directory_picker_native --> pkg_client_ui_slots
+  pkg_host_directory_picker_native --> pkg_client_ui_workspace
+  pkg_host_directory_picker_native --> pkg_invariants
+  pkg_client_ui_command --> pkg_client_connection
+  pkg_client_ui_command --> pkg_client_locale
+  pkg_client_ui_command --> pkg_client_runtime
+  pkg_client_ui_command --> pkg_client_ui_conversation
+  pkg_client_ui_command --> pkg_client_ui_primitives
+  pkg_client_ui_command --> pkg_client_ui_slash
+  pkg_client_ui_command --> pkg_client_ui_slots
+  pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_goal --> pkg_client_connection
+  pkg_client_ui_goal --> pkg_client_locale
+  pkg_client_ui_goal --> pkg_client_runtime
+  pkg_client_ui_goal --> pkg_client_ui_conversation
+  pkg_client_ui_goal --> pkg_client_ui_primitives
+  pkg_client_ui_goal --> pkg_client_ui_slots
+  pkg_client_ui_goal --> pkg_goal
+  pkg_client_ui_goal --> pkg_invariants
+  pkg_client_ui_plan --> pkg_client_connection
+  pkg_client_ui_plan --> pkg_client_locale
+  pkg_client_ui_plan --> pkg_client_runtime
+  pkg_client_ui_plan --> pkg_client_ui_conversation
+  pkg_client_ui_plan --> pkg_client_ui_primitives
+  pkg_client_ui_plan --> pkg_client_ui_slots
+  pkg_client_ui_plan --> pkg_invariants
+  pkg_client_ui_plan --> pkg_plan_mode
+  pkg_client_ui_subagent --> pkg_client_locale
+  pkg_client_ui_subagent --> pkg_client_runtime
+  pkg_client_ui_subagent --> pkg_client_ui_conversation
+  pkg_client_ui_subagent --> pkg_client_ui_primitives
+  pkg_client_ui_subagent --> pkg_client_ui_slash
+  pkg_client_ui_subagent --> pkg_client_ui_slots
+  pkg_client_ui_subagent --> pkg_invariants
+  pkg_client_ui_subagent --> pkg_subagent
+  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse
+  pkg_host_directory_picker_auto --> pkg_host_directory_picker_native
+  pkg_host_directory_picker_auto --> pkg_host_webserver
+  pkg_host_directory_picker_auto --> pkg_invariants
+  pkg_client_ui_model --> pkg_client_connection
+  pkg_client_ui_model --> pkg_client_locale
+  pkg_client_ui_model --> pkg_client_runtime
+  pkg_client_ui_model --> pkg_client_ui_command
+  pkg_client_ui_model --> pkg_client_ui_conversation
+  pkg_client_ui_model --> pkg_client_ui_primitives
+  pkg_client_ui_model --> pkg_client_ui_slash
+  pkg_client_ui_model --> pkg_client_ui_slots
+  pkg_client_ui_model --> pkg_invariants
+  pkg_client_ui_permission --> pkg_client_connection
+  pkg_client_ui_permission --> pkg_client_locale
+  pkg_client_ui_permission --> pkg_client_runtime
+  pkg_client_ui_permission --> pkg_client_schema_form
+  pkg_client_ui_permission --> pkg_client_ui_command
+  pkg_client_ui_permission --> pkg_client_ui_primitives
+  pkg_client_ui_permission --> pkg_client_ui_slash
+  pkg_client_ui_permission --> pkg_client_ui_slots
+  pkg_client_ui_permission --> pkg_invariants
+  pkg_client_ui_permission --> pkg_permission
 ```
 
 | Package | Group | Depends on |
@@ -1149,7 +1198,6 @@ flowchart TD
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`invariants`](../packages/support/invariants) |
 | [`base`](../packages/bundle/base) | `bundle` | [`invariants`](../packages/support/invariants) |
 | [`client-modules`](../packages/client/modules) | `client` | [`invariants`](../packages/support/invariants) |
-| [`client-runtime`](../packages/client/runtime) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-schema-form`](../packages/client/schema-form) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-ui-primitives`](../packages/client/ui-primitives) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-ui-slots`](../packages/client/ui-slots) | `client` | [`invariants`](../packages/support/invariants) |
@@ -1168,10 +1216,6 @@ flowchart TD
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout) |
 | [`client-connection`](../packages/client/connection) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
-| [`client-locale`](../packages/client/locale) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-test-runtime`](../packages/client/test-runtime) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/support/invariants) |
-| [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`invariants`](../packages/support/invariants) |
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
@@ -1187,13 +1231,6 @@ flowchart TD
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`type-meta`](../packages/typert/type-meta) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
-| [`client-ui-models`](../packages/client/ui-models) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
-| [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |
-| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
-| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`host-api-gateway`](../packages/host/api-gateway) | `host` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
@@ -1210,16 +1247,17 @@ flowchart TD
 | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
+<<<<<<< HEAD
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
+=======
+>>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
-| [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`session-projection`](../packages/session-projection/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
-| [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
+| [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pwsh-local`](../packages/bash/pwsh-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
@@ -1237,7 +1275,6 @@ flowchart TD
 | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants) |
@@ -1257,8 +1294,12 @@ flowchart TD
 | [`session-title-llm`](../packages/session-title/session-title-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`timeout`](../packages/util/timeout) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
 | [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/ui/user-approval) |
+<<<<<<< HEAD
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+=======
+| [`client-remotes`](../packages/client/remotes) | `client` | [`goal`](../packages/goal/goal), [`host-api-gateway`](../packages/host/api-gateway), [`invariants`](../packages/support/invariants) |
+>>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -1284,10 +1325,14 @@ flowchart TD
 | [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`session-title-llm`](../packages/session-title/session-title-llm) |
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+<<<<<<< HEAD
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
 | [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+=======
+| [`client-runtime`](../packages/client/runtime) | `client` | [`client-remotes`](../packages/client/remotes), [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
+>>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
@@ -1309,10 +1354,11 @@ flowchart TD
 | [`repository-plugin`](../packages/cordis/repository-plugin) | `cordis` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
-| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/ui/permission) |
-| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
-| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`client-locale`](../packages/client/locale) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-test-runtime`](../packages/client/test-runtime) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/support/invariants) |
+| [`client-ui-models`](../packages/client/ui-models) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
+| [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`invariants`](../packages/support/invariants) |
 | [`sdk-protocol`](../packages/sdk/sdk-protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
@@ -1320,8 +1366,26 @@ flowchart TD
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |
+| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
+| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`sdk-client`](../packages/sdk/sdk-client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/sdk-client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`cli-demo`](../packages/examples/cli-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
+| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/ui/permission) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 3c037198da..48732dbbb0 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -340,7 +340,7 @@ Source: [`packages/feedback/command-feedback/src/index.ts:24`](../packages/feedb
 'goal/change': GoalChangeMeta
 ```
 
-Source: [`packages/goal/goal/src/domain.ts:81`](../packages/goal/goal/src/domain.ts)
+Source: [`packages/goal/goal/src/domain.ts:66`](../packages/goal/goal/src/domain.ts)
 
 ### `hook/*`
 
diff --git a/knip.json b/knip.json
index 32c9e20dbf..3ce9a32d99 100644
--- a/knip.json
+++ b/knip.json
@@ -115,6 +115,15 @@
         "tests/**/*.ts"
       ]
     },
+    "packages/client/remotes": {
+      "entry": [
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
+    },
     "packages/client/ui-primitives": {
       "entry": [
         "tests/**/*.spec.tsx"
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 681f0d5121..001c43948d 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -124,6 +124,9 @@
     - id: connection
       name: '@deepseek-ai/dsh-client-connection'
 
+    - id: client-remotes
+      name: '@deepseek-ai/dsh-client-remotes'
+
     - id: client-runtime
       name: '@deepseek-ai/dsh-client-runtime'
 
diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json
index 29eeb24009..89b5e8e2a7 100644
--- a/packages/bundle/web-app/package.json
+++ b/packages/bundle/web-app/package.json
@@ -36,6 +36,7 @@
     "@deepseek-ai/dsh-client-hmr": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-modules": "workspace:^",
+    "@deepseek-ai/dsh-client-remotes": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-command": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
diff --git a/packages/client/remotes/README.i18n.yaml b/packages/client/remotes/README.i18n.yaml
new file mode 100644
index 0000000000..86f2aded18
--- /dev/null
+++ b/packages/client/remotes/README.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 packages/client/remotes/README.md
+README.md: e29188b8e3ae5ecefe194f1355558e9bdeaae7dd
+README.zh.md: e6425ab190a28e0a38c3713c4e21645789a8f00c
diff --git a/packages/client/remotes/README.md b/packages/client/remotes/README.md
new file mode 100644
index 0000000000..e29188b8e3
--- /dev/null
+++ b/packages/client/remotes/README.md
@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-remotes
+
+English | [中文](README.zh.md)
+
+Platform-neutral Client facade for Host Remote capabilities selected by this application. Its Client entry imports generated `/remote` artifacts as runtime values, mounts each contribution through `ctx.api`, and re-exports their declaration merges. Client business packages depend on this facade rather than the Host API Gateway or individual Remote runtime entries.
+
+The current assembly mounts only the Goal Remote contribution. Cordis effect ownership withdraws every contribution when this assembly unloads, while the Client face of `@deepseek-ai/dsh-host-api-gateway` owns descriptor validation, concrete root and scoped methods, invocation, and cancellation.
+
+This package contains no transport or Host discovery logic. It can be reused by Web or a future TUI Client that provides the same React-free `ctx.api` contract.
+
+## Model Experience
+
+None, as this Client assembly selects Remote application methods and registers no model surface.
+
+#### KV Cache effect
+
+No direct effect; mounted Host capabilities own any model-visible behavior they trigger.
+
+## Known Limitations and Deferred Work
+
+- The capability set is fixed by explicit build-time value imports; the Client does not discover the Host's active Services or Remote definitions at runtime.
+- Additional capabilities require an explicit `/remote` value import and mount in this assembly.
diff --git a/packages/client/remotes/README.zh.md b/packages/client/remotes/README.zh.md
new file mode 100644
index 0000000000..e6425ab190
--- /dev/null
+++ b/packages/client/remotes/README.zh.md
@@ -0,0 +1,22 @@
+# @deepseek-ai/dsh-client-remotes
+
+[English](README.md) | 中文
+
+为本应用选定的 Host Remote 能力提供平台无关的 Client 外观。其 Client 入口以运行时值形式导入生成的 `/remote` 产物，通过 `ctx.api` 挂载每项贡献，并重新导出对应的声明合并。Client 业务包依赖此外观，而不依赖 Host API Gateway 或单独的 Remote 运行时入口。
+
+当前组合仅挂载 Goal Remote 贡献。该组合卸载时，Cordis effect 的所有权机制会撤回所有贡献；`@deepseek-ai/dsh-host-api-gateway` 的 Client 侧负责描述符校验、具体的根级方法和作用域方法、调用与取消。
+
+本包不包含传输逻辑或 Host 发现逻辑。Web 和未来的 TUI Client 只要提供同一份不依赖 React 的 `ctx.api` 契约，均可复用本包。
+
+## 模型体验
+
+无，因为此 Client 组合只选择应用的 Remote 方法，不注册任何模型接口。
+
+#### KV Cache 影响
+
+无直接影响；其触发的任何模型可见行为均由已挂载的 Host 能力负责。
+
+## 已知限制与暂缓事项
+
+- 能力集合由构建时显式导入的值固定确定；Client 不会在运行时发现 Host 中已启用的服务或 Remote 定义。
+- 若要增加能力，必须显式导入相应的 `/remote` 值并在此组合中挂载。
diff --git a/packages/client/remotes/package.json b/packages/client/remotes/package.json
new file mode 100644
index 0000000000..ba4e7b6a01
--- /dev/null
+++ b/packages/client/remotes/package.json
@@ -0,0 +1,55 @@
+{
+  "name": "@deepseek-ai/dsh-client-remotes",
+  "description": "Platform-neutral assembly of explicitly selected Host Remote contributions",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-host-api-gateway"
+    ],
+    "platform": "web",
+    "immediately": true
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-host-api-gateway": "^0.0.1",
+    "@deepseek-ai/dsh-goal": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-host-api-gateway": "workspace:^",
+    "@deepseek-ai/dsh-goal": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/client/remotes/src/client/index.ts b/packages/client/remotes/src/client/index.ts
new file mode 100644
index 0000000000..09757b5e9e
--- /dev/null
+++ b/packages/client/remotes/src/client/index.ts
@@ -0,0 +1,19 @@
+/** Platform-neutral assembly of generated Host Remote contributions. */
+
+import type { Context } from 'cordis'
+import type {} from '@deepseek-ai/dsh-host-api-gateway/client'
+import goalsRemote from '@deepseek-ai/dsh-goal/remote'
+
+export type { ClientApi } from '@deepseek-ai/dsh-host-api-gateway/client'
+export type {} from '@deepseek-ai/dsh-goal/remote'
+
+/** Required service: the typed Client API contribution mount. */
+export const inject = ['api']
+
+/**
+ * Mount the Host capabilities explicitly selected for this Client assembly.
+ * @param ctx - Client Cordis root carrying the typed API service.
+ */
+export function apply(ctx: Context): void {
+  ctx.api.mount(goalsRemote)
+}
diff --git a/packages/client/remotes/src/index.ts b/packages/client/remotes/src/index.ts
new file mode 100644
index 0000000000..c8c4ff20be
--- /dev/null
+++ b/packages/client/remotes/src/index.ts
@@ -0,0 +1,4 @@
+/** Host Loader entry for the Client Remote contribution assembly. */
+
+/** Host plugin body; the selected contributions mount only in Client environments. */
+export function apply(): void {}
diff --git a/packages/client/remotes/src/invariant.ts b/packages/client/remotes/src/invariant.ts
new file mode 100644
index 0000000000..1a6b0ba237
--- /dev/null
+++ b/packages/client/remotes/src/invariant.ts
@@ -0,0 +1,24 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-client-remotes`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-remotes'
+
+/** Cordis companion plugin name. */
+export const name = 'client-remotes-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: the API service owns contribution and method lifecycle atomically. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/remotes/tests/built-lib.e2e.ts b/packages/client/remotes/tests/built-lib.e2e.ts
new file mode 100644
index 0000000000..bbba218844
--- /dev/null
+++ b/packages/client/remotes/tests/built-lib.e2e.ts
@@ -0,0 +1,214 @@
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Built-artifact smoke for the first generated Remote: plain Node boots the
+ * Host and Browser bundle handoffs, then crosses the real `/api2` HTTP route.
+ */
+
+const packageDir = fileURLToPath(new URL('..', import.meta.url))
+const root = resolve(packageDir, '../../..')
+const artifact = (path: string): string => join(root, path)
+const artifactUrl = (path: string): string => pathToFileURL(artifact(path)).href
+
+const requiredArtifacts = [
+  'packages/client/connection/lib/client.js',
+  'packages/client/connection/lib/index.js',
+  'packages/client/remotes/lib/client.js',
+  'packages/core/agent/lib/index.js',
+  'packages/core/session/lib/index.js',
+  'packages/goal/goal/lib/index.js',
+  'packages/goal/goal/lib/typert.host.js',
+  'packages/host/api-gateway/lib/client.js',
+  'packages/host/api-gateway/lib/index.js',
+  'packages/typert/registry/lib/client.js',
+  'packages/typert/registry/lib/index.js',
+].every(path => existsSync(artifact(path)))
+
+describe.skipIf(!requiredArtifacts)('Goal Remote built LIB chain', () => {
+  it('runs root and Agent-scoped calls through generated bundles and real HTTP', async () => {
+    const urls = Object.fromEntries(Object.entries({
+      agent: 'packages/core/agent/lib/index.js',
+      apiGatewayClient: 'packages/host/api-gateway/lib/client.js',
+      apiGatewayHost: 'packages/host/api-gateway/lib/index.js',
+      connectionClient: 'packages/client/connection/lib/client.js',
+      connectionHost: 'packages/client/connection/lib/index.js',
+      goal: 'packages/goal/goal/lib/index.js',
+      goalTypert: 'packages/goal/goal/lib/typert.host.js',
+      registryClient: 'packages/typert/registry/lib/client.js',
+      registryHost: 'packages/typert/registry/lib/index.js',
+      remotesClient: 'packages/client/remotes/lib/client.js',
+      session: 'packages/core/session/lib/index.js',
+    }).map(([key, path]) => [key, artifactUrl(path)]))
+    const script = `
+      import { createServer } from 'node:http'
+      import * as cordis from 'cordis'
+
+      const urls = ${JSON.stringify(urls)}
+      const { Context } = cordis
+      const { default: AgentRegistry } = await import(urls.agent)
+      const connectionHost = await import(urls.connectionHost)
+      const { default: TypertGatewayService } = await import(urls.apiGatewayHost)
+      const { default: GoalService } = await import(urls.goal)
+      const { TYPERT } = await import(urls.goalTypert)
+      const { default: TypertRegistry } = await import(urls.registryHost)
+      const { Session, SessionId } = await import(urls.session)
+
+      const routes = []
+      const host = new Context()
+      host.provide('httpServer', {
+        register(route) {
+          routes.push(route)
+          return () => { routes.splice(routes.indexOf(route), 1) }
+        },
+        tapIndex() { return () => {} },
+        port: 0,
+      })
+      await host.plugin({ inject: connectionHost.inject, apply: connectionHost.apply })
+      await host.plugin(TypertRegistry)
+      await host.plugin(AgentRegistry)
+      await host.plugin(TypertGatewayService)
+      await host.plugin(GoalService)
+      host.typert.register(TYPERT)
+
+      const makeAgent = rawId => {
+        const session = new Session(SessionId(rawId))
+        return {
+          id: session.id,
+          options: {},
+          session,
+          ctx: host.extend(),
+          status: 'idle',
+          acceptsNextStep: false,
+          send() {},
+          updateInbox() { return 'not-found' },
+          followup() {},
+          steer() { return { outcome: Promise.resolve({ status: 'rejected' }) } },
+          inject(input) { session.append('user/message', input, { surfaceOp: 'append' }) },
+          reserveTurnAdmission() {},
+          cancel() {},
+          whenIdle() { return Promise.resolve() },
+        }
+      }
+      const rootAgent = makeAgent('built-root-agent')
+      const scopedAgent = makeAgent('built-scoped-agent')
+      host.agents.register(rootAgent)
+      host.agents.register(scopedAgent)
+
+      if (routes.length !== 1) throw new Error('Gateway did not register exactly one /api2 route')
+      const server = createServer((request, response) => { void routes[0].handler(request, response) })
+      await new Promise(resolveListen => server.listen(0, '127.0.0.1', resolveListen))
+      const address = server.address()
+      if (address === null || typeof address === 'string') throw new Error('HTTP server has no TCP address')
+      const origin = 'http://127.0.0.1:' + String(address.port)
+
+      const handoffs = new Map()
+      globalThis.window = {
+        __ModuleLoader__: {
+          load(handoff) { handoffs.set(handoff.id, handoff) },
+        },
+      }
+      globalThis.location = { hostname: '127.0.0.1', origin, search: '' }
+      await import(urls.registryClient)
+      await import(urls.connectionClient)
+      await import(urls.apiGatewayClient)
+      await import(urls.remotesClient)
+
+      const instantiate = id => {
+        const handoff = handoffs.get(id)
+        if (handoff === undefined) throw new Error('missing Client bundle handoff ' + id)
+        return handoff.factory(specifier => {
+          if (specifier === 'cordis') return cordis
+          throw new Error('unexpected Client external ' + specifier)
+        })
+      }
+      const client = new Context()
+      for (const id of [
+        '@deepseek-ai/dsh-typert-registry',
+        '@deepseek-ai/dsh-client-connection',
+        '@deepseek-ai/dsh-host-api-gateway',
+        '@deepseek-ai/dsh-client-remotes',
+      ]) {
+        const plugin = instantiate(id)
+        await client.plugin({ inject: plugin.inject, apply: plugin.apply })
+      }
+      client.typert.contexts.registerClient('agent', {
+        identity: candidate => candidate.builtAgentId,
+      })
+
+      let invalidRejected = false
+      try {
+        await client.api.goals.create(rootAgent.id, { objective: 1 })
+      } catch {
+        invalidRejected = true
+      }
+      const rootResult = await client.api.goals.create(rootAgent.id, { objective: 'root goal' })
+      const agentContext = client.extend({ builtAgentId: scopedAgent.id })
+      const scopedResult = await agentContext.goals.create({ objective: 'scoped goal', maxGoalRounds: 3 })
+      const result = {
+        invalidRejected,
+        rootResult,
+        scopedResult,
+        rootGoal: host.goals.get(rootAgent)?.objective,
+        scopedGoal: host.goals.get(scopedAgent)?.objective,
+        rootEvents: rootAgent.session.events.length,
+        scopedEvents: scopedAgent.session.events.length,
+      }
+
+      await client.fiber.dispose()
+      await new Promise((resolveClose, rejectClose) => server.close(error => {
+        if (error === undefined) resolveClose()
+        else rejectClose(error)
+      }))
+      await host.fiber.dispose()
+      console.log(JSON.stringify(result))
+    `
+
+    const result = await runPlainNode(script)
+    expect(result.exitCode, `stderr:\n${result.stderr}`).toBe(0)
+    const output = JSON.parse(result.stdout.trim().split('\n').at(-1) ?? '{}') as {
+      invalidRejected: boolean
+      rootResult: { ref: { id: string; revision: number } }
+      scopedResult: { ref: { id: string; revision: number } }
+      rootGoal: string
+      scopedGoal: string
+      rootEvents: number
+      scopedEvents: number
+    }
+    expect(output).toMatchObject({
+      invalidRejected: true,
+      rootResult: { ref: { revision: 1 } },
+      scopedResult: { ref: { revision: 1 } },
+      rootGoal: 'root goal',
+      scopedGoal: 'scoped goal',
+      rootEvents: 1,
+      scopedEvents: 1,
+    })
+    expect(output.rootResult.ref.id).toMatch(/^goal-/)
+    expect(output.scopedResult.ref.id).toMatch(/^goal-/)
+  }, 60_000)
+})
+
+/** Execute one ESM script without tsx or a TypeScript loader. */
+function runPlainNode(script: string): Promise<{
+  readonly exitCode: number | null
+  readonly stdout: string
+  readonly stderr: string
+}> {
+  return new Promise((resolveRun) => {
+    execFile(process.execPath, ['--input-type=module', '-e', script], {
+      cwd: packageDir,
+      encoding: 'utf8',
+      timeout: 55_000,
+    }, (error, stdout, stderr) => {
+      resolveRun({
+        exitCode: error === null ? 0 : typeof error.code === 'number' ? error.code : null,
+        stdout,
+        stderr,
+      })
+    })
+  })
+}
diff --git a/packages/client/remotes/tsconfig.json b/packages/client/remotes/tsconfig.json
new file mode 100644
index 0000000000..c99a5fce19
--- /dev/null
+++ b/packages/client/remotes/tsconfig.json
@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../host/api-gateway"
+    },
+    {
+      "path": "../../ui/commands"
+    },
+    {
+      "path": "../../goal/goal"
+    },
+    {
+      "path": "../../session-title/session-title"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/remotes/tsdown.config.ts b/packages/client/remotes/tsdown.config.ts
new file mode 100644
index 0000000000..20fa098462
--- /dev/null
+++ b/packages/client/remotes/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-remotes', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
index b636316b68..cc51aa772d 100644
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -24,7 +24,9 @@
   },
   "dshClient": {
     "inject": [
-      "@deepseek-ai/dsh-client-connection"
+      "@deepseek-ai/dsh-client-connection",
+      "@deepseek-ai/dsh-client-remotes",
+      "@deepseek-ai/dsh-typert-registry"
     ],
     "platform": "web",
     "immediately": true
@@ -47,11 +49,17 @@
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-client-remotes": "^0.0.1",
+    "@deepseek-ai/dsh-type-meta": "^0.0.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-client-remotes": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "@types/react": "~18.3.1",
     "cordis": "^4.0.0-rc.7"
   },
diff --git a/packages/client/runtime/src/client/agents/scope.ts b/packages/client/runtime/src/client/agents/scope.ts
index af6fa3afcd..ba4fd8ede7 100644
--- a/packages/client/runtime/src/client/agents/scope.ts
+++ b/packages/client/runtime/src/client/agents/scope.ts
@@ -18,6 +18,7 @@
 import { Context as CordisContext } from 'cordis'
 import type { Context, Fiber } from 'cordis'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { TypeRTRemoteContextApi } from '@deepseek-ai/dsh-type-meta'
 
 /** Context tag written by {@link createScope}. */
 const kScope = Symbol('dsh.client.scope')
@@ -29,7 +30,7 @@ export interface AgentScopeHandle {
    * through it (passing it as the dispatch subject routes to this agent's
    * tagged listeners plus every untagged one).
    */
-  ctx: Context
+  ctx: Context & TypeRTRemoteContextApi<'agent'>
   /** Backing fiber (dispose tears down every scope-owned registration). */
   fiber: Fiber
 }
@@ -48,15 +49,16 @@ function agentScope(): void {}
  */
 export function createScope(ctx: Context, key: SessionId): AgentScopeHandle {
   const fiber = ctx.plugin(agentScope)
+  const scoped = fiber.ctx.extend({
+    [kScope]: key,
+    [CordisContext.filter](listenerCtx: Context): boolean {
+      const tag = scopeOf(listenerCtx)
+      return tag === undefined || tag === key
+    },
+  }) as Context & TypeRTRemoteContextApi<'agent'>
   return {
     fiber,
-    ctx: fiber.ctx.extend({
-      [kScope]: key,
-      [CordisContext.filter](listenerCtx: Context): boolean {
-        const tag = scopeOf(listenerCtx)
-        return tag === undefined || tag === key
-      },
-    }),
+    ctx: scoped,
   }
 }
 
diff --git a/packages/client/runtime/src/client/contract/sessions.ts b/packages/client/runtime/src/client/contract/sessions.ts
index fbb0bb1a4e..8e9c530720 100644
--- a/packages/client/runtime/src/client/contract/sessions.ts
+++ b/packages/client/runtime/src/client/contract/sessions.ts
@@ -11,6 +11,7 @@ import type { Context } from 'cordis'
 import type {
   RpcResult, SessionId, SubagentAddress,
 } from '@deepseek-ai/dsh-client-connection/client'
+import type { TypeRTRemoteContextApi } from '@deepseek-ai/dsh-type-meta'
 import type { HostObservable, SessionMaybeProvideInfo } from '@deepseek-ai/dsh-client-ui-slots'
 import type { SessionSearchResultItem } from '../sessions/manager.ts'
 import type {
@@ -19,6 +20,9 @@ import type {
 import type { SessionFace } from './session.ts'
 import type { ObservableSnapshot } from './store.ts'
 
+/** Client Cordis Context carrying one Agent identity and its generated Remote namespaces. */
+export type AgentContext = Context & TypeRTRemoteContextApi<'agent'>
+
 /** The sessions-service face injected as `ctx.sessions`. */
 export interface ISessions {
   /** The useSessions standard feed (list rows + current selection; read face — writes stay inside the domain). */
@@ -95,7 +99,7 @@ export interface ISessions {
    * @param id - session id.
    * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
    */
-  scope(id: SessionId): Context | undefined
+  scope(id: SessionId): AgentContext | undefined
   /**
    * Read the Agent scope tag off a context (service-method seam: fetch
    * bundles must reach scope resolution through ctx.sessions).
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index 06f88a9131..f1efd6a65d 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -1,6 +1,8 @@
 /** Browser runtime services for slots, sessions, workspaces, and connection-stream delivery. */
 import type { Context } from 'cordis'
 import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type {} from '@deepseek-ai/dsh-client-remotes/client'
+import type { TypeRTContext } from '@deepseek-ai/dsh-type-meta'
 import type { MaybeSnapshotSelectorHook, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from './slots.ts'
 import { SessionsService } from './sessions/service.ts'
@@ -26,7 +28,7 @@ export type { ISession, ProjectionsFace, SessionFace } from './contract/session.
 export type {
   ISessionHistory, SessionHistoryFace, SessionHistorySnapshot,
 } from './contract/session-history.ts'
-export type { ISessions } from './contract/sessions.ts'
+export type { AgentContext, ISessions } from './contract/sessions.ts'
 export type { IWorkspaces } from './contract/workspaces.ts'
 export type {
   SessionBinding, SessionListState, SessionProvideContribution, SessionProvideDescriptor, SessionSummary,
@@ -75,6 +77,13 @@ export type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 /** Client-side Cordis context after declaration merging. */
 export type ClientContext = Context
 
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTContextMap {
+    /** Client Agent scope identity; the agent and session share one wire id. */
+    agent: TypeRTContext<SessionId>
+  }
+}
+
 /** The conversation-snapshot selector hook (ConvViewProps/ToolRowProps take this). */
 export type UseConversationSession = SnapshotSelectorHook<ConversationSnapshot>
 
@@ -170,8 +179,8 @@ declare module 'cordis' {
   }
 }
 
-/** Required services: the wire handle mounted by the connection plugin. */
-export const inject = ['connection']
+/** Required services: the typed Remote API, wire handle, and Client TypeRT registry. */
+export const inject = ['api', 'connection', 'typert']
 
 /** Mounts the browser runtime services and connection stream.
  * @param ctx - Client Cordis context.
@@ -180,6 +189,9 @@ export function apply(ctx: Context): void {
   ctx.plugin(SlotsService)
   const connection = ctx.get('connection') as ConnectionHandle
   const sessions = new SessionsService(ctx, connection.api)
+  ctx.typert.contexts.registerClient('agent', {
+    identity: candidate => sessions.scopeOf(candidate),
+  })
   const sessionHistory = new SessionHistoryService(ctx, connection.api)
   const workspaces = new WorkspacesService(ctx, connection.api, sessions)
   ctx.effect(
diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts
index b1b271e702..621760df02 100644
--- a/packages/client/runtime/src/client/sessions/service.ts
+++ b/packages/client/runtime/src/client/sessions/service.ts
@@ -29,7 +29,7 @@ import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/t
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
 import type { SessionFace } from '../contract/session.ts'
-import type { ISessions } from '../contract/sessions.ts'
+import type { AgentContext, ISessions } from '../contract/sessions.ts'
 import { createScope, scopeOf as scopeTagOf } from '../agents/scope.ts'
 import { SessionManager } from './manager.ts'
 import type { SessionListPhase, SessionSearchResultItem, SubagentCatalogSnapshot } from './manager.ts'
@@ -127,7 +127,7 @@ export interface SessionBinding {
   readonly sessionId: SessionId
   /** The outward session face only — feature code never sees the concrete class. */
   readonly session: SessionFace
-  readonly ctx: Context
+  readonly ctx: AgentContext
 }
 
 // Scope primitives live in ../agents/scope.ts (the client mirror of host
@@ -182,7 +182,7 @@ function increasedForkTitle(title: string): string {
 
 interface ScopeRecord {
   fiber: Fiber
-  ctx: Context
+  ctx: AgentContext
   binding: SessionBinding
   /** The concrete Session for runtime-internal entry points (staging open()); the binding carries only the outward face. */
   session: Session
@@ -483,7 +483,7 @@ export class SessionsService implements ISessions {
    * @param id - session id (the agent identity — 1:1 same axis).
    * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
    */
-  scope(id: SessionId): Context | undefined {
+  scope(id: SessionId): AgentContext | undefined {
     return this.resolve(id)?.ctx
   }
 
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index 14e51fae8e..5635793122 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -8,6 +8,7 @@ import { describe, expect, it } from 'vitest'
 import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
 import type { ConnectionSinks } from '@deepseek-ai/dsh-client-connection/client'
 import { SESSION_SEARCH_RESULT_LIMIT } from '@deepseek-ai/dsh-host-apiproxy/api'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import * as RuntimeClient from '../src/client/index.ts'
 import type { SessionsService } from '../src/client/sessions/service.ts'
 import type { WorkspacesService } from '../src/client/workspaces/service.ts'
@@ -22,6 +23,7 @@ interface Bench {
 
 async function mount(): Promise<Bench> {
   const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
   const api = new FakeApiClient()
   const bench: Bench = { ctx, api, sinks: undefined, stopped: 0 }
   const handle: ConnectionHandle = {
@@ -36,6 +38,7 @@ async function mount(): Promise<Bench> {
     },
   }
   ctx.reflect.provide('connection', handle)
+  ctx.reflect.provide('api', {})
   await ctx.plugin(RuntimeClient).await()
   return bench
 }
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index f1512c7059..85ba61d41a 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -20,6 +20,9 @@
     {
       "path": "../connection"
     },
+    {
+      "path": "../remotes"
+    },
     {
       "path": "../../host/apiproxy"
     },
@@ -43,6 +46,12 @@
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../typert/type-meta"
+    },
+    {
+      "path": "../../typert/registry"
     }
   ],
   "exclude": [
diff --git a/packages/client/test-runtime/src/sessions.ts b/packages/client/test-runtime/src/sessions.ts
index e313b63fd2..4747929572 100644
--- a/packages/client/test-runtime/src/sessions.ts
+++ b/packages/client/test-runtime/src/sessions.ts
@@ -3,7 +3,7 @@ import type { Context } from 'cordis'
 import { createScope, scopeOf, SessionProvideChannel } from '@deepseek-ai/dsh-client-runtime/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
-  ConversationSnapshot, ISessions, ObservableSnapshot, ProjectionsFace, SessionFace, SessionId,
+  AgentContext, ConversationSnapshot, ISessions, ObservableSnapshot, ProjectionsFace, SessionFace, SessionId,
   SessionListState, SessionProvideDescriptor, SessionSearchResultItem, SessionSummary, SnapshotStore,
   SubagentAddress,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -134,7 +134,7 @@ interface SessionRecord {
   summary: SessionSummary
   snapshot: SnapshotStore<ConversationSnapshot>
   session: FixtureSession
-  scope: Context | undefined
+  scope: AgentContext | undefined
   scopeFiber: { dispose(): Promise<void> } | undefined
   /** Materialized standard-props bundle (identity-stable per session; invalidated on roster change). */
   provideInfo: SessionProvideInfo | undefined
@@ -144,7 +144,7 @@ interface SessionRecord {
 export interface TestSessionBinding {
   readonly sessionId: SessionId
   readonly session: FixtureSession
-  readonly ctx: Context
+  readonly ctx: AgentContext
 }
 
 /**
@@ -345,7 +345,7 @@ export class TestSessions implements ISessions {
    * @param id - session id.
    * @returns the scoped context, or undefined for unknown sessions.
    */
-  scope(id: string): Context | undefined {
+  scope(id: string): AgentContext | undefined {
     const record = this.records.get(id as SessionId)
     if (record === undefined) return undefined
     if (record.scope === undefined) {
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index b8da6049e8..48f4aadeed 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -382,6 +382,30 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'clear(agent: Agent, ref: GoalRef): GoalRef',
         jsDoc: '/**\n * Clear the current goal while retaining a durable tombstone and history.\n * @param agent - owning live agent.\n * @param ref - expected current revision.\n * @returns the tombstone ref whose revision is one past the cleared snapshot.\n */',
       },
+      {
+        signature: '@Remote(\'create\') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult',
+        jsDoc: '/**\n * Create one Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param request - objective and optional round cap.\n * @returns the created Goal identity.\n */',
+      },
+      {
+        signature: '@Remote(\'edit\') remoteExportEdit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView',
+        jsDoc: '/**\n * Edit one Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param ref - expected current revision.\n * @param request - replacement fields.\n * @returns the edited Goal view.\n */',
+      },
+      {
+        signature: '@Remote(\'pause\') remoteExportPause(agent: Agent, ref: GoalRef): GoalView',
+        jsDoc: '/**\n * Pause one Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param ref - expected current revision.\n * @returns the paused Goal view.\n */',
+      },
+      {
+        signature: '@Remote(\'resume\') remoteExportResume(agent: Agent, ref: GoalRef): GoalView',
+        jsDoc: '/**\n * Resume one Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param ref - expected current revision.\n * @returns the resumed Goal view.\n */',
+      },
+      {
+        signature: '@Remote(\'complete\') remoteExportComplete(agent: Agent, ref: GoalRef): GoalView',
+        jsDoc: '/**\n * Complete one Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param ref - expected current revision.\n * @returns the completed Goal view.\n */',
+      },
+      {
+        signature: '@Remote(\'clear\') remoteExportClear(agent: Agent, ref: GoalRef): GoalRef',
+        jsDoc: '/**\n * Clear one terminal Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param ref - expected current revision.\n * @returns the committed clear revision.\n */',
+      },
     ],
   },
   {
@@ -1859,6 +1883,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'CreateGoalRequest',
     declaration: 'export interface CreateGoalRequest {\n    readonly objective: string;\n    readonly maxGoalRounds?: number;\n}',
   },
+  {
+    name: 'CreateGoalResult',
+    declaration: 'export interface CreateGoalResult {\n    readonly ref: GoalRef;\n}',
+  },
   {
     name: 'CreateSessionOptions',
     declaration: 'export interface CreateSessionOptions {\n    readonly seed?: readonly SessionEvent[];\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly createdAt?: number;\n        readonly seedLength?: number;\n        readonly origin?: \'subagent\';\n        readonly delegationDepth?: number;\n    };\n}',
diff --git a/packages/goal/goal/package.json b/packages/goal/goal/package.json
index 397e5717ba..fccf7de3be 100644
--- a/packages/goal/goal/package.json
+++ b/packages/goal/goal/package.json
@@ -23,6 +23,14 @@
       "types": "./lib/types/client.d.ts",
       "default": "./lib/types/client.js"
     },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
@@ -30,7 +38,13 @@
     "lib/index.js",
     "lib/invariant.js",
     "lib/types/**/*.js",
-    "lib/types/**/*.d.ts"
+    "lib/types/**/*.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.host.d.ts",
+    "lib/typert.remote-client.js",
+    "lib/typert.remote-client.d.ts",
+    "lib/typert.remote-client.d.ts.map",
+    "src"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
@@ -41,6 +55,7 @@
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-scope": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-type-meta": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
@@ -56,6 +71,7 @@
     "@deepseek-ai/dsh-loader-smoke": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/goal/goal/src/index.ts b/packages/goal/goal/src/index.ts
index 87ea52018e..0997aad0dc 100644
--- a/packages/goal/goal/src/index.ts
+++ b/packages/goal/goal/src/index.ts
@@ -12,6 +12,7 @@ import type { ZodType } from 'zod'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { Remote, bindTypeRTGateway } from '@deepseek-ai/dsh-type-meta'
 // Type-only: resolves ctx.sessionProjections for the optional unit child.
 import type {} from '@deepseek-ai/dsh-session-projection'
 import {
@@ -189,6 +190,9 @@ export class GoalService extends Service {
   private readonly resolved: ResolvedConfig
   private readonly caches = new WeakMap<Session, GoalCache>()
 
+  /** Explicit participation in the TypeRT Gateway under the Cordis service key. */
+  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+
   constructor(ctx: Context, config: Config = {}) {
     super(ctx, 'goals')
     this.resolved = {
@@ -576,6 +580,7 @@ export class GoalService extends Service {
    * @param request - objective and optional round cap.
    * @returns the created Goal identity.
    */
+  @Remote('create')
   remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
     const view = this.create(agent, request)
     return { ref: { id: view.id, revision: view.revision } }
@@ -588,6 +593,7 @@ export class GoalService extends Service {
    * @param request - replacement fields.
    * @returns the edited Goal view.
    */
+  @Remote('edit')
   remoteExportEdit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView {
     return this.edit(agent, ref, request)
   }
@@ -598,6 +604,7 @@ export class GoalService extends Service {
    * @param ref - expected current revision.
    * @returns the paused Goal view.
    */
+  @Remote('pause')
   remoteExportPause(agent: Agent, ref: GoalRef): GoalView {
     return this.pause(agent, ref)
   }
@@ -608,6 +615,7 @@ export class GoalService extends Service {
    * @param ref - expected current revision.
    * @returns the resumed Goal view.
    */
+  @Remote('resume')
   remoteExportResume(agent: Agent, ref: GoalRef): GoalView {
     return this.resume(agent, ref)
   }
@@ -618,6 +626,7 @@ export class GoalService extends Service {
    * @param ref - expected current revision.
    * @returns the completed Goal view.
    */
+  @Remote('complete')
   remoteExportComplete(agent: Agent, ref: GoalRef): GoalView {
     return this.complete(agent, ref)
   }
@@ -628,6 +637,7 @@ export class GoalService extends Service {
    * @param ref - expected current revision.
    * @returns the committed clear revision.
    */
+  @Remote('clear')
   remoteExportClear(agent: Agent, ref: GoalRef): GoalRef {
     return this.clear(agent, ref)
   }
diff --git a/packages/goal/goal/tsconfig.json b/packages/goal/goal/tsconfig.json
index 9663f894fe..f106707bd3 100644
--- a/packages/goal/goal/tsconfig.json
+++ b/packages/goal/goal/tsconfig.json
@@ -35,6 +35,9 @@
     {
       "path": "../../session-projection/session-projection"
     },
+    {
+      "path": "../../typert/type-meta"
+    },
     {
       "path": "../../support/invariants"
     }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index caf1f8a5ba..d9a4453a61 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1131,6 +1131,9 @@ importers:
       '@deepseek-ai/dsh-client-modules':
         specifier: workspace:^
         version: link:../../client/modules
+      '@deepseek-ai/dsh-client-remotes':
+        specifier: workspace:^
+        version: link:../../client/remotes
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../../client/runtime
@@ -1345,6 +1348,21 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/client/remotes:
+    devDependencies:
+      '@deepseek-ai/dsh-goal':
+        specifier: workspace:^
+        version: link:../../goal/goal
+      '@deepseek-ai/dsh-host-api-gateway':
+        specifier: workspace:^
+        version: link:../../host/api-gateway
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/client/runtime:
     dependencies:
       '@deepseek-ai/dsh-client-connection':
@@ -1387,12 +1405,21 @@ importers:
         specifier: ~4.4.7
         version: 4.4.7(@types/react@18.3.31)(immer@10.2.0)(react@18.3.1)
     devDependencies:
+      '@deepseek-ai/dsh-client-remotes':
+        specifier: workspace:^
+        version: link:../remotes
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
       '@deepseek-ai/dsh-timeout':
         specifier: workspace:^
         version: link:../../util/timeout
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../../typert/type-meta
+      '@deepseek-ai/dsh-typert-registry':
+        specifier: workspace:^
+        version: link:../../typert/registry
       '@types/react':
         specifier: ~18.3.1
         version: 18.3.31
@@ -3509,6 +3536,9 @@ importers:
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
         version: link:../../session-projection/session-projection
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../../typert/type-meta
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 84013225f7..088329e83d 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -90,6 +90,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   FsWriteIntent: 'filesystem.md',
   FsWriteOutcome: 'filesystem.md',
   CreateGoalRequest: 'goal.md',
+  CreateGoalResult: 'goal.md',
   EditGoalRequest: 'goal.md',
   GoalBlockReason: 'goal.md',
   GoalChanged: 'goal.md',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 603ad20d8e..84b957e633 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -199,7 +199,7 @@
     {
       "doc": "docs/core-data-structures/goal.md",
       "symbol": "GoalView",
-      "source": "packages/goal/goal/src/domain.ts"
+      "source": "packages/goal/goal/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/goal.md",
@@ -219,12 +219,12 @@
     {
       "doc": "docs/core-data-structures/goal.md",
       "symbol": "CreateGoalRequest",
-      "source": "packages/goal/goal/src/domain.ts"
+      "source": "packages/goal/goal/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/goal.md",
       "symbol": "EditGoalRequest",
-      "source": "packages/goal/goal/src/domain.ts"
+      "source": "packages/goal/goal/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/goal.md",
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 7e81b30e07..78745dbed1 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -57,6 +57,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/web-react': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/schema-form': { kind: 'none', reason: 'Browser-side form-rendering library; registers no model surface.' },
   'packages/client/connection': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/remotes': { kind: 'none', reason: 'Client-side Remote assembly; selected business methods own any model-visible effect.' },
   'packages/client/runtime': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
diff --git a/tsconfig.client.json b/tsconfig.client.json
index b0567f762e..327b337963 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -53,6 +53,7 @@
     { "path": "./packages/client/connection" },
     { "path": "./packages/typert/registry" },
     { "path": "./packages/host/api-gateway" },
+    { "path": "./packages/client/remotes" },
     { "path": "./packages/client/runtime" },
     { "path": "./packages/client/test-runtime" },
     { "path": "./packages/client/ui-layout" },

From 4eff7510589a1661e114a7cef28b8db1733abe6b Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 16:13:45 +0800
Subject: [PATCH 121/516] test(client): mount TypeRT remote assembly in
 fixtures

---
 apps/web/tests/assembled-boot.ts              | 31 ++++++++++---------
 apps/web/tests/search-card.snapshot.ts        |  4 +--
 .../client/runtime/tests/wire-events.spec.ts  |  3 ++
 3 files changed, 22 insertions(+), 16 deletions(-)

diff --git a/apps/web/tests/assembled-boot.ts b/apps/web/tests/assembled-boot.ts
index 0e168ba9fe..ebb2aa513a 100644
--- a/apps/web/tests/assembled-boot.ts
+++ b/apps/web/tests/assembled-boot.ts
@@ -1,5 +1,5 @@
 // Shared scaffolding for the assembled-jsdom snapshots: the real built
-// `packages/client/*/lib/client.js` artifacts booted through AppWebEntry's
+// workspace `lib/client.js` artifacts booted through AppWebEntry's
 // ModuleLoader path (loadBundle) against the keyless FixtureApiClient
 // transport. Every file that mounts this graph needs the same boot entry list,
 // the same bundle map, the same jsdom globals, and the same mount call, and
@@ -14,18 +14,21 @@ import { afterEach, beforeEach, vi } from 'vitest'
 import type { WebBootEntry } from '@deepseek-ai/dsh-client-modules/client'
 import { AppWebEntry } from '@deepseek-ai/dsh-client-web'
 
-/** Boot entries for the minimal assembled graph, each carrying the workspace directory its bundle is read from. */
-const PLUGINS: readonly (WebBootEntry & { dir: string })[] = [
-  { id: '@deepseek-ai/dsh-client-connection', dir: 'connection', url: '/plugins/connection.js', rev: 'fx', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-runtime', dir: 'runtime', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection'], immediately: true },
-  { id: '@deepseek-ai/dsh-client-ui-theme', dir: 'ui-theme', url: '/plugins/ui-theme.js', rev: 'fx', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-locale', dir: 'locale', url: '/plugins/locale.js', rev: 'fx', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-ui-layout', dir: 'ui-layout', url: '/plugins/ui-layout.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime'] },
-  { id: '@deepseek-ai/dsh-client-ui-sidebar', dir: 'ui-sidebar', url: '/plugins/ui-sidebar.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
-  { id: '@deepseek-ai/dsh-client-ui-conversation', dir: 'ui-conversation', url: '/plugins/ui-conversation.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
+/** Boot entries for the minimal assembled graph, each carrying the workspace bundle it loads. */
+const PLUGINS: readonly (WebBootEntry & { bundlePath: string })[] = [
+  { id: '@deepseek-ai/dsh-typert-registry', bundlePath: 'packages/typert/registry/lib/client.js', url: '/plugins/typert-registry.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-connection', bundlePath: 'packages/client/connection/lib/client.js', url: '/plugins/connection.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-host-api-gateway', bundlePath: 'packages/host/api-gateway/lib/client.js', url: '/plugins/api-gateway.js', rev: 'fx', inject: ['@deepseek-ai/dsh-typert-registry', '@deepseek-ai/dsh-client-connection'], immediately: true },
+  { id: '@deepseek-ai/dsh-client-remotes', bundlePath: 'packages/client/remotes/lib/client.js', url: '/plugins/client-remotes.js', rev: 'fx', inject: ['@deepseek-ai/dsh-host-api-gateway'], immediately: true },
+  { id: '@deepseek-ai/dsh-client-runtime', bundlePath: 'packages/client/runtime/lib/client.js', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection', '@deepseek-ai/dsh-client-remotes', '@deepseek-ai/dsh-typert-registry'], immediately: true },
+  { id: '@deepseek-ai/dsh-client-ui-theme', bundlePath: 'packages/client/ui-theme/lib/client.js', url: '/plugins/ui-theme.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-locale', bundlePath: 'packages/client/locale/lib/client.js', url: '/plugins/locale.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-ui-layout', bundlePath: 'packages/client/ui-layout/lib/client.js', url: '/plugins/ui-layout.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime'] },
+  { id: '@deepseek-ai/dsh-client-ui-sidebar', bundlePath: 'packages/client/ui-sidebar/lib/client.js', url: '/plugins/ui-sidebar.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
+  { id: '@deepseek-ai/dsh-client-ui-conversation', bundlePath: 'packages/client/ui-conversation/lib/client.js', url: '/plugins/ui-conversation.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
   {
     id: '@deepseek-ai/dsh-client-ui-workspace',
-    dir: 'ui-workspace',
+    bundlePath: 'packages/client/ui-workspace/lib/client.js',
     url: '/plugins/ui-workspace.js',
     rev: 'fx',
     inject: [
@@ -34,12 +37,12 @@ const PLUGINS: readonly (WebBootEntry & { dir: string })[] = [
       '@deepseek-ai/dsh-client-ui-sidebar',
     ],
   },
-  { id: '@deepseek-ai/dsh-client-ui-trajectory', dir: 'ui-trajectory', url: '/plugins/ui-trajectory.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-conversation'] },
+  { id: '@deepseek-ai/dsh-client-ui-trajectory', bundlePath: 'packages/client/ui-trajectory/lib/client.js', url: '/plugins/ui-trajectory.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-conversation'] },
 ]
 
 const bundles = new Map(PLUGINS.map(plugin => [
   plugin.url,
-  readFileSync(join(process.cwd(), 'packages/client', plugin.dir, 'lib/client.js'), 'utf8'),
+  readFileSync(join(process.cwd(), plugin.bundlePath), 'utf8'),
 ]))
 
 interface FixtureWindow extends Window {
@@ -97,7 +100,7 @@ export function mountAssembledApp(): void {
   const root = document.createElement('div')
   root.id = 'root'
   document.body.appendChild(root)
-  win.__DSH_BOOT__ = { rev: 'fx', entries: PLUGINS.map(({ dir: _dir, ...plugin }) => plugin) }
+  win.__DSH_BOOT__ = { rev: 'fx', entries: PLUGINS.map(({ bundlePath: _bundlePath, ...plugin }) => plugin) }
   act(() => {
     const entry = new AppWebEntry(root, {
       loadBundle: async (url) => {
diff --git a/apps/web/tests/search-card.snapshot.ts b/apps/web/tests/search-card.snapshot.ts
index 626be993a6..8e6322c4af 100644
--- a/apps/web/tests/search-card.snapshot.ts
+++ b/apps/web/tests/search-card.snapshot.ts
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
-// Assembled search-card snapshot: boots the real built `packages/client/*/lib/
-// client.js` bundles through AppWebEntry's ModuleLoader path against the keyless
+// Assembled search-card snapshot: boots the real built workspace client bundles
+// through AppWebEntry's ModuleLoader path against the keyless
 // FixtureApiClient transport (no API key, no model round), opens the fixture
 // session, and pins the search card the `grep` turn (fixture turn 66) renders in
 // the assembled application. The built-boot smoke proves the graph boots but
diff --git a/packages/client/runtime/tests/wire-events.spec.ts b/packages/client/runtime/tests/wire-events.spec.ts
index f081eb54c1..5ab644682a 100644
--- a/packages/client/runtime/tests/wire-events.spec.ts
+++ b/packages/client/runtime/tests/wire-events.spec.ts
@@ -6,6 +6,7 @@
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import type { ConnectionHandle, ConnectionSinks } from '@deepseek-ai/dsh-client-connection/client'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import * as RuntimeClient from '../src/client/index.ts'
 import { FakeApiClient } from './fake-api.ts'
 
@@ -16,6 +17,7 @@ interface Bench {
 
 async function mount(): Promise<Bench> {
   const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
   const api = new FakeApiClient()
   const bench: Bench = { ctx, sinks: undefined }
   const handle: ConnectionHandle = {
@@ -30,6 +32,7 @@ async function mount(): Promise<Bench> {
     },
   }
   ctx.reflect.provide('connection', handle)
+  ctx.reflect.provide('api', {})
   await ctx.plugin(RuntimeClient).await()
   return bench
 }

From 36516e97b970c47b15504f6825d891b1f21bf864 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 16:41:24 +0800
Subject: [PATCH 122/516] feat(connection): dispatch TypeRT remotes through
 shared API

---
 ...08-02-typert-remote-method-calls.i18n.yaml |   4 +-
 .../2026-08-02-typert-remote-method-calls.md  |  73 ++++++-----
 ...026-08-02-typert-remote-method-calls.zh.md |  73 ++++++-----
 packages/client/connection/README.i18n.yaml   |   4 +-
 packages/client/connection/README.md          |   2 +-
 packages/client/connection/README.zh.md       |   2 +-
 .../connection/src/api-request-trust.ts       |   9 +-
 packages/client/connection/src/http-bridge.ts |   8 +-
 packages/client/connection/src/index.ts       |  66 +++++-----
 packages/client/connection/src/rpc-host.ts    |  74 ++++++++++-
 packages/client/connection/src/rpc.ts         |  22 +++-
 .../connection/tests/client-apply.spec.ts     |  28 ++---
 .../client/connection/tests/node-half.spec.ts | 118 +++++++++++++++---
 packages/host/api-gateway/README.i18n.yaml    |   4 +-
 packages/host/api-gateway/README.md           |   4 +-
 packages/host/api-gateway/README.zh.md        |   4 +-
 packages/host/api-gateway/src/client/index.ts |   2 +-
 packages/host/api-gateway/src/index.ts        |  45 ++++---
 .../host/api-gateway/tests/client.spec.ts     |   6 +-
 .../host/api-gateway/tests/gateway.spec.ts    |  73 +++++++++--
 20 files changed, 439 insertions(+), 182 deletions(-)

diff --git a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index cc2f0736d4..6e7a1a3a13 100644
--- a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: c3a7a77c583720c3f967de185a089d374f017d81
-2026-08-02-typert-remote-method-calls.zh.md: 9b2fbbd69f1c054cbf6c86f177b743c583be3e8a
+2026-08-02-typert-remote-method-calls.md: 61c8f61468621846fa8e8ff78d52313ae805aa17
+2026-08-02-typert-remote-method-calls.zh.md: 1e09965d2baba2db35301288f338cef15d947f36
diff --git a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md
index c3a7a77c58..61c8f61468 100644
--- a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md
@@ -20,7 +20,7 @@ A business Service declares callable methods with `@Remote` or `@RemoteContext()
 
 The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. The `.d.ts` exposes only methods marked with a Remote decorator and refers to the business package's single public type symbols. The `.d.ts.map` navigates consumer API methods back to their Host business method implementations. The `.js` carries endpoint, parameter, Context, and Zod information for the same contract. At the assembly layer, the Browser Client mounts the required Remote JS contributions onto the Client API Service. The projection and API abstraction remain platform-independent so that a future TUI can reuse them.
 
-`@deepseek-ai/dsh-host-api-gateway`, located at `packages/host/api-gateway`, provides two symmetric faces: its default entry provides Host `ctx.typertGateway`, while its `/client` entry provides consumer-side `ctx.api`. Each side consumes a locally generated `InvocationDescriptor` from the same model; descriptors are not sent over the wire. The Remote data protocol runs over the single Connection/RPC mechanism through an isolated `/api2` channel. The business calling interface does not change when Connection migrates from HTTP to WebSocket.
+`@deepseek-ai/dsh-host-api-gateway`, located at `packages/host/api-gateway`, provides two symmetric faces: its default entry provides Host `ctx.typertGateway`, while its `/client` entry provides consumer-side `ctx.api`. Each side consumes a locally generated `InvocationDescriptor` from the same model; descriptors are not sent over the wire. The Remote data protocol runs over Connection's shared `/api` RPC channel. The business calling interface does not change when Connection migrates from HTTP to WebSocket.
 
 ## Components and Cordis services
 
@@ -30,7 +30,7 @@ The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. T
 | TypeRT registry | `ctx.typert` | Separately stores reflection for the current environment, imported Remote contributions, lookup providers, and Context providers |
 | TypeRT generator/loader | No new business service | Generates three kinds of `lib` artifacts from the Host/Client Programs and registers the current environment's artifacts with `ctx.typert` |
 | Host API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, invokes methods, and encodes results |
-| Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, RPC envelope, rpcId, serialization, trust, and error transport, while carrying the isolated `/api` and `/api2` channels |
+| Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, the shared `/api` route, RPC envelope, rpcId, serialization, trust, error transport, TypeRT interception, and legacy API Proxy fallback |
 | Host API Gateway's Client face | `ctx.api` | Mounts Remote contributions, materializes root and scoped APIs, and delegates canonical calls to `ctx.connection.rpc` |
 | Client Remotes | No new service | Serves as the only Remote facade for Client business code, selecting and mounting `/remote` contributions while exposing the Gateway Client face and the selected API declarations |
 | Agent/Session owning packages | Existing domain services | Provide both static interface merges and runtime lookup/Context providers |
@@ -139,7 +139,7 @@ Parameter order comes from the method signature. HTTP fields come from parameter
 
 A LIB codec contains a Zod schema and a canonical `typeSymbol` consisting of "package + public subpath + export name." An SRC codec is marked only as `src-json`. When the Host and consumer run in different JavaScript realms, each holds its own Zod instances, but both sets are generated from the same TypeRT model and symbol keys.
 
-Descriptors exist only in the local registry on each side. The wire carries only the `/api2` channel, endpoint, and `{ args }` payload. The Host uses its descriptor to decode and invoke the method, while the Client uses its corresponding descriptor to encode arguments and validate the result.
+Descriptors exist only in the local registry on each side. The wire carries only the `/api` channel, endpoint, and `{ args }` payload. The Host uses its descriptor to decode and invoke the method, while the Client uses its corresponding descriptor to encode arguments and validate the result.
 
 ## TypeRT runtime registry
 
@@ -294,20 +294,20 @@ Client business packages depend only on `@deepseek-ai/dsh-client-remotes/client`
 
 `ctx.api.mount()` registers a contribution with `TypeRT.remotes`, and its disposer is owned by the Cordis fiber that called the method. Duplicate endpoints, conflicting invocation modes for the same namespace and method, or conflicts between a descriptor and an existing type identity fail immediately.
 
-The API Service materializes each `@Remote` descriptor as a real function on the root `api`. The function constructs named `args` in descriptor parameter order, applies the Client's strict codec, and then calls `ctx.connection.rpc.call('/api2', endpoint, { args })`.
+The API Service materializes each `@Remote` descriptor as a real function on the root `api`. The function constructs named `args` in descriptor parameter order, applies the Client's strict codec, and then calls `ctx.connection.rpc.call('/api', endpoint, { args })`.
 
-Neither a direct descriptor with `scope` nor a `@RemoteContext` descriptor copies functions into every Agent Scope. The API Service creates one root singleton Cordis Service for each scoped namespace and materializes methods on that Service. When `agent.goals.create()` is called, the Cordis tracker rebinds the Service's `this.ctx` to the current Agent Context. The method then asks the corresponding Context binder for identity from `this.ctx`. A direct scoped projection substitutes this identity at the lookup position named by `scope.wire`; a Context descriptor writes the identity into the receiver's separate wire field. Both issue the same kind of `/api2` call.
+Neither a direct descriptor with `scope` nor a `@RemoteContext` descriptor copies functions into every Agent Scope. The API Service creates one root singleton Cordis Service for each scoped namespace and materializes methods on that Service. When `agent.goals.create()` is called, the Cordis tracker rebinds the Service's `this.ctx` to the current Agent Context. The method then asks the corresponding Context binder for identity from `this.ctx`. A direct scoped projection substitutes this identity at the lookup position named by `scope.wire`; a Context descriptor writes the identity into the receiver's separate wire field. Both issue the same kind of `/api` call.
 
 ```text
 root ctx.api.goals.create(agentId, request)
   → direct descriptor
-  → ctx.connection.rpc.call('/api2', 'goals/create', { args })
+  → ctx.connection.rpc.call('/api', 'goals/create', { args })
 
 agent.goals.create(request)
   → tracker 将 namespace Service rebind 到 agent Context
   → agent binder 从 caller Context 取得 agentId
   → 用 agentId 补入同一 direct descriptor 的 lookup 参数
-  → ctx.connection.rpc.call('/api2', 'goals/create', { args })
+  → ctx.connection.rpc.call('/api', 'goals/create', { args })
 ```
 
 The Root `Context` does not merge the scoped `goals` type; only `AgentContext` gains that property through `RemoteContextApi<'agent'>`. If a caller bypasses the type system and dynamically calls a scoped method from Root, the binder reports an explicit error. If the Client already has a Cordis service with the same name, or two contributions claim the same namespace and method incompatibly, mounting fails instead of overwriting the existing service.
@@ -318,7 +318,7 @@ Generated Remote JS contains only descriptors, symbol keys, and codecs; it does
 
 Remote API is a consumer capability, not a synonym for Browser API. This phase implements only Browser Client contribution mounting, Connection RPC calls, and Agent Scope association.
 
-Remote DTS, Remote JS, `RemoteApi`, `InvocationDescriptor`, the Remote RPC data protocol, and Context binders must not depend on the DOM, Browser module loaders, or HTTP. Through Connection, the Browser Client encodes descriptor-materialized methods as `/api2` RPC calls.
+Remote DTS, Remote JS, `RemoteApi`, `InvocationDescriptor`, the Remote RPC data protocol, and Context binders must not depend on the DOM, Browser module loaders, or HTTP. Through Connection, the Browser Client encodes descriptor-materialized methods as `/api` RPC calls.
 
 A future TUI can join the same call abstraction without changing business decorators, Remote maps, or the shape of API calls. The TUI-visible API must still be generated exclusively from `@Remote` and `@RemoteContext`; sharing a process with the Host must not allow it to bypass Remote restrictions and expose Service methods directly.
 
@@ -363,22 +363,28 @@ ctx.typertGateway.invoke({ namespace, method, args })
 
 `ctx.typertGateway.invoke()` is the carrier-independent Host entry point. It neither creates an rpcId, RPC envelope, nor HTTP response. It returns only the encoded result or raises a Gateway error that the Connection RPC adapter maps for transport.
 
-## The `/api2` call chain
+## The shared `/api` call chain
 
-`/api2` is an isolated protocol channel on the single Connection/RPC mechanism, not a transport created by the Gateway. The Gateway registers one local handler with Connection. This phase adds the following general channel capability to the existing HTTP Connection:
+Connection owns one `/api` route on the HTTP Server. The Gateway mounts a synchronous endpoint ownership test and the Remote RPC handler into Connection:
 
 ```text
-ctx.connection.rpc.handle('/api2', (endpoint, payload) => {
-  const { namespace, method } = parseEndpoint(endpoint)
-  const { args } = parsePayload(payload)
-  return ctx.typertGateway.invoke({ namespace, method, args })
-})
+ctx.connection.rpc.intercept(
+  '/api',
+  endpoint => ownsRemoteEndpoint(endpoint),
+  (endpoint, payload) => {
+    const { namespace, method } = parseEndpoint(endpoint)
+    const { args } = parsePayload(payload)
+    return ctx.typertGateway.invoke({ namespace, method, args })
+  },
+)
 ```
 
-The Connection Host half obtains a handle from the single HTTP Server and reuses the same RPC bridge, request/response envelope, rpcId, serialization, trust, transport errors, and `RpcError`. Its current physical mapping is:
+The Gateway claims an endpoint when the Host registry contains its strict descriptor, remembers a withdrawn strict descriptor, or finds a matching `@Remote` marker on an active SRC Service binding. A claimed endpoint stays in the Gateway after payload decoding, descriptor resolution, or invocation fails; only an endpoint that is not Remote-owned reaches the legacy API Proxy fallback.
+
+The Connection Host half passes one composite FetchHandler to the HTTP bridge. After the bridge creates a standard `Request`, that handler selects either the Gateway RPC FetchHandler or the API Proxy FetchHandler. Both paths reuse the same request/response envelope, rpcId, serialization, trust, transport errors, and `RpcError`. The current physical mapping is:
 
 ```text
-POST /api2/<namespace>/<method>
+POST /api/<namespace>/<method>
 ```
 
 The Remote payload is a named JSON object, not a positional array, and does not carry an `InvocationDescriptor`. A normal Goal call has this payload slot:
@@ -399,11 +405,12 @@ The complete path is:
 ```text
 ctx.api.goals.create(sessionId, request)
 → Client InvocationDescriptor 编码 { args: { agentId, request } }
-→ ctx.connection.rpc.call('/api2', 'goals/create', { args })
+→ ctx.connection.rpc.call('/api', 'goals/create', { args })
 → Connection 创建 rpcId 和既有 client-request envelope
-→ 当前 carrier 发送 POST /api2/goals/create
-→ Connection Host half 执行 trust、反序列化和 RPC 分发
-→ /api2 handler 调用 ctx.typertGateway.invoke(...)
+→ 当前 carrier 发送 POST /api/goals/create
+→ Connection Host half 执行共享 trust，再由 bridge 创建标准 Request
+→ 复合 FetchHandler 判断 endpoint ownership 并选择目标 FetchHandler
+→ TypeRT interceptor 调用 ctx.typertGateway.invoke(...)
 → Host InvocationDescriptor 解码、lookup、receiver 解析和 Reflect.apply
 → result codec 编码
 → Connection 写入既有 RPC result 并回送相同 rpcId
@@ -412,30 +419,30 @@ ctx.api.goals.create(sessionId, request)
 
 Remote does not define a second-layer `{ ok, value/error }` response. Successful values and Gateway errors use the existing RPC response's `result` directly. The Gateway adapter maps endpoint, schema, lookup, Context, Service, and business-invocation failures to `RpcError`; Connection transports that error.
 
-The Gateway does not handle per-method permissions, caller identity, cancellation, idempotency, or long-lived connection state. This work only extends Connection with general channel registration and invocation capabilities. It does not change existing `/api`, trusted connection, trusted-host, or privileged-method semantics. Connection's WebSocket migration remains separate follow-up work.
+The Gateway does not handle per-method permissions, caller identity, cancellation, idempotency, or long-lived connection state. TypeRT endpoints use Connection's trusted-host policy; unclaimed endpoints retain the legacy API Proxy's trust and privileged-method policies. Connection's WebSocket migration remains separate follow-up work.
 
 ## Connection and protocol boundaries
 
-The API Service owns Remote contributions, method materialization, Scope binding, and the correspondence between positional parameters and descriptors. The Gateway owns Host descriptors, lookup, Context, and business invocation. Connection only sends `/api2`, the endpoint, and `{ args }` as one RPC call to the target and returns the existing RPC result; it does not understand Goal, Agent, lookup, descriptors, or Client API types.
+The API Service owns Remote contributions, method materialization, Scope binding, and the correspondence between positional parameters and descriptors. The Gateway owns Host descriptors, endpoint ownership, lookup, Context, and business invocation. Connection sends `/api`, the endpoint, and `{ args }` as one RPC call to the target and returns the existing RPC result; it does not understand Goal, Agent, lookup, descriptors, or Client API types.
 
-`/api` and `/api2` share one Connection, Server, RPC envelope, and connection lifecycle while remaining separate protocols. When Connection migrates from HTTP to WebSocket, `/api2` naturally changes from a physical path to a logical channel. The Remote payload, business decorators, generated DTS, Remote API types, and Agent Scope programming interface remain unchanged.
+The Gateway registers only its ownership matcher and RPC handler with Connection; it does not register an HTTP route. Connection mounts the shared `/api` route into the HTTP Server and gives the bridge one composite FetchHandler; that handler dispatches claimed endpoints to Gateway and unclaimed endpoints to API Proxy. A future Connection transport can preserve this order without changing the Remote payload, business decorators, generated DTS, Remote API types, or Agent Scope programming interface.
 
 ## Package boundaries
 
 - `@deepseek-ai/dsh-type-meta`: lightweight protocols for decorators, bindings, lookup, Remote Context, and descriptors.
 - TypeRT generator: analyzes Host/Client Programs, generates local faces and Remote consumer projections, and emits canonical symbol/Zod information.
 - TypeRT runtime: separately stores the current environment's local reflection and imported Remote contributions.
-- `@deepseek-ai/dsh-host-api-gateway`: its default entry associates Host definitions with Services, performs lookup, resolves Context receivers, invokes methods, encodes results, and registers an `/api2` handler with Connection; its `/client` entry mounts Remote contributions, creates strict API methods, and delegates calls to `ctx.connection.rpc`. The entries share the Remote protocol but do not import each other's Cordis interface merges.
+- `@deepseek-ai/dsh-host-api-gateway`: its default entry associates Host definitions with Services, claims Remote endpoints, performs lookup, resolves Context receivers, invokes methods, encodes results, and registers an `/api` interceptor with Connection; its `/client` entry mounts Remote contributions, creates strict API methods, and delegates calls to `ctx.connection.rpc`. The entries share the Remote protocol but do not import each other's Cordis interface merges.
 - `@deepseek-ai/dsh-client-remotes`: the only Remote facade depended on by Client business code; directly depends on the Gateway Client face, selects `/remote` contributions, and exposes the merged API types to business packages.
-- Connection: owns the single HTTP Server/future WebSocket carrier, RPC envelope, rpcId, serialization, trust, and error transport while carrying the isolated `/api` and `/api2` channels.
+- Connection: owns the single HTTP Server/future WebSocket carrier, shared `/api` route and composite FetchHandler, API Proxy fallback, RPC envelope, rpcId, serialization, trust, and error transport.
 - Business-object packages such as Agent/Session: own lookup, Context providers, canonical ID types, and public type-only entries.
 - Business Service packages: declare bindings, Remote methods, and their request/result types, and export the generated `/remote` subpath.
 
 ## Initial implementation scope
 
-The first vertical path implements `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api2 → Host Gateway → GoalService.remoteExportCreate()` and proves that the same direct descriptor with an Agent lookup supports both `ctx.api.goals.create(agentId, request)` and `agentCtx.goals.create(request)`. The scoped-receiver semantics of `@RemoteContext('agent')` remain a separate mode.
+The first vertical path implements `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()` and proves that the same direct descriptor with an Agent lookup supports both `ctx.api.goals.create(agentId, request)` and `agentCtx.goals.create(request)`. The scoped-receiver semantics of `@RemoteContext('agent')` remain a separate mode.
 
-This phase implements Connection's general second-channel API and its current HTTP carrier mapping, but not WebSocket migration, the TUI runtime, a TUI carrier, or TUI Agent Scope wiring. This RFC also does not design Permission/Approval state machines, Session event streams, call authorization, cancellation, retries, idempotency, or cross-version protocol compatibility.
+This phase implements Connection's shared-channel interceptor and current HTTP carrier mapping, but not WebSocket migration, the TUI runtime, a TUI carrier, or TUI Agent Scope wiring. This RFC also does not design Permission/Approval state machines, Session event streams, call authorization, cancellation, retries, idempotency, or cross-version protocol compatibility.
 
 ## Alternatives considered
 
@@ -455,7 +462,7 @@ This phase implements Connection's general second-channel API and its current HT
 
 **Let a top-level `/remote` import register global state implicitly.** The target Cordis Context may not exist when ESM evaluation occurs, and ownership becomes ambiguous across multiple Contexts, HMR, and disposal. A normal value import therefore returns only a contribution, which the environment assembly explicitly mounts through the API Service.
 
-**Create a separate transport, HTTP route, and response envelope for Remote.** This would duplicate the existing Connection's Server ownership, rpcId, serialization, trust, errors, and future WebSocket lifecycle, requiring two RPC stacks to migrate separately. `/api2` instead reuses the single Connection/RPC mechanism as an isolated protocol channel.
+**Create a separate transport, HTTP route, or `/api2` channel for Remote.** This would duplicate or split Connection's Server ownership, rpcId, serialization, trust, errors, and future WebSocket lifecycle. The shared `/api` interceptor instead keeps one physical route and lets Connection preserve API Proxy as the fallback FetchHandler.
 
 ## Acceptance criteria
 
@@ -465,10 +472,10 @@ This phase implements Connection's general second-channel API and its current HT
 - After the Client assembly mounts the JS contribution obtained from the same import, TypeRT can reflect endpoint, parameter, result, lookup, Context, and Zod information, and the API Service creates the calling method without a hand-written stub.
 - Remote DTS, Remote JS, `RemoteApi`, and the descriptor protocol do not depend on Browser-specific capabilities, and the type model cannot expose unmarked Goal Service methods, preserving the boundary required for future isomorphic TUI integration.
 - `agent.goals.*` obtains its call Scope through the Cordis tracker and Context binder. The Root Context has no Agent-only type, and functions are not copied into each Scope.
-- `/api2/goals/create` resolves `agentId` to the canonical Agent object, invokes the original Goal Service receiver, and returns the result through the existing RPC result/error mechanism.
-- `/api2` and `/api` share the single Connection/RPC carrier while remaining protocol-isolated. Remote neither registers an HTTP Server handle directly nor defines a second response envelope.
-- Connection provides general channel registration and invocation capabilities and maps `/api2` to the current HTTP carrier. Existing `/api` behavior and trust semantics remain unchanged.
-- This implementation does not change existing `/api`, Connection/trusted connection, Permission/Approval, or Session event stream behavior.
+- `/api/goals/create` resolves `agentId` to the canonical Agent object, invokes the original Goal Service receiver, and returns the result through the existing RPC result/error mechanism.
+- Gateway mounts into Connection, Connection mounts the single `/api` route into HTTP Server, and Remote defines neither an HTTP route nor a second response envelope.
+- Connection's composite FetchHandler dispatches a TypeRT-owned endpoint to Gateway and falls back to API Proxy only when Gateway does not claim it. A withdrawn strict endpoint remains claimed and fails as unavailable.
+- Existing API Proxy trust, privileged-method, Permission/Approval, and Session event stream behavior remains unchanged for unclaimed endpoints.
 
 ## Risks
 
diff --git a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 9b2fbbd69f..1e09965d2b 100644
--- a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -20,7 +20,7 @@ Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以
 
 Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client API Service；该投影和 API 抽象保持平台无关，以便未来 TUI 复用。
 
-`@deepseek-ai/dsh-host-api-gateway` 在 `packages/host/api-gateway` 内提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.api`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在唯一 Connection/RPC 机制之上，使用独立 `/api2` channel；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
+`@deepseek-ai/dsh-host-api-gateway` 在 `packages/host/api-gateway` 内提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.api`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在 Connection 共享的 `/api` RPC channel 上；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
 
 ## 组件和 Cordis 服务
 
@@ -30,7 +30,7 @@ Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只
 | TypeRT registry | `ctx.typert` | 分开保存当前环境 reflection、导入的 Remote contribution、lookup provider 和 Context provider |
 | TypeRT generator/loader | 无新增业务服务 | 从 Host/Client Program 生成三类 `lib` 产物，并把当前环境产物注册到 `ctx.typert` |
 | Host API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service，解码参数、解析 receiver、调用方法和编码结果 |
-| Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、RPC envelope、rpcId、序列化、trust 和错误传输，并承载 `/api` 与 `/api2` 两个隔离 channel |
+| Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、共享 `/api` route、RPC envelope、rpcId、序列化、trust、错误传输、TypeRT 拦截和旧 API Proxy 回退 |
 | Host API Gateway 的 Client face | `ctx.api` | mount Remote contribution，实体化根 API 和 scoped API，把规范调用交给 `ctx.connection.rpc` |
 | Client Remotes | 无新增服务 | 作为 Client 业务的唯一 Remote facade，选择并挂载 `/remote` contribution，同时传递 Gateway Client face 和所选 API 的类型声明 |
 | Agent/Session owning 包 | 既有领域服务 | 同时提供静态 interface merge 与运行时 lookup/Context provider |
@@ -139,7 +139,7 @@ InvocationDescriptor {
 
 LIB codec 带有 Zod schema 和“package + 公共 subpath + export name”的规范 `typeSymbol`；SRC codec 只标记 `src-json`。Host 和消费端运行在不同 JavaScript realm 时会各自持有 Zod 实例，但这些实例由同一 TypeRT 模型和 symbol key 生成。
 
-descriptor 只存在于两端本地 registry。wire 上只有 `/api2` channel、endpoint 和 `{ args }` payload；Host 用自己的 descriptor 解码和调用，Client 用自己的对应 descriptor 编码参数和验证结果。
+descriptor 只存在于两端本地 registry。wire 上只有 `/api` channel、endpoint 和 `{ args }` payload；Host 用自己的 descriptor 解码和调用，Client 用自己的对应 descriptor 编码参数和验证结果。
 
 ## TypeRT 运行时 registry
 
@@ -294,20 +294,20 @@ Client 业务包只引用 `@deepseek-ai/dsh-client-remotes/client`，不直接
 
 `ctx.api.mount()` 把 contribution 注册到 `TypeRT.remotes`，并由调用该方法的 Cordis fiber 持有 disposer。endpoint 重复、同一 namespace/method 模式冲突或 descriptor 与现有类型身份冲突时直接失败。
 
-API Service 把 `@Remote` descriptor 实体化为根 `api` 上的真实函数。函数按 descriptor 的位置参数顺序构造具名 `args`，执行 Client strict codec，然后调用 `ctx.connection.rpc.call('/api2', endpoint, { args })`。
+API Service 把 `@Remote` descriptor 实体化为根 `api` 上的真实函数。函数按 descriptor 的位置参数顺序构造具名 `args`，执行 Client strict codec，然后调用 `ctx.connection.rpc.call('/api', endpoint, { args })`。
 
-带 `scope` 的 direct descriptor 和 `@RemoteContext` descriptor 都不为每个 Agent Scope 复制函数。API Service 为每个 scoped namespace 建立一个 root singleton Cordis Service，并在该 Service 上实体化方法；Cordis tracker 在 `agent.goals.create()` 调用时把 Service 的 `this.ctx` rebind 到当前 Agent Context。方法再通过对应 Context binder 从 `this.ctx` 取得 identity。direct scoped 投影用 identity 替代 `scope.wire` 指定的 lookup 位置，Context descriptor 则把 identity 写入 receiver 的独立 wire 字段；两者都发起同一种 `/api2` 调用。
+带 `scope` 的 direct descriptor 和 `@RemoteContext` descriptor 都不为每个 Agent Scope 复制函数。API Service 为每个 scoped namespace 建立一个 root singleton Cordis Service，并在该 Service 上实体化方法；Cordis tracker 在 `agent.goals.create()` 调用时把 Service 的 `this.ctx` rebind 到当前 Agent Context。方法再通过对应 Context binder 从 `this.ctx` 取得 identity。direct scoped 投影用 identity 替代 `scope.wire` 指定的 lookup 位置，Context descriptor 则把 identity 写入 receiver 的独立 wire 字段；两者都发起同一种 `/api` 调用。
 
 ```text
 root ctx.api.goals.create(agentId, request)
   → direct descriptor
-  → ctx.connection.rpc.call('/api2', 'goals/create', { args })
+  → ctx.connection.rpc.call('/api', 'goals/create', { args })
 
 agent.goals.create(request)
   → tracker 将 namespace Service rebind 到 agent Context
   → agent binder 从 caller Context 取得 agentId
   → 用 agentId 补入同一 direct descriptor 的 lookup 参数
-  → ctx.connection.rpc.call('/api2', 'goals/create', { args })
+  → ctx.connection.rpc.call('/api', 'goals/create', { args })
 ```
 
 Root `Context` 不 merge scoped `goals` 类型；只有 `AgentContext` 通过 `RemoteContextApi<'agent'>` 获得该属性。若调用方绕过类型从 Root 动态调用 scoped 方法，binder 明确报错。若 Client 已有同名 Cordis service，或两个 contribution 冲突占用同一 namespace/method，mount 直接失败，不覆盖现有服务。
@@ -318,7 +318,7 @@ Root `Context` 不 merge scoped `goals` 类型；只有 `AgentContext` 通过 `R
 
 Remote API 是消费端能力，不等同于 Browser API。本期只实现 Browser Client 的 contribution 挂载、Connection RPC 调用和 Agent Scope 关联。
 
-Remote DTS、Remote JS、`RemoteApi`、`InvocationDescriptor`、Remote RPC 数据协议和 Context binder 不得依赖 DOM、Browser module loader 或 HTTP。Browser Client 通过 Connection 把 descriptor 实体化的方法编码为 `/api2` RPC 调用。
+Remote DTS、Remote JS、`RemoteApi`、`InvocationDescriptor`、Remote RPC 数据协议和 Context binder 不得依赖 DOM、Browser module loader 或 HTTP。Browser Client 通过 Connection 把 descriptor 实体化的方法编码为 `/api` RPC 调用。
 
 未来 TUI 可以在不改变业务 decorator、Remote maps 和 API 调用形状的前提下接入同一调用抽象。届时 TUI 可见的 API 仍只能由 `@Remote` 和 `@RemoteContext` 生成，不能因为它与 Host 同进程就绕过 Remote 限制直接暴露 Service 方法。
 
@@ -363,22 +363,28 @@ ctx.typertGateway.invoke({ namespace, method, args })
 
 `ctx.typertGateway.invoke()` 是 carrier-independent 的 Host 入口。它不创建 rpcId、RPC envelope 或 HTTP response；它只返回编码结果，或产生由 Connection RPC adapter 映射的 Gateway 错误。
 
-## `/api2` 调用链
+## 共享 `/api` 调用链
 
-`/api2` 是唯一 Connection/RPC 机制上的独立协议 channel，不是 Gateway 自建的 transport。Gateway 只向 Connection 注册一个本地 handler；本期在现有 HTTP Connection 中增加这项通用 channel 能力：
+Connection 在 HTTP Server 上持有唯一 `/api` route。Gateway 把同步 endpoint ownership 判断和 Remote RPC handler 挂到 Connection：
 
 ```text
-ctx.connection.rpc.handle('/api2', (endpoint, payload) => {
-  const { namespace, method } = parseEndpoint(endpoint)
-  const { args } = parsePayload(payload)
-  return ctx.typertGateway.invoke({ namespace, method, args })
-})
+ctx.connection.rpc.intercept(
+  '/api',
+  endpoint => ownsRemoteEndpoint(endpoint),
+  (endpoint, payload) => {
+    const { namespace, method } = parseEndpoint(endpoint)
+    const { args } = parsePayload(payload)
+    return ctx.typertGateway.invoke({ namespace, method, args })
+  },
+)
 ```
 
-Connection Host half 从唯一 HTTP Server 取得 handle，复用同一 RPC bridge、request/response envelope、rpcId、序列化、trust、transport error 和 `RpcError`。当前物理映射是：
+Host registry 中存在 strict descriptor、记录过已撤回的 strict descriptor，或 active SRC Service binding 上存在匹配的 `@Remote` 标记时，Gateway 认领该 endpoint。endpoint 一旦被认领，即使 payload 解码、descriptor 解析或调用失败也继续由 Gateway 返回错误；只有不属于 Remote 的 endpoint 才进入旧 API Proxy 回退。
+
+Connection Host half 把一个复合 FetchHandler 交给 HTTP bridge。bridge 创建标准 `Request` 后，该 handler 再选择 Gateway RPC FetchHandler 或 API Proxy FetchHandler；两条路径复用同一 request/response envelope、rpcId、序列化、trust、transport error 和 `RpcError`。当前物理映射是：
 
 ```text
-POST /api2/<namespace>/<method>
+POST /api/<namespace>/<method>
 ```
 
 Remote payload 使用具名 JSON 对象，不使用位置数组，也不发送 `InvocationDescriptor`。普通 Goal 调用的 payload slot 是：
@@ -399,11 +405,12 @@ Remote payload 使用具名 JSON 对象，不使用位置数组，也不发送 `
 ```text
 ctx.api.goals.create(sessionId, request)
 → Client InvocationDescriptor 编码 { args: { agentId, request } }
-→ ctx.connection.rpc.call('/api2', 'goals/create', { args })
+→ ctx.connection.rpc.call('/api', 'goals/create', { args })
 → Connection 创建 rpcId 和既有 client-request envelope
-→ 当前 carrier 发送 POST /api2/goals/create
-→ Connection Host half 执行 trust、反序列化和 RPC 分发
-→ /api2 handler 调用 ctx.typertGateway.invoke(...)
+→ 当前 carrier 发送 POST /api/goals/create
+→ Connection Host half 执行共享 trust，再由 bridge 创建标准 Request
+→ 复合 FetchHandler 判断 endpoint ownership 并选择目标 FetchHandler
+→ TypeRT interceptor 调用 ctx.typertGateway.invoke(...)
 → Host InvocationDescriptor 解码、lookup、receiver 解析和 Reflect.apply
 → result codec 编码
 → Connection 写入既有 RPC result 并回送相同 rpcId
@@ -412,30 +419,30 @@ ctx.api.goals.create(sessionId, request)
 
 Remote 不定义第二层 `{ ok, value/error }` response。成功值和 Gateway 错误直接使用既有 RPC response 的 `result`；Gateway adapter 负责把 endpoint、schema、lookup、Context、Service 和业务调用失败映射为 `RpcError`，Connection 负责传输该错误。
 
-Gateway 不处理逐方法权限、调用者身份、取消、幂等或长连接状态。本工作只扩展 Connection 的通用 channel 注册和调用能力，不改变现有 `/api`、trusted connection、trusted-host 或 privileged method 语义；Connection/WebSocket 迁移后续独立完成。
+Gateway 不处理逐方法权限、调用者身份、取消、幂等或长连接状态。TypeRT endpoint 使用 Connection 的 trusted-host 策略；未认领 endpoint 保留旧 API Proxy 的 trust 和 privileged-method 策略。Connection/WebSocket 迁移后续独立完成。
 
 ## Connection 与协议边界
 
-API Service 负责 Remote contribution、方法实体化、Scope 绑定以及位置参数与 descriptor 的对应。Gateway 负责 Host descriptor、lookup、Context 和业务调用。Connection 只负责把 `/api2`、endpoint 和 `{ args }` 作为一个 RPC 调用发送到目标并返回既有 RPC result；它不理解 Goal、Agent、lookup、descriptor 或 Client API 类型。
+API Service 负责 Remote contribution、方法实体化、Scope 绑定以及位置参数与 descriptor 的对应。Gateway 负责 Host descriptor、endpoint ownership、lookup、Context 和业务调用。Connection 把 `/api`、endpoint 和 `{ args }` 作为一个 RPC 调用发送到目标并返回既有 RPC result；它不理解 Goal、Agent、lookup、descriptor 或 Client API 类型。
 
-`/api` 与 `/api2` 共享唯一 Connection、Server、RPC envelope 和连接生命周期，但保持协议隔离。Connection 从 HTTP 迁移到 WebSocket 时，`/api2` 从物理路径自然变成逻辑 channel；Remote payload、业务 decorator、生成的 DTS、Remote API 类型和 Agent Scope 编程界面都不变化。
+Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 HTTP route。Connection 把共享 `/api` route 挂到 HTTP Server，并把一个复合 FetchHandler 交给 bridge；该 handler 将已认领 endpoint 分发给 Gateway，未认领 endpoint 则交给 API Proxy。未来 Connection transport 可以保留相同顺序，而不改变 Remote payload、业务 decorator、生成的 DTS、Remote API 类型或 Agent Scope 编程界面。
 
 ## 包边界
 
 - `@deepseek-ai/dsh-type-meta`：轻量 decorator、binding、lookup、Remote Context 和 descriptor 协议。
 - TypeRT generator：分析 Host/Client Program，生成本地 face 和 Remote 消费端投影，并生成规范 symbol/Zod 信息。
 - TypeRT runtime：分别保存当前环境的 local reflection 与导入的 Remote contribution。
-- `@deepseek-ai/dsh-host-api-gateway`：默认入口关联 Host definition 与 Service，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api2` handler；`/client` 入口挂载 Remote contribution，创建严格 API 方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
+- `@deepseek-ai/dsh-host-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 API 方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
 - `@deepseek-ai/dsh-client-remotes`：Client 业务唯一依赖的 Remote facade；直接依赖 Gateway Client face，选择 `/remote` contributions，并向业务包传递合并后的 API 类型。
-- Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、RPC envelope、rpcId、序列化、trust 和错误传输，同时承载隔离的 `/api` 与 `/api2` channel。
+- Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、共享 `/api` route 与复合 FetchHandler、API Proxy 回退、RPC envelope、rpcId、序列化、trust 和错误传输。
 - Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
 - 业务 Service 包：声明 binding、Remote 方法及其 request/result 类型，并导出生成的 `/remote` 子路径。
 
 ## 首期实现范围
 
-第一条纵向链路实现 `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api2 → Host Gateway → GoalService.remoteExportCreate()`，并证明同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.api.goals.create(agentId, request)` 与 `agentCtx.goals.create(request)`。`@RemoteContext('agent')` 的 scoped receiver 语义继续保留为独立模式。
+第一条纵向链路实现 `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`，并证明同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.api.goals.create(agentId, request)` 与 `agentCtx.goals.create(request)`。`@RemoteContext('agent')` 的 scoped receiver 语义继续保留为独立模式。
 
-本期实现 Connection 的通用第二 channel API 及当前 HTTP carrier 映射，但不实现 WebSocket 迁移、TUI runtime、TUI carrier 或 TUI Agent Scope 接线。本 RFC 也不设计 Permission/Approval 状态机、Session 事件流、调用授权、取消、重试、幂等和跨版本协议兼容。
+本期实现 Connection 的共享 channel interceptor 及当前 HTTP carrier 映射，但不实现 WebSocket 迁移、TUI runtime、TUI carrier 或 TUI Agent Scope 接线。本 RFC 也不设计 Permission/Approval 状态机、Session 事件流、调用授权、取消、重试、幂等和跨版本协议兼容。
 
 ## Alternatives considered
 
@@ -455,7 +462,7 @@ API Service 负责 Remote contribution、方法实体化、Scope 绑定以及位
 
 **让 `/remote` 的顶层 import 偷偷注册全局状态。** ESM 求值时未必已有目标 Cordis Context，多个 Context、HMR 和 dispose 也无法明确归属，因此普通 value import 只返回 contribution，由环境 assembly 的 API Service 显式挂载。
 
-**为 Remote 新建独立 transport、HTTP route 和响应信封。** 这会复制现有 Connection 的 Server ownership、rpcId、序列化、trust、错误和未来 WebSocket 生命周期，并让两个 RPC 栈分别迁移，因此 `/api2` 作为独立协议 channel 复用唯一 Connection/RPC 机制。
+**为 Remote 新建独立 transport、HTTP route 或 `/api2` channel。** 这会复制或拆分 Connection 的 Server ownership、rpcId、序列化、trust、错误和未来 WebSocket 生命周期。共享 `/api` interceptor 保留唯一物理 route，并让 Connection 继续以 API Proxy 作为回退 FetchHandler。
 
 ## Acceptance criteria
 
@@ -465,10 +472,10 @@ API Service 负责 Remote contribution、方法实体化、Scope 绑定以及位
 - Client assembly 挂载同一个 import 得到的 JS contribution 后，TypeRT 能反射 endpoint、参数、结果、lookup、Context 和 Zod 信息，API Service 无需手写 stub 即可创建调用方法。
 - Remote DTS、Remote JS、`RemoteApi` 和 descriptor 协议不依赖 Browser 专属能力，且类型模型无法暴露未标记的 Goal Service 方法，为未来 TUI 同构接入保留边界。
 - `agent.goals.*` 通过 Cordis tracker 和 Context binder 取得调用 Scope，Root Context 不获得 Agent-only 类型，且不为每个 Scope 复制函数。
-- `/api2/goals/create` 能把 `agentId` 解析为唯一 Agent 对象，调用原始 Goal Service receiver，并通过既有 RPC result/error 返回结果。
-- `/api2` 与 `/api` 共享唯一 Connection/RPC carrier，但保持协议隔离；Remote 不直接注册 HTTP Server handle，也不定义第二套 response envelope。
-- Connection 提供通用 channel 注册和调用能力，并把 `/api2` 映射到当前 HTTP carrier；现有 `/api` 行为与 trust 语义保持不变。
-- 现有 `/api`、Connection/trusted connection、Permission/Approval 和 Session 事件流行为不因本实现改变。
+- `/api/goals/create` 能把 `agentId` 解析为唯一 Agent 对象，调用原始 Goal Service receiver，并通过既有 RPC result/error 返回结果。
+- Gateway 挂到 Connection，Connection 把唯一 `/api` route 挂到 HTTP Server；Remote 不定义 HTTP route 或第二套 response envelope。
+- Connection 的复合 FetchHandler 将 TypeRT 认领的 endpoint 分发给 Gateway，仅在 Gateway 不认领时回退 API Proxy；已撤回的 strict endpoint 继续被认领并返回 unavailable。
+- 未认领 endpoint 保留既有 API Proxy trust、privileged-method、Permission/Approval 和 Session 事件流行为。
 
 ## Risks
 
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 05b9bb4141..ddfda12f4e 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
-README.md: 1393e79aacecbbf7b186f19e4c42269595854b0e
-README.zh.md: 70380ceba1b16b2970e947fb6cd9b2af9085ae51
+README.md: 161e34c4b6018625fb690e178eb9a9f8ac0ef21b
+README.zh.md: d17012cc89c02a1b11f16d126b7c0cafe67fb2a0
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index 1393e79aac..161e34c4b6 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md); the protocol contract is api-contracts v3 §3.
+Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. The Host half owns the single `/api` route and its Fetch bridge; a registered TypeRT interceptor claims its Remote endpoints before the API Proxy fallback. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md); the protocol contract is api-contracts v3 §3.
 
 ## /api browser-trust fence
 
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index 70380ceba1..d17012cc89 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议契约见 api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议契约见 api-contracts v3 §3。
 
 ## /api 浏览器信任栅栏
 
diff --git a/packages/client/connection/src/api-request-trust.ts b/packages/client/connection/src/api-request-trust.ts
index 4e897ccf87..141092c63b 100644
--- a/packages/client/connection/src/api-request-trust.ts
+++ b/packages/client/connection/src/api-request-trust.ts
@@ -16,12 +16,13 @@
 import type { IncomingHttpHeaders } from 'node:http'
 import { isLoopbackHostname } from './loopback-hostname.ts'
 
-/** The request facts the fence reads (structural subset of IncomingMessage). */
+/** The request facts the fence reads from either HTTP representation. */
 interface ApiTrustRequest {
-  headers: IncomingHttpHeaders
+  headers: IncomingHttpHeaders | Headers
 }
 
-function header(headers: IncomingHttpHeaders, name: string): string | undefined {
+function header(headers: IncomingHttpHeaders | Headers, name: string): string | undefined {
+  if (headers instanceof Headers) return headers.get(name) ?? undefined
   const value = headers[name]
   return typeof value === 'string' ? value : undefined
 }
@@ -88,7 +89,7 @@ function isTrustedAuthority(hostUrl: URL, trustedHosts: readonly string[]): bool
 
 /**
  * Decide whether one /api request may reach the RPC bridge.
- * @param request - node HTTP request facts (headers).
+ * @param request - Node HTTP or Fetch request facts (headers).
  * @param trustedHosts - non-loopback authorities this deployment serves: exact `host:port`, or port-less `host` matching any port.
  * @returns true when the Host is ours (loopback or trusted) and any attached browser markers are same-origin.
  */
diff --git a/packages/client/connection/src/http-bridge.ts b/packages/client/connection/src/http-bridge.ts
index 88d577bef8..cdf8d12bfe 100644
--- a/packages/client/connection/src/http-bridge.ts
+++ b/packages/client/connection/src/http-bridge.ts
@@ -5,7 +5,13 @@
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
-interface FetchHandler {
+/** Transport-independent request handler consumed by the Host HTTP bridge. */
+export interface FetchHandler {
+  /**
+   * Handle one standard Fetch request.
+   * @param request - request produced by the active transport bridge.
+   * @returns complete or streaming Fetch response.
+   */
   fetch(request: Request): Promise<Response>
 }
 
diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts
index d8b6ef8846..aefdcdadf4 100644
--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -12,6 +12,7 @@ import { rejectWebSocketUpgrade, WebSocketDownlinks } from './websocket-downlink
 
 export type {
   ConnectionRpcAuthority,
+  ConnectionRpcEndpointMatcher,
   ConnectionRpcHandler,
   ConnectionRpcHandlerOptions,
   HostConnectionHandle,
@@ -24,7 +25,7 @@ export { API_PATH, HOST_EVENTS_PATH, MUX_EVENTS_PATH } from './api-path.ts'
 /** Stable Cordis plugin name. */
 export const name = 'client-connection'
 
-/** Services required before providing Connection; legacy `/api` attaches when apiProxy is present. */
+/** Services required before providing Connection; API Proxy is an optional `/api` fallback. */
 export const inject = ['httpServer']
 
 /** Plugin config: the deployment's non-loopback serving authorities. */
@@ -93,35 +94,44 @@ export function apply(ctx: Context, config?: ConnectionConfig): void {
   // Config boundary: a malformed entry fails the load loudly here rather than
   // silently authorizing its hostname prefix at request time.
   for (const entry of trustedHosts) assertTrustedAuthority(entry)
-  new HostConnectionService(ctx, trustedHosts)
+  const connection = new HostConnectionService(ctx, trustedHosts)
+  const fetchHandler = connection.createSharedFetchHandler(API_PATH, {
+    async fetch(request) {
+      const pathname = new URL(request.url).pathname
+      const method = pathname.startsWith(`${API_PATH}/`)
+        ? pathname.slice(API_PATH.length + 1)
+        : undefined
+      if (method !== undefined
+        && PRIVILEGED_METHODS.has(method)
+        && !isTrustedApiRequest(request, [])) {
+        return new Response('forbidden', { status: 403 })
+      }
+      if (request.method === 'GET' && (pathname === MUX_EVENTS_PATH || pathname === HOST_EVENTS_PATH)) {
+        return new Response('upgrade required', {
+          status: 426,
+          headers: { connection: 'Upgrade', upgrade: 'websocket' },
+        })
+      }
+      const apiProxy = ctx.get('apiProxy')
+      if (apiProxy === undefined) return new Response('not found', { status: 404 })
+      return toFetchHandler(apiProxy).fetch(request)
+    },
+  })
+  const route: WebRoute = {
+    kind: 'prefix',
+    path: API_PATH,
+    handler: async (req, res) => {
+      if (!isTrustedApiRequest(req, trustedHosts)) {
+        res.writeHead(403)
+        res.end('forbidden')
+        return
+      }
+      await bridge(req, res, fetchHandler)
+    },
+  }
+  ctx.effect(() => ctx.httpServer.register(route), 'client-connection: /api route')
   ctx.inject(['apiProxy'], (apiCtx) => {
-    const apiHandler = toFetchHandler(apiCtx.apiProxy)
     const downlinks = new WebSocketDownlinks(apiCtx.apiProxy)
-    const route: WebRoute = {
-      kind: 'prefix',
-      path: API_PATH,
-      handler: async (req, res) => {
-        const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
-        const method = pathname.startsWith(`${API_PATH}/`)
-          ? pathname.slice(API_PATH.length + 1)
-          : undefined
-        const allowed = method !== undefined && PRIVILEGED_METHODS.has(method)
-          ? isTrustedApiRequest(req, [])
-          : isTrustedApiRequest(req, trustedHosts)
-        if (!allowed) {
-          res.writeHead(403)
-          res.end('forbidden')
-          return
-        }
-        if (req.method === 'GET' && (pathname === MUX_EVENTS_PATH || pathname === HOST_EVENTS_PATH)) {
-          res.writeHead(426, { connection: 'Upgrade', upgrade: 'websocket' })
-          res.end('upgrade required')
-          return
-        }
-        await bridge(req, res, apiHandler)
-      },
-    }
-    apiCtx.effect(() => apiCtx.httpServer.register(route), 'client-connection: /api route')
     const registerDownlink = (
       path: string,
       handle: WebUpgradeRoute['handler'],
diff --git a/packages/client/connection/src/rpc-host.ts b/packages/client/connection/src/rpc-host.ts
index a6fbdb0264..7d3e5ff6f5 100644
--- a/packages/client/connection/src/rpc-host.ts
+++ b/packages/client/connection/src/rpc-host.ts
@@ -11,9 +11,11 @@ import {
   type RpcId as RpcIdType,
   type ServerResponse as RpcServerResponse,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
-import { bridge } from './http-bridge.ts'
+import { bridge, type FetchHandler } from './http-bridge.ts'
 import { isTrustedApiRequest } from './api-request-trust.ts'
+import { API_PATH } from './api-path.ts'
 import type {
+  ConnectionRpcEndpointMatcher,
   ConnectionRpcHandler,
   ConnectionRpcHandlerOptions,
   HostConnectionHandle,
@@ -24,8 +26,23 @@ const INVALID_REQUEST_RPC_ID = RpcId('invalid-request')
 const CHANNEL_PATTERN = /^\/[A-Za-z0-9._~-]+$/
 const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
 
+interface ConnectionRpcInterceptor {
+  readonly matches: ConnectionRpcEndpointMatcher
+  readonly fetchHandler: FetchHandler
+  readonly options: ConnectionRpcHandlerOptions
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** Host Connection transport and RPC registrations. */
+    connection: HostConnectionHandle
+  }
+}
+
 /** Host Connection service whose channel registrations belong to the caller fiber. */
 export class HostConnectionService extends Service implements HostConnectionHandle {
+  private readonly interceptors = new Map<string, ConnectionRpcInterceptor>()
+
   /**
    * Provide the Host half over the active HTTP server.
    * @param ctx - owning Connection plugin context.
@@ -40,6 +57,33 @@ export class HostConnectionService extends Service implements HostConnectionHand
     const owner = this.ctx
     return {
       handle: (channel, handler, options) => this.register(owner, channel, handler, options),
+      intercept: (channel, matches, handler, options) =>
+        this.registerInterceptor(owner, channel, matches, handler, options),
+    }
+  }
+
+  /**
+   * Compose one shared-channel Fetch handler from its interceptor and fallback.
+   * @param channel - shared channel mounted by Connection.
+   * @param fallback - handler for endpoints not claimed by the interceptor.
+   * @returns Fetch handler that selects exactly one target for each request.
+   */
+  createSharedFetchHandler(
+    channel: '/api',
+    fallback: FetchHandler,
+  ): FetchHandler {
+    return {
+      fetch: (request) => {
+        const endpoint = endpointFromPath(channel, new URL(request.url).pathname)
+        const interceptor = this.interceptors.get(channel)
+        if (endpoint === undefined || interceptor === undefined || !interceptor.matches(endpoint)) {
+          return fallback.fetch(request)
+        }
+        if (interceptor.options.authority === 'loopback' && !isTrustedApiRequest(request, [])) {
+          return Promise.resolve(new Response('forbidden', { status: 403 }))
+        }
+        return interceptor.fetchHandler.fetch(request)
+      },
     }
   }
 
@@ -69,12 +113,38 @@ export class HostConnectionService extends Service implements HostConnectionHand
       `client-connection: ${channel} rpc channel`,
     )
   }
+
+  private registerInterceptor(
+    owner: Context,
+    channel: string,
+    matches: ConnectionRpcEndpointMatcher,
+    handler: ConnectionRpcHandler,
+    options: ConnectionRpcHandlerOptions,
+  ): () => Promise<void> {
+    if (channel !== API_PATH) {
+      throw new Error(`connection: invalid shared RPC channel ${JSON.stringify(channel)}`)
+    }
+    const interceptor: ConnectionRpcInterceptor = {
+      matches,
+      fetchHandler: rpcFetchHandler(channel, handler),
+      options,
+    }
+    return owner.effect(() => {
+      if (this.interceptors.has(channel)) {
+        throw new Error(`connection: shared RPC channel ${JSON.stringify(channel)} already has an interceptor`)
+      }
+      this.interceptors.set(channel, interceptor)
+      return () => {
+        this.interceptors.delete(channel)
+      }
+    }, `client-connection: ${channel} rpc interceptor`)
+  }
 }
 
 function rpcFetchHandler(
   channel: string,
   handler: ConnectionRpcHandler,
-): { fetch(request: Request): Promise<Response> } {
+): FetchHandler {
   return {
     async fetch(request: Request): Promise<Response> {
       const endpoint = endpointFromPath(channel, new URL(request.url).pathname)
diff --git a/packages/client/connection/src/rpc.ts b/packages/client/connection/src/rpc.ts
index ab68783724..e1260f00e8 100644
--- a/packages/client/connection/src/rpc.ts
+++ b/packages/client/connection/src/rpc.ts
@@ -18,11 +18,14 @@ export type ConnectionRpcHandler = (
   signal: AbortSignal,
 ) => Promise<RpcResult<unknown>>
 
+/** Synchronous ownership test for one endpoint on a shared RPC channel. */
+export type ConnectionRpcEndpointMatcher = (endpoint: string) => boolean
+
 /** Host registry for logical RPC channels carried by the current transport. */
 export interface HostConnectionRpc {
   /**
    * Register one absolute channel prefix and its trust policy.
-   * @param channel - absolute logical channel such as `/api2`.
+   * @param channel - absolute logical channel such as `/rpc`.
    * @param handler - decoded endpoint handler returning the existing RPC result shape.
    * @param options - channel trust policy.
    * @returns asynchronous disposer removing the channel and its physical route.
@@ -32,6 +35,21 @@ export interface HostConnectionRpc {
     handler: ConnectionRpcHandler,
     options: ConnectionRpcHandlerOptions,
   ): () => Promise<void>
+
+  /**
+   * Intercept owned endpoints on the shared `/api` channel before its fallback.
+   * @param channel - reserved shared channel; currently `/api`.
+   * @param matches - synchronous endpoint ownership test.
+   * @param handler - decoded endpoint handler returning the existing RPC result shape.
+   * @param options - trust policy for every endpoint claimed by this interceptor.
+   * @returns asynchronous disposer removing the interceptor.
+   */
+  intercept(
+    channel: '/api',
+    matches: ConnectionRpcEndpointMatcher,
+    handler: ConnectionRpcHandler,
+    options: ConnectionRpcHandlerOptions,
+  ): () => Promise<void>
 }
 
 /** Host `ctx.connection` shape consumed by transport-independent adapters. */
@@ -44,7 +62,7 @@ export interface HostConnectionHandle {
 export interface ClientConnectionRpc {
   /**
    * Call one endpoint through an already registered logical channel.
-   * @param channel - absolute logical channel such as `/api2`.
+   * @param channel - absolute logical channel such as `/api`.
    * @param endpoint - channel-relative endpoint such as `goals/create`.
    * @param payload - channel-owned request payload.
    * @param signal - optional caller cancellation.
diff --git a/packages/client/connection/tests/client-apply.spec.ts b/packages/client/connection/tests/client-apply.spec.ts
index 3ce8b89ecb..6bf9c26b46 100644
--- a/packages/client/connection/tests/client-apply.spec.ts
+++ b/packages/client/connection/tests/client-apply.spec.ts
@@ -204,7 +204,7 @@ describe('connection client apply', () => {
     expect(sockets[0]?.readyState).toBe(FakeWebSocket.CLOSED)
   })
 
-  it('carries generic RPC calls over the isolated channel with rpcId echo validation', async () => {
+  it('carries RPC calls over the shared API channel with rpcId echo validation', async () => {
     ;(globalThis as Win).location = { hostname: 'localhost', search: '' }
     const handle = await mount()
     const original = globalThis.fetch
@@ -221,13 +221,13 @@ describe('connection client apply', () => {
       })
     }
     try {
-      await expect(handle.rpc.call('/api2', 'goals/create', { args: { agentId: 'agent-1' } }))
+      await expect(handle.rpc.call('/api', 'goals/create', { args: { agentId: 'agent-1' } }))
         .resolves.toEqual({ ok: true, value: { ref: 'goal-1' } })
     } finally {
       globalThis.fetch = original
     }
     expect(seen).toHaveLength(1)
-    expect(seen[0]?.url).toBe('http://dsh.internal/api2/goals/create')
+    expect(seen[0]?.url).toBe('http://dsh.internal/api/goals/create')
     expect(seen[0]?.body).toMatchObject({
       type: 'client-request',
       method: 'goals/create',
@@ -244,10 +244,10 @@ describe('connection client apply', () => {
     const abort = new AbortController()
     globalThis.fetch = vi.fn().mockResolvedValue(new Response('unavailable', { status: 503 }))
     try {
-      await expect(handle.rpc.call('/api2', 'goals/create', {}, abort.signal))
+      await expect(handle.rpc.call('/api', 'goals/create', {}, abort.signal))
         .rejects.toThrow('HTTP 503')
       expect(globalThis.fetch).toHaveBeenCalledWith(
-        new URL('https://harness.example/api2/goals/create'),
+        new URL('https://harness.example/api/goals/create'),
         expect.objectContaining({ signal: abort.signal }),
       )
 
@@ -257,9 +257,9 @@ describe('connection client apply', () => {
         rpcId: 'different-rpc',
         result: { ok: true, value: null },
       }))
-      await expect(handle.rpc.call('/api2', 'goals/create', {})).rejects.toThrow('rpcId mismatch')
+      await expect(handle.rpc.call('/api', 'goals/create', {})).rejects.toThrow('rpcId mismatch')
       const fetch = vi.mocked(globalThis.fetch)
-      expect(fetch.mock.calls[0]?.[0]).toEqual(new URL('http://dsh.internal/api2/goals/create'))
+      expect(fetch.mock.calls[0]?.[0]).toEqual(new URL('http://dsh.internal/api/goals/create'))
       expect(fetch.mock.calls[0]?.[1]).not.toHaveProperty('signal')
     } finally {
       globalThis.fetch = original
@@ -267,12 +267,12 @@ describe('connection client apply', () => {
 
     for (const [channel, endpoint] of [
       ['api2', 'goals/create'],
-      ['/api2/path', 'goals/create'],
-      ['/api2', ''],
-      ['/api2', '.'],
-      ['/api2', '..'],
-      ['/api2', 'goals//create'],
-      ['/api2', 'goals/create?unsafe'],
+      ['/api/path', 'goals/create'],
+      ['/api', ''],
+      ['/api', '.'],
+      ['/api', '..'],
+      ['/api', 'goals//create'],
+      ['/api', 'goals/create?unsafe'],
     ] as const) {
       await expect(handle.rpc.call(channel, endpoint, {})).rejects.toThrow('invalid RPC target')
     }
@@ -281,6 +281,6 @@ describe('connection client apply', () => {
   it('keeps generic Remote calls unavailable in the client-only fixture', async () => {
     ;(globalThis as Win).location = { hostname: 'localhost', search: '?fixture' }
     const handle = await mount()
-    await expect(handle.rpc.call('/api2', 'goals/create', {})).rejects.toThrow(/unavailable in fixture mode/)
+    await expect(handle.rpc.call('/api', 'goals/create', {})).rejects.toThrow(/unavailable in fixture mode/)
   })
 })
diff --git a/packages/client/connection/tests/node-half.spec.ts b/packages/client/connection/tests/node-half.spec.ts
index 1c42a9dc88..59ab8e6102 100644
--- a/packages/client/connection/tests/node-half.spec.ts
+++ b/packages/client/connection/tests/node-half.spec.ts
@@ -195,35 +195,36 @@ describe('connection node half', () => {
     await dispose()
   })
 
-  it('provides a disposable generic RPC channel without requiring apiProxy', async () => {
+  it('provides a disposable dedicated RPC channel without requiring apiProxy', async () => {
     const ctx = new Context()
     const routes: WebRoute[] = []
     ctx.provide('httpServer', fakeHttpServer(routes, []) as HttpServerService)
     const fiber = ctx.plugin({ inject: [...inject], apply })
     await fiber.await()
-    expect(routes).toHaveLength(0)
+    expect(routes).toHaveLength(1)
+    expect(routes[0]).toMatchObject({ kind: 'prefix', path: API_PATH })
 
     const connection = ctx.get('connection') as HostConnectionHandle
     const calls: unknown[] = []
-    const remove = connection.rpc.handle('/api2', async (endpoint, payload) => {
+    const remove = connection.rpc.handle('/rpc', async (endpoint, payload) => {
       calls.push({ endpoint, payload })
       return { ok: true, value: { accepted: true } }
     }, { authority: 'trusted-host' })
-    const route = routes.find(candidate => candidate.path === '/api2')
+    const route = routes.find(candidate => candidate.path === '/rpc')
     expect(route).toBeDefined()
 
     const request: ClientRequest = {
       type: 'client-request',
-      rpcId: RpcId('rpc-api2'),
+      rpcId: RpcId('rpc-dedicated'),
       method: 'goals/create',
       payload: { args: { agentId: 'agent-1' } },
     }
     const result = fakeResponse()
-    await route!.handler(fakePost({ host: '127.0.0.1:3080' }, '/api2/goals/create', request), result.response)
+    await route!.handler(fakePost({ host: '127.0.0.1:3080' }, '/rpc/goals/create', request), result.response)
     expect(result.state.status).toBe(200)
     expect(JSON.parse(String(result.state.body))).toEqual({
       type: 'server-response',
-      rpcId: 'rpc-api2',
+      rpcId: 'rpc-dedicated',
       result: { ok: true, value: { accepted: true } },
     })
     expect(calls).toEqual([{
@@ -231,11 +232,90 @@ describe('connection node half', () => {
       payload: { args: { agentId: 'agent-1' } },
     }])
 
-    expect(() => connection.rpc.handle('/api2', async () => ({ ok: true, value: null }), {
+    expect(() => connection.rpc.handle('/rpc', async () => ({ ok: true, value: null }), {
       authority: 'trusted-host',
     })).toThrow(/duplicate route/)
     await remove()
+    expect(routes.map(candidate => candidate.path)).toEqual([API_PATH])
+    await fiber.dispose()
     expect(routes).toHaveLength(0)
+  })
+
+  it('dispatches claimed /api endpoints before the API Proxy fallback and withdraws the claim', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    ctx.provide('httpServer', fakeHttpServer(routes, []) as HttpServerService)
+    ctx.provide('apiProxy', {} as unknown as ApiProxy)
+    const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.example'] })
+    await fiber.await()
+    const connection = ctx.get('connection') as HostConnectionHandle
+    const calls: unknown[] = []
+    const remove = connection.rpc.intercept(
+      '/api',
+      endpoint => endpoint === 'goals/create',
+      async (endpoint, payload) => {
+        calls.push({ endpoint, payload })
+        return { ok: true, value: { accepted: true } }
+      },
+      { authority: 'trusted-host' },
+    )
+    expect(() => connection.rpc.intercept(
+      '/api',
+      () => true,
+      async () => ({ ok: true, value: null }),
+      { authority: 'trusted-host' },
+    )).toThrow('already has an interceptor')
+    expect(() => connection.rpc.intercept(
+      '/rpc' as '/api',
+      () => true,
+      async () => ({ ok: true, value: null }),
+      { authority: 'trusted-host' },
+    )).toThrow('invalid shared RPC channel')
+    const route = routes.find(candidate => candidate.path === API_PATH)!
+    const request: ClientRequest = {
+      type: 'client-request',
+      rpcId: RpcId('rpc-shared'),
+      method: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }
+
+    const claimed = fakeResponse()
+    await route.handler(fakePost({ host: '127.0.0.1:3080' }, '/api/goals/create', request), claimed.response)
+    expect(JSON.parse(String(claimed.state.body))).toEqual({
+      type: 'server-response',
+      rpcId: 'rpc-shared',
+      result: { ok: true, value: { accepted: true } },
+    })
+    expect(calls).toEqual([{
+      endpoint: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }])
+
+    const denied = fakeResponse()
+    await route.handler(fakePost({ host: 'other.example' }, '/api/goals/create', request), denied.response)
+    expect(denied.state).toMatchObject({ status: 403, body: 'forbidden' })
+    expect(calls).toHaveLength(1)
+
+    const unclaimed = fakeResponse()
+    await route.handler(fakeRequest({ host: '127.0.0.1:3080' }, '/api/session.list'), unclaimed.response)
+    expect(unclaimed.state.status).toBe(404)
+
+    await remove()
+    const withdrawn = fakeResponse()
+    await route.handler(fakePost({ host: '127.0.0.1:3080' }, '/api/goals/create', request), withdrawn.response)
+    expect(withdrawn.state.status).toBe(404)
+    expect(calls).toHaveLength(1)
+
+    const removeLoopback = connection.rpc.intercept(
+      '/api',
+      endpoint => endpoint === 'goals/create',
+      async () => ({ ok: true, value: null }),
+      { authority: 'loopback' },
+    )
+    const loopbackOnly = fakeResponse()
+    await route.handler(fakePost({ host: 'harness.example' }, '/api/goals/create', request), loopbackOnly.response)
+    expect(loopbackOnly.state.status).toBe(403)
+    await removeLoopback()
     await fiber.dispose()
   })
 
@@ -246,20 +326,20 @@ describe('connection node half', () => {
     const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.example'] })
     await fiber.await()
     const connection = ctx.get('connection') as HostConnectionHandle
-    const remove = connection.rpc.handle('/api2', async (endpoint) => {
+    const remove = connection.rpc.handle('/rpc', async (endpoint) => {
       if (endpoint === 'fail') throw new Error('handler broke')
       return { ok: true, value: null }
     }, {
       authority: 'trusted-host',
     })
-    const route = routes[0]!
+    const route = routes.find(candidate => candidate.path === '/rpc')!
 
     const denied = fakeResponse()
-    await route.handler(fakePost({ host: 'other.example' }, '/api2/goals/create', {}), denied.response)
+    await route.handler(fakePost({ host: 'other.example' }, '/rpc/goals/create', {}), denied.response)
     expect(denied.state).toMatchObject({ status: 403, body: 'forbidden' })
 
     const methodMismatch = fakeResponse()
-    await route.handler(fakePost({ host: 'harness.example' }, '/api2/goals/create', {
+    await route.handler(fakePost({ host: 'harness.example' }, '/rpc/goals/create', {
       type: 'client-request', rpcId: 'rpc-bad', method: 'other', payload: {},
     }), methodMismatch.response)
     expect(JSON.parse(String(methodMismatch.state.body))).toMatchObject({
@@ -268,12 +348,12 @@ describe('connection node half', () => {
     })
 
     for (const [request, status] of [
-      [fakeRequest({ host: 'harness.example' }, '/api2/goals/create'), 404],
+      [fakeRequest({ host: 'harness.example' }, '/rpc/goals/create'), 404],
       [fakePost({ host: 'harness.example' }, '/outside/goals/create', {}), 404],
-      [fakePost({ host: 'harness.example' }, '/api2/goals//create', {}), 404],
-      [fakeRawPost({ host: 'harness.example' }, '/api2/goals/create', '{}'), 415],
-      [fakeRawPost({ host: 'harness.example', 'content-type': 'text/plain' }, '/api2/goals/create', '{}'), 415],
-      [fakeRawPost({ host: 'harness.example', 'content-type': 'application/json; charset=utf-8' }, '/api2/goals/create', '{'), 400],
+      [fakePost({ host: 'harness.example' }, '/rpc/goals//create', {}), 404],
+      [fakeRawPost({ host: 'harness.example' }, '/rpc/goals/create', '{}'), 415],
+      [fakeRawPost({ host: 'harness.example', 'content-type': 'text/plain' }, '/rpc/goals/create', '{}'), 415],
+      [fakeRawPost({ host: 'harness.example', 'content-type': 'application/json; charset=utf-8' }, '/rpc/goals/create', '{'), 400],
     ] as const) {
       const response = fakeResponse()
       await route.handler(request, response.response)
@@ -286,7 +366,7 @@ describe('connection node half', () => {
       [null, 'invalid-request'],
     ] as const) {
       const response = fakeResponse()
-      await route.handler(fakePost({ host: 'harness.example' }, '/api2/goals/create', body), response.response)
+      await route.handler(fakePost({ host: 'harness.example' }, '/rpc/goals/create', body), response.response)
       expect(JSON.parse(String(response.state.body))).toMatchObject({
         rpcId,
         result: { ok: false, error: { code: 'bad-request' } },
@@ -294,7 +374,7 @@ describe('connection node half', () => {
     }
 
     const failed = fakeResponse()
-    await route.handler(fakePost({ host: 'harness.example' }, '/api2/fail', {
+    await route.handler(fakePost({ host: 'harness.example' }, '/rpc/fail', {
       type: 'client-request', rpcId: 'rpc-fail', method: 'fail', payload: {},
     }), failed.response)
     expect(failed.state).toMatchObject({ status: 500, body: 'handler failure: Error: handler broke' })
diff --git a/packages/host/api-gateway/README.i18n.yaml b/packages/host/api-gateway/README.i18n.yaml
index 2abe47e0d3..747aa65665 100644
--- a/packages/host/api-gateway/README.i18n.yaml
+++ b/packages/host/api-gateway/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/host/api-gateway/README.md
-README.md: 3ef926ace2ee4d6008b1d6c18b1e070fa39bc176
-README.zh.md: 77b8b8a87d5f511000aac5cf9f75ebca5fcdfbca
+README.md: cc80bb19fec15414aa0857154a8a36fb4f642672
+README.zh.md: 6febb1cfe4fc7fa4c5a17e1e4f6a21e2ee03e295
diff --git a/packages/host/api-gateway/README.md b/packages/host/api-gateway/README.md
index 3ef926ace2..cc80bb19fe 100644
--- a/packages/host/api-gateway/README.md
+++ b/packages/host/api-gateway/README.md
@@ -10,13 +10,13 @@ Two-sided Remote control for Host and Client Cordis environments. The Host entry
 
 Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use registered `ctx.typert.lookups` providers, while `@RemoteContext` resolves its receiver through a registered Host Context provider. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation.
 
-The Host entry registers the trusted-host `/api2` unary RPC channel when Connection is available. Direct `invoke()` calls preserve business errors; `TypertGatewayError` distinguishes failures owned by dispatch, binding, providers, lookup, Context, arguments, and codecs.
+The Host entry registers a trusted-host interceptor on Connection's shared `/api` FetchHandler. Connection passes this composite handler through its HTTP bridge; the handler dispatches claimed endpoints to Gateway and unclaimed endpoints to API Proxy. Direct `invoke()` calls preserve business errors; `TypertGatewayError` distinguishes failures owned by dispatch, binding, providers, lookup, Context, arguments, and codecs.
 
 ## Client service: `ClientApi` (ctx key: `api`)
 
 `ctx.api.mount()` validates and registers a generated Host-for-Client contribution, then installs concrete direct and scoped methods for the calling Cordis fiber. Duplicate endpoints, namespace collisions, and descriptors without strict generated codecs fail before methods become callable.
 
-Each call validates positional inputs, constructs the descriptor's exact named `args`, and sends it through `ctx.connection.rpc.call('/api2', endpoint, ...)`. The returned value is validated before reaching application code. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls, and makes retained method handles reject.
+Each call validates positional inputs, constructs the descriptor's exact named `args`, and sends it through `ctx.connection.rpc.call('/api', endpoint, ...)`. The returned value is validated before reaching application code. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls, and makes retained method handles reject.
 
 Generated declaration merges provide the TypeScript API. The Client entry contains no Host Service or Host Cordis interface merge, and method lookup and invocation use ordinary objects and functions rather than a JavaScript Proxy.
 
diff --git a/packages/host/api-gateway/README.zh.md b/packages/host/api-gateway/README.zh.md
index 77b8b8a87d..6febb1cfe4 100644
--- a/packages/host/api-gateway/README.zh.md
+++ b/packages/host/api-gateway/README.zh.md
@@ -10,13 +10,13 @@
 
 严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用已向 `ctx.typert.lookups` 注册的提供方，`@RemoteContext` 则通过已注册的 Host Context 提供方解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。
 
-Connection 可用时，Host 入口会注册 trusted-host 的 `/api2` 一元 RPC 通道。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 可区分分发、绑定、提供方、查找、Context、参数和编解码器各自负责的故障。
+Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandler 上注册 trusted-host interceptor。Connection 把这个复合 handler 交给 HTTP bridge；handler 将已认领 endpoint 分发给 Gateway，未认领 endpoint 则交给 API Proxy。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 可区分分发、绑定、提供方、查找、Context、参数和编解码器各自负责的故障。
 
 ## Client 服务：`ClientApi`（ctx key：`api`）
 
 `ctx.api.mount()` 会校验并注册生成的 Host-for-Client 贡献项，然后为发起调用的 Cordis fiber 安装具体的直接方法和作用域方法。重复端点、命名空间冲突，以及缺少生成的严格编解码器的描述符，都会在方法可调用前报错。
 
-每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api2', endpoint, ...)` 发送。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
+每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api', endpoint, ...)` 发送。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
 
 生成的声明合并提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
 
diff --git a/packages/host/api-gateway/src/client/index.ts b/packages/host/api-gateway/src/client/index.ts
index fe8fd9f1b3..1f92bc0748 100644
--- a/packages/host/api-gateway/src/client/index.ts
+++ b/packages/host/api-gateway/src/client/index.ts
@@ -248,7 +248,7 @@ class ClientApiService extends Service implements ClientApi {
     })
     const connection = this.ownerCtx.get('connection') as ConnectionHandle | undefined
     if (connection === undefined) throw new Error(`client api: ${endpoint} has no active Connection`)
-    const result = await connection.rpc.call('/api2', endpoint, { args }, token.abort.signal)
+    const result = await connection.rpc.call('/api', endpoint, { args }, token.abort.signal)
     if (!mountActive(token)) throw new Error(`client api: Remote method ${endpoint} was withdrawn during invocation`)
     if (!result.ok) throw remoteFailure(endpoint, result.error)
     return parse(descriptor.result, result.value, endpoint, 'result')
diff --git a/packages/host/api-gateway/src/index.ts b/packages/host/api-gateway/src/index.ts
index c83772261a..2adfaa8387 100644
--- a/packages/host/api-gateway/src/index.ts
+++ b/packages/host/api-gateway/src/index.ts
@@ -5,6 +5,7 @@
  */
 
 import { Context, Service, symbols } from 'cordis'
+import type { ConnectionRpcHandler } from '@deepseek-ai/dsh-client-connection'
 import {
   remoteMethods,
   type InvocationDescriptor,
@@ -35,26 +36,7 @@ interface ResolvedBinding {
   readonly original: object
 }
 
-type ConnectionRpcResult =
-  | { readonly ok: true; readonly value: unknown }
-  | {
-    readonly ok: false
-    readonly error: {
-      readonly code: 'internal'
-      readonly message: string
-      readonly details: Record<never, never>
-    }
-  }
-
-interface HostConnectionLike {
-  readonly rpc: {
-    handle(
-      channel: string,
-      handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<ConnectionRpcResult>,
-      options: { readonly authority: 'trusted-host' | 'loopback' },
-    ): () => Promise<void>
-  }
-}
+type ConnectionRpcResult = Awaited<ReturnType<ConnectionRpcHandler>>
 
 /** Dispatch failure produced outside the invoked business method. */
 export class TypertGatewayError extends Error {
@@ -101,15 +83,32 @@ export class TypertGatewayService extends Service implements TypertGateway {
   constructor(ctx: Context) {
     super(ctx, 'typertGateway')
     ctx.inject(['connection'], (connectionCtx) => {
-      const connection = connectionCtx.get('connection') as unknown as HostConnectionLike
-      connection.rpc.handle(
-        '/api2',
+      connectionCtx.connection.rpc.intercept(
+        '/api',
+        endpoint => this.claimsEndpoint(endpoint),
         (endpoint, payload, signal) => this.dispatchRpc(endpoint, payload, signal),
         { authority: 'trusted-host' },
       )
     })
   }
 
+  private claimsEndpoint(endpoint: string): boolean {
+    const segments = endpoint.split('/')
+    if (segments.length !== 2 || segments[0] === '' || segments[1] === '') return false
+    const [namespace, method] = segments as [string, string]
+    if (this.ctx.typert.local.get(endpoint) !== undefined || this.ctx.typert.local.hasSeen(endpoint)) return true
+    for (const [serviceKey, definition] of Object.entries(this.ctx.reflect.props)) {
+      if (definition.type !== 'service') continue
+      const receiver = this.ctx.get(serviceKey) as unknown
+      if (!isObject(receiver)) continue
+      const original = originalOf(receiver)
+      const binding = Reflect.get(original, 'typertGateway') as unknown
+      if (!isObject(binding) || Reflect.get(binding, 'namespace') !== namespace) continue
+      if (remoteMethods(original).some(candidate => (candidate.exportName ?? candidate.method) === method)) return true
+    }
+    return false
+  }
+
   /**
    * Invoke one live Remote method through strict generated reflection or SRC markers.
    * @param request - decoded endpoint and exact named wire arguments.
diff --git a/packages/host/api-gateway/tests/client.spec.ts b/packages/host/api-gateway/tests/client.spec.ts
index 8c0753f3f9..ab08ef09bc 100644
--- a/packages/host/api-gateway/tests/client.spec.ts
+++ b/packages/host/api-gateway/tests/client.spec.ts
@@ -109,7 +109,7 @@ describe('Client TypeRT API', () => {
 
     await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).resolves.toEqual({ ref: 'goal-1' })
     expect(call).toHaveBeenCalledWith(
-      '/api2',
+      '/api',
       'goals/create',
       { args: { agentId: 'agent-1', request: { objective: 'ship' } } },
       expect.any(AbortSignal),
@@ -144,7 +144,7 @@ describe('Client TypeRT API', () => {
 
     await expect(agentCtx.goals.create({ objective: 'ship scoped' })).resolves.toEqual({ ref: 'goal-2' })
     expect(call).toHaveBeenCalledWith(
-      '/api2',
+      '/api',
       'goals/create',
       { args: { agentId: 'agent-2', request: { objective: 'ship scoped' } } },
       expect.any(AbortSignal),
@@ -175,7 +175,7 @@ describe('Client TypeRT API', () => {
 
     await expect(agentCtx.goals.rename({ objective: 'land' })).resolves.toEqual({ renamed: true })
     expect(call).toHaveBeenCalledWith(
-      '/api2',
+      '/api',
       'goals/rename',
       { args: { agentId: 'agent-2', request: { objective: 'land' } } },
       expect.any(AbortSignal),
diff --git a/packages/host/api-gateway/tests/gateway.spec.ts b/packages/host/api-gateway/tests/gateway.spec.ts
index 0b550e126d..d5a3f9a8ee 100644
--- a/packages/host/api-gateway/tests/gateway.spec.ts
+++ b/packages/host/api-gateway/tests/gateway.spec.ts
@@ -96,6 +96,7 @@ type FakeRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal)
 class FakeConnectionService extends Service {
   channel: string | undefined
   authority: string | undefined
+  matches: ((endpoint: string) => boolean) | undefined
   handler: FakeRpcHandler | undefined
 
   constructor(ctx: Context) {
@@ -105,14 +106,21 @@ class FakeConnectionService extends Service {
   get rpc() {
     const owner = this.ctx
     return {
-      handle: (channel: string, handler: FakeRpcHandler, options: { readonly authority: string }) =>
+      intercept: (
+        channel: string,
+        matches: (endpoint: string) => boolean,
+        handler: FakeRpcHandler,
+        options: { readonly authority: string },
+      ) =>
         owner.effect(() => {
           this.channel = channel
           this.authority = options.authority
+          this.matches = matches
           this.handler = handler
           return () => {
             this.channel = undefined
             this.authority = undefined
+            this.matches = undefined
             this.handler = undefined
           }
         }),
@@ -820,7 +828,7 @@ describe('TypertGatewayService', () => {
     }), 'invocation-unavailable')
   })
 
-  it('mounts /api2 through an optional Connection and returns existing RPC results', async () => {
+  it('mounts a shared /api interceptor through an optional Connection and returns existing RPC results', async () => {
     const ctx = new Context().extend({ fixtureScope: 'rpc-caller' })
     await ctx.plugin(TypertRegistry)
     await ctx.plugin(FakeConnectionService)
@@ -828,13 +836,18 @@ describe('TypertGatewayService', () => {
     await gatewayFiber
     await ctx.plugin(GoalService)
     const connection = rawConnection(ctx)
-    expect(connection).toMatchObject({ channel: '/api2', authority: 'trusted-host' })
+    expect(connection).toMatchObject({ channel: '/api', authority: 'trusted-host' })
 
     registerAgentLookup(ctx, { id: 'agent-1' })
     registerStrict(ctx, [createDescriptor()])
+    expect(connection.matches?.('goals/create')).toBe(true)
+    expect(connection.matches?.('goals/passthrough')).toBe(true)
+    expect(connection.matches?.('goals')).toBe(false)
+    expect(connection.matches?.('goals/missing')).toBe(false)
+    expect(connection.matches?.('legacy/list')).toBe(false)
     const signal = new AbortController().signal
     const handler = connection.handler
-    if (handler === undefined) throw new Error('fixture Connection did not retain the /api2 handler')
+    if (handler === undefined) throw new Error('fixture Connection did not retain the /api interceptor')
     await expect(handler('goals/create', {
       args: { agentId: 'agent-1', request: { title: 'ship' } },
     }, signal)).resolves.toEqual({
@@ -873,7 +886,7 @@ describe('TypertGatewayService', () => {
     expect(connection.handler).toBeUndefined()
   })
 
-  it('dispatches a generated invocation through the real /api2 HTTP carrier', async () => {
+  it('dispatches claimed invocations through /api and leaves unclaimed endpoints to its fallback', async () => {
     const ctx = new Context().extend({ fixtureScope: 'http-caller' })
     const routes: WebRoute[] = []
     ctx.provide('httpServer', fakeHttpServer(routes) as HttpServerService)
@@ -886,11 +899,12 @@ describe('TypertGatewayService', () => {
     await goalFiber
     const removeLookup = registerAgentLookup(ctx, { id: 'agent-1' })
     const removeStrict = registerStrict(ctx, [createDescriptor()])
+    let strictActive = true
     expect(routes).toHaveLength(1)
     const server = await serveRoute(routes[0]!)
 
     try {
-      const response = await fetch(`${server.origin}/api2/goals/create`, {
+      const response = await fetch(`${server.origin}/api/goals/create`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({
@@ -909,9 +923,54 @@ describe('TypertGatewayService', () => {
           value: { agentId: 'agent-1', title: 'ship', scope: 'http-caller' },
         },
       })
+
+      const invalid = await fetch(`${server.origin}/api/goals/create`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          type: 'client-request',
+          rpcId: 'rpc-invalid',
+          method: 'goals/create',
+          payload: { invalid: true },
+        }),
+      })
+      expect(invalid.status).toBe(200)
+      await expect(invalid.json()).resolves.toMatchObject({
+        type: 'server-response',
+        rpcId: 'rpc-invalid',
+        result: {
+          ok: false,
+          error: { code: 'internal', message: expect.stringContaining('plain-object args field') },
+        },
+      })
+
+      await removeStrict()
+      strictActive = false
+      const withdrawn = await fetch(`${server.origin}/api/goals/create`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          type: 'client-request',
+          rpcId: 'rpc-withdrawn',
+          method: 'goals/create',
+          payload: { args: { agentId: 'agent-1', request: { title: 'ship' } } },
+        }),
+      })
+      expect(withdrawn.status).toBe(200)
+      await expect(withdrawn.json()).resolves.toMatchObject({
+        type: 'server-response',
+        rpcId: 'rpc-withdrawn',
+        result: {
+          ok: false,
+          error: { code: 'internal', message: expect.stringContaining('strict definition was withdrawn') },
+        },
+      })
+
+      const unclaimed = await fetch(`${server.origin}/api/legacy/list`, { method: 'POST' })
+      expect(unclaimed.status).toBe(404)
     } finally {
       await server.close()
-      await removeStrict()
+      if (strictActive) await removeStrict()
       await removeLookup()
       await goalFiber.dispose()
       await gatewayFiber.dispose()

From cd566f26f56ae8ac4a56c23adec94ee067def193 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 16:46:02 +0800
Subject: [PATCH 123/516] test(client-remotes): cover shared API bundle chain

---
 packages/client/remotes/tests/built-lib.e2e.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/client/remotes/tests/built-lib.e2e.ts b/packages/client/remotes/tests/built-lib.e2e.ts
index bbba218844..bef3f4ad65 100644
--- a/packages/client/remotes/tests/built-lib.e2e.ts
+++ b/packages/client/remotes/tests/built-lib.e2e.ts
@@ -6,7 +6,7 @@ import { describe, expect, it } from 'vitest'
 
 /**
  * Built-artifact smoke for the first generated Remote: plain Node boots the
- * Host and Browser bundle handoffs, then crosses the real `/api2` HTTP route.
+ * Host and Browser bundle handoffs, then crosses the shared `/api` HTTP route.
  */
 
 const packageDir = fileURLToPath(new URL('..', import.meta.url))
@@ -98,7 +98,9 @@ describe.skipIf(!requiredArtifacts)('Goal Remote built LIB chain', () => {
       host.agents.register(rootAgent)
       host.agents.register(scopedAgent)
 
-      if (routes.length !== 1) throw new Error('Gateway did not register exactly one /api2 route')
+      if (routes.length !== 1 || routes[0].path !== '/api') {
+        throw new Error('Connection did not register exactly one /api route')
+      }
       const server = createServer((request, response) => { void routes[0].handler(request, response) })
       await new Promise(resolveListen => server.listen(0, '127.0.0.1', resolveListen))
       const address = server.address()

From 88385a658e7e1e138e002a9146919abe428633b0 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 17:06:54 +0800
Subject: [PATCH 124/516] docs(cordis): refresh gateway service location

---
 docs/cordis-catalog/services.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 9f5e66ea36..a0fee79546 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2650,7 +2650,7 @@ Resolve strict generated definitions or conservative SRC markers against current
 async invoke(request: InvokeRemoteRequest): Promise<unknown>
 ```
 
-Source: [`packages/host/api-gateway/src/index.ts:94`](../../packages/host/api-gateway/src/index.ts)
+Source: [`packages/host/api-gateway/src/index.ts:76`](../../packages/host/api-gateway/src/index.ts)
 
 ## `ctx.userInteraction` — `UserInteractionService`
 

From 9b63d72c9482c1dfd39f79ec1fd3b0562b521b93 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 17:49:35 +0800
Subject: [PATCH 125/516] fix(typert): harden remote reflection boundaries

---
 ...08-02-typert-remote-method-calls.i18n.yaml |   6 +
 .../2026-08-02-typert-remote-method-calls.md  |  66 +++---
 ...026-08-02-typert-remote-method-calls.zh.md |  66 +++---
 ...08-02-typert-remote-method-calls.i18n.yaml |   6 -
 docs/config-catalog.md                        |   2 +-
 docs/cordis-catalog/services.md               |   2 +-
 docs/core-data-structures/core.i18n.yaml      |   4 +-
 docs/core-data-structures/core.md             |   1 +
 docs/core-data-structures/core.zh.md          |   1 +
 docs/core-data-structures/typert.i18n.yaml    |   6 +
 docs/core-data-structures/typert.md           | 196 ++++++++++++++++++
 docs/core-data-structures/typert.zh.md        | 196 ++++++++++++++++++
 package.json                                  |   2 +-
 .../cordis/tool-cordis/src/api-catalog.ts     |   2 +-
 packages/host/api-gateway/src/client/index.ts |   1 +
 packages/host/api-gateway/src/index.ts        |  12 +-
 .../host/api-gateway/tests/client.spec.ts     |  15 +-
 .../host/api-gateway/tests/gateway.spec.ts    |  29 +++
 packages/typert/generator/src/analyzer.ts     | 104 +++++++++-
 .../generator/tests/remote-model.spec.ts      |  26 +++
 packages/typert/loader/src/index.ts           |   6 +-
 packages/typert/loader/tests/loader.spec.ts   |  52 +++--
 packages/typert/registry/src/service.ts       |  26 ++-
 packages/typert/registry/src/types.ts         |   7 +-
 packages/typert/registry/tests/typert.spec.ts |  18 ++
 packages/typert/type-meta/src/index.ts        |   1 +
 packages/typert/type-meta/src/types.ts        |  16 ++
 scripts/type-equiv.manifest.json              |  60 ++++++
 28 files changed, 813 insertions(+), 116 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
 rename .agents/notes/{proposed => implemented}/architecture/2026-08-02-typert-remote-method-calls.md (85%)
 rename .agents/notes/{proposed => implemented}/architecture/2026-08-02-typert-remote-method-calls.zh.md (85%)
 delete mode 100644 .agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
 create mode 100644 docs/core-data-structures/typert.i18n.yaml
 create mode 100644 docs/core-data-structures/typert.md
 create mode 100644 docs/core-data-structures/typert.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
new file mode 100644
index 0000000000..752a5d4c8b
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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/architecture/2026-08-02-typert-remote-method-calls.md
+2026-08-02-typert-remote-method-calls.md: 91ab8e44ff8aedf666fe3426b85b54491deb340c
+2026-08-02-typert-remote-method-calls.zh.md: 73abd53109d871076aa41af39825c80c35ac3f26
diff --git a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
similarity index 85%
rename from .agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md
rename to .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index 61c8f61468..91ab8e44ff 100644
--- a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -1,6 +1,6 @@
 # Agent Note: TypeRT Gateway Targeted Method Calls
 
-Status: proposed
+Status: implemented
 
 English | [中文](2026-08-02-typert-remote-method-calls.zh.md)
 
@@ -8,13 +8,13 @@ English | [中文](2026-08-02-typert-remote-method-calls.zh.md)
 
 The Host API Proxy handles direct method calls, stateful interactions, and Session event streams. These concerns have different lifecycles, routing semantics, and client programming interfaces. Continuing to export all business operations through one package would couple business Services, transport protocols, state machines, and client types.
 
-This proposal addresses only targeted method calls in which one request produces one result. Stateful interactions such as Permission and Approval, as well as Session event streams, do not use this design and will be designed separately.
+This decision covers only targeted method calls in which one request produces one result. Stateful interactions such as Permission and Approval, as well as Session event streams, remain separate designs.
 
-The contract for a direct method call belongs to the business Service that implements it. Business developers should declare only which methods are remotely callable, without also maintaining a central API interface, routing table, parameter conversion table, client stub, and Zod schema.
+The contract for a direct method call belongs to the business Service that implements it. Business developers declare only which methods are remotely callable, without also maintaining a central API interface, routing table, parameter conversion table, client stub, and Zod schema.
 
 The Host and Browser Client use separate TypeScript Programs because each side augments the Cordis `Context` type differently. A Remote projection must not import the complete Host declarations into a consumer or depend on Browser-specific types. If the TUI later reuses this programming interface, it must likewise see only methods marked Remote. TUI integration is outside the current scope, but the implementation boundary must preserve this isomorphic reuse.
 
-## Proposal
+## Decision
 
 A business Service declares callable methods with `@Remote` or `@RemoteContext()` and explicitly joins the Gateway through `bindTypeRTGateway()`. TypeRT generates the Host-local reflection artifact and a platform-independent Remote consumer projection from the Host Program. The Client Program continues to generate its own local reflection artifact independently.
 
@@ -24,7 +24,7 @@ The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. T
 
 ## Components and Cordis services
 
-| Component | Cordis service | Responsibility in this proposal |
+| Component | Cordis service | Responsibility |
 |---|---|---|
 | `@deepseek-ai/dsh-type-meta` | Declares only the minimal `ctx.typert` protocol | Decorators, bindings, descriptors, lookup/Context, and the Remote map; no dependency on the compiler, Zod, Connection, or Browser |
 | TypeRT registry | `ctx.typert` | Separately stores reflection for the current environment, imported Remote contributions, lookup providers, and Context providers |
@@ -104,7 +104,7 @@ ctx.typert.lookups.register('agent', {
 
 The static declaration tells TypeRT that `Agent` corresponds to `SessionId` on the wire. The runtime provider resolves an `agentId` in a request to the currently live `Agent` object. If either side is missing, the LIB build or the earliest resolvable runtime registration fails immediately.
 
-Lookup objects such as Agent and Session may each occupy only one top-level parameter position. An ordinary JSON request may be passed as another complete parameter, but this proposal does not support `request.agent`, object destructuring, arrays of objects, nested lookups, or searching arbitrary complex structures for IDs.
+Lookup objects such as Agent and Session may each occupy only one top-level parameter position. An ordinary JSON request may be passed as another complete parameter, but this design does not support `request.agent`, object destructuring, arrays of objects, nested lookups, or searching arbitrary complex structures for IDs.
 
 Remote Context uses a separate merge-extensible map and provider. The Agent package registers an `agent` Context provider that locates the Agent Context from its wire identity and resolves the Service key named by the descriptor from that Context. The Gateway does not know the internal structure of an Agent Context.
 
@@ -150,7 +150,9 @@ ctx.typert.lookups   wire ID 到 Host 活对象的 provider
 ctx.typert.contexts  Host Context resolver 与 Client Context binder
 ```
 
-Every registration returns a disposer owned by the caller's Cordis fiber. The Gateway and API Service read the current snapshot before subscribing to changes, so business Services, generated contributions, providers, and consumers can load in any order. When any dependency is disposed, its related endpoints or methods become unavailable immediately.
+Every registration returns a disposer owned by the caller's Cordis fiber. Client contribution mounting registers the descriptor set and concrete methods as one owned operation. The Host Gateway resolves descriptors, Services, and providers from current state for every claim and invocation instead of retaining endpoint registrations. Removing a strict definition, Service, or provider therefore makes the corresponding call unavailable without leaving a stale live object.
+
+The lookup registry retains the stable wire declaration after its live resolver unloads. SRC parsing continues to classify the parameter as a lookup, while invocation fails with `lookup-unavailable`; it never reclassifies the incoming ID as an ordinary JSON business object. Re-registering the same key with different parameter, wire, or canonical type symbols fails for the lifetime of that TypeRT Service.
 
 The registry's Host root entry has the complete `TypeRTService` interface merge. The registry implementation shared by Host and Client lives in a separate module without environment declarations. The registry's `/client` entry imports only that shared implementation and does not pass through the Host root entry, so it cannot bring Host Cordis declarations into the Client Program.
 
@@ -312,11 +314,11 @@ agent.goals.create(request)
 
 The Root `Context` does not merge the scoped `goals` type; only `AgentContext` gains that property through `RemoteContextApi<'agent'>`. If a caller bypasses the type system and dynamically calls a scoped method from Root, the binder reports an explicit error. If the Client already has a Cordis service with the same name, or two contributions claim the same namespace and method incompatibly, mounting fails instead of overwriting the existing service.
 
-Generated Remote JS contains only descriptors, symbol keys, and codecs; it does not bundle Host Service implementations. The API Service can create real functions from that data, so this proposal does not depend on a JavaScript Proxy. A Proxy remains an implementation option but is not a source of types or reflection.
+Generated Remote JS contains only descriptors, symbol keys, and codecs; it does not bundle Host Service implementations. The API Service creates real functions from that data, so the runtime does not depend on a JavaScript Proxy. A Proxy remains an implementation option but is not a source of types or reflection.
 
 ## Cross-environment isomorphism constraints
 
-Remote API is a consumer capability, not a synonym for Browser API. This phase implements only Browser Client contribution mounting, Connection RPC calls, and Agent Scope association.
+Remote API is a consumer capability, not a synonym for Browser API. The shipped runtime implements Browser Client contribution mounting, Connection RPC calls, and Agent Scope association.
 
 Remote DTS, Remote JS, `RemoteApi`, `InvocationDescriptor`, the Remote RPC data protocol, and Context binders must not depend on the DOM, Browser module loaders, or HTTP. Through Connection, the Browser Client encodes descriptor-materialized methods as `/api` RPC calls.
 
@@ -324,7 +326,7 @@ A future TUI can join the same call abstraction without changing business decora
 
 TUI runtime mounting, carriers, Agent Scope association, and SRC startup wiring are outside this phase.
 
-The Web already depends on build artifacts such as `lib/client.js`, so it requires a complete `build:lib` before startup. After the Host Remote contract changes, developers must rebuild the lib and then start or restart the Web. The first phase does not implement incremental watching of the Remote contract.
+The Web already depends on build artifacts such as `lib/client.js`, so it requires a complete `build:lib` before startup. After the Host Remote contract changes, developers rebuild the lib and then start or restart the Web. Incremental watching of the Remote contract is not implemented.
 
 ## SRC and LIB operating modes
 
@@ -340,11 +342,11 @@ At runtime, LIB only loads definitions from `lib`; it does not start the TypeScr
 
 CI and releases use LIB. Moving all repository coverage to LIB is separate follow-up work and does not block this direct-method-call implementation.
 
-## Host Gateway registration
+## Host Gateway resolution
 
-The Host Gateway observes both TypeRT Remote definitions and the Cordis Service lifecycle. When a Service carrying the `typertGateway` facet and a definition with the same service key are both available, the Gateway registers the definition's endpoints. Their arrival order does not matter.
+The Host Gateway registers one `/api` interceptor with Connection and does not maintain a second endpoint registry. Its ownership matcher resolves each endpoint from the current TypeRT local registry or scans current Cordis Services for a matching `typertGateway` binding and SRC Remote marker. TypeRT definitions and business Services may therefore arrive in either order.
 
-At startup, the Gateway reads the current snapshots of TypeRT definitions and the Cordis reflection store before subscribing to registry changes and `internal/service`. It reconciles definitions, live Services, and bindings by service key, and unregisters endpoints when a Service is replaced or disposed. If a definition, lookup provider, or Context provider is removed, dependent endpoints immediately become unavailable; the Gateway neither retains invalid objects nor degrades to invoking methods with raw IDs.
+Invocation resolves the descriptor, receiver, lookup providers, and Context provider again from current state. A current strict descriptor takes precedence over SRC. After a strict endpoint has appeared, `TypeRTLocalRegistry.hasSeen()` keeps it owned when that descriptor is withdrawn and forbids SRC fallback for the remainder of the registry lifetime; re-registering the strict descriptor restores calls. Removing a Service or provider makes invocation fail explicitly, and the Gateway neither retains invalid objects nor invokes a method with a raw lookup ID.
 
 An ordinary `@Remote` call retains the original Service instance as receiver. After lookups succeed, the Gateway calls the member identified by `implementation ?? method` with parameters in descriptor order.
 
@@ -417,7 +419,7 @@ ctx.api.goals.create(sessionId, request)
 → Client result codec 验证并返回 CreateGoalResult
 ```
 
-Remote does not define a second-layer `{ ok, value/error }` response. Successful values and Gateway errors use the existing RPC response's `result` directly. The Gateway adapter maps endpoint, schema, lookup, Context, Service, and business-invocation failures to `RpcError`; Connection transports that error.
+Remote does not define a second-layer `{ ok, value/error }` response. Successful values and Gateway errors use the existing RPC response's `result` directly. The current adapter converts every Gateway and business-invocation failure to the existing `RpcError` envelope with `code: 'internal'`; the Gateway's structured error category remains available only in-process, while the message carries the diagnostic across Connection.
 
 The Gateway does not handle per-method permissions, caller identity, cancellation, idempotency, or long-lived connection state. TypeRT endpoints use Connection's trusted-host policy; unclaimed endpoints retain the legacy API Proxy's trust and privileged-method policies. Connection's WebSocket migration remains separate follow-up work.
 
@@ -438,11 +440,11 @@ The Gateway registers only its ownership matcher and RPC handler with Connection
 - Business-object packages such as Agent/Session: own lookup, Context providers, canonical ID types, and public type-only entries.
 - Business Service packages: declare bindings, Remote methods, and their request/result types, and export the generated `/remote` subpath.
 
-## Initial implementation scope
+## Shipped scope and deferred work
 
-The first vertical path implements `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()` and proves that the same direct descriptor with an Agent lookup supports both `ctx.api.goals.create(agentId, request)` and `agentCtx.goals.create(request)`. The scoped-receiver semantics of `@RemoteContext('agent')` remain a separate mode.
+The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`. The same direct descriptor with an Agent lookup supports both `ctx.api.goals.create(agentId, request)` and `agentCtx.goals.create(request)`. `@RemoteContext('agent')` remains the distinct scoped-receiver mode.
 
-This phase implements Connection's shared-channel interceptor and current HTTP carrier mapping, but not WebSocket migration, the TUI runtime, a TUI carrier, or TUI Agent Scope wiring. This RFC also does not design Permission/Approval state machines, Session event streams, call authorization, cancellation, retries, idempotency, or cross-version protocol compatibility.
+Connection supplies the shared-channel interceptor and current HTTP carrier mapping. WebSocket migration, the TUI runtime and carrier, TUI Agent Scope wiring, Permission/Approval state machines, Session event streams, call authorization, cancellation, retries, idempotency, and cross-version protocol compatibility remain outside this decision.
 
 ## Alternatives considered
 
@@ -464,26 +466,24 @@ This phase implements Connection's shared-channel interceptor and current HTTP c
 
 **Create a separate transport, HTTP route, or `/api2` channel for Remote.** This would duplicate or split Connection's Server ownership, rpcId, serialization, trust, errors, and future WebSocket lifecycle. The shared `/api` interceptor instead keeps one physical route and lets Connection preserve API Proxy as the fallback FetchHandler.
 
-## Acceptance criteria
+## Verification
 
-- Goal Service retains its existing business method and adds a remote entry point at the end of the class through an explicit `typertGateway` and `@Remote('create') remoteExportCreate(...)`, without maintaining a second route, codec, or Client method list.
-- One clean `build:lib` generates the Host Remote contract before compiling Host and Client consumers and produces JS, DTS, and a DTS map under the business package's `lib`, importable through `/remote`.
-- After importing `@deepseek-ai/dsh-goal/remote`, a consumer project gets a strict `api.goals.create(...)` type; without the import, that namespace does not enter its types. Go to Definition on `create` follows the declaration map to the Host Service's `remoteExportCreate` implementation.
-- After the Client assembly mounts the JS contribution obtained from the same import, TypeRT can reflect endpoint, parameter, result, lookup, Context, and Zod information, and the API Service creates the calling method without a hand-written stub.
-- Remote DTS, Remote JS, `RemoteApi`, and the descriptor protocol do not depend on Browser-specific capabilities, and the type model cannot expose unmarked Goal Service methods, preserving the boundary required for future isomorphic TUI integration.
-- `agent.goals.*` obtains its call Scope through the Cordis tracker and Context binder. The Root Context has no Agent-only type, and functions are not copied into each Scope.
-- `/api/goals/create` resolves `agentId` to the canonical Agent object, invokes the original Goal Service receiver, and returns the result through the existing RPC result/error mechanism.
-- Gateway mounts into Connection, Connection mounts the single `/api` route into HTTP Server, and Remote defines neither an HTTP route nor a second response envelope.
-- Connection's composite FetchHandler dispatches a TypeRT-owned endpoint to Gateway and falls back to API Proxy only when Gateway does not claim it. A withdrawn strict endpoint remains claimed and fails as unavailable.
-- Existing API Proxy trust, privileged-method, Permission/Approval, and Session event stream behavior remains unchanged for unclaimed endpoints.
+- Goal Service keeps its existing business method and adds an explicit `typertGateway` plus `@Remote('create') remoteExportCreate(...)`, without a second route, codec, or Client method list.
+- A clean `build:lib` emits Host and consumer Remote artifacts before Client compilation, including the business package's JS, DTS, and declaration map under `/remote`.
+- Importing `@deepseek-ai/dsh-goal/remote` adds the strict `api.goals.create(...)` type and declaration navigation to `remoteExportCreate`; omitting that import omits the namespace.
+- Mounting the same import's JS contribution supplies endpoint, parameter, result, lookup, Context, and Zod reflection and materializes the call without a handwritten stub.
+- Root and Agent-scoped calls cross the real shared `/api` carrier, resolve `agentId` to the live Agent, invoke the original Goal receiver, and return through the existing RPC envelope.
+- The Remote artifacts and maps contain only marked methods and no Browser dependency, preserving the same consumer boundary for a future TUI.
+- Lifecycle tests withdraw and remount descriptors, Services, lookups, Context providers, and Client namespaces; unavailable dependencies fail without stale calls or raw-ID fallback.
+- Unclaimed endpoints continue through the existing API Proxy path with its trust, privileged-method, Permission/Approval, and Session event-stream behavior unchanged.
 
-## Risks
+## Consequences
 
 Remote API types depend on generated `lib` declarations. Build orchestration must finish the Host contract pass before compiling Host and Client consumers; an incorrect order makes a clean build depend on stale artifacts.
 
 Source navigation requires a Remote package to publish both its declaration map and the `src` file referenced by the map. If package `files` omits either side, types still compile but consumer navigation stops at the generated DTS. The workspace manifest check must therefore treat both as one publication contract.
 
-The permissive SRC descriptor does not validate the internal structure of ordinary JSON. After a Host Remote signature changes, the Web and strict type consumers must rebuild the lib; the first phase has no incremental contract watcher.
+The permissive SRC descriptor does not validate the internal structure of ordinary JSON. After a Host Remote signature changes, the Web and strict type consumers must rebuild the lib because no incremental contract watcher exists.
 
 Canonical public types require business DTOs to have type-only entries, which may expose packages whose Host types and implementation entries are currently mixed. The build rejects those boundaries instead of copying types to conceal them.
 
@@ -494,3 +494,9 @@ Browser and Host each hold their own Zod instances and cannot compare object ide
 A consumer may import a Remote contract that is not currently mounted on the Host. The types mean "this protocol capability was selected by the consumer," not that a corresponding Service currently exists in the target process; an unavailable endpoint must fail explicitly at runtime.
 
 Connection's general channel API must suit both the current HTTP carrier and a future WebSocket carrier. If the API exposes `fetch`, an HTTP request, or a route handle to the Gateway/API Service, WebSocket migration will pierce the Remote layer again. Those physical objects must therefore remain internal to Connection.
+
+Remote endpoints use Connection's `trusted-host` authority. Loopback is accepted by default and LAN callers require an explicit trusted-host configuration, but this layer adds no per-method caller authorization; every trusted host can invoke a mounted Remote endpoint.
+
+`hasSeen()` favors strict-definition safety over SRC availability. While a strict descriptor is withdrawn, such as during HMR, the Gateway continues to claim the endpoint and reports it unavailable instead of falling back to a weak SRC descriptor. Re-registration restores it; only a TypeRT registry restart forgets the historical strict definition.
+
+Connection supplies an `AbortSignal`, but Remote business signatures have no cancellation parameter. A client disconnect therefore does not cancel business work; cancellation remains deferred rather than being implied by the transport handler shape.
diff --git a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
similarity index 85%
rename from .agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md
rename to .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 1e09965d2b..73abd53109 100644
--- a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -1,6 +1,6 @@
 # Agent Note: TypeRT Gateway 定向方法调用
 
-Status: proposed
+Status: implemented
 
 [English](2026-08-02-typert-remote-method-calls.md) | 中文
 
@@ -8,13 +8,13 @@ Status: proposed
 
 Host API Proxy 同时承担直接方法调用、带状态交互和 Session 事件流。三者的生命周期、路由语义和客户端编程界面不同，继续共用一个业务导出包会让业务 Service、传输协议、状态机和客户端类型彼此耦合。
 
-本方案只解决一次请求对应一次结果的定向方法调用。Permission、Approval 等带状态交互以及 Session 事件流不使用本方案，后续分别设计。
+本决策只涵盖一次请求对应一次结果的定向方法调用。Permission、Approval 等带状态交互以及 Session 事件流仍采用独立设计。
 
-直接方法调用的契约属于实现该行为的业务 Service。业务开发者应只声明哪些方法可以远程调用，而不应再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
+直接方法调用的契约属于实现该行为的业务 Service。业务开发者只需声明哪些方法可以远程调用，无需再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
 
 Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以不同类型合并同名 Cordis `Context`。Remote 投影不能把完整 Host 声明导入消费端，也不能依赖 Browser 专属类型；未来 TUI 若复用这套编程界面，也只能看到 Remote 标记的方法。本期不实现 TUI 接入，但实现边界不得阻断这种同构复用。
 
-## Proposal
+## 决策
 
 业务 Service 通过 `@Remote` 或 `@RemoteContext()` 声明可调用方法，并通过 `bindTypeRTGateway()` 显式加入 Gateway。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
 
@@ -24,7 +24,7 @@ Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只
 
 ## 组件和 Cordis 服务
 
-| 组件 | Cordis 服务 | 本方案中的职责 |
+| 组件 | Cordis 服务 | 职责 |
 |---|---|---|
 | `@deepseek-ai/dsh-type-meta` | 只声明 `ctx.typert` 的最小协议 | decorator、binding、descriptor、lookup/Context 和 Remote map；不依赖 compiler、Zod、Connection 或 Browser |
 | TypeRT registry | `ctx.typert` | 分开保存当前环境 reflection、导入的 Remote contribution、lookup provider 和 Context provider |
@@ -104,7 +104,7 @@ ctx.typert.lookups.register('agent', {
 
 静态声明让 TypeRT 知道 `Agent` 在 wire 上对应 `SessionId`；运行时 provider 负责把请求中的 `agentId` 解析为当前活的 `Agent` 对象。缺少任一侧时，LIB 构建或最早可解析的运行时注册直接失败。
 
-Agent、Session 等 lookup 对象只能各自占据一个顶层参数位置。普通 JSON request 可以作为另一个完整参数传入，但本方案不支持 `request.agent`、对象解构、对象数组、嵌套 lookup 或从任意复杂结构中搜索 ID。
+Agent、Session 等 lookup 对象只能各自占据一个顶层参数位置。普通 JSON request 可以作为另一个完整参数传入，但本设计不支持 `request.agent`、对象解构、对象数组、嵌套 lookup 或从任意复杂结构中搜索 ID。
 
 Remote Context 使用独立的 merge-extensible map 和 provider。Agent 包注册 `agent` Context provider，负责用 wire identity 找到 Agent Context，并从该 Context 解析 descriptor 指定的 service key；Gateway 不知道 Agent Context 的内部结构。
 
@@ -150,7 +150,9 @@ ctx.typert.lookups   wire ID 到 Host 活对象的 provider
 ctx.typert.contexts  Host Context resolver 与 Client Context binder
 ```
 
-每次注册都返回由调用方 Cordis fiber 持有的 disposer。Gateway 和 API Service 先读取当前快照再订阅变化，因此业务 Service、generated contribution、provider 和消费者可以按任意顺序加载；任一依赖 dispose 后，相关 endpoint 或方法立即失效。
+每次注册都返回由调用方 Cordis fiber 持有的 disposer。挂载 Client contribution 时，descriptor 集与具体方法会作为一项有明确所有者的操作统一注册。Host Gateway 每次认领和调用时都从当前状态解析 descriptor、Service 与提供方，不保留 endpoint 注册。因此移除 strict definition、Service 或提供方会使相应调用不可用，且不会留下陈旧的活对象。
+
+lookup 注册表会在活 resolver 卸载后保留稳定的 wire 声明。SRC 解析仍会把该参数归类为 lookup，而调用会以 `lookup-unavailable` 失败；系统绝不会把传入的 ID 重新归类为普通 JSON 业务对象。在同一个 TypeRT Service 的生命周期内，以不同参数、wire 或规范类型 symbol 重新注册同一 key 会直接失败。
 
 Registry 的 Host 根入口拥有完整 `TypeRTService` interface merge；Host 与 Client 共用的 registry 实现位于无环境声明的独立模块。Registry `/client` 入口只引用该共享实现，不经过 Host 根入口，因此不会把 Host Cordis 声明带入 Client Program。
 
@@ -312,11 +314,11 @@ agent.goals.create(request)
 
 Root `Context` 不 merge scoped `goals` 类型；只有 `AgentContext` 通过 `RemoteContextApi<'agent'>` 获得该属性。若调用方绕过类型从 Root 动态调用 scoped 方法，binder 明确报错。若 Client 已有同名 Cordis service，或两个 contribution 冲突占用同一 namespace/method，mount 直接失败，不覆盖现有服务。
 
-生成的 Remote JS 只包含 descriptor、symbol key 和 codec，不打包 Host Service 实现。API Service 可以据此创建真实函数，因此本方案不依赖 JavaScript Proxy；Proxy 可以作为实现选择，但不会成为类型或反射来源。
+生成的 Remote JS 只包含 descriptor、symbol key 和 codec，不打包 Host Service 实现。API Service 据此创建真实函数，因此运行时不依赖 JavaScript Proxy；Proxy 可以作为实现选择，但不会成为类型或反射来源。
 
 ## 跨环境同构约束
 
-Remote API 是消费端能力，不等同于 Browser API。本期只实现 Browser Client 的 contribution 挂载、Connection RPC 调用和 Agent Scope 关联。
+Remote API 是消费端能力，不等同于 Browser API。已交付的运行时实现 Browser Client contribution 挂载、Connection RPC 调用和 Agent Scope 关联。
 
 Remote DTS、Remote JS、`RemoteApi`、`InvocationDescriptor`、Remote RPC 数据协议和 Context binder 不得依赖 DOM、Browser module loader 或 HTTP。Browser Client 通过 Connection 把 descriptor 实体化的方法编码为 `/api` RPC 调用。
 
@@ -324,7 +326,7 @@ Remote DTS、Remote JS、`RemoteApi`、`InvocationDescriptor`、Remote RPC 数
 
 TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均不属于本期实现。
 
-Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 契约变化后必须重新执行 lib build，再启动或重启 Web；本方案不在第一阶段实现 Remote contract 的增量 watch。
+Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 契约变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
 
 ## SRC 与 LIB 运行模式
 
@@ -340,11 +342,11 @@ LIB 运行时只加载 `lib` 中的 definition，不启动 TypeScript compiler
 
 CI 和发布运行 LIB。全仓 coverage 全部切换到 LIB 是独立后续工作，不阻塞本次直接方法调用实现。
 
-## Host Gateway 注册
+## Host Gateway 解析
 
-Host Gateway 同时观察 TypeRT Remote definition 和 Cordis Service 生命周期。当某个带 `typertGateway` facet 的 Service 与同 service key 的 definition 都可用时，Gateway 注册其 endpoint；两者到达顺序不影响结果。
+Host Gateway 向 Connection 注册一个 `/api` interceptor，不维护第二份 endpoint 注册表。ownership matcher 会从当前 TypeRT local 注册表解析各 endpoint，或扫描当前 Cordis Service，查找匹配的 `typertGateway` binding 与 SRC Remote 标记。因此 TypeRT definition 与业务 Service 可以按任意顺序到达。
 
-Gateway 启动时先读取 TypeRT definition 和 Cordis reflection store 的当前快照，再订阅 registry change 与 `internal/service`。它按 service key reconcile definition、活 Service 和 binding；Service 被替换或 dispose 时撤销对应 endpoint。definition、lookup provider 或 Context provider 撤销时，依赖它们的 endpoint 立即不可调用，不保留失效对象或降级为原始 ID 调用。
+每次调用都会重新从当前状态解析 descriptor、receiver、lookup 提供方与 Context 提供方。当前 strict descriptor 优先于 SRC。strict endpoint 一旦出现，即使随后撤回对应 descriptor，`TypeRTLocalRegistry.hasSeen()` 仍会在注册表剩余生命周期内保持对它的认领并禁止回退 SRC；重新注册 strict descriptor 即可恢复调用。移除 Service 或提供方会让调用明确失败；Gateway 既不保留失效对象，也不会以原始 lookup ID 调用方法。
 
 普通 `@Remote` 调用保留原始 Service 实例作为 receiver。lookup 成功后，Gateway 按 descriptor 的参数顺序调用 `implementation ?? method` 指定的成员。
 
@@ -417,7 +419,7 @@ ctx.api.goals.create(sessionId, request)
 → Client result codec 验证并返回 CreateGoalResult
 ```
 
-Remote 不定义第二层 `{ ok, value/error }` response。成功值和 Gateway 错误直接使用既有 RPC response 的 `result`；Gateway adapter 负责把 endpoint、schema、lookup、Context、Service 和业务调用失败映射为 `RpcError`，Connection 负责传输该错误。
+Remote 不定义第二层 `{ ok, value/error }` response。成功值和 Gateway 错误直接使用既有 RPC response 的 `result`。当前 adapter 把所有 Gateway 与业务调用失败转换为既有 `RpcError` envelope，并统一使用 `code: 'internal'`；Gateway 的结构化错误分类仅在进程内保留，诊断信息则通过 message 跨 Connection 传递。
 
 Gateway 不处理逐方法权限、调用者身份、取消、幂等或长连接状态。TypeRT endpoint 使用 Connection 的 trusted-host 策略；未认领 endpoint 保留旧 API Proxy 的 trust 和 privileged-method 策略。Connection/WebSocket 迁移后续独立完成。
 
@@ -438,11 +440,11 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 - Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
 - 业务 Service 包：声明 binding、Remote 方法及其 request/result 类型，并导出生成的 `/remote` 子路径。
 
-## 首期实现范围
+## 已交付范围与后续工作
 
-第一条纵向链路实现 `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`，并证明同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.api.goals.create(agentId, request)` 与 `agentCtx.goals.create(request)`。`@RemoteContext('agent')` 的 scoped receiver 语义继续保留为独立模式。
+已交付的纵向链路是 `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`。同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.api.goals.create(agentId, request)` 与 `agentCtx.goals.create(request)`。`@RemoteContext('agent')` 仍是独立的 scoped receiver 模式。
 
-本期实现 Connection 的共享 channel interceptor 及当前 HTTP carrier 映射，但不实现 WebSocket 迁移、TUI runtime、TUI carrier 或 TUI Agent Scope 接线。本 RFC 也不设计 Permission/Approval 状态机、Session 事件流、调用授权、取消、重试、幂等和跨版本协议兼容。
+Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebSocket 迁移、TUI runtime 与 carrier、TUI Agent Scope 接线、Permission/Approval 状态机、Session 事件流、调用授权、取消、重试、幂等及跨版本协议兼容均不属于本决策。
 
 ## Alternatives considered
 
@@ -464,26 +466,24 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 
 **为 Remote 新建独立 transport、HTTP route 或 `/api2` channel。** 这会复制或拆分 Connection 的 Server ownership、rpcId、序列化、trust、错误和未来 WebSocket 生命周期。共享 `/api` interceptor 保留唯一物理 route，并让 Connection 继续以 API Proxy 作为回退 FetchHandler。
 
-## Acceptance criteria
+## 验证
 
-- Goal Service 保留既有业务方法，在类末尾通过显式 `typertGateway` 和 `@Remote('create') remoteExportCreate(...)` 新增远程出口，不维护第二份路由、codec 或 Client 方法清单。
-- 一次干净 `build:lib` 先生成 Host Remote contract，再完成 Host 和 Client 消费端编译，并在业务包 `lib` 下产生可通过 `/remote` 导入的 JS、DTS 和 DTS map。
-- 导入 `@deepseek-ai/dsh-goal/remote` 后，消费 project 获得严格的 `api.goals.create(...)` 类型；不导入时该 namespace 不进入类型；从 `create` 跳转定义会通过 declaration map 到达 Host Service 的 `remoteExportCreate` 实现。
-- Client assembly 挂载同一个 import 得到的 JS contribution 后，TypeRT 能反射 endpoint、参数、结果、lookup、Context 和 Zod 信息，API Service 无需手写 stub 即可创建调用方法。
-- Remote DTS、Remote JS、`RemoteApi` 和 descriptor 协议不依赖 Browser 专属能力，且类型模型无法暴露未标记的 Goal Service 方法，为未来 TUI 同构接入保留边界。
-- `agent.goals.*` 通过 Cordis tracker 和 Context binder 取得调用 Scope，Root Context 不获得 Agent-only 类型，且不为每个 Scope 复制函数。
-- `/api/goals/create` 能把 `agentId` 解析为唯一 Agent 对象，调用原始 Goal Service receiver，并通过既有 RPC result/error 返回结果。
-- Gateway 挂到 Connection，Connection 把唯一 `/api` route 挂到 HTTP Server；Remote 不定义 HTTP route 或第二套 response envelope。
-- Connection 的复合 FetchHandler 将 TypeRT 认领的 endpoint 分发给 Gateway，仅在 Gateway 不认领时回退 API Proxy；已撤回的 strict endpoint 继续被认领并返回 unavailable。
-- 未认领 endpoint 保留既有 API Proxy trust、privileged-method、Permission/Approval 和 Session 事件流行为。
+- Goal Service 保留既有业务方法，并新增显式 `typertGateway` 与 `@Remote('create') remoteExportCreate(...)`，无需第二条路由、第二份 codec 或 Client 方法清单。
+- 一次干净的 `build:lib` 会在 Client 编译前生成 Host 与消费方 Remote 产物，包括业务包 `/remote` 下的 JS、DTS 和 declaration map。
+- 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `api.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
+- 挂载同一次 import 得到的 JS contribution 会提供 endpoint、参数、结果、lookup、Context 和 Zod 反射，并在无需手写 stub 的情况下实体化调用。
+- Root 与 Agent-scoped 调用会经过真实的共享 `/api` carrier，将 `agentId` 解析为活 Agent，调用原始 Goal receiver，并通过既有 RPC envelope 返回。
+- Remote 产物与 map 仅包含已标记的方法，不依赖 Browser，从而为未来 TUI 保留相同的消费方边界。
+- 生命周期测试会撤回并重新挂载 descriptor、Service、lookup、Context 提供方和 Client namespace；依赖不可用时，调用会失败，且不会使用陈旧调用或回退原始 ID。
+- 未认领 endpoint 继续使用既有 API Proxy 路径，其 trust、privileged-method、Permission/Approval 与 Session 事件流行为保持不变。
 
-## Risks
+## 后果
 
 Remote API 类型依赖生成的 `lib` 声明，构建编排必须在 Host 和 Client 消费端编译前完成 contract pass；顺序错误会让干净构建依赖陈旧产物。
 
 源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布契约。
 
-SRC 弱 descriptor 不验证普通 JSON 内部结构。Host Remote 签名变化后，Web 和严格类型消费者必须重新执行 lib build；第一阶段没有增量 contract watch。
+SRC 弱 descriptor 不验证普通 JSON 内部结构。Host Remote 签名变化后，Web 和严格类型消费方必须重新执行 lib build，因为系统没有增量 contract watcher。
 
 公共类型唯一性要求业务 DTO 具有纯类型出口，可能暴露现有包中 Host 类型与实现入口混杂的问题。构建会拒绝这些边界，而不是复制类型掩盖问题。
 
@@ -494,3 +494,9 @@ Browser 与 Host 各自持有 Zod 实例，不能依赖对象 identity 跨 realm
 消费端可以导入 Host 当前未挂载的 Remote contract。类型表示“该协议能力已被消费端选择”，不保证目标进程当前存在对应 Service；运行时 endpoint 不可用必须明确失败。
 
 Connection 的通用 channel API 必须同时适合当前 HTTP carrier 和后续 WebSocket carrier。若接口把 `fetch`、HTTP request 或 route handle 暴露给 Gateway/API Service，WebSocket 迁移会再次穿透 Remote 层，因此这些物理对象必须留在 Connection 内部。
+
+Remote endpoint 使用 Connection 的 `trusted-host` authority。系统默认接受 loopback；LAN 调用方必须通过显式 trusted-host 配置接入，但本层不增加逐方法调用方授权，因此每个 trusted host 都能调用已挂载的 Remote endpoint。
+
+`hasSeen()` 优先保障 strict definition 的安全性，而非 SRC 可用性。strict descriptor 撤回时（例如 HMR 期间），Gateway 会继续认领 endpoint 并报告不可用，而不会回退到弱 SRC descriptor。重新注册即可恢复；只有重启 TypeRT 注册表才会忘记历史 strict definition。
+
+Connection 提供 `AbortSignal`，但 Remote 业务签名没有取消参数。因此 Client 断连不会取消业务工作；取消仍作为后续工作，而不能由 transport handler 的形状暗示已经支持。
diff --git a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
deleted file mode 100644
index 6e7a1a3a13..0000000000
--- a/.agents/notes/proposed/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/proposed/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: 61c8f61468621846fa8e8ff78d52313ae805aa17
-2026-08-02-typert-remote-method-calls.zh.md: 1e09965d2baba2db35301288f338cef15d947f36
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 08f26479ca..41c9c98515 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -308,7 +308,7 @@ export interface ConnectionConfig {
 }
 ```
 
-Source: [`packages/client/connection/src/index.ts:31`](../packages/client/connection/src/index.ts)
+Source: [`packages/client/connection/src/index.ts:32`](../packages/client/connection/src/index.ts)
 
 ## `@deepseek-ai/dsh-client-hmr`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index a0fee79546..99ffaca7c7 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2634,7 +2634,7 @@ listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
 toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
 ```
 
-Source: [`packages/typert/registry/src/service.ts:324`](../../packages/typert/registry/src/service.ts)
+Source: [`packages/typert/registry/src/service.ts:346`](../../packages/typert/registry/src/service.ts)
 
 ## `ctx.typertGateway` — `TypertGatewayService`
 
diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml
index a048f4e43d..461d1ef4fc 100644
--- a/docs/core-data-structures/core.i18n.yaml
+++ b/docs/core-data-structures/core.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 docs/core-data-structures/core.md
-core.md: eb96988abe096455c4f24ac220a6da3f266e690d
-core.zh.md: 7334b3d3a5bd088f5467a72d7357f87c4c745487
+core.md: f7cf288715a3aec2f7037f12fc983e3172a77cef
+core.zh.md: c17fd1335503c95e7f7f6f96cc286f567a8384e6
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index eb96988abe..f7cf288715 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -20,6 +20,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [llm-streaming.md](llm-streaming.md) | the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
 | [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
+| [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API seams |
 | [goal.md](goal.md) | persisted goal identity, lifecycle snapshots, activation, change records, and round attribution |
 | [commands.md](commands.md) | the human-command seam: definitions, adapter discovery, direct invocation, results, and parsing views |
 | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events |
diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md
index 7334b3d3a5..c17fd13355 100644
--- a/docs/core-data-structures/core.zh.md
+++ b/docs/core-data-structures/core.zh.md
@@ -20,6 +20,7 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [llm-streaming.md](llm-streaming.md) | `StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
+| [typert.md](typert.md) | Remote 调用 descriptor、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
 | [goal.md](goal.md) | 持久 goal 标识、生命周期快照、激活、变更记录与 Round 归属 |
 | [commands.md](commands.md) | 人类命令 seam：定义、适配器发现、直接调用、结果与解析视图 |
 | [session.md](session.md) | 完整的 `SessionEventMap` 变体目录、`TurnTrigger`/`TurnEndReason`、`deriveMessages()`、执行封闭与独立事件 |
diff --git a/docs/core-data-structures/typert.i18n.yaml b/docs/core-data-structures/typert.i18n.yaml
new file mode 100644
index 0000000000..be40eeb20a
--- /dev/null
+++ b/docs/core-data-structures/typert.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 docs/core-data-structures/typert.md
+typert.md: 9f5c63fc554a43fd0248ed08a64dcff566c83b58
+typert.zh.md: 2b74c8325a510ba39d134fa6d463dab273239772
diff --git a/docs/core-data-structures/typert.md b/docs/core-data-structures/typert.md
new file mode 100644
index 0000000000..9f5c63fc55
--- /dev/null
+++ b/docs/core-data-structures/typert.md
@@ -0,0 +1,196 @@
+# TypeRT remote calls
+
+English | [中文](typert.zh.md)
+
+Types shared by generated Remote artifacts, the Host Gateway, and consumer API assemblies. The [TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) owns the architecture and transport decisions; this page records the literal public contracts from [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) and [`dsh-host-api-gateway`](../../packages/host/api-gateway/src/types.ts).
+
+## Lookup and Context declarations
+
+Business-object packages extend two empty maps through declaration merging. A lookup associates one Host object type with its wire identity; a Context declaration associates one scoped Context kind with its wire identity. Generated descriptors name these keys, while runtime providers supply the live resolution behavior.
+
+```ts type-equiv
+/** Merge-extensible Host object lookup declarations. */
+interface TypeRTLookupMap {}
+```
+
+```ts type-equiv
+/** Merge-extensible scoped Context declarations. */
+interface TypeRTContextMap {}
+```
+
+The registry retains a lookup's wire declaration after its resolver unloads. SRC discovery therefore continues to classify the parameter as a lookup and fails unavailable instead of accepting the wire value as an ordinary business object.
+
+```ts type-equiv
+/** Stable wire declaration retained after a lookup provider unloads. */
+interface TypeRTLookupDefinition {
+  /** Merge-declared lookup key. */
+  readonly key: string
+  /** Source parameter name recognized by the SRC weak parser. */
+  readonly parameter: string
+  /** Wire field replacing the Host object parameter. */
+  readonly wire: string
+  /** Canonical Host type symbol used by strict generation. */
+  readonly hostTypeSymbol: string
+  /** Canonical wire type symbol used by strict generation. */
+  readonly wireTypeSymbol: string
+}
+```
+
+## Invocation descriptors
+
+An `InvocationDescriptor` is local reflection, not a wire message. Host and consumer builds generate corresponding descriptors; the request sends only the endpoint and named `args`. Strict codecs carry generated schemas, while SRC codecs enforce JSON-safe values without structural type recovery.
+
+```ts type-equiv
+/** Codec attached to one invocation parameter or result. */
+type TypeRTCodec =
+  | {
+    readonly mode: 'strict'
+    readonly typeSymbol: string
+    readonly schema: TypeRTSchema
+  }
+  | {
+    readonly mode: 'src-json'
+  }
+```
+
+```ts type-equiv
+/** One ordered business parameter in a Remote invocation. */
+interface InvocationParameterDescriptor {
+  /** Source-level parameter name. */
+  readonly name: string
+  /** Required key in the wire `args` object. */
+  readonly wire: string
+  /** Whether the value is JSON or requires a registered Host lookup. */
+  readonly source: 'json' | 'lookup'
+  /** Lookup key when `source` is `lookup`. */
+  readonly lookup?: string
+  /** Boundary codec for the wire representation. */
+  readonly codec: TypeRTCodec
+}
+```
+
+```ts type-equiv
+/** Carrier-independent description of one exported method invocation. */
+interface InvocationDescriptor {
+  /** Globally stable generated identity. */
+  readonly id: string
+  /** Cordis service key owning the method. */
+  readonly service: string
+  /** Wire namespace, defaulting to the service key. */
+  readonly namespace: string
+  /** Public instance method name. */
+  readonly method: string
+  /** Service member invoked when the exported method name is an alias. */
+  readonly implementation?: string
+  /** Receiver selection mode. */
+  readonly invocation:
+    | { readonly kind: 'direct' }
+    | {
+      readonly kind: 'context'
+      readonly context: string
+      readonly wire: string
+      readonly codec: TypeRTCodec
+    }
+  /** Optional consuming-Context projection for one direct lookup parameter. */
+  readonly scope?: {
+    /** Context kind whose Client binder supplies the identity. */
+    readonly context: string
+    /** Lookup parameter wire field replaced by the Context identity. */
+    readonly wire: string
+  }
+  /** Ordered business parameters. */
+  readonly parameters: readonly InvocationParameterDescriptor[]
+  /** Codec for the resolved method result. */
+  readonly result: TypeRTCodec
+  /** Source declaration used only for diagnostics. */
+  readonly sourceLocation?: InvocationSourceLocation
+}
+```
+
+## TypeRT registry
+
+`ctx.typert` separates current-environment descriptors, explicitly selected Remote contributions, live lookup providers, and scoped Context providers. Registrations are Cordis-owned effects and return awaitable disposers.
+
+```ts type-equiv
+/** Minimal TypeRT runtime consumed through dependency inversion. */
+interface TypeRTService {
+  readonly local: TypeRTLocalRegistry
+  readonly remotes: TypeRTRemoteRegistry
+  readonly lookups: TypeRTLookupRegistry
+  readonly contexts: TypeRTContextRegistry
+}
+```
+
+Generated consumer declarations merge direct namespaces into the map inherited by `ClientApi`.
+
+```ts type-equiv
+/** Merge-extensible direct namespace surface generated for Client API services. */
+interface TypeRTRemoteNamespaceMap {}
+```
+
+## Host Gateway
+
+Connection decodes its carrier envelope before calling `ctx.typertGateway`. The request carries exact named wire fields; infrastructure and boundary failures use the Gateway's in-process error taxonomy, although the current RPC adapter folds them into the transport's `internal` error code.
+
+```ts type-equiv
+/** One Remote method request after a carrier has decoded its envelope. */
+interface InvokeRemoteRequest {
+  /** Remote namespace selected by the generated descriptor. */
+  readonly namespace: string
+  /** Exported Service method name. */
+  readonly method: string
+  /** Named wire values; fields must exactly match the descriptor. */
+  readonly args: Readonly<Record<string, unknown>>
+}
+```
+
+```ts type-equiv
+/** Stable infrastructure and boundary failures emitted before or after business execution. */
+type TypertGatewayErrorCode =
+  | 'ambiguous-endpoint'
+  | 'arguments-invalid'
+  | 'binding-invalid'
+  | 'context-failed'
+  | 'context-not-found'
+  | 'context-unavailable'
+  | 'definition-unavailable'
+  | 'input-invalid'
+  | 'invocation-unavailable'
+  | 'lookup-failed'
+  | 'lookup-not-found'
+  | 'lookup-unavailable'
+  | 'method-unavailable'
+  | 'provider-mismatch'
+  | 'result-invalid'
+  | 'service-unavailable'
+  | 'signature-invalid'
+```
+
+```ts type-equiv
+/** Host dispatcher consumed by Connection adapters. */
+interface TypertGateway {
+  /**
+   * Invoke one live Remote method without assuming a carrier or response envelope.
+   * @param request - decoded endpoint and named wire arguments.
+   * @returns the validated business result.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+   */
+  invoke(request: InvokeRemoteRequest): Promise<unknown>
+}
+```
+
+## Consumer API
+
+`ctx.api` exposes only namespaces contributed by imported `/remote` artifacts. Mounting installs the generated descriptors and concrete root/scoped methods as one fiber-owned operation; no JavaScript Proxy or Host Service type enters the consumer.
+
+```ts type-equiv
+/** Typed API service augmented by generated direct Remote namespaces. */
+interface ClientApi extends TypeRTRemoteNamespaceMap {
+  /**
+   * Mount one generated Host-for-Client contribution in the caller's fiber.
+   * @param contribution - explicitly selected Remote package artifact.
+   * @returns disposer withdrawing descriptors and concrete methods together.
+   */
+  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer
+}
+```
diff --git a/docs/core-data-structures/typert.zh.md b/docs/core-data-structures/typert.zh.md
new file mode 100644
index 0000000000..2b74c8325a
--- /dev/null
+++ b/docs/core-data-structures/typert.zh.md
@@ -0,0 +1,196 @@
+# TypeRT 远程调用
+
+[English](typert.md) | 中文
+
+以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-host-api-gateway`](../../packages/host/api-gateway/src/types.ts) 中公共契约的字面定义。
+
+## Lookup 与 Context 声明
+
+业务对象包通过声明合并扩展两个空 map。lookup 将一种 Host 对象类型与其 wire identity 关联；Context 声明将一种 scoped Context 类别与其 wire identity 关联。生成的 descriptor 引用这些 key，运行时提供方则提供活对象解析行为。
+
+```ts type-equiv
+/** Merge-extensible Host object lookup declarations. */
+interface TypeRTLookupMap {}
+```
+
+```ts type-equiv
+/** Merge-extensible scoped Context declarations. */
+interface TypeRTContextMap {}
+```
+
+lookup 的 resolver 卸载后，注册表仍会保留其 wire 声明。因此 SRC 发现过程会继续把该参数归类为 lookup，并因不可用而失败，而不会把 wire 值当作普通业务对象接受。
+
+```ts type-equiv
+/** Stable wire declaration retained after a lookup provider unloads. */
+interface TypeRTLookupDefinition {
+  /** Merge-declared lookup key. */
+  readonly key: string
+  /** Source parameter name recognized by the SRC weak parser. */
+  readonly parameter: string
+  /** Wire field replacing the Host object parameter. */
+  readonly wire: string
+  /** Canonical Host type symbol used by strict generation. */
+  readonly hostTypeSymbol: string
+  /** Canonical wire type symbol used by strict generation. */
+  readonly wireTypeSymbol: string
+}
+```
+
+## 调用 descriptor
+
+`InvocationDescriptor` 是本地反射信息，不是 wire message。Host 与消费方构建会生成彼此对应的 descriptor；请求只发送 endpoint 与具名 `args`。strict codec 携带生成的 schema，SRC codec 则在不恢复结构类型的前提下强制要求 JSON 安全值。
+
+```ts type-equiv
+/** Codec attached to one invocation parameter or result. */
+type TypeRTCodec =
+  | {
+    readonly mode: 'strict'
+    readonly typeSymbol: string
+    readonly schema: TypeRTSchema
+  }
+  | {
+    readonly mode: 'src-json'
+  }
+```
+
+```ts type-equiv
+/** One ordered business parameter in a Remote invocation. */
+interface InvocationParameterDescriptor {
+  /** Source-level parameter name. */
+  readonly name: string
+  /** Required key in the wire `args` object. */
+  readonly wire: string
+  /** Whether the value is JSON or requires a registered Host lookup. */
+  readonly source: 'json' | 'lookup'
+  /** Lookup key when `source` is `lookup`. */
+  readonly lookup?: string
+  /** Boundary codec for the wire representation. */
+  readonly codec: TypeRTCodec
+}
+```
+
+```ts type-equiv
+/** Carrier-independent description of one exported method invocation. */
+interface InvocationDescriptor {
+  /** Globally stable generated identity. */
+  readonly id: string
+  /** Cordis service key owning the method. */
+  readonly service: string
+  /** Wire namespace, defaulting to the service key. */
+  readonly namespace: string
+  /** Public instance method name. */
+  readonly method: string
+  /** Service member invoked when the exported method name is an alias. */
+  readonly implementation?: string
+  /** Receiver selection mode. */
+  readonly invocation:
+    | { readonly kind: 'direct' }
+    | {
+      readonly kind: 'context'
+      readonly context: string
+      readonly wire: string
+      readonly codec: TypeRTCodec
+    }
+  /** Optional consuming-Context projection for one direct lookup parameter. */
+  readonly scope?: {
+    /** Context kind whose Client binder supplies the identity. */
+    readonly context: string
+    /** Lookup parameter wire field replaced by the Context identity. */
+    readonly wire: string
+  }
+  /** Ordered business parameters. */
+  readonly parameters: readonly InvocationParameterDescriptor[]
+  /** Codec for the resolved method result. */
+  readonly result: TypeRTCodec
+  /** Source declaration used only for diagnostics. */
+  readonly sourceLocation?: InvocationSourceLocation
+}
+```
+
+## TypeRT 注册表
+
+`ctx.typert` 分开保存当前环境的 descriptor、显式选择的 Remote contribution、活 lookup 提供方与 scoped Context 提供方。各项注册都是由 Cordis 持有的 effect，并返回可等待的 disposer。
+
+```ts type-equiv
+/** Minimal TypeRT runtime consumed through dependency inversion. */
+interface TypeRTService {
+  readonly local: TypeRTLocalRegistry
+  readonly remotes: TypeRTRemoteRegistry
+  readonly lookups: TypeRTLookupRegistry
+  readonly contexts: TypeRTContextRegistry
+}
+```
+
+生成的消费方声明会把 direct namespace 合并到 `ClientApi` 继承的 map 中。
+
+```ts type-equiv
+/** Merge-extensible direct namespace surface generated for Client API services. */
+interface TypeRTRemoteNamespaceMap {}
+```
+
+## Host Gateway
+
+Connection 会先解码 carrier envelope，再调用 `ctx.typertGateway`。请求携带精确的具名 wire 字段；基础设施与边界失败使用 Gateway 的进程内错误分类体系，但当前 RPC 适配器会把这些错误折叠为传输层的 `internal` 错误码。
+
+```ts type-equiv
+/** One Remote method request after a carrier has decoded its envelope. */
+interface InvokeRemoteRequest {
+  /** Remote namespace selected by the generated descriptor. */
+  readonly namespace: string
+  /** Exported Service method name. */
+  readonly method: string
+  /** Named wire values; fields must exactly match the descriptor. */
+  readonly args: Readonly<Record<string, unknown>>
+}
+```
+
+```ts type-equiv
+/** Stable infrastructure and boundary failures emitted before or after business execution. */
+type TypertGatewayErrorCode =
+  | 'ambiguous-endpoint'
+  | 'arguments-invalid'
+  | 'binding-invalid'
+  | 'context-failed'
+  | 'context-not-found'
+  | 'context-unavailable'
+  | 'definition-unavailable'
+  | 'input-invalid'
+  | 'invocation-unavailable'
+  | 'lookup-failed'
+  | 'lookup-not-found'
+  | 'lookup-unavailable'
+  | 'method-unavailable'
+  | 'provider-mismatch'
+  | 'result-invalid'
+  | 'service-unavailable'
+  | 'signature-invalid'
+```
+
+```ts type-equiv
+/** Host dispatcher consumed by Connection adapters. */
+interface TypertGateway {
+  /**
+   * Invoke one live Remote method without assuming a carrier or response envelope.
+   * @param request - decoded endpoint and named wire arguments.
+   * @returns the validated business result.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+   */
+  invoke(request: InvokeRemoteRequest): Promise<unknown>
+}
+```
+
+## 消费方 API
+
+`ctx.api` 只暴露由已导入 `/remote` 产物贡献的 namespace。挂载会把生成的 descriptor 与具体的 root/scoped 方法作为一项由 fiber 持有的操作统一注册；JavaScript Proxy 与 Host 服务类型都不会进入消费方。
+
+```ts type-equiv
+/** Typed API service augmented by generated direct Remote namespaces. */
+interface ClientApi extends TypeRTRemoteNamespaceMap {
+  /**
+   * Mount one generated Host-for-Client contribution in the caller's fiber.
+   * @param contribution - explicitly selected Remote package artifact.
+   * @returns disposer withdrawing descriptors and concrete methods together.
+   */
+  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer
+}
+```
diff --git a/package.json b/package.json
index 9d0cac6d5e..a327e36ec3 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,7 @@
     "build:web": "pnpm --filter @deepseek-ai/dsh-frontend run build",
     "clean": "tsx scripts/clean.ts",
     "change-scope": "tsx scripts/change-scope.ts",
-    "typecheck": "tsc -b",
+    "typecheck": "npm run build:lib:contracts && tsc -b",
     "lint": "tsx scripts/run-oxlint.ts .",
     "lint:fix": "eslint --config eslint.format.config.mjs --fix . && tsx scripts/run-oxlint.ts . --fix",
     "duplication": "jscpd --config .jscpd.json packages scripts",
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 48f4aadeed..4fe2b12323 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -3097,7 +3097,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TypertContribution',
-    declaration: 'export interface TypertContribution {\n    readonly package: string;\n    readonly face: TypertFace;\n    readonly schemas: readonly TypertSchema[];\n    readonly model: TypertPackageModel;\n    readonly invocations?: readonly InvocationDescriptor[];\n}',
+    declaration: 'export interface TypertContribution {\n    readonly package: string;\n    readonly face: TypertFace;\n    readonly schemas: readonly TypertSchema[];\n    readonly model: TypertPackageModel;\n    readonly invocations: readonly InvocationDescriptor[];\n}',
   },
   {
     name: 'TypeRTDisposer',
diff --git a/packages/host/api-gateway/src/client/index.ts b/packages/host/api-gateway/src/client/index.ts
index 1f92bc0748..5cd8ab75d1 100644
--- a/packages/host/api-gateway/src/client/index.ts
+++ b/packages/host/api-gateway/src/client/index.ts
@@ -284,6 +284,7 @@ class ScopedRemoteNamespace extends Service {
 
   install(descriptor: InvocationDescriptor, projection: ScopedProjection, token: MountToken): void {
     this.assertMethodAvailable(descriptor.method)
+    if (this.methods.size === 0) this.ownerCtx.set(this.name, this)
     const method = descriptor.method
     Object.defineProperty(this, method, {
       configurable: true,
diff --git a/packages/host/api-gateway/src/index.ts b/packages/host/api-gateway/src/index.ts
index 2adfaa8387..64d5715719 100644
--- a/packages/host/api-gateway/src/index.ts
+++ b/packages/host/api-gateway/src/index.ts
@@ -12,7 +12,6 @@ import {
   type InvocationParameterDescriptor,
   type TypeRTCodec,
   type TypeRTGatewayBinding,
-  type TypeRTLookupProvider,
 } from '@deepseek-ai/dsh-type-meta'
 import type {
   InvokeRemoteRequest,
@@ -149,6 +148,7 @@ export class TypertGatewayService extends Service implements TypertGateway {
     payload: unknown,
     _signal: AbortSignal,
   ): Promise<ConnectionRpcResult> {
+    // Remote methods have no cancellation parameter yet, so disconnects do not cancel business work.
     return this.invokeRpc(endpoint, payload)
   }
 
@@ -229,10 +229,8 @@ export class TypertGatewayService extends Service implements TypertGateway {
     const parameters: InvocationParameterDescriptor[] = []
     const wires = new Set<string>()
     for (const name of names) {
-      const matches = this.ctx.typert.lookups.keys()
-        .map(key => ({ key, provider: this.ctx.typert.lookups.get(key) }))
-        .filter((entry): entry is { key: string; provider: TypeRTLookupProvider } =>
-          entry.provider?.parameter === name)
+      const matches = this.ctx.typert.lookups.definitions()
+        .filter(definition => definition.parameter === name)
       if (matches.length > 1) {
         throw new TypertGatewayError(
           'signature-invalid',
@@ -246,7 +244,7 @@ export class TypertGatewayService extends Service implements TypertGateway {
         ? { name, wire: name, source: 'json', codec: { mode: 'src-json' } }
         : {
           name,
-          wire: match.provider.wire,
+          wire: match.wire,
           source: 'lookup',
           lookup: match.key,
           codec: { mode: 'src-json' },
@@ -540,7 +538,7 @@ function decode(
   field: string,
 ): unknown {
   try {
-    if (codec.mode === 'strict') return codec.schema.parse(value)
+    if (codec.mode === 'strict') value = codec.schema.parse(value)
     assertJsonValue(value, new Set())
     return value
   } catch (cause) {
diff --git a/packages/host/api-gateway/tests/client.spec.ts b/packages/host/api-gateway/tests/client.spec.ts
index ab08ef09bc..2e00d29c0d 100644
--- a/packages/host/api-gateway/tests/client.spec.ts
+++ b/packages/host/api-gateway/tests/client.spec.ts
@@ -204,7 +204,13 @@ describe('Client TypeRT API', () => {
   })
 
   it('rejects duplicate, live, scoped-service, and Context namespace collisions', async () => {
-    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { renamed: true } })
+    const ctx = await bench(call)
+    const agentCtx = ctx.extend({ fixtureId: 'agent-remounted' }) as FixtureContext
+    ctx.typert.contexts.registerClient('fixture', {
+      identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId,
+    })
     const direct = directDescriptor()
     const context = contextDescriptor()
 
@@ -242,6 +248,13 @@ describe('Client TypeRT API', () => {
       package: '@fixture/multiple-scoped',
       descriptors: [directDescriptor(), contextDescriptor()],
     })
+    await expect(agentCtx.goals.rename({ objective: 'remounted' })).resolves.toEqual({ renamed: true })
+    expect(call).toHaveBeenLastCalledWith(
+      '/api',
+      'goals/rename',
+      { args: { agentId: 'agent-remounted', request: { objective: 'remounted' } } },
+      expect.any(AbortSignal),
+    )
     await disposeMultipleScoped()
   })
 
diff --git a/packages/host/api-gateway/tests/gateway.spec.ts b/packages/host/api-gateway/tests/gateway.spec.ts
index d5a3f9a8ee..4aeadeedb8 100644
--- a/packages/host/api-gateway/tests/gateway.spec.ts
+++ b/packages/host/api-gateway/tests/gateway.spec.ts
@@ -370,6 +370,19 @@ describe('TypertGatewayService', () => {
     })).resolves.toEqual({ agentId: 'agent-1', title: 'ship', scope: 'direct-src' })
   })
 
+  it('does not downgrade an observed SRC lookup after its provider unloads', async () => {
+    const { ctx, service } = await setup()
+    const dispose = registerAgentLookup(ctx, { id: 'agent-1' })
+    await dispose()
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'lookup-unavailable')
+    expect(service.calls).toEqual([])
+  })
+
   it('derives SRC Remote Context identity and preserves the scoped Proxy receiver', async () => {
     const { ctx } = await setup()
     const scoped = ctx.extend({ fixtureScope: 'agent-src' })
@@ -657,6 +670,22 @@ describe('TypertGatewayService', () => {
     }), 'result-invalid')
   })
 
+  it('rejects non-JSON values after strict codec validation', async () => {
+    const { ctx, service } = await setup()
+    const descriptor = strictOnlyDescriptor()
+    registerStrict(ctx, [{
+      ...descriptor,
+      result: strictCodec('@fixture/gateway#UnknownResult', z.unknown()),
+    }])
+    service.nextResult = 1n
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'strictOnly',
+      args: { request: { title: 'ship' } },
+    }), 'result-invalid')
+  })
+
   it.each([
     undefined,
     Number.NaN,
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index 5757d7cef5..f430d757fb 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -1318,6 +1318,8 @@ class FaceAnalyzer {
    * type evaluator.
    */
   private resolvedRemoteCodecType(authoredType: ts.TypeNode): TypeNodeId {
+    const resolvedType = this.checker.getTypeFromTypeNode(authoredType)
+    this.assertRemoteJsonType(resolvedType, authoredType, new Set(), false)
     const completed = new Map<ts.Type, TypeNodeId>()
     const active = new Map<ts.Type, TypeNodeId>()
     const recursiveDeclarations = new Map<ts.Type, SymbolId>()
@@ -1474,7 +1476,107 @@ class FaceAnalyzer {
         active.delete(type)
       }
     }
-    return convert(this.checker.getTypeFromTypeNode(authoredType))
+    return convert(resolvedType)
+  }
+
+  private assertRemoteJsonType(
+    type: ts.Type,
+    site: ts.TypeNode,
+    active: Set<ts.Type>,
+    allowUndefined: boolean,
+  ): void {
+    const flags = type.flags
+    if ((flags & ts.TypeFlags.Undefined) !== 0 && allowUndefined) return
+    if ((flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0) {
+      this.fail(site, `Remote boundary contains unconstrained ${this.checker.typeToString(type)} data`)
+    }
+    if ((flags & (ts.TypeFlags.BigIntLike | ts.TypeFlags.ESSymbolLike | ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0) {
+      this.fail(site, `Remote boundary contains non-JSON type ${this.checker.typeToString(type)}`)
+    }
+    if ((flags & (ts.TypeFlags.StringLike
+      | ts.TypeFlags.NumberLike
+      | ts.TypeFlags.BooleanLike
+      | ts.TypeFlags.Null
+      | ts.TypeFlags.Never)) !== 0) return
+    if (type.isUnion()) {
+      for (const member of type.types) this.assertRemoteJsonType(member, site, active, allowUndefined)
+      return
+    }
+    if (type.isIntersection()) {
+      const material = type.types.filter(member => !this.isRemotePhantomConstraint(member))
+      if (material.length === 0) this.fail(site, 'Remote boundary contains a symbol-only object')
+      for (const member of material) this.assertRemoteJsonType(member, site, active, false)
+      return
+    }
+    if ((flags & ts.TypeFlags.TypeParameter) !== 0) {
+      this.fail(site, 'Remote boundary contains an unresolved type parameter')
+    }
+    if ((flags & ts.TypeFlags.Object) === 0) {
+      this.fail(site, `Remote boundary contains non-JSON type ${this.checker.typeToString(type)}`)
+    }
+    const symbol = type.getSymbol()
+    const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.[0]
+    if (declaration !== undefined && (ts.isClassDeclaration(declaration) || ts.isClassExpression(declaration))) {
+      this.fail(site, `Remote boundary contains class instance ${symbol?.name ?? this.checker.typeToString(type)}`)
+    }
+    if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) {
+      this.fail(site, 'Remote boundary contains callable or constructable data')
+    }
+    if (active.has(type)) return
+    active.add(type)
+    try {
+      if (this.checker.isTupleType(type)) {
+        const reference = type as ts.TypeReference
+        const target = reference.target as ts.TupleType
+        const arguments_ = this.checker.getTypeArguments(reference)
+        arguments_.forEach((argument, index) => {
+          const elementFlags = target.elementFlags[index] ?? ts.ElementFlags.Required
+          this.assertRemoteJsonType(
+            argument,
+            site,
+            active,
+            (elementFlags & ts.ElementFlags.Optional) !== 0,
+          )
+        })
+        return
+      }
+      if (this.checker.isArrayType(type) || this.checker.isArrayLikeType(type)) {
+        const element = this.checker.getIndexTypeOfType(type, ts.IndexKind.Number)
+        if (element === undefined) this.fail(site, 'Remote boundary array has no element type')
+        this.assertRemoteJsonType(element, site, active, false)
+        return
+      }
+      const properties = this.checker.getPropertiesOfType(type)
+      if (properties.some(property => property.getName().startsWith('__@'))) {
+        this.fail(site, 'Remote boundary contains a symbol-keyed property')
+      }
+      for (const property of properties) {
+        const propertyDeclaration = property.valueDeclaration ?? property.declarations?.[0]
+        const propertyType = this.checker.getTypeOfSymbolAtLocation(property, propertyDeclaration ?? site)
+        this.assertRemoteJsonType(
+          propertyType,
+          site,
+          active,
+          (property.flags & ts.SymbolFlags.Optional) !== 0,
+        )
+      }
+      for (const info of this.checker.getIndexInfosOfType(type)) {
+        if ((info.keyType.flags & ts.TypeFlags.ESSymbolLike) !== 0) {
+          this.fail(site, 'Remote boundary contains a symbol index signature')
+        }
+        this.assertRemoteJsonType(info.type, site, active, false)
+      }
+    } finally {
+      active.delete(type)
+    }
+  }
+
+  private isRemotePhantomConstraint(type: ts.Type): boolean {
+    if ((type.flags & ts.TypeFlags.Unknown) !== 0) return true
+    if ((type.flags & ts.TypeFlags.Any) !== 0 || (type.flags & ts.TypeFlags.Object) === 0) return false
+    if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) return false
+    if (this.checker.getIndexInfosOfType(type).length > 0) return false
+    return this.checker.getPropertiesOfType(type).every(property => property.getName().startsWith('__@'))
   }
 
   private resolvedCycleReference(
diff --git a/packages/typert/generator/tests/remote-model.spec.ts b/packages/typert/generator/tests/remote-model.spec.ts
index 90056e673e..cb6e6e6060 100644
--- a/packages/typert/generator/tests/remote-model.spec.ts
+++ b/packages/typert/generator/tests/remote-model.spec.ts
@@ -284,6 +284,32 @@ export type GenericResult = {
     expect(() => analyzeRemote(root, false)).toThrow(/non-JSON class parameter Agent requires a TypeRTLookupMap entry/)
   })
 
+  it.each([
+    ['bigint', 'bigint'],
+    ['symbol', 'symbol'],
+    ['undefined', 'undefined'],
+    ['any', 'unconstrained any'],
+    ['unknown', 'unconstrained unknown'],
+  ])('rejects non-JSON Remote boundary type %s', (type, message) => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/types.ts', source => source.replace(
+      '  readonly title: string\n}',
+      `  readonly title: string\n  readonly invalid: ${type}\n}`,
+    ))
+
+    expect(() => analyzeRemote(root, false)).toThrow(new RegExp(message))
+  })
+
+  it('keeps optional JSON object fields valid', () => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/types.ts', source => source.replace(
+      '  readonly title: string\n}',
+      '  readonly title: string\n  readonly note?: string\n}',
+    ))
+
+    expect(() => analyzeRemote(root)).not.toThrow()
+  })
+
   it('rejects a Remote Context without a static Context declaration', () => {
     const root = copyFixture()
     editFile(root, 'packages/remote/src/index.ts', source => source.replace("@RemoteContext('agent')", "@RemoteContext('missing')"))
diff --git a/packages/typert/loader/src/index.ts b/packages/typert/loader/src/index.ts
index fee1098340..efe0fa6f94 100644
--- a/packages/typert/loader/src/index.ts
+++ b/packages/typert/loader/src/index.ts
@@ -135,10 +135,8 @@ export function validateTypertManifest(pkgName: string, exported: unknown): Type
     requireMembers(pkgName, object.members, `object "${object.name as string}"`)
     requireTypes(pkgName, object.types, `object "${object.name as string}"`)
   }
-  if (manifest.invocations !== undefined) {
-    for (const value of requireArray(pkgName, manifest.invocations, 'TYPERT.invocations')) {
-      requireInvocation(pkgName, value)
-    }
+  for (const value of requireArray(pkgName, manifest.invocations, 'TYPERT.invocations')) {
+    requireInvocation(pkgName, value)
   }
   return manifest as unknown as TypertContribution
 }
diff --git a/packages/typert/loader/tests/loader.spec.ts b/packages/typert/loader/tests/loader.spec.ts
index 1e7e553605..ec407f82d9 100644
--- a/packages/typert/loader/tests/loader.spec.ts
+++ b/packages/typert/loader/tests/loader.spec.ts
@@ -60,6 +60,7 @@ function typertSource(pkgName: string, entryName: string): string {
     '  face: \'host\',',
     `  schemas: [{ name: '${entryName}', schema: ${entryName} }],`,
     '  model: { services: [], events: [], objects: [] },',
+    '  invocations: [],',
     '}',
     '',
   ].join('\n')
@@ -262,6 +263,7 @@ describe('typert loader', () => {
         '  face: \'host\',',
         '  schemas: [{ name: \'Pending\', schema: Pending }],',
         '  model: { services: [], events: [], objects: [] },',
+        '  invocations: [],',
         '}',
         '',
       ].join('\n'),
@@ -295,7 +297,7 @@ describe('typert loader', () => {
     root = await mkdtemp(join(tmpdir(), 'dsh-typert-loader-'))
     await linkZod(root)
     await writePackage(root, '@fixture/broken', {
-      typertSource: 'export const TYPERT = { package: \'@fixture/broken\', face: \'host\', schemas: [{ name: \'\', schema: {} }], model: { services: [], events: [], objects: [] } }\n',
+      typertSource: 'export const TYPERT = { package: \'@fixture/broken\', face: \'host\', schemas: [{ name: \'\', schema: {} }], model: { services: [], events: [], objects: [] }, invocations: [] }\n',
     })
     const ctx = await boot()
     await ctx.loader.create({ name: '@fixture/broken' })
@@ -410,6 +412,7 @@ describe('validateTypertManifest', () => {
       face: 'host',
       schemas: [{ name: 'A', schema: zodish }],
       model: { services: [], events: [], objects: [] },
+      invocations: [],
     }).schemas).toHaveLength(1)
 
     expect(() => validateTypertManifest('pkg', undefined)).toThrow('no TYPERT manifest object')
@@ -490,12 +493,14 @@ describe('validateTypertManifest', () => {
     })).toThrow('object has a missing or empty exportName')
   })
 
-  it('validates strict invocation descriptors and accepts legacy manifests without them', () => {
-    const legacy = completeManifest(zodish)
-    expect(validateTypertManifest('pkg', legacy)).toBe(legacy)
+  it('requires and validates strict invocation descriptors', () => {
+    const base = completeManifest(zodish)
+    const { invocations: _invocations, ...missingInvocations } = base
+    expect(() => validateTypertManifest('pkg', missingInvocations))
+      .toThrow('TYPERT.invocations must be an array')
 
     const descriptor = strictInvocation()
-    const manifest = { ...legacy, invocations: [descriptor] }
+    const manifest = { ...base, invocations: [descriptor] }
     expect(validateTypertManifest('pkg', manifest)).toBe(manifest)
     const scoped = {
       ...descriptor,
@@ -508,53 +513,53 @@ describe('validateTypertManifest', () => {
         codec: strictCodec('pkg#AgentId'),
       }, ...descriptor.parameters],
     }
-    expect(validateTypertManifest('pkg', { ...legacy, invocations: [scoped] }).invocations)
+    expect(validateTypertManifest('pkg', { ...base, invocations: [scoped] }).invocations)
       .toEqual([scoped])
 
-    expect(() => validateTypertManifest('pkg', { ...legacy, invocations: {} }))
+    expect(() => validateTypertManifest('pkg', { ...base, invocations: {} }))
       .toThrow('TYPERT.invocations must be an array')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{ ...descriptor, invocation: { kind: 'future' } }],
     })).toThrow('receiver kind must be "direct" or "context"')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{ ...descriptor, result: { mode: 'src-json' } }],
     })).toThrow('result codec must use a strict codec')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{ ...descriptor, result: { mode: 'strict', typeSymbol: 'pkg#Result', schema: zodish } }],
     })).toThrow('result codec is not backed by a zod v4 schema')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{
         ...descriptor,
         parameters: [{ ...descriptor.parameters[0], source: 'future' }],
       }],
     })).toThrow('parameter source must be "json" or "lookup"')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{
         ...descriptor,
         parameters: [{ ...descriptor.parameters[0], source: 'lookup' }],
       }],
     })).toThrow('lookup parameter has a missing or empty lookup')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{
         ...descriptor,
         parameters: [{ ...descriptor.parameters[0], lookup: 'agent' }],
       }],
     })).toThrow('JSON parameter declares a lookup')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{
         ...descriptor,
         parameters: [descriptor.parameters[0], { ...descriptor.parameters[0], name: 'again' }],
       }],
     })).toThrow('repeats wire field "request"')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{
         ...descriptor,
         invocation: {
@@ -566,19 +571,19 @@ describe('validateTypertManifest', () => {
       }],
     })).toThrow('repeats Context wire field "request"')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{ ...scoped, scope: null }],
     })).toThrow('scope must be an object')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{ ...scoped, scope: { wire: 'agentId' } }],
     })).toThrow('scope has a missing or empty context')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{ ...scoped, scope: { context: 'agent' } }],
     })).toThrow('scope has a missing or empty wire')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{
         ...scoped,
         invocation: {
@@ -590,11 +595,11 @@ describe('validateTypertManifest', () => {
       }],
     })).toThrow('Context receiver cannot declare a direct scope projection')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{ ...scoped, scope: { context: 'agent', wire: 'missingId' } }],
     })).toThrow('must select its only lookup parameter')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{
         ...scoped,
         parameters: [...scoped.parameters, {
@@ -607,11 +612,11 @@ describe('validateTypertManifest', () => {
       }],
     })).toThrow('must select its only lookup parameter')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{ ...scoped, scope: { context: 'other', wire: 'agentId' } }],
     })).toThrow('must select its only lookup parameter')
     expect(() => validateTypertManifest('pkg', {
-      ...legacy,
+      ...base,
       invocations: [{ ...descriptor, sourceLocation: { file: 'src/index.ts', line: 0, column: 1 } }],
     })).toThrow('sourceLocation.line must be a positive integer')
   })
@@ -646,6 +651,7 @@ function completeManifest(zodish: object) {
     package: 'pkg',
     face: 'host',
     schemas: [{ name: 'Schema', schema: zodish }],
+    invocations: [],
     model: {
       services: [{
         key: 'service',
diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
index 4973732fad..6749cdbeb9 100644
--- a/packages/typert/registry/src/service.ts
+++ b/packages/typert/registry/src/service.ts
@@ -17,6 +17,7 @@ import type {
   TypeRTHostContextProvider,
   TypeRTLocalRegistry,
   TypeRTLookupHost,
+  TypeRTLookupDefinition,
   TypeRTLookupMap,
   TypeRTLookupProvider,
   TypeRTLookupRegistry,
@@ -212,6 +213,7 @@ class RemoteStore {
 
 class LookupStore {
   private readonly providers = new Map<string, ProviderEntry<TypeRTLookupProvider>>()
+  private readonly definitions = new Map<string, TypeRTLookupDefinition>()
   private readonly changes: ChangeSource
 
   constructor(report: ReportObserverError) {
@@ -228,6 +230,7 @@ class LookupStore {
         >,
       ) => this.register(ctx, key, provider),
       get: key => this.providers.get(key)?.provider,
+      definitions: () => [...this.definitions.values()],
       keys: () => [...this.providers.keys()],
       subscribe: listener => this.changes.subscribe(ctx, listener),
     }
@@ -240,10 +243,22 @@ class LookupStore {
     validateNonempty('lookup Host type symbol', provider.hostTypeSymbol)
     validateNonempty('lookup wire type symbol', provider.wireTypeSymbol)
     if (this.providers.has(key)) throw new Error(`typert: lookup "${key}" is already registered`)
+    const definition: TypeRTLookupDefinition = {
+      key,
+      parameter: provider.parameter,
+      wire: provider.wire,
+      hostTypeSymbol: provider.hostTypeSymbol,
+      wireTypeSymbol: provider.wireTypeSymbol,
+    }
+    const known = this.definitions.get(key)
+    if (known !== undefined && !lookupDefinitionEquals(known, definition)) {
+      throw new Error(`typert: lookup "${key}" changed its wire declaration during this registry lifetime`)
+    }
     const owner = {}
     const entry: ProviderEntry<TypeRTLookupProvider> = { provider, owner }
-    const { providers, changes } = this
+    const { definitions, providers, changes } = this
     return ctx.effect(function* () {
+      definitions.set(key, definition)
       providers.set(key, entry)
       changes.emit({ kind: 'lookup', key })
       yield () => {
@@ -256,6 +271,13 @@ class LookupStore {
   }
 }
 
+function lookupDefinitionEquals(left: TypeRTLookupDefinition, right: TypeRTLookupDefinition): boolean {
+  return left.parameter === right.parameter
+    && left.wire === right.wire
+    && left.hostTypeSymbol === right.hostTypeSymbol
+    && left.wireTypeSymbol === right.wireTypeSymbol
+}
+
 class ContextStore {
   private readonly hosts = new Map<string, ProviderEntry<TypeRTHostContextProvider>>()
   private readonly clients = new Map<string, ProviderEntry<TypeRTClientContextBinder>>()
@@ -377,7 +399,7 @@ export class TypertRegistry extends Service implements TypeRTService {
   register(contribution: TypertContribution): TypeRTDisposer {
     const packageRecord = this.validatePackage(contribution)
     const schemaRecords = this.validateSchemas(contribution)
-    const invocations = contribution.invocations ?? []
+    const invocations = contribution.invocations
     this.localStore.validate(invocations)
     const owner = {}
     const { schemas, packages, localStore } = this
diff --git a/packages/typert/registry/src/types.ts b/packages/typert/registry/src/types.ts
index 6ba0e0f1f2..4dcfc4b7a1 100644
--- a/packages/typert/registry/src/types.ts
+++ b/packages/typert/registry/src/types.ts
@@ -83,12 +83,7 @@ export interface TypertContribution {
   readonly face: TypertFace
   readonly schemas: readonly TypertSchema[]
   readonly model: TypertPackageModel
-  /** Host invocation definitions; absent on artifacts generated before Remote support. */
-  readonly invocations?: readonly InvocationDescriptor[]
-}
-
-/** Generated Host contribution with strict Remote invocation definitions. */
-export interface TypertLocalContribution extends TypertContribution {
+  /** Host invocation definitions, empty when the package exports no Remote methods. */
   readonly invocations: readonly InvocationDescriptor[]
 }
 
diff --git a/packages/typert/registry/tests/typert.spec.ts b/packages/typert/registry/tests/typert.spec.ts
index 95f8bc871f..51e7594749 100644
--- a/packages/typert/registry/tests/typert.spec.ts
+++ b/packages/typert/registry/tests/typert.spec.ts
@@ -36,6 +36,7 @@ function toolsContribution(schema: z.ZodType = z.object({ name: z.string() })):
     package: '@deepseek-ai/dsh-tools',
     face: 'host',
     schemas: [{ name: 'ToolInput', schema }],
+    invocations: [],
     model: {
       services: [{
         key: 'tools',
@@ -329,11 +330,19 @@ describe('TypertRegistry', () => {
     })
 
     expect(ctx.typert.lookups.get('fixture')?.resolve('agent-1')).toBe(object)
+    expect(ctx.typert.lookups.definitions()).toEqual([{
+      key: 'fixture',
+      parameter: 'agent',
+      wire: 'agentId',
+      hostTypeSymbol: '@fixture/agent#Agent',
+      wireTypeSymbol: '@fixture/session#SessionId',
+    }])
     expect(ctx.typert.contexts.getHost('registryFixture')?.resolve('agent-1')).toBe(scoped)
     expect(ctx.typert.contexts.getClient('registryFixture')?.identity(scoped)).toBe('agent-1')
 
     await Promise.all([disposeClient(), disposeHost(), disposeLookup()])
     expect(ctx.typert.lookups.keys()).toEqual([])
+    expect(ctx.typert.lookups.definitions()).toHaveLength(1)
     expect(ctx.typert.contexts.getHost('registryFixture')).toBeUndefined()
     expect(ctx.typert.contexts.getClient('registryFixture')).toBeUndefined()
   })
@@ -378,6 +387,15 @@ describe('TypertRegistry', () => {
     ])
 
     await Promise.all([disposeLookupSubscription(), disposeContextSubscription()])
+    for (const changed of [
+      { ...lookup, parameter: 'session' },
+      { ...lookup, wire: 'sessionId' },
+      { ...lookup, hostTypeSymbol: '@fixture#Session' },
+      { ...lookup, wireTypeSymbol: '@fixture#SessionId' },
+    ]) {
+      expect(() => ctx.typert.lookups.register('fixture', changed))
+        .toThrow('changed its wire declaration during this registry lifetime')
+    }
     ctx.typert.lookups.register('fixture', lookup)
     expect(changes).toHaveLength(6)
   })
diff --git a/packages/typert/type-meta/src/index.ts b/packages/typert/type-meta/src/index.ts
index 1e79bb2e55..92438ee0fa 100644
--- a/packages/typert/type-meta/src/index.ts
+++ b/packages/typert/type-meta/src/index.ts
@@ -20,6 +20,7 @@ export type {
   TypeRTHostContextProvider,
   TypeRTLocalRegistry,
   TypeRTLookup,
+  TypeRTLookupDefinition,
   TypeRTLookupHost,
   TypeRTLookupMap,
   TypeRTLookupProvider,
diff --git a/packages/typert/type-meta/src/types.ts b/packages/typert/type-meta/src/types.ts
index 87ab091075..f9ed7ffa97 100644
--- a/packages/typert/type-meta/src/types.ts
+++ b/packages/typert/type-meta/src/types.ts
@@ -189,6 +189,20 @@ export interface TypeRTLookupProvider<Host = unknown, Wire = unknown> {
   resolve(id: Wire): Host | undefined
 }
 
+/** Stable wire declaration retained after a lookup provider unloads. */
+export interface TypeRTLookupDefinition {
+  /** Merge-declared lookup key. */
+  readonly key: string
+  /** Source parameter name recognized by the SRC weak parser. */
+  readonly parameter: string
+  /** Wire field replacing the Host object parameter. */
+  readonly wire: string
+  /** Canonical Host type symbol used by strict generation. */
+  readonly hostTypeSymbol: string
+  /** Canonical wire type symbol used by strict generation. */
+  readonly wireTypeSymbol: string
+}
+
 /** Host resolver for one scoped Remote Context kind. */
 export interface TypeRTHostContextProvider<Wire = unknown> {
   /** Wire field carrying the Context identity. */
@@ -291,6 +305,8 @@ export interface TypeRTLookupRegistry {
    * @returns the live provider, or `undefined` when absent.
    */
   get(key: string): TypeRTLookupProvider | undefined
+  /** @returns lookup declarations observed during this TypeRT Service lifetime. */
+  definitions(): readonly TypeRTLookupDefinition[]
   /** @returns a snapshot of registered provider keys. */
   keys(): readonly string[]
   /**
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 84b957e633..edadc3f134 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1494,6 +1494,66 @@
       "doc": "docs/core-data-structures/settings.md",
       "symbol": "SettingsPathOp",
       "source": "packages/settings/settings/src/index.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "TypeRTLookupMap",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "TypeRTContextMap",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "TypeRTLookupDefinition",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "TypeRTCodec",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "InvocationParameterDescriptor",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "InvocationDescriptor",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "TypeRTService",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "TypeRTRemoteNamespaceMap",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "InvokeRemoteRequest",
+      "source": "packages/host/api-gateway/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "TypertGatewayErrorCode",
+      "source": "packages/host/api-gateway/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "TypertGateway",
+      "source": "packages/host/api-gateway/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/typert.md",
+      "symbol": "ClientApi",
+      "source": "packages/host/api-gateway/src/client/index.ts"
     }
   ]
 }

From 22bec5e63f1656a7c0c3a931a8293f1fb4a223a5 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 18:13:15 +0800
Subject: [PATCH 126/516] feat(typert): propagate Remote cancellation

---
 ...08-02-typert-remote-method-calls.i18n.yaml |  4 +-
 .../2026-08-02-typert-remote-method-calls.md  | 37 ++++++++++------
 ...026-08-02-typert-remote-method-calls.zh.md | 37 ++++++++++------
 docs/core-data-structures/typert.i18n.yaml    |  4 +-
 docs/core-data-structures/typert.md           | 11 ++++-
 docs/core-data-structures/typert.zh.md        | 11 ++++-
 .../cordis/tool-cordis/src/api-catalog.ts     |  4 +-
 packages/host/api-gateway/README.i18n.yaml    |  4 +-
 packages/host/api-gateway/README.md           |  4 +-
 packages/host/api-gateway/README.zh.md        |  4 +-
 packages/host/api-gateway/src/client/index.ts | 14 ++++--
 packages/host/api-gateway/src/index.ts        | 26 ++++++++---
 packages/host/api-gateway/src/types.ts        |  2 +
 .../host/api-gateway/tests/client.spec.ts     | 37 ++++++++++++++--
 .../host/api-gateway/tests/gateway.spec.ts    | 43 +++++++++++++++++--
 packages/typert/generator/src/analyzer.ts     | 23 +++++++++-
 packages/typert/generator/src/emitter.ts      |  4 ++
 packages/typert/generator/src/model.ts        |  3 ++
 .../remote-model/packages/remote/src/index.ts |  3 +-
 .../generator/tests/remote-model.spec.ts      | 31 +++++++++++--
 packages/typert/loader/src/index.ts           |  6 +++
 packages/typert/loader/tests/loader.spec.ts   | 13 ++++++
 packages/typert/registry/src/service.ts       |  3 ++
 packages/typert/registry/tests/typert.spec.ts |  5 +++
 packages/typert/type-meta/README.i18n.yaml    |  4 +-
 packages/typert/type-meta/README.md           |  2 +
 packages/typert/type-meta/README.zh.md        |  2 +
 packages/typert/type-meta/src/types.ts        |  5 +++
 28 files changed, 280 insertions(+), 66 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 752a5d4c8b..bd83c38a3e 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: 91ab8e44ff8aedf666fe3426b85b54491deb340c
-2026-08-02-typert-remote-method-calls.zh.md: 73abd53109d871076aa41af39825c80c35ac3f26
+2026-08-02-typert-remote-method-calls.md: 4268539ecf0d40a9e8080e0571992cc2c5d724af
+2026-08-02-typert-remote-method-calls.zh.md: f9f426f2fb80c74cb9ebaef15e801ccfcf67e027
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index 91ab8e44ff..4268539ecf 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -76,6 +76,8 @@ An endpoint selects exactly one invocation mode. A flow that needs an explicit `
 
 Business packages depend only on the lightweight `@deepseek-ai/dsh-type-meta`. It provides declaration protocols for decorators, `bindTypeRTGateway()`, lookup, Remote Context, and descriptors, without depending on the TypeScript compiler, Zod, HTTP, or the Client runtime.
 
+A method that cooperatively supports cancellation declares `signal: AbortSignal` as its final Host parameter. This reserved parameter is not a business value, lookup, or JSON field. The generated consumer method exposes it as a final optional parameter so ordinary calls remain unchanged while callers that own cancellation can pass a signal.
+
 ## Decorators and the explicit Gateway facet
 
 A decorator only states that a method participates in the Remote contract. It performs no runtime type reflection and injects no hidden symbol into a Service constructor. The arguments to `@Remote('create')` and `@RemoteContext('agent', 'create')` are external method names, while the actual member remains named `remoteExportCreate`. The member name becomes the external method name only when no alias is provided. `typertGateway` is the sole explicit marker that a Service has joined the Gateway, making this capability visible on both the business class and its runtime instance.
@@ -126,6 +128,7 @@ InvocationDescriptor {
   parameters: [
     { name, wire, source: json | lookup, lookup?, codec }
   ]
+  cancellation?: { parameter: 'signal' }
   result: codec
   sourceLocation
 }
@@ -135,7 +138,7 @@ InvocationDescriptor {
 
 The strict generator writes `scope` only when a direct method has exactly one lookup parameter, a `TypeRTContextMap` declaration with the same name exists, and both use the same wire type symbol. `scope.wire` must identify that lookup parameter. It declares that a consumer may fill this parameter from the Context in which the call occurs, without changing the Host receiver or endpoint. No scoped projection is generated when there are multiple lookups, no Context declaration, or mismatched wire types; a type mismatch is a build error.
 
-Parameter order comes from the method signature. HTTP fields come from parameter names or lookup declarations. The Gateway does not infer optional fields, Context types, lookup types, or missing arguments from request contents, and it does not synthesize business defaults.
+Parameter order comes from the method signature. HTTP fields come from parameter names or lookup declarations. A cancellation descriptor reserves only the final `signal` position and keeps it outside named `args`; Connection or a direct Gateway caller supplies the actual signal. The Gateway does not infer optional fields, Context types, lookup types, or missing arguments from request contents, and it does not synthesize business defaults.
 
 A LIB codec contains a Zod schema and a canonical `typeSymbol` consisting of "package + public subpath + export name." An SRC codec is marked only as `src-json`. When the Host and consumer run in different JavaScript realms, each holds its own Zod instances, but both sets are generated from the same TypeRT model and symbol keys.
 
@@ -239,6 +242,7 @@ interface TypeRTRemoteNamespace$676f616c73 {
   create: (
     agentId: SessionId,
     request: CreateGoalRequest,
+    signal?: AbortSignal,
   ) => Promise<CreateGoalResult>
 }
 
@@ -246,6 +250,7 @@ interface TypeRTRemoteMap {
   'goals/create': (
     agentId: SessionId,
     request: CreateGoalRequest,
+    signal?: AbortSignal,
   ) => Promise<CreateGoalResult>
 }
 
@@ -256,6 +261,7 @@ interface TypeRTRemoteNamespaceMap {
 interface TypeRTRemoteContextMap {
   'agent:goals/create': (
     request: CreateGoalRequest,
+    signal?: AbortSignal,
   ) => Promise<CreateGoalResult>
 }
 ```
@@ -296,7 +302,7 @@ Client business packages depend only on `@deepseek-ai/dsh-client-remotes/client`
 
 `ctx.api.mount()` registers a contribution with `TypeRT.remotes`, and its disposer is owned by the Cordis fiber that called the method. Duplicate endpoints, conflicting invocation modes for the same namespace and method, or conflicts between a descriptor and an existing type identity fail immediately.
 
-The API Service materializes each `@Remote` descriptor as a real function on the root `api`. The function constructs named `args` in descriptor parameter order, applies the Client's strict codec, and then calls `ctx.connection.rpc.call('/api', endpoint, { args })`.
+The API Service materializes each `@Remote` descriptor as a real function on the root `api`. The function constructs named `args` in descriptor parameter order, applies the Client's strict codec, and then calls `ctx.connection.rpc.call('/api', endpoint, { args }, signal)`. For a cancellation-aware descriptor, the generated function accepts a final optional signal and combines it with the contribution mount lifetime; unmounting therefore cancels every in-flight carrier call, while a caller can cancel one call independently.
 
 Neither a direct descriptor with `scope` nor a `@RemoteContext` descriptor copies functions into every Agent Scope. The API Service creates one root singleton Cordis Service for each scoped namespace and materializes methods on that Service. When `agent.goals.create()` is called, the Cordis tracker rebinds the Service's `this.ctx` to the current Agent Context. The method then asks the corresponding Context binder for identity from `this.ctx`. A direct scoped projection substitutes this identity at the lookup position named by `scope.wire`; a Context descriptor writes the identity into the receiver's separate wire field. Both issue the same kind of `/api` call.
 
@@ -332,11 +338,11 @@ The Web already depends on build artifacts such as `lib/client.js`, so it requir
 
 SRC supports local source startup. The `WeakMap` records created by `@Remote` and `@RemoteContext()` provide method names and invocation modes. At runtime, the system reads ordered parameter names from the JavaScript function signature and combines them with registered lookup/Context providers to produce a permissive descriptor.
 
-For example, `@Remote('create') remoteExportCreate(agent, request)` resolves to the external method `create`, implementation member `remoteExportCreate`, and two top-level parameters. Lookup registration rewrites `agent` to the wire field `agentId`, while `request` is passed as a same-named JSON parameter. SRC does not start a `ts.Program`, use a preload or loader hook, generate or rewrite source, or inspect the internal structure of an ordinary JSON object.
+For example, `@Remote('create') remoteExportCreate(agent, request, signal)` resolves to the external method `create`, implementation member `remoteExportCreate`, two top-level business parameters, and one cancellation injection point. Lookup registration rewrites `agent` to the wire field `agentId`, `request` is passed as a same-named JSON parameter, and the final `signal` stays outside the payload. SRC does not start a `ts.Program`, use a preload or loader hook, generate or rewrite source, or inspect the internal structure of an ordinary JSON object.
 
 A signature that SRC cannot resolve unambiguously fails when the Service mounts. It does not guess at object destructuring, ambiguity caused by default parameters, rest parameters, nested lookups, or complex types.
 
-LIB supports CI, releases, and the prerequisite Web build. TypeRT scans the complete Host project and checks Remote decorators, explicit bindings, service keys, endpoint conflicts, lookup/Context declarations, public-symbol reachability, JSON codecs, and result codecs, then generates strict descriptors.
+LIB supports CI, releases, and the prerequisite Web build. TypeRT scans the complete Host project and checks Remote decorators, explicit bindings, service keys, endpoint conflicts, lookup/Context declarations, public-symbol reachability, JSON codecs, result codecs, and that a reserved final `signal` parameter has the global `AbortSignal` type, then generates strict descriptors.
 
 At runtime, LIB only loads definitions from `lib`; it does not start the TypeScript compiler. The subsequent association of Services, lookup, Context resolution, invocation, and response encoding in the Host Gateway does not depend on whether a descriptor came from permissive SRC parsing or strict LIB generation.
 
@@ -348,17 +354,18 @@ The Host Gateway registers one `/api` interceptor with Connection and does not m
 
 Invocation resolves the descriptor, receiver, lookup providers, and Context provider again from current state. A current strict descriptor takes precedence over SRC. After a strict endpoint has appeared, `TypeRTLocalRegistry.hasSeen()` keeps it owned when that descriptor is withdrawn and forbids SRC fallback for the remainder of the registry lifetime; re-registering the strict descriptor restores calls. Removing a Service or provider makes invocation fail explicitly, and the Gateway neither retains invalid objects nor invokes a method with a raw lookup ID.
 
-An ordinary `@Remote` call retains the original Service instance as receiver. After lookups succeed, the Gateway calls the member identified by `implementation ?? method` with parameters in descriptor order.
+An ordinary `@Remote` call retains the original Service instance as receiver. After lookups succeed, the Gateway calls the member identified by `implementation ?? method` with parameters in descriptor order, followed by the carrier signal when the descriptor declares cancellation.
 
 A `@RemoteContext('agent')` call first asks the Agent Context provider to resolve the wire identity, then reads the descriptor's service key from that Context and invokes the scoped receiver. The business method receives neither a hidden Context parameter nor an Agent ID.
 
 ```text
-ctx.typertGateway.invoke({ namespace, method, args })
+ctx.typertGateway.invoke({ namespace, method, args, signal })
 → 查找本地 InvocationDescriptor 与 live receiver
 → 按参数 descriptor 读取具名 wire 字段
 → codec 解码普通值或 lookup ID
 → lookup provider 把 ID 解析为活对象
 → direct 使用原 Service；context 先解析 scoped Context 和 Service
+→ cancellation descriptor 存在时把 signal 追加到业务参数末尾
 → Reflect.apply(receiver[implementation ?? method], receiver, orderedArgs)
 → result codec 编码业务结果
 ```
@@ -373,10 +380,10 @@ Connection owns one `/api` route on the HTTP Server. The Gateway mounts a synchr
 ctx.connection.rpc.intercept(
   '/api',
   endpoint => ownsRemoteEndpoint(endpoint),
-  (endpoint, payload) => {
+  (endpoint, payload, signal) => {
     const { namespace, method } = parseEndpoint(endpoint)
     const { args } = parsePayload(payload)
-    return ctx.typertGateway.invoke({ namespace, method, args })
+    return ctx.typertGateway.invoke({ namespace, method, args, signal })
   },
 )
 ```
@@ -405,15 +412,16 @@ The Remote payload is a named JSON object, not a positional array, and does not
 The complete path is:
 
 ```text
-ctx.api.goals.create(sessionId, request)
+ctx.api.goals.create(sessionId, request, signal?)
 → Client InvocationDescriptor 编码 { args: { agentId, request } }
-→ ctx.connection.rpc.call('/api', 'goals/create', { args })
+→ Client 合并 caller signal 与 contribution mount lifetime
+→ ctx.connection.rpc.call('/api', 'goals/create', { args }, signal)
 → Connection 创建 rpcId 和既有 client-request envelope
 → 当前 carrier 发送 POST /api/goals/create
 → Connection Host half 执行共享 trust，再由 bridge 创建标准 Request
 → 复合 FetchHandler 判断 endpoint ownership 并选择目标 FetchHandler
-→ TypeRT interceptor 调用 ctx.typertGateway.invoke(...)
-→ Host InvocationDescriptor 解码、lookup、receiver 解析和 Reflect.apply
+→ TypeRT interceptor 调用 ctx.typertGateway.invoke(..., request.signal)
+→ Host InvocationDescriptor 解码、lookup、receiver 解析并把 signal 注入 Reflect.apply
 → result codec 编码
 → Connection 写入既有 RPC result 并回送相同 rpcId
 → Client result codec 验证并返回 CreateGoalResult
@@ -421,7 +429,7 @@ ctx.api.goals.create(sessionId, request)
 
 Remote does not define a second-layer `{ ok, value/error }` response. Successful values and Gateway errors use the existing RPC response's `result` directly. The current adapter converts every Gateway and business-invocation failure to the existing `RpcError` envelope with `code: 'internal'`; the Gateway's structured error category remains available only in-process, while the message carries the diagnostic across Connection.
 
-The Gateway does not handle per-method permissions, caller identity, cancellation, idempotency, or long-lived connection state. TypeRT endpoints use Connection's trusted-host policy; unclaimed endpoints retain the legacy API Proxy's trust and privileged-method policies. Connection's WebSocket migration remains separate follow-up work.
+The Gateway does not handle per-method permissions, caller identity, idempotency, or long-lived connection state. It only propagates cooperative cancellation from Connection into explicitly cancellation-aware business methods. TypeRT endpoints use Connection's trusted-host policy; unclaimed endpoints retain the legacy API Proxy's trust and privileged-method policies. Connection's WebSocket migration remains separate follow-up work.
 
 ## Connection and protocol boundaries
 
@@ -475,6 +483,7 @@ Connection supplies the shared-channel interceptor and current HTTP carrier mapp
 - Root and Agent-scoped calls cross the real shared `/api` carrier, resolve `agentId` to the live Agent, invoke the original Goal receiver, and return through the existing RPC envelope.
 - The Remote artifacts and maps contain only marked methods and no Browser dependency, preserving the same consumer boundary for a future TUI.
 - Lifecycle tests withdraw and remount descriptors, Services, lookups, Context providers, and Client namespaces; unavailable dependencies fail without stale calls or raw-ID fallback.
+- Cancellation tests cover strict generation, SRC final-name recognition, Client signal fusion, Connection-to-Gateway propagation, and Host injection outside wire `args`.
 - Unclaimed endpoints continue through the existing API Proxy path with its trust, privileged-method, Permission/Approval, and Session event-stream behavior unchanged.
 
 ## Consequences
@@ -499,4 +508,4 @@ Remote endpoints use Connection's `trusted-host` authority. Loopback is accepted
 
 `hasSeen()` favors strict-definition safety over SRC availability. While a strict descriptor is withdrawn, such as during HMR, the Gateway continues to claim the endpoint and reports it unavailable instead of falling back to a weak SRC descriptor. Re-registration restores it; only a TypeRT registry restart forgets the historical strict definition.
 
-Connection supplies an `AbortSignal`, but Remote business signatures have no cancellation parameter. A client disconnect therefore does not cancel business work; cancellation remains deferred rather than being implied by the transport handler shape.
+Cancellation-aware Remote signatures receive Connection's request `AbortSignal`, so an HTTP disconnect or Client-side abort reaches ongoing business work without entering the JSON protocol. Cancellation remains cooperative: methods without the reserved final parameter continue running, and a method that receives the signal must pass it to its own cancellable operations or observe it directly.
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 73abd53109..f9f426f2fb 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -76,6 +76,8 @@ export class ScopedGoalService extends Service {
 
 业务包只依赖轻量的 `@deepseek-ai/dsh-type-meta`。它提供 decorator、`bindTypeRTGateway()`、lookup、Remote Context 和 descriptor 的声明协议，不依赖 TypeScript compiler、Zod、HTTP 或 Client runtime。
 
+支持协作式取消的方法会把 `signal: AbortSignal` 声明为最后一个 Host 参数。这个保留参数不是业务值、lookup 或 JSON 字段。生成的消费方方法将其暴露为最后一个可选参数，因此普通调用保持不变，而拥有取消控制权的调用方可以传入 signal。
+
 ## Decorator 与显式 Gateway facet
 
 Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteContext('agent', 'create')` 的参数是外部方法名，实际成员名保持 `remoteExportCreate`；未给别名时才使用成员名作为外部方法名。`typertGateway` 是 Service 加入 Gateway 的唯一显式标志，使业务类和运行时实例都能直接看出这项能力。
@@ -126,6 +128,7 @@ InvocationDescriptor {
   parameters: [
     { name, wire, source: json | lookup, lookup?, codec }
   ]
+  cancellation?: { parameter: 'signal' }
   result: codec
   sourceLocation
 }
@@ -135,7 +138,7 @@ InvocationDescriptor {
 
 严格生成器只在 direct 方法恰好包含一个 lookup 参数、同名 `TypeRTContextMap` 声明存在且两者使用同一 wire 类型 symbol 时写入 `scope`。`scope.wire` 必须指向该 lookup 参数；它声明消费端可以从调用所在 Context 补入这个参数，不改变 Host receiver 或 endpoint。多个 lookup、缺少 Context 声明或 wire 类型不一致时不生成 scoped 投影，其中类型不一致属于构建错误。
 
-参数顺序来自方法签名，HTTP 字段来自参数名或 lookup 声明。Gateway 不根据请求内容推断可选字段、Context 类型、lookup 类型或缺失参数，也不会合成业务默认值。
+参数顺序来自方法签名，HTTP 字段来自参数名或 lookup 声明。取消 descriptor 只保留最后一个 `signal` 位置，并使其不进入具名 `args`；实际 signal 由 Connection 或直接调用 Gateway 的调用方提供。Gateway 不根据请求内容推断可选字段、Context 类型、lookup 类型或缺失参数，也不会合成业务默认值。
 
 LIB codec 带有 Zod schema 和“package + 公共 subpath + export name”的规范 `typeSymbol`；SRC codec 只标记 `src-json`。Host 和消费端运行在不同 JavaScript realm 时会各自持有 Zod 实例，但这些实例由同一 TypeRT 模型和 symbol key 生成。
 
@@ -239,6 +242,7 @@ interface TypeRTRemoteNamespace$676f616c73 {
   create: (
     agentId: SessionId,
     request: CreateGoalRequest,
+    signal?: AbortSignal,
   ) => Promise<CreateGoalResult>
 }
 
@@ -246,6 +250,7 @@ interface TypeRTRemoteMap {
   'goals/create': (
     agentId: SessionId,
     request: CreateGoalRequest,
+    signal?: AbortSignal,
   ) => Promise<CreateGoalResult>
 }
 
@@ -256,6 +261,7 @@ interface TypeRTRemoteNamespaceMap {
 interface TypeRTRemoteContextMap {
   'agent:goals/create': (
     request: CreateGoalRequest,
+    signal?: AbortSignal,
   ) => Promise<CreateGoalResult>
 }
 ```
@@ -296,7 +302,7 @@ Client 业务包只引用 `@deepseek-ai/dsh-client-remotes/client`，不直接
 
 `ctx.api.mount()` 把 contribution 注册到 `TypeRT.remotes`，并由调用该方法的 Cordis fiber 持有 disposer。endpoint 重复、同一 namespace/method 模式冲突或 descriptor 与现有类型身份冲突时直接失败。
 
-API Service 把 `@Remote` descriptor 实体化为根 `api` 上的真实函数。函数按 descriptor 的位置参数顺序构造具名 `args`，执行 Client strict codec，然后调用 `ctx.connection.rpc.call('/api', endpoint, { args })`。
+API Service 把 `@Remote` descriptor 实体化为根 `api` 上的真实函数。函数按 descriptor 的位置参数顺序构造具名 `args`，执行 Client strict codec，然后调用 `ctx.connection.rpc.call('/api', endpoint, { args }, signal)`。对于支持取消的 descriptor，生成的函数接受最后一个可选 signal，并将其与 contribution 的挂载生命周期合并；因此卸载会取消所有正在进行的 carrier 调用，而调用方也可以单独取消一次调用。
 
 带 `scope` 的 direct descriptor 和 `@RemoteContext` descriptor 都不为每个 Agent Scope 复制函数。API Service 为每个 scoped namespace 建立一个 root singleton Cordis Service，并在该 Service 上实体化方法；Cordis tracker 在 `agent.goals.create()` 调用时把 Service 的 `this.ctx` rebind 到当前 Agent Context。方法再通过对应 Context binder 从 `this.ctx` 取得 identity。direct scoped 投影用 identity 替代 `scope.wire` 指定的 lookup 位置，Context descriptor 则把 identity 写入 receiver 的独立 wire 字段；两者都发起同一种 `/api` 调用。
 
@@ -332,11 +338,11 @@ Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完
 
 SRC 面向本地源码启动。`@Remote` 和 `@RemoteContext()` 的 WeakMap 记录给出方法名和调用模式，运行时从 JavaScript 函数签名读取顺序参数名，并结合已注册 lookup/Context provider 生成弱 descriptor。
 
-例如 `@Remote('create') remoteExportCreate(agent, request)` 解析为外部方法 `create`、实现成员 `remoteExportCreate` 和两个顶层参数；lookup 注册把 `agent` 改写为 wire 字段 `agentId`，`request` 按同名 JSON 参数传递。SRC 不启动 `ts.Program`，不使用 preload、loader hook、源码生成或模块改写，也不检查普通 JSON 对象的内部结构。
+例如 `@Remote('create') remoteExportCreate(agent, request, signal)` 解析为外部方法 `create`、实现成员 `remoteExportCreate`、两个顶层业务参数和一个取消注入点；lookup 注册把 `agent` 改写为 wire 字段 `agentId`，`request` 按同名 JSON 参数传递，最后一个 `signal` 则留在 payload 之外。SRC 不启动 `ts.Program`，不使用 preload、loader hook、源码生成或模块改写，也不检查普通 JSON 对象的内部结构。
 
 SRC 无法明确解析的签名在 Service 挂载时失败。对象解构、默认参数造成的歧义、rest 参数、嵌套 lookup 和复杂类型不做猜测。
 
-LIB 面向 CI、发布和 Web 前置构建。TypeRT 扫描完整 Host project，检查 Remote decorator、显式 binding、service key、endpoint 冲突、lookup/Context 声明、公共符号可达性、JSON codec 和结果 codec，并生成严格 descriptor。
+LIB 面向 CI、发布和 Web 前置构建。TypeRT 扫描完整 Host project，检查 Remote decorator、显式 binding、service key、endpoint 冲突、lookup/Context 声明、公共符号可达性、JSON codec、结果 codec，以及保留的最后一个 `signal` 参数是否具有全局 `AbortSignal` 类型，并生成严格 descriptor。
 
 LIB 运行时只加载 `lib` 中的 definition，不启动 TypeScript compiler。Host Gateway 后续的 Service 关联、lookup、Context 解析、调用和响应编码不区分 descriptor 来自 SRC 弱解析还是 LIB 严格生成。
 
@@ -348,17 +354,18 @@ Host Gateway 向 Connection 注册一个 `/api` interceptor，不维护第二份
 
 每次调用都会重新从当前状态解析 descriptor、receiver、lookup 提供方与 Context 提供方。当前 strict descriptor 优先于 SRC。strict endpoint 一旦出现，即使随后撤回对应 descriptor，`TypeRTLocalRegistry.hasSeen()` 仍会在注册表剩余生命周期内保持对它的认领并禁止回退 SRC；重新注册 strict descriptor 即可恢复调用。移除 Service 或提供方会让调用明确失败；Gateway 既不保留失效对象，也不会以原始 lookup ID 调用方法。
 
-普通 `@Remote` 调用保留原始 Service 实例作为 receiver。lookup 成功后，Gateway 按 descriptor 的参数顺序调用 `implementation ?? method` 指定的成员。
+普通 `@Remote` 调用保留原始 Service 实例作为 receiver。lookup 成功后，Gateway 按 descriptor 的参数顺序调用 `implementation ?? method` 指定的成员；若 descriptor 声明取消，则在这些参数之后追加 carrier signal。
 
 `@RemoteContext('agent')` 调用先由 Agent Context provider 解析 wire identity，再从该 Context 读取 descriptor 的 service key 并调用 scoped receiver。业务方法不会收到隐藏 Context 参数或 Agent ID。
 
 ```text
-ctx.typertGateway.invoke({ namespace, method, args })
+ctx.typertGateway.invoke({ namespace, method, args, signal })
 → 查找本地 InvocationDescriptor 与 live receiver
 → 按参数 descriptor 读取具名 wire 字段
 → codec 解码普通值或 lookup ID
 → lookup provider 把 ID 解析为活对象
 → direct 使用原 Service；context 先解析 scoped Context 和 Service
+→ cancellation descriptor 存在时把 signal 追加到业务参数末尾
 → Reflect.apply(receiver[implementation ?? method], receiver, orderedArgs)
 → result codec 编码业务结果
 ```
@@ -373,10 +380,10 @@ Connection 在 HTTP Server 上持有唯一 `/api` route。Gateway 把同步 endp
 ctx.connection.rpc.intercept(
   '/api',
   endpoint => ownsRemoteEndpoint(endpoint),
-  (endpoint, payload) => {
+  (endpoint, payload, signal) => {
     const { namespace, method } = parseEndpoint(endpoint)
     const { args } = parsePayload(payload)
-    return ctx.typertGateway.invoke({ namespace, method, args })
+    return ctx.typertGateway.invoke({ namespace, method, args, signal })
   },
 )
 ```
@@ -405,15 +412,16 @@ Remote payload 使用具名 JSON 对象，不使用位置数组，也不发送 `
 完整链路为：
 
 ```text
-ctx.api.goals.create(sessionId, request)
+ctx.api.goals.create(sessionId, request, signal?)
 → Client InvocationDescriptor 编码 { args: { agentId, request } }
-→ ctx.connection.rpc.call('/api', 'goals/create', { args })
+→ Client 合并 caller signal 与 contribution mount lifetime
+→ ctx.connection.rpc.call('/api', 'goals/create', { args }, signal)
 → Connection 创建 rpcId 和既有 client-request envelope
 → 当前 carrier 发送 POST /api/goals/create
 → Connection Host half 执行共享 trust，再由 bridge 创建标准 Request
 → 复合 FetchHandler 判断 endpoint ownership 并选择目标 FetchHandler
-→ TypeRT interceptor 调用 ctx.typertGateway.invoke(...)
-→ Host InvocationDescriptor 解码、lookup、receiver 解析和 Reflect.apply
+→ TypeRT interceptor 调用 ctx.typertGateway.invoke(..., request.signal)
+→ Host InvocationDescriptor 解码、lookup、receiver 解析并把 signal 注入 Reflect.apply
 → result codec 编码
 → Connection 写入既有 RPC result 并回送相同 rpcId
 → Client result codec 验证并返回 CreateGoalResult
@@ -421,7 +429,7 @@ ctx.api.goals.create(sessionId, request)
 
 Remote 不定义第二层 `{ ok, value/error }` response。成功值和 Gateway 错误直接使用既有 RPC response 的 `result`。当前 adapter 把所有 Gateway 与业务调用失败转换为既有 `RpcError` envelope，并统一使用 `code: 'internal'`；Gateway 的结构化错误分类仅在进程内保留，诊断信息则通过 message 跨 Connection 传递。
 
-Gateway 不处理逐方法权限、调用者身份、取消、幂等或长连接状态。TypeRT endpoint 使用 Connection 的 trusted-host 策略；未认领 endpoint 保留旧 API Proxy 的 trust 和 privileged-method 策略。Connection/WebSocket 迁移后续独立完成。
+Gateway 不处理逐方法权限、调用者身份、幂等或长连接状态。它只把 Connection 的协作式取消传播给显式支持取消的业务方法。TypeRT endpoint 使用 Connection 的 trusted-host 策略；未认领 endpoint 保留旧 API Proxy 的 trust 和 privileged-method 策略。Connection/WebSocket 迁移后续独立完成。
 
 ## Connection 与协议边界
 
@@ -475,6 +483,7 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 - Root 与 Agent-scoped 调用会经过真实的共享 `/api` carrier，将 `agentId` 解析为活 Agent，调用原始 Goal receiver，并通过既有 RPC envelope 返回。
 - Remote 产物与 map 仅包含已标记的方法，不依赖 Browser，从而为未来 TUI 保留相同的消费方边界。
 - 生命周期测试会撤回并重新挂载 descriptor、Service、lookup、Context 提供方和 Client namespace；依赖不可用时，调用会失败，且不会使用陈旧调用或回退原始 ID。
+- 取消测试覆盖严格生成、SRC 末位参数名识别、Client signal 合并、Connection 到 Gateway 的传播，以及 Host 在 wire `args` 之外的注入。
 - 未认领 endpoint 继续使用既有 API Proxy 路径，其 trust、privileged-method、Permission/Approval 与 Session 事件流行为保持不变。
 
 ## 后果
@@ -499,4 +508,4 @@ Remote endpoint 使用 Connection 的 `trusted-host` authority。系统默认接
 
 `hasSeen()` 优先保障 strict definition 的安全性，而非 SRC 可用性。strict descriptor 撤回时（例如 HMR 期间），Gateway 会继续认领 endpoint 并报告不可用，而不会回退到弱 SRC descriptor。重新注册即可恢复；只有重启 TypeRT 注册表才会忘记历史 strict definition。
 
-Connection 提供 `AbortSignal`，但 Remote 业务签名没有取消参数。因此 Client 断连不会取消业务工作；取消仍作为后续工作，而不能由 transport handler 的形状暗示已经支持。
+支持取消的 Remote 签名会接收 Connection 请求的 `AbortSignal`，因此 HTTP 断连或 Client 侧 abort 能在不进入 JSON 协议的情况下传递到正在进行的业务工作。取消仍是协作式的：没有保留末位参数的方法会继续运行；收到 signal 的方法必须将它传给自身支持取消的操作，或自行观测它。
diff --git a/docs/core-data-structures/typert.i18n.yaml b/docs/core-data-structures/typert.i18n.yaml
index be40eeb20a..a5484d06c4 100644
--- a/docs/core-data-structures/typert.i18n.yaml
+++ b/docs/core-data-structures/typert.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 docs/core-data-structures/typert.md
-typert.md: 9f5c63fc554a43fd0248ed08a64dcff566c83b58
-typert.zh.md: 2b74c8325a510ba39d134fa6d463dab273239772
+typert.md: da6e229ff6a2300c36f5734ad05c621a5e63082d
+typert.zh.md: b3b0e8897756b5b4f9b645522cc5a1b27eac1d33
diff --git a/docs/core-data-structures/typert.md b/docs/core-data-structures/typert.md
index 9f5c63fc55..da6e229ff6 100644
--- a/docs/core-data-structures/typert.md
+++ b/docs/core-data-structures/typert.md
@@ -38,7 +38,7 @@ interface TypeRTLookupDefinition {
 
 ## Invocation descriptors
 
-An `InvocationDescriptor` is local reflection, not a wire message. Host and consumer builds generate corresponding descriptors; the request sends only the endpoint and named `args`. Strict codecs carry generated schemas, while SRC codecs enforce JSON-safe values without structural type recovery.
+An `InvocationDescriptor` is local reflection, not a wire message. Host and consumer builds generate corresponding descriptors; the request sends only the endpoint and named `args`. Strict codecs carry generated schemas, while SRC codecs enforce JSON-safe values without structural type recovery. Cancellation is an out-of-band carrier signal injected after business parameters and never enters `args`.
 
 ```ts type-equiv
 /** Codec attached to one invocation parameter or result. */
@@ -100,6 +100,11 @@ interface InvocationDescriptor {
   }
   /** Ordered business parameters. */
   readonly parameters: readonly InvocationParameterDescriptor[]
+  /** Transport cancellation injected after business parameters instead of entering wire args. */
+  readonly cancellation?: {
+    /** Reserved final Host method parameter. */
+    readonly parameter: 'signal'
+  }
   /** Codec for the resolved method result. */
   readonly result: TypeRTCodec
   /** Source declaration used only for diagnostics. */
@@ -130,7 +135,7 @@ interface TypeRTRemoteNamespaceMap {}
 
 ## Host Gateway
 
-Connection decodes its carrier envelope before calling `ctx.typertGateway`. The request carries exact named wire fields; infrastructure and boundary failures use the Gateway's in-process error taxonomy, although the current RPC adapter folds them into the transport's `internal` error code.
+Connection decodes its carrier envelope before calling `ctx.typertGateway`. The request carries exact named wire fields and the carrier's cancellation signal separately; infrastructure and boundary failures use the Gateway's in-process error taxonomy, although the current RPC adapter folds them into the transport's `internal` error code.
 
 ```ts type-equiv
 /** One Remote method request after a carrier has decoded its envelope. */
@@ -141,6 +146,8 @@ interface InvokeRemoteRequest {
   readonly method: string
   /** Named wire values; fields must exactly match the descriptor. */
   readonly args: Readonly<Record<string, unknown>>
+  /** Carrier or direct-caller cancellation injected only into cancellation-aware methods. */
+  readonly signal?: AbortSignal
 }
 ```
 
diff --git a/docs/core-data-structures/typert.zh.md b/docs/core-data-structures/typert.zh.md
index 2b74c8325a..b3b0e88977 100644
--- a/docs/core-data-structures/typert.zh.md
+++ b/docs/core-data-structures/typert.zh.md
@@ -38,7 +38,7 @@ interface TypeRTLookupDefinition {
 
 ## 调用 descriptor
 
-`InvocationDescriptor` 是本地反射信息，不是 wire message。Host 与消费方构建会生成彼此对应的 descriptor；请求只发送 endpoint 与具名 `args`。strict codec 携带生成的 schema，SRC codec 则在不恢复结构类型的前提下强制要求 JSON 安全值。
+`InvocationDescriptor` 是本地反射信息，不是 wire message。Host 与消费方构建会生成彼此对应的 descriptor；请求只发送 endpoint 与具名 `args`。strict codec 携带生成的 schema，SRC codec 则在不恢复结构类型的前提下强制要求 JSON 安全值。取消通过带外 carrier signal 表达：它在业务参数之后注入，绝不进入 `args`。
 
 ```ts type-equiv
 /** Codec attached to one invocation parameter or result. */
@@ -100,6 +100,11 @@ interface InvocationDescriptor {
   }
   /** Ordered business parameters. */
   readonly parameters: readonly InvocationParameterDescriptor[]
+  /** Transport cancellation injected after business parameters instead of entering wire args. */
+  readonly cancellation?: {
+    /** Reserved final Host method parameter. */
+    readonly parameter: 'signal'
+  }
   /** Codec for the resolved method result. */
   readonly result: TypeRTCodec
   /** Source declaration used only for diagnostics. */
@@ -130,7 +135,7 @@ interface TypeRTRemoteNamespaceMap {}
 
 ## Host Gateway
 
-Connection 会先解码 carrier envelope，再调用 `ctx.typertGateway`。请求携带精确的具名 wire 字段；基础设施与边界失败使用 Gateway 的进程内错误分类体系，但当前 RPC 适配器会把这些错误折叠为传输层的 `internal` 错误码。
+Connection 会先解码 carrier envelope，再调用 `ctx.typertGateway`。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带；基础设施与边界失败使用 Gateway 的进程内错误分类体系，但当前 RPC 适配器会把这些错误折叠为传输层的 `internal` 错误码。
 
 ```ts type-equiv
 /** One Remote method request after a carrier has decoded its envelope. */
@@ -141,6 +146,8 @@ interface InvokeRemoteRequest {
   readonly method: string
   /** Named wire values; fields must exactly match the descriptor. */
   readonly args: Readonly<Record<string, unknown>>
+  /** Carrier or direct-caller cancellation injected only into cancellation-aware methods. */
+  readonly signal?: AbortSignal
 }
 ```
 
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 4fe2b12323..d8d067ce3e 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -2097,7 +2097,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'InvocationDescriptor',
-    declaration: 'export interface InvocationDescriptor {\n    readonly id: string;\n    readonly service: string;\n    readonly namespace: string;\n    readonly method: string;\n    readonly implementation?: string;\n    readonly invocation: {\n        readonly kind: \'direct\';\n    } | {\n        readonly kind: \'context\';\n        readonly context: string;\n        readonly wire: string;\n        readonly codec: TypeRTCodec;\n    };\n    readonly scope?: {\n        readonly context: string;\n        readonly wire: string;\n    };\n    readonly parameters: readonly InvocationParameterDescriptor[];\n    readonly result: TypeRTCodec;\n    readonly sourceLocation?: InvocationSourceLocation;\n}',
+    declaration: 'export interface InvocationDescriptor {\n    readonly id: string;\n    readonly service: string;\n    readonly namespace: string;\n    readonly method: string;\n    readonly implementation?: string;\n    readonly invocation: {\n        readonly kind: \'direct\';\n    } | {\n        readonly kind: \'context\';\n        readonly context: string;\n        readonly wire: string;\n        readonly codec: TypeRTCodec;\n    };\n    readonly scope?: {\n        readonly context: string;\n        readonly wire: string;\n    };\n    readonly parameters: readonly InvocationParameterDescriptor[];\n    readonly cancellation?: {\n        readonly parameter: \'signal\';\n    };\n    readonly result: TypeRTCodec;\n    readonly sourceLocation?: InvocationSourceLocation;\n}',
   },
   {
     name: 'InvocationParameterDescriptor',
@@ -2109,7 +2109,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'InvokeRemoteRequest',
-    declaration: 'export interface InvokeRemoteRequest {\n    readonly namespace: string;\n    readonly method: string;\n    readonly args: Readonly<Record<string, unknown>>;\n}',
+    declaration: 'export interface InvokeRemoteRequest {\n    readonly namespace: string;\n    readonly method: string;\n    readonly args: Readonly<Record<string, unknown>>;\n    readonly signal?: AbortSignal;\n}',
   },
   {
     name: 'JsonSchemaNode',
diff --git a/packages/host/api-gateway/README.i18n.yaml b/packages/host/api-gateway/README.i18n.yaml
index 747aa65665..a1c22433f3 100644
--- a/packages/host/api-gateway/README.i18n.yaml
+++ b/packages/host/api-gateway/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/host/api-gateway/README.md
-README.md: cc80bb19fec15414aa0857154a8a36fb4f642672
-README.zh.md: 6febb1cfe4fc7fa4c5a17e1e4f6a21e2ee03e295
+README.md: 9cb6e7e1c0a23789ab4ab2c999b5a6c2d4cd32f9
+README.zh.md: 609580ceb77649ba8df6103093a72092c9ccc8a1
diff --git a/packages/host/api-gateway/README.md b/packages/host/api-gateway/README.md
index cc80bb19fe..9cb6e7e1c0 100644
--- a/packages/host/api-gateway/README.md
+++ b/packages/host/api-gateway/README.md
@@ -12,11 +12,13 @@ Strict mode reads generated invocation descriptors from `ctx.typert.local`. Look
 
 The Host entry registers a trusted-host interceptor on Connection's shared `/api` FetchHandler. Connection passes this composite handler through its HTTP bridge; the handler dispatches claimed endpoints to Gateway and unclaimed endpoints to API Proxy. Direct `invoke()` calls preserve business errors; `TypertGatewayError` distinguishes failures owned by dispatch, binding, providers, lookup, Context, arguments, and codecs.
 
+A cancellation-aware Remote method declares `signal: AbortSignal` as its final Host parameter. The signal is descriptor metadata rather than a wire argument: Connection supplies it to the Gateway, and the Gateway injects it after decoded business parameters. SRC recognizes the reserved final name, while strict generation additionally requires the global `AbortSignal` type.
+
 ## Client service: `ClientApi` (ctx key: `api`)
 
 `ctx.api.mount()` validates and registers a generated Host-for-Client contribution, then installs concrete direct and scoped methods for the calling Cordis fiber. Duplicate endpoints, namespace collisions, and descriptors without strict generated codecs fail before methods become callable.
 
-Each call validates positional inputs, constructs the descriptor's exact named `args`, and sends it through `ctx.connection.rpc.call('/api', endpoint, ...)`. The returned value is validated before reaching application code. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls, and makes retained method handles reject.
+Each call validates positional inputs, constructs the descriptor's exact named `args`, and sends it through `ctx.connection.rpc.call('/api', endpoint, ...)`. Generated cancellation-aware methods accept a final optional `AbortSignal`; the Client combines it with the contribution mount lifetime before calling Connection. The returned value is validated before reaching application code. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls, and makes retained method handles reject.
 
 Generated declaration merges provide the TypeScript API. The Client entry contains no Host Service or Host Cordis interface merge, and method lookup and invocation use ordinary objects and functions rather than a JavaScript Proxy.
 
diff --git a/packages/host/api-gateway/README.zh.md b/packages/host/api-gateway/README.zh.md
index 6febb1cfe4..609580ceb7 100644
--- a/packages/host/api-gateway/README.zh.md
+++ b/packages/host/api-gateway/README.zh.md
@@ -12,11 +12,13 @@
 
 Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandler 上注册 trusted-host interceptor。Connection 把这个复合 handler 交给 HTTP bridge；handler 将已认领 endpoint 分发给 Gateway，未认领 endpoint 则交给 API Proxy。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 可区分分发、绑定、提供方、查找、Context、参数和编解码器各自负责的故障。
 
+支持取消的 Remote 方法会把 `signal: AbortSignal` 声明为最后一个 Host 参数。signal 是 descriptor 元数据，而不是 wire 参数：Connection 将它提供给 Gateway，Gateway 则在已解码的业务参数之后注入它。SRC 识别这个保留的末位参数名，严格生成还要求它具有全局 `AbortSignal` 类型。
+
 ## Client 服务：`ClientApi`（ctx key：`api`）
 
 `ctx.api.mount()` 会校验并注册生成的 Host-for-Client 贡献项，然后为发起调用的 Cordis fiber 安装具体的直接方法和作用域方法。重复端点、命名空间冲突，以及缺少生成的严格编解码器的描述符，都会在方法可调用前报错。
 
-每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api', endpoint, ...)` 发送。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
+每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api', endpoint, ...)` 发送。生成的支持取消的方法接受最后一个可选 `AbortSignal`；Client 会在调用 Connection 前将它与贡献项的挂载生命周期合并。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
 
 生成的声明合并提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
 
diff --git a/packages/host/api-gateway/src/client/index.ts b/packages/host/api-gateway/src/client/index.ts
index 5cd8ab75d1..292df54152 100644
--- a/packages/host/api-gateway/src/client/index.ts
+++ b/packages/host/api-gateway/src/client/index.ts
@@ -223,9 +223,13 @@ class ClientApiService extends Service implements ClientApi {
     const endpoint = endpointOf(descriptor)
     if (!token.active) throw new Error(`client api: Remote method ${endpoint} is no longer mounted`)
     const expected = descriptor.parameters.length - (projection?.parameterIndex === undefined ? 0 : 1)
-    if (values.length !== expected) {
+    const hasCallerSignal = descriptor.cancellation !== undefined && values.length === expected + 1
+    if (values.length !== expected && !hasCallerSignal) {
+      const contract = descriptor.cancellation === undefined
+        ? `${String(expected)} argument(s)`
+        : `${String(expected)} business argument(s) plus an optional AbortSignal`
       throw new Error(
-        `client api: ${endpoint} expected ${String(expected)} argument(s), got ${String(values.length)}`,
+        `client api: ${endpoint} expected ${contract}, got ${String(values.length)}`,
       )
     }
     const args: Record<string, unknown> = {}
@@ -248,7 +252,11 @@ class ClientApiService extends Service implements ClientApi {
     })
     const connection = this.ownerCtx.get('connection') as ConnectionHandle | undefined
     if (connection === undefined) throw new Error(`client api: ${endpoint} has no active Connection`)
-    const result = await connection.rpc.call('/api', endpoint, { args }, token.abort.signal)
+    const callerSignal = hasCallerSignal ? values[expected] as AbortSignal | undefined : undefined
+    const signal = callerSignal === undefined
+      ? token.abort.signal
+      : AbortSignal.any([token.abort.signal, callerSignal])
+    const result = await connection.rpc.call('/api', endpoint, { args }, signal)
     if (!mountActive(token)) throw new Error(`client api: Remote method ${endpoint} was withdrawn during invocation`)
     if (!result.ok) throw remoteFailure(endpoint, result.error)
     return parse(descriptor.result, result.value, endpoint, 'result')
diff --git a/packages/host/api-gateway/src/index.ts b/packages/host/api-gateway/src/index.ts
index 64d5715719..c4a61cef8d 100644
--- a/packages/host/api-gateway/src/index.ts
+++ b/packages/host/api-gateway/src/index.ts
@@ -36,6 +36,7 @@ interface ResolvedBinding {
 }
 
 type ConnectionRpcResult = Awaited<ReturnType<ConnectionRpcHandler>>
+const NEVER_ABORTED_SIGNAL = new AbortController().signal
 
 /** Dispatch failure produced outside the invoked business method. */
 export class TypertGatewayError extends Error {
@@ -129,6 +130,7 @@ export class TypertGatewayService extends Service implements TypertGateway {
     }
     validateBinding(receiver, descriptor.service, descriptor.namespace, endpoint)
     const args = descriptor.parameters.map(parameter => this.resolveParameter(parameter, request.args, endpoint))
+    if (descriptor.cancellation !== undefined) args.push(request.signal ?? NEVER_ABORTED_SIGNAL)
     const implementation = descriptor.implementation ?? descriptor.method
     const method = Reflect.get(receiver, implementation) as unknown
     if (typeof method !== 'function') {
@@ -146,13 +148,12 @@ export class TypertGatewayService extends Service implements TypertGateway {
   private async dispatchRpc(
     endpoint: string,
     payload: unknown,
-    _signal: AbortSignal,
+    signal: AbortSignal,
   ): Promise<ConnectionRpcResult> {
-    // Remote methods have no cancellation parameter yet, so disconnects do not cancel business work.
-    return this.invokeRpc(endpoint, payload)
+    return this.invokeRpc(endpoint, payload, signal)
   }
 
-  private async invokeRpc(endpoint: string, payload: unknown): Promise<ConnectionRpcResult> {
+  private async invokeRpc(endpoint: string, payload: unknown, signal: AbortSignal): Promise<ConnectionRpcResult> {
     try {
       const segments = endpoint.split('/')
       if (segments.length !== 2 || segments[0] === '' || segments[1] === '') {
@@ -171,6 +172,7 @@ export class TypertGatewayService extends Service implements TypertGateway {
         namespace,
         method,
         args: payload.args,
+        signal,
       })
       return { ok: true, value }
     } catch (error) {
@@ -226,9 +228,22 @@ export class TypertGatewayService extends Service implements TypertGateway {
     endpoint: string,
   ): InvocationDescriptor {
     const names = methodParameterNames(binding.service, marker.method, endpoint)
+    const signalIndex = names.indexOf('signal')
+    if (signalIndex >= 0 && signalIndex !== names.length - 1) {
+      throw new TypertGatewayError(
+        'signature-invalid',
+        endpoint,
+        'SRC cancellation parameter signal must be the final parameter',
+        { field: 'signal' },
+      )
+    }
+    const cancellation = signalIndex >= 0
+      ? { parameter: 'signal' as const }
+      : undefined
+    const businessNames = cancellation === undefined ? names : names.slice(0, -1)
     const parameters: InvocationParameterDescriptor[] = []
     const wires = new Set<string>()
-    for (const name of names) {
+    for (const name of businessNames) {
       const matches = this.ctx.typert.lookups.definitions()
         .filter(definition => definition.parameter === name)
       if (matches.length > 1) {
@@ -295,6 +310,7 @@ export class TypertGatewayService extends Service implements TypertGateway {
       ...(marker.method === method ? {} : { implementation: marker.method }),
       invocation: receiver,
       parameters,
+      ...(cancellation === undefined ? {} : { cancellation }),
       result: { mode: 'src-json' },
     }
   }
diff --git a/packages/host/api-gateway/src/types.ts b/packages/host/api-gateway/src/types.ts
index eea2bdc4f1..b7f36eb340 100644
--- a/packages/host/api-gateway/src/types.ts
+++ b/packages/host/api-gateway/src/types.ts
@@ -11,6 +11,8 @@ export interface InvokeRemoteRequest {
   readonly method: string
   /** Named wire values; fields must exactly match the descriptor. */
   readonly args: Readonly<Record<string, unknown>>
+  /** Carrier or direct-caller cancellation injected only into cancellation-aware methods. */
+  readonly signal?: AbortSignal
 }
 
 /** Stable infrastructure and boundary failures emitted before or after business execution. */
diff --git a/packages/host/api-gateway/tests/client.spec.ts b/packages/host/api-gateway/tests/client.spec.ts
index 2e00d29c0d..3ad00ff0fc 100644
--- a/packages/host/api-gateway/tests/client.spec.ts
+++ b/packages/host/api-gateway/tests/client.spec.ts
@@ -17,11 +17,18 @@ declare module '@deepseek-ai/dsh-type-meta' {
   }
 
   interface TypeRTRemoteMap {
-    'goals/create': (agentId: string, request: { readonly objective: string }) => Promise<{ readonly ref: string }>
+    'goals/create': (
+      agentId: string,
+      request: { readonly objective: string },
+      signal?: AbortSignal,
+    ) => Promise<{ readonly ref: string }>
   }
 
   interface TypeRTRemoteContextMap {
-    'fixture:goals/create': (request: { readonly objective: string }) => Promise<{ readonly ref: string }>
+    'fixture:goals/create': (
+      request: { readonly objective: string },
+      signal?: AbortSignal,
+    ) => Promise<{ readonly ref: string }>
     'fixture:goals/rename': (request: { readonly objective: string }) => Promise<{ readonly renamed: boolean }>
   }
 
@@ -58,6 +65,7 @@ function directDescriptor(): InvocationDescriptor {
       source: 'json',
       codec: { mode: 'strict', typeSymbol: '@fixture#CreateRequest', schema: requestSchema },
     }],
+    cancellation: { parameter: 'signal' },
     result: { mode: 'strict', typeSymbol: '@fixture#CreateResult', schema: createResultSchema },
   }
 }
@@ -114,6 +122,19 @@ describe('Client TypeRT API', () => {
       { args: { agentId: 'agent-1', request: { objective: 'ship' } } },
       expect.any(AbortSignal),
     )
+    const callerAbort = new AbortController()
+    await expect(ctx.api.goals.create(
+      'agent-1',
+      { objective: 'cancel me' },
+      callerAbort.signal,
+    )).resolves.toEqual({ ref: 'goal-1' })
+    const combinedSignal = call.mock.calls.at(-1)?.[3]
+    expect(combinedSignal).toBeInstanceOf(AbortSignal)
+    expect(combinedSignal).not.toBe(callerAbort.signal)
+    const cancellation = new Error('caller cancelled')
+    callerAbort.abort(cancellation)
+    expect(combinedSignal?.aborted).toBe(true)
+    expect(combinedSignal?.reason).toBe(cancellation)
     await expect(ctx.api.goals.create('', { objective: 'ship' })).rejects.toThrow('rejected "agentId"')
 
     call.mockResolvedValueOnce({ ok: true, value: { ref: 1 } })
@@ -299,10 +320,18 @@ describe('Client TypeRT API', () => {
       .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })
     const ctx = await bench(call)
     const descriptor = directDescriptor()
-    const dispose = ctx.api.mount({ package: '@fixture/goals', descriptors: [descriptor] })
+    const dispose = ctx.api.mount({
+      package: '@fixture/goals',
+      descriptors: [descriptor, contextDescriptor()],
+    })
     const create = ctx.api.goals.create as unknown as (...args: unknown[]) => Promise<unknown>
+    const goals = (ctx as FixtureContext).goals
+    const rename = goals.rename as unknown as (...args: unknown[]) => Promise<unknown>
 
-    await expect(create('agent-1')).rejects.toThrow('expected 2 argument(s), got 1')
+    await expect(create('agent-1')).rejects.toThrow('expected 2 business argument(s) plus an optional AbortSignal, got 1')
+    await expect(create('agent-1', { objective: 'ship' }, undefined, 'extra'))
+      .rejects.toThrow('got 4')
+    await expect(rename.call(goals)).rejects.toThrow('expected 1 argument(s), got 0')
     await expect((ctx as FixtureContext).goals.create({ objective: 'ship' }))
       .rejects.toThrow('no Client Context binder')
 
diff --git a/packages/host/api-gateway/tests/gateway.spec.ts b/packages/host/api-gateway/tests/gateway.spec.ts
index 4aeadeedb8..c05bfefb93 100644
--- a/packages/host/api-gateway/tests/gateway.spec.ts
+++ b/packages/host/api-gateway/tests/gateway.spec.ts
@@ -45,6 +45,7 @@ const emptyModel: TypertContribution['model'] = {
 class GoalService extends Service {
   readonly typertGateway = bindTypeRTGateway(this, 'goals')
   readonly calls: string[] = []
+  lastSignal: AbortSignal | undefined
   nextResult: unknown = undefined
   businessError: Error | undefined
 
@@ -53,8 +54,9 @@ class GoalService extends Service {
   }
 
   @Remote
-  create(agent: FixtureAgent, request: { readonly title: string }): unknown {
+  create(agent: FixtureAgent, request: { readonly title: string }, signal: AbortSignal): unknown {
     this.calls.push('create')
+    this.lastSignal = signal
     return {
       agentId: agent.id,
       title: request.title,
@@ -224,6 +226,19 @@ class RestParameterService extends Service {
   }
 }
 
+class NonFinalSignalService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'nonFinalSignal', { namespace: 'invalid-signal' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'nonFinalSignal')
+  }
+
+  @Remote
+  run(signal: AbortSignal, value: string): string {
+    return signal.aborted ? '' : value
+  }
+}
+
 class WrongBindingService extends Service {
   readonly typertGateway = bindTypeRTGateway(this, 'notWrongBinding', { namespace: 'wrong-binding' })
 
@@ -334,13 +349,24 @@ describe('TypertGatewayService', () => {
     registerAgentLookup(ctx, agent)
     registerStrict(ctx, [createDescriptor()])
     const caller = ctx.extend({ fixtureScope: 'direct-caller' })
+    const abort = new AbortController()
 
     await expect(caller.typertGateway.invoke({
       namespace: 'goals',
       method: 'create',
       args: { agentId: 'agent-1', request: { title: '  ship  ' } },
+      signal: abort.signal,
     })).resolves.toEqual({ agentId: 'agent-1', title: 'ship', scope: 'direct-caller' })
     expect(service.calls).toEqual(['create'])
+    expect(service.lastSignal).toBe(abort.signal)
+
+    await expect(caller.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'again' } },
+    })).resolves.toEqual({ agentId: 'agent-1', title: 'again', scope: 'direct-caller' })
+    expect(service.lastSignal).toBeInstanceOf(AbortSignal)
+    expect(service.lastSignal?.aborted).toBe(false)
   })
 
   it('resolves strict Remote Context identity without adding a business argument', async () => {
@@ -358,16 +384,19 @@ describe('TypertGatewayService', () => {
   })
 
   it('derives SRC direct lookup and JSON parameters from marker and parameter names', async () => {
-    const { ctx } = await setup()
+    const { ctx, service } = await setup()
     const agent = { id: 'agent-1' }
     registerAgentLookup(ctx, agent)
     const caller = ctx.extend({ fixtureScope: 'direct-src' })
+    const abort = new AbortController()
 
     await expect(caller.typertGateway.invoke({
       namespace: 'goals',
       method: 'create',
       args: { agentId: 'agent-1', request: { title: 'ship' } },
+      signal: abort.signal,
     })).resolves.toEqual({ agentId: 'agent-1', title: 'ship', scope: 'direct-src' })
+    expect(service.lastSignal).toBe(abort.signal)
   })
 
   it('does not downgrade an observed SRC lookup after its provider unloads', async () => {
@@ -605,6 +634,7 @@ describe('TypertGatewayService', () => {
       { plugin: DefaultParameterService, namespace: 'invalid-default', args: { value: 'x' } },
       { plugin: DestructuredParameterService, namespace: 'invalid-destructure', args: { value: { value: 'x' } } },
       { plugin: RestParameterService, namespace: 'invalid-rest', args: { values: ['x'] } },
+      { plugin: NonFinalSignalService, namespace: 'invalid-signal', args: { value: 'x' } },
     ] as const
     for (const testCase of cases) {
       const ctx = await setupGateway()
@@ -874,7 +904,8 @@ describe('TypertGatewayService', () => {
     expect(connection.matches?.('goals')).toBe(false)
     expect(connection.matches?.('goals/missing')).toBe(false)
     expect(connection.matches?.('legacy/list')).toBe(false)
-    const signal = new AbortController().signal
+    const abort = new AbortController()
+    const signal = abort.signal
     const handler = connection.handler
     if (handler === undefined) throw new Error('fixture Connection did not retain the /api interceptor')
     await expect(handler('goals/create', {
@@ -883,6 +914,10 @@ describe('TypertGatewayService', () => {
       ok: true,
       value: { agentId: 'agent-1', title: 'ship', scope: 'rpc-caller' },
     })
+    const service = rawGoalService(ctx)
+    expect(service.lastSignal).toBe(signal)
+    abort.abort(new Error('client disconnected'))
+    expect(service.lastSignal?.aborted).toBe(true)
     const invalid = await handler('goals/create', { invalid: true }, signal)
     expect(invalid).toMatchObject({
       ok: false,
@@ -904,7 +939,6 @@ describe('TypertGatewayService', () => {
       expect(result.error.message).toContain('plain-object args field')
     }
 
-    const service = rawGoalService(ctx)
     service.businessError = 'non-error failure' as unknown as Error
     await expect(handler('goals/fail', { args: { request: null } }, signal)).resolves.toEqual({
       ok: false,
@@ -1099,6 +1133,7 @@ function createDescriptor(): InvocationDescriptor {
         })),
       },
     ],
+    cancellation: { parameter: 'signal' },
     result: strictCodec('@fixture/gateway#CreateResult', z.object({
       agentId: z.string(),
       title: z.string(),
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index f430d757fb..87a23f17f5 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -963,8 +963,9 @@ class FaceAnalyzer {
     const lookups = this.lookupDeclarations()
     const lookupByHost = new Map(lookups.map(lookup => [lookup.hostSymbol, lookup]))
     const parameters: InvocationParameterModel[] = []
+    let cancellation: InvocationModel['cancellation']
     const wires = new Set<string>()
-    for (const parameter of method.parameters) {
+    for (const [parameterIndex, parameter] of method.parameters.entries()) {
       if (!ts.isIdentifier(parameter.name)) {
         this.fail(parameter, 'Remote parameters must use identifier bindings')
       }
@@ -973,6 +974,18 @@ class FaceAnalyzer {
       if (parameter.questionToken !== undefined) this.fail(parameter, 'Remote parameters cannot be optional')
       if (parameter.name.text === 'this') this.fail(parameter, 'Remote methods cannot declare an explicit this parameter')
       const authoredType = this.requiredType(parameter, parameter.type, 'parameter')
+      const cancellationName = parameter.name.text === 'signal'
+      const cancellationType = this.isGlobalAbortSignal(authoredType)
+      if (cancellationName || cancellationType) {
+        if (!cancellationName || !cancellationType) {
+          this.fail(parameter, 'Remote cancellation must use a parameter named signal with the global AbortSignal type')
+        }
+        if (parameterIndex !== method.parameters.length - 1) {
+          this.fail(parameter, 'Remote cancellation signal must be the final parameter')
+        }
+        cancellation = { parameter: 'signal' }
+        continue
+      }
       const hostSymbol = this.symbolAtType(authoredType)
       const lookup = hostSymbol === undefined ? undefined : lookupByHost.get(this.symbolId(hostSymbol))
       let modeled: InvocationParameterModel
@@ -1065,6 +1078,7 @@ class FaceAnalyzer {
       invocation: receiver,
       ...(scope === undefined ? {} : { scope }),
       parameters,
+      ...(cancellation === undefined ? {} : { cancellation }),
       result: this.remoteBoundary(
         resultType,
         `${registration.name}#${binding.namespace}/${exportedMethod}:result`,
@@ -1181,6 +1195,13 @@ class FaceAnalyzer {
     return resultType
   }
 
+  private isGlobalAbortSignal(type: ts.TypeNode): boolean {
+    const symbol = this.symbolAtType(type)
+    if (symbol?.name !== 'AbortSignal') return false
+    return symbol.declarations?.some(declaration =>
+      isStandardLibraryFile(declaration.getSourceFile().fileName)) === true
+  }
+
   private lookupDeclarations(): readonly StaticLookupDeclaration[] {
     if (this.staticLookups !== undefined) return this.staticLookups
     const byKey = new Map<string, StaticLookupDeclaration>()
diff --git a/packages/typert/generator/src/emitter.ts b/packages/typert/generator/src/emitter.ts
index 63b1ee7ace..c8b9ab4195 100644
--- a/packages/typert/generator/src/emitter.ts
+++ b/packages/typert/generator/src/emitter.ts
@@ -315,6 +315,9 @@ export class FaceModelEmitter {
       lines.push('    },')
     })
     lines.push('  ],')
+    if (invocation.cancellation !== undefined) {
+      lines.push("  cancellation: { parameter: 'signal' },")
+    }
     lines.push(`  result: ${indent(strictCodec(
       invocation.result,
       schemas.boundary(resultBoundaryKey(invocation)),
@@ -459,6 +462,7 @@ export class FaceModelEmitter {
     const parameters = invocation.parameters.filter(parameter =>
       !scoped || invocation.invocation.kind === 'context' || parameter.wire !== invocation.scope?.wire).map(parameter =>
       `${safeIdentifier(parameter.wire)}: ${this.renderer.renderType(parameter.boundary.type, referenceNames)}`)
+    if (invocation.cancellation !== undefined) parameters.push('signal?: AbortSignal')
     const result = this.renderer.renderType(invocation.result.type, referenceNames)
     return `(${parameters.join(', ')}) => Promise<${result}>`
   }
diff --git a/packages/typert/generator/src/model.ts b/packages/typert/generator/src/model.ts
index 7f15c8407c..81bc6a91a1 100644
--- a/packages/typert/generator/src/model.ts
+++ b/packages/typert/generator/src/model.ts
@@ -140,6 +140,9 @@ export interface InvocationModel {
     readonly wire: string
   }
   readonly parameters: readonly InvocationParameterModel[]
+  readonly cancellation?: {
+    readonly parameter: 'signal'
+  }
   readonly result: RemoteBoundaryModel
   readonly location: SourceLocation
 }
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
index 816a13a5a7..115b3b87a6 100644
--- a/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
@@ -12,7 +12,8 @@ export class GoalService {
   readonly typertGateway = bindTypeRTGateway(this, 'goals')
 
   @Remote
-  async create(agent: Agent, request: CreateGoalRequest): Promise<CreateGoalResult> {
+  async create(agent: Agent, request: CreateGoalRequest, signal: AbortSignal): Promise<CreateGoalResult> {
+    signal.throwIfAborted()
     return { ref: `${agent.id}:${request.title}` }
   }
 
diff --git a/packages/typert/generator/tests/remote-model.spec.ts b/packages/typert/generator/tests/remote-model.spec.ts
index cb6e6e6060..d5838f39ce 100644
--- a/packages/typert/generator/tests/remote-model.spec.ts
+++ b/packages/typert/generator/tests/remote-model.spec.ts
@@ -16,6 +16,7 @@ interface RuntimeSchema {
 
 interface RuntimeDescriptor {
   readonly id: string
+  readonly cancellation?: { readonly parameter: 'signal' }
   readonly parameters: readonly {
     readonly wire: string
     readonly codec: { readonly schema: RuntimeSchema }
@@ -83,6 +84,7 @@ describe('Remote model generation', { timeout: 60_000 }, () => {
           boundary: { typeSymbol: '@fixture/remote/types#CreateGoalRequest' },
         },
       ],
+      cancellation: { parameter: 'signal' },
       result: { typeSymbol: '@fixture/remote/types#CreateGoalResult' },
     })
     expect(model.invocations[1]).toMatchObject({
@@ -107,12 +109,12 @@ describe('Remote model generation', { timeout: 60_000 }, () => {
 
     expect(artifact?.js).toContain('invocations: [')
     expect(artifact?.remote?.dts).toContain(
-      "'goals/create': (agentId: AgentId, request: CreateGoalRequest) => Promise<CreateGoalResult>",
+      "'goals/create': (agentId: AgentId, request: CreateGoalRequest, signal?: AbortSignal) => Promise<CreateGoalResult>",
     )
     expect(artifact?.remote?.dts).toContain('interface TypeRTRemoteNamespace$676f616c73 {\n    create:')
     expect(artifact?.remote?.dts).toContain("'goals': TypeRTRemoteNamespace$676f616c73")
     expect(artifact?.remote?.dts).toContain(
-      "'agent:goals/create': (request: CreateGoalRequest) => Promise<CreateGoalResult>",
+      "'agent:goals/create': (request: CreateGoalRequest, signal?: AbortSignal) => Promise<CreateGoalResult>",
     )
     expect(artifact?.remote?.dts).toContain(
       "'agent:goals/rename': (request: RenameGoalRequest) => Promise<RenameGoalResult>",
@@ -124,6 +126,7 @@ describe('Remote model generation', { timeout: 60_000 }, () => {
     const generated = await import(`data:text/javascript,${encodeURIComponent(executable)}`) as RuntimeRemoteModule
     expect(generated.TYPERT_REMOTE.package).toBe('@fixture/remote')
     const create = generated.TYPERT_REMOTE.descriptors[0]
+    expect(create?.cancellation).toEqual({ parameter: 'signal' })
     expect(create?.parameters[1]?.codec.schema.safeParse({ title: 'ship' }).success).toBe(true)
     expect(create?.parameters[1]?.codec.schema.safeParse({ title: 1 }).success).toBe(false)
     expect(create?.result.schema.safeParse({ ref: 'goal-1' }).success).toBe(true)
@@ -234,8 +237,8 @@ export type GenericResult = {
       edit: (source: string) => source
         .replace('export class GoalService', 'export abstract class GoalService')
         .replace(
-          '  async create(agent: Agent, request: CreateGoalRequest): Promise<CreateGoalResult> {\n    return { ref: `${agent.id}:${request.title}` }\n  }',
-          '  abstract create(agent: Agent, request: CreateGoalRequest): Promise<CreateGoalResult>',
+          '  async create(agent: Agent, request: CreateGoalRequest, signal: AbortSignal): Promise<CreateGoalResult> {\n    signal.throwIfAborted()\n    return { ref: `${agent.id}:${request.title}` }\n  }',
+          '  abstract create(agent: Agent, request: CreateGoalRequest, signal: AbortSignal): Promise<CreateGoalResult>',
         ),
       message: 'Remote methods must have a concrete implementation',
     },
@@ -267,6 +270,24 @@ export type GenericResult = {
       edit: (source: string) => source.replace('request: CreateGoalRequest', 'request?: CreateGoalRequest'),
       message: 'Remote parameters cannot be optional',
     },
+    {
+      name: 'wrong cancellation type',
+      edit: (source: string) => source.replace('signal: AbortSignal', 'signal: string'),
+      message: 'cancellation must use a parameter named signal with the global AbortSignal type',
+    },
+    {
+      name: 'wrong cancellation name',
+      edit: (source: string) => source.replace('signal: AbortSignal', 'abort: AbortSignal'),
+      message: 'cancellation must use a parameter named signal with the global AbortSignal type',
+    },
+    {
+      name: 'non-final cancellation',
+      edit: (source: string) => source.replace(
+        'agent: Agent, request: CreateGoalRequest, signal: AbortSignal',
+        'agent: Agent, signal: AbortSignal, request: CreateGoalRequest',
+      ),
+      message: 'cancellation signal must be the final parameter',
+    },
   ])('rejects $name', ({ edit, message }) => {
     const root = copyFixture()
     editFile(root, 'packages/remote/src/index.ts', edit)
@@ -399,12 +420,14 @@ declare const create: TypeRTRemoteMap['goals/create']
 declare const createScoped: TypeRTRemoteContextMap['agent:goals/create']
 declare const rename: TypeRTRemoteContextMap['agent:goals/rename']
 const created: Promise<CreateGoalResult> = create('agent-1', { title: 'ship' })
+const cancellable: Promise<CreateGoalResult> = create('agent-1', { title: 'ship' }, new AbortController().signal)
 const createdScoped: Promise<CreateGoalResult> = createScoped({ title: 'ship' })
 const renamed: Promise<RenameGoalResult> = rename({ ref: 'goal-1', title: 'land' })
 declare const ctx: { api: TypeRTRemoteNamespaceMap }
 const navigated: Promise<CreateGoalResult> = ctx.api.goals.create('agent-1', { title: 'navigate' })
 void contribution
 void created
+void cancellable
 void createdScoped
 void renamed
 void navigated
diff --git a/packages/typert/loader/src/index.ts b/packages/typert/loader/src/index.ts
index efe0fa6f94..575d066e0d 100644
--- a/packages/typert/loader/src/index.ts
+++ b/packages/typert/loader/src/index.ts
@@ -226,6 +226,12 @@ function requireInvocation(pkgName: string, value: unknown): void {
     parameters.set(wire, parameter)
     requireStrictCodec(pkgName, parameter.codec, `invocation "${id}" parameter codec`)
   }
+  if (invocation.cancellation !== undefined) {
+    const cancellation = requireObject(pkgName, invocation.cancellation, `invocation "${id}" cancellation`)
+    if (cancellation.parameter !== 'signal') {
+      throw new Error(`typert-loader: ${pkgName} invocation "${id}" cancellation parameter must be "signal"`)
+    }
+  }
   if (invocation.scope !== undefined) {
     if (receiver.kind !== 'direct') {
       throw new Error(`typert-loader: ${pkgName} invocation "${id}" Context receiver cannot declare a direct scope projection`)
diff --git a/packages/typert/loader/tests/loader.spec.ts b/packages/typert/loader/tests/loader.spec.ts
index ec407f82d9..750cc92e57 100644
--- a/packages/typert/loader/tests/loader.spec.ts
+++ b/packages/typert/loader/tests/loader.spec.ts
@@ -83,6 +83,7 @@ function invocationTypertSource(pkgName: string): string {
     '      name: \'request\', wire: \'request\', source: \'json\',',
     `      codec: { mode: 'strict', typeSymbol: '${pkgName}/types#Request', schema: Text },`,
     '    }],',
+    "    cancellation: { parameter: 'signal' },",
     `    result: { mode: 'strict', typeSymbol: '${pkgName}/types#Result', schema: Text },`,
     '    sourceLocation: { file: \'src/index.ts\', line: 8, column: 3 },',
     '  }],',
@@ -157,6 +158,7 @@ describe('typert loader', () => {
       id: '@fixture/invocation#goals/create',
       invocation: { kind: 'direct' },
       parameters: [{ wire: 'request', source: 'json' }],
+      cancellation: { parameter: 'signal' },
       sourceLocation: { file: 'src/index.ts', line: 8, column: 3 },
     })
     expect(descriptor?.parameters[0]?.codec.mode).toBe('strict')
@@ -502,6 +504,9 @@ describe('validateTypertManifest', () => {
     const descriptor = strictInvocation()
     const manifest = { ...base, invocations: [descriptor] }
     expect(validateTypertManifest('pkg', manifest)).toBe(manifest)
+    const cancellable = { ...descriptor, cancellation: { parameter: 'signal' } }
+    expect(validateTypertManifest('pkg', { ...base, invocations: [cancellable] }).invocations)
+      .toEqual([cancellable])
     const scoped = {
       ...descriptor,
       scope: { context: 'agent', wire: 'agentId' },
@@ -526,6 +531,14 @@ describe('validateTypertManifest', () => {
       ...base,
       invocations: [{ ...descriptor, result: { mode: 'src-json' } }],
     })).toThrow('result codec must use a strict codec')
+    expect(() => validateTypertManifest('pkg', {
+      ...base,
+      invocations: [{ ...descriptor, cancellation: null }],
+    })).toThrow('cancellation must be an object')
+    expect(() => validateTypertManifest('pkg', {
+      ...base,
+      invocations: [{ ...descriptor, cancellation: { parameter: 'abort' } }],
+    })).toThrow('cancellation parameter must be "signal"')
     expect(() => validateTypertManifest('pkg', {
       ...base,
       invocations: [{ ...descriptor, result: { mode: 'strict', typeSymbol: 'pkg#Result', schema: zodish } }],
diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
index 6749cdbeb9..229dc7affc 100644
--- a/packages/typert/registry/src/service.ts
+++ b/packages/typert/registry/src/service.ts
@@ -562,6 +562,9 @@ function validateInvocation(descriptor: InvocationDescriptor): void {
     }
     validateCodec(parameter.codec, `${descriptor.id} parameter ${parameter.name}`)
   }
+  if (descriptor.cancellation !== undefined && descriptor.cancellation.parameter !== 'signal') {
+    throw new Error(`typert: invocation "${descriptor.id}" cancellation parameter must be "signal"`)
+  }
   if (descriptor.scope !== undefined) {
     if (descriptor.invocation.kind !== 'direct') {
       throw new Error(`typert: invocation "${descriptor.id}" Context receiver cannot declare a direct scope projection`)
diff --git a/packages/typert/registry/tests/typert.spec.ts b/packages/typert/registry/tests/typert.spec.ts
index 51e7594749..5603ce8954 100644
--- a/packages/typert/registry/tests/typert.spec.ts
+++ b/packages/typert/registry/tests/typert.spec.ts
@@ -411,6 +411,7 @@ describe('TypertRegistry', () => {
       ...invocation('@fixture/remote#strict'),
       implementation: 'remoteExportCreate',
       parameters: [{ name: 'request', wire: 'request', source: 'json', codec: strict }],
+      cancellation: { parameter: 'signal' },
       result: strict,
     }
     const dispose = ctx.typert.remotes.register({ package: '@fixture/strict', descriptors: [strictInvocation] })
@@ -420,6 +421,10 @@ describe('TypertRegistry', () => {
       [{ ...invocation(), id: '' }, 'invocation id'],
       [{ ...invocation(), namespace: 'bad/name' }, 'namespace'],
       [{ ...invocation(), implementation: 'bad/name' }, 'implementation method'],
+      [{
+        ...invocation(),
+        cancellation: { parameter: 'abort' } as unknown as { readonly parameter: 'signal' },
+      }, 'cancellation parameter'],
       [{
         ...invocation(),
         parameters: [
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
index 90d93152b7..9751c4c088 100644
--- a/packages/typert/type-meta/README.i18n.yaml
+++ b/packages/typert/type-meta/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/typert/type-meta/README.md
-README.md: 9dd8dadd07b219c7471c8851262958d4d9e96a43
-README.zh.md: 5716f56d988c6d2dd9cd237346c3b02ec9ae7c4e
+README.md: 95716446c01c7fd510cdf55a82509b5b8af6f3ae
+README.zh.md: 0d30b3122265d9bb3caa289345f843fe67377be3
diff --git a/packages/typert/type-meta/README.md b/packages/typert/type-meta/README.md
index 9dd8dadd07..95716446c0 100644
--- a/packages/typert/type-meta/README.md
+++ b/packages/typert/type-meta/README.md
@@ -11,6 +11,8 @@ Compiler-independent declarations shared by business packages, generated TypeRT
 - `bindTypeRTGateway(this, serviceKey, options?)` creates the visible, frozen binding between a Service instance, its exact Cordis key, and its wire namespace.
 - `remoteMethods(service)` returns a detached declaration-order snapshot used by the Gateway's SRC fallback.
 
+A Host method opts into cooperative cancellation by declaring `signal: AbortSignal` as its final parameter. `InvocationDescriptor.cancellation` records that reserved injection point; the signal never becomes a JSON parameter or lookup field. SRC recognizes the final parameter name, while strict generation also verifies the global `AbortSignal` type.
+
 Decorator initializers retain markers in a module-private `WeakMap` keyed by the Service prototype. They do not add constructor symbols, prototype properties, parameter metadata, or runtime reflection fields. The Service opts in explicitly through its `typertGateway` binding field.
 
 ## TypeRT protocol
diff --git a/packages/typert/type-meta/README.zh.md b/packages/typert/type-meta/README.zh.md
index 5716f56d98..0d30b31222 100644
--- a/packages/typert/type-meta/README.zh.md
+++ b/packages/typert/type-meta/README.zh.md
@@ -11,6 +11,8 @@
 - `bindTypeRTGateway(this, serviceKey, options?)` 在服务实例、其准确的 Cordis key 与协议命名空间之间创建可见且冻结的绑定。
 - `remoteMethods(service)` 返回按声明顺序排列、与内部状态分离的快照，供 Gateway 的 SRC 回退路径使用。
 
+Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用协作式取消。`InvocationDescriptor.cancellation` 记录这个保留的注入点；signal 绝不会成为 JSON 参数或 lookup 字段。SRC 识别末位参数名，严格生成还会校验它是否具有全局 `AbortSignal` 类型。
+
 装饰器初始化器将标记保存在以服务 prototype 为键的模块私有 `WeakMap` 中。它们不会在构造函数上添加 symbol，也不会添加 prototype 属性、参数元数据或运行时反射字段。服务通过自身的 `typertGateway` 绑定字段显式接入。
 
 ## TypeRT 协议
diff --git a/packages/typert/type-meta/src/types.ts b/packages/typert/type-meta/src/types.ts
index f9ed7ffa97..6de5c7f823 100644
--- a/packages/typert/type-meta/src/types.ts
+++ b/packages/typert/type-meta/src/types.ts
@@ -157,6 +157,11 @@ export interface InvocationDescriptor {
   }
   /** Ordered business parameters. */
   readonly parameters: readonly InvocationParameterDescriptor[]
+  /** Transport cancellation injected after business parameters instead of entering wire args. */
+  readonly cancellation?: {
+    /** Reserved final Host method parameter. */
+    readonly parameter: 'signal'
+  }
   /** Codec for the resolved method result. */
   readonly result: TypeRTCodec
   /** Source declaration used only for diagnostics. */

From 1ea5507bf893cae71de68da12d534d6d5dca6d03 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 18:43:31 +0800
Subject: [PATCH 127/516] fix(typert): close remote gateway review gaps

---
 ...08-02-typert-remote-method-calls.i18n.yaml |  4 +-
 .../2026-08-02-typert-remote-method-calls.md  |  2 +-
 ...026-08-02-typert-remote-method-calls.zh.md |  2 +-
 packages/goal/goal/tests/goal.spec.ts         | 16 ++++++++
 .../host/api-gateway/tests/gateway.spec.ts    | 12 ++++--
 packages/typert/registry/src/service.ts       |  3 +-
 scripts/run-gates.ts                          |  1 +
 vitest.config.ts                              | 30 +++------------
 vitest.e2e.config.ts                          |  4 +-
 vitest.shared.ts                              | 37 +++++++++++++++++++
 vitest.snapshot.config.ts                     |  4 +-
 11 files changed, 77 insertions(+), 38 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index bd83c38a3e..57e1054dfc 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: 4268539ecf0d40a9e8080e0571992cc2c5d724af
-2026-08-02-typert-remote-method-calls.zh.md: f9f426f2fb80c74cb9ebaef15e801ccfcf67e027
+2026-08-02-typert-remote-method-calls.md: 552e910b403312c7c7a1cec3a14c0dc1f9cc4380
+2026-08-02-typert-remote-method-calls.zh.md: 18b8c1687d2c01aa23bb7cb9402fccf85fec333d
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index 4268539ecf..552e910b40 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -452,7 +452,7 @@ The Gateway registers only its ownership matcher and RPC handler with Connection
 
 The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`. The same direct descriptor with an Agent lookup supports both `ctx.api.goals.create(agentId, request)` and `agentCtx.goals.create(request)`. `@RemoteContext('agent')` remains the distinct scoped-receiver mode.
 
-Connection supplies the shared-channel interceptor and current HTTP carrier mapping. WebSocket migration, the TUI runtime and carrier, TUI Agent Scope wiring, Permission/Approval state machines, Session event streams, call authorization, cancellation, retries, idempotency, and cross-version protocol compatibility remain outside this decision.
+Connection supplies the shared-channel interceptor and current HTTP carrier mapping. WebSocket migration, the TUI runtime and carrier, TUI Agent Scope wiring, Permission/Approval state machines, Session event streams, call authorization, retries, idempotency, and cross-version protocol compatibility remain outside this decision.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index f9f426f2fb..18b8c1687d 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -452,7 +452,7 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 
 已交付的纵向链路是 `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`。同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.api.goals.create(agentId, request)` 与 `agentCtx.goals.create(request)`。`@RemoteContext('agent')` 仍是独立的 scoped receiver 模式。
 
-Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebSocket 迁移、TUI runtime 与 carrier、TUI Agent Scope 接线、Permission/Approval 状态机、Session 事件流、调用授权、取消、重试、幂等及跨版本协议兼容均不属于本决策。
+Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebSocket 迁移、TUI runtime 与 carrier、TUI Agent Scope 接线、Permission/Approval 状态机、Session 事件流、调用授权、重试、幂等及跨版本协议兼容均不属于本决策。
 
 ## Alternatives considered
 
diff --git a/packages/goal/goal/tests/goal.spec.ts b/packages/goal/goal/tests/goal.spec.ts
index 38eea7cf61..2dd5885cc7 100644
--- a/packages/goal/goal/tests/goal.spec.ts
+++ b/packages/goal/goal/tests/goal.spec.ts
@@ -245,6 +245,22 @@ describe('GoalService creation and replay', () => {
 })
 
 describe('GoalService mutations', () => {
+  it('exposes the supported mutation sequence through Remote wrappers', async () => {
+    const { ctx, agent } = await harness()
+    const created = ctx.goals.remoteExportCreate(agent, { objective: 'remote lifecycle' })
+    const edited = ctx.goals.remoteExportEdit(agent, created.ref, { objective: 'edited remotely' })
+    const paused = ctx.goals.remoteExportPause(agent, edited)
+    const resumed = ctx.goals.remoteExportResume(agent, paused)
+    const completed = ctx.goals.remoteExportComplete(agent, resumed)
+    const cleared = ctx.goals.remoteExportClear(agent, completed)
+
+    expect(edited).toMatchObject({ objective: 'edited remotely', revision: 2 })
+    expect(paused).toMatchObject({ phase: 'paused', revision: 3 })
+    expect(resumed).toMatchObject({ phase: 'active', revision: 4 })
+    expect(completed).toMatchObject({ phase: 'complete', revision: 5 })
+    expect(cleared).toEqual({ id: created.ref.id, revision: 6 })
+  })
+
   it('edits with compare-and-set revisions and rejects empty edits', async () => {
     const { ctx, agent } = await harness()
     const created = ctx.goals.create(agent, { objective: 'old', maxGoalRounds: 4 })
diff --git a/packages/host/api-gateway/tests/gateway.spec.ts b/packages/host/api-gateway/tests/gateway.spec.ts
index c05bfefb93..6558a7ca47 100644
--- a/packages/host/api-gateway/tests/gateway.spec.ts
+++ b/packages/host/api-gateway/tests/gateway.spec.ts
@@ -998,14 +998,16 @@ describe('TypertGatewayService', () => {
         }),
       })
       expect(invalid.status).toBe(200)
-      await expect(invalid.json()).resolves.toMatchObject({
+      const invalidBody = await invalid.json() as unknown
+      expect(invalidBody).toMatchObject({
         type: 'server-response',
         rpcId: 'rpc-invalid',
         result: {
           ok: false,
-          error: { code: 'internal', message: expect.stringContaining('plain-object args field') },
+          error: { code: 'internal' },
         },
       })
+      expect(JSON.stringify(invalidBody)).toContain('plain-object args field')
 
       await removeStrict()
       strictActive = false
@@ -1020,14 +1022,16 @@ describe('TypertGatewayService', () => {
         }),
       })
       expect(withdrawn.status).toBe(200)
-      await expect(withdrawn.json()).resolves.toMatchObject({
+      const withdrawnBody = await withdrawn.json() as unknown
+      expect(withdrawnBody).toMatchObject({
         type: 'server-response',
         rpcId: 'rpc-withdrawn',
         result: {
           ok: false,
-          error: { code: 'internal', message: expect.stringContaining('strict definition was withdrawn') },
+          error: { code: 'internal' },
         },
       })
+      expect(JSON.stringify(withdrawnBody)).toContain('strict definition was withdrawn')
 
       const unclaimed = await fetch(`${server.origin}/api/legacy/list`, { method: 'POST' })
       expect(unclaimed.status).toBe(404)
diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
index 229dc7affc..d04f38cde5 100644
--- a/packages/typert/registry/src/service.ts
+++ b/packages/typert/registry/src/service.ts
@@ -562,7 +562,8 @@ function validateInvocation(descriptor: InvocationDescriptor): void {
     }
     validateCodec(parameter.codec, `${descriptor.id} parameter ${parameter.name}`)
   }
-  if (descriptor.cancellation !== undefined && descriptor.cancellation.parameter !== 'signal') {
+  const cancellation = descriptor.cancellation as { readonly parameter: string } | undefined
+  if (cancellation !== undefined && cancellation.parameter !== 'signal') {
     throw new Error(`typert: invocation "${descriptor.id}" cancellation parameter must be "signal"`)
   }
   if (descriptor.scope !== undefined) {
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index f7669eac7e..6d6a76e476 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -601,6 +601,7 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts',
     'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
     'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
+    'packages/client/remotes/tests/built-lib.e2e.ts',
     // The worker-entry packages' built bundles: the only automated proof
     // that lib/index.js resolves its sibling lib/worker.cjs under plain node
     // (the e2e lane runs unbuilt, so these files self-skip there).
diff --git a/vitest.config.ts b/vitest.config.ts
index 4c4c668b94..56a5a1575b 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -3,8 +3,7 @@ import { fileURLToPath } from 'node:url'
 import tsconfigPaths from 'vite-tsconfig-paths'
 import { resolvePwshPath } from './packages/bash/pwsh-local/src/resolve.ts'
 import { defineConfig } from 'vitest/config'
-import ts from 'typescript'
-import { vitestExecArgv } from './vitest.shared.ts'
+import { standardDecoratorPlugin, vitestExecArgv } from './vitest.shared.ts'
 import { COVERAGE_EXEMPT_ENV, coverageExemptHeavySuites } from './scripts/coverage-exempt.ts'
 
 // Prints exact `path:line:col` records for every uncovered statement, branch
@@ -18,29 +17,6 @@ const uncoveredLocationsReporter = fileURLToPath(new URL('./scripts/coverage-unc
 // map applies to every test file. paths must win over package exports so built
 // lib/ never loads a second module-singleton copy.
 const pathsPlugin = (): ReturnType<typeof tsconfigPaths> => tsconfigPaths({ projects: ['./tsconfig.base.json'] })
-const decoratorSyntax = /^\s*@[A-Za-z_$][\w$]*/m
-
-const standardDecoratorPlugin = () => ({
-  name: 'dsh-standard-decorators',
-  enforce: 'pre' as const,
-  transform(code: string, id: string) {
-    const file = id.split('?', 1)[0]!
-    if (!/\.[cm]?tsx?$/.test(file) || !decoratorSyntax.test(code)) return
-    const result = ts.transpileModule(code, {
-      fileName: file,
-      compilerOptions: {
-        target: ts.ScriptTarget.ES2024,
-        module: ts.ModuleKind.ESNext,
-        jsx: file.endsWith('x') ? ts.JsxEmit.ReactJSX : undefined,
-        sourceMap: true,
-      },
-    })
-    return {
-      code: result.outputText.replace(/\n?\/\/# sourceMappingURL=.*$/u, '\n'),
-      map: result.sourceMapText,
-    }
-  },
-})
 
 const windowsUnsupportedPackages = process.platform === 'win32'
   ? [
@@ -203,6 +179,10 @@ export default defineConfig({
         'packages/client/hmr/src/invariant.ts',
         'packages/client/connection/src/index.ts',
         'packages/client/connection/src/http-bridge.ts',
+        // This assembly imports generated Host-for-Client code that exists
+        // only in lib; the post-build built-bin smoke executes both entries.
+        'packages/client/remotes/src/index.ts',
+        'packages/client/remotes/src/client/index.ts',
         // Slash/command/input round: per-file gaps deferred with the same
         // client-lane debt. TODO(gui): cover and remove with the lane above.
         'packages/client/connection/src/client/fixture.ts',
diff --git a/vitest.e2e.config.ts b/vitest.e2e.config.ts
index d8e6aa53a7..f898d2d9da 100644
--- a/vitest.e2e.config.ts
+++ b/vitest.e2e.config.ts
@@ -1,6 +1,6 @@
 import tsconfigPaths from 'vite-tsconfig-paths'
 import { defineConfig } from 'vitest/config'
-import { vitestExecArgv } from './vitest.shared.ts'
+import { standardDecoratorPlugin, vitestExecArgv } from './vitest.shared.ts'
 
 // Real-API suite, separate because it spends tokens. Each test self-skips without
 // its provider credential for keyless CI; credentialed workflows preflight the
@@ -36,7 +36,7 @@ export default defineConfig({
   // Built-artifact e2e suites are unaffected: their built-ness lives in
   // subprocesses and createRequire lookups, which bypass vite resolution
   // entirely.
-  plugins: [tsconfigPaths({ projects: ['./tsconfig.base.json'] })],
+  plugins: [tsconfigPaths({ projects: ['./tsconfig.base.json'] }), standardDecoratorPlugin()],
   test: {
     execArgv: vitestExecArgv,
     setupFiles: ['./scripts/test-invariants.ts'],
diff --git a/vitest.shared.ts b/vitest.shared.ts
index 506fabb380..7c6ca2bee8 100644
--- a/vitest.shared.ts
+++ b/vitest.shared.ts
@@ -1,5 +1,42 @@
+import ts from 'typescript'
+
+const decoratorSyntax = /^\s*@[A-Za-z_$][\w$]*/m
+
 /**
  * Worker arguments that keep process-wide Web Storage from shadowing jsdom storage.
  * Node lists the positive spelling in `allowedNodeEnvironmentFlags` for this negatable flag.
  */
 export const vitestExecArgv = process.allowedNodeEnvironmentFlags.has('--webstorage') ? ['--no-webstorage'] : []
+
+/**
+ * Transform standard TypeScript decorators before Vite's default parser sees source files.
+ * @returns a pre-transform Vite plugin shared by source-mode test configurations.
+ */
+export function standardDecoratorPlugin() {
+  return {
+    name: 'dsh-standard-decorators',
+    enforce: 'pre' as const,
+    transform(code: string, id: string) {
+      const file = id.split('?', 1)[0]!
+      if (!/\.[cm]?tsx?$/.test(file) || !decoratorSyntax.test(code)) return
+      const result = ts.transpileModule(code, {
+        fileName: file,
+        compilerOptions: {
+          target: ts.ScriptTarget.ES2024,
+          module: ts.ModuleKind.ESNext,
+          jsx: file.endsWith('x') ? ts.JsxEmit.ReactJSX : undefined,
+          sourceMap: true,
+        },
+      })
+      return {
+        code: result.outputText
+          .replace(
+            /^(\s*)(__esDecorate\()/gmu,
+            '$1/* v8 ignore next -- compiler-synthetic decorator accessors have no source behavior */ $2',
+          )
+          .replace(/\n?\/\/# sourceMappingURL=.*$/u, '\n'),
+        map: result.sourceMapText,
+      }
+    },
+  }
+}
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index 455ecfb4d4..cfa7d12e17 100644
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -1,7 +1,7 @@
 import { availableParallelism } from 'node:os'
 import tsconfigPaths from 'vite-tsconfig-paths'
 import { defineConfig } from 'vitest/config'
-import { vitestExecArgv } from './vitest.shared.ts'
+import { standardDecoratorPlugin, vitestExecArgv } from './vitest.shared.ts'
 
 const DEFAULT_SNAPSHOT_MAX_CONCURRENCY = 5
 
@@ -40,7 +40,7 @@ export default defineConfig({
   // Same resolution note as vitest.config.ts: bare workspace names resolve
   // through the tsconfig.base.json paths facade; the native option cannot do
   // this (the root tsconfig is a solution file with no paths).
-  plugins: [tsconfigPaths({ projects: ['./tsconfig.base.json'] })],
+  plugins: [tsconfigPaths({ projects: ['./tsconfig.base.json'] }), standardDecoratorPlugin()],
   test: {
     execArgv: vitestExecArgv,
     setupFiles: ['./scripts/test-invariants.ts'],

From e8f2ab89bb98c81374f570386793173f4c718aa2 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 6 Aug 2026 23:04:25 +0800
Subject: [PATCH 128/516] refactor(typert): bind remote services through base
 class

---
 ...08-02-typert-remote-method-calls.i18n.yaml |  4 +-
 .../2026-08-02-typert-remote-method-calls.md  | 24 ++++----
 ...026-08-02-typert-remote-method-calls.zh.md | 24 ++++----
 packages/goal/goal/src/index.ts               |  9 +--
 packages/host/api-gateway/README.i18n.yaml    |  4 +-
 packages/host/api-gateway/README.md           |  2 +-
 packages/host/api-gateway/README.zh.md        |  2 +-
 packages/typert/generator/src/analyzer.ts     | 50 ++++++++++++++--
 .../remote-model/packages/remote/src/index.ts |  8 ++-
 .../fixtures/remote-model/type-meta.d.ts      | 13 ++++
 .../generator/tests/remote-model.spec.ts      | 60 +++++++++++++++++--
 packages/typert/type-meta/README.i18n.yaml    |  4 +-
 packages/typert/type-meta/README.md           |  7 ++-
 packages/typert/type-meta/README.zh.md        |  7 ++-
 packages/typert/type-meta/src/index.ts        | 18 ++++++
 .../type-meta/tests/fixtures/source-launch.ts | 11 ++--
 .../typert/type-meta/tests/type-meta.spec.ts  | 27 +++++++--
 17 files changed, 213 insertions(+), 61 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 57e1054dfc..3808a8d363 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: 552e910b403312c7c7a1cec3a14c0dc1f9cc4380
-2026-08-02-typert-remote-method-calls.zh.md: 18b8c1687d2c01aa23bb7cb9402fccf85fec333d
+2026-08-02-typert-remote-method-calls.md: ade8eb827ae765677be8dcdb0ffec965c67bc4ab
+2026-08-02-typert-remote-method-calls.zh.md: 2de887a2a0e46148fbb2b5ac52cfd7e3b2305b8d
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index 552e910b40..ade8eb827a 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -16,7 +16,7 @@ The Host and Browser Client use separate TypeScript Programs because each side a
 
 ## Decision
 
-A business Service declares callable methods with `@Remote` or `@RemoteContext()` and explicitly joins the Gateway through `bindTypeRTGateway()`. TypeRT generates the Host-local reflection artifact and a platform-independent Remote consumer projection from the Host Program. The Client Program continues to generate its own local reflection artifact independently.
+A business Service extends `GatewayService` and declares callable methods with `@Remote` or `@RemoteContext()`. A Service that already has another base class may instead expose the same binding through `bindTypeRTGateway()`. TypeRT generates the Host-local reflection artifact and a platform-independent Remote consumer projection from the Host Program. The Client Program continues to generate its own local reflection artifact independently.
 
 The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. The `.d.ts` exposes only methods marked with a Remote decorator and refers to the business package's single public type symbols. The `.d.ts.map` navigates consumer API methods back to their Host business method implementations. The `.js` carries endpoint, parameter, Context, and Zod information for the same contract. At the assembly layer, the Browser Client mounts the required Remote JS contributions onto the Client API Service. The projection and API abstraction remain platform-independent so that a future TUI can reuse them.
 
@@ -26,7 +26,7 @@ The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. T
 
 | Component | Cordis service | Responsibility |
 |---|---|---|
-| `@deepseek-ai/dsh-type-meta` | Declares only the minimal `ctx.typert` protocol | Decorators, bindings, descriptors, lookup/Context, and the Remote map; no dependency on the compiler, Zod, Connection, or Browser |
+| `@deepseek-ai/dsh-type-meta` | Declares only the minimal `ctx.typert` protocol | `GatewayService`, decorators, binding fallback, descriptors, lookup/Context, and the Remote map; no dependency on the compiler, Zod, Connection, or Browser |
 | TypeRT registry | `ctx.typert` | Separately stores reflection for the current environment, imported Remote contributions, lookup providers, and Context providers |
 | TypeRT generator/loader | No new business service | Generates three kinds of `lib` artifacts from the Host/Client Programs and registers the current environment's artifacts with `ctx.typert` |
 | Host API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, invokes methods, and encodes results |
@@ -43,8 +43,10 @@ The Host Gateway does not depend on concrete implementations of `ctx.agents`, `c
 Ordinary direct calls use `@Remote`. When migrating to an existing Service or Registry, do not rename or alter existing methods. Add `remoteExport*` entry points at the end of the class and use decorator arguments to declare their short API names. A method explicitly declares every required business object in a top-level parameter position:
 
 ```text
-export class GoalService extends Service {
-  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+export class GoalService extends GatewayService {
+  constructor(ctx: Context) {
+    super(ctx, 'goals')
+  }
 
   create(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
     // Existing business method remains unchanged.
@@ -57,13 +59,15 @@ export class GoalService extends Service {
 }
 ```
 
-`goals` is an explicit Cordis service key and is the default wire namespace. Override it through an option to `bindTypeRTGateway()` only when the protocol namespace genuinely needs to differ from the service key.
+`goals` is the explicit Cordis service key passed to `super()` and is the default wire namespace. Pass a `namespace` option as the third argument only when the protocol namespace genuinely needs to differ from the service key.
 
 Use `@RemoteContext()` when the Service receiver must be resolved within an isolated kind of Context. Context identity does not enter the business method's parameters:
 
 ```text
-export class ScopedGoalService extends Service {
-  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+export class ScopedGoalService extends GatewayService {
+  constructor(ctx: Context) {
+    super(ctx, 'goals')
+  }
 
   @RemoteContext('agent', 'create')
   remoteExportCreate(request: CreateGoalRequest): Promise<CreateGoalResult> {
@@ -74,17 +78,17 @@ export class ScopedGoalService extends Service {
 
 An endpoint selects exactly one invocation mode. A flow that needs an explicit `Agent` parameter uses `@Remote`. A flow that first switches to an Agent Context and then resolves a scoped receiver uses `@RemoteContext('agent')`. TypeRT does not infer either mode from the method body or from a missing parameter.
 
-Business packages depend only on the lightweight `@deepseek-ai/dsh-type-meta`. It provides declaration protocols for decorators, `bindTypeRTGateway()`, lookup, Remote Context, and descriptors, without depending on the TypeScript compiler, Zod, HTTP, or the Client runtime.
+Business packages depend only on the lightweight `@deepseek-ai/dsh-type-meta`. It provides `GatewayService` and declaration protocols for decorators, the binding fallback, lookup, Remote Context, and descriptors, without depending on the TypeScript compiler, Zod, HTTP, or the Client runtime.
 
 A method that cooperatively supports cancellation declares `signal: AbortSignal` as its final Host parameter. This reserved parameter is not a business value, lookup, or JSON field. The generated consumer method exposes it as a final optional parameter so ordinary calls remain unchanged while callers that own cancellation can pass a signal.
 
 ## Decorators and the explicit Gateway facet
 
-A decorator only states that a method participates in the Remote contract. It performs no runtime type reflection and injects no hidden symbol into a Service constructor. The arguments to `@Remote('create')` and `@RemoteContext('agent', 'create')` are external method names, while the actual member remains named `remoteExportCreate`. The member name becomes the external method name only when no alias is provided. `typertGateway` is the sole explicit marker that a Service has joined the Gateway, making this capability visible on both the business class and its runtime instance.
+A decorator only states that a method participates in the Remote contract. It performs no runtime type reflection and injects no hidden symbol into a Service constructor. The arguments to `@Remote('create')` and `@RemoteContext('agent', 'create')` are external method names, while the actual member remains named `remoteExportCreate`. The member name becomes the external method name only when no alias is provided. Inheriting `GatewayService` is the normal explicit declaration that a Service has joined the Gateway; its public readonly `typertGateway` field keeps the binding visible on the runtime instance.
 
 In SRC mode, the decorator may record the prototype, method name, and invocation mode in a `WeakMap` internal to `dsh-type-meta`. It writes no custom properties to a Service instance, prototype, constructor, or method function.
 
-In LIB mode, the TypeRT compiler performs strict method discovery, type resolution, and descriptor generation. Generation neither rewrites business source nor secretly supplies generated arguments to `bindTypeRTGateway()`.
+In LIB mode, the TypeRT compiler performs strict method discovery, type resolution, and descriptor generation. It accepts a literal service key in `GatewayService`'s direct `super()` call or the explicit binding fallback; generation neither rewrites business source nor injects hidden registration metadata.
 
 ## Lookup and Remote Context registration
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 18b8c1687d..2de887a2a0 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -16,7 +16,7 @@ Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以
 
 ## 决策
 
-业务 Service 通过 `@Remote` 或 `@RemoteContext()` 声明可调用方法，并通过 `bindTypeRTGateway()` 显式加入 Gateway。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
+业务 Service 继承 `GatewayService`，并通过 `@Remote` 或 `@RemoteContext()` 声明可调用方法；已有其他基类的 Service 可以改用 `bindTypeRTGateway()` 暴露同一绑定。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
 
 Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client API Service；该投影和 API 抽象保持平台无关，以便未来 TUI 复用。
 
@@ -26,7 +26,7 @@ Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只
 
 | 组件 | Cordis 服务 | 职责 |
 |---|---|---|
-| `@deepseek-ai/dsh-type-meta` | 只声明 `ctx.typert` 的最小协议 | decorator、binding、descriptor、lookup/Context 和 Remote map；不依赖 compiler、Zod、Connection 或 Browser |
+| `@deepseek-ai/dsh-type-meta` | 只声明 `ctx.typert` 的最小协议 | `GatewayService`、decorator、binding 回退、descriptor、lookup/Context 和 Remote map；不依赖 compiler、Zod、Connection 或 Browser |
 | TypeRT registry | `ctx.typert` | 分开保存当前环境 reflection、导入的 Remote contribution、lookup provider 和 Context provider |
 | TypeRT generator/loader | 无新增业务服务 | 从 Host/Client Program 生成三类 `lib` 产物，并把当前环境产物注册到 `ctx.typert` |
 | Host API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service，解码参数、解析 receiver、调用方法和编码结果 |
@@ -43,8 +43,10 @@ Host Gateway 不依赖 `ctx.agents`、`ctx.sessions`、`ctx.goals` 或 `ctx.http
 普通直接调用使用 `@Remote`。迁移到现存 Service 或 Registry 时不重命名、不改变存量方法；类末尾新增 `remoteExport*` 出口，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
 
 ```text
-export class GoalService extends Service {
-  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+export class GoalService extends GatewayService {
+  constructor(ctx: Context) {
+    super(ctx, 'goals')
+  }
 
   create(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
     // Existing business method remains unchanged.
@@ -57,13 +59,15 @@ export class GoalService extends Service {
 }
 ```
 
-`goals` 是明确的 Cordis service key，并默认作为 wire namespace。只有协议 namespace 确实需要与 service key 不同时，才通过 `bindTypeRTGateway()` 的选项覆盖。
+`goals` 是传给 `super()` 的明确 Cordis service key，并默认作为 wire namespace。只有协议 namespace 确实需要与 service key 不同时，才通过第三个参数传入 `namespace` 选项。
 
 需要在某类隔离 Context 中查找 Service receiver 时使用 `@RemoteContext()`。Context identity 不进入业务方法参数：
 
 ```text
-export class ScopedGoalService extends Service {
-  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+export class ScopedGoalService extends GatewayService {
+  constructor(ctx: Context) {
+    super(ctx, 'goals')
+  }
 
   @RemoteContext('agent', 'create')
   remoteExportCreate(request: CreateGoalRequest): Promise<CreateGoalResult> {
@@ -74,17 +78,17 @@ export class ScopedGoalService extends Service {
 
 同一个 endpoint 只能选择一种调用模式。需要显式 `Agent` 参数的流程使用 `@Remote`；需要切换到 Agent Context 再解析 scoped receiver 的流程使用 `@RemoteContext('agent')`，两者不会由 TypeRT 根据方法体或参数缺失自动猜测。
 
-业务包只依赖轻量的 `@deepseek-ai/dsh-type-meta`。它提供 decorator、`bindTypeRTGateway()`、lookup、Remote Context 和 descriptor 的声明协议，不依赖 TypeScript compiler、Zod、HTTP 或 Client runtime。
+业务包只依赖轻量的 `@deepseek-ai/dsh-type-meta`。它提供 `GatewayService`，以及 decorator、binding 回退、lookup、Remote Context 和 descriptor 的声明协议，不依赖 TypeScript compiler、Zod、HTTP 或 Client runtime。
 
 支持协作式取消的方法会把 `signal: AbortSignal` 声明为最后一个 Host 参数。这个保留参数不是业务值、lookup 或 JSON 字段。生成的消费方方法将其暴露为最后一个可选参数，因此普通调用保持不变，而拥有取消控制权的调用方可以传入 signal。
 
 ## Decorator 与显式 Gateway facet
 
-Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteContext('agent', 'create')` 的参数是外部方法名，实际成员名保持 `remoteExportCreate`；未给别名时才使用成员名作为外部方法名。`typertGateway` 是 Service 加入 Gateway 的唯一显式标志，使业务类和运行时实例都能直接看出这项能力。
+Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteContext('agent', 'create')` 的参数是外部方法名，实际成员名保持 `remoteExportCreate`；未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
 
 SRC 运行时允许 decorator 在 `dsh-type-meta` 内部的 `WeakMap` 记录 prototype、方法名和调用模式。它不向 Service 实例、prototype、constructor 或方法函数写入自定义属性。
 
-LIB 的严格方法发现、类型解析和 descriptor 生成由 TypeRT compiler 完成。生成过程不改写业务源码，也不向 `bindTypeRTGateway()` 偷注生成参数。
+LIB 的严格方法发现、类型解析和 descriptor 生成由 TypeRT compiler 完成。它接受 `GatewayService` 直接 `super()` 调用中的字面量 service key，或显式 binding 回退；生成过程不改写业务源码，也不注入隐藏注册元数据。
 
 ## Lookup 与 Remote Context 注册
 
diff --git a/packages/goal/goal/src/index.ts b/packages/goal/goal/src/index.ts
index 0997aad0dc..312e3a70d9 100644
--- a/packages/goal/goal/src/index.ts
+++ b/packages/goal/goal/src/index.ts
@@ -5,14 +5,14 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { Context, Service } from 'cordis'
+import { Context } from 'cordis'
 import z from 'schemastery'
 import { z as zod } from 'zod'
 import type { ZodType } from 'zod'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
-import { Remote, bindTypeRTGateway } from '@deepseek-ai/dsh-type-meta'
+import { GatewayService, Remote } from '@deepseek-ai/dsh-type-meta'
 // Type-only: resolves ctx.sessionProjections for the optional unit child.
 import type {} from '@deepseek-ai/dsh-session-projection'
 import {
@@ -180,7 +180,7 @@ function resolveBlockReason(reason: unknown): GoalBlockReason {
 }
 
 /** Goal service (`ctx.goals`) backed exclusively by the owning session log. */
-export class GoalService extends Service {
+export class GoalService extends GatewayService {
   static inject = ['agents']
 
   static Config: z<Config> = z.object({
@@ -190,9 +190,6 @@ export class GoalService extends Service {
   private readonly resolved: ResolvedConfig
   private readonly caches = new WeakMap<Session, GoalCache>()
 
-  /** Explicit participation in the TypeRT Gateway under the Cordis service key. */
-  readonly typertGateway = bindTypeRTGateway(this, 'goals')
-
   constructor(ctx: Context, config: Config = {}) {
     super(ctx, 'goals')
     this.resolved = {
diff --git a/packages/host/api-gateway/README.i18n.yaml b/packages/host/api-gateway/README.i18n.yaml
index a1c22433f3..273a493c24 100644
--- a/packages/host/api-gateway/README.i18n.yaml
+++ b/packages/host/api-gateway/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/host/api-gateway/README.md
-README.md: 9cb6e7e1c0a23789ab4ab2c999b5a6c2d4cd32f9
-README.zh.md: 609580ceb77649ba8df6103093a72092c9ccc8a1
+README.md: 43e8f464e2a2790d05628a7fba61143a6a5ab26a
+README.zh.md: 761045d0c1afc17dfc230f9f45849c46e4e579fc
diff --git a/packages/host/api-gateway/README.md b/packages/host/api-gateway/README.md
index 9cb6e7e1c0..43e8f464e2 100644
--- a/packages/host/api-gateway/README.md
+++ b/packages/host/api-gateway/README.md
@@ -6,7 +6,7 @@ Two-sided Remote control for Host and Client Cordis environments. The Host entry
 
 ## Host service: `TypertGatewayService` (ctx key: `typertGateway`)
 
-`ctx.typertGateway.invoke()` resolves the current descriptor and Cordis Service for each call, validates exact named arguments, resolves registered object or Context identities, invokes the public business method, and validates its result. Business Services declare participation with `bindTypeRTGateway()` and `@Remote` or `@RemoteContext` from [`dsh-type-meta`](../../typert/type-meta/README.md).
+`ctx.typertGateway.invoke()` resolves the current descriptor and Cordis Service for each call, validates exact named arguments, resolves registered object or Context identities, invokes the public business method, and validates its result. Business Services extend `GatewayService` and mark methods with `@Remote` or `@RemoteContext` from [`dsh-type-meta`](../../typert/type-meta/README.md); `bindTypeRTGateway()` remains available when another base class owns inheritance.
 
 Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use registered `ctx.typert.lookups` providers, while `@RemoteContext` resolves its receiver through a registered Host Context provider. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation.
 
diff --git a/packages/host/api-gateway/README.zh.md b/packages/host/api-gateway/README.zh.md
index 609580ceb7..761045d0c1 100644
--- a/packages/host/api-gateway/README.zh.md
+++ b/packages/host/api-gateway/README.zh.md
@@ -6,7 +6,7 @@
 
 ## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
 
-每次调用时，`ctx.typertGateway.invoke()` 都会解析当前的描述符和 Cordis 服务，校验具名参数是否完全匹配，解析已注册的对象或 Context 身份标识，调用公开的业务方法，并校验其结果。业务服务调用 `bindTypeRTGateway()` 并使用 [`dsh-type-meta`](../../typert/type-meta/README.md) 提供的 `@Remote` 或 `@RemoteContext` 装饰器，以显式声明接入。
+每次调用时，`ctx.typertGateway.invoke()` 都会解析当前的描述符和 Cordis 服务，校验具名参数是否完全匹配，解析已注册的对象或 Context 身份标识，调用公开的业务方法，并校验其结果。业务服务继承 [`dsh-type-meta`](../../typert/type-meta/README.md) 的 `GatewayService`，并用 `@Remote` 或 `@RemoteContext` 标记方法；已有其他基类时仍可改用 `bindTypeRTGateway()`。
 
 严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用已向 `ctx.typert.lookups` 注册的提供方，`@RemoteContext` 则通过已注册的 Host Context 提供方解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。
 
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index 87a23f17f5..ecc7d8aa6b 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -142,7 +142,7 @@ interface StaticContextDeclaration {
 interface GatewayBinding {
   readonly service: string
   readonly namespace: string
-  readonly site: ts.PropertyDeclaration
+  readonly site: ts.Node
 }
 
 type ReferenceSite = ts.TypeReferenceNode | ts.ExpressionWithTypeArguments | ts.ImportTypeNode
@@ -927,7 +927,10 @@ class FaceAnalyzer {
         if (first === undefined) continue
         const binding = this.gatewayBinding(statement)
         if (binding === undefined) {
-          this.fail(first.method, 'Remote methods require readonly typertGateway = bindTypeRTGateway(this, serviceKey)')
+          this.fail(
+            first.method,
+            'Remote methods require GatewayService or readonly typertGateway = bindTypeRTGateway(this, serviceKey)',
+          )
         }
         for (const { method, invocation } of marked) {
           result.push(this.invocationModel(registration, binding, method, invocation))
@@ -1089,6 +1092,15 @@ class FaceAnalyzer {
   }
 
   private gatewayBinding(declaration: ts.ClassDeclaration): GatewayBinding | undefined {
+    const field = this.gatewayFieldBinding(declaration)
+    const base = this.gatewayServiceBinding(declaration)
+    if (field !== undefined && base !== undefined) {
+      this.fail(field.site, 'GatewayService subclasses must not declare a second typertGateway binding')
+    }
+    return field ?? base
+  }
+
+  private gatewayFieldBinding(declaration: ts.ClassDeclaration): GatewayBinding | undefined {
     const candidates = declaration.members.filter((member): member is ts.PropertyDeclaration =>
       ts.isPropertyDeclaration(member) && memberName(member.name) === 'typertGateway')
     const [property, duplicate] = candidates
@@ -1111,10 +1123,38 @@ class FaceAnalyzer {
     if (call.arguments[0]?.kind !== ts.SyntaxKind.ThisKeyword) {
       this.fail(call.arguments[0] ?? call, 'bindTypeRTGateway() first argument must be this')
     }
+    return this.gatewayBindingArguments(call, property)
+  }
+
+  private gatewayServiceBinding(declaration: ts.ClassDeclaration): GatewayBinding | undefined {
+    const heritage = (declaration.heritageClauses ?? [])
+      .filter(clause => clause.token === ts.SyntaxKind.ExtendsKeyword)
+      .flatMap(clause => [...clause.types])
+      .find(type => this.isTypeMetaSymbol(type.expression, 'GatewayService'))
+    if (heritage === undefined) return undefined
+
+    const constructor = declaration.members.find(ts.isConstructorDeclaration)
+    if (constructor?.body === undefined) {
+      this.fail(heritage, 'GatewayService subclasses must declare a constructor with super(ctx, serviceKey)')
+    }
+    const call = constructor.body.statements.flatMap((statement) => {
+      if (!ts.isExpressionStatement(statement) || !ts.isCallExpression(statement.expression)) return []
+      return statement.expression.expression.kind === ts.SyntaxKind.SuperKeyword ? [statement.expression] : []
+    })[0]
+    if (call === undefined) {
+      this.fail(constructor, 'GatewayService constructor must call super(ctx, serviceKey) directly')
+    }
+    if (call.arguments.length < 2 || call.arguments.length > 3) {
+      this.fail(call, 'GatewayService super() requires context, service key, and an optional options object')
+    }
+    return this.gatewayBindingArguments(call, heritage)
+  }
+
+  private gatewayBindingArguments(call: ts.CallExpression, site: ts.Node): GatewayBinding {
     const serviceArgument = call.arguments[1]
-    if (serviceArgument === undefined) this.fail(call, 'bindTypeRTGateway() service key must be a string literal')
+    if (serviceArgument === undefined) this.fail(call, 'Gateway service key must be a string literal')
     const service = stringLiteralValue(serviceArgument)
-    if (service === undefined) this.fail(serviceArgument, 'bindTypeRTGateway() service key must be a string literal')
+    if (service === undefined) this.fail(serviceArgument, 'Gateway service key must be a string literal')
     let namespace = service
     const options = call.arguments[2]
     if (options !== undefined) {
@@ -1133,7 +1173,7 @@ class FaceAnalyzer {
     }
     if (!isRemoteSegment(service)) this.fail(serviceArgument, 'Gateway service key must be nonempty and must not contain "/"')
     if (!isRemoteSegment(namespace)) this.fail(options ?? call, 'Gateway namespace must be nonempty and must not contain "/"')
-    return { service, namespace, site: property }
+    return { service, namespace, site }
   }
 
   private remoteMarker(
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
index 115b3b87a6..4aa51ec433 100644
--- a/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
@@ -1,4 +1,4 @@
-import { Remote, RemoteContext, bindTypeRTGateway } from '@deepseek-ai/dsh-type-meta'
+import { GatewayService, Remote, RemoteContext } from '@deepseek-ai/dsh-type-meta'
 import type { Agent } from '@fixture/domain'
 import type {
   CreateGoalRequest,
@@ -8,8 +8,10 @@ import type {
 } from './types.ts'
 
 /** Remote-only business Service with no Cordis declaration merge. */
-export class GoalService {
-  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+export class GoalService extends GatewayService {
+  constructor() {
+    super(undefined, 'goals')
+  }
 
   @Remote
   async create(agent: Agent, request: CreateGoalRequest, signal: AbortSignal): Promise<CreateGoalResult> {
diff --git a/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts b/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
index f8e84bbe90..91daea98c2 100644
--- a/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
+++ b/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
@@ -26,6 +26,19 @@ declare module '@deepseek-ai/dsh-type-meta' {
     readonly descriptors: readonly unknown[]
   }
 
+  export abstract class GatewayService {
+    readonly typertGateway: {
+      readonly service: GatewayService
+      readonly serviceKey: string
+      readonly namespace: string
+    }
+    protected constructor(
+      ctx: unknown,
+      serviceKey: string,
+      options?: { readonly namespace?: string },
+    )
+  }
+
   export function bindTypeRTGateway<Service extends object>(
     service: Service,
     serviceKey: string,
diff --git a/packages/typert/generator/tests/remote-model.spec.ts b/packages/typert/generator/tests/remote-model.spec.ts
index d5838f39ce..268645ca73 100644
--- a/packages/typert/generator/tests/remote-model.spec.ts
+++ b/packages/typert/generator/tests/remote-model.spec.ts
@@ -219,8 +219,56 @@ export type GenericResult = {
   it.each([
     {
       name: 'missing binding',
-      edit: (source: string) => source.replace("  readonly typertGateway = bindTypeRTGateway(this, 'goals')\n\n", ''),
-      message: 'Remote methods require readonly typertGateway',
+      edit: (source: string) => source.replace(
+        "export class GoalService extends GatewayService {\n  constructor() {\n    super(undefined, 'goals')\n  }",
+        'export class GoalService {',
+      ),
+      message: 'Remote methods require GatewayService',
+    },
+    {
+      name: 'dynamic GatewayService key',
+      edit: (source: string) => source.replace(
+        "  constructor() {\n    super(undefined, 'goals')\n  }",
+        '  constructor(serviceKey: string) {\n    super(undefined, serviceKey)\n  }',
+      ),
+      message: 'Gateway service key must be a string literal',
+    },
+    {
+      name: 'GatewayService without a constructor',
+      edit: (source: string) => source.replace(
+        "  constructor() {\n    super(undefined, 'goals')\n  }\n\n",
+        '',
+      ),
+      message: 'GatewayService subclasses must declare a constructor',
+    },
+    {
+      name: 'GatewayService without a direct super call',
+      edit: (source: string) => source.replace(
+        "    super(undefined, 'goals')",
+        '    void undefined',
+      ),
+      message: 'GatewayService constructor must call super',
+    },
+    {
+      name: 'GatewayService super call without a service key',
+      edit: (source: string) => source.replace(
+        "    super(undefined, 'goals')",
+        '    super(undefined)',
+      ),
+      message: 'GatewayService super\\(\\) requires context, service key',
+    },
+    {
+      name: 'duplicate GatewayService field binding',
+      edit: (source: string) => source
+        .replace(
+          'import { GatewayService, Remote, RemoteContext }',
+          'import { GatewayService, Remote, RemoteContext, bindTypeRTGateway }',
+        )
+        .replace(
+          'export class GoalService extends GatewayService {',
+          "export class GoalService extends GatewayService {\n  readonly typertGateway = bindTypeRTGateway(this, 'goals')",
+        ),
+      message: 'GatewayService subclasses must not declare a second typertGateway binding',
     },
     {
       name: 'private method',
@@ -351,8 +399,10 @@ export type GenericResult = {
   it('rejects duplicate endpoints across Remote services', () => {
     const root = copyFixture()
     editFile(root, 'packages/remote/src/index.ts', source => `${source}
-export class DuplicateGoalService {
-  readonly typertGateway = bindTypeRTGateway(this, 'duplicate', { namespace: 'goals' })
+export class DuplicateGoalService extends GatewayService {
+  constructor() {
+    super(undefined, 'duplicate', { namespace: 'goals' })
+  }
 
   @Remote
   create(request: CreateGoalRequest): CreateGoalResult {
@@ -521,7 +571,7 @@ ctx.api.goals.create('agent-1', { title: 'must not compile' })
   if (config.error !== undefined) throw new Error(formatDiagnostics([config.error]))
   const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, consumerRoot, undefined, configPath)
   const diagnostics = ts.getPreEmitDiagnostics(ts.createProgram(parsed.fileNames, parsed.options))
-  expect(diagnostics).toHaveLength(1)
+  expect(diagnostics, formatDiagnostics(diagnostics)).toHaveLength(1)
   expect(diagnostics[0]?.code).toBe(2339)
   expect(ts.flattenDiagnosticMessageText(diagnostics[0]?.messageText ?? '', '\n')).toContain("Property 'goals' does not exist")
 }
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
index 9751c4c088..a3e0643ace 100644
--- a/packages/typert/type-meta/README.i18n.yaml
+++ b/packages/typert/type-meta/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/typert/type-meta/README.md
-README.md: 95716446c01c7fd510cdf55a82509b5b8af6f3ae
-README.zh.md: 0d30b3122265d9bb3caa289345f843fe67377be3
+README.md: 245df305efcf711486b2d3f32e40a8b415f2682e
+README.zh.md: 592aa5d027a52a7a277a90ba5d51f19101f055f6
diff --git a/packages/typert/type-meta/README.md b/packages/typert/type-meta/README.md
index 95716446c0..245df305ef 100644
--- a/packages/typert/type-meta/README.md
+++ b/packages/typert/type-meta/README.md
@@ -2,18 +2,19 @@
 
 English | [中文](README.zh.md)
 
-Compiler-independent declarations shared by business packages, generated TypeRT artifacts, the Host Gateway, and Client API. This package owns Remote decorators, the explicit Service binding, merge-extensible protocol maps, invocation descriptors, codecs, and provider contracts; it does not run TypeScript analysis or provide a Cordis service.
+Compiler-independent declarations shared by business packages, generated TypeRT artifacts, the Host Gateway, and Client API. This package owns the Remote Service base, decorators, explicit binding fallback, merge-extensible protocol maps, invocation descriptors, codecs, and provider contracts; it does not run TypeScript analysis or register a concrete Cordis service.
 
 ## Remote declarations
 
 - `@Remote` marks a public instance method for direct invocation on its registered Cordis Service.
 - `@RemoteContext(key)` marks a method whose receiver is selected from a merge-declared scoped Context kind.
-- `bindTypeRTGateway(this, serviceKey, options?)` creates the visible, frozen binding between a Service instance, its exact Cordis key, and its wire namespace.
+- `GatewayService` binds the Cordis key passed to `super(ctx, serviceKey, options?)` to the same default wire namespace.
+- `bindTypeRTGateway(this, serviceKey, options?)` provides the same visible, frozen binding for a Service that cannot inherit from `GatewayService`.
 - `remoteMethods(service)` returns a detached declaration-order snapshot used by the Gateway's SRC fallback.
 
 A Host method opts into cooperative cancellation by declaring `signal: AbortSignal` as its final parameter. `InvocationDescriptor.cancellation` records that reserved injection point; the signal never becomes a JSON parameter or lookup field. SRC recognizes the final parameter name, while strict generation also verifies the global `AbortSignal` type.
 
-Decorator initializers retain markers in a module-private `WeakMap` keyed by the Service prototype. They do not add constructor symbols, prototype properties, parameter metadata, or runtime reflection fields. The Service opts in explicitly through its `typertGateway` binding field.
+Decorator initializers retain markers in a module-private `WeakMap` keyed by the Service prototype. They do not add constructor symbols, prototype properties, parameter metadata, or runtime reflection fields. A `GatewayService` exposes the same public readonly `typertGateway` binding that the explicit helper returns.
 
 ## TypeRT protocol
 
diff --git a/packages/typert/type-meta/README.zh.md b/packages/typert/type-meta/README.zh.md
index 0d30b31222..592aa5d027 100644
--- a/packages/typert/type-meta/README.zh.md
+++ b/packages/typert/type-meta/README.zh.md
@@ -2,18 +2,19 @@
 
 [English](README.md) | 中文
 
-该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、Host Gateway 和 Client API 共享。它负责 Remote 装饰器、显式服务绑定、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方契约；它不执行 TypeScript 分析，也不提供 Cordis 服务。
+该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、Host Gateway 和 Client API 共享。它负责 Remote Service 基类、装饰器、显式 binding 回退、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方契约；它不执行 TypeScript 分析，也不注册具体 Cordis 服务。
 
 ## Remote 声明
 
 - `@Remote` 将公开实例方法标记为可在其注册的 Cordis 服务上直接调用。
 - `@RemoteContext(key)` 标记接收者选自合并声明的作用域 Context 类型的方法。
-- `bindTypeRTGateway(this, serviceKey, options?)` 在服务实例、其准确的 Cordis key 与协议命名空间之间创建可见且冻结的绑定。
+- `GatewayService` 将 `super(ctx, serviceKey, options?)` 接收的 Cordis key 同时绑定为默认 wire namespace。
+- `bindTypeRTGateway(this, serviceKey, options?)` 为无法继承 `GatewayService` 的 Service 提供同样可见且冻结的绑定。
 - `remoteMethods(service)` 返回按声明顺序排列、与内部状态分离的快照，供 Gateway 的 SRC 回退路径使用。
 
 Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用协作式取消。`InvocationDescriptor.cancellation` 记录这个保留的注入点；signal 绝不会成为 JSON 参数或 lookup 字段。SRC 识别末位参数名，严格生成还会校验它是否具有全局 `AbortSignal` 类型。
 
-装饰器初始化器将标记保存在以服务 prototype 为键的模块私有 `WeakMap` 中。它们不会在构造函数上添加 symbol，也不会添加 prototype 属性、参数元数据或运行时反射字段。服务通过自身的 `typertGateway` 绑定字段显式接入。
+装饰器初始化器将标记保存在以服务 prototype 为键的模块私有 `WeakMap` 中。它们不会在构造函数上添加 symbol，也不会添加 prototype 属性、参数元数据或运行时反射字段。`GatewayService` 会暴露与显式 helper 相同的 public readonly `typertGateway` 绑定。
 
 ## TypeRT 协议
 
diff --git a/packages/typert/type-meta/src/index.ts b/packages/typert/type-meta/src/index.ts
index 92438ee0fa..4d4457b5be 100644
--- a/packages/typert/type-meta/src/index.ts
+++ b/packages/typert/type-meta/src/index.ts
@@ -4,6 +4,7 @@
  * @module @deepseek-ai/dsh-type-meta
  */
 
+import { Service, type Context } from 'cordis'
 import type { TypeRTContextMap } from './types.ts'
 
 export type {
@@ -104,6 +105,23 @@ export function bindTypeRTGateway<Service extends object>(
   return Object.freeze({ service, serviceKey, namespace })
 }
 
+/** Cordis Service base that exposes its registered name through TypeRT Gateway. */
+export abstract class GatewayService<out T = never> extends Service<T> {
+  /** Visible binding consumed by the Gateway's source-mode discovery. */
+  readonly typertGateway: TypeRTGatewayBinding<this>
+
+  /**
+   * Register the Service and bind the same key to TypeRT Gateway.
+   * @param ctx - owning Cordis Context.
+   * @param serviceKey - exact Cordis service key and default wire namespace.
+   * @param options - optional distinct wire namespace.
+   */
+  protected constructor(ctx: Context, serviceKey: string, options: TypeRTGatewayBindingOptions = {}) {
+    super(ctx, serviceKey)
+    this.typertGateway = bindTypeRTGateway(this, this.name, options)
+  }
+}
+
 /**
  * Mark one public instance method as a direct Remote invocation.
  * @param _method - decorated method; retained only by the class itself.
diff --git a/packages/typert/type-meta/tests/fixtures/source-launch.ts b/packages/typert/type-meta/tests/fixtures/source-launch.ts
index 68f886dff1..b13a80796d 100644
--- a/packages/typert/type-meta/tests/fixtures/source-launch.ts
+++ b/packages/typert/type-meta/tests/fixtures/source-launch.ts
@@ -1,12 +1,15 @@
+import { Context } from 'cordis'
 import {
-  bindTypeRTGateway,
+  GatewayService,
   Remote,
   RemoteContext,
   remoteMethods,
 } from '@deepseek-ai/dsh-type-meta'
 
-class Goals {
-  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+class Goals extends GatewayService {
+  constructor(ctx: Context) {
+    super(ctx, 'goals')
+  }
 
   @Remote
   create(value: string): string {
@@ -19,7 +22,7 @@ class Goals {
   }
 }
 
-const methods = remoteMethods(new Goals())
+const methods = remoteMethods(new Goals(new Context()))
 const actual = JSON.stringify(methods)
 const expected = JSON.stringify([
   { method: 'create', invocation: { kind: 'direct' } },
diff --git a/packages/typert/type-meta/tests/type-meta.spec.ts b/packages/typert/type-meta/tests/type-meta.spec.ts
index f25c367914..8a2a4372ce 100644
--- a/packages/typert/type-meta/tests/type-meta.spec.ts
+++ b/packages/typert/type-meta/tests/type-meta.spec.ts
@@ -1,8 +1,10 @@
 import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import {
   bindTypeRTGateway,
+  GatewayService,
   Remote,
   RemoteContext,
   remoteMethods,
@@ -16,9 +18,11 @@ declare module '@deepseek-ai/dsh-type-meta' {
 }
 
 describe('type-meta Remote declarations', () => {
-  it('executes standard decorator syntax through the Vitest source transform', () => {
-    class Goals {
-      readonly typertGateway = bindTypeRTGateway(this, 'goals')
+  it('binds a GatewayService name and executes decorators through the Vitest source transform', async () => {
+    class Goals extends GatewayService {
+      constructor(ctx: Context) {
+        super(ctx, 'goals')
+      }
 
       @Remote
       create(value: string): string {
@@ -31,11 +35,26 @@ describe('type-meta Remote declarations', () => {
       }
     }
 
-    const goals = new Goals()
+    class NamespacedGoals extends GatewayService {
+      constructor(ctx: Context) {
+        super(ctx, 'internalGoals', { namespace: 'goals' })
+      }
+    }
+
+    const ctx = new Context()
+    const goals = new Goals(ctx)
+    const namespaced = new NamespacedGoals(ctx)
+    expect(goals.typertGateway).toEqual({ service: goals, serviceKey: 'goals', namespace: 'goals' })
+    expect(namespaced.typertGateway).toEqual({
+      service: namespaced,
+      serviceKey: 'internalGoals',
+      namespace: 'goals',
+    })
     expect(remoteMethods(goals)).toEqual([
       { method: 'create', invocation: { kind: 'direct' } },
       { method: 'scoped', invocation: { kind: 'context', context: 'metaFixture' } },
     ])
+    await ctx.fiber.dispose()
   })
 
   it('executes standard decorator syntax through the TSX source launcher', () => {

From ede278d0c79ff07a53df018d782ed4753356e308 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 01:16:07 +0800
Subject: [PATCH 129/516] fix(connection): mint RPC ids on insecure origins

---
 packages/client/connection/src/client/fixture.ts   |  3 ++-
 .../client/connection/src/client/random-uuid.ts    | 14 ++++++++++++++
 packages/client/connection/src/client/rpc.ts       |  3 ++-
 .../client/connection/tests/client-apply.spec.ts   |  9 ++++++++-
 4 files changed, 26 insertions(+), 3 deletions(-)
 create mode 100644 packages/client/connection/src/client/random-uuid.ts

diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 31747bb311..e13c0a19f6 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -35,10 +35,11 @@ import type {
 } from './api.ts'
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { AbstractApiClient, RpcId, SESSION_SEARCH_RESULT_LIMIT } from './api.ts'
+import { randomUuid } from './random-uuid.ts'
 
 /** The fake carrier mints like a real one (business code never mints). */
 function rpcRequest<P>(payload: P): RpcRequest<P> {
-  return { rpcId: RpcId(crypto.randomUUID()), payload }
+  return { rpcId: RpcId(randomUuid()), payload }
 }
 
 function text(t: string): ContentBlock[] {
diff --git a/packages/client/connection/src/client/random-uuid.ts b/packages/client/connection/src/client/random-uuid.ts
new file mode 100644
index 0000000000..dc3106bd86
--- /dev/null
+++ b/packages/client/connection/src/client/random-uuid.ts
@@ -0,0 +1,14 @@
+/** Browser-safe UUID generation for client-side wire correlation. */
+
+/**
+ * Generate an RFC 4122 version 4 UUID without requiring a secure context.
+ * @returns a UUID backed by `crypto.getRandomValues()`, which browsers expose on insecure origins.
+ */
+export function randomUuid(): string {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16))
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  view.setUint8(6, (view.getUint8(6) & 0x0f) | 0x40)
+  view.setUint8(8, (view.getUint8(8) & 0x3f) | 0x80)
+  const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
diff --git a/packages/client/connection/src/client/rpc.ts b/packages/client/connection/src/client/rpc.ts
index 0c12149d7b..7883f2a9d3 100644
--- a/packages/client/connection/src/client/rpc.ts
+++ b/packages/client/connection/src/client/rpc.ts
@@ -6,6 +6,7 @@ import {
   type ClientRequest,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { ClientConnectionRpc } from '../rpc.ts'
+import { randomUuid } from './random-uuid.ts'
 
 const INTERNAL_BASE = 'http://dsh.internal'
 const CHANNEL_PATTERN = /^\/[A-Za-z0-9._~-]+$/
@@ -19,7 +20,7 @@ export function createWebConnectionRpc(): ClientConnectionRpc {
   return {
     async call(channel, endpoint, payload, signal) {
       assertTarget(channel, endpoint)
-      const rpcId = RpcId(crypto.randomUUID())
+      const rpcId = RpcId(randomUuid())
       const message: ClientRequest = {
         type: 'client-request',
         rpcId,
diff --git a/packages/client/connection/tests/client-apply.spec.ts b/packages/client/connection/tests/client-apply.spec.ts
index 6bf9c26b46..41e8e9b0e2 100644
--- a/packages/client/connection/tests/client-apply.spec.ts
+++ b/packages/client/connection/tests/client-apply.spec.ts
@@ -204,8 +204,13 @@ describe('connection client apply', () => {
     expect(sockets[0]?.readyState).toBe(FakeWebSocket.CLOSED)
   })
 
-  it('carries RPC calls over the shared API channel with rpcId echo validation', async () => {
+  it('carries RPC calls without requiring secure-context randomUUID', async () => {
     ;(globalThis as Win).location = { hostname: 'localhost', search: '' }
+    vi.stubGlobal('crypto', {
+      getRandomValues(bytes: Uint8Array) {
+        return bytes.fill(0)
+      },
+    })
     const handle = await mount()
     const original = globalThis.fetch
     const seen: { url: string; body: unknown }[] = []
@@ -225,11 +230,13 @@ describe('connection client apply', () => {
         .resolves.toEqual({ ok: true, value: { ref: 'goal-1' } })
     } finally {
       globalThis.fetch = original
+      vi.unstubAllGlobals()
     }
     expect(seen).toHaveLength(1)
     expect(seen[0]?.url).toBe('http://dsh.internal/api/goals/create')
     expect(seen[0]?.body).toMatchObject({
       type: 'client-request',
+      rpcId: '00000000-0000-4000-8000-000000000000',
       method: 'goals/create',
       payload: { args: { agentId: 'agent-1' } },
     })

From 2f619b1b88ebd0ffc054ff24852c8775d98946a1 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 01:59:34 +0800
Subject: [PATCH 130/516] docs: document TypeRT API-Gateway

---
 docs/api-gateway.i18n.yaml  |   6 ++
 docs/api-gateway.md         | 157 ++++++++++++++++++++++++++++++++++++
 docs/api-gateway.zh.md      | 157 ++++++++++++++++++++++++++++++++++++
 docs/architecture.i18n.yaml |   4 +-
 docs/architecture.md        |   1 +
 docs/architecture.zh.md     |   1 +
 docs/development.i18n.yaml  |   4 +-
 docs/development.md         |   2 +
 docs/development.zh.md      |   2 +
 9 files changed, 330 insertions(+), 4 deletions(-)
 create mode 100644 docs/api-gateway.i18n.yaml
 create mode 100644 docs/api-gateway.md
 create mode 100644 docs/api-gateway.zh.md

diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
new file mode 100644
index 0000000000..87abb10c88
--- /dev/null
+++ b/docs/api-gateway.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 docs/api-gateway.md
+api-gateway.md: 76af93880d278a17dc46370fd5065fdcdadb9fb6
+api-gateway.zh.md: d447cea6b64bf88084f86a210a5f654bd9445d6c
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
new file mode 100644
index 0000000000..76af93880d
--- /dev/null
+++ b/docs/api-gateway.md
@@ -0,0 +1,157 @@
+# API Gateway
+
+English | [中文](api-gateway.zh.md)
+
+This is the current-state reference for the TypeRT API Gateway. It describes how business services declare unary Remote methods, how the build generates Host and Client contracts, and how calls reuse the Connection RPC and `/api` route. Session events, incremental data, and other streaming protocols are outside this document's scope; they may use the same Connection but do not use Remote method descriptors.
+
+## Programming model
+
+Business services use `@Remote` or `@RemoteContext` to select the methods exposed to the Client. Unmarked methods do not enter the generated Client types or runtime contributions and cannot be called through `ctx.api`.
+
+`@Remote` denotes calling a Cordis service registered on the root Host Context. Complex Host objects cannot cross the wire directly; the business package must declare their association with a wire identity through `TypeRTLookupMap` and register a resolution provider with `ctx.typert.lookups` at runtime. For example, an `Agent` parameter named `agent` in the Host signature produces an `agentId` wire field, and the Gateway resolves that id to the current live object before invoking the business method.
+
+`@RemoteContext(key)` first resolves an identity to a scoped Context through `ctx.typert.contexts`, then obtains the service from that Context and invokes the method. It applies when the method itself depends on scoped composition and does not need to receive objects such as `Agent` explicitly.
+
+Services normally extend `GatewayService` so the constructor explicitly binds the Cordis service key and default Remote namespace. A service that already has another base class can instead declare `readonly typertGateway = bindTypeRTGateway(this, serviceKey)`; both forms leave an inspectable public binding and do not depend on the compiler injecting a symbol into the constructor.
+
+```ts
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { GatewayService, Remote, RemoteContext } from '@deepseek-ai/dsh-type-meta'
+import type { Context } from 'cordis'
+
+export interface CreateGoalRequest {
+  objective: string
+}
+
+export interface CreateGoalResult {
+  accepted: boolean
+}
+
+export class GoalService extends GatewayService {
+  constructor(ctx: Context) {
+    super(ctx, 'goals')
+  }
+
+  @Remote('create')
+  createForClient(
+    agent: Agent,
+    request: CreateGoalRequest,
+    signal: AbortSignal,
+  ): CreateGoalResult {
+    signal.throwIfAborted()
+    return this.create(agent, request)
+  }
+
+  @RemoteContext('agent', 'current')
+  currentForClient(): CreateGoalResult {
+    return { accepted: true }
+  }
+
+  private create(_agent: Agent, request: CreateGoalRequest): CreateGoalResult {
+    return { accepted: request.objective.length > 0 }
+  }
+}
+```
+
+Remote methods may return a value synchronously or return a Promise. For cooperative cancellation, the final parameter in the Host signature must be `signal: AbortSignal` using the global type; it is recorded in the descriptor instead of entering `args`, while the generated Client method accepts an optional final `AbortSignal`.
+
+The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct Remotes appear under `ctx.api.<namespace>`; when an `@Remote` method has exactly one lookup parameter and a same-named `TypeRTContextMap` uses the same wire identity, the generator also projects the method without that identity parameter onto the corresponding scoped Context. `@RemoteContext` generates only the scoped invocation interface.
+
+```ts
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { AgentContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { Context } from 'cordis'
+import type {} from '@deepseek-ai/dsh-client-remotes/client'
+
+declare const ctx: Context
+declare const agentCtx: AgentContext
+declare const agentId: SessionId
+
+await ctx.api.goals.create(agentId, { objective: 'ship it' })
+await agentCtx.goals.create({ objective: 'ship it' })
+```
+
+Client applications assemble only `@deepseek-ai/dsh-client-remotes`. That package imports the `/remote` subpaths of selected business packages as runtime values, mounts their contributions on `ctx.api`, and re-exports the declaration merges from the same files. Adding a Host Remote package is an explicit choice by the Client composition owner; business components do not need to load the Host API Gateway or the business package's Remote JS separately.
+
+A future TUI can assemble the same React-independent `client-remotes` and `ctx.api` contract, so the Host methods visible to it are likewise limited to the Remote methods selected at generation time. This document does not define or implement the TUI composition.
+
+## Component responsibilities
+
+| Location | Package or entry | Responsibility |
+|---|---|---|
+| Shared | `@deepseek-ai/dsh-type-meta` | Declares decorators, Gateway bindings, merge-extensible protocol maps, invocation descriptors, and provider types; starts no TypeScript analysis and registers no Cordis services |
+| Build | `@deepseek-ai/dsh-typert-generator` | Strictly analyzes Remote signatures, the type graph, lookups, Contexts, and source locations from the Host `ts.Program`, then generates Host and Host-for-Client artifacts |
+| Host | `@deepseek-ai/dsh-typert-registry` and Loader | Places generated Host descriptors, schemas, and business-package registrations in `ctx.typert`, and holds lookup and Context providers |
+| Host | `@deepseek-ai/dsh-host-api-gateway` | Provides `ctx.typertGateway`, claims Remote endpoints, resolves objects or Contexts, invokes live Cordis services, and validates boundaries |
+| Client | `@deepseek-ai/dsh-host-api-gateway/client` | Provides `ctx.api`, mounts generated descriptors as concrete methods, and initiates, validates, and cancels calls through the Connection |
+| Client | `@deepseek-ai/dsh-client-remotes/client` | Explicitly selects and mounts the `/remote` contributions allowed by the application and brings the corresponding declaration merges into business code |
+| Both | `@deepseek-ai/dsh-client-connection` | Provides the RPC carrier, request correlation, trust boundary, cancellation, response envelope, and current `/api` HTTP bridge |
+
+The Host API Gateway package owns the Host dispatcher and Client API as peer entries, but the two builds never enter the same `ts.Program`. The Host entry does not import the Client Cordis `Context` merge, and the Client entry does not import the Host Gateway service.
+
+## Strict generation pipeline
+
+The root build orders `build:lib:host`, `build:lib:client`, and `build:web`. The Host lib build first runs `build:lib:contracts`: it compiles the TypeRT generator, then starts a Host `ts.Program` through `tsdown.typert-host.config.ts` with `tsconfig.host.json` as its seed. The generator does not put the Host and Client aggregates in the same program, so it does not trigger conflicts between the two Cordis `Context` declaration merges.
+
+Each contributing business package writes generated files to its own `lib/` directory, not to its source directory:
+
+| File | Consumer | Contents |
+|---|---|---|
+| `typert.host.js` | Host Loader | Runtime reflection for the Host face, strict invocation descriptors, and schema registration values |
+| `typert.host.d.ts` | Host type system | Generated declarations for the Host face |
+| `typert.remote-client.js` | `client-remotes` | A mountable `TypeRTRemoteContribution` containing strict descriptors and runtime codecs |
+| `typert.remote-client.d.ts` | Client type system | Declaration merges for `TypeRTRemoteNamespaceMap` and `TypeRTRemoteContextMap`, plus Client-safe type references |
+| `typert.remote-client.d.ts.map` | Editor | Maps generated method properties back to Remote method declarations in the Host package |
+
+Business packages expose the Host Loader entry through `./typert` and the Host-for-Client entry through `./remote`. The generator also validates these package exports and published-file lists; it generates artifacts only for explicit contribution packages that provide the corresponding entry.
+
+Parameter names in Remote Client declarations come from wire fields, while parameter and return types reference Client-safe types exported by the original business package. The declaration map resolves the generated property behind `ctx.api.goals.create` back to the Host source method marked with `@Remote`, so editors that support declaration maps can navigate from a Client call to the real implementation instead of stopping at the generated `.d.ts`.
+
+Strict analysis requires a Remote to be a public, non-static instance method with a concrete implementation. The method cannot be generic; parameters must be required, named simple identifiers and cannot use destructuring, default values, rest parameters, or optional parameters. TypeRT generates strict schemas for ordinary JSON-representable types; complex objects such as workspace classes must have a unique `TypeRTLookupMap` declaration. Lookup and Context packages are responsible for both static declaration merges and runtime provider registration; if either side is missing, the build or earliest resolvable runtime boundary fails.
+
+## Runtime invocation
+
+Remote and API Proxy currently share the Connection's `/api` route; there is no separate `/api2` server or second Connection. The Client API calls `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`; the current HTTP carrier maps this to `POST /api/<namespace>/<method>`, with a payload containing only a named `args` object.
+
+The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler in interceptor order. The TypeRT Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; unclaimed requests fall back to the existing API Proxy. The Connection owns transport, RPC ids, response envelopes, and request cancellation, while the Gateway owns only the Remote data protocol and business dispatch. Replacing the Connection carrier in the future does not require changes to Remote descriptors or the Client programming interface.
+
+For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. It requires the fields in `args` to match the descriptor exactly, validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, invokes the service method targeted by the binding, and validates the return value. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails at the boundary before entering or after leaving business code.
+
+Unloading a Client contribution removes its descriptors and concrete methods together, aborts its in-flight calls, and makes stale method handles retained by external code reject further calls. A strict endpoint withdrawn on the Host also does not degrade to SRC inference, preventing a hot unload from silently weakening validation.
+
+## SRC development fallback
+
+When the Host starts from source through `node --import tsx/esm`, it does not execute the TypeRT compiler plugin. Standard decorator initializers still record the method name and invocation mode in a module-private `WeakMap`, while `GatewayService` or `bindTypeRTGateway()` supplies the explicit service binding; the Gateway can therefore construct a weaker temporary descriptor without starting a `ts.Program`.
+
+The SRC fallback parses simple parameter names from the live function. When a parameter name matches the `parameter` of a registered lookup, such as `agent` or `session`, it uses the lookup's `agentId` or `sessionId` wire field and resolves the object on the Host; other parameters are checked only for cycle-free, JSON-safe data with no special prototype. `@RemoteContext` directly uses the wire field of a registered Host Context provider. SRC does not read TypeScript types, generate Zod schemas, infer optional parameters, or support destructuring, default values, rest parameters, or duplicate parameter names.
+
+SRC solves only dispatch for a Host process running from source. The Client does not discover decorators from the running Host, and the Client API refuses to mount SRC descriptors that lack strict codecs; its types, codecs, and Remote registration values always come from the most recently generated `lib/typert.remote-client.*` artifacts.
+
+## Development mode
+
+A complete build generates Host contracts before compiling the Host, Client, and Web, so it is the deterministic entry for creating or refreshing all artifacts:
+
+```sh
+pnpm run build
+```
+
+Web development normally starts the source Host after one complete build and runs the Client plugin watcher in another terminal:
+
+```sh
+pnpm run dsh -- web --dev
+pnpm run dev:web
+```
+
+`dsh` starts the Host source through tsx, so the Host can use the SRC fallback; `dev:web` watches only Client plugins with a `dshClient` declaration and rewrites their `lib/client.js`. It does not analyze Host decorators or generate Remote Client DTS.
+
+Changing only a Remote method's implementation body without changing its contract does not require regenerating the TypeRT files. After adding or removing a decorator or changing an export name, namespace, parameter, return value, lookup, Context, or cancellation signature, regenerate the strict contracts before the Client bundle consumes the new artifacts:
+
+```sh
+pnpm run build:lib:contracts
+```
+
+The running Client watcher consumes these generated files when it rebundles; without a watcher, run `pnpm run build:lib:client`. Recompiling only the frontend source cannot infer new types from Host decorators. `pnpm run typecheck` includes `build:lib:contracts` as a prerequisite, and CI and release builds also use the strict generation pipeline.
+
+## Boundaries
+
+Remote handles only unary method calls with one request and one result. Session event streams, pagination, incremental reduce, projection, and entity substreams require a separate data protocol and registration model; even when they reuse the Connection, they must not masquerade as Remote methods or enter invocation descriptors.
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
new file mode 100644
index 0000000000..d447cea6b6
--- /dev/null
+++ b/docs/api-gateway.zh.md
@@ -0,0 +1,157 @@
+# API Gateway
+
+[English](api-gateway.md) | 中文
+
+本文是 TypeRT API Gateway 的当前状态参考。它描述业务 Service 如何声明一元 Remote 方法、构建如何生成 Host 与 Client 契约，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
+
+## 编程模型
+
+业务 Service 通过 `@Remote` 或 `@RemoteContext` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.api` 调用。
+
+`@Remote` 表示调用根 Host Context 中注册的 Cordis Service。复杂的 Host 对象不能直接跨 wire 传输；业务包必须通过 `TypeRTLookupMap` 声明它与 wire identity 的关联，并在运行时向 `ctx.typert.lookups` 注册解析提供方。例如 `Agent` 参数在 Host 签名中名为 `agent`，生成的 wire 字段为 `agentId`，Gateway 在调用业务方法前将 id 解析为当前的实时对象。
+
+`@RemoteContext(key)` 表示先通过 `ctx.typert.contexts` 把 identity 解析为一个作用域 Context，再从该 Context 取得 Service 并调用方法。它适用于方法本身依赖作用域组合、而不需要显式接收 `Agent` 等对象的情形。
+
+Service 通常继承 `GatewayService`，让 Cordis service key 与默认 Remote namespace 在构造器中显式绑定。已有其他基类的 Service 可以改为声明 `readonly typertGateway = bindTypeRTGateway(this, serviceKey)`；两种方式都会留下可检查的公开 binding，不依赖编译器向构造函数注入 symbol。
+
+```ts
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { GatewayService, Remote, RemoteContext } from '@deepseek-ai/dsh-type-meta'
+import type { Context } from 'cordis'
+
+export interface CreateGoalRequest {
+  objective: string
+}
+
+export interface CreateGoalResult {
+  accepted: boolean
+}
+
+export class GoalService extends GatewayService {
+  constructor(ctx: Context) {
+    super(ctx, 'goals')
+  }
+
+  @Remote('create')
+  createForClient(
+    agent: Agent,
+    request: CreateGoalRequest,
+    signal: AbortSignal,
+  ): CreateGoalResult {
+    signal.throwIfAborted()
+    return this.create(agent, request)
+  }
+
+  @RemoteContext('agent', 'current')
+  currentForClient(): CreateGoalResult {
+    return { accepted: true }
+  }
+
+  private create(_agent: Agent, request: CreateGoalRequest): CreateGoalResult {
+    return { accepted: request.objective.length > 0 }
+  }
+}
+```
+
+Remote 方法可以同步返回或返回 Promise。若需要协作式取消，Host 签名的最后一个参数必须是全局类型的 `signal: AbortSignal`；它记录在描述符中而不是进入 `args`，Client 生成的方法则接受最后一个可选的 `AbortSignal`。
+
+Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接 Remote 出现在 `ctx.api.<namespace>`；当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成器还会把去掉该 identity 参数后的方法投影到对应作用域 Context。`@RemoteContext` 只生成作用域调用界面。
+
+```ts
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { AgentContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { Context } from 'cordis'
+import type {} from '@deepseek-ai/dsh-client-remotes/client'
+
+declare const ctx: Context
+declare const agentCtx: AgentContext
+declare const agentId: SessionId
+
+await ctx.api.goals.create(agentId, { objective: 'ship it' })
+await agentCtx.goals.create({ objective: 'ship it' })
+```
+
+Client 应用只装配 `@deepseek-ai/dsh-client-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，并向 `ctx.api` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 Host API Gateway 或业务包的 Remote JS。
+
+未来的 TUI 可以装配同一个不依赖 React 的 `client-remotes` 与 `ctx.api` 契约，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
+
+## 组件职责
+
+| 位置 | 包或入口 | 职责 |
+|---|---|---|
+| 共享 | `@deepseek-ai/dsh-type-meta` | 声明 decorator、Gateway binding、可合并协议映射、调用描述符及提供方类型；不启动 TypeScript 分析，也不注册 Cordis 服务 |
+| 构建 | `@deepseek-ai/dsh-typert-generator` | 从 Host `ts.Program` 严格分析 Remote 签名、类型图、lookup、Context 与源码位置，并生成 Host 和 Host-for-Client 产物 |
+| Host | `@deepseek-ai/dsh-typert-registry` 与 Loader | 把生成的 Host 描述符、schema 及业务包注册项放入 `ctx.typert`，并持有 lookup 与 Context 提供方 |
+| Host | `@deepseek-ai/dsh-host-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或 Context，调用实时 Cordis Service 并校验边界 |
+| Client | `@deepseek-ai/dsh-host-api-gateway/client` | 提供 `ctx.api`，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
+| Client | `@deepseek-ai/dsh-client-remotes/client` | 显式选择并挂载本应用允许使用的 `/remote` 贡献，向业务代码带入对应的声明合并 |
+| 双侧 | `@deepseek-ai/dsh-client-connection` | 提供 RPC carrier、请求关联、信任边界、取消、响应 envelope 与当前 `/api` HTTP bridge |
+
+Host API Gateway 包同时拥有 Host dispatcher 与 Client API 两个对等入口，但两侧构建不会进入同一个 `ts.Program`。Host 入口不导入 Client 的 Cordis `Context` 合并，Client 入口也不导入 Host Gateway 服务。
+
+## 严格生成链路
+
+根构建按 `build:lib:host`、`build:lib:client`、`build:web` 排序。Host lib 构建首先运行 `build:lib:contracts`：它先编译 TypeRT generator，再通过 `tsdown.typert-host.config.ts` 以 `tsconfig.host.json` 为种子启动 Host `ts.Program`。生成器不会把 Host 与 Client 聚合放入同一个 program，因而不会触发两侧 Cordis `Context` 声明合并冲突。
+
+每个贡献业务包把生成文件写入自己的 `lib/`，而不是源码目录：
+
+| 文件 | 消费方 | 内容 |
+|---|---|---|
+| `typert.host.js` | Host Loader | Host face 的运行时反射、严格调用描述符和 schema 注册值 |
+| `typert.host.d.ts` | Host 类型系统 | Host face 的生成声明 |
+| `typert.remote-client.js` | `client-remotes` | 可挂载的 `TypeRTRemoteContribution`，包含严格描述符与运行时 codec |
+| `typert.remote-client.d.ts` | Client 类型系统 | `TypeRTRemoteNamespaceMap` 与 `TypeRTRemoteContextMap` 的声明合并及 Client-safe 类型引用 |
+| `typert.remote-client.d.ts.map` | 编辑器 | 将生成的方法属性映射回 Host 包中的 Remote 方法声明 |
+
+业务包通过 `./typert` 暴露 Host Loader 入口，通过 `./remote` 暴露 Host-for-Client 入口。生成器同时校验这些 package export 及发布文件清单；只有具备相应入口的显式贡献包才会生成产物。
+
+Remote Client 声明中的参数名来自 wire 字段，参数和返回类型则引用原业务包导出的 Client-safe 类型。声明 map 把 `ctx.api.goals.create` 最终解析到的生成属性映射到带 `@Remote` 的 Host 源方法，因此支持 declaration-map 的编辑器可以从 Client 调用跳到真实实现，而不是停在生成的 `.d.ts`。
+
+严格分析要求 Remote 是公开、非静态、有具体实现的实例方法。方法不能是泛型；参数必须是具名且必填的简单标识符，不能使用解构、默认值、rest 或可选参数。可 JSON 表示的普通类型由 TypeRT 生成严格 schema；工作区 class 等复杂对象必须具有唯一的 `TypeRTLookupMap` 声明。lookup 与 Context 包同时负责静态声明合并和运行时提供方注册，缺少任一侧都会在构建或最早可解析的运行时边界报错。
+
+## 运行时调用
+
+当前 Remote 与 API Proxy 共用 Connection 的 `/api` 路由，不存在独立 `/api2` server 或第二套 Connection。Client API 调用 `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`；当前 HTTP carrier 对应 `POST /api/<namespace>/<method>`，payload 只包含一个具名 `args` 对象。
+
+Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内按 interceptor 顺序分发。TypeRT Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；未认领的请求回退到既有 API Proxy。Connection 拥有传输、RPC id、响应 envelope 和 request cancellation，Gateway 只拥有 Remote 数据协议和业务分发。未来替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程界面。
+
+Gateway 每次调用都从当前注册表解析描述符和实时 Service，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或 Context provider 解析对象或接收者，最后调用 binding 指向的 Service 方法并校验返回值。缺少 provider、identity 未命中、binding 不一致、参数多缺、schema 失败和方法不存在都在进入或离开业务边界时失败。
+
+Client 卸载一个贡献时会一起移除描述符和具体方法，中止其进行中的调用，并使外部仍持有的旧方法句柄拒绝继续调用。Host 上已经注册过的严格 endpoint 被撤回后也不会降级到 SRC 推断，以免热卸载悄然降低校验强度。
+
+## SRC 开发回退
+
+Host 通过 `node --import tsx/esm` 从源码启动时不会执行 TypeRT 编译插件。标准 decorator 初始化器仍会把方法名和调用模式记录到模块私有 `WeakMap`，`GatewayService` 或 `bindTypeRTGateway()` 则提供显式 service binding；Gateway 因而可以在不启动 `ts.Program` 的情况下构造一个较弱的临时描述符。
+
+SRC 回退从运行中函数解析简单参数名。参数名与某个已注册 lookup 的 `parameter` 相同，例如 `agent` 或 `session`，就使用其 `agentId` 或 `sessionId` wire 字段并在 Host 解析对象；其他参数只检查值是否为无循环、无特殊 prototype 的 JSON-safe 数据。`@RemoteContext` 直接使用已注册 Host Context provider 的 wire 字段。SRC 不读取 TypeScript 类型，不生成 Zod schema，不推断可选参数，也不支持解构、默认值、rest 或重复参数名。
+
+SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Host 发现 decorator，Client API 也拒绝挂载缺少严格 codec 的 SRC 描述符；其类型、codec 和 Remote 注册值始终来自最近一次生成的 `lib/typert.remote-client.*`。
+
+## 开发模式
+
+完整构建会先生成 Host 契约，再编译 Host、Client 与 Web，因此是建立或刷新所有产物的确定性入口：
+
+```sh
+pnpm run build
+```
+
+Web 开发通常在完成一次构建后启动源码 Host，并在另一个终端运行 Client plugin watcher：
+
+```sh
+pnpm run dsh -- web --dev
+pnpm run dev:web
+```
+
+`dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 只监听带 `dshClient` 声明的 Client plugin 并重写其 `lib/client.js`，它不会分析 Host decorator，也不会生成 Remote Client DTS。
+
+只修改 Remote 方法实现体而不改变契约时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，先重新生成严格契约，再让 Client bundle 使用新的产物：
+
+```sh
+pnpm run build:lib:contracts
+```
+
+运行中的 Client watcher 会在重新打包时消费这些生成文件；没有 watcher 时运行 `pnpm run build:lib:client`。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 自带 `build:lib:contracts` 前置步骤，CI 与发布构建也使用严格生成链路。
+
+## 边界
+
+Remote 只处理有单个请求与单个结果的一元方法调用。Session event stream、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 8daacae254..774bc296b1 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 81464d9c8800556565c84d33239882dc750180a8
-architecture.zh.md: c02bca4f12c3758723b0fc818c89080dccf435d9
+architecture.md: db5991d98dfbc6b04992d62d5a465c375c9a78b8
+architecture.zh.md: 2eb8c3834a6ffc3283c8aa669be481b534bb5914
diff --git a/docs/architecture.md b/docs/architecture.md
index 81464d9c88..db5991d98d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -48,6 +48,7 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 | `ctx.credentials` | [`credentials/`](../packages/credentials/README.md) | named secret references resolved per operation, never inlined in configuration |
 | `ctx.directoryPicker` | [`host/directory-picker`](../packages/host/directory-picker/README.md) | GUI-host directory picking (`native`/`browse` interactions) |
 | `ctx.typert` | [`typert/registry`](../packages/typert/registry/README.md) | runtime registry for generated package reflection and live Zod schemas |
+| `ctx.typertGateway` | [`host/api-gateway`](../packages/host/api-gateway/README.md) | dispatches TypeRT Remote unary calls through the [API Gateway](api-gateway.md) |
 | `ctx.invariants` | [`support/invariants`](../packages/support/invariants/README.md) | package-name-selected registry of package-owned runtime checks |
 
 ## Event
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index c02bca4f12..2eb8c3834a 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -48,6 +48,7 @@
 | `ctx.credentials` | [`credentials/`](../packages/credentials/README.md) | 具名密钥引用，按操作解析，绝不内联进配置 |
 | `ctx.directoryPicker` | [`host/directory-picker`](../packages/host/directory-picker/README.md) | GUI 宿主目录选取（`native`／`browse` 交互） |
 | `ctx.typert` | [`typert/registry`](../packages/typert/registry/README.md) | 生成的包反射和实时 Zod schema 的运行时注册表 |
+| `ctx.typertGateway` | [`host/api-gateway`](../packages/host/api-gateway/README.md) | 通过 [API Gateway](api-gateway.md) 分发 TypeRT Remote 一元调用 |
 | `ctx.invariants` | [`support/invariants`](../packages/support/invariants/README.md) | 按包名筛选包自有运行时检查的注册表 |
 
 ## 事件
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 95ed34cce0..2ea336b1f0 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: 30a2bd0a2c97df8d3d75ec50f47b861b3a65590e
-development.zh.md: 5582a85429c97c3e31517a495c69392b80885f7d
+development.md: d480f548dd24ea81d132e4b4c0cc364ce1b0cd53
+development.zh.md: 08ef7fd2d3da7db83eb3ca4dff9f9c85f6d7cb5e
diff --git a/docs/development.md b/docs/development.md
index 30a2bd0a2c..d480f548dd 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -62,6 +62,8 @@ Host and client stay two aggregate programs because both sides declaration-merge
 
 Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).
 
+Business services declare callable methods on the Host with `@Remote` or `@RemoteContext`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `client-remotes` composition loads those contributions and mounts concrete methods on `ctx.api` or the corresponding scoped Context. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
+
 If a relevant local check consumes built package output, build once first:
 
 ```sh
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 5582a85429..08ef7fd2d3 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -62,6 +62,8 @@ host 与 client 保持两个聚合 program，是因为两侧在相同键下以
 
 静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。
 
+业务 Service 在 Host 使用 `@Remote` 或 `@RemoteContext` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `client-remotes` 组合加载这些贡献并将具体方法挂载到 `ctx.api` 或对应的作用域 Context。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
+
 如果相关的本地检查需要使用构建后的包产物，请先构建一次：
 
 ```sh

From da1ebd2b68a14af5d8688942fcedcfef59ff32a5 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 10:47:17 +0800
Subject: [PATCH 131/516] refactor(goal): call entity methods through remote
 API

---
 ...08-02-typert-remote-method-calls.i18n.yaml |  4 +-
 .../2026-08-02-typert-remote-method-calls.md  | 13 ++--
 ...026-08-02-typert-remote-method-calls.zh.md | 13 ++--
 docs/cordis-catalog/services.md               | 51 ++------------
 .../client/remotes/tests/built-lib.e2e.ts     | 12 +++-
 packages/client/ui-goal/README.i18n.yaml      |  4 +-
 packages/client/ui-goal/README.md             |  4 +-
 packages/client/ui-goal/README.zh.md          |  4 +-
 packages/client/ui-goal/package.json          |  5 +-
 packages/client/ui-goal/src/client/index.ts   | 51 +++++++++-----
 .../ui-goal/tests/browser-plugin.spec.tsx     | 70 ++++++++++++-------
 packages/client/ui-goal/tsconfig.json         |  4 +-
 .../cordis/tool-cordis/src/api-catalog.ts     | 30 ++------
 packages/goal/goal/src/index.ts               | 61 ++--------------
 packages/goal/goal/tests/goal.spec.ts         | 12 ++--
 pnpm-lock.yaml                                |  6 +-
 16 files changed, 140 insertions(+), 204 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 3808a8d363..1a59abbb43 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: ade8eb827ae765677be8dcdb0ffec965c67bc4ab
-2026-08-02-typert-remote-method-calls.zh.md: 2de887a2a0e46148fbb2b5ac52cfd7e3b2305b8d
+2026-08-02-typert-remote-method-calls.md: c810a221a23549f3e17e25bd40fcc1fc0f9ec868
+2026-08-02-typert-remote-method-calls.zh.md: 38e3ca286dad98665269697f49fba731346e665e
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index ade8eb827a..c810a221a2 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -40,7 +40,7 @@ The Host Gateway does not depend on concrete implementations of `ctx.agents`, `c
 
 ## Business declarations
 
-Ordinary direct calls use `@Remote`. When migrating to an existing Service or Registry, do not rename or alter existing methods. Add `remoteExport*` entry points at the end of the class and use decorator arguments to declare their short API names. A method explicitly declares every required business object in a top-level parameter position:
+Ordinary direct calls use `@Remote`. When an existing method's parameters and result are already the intended Remote contract, decorate that method directly without renaming it. Add a `remoteExport*` adapter only when the wire contract needs a distinct request or result shape, and use the decorator argument to declare its short API name. A method explicitly declares every required business object in a top-level parameter position:
 
 ```text
 export class GoalService extends GatewayService {
@@ -48,13 +48,14 @@ export class GoalService extends GatewayService {
     super(ctx, 'goals')
   }
 
-  create(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
+  create(agent: Agent, request: CreateGoalRequest): GoalView {
     // Existing business method remains unchanged.
   }
 
   @Remote('create')
   remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
-    return this.create(agent, request)
+    const view = this.create(agent, request)
+    return { ref: { id: view.id, revision: view.revision } }
   }
 }
 ```
@@ -84,7 +85,7 @@ A method that cooperatively supports cancellation declares `signal: AbortSignal`
 
 ## Decorators and the explicit Gateway facet
 
-A decorator only states that a method participates in the Remote contract. It performs no runtime type reflection and injects no hidden symbol into a Service constructor. The arguments to `@Remote('create')` and `@RemoteContext('agent', 'create')` are external method names, while the actual member remains named `remoteExportCreate`. The member name becomes the external method name only when no alias is provided. Inheriting `GatewayService` is the normal explicit declaration that a Service has joined the Gateway; its public readonly `typertGateway` field keeps the binding visible on the runtime instance.
+A decorator only states that a method participates in the Remote contract. It performs no runtime type reflection and injects no hidden symbol into a Service constructor. The arguments to `@Remote('create')` and `@RemoteContext('agent', 'create')` are external method names; the decorated member may be the business method itself or an adapter such as `remoteExportCreate`. The member name becomes the external method name only when no alias is provided. Inheriting `GatewayService` is the normal explicit declaration that a Service has joined the Gateway; its public readonly `typertGateway` field keeps the binding visible on the runtime instance.
 
 In SRC mode, the decorator may record the prototype, method name, and invocation mode in a `WeakMap` internal to `dsh-type-meta`. It writes no custom properties to a Service instance, prototype, constructor, or method function.
 
@@ -174,7 +175,7 @@ import type { CreateGoalRequest, CreateGoalResult } from '@deepseek-ai/dsh-goal/
 
 Consequently, `SessionId`, the Agent wire ID, the request, and the result all refer to the same TypeScript declaration in the Host and Browser Client. A future TUI can reuse them without a second set of types. Go to Definition, renames, and Find References for a DTO return to the one source location for the business type instead of stopping at a copy in a generated file.
 
-Remote API methods themselves use declaration-map navigation. TypeRT anchors `InvocationModel.location` to the method-name token of the Host `remoteExport*` method and emits a source-map segment on the corresponding property of the namespace interface. After the TypeScript editor resolves `ctx.api.models.list` to its generated declaration, `typert.remote-client.d.ts.map` takes it to the Host Service's `remoteExportList` entry point. That entry point explicitly calls the existing, unrenamed `list()` method; the map does not misidentify the decorator, class, or full signature as the method definition.
+Remote API methods themselves use declaration-map navigation. TypeRT anchors `InvocationModel.location` to the decorated Host method-name token and emits a source-map segment on the corresponding property of the namespace interface. For an adapter-backed endpoint, after the TypeScript editor resolves `ctx.api.models.list` to its generated declaration, `typert.remote-client.d.ts.map` takes it to the Host Service's `remoteExportList` entry point. That entry point explicitly calls the existing, unrenamed `list()` method; the map does not misidentify the decorator, class, or full signature as the method definition.
 
 TypeRT generates a wire Zod codec for the same symbol key. The Host Gateway uses it to validate input and encode results, while the Client API may use it to encode arguments and validate responses. If a complex type cannot produce a strict codec, the LIB build fails instead of degrading to `unknown` or unchecked JSON.
 
@@ -480,7 +481,7 @@ Connection supplies the shared-channel interceptor and current HTTP carrier mapp
 
 ## Verification
 
-- Goal Service keeps its existing business method and adds an explicit `typertGateway` plus `@Remote('create') remoteExportCreate(...)`, without a second route, codec, or Client method list.
+- Goal Service directly decorates mutation methods whose business signatures already match the Remote contract and keeps `remoteExportCreate(...)` only to adapt `GoalView` into `CreateGoalResult`, without a second route, codec, or Client method list.
 - A clean `build:lib` emits Host and consumer Remote artifacts before Client compilation, including the business package's JS, DTS, and declaration map under `/remote`.
 - Importing `@deepseek-ai/dsh-goal/remote` adds the strict `api.goals.create(...)` type and declaration navigation to `remoteExportCreate`; omitting that import omits the namespace.
 - Mounting the same import's JS contribution supplies endpoint, parameter, result, lookup, Context, and Zod reflection and materializes the call without a handwritten stub.
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 2de887a2a0..38e3ca286d 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -40,7 +40,7 @@ Host Gateway 不依赖 `ctx.agents`、`ctx.sessions`、`ctx.goals` 或 `ctx.http
 
 ## 业务声明
 
-普通直接调用使用 `@Remote`。迁移到现存 Service 或 Registry 时不重命名、不改变存量方法；类末尾新增 `remoteExport*` 出口，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
+普通直接调用使用 `@Remote`。现有方法的参数和结果已经是预期的 Remote 契约时，直接装饰该方法，不为此重命名。只有 wire 契约需要不同的请求或结果形态时，才新增 `remoteExport*` 适配器，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
 
 ```text
 export class GoalService extends GatewayService {
@@ -48,13 +48,14 @@ export class GoalService extends GatewayService {
     super(ctx, 'goals')
   }
 
-  create(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
+  create(agent: Agent, request: CreateGoalRequest): GoalView {
     // Existing business method remains unchanged.
   }
 
   @Remote('create')
   remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
-    return this.create(agent, request)
+    const view = this.create(agent, request)
+    return { ref: { id: view.id, revision: view.revision } }
   }
 }
 ```
@@ -84,7 +85,7 @@ export class ScopedGoalService extends GatewayService {
 
 ## Decorator 与显式 Gateway facet
 
-Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteContext('agent', 'create')` 的参数是外部方法名，实际成员名保持 `remoteExportCreate`；未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
+Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteContext('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
 
 SRC 运行时允许 decorator 在 `dsh-type-meta` 内部的 `WeakMap` 记录 prototype、方法名和调用模式。它不向 Service 实例、prototype、constructor 或方法函数写入自定义属性。
 
@@ -174,7 +175,7 @@ import type { CreateGoalRequest, CreateGoalResult } from '@deepseek-ai/dsh-goal/
 
 因此 `SessionId`、Agent wire ID、request 和 result 在 Host 与 Browser Client 中都指向同一 TypeScript declaration，未来 TUI 复用时也不需要第二份类型。DTO 的跳转定义、重命名和引用查找回到业务类型的唯一源码位置，而不是停在生成文件中的副本。
 
-Remote API 方法本身使用 declaration map 导航。TypeRT 把 `InvocationModel.location` 固定在 Host 的 `remoteExport*` 方法名 token，并在 namespace interface 的对应属性上写入 source-map segment；TypeScript editor 从 `ctx.api.models.list` 取得生成 declaration 后，再沿 `typert.remote-client.d.ts.map` 跳到 Host Service 的 `remoteExportList` 远程出口。该出口继续显式调用不改名的存量 `list()`，map 不把 decorator、class 或整个签名误当成方法定义位置。
+Remote API 方法本身使用 declaration map 导航。TypeRT 把 `InvocationModel.location` 固定在 Host 被装饰方法的方法名 token，并在 namespace interface 的对应属性上写入 source-map segment。对于由适配器支撑的 endpoint，TypeScript editor 从 `ctx.api.models.list` 取得生成 declaration 后，再沿 `typert.remote-client.d.ts.map` 跳到 Host Service 的 `remoteExportList` 远程出口。该出口继续显式调用不改名的存量 `list()`，map 不把 decorator、class 或整个签名误当成方法定义位置。
 
 TypeRT 为同一 symbol key 生成 wire Zod codec。Host Gateway 用它校验输入和编码结果，Client API 可以用它编码参数并校验响应；复杂类型无法生成严格 codec 时，LIB 构建失败，不降级为 `unknown` 或无校验 JSON。
 
@@ -480,7 +481,7 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 ## 验证
 
-- Goal Service 保留既有业务方法，并新增显式 `typertGateway` 与 `@Remote('create') remoteExportCreate(...)`，无需第二条路由、第二份 codec 或 Client 方法清单。
+- Goal Service 直接装饰业务签名已经符合 Remote 契约的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
 - 一次干净的 `build:lib` 会在 Client 编译前生成 Host 与消费方 Remote 产物，包括业务包 `/remote` 下的 JS、DTS 和 declaration map。
 - 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `api.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
 - 挂载同一次 import 得到的 JS contribution 会提供 endpoint、参数、结果、lookup、Context 和 Zod 反射，并在无需手写 stub 的情况下实体化调用。
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 99ffaca7c7..8a646fc177 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -718,7 +718,7 @@ create(agent: Agent, request: CreateGoalRequest): GoalView
  * @param request - at least one replacement field.
  * @returns the edited view.
  */
-edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
+@Remote('edit') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
 
 /**
  * Pause an active goal and disarm automatic continuation.
@@ -726,7 +726,7 @@ edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
  * @param ref - expected current revision.
  * @returns the paused view.
  */
-pause(agent: Agent, ref: GoalRef): GoalView
+@Remote('pause') pause(agent: Agent, ref: GoalRef): GoalView
 
 /**
  * Resume and arm a stopped goal, or rearm an active goal after a
@@ -735,7 +735,7 @@ pause(agent: Agent, ref: GoalRef): GoalView
  * @param ref - expected current revision.
  * @returns the active view.
  */
-resume(agent: Agent, ref: GoalRef): GoalView
+@Remote('resume') resume(agent: Agent, ref: GoalRef): GoalView
 
 /**
  * Mark a current non-complete goal complete and disarm it.
@@ -743,7 +743,7 @@ resume(agent: Agent, ref: GoalRef): GoalView
  * @param ref - expected current revision.
  * @returns the completed view.
  */
-complete(agent: Agent, ref: GoalRef): GoalView
+@Remote('complete') complete(agent: Agent, ref: GoalRef): GoalView
 
 /**
  * Mark an active goal blocked and disarm it.
@@ -760,7 +760,7 @@ block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
  * @param ref - expected current revision.
  * @returns the tombstone ref whose revision is one past the cleared snapshot.
  */
-clear(agent: Agent, ref: GoalRef): GoalRef
+@Remote('clear') clear(agent: Agent, ref: GoalRef): GoalRef
 
 /**
  * Create one Goal through the remote boundary.
@@ -769,47 +769,6 @@ clear(agent: Agent, ref: GoalRef): GoalRef
  * @returns the created Goal identity.
  */
 @Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
-
-/**
- * Edit one Goal through the remote boundary.
- * @param agent - exact live Agent resolved from the wire identity.
- * @param ref - expected current revision.
- * @param request - replacement fields.
- * @returns the edited Goal view.
- */
-@Remote('edit') remoteExportEdit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
-
-/**
- * Pause one Goal through the remote boundary.
- * @param agent - exact live Agent resolved from the wire identity.
- * @param ref - expected current revision.
- * @returns the paused Goal view.
- */
-@Remote('pause') remoteExportPause(agent: Agent, ref: GoalRef): GoalView
-
-/**
- * Resume one Goal through the remote boundary.
- * @param agent - exact live Agent resolved from the wire identity.
- * @param ref - expected current revision.
- * @returns the resumed Goal view.
- */
-@Remote('resume') remoteExportResume(agent: Agent, ref: GoalRef): GoalView
-
-/**
- * Complete one Goal through the remote boundary.
- * @param agent - exact live Agent resolved from the wire identity.
- * @param ref - expected current revision.
- * @returns the completed Goal view.
- */
-@Remote('complete') remoteExportComplete(agent: Agent, ref: GoalRef): GoalView
-
-/**
- * Clear one terminal Goal through the remote boundary.
- * @param agent - exact live Agent resolved from the wire identity.
- * @param ref - expected current revision.
- * @returns the committed clear revision.
- */
-@Remote('clear') remoteExportClear(agent: Agent, ref: GoalRef): GoalRef
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [CreateGoalRequest](../core-data-structures/goal.md) · [CreateGoalResult](../core-data-structures/goal.md) · [EditGoalRequest](../core-data-structures/goal.md) · [GoalBlockReason](../core-data-structures/goal.md) · [GoalRef](../core-data-structures/goal.md) · [GoalView](../core-data-structures/goal.md)
diff --git a/packages/client/remotes/tests/built-lib.e2e.ts b/packages/client/remotes/tests/built-lib.e2e.ts
index bef3f4ad65..0cee3eb245 100644
--- a/packages/client/remotes/tests/built-lib.e2e.ts
+++ b/packages/client/remotes/tests/built-lib.e2e.ts
@@ -148,11 +148,17 @@ describe.skipIf(!requiredArtifacts)('Goal Remote built LIB chain', () => {
         invalidRejected = true
       }
       const rootResult = await client.api.goals.create(rootAgent.id, { objective: 'root goal' })
+      const rootEdit = await client.api.goals.edit(
+        rootAgent.id,
+        rootResult.ref,
+        { objective: 'edited root goal' },
+      )
       const agentContext = client.extend({ builtAgentId: scopedAgent.id })
       const scopedResult = await agentContext.goals.create({ objective: 'scoped goal', maxGoalRounds: 3 })
       const result = {
         invalidRejected,
         rootResult,
+        rootEdit,
         scopedResult,
         rootGoal: host.goals.get(rootAgent)?.objective,
         scopedGoal: host.goals.get(scopedAgent)?.objective,
@@ -174,6 +180,7 @@ describe.skipIf(!requiredArtifacts)('Goal Remote built LIB chain', () => {
     const output = JSON.parse(result.stdout.trim().split('\n').at(-1) ?? '{}') as {
       invalidRejected: boolean
       rootResult: { ref: { id: string; revision: number } }
+      rootEdit: { objective: string; revision: number }
       scopedResult: { ref: { id: string; revision: number } }
       rootGoal: string
       scopedGoal: string
@@ -183,10 +190,11 @@ describe.skipIf(!requiredArtifacts)('Goal Remote built LIB chain', () => {
     expect(output).toMatchObject({
       invalidRejected: true,
       rootResult: { ref: { revision: 1 } },
+      rootEdit: { objective: 'edited root goal', revision: 2 },
       scopedResult: { ref: { revision: 1 } },
-      rootGoal: 'root goal',
+      rootGoal: 'edited root goal',
       scopedGoal: 'scoped goal',
-      rootEvents: 1,
+      rootEvents: 2,
       scopedEvents: 1,
     })
     expect(output.rootResult.ref.id).toMatch(/^goal-/)
diff --git a/packages/client/ui-goal/README.i18n.yaml b/packages/client/ui-goal/README.i18n.yaml
index 5120d720cd..f30f14ed48 100644
--- a/packages/client/ui-goal/README.i18n.yaml
+++ b/packages/client/ui-goal/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/client/ui-goal/README.md
-README.md: 0ea00b8bf9b07f02b5df0f7b3e7d3d9c6f109fde
-README.zh.md: 70bf443118e5d2b1ce46e7bc1479bf932507b3f9
+README.md: b99aaf624a7d669879ba668938ee455e3cdc68ad
+README.zh.md: 3d823d013066bc912398f61c85553887e05ca3b4
diff --git a/packages/client/ui-goal/README.md b/packages/client/ui-goal/README.md
index 0ea00b8bf9..b99aaf624a 100644
--- a/packages/client/ui-goal/README.md
+++ b/packages/client/ui-goal/README.md
@@ -2,13 +2,13 @@
 
 English | [中文](README.zh.md)
 
-Goal surface plugin, browser half: the `GoalBar` strip is the second standalone card in the `conversation.input.dock` composer-context stack (order 10, after Todo and before Queue). The live goal arrives through `useProjection('goal')` — the host-computed whole value seeded by the history tail page and updated by `session/projection` frames — so the plugin owns no domain store, refresh chain, or event listener. The slot inject face carries only the four mutation verbs (edit / pause / resume / clear over the `goal.*` wire domain — an active goal offers the pause action, a paused one resume); each reads the CAS ref from the session's current projected value at call time and surfaces the settled RPC error inline. The strip single-flights mutations synchronously because React's pending render cannot fence same-frame clicks; after a successful clear it immediately suppresses that exact goal id while the authoritative null projection catches up. Goal creation stays on the `/goal` host command; loading, absent, completed, and successfully cleared goals render nothing.
+Goal surface plugin, browser half: the `GoalBar` strip is the second standalone card in the `conversation.input.dock` composer-context stack (order 10, after Todo and before Queue). The live goal arrives through `useProjection('goal')` — the host-computed whole value seeded by the history tail page and updated by `session/projection` frames — so the plugin owns no domain store, refresh chain, or event listener. The slot inject face carries only the four mutation verbs (edit / pause / resume / clear through `ctx.api.goals` — an active goal offers the pause action, a paused one resume); each reads the CAS ref from the session's current projected value at call time and surfaces the rejected Remote error inline. The strip single-flights mutations synchronously because React's pending render cannot fence same-frame clicks; after a successful clear it immediately suppresses that exact goal id while the authoritative null projection catches up. Goal creation stays on the `/goal` host command; loading, absent, completed, and successfully cleared goals render nothing.
 
 The `/client` export surface is the plugin body (`apply`/`inject`), the `GoalBar`/`GoalDock` components, and the injected verb face types.
 
 ## Model Experience
 
-Indirectly, through the `goal.edit`/`goal.pause`/`goal.resume`/`goal.clear` RPCs the strip's verbs submit: each accepted mutation commits in a durable `agent/inbox/spliced` insertion, which the goal projection folds immediately, and queues a `goal/change` context message. The model sees that context only if a later pre-step admits it; discarding the queued message does not roll back the projected state. The strip itself adds no prompt content.
+Indirectly, through the `goals/edit`, `goals/pause`, `goals/resume`, and `goals/clear` Remote methods the strip invokes: each accepted mutation commits in a durable `agent/inbox/spliced` insertion, which the goal projection folds immediately, and queues a `goal/change` context message. The model sees that context only if a later pre-step admits it; discarding the queued message does not roll back the projected state. The strip itself adds no prompt content.
 
 #### KV Cache effect
 
diff --git a/packages/client/ui-goal/README.zh.md b/packages/client/ui-goal/README.zh.md
index 70bf443118..3d823d0130 100644
--- a/packages/client/ui-goal/README.zh.md
+++ b/packages/client/ui-goal/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-Goal 界面插件（浏览器端部分）：`GoalBar` 条带是 `conversation.input.dock` composer 上下文堆栈中的第二张独立卡片（order 10，位于 Todo 之后、Queue 之前）。活值经 `useProjection('goal')` 到达——host 计算的全量值由历史尾页播种、由 `session/projection` 帧更新——因此本插件不持有领域 store、不设刷新链、不挂事件监听。slot 注入面只携带四个变更动词（edit / pause / resume / clear，走 `goal.*` 协议域——active 的 goal 提供暂停动作，paused 的提供恢复）；每个动词在调用时从会话当前投影值读取 CAS ref，并把结算后的 RPC 错误内联呈现。由于 React 的 pending 渲染无法拦住同一帧内的点击，横条会同步为变更建立 single-flight 防护；清除成功后，会立即抑制该 goal id 对应的目标显示，直到权威的 null 投影追上。goal 的创建仍归 `/goal` host 命令；加载中、无 goal、已完成和已成功清除的 goal 一律不渲染。
+Goal 界面插件（浏览器端部分）：`GoalBar` 条带是 `conversation.input.dock` composer 上下文堆栈中的第二张独立卡片（order 10，位于 Todo 之后、Queue 之前）。活值经 `useProjection('goal')` 到达——host 计算的全量值由历史尾页播种、由 `session/projection` 帧更新——因此本插件不持有领域 store、不设刷新链、不挂事件监听。slot 注入面只携带四个变更动词（edit / pause / resume / clear，经 `ctx.api.goals` 调用——active 的 goal 提供暂停动作，paused 的提供恢复）；每个动词在调用时从会话当前投影值读取 CAS ref，并将 Remote 调用的拒绝错误内联呈现。由于 React 的 pending 渲染无法拦住同一帧内的点击，横条会同步为变更建立 single-flight 防护；清除成功后，会立即抑制该 goal id 对应的目标显示，直到权威的 null 投影追上。goal 的创建仍归 `/goal` host 命令；加载中、无 goal、已完成和已成功清除的 goal 一律不渲染。
 
 `/client` 的导出接口包括插件本体（`apply`/`inject`）、`GoalBar`/`GoalDock` 组件与注入动词面类型。
 
 ## 模型体验
 
-间接影响：条带动词提交的 `goal.edit`/`goal.pause`/`goal.resume`/`goal.clear` RPC 每次被接受后，变更都会在持久 `agent/inbox/spliced` 插入项中提交，goal 投影会立即折叠该插入项，同时将一条 `goal/change` 上下文消息排队。只有后续 pre-step 准入该上下文时，模型才会看到它；丢弃已排队的消息不会回滚投影状态。条带自身不添加任何提示词内容。
+间接影响：条带通过调用 `goals/edit`、`goals/pause`、`goals/resume` 和 `goals/clear` Remote 方法提交变更；每次被接受的变更都会在持久 `agent/inbox/spliced` 插入项中提交，goal 投影会立即折叠该插入项，同时将一条 `goal/change` 上下文消息排队。只有后续 pre-step 准入该上下文时，模型才会看到它；丢弃已排队的消息不会回滚投影状态。条带自身不添加任何提示词内容。
 
 #### KV Cache 影响
 
diff --git a/packages/client/ui-goal/package.json b/packages/client/ui-goal/package.json
index 9430da812f..4c26405bd8 100644
--- a/packages/client/ui-goal/package.json
+++ b/packages/client/ui-goal/package.json
@@ -25,6 +25,7 @@
   "dshClient": {
     "inject": [
       "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-remotes",
       "@deepseek-ai/dsh-client-locale",
       "@deepseek-ai/dsh-client-ui-conversation"
     ],
@@ -36,8 +37,8 @@
   },
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-client-connection": "^0.0.1",
     "@deepseek-ai/dsh-client-locale": "^0.0.1",
+    "@deepseek-ai/dsh-client-remotes": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
@@ -48,8 +49,8 @@
     "react": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-remotes": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
diff --git a/packages/client/ui-goal/src/client/index.ts b/packages/client/ui-goal/src/client/index.ts
index 6ee340715c..19b88139b5 100644
--- a/packages/client/ui-goal/src/client/index.ts
+++ b/packages/client/ui-goal/src/client/index.ts
@@ -4,19 +4,19 @@
  * arrives through `useProjection('goal')` (seeded by the history tail page,
  * updated by session/projection frames), so this plugin owns no store, no
  * refresh chain, and no event listener. The inject face carries only the
- * three mutation verbs (edit/resume/clear over the goal.* wire domain);
+ * four mutation verbs through the generated Goal Remote API;
  * their CAS ref reads the session's current projected value at call time.
  * Goal creation stays on the /goal host command.
  */
-import type { ConnectionHandle, GoalRef, SessionId } from '@deepseek-ai/dsh-client-connection/client'
-import type { RpcResult } from '@deepseek-ai/dsh-client-connection/client'
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ClientContext, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: pulls the generated Remote API and ctx.api merge through the Client assembly boundary.
+import type {} from '@deepseek-ai/dsh-client-remotes/client'
 // Type-only: pulls the ui-conversation SlotMap merge (the input.dock entry).
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 // Type-only: the `goal` SessionProjectionMap key merge (single source, the domain's pure outlet).
-import type { GoalProjection } from '@deepseek-ai/dsh-goal/client'
+import type { GoalProjection, GoalRef } from '@deepseek-ai/dsh-goal/client'
 import type { GoalActionResult, GoalBarActions } from './slots.ts'
 import { GoalDock } from './GoalBar.tsx'
 import { en, zh, type GoalKey } from './locales.ts'
@@ -35,13 +35,32 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 /** Dictionary namespace owned by this plugin. */
 const NS = 'goal'
 
-/** Required services: slots for the dock entry, sessions for the projected ref, connection for the wire verbs, locale for the copy. */
-export const inject = ['slots', 'sessions', 'connection', 'locale']
+/** Required services: slots for the dock entry, sessions for the projected ref, API for Remote mutations, locale for the copy. */
+export const inject = ['slots', 'sessions', 'api', 'locale']
 
-/** Map one settled RPC result onto the strip's inline-render shape. */
-function settle<T>(result: RpcResult<T>): GoalActionResult {
-  if (result.ok) return { ok: true }
-  return { ok: false, error: { code: result.error.code, message: result.error.message } }
+/** Map one generated Remote call onto the strip's inline-render shape. */
+async function settle(result: Promise<unknown>): Promise<GoalActionResult> {
+  try {
+    await result
+    return { ok: true }
+  } catch (error) {
+    const cause = error instanceof Error ? error.cause : undefined
+    if (isRemoteError(cause)) return { ok: false, error: { code: cause.code, message: cause.message } }
+    return {
+      ok: false,
+      error: {
+        code: 'internal',
+        message: error instanceof Error ? error.message : 'goal mutation failed',
+      },
+    }
+  }
+}
+
+function isRemoteError(value: unknown): value is { readonly code: string; readonly message: string } {
+  return value !== null
+    && typeof value === 'object'
+    && typeof (value as { code?: unknown }).code === 'string'
+    && typeof (value as { message?: unknown }).message === 'string'
 }
 
 /**
@@ -51,7 +70,7 @@ function settle<T>(result: RpcResult<T>): GoalActionResult {
 export function apply(ctx: ClientContext): void {
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-goal: dictionaries')
 
-  const { goals } = (ctx.get('connection') as ConnectionHandle).api
+  const { goals } = ctx.api
 
   const sessions = ctx.sessions
 
@@ -77,22 +96,22 @@ export function apply(ctx: ClientContext): void {
       onEdit: async (objective) => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle((await goals.edit({ sessionId, ref, objective })).result)
+        return settle(goals.edit(sessionId, ref, { objective }))
       },
       onPause: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle((await goals.pause({ sessionId, ref })).result)
+        return settle(goals.pause(sessionId, ref))
       },
       onResume: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle((await goals.resume({ sessionId, ref })).result)
+        return settle(goals.resume(sessionId, ref))
       },
       onClear: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle((await goals.clear({ sessionId, ref })).result)
+        return settle(goals.clear(sessionId, ref))
       },
     }),
   }, GoalDock))
diff --git a/packages/client/ui-goal/tests/browser-plugin.spec.tsx b/packages/client/ui-goal/tests/browser-plugin.spec.tsx
index 98d5a0291a..eddb272be4 100644
--- a/packages/client/ui-goal/tests/browser-plugin.spec.tsx
+++ b/packages/client/ui-goal/tests/browser-plugin.spec.tsx
@@ -1,11 +1,11 @@
 // @vitest-environment jsdom
 /**
- * ui-goal browser half on a real cordis Context with fake slots/connection/
+ * ui-goal browser half on a real cordis Context with fake slots/api/
  * sessions faces: the plugin registers the GoalBar dock entry at
- * conversation.input.dock, the inject face's three verbs read the CAS ref
+ * conversation.input.dock, the inject face's four verbs read the CAS ref
  * from the session's CURRENT projected value at call time (no fence — the
- * RPC's compare-and-set is the guard), a missing projection short-circuits
- * to the no-current-goal error without touching the wire, and RPC errors
+ * Remote method's compare-and-set is the guard), a missing projection short-circuits
+ * to the no-current-goal error without touching the wire, and Remote errors
  * map onto the inline-render result shape. Registration disposal rides the
  * plugin fiber (HMR safety). The node half and the invariant companion are
  * exercised over the same Context.
@@ -44,27 +44,32 @@ function makeProjection(revision = 3): GoalProjection {
   }
 }
 
-/** Boot the plugin over fake faces; goals verbs record payloads and answer per the script. */
-async function bench(options: { projection?: GoalProjection | null | undefined; failWith?: { code: string; message: string } } = {}) {
+/** Boot the plugin over fake faces; Goal Remote methods record arguments and answer per the script. */
+async function bench(options: {
+  projection?: GoalProjection | null | undefined
+  failWith?: { code: string; message: string }
+  rejectWith?: unknown
+} = {}) {
   const ctx = new Context()
-  const calls: { method: string; payload: unknown }[] = []
+  const calls: { method: string; args: unknown[] }[] = []
   function answer<T>(method: string, value: T) {
-    return (payload: unknown) => {
-      calls.push({ method, payload })
-      return Promise.resolve({
-        result: options.failWith === undefined
-          ? { ok: true as const, value }
-          : { ok: false as const, error: { ...options.failWith, details: {} } },
-      })
+    return (...args: unknown[]) => {
+      calls.push({ method, args })
+      // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- the non-Error rejection is the defensive scenario under test.
+      if ('rejectWith' in options) return Promise.reject(options.rejectWith)
+      if (options.failWith !== undefined) {
+        return Promise.reject(new Error(`Remote ${method} failed`, { cause: options.failWith }))
+      }
+      return Promise.resolve(value)
     }
   }
   const ref = { id: 'g-1', revision: 3 }
-  ctx.provide('connection', { api: { goals: {
-    edit: answer('goal.edit', { ref }),
-    pause: answer('goal.pause', { ref }),
-    resume: answer('goal.resume', { ref }),
-    clear: answer('goal.clear', { cleared: true as const }),
-  } } })
+  ctx.provide('api', { goals: {
+    edit: answer('goals/edit', { ref }),
+    pause: answer('goals/pause', { ref }),
+    resume: answer('goals/resume', { ref }),
+    clear: answer('goals/clear', ref),
+  } })
   await ctx.plugin(SlotsService).await()
   ctx.slots.register({
     name: 'root', children: { 'conversation.input.dock': { kind: 'list', scope: 'session' } },
@@ -113,12 +118,12 @@ describe('ui-goal browser plugin', () => {
     expect(await verbs.onPause()).toEqual({ ok: true })
     expect(await verbs.onResume()).toEqual({ ok: true })
     expect(await verbs.onClear()).toEqual({ ok: true })
-    expect(b.calls.map(c => c.method)).toEqual(['goal.edit', 'goal.pause', 'goal.resume', 'goal.clear'])
+    expect(b.calls.map(c => c.method)).toEqual(['goals/edit', 'goals/pause', 'goals/resume', 'goals/clear'])
     const ref = { id: 'g-1', revision: 5 }
-    expect(b.calls[0]?.payload).toEqual({ sessionId: 's1', ref, objective: 'New objective' })
-    expect(b.calls[1]?.payload).toEqual({ sessionId: 's1', ref })
-    expect(b.calls[2]?.payload).toEqual({ sessionId: 's1', ref })
-    expect(b.calls[3]?.payload).toEqual({ sessionId: 's1', ref })
+    expect(b.calls[0]?.args).toEqual(['s1', ref, { objective: 'New objective' }])
+    expect(b.calls[1]?.args).toEqual(['s1', ref])
+    expect(b.calls[2]?.args).toEqual(['s1', ref])
+    expect(b.calls[3]?.args).toEqual(['s1', ref])
   })
 
   it('a null or absent projection short-circuits every verb without touching the wire', async () => {
@@ -133,13 +138,26 @@ describe('ui-goal browser plugin', () => {
     }
   })
 
-  it('maps a settled RPC error onto the inline-render shape', async () => {
+  it('maps a Remote error onto the inline-render shape', async () => {
     const b = await bench({ projection: makeProjection(), failWith: { code: 'internal', message: 'stale revision' } })
     await b.fiber.await()
     const verbs = b.entry()!.inject!(sid('s1'))
     expect(await verbs.onEdit('x')).toEqual({ ok: false, error: { code: 'internal', message: 'stale revision' } })
   })
 
+  it.each([
+    [new Error('connection closed'), 'connection closed'],
+    ['connection closed', 'goal mutation failed'],
+    [new Error('invalid Remote failure', { cause: null }), 'invalid Remote failure'],
+    [new Error('invalid Remote failure', { cause: { code: 1, message: 'stale revision' } }), 'invalid Remote failure'],
+    [new Error('invalid Remote failure', { cause: { code: 'internal', message: 1 } }), 'invalid Remote failure'],
+  ])('maps an unstructured rejection onto an internal error', async (rejection, message) => {
+    const b = await bench({ projection: makeProjection(), rejectWith: rejection })
+    await b.fiber.await()
+    const verbs = b.entry()!.inject!(sid('s1'))
+    expect(await verbs.onEdit('x')).toEqual({ ok: false, error: { code: 'internal', message } })
+  })
+
   it('drops the dock entry when the plugin fiber unloads (HMR safety)', async () => {
     const b = await bench()
     await b.fiber.await()
diff --git a/packages/client/ui-goal/tsconfig.json b/packages/client/ui-goal/tsconfig.json
index ad863bdc32..2bb4070b18 100644
--- a/packages/client/ui-goal/tsconfig.json
+++ b/packages/client/ui-goal/tsconfig.json
@@ -12,10 +12,10 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../connection"
+      "path": "../locale"
     },
     {
-      "path": "../locale"
+      "path": "../remotes"
     },
     {
       "path": "../runtime"
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index d8d067ce3e..2627d43b69 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -359,19 +359,19 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         jsDoc: '/**\n * Create and arm a goal. A completed goal may be replaced; every other\n * current phase must be cleared or resumed instead.\n * @param agent - owning live agent.\n * @param request - objective and optional round cap.\n * @returns the created live view.\n */',
       },
       {
-        signature: 'edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView',
+        signature: '@Remote(\'edit\') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView',
         jsDoc: '/**\n * Edit objective and/or round cap without changing phase.\n * @param agent - owning live agent.\n * @param ref - expected current revision.\n * @param request - at least one replacement field.\n * @returns the edited view.\n */',
       },
       {
-        signature: 'pause(agent: Agent, ref: GoalRef): GoalView',
+        signature: '@Remote(\'pause\') pause(agent: Agent, ref: GoalRef): GoalView',
         jsDoc: '/**\n * Pause an active goal and disarm automatic continuation.\n * @param agent - owning live agent.\n * @param ref - expected current revision.\n * @returns the paused view.\n */',
       },
       {
-        signature: 'resume(agent: Agent, ref: GoalRef): GoalView',
+        signature: '@Remote(\'resume\') resume(agent: Agent, ref: GoalRef): GoalView',
         jsDoc: '/**\n * Resume and arm a stopped goal, or rearm an active goal after a\n * session-start edge, while its round budget still has capacity.\n * @param agent - owning live agent.\n * @param ref - expected current revision.\n * @returns the active view.\n */',
       },
       {
-        signature: 'complete(agent: Agent, ref: GoalRef): GoalView',
+        signature: '@Remote(\'complete\') complete(agent: Agent, ref: GoalRef): GoalView',
         jsDoc: '/**\n * Mark a current non-complete goal complete and disarm it.\n * @param agent - owning live agent.\n * @param ref - expected current revision.\n * @returns the completed view.\n */',
       },
       {
@@ -379,33 +379,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         jsDoc: '/**\n * Mark an active goal blocked and disarm it.\n * @param agent - owning live agent.\n * @param ref - expected current revision.\n * @param reason - policy-owned stable code and human-readable explanation.\n * @returns the blocked view with its durable reason.\n */',
       },
       {
-        signature: 'clear(agent: Agent, ref: GoalRef): GoalRef',
+        signature: '@Remote(\'clear\') clear(agent: Agent, ref: GoalRef): GoalRef',
         jsDoc: '/**\n * Clear the current goal while retaining a durable tombstone and history.\n * @param agent - owning live agent.\n * @param ref - expected current revision.\n * @returns the tombstone ref whose revision is one past the cleared snapshot.\n */',
       },
       {
         signature: '@Remote(\'create\') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult',
         jsDoc: '/**\n * Create one Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param request - objective and optional round cap.\n * @returns the created Goal identity.\n */',
       },
-      {
-        signature: '@Remote(\'edit\') remoteExportEdit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView',
-        jsDoc: '/**\n * Edit one Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param ref - expected current revision.\n * @param request - replacement fields.\n * @returns the edited Goal view.\n */',
-      },
-      {
-        signature: '@Remote(\'pause\') remoteExportPause(agent: Agent, ref: GoalRef): GoalView',
-        jsDoc: '/**\n * Pause one Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param ref - expected current revision.\n * @returns the paused Goal view.\n */',
-      },
-      {
-        signature: '@Remote(\'resume\') remoteExportResume(agent: Agent, ref: GoalRef): GoalView',
-        jsDoc: '/**\n * Resume one Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param ref - expected current revision.\n * @returns the resumed Goal view.\n */',
-      },
-      {
-        signature: '@Remote(\'complete\') remoteExportComplete(agent: Agent, ref: GoalRef): GoalView',
-        jsDoc: '/**\n * Complete one Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param ref - expected current revision.\n * @returns the completed Goal view.\n */',
-      },
-      {
-        signature: '@Remote(\'clear\') remoteExportClear(agent: Agent, ref: GoalRef): GoalRef',
-        jsDoc: '/**\n * Clear one terminal Goal through the remote boundary.\n * @param agent - exact live Agent resolved from the wire identity.\n * @param ref - expected current revision.\n * @returns the committed clear revision.\n */',
-      },
     ],
   },
   {
diff --git a/packages/goal/goal/src/index.ts b/packages/goal/goal/src/index.ts
index 312e3a70d9..6667463d86 100644
--- a/packages/goal/goal/src/index.ts
+++ b/packages/goal/goal/src/index.ts
@@ -273,6 +273,7 @@ export class GoalService extends GatewayService {
    * @param request - at least one replacement field.
    * @returns the edited view.
    */
+  @Remote('edit')
   edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView {
     const cache = this.prepareMutation(agent)
     const current = this.expectCurrent(cache, ref)
@@ -294,6 +295,7 @@ export class GoalService extends GatewayService {
    * @param ref - expected current revision.
    * @returns the paused view.
    */
+  @Remote('pause')
   pause(agent: Agent, ref: GoalRef): GoalView {
     return this.transition(agent, ref, 'pause', ['active'], 'paused', 'disarmed')
   }
@@ -305,6 +307,7 @@ export class GoalService extends GatewayService {
    * @param ref - expected current revision.
    * @returns the active view.
    */
+  @Remote('resume')
   resume(agent: Agent, ref: GoalRef): GoalView {
     const cache = this.prepareMutation(agent)
     const current = this.expectCurrent(cache, ref)
@@ -330,6 +333,7 @@ export class GoalService extends GatewayService {
    * @param ref - expected current revision.
    * @returns the completed view.
    */
+  @Remote('complete')
   complete(agent: Agent, ref: GoalRef): GoalView {
     return this.transition(
       agent,
@@ -369,6 +373,7 @@ export class GoalService extends GatewayService {
    * @param ref - expected current revision.
    * @returns the tombstone ref whose revision is one past the cleared snapshot.
    */
+  @Remote('clear')
   clear(agent: Agent, ref: GoalRef): GoalRef {
     const cache = this.prepareMutation(agent)
     const current = this.expectCurrent(cache, ref)
@@ -582,62 +587,6 @@ export class GoalService extends GatewayService {
     const view = this.create(agent, request)
     return { ref: { id: view.id, revision: view.revision } }
   }
-
-  /**
-   * Edit one Goal through the remote boundary.
-   * @param agent - exact live Agent resolved from the wire identity.
-   * @param ref - expected current revision.
-   * @param request - replacement fields.
-   * @returns the edited Goal view.
-   */
-  @Remote('edit')
-  remoteExportEdit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView {
-    return this.edit(agent, ref, request)
-  }
-
-  /**
-   * Pause one Goal through the remote boundary.
-   * @param agent - exact live Agent resolved from the wire identity.
-   * @param ref - expected current revision.
-   * @returns the paused Goal view.
-   */
-  @Remote('pause')
-  remoteExportPause(agent: Agent, ref: GoalRef): GoalView {
-    return this.pause(agent, ref)
-  }
-
-  /**
-   * Resume one Goal through the remote boundary.
-   * @param agent - exact live Agent resolved from the wire identity.
-   * @param ref - expected current revision.
-   * @returns the resumed Goal view.
-   */
-  @Remote('resume')
-  remoteExportResume(agent: Agent, ref: GoalRef): GoalView {
-    return this.resume(agent, ref)
-  }
-
-  /**
-   * Complete one Goal through the remote boundary.
-   * @param agent - exact live Agent resolved from the wire identity.
-   * @param ref - expected current revision.
-   * @returns the completed Goal view.
-   */
-  @Remote('complete')
-  remoteExportComplete(agent: Agent, ref: GoalRef): GoalView {
-    return this.complete(agent, ref)
-  }
-
-  /**
-   * Clear one terminal Goal through the remote boundary.
-   * @param agent - exact live Agent resolved from the wire identity.
-   * @param ref - expected current revision.
-   * @returns the committed clear revision.
-   */
-  @Remote('clear')
-  remoteExportClear(agent: Agent, ref: GoalRef): GoalRef {
-    return this.clear(agent, ref)
-  }
 }
 
 export default GoalService
diff --git a/packages/goal/goal/tests/goal.spec.ts b/packages/goal/goal/tests/goal.spec.ts
index 2dd5885cc7..3c642d2a8c 100644
--- a/packages/goal/goal/tests/goal.spec.ts
+++ b/packages/goal/goal/tests/goal.spec.ts
@@ -245,14 +245,14 @@ describe('GoalService creation and replay', () => {
 })
 
 describe('GoalService mutations', () => {
-  it('exposes the supported mutation sequence through Remote wrappers', async () => {
+  it('adapts Remote creation and reuses business methods for later mutations', async () => {
     const { ctx, agent } = await harness()
     const created = ctx.goals.remoteExportCreate(agent, { objective: 'remote lifecycle' })
-    const edited = ctx.goals.remoteExportEdit(agent, created.ref, { objective: 'edited remotely' })
-    const paused = ctx.goals.remoteExportPause(agent, edited)
-    const resumed = ctx.goals.remoteExportResume(agent, paused)
-    const completed = ctx.goals.remoteExportComplete(agent, resumed)
-    const cleared = ctx.goals.remoteExportClear(agent, completed)
+    const edited = ctx.goals.edit(agent, created.ref, { objective: 'edited remotely' })
+    const paused = ctx.goals.pause(agent, edited)
+    const resumed = ctx.goals.resume(agent, paused)
+    const completed = ctx.goals.complete(agent, resumed)
+    const cleared = ctx.goals.clear(agent, completed)
 
     expect(edited).toMatchObject({ objective: 'edited remotely', revision: 2 })
     expect(paused).toMatchObject({ phase: 'paused', revision: 3 })
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d9a4453a61..79d38a43cd 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1617,12 +1617,12 @@ importers:
 
   packages/client/ui-goal:
     devDependencies:
-      '@deepseek-ai/dsh-client-connection':
-        specifier: workspace:^
-        version: link:../connection
       '@deepseek-ai/dsh-client-locale':
         specifier: workspace:^
         version: link:../locale
+      '@deepseek-ai/dsh-client-remotes':
+        specifier: workspace:^
+        version: link:../remotes
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../runtime

From 2e1f9a5ceaf1c801f018791c326ea29fe42caf3d Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 11:05:55 +0800
Subject: [PATCH 132/516] fix(typert): address remote gateway review

---
 ...08-02-typert-remote-method-calls.i18n.yaml |  4 +-
 .../2026-08-02-typert-remote-method-calls.md  |  2 +-
 ...026-08-02-typert-remote-method-calls.zh.md |  2 +-
 packages/host/api-gateway/src/client/index.ts | 51 +++++++---
 .../host/api-gateway/tests/client.spec.ts     | 18 ++++
 packages/typert/generator/package.json        |  1 +
 packages/typert/generator/src/analyzer.ts     | 39 ++++----
 packages/typert/generator/src/emitter.ts      |  9 +-
 .../typert/generator/src/tsdown-plugin.ts     | 11 ++-
 packages/typert/generator/src/workspace.ts    | 20 ++--
 .../fixtures/remote-model/type-meta.d.ts      |  8 +-
 .../generator/tests/remote-model.spec.ts      | 97 ++++++++++++++++++-
 .../generator/tests/tsdown-plugin.spec.ts     | 33 ++++++-
 packages/typert/generator/tsconfig.json       |  3 +
 packages/typert/registry/src/service.ts       |  6 +-
 packages/typert/registry/tests/typert.spec.ts |  8 ++
 packages/typert/type-meta/src/index.ts        | 15 ++-
 .../typert/type-meta/tests/type-meta.spec.ts  |  3 +
 pnpm-lock.yaml                                |  3 +
 19 files changed, 275 insertions(+), 58 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 1a59abbb43..2400e39519 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: c810a221a23549f3e17e25bd40fcc1fc0f9ec868
-2026-08-02-typert-remote-method-calls.zh.md: 38e3ca286dad98665269697f49fba731346e665e
+2026-08-02-typert-remote-method-calls.md: 13b407d580c6042a71234e55cdb61225910f0e48
+2026-08-02-typert-remote-method-calls.zh.md: 434cf4765d2206f3c6f99b67c156b9508d70f313
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index c810a221a2..13b407d580 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -345,7 +345,7 @@ SRC supports local source startup. The `WeakMap` records created by `@Remote` an
 
 For example, `@Remote('create') remoteExportCreate(agent, request, signal)` resolves to the external method `create`, implementation member `remoteExportCreate`, two top-level business parameters, and one cancellation injection point. Lookup registration rewrites `agent` to the wire field `agentId`, `request` is passed as a same-named JSON parameter, and the final `signal` stays outside the payload. SRC does not start a `ts.Program`, use a preload or loader hook, generate or rewrite source, or inspect the internal structure of an ordinary JSON object.
 
-A signature that SRC cannot resolve unambiguously fails when the Service mounts. It does not guess at object destructuring, ambiguity caused by default parameters, rest parameters, nested lookups, or complex types.
+A signature that SRC cannot resolve unambiguously fails on the first invocation that resolves its descriptor; Service mounting records only the decorator marker and does not inspect the JavaScript signature. SRC does not guess at object destructuring, ambiguity caused by default parameters, rest parameters, nested lookups, or complex types.
 
 LIB supports CI, releases, and the prerequisite Web build. TypeRT scans the complete Host project and checks Remote decorators, explicit bindings, service keys, endpoint conflicts, lookup/Context declarations, public-symbol reachability, JSON codecs, result codecs, and that a reserved final `signal` parameter has the global `AbortSignal` type, then generates strict descriptors.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 38e3ca286d..434cf4765d 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -345,7 +345,7 @@ SRC 面向本地源码启动。`@Remote` 和 `@RemoteContext()` 的 WeakMap 记
 
 例如 `@Remote('create') remoteExportCreate(agent, request, signal)` 解析为外部方法 `create`、实现成员 `remoteExportCreate`、两个顶层业务参数和一个取消注入点；lookup 注册把 `agent` 改写为 wire 字段 `agentId`，`request` 按同名 JSON 参数传递，最后一个 `signal` 则留在 payload 之外。SRC 不启动 `ts.Program`，不使用 preload、loader hook、源码生成或模块改写，也不检查普通 JSON 对象的内部结构。
 
-SRC 无法明确解析的签名在 Service 挂载时失败。对象解构、默认参数造成的歧义、rest 参数、嵌套 lookup 和复杂类型不做猜测。
+SRC 无法明确解析的签名会在首次调用解析其 descriptor 时失败；Service 挂载只记录 decorator 标记，不检查 JavaScript 签名。SRC 不会猜测对象解构、默认参数造成的歧义、rest 参数、嵌套 lookup 或复杂类型。
 
 LIB 面向 CI、发布和 Web 前置构建。TypeRT 扫描完整 Host project，检查 Remote decorator、显式 binding、service key、endpoint 冲突、lookup/Context 声明、公共符号可达性、JSON codec、结果 codec，以及保留的最后一个 `signal` 参数是否具有全局 `AbortSignal` 类型，并生成严格 descriptor。
 
diff --git a/packages/host/api-gateway/src/client/index.ts b/packages/host/api-gateway/src/client/index.ts
index 292df54152..3fc8389079 100644
--- a/packages/host/api-gateway/src/client/index.ts
+++ b/packages/host/api-gateway/src/client/index.ts
@@ -134,8 +134,11 @@ class ClientApiService extends Service implements ClientApi {
       const record = this.scoped.get(namespace)
       if (record !== undefined) {
         for (const method of methods) record.service.assertMethodAvailable(method)
-      } else if (this.ownerCtx.reflect.props[namespace] !== undefined) {
-        throw new Error(`client api: scoped namespace ${JSON.stringify(namespace)} conflicts with an existing Context property`)
+      } else {
+        for (const method of methods) ScopedRemoteNamespace.assertMethodAvailable(namespace, method)
+        if (this.ownerCtx.reflect.props[namespace] !== undefined) {
+          throw new Error(`client api: scoped namespace ${JSON.stringify(namespace)} conflicts with an existing Context property`)
+        }
       }
     }
   }
@@ -143,11 +146,18 @@ class ClientApiService extends Service implements ClientApi {
   private install(descriptor: InvocationDescriptor): () => void {
     const token: MountToken = { active: true, abort: new AbortController() }
     const installed: (() => void)[] = []
-    if (descriptor.invocation.kind === 'direct') {
-      installed.push(this.installDirect(descriptor, token))
+    try {
+      if (descriptor.invocation.kind === 'direct') {
+        installed.push(this.installDirect(descriptor, token))
+      }
+      const projection = scopedProjection(descriptor)
+      if (projection !== undefined) installed.push(this.installScoped(descriptor, projection, token))
+    } catch (error) {
+      token.active = false
+      for (const dispose of installed.reverse()) dispose()
+      token.abort.abort()
+      throw error
     }
-    const projection = scopedProjection(descriptor)
-    if (projection !== undefined) installed.push(this.installScoped(descriptor, projection, token))
     return () => {
       /* v8 ignore next -- Cordis effect disposers are idempotent and invoke this cleanup at most once. */
       if (!token.active) return
@@ -192,19 +202,19 @@ class ClientApiService extends Service implements ClientApi {
   ): () => void {
     let namespace = this.scoped.get(descriptor.namespace)
     if (namespace === undefined) {
-      namespace = {
-        service: new ScopedRemoteNamespace(
-          this.ownerCtx,
-          descriptor.namespace,
-          (current, currentProjection, currentToken, caller, args) =>
-            this.invoke(current, currentProjection, currentToken, caller, args),
-        ),
-        tokens: new Map(),
-      }
+      const service = new ScopedRemoteNamespace(
+        this.ownerCtx,
+        descriptor.namespace,
+        (current, currentProjection, currentToken, caller, args) =>
+          this.invoke(current, currentProjection, currentToken, caller, args),
+      )
+      service.install(descriptor, projection, token)
+      namespace = { service, tokens: new Map() }
       this.scoped.set(descriptor.namespace, namespace)
+    } else {
+      namespace.service.install(descriptor, projection, token)
     }
     namespace.tokens.set(descriptor.method, token)
-    namespace.service.install(descriptor, projection, token)
     return () => {
       /* v8 ignore next -- duplicate live methods are rejected before installation, so no newer token can replace this one. */
       if (namespace.tokens.get(descriptor.method) !== token) return
@@ -275,6 +285,12 @@ class ScopedRemoteNamespace extends Service {
   private readonly ownerCtx: Context
   private readonly methods = new Set<string>()
 
+  static assertMethodAvailable(namespace: string, method: string): void {
+    if (SCOPED_NAMESPACE_FIELDS.has(method) || method in ScopedRemoteNamespace.prototype) {
+      throw new Error(`client api: scoped method ${JSON.stringify(`${namespace}/${method}`)} conflicts with its namespace service`)
+    }
+  }
+
   constructor(
     ctx: Context,
     name: string,
@@ -285,6 +301,7 @@ class ScopedRemoteNamespace extends Service {
   }
 
   assertMethodAvailable(method: string): void {
+    ScopedRemoteNamespace.assertMethodAvailable(this.name, method)
     if (method in this) {
       throw new Error(`client api: scoped method ${JSON.stringify(`${this.name}/${method}`)} conflicts with its namespace service`)
     }
@@ -311,6 +328,8 @@ class ScopedRemoteNamespace extends Service {
   }
 }
 
+const SCOPED_NAMESPACE_FIELDS = new Set(['ctx', 'invokeRemote', 'methods', 'name', 'ownerCtx'])
+
 function endpointOf(descriptor: Pick<InvocationDescriptor, 'namespace' | 'method'>): string {
   return `${descriptor.namespace}/${descriptor.method}`
 }
diff --git a/packages/host/api-gateway/tests/client.spec.ts b/packages/host/api-gateway/tests/client.spec.ts
index 3ad00ff0fc..28aa848fcd 100644
--- a/packages/host/api-gateway/tests/client.spec.ts
+++ b/packages/host/api-gateway/tests/client.spec.ts
@@ -279,6 +279,24 @@ describe('Client TypeRT API', () => {
     await disposeMultipleScoped()
   })
 
+  it('rolls back direct projection when scoped installation fails', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const descriptor: InvocationDescriptor = {
+      ...directDescriptor(),
+      id: '@fixture/goals#fresh/remove',
+      namespace: 'fresh',
+      method: 'remove',
+    }
+
+    for (const packageName of ['@fixture/first-attempt', '@fixture/second-attempt']) {
+      expect(() => ctx.api.mount({ package: packageName, descriptors: [descriptor] }))
+        .toThrow('conflicts with its namespace service')
+      expect((ctx.api as unknown as Record<string, unknown>).fresh).toBeUndefined()
+      expect(ctx.get('fresh')).toBeUndefined()
+      expect(ctx.typert.remotes.list()).toEqual([])
+    }
+  })
+
   it('rejects weak parameter and Context codecs plus malformed scope projections', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const direct = directDescriptor()
diff --git a/packages/typert/generator/package.json b/packages/typert/generator/package.json
index 5ffb933214..eed553ebed 100644
--- a/packages/typert/generator/package.json
+++ b/packages/typert/generator/package.json
@@ -30,6 +30,7 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
     "@jridgewell/gen-mapping": "^0.3.13",
     "typescript": "^6.0.3"
   },
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index ecc7d8aa6b..5e26245171 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -8,6 +8,7 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import { dirname, extname, join, relative, resolve, sep } from 'node:path'
 import ts from 'typescript'
+import { isTypeRTRemoteSegment } from '@deepseek-ai/dsh-type-meta'
 import type {
   CrossFaceLink,
   DocumentationModel,
@@ -1171,8 +1172,8 @@ class FaceAnalyzer {
         namespace = value
       }
     }
-    if (!isRemoteSegment(service)) this.fail(serviceArgument, 'Gateway service key must be nonempty and must not contain "/"')
-    if (!isRemoteSegment(namespace)) this.fail(options ?? call, 'Gateway namespace must be nonempty and must not contain "/"')
+    if (!isRemoteSegment(service)) this.fail(serviceArgument, 'Gateway service key must contain only RPC endpoint segment characters')
+    if (!isRemoteSegment(namespace)) this.fail(options ?? call, 'Gateway namespace must contain only RPC endpoint segment characters')
     return { service, namespace, site }
   }
 
@@ -1196,7 +1197,7 @@ class FaceAnalyzer {
         if (expression.arguments.length !== 1) this.fail(expression, 'Remote() requires one exported method name')
         const exportName = stringLiteralValue(expression.arguments[0])
         if (exportName === undefined || !isRemoteSegment(exportName)) {
-          this.fail(expression.arguments[0] ?? expression, 'Remote() name must be a nonempty string literal without "/"')
+          this.fail(expression.arguments[0] ?? expression, 'Remote() name must be a string literal containing only RPC endpoint segment characters')
         }
         marker = { kind: 'direct', exportName }
       } else if (ts.isCallExpression(expression)
@@ -1206,12 +1207,12 @@ class FaceAnalyzer {
         }
         const context = stringLiteralValue(expression.arguments[0])
         if (context === undefined || !isRemoteSegment(context)) {
-          this.fail(expression.arguments[0] ?? expression, 'RemoteContext() key must be a nonempty string literal without "/"')
+          this.fail(expression.arguments[0] ?? expression, 'RemoteContext() key must be a string literal containing only RPC endpoint segment characters')
         }
         const exportArgument = expression.arguments[1]
         const exportName = exportArgument === undefined ? undefined : stringLiteralValue(exportArgument)
         if (exportArgument !== undefined && (exportName === undefined || !isRemoteSegment(exportName))) {
-          this.fail(exportArgument, 'RemoteContext() name must be a nonempty string literal without "/"')
+          this.fail(exportArgument, 'RemoteContext() name must be a string literal containing only RPC endpoint segment characters')
         }
         marker = { kind: 'context', context, ...exportName === undefined ? {} : { exportName } }
       } else {
@@ -1251,7 +1252,7 @@ class FaceAnalyzer {
         this.fail(declaration, 'TypeRTLookupMap entries must be required properties')
       }
       const key = memberName(declaration.name)
-      if (!isRemoteSegment(key)) this.fail(declaration.name, 'TypeRTLookupMap key must be nonempty and must not contain "/"')
+      if (!isRemoteSegment(key)) this.fail(declaration.name, 'TypeRTLookupMap key must contain only RPC endpoint segment characters')
       if (!ts.isTypeReferenceNode(declaration.type)
         || !this.isTypeMetaSymbol(declaration.type.typeName, 'TypeRTLookup')
         || declaration.type.typeArguments?.length !== 2) {
@@ -1287,7 +1288,7 @@ class FaceAnalyzer {
         this.fail(declaration, 'TypeRTContextMap entries must be required properties')
       }
       const key = memberName(declaration.name)
-      if (!isRemoteSegment(key)) this.fail(declaration.name, 'TypeRTContextMap key must be nonempty and must not contain "/"')
+      if (!isRemoteSegment(key)) this.fail(declaration.name, 'TypeRTContextMap key must contain only RPC endpoint segment characters')
       if (!ts.isTypeReferenceNode(declaration.type)
         || !this.isTypeMetaSymbol(declaration.type.typeName, 'TypeRTContext')
         || declaration.type.typeArguments?.length !== 1) {
@@ -1331,16 +1332,6 @@ class FaceAnalyzer {
     const type = this.convertType(authoredType)
     const codecType = this.resolvedRemoteCodecType(authoredType)
     const rootSymbol = this.namedWorkspaceType(authoredType)
-    if (rootSymbol !== undefined) {
-      const imported = this.publicRemoteType(rootSymbol, authoredType)
-      return {
-        type,
-        codecType,
-        typeSymbol: `${imported.specifier}#${imported.name}`,
-        imports: [imported],
-      }
-    }
-    if (requireNamed) this.fail(authoredType, 'lookup and Context wire types must be named public types')
     const imports = new Map<SymbolId, RemoteTypeImportModel>()
     const visit = (node: ts.Node): void => {
       if ((ts.isTypeReferenceNode(node) || ts.isImportTypeNode(node))) {
@@ -1355,13 +1346,23 @@ class FaceAnalyzer {
             && this.registrationForFile(declaration.getSourceFile().fileName) !== undefined) {
             const imported = this.publicRemoteType(resolved, node)
             imports.set(imported.symbol, imported)
-            return
           }
         }
       }
       ts.forEachChild(node, visit)
     }
     visit(authoredType)
+    if (rootSymbol !== undefined) {
+      const imported = this.publicRemoteType(rootSymbol, authoredType)
+      return {
+        type,
+        codecType,
+        typeSymbol: `${imported.specifier}#${imported.name}`,
+        imports: [...imports.values()].sort((left, right) =>
+          left.specifier.localeCompare(right.specifier) || left.name.localeCompare(right.name)),
+      }
+    }
+    if (requireNamed) this.fail(authoredType, 'lookup and Context wire types must be named public types')
     return {
       type,
       codecType,
@@ -2810,7 +2811,7 @@ function stringLiteralValue(node: ts.Node | undefined): string | undefined {
 }
 
 function isRemoteSegment(value: string): boolean {
-  return value.length > 0 && !value.includes('/')
+  return isTypeRTRemoteSegment(value)
 }
 
 function expressionName(node: ts.Expression): string | undefined {
diff --git a/packages/typert/generator/src/emitter.ts b/packages/typert/generator/src/emitter.ts
index c8b9ab4195..bb39959606 100644
--- a/packages/typert/generator/src/emitter.ts
+++ b/packages/typert/generator/src/emitter.ts
@@ -414,8 +414,9 @@ export class FaceModelEmitter {
     invocation: InvocationModel,
     referenceNames: ReadonlyMap<SymbolId, string>,
   ): void {
-    const signature = `${invocation.method}: ${this.remoteFunctionType(invocation, referenceNames, false)}`
-    this.pushMappedRemoteSignature(lines, sourceMap, packageModel, invocation, signature, invocation.method.length)
+    const key = renderRemotePropertyName(invocation.method)
+    const signature = `${key}: ${this.remoteFunctionType(invocation, referenceNames, false)}`
+    this.pushMappedRemoteSignature(lines, sourceMap, packageModel, invocation, signature, key.length)
   }
 
   private pushMappedRemoteSignature(
@@ -914,6 +915,10 @@ function safeIdentifier(name: string): string {
   return `_${normalized}`
 }
 
+function renderRemotePropertyName(name: string): string {
+  return /^[$A-Z_a-z][$\w]*$/u.test(name) ? name : quote(name)
+}
+
 function quote(value: string): string {
   return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'").replaceAll('\n', '\\n').replaceAll('\r', '\\r')}'`
 }
diff --git a/packages/typert/generator/src/tsdown-plugin.ts b/packages/typert/generator/src/tsdown-plugin.ts
index 10cba60974..eca5ad47d2 100644
--- a/packages/typert/generator/src/tsdown-plugin.ts
+++ b/packages/typert/generator/src/tsdown-plugin.ts
@@ -6,7 +6,7 @@
  * @module @deepseek-ai/dsh-typert-generator/tsdown
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import ts from 'typescript'
 import { WorkspaceTypertGenerator } from './workspace.ts'
@@ -103,15 +103,24 @@ export function typertPlugin(pluginOptions: TypertPluginOptions = {}): TypertPlu
 function emitArtifacts(packageDir: string, artifacts: readonly WorkspaceEmitResult[]): void {
   const output = join(packageDir, 'lib')
   mkdirSync(output, { recursive: true })
+  let emittedRemote = false
   for (const artifact of artifacts) {
     writeFileSync(join(output, `typert.${artifact.face}.js`), artifact.js)
     writeFileSync(join(output, `typert.${artifact.face}.d.ts`), artifact.dts)
     if (artifact.remote !== undefined) {
+      emittedRemote = true
       writeFileSync(join(output, 'typert.remote-client.js'), artifact.remote.js)
       writeFileSync(join(output, 'typert.remote-client.d.ts'), artifact.remote.dts)
       writeFileSync(join(output, 'typert.remote-client.d.ts.map'), artifact.remote.dtsMap)
     }
   }
+  if (!emittedRemote && artifacts.some(artifact => artifact.face === 'host')) {
+    for (const file of [
+      'typert.remote-client.js',
+      'typert.remote-client.d.ts',
+      'typert.remote-client.d.ts.map',
+    ]) rmSync(join(output, file), { force: true })
+  }
 }
 
 function readManifest(packageDir: string): { name?: string; exports?: unknown } {
diff --git a/packages/typert/generator/src/workspace.ts b/packages/typert/generator/src/workspace.ts
index c79861a796..6327872166 100644
--- a/packages/typert/generator/src/workspace.ts
+++ b/packages/typert/generator/src/workspace.ts
@@ -90,7 +90,6 @@ export class WorkspaceTypertGenerator {
         throw new TypertAnalysisError(`typert(${artifact.face}): ${artifact.package} package files must include ${file}`)
       }
     }
-    if (artifact.remote === undefined) return
     const remoteExpected = {
       types: './lib/typert.remote-client.d.ts',
       default: './lib/typert.remote-client.js',
@@ -98,16 +97,25 @@ export class WorkspaceTypertGenerator {
     const remoteActual = manifest.exports !== null && typeof manifest.exports === 'object'
       ? (manifest.exports as Record<string, unknown>)['./remote']
       : undefined
+    const remoteFiles = [
+      'lib/typert.remote-client.js',
+      'lib/typert.remote-client.d.ts',
+      'lib/typert.remote-client.d.ts.map',
+    ]
+    if (artifact.remote === undefined) {
+      if (remoteActual !== undefined || remoteFiles.some(file => files.includes(file))) {
+        throw new TypertAnalysisError(
+          `typert(host): ${artifact.package} publishes Remote artifacts but has no Remote methods`,
+        )
+      }
+      return
+    }
     if (!sameExport(remoteActual, remoteExpected)) {
       throw new TypertAnalysisError(
         `typert(host): ${artifact.package} must export ./remote as ${JSON.stringify(remoteExpected)}`,
       )
     }
-    for (const file of [
-      'lib/typert.remote-client.js',
-      'lib/typert.remote-client.d.ts',
-      'lib/typert.remote-client.d.ts.map',
-    ]) {
+    for (const file of remoteFiles) {
       if (!files.includes(file)) {
         throw new TypertAnalysisError(`typert(host): ${artifact.package} package files must include ${file}`)
       }
diff --git a/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts b/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
index 91daea98c2..5347a6b77e 100644
--- a/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
+++ b/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
@@ -50,7 +50,13 @@ declare module '@deepseek-ai/dsh-type-meta' {
     context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
   ): void
 
-  export function RemoteContext(key: Extract<keyof TypeRTContextMap, string>):
+  export function Remote(exportName: string):
+  <This extends object, Args extends unknown[], Result>(
+    method: (this: This, ...args: Args) => Result,
+    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
+  ) => void
+
+  export function RemoteContext(key: Extract<keyof TypeRTContextMap, string>, exportName?: string):
   <This extends object, Args extends unknown[], Result>(
     method: (this: This, ...args: Args) => Result,
     context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
diff --git a/packages/typert/generator/tests/remote-model.spec.ts b/packages/typert/generator/tests/remote-model.spec.ts
index 268645ca73..4f4f3ea7cb 100644
--- a/packages/typert/generator/tests/remote-model.spec.ts
+++ b/packages/typert/generator/tests/remote-model.spec.ts
@@ -216,6 +216,91 @@ export type GenericResult = {
     expect(dispatch?.result.schema.safeParse({ kind: 'ship', value: { cancelled: true } }).success).toBe(false)
   })
 
+  it('imports public type arguments nested under a named generic boundary', () => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/types.ts', source => `${source}
+
+/** Generic Remote envelope. */
+export interface Box<Value> {
+  readonly value: Value
+}
+
+/** Payload reachable only as a generic argument. */
+export interface BoxPayload {
+  readonly count: number
+}
+`)
+    editFile(root, 'packages/remote/src/index.ts', source => source
+      .replace(
+        '  RenameGoalResult,\n',
+        '  RenameGoalResult,\n  Box,\n  BoxPayload,\n',
+      )
+      .replace(
+        '  rename(request: RenameGoalRequest): RenameGoalResult {\n    return { renamed: request.title.length > 0 }\n  }\n}',
+        `  rename(request: RenameGoalRequest): RenameGoalResult {
+    return { renamed: request.title.length > 0 }
+  }
+
+  @Remote
+  box(request: Box<BoxPayload>): Box<BoxPayload> {
+    return request
+  }
+}`,
+      ))
+
+    const [artifact] = new WorkspaceTypertGenerator(root).generate()
+    expect(artifact?.remote?.dts).toMatch(/import type \{ [^}]*Box[^}]*BoxPayload[^}]* \} from '@fixture\/remote\/types'/)
+    expect(artifact?.remote?.dts).toContain('box: (request: Box<BoxPayload>) => Promise<Box<BoxPayload>>')
+    assertRemoteConsumerTypechecks(artifact?.remote?.dts, artifact?.remote?.dtsMap, root)
+  })
+
+  it('quotes aliased methods in generated namespace interfaces', () => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/index.ts', source => source.replace(
+      '  rename(request: RenameGoalRequest): RenameGoalResult {\n    return { renamed: request.title.length > 0 }\n  }\n}',
+      `  rename(request: RenameGoalRequest): RenameGoalResult {
+    return { renamed: request.title.length > 0 }
+  }
+
+  @Remote('create-goal')
+  createAlias(request: CreateGoalRequest): CreateGoalResult {
+    return { ref: request.title }
+  }
+}`,
+    ))
+
+    const [artifact] = new WorkspaceTypertGenerator(root).generate()
+    expect(artifact?.remote?.dts).toContain("'create-goal': (request: CreateGoalRequest) => Promise<CreateGoalResult>")
+    assertRemoteConsumerTypechecks(artifact?.remote?.dts, artifact?.remote?.dtsMap, root)
+  })
+
+  it.each(['create#v2', 'create goal'])('rejects untransportable Remote alias %s', (alias) => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/index.ts', source => source.replace(
+      '  @Remote\n  async create(',
+      `  @Remote('${alias}')\n  async create(`,
+    ))
+
+    expect(() => analyzeRemote(root, false)).toThrow(/RPC endpoint segment characters/)
+  })
+
+  it('rejects a Remote export after its last Remote method is removed', () => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/index.ts', source => source
+      .replace('  @Remote\n', '')
+      .replace("  @RemoteContext('agent')\n", ''))
+    editFile(root, 'packages/remote/src/types.ts', source => `${source}
+
+/** @typert schema */
+export interface RemainingSchema {
+  readonly value: string
+}
+`)
+
+    expect(() => new WorkspaceTypertGenerator(root).generate())
+      .toThrow('publishes Remote artifacts but has no Remote methods')
+  })
+
   it.each([
     {
       name: 'missing binding',
@@ -429,9 +514,9 @@ function remotePackage(root: string): {
   return packageModel
 }
 
-function copyFixture(): string {
+function copyFixture(sourceRoot = fixtureRoot): string {
   const root = mkdtempSync(join(tmpdir(), 'dsh-typert-remote-model-'))
-  cpSync(fixtureRoot, root, { recursive: true })
+  cpSync(sourceRoot, root, { recursive: true })
   temporaryRoots.push(root)
   return root
 }
@@ -444,10 +529,14 @@ function editFile(root: string, relativePath: string, edit: (source: string) =>
   writeFileSync(path, result)
 }
 
-function assertRemoteConsumerTypechecks(dts: string | undefined, dtsMap: string | undefined): void {
+function assertRemoteConsumerTypechecks(
+  dts: string | undefined,
+  dtsMap: string | undefined,
+  sourceRoot = fixtureRoot,
+): void {
   if (dts === undefined) throw new Error('Remote fixture emitted no Host-for-Client declaration')
   if (dtsMap === undefined) throw new Error('Remote fixture emitted no Host-for-Client declaration map')
-  const consumerRoot = copyFixture()
+  const consumerRoot = copyFixture(sourceRoot)
   const declarationPath = join(consumerRoot, 'packages/remote/lib/typert.remote-client.d.ts')
   const declarationMapPath = `${declarationPath}.map`
   const consumerPath = join(consumerRoot, 'consumer.ts')
diff --git a/packages/typert/generator/tests/tsdown-plugin.spec.ts b/packages/typert/generator/tests/tsdown-plugin.spec.ts
index 106b8950ff..556e96045d 100644
--- a/packages/typert/generator/tests/tsdown-plugin.spec.ts
+++ b/packages/typert/generator/tests/tsdown-plugin.spec.ts
@@ -3,8 +3,9 @@ import { mkdir } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { WorkspaceEmitResult } from '../src/workspace.ts'
 
-const generated = vi.hoisted(() => vi.fn(() => [
+const generated = vi.hoisted(() => vi.fn<() => WorkspaceEmitResult[]>(() => [
   {
     package: '@deepseek-ai/dsh-tools',
     packageRoot: 'packages/core/tools',
@@ -141,6 +142,36 @@ describe('typertPlugin', () => {
       .toBe('{"version":3}\n')
   })
 
+  it('removes stale Remote artifacts from a Host package without Remote output', async () => {
+    const root = await workspace()
+    const output = await packageOutput(root, 'tools', {
+      name: '@deepseek-ai/dsh-tools',
+      exports: { './typert': './lib/typert.host.js' },
+    })
+    const packageLib = join(root, 'packages', 'tools', 'lib')
+    for (const file of [
+      'typert.remote-client.js',
+      'typert.remote-client.d.ts',
+      'typert.remote-client.d.ts.map',
+    ]) writeFileSync(join(packageLib, file), 'stale\n')
+    generated.mockReturnValueOnce([{
+      package: '@deepseek-ai/dsh-tools',
+      packageRoot: 'packages/core/tools',
+      face: 'host',
+      exports: [],
+      js: 'export const host = true\n',
+      dts: 'export declare const host: true\n',
+    }])
+
+    typertPlugin().writeBundle({ dir: output })
+
+    for (const file of [
+      'typert.remote-client.js',
+      'typert.remote-client.d.ts',
+      'typert.remote-client.d.ts.map',
+    ]) expect(existsSync(join(packageLib, file))).toBe(false)
+  })
+
   it('emits every explicit workspace contributor once from a host-only prepass', async () => {
     const root = await workspace()
     const trigger = await packageOutput(root, 'generator', { name: '@deepseek-ai/dsh-typert-generator' })
diff --git a/packages/typert/generator/tsconfig.json b/packages/typert/generator/tsconfig.json
index 9966c8ca8a..311dfa4b6d 100644
--- a/packages/typert/generator/tsconfig.json
+++ b/packages/typert/generator/tsconfig.json
@@ -16,6 +16,9 @@
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../type-meta"
     }
   ]
 }
diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
index d04f38cde5..7a097b8635 100644
--- a/packages/typert/registry/src/service.ts
+++ b/packages/typert/registry/src/service.ts
@@ -7,6 +7,7 @@
 
 import { Context, Service } from 'cordis'
 import { z } from 'zod'
+import { isTypeRTRemoteSegment } from '@deepseek-ai/dsh-type-meta'
 import type {
   InvocationDescriptor,
   TypeRTClientContextBinder,
@@ -600,8 +601,9 @@ function validateCodec(codec: InvocationDescriptor['result'], subject: string):
 }
 
 function validateWireName(subject: string, value: string): void {
-  validateSegment(subject, value)
-  if (value.includes('/')) throw new Error(`typert: invalid ${subject} "${value}" — must not contain "/"`)
+  if (!isTypeRTRemoteSegment(value)) {
+    throw new Error(`typert: invalid ${subject} "${value}" — must contain only RPC endpoint segment characters`)
+  }
 }
 
 function validateSegment(subject: string, value: string): void {
diff --git a/packages/typert/registry/tests/typert.spec.ts b/packages/typert/registry/tests/typert.spec.ts
index 5603ce8954..6661cbeeb4 100644
--- a/packages/typert/registry/tests/typert.spec.ts
+++ b/packages/typert/registry/tests/typert.spec.ts
@@ -247,6 +247,14 @@ describe('TypertRegistry', () => {
     })).toThrow('endpoint "goals/create" is already registered')
   })
 
+  it.each(['create#v2', 'create goal'])('rejects untransportable invocation method %s', async (method) => {
+    const ctx = await makeCtx()
+    expect(() => ctx.typert.remotes.register({
+      package: '@fixture/invalid-endpoint',
+      descriptors: [{ ...invocation(), method }],
+    })).toThrow('RPC endpoint segment characters')
+  })
+
   it('mounts Remote contributions in the calling fiber and withdraws them exactly', async () => {
     const ctx = await makeCtx()
     const descriptor = invocation()
diff --git a/packages/typert/type-meta/src/index.ts b/packages/typert/type-meta/src/index.ts
index 4d4457b5be..67a4169f96 100644
--- a/packages/typert/type-meta/src/index.ts
+++ b/packages/typert/type-meta/src/index.ts
@@ -7,6 +7,17 @@
 import { Service, type Context } from 'cordis'
 import type { TypeRTContextMap } from './types.ts'
 
+const TYPERT_REMOTE_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
+
+/**
+ * Test one generated Remote name against the Connection endpoint grammar.
+ * @param value - namespace, method, lookup, or Context segment.
+ * @returns whether the value can cross the shared RPC carrier unchanged.
+ */
+export function isTypeRTRemoteSegment(value: string): boolean {
+  return TYPERT_REMOTE_SEGMENT_PATTERN.test(value)
+}
+
 export type {
   InvocationDescriptor,
   InvocationParameterDescriptor,
@@ -236,7 +247,7 @@ function sameInvocation(left: RemoteInvocationMarker, right: RemoteInvocationMar
 }
 
 function validateName(subject: string, value: string): void {
-  if (value.length === 0 || value.includes('/')) {
-    throw new TypeError(`type-meta: ${subject} must be nonempty and must not contain "/"`)
+  if (!isTypeRTRemoteSegment(value)) {
+    throw new TypeError(`type-meta: ${subject} must contain only RPC endpoint segment characters`)
   }
 }
diff --git a/packages/typert/type-meta/tests/type-meta.spec.ts b/packages/typert/type-meta/tests/type-meta.spec.ts
index 8a2a4372ce..757488024d 100644
--- a/packages/typert/type-meta/tests/type-meta.spec.ts
+++ b/packages/typert/type-meta/tests/type-meta.spec.ts
@@ -162,6 +162,8 @@ describe('type-meta Remote declarations', () => {
     const method: (this: object) => void = function (this: object): void {}
     expect(() => { (Remote as unknown as (value: typeof method) => void)(method) }).toThrow('context is missing')
     expect(() => Remote('bad/name')).toThrow('export name')
+    expect(() => Remote('bad#name')).toThrow('export name')
+    expect(() => Remote('bad name')).toThrow('export name')
     expect(() => RemoteContext('' as 'metaFixture')).toThrow('Context key')
     expect(() => RemoteContext('metaFixture', 'bad/name')).toThrow('export name')
 
@@ -203,6 +205,7 @@ describe('type-meta Remote declarations', () => {
   it('rejects ambiguous binding names', () => {
     expect(() => bindTypeRTGateway({}, '')).toThrow('service key')
     expect(() => bindTypeRTGateway({}, 'goals', { namespace: 'api/goals' })).toThrow('namespace')
+    expect(() => bindTypeRTGateway({}, 'goals', { namespace: 'api goals' })).toThrow('namespace')
   })
 })
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 79d38a43cd..d6889328eb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -6172,6 +6172,9 @@ importers:
 
   packages/typert/generator:
     dependencies:
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../type-meta
       '@jridgewell/gen-mapping':
         specifier: ^0.3.13
         version: 0.3.13

From 0ad58850155b9eab5fd1f6c000b09f28f1bb0f03 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 11:13:19 +0800
Subject: [PATCH 133/516] fix(typert): keep generator bootstrap self-contained

---
 packages/typert/generator/package.json    | 1 -
 packages/typert/generator/src/analyzer.ts | 3 +--
 packages/typert/generator/tsconfig.json   | 3 ---
 pnpm-lock.yaml                            | 3 ---
 4 files changed, 1 insertion(+), 9 deletions(-)

diff --git a/packages/typert/generator/package.json b/packages/typert/generator/package.json
index eed553ebed..5ffb933214 100644
--- a/packages/typert/generator/package.json
+++ b/packages/typert/generator/package.json
@@ -30,7 +30,6 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
-    "@deepseek-ai/dsh-type-meta": "workspace:^",
     "@jridgewell/gen-mapping": "^0.3.13",
     "typescript": "^6.0.3"
   },
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index 5e26245171..16c30e8bc5 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -8,7 +8,6 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import { dirname, extname, join, relative, resolve, sep } from 'node:path'
 import ts from 'typescript'
-import { isTypeRTRemoteSegment } from '@deepseek-ai/dsh-type-meta'
 import type {
   CrossFaceLink,
   DocumentationModel,
@@ -2811,7 +2810,7 @@ function stringLiteralValue(node: ts.Node | undefined): string | undefined {
 }
 
 function isRemoteSegment(value: string): boolean {
-  return isTypeRTRemoteSegment(value)
+  return /^[A-Za-z0-9_$.-]+$/.test(value)
 }
 
 function expressionName(node: ts.Expression): string | undefined {
diff --git a/packages/typert/generator/tsconfig.json b/packages/typert/generator/tsconfig.json
index 311dfa4b6d..9966c8ca8a 100644
--- a/packages/typert/generator/tsconfig.json
+++ b/packages/typert/generator/tsconfig.json
@@ -16,9 +16,6 @@
     },
     {
       "path": "../../support/invariants"
-    },
-    {
-      "path": "../type-meta"
     }
   ]
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d6889328eb..79d38a43cd 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -6172,9 +6172,6 @@ importers:
 
   packages/typert/generator:
     dependencies:
-      '@deepseek-ai/dsh-type-meta':
-        specifier: workspace:^
-        version: link:../type-meta
       '@jridgewell/gen-mapping':
         specifier: ^0.3.13
         version: 0.3.13

From 5ea631194910153c5f89f3eb7a100c012ff72288 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 11:22:52 +0800
Subject: [PATCH 134/516] test(api-gateway): cover client mount rollback

---
 .../host/api-gateway/tests/client.spec.ts     | 48 ++++++++++++++-----
 1 file changed, 36 insertions(+), 12 deletions(-)

diff --git a/packages/host/api-gateway/tests/client.spec.ts b/packages/host/api-gateway/tests/client.spec.ts
index 28aa848fcd..5c2c427605 100644
--- a/packages/host/api-gateway/tests/client.spec.ts
+++ b/packages/host/api-gateway/tests/client.spec.ts
@@ -258,6 +258,13 @@ describe('Client TypeRT API', () => {
       package: '@fixture/service-method-conflict',
       descriptors: [{ ...context, id: '@fixture/goals#goals/remove', method: 'remove' }],
     })).toThrow('conflicts with its namespace service')
+    const scopedService = ctx.get('goals') as unknown as object
+    Object.defineProperty(scopedService, 'custom', { configurable: true, value: () => undefined })
+    expect(() => ctx.api.mount({
+      package: '@fixture/service-own-property-conflict',
+      descriptors: [{ ...direct, id: '@fixture/goals#goals/custom', method: 'custom' }],
+    })).toThrow('conflicts with its namespace service')
+    Reflect.deleteProperty(scopedService, 'custom')
     await disposeScoped()
 
     expect(() => ctx.api.mount({
@@ -281,20 +288,37 @@ describe('Client TypeRT API', () => {
 
   it('rolls back direct projection when scoped installation fails', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
-    const descriptor: InvocationDescriptor = {
-      ...directDescriptor(),
-      id: '@fixture/goals#fresh/remove',
-      namespace: 'fresh',
-      method: 'remove',
+    const disposeScoped = ctx.api.mount({
+      package: '@fixture/scoped-base',
+      descriptors: [contextDescriptor()],
+    })
+    const defineProperty = Object.defineProperty
+    let createDefinitions = 0
+    const definePropertySpy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      // The direct projection defines `create` first; fail the following scoped projection.
+      if (key === 'create' && ++createDefinitions === 2) throw new Error('simulated scoped installation failure')
+      return defineProperty(target, key, attributes)
+    })
+
+    try {
+      expect(() => ctx.api.mount({
+        package: '@fixture/failing-install',
+        descriptors: [directDescriptor()],
+      })).toThrow('simulated scoped installation failure')
+    } finally {
+      definePropertySpy.mockRestore()
     }
 
-    for (const packageName of ['@fixture/first-attempt', '@fixture/second-attempt']) {
-      expect(() => ctx.api.mount({ package: packageName, descriptors: [descriptor] }))
-        .toThrow('conflicts with its namespace service')
-      expect((ctx.api as unknown as Record<string, unknown>).fresh).toBeUndefined()
-      expect(ctx.get('fresh')).toBeUndefined()
-      expect(ctx.typert.remotes.list()).toEqual([])
-    }
+    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect(ctx.get('goals') !== undefined).toBe(true)
+    expect(ctx.typert.remotes.list()).toHaveLength(1)
+
+    const disposeRetry = ctx.api.mount({
+      package: '@fixture/retry',
+      descriptors: [directDescriptor()],
+    })
+    await disposeRetry()
+    await disposeScoped()
   })
 
   it('rejects weak parameter and Context codecs plus malformed scope projections', async () => {

From 56af59b41d8a8459d36a8d3e18aa6b455cbf03be Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 11:52:24 +0800
Subject: [PATCH 135/516] fix(typert): keep client registry bundle pure

---
 packages/typert/registry/src/service.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
index 7a097b8635..2f85138edd 100644
--- a/packages/typert/registry/src/service.ts
+++ b/packages/typert/registry/src/service.ts
@@ -7,7 +7,6 @@
 
 import { Context, Service } from 'cordis'
 import { z } from 'zod'
-import { isTypeRTRemoteSegment } from '@deepseek-ai/dsh-type-meta'
 import type {
   InvocationDescriptor,
   TypeRTClientContextBinder,
@@ -601,7 +600,7 @@ function validateCodec(codec: InvocationDescriptor['result'], subject: string):
 }
 
 function validateWireName(subject: string, value: string): void {
-  if (!isTypeRTRemoteSegment(value)) {
+  if (!/^[A-Za-z0-9_$.-]+$/.test(value)) {
     throw new Error(`typert: invalid ${subject} "${value}" — must contain only RPC endpoint segment characters`)
   }
 }

From eca3090dfaecfd67ff79e4679f1cf90fa295eccb Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 12:11:32 +0800
Subject: [PATCH 136/516] fix: docs

---
 docs/config-catalog.md | 2 --
 docs/module-graph.md   | 4 ++--
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 41c9c98515..77baad512d 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2565,8 +2565,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/timeout/timeout-policy/src/index.ts`](../packages/timeout/timeout-policy/src/index.ts))
 - `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/ui/tool-ask-user/src/index.ts`](../packages/ui/tool-ask-user/src/index.ts))
 - `@deepseek-ai/dsh-tool-subagent-control` — requires `tools` · `subagents` ([`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts))
-- `@deepseek-ai/dsh-tool-todo` — requires `tools` ([`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts))
-- `@deepseek-ai/dsh-typert-registry` ([`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts))
 - `@deepseek-ai/dsh-user-interaction` ([`packages/ui/user-interaction/src/index.ts`](../packages/ui/user-interaction/src/index.ts))
 - `@deepseek-ai/dsh-workspace` — requires `storageDomain` · `sessionPersistence` ([`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts))
 
diff --git a/docs/module-graph.md b/docs/module-graph.md
index f659e61206..ac46e968b3 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -1132,8 +1132,8 @@ flowchart TD
   pkg_client_ui_command --> pkg_client_ui_slash
   pkg_client_ui_command --> pkg_client_ui_slots
   pkg_client_ui_command --> pkg_invariants
-  pkg_client_ui_goal --> pkg_client_connection
   pkg_client_ui_goal --> pkg_client_locale
+  pkg_client_ui_goal --> pkg_client_remotes
   pkg_client_ui_goal --> pkg_client_runtime
   pkg_client_ui_goal --> pkg_client_ui_conversation
   pkg_client_ui_goal --> pkg_client_ui_primitives
@@ -1383,7 +1383,7 @@ flowchart TD
 | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-locale`](../packages/client/locale), [`client-remotes`](../packages/client/remotes), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
 | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
 | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |

From e28ac506edf9ea5c5c72bdba20fea1e16f708728 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 12:21:41 +0800
Subject: [PATCH 137/516] perf(api-gateway): cache SRC endpoint claims

---
 ...08-02-typert-remote-method-calls.i18n.yaml |  4 +-
 .../2026-08-02-typert-remote-method-calls.md  |  4 +-
 ...026-08-02-typert-remote-method-calls.zh.md |  4 +-
 docs/event-producer-consumer.md               |  1 +
 packages/host/api-gateway/src/index.ts        | 21 ++++++--
 .../host/api-gateway/tests/gateway.spec.ts    | 49 +++++++++++++++++++
 6 files changed, 73 insertions(+), 10 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 2400e39519..02e6c428ff 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: 13b407d580c6042a71234e55cdb61225910f0e48
-2026-08-02-typert-remote-method-calls.zh.md: 434cf4765d2206f3c6f99b67c156b9508d70f313
+2026-08-02-typert-remote-method-calls.md: ddc93b4fc672f320b4e3dc3e11586d92604e6aa4
+2026-08-02-typert-remote-method-calls.zh.md: 808c7d54bff19d9a4e9cf924769df1d405d997b5
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index 13b407d580..ddc93b4fc6 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -158,7 +158,7 @@ ctx.typert.lookups   wire ID 到 Host 活对象的 provider
 ctx.typert.contexts  Host Context resolver 与 Client Context binder
 ```
 
-Every registration returns a disposer owned by the caller's Cordis fiber. Client contribution mounting registers the descriptor set and concrete methods as one owned operation. The Host Gateway resolves descriptors, Services, and providers from current state for every claim and invocation instead of retaining endpoint registrations. Removing a strict definition, Service, or provider therefore makes the corresponding call unavailable without leaving a stale live object.
+Every registration returns a disposer owned by the caller's Cordis fiber. Client contribution mounting registers the descriptor set and concrete methods as one owned operation. The Host Gateway caches only the set of SRC-owned endpoint names and discards it whenever the Cordis Service set changes; it retains no descriptor, Service, or provider. Invocation resolves all live objects from current state, so removing a strict definition, Service, or provider makes the corresponding call unavailable without leaving a stale live object.
 
 The lookup registry retains the stable wire declaration after its live resolver unloads. SRC parsing continues to classify the parameter as a lookup, while invocation fails with `lookup-unavailable`; it never reclassifies the incoming ID as an ordinary JSON business object. Re-registering the same key with different parameter, wire, or canonical type symbols fails for the lifetime of that TypeRT Service.
 
@@ -355,7 +355,7 @@ CI and releases use LIB. Moving all repository coverage to LIB is separate follo
 
 ## Host Gateway resolution
 
-The Host Gateway registers one `/api` interceptor with Connection and does not maintain a second endpoint registry. Its ownership matcher resolves each endpoint from the current TypeRT local registry or scans current Cordis Services for a matching `typertGateway` binding and SRC Remote marker. TypeRT definitions and business Services may therefore arrive in either order.
+The Host Gateway registers one `/api` interceptor with Connection and does not maintain a second endpoint registry. Its ownership matcher checks the current TypeRT local registry first, then consults an invalidation-aware set populated by scanning current Cordis Services for `typertGateway` bindings and SRC Remote markers. A Cordis Service change discards the set, so TypeRT definitions and business Services may arrive in either order without making legacy `/api` traffic rescan every Service on each request or letting arbitrary request paths grow the cache.
 
 Invocation resolves the descriptor, receiver, lookup providers, and Context provider again from current state. A current strict descriptor takes precedence over SRC. After a strict endpoint has appeared, `TypeRTLocalRegistry.hasSeen()` keeps it owned when that descriptor is withdrawn and forbids SRC fallback for the remainder of the registry lifetime; re-registering the strict descriptor restores calls. Removing a Service or provider makes invocation fail explicitly, and the Gateway neither retains invalid objects nor invokes a method with a raw lookup ID.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 434cf4765d..808c7d54bf 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -158,7 +158,7 @@ ctx.typert.lookups   wire ID 到 Host 活对象的 provider
 ctx.typert.contexts  Host Context resolver 与 Client Context binder
 ```
 
-每次注册都返回由调用方 Cordis fiber 持有的 disposer。挂载 Client contribution 时，descriptor 集与具体方法会作为一项有明确所有者的操作统一注册。Host Gateway 每次认领和调用时都从当前状态解析 descriptor、Service 与提供方，不保留 endpoint 注册。因此移除 strict definition、Service 或提供方会使相应调用不可用，且不会留下陈旧的活对象。
+每次注册都返回由调用方 Cordis fiber 持有的 disposer。挂载 Client contribution 时，descriptor 集与具体方法会作为一项有明确所有者的操作统一注册。Host Gateway 只缓存 SRC 所认领的 endpoint 名称集合，并在 Cordis Service 集合发生变化时整体丢弃该集合；它不保留 descriptor、Service 或提供方。调用时会从当前状态解析所有活对象，因此移除 strict definition、Service 或提供方会使相应调用不可用，且不会留下陈旧的活对象。
 
 lookup 注册表会在活 resolver 卸载后保留稳定的 wire 声明。SRC 解析仍会把该参数归类为 lookup，而调用会以 `lookup-unavailable` 失败；系统绝不会把传入的 ID 重新归类为普通 JSON 业务对象。在同一个 TypeRT Service 的生命周期内，以不同参数、wire 或规范类型 symbol 重新注册同一 key 会直接失败。
 
@@ -355,7 +355,7 @@ CI 和发布运行 LIB。全仓 coverage 全部切换到 LIB 是独立后续工
 
 ## Host Gateway 解析
 
-Host Gateway 向 Connection 注册一个 `/api` interceptor，不维护第二份 endpoint 注册表。ownership matcher 会从当前 TypeRT local 注册表解析各 endpoint，或扫描当前 Cordis Service，查找匹配的 `typertGateway` binding 与 SRC Remote 标记。因此 TypeRT definition 与业务 Service 可以按任意顺序到达。
+Host Gateway 向 Connection 注册一个 `/api` interceptor，不维护第二份 endpoint 注册表。ownership matcher 会先检查当前 TypeRT local 注册表，再查询一份可失效的集合；该集合通过扫描当前 Cordis Service 中的 `typertGateway` binding 与 SRC Remote 标记生成。Cordis Service 发生变化时会整体丢弃该集合，因此 TypeRT definition 与业务 Service 可以按任意顺序到达，同时既不会让旧 API Proxy 的 `/api` 流量在每次请求时重新扫描所有 Service，也不会因任意请求路径而扩大缓存。
 
 每次调用都会重新从当前状态解析 descriptor、receiver、lookup 提供方与 Context 提供方。当前 strict descriptor 优先于 SRC。strict endpoint 一旦出现，即使随后撤回对应 descriptor，`TypeRTLocalRegistry.hasSeen()` 仍会在注册表剩余生命周期内保持对它的认领并禁止回退 SRC；重新注册 strict descriptor 即可恢复调用。移除 Service 或提供方会让调用明确失败；Gateway 既不保留失效对象，也不会以原始 lookup ID 调用方法。
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index f5b3a0b99a..34f4d37ffd 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -66,6 +66,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `credentials/changed` | `runtime` (`emit`) | `ui-models` |
 | `internal/dispatch` | - | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
 | `internal/plugin` | - | `hmr`, `loader`, `modules`, `webserver` |
+| `internal/service` | - | `api-gateway` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
 | `locale/change` | `locale` (`emit`) | `locale` |
 | `models/changed` | `runtime` (`emit`) | `ui-models` |
diff --git a/packages/host/api-gateway/src/index.ts b/packages/host/api-gateway/src/index.ts
index c4a61cef8d..7dd2410873 100644
--- a/packages/host/api-gateway/src/index.ts
+++ b/packages/host/api-gateway/src/index.ts
@@ -76,12 +76,17 @@ export class TypertGatewayError extends Error {
 export class TypertGatewayService extends Service implements TypertGateway {
   static inject = ['typert']
 
+  private srcClaims: ReadonlySet<string> | undefined
+
   /**
    * Register the Gateway against the active TypeRT registry.
    * @param ctx - owning Host Context with TypeRT registry access.
    */
   constructor(ctx: Context) {
     super(ctx, 'typertGateway')
+    ctx.on('internal/service', () => {
+      this.srcClaims = undefined
+    })
     ctx.inject(['connection'], (connectionCtx) => {
       connectionCtx.connection.rpc.intercept(
         '/api',
@@ -95,18 +100,26 @@ export class TypertGatewayService extends Service implements TypertGateway {
   private claimsEndpoint(endpoint: string): boolean {
     const segments = endpoint.split('/')
     if (segments.length !== 2 || segments[0] === '' || segments[1] === '') return false
-    const [namespace, method] = segments as [string, string]
     if (this.ctx.typert.local.get(endpoint) !== undefined || this.ctx.typert.local.hasSeen(endpoint)) return true
+    this.srcClaims ??= this.collectSrcClaims()
+    return this.srcClaims.has(endpoint)
+  }
+
+  private collectSrcClaims(): ReadonlySet<string> {
+    const claims = new Set<string>()
     for (const [serviceKey, definition] of Object.entries(this.ctx.reflect.props)) {
       if (definition.type !== 'service') continue
       const receiver = this.ctx.get(serviceKey) as unknown
       if (!isObject(receiver)) continue
       const original = originalOf(receiver)
       const binding = Reflect.get(original, 'typertGateway') as unknown
-      if (!isObject(binding) || Reflect.get(binding, 'namespace') !== namespace) continue
-      if (remoteMethods(original).some(candidate => (candidate.exportName ?? candidate.method) === method)) return true
+      if (!isObject(binding) || typeof Reflect.get(binding, 'namespace') !== 'string') continue
+      const namespace = Reflect.get(binding, 'namespace') as string
+      for (const candidate of remoteMethods(original)) {
+        claims.add(endpointOf(namespace, candidate.exportName ?? candidate.method))
+      }
     }
-    return false
+    return claims
   }
 
   /**
diff --git a/packages/host/api-gateway/tests/gateway.spec.ts b/packages/host/api-gateway/tests/gateway.spec.ts
index 6558a7ca47..aebe23da57 100644
--- a/packages/host/api-gateway/tests/gateway.spec.ts
+++ b/packages/host/api-gateway/tests/gateway.spec.ts
@@ -314,6 +314,25 @@ class NoBindingService extends Service {
   }
 }
 
+class ObservedClaimService extends Service {
+  private readonly binding = bindTypeRTGateway(this, 'observedClaim', { namespace: 'observed-claim' })
+  bindingReads = 0
+
+  constructor(ctx: Context) {
+    super(ctx, 'observedClaim')
+  }
+
+  get typertGateway() {
+    this.bindingReads += 1
+    return this.binding
+  }
+
+  @Remote
+  run(value: string): string {
+    return value
+  }
+}
+
 class MissingMethodService extends Service {
   readonly typertGateway = bindTypeRTGateway(this, 'missingMethod', { namespace: 'missing-method' })
 
@@ -949,6 +968,36 @@ describe('TypertGatewayService', () => {
     expect(connection.handler).toBeUndefined()
   })
 
+  it('caches SRC ownership until the Cordis Service set changes', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    await ctx.plugin(FakeConnectionService)
+    await ctx.plugin(TypertGatewayService)
+    const observedFiber = ctx.plugin(ObservedClaimService)
+    await observedFiber
+    const connection = rawConnection(ctx)
+    const observed = ctx.get('observedClaim') as unknown as ObservedClaimService & {
+      [symbols.original]?: ObservedClaimService
+    }
+    const service = observed[symbols.original] ?? observed
+
+    expect(connection.matches?.('legacy/list')).toBe(false)
+    expect(connection.matches?.('legacy/list')).toBe(false)
+    expect(service.bindingReads).toBe(1)
+    expect(connection.matches?.('observed-claim/run')).toBe(true)
+    expect(connection.matches?.('observed-claim/run')).toBe(true)
+    expect(service.bindingReads).toBe(1)
+
+    const unrelatedFiber = ctx.plugin(NoBindingService)
+    await unrelatedFiber
+    expect(connection.matches?.('legacy/list')).toBe(false)
+    expect(service.bindingReads).toBe(2)
+
+    await observedFiber.dispose()
+    expect(connection.matches?.('observed-claim/run')).toBe(false)
+    await unrelatedFiber.dispose()
+  })
+
   it('dispatches claimed invocations through /api and leaves unclaimed endpoints to its fallback', async () => {
     const ctx = new Context().extend({ fixtureScope: 'http-caller' })
     const routes: WebRoute[] = []

From 286a8b168e1e4e536c75800d0b9d2523213f7991 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 12:53:16 +0800
Subject: [PATCH 138/516] fix(connection): route fixture calls through remote
 semantics

---
 .../client/connection/src/client/fixture.ts   | 266 +++++++++++++-----
 .../client/connection/src/client/index.ts     |   7 +-
 packages/client/connection/src/client/rpc.ts  |  12 -
 .../connection/tests/client-apply.spec.ts     |  32 ++-
 4 files changed, 234 insertions(+), 83 deletions(-)

diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index e13c0a19f6..1a9841aece 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -36,6 +36,7 @@ import type {
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { AbstractApiClient, RpcId, SESSION_SEARCH_RESULT_LIMIT } from './api.ts'
 import { randomUuid } from './random-uuid.ts'
+import type { ClientConnectionRpc } from '../rpc.ts'
 
 /** The fake carrier mints like a real one (business code never mints). */
 function rpcRequest<P>(payload: P): RpcRequest<P> {
@@ -1329,6 +1330,16 @@ class FxInbox<F> implements StreamConn<F> {
  * @returns an ApiProxy backed entirely by in-memory state — no host process, no network.
  */
 export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
+  return createFixtureWorld(options).api
+}
+
+interface FixtureWorld {
+  readonly api: ApiProxy
+  readonly rpc: ClientConnectionRpc
+}
+
+/** Build the fixture's legacy API and Remote RPC faces over one state graph. */
+function createFixtureWorld(options: FixtureOptions): FixtureWorld {
   // The resident fixture sessions all carry history, so none of them is blank.
   const sessions: SessionSummary[] = options.empty ? [] : [
     { sessionId: sid('fx-alpha'), updatedAt: Date.now(), running: true, blank: false, cwd: '/tmp/fixture' },
@@ -1507,31 +1518,136 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
     return backscanGoal(log) as FxGoalProjection
   }
 
-  /** Shared CAS mutation path of the goal verbs (undefined next = invalid transition). */
-  const fxMutateGoal = (
-    request: RpcRequest<{ sessionId: SessionId; ref: { id: string; revision: number } }>,
-    ref: { id: string; revision: number },
+  type FxGoalRef = { id: string; revision: number }
+  type FxGoalView = FxGoalProjection['goal'] & {
+    roundsStarted: number
+    createdAt: number
+    updatedAt: number
+    activation: 'armed' | 'disarmed'
+  }
+
+  const goalFailure = <T>(message: string): RpcResult<T> => ({
+    ok: false,
+    error: { code: 'internal', message, details: {} },
+  })
+
+  const requireGoalSession = (id: SessionId): RpcResult<never> | undefined => (
+    summaryOf(id) === undefined
+      ? { ok: false, error: { code: 'session-not-found', message: `no session ${id}`, details: { sessionId: id } } }
+      : undefined
+  )
+
+  const goalView = (projection: FxGoalProjection): FxGoalView => ({
+    ...projection.goal,
+    roundsStarted: projection.roundsStarted,
+    createdAt: projection.createdAt,
+    updatedAt: projection.updatedAt,
+    activation: projection.goal.phase === 'active' ? 'armed' : 'disarmed',
+  })
+
+  /** Canonical fixture implementation of the generated Goal Remote contract. */
+  const goalRemotes = {
+    create(id: SessionId, request: { objective: string; maxGoalRounds?: number }): RpcResult<{ ref: FxGoalRef }> {
+      const missing = requireGoalSession(id)
+      if (missing !== undefined) return missing
+      const current = backscanGoal(logOf(id))
+      if (current !== null && current.goal.phase !== 'complete') {
+        return goalFailure(`goal "${current.goal.id}" already exists`)
+      }
+      const now = Date.now()
+      const projection = appendGoalChange(id, {
+        kind: 'goal/change', version: 1, operation: 'create',
+        goal: {
+          id: `fx-goal-${logOf(id).length}`,
+          revision: 1,
+          objective: request.objective,
+          phase: 'active',
+          maxGoalRounds: request.maxGoalRounds ?? 256,
+        },
+        roundsStarted: 0, createdAt: now, updatedAt: now,
+      })
+      return { ok: true, value: { ref: { id: projection.goal.id, revision: projection.goal.revision } } }
+    },
+    edit(id: SessionId, ref: FxGoalRef, request: { objective?: string; maxGoalRounds?: number }): RpcResult<FxGoalView> {
+      return mutateGoal(id, ref, current => ({
+        ...current.goal,
+        revision: current.goal.revision + 1,
+        ...request.objective === undefined ? {} : { objective: request.objective },
+        ...request.maxGoalRounds === undefined ? {} : { maxGoalRounds: request.maxGoalRounds },
+      }))
+    },
+    pause(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalView> {
+      return mutateGoal(id, ref, current => (
+        current.goal.phase === 'active'
+          ? { ...current.goal, revision: current.goal.revision + 1, phase: 'paused' }
+          : undefined
+      ))
+    },
+    resume(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalView> {
+      return mutateGoal(id, ref, current => (
+        current.goal.phase === 'paused' || current.goal.phase === 'blocked' || current.goal.phase === 'active'
+          ? { ...current.goal, revision: current.goal.revision + 1, phase: 'active' }
+          : undefined
+      ))
+    },
+    complete(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalView> {
+      return mutateGoal(id, ref, current => (
+        current.goal.phase === 'complete'
+          ? undefined
+          : { ...current.goal, revision: current.goal.revision + 1, phase: 'complete' }
+      ))
+    },
+    clear(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalRef> {
+      const missing = requireGoalSession(id)
+      if (missing !== undefined) return missing
+      const current = backscanGoal(logOf(id))
+      if (current === null || current.goal.id !== ref.id || current.goal.revision !== ref.revision) {
+        return goalFailure('stale or missing goal revision')
+      }
+      const tombstone = { id: current.goal.id, revision: current.goal.revision + 1 }
+      appendGoalChange(id, {
+        kind: 'goal/change', version: 1, operation: 'clear', cleared: tombstone, clearedAt: Date.now(),
+      })
+      return { ok: true, value: tombstone }
+    },
+  }
+
+  /** Shared CAS mutation path behind the canonical Remote verbs. */
+  function mutateGoal(
+    id: SessionId,
+    ref: FxGoalRef,
     next: (current: FxGoalProjection) => FxGoalProjection['goal'] | undefined,
-  ): Promise<RpcResponse<{ ref: { id: never; revision: number } }>> => {
-    const missing = requireSession(request)
+  ): RpcResult<FxGoalView> {
+    const missing = requireGoalSession(id)
     if (missing !== undefined) return missing
-    const id = request.payload.sessionId
     const current = backscanGoal(logOf(id))
     if (current === null || current.goal.id !== ref.id || current.goal.revision !== ref.revision) {
-      return err(request, { code: 'internal', message: 'stale or missing goal revision', details: { goalCode: 'GOAL_STALE_REVISION' } })
+      return goalFailure('stale or missing goal revision')
     }
     const goal = next(current)
     if (goal === undefined) {
-      return err(request, { code: 'internal', message: `invalid goal transition from "${current.goal.phase}"`, details: { goalCode: 'GOAL_INVALID_TRANSITION' } })
+      return goalFailure(`invalid goal transition from "${current.goal.phase}"`)
     }
     const projection = appendGoalChange(id, {
       kind: 'goal/change', version: 1,
       operation: goal.phase === current.goal.phase ? 'edit' : goal.phase === 'paused' ? 'pause' : goal.phase === 'active' ? 'resume' : 'complete',
       goal, roundsStarted: current.roundsStarted, createdAt: current.createdAt, updatedAt: Date.now(),
     })
-    return ok(request, { ref: { id: projection.goal.id as never, revision: projection.goal.revision } })
+    return { ok: true, value: goalView(projection) }
   }
 
+  const mapGoalResult = <T, U>(result: RpcResult<T>, map: (value: T) => U): RpcResult<U> => (
+    result.ok ? { ok: true, value: map(result.value) } : result
+  )
+
+  const goalRefResult = (result: RpcResult<FxGoalView>): RpcResult<{ ref: { id: never; revision: number } }> => (
+    mapGoalResult(result, view => ({ ref: { id: view.id as never, revision: view.revision } }))
+  )
+
+  const legacyGoalResponse = <P, T>(request: RpcRequest<P>, result: RpcResult<T>): Promise<RpcResponse<T>> => (
+    Promise.resolve({ rpcId: request.rpcId, result })
+  )
+
   /** At most one in-flight replay per session; cancel clears it. */
   const replays = new Map<SessionId, { timer: ReturnType<typeof setTimeout>; finish(aborted: boolean): void }>()
 
@@ -1777,7 +1893,7 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
     replays.set(id, { timer: setTimeout(tick, 80), finish })
   }
 
-  return {
+  const api: ApiProxy = {
     sessions: {
       list: request => ok(request, { items: [...sessions].sort((a, b) => b.updatedAt - a.updatedAt) }),
       search: (request, signal) => {
@@ -2334,60 +2450,44 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       },
     },
     goals: {
-      // Mutation-only mirror of the host handlers: each verb CAS-checks the
-      // projected current goal, appends the whole-value change (the mux
-      // stream and projection frame ride the shared append path), and
-      // acknowledges with the new ref only.
-      create: (request) => {
-        const missing = requireSession(request)
-        if (missing !== undefined) return missing
-        const id = request.payload.sessionId
-        const current = backscanGoal(logOf(id))
-        if (current !== null && current.goal.phase !== 'complete') {
-          return err(request, { code: 'internal', message: `goal "${current.goal.id}" already exists`, details: { goalCode: 'GOAL_ALREADY_EXISTS' } })
-        }
-        const projection = appendGoalChange(id, {
-          kind: 'goal/change', version: 1, operation: 'create',
-          goal: { id: `fx-goal-${logOf(id).length}`, revision: 1, objective: request.payload.objective, phase: 'active', maxGoalRounds: request.payload.maxGoalRounds ?? 256 },
-          roundsStarted: 0, createdAt: Date.now(), updatedAt: Date.now(),
-        })
-        return ok(request, { ref: { id: projection.goal.id as never, revision: projection.goal.revision } })
-      },
-      edit: request => fxMutateGoal(request, request.payload.ref, current => ({
-        ...current.goal,
-        revision: current.goal.revision + 1,
-        ...request.payload.objective === undefined ? {} : { objective: request.payload.objective },
-        ...request.payload.maxGoalRounds === undefined ? {} : { maxGoalRounds: request.payload.maxGoalRounds },
-      })),
-      pause: request => fxMutateGoal(request, request.payload.ref, current => (
-        current.goal.phase === 'active'
-          ? { ...current.goal, revision: current.goal.revision + 1, phase: 'paused' }
-          : undefined
-      )),
-      resume: request => fxMutateGoal(request, request.payload.ref, current => (
-        current.goal.phase === 'paused' || current.goal.phase === 'blocked' || current.goal.phase === 'active'
-          ? { ...current.goal, revision: current.goal.revision + 1, phase: 'active' }
-          : undefined
-      )),
-      complete: request => fxMutateGoal(request, request.payload.ref, current => (
-        current.goal.phase === 'complete'
-          ? undefined
-          : { ...current.goal, revision: current.goal.revision + 1, phase: 'complete' }
-      )),
-      clear: (request) => {
-        const missing = requireSession(request)
-        if (missing !== undefined) return missing
-        const id = request.payload.sessionId
-        const current = backscanGoal(logOf(id))
-        if (current === null || current.goal.id !== request.payload.ref.id || current.goal.revision !== request.payload.ref.revision) {
-          return err(request, { code: 'internal', message: 'stale or missing goal revision', details: { goalCode: 'GOAL_STALE_REVISION' } })
-        }
-        appendGoalChange(id, {
-          kind: 'goal/change', version: 1, operation: 'clear',
-          cleared: { id: current.goal.id, revision: current.goal.revision + 1 }, clearedAt: Date.now(),
-        })
-        return ok(request, { cleared: true as const })
-      },
+      // Compatibility face only: old API Proxy payloads and acknowledgements
+      // adapt to the canonical fixture Remote implementation above.
+      create: request => legacyGoalResponse(
+        request,
+        mapGoalResult(
+          goalRemotes.create(request.payload.sessionId, {
+            objective: request.payload.objective,
+            ...request.payload.maxGoalRounds === undefined ? {} : { maxGoalRounds: request.payload.maxGoalRounds },
+          }),
+          value => ({ ref: { id: value.ref.id as never, revision: value.ref.revision } }),
+        ),
+      ),
+      edit: request => legacyGoalResponse(
+        request,
+        goalRefResult(goalRemotes.edit(request.payload.sessionId, request.payload.ref, {
+          ...request.payload.objective === undefined ? {} : { objective: request.payload.objective },
+          ...request.payload.maxGoalRounds === undefined ? {} : { maxGoalRounds: request.payload.maxGoalRounds },
+        })),
+      ),
+      pause: request => legacyGoalResponse(
+        request,
+        goalRefResult(goalRemotes.pause(request.payload.sessionId, request.payload.ref)),
+      ),
+      resume: request => legacyGoalResponse(
+        request,
+        goalRefResult(goalRemotes.resume(request.payload.sessionId, request.payload.ref)),
+      ),
+      complete: request => legacyGoalResponse(
+        request,
+        goalRefResult(goalRemotes.complete(request.payload.sessionId, request.payload.ref)),
+      ),
+      clear: request => legacyGoalResponse(
+        request,
+        mapGoalResult(
+          goalRemotes.clear(request.payload.sessionId, request.payload.ref),
+          () => ({ cleared: true as const }),
+        ),
+      ),
     },
     events: {
       async *mux(_request, signal) {
@@ -2548,6 +2648,36 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       return Promise.resolve({ accepted: true })
     },
   }
+
+  const rpc: ClientConnectionRpc = {
+    call(channel, endpoint, payload) {
+      if (channel !== '/api') {
+        return Promise.reject(new Error(`fixture connection RPC channel ${JSON.stringify(channel)} is unavailable`))
+      }
+      const args = (payload as {
+        args: {
+          agentId: SessionId
+          ref?: { id: string; revision: number }
+          request?: { objective?: string; maxGoalRounds?: number }
+        }
+      }).args
+      const sessionId = args.agentId
+      switch (endpoint) {
+        case 'goals/create': return Promise.resolve(goalRemotes.create(sessionId, {
+          objective: args.request?.objective as string,
+          ...args.request?.maxGoalRounds === undefined ? {} : { maxGoalRounds: args.request.maxGoalRounds },
+        }))
+        case 'goals/edit': return Promise.resolve(goalRemotes.edit(sessionId, args.ref as FxGoalRef, args.request ?? {}))
+        case 'goals/pause': return Promise.resolve(goalRemotes.pause(sessionId, args.ref as FxGoalRef))
+        case 'goals/resume': return Promise.resolve(goalRemotes.resume(sessionId, args.ref as FxGoalRef))
+        case 'goals/complete': return Promise.resolve(goalRemotes.complete(sessionId, args.ref as FxGoalRef))
+        case 'goals/clear': return Promise.resolve(goalRemotes.clear(sessionId, args.ref as FxGoalRef))
+        default:
+          return Promise.reject(new Error(`fixture connection RPC endpoint ${JSON.stringify(endpoint)} is unavailable`))
+      }
+    },
+  }
+  return { api, rpc }
 }
 
 /**
@@ -2559,10 +2689,14 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
  */
 export class FixtureApiClient extends AbstractApiClient {
   private readonly api: ApiProxy
+  /** Generic Remote caller backed by the same in-memory state as the legacy fixture API. */
+  readonly rpc: ClientConnectionRpc
 
   constructor() {
     super()
-    this.api = createFixtureApi(fixtureOptionsFromLocation())
+    const world = createFixtureWorld(fixtureOptionsFromLocation())
+    this.api = world.api
+    this.rpc = world.rpc
   }
 
   protected doFetch(): Promise<Response> {
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index 521e54160e..c2a6668d46 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -8,7 +8,7 @@ import type { IApiClient } from './api.ts'
 import { ConnectionController, type ConnectionConfig, type ConnectionSinks, type ConnectionState } from './connection.ts'
 import { FixtureApiClient } from './fixture.ts'
 import { WebApiClient } from './web-api-client.ts'
-import { createUnavailableConnectionRpc, createWebConnectionRpc } from './rpc.ts'
+import { createWebConnectionRpc } from './rpc.ts'
 import { isLoopbackHostname } from '../loopback-hostname.ts'
 import type { ClientConnectionRpc } from '../rpc.ts'
 
@@ -74,8 +74,9 @@ export interface ConnectionHandle {
 export function apply(ctx: Context): void {
   const pageLocation = typeof location === 'undefined' ? undefined : location
   const fixture = pageLocation !== undefined && new URLSearchParams(pageLocation.search).has('fixture')
-  const api: IApiClient = fixture ? new FixtureApiClient() : new WebApiClient()
-  const rpc = fixture ? createUnavailableConnectionRpc() : createWebConnectionRpc()
+  const fixtureClient = fixture ? new FixtureApiClient() : undefined
+  const api: IApiClient = fixtureClient ?? new WebApiClient()
+  const rpc = fixtureClient?.rpc ?? createWebConnectionRpc()
   let started = false
   const handle: ConnectionHandle = {
     api,
diff --git a/packages/client/connection/src/client/rpc.ts b/packages/client/connection/src/client/rpc.ts
index 7883f2a9d3..f8bacb1553 100644
--- a/packages/client/connection/src/client/rpc.ts
+++ b/packages/client/connection/src/client/rpc.ts
@@ -48,18 +48,6 @@ export function createWebConnectionRpc(): ClientConnectionRpc {
   }
 }
 
-/**
- * Create the fixture-mode caller, where no Host Remote registry exists.
- * @returns caller that rejects every generic Remote invocation.
- */
-export function createUnavailableConnectionRpc(): ClientConnectionRpc {
-  return {
-    call(channel, endpoint) {
-      return Promise.reject(new Error(`connection RPC ${channel}/${endpoint} is unavailable in fixture mode`))
-    },
-  }
-}
-
 function resolveBase(): string {
   const location = (globalThis as { location?: { origin?: string } }).location
   return location?.origin !== undefined && location.origin !== 'null' ? location.origin : INTERNAL_BASE
diff --git a/packages/client/connection/tests/client-apply.spec.ts b/packages/client/connection/tests/client-apply.spec.ts
index 41e8e9b0e2..9d9bbd2f26 100644
--- a/packages/client/connection/tests/client-apply.spec.ts
+++ b/packages/client/connection/tests/client-apply.spec.ts
@@ -285,9 +285,37 @@ describe('connection client apply', () => {
     }
   })
 
-  it('keeps generic Remote calls unavailable in the client-only fixture', async () => {
+  it('carries Goal Remotes over the same state as the client-only fixture API', async () => {
     ;(globalThis as Win).location = { hostname: 'localhost', search: '?fixture' }
     const handle = await mount()
-    await expect(handle.rpc.call('/api', 'goals/create', {})).rejects.toThrow(/unavailable in fixture mode/)
+    const created = await handle.rpc.call('/api', 'goals/create', {
+      args: { agentId: 'fx-alpha', request: { objective: 'fixture remote' } },
+    })
+    expect(created).toMatchObject({ ok: true, value: { ref: { revision: 1 } } })
+    if (!created.ok) throw new Error('fixture Goal create failed')
+    const ref = (created.value as { ref: { id: string; revision: number } }).ref
+    const edited = await handle.rpc.call('/api', 'goals/edit', {
+      args: { agentId: 'fx-alpha', ref, request: { objective: 'edited fixture remote' } },
+    })
+    expect(edited).toMatchObject({ ok: true, value: { objective: 'edited fixture remote', revision: 2 } })
+    const editedRef = { id: ref.id, revision: 2 }
+    const paused = await handle.rpc.call('/api', 'goals/pause', {
+      args: { agentId: 'fx-alpha', ref: editedRef },
+    })
+    expect(paused).toMatchObject({ ok: true, value: { phase: 'paused', activation: 'disarmed', revision: 3 } })
+    const resumed = await handle.rpc.call('/api', 'goals/resume', {
+      args: { agentId: 'fx-alpha', ref: { id: ref.id, revision: 3 } },
+    })
+    expect(resumed).toMatchObject({ ok: true, value: { phase: 'active', activation: 'armed', revision: 4 } })
+    const completed = await handle.rpc.call('/api', 'goals/complete', {
+      args: { agentId: 'fx-alpha', ref: { id: ref.id, revision: 4 } },
+    })
+    expect(completed).toMatchObject({ ok: true, value: { phase: 'complete', activation: 'disarmed', revision: 5 } })
+    await expect(handle.rpc.call('/api', 'goals/clear', {
+      args: { agentId: 'fx-alpha', ref: { id: ref.id, revision: 5 } },
+    })).resolves.toEqual({ ok: true, value: { id: ref.id, revision: 6 } })
+    await expect(handle.rpc.call('/other', 'goals/create', {})).rejects.toThrow(/channel.*unavailable/)
+    await expect(handle.rpc.call('/api', 'unknown/read', { args: { agentId: 'fx-alpha' } }))
+      .rejects.toThrow(/endpoint.*unavailable/)
   })
 })

From 737c12935ac1c95bd4118422c19f283abdb540f6 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 13:04:42 +0800
Subject: [PATCH 139/516] fix(connection): share fixture goal revision lookup

---
 .../client/connection/src/client/fixture.ts   | 29 +++++++++++--------
 .../request-response.expected.json            |  4 +--
 2 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 1a9841aece..776d21fd46 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -1598,12 +1598,9 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
       ))
     },
     clear(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalRef> {
-      const missing = requireGoalSession(id)
-      if (missing !== undefined) return missing
-      const current = backscanGoal(logOf(id))
-      if (current === null || current.goal.id !== ref.id || current.goal.revision !== ref.revision) {
-        return goalFailure('stale or missing goal revision')
-      }
+      const resolved = resolveGoal(id, ref)
+      if (!resolved.ok) return resolved
+      const current = resolved.value
       const tombstone = { id: current.goal.id, revision: current.goal.revision + 1 }
       appendGoalChange(id, {
         kind: 'goal/change', version: 1, operation: 'clear', cleared: tombstone, clearedAt: Date.now(),
@@ -1612,18 +1609,26 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     },
   }
 
-  /** Shared CAS mutation path behind the canonical Remote verbs. */
-  function mutateGoal(
-    id: SessionId,
-    ref: FxGoalRef,
-    next: (current: FxGoalProjection) => FxGoalProjection['goal'] | undefined,
-  ): RpcResult<FxGoalView> {
+  /** Resolve one current goal revision for a canonical Remote mutation. */
+  function resolveGoal(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalProjection> {
     const missing = requireGoalSession(id)
     if (missing !== undefined) return missing
     const current = backscanGoal(logOf(id))
     if (current === null || current.goal.id !== ref.id || current.goal.revision !== ref.revision) {
       return goalFailure('stale or missing goal revision')
     }
+    return { ok: true, value: current }
+  }
+
+  /** Shared CAS mutation path behind the canonical Remote verbs. */
+  function mutateGoal(
+    id: SessionId,
+    ref: FxGoalRef,
+    next: (current: FxGoalProjection) => FxGoalProjection['goal'] | undefined,
+  ): RpcResult<FxGoalView> {
+    const resolved = resolveGoal(id, ref)
+    if (!resolved.ok) return resolved
+    const current = resolved.value
     const goal = next(current)
     if (goal === undefined) {
       return goalFailure(`invalid goal transition from "${current.goal.phase}"`)
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index b9d67f4bf6..e796de8a8a 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository typecheck runs the whole-repo `tsc -b` graph: it emits every package/vendor `lib/types` and checks examples, tests, and scripts through two no-emit aggregates.\n\nThe repository's TypeScript configuration has exactly three roles; every tsconfig file plays one of them.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, references to the two aggregates. The whole-repo `tsc -b tsconfig.json` graph, the tsserver discovery entry, and — through the inherited `paths` — the resolution config for tsx running `examples/` and `scripts/` (their nearest tsconfig is this file). | No |\n| `tsconfig.host.json` | Host aggregate: host-side packages (via references), examples, tests, scripts, website. Excludes `packages/client`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the client aggregate and every `packages/client/*` package. | No |\n\nHost and client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Two disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges. Program-backed generators and gates (`scripts/ts-project.ts` consumers, doc-typecheck standalone mode) are host-only by decision; the client side gains program-backed tooling only with a concrete need.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository typecheck runs the whole-repo `tsc -b` graph: it emits every package/vendor `lib/types` and checks examples, tests, and scripts through two no-emit aggregates.\n\nThe repository's TypeScript configuration has exactly three roles; every tsconfig file plays one of them.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, references to the two aggregates. The whole-repo `tsc -b tsconfig.json` graph, the tsserver discovery entry, and — through the inherited `paths` — the resolution config for tsx running `examples/` and `scripts/` (their nearest tsconfig is this file). | No |\n| `tsconfig.host.json` | Host aggregate: host-side packages (via references), examples, tests, scripts, website. Excludes `packages/client`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the client aggregate and every `packages/client/*` package. | No |\n\nHost and client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Two disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges. Program-backed generators and gates (`scripts/ts-project.ts` consumers, doc-typecheck standalone mode) are host-only by decision; the client side gains program-backed tooling only with a concrete need.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteContext`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `client-remotes` composition loads those contributions and mounts concrete methods on `ctx.api` or the corresponding scoped Context. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库类型检查会执行全仓 `tsc -b` 图：它会发射每个 package/vendor 的 `lib/types`，并通过两个 no-emit 聚合检查示例、测试和脚本。\n\n仓库的 TypeScript 配置只有三种角色；每个 tsconfig 文件恰好扮演其中一种。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个聚合。全仓 `tsc -b tsconfig.json` 图、tsserver 发现入口，并经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置（它们最近的 tsconfig 就是此文件）。 | 否 |\n| `tsconfig.host.json` | host 聚合：host 侧各包（经 references）、示例、测试、脚本、website。排除 `packages/client`。 | 是 |\n| `tsconfig.client.json` | client 聚合：`packages/client/*` 各包及其测试、`apps/web`。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 client 聚合和每个 `packages/client/*` 包 extends。 | 否 |\n\nhost 与 client 保持两个聚合 program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个聚合，一个 paths 门面也可以横跨两侧。由此推出两条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个聚合展平进一个 program 会撞上 `Context` 合并冲突。基于 program 的生成器与门禁（`scripts/ts-project.ts` 的消费者、doc-typecheck standalone 模式）按决策仅覆盖 host 侧；client 侧只在出现真实需求时再获得基于 program 的工具。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库类型检查会执行全仓 `tsc -b` 图：它会发射每个 package/vendor 的 `lib/types`，并通过两个 no-emit 聚合检查示例、测试和脚本。\n\n仓库的 TypeScript 配置只有三种角色；每个 tsconfig 文件恰好扮演其中一种。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个聚合。全仓 `tsc -b tsconfig.json` 图、tsserver 发现入口，并经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置（它们最近的 tsconfig 就是此文件）。 | 否 |\n| `tsconfig.host.json` | host 聚合：host 侧各包（经 references）、示例、测试、脚本、website。排除 `packages/client`。 | 是 |\n| `tsconfig.client.json` | client 聚合：`packages/client/*` 各包及其测试、`apps/web`。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 client 聚合和每个 `packages/client/*` 包 extends。 | 否 |\n\nhost 与 client 保持两个聚合 program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个聚合，一个 paths 门面也可以横跨两侧。由此推出两条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个聚合展平进一个 program 会撞上 `Context` 合并冲突。基于 program 的生成器与门禁（`scripts/ts-project.ts` 的消费者、doc-typecheck standalone 模式）按决策仅覆盖 host 侧；client 侧只在出现真实需求时再获得基于 program 的工具。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteContext` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `client-remotes` 组合加载这些贡献并将具体方法挂载到 `ctx.api` 或对应的作用域 Context。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",

From 2fe4a53557179de0fbebe4e83e8cb18e735f112b Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 14:07:19 +0800
Subject: [PATCH 140/516] fix(typert): validate and mount remote contributions
 safely

---
 packages/host/api-gateway/src/client/index.ts | 72 ++++++++++++-----
 .../host/api-gateway/tests/client.spec.ts     | 80 +++++++++++++++++++
 packages/typert/generator/src/analyzer.ts     |  4 +-
 packages/typert/generator/src/workspace.ts    |  1 +
 .../generator/tests/remote-model.spec.ts      | 33 +++++++-
 packages/typert/registry/src/service.ts       |  2 +-
 packages/typert/registry/tests/typert.spec.ts |  2 +-
 packages/typert/type-meta/src/index.ts        |  2 +-
 .../typert/type-meta/tests/type-meta.spec.ts  |  2 +
 9 files changed, 173 insertions(+), 25 deletions(-)

diff --git a/packages/host/api-gateway/src/client/index.ts b/packages/host/api-gateway/src/client/index.ts
index 3fc8389079..5503fc3dcf 100644
--- a/packages/host/api-gateway/src/client/index.ts
+++ b/packages/host/api-gateway/src/client/index.ts
@@ -4,7 +4,7 @@
  * lookup, invocation, or type exposure.
  */
 
-import { Service } from 'cordis'
+import { Service, symbols } from 'cordis'
 import type { Context } from 'cordis'
 import type { ConnectionHandle, RpcError } from '@deepseek-ai/dsh-client-connection/client'
 import type {
@@ -84,7 +84,13 @@ class ClientApiService extends Service implements ClientApi {
     let disposeMethods: () => void | Promise<void>
     try {
       disposeMethods = callerCtx.effect(() => {
-        const installed = contribution.descriptors.map(descriptor => this.install(descriptor))
+        const installed: Array<() => void> = []
+        try {
+          for (const descriptor of contribution.descriptors) installed.push(this.install(descriptor))
+        } catch (error) {
+          for (const dispose of installed.reverse()) dispose()
+          throw error
+        }
         return () => {
           for (const dispose of installed.reverse()) dispose()
         }
@@ -169,21 +175,27 @@ class ClientApiService extends Service implements ClientApi {
 
   private installDirect(descriptor: InvocationDescriptor, token: MountToken): () => void {
     let namespace = this.direct.get(descriptor.namespace)
+    const fresh = namespace === undefined
     if (namespace === undefined) {
       namespace = { value: Object.create(null) as Record<string, RemoteMethod>, tokens: new Map() }
-      this.direct.set(descriptor.namespace, namespace)
       Object.defineProperty(this, descriptor.namespace, {
         configurable: true,
         enumerable: true,
         value: namespace.value,
       })
     }
+    try {
+      Object.defineProperty(namespace.value, descriptor.method, {
+        configurable: true,
+        enumerable: true,
+        value: (...args: unknown[]) => this.invoke(descriptor, undefined, token, this.ownerCtx, args),
+      })
+    } catch (error) {
+      if (fresh) Reflect.deleteProperty(this, descriptor.namespace)
+      throw error
+    }
+    if (fresh) this.direct.set(descriptor.namespace, namespace)
     namespace.tokens.set(descriptor.method, token)
-    Object.defineProperty(namespace.value, descriptor.method, {
-      configurable: true,
-      enumerable: true,
-      value: (...args: unknown[]) => this.invoke(descriptor, undefined, token, this.ownerCtx, args),
-    })
     return () => {
       /* v8 ignore next -- duplicate live methods are rejected before installation, so no newer token can replace this one. */
       if (namespace.tokens.get(descriptor.method) !== token) return
@@ -242,7 +254,7 @@ class ClientApiService extends Service implements ClientApi {
         `client api: ${endpoint} expected ${contract}, got ${String(values.length)}`,
       )
     }
-    const args: Record<string, unknown> = {}
+    const args = Object.create(null) as Record<string, unknown>
     if (projection !== undefined) {
       const binder = this.ownerCtx.typert.contexts.getClient(projection.context)
       if (binder === undefined) {
@@ -281,9 +293,12 @@ type InvokeRemote = (
   args: readonly unknown[],
 ) => Promise<unknown>
 
-class ScopedRemoteNamespace extends Service {
+class ScopedRemoteNamespace {
+  private readonly ctx: Context
   private readonly ownerCtx: Context
   private readonly methods = new Set<string>()
+  private provided = false
+  readonly name: string
 
   static assertMethodAvailable(namespace: string, method: string): void {
     if (SCOPED_NAMESPACE_FIELDS.has(method) || method in ScopedRemoteNamespace.prototype) {
@@ -296,8 +311,12 @@ class ScopedRemoteNamespace extends Service {
     name: string,
     private readonly invokeRemote: InvokeRemote,
   ) {
-    super(ctx, name)
+    this.ctx = ctx
     this.ownerCtx = ctx
+    this.name = name
+    Object.defineProperty(this, symbols.tracker, {
+      value: { associate: name, property: 'ctx' },
+    })
   }
 
   assertMethodAvailable(method: string): void {
@@ -309,15 +328,28 @@ class ScopedRemoteNamespace extends Service {
 
   install(descriptor: InvocationDescriptor, projection: ScopedProjection, token: MountToken): void {
     this.assertMethodAvailable(descriptor.method)
-    if (this.methods.size === 0) this.ownerCtx.set(this.name, this)
+    const activate = this.methods.size === 0
     const method = descriptor.method
-    Object.defineProperty(this, method, {
-      configurable: true,
-      enumerable: true,
-      value: function (this: ScopedRemoteNamespace, ...args: unknown[]): Promise<unknown> {
-        return this.invokeRemote(descriptor, projection, token, this.ctx, args)
-      },
-    })
+    try {
+      Object.defineProperty(this, method, {
+        configurable: true,
+        enumerable: true,
+        value: function (this: ScopedRemoteNamespace, ...args: unknown[]): Promise<unknown> {
+          return this.invokeRemote(descriptor, projection, token, this.ctx, args)
+        },
+      })
+      if (activate) {
+        if (this.provided) {
+          this.ownerCtx.set(this.name, this)
+        } else {
+          this.ownerCtx.reflect.provide(this.name, this)
+          this.provided = true
+        }
+      }
+    } catch (error) {
+      Reflect.deleteProperty(this, method)
+      throw error
+    }
     this.methods.add(method)
   }
 
@@ -328,7 +360,7 @@ class ScopedRemoteNamespace extends Service {
   }
 }
 
-const SCOPED_NAMESPACE_FIELDS = new Set(['ctx', 'invokeRemote', 'methods', 'name', 'ownerCtx'])
+const SCOPED_NAMESPACE_FIELDS = new Set(['ctx', 'invokeRemote', 'methods', 'name', 'ownerCtx', 'provided'])
 
 function endpointOf(descriptor: Pick<InvocationDescriptor, 'namespace' | 'method'>): string {
   return `${descriptor.namespace}/${descriptor.method}`
diff --git a/packages/host/api-gateway/tests/client.spec.ts b/packages/host/api-gateway/tests/client.spec.ts
index 5c2c427605..c1f94f2e44 100644
--- a/packages/host/api-gateway/tests/client.spec.ts
+++ b/packages/host/api-gateway/tests/client.spec.ts
@@ -321,6 +321,34 @@ describe('Client TypeRT API', () => {
     await disposeScoped()
   })
 
+  it('rolls back earlier descriptors when a later descriptor fails to install', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const { scope: _scope, ...first } = directDescriptor()
+    const second: InvocationDescriptor = {
+      ...first,
+      id: '@fixture/goals#goals/archive',
+      method: 'archive',
+    }
+    const defineProperty = Object.defineProperty
+    const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      if (key === 'archive') throw new Error('fixture later-descriptor failure')
+      return defineProperty(target, key, attributes)
+    })
+    try {
+      expect(() => ctx.api.mount({ package: '@fixture/failing-batch', descriptors: [first, second] }))
+        .toThrow('fixture later-descriptor failure')
+    } finally {
+      spy.mockRestore()
+    }
+
+    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+    await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
+    const retry = ctx.api.mount({ package: '@fixture/retry-batch', descriptors: [first, second] })
+    expect(ctx.api.goals.create).toBeTypeOf('function')
+    expect((ctx.api.goals as unknown as Record<string, unknown>).archive).toBeTypeOf('function')
+    await retry()
+  })
+
   it('rejects weak parameter and Context codecs plus malformed scope projections', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const direct = directDescriptor()
@@ -409,6 +437,33 @@ describe('Client TypeRT API', () => {
     expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
   })
 
+  it('preserves a __proto__ wire parameter as an own named argument', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })
+    const ctx = await bench(call)
+    const { scope: _scope, ...base } = directDescriptor()
+    const descriptor: InvocationDescriptor = {
+      ...base,
+      id: '@fixture/goals#goals/prototype',
+      method: 'prototype',
+      parameters: [{
+        name: 'value',
+        wire: '__proto__',
+        source: 'json',
+        codec: { mode: 'strict', typeSymbol: '@fixture#PrototypeValue', schema: z.string() },
+      }],
+    }
+    const dispose = ctx.api.mount({ package: '@fixture/prototype', descriptors: [descriptor] })
+
+    const method = (ctx.api.goals as unknown as Record<string, (...args: unknown[]) => Promise<unknown>>).prototype
+    await expect(method?.('wire-value')).resolves.toEqual({ ref: 'goal-1' })
+    const payload = call.mock.calls[0]?.[2] as { readonly args: Record<string, unknown> }
+    expect(Object.getPrototypeOf(payload.args)).toBeNull()
+    expect(Object.hasOwn(payload.args, '__proto__')).toBe(true)
+    expect(payload.args.__proto__).toBe('wire-value')
+    await dispose()
+  })
+
   it('rolls back Remote registration when concrete method installation fails', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const defineProperty = Object.defineProperty
@@ -423,6 +478,31 @@ describe('Client TypeRT API', () => {
     } finally {
       spy.mockRestore()
     }
+
+    const retry = ctx.api.mount({ package: '@fixture/goals-retry', descriptors: [directDescriptor()] })
+    expect(ctx.api.goals.create).toBeTypeOf('function')
+    await retry()
+  })
+
+  it('withdraws a fresh scoped Service when its first method fails to install', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const defineProperty = Object.defineProperty
+    const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      if (key === 'rename') throw new Error('fixture scoped installation failure')
+      return defineProperty(target, key, attributes)
+    })
+    try {
+      expect(() => ctx.api.mount({ package: '@fixture/scoped-failure', descriptors: [contextDescriptor()] }))
+        .toThrow('fixture scoped installation failure')
+    } finally {
+      spy.mockRestore()
+    }
+
+    expect(ctx.get('goals')).toBeUndefined()
+    await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
+    const retry = ctx.api.mount({ package: '@fixture/scoped-retry', descriptors: [contextDescriptor()] })
+    expect((ctx.get('goals') as unknown as Record<string, unknown>).rename).toBeTypeOf('function')
+    await retry()
   })
 
   it('throws RPC failures with the structured error as its cause', async () => {
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index 16c30e8bc5..bc5024a7d8 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -2810,7 +2810,9 @@ function stringLiteralValue(node: ts.Node | undefined): string | undefined {
 }
 
 function isRemoteSegment(value: string): boolean {
-  return /^[A-Za-z0-9_$.-]+$/.test(value)
+  // Generation bootstraps workspace artifacts before dsh-type-meta is built,
+  // so this extraction-only copy must mirror isTypeRTRemoteSegment().
+  return value !== '.' && value !== '..' && /^[A-Za-z0-9_$.-]+$/.test(value)
 }
 
 function expressionName(node: ts.Expression): string | undefined {
diff --git a/packages/typert/generator/src/workspace.ts b/packages/typert/generator/src/workspace.ts
index 6327872166..4a303c4bd4 100644
--- a/packages/typert/generator/src/workspace.ts
+++ b/packages/typert/generator/src/workspace.ts
@@ -90,6 +90,7 @@ export class WorkspaceTypertGenerator {
         throw new TypertAnalysisError(`typert(${artifact.face}): ${artifact.package} package files must include ${file}`)
       }
     }
+    if (artifact.face !== 'host') return
     const remoteExpected = {
       types: './lib/typert.remote-client.d.ts',
       default: './lib/typert.remote-client.js',
diff --git a/packages/typert/generator/tests/remote-model.spec.ts b/packages/typert/generator/tests/remote-model.spec.ts
index 4f4f3ea7cb..27bdac2fac 100644
--- a/packages/typert/generator/tests/remote-model.spec.ts
+++ b/packages/typert/generator/tests/remote-model.spec.ts
@@ -274,7 +274,7 @@ export interface BoxPayload {
     assertRemoteConsumerTypechecks(artifact?.remote?.dts, artifact?.remote?.dtsMap, root)
   })
 
-  it.each(['create#v2', 'create goal'])('rejects untransportable Remote alias %s', (alias) => {
+  it.each(['create#v2', 'create goal', '.', '..'])('rejects untransportable Remote alias %s', (alias) => {
     const root = copyFixture()
     editFile(root, 'packages/remote/src/index.ts', source => source.replace(
       '  @Remote\n  async create(',
@@ -301,6 +301,37 @@ export interface RemainingSchema {
       .toThrow('publishes Remote artifacts but has no Remote methods')
   })
 
+  it('validates Remote artifacts only on the host face of a dual-face package', () => {
+    const root = copyFixture()
+    const manifestPath = join(root, 'packages/remote/package.json')
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as {
+      dshClient?: object
+      exports: Record<string, unknown>
+      files: string[]
+    }
+    manifest.dshClient = {}
+    manifest.exports['./client'] = './src/client.ts'
+    manifest.exports['./client/typert'] = {
+      types: './lib/typert.client.d.ts',
+      default: './lib/typert.client.js',
+    }
+    manifest.files.push('lib/typert.client.js', 'lib/typert.client.d.ts')
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+    writeFileSync(join(root, 'tsconfig.client.json'), `${JSON.stringify({
+      extends: './tsconfig.base.json',
+      files: [],
+      references: [{ path: './packages/remote' }],
+    }, null, 2)}\n`)
+    writeFileSync(join(root, 'packages/remote/src/client.ts'), `/** @typert schema */
+export interface ClientMarker {
+  readonly ready: boolean
+}
+`)
+
+    expect(new WorkspaceTypertGenerator(root).generate().map(artifact => artifact.face))
+      .toEqual(['host', 'client'])
+  })
+
   it.each([
     {
       name: 'missing binding',
diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
index 2f85138edd..3631253342 100644
--- a/packages/typert/registry/src/service.ts
+++ b/packages/typert/registry/src/service.ts
@@ -600,7 +600,7 @@ function validateCodec(codec: InvocationDescriptor['result'], subject: string):
 }
 
 function validateWireName(subject: string, value: string): void {
-  if (!/^[A-Za-z0-9_$.-]+$/.test(value)) {
+  if (value === '.' || value === '..' || !/^[A-Za-z0-9_$.-]+$/.test(value)) {
     throw new Error(`typert: invalid ${subject} "${value}" — must contain only RPC endpoint segment characters`)
   }
 }
diff --git a/packages/typert/registry/tests/typert.spec.ts b/packages/typert/registry/tests/typert.spec.ts
index 6661cbeeb4..29654babf7 100644
--- a/packages/typert/registry/tests/typert.spec.ts
+++ b/packages/typert/registry/tests/typert.spec.ts
@@ -247,7 +247,7 @@ describe('TypertRegistry', () => {
     })).toThrow('endpoint "goals/create" is already registered')
   })
 
-  it.each(['create#v2', 'create goal'])('rejects untransportable invocation method %s', async (method) => {
+  it.each(['create#v2', 'create goal', '.', '..'])('rejects untransportable invocation method %s', async (method) => {
     const ctx = await makeCtx()
     expect(() => ctx.typert.remotes.register({
       package: '@fixture/invalid-endpoint',
diff --git a/packages/typert/type-meta/src/index.ts b/packages/typert/type-meta/src/index.ts
index 67a4169f96..3d782dbb77 100644
--- a/packages/typert/type-meta/src/index.ts
+++ b/packages/typert/type-meta/src/index.ts
@@ -15,7 +15,7 @@ const TYPERT_REMOTE_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
  * @returns whether the value can cross the shared RPC carrier unchanged.
  */
 export function isTypeRTRemoteSegment(value: string): boolean {
-  return TYPERT_REMOTE_SEGMENT_PATTERN.test(value)
+  return value !== '.' && value !== '..' && TYPERT_REMOTE_SEGMENT_PATTERN.test(value)
 }
 
 export type {
diff --git a/packages/typert/type-meta/tests/type-meta.spec.ts b/packages/typert/type-meta/tests/type-meta.spec.ts
index 757488024d..b84b76300c 100644
--- a/packages/typert/type-meta/tests/type-meta.spec.ts
+++ b/packages/typert/type-meta/tests/type-meta.spec.ts
@@ -164,6 +164,8 @@ describe('type-meta Remote declarations', () => {
     expect(() => Remote('bad/name')).toThrow('export name')
     expect(() => Remote('bad#name')).toThrow('export name')
     expect(() => Remote('bad name')).toThrow('export name')
+    expect(() => Remote('.')).toThrow('export name')
+    expect(() => Remote('..')).toThrow('export name')
     expect(() => RemoteContext('' as 'metaFixture')).toThrow('Context key')
     expect(() => RemoteContext('metaFixture', 'bad/name')).toThrow('export name')
 

From d9413502278318ad27a849b01a2c59b8cefaea24 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 14:51:49 +0800
Subject: [PATCH 141/516] fix(typert): preserve remote lookup semantics

---
 ...08-02-typert-remote-method-calls.i18n.yaml |  4 +-
 .../2026-08-02-typert-remote-method-calls.md  | 12 ++-
 ...026-08-02-typert-remote-method-calls.zh.md | 12 ++-
 docs/api-gateway.i18n.yaml                    |  4 +-
 docs/api-gateway.md                           |  6 +-
 docs/api-gateway.zh.md                        |  6 +-
 docs/cordis-catalog/services.md               |  6 +-
 docs/core-data-structures/typert.i18n.yaml    |  4 +-
 docs/core-data-structures/typert.md           |  6 +-
 docs/core-data-structures/typert.zh.md        |  6 +-
 packages/client/ui-goal/src/client/index.ts   | 10 +-
 .../ui-goal/tests/browser-plugin.spec.tsx     | 27 ++++--
 .../cordis/tool-cordis/src/api-catalog.ts     |  2 +-
 packages/host/api-gateway/README.i18n.yaml    |  4 +-
 packages/host/api-gateway/README.md           |  7 +-
 packages/host/api-gateway/README.zh.md        |  7 +-
 packages/host/api-gateway/src/index.ts        | 17 +++-
 packages/host/api-gateway/src/types.ts        |  2 +-
 .../host/api-gateway/tests/client.spec.ts     | 21 ++++
 .../host/api-gateway/tests/gateway.spec.ts    | 44 ++++++++-
 packages/host/apiproxy/package.json           |  2 +
 packages/host/apiproxy/src/api-proxy.ts       | 18 ++++
 .../apiproxy/tests/api-proxy-cold.spec.ts     | 96 +++++++++++++++++++
 packages/host/apiproxy/tsconfig.json          |  6 ++
 packages/typert/registry/README.i18n.yaml     |  4 +-
 packages/typert/registry/README.md            |  1 +
 packages/typert/registry/README.zh.md         |  1 +
 packages/typert/registry/src/service.ts       | 56 ++++++++++-
 packages/typert/registry/tests/typert.spec.ts | 34 +++++++
 packages/typert/type-meta/README.i18n.yaml    |  4 +-
 packages/typert/type-meta/README.md           |  2 +-
 packages/typert/type-meta/README.zh.md        |  2 +-
 packages/typert/type-meta/src/index.ts        | 20 ++++
 packages/typert/type-meta/src/types.ts        | 31 +++++-
 pnpm-lock.yaml                                |  6 ++
 35 files changed, 425 insertions(+), 65 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 02e6c428ff..c76dabca3c 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: ddc93b4fc672f320b4e3dc3e11586d92604e6aa4
-2026-08-02-typert-remote-method-calls.zh.md: 808c7d54bff19d9a4e9cf924769df1d405d997b5
+2026-08-02-typert-remote-method-calls.md: d91f6f173c1b56efcd21d3136392837e61f54aae
+2026-08-02-typert-remote-method-calls.zh.md: 0c548522d1137f0e0002a740d12ca0b796da5e39
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index ddc93b4fc6..d91f6f173c 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -154,7 +154,7 @@ Descriptors exist only in the local registry on each side. The wire carries only
 ```text
 ctx.typert.local     当前进程自己的 Host 或 Client reflection
 ctx.typert.remotes   消费端显式 mount 的对端 Remote contribution
-ctx.typert.lookups   wire ID 到 Host 活对象的 provider
+ctx.typert.lookups   wire ID 到 Host 对象的 provider 与组合策略
 ctx.typert.contexts  Host Context resolver 与 Client Context binder
 ```
 
@@ -162,6 +162,8 @@ Every registration returns a disposer owned by the caller's Cordis fiber. Client
 
 The lookup registry retains the stable wire declaration after its live resolver unloads. SRC parsing continues to classify the parameter as a lookup, while invocation fails with `lookup-unavailable`; it never reclassifies the incoming ID as an ordinary JSON business object. Re-registering the same key with different parameter, wire, or canonical type symbols fails for the lifetime of that TypeRT Service.
 
+Business-object packages own stable declarations and default resolvers through `register()`; Host composition supplies an effect-scoped asynchronous policy for the same key through `configure()`. Configuration may precede provider registration, but does not by itself make a lookup available without a live provider; unloading the configuration restores the provider's default resolver. The standard Web Host's API Proxy configures the same `agentFor()` for `agent` and `session`: live Agents are reused, ordinary cold sessions are resumed automatically, concurrent resumes are deduplicated by Session ID, and the subagent ownership fence returns the existing `agent-busy`. The `session` resolver returns the resolved Agent's Session, so the two parameter kinds do not create separate resume lifecycles.
+
 The registry's Host root entry has the complete `TypeRTService` interface merge. The registry implementation shared by Host and Client lives in a separate module without environment declarations. The registry's `/client` entry imports only that shared implementation and does not pass through the Host root entry, so it cannot bring Host Cordis declarations into the Client Program.
 
 ## Canonical types, symbols, and Zod
@@ -432,7 +434,7 @@ ctx.api.goals.create(sessionId, request, signal?)
 → Client result codec 验证并返回 CreateGoalResult
 ```
 
-Remote does not define a second-layer `{ ok, value/error }` response. Successful values and Gateway errors use the existing RPC response's `result` directly. The current adapter converts every Gateway and business-invocation failure to the existing `RpcError` envelope with `code: 'internal'`; the Gateway's structured error category remains available only in-process, while the message carries the diagnostic across Connection.
+Remote does not define a second-layer `{ ok, value/error }` response. Successful values and Gateway errors use the existing RPC response's `result` directly. The adapter converts ordinary Gateway and business-invocation failures to the existing `RpcError` envelope with `code: 'internal'`; an existing RPC error carried by a resolver in `TypeRTLookupFailure` is returned unchanged, preserving stable error codes for cold-resume failures and ownership fences. The Gateway's structured error category remains available only in-process, while the message carries the diagnostic across Connection.
 
 The Gateway does not handle per-method permissions, caller identity, idempotency, or long-lived connection state. It only propagates cooperative cancellation from Connection into explicitly cancellation-aware business methods. TypeRT endpoints use Connection's trusted-host policy; unclaimed endpoints retain the legacy API Proxy's trust and privileged-method policies. Connection's WebSocket migration remains separate follow-up work.
 
@@ -451,11 +453,12 @@ The Gateway registers only its ownership matcher and RPC handler with Connection
 - `@deepseek-ai/dsh-client-remotes`: the only Remote facade depended on by Client business code; directly depends on the Gateway Client face, selects `/remote` contributions, and exposes the merged API types to business packages.
 - Connection: owns the single HTTP Server/future WebSocket carrier, shared `/api` route and composite FetchHandler, API Proxy fallback, RPC envelope, rpcId, serialization, trust, and error transport.
 - Business-object packages such as Agent/Session: own lookup, Context providers, canonical ID types, and public type-only entries.
+- API Proxy Host composition: configures cold resume, concurrent deduplication, and subagent ownership policy for `agent`/`session` lookups through the existing `agentFor()`.
 - Business Service packages: declare bindings, Remote methods, and their request/result types, and export the generated `/remote` subpath.
 
 ## Shipped scope and deferred work
 
-The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`. The same direct descriptor with an Agent lookup supports both `ctx.api.goals.create(agentId, request)` and `agentCtx.goals.create(request)`. `@RemoteContext('agent')` remains the distinct scoped-receiver mode.
+The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`. The same direct descriptor with an Agent lookup supports both `ctx.api.goals.create(agentId, request)` and `agentCtx.goals.create(request)`. Ordinary cold sessions are resumed through `agentFor()` during lookup, while subagent-owned identities retain the existing `agent-busy` fence; `@RemoteContext('agent')` remains the distinct scoped-receiver mode.
 
 Connection supplies the shared-channel interceptor and current HTTP carrier mapping. WebSocket migration, the TUI runtime and carrier, TUI Agent Scope wiring, Permission/Approval state machines, Session event streams, call authorization, retries, idempotency, and cross-version protocol compatibility remain outside this decision.
 
@@ -486,6 +489,7 @@ Connection supplies the shared-channel interceptor and current HTTP carrier mapp
 - Importing `@deepseek-ai/dsh-goal/remote` adds the strict `api.goals.create(...)` type and declaration navigation to `remoteExportCreate`; omitting that import omits the namespace.
 - Mounting the same import's JS contribution supplies endpoint, parameter, result, lookup, Context, and Zod reflection and materializes the call without a handwritten stub.
 - Root and Agent-scoped calls cross the real shared `/api` carrier, resolve `agentId` to the live Agent, invoke the original Goal receiver, and return through the existing RPC envelope.
+- Agent and Session lookups share a single in-flight cold-session resume; ordinary cold sessions receive restored objects, while both cold and live subagent identities return `agent-busy` before business invocation.
 - The Remote artifacts and maps contain only marked methods and no Browser dependency, preserving the same consumer boundary for a future TUI.
 - Lifecycle tests withdraw and remount descriptors, Services, lookups, Context providers, and Client namespaces; unavailable dependencies fail without stale calls or raw-ID fallback.
 - Cancellation tests cover strict generation, SRC final-name recognition, Client signal fusion, Connection-to-Gateway propagation, and Host injection outside wire `args`.
@@ -514,3 +518,5 @@ Remote endpoints use Connection's `trusted-host` authority. Loopback is accepted
 `hasSeen()` favors strict-definition safety over SRC availability. While a strict descriptor is withdrawn, such as during HMR, the Gateway continues to claim the endpoint and reports it unavailable instead of falling back to a weak SRC descriptor. Re-registration restores it; only a TypeRT registry restart forgets the historical strict definition.
 
 Cancellation-aware Remote signatures receive Connection's request `AbortSignal`, so an HTTP disconnect or Client-side abort reaches ongoing business work without entering the JSON protocol. Cancellation remains cooperative: methods without the reserved final parameter continue running, and a method that receives the signal must pass it to its own cancellable operations or observe it directly.
+
+Lookup configuration currently operates at key granularity, so every `agent` or `session` parameter uses the same cold-resume policy. A specific Remote that requires live-only semantics must wait for an explicit per-parameter or per-endpoint policy; the business implementation cannot be left to guess whether the object was just resumed.
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 808c7d54bf..0c548522d1 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -154,7 +154,7 @@ descriptor 只存在于两端本地 registry。wire 上只有 `/api` channel、e
 ```text
 ctx.typert.local     当前进程自己的 Host 或 Client reflection
 ctx.typert.remotes   消费端显式 mount 的对端 Remote contribution
-ctx.typert.lookups   wire ID 到 Host 活对象的 provider
+ctx.typert.lookups   wire ID 到 Host 对象的 provider 与组合策略
 ctx.typert.contexts  Host Context resolver 与 Client Context binder
 ```
 
@@ -162,6 +162,8 @@ ctx.typert.contexts  Host Context resolver 与 Client Context binder
 
 lookup 注册表会在活 resolver 卸载后保留稳定的 wire 声明。SRC 解析仍会把该参数归类为 lookup，而调用会以 `lookup-unavailable` 失败；系统绝不会把传入的 ID 重新归类为普通 JSON 业务对象。在同一个 TypeRT Service 的生命周期内，以不同参数、wire 或规范类型 symbol 重新注册同一 key 会直接失败。
 
+业务对象包通过 `register()` 拥有稳定声明和默认 resolver；Host 组合通过 `configure()` 为同一个 key 提供 effect-scoped 异步策略。配置可以先于 provider 注册，但没有活 provider 时不会单独形成可用 lookup；配置卸载后恢复 provider 默认 resolver。标准 Web Host 的 API Proxy 为 `agent` 和 `session` 配置同一套 `agentFor()`：live Agent 直接复用，普通冷会话自动恢复，并发恢复按 Session ID 去重，subagent ownership fence 则返回既有 `agent-busy`。`session` resolver 返回解析所得 Agent 的 Session，因而两种参数不会产生两套恢复生命周期。
+
 Registry 的 Host 根入口拥有完整 `TypeRTService` interface merge；Host 与 Client 共用的 registry 实现位于无环境声明的独立模块。Registry `/client` 入口只引用该共享实现，不经过 Host 根入口，因此不会把 Host Cordis 声明带入 Client Program。
 
 ## 唯一类型、符号与 Zod
@@ -432,7 +434,7 @@ ctx.api.goals.create(sessionId, request, signal?)
 → Client result codec 验证并返回 CreateGoalResult
 ```
 
-Remote 不定义第二层 `{ ok, value/error }` response。成功值和 Gateway 错误直接使用既有 RPC response 的 `result`。当前 adapter 把所有 Gateway 与业务调用失败转换为既有 `RpcError` envelope，并统一使用 `code: 'internal'`；Gateway 的结构化错误分类仅在进程内保留，诊断信息则通过 message 跨 Connection 传递。
+Remote 不定义第二层 `{ ok, value/error }` response。成功值和 Gateway 错误直接使用既有 RPC response 的 `result`。adapter 把普通 Gateway 与业务调用失败转换为既有 `RpcError` envelope，并统一使用 `code: 'internal'`；resolver 通过 `TypeRTLookupFailure` 携带的既有 RPC error 则原样返回，使冷恢复失败和 ownership fence 保持稳定错误码。Gateway 的结构化错误分类仅在进程内保留，诊断信息则通过 message 跨 Connection 传递。
 
 Gateway 不处理逐方法权限、调用者身份、幂等或长连接状态。它只把 Connection 的协作式取消传播给显式支持取消的业务方法。TypeRT endpoint 使用 Connection 的 trusted-host 策略；未认领 endpoint 保留旧 API Proxy 的 trust 和 privileged-method 策略。Connection/WebSocket 迁移后续独立完成。
 
@@ -451,11 +453,12 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 - `@deepseek-ai/dsh-client-remotes`：Client 业务唯一依赖的 Remote facade；直接依赖 Gateway Client face，选择 `/remote` contributions，并向业务包传递合并后的 API 类型。
 - Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、共享 `/api` route 与复合 FetchHandler、API Proxy 回退、RPC envelope、rpcId、序列化、trust 和错误传输。
 - Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
+- API Proxy Host 组合：用既有 `agentFor()` 配置 `agent`/`session` lookup 的冷恢复、并发去重和 subagent ownership 策略。
 - 业务 Service 包：声明 binding、Remote 方法及其 request/result 类型，并导出生成的 `/remote` 子路径。
 
 ## 已交付范围与后续工作
 
-已交付的纵向链路是 `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`。同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.api.goals.create(agentId, request)` 与 `agentCtx.goals.create(request)`。`@RemoteContext('agent')` 仍是独立的 scoped receiver 模式。
+已交付的纵向链路是 `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`。同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.api.goals.create(agentId, request)` 与 `agentCtx.goals.create(request)`。普通冷会话在 lookup 时通过 `agentFor()` 恢复，subagent-owned identity 保持既有 `agent-busy` fence；`@RemoteContext('agent')` 仍是独立的 scoped receiver 模式。
 
 Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebSocket 迁移、TUI runtime 与 carrier、TUI Agent Scope 接线、Permission/Approval 状态机、Session 事件流、调用授权、重试、幂等及跨版本协议兼容均不属于本决策。
 
@@ -486,6 +489,7 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 - 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `api.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
 - 挂载同一次 import 得到的 JS contribution 会提供 endpoint、参数、结果、lookup、Context 和 Zod 反射，并在无需手写 stub 的情况下实体化调用。
 - Root 与 Agent-scoped 调用会经过真实的共享 `/api` carrier，将 `agentId` 解析为活 Agent，调用原始 Goal receiver，并通过既有 RPC envelope 返回。
+- Agent 与 Session lookup 会共享同一次并发冷恢复；普通冷会话得到恢复后的对象，冷态或 live subagent identity 均在业务调用前返回 `agent-busy`。
 - Remote 产物与 map 仅包含已标记的方法，不依赖 Browser，从而为未来 TUI 保留相同的消费方边界。
 - 生命周期测试会撤回并重新挂载 descriptor、Service、lookup、Context 提供方和 Client namespace；依赖不可用时，调用会失败，且不会使用陈旧调用或回退原始 ID。
 - 取消测试覆盖严格生成、SRC 末位参数名识别、Client signal 合并、Connection 到 Gateway 的传播，以及 Host 在 wire `args` 之外的注入。
@@ -514,3 +518,5 @@ Remote endpoint 使用 Connection 的 `trusted-host` authority。系统默认接
 `hasSeen()` 优先保障 strict definition 的安全性，而非 SRC 可用性。strict descriptor 撤回时（例如 HMR 期间），Gateway 会继续认领 endpoint 并报告不可用，而不会回退到弱 SRC descriptor。重新注册即可恢复；只有重启 TypeRT 注册表才会忘记历史 strict definition。
 
 支持取消的 Remote 签名会接收 Connection 请求的 `AbortSignal`，因此 HTTP 断连或 Client 侧 abort 能在不进入 JSON 协议的情况下传递到正在进行的业务工作。取消仍是协作式的：没有保留末位参数的方法会继续运行；收到 signal 的方法必须将它传给自身支持取消的操作，或自行观测它。
+
+lookup 配置当前以 key 为粒度，因此每个 `agent` 或 `session` 参数都采用同一套冷恢复策略。需要 live-only 语义的特定 Remote 必须等待显式的逐参数或逐 endpoint 策略，不能靠业务实现猜测对象是否刚被恢复。
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index 87abb10c88..58891890d3 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.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 docs/api-gateway.md
-api-gateway.md: 76af93880d278a17dc46370fd5065fdcdadb9fb6
-api-gateway.zh.md: d447cea6b64bf88084f86a210a5f654bd9445d6c
+api-gateway.md: 2e0717fd7b0e5b9ca33d650ffad7ac454046f780
+api-gateway.zh.md: 4d1beebf92cae702dac323cdd974b6220091a214
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index 76af93880d..2e0717fd7b 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -8,7 +8,7 @@ This is the current-state reference for the TypeRT API Gateway. It describes how
 
 Business services use `@Remote` or `@RemoteContext` to select the methods exposed to the Client. Unmarked methods do not enter the generated Client types or runtime contributions and cannot be called through `ctx.api`.
 
-`@Remote` denotes calling a Cordis service registered on the root Host Context. Complex Host objects cannot cross the wire directly; the business package must declare their association with a wire identity through `TypeRTLookupMap` and register a resolution provider with `ctx.typert.lookups` at runtime. For example, an `Agent` parameter named `agent` in the Host signature produces an `agentId` wire field, and the Gateway resolves that id to the current live object before invoking the business method.
+`@Remote` denotes calling a Cordis service registered on the root Host Context. Complex Host objects cannot cross the wire directly; the business package must declare their association with a wire identity through `TypeRTLookupMap` and register a default resolution provider with `ctx.typert.lookups` at runtime. For example, an `Agent` parameter named `agent` in the Host signature produces an `agentId` wire field, and the Gateway resolves that id to a Host object before invoking the business method. Host composition can use `ctx.typert.lookups.configure()` to override the resolution policy for a lookup key without changing the parameter name, wire field, or canonical type symbol owned by the business package.
 
 `@RemoteContext(key)` first resolves an identity to a scoped Context through `ctx.typert.contexts`, then obtains the service from that Context and invokes the method. It applies when the method itself depends on scoped composition and does not need to receive objects such as `Agent` explicitly.
 
@@ -117,6 +117,8 @@ The Connection performs the unified trust check for `/api` before the HTTP bridg
 
 For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. It requires the fields in `args` to match the descriptor exactly, validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, invokes the service method targeted by the binding, and validates the return value. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails at the boundary before entering or after leaving business code.
 
+The lookup provider's `register()` supplies both the stable declaration and the default resolver; `configure()` supplies a resolver owned by Host composition that may execute asynchronously and is scoped to an effect lifetime. Configuration may precede provider mounting; without a provider, invocation still fails with `lookup-unavailable`, and unloading the configuration restores the provider's default policy. The standard Web Host's API Proxy configures the same `agentFor()` semantics for `agent` and `session`: it reuses a live Agent, automatically resumes ordinary cold sessions, deduplicates concurrent resumes, and rejects identities owned by subagent routing; the `session` lookup returns that Agent's Session. Resume failures and ownership fences pass through unchanged as existing RPC errors rather than being collapsed into the Gateway's `internal` error.
+
 Unloading a Client contribution removes its descriptors and concrete methods together, aborts its in-flight calls, and makes stale method handles retained by external code reject further calls. A strict endpoint withdrawn on the Host also does not degrade to SRC inference, preventing a hot unload from silently weakening validation.
 
 ## SRC development fallback
@@ -155,3 +157,5 @@ The running Client watcher consumes these generated files when it rebundles; wit
 ## Boundaries
 
 Remote handles only unary method calls with one request and one result. Session event streams, pagination, incremental reduce, projection, and entity substreams require a separate data protocol and registration model; even when they reuse the Connection, they must not masquerade as Remote methods or enter invocation descriptors.
+
+Lookup policy is currently configured per key, so all `agent` or `session` parameters share the cold-resume behavior. If a Remote endpoint must accept live objects only, an explicit per-parameter or per-endpoint policy must be added later; the business method must not guess whether the object came from restoration.
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index d447cea6b6..4d1beebf92 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -8,7 +8,7 @@
 
 业务 Service 通过 `@Remote` 或 `@RemoteContext` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.api` 调用。
 
-`@Remote` 表示调用根 Host Context 中注册的 Cordis Service。复杂的 Host 对象不能直接跨 wire 传输；业务包必须通过 `TypeRTLookupMap` 声明它与 wire identity 的关联，并在运行时向 `ctx.typert.lookups` 注册解析提供方。例如 `Agent` 参数在 Host 签名中名为 `agent`，生成的 wire 字段为 `agentId`，Gateway 在调用业务方法前将 id 解析为当前的实时对象。
+`@Remote` 表示调用根 Host Context 中注册的 Cordis Service。复杂的 Host 对象不能直接跨 wire 传输；业务包必须通过 `TypeRTLookupMap` 声明它与 wire identity 的关联，并在运行时向 `ctx.typert.lookups` 注册默认解析提供方。例如 `Agent` 参数在 Host 签名中名为 `agent`，生成的 wire 字段为 `agentId`，Gateway 在调用业务方法前将 id 解析为 Host 对象。Host 组合可以用 `ctx.typert.lookups.configure()` 覆盖某个 lookup key 的解析策略，而不改变业务包拥有的参数名、wire 字段或规范类型 symbol。
 
 `@RemoteContext(key)` 表示先通过 `ctx.typert.contexts` 把 identity 解析为一个作用域 Context，再从该 Context 取得 Service 并调用方法。它适用于方法本身依赖作用域组合、而不需要显式接收 `Agent` 等对象的情形。
 
@@ -117,6 +117,8 @@ Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共
 
 Gateway 每次调用都从当前注册表解析描述符和实时 Service，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或 Context provider 解析对象或接收者，最后调用 binding 指向的 Service 方法并校验返回值。缺少 provider、identity 未命中、binding 不一致、参数多缺、schema 失败和方法不存在都在进入或离开业务边界时失败。
 
+lookup provider 的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于 provider 挂载；没有 provider 时调用仍以 `lookup-unavailable` 失败，配置卸载后则恢复 provider 默认策略。标准 Web Host 的 API Proxy 为 `agent` 与 `session` 配置同一套 `agentFor()` 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。恢复失败和 ownership fence 通过既有 RPC error 原样返回，不折叠为 Gateway 的 `internal` 错误。
+
 Client 卸载一个贡献时会一起移除描述符和具体方法，中止其进行中的调用，并使外部仍持有的旧方法句柄拒绝继续调用。Host 上已经注册过的严格 endpoint 被撤回后也不会降级到 SRC 推断，以免热卸载悄然降低校验强度。
 
 ## SRC 开发回退
@@ -155,3 +157,5 @@ pnpm run build:lib:contracts
 ## 边界
 
 Remote 只处理有单个请求与单个结果的一元方法调用。Session event stream、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
+
+当前 lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。某个 Remote endpoint 若必须只接受 live 对象，需要后续增加显式的逐参数或逐 endpoint 策略，不能通过业务方法内部猜测恢复来源。
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 8a646fc177..8acd669131 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2593,7 +2593,7 @@ listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
 toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
 ```
 
-Source: [`packages/typert/registry/src/service.ts:346`](../../packages/typert/registry/src/service.ts)
+Source: [`packages/typert/registry/src/service.ts:400`](../../packages/typert/registry/src/service.ts)
 
 ## `ctx.typertGateway` — `TypertGatewayService`
 
@@ -2604,12 +2604,12 @@ Resolve strict generated definitions or conservative SRC markers against current
  * Invoke one live Remote method through strict generated reflection or SRC markers.
  * @param request - decoded endpoint and exact named wire arguments.
  * @returns the validated business result.
- * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+ * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
  */
 async invoke(request: InvokeRemoteRequest): Promise<unknown>
 ```
 
-Source: [`packages/host/api-gateway/src/index.ts:76`](../../packages/host/api-gateway/src/index.ts)
+Source: [`packages/host/api-gateway/src/index.ts:78`](../../packages/host/api-gateway/src/index.ts)
 
 ## `ctx.userInteraction` — `UserInteractionService`
 
diff --git a/docs/core-data-structures/typert.i18n.yaml b/docs/core-data-structures/typert.i18n.yaml
index a5484d06c4..5b0b70de54 100644
--- a/docs/core-data-structures/typert.i18n.yaml
+++ b/docs/core-data-structures/typert.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 docs/core-data-structures/typert.md
-typert.md: da6e229ff6a2300c36f5734ad05c621a5e63082d
-typert.zh.md: b3b0e8897756b5b4f9b645522cc5a1b27eac1d33
+typert.md: 1ff0fe80e483d481f686336c86038cdd169ecdbc
+typert.zh.md: 3cc0aa26406e01db5a6c05074210fc9d40b8ec00
diff --git a/docs/core-data-structures/typert.md b/docs/core-data-structures/typert.md
index da6e229ff6..1ff0fe80e4 100644
--- a/docs/core-data-structures/typert.md
+++ b/docs/core-data-structures/typert.md
@@ -114,7 +114,7 @@ interface InvocationDescriptor {
 
 ## TypeRT registry
 
-`ctx.typert` separates current-environment descriptors, explicitly selected Remote contributions, live lookup providers, and scoped Context providers. Registrations are Cordis-owned effects and return awaitable disposers.
+`ctx.typert` separates current-environment descriptors, explicitly selected Remote contributions, lookup providers, and scoped Context providers. A lookup provider owns the stable wire declaration and default resolver; Host composition can configure an effect-scoped synchronous or asynchronous resolver for the same key, and unloading that configuration restores the default policy. Registrations are Cordis-owned effects and return awaitable disposers.
 
 ```ts type-equiv
 /** Minimal TypeRT runtime consumed through dependency inversion. */
@@ -135,7 +135,7 @@ interface TypeRTRemoteNamespaceMap {}
 
 ## Host Gateway
 
-Connection decodes its carrier envelope before calling `ctx.typertGateway`. The request carries exact named wire fields and the carrier's cancellation signal separately; infrastructure and boundary failures use the Gateway's in-process error taxonomy, although the current RPC adapter folds them into the transport's `internal` error code.
+Connection decodes its carrier envelope before calling `ctx.typertGateway`. The request carries exact named wire fields and the carrier's cancellation signal separately; infrastructure and boundary failures use the Gateway's in-process error taxonomy, ordinary exceptions are folded by the RPC adapter into the transport's `internal` error code, and existing RPC errors carried by lookup policy through `TypeRTLookupFailure` are returned unchanged.
 
 ```ts type-equiv
 /** One Remote method request after a carrier has decoded its envelope. */
@@ -180,7 +180,7 @@ interface TypertGateway {
    * Invoke one live Remote method without assuming a carrier or response envelope.
    * @param request - decoded endpoint and named wire arguments.
    * @returns the validated business result.
-   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
    */
   invoke(request: InvokeRemoteRequest): Promise<unknown>
 }
diff --git a/docs/core-data-structures/typert.zh.md b/docs/core-data-structures/typert.zh.md
index b3b0e88977..3cc0aa2640 100644
--- a/docs/core-data-structures/typert.zh.md
+++ b/docs/core-data-structures/typert.zh.md
@@ -114,7 +114,7 @@ interface InvocationDescriptor {
 
 ## TypeRT 注册表
 
-`ctx.typert` 分开保存当前环境的 descriptor、显式选择的 Remote contribution、活 lookup 提供方与 scoped Context 提供方。各项注册都是由 Cordis 持有的 effect，并返回可等待的 disposer。
+`ctx.typert` 分开保存当前环境的 descriptor、显式选择的 Remote contribution、lookup 提供方与 scoped Context 提供方。lookup 提供方拥有稳定 wire 声明和默认 resolver；Host 组合可以为同一个 key 配置 effect-scoped 同步或异步 resolver，配置卸载后恢复默认策略。各项注册都是由 Cordis 持有的 effect，并返回可等待的 disposer。
 
 ```ts type-equiv
 /** Minimal TypeRT runtime consumed through dependency inversion. */
@@ -135,7 +135,7 @@ interface TypeRTRemoteNamespaceMap {}
 
 ## Host Gateway
 
-Connection 会先解码 carrier envelope，再调用 `ctx.typertGateway`。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带；基础设施与边界失败使用 Gateway 的进程内错误分类体系，但当前 RPC 适配器会把这些错误折叠为传输层的 `internal` 错误码。
+Connection 会先解码 carrier envelope，再调用 `ctx.typertGateway`。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带；基础设施与边界失败使用 Gateway 的进程内错误分类体系，普通异常由 RPC 适配器折叠为传输层的 `internal` 错误码，lookup 策略通过 `TypeRTLookupFailure` 携带的既有 RPC error 则原样返回。
 
 ```ts type-equiv
 /** One Remote method request after a carrier has decoded its envelope. */
@@ -180,7 +180,7 @@ interface TypertGateway {
    * Invoke one live Remote method without assuming a carrier or response envelope.
    * @param request - decoded endpoint and named wire arguments.
    * @returns the validated business result.
-   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
    */
   invoke(request: InvokeRemoteRequest): Promise<unknown>
 }
diff --git a/packages/client/ui-goal/src/client/index.ts b/packages/client/ui-goal/src/client/index.ts
index 19b88139b5..8fcfd292d2 100644
--- a/packages/client/ui-goal/src/client/index.ts
+++ b/packages/client/ui-goal/src/client/index.ts
@@ -70,8 +70,6 @@ function isRemoteError(value: unknown): value is { readonly code: string; readon
 export function apply(ctx: ClientContext): void {
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-goal: dictionaries')
 
-  const { goals } = ctx.api
-
   const sessions = ctx.sessions
 
   /** The session's current projected CAS ref, read at verb call time (no staleness fence: the RPC's CAS is the guard). */
@@ -96,22 +94,22 @@ export function apply(ctx: ClientContext): void {
       onEdit: async (objective) => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(goals.edit(sessionId, ref, { objective }))
+        return settle(ctx.api.goals.edit(sessionId, ref, { objective }))
       },
       onPause: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(goals.pause(sessionId, ref))
+        return settle(ctx.api.goals.pause(sessionId, ref))
       },
       onResume: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(goals.resume(sessionId, ref))
+        return settle(ctx.api.goals.resume(sessionId, ref))
       },
       onClear: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(goals.clear(sessionId, ref))
+        return settle(ctx.api.goals.clear(sessionId, ref))
       },
     }),
   }, GoalDock))
diff --git a/packages/client/ui-goal/tests/browser-plugin.spec.tsx b/packages/client/ui-goal/tests/browser-plugin.spec.tsx
index eddb272be4..11c95e27d9 100644
--- a/packages/client/ui-goal/tests/browser-plugin.spec.tsx
+++ b/packages/client/ui-goal/tests/browser-plugin.spec.tsx
@@ -64,12 +64,16 @@ async function bench(options: {
     }
   }
   const ref = { id: 'g-1', revision: 3 }
-  ctx.provide('api', { goals: {
-    edit: answer('goals/edit', { ref }),
-    pause: answer('goals/pause', { ref }),
-    resume: answer('goals/resume', { ref }),
-    clear: answer('goals/clear', ref),
-  } })
+  const goals = (prefix: string) => ({
+    edit: answer(`${prefix}/edit`, { ref }),
+    pause: answer(`${prefix}/pause`, { ref }),
+    resume: answer(`${prefix}/resume`, { ref }),
+    clear: answer(`${prefix}/clear`, ref),
+  })
+  let activeGoals = goals('goals')
+  ctx.provide('api', {
+    get goals() { return activeGoals },
+  })
   await ctx.plugin(SlotsService).await()
   ctx.slots.register({
     name: 'root', children: { 'conversation.input.dock': { kind: 'list', scope: 'session' } },
@@ -90,6 +94,7 @@ async function bench(options: {
     ctx,
     fiber,
     calls,
+    remountGoals: () => { activeGoals = goals('remounted-goals') },
     entry: () => {
       const entry = ctx.slots.entries('conversation.input.dock')[0]
       if (entry === undefined) return undefined
@@ -126,6 +131,16 @@ describe('ui-goal browser plugin', () => {
     expect(b.calls[3]?.args).toEqual(['s1', ref])
   })
 
+  it('verbs read a remounted Remote namespace at action time', async () => {
+    const b = await bench({ projection: makeProjection() })
+    await b.fiber.await()
+    const verbs = b.entry()!.inject!(sid('s1'))
+    b.remountGoals()
+
+    expect(await verbs.onPause()).toEqual({ ok: true })
+    expect(b.calls).toMatchObject([{ method: 'remounted-goals/pause' }])
+  })
+
   it('a null or absent projection short-circuits every verb without touching the wire', async () => {
     for (const projection of [null, undefined]) {
       const b = await bench({ projection })
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 2627d43b69..b7fd6d3c5a 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -1160,7 +1160,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'async invoke(request: InvokeRemoteRequest): Promise<unknown>',
-        jsDoc: '/**\n * Invoke one live Remote method through strict generated reflection or SRC markers.\n * @param request - decoded endpoint and exact named wire arguments.\n * @returns the validated business result.\n * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.\n */',
+        jsDoc: '/**\n * Invoke one live Remote method through strict generated reflection or SRC markers.\n * @param request - decoded endpoint and exact named wire arguments.\n * @returns the validated business result.\n * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.\n */',
       },
     ],
   },
diff --git a/packages/host/api-gateway/README.i18n.yaml b/packages/host/api-gateway/README.i18n.yaml
index 273a493c24..8d8d699c7a 100644
--- a/packages/host/api-gateway/README.i18n.yaml
+++ b/packages/host/api-gateway/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/host/api-gateway/README.md
-README.md: 43e8f464e2a2790d05628a7fba61143a6a5ab26a
-README.zh.md: 761045d0c1afc17dfc230f9f45849c46e4e579fc
+README.md: eb48c29628d39e381235b1f72754eb114960b1ad
+README.zh.md: e53bb6c216e42fe2e970bf2cb80eac9ea7426497
diff --git a/packages/host/api-gateway/README.md b/packages/host/api-gateway/README.md
index 43e8f464e2..eb48c29628 100644
--- a/packages/host/api-gateway/README.md
+++ b/packages/host/api-gateway/README.md
@@ -8,9 +8,9 @@ Two-sided Remote control for Host and Client Cordis environments. The Host entry
 
 `ctx.typertGateway.invoke()` resolves the current descriptor and Cordis Service for each call, validates exact named arguments, resolves registered object or Context identities, invokes the public business method, and validates its result. Business Services extend `GatewayService` and mark methods with `@Remote` or `@RemoteContext` from [`dsh-type-meta`](../../typert/type-meta/README.md); `bindTypeRTGateway()` remains available when another base class owns inheritance.
 
-Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use registered `ctx.typert.lookups` providers, while `@RemoteContext` resolves its receiver through a registered Host Context provider. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation.
+Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use the currently active resolver in `ctx.typert.lookups`: the business package registers the stable declaration and default policy, while Host composition can override resolution behavior with effect-scoped `configure()`; `@RemoteContext` resolves its receiver through a registered Host Context provider. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation.
 
-The Host entry registers a trusted-host interceptor on Connection's shared `/api` FetchHandler. Connection passes this composite handler through its HTTP bridge; the handler dispatches claimed endpoints to Gateway and unclaimed endpoints to API Proxy. Direct `invoke()` calls preserve business errors; `TypertGatewayError` distinguishes failures owned by dispatch, binding, providers, lookup, Context, arguments, and codecs.
+The Host entry registers a trusted-host interceptor on Connection's shared `/api` FetchHandler. Connection passes this composite handler through its HTTP bridge; the handler dispatches claimed endpoints to Gateway and unclaimed endpoints to API Proxy. Direct `invoke()` calls preserve business errors; `TypertGatewayError` distinguishes failures owned by dispatch, binding, providers, lookup, Context, arguments, and codecs. A resolver may use `TypeRTLookupFailure` to carry an existing RPC error, preserving its original error code for policy rejections such as cold-resume failures or ownership fences.
 
 A cancellation-aware Remote method declares `signal: AbortSignal` as its final Host parameter. The signal is descriptor metadata rather than a wire argument: Connection supplies it to the Gateway, and the Gateway injects it after decoded business parameters. SRC recognizes the reserved final name, while strict generation additionally requires the global `AbortSignal` type.
 
@@ -32,7 +32,8 @@ No direct effect; invoked business Services own any model-visible result.
 
 ## Known Limitations and Deferred Work
 
-- The Connection adapter currently maps dispatch and business failures to the RPC `internal` code with empty details. Structured `TypertGatewayError` categories remain available only to same-process callers.
+- The Connection adapter maps ordinary dispatch failures and business exceptions to the RPC `internal` code with empty details; lookup-policy errors carried by `TypeRTLookupFailure` are returned unchanged. Structured `TypertGatewayError` categories remain available only to same-process callers.
 - SRC mode supports unique identifier parameters without destructuring, defaults, or rest parameters. It validates JSON safety rather than generated business types and never infers optional fields.
 - Only strict generated contributions can mount on the Client face. SRC markers have no Client codec or type projection.
 - The package dispatches unary methods only. Incremental Session data uses a separate named-stream protocol over the same Connection.
+- Lookup resolvers are configured per key; an individual Remote parameter or endpoint cannot currently select a live-only policy under the same `agent`/`session` key.
diff --git a/packages/host/api-gateway/README.zh.md b/packages/host/api-gateway/README.zh.md
index 761045d0c1..e53bb6c216 100644
--- a/packages/host/api-gateway/README.zh.md
+++ b/packages/host/api-gateway/README.zh.md
@@ -8,9 +8,9 @@
 
 每次调用时，`ctx.typertGateway.invoke()` 都会解析当前的描述符和 Cordis 服务，校验具名参数是否完全匹配，解析已注册的对象或 Context 身份标识，调用公开的业务方法，并校验其结果。业务服务继承 [`dsh-type-meta`](../../typert/type-meta/README.md) 的 `GatewayService`，并用 `@Remote` 或 `@RemoteContext` 标记方法；已有其他基类时仍可改用 `bindTypeRTGateway()`。
 
-严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用已向 `ctx.typert.lookups` 注册的提供方，`@RemoteContext` 则通过已注册的 Host Context 提供方解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。
+严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用 `ctx.typert.lookups` 中当前有效的 resolver：业务包注册稳定声明与默认策略，Host 组合可用 effect-scoped `configure()` 覆盖解析行为；`@RemoteContext` 则通过已注册的 Host Context 提供方解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。
 
-Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandler 上注册 trusted-host interceptor。Connection 把这个复合 handler 交给 HTTP bridge；handler 将已认领 endpoint 分发给 Gateway，未认领 endpoint 则交给 API Proxy。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 可区分分发、绑定、提供方、查找、Context、参数和编解码器各自负责的故障。
+Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandler 上注册 trusted-host interceptor。Connection 把这个复合 handler 交给 HTTP bridge；handler 将已认领 endpoint 分发给 Gateway，未认领 endpoint 则交给 API Proxy。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 可区分分发、绑定、提供方、查找、Context、参数和编解码器各自负责的故障。resolver 可以用 `TypeRTLookupFailure` 携带既有 RPC error，使冷恢复失败或 ownership fence 等策略拒绝保持原错误码。
 
 支持取消的 Remote 方法会把 `signal: AbortSignal` 声明为最后一个 Host 参数。signal 是 descriptor 元数据，而不是 wire 参数：Connection 将它提供给 Gateway，Gateway 则在已解码的业务参数之后注入它。SRC 识别这个保留的末位参数名，严格生成还要求它具有全局 `AbortSignal` 类型。
 
@@ -32,7 +32,8 @@ Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandle
 
 ## 已知限制与延期工作
 
-- Connection 适配器目前将分发故障和业务故障映射为 RPC 的 `internal` 代码，且不附带详细信息。结构化的 `TypertGatewayError` 类别仅供同进程调用方使用。
+- Connection 适配器将普通分发故障和业务异常映射为 RPC 的 `internal` 代码，且不附带详细信息；`TypeRTLookupFailure` 携带的 lookup 策略错误会原样返回。结构化的 `TypertGatewayError` 类别仅供同进程调用方使用。
 - SRC 模式仅支持名称唯一的标识符参数，不支持解构、默认值或剩余参数。它只校验值能否安全表示为 JSON，不校验生成的业务类型，也绝不会推断可选字段。
 - Client 侧只能挂载严格模式生成的贡献项。SRC 标记不具备 Client 编解码器或类型投影。
 - 该包只分发一元方法。增量会话数据通过同一个 Connection 上独立的具名流协议传输。
+- lookup resolver 按 key 配置；当前无法让单个 Remote 参数或 endpoint 在同一 `agent`/`session` key 下选择 live-only 策略。
diff --git a/packages/host/api-gateway/src/index.ts b/packages/host/api-gateway/src/index.ts
index 7dd2410873..8ea26b5990 100644
--- a/packages/host/api-gateway/src/index.ts
+++ b/packages/host/api-gateway/src/index.ts
@@ -8,6 +8,7 @@ import { Context, Service, symbols } from 'cordis'
 import type { ConnectionRpcHandler } from '@deepseek-ai/dsh-client-connection'
 import {
   remoteMethods,
+  TypeRTLookupFailure,
   type InvocationDescriptor,
   type InvocationParameterDescriptor,
   type TypeRTCodec,
@@ -36,6 +37,7 @@ interface ResolvedBinding {
 }
 
 type ConnectionRpcResult = Awaited<ReturnType<ConnectionRpcHandler>>
+type ConnectionRpcError = Extract<ConnectionRpcResult, { readonly ok: false }>['error']
 const NEVER_ABORTED_SIGNAL = new AbortController().signal
 
 /** Dispatch failure produced outside the invoked business method. */
@@ -126,7 +128,7 @@ export class TypertGatewayService extends Service implements TypertGateway {
    * Invoke one live Remote method through strict generated reflection or SRC markers.
    * @param request - decoded endpoint and exact named wire arguments.
    * @returns the validated business result.
-   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
    */
   async invoke(request: InvokeRemoteRequest): Promise<unknown> {
     const endpoint = endpointOf(request.namespace, request.method)
@@ -142,7 +144,8 @@ export class TypertGatewayService extends Service implements TypertGateway {
       )
     }
     validateBinding(receiver, descriptor.service, descriptor.namespace, endpoint)
-    const args = descriptor.parameters.map(parameter => this.resolveParameter(parameter, request.args, endpoint))
+    const args = await Promise.all(descriptor.parameters.map(parameter =>
+      this.resolveParameter(parameter, request.args, endpoint)))
     if (descriptor.cancellation !== undefined) args.push(request.signal ?? NEVER_ABORTED_SIGNAL)
     const implementation = descriptor.implementation ?? descriptor.method
     const method = Reflect.get(receiver, implementation) as unknown
@@ -375,11 +378,11 @@ export class TypertGatewayService extends Service implements TypertGateway {
     return context
   }
 
-  private resolveParameter(
+  private async resolveParameter(
     parameter: InvocationParameterDescriptor,
     args: Readonly<Record<string, unknown>>,
     endpoint: string,
-  ): unknown {
+  ): Promise<unknown> {
     const value = decode(parameter.codec, args[parameter.wire], 'input-invalid', endpoint, parameter.wire)
     if (parameter.source === 'json') return value
     const key = parameter.lookup
@@ -412,8 +415,9 @@ export class TypertGatewayService extends Service implements TypertGateway {
     }
     let resolved: unknown
     try {
-      resolved = provider.resolve(value)
+      resolved = await provider.resolve(value)
     } catch (cause) {
+      if (cause instanceof TypeRTLookupFailure) throw cause
       throw new TypertGatewayError(
         'lookup-failed',
         endpoint,
@@ -434,6 +438,9 @@ export class TypertGatewayService extends Service implements TypertGateway {
 }
 
 function rpcFailure(error: unknown): ConnectionRpcResult {
+  if (error instanceof TypeRTLookupFailure) {
+    return { ok: false, error: error.failure as ConnectionRpcError }
+  }
   return {
     ok: false,
     error: {
diff --git a/packages/host/api-gateway/src/types.ts b/packages/host/api-gateway/src/types.ts
index b7f36eb340..f4bb276c22 100644
--- a/packages/host/api-gateway/src/types.ts
+++ b/packages/host/api-gateway/src/types.ts
@@ -41,7 +41,7 @@ export interface TypertGateway {
    * Invoke one live Remote method without assuming a carrier or response envelope.
    * @param request - decoded endpoint and named wire arguments.
    * @returns the validated business result.
-   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
    */
   invoke(request: InvokeRemoteRequest): Promise<unknown>
 }
diff --git a/packages/host/api-gateway/tests/client.spec.ts b/packages/host/api-gateway/tests/client.spec.ts
index c1f94f2e44..2fbcbb9280 100644
--- a/packages/host/api-gateway/tests/client.spec.ts
+++ b/packages/host/api-gateway/tests/client.spec.ts
@@ -484,6 +484,27 @@ describe('Client TypeRT API', () => {
     await retry()
   })
 
+  it('withdraws a fresh direct namespace when its first method fails to install', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const defineProperty = Object.defineProperty
+    const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      if (key === 'create') throw new Error('fixture direct method installation failure')
+      return defineProperty(target, key, attributes)
+    })
+    try {
+      expect(() => ctx.api.mount({ package: '@fixture/direct-method-failure', descriptors: [directDescriptor()] }))
+        .toThrow('fixture direct method installation failure')
+    } finally {
+      spy.mockRestore()
+    }
+
+    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+    await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
+    const retry = ctx.api.mount({ package: '@fixture/direct-method-retry', descriptors: [directDescriptor()] })
+    expect(ctx.api.goals.create).toBeTypeOf('function')
+    await retry()
+  })
+
   it('withdraws a fresh scoped Service when its first method fails to install', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const defineProperty = Object.defineProperty
diff --git a/packages/host/api-gateway/tests/gateway.spec.ts b/packages/host/api-gateway/tests/gateway.spec.ts
index aebe23da57..0871dc2761 100644
--- a/packages/host/api-gateway/tests/gateway.spec.ts
+++ b/packages/host/api-gateway/tests/gateway.spec.ts
@@ -9,6 +9,7 @@ import {
   bindTypeRTGateway,
   Remote,
   RemoteContext,
+  TypeRTLookupFailure,
   type InvocationDescriptor,
   type TypeRTContext,
   type TypeRTLookup,
@@ -91,7 +92,7 @@ class GoalService extends Service {
 
 type FakeRpcResult =
   | { readonly ok: true; readonly value: unknown }
-  | { readonly ok: false; readonly error: { readonly code: 'internal'; readonly message: string; readonly details: object } }
+  | { readonly ok: false; readonly error: { readonly code: string; readonly message: string; readonly details: object } }
 
 type FakeRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<FakeRpcResult>
 
@@ -568,7 +569,7 @@ describe('TypertGatewayService', () => {
     registerStrict(ctx, [createDescriptor()])
     const throwing = ctx.typert.lookups.register('gatewayFixture', {
       ...agentLookup({ id: 'agent-1' }),
-      resolve: () => { throw new Error('lookup failed') },
+      resolve: async () => { throw new Error('lookup failed') },
     })
     const failure = await expectCode(ctx.typertGateway.invoke({
       namespace: 'goals',
@@ -578,15 +579,26 @@ describe('TypertGatewayService', () => {
     expect(failure.cause).toEqual(new Error('lookup failed'))
     await throwing()
 
-    ctx.typert.lookups.register('gatewayFixture', {
+    const missing = ctx.typert.lookups.register('gatewayFixture', {
       ...agentLookup({ id: 'agent-1' }),
-      resolve: () => undefined,
+      resolve: () => Promise.resolve(undefined),
     })
     await expectCode(ctx.typertGateway.invoke({
       namespace: 'goals',
       method: 'create',
       args: { agentId: 'agent-1', request: { title: 'ship' } },
     }), 'lookup-not-found')
+    await missing()
+
+    ctx.typert.lookups.register('gatewayFixture', {
+      ...agentLookup({ id: 'agent-1' }),
+      resolve: async id => ({ id }),
+    })
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    })).resolves.toMatchObject({ agentId: 'agent-1', title: 'ship' })
   })
 
   it('never downgrades an observed strict endpoint after definition disposal', async () => {
@@ -968,6 +980,30 @@ describe('TypertGatewayService', () => {
     expect(connection.handler).toBeUndefined()
   })
 
+  it('preserves a lookup policy rejection through the Connection RPC result', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    await ctx.plugin(FakeConnectionService)
+    await ctx.plugin(TypertGatewayService)
+    await ctx.plugin(GoalService)
+    registerStrict(ctx, [createDescriptor()])
+    const failure = {
+      code: 'agent-busy',
+      message: 'session is owned by subagent routing',
+      details: { reason: 'use subagent delivery for this child session' },
+    }
+    ctx.typert.lookups.register('gatewayFixture', {
+      ...agentLookup({ id: 'agent-1' }),
+      resolve: () => { throw new TypeRTLookupFailure(failure) },
+    })
+    const handler = rawConnection(ctx).handler
+    if (handler === undefined) throw new Error('fixture Connection did not retain the /api interceptor')
+
+    await expect(handler('goals/create', {
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }, new AbortController().signal)).resolves.toEqual({ ok: false, error: failure })
+  })
+
   it('caches SRC ownership until the Cordis Service set changes', async () => {
     const ctx = new Context()
     await ctx.plugin(TypertRegistry)
diff --git a/packages/host/apiproxy/package.json b/packages/host/apiproxy/package.json
index 426860eebc..ce740a025f 100644
--- a/packages/host/apiproxy/package.json
+++ b/packages/host/apiproxy/package.json
@@ -56,6 +56,8 @@
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-subagent": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",
     "@deepseek-ai/dsh-workspace": "workspace:^",
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 2a54e2c113..f2c199feca 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -19,6 +19,9 @@ import { SessionQueryError, type SessionSearchCursor } from '@deepseek-ai/dsh-se
 import { SubagentError } from '@deepseek-ai/dsh-subagent'
 import type { SubagentListEntry as CatalogSubagentListEntry } from '@deepseek-ai/dsh-subagent'
 import type { Workspace, WorkspaceRecord } from '@deepseek-ai/dsh-workspace'
+import { TypeRTLookupFailure } from '@deepseek-ai/dsh-type-meta'
+// Type-only: resolves the optional `ctx.typert` lookup-policy composition.
+import type {} from '@deepseek-ai/dsh-typert-registry'
 import {
   workspaceDomainState, workspaceRecord, WorkspaceId as brandWorkspaceId,
   WorkspaceMoveInvalidError, WorkspaceUnknownSessionError,
@@ -1099,6 +1102,21 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     }
   }
 
+  // Remote object parameters use the same identity policy as API Proxy methods:
+  // ordinary cold sessions resume once, while subagent-owned identities retain
+  // their stable caller-facing rejection. The provider packages continue to
+  // own wire declarations and live-only defaults; this Host composition owns
+  // the broader lookup policy.
+  ctx.inject(['typert'], (typeCtx) => {
+    const resolveAgent = async (sessionId: SessionId): Promise<Agent> => {
+      const found = await agentFor(sessionId)
+      if ('error' in found) throw new TypeRTLookupFailure(found.error)
+      return found.agent
+    }
+    typeCtx.typert.lookups.configure('agent', resolveAgent)
+    typeCtx.typert.lookups.configure('session', async sessionId => (await resolveAgent(sessionId)).session)
+  })
+
   type SessionReadState = {
     id: SessionId
     header: SessionHeader
diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
index 4b6337ede8..e5e137f0c4 100644
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -11,6 +11,8 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import SessionStore from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
+import { TypeRTLookupFailure } from '@deepseek-ai/dsh-type-meta'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import { MessageId } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
@@ -180,6 +182,100 @@ describe('cold history recovery view', () => {
   })
 })
 
+describe('Remote Agent and Session lookup policy', () => {
+  it('deduplicates a cold resume across Agent and Session parameters', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const sessionId = sid('session-remote-cold')
+    const meta = header(sessionId, 1000)
+    const inspect = vi.fn(() => Promise.resolve({ meta, events: [] as SessionEvent[] }))
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve([meta]),
+      inspect,
+      locate: () => undefined,
+    } as never)
+    const resumedSession = { id: sessionId, header: meta, events: [] } as unknown as import('@deepseek-ai/dsh-session').Session
+    const resumedAgent = { id: sessionId, session: resumedSession, status: 'idle', ctx } as Agent
+    const release = Promise.withResolvers<undefined>()
+    const resume = vi.spyOn(ctx.agents, 'resume').mockImplementation(async () => {
+      await release.promise
+      return { agent: resumedAgent, dispose: () => Promise.resolve() }
+    })
+    const defaultAgentLookup = ctx.typert.lookups.get('agent')
+    const defaultSessionLookup = ctx.typert.lookups.get('session')
+    createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    await vi.waitFor(() => {
+      expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
+      expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
+    })
+    const agentLookup = ctx.typert.lookups.get('agent')
+    const sessionLookup = ctx.typert.lookups.get('session')
+    if (agentLookup === undefined || sessionLookup === undefined) throw new Error('core lookup providers were not mounted')
+
+    const resolvedAgent = Promise.resolve(agentLookup.resolve(sessionId))
+    const resolvedSession = Promise.resolve(sessionLookup.resolve(sessionId))
+    await vi.waitFor(() => { expect(resume).toHaveBeenCalledOnce() })
+    release.resolve(undefined)
+
+    await expect(resolvedAgent).resolves.toBe(resumedAgent)
+    await expect(resolvedSession).resolves.toBe(resumedSession)
+    expect(inspect).toHaveBeenCalledOnce()
+  })
+
+  it('preserves the subagent ownership fence for cold and live Remote lookups', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const coldId = sid('session-remote-cold-child')
+    const coldMeta = header(coldId, 1000, {
+      parentSession: sid('session-parent'),
+      origin: 'subagent',
+    })
+    const inspect = vi.fn(() => Promise.resolve({ meta: coldMeta, events: [] as SessionEvent[] }))
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve([coldMeta]),
+      inspect,
+      locate: () => undefined,
+    } as never)
+    const liveSession = ctx.sessions.create(sid('session-remote-live-child'), {
+      meta: { cwd: '/proj', parentSession: sid('session-parent'), origin: 'subagent' },
+    })
+    const liveAgent = { id: liveSession.id, session: liveSession, status: 'idle', ctx } as Agent
+    ctx.agents.register(liveAgent)
+    const resume = vi.spyOn(ctx.agents, 'resume')
+    const defaultAgentLookup = ctx.typert.lookups.get('agent')
+    const defaultSessionLookup = ctx.typert.lookups.get('session')
+    createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    await vi.waitFor(() => {
+      expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
+      expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
+    })
+    const agentLookup = ctx.typert.lookups.get('agent')
+    const sessionLookup = ctx.typert.lookups.get('session')
+    if (agentLookup === undefined || sessionLookup === undefined) throw new Error('core lookup providers were not mounted')
+    const ownershipFailure = {
+      failure: {
+        code: 'agent-busy',
+        details: { reason: 'use subagent delivery for this child session' },
+      },
+    }
+
+    const coldFailure = Promise.resolve(agentLookup.resolve(coldId))
+    const liveFailure = Promise.resolve(sessionLookup.resolve(liveSession.id))
+    await expect(coldFailure).rejects.toBeInstanceOf(TypeRTLookupFailure)
+    await expect(coldFailure).rejects.toMatchObject(ownershipFailure)
+    await expect(liveFailure).rejects.toBeInstanceOf(TypeRTLookupFailure)
+    await expect(liveFailure).rejects.toMatchObject(ownershipFailure)
+    expect(resume).not.toHaveBeenCalled()
+    expect(inspect).toHaveBeenCalledOnce()
+  })
+})
+
 describe('subagent ownership fence', () => {
   it('reads a cold child without an Agent and rejects generic resume or adoption', async () => {
     const ctx = new Context()
diff --git a/packages/host/apiproxy/tsconfig.json b/packages/host/apiproxy/tsconfig.json
index c648d7a30d..23c170f4fd 100644
--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -38,6 +38,12 @@
     {
       "path": "../../core/tools"
     },
+    {
+      "path": "../../typert/type-meta"
+    },
+    {
+      "path": "../../typert/registry"
+    },
     {
       "path": "../../session-persistence/session-persistence"
     },
diff --git a/packages/typert/registry/README.i18n.yaml b/packages/typert/registry/README.i18n.yaml
index b8c97637c9..a6180c6bfc 100644
--- a/packages/typert/registry/README.i18n.yaml
+++ b/packages/typert/registry/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/typert/registry/README.md
-README.md: 83c03ab284abf2b7cab4dd1ee70d7e855184a1e0
-README.zh.md: db2140e51d85be53bbf6eb4d1dd86ec38ceefc58
+README.md: dae8c3ed124fd6e2d61eb47964e2c07dda762b48
+README.zh.md: aea74b3753feccd88ee132363dc60ade02161498
diff --git a/packages/typert/registry/README.md b/packages/typert/registry/README.md
index 83c03ab284..dae8c3ed12 100644
--- a/packages/typert/registry/README.md
+++ b/packages/typert/registry/README.md
@@ -9,6 +9,7 @@ Package reflection is keyed by `<package>#<face>`. Schemas are keyed by `<packag
 ## Public API
 
 - `TypertRegistry` is the default plugin and provides `ctx.typert`.
+- `ctx.typert.lookups.register()` registers the wire declaration and default resolver owned by the business package; `configure()` registers a resolver owned by Host composition that may run asynchronously. Their lifetimes are independent: configuration may precede the provider, and unloading the configuration restores the default policy.
 - `register(contribution)` rejects malformed identities and duplicate package-face or schema keys before committing anything, then returns the exact Cordis effect disposer.
 - `get(key)`, `resolve(key)`, and `list(filter?)` query live schemas. `resolve()` distinguishes a malformed key, an absent package, and a package that contributes no schema under that name.
 - `getPackage(packageName, face?)` and `listPackages(filter?)` query generated service, event, and object reflection; the default face is `host`.
diff --git a/packages/typert/registry/README.zh.md b/packages/typert/registry/README.zh.md
index db2140e51d..aea74b3753 100644
--- a/packages/typert/registry/README.zh.md
+++ b/packages/typert/registry/README.zh.md
@@ -9,6 +9,7 @@
 ## 公开 API
 
 - `TypertRegistry` 是默认插件，并提供 `ctx.typert`。
+- `ctx.typert.lookups.register()` 注册业务包拥有的 wire 声明和默认 resolver；`configure()` 注册 Host 组合拥有、可异步执行的 resolver。两者生命周期独立，配置可以先于 provider，卸载配置会恢复默认策略。
 - `register(contribution)` 会在提交任何内容之前拒绝格式错误的标识，以及重复的包与 face 组合键或 schema 键，随后返回 Cordis effect 提供的同一资源释放函数。
 - `get(key)`、`resolve(key)` 和 `list(filter?)` 查询当前有效的 schema。`resolve()` 能区分格式错误的键、未注册的包，以及已注册但未以该名称提供 schema 的包。
 - `getPackage(packageName, face?)` 和 `listPackages(filter?)` 查询生成的服务、事件和对象反射信息；默认 face 为 `host`。
diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
index 3631253342..9011acc0a1 100644
--- a/packages/typert/registry/src/service.ts
+++ b/packages/typert/registry/src/service.ts
@@ -20,6 +20,7 @@ import type {
   TypeRTLookupDefinition,
   TypeRTLookupMap,
   TypeRTLookupProvider,
+  TypeRTLookupResolver,
   TypeRTLookupRegistry,
   TypeRTLookupWire,
   TypeRTRemoteContribution,
@@ -213,6 +214,7 @@ class RemoteStore {
 
 class LookupStore {
   private readonly providers = new Map<string, ProviderEntry<TypeRTLookupProvider>>()
+  private readonly resolvers = new Map<string, ProviderEntry<LookupResolverEntry>>()
   private readonly definitions = new Map<string, TypeRTLookupDefinition>()
   private readonly changes: ChangeSource
 
@@ -229,13 +231,61 @@ class LookupStore {
           TypeRTLookupWire<TypeRTLookupMap[K]>
         >,
       ) => this.register(ctx, key, provider),
-      get: key => this.providers.get(key)?.provider,
+      configure: <K extends Extract<keyof TypeRTLookupMap, string>>(
+        key: K,
+        resolver: TypeRTLookupResolver<
+          TypeRTLookupHost<TypeRTLookupMap[K]>,
+          TypeRTLookupWire<TypeRTLookupMap[K]>
+        >,
+      ) => this.configure(ctx, key, resolver),
+      get: key => this.get(key),
       definitions: () => [...this.definitions.values()],
       keys: () => [...this.providers.keys()],
       subscribe: listener => this.changes.subscribe(ctx, listener),
     }
   }
 
+  private get(key: string): TypeRTLookupProvider | undefined {
+    const provider = this.providers.get(key)?.provider
+    if (provider === undefined) return undefined
+    const resolver = this.resolvers.get(key)?.provider
+    if (resolver === undefined) return provider
+    return {
+      parameter: provider.parameter,
+      wire: provider.wire,
+      hostTypeSymbol: provider.hostTypeSymbol,
+      wireTypeSymbol: provider.wireTypeSymbol,
+      resolve: id => resolver.resolve(id),
+    }
+  }
+
+  private configure<Host, Wire>(
+    ctx: Context,
+    key: string,
+    resolver: TypeRTLookupResolver<Host, Wire>,
+  ): TypeRTDisposer {
+    validateSegment('lookup key', key)
+    if (this.resolvers.has(key)) throw new Error(`typert: lookup "${key}" resolver is already configured`)
+    const owner = {}
+    // The map erases each merge-declared Wire type; restore it only at the
+    // typed configure() boundary so strict function variance remains sound.
+    const entry: ProviderEntry<LookupResolverEntry> = {
+      provider: { resolve: async id => resolver(id as Wire) },
+      owner,
+    }
+    const { resolvers, changes } = this
+    return ctx.effect(function* () {
+      resolvers.set(key, entry)
+      changes.emit({ kind: 'lookup', key })
+      yield () => {
+        /* v8 ignore next -- duplicate configuration is rejected, so this effect remains the key's unique owner. */
+        if (resolvers.get(key) !== entry) return
+        resolvers.delete(key)
+        changes.emit({ kind: 'lookup', key })
+      }
+    }, `typert.lookups.configure(${JSON.stringify(key)})`)
+  }
+
   private register<Host, Wire>(ctx: Context, key: string, provider: TypeRTLookupProvider<Host, Wire>): TypeRTDisposer {
     validateSegment('lookup key', key)
     validateSegment('lookup parameter', provider.parameter)
@@ -271,6 +321,10 @@ class LookupStore {
   }
 }
 
+interface LookupResolverEntry {
+  resolve(id: unknown): Promise<unknown>
+}
+
 function lookupDefinitionEquals(left: TypeRTLookupDefinition, right: TypeRTLookupDefinition): boolean {
   return left.parameter === right.parameter
     && left.wire === right.wire
diff --git a/packages/typert/registry/tests/typert.spec.ts b/packages/typert/registry/tests/typert.spec.ts
index 29654babf7..087cf00fc4 100644
--- a/packages/typert/registry/tests/typert.spec.ts
+++ b/packages/typert/registry/tests/typert.spec.ts
@@ -355,6 +355,40 @@ describe('TypertRegistry', () => {
     expect(ctx.typert.contexts.getClient('registryFixture')).toBeUndefined()
   })
 
+  it('configures an asynchronous lookup resolver independently of provider load order', async () => {
+    const ctx = await makeCtx()
+    const fallback = { id: 'fallback' }
+    const configured = { id: 'configured' }
+    const disposeResolver = ctx.typert.lookups.configure('fixture', async id =>
+      id === configured.id ? configured : undefined)
+
+    expect(ctx.typert.lookups.get('fixture')).toBeUndefined()
+    const disposeProvider = ctx.typert.lookups.register('fixture', {
+      parameter: 'agent',
+      wire: 'agentId',
+      hostTypeSymbol: '@fixture/agent#Agent',
+      wireTypeSymbol: '@fixture/session#SessionId',
+      resolve: id => id === fallback.id ? fallback : undefined,
+    })
+    await expect(ctx.typert.lookups.get('fixture')?.resolve('configured')).resolves.toBe(configured)
+    expect(() => ctx.typert.lookups.configure('fixture', () => undefined)).toThrow('already configured')
+
+    await disposeProvider()
+    expect(ctx.typert.lookups.get('fixture')).toBeUndefined()
+    const disposeReloadedProvider = ctx.typert.lookups.register('fixture', {
+      parameter: 'agent',
+      wire: 'agentId',
+      hostTypeSymbol: '@fixture/agent#Agent',
+      wireTypeSymbol: '@fixture/session#SessionId',
+      resolve: id => id === fallback.id ? fallback : undefined,
+    })
+    await expect(ctx.typert.lookups.get('fixture')?.resolve('configured')).resolves.toBe(configured)
+
+    await disposeResolver()
+    expect(ctx.typert.lookups.get('fixture')?.resolve('fallback')).toBe(fallback)
+    await disposeReloadedProvider()
+  })
+
   it('publishes provider changes, rejects duplicate providers, and disposes subscriptions', async () => {
     const ctx = await makeCtx()
     const changes: string[] = []
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
index a3e0643ace..510b8d3854 100644
--- a/packages/typert/type-meta/README.i18n.yaml
+++ b/packages/typert/type-meta/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/typert/type-meta/README.md
-README.md: 245df305efcf711486b2d3f32e40a8b415f2682e
-README.zh.md: 592aa5d027a52a7a277a90ba5d51f19101f055f6
+README.md: b394c843409e840b75bbb08b128614379e528001
+README.zh.md: 5bd9bb18289a0320e0603d8b373e60d7f1e3c7e5
diff --git a/packages/typert/type-meta/README.md b/packages/typert/type-meta/README.md
index 245df305ef..b394c84340 100644
--- a/packages/typert/type-meta/README.md
+++ b/packages/typert/type-meta/README.md
@@ -20,7 +20,7 @@ Decorator initializers retain markers in a module-private `WeakMap` keyed by the
 
 Business packages extend `TypeRTLookupMap` and `TypeRTContextMap` to associate Host objects or scoped Contexts with their wire identities. Generated artifacts extend `TypeRTRemoteMap`, `TypeRTRemoteContextMap`, and `TypeRTRemoteNamespaceMap` so Client imports expose only selected Remote methods. `InvocationDescriptor` is the shared runtime form consumed by the registry, Gateway, and Client API.
 
-Lookup and Context packages own both sides of their contract: declaration merging supplies the static association, while runtime providers register identity resolution with `ctx.typert`. Strict codecs carry generated schemas; `src-json` codecs identify the weaker source-launch path.
+Lookup and Context packages own both sides of their contract: declaration merging supplies the static association, while runtime providers register identity resolution with `ctx.typert`. A lookup provider supplies the stable declaration and default resolver, while Host composition may separately configure a synchronous or asynchronous resolver; policy rejections may use `TypeRTLookupFailure` to carry a failure value owned by the boundary adapter. Strict codecs carry generated schemas; `src-json` codecs identify the weaker source-launch path.
 
 ## Model Experience
 
diff --git a/packages/typert/type-meta/README.zh.md b/packages/typert/type-meta/README.zh.md
index 592aa5d027..5bd9bb1828 100644
--- a/packages/typert/type-meta/README.zh.md
+++ b/packages/typert/type-meta/README.zh.md
@@ -20,7 +20,7 @@ Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用
 
 业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联 Host 对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteContextMap` 和 `TypeRTRemoteNamespaceMap`，使 Client 导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、Gateway 和 Client API 使用的共享运行时形式。
 
-查找包与 Context 包同时负责其契约的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
+查找包与 Context 包同时负责其契约的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。lookup provider 提供稳定声明与默认 resolver，Host 组合可以另行配置同步或异步 resolver；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
 
 ## 模型体验
 
diff --git a/packages/typert/type-meta/src/index.ts b/packages/typert/type-meta/src/index.ts
index 3d782dbb77..7ded29fa4a 100644
--- a/packages/typert/type-meta/src/index.ts
+++ b/packages/typert/type-meta/src/index.ts
@@ -18,6 +18,25 @@ export function isTypeRTRemoteSegment(value: string): boolean {
   return value !== '.' && value !== '..' && TYPERT_REMOTE_SEGMENT_PATTERN.test(value)
 }
 
+/**
+ * A lookup policy rejection whose typed payload belongs to the active boundary adapter.
+ * Gateway adapters preserve this payload instead of collapsing it into an infrastructure failure.
+ */
+export class TypeRTLookupFailure<Failure = unknown> extends Error {
+  /** Adapter-owned failure returned to the caller. */
+  readonly failure: Failure
+
+  /**
+   * Wrap one adapter failure without exposing the rejected identity.
+   * @param failure - typed failure owned by the active boundary adapter.
+   */
+  constructor(failure: Failure) {
+    super('TypeRT lookup policy rejected the requested identity')
+    this.name = 'TypeRTLookupFailure'
+    this.failure = failure
+  }
+}
+
 export type {
   InvocationDescriptor,
   InvocationParameterDescriptor,
@@ -36,6 +55,7 @@ export type {
   TypeRTLookupHost,
   TypeRTLookupMap,
   TypeRTLookupProvider,
+  TypeRTLookupResolver,
   TypeRTLookupRegistry,
   TypeRTLookupWire,
   TypeRTRemoteContextApi,
diff --git a/packages/typert/type-meta/src/types.ts b/packages/typert/type-meta/src/types.ts
index 6de5c7f823..7831c08e37 100644
--- a/packages/typert/type-meta/src/types.ts
+++ b/packages/typert/type-meta/src/types.ts
@@ -176,7 +176,16 @@ export interface TypeRTRemoteContribution {
   readonly descriptors: readonly InvocationDescriptor[]
 }
 
-/** Runtime resolver for one declared Host object lookup. */
+/**
+ * Resolve one validated wire identity, synchronously or asynchronously.
+ * @param id - validated wire identity.
+ * @returns the Host object, or `undefined` when unavailable.
+ */
+export type TypeRTLookupResolver<Host = unknown, Wire = unknown> = (
+  id: Wire,
+) => Host | undefined | Promise<Host | undefined>
+
+/** Runtime provider for one declared Host object lookup. */
 export interface TypeRTLookupProvider<Host = unknown, Wire = unknown> {
   /** Source parameter name recognized by the SRC weak parser. */
   readonly parameter: string
@@ -187,11 +196,11 @@ export interface TypeRTLookupProvider<Host = unknown, Wire = unknown> {
   /** Canonical wire type symbol used by strict generation. */
   readonly wireTypeSymbol: string
   /**
-   * Resolve a wire identity to the current live Host object.
+   * Resolve a wire identity through the provider's default policy.
    * @param id - validated wire identity.
-   * @returns the live object, or `undefined` when it is unavailable.
+   * @returns the object, `undefined` when unavailable, or either asynchronously.
    */
-  resolve(id: Wire): Host | undefined
+  resolve(id: Wire): Host | undefined | Promise<Host | undefined>
 }
 
 /** Stable wire declaration retained after a lookup provider unloads. */
@@ -304,6 +313,20 @@ export interface TypeRTLookupRegistry {
       TypeRTLookupWire<TypeRTLookupMap[K]>
     >,
   ): TypeRTDisposer
+  /**
+   * Replace one provider's default resolution policy while this contribution is active.
+   * Configuration may precede provider registration; without a live provider, `get()` remains unavailable.
+   * @param key - lookup key whose wire declaration remains provider-owned.
+   * @param resolver - composition-owned resolver used by every lookup of this key.
+   * @returns disposer restoring the provider's default resolver.
+   */
+  configure<K extends StringKeyOf<TypeRTLookupMap>>(
+    key: K,
+    resolver: TypeRTLookupResolver<
+      TypeRTLookupHost<TypeRTLookupMap[K]>,
+      TypeRTLookupWire<TypeRTLookupMap[K]>
+    >,
+  ): TypeRTDisposer
   /**
    * Look up one provider by runtime key.
    * @param key - descriptor lookup key.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 79d38a43cd..e0adfb22c1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -3838,6 +3838,12 @@ importers:
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../../typert/type-meta
+      '@deepseek-ai/dsh-typert-registry':
+        specifier: workspace:^
+        version: link:../../typert/registry
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
         version: link:../../ui/user-approval

From bb61dc13f221fb9052a52a0c7e337fbd8e4c5898 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 15:48:29 +0800
Subject: [PATCH 142/516] refactor(api): colocate gateway and remote assembly

---
 ...08-02-typert-remote-method-calls.i18n.yaml |   4 +-
 .../2026-08-02-typert-remote-method-calls.md  |  24 ++-
 ...026-08-02-typert-remote-method-calls.zh.md |  24 ++-
 AGENTS.md                                     |   1 +
 apps/cli/composition.md                       |   4 +-
 apps/web/tests/assembled-boot.ts              |   6 +-
 docs/api-gateway.i18n.yaml                    |   4 +-
 docs/api-gateway.md                           |  21 +-
 docs/api-gateway.zh.md                        |  21 +-
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   2 +-
 docs/architecture.zh.md                       |   2 +-
 docs/capability-seams.md                      |   4 +-
 docs/config-catalog.md                        |   4 +-
 docs/cordis-catalog/services.md               |   2 +-
 docs/core-data-structures/typert.i18n.yaml    |   4 +-
 docs/core-data-structures/typert.md           |   8 +-
 docs/core-data-structures/typert.zh.md        |   8 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +-
 docs/development.zh.md                        |   2 +-
 docs/event-producer-consumer.md               |   2 +-
 docs/module-graph.md                          |  39 +++-
 knip.json                                     |   2 +-
 packages/README.i18n.yaml                     |   4 +-
 packages/README.md                            |   1 +
 packages/README.zh.md                         |   1 +
 .../{client/remotes => api}/README.i18n.yaml  |   6 +-
 packages/api/README.md                        |  17 ++
 packages/api/README.zh.md                     |  17 ++
 .../gateway}/README.i18n.yaml                 |   6 +-
 .../api-gateway => api/gateway}/README.md     |   6 +-
 .../api-gateway => api/gateway}/README.zh.md  |   6 +-
 .../api-gateway => api/gateway}/package.json  |   4 +-
 .../gateway}/src/client/index.ts              |  16 +-
 .../api-gateway => api/gateway}/src/index.ts  |   2 +-
 .../gateway}/src/invariant.ts                 |   8 +-
 .../api-gateway => api/gateway}/src/types.ts  |   2 +-
 .../gateway}/tests/client.spec.ts             |   0
 .../gateway}/tests/gateway.spec.ts            |   2 +-
 .../api-gateway => api/gateway}/tsconfig.json |   0
 packages/api/gateway/tsdown.config.ts         |   3 +
 packages/api/remotes/README.i18n.yaml         |   6 +
 packages/api/remotes/README.md                |  25 +++
 packages/api/remotes/README.zh.md             |  25 +++
 packages/{client => api}/remotes/package.json |  19 +-
 packages/api/remotes/src/agent-lookup.ts      | 193 ++++++++++++++++++
 .../remotes/src/client/index.ts               |  11 +-
 packages/api/remotes/src/index.ts             |  18 ++
 .../{client => api}/remotes/src/invariant.ts  |   8 +-
 .../remotes/tests/built-lib.e2e.ts            |  16 +-
 .../{client => api}/remotes/tsconfig.json     |  14 +-
 packages/api/remotes/tsdown.config.ts         |   3 +
 packages/bundle/base/cordis.patch.yml         |   2 +-
 packages/bundle/base/package.json             |   2 +-
 packages/bundle/web-app/cordis.patch.yml      |   4 +-
 packages/bundle/web-app/package.json          |   2 +-
 packages/client/remotes/README.md             |  22 --
 packages/client/remotes/README.zh.md          |  22 --
 packages/client/remotes/src/index.ts          |   4 -
 packages/client/remotes/tsdown.config.ts      |   3 -
 packages/client/runtime/package.json          |   6 +-
 packages/client/runtime/src/client/index.ts   |   2 +-
 packages/client/runtime/tsconfig.json         |   2 +-
 packages/client/ui-goal/package.json          |   6 +-
 packages/client/ui-goal/src/client/index.ts   |   2 +-
 packages/client/ui-goal/tsconfig.json         |   2 +-
 packages/host/api-gateway/tsdown.config.ts    |   3 -
 packages/host/apiproxy/package.json           |   5 +-
 packages/host/apiproxy/src/api-proxy.ts       | 161 ++-------------
 packages/host/apiproxy/tsconfig.json          |   9 +-
 packages/typert/type-meta/src/index.ts        |   1 +
 packages/typert/type-meta/src/types.ts        |  10 +
 pnpm-lock.yaml                                | 130 ++++++------
 scripts/gen-cordis-catalog.ts                 |   2 +-
 scripts/run-gates.ts                          |   2 +-
 scripts/type-equiv.manifest.json              |  10 +-
 .../verify-package-readme-model-experience.ts |   4 +-
 tsconfig.base.json                            |  12 +-
 tsconfig.client.json                          |   4 +-
 tsconfig.host.json                            |   2 +-
 vitest.config.ts                              |   4 +-
 82 files changed, 645 insertions(+), 432 deletions(-)
 rename packages/{client/remotes => api}/README.i18n.yaml (56%)
 create mode 100644 packages/api/README.md
 create mode 100644 packages/api/README.zh.md
 rename packages/{host/api-gateway => api/gateway}/README.i18n.yaml (56%)
 rename packages/{host/api-gateway => api/gateway}/README.md (86%)
 rename packages/{host/api-gateway => api/gateway}/README.zh.md (86%)
 rename packages/{host/api-gateway => api/gateway}/package.json (92%)
 rename packages/{host/api-gateway => api/gateway}/src/client/index.ts (96%)
 rename packages/{host/api-gateway => api/gateway}/src/index.ts (99%)
 rename packages/{host/api-gateway => api/gateway}/src/invariant.ts (77%)
 rename packages/{host/api-gateway => api/gateway}/src/types.ts (97%)
 rename packages/{host/api-gateway => api/gateway}/tests/client.spec.ts (100%)
 rename packages/{host/api-gateway => api/gateway}/tests/gateway.spec.ts (99%)
 rename packages/{host/api-gateway => api/gateway}/tsconfig.json (100%)
 create mode 100644 packages/api/gateway/tsdown.config.ts
 create mode 100644 packages/api/remotes/README.i18n.yaml
 create mode 100644 packages/api/remotes/README.md
 create mode 100644 packages/api/remotes/README.zh.md
 rename packages/{client => api}/remotes/package.json (64%)
 create mode 100644 packages/api/remotes/src/agent-lookup.ts
 rename packages/{client => api}/remotes/src/client/index.ts (64%)
 create mode 100644 packages/api/remotes/src/index.ts
 rename packages/{client => api}/remotes/src/invariant.ts (70%)
 rename packages/{client => api}/remotes/tests/built-lib.e2e.ts (95%)
 rename packages/{client => api}/remotes/tsconfig.json (63%)
 create mode 100644 packages/api/remotes/tsdown.config.ts
 delete mode 100644 packages/client/remotes/README.md
 delete mode 100644 packages/client/remotes/README.zh.md
 delete mode 100644 packages/client/remotes/src/index.ts
 delete mode 100644 packages/client/remotes/tsdown.config.ts
 delete mode 100644 packages/host/api-gateway/tsdown.config.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index c76dabca3c..9ba0cf8dc1 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: d91f6f173c1b56efcd21d3136392837e61f54aae
-2026-08-02-typert-remote-method-calls.zh.md: 0c548522d1137f0e0002a740d12ca0b796da5e39
+2026-08-02-typert-remote-method-calls.md: c4f3a5b94bf25b4581b9430cfcb4f02f707e0749
+2026-08-02-typert-remote-method-calls.zh.md: e11d8ebe42d44cc9805e942a31f13f7ae847815a
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index d91f6f173c..c4f3a5b94b 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -20,7 +20,9 @@ A business Service extends `GatewayService` and declares callable methods with `
 
 The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. The `.d.ts` exposes only methods marked with a Remote decorator and refers to the business package's single public type symbols. The `.d.ts.map` navigates consumer API methods back to their Host business method implementations. The `.js` carries endpoint, parameter, Context, and Zod information for the same contract. At the assembly layer, the Browser Client mounts the required Remote JS contributions onto the Client API Service. The projection and API abstraction remain platform-independent so that a future TUI can reuse them.
 
-`@deepseek-ai/dsh-host-api-gateway`, located at `packages/host/api-gateway`, provides two symmetric faces: its default entry provides Host `ctx.typertGateway`, while its `/client` entry provides consumer-side `ctx.api`. Each side consumes a locally generated `InvocationDescriptor` from the same model; descriptors are not sent over the wire. The Remote data protocol runs over Connection's shared `/api` RPC channel. The business calling interface does not change when Connection migrates from HTTP to WebSocket.
+`@deepseek-ai/dsh-api-gateway`, located at `packages/api/gateway`, provides two symmetric faces: its default entry provides Host `ctx.typertGateway`, while its `/client` entry provides consumer-side `ctx.api`. Each side consumes a locally generated `InvocationDescriptor` from the same model; descriptors are not sent over the wire. The Remote data protocol runs over Connection's shared `/api` RPC channel. The business calling interface does not change when Connection migrates from HTTP to WebSocket.
+
+`@deepseek-ai/dsh-api-remotes`, located at `packages/api/remotes`, is the BFF layer above the Gateway. Its Host entry owns Agent/Session identity resolution and TypeRT lookup configuration; its `/client` entry selects the generated Remote contributions exposed by the application. The Client entry consumes the shared `TypeRTClientApi` contract through Cordis rather than importing the concrete Gateway implementation.
 
 ## Components and Cordis services
 
@@ -29,10 +31,10 @@ The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. T
 | `@deepseek-ai/dsh-type-meta` | Declares only the minimal `ctx.typert` protocol | `GatewayService`, decorators, binding fallback, descriptors, lookup/Context, and the Remote map; no dependency on the compiler, Zod, Connection, or Browser |
 | TypeRT registry | `ctx.typert` | Separately stores reflection for the current environment, imported Remote contributions, lookup providers, and Context providers |
 | TypeRT generator/loader | No new business service | Generates three kinds of `lib` artifacts from the Host/Client Programs and registers the current environment's artifacts with `ctx.typert` |
-| Host API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, invokes methods, and encodes results |
+| API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, invokes methods, and encodes results |
 | Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, the shared `/api` route, RPC envelope, rpcId, serialization, trust, error transport, TypeRT interception, and legacy API Proxy fallback |
-| Host API Gateway's Client face | `ctx.api` | Mounts Remote contributions, materializes root and scoped APIs, and delegates canonical calls to `ctx.connection.rpc` |
-| Client Remotes | No new service | Serves as the only Remote facade for Client business code, selecting and mounting `/remote` contributions while exposing the Gateway Client face and the selected API declarations |
+| API Gateway's Client face | `ctx.api` | Mounts Remote contributions, materializes root and scoped APIs, and delegates canonical calls to `ctx.connection.rpc` |
+| API Remotes | No new service | Owns Host Agent/Session lookup policy and serves as the only Client business facade, selecting and mounting `/remote` contributions while exposing the selected API declarations |
 | Agent/Session owning packages | Existing domain services | Provide both static interface merges and runtime lookup/Context providers |
 | Business packages such as Goal | Existing business Services | Declare only bindings, Remote methods, and canonical DTOs, and export the generated `/remote` subpath |
 
@@ -162,7 +164,7 @@ Every registration returns a disposer owned by the caller's Cordis fiber. Client
 
 The lookup registry retains the stable wire declaration after its live resolver unloads. SRC parsing continues to classify the parameter as a lookup, while invocation fails with `lookup-unavailable`; it never reclassifies the incoming ID as an ordinary JSON business object. Re-registering the same key with different parameter, wire, or canonical type symbols fails for the lifetime of that TypeRT Service.
 
-Business-object packages own stable declarations and default resolvers through `register()`; Host composition supplies an effect-scoped asynchronous policy for the same key through `configure()`. Configuration may precede provider registration, but does not by itself make a lookup available without a live provider; unloading the configuration restores the provider's default resolver. The standard Web Host's API Proxy configures the same `agentFor()` for `agent` and `session`: live Agents are reused, ordinary cold sessions are resumed automatically, concurrent resumes are deduplicated by Session ID, and the subagent ownership fence returns the existing `agent-busy`. The `session` resolver returns the resolved Agent's Session, so the two parameter kinds do not create separate resume lifecycles.
+Business-object packages own stable declarations and default resolvers through `register()`; Host composition supplies an effect-scoped asynchronous policy for the same key through `configure()`. Configuration may precede provider registration, but does not by itself make a lookup available without a live provider; unloading the configuration restores the provider's default resolver. API Remotes creates the shared `agentFor()` resolver for `agent` and `session`: live Agents are reused, ordinary cold sessions are resumed automatically, concurrent resumes are deduplicated by Session ID, and the subagent ownership fence returns the existing `agent-busy`. The standard Web API Proxy supplies its Agent defaults and scope setup and consumes that resolver for legacy methods. The `session` resolver returns the resolved Agent's Session, so the two parameter kinds do not create separate resume lifecycles.
 
 The registry's Host root entry has the complete `TypeRTService` interface merge. The registry implementation shared by Host and Client lives in a separate module without environment declarations. The registry's `/client` entry imports only that shared implementation and does not pass through the Host root entry, so it cannot bring Host Cordis declarations into the Client Program.
 
@@ -295,7 +297,7 @@ TypeRT.local    当前环境自己的反射模型
 TypeRT.remotes  已导入的 Remote contribution
 ```
 
-`@deepseek-ai/dsh-client-remotes/client` centrally loads the required Remote contributions:
+`@deepseek-ai/dsh-api-remotes/client` centrally loads the required Remote contributions:
 
 ```text
 import goalsRemote from '@deepseek-ai/dsh-goal/remote'
@@ -305,7 +307,7 @@ ctx.api.mount(goalsRemote)
 ctx.api.mount(sessionsRemote)
 ```
 
-Client business packages depend only on `@deepseek-ai/dsh-client-remotes/client`, not directly on the Host API Gateway or the runtime entry of each business `/remote`. Client Remotes itself depends on the Gateway Client face and re-exports declarations so the selected Remote map reaches business compilation. Adding or removing a complete Client capability changes only this assembly point.
+Client business packages depend only on `@deepseek-ai/dsh-api-remotes/client`, not directly on the API Gateway or the runtime entry of each business `/remote`. API Remotes consumes the shared `TypeRTClientApi` contract and Cordis `ctx.api` service, then re-exports declarations so the selected Remote map reaches business compilation. Adding or removing a complete Client capability changes only this assembly point.
 
 `ctx.api.mount()` registers a contribution with `TypeRT.remotes`, and its disposer is owned by the Cordis fiber that called the method. Duplicate endpoints, conflicting invocation modes for the same namespace and method, or conflicts between a descriptor and an existing type identity fail immediately.
 
@@ -449,11 +451,11 @@ The Gateway registers only its ownership matcher and RPC handler with Connection
 - `@deepseek-ai/dsh-type-meta`: lightweight protocols for decorators, bindings, lookup, Remote Context, and descriptors.
 - TypeRT generator: analyzes Host/Client Programs, generates local faces and Remote consumer projections, and emits canonical symbol/Zod information.
 - TypeRT runtime: separately stores the current environment's local reflection and imported Remote contributions.
-- `@deepseek-ai/dsh-host-api-gateway`: its default entry associates Host definitions with Services, claims Remote endpoints, performs lookup, resolves Context receivers, invokes methods, encodes results, and registers an `/api` interceptor with Connection; its `/client` entry mounts Remote contributions, creates strict API methods, and delegates calls to `ctx.connection.rpc`. The entries share the Remote protocol but do not import each other's Cordis interface merges.
-- `@deepseek-ai/dsh-client-remotes`: the only Remote facade depended on by Client business code; directly depends on the Gateway Client face, selects `/remote` contributions, and exposes the merged API types to business packages.
+- `@deepseek-ai/dsh-api-gateway`: its default entry associates Host definitions with Services, claims Remote endpoints, performs lookup, resolves Context receivers, invokes methods, encodes results, and registers an `/api` interceptor with Connection; its `/client` entry mounts Remote contributions, creates strict API methods, and delegates calls to `ctx.connection.rpc`. The entries share the Remote protocol but do not import each other's Cordis interface merges.
+- `@deepseek-ai/dsh-api-remotes`: the BFF layer; owns the Host Agent/Session resolver, selects Client `/remote` contributions, and exposes the merged API types to business packages through the shared `TypeRTClientApi` contract.
 - Connection: owns the single HTTP Server/future WebSocket carrier, shared `/api` route and composite FetchHandler, API Proxy fallback, RPC envelope, rpcId, serialization, trust, and error transport.
 - Business-object packages such as Agent/Session: own lookup, Context providers, canonical ID types, and public type-only entries.
-- API Proxy Host composition: configures cold resume, concurrent deduplication, and subagent ownership policy for `agent`/`session` lookups through the existing `agentFor()`.
+- API Proxy Host composition: supplies Web Agent defaults and scope setup to API Remotes and consumes the same `agentFor()` for legacy methods.
 - Business Service packages: declare bindings, Remote methods, and their request/result types, and export the generated `/remote` subpath.
 
 ## Shipped scope and deferred work
@@ -462,6 +464,8 @@ The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client AP
 
 Connection supplies the shared-channel interceptor and current HTTP carrier mapping. WebSocket migration, the TUI runtime and carrier, TUI Agent Scope wiring, Permission/Approval state machines, Session event streams, call authorization, retries, idempotency, and cross-version protocol compatibility remain outside this decision.
 
+The package topology is `api/remotes → api/gateway → client/connection → host/webserver`. Connection and WebServer retain their existing paths in this change; moving them later to `api/connection` and `api/webserver` changes package placement rather than these service boundaries. The legacy API Proxy likewise remains under `host/apiproxy` as the fallback for methods not yet migrated to Remote.
+
 ## Alternatives considered
 
 **Continue using the central API Proxy package.** This would require business methods, Host routes, and Client interfaces to be declared repeatedly in several locations. It would also keep direct calls, stateful interactions, and event streams tied to the same lifecycle, so this alternative is rejected.
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 0c548522d1..e11d8ebe42 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -20,7 +20,9 @@ Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以
 
 Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client API Service；该投影和 API 抽象保持平台无关，以便未来 TUI 复用。
 
-`@deepseek-ai/dsh-host-api-gateway` 在 `packages/host/api-gateway` 内提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.api`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在 Connection 共享的 `/api` RPC channel 上；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
+`@deepseek-ai/dsh-api-gateway` 位于 `packages/api/gateway`，提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.api`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在 Connection 共享的 `/api` RPC channel 上；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
+
+`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientApi` 契约，而不导入具体 Gateway 实现。
 
 ## 组件和 Cordis 服务
 
@@ -29,10 +31,10 @@ Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只
 | `@deepseek-ai/dsh-type-meta` | 只声明 `ctx.typert` 的最小协议 | `GatewayService`、decorator、binding 回退、descriptor、lookup/Context 和 Remote map；不依赖 compiler、Zod、Connection 或 Browser |
 | TypeRT registry | `ctx.typert` | 分开保存当前环境 reflection、导入的 Remote contribution、lookup provider 和 Context provider |
 | TypeRT generator/loader | 无新增业务服务 | 从 Host/Client Program 生成三类 `lib` 产物，并把当前环境产物注册到 `ctx.typert` |
-| Host API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service，解码参数、解析 receiver、调用方法和编码结果 |
+| API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service，解码参数、解析 receiver、调用方法和编码结果 |
 | Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、共享 `/api` route、RPC envelope、rpcId、序列化、trust、错误传输、TypeRT 拦截和旧 API Proxy 回退 |
-| Host API Gateway 的 Client face | `ctx.api` | mount Remote contribution，实体化根 API 和 scoped API，把规范调用交给 `ctx.connection.rpc` |
-| Client Remotes | 无新增服务 | 作为 Client 业务的唯一 Remote facade，选择并挂载 `/remote` contribution，同时传递 Gateway Client face 和所选 API 的类型声明 |
+| API Gateway 的 Client face | `ctx.api` | mount Remote contribution，实体化根 API 和 scoped API，把规范调用交给 `ctx.connection.rpc` |
+| API Remotes | 无新增服务 | 负责 Host Agent/Session lookup 策略，并作为 Client 业务的唯一 facade，选择并挂载 `/remote` contribution，同时暴露所选 API 声明 |
 | Agent/Session owning 包 | 既有领域服务 | 同时提供静态 interface merge 与运行时 lookup/Context provider |
 | Goal 等业务包 | 既有业务 Service | 只声明 binding、Remote 方法和唯一 DTO，并导出生成的 `/remote` 子路径 |
 
@@ -162,7 +164,7 @@ ctx.typert.contexts  Host Context resolver 与 Client Context binder
 
 lookup 注册表会在活 resolver 卸载后保留稳定的 wire 声明。SRC 解析仍会把该参数归类为 lookup，而调用会以 `lookup-unavailable` 失败；系统绝不会把传入的 ID 重新归类为普通 JSON 业务对象。在同一个 TypeRT Service 的生命周期内，以不同参数、wire 或规范类型 symbol 重新注册同一 key 会直接失败。
 
-业务对象包通过 `register()` 拥有稳定声明和默认 resolver；Host 组合通过 `configure()` 为同一个 key 提供 effect-scoped 异步策略。配置可以先于 provider 注册，但没有活 provider 时不会单独形成可用 lookup；配置卸载后恢复 provider 默认 resolver。标准 Web Host 的 API Proxy 为 `agent` 和 `session` 配置同一套 `agentFor()`：live Agent 直接复用，普通冷会话自动恢复，并发恢复按 Session ID 去重，subagent ownership fence 则返回既有 `agent-busy`。`session` resolver 返回解析所得 Agent 的 Session，因而两种参数不会产生两套恢复生命周期。
+业务对象包通过 `register()` 拥有稳定声明和默认 resolver；Host 组合通过 `configure()` 为同一个 key 提供 effect-scoped 异步策略。配置可以先于 provider 注册，但没有活 provider 时不会单独形成可用 lookup；配置卸载后恢复 provider 默认 resolver。API Remotes 为 `agent` 和 `session` 创建共享的 `agentFor()` resolver：live Agent 直接复用，普通冷会话自动恢复，并发恢复按 Session ID 去重，subagent ownership fence 则返回既有 `agent-busy`。标准 Web API Proxy 提供 Agent 默认值和 scope 设置，并让旧方法使用该 resolver。`session` resolver 返回解析所得 Agent 的 Session，因而两种参数不会产生两套恢复生命周期。
 
 Registry 的 Host 根入口拥有完整 `TypeRTService` interface merge；Host 与 Client 共用的 registry 实现位于无环境声明的独立模块。Registry `/client` 入口只引用该共享实现，不经过 Host 根入口，因此不会把 Host Cordis 声明带入 Client Program。
 
@@ -295,7 +297,7 @@ TypeRT.local    当前环境自己的反射模型
 TypeRT.remotes  已导入的 Remote contribution
 ```
 
-`@deepseek-ai/dsh-client-remotes/client` 集中加载需要的 Remote contribution：
+`@deepseek-ai/dsh-api-remotes/client` 集中加载需要的 Remote contribution：
 
 ```text
 import goalsRemote from '@deepseek-ai/dsh-goal/remote'
@@ -305,7 +307,7 @@ ctx.api.mount(goalsRemote)
 ctx.api.mount(sessionsRemote)
 ```
 
-Client 业务包只引用 `@deepseek-ai/dsh-client-remotes/client`，不直接依赖 Host API Gateway 或各业务 `/remote` 运行时入口。Client Remotes 自己依赖 Gateway Client face，并通过声明 re-export 把所选 Remote map 传给业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
+Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientApi` 契约和 Cordis `ctx.api` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
 
 `ctx.api.mount()` 把 contribution 注册到 `TypeRT.remotes`，并由调用该方法的 Cordis fiber 持有 disposer。endpoint 重复、同一 namespace/method 模式冲突或 descriptor 与现有类型身份冲突时直接失败。
 
@@ -449,11 +451,11 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 - `@deepseek-ai/dsh-type-meta`：轻量 decorator、binding、lookup、Remote Context 和 descriptor 协议。
 - TypeRT generator：分析 Host/Client Program，生成本地 face 和 Remote 消费端投影，并生成规范 symbol/Zod 信息。
 - TypeRT runtime：分别保存当前环境的 local reflection 与导入的 Remote contribution。
-- `@deepseek-ai/dsh-host-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 API 方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
-- `@deepseek-ai/dsh-client-remotes`：Client 业务唯一依赖的 Remote facade；直接依赖 Gateway Client face，选择 `/remote` contributions，并向业务包传递合并后的 API 类型。
+- `@deepseek-ai/dsh-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 API 方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
+- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientApi` 契约向业务包暴露合并后的 API 类型。
 - Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、共享 `/api` route 与复合 FetchHandler、API Proxy 回退、RPC envelope、rpcId、序列化、trust 和错误传输。
 - Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
-- API Proxy Host 组合：用既有 `agentFor()` 配置 `agent`/`session` lookup 的冷恢复、并发去重和 subagent ownership 策略。
+- API Proxy Host 组合：向 API Remotes 提供 Web Agent 默认值和 scope 设置，并让旧方法使用同一个 `agentFor()`。
 - 业务 Service 包：声明 binding、Remote 方法及其 request/result 类型，并导出生成的 `/remote` 子路径。
 
 ## 已交付范围与后续工作
@@ -462,6 +464,8 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 
 Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebSocket 迁移、TUI runtime 与 carrier、TUI Agent Scope 接线、Permission/Approval 状态机、Session 事件流、调用授权、重试、幂等及跨版本协议兼容均不属于本决策。
 
+包拓扑为 `api/remotes → api/gateway → client/connection → host/webserver`。Connection 与 WebServer 在本次变更中保留既有路径；后续将它们移到 `api/connection` 和 `api/webserver` 只会改变包位置，不会改变这些服务边界。旧 API Proxy 同样保留在 `host/apiproxy` 下，作为尚未迁移到 Remote 的方法的回退路径。
+
 ## Alternatives considered
 
 **继续使用中央 API Proxy 包。** 该方案要求业务方法、Host 路由和 Client 接口在多个位置重复声明，也会继续把直接调用、带状态交互和事件流绑在同一生命周期中，因此不采用。
diff --git a/AGENTS.md b/AGENTS.md
index 0d27b20df0..c265d3cf32 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,6 +12,7 @@ DeepSeek Harness SDK is a plugin-based agent harness on vendored Cordis: **every
 vendor/      Vendored Cordis source — manifest + sync procedure in vendor/README.md
 packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
+  api/         Remote BFF assembly and TypeRT RPC gateway
   typert/      type graph generator, loader, and runtime registry
   llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
   bash/        bash executor seam + local/pwsh impls + model-facing shell tools
diff --git a/apps/cli/composition.md b/apps/cli/composition.md
index 0246f6163f..45dc52561a 100644
--- a/apps/cli/composition.md
+++ b/apps/cli/composition.md
@@ -22,7 +22,7 @@ flowchart LR
   cfg --> plugin_dsh_base_typert
   plugin_dsh_base_typert_loader["typert-loader<br/>@deepseek-ai/dsh-typert-loader"]
   cfg --> plugin_dsh_base_typert_loader
-  plugin_dsh_base_typert_gateway["typert-gateway<br/>@deepseek-ai/dsh-host-api-gateway"]
+  plugin_dsh_base_typert_gateway["typert-gateway<br/>@deepseek-ai/dsh-api-gateway"]
   cfg --> plugin_dsh_base_typert_gateway
   plugin_dsh_base_session_title["session-title<br/>@deepseek-ai/dsh-session-title"]
   cfg --> plugin_dsh_base_session_title
@@ -167,7 +167,7 @@ flowchart LR
 | `session` | `@deepseek-ai/dsh-session` |
 | `typert` | `@deepseek-ai/dsh-typert-registry` |
 | `typert-loader` | `@deepseek-ai/dsh-typert-loader` |
-| `typert-gateway` | `@deepseek-ai/dsh-host-api-gateway` |
+| `typert-gateway` | `@deepseek-ai/dsh-api-gateway` |
 | `session-title` | `@deepseek-ai/dsh-session-title` |
 | `session-title-llm` | `@deepseek-ai/dsh-session-title-first-message-llm` |
 | `user-interaction` | `@deepseek-ai/dsh-user-interaction` |
diff --git a/apps/web/tests/assembled-boot.ts b/apps/web/tests/assembled-boot.ts
index ebb2aa513a..729428e47b 100644
--- a/apps/web/tests/assembled-boot.ts
+++ b/apps/web/tests/assembled-boot.ts
@@ -18,9 +18,9 @@ import { AppWebEntry } from '@deepseek-ai/dsh-client-web'
 const PLUGINS: readonly (WebBootEntry & { bundlePath: string })[] = [
   { id: '@deepseek-ai/dsh-typert-registry', bundlePath: 'packages/typert/registry/lib/client.js', url: '/plugins/typert-registry.js', rev: 'fx', inject: [], immediately: true },
   { id: '@deepseek-ai/dsh-client-connection', bundlePath: 'packages/client/connection/lib/client.js', url: '/plugins/connection.js', rev: 'fx', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-host-api-gateway', bundlePath: 'packages/host/api-gateway/lib/client.js', url: '/plugins/api-gateway.js', rev: 'fx', inject: ['@deepseek-ai/dsh-typert-registry', '@deepseek-ai/dsh-client-connection'], immediately: true },
-  { id: '@deepseek-ai/dsh-client-remotes', bundlePath: 'packages/client/remotes/lib/client.js', url: '/plugins/client-remotes.js', rev: 'fx', inject: ['@deepseek-ai/dsh-host-api-gateway'], immediately: true },
-  { id: '@deepseek-ai/dsh-client-runtime', bundlePath: 'packages/client/runtime/lib/client.js', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection', '@deepseek-ai/dsh-client-remotes', '@deepseek-ai/dsh-typert-registry'], immediately: true },
+  { id: '@deepseek-ai/dsh-api-gateway', bundlePath: 'packages/api/gateway/lib/client.js', url: '/plugins/api-gateway.js', rev: 'fx', inject: ['@deepseek-ai/dsh-typert-registry', '@deepseek-ai/dsh-client-connection'], immediately: true },
+  { id: '@deepseek-ai/dsh-api-remotes', bundlePath: 'packages/api/remotes/lib/client.js', url: '/plugins/api-remotes.js', rev: 'fx', inject: ['@deepseek-ai/dsh-api-gateway'], immediately: true },
+  { id: '@deepseek-ai/dsh-client-runtime', bundlePath: 'packages/client/runtime/lib/client.js', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection', '@deepseek-ai/dsh-api-remotes', '@deepseek-ai/dsh-typert-registry'], immediately: true },
   { id: '@deepseek-ai/dsh-client-ui-theme', bundlePath: 'packages/client/ui-theme/lib/client.js', url: '/plugins/ui-theme.js', rev: 'fx', inject: [], immediately: true },
   { id: '@deepseek-ai/dsh-client-locale', bundlePath: 'packages/client/locale/lib/client.js', url: '/plugins/locale.js', rev: 'fx', inject: [], immediately: true },
   { id: '@deepseek-ai/dsh-client-ui-layout', bundlePath: 'packages/client/ui-layout/lib/client.js', url: '/plugins/ui-layout.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime'] },
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index 58891890d3..05038eb8b9 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.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 docs/api-gateway.md
-api-gateway.md: 2e0717fd7b0e5b9ca33d650ffad7ac454046f780
-api-gateway.zh.md: 4d1beebf92cae702dac323cdd974b6220091a214
+api-gateway.md: 090758d58306d5ea806567f0de710a1c1f5ed747
+api-gateway.zh.md: 9d7286b6b86918f3bc1e7a6cdd9bdf04447abc57
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index 2e0717fd7b..090758d583 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -61,7 +61,7 @@ The Client uses concrete functions on ordinary objects, not a JavaScript Proxy.
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { AgentContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { Context } from 'cordis'
-import type {} from '@deepseek-ai/dsh-client-remotes/client'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
 
 declare const ctx: Context
 declare const agentCtx: AgentContext
@@ -71,9 +71,9 @@ await ctx.api.goals.create(agentId, { objective: 'ship it' })
 await agentCtx.goals.create({ objective: 'ship it' })
 ```
 
-Client applications assemble only `@deepseek-ai/dsh-client-remotes`. That package imports the `/remote` subpaths of selected business packages as runtime values, mounts their contributions on `ctx.api`, and re-exports the declaration merges from the same files. Adding a Host Remote package is an explicit choice by the Client composition owner; business components do not need to load the Host API Gateway or the business package's Remote JS separately.
+Client applications assemble only `@deepseek-ai/dsh-api-remotes`. That package imports the `/remote` subpaths of selected business packages as runtime values, mounts their contributions on `ctx.api`, and re-exports the declaration merges from the same files. Adding a Host Remote package is an explicit choice by the Client composition owner; business components do not need to load the TypeRT Gateway or the business package's Remote JS separately.
 
-A future TUI can assemble the same React-independent `client-remotes` and `ctx.api` contract, so the Host methods visible to it are likewise limited to the Remote methods selected at generation time. This document does not define or implement the TUI composition.
+A future TUI can assemble the same React-independent `api-remotes` and `ctx.api` contract, so the Host methods visible to it are likewise limited to the Remote methods selected at generation time. This document does not define or implement the TUI composition.
 
 ## Component responsibilities
 
@@ -82,12 +82,13 @@ A future TUI can assemble the same React-independent `client-remotes` and `ctx.a
 | Shared | `@deepseek-ai/dsh-type-meta` | Declares decorators, Gateway bindings, merge-extensible protocol maps, invocation descriptors, and provider types; starts no TypeScript analysis and registers no Cordis services |
 | Build | `@deepseek-ai/dsh-typert-generator` | Strictly analyzes Remote signatures, the type graph, lookups, Contexts, and source locations from the Host `ts.Program`, then generates Host and Host-for-Client artifacts |
 | Host | `@deepseek-ai/dsh-typert-registry` and Loader | Places generated Host descriptors, schemas, and business-package registrations in `ctx.typert`, and holds lookup and Context providers |
-| Host | `@deepseek-ai/dsh-host-api-gateway` | Provides `ctx.typertGateway`, claims Remote endpoints, resolves objects or Contexts, invokes live Cordis services, and validates boundaries |
-| Client | `@deepseek-ai/dsh-host-api-gateway/client` | Provides `ctx.api`, mounts generated descriptors as concrete methods, and initiates, validates, and cancels calls through the Connection |
-| Client | `@deepseek-ai/dsh-client-remotes/client` | Explicitly selects and mounts the `/remote` contributions allowed by the application and brings the corresponding declaration merges into business code |
+| Host | `@deepseek-ai/dsh-api-remotes` | Owns the application Agent/Session identity policy and configures the corresponding TypeRT lookups |
+| Host | `@deepseek-ai/dsh-api-gateway` | Provides `ctx.typertGateway`, claims Remote endpoints, resolves objects or Contexts, invokes live Cordis services, and validates boundaries |
+| Client | `@deepseek-ai/dsh-api-gateway/client` | Provides `ctx.api`, mounts generated descriptors as concrete methods, and initiates, validates, and cancels calls through the Connection |
+| Client | `@deepseek-ai/dsh-api-remotes/client` | Explicitly selects and mounts the `/remote` contributions allowed by the application and brings the corresponding declaration merges into business code |
 | Both | `@deepseek-ai/dsh-client-connection` | Provides the RPC carrier, request correlation, trust boundary, cancellation, response envelope, and current `/api` HTTP bridge |
 
-The Host API Gateway package owns the Host dispatcher and Client API as peer entries, but the two builds never enter the same `ts.Program`. The Host entry does not import the Client Cordis `Context` merge, and the Client entry does not import the Host Gateway service.
+The API Gateway package owns the Host dispatcher and Client API as peer entries, but the two builds never enter the same `ts.Program`. The Host entry does not import the Client Cordis `Context` merge, and the Client entry does not import the Host Gateway service.
 
 ## Strict generation pipeline
 
@@ -99,7 +100,7 @@ Each contributing business package writes generated files to its own `lib/` dire
 |---|---|---|
 | `typert.host.js` | Host Loader | Runtime reflection for the Host face, strict invocation descriptors, and schema registration values |
 | `typert.host.d.ts` | Host type system | Generated declarations for the Host face |
-| `typert.remote-client.js` | `client-remotes` | A mountable `TypeRTRemoteContribution` containing strict descriptors and runtime codecs |
+| `typert.remote-client.js` | `api-remotes` | A mountable `TypeRTRemoteContribution` containing strict descriptors and runtime codecs |
 | `typert.remote-client.d.ts` | Client type system | Declaration merges for `TypeRTRemoteNamespaceMap` and `TypeRTRemoteContextMap`, plus Client-safe type references |
 | `typert.remote-client.d.ts.map` | Editor | Maps generated method properties back to Remote method declarations in the Host package |
 
@@ -117,7 +118,7 @@ The Connection performs the unified trust check for `/api` before the HTTP bridg
 
 For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. It requires the fields in `args` to match the descriptor exactly, validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, invokes the service method targeted by the binding, and validates the return value. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails at the boundary before entering or after leaving business code.
 
-The lookup provider's `register()` supplies both the stable declaration and the default resolver; `configure()` supplies a resolver owned by Host composition that may execute asynchronously and is scoped to an effect lifetime. Configuration may precede provider mounting; without a provider, invocation still fails with `lookup-unavailable`, and unloading the configuration restores the provider's default policy. The standard Web Host's API Proxy configures the same `agentFor()` semantics for `agent` and `session`: it reuses a live Agent, automatically resumes ordinary cold sessions, deduplicates concurrent resumes, and rejects identities owned by subagent routing; the `session` lookup returns that Agent's Session. Resume failures and ownership fences pass through unchanged as existing RPC errors rather than being collapsed into the Gateway's `internal` error.
+The lookup provider's `register()` supplies both the stable declaration and the default resolver; `configure()` supplies a resolver owned by Host composition that may execute asynchronously and is scoped to an effect lifetime. Configuration may precede provider mounting; without a provider, invocation still fails with `lookup-unavailable`, and unloading the configuration restores the provider's default policy. API Remotes owns the standard `agentFor()` semantics for `agent` and `session`: it reuses a live Agent, automatically resumes ordinary cold sessions, deduplicates concurrent resumes, and rejects identities owned by subagent routing; the `session` lookup returns that Agent's Session. The Web API Proxy supplies its Agent defaults and scope setup, then consumes the same resolver for legacy methods. Resume failures and ownership fences pass through unchanged as existing RPC errors rather than being collapsed into the Gateway's `internal` error.
 
 Unloading a Client contribution removes its descriptors and concrete methods together, aborts its in-flight calls, and makes stale method handles retained by external code reject further calls. A strict endpoint withdrawn on the Host also does not degrade to SRC inference, preventing a hot unload from silently weakening validation.
 
@@ -158,4 +159,6 @@ The running Client watcher consumes these generated files when it rebundles; wit
 
 Remote handles only unary method calls with one request and one result. Session event streams, pagination, incremental reduce, projection, and entity substreams require a separate data protocol and registration model; even when they reuse the Connection, they must not masquerade as Remote methods or enter invocation descriptors.
 
+The API layers are organized as `remotes → gateway → connection → webserver`. The BFF and TypeRT RPC layers live under `packages/api`; Connection and WebServer remain at `packages/client/connection` and `packages/host/webserver`, with service contracts that permit a later package-only move to `packages/api`. The legacy API Proxy remains at `packages/host/apiproxy` as the fallback for endpoints not yet migrated to Remote.
+
 Lookup policy is currently configured per key, so all `agent` or `session` parameters share the cold-resume behavior. If a Remote endpoint must accept live objects only, an explicit per-parameter or per-endpoint policy must be added later; the business method must not guess whether the object came from restoration.
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 4d1beebf92..9d7286b6b8 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -61,7 +61,7 @@ Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { AgentContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { Context } from 'cordis'
-import type {} from '@deepseek-ai/dsh-client-remotes/client'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
 
 declare const ctx: Context
 declare const agentCtx: AgentContext
@@ -71,9 +71,9 @@ await ctx.api.goals.create(agentId, { objective: 'ship it' })
 await agentCtx.goals.create({ objective: 'ship it' })
 ```
 
-Client 应用只装配 `@deepseek-ai/dsh-client-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，并向 `ctx.api` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 Host API Gateway 或业务包的 Remote JS。
+Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，并向 `ctx.api` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 TypeRT Gateway 或业务包的 Remote JS。
 
-未来的 TUI 可以装配同一个不依赖 React 的 `client-remotes` 与 `ctx.api` 契约，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
+未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.api` 契约，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
 
 ## 组件职责
 
@@ -82,12 +82,13 @@ Client 应用只装配 `@deepseek-ai/dsh-client-remotes`。该包以运行时值
 | 共享 | `@deepseek-ai/dsh-type-meta` | 声明 decorator、Gateway binding、可合并协议映射、调用描述符及提供方类型；不启动 TypeScript 分析，也不注册 Cordis 服务 |
 | 构建 | `@deepseek-ai/dsh-typert-generator` | 从 Host `ts.Program` 严格分析 Remote 签名、类型图、lookup、Context 与源码位置，并生成 Host 和 Host-for-Client 产物 |
 | Host | `@deepseek-ai/dsh-typert-registry` 与 Loader | 把生成的 Host 描述符、schema 及业务包注册项放入 `ctx.typert`，并持有 lookup 与 Context 提供方 |
-| Host | `@deepseek-ai/dsh-host-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或 Context，调用实时 Cordis Service 并校验边界 |
-| Client | `@deepseek-ai/dsh-host-api-gateway/client` | 提供 `ctx.api`，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
-| Client | `@deepseek-ai/dsh-client-remotes/client` | 显式选择并挂载本应用允许使用的 `/remote` 贡献，向业务代码带入对应的声明合并 |
+| Host | `@deepseek-ai/dsh-api-remotes` | 负责应用的 Agent/Session 身份策略，并配置对应的 TypeRT lookup |
+| Host | `@deepseek-ai/dsh-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或 Context，调用实时 Cordis Service 并校验边界 |
+| Client | `@deepseek-ai/dsh-api-gateway/client` | 提供 `ctx.api`，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
+| Client | `@deepseek-ai/dsh-api-remotes/client` | 显式选择并挂载本应用允许使用的 `/remote` 贡献，向业务代码带入对应的声明合并 |
 | 双侧 | `@deepseek-ai/dsh-client-connection` | 提供 RPC carrier、请求关联、信任边界、取消、响应 envelope 与当前 `/api` HTTP bridge |
 
-Host API Gateway 包同时拥有 Host dispatcher 与 Client API 两个对等入口，但两侧构建不会进入同一个 `ts.Program`。Host 入口不导入 Client 的 Cordis `Context` 合并，Client 入口也不导入 Host Gateway 服务。
+API Gateway 包同时拥有 Host dispatcher 与 Client API 两个对等入口，但两侧构建不会进入同一个 `ts.Program`。Host 入口不导入 Client 的 Cordis `Context` 合并，Client 入口也不导入 Host Gateway 服务。
 
 ## 严格生成链路
 
@@ -99,7 +100,7 @@ Host API Gateway 包同时拥有 Host dispatcher 与 Client API 两个对等入
 |---|---|---|
 | `typert.host.js` | Host Loader | Host face 的运行时反射、严格调用描述符和 schema 注册值 |
 | `typert.host.d.ts` | Host 类型系统 | Host face 的生成声明 |
-| `typert.remote-client.js` | `client-remotes` | 可挂载的 `TypeRTRemoteContribution`，包含严格描述符与运行时 codec |
+| `typert.remote-client.js` | `api-remotes` | 可挂载的 `TypeRTRemoteContribution`，包含严格描述符与运行时 codec |
 | `typert.remote-client.d.ts` | Client 类型系统 | `TypeRTRemoteNamespaceMap` 与 `TypeRTRemoteContextMap` 的声明合并及 Client-safe 类型引用 |
 | `typert.remote-client.d.ts.map` | 编辑器 | 将生成的方法属性映射回 Host 包中的 Remote 方法声明 |
 
@@ -117,7 +118,7 @@ Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共
 
 Gateway 每次调用都从当前注册表解析描述符和实时 Service，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或 Context provider 解析对象或接收者，最后调用 binding 指向的 Service 方法并校验返回值。缺少 provider、identity 未命中、binding 不一致、参数多缺、schema 失败和方法不存在都在进入或离开业务边界时失败。
 
-lookup provider 的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于 provider 挂载；没有 provider 时调用仍以 `lookup-unavailable` 失败，配置卸载后则恢复 provider 默认策略。标准 Web Host 的 API Proxy 为 `agent` 与 `session` 配置同一套 `agentFor()` 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。恢复失败和 ownership fence 通过既有 RPC error 原样返回，不折叠为 Gateway 的 `internal` 错误。
+lookup provider 的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于 provider 挂载；没有 provider 时调用仍以 `lookup-unavailable` 失败，配置卸载后则恢复 provider 默认策略。API Remotes 负责 `agent` 与 `session` 的标准 `agentFor()` 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。Web API Proxy 提供 Agent 默认值与 scope 设置，再让旧方法使用同一个 resolver。恢复失败和 ownership fence 通过既有 RPC error 原样返回，不折叠为 Gateway 的 `internal` 错误。
 
 Client 卸载一个贡献时会一起移除描述符和具体方法，中止其进行中的调用，并使外部仍持有的旧方法句柄拒绝继续调用。Host 上已经注册过的严格 endpoint 被撤回后也不会降级到 SRC 推断，以免热卸载悄然降低校验强度。
 
@@ -158,4 +159,6 @@ pnpm run build:lib:contracts
 
 Remote 只处理有单个请求与单个结果的一元方法调用。Session event stream、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
 
+API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务契约允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
+
 当前 lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。某个 Remote endpoint 若必须只接受 live 对象，需要后续增加显式的逐参数或逐 endpoint 策略，不能通过业务方法内部猜测恢复来源。
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 774bc296b1..0164acefcf 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: db5991d98dfbc6b04992d62d5a465c375c9a78b8
-architecture.zh.md: 2eb8c3834a6ffc3283c8aa669be481b534bb5914
+architecture.md: 35a73d4a307f5f48cc41cc496742a2ac210e8877
+architecture.zh.md: 185958221a477bb690e3ab5c91c33ba892ab2d73
diff --git a/docs/architecture.md b/docs/architecture.md
index db5991d98d..35a73d4a30 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -48,7 +48,7 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 | `ctx.credentials` | [`credentials/`](../packages/credentials/README.md) | named secret references resolved per operation, never inlined in configuration |
 | `ctx.directoryPicker` | [`host/directory-picker`](../packages/host/directory-picker/README.md) | GUI-host directory picking (`native`/`browse` interactions) |
 | `ctx.typert` | [`typert/registry`](../packages/typert/registry/README.md) | runtime registry for generated package reflection and live Zod schemas |
-| `ctx.typertGateway` | [`host/api-gateway`](../packages/host/api-gateway/README.md) | dispatches TypeRT Remote unary calls through the [API Gateway](api-gateway.md) |
+| `ctx.typertGateway` | [`api/gateway`](../packages/api/gateway/README.md) | dispatches TypeRT Remote unary calls through the [API Gateway](api-gateway.md) |
 | `ctx.invariants` | [`support/invariants`](../packages/support/invariants/README.md) | package-name-selected registry of package-owned runtime checks |
 
 ## Event
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 2eb8c3834a..185958221a 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -48,7 +48,7 @@
 | `ctx.credentials` | [`credentials/`](../packages/credentials/README.md) | 具名密钥引用，按操作解析，绝不内联进配置 |
 | `ctx.directoryPicker` | [`host/directory-picker`](../packages/host/directory-picker/README.md) | GUI 宿主目录选取（`native`／`browse` 交互） |
 | `ctx.typert` | [`typert/registry`](../packages/typert/registry/README.md) | 生成的包反射和实时 Zod schema 的运行时注册表 |
-| `ctx.typertGateway` | [`host/api-gateway`](../packages/host/api-gateway/README.md) | 通过 [API Gateway](api-gateway.md) 分发 TypeRT Remote 一元调用 |
+| `ctx.typertGateway` | [`api/gateway`](../packages/api/gateway/README.md) | 通过 [API Gateway](api-gateway.md) 分发 TypeRT Remote 一元调用 |
 | `ctx.invariants` | [`support/invariants`](../packages/support/invariants/README.md) | 按包名筛选包自有运行时检查的注册表 |
 
 ## 事件
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 18839bf3c2..2de89ef94b 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -367,8 +367,8 @@ flowchart LR
 | `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
 | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
-| `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), `api-gateway` | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
-| `ctx.typertGateway` | `core` | `api-gateway` | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
+| `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
+| `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
 | `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer. |
 | `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 77baad512d..21f38d18e2 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2520,9 +2520,10 @@ Source: [`packages/context/workspace-context/src/config.ts:18`](../packages/cont
 These load from a `cordis.yml` entry with no `config:` block; they declare no config surface.
 
 - `@deepseek-ai/dsh-agent` ([`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts))
+- `@deepseek-ai/dsh-api-gateway` — requires `typert` ([`packages/api/gateway/src/index.ts`](../packages/api/gateway/src/index.ts))
+- `@deepseek-ai/dsh-api-remotes` ([`packages/api/remotes/src/index.ts`](../packages/api/remotes/src/index.ts))
 - `@deepseek-ai/dsh-client-locale` ([`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts))
 - `@deepseek-ai/dsh-client-modules` — requires `httpServer` · `loader` ([`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts))
-- `@deepseek-ai/dsh-client-remotes` ([`packages/client/remotes/src/index.ts`](../packages/client/remotes/src/index.ts))
 - `@deepseek-ai/dsh-client-runtime` ([`packages/client/runtime/src/index.ts`](../packages/client/runtime/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-command` ([`packages/client/ui-command/src/index.ts`](../packages/client/ui-command/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-conversation` ([`packages/client/ui-conversation/src/index.ts`](../packages/client/ui-conversation/src/index.ts))
@@ -2549,7 +2550,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts))
 - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts))
 - `@deepseek-ai/dsh-goal-session` — requires `agents` · `goals` · `sessions` ([`packages/goal/goal-session/src/index.ts`](../packages/goal/goal-session/src/index.ts))
-- `@deepseek-ai/dsh-host-api-gateway` — requires `typert` ([`packages/host/api-gateway/src/index.ts`](../packages/host/api-gateway/src/index.ts))
 - `@deepseek-ai/dsh-host-directory-picker-auto` — requires `httpServer` · `loader` ([`packages/host/directory-picker-auto/src/index.ts`](../packages/host/directory-picker-auto/src/index.ts))
 - `@deepseek-ai/dsh-host-directory-picker-native` ([`packages/host/directory-picker-native/src/index.ts`](../packages/host/directory-picker-native/src/index.ts))
 - `@deepseek-ai/dsh-llm` ([`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts))
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 8acd669131..cf763dca98 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2609,7 +2609,7 @@ Resolve strict generated definitions or conservative SRC markers against current
 async invoke(request: InvokeRemoteRequest): Promise<unknown>
 ```
 
-Source: [`packages/host/api-gateway/src/index.ts:78`](../../packages/host/api-gateway/src/index.ts)
+Source: [`packages/api/gateway/src/index.ts:78`](../../packages/api/gateway/src/index.ts)
 
 ## `ctx.userInteraction` — `UserInteractionService`
 
diff --git a/docs/core-data-structures/typert.i18n.yaml b/docs/core-data-structures/typert.i18n.yaml
index 5b0b70de54..a6e1eb5415 100644
--- a/docs/core-data-structures/typert.i18n.yaml
+++ b/docs/core-data-structures/typert.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 docs/core-data-structures/typert.md
-typert.md: 1ff0fe80e483d481f686336c86038cdd169ecdbc
-typert.zh.md: 3cc0aa26406e01db5a6c05074210fc9d40b8ec00
+typert.md: a61ed8587833e03fd5c1246311e62a6ffaeb3bd0
+typert.zh.md: 18c24018f4abd644cf35185c2bd06b6980195481
diff --git a/docs/core-data-structures/typert.md b/docs/core-data-structures/typert.md
index 1ff0fe80e4..a61ed85878 100644
--- a/docs/core-data-structures/typert.md
+++ b/docs/core-data-structures/typert.md
@@ -2,7 +2,7 @@
 
 English | [中文](typert.zh.md)
 
-Types shared by generated Remote artifacts, the Host Gateway, and consumer API assemblies. The [TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) owns the architecture and transport decisions; this page records the literal public contracts from [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) and [`dsh-host-api-gateway`](../../packages/host/api-gateway/src/types.ts).
+Types shared by generated Remote artifacts, the Host Gateway, and consumer API assemblies. The [TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) owns the architecture and transport decisions; this page records the literal public contracts from [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) and [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts).
 
 ## Lookup and Context declarations
 
@@ -126,7 +126,7 @@ interface TypeRTService {
 }
 ```
 
-Generated consumer declarations merge direct namespaces into the map inherited by `ClientApi`.
+Generated consumer declarations merge direct namespaces into the map inherited by `TypeRTClientApi`.
 
 ```ts type-equiv
 /** Merge-extensible direct namespace surface generated for Client API services. */
@@ -191,8 +191,8 @@ interface TypertGateway {
 `ctx.api` exposes only namespaces contributed by imported `/remote` artifacts. Mounting installs the generated descriptors and concrete root/scoped methods as one fiber-owned operation; no JavaScript Proxy or Host Service type enters the consumer.
 
 ```ts type-equiv
-/** Typed API service augmented by generated direct Remote namespaces. */
-interface ClientApi extends TypeRTRemoteNamespaceMap {
+/** Client API capability implemented by the Gateway and consumed by Remote assemblies. */
+interface TypeRTClientApi extends TypeRTRemoteNamespaceMap {
   /**
    * Mount one generated Host-for-Client contribution in the caller's fiber.
    * @param contribution - explicitly selected Remote package artifact.
diff --git a/docs/core-data-structures/typert.zh.md b/docs/core-data-structures/typert.zh.md
index 3cc0aa2640..18c24018f4 100644
--- a/docs/core-data-structures/typert.zh.md
+++ b/docs/core-data-structures/typert.zh.md
@@ -2,7 +2,7 @@
 
 [English](typert.md) | 中文
 
-以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-host-api-gateway`](../../packages/host/api-gateway/src/types.ts) 中公共契约的字面定义。
+以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts) 中公共契约的字面定义。
 
 ## Lookup 与 Context 声明
 
@@ -126,7 +126,7 @@ interface TypeRTService {
 }
 ```
 
-生成的消费方声明会把 direct namespace 合并到 `ClientApi` 继承的 map 中。
+生成的消费方声明会把 direct namespace 合并到 `TypeRTClientApi` 继承的 map 中。
 
 ```ts type-equiv
 /** Merge-extensible direct namespace surface generated for Client API services. */
@@ -191,8 +191,8 @@ interface TypertGateway {
 `ctx.api` 只暴露由已导入 `/remote` 产物贡献的 namespace。挂载会把生成的 descriptor 与具体的 root/scoped 方法作为一项由 fiber 持有的操作统一注册；JavaScript Proxy 与 Host 服务类型都不会进入消费方。
 
 ```ts type-equiv
-/** Typed API service augmented by generated direct Remote namespaces. */
-interface ClientApi extends TypeRTRemoteNamespaceMap {
+/** Client API capability implemented by the Gateway and consumed by Remote assemblies. */
+interface TypeRTClientApi extends TypeRTRemoteNamespaceMap {
   /**
    * Mount one generated Host-for-Client contribution in the caller's fiber.
    * @param contribution - explicitly selected Remote package artifact.
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 2ea336b1f0..b0809af72e 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: d480f548dd24ea81d132e4b4c0cc364ce1b0cd53
-development.zh.md: 08ef7fd2d3da7db83eb3ca4dff9f9c85f6d7cb5e
+development.md: f832956c4c7cbde96613a69db6c636a2246786a7
+development.zh.md: 3ae70e7135ad5faee0e37d99f55cdb41373aab2c
diff --git a/docs/development.md b/docs/development.md
index d480f548dd..f832956c4c 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -62,7 +62,7 @@ Host and client stay two aggregate programs because both sides declaration-merge
 
 Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).
 
-Business services declare callable methods on the Host with `@Remote` or `@RemoteContext`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `client-remotes` composition loads those contributions and mounts concrete methods on `ctx.api` or the corresponding scoped Context. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
+Business services declare callable methods on the Host with `@Remote` or `@RemoteContext`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions and mounts concrete methods on `ctx.api` or the corresponding scoped Context. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
 
 If a relevant local check consumes built package output, build once first:
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 08ef7fd2d3..3ae70e7135 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -62,7 +62,7 @@ host 与 client 保持两个聚合 program，是因为两侧在相同键下以
 
 静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。
 
-业务 Service 在 Host 使用 `@Remote` 或 `@RemoteContext` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `client-remotes` 组合加载这些贡献并将具体方法挂载到 `ctx.api` 或对应的作用域 Context。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
+业务 Service 在 Host 使用 `@Remote` 或 `@RemoteContext` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并将具体方法挂载到 `ctx.api` 或对应的作用域 Context。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
 
 如果相关的本地检查需要使用构建后的包产物，请先构建一次：
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 34f4d37ffd..92bf908613 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -66,7 +66,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `credentials/changed` | `runtime` (`emit`) | `ui-models` |
 | `internal/dispatch` | - | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
 | `internal/plugin` | - | `hmr`, `loader`, `modules`, `webserver` |
-| `internal/service` | - | `api-gateway` |
+| `internal/service` | - | `gateway` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
 | `locale/change` | `locale` (`emit`) | `locale` |
 | `models/changed` | `runtime` (`emit`) | `ui-models` |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index ac46e968b3..43923e0865 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -146,6 +146,10 @@ flowchart TD
     pkg_user_approval["user-approval"]
     pkg_user_interaction["user-interaction"]
   end
+  subgraph group_api["packages/api"]
+    pkg_api_gateway["api-gateway"]
+    pkg_api_remotes["api-remotes"]
+  end
   subgraph group_bundle["packages/bundle"]
     pkg_base["base"]
     pkg_headless["headless"]
@@ -156,7 +160,6 @@ flowchart TD
     pkg_client_hmr["client-hmr"]
     pkg_client_locale["client-locale"]
     pkg_client_modules["client-modules"]
-    pkg_client_remotes["client-remotes"]
     pkg_client_runtime["client-runtime"]
     pkg_client_schema_form["client-schema-form"]
     pkg_client_test_runtime["client-test-runtime"]
@@ -212,7 +215,6 @@ flowchart TD
   end
   subgraph group_host["packages/host"]
     pkg_frontend_static["frontend-static"]
-    pkg_host_api_gateway["host-api-gateway"]
     pkg_host_apiproxy["host-apiproxy"]
     pkg_host_directory_picker["host-directory-picker"]
     pkg_host_directory_picker_auto["host-directory-picker-auto"]
@@ -367,13 +369,13 @@ flowchart TD
   pkg_system_prompt --> pkg_scope
   pkg_web --> pkg_invariants
   pkg_web --> pkg_llm
+  pkg_api_gateway --> pkg_client_connection
+  pkg_api_gateway --> pkg_invariants
+  pkg_api_gateway --> pkg_typert_registry
   pkg_credentials_local --> pkg_atomic_write
   pkg_credentials_local --> pkg_credentials
   pkg_credentials_local --> pkg_invariants
   pkg_credentials_local --> pkg_paths
-  pkg_host_api_gateway --> pkg_client_connection
-  pkg_host_api_gateway --> pkg_invariants
-  pkg_host_api_gateway --> pkg_typert_registry
   pkg_lsp --> pkg_brand
   pkg_lsp --> pkg_invariants
   pkg_lsp --> pkg_llm
@@ -614,6 +616,7 @@ flowchart TD
   pkg_permission --> pkg_session_projection
   pkg_permission --> pkg_settings
   pkg_permission --> pkg_user_approval
+<<<<<<< HEAD
 <<<<<<< HEAD
   pkg_client_ui_conversation --> pkg_client_locale
   pkg_client_ui_conversation --> pkg_client_runtime
@@ -630,6 +633,14 @@ flowchart TD
   pkg_client_remotes --> pkg_host_api_gateway
   pkg_client_remotes --> pkg_invariants
 >>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
+=======
+  pkg_api_remotes --> pkg_agent
+  pkg_api_remotes --> pkg_goal
+  pkg_api_remotes --> pkg_invariants
+  pkg_api_remotes --> pkg_session
+  pkg_api_remotes --> pkg_session_persistence
+  pkg_api_remotes --> pkg_typert_registry
+>>>>>>> c671d9e48c (refactor(api): colocate gateway and remote assembly)
   pkg_pty_local --> pkg_agent
   pkg_pty_local --> pkg_invariants
   pkg_pty_local --> pkg_pty
@@ -783,6 +794,7 @@ flowchart TD
   pkg_tool_ask_user --> pkg_invariants
   pkg_tool_ask_user --> pkg_tools
   pkg_tool_ask_user --> pkg_user_interaction
+<<<<<<< HEAD
 <<<<<<< HEAD
   pkg_client_ui_command --> pkg_client_connection
   pkg_client_ui_command --> pkg_client_locale
@@ -815,6 +827,9 @@ flowchart TD
   pkg_client_ui_skill --> pkg_invariants
 =======
   pkg_client_runtime --> pkg_client_remotes
+=======
+  pkg_client_runtime --> pkg_api_remotes
+>>>>>>> c671d9e48c (refactor(api): colocate gateway and remote assembly)
   pkg_client_runtime --> pkg_invariants
   pkg_client_runtime --> pkg_type_meta
   pkg_client_runtime --> pkg_typert_registry
@@ -1132,8 +1147,8 @@ flowchart TD
   pkg_client_ui_command --> pkg_client_ui_slash
   pkg_client_ui_command --> pkg_client_ui_slots
   pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_goal --> pkg_api_remotes
   pkg_client_ui_goal --> pkg_client_locale
-  pkg_client_ui_goal --> pkg_client_remotes
   pkg_client_ui_goal --> pkg_client_runtime
   pkg_client_ui_goal --> pkg_client_ui_conversation
   pkg_client_ui_goal --> pkg_client_ui_primitives
@@ -1231,8 +1246,8 @@ flowchart TD
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`type-meta`](../packages/typert/type-meta) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
-| [`host-api-gateway`](../packages/host/api-gateway) | `host` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`settings-local`](../packages/settings/settings-local) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`settings`](../packages/settings/settings) |
@@ -1295,11 +1310,15 @@ flowchart TD
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
 | [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/ui/user-approval) |
 <<<<<<< HEAD
+<<<<<<< HEAD
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 =======
 | [`client-remotes`](../packages/client/remotes) | `client` | [`goal`](../packages/goal/goal), [`host-api-gateway`](../packages/host/api-gateway), [`invariants`](../packages/support/invariants) |
 >>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
+=======
+| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`typert-registry`](../packages/typert/registry) |
+>>>>>>> c671d9e48c (refactor(api): colocate gateway and remote assembly)
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -1326,6 +1345,7 @@ flowchart TD
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
 <<<<<<< HEAD
+<<<<<<< HEAD
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
@@ -1333,6 +1353,9 @@ flowchart TD
 =======
 | [`client-runtime`](../packages/client/runtime) | `client` | [`client-remotes`](../packages/client/remotes), [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
 >>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
+=======
+| [`client-runtime`](../packages/client/runtime) | `client` | [`api-remotes`](../packages/api/remotes), [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
+>>>>>>> c671d9e48c (refactor(api): colocate gateway and remote assembly)
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
@@ -1383,7 +1406,7 @@ flowchart TD
 | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-locale`](../packages/client/locale), [`client-remotes`](../packages/client/remotes), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
 | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
 | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
diff --git a/knip.json b/knip.json
index 3ce9a32d99..3d7836104f 100644
--- a/knip.json
+++ b/knip.json
@@ -115,7 +115,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/client/remotes": {
+    "packages/api/remotes": {
       "entry": [
         "tests/**/*.e2e.ts"
       ],
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index d10f476f79..8aa9b92b91 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 8fbb6069a784a5bd45423a4e1ae11834a597750d
-README.zh.md: 42a8d691344c716021188df6fd870a841d543f36
+README.md: 229feae568ba6e40a9c633696097eff46fd5bc95
+README.zh.md: b84aef020a7e3edf305df709d399fbc7b093b6a3
diff --git a/packages/README.md b/packages/README.md
index 8fbb6069a7..229feae568 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -11,6 +11,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | Group | Role | Release expectation |
 |---|---|---|
 | [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable surface |
+| [`api/`](api/README.md) | Remote BFF assembly and TypeRT RPC gateway | Product — stable surface |
 | [`typert/`](typert/README.md) | Type graph generation, artifact loading, and runtime registry | Product — stable surface |
 | [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 42a8d69134..b84aef020a 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -11,6 +11,7 @@
 | 组 | 职责 | 发布预期 |
 |---|---|---|
 | [`core/`](core/README.md) | 产品 API 主干：会话、提示词、工具、agent（智能体）服务与具体循环 | 产品：稳定表面 |
+| [`api/`](api/README.md) | Remote BFF 装配与 TypeRT RPC Gateway | 产品：稳定表面 |
 | [`typert/`](typert/README.md) | 类型图生成、产物加载与运行时注册表 | 产品：稳定表面 |
 | [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |
diff --git a/packages/client/remotes/README.i18n.yaml b/packages/api/README.i18n.yaml
similarity index 56%
rename from packages/client/remotes/README.i18n.yaml
rename to packages/api/README.i18n.yaml
index 86f2aded18..855eeb8eaa 100644
--- a/packages/client/remotes/README.i18n.yaml
+++ b/packages/api/README.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 packages/client/remotes/README.md
-README.md: e29188b8e3ae5ecefe194f1355558e9bdeaae7dd
-README.zh.md: e6425ab190a28e0a38c3713c4e21645789a8f00c
+#   pnpm run verify-translation-pairing --write packages/api/README.md
+README.md: 0dcded5922fea1ea6676315029ba0eadd74dd3df
+README.zh.md: 1b9bb9133a955d0cbef0ca91728aab1545831d94
diff --git a/packages/api/README.md b/packages/api/README.md
new file mode 100644
index 0000000000..0dcded5922
--- /dev/null
+++ b/packages/api/README.md
@@ -0,0 +1,17 @@
+# api/ — Remote API layers
+
+English | [中文](README.zh.md)
+
+The application-facing Remote stack. `remotes` owns BFF policy and the selected business API, while `gateway` implements the TypeRT unary RPC endpoints shared by Host and Client environments.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`remotes/`](remotes/README.md) | Host Agent/Session lookup policy and Client Remote contribution assembly | no service; configures `ctx.typert` and consumes `ctx.api` |
+| [`gateway/`](gateway/README.md) | Host TypeRT dispatcher and Client API endpoint | `ctx.typertGateway` / `ctx.api` |
+
+The runtime dependency direction is `remotes → gateway → connection → webserver`: the BFF consumes the shared `TypeRTClientApi` contract, Gateway delegates transport to Connection, and Connection mounts on the HTTP server. Cordis service injection and Client module metadata preserve this order without importing the concrete Gateway from the Remotes Client entry.
+
+## Known Limitations and Deferred Work
+
+- Connection and WebServer remain at [`client/connection`](../client/connection/README.md) and [`host/webserver`](../host/webserver/README.md); a later package-only move can place them under `api/connection` and `api/webserver` without changing their service contracts.
+- The legacy API Proxy remains at [`host/apiproxy`](../host/apiproxy/README.md) as the fallback for methods not yet migrated to Remote. It consumes the Host resolver owned by `api-remotes` so migrated and legacy methods retain one Agent/Session identity policy.
diff --git a/packages/api/README.zh.md b/packages/api/README.zh.md
new file mode 100644
index 0000000000..1b9bb9133a
--- /dev/null
+++ b/packages/api/README.zh.md
@@ -0,0 +1,17 @@
+# api/：Remote API 层
+
+[English](README.md) | 中文
+
+面向应用的 Remote 技术栈。`remotes` 负责 BFF 策略和选定的业务 API，`gateway` 则实现 Host 与 Client 环境共用的 TypeRT 一元 RPC endpoint。
+
+| 包 | 职责 | ctx key |
+|---|---|---|
+| [`remotes/`](remotes/README.md) | Host Agent/Session lookup 策略与 Client Remote contribution 装配 | 无服务；配置 `ctx.typert` 并消费 `ctx.api` |
+| [`gateway/`](gateway/README.md) | Host TypeRT 分发器与 Client API endpoint | `ctx.typertGateway` / `ctx.api` |
+
+运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientApi` 契约，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
+
+## 已知限制与延期工作
+
+- Connection 与 WebServer 仍位于 [`client/connection`](../client/connection/README.md) 和 [`host/webserver`](../host/webserver/README.md)；后续可以只移动包，将它们放到 `api/connection` 和 `api/webserver` 下，而无需改变服务契约。
+- 旧 API Proxy 仍位于 [`host/apiproxy`](../host/apiproxy/README.md)，作为尚未迁移到 Remote 的方法的回退路径。它使用由 `api-remotes` 持有的 Host resolver，使已迁移与旧方法共用同一套 Agent/Session 身份策略。
diff --git a/packages/host/api-gateway/README.i18n.yaml b/packages/api/gateway/README.i18n.yaml
similarity index 56%
rename from packages/host/api-gateway/README.i18n.yaml
rename to packages/api/gateway/README.i18n.yaml
index 8d8d699c7a..41bbb0621f 100644
--- a/packages/host/api-gateway/README.i18n.yaml
+++ b/packages/api/gateway/README.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 packages/host/api-gateway/README.md
-README.md: eb48c29628d39e381235b1f72754eb114960b1ad
-README.zh.md: e53bb6c216e42fe2e970bf2cb80eac9ea7426497
+#   pnpm run verify-translation-pairing --write packages/api/gateway/README.md
+README.md: 9e3d4d89788bbc6edebfc0c0127999fed3ed9261
+README.zh.md: 9bbd46c71185a2fbf8da163565d6c19141c079ca
diff --git a/packages/host/api-gateway/README.md b/packages/api/gateway/README.md
similarity index 86%
rename from packages/host/api-gateway/README.md
rename to packages/api/gateway/README.md
index eb48c29628..9e3d4d8978 100644
--- a/packages/host/api-gateway/README.md
+++ b/packages/api/gateway/README.md
@@ -1,8 +1,8 @@
-# @deepseek-ai/dsh-host-api-gateway
+# @deepseek-ai/dsh-api-gateway
 
 English | [中文](README.zh.md)
 
-Two-sided Remote control for Host and Client Cordis environments. The Host entry provides `ctx.typertGateway`, while `@deepseek-ai/dsh-host-api-gateway/client` provides `ctx.api`; both consume the same generated `InvocationDescriptor` contract and leave transport, request correlation, trust, and response envelopes to Connection.
+Two-sided TypeRT RPC endpoint for Host and Client Cordis environments. The Host entry provides `ctx.typertGateway`, while `@deepseek-ai/dsh-api-gateway/client` provides `ctx.api`; both consume the same generated `InvocationDescriptor` contract and leave business selection to API Remotes and transport, request correlation, trust, and response envelopes to Connection.
 
 ## Host service: `TypertGatewayService` (ctx key: `typertGateway`)
 
@@ -20,7 +20,7 @@ A cancellation-aware Remote method declares `signal: AbortSignal` as its final H
 
 Each call validates positional inputs, constructs the descriptor's exact named `args`, and sends it through `ctx.connection.rpc.call('/api', endpoint, ...)`. Generated cancellation-aware methods accept a final optional `AbortSignal`; the Client combines it with the contribution mount lifetime before calling Connection. The returned value is validated before reaching application code. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls, and makes retained method handles reject.
 
-Generated declaration merges provide the TypeScript API. The Client entry contains no Host Service or Host Cordis interface merge, and method lookup and invocation use ordinary objects and functions rather than a JavaScript Proxy.
+Generated declaration merges provide the TypeScript API through the shared `TypeRTClientApi` contract. The Client entry contains no Host Service or Host Cordis interface merge, and method lookup and invocation use ordinary objects and functions rather than a JavaScript Proxy.
 
 ## Model Experience
 
diff --git a/packages/host/api-gateway/README.zh.md b/packages/api/gateway/README.zh.md
similarity index 86%
rename from packages/host/api-gateway/README.zh.md
rename to packages/api/gateway/README.zh.md
index e53bb6c216..9bbd46c711 100644
--- a/packages/host/api-gateway/README.zh.md
+++ b/packages/api/gateway/README.zh.md
@@ -1,8 +1,8 @@
-# @deepseek-ai/dsh-host-api-gateway
+# @deepseek-ai/dsh-api-gateway
 
 [English](README.md) | 中文
 
-为 Host 与 Client 两侧的 Cordis 环境提供 Remote 控制。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-host-api-gateway/client` 则提供 `ctx.api`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将传输、请求关联、信任和响应封装交由 Connection 处理。
+为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.api`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
 
 ## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
 
@@ -20,7 +20,7 @@ Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandle
 
 每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api', endpoint, ...)` 发送。生成的支持取消的方法接受最后一个可选 `AbortSignal`；Client 会在调用 Connection 前将它与贡献项的挂载生命周期合并。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
 
-生成的声明合并提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
+生成的声明合并通过共享的 `TypeRTClientApi` 契约提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
 
 ## 模型体验
 
diff --git a/packages/host/api-gateway/package.json b/packages/api/gateway/package.json
similarity index 92%
rename from packages/host/api-gateway/package.json
rename to packages/api/gateway/package.json
index 794ae323aa..fa351d84bf 100644
--- a/packages/host/api-gateway/package.json
+++ b/packages/api/gateway/package.json
@@ -1,6 +1,6 @@
 {
-  "name": "@deepseek-ai/dsh-host-api-gateway",
-  "description": "Host dispatcher and Client API for TypeRT Remote invocations",
+  "name": "@deepseek-ai/dsh-api-gateway",
+  "description": "TypeRT Remote Host dispatcher and Client API endpoint",
   "version": "0.0.1",
   "private": true,
   "type": "module",
diff --git a/packages/host/api-gateway/src/client/index.ts b/packages/api/gateway/src/client/index.ts
similarity index 96%
rename from packages/host/api-gateway/src/client/index.ts
rename to packages/api/gateway/src/client/index.ts
index 5503fc3dcf..bafffa80f7 100644
--- a/packages/host/api-gateway/src/client/index.ts
+++ b/packages/api/gateway/src/client/index.ts
@@ -9,10 +9,9 @@ import type { Context } from 'cordis'
 import type { ConnectionHandle, RpcError } from '@deepseek-ai/dsh-client-connection/client'
 import type {
   InvocationDescriptor,
+  TypeRTClientApi,
   TypeRTCodec,
-  TypeRTDisposer,
   TypeRTRemoteContribution,
-  TypeRTRemoteNamespaceMap,
 } from '@deepseek-ai/dsh-type-meta'
 
 type RemoteMethod = (...args: unknown[]) => Promise<unknown>
@@ -40,14 +39,7 @@ interface ScopedProjection {
 }
 
 /** Typed API service augmented by generated direct Remote namespaces. */
-export interface ClientApi extends TypeRTRemoteNamespaceMap {
-  /**
-   * Mount one generated Host-for-Client contribution in the caller's fiber.
-   * @param contribution - explicitly selected Remote package artifact.
-   * @returns disposer withdrawing descriptors and concrete methods together.
-   */
-  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer
-}
+export type ClientApi = TypeRTClientApi
 
 declare module 'cordis' {
   interface Context {
@@ -67,7 +59,7 @@ export function apply(ctx: Context): void {
   new ClientApiService(ctx)
 }
 
-class ClientApiService extends Service implements ClientApi {
+class ClientApiService extends Service implements TypeRTClientApi {
   private readonly ownerCtx: Context
   private readonly direct = new Map<string, DirectNamespaceRecord>()
   private readonly scoped = new Map<string, ScopedNamespaceRecord>()
@@ -77,7 +69,7 @@ class ClientApiService extends Service implements ClientApi {
     this.ownerCtx = ctx
   }
 
-  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer {
+  mount(contribution: TypeRTRemoteContribution): ReturnType<TypeRTClientApi['mount']> {
     this.validateContribution(contribution)
     const callerCtx = this.ctx
     const disposeRemote = callerCtx.typert.remotes.register(contribution)
diff --git a/packages/host/api-gateway/src/index.ts b/packages/api/gateway/src/index.ts
similarity index 99%
rename from packages/host/api-gateway/src/index.ts
rename to packages/api/gateway/src/index.ts
index 8ea26b5990..13cf460f4d 100644
--- a/packages/host/api-gateway/src/index.ts
+++ b/packages/api/gateway/src/index.ts
@@ -1,7 +1,7 @@
 /**
  * Live TypeRT Remote dispatch over Cordis Services and registered providers.
  * Transport, request correlation, and response envelopes belong to Connection.
- * @module @deepseek-ai/dsh-host-api-gateway
+ * @module @deepseek-ai/dsh-api-gateway
  */
 
 import { Context, Service, symbols } from 'cordis'
diff --git a/packages/host/api-gateway/src/invariant.ts b/packages/api/gateway/src/invariant.ts
similarity index 77%
rename from packages/host/api-gateway/src/invariant.ts
rename to packages/api/gateway/src/invariant.ts
index 65c94b4ac4..711c4edab5 100644
--- a/packages/host/api-gateway/src/invariant.ts
+++ b/packages/api/gateway/src/invariant.ts
@@ -1,16 +1,16 @@
 /**
- * Package-owned invariant companion for `@deepseek-ai/dsh-host-api-gateway`.
- * @module @deepseek-ai/dsh-host-api-gateway/invariant
+ * Package-owned invariant companion for `@deepseek-ai/dsh-api-gateway`.
+ * @module @deepseek-ai/dsh-api-gateway/invariant
  */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
-const PACKAGE_NAME = '@deepseek-ai/dsh-host-api-gateway'
+const PACKAGE_NAME = '@deepseek-ai/dsh-api-gateway'
 
 /** Cordis companion plugin name. */
-export const name = 'host-api-gateway-invariant'
+export const name = 'api-gateway-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
diff --git a/packages/host/api-gateway/src/types.ts b/packages/api/gateway/src/types.ts
similarity index 97%
rename from packages/host/api-gateway/src/types.ts
rename to packages/api/gateway/src/types.ts
index f4bb276c22..0917ba2ca6 100644
--- a/packages/host/api-gateway/src/types.ts
+++ b/packages/api/gateway/src/types.ts
@@ -1,6 +1,6 @@
 /**
  * Carrier-independent TypeRT Gateway request, service, and error contracts.
- * @module @deepseek-ai/dsh-host-api-gateway/types
+ * @module @deepseek-ai/dsh-api-gateway/types
  */
 
 /** One Remote method request after a carrier has decoded its envelope. */
diff --git a/packages/host/api-gateway/tests/client.spec.ts b/packages/api/gateway/tests/client.spec.ts
similarity index 100%
rename from packages/host/api-gateway/tests/client.spec.ts
rename to packages/api/gateway/tests/client.spec.ts
diff --git a/packages/host/api-gateway/tests/gateway.spec.ts b/packages/api/gateway/tests/gateway.spec.ts
similarity index 99%
rename from packages/host/api-gateway/tests/gateway.spec.ts
rename to packages/api/gateway/tests/gateway.spec.ts
index 0871dc2761..d784a1ac2f 100644
--- a/packages/host/api-gateway/tests/gateway.spec.ts
+++ b/packages/api/gateway/tests/gateway.spec.ts
@@ -16,7 +16,7 @@ import {
   type TypeRTLookupProvider,
 } from '@deepseek-ai/dsh-type-meta'
 import TypertRegistry, { type TypertContribution } from '@deepseek-ai/dsh-typert-registry'
-import TypertGatewayService, { TypertGatewayError } from '@deepseek-ai/dsh-host-api-gateway'
+import TypertGatewayService, { TypertGatewayError } from '@deepseek-ai/dsh-api-gateway'
 
 interface FixtureAgent {
   readonly id: string
diff --git a/packages/host/api-gateway/tsconfig.json b/packages/api/gateway/tsconfig.json
similarity index 100%
rename from packages/host/api-gateway/tsconfig.json
rename to packages/api/gateway/tsconfig.json
diff --git a/packages/api/gateway/tsdown.config.ts b/packages/api/gateway/tsdown.config.ts
new file mode 100644
index 0000000000..f9049b6067
--- /dev/null
+++ b/packages/api/gateway/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../../client/tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-api-gateway', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/api/remotes/README.i18n.yaml b/packages/api/remotes/README.i18n.yaml
new file mode 100644
index 0000000000..c3c13a8049
--- /dev/null
+++ b/packages/api/remotes/README.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 packages/api/remotes/README.md
+README.md: cf54a56a849246d4efdca09cadd42e157064bdee
+README.zh.md: 5cd7ef21c926440ca4df6d88ee4adfe87defcc3f
diff --git a/packages/api/remotes/README.md b/packages/api/remotes/README.md
new file mode 100644
index 0000000000..cf54a56a84
--- /dev/null
+++ b/packages/api/remotes/README.md
@@ -0,0 +1,25 @@
+# @deepseek-ai/dsh-api-remotes
+
+English | [中文](README.zh.md)
+
+Two-sided BFF for Host Remote capabilities selected by this application. The Host entry owns Agent/Session identity policy; the Client entry imports generated `/remote` artifacts as runtime values, mounts each contribution through `ctx.api`, and re-exports their declaration merges. Client business packages depend on this facade rather than the Gateway implementation or individual Remote runtime entries.
+
+`createApiRemoteAgentResolver()` reuses live Agents, resumes ordinary cold sessions, deduplicates concurrent resumes, preserves the subagent ownership fence, and configures the same resolver for TypeRT `agent` and `session` lookups. The standard Web API Proxy supplies its Agent defaults and scope setup, then uses the returned resolver for legacy methods, so migrated and unmigrated methods share one policy implementation.
+
+The current Client assembly mounts only the Goal Remote contribution. Cordis effect ownership withdraws every contribution when this assembly unloads, while `@deepseek-ai/dsh-api-gateway/client` owns descriptor validation, concrete root and scoped methods, invocation, and cancellation. The Client entry consumes the shared `TypeRTClientApi` interface through Cordis and does not import the concrete Gateway.
+
+This package contains no transport or Host service discovery logic. Its Client face can be reused by Web or a future TUI that provides the same React-free `ctx.api` contract.
+
+## Model Experience
+
+None, as this BFF selects Remote application methods and identity policy but registers no model surface.
+
+#### KV Cache effect
+
+No direct effect; mounted Host capabilities own any model-visible behavior they trigger.
+
+## Known Limitations and Deferred Work
+
+- The capability set is fixed by explicit build-time value imports; the Client does not discover the Host's active Services or Remote definitions at runtime.
+- Additional capabilities require an explicit `/remote` value import and mount in this assembly.
+- The standard Web Host supplies resume defaults and Agent-scope setup from the legacy API Proxy until that remaining BFF configuration moves into `api-remotes`.
diff --git a/packages/api/remotes/README.zh.md b/packages/api/remotes/README.zh.md
new file mode 100644
index 0000000000..5cd7ef21c9
--- /dev/null
+++ b/packages/api/remotes/README.zh.md
@@ -0,0 +1,25 @@
+# @deepseek-ai/dsh-api-remotes
+
+[English](README.md) | 中文
+
+为本应用选定的 Host Remote 能力提供双侧 BFF。Host 入口负责 Agent/Session 身份策略；Client 入口以运行时值形式导入生成的 `/remote` 产物，通过 `ctx.api` 挂载每项贡献，并重新导出对应的声明合并。Client 业务包依赖该外观，而不依赖 Gateway 实现或单独的 Remote 运行时入口。
+
+`createApiRemoteAgentResolver()` 会复用 live Agent、恢复普通冷会话、对并发恢复去重、保留 subagent ownership fence，并为 TypeRT `agent` 和 `session` lookup 配置同一个 resolver。标准 Web API Proxy 提供 Agent 默认值和 scope 设置，再将返回的 resolver 用于旧方法，使已迁移与未迁移方法共用同一份策略实现。
+
+当前 Client 组合仅挂载 Goal Remote 贡献。该组合卸载时，Cordis effect 的所有权机制会撤回所有贡献；`@deepseek-ai/dsh-api-gateway/client` 负责描述符校验、具体的根级方法和作用域方法、调用与取消。Client 入口通过 Cordis 消费共享的 `TypeRTClientApi` 接口，不导入具体 Gateway。
+
+本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.api` 契约，均可复用其 Client face。
+
+## 模型体验
+
+无，因为该 BFF 只选择 Remote 应用方法和身份策略，不注册任何模型接口。
+
+#### KV Cache 影响
+
+无直接影响；其触发的任何模型可见行为均由已挂载的 Host 能力负责。
+
+## 已知限制与暂缓事项
+
+- 能力集合由构建时显式导入的值固定确定；Client 不会在运行时发现 Host 中已启用的服务或 Remote 定义。
+- 若要增加能力，必须显式导入相应的 `/remote` 值并在此组合中挂载。
+- 在剩余 BFF 配置迁移到 `api-remotes` 之前，标准 Web Host 仍从旧 API Proxy 提供恢复默认值与 Agent scope 设置。
diff --git a/packages/client/remotes/package.json b/packages/api/remotes/package.json
similarity index 64%
rename from packages/client/remotes/package.json
rename to packages/api/remotes/package.json
index ba4e7b6a01..0a1e3ec71d 100644
--- a/packages/client/remotes/package.json
+++ b/packages/api/remotes/package.json
@@ -1,6 +1,6 @@
 {
-  "name": "@deepseek-ai/dsh-client-remotes",
-  "description": "Platform-neutral assembly of explicitly selected Host Remote contributions",
+  "name": "@deepseek-ai/dsh-api-remotes",
+  "description": "Remote BFF assembly and Host Agent/Session lookup policy",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -24,7 +24,7 @@
   },
   "dshClient": {
     "inject": [
-      "@deepseek-ai/dsh-host-api-gateway"
+      "@deepseek-ai/dsh-api-gateway"
     ],
     "platform": "web",
     "immediately": true
@@ -40,16 +40,25 @@
     "lib/client.js",
     "lib/types/**/*.d.ts"
   ],
+  "dependencies": {
+    "@deepseek-ai/dsh-type-meta": "workspace:^"
+  },
   "peerDependencies": {
-    "@deepseek-ai/dsh-host-api-gateway": "^0.0.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-goal": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-host-api-gateway": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/api/remotes/src/agent-lookup.ts b/packages/api/remotes/src/agent-lookup.ts
new file mode 100644
index 0000000000..e3a5b27df8
--- /dev/null
+++ b/packages/api/remotes/src/agent-lookup.ts
@@ -0,0 +1,193 @@
+/** Host BFF policy for resolving Remote Agent and Session identities. */
+
+import type { Context } from 'cordis'
+import type { Agent, AgentOptions, AgentSetup } from '@deepseek-ai/dsh-agent'
+import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-persistence'
+import { TypeRTLookupFailure } from '@deepseek-ai/dsh-type-meta'
+import type {} from '@deepseek-ai/dsh-typert-registry'
+
+/** Caller-facing failures preserved by the Gateway's RPC adapter. */
+export type ApiRemoteLookupError =
+  | { readonly code: 'agent-busy'; readonly message: string; readonly details: { readonly reason: string } }
+  | { readonly code: 'session-not-found'; readonly message: string; readonly details: { readonly sessionId: SessionId } }
+  | { readonly code: 'internal'; readonly message: string; readonly details: Record<never, never> }
+
+/** Result of resolving one session identity to its live Agent. */
+export type ApiRemoteAgentResult =
+  | { readonly agent: Agent }
+  | { readonly error: ApiRemoteLookupError }
+
+/** Resume configuration supplied by the owning Host composition. */
+export interface ApiRemoteAgentOptions {
+  /** Per-Agent defaults used when a cold identity must resume. */
+  readonly agentOptions?: AgentOptions
+  /** Host-specific Agent-scope composition completed before publication. */
+  readonly setup?: AgentSetup
+}
+
+/** Cold identity absent from the durable session store. */
+export class ApiRemoteSessionNotFound extends Error {}
+
+/** Session identity whose lifecycle belongs to subagent routing. */
+export class ApiRemoteSubagentSessionOwnership extends Error {
+  /**
+   * Construct the ownership fence.
+   * @param sessionId - identity reserved to subagent routing.
+   */
+  constructor(readonly sessionId: SessionId) {
+    super(`session "${sessionId}" is a subagent session; use subagent delivery`)
+  }
+}
+
+/**
+ * Test whether generic Host routing must leave an identity to subagent routing.
+ * @param ctx - Host Context carrying the live Agent registry.
+ * @param session - attached or live Session metadata.
+ * @param agent - live Agent when one is registered.
+ * @returns whether generic Remote and legacy API calls must reject the identity.
+ */
+export function hasApiRemoteSubagentOwner(
+  ctx: Context,
+  session: Pick<Session, 'header'>,
+  agent: Agent | undefined,
+): boolean {
+  if (session.header.origin === 'subagent') return true
+  const parentId = session.header.parentSession
+  if (parentId === undefined || agent === undefined) return false
+  const parent = ctx.agents.get(parentId)
+  return parent !== undefined && ctx.agents.isOwnedBy(agent.id, parent)
+}
+
+/**
+ * Build the stable caller-facing ownership rejection.
+ * @param sessionId - identity reserved to subagent routing.
+ * @returns the existing `agent-busy` RPC shape.
+ */
+export function apiRemoteSubagentOwnershipError(sessionId: SessionId): ApiRemoteLookupError {
+  return {
+    code: 'agent-busy',
+    message: `session "${sessionId}" is owned by subagent routing`,
+    details: { reason: 'use subagent delivery for this child session' },
+  }
+}
+
+/**
+ * Inspect one cold served session without repairing, resuming, or publishing it.
+ * @param ctx - Host Context carrying the optional persistence provider.
+ * @param sessionId - durable identity to inspect.
+ * @returns detached metadata and events for a servable session.
+ * @throws {@link ApiRemoteSessionNotFound} when the identity has no project-backed session.
+ */
+export async function inspectApiRemoteSession(
+  ctx: Context,
+  sessionId: SessionId,
+): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  const persistence = ctx.get('sessionPersistence')
+  if (persistence === undefined) {
+    throw new Error('session persistence is not configured (load a dsh-session-persistence backend)')
+  }
+  const meta = (await persistence.list()).find(candidate => candidate.id === sessionId)
+  if (meta === undefined || meta.cwd === undefined) {
+    throw new ApiRemoteSessionNotFound(`session "${sessionId}" not found`)
+  }
+  const inspected = await persistence.inspect(sessionId)
+  if (inspected.meta.cwd === undefined) {
+    throw new ApiRemoteSessionNotFound(`session "${sessionId}" not found`)
+  }
+  return { meta: inspected.meta, events: [...inspected.events] }
+}
+
+/**
+ * Create the Host's shared Agent resolver and configure Agent/Session TypeRT lookups.
+ * Live Agents are reused, ordinary cold sessions resume once per identity, and
+ * subagent-owned identities retain the legacy `agent-busy` fence.
+ * @param ctx - owning Host Context.
+ * @param options - defaults and Agent-scope setup used only for cold resume.
+ * @returns resolver shared by legacy API Proxy methods and TypeRT lookups.
+ */
+export function createApiRemoteAgentResolver(
+  ctx: Context,
+  options: ApiRemoteAgentOptions,
+): (sessionId: SessionId) => Promise<ApiRemoteAgentResult> {
+  const resumes = new Map<SessionId, Promise<Agent>>()
+
+  const fencedLiveAgent = (sessionId: SessionId): ApiRemoteAgentResult | undefined => {
+    const live = ctx.agents.get(sessionId)
+    if (live === undefined) return undefined
+    if (hasApiRemoteSubagentOwner(ctx, live.session, live)) {
+      return { error: apiRemoteSubagentOwnershipError(sessionId) }
+    }
+    return { agent: live }
+  }
+
+  const agentFor = async (sessionId: SessionId): Promise<ApiRemoteAgentResult> => {
+    const fenced = fencedLiveAgent(sessionId)
+    if (fenced !== undefined) return fenced
+    const attached = ctx.sessions.get(sessionId)
+    if (attached !== undefined && hasApiRemoteSubagentOwner(ctx, attached, undefined)) {
+      return { error: apiRemoteSubagentOwnershipError(sessionId) }
+    }
+    let resume = resumes.get(sessionId)
+    if (resume === undefined) {
+      resume = (async () => {
+        try {
+          const inspected = await inspectApiRemoteSession(ctx, sessionId)
+          if (hasApiRemoteSubagentOwner(ctx, { header: inspected.meta }, undefined)) {
+            throw new ApiRemoteSubagentSessionOwnership(sessionId)
+          }
+          const publishedSession = ctx.sessions.get(sessionId)
+          const publishedAgent = ctx.agents.get(sessionId)
+          if (publishedSession !== undefined
+            && hasApiRemoteSubagentOwner(ctx, publishedSession, publishedAgent)) {
+            throw new ApiRemoteSubagentSessionOwnership(sessionId)
+          }
+          const handle = await ctx.agents.resume({
+            resumeSessionId: sessionId,
+            ...options.agentOptions === undefined ? {} : { agentOptions: options.agentOptions },
+            ...options.setup === undefined ? {} : { setup: options.setup },
+          })
+          return handle.agent
+        } finally {
+          resumes.delete(sessionId)
+        }
+      })()
+      resumes.set(sessionId, resume)
+    }
+    try {
+      return { agent: await resume }
+    } catch (error: unknown) {
+      if (error instanceof ApiRemoteSessionNotFound) {
+        return { error: { code: 'session-not-found', message: error.message, details: { sessionId } } }
+      }
+      if (error instanceof ApiRemoteSubagentSessionOwnership) {
+        return { error: apiRemoteSubagentOwnershipError(error.sessionId) }
+      }
+      const fenced = fencedLiveAgent(sessionId)
+      if (fenced !== undefined) return fenced
+      const attached = ctx.sessions.get(sessionId)
+      if (attached !== undefined && hasApiRemoteSubagentOwner(ctx, attached, undefined)) {
+        return { error: apiRemoteSubagentOwnershipError(sessionId) }
+      }
+      return {
+        error: {
+          code: 'internal',
+          message: `resume failed for session "${sessionId}": ${String(error)}`,
+          details: {},
+        },
+      }
+    }
+  }
+
+  ctx.inject(['typert'], (typeCtx) => {
+    const resolveAgent = async (sessionId: SessionId): Promise<Agent> => {
+      const found = await agentFor(sessionId)
+      if ('error' in found) throw new TypeRTLookupFailure(found.error)
+      return found.agent
+    }
+    typeCtx.typert.lookups.configure('agent', resolveAgent)
+    typeCtx.typert.lookups.configure('session', async sessionId => (await resolveAgent(sessionId)).session)
+  })
+
+  return agentFor
+}
diff --git a/packages/client/remotes/src/client/index.ts b/packages/api/remotes/src/client/index.ts
similarity index 64%
rename from packages/client/remotes/src/client/index.ts
rename to packages/api/remotes/src/client/index.ts
index 09757b5e9e..1bc36b62ee 100644
--- a/packages/client/remotes/src/client/index.ts
+++ b/packages/api/remotes/src/client/index.ts
@@ -1,12 +1,19 @@
 /** Platform-neutral assembly of generated Host Remote contributions. */
 
 import type { Context } from 'cordis'
-import type {} from '@deepseek-ai/dsh-host-api-gateway/client'
 import goalsRemote from '@deepseek-ai/dsh-goal/remote'
+import type { TypeRTClientApi } from '@deepseek-ai/dsh-type-meta'
 
-export type { ClientApi } from '@deepseek-ai/dsh-host-api-gateway/client'
+export type { TypeRTClientApi as ClientApi } from '@deepseek-ai/dsh-type-meta'
 export type {} from '@deepseek-ai/dsh-goal/remote'
 
+declare module 'cordis' {
+  interface Context {
+    /** Generated direct Remote namespaces selected by this Client assembly. */
+    api: TypeRTClientApi
+  }
+}
+
 /** Required service: the typed Client API contribution mount. */
 export const inject = ['api']
 
diff --git a/packages/api/remotes/src/index.ts b/packages/api/remotes/src/index.ts
new file mode 100644
index 0000000000..4cd70f4a78
--- /dev/null
+++ b/packages/api/remotes/src/index.ts
@@ -0,0 +1,18 @@
+/** Host BFF entry and Loader shell for the Remote contribution assembly. */
+
+export {
+  ApiRemoteSessionNotFound,
+  ApiRemoteSubagentSessionOwnership,
+  apiRemoteSubagentOwnershipError,
+  createApiRemoteAgentResolver,
+  hasApiRemoteSubagentOwner,
+  inspectApiRemoteSession,
+} from './agent-lookup.ts'
+export type {
+  ApiRemoteAgentOptions,
+  ApiRemoteAgentResult,
+  ApiRemoteLookupError,
+} from './agent-lookup.ts'
+
+/** Host plugin body; the selected contributions mount only in Client environments. */
+export function apply(): void {}
diff --git a/packages/client/remotes/src/invariant.ts b/packages/api/remotes/src/invariant.ts
similarity index 70%
rename from packages/client/remotes/src/invariant.ts
rename to packages/api/remotes/src/invariant.ts
index 1a6b0ba237..3310bed11f 100644
--- a/packages/client/remotes/src/invariant.ts
+++ b/packages/api/remotes/src/invariant.ts
@@ -1,17 +1,17 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-client-remotes`. */
+/** Package-owned invariant companion for `@deepseek-ai/dsh-api-remotes`. */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
-const PACKAGE_NAME = '@deepseek-ai/dsh-client-remotes'
+const PACKAGE_NAME = '@deepseek-ai/dsh-api-remotes'
 
 /** Cordis companion plugin name. */
-export const name = 'client-remotes-invariant'
+export const name = 'api-remotes-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
-/** No runtime invariant: the API service owns contribution and method lifecycle atomically. */
+/** No runtime invariant: TypeRT and the Agent/Session registries own the observed relationships. */
 const install: InvariantInstaller = () => {}
 
 /**
diff --git a/packages/client/remotes/tests/built-lib.e2e.ts b/packages/api/remotes/tests/built-lib.e2e.ts
similarity index 95%
rename from packages/client/remotes/tests/built-lib.e2e.ts
rename to packages/api/remotes/tests/built-lib.e2e.ts
index 0cee3eb245..b8f6c81e98 100644
--- a/packages/client/remotes/tests/built-lib.e2e.ts
+++ b/packages/api/remotes/tests/built-lib.e2e.ts
@@ -17,13 +17,13 @@ const artifactUrl = (path: string): string => pathToFileURL(artifact(path)).href
 const requiredArtifacts = [
   'packages/client/connection/lib/client.js',
   'packages/client/connection/lib/index.js',
-  'packages/client/remotes/lib/client.js',
+  'packages/api/remotes/lib/client.js',
   'packages/core/agent/lib/index.js',
   'packages/core/session/lib/index.js',
   'packages/goal/goal/lib/index.js',
   'packages/goal/goal/lib/typert.host.js',
-  'packages/host/api-gateway/lib/client.js',
-  'packages/host/api-gateway/lib/index.js',
+  'packages/api/gateway/lib/client.js',
+  'packages/api/gateway/lib/index.js',
   'packages/typert/registry/lib/client.js',
   'packages/typert/registry/lib/index.js',
 ].every(path => existsSync(artifact(path)))
@@ -32,15 +32,15 @@ describe.skipIf(!requiredArtifacts)('Goal Remote built LIB chain', () => {
   it('runs root and Agent-scoped calls through generated bundles and real HTTP', async () => {
     const urls = Object.fromEntries(Object.entries({
       agent: 'packages/core/agent/lib/index.js',
-      apiGatewayClient: 'packages/host/api-gateway/lib/client.js',
-      apiGatewayHost: 'packages/host/api-gateway/lib/index.js',
+      apiGatewayClient: 'packages/api/gateway/lib/client.js',
+      apiGatewayHost: 'packages/api/gateway/lib/index.js',
       connectionClient: 'packages/client/connection/lib/client.js',
       connectionHost: 'packages/client/connection/lib/index.js',
       goal: 'packages/goal/goal/lib/index.js',
       goalTypert: 'packages/goal/goal/lib/typert.host.js',
       registryClient: 'packages/typert/registry/lib/client.js',
       registryHost: 'packages/typert/registry/lib/index.js',
-      remotesClient: 'packages/client/remotes/lib/client.js',
+      remotesClient: 'packages/api/remotes/lib/client.js',
       session: 'packages/core/session/lib/index.js',
     }).map(([key, path]) => [key, artifactUrl(path)]))
     const script = `
@@ -131,8 +131,8 @@ describe.skipIf(!requiredArtifacts)('Goal Remote built LIB chain', () => {
       for (const id of [
         '@deepseek-ai/dsh-typert-registry',
         '@deepseek-ai/dsh-client-connection',
-        '@deepseek-ai/dsh-host-api-gateway',
-        '@deepseek-ai/dsh-client-remotes',
+        '@deepseek-ai/dsh-api-gateway',
+        '@deepseek-ai/dsh-api-remotes',
       ]) {
         const plugin = instantiate(id)
         await client.plugin({ inject: plugin.inject, apply: plugin.apply })
diff --git a/packages/client/remotes/tsconfig.json b/packages/api/remotes/tsconfig.json
similarity index 63%
rename from packages/client/remotes/tsconfig.json
rename to packages/api/remotes/tsconfig.json
index c99a5fce19..148804dc0f 100644
--- a/packages/client/remotes/tsconfig.json
+++ b/packages/api/remotes/tsconfig.json
@@ -12,7 +12,19 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../host/api-gateway"
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../session-persistence/session-persistence"
+    },
+    {
+      "path": "../../typert/type-meta"
+    },
+    {
+      "path": "../../typert/registry"
     },
     {
       "path": "../../ui/commands"
diff --git a/packages/api/remotes/tsdown.config.ts b/packages/api/remotes/tsdown.config.ts
new file mode 100644
index 0000000000..287b2c7975
--- /dev/null
+++ b/packages/api/remotes/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../../client/tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-api-remotes', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml
index 0b1cc43a50..11b23c27be 100644
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -41,7 +41,7 @@
       name: '@deepseek-ai/dsh-typert-loader'
 
     - id: typert-gateway
-      name: '@deepseek-ai/dsh-host-api-gateway'
+      name: '@deepseek-ai/dsh-api-gateway'
 
     - id: session-title
       name: '@deepseek-ai/dsh-session-title'
diff --git a/packages/bundle/base/package.json b/packages/bundle/base/package.json
index 2ec17d9c66..9895d8834c 100644
--- a/packages/bundle/base/package.json
+++ b/packages/bundle/base/package.json
@@ -49,7 +49,7 @@
     "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-goal-session": "workspace:^",
-    "@deepseek-ai/dsh-host-api-gateway": "workspace:^",
+    "@deepseek-ai/dsh-api-gateway": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
     "@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 001c43948d..dc3212a36c 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -124,8 +124,8 @@
     - id: connection
       name: '@deepseek-ai/dsh-client-connection'
 
-    - id: client-remotes
-      name: '@deepseek-ai/dsh-client-remotes'
+    - id: api-remotes
+      name: '@deepseek-ai/dsh-api-remotes'
 
     - id: client-runtime
       name: '@deepseek-ai/dsh-client-runtime'
diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json
index 89b5e8e2a7..4e2d9cf70b 100644
--- a/packages/bundle/web-app/package.json
+++ b/packages/bundle/web-app/package.json
@@ -36,7 +36,7 @@
     "@deepseek-ai/dsh-client-hmr": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-modules": "workspace:^",
-    "@deepseek-ai/dsh-client-remotes": "workspace:^",
+    "@deepseek-ai/dsh-api-remotes": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-command": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
diff --git a/packages/client/remotes/README.md b/packages/client/remotes/README.md
deleted file mode 100644
index e29188b8e3..0000000000
--- a/packages/client/remotes/README.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# @deepseek-ai/dsh-client-remotes
-
-English | [中文](README.zh.md)
-
-Platform-neutral Client facade for Host Remote capabilities selected by this application. Its Client entry imports generated `/remote` artifacts as runtime values, mounts each contribution through `ctx.api`, and re-exports their declaration merges. Client business packages depend on this facade rather than the Host API Gateway or individual Remote runtime entries.
-
-The current assembly mounts only the Goal Remote contribution. Cordis effect ownership withdraws every contribution when this assembly unloads, while the Client face of `@deepseek-ai/dsh-host-api-gateway` owns descriptor validation, concrete root and scoped methods, invocation, and cancellation.
-
-This package contains no transport or Host discovery logic. It can be reused by Web or a future TUI Client that provides the same React-free `ctx.api` contract.
-
-## Model Experience
-
-None, as this Client assembly selects Remote application methods and registers no model surface.
-
-#### KV Cache effect
-
-No direct effect; mounted Host capabilities own any model-visible behavior they trigger.
-
-## Known Limitations and Deferred Work
-
-- The capability set is fixed by explicit build-time value imports; the Client does not discover the Host's active Services or Remote definitions at runtime.
-- Additional capabilities require an explicit `/remote` value import and mount in this assembly.
diff --git a/packages/client/remotes/README.zh.md b/packages/client/remotes/README.zh.md
deleted file mode 100644
index e6425ab190..0000000000
--- a/packages/client/remotes/README.zh.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# @deepseek-ai/dsh-client-remotes
-
-[English](README.md) | 中文
-
-为本应用选定的 Host Remote 能力提供平台无关的 Client 外观。其 Client 入口以运行时值形式导入生成的 `/remote` 产物，通过 `ctx.api` 挂载每项贡献，并重新导出对应的声明合并。Client 业务包依赖此外观，而不依赖 Host API Gateway 或单独的 Remote 运行时入口。
-
-当前组合仅挂载 Goal Remote 贡献。该组合卸载时，Cordis effect 的所有权机制会撤回所有贡献；`@deepseek-ai/dsh-host-api-gateway` 的 Client 侧负责描述符校验、具体的根级方法和作用域方法、调用与取消。
-
-本包不包含传输逻辑或 Host 发现逻辑。Web 和未来的 TUI Client 只要提供同一份不依赖 React 的 `ctx.api` 契约，均可复用本包。
-
-## 模型体验
-
-无，因为此 Client 组合只选择应用的 Remote 方法，不注册任何模型接口。
-
-#### KV Cache 影响
-
-无直接影响；其触发的任何模型可见行为均由已挂载的 Host 能力负责。
-
-## 已知限制与暂缓事项
-
-- 能力集合由构建时显式导入的值固定确定；Client 不会在运行时发现 Host 中已启用的服务或 Remote 定义。
-- 若要增加能力，必须显式导入相应的 `/remote` 值并在此组合中挂载。
diff --git a/packages/client/remotes/src/index.ts b/packages/client/remotes/src/index.ts
deleted file mode 100644
index c8c4ff20be..0000000000
--- a/packages/client/remotes/src/index.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-/** Host Loader entry for the Client Remote contribution assembly. */
-
-/** Host plugin body; the selected contributions mount only in Client environments. */
-export function apply(): void {}
diff --git a/packages/client/remotes/tsdown.config.ts b/packages/client/remotes/tsdown.config.ts
deleted file mode 100644
index 20fa098462..0000000000
--- a/packages/client/remotes/tsdown.config.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import { clientBundle } from '../tsdown.client.ts'
-
-export default clientBundle('@deepseek-ai/dsh-client-remotes', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
index cc51aa772d..711510b705 100644
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -25,7 +25,7 @@
   "dshClient": {
     "inject": [
       "@deepseek-ai/dsh-client-connection",
-      "@deepseek-ai/dsh-client-remotes",
+      "@deepseek-ai/dsh-api-remotes",
       "@deepseek-ai/dsh-typert-registry"
     ],
     "platform": "web",
@@ -49,14 +49,14 @@
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-client-remotes": "^0.0.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.0.1",
     "@deepseek-ai/dsh-type-meta": "^0.0.1",
     "@deepseek-ai/dsh-typert-registry": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-client-remotes": "workspace:^",
+    "@deepseek-ai/dsh-api-remotes": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
     "@deepseek-ai/dsh-type-meta": "workspace:^",
     "@deepseek-ai/dsh-typert-registry": "workspace:^",
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index f1efd6a65d..a9d2bb0d7d 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -1,7 +1,7 @@
 /** Browser runtime services for slots, sessions, workspaces, and connection-stream delivery. */
 import type { Context } from 'cordis'
 import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
-import type {} from '@deepseek-ai/dsh-client-remotes/client'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
 import type { TypeRTContext } from '@deepseek-ai/dsh-type-meta'
 import type { MaybeSnapshotSelectorHook, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from './slots.ts'
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index 85ba61d41a..efbf7c26d7 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../connection"
     },
     {
-      "path": "../remotes"
+      "path": "../../api/remotes"
     },
     {
       "path": "../../host/apiproxy"
diff --git a/packages/client/ui-goal/package.json b/packages/client/ui-goal/package.json
index 4c26405bd8..63410707a0 100644
--- a/packages/client/ui-goal/package.json
+++ b/packages/client/ui-goal/package.json
@@ -25,7 +25,7 @@
   "dshClient": {
     "inject": [
       "@deepseek-ai/dsh-client-runtime",
-      "@deepseek-ai/dsh-client-remotes",
+      "@deepseek-ai/dsh-api-remotes",
       "@deepseek-ai/dsh-client-locale",
       "@deepseek-ai/dsh-client-ui-conversation"
     ],
@@ -38,7 +38,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-client-locale": "^0.0.1",
-    "@deepseek-ai/dsh-client-remotes": "^0.0.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-client-locale": "workspace:^",
-    "@deepseek-ai/dsh-client-remotes": "workspace:^",
+    "@deepseek-ai/dsh-api-remotes": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
diff --git a/packages/client/ui-goal/src/client/index.ts b/packages/client/ui-goal/src/client/index.ts
index 8fcfd292d2..2e49d5b6b8 100644
--- a/packages/client/ui-goal/src/client/index.ts
+++ b/packages/client/ui-goal/src/client/index.ts
@@ -10,7 +10,7 @@
  */
 import type { ClientContext, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 // Type-only: pulls the generated Remote API and ctx.api merge through the Client assembly boundary.
-import type {} from '@deepseek-ai/dsh-client-remotes/client'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
 // Type-only: pulls the ui-conversation SlotMap merge (the input.dock entry).
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
diff --git a/packages/client/ui-goal/tsconfig.json b/packages/client/ui-goal/tsconfig.json
index 2bb4070b18..263dfceb26 100644
--- a/packages/client/ui-goal/tsconfig.json
+++ b/packages/client/ui-goal/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../locale"
     },
     {
-      "path": "../remotes"
+      "path": "../../api/remotes"
     },
     {
       "path": "../runtime"
diff --git a/packages/host/api-gateway/tsdown.config.ts b/packages/host/api-gateway/tsdown.config.ts
deleted file mode 100644
index 1f95a1f2c5..0000000000
--- a/packages/host/api-gateway/tsdown.config.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import { clientBundle } from '../../client/tsdown.client.ts'
-
-export default clientBundle('@deepseek-ai/dsh-host-api-gateway', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/packages/host/apiproxy/package.json b/packages/host/apiproxy/package.json
index ce740a025f..91d03b4448 100644
--- a/packages/host/apiproxy/package.json
+++ b/packages/host/apiproxy/package.json
@@ -39,6 +39,7 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-api-remotes": "workspace:^",
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-credentials": "workspace:^",
@@ -56,8 +57,6 @@
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-subagent": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
-    "@deepseek-ai/dsh-type-meta": "workspace:^",
-    "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",
     "@deepseek-ai/dsh-workspace": "workspace:^",
@@ -71,6 +70,8 @@
   "devDependencies": {
     "@deepseek-ai/dsh-storage": "workspace:^",
     "@deepseek-ai/dsh-storage-domain": "workspace:^",
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "cordis": "^4.0.0-rc.7",
     "@deepseek-ai/dsh-invariants": "workspace:^"
   }
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index f2c199feca..e4b715a0c4 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -19,9 +19,6 @@ import { SessionQueryError, type SessionSearchCursor } from '@deepseek-ai/dsh-se
 import { SubagentError } from '@deepseek-ai/dsh-subagent'
 import type { SubagentListEntry as CatalogSubagentListEntry } from '@deepseek-ai/dsh-subagent'
 import type { Workspace, WorkspaceRecord } from '@deepseek-ai/dsh-workspace'
-import { TypeRTLookupFailure } from '@deepseek-ai/dsh-type-meta'
-// Type-only: resolves the optional `ctx.typert` lookup-policy composition.
-import type {} from '@deepseek-ai/dsh-typert-registry'
 import {
   workspaceDomainState, workspaceRecord, WorkspaceId as brandWorkspaceId,
   WorkspaceMoveInvalidError, WorkspaceUnknownSessionError,
@@ -72,6 +69,14 @@ import type {
 } from '@deepseek-ai/dsh-user-interaction'
 import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction'
 import { DirectoryPickerError } from '@deepseek-ai/dsh-host-directory-picker'
+import {
+  ApiRemoteSessionNotFound as SessionNotFound,
+  ApiRemoteSubagentSessionOwnership as SubagentSessionOwnership,
+  apiRemoteSubagentOwnershipError,
+  createApiRemoteAgentResolver,
+  hasApiRemoteSubagentOwner,
+  inspectApiRemoteSession,
+} from '@deepseek-ai/dsh-api-remotes'
 import { openNativePath, openNativeTextFile } from './native-path-opener.ts'
 
 /** Page size when history is called without maxMessages. */
@@ -666,19 +671,6 @@ async function catalogChild(
   }
 }
 
-/**
- * Thrown by the cold-resume path when the id names no servable session
- * (absent from the store, or a pre-project legacy log without a cwd).
- */
-class SessionNotFound extends Error {}
-
-/** Session identity whose lifecycle belongs to subagent routing, not generic Host resume. */
-class SubagentSessionOwnership extends Error {
-  constructor(readonly sessionId: SessionId) {
-    super(`session "${sessionId}" is a subagent session; use subagent delivery`)
-  }
-}
-
 /** Requested identity already belongs to a session with another project cwd. */
 class SessionCwdConflict extends Error {
   constructor(
@@ -752,8 +744,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
   }
   type WebLlmTargetRef = AgentLlmTargetRef & { current: AgentLlmTarget }
   const targets = new WeakMap<Agent, WebLlmTargetRef>()
-  /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
-  const resumes = new Map<SessionId, Promise<Agent>>()
   /** Client-chosen identity creation/resume, deduplicated across concurrent retries. */
   const sessionCreations = new Map<SessionId, Promise<Agent>>()
   /** Serializes path ownership and explicit title checks with Workspace mutations. */
@@ -811,6 +801,16 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     targetFor(agent)
   }
 
+  const hasSubagentOwner = (
+    session: Pick<Session, 'header'>,
+    agent: Agent | undefined,
+  ): boolean => hasApiRemoteSubagentOwner(ctx, session, agent)
+  const subagentOwnershipError = (sessionId: SessionId): RpcError =>
+    apiRemoteSubagentOwnershipError(sessionId)
+  const inspectServable = (sessionId: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> =>
+    inspectApiRemoteSession(ctx, sessionId)
+  const agentFor = createApiRemoteAgentResolver(ctx, { agentOptions, setup: installTarget })
+
   /** Send one transient frame to every connected mux consumer. */
   function broadcast(payload: MuxFrame): void {
     const envelope = frame(payload)
@@ -992,131 +992,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     })
   }
 
-  /**
-   * Generic Host interaction cannot claim a durably classified subagent
-   * (`origin: 'subagent'` in the header) or an Agent runtime-owned by its
-   * live parent.
-   */
-  function hasSubagentOwner(
-    session: Pick<Session, 'header'>,
-    agent: Agent | undefined,
-  ): boolean {
-    if (session.header.origin === 'subagent') return true
-    const parentId = session.header.parentSession
-    if (parentId === undefined || agent === undefined) return false
-    const parent = ctx.agents.get(parentId)
-    return parent !== undefined && ctx.agents.isOwnedBy(agent.id, parent)
-  }
-
-  /** Stable generic-Host error for an identity reserved to subagent routing. */
-  function subagentOwnershipError(sessionId: SessionId): RpcError {
-    return {
-      code: 'agent-busy',
-      message: `session "${sessionId}" is owned by subagent routing`,
-      details: { reason: 'use subagent delivery for this child session' },
-    }
-  }
-
-  /** Inspect one cold served session without repairing, resuming, or publishing it. */
-  async function inspectServable(sessionId: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    const persistence = ctx.get('sessionPersistence')
-    if (persistence === undefined) {
-      throw new Error('session persistence is not configured (load a dsh-session-persistence backend)')
-    }
-    const meta = (await persistence.list()).find(m => m.id === sessionId)
-    if (meta === undefined || meta.cwd === undefined) throw new SessionNotFound(`session "${sessionId}" not found`)
-    const inspected = await persistence.inspect(sessionId)
-    if (inspected.meta.cwd === undefined) throw new SessionNotFound(`session "${sessionId}" not found`)
-    return { meta: inspected.meta, events: [...inspected.events] }
-  }
-
-  /**
-   * Resolve one live registered identity through the subagent-ownership
-   * fence: subagent-owned agents answer `agent-busy`, plain agents pass.
-   * Fences the live agent's own session rather than trusting a
-   * "registered ⇒ attached-store" invariant — a registered subagent whose
-   * session is ever absent from the attached store must still not be handed
-   * out through generic Host routing. `undefined` means no live agent.
-   */
-  function fencedLiveAgent(sessionId: SessionId): { agent: Agent } | { error: RpcError } | undefined {
-    const live = ctx.agents.get(sessionId)
-    if (live === undefined) return undefined
-    if (hasSubagentOwner(live.session, live)) return { error: subagentOwnershipError(sessionId) }
-    return { agent: live }
-  }
-
-  async function agentFor(sessionId: SessionId): Promise<{ agent: Agent } | { error: RpcError }> {
-    const fenced = fencedLiveAgent(sessionId)
-    if (fenced !== undefined) return fenced
-    const attached = ctx.sessions.get(sessionId)
-    if (attached !== undefined && hasSubagentOwner(attached, undefined)) {
-      return { error: subagentOwnershipError(sessionId) }
-    }
-    let resume = resumes.get(sessionId)
-    if (resume === undefined) {
-      resume = (async () => {
-        try {
-          const inspected = await inspectServable(sessionId)
-          if (hasSubagentOwner({ header: inspected.meta }, undefined)) {
-            throw new SubagentSessionOwnership(sessionId)
-          }
-          const publishedSession = ctx.sessions.get(sessionId)
-          const publishedAgent = ctx.agents.get(sessionId)
-          if (publishedSession !== undefined && hasSubagentOwner(publishedSession, publishedAgent)) {
-            throw new SubagentSessionOwnership(sessionId)
-          }
-          const handle = await ctx.agents.resume({
-            resumeSessionId: sessionId,
-            agentOptions: agentOptions(),
-            setup: installTarget,
-          })
-          return handle.agent
-        } finally {
-          resumes.delete(sessionId)
-        }
-      })()
-      resumes.set(sessionId, resume)
-    }
-    try {
-      return { agent: await resume }
-    } catch (error: unknown) {
-      if (error instanceof SessionNotFound) {
-        return { error: { code: 'session-not-found', message: error.message, details: { sessionId } } }
-      }
-      if (error instanceof SubagentSessionOwnership) {
-        return { error: subagentOwnershipError(error.sessionId) }
-      }
-      // A concurrent publish can win the identity between the pre-resume
-      // re-check and `ctx.agents.resume` publication; the ID-collision
-      // rejection falls through here. Mirror ensureSession's `.catch` in
-      // full: classify a subagent-owned winner into the stable ownership
-      // error, and hand a clean plain-agent winner straight back.
-      const fenced = fencedLiveAgent(sessionId)
-      if (fenced !== undefined) return fenced
-      const attached = ctx.sessions.get(sessionId)
-      if (attached !== undefined && hasSubagentOwner(attached, undefined)) {
-        return { error: subagentOwnershipError(sessionId) }
-      }
-      // The internal details slot is contractually {}; the reason rides the message.
-      return { error: { code: 'internal', message: `resume failed for session "${sessionId}": ${String(error)}`, details: {} } }
-    }
-  }
-
-  // Remote object parameters use the same identity policy as API Proxy methods:
-  // ordinary cold sessions resume once, while subagent-owned identities retain
-  // their stable caller-facing rejection. The provider packages continue to
-  // own wire declarations and live-only defaults; this Host composition owns
-  // the broader lookup policy.
-  ctx.inject(['typert'], (typeCtx) => {
-    const resolveAgent = async (sessionId: SessionId): Promise<Agent> => {
-      const found = await agentFor(sessionId)
-      if ('error' in found) throw new TypeRTLookupFailure(found.error)
-      return found.agent
-    }
-    typeCtx.typert.lookups.configure('agent', resolveAgent)
-    typeCtx.typert.lookups.configure('session', async sessionId => (await resolveAgent(sessionId)).session)
-  })
-
   type SessionReadState = {
     id: SessionId
     header: SessionHeader
diff --git a/packages/host/apiproxy/tsconfig.json b/packages/host/apiproxy/tsconfig.json
index 23c170f4fd..912f2cd794 100644
--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -23,6 +23,9 @@
     {
       "path": "../../../vendor/schemastery"
     },
+    {
+      "path": "../../api/remotes"
+    },
     {
       "path": "../../util/brand"
     },
@@ -38,12 +41,6 @@
     {
       "path": "../../core/tools"
     },
-    {
-      "path": "../../typert/type-meta"
-    },
-    {
-      "path": "../../typert/registry"
-    },
     {
       "path": "../../session-persistence/session-persistence"
     },
diff --git a/packages/typert/type-meta/src/index.ts b/packages/typert/type-meta/src/index.ts
index 7ded29fa4a..1418c9d7f2 100644
--- a/packages/typert/type-meta/src/index.ts
+++ b/packages/typert/type-meta/src/index.ts
@@ -41,6 +41,7 @@ export type {
   InvocationDescriptor,
   InvocationParameterDescriptor,
   InvocationSourceLocation,
+  TypeRTClientApi,
   TypeRTClientContextBinder,
   TypeRTCodec,
   TypeRTContext,
diff --git a/packages/typert/type-meta/src/types.ts b/packages/typert/type-meta/src/types.ts
index 7831c08e37..b65690115f 100644
--- a/packages/typert/type-meta/src/types.ts
+++ b/packages/typert/type-meta/src/types.ts
@@ -176,6 +176,16 @@ export interface TypeRTRemoteContribution {
   readonly descriptors: readonly InvocationDescriptor[]
 }
 
+/** Client API capability implemented by the Gateway and consumed by Remote assemblies. */
+export interface TypeRTClientApi extends TypeRTRemoteNamespaceMap {
+  /**
+   * Mount one generated Host-for-Client contribution in the caller's fiber.
+   * @param contribution - explicitly selected Remote package artifact.
+   * @returns disposer withdrawing descriptors and concrete methods together.
+   */
+  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer
+}
+
 /**
  * Resolve one validated wire identity, synchronously or asynchronously.
  * @param id - validated wire identity.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e0adfb22c1..bd4ff1ea14 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -621,6 +621,59 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/api/gateway:
+    dependencies:
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../../typert/type-meta
+    devDependencies:
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../../client/connection
+      '@deepseek-ai/dsh-host-webserver':
+        specifier: workspace:^
+        version: link:../../host/webserver
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-typert-registry':
+        specifier: workspace:^
+        version: link:../../typert/registry
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+
+  packages/api/remotes:
+    dependencies:
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../../typert/type-meta
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-goal':
+        specifier: workspace:^
+        version: link:../../goal/goal
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence':
+        specifier: workspace:^
+        version: link:../../session-persistence/session-persistence
+      '@deepseek-ai/dsh-typert-registry':
+        specifier: workspace:^
+        version: link:../../typert/registry
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/bash/bash:
     devDependencies:
       '@deepseek-ai/dsh-invariants':
@@ -877,6 +930,9 @@ importers:
       '@deepseek-ai/dsh-agent-loop':
         specifier: workspace:^
         version: link:../../core/agent-loop
+      '@deepseek-ai/dsh-api-gateway':
+        specifier: workspace:^
+        version: link:../../api/gateway
       '@deepseek-ai/dsh-bash-env':
         specifier: workspace:^
         version: link:../../bash/bash-env
@@ -916,9 +972,6 @@ importers:
       '@deepseek-ai/dsh-goal-session':
         specifier: workspace:^
         version: link:../../goal/goal-session
-      '@deepseek-ai/dsh-host-api-gateway':
-        specifier: workspace:^
-        version: link:../../host/api-gateway
       '@deepseek-ai/dsh-llm':
         specifier: workspace:^
         version: link:../../llm/llm
@@ -1119,6 +1172,9 @@ importers:
 
   packages/bundle/web-app:
     dependencies:
+      '@deepseek-ai/dsh-api-remotes':
+        specifier: workspace:^
+        version: link:../../api/remotes
       '@deepseek-ai/dsh-client-connection':
         specifier: workspace:^
         version: link:../../client/connection
@@ -1131,9 +1187,6 @@ importers:
       '@deepseek-ai/dsh-client-modules':
         specifier: workspace:^
         version: link:../../client/modules
-      '@deepseek-ai/dsh-client-remotes':
-        specifier: workspace:^
-        version: link:../../client/remotes
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../../client/runtime
@@ -1348,21 +1401,6 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/client/remotes:
-    devDependencies:
-      '@deepseek-ai/dsh-goal':
-        specifier: workspace:^
-        version: link:../../goal/goal
-      '@deepseek-ai/dsh-host-api-gateway':
-        specifier: workspace:^
-        version: link:../../host/api-gateway
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
   packages/client/runtime:
     dependencies:
       '@deepseek-ai/dsh-client-connection':
@@ -1405,9 +1443,9 @@ importers:
         specifier: ~4.4.7
         version: 4.4.7(@types/react@18.3.31)(immer@10.2.0)(react@18.3.1)
     devDependencies:
-      '@deepseek-ai/dsh-client-remotes':
+      '@deepseek-ai/dsh-api-remotes':
         specifier: workspace:^
-        version: link:../remotes
+        version: link:../../api/remotes
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -1617,12 +1655,12 @@ importers:
 
   packages/client/ui-goal:
     devDependencies:
+      '@deepseek-ai/dsh-api-remotes':
+        specifier: workspace:^
+        version: link:../../api/remotes
       '@deepseek-ai/dsh-client-locale':
         specifier: workspace:^
         version: link:../locale
-      '@deepseek-ai/dsh-client-remotes':
-        specifier: workspace:^
-        version: link:../remotes
       '@deepseek-ai/dsh-client-runtime':
         specifier: workspace:^
         version: link:../runtime
@@ -3757,36 +3795,14 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/host/api-gateway:
-    dependencies:
-      '@deepseek-ai/dsh-type-meta':
-        specifier: workspace:^
-        version: link:../../typert/type-meta
-    devDependencies:
-      '@deepseek-ai/dsh-client-connection':
-        specifier: workspace:^
-        version: link:../../client/connection
-      '@deepseek-ai/dsh-host-webserver':
-        specifier: workspace:^
-        version: link:../webserver
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-typert-registry':
-        specifier: workspace:^
-        version: link:../../typert/registry
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-      zod:
-        specifier: ^4.4.3
-        version: 4.4.3
-
   packages/host/apiproxy:
     dependencies:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
+      '@deepseek-ai/dsh-api-remotes':
+        specifier: workspace:^
+        version: link:../../api/remotes
       '@deepseek-ai/dsh-brand':
         specifier: workspace:^
         version: link:../../util/brand
@@ -3838,12 +3854,6 @@ importers:
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
-      '@deepseek-ai/dsh-type-meta':
-        specifier: workspace:^
-        version: link:../../typert/type-meta
-      '@deepseek-ai/dsh-typert-registry':
-        specifier: workspace:^
-        version: link:../../typert/registry
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
         version: link:../../ui/user-approval
@@ -3869,6 +3879,12 @@ importers:
       '@deepseek-ai/dsh-storage-domain':
         specifier: workspace:^
         version: link:../../storage/storage-domain
+      '@deepseek-ai/dsh-type-meta':
+        specifier: workspace:^
+        version: link:../../typert/type-meta
+      '@deepseek-ai/dsh-typert-registry':
+        specifier: workspace:^
+        version: link:../../typert/registry
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 088329e83d..54581a8605 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -289,7 +289,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   ThemeTokens: 'service-local token dictionary is owned by packages/client/ui-theme/src/index.ts',
   Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
-  InvokeRemoteRequest: 'gateway invocation contract is owned by packages/host/api-gateway/README.md',
+  InvokeRemoteRequest: 'gateway invocation contract is owned by packages/api/gateway/README.md',
   PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
   PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
   KnobState: 'projection unit state shape is owned by packages/ui/permission/README.md',
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 6d6a76e476..9adc3d9768 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -601,7 +601,7 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts',
     'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
     'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
-    'packages/client/remotes/tests/built-lib.e2e.ts',
+    'packages/api/remotes/tests/built-lib.e2e.ts',
     // The worker-entry packages' built bundles: the only automated proof
     // that lib/index.js resolves its sibling lib/worker.cjs under plain node
     // (the e2e lane runs unbuilt, so these files self-skip there).
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index edadc3f134..ecb13f167c 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1538,22 +1538,22 @@
     {
       "doc": "docs/core-data-structures/typert.md",
       "symbol": "InvokeRemoteRequest",
-      "source": "packages/host/api-gateway/src/types.ts"
+      "source": "packages/api/gateway/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/typert.md",
       "symbol": "TypertGatewayErrorCode",
-      "source": "packages/host/api-gateway/src/types.ts"
+      "source": "packages/api/gateway/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/typert.md",
       "symbol": "TypertGateway",
-      "source": "packages/host/api-gateway/src/types.ts"
+      "source": "packages/api/gateway/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/typert.md",
-      "symbol": "ClientApi",
-      "source": "packages/host/api-gateway/src/client/index.ts"
+      "symbol": "TypeRTClientApi",
+      "source": "packages/typert/type-meta/src/types.ts"
     }
   ]
 }
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 78745dbed1..e131d6c403 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -57,7 +57,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/web-react': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/schema-form': { kind: 'none', reason: 'Browser-side form-rendering library; registers no model surface.' },
   'packages/client/connection': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/remotes': { kind: 'none', reason: 'Client-side Remote assembly; selected business methods own any model-visible effect.' },
+  'packages/api/remotes': { kind: 'none', reason: 'The Remote BFF selects business methods and identity policy; selected services own any model-visible effect.' },
   'packages/client/runtime': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
@@ -126,7 +126,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/support/loader-smoke': { kind: 'none', reason: 'The test harness observes child-process streams without changing live requests.' },
   'packages/support/llm-mock-server': { kind: 'none', reason: 'The test server substitutes provider wire behavior without invoking a real model.' },
   'packages/support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
-  'packages/host/api-gateway': { kind: 'none', reason: 'Remote dispatch infrastructure; invoked business methods own any model-visible effect.' },
+  'packages/api/gateway': { kind: 'none', reason: 'Remote dispatch infrastructure; invoked business methods own any model-visible effect.' },
   'packages/typert/type-meta': { kind: 'none', reason: 'Compiler-independent Remote protocol declarations; registers no model surface.' },
   'packages/typert/generator': { kind: 'none', reason: 'The build-time generator runs outside any agent runtime and touches no model request.' },
   'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index ce4fca35f9..b9907348fa 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -41,10 +41,10 @@
       "@deepseek-ai/dsh-invariants": ["./packages/support/invariants/src/index.ts"],
       "@deepseek-ai/dsh-typert-registry": ["./packages/typert/registry/src/index.ts"],
       "@deepseek-ai/dsh-typert-registry/client": ["./packages/typert/registry/src/client/index.ts"],
-      "@deepseek-ai/dsh-host-api-gateway": ["./packages/host/api-gateway/src/index.ts"],
-      "@deepseek-ai/dsh-host-api-gateway/client": ["./packages/host/api-gateway/src/client/index.ts"],
-      "@deepseek-ai/dsh-host-api-gateway/invariant": ["./packages/host/api-gateway/src/invariant.ts"],
-      "@deepseek-ai/dsh-host-api-gateway/types": ["./packages/host/api-gateway/src/types.ts"],
+      "@deepseek-ai/dsh-api-gateway": ["./packages/api/gateway/src/index.ts"],
+      "@deepseek-ai/dsh-api-gateway/client": ["./packages/api/gateway/src/client/index.ts"],
+      "@deepseek-ai/dsh-api-gateway/invariant": ["./packages/api/gateway/src/invariant.ts"],
+      "@deepseek-ai/dsh-api-gateway/types": ["./packages/api/gateway/src/types.ts"],
       "@deepseek-ai/dsh-type-meta": ["./packages/typert/type-meta/src/index.ts"],
       "@deepseek-ai/dsh-type-meta/types": ["./packages/typert/type-meta/src/types.ts"],
       "@deepseek-ai/dsh-typert-loader": ["./packages/typert/loader/src/index.ts"],
@@ -151,8 +151,8 @@
       "@deepseek-ai/dsh-client-schema-form/invariant": ["./packages/client/schema-form/src/invariant.ts"],
       "@deepseek-ai/dsh-client-web-react": ["./packages/client/web-react/src"],
       "@deepseek-ai/dsh-client-connection": ["./packages/client/connection/src"],
-      "@deepseek-ai/dsh-client-remotes": ["./packages/client/remotes/src"],
-      "@deepseek-ai/dsh-client-remotes/client": ["./packages/client/remotes/src/client/index.ts"],
+      "@deepseek-ai/dsh-api-remotes": ["./packages/api/remotes/src"],
+      "@deepseek-ai/dsh-api-remotes/client": ["./packages/api/remotes/src/client/index.ts"],
       "@deepseek-ai/dsh-client-hmr": ["./packages/client/hmr/src"],
       "@deepseek-ai/dsh-client-modules": ["./packages/client/modules/src"],
       "@deepseek-ai/dsh-client-runtime": ["./packages/client/runtime/src"],
diff --git a/tsconfig.client.json b/tsconfig.client.json
index 327b337963..9821c0e41b 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -52,8 +52,8 @@
     { "path": "./packages/client/hmr" },
     { "path": "./packages/client/connection" },
     { "path": "./packages/typert/registry" },
-    { "path": "./packages/host/api-gateway" },
-    { "path": "./packages/client/remotes" },
+    { "path": "./packages/api/gateway" },
+    { "path": "./packages/api/remotes" },
     { "path": "./packages/client/runtime" },
     { "path": "./packages/client/test-runtime" },
     { "path": "./packages/client/ui-layout" },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 37c20c0d5c..6884839536 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -102,7 +102,7 @@
     { "path": "./packages/core/scope" },
     { "path": "./packages/typert/type-meta" },
     { "path": "./packages/typert/registry" },
-    { "path": "./packages/host/api-gateway" },
+    { "path": "./packages/api/gateway" },
     { "path": "./packages/typert/loader" },
     { "path": "./packages/session-persistence/session-persistence" },
     { "path": "./packages/session-persistence/session-checkpoint-policy" },
diff --git a/vitest.config.ts b/vitest.config.ts
index 56a5a1575b..f5a86ac7a9 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -181,8 +181,8 @@ export default defineConfig({
         'packages/client/connection/src/http-bridge.ts',
         // This assembly imports generated Host-for-Client code that exists
         // only in lib; the post-build built-bin smoke executes both entries.
-        'packages/client/remotes/src/index.ts',
-        'packages/client/remotes/src/client/index.ts',
+        'packages/api/remotes/src/index.ts',
+        'packages/api/remotes/src/client/index.ts',
         // Slash/command/input round: per-file gaps deferred with the same
         // client-lane debt. TODO(gui): cover and remove with the lane above.
         'packages/client/connection/src/client/fixture.ts',

From 502bd2b6f736d8baafb115d512589003eba4c41c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 16:00:35 +0800
Subject: [PATCH 143/516] fix: docs

---
 docs/module-graph.md | 111 ++++++++-----------------------------------
 1 file changed, 19 insertions(+), 92 deletions(-)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index 43923e0865..9cf6f4c895 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -421,13 +421,6 @@ flowchart TD
   pkg_app_boot --> pkg_invariants
   pkg_app_boot --> pkg_paths
   pkg_app_boot --> pkg_system_prompt
-<<<<<<< HEAD
-  pkg_client_ui_layout --> pkg_client_runtime
-  pkg_client_ui_layout --> pkg_client_ui_slots
-  pkg_client_ui_layout --> pkg_client_ui_theme
-  pkg_client_ui_layout --> pkg_invariants
-=======
->>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
   pkg_code_runtime_worker --> pkg_code_runtime
   pkg_code_runtime_worker --> pkg_invariants
   pkg_code_runtime_worker --> pkg_session
@@ -616,31 +609,15 @@ flowchart TD
   pkg_permission --> pkg_session_projection
   pkg_permission --> pkg_settings
   pkg_permission --> pkg_user_approval
-<<<<<<< HEAD
-<<<<<<< HEAD
-  pkg_client_ui_conversation --> pkg_client_locale
-  pkg_client_ui_conversation --> pkg_client_runtime
-  pkg_client_ui_conversation --> pkg_client_ui_primitives
-  pkg_client_ui_conversation --> pkg_client_ui_slash
-  pkg_client_ui_conversation --> pkg_client_ui_slots
-  pkg_client_ui_conversation --> pkg_invariants
-  pkg_client_ui_conversation --> pkg_token_meter
-  pkg_command_feedback --> pkg_commands
-  pkg_command_feedback --> pkg_invariants
-  pkg_command_feedback --> pkg_session
-=======
-  pkg_client_remotes --> pkg_goal
-  pkg_client_remotes --> pkg_host_api_gateway
-  pkg_client_remotes --> pkg_invariants
->>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
-=======
   pkg_api_remotes --> pkg_agent
   pkg_api_remotes --> pkg_goal
   pkg_api_remotes --> pkg_invariants
   pkg_api_remotes --> pkg_session
   pkg_api_remotes --> pkg_session_persistence
   pkg_api_remotes --> pkg_typert_registry
->>>>>>> c671d9e48c (refactor(api): colocate gateway and remote assembly)
+  pkg_command_feedback --> pkg_commands
+  pkg_command_feedback --> pkg_invariants
+  pkg_command_feedback --> pkg_session
   pkg_pty_local --> pkg_agent
   pkg_pty_local --> pkg_invariants
   pkg_pty_local --> pkg_pty
@@ -794,46 +771,10 @@ flowchart TD
   pkg_tool_ask_user --> pkg_invariants
   pkg_tool_ask_user --> pkg_tools
   pkg_tool_ask_user --> pkg_user_interaction
-<<<<<<< HEAD
-<<<<<<< HEAD
-  pkg_client_ui_command --> pkg_client_connection
-  pkg_client_ui_command --> pkg_client_locale
-  pkg_client_ui_command --> pkg_client_runtime
-  pkg_client_ui_command --> pkg_client_ui_conversation
-  pkg_client_ui_command --> pkg_client_ui_primitives
-  pkg_client_ui_command --> pkg_client_ui_slash
-  pkg_client_ui_command --> pkg_client_ui_slots
-  pkg_client_ui_command --> pkg_invariants
-  pkg_client_ui_deliverables --> pkg_client_locale
-  pkg_client_ui_deliverables --> pkg_client_runtime
-  pkg_client_ui_deliverables --> pkg_client_ui_conversation
-  pkg_client_ui_deliverables --> pkg_client_ui_slots
-  pkg_client_ui_deliverables --> pkg_invariants
-  pkg_client_ui_goal --> pkg_client_connection
-  pkg_client_ui_goal --> pkg_client_locale
-  pkg_client_ui_goal --> pkg_client_runtime
-  pkg_client_ui_goal --> pkg_client_ui_conversation
-  pkg_client_ui_goal --> pkg_client_ui_primitives
-  pkg_client_ui_goal --> pkg_client_ui_slots
-  pkg_client_ui_goal --> pkg_goal
-  pkg_client_ui_goal --> pkg_invariants
-  pkg_client_ui_skill --> pkg_client_connection
-  pkg_client_ui_skill --> pkg_client_locale
-  pkg_client_ui_skill --> pkg_client_runtime
-  pkg_client_ui_skill --> pkg_client_ui_conversation
-  pkg_client_ui_skill --> pkg_client_ui_primitives
-  pkg_client_ui_skill --> pkg_client_ui_slash
-  pkg_client_ui_skill --> pkg_client_ui_slots
-  pkg_client_ui_skill --> pkg_invariants
-=======
-  pkg_client_runtime --> pkg_client_remotes
-=======
   pkg_client_runtime --> pkg_api_remotes
->>>>>>> c671d9e48c (refactor(api): colocate gateway and remote assembly)
   pkg_client_runtime --> pkg_invariants
   pkg_client_runtime --> pkg_type_meta
   pkg_client_runtime --> pkg_typert_registry
->>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compact
   pkg_session_reference --> pkg_invariants
@@ -1104,11 +1045,6 @@ flowchart TD
   pkg_client_ui_layout --> pkg_client_ui_slots
   pkg_client_ui_layout --> pkg_client_ui_theme
   pkg_client_ui_layout --> pkg_invariants
-  pkg_client_ui_skill --> pkg_client_connection
-  pkg_client_ui_skill --> pkg_client_runtime
-  pkg_client_ui_skill --> pkg_client_ui_slash
-  pkg_client_ui_skill --> pkg_client_ui_slots
-  pkg_client_ui_skill --> pkg_invariants
   pkg_acp_demo --> pkg_acp
   pkg_acp_demo --> pkg_agent_spine_demo
   pkg_acp_demo --> pkg_app_boot
@@ -1147,6 +1083,11 @@ flowchart TD
   pkg_client_ui_command --> pkg_client_ui_slash
   pkg_client_ui_command --> pkg_client_ui_slots
   pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_deliverables --> pkg_client_locale
+  pkg_client_ui_deliverables --> pkg_client_runtime
+  pkg_client_ui_deliverables --> pkg_client_ui_conversation
+  pkg_client_ui_deliverables --> pkg_client_ui_slots
+  pkg_client_ui_deliverables --> pkg_invariants
   pkg_client_ui_goal --> pkg_api_remotes
   pkg_client_ui_goal --> pkg_client_locale
   pkg_client_ui_goal --> pkg_client_runtime
@@ -1163,6 +1104,14 @@ flowchart TD
   pkg_client_ui_plan --> pkg_client_ui_slots
   pkg_client_ui_plan --> pkg_invariants
   pkg_client_ui_plan --> pkg_plan_mode
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_locale
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_conversation
+  pkg_client_ui_skill --> pkg_client_ui_primitives
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_invariants
   pkg_client_ui_subagent --> pkg_client_locale
   pkg_client_ui_subagent --> pkg_client_runtime
   pkg_client_ui_subagent --> pkg_client_ui_conversation
@@ -1262,10 +1211,6 @@ flowchart TD
 | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
-<<<<<<< HEAD
-| [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
-=======
->>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
@@ -1309,16 +1254,8 @@ flowchart TD
 | [`session-title-llm`](../packages/session-title/session-title-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`timeout`](../packages/util/timeout) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
 | [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/ui/user-approval) |
-<<<<<<< HEAD
-<<<<<<< HEAD
-| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
-| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-=======
-| [`client-remotes`](../packages/client/remotes) | `client` | [`goal`](../packages/goal/goal), [`host-api-gateway`](../packages/host/api-gateway), [`invariants`](../packages/support/invariants) |
->>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
-=======
 | [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`typert-registry`](../packages/typert/registry) |
->>>>>>> c671d9e48c (refactor(api): colocate gateway and remote assembly)
+| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -1344,18 +1281,7 @@ flowchart TD
 | [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`session-title-llm`](../packages/session-title/session-title-llm) |
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
-<<<<<<< HEAD
-<<<<<<< HEAD
-| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
-| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-=======
-| [`client-runtime`](../packages/client/runtime) | `client` | [`client-remotes`](../packages/client/remotes), [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
->>>>>>> d6e02ebbcc (feat(goal): add TypeRT gateway example)
-=======
 | [`client-runtime`](../packages/client/runtime) | `client` | [`api-remotes`](../packages/api/remotes), [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
->>>>>>> c671d9e48c (refactor(api): colocate gateway and remote assembly)
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
@@ -1400,14 +1326,15 @@ flowchart TD
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/sdk-client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
-| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`cli-demo`](../packages/examples/cli-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
 | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |

From ef8660076b05ed909065387e139592ffbf79329a Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 16:04:25 +0800
Subject: [PATCH 144/516] fix: docs budget

---
 scripts/doc-budgets.manifest.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json
index a6ad066add..b5c000a714 100644
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,5 +1,5 @@
 {
-  "AGENTS.md": 1775,
+  "AGENTS.md": 1782,
   "docs/AGENTS.md": 1320,
   "docs/architecture.md": 2160,
   "docs/cordis-primer.md": 600,
@@ -7,5 +7,5 @@
   "docs/testing.md": 1150,
   "examples/AGENTS.md": 310,
   "packages/AGENTS.md": 675,
-  "packages/README.md": 920
+  "packages/README.md": 936
 }

From d2596a0d74ed1729f687d2f2a224405be7f813a1 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 16:07:17 +0800
Subject: [PATCH 145/516] test(api-remotes): cover lookup publication races

---
 .../api/remotes/tests/agent-lookup.spec.ts    | 110 ++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 packages/api/remotes/tests/agent-lookup.spec.ts

diff --git a/packages/api/remotes/tests/agent-lookup.spec.ts b/packages/api/remotes/tests/agent-lookup.spec.ts
new file mode 100644
index 0000000000..c9110b8f3f
--- /dev/null
+++ b/packages/api/remotes/tests/agent-lookup.spec.ts
@@ -0,0 +1,110 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import { createApiRemoteAgentResolver } from '@deepseek-ai/dsh-api-remotes'
+
+const sid = (value: string): SessionId => value as SessionId
+
+function header(id: SessionId): SessionHeader {
+  return { version: 0, id, createdAt: 1, cwd: '/proj' }
+}
+
+async function createContext(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  return ctx
+}
+
+function provideSession(
+  ctx: Context,
+  meta: SessionHeader,
+  inspect: () => Promise<{ meta: SessionHeader; events: SessionEvent[] }>,
+): void {
+  ctx.provide('sessionPersistence', {
+    list: () => Promise.resolve([meta]),
+    inspect,
+    locate: () => undefined,
+  } as never)
+}
+
+function stubAgent(ctx: Context, session: Session): Agent {
+  return { id: session.id, session, status: 'idle', ctx } as Agent
+}
+
+describe('API Remote Agent resolver races', () => {
+  it('maps an inspected session without a cwd to session-not-found', async () => {
+    const ctx = await createContext()
+    const sessionId = sid('missing-after-inspect')
+    const meta = header(sessionId)
+    provideSession(ctx, meta, () => Promise.resolve({
+      meta: { ...meta, cwd: undefined } as unknown as SessionHeader,
+      events: [],
+    }))
+
+    const result = await createApiRemoteAgentResolver(ctx, {})(sessionId)
+
+    expect(result).toMatchObject({ error: { code: 'session-not-found', details: { sessionId } } })
+    await ctx.fiber.dispose()
+  })
+
+  it('resumes through a concurrently attached ordinary Session without optional defaults', async () => {
+    const ctx = await createContext()
+    const sessionId = sid('ordinary-attach-race')
+    const meta = header(sessionId)
+    let published: Session | undefined
+    provideSession(ctx, meta, () => {
+      published = ctx.sessions.create(sessionId, { meta: { cwd: '/proj' } })
+      return Promise.resolve({ meta, events: [] })
+    })
+    const resume = vi.spyOn(ctx.agents, 'resume').mockImplementation(async () => {
+      if (published === undefined) throw new Error('Session was not published')
+      return { agent: stubAgent(ctx, published), dispose: () => Promise.resolve() }
+    })
+
+    const result = await createApiRemoteAgentResolver(ctx, {})(sessionId)
+
+    expect(result).toMatchObject({ agent: { id: sessionId } })
+    expect(resume).toHaveBeenCalledWith({ resumeSessionId: sessionId })
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects a subagent Session published after durable inspection', async () => {
+    const ctx = await createContext()
+    const sessionId = sid('owned-attach-race')
+    const meta = header(sessionId)
+    provideSession(ctx, meta, () => {
+      ctx.sessions.create(sessionId, { meta: { cwd: '/proj', origin: 'subagent' } })
+      return Promise.resolve({ meta, events: [] })
+    })
+    const resume = vi.spyOn(ctx.agents, 'resume')
+
+    const result = await createApiRemoteAgentResolver(ctx, {})(sessionId)
+
+    expect(result).toMatchObject({ error: { code: 'agent-busy' } })
+    expect(resume).not.toHaveBeenCalled()
+    await ctx.fiber.dispose()
+  })
+
+  it('reclassifies failed resumes after a live or attached subagent wins publication', async () => {
+    for (const winner of ['agent', 'session'] as const) {
+      const ctx = await createContext()
+      const sessionId = sid(`owned-${winner}-resume-race`)
+      const meta = header(sessionId)
+      provideSession(ctx, meta, () => Promise.resolve({ meta, events: [] }))
+      vi.spyOn(ctx.agents, 'resume').mockImplementationOnce(async () => {
+        const session = ctx.sessions.create(sessionId, { meta: { cwd: '/proj', origin: 'subagent' } })
+        if (winner === 'agent') ctx.agents.register(stubAgent(ctx, session))
+        throw new Error('session id already published')
+      })
+
+      const result = await createApiRemoteAgentResolver(ctx, {})(sessionId)
+
+      expect(result).toMatchObject({ error: { code: 'agent-busy' } })
+      await ctx.fiber.dispose()
+    }
+  })
+})

From d49028ff5daf083dab533fde27b039842d6da879 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 16:14:27 +0800
Subject: [PATCH 146/516] fix: docs

---
 docs/event-producer-consumer.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 92bf908613..9d486c46f6 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -30,10 +30,10 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
-| `session/created` | `emit` | [`packages/core/session/src/index.ts:73`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
-| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:95`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
-| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:104`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:188`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |

From e89d078819de825aa0fa1f40983daed1b76275e4 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 16:25:00 +0800
Subject: [PATCH 147/516] fix: test snapshot

---
 .../translation-prompt-v4/request-response.expected.json      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index e796de8a8a..794cf18f49 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository typecheck runs the whole-repo `tsc -b` graph: it emits every package/vendor `lib/types` and checks examples, tests, and scripts through two no-emit aggregates.\n\nThe repository's TypeScript configuration has exactly three roles; every tsconfig file plays one of them.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, references to the two aggregates. The whole-repo `tsc -b tsconfig.json` graph, the tsserver discovery entry, and — through the inherited `paths` — the resolution config for tsx running `examples/` and `scripts/` (their nearest tsconfig is this file). | No |\n| `tsconfig.host.json` | Host aggregate: host-side packages (via references), examples, tests, scripts, website. Excludes `packages/client`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the client aggregate and every `packages/client/*` package. | No |\n\nHost and client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Two disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges. Program-backed generators and gates (`scripts/ts-project.ts` consumers, doc-typecheck standalone mode) are host-only by decision; the client side gains program-backed tooling only with a concrete need.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteContext`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `client-remotes` composition loads those contributions and mounts concrete methods on `ctx.api` or the corresponding scoped Context. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository typecheck runs the whole-repo `tsc -b` graph: it emits every package/vendor `lib/types` and checks examples, tests, and scripts through two no-emit aggregates.\n\nThe repository's TypeScript configuration has exactly three roles; every tsconfig file plays one of them.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, references to the two aggregates. The whole-repo `tsc -b tsconfig.json` graph, the tsserver discovery entry, and — through the inherited `paths` — the resolution config for tsx running `examples/` and `scripts/` (their nearest tsconfig is this file). | No |\n| `tsconfig.host.json` | Host aggregate: host-side packages (via references), examples, tests, scripts, website. Excludes `packages/client`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the client aggregate and every `packages/client/*` package. | No |\n\nHost and client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Two disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges. Program-backed generators and gates (`scripts/ts-project.ts` consumers, doc-typecheck standalone mode) are host-only by decision; the client side gains program-backed tooling only with a concrete need.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteContext`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions and mounts concrete methods on `ctx.api` or the corresponding scoped Context. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库类型检查会执行全仓 `tsc -b` 图：它会发射每个 package/vendor 的 `lib/types`，并通过两个 no-emit 聚合检查示例、测试和脚本。\n\n仓库的 TypeScript 配置只有三种角色；每个 tsconfig 文件恰好扮演其中一种。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个聚合。全仓 `tsc -b tsconfig.json` 图、tsserver 发现入口，并经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置（它们最近的 tsconfig 就是此文件）。 | 否 |\n| `tsconfig.host.json` | host 聚合：host 侧各包（经 references）、示例、测试、脚本、website。排除 `packages/client`。 | 是 |\n| `tsconfig.client.json` | client 聚合：`packages/client/*` 各包及其测试、`apps/web`。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 client 聚合和每个 `packages/client/*` 包 extends。 | 否 |\n\nhost 与 client 保持两个聚合 program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个聚合，一个 paths 门面也可以横跨两侧。由此推出两条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个聚合展平进一个 program 会撞上 `Context` 合并冲突。基于 program 的生成器与门禁（`scripts/ts-project.ts` 的消费者、doc-typecheck standalone 模式）按决策仅覆盖 host 侧；client 侧只在出现真实需求时再获得基于 program 的工具。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteContext` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `client-remotes` 组合加载这些贡献并将具体方法挂载到 `ctx.api` 或对应的作用域 Context。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库类型检查会执行全仓 `tsc -b` 图：它会发射每个 package/vendor 的 `lib/types`，并通过两个 no-emit 聚合检查示例、测试和脚本。\n\n仓库的 TypeScript 配置只有三种角色；每个 tsconfig 文件恰好扮演其中一种。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个聚合。全仓 `tsc -b tsconfig.json` 图、tsserver 发现入口，并经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置（它们最近的 tsconfig 就是此文件）。 | 否 |\n| `tsconfig.host.json` | host 聚合：host 侧各包（经 references）、示例、测试、脚本、website。排除 `packages/client`。 | 是 |\n| `tsconfig.client.json` | client 聚合：`packages/client/*` 各包及其测试、`apps/web`。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 client 聚合和每个 `packages/client/*` 包 extends。 | 否 |\n\nhost 与 client 保持两个聚合 program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个聚合，一个 paths 门面也可以横跨两侧。由此推出两条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个聚合展平进一个 program 会撞上 `Context` 合并冲突。基于 program 的生成器与门禁（`scripts/ts-project.ts` 的消费者、doc-typecheck standalone 模式）按决策仅覆盖 host 侧；client 侧只在出现真实需求时再获得基于 program 的工具。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteContext` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并将具体方法挂载到 `ctx.api` 或对应的作用域 Context。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",

From 686ee5b3f6824b4bcdda4e334d59bf55ea0aec3d Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 16:53:04 +0800
Subject: [PATCH 148/516] fix(api-gateway): harden remote lifecycle and
 recovery

---
 ...08-02-typert-remote-method-calls.i18n.yaml |  4 +-
 .../2026-08-02-typert-remote-method-calls.md  |  2 +-
 ...026-08-02-typert-remote-method-calls.zh.md |  2 +-
 packages/api/gateway/src/client/index.ts      | 20 ++++----
 packages/api/gateway/src/index.ts             |  9 ++--
 packages/api/gateway/tests/client.spec.ts     | 14 ++++++
 packages/api/gateway/tests/gateway.spec.ts    | 16 +++++++
 packages/api/remotes/src/agent-lookup.ts      |  1 +
 .../api/remotes/tests/agent-lookup.spec.ts    | 44 +++++++++++++++++
 packages/client/ui-goal/src/client/index.ts   | 14 +++---
 .../ui-goal/tests/browser-plugin.spec.tsx     | 15 +++++-
 packages/typert/registry/README.i18n.yaml     |  4 +-
 packages/typert/registry/README.md            |  1 +
 packages/typert/registry/README.zh.md         |  1 +
 packages/typert/registry/src/service.ts       | 48 ++++++++++++++++++-
 packages/typert/registry/tests/typert.spec.ts | 30 ++++++++++++
 packages/typert/type-meta/README.i18n.yaml    |  4 +-
 packages/typert/type-meta/README.md           |  2 +-
 packages/typert/type-meta/README.zh.md        |  2 +-
 packages/typert/type-meta/src/index.ts        |  1 +
 packages/typert/type-meta/src/types.ts        | 18 ++++++-
 21 files changed, 218 insertions(+), 34 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 9ba0cf8dc1..1e4aeaabd7 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: c4f3a5b94bf25b4581b9430cfcb4f02f707e0749
-2026-08-02-typert-remote-method-calls.zh.md: e11d8ebe42d44cc9805e942a31f13f7ae847815a
+2026-08-02-typert-remote-method-calls.md: 3d5a79fd4a26f7d232dcc7635625899e2eb9df6b
+2026-08-02-typert-remote-method-calls.zh.md: 3d6ec680ba97a532f18219670e8dba799a94ed7b
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index c4f3a5b94b..3d5a79fd4a 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -164,7 +164,7 @@ Every registration returns a disposer owned by the caller's Cordis fiber. Client
 
 The lookup registry retains the stable wire declaration after its live resolver unloads. SRC parsing continues to classify the parameter as a lookup, while invocation fails with `lookup-unavailable`; it never reclassifies the incoming ID as an ordinary JSON business object. Re-registering the same key with different parameter, wire, or canonical type symbols fails for the lifetime of that TypeRT Service.
 
-Business-object packages own stable declarations and default resolvers through `register()`; Host composition supplies an effect-scoped asynchronous policy for the same key through `configure()`. Configuration may precede provider registration, but does not by itself make a lookup available without a live provider; unloading the configuration restores the provider's default resolver. API Remotes creates the shared `agentFor()` resolver for `agent` and `session`: live Agents are reused, ordinary cold sessions are resumed automatically, concurrent resumes are deduplicated by Session ID, and the subagent ownership fence returns the existing `agent-busy`. The standard Web API Proxy supplies its Agent defaults and scope setup and consumes that resolver for legacy methods. The `session` resolver returns the resolved Agent's Session, so the two parameter kinds do not create separate resume lifecycles.
+Business-object and scoped-Context packages own stable declarations and default resolvers through `lookups.register()` and `contexts.registerHost()`; Host composition supplies effect-scoped asynchronous policies through `lookups.configure()` and `contexts.configureHost()`. Configuration may precede provider registration, but does not by itself make an identity available without a live provider; unloading the configuration restores the provider's default resolver. API Remotes creates the shared `agentFor()` resolver for `agent` and `session` lookups and the `agent` Host Context: live Agents are reused, ordinary cold sessions are resumed automatically, concurrent resumes are deduplicated by Session ID, and the subagent ownership fence returns the existing `agent-busy`. The standard Web API Proxy supplies its Agent defaults and scope setup and consumes that resolver for legacy methods. The `session` lookup returns the resolved Agent's Session, while the `agent` Host Context returns its Context, so all three projections share one resume lifecycle.
 
 The registry's Host root entry has the complete `TypeRTService` interface merge. The registry implementation shared by Host and Client lives in a separate module without environment declarations. The registry's `/client` entry imports only that shared implementation and does not pass through the Host root entry, so it cannot bring Host Cordis declarations into the Client Program.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index e11d8ebe42..3d6ec680ba 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -164,7 +164,7 @@ ctx.typert.contexts  Host Context resolver 与 Client Context binder
 
 lookup 注册表会在活 resolver 卸载后保留稳定的 wire 声明。SRC 解析仍会把该参数归类为 lookup，而调用会以 `lookup-unavailable` 失败；系统绝不会把传入的 ID 重新归类为普通 JSON 业务对象。在同一个 TypeRT Service 的生命周期内，以不同参数、wire 或规范类型 symbol 重新注册同一 key 会直接失败。
 
-业务对象包通过 `register()` 拥有稳定声明和默认 resolver；Host 组合通过 `configure()` 为同一个 key 提供 effect-scoped 异步策略。配置可以先于 provider 注册，但没有活 provider 时不会单独形成可用 lookup；配置卸载后恢复 provider 默认 resolver。API Remotes 为 `agent` 和 `session` 创建共享的 `agentFor()` resolver：live Agent 直接复用，普通冷会话自动恢复，并发恢复按 Session ID 去重，subagent ownership fence 则返回既有 `agent-busy`。标准 Web API Proxy 提供 Agent 默认值和 scope 设置，并让旧方法使用该 resolver。`session` resolver 返回解析所得 Agent 的 Session，因而两种参数不会产生两套恢复生命周期。
+业务对象包和 scoped Context 包通过 `lookups.register()` 与 `contexts.registerHost()` 拥有稳定声明和默认 resolver；Host 组合通过 `lookups.configure()` 与 `contexts.configureHost()` 提供 effect-scoped 异步策略。配置可以先于 provider 注册，但没有活 provider 时不会单独形成可用身份；配置卸载后恢复 provider 默认 resolver。API Remotes 为 `agent`、`session` lookup 和 `agent` Host Context 创建共享的 `agentFor()` resolver：live Agent 直接复用，普通冷会话自动恢复，并发恢复按 Session ID 去重，subagent ownership fence 则返回既有 `agent-busy`。标准 Web API Proxy 提供 Agent 默认值和 scope 设置，并让旧方法使用该 resolver。`session` lookup 返回解析所得 Agent 的 Session，`agent` Host Context 返回其 Context，因此三种投影共用一个恢复生命周期。
 
 Registry 的 Host 根入口拥有完整 `TypeRTService` interface merge；Host 与 Client 共用的 registry 实现位于无环境声明的独立模块。Registry `/client` 入口只引用该共享实现，不经过 Host 根入口，因此不会把 Host Cordis 声明带入 Client Program。
 
diff --git a/packages/api/gateway/src/client/index.ts b/packages/api/gateway/src/client/index.ts
index bafffa80f7..ddef36e288 100644
--- a/packages/api/gateway/src/client/index.ts
+++ b/packages/api/gateway/src/client/index.ts
@@ -134,7 +134,8 @@ class ClientApiService extends Service implements TypeRTClientApi {
         for (const method of methods) record.service.assertMethodAvailable(method)
       } else {
         for (const method of methods) ScopedRemoteNamespace.assertMethodAvailable(namespace, method)
-        if (this.ownerCtx.reflect.props[namespace] !== undefined) {
+        const property = this.ownerCtx.reflect.props[namespace]
+        if (property?.type === 'accessor' || this.ownerCtx.get(namespace) !== undefined) {
           throw new Error(`client api: scoped namespace ${JSON.stringify(namespace)} conflicts with an existing Context property`)
         }
       }
@@ -224,6 +225,7 @@ class ClientApiService extends Service implements TypeRTClientApi {
       if (namespace.tokens.get(descriptor.method) !== token) return
       namespace.service.remove(descriptor.method)
       namespace.tokens.delete(descriptor.method)
+      if (namespace.tokens.size === 0) this.scoped.delete(descriptor.namespace)
     }
   }
 
@@ -289,7 +291,7 @@ class ScopedRemoteNamespace {
   private readonly ctx: Context
   private readonly ownerCtx: Context
   private readonly methods = new Set<string>()
-  private provided = false
+  private disposeService: (() => void) | undefined
   readonly name: string
 
   static assertMethodAvailable(namespace: string, method: string): void {
@@ -331,12 +333,7 @@ class ScopedRemoteNamespace {
         },
       })
       if (activate) {
-        if (this.provided) {
-          this.ownerCtx.set(this.name, this)
-        } else {
-          this.ownerCtx.reflect.provide(this.name, this)
-          this.provided = true
-        }
+        this.disposeService = this.ownerCtx.reflect.provide(this.name, this)
       }
     } catch (error) {
       Reflect.deleteProperty(this, method)
@@ -348,11 +345,14 @@ class ScopedRemoteNamespace {
   remove(method: string): void {
     Reflect.deleteProperty(this, method)
     this.methods.delete(method)
-    if (this.methods.size === 0) this.ownerCtx.set(this.name, undefined)
+    if (this.methods.size !== 0) return
+    const disposeService = this.disposeService
+    this.disposeService = undefined
+    disposeService?.()
   }
 }
 
-const SCOPED_NAMESPACE_FIELDS = new Set(['ctx', 'invokeRemote', 'methods', 'name', 'ownerCtx', 'provided'])
+const SCOPED_NAMESPACE_FIELDS = new Set(['ctx', 'disposeService', 'invokeRemote', 'methods', 'name', 'ownerCtx'])
 
 function endpointOf(descriptor: Pick<InvocationDescriptor, 'namespace' | 'method'>): string {
   return `${descriptor.namespace}/${descriptor.method}`
diff --git a/packages/api/gateway/src/index.ts b/packages/api/gateway/src/index.ts
index 13cf460f4d..5899f5d560 100644
--- a/packages/api/gateway/src/index.ts
+++ b/packages/api/gateway/src/index.ts
@@ -134,7 +134,7 @@ export class TypertGatewayService extends Service implements TypertGateway {
     const endpoint = endpointOf(request.namespace, request.method)
     const descriptor = this.resolveDescriptor(request.namespace, request.method, endpoint)
     assertExactArguments(request.args, descriptor, endpoint)
-    const receiverContext = this.resolveReceiverContext(descriptor, request.args, endpoint)
+    const receiverContext = await this.resolveReceiverContext(descriptor, request.args, endpoint)
     const receiver = receiverContext.get(descriptor.service) as unknown
     if (!isObject(receiver)) {
       throw new TypertGatewayError(
@@ -331,11 +331,11 @@ export class TypertGatewayService extends Service implements TypertGateway {
     }
   }
 
-  private resolveReceiverContext(
+  private async resolveReceiverContext(
     descriptor: InvocationDescriptor,
     args: Readonly<Record<string, unknown>>,
     endpoint: string,
-  ): Context {
+  ): Promise<Context> {
     if (descriptor.invocation.kind === 'direct') return this.ctx
     const invocation = descriptor.invocation
     const provider = this.ctx.typert.contexts.getHost(invocation.context)
@@ -358,8 +358,9 @@ export class TypertGatewayService extends Service implements TypertGateway {
     const identity = decode(invocation.codec, args[invocation.wire], 'input-invalid', endpoint, invocation.wire)
     let context: Context | undefined
     try {
-      context = provider.resolve(identity)
+      context = await provider.resolve(identity)
     } catch (cause) {
+      if (cause instanceof TypeRTLookupFailure) throw cause
       throw new TypertGatewayError(
         'context-failed',
         endpoint,
diff --git a/packages/api/gateway/tests/client.spec.ts b/packages/api/gateway/tests/client.spec.ts
index 2fbcbb9280..feae3056c9 100644
--- a/packages/api/gateway/tests/client.spec.ts
+++ b/packages/api/gateway/tests/client.spec.ts
@@ -526,6 +526,20 @@ describe('Client TypeRT API', () => {
     await retry()
   })
 
+  it('unregisters an empty scoped namespace so another provider can claim its name', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const dispose = ctx.api.mount({ package: '@fixture/scoped', descriptors: [contextDescriptor()] })
+    expect(ctx.get('goals')).toBeDefined()
+
+    await dispose()
+
+    expect(ctx.get('goals')).toBeUndefined()
+    const replacement = { owner: 'replacement' }
+    const disposeReplacement = ctx.reflect.provide('goals', replacement)
+    expect(ctx.get('goals')).toBe(replacement)
+    await disposeReplacement()
+  })
+
   it('throws RPC failures with the structured error as its cause', async () => {
     const rpcError = { code: 'internal' as const, message: 'host failed', details: {} }
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>().mockResolvedValue({ ok: false, error: rpcError }))
diff --git a/packages/api/gateway/tests/gateway.spec.ts b/packages/api/gateway/tests/gateway.spec.ts
index d784a1ac2f..d298116b82 100644
--- a/packages/api/gateway/tests/gateway.spec.ts
+++ b/packages/api/gateway/tests/gateway.spec.ts
@@ -538,6 +538,22 @@ describe('TypertGatewayService', () => {
     expect(error.cause).toEqual(new Error('provider failed'))
   })
 
+  it('preserves a Host Context policy rejection for the active RPC adapter', async () => {
+    const { ctx } = await setup()
+    const rejection = new TypeRTLookupFailure({ code: 'agent-busy', message: 'owned', details: { reason: 'subagent' } })
+    ctx.typert.contexts.registerHost('gatewayFixture', {
+      ...contextProvider(ctx.extend()),
+      resolve: async () => { throw rejection },
+    })
+    registerStrict(ctx, [renameDescriptor()])
+
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    })).rejects.toBe(rejection)
+  })
+
   it('reports Context provider metadata mismatch and unresolved identities', async () => {
     const { ctx } = await setup()
     registerStrict(ctx, [renameDescriptor()])
diff --git a/packages/api/remotes/src/agent-lookup.ts b/packages/api/remotes/src/agent-lookup.ts
index e3a5b27df8..eb54ea9b0b 100644
--- a/packages/api/remotes/src/agent-lookup.ts
+++ b/packages/api/remotes/src/agent-lookup.ts
@@ -187,6 +187,7 @@ export function createApiRemoteAgentResolver(
     }
     typeCtx.typert.lookups.configure('agent', resolveAgent)
     typeCtx.typert.lookups.configure('session', async sessionId => (await resolveAgent(sessionId)).session)
+    typeCtx.typert.contexts.configureHost('agent', async sessionId => (await resolveAgent(sessionId)).ctx)
   })
 
   return agentFor
diff --git a/packages/api/remotes/tests/agent-lookup.spec.ts b/packages/api/remotes/tests/agent-lookup.spec.ts
index c9110b8f3f..7179f5b2b2 100644
--- a/packages/api/remotes/tests/agent-lookup.spec.ts
+++ b/packages/api/remotes/tests/agent-lookup.spec.ts
@@ -5,6 +5,8 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import { createApiRemoteAgentResolver } from '@deepseek-ai/dsh-api-remotes'
+import { TypeRTLookupFailure } from '@deepseek-ai/dsh-type-meta'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 
 const sid = (value: string): SessionId => value as SessionId
 
@@ -14,6 +16,7 @@ function header(id: SessionId): SessionHeader {
 
 async function createContext(): Promise<Context> {
   const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
   await ctx.plugin(SessionStore)
   await ctx.plugin(AgentRegistry)
   return ctx
@@ -107,4 +110,45 @@ describe('API Remote Agent resolver races', () => {
       await ctx.fiber.dispose()
     }
   })
+
+  it('uses the shared cold-resume policy for the Agent Host Context', async () => {
+    const ctx = await createContext()
+    const sessionId = sid('context-cold-resume')
+    const meta = header(sessionId)
+    let published: Session | undefined
+    provideSession(ctx, meta, () => {
+      published = ctx.sessions.create(sessionId, { meta: { cwd: '/proj' } })
+      return Promise.resolve({ meta, events: [] })
+    })
+    const agentCtx = ctx.extend()
+    vi.spyOn(ctx.agents, 'resume').mockImplementation(async () => {
+      if (published === undefined) throw new Error('Session was not published')
+      return { agent: stubAgent(agentCtx, published), dispose: () => Promise.resolve() }
+    })
+    const defaultProvider = ctx.typert.contexts.getHost('agent')
+    createApiRemoteAgentResolver(ctx, {})
+    await vi.waitFor(() => { expect(ctx.typert.contexts.getHost('agent')).not.toBe(defaultProvider) })
+    const provider = ctx.typert.contexts.getHost('agent')
+    if (provider === undefined) throw new Error('Agent Host Context provider was not mounted')
+
+    await expect(provider.resolve(sessionId)).resolves.toBe(agentCtx)
+    await ctx.fiber.dispose()
+  })
+
+  it('applies the subagent ownership fence to the Agent Host Context', async () => {
+    const ctx = await createContext()
+    const sessionId = sid('context-owned-subagent')
+    const session = ctx.sessions.create(sessionId, { meta: { cwd: '/proj', origin: 'subagent' } })
+    ctx.agents.register(stubAgent(ctx.extend(), session))
+    const defaultProvider = ctx.typert.contexts.getHost('agent')
+    createApiRemoteAgentResolver(ctx, {})
+    await vi.waitFor(() => { expect(ctx.typert.contexts.getHost('agent')).not.toBe(defaultProvider) })
+    const provider = ctx.typert.contexts.getHost('agent')
+    if (provider === undefined) throw new Error('Agent Host Context provider was not mounted')
+
+    const resolution = provider.resolve(sessionId)
+    await expect(resolution).rejects.toBeInstanceOf(TypeRTLookupFailure)
+    await expect(resolution).rejects.toMatchObject({ failure: { code: 'agent-busy' } })
+    await ctx.fiber.dispose()
+  })
 })
diff --git a/packages/client/ui-goal/src/client/index.ts b/packages/client/ui-goal/src/client/index.ts
index 2e49d5b6b8..bea4f67df2 100644
--- a/packages/client/ui-goal/src/client/index.ts
+++ b/packages/client/ui-goal/src/client/index.ts
@@ -38,10 +38,10 @@ const NS = 'goal'
 /** Required services: slots for the dock entry, sessions for the projected ref, API for Remote mutations, locale for the copy. */
 export const inject = ['slots', 'sessions', 'api', 'locale']
 
-/** Map one generated Remote call onto the strip's inline-render shape. */
-async function settle(result: Promise<unknown>): Promise<GoalActionResult> {
+/** Map one generated Remote call, including synchronous namespace lookup failures, onto the strip's inline-render shape. */
+async function settle(invoke: () => Promise<unknown>): Promise<GoalActionResult> {
   try {
-    await result
+    await invoke()
     return { ok: true }
   } catch (error) {
     const cause = error instanceof Error ? error.cause : undefined
@@ -94,22 +94,22 @@ export function apply(ctx: ClientContext): void {
       onEdit: async (objective) => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(ctx.api.goals.edit(sessionId, ref, { objective }))
+        return settle(() => ctx.api.goals.edit(sessionId, ref, { objective }))
       },
       onPause: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(ctx.api.goals.pause(sessionId, ref))
+        return settle(() => ctx.api.goals.pause(sessionId, ref))
       },
       onResume: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(ctx.api.goals.resume(sessionId, ref))
+        return settle(() => ctx.api.goals.resume(sessionId, ref))
       },
       onClear: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(ctx.api.goals.clear(sessionId, ref))
+        return settle(() => ctx.api.goals.clear(sessionId, ref))
       },
     }),
   }, GoalDock))
diff --git a/packages/client/ui-goal/tests/browser-plugin.spec.tsx b/packages/client/ui-goal/tests/browser-plugin.spec.tsx
index 11c95e27d9..f900682712 100644
--- a/packages/client/ui-goal/tests/browser-plugin.spec.tsx
+++ b/packages/client/ui-goal/tests/browser-plugin.spec.tsx
@@ -70,7 +70,7 @@ async function bench(options: {
     resume: answer(`${prefix}/resume`, { ref }),
     clear: answer(`${prefix}/clear`, ref),
   })
-  let activeGoals = goals('goals')
+  let activeGoals: ReturnType<typeof goals> | undefined = goals('goals')
   ctx.provide('api', {
     get goals() { return activeGoals },
   })
@@ -95,6 +95,7 @@ async function bench(options: {
     fiber,
     calls,
     remountGoals: () => { activeGoals = goals('remounted-goals') },
+    unmountGoals: () => { activeGoals = undefined },
     entry: () => {
       const entry = ctx.slots.entries('conversation.input.dock')[0]
       if (entry === undefined) return undefined
@@ -141,6 +142,18 @@ describe('ui-goal browser plugin', () => {
     expect(b.calls).toMatchObject([{ method: 'remounted-goals/pause' }])
   })
 
+  it('settles every verb when the Remote namespace is temporarily absent', async () => {
+    const b = await bench({ projection: makeProjection() })
+    await b.fiber.await()
+    const verbs = b.entry()!.inject!(sid('s1'))
+    b.unmountGoals()
+
+    for (const result of [await verbs.onEdit('x'), await verbs.onPause(), await verbs.onResume(), await verbs.onClear()]) {
+      expect(result).toMatchObject({ ok: false, error: { code: 'internal' } })
+    }
+    expect(b.calls).toHaveLength(0)
+  })
+
   it('a null or absent projection short-circuits every verb without touching the wire', async () => {
     for (const projection of [null, undefined]) {
       const b = await bench({ projection })
diff --git a/packages/typert/registry/README.i18n.yaml b/packages/typert/registry/README.i18n.yaml
index a6180c6bfc..011834c52d 100644
--- a/packages/typert/registry/README.i18n.yaml
+++ b/packages/typert/registry/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/typert/registry/README.md
-README.md: dae8c3ed124fd6e2d61eb47964e2c07dda762b48
-README.zh.md: aea74b3753feccd88ee132363dc60ade02161498
+README.md: fa227b1c8faf1abd5a6492d4b8fe7d0c51ceeef1
+README.zh.md: 343e43aaca6ddaa0bb5e8d3130c85f37e4b4cb93
diff --git a/packages/typert/registry/README.md b/packages/typert/registry/README.md
index dae8c3ed12..fa227b1c8f 100644
--- a/packages/typert/registry/README.md
+++ b/packages/typert/registry/README.md
@@ -10,6 +10,7 @@ Package reflection is keyed by `<package>#<face>`. Schemas are keyed by `<packag
 
 - `TypertRegistry` is the default plugin and provides `ctx.typert`.
 - `ctx.typert.lookups.register()` registers the wire declaration and default resolver owned by the business package; `configure()` registers a resolver owned by Host composition that may run asynchronously. Their lifetimes are independent: configuration may precede the provider, and unloading the configuration restores the default policy.
+- `ctx.typert.contexts.registerHost()` and `configureHost()` apply the same ownership split to scoped Context identity; `registerClient()` supplies the corresponding Client Context binder.
 - `register(contribution)` rejects malformed identities and duplicate package-face or schema keys before committing anything, then returns the exact Cordis effect disposer.
 - `get(key)`, `resolve(key)`, and `list(filter?)` query live schemas. `resolve()` distinguishes a malformed key, an absent package, and a package that contributes no schema under that name.
 - `getPackage(packageName, face?)` and `listPackages(filter?)` query generated service, event, and object reflection; the default face is `host`.
diff --git a/packages/typert/registry/README.zh.md b/packages/typert/registry/README.zh.md
index aea74b3753..343e43aaca 100644
--- a/packages/typert/registry/README.zh.md
+++ b/packages/typert/registry/README.zh.md
@@ -10,6 +10,7 @@
 
 - `TypertRegistry` 是默认插件，并提供 `ctx.typert`。
 - `ctx.typert.lookups.register()` 注册业务包拥有的 wire 声明和默认 resolver；`configure()` 注册 Host 组合拥有、可异步执行的 resolver。两者生命周期独立，配置可以先于 provider，卸载配置会恢复默认策略。
+- `ctx.typert.contexts.registerHost()` 和 `configureHost()` 将同一所有权拆分应用于 scoped Context 身份；`registerClient()` 提供对应的 Client Context binder。
 - `register(contribution)` 会在提交任何内容之前拒绝格式错误的标识，以及重复的包与 face 组合键或 schema 键，随后返回 Cordis effect 提供的同一资源释放函数。
 - `get(key)`、`resolve(key)` 和 `list(filter?)` 查询当前有效的 schema。`resolve()` 能区分格式错误的键、未注册的包，以及已注册但未以该名称提供 schema 的包。
 - `getPackage(packageName, face?)` 和 `listPackages(filter?)` 查询生成的服务、事件和对象反射信息；默认 face 为 `host`。
diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
index 9011acc0a1..353ad4c9e0 100644
--- a/packages/typert/registry/src/service.ts
+++ b/packages/typert/registry/src/service.ts
@@ -15,6 +15,7 @@ import type {
   TypeRTContextWire,
   TypeRTDisposer,
   TypeRTHostContextProvider,
+  TypeRTHostContextResolver,
   TypeRTLocalRegistry,
   TypeRTLookupHost,
   TypeRTLookupDefinition,
@@ -334,6 +335,7 @@ function lookupDefinitionEquals(left: TypeRTLookupDefinition, right: TypeRTLooku
 
 class ContextStore {
   private readonly hosts = new Map<string, ProviderEntry<TypeRTHostContextProvider>>()
+  private readonly hostResolvers = new Map<string, ProviderEntry<HostContextResolverEntry>>()
   private readonly clients = new Map<string, ProviderEntry<TypeRTClientContextBinder>>()
   private readonly changes: ChangeSource
 
@@ -347,16 +349,56 @@ class ContextStore {
         key: K,
         provider: TypeRTHostContextProvider<TypeRTContextWire<TypeRTContextMap[K]>>,
       ) => this.registerHost(ctx, key, provider),
+      configureHost: <K extends Extract<keyof TypeRTContextMap, string>>(
+        key: K,
+        resolver: TypeRTHostContextResolver<TypeRTContextWire<TypeRTContextMap[K]>>,
+      ) => this.configureHost(ctx, key, resolver),
       registerClient: <K extends Extract<keyof TypeRTContextMap, string>>(
         key: K,
         binder: TypeRTClientContextBinder<TypeRTContextWire<TypeRTContextMap[K]>>,
       ) => this.registerClient(ctx, key, binder),
-      getHost: key => this.hosts.get(key)?.provider,
+      getHost: key => this.getHost(key),
       getClient: key => this.clients.get(key)?.provider,
       subscribe: listener => this.changes.subscribe(ctx, listener),
     }
   }
 
+  private getHost(key: string): TypeRTHostContextProvider | undefined {
+    const provider = this.hosts.get(key)?.provider
+    if (provider === undefined) return undefined
+    const resolver = this.hostResolvers.get(key)?.provider
+    if (resolver === undefined) return provider
+    return {
+      wire: provider.wire,
+      wireTypeSymbol: provider.wireTypeSymbol,
+      resolve: id => resolver.resolve(id),
+    }
+  }
+
+  private configureHost<Wire>(
+    ctx: Context,
+    key: string,
+    resolver: TypeRTHostContextResolver<Wire>,
+  ): TypeRTDisposer {
+    validateSegment('Context key', key)
+    if (this.hostResolvers.has(key)) throw new Error(`typert: host-context "${key}" resolver is already configured`)
+    const entry: ProviderEntry<HostContextResolverEntry> = {
+      provider: { resolve: async id => resolver(id as Wire) },
+      owner: {},
+    }
+    const { hostResolvers, changes } = this
+    return ctx.effect(function* () {
+      hostResolvers.set(key, entry)
+      changes.emit({ kind: 'host-context', key })
+      yield () => {
+        /* v8 ignore next -- duplicate configuration is rejected, so this effect remains the key's unique owner. */
+        if (hostResolvers.get(key) !== entry) return
+        hostResolvers.delete(key)
+        changes.emit({ kind: 'host-context', key })
+      }
+    }, `typert.contexts.configureHost(${JSON.stringify(key)})`)
+  }
+
   private registerHost<Wire>(ctx: Context, key: string, provider: TypeRTHostContextProvider<Wire>): TypeRTDisposer {
     validateSegment('Context key', key)
     validateWireName('Context wire field', provider.wire)
@@ -392,6 +434,10 @@ class ContextStore {
   }
 }
 
+interface HostContextResolverEntry {
+  resolve(id: unknown): Promise<Context | undefined>
+}
+
 /**
  * Registry of generated schemas, package reflection, invocations, and Remote
  * dependency providers.
diff --git a/packages/typert/registry/tests/typert.spec.ts b/packages/typert/registry/tests/typert.spec.ts
index 087cf00fc4..92b81803c7 100644
--- a/packages/typert/registry/tests/typert.spec.ts
+++ b/packages/typert/registry/tests/typert.spec.ts
@@ -389,6 +389,36 @@ describe('TypertRegistry', () => {
     await disposeReloadedProvider()
   })
 
+  it('configures an asynchronous Host Context resolver independently of provider load order', async () => {
+    const ctx = await makeCtx()
+    const fallback = ctx.extend()
+    const configured = ctx.extend()
+    const disposeResolver = ctx.typert.contexts.configureHost('registryFixture', async id =>
+      id === 'configured' ? configured : undefined)
+
+    expect(ctx.typert.contexts.getHost('registryFixture')).toBeUndefined()
+    const disposeProvider = ctx.typert.contexts.registerHost('registryFixture', {
+      wire: 'agentId',
+      wireTypeSymbol: '@fixture/session#SessionId',
+      resolve: id => id === 'fallback' ? fallback : undefined,
+    })
+    await expect(ctx.typert.contexts.getHost('registryFixture')?.resolve('configured')).resolves.toBe(configured)
+    expect(() => ctx.typert.contexts.configureHost('registryFixture', () => undefined)).toThrow('already configured')
+
+    await disposeProvider()
+    expect(ctx.typert.contexts.getHost('registryFixture')).toBeUndefined()
+    const disposeReloadedProvider = ctx.typert.contexts.registerHost('registryFixture', {
+      wire: 'agentId',
+      wireTypeSymbol: '@fixture/session#SessionId',
+      resolve: id => id === 'fallback' ? fallback : undefined,
+    })
+    await expect(ctx.typert.contexts.getHost('registryFixture')?.resolve('configured')).resolves.toBe(configured)
+
+    await disposeResolver()
+    expect(ctx.typert.contexts.getHost('registryFixture')?.resolve('fallback')).toBe(fallback)
+    await disposeReloadedProvider()
+  })
+
   it('publishes provider changes, rejects duplicate providers, and disposes subscriptions', async () => {
     const ctx = await makeCtx()
     const changes: string[] = []
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
index 510b8d3854..6c21127e54 100644
--- a/packages/typert/type-meta/README.i18n.yaml
+++ b/packages/typert/type-meta/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/typert/type-meta/README.md
-README.md: b394c843409e840b75bbb08b128614379e528001
-README.zh.md: 5bd9bb18289a0320e0603d8b373e60d7f1e3c7e5
+README.md: a76169742cb78d0d19814bcd0f978c71036a5a1c
+README.zh.md: 6f2d2fd6e241441fae8102c0639608e9b27b9bec
diff --git a/packages/typert/type-meta/README.md b/packages/typert/type-meta/README.md
index b394c84340..a76169742c 100644
--- a/packages/typert/type-meta/README.md
+++ b/packages/typert/type-meta/README.md
@@ -20,7 +20,7 @@ Decorator initializers retain markers in a module-private `WeakMap` keyed by the
 
 Business packages extend `TypeRTLookupMap` and `TypeRTContextMap` to associate Host objects or scoped Contexts with their wire identities. Generated artifacts extend `TypeRTRemoteMap`, `TypeRTRemoteContextMap`, and `TypeRTRemoteNamespaceMap` so Client imports expose only selected Remote methods. `InvocationDescriptor` is the shared runtime form consumed by the registry, Gateway, and Client API.
 
-Lookup and Context packages own both sides of their contract: declaration merging supplies the static association, while runtime providers register identity resolution with `ctx.typert`. A lookup provider supplies the stable declaration and default resolver, while Host composition may separately configure a synchronous or asynchronous resolver; policy rejections may use `TypeRTLookupFailure` to carry a failure value owned by the boundary adapter. Strict codecs carry generated schemas; `src-json` codecs identify the weaker source-launch path.
+Lookup and Context packages own both sides of their contract: declaration merging supplies the static association, while runtime providers register identity resolution with `ctx.typert`. A lookup or Host Context provider supplies the stable declaration and default resolver, while Host composition may separately configure a synchronous or asynchronous resolver; policy rejections may use `TypeRTLookupFailure` to carry a failure value owned by the boundary adapter. Strict codecs carry generated schemas; `src-json` codecs identify the weaker source-launch path.
 
 ## Model Experience
 
diff --git a/packages/typert/type-meta/README.zh.md b/packages/typert/type-meta/README.zh.md
index 5bd9bb1828..6f2d2fd6e2 100644
--- a/packages/typert/type-meta/README.zh.md
+++ b/packages/typert/type-meta/README.zh.md
@@ -20,7 +20,7 @@ Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用
 
 业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联 Host 对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteContextMap` 和 `TypeRTRemoteNamespaceMap`，使 Client 导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、Gateway 和 Client API 使用的共享运行时形式。
 
-查找包与 Context 包同时负责其契约的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。lookup provider 提供稳定声明与默认 resolver，Host 组合可以另行配置同步或异步 resolver；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
+查找包与 Context 包同时负责其契约的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。lookup 或 Host Context provider 提供稳定声明与默认 resolver，Host 组合可以另行配置同步或异步 resolver；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
 
 ## 模型体验
 
diff --git a/packages/typert/type-meta/src/index.ts b/packages/typert/type-meta/src/index.ts
index 1418c9d7f2..2f687f985f 100644
--- a/packages/typert/type-meta/src/index.ts
+++ b/packages/typert/type-meta/src/index.ts
@@ -50,6 +50,7 @@ export type {
   TypeRTContextWire,
   TypeRTDisposer,
   TypeRTHostContextProvider,
+  TypeRTHostContextResolver,
   TypeRTLocalRegistry,
   TypeRTLookup,
   TypeRTLookupDefinition,
diff --git a/packages/typert/type-meta/src/types.ts b/packages/typert/type-meta/src/types.ts
index b65690115f..ed309b7857 100644
--- a/packages/typert/type-meta/src/types.ts
+++ b/packages/typert/type-meta/src/types.ts
@@ -238,9 +238,14 @@ export interface TypeRTHostContextProvider<Wire = unknown> {
    * @param id - validated wire identity.
    * @returns the scoped Context, or `undefined` when unavailable.
    */
-  resolve(id: Wire): Context | undefined
+  resolve(id: Wire): Context | undefined | Promise<Context | undefined>
 }
 
+/** Composition-owned resolver replacing one Host Context provider's default lookup policy. */
+export type TypeRTHostContextResolver<Wire = unknown> = (
+  id: Wire,
+) => Context | undefined | Promise<Context | undefined>
+
 /** Client resolver for the identity carried by the calling scoped Context. */
 export interface TypeRTClientContextBinder<Wire = unknown> {
   /**
@@ -367,6 +372,17 @@ export interface TypeRTContextRegistry {
     key: K,
     provider: TypeRTHostContextProvider<TypeRTContextWire<TypeRTContextMap[K]>>,
   ): TypeRTDisposer
+  /**
+   * Override one Host Context key's identity policy for the calling fiber.
+   * Configuration may precede provider registration and restores the provider's default resolver on disposal.
+   * @param key - merge-declared Context key.
+   * @param resolver - composition-owned resolver used by every Host Context lookup of this key.
+   * @returns disposer restoring the provider's default resolver.
+   */
+  configureHost<K extends StringKeyOf<TypeRTContextMap>>(
+    key: K,
+    resolver: TypeRTHostContextResolver<TypeRTContextWire<TypeRTContextMap[K]>>,
+  ): TypeRTDisposer
   /**
    * Register a Client Context identity binder.
    * @param key - merge-declared Context key.

From d3b7ff17f005096031a5e25c255b0010d1fca13c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 16:58:43 +0800
Subject: [PATCH 149/516] fix: ci

---
 docs/cordis-catalog/services.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index cf763dca98..4a73dc06ad 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2593,7 +2593,7 @@ listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
 toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
 ```
 
-Source: [`packages/typert/registry/src/service.ts:400`](../../packages/typert/registry/src/service.ts)
+Source: [`packages/typert/registry/src/service.ts:446`](../../packages/typert/registry/src/service.ts)
 
 ## `ctx.typertGateway` — `TypertGatewayService`
 

From 146097368b4e2398db7b1a866144ab6d363f2803 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 17:21:37 +0800
Subject: [PATCH 150/516] fix(api-gateway): type async service disposer

---
 packages/api/gateway/src/client/index.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/api/gateway/src/client/index.ts b/packages/api/gateway/src/client/index.ts
index ddef36e288..a9343823ff 100644
--- a/packages/api/gateway/src/client/index.ts
+++ b/packages/api/gateway/src/client/index.ts
@@ -11,6 +11,7 @@ import type {
   InvocationDescriptor,
   TypeRTClientApi,
   TypeRTCodec,
+  TypeRTDisposer,
   TypeRTRemoteContribution,
 } from '@deepseek-ai/dsh-type-meta'
 
@@ -291,7 +292,7 @@ class ScopedRemoteNamespace {
   private readonly ctx: Context
   private readonly ownerCtx: Context
   private readonly methods = new Set<string>()
-  private disposeService: (() => void) | undefined
+  private disposeService: TypeRTDisposer | undefined
   readonly name: string
 
   static assertMethodAvailable(namespace: string, method: string): void {
@@ -348,7 +349,7 @@ class ScopedRemoteNamespace {
     if (this.methods.size !== 0) return
     const disposeService = this.disposeService
     this.disposeService = undefined
-    disposeService?.()
+    void disposeService?.()
   }
 }
 

From d6ffd87c5f1b193d698620e716a261743b9324dc Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 18:28:30 +0800
Subject: [PATCH 151/516] refactor(api): expose traced remote namespaces

---
 ...08-02-typert-remote-method-calls.i18n.yaml |   4 +-
 .../2026-08-02-typert-remote-method-calls.md  |  72 +--
 ...026-08-02-typert-remote-method-calls.zh.md |  72 +--
 docs/api-gateway.i18n.yaml                    |   4 +-
 docs/api-gateway.md                           |  22 +-
 docs/api-gateway.zh.md                        |  22 +-
 docs/core-data-structures/typert.i18n.yaml    |   4 +-
 docs/core-data-structures/typert.md           |  16 +-
 docs/core-data-structures/typert.zh.md        |  16 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +-
 docs/development.zh.md                        |   2 +-
 packages/api/README.i18n.yaml                 |   4 +-
 packages/api/README.md                        |   6 +-
 packages/api/README.zh.md                     |   6 +-
 packages/api/gateway/README.i18n.yaml         |   4 +-
 packages/api/gateway/README.md                |   8 +-
 packages/api/gateway/README.zh.md             |   8 +-
 packages/api/gateway/src/client/index.ts      | 414 +++++++++++-------
 packages/api/gateway/tests/client.spec.ts     | 245 +++++------
 packages/api/remotes/README.i18n.yaml         |   4 +-
 packages/api/remotes/README.md                |   6 +-
 packages/api/remotes/README.zh.md             |   6 +-
 packages/api/remotes/src/client/index.ts      |  16 +-
 packages/api/remotes/tests/built-lib.e2e.ts   |   8 +-
 .../client/runtime/src/client/agents/scope.ts |  11 +-
 .../runtime/src/client/contract/sessions.ts   |   5 +-
 packages/client/runtime/src/client/index.ts   |   4 +-
 .../client/runtime/tests/client-apply.spec.ts |   3 +-
 .../client/runtime/tests/wire-events.spec.ts  |   3 +-
 packages/client/ui-goal/README.i18n.yaml      |   4 +-
 packages/client/ui-goal/README.md             |   2 +-
 packages/client/ui-goal/README.zh.md          |   2 +-
 packages/client/ui-goal/src/client/index.ts   |  12 +-
 .../ui-goal/tests/browser-plugin.spec.tsx     |  15 +-
 .../generator/tests/remote-model.spec.ts      |  10 +-
 packages/typert/type-meta/src/index.ts        |   2 +-
 packages/typert/type-meta/src/types.ts        |  10 +-
 38 files changed, 566 insertions(+), 492 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 1e4aeaabd7..341bf44923 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: 3d5a79fd4a26f7d232dcc7635625899e2eb9df6b
-2026-08-02-typert-remote-method-calls.zh.md: 3d6ec680ba97a532f18219670e8dba799a94ed7b
+2026-08-02-typert-remote-method-calls.md: a8254090e042e4b359ae74fc5c19bad8abc5ef89
+2026-08-02-typert-remote-method-calls.zh.md: f1b7e5f9c61b474379962ce007e5d6bb966e5ebd
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index 3d5a79fd4a..a8254090e0 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -18,11 +18,11 @@ The Host and Browser Client use separate TypeScript Programs because each side a
 
 A business Service extends `GatewayService` and declares callable methods with `@Remote` or `@RemoteContext()`. A Service that already has another base class may instead expose the same binding through `bindTypeRTGateway()`. TypeRT generates the Host-local reflection artifact and a platform-independent Remote consumer projection from the Host Program. The Client Program continues to generate its own local reflection artifact independently.
 
-The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. The `.d.ts` exposes only methods marked with a Remote decorator and refers to the business package's single public type symbols. The `.d.ts.map` navigates consumer API methods back to their Host business method implementations. The `.js` carries endpoint, parameter, Context, and Zod information for the same contract. At the assembly layer, the Browser Client mounts the required Remote JS contributions onto the Client API Service. The projection and API abstraction remain platform-independent so that a future TUI can reuse them.
+The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. The `.d.ts` exposes only methods marked with a Remote decorator and refers to the business package's single public type symbols. The `.d.ts.map` navigates consumer API methods back to their Host business method implementations. The `.js` carries endpoint, parameter, Context, and Zod information for the same contract. At the assembly layer, the Browser Client mounts the required Remote JS contributions onto the Client Remote Service. The projection and Remote abstraction remain platform-independent so that a future TUI can reuse them.
 
-`@deepseek-ai/dsh-api-gateway`, located at `packages/api/gateway`, provides two symmetric faces: its default entry provides Host `ctx.typertGateway`, while its `/client` entry provides consumer-side `ctx.api`. Each side consumes a locally generated `InvocationDescriptor` from the same model; descriptors are not sent over the wire. The Remote data protocol runs over Connection's shared `/api` RPC channel. The business calling interface does not change when Connection migrates from HTTP to WebSocket.
+`@deepseek-ai/dsh-api-gateway`, located at `packages/api/gateway`, provides two symmetric faces: its default entry provides Host `ctx.typertGateway`, while its `/client` entry provides consumer-side `ctx.remote`. Each side consumes a locally generated `InvocationDescriptor` from the same model; descriptors are not sent over the wire. The Remote data protocol runs over Connection's shared `/api` RPC channel. The business calling interface does not change when Connection migrates from HTTP to WebSocket.
 
-`@deepseek-ai/dsh-api-remotes`, located at `packages/api/remotes`, is the BFF layer above the Gateway. Its Host entry owns Agent/Session identity resolution and TypeRT lookup configuration; its `/client` entry selects the generated Remote contributions exposed by the application. The Client entry consumes the shared `TypeRTClientApi` contract through Cordis rather than importing the concrete Gateway implementation.
+`@deepseek-ai/dsh-api-remotes`, located at `packages/api/remotes`, is the BFF layer above the Gateway. Its Host entry owns Agent/Session identity resolution and TypeRT lookup configuration; its `/client` entry selects the generated Remote contributions exposed by the application. The Client entry consumes the shared `TypeRTClientRemote` contract through Cordis rather than importing the concrete Gateway implementation.
 
 ## Components and Cordis services
 
@@ -33,12 +33,12 @@ The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. T
 | TypeRT generator/loader | No new business service | Generates three kinds of `lib` artifacts from the Host/Client Programs and registers the current environment's artifacts with `ctx.typert` |
 | API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, invokes methods, and encodes results |
 | Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, the shared `/api` route, RPC envelope, rpcId, serialization, trust, error transport, TypeRT interception, and legacy API Proxy fallback |
-| API Gateway's Client face | `ctx.api` | Mounts Remote contributions, materializes root and scoped APIs, and delegates canonical calls to `ctx.connection.rpc` |
+| API Gateway's Client face | `ctx.remote`, `ctx.remote.<namespace>` | Mounts Remote contributions, materializes each namespace as a traced `remote.<namespace>` child Service, and delegates canonical calls to `ctx.connection.rpc` |
 | API Remotes | No new service | Owns Host Agent/Session lookup policy and serves as the only Client business facade, selecting and mounting `/remote` contributions while exposing the selected API declarations |
 | Agent/Session owning packages | Existing domain services | Provide both static interface merges and runtime lookup/Context providers |
 | Business packages such as Goal | Existing business Services | Declare only bindings, Remote methods, and canonical DTOs, and export the generated `/remote` subpath |
 
-The Host Gateway does not depend on concrete implementations of `ctx.agents`, `ctx.sessions`, `ctx.goals`, or `ctx.httpServer`. The Client API does not understand the physical carrier, and Connection does not understand Goal, Agent, lookup, `InvocationDescriptor`, or Client API namespaces.
+The Host Gateway does not depend on concrete implementations of `ctx.agents`, `ctx.sessions`, `ctx.goals`, or `ctx.httpServer`. The Client Remote does not understand the physical carrier, and Connection does not understand Goal, Agent, lookup, `InvocationDescriptor`, or Remote namespaces.
 
 ## Business declarations
 
@@ -121,7 +121,7 @@ The Client also registers an `agent` Context binder. The binder only retrieves a
 
 ## InvocationDescriptor
 
-TypeRT, the permissive SRC parser, Host Gateway, and Client API exchange one canonical description:
+TypeRT, the permissive SRC parser, Host Gateway, and Client Remote exchange one canonical description:
 
 ```text
 InvocationDescriptor {
@@ -141,7 +141,7 @@ InvocationDescriptor {
 }
 ```
 
-`method` is the external short name used by the endpoint and Client API; `implementation` is the actual member name on the Host receiver. `implementation` may be omitted when the two names match. A `direct` descriptor retains the original Service instance as the receiver. A Context descriptor first uses the corresponding Context provider to find the scoped Context, then resolves the receiver by the descriptor's service key.
+`method` is the external short name used by the endpoint and Client Remote; `implementation` is the actual member name on the Host receiver. `implementation` may be omitted when the two names match. A `direct` descriptor retains the original Service instance as the receiver. A Context descriptor first uses the corresponding Context provider to find the scoped Context, then resolves the receiver by the descriptor's service key.
 
 The strict generator writes `scope` only when a direct method has exactly one lookup parameter, a `TypeRTContextMap` declaration with the same name exists, and both use the same wire type symbol. `scope.wire` must identify that lookup parameter. It declares that a consumer may fill this parameter from the Context in which the call occurs, without changing the Host receiver or endpoint. No scoped projection is generated when there are multiple lookups, no Context declaration, or mismatched wire types; a type mismatch is a build error.
 
@@ -179,9 +179,9 @@ import type { CreateGoalRequest, CreateGoalResult } from '@deepseek-ai/dsh-goal/
 
 Consequently, `SessionId`, the Agent wire ID, the request, and the result all refer to the same TypeScript declaration in the Host and Browser Client. A future TUI can reuse them without a second set of types. Go to Definition, renames, and Find References for a DTO return to the one source location for the business type instead of stopping at a copy in a generated file.
 
-Remote API methods themselves use declaration-map navigation. TypeRT anchors `InvocationModel.location` to the decorated Host method-name token and emits a source-map segment on the corresponding property of the namespace interface. For an adapter-backed endpoint, after the TypeScript editor resolves `ctx.api.models.list` to its generated declaration, `typert.remote-client.d.ts.map` takes it to the Host Service's `remoteExportList` entry point. That entry point explicitly calls the existing, unrenamed `list()` method; the map does not misidentify the decorator, class, or full signature as the method definition.
+Remote methods themselves use declaration-map navigation. TypeRT anchors `InvocationModel.location` to the decorated Host method-name token and emits a source-map segment on the corresponding property of the namespace interface. For an adapter-backed endpoint, after the TypeScript editor resolves `ctx.remote.models.list` to its generated declaration, `typert.remote-client.d.ts.map` takes it to the Host Service's `remoteExportList` entry point. That entry point explicitly calls the existing, unrenamed `list()` method; the map does not misidentify the decorator, class, or full signature as the method definition.
 
-TypeRT generates a wire Zod codec for the same symbol key. The Host Gateway uses it to validate input and encode results, while the Client API may use it to encode arguments and validate responses. If a complex type cannot produce a strict codec, the LIB build fails instead of degrading to `unknown` or unchecked JSON.
+TypeRT generates a wire Zod codec for the same symbol key. The Host Gateway uses it to validate input and encode results, while the Client Remote uses it to encode arguments and validate responses. If a complex type cannot produce a strict codec, the LIB build fails instead of degrading to `unknown` or unchecked JSON.
 
 Named business types referenced by Remote methods must be exported from public, type-only subpaths. If the only reachable entry also imports Host Services, Cordis `Context` merges, or Host-only implementations, the build fails and requires the business package to provide a safe type entry. Primitives, literals, and simple compositions explicitly supported by TypeRT need no additional names.
 
@@ -238,7 +238,7 @@ This import brings the `.d.ts` map augmentation into the current TypeScript proj
 
 The business package's published files must include both `lib/typert.remote-client.d.ts.map` and the `src` file referenced by that map. The generated DTS refers to its adjacent map with `//# sourceMappingURL=typert.remote-client.d.ts.map`; the map source points from `lib` to the business source by a relative path such as `../src/index.ts`. The `/remote` export does not list the map separately; the package `files` field publishes it together with the source.
 
-Code that needs only static types may use `import type {} from '@deepseek-ai/dsh-goal/remote'`. This import is erased at runtime, loads no JS, and cannot trigger runtime registration. An environment that makes real calls must pass the contribution from a normal value import to the API Service.
+Code that needs only static types may use `import type {} from '@deepseek-ai/dsh-goal/remote'`. This import is erased at runtime, loads no JS, and cannot trigger runtime registration. An environment that makes real calls must pass the contribution from a normal value import to the Client Remote Service.
 
 Workspace resolution for `/remote` must explicitly target generated `lib` artifacts and must not let a general package-to-`src` paths rule redirect it to Host source. Ordinary business imports may continue resolving to SRC or LIB according to each environment's existing rules.
 
@@ -275,18 +275,18 @@ interface TypeRTRemoteContextMap {
 }
 ```
 
-`TypeRTRemoteMap` preserves canonical endpoint signatures for protocol typing and reflection. The root API type reads `TypeRTRemoteNamespaceMap` directly instead of deriving methods indirectly through a key-remapped mapped type; the TypeScript Language Service cannot reliably navigate such indirect properties through a declaration map. A namespace interface name encodes the namespace's UTF-8 bytes as hexadecimal, so `goals` deterministically becomes `TypeRTRemoteNamespace$676f616c73`. Different packages generate the same interface name for the same namespace and use module augmentation to merge their methods, while `TypeRTRemoteNamespaceMap.goals` always refers to that one type.
+`TypeRTRemoteMap` preserves canonical endpoint signatures for protocol typing and reflection. The root Remote type reads `TypeRTRemoteNamespaceMap` directly instead of deriving methods indirectly through a key-remapped mapped type; the TypeScript Language Service cannot reliably navigate such indirect properties through a declaration map. A namespace interface name encodes the namespace's UTF-8 bytes as hexadecimal, so `goals` deterministically becomes `TypeRTRemoteNamespace$676f616c73`. Different packages generate the same interface name for the same namespace and use module augmentation to merge their methods, while `TypeRTRemoteNamespaceMap.goals` always refers to that one type.
 
 TypeRT projects `TypeRTRemoteContextMap` onto a dedicated Scope type according to its Context key. The final programming interface remains:
 
 ```text
-api.goals.create(agentId, request)
-agent.goals.create(request)
+ctx.remote.goals.create(agentId, request)
+agentCtx.remote.goals.create(request)
 ```
 
-The Agent Scope supplies its own `SessionId` automatically. A `@Remote` method with an `agent` lookup can therefore generate both root and scoped consumer signatures. A `@RemoteContext('agent')` method also omits a separate Context identity, but generates only the scoped signature. In this phase, only the Client Agent Context gains `goals`; the Root Context does not. A future TUI must preserve the same Scope restriction.
+The Agent Scope supplies its own `SessionId` automatically. A `@Remote` method with an `agent` lookup can therefore generate both root and scoped consumer signatures. A `@RemoteContext('agent')` method also omits a separate Context identity, but generates only the scoped signature. The root `Context` exposes direct namespaces through `ctx.remote`, while `AgentContext.remote` intersects that direct surface with the scoped surface. A future TUI must preserve the same distinction.
 
-`RemoteApi` remains platform-independent, and the Browser Client uses it as its `ClientApi`. If a future TUI reuses this type, it must likewise access it through a dedicated API object and Agent Scope rather than treating the Host `Context` as a broader Service collection. Public Service methods without Remote markers do not enter the Remote maps.
+`TypeRTClientRemote` remains platform-independent, and the Browser Client exposes it as `ctx.remote`. If a future TUI reuses this type, it must likewise access it through a dedicated Remote object and Agent Scope rather than treating the Host `Context` as a broader Service collection. Public Service methods without Remote markers do not enter the Remote maps.
 
 ## Client TypeRT and the API Gateway Client face
 
@@ -303,39 +303,39 @@ TypeRT.remotes  已导入的 Remote contribution
 import goalsRemote from '@deepseek-ai/dsh-goal/remote'
 import sessionsRemote from '@deepseek-ai/dsh-session/remote'
 
-ctx.api.mount(goalsRemote)
-ctx.api.mount(sessionsRemote)
+await ctx.remote.$mount(goalsRemote)
+await ctx.remote.$mount(sessionsRemote)
 ```
 
-Client business packages depend only on `@deepseek-ai/dsh-api-remotes/client`, not directly on the API Gateway or the runtime entry of each business `/remote`. API Remotes consumes the shared `TypeRTClientApi` contract and Cordis `ctx.api` service, then re-exports declarations so the selected Remote map reaches business compilation. Adding or removing a complete Client capability changes only this assembly point.
+Client business packages depend only on `@deepseek-ai/dsh-api-remotes/client`, not directly on the API Gateway or the runtime entry of each business `/remote`. API Remotes consumes the shared `TypeRTClientRemote` contract and Cordis `ctx.remote` service, then re-exports declarations so the selected Remote map reaches business compilation. Adding or removing a complete Client capability changes only this assembly point.
 
-`ctx.api.mount()` registers a contribution with `TypeRT.remotes`, and its disposer is owned by the Cordis fiber that called the method. Duplicate endpoints, conflicting invocation modes for the same namespace and method, or conflicts between a descriptor and an existing type identity fail immediately.
+`ctx.remote.$mount()` registers a contribution with `TypeRT.remotes`, installs its namespace Services and concrete methods, and resolves only after they are ready. Its disposer is owned by the Cordis fiber that called the method. Duplicate endpoints, conflicting invocation modes for the same namespace and method, or conflicts between a descriptor and an existing type identity fail immediately.
 
-The API Service materializes each `@Remote` descriptor as a real function on the root `api`. The function constructs named `args` in descriptor parameter order, applies the Client's strict codec, and then calls `ctx.connection.rpc.call('/api', endpoint, { args }, signal)`. For a cancellation-aware descriptor, the generated function accepts a final optional signal and combines it with the contribution mount lifetime; unmounting therefore cancels every in-flight carrier call, while a caller can cancel one call independently.
+The Client Remote Service materializes each `@Remote` descriptor as a real function on a `remote.<namespace>` child Service. The function constructs named `args` in descriptor parameter order, applies the Client's strict codec, and then calls `ctx.connection.rpc.call('/api', endpoint, { args }, signal)`. For a cancellation-aware descriptor, the generated function accepts a final optional signal and combines it with the contribution mount lifetime; unmounting therefore cancels every in-flight carrier call, while a caller can cancel one call independently.
 
-Neither a direct descriptor with `scope` nor a `@RemoteContext` descriptor copies functions into every Agent Scope. The API Service creates one root singleton Cordis Service for each scoped namespace and materializes methods on that Service. When `agent.goals.create()` is called, the Cordis tracker rebinds the Service's `this.ctx` to the current Agent Context. The method then asks the corresponding Context binder for identity from `this.ctx`. A direct scoped projection substitutes this identity at the lookup position named by `scope.wire`; a Context descriptor writes the identity into the receiver's separate wire field. Both issue the same kind of `/api` call.
+Neither a direct descriptor with `scope` nor a `@RemoteContext` descriptor copies functions into every Agent Scope. The Client Remote Service creates one Cordis child Service per namespace, registered as `remote.<namespace>`, and materializes direct and scoped variants on it. Accessing a method through `agentCtx.remote.goals` captures the current Agent Context before returning the callable handle. The method then asks the corresponding Context binder for identity from that Context. A direct scoped projection substitutes this identity at the lookup position named by `scope.wire`; a Context descriptor writes the identity into the receiver's separate wire field. Both issue the same kind of `/api` call.
 
 ```text
-root ctx.api.goals.create(agentId, request)
+root ctx.remote.goals.create(agentId, request)
   → direct descriptor
   → ctx.connection.rpc.call('/api', 'goals/create', { args })
 
-agent.goals.create(request)
-  → tracker 将 namespace Service rebind 到 agent Context
+agentCtx.remote.goals.create(request)
+  → remote.goals accessor 捕获 agent Context
   → agent binder 从 caller Context 取得 agentId
   → 用 agentId 补入同一 direct descriptor 的 lookup 参数
   → ctx.connection.rpc.call('/api', 'goals/create', { args })
 ```
 
-The Root `Context` does not merge the scoped `goals` type; only `AgentContext` gains that property through `RemoteContextApi<'agent'>`. If a caller bypasses the type system and dynamically calls a scoped method from Root, the binder reports an explicit error. If the Client already has a Cordis service with the same name, or two contributions claim the same namespace and method incompatibly, mounting fails instead of overwriting the existing service.
+The root `Context` merges only the direct `TypeRTClientRemote` surface. `AgentContext` replaces that property with the intersection of `TypeRTClientRemote` and `TypeRTRemoteContextApi<'agent'>`, so scoped-only methods remain unavailable from root code. If a caller bypasses the type system and dynamically calls a scoped-only method from Root, the binder reports an explicit error. If the Client already has a Cordis service named `remote.<namespace>`, or two contributions claim the same namespace and method incompatibly, mounting fails instead of overwriting the existing service.
 
-Generated Remote JS contains only descriptors, symbol keys, and codecs; it does not bundle Host Service implementations. The API Service creates real functions from that data, so the runtime does not depend on a JavaScript Proxy. A Proxy remains an implementation option but is not a source of types or reflection.
+Generated Remote JS contains only descriptors, symbol keys, and codecs; it does not bundle Host Service implementations. The Client Remote Service creates real functions from that data, so the runtime does not depend on a JavaScript Proxy. A Proxy remains an implementation option but is not a source of types or reflection.
 
 ## Cross-environment isomorphism constraints
 
 Remote API is a consumer capability, not a synonym for Browser API. The shipped runtime implements Browser Client contribution mounting, Connection RPC calls, and Agent Scope association.
 
-Remote DTS, Remote JS, `RemoteApi`, `InvocationDescriptor`, the Remote RPC data protocol, and Context binders must not depend on the DOM, Browser module loaders, or HTTP. Through Connection, the Browser Client encodes descriptor-materialized methods as `/api` RPC calls.
+Remote DTS, Remote JS, `TypeRTClientRemote`, `InvocationDescriptor`, the Remote RPC data protocol, and Context binders must not depend on the DOM, Browser module loaders, or HTTP. Through Connection, the Browser Client encodes descriptor-materialized methods as `/api` RPC calls.
 
 A future TUI can join the same call abstraction without changing business decorators, Remote maps, or the shape of API calls. The TUI-visible API must still be generated exclusively from `@Remote` and `@RemoteContext`; sharing a process with the Host must not allow it to bypass Remote restrictions and expose Service methods directly.
 
@@ -421,7 +421,7 @@ The Remote payload is a named JSON object, not a positional array, and does not
 The complete path is:
 
 ```text
-ctx.api.goals.create(sessionId, request, signal?)
+ctx.remote.goals.create(sessionId, request, signal?)
 → Client InvocationDescriptor 编码 { args: { agentId, request } }
 → Client 合并 caller signal 与 contribution mount lifetime
 → ctx.connection.rpc.call('/api', 'goals/create', { args }, signal)
@@ -442,7 +442,7 @@ The Gateway does not handle per-method permissions, caller identity, idempotency
 
 ## Connection and protocol boundaries
 
-The API Service owns Remote contributions, method materialization, Scope binding, and the correspondence between positional parameters and descriptors. The Gateway owns Host descriptors, endpoint ownership, lookup, Context, and business invocation. Connection sends `/api`, the endpoint, and `{ args }` as one RPC call to the target and returns the existing RPC result; it does not understand Goal, Agent, lookup, descriptors, or Client API types.
+The Client Remote Service owns Remote contributions, namespace Service materialization, Scope binding, and the correspondence between positional parameters and descriptors. The Gateway owns Host descriptors, endpoint ownership, lookup, Context, and business invocation. Connection sends `/api`, the endpoint, and `{ args }` as one RPC call to the target and returns the existing RPC result; it does not understand Goal, Agent, lookup, descriptors, or Client Remote types.
 
 The Gateway registers only its ownership matcher and RPC handler with Connection; it does not register an HTTP route. Connection mounts the shared `/api` route into the HTTP Server and gives the bridge one composite FetchHandler; that handler dispatches claimed endpoints to Gateway and unclaimed endpoints to API Proxy. A future Connection transport can preserve this order without changing the Remote payload, business decorators, generated DTS, Remote API types, or Agent Scope programming interface.
 
@@ -451,8 +451,8 @@ The Gateway registers only its ownership matcher and RPC handler with Connection
 - `@deepseek-ai/dsh-type-meta`: lightweight protocols for decorators, bindings, lookup, Remote Context, and descriptors.
 - TypeRT generator: analyzes Host/Client Programs, generates local faces and Remote consumer projections, and emits canonical symbol/Zod information.
 - TypeRT runtime: separately stores the current environment's local reflection and imported Remote contributions.
-- `@deepseek-ai/dsh-api-gateway`: its default entry associates Host definitions with Services, claims Remote endpoints, performs lookup, resolves Context receivers, invokes methods, encodes results, and registers an `/api` interceptor with Connection; its `/client` entry mounts Remote contributions, creates strict API methods, and delegates calls to `ctx.connection.rpc`. The entries share the Remote protocol but do not import each other's Cordis interface merges.
-- `@deepseek-ai/dsh-api-remotes`: the BFF layer; owns the Host Agent/Session resolver, selects Client `/remote` contributions, and exposes the merged API types to business packages through the shared `TypeRTClientApi` contract.
+- `@deepseek-ai/dsh-api-gateway`: its default entry associates Host definitions with Services, claims Remote endpoints, performs lookup, resolves Context receivers, invokes methods, encodes results, and registers an `/api` interceptor with Connection; its `/client` entry mounts Remote contributions, creates strict Remote namespace Services and methods, and delegates calls to `ctx.connection.rpc`. The entries share the Remote protocol but do not import each other's Cordis interface merges.
+- `@deepseek-ai/dsh-api-remotes`: the BFF layer; owns the Host Agent/Session resolver, selects Client `/remote` contributions, and exposes the merged Remote types to business packages through the shared `TypeRTClientRemote` contract.
 - Connection: owns the single HTTP Server/future WebSocket carrier, shared `/api` route and composite FetchHandler, API Proxy fallback, RPC envelope, rpcId, serialization, trust, and error transport.
 - Business-object packages such as Agent/Session: own lookup, Context providers, canonical ID types, and public type-only entries.
 - API Proxy Host composition: supplies Web Agent defaults and scope setup to API Remotes and consumes the same `agentFor()` for legacy methods.
@@ -460,7 +460,7 @@ The Gateway registers only its ownership matcher and RPC handler with Connection
 
 ## Shipped scope and deferred work
 
-The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`. The same direct descriptor with an Agent lookup supports both `ctx.api.goals.create(agentId, request)` and `agentCtx.goals.create(request)`. Ordinary cold sessions are resumed through `agentFor()` during lookup, while subagent-owned identities retain the existing `agent-busy` fence; `@RemoteContext('agent')` remains the distinct scoped-receiver mode.
+The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client Remote → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`. The same direct descriptor with an Agent lookup supports both `ctx.remote.goals.create(agentId, request)` and `agentCtx.remote.goals.create(request)`. Ordinary cold sessions are resumed through `agentFor()` during lookup, while subagent-owned identities retain the existing `agent-busy` fence; `@RemoteContext('agent')` remains the distinct scoped-receiver mode.
 
 Connection supplies the shared-channel interceptor and current HTTP carrier mapping. WebSocket migration, the TUI runtime and carrier, TUI Agent Scope wiring, Permission/Approval state machines, Session event streams, call authorization, retries, idempotency, and cross-version protocol compatibility remain outside this decision.
 
@@ -482,7 +482,7 @@ The package topology is `api/remotes → api/gateway → client/connection → h
 
 **Generate only Remote DTS, without JS.** Types would work, but the runtime could not enumerate endpoints, codecs, and Context modes without a Proxy or another hand-written registry. The same Host projection therefore emits a Remote JS contribution as well.
 
-**Let a top-level `/remote` import register global state implicitly.** The target Cordis Context may not exist when ESM evaluation occurs, and ownership becomes ambiguous across multiple Contexts, HMR, and disposal. A normal value import therefore returns only a contribution, which the environment assembly explicitly mounts through the API Service.
+**Let a top-level `/remote` import register global state implicitly.** The target Cordis Context may not exist when ESM evaluation occurs, and ownership becomes ambiguous across multiple Contexts, HMR, and disposal. A normal value import therefore returns only a contribution, which the environment assembly explicitly mounts through the Client Remote Service.
 
 **Create a separate transport, HTTP route, or `/api2` channel for Remote.** This would duplicate or split Connection's Server ownership, rpcId, serialization, trust, errors, and future WebSocket lifecycle. The shared `/api` interceptor instead keeps one physical route and lets Connection preserve API Proxy as the fallback FetchHandler.
 
@@ -490,7 +490,7 @@ The package topology is `api/remotes → api/gateway → client/connection → h
 
 - Goal Service directly decorates mutation methods whose business signatures already match the Remote contract and keeps `remoteExportCreate(...)` only to adapt `GoalView` into `CreateGoalResult`, without a second route, codec, or Client method list.
 - A clean `build:lib` emits Host and consumer Remote artifacts before Client compilation, including the business package's JS, DTS, and declaration map under `/remote`.
-- Importing `@deepseek-ai/dsh-goal/remote` adds the strict `api.goals.create(...)` type and declaration navigation to `remoteExportCreate`; omitting that import omits the namespace.
+- Importing `@deepseek-ai/dsh-goal/remote` adds the strict `ctx.remote.goals.create(...)` type and declaration navigation to `remoteExportCreate`; omitting that import omits the namespace.
 - Mounting the same import's JS contribution supplies endpoint, parameter, result, lookup, Context, and Zod reflection and materializes the call without a handwritten stub.
 - Root and Agent-scoped calls cross the real shared `/api` carrier, resolve `agentId` to the live Agent, invoke the original Goal receiver, and return through the existing RPC envelope.
 - Agent and Session lookups share a single in-flight cold-session resume; ordinary cold sessions receive restored objects, while both cold and live subagent identities return `agent-busy` before business invocation.
@@ -509,13 +509,13 @@ The permissive SRC descriptor does not validate the internal structure of ordina
 
 Canonical public types require business DTOs to have type-only entries, which may expose packages whose Host types and implementation entries are currently mixed. The build rejects those boundaries instead of copying types to conceal them.
 
-Type imports and runtime contributions have different effects. `import type {}` extends only the static API. If a real calling environment omits the value contribution, the API Service must fail with an explicit "Remote not mounted" error.
+Type imports and runtime contributions have different effects. `import type {}` extends only the static Remote surface. If a real calling environment omits the value contribution, the Client Remote Service must fail with an explicit "Remote not mounted" error.
 
 Browser and Host each hold their own Zod instances and cannot compare object identities across realms. Consistency is guaranteed only by canonical symbol keys, the same generated model, and wire behavior.
 
 A consumer may import a Remote contract that is not currently mounted on the Host. The types mean "this protocol capability was selected by the consumer," not that a corresponding Service currently exists in the target process; an unavailable endpoint must fail explicitly at runtime.
 
-Connection's general channel API must suit both the current HTTP carrier and a future WebSocket carrier. If the API exposes `fetch`, an HTTP request, or a route handle to the Gateway/API Service, WebSocket migration will pierce the Remote layer again. Those physical objects must therefore remain internal to Connection.
+Connection's general channel API must suit both the current HTTP carrier and a future WebSocket carrier. If the Client Remote or Gateway exposes `fetch`, an HTTP request, or a route handle, WebSocket migration will pierce the Remote layer again. Those physical objects must therefore remain internal to Connection.
 
 Remote endpoints use Connection's `trusted-host` authority. Loopback is accepted by default and LAN callers require an explicit trusted-host configuration, but this layer adds no per-method caller authorization; every trusted host can invoke a mounted Remote endpoint.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 3d6ec680ba..f1b7e5f9c6 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -18,11 +18,11 @@ Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以
 
 业务 Service 继承 `GatewayService`，并通过 `@Remote` 或 `@RemoteContext()` 声明可调用方法；已有其他基类的 Service 可以改用 `bindTypeRTGateway()` 暴露同一绑定。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
 
-Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client API Service；该投影和 API 抽象保持平台无关，以便未来 TUI 复用。
+Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client Remote Service；该投影和 Remote 抽象保持平台无关，以便未来 TUI 复用。
 
-`@deepseek-ai/dsh-api-gateway` 位于 `packages/api/gateway`，提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.api`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在 Connection 共享的 `/api` RPC channel 上；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
+`@deepseek-ai/dsh-api-gateway` 位于 `packages/api/gateway`，提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.remote`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在 Connection 共享的 `/api` RPC channel 上；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
 
-`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientApi` 契约，而不导入具体 Gateway 实现。
+`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 契约，而不导入具体 Gateway 实现。
 
 ## 组件和 Cordis 服务
 
@@ -33,12 +33,12 @@ Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只
 | TypeRT generator/loader | 无新增业务服务 | 从 Host/Client Program 生成三类 `lib` 产物，并把当前环境产物注册到 `ctx.typert` |
 | API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service，解码参数、解析 receiver、调用方法和编码结果 |
 | Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、共享 `/api` route、RPC envelope、rpcId、序列化、trust、错误传输、TypeRT 拦截和旧 API Proxy 回退 |
-| API Gateway 的 Client face | `ctx.api` | mount Remote contribution，实体化根 API 和 scoped API，把规范调用交给 `ctx.connection.rpc` |
+| API Gateway 的 Client face | `ctx.remote`、`ctx.remote.<namespace>` | mount Remote contribution，把每个 namespace 实体化为可追踪的 `remote.<namespace>` 子 Service，并把规范调用交给 `ctx.connection.rpc` |
 | API Remotes | 无新增服务 | 负责 Host Agent/Session lookup 策略，并作为 Client 业务的唯一 facade，选择并挂载 `/remote` contribution，同时暴露所选 API 声明 |
 | Agent/Session owning 包 | 既有领域服务 | 同时提供静态 interface merge 与运行时 lookup/Context provider |
 | Goal 等业务包 | 既有业务 Service | 只声明 binding、Remote 方法和唯一 DTO，并导出生成的 `/remote` 子路径 |
 
-Host Gateway 不依赖 `ctx.agents`、`ctx.sessions`、`ctx.goals` 或 `ctx.httpServer` 的具体实现。Client API 不理解物理 carrier，Connection 也不理解 Goal、Agent、lookup、`InvocationDescriptor` 或 Client API namespace。
+Host Gateway 不依赖 `ctx.agents`、`ctx.sessions`、`ctx.goals` 或 `ctx.httpServer` 的具体实现。Client Remote 不理解物理 carrier，Connection 也不理解 Goal、Agent、lookup、`InvocationDescriptor` 或 Remote namespace。
 
 ## 业务声明
 
@@ -121,7 +121,7 @@ Client 侧也注册 `agent` Context binder。binder 只负责从一次调用所
 
 ## InvocationDescriptor
 
-TypeRT、SRC 弱解析器、Host Gateway 和 Client API 之间只交换一种规范描述：
+TypeRT、SRC 弱解析器、Host Gateway 和 Client Remote 之间只交换一种规范描述：
 
 ```text
 InvocationDescriptor {
@@ -141,7 +141,7 @@ InvocationDescriptor {
 }
 ```
 
-`method` 是 endpoint 和 Client API 使用的外部短名，`implementation` 是 Host receiver 上的真实成员名；两者相同时可省略 `implementation`。`direct` descriptor 保留原始 Service 实例作为 receiver。Context descriptor 先通过对应 Context provider 找到 scoped Context，再以 descriptor 的 service key 解析 receiver。
+`method` 是 endpoint 和 Client Remote 使用的外部短名，`implementation` 是 Host receiver 上的真实成员名；两者相同时可省略 `implementation`。`direct` descriptor 保留原始 Service 实例作为 receiver。Context descriptor 先通过对应 Context provider 找到 scoped Context，再以 descriptor 的 service key 解析 receiver。
 
 严格生成器只在 direct 方法恰好包含一个 lookup 参数、同名 `TypeRTContextMap` 声明存在且两者使用同一 wire 类型 symbol 时写入 `scope`。`scope.wire` 必须指向该 lookup 参数；它声明消费端可以从调用所在 Context 补入这个参数，不改变 Host receiver 或 endpoint。多个 lookup、缺少 Context 声明或 wire 类型不一致时不生成 scoped 投影，其中类型不一致属于构建错误。
 
@@ -179,9 +179,9 @@ import type { CreateGoalRequest, CreateGoalResult } from '@deepseek-ai/dsh-goal/
 
 因此 `SessionId`、Agent wire ID、request 和 result 在 Host 与 Browser Client 中都指向同一 TypeScript declaration，未来 TUI 复用时也不需要第二份类型。DTO 的跳转定义、重命名和引用查找回到业务类型的唯一源码位置，而不是停在生成文件中的副本。
 
-Remote API 方法本身使用 declaration map 导航。TypeRT 把 `InvocationModel.location` 固定在 Host 被装饰方法的方法名 token，并在 namespace interface 的对应属性上写入 source-map segment。对于由适配器支撑的 endpoint，TypeScript editor 从 `ctx.api.models.list` 取得生成 declaration 后，再沿 `typert.remote-client.d.ts.map` 跳到 Host Service 的 `remoteExportList` 远程出口。该出口继续显式调用不改名的存量 `list()`，map 不把 decorator、class 或整个签名误当成方法定义位置。
+Remote 方法本身使用 declaration map 导航。TypeRT 把 `InvocationModel.location` 固定在 Host 被装饰方法的方法名 token，并在 namespace interface 的对应属性上写入 source-map segment。对于由适配器支撑的 endpoint，TypeScript editor 从 `ctx.remote.models.list` 取得生成 declaration 后，再沿 `typert.remote-client.d.ts.map` 跳到 Host Service 的 `remoteExportList` 远程出口。该出口继续显式调用不改名的存量 `list()`，map 不把 decorator、class 或整个签名误当成方法定义位置。
 
-TypeRT 为同一 symbol key 生成 wire Zod codec。Host Gateway 用它校验输入和编码结果，Client API 可以用它编码参数并校验响应；复杂类型无法生成严格 codec 时，LIB 构建失败，不降级为 `unknown` 或无校验 JSON。
+TypeRT 为同一 symbol key 生成 wire Zod codec。Host Gateway 用它校验输入和编码结果，Client Remote 用它编码参数并校验响应；复杂类型无法生成严格 codec 时，LIB 构建失败，不降级为 `unknown` 或无校验 JSON。
 
 Remote 方法引用的命名业务类型必须从纯类型公共 subpath 导出。如果唯一可达入口会带入 Host Service、Cordis `Context` merge 或 Host-only 实现，构建失败并要求业务包提供安全的类型出口。原始值、字面量和 TypeRT 明确支持的简单组合不需要额外命名。
 
@@ -238,7 +238,7 @@ import goalsRemote from '@deepseek-ai/dsh-goal/remote'
 
 业务 package 的发布文件必须同时包含 `lib/typert.remote-client.d.ts.map` 和 map 指向的 `src` 文件。生成 DTS 以 `//# sourceMappingURL=typert.remote-client.d.ts.map` 引用相邻 map；map 中的 source 从 `lib` 相对指向业务源码，例如 `../src/index.ts`。`/remote` export 不单独列出 map，package `files` 负责把它与源码一起发布。
 
-仅需要静态类型时可以使用 `import type {} from '@deepseek-ai/dsh-goal/remote'`；这种 import 在运行时会被擦除，不会加载 JS，也不能触发任何运行时注册。需要真实调用的环境必须把普通 value import 得到的 contribution 交给 API Service。
+仅需要静态类型时可以使用 `import type {} from '@deepseek-ai/dsh-goal/remote'`；这种 import 在运行时会被擦除，不会加载 JS，也不能触发任何运行时注册。需要真实调用的环境必须把普通 value import 得到的 contribution 交给 Client Remote Service。
 
 workspace 对 `/remote` 的解析必须明确指向 `lib` 生成物，不能被通用 package-to-`src` paths 规则带回 Host 源码。普通业务 import 仍可按各环境既有规则解析到 SRC 或 LIB。
 
@@ -275,18 +275,18 @@ interface TypeRTRemoteContextMap {
 }
 ```
 
-`TypeRTRemoteMap` 保留规范 endpoint 签名，供协议类型和反射使用。根 API 类型直接读取 `TypeRTRemoteNamespaceMap`，不通过 key-remapped mapped type 间接推导方法；TypeScript Language Service 无法把这种间接属性稳定导航到 declaration map。namespace interface 名由 namespace 的 UTF-8 bytes 编成 hex，`goals` 因而稳定得到 `TypeRTRemoteNamespace$676f616c73`。不同 package 对同一 namespace 生成同名 interface，依靠 module augmentation 合并各自方法，且 `TypeRTRemoteNamespaceMap.goals` 始终引用同一类型。
+`TypeRTRemoteMap` 保留规范 endpoint 签名，供协议类型和反射使用。根 Remote 类型直接读取 `TypeRTRemoteNamespaceMap`，不通过 key-remapped mapped type 间接推导方法；TypeScript Language Service 无法把这种间接属性稳定导航到 declaration map。namespace interface 名由 namespace 的 UTF-8 bytes 编成 hex，`goals` 因而稳定得到 `TypeRTRemoteNamespace$676f616c73`。不同 package 对同一 namespace 生成同名 interface，依靠 module augmentation 合并各自方法，且 `TypeRTRemoteNamespaceMap.goals` 始终引用同一类型。
 
 TypeRT 把 `TypeRTRemoteContextMap` 按 Context key 投影到专用 Scope 类型。最终编程界面保持：
 
 ```text
-api.goals.create(agentId, request)
-agent.goals.create(request)
+ctx.remote.goals.create(agentId, request)
+agentCtx.remote.goals.create(request)
 ```
 
-Agent Scope 自动提供自己的 `SessionId`。因此带 `agent` lookup 的 `@Remote` 方法可以同时生成 root 和 scoped 两种消费端签名；`@RemoteContext('agent')` 方法也省略独立的 Context identity，但只生成 scoped 签名。本期只有 Client Agent Context 获得 `goals`，Root Context 不获得该属性；未来 TUI 复用时必须维持相同的 Scope 限制。
+Agent Scope 自动提供自己的 `SessionId`。因此带 `agent` lookup 的 `@Remote` 方法可以同时生成 root 和 scoped 两种消费端签名；`@RemoteContext('agent')` 方法也省略独立的 Context identity，但只生成 scoped 签名。根 `Context` 通过 `ctx.remote` 暴露 direct namespace，`AgentContext.remote` 则把该 direct surface 与 scoped surface 取交集。未来 TUI 复用时必须维持相同区分。
 
-`RemoteApi` 保持平台无关，Browser Client 把它作为自己的 `ClientApi`。未来 TUI 若复用该类型，也必须通过专用 API 对象和 Agent Scope 使用它，不能把 Host `Context` 当成更宽的 Service 集合；未标记的 public Service 方法不会进入 Remote maps。
+`TypeRTClientRemote` 保持平台无关，Browser Client 通过 `ctx.remote` 暴露它。未来 TUI 若复用该类型，也必须通过专用 Remote 对象和 Agent Scope 使用它，不能把 Host `Context` 当成更宽的 Service 集合；未标记的 public Service 方法不会进入 Remote maps。
 
 ## Client TypeRT 与 API Gateway Client face
 
@@ -303,39 +303,39 @@ TypeRT.remotes  已导入的 Remote contribution
 import goalsRemote from '@deepseek-ai/dsh-goal/remote'
 import sessionsRemote from '@deepseek-ai/dsh-session/remote'
 
-ctx.api.mount(goalsRemote)
-ctx.api.mount(sessionsRemote)
+await ctx.remote.$mount(goalsRemote)
+await ctx.remote.$mount(sessionsRemote)
 ```
 
-Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientApi` 契约和 Cordis `ctx.api` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
+Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientRemote` 契约和 Cordis `ctx.remote` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
 
-`ctx.api.mount()` 把 contribution 注册到 `TypeRT.remotes`，并由调用该方法的 Cordis fiber 持有 disposer。endpoint 重复、同一 namespace/method 模式冲突或 descriptor 与现有类型身份冲突时直接失败。
+`ctx.remote.$mount()` 把 contribution 注册到 `TypeRT.remotes`，安装它的 namespace Service 和具体方法，并在它们就绪后才 resolve。调用该方法的 Cordis fiber 持有 disposer。endpoint 重复、同一 namespace/method 模式冲突或 descriptor 与现有类型身份冲突时直接失败。
 
-API Service 把 `@Remote` descriptor 实体化为根 `api` 上的真实函数。函数按 descriptor 的位置参数顺序构造具名 `args`，执行 Client strict codec，然后调用 `ctx.connection.rpc.call('/api', endpoint, { args }, signal)`。对于支持取消的 descriptor，生成的函数接受最后一个可选 signal，并将其与 contribution 的挂载生命周期合并；因此卸载会取消所有正在进行的 carrier 调用，而调用方也可以单独取消一次调用。
+Client Remote Service 把 `@Remote` descriptor 实体化为 `remote.<namespace>` 子 Service 上的真实函数。函数按 descriptor 的位置参数顺序构造具名 `args`，执行 Client strict codec，然后调用 `ctx.connection.rpc.call('/api', endpoint, { args }, signal)`。对于支持取消的 descriptor，生成的函数接受最后一个可选 signal，并将其与 contribution 的挂载生命周期合并；因此卸载会取消所有正在进行的 carrier 调用，而调用方也可以单独取消一次调用。
 
-带 `scope` 的 direct descriptor 和 `@RemoteContext` descriptor 都不为每个 Agent Scope 复制函数。API Service 为每个 scoped namespace 建立一个 root singleton Cordis Service，并在该 Service 上实体化方法；Cordis tracker 在 `agent.goals.create()` 调用时把 Service 的 `this.ctx` rebind 到当前 Agent Context。方法再通过对应 Context binder 从 `this.ctx` 取得 identity。direct scoped 投影用 identity 替代 `scope.wire` 指定的 lookup 位置，Context descriptor 则把 identity 写入 receiver 的独立 wire 字段；两者都发起同一种 `/api` 调用。
+带 `scope` 的 direct descriptor 和 `@RemoteContext` descriptor 都不为每个 Agent Scope 复制函数。Client Remote Service 为每个 namespace 创建一个注册为 `remote.<namespace>` 的 Cordis 子 Service，并在其上实体化 direct 与 scoped 变体。通过 `agentCtx.remote.goals` 取得方法时，accessor 会在返回可调用句柄前捕获当前 Agent Context。方法再通过对应 Context binder 从该 Context 取得 identity。direct scoped 投影用 identity 替代 `scope.wire` 指定的 lookup 位置，Context descriptor 则把 identity 写入 receiver 的独立 wire 字段；两者都发起同一种 `/api` 调用。
 
 ```text
-root ctx.api.goals.create(agentId, request)
+root ctx.remote.goals.create(agentId, request)
   → direct descriptor
   → ctx.connection.rpc.call('/api', 'goals/create', { args })
 
-agent.goals.create(request)
-  → tracker 将 namespace Service rebind 到 agent Context
+agentCtx.remote.goals.create(request)
+  → remote.goals accessor 捕获 agent Context
   → agent binder 从 caller Context 取得 agentId
   → 用 agentId 补入同一 direct descriptor 的 lookup 参数
   → ctx.connection.rpc.call('/api', 'goals/create', { args })
 ```
 
-Root `Context` 不 merge scoped `goals` 类型；只有 `AgentContext` 通过 `RemoteContextApi<'agent'>` 获得该属性。若调用方绕过类型从 Root 动态调用 scoped 方法，binder 明确报错。若 Client 已有同名 Cordis service，或两个 contribution 冲突占用同一 namespace/method，mount 直接失败，不覆盖现有服务。
+根 `Context` 只 merge direct `TypeRTClientRemote` surface；`AgentContext` 把该属性替换为 `TypeRTClientRemote` 与 `TypeRTRemoteContextApi<'agent'>` 的交叉，因而 scoped-only 方法不会暴露给 root 代码。若调用方绕过类型从 Root 动态调用 scoped-only 方法，binder 明确报错。若 Client 已有名为 `remote.<namespace>` 的 Cordis service，或两个 contribution 冲突占用同一 namespace/method，mount 直接失败，不覆盖现有服务。
 
-生成的 Remote JS 只包含 descriptor、symbol key 和 codec，不打包 Host Service 实现。API Service 据此创建真实函数，因此运行时不依赖 JavaScript Proxy；Proxy 可以作为实现选择，但不会成为类型或反射来源。
+生成的 Remote JS 只包含 descriptor、symbol key 和 codec，不打包 Host Service 实现。Client Remote Service 据此创建真实函数，因此运行时不依赖 JavaScript Proxy；Proxy 可以作为实现选择，但不会成为类型或反射来源。
 
 ## 跨环境同构约束
 
 Remote API 是消费端能力，不等同于 Browser API。已交付的运行时实现 Browser Client contribution 挂载、Connection RPC 调用和 Agent Scope 关联。
 
-Remote DTS、Remote JS、`RemoteApi`、`InvocationDescriptor`、Remote RPC 数据协议和 Context binder 不得依赖 DOM、Browser module loader 或 HTTP。Browser Client 通过 Connection 把 descriptor 实体化的方法编码为 `/api` RPC 调用。
+Remote DTS、Remote JS、`TypeRTClientRemote`、`InvocationDescriptor`、Remote RPC 数据协议和 Context binder 不得依赖 DOM、Browser module loader 或 HTTP。Browser Client 通过 Connection 把 descriptor 实体化的方法编码为 `/api` RPC 调用。
 
 未来 TUI 可以在不改变业务 decorator、Remote maps 和 API 调用形状的前提下接入同一调用抽象。届时 TUI 可见的 API 仍只能由 `@Remote` 和 `@RemoteContext` 生成，不能因为它与 Host 同进程就绕过 Remote 限制直接暴露 Service 方法。
 
@@ -421,7 +421,7 @@ Remote payload 使用具名 JSON 对象，不使用位置数组，也不发送 `
 完整链路为：
 
 ```text
-ctx.api.goals.create(sessionId, request, signal?)
+ctx.remote.goals.create(sessionId, request, signal?)
 → Client InvocationDescriptor 编码 { args: { agentId, request } }
 → Client 合并 caller signal 与 contribution mount lifetime
 → ctx.connection.rpc.call('/api', 'goals/create', { args }, signal)
@@ -442,7 +442,7 @@ Gateway 不处理逐方法权限、调用者身份、幂等或长连接状态。
 
 ## Connection 与协议边界
 
-API Service 负责 Remote contribution、方法实体化、Scope 绑定以及位置参数与 descriptor 的对应。Gateway 负责 Host descriptor、endpoint ownership、lookup、Context 和业务调用。Connection 把 `/api`、endpoint 和 `{ args }` 作为一个 RPC 调用发送到目标并返回既有 RPC result；它不理解 Goal、Agent、lookup、descriptor 或 Client API 类型。
+Client Remote Service 负责 Remote contribution、namespace Service 实体化、Scope 绑定以及位置参数与 descriptor 的对应。Gateway 负责 Host descriptor、endpoint ownership、lookup、Context 和业务调用。Connection 把 `/api`、endpoint 和 `{ args }` 作为一个 RPC 调用发送到目标并返回既有 RPC result；它不理解 Goal、Agent、lookup、descriptor 或 Client Remote 类型。
 
 Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 HTTP route。Connection 把共享 `/api` route 挂到 HTTP Server，并把一个复合 FetchHandler 交给 bridge；该 handler 将已认领 endpoint 分发给 Gateway，未认领 endpoint 则交给 API Proxy。未来 Connection transport 可以保留相同顺序，而不改变 Remote payload、业务 decorator、生成的 DTS、Remote API 类型或 Agent Scope 编程界面。
 
@@ -451,8 +451,8 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 - `@deepseek-ai/dsh-type-meta`：轻量 decorator、binding、lookup、Remote Context 和 descriptor 协议。
 - TypeRT generator：分析 Host/Client Program，生成本地 face 和 Remote 消费端投影，并生成规范 symbol/Zod 信息。
 - TypeRT runtime：分别保存当前环境的 local reflection 与导入的 Remote contribution。
-- `@deepseek-ai/dsh-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 API 方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
-- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientApi` 契约向业务包暴露合并后的 API 类型。
+- `@deepseek-ai/dsh-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 Remote namespace Service 和方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
+- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientRemote` 契约向业务包暴露合并后的 Remote 类型。
 - Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、共享 `/api` route 与复合 FetchHandler、API Proxy 回退、RPC envelope、rpcId、序列化、trust 和错误传输。
 - Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
 - API Proxy Host 组合：向 API Remotes 提供 Web Agent 默认值和 scope 设置，并让旧方法使用同一个 `agentFor()`。
@@ -460,7 +460,7 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 
 ## 已交付范围与后续工作
 
-已交付的纵向链路是 `@deepseek-ai/dsh-goal/remote → Browser Client API → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`。同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.api.goals.create(agentId, request)` 与 `agentCtx.goals.create(request)`。普通冷会话在 lookup 时通过 `agentFor()` 恢复，subagent-owned identity 保持既有 `agent-busy` fence；`@RemoteContext('agent')` 仍是独立的 scoped receiver 模式。
+已交付的纵向链路是 `@deepseek-ai/dsh-goal/remote → Browser Client Remote → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`。同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.remote.goals.create(agentId, request)` 与 `agentCtx.remote.goals.create(request)`。普通冷会话在 lookup 时通过 `agentFor()` 恢复，subagent-owned identity 保持既有 `agent-busy` fence；`@RemoteContext('agent')` 仍是独立的 scoped receiver 模式。
 
 Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebSocket 迁移、TUI runtime 与 carrier、TUI Agent Scope 接线、Permission/Approval 状态机、Session 事件流、调用授权、重试、幂等及跨版本协议兼容均不属于本决策。
 
@@ -482,7 +482,7 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 **只生成 Remote DTS，不生成 JS。** 类型可以成立，但运行时无法枚举 endpoint、codec 和 Context 模式，只能依赖 Proxy 或另一份手写注册表，因此同一次 Host 投影同时生成 Remote JS contribution。
 
-**让 `/remote` 的顶层 import 偷偷注册全局状态。** ESM 求值时未必已有目标 Cordis Context，多个 Context、HMR 和 dispose 也无法明确归属，因此普通 value import 只返回 contribution，由环境 assembly 的 API Service 显式挂载。
+**让 `/remote` 的顶层 import 偷偷注册全局状态。** ESM 求值时未必已有目标 Cordis Context，多个 Context、HMR 和 dispose 也无法明确归属，因此普通 value import 只返回 contribution，由环境 assembly 的 Client Remote Service 显式挂载。
 
 **为 Remote 新建独立 transport、HTTP route 或 `/api2` channel。** 这会复制或拆分 Connection 的 Server ownership、rpcId、序列化、trust、错误和未来 WebSocket 生命周期。共享 `/api` interceptor 保留唯一物理 route，并让 Connection 继续以 API Proxy 作为回退 FetchHandler。
 
@@ -490,7 +490,7 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 - Goal Service 直接装饰业务签名已经符合 Remote 契约的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
 - 一次干净的 `build:lib` 会在 Client 编译前生成 Host 与消费方 Remote 产物，包括业务包 `/remote` 下的 JS、DTS 和 declaration map。
-- 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `api.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
+- 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `ctx.remote.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
 - 挂载同一次 import 得到的 JS contribution 会提供 endpoint、参数、结果、lookup、Context 和 Zod 反射，并在无需手写 stub 的情况下实体化调用。
 - Root 与 Agent-scoped 调用会经过真实的共享 `/api` carrier，将 `agentId` 解析为活 Agent，调用原始 Goal receiver，并通过既有 RPC envelope 返回。
 - Agent 与 Session lookup 会共享同一次并发冷恢复；普通冷会话得到恢复后的对象，冷态或 live subagent identity 均在业务调用前返回 `agent-busy`。
@@ -509,13 +509,13 @@ SRC 弱 descriptor 不验证普通 JSON 内部结构。Host Remote 签名变化
 
 公共类型唯一性要求业务 DTO 具有纯类型出口，可能暴露现有包中 Host 类型与实现入口混杂的问题。构建会拒绝这些边界，而不是复制类型掩盖问题。
 
-类型 import 与运行时 contribution 是两种不同效果。`import type {}` 只扩展静态 API；真实调用环境遗漏 value contribution 时，API Service 必须以明确的“Remote 未挂载”错误失败。
+类型 import 与运行时 contribution 是两种不同效果。`import type {}` 只扩展静态 Remote surface；真实调用环境遗漏 value contribution 时，Client Remote Service 必须以明确的“Remote 未挂载”错误失败。
 
 Browser 与 Host 各自持有 Zod 实例，不能依赖对象 identity 跨 realm 比较；一致性只由规范 symbol key、同一生成模型和 wire 行为保证。
 
 消费端可以导入 Host 当前未挂载的 Remote contract。类型表示“该协议能力已被消费端选择”，不保证目标进程当前存在对应 Service；运行时 endpoint 不可用必须明确失败。
 
-Connection 的通用 channel API 必须同时适合当前 HTTP carrier 和后续 WebSocket carrier。若接口把 `fetch`、HTTP request 或 route handle 暴露给 Gateway/API Service，WebSocket 迁移会再次穿透 Remote 层，因此这些物理对象必须留在 Connection 内部。
+Connection 的通用 channel API 必须同时适合当前 HTTP carrier 和后续 WebSocket carrier。若 Client Remote 或 Gateway 暴露 `fetch`、HTTP request 或 route handle，WebSocket 迁移会再次穿透 Remote 层，因此这些物理对象必须留在 Connection 内部。
 
 Remote endpoint 使用 Connection 的 `trusted-host` authority。系统默认接受 loopback；LAN 调用方必须通过显式 trusted-host 配置接入，但本层不增加逐方法调用方授权，因此每个 trusted host 都能调用已挂载的 Remote endpoint。
 
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index 05038eb8b9..d07272c182 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.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 docs/api-gateway.md
-api-gateway.md: 090758d58306d5ea806567f0de710a1c1f5ed747
-api-gateway.zh.md: 9d7286b6b86918f3bc1e7a6cdd9bdf04447abc57
+api-gateway.md: 90aa661cc86a4f419e173560c55511c969182990
+api-gateway.zh.md: 6fcbb562b204e71d00833042ee0632bda0217940
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index 090758d583..90aa661cc8 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -6,7 +6,7 @@ This is the current-state reference for the TypeRT API Gateway. It describes how
 
 ## Programming model
 
-Business services use `@Remote` or `@RemoteContext` to select the methods exposed to the Client. Unmarked methods do not enter the generated Client types or runtime contributions and cannot be called through `ctx.api`.
+Business services use `@Remote` or `@RemoteContext` to select the methods exposed to the Client. Unmarked methods do not enter the generated Client types or runtime contributions and cannot be called through `ctx.remote`.
 
 `@Remote` denotes calling a Cordis service registered on the root Host Context. Complex Host objects cannot cross the wire directly; the business package must declare their association with a wire identity through `TypeRTLookupMap` and register a default resolution provider with `ctx.typert.lookups` at runtime. For example, an `Agent` parameter named `agent` in the Host signature produces an `agentId` wire field, and the Gateway resolves that id to a Host object before invoking the business method. Host composition can use `ctx.typert.lookups.configure()` to override the resolution policy for a lookup key without changing the parameter name, wire field, or canonical type symbol owned by the business package.
 
@@ -55,7 +55,7 @@ export class GoalService extends GatewayService {
 
 Remote methods may return a value synchronously or return a Promise. For cooperative cancellation, the final parameter in the Host signature must be `signal: AbortSignal` using the global type; it is recorded in the descriptor instead of entering `args`, while the generated Client method accepts an optional final `AbortSignal`.
 
-The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct Remotes appear under `ctx.api.<namespace>`; when an `@Remote` method has exactly one lookup parameter and a same-named `TypeRTContextMap` uses the same wire identity, the generator also projects the method without that identity parameter onto the corresponding scoped Context. `@RemoteContext` generates only the scoped invocation interface.
+The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct and scoped calls appear under `ctx.remote.<namespace>` and `agentCtx.remote.<namespace>`. Each namespace is a traced Cordis child Service registered as `remote.<namespace>`; the Client assembly mounts contributions through `ctx.remote.$mount()`, consumers inject both `remote` and the namespace Service they call, and the namespace unloads after its last method is withdrawn. When an `@Remote` method has exactly one lookup parameter and a same-named `TypeRTContextMap` uses the same wire identity, the generated scoped signature omits that identity parameter. `@RemoteContext` generates only the scoped invocation interface.
 
 ```ts
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -67,13 +67,13 @@ declare const ctx: Context
 declare const agentCtx: AgentContext
 declare const agentId: SessionId
 
-await ctx.api.goals.create(agentId, { objective: 'ship it' })
-await agentCtx.goals.create({ objective: 'ship it' })
+await ctx.remote.goals.create(agentId, { objective: 'ship it' })
+await agentCtx.remote.goals.create({ objective: 'ship it' })
 ```
 
-Client applications assemble only `@deepseek-ai/dsh-api-remotes`. That package imports the `/remote` subpaths of selected business packages as runtime values, mounts their contributions on `ctx.api`, and re-exports the declaration merges from the same files. Adding a Host Remote package is an explicit choice by the Client composition owner; business components do not need to load the TypeRT Gateway or the business package's Remote JS separately.
+Client applications assemble only `@deepseek-ai/dsh-api-remotes`. That package imports the `/remote` subpaths of selected business packages as runtime values, mounts their contributions through `ctx.remote.$mount()`, and re-exports the declaration merges from the same files. Adding a Host Remote package is an explicit choice by the Client composition owner; business components do not need to load the TypeRT Gateway or the business package's Remote JS separately.
 
-A future TUI can assemble the same React-independent `api-remotes` and `ctx.api` contract, so the Host methods visible to it are likewise limited to the Remote methods selected at generation time. This document does not define or implement the TUI composition.
+A future TUI can assemble the same React-independent `api-remotes` and `ctx.remote` contract, so the Host methods visible to it are likewise limited to the Remote methods selected at generation time. This document does not define or implement the TUI composition.
 
 ## Component responsibilities
 
@@ -84,11 +84,11 @@ A future TUI can assemble the same React-independent `api-remotes` and `ctx.api`
 | Host | `@deepseek-ai/dsh-typert-registry` and Loader | Places generated Host descriptors, schemas, and business-package registrations in `ctx.typert`, and holds lookup and Context providers |
 | Host | `@deepseek-ai/dsh-api-remotes` | Owns the application Agent/Session identity policy and configures the corresponding TypeRT lookups |
 | Host | `@deepseek-ai/dsh-api-gateway` | Provides `ctx.typertGateway`, claims Remote endpoints, resolves objects or Contexts, invokes live Cordis services, and validates boundaries |
-| Client | `@deepseek-ai/dsh-api-gateway/client` | Provides `ctx.api`, mounts generated descriptors as concrete methods, and initiates, validates, and cancels calls through the Connection |
+| Client | `@deepseek-ai/dsh-api-gateway/client` | Provides `ctx.remote` and `remote.<namespace>` child Services, mounts generated descriptors as concrete methods, and initiates, validates, and cancels calls through the Connection |
 | Client | `@deepseek-ai/dsh-api-remotes/client` | Explicitly selects and mounts the `/remote` contributions allowed by the application and brings the corresponding declaration merges into business code |
 | Both | `@deepseek-ai/dsh-client-connection` | Provides the RPC carrier, request correlation, trust boundary, cancellation, response envelope, and current `/api` HTTP bridge |
 
-The API Gateway package owns the Host dispatcher and Client API as peer entries, but the two builds never enter the same `ts.Program`. The Host entry does not import the Client Cordis `Context` merge, and the Client entry does not import the Host Gateway service.
+The API Gateway package owns the Host dispatcher and Client Remote endpoint as peer entries, but the two builds never enter the same `ts.Program`. The Host entry does not import the Client Cordis `Context` merge, and the Client entry does not import the Host Gateway service.
 
 ## Strict generation pipeline
 
@@ -106,13 +106,13 @@ Each contributing business package writes generated files to its own `lib/` dire
 
 Business packages expose the Host Loader entry through `./typert` and the Host-for-Client entry through `./remote`. The generator also validates these package exports and published-file lists; it generates artifacts only for explicit contribution packages that provide the corresponding entry.
 
-Parameter names in Remote Client declarations come from wire fields, while parameter and return types reference Client-safe types exported by the original business package. The declaration map resolves the generated property behind `ctx.api.goals.create` back to the Host source method marked with `@Remote`, so editors that support declaration maps can navigate from a Client call to the real implementation instead of stopping at the generated `.d.ts`.
+Parameter names in Remote Client declarations come from wire fields, while parameter and return types reference Client-safe types exported by the original business package. The declaration map resolves the generated property behind `ctx.remote.goals.create` back to the Host source method marked with `@Remote`, so editors that support declaration maps can navigate from a Client call to the real implementation instead of stopping at the generated `.d.ts`.
 
 Strict analysis requires a Remote to be a public, non-static instance method with a concrete implementation. The method cannot be generic; parameters must be required, named simple identifiers and cannot use destructuring, default values, rest parameters, or optional parameters. TypeRT generates strict schemas for ordinary JSON-representable types; complex objects such as workspace classes must have a unique `TypeRTLookupMap` declaration. Lookup and Context packages are responsible for both static declaration merges and runtime provider registration; if either side is missing, the build or earliest resolvable runtime boundary fails.
 
 ## Runtime invocation
 
-Remote and API Proxy currently share the Connection's `/api` route; there is no separate `/api2` server or second Connection. The Client API calls `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`; the current HTTP carrier maps this to `POST /api/<namespace>/<method>`, with a payload containing only a named `args` object.
+Remote and API Proxy currently share the Connection's `/api` route; there is no separate `/api2` server or second Connection. The Client Remote calls `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`; the current HTTP carrier maps this to `POST /api/<namespace>/<method>`, with a payload containing only a named `args` object.
 
 The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler in interceptor order. The TypeRT Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; unclaimed requests fall back to the existing API Proxy. The Connection owns transport, RPC ids, response envelopes, and request cancellation, while the Gateway owns only the Remote data protocol and business dispatch. Replacing the Connection carrier in the future does not require changes to Remote descriptors or the Client programming interface.
 
@@ -128,7 +128,7 @@ When the Host starts from source through `node --import tsx/esm`, it does not ex
 
 The SRC fallback parses simple parameter names from the live function. When a parameter name matches the `parameter` of a registered lookup, such as `agent` or `session`, it uses the lookup's `agentId` or `sessionId` wire field and resolves the object on the Host; other parameters are checked only for cycle-free, JSON-safe data with no special prototype. `@RemoteContext` directly uses the wire field of a registered Host Context provider. SRC does not read TypeScript types, generate Zod schemas, infer optional parameters, or support destructuring, default values, rest parameters, or duplicate parameter names.
 
-SRC solves only dispatch for a Host process running from source. The Client does not discover decorators from the running Host, and the Client API refuses to mount SRC descriptors that lack strict codecs; its types, codecs, and Remote registration values always come from the most recently generated `lib/typert.remote-client.*` artifacts.
+SRC solves only dispatch for a Host process running from source. The Client does not discover decorators from the running Host, and the Client Remote refuses to mount SRC descriptors that lack strict codecs; its types, codecs, and Remote registration values always come from the most recently generated `lib/typert.remote-client.*` artifacts.
 
 ## Development mode
 
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 9d7286b6b8..6fcbb562b2 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -6,7 +6,7 @@
 
 ## 编程模型
 
-业务 Service 通过 `@Remote` 或 `@RemoteContext` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.api` 调用。
+业务 Service 通过 `@Remote` 或 `@RemoteContext` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.remote` 调用。
 
 `@Remote` 表示调用根 Host Context 中注册的 Cordis Service。复杂的 Host 对象不能直接跨 wire 传输；业务包必须通过 `TypeRTLookupMap` 声明它与 wire identity 的关联，并在运行时向 `ctx.typert.lookups` 注册默认解析提供方。例如 `Agent` 参数在 Host 签名中名为 `agent`，生成的 wire 字段为 `agentId`，Gateway 在调用业务方法前将 id 解析为 Host 对象。Host 组合可以用 `ctx.typert.lookups.configure()` 覆盖某个 lookup key 的解析策略，而不改变业务包拥有的参数名、wire 字段或规范类型 symbol。
 
@@ -55,7 +55,7 @@ export class GoalService extends GatewayService {
 
 Remote 方法可以同步返回或返回 Promise。若需要协作式取消，Host 签名的最后一个参数必须是全局类型的 `signal: AbortSignal`；它记录在描述符中而不是进入 `args`，Client 生成的方法则接受最后一个可选的 `AbortSignal`。
 
-Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接 Remote 出现在 `ctx.api.<namespace>`；当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成器还会把去掉该 identity 参数后的方法投影到对应作用域 Context。`@RemoteContext` 只生成作用域调用界面。
+Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子 Service；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，消费方同时注入 `remote` 与所调用的 namespace Service，最后一个方法撤回后该 namespace 随即卸载。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteContext` 只生成作用域调用界面。
 
 ```ts
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -67,13 +67,13 @@ declare const ctx: Context
 declare const agentCtx: AgentContext
 declare const agentId: SessionId
 
-await ctx.api.goals.create(agentId, { objective: 'ship it' })
-await agentCtx.goals.create({ objective: 'ship it' })
+await ctx.remote.goals.create(agentId, { objective: 'ship it' })
+await agentCtx.remote.goals.create({ objective: 'ship it' })
 ```
 
-Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，并向 `ctx.api` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 TypeRT Gateway 或业务包的 Remote JS。
+Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，通过 `ctx.remote.$mount()` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 TypeRT Gateway 或业务包的 Remote JS。
 
-未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.api` 契约，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
+未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 契约，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
 
 ## 组件职责
 
@@ -84,11 +84,11 @@ Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导
 | Host | `@deepseek-ai/dsh-typert-registry` 与 Loader | 把生成的 Host 描述符、schema 及业务包注册项放入 `ctx.typert`，并持有 lookup 与 Context 提供方 |
 | Host | `@deepseek-ai/dsh-api-remotes` | 负责应用的 Agent/Session 身份策略，并配置对应的 TypeRT lookup |
 | Host | `@deepseek-ai/dsh-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或 Context，调用实时 Cordis Service 并校验边界 |
-| Client | `@deepseek-ai/dsh-api-gateway/client` | 提供 `ctx.api`，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
+| Client | `@deepseek-ai/dsh-api-gateway/client` | 提供 `ctx.remote` 与 `remote.<namespace>` 子 Service，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
 | Client | `@deepseek-ai/dsh-api-remotes/client` | 显式选择并挂载本应用允许使用的 `/remote` 贡献，向业务代码带入对应的声明合并 |
 | 双侧 | `@deepseek-ai/dsh-client-connection` | 提供 RPC carrier、请求关联、信任边界、取消、响应 envelope 与当前 `/api` HTTP bridge |
 
-API Gateway 包同时拥有 Host dispatcher 与 Client API 两个对等入口，但两侧构建不会进入同一个 `ts.Program`。Host 入口不导入 Client 的 Cordis `Context` 合并，Client 入口也不导入 Host Gateway 服务。
+API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对等入口，但两侧构建不会进入同一个 `ts.Program`。Host 入口不导入 Client 的 Cordis `Context` 合并，Client 入口也不导入 Host Gateway 服务。
 
 ## 严格生成链路
 
@@ -106,13 +106,13 @@ API Gateway 包同时拥有 Host dispatcher 与 Client API 两个对等入口，
 
 业务包通过 `./typert` 暴露 Host Loader 入口，通过 `./remote` 暴露 Host-for-Client 入口。生成器同时校验这些 package export 及发布文件清单；只有具备相应入口的显式贡献包才会生成产物。
 
-Remote Client 声明中的参数名来自 wire 字段，参数和返回类型则引用原业务包导出的 Client-safe 类型。声明 map 把 `ctx.api.goals.create` 最终解析到的生成属性映射到带 `@Remote` 的 Host 源方法，因此支持 declaration-map 的编辑器可以从 Client 调用跳到真实实现，而不是停在生成的 `.d.ts`。
+Remote Client 声明中的参数名来自 wire 字段，参数和返回类型则引用原业务包导出的 Client-safe 类型。声明 map 把 `ctx.remote.goals.create` 最终解析到的生成属性映射到带 `@Remote` 的 Host 源方法，因此支持 declaration-map 的编辑器可以从 Client 调用跳到真实实现，而不是停在生成的 `.d.ts`。
 
 严格分析要求 Remote 是公开、非静态、有具体实现的实例方法。方法不能是泛型；参数必须是具名且必填的简单标识符，不能使用解构、默认值、rest 或可选参数。可 JSON 表示的普通类型由 TypeRT 生成严格 schema；工作区 class 等复杂对象必须具有唯一的 `TypeRTLookupMap` 声明。lookup 与 Context 包同时负责静态声明合并和运行时提供方注册，缺少任一侧都会在构建或最早可解析的运行时边界报错。
 
 ## 运行时调用
 
-当前 Remote 与 API Proxy 共用 Connection 的 `/api` 路由，不存在独立 `/api2` server 或第二套 Connection。Client API 调用 `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`；当前 HTTP carrier 对应 `POST /api/<namespace>/<method>`，payload 只包含一个具名 `args` 对象。
+当前 Remote 与 API Proxy 共用 Connection 的 `/api` 路由，不存在独立 `/api2` server 或第二套 Connection。Client Remote 调用 `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`；当前 HTTP carrier 对应 `POST /api/<namespace>/<method>`，payload 只包含一个具名 `args` 对象。
 
 Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内按 interceptor 顺序分发。TypeRT Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；未认领的请求回退到既有 API Proxy。Connection 拥有传输、RPC id、响应 envelope 和 request cancellation，Gateway 只拥有 Remote 数据协议和业务分发。未来替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程界面。
 
@@ -128,7 +128,7 @@ Host 通过 `node --import tsx/esm` 从源码启动时不会执行 TypeRT 编译
 
 SRC 回退从运行中函数解析简单参数名。参数名与某个已注册 lookup 的 `parameter` 相同，例如 `agent` 或 `session`，就使用其 `agentId` 或 `sessionId` wire 字段并在 Host 解析对象；其他参数只检查值是否为无循环、无特殊 prototype 的 JSON-safe 数据。`@RemoteContext` 直接使用已注册 Host Context provider 的 wire 字段。SRC 不读取 TypeScript 类型，不生成 Zod schema，不推断可选参数，也不支持解构、默认值、rest 或重复参数名。
 
-SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Host 发现 decorator，Client API 也拒绝挂载缺少严格 codec 的 SRC 描述符；其类型、codec 和 Remote 注册值始终来自最近一次生成的 `lib/typert.remote-client.*`。
+SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Host 发现 decorator，Client Remote 也拒绝挂载缺少严格 codec 的 SRC 描述符；其类型、codec 和 Remote 注册值始终来自最近一次生成的 `lib/typert.remote-client.*`。
 
 ## 开发模式
 
diff --git a/docs/core-data-structures/typert.i18n.yaml b/docs/core-data-structures/typert.i18n.yaml
index a6e1eb5415..75b7837687 100644
--- a/docs/core-data-structures/typert.i18n.yaml
+++ b/docs/core-data-structures/typert.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 docs/core-data-structures/typert.md
-typert.md: a61ed8587833e03fd5c1246311e62a6ffaeb3bd0
-typert.zh.md: 18c24018f4abd644cf35185c2bd06b6980195481
+typert.md: c70e50e2fea8455eb75dfdf8c309f659ab9cb2f9
+typert.zh.md: 2cd1636d4cc8dbcfa009073b4a8e1dcc8d5897e4
diff --git a/docs/core-data-structures/typert.md b/docs/core-data-structures/typert.md
index a61ed85878..c70e50e2fe 100644
--- a/docs/core-data-structures/typert.md
+++ b/docs/core-data-structures/typert.md
@@ -126,10 +126,10 @@ interface TypeRTService {
 }
 ```
 
-Generated consumer declarations merge direct namespaces into the map inherited by `TypeRTClientApi`.
+Generated consumer declarations merge direct namespaces into the map inherited by `TypeRTClientRemote`.
 
 ```ts type-equiv
-/** Merge-extensible direct namespace surface generated for Client API services. */
+/** Merge-extensible direct namespace surface generated for Client Remote services. */
 interface TypeRTRemoteNamespaceMap {}
 ```
 
@@ -186,18 +186,18 @@ interface TypertGateway {
 }
 ```
 
-## Consumer API
+## Consumer Remote
 
-`ctx.api` exposes only namespaces contributed by imported `/remote` artifacts. Mounting installs the generated descriptors and concrete root/scoped methods as one fiber-owned operation; no JavaScript Proxy or Host Service type enters the consumer.
+`ctx.remote` exposes only namespaces contributed by imported `/remote` artifacts. `$mount()` installs generated descriptors and concrete methods as one fiber-owned operation. Each namespace is a traced `remote.<namespace>` Cordis child Service whose lifetime spans its mounted methods; no JavaScript Proxy or Host business Service type enters the consumer.
 
 ```ts type-equiv
-/** Client API capability implemented by the Gateway and consumed by Remote assemblies. */
-interface TypeRTClientApi extends TypeRTRemoteNamespaceMap {
+/** Client Remote capability implemented by the Gateway and consumed by Remote assemblies. */
+interface TypeRTClientRemote extends TypeRTRemoteNamespaceMap {
   /**
    * Mount one generated Host-for-Client contribution in the caller's fiber.
    * @param contribution - explicitly selected Remote package artifact.
-   * @returns disposer withdrawing descriptors and concrete methods together.
+   * @returns disposer after namespace services and concrete methods are ready.
    */
-  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer
+  $mount(contribution: TypeRTRemoteContribution): Promise<TypeRTDisposer>
 }
 ```
diff --git a/docs/core-data-structures/typert.zh.md b/docs/core-data-structures/typert.zh.md
index 18c24018f4..2cd1636d4c 100644
--- a/docs/core-data-structures/typert.zh.md
+++ b/docs/core-data-structures/typert.zh.md
@@ -126,10 +126,10 @@ interface TypeRTService {
 }
 ```
 
-生成的消费方声明会把 direct namespace 合并到 `TypeRTClientApi` 继承的 map 中。
+生成的消费方声明会把 direct namespace 合并到 `TypeRTClientRemote` 继承的 map 中。
 
 ```ts type-equiv
-/** Merge-extensible direct namespace surface generated for Client API services. */
+/** Merge-extensible direct namespace surface generated for Client Remote services. */
 interface TypeRTRemoteNamespaceMap {}
 ```
 
@@ -186,18 +186,18 @@ interface TypertGateway {
 }
 ```
 
-## 消费方 API
+## 消费方 Remote
 
-`ctx.api` 只暴露由已导入 `/remote` 产物贡献的 namespace。挂载会把生成的 descriptor 与具体的 root/scoped 方法作为一项由 fiber 持有的操作统一注册；JavaScript Proxy 与 Host 服务类型都不会进入消费方。
+`ctx.remote` 只暴露由已导入 `/remote` 产物贡献的 namespace。`$mount()` 会把生成的 descriptor 与具体方法作为一项由 fiber 持有的操作统一注册。每个 namespace 都是可追踪的 `remote.<namespace>` Cordis 子 Service，其生命周期覆盖已挂载的方法；JavaScript Proxy 与 Host 业务 Service 类型都不会进入消费方。
 
 ```ts type-equiv
-/** Client API capability implemented by the Gateway and consumed by Remote assemblies. */
-interface TypeRTClientApi extends TypeRTRemoteNamespaceMap {
+/** Client Remote capability implemented by the Gateway and consumed by Remote assemblies. */
+interface TypeRTClientRemote extends TypeRTRemoteNamespaceMap {
   /**
    * Mount one generated Host-for-Client contribution in the caller's fiber.
    * @param contribution - explicitly selected Remote package artifact.
-   * @returns disposer withdrawing descriptors and concrete methods together.
+   * @returns disposer after namespace services and concrete methods are ready.
    */
-  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer
+  $mount(contribution: TypeRTRemoteContribution): Promise<TypeRTDisposer>
 }
 ```
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index b0809af72e..933f204fa0 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: f832956c4c7cbde96613a69db6c636a2246786a7
-development.zh.md: 3ae70e7135ad5faee0e37d99f55cdb41373aab2c
+development.md: 37bc88c7c1cfedfbe1a93e08a4cbde833ac32372
+development.zh.md: a738e53cb3434d7930aa82107782a4c22aea1470
diff --git a/docs/development.md b/docs/development.md
index f832956c4c..37bc88c7c1 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -62,7 +62,7 @@ Host and client stay two aggregate programs because both sides declaration-merge
 
 Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).
 
-Business services declare callable methods on the Host with `@Remote` or `@RemoteContext`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions and mounts concrete methods on `ctx.api` or the corresponding scoped Context. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
+Business services declare callable methods on the Host with `@Remote` or `@RemoteContext`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
 
 If a relevant local check consumes built package output, build once first:
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 3ae70e7135..a738e53cb3 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -62,7 +62,7 @@ host 与 client 保持两个聚合 program，是因为两侧在相同键下以
 
 静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。
 
-业务 Service 在 Host 使用 `@Remote` 或 `@RemoteContext` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并将具体方法挂载到 `ctx.api` 或对应的作用域 Context。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
+业务 Service 在 Host 使用 `@Remote` 或 `@RemoteContext` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
 
 如果相关的本地检查需要使用构建后的包产物，请先构建一次：
 
diff --git a/packages/api/README.i18n.yaml b/packages/api/README.i18n.yaml
index 855eeb8eaa..6a834cdf4d 100644
--- a/packages/api/README.i18n.yaml
+++ b/packages/api/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/api/README.md
-README.md: 0dcded5922fea1ea6676315029ba0eadd74dd3df
-README.zh.md: 1b9bb9133a955d0cbef0ca91728aab1545831d94
+README.md: 7c75e8012459266e0ce09c97416d140e5ac777e1
+README.zh.md: 87bd15fc4e5ad23ef785f7c9ee805a4aa1a35e46
diff --git a/packages/api/README.md b/packages/api/README.md
index 0dcded5922..7c75e80124 100644
--- a/packages/api/README.md
+++ b/packages/api/README.md
@@ -6,10 +6,10 @@ The application-facing Remote stack. `remotes` owns BFF policy and the selected
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`remotes/`](remotes/README.md) | Host Agent/Session lookup policy and Client Remote contribution assembly | no service; configures `ctx.typert` and consumes `ctx.api` |
-| [`gateway/`](gateway/README.md) | Host TypeRT dispatcher and Client API endpoint | `ctx.typertGateway` / `ctx.api` |
+| [`remotes/`](remotes/README.md) | Host Agent/Session lookup policy and Client Remote contribution assembly | no service; configures `ctx.typert` and consumes `ctx.remote` |
+| [`gateway/`](gateway/README.md) | Host TypeRT dispatcher and Client Remote endpoint | `ctx.typertGateway` / `ctx.remote` |
 
-The runtime dependency direction is `remotes → gateway → connection → webserver`: the BFF consumes the shared `TypeRTClientApi` contract, Gateway delegates transport to Connection, and Connection mounts on the HTTP server. Cordis service injection and Client module metadata preserve this order without importing the concrete Gateway from the Remotes Client entry.
+The runtime dependency direction is `remotes → gateway → connection → webserver`: the BFF consumes the shared `TypeRTClientRemote` contract, Gateway delegates transport to Connection, and Connection mounts on the HTTP server. Cordis service injection and Client module metadata preserve this order without importing the concrete Gateway from the Remotes Client entry.
 
 ## Known Limitations and Deferred Work
 
diff --git a/packages/api/README.zh.md b/packages/api/README.zh.md
index 1b9bb9133a..87bd15fc4e 100644
--- a/packages/api/README.zh.md
+++ b/packages/api/README.zh.md
@@ -6,10 +6,10 @@
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`remotes/`](remotes/README.md) | Host Agent/Session lookup 策略与 Client Remote contribution 装配 | 无服务；配置 `ctx.typert` 并消费 `ctx.api` |
-| [`gateway/`](gateway/README.md) | Host TypeRT 分发器与 Client API endpoint | `ctx.typertGateway` / `ctx.api` |
+| [`remotes/`](remotes/README.md) | Host Agent/Session lookup 策略与 Client Remote contribution 装配 | 无服务；配置 `ctx.typert` 并消费 `ctx.remote` |
+| [`gateway/`](gateway/README.md) | Host TypeRT 分发器与 Client Remote endpoint | `ctx.typertGateway` / `ctx.remote` |
 
-运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientApi` 契约，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
+运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientRemote` 契约，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
 
 ## 已知限制与延期工作
 
diff --git a/packages/api/gateway/README.i18n.yaml b/packages/api/gateway/README.i18n.yaml
index 41bbb0621f..3a9a0ba50d 100644
--- a/packages/api/gateway/README.i18n.yaml
+++ b/packages/api/gateway/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/api/gateway/README.md
-README.md: 9e3d4d89788bbc6edebfc0c0127999fed3ed9261
-README.zh.md: 9bbd46c71185a2fbf8da163565d6c19141c079ca
+README.md: e37359db71c1388667e9e61f538354711e90c0c1
+README.zh.md: 2054febb9a5423297c32b029b40a035062250aab
diff --git a/packages/api/gateway/README.md b/packages/api/gateway/README.md
index 9e3d4d8978..e37359db71 100644
--- a/packages/api/gateway/README.md
+++ b/packages/api/gateway/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Two-sided TypeRT RPC endpoint for Host and Client Cordis environments. The Host entry provides `ctx.typertGateway`, while `@deepseek-ai/dsh-api-gateway/client` provides `ctx.api`; both consume the same generated `InvocationDescriptor` contract and leave business selection to API Remotes and transport, request correlation, trust, and response envelopes to Connection.
+Two-sided TypeRT RPC endpoint for Host and Client Cordis environments. The Host entry provides `ctx.typertGateway`, while `@deepseek-ai/dsh-api-gateway/client` provides `ctx.remote`; both consume the same generated `InvocationDescriptor` contract and leave business selection to API Remotes and transport, request correlation, trust, and response envelopes to Connection.
 
 ## Host service: `TypertGatewayService` (ctx key: `typertGateway`)
 
@@ -14,13 +14,13 @@ The Host entry registers a trusted-host interceptor on Connection's shared `/api
 
 A cancellation-aware Remote method declares `signal: AbortSignal` as its final Host parameter. The signal is descriptor metadata rather than a wire argument: Connection supplies it to the Gateway, and the Gateway injects it after decoded business parameters. SRC recognizes the reserved final name, while strict generation additionally requires the global `AbortSignal` type.
 
-## Client service: `ClientApi` (ctx key: `api`)
+## Client service: `ClientRemote` (ctx key: `remote`)
 
-`ctx.api.mount()` validates and registers a generated Host-for-Client contribution, then installs concrete direct and scoped methods for the calling Cordis fiber. Duplicate endpoints, namespace collisions, and descriptors without strict generated codecs fail before methods become callable.
+`ctx.remote.$mount()` validates and registers a generated Host-for-Client contribution, then installs concrete direct and scoped methods for the calling Cordis fiber. Each namespace is a traced `remote.<namespace>` child Service and unloads after its last method is withdrawn. Duplicate endpoints, namespace collisions, and descriptors without strict generated codecs fail before methods become callable.
 
 Each call validates positional inputs, constructs the descriptor's exact named `args`, and sends it through `ctx.connection.rpc.call('/api', endpoint, ...)`. Generated cancellation-aware methods accept a final optional `AbortSignal`; the Client combines it with the contribution mount lifetime before calling Connection. The returned value is validated before reaching application code. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls, and makes retained method handles reject.
 
-Generated declaration merges provide the TypeScript API through the shared `TypeRTClientApi` contract. The Client entry contains no Host Service or Host Cordis interface merge, and method lookup and invocation use ordinary objects and functions rather than a JavaScript Proxy.
+Generated declaration merges provide the TypeScript API through the shared `TypeRTClientRemote` contract. The Client entry contains no Host Service or Host Cordis interface merge, and method lookup and invocation use ordinary objects and functions rather than a JavaScript Proxy.
 
 ## Model Experience
 
diff --git a/packages/api/gateway/README.zh.md b/packages/api/gateway/README.zh.md
index 9bbd46c711..2054febb9a 100644
--- a/packages/api/gateway/README.zh.md
+++ b/packages/api/gateway/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.api`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
+为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
 
 ## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
 
@@ -14,13 +14,13 @@ Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandle
 
 支持取消的 Remote 方法会把 `signal: AbortSignal` 声明为最后一个 Host 参数。signal 是 descriptor 元数据，而不是 wire 参数：Connection 将它提供给 Gateway，Gateway 则在已解码的业务参数之后注入它。SRC 识别这个保留的末位参数名，严格生成还要求它具有全局 `AbortSignal` 类型。
 
-## Client 服务：`ClientApi`（ctx key：`api`）
+## Client 服务：`ClientRemote`（ctx key：`remote`）
 
-`ctx.api.mount()` 会校验并注册生成的 Host-for-Client 贡献项，然后为发起调用的 Cordis fiber 安装具体的直接方法和作用域方法。重复端点、命名空间冲突，以及缺少生成的严格编解码器的描述符，都会在方法可调用前报错。
+`ctx.remote.$mount()` 会校验并注册生成的 Host-for-Client 贡献项，然后为发起调用的 Cordis fiber 安装具体的直接方法和作用域方法。每个 namespace 都是可追踪的 `remote.<namespace>` 子 Service，并在最后一个方法撤回后卸载。重复端点、命名空间冲突，以及缺少生成的严格编解码器的描述符，都会在方法可调用前报错。
 
 每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api', endpoint, ...)` 发送。生成的支持取消的方法接受最后一个可选 `AbortSignal`；Client 会在调用 Connection 前将它与贡献项的挂载生命周期合并。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
 
-生成的声明合并通过共享的 `TypeRTClientApi` 契约提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
+生成的声明合并通过共享的 `TypeRTClientRemote` 契约提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
 
 ## 模型体验
 
diff --git a/packages/api/gateway/src/client/index.ts b/packages/api/gateway/src/client/index.ts
index a9343823ff..d0429339c8 100644
--- a/packages/api/gateway/src/client/index.ts
+++ b/packages/api/gateway/src/client/index.ts
@@ -1,37 +1,25 @@
 /**
  * Client projection of generated TypeRT Remote descriptors. Contributions
- * install concrete namespace methods; no JavaScript Proxy participates in
- * lookup, invocation, or type exposure.
+ * install traced `remote.<namespace>` services; no JavaScript Proxy
+ * participates in method lookup, invocation, or type exposure.
  */
 
-import { Service, symbols } from 'cordis'
+import { Service } from 'cordis'
 import type { Context } from 'cordis'
 import type { ConnectionHandle, RpcError } from '@deepseek-ai/dsh-client-connection/client'
 import type {
   InvocationDescriptor,
-  TypeRTClientApi,
+  TypeRTClientRemote,
   TypeRTCodec,
   TypeRTDisposer,
   TypeRTRemoteContribution,
 } from '@deepseek-ai/dsh-type-meta'
 
-type RemoteMethod = (...args: unknown[]) => Promise<unknown>
-
 interface MountToken {
   active: boolean
   readonly abort: AbortController
 }
 
-interface DirectNamespaceRecord {
-  readonly value: Record<string, RemoteMethod>
-  readonly tokens: Map<string, MountToken>
-}
-
-interface ScopedNamespaceRecord {
-  readonly service: ScopedRemoteNamespace
-  readonly tokens: Map<string, MountToken>
-}
-
 interface ScopedProjection {
   readonly context: string
   readonly wire: string
@@ -39,13 +27,36 @@ interface ScopedProjection {
   readonly parameterIndex?: number
 }
 
-/** Typed API service augmented by generated direct Remote namespaces. */
-export type ClientApi = TypeRTClientApi
+interface DirectMethod {
+  readonly descriptor: InvocationDescriptor
+  readonly token: MountToken
+}
+
+interface ScopedMethod extends DirectMethod {
+  readonly projection: ScopedProjection
+}
+
+interface RemoteMethodRecord {
+  direct?: DirectMethod
+  scoped?: ScopedMethod
+}
+
+interface BoundContextIdentity {
+  readonly value: unknown
+}
+
+interface RemoteNamespaceHandle {
+  readonly service: RemoteNamespaceService
+  readonly dispose: TypeRTDisposer
+}
+
+/** Typed Remote service augmented by generated direct namespaces. */
+export type ClientRemote = TypeRTClientRemote
 
 declare module 'cordis' {
   interface Context {
-    /** Generated direct Remote namespaces selected by the Client assembly. */
-    api: ClientApi
+    /** Generated Remote namespaces selected by the Client assembly. */
+    remote: ClientRemote
   }
 }
 
@@ -53,48 +64,56 @@ declare module 'cordis' {
 export const inject = ['typert', 'connection']
 
 /**
- * Install the typed Client API service.
+ * Install the typed Client Remote service.
  * @param ctx - Client Cordis root.
  */
 export function apply(ctx: Context): void {
-  new ClientApiService(ctx)
+  new ClientRemoteService(ctx)
 }
 
-class ClientApiService extends Service implements TypeRTClientApi {
+class ClientRemoteService extends Service implements TypeRTClientRemote {
   private readonly ownerCtx: Context
-  private readonly direct = new Map<string, DirectNamespaceRecord>()
-  private readonly scoped = new Map<string, ScopedNamespaceRecord>()
+  private readonly namespaces = new Map<string, RemoteNamespaceHandle>()
+  private mutations = Promise.resolve()
 
   constructor(ctx: Context) {
-    super(ctx, 'api')
+    super(ctx, 'remote')
     this.ownerCtx = ctx
   }
 
-  mount(contribution: TypeRTRemoteContribution): ReturnType<TypeRTClientApi['mount']> {
-    this.validateContribution(contribution)
+  async $mount(contribution: TypeRTRemoteContribution): ReturnType<TypeRTClientRemote['$mount']> {
     const callerCtx = this.ctx
+    const owned = callerCtx.effect(async () => {
+      const dispose = await this.enqueue(() => this.mountContribution(callerCtx, contribution))
+      return () => this.enqueue(dispose)
+    }, `api-gateway.client.$mount(${JSON.stringify(contribution.package)})`)
+    await owned
+    return async () => { await owned() }
+  }
+
+  private enqueue<T>(operation: () => T | Promise<T>): Promise<T> {
+    const result = this.mutations.then(operation, operation)
+    this.mutations = result.then(() => undefined, () => undefined)
+    return result
+  }
+
+  private async mountContribution(
+    callerCtx: Context,
+    contribution: TypeRTRemoteContribution,
+  ): Promise<TypeRTDisposer> {
+    this.validateContribution(contribution)
     const disposeRemote = callerCtx.typert.remotes.register(contribution)
-    let disposeMethods: () => void | Promise<void>
+    const installed: TypeRTDisposer[] = []
     try {
-      disposeMethods = callerCtx.effect(() => {
-        const installed: Array<() => void> = []
-        try {
-          for (const descriptor of contribution.descriptors) installed.push(this.install(descriptor))
-        } catch (error) {
-          for (const dispose of installed.reverse()) dispose()
-          throw error
-        }
-        return () => {
-          for (const dispose of installed.reverse()) dispose()
-        }
-      }, `api-gateway.client.mount(${JSON.stringify(contribution.package)})`)
+      for (const descriptor of contribution.descriptors) installed.push(await this.install(descriptor))
     } catch (error) {
-      /* v8 ignore next -- rollback disposal only rejects if Cordis teardown itself fails while handling the installation error. */
-      Promise.resolve(disposeRemote()).catch(() => {})
+      for (const dispose of installed.reverse()) await dispose()
+      await disposeRemote()
       throw error
     }
     return async () => {
-      await Promise.all([disposeMethods(), disposeRemote()])
+      for (const dispose of installed.reverse()) await dispose()
+      await disposeRemote()
     }
   }
 
@@ -112,10 +131,8 @@ class ClientApiService extends Service implements TypeRTClientApi {
       }
       methods.add(descriptor.method)
       table.set(descriptor.namespace, methods)
-      const live = kind === 'direct'
-        ? this.direct.get(descriptor.namespace)?.tokens
-        : this.scoped.get(descriptor.namespace)?.tokens
-      if (live?.has(descriptor.method) === true) {
+      const namespace = this.namespaces.get(descriptor.namespace)?.service
+      if (namespace?.has(kind, descriptor.method) === true) {
         throw new Error(`client api: ${kind} method ${endpointOf(descriptor)} is already mounted`)
       }
     }
@@ -124,118 +141,151 @@ class ClientApiService extends Service implements TypeRTClientApi {
       if (descriptor.invocation.kind === 'direct') add(direct, descriptor, 'direct')
       if (scopedProjection(descriptor) !== undefined) add(scoped, descriptor, 'scoped')
     }
-    for (const namespace of direct.keys()) {
-      if (!this.direct.has(namespace) && namespace in this) {
-        throw new Error(`client api: namespace ${JSON.stringify(namespace)} conflicts with the API service`)
-      }
-    }
-    for (const [namespace, methods] of scoped) {
-      const record = this.scoped.get(namespace)
-      if (record !== undefined) {
-        for (const method of methods) record.service.assertMethodAvailable(method)
-      } else {
-        for (const method of methods) ScopedRemoteNamespace.assertMethodAvailable(namespace, method)
-        const property = this.ownerCtx.reflect.props[namespace]
-        if (property?.type === 'accessor' || this.ownerCtx.get(namespace) !== undefined) {
-          throw new Error(`client api: scoped namespace ${JSON.stringify(namespace)} conflicts with an existing Context property`)
+    const namespaces = new Set([...direct.keys(), ...scoped.keys()])
+    for (const namespace of namespaces) {
+      const service = this.namespaces.get(namespace)?.service
+      if (service === undefined) {
+        if (namespace in this) {
+          throw new Error(`client api: namespace ${JSON.stringify(namespace)} conflicts with the Remote service`)
         }
+        const serviceKey = remoteServiceKey(namespace)
+        const property = this.ownerCtx.reflect.props[serviceKey]
+        if (property?.type === 'accessor' || this.ownerCtx.get(serviceKey) !== undefined) {
+          throw new Error(`client api: namespace ${JSON.stringify(namespace)} conflicts with an existing Remote namespace`)
+        }
+      }
+      for (const method of new Set([...(direct.get(namespace) ?? []), ...(scoped.get(namespace) ?? [])])) {
+        if (service === undefined) RemoteNamespaceService.assertMethodAvailable(namespace, method)
+        else service.assertMethodAvailable(method)
       }
     }
   }
 
-  private install(descriptor: InvocationDescriptor): () => void {
+  private async install(descriptor: InvocationDescriptor): Promise<TypeRTDisposer> {
     const token: MountToken = { active: true, abort: new AbortController() }
-    const installed: (() => void)[] = []
+    const installed: TypeRTDisposer[] = []
     try {
       if (descriptor.invocation.kind === 'direct') {
-        installed.push(this.installDirect(descriptor, token))
+        installed.push(await this.installDirect(descriptor, token))
       }
       const projection = scopedProjection(descriptor)
-      if (projection !== undefined) installed.push(this.installScoped(descriptor, projection, token))
+      if (projection !== undefined) installed.push(await this.installScoped(descriptor, projection, token))
     } catch (error) {
       token.active = false
-      for (const dispose of installed.reverse()) dispose()
       token.abort.abort()
+      for (const dispose of installed.reverse()) await dispose()
       throw error
     }
-    return () => {
+    return async () => {
       /* v8 ignore next -- Cordis effect disposers are idempotent and invoke this cleanup at most once. */
       if (!token.active) return
       token.active = false
-      for (const dispose of installed.reverse()) dispose()
       token.abort.abort()
+      for (const dispose of installed.reverse()) await dispose()
     }
   }
 
-  private installDirect(descriptor: InvocationDescriptor, token: MountToken): () => void {
-    let namespace = this.direct.get(descriptor.namespace)
-    const fresh = namespace === undefined
-    if (namespace === undefined) {
-      namespace = { value: Object.create(null) as Record<string, RemoteMethod>, tokens: new Map() }
-      Object.defineProperty(this, descriptor.namespace, {
-        configurable: true,
-        enumerable: true,
-        value: namespace.value,
-      })
-    }
+  private async installDirect(descriptor: InvocationDescriptor, token: MountToken): Promise<TypeRTDisposer> {
+    const namespace = await this.namespace(descriptor.namespace)
     try {
-      Object.defineProperty(namespace.value, descriptor.method, {
-        configurable: true,
-        enumerable: true,
-        value: (...args: unknown[]) => this.invoke(descriptor, undefined, token, this.ownerCtx, args),
-      })
+      namespace.service.installDirect(descriptor, token)
     } catch (error) {
-      if (fresh) Reflect.deleteProperty(this, descriptor.namespace)
+      await this.disposeNamespace(descriptor.namespace, namespace)
       throw error
     }
-    if (fresh) this.direct.set(descriptor.namespace, namespace)
-    namespace.tokens.set(descriptor.method, token)
-    return () => {
-      /* v8 ignore next -- duplicate live methods are rejected before installation, so no newer token can replace this one. */
-      if (namespace.tokens.get(descriptor.method) !== token) return
-      Reflect.deleteProperty(namespace.value, descriptor.method)
-      namespace.tokens.delete(descriptor.method)
-      if (namespace.tokens.size !== 0) return
-      this.direct.delete(descriptor.namespace)
-      Reflect.deleteProperty(this, descriptor.namespace)
+    return async () => {
+      if (!namespace.service.remove('direct', descriptor.method, token)) return
+      await this.disposeNamespace(descriptor.namespace, namespace)
     }
   }
 
-  private installScoped(
+  private async installScoped(
     descriptor: InvocationDescriptor,
     projection: ScopedProjection,
     token: MountToken,
-  ): () => void {
-    let namespace = this.scoped.get(descriptor.namespace)
-    if (namespace === undefined) {
-      const service = new ScopedRemoteNamespace(
-        this.ownerCtx,
-        descriptor.namespace,
-        (current, currentProjection, currentToken, caller, args) =>
-          this.invoke(current, currentProjection, currentToken, caller, args),
-      )
-      service.install(descriptor, projection, token)
-      namespace = { service, tokens: new Map() }
-      this.scoped.set(descriptor.namespace, namespace)
-    } else {
-      namespace.service.install(descriptor, projection, token)
+  ): Promise<TypeRTDisposer> {
+    const namespace = await this.namespace(descriptor.namespace)
+    try {
+      namespace.service.installScoped(descriptor, projection, token)
+    } catch (error) {
+      await this.disposeNamespace(descriptor.namespace, namespace)
+      throw error
     }
-    namespace.tokens.set(descriptor.method, token)
-    return () => {
-      /* v8 ignore next -- duplicate live methods are rejected before installation, so no newer token can replace this one. */
-      if (namespace.tokens.get(descriptor.method) !== token) return
-      namespace.service.remove(descriptor.method)
-      namespace.tokens.delete(descriptor.method)
-      if (namespace.tokens.size === 0) this.scoped.delete(descriptor.namespace)
+    return async () => {
+      if (!namespace.service.remove('scoped', descriptor.method, token)) return
+      await this.disposeNamespace(descriptor.namespace, namespace)
     }
   }
 
+  private async namespace(name: string): Promise<RemoteNamespaceHandle> {
+    let namespace = this.namespaces.get(name)
+    if (namespace !== undefined) return namespace
+    let service: RemoteNamespaceService | undefined
+    const fiber = this.ownerCtx.plugin({
+      name: remoteServiceKey(name),
+      apply: (ctx: Context) => {
+        service = new RemoteNamespaceService(
+          ctx,
+          name,
+          (direct, scoped, caller, args) => this.invokeMethod(direct, scoped, caller, args),
+        )
+      },
+    })
+    try {
+      await fiber
+    } catch (error) {
+      await fiber.dispose()
+      throw error
+    }
+    /* v8 ignore next -- a settled namespace fiber synchronously constructs its Service. */
+    if (service === undefined) throw new Error(`client api: namespace ${JSON.stringify(name)} did not start`)
+    namespace = { service, dispose: fiber.dispose }
+    this.namespaces.set(name, namespace)
+    return namespace
+  }
+
+  private async disposeNamespace(name: string, namespace: RemoteNamespaceHandle): Promise<void> {
+    if (!namespace.service.empty || this.namespaces.get(name) !== namespace) return
+    this.namespaces.delete(name)
+    await namespace.dispose()
+  }
+
+  private invokeMethod(
+    direct: DirectMethod | undefined,
+    scoped: ScopedMethod | undefined,
+    callerCtx: Context,
+    values: readonly unknown[],
+  ): Promise<unknown> {
+    if (scoped !== undefined) {
+      const binder = this.ownerCtx.typert.contexts.getClient(scoped.projection.context)
+      const identity = binder?.identity(callerCtx)
+      if (identity !== undefined) {
+        return this.invoke(
+          scoped.descriptor,
+          scoped.projection,
+          scoped.token,
+          callerCtx,
+          values,
+          { value: identity },
+        )
+      }
+    }
+    if (direct !== undefined) {
+      return this.invoke(direct.descriptor, undefined, direct.token, callerCtx, values)
+    }
+    if (scoped !== undefined) {
+      return this.invoke(scoped.descriptor, scoped.projection, scoped.token, callerCtx, values)
+    }
+    throw new Error('client api: Remote method is no longer mounted')
+  }
+
   private async invoke(
     descriptor: InvocationDescriptor,
     projection: ScopedProjection | undefined,
     token: MountToken,
     callerCtx: Context,
     values: readonly unknown[],
+    boundIdentity?: BoundContextIdentity,
   ): Promise<unknown> {
     const endpoint = endpointOf(descriptor)
     if (!token.active) throw new Error(`client api: Remote method ${endpoint} is no longer mounted`)
@@ -251,11 +301,15 @@ class ClientApiService extends Service implements TypeRTClientApi {
     }
     const args = Object.create(null) as Record<string, unknown>
     if (projection !== undefined) {
-      const binder = this.ownerCtx.typert.contexts.getClient(projection.context)
-      if (binder === undefined) {
+      const binder = boundIdentity === undefined
+        ? this.ownerCtx.typert.contexts.getClient(projection.context)
+        : undefined
+      if (boundIdentity === undefined && binder === undefined) {
         throw new Error(`client api: ${endpoint} has no Client Context binder for ${JSON.stringify(projection.context)}`)
       }
-      const identity = binder.identity(callerCtx)
+      const identity = boundIdentity === undefined
+        ? binder?.identity(callerCtx)
+        : boundIdentity.value
       if (identity === undefined) {
         throw new Error(`client api: ${endpoint} requires a ${JSON.stringify(projection.context)} Context`)
       }
@@ -281,23 +335,19 @@ class ClientApiService extends Service implements TypeRTClientApi {
 }
 
 type InvokeRemote = (
-  descriptor: InvocationDescriptor,
-  projection: ScopedProjection,
-  token: MountToken,
+  direct: DirectMethod | undefined,
+  scoped: ScopedMethod | undefined,
   callerCtx: Context,
   args: readonly unknown[],
 ) => Promise<unknown>
 
-class ScopedRemoteNamespace {
-  private readonly ctx: Context
-  private readonly ownerCtx: Context
-  private readonly methods = new Set<string>()
-  private disposeService: TypeRTDisposer | undefined
-  readonly name: string
+class RemoteNamespaceService extends Service {
+  private readonly methods = new Map<string, RemoteMethodRecord>()
+  private readonly namespace: string
 
   static assertMethodAvailable(namespace: string, method: string): void {
-    if (SCOPED_NAMESPACE_FIELDS.has(method) || method in ScopedRemoteNamespace.prototype) {
-      throw new Error(`client api: scoped method ${JSON.stringify(`${namespace}/${method}`)} conflicts with its namespace service`)
+    if (REMOTE_NAMESPACE_FIELDS.has(method) || method in RemoteNamespaceService.prototype) {
+      throw new Error(`client api: method ${JSON.stringify(`${namespace}/${method}`)} conflicts with its namespace service`)
     }
   }
 
@@ -306,54 +356,92 @@ class ScopedRemoteNamespace {
     name: string,
     private readonly invokeRemote: InvokeRemote,
   ) {
-    this.ctx = ctx
-    this.ownerCtx = ctx
-    this.name = name
-    Object.defineProperty(this, symbols.tracker, {
-      value: { associate: name, property: 'ctx' },
-    })
+    super(ctx, remoteServiceKey(name))
+    this.namespace = name
   }
 
   assertMethodAvailable(method: string): void {
-    ScopedRemoteNamespace.assertMethodAvailable(this.name, method)
-    if (method in this) {
-      throw new Error(`client api: scoped method ${JSON.stringify(`${this.name}/${method}`)} conflicts with its namespace service`)
+    RemoteNamespaceService.assertMethodAvailable(this.namespace, method)
+    if (method in this && !this.methods.has(method)) {
+      throw new Error(`client api: method ${JSON.stringify(`${this.namespace}/${method}`)} conflicts with its namespace service`)
     }
   }
 
-  install(descriptor: InvocationDescriptor, projection: ScopedProjection, token: MountToken): void {
-    this.assertMethodAvailable(descriptor.method)
-    const activate = this.methods.size === 0
-    const method = descriptor.method
+  get empty(): boolean {
+    return this.methods.size === 0
+  }
+
+  has(kind: 'direct' | 'scoped', method: string): boolean {
+    return this.methods.get(method)?.[kind] !== undefined
+  }
+
+  installDirect(descriptor: InvocationDescriptor, token: MountToken): void {
+    this.install(descriptor.method, 'direct', { descriptor, token })
+  }
+
+  installScoped(descriptor: InvocationDescriptor, projection: ScopedProjection, token: MountToken): void {
+    this.install(descriptor.method, 'scoped', { descriptor, projection, token })
+  }
+
+  private install(method: string, kind: 'direct', value: DirectMethod): void
+  private install(method: string, kind: 'scoped', value: ScopedMethod): void
+  private install(method: string, kind: 'direct' | 'scoped', value: DirectMethod | ScopedMethod): void {
+    this.assertMethodAvailable(method)
+    let record = this.methods.get(method)
+    const fresh = record === undefined
+    record ??= {}
+    if (record[kind] !== undefined) {
+      throw new Error(`client api: ${kind} method ${this.namespace}/${method} is already mounted`)
+    }
     try {
-      Object.defineProperty(this, method, {
-        configurable: true,
-        enumerable: true,
-        value: function (this: ScopedRemoteNamespace, ...args: unknown[]): Promise<unknown> {
-          return this.invokeRemote(descriptor, projection, token, this.ctx, args)
-        },
-      })
-      if (activate) {
-        this.disposeService = this.ownerCtx.reflect.provide(this.name, this)
+      if (fresh) {
+        Object.defineProperty(this, method, {
+          configurable: true,
+          enumerable: true,
+          get: function (this: RemoteNamespaceService): (...args: unknown[]) => Promise<unknown> {
+            const callerCtx = this.ctx
+            const current = this.methods.get(method)
+            const direct = current?.direct
+            const scoped = current?.scoped
+            return (...args: unknown[]) => {
+              return this.invokeRemote(direct, scoped, callerCtx, args)
+            }
+          },
+        })
+        this.methods.set(method, record)
       }
+      if (kind === 'direct') record.direct = value
+      else record.scoped = value as ScopedMethod
     } catch (error) {
-      Reflect.deleteProperty(this, method)
+      if (kind === 'direct') delete record.direct
+      else delete record.scoped
+      if (fresh) {
+        this.methods.delete(method)
+        Reflect.deleteProperty(this, method)
+      }
       throw error
     }
-    this.methods.add(method)
   }
 
-  remove(method: string): void {
-    Reflect.deleteProperty(this, method)
+  remove(kind: 'direct' | 'scoped', method: string, token: MountToken): boolean {
+    const record = this.methods.get(method)
+    const current = record?.[kind]
+    /* v8 ignore next -- duplicate live variants are rejected before installation, so no newer token can replace this one. */
+    if (record === undefined || current?.token !== token) return false
+    if (kind === 'direct') delete record.direct
+    else delete record.scoped
+    if (record.direct !== undefined || record.scoped !== undefined) return true
     this.methods.delete(method)
-    if (this.methods.size !== 0) return
-    const disposeService = this.disposeService
-    this.disposeService = undefined
-    void disposeService?.()
+    Reflect.deleteProperty(this, method)
+    return true
   }
 }
 
-const SCOPED_NAMESPACE_FIELDS = new Set(['ctx', 'disposeService', 'invokeRemote', 'methods', 'name', 'ownerCtx'])
+const REMOTE_NAMESPACE_FIELDS = new Set(['ctx', 'empty', 'invokeRemote', 'methods', 'name', 'namespace'])
+
+function remoteServiceKey(namespace: string): string {
+  return `remote.${namespace}`
+}
 
 function endpointOf(descriptor: Pick<InvocationDescriptor, 'namespace' | 'method'>): string {
   return `${descriptor.namespace}/${descriptor.method}`
diff --git a/packages/api/gateway/tests/client.spec.ts b/packages/api/gateway/tests/client.spec.ts
index feae3056c9..216f2359e7 100644
--- a/packages/api/gateway/tests/client.spec.ts
+++ b/packages/api/gateway/tests/client.spec.ts
@@ -1,4 +1,4 @@
-import { Context } from 'cordis'
+import { Context, Service } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
 import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
@@ -38,7 +38,7 @@ declare module '@deepseek-ai/dsh-type-meta' {
 
 }
 
-type FixtureContext = Context & TypeRTRemoteContextApi<'fixture'>
+type FixtureContext = Omit<Context, 'remote'> & { readonly remote: TypeRTRemoteContextApi<'fixture'> }
 
 const idSchema = z.string().min(1)
 const requestSchema = z.object({ objective: z.string().min(1) })
@@ -105,17 +105,16 @@ describe('Client TypeRT API', () => {
     const call = vi.fn<ConnectionHandle['rpc']['call']>()
       .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })
     const ctx = await bench(call)
-    let retained: typeof ctx.api.goals.create | undefined
+    const businessGoals = { owner: 'host business service' }
+    const disposeBusinessGoals = ctx.provide('goals', businessGoals)
     const assembly = ctx.plugin(Object.assign(
-      (scope: Context) => {
-        scope.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
-        retained = scope.api.goals.create
-      },
-      { inject: ['api'] },
+      (scope: Context) => scope.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] }),
+      { inject: ['remote'] },
     ))
     await assembly
+    const retained = ctx.remote.goals.create
 
-    await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).resolves.toEqual({ ref: 'goal-1' })
+    await expect(ctx.remote.goals.create('agent-1', { objective: 'ship' })).resolves.toEqual({ ref: 'goal-1' })
     expect(call).toHaveBeenCalledWith(
       '/api',
       'goals/create',
@@ -123,7 +122,7 @@ describe('Client TypeRT API', () => {
       expect.any(AbortSignal),
     )
     const callerAbort = new AbortController()
-    await expect(ctx.api.goals.create(
+    await expect(ctx.remote.goals.create(
       'agent-1',
       { objective: 'cancel me' },
       callerAbort.signal,
@@ -135,16 +134,18 @@ describe('Client TypeRT API', () => {
     callerAbort.abort(cancellation)
     expect(combinedSignal?.aborted).toBe(true)
     expect(combinedSignal?.reason).toBe(cancellation)
-    await expect(ctx.api.goals.create('', { objective: 'ship' })).rejects.toThrow('rejected "agentId"')
+    await expect(ctx.remote.goals.create('', { objective: 'ship' })).rejects.toThrow('rejected "agentId"')
 
     call.mockResolvedValueOnce({ ok: true, value: { ref: 1 } })
-    await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('rejected "result"')
+    await expect(ctx.remote.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('rejected "result"')
 
     await assembly.dispose()
-    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
-    expect(ctx.get('goals')).toBeUndefined()
+    expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect(ctx.get('remote.goals')).toBeUndefined()
+    expect(ctx.get('goals')).toBe(businessGoals)
     expect(ctx.typert.remotes.list()).toEqual([])
     await expect(retained?.('agent-1', { objective: 'ship' })).rejects.toThrow('no longer mounted')
+    disposeBusinessGoals()
   })
 
   it('projects one direct lookup descriptor onto an Agent-scoped alias', async () => {
@@ -156,26 +157,24 @@ describe('Client TypeRT API', () => {
       identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId,
     })
     const assembly = ctx.plugin(Object.assign(
-      (scope: Context) => {
-        scope.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
-      },
-      { inject: ['api'] },
+      (scope: Context) => scope.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] }),
+      { inject: ['remote'] },
     ))
     await assembly
 
-    await expect(agentCtx.goals.create({ objective: 'ship scoped' })).resolves.toEqual({ ref: 'goal-2' })
+    await expect(agentCtx.remote.goals.create({ objective: 'ship scoped' })).resolves.toEqual({ ref: 'goal-2' })
     expect(call).toHaveBeenCalledWith(
       '/api',
       'goals/create',
       { args: { agentId: 'agent-2', request: { objective: 'ship scoped' } } },
       expect.any(AbortSignal),
     )
-    await expect((ctx as FixtureContext).goals.create({ objective: 'wrong scope' }))
-      .rejects.toThrow('requires a "fixture" Context')
+    await expect((ctx as FixtureContext).remote.goals.create({ objective: 'wrong scope' }))
+      .rejects.toThrow('expected 2 business argument(s)')
 
     await assembly.dispose()
-    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
-    expect(ctx.get('goals')).toBeUndefined()
+    expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect(ctx.get('remote.goals')).toBeUndefined()
   })
 
   it('uses the caller Context identity for scoped namespace methods', async () => {
@@ -187,25 +186,23 @@ describe('Client TypeRT API', () => {
       identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId,
     })
     const assembly = ctx.plugin(Object.assign(
-      (scope: Context) => {
-        scope.api.mount({ package: '@fixture/goals', descriptors: [contextDescriptor()] })
-      },
-      { inject: ['api'] },
+      (scope: Context) => scope.remote.$mount({ package: '@fixture/goals', descriptors: [contextDescriptor()] }),
+      { inject: ['remote'] },
     ))
     await assembly
 
-    await expect(agentCtx.goals.rename({ objective: 'land' })).resolves.toEqual({ renamed: true })
+    await expect(agentCtx.remote.goals.rename({ objective: 'land' })).resolves.toEqual({ renamed: true })
     expect(call).toHaveBeenCalledWith(
       '/api',
       'goals/rename',
       { args: { agentId: 'agent-2', request: { objective: 'land' } } },
       expect.any(AbortSignal),
     )
-    await expect((ctx as FixtureContext).goals.rename({ objective: 'land' }))
+    await expect((ctx as FixtureContext).remote.goals.rename({ objective: 'land' }))
       .rejects.toThrow('requires a "fixture" Context')
 
     await assembly.dispose()
-    expect(ctx.get('goals')).toBeUndefined()
+    expect(ctx.get('remote.goals')).toBeUndefined()
   })
 
   it('rejects weak descriptors and namespace collisions before registration', async () => {
@@ -215,12 +212,12 @@ describe('Client TypeRT API', () => {
       result: { mode: 'src-json' },
     }
 
-    expect(() => ctx.api.mount({ package: '@fixture/weak', descriptors: [weak] }))
-      .toThrow('has no strict codec')
-    expect(() => ctx.api.mount({
+    await expect(ctx.remote.$mount({ package: '@fixture/weak', descriptors: [weak] }))
+      .rejects.toThrow('has no strict codec')
+    await expect(ctx.remote.$mount({
       package: '@fixture/conflict',
-      descriptors: [{ ...directDescriptor(), namespace: 'mount' }],
-    })).toThrow('conflicts with the API service')
+      descriptors: [{ ...directDescriptor(), namespace: '$mount' }],
+    })).rejects.toThrow('conflicts with the Remote service')
     expect(ctx.typert.remotes.list()).toEqual([])
   })
 
@@ -235,48 +232,50 @@ describe('Client TypeRT API', () => {
     const direct = directDescriptor()
     const context = contextDescriptor()
 
-    expect(() => ctx.api.mount({
+    await expect(ctx.remote.$mount({
       package: '@fixture/direct-duplicates',
       descriptors: [direct, { ...direct, id: '@fixture/goals#goals/create-again' }],
-    })).toThrow('repeats direct method')
-    expect(() => ctx.api.mount({
+    })).rejects.toThrow('repeats direct method')
+    await expect(ctx.remote.$mount({
       package: '@fixture/scoped-duplicates',
       descriptors: [context, { ...context, id: '@fixture/goals#goals/rename-again' }],
-    })).toThrow('repeats scoped method')
+    })).rejects.toThrow('repeats scoped method')
 
-    const disposeDirect = ctx.api.mount({ package: '@fixture/direct-live', descriptors: [direct] })
-    expect(() => ctx.api.mount({
+    const disposeDirect = await ctx.remote.$mount({ package: '@fixture/direct-live', descriptors: [direct] })
+    await expect(ctx.remote.$mount({
       package: '@fixture/direct-conflict', descriptors: [{ ...direct, id: '@fixture/other#goals/create' }],
-    })).toThrow('direct method goals/create is already mounted')
+    })).rejects.toThrow('direct method goals/create is already mounted')
     await disposeDirect()
 
-    const disposeScoped = ctx.api.mount({ package: '@fixture/scoped-live', descriptors: [context] })
-    expect(() => ctx.api.mount({
+    const disposeScoped = await ctx.remote.$mount({ package: '@fixture/scoped-live', descriptors: [context] })
+    await expect(ctx.remote.$mount({
       package: '@fixture/scoped-conflict', descriptors: [{ ...context, id: '@fixture/other#goals/rename' }],
-    })).toThrow('scoped method goals/rename is already mounted')
-    expect(() => ctx.api.mount({
+    })).rejects.toThrow('scoped method goals/rename is already mounted')
+    await expect(ctx.remote.$mount({
       package: '@fixture/service-method-conflict',
       descriptors: [{ ...context, id: '@fixture/goals#goals/remove', method: 'remove' }],
-    })).toThrow('conflicts with its namespace service')
-    const scopedService = ctx.get('goals') as unknown as object
+    })).rejects.toThrow('conflicts with its namespace service')
+    const scopedService = ctx.get('remote.goals') as unknown as object
     Object.defineProperty(scopedService, 'custom', { configurable: true, value: () => undefined })
-    expect(() => ctx.api.mount({
+    await expect(ctx.remote.$mount({
       package: '@fixture/service-own-property-conflict',
       descriptors: [{ ...direct, id: '@fixture/goals#goals/custom', method: 'custom' }],
-    })).toThrow('conflicts with its namespace service')
+    })).rejects.toThrow('conflicts with its namespace service')
     Reflect.deleteProperty(scopedService, 'custom')
     await disposeScoped()
 
-    expect(() => ctx.api.mount({
+    const disposeRemoteTypert = ctx.reflect.provide('remote.typert', { owner: 'fixture' })
+    await expect(ctx.remote.$mount({
       package: '@fixture/context-property-conflict',
       descriptors: [{ ...context, namespace: 'typert' }],
-    })).toThrow('conflicts with an existing Context property')
+    })).rejects.toThrow('conflicts with an existing Remote namespace')
+    await disposeRemoteTypert()
 
-    const disposeMultipleScoped = ctx.api.mount({
+    const disposeMultipleScoped = await ctx.remote.$mount({
       package: '@fixture/multiple-scoped',
       descriptors: [directDescriptor(), contextDescriptor()],
     })
-    await expect(agentCtx.goals.rename({ objective: 'remounted' })).resolves.toEqual({ renamed: true })
+    await expect(agentCtx.remote.goals.rename({ objective: 'remounted' })).resolves.toEqual({ renamed: true })
     expect(call).toHaveBeenLastCalledWith(
       '/api',
       'goals/rename',
@@ -286,41 +285,6 @@ describe('Client TypeRT API', () => {
     await disposeMultipleScoped()
   })
 
-  it('rolls back direct projection when scoped installation fails', async () => {
-    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
-    const disposeScoped = ctx.api.mount({
-      package: '@fixture/scoped-base',
-      descriptors: [contextDescriptor()],
-    })
-    const defineProperty = Object.defineProperty
-    let createDefinitions = 0
-    const definePropertySpy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
-      // The direct projection defines `create` first; fail the following scoped projection.
-      if (key === 'create' && ++createDefinitions === 2) throw new Error('simulated scoped installation failure')
-      return defineProperty(target, key, attributes)
-    })
-
-    try {
-      expect(() => ctx.api.mount({
-        package: '@fixture/failing-install',
-        descriptors: [directDescriptor()],
-      })).toThrow('simulated scoped installation failure')
-    } finally {
-      definePropertySpy.mockRestore()
-    }
-
-    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
-    expect(ctx.get('goals') !== undefined).toBe(true)
-    expect(ctx.typert.remotes.list()).toHaveLength(1)
-
-    const disposeRetry = ctx.api.mount({
-      package: '@fixture/retry',
-      descriptors: [directDescriptor()],
-    })
-    await disposeRetry()
-    await disposeScoped()
-  })
-
   it('rolls back earlier descriptors when a later descriptor fails to install', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const { scope: _scope, ...first } = directDescriptor()
@@ -335,17 +299,17 @@ describe('Client TypeRT API', () => {
       return defineProperty(target, key, attributes)
     })
     try {
-      expect(() => ctx.api.mount({ package: '@fixture/failing-batch', descriptors: [first, second] }))
-        .toThrow('fixture later-descriptor failure')
+      await expect(ctx.remote.$mount({ package: '@fixture/failing-batch', descriptors: [first, second] }))
+        .rejects.toThrow('fixture later-descriptor failure')
     } finally {
       spy.mockRestore()
     }
 
-    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
     await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
-    const retry = ctx.api.mount({ package: '@fixture/retry-batch', descriptors: [first, second] })
-    expect(ctx.api.goals.create).toBeTypeOf('function')
-    expect((ctx.api.goals as unknown as Record<string, unknown>).archive).toBeTypeOf('function')
+    const retry = await ctx.remote.$mount({ package: '@fixture/retry-batch', descriptors: [first, second] })
+    expect(ctx.remote.goals.create).toBeTypeOf('function')
+    expect((ctx.remote.goals as unknown as Record<string, unknown>).archive).toBeTypeOf('function')
     await retry()
   })
 
@@ -353,7 +317,7 @@ describe('Client TypeRT API', () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const direct = directDescriptor()
     const context = contextDescriptor()
-    expect(() => ctx.api.mount({
+    await expect(ctx.remote.$mount({
       package: '@fixture/weak-parameter',
       descriptors: [{
         ...direct,
@@ -361,19 +325,19 @@ describe('Client TypeRT API', () => {
           ? { ...parameter, codec: { mode: 'src-json' } }
           : parameter),
       }],
-    })).toThrow('has no strict codec')
-    expect(() => ctx.api.mount({
+    })).rejects.toThrow('has no strict codec')
+    await expect(ctx.remote.$mount({
       package: '@fixture/weak-context',
       descriptors: [{
         ...context,
         invocation: { ...context.invocation, codec: { mode: 'src-json' } },
       } as InvocationDescriptor],
-    })).toThrow('has no strict codec')
-    expect(() => ctx.api.mount({
+    })).rejects.toThrow('has no strict codec')
+    await expect(ctx.remote.$mount({
       package: '@fixture/malformed-scope',
       descriptors: [{ ...direct, scope: { context: 'fixture', wire: 'missingId' } }],
-    })).toThrow('scope must select its only lookup parameter')
-    expect(() => ctx.api.mount({
+    })).rejects.toThrow('scope must select its only lookup parameter')
+    await expect(ctx.remote.$mount({
       package: '@fixture/ambiguous-scope',
       descriptors: [{
         ...direct,
@@ -382,7 +346,7 @@ describe('Client TypeRT API', () => {
           codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', schema: idSchema },
         }],
       }],
-    })).toThrow('scope must select its only lookup parameter')
+    })).rejects.toThrow('scope must select its only lookup parameter')
   })
 
   it('validates invocation arity, required binders, live Connection, and mutable descriptor codecs', async () => {
@@ -390,27 +354,29 @@ describe('Client TypeRT API', () => {
       .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })
     const ctx = await bench(call)
     const descriptor = directDescriptor()
-    const dispose = ctx.api.mount({
+    const dispose = await ctx.remote.$mount({
       package: '@fixture/goals',
       descriptors: [descriptor, contextDescriptor()],
     })
-    const create = ctx.api.goals.create as unknown as (...args: unknown[]) => Promise<unknown>
-    const goals = (ctx as FixtureContext).goals
+    const create = ctx.remote.goals.create as unknown as (...args: unknown[]) => Promise<unknown>
+    const goals = (ctx as FixtureContext).remote.goals
     const rename = goals.rename as unknown as (...args: unknown[]) => Promise<unknown>
 
     await expect(create('agent-1')).rejects.toThrow('expected 2 business argument(s) plus an optional AbortSignal, got 1')
     await expect(create('agent-1', { objective: 'ship' }, undefined, 'extra'))
       .rejects.toThrow('got 4')
     await expect(rename.call(goals)).rejects.toThrow('expected 1 argument(s), got 0')
-    await expect((ctx as FixtureContext).goals.create({ objective: 'ship' }))
+    await expect((ctx as FixtureContext).remote.goals.create({ objective: 'ship' }))
+      .rejects.toThrow('expected 2 business argument(s)')
+    await expect((ctx as FixtureContext).remote.goals.rename({ objective: 'ship' }))
       .rejects.toThrow('no Client Context binder')
 
     ;(descriptor.parameters[0] as { codec: { mode: string } }).codec.mode = 'src-json'
-    await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('has no strict codec')
+    await expect(ctx.remote.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('has no strict codec')
     ;(descriptor.parameters[0] as { codec: { mode: string } }).codec.mode = 'strict'
 
     ctx.set('connection', undefined)
-    await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('no active Connection')
+    await expect(ctx.remote.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('no active Connection')
     await dispose()
   })
 
@@ -427,14 +393,14 @@ describe('Client TypeRT API', () => {
       id: '@fixture/goals#goals/archive',
       method: 'archive',
     }
-    const dispose = ctx.api.mount({ package: '@fixture/goals', descriptors: [first, second] })
-    const invocation = ctx.api.goals.create('agent-1', { objective: 'ship' })
+    const dispose = await ctx.remote.$mount({ package: '@fixture/goals', descriptors: [first, second] })
+    const invocation = ctx.remote.goals.create('agent-1', { objective: 'ship' })
     await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(1) })
     await dispose()
     resolveCall({ ok: true, value: { ref: 'goal-1' } })
 
     await expect(invocation).rejects.toThrow('withdrawn during invocation')
-    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
   })
 
   it('preserves a __proto__ wire parameter as an own named argument', async () => {
@@ -453,9 +419,9 @@ describe('Client TypeRT API', () => {
         codec: { mode: 'strict', typeSymbol: '@fixture#PrototypeValue', schema: z.string() },
       }],
     }
-    const dispose = ctx.api.mount({ package: '@fixture/prototype', descriptors: [descriptor] })
+    const dispose = await ctx.remote.$mount({ package: '@fixture/prototype', descriptors: [descriptor] })
 
-    const method = (ctx.api.goals as unknown as Record<string, (...args: unknown[]) => Promise<unknown>>).prototype
+    const method = (ctx.remote.goals as unknown as Record<string, (...args: unknown[]) => Promise<unknown>>).prototype
     await expect(method?.('wire-value')).resolves.toEqual({ ref: 'goal-1' })
     const payload = call.mock.calls[0]?.[2] as { readonly args: Record<string, unknown> }
     expect(Object.getPrototypeOf(payload.args)).toBeNull()
@@ -464,23 +430,23 @@ describe('Client TypeRT API', () => {
     await dispose()
   })
 
-  it('rolls back Remote registration when concrete method installation fails', async () => {
+  it('rolls back Remote registration when namespace Service startup fails', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const defineProperty = Object.defineProperty
     const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
-      if (key === 'goals') throw new Error('fixture installation failure')
+      if (key === Service.tracker) throw new Error('fixture namespace startup failure')
       return defineProperty(target, key, attributes)
     })
     try {
-      expect(() => ctx.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] }))
-        .toThrow('fixture installation failure')
+      await expect(ctx.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] }))
+        .rejects.toThrow('fixture namespace startup failure')
       await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
     } finally {
       spy.mockRestore()
     }
 
-    const retry = ctx.api.mount({ package: '@fixture/goals-retry', descriptors: [directDescriptor()] })
-    expect(ctx.api.goals.create).toBeTypeOf('function')
+    const retry = await ctx.remote.$mount({ package: '@fixture/goals-retry', descriptors: [directDescriptor()] })
+    expect(ctx.remote.goals.create).toBeTypeOf('function')
     await retry()
   })
 
@@ -492,16 +458,21 @@ describe('Client TypeRT API', () => {
       return defineProperty(target, key, attributes)
     })
     try {
-      expect(() => ctx.api.mount({ package: '@fixture/direct-method-failure', descriptors: [directDescriptor()] }))
-        .toThrow('fixture direct method installation failure')
+      await expect(ctx.remote.$mount({
+        package: '@fixture/direct-method-failure',
+        descriptors: [directDescriptor()],
+      })).rejects.toThrow('fixture direct method installation failure')
     } finally {
       spy.mockRestore()
     }
 
-    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
     await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
-    const retry = ctx.api.mount({ package: '@fixture/direct-method-retry', descriptors: [directDescriptor()] })
-    expect(ctx.api.goals.create).toBeTypeOf('function')
+    const retry = await ctx.remote.$mount({
+      package: '@fixture/direct-method-retry',
+      descriptors: [directDescriptor()],
+    })
+    expect(ctx.remote.goals.create).toBeTypeOf('function')
     await retry()
   })
 
@@ -513,41 +484,41 @@ describe('Client TypeRT API', () => {
       return defineProperty(target, key, attributes)
     })
     try {
-      expect(() => ctx.api.mount({ package: '@fixture/scoped-failure', descriptors: [contextDescriptor()] }))
-        .toThrow('fixture scoped installation failure')
+      await expect(ctx.remote.$mount({ package: '@fixture/scoped-failure', descriptors: [contextDescriptor()] }))
+        .rejects.toThrow('fixture scoped installation failure')
     } finally {
       spy.mockRestore()
     }
 
-    expect(ctx.get('goals')).toBeUndefined()
+    expect(ctx.get('remote.goals')).toBeUndefined()
     await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
-    const retry = ctx.api.mount({ package: '@fixture/scoped-retry', descriptors: [contextDescriptor()] })
-    expect((ctx.get('goals') as unknown as Record<string, unknown>).rename).toBeTypeOf('function')
+    const retry = await ctx.remote.$mount({ package: '@fixture/scoped-retry', descriptors: [contextDescriptor()] })
+    expect((ctx.get('remote.goals') as unknown as Record<string, unknown>).rename).toBeTypeOf('function')
     await retry()
   })
 
   it('unregisters an empty scoped namespace so another provider can claim its name', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
-    const dispose = ctx.api.mount({ package: '@fixture/scoped', descriptors: [contextDescriptor()] })
-    expect(ctx.get('goals')).toBeDefined()
+    const dispose = await ctx.remote.$mount({ package: '@fixture/scoped', descriptors: [contextDescriptor()] })
+    expect(ctx.get('remote.goals')).toBeDefined()
 
     await dispose()
 
-    expect(ctx.get('goals')).toBeUndefined()
+    expect(ctx.get('remote.goals')).toBeUndefined()
     const replacement = { owner: 'replacement' }
-    const disposeReplacement = ctx.reflect.provide('goals', replacement)
-    expect(ctx.get('goals')).toBe(replacement)
+    const disposeReplacement = ctx.reflect.provide('remote.goals', replacement)
+    expect(ctx.get('remote.goals')).toBe(replacement)
     await disposeReplacement()
   })
 
   it('throws RPC failures with the structured error as its cause', async () => {
     const rpcError = { code: 'internal' as const, message: 'host failed', details: {} }
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>().mockResolvedValue({ ok: false, error: rpcError }))
-    ctx.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
+    await ctx.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
 
     let failure: unknown
     try {
-      await ctx.api.goals.create('agent-1', { objective: 'ship' })
+      await ctx.remote.goals.create('agent-1', { objective: 'ship' })
     } catch (error) {
       failure = error
     }
diff --git a/packages/api/remotes/README.i18n.yaml b/packages/api/remotes/README.i18n.yaml
index c3c13a8049..82947331c5 100644
--- a/packages/api/remotes/README.i18n.yaml
+++ b/packages/api/remotes/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/api/remotes/README.md
-README.md: cf54a56a849246d4efdca09cadd42e157064bdee
-README.zh.md: 5cd7ef21c926440ca4df6d88ee4adfe87defcc3f
+README.md: 7f6a2114d900413d972584c0f1c141b7f835ba36
+README.zh.md: cce263747d696570f362811556fa6f5c0be0a0f5
diff --git a/packages/api/remotes/README.md b/packages/api/remotes/README.md
index cf54a56a84..7f6a2114d9 100644
--- a/packages/api/remotes/README.md
+++ b/packages/api/remotes/README.md
@@ -2,13 +2,13 @@
 
 English | [中文](README.zh.md)
 
-Two-sided BFF for Host Remote capabilities selected by this application. The Host entry owns Agent/Session identity policy; the Client entry imports generated `/remote` artifacts as runtime values, mounts each contribution through `ctx.api`, and re-exports their declaration merges. Client business packages depend on this facade rather than the Gateway implementation or individual Remote runtime entries.
+Two-sided BFF for Host Remote capabilities selected by this application. The Host entry owns Agent/Session identity policy; the Client entry imports generated `/remote` artifacts as runtime values, mounts each contribution through `ctx.remote.$mount()`, and re-exports their declaration merges. Client business packages depend on this facade rather than the Gateway implementation or individual Remote runtime entries.
 
 `createApiRemoteAgentResolver()` reuses live Agents, resumes ordinary cold sessions, deduplicates concurrent resumes, preserves the subagent ownership fence, and configures the same resolver for TypeRT `agent` and `session` lookups. The standard Web API Proxy supplies its Agent defaults and scope setup, then uses the returned resolver for legacy methods, so migrated and unmigrated methods share one policy implementation.
 
-The current Client assembly mounts only the Goal Remote contribution. Cordis effect ownership withdraws every contribution when this assembly unloads, while `@deepseek-ai/dsh-api-gateway/client` owns descriptor validation, concrete root and scoped methods, invocation, and cancellation. The Client entry consumes the shared `TypeRTClientApi` interface through Cordis and does not import the concrete Gateway.
+The current Client assembly mounts only the Goal Remote contribution. Cordis effect ownership withdraws every contribution when this assembly unloads, while `@deepseek-ai/dsh-api-gateway/client` owns descriptor validation, traced namespace Services, direct and scoped methods, invocation, and cancellation. The Client entry consumes the shared `TypeRTClientRemote` interface through Cordis and does not import the concrete Gateway.
 
-This package contains no transport or Host service discovery logic. Its Client face can be reused by Web or a future TUI that provides the same React-free `ctx.api` contract.
+This package contains no transport or Host service discovery logic. Its Client face can be reused by Web or a future TUI that provides the same React-free `ctx.remote` contract.
 
 ## Model Experience
 
diff --git a/packages/api/remotes/README.zh.md b/packages/api/remotes/README.zh.md
index 5cd7ef21c9..cce263747d 100644
--- a/packages/api/remotes/README.zh.md
+++ b/packages/api/remotes/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-为本应用选定的 Host Remote 能力提供双侧 BFF。Host 入口负责 Agent/Session 身份策略；Client 入口以运行时值形式导入生成的 `/remote` 产物，通过 `ctx.api` 挂载每项贡献，并重新导出对应的声明合并。Client 业务包依赖该外观，而不依赖 Gateway 实现或单独的 Remote 运行时入口。
+为本应用选定的 Host Remote 能力提供双侧 BFF。Host 入口负责 Agent/Session 身份策略；Client 入口以运行时值形式导入生成的 `/remote` 产物，通过 `ctx.remote.$mount()` 挂载每项贡献，并重新导出对应的声明合并。Client 业务包依赖该外观，而不依赖 Gateway 实现或单独的 Remote 运行时入口。
 
 `createApiRemoteAgentResolver()` 会复用 live Agent、恢复普通冷会话、对并发恢复去重、保留 subagent ownership fence，并为 TypeRT `agent` 和 `session` lookup 配置同一个 resolver。标准 Web API Proxy 提供 Agent 默认值和 scope 设置，再将返回的 resolver 用于旧方法，使已迁移与未迁移方法共用同一份策略实现。
 
-当前 Client 组合仅挂载 Goal Remote 贡献。该组合卸载时，Cordis effect 的所有权机制会撤回所有贡献；`@deepseek-ai/dsh-api-gateway/client` 负责描述符校验、具体的根级方法和作用域方法、调用与取消。Client 入口通过 Cordis 消费共享的 `TypeRTClientApi` 接口，不导入具体 Gateway。
+当前 Client 组合仅挂载 Goal Remote 贡献。该组合卸载时，Cordis effect 的所有权机制会撤回所有贡献；`@deepseek-ai/dsh-api-gateway/client` 负责描述符校验、可追踪 namespace Service、直接与作用域方法、调用与取消。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 接口，不导入具体 Gateway。
 
-本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.api` 契约，均可复用其 Client face。
+本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 契约，均可复用其 Client face。
 
 ## 模型体验
 
diff --git a/packages/api/remotes/src/client/index.ts b/packages/api/remotes/src/client/index.ts
index 1bc36b62ee..ebd342300e 100644
--- a/packages/api/remotes/src/client/index.ts
+++ b/packages/api/remotes/src/client/index.ts
@@ -2,25 +2,25 @@
 
 import type { Context } from 'cordis'
 import goalsRemote from '@deepseek-ai/dsh-goal/remote'
-import type { TypeRTClientApi } from '@deepseek-ai/dsh-type-meta'
+import type { TypeRTClientRemote } from '@deepseek-ai/dsh-type-meta'
 
-export type { TypeRTClientApi as ClientApi } from '@deepseek-ai/dsh-type-meta'
+export type { TypeRTClientRemote as ClientRemote } from '@deepseek-ai/dsh-type-meta'
 export type {} from '@deepseek-ai/dsh-goal/remote'
 
 declare module 'cordis' {
   interface Context {
-    /** Generated direct Remote namespaces selected by this Client assembly. */
-    api: TypeRTClientApi
+    /** Generated Remote namespaces selected by this Client assembly. */
+    remote: TypeRTClientRemote
   }
 }
 
-/** Required service: the typed Client API contribution mount. */
-export const inject = ['api']
+/** Required service: the typed Client Remote contribution mount. */
+export const inject = ['remote']
 
 /**
  * Mount the Host capabilities explicitly selected for this Client assembly.
  * @param ctx - Client Cordis root carrying the typed API service.
  */
-export function apply(ctx: Context): void {
-  ctx.api.mount(goalsRemote)
+export function apply(ctx: Context): Promise<() => Promise<void>> {
+  return ctx.remote.$mount(goalsRemote)
 }
diff --git a/packages/api/remotes/tests/built-lib.e2e.ts b/packages/api/remotes/tests/built-lib.e2e.ts
index b8f6c81e98..af584cba7f 100644
--- a/packages/api/remotes/tests/built-lib.e2e.ts
+++ b/packages/api/remotes/tests/built-lib.e2e.ts
@@ -143,18 +143,18 @@ describe.skipIf(!requiredArtifacts)('Goal Remote built LIB chain', () => {
 
       let invalidRejected = false
       try {
-        await client.api.goals.create(rootAgent.id, { objective: 1 })
+        await client.remote.goals.create(rootAgent.id, { objective: 1 })
       } catch {
         invalidRejected = true
       }
-      const rootResult = await client.api.goals.create(rootAgent.id, { objective: 'root goal' })
-      const rootEdit = await client.api.goals.edit(
+      const rootResult = await client.remote.goals.create(rootAgent.id, { objective: 'root goal' })
+      const rootEdit = await client.remote.goals.edit(
         rootAgent.id,
         rootResult.ref,
         { objective: 'edited root goal' },
       )
       const agentContext = client.extend({ builtAgentId: scopedAgent.id })
-      const scopedResult = await agentContext.goals.create({ objective: 'scoped goal', maxGoalRounds: 3 })
+      const scopedResult = await agentContext.remote.goals.create({ objective: 'scoped goal', maxGoalRounds: 3 })
       const result = {
         invalidRejected,
         rootResult,
diff --git a/packages/client/runtime/src/client/agents/scope.ts b/packages/client/runtime/src/client/agents/scope.ts
index ba4fd8ede7..1154d10feb 100644
--- a/packages/client/runtime/src/client/agents/scope.ts
+++ b/packages/client/runtime/src/client/agents/scope.ts
@@ -18,7 +18,12 @@
 import { Context as CordisContext } from 'cordis'
 import type { Context, Fiber } from 'cordis'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
-import type { TypeRTRemoteContextApi } from '@deepseek-ai/dsh-type-meta'
+import type { TypeRTClientRemote, TypeRTRemoteContextApi } from '@deepseek-ai/dsh-type-meta'
+
+/** Client Cordis Context carrying one Agent identity and its scoped Remote namespaces. */
+export type AgentContext = Omit<Context, 'remote'> & {
+  readonly remote: TypeRTClientRemote & TypeRTRemoteContextApi<'agent'>
+}
 
 /** Context tag written by {@link createScope}. */
 const kScope = Symbol('dsh.client.scope')
@@ -30,7 +35,7 @@ export interface AgentScopeHandle {
    * through it (passing it as the dispatch subject routes to this agent's
    * tagged listeners plus every untagged one).
    */
-  ctx: Context & TypeRTRemoteContextApi<'agent'>
+  ctx: AgentContext
   /** Backing fiber (dispose tears down every scope-owned registration). */
   fiber: Fiber
 }
@@ -55,7 +60,7 @@ export function createScope(ctx: Context, key: SessionId): AgentScopeHandle {
       const tag = scopeOf(listenerCtx)
       return tag === undefined || tag === key
     },
-  }) as Context & TypeRTRemoteContextApi<'agent'>
+  }) as AgentContext
   return {
     fiber,
     ctx: scoped,
diff --git a/packages/client/runtime/src/client/contract/sessions.ts b/packages/client/runtime/src/client/contract/sessions.ts
index 8e9c530720..2af2ef51c8 100644
--- a/packages/client/runtime/src/client/contract/sessions.ts
+++ b/packages/client/runtime/src/client/contract/sessions.ts
@@ -11,8 +11,8 @@ import type { Context } from 'cordis'
 import type {
   RpcResult, SessionId, SubagentAddress,
 } from '@deepseek-ai/dsh-client-connection/client'
-import type { TypeRTRemoteContextApi } from '@deepseek-ai/dsh-type-meta'
 import type { HostObservable, SessionMaybeProvideInfo } from '@deepseek-ai/dsh-client-ui-slots'
+import type { AgentContext } from '../agents/scope.ts'
 import type { SessionSearchResultItem } from '../sessions/manager.ts'
 import type {
   SessionBinding, SessionListState, SessionProvideDescriptor,
@@ -20,8 +20,7 @@ import type {
 import type { SessionFace } from './session.ts'
 import type { ObservableSnapshot } from './store.ts'
 
-/** Client Cordis Context carrying one Agent identity and its generated Remote namespaces. */
-export type AgentContext = Context & TypeRTRemoteContextApi<'agent'>
+export type { AgentContext } from '../agents/scope.ts'
 
 /** The sessions-service face injected as `ctx.sessions`. */
 export interface ISessions {
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index a9d2bb0d7d..b772e315a3 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -179,8 +179,8 @@ declare module 'cordis' {
   }
 }
 
-/** Required services: the typed Remote API, wire handle, and Client TypeRT registry. */
-export const inject = ['api', 'connection', 'typert']
+/** Required services: the Remote root and Goal namespace, wire handle, and Client TypeRT registry. */
+export const inject = ['remote', 'remote.goals', 'connection', 'typert']
 
 /** Mounts the browser runtime services and connection stream.
  * @param ctx - Client Cordis context.
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index 5635793122..e9b387fb00 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -38,7 +38,8 @@ async function mount(): Promise<Bench> {
     },
   }
   ctx.reflect.provide('connection', handle)
-  ctx.reflect.provide('api', {})
+  ctx.reflect.provide('remote', {})
+  ctx.reflect.provide('remote.goals', {})
   await ctx.plugin(RuntimeClient).await()
   return bench
 }
diff --git a/packages/client/runtime/tests/wire-events.spec.ts b/packages/client/runtime/tests/wire-events.spec.ts
index 5ab644682a..703c5b1728 100644
--- a/packages/client/runtime/tests/wire-events.spec.ts
+++ b/packages/client/runtime/tests/wire-events.spec.ts
@@ -32,7 +32,8 @@ async function mount(): Promise<Bench> {
     },
   }
   ctx.reflect.provide('connection', handle)
-  ctx.reflect.provide('api', {})
+  ctx.reflect.provide('remote', {})
+  ctx.reflect.provide('remote.goals', {})
   await ctx.plugin(RuntimeClient).await()
   return bench
 }
diff --git a/packages/client/ui-goal/README.i18n.yaml b/packages/client/ui-goal/README.i18n.yaml
index f30f14ed48..55853ef4bd 100644
--- a/packages/client/ui-goal/README.i18n.yaml
+++ b/packages/client/ui-goal/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/client/ui-goal/README.md
-README.md: b99aaf624a7d669879ba668938ee455e3cdc68ad
-README.zh.md: 3d823d013066bc912398f61c85553887e05ca3b4
+README.md: a53fb3a89eaee364cb025ca728ca42ce934887b0
+README.zh.md: 1ad9f50aee5b103f6455e4d4b7d29fa9eb29a108
diff --git a/packages/client/ui-goal/README.md b/packages/client/ui-goal/README.md
index b99aaf624a..a53fb3a89e 100644
--- a/packages/client/ui-goal/README.md
+++ b/packages/client/ui-goal/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Goal surface plugin, browser half: the `GoalBar` strip is the second standalone card in the `conversation.input.dock` composer-context stack (order 10, after Todo and before Queue). The live goal arrives through `useProjection('goal')` — the host-computed whole value seeded by the history tail page and updated by `session/projection` frames — so the plugin owns no domain store, refresh chain, or event listener. The slot inject face carries only the four mutation verbs (edit / pause / resume / clear through `ctx.api.goals` — an active goal offers the pause action, a paused one resume); each reads the CAS ref from the session's current projected value at call time and surfaces the rejected Remote error inline. The strip single-flights mutations synchronously because React's pending render cannot fence same-frame clicks; after a successful clear it immediately suppresses that exact goal id while the authoritative null projection catches up. Goal creation stays on the `/goal` host command; loading, absent, completed, and successfully cleared goals render nothing.
+Goal surface plugin, browser half: the `GoalBar` strip is the second standalone card in the `conversation.input.dock` composer-context stack (order 10, after Todo and before Queue). The live goal arrives through `useProjection('goal')` — the host-computed whole value seeded by the history tail page and updated by `session/projection` frames — so the plugin owns no domain store, refresh chain, or event listener. The slot inject face carries only the four mutation verbs (edit / pause / resume / clear through `ctx.remote.goals` — an active goal offers the pause action, a paused one resume); each reads the CAS ref from the session's current projected value at call time and surfaces the rejected Remote error inline. The strip single-flights mutations synchronously because React's pending render cannot fence same-frame clicks; after a successful clear it immediately suppresses that exact goal id while the authoritative null projection catches up. Goal creation stays on the `/goal` host command; loading, absent, completed, and successfully cleared goals render nothing.
 
 The `/client` export surface is the plugin body (`apply`/`inject`), the `GoalBar`/`GoalDock` components, and the injected verb face types.
 
diff --git a/packages/client/ui-goal/README.zh.md b/packages/client/ui-goal/README.zh.md
index 3d823d0130..1ad9f50aee 100644
--- a/packages/client/ui-goal/README.zh.md
+++ b/packages/client/ui-goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Goal 界面插件（浏览器端部分）：`GoalBar` 条带是 `conversation.input.dock` composer 上下文堆栈中的第二张独立卡片（order 10，位于 Todo 之后、Queue 之前）。活值经 `useProjection('goal')` 到达——host 计算的全量值由历史尾页播种、由 `session/projection` 帧更新——因此本插件不持有领域 store、不设刷新链、不挂事件监听。slot 注入面只携带四个变更动词（edit / pause / resume / clear，经 `ctx.api.goals` 调用——active 的 goal 提供暂停动作，paused 的提供恢复）；每个动词在调用时从会话当前投影值读取 CAS ref，并将 Remote 调用的拒绝错误内联呈现。由于 React 的 pending 渲染无法拦住同一帧内的点击，横条会同步为变更建立 single-flight 防护；清除成功后，会立即抑制该 goal id 对应的目标显示，直到权威的 null 投影追上。goal 的创建仍归 `/goal` host 命令；加载中、无 goal、已完成和已成功清除的 goal 一律不渲染。
+Goal 界面插件（浏览器端部分）：`GoalBar` 条带是 `conversation.input.dock` composer 上下文堆栈中的第二张独立卡片（order 10，位于 Todo 之后、Queue 之前）。活值经 `useProjection('goal')` 到达——host 计算的全量值由历史尾页播种、由 `session/projection` 帧更新——因此本插件不持有领域 store、不设刷新链、不挂事件监听。slot 注入面只携带四个变更动词（edit / pause / resume / clear，经 `ctx.remote.goals` 调用——active 的 goal 提供暂停动作，paused 的提供恢复）；每个动词在调用时从会话当前投影值读取 CAS ref，并将 Remote 调用的拒绝错误内联呈现。由于 React 的 pending 渲染无法拦住同一帧内的点击，横条会同步为变更建立 single-flight 防护；清除成功后，会立即抑制该 goal id 对应的目标显示，直到权威的 null 投影追上。goal 的创建仍归 `/goal` host 命令；加载中、无 goal、已完成和已成功清除的 goal 一律不渲染。
 
 `/client` 的导出接口包括插件本体（`apply`/`inject`）、`GoalBar`/`GoalDock` 组件与注入动词面类型。
 
diff --git a/packages/client/ui-goal/src/client/index.ts b/packages/client/ui-goal/src/client/index.ts
index bea4f67df2..2c041e0eae 100644
--- a/packages/client/ui-goal/src/client/index.ts
+++ b/packages/client/ui-goal/src/client/index.ts
@@ -9,7 +9,7 @@
  * Goal creation stays on the /goal host command.
  */
 import type { ClientContext, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
-// Type-only: pulls the generated Remote API and ctx.api merge through the Client assembly boundary.
+// Type-only: pulls the generated Remote API and ctx.remote merge through the Client assembly boundary.
 import type {} from '@deepseek-ai/dsh-api-remotes/client'
 // Type-only: pulls the ui-conversation SlotMap merge (the input.dock entry).
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
@@ -36,7 +36,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 const NS = 'goal'
 
 /** Required services: slots for the dock entry, sessions for the projected ref, API for Remote mutations, locale for the copy. */
-export const inject = ['slots', 'sessions', 'api', 'locale']
+export const inject = ['slots', 'sessions', 'remote', 'remote.goals', 'locale']
 
 /** Map one generated Remote call, including synchronous namespace lookup failures, onto the strip's inline-render shape. */
 async function settle(invoke: () => Promise<unknown>): Promise<GoalActionResult> {
@@ -94,22 +94,22 @@ export function apply(ctx: ClientContext): void {
       onEdit: async (objective) => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(() => ctx.api.goals.edit(sessionId, ref, { objective }))
+        return settle(() => ctx.remote.goals.edit(sessionId, ref, { objective }))
       },
       onPause: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(() => ctx.api.goals.pause(sessionId, ref))
+        return settle(() => ctx.remote.goals.pause(sessionId, ref))
       },
       onResume: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(() => ctx.api.goals.resume(sessionId, ref))
+        return settle(() => ctx.remote.goals.resume(sessionId, ref))
       },
       onClear: async () => {
         const ref = refOf(sessionId)
         if (ref === undefined) return noCurrentGoal
-        return settle(() => ctx.api.goals.clear(sessionId, ref))
+        return settle(() => ctx.remote.goals.clear(sessionId, ref))
       },
     }),
   }, GoalDock))
diff --git a/packages/client/ui-goal/tests/browser-plugin.spec.tsx b/packages/client/ui-goal/tests/browser-plugin.spec.tsx
index f900682712..756968136e 100644
--- a/packages/client/ui-goal/tests/browser-plugin.spec.tsx
+++ b/packages/client/ui-goal/tests/browser-plugin.spec.tsx
@@ -10,7 +10,7 @@
  * plugin fiber (HMR safety). The node half and the invariant companion are
  * exercised over the same Context.
  */
-import { Context } from 'cordis'
+import { Context, Service } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
 import { afterEach } from 'vitest'
@@ -71,8 +71,17 @@ async function bench(options: {
     clear: answer(`${prefix}/clear`, ref),
   })
   let activeGoals: ReturnType<typeof goals> | undefined = goals('goals')
-  ctx.provide('api', {
-    get goals() { return activeGoals },
+  class RemoteService extends Service {
+    constructor(serviceCtx: Context) {
+      super(serviceCtx, 'remote')
+    }
+  }
+  new RemoteService(ctx)
+  ctx.provide('remote.goals', {
+    get edit() { return activeGoals?.edit },
+    get pause() { return activeGoals?.pause },
+    get resume() { return activeGoals?.resume },
+    get clear() { return activeGoals?.clear },
   })
   await ctx.plugin(SlotsService).await()
   ctx.slots.register({
diff --git a/packages/typert/generator/tests/remote-model.spec.ts b/packages/typert/generator/tests/remote-model.spec.ts
index 27bdac2fac..eaaf680cc6 100644
--- a/packages/typert/generator/tests/remote-model.spec.ts
+++ b/packages/typert/generator/tests/remote-model.spec.ts
@@ -593,8 +593,8 @@ const created: Promise<CreateGoalResult> = create('agent-1', { title: 'ship' })
 const cancellable: Promise<CreateGoalResult> = create('agent-1', { title: 'ship' }, new AbortController().signal)
 const createdScoped: Promise<CreateGoalResult> = createScoped({ title: 'ship' })
 const renamed: Promise<RenameGoalResult> = rename({ ref: 'goal-1', title: 'land' })
-declare const ctx: { api: TypeRTRemoteNamespaceMap }
-const navigated: Promise<CreateGoalResult> = ctx.api.goals.create('agent-1', { title: 'navigate' })
+declare const ctx: { remote: TypeRTRemoteNamespaceMap }
+const navigated: Promise<CreateGoalResult> = ctx.remote.goals.create('agent-1', { title: 'navigate' })
 void contribution
 void created
 void cancellable
@@ -643,7 +643,7 @@ void navigated
     readFile: path => ts.sys.readFile(path),
     realpath: path => ts.sys.realpath?.(path) ?? path,
   })
-  const navigation = 'ctx.api.goals.create'
+  const navigation = 'ctx.remote.goals.create'
   const position = consumerSource.indexOf(navigation) + navigation.lastIndexOf('create') + 1
   const definitions = languageService.getDefinitionAtPosition(consumerPath, position)
   const generatedDefinition = definitions?.find(candidate => candidate.fileName === declarationPath)
@@ -672,8 +672,8 @@ function assertRemoteConsumerWithoutImportHasNoNamespace(consumerRoot: string):
   const consumerPath = join(consumerRoot, 'consumer-without-remote.ts')
   writeFileSync(consumerPath, `
 import type { TypeRTRemoteNamespaceMap } from '@deepseek-ai/dsh-type-meta'
-declare const ctx: { api: TypeRTRemoteNamespaceMap }
-ctx.api.goals.create('agent-1', { title: 'must not compile' })
+declare const ctx: { remote: TypeRTRemoteNamespaceMap }
+ctx.remote.goals.create('agent-1', { title: 'must not compile' })
 `)
   const configPath = join(consumerRoot, 'tsconfig.consumer-without-remote.json')
   writeFileSync(configPath, JSON.stringify({
diff --git a/packages/typert/type-meta/src/index.ts b/packages/typert/type-meta/src/index.ts
index 2f687f985f..774c6d3b32 100644
--- a/packages/typert/type-meta/src/index.ts
+++ b/packages/typert/type-meta/src/index.ts
@@ -41,7 +41,7 @@ export type {
   InvocationDescriptor,
   InvocationParameterDescriptor,
   InvocationSourceLocation,
-  TypeRTClientApi,
+  TypeRTClientRemote,
   TypeRTClientContextBinder,
   TypeRTCodec,
   TypeRTContext,
diff --git a/packages/typert/type-meta/src/types.ts b/packages/typert/type-meta/src/types.ts
index ed309b7857..5e7c20cd7c 100644
--- a/packages/typert/type-meta/src/types.ts
+++ b/packages/typert/type-meta/src/types.ts
@@ -77,7 +77,7 @@ export type TypeRTRemoteContextApi<ContextKey extends string> = {
   TypeRTRemoteContextNamespace<Namespace, ContextKey>
 }
 
-/** Merge-extensible direct namespace surface generated for Client API services. */
+/** Merge-extensible direct namespace surface generated for Client Remote services. */
 export interface TypeRTRemoteNamespaceMap {}
 
 /** Awaitable disposer returned by Cordis-owned TypeRT registrations. */
@@ -176,14 +176,14 @@ export interface TypeRTRemoteContribution {
   readonly descriptors: readonly InvocationDescriptor[]
 }
 
-/** Client API capability implemented by the Gateway and consumed by Remote assemblies. */
-export interface TypeRTClientApi extends TypeRTRemoteNamespaceMap {
+/** Client Remote capability implemented by the Gateway and consumed by Remote assemblies. */
+export interface TypeRTClientRemote extends TypeRTRemoteNamespaceMap {
   /**
    * Mount one generated Host-for-Client contribution in the caller's fiber.
    * @param contribution - explicitly selected Remote package artifact.
-   * @returns disposer withdrawing descriptors and concrete methods together.
+   * @returns disposer after namespace services and concrete methods are ready.
    */
-  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer
+  $mount(contribution: TypeRTRemoteContribution): Promise<TypeRTDisposer>
 }
 
 /**

From d362cdb54f228ddd0edda4771b5db64420eec04e Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 18:35:50 +0800
Subject: [PATCH 152/516] refactor(typert): rename RemoteContext to RemoteScope

---
 ...08-02-typert-remote-method-calls.i18n.yaml |  4 +--
 .../2026-08-02-typert-remote-method-calls.md  | 36 +++++++++----------
 ...026-08-02-typert-remote-method-calls.zh.md | 36 +++++++++----------
 docs/api-gateway.i18n.yaml                    |  4 +--
 docs/api-gateway.md                           | 14 ++++----
 docs/api-gateway.zh.md                        | 14 ++++----
 docs/development.i18n.yaml                    |  4 +--
 docs/development.md                           |  2 +-
 docs/development.zh.md                        |  2 +-
 packages/api/gateway/README.i18n.yaml         |  4 +--
 packages/api/gateway/README.md                |  4 +--
 packages/api/gateway/README.zh.md             |  4 +--
 packages/api/gateway/tests/client.spec.ts     |  6 ++--
 packages/api/gateway/tests/gateway.spec.ts    | 10 +++---
 .../client/runtime/src/client/agents/scope.ts |  4 +--
 packages/typert/generator/src/analyzer.ts     | 14 ++++----
 packages/typert/generator/src/emitter.ts      |  2 +-
 .../remote-model/packages/remote/src/index.ts |  4 +--
 .../fixtures/remote-model/type-meta.d.ts      |  4 +--
 .../generator/tests/remote-model.spec.ts      | 18 +++++-----
 packages/typert/type-meta/README.i18n.yaml    |  4 +--
 packages/typert/type-meta/README.md           |  4 +--
 packages/typert/type-meta/README.zh.md        |  4 +--
 packages/typert/type-meta/src/index.ts        | 14 ++++----
 packages/typert/type-meta/src/types.ts        | 20 +++++------
 .../type-meta/tests/fixtures/source-launch.ts |  4 +--
 .../typert/type-meta/tests/type-meta.spec.ts  | 14 ++++----
 27 files changed, 127 insertions(+), 127 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 341bf44923..71ded0fa8d 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: a8254090e042e4b359ae74fc5c19bad8abc5ef89
-2026-08-02-typert-remote-method-calls.zh.md: f1b7e5f9c61b474379962ce007e5d6bb966e5ebd
+2026-08-02-typert-remote-method-calls.md: 215c647bcd7413b92625ee670022dc7316e3045a
+2026-08-02-typert-remote-method-calls.zh.md: 0ce431b7cbc948e937f722f2769b15a1d26dcec9
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index a8254090e0..215c647bcd 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -16,7 +16,7 @@ The Host and Browser Client use separate TypeScript Programs because each side a
 
 ## Decision
 
-A business Service extends `GatewayService` and declares callable methods with `@Remote` or `@RemoteContext()`. A Service that already has another base class may instead expose the same binding through `bindTypeRTGateway()`. TypeRT generates the Host-local reflection artifact and a platform-independent Remote consumer projection from the Host Program. The Client Program continues to generate its own local reflection artifact independently.
+A business Service extends `GatewayService` and declares callable methods with `@Remote` or `@RemoteScope()`. A Service that already has another base class may instead expose the same binding through `bindTypeRTGateway()`. TypeRT generates the Host-local reflection artifact and a platform-independent Remote consumer projection from the Host Program. The Client Program continues to generate its own local reflection artifact independently.
 
 The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. The `.d.ts` exposes only methods marked with a Remote decorator and refers to the business package's single public type symbols. The `.d.ts.map` navigates consumer API methods back to their Host business method implementations. The `.js` carries endpoint, parameter, Context, and Zod information for the same contract. At the assembly layer, the Browser Client mounts the required Remote JS contributions onto the Client Remote Service. The projection and Remote abstraction remain platform-independent so that a future TUI can reuse them.
 
@@ -64,7 +64,7 @@ export class GoalService extends GatewayService {
 
 `goals` is the explicit Cordis service key passed to `super()` and is the default wire namespace. Pass a `namespace` option as the third argument only when the protocol namespace genuinely needs to differ from the service key.
 
-Use `@RemoteContext()` when the Service receiver must be resolved within an isolated kind of Context. Context identity does not enter the business method's parameters:
+Use `@RemoteScope()` when the Service receiver must be resolved within an isolated kind of Context. Scope identity does not enter the business method's parameters:
 
 ```text
 export class ScopedGoalService extends GatewayService {
@@ -72,28 +72,28 @@ export class ScopedGoalService extends GatewayService {
     super(ctx, 'goals')
   }
 
-  @RemoteContext('agent', 'create')
+  @RemoteScope('agent', 'create')
   remoteExportCreate(request: CreateGoalRequest): Promise<CreateGoalResult> {
     // Runs against the goals service resolved from the Agent Context.
   }
 }
 ```
 
-An endpoint selects exactly one invocation mode. A flow that needs an explicit `Agent` parameter uses `@Remote`. A flow that first switches to an Agent Context and then resolves a scoped receiver uses `@RemoteContext('agent')`. TypeRT does not infer either mode from the method body or from a missing parameter.
+An endpoint selects exactly one invocation mode. A flow that needs an explicit `Agent` parameter uses `@Remote`. A flow that first switches to an Agent Context and then resolves a scoped receiver uses `@RemoteScope('agent')`. TypeRT does not infer either mode from the method body or from a missing parameter.
 
-Business packages depend only on the lightweight `@deepseek-ai/dsh-type-meta`. It provides `GatewayService` and declaration protocols for decorators, the binding fallback, lookup, Remote Context, and descriptors, without depending on the TypeScript compiler, Zod, HTTP, or the Client runtime.
+Business packages depend only on the lightweight `@deepseek-ai/dsh-type-meta`. It provides `GatewayService` and declaration protocols for decorators, the binding fallback, lookup, Remote Scope, and descriptors, without depending on the TypeScript compiler, Zod, HTTP, or the Client runtime.
 
 A method that cooperatively supports cancellation declares `signal: AbortSignal` as its final Host parameter. This reserved parameter is not a business value, lookup, or JSON field. The generated consumer method exposes it as a final optional parameter so ordinary calls remain unchanged while callers that own cancellation can pass a signal.
 
 ## Decorators and the explicit Gateway facet
 
-A decorator only states that a method participates in the Remote contract. It performs no runtime type reflection and injects no hidden symbol into a Service constructor. The arguments to `@Remote('create')` and `@RemoteContext('agent', 'create')` are external method names; the decorated member may be the business method itself or an adapter such as `remoteExportCreate`. The member name becomes the external method name only when no alias is provided. Inheriting `GatewayService` is the normal explicit declaration that a Service has joined the Gateway; its public readonly `typertGateway` field keeps the binding visible on the runtime instance.
+A decorator only states that a method participates in the Remote contract. It performs no runtime type reflection and injects no hidden symbol into a Service constructor. The arguments to `@Remote('create')` and `@RemoteScope('agent', 'create')` are external method names; the decorated member may be the business method itself or an adapter such as `remoteExportCreate`. The member name becomes the external method name only when no alias is provided. Inheriting `GatewayService` is the normal explicit declaration that a Service has joined the Gateway; its public readonly `typertGateway` field keeps the binding visible on the runtime instance.
 
 In SRC mode, the decorator may record the prototype, method name, and invocation mode in a `WeakMap` internal to `dsh-type-meta`. It writes no custom properties to a Service instance, prototype, constructor, or method function.
 
 In LIB mode, the TypeRT compiler performs strict method discovery, type resolution, and descriptor generation. It accepts a literal service key in `GatewayService`'s direct `super()` call or the explicit binding fallback; generation neither rewrites business source nor injects hidden registration metadata.
 
-## Lookup and Remote Context registration
+## Lookup and Remote Scope registration
 
 The Gateway has no built-in branches for Agent, Session, or other business objects. Each object-owning package provides both a static declaration and a runtime provider:
 
@@ -115,7 +115,7 @@ The static declaration tells TypeRT that `Agent` corresponds to `SessionId` on t
 
 Lookup objects such as Agent and Session may each occupy only one top-level parameter position. An ordinary JSON request may be passed as another complete parameter, but this design does not support `request.agent`, object destructuring, arrays of objects, nested lookups, or searching arbitrary complex structures for IDs.
 
-Remote Context uses a separate merge-extensible map and provider. The Agent package registers an `agent` Context provider that locates the Agent Context from its wire identity and resolves the Service key named by the descriptor from that Context. The Gateway does not know the internal structure of an Agent Context.
+Remote Scope uses a separate merge-extensible map and Context provider. The Agent package registers an `agent` provider that locates the Agent Context from its wire identity and resolves the Service key named by the descriptor from that Context. The Gateway does not know the internal structure of an Agent Context.
 
 The Client also registers an `agent` Context binder. The binder only retrieves a `SessionId` from the Context in which a call occurs; it neither enumerates Scopes nor copies methods into each one. A Cordis Service tracker automatically rebinds a scoped namespace to the current Agent Context.
 
@@ -267,7 +267,7 @@ interface TypeRTRemoteNamespaceMap {
   goals: TypeRTRemoteNamespace$676f616c73
 }
 
-interface TypeRTRemoteContextMap {
+interface TypeRTRemoteScopeMap {
   'agent:goals/create': (
     request: CreateGoalRequest,
     signal?: AbortSignal,
@@ -277,14 +277,14 @@ interface TypeRTRemoteContextMap {
 
 `TypeRTRemoteMap` preserves canonical endpoint signatures for protocol typing and reflection. The root Remote type reads `TypeRTRemoteNamespaceMap` directly instead of deriving methods indirectly through a key-remapped mapped type; the TypeScript Language Service cannot reliably navigate such indirect properties through a declaration map. A namespace interface name encodes the namespace's UTF-8 bytes as hexadecimal, so `goals` deterministically becomes `TypeRTRemoteNamespace$676f616c73`. Different packages generate the same interface name for the same namespace and use module augmentation to merge their methods, while `TypeRTRemoteNamespaceMap.goals` always refers to that one type.
 
-TypeRT projects `TypeRTRemoteContextMap` onto a dedicated Scope type according to its Context key. The final programming interface remains:
+TypeRT projects `TypeRTRemoteScopeMap` onto a dedicated Scope type according to its Context key. The final programming interface remains:
 
 ```text
 ctx.remote.goals.create(agentId, request)
 agentCtx.remote.goals.create(request)
 ```
 
-The Agent Scope supplies its own `SessionId` automatically. A `@Remote` method with an `agent` lookup can therefore generate both root and scoped consumer signatures. A `@RemoteContext('agent')` method also omits a separate Context identity, but generates only the scoped signature. The root `Context` exposes direct namespaces through `ctx.remote`, while `AgentContext.remote` intersects that direct surface with the scoped surface. A future TUI must preserve the same distinction.
+The Agent Scope supplies its own `SessionId` automatically. A `@Remote` method with an `agent` lookup can therefore generate both root and scoped consumer signatures. A `@RemoteScope('agent')` method also omits a separate Scope identity, but generates only the scoped signature. The root `Context` exposes direct namespaces through `ctx.remote`, while `AgentContext.remote` intersects that direct surface with the scoped surface. A future TUI must preserve the same distinction.
 
 `TypeRTClientRemote` remains platform-independent, and the Browser Client exposes it as `ctx.remote`. If a future TUI reuses this type, it must likewise access it through a dedicated Remote object and Agent Scope rather than treating the Host `Context` as a broader Service collection. Public Service methods without Remote markers do not enter the Remote maps.
 
@@ -313,7 +313,7 @@ Client business packages depend only on `@deepseek-ai/dsh-api-remotes/client`, n
 
 The Client Remote Service materializes each `@Remote` descriptor as a real function on a `remote.<namespace>` child Service. The function constructs named `args` in descriptor parameter order, applies the Client's strict codec, and then calls `ctx.connection.rpc.call('/api', endpoint, { args }, signal)`. For a cancellation-aware descriptor, the generated function accepts a final optional signal and combines it with the contribution mount lifetime; unmounting therefore cancels every in-flight carrier call, while a caller can cancel one call independently.
 
-Neither a direct descriptor with `scope` nor a `@RemoteContext` descriptor copies functions into every Agent Scope. The Client Remote Service creates one Cordis child Service per namespace, registered as `remote.<namespace>`, and materializes direct and scoped variants on it. Accessing a method through `agentCtx.remote.goals` captures the current Agent Context before returning the callable handle. The method then asks the corresponding Context binder for identity from that Context. A direct scoped projection substitutes this identity at the lookup position named by `scope.wire`; a Context descriptor writes the identity into the receiver's separate wire field. Both issue the same kind of `/api` call.
+Neither a direct descriptor with `scope` nor a `@RemoteScope` descriptor copies functions into every Agent Scope. The Client Remote Service creates one Cordis child Service per namespace, registered as `remote.<namespace>`, and materializes direct and scoped variants on it. Accessing a method through `agentCtx.remote.goals` captures the current Agent Context before returning the callable handle. The method then asks the corresponding Context binder for identity from that Context. A direct scoped projection substitutes this identity at the lookup position named by `scope.wire`; a Remote Scope descriptor writes the identity into the receiver's separate wire field. Both issue the same kind of `/api` call.
 
 ```text
 root ctx.remote.goals.create(agentId, request)
@@ -327,7 +327,7 @@ agentCtx.remote.goals.create(request)
   → ctx.connection.rpc.call('/api', 'goals/create', { args })
 ```
 
-The root `Context` merges only the direct `TypeRTClientRemote` surface. `AgentContext` replaces that property with the intersection of `TypeRTClientRemote` and `TypeRTRemoteContextApi<'agent'>`, so scoped-only methods remain unavailable from root code. If a caller bypasses the type system and dynamically calls a scoped-only method from Root, the binder reports an explicit error. If the Client already has a Cordis service named `remote.<namespace>`, or two contributions claim the same namespace and method incompatibly, mounting fails instead of overwriting the existing service.
+The root `Context` merges only the direct `TypeRTClientRemote` surface. `AgentContext` replaces that property with the intersection of `TypeRTClientRemote` and `TypeRTRemoteScopeApi<'agent'>`, so scoped-only methods remain unavailable from root code. If a caller bypasses the type system and dynamically calls a scoped-only method from Root, the binder reports an explicit error. If the Client already has a Cordis service named `remote.<namespace>`, or two contributions claim the same namespace and method incompatibly, mounting fails instead of overwriting the existing service.
 
 Generated Remote JS contains only descriptors, symbol keys, and codecs; it does not bundle Host Service implementations. The Client Remote Service creates real functions from that data, so the runtime does not depend on a JavaScript Proxy. A Proxy remains an implementation option but is not a source of types or reflection.
 
@@ -337,7 +337,7 @@ Remote API is a consumer capability, not a synonym for Browser API. The shipped
 
 Remote DTS, Remote JS, `TypeRTClientRemote`, `InvocationDescriptor`, the Remote RPC data protocol, and Context binders must not depend on the DOM, Browser module loaders, or HTTP. Through Connection, the Browser Client encodes descriptor-materialized methods as `/api` RPC calls.
 
-A future TUI can join the same call abstraction without changing business decorators, Remote maps, or the shape of API calls. The TUI-visible API must still be generated exclusively from `@Remote` and `@RemoteContext`; sharing a process with the Host must not allow it to bypass Remote restrictions and expose Service methods directly.
+A future TUI can join the same call abstraction without changing business decorators, Remote maps, or the shape of API calls. The TUI-visible API must still be generated exclusively from `@Remote` and `@RemoteScope`; sharing a process with the Host must not allow it to bypass Remote restrictions and expose Service methods directly.
 
 TUI runtime mounting, carriers, Agent Scope association, and SRC startup wiring are outside this phase.
 
@@ -345,7 +345,7 @@ The Web already depends on build artifacts such as `lib/client.js`, so it requir
 
 ## SRC and LIB operating modes
 
-SRC supports local source startup. The `WeakMap` records created by `@Remote` and `@RemoteContext()` provide method names and invocation modes. At runtime, the system reads ordered parameter names from the JavaScript function signature and combines them with registered lookup/Context providers to produce a permissive descriptor.
+SRC supports local source startup. The `WeakMap` records created by `@Remote` and `@RemoteScope()` provide method names and invocation modes. At runtime, the system reads ordered parameter names from the JavaScript function signature and combines them with registered lookup/Context providers to produce a permissive descriptor.
 
 For example, `@Remote('create') remoteExportCreate(agent, request, signal)` resolves to the external method `create`, implementation member `remoteExportCreate`, two top-level business parameters, and one cancellation injection point. Lookup registration rewrites `agent` to the wire field `agentId`, `request` is passed as a same-named JSON parameter, and the final `signal` stays outside the payload. SRC does not start a `ts.Program`, use a preload or loader hook, generate or rewrite source, or inspect the internal structure of an ordinary JSON object.
 
@@ -365,7 +365,7 @@ Invocation resolves the descriptor, receiver, lookup providers, and Context prov
 
 An ordinary `@Remote` call retains the original Service instance as receiver. After lookups succeed, the Gateway calls the member identified by `implementation ?? method` with parameters in descriptor order, followed by the carrier signal when the descriptor declares cancellation.
 
-A `@RemoteContext('agent')` call first asks the Agent Context provider to resolve the wire identity, then reads the descriptor's service key from that Context and invokes the scoped receiver. The business method receives neither a hidden Context parameter nor an Agent ID.
+A `@RemoteScope('agent')` call first asks the Agent Context provider to resolve the wire identity, then reads the descriptor's service key from that Context and invokes the scoped receiver. The business method receives neither a hidden Context parameter nor an Agent ID.
 
 ```text
 ctx.typertGateway.invoke({ namespace, method, args, signal })
@@ -448,7 +448,7 @@ The Gateway registers only its ownership matcher and RPC handler with Connection
 
 ## Package boundaries
 
-- `@deepseek-ai/dsh-type-meta`: lightweight protocols for decorators, bindings, lookup, Remote Context, and descriptors.
+- `@deepseek-ai/dsh-type-meta`: lightweight protocols for decorators, bindings, lookup, Remote Scope, and descriptors.
 - TypeRT generator: analyzes Host/Client Programs, generates local faces and Remote consumer projections, and emits canonical symbol/Zod information.
 - TypeRT runtime: separately stores the current environment's local reflection and imported Remote contributions.
 - `@deepseek-ai/dsh-api-gateway`: its default entry associates Host definitions with Services, claims Remote endpoints, performs lookup, resolves Context receivers, invokes methods, encodes results, and registers an `/api` interceptor with Connection; its `/client` entry mounts Remote contributions, creates strict Remote namespace Services and methods, and delegates calls to `ctx.connection.rpc`. The entries share the Remote protocol but do not import each other's Cordis interface merges.
@@ -460,7 +460,7 @@ The Gateway registers only its ownership matcher and RPC handler with Connection
 
 ## Shipped scope and deferred work
 
-The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client Remote → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`. The same direct descriptor with an Agent lookup supports both `ctx.remote.goals.create(agentId, request)` and `agentCtx.remote.goals.create(request)`. Ordinary cold sessions are resumed through `agentFor()` during lookup, while subagent-owned identities retain the existing `agent-busy` fence; `@RemoteContext('agent')` remains the distinct scoped-receiver mode.
+The shipped vertical path is `@deepseek-ai/dsh-goal/remote → Browser Client Remote → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`. The same direct descriptor with an Agent lookup supports both `ctx.remote.goals.create(agentId, request)` and `agentCtx.remote.goals.create(request)`. Ordinary cold sessions are resumed through `agentFor()` during lookup, while subagent-owned identities retain the existing `agent-busy` fence; `@RemoteScope('agent')` remains the distinct scoped-receiver mode.
 
 Connection supplies the shared-channel interceptor and current HTTP carrier mapping. WebSocket migration, the TUI runtime and carrier, TUI Agent Scope wiring, Permission/Approval state machines, Session event streams, call authorization, retries, idempotency, and cross-version protocol compatibility remain outside this decision.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index f1b7e5f9c6..0ce431b7cb 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -16,7 +16,7 @@ Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以
 
 ## 决策
 
-业务 Service 继承 `GatewayService`，并通过 `@Remote` 或 `@RemoteContext()` 声明可调用方法；已有其他基类的 Service 可以改用 `bindTypeRTGateway()` 暴露同一绑定。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
+业务 Service 继承 `GatewayService`，并通过 `@Remote` 或 `@RemoteScope()` 声明可调用方法；已有其他基类的 Service 可以改用 `bindTypeRTGateway()` 暴露同一绑定。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
 
 Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client Remote Service；该投影和 Remote 抽象保持平台无关，以便未来 TUI 复用。
 
@@ -64,7 +64,7 @@ export class GoalService extends GatewayService {
 
 `goals` 是传给 `super()` 的明确 Cordis service key，并默认作为 wire namespace。只有协议 namespace 确实需要与 service key 不同时，才通过第三个参数传入 `namespace` 选项。
 
-需要在某类隔离 Context 中查找 Service receiver 时使用 `@RemoteContext()`。Context identity 不进入业务方法参数：
+需要在某类隔离 Context 中查找 Service receiver 时使用 `@RemoteScope()`。Scope identity 不进入业务方法参数：
 
 ```text
 export class ScopedGoalService extends GatewayService {
@@ -72,28 +72,28 @@ export class ScopedGoalService extends GatewayService {
     super(ctx, 'goals')
   }
 
-  @RemoteContext('agent', 'create')
+  @RemoteScope('agent', 'create')
   remoteExportCreate(request: CreateGoalRequest): Promise<CreateGoalResult> {
     // Runs against the goals service resolved from the Agent Context.
   }
 }
 ```
 
-同一个 endpoint 只能选择一种调用模式。需要显式 `Agent` 参数的流程使用 `@Remote`；需要切换到 Agent Context 再解析 scoped receiver 的流程使用 `@RemoteContext('agent')`，两者不会由 TypeRT 根据方法体或参数缺失自动猜测。
+同一个 endpoint 只能选择一种调用模式。需要显式 `Agent` 参数的流程使用 `@Remote`；需要切换到 Agent Context 再解析 scoped receiver 的流程使用 `@RemoteScope('agent')`，两者不会由 TypeRT 根据方法体或参数缺失自动猜测。
 
-业务包只依赖轻量的 `@deepseek-ai/dsh-type-meta`。它提供 `GatewayService`，以及 decorator、binding 回退、lookup、Remote Context 和 descriptor 的声明协议，不依赖 TypeScript compiler、Zod、HTTP 或 Client runtime。
+业务包只依赖轻量的 `@deepseek-ai/dsh-type-meta`。它提供 `GatewayService`，以及 decorator、binding 回退、lookup、Remote Scope 和 descriptor 的声明协议，不依赖 TypeScript compiler、Zod、HTTP 或 Client runtime。
 
 支持协作式取消的方法会把 `signal: AbortSignal` 声明为最后一个 Host 参数。这个保留参数不是业务值、lookup 或 JSON 字段。生成的消费方方法将其暴露为最后一个可选参数，因此普通调用保持不变，而拥有取消控制权的调用方可以传入 signal。
 
 ## Decorator 与显式 Gateway facet
 
-Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteContext('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
+Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteScope('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
 
 SRC 运行时允许 decorator 在 `dsh-type-meta` 内部的 `WeakMap` 记录 prototype、方法名和调用模式。它不向 Service 实例、prototype、constructor 或方法函数写入自定义属性。
 
 LIB 的严格方法发现、类型解析和 descriptor 生成由 TypeRT compiler 完成。它接受 `GatewayService` 直接 `super()` 调用中的字面量 service key，或显式 binding 回退；生成过程不改写业务源码，也不注入隐藏注册元数据。
 
-## Lookup 与 Remote Context 注册
+## Lookup 与 Remote Scope 注册
 
 Gateway 不内置 Agent、Session 或其他业务对象分支。对象所属包同时提供静态声明和运行时 provider：
 
@@ -115,7 +115,7 @@ ctx.typert.lookups.register('agent', {
 
 Agent、Session 等 lookup 对象只能各自占据一个顶层参数位置。普通 JSON request 可以作为另一个完整参数传入，但本设计不支持 `request.agent`、对象解构、对象数组、嵌套 lookup 或从任意复杂结构中搜索 ID。
 
-Remote Context 使用独立的 merge-extensible map 和 provider。Agent 包注册 `agent` Context provider，负责用 wire identity 找到 Agent Context，并从该 Context 解析 descriptor 指定的 service key；Gateway 不知道 Agent Context 的内部结构。
+Remote Scope 使用独立的 merge-extensible map 和 Context provider。Agent 包注册 `agent` provider，负责用 wire identity 找到 Agent Context，并从该 Context 解析 descriptor 指定的 service key；Gateway 不知道 Agent Context 的内部结构。
 
 Client 侧也注册 `agent` Context binder。binder 只负责从一次调用所在的 Context 取得 `SessionId`；它不枚举 Scope，也不逐个复制方法。scoped namespace 由 Cordis Service tracker 自动 rebind 到当前 Agent Context。
 
@@ -267,7 +267,7 @@ interface TypeRTRemoteNamespaceMap {
   goals: TypeRTRemoteNamespace$676f616c73
 }
 
-interface TypeRTRemoteContextMap {
+interface TypeRTRemoteScopeMap {
   'agent:goals/create': (
     request: CreateGoalRequest,
     signal?: AbortSignal,
@@ -277,14 +277,14 @@ interface TypeRTRemoteContextMap {
 
 `TypeRTRemoteMap` 保留规范 endpoint 签名，供协议类型和反射使用。根 Remote 类型直接读取 `TypeRTRemoteNamespaceMap`，不通过 key-remapped mapped type 间接推导方法；TypeScript Language Service 无法把这种间接属性稳定导航到 declaration map。namespace interface 名由 namespace 的 UTF-8 bytes 编成 hex，`goals` 因而稳定得到 `TypeRTRemoteNamespace$676f616c73`。不同 package 对同一 namespace 生成同名 interface，依靠 module augmentation 合并各自方法，且 `TypeRTRemoteNamespaceMap.goals` 始终引用同一类型。
 
-TypeRT 把 `TypeRTRemoteContextMap` 按 Context key 投影到专用 Scope 类型。最终编程界面保持：
+TypeRT 把 `TypeRTRemoteScopeMap` 按 Context key 投影到专用 Scope 类型。最终编程界面保持：
 
 ```text
 ctx.remote.goals.create(agentId, request)
 agentCtx.remote.goals.create(request)
 ```
 
-Agent Scope 自动提供自己的 `SessionId`。因此带 `agent` lookup 的 `@Remote` 方法可以同时生成 root 和 scoped 两种消费端签名；`@RemoteContext('agent')` 方法也省略独立的 Context identity，但只生成 scoped 签名。根 `Context` 通过 `ctx.remote` 暴露 direct namespace，`AgentContext.remote` 则把该 direct surface 与 scoped surface 取交集。未来 TUI 复用时必须维持相同区分。
+Agent Scope 自动提供自己的 `SessionId`。因此带 `agent` lookup 的 `@Remote` 方法可以同时生成 root 和 scoped 两种消费端签名；`@RemoteScope('agent')` 方法也省略独立的 Scope identity，但只生成 scoped 签名。根 `Context` 通过 `ctx.remote` 暴露 direct namespace，`AgentContext.remote` 则把该 direct surface 与 scoped surface 取交集。未来 TUI 复用时必须维持相同区分。
 
 `TypeRTClientRemote` 保持平台无关，Browser Client 通过 `ctx.remote` 暴露它。未来 TUI 若复用该类型，也必须通过专用 Remote 对象和 Agent Scope 使用它，不能把 Host `Context` 当成更宽的 Service 集合；未标记的 public Service 方法不会进入 Remote maps。
 
@@ -313,7 +313,7 @@ Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依
 
 Client Remote Service 把 `@Remote` descriptor 实体化为 `remote.<namespace>` 子 Service 上的真实函数。函数按 descriptor 的位置参数顺序构造具名 `args`，执行 Client strict codec，然后调用 `ctx.connection.rpc.call('/api', endpoint, { args }, signal)`。对于支持取消的 descriptor，生成的函数接受最后一个可选 signal，并将其与 contribution 的挂载生命周期合并；因此卸载会取消所有正在进行的 carrier 调用，而调用方也可以单独取消一次调用。
 
-带 `scope` 的 direct descriptor 和 `@RemoteContext` descriptor 都不为每个 Agent Scope 复制函数。Client Remote Service 为每个 namespace 创建一个注册为 `remote.<namespace>` 的 Cordis 子 Service，并在其上实体化 direct 与 scoped 变体。通过 `agentCtx.remote.goals` 取得方法时，accessor 会在返回可调用句柄前捕获当前 Agent Context。方法再通过对应 Context binder 从该 Context 取得 identity。direct scoped 投影用 identity 替代 `scope.wire` 指定的 lookup 位置，Context descriptor 则把 identity 写入 receiver 的独立 wire 字段；两者都发起同一种 `/api` 调用。
+带 `scope` 的 direct descriptor 和 `@RemoteScope` descriptor 都不为每个 Agent Scope 复制函数。Client Remote Service 为每个 namespace 创建一个注册为 `remote.<namespace>` 的 Cordis 子 Service，并在其上实体化 direct 与 scoped 变体。通过 `agentCtx.remote.goals` 取得方法时，accessor 会在返回可调用句柄前捕获当前 Agent Context。方法再通过对应 Context binder 从该 Context 取得 identity。direct scoped 投影用 identity 替代 `scope.wire` 指定的 lookup 位置，Remote Scope descriptor 则把 identity 写入 receiver 的独立 wire 字段；两者都发起同一种 `/api` 调用。
 
 ```text
 root ctx.remote.goals.create(agentId, request)
@@ -327,7 +327,7 @@ agentCtx.remote.goals.create(request)
   → ctx.connection.rpc.call('/api', 'goals/create', { args })
 ```
 
-根 `Context` 只 merge direct `TypeRTClientRemote` surface；`AgentContext` 把该属性替换为 `TypeRTClientRemote` 与 `TypeRTRemoteContextApi<'agent'>` 的交叉，因而 scoped-only 方法不会暴露给 root 代码。若调用方绕过类型从 Root 动态调用 scoped-only 方法，binder 明确报错。若 Client 已有名为 `remote.<namespace>` 的 Cordis service，或两个 contribution 冲突占用同一 namespace/method，mount 直接失败，不覆盖现有服务。
+根 `Context` 只 merge direct `TypeRTClientRemote` surface；`AgentContext` 把该属性替换为 `TypeRTClientRemote` 与 `TypeRTRemoteScopeApi<'agent'>` 的交叉，因而 scoped-only 方法不会暴露给 root 代码。若调用方绕过类型从 Root 动态调用 scoped-only 方法，binder 明确报错。若 Client 已有名为 `remote.<namespace>` 的 Cordis service，或两个 contribution 冲突占用同一 namespace/method，mount 直接失败，不覆盖现有服务。
 
 生成的 Remote JS 只包含 descriptor、symbol key 和 codec，不打包 Host Service 实现。Client Remote Service 据此创建真实函数，因此运行时不依赖 JavaScript Proxy；Proxy 可以作为实现选择，但不会成为类型或反射来源。
 
@@ -337,7 +337,7 @@ Remote API 是消费端能力，不等同于 Browser API。已交付的运行时
 
 Remote DTS、Remote JS、`TypeRTClientRemote`、`InvocationDescriptor`、Remote RPC 数据协议和 Context binder 不得依赖 DOM、Browser module loader 或 HTTP。Browser Client 通过 Connection 把 descriptor 实体化的方法编码为 `/api` RPC 调用。
 
-未来 TUI 可以在不改变业务 decorator、Remote maps 和 API 调用形状的前提下接入同一调用抽象。届时 TUI 可见的 API 仍只能由 `@Remote` 和 `@RemoteContext` 生成，不能因为它与 Host 同进程就绕过 Remote 限制直接暴露 Service 方法。
+未来 TUI 可以在不改变业务 decorator、Remote maps 和 API 调用形状的前提下接入同一调用抽象。届时 TUI 可见的 API 仍只能由 `@Remote` 和 `@RemoteScope` 生成，不能因为它与 Host 同进程就绕过 Remote 限制直接暴露 Service 方法。
 
 TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均不属于本期实现。
 
@@ -345,7 +345,7 @@ Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完
 
 ## SRC 与 LIB 运行模式
 
-SRC 面向本地源码启动。`@Remote` 和 `@RemoteContext()` 的 WeakMap 记录给出方法名和调用模式，运行时从 JavaScript 函数签名读取顺序参数名，并结合已注册 lookup/Context provider 生成弱 descriptor。
+SRC 面向本地源码启动。`@Remote` 和 `@RemoteScope()` 的 WeakMap 记录给出方法名和调用模式，运行时从 JavaScript 函数签名读取顺序参数名，并结合已注册 lookup/Context provider 生成弱 descriptor。
 
 例如 `@Remote('create') remoteExportCreate(agent, request, signal)` 解析为外部方法 `create`、实现成员 `remoteExportCreate`、两个顶层业务参数和一个取消注入点；lookup 注册把 `agent` 改写为 wire 字段 `agentId`，`request` 按同名 JSON 参数传递，最后一个 `signal` 则留在 payload 之外。SRC 不启动 `ts.Program`，不使用 preload、loader hook、源码生成或模块改写，也不检查普通 JSON 对象的内部结构。
 
@@ -365,7 +365,7 @@ Host Gateway 向 Connection 注册一个 `/api` interceptor，不维护第二份
 
 普通 `@Remote` 调用保留原始 Service 实例作为 receiver。lookup 成功后，Gateway 按 descriptor 的参数顺序调用 `implementation ?? method` 指定的成员；若 descriptor 声明取消，则在这些参数之后追加 carrier signal。
 
-`@RemoteContext('agent')` 调用先由 Agent Context provider 解析 wire identity，再从该 Context 读取 descriptor 的 service key 并调用 scoped receiver。业务方法不会收到隐藏 Context 参数或 Agent ID。
+`@RemoteScope('agent')` 调用先由 Agent Context provider 解析 wire identity，再从该 Context 读取 descriptor 的 service key 并调用 scoped receiver。业务方法不会收到隐藏 Context 参数或 Agent ID。
 
 ```text
 ctx.typertGateway.invoke({ namespace, method, args, signal })
@@ -448,7 +448,7 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 
 ## 包边界
 
-- `@deepseek-ai/dsh-type-meta`：轻量 decorator、binding、lookup、Remote Context 和 descriptor 协议。
+- `@deepseek-ai/dsh-type-meta`：轻量 decorator、binding、lookup、Remote Scope 和 descriptor 协议。
 - TypeRT generator：分析 Host/Client Program，生成本地 face 和 Remote 消费端投影，并生成规范 symbol/Zod 信息。
 - TypeRT runtime：分别保存当前环境的 local reflection 与导入的 Remote contribution。
 - `@deepseek-ai/dsh-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 Remote namespace Service 和方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
@@ -460,7 +460,7 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 
 ## 已交付范围与后续工作
 
-已交付的纵向链路是 `@deepseek-ai/dsh-goal/remote → Browser Client Remote → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`。同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.remote.goals.create(agentId, request)` 与 `agentCtx.remote.goals.create(request)`。普通冷会话在 lookup 时通过 `agentFor()` 恢复，subagent-owned identity 保持既有 `agent-busy` fence；`@RemoteContext('agent')` 仍是独立的 scoped receiver 模式。
+已交付的纵向链路是 `@deepseek-ai/dsh-goal/remote → Browser Client Remote → Connection RPC /api → Host Gateway → GoalService.remoteExportCreate()`。同一个带 Agent lookup 的 direct descriptor 同时支持 `ctx.remote.goals.create(agentId, request)` 与 `agentCtx.remote.goals.create(request)`。普通冷会话在 lookup 时通过 `agentFor()` 恢复，subagent-owned identity 保持既有 `agent-busy` fence；`@RemoteScope('agent')` 仍是独立的 scoped receiver 模式。
 
 Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebSocket 迁移、TUI runtime 与 carrier、TUI Agent Scope 接线、Permission/Approval 状态机、Session 事件流、调用授权、重试、幂等及跨版本协议兼容均不属于本决策。
 
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index d07272c182..2a6ae0807b 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.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 docs/api-gateway.md
-api-gateway.md: 90aa661cc86a4f419e173560c55511c969182990
-api-gateway.zh.md: 6fcbb562b204e71d00833042ee0632bda0217940
+api-gateway.md: ba95d429dd0c9f9f354baf0063197cea6e3ecbf8
+api-gateway.zh.md: 4e42ebea7a5db19c7df23079050b9488679a3a23
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index 90aa661cc8..ba95d429dd 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -6,17 +6,17 @@ This is the current-state reference for the TypeRT API Gateway. It describes how
 
 ## Programming model
 
-Business services use `@Remote` or `@RemoteContext` to select the methods exposed to the Client. Unmarked methods do not enter the generated Client types or runtime contributions and cannot be called through `ctx.remote`.
+Business services use `@Remote` or `@RemoteScope` to select the methods exposed to the Client. Unmarked methods do not enter the generated Client types or runtime contributions and cannot be called through `ctx.remote`.
 
 `@Remote` denotes calling a Cordis service registered on the root Host Context. Complex Host objects cannot cross the wire directly; the business package must declare their association with a wire identity through `TypeRTLookupMap` and register a default resolution provider with `ctx.typert.lookups` at runtime. For example, an `Agent` parameter named `agent` in the Host signature produces an `agentId` wire field, and the Gateway resolves that id to a Host object before invoking the business method. Host composition can use `ctx.typert.lookups.configure()` to override the resolution policy for a lookup key without changing the parameter name, wire field, or canonical type symbol owned by the business package.
 
-`@RemoteContext(key)` first resolves an identity to a scoped Context through `ctx.typert.contexts`, then obtains the service from that Context and invokes the method. It applies when the method itself depends on scoped composition and does not need to receive objects such as `Agent` explicitly.
+`@RemoteScope(key)` first resolves an identity to a scoped Context through `ctx.typert.contexts`, then obtains the service from that Context and invokes the method. It applies when the method itself depends on scoped composition and does not need to receive objects such as `Agent` explicitly.
 
 Services normally extend `GatewayService` so the constructor explicitly binds the Cordis service key and default Remote namespace. A service that already has another base class can instead declare `readonly typertGateway = bindTypeRTGateway(this, serviceKey)`; both forms leave an inspectable public binding and do not depend on the compiler injecting a symbol into the constructor.
 
 ```ts
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { GatewayService, Remote, RemoteContext } from '@deepseek-ai/dsh-type-meta'
+import { GatewayService, Remote, RemoteScope } from '@deepseek-ai/dsh-type-meta'
 import type { Context } from 'cordis'
 
 export interface CreateGoalRequest {
@@ -42,7 +42,7 @@ export class GoalService extends GatewayService {
     return this.create(agent, request)
   }
 
-  @RemoteContext('agent', 'current')
+  @RemoteScope('agent', 'current')
   currentForClient(): CreateGoalResult {
     return { accepted: true }
   }
@@ -55,7 +55,7 @@ export class GoalService extends GatewayService {
 
 Remote methods may return a value synchronously or return a Promise. For cooperative cancellation, the final parameter in the Host signature must be `signal: AbortSignal` using the global type; it is recorded in the descriptor instead of entering `args`, while the generated Client method accepts an optional final `AbortSignal`.
 
-The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct and scoped calls appear under `ctx.remote.<namespace>` and `agentCtx.remote.<namespace>`. Each namespace is a traced Cordis child Service registered as `remote.<namespace>`; the Client assembly mounts contributions through `ctx.remote.$mount()`, consumers inject both `remote` and the namespace Service they call, and the namespace unloads after its last method is withdrawn. When an `@Remote` method has exactly one lookup parameter and a same-named `TypeRTContextMap` uses the same wire identity, the generated scoped signature omits that identity parameter. `@RemoteContext` generates only the scoped invocation interface.
+The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct and scoped calls appear under `ctx.remote.<namespace>` and `agentCtx.remote.<namespace>`. Each namespace is a traced Cordis child Service registered as `remote.<namespace>`; the Client assembly mounts contributions through `ctx.remote.$mount()`, consumers inject both `remote` and the namespace Service they call, and the namespace unloads after its last method is withdrawn. When an `@Remote` method has exactly one lookup parameter and a same-named `TypeRTContextMap` uses the same wire identity, the generated scoped signature omits that identity parameter. `@RemoteScope` generates only the scoped invocation interface.
 
 ```ts
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -101,7 +101,7 @@ Each contributing business package writes generated files to its own `lib/` dire
 | `typert.host.js` | Host Loader | Runtime reflection for the Host face, strict invocation descriptors, and schema registration values |
 | `typert.host.d.ts` | Host type system | Generated declarations for the Host face |
 | `typert.remote-client.js` | `api-remotes` | A mountable `TypeRTRemoteContribution` containing strict descriptors and runtime codecs |
-| `typert.remote-client.d.ts` | Client type system | Declaration merges for `TypeRTRemoteNamespaceMap` and `TypeRTRemoteContextMap`, plus Client-safe type references |
+| `typert.remote-client.d.ts` | Client type system | Declaration merges for `TypeRTRemoteNamespaceMap` and `TypeRTRemoteScopeMap`, plus Client-safe type references |
 | `typert.remote-client.d.ts.map` | Editor | Maps generated method properties back to Remote method declarations in the Host package |
 
 Business packages expose the Host Loader entry through `./typert` and the Host-for-Client entry through `./remote`. The generator also validates these package exports and published-file lists; it generates artifacts only for explicit contribution packages that provide the corresponding entry.
@@ -126,7 +126,7 @@ Unloading a Client contribution removes its descriptors and concrete methods tog
 
 When the Host starts from source through `node --import tsx/esm`, it does not execute the TypeRT compiler plugin. Standard decorator initializers still record the method name and invocation mode in a module-private `WeakMap`, while `GatewayService` or `bindTypeRTGateway()` supplies the explicit service binding; the Gateway can therefore construct a weaker temporary descriptor without starting a `ts.Program`.
 
-The SRC fallback parses simple parameter names from the live function. When a parameter name matches the `parameter` of a registered lookup, such as `agent` or `session`, it uses the lookup's `agentId` or `sessionId` wire field and resolves the object on the Host; other parameters are checked only for cycle-free, JSON-safe data with no special prototype. `@RemoteContext` directly uses the wire field of a registered Host Context provider. SRC does not read TypeScript types, generate Zod schemas, infer optional parameters, or support destructuring, default values, rest parameters, or duplicate parameter names.
+The SRC fallback parses simple parameter names from the live function. When a parameter name matches the `parameter` of a registered lookup, such as `agent` or `session`, it uses the lookup's `agentId` or `sessionId` wire field and resolves the object on the Host; other parameters are checked only for cycle-free, JSON-safe data with no special prototype. `@RemoteScope` directly uses the wire field of a registered Host Context provider. SRC does not read TypeScript types, generate Zod schemas, infer optional parameters, or support destructuring, default values, rest parameters, or duplicate parameter names.
 
 SRC solves only dispatch for a Host process running from source. The Client does not discover decorators from the running Host, and the Client Remote refuses to mount SRC descriptors that lack strict codecs; its types, codecs, and Remote registration values always come from the most recently generated `lib/typert.remote-client.*` artifacts.
 
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 6fcbb562b2..4e42ebea7a 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -6,17 +6,17 @@
 
 ## 编程模型
 
-业务 Service 通过 `@Remote` 或 `@RemoteContext` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.remote` 调用。
+业务 Service 通过 `@Remote` 或 `@RemoteScope` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.remote` 调用。
 
 `@Remote` 表示调用根 Host Context 中注册的 Cordis Service。复杂的 Host 对象不能直接跨 wire 传输；业务包必须通过 `TypeRTLookupMap` 声明它与 wire identity 的关联，并在运行时向 `ctx.typert.lookups` 注册默认解析提供方。例如 `Agent` 参数在 Host 签名中名为 `agent`，生成的 wire 字段为 `agentId`，Gateway 在调用业务方法前将 id 解析为 Host 对象。Host 组合可以用 `ctx.typert.lookups.configure()` 覆盖某个 lookup key 的解析策略，而不改变业务包拥有的参数名、wire 字段或规范类型 symbol。
 
-`@RemoteContext(key)` 表示先通过 `ctx.typert.contexts` 把 identity 解析为一个作用域 Context，再从该 Context 取得 Service 并调用方法。它适用于方法本身依赖作用域组合、而不需要显式接收 `Agent` 等对象的情形。
+`@RemoteScope(key)` 表示先通过 `ctx.typert.contexts` 把 identity 解析为一个作用域 Context，再从该 Context 取得 Service 并调用方法。它适用于方法本身依赖作用域组合、而不需要显式接收 `Agent` 等对象的情形。
 
 Service 通常继承 `GatewayService`，让 Cordis service key 与默认 Remote namespace 在构造器中显式绑定。已有其他基类的 Service 可以改为声明 `readonly typertGateway = bindTypeRTGateway(this, serviceKey)`；两种方式都会留下可检查的公开 binding，不依赖编译器向构造函数注入 symbol。
 
 ```ts
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { GatewayService, Remote, RemoteContext } from '@deepseek-ai/dsh-type-meta'
+import { GatewayService, Remote, RemoteScope } from '@deepseek-ai/dsh-type-meta'
 import type { Context } from 'cordis'
 
 export interface CreateGoalRequest {
@@ -42,7 +42,7 @@ export class GoalService extends GatewayService {
     return this.create(agent, request)
   }
 
-  @RemoteContext('agent', 'current')
+  @RemoteScope('agent', 'current')
   currentForClient(): CreateGoalResult {
     return { accepted: true }
   }
@@ -55,7 +55,7 @@ export class GoalService extends GatewayService {
 
 Remote 方法可以同步返回或返回 Promise。若需要协作式取消，Host 签名的最后一个参数必须是全局类型的 `signal: AbortSignal`；它记录在描述符中而不是进入 `args`，Client 生成的方法则接受最后一个可选的 `AbortSignal`。
 
-Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子 Service；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，消费方同时注入 `remote` 与所调用的 namespace Service，最后一个方法撤回后该 namespace 随即卸载。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteContext` 只生成作用域调用界面。
+Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子 Service；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，消费方同时注入 `remote` 与所调用的 namespace Service，最后一个方法撤回后该 namespace 随即卸载。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用界面。
 
 ```ts
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -101,7 +101,7 @@ API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对
 | `typert.host.js` | Host Loader | Host face 的运行时反射、严格调用描述符和 schema 注册值 |
 | `typert.host.d.ts` | Host 类型系统 | Host face 的生成声明 |
 | `typert.remote-client.js` | `api-remotes` | 可挂载的 `TypeRTRemoteContribution`，包含严格描述符与运行时 codec |
-| `typert.remote-client.d.ts` | Client 类型系统 | `TypeRTRemoteNamespaceMap` 与 `TypeRTRemoteContextMap` 的声明合并及 Client-safe 类型引用 |
+| `typert.remote-client.d.ts` | Client 类型系统 | `TypeRTRemoteNamespaceMap` 与 `TypeRTRemoteScopeMap` 的声明合并及 Client-safe 类型引用 |
 | `typert.remote-client.d.ts.map` | 编辑器 | 将生成的方法属性映射回 Host 包中的 Remote 方法声明 |
 
 业务包通过 `./typert` 暴露 Host Loader 入口，通过 `./remote` 暴露 Host-for-Client 入口。生成器同时校验这些 package export 及发布文件清单；只有具备相应入口的显式贡献包才会生成产物。
@@ -126,7 +126,7 @@ Client 卸载一个贡献时会一起移除描述符和具体方法，中止其
 
 Host 通过 `node --import tsx/esm` 从源码启动时不会执行 TypeRT 编译插件。标准 decorator 初始化器仍会把方法名和调用模式记录到模块私有 `WeakMap`，`GatewayService` 或 `bindTypeRTGateway()` 则提供显式 service binding；Gateway 因而可以在不启动 `ts.Program` 的情况下构造一个较弱的临时描述符。
 
-SRC 回退从运行中函数解析简单参数名。参数名与某个已注册 lookup 的 `parameter` 相同，例如 `agent` 或 `session`，就使用其 `agentId` 或 `sessionId` wire 字段并在 Host 解析对象；其他参数只检查值是否为无循环、无特殊 prototype 的 JSON-safe 数据。`@RemoteContext` 直接使用已注册 Host Context provider 的 wire 字段。SRC 不读取 TypeScript 类型，不生成 Zod schema，不推断可选参数，也不支持解构、默认值、rest 或重复参数名。
+SRC 回退从运行中函数解析简单参数名。参数名与某个已注册 lookup 的 `parameter` 相同，例如 `agent` 或 `session`，就使用其 `agentId` 或 `sessionId` wire 字段并在 Host 解析对象；其他参数只检查值是否为无循环、无特殊 prototype 的 JSON-safe 数据。`@RemoteScope` 直接使用已注册 Host Context provider 的 wire 字段。SRC 不读取 TypeScript 类型，不生成 Zod schema，不推断可选参数，也不支持解构、默认值、rest 或重复参数名。
 
 SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Host 发现 decorator，Client Remote 也拒绝挂载缺少严格 codec 的 SRC 描述符；其类型、codec 和 Remote 注册值始终来自最近一次生成的 `lib/typert.remote-client.*`。
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 933f204fa0..b66552b175 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: 37bc88c7c1cfedfbe1a93e08a4cbde833ac32372
-development.zh.md: a738e53cb3434d7930aa82107782a4c22aea1470
+development.md: b7ecab3536d739c105f11a640a07ea83a22f4398
+development.zh.md: 33ceba9f05c45c06acae7c83425a30c5e26ca433
diff --git a/docs/development.md b/docs/development.md
index 37bc88c7c1..b7ecab3536 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -62,7 +62,7 @@ Host and client stay two aggregate programs because both sides declaration-merge
 
 Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).
 
-Business services declare callable methods on the Host with `@Remote` or `@RemoteContext`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
+Business services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
 
 If a relevant local check consumes built package output, build once first:
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index a738e53cb3..33ceba9f05 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -62,7 +62,7 @@ host 与 client 保持两个聚合 program，是因为两侧在相同键下以
 
 静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。
 
-业务 Service 在 Host 使用 `@Remote` 或 `@RemoteContext` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
+业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
 
 如果相关的本地检查需要使用构建后的包产物，请先构建一次：
 
diff --git a/packages/api/gateway/README.i18n.yaml b/packages/api/gateway/README.i18n.yaml
index 3a9a0ba50d..3f4cd32e4d 100644
--- a/packages/api/gateway/README.i18n.yaml
+++ b/packages/api/gateway/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/api/gateway/README.md
-README.md: e37359db71c1388667e9e61f538354711e90c0c1
-README.zh.md: 2054febb9a5423297c32b029b40a035062250aab
+README.md: 0e1a03d2016b8cfbe165dbf1b0a9802290b29502
+README.zh.md: 6b5ccff2340405cc0045147239c5bd4f3eead7da
diff --git a/packages/api/gateway/README.md b/packages/api/gateway/README.md
index e37359db71..0e1a03d201 100644
--- a/packages/api/gateway/README.md
+++ b/packages/api/gateway/README.md
@@ -6,9 +6,9 @@ Two-sided TypeRT RPC endpoint for Host and Client Cordis environments. The Host
 
 ## Host service: `TypertGatewayService` (ctx key: `typertGateway`)
 
-`ctx.typertGateway.invoke()` resolves the current descriptor and Cordis Service for each call, validates exact named arguments, resolves registered object or Context identities, invokes the public business method, and validates its result. Business Services extend `GatewayService` and mark methods with `@Remote` or `@RemoteContext` from [`dsh-type-meta`](../../typert/type-meta/README.md); `bindTypeRTGateway()` remains available when another base class owns inheritance.
+`ctx.typertGateway.invoke()` resolves the current descriptor and Cordis Service for each call, validates exact named arguments, resolves registered object or Context identities, invokes the public business method, and validates its result. Business Services extend `GatewayService` and mark methods with `@Remote` or `@RemoteScope` from [`dsh-type-meta`](../../typert/type-meta/README.md); `bindTypeRTGateway()` remains available when another base class owns inheritance.
 
-Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use the currently active resolver in `ctx.typert.lookups`: the business package registers the stable declaration and default policy, while Host composition can override resolution behavior with effect-scoped `configure()`; `@RemoteContext` resolves its receiver through a registered Host Context provider. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation.
+Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use the currently active resolver in `ctx.typert.lookups`: the business package registers the stable declaration and default policy, while Host composition can override resolution behavior with effect-scoped `configure()`; `@RemoteScope` resolves its receiver through a registered Host Context provider. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation.
 
 The Host entry registers a trusted-host interceptor on Connection's shared `/api` FetchHandler. Connection passes this composite handler through its HTTP bridge; the handler dispatches claimed endpoints to Gateway and unclaimed endpoints to API Proxy. Direct `invoke()` calls preserve business errors; `TypertGatewayError` distinguishes failures owned by dispatch, binding, providers, lookup, Context, arguments, and codecs. A resolver may use `TypeRTLookupFailure` to carry an existing RPC error, preserving its original error code for policy rejections such as cold-resume failures or ownership fences.
 
diff --git a/packages/api/gateway/README.zh.md b/packages/api/gateway/README.zh.md
index 2054febb9a..6b5ccff234 100644
--- a/packages/api/gateway/README.zh.md
+++ b/packages/api/gateway/README.zh.md
@@ -6,9 +6,9 @@
 
 ## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
 
-每次调用时，`ctx.typertGateway.invoke()` 都会解析当前的描述符和 Cordis 服务，校验具名参数是否完全匹配，解析已注册的对象或 Context 身份标识，调用公开的业务方法，并校验其结果。业务服务继承 [`dsh-type-meta`](../../typert/type-meta/README.md) 的 `GatewayService`，并用 `@Remote` 或 `@RemoteContext` 标记方法；已有其他基类时仍可改用 `bindTypeRTGateway()`。
+每次调用时，`ctx.typertGateway.invoke()` 都会解析当前的描述符和 Cordis 服务，校验具名参数是否完全匹配，解析已注册的对象或 Context 身份标识，调用公开的业务方法，并校验其结果。业务服务继承 [`dsh-type-meta`](../../typert/type-meta/README.md) 的 `GatewayService`，并用 `@Remote` 或 `@RemoteScope` 标记方法；已有其他基类时仍可改用 `bindTypeRTGateway()`。
 
-严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用 `ctx.typert.lookups` 中当前有效的 resolver：业务包注册稳定声明与默认策略，Host 组合可用 effect-scoped `configure()` 覆盖解析行为；`@RemoteContext` 则通过已注册的 Host Context 提供方解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。
+严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用 `ctx.typert.lookups` 中当前有效的 resolver：业务包注册稳定声明与默认策略，Host 组合可用 effect-scoped `configure()` 覆盖解析行为；`@RemoteScope` 则通过已注册的 Host Context 提供方解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。
 
 Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandler 上注册 trusted-host interceptor。Connection 把这个复合 handler 交给 HTTP bridge；handler 将已认领 endpoint 分发给 Gateway，未认领 endpoint 则交给 API Proxy。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 可区分分发、绑定、提供方、查找、Context、参数和编解码器各自负责的故障。resolver 可以用 `TypeRTLookupFailure` 携带既有 RPC error，使冷恢复失败或 ownership fence 等策略拒绝保持原错误码。
 
diff --git a/packages/api/gateway/tests/client.spec.ts b/packages/api/gateway/tests/client.spec.ts
index 216f2359e7..1383175e73 100644
--- a/packages/api/gateway/tests/client.spec.ts
+++ b/packages/api/gateway/tests/client.spec.ts
@@ -5,7 +5,7 @@ import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client
 import type {
   InvocationDescriptor,
   TypeRTContext,
-  TypeRTRemoteContextApi,
+  TypeRTRemoteScopeApi,
   TypeRTRemoteNamespace,
 } from '@deepseek-ai/dsh-type-meta'
 import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
@@ -24,7 +24,7 @@ declare module '@deepseek-ai/dsh-type-meta' {
     ) => Promise<{ readonly ref: string }>
   }
 
-  interface TypeRTRemoteContextMap {
+  interface TypeRTRemoteScopeMap {
     'fixture:goals/create': (
       request: { readonly objective: string },
       signal?: AbortSignal,
@@ -38,7 +38,7 @@ declare module '@deepseek-ai/dsh-type-meta' {
 
 }
 
-type FixtureContext = Omit<Context, 'remote'> & { readonly remote: TypeRTRemoteContextApi<'fixture'> }
+type FixtureContext = Omit<Context, 'remote'> & { readonly remote: TypeRTRemoteScopeApi<'fixture'> }
 
 const idSchema = z.string().min(1)
 const requestSchema = z.object({ objective: z.string().min(1) })
diff --git a/packages/api/gateway/tests/gateway.spec.ts b/packages/api/gateway/tests/gateway.spec.ts
index d298116b82..4fa0ea80ad 100644
--- a/packages/api/gateway/tests/gateway.spec.ts
+++ b/packages/api/gateway/tests/gateway.spec.ts
@@ -8,7 +8,7 @@ import type { HttpServerService, WebRoute } from '@deepseek-ai/dsh-host-webserve
 import {
   bindTypeRTGateway,
   Remote,
-  RemoteContext,
+  RemoteScope,
   TypeRTLookupFailure,
   type InvocationDescriptor,
   type TypeRTContext,
@@ -65,7 +65,7 @@ class GoalService extends Service {
     }
   }
 
-  @RemoteContext('gatewayFixture')
+  @RemoteScope('gatewayFixture')
   rename(request: { readonly title: string }): unknown {
     this.calls.push('rename')
     return { title: request.title, scope: (this.ctx as MarkedContext).fixtureScope ?? 'root' }
@@ -299,7 +299,7 @@ class ContextWireService extends Service {
     super(ctx, 'contextWire')
   }
 
-  @RemoteContext('gatewayFixture')
+  @RemoteScope('gatewayFixture')
   run(agentId: string): string {
     return agentId
   }
@@ -389,7 +389,7 @@ describe('TypertGatewayService', () => {
     expect(service.lastSignal?.aborted).toBe(false)
   })
 
-  it('resolves strict Remote Context identity without adding a business argument', async () => {
+  it('resolves strict Remote Scope identity without adding a business argument', async () => {
     const { ctx, service } = await setup()
     const scoped = ctx.extend({ fixtureScope: 'agent-scope' })
     ctx.typert.contexts.registerHost('gatewayFixture', contextProvider(scoped))
@@ -432,7 +432,7 @@ describe('TypertGatewayService', () => {
     expect(service.calls).toEqual([])
   })
 
-  it('derives SRC Remote Context identity and preserves the scoped Proxy receiver', async () => {
+  it('derives SRC Remote Scope identity and preserves the scoped Proxy receiver', async () => {
     const { ctx } = await setup()
     const scoped = ctx.extend({ fixtureScope: 'agent-src' })
     ctx.typert.contexts.registerHost('gatewayFixture', contextProvider(scoped))
diff --git a/packages/client/runtime/src/client/agents/scope.ts b/packages/client/runtime/src/client/agents/scope.ts
index 1154d10feb..25644d24ba 100644
--- a/packages/client/runtime/src/client/agents/scope.ts
+++ b/packages/client/runtime/src/client/agents/scope.ts
@@ -18,11 +18,11 @@
 import { Context as CordisContext } from 'cordis'
 import type { Context, Fiber } from 'cordis'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
-import type { TypeRTClientRemote, TypeRTRemoteContextApi } from '@deepseek-ai/dsh-type-meta'
+import type { TypeRTClientRemote, TypeRTRemoteScopeApi } from '@deepseek-ai/dsh-type-meta'
 
 /** Client Cordis Context carrying one Agent identity and its scoped Remote namespaces. */
 export type AgentContext = Omit<Context, 'remote'> & {
-  readonly remote: TypeRTClientRemote & TypeRTRemoteContextApi<'agent'>
+  readonly remote: TypeRTClientRemote & TypeRTRemoteScopeApi<'agent'>
 }
 
 /** Context tag written by {@link createScope}. */
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index bc5024a7d8..c5d89b3726 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -1032,10 +1032,10 @@ class FaceAnalyzer {
     if (invocation.kind === 'context') {
       const context = this.contextDeclarations().get(invocation.context)
       if (context === undefined) {
-        this.fail(method, `Remote Context ${invocation.context} has no TypeRTContextMap entry`)
+        this.fail(method, `Remote Scope ${invocation.context} has no TypeRTContextMap entry`)
       }
       const wire = `${invocation.context}Id`
-      if (wires.has(wire)) this.fail(method, `Remote Context wire field ${wire} conflicts with a method parameter`)
+      if (wires.has(wire)) this.fail(method, `Remote Scope wire field ${wire} conflicts with a method parameter`)
       receiver = {
         kind: 'context',
         context: invocation.context,
@@ -1200,18 +1200,18 @@ class FaceAnalyzer {
         }
         marker = { kind: 'direct', exportName }
       } else if (ts.isCallExpression(expression)
-        && this.isTypeMetaSymbol(expression.expression, 'RemoteContext')) {
+        && this.isTypeMetaSymbol(expression.expression, 'RemoteScope')) {
         if (expression.arguments.length < 1 || expression.arguments.length > 2) {
-          this.fail(expression, 'RemoteContext() requires a Context key and optional exported method name')
+          this.fail(expression, 'RemoteScope() requires a Context key and optional exported method name')
         }
         const context = stringLiteralValue(expression.arguments[0])
         if (context === undefined || !isRemoteSegment(context)) {
-          this.fail(expression.arguments[0] ?? expression, 'RemoteContext() key must be a string literal containing only RPC endpoint segment characters')
+          this.fail(expression.arguments[0] ?? expression, 'RemoteScope() key must be a string literal containing only RPC endpoint segment characters')
         }
         const exportArgument = expression.arguments[1]
         const exportName = exportArgument === undefined ? undefined : stringLiteralValue(exportArgument)
         if (exportArgument !== undefined && (exportName === undefined || !isRemoteSegment(exportName))) {
-          this.fail(exportArgument, 'RemoteContext() name must be a string literal containing only RPC endpoint segment characters')
+          this.fail(exportArgument, 'RemoteScope() name must be a string literal containing only RPC endpoint segment characters')
         }
         marker = { kind: 'context', context, ...exportName === undefined ? {} : { exportName } }
       } else {
@@ -2529,7 +2529,7 @@ function sourceFileHasSurface(sourceFile: ts.SourceFile): boolean {
             ? decorator.expression.expression
             : decorator.expression
           const name = expressionName(expression)
-          if (name === 'Remote' || name === 'RemoteContext') return true
+          if (name === 'Remote' || name === 'RemoteScope') return true
         }
       }
     }
diff --git a/packages/typert/generator/src/emitter.ts b/packages/typert/generator/src/emitter.ts
index bb39959606..cbed0047c3 100644
--- a/packages/typert/generator/src/emitter.ts
+++ b/packages/typert/generator/src/emitter.ts
@@ -376,7 +376,7 @@ export class FaceModelEmitter {
       lines.push('  }')
     }
     if (scoped.length > 0) {
-      lines.push('  interface TypeRTRemoteContextMap {')
+      lines.push('  interface TypeRTRemoteScopeMap {')
       for (const invocation of scoped) {
         this.pushRemoteSignature(lines, sourceMap, packageModel, invocation, referenceNames, true)
       }
diff --git a/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
index 4aa51ec433..e84d6fd142 100644
--- a/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
+++ b/packages/typert/generator/tests/fixtures/remote-model/packages/remote/src/index.ts
@@ -1,4 +1,4 @@
-import { GatewayService, Remote, RemoteContext } from '@deepseek-ai/dsh-type-meta'
+import { GatewayService, Remote, RemoteScope } from '@deepseek-ai/dsh-type-meta'
 import type { Agent } from '@fixture/domain'
 import type {
   CreateGoalRequest,
@@ -19,7 +19,7 @@ export class GoalService extends GatewayService {
     return { ref: `${agent.id}:${request.title}` }
   }
 
-  @RemoteContext('agent')
+  @RemoteScope('agent')
   rename(request: RenameGoalRequest): RenameGoalResult {
     return { renamed: request.title.length > 0 }
   }
diff --git a/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts b/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
index 5347a6b77e..707dc84ce9 100644
--- a/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
+++ b/packages/typert/generator/tests/fixtures/remote-model/type-meta.d.ts
@@ -11,7 +11,7 @@ declare module '@deepseek-ai/dsh-type-meta' {
   export interface TypeRTLookupMap {}
   export interface TypeRTContextMap {}
   export interface TypeRTRemoteMap {}
-  export interface TypeRTRemoteContextMap {}
+  export interface TypeRTRemoteScopeMap {}
 
   export type TypeRTRemoteNamespace<Namespace extends string> = {
     [Endpoint in keyof TypeRTRemoteMap as Endpoint extends `${Namespace}/${infer Method}`
@@ -56,7 +56,7 @@ declare module '@deepseek-ai/dsh-type-meta' {
     context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
   ) => void
 
-  export function RemoteContext(key: Extract<keyof TypeRTContextMap, string>, exportName?: string):
+  export function RemoteScope(key: Extract<keyof TypeRTContextMap, string>, exportName?: string):
   <This extends object, Args extends unknown[], Result>(
     method: (this: This, ...args: Args) => Result,
     context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
diff --git a/packages/typert/generator/tests/remote-model.spec.ts b/packages/typert/generator/tests/remote-model.spec.ts
index eaaf680cc6..0e62a56bf4 100644
--- a/packages/typert/generator/tests/remote-model.spec.ts
+++ b/packages/typert/generator/tests/remote-model.spec.ts
@@ -288,7 +288,7 @@ export interface BoxPayload {
     const root = copyFixture()
     editFile(root, 'packages/remote/src/index.ts', source => source
       .replace('  @Remote\n', '')
-      .replace("  @RemoteContext('agent')\n", ''))
+      .replace("  @RemoteScope('agent')\n", ''))
     editFile(root, 'packages/remote/src/types.ts', source => `${source}
 
 /** @typert schema */
@@ -377,8 +377,8 @@ export interface ClientMarker {
       name: 'duplicate GatewayService field binding',
       edit: (source: string) => source
         .replace(
-          'import { GatewayService, Remote, RemoteContext }',
-          'import { GatewayService, Remote, RemoteContext, bindTypeRTGateway }',
+          'import { GatewayService, Remote, RemoteScope }',
+          'import { GatewayService, Remote, RemoteScope, bindTypeRTGateway }',
         )
         .replace(
           'export class GoalService extends GatewayService {',
@@ -495,11 +495,11 @@ export interface ClientMarker {
     expect(() => analyzeRemote(root)).not.toThrow()
   })
 
-  it('rejects a Remote Context without a static Context declaration', () => {
+  it('rejects a Remote Scope without a static Context declaration', () => {
     const root = copyFixture()
-    editFile(root, 'packages/remote/src/index.ts', source => source.replace("@RemoteContext('agent')", "@RemoteContext('missing')"))
+    editFile(root, 'packages/remote/src/index.ts', source => source.replace("@RemoteScope('agent')", "@RemoteScope('missing')"))
 
-    expect(() => analyzeRemote(root, false)).toThrow(/Remote Context missing has no TypeRTContextMap entry/)
+    expect(() => analyzeRemote(root, false)).toThrow(/Remote Scope missing has no TypeRTContextMap entry/)
   })
 
   it('rejects a direct scoped projection whose Context and lookup wire symbols differ', () => {
@@ -579,7 +579,7 @@ function assertRemoteConsumerTypechecks(
 import remote from '@fixture/remote/remote'
 import type {
   TypeRTRemoteContribution,
-  TypeRTRemoteContextMap,
+  TypeRTRemoteScopeMap,
   TypeRTRemoteMap,
   TypeRTRemoteNamespaceMap,
 } from '@deepseek-ai/dsh-type-meta'
@@ -587,8 +587,8 @@ import type { CreateGoalResult, RenameGoalResult } from '@fixture/remote/types'
 
 const contribution: TypeRTRemoteContribution = remote
 declare const create: TypeRTRemoteMap['goals/create']
-declare const createScoped: TypeRTRemoteContextMap['agent:goals/create']
-declare const rename: TypeRTRemoteContextMap['agent:goals/rename']
+declare const createScoped: TypeRTRemoteScopeMap['agent:goals/create']
+declare const rename: TypeRTRemoteScopeMap['agent:goals/rename']
 const created: Promise<CreateGoalResult> = create('agent-1', { title: 'ship' })
 const cancellable: Promise<CreateGoalResult> = create('agent-1', { title: 'ship' }, new AbortController().signal)
 const createdScoped: Promise<CreateGoalResult> = createScoped({ title: 'ship' })
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
index 6c21127e54..a61602c07b 100644
--- a/packages/typert/type-meta/README.i18n.yaml
+++ b/packages/typert/type-meta/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/typert/type-meta/README.md
-README.md: a76169742cb78d0d19814bcd0f978c71036a5a1c
-README.zh.md: 6f2d2fd6e241441fae8102c0639608e9b27b9bec
+README.md: 9bd475f8973ec54756fe0e63d5b7fa485381697d
+README.zh.md: 10a6309bc47001d572abb3dd3f794ebfcf6252e8
diff --git a/packages/typert/type-meta/README.md b/packages/typert/type-meta/README.md
index a76169742c..9bd475f897 100644
--- a/packages/typert/type-meta/README.md
+++ b/packages/typert/type-meta/README.md
@@ -7,7 +7,7 @@ Compiler-independent declarations shared by business packages, generated TypeRT
 ## Remote declarations
 
 - `@Remote` marks a public instance method for direct invocation on its registered Cordis Service.
-- `@RemoteContext(key)` marks a method whose receiver is selected from a merge-declared scoped Context kind.
+- `@RemoteScope(key)` marks a method whose receiver is selected from a merge-declared scoped Context kind.
 - `GatewayService` binds the Cordis key passed to `super(ctx, serviceKey, options?)` to the same default wire namespace.
 - `bindTypeRTGateway(this, serviceKey, options?)` provides the same visible, frozen binding for a Service that cannot inherit from `GatewayService`.
 - `remoteMethods(service)` returns a detached declaration-order snapshot used by the Gateway's SRC fallback.
@@ -18,7 +18,7 @@ Decorator initializers retain markers in a module-private `WeakMap` keyed by the
 
 ## TypeRT protocol
 
-Business packages extend `TypeRTLookupMap` and `TypeRTContextMap` to associate Host objects or scoped Contexts with their wire identities. Generated artifacts extend `TypeRTRemoteMap`, `TypeRTRemoteContextMap`, and `TypeRTRemoteNamespaceMap` so Client imports expose only selected Remote methods. `InvocationDescriptor` is the shared runtime form consumed by the registry, Gateway, and Client API.
+Business packages extend `TypeRTLookupMap` and `TypeRTContextMap` to associate Host objects or scoped Contexts with their wire identities. Generated artifacts extend `TypeRTRemoteMap`, `TypeRTRemoteScopeMap`, and `TypeRTRemoteNamespaceMap` so Client imports expose only selected Remote methods. `InvocationDescriptor` is the shared runtime form consumed by the registry, Gateway, and Client Remote.
 
 Lookup and Context packages own both sides of their contract: declaration merging supplies the static association, while runtime providers register identity resolution with `ctx.typert`. A lookup or Host Context provider supplies the stable declaration and default resolver, while Host composition may separately configure a synchronous or asynchronous resolver; policy rejections may use `TypeRTLookupFailure` to carry a failure value owned by the boundary adapter. Strict codecs carry generated schemas; `src-json` codecs identify the weaker source-launch path.
 
diff --git a/packages/typert/type-meta/README.zh.md b/packages/typert/type-meta/README.zh.md
index 6f2d2fd6e2..10a6309bc4 100644
--- a/packages/typert/type-meta/README.zh.md
+++ b/packages/typert/type-meta/README.zh.md
@@ -7,7 +7,7 @@
 ## Remote 声明
 
 - `@Remote` 将公开实例方法标记为可在其注册的 Cordis 服务上直接调用。
-- `@RemoteContext(key)` 标记接收者选自合并声明的作用域 Context 类型的方法。
+- `@RemoteScope(key)` 标记接收者选自合并声明的作用域 Context 类型的方法。
 - `GatewayService` 将 `super(ctx, serviceKey, options?)` 接收的 Cordis key 同时绑定为默认 wire namespace。
 - `bindTypeRTGateway(this, serviceKey, options?)` 为无法继承 `GatewayService` 的 Service 提供同样可见且冻结的绑定。
 - `remoteMethods(service)` 返回按声明顺序排列、与内部状态分离的快照，供 Gateway 的 SRC 回退路径使用。
@@ -18,7 +18,7 @@ Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用
 
 ## TypeRT 协议
 
-业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联 Host 对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteContextMap` 和 `TypeRTRemoteNamespaceMap`，使 Client 导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、Gateway 和 Client API 使用的共享运行时形式。
+业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联 Host 对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteScopeMap` 和 `TypeRTRemoteNamespaceMap`，使 Client 导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、Gateway 和 Client Remote 使用的共享运行时形式。
 
 查找包与 Context 包同时负责其契约的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。lookup 或 Host Context provider 提供稳定声明与默认 resolver，Host 组合可以另行配置同步或异步 resolver；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
 
diff --git a/packages/typert/type-meta/src/index.ts b/packages/typert/type-meta/src/index.ts
index 774c6d3b32..1375d7872b 100644
--- a/packages/typert/type-meta/src/index.ts
+++ b/packages/typert/type-meta/src/index.ts
@@ -60,9 +60,9 @@ export type {
   TypeRTLookupResolver,
   TypeRTLookupRegistry,
   TypeRTLookupWire,
-  TypeRTRemoteContextApi,
-  TypeRTRemoteContextMap,
-  TypeRTRemoteContextNamespace,
+  TypeRTRemoteScopeApi,
+  TypeRTRemoteScopeMap,
+  TypeRTRemoteScopeNamespace,
   TypeRTRemoteContribution,
   TypeRTRemoteMap,
   TypeRTRemoteNamespace,
@@ -191,16 +191,16 @@ export function Remote<This extends object, Args extends unknown[], Result>(
 }
 
 /**
- * Create a decorator for a method resolved from one scoped Remote Context.
- * @param key - merge-declared Context key.
+ * Create a decorator for a method resolved from one Remote Scope.
+ * @param key - scope key declared through the Context map.
  * @param exportName - optional Remote export name; defaults to the method name.
  * @returns a standard method decorator that records only private module state.
  */
-export function RemoteContext(
+export function RemoteScope(
   key: Extract<keyof TypeRTContextMap, string>,
   exportName?: string,
 ): RemoteMethodDecorator {
-  validateName('Context key', key)
+  validateName('Scope key', key)
   if (exportName !== undefined) validateName('Remote export name', exportName)
   return function <This extends object, Args extends unknown[], Result>(
     _method: (this: This, ...args: Args) => Result,
diff --git a/packages/typert/type-meta/src/types.ts b/packages/typert/type-meta/src/types.ts
index 5e7c20cd7c..c1d6b3dcf9 100644
--- a/packages/typert/type-meta/src/types.ts
+++ b/packages/typert/type-meta/src/types.ts
@@ -40,7 +40,7 @@ export interface TypeRTContextMap {}
 export interface TypeRTRemoteMap {}
 
 /** Merge-extensible scoped Remote method signatures generated for consumers. */
-export interface TypeRTRemoteContextMap {}
+export interface TypeRTRemoteScopeMap {}
 
 /**
  * Resolve one direct Remote namespace from the generated flat endpoint map.
@@ -57,24 +57,24 @@ export type TypeRTRemoteNamespace<Namespace extends string> = {
  * The calling Cordis Context supplies the concrete identity at runtime.
  * @template Namespace - wire namespace between the Context prefix and method.
  */
-export type TypeRTRemoteContextNamespace<
+export type TypeRTRemoteScopeNamespace<
   Namespace extends string,
   ContextKey extends string = string,
 > = {
-  [Endpoint in keyof TypeRTRemoteContextMap as Endpoint extends `${ContextKey}:${Namespace}/${infer Method}`
+  [Endpoint in keyof TypeRTRemoteScopeMap as Endpoint extends `${ContextKey}:${Namespace}/${infer Method}`
     ? Method
-    : never]: TypeRTRemoteContextMap[Endpoint]
+    : never]: TypeRTRemoteScopeMap[Endpoint]
 }
 
-type TypeRTRemoteContextNamespaceKey<
+type TypeRTRemoteScopeNamespaceKey<
   ContextKey extends string,
-  Endpoint = keyof TypeRTRemoteContextMap,
+  Endpoint = keyof TypeRTRemoteScopeMap,
 > = Endpoint extends `${ContextKey}:${infer Namespace}/${string}` ? Namespace : never
 
 /** Generated scoped Remote namespaces available to one Context kind. */
-export type TypeRTRemoteContextApi<ContextKey extends string> = {
-  [Namespace in TypeRTRemoteContextNamespaceKey<ContextKey>]:
-  TypeRTRemoteContextNamespace<Namespace, ContextKey>
+export type TypeRTRemoteScopeApi<ContextKey extends string> = {
+  [Namespace in TypeRTRemoteScopeNamespaceKey<ContextKey>]:
+  TypeRTRemoteScopeNamespace<Namespace, ContextKey>
 }
 
 /** Merge-extensible direct namespace surface generated for Client Remote services. */
@@ -227,7 +227,7 @@ export interface TypeRTLookupDefinition {
   readonly wireTypeSymbol: string
 }
 
-/** Host resolver for one scoped Remote Context kind. */
+/** Host resolver for one scoped Remote kind. */
 export interface TypeRTHostContextProvider<Wire = unknown> {
   /** Wire field carrying the Context identity. */
   readonly wire: string
diff --git a/packages/typert/type-meta/tests/fixtures/source-launch.ts b/packages/typert/type-meta/tests/fixtures/source-launch.ts
index b13a80796d..14eec6610d 100644
--- a/packages/typert/type-meta/tests/fixtures/source-launch.ts
+++ b/packages/typert/type-meta/tests/fixtures/source-launch.ts
@@ -2,7 +2,7 @@ import { Context } from 'cordis'
 import {
   GatewayService,
   Remote,
-  RemoteContext,
+  RemoteScope,
   remoteMethods,
 } from '@deepseek-ai/dsh-type-meta'
 
@@ -16,7 +16,7 @@ class Goals extends GatewayService {
     return value
   }
 
-  @RemoteContext('agent')
+  @RemoteScope('agent')
   scoped(value: string): string {
     return value
   }
diff --git a/packages/typert/type-meta/tests/type-meta.spec.ts b/packages/typert/type-meta/tests/type-meta.spec.ts
index b84b76300c..bfe99630b9 100644
--- a/packages/typert/type-meta/tests/type-meta.spec.ts
+++ b/packages/typert/type-meta/tests/type-meta.spec.ts
@@ -6,7 +6,7 @@ import {
   bindTypeRTGateway,
   GatewayService,
   Remote,
-  RemoteContext,
+  RemoteScope,
   remoteMethods,
   type TypeRTContext,
 } from '@deepseek-ai/dsh-type-meta'
@@ -29,7 +29,7 @@ describe('type-meta Remote declarations', () => {
         return value
       }
 
-      @RemoteContext('metaFixture')
+      @RemoteScope('metaFixture')
       scoped(value: string): string {
         return value
       }
@@ -84,7 +84,7 @@ describe('type-meta Remote declarations', () => {
       Reflect.get(Goals.prototype, 'create') as (this: Goals, ...args: unknown[]) => unknown,
       methodContext('create', initializers),
     )
-    RemoteContext('metaFixture')(
+    RemoteScope('metaFixture')(
       Reflect.get(Goals.prototype, 'scoped') as (this: Goals, ...args: unknown[]) => unknown,
       methodContext('scoped', initializers),
     )
@@ -141,7 +141,7 @@ describe('type-meta Remote declarations', () => {
       Reflect.get(Service.prototype, 'run') as (this: Service, ...args: unknown[]) => unknown,
       methodContext('run', initializers),
     )
-    RemoteContext('metaFixture', 'inspect')(
+    RemoteScope('metaFixture', 'inspect')(
       Reflect.get(Service.prototype, 'scoped') as (this: Service, ...args: unknown[]) => unknown,
       methodContext('scoped', initializers),
     )
@@ -166,8 +166,8 @@ describe('type-meta Remote declarations', () => {
     expect(() => Remote('bad name')).toThrow('export name')
     expect(() => Remote('.')).toThrow('export name')
     expect(() => Remote('..')).toThrow('export name')
-    expect(() => RemoteContext('' as 'metaFixture')).toThrow('Context key')
-    expect(() => RemoteContext('metaFixture', 'bad/name')).toThrow('export name')
+    expect(() => RemoteScope('' as 'metaFixture')).toThrow('Scope key')
+    expect(() => RemoteScope('metaFixture', 'bad/name')).toThrow('export name')
 
     for (const context of [
       { ...methodContext('run', []), private: true },
@@ -195,7 +195,7 @@ describe('type-meta Remote declarations', () => {
       Reflect.get(Service.prototype, 'run'),
       methodContext('run', conflicting),
     )
-    RemoteContext('metaFixture')(
+    RemoteScope('metaFixture')(
       Reflect.get(Service.prototype, 'run'),
       methodContext('run', conflicting),
     )

From 8bbbb6fe59d71e52f0aeefcd1c95c7bd84e55f91 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 19:23:47 +0800
Subject: [PATCH 153/516] fix(api-gateway): compose scoped remote fixture types

---
 packages/api/gateway/tests/client.spec.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/api/gateway/tests/client.spec.ts b/packages/api/gateway/tests/client.spec.ts
index 1383175e73..d253c38acc 100644
--- a/packages/api/gateway/tests/client.spec.ts
+++ b/packages/api/gateway/tests/client.spec.ts
@@ -4,6 +4,7 @@ import { z } from 'zod'
 import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
 import type {
   InvocationDescriptor,
+  TypeRTClientRemote,
   TypeRTContext,
   TypeRTRemoteScopeApi,
   TypeRTRemoteNamespace,
@@ -38,7 +39,9 @@ declare module '@deepseek-ai/dsh-type-meta' {
 
 }
 
-type FixtureContext = Omit<Context, 'remote'> & { readonly remote: TypeRTRemoteScopeApi<'fixture'> }
+type FixtureContext = Omit<Context, 'remote'> & {
+  readonly remote: TypeRTClientRemote & TypeRTRemoteScopeApi<'fixture'>
+}
 
 const idSchema = z.string().min(1)
 const requestSchema = z.object({ objective: z.string().min(1) })

From 55ccfb5a48ab9d50b7953119036117c50057d650 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 19:44:47 +0800
Subject: [PATCH 154/516] fix(api): preserve dynamic defaults after rebase

---
 packages/api/remotes/src/agent-lookup.ts            | 6 +++---
 packages/host/apiproxy/tests/api-proxy-cold.spec.ts | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/api/remotes/src/agent-lookup.ts b/packages/api/remotes/src/agent-lookup.ts
index eb54ea9b0b..71d7a76379 100644
--- a/packages/api/remotes/src/agent-lookup.ts
+++ b/packages/api/remotes/src/agent-lookup.ts
@@ -20,8 +20,8 @@ export type ApiRemoteAgentResult =
 
 /** Resume configuration supplied by the owning Host composition. */
 export interface ApiRemoteAgentOptions {
-  /** Per-Agent defaults used when a cold identity must resume. */
-  readonly agentOptions?: AgentOptions
+  /** Read the per-Agent defaults when a cold identity must resume. */
+  readonly agentOptions?: () => AgentOptions
   /** Host-specific Agent-scope composition completed before publication. */
   readonly setup?: AgentSetup
 }
@@ -144,7 +144,7 @@ export function createApiRemoteAgentResolver(
           }
           const handle = await ctx.agents.resume({
             resumeSessionId: sessionId,
-            ...options.agentOptions === undefined ? {} : { agentOptions: options.agentOptions },
+            ...options.agentOptions === undefined ? {} : { agentOptions: options.agentOptions() },
             ...options.setup === undefined ? {} : { setup: options.setup },
           })
           return handle.agent
diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
index e5e137f0c4..8e79c641a8 100644
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -206,7 +206,7 @@ describe('Remote Agent and Session lookup policy', () => {
     })
     const defaultAgentLookup = ctx.typert.lookups.get('agent')
     const defaultSessionLookup = ctx.typert.lookups.get('session')
-    createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     await vi.waitFor(() => {
       expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
       expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
@@ -250,7 +250,7 @@ describe('Remote Agent and Session lookup policy', () => {
     const resume = vi.spyOn(ctx.agents, 'resume')
     const defaultAgentLookup = ctx.typert.lookups.get('agent')
     const defaultSessionLookup = ctx.typert.lookups.get('session')
-    createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     await vi.waitFor(() => {
       expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
       expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)

From 5c2625c26eb6affb3732be713823ec655dabf5a0 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 20:02:12 +0800
Subject: [PATCH 155/516] docs(typert): align client remote type mapping

---
 scripts/type-equiv.manifest.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index ecb13f167c..095fa25b4f 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1552,7 +1552,7 @@
     },
     {
       "doc": "docs/core-data-structures/typert.md",
-      "symbol": "TypeRTClientApi",
+      "symbol": "TypeRTClientRemote",
       "source": "packages/typert/type-meta/src/types.ts"
     }
   ]

From 14ea7e134d0fe90b54218b651da7c00ca4e89a1f Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 20:02:12 +0800
Subject: [PATCH 156/516] fix(api-remotes): await namespace assembly startup

---
 packages/api/remotes/src/client/index.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/api/remotes/src/client/index.ts b/packages/api/remotes/src/client/index.ts
index ebd342300e..be92b02d77 100644
--- a/packages/api/remotes/src/client/index.ts
+++ b/packages/api/remotes/src/client/index.ts
@@ -20,7 +20,8 @@ export const inject = ['remote']
 /**
  * Mount the Host capabilities explicitly selected for this Client assembly.
  * @param ctx - Client Cordis root carrying the typed API service.
+ * @returns disposer after every selected Remote namespace is ready.
  */
-export function apply(ctx: Context): Promise<() => Promise<void>> {
-  return ctx.remote.$mount(goalsRemote)
+export async function apply(ctx: Context): Promise<() => Promise<void>> {
+  return await ctx.remote.$mount(goalsRemote)
 }

From 8b51a1e95c4bc87d69ac5c060ec390ea571b08f4 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 20:11:42 +0800
Subject: [PATCH 157/516] test(api-gateway): cover namespace rollback paths

---
 packages/api/gateway/src/client/index.ts  | 58 +++++++++--------------
 packages/api/gateway/tests/client.spec.ts | 40 ++++++++++++++++
 2 files changed, 62 insertions(+), 36 deletions(-)

diff --git a/packages/api/gateway/src/client/index.ts b/packages/api/gateway/src/client/index.ts
index d0429339c8..e49e9e5822 100644
--- a/packages/api/gateway/src/client/index.ts
+++ b/packages/api/gateway/src/client/index.ts
@@ -194,7 +194,7 @@ class ClientRemoteService extends Service implements TypeRTClientRemote {
       throw error
     }
     return async () => {
-      if (!namespace.service.remove('direct', descriptor.method, token)) return
+      namespace.service.remove('direct', descriptor.method, token)
       await this.disposeNamespace(descriptor.namespace, namespace)
     }
   }
@@ -212,7 +212,7 @@ class ClientRemoteService extends Service implements TypeRTClientRemote {
       throw error
     }
     return async () => {
-      if (!namespace.service.remove('scoped', descriptor.method, token)) return
+      namespace.service.remove('scoped', descriptor.method, token)
       await this.disposeNamespace(descriptor.namespace, namespace)
     }
   }
@@ -390,50 +390,36 @@ class RemoteNamespaceService extends Service {
     let record = this.methods.get(method)
     const fresh = record === undefined
     record ??= {}
-    if (record[kind] !== undefined) {
-      throw new Error(`client api: ${kind} method ${this.namespace}/${method} is already mounted`)
-    }
-    try {
-      if (fresh) {
-        Object.defineProperty(this, method, {
-          configurable: true,
-          enumerable: true,
-          get: function (this: RemoteNamespaceService): (...args: unknown[]) => Promise<unknown> {
-            const callerCtx = this.ctx
-            const current = this.methods.get(method)
-            const direct = current?.direct
-            const scoped = current?.scoped
-            return (...args: unknown[]) => {
-              return this.invokeRemote(direct, scoped, callerCtx, args)
-            }
-          },
-        })
-        this.methods.set(method, record)
-      }
-      if (kind === 'direct') record.direct = value
-      else record.scoped = value as ScopedMethod
-    } catch (error) {
-      if (kind === 'direct') delete record.direct
-      else delete record.scoped
-      if (fresh) {
-        this.methods.delete(method)
-        Reflect.deleteProperty(this, method)
-      }
-      throw error
+    if (fresh) {
+      Object.defineProperty(this, method, {
+        configurable: true,
+        enumerable: true,
+        get: function (this: RemoteNamespaceService): (...args: unknown[]) => Promise<unknown> {
+          const callerCtx = this.ctx
+          const current = this.methods.get(method)
+          const direct = current?.direct
+          const scoped = current?.scoped
+          return (...args: unknown[]) => {
+            return this.invokeRemote(direct, scoped, callerCtx, args)
+          }
+        },
+      })
+      this.methods.set(method, record)
     }
+    if (kind === 'direct') record.direct = value
+    else record.scoped = value as ScopedMethod
   }
 
-  remove(kind: 'direct' | 'scoped', method: string, token: MountToken): boolean {
+  remove(kind: 'direct' | 'scoped', method: string, token: MountToken): void {
     const record = this.methods.get(method)
     const current = record?.[kind]
     /* v8 ignore next -- duplicate live variants are rejected before installation, so no newer token can replace this one. */
-    if (record === undefined || current?.token !== token) return false
+    if (record === undefined || current?.token !== token) return
     if (kind === 'direct') delete record.direct
     else delete record.scoped
-    if (record.direct !== undefined || record.scoped !== undefined) return true
+    if (record.direct !== undefined || record.scoped !== undefined) return
     this.methods.delete(method)
     Reflect.deleteProperty(this, method)
-    return true
   }
 }
 
diff --git a/packages/api/gateway/tests/client.spec.ts b/packages/api/gateway/tests/client.spec.ts
index d253c38acc..01bb9c53b7 100644
--- a/packages/api/gateway/tests/client.spec.ts
+++ b/packages/api/gateway/tests/client.spec.ts
@@ -316,6 +316,32 @@ describe('Client TypeRT API', () => {
     await retry()
   })
 
+  it('rolls back a direct projection when its scoped projection fails to install', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const disposeContext = await ctx.remote.$mount({
+      package: '@fixture/context-anchor',
+      descriptors: [contextDescriptor()],
+    })
+    const namespace = ctx.get('remote.goals') as unknown as {
+      installScoped: (...args: unknown[]) => void
+      readonly create?: unknown
+    }
+    const installScoped = vi.spyOn(namespace, 'installScoped').mockImplementation(() => {
+      throw new Error('fixture scoped projection failure')
+    })
+    try {
+      await expect(ctx.remote.$mount({
+        package: '@fixture/direct-projection-failure',
+        descriptors: [directDescriptor()],
+      })).rejects.toThrow('fixture scoped projection failure')
+    } finally {
+      installScoped.mockRestore()
+    }
+
+    expect(namespace.create).toBeUndefined()
+    await disposeContext()
+  })
+
   it('rejects weak parameter and Context codecs plus malformed scope projections', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const direct = directDescriptor()
@@ -406,6 +432,20 @@ describe('Client TypeRT API', () => {
     expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
   })
 
+  it('rejects a method obtained from a withdrawn namespace getter', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const dispose = await ctx.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
+    const namespace = ctx.get('remote.goals') as unknown as object
+    const getter = Object.getOwnPropertyDescriptor(namespace, 'create')?.get
+
+    await dispose()
+
+    expect(getter).toBeTypeOf('function')
+    const withdrawn = getter?.call(namespace) as (...args: unknown[]) => Promise<unknown>
+    await expect(withdrawn('agent-1', { objective: 'ship' }))
+      .rejects.toThrow('Remote method is no longer mounted')
+  })
+
   it('preserves a __proto__ wire parameter as an own named argument', async () => {
     const call = vi.fn<ConnectionHandle['rpc']['call']>()
       .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })

From 00a559bf2b97caf8f15b2e8303cbb17b061692de Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 20:16:29 +0800
Subject: [PATCH 158/516] test(api-gateway): assert withdrawn method failure

---
 packages/api/gateway/tests/client.spec.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/api/gateway/tests/client.spec.ts b/packages/api/gateway/tests/client.spec.ts
index 01bb9c53b7..2284fa662c 100644
--- a/packages/api/gateway/tests/client.spec.ts
+++ b/packages/api/gateway/tests/client.spec.ts
@@ -432,7 +432,7 @@ describe('Client TypeRT API', () => {
     expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
   })
 
-  it('rejects a method obtained from a withdrawn namespace getter', async () => {
+  it('fails a method obtained from a withdrawn namespace getter', async () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const dispose = await ctx.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
     const namespace = ctx.get('remote.goals') as unknown as object
@@ -442,8 +442,8 @@ describe('Client TypeRT API', () => {
 
     expect(getter).toBeTypeOf('function')
     const withdrawn = getter?.call(namespace) as (...args: unknown[]) => Promise<unknown>
-    await expect(withdrawn('agent-1', { objective: 'ship' }))
-      .rejects.toThrow('Remote method is no longer mounted')
+    expect(() => withdrawn('agent-1', { objective: 'ship' }))
+      .toThrow('Remote method is no longer mounted')
   })
 
   it('preserves a __proto__ wire parameter as an own named argument', async () => {

From ddd43ec3718eb4d97e1db072940e35073cad4d6c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 20:29:39 +0800
Subject: [PATCH 159/516] test(api-gateway): repair CI fixtures

---
 packages/api/gateway/tests/client.spec.ts                   | 6 +++---
 .../translation-prompt-v4/request-response.expected.json    | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/api/gateway/tests/client.spec.ts b/packages/api/gateway/tests/client.spec.ts
index 2284fa662c..641ea81ebc 100644
--- a/packages/api/gateway/tests/client.spec.ts
+++ b/packages/api/gateway/tests/client.spec.ts
@@ -436,12 +436,12 @@ describe('Client TypeRT API', () => {
     const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
     const dispose = await ctx.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
     const namespace = ctx.get('remote.goals') as unknown as object
-    const getter = Object.getOwnPropertyDescriptor(namespace, 'create')?.get
+    const getWithdrawn = Object.getOwnPropertyDescriptor(namespace, 'create')?.get?.bind(namespace)
 
     await dispose()
 
-    expect(getter).toBeTypeOf('function')
-    const withdrawn = getter?.call(namespace) as (...args: unknown[]) => Promise<unknown>
+    expect(getWithdrawn).toBeTypeOf('function')
+    const withdrawn = getWithdrawn?.() as (...args: unknown[]) => Promise<unknown>
     expect(() => withdrawn('agent-1', { objective: 'ship' }))
       .toThrow('Remote method is no longer mounted')
   })
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 794cf18f49..91509f3267 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository typecheck runs the whole-repo `tsc -b` graph: it emits every package/vendor `lib/types` and checks examples, tests, and scripts through two no-emit aggregates.\n\nThe repository's TypeScript configuration has exactly three roles; every tsconfig file plays one of them.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, references to the two aggregates. The whole-repo `tsc -b tsconfig.json` graph, the tsserver discovery entry, and — through the inherited `paths` — the resolution config for tsx running `examples/` and `scripts/` (their nearest tsconfig is this file). | No |\n| `tsconfig.host.json` | Host aggregate: host-side packages (via references), examples, tests, scripts, website. Excludes `packages/client`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the client aggregate and every `packages/client/*` package. | No |\n\nHost and client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Two disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges. Program-backed generators and gates (`scripts/ts-project.ts` consumers, doc-typecheck standalone mode) are host-only by decision; the client side gains program-backed tooling only with a concrete need.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteContext`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions and mounts concrete methods on `ctx.api` or the corresponding scoped Context. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository typecheck runs the whole-repo `tsc -b` graph: it emits every package/vendor `lib/types` and checks examples, tests, and scripts through two no-emit aggregates.\n\nThe repository's TypeScript configuration has exactly three roles; every tsconfig file plays one of them.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, references to the two aggregates. The whole-repo `tsc -b tsconfig.json` graph, the tsserver discovery entry, and — through the inherited `paths` — the resolution config for tsx running `examples/` and `scripts/` (their nearest tsconfig is this file). | No |\n| `tsconfig.host.json` | Host aggregate: host-side packages (via references), examples, tests, scripts, website. Excludes `packages/client`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the client aggregate and every `packages/client/*` package. | No |\n\nHost and client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Two disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges. Program-backed generators and gates (`scripts/ts-project.ts` consumers, doc-typecheck standalone mode) are host-only by decision; the client side gains program-backed tooling only with a concrete need.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库类型检查会执行全仓 `tsc -b` 图：它会发射每个 package/vendor 的 `lib/types`，并通过两个 no-emit 聚合检查示例、测试和脚本。\n\n仓库的 TypeScript 配置只有三种角色；每个 tsconfig 文件恰好扮演其中一种。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个聚合。全仓 `tsc -b tsconfig.json` 图、tsserver 发现入口，并经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置（它们最近的 tsconfig 就是此文件）。 | 否 |\n| `tsconfig.host.json` | host 聚合：host 侧各包（经 references）、示例、测试、脚本、website。排除 `packages/client`。 | 是 |\n| `tsconfig.client.json` | client 聚合：`packages/client/*` 各包及其测试、`apps/web`。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 client 聚合和每个 `packages/client/*` 包 extends。 | 否 |\n\nhost 与 client 保持两个聚合 program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个聚合，一个 paths 门面也可以横跨两侧。由此推出两条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个聚合展平进一个 program 会撞上 `Context` 合并冲突。基于 program 的生成器与门禁（`scripts/ts-project.ts` 的消费者、doc-typecheck standalone 模式）按决策仅覆盖 host 侧；client 侧只在出现真实需求时再获得基于 program 的工具。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteContext` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并将具体方法挂载到 `ctx.api` 或对应的作用域 Context。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库类型检查会执行全仓 `tsc -b` 图：它会发射每个 package/vendor 的 `lib/types`，并通过两个 no-emit 聚合检查示例、测试和脚本。\n\n仓库的 TypeScript 配置只有三种角色；每个 tsconfig 文件恰好扮演其中一种。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个聚合。全仓 `tsc -b tsconfig.json` 图、tsserver 发现入口，并经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置（它们最近的 tsconfig 就是此文件）。 | 否 |\n| `tsconfig.host.json` | host 聚合：host 侧各包（经 references）、示例、测试、脚本、website。排除 `packages/client`。 | 是 |\n| `tsconfig.client.json` | client 聚合：`packages/client/*` 各包及其测试、`apps/web`。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 client 聚合和每个 `packages/client/*` 包 extends。 | 否 |\n\nhost 与 client 保持两个聚合 program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个聚合，一个 paths 门面也可以横跨两侧。由此推出两条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个聚合展平进一个 program 会撞上 `Context` 合并冲突。基于 program 的生成器与门禁（`scripts/ts-project.ts` 的消费者、doc-typecheck standalone 模式）按决策仅覆盖 host 侧；client 侧只在出现真实需求时再获得基于 program 的工具。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",

From 71ebeaa55985a4033c86793f6c91fc0fe65cf8b0 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:43:34 +0800
Subject: [PATCH 160/516] fix(client-runtime): localize remote namespace
 dependency

---
 docs/api-gateway.i18n.yaml                         | 4 ++--
 docs/api-gateway.md                                | 4 +++-
 docs/api-gateway.zh.md                             | 4 +++-
 packages/client/runtime/src/client/index.ts        | 4 ++--
 packages/client/runtime/tests/client-apply.spec.ts | 1 -
 packages/client/runtime/tests/wire-events.spec.ts  | 1 -
 6 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index 2a6ae0807b..074644ff3e 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.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 docs/api-gateway.md
-api-gateway.md: ba95d429dd0c9f9f354baf0063197cea6e3ecbf8
-api-gateway.zh.md: 4e42ebea7a5db19c7df23079050b9488679a3a23
+api-gateway.md: 33dfb30c9da25e46b660a3fa54ef37f587cbda08
+api-gateway.zh.md: 633eb10c0f2f065ecf27545813cc17d79f391865
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index ba95d429dd..33dfb30c9d 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -55,7 +55,7 @@ export class GoalService extends GatewayService {
 
 Remote methods may return a value synchronously or return a Promise. For cooperative cancellation, the final parameter in the Host signature must be `signal: AbortSignal` using the global type; it is recorded in the descriptor instead of entering `args`, while the generated Client method accepts an optional final `AbortSignal`.
 
-The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct and scoped calls appear under `ctx.remote.<namespace>` and `agentCtx.remote.<namespace>`. Each namespace is a traced Cordis child Service registered as `remote.<namespace>`; the Client assembly mounts contributions through `ctx.remote.$mount()`, consumers inject both `remote` and the namespace Service they call, and the namespace unloads after its last method is withdrawn. When an `@Remote` method has exactly one lookup parameter and a same-named `TypeRTContextMap` uses the same wire identity, the generated scoped signature omits that identity parameter. `@RemoteScope` generates only the scoped invocation interface.
+The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct and scoped calls appear under `ctx.remote.<namespace>` and `agentCtx.remote.<namespace>`. Each namespace is a traced Cordis child Service registered as `remote.<namespace>`; the Client assembly mounts contributions through `ctx.remote.$mount()`, and the namespace unloads after its last method is withdrawn. Dependency declarations belong to the actual caller: only a business package that reads `ctx.remote.<namespace>` or `agentCtx.remote.<namespace>` declares both `remote` and `remote.<namespace>` in its own `inject`; assemblies that only mount contributions and higher-level runtimes that do not call that namespace do not declare the namespace dependency on the business package's behalf. When an `@Remote` method has exactly one lookup parameter and a same-named `TypeRTContextMap` uses the same wire identity, the generated scoped signature omits that identity parameter. `@RemoteScope` generates only the scoped invocation interface.
 
 ```ts
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -63,6 +63,8 @@ import type { AgentContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { Context } from 'cordis'
 import type {} from '@deepseek-ai/dsh-api-remotes/client'
 
+export const inject = ['remote', 'remote.goals']
+
 declare const ctx: Context
 declare const agentCtx: AgentContext
 declare const agentId: SessionId
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 4e42ebea7a..633eb10c0f 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -55,7 +55,7 @@ export class GoalService extends GatewayService {
 
 Remote 方法可以同步返回或返回 Promise。若需要协作式取消，Host 签名的最后一个参数必须是全局类型的 `signal: AbortSignal`；它记录在描述符中而不是进入 `args`，Client 生成的方法则接受最后一个可选的 `AbortSignal`。
 
-Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子 Service；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，消费方同时注入 `remote` 与所调用的 namespace Service，最后一个方法撤回后该 namespace 随即卸载。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用界面。
+Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子 Service；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，最后一个方法撤回后该 namespace 随即卸载。依赖声明归实际调用方所有：只有读取 `ctx.remote.<namespace>` 或 `agentCtx.remote.<namespace>` 的业务包才在自己的 `inject` 中同时声明 `remote` 与 `remote.<namespace>`；只负责挂载 contribution 的 assembly，以及不调用该 namespace 的上层 runtime，不代业务包声明 namespace 依赖。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用界面。
 
 ```ts
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -63,6 +63,8 @@ import type { AgentContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { Context } from 'cordis'
 import type {} from '@deepseek-ai/dsh-api-remotes/client'
 
+export const inject = ['remote', 'remote.goals']
+
 declare const ctx: Context
 declare const agentCtx: AgentContext
 declare const agentId: SessionId
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index b772e315a3..5a1677df96 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -179,8 +179,8 @@ declare module 'cordis' {
   }
 }
 
-/** Required services: the Remote root and Goal namespace, wire handle, and Client TypeRT registry. */
-export const inject = ['remote', 'remote.goals', 'connection', 'typert']
+/** Required services: the Remote root, wire handle, and Client TypeRT registry. */
+export const inject = ['remote', 'connection', 'typert']
 
 /** Mounts the browser runtime services and connection stream.
  * @param ctx - Client Cordis context.
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index e9b387fb00..b700c4c066 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -39,7 +39,6 @@ async function mount(): Promise<Bench> {
   }
   ctx.reflect.provide('connection', handle)
   ctx.reflect.provide('remote', {})
-  ctx.reflect.provide('remote.goals', {})
   await ctx.plugin(RuntimeClient).await()
   return bench
 }
diff --git a/packages/client/runtime/tests/wire-events.spec.ts b/packages/client/runtime/tests/wire-events.spec.ts
index 703c5b1728..dfafcd07aa 100644
--- a/packages/client/runtime/tests/wire-events.spec.ts
+++ b/packages/client/runtime/tests/wire-events.spec.ts
@@ -33,7 +33,6 @@ async function mount(): Promise<Bench> {
   }
   ctx.reflect.provide('connection', handle)
   ctx.reflect.provide('remote', {})
-  ctx.reflect.provide('remote.goals', {})
   await ctx.plugin(RuntimeClient).await()
   return bench
 }

From 3dfb16008de63d472b10b3c6db074e89c2322c17 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:24:16 +0800
Subject: [PATCH 161/516] docs(config): align environment and credential
 contracts

Code already treats $DSH_HOME/.env as ordinary launch environment and stores managed credentials in .credentials.yaml, but public docs still described the old store, old precedence, removed literal adapter keys, and the deleted TUI. That directed users to the wrong file and overstated the supported configuration surface.

Update the existing English and Chinese owners in place, document inherited > managed > project > user credential resolution, and record the loadLayeredEnv export. Regenerate only pairing records and the source-line catalog; add no new section or site route.
---
 ...026-08-04-configuration-source-ownership.i18n.yaml |  4 ++--
 .../2026-08-04-configuration-source-ownership.md      |  4 ++--
 .../2026-08-04-configuration-source-ownership.zh.md   |  4 ++--
 ...dentials-yaml-and-user-environment-layer.i18n.yaml |  4 ++--
 ...-04-credentials-yaml-and-user-environment-layer.md | 11 +++++------
 ...-credentials-yaml-and-user-environment-layer.zh.md | 11 +++++------
 apps/cli/reference/README.i18n.yaml                   |  4 ++--
 apps/cli/reference/README.md                          |  2 +-
 apps/cli/reference/README.zh.md                       |  2 +-
 docs/config-catalog.md                                |  2 +-
 docs/cordis-tutorial/05-config.i18n.yaml              |  4 ++--
 docs/cordis-tutorial/05-config.md                     |  6 +++---
 docs/cordis-tutorial/05-config.zh.md                  |  6 +++---
 docs/user/guide/config.i18n.yaml                      |  4 ++--
 docs/user/guide/config.md                             |  9 ++-------
 docs/user/guide/config.zh.md                          |  9 ++-------
 docs/user/guide/index.i18n.yaml                       |  4 ++--
 docs/user/guide/index.md                              |  2 --
 docs/user/guide/index.zh.md                           |  2 --
 docs/user/guide/providers.i18n.yaml                   |  4 ++--
 docs/user/guide/providers.md                          |  6 +++---
 docs/user/guide/providers.zh.md                       |  6 +++---
 packages/bundle/base/cordis.patch.yml                 | 10 ++++------
 packages/client/ui-models/README.i18n.yaml            |  4 ++--
 packages/client/ui-models/README.md                   |  6 +++---
 packages/client/ui-models/README.zh.md                |  6 +++---
 .../credentials/credentials-local/README.i18n.yaml    |  4 ++--
 packages/credentials/credentials-local/README.md      |  2 +-
 packages/credentials/credentials-local/README.zh.md   |  2 +-
 packages/credentials/credentials-local/src/index.ts   |  7 +++----
 packages/credentials/credentials/README.i18n.yaml     |  4 ++--
 packages/credentials/credentials/README.md            |  2 +-
 packages/credentials/credentials/README.zh.md         |  2 +-
 packages/llm/llm-pi-ai/README.i18n.yaml               |  4 ++--
 packages/llm/llm-pi-ai/README.md                      | 10 +++++-----
 packages/llm/llm-pi-ai/README.zh.md                   | 10 +++++-----
 packages/llm/llm-retry/README.i18n.yaml               |  4 ++--
 packages/llm/llm-retry/README.md                      |  2 +-
 packages/llm/llm-retry/README.zh.md                   |  2 +-
 packages/ui/app-boot/README.i18n.yaml                 |  4 ++--
 packages/ui/app-boot/README.md                        |  5 +++--
 packages/ui/app-boot/README.zh.md                     |  5 +++--
 42 files changed, 94 insertions(+), 111 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 38d2409b9d..32f4e05648 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: e06dbc85f2307fa8a50fba13000f42306d69d9bf
-2026-08-04-configuration-source-ownership.zh.md: 6c6a128f1279a271f583e0bf4bcd27d0e5b81162
+2026-08-04-configuration-source-ownership.md: 2603736e35fbf838609fd2ca133785cfe5534e27
+2026-08-04-configuration-source-ownership.zh.md: 98c9291503201db81b5b4797dcc04823e0a27db7
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index e06dbc85f2..2603736e35 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -40,7 +40,7 @@ inherited process environment      (read-only, wins)
 
 The launching environment wins because `DEEPSEEK_API_KEY=… dsh`, a CI secret, and a container `-e` are the one override an operator must be able to apply per run without editing machine state, and because it cannot be edited from inside it must be *visibly* read-only. Configuration is meant to carry only the *reference* — which name to resolve — and that name follows the non-secret ordering above.
 
-**The project the harness is launched in is trusted, by default and without a prompt.** A checkout may carry its own endpoint, its own ordinary variables, and its own key; the key ranks below the managed store, so a key stored through the web page or TUI is never displaced by one a checkout happens to contain. `EnvironmentSnapshot.getFrom(name, sources)` still searches only the layers a caller names, and omitting one is a refusal rather than a demotion — the mechanism exists for the decisions where a layer must be unreachable, not because the project is one of them today.
+**The project the harness is launched in is trusted, by default and without a prompt.** A checkout may carry its own endpoint, its own ordinary variables, and its own key; the key ranks below the managed store, so a key stored through the Models page is never displaced by one a checkout happens to contain. `EnvironmentSnapshot.getFrom(name, sources)` still searches only the layers a caller names, and omitting one is a refusal rather than a demotion — the mechanism exists for the decisions where a layer must be unreachable, not because the project is one of them today.
 
 **Trust does not extend to changing the harness itself.** `isBootstrapOnly` rejects, at load and before anything is materialized, any `.env` that sets a variable governing how a process launches (`PATH`, `SHELL`, `NODE_OPTIONS`, `LD_PRELOAD`), what code a runtime executes before the program it was asked to run (`BASH_ENV`, `PERL5OPT`, `PYTHONSTARTUP`, `RUBYOPT`, `JAVA_TOOL_OPTIONS`, the Git hook commands), where model-visible instructions load from (the whole `DSH_*` namespace, `HOME`, `XDG_*`), or how the network is reached and trusted (proxy and CA variables). Matching is case-insensitive, so `https_proxy` is not a bypass.
 
@@ -55,7 +55,7 @@ The line is that these take effect with no user action, before any turn, outside
 - The web credential form now takes effect against an older key in the user's `.env`; only a key exported in the launching shell still makes it read-only, and the diagnostic says so.
 - A `.env` holding `DSH_*`, `PATH`, or a proxy variable fails the launch instead of being applied. Developers keeping switches in a repository `.env` move them to their shell — a deliberate, loud break.
 - Composition is no longer overridable by a stale shell endpoint. It is still overridable by a user's stored `settings.yaml`, which is the settings seam's layering and not something this note changes; the product CLI offers no flag above it, so a deployment that must win against stored settings owns its own bin or loader tree.
-- Not solved: the layers are still materialized into `process.env`, so ordinary project variables continue to reach child processes under the subprocess scrub. Bootstrap variables cannot come from a file at all, which closes the escalation path; a project `.env` setting something like `GIT_SSH_COMMAND` for the tools an agent runs remains possible and is recorded as a limitation on the package.
+- Not solved: the layers are still materialized into `process.env`, so ordinary project variables continue to reach child processes under the subprocess scrub. Bootstrap variables cannot come from a file at all; the environment package records the remaining subprocess reach as a limitation.
 - The LLM adapters no longer accept a literal `apiKey`: configuration carries the reference and nothing else, so a settings document cannot become a second credential store. No adapter namespace is strict, so writing one is dropped rather than rejected. The web-search providers still declare a `role('secret')` literal key; they register no settings namespace, so nothing can shadow a stored credential through them, but the claim is about the adapters rather than the repository as a whole.
 - Exa and Perplexity still capture their key at load time rather than through the credential seam. They no longer read raw `process.env` — they resolve through the trusted layers — but converting them to per-request seam resolution is separate work.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index 6c6a128f12..98c9291503 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -42,7 +42,7 @@ inherited process environment      (read-only, wins)
 
 继承环境优先，因为 `DEEPSEEK_API_KEY=… dsh`、CI 机密与容器 `-e` 是运维必须能按次施加、且无需改动机器状态的那一种覆盖；而它无法从进程内部修改，就必须*可见地*只读。配置本应只携带*引用*——解析哪个名字——该名字本身遵循上面的非密钥顺序。
 
-**harness 被启动于其中的项目默认可信，且不做询问。** 一个 checkout 可以携带自己的 endpoint、自己的普通变量和自己的密钥；密钥排在受管存储之下，因此通过 Web 页面或 TUI 存下的密钥绝不会被 checkout 中恰好带有的那一个顶掉。`EnvironmentSnapshot.getFrom(name, sources)` 仍然只搜索调用方点名的层，省略某层仍是拒绝而不是降级——该机制是为「某一层必须不可达」的那些决策准备的，而项目层今天不在其列。
+**harness 被启动于其中的项目默认可信，且不做询问。** 一个 checkout 可以携带自己的 endpoint、自己的普通变量和自己的密钥；密钥排在受管存储之下，因此通过 Models 页存下的密钥绝不会被 checkout 中恰好带有的那一个顶掉。`EnvironmentSnapshot.getFrom(name, sources)` 仍然只搜索调用方点名的层，省略某层仍是拒绝而不是降级——该机制是为「某一层必须不可达」的那些决策准备的，而项目层今天不在其列。
 
 **信任不延伸到改变 harness 本身。** `isBootstrapOnly` 会在加载时、且在物化任何内容之前，拒绝任何设置了下列变量的 `.env`：决定进程如何启动的（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD`）、决定运行时在执行被要求运行的程序之前先执行哪些代码的（`BASH_ENV`、`PERL5OPT`、`PYTHONSTARTUP`、`RUBYOPT`、`JAVA_TOOL_OPTIONS`、Git 的钩子命令）、决定模型可见指令从哪里加载的（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），以及决定网络如何抵达与信任的（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
 
@@ -57,7 +57,7 @@ inherited process environment      (read-only, wins)
 - Web 凭据表单现在能压过用户 `.env` 里更旧的密钥；只有在启动 shell 里 export 的密钥才会让它变成只读，诊断信息也会这么说。
 - 含 `DSH_*`、`PATH` 或 proxy 变量的 `.env` 会导致启动失败而不是被应用。把开关放在仓库 `.env` 里的开发者需要改放到 shell——这是一次刻意且响亮的破坏。
 - composition 不再会被陈旧的 shell endpoint 覆盖。但它仍然会被用户已存的 `settings.yaml` 覆盖，这是 settings seam 的分层方式，本 Note 不改变它；产品 CLI 没有高于它的标志，因此需要压过已存 settings 的部署方要自带 bin 或 loader 配置树。
-- 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件，提权路径已封闭；项目 `.env` 为 agent 运行的工具设置诸如 `GIT_SSH_COMMAND` 之类的变量仍然可能，已作为限制记录在该包上。
+- 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件；其余变量抵达子进程的限制记录在环境包中。
 - LLM 适配器不再接受字面 `apiKey`：配置只携带引用，因此 settings 文档无法成为第二个凭据存储。由于没有任何适配器 namespace 是 strict 的，写入该键会被 schema 丢弃而不是报错。web-search 提供方仍声明 `role('secret')` 的字面密钥字段；它们不注册 settings namespace，因此无法借此遮蔽已存凭据，但这条声明的范围是适配器，而不是整个仓库。
 - Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求经 seam 解析是另一件事。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
index 376838d151..ba4444166c 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.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 .agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
-2026-08-04-credentials-yaml-and-user-environment-layer.md: f03f3f885c13476619ba3cda51e2dfed7e3258c1
-2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 7cce1daeffadb18678f00a5c9acd1b14c6ac1b22
+2026-08-04-credentials-yaml-and-user-environment-layer.md: 4ecbc41adf4e22c74ecf425c2caf628efdf7cf54
+2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 370179b442783f4f8ecd8e3badbd236a924f5f81
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
index f03f3f885c..4ecbc41adf 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-04-credentials-yaml-and-user-environment-layer.zh.md)
 
 ## Problem
 
-`$DSH_HOME/.env` carried two incompatible jobs. It was the writable secret store of [`credentials-local`](../../../../packages/credentials/credentials-local/README.md), so no surface could hoist it into `process.env` — hoisting would make every stored key read as a read-only launch override and block rotation from the TUI and the web page. But its name and dotenv format promise an environment file, so users put non-secrets in it and those values reached nothing: a `DEEPSEEK_BASE_URL` beside a working `DEEPSEEK_API_KEY` in the same file was silently ignored, because only the credential provider read the document and it addresses credential references alone.
+`$DSH_HOME/.env` carried two incompatible jobs. It was the writable secret store of [`credentials-local`](../../../../packages/credentials/credentials-local/README.md), so no surface could hoist it into `process.env` — hoisting would make every stored key read as a read-only launch override and block rotation from the Models page. But its name and dotenv format promise an environment file, so users put non-secrets in it and those values reached nothing: a `DEEPSEEK_BASE_URL` beside a working `DEEPSEEK_API_KEY` in the same file was silently ignored, because only the credential provider read the document and it addresses credential references alone.
 
 One file cannot be both a store the Harness owns and isolates and a layer that propagates by ordinary environment rules. The [request-level credential decision](2026-07-29-request-level-llm-config-credentials.md) chose dotenv to match peer products' home `.env`, and the conflation was not visible until a non-secret needed the same file.
 
@@ -23,16 +23,15 @@ OPENAI_API_KEY: sk-…
 
 Because the document holds credentials and nothing else, every deviation is a rejection rather than a skipped entry: a non-mapping root, a key that is not a POSIX identifier, a non-string value, an empty string, a duplicate key, and malformed YAML all fail — loud at boot and at a write, warn-and-keep-the-last-good-snapshot on a live reload. A silently ignored key would read as "the secret I stored has no effect", which is the failure this change exists to remove. The dotenv physical-line editor is replaced by a patch of the parsed document, so comments and untouched entries keep their formatting, any string value round-trips (multi-line included), and no entry is unwritable for want of a quoting style. The writer lock, read-modify-write, atomic `0600` write under a `0700` directory, exact-path watcher, content-equality self-write suppression, and quiescent disposal are unchanged.
 
-**`$DSH_HOME/.env` is the user's ordinary environment layer.** `loadLayeredEnv` in [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) loads the invoking directory's `.env` and then the Harness home's, giving `user < project < inherited` — `process.loadEnvFile` never replaces a name already set, which is what the load order exploits and what the app-boot tests pin across all three layers. The Harness home is resolved from the inherited environment *before* either file loads, so a project `.env` cannot redirect which user document is read. Only the product CLI layers these files; SDK and example bins keep loading their own directory through `loadEnv` and must not inherit a developer's `$DSH_HOME`.
+**`$DSH_HOME/.env` is the user's ordinary environment layer.** `loadLayeredEnv` in [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) parses the invoking directory's `.env` and then the Harness home's, giving `user < project < inherited` by materializing each accepted value only when the process has no higher-layer value. The Harness home is resolved from the inherited environment *before* either file loads, so a project `.env` cannot redirect which user document is read. Only the product CLI layers these files; SDK and example bins keep loading their own directory through `loadEnv` and must not inherit a developer's `$DSH_HOME`.
 
-Credential precedence is unchanged this round: the live process environment still wins read-only over the file, and `set`/`unset` still reject a write the environment would shadow. Whether a provider-managed store should instead win over the environment is a separate decision, deliberately not taken here.
+Credential precedence distinguishes the inherited environment from discovered files: the inherited value stays the read-only per-run override, the managed document wins next, and project then user `.env` values remain writable fallbacks. A `set` therefore replaces a discovered-file value instead of rejecting a write that only the flattened `process.env` view would consider shadowed.
 
-There is no migration. The product is unreleased, and a key already in `$DSH_HOME/.env` keeps resolving through the new environment layer — as a read-only `env` source that shadows the stored one, which is exactly what the diagnostics say.
+There is no migration. A key already in `$DSH_HOME/.env` keeps resolving as a fallback, while the managed document wins as soon as the Models page stores that reference.
 
 ## Consequences
 
-- Given up: a key left in `$DSH_HOME/.env` is now hoisted into `process.env`, so it reaches subprocesses under the [subprocess credential scrub](../../../../packages/subprocess/subprocess/README.md) rather than staying inside the provider. That is the honest meaning of "ordinary environment layer"; a secret the Harness should own and isolate belongs in `.credentials.yaml`, which is never hoisted.
-- Given up: the same key shadows `.credentials.yaml` and makes the web Models page's write reject. The seam already reports `source: 'env', writable: false` for that state, and the rejection message now names the loaded `.env` as a place to unset it.
+- Given up: a key left in `$DSH_HOME/.env` is materialized into `process.env`, so it reaches subprocesses under the [subprocess credential scrub](../../../../packages/subprocess/subprocess/README.md) rather than staying inside the provider. It remains a writable fallback below `.credentials.yaml`; a secret the Harness should own and isolate belongs in the managed document, which is never materialized.
 - Bought: a non-secret in the user's `.env` finally takes effect, which was the original defect; the document format can reject what it cannot serve; and `0600` covers a file that holds only secrets instead of a file users are told to put ordinary configuration in.
 - The `0600` the provider writes is also enforced on what it reads: on POSIX, a document with any group or other permission bit fails the launch before its contents are read, at boot and on every reload, and the diagnostic names the `chmod 600` repair. Windows has no mode to inspect — its ACLs are not expressible here — so the check is skipped rather than faked.
 - The `0600` boundary still stops other OS users and not the model, unchanged by this split — the [provider README](../../../../packages/credentials/credentials-local/README.md) owns that limit and the keychain-provider deferral.
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
index 7cce1daeff..370179b442 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-`$DSH_HOME/.env` 同时承担了两件互不相容的工作。它是 [`credentials-local`](../../../../packages/credentials/credentials-local/README.md) 的可写密钥存储，因此任何表层都不能把它提升进 `process.env`——一旦提升，每个已存密钥都会读作只读的启动时覆盖，从而阻断从 TUI 与 Web 页面轮换密钥。但它的文件名和 dotenv 格式承诺的是一个环境文件，于是用户把非密钥值放进去，而那些值哪儿也到不了：同一个文件里，一个能用的 `DEEPSEEK_API_KEY` 旁边的 `DEEPSEEK_BASE_URL` 会被静默忽略，因为只有凭据 provider 读这份文档，而它只寻址凭据引用。
+`$DSH_HOME/.env` 同时承担了两件互不相容的工作。它是 [`credentials-local`](../../../../packages/credentials/credentials-local/README.md) 的可写密钥存储，因此任何表层都不能把它提升进 `process.env`——一旦提升，每个已存密钥都会读作只读的启动时覆盖，从而阻断从 Models 页轮换密钥。但它的文件名和 dotenv 格式承诺的是一个环境文件，于是用户把非密钥值放进去，而那些值哪儿也到不了：同一个文件里，一个能用的 `DEEPSEEK_API_KEY` 旁边的 `DEEPSEEK_BASE_URL` 会被静默忽略，因为只有凭据 provider 读这份文档，而它只寻址凭据引用。
 
 一个文件无法既是由 Harness 拥有并隔离的存储，又是按普通环境规则传播的层。[请求级凭据决策](2026-07-29-request-level-llm-config-credentials.md)当初选择 dotenv 是为了对齐同类产品的 home `.env`，而这种混同直到有非密钥值需要用同一个文件时才暴露出来。
 
@@ -23,16 +23,15 @@ OPENAI_API_KEY: sk-…
 
 因为该文档只存放凭据、别无他物，任何偏离都是拒绝而不是跳过条目：非 mapping 的根、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败——启动时和写入时响亮失败，运行期热重载则告警并保留最后可用快照。被静默忽略的键读起来就是「我存进去的密钥没有生效」，而这正是本次变更要消除的失败。dotenv 物理行编辑器被替换为对已解析文档打补丁，因此注释与未触及条目的排版都会保留，任何字符串值都能往返（含多行），也不会再有条目因为缺少可用引号样式而不可写。写锁、read-modify-write、`0700` 目录下的 `0600` 原子写、精确路径 watcher、按内容相等抑制自写、以及 dispose 时的完全停稳，均保持不变。
 
-**`$DSH_HOME/.env` 是用户的普通环境层。** [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) 中的 `loadLayeredEnv` 先加载调用目录的 `.env`，再加载 Harness home 的，得到 `用户 < 项目 < 继承`——`process.loadEnvFile` 从不替换已经设置的名字，加载顺序正是利用了这一点，app-boot 的测试也把三层一起钉住。Harness home 在两个文件加载*之前*就从继承的环境解析完毕，因此项目 `.env` 无法改变读取哪份用户文档。只有产品 CLI（命令行界面）叠加这两个文件；SDK 与示例 bin 仍通过 `loadEnv` 加载各自的目录，绝不继承开发者的 `$DSH_HOME`。
+**`$DSH_HOME/.env` 是用户的普通环境层。** [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) 中的 `loadLayeredEnv` 先解析调用目录的 `.env`，再解析 Harness home 的，并且只在进程中没有更高层值时物化每个已接受的值，从而得到 `用户 < 项目 < 继承`。Harness home 在两个文件加载*之前*就从继承的环境解析完毕，因此项目 `.env` 无法改变读取哪份用户文档。只有产品 CLI（命令行界面）叠加这两个文件；SDK 与示例 bin 仍通过 `loadEnv` 加载各自的目录，绝不继承开发者的 `$DSH_HOME`。
 
-本轮不改凭据优先级：活跃进程环境仍然只读地优先于文件，`set`/`unset` 仍然拒绝会被环境遮蔽的写入。provider 管理的存储是否应当反过来压过环境，是另一个决策，此处刻意不作。
+凭据优先级会区分继承环境与发现的文件：继承值仍是只读的按次覆盖，其后是受管文档，再后是仍可写的项目与用户 `.env` 后备值。因此 `set` 会替换发现文件中的值，而不是因为扁平化的 `process.env` 视图认为写入会被遮蔽就加以拒绝。
 
-不做迁移。产品尚未发布，而已经放在 `$DSH_HOME/.env` 里的密钥会继续通过新的环境层解析——作为只读的 `env` 来源遮蔽已存储的那一份，诊断给出的也正是这个结论。
+不做迁移。已经放在 `$DSH_HOME/.env` 里的密钥会继续作为后备值解析；Models 页一旦存储该引用，受管文档就会优先。
 
 ## Consequences
 
-- 放弃的：留在 `$DSH_HOME/.env` 里的密钥现在会被提升进 `process.env`，因而会按[子进程凭据清洗](../../../../packages/subprocess/subprocess/README.md)的规则抵达子进程，而不再留在 provider 内部。这就是「普通环境层」的诚实含义；需要由 Harness 拥有并隔离的密钥属于 `.credentials.yaml`，后者永不提升。
-- 放弃的：同一个键会遮蔽 `.credentials.yaml`，并让 Web Models 页的写入被拒。seam 对这种状态本来就报告 `source: 'env', writable: false`，而拒绝信息现在会把已加载的 `.env` 一并指为需要清除的位置。
+- 放弃的：留在 `$DSH_HOME/.env` 里的密钥会被物化进 `process.env`，因而会按[子进程凭据清洗](../../../../packages/subprocess/subprocess/README.md)的规则抵达子进程，而不再留在 provider 内部。它仍是 `.credentials.yaml` 之下的可写后备值；需要由 Harness 拥有并隔离的密钥属于受管文档，后者永不物化。
 - 换来的：用户 `.env` 里的非密钥值终于生效，这正是最初的缺陷；文档格式可以拒绝它无法承担的内容；`0600` 保护的是一个只存密钥的文件，而不是一个我们同时叫用户往里写普通配置的文件。
 - provider 写入时用的 `0600` 同样约束它读取的内容：在 POSIX 上，只要文档带有任何 group 或 other 权限位，就会在读取内容之前让启动失败——启动时与每次 reload 都检查，诊断里给出 `chmod 600` 的修复命令。Windows 没有可检查的 mode（其 ACL 无法在此表达），因此跳过该检查而不是伪造它。
 - `0600` 这条边界仍然只挡其他 OS 用户、挡不住模型，本次拆分未改变这一点——该限制及 keychain provider 的延后项归 [provider README](../../../../packages/credentials/credentials-local/README.md) 所有。
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 07d7810529..e64141c31d 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
-README.md: 8b8a0e7dbebafedd6a4f8d988adb3fd11c7bd026
-README.zh.md: d1d6d5a594596a8be5db30021163f0fcea4a95bf
+README.md: c7c7b2aa231d4c9f4b3fbf31663237c8457eb051
+README.zh.md: 5439aa78b74415c8e6264d21f5c52e5cee5b38ee
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index 8b8a0e7dbe..c7c7b2aa23 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -59,7 +59,7 @@ New sessions default to the `workspace-write` permission preset. Bash and filesy
 
 ## Shared deployment behavior
 
-The base bundle mounts the native DeepSeek adapter, settings and credential providers, stable `web_search`, repository Plugin support, and session telemetry. Provider credentials live in `$DSH_HOME/.env` or the ambient environment and remain rotatable because the launcher never hoists the credential file into `process.env`. Search uses `DEEPSEEK_API_KEY` and accepts `DEEPSEEK_SEARCH_BASE_URL`; `web_fetch` is disabled unless a patch layer inserts a provider and enables it.
+The base bundle mounts the native DeepSeek adapter, settings and credential providers, stable `web_search`, repository Plugin support, and session telemetry. Provider credentials resolve from the inherited environment, `$DSH_HOME/.credentials.yaml`, the invoking directory's `.env`, then `$DSH_HOME/.env`; the managed document is never materialized into `process.env`, while both `.env` files are ordinary launch environment layers. Search uses `DEEPSEEK_API_KEY` and accepts `DEEPSEEK_SEARCH_BASE_URL`; `web_fetch` is disabled unless a patch layer inserts a provider and enables it.
 
 Session events stream as OTLP/HTTP logs by default. `DSH_TELEMETRY_OTLP_URL` selects another collector. Any non-empty `DSH_TELEMETRY_DISABLED` disables the telemetry row before boot. The shipped base has no telemetry redaction rule, so exported records can contain message text, tool arguments and results, and workspace paths; the [telemetry Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md) owns that deployment decision.
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index d1d6d5a594..5439aa78b7 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -59,7 +59,7 @@ dsh web --dump-config
 
 ## 共享部署行为
 
-基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search`、repository Plugin 支持和会话遥测。提供方凭据存放在 `$DSH_HOME/.env` 或环境中；启动器从不把凭据文件提升到 `process.env`，因此凭据可以轮换。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`；只有 patch 层插入提供方并启用 `web_fetch` 后，该工具才可用。
+基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search`、repository Plugin 支持和会话遥测。提供方凭据依次从继承环境、`$DSH_HOME/.credentials.yaml`、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析；受管文档从不物化进 `process.env`，而两个 `.env` 文件都是普通启动环境层。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`；只有 patch 层插入提供方并启用 `web_fetch` 后，该工具才可用。
 
 会话事件默认作为 OTLP/HTTP 日志流式发送。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。任何非空 `DSH_TELEMETRY_DISABLED` 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由[遥测 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)负责。
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 2902d30c8f..d207207073 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -437,7 +437,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts)
+Source: [`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-frontend-static`
 
diff --git a/docs/cordis-tutorial/05-config.i18n.yaml b/docs/cordis-tutorial/05-config.i18n.yaml
index 01047ad516..db300b1745 100644
--- a/docs/cordis-tutorial/05-config.i18n.yaml
+++ b/docs/cordis-tutorial/05-config.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 docs/cordis-tutorial/05-config.md
-05-config.md: fc19add239636fa9e7071d9c77e48595caec1f08
-05-config.zh.md: 0c8170f518f0c87ab5c754606436496a4ff9d51e
+05-config.md: 8d4043e33a58fc425d82d9846ff82473bcdef4c1
+05-config.zh.md: e9463bd34e9c72dbae7b1ceb9907e35edf7b773b
diff --git a/docs/cordis-tutorial/05-config.md b/docs/cordis-tutorial/05-config.md
index fc19add239..8d4043e33a 100644
--- a/docs/cordis-tutorial/05-config.md
+++ b/docs/cordis-tutorial/05-config.md
@@ -69,12 +69,12 @@ The plugin's fiber goes to FAILED, and this tutorial's launcher exits with statu
 
 ## Computed config values
 
-The loader used in this repo supports a `!!js` tag for config values that must be computed at load time, such as reading an API key from the environment:
+The loader used in this repo supports a `!!js` tag for config values that must be computed at load time:
 
 ```yaml
-- name: '@deepseek-ai/dsh-llm-deepseek'
+- name: './config-demo.ts'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    greeting: !!js process.env.DEMO_GREETING ?? 'Hello'
 ```
 
 `!!js` works **only inside `config`**. Entry metadata (`name`, `id`, `disabled`, `inject`, ...) is static; `disabled: !!js ...` produces a truthy expression object that always disables the entry. See [loader configuration](../cordis-primer.md#loader-configuration).
diff --git a/docs/cordis-tutorial/05-config.zh.md b/docs/cordis-tutorial/05-config.zh.md
index 0c8170f518..e9463bd34e 100644
--- a/docs/cordis-tutorial/05-config.zh.md
+++ b/docs/cordis-tutorial/05-config.zh.md
@@ -69,12 +69,12 @@ ValidationError: invalid config:
 
 ## 计算得到的配置值
 
-本仓库使用的 loader 支持 `!!js` 标签，用于必须在加载时计算的配置值，例如从环境中读取 API key：
+本仓库使用的 loader 支持 `!!js` 标签，用于必须在加载时计算的配置值：
 
 ```yaml
-- name: '@deepseek-ai/dsh-llm-deepseek'
+- name: './config-demo.ts'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    greeting: !!js process.env.DEMO_GREETING ?? 'Hello'
 ```
 
 `!!js` **仅在 `config` 内有效**。Cordis 配置项的元数据（`name`、`id`、`disabled`、`inject` 等）是静态的；`disabled: !!js ...` 会生成一个真值表达式对象，始终禁用该 Cordis 配置项。详见 [loader 配置](../cordis-primer.md#loader-configuration)。
diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml
index 172af1bcac..954eab633d 100644
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.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 docs/user/guide/config.md
-config.md: 0f1a99ed0afdab13d052ae2714fc2e1718d3d85e
-config.zh.md: 74e14e4e6e1fbb38a7a8d5167a4747080a662128
+config.md: 34ab38c60cc7a9b6026f5be2be47f440eb6cb08d
+config.zh.md: ce965dfc67c759ffcbad7b044b74abb2025851c2
diff --git a/docs/user/guide/config.md b/docs/user/guide/config.md
index 0f1a99ed0a..34ab38c60c 100644
--- a/docs/user/guide/config.md
+++ b/docs/user/guide/config.md
@@ -18,10 +18,6 @@ A minimal configuration is a list of plugin entries:
 ```yaml
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    models:
-      - deepseek-v4-flash
 
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
@@ -53,15 +49,14 @@ Cordis starts sibling entries concurrently. A plugin declares required services
 
 `dsh --profile <name>` composes the profile's bundle patch layers (its manifest's `dsh.profile.bundles` list, in order) over an empty root, then the profile's own `~/.dsh/profiles/<name>/cordis.patch.yml`, then each `--patch <path>` overlay, then CLI-flag patches. Later layers win per row.
 
-A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKey` and `baseURL`, so restate every key the row must retain.
+A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKeyEnv` and `baseURL`, so restate every key the row must retain.
 
 ## JavaScript values and environment variables
 
-The Cordis loader evaluates runtime expressions tagged with `!!js`. Keep API keys and other secrets in the gitignored `.env` file at the repository root, never in committed configuration.
+The Cordis loader evaluates runtime expressions tagged with `!!js` for non-secret runtime values. Bundled LLM adapters carry credential references such as `apiKeyEnv`; the value belongs in an environment layer or `$DSH_HOME/.credentials.yaml`, not Cordis configuration.
 
 ```yaml
 config:
-  apiKey: !!js process.env.DEEPSEEK_API_KEY
   cwd: !!js process.cwd()
 ```
 
diff --git a/docs/user/guide/config.zh.md b/docs/user/guide/config.zh.md
index 74e14e4e6e..ce965dfc67 100644
--- a/docs/user/guide/config.zh.md
+++ b/docs/user/guide/config.zh.md
@@ -18,10 +18,6 @@ Harness 使用 `cordis.yml` 描述 agent（智能体）加载哪些插件以及
 ```yaml
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    models:
-      - deepseek-v4-flash
 
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
@@ -53,15 +49,14 @@ Cordis 会并发启动同级配置项。插件通过 `inject` 声明必需服务
 
 `dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、每个 `--patch <path>` overlay，最后是 CLI（命令行界面）标志补丁。同一行以较后的层为准。
 
-补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKey` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
+补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKeyEnv` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
 
 ## JavaScript 值和环境变量
 
-Cordis loader 使用 `!!js` 标签读取运行时表达式。API key 等凭据应放在仓库根目录、已被 Git 忽略的 `.env` 中，不能提交到配置文件。
+Cordis loader 会求值以 `!!js` 标记的运行时表达式，用于非机密的运行时值。仓库内置的 LLM（大语言模型）适配器携带 `apiKeyEnv` 等凭据引用；对应的值应放在环境层或 `$DSH_HOME/.credentials.yaml`，而不是 Cordis 配置中。
 
 ```yaml
 config:
-  apiKey: !!js process.env.DEEPSEEK_API_KEY
   cwd: !!js process.cwd()
 ```
 
diff --git a/docs/user/guide/index.i18n.yaml b/docs/user/guide/index.i18n.yaml
index 137a9697c1..b722161724 100644
--- a/docs/user/guide/index.i18n.yaml
+++ b/docs/user/guide/index.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 docs/user/guide/index.md
-index.md: 4bb9f2e0056792a160877515f142eb36d4f680ac
-index.zh.md: 2792547a146b5ca6186bcb69c1c026744e80b326
+index.md: ede09506a996193fe5cf4ae6cd9b64d3529798a6
+index.zh.md: 5f72a6d3099d2d4721eccebae92eacfe72d33bce
diff --git a/docs/user/guide/index.md b/docs/user/guide/index.md
index 4bb9f2e005..ede09506a9 100644
--- a/docs/user/guide/index.md
+++ b/docs/user/guide/index.md
@@ -11,8 +11,6 @@ Harness implements every capability an AI agent needs—including LLM calls, too
 ```yaml
 # Select the LLM backend
 - name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
 
 # Select the one-shot application
 - id: cli-agent
diff --git a/docs/user/guide/index.zh.md b/docs/user/guide/index.zh.md
index 2792547a14..5f72a6d309 100644
--- a/docs/user/guide/index.zh.md
+++ b/docs/user/guide/index.zh.md
@@ -11,8 +11,6 @@ Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调
 ```yaml
 # Select the LLM backend
 - name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
 
 # Select the one-shot application
 - id: cli-agent
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 665eae8457..343ac902c1 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
-providers.md: 66b6cf25c61a252fbd10a85f8c79c246eeae8abe
-providers.zh.md: a2c33c90be971e09ab29e2355ca6a7ae6f947c39
+providers.md: 450b488f292e947a69e4315ea4d1ff74b74d390d
+providers.zh.md: 79f776b10eb4bd80663950f93555b353e320b7f1
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index 66b6cf25c6..450b488f29 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -31,7 +31,7 @@ That holds for providers that authenticate with an API key. The catalog also car
 
 **Let the endpoint report its models.** Expand **Model catalog** and choose **Fetch available models**: the interrogation asks the endpoint **the form currently shows** — including a base URL edited but not yet saved and a key typed but not yet stored — and offers what it reports as candidates to pick from. A route the installed catalog describes is answered from that catalog with no network call. Adopting a candidate only writes rows into the draft; nothing is stored until you save.
 
-Keys are write-only: the page only ever holds a redacted descriptor, never the literal secret. A key you enter is stored in `$DSH_HOME/.env`, and the profile records only the variable name that references it.
+Keys are write-only: the page only ever holds a redacted descriptor, never the literal secret. A key you enter is stored in `$DSH_HOME/.credentials.yaml`, and the profile records only the variable name that references it.
 
 ## settings.yaml for advanced configuration
 
@@ -89,9 +89,9 @@ Model ids are not lifecycle configuration. Requesting a model the route does not
 
 ## Credentials
 
-Prefer `apiKeyEnv`: it is a *reference* resolved per request, so no secret enters the configuration file. A literal `apiKey` is the escape hatch. Omitting both is what leaves a route unauthenticated, which for a catalog route means pi-ai's own environment discovery. A reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` rather than falling through to whatever unrelated key the environment happens to hold.
+Use `apiKeyEnv`: it is a *reference* resolved per request, so no secret enters the configuration file. Omitting it leaves a route unauthenticated, which for a catalog route means pi-ai's own environment discovery. A reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` rather than falling through to whatever unrelated key the environment happens to hold.
 
-References resolve from `$DSH_HOME/.env` — what the Models page's key fields write — and from the matching environment variable when no credential service is mounted. One credential serves every model on its route.
+Under `dsh`, references resolve from the inherited environment, the Models page's `$DSH_HOME/.credentials.yaml` store, the invoking directory's `.env`, then `$DSH_HOME/.env`. Without a credential service, a reference reads only the matching environment variable. One credential serves every model on its route.
 
 ## Point an agent at the new provider
 
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index a2c33c90be..79f776b10e 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -31,7 +31,7 @@ Harness 出厂就带 DeepSeek，同时挂着一个通用的多提供方适配器
 
 **让端点自己报模型。** 展开**模型目录**后点**获取可用模型**，会按你**当前表单里**的地址与密钥去问端点（地址改了但没保存、密钥刚输入还没存下，都算数），把它报告的模型列成候选让你勾选。内置目录里的路由直接由目录作答，不联网。采纳只是把行写进草稿，最终还是你点保存才落盘。
 
-密钥是只写的：页面拿到的永远是脱敏描述符，不是明文。写入的密钥存进 `$DSH_HOME/.env`，profile 里只记录引用它的变量名。
+密钥是只写的：页面拿到的永远是脱敏描述符，不是明文。写入的密钥存进 `$DSH_HOME/.credentials.yaml`，profile 里只记录引用它的变量名。
 
 ## settings.yaml：进阶配置
 
@@ -89,9 +89,9 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 ## 凭据
 
-优先用 `apiKeyEnv`——它是一个**引用**，每次请求时解析，密钥本身不进配置文件；`apiKey` 字面量是应急出口。两者都不给，才表示这个路由不带认证，对内置目录路由意味着交给 pi-ai 自己的环境发现。给了引用却解析不到，请求会以 `MISSING_CREDENTIAL` 失败，而不是退回去用环境里碰巧存在的某个不相干的 key 计费。
+使用 `apiKeyEnv`——它是一个**引用**，每次请求时解析，密钥本身不进配置文件。省略它会让路由不带认证，对内置目录路由意味着交给 pi-ai 自己的环境发现。给了引用却解析不到，请求会以 `MISSING_CREDENTIAL` 失败，而不是退回去用环境里碰巧存在的某个不相干的 key 计费。
 
-引用解析自 `$DSH_HOME/.env`（模型页的密钥输入框写的就是它），没有挂载凭据服务时则直接读同名环境变量。一份凭据供该路由上的所有模型使用。
+在 `dsh` 下，引用依次从继承环境、模型页的 `$DSH_HOME/.credentials.yaml` 存储、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析。未挂载凭据服务时，引用只读取同名环境变量。一份凭据供该路由上的所有模型使用。
 
 ## 让 agent 用上新提供方
 
diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml
index e284bdca7b..9ba9494c1c 100644
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -68,12 +68,10 @@
     - id: settings
       name: '@deepseek-ai/dsh-settings-local'
 
-    # Credential store: the live process environment over `$DSH_HOME/.env`
-    # (owner-only file, hot-reloaded). Adapters resolve their key references
-    # through it at each request, so no key is inlined in this file. The web
-    # Models page's key inputs write it through `credentials.set`; nothing hoists
-    # the document into the process environment, which would make every stored key
-    # read as an unrotatable ambient override.
+    # Credential sources: inherited environment over the managed
+    # `$DSH_HOME/.credentials.yaml`, with project and user `.env` fallbacks.
+    # Adapters resolve references per request; the Models page writes only the
+    # managed document, which is never materialized into the process environment.
     - id: credentials
       name: '@deepseek-ai/dsh-credentials-local'
 
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index 6c4c0e6aa0..edce8ce144 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/client/ui-models/README.md
-README.md: 80ae642ec9d6f91c78af041dda0b201959309577
-README.zh.md: 4236c8fec4f6d5e51363095d790944af9c08092a
+README.md: 06c60b8bf6e16f3aeab422b12851cf7d39b13ab6
+README.zh.md: 5ff458820a5da225a0ebd05e91f3e55a8cb764b8
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index 80ae642ec9..06c60b8bf6 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -4,11 +4,11 @@ English | [中文](README.zh.md)
 
 Models settings plugin: the provider configuration page and official-DeepSeek conditional onboarding step. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time, without presenting route liveness as provider status.
 
-Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a literal key or referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), `reasoningEffort` (deepseek) or `reasoning` (pi-ai), and each adapter's model catalog. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action.
+Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint), `reasoningEffort` (deepseek) or `reasoning` (pi-ai), and each adapter's model catalog. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action.
 
-The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured literal `apiKey` secret sidecar or configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
+The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
 
-Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, the same shape the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. A typed API key is judged on its own field the same way: after trimming, it must be non-empty and every character must be printable ASCII (`[\x21-\x7E]`), which is exactly what an HTTP header value can carry — the twin of `normalizeApiKey` in `@deepseek-ai/dsh-llm`, mirrored here because the source-plane split forbids importing it. A value shaped like a pasted `NAME=value` environment line or wrapped in matching quotes is refused as the same format failure; that paste-shape heuristic runs only in the browser, since a false positive in a resolver would leave the environment refusing the key as well. A field holding only whitespace fails rather than being silently dropped, while an empty field is not a failure at all: it means keep the stored key on an editor card, and authenticate some other way on a create card. A refused key blocks both the write and the endpoint interrogation, so the page never spends a round trip to be told what the field already says. Each settings write carries the card's current `revision`, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict`; after settings commit, the card adopts the returned redacted user subtree and revision before storing the credential, which makes a failed credential stage retry only that stage. Deletion removes a configured, writable credential only when the profile names the page's derived `<ROUTE>_API_KEY` target, then unsets the profile; both operations are idempotent, and a partial failure remains in the identified confirmation dialog for retry. Environment credentials, custom references, and credentials whose target cannot be identified remain untouched. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
+Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted provider row. The page only ever holds the REDACTED descriptor, so it mutates the fields it can see rather than rebuilding a section. DeepSeek's `models` is one replace-by-value array: the editor shows inherited effective rows until the first model edit materializes the complete array in the user layer, while reset unsets that override. A row carries the model id and display name; its context window and output cap sit behind the row's own disclosure, the same shape the pi-ai provider form uses. Either capacity is typed as a count with an optional decimal `K` or `M` suffix (`256K`, `1M`; `1M` is 1000K) and stored as the plain count, spelled back in the shortest form that round-trips. Empty ids, duplicate ids, empty explicit names, and unreadable, non-positive, or fractional capacities fail before any write. A typed API key is judged on its own field the same way: after trimming, it must be non-empty and every character must be printable ASCII (`[\x21-\x7E]`), which is exactly what an HTTP header value can carry — the twin of `normalizeApiKey` in `@deepseek-ai/dsh-llm`, mirrored here because the source-plane split forbids importing it. A value shaped like a pasted `NAME=value` environment line or wrapped in matching quotes is refused as the same format failure; that paste-shape heuristic runs only in the browser, since a false positive in a resolver would leave the environment refusing the key as well. A field holding only whitespace fails rather than being silently dropped, while an empty field is not a failure at all: it means keep the stored key on an editor card, and authenticate some other way on a create card. A refused key blocks both the write and the endpoint interrogation, so the page never spends a round trip to be told what the field already says. Each settings write carries the card's current `revision`, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict`; after settings commit, the card adopts the returned redacted user subtree and revision before storing the credential, which makes a failed credential stage retry only that stage. Deletion removes a configured, writable credential only when the profile names the page's derived `<ROUTE>_API_KEY` target, then unsets the profile; both operations are idempotent, and a partial failure remains in the identified confirmation dialog for retry. Environment credentials, custom references, and credentials whose target cannot be identified remain untouched. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
 
 ## Model list and endpoint interrogation
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index 4236c8fec4..5ff458820a 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -4,11 +4,11 @@
 
 模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。
 
-行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可以询问提供方它服务什么。只有确认字面密钥或引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），另有 `reasoningEffort`（deepseek）或 `reasoning`（pi-ai），以及各适配器自己的模型目录。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可以询问提供方它服务什么。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），另有 `reasoningEffort`（deepseek）或 `reasoning`（pi-ai），以及各适配器自己的模型目录。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。
 
-前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
+前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。凭据引用已配置时，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
-每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，与 pi-ai 提供方表单采用的形态相同。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。键入的 API 密钥同样在它自己的字段上被判定：trim 之后必须非空，且每个字符都是可打印 ASCII（`[\x21-\x7E]`）——这正是 HTTP 标头值所能承载的范围，是 `@deepseek-ai/dsh-llm` 中 `normalizeApiKey` 的孪生体，因源码平面分割禁止直接引入而在此镜像。形如整行粘贴的 `NAME=value` 环境变量或首尾成对引号包裹的值，会以同一条格式失败被拒绝；该粘贴形状启发式只在浏览器中运行，因为 resolver 中的一次误判会连带让环境变量这条路也拒绝该密钥。只含空白的输入框会失败而不是被静默丢弃；留空则完全不是失败：在编辑卡片上意味着保持已存储的密钥，在新建卡片上则意味着以其他方式鉴权。被拒绝的密钥会同时拦截写入与端点探测，因此页面不会白花一次往返去换取字段上已经写明的答案。每次 settings 写入都携带卡片当前的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝；settings 提交成功后，卡片会在存储凭据前采用响应返回的脱敏用户子树与 revision，因此凭据阶段失败时，重试只会重复该阶段。删除操作只会在 profile 指向页面派生的 `<ROUTE>_API_KEY` 目标时清除已配置且可写的凭据，随后取消设置 profile；两项操作都具备幂等性，部分失败会停留在点名目标的确认对话框中供重试。环境凭据、自定义引用和无法识别目标的凭据保持不变。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
+每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它只修改自己看得见的字段，而不重建分节。DeepSeek 的 `models` 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，与 pi-ai 提供方表单采用的形态相同。两项容量都按数值键入，可带十进制的 `K` 或 `M` 后缀（`256K`、`1M`；`1M` 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。键入的 API 密钥同样在它自己的字段上被判定：trim 之后必须非空，且每个字符都是可打印 ASCII（`[\x21-\x7E]`）——这正是 HTTP 标头值所能承载的范围，是 `@deepseek-ai/dsh-llm` 中 `normalizeApiKey` 的孪生体，因源码平面分割禁止直接引入而在此镜像。形如整行粘贴的 `NAME=value` 环境变量或首尾成对引号包裹的值，会以同一条格式失败被拒绝；该粘贴形状启发式只在浏览器中运行，因为 resolver 中的一次误判会连带让环境变量这条路也拒绝该密钥。只含空白的输入框会失败而不是被静默丢弃；留空则完全不是失败：在编辑卡片上意味着保持已存储的密钥，在新建卡片上则意味着以其他方式鉴权。被拒绝的密钥会同时拦截写入与端点探测，因此页面不会白花一次往返去换取字段上已经写明的答案。每次 settings 写入都携带卡片当前的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝；settings 提交成功后，卡片会在存储凭据前采用响应返回的脱敏用户子树与 revision，因此凭据阶段失败时，重试只会重复该阶段。删除操作只会在 profile 指向页面派生的 `<ROUTE>_API_KEY` 目标时清除已配置且可写的凭据，随后取消设置 profile；两项操作都具备幂等性，部分失败会停留在点名目标的确认对话框中供重试。环境凭据、自定义引用和无法识别目标的凭据保持不变。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
 
 ## 模型列表与端点询问
 
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index 0f4d11b397..07a3efd5c3 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-local/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/credentials/credentials-local/README.md
-README.md: 2841440a853ea6a7859cb72de38d75e2bc5a821c
-README.zh.md: accd20154106845c911f3ebe46ae4c61e615caca
+README.md: 8e95a890a8e38172cf8984653a01c59570f0061a
+README.zh.md: 04ad07ae4e703ab0416d1d8f1bb6a6ff90adf337
diff --git a/packages/credentials/credentials-local/README.md b/packages/credentials/credentials-local/README.md
index 2841440a85..8e95a890a8 100644
--- a/packages/credentials/credentials-local/README.md
+++ b/packages/credentials/credentials-local/README.md
@@ -13,7 +13,7 @@ File-backed [credentials](../credentials/README.md) provider: four layers, one h
 
 The launching environment wins because a per-run override (`DEEPSEEK_API_KEY=… dsh`, a CI secret, a container `-e`) is operator intent for this run — and because it cannot be edited from inside, it must be *visibly* read-only: `describe()` reports `source: 'env', writable: false`, and `set`/`unset` reject instead of writing a change the reader would never see.
 
-Everything below it loses to the managed store, so a key written by the web page or TUI takes effect immediately even when an older key sits in a `.env`. Those two layers still resolve when nothing is stored, and `describe()` names them `project-env` or `user-env` with `writable: true` — storing a key replaces them as the effective source.
+Everything below it loses to the managed store, so a key written by the Models page takes effect immediately even when an older key sits in a `.env`. Those two layers still resolve when nothing is stored, and `describe()` names them `project-env` or `user-env` with `writable: true` — storing a key replaces them as the effective source.
 
 Under the product CLI, resolution reads the launcher's frozen [environment snapshot](../../util/environment/README.md) rather than `process.env`: only the snapshot can say whether a value came from the launching shell or from a file. A composition the product CLI did not boot has the inherited environment as its only layer, which keeps embedders on the semantics they already had.
 
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index accd201541..04ad07ae4e 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -13,7 +13,7 @@
 
 启动环境优先，因为按次覆盖（`DEEPSEEK_API_KEY=… dsh`、CI 机密、容器 `-e`）代表本次运行的操作者意图——而它无法从进程内部修改，就必须*可见地*只读：`describe()` 报告 `source: 'env', writable: false`，`set`/`unset` 直接拒绝，而不是写下一个读取方永远看不到的变更。
 
-它之下的一切都输给受管存储，因此 Web 页面或 TUI 写入的密钥会立即生效，即使某个 `.env` 里还留着更旧的密钥。没有存储任何东西时这两层仍会解析，`describe()` 会把来源报告为 `project-env` 或 `user-env` 且 `writable: true`——存入一个密钥就会取代它们成为生效来源。
+它之下的一切都输给受管存储，因此 Models 页写入的密钥会立即生效，即使某个 `.env` 里还留着更旧的密钥。没有存储任何东西时这两层仍会解析，`describe()` 会把来源报告为 `project-env` 或 `user-env` 且 `writable: true`——存入一个密钥就会取代它们成为生效来源。
 
 在产品 CLI（命令行界面）下，解析读取的是启动器冻结的[环境快照](../../util/environment/README.md)而不是 `process.env`：只有快照才说得清某个值来自启动 shell 还是来自某个文件。并非由产品 CLI 启动的组合只有继承环境这一层，这让嵌入方保持它们原有的语义。
 
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index ea77458d12..e781c10f3e 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -13,13 +13,12 @@
  * secret, or a container `-e` is this run's explicit intent; it cannot be
  * edited from inside, so it must be *visibly* read-only rather than silently
  * shadow writes. Everything below it loses to the managed store, so a key the
- * web page or TUI writes takes effect immediately even when an older key sits
- * in the user's `.env`.
+ * Models page writes takes effect immediately even when an older key sits in
+ * the user's `.env`.
  *
  * The invoking project may supply a key, because the product trusts the
  * project it is launched in. It ranks below the managed store, so a key stored
- * through the web page or TUI is never displaced by one a checkout happens to
- * carry.
+ * through the Models page is never displaced by one a checkout happens to carry.
  *
  * The file is the provider-managed writable source: every write re-reads the
  * document under a cross-process writer lock before patching only its own key
diff --git a/packages/credentials/credentials/README.i18n.yaml b/packages/credentials/credentials/README.i18n.yaml
index 10fe5f0ffe..beeeef0ffd 100644
--- a/packages/credentials/credentials/README.i18n.yaml
+++ b/packages/credentials/credentials/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/credentials/credentials/README.md
-README.md: 1c18c4762360ad081227b7097cd82ddab4fcdefc
-README.zh.md: 751fb7c1e8326cef91b925c5f8b9f40d92e1bba6
+README.md: 95ef76d145727340d8135bf1d48babd6d8adb882
+README.zh.md: b3404858025d4ec53a76548c78c1808d2c858844
diff --git a/packages/credentials/credentials/README.md b/packages/credentials/credentials/README.md
index 1c18c47623..95ef76d145 100644
--- a/packages/credentials/credentials/README.md
+++ b/packages/credentials/credentials/README.md
@@ -31,7 +31,7 @@ The shadowing rule on `set`/`unset` is deliberate fail-loud: when a read-only so
 
 ## Providers
 
-[`dsh-credentials-local`](../credentials-local/README.md) layers the live process environment over a `$DSH_HOME/.env` file. The seam shape leaves room for keyring-, helper-command-, and KMS-backed providers; a remote settings provider never needs to carry secrets.
+[`dsh-credentials-local`](../credentials-local/README.md) layers the inherited process environment over its managed `$DSH_HOME/.credentials.yaml` document, with the launcher's project and user `.env` layers as fallbacks. The seam shape leaves room for keyring-, helper-command-, and KMS-backed providers; a remote settings provider never needs to carry secrets.
 
 ## Model Experience
 
diff --git a/packages/credentials/credentials/README.zh.md b/packages/credentials/credentials/README.zh.md
index 751fb7c1e8..b340485802 100644
--- a/packages/credentials/credentials/README.zh.md
+++ b/packages/credentials/credentials/README.zh.md
@@ -31,7 +31,7 @@ await ctx.credentials.unset(ref)                         // no-op when absent; s
 
 ## Providers
 
-[`dsh-credentials-local`](../credentials-local/README.md) 把活跃进程环境叠加在 `$DSH_HOME/.env` 文件之上。seam 形状为 keyring、辅助命令、KMS 后端的 provider 留好了位置；远端 settings provider 永远不必携带机密。
+[`dsh-credentials-local`](../credentials-local/README.md) 把继承的进程环境叠加在其受管 `$DSH_HOME/.credentials.yaml` 文档之上，并以启动器的项目和用户 `.env` 层作为后备。seam 形状为 keyring、辅助命令、KMS 后端的 provider 留好了位置；远端 settings provider 永远不必携带机密。
 
 ## Model Experience
 
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index bd322be07f..8b563b72b0 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: 0dcf15d6caf365a1f8e75088cb363eaa6560a6ec
-README.zh.md: 79be5d320c0f4411f7cf8a0bd72c887048929dcb
+README.md: 141a1a6250a69982564a9277e2cc97d8009d30e3
+README.zh.md: d2312bd2f4716500d8458b7806f6479e2e411937
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index 0dcf15d6ca..141a1a6250 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -8,7 +8,7 @@ The package root exposes the Cordis plugin contract, `PiAiAdapter`, and `support
 
 ## Config
 
-Configure credentials, the model catalog, and deployment-specific transport settings per provider, keyed by the provider route itself. Prefer `apiKeyEnv` — a credential *reference* resolved per request — over a literal `apiKey`, so no secret enters this file. Omitting **both** is what leaves the route unauthenticated, which for an installed catalog route means pi-ai's provider-native ambient discovery; a configured reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` instead, because falling through would authenticate with whatever unrelated key the environment happens to hold. One credential serves every model on its route.
+Configure credentials, the model catalog, and deployment-specific transport settings per provider, keyed by the provider route itself. `apiKeyEnv` is a credential *reference* resolved per request, so no secret enters this file. Omitting it leaves the route unauthenticated, which for an installed catalog route means pi-ai's provider-native ambient discovery; a configured reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` instead, because falling through would authenticate with whatever unrelated key the environment happens to hold. One credential serves every model on its route.
 
 ```yaml
 - id: llm
@@ -67,7 +67,7 @@ Resolution still fails loud, naming the offending route and model, when a route
 
 The adapter reads its profiles through a thunk **once per operation** instead of freezing them at construction. The plugin registers the `llm-pi-ai` namespace on the optional `ctx.settings` seam with this same `Config` schema and its `cordis.yml` entry as the composition `base`, and because `providers` is a dict, the base and the user's `llm-pi-ai:` settings section merge **per provider**: a user can add a route, override one field of a composition route, or point a route at another proxy, all effective on the next request with no restart. Without a mounted settings service the entry config alone drives the adapter, unchanged.
 
-Credentials resolve per stream call: a non-empty literal `apiKey` wins, then `apiKeyEnv` through the optional `ctx.credentials` seam (`$DSH_HOME/.env` under the live environment; exactly that variable without a mounted seam). A profile naming no credential at all — and only that case — defers to pi-ai's ambient discovery. Every key is trimmed and format-checked before use — a literal `apiKey` when profiles resolve (plugin load, or the next settings snapshot), a value `apiKeyEnv` resolves at request time — so a value no HTTP header can carry is refused there instead of surfacing as an opaque `fetch` `TypeError`; the request-time refusal throws `LlmError('INVALID_CREDENTIAL')` naming the failing route and credential reference but never any part of the key. The route set and each route's captured retry policy are the registration-level facts: when either changes, the plugin replaces its registration atomically (same adapter instance, candidate set validated first), so a route another adapter already owns leaves the previous routes serving and reverting to a working configuration re-applies. Provider key order never counts as a change. A section this adapter could not serve is refused where it is written — the registered `validate` resolves the whole profile set, so `ctx.settings.mutate` rejects with the resolver's own error (the wire surface reports it as `settings-rejected`) and nothing is stored. A stored section that becomes unserviceable some other way — an external edit of `settings.yaml` — keeps the namespace's last good value at the settings seam and warns. The entry config itself still fails plugin load, and a route the llm registry refuses (one another adapter family already owns) is logged while the previously registered routes keep serving.
+Credentials resolve per stream call through `apiKeyEnv` and the optional `ctx.credentials` seam; without that seam, the adapter reads exactly the referenced environment variable. A profile naming no credential at all — and only that case — defers to pi-ai's ambient discovery. Every resolved key is trimmed and format-checked before use, so a value no HTTP header can carry is refused instead of surfacing as an opaque `fetch` `TypeError`; the refusal throws `LlmError('INVALID_CREDENTIAL')` naming the failing route and credential reference but never any part of the key. The route set and each route's captured retry policy are the registration-level facts: when either changes, the plugin replaces its registration atomically (same adapter instance, candidate set validated first), so a route another adapter already owns leaves the previous routes serving and reverting to a working configuration re-applies. Provider key order never counts as a change. A section this adapter could not serve is refused where it is written — the registered `validate` resolves the whole profile set, so `ctx.settings.mutate` rejects with the resolver's own error (the wire surface reports it as `settings-rejected`) and nothing is stored. A stored section that becomes unserviceable some other way — an external edit of `settings.yaml` — keeps the namespace's last good value at the settings seam and warns. The entry config itself still fails plugin load, and a route the llm registry refuses (one another adapter family already owns) is logged while the previously registered routes keep serving.
 
 The adapter exposes each configured route's models through `ctx.llm.listModels(provider)`. This is provider-neutral selector metadata read from the same pi-ai `Models` collection the request path uses, so discovery does not create a second model registry. `ctx.llm.resolveModelInfo(provider, model)` performs that exact descriptor lookup once and returns its identity, context window, configured output cap, and selectable thinking levels, keeping authoritative metadata on the route-owning adapter rather than its consumers. A model's **configured** `maxTokens` becomes the seam's `defaultMaxTokens`, so a request that names no output cap carries the one the deployment chose; a value inherited from the installed catalog is the model's output *capability* and never becomes a request default on its own.
 
@@ -75,7 +75,7 @@ A model that carries reasoning metadata exposes pi-ai's ordered `getSupportedThi
 
 A model **without** that metadata — every hand-declared one, and a catalog model pi-ai marks as non-reasoning — exposes no `reasoning` at all. pi-ai reports such a model as supporting the single level `off`, but `off` is translated to *omitting* the reasoning option, which is byte-for-byte the request that naming no effort already produces: selecting it could not disable anything, so a provider whose own default is to think would keep thinking with `off` shown as selected. Reporting the capability as unavailable leaves a surface offering the provider's default and nothing that misrepresents it. The profile `reasoning` value, including `off`, is the deployment default when configured; omitting it preserves the provider default. Per-request `GenerateOptions.reasoningEffort` takes precedence, and any explicit value absent from the exact model capability fails with `UNSUPPORTED_REASONING_EFFORT` before network I/O instead of being clamped. pi-ai's common stream options represent `off` by omitting `reasoning`.
 
-Supported profile fields are `apiKey`, `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `defaultContextWindow`, `defaultMaxTokens`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
+Supported profile fields are `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `defaultContextWindow`, `defaultMaxTokens`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
 
 The adapter forces pi-ai's SDK `maxRetries` to zero so one `stream()` call makes one provider request. The removed profile fields `maxRetries` and `maxRetryDelayMs` fail load instead of silently multiplying or hiding the separately composed agent-level retry budget. Idle expiry aborts the SDK's stable request signal and surfaces `TIMEOUT`; an earlier caller abort remains `ABORTED`.
 
@@ -85,7 +85,7 @@ The plugin offers `ctx.llm.registerModelDiscovery('llm-pi-ai', …)`, which answ
 
 A request naming a route the **installed catalog ships is answered from that catalog**, with no network call: pi-ai's registry is the authoritative list for its own providers, and it carries the context windows and output caps a listing endpoint would not disclose. Such a route needs no `baseURL` at all. Only a route the catalog does not describe — a gateway, a self-hosted server — is interrogated over the wire, and one that names no endpoint is told to set one or enter its models by hand.
 
-A draft carries the credential the user typed, if any; a route that already stored one shows a configuration surface only a redacted descriptor, so the interrogation supplies that route's own credential — resolved exactly as a request to it would, `apiKey` then `apiKeyEnv` — rather than going out unauthenticated and reporting the endpoint's 401 as a wrong key. A typed key wins, being the one under test. Resolution happens only on the path that reaches the network, so a catalog route answers without touching credentials at all. A supplied or stored probe key is trimmed and format-checked the same way, so a value no HTTP header can carry is refused immediately as `LlmError('INVALID_CREDENTIAL')` instead of reaching `fetch`, where it would surface as an opaque `ByteString` failure indistinguishable from an unreachable endpoint.
+A draft carries the credential the user typed, if any; a route that already stored one shows a configuration surface only a redacted descriptor, so the interrogation resolves that route's `apiKeyEnv` rather than going out unauthenticated and reporting the endpoint's 401 as a wrong key. A typed key wins, being the one under test. Resolution happens only on the path that reaches the network, so a catalog route answers without touching credentials at all. A supplied or stored probe key is trimmed and format-checked the same way, so a value no HTTP header can carry is refused immediately as `LlmError('INVALID_CREDENTIAL')` instead of reaching `fetch`, where it would surface as an opaque `ByteString` failure indistinguishable from an unreachable endpoint.
 
 Interrogation reads `openai-completions` and `openai-responses`, whose `GET /models` shape with bearer auth is the one a gateway, a self-hosted server, and the official endpoints all agree on. Azure is excluded despite its OpenAI lineage — it authenticates with an `api-key` header and requires an `api-version` query — and Codex uses OAuth; every other protocol answers `DISCOVERY_UNSUPPORTED` so the surface falls back to hand-entry instead of an authentication failure being reported as a provider with no models. The `baseURL` is treated as a prefix rather than a URL to resolve against, so a deployment path such as `https://gateway.example/openai/v1` keeps its segments.
 
@@ -155,7 +155,7 @@ Recorded response content appends to the next request and does not invalidate it
 - **`headers` can carry a credential the redactor never sees** — the profile's `headers` dict is plain strings, so `Authorization` or `api-key` set there is returned verbatim by a redacted `describe()` and rendered by any configuration UI. Store credentials as `apiKeyEnv` references; making the dict write-only is deferred with the rest of the [wire-boundary work](../llm/README.md#known-limitations-and-deferred-work).
 - **A route's catalog never refreshes itself** — the catalog is whatever `settings.yaml` says, so a model list is only as current as its last edit. Nothing here queries a provider for the models it serves; a route gains a model when someone writes one.
 - **One wire protocol per route** — `api` applies to the whole route, so a mixed-protocol catalog route (an OpenAI-style catalog spanning Responses and Chat Completions) cannot host a model of the other protocol, and adding a model such a route does not describe requires naming `api` and moving every model onto it. Splitting the provider across two route keys is the workaround.
-- **An unauthenticated route depends on its protocol** — naming no credential resolves the route as configured-but-keyless, but pi-ai's OpenAI-compatible implementation still requires an API key or an `Authorization` header, so a keyless local server needs a placeholder `apiKey` or an `Authorization` entry in `headers`.
+- **An unauthenticated route depends on its protocol** — naming no credential resolves the route as configured-but-keyless, but pi-ai's OpenAI-compatible implementation still requires an API key or an `Authorization` header, so a keyless local server needs a placeholder credential referenced by `apiKeyEnv` or an `Authorization` entry in `headers`.
 - **`GenerateOptions.stop` is unsupported** — pi-ai's common stream options cannot guarantee stop-sequence behavior across providers, so the adapter rejects the field.
 - **In-history `system` messages use pi-ai's common context conversion** — provider-specific placement follows pi-ai rather than a harness-owned wire override.
 - **Provider HTTP status is unavailable** — pi-ai error events do not expose a stable HTTP status across providers; failures expose only stable harness error codes.
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index 79be5d320c..d2312bd2f4 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -8,7 +8,7 @@
 
 ## 配置
 
-按提供方配置凭据、模型 catalog 与部署特定传输设置，并以提供方路由本身为键。优先使用 `apiKeyEnv`——按请求解析的凭据*引用*——而非字面 `apiKey`，让机密不进入该文件。**两者**都省略，才会让该路由处于未认证状态；对已安装 catalog 路由而言，这意味着交给 pi-ai 的提供方原生环境发现。已配置却解析不出任何值的引用则相反，会让请求以 `MISSING_CREDENTIAL` 失败，因为放行下去就会用环境里恰好持有的某个无关密钥完成认证。一条凭据服务该路由下的全部模型。
+按提供方配置凭据、模型 catalog 与部署特定传输设置，并以提供方路由本身为键。`apiKeyEnv` 是按请求解析的凭据*引用*，因此机密不进入该文件。省略它会让该路由处于未认证状态；对已安装 catalog 路由而言，这意味着交给 pi-ai 的提供方原生环境发现。已配置却解析不出任何值的引用则相反，会让请求以 `MISSING_CREDENTIAL` 失败，因为放行下去就会用环境里恰好持有的某个无关密钥完成认证。一条凭据服务该路由下的全部模型。
 
 ```yaml
 - id: llm
@@ -67,7 +67,7 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 适配器经由一个 thunk **每操作读取一次** profile，而非在构造期冻结。插件在可选的 `ctx.settings` seam 上用同一份 `Config` schema 注册 `llm-pi-ai` namespace，并以其 `cordis.yml` 条目为组合 `base`；由于 `providers` 是字典，base 与用户的 `llm-pi-ai:` settings 分节**按提供方**合并：用户可以新增路由、覆盖组合路由的单个字段，或把路由指向另一个 proxy，全部在下一次请求生效，无需重启。未挂载 settings 服务时，仅由 entry 配置驱动适配器，行为不变。
 
-凭据按每次 stream 调用解析：非空的字面 `apiKey` 优先，其次经可选的 `ctx.credentials` seam 解析 `apiKeyEnv`（活跃环境之下的 `$DSH_HOME/.env`；未挂载 seam 时恰好读取该环境变量）。只有完全没有点名任何凭据的 profile——仅限这一种情况——才交给 pi-ai 的环境发现。每个密钥在使用前都会被去除首尾空白并校验格式——字面 `apiKey` 在 profile 解析时（插件加载，或下一次 settings 快照）校验，`apiKeyEnv` 解析出的值则在请求时校验——因此 HTTP 标头无法承载的值会在这一步被拒绝，而不是以语义不明的 `fetch` `TypeError` 形式浮现；请求时的拒绝会抛出 `LlmError('INVALID_CREDENTIAL')`，点名失败的路由与凭据引用，但绝不透露密钥的任何部分。路由集合与每条路由捕获的重试策略是注册级事实：两者任一变化时，插件都会原子地替换自己的注册（同一适配器实例，候选集合先经校验），因此某条路由若已被另一适配器占有，先前的路由会继续服务，而改回可用配置时注册会重新生效。提供方键的顺序绝不算作变化。本适配器无法服务的分节会在写入处被拒——注册的 `validate` 会解析整份 profile 集合，因此 `ctx.settings.mutate` 以 resolver 自身的错误拒绝（协议面将其报为 `settings-rejected`），什么都不会存储。已存储分节若因其他途径变得不可服务——比如外部编辑了 `settings.yaml`——则由 settings seam 保留该 namespace 最后可用的值并告警。entry 配置本身仍会使插件加载失败；而 llm 注册表拒绝的路由（已被另一适配器族占有的那种）会被记录下来，先前注册的路由继续服务。
+凭据在每次 stream 调用时通过 `apiKeyEnv` 与可选的 `ctx.credentials` seam 解析；未挂载该 seam 时，适配器只读取该引用指向的环境变量。只有完全没有点名任何凭据的 profile——仅限这一种情况——才交给 pi-ai 的环境发现。每个解析出的密钥都会在使用前去除首尾空白并校验格式，因此 HTTP 标头无法承载的值会被拒绝，而不是以语义不明的 `fetch` `TypeError` 形式浮现；这种拒绝会抛出 `LlmError('INVALID_CREDENTIAL')`，点名失败的路由与凭据引用，但绝不透露密钥的任何部分。路由集合与每条路由捕获的重试策略是注册级事实：两者任一变化时，插件都会原子地替换自己的注册（同一适配器实例，候选集合先经校验），因此某条路由若已被另一适配器占有，先前的路由会继续服务，而改回可用配置时注册会重新生效。提供方键的顺序绝不算作变化。本适配器无法服务的分节会在写入处被拒——注册的 `validate` 会解析整份 profile 集合，因此 `ctx.settings.mutate` 以 resolver 自身的错误拒绝（协议面将其报为 `settings-rejected`），什么都不会存储。已存储分节若因其他途径变得不可服务——比如外部编辑了 `settings.yaml`——则由 settings seam 保留该 namespace 最后可用的值并告警。entry 配置本身仍会使插件加载失败；而 llm 注册表拒绝的路由（已被另一适配器族占有的那种）会被记录下来，先前注册的路由继续服务。
 
 适配器通过 `ctx.llm.listModels(provider)` 公开每条已配置路由的模型。这是从请求路径所用的同一个 pi-ai `Models` 集合读取的提供方无关 selector 元数据，因此发现不会创建第二个模型注册表。`ctx.llm.resolveModelInfo(provider, model)` 会执行一次精确 descriptor 查找，并返回其身份、上下文窗口、已配置输出上限和可选思考级别，让权威元数据保留在拥有路由的适配器上，而非消费方。模型**已配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`，因此未点名输出上限的请求会携带部署选定的那一个；而从已安装 catalog 继承来的值是模型的输出**能力**，绝不会自行变成请求默认值。
 
@@ -75,7 +75,7 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 **没有**这份元数据的模型——每一个手工声明的模型，以及 pi-ai 标记为不具备推理能力的 catalog 模型——完全不公开 `reasoning`。pi-ai 会把这类模型报告为只支持 `off` 一档，但 `off` 会被翻译成*省略* reasoning 选项，而那与「不点名任何档位」产出的请求逐字节相同：选它关不掉任何东西，于是自身默认就在思考的提供方，会在界面显示 `off` 被选中的同时继续思考。把该能力报告为不可用，界面就只剩提供方默认这一项，不会再出现自相矛盾的控件。配置 profile 的 `reasoning` 值（包括 `off`）在存在时是部署默认值；省略它会保留提供方默认值。每次请求的 `GenerateOptions.reasoningEffort` 优先；任何未出现在确切模型能力中的显式值都会在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败，而不会被自动调整。pi-ai 的通用流选项通过省略 `reasoning` 表示 `off`。
 
-受支持的 profile 字段是 `apiKey`、`apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`defaultContextWindow`、`defaultMaxTokens`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs` 和 `retryPolicy`。每个 profile 的可选重试策略都会与该提供方路由一同捕获；省略时使用有界的常规默认值。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。若已配置标头中有同名项，则以 Harness 应用归因为准。
+受支持的 profile 字段是 `apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`defaultContextWindow`、`defaultMaxTokens`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs` 和 `retryPolicy`。每个 profile 的可选重试策略都会与该提供方路由一同捕获；省略时使用有界的常规默认值。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。若已配置标头中有同名项，则以 Harness 应用归因为准。
 
 适配器强制 pi-ai SDK `maxRetries` 为零，因此一次 `stream()` 调用只会发起一次提供方请求。已移除 profile 字段 `maxRetries` 和 `maxRetryDelayMs` 会使加载失败，而不是静默倍增或隐藏单独组合的 agent（智能体）级重试预算。空闲超时会 abort SDK 的稳定请求信号，并以 `TIMEOUT` 呈现；较早的调用方 abort 仍为 `ABORTED`。
 
@@ -85,7 +85,7 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 点名了**已安装 catalog 所提供路由**的请求，直接由该 catalog 作答，完全不联网：pi-ai 的注册表才是它自家提供方的权威列表，且携带列表端点不会公布的上下文窗口与输出上限。这类路由根本不需要 `baseURL`。只有 catalog 未描述的路由——网关、自建服务——才会经协议层询问；若它也没给端点，则会被告知去设置一个或手工填写模型。
 
-草稿携带的是用户当下键入的凭据（如果有）；已经存好凭据的路由，在配置界面上只呈现一个脱敏描述符，因此询问会自行取用该路由的凭据——解析方式与向它发请求时完全一致，先 `apiKey` 后 `apiKeyEnv`——而不是不带认证发出去、再把端点的 401 报成密钥不对。键入的密钥优先，因为那正是被测试的那一把。解析只发生在真正要联网的路径上，因此 catalog 路由作答时完全不会触碰凭据。用户提供或已存储的探测密钥也会经过同样的去除空白与格式校验：HTTP 标头无法承载的值会被立即以 `LlmError('INVALID_CREDENTIAL')` 拒绝，而不会传到 `fetch`——否则会呈现为一个和端点不可达难以区分的、语义不明的 `ByteString` 失败。
+草稿携带的是用户当下键入的凭据（如果有）；已经存好凭据的路由，在配置界面上只呈现一个脱敏描述符，因此询问会解析该路由的 `apiKeyEnv`，而不是不带认证发出去、再把端点的 401 报成密钥不对。键入的密钥优先，因为那正是被测试的那一把。解析只发生在真正要联网的路径上，因此 catalog 路由作答时完全不会触碰凭据。用户提供或已存储的探测密钥也会经过同样的去除空白与格式校验：HTTP 标头无法承载的值会被立即以 `LlmError('INVALID_CREDENTIAL')` 拒绝，而不会传到 `fetch`——否则会呈现为一个和端点不可达难以区分的、语义不明的 `ByteString` 失败。
 
 询问只读 `openai-completions` 与 `openai-responses`，它们「`GET /models` + bearer 认证」的形状是网关、自建服务与官方端点三方一致认可的那一种。Azure 尽管出身 OpenAI 也被排除——它用 `api-key` 标头认证并要求 `api-version` 查询参数——Codex 则走 OAuth；其余协议一律以 `DISCOVERY_UNSUPPORTED` 回答，让界面回退到手工填写，而不是把认证失败报成一个没有模型的提供方。`baseURL` 按前缀而非待解析 URL 处理，因此 `https://gateway.example/openai/v1` 这类部署路径会保留其路径段。
 
@@ -155,7 +155,7 @@ pi-ai 事件会变为 harness 推理、文本、工具调用、usage 与 finish
 - **`headers` 可能承载一条脱敏器看不见的凭据**：profile 的 `headers` 是纯字符串字典，因此设在其中的 `Authorization` 或 `api-key` 会被脱敏后的 `describe()` 原样返回，并被任何配置 UI 渲染出来。请把凭据存为 `apiKeyEnv` 引用；把该字典整体改为只写与其余[协议边界工作](../llm/README.md#known-limitations-and-deferred-work)一并暂缓。
 - **路由的 catalog 不会自我刷新**：catalog 就是 `settings.yaml` 所写的内容，因此模型列表的新鲜度只到最近一次编辑为止。这里没有任何环节会去问提供方它服务哪些模型；路由要多一个模型，得有人写进去。
 - **每条路由只有一种协议格式**：`api` 作用于整条路由，因此混合协议的 catalog 路由（跨 Responses 与 Chat Completions 的 OpenAI 式 catalog）无法承载另一种协议的模型，向这类路由添加它未描述的模型必须点名 `api` 并把全部模型一起迁过去。把该提供方拆成两个路由键是变通办法。
-- **未认证路由取决于其协议**：不点名凭据会让路由解析为「已配置但无密钥」，但 pi-ai 的 OpenAI 兼容实现仍要求 API key 或 `Authorization` 标头，因此无鉴权的本地服务需要一个占位 `apiKey`，或在 `headers` 中给出 `Authorization` 条目。
+- **未认证路由取决于其协议**：不点名凭据会让路由解析为「已配置但无密钥」，但 pi-ai 的 OpenAI 兼容实现仍要求 API key 或 `Authorization` 标头，因此无鉴权的本地服务需要一个由 `apiKeyEnv` 引用的占位凭据，或在 `headers` 中给出 `Authorization` 条目。
 - **不支持 `GenerateOptions.stop`**：pi-ai 的通用流选项无法保证所有提供方都支持 stop sequence，因此适配器会拒绝该字段。
 - **历史中的 `system` 消息使用 pi-ai 通用上下文转换**：提供方特定位置由 pi-ai 决定，而非由 harness 拥有的协议覆盖决定。
 - **无法获取提供方 HTTP 状态**：pi-ai 错误事件不会在所有提供方上公开稳定 HTTP 状态；失败只公开稳定 harness 错误 code。
diff --git a/packages/llm/llm-retry/README.i18n.yaml b/packages/llm/llm-retry/README.i18n.yaml
index b1157f806f..65e0c911ed 100644
--- a/packages/llm/llm-retry/README.i18n.yaml
+++ b/packages/llm/llm-retry/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/llm/llm-retry/README.md
-README.md: 23b55a30989cc51d4dd9076b61b6595452b0abd0
-README.zh.md: 267ef12a87561fd8effef726a781e505225baf03
+README.md: e6e56ec44032d714393c6fcc1c42d7271017a294
+README.zh.md: b7ce8bee4acd2c4f7c88870745dff96ec5695435
diff --git a/packages/llm/llm-retry/README.md b/packages/llm/llm-retry/README.md
index 23b55a3098..e6e56ec440 100644
--- a/packages/llm/llm-retry/README.md
+++ b/packages/llm/llm-retry/README.md
@@ -15,7 +15,7 @@ The separately published `./invariant` companion checks that every retry record
 ```yaml
 - name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    apiKeyEnv: DEEPSEEK_API_KEY
     retryPolicy:
       mode: always
       backoff:
diff --git a/packages/llm/llm-retry/README.zh.md b/packages/llm/llm-retry/README.zh.md
index 267ef12a87..b7ce8bee4a 100644
--- a/packages/llm/llm-retry/README.zh.md
+++ b/packages/llm/llm-retry/README.zh.md
@@ -15,7 +15,7 @@
 ```yaml
 - name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    apiKeyEnv: DEEPSEEK_API_KEY
     retryPolicy:
       mode: always
       backoff:
diff --git a/packages/ui/app-boot/README.i18n.yaml b/packages/ui/app-boot/README.i18n.yaml
index 398ec6e923..1c15f51109 100644
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/ui/app-boot/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/app-boot/README.md
-README.md: cdd78047b6ad71148c6ebeba598b63b4ae4cfa7b
-README.zh.md: ee2b07884e68510e2b59b9f2c27053c263d15f1a
+README.md: 9c2f9a8dac6b164cb23260e743eb2cdf1f29d3aa
+README.zh.md: 8422a176e682a87d1e592d5140b719e628e7d8e7
diff --git a/packages/ui/app-boot/README.md b/packages/ui/app-boot/README.md
index cdd78047b6..9c2f9a8dac 100644
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -8,6 +8,7 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | Absolute config path; `snapshotMode === 'replay'` swaps a `cordis.yml`/`.yaml` basename for its sibling `cordis.snapshot.yml` |
 | `loadEnv(binName, dir?, warn?)` | Load the gitignored `.env` (Node `process.loadEnvFile`); absent file is fine, an unloadable one warns a single labelled line (default: stderr) |
+| `loadLayeredEnv(binName, cwd?, warn?)` | Build the product CLI's frozen inherited > project `.env` > user `.env` snapshot, reject bootstrap-only file variables, and materialize accepted file values without replacing inherited ones |
 | `installFailLoud(binName, proc?, release?)` | Turn an unhandled boot or later Loader rejection into one labelled stderr line + `exit(1)`; the optional `release` teardown is awaited between the two (bounded by `FAIL_LOUD_RELEASE_TIMEOUT_MS`) so a terminal-owning surface restores the terminal before exit; returns the uninstaller |
 | `FAIL_LOUD_RELEASE_TIMEOUT_MS` | How long `installFailLoud` waits for its `release` hook; a wedged disposer delays the fatal exit, never cancels it |
 | `assertEntriesLoaded(ctx, binName)` | Throw when a settled tree holds an enabled entry with no fiber, reporting every unresolved plugin name as a Cordis startup failure |
@@ -36,7 +37,7 @@ A profile is a directory under `$DSH_HOME/profiles/<name>` (the Harness home res
 
 User-level machine-local preferences also live in the Harness home:
 
-- **`.env`** — the credential store of [`dsh-credentials-local`](../../credentials/credentials-local/README.md), read by that provider alone. No surface hoists it into `process.env`: doing so would make every stored key look like a read-only launch override on the next run, blocking rotation from the Web settings page. The environment layers are the ambient one and the invoking directory's `.env` (loaded by the bin; `process.loadEnvFile` never overrides), and a composition without the credential provider keeps resolving keys from those alone.
+- **`.env`** — the product CLI's ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. `loadLayeredEnv` snapshots each value's source, rejects bootstrap-only file variables, and materializes accepted values into `process.env` for Loader expressions and third-party libraries. Managed credentials live separately in [`.credentials.yaml`](../../credentials/credentials-local/README.md); a credential left in either `.env` remains a lower-priority fallback.
 - **`cordis.patch.yml`** (home level) and **`profiles/<name>/cordis.patch.yml`** — the user patch layers, applied after every bundle layer (per-profile first, then the home-level file, which therefore outranks it): an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount. A patch naming an entry id absent from the composed tree is a stderr warning. An empty or comments-only file throws (it parses to nothing, not to a list); disable the layer with `[]`.
 
 Long-lived surfaces keep `cordis.patch.yml` live through `watchUserPatches`; one-shot runs read only the startup value. The watcher targets the exact path even when the file or immediate parent does not exist, serializes bursts, and recomposes the user patches inside the caller's layer order (bundle layers below, overlay/flag patches above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
@@ -53,5 +54,5 @@ No direct invalidation from `boot()`; a consumer that calls `addHarnessSourceSec
 
 - **Bare package specifiers depend on Loader internals** — production bins need Loader's optional native helper; an in-process caller without it must use resolvable relative/file specifiers or provide its own module-resolution hook.
 - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection.
-- **Environment loading is cwd-scoped and optional** — the helper loads one `.env` file and warns on failure; it does not search parents, merge profiles, or validate required variables.
+- **Environment discovery is launch-scoped** — `loadLayeredEnv` reads only the invocation directory and Harness home once; it does not search parents or follow a workspace selected later. `loadEnv` remains the one-directory helper for non-product bins.
 - **User patch layers are patch-shaped** — an id-targeted patch replaces the entry's whole `config` rather than deep-merging, so a profile override restates the bundle fields it keeps.
diff --git a/packages/ui/app-boot/README.zh.md b/packages/ui/app-boot/README.zh.md
index ee2b07884e..8422a176e6 100644
--- a/packages/ui/app-boot/README.zh.md
+++ b/packages/ui/app-boot/README.zh.md
@@ -8,6 +8,7 @@
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | 生成绝对配置路径；当 `snapshotMode === 'replay'` 时，把 basename 为 `cordis.yml`/`.yaml` 的文件替换为同级 `cordis.snapshot.yml` |
 | `loadEnv(binName, dir?, warn?)` | 加载已被 git 忽略的 `.env`（Node `process.loadEnvFile`）；文件不存在不影响启动，文件无法加载时输出一行带标签的警告（默认写入 stderr） |
+| `loadLayeredEnv(binName, cwd?, warn?)` | 构建产品 CLI（命令行界面）冻结的「继承环境 > 项目 `.env` > 用户 `.env`」快照，拒绝文件中的 bootstrap-only 变量，并在不替换继承值的前提下物化其余文件值 |
 | `installFailLoud(binName, proc?, release?)` | 将启动期或后续未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 `exit(1)`；两者之间会等待可选的 `release` 拆卸回调（以 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 为上限），使持有终端的界面能在退出前恢复终端；返回卸载函数 |
 | `FAIL_LOUD_RELEASE_TIMEOUT_MS` | `installFailLoud` 等待其 `release` 回调的时长；卡住的 disposer 只会延迟致命退出，而不会取消它 |
 | `assertEntriesLoaded(ctx, binName)` | 树结算后，如果其中存在已启用但没有 fiber 的条目，则抛出异常，并以 Cordis 启动故障的形式报告每个未解析插件的名称 |
@@ -36,7 +37,7 @@ profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`
 
 用户级的机器本地偏好同样位于 Harness home 中：
 
-- **`.env`**：[`dsh-credentials-local`](../../credentials/credentials-local/README.md) 的凭据存储，只由该 provider 读取。没有任何表层会把它提升进 `process.env`：那样做会让每个已存密钥在下次运行时看起来都像只读的启动时覆盖，从而阻断从 Web 设置页面轮换密钥。环境层次由环境中的值与调用目录的 `.env` 构成（由 bin 加载；`process.loadEnvFile` 从不覆盖已有值），没有凭据 provider 的组合仍然只从这两者解析密钥。
+- **`.env`**：产品 CLI 的普通环境层；调用目录的文件优先于 Harness home 的文件，两者都低于继承环境。`loadLayeredEnv` 记录每个值的来源，拒绝文件中的 bootstrap-only 变量，并把其余值物化进 `process.env`，供 Loader 表达式和第三方库使用。受管凭据另存于 [`.credentials.yaml`](../../credentials/credentials-local/README.md)；留在任一 `.env` 中的凭据仍是低优先级后备值。
 - **`cordis.patch.yml`**（home 级）与 **`profiles/<name>/cordis.patch.yml`**：用户 patch 层，应用在所有组合包层之后（先应用逐 profile 的文件，再应用 home 级文件，因此后者优先级更高）：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在组合后的树中，则输出一条 stderr 警告。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用该层，请使用 `[]`。
 
 长期运行的 surface 会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay／标志 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
@@ -53,5 +54,5 @@ profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`
 
 - **裸包 specifier 依赖 Loader 内部机制**：生产 bin 需要 Loader 的可选原生 helper；没有该 helper 的进程内调用方必须使用可解析的相对／file specifier，或提供自己的模块解析钩子。
 - **快照回放替换仅识别特定 basename**：只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
-- **环境加载局限于 cwd 且为可选操作**：helper 只加载一个 `.env` 文件，并在失败时发出警告；它不会搜索父目录、合并 profile 或验证必需变量。
+- **环境发现以启动为界**：`loadLayeredEnv` 只读取一次调用目录与 Harness home 中的 `.env`；它不搜索父目录，也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。
 - **用户 patch 层采用 patch 形式**：按 id 定位的 patch 会替换条目的整个 `config`，而不是深度合并，因此 profile 覆盖必须重述需要保留的组合包字段。

From ac154b2dfa1c174b062931a9ab57e8e3737a3b77 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:41:22 +0800
Subject: [PATCH 162/516] test(cli): cover Harness-home credential loading in
 built entry

Source-level environment and credential tests prove the individual loaders, but they do not prove that the published launcher runs them before Loader evaluates a shipped profile.

Start the built dsh binary with the shipped base bundle and a test-only LLM probe. Put the endpoint in $DSH_HOME/.env, put the bearer token only in $DSH_HOME/.credentials.yaml, remove inherited DeepSeek overrides, and assert the mock request received both without leaking the token. This covers launch order, profile composition, the adapter, and the credential seam without a real API.
---
 apps/cli/package.json           |  1 +
 apps/cli/tests/built-bin.e2e.ts | 91 ++++++++++++++++++++++++++++++++-
 pnpm-lock.yaml                  |  3 ++
 3 files changed, 93 insertions(+), 2 deletions(-)

diff --git a/apps/cli/package.json b/apps/cli/package.json
index 87677ce1f9..71b70b078d 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -39,6 +39,7 @@
     "@deepseek-ai/dsh-frontend-static": "workspace:^",
     "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
     "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-llm-mock-server": "workspace:^",
     "@deepseek-ai/dsh-loader-smoke": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index ede3d17134..22fe20883e 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
+import { startMockLlmServer } from '@deepseek-ai/dsh-llm-mock-server'
 import { execa } from 'execa'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
@@ -13,14 +14,21 @@ const invalidProvider = fileURLToPath(new URL('./fixtures/invalid-provider.cordi
 
 async function runBuiltBin(
   args: readonly string[] = [],
-  env: Record<string, string> = {},
+  env: Readonly<Record<string, string | undefined>> = {},
+  cwd?: string,
 ): Promise<{ stdout: string; code: number; stderr: string }> {
+  const childEnv = Object.fromEntries(
+    Object.entries({ ...process.env, ...env })
+      .filter((entry): entry is [string, string] => entry[1] !== undefined),
+  )
   const result = await execa(process.execPath, [dshBin, ...args], {
     input: '',
     timeout: 25_000,
     killSignal: 'SIGKILL',
     reject: false,
-    env,
+    env: childEnv,
+    extendEnv: false,
+    ...cwd === undefined ? {} : { cwd },
   })
   if (result.timedOut) {
     throw new Error(`dsh built bin did not exit within 25s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
@@ -127,6 +135,44 @@ function startProfileLifecycle(fixture: ProfileLifecycleFixture) {
   })
 }
 
+function createEnvironmentProbeProfile(home: string, project: string): void {
+  const pluginFile = join(project, 'environment-probe.mjs')
+  writeFileSync(pluginFile, [
+    "export const name = 'environment-probe'",
+    "export const inject = ['llm']",
+    'export function apply(ctx) {',
+    '  void ctx.loader.await().then(async () => {',
+    "    let text = ''",
+    '    for await (const chunk of ctx.llm.stream({',
+    "      provider: 'deepseek-official',",
+    "      model: 'deepseek-v4-flash',",
+    '      messages: [],',
+    '      maxTokens: 32,',
+    '    })) {',
+    "      if (chunk.type === 'text-delta') text += chunk.text",
+    '    }',
+    '    process.stdout.write(`${text}\\n`)',
+    "    process.kill(process.pid, 'SIGTERM')",
+    '  })',
+    '}',
+    '',
+  ].join('\n'))
+  const profileDir = join(home, 'profiles', 'environment-probe')
+  mkdirSync(profileDir, { recursive: true })
+  writeFileSync(join(profileDir, 'package.json'), JSON.stringify({
+    name: 'dsh-profile-environment-probe',
+    private: true,
+    dependencies: {},
+    dsh: { profile: { bundles: ['@deepseek-ai/dsh-base'] } },
+  }, undefined, 2))
+  writeFileSync(join(profileDir, 'cordis.patch.yml'), [
+    '- insert:',
+    '    - id: environment-probe',
+    `      name: ${pathToFileURL(pluginFile).href}`,
+    '',
+  ].join('\n'))
+}
+
 describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)', () => {
   it('requires --profile and rejects removed commands', async () => {
     const bare = await runBuiltBin()
@@ -156,6 +202,47 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     }
   }, 30_000)
 
+  it('uses the Harness-home environment and managed credential through the published entry', async () => {
+    const apiKey = 'built-home-layer-key'
+    const server = await startMockLlmServer({
+      sequence: ['success'],
+      apiKey,
+      successText: 'home environment reached the mock',
+    })
+    const home = mkdtempSync(join(tmpdir(), 'dsh-home-environment-'))
+    const project = mkdtempSync(join(tmpdir(), 'dsh-home-project-'))
+    writeFileSync(join(home, '.env'), `DEEPSEEK_BASE_URL=${server.baseURL}\n`)
+    writeFileSync(join(home, '.credentials.yaml'), `DEEPSEEK_API_KEY: ${apiKey}\n`, { mode: 0o600 })
+    createEnvironmentProbeProfile(home, project)
+    try {
+      const result = await runBuiltBin(
+        ['--profile', 'environment-probe'],
+        {
+          DSH_HOME: home,
+          DSH_TELEMETRY_DISABLED: '1',
+          DEEPSEEK_API_KEY: undefined,
+          DEEPSEEK_BASE_URL: undefined,
+        },
+        project,
+      )
+      expect(
+        result.code,
+        `${result.stderr}\nstdout:\n${result.stdout}\nmock requests: ${String(server.requests.length)}`,
+      ).toBe(0)
+      expect(result.stdout).toBe('home environment reached the mock')
+      expect(result.stdout).not.toContain(apiKey)
+      expect(result.stderr).not.toContain(apiKey)
+      expect(server.requests).toHaveLength(1)
+      expect(server.requests[0]?.path).toBe('/chat/completions')
+      expect(server.requests[0]?.headers.authorization).toBe(`Bearer ${apiKey}`)
+      expect(JSON.stringify(server.requests[0]?.body)).not.toContain(apiKey)
+    } finally {
+      await server.close()
+      rmSync(home, { recursive: true, force: true })
+      rmSync(project, { recursive: true, force: true })
+    }
+  }, 30_000)
+
   it('reports a patch-overlay boot failure without hanging', async () => {
     // The HMR main watcher's initial scan once refreshed the include
     // mid-initial-apply, deadlocking the failing apply's rollback against the
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c7c39a7522..4c4c100582 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -201,6 +201,9 @@ importers:
       '@deepseek-ai/dsh-host-webserver':
         specifier: workspace:^
         version: link:../../packages/host/webserver
+      '@deepseek-ai/dsh-llm-mock-server':
+        specifier: workspace:^
+        version: link:../../packages/support/llm-mock-server
       '@deepseek-ai/dsh-loader-smoke':
         specifier: workspace:^
         version: link:../../packages/support/loader-smoke

From 356453d6cbe2b0c29d7d37ab799b5296dd7c4b9a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 22:03:49 +0800
Subject: [PATCH 163/516] cleanup(config): remove literal credential
 compatibility residue

Adapter schemas now carry only credential references, but the Models join, onboarding readiness, shipped overlays, SDK scaffolding, fixtures, and active decision prose still treated a redacted literal apiKey as a supported compatibility state. That residue made an unsupported field look contractual and pinned Schemastery silent-dropping as behavior.

Delete those branches and examples, and let compositions and scaffolds use adapter-owned reference and environment resolution. Do not add a tombstone validator or change generic unknown-key behavior: literal adapter credentials have no migration contract to preserve.
---
 ...est-level-llm-config-credentials.i18n.yaml |  4 +--
 ...29-request-level-llm-config-credentials.md |  2 +-
 ...request-level-llm-config-credentials.zh.md |  2 +-
 ...undaries-and-atomic-registration.i18n.yaml |  4 +--
 ...tial-boundaries-and-atomic-registration.md |  4 +--
 ...l-boundaries-and-atomic-registration.zh.md |  4 +--
 ...4-configuration-source-ownership.i18n.yaml |  4 +--
 ...26-08-04-configuration-source-ownership.md |  1 -
 ...08-04-configuration-source-ownership.zh.md |  1 -
 ...-08-06-api-key-format-validation.i18n.yaml |  4 +--
 .../2026-08-06-api-key-format-validation.md   | 14 +++------
 ...2026-08-06-api-key-format-validation.zh.md | 14 +++------
 ...06-provider-credential-lifecycle.i18n.yaml |  4 +--
 ...026-08-06-provider-credential-lifecycle.md |  6 ++--
 ...-08-06-provider-credential-lifecycle.zh.md |  6 ++--
 ...seek-onboarding-credential-setup.i18n.yaml |  4 +--
 ...30-deepseek-onboarding-credential-setup.md |  4 +--
 ...deepseek-onboarding-credential-setup.zh.md |  4 +--
 examples/acp-agent/tests/fs-search.cordis.yml |  2 --
 examples/acp-agent/tests/pwsh.cordis.yml      |  2 --
 packages/bundle/web-app/cordis.patch.yml      |  5 ---
 .../ui-models/src/client/ModelsSection.tsx    | 14 ++++-----
 .../ui-models/src/client/ProviderEditor.tsx   | 17 +++++-----
 packages/client/ui-models/src/client/store.ts | 17 ----------
 .../ui-models/tests/components.spec.tsx       | 31 ++++++-------------
 .../tests/onboarding-dialog.spec.tsx          |  6 ++--
 .../client/ui-models/tests/readiness.spec.ts  |  8 -----
 packages/client/ui-models/tests/store.spec.ts | 27 +---------------
 .../examples/acp-demo/tests/load-path.e2e.ts  |  2 --
 .../llm/llm-deepseek/tests/adapter.spec.ts    |  3 +-
 .../llm-deepseek/tests/dynamic-config.spec.ts | 17 ----------
 packages/sdk/create-sdk/tests/create.spec.ts  |  2 +-
 .../helper/src/features/builtin/provider.ts   |  9 ++----
 packages/sdk/helper/tests/documents.spec.ts   | 12 +++----
 packages/sdk/helper/tests/project.spec.ts     |  3 +-
 packages/sdk/scripts/tests/scripts.spec.ts    |  2 +-
 .../telemetry/tests/consent-resolver.spec.ts  |  2 +-
 37 files changed, 78 insertions(+), 189 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
index 6a87258771..5524e0d54d 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.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 .agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
-2026-07-29-request-level-llm-config-credentials.md: 5359865d1ca0c6620f4af1fa82c2f7e5413e79d6
-2026-07-29-request-level-llm-config-credentials.zh.md: 90f7c9447978f9621d9d940a56fd341714e69001
+2026-07-29-request-level-llm-config-credentials.md: 238400ea41f25a716729d1721c113645c2c8ba72
+2026-07-29-request-level-llm-config-credentials.zh.md: b0d04d4303bf0ccf5ebc74af8c4a3e493f861d63
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
index 5359865d1c..238400ea41 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
@@ -14,7 +14,7 @@ The [settings seam](2026-07-28-user-settings-seam.md) shipped without a producti
 
 **Per-request resolution, not fiber rebuilds.** The adapters take an options thunk (and a per-stream credential resolver) instead of frozen construction facts, resolving once per operation — the Pi pattern, with its tested semantics: two requests straddling a change see two configurations, one request resolves exactly once, and an in-flight stream keeps the facts it started with. This deletes the entire swap machinery a rebuild design needs (`DUPLICATE_ADAPTER` ordering, `NO_ADAPTER` windows, a deferred-activation state machine) and makes a missing key a *request-time* actionable failure (`MISSING_CREDENTIAL` naming every entry point) while the route stays registered and the catalog stays browsable. The one registration-captured fact — the retry policy the `ctx.llm` registry snapshots at `registerAdapter` (plus pi-ai's route *set*) — re-registers the same adapter instance in one synchronous section when it changes.
 
-**Secrets are references, values live behind `ctx.credentials`.** Configuration (both planes) carries `apiKeyEnv: DEEPSEEK_API_KEY`; the three-package credential seam resolves it per operation. `credentials-local` layers the live process environment (read-only, wins — a launch-time override is operator intent and must be *visibly* read-only, so shadowed writes reject instead of appearing to succeed) over the provider-managed document (writable, wholesale snapshot replacement on reload so a deleted entry never lingers — the Claude Code additive-reapply lesson). That document was `$DSH_HOME/.env` in dotenv form; the [credentials document split](2026-08-04-credentials-yaml-and-user-environment-layer.md) later moved it to `$DSH_HOME/.credentials.yaml` and freed the old path to become the user's environment layer. Resolution order in the adapters is literal `apiKey` first (preserving the historical `config.apiKey ?? env` observable semantics), then the seam, then — only without a mounted seam — the raw environment variable.
+**Secrets are references, values live behind `ctx.credentials`.** Configuration (both planes) carries `apiKeyEnv: DEEPSEEK_API_KEY`; the three-package credential seam resolves it per operation. `credentials-local` layers the live process environment (read-only, wins — a launch-time override is operator intent and must be *visibly* read-only, so shadowed writes reject instead of appearing to succeed) over the provider-managed document (writable, wholesale snapshot replacement on reload so a deleted entry never lingers — the Claude Code additive-reapply lesson). That document was `$DSH_HOME/.env` in dotenv form; the [credentials document split](2026-08-04-credentials-yaml-and-user-environment-layer.md) later moved it to `$DSH_HOME/.credentials.yaml` and freed the old path to become the user's environment layer. Adapters resolve the reference through the seam, or — only without a mounted seam — through the environment layers.
 
 **Per-plugin namespaces, schema ≡ `Config`.** Each adapter registers its own namespace (`llm-deepseek`, `llm-pi-ai`) with its plugin `Config` schema and its `cordis.yml` entry as the composition `base` — a settings section is the same YAML shape as the entry config, and `resolveAdapterOptions`/`resolveProfiles` stay the one explicit resolve step for both. A live snapshot failing a beyond-schema bound keeps the last good facts (the seam's last-good philosophy extended one level up); the entry config itself still fails load. pi-ai's `providers` became a dict keyed by route so base and user layers merge per provider and the route set is structural; the array shape fails loud with migration directions, and an empty dict is the valid dormant posture — a composition ships the adapter bare and every route stays a user-plane decision.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
index 90f7c94479..b0d04d4303 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 **按请求解析，而非重建 fiber。**适配器改为接收一个 options thunk（外加按流调用的凭据解析器），不再持有冻结的构造期事实，每个操作解析一次——即 Pi 的模式，连同其经测试固定的语义：跨越一次变更的两个请求看到两份配置，一个请求恰好解析一次，进行中的流保持其起始事实。这删掉了重建式设计所需的整套切换机制（`DUPLICATE_ADAPTER` 顺序问题、`NO_ADAPTER` 窗口、延迟激活状态机），并把密钥缺失变成*请求时*可行动的失败（`MISSING_CREDENTIAL` 点名每个配置入口），同时路由保持注册、catalog 保持可浏览。唯一在注册期捕获的事实——`ctx.llm` 注册表在 `registerAdapter` 时快照的重试策略（外加 pi-ai 的路由*集合*）——在其变化时于一个同步区段内原地重新注册同一适配器实例。
 
-**机密是引用，值藏在 `ctx.credentials` 背后。**配置（两个面）携带 `apiKeyEnv: DEEPSEEK_API_KEY`；三包凭据 seam 按操作解析它。`credentials-local` 把活跃进程环境（只读、优先——启动时覆盖是操作者意图，必须*可见地*只读，因此被遮蔽的写入直接拒绝而不是表面成功）叠加在 provider 管理的文档之上（可写、重载时整体替换快照使删除的条目绝不滞留——来自 Claude Code 增量重放（additive reapply）的教训）。该文档当时是 dotenv 形式的 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，并让旧路径转为用户的环境层。适配器内的解析顺序为：字面 `apiKey` 优先（保留历史 `config.apiKey ?? env` 的可观察语义），然后是 seam，最后——仅在未挂载 seam 时——原始环境变量。
+**机密是引用，值藏在 `ctx.credentials` 背后。**配置（两个面）携带 `apiKeyEnv: DEEPSEEK_API_KEY`；三包凭据 seam 按操作解析它。`credentials-local` 把活跃进程环境（只读、优先——启动时覆盖是操作者意图，必须*可见地*只读，因此被遮蔽的写入直接拒绝而不是表面成功）叠加在 provider 管理的文档之上（可写、重载时整体替换快照使删除的条目绝不滞留——来自 Claude Code 增量重放（additive reapply）的教训）。该文档当时是 dotenv 形式的 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，并让旧路径转为用户的环境层。适配器通过 seam 解析该引用；仅在未挂载 seam 时，才通过各环境层解析。
 
 **按插件划分 namespace，schema ≡ `Config`。**每个适配器注册自己的 namespace（`llm-deepseek`、`llm-pi-ai`），schema 用其插件 `Config` schema，组合 `base` 用其 `cordis.yml` 条目——settings 分节与 entry 配置是同一种 YAML 形状，`resolveAdapterOptions`/`resolveProfiles` 对两者仍是唯一的显式 resolve 步骤。存活快照若违反 schema 之外的约束，则保留最后可用事实（seam 的最后可用值哲学向上延伸一层）；entry 配置本身仍会加载失败。pi-ai 的 `providers` 改为以路由为键的字典，base 层与用户层因此按提供方合并，路由集合也由结构直接表达；数组形状响亮失败并给出迁移指引，而空字典是合法的休眠姿态——组合可以裸挂该适配器，把每一条路由都留给用户面决定。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index db8945f8a2..4becd41658 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.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 .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
-2026-07-30-credential-boundaries-and-atomic-registration.md: a093a78d7e3dafe218eb8f1013f226de0d6d9a0b
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 6dcb5fb6bba336ddb2d8de659ef32670ec07129e
+2026-07-30-credential-boundaries-and-atomic-registration.md: 94b32c3cfaa3e1c5059573881a2f393d29aed3ac
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 2506ce391c9125323faf107e3c04c52785e0cc98
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
index a093a78d7e..94b32c3cfa 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
@@ -10,7 +10,7 @@ English | [中文](2026-07-30-credential-boundaries-and-atomic-registration.zh.m
 
 Review found the credential path leaking across boundaries it had drawn. The shipped surfaces hoisted `$DSH_HOME/.env` into `process.env` before cordis booted, so on the next run `credentials-local` classified every key it had stored itself as a read-only ambient launch override: `describe()` reported `source: 'env'` with `writable: false`, `set`/`unset` rejected as shadowed, and a key stored from the web page or TUI became unrotatable and undeletable while the adapter kept using the value captured at launch. The store's own write path repeated the settings-local defects that same review round fixed (two independent chains, whole-file render from a stale cache), plus editor bugs of its own: a physical line inside another key's quoted multi-line value read as an assignment, CRLF endings degraded to LF, a multi-line entry reported `writable: true` while `set` always threw, and `credentials/updated` was emitted bare after the commit, so one broken observer made a durable write look failed. On the read side, the file's `0600` mode stops other OS users but not the model, whose bash and filesystem tools run as the same user.
 
-Two request-path defects sat beside them. DeepSeek's per-request resolution kept connection facts in a last-good snapshot but re-read the literal `apiKey` from the raw configuration, so a settings generation the resolver rejected could still put its key on the previous generation's endpoint. pi-ai handed the SDK `undefined` when a configured `apiKeyEnv` resolved to nothing, letting pi-ai's own environment discovery authenticate with an unrelated provider key — another tenant, silently billed. And its route swap disposed the old registration before creating the new one: a route another adapter owned dropped every existing route, after which the facts cache could equal the registry's, so restoring the working configuration never re-applied.
+Two request-path defects sat beside them. DeepSeek resolved connection and credential facts independently, so a settings generation the resolver rejected could still pair its credential choice with the previous generation's endpoint. pi-ai handed the SDK `undefined` when a configured `apiKeyEnv` resolved to nothing, letting pi-ai's own environment discovery authenticate with an unrelated provider key — another tenant, silently billed. And its route swap disposed the old registration before creating the new one: a route another adapter owned dropped every existing route, after which the facts cache could equal the registry's, so restoring the working configuration never re-applied.
 
 ## Decision
 
@@ -18,7 +18,7 @@ Two request-path defects sat beside them. DeepSeek's per-request resolution kept
 
 **The stored credential has no boundary against the model, and the READMEs say so.** `0600` under a `0700` directory stops other OS users; the model's bash and filesystem tools run as that same user, and the shipped default confines nothing. What the harness does hold to is narrower and stated as exactly that: no surface hoists the document into `process.env`, and the model is never handed a resolved path to it, so reaching the value takes a deliberate read of a path it was not given. An OS-keychain provider — a store the model's processes cannot read at all — is recorded as the real answer rather than implied by a partial one.
 
-**One request, one generation.** DeepSeek's resolved snapshot carries the credential facts (literal key and reference) beside the endpoint, and `resolveApiKey` receives that snapshot instead of re-reading configuration. A rejected generation now contributes nothing at all. pi-ai defers to provider-native discovery only for a profile naming no credential; a configured reference that misses fails with `MISSING_CREDENTIAL` naming the route and the reference. The boot-time credential probe is deleted: it could run before the credentials service mounted and reported every failure as a missing key, while the first request already gives the accurate error.
+**One request, one generation.** DeepSeek's resolved snapshot carries the credential reference beside the endpoint, and `resolveApiKey` receives that snapshot instead of re-reading configuration. A rejected generation now contributes nothing at all. pi-ai defers to provider-native discovery only for a profile naming no credential; a configured reference that misses fails with `MISSING_CREDENTIAL` naming the route and the reference. The boot-time credential probe is deleted: it could run before the credentials service mounted and reported every failure as a missing key, while the first request already gives the accurate error.
 
 **Route replacement is a registry operation, not a caller sequence.** `registerAdapter` returns a handle carrying `replace(providers)`: the candidate set is validated in full first (conflicts, names, provider metadata), then swapped in one synchronous section. A refused replacement leaves the previous routes registered and serving, and the caller's facts cache only advances after the registry actually holds the new set, so reverting to a working configuration re-applies. pi-ai's registration facts are sorted by provider, so a settings document that merely reorders its keys is no longer a route change.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index 6dcb5fb6bb..2506ce391c 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 在读取一侧，文件的 `0600` 权限挡得住其他 OS 用户，却挡不住模型：它的 bash 与文件系统工具就以同一个用户身份运行。
 
-与之并排的还有两个请求路径缺陷。DeepSeek 的按请求解析把连接事实保存在最后可用快照里，却仍从原始配置重新读取字面 `apiKey`，于是被 resolver 拒绝的那一代设置，照样能把自己的密钥送到上一代的端点上。配置了 `apiKeyEnv` 却解析不到值时，pi-ai 会把 `undefined` 交给 SDK，让 pi-ai 自己的环境发现拿一个毫不相干的提供方密钥完成鉴权——那是另一个租户，账单还悄悄记在它头上。而且它的路由替换是先释放旧注册、再创建新注册：只要有一条路由已被别的适配器占有，现有路由就会被全部丢掉，此后事实缓存可能与注册表中的事实相等，于是把配置改回可用状态也不会重新生效。
+与之并排的还有两个请求路径缺陷。DeepSeek 分别解析连接事实与凭据事实，因此被 resolver 拒绝的那一代设置仍可能把自己的凭据选择与上一代的端点配在一起。配置了 `apiKeyEnv` 却解析不到值时，pi-ai 会把 `undefined` 交给 SDK，让 pi-ai 自己的环境发现拿一个毫不相干的提供方密钥完成鉴权——那是另一个租户，账单还悄悄记在它头上。而且它的路由替换是先释放旧注册、再创建新注册：只要有一条路由已被别的适配器占有，现有路由就会被全部丢掉，此后事实缓存可能与注册表中的事实相等，于是把配置改回可用状态也不会重新生效。
 
 ## 决策
 
@@ -22,7 +22,7 @@ Status: implemented
 
 **存下的凭据对模型没有边界，而 README 就是这么写的。**`0700` 目录下的 `0600` 挡得住其他 OS 用户；模型的 bash 与文件系统工具正是以同一用户身份运行，而已交付的默认值不约束任何东西。harness 真正守住的更窄，也就照这个宽度写下来：没有任何一个面会把该文档提升进 `process.env`，模型也从不会拿到它的解析后路径，因此要拿到这个值，需要刻意去读一条并未交给它的路径。OS 钥匙串（keychain）提供方——一个模型的进程根本读不到的存储——被记录为真正的答案，而不是靠一个残缺的方案去暗示它。
 
-**一次请求，一代设置。**DeepSeek 解析出的快照在端点旁一并携带凭据事实（字面密钥与引用），`resolveApiKey` 接收这份快照，而不再重新读取配置。被拒绝的那一代如今完全不再贡献任何东西。只有当一个 profile 完全没有点名凭据时，pi-ai 才交给提供方原生的发现流程；配置了引用却解析不到，就以 `MISSING_CREDENTIAL` 失败，并点名该路由与该引用。启动时的凭据探测被删除：它可能在凭据服务挂载之前就运行，并把每一种失败都报成密钥缺失，而第一次请求本就会给出准确的错误。
+**一次请求，一代设置。**DeepSeek 解析出的快照在端点旁一并携带凭据引用，`resolveApiKey` 接收这份快照，而不再重新读取配置。被拒绝的那一代如今完全不再贡献任何东西。只有当一个 profile 完全没有点名凭据时，pi-ai 才交给提供方原生的发现流程；配置了引用却解析不到，就以 `MISSING_CREDENTIAL` 失败，并点名该路由与该引用。启动时的凭据探测被删除：它可能在凭据服务挂载之前就运行，并把每一种失败都报成密钥缺失，而第一次请求本就会给出准确的错误。
 
 **路由替换是注册表的操作，不是调用方的一串步骤。**`registerAdapter` 返回一个携带 `replace(providers)` 的句柄：候选集合先被完整校验（冲突、名称、提供方元数据），再在一个同步区段内完成替换。被拒绝的替换会让先前的路由保持注册并继续服务，而调用方的事实缓存只有在注册表确实持有新集合之后才会推进，因此改回可用配置时会重新生效。pi-ai 的注册事实按提供方排序，因此仅仅调换键顺序的设置文档不再算作路由变更。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 32f4e05648..2d966fa8ea 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: 2603736e35fbf838609fd2ca133785cfe5534e27
-2026-08-04-configuration-source-ownership.zh.md: 98c9291503201db81b5b4797dcc04823e0a27db7
+2026-08-04-configuration-source-ownership.md: 0b11df50c8f00875a92b722e9f225dd27ed218b5
+2026-08-04-configuration-source-ownership.zh.md: 648cea0167bef564195597f7b2791b5211d40267
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index 2603736e35..0b11df50c8 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -56,7 +56,6 @@ The line is that these take effect with no user action, before any turn, outside
 - A `.env` holding `DSH_*`, `PATH`, or a proxy variable fails the launch instead of being applied. Developers keeping switches in a repository `.env` move them to their shell — a deliberate, loud break.
 - Composition is no longer overridable by a stale shell endpoint. It is still overridable by a user's stored `settings.yaml`, which is the settings seam's layering and not something this note changes; the product CLI offers no flag above it, so a deployment that must win against stored settings owns its own bin or loader tree.
 - Not solved: the layers are still materialized into `process.env`, so ordinary project variables continue to reach child processes under the subprocess scrub. Bootstrap variables cannot come from a file at all; the environment package records the remaining subprocess reach as a limitation.
-- The LLM adapters no longer accept a literal `apiKey`: configuration carries the reference and nothing else, so a settings document cannot become a second credential store. No adapter namespace is strict, so writing one is dropped rather than rejected. The web-search providers still declare a `role('secret')` literal key; they register no settings namespace, so nothing can shadow a stored credential through them, but the claim is about the adapters rather than the repository as a whole.
 - Exa and Perplexity still capture their key at load time rather than through the credential seam. They no longer read raw `process.env` — they resolve through the trusted layers — but converting them to per-request seam resolution is separate work.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index 98c9291503..648cea0167 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -58,7 +58,6 @@ inherited process environment      (read-only, wins)
 - 含 `DSH_*`、`PATH` 或 proxy 变量的 `.env` 会导致启动失败而不是被应用。把开关放在仓库 `.env` 里的开发者需要改放到 shell——这是一次刻意且响亮的破坏。
 - composition 不再会被陈旧的 shell endpoint 覆盖。但它仍然会被用户已存的 `settings.yaml` 覆盖，这是 settings seam 的分层方式，本 Note 不改变它；产品 CLI 没有高于它的标志，因此需要压过已存 settings 的部署方要自带 bin 或 loader 配置树。
 - 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件；其余变量抵达子进程的限制记录在环境包中。
-- LLM 适配器不再接受字面 `apiKey`：配置只携带引用，因此 settings 文档无法成为第二个凭据存储。由于没有任何适配器 namespace 是 strict 的，写入该键会被 schema 丢弃而不是报错。web-search 提供方仍声明 `role('secret')` 的字面密钥字段；它们不注册 settings namespace，因此无法借此遮蔽已存凭据，但这条声明的范围是适配器，而不是整个仓库。
 - Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求经 seam 解析是另一件事。
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index 123058ac7e..e1c3ac3ef8 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.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 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
-2026-08-06-api-key-format-validation.md: d1f6d31d362b76392514704be780f553b45d36ad
-2026-08-06-api-key-format-validation.zh.md: 75b3fa247bdf449964a874e909e6e3bc9e0694fa
+2026-08-06-api-key-format-validation.md: e9ca76ede06080f2b868f6436998d163e642adbc
+2026-08-06-api-key-format-validation.zh.md: 5666a884d4c9478291072375681d8d3526b2632a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
index d1f6d31d36..e9ca76ede0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
@@ -12,7 +12,7 @@ Pasting a key containing an emoji, CJK text, or a full-width punctuation mark in
 
 `llm-pi-ai` was worse on the same input. Its discovery probe builds the same header with a bare `fetch` in [discovery.ts](../../../../packages/llm/llm-pi-ai/src/discovery.ts) and wrapped every failure as `could not reach <url>`, so a local key fault was reported as an unreachable network. The probe is reachable from the unsaved draft: `ProviderEditor` puts the typed `keyDraft` into its probe request, so the model-listing button sent an illegal key before anything was stored.
 
-Whitespace passed every check. `ProviderEditor` tested `keyDraft.length` and `resolveAdapterOptions` tested `config.apiKey.length`, so a key of three spaces stored and then authenticated as `Bearer` plus blanks. `llm-pi-ai` rejected an empty literal `apiKey` in `resolveProfiles`, but applied no check whatsoever to a credential- or environment-sourced key — the path the Models page writes, and therefore the path users actually take.
+Whitespace passed every check. `ProviderEditor` tested `keyDraft.length`, so a key of three spaces was stored and then authenticated as `Bearer` plus blanks. Neither adapter checked a credential- or environment-sourced key — the path the Models page writes, and therefore the path users actually take.
 
 Sources: deepseek-harness#1594 and #1595; dsh-external#247, #249, #266, and #210.
 
@@ -32,13 +32,13 @@ The shape rule is a guess about how people paste, so it runs **only in the brows
 
 ### Absence is a configuration state, not a missing key
 
-"No API key" means three different things here, and only one of them is an error. The rule applies to a value that was *provided*; deciding whether one was provided at all stays with each caller.
+The rule applies to a value that was *provided*; deciding whether one was provided at all stays with each caller.
 
-**Omitted.** A profile naming neither `apiKey` nor `apiKeyEnv` is authenticated by something other than a harness-held key. `routeAuth` in [provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) keeps the installed catalog provider's own auth precisely so provider-native ambient discovery survives, and `openai-codex` — shipped in that catalog — authenticates through OAuth and refuses an explicit key outright. `namesCredential` carries this distinction. In `llm-deepseek`, an absent `apiKey` likewise falls through to `apiKeyEnv`. Omission is never validated.
+**No named credential.** A pi-ai profile omitting `apiKeyEnv` may authenticate outside the harness-held credential path. `routeAuth` in [provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) keeps the installed catalog provider's own auth precisely so provider-native ambient discovery survives, and `openai-codex` — shipped in that catalog — authenticates through OAuth. `namesCredential` carries this distinction; omission is not a value to validate.
 
 **A blank field in the web UI.** The key input opens empty even for a provider whose key is already stored — the `keyStored` copy reads "Configured — enter a new value to replace" — so blank means *keep what is stored*. `ProviderEditor` skips `credentials.set` entirely when the draft is empty, and that stays a no-op: a blank field never blocks submit, or editing a base URL would demand re-entering the key.
 
-**Provided, but empty or whitespace-only.** What this means depends on what absence selects for that surface, and the two adapters differ for a reason. In `llm-pi-ai` it is an error, because absence there switches authentication mode — to the installed provider's ambient discovery or OAuth — so a blank key leaves genuine ambiguity about which was meant; its wording names the legitimate alternative rather than just refusing (*has an empty apiKey; omit it to use ambient authentication*). In `llm-deepseek` absence merely selects a different *source* for the same key, `apiKeyEnv`, so a blank literal resolves through that fallback exactly as an omitted one does. In the browser it is always a failure, on both cards: the field is where a person just typed, and silently discarding what they typed is never the right answer.
+**A resolved value that is whitespace-only.** This is invalid at both adapters because it cannot authenticate a request. In the browser it is also a field-level failure: the field is where a person just typed, and silently discarding what they typed is never the right answer.
 
 `normalizeApiKey` therefore takes `string`, never `string | undefined`.
 
@@ -55,9 +55,7 @@ The client cannot import any of this: client packages reference only client pack
 | Surface | Behavior |
 |---|---|
 | `dsh-llm` | Owns `normalizeApiKey`, `assertUsableApiKey`, and `INVALID_CREDENTIAL_CODE`, which is deliberately outside `DEFAULT_RETRYABLE_CODES`. |
-| `llm-deepseek` `resolveAdapterOptions` | Refuses a literal `apiKey` no header can carry, beside the other beyond-schema bounds; uses the trimmed value. An absent or blank one falls through to `apiKeyEnv`. |
 | `llm-deepseek` `resolveApiKey` | Normalizes what the credentials seam or environment returns, rejecting with `INVALID_CREDENTIAL` naming the Models page and never echoing the key. |
-| `llm-pi-ai` `resolveProfiles` | Applies the shared rule, keeping its "omit it to use ambient authentication" wording, and writes the trimmed value into the resolved profile. |
 | `llm-pi-ai` `resolveApiKey` | Normalizes the credential and environment paths. A profile naming no credential still returns `undefined`, so ambient and OAuth routes are unaffected. |
 | `llm-pi-ai` `discoverModels` | Normalizes before building the header, so an illegal key is a credential fault rather than an unreachable endpoint. A probe carrying no key stays unauthenticated. |
 | `ui-models` | Mirrors the charset rule, adds the shape heuristic, trims `keyDraft` before probe and `credentials.set`, and fixes the `stringAt` emptiness test. A blank field remains a no-op that submits; a field holding only whitespace is a field-level failure. Submit **and the endpoint interrogation** are both gated, so a refused key never spends a round trip to be told what the field already says, and the failure renders on the field, matching the existing `modelFailure` pattern. |
@@ -68,8 +66,6 @@ The client cannot import any of this: client packages reference only client pack
 
 ## Alternatives considered
 
-**A `.pattern()` on the `apiKey` schema field.** Vendored schemastery supports it, and the pattern would serialize to the browser with the rest of the namespace schema — one rule, delivered rather than mirrored. It lost because a pattern cannot trim first: `cordis.yml` would then reject a padded key while `.env` tolerated one, and the resolver would disagree with the schema about the same string. Validating in `resolveAdapterOptions` keeps every surface trim-then-validate, and that function is already where this package re-judges bounds the schema cannot express.
-
 **A validation module shared by client and host.** Rejected by the source-plane layout: client packages reference only client packages plus `vendor/cordis` and `support/invariants`, and widening that to reach a host package would collide the two `Context` merges the split exists to keep apart. Mirroring a one-line predicate with a test on each side is the established shape here.
 
 **A per-adapter thrower in each of `llm-deepseek` and `llm-pi-ai`.** The first plan gave each adapter its own, differing only by the package prefix in the message, with a duplication-gate exemption to excuse the pair. Rejected before implementation: `LlmError` is declared in the seam, so the seam can own the diagnosis outright, and an exemption there would have hidden exactly the duplication it was covering for.
@@ -100,7 +96,7 @@ The costliest way to get this wrong would have been to treat absence as invalidi
 
 `packages/llm/llm/tests/api-key.spec.ts` drives `normalizeApiKey` and `assertUsableApiKey` over the whole input table — empty, whitespace-only, padded, interior-space, C0 control, emoji, CJK, full-width, latin-1, and the printable-ASCII boundary — and pins that a refusal carries `INVALID_CREDENTIAL` and no part of the key.
 
-`packages/llm/llm-deepseek/tests/` covers the literal-config path in `adapter.spec.ts` and the stored-credential path end to end in `dynamic-config.spec.ts`, through the real credentials seam rather than a stub. `packages/llm/llm-pi-ai/tests/` covers `resolveProfiles` — including that the trimmed value reaches the resolved profile, which the `...rest` spread would otherwise discard — and the discovery probe, including that a probe with no key sends no `authorization` header.
+`packages/llm/llm-deepseek/tests/` covers the stored-credential path end to end in `dynamic-config.spec.ts`, through the real credentials seam rather than a stub. `packages/llm/llm-pi-ai/tests/` covers the discovery probe, including that a probe with no key sends no `authorization` header.
 
 `packages/client/ui-models/tests/` pins `apiKeyFailure` over the same table plus the paste-shape cases, and drives both cards: a blank field submits without writing a credential, a whitespace-only field fails on the field, an illegal or wrapped key blocks submit and the interrogation alike, a padded key is trimmed before `credentials.set` and before an interrogation, and a hand-declared route can be created with no key at all.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index 75b3fa247b..5666a884d4 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 同样的输入在 `llm-pi-ai` 上更糟。它的探测路径在 [discovery.ts](../../../../packages/llm/llm-pi-ai/src/discovery.ts) 里用裸 `fetch` 构造同一个 header，并把一切失败包装成 `could not reach <url>`，于是一个本地的 Key 故障被报成网络不可达。这条探测在保存之前就够得着：`ProviderEditor` 把用户输入的 `keyDraft` 直接放进探测请求，所以「获取模型列表」按钮会在任何东西落盘之前就把非法 Key 发出去。
 
-空白字符能通过每一道检查。`ProviderEditor` 判的是 `keyDraft.length`，`resolveAdapterOptions` 判的是 `config.apiKey.length`，于是三个空格构成的 Key 会被存下，随后以 `Bearer` 加若干空格去认证。`llm-pi-ai` 在 `resolveProfiles` 中拒绝空的字面量 `apiKey`，却对来自凭据或环境的 Key 完全不做检查——而那正是模型设置页写入的路径，也就是用户真正走的路径。
+空白字符能通过每一道检查。`ProviderEditor` 判的是 `keyDraft.length`，于是三个空格构成的 Key 会被存下，随后以 `Bearer` 加若干空格去认证。两个适配器都不检查来自凭据或环境的 Key——而那正是 Models 页写入的路径，也就是用户真正走的路径。
 
 来源：deepseek-harness#1594 与 #1595；dsh-external#247、#249、#266、#210。
 
@@ -32,13 +32,13 @@ Status: implemented
 
 ### 「没有 Key」是一种配置状态，不是缺失
 
-在这里，「没有 API Key」意味着三件完全不同的事，其中只有一件是错误。规则作用于**已提供**的值；至于究竟有没有提供，由各个调用方自行判断。
+规则作用于*已提供*的值；至于究竟有没有提供，由各个调用方自行判断。
 
-**未指定。** 既不写 `apiKey` 也不写 `apiKeyEnv` 的 profile，是由 harness 所持有的 Key 之外的东西来鉴权的。[provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) 中的 `routeAuth` 保留内置 catalog provider 自身的鉴权，正是为了让 provider 原生的 ambient 发现得以存活；而该 catalog 附带的 `openai-codex` 通过 OAuth 鉴权，并会直接拒绝一个显式的 Key。`namesCredential` 承载着这一区分。在 `llm-deepseek` 中，缺省的 `apiKey` 同样会回落到 `apiKeyEnv`。未指定的情形永不参与校验。
+**未点名凭据。** 省略 `apiKeyEnv` 的 pi-ai profile 可以在 harness 持有的凭据路径之外鉴权。[provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) 中的 `routeAuth` 保留内置 catalog provider 自身的鉴权，正是为了让 provider 原生的 ambient 发现继续工作；而该 catalog 附带的 `openai-codex` 通过 OAuth 鉴权。`namesCredential` 承载这一区分；省略不是需要校验的值。
 
 **Web UI 中留空的输入框。** 即便某个 provider 的 Key 已经存好，该输入框也是空着打开的——`keyStored` 的文案写的是「已配置——输入新值以替换」——所以留空意味着*保持已存储的值*。`ProviderEditor` 在草稿为空时完全跳过 `credentials.set`，这一点保持不变：留空绝不拦截提交，否则改一个 base URL 都得重新输一遍 Key。
 
-**已提供，但为空或纯空白。** 它意味着什么，取决于「缺失」在该界面上选中了什么，而两个适配器的差异是有依据的。在 `llm-pi-ai` 中它是错误，因为那里的缺失切换的是**鉴权方式**——转向内置 provider 的 ambient 发现或 OAuth——因此一个空 Key 究竟想选哪一种是真有歧义；它的措辞指明了合法替代路径而非单纯拒绝（*has an empty apiKey; omit it to use ambient authentication*）。在 `llm-deepseek` 中，缺失只是为同一把 Key 选择了另一个**来源** `apiKeyEnv`，因此空白字面量会像缺省一样经该回落解析。在浏览器中它始终是失败，两张卡片皆然：字段是人刚刚敲过字的地方，静默丢弃他敲进去的内容永远不是正确答案。
+**解析得到的值只含空白。** 两个适配器都将其视为非法，因为它无法为请求鉴权。在浏览器中，这同样是字段级失败：字段是人刚刚敲过字的地方，静默丢弃他敲进去的内容永远不是正确答案。
 
 因此 `normalizeApiKey` 接受 `string`，而绝非 `string | undefined`。
 
@@ -55,9 +55,7 @@ Status: implemented
 | 界面 | 行为 |
 |---|---|
 | `dsh-llm` | 拥有 `normalizeApiKey`、`assertUsableApiKey` 与 `INVALID_CREDENTIAL_CODE`，后者刻意不进 `DEFAULT_RETRYABLE_CODES`。 |
-| `llm-deepseek` `resolveAdapterOptions` | 拒绝标头无法承载的字面量 `apiKey`，与其他超出 schema 的边界检查并排；使用 trim 后的值。缺省或空白的 `apiKey` 回落到 `apiKeyEnv`。 |
 | `llm-deepseek` `resolveApiKey` | 归一化凭据 seam 或环境返回的值，以 `INVALID_CREDENTIAL` 拒绝，消息指明模型设置页，绝不回显 Key。 |
-| `llm-pi-ai` `resolveProfiles` | 施加这条共享规则，保留其「omit it to use ambient authentication」的措辞，并把 trim 后的值写进解析后的 profile。 |
 | `llm-pi-ai` `resolveApiKey` | 归一化凭据与环境路径。不指定任何凭据的 profile 仍返回 `undefined`，ambient 与 OAuth 路由不受影响。 |
 | `llm-pi-ai` `discoverModels` | 在构造 header 之前归一化，使非法 Key 成为凭据故障而非端点不可达。不带 Key 的探测保持未鉴权。 |
 | `ui-models` | 镜像字符集规则，加入形状启发式，在探测与 `credentials.set` 之前 trim `keyDraft`，并修正 `stringAt` 的空值判断。留空的输入框仍是可以提交的空操作；只含空白的输入框则是字段级失败。提交**与端点探测**同时受拦截，因此被拒绝的密钥不会白花一次往返去换取字段上已经写明的答案；失败呈现在字段上，与既有的 `modelFailure` 模式一致。 |
@@ -68,8 +66,6 @@ Status: implemented
 
 ## Alternatives considered
 
-**在 `apiKey` schema 字段上加 `.pattern()`。** vendor 中的 schemastery 支持它，且该 pattern 会随命名空间 schema 一同序列化到浏览器——一条规则，投递而非镜像。它落败于 pattern 无法先行 trim：那样 `cordis.yml` 会拒绝带首尾空白的 Key 而 `.env` 却容忍，resolver 与 schema 会对同一个字符串给出分歧。在 `resolveAdapterOptions` 中校验可以让每一层都是 trim-then-validate，而该函数本就是本包重新裁定 schema 无法表达的边界之处。
-
 **由 client 与 host 共享一个校验模块。** 被 source plane 布局否决：client 包只 reference client 包外加 `vendor/cordis` 与 `support/invariants`，把它放宽到够得着 host 包会撞上这一分割本就要隔开的两份 `Context` 合并。在两侧各镜像一行断言并各配一份测试，是此处的既定形态。
 
 **在 `llm-deepseek` 与 `llm-pi-ai` 中各留一个抛错 helper。** 最初的计划正是各留一份，差别仅在消息中的包名前缀，并配一个重复检测豁免来放行这一对。在实现之前即被否决：`LlmError` 声明在 seam 中，因此 seam 完全可以自己拥有这句诊断，而那里的一个豁免恰恰会掩盖它本要遮掩的重复。
@@ -100,7 +96,7 @@ Status: implemented
 
 `packages/llm/llm/tests/api-key.spec.ts` 以整张输入表驱动 `normalizeApiKey` 与 `assertUsableApiKey`——空值、纯空白、带首尾空白、含中间空格、C0 控制字符、emoji、中文、全角、latin-1，以及可打印 ASCII 的边界字符——并钉住一次拒绝携带 `INVALID_CREDENTIAL` 且不含 Key 的任何部分。
 
-`packages/llm/llm-deepseek/tests/` 在 `adapter.spec.ts` 中覆盖字面量配置路径，在 `dynamic-config.spec.ts` 中经真实凭据 seam（而非 stub）端到端覆盖已存储凭据路径。`packages/llm/llm-pi-ai/tests/` 覆盖 `resolveProfiles`——包括 trim 后的值确实到达解析后的 profile，否则会被 `...rest` 展开丢弃——以及探测路径，包括不带 Key 的探测不会发出 `authorization` 标头。
+`packages/llm/llm-deepseek/tests/` 在 `dynamic-config.spec.ts` 中经真实凭据 seam（而非 stub）端到端覆盖已存储凭据路径。`packages/llm/llm-pi-ai/tests/` 覆盖探测路径，包括不带 Key 的探测不会发出 `authorization` 标头。
 
 `packages/client/ui-models/tests/` 以同一张表加上形状用例钉住 `apiKeyFailure`，并驱动两张卡片：留空的输入框可提交且不写入凭据、只含空白的输入框在字段上失败、非法或被包裹的 Key 同时拦截提交与探测、带首尾空白的 Key 在 `credentials.set` 与探测之前被 trim，以及手工声明的路由可以完全不带 Key 创建。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
index 9f16a183b9..de0b20d867 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.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 .agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.md
-2026-08-06-provider-credential-lifecycle.md: ce45207e7ac7224f44e34945e36ba85db0971f09
-2026-08-06-provider-credential-lifecycle.zh.md: c476417517b8ed72036344a13720a8ba378775e6
+2026-08-06-provider-credential-lifecycle.md: c28788921e8f1b233b44e19b29ad4d4acaa25022
+2026-08-06-provider-credential-lifecycle.zh.md: 2ea3b21fb6ceb4fa38a0cad0daf47c3b6a98a664
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.md b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.md
index ce45207e7a..c28788921e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.md
@@ -12,7 +12,7 @@ The Models editor spans independent settings and credential RPC domains. It prev
 
 Provider save remains a two-stage settings-then-credentials operation over the existing wire domains, but the card treats the successful settings response as a commit checkpoint. It replaces its comparison subtree and expected revision with the returned redacted descriptor before attempting `credentials.set`; if that second stage fails, the draft key and card stay visible, and retry produces no settings ops and repeats only the credential write. Genuine concurrent changes before the first settings commit still fail with `settings-conflict`. Typed keys are trimmed at the UI and direct DeepSeek resolver boundaries, and pi-ai records a derived reference only when the normalized key is non-empty; saving a blank key materializes an empty, reference-free profile for provider-native discovery.
 
-Deletion removes a credential only when the joined row identifies the exact `<ROUTE>_API_KEY` reference derived by this page and reports it configured and writable. It unsets that credential before the user-layer profile so a settings-stage failure leaves the row and its frozen target visible for retry; both unsets are idempotent. Custom references, environment credentials, missing credentials, and targets the join cannot identify are retained. The row's accessible Edit/Delete names and the destructive dialog title, description, and final action all use the same stable `Display Name (route-id)` identity, collapsing to the route id when both strings match. The dialog states whether the stored key will be removed and owns operation failures instead of replacing the whole page with a load-error banner. Rows expose API-key state only from the value-free join: a confirmed literal or referenced credential is a green solid dot, a confirmed missing named reference is a red solid dot, and reference-free provider-native authentication or unavailable credential enrichment has no dot. Each dot has accessible copy and a tooltip, while successful Apply uses the same provider identity in a local status message and never echoes secret material.
+Deletion removes a credential only when the joined row identifies the exact `<ROUTE>_API_KEY` reference derived by this page and reports it configured and writable. It unsets that credential before the user-layer profile so a settings-stage failure leaves the row and its frozen target visible for retry; both unsets are idempotent. Custom references, environment credentials, missing credentials, and targets the join cannot identify are retained. The row's accessible Edit/Delete names and the destructive dialog title, description, and final action all use the same stable `Display Name (route-id)` identity, collapsing to the route id when both strings match. The dialog states whether the stored key will be removed and owns operation failures instead of replacing the whole page with a load-error banner. Rows expose API-key state only from the value-free join: a confirmed referenced credential is a green solid dot, a confirmed missing named reference is a red solid dot, and reference-free provider-native authentication or unavailable credential enrichment has no dot. Each dot has accessible copy and a tooltip, while successful Apply uses the same provider identity in a local status message and never echoes secret material.
 
 ## Alternatives considered
 
@@ -20,8 +20,8 @@ Deletion removes a credential only when the joined row identifies the exact `<RO
 
 **Delete every credential reference named by a removed profile.** A custom reference can be shared, externally managed, or intentionally survive profile churn. Exact equality with this page's derived target plus configured+writable state is the narrow evidence available to the page; anything weaker risks deleting a credential it does not own.
 
-**Remove settings first and compensate by recreating the profile.** The browser holds only a redacted subtree and cannot faithfully reconstruct stored literal secrets or concurrent edits. Credential-first deletion leaves the authoritative profile visible on partial failure and makes retry safe without synthesizing configuration.
+**Remove settings first and compensate by recreating the profile.** The browser holds only a redacted subtree and cannot faithfully reconstruct concurrent edits. Credential-first deletion leaves the authoritative profile visible on partial failure and makes retry safe without synthesizing configuration.
 
 ## Consequences
 
-The Models page can recover from either second-stage failure without reload, secret disclosure, or a false concurrency conflict, and blank-key pi-ai profiles preserve Bedrock, Vertex, and other provider-native authentication. Confirmed status is visible without turning route liveness, native authentication, or a failed credential lookup into a false error, and a successful replacement remains observable even when the row stays green. Deleting a page-managed provider no longer leaves a reusable local key, while ambiguous credentials deliberately remain for manual management. Save and delete are still not atomic across durable stores: a process crash can stop between stages, but their order and idempotence leave an observable, retryable state. Component tests pin partial-success retries, empty-key native auth, normalized literals, status visibility, target identity, cleanup ownership, and credential/settings rejection ordering; the keyless browser scenario pins bilingual accessible copy and verifies that confirmed deletion removes both `settings.yaml` profile and `.env` credential. This decision refines the Models apply semantics recorded in the [web configuration plane note](../architecture/2026-07-30-web-config-plane.md).
+The Models page can recover from either second-stage failure without reload, secret disclosure, or a false concurrency conflict, and blank-key pi-ai profiles preserve Bedrock, Vertex, and other provider-native authentication. Confirmed status is visible without turning route liveness, native authentication, or a failed credential lookup into a false error, and a successful replacement remains observable even when the row stays green. Deleting a page-managed provider no longer leaves a reusable local key, while ambiguous credentials deliberately remain for manual management. Save and delete are still not atomic across durable stores: a process crash can stop between stages, but their order and idempotence leave an observable, retryable state. Component tests pin partial-success retries, empty-key native auth, trimmed key handling, status visibility, target identity, cleanup ownership, and credential/settings rejection ordering; the keyless browser scenario pins bilingual accessible copy and verifies that confirmed deletion removes both the `settings.yaml` profile and `.credentials.yaml` entry. This decision refines the Models apply semantics recorded in the [web configuration plane note](../architecture/2026-07-30-web-config-plane.md).
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
index c476417517..2ea3b21fb6 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
@@ -12,7 +12,7 @@ Models 编辑器横跨互相独立的 settings 与凭据 RPC 领域。之前它
 
 提供方保存仍在现有 wire 领域上按先 settings、后凭据的两阶段顺序执行，但卡片会把成功的 settings 响应视为提交检查点。它会在尝试 `credentials.set` 之前，用返回的脱敏 descriptor 替换比较基准子树与预期 revision；如果第二阶段失败，草稿密钥与卡片会继续显示，重试不会产生 settings op，只会再次写入凭据。首次 settings 提交之前发生的真实并发变更仍会以 `settings-conflict` 失败。UI 与 DeepSeek 直连 resolver 边界均会去除所输密钥的首尾空白，且只有标准化密钥非空时，pi-ai 才会记录派生引用；留空密钥会具化一个空的、不带引用的 profile，以便使用提供方原生凭据发现。
 
-只有当联接所得的行识别出该页面派生的精确 `<ROUTE>_API_KEY` 引用，并将其报告为已配置且可写时，删除操作才会清除该凭据。它会先取消设置该凭据，再取消设置用户层 profile；如果 settings 阶段失败，该行及其已冻结的目标仍可见，便于重试。两项 unset 都具备幂等性。自定义引用、环境凭据、缺失的凭据，以及联接无法识别目标的凭据均会保留。行的无障碍 Edit/Delete 名称以及破坏性对话框的标题、说明和最终操作都使用同一个稳定的 `Display Name (route-id)` 标识；当两个字符串相同时，标识会简化为路由 id。对话框会说明是否一并删除已存密钥，并在自身内显示操作失败，而不是用加载错误横幅替换整个页面。行只根据不含值的联接结果展示 API 密钥状态：确认已配置的字面密钥或引用凭据显示为绿色实心点，确认缺失的具名引用显示为红色实心点，无引用的提供方原生认证或无法取得凭据补充信息时则不显示状态点。每个状态点都有无障碍文案和工具提示；「应用」成功后的本地状态消息会使用同一个提供方标识，且绝不回显任何机密内容。
+只有当联接所得的行识别出该页面派生的精确 `<ROUTE>_API_KEY` 引用，并将其报告为已配置且可写时，删除操作才会清除该凭据。它会先取消设置该凭据，再取消设置用户层 profile；如果 settings 阶段失败，该行及其已冻结的目标仍可见，便于重试。两项 unset 都具备幂等性。自定义引用、环境凭据、缺失的凭据，以及联接无法识别目标的凭据均会保留。行的无障碍 Edit/Delete 名称以及破坏性对话框的标题、说明和最终操作都使用同一个稳定的 `Display Name (route-id)` 标识；当两个字符串相同时，标识会简化为路由 id。对话框会说明是否一并删除已存密钥，并在自身内显示操作失败，而不是用加载错误横幅替换整个页面。行只根据不含值的联接结果展示 API 密钥状态：确认已配置的引用凭据显示为绿色实心点，确认缺失的具名引用显示为红色实心点，无引用的提供方原生认证或无法取得凭据补充信息时则不显示状态点。每个状态点都有无障碍文案和工具提示；「应用」成功后的本地状态消息会使用同一个提供方标识，且绝不回显任何机密内容。
 
 ## 曾考虑的替代方案
 
@@ -20,8 +20,8 @@ Models 编辑器横跨互相独立的 settings 与凭据 RPC 领域。之前它
 
 **删除被移除 profile 所指定的每一个凭据引用。**自定义引用可能被共享、由外部管理，或有意在 profile 反复增删时存留。与该页面派生目标精确相等，再加上已配置且可写的状态，是页面所能获得的最小范围证据；比这更弱的判定都有可能删除不属于它的凭据。
 
-**先删除 settings，再重建 profile 以作补偿。**浏览器只持有脱敏后的子树，无法忠实重建已存的字面机密或并发编辑。先删除凭据可以让权威 profile 在部分失败时仍然可见，并且无需合成配置就能安全重试。
+**先删除 settings，再重建 profile 以作补偿。**浏览器只持有脱敏后的子树，无法忠实重建并发编辑。先删除凭据可以让权威 profile 在部分失败时仍然可见，并且无需合成配置就能安全重试。
 
 ## 后果
 
-Models 页可以从任一第二阶段失败中恢复，无需重新加载，也不会泄露机密或产生虚假的并发冲突；空密钥的 pi-ai profile 会保留 Bedrock、Vertex 与其他提供方原生认证。已确认的状态清晰可见，同时不会把路由存活状态、原生认证或凭据查询失败误报为错误；即使该行继续显示绿色，密钥替换成功也仍然可观察。删除由页面管理的提供方不再遗留可重用的本地密钥，而存在歧义的凭据会有意保留，交由手动管理。保存与删除在跨持久存储时仍非原子操作：进程可能在两个阶段之间崩溃，但它们的顺序与幂等性会留下可观察、可重试的状态。组件测试固定了部分成功后的重试、空密钥原生认证、标准化字面值、状态可见性、目标标识、清理所有权，以及凭据／settings 拒绝顺序；无密钥的浏览器场景固定了双语无障碍文案，并验证确认删除会同时清除 `settings.yaml` profile 与 `.env` 凭据。此决策细化了 [web 配置平面 note](../architecture/2026-07-30-web-config-plane.md) 中记录的 Models 应用语义。
+Models 页可以从任一第二阶段失败中恢复，无需重新加载，也不会泄露机密或产生虚假的并发冲突；空密钥的 pi-ai profile 会保留 Bedrock、Vertex 与其他提供方原生认证。已确认的状态清晰可见，同时不会把路由存活状态、原生认证或凭据查询失败误报为错误；即使该行继续显示绿色，密钥替换成功也仍然可观察。删除由页面管理的提供方不再遗留可重用的本地密钥，而存在歧义的凭据会有意保留，交由手动管理。保存与删除在跨持久存储时仍非原子操作：进程可能在两个阶段之间崩溃，但它们的顺序与幂等性会留下可观察、可重试的状态。组件测试固定了部分成功后的重试、空密钥原生认证、密钥首尾空白处理、状态可见性、目标标识、清理所有权，以及凭据／settings 拒绝顺序；无密钥的浏览器场景固定了双语无障碍文案，并验证确认删除会同时清除 `settings.yaml` profile 与 `.credentials.yaml` 条目。此决策细化了 [web 配置平面 note](../architecture/2026-07-30-web-config-plane.md) 中记录的 Models 应用语义。
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
index 34baccb6f5..418c81f17d 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.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 .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
-2026-07-30-deepseek-onboarding-credential-setup.md: c732758bc567376a0be4ac348aa9129aa8126ac4
-2026-07-30-deepseek-onboarding-credential-setup.zh.md: 2dc7e0ccf5f9a99ad35c859a7ecfb9f98d93d530
+2026-07-30-deepseek-onboarding-credential-setup.md: 419ea0aea56e82e301189d90d5ca78495da2da71
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: 936402c9ed83eccc3d5e78a57247f06347522c0f
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
index c732758bc5..419ea0aea5 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
@@ -10,7 +10,7 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 ## Decision
 
-**One readiness projection owns both Models and onboarding facts.** `ui-models` keeps a single store that joins `llm.providers({})`, redacted `settings.describe({})`, and batched `credentials.describe({refs})`. The onboarding projection selects the `deepseek-official` configurable-provider entry owned by the `llm-deepseek` namespace and empty settings path, reads the effective `apiKeyEnv`, and evaluates the matching credential descriptor. A live route with the same provider id but no matching configurable-provider declaration is adapter-absent for onboarding. A configured literal `apiKey` secret sidecar is also ready, so compatibility configuration does not trigger a false prompt; a configured process-environment credential is ready and remains read-only.
+**One readiness projection owns both Models and onboarding facts.** `ui-models` keeps a single store that joins `llm.providers({})`, redacted `settings.describe({})`, and batched `credentials.describe({refs})`. The onboarding projection selects the `deepseek-official` configurable-provider entry owned by the `llm-deepseek` namespace and empty settings path, reads the effective `apiKeyEnv`, and evaluates the matching credential descriptor. A live route with the same provider id but no matching configurable-provider declaration is adapter-absent for onboarding. A configured process-environment credential is ready and remains read-only.
 
 **The settings shell contributes ordering and navigation, not provider policy.** `ui-settings` declares a root-scoped `settings.onboarding` list slot and mounts one ordered step at a time while the current surface is the empty Hero. The active registrant receives `complete()` and a private `openSection(id)` callback; completion transfers ownership to the next entry. `ui-models` registers the DeepSeek step and its Models section through `slots.inject()`, so each contribution follows its declaration lifetime without making plugin load order a contract, and independently contributed dialogs cannot stack. The product-wide welcome step that precedes it is owned separately by [the versioned welcome decision](2026-07-30-versioned-gui-welcome-onboarding.md).
 
@@ -30,4 +30,4 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 ## Consequences
 
-The ordered flow leads from the product notice to the shipped adapter's existing editor without restarting: a keyless browser test boots the real Web composition under an isolated harness home, acknowledges the notice, follows the DeepSeek page to Models, stores a generated key through that page into the home's `.env`, verifies no key reaches DOM, ARIA, or browser console output, and confirms the running page reports configured. The full keyless Web replay lane also pins that a non-configurable replay route with the same provider id does not block unrelated journeys. Pure readiness and React tests pin literal, file, process-environment, missing-provider, missing-capability, navigation, cancellation, external-invalidation, and coordinator-transfer behavior. The flow deliberately inherits the configuration plane's documented base limitations rather than adding local secret storage, redaction, or settings replacement workarounds.
+The ordered flow leads from the product notice to the shipped adapter's existing editor without restarting: a keyless browser test boots the real Web composition under an isolated harness home, acknowledges the notice, follows the DeepSeek page to Models, stores a generated key through that page into the home's `.credentials.yaml`, verifies no key reaches DOM, ARIA, or browser console output, and confirms the running page reports configured. The full keyless Web replay lane also pins that a non-configurable replay route with the same provider id does not block unrelated journeys. Pure readiness and React tests pin managed-file and process-environment credentials, missing providers and capabilities, navigation, cancellation, external invalidation, and coordinator transfer. The flow deliberately inherits the configuration plane's documented base limitations rather than adding local secret storage, redaction, or settings replacement workarounds.
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
index 2dc7e0ccf5..936402c9ed 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-**Models 与首次使用引导共享同一个就绪状态投影。**`ui-models` 维护一个 store，把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取由 `llm-deepseek` namespace 与空 settings path 持有的 `deepseek-official` 可配置提供方条目，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。同 provider id 但没有匹配可配置提供方声明的存活路由，在首次使用引导中视为适配器缺失。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，也会判定为就绪，兼容配置因此不会误触发页面；通过进程环境提供的凭据若已配置，同样判定为就绪并保持只读。
+**Models 与首次使用引导共享同一个就绪状态投影。**`ui-models` 维护一个 store，把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取由 `llm-deepseek` namespace 与空 settings path 持有的 `deepseek-official` 可配置提供方条目，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。同 provider id 但没有匹配可配置提供方声明的存活路由，在首次使用引导中视为适配器缺失。通过进程环境提供的凭据若已配置，则判定为就绪并保持只读。
 
 **设置外壳只贡献排序与导航，不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 通过 `slots.inject()` 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为契约；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
 
@@ -30,4 +30,4 @@ Status: implemented
 
 ## 后果
 
-有序流程从产品声明页开始，无需重启即可引导用户前往随产品提供的适配器已有的编辑器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，确认声明后依照 DeepSeek 页面前往 Models，通过该页面把生成的密钥存入该目录的 `.env`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的页面报告已配置。完整的无密钥 Web 回放也固定了同 id 的不可配置回放路由不会阻塞无关流程。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、导航、取消、外部失效和协调器移交行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。
+有序流程从产品声明页开始，无需重启即可引导用户前往随产品提供的适配器已有的编辑器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，确认声明后依照 DeepSeek 页面前往 Models，通过该页面把生成的密钥存入该目录的 `.credentials.yaml`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的页面报告已配置。完整的无密钥 Web 回放也固定了同 id 的不可配置回放路由不会阻塞无关流程。纯就绪状态测试与 React 测试固化了受管文件凭据与进程环境凭据、提供方与能力缺失、导航、取消、外部失效和协调器移交。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。
diff --git a/examples/acp-agent/tests/fs-search.cordis.yml b/examples/acp-agent/tests/fs-search.cordis.yml
index c86b34b8aa..9f9ac7cf0c 100644
--- a/examples/acp-agent/tests/fs-search.cordis.yml
+++ b/examples/acp-agent/tests/fs-search.cordis.yml
@@ -2,8 +2,6 @@
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
     models:
       - id: deepseek-v4-pro
 
diff --git a/examples/acp-agent/tests/pwsh.cordis.yml b/examples/acp-agent/tests/pwsh.cordis.yml
index 7021ae2116..570d98bf4d 100644
--- a/examples/acp-agent/tests/pwsh.cordis.yml
+++ b/examples/acp-agent/tests/pwsh.cordis.yml
@@ -2,8 +2,6 @@
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
     models:
       - id: deepseek-v4-pro
 
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 624e9e37af..8afbd1d248 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -35,11 +35,6 @@
     # once the web UI owns the choice per session.
     mode: !!js process.env.DSH_TOOLS_MODE
 
-- id: llm-deepseek
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
-
 # ── web-only host rows, the transport layer, and the browser roster ─────────
 
 # `dshClient` rows are the browser roster the modules node half scans into
diff --git a/packages/client/ui-models/src/client/ModelsSection.tsx b/packages/client/ui-models/src/client/ModelsSection.tsx
index b5a2801bf5..3830710df1 100644
--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-models/src/client/ModelsSection.tsx
@@ -80,8 +80,8 @@ function renderProviderEditor({ target, ...props }: ProviderEditorRenderProps):
  * Remove one user-added provider and its page-managed credential. Credential
  * removal comes first so a second-step failure leaves the provider row visible
  * and the whole operation safely retryable; both unsets are idempotent.
- * The settings removal names the profile rather than rebuilding its redacted
- * namespace, which would drop literal secrets stored elsewhere.
+ * The settings removal names the profile rather than rebuilding its whole
+ * namespace from a partial view.
  * @param api - settings and credential wire faces.
  * @param controller - the page store to refresh.
  * @param target - the provider's settings address and optional managed credential.
@@ -112,16 +112,14 @@ export async function removeProviderProfile(
 }
 
 /**
- * Whether a whole-section provider still needs its first key: nothing marks
- * the credential configured and no literal `apiKey` is stored, so the page
- * opens the setup card instead of showing a row.
+ * Whether a whole-section provider still needs its first key: an unconfigured
+ * credential opens the setup card instead of showing a row.
  * @param row - the joined provider row.
  * @returns whether to render the setup card.
  */
 export function needsSetup(row: ProviderRow): boolean {
   if (row.entry.settingsPath.length > 0) return false
-  if (row.credential?.configured === true) return false
-  return !row.literalApiKeyConfigured
+  return row.credential?.configured !== true
 }
 
 function targetOf(row: ProviderRow): EditorTarget {
@@ -264,7 +262,7 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
             )
           }
           const open = !adding && editing?.provider === row.entry.provider
-          const credentialConfigured = row.literalApiKeyConfigured || row.credential?.configured === true
+          const credentialConfigured = row.credential?.configured === true
           const credentialMissing = !credentialConfigured
             && row.apiKeyEnv !== undefined
             && row.credential?.configured === false
diff --git a/packages/client/ui-models/src/client/ProviderEditor.tsx b/packages/client/ui-models/src/client/ProviderEditor.tsx
index e4cef56250..5020e024d5 100644
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -10,9 +10,8 @@
  * both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, and
  * DeepSeek's id/name/context-window model catalog). Everything else stays
  * owned by `settings.yaml`. Profile edits land as minimal `settings.mutate`
- * path ops against the stored section — the card reads the redacted
- * descriptor, so it names only the fields it can see and a stored literal
- * secret is never collaterally removed.
+ * path ops against the stored section — the card names only the fields it can
+ * see instead of rebuilding the whole subtree from a partial descriptor.
  */
 
 import { useEffect, useMemo, useState } from 'react'
@@ -80,10 +79,9 @@ function draftAt(namespace: SettingsNamespaceView, path: readonly string[]): Rec
 
 /**
  * The minimal path ops carrying `after` over `before`, both as the card sees
- * them (that is, redacted). Only keys the card observed are named: a stored
- * `role('secret')` field appears in neither side, so it produces no op and
- * survives the write — the whole reason edits are path-addressed rather than
- * a rebuilt section.
+ * them. Only keys the card observed are named; fields absent from both sides
+ * produce no op, which is why edits are path-addressed rather than a rebuilt
+ * section.
  * @param base - path of the edited subtree inside the user section.
  * @param before - the subtree as loaded, or undefined when it is new.
  * @param after - the subtree as edited.
@@ -205,9 +203,8 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
   /**
    * The write for this card, or a failure message. Every edit travels as
    * path ops against the STORED section: the draft comes from the redacted
-   * descriptor, so a wholesale replace rebuilt from it would delete the
-   * literal secrets the wire never returned. Ops name only the fields this
-   * card can see, so a stored secret is untouched by construction.
+   * descriptor, so a wholesale replace rebuilt from it could delete fields
+   * outside the card. Ops name only the fields this card can see.
    */
   const applyOnce = async (): Promise<string | undefined> => {
     const ns = namespace.ns
diff --git a/packages/client/ui-models/src/client/store.ts b/packages/client/ui-models/src/client/store.ts
index 938283b903..95db7e6787 100644
--- a/packages/client/ui-models/src/client/store.ts
+++ b/packages/client/ui-models/src/client/store.ts
@@ -31,8 +31,6 @@ export interface ProviderRow {
   apiKeyEnv: string | undefined
   /** Credential state for {@link apiKeyEnv}, once described. */
   credential: CredentialView | undefined
-  /** Whether the redacted secret sidecar reports an effective literal `apiKey`. */
-  literalApiKeyConfigured: boolean
 }
 
 /** Page snapshot. */
@@ -97,19 +95,6 @@ function apiKeyEnvOf(namespace: SettingsNamespaceView | undefined, path: readonl
   return typeof ref === 'string' && ref.length > 0 ? ref : undefined
 }
 
-/** Whether one namespace's redacted sidecar reports a set literal API key. */
-function literalApiKeyConfigured(
-  namespace: SettingsNamespaceView | undefined,
-  path: readonly string[],
-): boolean {
-  if (namespace === undefined) return false
-  const secretPath = [...path, 'apiKey']
-  return namespace.secrets.some(secret =>
-    secret.set
-    && secret.path.length === secretPath.length
-    && secret.path.every((key, index) => key === secretPath[index]))
-}
-
 /** The models settings page controller (one per settings surface). */
 export class ModelsSettingsStore {
   /** The snapshot the section renders from (uSES-safe store). */
@@ -170,7 +155,6 @@ export class ModelsSettingsStore {
         removable,
         apiKeyEnv: apiKeyEnvOf(namespace, entry.settingsPath),
         credential: undefined,
-        literalApiKeyConfigured: literalApiKeyConfigured(namespace, entry.settingsPath),
       }
     })
     const refs = [...new Set(rows.flatMap(row => row.apiKeyEnv === undefined ? [] : [row.apiKeyEnv]))]
@@ -257,7 +241,6 @@ export function deepSeekReadiness(state: ModelsSettingsState): DeepSeekReadiness
       reason: 'settings-unavailable',
     }
   }
-  if (row.literalApiKeyConfigured) return { kind: 'configured' }
   if (row.apiKeyEnv === undefined) {
     return {
       kind: 'unavailable',
diff --git a/packages/client/ui-models/tests/components.spec.tsx b/packages/client/ui-models/tests/components.spec.tsx
index 931410fb35..be798bd495 100644
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -35,9 +35,7 @@ function capacityInputs(label: string): HTMLInputElement[] {
 }
 
 const PiAiConfig = Schema.object({
-  token: Schema.string().role('secret'),
   providers: Schema.dict(Schema.object({
-    apiKey: Schema.string().role('secret'),
     apiKeyEnv: Schema.string().role('credential-ref'),
     baseURL: Schema.string(),
     reasoning: Schema.union(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']),
@@ -46,7 +44,6 @@ const PiAiConfig = Schema.object({
 })
 
 const DeepSeekConfig = Schema.object({
-  apiKey: Schema.string().role('secret'),
   apiKeyEnv: Schema.string().role('credential-ref'),
   baseURL: Schema.string().pattern(/^https:\/\//),
   reasoningEffort: Schema.union(['off', 'high', 'max']),
@@ -100,7 +97,7 @@ function wireNamespaces(): SettingsNamespaceView[] {
       base: { defaultContextWindow: 1_000_000, maxTokens: 256_000, models: DEFAULT_DEEPSEEK_MODELS },
       user: { reasoningEffort: 'high' },
       applies: 'live',
-      secrets: [{ path: ['apiKey'], set: false }],
+      secrets: [],
       revision: 0,
     },
     {
@@ -119,7 +116,7 @@ function wireNamespaces(): SettingsNamespaceView[] {
       value: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://proxy', headers: { 'X-Team': 'a' } }, zombie: {} } },
       user: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://proxy', headers: { 'X-Team': 'a' } }, zombie: {} } },
       applies: 'live',
-      secrets: [{ path: ['token'], set: false }, { path: ['providers', 'openai', 'apiKey'], set: false }],
+      secrets: [],
       revision: 0,
     },
   ]
@@ -263,22 +260,17 @@ describe('ModelsSection', () => {
     expect(screen.queryByLabelText(en.keyInput)).toBeNull()
   })
 
-  it('decides setup need from the joined credential state and literal-key sidecar', () => {
+  it('decides setup need from the joined credential state', () => {
     const entry = { provider: 'p', displayName: 'p', settingsNs: 'llm-deepseek', settingsPath: [], active: true }
-    const row = (
-      credential: ProviderRow['credential'],
-      literalApiKeyConfigured = false,
-    ): ProviderRow => ({
+    const row = (credential: ProviderRow['credential']): ProviderRow => ({
       entry,
       configured: true,
       removable: false,
       apiKeyEnv: 'X',
       credential,
-      literalApiKeyConfigured,
     })
     expect(needsSetup(row(undefined))).toBe(true)
     expect(needsSetup(row({ configured: true, writable: true }))).toBe(false)
-    expect(needsSetup(row(undefined, true))).toBe(false)
     const nested = { ...row(undefined), entry: { ...entry, settingsPath: ['providers', 'x'] } }
     expect(needsSetup(nested)).toBe(false)
   })
@@ -295,9 +287,7 @@ describe('ModelsSection', () => {
     expect(providerTargetLabel(OPENAI_TARGET)).toBe('openai')
   })
 
-  it('names only the fields the card can see, so an unseen secret survives', () => {
-    // `before` is the REDACTED subtree: a stored literal apiKey is in neither
-    // side, so no op mentions it and the seam leaves it alone.
+  it('names only changed fields instead of rebuilding the section', () => {
     expect(pathOps(['providers', 'openai'], { baseURL: 'https://old', reasoning: 'high' }, { reasoning: 'high' }))
       .toEqual([{ op: 'unset', path: ['providers', 'openai', 'baseURL'] }])
     expect(pathOps([], { b: 1 }, { b: 2, d: 3 }))
@@ -725,8 +715,7 @@ describe('ModelsSection', () => {
   })
 
   it('clears an inherited override with an unset op, never a whole-section replace', async () => {
-    // The data-loss shape: the old path rebuilt the section from the REDACTED
-    // user layer and replaced it wholesale, deleting any stored literal key.
+    // The old path rebuilt the whole user section to clear one inherited field.
     const { replace, update, mutate } = await mountSection()
     fireEvent.click(screen.getByText(en.customized))
     const effort = screen.getByLabelText<HTMLSelectElement>(en.effort)
@@ -800,9 +789,7 @@ describe('ModelsSection', () => {
     fireEvent.click(screen.getAllByText(en.apply)[1] as HTMLElement)
     await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
     // Only the edited field travels: apiKeyEnv, baseURL and headers were
-    // already stored with these values, so no op restates them — and the
-    // profile's stored literal apiKey, absent from the redacted view the card
-    // read, is named by nothing at all.
+    // already stored with these values, so no op restates them.
     expect(mutate.mock.calls[0]?.[0]).toEqual({
       ns: 'llm-pi-ai',
       ops: [{ op: 'set', path: ['providers', 'openai', 'reasoning'], value: 'xhigh' }],
@@ -1134,8 +1121,8 @@ describe('ModelsSection', () => {
   })
 
   it('removes by unsetting the profile path, never by rebuilding the section', async () => {
-    // The section rebuild is what dropped stored literal secrets: this page
-    // only ever holds the redacted descriptor, so the removal names the path.
+    // The page only needs to name the profile path; rebuilding the section
+    // would widen the write for no benefit.
     const { face, mutate, replace, controller } = await mountSection()
     await removeProviderProfile(
       face as unknown as Parameters<typeof removeProviderProfile>[0],
diff --git a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
index 07acc89fe4..772e14aaba 100644
--- a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
+++ b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
@@ -28,7 +28,6 @@ function harness(options: {
   providerActive?: boolean
   settingsNamespace?: boolean
   apiKeyEnv?: string | null
-  literal?: boolean
   configured?: () => boolean
   credential?: { source?: string; writable: boolean }
   describeFailure?: string
@@ -66,7 +65,7 @@ function harness(options: {
               ? {}
               : { apiKeyEnv: options.apiKeyEnv ?? 'DEEPSEEK_API_KEY' },
             applies: 'live' as const,
-            secrets: [{ path: ['apiKey'], set: options.literal === true }],
+            secrets: [],
             revision: 0,
           }],
       })),
@@ -153,11 +152,10 @@ describe('DeepSeekOnboardingDialog', () => {
     }
   })
 
-  it('skips an absent adapter and already-configured literal or environment credentials', async () => {
+  it('skips an absent adapter and an already-configured environment credential', async () => {
     for (const h of [
       harness({ provider: false }),
       harness({ providerSettingsNs: '' }),
-      harness({ literal: true, describeFailure: 'credential seam absent' }),
       harness({ configured: () => true, credential: { source: 'env', writable: false } }),
     ]) {
       const view = render(<DeepSeekOnboardingDialog {...h.props} />)
diff --git a/packages/client/ui-models/tests/readiness.spec.ts b/packages/client/ui-models/tests/readiness.spec.ts
index d03cd130f4..f01ab75930 100644
--- a/packages/client/ui-models/tests/readiness.spec.ts
+++ b/packages/client/ui-models/tests/readiness.spec.ts
@@ -19,7 +19,6 @@ function row(overrides: Partial<ProviderRow> = {}): ProviderRow {
     removable: false,
     apiKeyEnv: 'DEEPSEEK_API_KEY',
     credential: missingCredential,
-    literalApiKeyConfigured: false,
     ...overrides,
   }
 }
@@ -64,13 +63,6 @@ describe('deepSeekReadiness', () => {
     }))).toEqual({ kind: 'configured' })
   })
 
-  it('accepts the redacted literal-key sidecar before judging the credential domain', () => {
-    expect(deepSeekReadiness(state({
-      credentialError: 'credentials service absent',
-      rows: [row({ literalApiKeyConfigured: true, credential: undefined })],
-    }))).toEqual({ kind: 'configured' })
-  })
-
   it('turns missing capabilities and inconsistent descriptors into diagnostics', () => {
     expect(deepSeekReadiness(state({ status: 'error', error: 'settings down' }))).toEqual({
       kind: 'unavailable',
diff --git a/packages/client/ui-models/tests/store.spec.ts b/packages/client/ui-models/tests/store.spec.ts
index ee9aa2ddaf..5a1f340a0d 100644
--- a/packages/client/ui-models/tests/store.spec.ts
+++ b/packages/client/ui-models/tests/store.spec.ts
@@ -25,7 +25,7 @@ const NAMESPACES = [
     value: { apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://base' },
     base: { baseURL: 'https://base' },
     applies: 'live' as const,
-    secrets: [{ path: ['apiKey'], set: false }],
+    secrets: [],
     revision: 0,
   },
   {
@@ -85,7 +85,6 @@ describe('ModelsSettingsStore', () => {
       removable: false,
       apiKeyEnv: 'DEEPSEEK_API_KEY',
       credential: { configured: false, writable: true },
-      literalApiKeyConfigured: false,
     })
     expect(byProvider.get('openai')).toMatchObject({
       configured: true,
@@ -131,30 +130,6 @@ describe('ModelsSettingsStore', () => {
     expect(store.store.getSnapshot().credentialError).toBe('credential transport refusal')
   })
 
-  it('joins a configured literal key from the redacted secret sidecar', async () => {
-    const { face } = api({
-      describeSettings: () => Promise.resolve(ok({
-        writable: true,
-        hasDocument: false,
-        namespaces: [{
-          ...NAMESPACES[0],
-          secrets: [
-            { path: ['apiKey', 'nested'], set: true },
-            { path: ['different'], set: true },
-            { path: ['apiKey'], set: true },
-          ],
-        }] as never,
-      })),
-      providers: () => Promise.resolve(ok({ providers: [DIRECTORY[0]] as never })),
-    })
-    const store = new ModelsSettingsStore(face)
-    await store.load()
-    expect(store.store.getSnapshot().rows[0]).toMatchObject({
-      literalApiKeyConfigured: true,
-      apiKeyEnv: 'DEEPSEEK_API_KEY',
-    })
-  })
-
   it('surfaces a directory failure and keeps the last good rows', async () => {
     const { face } = api()
     const store = new ModelsSettingsStore(face)
diff --git a/packages/examples/acp-demo/tests/load-path.e2e.ts b/packages/examples/acp-demo/tests/load-path.e2e.ts
index 37b41cedd0..4719c161fe 100644
--- a/packages/examples/acp-demo/tests/load-path.e2e.ts
+++ b/packages/examples/acp-demo/tests/load-path.e2e.ts
@@ -33,8 +33,6 @@ const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.m
 const CORDIS_YML = `
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
 - id: subprocess
   name: '@deepseek-ai/dsh-subprocess-local'
 - id: bash
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index ae167329a1..dbf0eb83b4 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -871,8 +871,7 @@ describe('plugin registration and config', () => {
     await expect(ctx.llm.listModels('deepseek-official')).resolves.toHaveLength(2)
     const first = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
     expect(first.finish).toMatchObject({ kind: 'error', failure: { code: 'MISSING_CREDENTIAL' } })
-    // The guidance leads with the credential store — the path that keeps the
-    // secret out of configuration files — and mentions a literal key last.
+    // The guidance leads with the managed credential store.
     const second = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
     expect(second.finish.kind).toBe('error')
     if (second.finish.kind !== 'error') throw new Error('expected an error finish')
diff --git a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
index 57b588ba7b..99e57d10c4 100644
--- a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
@@ -78,23 +78,6 @@ describe('request-level dynamic configuration', () => {
     expect(serverB.headers[0]?.authorization).toBe('Bearer second-key')
   })
 
-  it('refuses a literal apiKey in settings and keeps serving the stored credential', async () => {
-    vi.stubEnv('DEEPSEEK_API_KEY', '')
-    const dir = await home()
-    await writeFile(join(dir, '.credentials.yaml'), 'DEEPSEEK_API_KEY: file-key\n', { mode: 0o600 })
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const { ctx } = await boot(dir, { baseURL: server.url })
-
-    // Configuration carries a reference, never a value. The namespace has no
-    // `apiKey` field, so writing one is dropped by the schema rather than
-    // rejected (no adapter namespace is strict); what matters is that a
-    // settings document cannot become a second credential store outranking
-    // `.credentials.yaml` and the environment.
-    await ctx.settings.update(NS, { apiKey: 'literal-key' })
-    await prompt(ctx)
-    expect(server.headers[0]?.authorization).toBe('Bearer file-key')
-  })
-
   it('starts keyless and serves the next request once the key arrives', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const dir = await home()
diff --git a/packages/sdk/create-sdk/tests/create.spec.ts b/packages/sdk/create-sdk/tests/create.spec.ts
index a099b38b23..6c2995ec7d 100644
--- a/packages/sdk/create-sdk/tests/create.spec.ts
+++ b/packages/sdk/create-sdk/tests/create.spec.ts
@@ -381,7 +381,7 @@ describe('CreateWizard and scaffolder', () => {
     }).run()
     await scaffoldProject(resolved.directory, resolved.request)
     expect(await readFile(join(resolved.directory, '.env'), 'utf8')).toBe(
-      '# Required before start; an empty value makes provider startup fail.\nDEEPSEEK_API_KEY=\n',
+      '# Required before the first model request.\nDEEPSEEK_API_KEY=\n',
     )
     expect(port.requests).toContain('Keep the API key empty and fill .env later?')
   })
diff --git a/packages/sdk/helper/src/features/builtin/provider.ts b/packages/sdk/helper/src/features/builtin/provider.ts
index 94ea8a9679..a72daff94b 100644
--- a/packages/sdk/helper/src/features/builtin/provider.ts
+++ b/packages/sdk/helper/src/features/builtin/provider.ts
@@ -4,7 +4,6 @@
  * @module @deepseek-ai/dsh-helper/features/builtin/provider
  */
 
-import { JsExpression } from '../../documents/cordis-yaml-file.ts'
 import { featureId } from '../../ids.ts'
 import type { FeatureSelection, ProjectProfile } from '../../project/types.ts'
 import {
@@ -17,7 +16,7 @@ import { npmCordisConfigEntry, environment } from './helpers.ts'
 
 const ID = featureId('provider')
 const DEFAULT_MODEL = 'deepseek-v4-flash'
-const API_KEY_COMMENT = 'Required before start; an empty value makes provider startup fail.'
+const API_KEY_COMMENT = 'Required before the first model request.'
 
 class DeepSeekOption extends FeatureOption {
   override readonly id = 'deepseek-official'
@@ -34,8 +33,7 @@ class DeepSeekOption extends FeatureOption {
       ...npmCordisConfigEntry(ID, {
         id: 'llm-deepseek',
         name: '@deepseek-ai/dsh-llm-deepseek',
-        config: { apiKey: new JsExpression('process.env.DEEPSEEK_API_KEY') },
-      }, ['apiKey', 'baseURL', 'models']),
+      }, ['baseURL', 'models']),
       environment(ID, 'DEEPSEEK_API_KEY', secrets.apiKey, API_KEY_COMMENT),
     ])
   }
@@ -60,8 +58,7 @@ class CustomOption extends FeatureOption {
       ...npmCordisConfigEntry(ID, {
         id: 'llm-pi-ai',
         name: '@deepseek-ai/dsh-llm-pi-ai',
-        config: { apiKey: new JsExpression('process.env.DEEPSEEK_API_KEY') },
-      }, ['apiKey', 'baseURL', 'models']),
+      }, ['baseURL', 'models']),
       environment(ID, 'DEEPSEEK_API_KEY', secrets.apiKey, API_KEY_COMMENT),
     ])
   }
diff --git a/packages/sdk/helper/tests/documents.spec.ts b/packages/sdk/helper/tests/documents.spec.ts
index 86e50ca8ad..e3ffe18b77 100644
--- a/packages/sdk/helper/tests/documents.spec.ts
+++ b/packages/sdk/helper/tests/documents.spec.ts
@@ -86,20 +86,20 @@ config:
     expect(flow.serialize()).not.toContain('{')
     const document = CordisYamlFile.parse(`# lead
 - id: provider
-  name: '@deepseek-ai/dsh-llm-deepseek'
+  name: 'provider-package'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    endpoint: !!js process.env.PROVIDER_URL
     custom: keep
 `)
-    const apiKey = document.entry('provider')?.config?.apiKey
-    expect(apiKey).toBeInstanceOf(JsExpression)
-    document.updateOwnedConfig('provider', ['apiKey'], { apiKey: new JsExpression('process.env.NEXT_KEY') })
+    const endpoint = document.entry('provider')?.config?.endpoint
+    expect(endpoint).toBeInstanceOf(JsExpression)
+    document.updateOwnedConfig('provider', ['endpoint'], { endpoint: new JsExpression('process.env.NEXT_URL') })
     document.setDisabled('provider', true)
     document.addEntry({ id: 'tool', name: 'demo-tool' })
     document.validate()
     const text = document.serialize()
     expect(text).toContain('# lead')
-    expect(text).toContain('!!js process.env.NEXT_KEY')
+    expect(text).toContain('!!js process.env.NEXT_URL')
     expect(text).toContain('custom: keep')
     expect(document.removeEntry('tool')).toBe(true)
     expect(document.removeEntry('tool')).toBe(false)
diff --git a/packages/sdk/helper/tests/project.spec.ts b/packages/sdk/helper/tests/project.spec.ts
index 20446216ab..d0f275ca4c 100644
--- a/packages/sdk/helper/tests/project.spec.ts
+++ b/packages/sdk/helper/tests/project.spec.ts
@@ -193,6 +193,7 @@ describe('SdkProject and ProjectEditSession', () => {
     expect(project.packageManifest().dependencies).not.toHaveProperty('@deepseek-ai/dsh-scope/invariant')
     expect(project.packageManifest().dependencies).not.toHaveProperty('node-addon-require-builtin')
     expect(project.cordis.entry('hmr')).toMatchObject({ name: '@cordisjs/plugin-hmr' })
+    expect(project.cordis.entry('llm-deepseek')).not.toHaveProperty('config.apiKey')
     expect(project.cordis.entry('llm-deepseek')?.config).not.toHaveProperty('baseURL')
     expect(project.cordis.entry('llm-deepseek')?.config).not.toHaveProperty('models')
   })
@@ -580,7 +581,7 @@ describe('SdkProject and ProjectEditSession', () => {
     await writeFile(join(partialRoot, 'cordis.yml'), `- id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    apiKey: test
+    apiKeyEnv: DEEPSEEK_API_KEY
 `)
     const partial = await SdkProject.open(partialRoot)
     const installation = createBuiltinRegistry(partial.profile)
diff --git a/packages/sdk/scripts/tests/scripts.spec.ts b/packages/sdk/scripts/tests/scripts.spec.ts
index 35df90ce98..6d2ea27991 100644
--- a/packages/sdk/scripts/tests/scripts.spec.ts
+++ b/packages/sdk/scripts/tests/scripts.spec.ts
@@ -535,7 +535,7 @@ describe('ConfigWorkflow', () => {
     ]), outputBuffer().stream, async () => {})
     const result = await workflow.run(project, registry)
     const provider = result.commit?.project.cordis.entry('llm-pi-ai')
-    expect(provider?.config?.apiKey).toBeDefined()
+    expect(provider?.config).not.toHaveProperty('apiKey')
     expect(provider?.config?.baseURL).toBe('https://provider.example/v1')
     expect(result.commit?.project.cordis.entry('acp')).toBeDefined()
     expect(result.commit?.project.cordis.entry('agent-loop')).toBeDefined()
diff --git a/packages/sdk/telemetry/tests/consent-resolver.spec.ts b/packages/sdk/telemetry/tests/consent-resolver.spec.ts
index ca0cec3bbd..05442bcc0f 100644
--- a/packages/sdk/telemetry/tests/consent-resolver.spec.ts
+++ b/packages/sdk/telemetry/tests/consent-resolver.spec.ts
@@ -77,7 +77,7 @@ describe('ConsentResolver cordis.yml state', () => {
       '- id: llm',
       '  name: \'@deepseek-ai/dsh-llm-deepseek\'',
       '  config:',
-      '    apiKey: !!js process.env.DEEPSEEK_API_KEY',
+      '    apiKeyEnv: DEEPSEEK_API_KEY',
       '',
     ].join('\n')
     expect(await resolver.resolve(await projectDir(yml)))

From 38c373af65923abcd8fff7c200f5a64ca93b617b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 22:41:09 +0800
Subject: [PATCH 164/516] fix(ci): keep issue policy test discovery focused

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 9698d0d2fa..81cb40acad 100644
--- a/package.json
+++ b/package.json
@@ -29,7 +29,7 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "test:issue-management": "node --test .github/issue-management/policy.test.mjs",
+    "test:issue-management": "node .github/issue-management/policy.test.mjs",
     "test:snapshot": "vitest run --config vitest.snapshot.config.ts",
     "test:snapshot:record": "DSH_SNAPSHOT=record vitest run --config vitest.snapshot.config.ts --update",
     "test:snapshot:refresh": "DSH_SNAPSHOT=refresh vitest run --config vitest.snapshot.config.ts",

From db0133b4c713d7e40f79e82db1e1480b997f27df Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 22:52:19 +0800
Subject: [PATCH 165/516] docs(notes): archive low-value records

---
 ...-native-typescript-source-launch.i18n.yaml |  6 ++
 ...-28-dsh-native-typescript-source-launch.md |  1 +
 ...-dsh-native-typescript-source-launch.zh.md |  1 +
 ...tion-composer-rows-do-not-shrink.i18n.yaml |  6 ++
 ...27-question-composer-rows-do-not-shrink.md |  1 +
 ...question-composer-rows-do-not-shrink.zh.md |  1 +
 ...28-web-conversation-polish-sweep.i18n.yaml |  6 ++
 ...026-07-28-web-conversation-polish-sweep.md |  1 +
 ...-07-28-web-conversation-polish-sweep.zh.md |  1 +
 ...07-30-web-details-default-closed.i18n.yaml |  6 ++
 .../2026-07-30-web-details-default-closed.md  |  1 +
 ...026-07-30-web-details-default-closed.zh.md |  1 +
 ...isible-while-blank-session-opens.i18n.yaml |  6 ++
 ...-hero-visible-while-blank-session-opens.md |  1 +
 ...ro-visible-while-blank-session-opens.zh.md |  1 +
 ...versation-column-one-axis-scroll.i18n.yaml |  6 ++
 ...-04-conversation-column-one-axis-scroll.md |  1 +
 ...-conversation-column-one-axis-scroll.zh.md |  5 +-
 .../2026-07-22-docked-web-goal-bar.i18n.yaml  |  6 ++
 .../feature/2026-07-22-docked-web-goal-bar.md |  1 +
 .../2026-07-22-docked-web-goal-bar.zh.md      |  1 +
 ...b-message-icon-actions-and-clock.i18n.yaml |  6 ++
 ...7-29-web-message-icon-actions-and-clock.md |  1 +
 ...9-web-message-icon-actions-and-clock.zh.md |  1 +
 .../2026-07-30-dsh-dump-config.i18n.yaml      |  6 ++
 .../feature/2026-07-30-dsh-dump-config.md     |  1 +
 .../feature/2026-07-30-dsh-dump-config.zh.md  |  1 +
 ...-composer-stats-and-input-polish.i18n.yaml |  6 ++
 ...-30-web-composer-stats-and-input-polish.md |  1 +
 ...-web-composer-stats-and-input-polish.zh.md |  1 +
 ...web-context-injection-disclosure.i18n.yaml |  6 ++
 ...-07-30-web-context-injection-disclosure.md |  1 +
 ...-30-web-context-injection-disclosure.zh.md |  1 +
 ...2026-07-31-hover-card-click-copy.i18n.yaml |  6 ++
 .../2026-07-31-hover-card-click-copy.md       |  1 +
 .../2026-07-31-hover-card-click-copy.zh.md    |  1 +
 .../2026-07-31-web-cards-toolrow.i18n.yaml    |  6 ++
 .../feature/2026-07-31-web-cards-toolrow.md   |  1 +
 .../2026-07-31-web-cards-toolrow.zh.md        |  1 +
 .agents/notes/archived/manifest.json          | 59 ++++++++++++++++++-
 ...6-06-20-generated-cordis-catalog.i18n.yaml |  6 ++
 .../2026-06-20-generated-cordis-catalog.md    |  1 +
 .../2026-06-20-generated-cordis-catalog.zh.md |  1 +
 ...ntsource-parser-for-deepseek-sse.i18n.yaml |  6 ++
 ...-26-eventsource-parser-for-deepseek-sse.md |  1 +
 ...-eventsource-parser-for-deepseek-sse.zh.md |  1 +
 ...ndown-for-tool-web-html-markdown.i18n.yaml |  6 ++
 ...-26-turndown-for-tool-web-html-markdown.md |  1 +
 ...-turndown-for-tool-web-html-markdown.zh.md |  1 +
 ...ebar-resize-without-visible-pill.i18n.yaml |  6 ++
 ...-30-sidebar-resize-without-visible-pill.md |  1 +
 ...-sidebar-resize-without-visible-pill.zh.md |  1 +
 ...eer-entry-or-interjection-chrome.i18n.yaml |  6 ++
 ...i-no-steer-entry-or-interjection-chrome.md |  1 +
 ...o-steer-entry-or-interjection-chrome.zh.md |  1 +
 ...eca-for-test-subprocess-plumbing.i18n.yaml |  6 ++
 ...7-26-execa-for-test-subprocess-plumbing.md |  1 +
 ...6-execa-for-test-subprocess-plumbing.zh.md |  1 +
 .../2026-06-13-twin-llm-adapters.i18n.yaml    |  4 +-
 .../2026-06-13-twin-llm-adapters.md           |  2 +-
 .../2026-06-13-twin-llm-adapters.zh.md        |  2 +-
 ...-native-typescript-source-launch.i18n.yaml |  6 --
 ...-07-29-dsh-source-launch-tsx-esm.i18n.yaml |  4 +-
 .../2026-07-29-dsh-source-launch-tsx-esm.md   |  4 +-
 ...2026-07-29-dsh-source-launch-tsx-esm.zh.md |  4 +-
 ...30-session-end-seed-log-boundary.i18n.yaml |  4 +-
 ...026-07-30-session-end-seed-log-boundary.md |  2 +-
 ...-07-30-session-end-seed-log-boundary.zh.md |  2 +-
 ...tion-composer-rows-do-not-shrink.i18n.yaml |  6 --
 ...28-web-conversation-polish-sweep.i18n.yaml |  6 --
 ...29-web-details-session-lifecycle.i18n.yaml |  4 +-
 ...026-07-29-web-details-session-lifecycle.md |  2 +-
 ...-07-29-web-details-session-lifecycle.zh.md |  2 +-
 ...07-30-web-details-default-closed.i18n.yaml |  6 --
 ...isible-while-blank-session-opens.i18n.yaml |  6 --
 ...versation-column-one-axis-scroll.i18n.yaml |  6 --
 ...actions-require-a-completed-turn.i18n.yaml |  4 +-
 ...n-tail-actions-require-a-completed-turn.md |  2 +-
 ...ail-actions-require-a-completed-turn.zh.md |  2 +-
 ...26-07-20-dsh-cli-personal-config.i18n.yaml |  4 +-
 .../2026-07-20-dsh-cli-personal-config.md     |  2 +-
 .../2026-07-20-dsh-cli-personal-config.zh.md  |  2 +-
 .../2026-07-22-docked-web-goal-bar.i18n.yaml  |  6 --
 ...b-message-icon-actions-and-clock.i18n.yaml |  6 --
 .../2026-07-30-dsh-dump-config.i18n.yaml      |  6 --
 ...-composer-stats-and-input-polish.i18n.yaml |  6 --
 ...web-context-injection-disclosure.i18n.yaml |  6 --
 ...2026-07-31-hover-card-click-copy.i18n.yaml |  6 --
 .../2026-07-31-web-cards-toolrow.i18n.yaml    |  6 --
 ...b-context-source-and-steer-marks.i18n.yaml |  4 +-
 ...8-04-web-context-source-and-steer-marks.md |  4 +-
 ...4-web-context-source-and-steer-marks.zh.md |  4 +-
 ...-20-core-data-structures-catalog.i18n.yaml |  4 +-
 ...2026-06-20-core-data-structures-catalog.md |  4 +-
 ...6-06-20-core-data-structures-catalog.zh.md |  4 +-
 ...6-06-20-generated-cordis-catalog.i18n.yaml |  6 --
 ...ntsource-parser-for-deepseek-sse.i18n.yaml |  6 --
 ...ndown-for-tool-web-html-markdown.i18n.yaml |  6 --
 ...ebar-resize-without-visible-pill.i18n.yaml |  6 --
 ...eer-entry-or-interjection-chrome.i18n.yaml |  6 --
 ...3-explicit-config-dsh-entrypoint.i18n.yaml |  4 +-
 ...26-08-03-explicit-config-dsh-entrypoint.md |  2 +-
 ...08-03-explicit-config-dsh-entrypoint.zh.md |  2 +-
 ...eca-for-test-subprocess-plumbing.i18n.yaml |  6 --
 ...-29-session-resumed-log-boundary.i18n.yaml |  6 --
 ...2026-07-29-session-resumed-log-boundary.md | 51 ----------------
 ...6-07-29-session-resumed-log-boundary.zh.md | 51 ----------------
 ...nimplemented-subagent-vocabulary.i18n.yaml |  6 --
 ...prune-unimplemented-subagent-vocabulary.md | 39 ------------
 ...ne-unimplemented-subagent-vocabulary.zh.md | 39 ------------
 ...ency-swaps-rejected-by-nih-audit.i18n.yaml |  4 +-
 ...-dependency-swaps-rejected-by-nih-audit.md |  4 +-
 ...pendency-swaps-rejected-by-nih-audit.zh.md |  4 +-
 .../client/ui-conversation/README.i18n.yaml   |  4 +-
 packages/client/ui-conversation/README.md     |  2 +-
 packages/client/ui-conversation/README.zh.md  |  2 +-
 .../client/ui-primitives/README.i18n.yaml     |  4 +-
 packages/client/ui-primitives/README.md       |  2 +-
 packages/client/ui-primitives/README.zh.md    |  2 +-
 packages/web/tool-web/README.i18n.yaml        |  4 +-
 packages/web/tool-web/README.md               |  2 +-
 packages/web/tool-web/README.zh.md            |  2 +-
 122 files changed, 272 insertions(+), 369 deletions(-)
 create mode 100644 .agents/notes/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.i18n.yaml
 rename .agents/notes/{implemented => archived}/architecture/2026-07-28-dsh-native-typescript-source-launch.md (99%)
 rename .agents/notes/{implemented => archived}/architecture/2026-07-28-dsh-native-typescript-source-launch.zh.md (99%)
 create mode 100644 .agents/notes/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.i18n.yaml
 rename .agents/notes/{implemented => archived}/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md (99%)
 rename .agents/notes/{implemented => archived}/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.zh.md (99%)
 create mode 100644 .agents/notes/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.i18n.yaml
 rename .agents/notes/{implemented => archived}/bug-fix/2026-07-28-web-conversation-polish-sweep.md (99%)
 rename .agents/notes/{implemented => archived}/bug-fix/2026-07-28-web-conversation-polish-sweep.zh.md (99%)
 create mode 100644 .agents/notes/archived/bug-fix/2026-07-30-web-details-default-closed.i18n.yaml
 rename .agents/notes/{implemented => archived}/bug-fix/2026-07-30-web-details-default-closed.md (99%)
 rename .agents/notes/{implemented => archived}/bug-fix/2026-07-30-web-details-default-closed.zh.md (99%)
 create mode 100644 .agents/notes/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml
 rename .agents/notes/{implemented => archived}/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md (99%)
 rename .agents/notes/{implemented => archived}/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md (99%)
 create mode 100644 .agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
 rename .agents/notes/{implemented => archived}/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md (99%)
 rename .agents/notes/{implemented => archived}/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md (97%)
 create mode 100644 .agents/notes/archived/feature/2026-07-22-docked-web-goal-bar.i18n.yaml
 rename .agents/notes/{implemented => archived}/feature/2026-07-22-docked-web-goal-bar.md (99%)
 rename .agents/notes/{implemented => archived}/feature/2026-07-22-docked-web-goal-bar.zh.md (99%)
 create mode 100644 .agents/notes/archived/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml
 rename .agents/notes/{implemented => archived}/feature/2026-07-29-web-message-icon-actions-and-clock.md (99%)
 rename .agents/notes/{implemented => archived}/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md (99%)
 create mode 100644 .agents/notes/archived/feature/2026-07-30-dsh-dump-config.i18n.yaml
 rename .agents/notes/{implemented => archived}/feature/2026-07-30-dsh-dump-config.md (99%)
 rename .agents/notes/{implemented => archived}/feature/2026-07-30-dsh-dump-config.zh.md (99%)
 create mode 100644 .agents/notes/archived/feature/2026-07-30-web-composer-stats-and-input-polish.i18n.yaml
 rename .agents/notes/{implemented => archived}/feature/2026-07-30-web-composer-stats-and-input-polish.md (99%)
 rename .agents/notes/{implemented => archived}/feature/2026-07-30-web-composer-stats-and-input-polish.zh.md (99%)
 create mode 100644 .agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.i18n.yaml
 rename .agents/notes/{implemented => archived}/feature/2026-07-30-web-context-injection-disclosure.md (99%)
 rename .agents/notes/{implemented => archived}/feature/2026-07-30-web-context-injection-disclosure.zh.md (99%)
 create mode 100644 .agents/notes/archived/feature/2026-07-31-hover-card-click-copy.i18n.yaml
 rename .agents/notes/{implemented => archived}/feature/2026-07-31-hover-card-click-copy.md (99%)
 rename .agents/notes/{implemented => archived}/feature/2026-07-31-hover-card-click-copy.zh.md (99%)
 create mode 100644 .agents/notes/archived/feature/2026-07-31-web-cards-toolrow.i18n.yaml
 rename .agents/notes/{implemented => archived}/feature/2026-07-31-web-cards-toolrow.md (99%)
 rename .agents/notes/{implemented => archived}/feature/2026-07-31-web-cards-toolrow.zh.md (99%)
 create mode 100644 .agents/notes/archived/process/2026-06-20-generated-cordis-catalog.i18n.yaml
 rename .agents/notes/{implemented => archived}/process/2026-06-20-generated-cordis-catalog.md (99%)
 rename .agents/notes/{implemented => archived}/process/2026-06-20-generated-cordis-catalog.zh.md (99%)
 create mode 100644 .agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.i18n.yaml
 rename .agents/notes/{implemented => archived}/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md (99%)
 rename .agents/notes/{implemented => archived}/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.zh.md (99%)
 create mode 100644 .agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.i18n.yaml
 rename .agents/notes/{implemented => archived}/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md (99%)
 rename .agents/notes/{implemented => archived}/simplification/2026-07-26-turndown-for-tool-web-html-markdown.zh.md (99%)
 create mode 100644 .agents/notes/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.i18n.yaml
 rename .agents/notes/{implemented => archived}/simplification/2026-07-30-sidebar-resize-without-visible-pill.md (98%)
 rename .agents/notes/{implemented => archived}/simplification/2026-07-30-sidebar-resize-without-visible-pill.zh.md (98%)
 create mode 100644 .agents/notes/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml
 rename .agents/notes/{implemented => archived}/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md (99%)
 rename .agents/notes/{implemented => archived}/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md (99%)
 create mode 100644 .agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml
 rename .agents/notes/{implemented => archived}/testing/2026-07-26-execa-for-test-subprocess-plumbing.md (99%)
 rename .agents/notes/{implemented => archived}/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md (99%)
 delete mode 100644 .agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.i18n.yaml
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.i18n.yaml
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.i18n.yaml
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.i18n.yaml
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-30-dsh-dump-config.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-30-web-composer-stats-and-input-polish.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-31-web-cards-toolrow.i18n.yaml
 delete mode 100644 .agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.i18n.yaml
 delete mode 100644 .agents/notes/implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.i18n.yaml
 delete mode 100644 .agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.i18n.yaml
 delete mode 100644 .agents/notes/implemented/simplification/2026-07-30-sidebar-resize-without-visible-pill.i18n.yaml
 delete mode 100644 .agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml
 delete mode 100644 .agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml
 delete mode 100644 .agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.i18n.yaml
 delete mode 100644 .agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.md
 delete mode 100644 .agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.zh.md
 delete mode 100644 .agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.i18n.yaml
 delete mode 100644 .agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.md
 delete mode 100644 .agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.zh.md

diff --git a/.agents/notes/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.i18n.yaml b/.agents/notes/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.i18n.yaml
new file mode 100644
index 0000000000..c0fcdd30f9
--- /dev/null
+++ b/.agents/notes/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.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/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md
+2026-07-28-dsh-native-typescript-source-launch.md: b5e8ed2a18bb0cbb3ab54cf5ed4a427efaa9dfeb
+2026-07-28-dsh-native-typescript-source-launch.zh.md: 05a4f92d2d3be553bb9ca363bf08e3ebf8e3f5b8
diff --git a/.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.md b/.agents/notes/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md
similarity index 99%
rename from .agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.md
rename to .agents/notes/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md
index 773f831ec2..b5e8ed2a18 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.md
+++ b/.agents/notes/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md
@@ -1,6 +1,7 @@
 # Agent Note: Native TypeScript source launch for dsh
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-28-dsh-native-typescript-source-launch.zh.md)
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.zh.md b/.agents/notes/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.zh.md
similarity index 99%
rename from .agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.zh.md
rename to .agents/notes/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.zh.md
index 0e40a7e32b..05a4f92d2d 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.zh.md
+++ b/.agents/notes/archived/architecture/2026-07-28-dsh-native-typescript-source-launch.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: dsh 原生 TypeScript 源码启动
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-28-dsh-native-typescript-source-launch.md) | 中文
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.i18n.yaml b/.agents/notes/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.i18n.yaml
new file mode 100644
index 0000000000..3520cf4974
--- /dev/null
+++ b/.agents/notes/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.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/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md
+2026-07-27-question-composer-rows-do-not-shrink.md: 47e581a23caaeb9368b075fa84a01d2bc945ab46
+2026-07-27-question-composer-rows-do-not-shrink.zh.md: a1b72cab41c51c268540dcec60e85a0edf2fe9bc
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md b/.agents/notes/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md
similarity index 99%
rename from .agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md
rename to .agents/notes/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md
index 2e0e9b9ca6..47e581a23c 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md
+++ b/.agents/notes/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md
@@ -1,6 +1,7 @@
 # Agent Note: Question-composer option rows are scroll content, not the slack absorber
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-27-question-composer-rows-do-not-shrink.zh.md)
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.zh.md b/.agents/notes/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.zh.md
similarity index 99%
rename from .agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.zh.md
rename to .agents/notes/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.zh.md
index 73e3e7614c..a1b72cab41 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.zh.md
+++ b/.agents/notes/archived/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 提问 composer 的选项行是滚动内容，而非空间不足时的吸收方
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-27-question-composer-rows-do-not-shrink.md) | 中文
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.i18n.yaml b/.agents/notes/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.i18n.yaml
new file mode 100644
index 0000000000..e77beba866
--- /dev/null
+++ b/.agents/notes/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.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/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.md
+2026-07-28-web-conversation-polish-sweep.md: 338b687c041c585c1d490fdad9b8bbcf88fc3912
+2026-07-28-web-conversation-polish-sweep.zh.md: 166662070b67837b9f4755e6457578f74af771ed
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.md b/.agents/notes/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.md
similarity index 99%
rename from .agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.md
rename to .agents/notes/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.md
index cae52217d6..338b687c04 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.md
+++ b/.agents/notes/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.md
@@ -1,6 +1,7 @@
 # Agent Note: Web conversation UI polish sweep
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-28-web-conversation-polish-sweep.zh.md)
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.zh.md b/.agents/notes/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.zh.md
similarity index 99%
rename from .agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.zh.md
rename to .agents/notes/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.zh.md
index 0f352f066d..166662070b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.zh.md
+++ b/.agents/notes/archived/bug-fix/2026-07-28-web-conversation-polish-sweep.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: Web 对话 UI 视觉优化
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-28-web-conversation-polish-sweep.md) | 中文
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-30-web-details-default-closed.i18n.yaml b/.agents/notes/archived/bug-fix/2026-07-30-web-details-default-closed.i18n.yaml
new file mode 100644
index 0000000000..286ed2a62e
--- /dev/null
+++ b/.agents/notes/archived/bug-fix/2026-07-30-web-details-default-closed.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/archived/bug-fix/2026-07-30-web-details-default-closed.md
+2026-07-30-web-details-default-closed.md: e4271917b998c9a916d8c67b30627022587547b8
+2026-07-30-web-details-default-closed.zh.md: 3b9432067c944ea604e039ee1b305a927a1c206e
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.md b/.agents/notes/archived/bug-fix/2026-07-30-web-details-default-closed.md
similarity index 99%
rename from .agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.md
rename to .agents/notes/archived/bug-fix/2026-07-30-web-details-default-closed.md
index 658b6fc2c1..e4271917b9 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.md
+++ b/.agents/notes/archived/bug-fix/2026-07-30-web-details-default-closed.md
@@ -1,6 +1,7 @@
 # Agent Note: Web details default closed
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-30-web-details-default-closed.zh.md)
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.zh.md b/.agents/notes/archived/bug-fix/2026-07-30-web-details-default-closed.zh.md
similarity index 99%
rename from .agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.zh.md
rename to .agents/notes/archived/bug-fix/2026-07-30-web-details-default-closed.zh.md
index 5a1d0e4713..3b9432067c 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.zh.md
+++ b/.agents/notes/archived/bug-fix/2026-07-30-web-details-default-closed.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: Web 详情栏默认关闭
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-30-web-details-default-closed.md) | 中文
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml b/.agents/notes/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml
new file mode 100644
index 0000000000..0cc1847c1a
--- /dev/null
+++ b/.agents/notes/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.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/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md
+2026-07-31-hero-visible-while-blank-session-opens.md: 1b1f35d82731675978585d718e4ef837f0c78aa5
+2026-07-31-hero-visible-while-blank-session-opens.zh.md: 91c1a372ebc6341632820450d9e54d58c9d36916
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md b/.agents/notes/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md
similarity index 99%
rename from .agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md
rename to .agents/notes/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md
index 6afa5d0ee2..1b1f35d827 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md
+++ b/.agents/notes/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md
@@ -1,6 +1,7 @@
 # Agent Note: Hero stays visible while a blank session opens
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-31-hero-visible-while-blank-session-opens.zh.md)
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md b/.agents/notes/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md
similarity index 99%
rename from .agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md
rename to .agents/notes/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md
index f21e549b58..91c1a372eb 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md
+++ b/.agents/notes/archived/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 空白会话打开期间保持 hero 可见
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-31-hero-visible-while-blank-session-opens.md) | 中文
 
diff --git a/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml b/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
new file mode 100644
index 0000000000..cb05519fde
--- /dev/null
+++ b/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.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/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
+2026-08-04-conversation-column-one-axis-scroll.md: e8f80c23a2ac2230079802fb6c85fec6c8b8e807
+2026-08-04-conversation-column-one-axis-scroll.zh.md: a7378b2d5ec026d6a054a080347b155cc476a57a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md b/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
similarity index 99%
rename from .agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
rename to .agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
index 9a487c506a..e8f80c23a2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
+++ b/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
@@ -1,6 +1,7 @@
 # Agent Note: The conversation column scrolls on one axis
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-08-04-conversation-column-one-axis-scroll.zh.md)
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md b/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
similarity index 97%
rename from .agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
rename to .agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
index 23441a7c86..a7378b2d5e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
+++ b/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
@@ -1,6 +1,7 @@
-# Agent Note：会话列只在一个轴上滚动
+# Agent Note: 会话列只在一个轴上滚动
 
-状态：已实现
+Status: implemented
+Archived: 2026-08-07
 
 [English](2026-08-04-conversation-column-one-axis-scroll.md) | 中文
 
diff --git a/.agents/notes/archived/feature/2026-07-22-docked-web-goal-bar.i18n.yaml b/.agents/notes/archived/feature/2026-07-22-docked-web-goal-bar.i18n.yaml
new file mode 100644
index 0000000000..535a0a8ff3
--- /dev/null
+++ b/.agents/notes/archived/feature/2026-07-22-docked-web-goal-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/archived/feature/2026-07-22-docked-web-goal-bar.md
+2026-07-22-docked-web-goal-bar.md: decf40996b51a0f2358a943bbb928f00d4db2026
+2026-07-22-docked-web-goal-bar.zh.md: 8ebb106b260a6107084c07b51b1763adb1df2da8
diff --git a/.agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.md b/.agents/notes/archived/feature/2026-07-22-docked-web-goal-bar.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.md
rename to .agents/notes/archived/feature/2026-07-22-docked-web-goal-bar.md
index ffddef6cec..decf40996b 100644
--- a/.agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.md
+++ b/.agents/notes/archived/feature/2026-07-22-docked-web-goal-bar.md
@@ -1,6 +1,7 @@
 # Agent Note: Docked web goal bar
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-22-docked-web-goal-bar.zh.md)
 
diff --git a/.agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.zh.md b/.agents/notes/archived/feature/2026-07-22-docked-web-goal-bar.zh.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.zh.md
rename to .agents/notes/archived/feature/2026-07-22-docked-web-goal-bar.zh.md
index b732f71cfc..8ebb106b26 100644
--- a/.agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.zh.md
+++ b/.agents/notes/archived/feature/2026-07-22-docked-web-goal-bar.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 停靠式 Web 目标条
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-22-docked-web-goal-bar.md) | 中文
 
diff --git a/.agents/notes/archived/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml b/.agents/notes/archived/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml
new file mode 100644
index 0000000000..47400cc87e
--- /dev/null
+++ b/.agents/notes/archived/feature/2026-07-29-web-message-icon-actions-and-clock.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/archived/feature/2026-07-29-web-message-icon-actions-and-clock.md
+2026-07-29-web-message-icon-actions-and-clock.md: a95c7d33a917026c882f17d30264cf9ec743dee5
+2026-07-29-web-message-icon-actions-and-clock.zh.md: b64c14aaa7056e19ccc4d512db3d24714e11a309
diff --git a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.md b/.agents/notes/archived/feature/2026-07-29-web-message-icon-actions-and-clock.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.md
rename to .agents/notes/archived/feature/2026-07-29-web-message-icon-actions-and-clock.md
index feced6aeb1..a95c7d33a9 100644
--- a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.md
+++ b/.agents/notes/archived/feature/2026-07-29-web-message-icon-actions-and-clock.md
@@ -1,6 +1,7 @@
 # Agent Note: Web message IconActions and clocks
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-29-web-message-icon-actions-and-clock.zh.md)
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md b/.agents/notes/archived/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md
rename to .agents/notes/archived/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md
index 5e33182421..b64c14aaa7 100644
--- a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md
+++ b/.agents/notes/archived/feature/2026-07-29-web-message-icon-actions-and-clock.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: Web 消息 IconActions 与时钟
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-29-web-message-icon-actions-and-clock.md) | 中文
 
diff --git a/.agents/notes/archived/feature/2026-07-30-dsh-dump-config.i18n.yaml b/.agents/notes/archived/feature/2026-07-30-dsh-dump-config.i18n.yaml
new file mode 100644
index 0000000000..1e8be61bca
--- /dev/null
+++ b/.agents/notes/archived/feature/2026-07-30-dsh-dump-config.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/archived/feature/2026-07-30-dsh-dump-config.md
+2026-07-30-dsh-dump-config.md: cc16f11d79b536a661d67811c6fd50705f6009e3
+2026-07-30-dsh-dump-config.zh.md: 185a2b8f37cef102b48d4dea1b3ed0a96958d220
diff --git a/.agents/notes/implemented/feature/2026-07-30-dsh-dump-config.md b/.agents/notes/archived/feature/2026-07-30-dsh-dump-config.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-30-dsh-dump-config.md
rename to .agents/notes/archived/feature/2026-07-30-dsh-dump-config.md
index bc6504541c..cc16f11d79 100644
--- a/.agents/notes/implemented/feature/2026-07-30-dsh-dump-config.md
+++ b/.agents/notes/archived/feature/2026-07-30-dsh-dump-config.md
@@ -1,6 +1,7 @@
 # Agent Note: dsh --dump-config prints the composed config tree
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-30-dsh-dump-config.zh.md)
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-dsh-dump-config.zh.md b/.agents/notes/archived/feature/2026-07-30-dsh-dump-config.zh.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-30-dsh-dump-config.zh.md
rename to .agents/notes/archived/feature/2026-07-30-dsh-dump-config.zh.md
index 5e173305a6..185a2b8f37 100644
--- a/.agents/notes/implemented/feature/2026-07-30-dsh-dump-config.zh.md
+++ b/.agents/notes/archived/feature/2026-07-30-dsh-dump-config.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: dsh --dump-config 打印合成后的配置树
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-30-dsh-dump-config.md) | 中文
 
diff --git a/.agents/notes/archived/feature/2026-07-30-web-composer-stats-and-input-polish.i18n.yaml b/.agents/notes/archived/feature/2026-07-30-web-composer-stats-and-input-polish.i18n.yaml
new file mode 100644
index 0000000000..5105501452
--- /dev/null
+++ b/.agents/notes/archived/feature/2026-07-30-web-composer-stats-and-input-polish.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/archived/feature/2026-07-30-web-composer-stats-and-input-polish.md
+2026-07-30-web-composer-stats-and-input-polish.md: 3c80b74c564a1779c69ef525f8d1f194e8915f6b
+2026-07-30-web-composer-stats-and-input-polish.zh.md: eabb174e78f3171997b9103650c7fe326793ce1b
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-composer-stats-and-input-polish.md b/.agents/notes/archived/feature/2026-07-30-web-composer-stats-and-input-polish.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-30-web-composer-stats-and-input-polish.md
rename to .agents/notes/archived/feature/2026-07-30-web-composer-stats-and-input-polish.md
index 78f286cb0e..3c80b74c56 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-composer-stats-and-input-polish.md
+++ b/.agents/notes/archived/feature/2026-07-30-web-composer-stats-and-input-polish.md
@@ -1,6 +1,7 @@
 # Agent Note: Web composer stats detail and input-zone polish
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-30-web-composer-stats-and-input-polish.zh.md)
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-composer-stats-and-input-polish.zh.md b/.agents/notes/archived/feature/2026-07-30-web-composer-stats-and-input-polish.zh.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-30-web-composer-stats-and-input-polish.zh.md
rename to .agents/notes/archived/feature/2026-07-30-web-composer-stats-and-input-polish.zh.md
index eeba56d9f3..eabb174e78 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-composer-stats-and-input-polish.zh.md
+++ b/.agents/notes/archived/feature/2026-07-30-web-composer-stats-and-input-polish.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: Web composer stats detail and input-zone polish
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-30-web-composer-stats-and-input-polish.md) | 中文
 
diff --git a/.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.i18n.yaml b/.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.i18n.yaml
new file mode 100644
index 0000000000..09f2268a0f
--- /dev/null
+++ b/.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.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/archived/feature/2026-07-30-web-context-injection-disclosure.md
+2026-07-30-web-context-injection-disclosure.md: e9551cacdcd5b3e45ba35eeb76db6c70e5bbe368
+2026-07-30-web-context-injection-disclosure.zh.md: a4937ba880df30b911f7c8a1eceaab7e2bb74026
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md b/.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md
rename to .agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md
index 84c3259f3f..e9551cacdc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md
+++ b/.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md
@@ -1,6 +1,7 @@
 # Agent Note: Web context injection disclosure
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-30-web-context-injection-disclosure.zh.md)
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.zh.md b/.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.zh.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.zh.md
rename to .agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.zh.md
index 4d77e06e27..a4937ba880 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.zh.md
+++ b/.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: Web 上下文注入展开项
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-30-web-context-injection-disclosure.md) | 中文
 
diff --git a/.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.i18n.yaml b/.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.i18n.yaml
new file mode 100644
index 0000000000..d0bc2ac45e
--- /dev/null
+++ b/.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.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/archived/feature/2026-07-31-hover-card-click-copy.md
+2026-07-31-hover-card-click-copy.md: 906f64129ee9ba767859260a3288faada21ea4de
+2026-07-31-hover-card-click-copy.zh.md: 0359b2edacde9e048db900d315b6a7befd361075
diff --git a/.agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.md b/.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.md
rename to .agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md
index c87734fe32..906f64129e 100644
--- a/.agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.md
+++ b/.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md
@@ -1,6 +1,7 @@
 # Agent Note: Hover cards copy their primary value on activation
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-31-hover-card-click-copy.zh.md)
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.zh.md b/.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.zh.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.zh.md
rename to .agents/notes/archived/feature/2026-07-31-hover-card-click-copy.zh.md
index 2d3bc893dd..0359b2edac 100644
--- a/.agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.zh.md
+++ b/.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 悬浮卡片激活时复制主要值
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-31-hover-card-click-copy.md) | 中文
 
diff --git a/.agents/notes/archived/feature/2026-07-31-web-cards-toolrow.i18n.yaml b/.agents/notes/archived/feature/2026-07-31-web-cards-toolrow.i18n.yaml
new file mode 100644
index 0000000000..fcd4878180
--- /dev/null
+++ b/.agents/notes/archived/feature/2026-07-31-web-cards-toolrow.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/archived/feature/2026-07-31-web-cards-toolrow.md
+2026-07-31-web-cards-toolrow.md: 9bdf5d4e8917178ec27ea5f5d24af753c0d10eab
+2026-07-31-web-cards-toolrow.zh.md: ce473a8a34ba8b1bb022d681244508c56a1084f3
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-cards-toolrow.md b/.agents/notes/archived/feature/2026-07-31-web-cards-toolrow.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-31-web-cards-toolrow.md
rename to .agents/notes/archived/feature/2026-07-31-web-cards-toolrow.md
index caa18563a9..9bdf5d4e89 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-cards-toolrow.md
+++ b/.agents/notes/archived/feature/2026-07-31-web-cards-toolrow.md
@@ -1,6 +1,7 @@
 # Agent Note: Card tool rows collapse through one ToolRow
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-31-web-cards-toolrow.zh.md)
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-cards-toolrow.zh.md b/.agents/notes/archived/feature/2026-07-31-web-cards-toolrow.zh.md
similarity index 99%
rename from .agents/notes/implemented/feature/2026-07-31-web-cards-toolrow.zh.md
rename to .agents/notes/archived/feature/2026-07-31-web-cards-toolrow.zh.md
index 7eb53a163f..ce473a8a34 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-cards-toolrow.zh.md
+++ b/.agents/notes/archived/feature/2026-07-31-web-cards-toolrow.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 卡片工具行通过同一个 ToolRow 折叠
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-31-web-cards-toolrow.md) | 中文
 
diff --git a/.agents/notes/archived/manifest.json b/.agents/notes/archived/manifest.json
index c5c0ce85a7..6fa5f06ceb 100644
--- a/.agents/notes/archived/manifest.json
+++ b/.agents/notes/archived/manifest.json
@@ -40,6 +40,9 @@
     "architecture/2026-07-28-consolidated-tui-presentation.i18n.yaml": "sha256:1eb43c420a21b7a3adf0aa5274d9aa597187630a29d7e535c5e266f82e803665",
     "architecture/2026-07-28-consolidated-tui-presentation.md": "sha256:e6fa4ea0c9d1d94942ab98de47c554f4e8aa3b639a1cce52113107b1dbb0f4b0",
     "architecture/2026-07-28-consolidated-tui-presentation.zh.md": "sha256:01814434482a84ebd7f672eb5c26fc468b568e773452563bf39ba52ad25d054a",
+    "architecture/2026-07-28-dsh-native-typescript-source-launch.i18n.yaml": "sha256:af071e07bce5d9bc8f3df65fed9dcd9b3779a98c5864badbd530363bda021b55",
+    "architecture/2026-07-28-dsh-native-typescript-source-launch.md": "sha256:1b56e3454277ace713e2a01c4da538c756c45bf633fd24d7b16443d584afac5d",
+    "architecture/2026-07-28-dsh-native-typescript-source-launch.zh.md": "sha256:8c0f97472c2c89d2c19ae5cfa68c6e67f32b50960b08b60b46496f78ea6ffad1",
     "bug-fix/2026-07-20-code-mode-result-card-completeness.i18n.yaml": "sha256:1035dae11d049d32ab09fd7d4f950eceae44bf46ba498b3cfaf3c75102b9fb64",
     "bug-fix/2026-07-20-code-mode-result-card-completeness.md": "sha256:6ca2c9d4df98be18813ef38b7462db880900b5bcd6944fbcd1b8f2258006b93e",
     "bug-fix/2026-07-20-code-mode-result-card-completeness.zh.md": "sha256:ed85fa7f935e5f525d566bc37a92014614983e649c75de9a9f244939097a7991",
@@ -61,6 +64,9 @@
     "bug-fix/2026-07-26-intent-draft-same-tick-echo.i18n.yaml": "sha256:c623947c4fa00e6d4b51792c7972ba09582bbcb7605beb373725c0dd666f2c81",
     "bug-fix/2026-07-26-intent-draft-same-tick-echo.md": "sha256:fa8b1417b2cdd3deecbf8e55bdddd73dd3a8c6e3486fd399b0b8bdf317e56373",
     "bug-fix/2026-07-26-intent-draft-same-tick-echo.zh.md": "sha256:00ce72552dbaa11562fbc541343a5d33f9449edabbe6dd354eb879a7d4d530f8",
+    "bug-fix/2026-07-27-question-composer-rows-do-not-shrink.i18n.yaml": "sha256:9b8fd6c3fc5f6527890d74a70372de90ade6db5fa957246d4bbdc06ee06e072c",
+    "bug-fix/2026-07-27-question-composer-rows-do-not-shrink.md": "sha256:0411033becc2835ce53cd268c9fa149830274c9f61016514087bea89562cfbb8",
+    "bug-fix/2026-07-27-question-composer-rows-do-not-shrink.zh.md": "sha256:41f024f8b7a4587a92026b4d36d77879086bc86716b0b28bf2131b85db35ee75",
     "bug-fix/2026-07-27-tool-card-single-row-fields-inline.i18n.yaml": "sha256:4b94aded16c60628d22414dce524e8a98a8af4fff298805ee7efc63cae02c90d",
     "bug-fix/2026-07-27-tool-card-single-row-fields-inline.md": "sha256:40adcd522a9a2eeacc6f2b0196d1f24888a4f57830b7490a3be3d78c86c4e968",
     "bug-fix/2026-07-27-tool-card-single-row-fields-inline.zh.md": "sha256:a79d56c9b781442ee596b47707d1a8c80abcd6466094b01802189c8e55f16da7",
@@ -70,15 +76,27 @@
     "bug-fix/2026-07-27-tui-step-timing-trails-tool-cards.i18n.yaml": "sha256:280b93ece72662501f65edd58a00cdafb5b5941e4ef1314d7198fab18950cb03",
     "bug-fix/2026-07-27-tui-step-timing-trails-tool-cards.md": "sha256:112bdbde16b6023eeb5b8a79cd2a711385e7198d51bbfc0520e9612acaa95c8a",
     "bug-fix/2026-07-27-tui-step-timing-trails-tool-cards.zh.md": "sha256:fc4e7f778ea63c4583cf81132c264cf6c4b9cc3e1818778061b0497ff16b8ef6",
+    "bug-fix/2026-07-28-web-conversation-polish-sweep.i18n.yaml": "sha256:27e60a7d822b201dee65eebc8335da8edd416ee19b9b89c056302bae69c830fd",
+    "bug-fix/2026-07-28-web-conversation-polish-sweep.md": "sha256:92647f06202f8711107918da9d9947767385a8b6307e772b1e868b0b1cb07412",
+    "bug-fix/2026-07-28-web-conversation-polish-sweep.zh.md": "sha256:95ccc18f4b35396bdcabee8b8745e75008f6c07f829fd8719bbb35d77ac0fd95",
     "bug-fix/2026-07-30-tui-adapter-registration-race.i18n.yaml": "sha256:50b7a32e11591719c249258ecc2ec0f45e58f1a04050d2e53f6e2650f58ba137",
     "bug-fix/2026-07-30-tui-adapter-registration-race.md": "sha256:7e17eb1dd8f92e1efb7a18477df277b13580840b473ffe8a5309fc70ec3cfa3e",
     "bug-fix/2026-07-30-tui-adapter-registration-race.zh.md": "sha256:efcbd3d82af6a58677efe1a0580edd715945b6a93418fde47badac9c01a29866",
+    "bug-fix/2026-07-30-web-details-default-closed.i18n.yaml": "sha256:2af5559d727f3e4afdd4946eaf89ac212c81db611db78dbd9bfabb1c4661db17",
+    "bug-fix/2026-07-30-web-details-default-closed.md": "sha256:27a280a817c8048718bb22927e7d9572cf99ffd0c044631e99e0fd6ea236876f",
+    "bug-fix/2026-07-30-web-details-default-closed.zh.md": "sha256:e047c7d02cf4b95b0c7f78f4b79af254091294b05cc75e98a8bb860ae2074189",
+    "bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml": "sha256:42218a762ce0141d3cb43deb6c688d3705cdc4405e03851d486c78f3d25b70ef",
+    "bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md": "sha256:a40992e89736131f5c487e5357848f14accd06e135dbec9ce242c968a5b11d43",
+    "bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md": "sha256:e0cc576bc1c196affc9220ddabf15d735c347029c530c56454f0e585979101e1",
     "bug-fix/2026-07-31-tui-diff-context-line-accounting.i18n.yaml": "sha256:cd39ae2646fdc6827bf29a63953b5463faa37d5b404ae8cc3c0913c47bc92d0c",
     "bug-fix/2026-07-31-tui-diff-context-line-accounting.md": "sha256:57066bccd22c2dc2c3546b363de73d13b55ff8683ee12b17a81ed2bcf536645b",
     "bug-fix/2026-07-31-tui-diff-context-line-accounting.zh.md": "sha256:a658d886c5eb203f5f30a6fac70ad18e4a24cf756746254723d8f1d144653c04",
     "bug-fix/2026-08-03-tui-long-session-render-costs.i18n.yaml": "sha256:f65f7bf8fc84c7a1f022ee393c8d969c06d9bde8bed3a0206de86fb35b246ac6",
     "bug-fix/2026-08-03-tui-long-session-render-costs.md": "sha256:6ecf2ef831f527f361ade18a882d79bc6eccf15cc676d05728e7753f41cde051",
     "bug-fix/2026-08-03-tui-long-session-render-costs.zh.md": "sha256:5f44e707b332e13fa06d625212173ea055c1c3c0aee60888435a0ff099ec6037",
+    "bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml": "sha256:ec2ab13c899d2f138cdad0fcbbba3565395ca13bb2c6925ac0fee6518c7b1a2b",
+    "bug-fix/2026-08-04-conversation-column-one-axis-scroll.md": "sha256:7866cb16460aa47a958b81e904161aa655d54ac331b32f585d6429fffb5c700c",
+    "bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md": "sha256:e01af7c18cad86dac88720014eaeb1f5491eb7feac1e542c5a3d0fd2cc3afee5",
     "feature/2026-06-14-acp-agent-client-protocol.i18n.yaml": "sha256:006795baa43ae962a8d125cc0f1e9f134bc2ee9fb758b6e7669e3fa0126e1918",
     "feature/2026-06-14-acp-agent-client-protocol.md": "sha256:6828c0af74bb3fb96206ca6b21c0e56a000b50e4744aad4bc2c05092f3a5a31b",
     "feature/2026-06-14-acp-agent-client-protocol.zh.md": "sha256:ba104e841a1fb84edbd3b6c8119d50445b7785255a7a8d13bb9ac8a2cb4d2e69",
@@ -157,6 +175,9 @@
     "feature/2026-07-21-tui-verbose-status-line.i18n.yaml": "sha256:4371b9a46d713d4180aa5d0b1ecde1ff3cae948380a8f56474c895e6113d7824",
     "feature/2026-07-21-tui-verbose-status-line.md": "sha256:9dcba19ee725b1593e9413a1da5398c205a258aff2e384acd406bb618e86c7f0",
     "feature/2026-07-21-tui-verbose-status-line.zh.md": "sha256:203c2abac99cedf7afa2540c925367ba66f00b61b926d1cc86472a603ad2bb07",
+    "feature/2026-07-22-docked-web-goal-bar.i18n.yaml": "sha256:4fae22f5b921ae37feda632addace14bab8d1578c861228dd1df89a7b579f057",
+    "feature/2026-07-22-docked-web-goal-bar.md": "sha256:94a4b00afc231eddd0fdcf6a494157d12a12b3ae40e8d732c3c05c6811b1c1f8",
+    "feature/2026-07-22-docked-web-goal-bar.zh.md": "sha256:90dfa4f855a810bce6d57157049eacd6b0d9aa45e99fc296d9024adae4ebac7a",
     "feature/2026-07-23-trajectory-step-cell.i18n.yaml": "sha256:fe2e935a0affdef877902a40d9861ef5f55b30f40650469f6a52a4d45a92793f",
     "feature/2026-07-23-trajectory-step-cell.md": "sha256:185e3b87174cb6d2f2d2271fd2a74b1517d03e8570be602570d027bf6002d106",
     "feature/2026-07-23-trajectory-step-cell.zh.md": "sha256:51f46be43d2f5c4f78a05ed9aeec92d1f33ac988f45cf24d35528e9c43828ef3",
@@ -205,24 +226,45 @@
     "feature/2026-07-29-tui-hidden-mode-assistant-fold.i18n.yaml": "sha256:0865835802348b730542adbe6b7db613750f3786993c6a14dbb2f47686c13c70",
     "feature/2026-07-29-tui-hidden-mode-assistant-fold.md": "sha256:a5fefebd802e2d9c3c79c7852c1c34c7bbef3f2ac2150d224608b9ec44e966ad",
     "feature/2026-07-29-tui-hidden-mode-assistant-fold.zh.md": "sha256:21bccd1e07ec8dc73b618f428461848bb90b6235afe0b842afb0afab2d5cc575",
+    "feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml": "sha256:59b09ed3c94f9b706b5ba8b567e264d9a6f4ff396245a8f4435ddfe5f4af3620",
+    "feature/2026-07-29-web-message-icon-actions-and-clock.md": "sha256:c4f56f6681f7fa5fdef5354cdd1d0d00ae7e77f4ebcfae6015579b8a4e9ad712",
+    "feature/2026-07-29-web-message-icon-actions-and-clock.zh.md": "sha256:6f8522382f644467ba39c7c0f15583de30a79ac17305cdba94c4195169cb0dc3",
     "feature/2026-07-30-compaction-progress-visibility.i18n.yaml": "sha256:4c2267054ad5d73aecc8d39d138a0cb532981b33175252e67252d07c3314b0f5",
     "feature/2026-07-30-compaction-progress-visibility.md": "sha256:2dfe07244cd784f27a9e5850801d40e96eae21a20ba10aaf56f9a793cdf5b505",
     "feature/2026-07-30-compaction-progress-visibility.zh.md": "sha256:6180b8aff0536147ab6ed6a78ecdbe1448fd12d89407746ecb1c7c05c73d4d60",
+    "feature/2026-07-30-dsh-dump-config.i18n.yaml": "sha256:b400c8cce902328989e5493301f66451de7a36e966d69c43b20935fc635aca0f",
+    "feature/2026-07-30-dsh-dump-config.md": "sha256:85b81dd517aaa6bb7510780acd961739c6da223bf2ddf6747d62f7a74e652d1f",
+    "feature/2026-07-30-dsh-dump-config.zh.md": "sha256:d0d55947bcb0ef53d534844c15928ae26eebe3fb6d43f98ab176ec36a8eac640",
     "feature/2026-07-30-tui-details-command.i18n.yaml": "sha256:033cea6df0a16fc68cbdb435babdc6e75c1199a8e70e1a71d87c800c40f5a044",
     "feature/2026-07-30-tui-details-command.md": "sha256:a13478d4e55ec6d358209b51b541413ec75d0e20dfc22196ace28020f03f0c2d",
     "feature/2026-07-30-tui-details-command.zh.md": "sha256:de9c449b98468cef34ce4f9a9d2a854a5d8905eecd61f80e27a9a0e4495e9901",
     "feature/2026-07-30-versioned-tui-first-run-welcome.i18n.yaml": "sha256:4c3fc380b0512ad7c00baacd0ac610e1a78ae45374311d9bd43bab6b5e29e630",
     "feature/2026-07-30-versioned-tui-first-run-welcome.md": "sha256:296f153e6c839f3743078e4f5aab3b2befc211c934835238668c57bdeae52231",
     "feature/2026-07-30-versioned-tui-first-run-welcome.zh.md": "sha256:82871a9cca1fec46bb08a5b39daad28a44bb2419dea367b4ae41af3cf07bfa65",
+    "feature/2026-07-30-web-composer-stats-and-input-polish.i18n.yaml": "sha256:eb0f02b1e15cb127618c82871fcea1b3ba4a9a5db670615072f15c71864729ea",
+    "feature/2026-07-30-web-composer-stats-and-input-polish.md": "sha256:68d0c0486219d8e886db07c4cde2285e515adf9756c1e4bc94e4bbd5cbcc2c93",
+    "feature/2026-07-30-web-composer-stats-and-input-polish.zh.md": "sha256:679565f7a2e183ac71132bd1cbd9d2418d77fe0e5472224b15bd310dd3931f4b",
+    "feature/2026-07-30-web-context-injection-disclosure.i18n.yaml": "sha256:83a8b78b0140afc8f18034674b594b998099c162ed9b9d939cb99e49cea2272b",
+    "feature/2026-07-30-web-context-injection-disclosure.md": "sha256:00f869b29861ff8f30e64ea3ca65aa9f8a06b33be205453ea3b679e5dfe05c4d",
+    "feature/2026-07-30-web-context-injection-disclosure.zh.md": "sha256:9bca10469e4d77b20c3785ce7ab6cbc628a03b8919de8a47c14466c1dbc94d36",
     "feature/2026-07-31-experimental-subcommand-gate.i18n.yaml": "sha256:d223669bebbf6ea65b4ec636e8e7ed618eff389117335946be713897151c6968",
     "feature/2026-07-31-experimental-subcommand-gate.md": "sha256:8fdee37340f7e72397cf2f440a2ca70639a987d07f0c2102e02e79c0fec4bfeb",
     "feature/2026-07-31-experimental-subcommand-gate.zh.md": "sha256:bcdec0f82319670a1d1de54a27b103b5e2d86306b884a5f9f415b89cd5a373f4",
+    "feature/2026-07-31-hover-card-click-copy.i18n.yaml": "sha256:2b95987c23e13a4499f5f3851770e8f97aa6f6df457a36b6aa818a8db08785c9",
+    "feature/2026-07-31-hover-card-click-copy.md": "sha256:f9a85c1603dcbdd36d26f730bf2a1f7bfaaa2267c7c30bee08cb9a94a7ce774e",
+    "feature/2026-07-31-hover-card-click-copy.zh.md": "sha256:b01e6edda5c6b031b5265ca0d868583fecce04cbc817fa7e8cc4433d10056e64",
+    "feature/2026-07-31-web-cards-toolrow.i18n.yaml": "sha256:f9a6ab72a77934cdcc02167c7313f08d7e9925362017b34bed7ad56c8c70fbaa",
+    "feature/2026-07-31-web-cards-toolrow.md": "sha256:5058f7cec4497d1cb0a5c8e77b88fddacac6eead034f3edec88e8514919b8a3e",
+    "feature/2026-07-31-web-cards-toolrow.zh.md": "sha256:ba84ef2e1be61211ab5ba6950b78ede3d3a979f252bc068d3e04e2c025f7bc03",
     "process/2026-06-11-doc-sync-enforcement.i18n.yaml": "sha256:33b6d5874427bd7a2bd82e7e2f4f482b12448b2464aef15a9c57975edb48554d",
     "process/2026-06-11-doc-sync-enforcement.md": "sha256:aa2fe83d519fc30d48dff19e596e83c8922aacc9e063e14fe2cc35b769b9100e",
     "process/2026-06-11-doc-sync-enforcement.zh.md": "sha256:698017bd35f030fdea3eac51df9e43138c48140f504739d687b7251d13fced2b",
     "process/2026-06-11-tsdown-over-dumble.i18n.yaml": "sha256:22791adb84a4b6c545173d4f1708eea51151d57e426d875e0e5423be9b6e0212",
     "process/2026-06-11-tsdown-over-dumble.md": "sha256:8d3c35dddd8869cc3361059dfe4b7b8ab6716d29dda232c97c2f37e92c841dc0",
     "process/2026-06-11-tsdown-over-dumble.zh.md": "sha256:cf11c651c13f5ffef5474e7795006ba3653c5eb08eae75a879be6499353455dc",
+    "process/2026-06-20-generated-cordis-catalog.i18n.yaml": "sha256:5250aaec698b25bdf5e3a02f67e531793fc968f9c38348f0c8bd11418571967f",
+    "process/2026-06-20-generated-cordis-catalog.md": "sha256:1f3190b759bf1445b35f25f2f18ac1c8b16d7f2e9263e2627bf3c94fac54d275",
+    "process/2026-06-20-generated-cordis-catalog.zh.md": "sha256:5d46da71bd73bba62ba15a9f11b21da422dbecc8ed68b6f530ceb302e1935ddb",
     "process/2026-07-03-documentation-graph-atlas.i18n.yaml": "sha256:b1e1ed4b7865d87f939dbf8c94c0ea1069fdf7af6fa68f695e6c9d6eccbeb123",
     "process/2026-07-03-documentation-graph-atlas.md": "sha256:b62e92bb12123bfa4c4dac806f584aabb6b60af4c5a6a4ab88f84bb9153e766d",
     "process/2026-07-03-documentation-graph-atlas.zh.md": "sha256:3485ede4a5e695643bcf9e744a62f8914cff788ae35717dac5eb6bf77e0d65cf",
@@ -322,9 +364,21 @@
     "simplification/2026-07-26-consolidate-gate-scripts-on-existing-deps.i18n.yaml": "sha256:7acf002ea8c1533f052c7bfc0c4e3da013ecf43c5872866a3ee4a8c2691c5e33",
     "simplification/2026-07-26-consolidate-gate-scripts-on-existing-deps.md": "sha256:f18a913096b7defd2192c4bac888a33f68075c3662703a0e28a6146897d17777",
     "simplification/2026-07-26-consolidate-gate-scripts-on-existing-deps.zh.md": "sha256:ff48a37673c97059536fe5b61aff746133eac682145550badb049eb5c83b097c",
+    "simplification/2026-07-26-eventsource-parser-for-deepseek-sse.i18n.yaml": "sha256:534abd90ddde9ccd35ab7e595de4242d8fa30a75908a638e5b3290f749553e5a",
+    "simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md": "sha256:ce449c72ed09238ba5dbe6068689db13bd33225694b2ad2c7696541f32dc0eec",
+    "simplification/2026-07-26-eventsource-parser-for-deepseek-sse.zh.md": "sha256:2f66b407b626f1f8c661d849b3b359c959e690715e0ac3f61f7e3d57d59e89c3",
+    "simplification/2026-07-26-turndown-for-tool-web-html-markdown.i18n.yaml": "sha256:6df56f5f5639847f0fac445abb5fea8a07f3cf9a0703d9022e50728c8f5055ca",
+    "simplification/2026-07-26-turndown-for-tool-web-html-markdown.md": "sha256:344c5cc2a1e79287eeda6996ae417dd2e02a7545987df0f2c9016b20ae094d93",
+    "simplification/2026-07-26-turndown-for-tool-web-html-markdown.zh.md": "sha256:8c4f2ac12ccd23f7ada90694502f5da689344e6bba72080a89672aa9b4f1903a",
     "simplification/2026-07-27-copyable-transcript-no-gutter-bar.i18n.yaml": "sha256:821f96f3e203e03b80553c07b10a511926bb5014be95c7df6bffb30c8e226d31",
     "simplification/2026-07-27-copyable-transcript-no-gutter-bar.md": "sha256:4b6aa150bbc8a4da0acac4d20f5fb8c2b77fef7e9c4c4dba8fd8e84dec36d619",
     "simplification/2026-07-27-copyable-transcript-no-gutter-bar.zh.md": "sha256:5225e627ff301be171434a5b9f18905fe1578f50eb2d4bf9998e126aba6cc3e3",
+    "simplification/2026-07-30-sidebar-resize-without-visible-pill.i18n.yaml": "sha256:ad42430fef4a5db610f8c56acfcda79b40396418694f664a5b0fb093bff1f114",
+    "simplification/2026-07-30-sidebar-resize-without-visible-pill.md": "sha256:6f2cfc5121371ec19c7178b31777c223e16bebdc9b63b7654a61cadc4a765b63",
+    "simplification/2026-07-30-sidebar-resize-without-visible-pill.zh.md": "sha256:ab859eeb12c6a74da3c37d411af52fce37bed3195941570b2f23ccd9a00d55fe",
+    "simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml": "sha256:531c446f0e95054f8ced17be9a180f8b0a823f7e9d5ce466c94c2f9cff90a111",
+    "simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md": "sha256:a35a6372aabdf7cbc211f1bd5820d85d3467c9ed50f84e05caa3339382379ce7",
+    "simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md": "sha256:a6ed9530289a783c3d7a1ddb038fba6b7daf7feb773298a57e811791e354d438",
     "testing/2026-06-20-remove-redundant-snapshot-log-expected-output.i18n.yaml": "sha256:4177012c0821a8c22499852ecdf096af56d7263cb91c5d9d1bcd552cc26a3e00",
     "testing/2026-06-20-remove-redundant-snapshot-log-expected-output.md": "sha256:45234e7cc04b6010c6141f8d5924c04547300098f96262d423c50108e7c7011a",
     "testing/2026-06-20-remove-redundant-snapshot-log-expected-output.zh.md": "sha256:15e5a4ad3dee0bb711480cabe45cd97ec37bbdba19c2c2b47d1e9c203b07a48b",
@@ -345,6 +399,9 @@
     "testing/2026-07-08-shared-acp-snapshot-package.zh.md": "sha256:02da3f910c2060f70038a0d86a7ddae4a8890905600440e1373412f54fbdcea8",
     "testing/2026-07-18-tui-terminal-state-snapshots.i18n.yaml": "sha256:c1a22174274b9f34ef4368039b3547f221507b040bd51b87af73a2722ee6b4d2",
     "testing/2026-07-18-tui-terminal-state-snapshots.md": "sha256:9a7fdcbeafc34376cb049b9668e0f4e9e541f523116fb11c3af9d35c2963e908",
-    "testing/2026-07-18-tui-terminal-state-snapshots.zh.md": "sha256:26750f240f6c8a7b28746f62fe161b357e9c5dd52867cc7037399f1ed6ff37fa"
+    "testing/2026-07-18-tui-terminal-state-snapshots.zh.md": "sha256:26750f240f6c8a7b28746f62fe161b357e9c5dd52867cc7037399f1ed6ff37fa",
+    "testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml": "sha256:dd45cddb591b892739b75b0c180bde7f14008f4769227b863571475be295e1e0",
+    "testing/2026-07-26-execa-for-test-subprocess-plumbing.md": "sha256:1f45a69d0a7367ec5afbf112a77b355339b35270af8ff52696bee879cdf770d3",
+    "testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md": "sha256:8a24bdc8376373d7a97f65cefc07078824bf918d6a9934056a025ecfafe8634b"
   }
 }
diff --git a/.agents/notes/archived/process/2026-06-20-generated-cordis-catalog.i18n.yaml b/.agents/notes/archived/process/2026-06-20-generated-cordis-catalog.i18n.yaml
new file mode 100644
index 0000000000..3eb6be2fb1
--- /dev/null
+++ b/.agents/notes/archived/process/2026-06-20-generated-cordis-catalog.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/archived/process/2026-06-20-generated-cordis-catalog.md
+2026-06-20-generated-cordis-catalog.md: 8d013a5b0c7e1b8df9f607215384f6c26a83b5b8
+2026-06-20-generated-cordis-catalog.zh.md: 2550bc805db7bea95106d444ecf9b0ad75ef91cc
diff --git a/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.md b/.agents/notes/archived/process/2026-06-20-generated-cordis-catalog.md
similarity index 99%
rename from .agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.md
rename to .agents/notes/archived/process/2026-06-20-generated-cordis-catalog.md
index 5005e50a2e..8d013a5b0c 100644
--- a/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.md
+++ b/.agents/notes/archived/process/2026-06-20-generated-cordis-catalog.md
@@ -1,6 +1,7 @@
 # Agent Note: Generated cordis events + services catalog
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-06-20-generated-cordis-catalog.zh.md)
 
diff --git a/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.zh.md b/.agents/notes/archived/process/2026-06-20-generated-cordis-catalog.zh.md
similarity index 99%
rename from .agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.zh.md
rename to .agents/notes/archived/process/2026-06-20-generated-cordis-catalog.zh.md
index 384e00d23a..2550bc805d 100644
--- a/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.zh.md
+++ b/.agents/notes/archived/process/2026-06-20-generated-cordis-catalog.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 生成的 Cordis 事件与服务目录
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-06-20-generated-cordis-catalog.md) | 中文
 
diff --git a/.agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.i18n.yaml b/.agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.i18n.yaml
new file mode 100644
index 0000000000..cfb5b17afd
--- /dev/null
+++ b/.agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.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/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md
+2026-07-26-eventsource-parser-for-deepseek-sse.md: 9e716cf9556c9c2d8cdf6cb85c6908d45a127a0f
+2026-07-26-eventsource-parser-for-deepseek-sse.zh.md: 16c63ddc9646f6309654910bd80801bd20005545
diff --git a/.agents/notes/implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md b/.agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md
similarity index 99%
rename from .agents/notes/implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md
rename to .agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md
index e7835bc738..9e716cf955 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md
+++ b/.agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md
@@ -1,6 +1,7 @@
 # Agent Note: Replace the hand-rolled SSE parser in llm-deepseek with eventsource-parser
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-26-eventsource-parser-for-deepseek-sse.zh.md)
 
diff --git a/.agents/notes/implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.zh.md b/.agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.zh.md
similarity index 99%
rename from .agents/notes/implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.zh.md
rename to .agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.zh.md
index 7c746079aa..16c63ddc96 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.zh.md
+++ b/.agents/notes/archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 用 eventsource-parser 替换 llm-deepseek 中手写的 SSE 解析器
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-26-eventsource-parser-for-deepseek-sse.md) | 中文
 
diff --git a/.agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.i18n.yaml b/.agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.i18n.yaml
new file mode 100644
index 0000000000..f79936b9fa
--- /dev/null
+++ b/.agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-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 .agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md
+2026-07-26-turndown-for-tool-web-html-markdown.md: 46c4eba12c782146aa32df245c5f69567723935a
+2026-07-26-turndown-for-tool-web-html-markdown.zh.md: 077ea89c54c63e41bec2aabd15e744b7b8a764da
diff --git a/.agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md b/.agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md
similarity index 99%
rename from .agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md
rename to .agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md
index 0e387021e3..46c4eba12c 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md
+++ b/.agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md
@@ -1,6 +1,7 @@
 # Agent Note: Replace tool-web's regex HTML-to-markdown converter with turndown
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-26-turndown-for-tool-web-html-markdown.zh.md)
 
diff --git a/.agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.zh.md b/.agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.zh.md
similarity index 99%
rename from .agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.zh.md
rename to .agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.zh.md
index 6c9b9a22db..077ea89c54 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.zh.md
+++ b/.agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 用 turndown 替换 tool-web 的正则 HTML 转 markdown 转换器
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-26-turndown-for-tool-web-html-markdown.md) | 中文
 
diff --git a/.agents/notes/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.i18n.yaml b/.agents/notes/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.i18n.yaml
new file mode 100644
index 0000000000..4f211e5ed8
--- /dev/null
+++ b/.agents/notes/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.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/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.md
+2026-07-30-sidebar-resize-without-visible-pill.md: 50bf43564675540df2db8e88530a82177f551407
+2026-07-30-sidebar-resize-without-visible-pill.zh.md: 41a33e039aaa29813d4232e5a6d36141b55ce947
diff --git a/.agents/notes/implemented/simplification/2026-07-30-sidebar-resize-without-visible-pill.md b/.agents/notes/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.md
similarity index 98%
rename from .agents/notes/implemented/simplification/2026-07-30-sidebar-resize-without-visible-pill.md
rename to .agents/notes/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.md
index cc41898990..50bf435646 100644
--- a/.agents/notes/implemented/simplification/2026-07-30-sidebar-resize-without-visible-pill.md
+++ b/.agents/notes/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.md
@@ -1,6 +1,7 @@
 # Agent Note: Sidebar resize without a visible pill
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-30-sidebar-resize-without-visible-pill.zh.md)
 
diff --git a/.agents/notes/implemented/simplification/2026-07-30-sidebar-resize-without-visible-pill.zh.md b/.agents/notes/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.zh.md
similarity index 98%
rename from .agents/notes/implemented/simplification/2026-07-30-sidebar-resize-without-visible-pill.zh.md
rename to .agents/notes/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.zh.md
index 9f1f521df2..41a33e039a 100644
--- a/.agents/notes/implemented/simplification/2026-07-30-sidebar-resize-without-visible-pill.zh.md
+++ b/.agents/notes/archived/simplification/2026-07-30-sidebar-resize-without-visible-pill.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 侧边栏缩放不显示胶囊
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-30-sidebar-resize-without-visible-pill.md) | 中文
 
diff --git a/.agents/notes/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml b/.agents/notes/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml
new file mode 100644
index 0000000000..32c335c431
--- /dev/null
+++ b/.agents/notes/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.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/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md
+2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md: 8ef2b7deb103f2e2a9147b4b50c7d39936ed2381
+2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md: 875e44a06e1cebf4f2b1731909c479b2f06fb06a
diff --git a/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md b/.agents/notes/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md
similarity index 99%
rename from .agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md
rename to .agents/notes/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md
index e2d821f395..8ef2b7deb1 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md
+++ b/.agents/notes/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md
@@ -1,6 +1,7 @@
 # Agent Note: Web UI drops steer entry and interjection chrome
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md)
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md b/.agents/notes/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md
similarity index 99%
rename from .agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md
rename to .agents/notes/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md
index b55d4a271e..875e44a06e 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md
+++ b/.agents/notes/archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: Web UI 去掉 steer 入口与插话 chrome
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md) | 中文
 
diff --git a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml
new file mode 100644
index 0000000000..2fb23f6ad5
--- /dev/null
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.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/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
+2026-07-26-execa-for-test-subprocess-plumbing.md: ca5edc50bf17a34809037462f8e9603b8ed28e74
+2026-07-26-execa-for-test-subprocess-plumbing.zh.md: 186e5cd560b6500364c855438d6c3ff18206b52b
diff --git a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.md b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
similarity index 99%
rename from .agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
rename to .agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
index 958abc4aee..ca5edc50bf 100644
--- a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
@@ -1,6 +1,7 @@
 # Agent Note: Adopt execa for hand-rolled test subprocess plumbing
 
 Status: implemented
+Archived: 2026-08-07
 
 English | [中文](2026-07-26-execa-for-test-subprocess-plumbing.zh.md)
 
diff --git a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
similarity index 99%
rename from .agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
rename to .agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
index 5ccadd93a1..186e5cd560 100644
--- a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 采用 execa 替换手写的测试子进程管道代码
 
 Status: implemented
+Archived: 2026-08-07
 
 [English](2026-07-26-execa-for-test-subprocess-plumbing.md) | 中文
 
diff --git a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml
index c897fc3bab..6fbbd961a2 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.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 .agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md
-2026-06-13-twin-llm-adapters.md: b922891d4438553fd96a7f4f4226f378e66e8ad2
-2026-06-13-twin-llm-adapters.zh.md: 391f9259172bc91bb4e5fc036e6064a207a7e308
+2026-06-13-twin-llm-adapters.md: a4c87325a0b0d1ebe6cf8f95672e5de74ef37d57
+2026-06-13-twin-llm-adapters.zh.md: 753d7900f23c0d3388be0488c291145fdccf5a95
diff --git a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md
index b922891d44..a4c87325a0 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md
@@ -12,7 +12,7 @@ English | [中文](2026-06-13-twin-llm-adapters.zh.md)
 
 Ship **two** adapters against the one contract from the start, deliberately built on different internals:
 
-- `dsh-llm-deepseek` — direct `fetch` + in-repo translation against the DeepSeek API; SSE framing is delegated to `eventsource-parser` ([the SSE-parser swap](../simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md)). The twin identity is owning the fetch/translate internals rather than delegating to a full provider SDK, not hand-rolling transport plumbing.
+- `dsh-llm-deepseek` — direct `fetch` + in-repo translation against the DeepSeek API; SSE framing is delegated to `eventsource-parser` ([the archived SSE-parser swap](../../archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md)). The twin identity is owning the fetch/translate internals rather than delegating to a full provider SDK, not hand-rolling transport plumbing.
 - `dsh-llm-pi-ai` — the same endpoint through the `@earendil-works/pi-ai` library (its own event vocabulary).
 
 The rule they enforce: **anything the StreamChunk vocabulary cannot express for BOTH implementations is a core-vocabulary bug**, caught immediately rather than at the next provider. The pair pinned down conventions now documented on `StreamChunk` in `dsh-llm/src/types.ts`: usage emitted before finish, nothing after finish, tool-call `arguments` as raw JSON strings end-to-end, and the two sanctioned error paths (throw from `stream()` *or* end with `finish {kind:'error'|'aborted'}`) that a consumer must handle on both sides — a divergence the library-backed adapter surfaced that a single direct-fetch adapter would have hidden.
diff --git a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md
index 391f925917..753d7900f2 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 从一开始就针对同一份契约交付**两个**适配器，刻意基于不同的内部实现构建：
 
-- `dsh-llm-deepseek`：直接 `fetch` + 仓库内翻译逻辑对接 DeepSeek API；SSE（Server-Sent Events）分帧委托给 `eventsource-parser`（[SSE 解析器替换](../simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md)）。孪生身份在于自行持有 fetch/translate 内部实现而非委托给完整的提供方 SDK，不在于手写传输层管道。
+- `dsh-llm-deepseek`：直接 `fetch` + 仓库内翻译逻辑对接 DeepSeek API；SSE（Server-Sent Events）分帧委托给 `eventsource-parser`（[已归档的 SSE 解析器替换](../../archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md)）。孪生身份在于自行持有 fetch/translate 内部实现而非委托给完整的提供方 SDK，不在于手写传输层管道。
 - `dsh-llm-pi-ai`：通过 `@earendil-works/pi-ai` 库访问同一端点（该库有自己的事件词汇）。
 
 二者共同执行的规则是：**凡 StreamChunk 词汇无法为两个实现同时表达的内容，都是核心词汇的缺陷**——立即暴露，而非等到下一个提供方接入时才发现。这对孪生适配器确立了现已记录在 `dsh-llm/src/types.ts` 中 `StreamChunk` 上的约定：usage 在 finish 之前发出、finish 之后不再有任何事件、工具调用的 `arguments` 全程以原始 JSON 字符串传递，以及消费方必须在两侧都处理的两条合法错误路径（`stream()` 抛异常，*或者*以 `finish {kind:'error'|'aborted'}` 结束）。这一分歧正是由基于库的适配器暴露出来的，单一直接 fetch 适配器会将其隐藏。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.i18n.yaml
deleted file mode 100644
index b74717afb9..0000000000
--- a/.agents/notes/implemented/architecture/2026-07-28-dsh-native-typescript-source-launch.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/architecture/2026-07-28-dsh-native-typescript-source-launch.md
-2026-07-28-dsh-native-typescript-source-launch.md: 773f831ec2b116d4908fcd5dc818df78c5deee5e
-2026-07-28-dsh-native-typescript-source-launch.zh.md: 0e40a7e32bfaf1186ce816ec0bc1e608c76b47e0
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
index 8a6dbf705c..5a884924f9 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.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 .agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
-2026-07-29-dsh-source-launch-tsx-esm.md: 93fbb248b45efde37d5fbdb1ec4b812ab3332088
-2026-07-29-dsh-source-launch-tsx-esm.zh.md: 4d7b2c47db68f21e904a607f16c80d33c706c488
+2026-07-29-dsh-source-launch-tsx-esm.md: 21e912c7c7bbdd70142c202105d9a3035442884a
+2026-07-29-dsh-source-launch-tsx-esm.zh.md: dc6150b7017777eea99778cc9813e17402354462
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
index 93fbb248b4..21e912c7c7 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
@@ -4,11 +4,11 @@ Status: implemented
 
 English | [中文](2026-07-29-dsh-source-launch-tsx-esm.zh.md)
 
-> Supersedes [native TypeScript source launch](2026-07-28-dsh-native-typescript-source-launch.md): Node removed the capability that decision was built on.
+> Supersedes [native TypeScript source launch](../../archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md): Node removed the capability that decision was built on.
 
 ## Problem
 
-The [native source-launch decision](2026-07-28-dsh-native-typescript-source-launch.md) ran `apps/cli/src/bin.ts` under `node --experimental-transform-types` with a resolve-only paths loader, so Node owned TypeScript transformation. Node 26.0.0 removed `--experimental-transform-types` (the process rejects the flag with `bad option`), keeping only strip mode, and strip mode rejects syntax this source graph requires: vendored Cordis parameter properties (`constructor(private ctx: Context)`), the `@Inject` decorators in `vendor/hmr`, and runtime enums/namespaces throughout `vendor/` and `packages/workflow`. The repository's engines range (`^22.19.0 || >=24.0.0`) includes Node 26, so the native launch chain could not start at all there — and no CI job executed the real launch vector, so the incompatibility shipped silently.
+The [archived native source-launch decision](../../archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md) ran `apps/cli/src/bin.ts` under `node --experimental-transform-types` with a resolve-only paths loader, so Node owned TypeScript transformation. Node 26.0.0 removed `--experimental-transform-types` (the process rejects the flag with `bad option`), keeping only strip mode, and strip mode rejects syntax this source graph requires: vendored Cordis parameter properties (`constructor(private ctx: Context)`), the `@Inject` decorators in `vendor/hmr`, and runtime enums/namespaces throughout `vendor/` and `packages/workflow`. The repository's engines range (`^22.19.0 || >=24.0.0`) includes Node 26, so the native launch chain could not start at all there — and no CI job executed the real launch vector, so the incompatibility shipped silently.
 
 Startup latency also mattered: the off-thread `module.register()` hooks worker serialized every resolution across threads (~440ms of `makeSyncRequest` wait during TUI boot), and the full tsx default (`--import tsx`) pays ~0.4s in its CJS hook's resolution amplification.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
index 4d7b2c47db..dc6150b701 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-07-29-dsh-source-launch-tsx-esm.md) | 中文
 
-> 取代[原生 TypeScript 源码启动](2026-07-28-dsh-native-typescript-source-launch.md)：Node 移除了该决策所依赖的能力。
+> 取代[已归档的原生 TypeScript 源码启动](../../archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md)：Node 移除了该决策所依赖的能力。
 
 ## 问题
 
-[原生源码启动决策](2026-07-28-dsh-native-typescript-source-launch.md)让 `apps/cli/src/bin.ts` 在 `node --experimental-transform-types` 下运行，配合一个只做解析的 paths loader，由 Node 负责 TypeScript 转换。Node 26.0.0 移除了 `--experimental-transform-types`（进程以 `bad option` 拒绝该 flag），只保留 strip 模式，而 strip 模式无法接受这个源码图必需的语法：vendor Cordis 中的参数属性（`constructor(private ctx: Context)`）、`vendor/hmr` 中的 `@Inject` 装饰器，以及遍布 `vendor/` 与 `packages/workflow` 的运行时 enum/namespace。仓库的 engines 范围（`^22.19.0 || >=24.0.0`）包含 Node 26，因此原生启动链在其上完全无法启动——且没有任何 CI 任务执行过真实启动向量，这一不兼容悄然发布。
+[已归档的原生源码启动决策](../../archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md)让 `apps/cli/src/bin.ts` 在 `node --experimental-transform-types` 下运行，配合一个只做解析的 paths loader，由 Node 负责 TypeScript 转换。Node 26.0.0 移除了 `--experimental-transform-types`（进程以 `bad option` 拒绝该 flag），只保留 strip 模式，而 strip 模式无法接受这个源码图必需的语法：vendor Cordis 中的参数属性（`constructor(private ctx: Context)`）、`vendor/hmr` 中的 `@Inject` 装饰器，以及遍布 `vendor/` 与 `packages/workflow` 的运行时 enum/namespace。仓库的 engines 范围（`^22.19.0 || >=24.0.0`）包含 Node 26，因此原生启动链在其上完全无法启动——且没有任何 CI 任务执行过真实启动向量，这一不兼容悄然发布。
 
 启动延迟同样是问题：off-thread 的 `module.register()` 钩子工作线程把每次解析都跨线程序列化（TUI 启动期间约 440ms 的 `makeSyncRequest` 等待），而完整的 tsx 默认形态（`--import tsx`）会因其 CJS 钩子放大解析开销而多花约 0.4s。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
index 55efb87b8f..7665dc3290 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.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 .agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
-2026-07-30-session-end-seed-log-boundary.md: 9d0685876b4d1bac339961c67ab08f620e499464
-2026-07-30-session-end-seed-log-boundary.zh.md: 8fa9625ea6c58b0b07d964ef2580b670893a3d75
+2026-07-30-session-end-seed-log-boundary.md: 26cd67ccbfdf5dfc62e44a53c877acf6d2fee34a
+2026-07-30-session-end-seed-log-boundary.zh.md: 5ce12681da3ee46cc7c69aa6d432d25712db17fd
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
index 9d0685876b..26cd67ccbf 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
@@ -36,7 +36,7 @@ The predicate holds for a bracket *this* session inherited, not as a liveness si
 
 ## Alternatives considered
 
-**A boundary written by the persistence coordinator's cold-load path.** Built first, as the [`session/resumed` boundary](../../rejected/architecture/2026-07-29-session-resumed-log-boundary.md), and abandoned before merge. It covers no fork, which is the one case where the inherited bracket's owner may still be running. Because the marker was minted at load it also had to be a durable write on a read path, which spread cost across the seam: a revision bump on every cold load, a `commitRepair` batch on a balanced log with nothing to repair, a stored-time floor to keep the clamp monotonic, and a load that failed against a read-only store.
+**A boundary written by the persistence coordinator's cold-load path.** Built first as a `session/resumed` boundary and abandoned before merge. It covers no fork, which is the one case where the inherited bracket's owner may still be running. Because the marker was minted at load it also had to be a durable write on a read path, which spread cost across the seam: a revision bump on every cold load, a `commitRepair` batch on a balanced log with nothing to repair, a stored-time floor to keep the clamp monotonic, and a load that failed against a read-only store.
 
 **A boundary appended at loop start.** The loop calls `resumeWith`, so it covers the resume paths, but it misses `fork()` and `adopt()` entirely, and the event would have to fire on `'startup'` — the source a fork child publishes — so `SessionStartSource` would stop discriminating. It also publishes the session before the marker is appended, so a `session/created` listener could observe a seeded log with no boundary.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
index 8fa9625ea6..5ce12681da 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
@@ -36,7 +36,7 @@ Status: implemented
 
 ## Alternatives considered
 
-**由持久化协调器的冷加载路径写入边界。** 最先实现的方案，即 [`session/resumed` 边界](../../rejected/architecture/2026-07-29-session-resumed-log-boundary.md)，在合并前被放弃。它完全覆盖不到 fork，而 fork 恰恰是继承括号的所有方可能仍然存活的那一种情形。由于标记是在加载时铸造的，它还必须在读取路径上做持久写入，这把成本铺开到整个 seam：每次冷加载都递增 revision、对一份无需修复的平衡日志也要走 `commitRepair`、需要一个已存储时间下限来维持钳制的单调性，以及加载在只读存储上会失败。
+**由持久化协调器的冷加载路径写入边界。** 最初将其实现为 `session/resumed` 边界，并在合并前放弃。它完全覆盖不到 fork，而 fork 恰恰是继承括号的所有方可能仍然存活的那一种情形。由于标记是在加载时铸造的，它还必须在读取路径上做持久写入，这把成本铺开到整个 seam：每次冷加载都递增 revision、对一份无需修复的平衡日志也要走 `commitRepair`、需要一个已存储时间下限来维持钳制的单调性，以及加载在只读存储上会失败。
 
 **在 loop 启动时追加边界。** loop 调用 `resumeWith`，因此覆盖恢复路径，但完全漏掉 `fork()` 与 `adopt()`，而且事件不得不在 `'startup'` 上触发——那是 fork 子会话发布的来源——于是 `SessionStartSource` 将不再具有区分力。它还会在追加标记之前就发布会话，因此 `session/created` 监听方可能观察到一份没有边界的带种子日志。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.i18n.yaml
deleted file mode 100644
index 712d3e2dd8..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-07-27-question-composer-rows-do-not-shrink.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-question-composer-rows-do-not-shrink.md
-2026-07-27-question-composer-rows-do-not-shrink.md: 2e0e9b9ca6b141a200ba53d8b6f6f0cad5f7e89d
-2026-07-27-question-composer-rows-do-not-shrink.zh.md: 73e3e7614c1eab814080eb7c5e0d03322f1c7145
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.i18n.yaml
deleted file mode 100644
index 987b40abff..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-conversation-polish-sweep.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-28-web-conversation-polish-sweep.md
-2026-07-28-web-conversation-polish-sweep.md: cae52217d66017509c025a5d8d37b1e1e8173c6a
-2026-07-28-web-conversation-polish-sweep.zh.md: 0f352f066da13a749f61e89f52dd20487f7726b1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
index ef84211f5c..f314df3e08 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.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 .agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.md
-2026-07-29-web-details-session-lifecycle.md: cc1501440d50cb560291e416a0f2b0292e08e1c8
-2026-07-29-web-details-session-lifecycle.zh.md: 1102530f288359ebc5fb04a36c2b813da41e1318
+2026-07-29-web-details-session-lifecycle.md: 41b89fc059a02e56f53b27e5a5b48fb9488b93d7
+2026-07-29-web-details-session-lifecycle.zh.md: 82fb5e0c2608cccbb786a21971a74958417b4f10
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.md b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.md
index cc1501440d..41b89fc059 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.md
@@ -10,7 +10,7 @@ The details entry is Session-scoped, but its preferred grid width is root-scoped
 
 ## Decision
 
-`AppFrame` reads the current Session id and its `blank` summary flag from the authoritative Session projection. It records the last non-blank selected id only when that Session can own details, so hero and other unselected states neither trigger closure nor replace the last Session owner; their rendered details track derives as zero without changing the stored preference. The first Session preserves the layout store's initial preference, whose [visibility default is now closed](2026-07-30-web-details-default-closed.md); returning to the same Session restores its current width, and selecting a different Session closes the root-scoped details preference through the layout store before paint. The per-Session chat selection remains owned by the session-scoped store described by the [slot system standard](../architecture/2026-07-22-slot-type-chain-implementation.md).
+`AppFrame` reads the current Session id and its `blank` summary flag from the authoritative Session projection. It records the last non-blank selected id only when that Session can own details, so hero and other unselected states neither trigger closure nor replace the last Session owner; their rendered details track derives as zero without changing the stored preference. The first Session preserves the layout store's initial preference, whose [archived visibility-default decision](../../archived/bug-fix/2026-07-30-web-details-default-closed.md) chose closed; returning to the same Session restores its current width, and selecting a different Session closes the root-scoped details preference through the layout store before paint. The per-Session chat selection remains owned by the session-scoped store described by the [slot system standard](../architecture/2026-07-22-slot-type-chain-implementation.md).
 
 The layout store is transient and starts details closed. It neither reads nor writes `localStorage`, so reload restores the sidebar default and details closed and needs no Session-baseline exception. Manual close and reopen inside one unchanged Session retain their existing behavior. The lifecycle effect changes neither the [Workspace-owned New Session flow](../feature/2026-07-25-workspace-ui-product-flow.md), composer drafts, Session navigation, nor concession-chain resizing.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
index 1102530f28..82fb5e0c26 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-`AppFrame` 从权威会话投影读取当前会话 id 及其摘要中的 `blank` 标志。它只在该会话能够拥有详情时记录最后一个选中的非 blank 会话 id，因此 hero 和其他未选中状态既不会触发关闭，也不会替换最后一个会话 owner；这些状态下，详情栏轨道的渲染宽度派生为零，但存储的首选宽度不变。首个会话保留布局 store 的初始首选值，该值的[可见性默认设置现为关闭](2026-07-30-web-details-default-closed.md)；返回同一会话时恢复其当前宽度；选择不同会话时，系统会先通过布局 store 关闭根作用域存储的详情栏首选宽度，再进行绘制。逐会话的聊天选中项继续由 [slot 体系标准](../architecture/2026-07-22-slot-type-chain-implementation.md)所述的会话作用域 store 拥有。
+`AppFrame` 从权威会话投影读取当前会话 id 及其摘要中的 `blank` 标志。它只在该会话能够拥有详情时记录最后一个选中的非 blank 会话 id，因此 hero 和其他未选中状态既不会触发关闭，也不会替换最后一个会话 owner；这些状态下，详情栏轨道的渲染宽度派生为零，但存储的首选宽度不变。首个会话保留布局 store 的初始首选值，其[已归档的可见性默认值决策](../../archived/bug-fix/2026-07-30-web-details-default-closed.md)选择关闭；返回同一会话时恢复其当前宽度；选择不同会话时，系统会先通过布局 store 关闭根作用域存储的详情栏首选宽度，再进行绘制。逐会话的聊天选中项继续由 [slot 体系标准](../architecture/2026-07-22-slot-type-chain-implementation.md)所述的会话作用域 store 拥有。
 
 布局 store 是瞬时状态，详情栏在启动时保持关闭。它既不读取也不写入 `localStorage`，因此重新加载会恢复侧边栏默认值，并使详情栏保持关闭，无需会话基线例外。在同一个未变化的会话内手动关闭和重新打开详情栏，仍保持原有行为。该生命周期 effect 不改变 [Workspace 拥有的 New Session 动线](../feature/2026-07-25-workspace-ui-product-flow.md)、composer 草稿、会话导航或让步链缩放。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.i18n.yaml
deleted file mode 100644
index 0f0ff3020b..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-details-default-closed.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-30-web-details-default-closed.md
-2026-07-30-web-details-default-closed.md: 658b6fc2c18dc67d8759bec78997f32dcba27914
-2026-07-30-web-details-default-closed.zh.md: 5a1d0e4713e47ce3bc0cc68fa4c4f5f8c94c945f
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml
deleted file mode 100644
index 202b86ce3b..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-31-hero-visible-while-blank-session-opens.md
-2026-07-31-hero-visible-while-blank-session-opens.md: 6afa5d0ee2b695d6805d20f54e82073db8028df7
-2026-07-31-hero-visible-while-blank-session-opens.zh.md: f21e549b5811d81094374b1363186a1d18fbadaf
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
deleted file mode 100644
index 754ca8bbd0..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-08-04-conversation-column-one-axis-scroll.md
-2026-08-04-conversation-column-one-axis-scroll.md: 9a487c506a75033d0854f08e95da24704309003d
-2026-08-04-conversation-column-one-axis-scroll.zh.md: 23441a7c8655d1f19d3c0fe0f661f81f69b55dba
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml
index 72d3ae50b8..0050d26e51 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.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 .agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.md
-2026-08-05-turn-tail-actions-require-a-completed-turn.md: 689d50bb86c830d6e428239f112568f00d74c9b8
-2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md: 2cc426bbb82acb8f57d491b0f068e89771699357
+2026-08-05-turn-tail-actions-require-a-completed-turn.md: 44a890c955089096204a5b2a2833905c9ef9f7ed
+2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md: 58ca9b2519101cae12121cd74e13bdaa90ce23cb
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.md b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.md
index 689d50bb86..44a890c955 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.md
@@ -8,7 +8,7 @@ English | [中文](2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md)
 
 Assistant IconActions were derived from the finalized transcript alone: the last content-text assistant of each turn owned the row. That quantity is stable only after the turn closes. While a turn is still producing steps, the narration a model writes before a tool call *is* the last content assistant so far, so it took the row for as long as the tool ran and then lost it to the next step's text. Readers saw copy, branch, and a clock appear under an intermediate sentence, shift the flow by one 28px row, and disappear. The row was also incoherent in that state: its branch control was already disabled through `turnEnds`, and its `Ran for` label was already withheld through `turnTimings`, so only copy worked.
 
-The [message chrome decision](../feature/2026-07-29-web-message-icon-actions-and-clock.md) always claimed mid-turn narration stays chrome-free; the derivation never carried a completion signal to make that true.
+The [archived message-chrome decision](../../archived/feature/2026-07-29-web-message-icon-actions-and-clock.md) always claimed mid-turn narration stays chrome-free; the derivation never carried a completion signal to make that true.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md
index 2cc426bbb8..58ca9b2519 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 assistant IconActions 此前只从已定稿的 transcript（文本记录）推导：每个轮次中最后一条含内容文本的 assistant 拥有该行。这个量只有在轮次关闭后才稳定。轮次仍在产出步骤时，模型在工具调用前写下的叙述就是当时该轮次的最后一条内容 assistant，于是它在工具执行期间取得该行，等下一步的文本落定又把它交出去。读者会看到复制、分支和时钟出现在一句中间叙述下方，把流程推开一行 28px，然后消失。该行在这个状态下本身也是残缺的：分支控件已经通过 `turnEnds` 判定为禁用，`Ran for` 标签已经通过 `turnTimings` 判定为不显示，只有复制可用。
 
-[消息 chrome 决策](../feature/2026-07-29-web-message-icon-actions-and-clock.md)一直声称轮次中间的叙述不带 chrome，但推导过程从未拿到能让这句话成立的完成信号。
+[已归档的消息 chrome 决策](../../archived/feature/2026-07-29-web-message-icon-actions-and-clock.md)一直声称轮次中间的叙述不带 chrome，但推导过程从未拿到能让这句话成立的完成信号。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index 0406274fbe..661cd44ce6 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.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 .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
-2026-07-20-dsh-cli-personal-config.md: 10f16a1cbabdd8cd383c59ad8e09787c02d0109a
-2026-07-20-dsh-cli-personal-config.zh.md: 22435efbec8ea661c546ffd0c1aa9bb0ff2ebbb2
+2026-07-20-dsh-cli-personal-config.md: e3baa2dc5158893ddaf919b610e51a0b278b58eb
+2026-07-20-dsh-cli-personal-config.zh.md: 8417e0b27393fddeff5c75804c39deafdd1d83f8
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
index 10f16a1cba..e3baa2dc51 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
@@ -41,7 +41,7 @@ The TUI and Web register the exact personal path through Cordis HMR after boot.
 ## Consequences
 
 - `dsh` from any directory (and `pnpm run demo:tui`) can apply personal providers, models, repository Plugins, and other Loader entries with no checkout edit; verified end-to-end against a personal Anthropic proxy with Opus 4.8, including a bash tool round trip.
-- Because an id-targeted patch replaces the whole `config`, a personal override restates the base fields it keeps and can drift when the base entry changes shape; the loader's entry-not-found/name-mismatch warnings and [`dsh --dump-config`](2026-07-30-dsh-dump-config.md) (which prints the composed tree those patches produce) are the diagnostics.
+- Because an id-targeted patch replaces the whole `config`, a personal override restates the base fields it keeps and can drift when the base entry changes shape; the loader's entry-not-found/name-mismatch warnings and [`dsh --dump-config`](../simplification/2026-08-03-explicit-config-dsh-entrypoint.md) (which prints the composed tree those patches produce) are the diagnostics.
 - Personal patches resolve ids against the booted file's own tree, so nested-include overlays (Code Mode) are not personalized; live-run parity for those leaves is deferred.
 - `dsh-app-boot` depends on `js-yaml` and imports the include's `!!js` YAML dialect (`entryListSchema`) directly, and, like `apps/cli`, depends on `@deepseek-ai/dsh-paths` for `resolveDshHome`.
 - Live watching belongs only to long-running TUI and Web processes. Headless automation gets deterministic startup configuration and exits without retaining a watcher.
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index 22435efbec..8417e0b273 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -41,7 +41,7 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 ## Consequences
 
 - 在任意目录运行 `dsh`（以及 `pnpm run demo:tui`），无需修改 checkout，即可应用个人提供方、模型、仓库插件和其他 Loader 配置项；已针对个人 Anthropic 代理与 Opus 4.8 端到端验证，包括一次 bash 工具往返。
-- 由于按 id 定位的补丁替换整个 `config`，个人覆盖必须复述它保留的基础字段，并可能随基础配置项形态变化而漂移；诊断手段是 loader 的「配置项未找到/名称不匹配」警告和 [`dsh --dump-config`](2026-07-30-dsh-dump-config.md)（打印这些补丁合成出的配置树）。
+- 由于按 id 定位的补丁替换整个 `config`，个人覆盖必须复述它保留的基础字段，并可能随基础配置项形态变化而漂移；诊断手段是 loader 的「配置项未找到/名称不匹配」警告和 [`dsh --dump-config`](../simplification/2026-08-03-explicit-config-dsh-entrypoint.md)（打印这些补丁合成出的配置树）。
 - 个人补丁只在被启动文件自身的树里解析 id，因此嵌套 include 的 overlay（Code Mode）不会被个性化；这些叶子的实际运行等价性暂缓。
 - `dsh-app-boot` 依赖 `js-yaml`，并直接导入 include 的 `!!js` YAML 方言（`entryListSchema`）；与 `apps/cli` 一样依赖 `@deepseek-ai/dsh-paths` 以获取 `resolveDshHome`。
 - 只有长时间运行的 TUI 和 Web 进程进行实时监视。无头自动化使用确定性的启动配置，退出时不会保留 watcher。
diff --git a/.agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.i18n.yaml
deleted file mode 100644
index 7712757384..0000000000
--- a/.agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-22-docked-web-goal-bar.md
-2026-07-22-docked-web-goal-bar.md: ffddef6cec8eb632cd44bb5352de246db7413c02
-2026-07-22-docked-web-goal-bar.zh.md: b732f71cfc3d3f813641c2ad9c594134beb2e440
diff --git a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml
deleted file mode 100644
index 45c03a2347..0000000000
--- a/.agents/notes/implemented/feature/2026-07-29-web-message-icon-actions-and-clock.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-29-web-message-icon-actions-and-clock.md
-2026-07-29-web-message-icon-actions-and-clock.md: feced6aeb11d176d6c774242a4d1dae14f6730f8
-2026-07-29-web-message-icon-actions-and-clock.zh.md: 5e33182421b423f45c84dbe1a979505f4c31b819
diff --git a/.agents/notes/implemented/feature/2026-07-30-dsh-dump-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-dsh-dump-config.i18n.yaml
deleted file mode 100644
index 0cd2549e55..0000000000
--- a/.agents/notes/implemented/feature/2026-07-30-dsh-dump-config.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-30-dsh-dump-config.md
-2026-07-30-dsh-dump-config.md: bc6504541c7868bad019a1bcd9f551435109e4c6
-2026-07-30-dsh-dump-config.zh.md: 5e173305a6cd03de3db4c763f26eeda6fba68ec7
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-composer-stats-and-input-polish.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-composer-stats-and-input-polish.i18n.yaml
deleted file mode 100644
index 653b7c0554..0000000000
--- a/.agents/notes/implemented/feature/2026-07-30-web-composer-stats-and-input-polish.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-30-web-composer-stats-and-input-polish.md
-2026-07-30-web-composer-stats-and-input-polish.md: 78f286cb0edf58d0212492024b8706ffd432ee70
-2026-07-30-web-composer-stats-and-input-polish.zh.md: eeba56d9f3c2ef10222e32b0809e099f60181ac8
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.i18n.yaml
deleted file mode 100644
index b3e0c18cdd..0000000000
--- a/.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-30-web-context-injection-disclosure.md
-2026-07-30-web-context-injection-disclosure.md: 84c3259f3f226e501a671cc55cacf7d7d96f61fb
-2026-07-30-web-context-injection-disclosure.zh.md: 4d77e06e27badb02fb73ca2ea2a739b33c5804de
diff --git a/.agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.i18n.yaml
deleted file mode 100644
index efc896170b..0000000000
--- a/.agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-31-hover-card-click-copy.md
-2026-07-31-hover-card-click-copy.md: c87734fe328fa2adb396d6685495faa82bc1fff2
-2026-07-31-hover-card-click-copy.zh.md: 2d3bc893dd617a3e2e21431175c54bcd4b7ed598
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-cards-toolrow.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-cards-toolrow.i18n.yaml
deleted file mode 100644
index 991243278a..0000000000
--- a/.agents/notes/implemented/feature/2026-07-31-web-cards-toolrow.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-31-web-cards-toolrow.md
-2026-07-31-web-cards-toolrow.md: caa18563a9e66f882873e8d7e84cc3ac20702033
-2026-07-31-web-cards-toolrow.zh.md: 7eb53a163f1fd22e09fcf498cb3e6b138834a2f3
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
index f9c6976a0d..abb67be310 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.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 .agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
-2026-08-04-web-context-source-and-steer-marks.md: 9070ea6ed34fffecd9fd2b90275bd31155100c75
-2026-08-04-web-context-source-and-steer-marks.zh.md: 9d7c7c0a34587071e281ff8b2cb77e359a1580c1
+2026-08-04-web-context-source-and-steer-marks.md: ca44702cf637c4250d141396ac22d206a16acc15
+2026-08-04-web-context-source-and-steer-marks.zh.md: 09cefd07e3b417b63f05ce430cfed7b30597452f
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
index 9070ea6ed3..ca44702cf6 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
@@ -14,13 +14,13 @@ The distinctions are already durable. `user/message.source` is the merge-extensi
 
 The transcript names all three roles a non-prompt message can play — injected context, recalled session, and steering.
 
-`TranscriptAdapter` and the history fold attach a `provenance` view to every `ContextMessageNode`, computed by `contextProvenance()` from the durable source alone. It returns a `role` (`inject`, or `recall` for a cross-session snapshot) and a `label` naming the producer. `ContextInjectionRow` titles itself from the role and shows the label beside that title in `ToolRow`'s summary geometry, so the collapsed row already answers what was added and by whom; the 141px scrollport and truncation bound are unchanged from the [disclosure decision](2026-07-30-web-context-injection-disclosure.md). What renders inside that scrollport is chosen by the independent form axis added in the [context form decision](2026-08-05-context-form-vocabulary.md).
+`TranscriptAdapter` and the history fold attach a `provenance` view to every `ContextMessageNode`, computed by `contextProvenance()` from the durable source alone. It returns a `role` (`inject`, or `recall` for a cross-session snapshot) and a `label` naming the producer. `ContextInjectionRow` titles itself from the role and shows the label beside that title in `ToolRow`'s summary geometry, so the collapsed row already answers what was added and by whom; the 141px scrollport and truncation bound are unchanged from the [archived disclosure decision](../../archived/feature/2026-07-30-web-context-injection-disclosure.md). What renders inside that scrollport is chosen by the independent form axis added in the [context form decision](2026-08-05-context-form-vocabulary.md).
 
 **The label is read out of the log, never from a client-side table of producer names.** `workspace-instructions` is named by the distinct instruction paths it reconciled, `session-reference` by the titles of the sessions it read, a plugin source by its logged plugin id, and any other source by its own `kind` — the documented default arm for a merge-extensible union. A source carrying no readable kind degrades to an unnamed injection. A new or renamed producer is therefore identifiable without a client release, no label can go stale against the code, and a resumed, forked, or foreign log projects exactly like a live session.
 
 `recall` covers `session-reference` because that is the one shipped source that lifts another session's material into this one. No Web leaf mounts `dsh-session-reference` today — it had only a terminal host — so the arm exists for log portability rather than for a bundled producer, and it is exercised by unit coverage rather than an assembled Web scenario.
 
-`MessageItem` captions durable and pending steering bubbles with `插话`. The runtime replays durable `agent/inbox/spliced` events and projects a user-origin `user/message` as `SteeringMessageNode` when that same message identity was claimed from `next-step`; a queued-turn claim stays a `UserMessageNode`, and a non-user next-step message stays context. This reverses one clause of [no steer entry or interjection chrome](../simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md), which removed the badge because the composer could not steer and the label named a gesture users could not perform. The composer gained a Steer gesture afterwards without amending that note; this decision supplies the product decision its reintroduction clause required, and corrects the stale facts left in it. The caption is the only steering chrome here: composer modes, the Queue dock's strict-steer action, and pending-steering lifecycle stay with their own owners.
+`MessageItem` captions durable and pending steering bubbles with `插话`. The runtime replays durable `agent/inbox/spliced` events and projects a user-origin `user/message` as `SteeringMessageNode` when that same message identity was claimed from `next-step`; a queued-turn claim stays a `UserMessageNode`, and a non-user next-step message stays context. This reverses one clause of the [archived no-steer decision](../../archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md), which removed the badge because the composer could not steer and the label named a gesture users could not perform. The composer gained a Steer gesture afterwards without amending that note; this decision supplies the product decision its reintroduction clause required, and corrects the stale facts left in it. The caption is the only steering chrome here: composer modes, the Queue dock's strict-steer action, and pending-steering lifecycle stay with their own owners.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
index 9d7c7c0a34..09cefd07e3 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
@@ -14,13 +14,13 @@ Status: implemented
 
 transcript 为非提示消息可能承担的三种角色分别命名：注入上下文、召回会话、steering。
 
-`TranscriptAdapter` 与历史折叠为每个 `ContextMessageNode` 附加一份 `provenance` 视图，由 `contextProvenance()` 仅依据持久来源计算得出。它返回 `role`（`inject`，跨会话快照则为 `recall`）与命名生产者的 `label`。`ContextInjectionRow` 以角色作为标题，并按 `ToolRow` 摘要的几何在标题旁展示该名称，因此折叠态就已经回答了「注入了什么、由谁注入」；141px 滚动视口与截断上限沿用[展开项决策](2026-07-30-web-context-injection-disclosure.md)，未作改动。视口里渲染什么，则由[上下文形态决策](2026-08-05-context-form-vocabulary.md)引入的、相互独立的形态轴决定。
+`TranscriptAdapter` 与历史折叠为每个 `ContextMessageNode` 附加一份 `provenance` 视图，由 `contextProvenance()` 仅依据持久来源计算得出。它返回 `role`（`inject`，跨会话快照则为 `recall`）与命名生产者的 `label`。`ContextInjectionRow` 以角色作为标题，并按 `ToolRow` 摘要的几何在标题旁展示该名称，因此折叠态就已经回答了「注入了什么、由谁注入」；141px 滚动视口与截断上限沿用[已归档的展开项决策](../../archived/feature/2026-07-30-web-context-injection-disclosure.md)，未作改动。视口里渲染什么，则由[上下文形态决策](2026-08-05-context-form-vocabulary.md)引入的、相互独立的形态轴决定。
 
 **名称从日志中读出，绝不来自客户端维护的生产者名称表。** `workspace-instructions` 以它对账过的去重指令文件路径命名，`session-reference` 以它读取的会话标题命名，插件来源以其记录的插件 id 命名，其余来源则以自身的 `kind` 命名——这正是可合并扩展联合类型有文档记载的默认分支。没有可读 kind 的来源降级为无名注入。于是新增或重命名的生产者无需客户端发版即可辨识，任何名称都不会相对代码变味，恢复、fork 或来自外部的日志与实时会话的投影结果完全一致。
 
 `recall` 覆盖 `session-reference`，因为它是当前唯一会把另一个会话的材料搬进本会话的已发布来源。今天没有任何 Web 叶子挂载 `dsh-session-reference`——它此前只有终端宿主——因此该分支的存在是为了日志可移植性，而不是为了某个已打包的生产方，其覆盖来自单元测试而非组装后的 Web 场景。
 
-`MessageItem` 为持久与待处理的 steering 气泡加上 `插话` 标注。runtime 会重放持久 `agent/inbox/spliced` 事件；如果一条用户来源的消息以相同身份从 `next-step` 被领取，后续 `user/message` 就投影为 `SteeringMessageNode`。从排队轮次领取的消息仍是 `UserMessageNode`，非用户来源的 next-step 消息仍是上下文。这推翻了[取消 steer 入口与插话装饰](../simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md)中的一条结论。当时移除徽章，是因为 composer 无法 steer，标签指向了用户做不到的动作。此后 composer 获得了 Steer 手势，却没有同步修订那份 note；本决策提供了它在「重新引入」条款中要求的产品决策，并订正了其中留下的过时事实。标注是这里唯一的 steering 装饰：composer 模式、Queue dock 的严格 steer 操作、待处理 steering 的生命周期仍归各自的所有者。
+`MessageItem` 为持久与待处理的 steering 气泡加上 `插话` 标注。runtime 会重放持久 `agent/inbox/spliced` 事件；如果一条用户来源的消息以相同身份从 `next-step` 被领取，后续 `user/message` 就投影为 `SteeringMessageNode`。从排队轮次领取的消息仍是 `UserMessageNode`，非用户来源的 next-step 消息仍是上下文。这推翻了[已归档的取消 steer 入口与插话装饰决策](../../archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md)中的一条结论。当时移除徽章，是因为 composer 无法 steer，标签指向了用户做不到的动作。此后 composer 获得了 Steer 手势，却没有同步修订那份 note；本决策提供了它在「重新引入」条款中要求的产品决策，并订正了其中留下的过时事实。标注是这里唯一的 steering 装饰：composer 模式、Queue dock 的严格 steer 操作、待处理 steering 的生命周期仍归各自的所有者。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index f58f595671..4acabc8700 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: ef100f96b06c454cfd1ec092cc7fd23e712bdf7a
-2026-06-20-core-data-structures-catalog.zh.md: 0545235f96341a638c43805de1b47a400d69e618
+2026-06-20-core-data-structures-catalog.md: 7ee1e0ac3df7cb37fc9797702d44f409da820a94
+2026-06-20-core-data-structures-catalog.zh.md: 7cb0ae216f5c5f429c18d097862350997a8335d3
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index ef100f96b0..7ee1e0ac3d 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -8,7 +8,7 @@ English | [中文](2026-06-20-core-data-structures-catalog.zh.md)
 
 A reader trying to understand the harness could find its *behavior* in [architecture.md](../../../../docs/architecture.md) (the service map, the session/turn/step lifecycle, the event taxonomy) but had no single place describing its *vocabulary* — the data structures that behavior moves around. The type shapes lived only in source, scattered across `packages/*/src/types.ts`, so understanding "what is a `Message`, a `SessionEvent`, a `StreamChunk`" meant reading the declarations directly. A prose catalog would help, but a catalog that paraphrases or paste-copies type definitions rots the instant a field changes — and an out-of-sync type doc is worse than none, because a reader trusts it.
 
-So the work had two intertwined questions: **what belongs in such a catalog** (the scoping problem — a harness has dozens of cross-package types and dumping all of them helps no one), and **how to keep pasted type definitions from drifting** (the durability problem). This Agent Note records both decisions. Its sibling, [the generated cordis events + services catalog](2026-06-20-generated-cordis-catalog.md), is the *wiring*-axis complement: this one catalogs the data structures, that one the events and services that move them.
+So the work had two intertwined questions: **what belongs in such a catalog** (the scoping problem — a harness has dozens of cross-package types and dumping all of them helps no one), and **how to keep pasted type definitions from drifting** (the durability problem). This Agent Note records both decisions. Its historical sibling, [the archived generated Cordis events + services catalog decision](../../archived/process/2026-06-20-generated-cordis-catalog.md), is the *wiring*-axis complement: this one catalogs the data structures, that one the events and services that move them.
 
 ## Decision
 
@@ -50,7 +50,7 @@ The durability requirement was specific: the doc shows the **literal** current t
 
 The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and definitions, the schema DSL, presentation types, and the session/persistence split before adoption.
 
-`verify-type-equiv` must scan the complete Markdown scope, not only manifest-named documents. Otherwise an unmanifested `type-equiv` block escapes the claimed one-to-one check. The gate therefore reports such blocks as orphans. This Agent Note records that fail-closed scan rule together with the spine-vs-seam and verbatim-match decisions; the generated Cordis catalog has the symmetric design record in [its Agent Note](2026-06-20-generated-cordis-catalog.md).
+`verify-type-equiv` must scan the complete Markdown scope, not only manifest-named documents. Otherwise an unmanifested `type-equiv` block escapes the claimed one-to-one check. The gate therefore reports such blocks as orphans. This Agent Note records that fail-closed scan rule together with the spine-vs-seam and verbatim-match decisions; the generated Cordis catalog has the symmetric design record in [its archived Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md).
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 0545235f96..7cb0ae216f 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 试图理解 harness 的读者可以在 [architecture.md](../../../../docs/architecture.md) 中找到它的*行为*（服务图、会话/轮次/步骤生命周期、事件分类），却找不到一个统一描述其*词汇*的地方，也就是这些行为所传递的数据结构。类型形状只存在于源码中，散落在 `packages/*/src/types.ts` 各处，因此要理解「什么是 `Message`、`SessionEvent`、`StreamChunk`」，就必须直接阅读声明。文字目录会有所帮助，但复述或复制粘贴类型定义的目录会在字段发生变化时立即腐化，而不同步的类型文档比没有文档更糟，因为读者会信任它。
 
-因此，这项工作有两个相互交织的问题：**这样的目录应包含什么**（范围问题——harness 有数十种跨包边界的类型，把它们全部倾倒进来对谁都没有帮助），以及**如何避免粘贴的类型定义发生漂移**（持久性问题）。本 Agent Note 记下了这两项决策。与它配套的[生成的 Cordis 事件与服务目录](2026-06-20-generated-cordis-catalog.md)从*接线*维度形成补充：本文对数据结构编目，另一篇则对传递这些结构的事件和服务编目。
+因此，这项工作有两个相互交织的问题：**这样的目录应包含什么**（范围问题——harness 有数十种跨包边界的类型，把它们全部倾倒进来对谁都没有帮助），以及**如何避免粘贴的类型定义发生漂移**（持久性问题）。本 Agent Note 记下了这两项决策。与它历史上配套的[已归档的 Cordis 事件与服务目录自动生成决策](../../archived/process/2026-06-20-generated-cordis-catalog.md)从*接线*维度形成补充：本文对数据结构编目，另一篇则对传递这些结构的事件和服务编目。
 
 ## 决策
 
@@ -50,7 +50,7 @@ Status: implemented
 
 主干与 seam 规则在采纳前经过了 `BashExecRequest`、工具 schema 与定义、schema DSL、展示类型以及会话/持久化拆分的逐一测试。
 
-`verify-type-equiv` 必须扫描完整的 Markdown 范围，而不仅是 manifest 点名的文档。否则，未列入清单的 `type-equiv` 块就会逃过所宣称的一一检查。因此，门禁会将此类块报告为未列入清单的块。本 Agent Note 将这条默认拒绝放行的扫描规则，连同主干与 seam 的分界决策及逐字匹配决策一并记录；生成的 Cordis 目录在[其 Agent Note](2026-06-20-generated-cordis-catalog.md) 中有对称的设计记录。
+`verify-type-equiv` 必须扫描完整的 Markdown 范围，而不仅是 manifest 点名的文档。否则，未列入清单的 `type-equiv` 块就会逃过所宣称的一一检查。因此，门禁会将此类块报告为未列入清单的块。本 Agent Note 将这条默认拒绝放行的扫描规则，连同主干与 seam 的分界决策及逐字匹配决策一并记录；生成的 Cordis 目录在[其已归档的 Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md) 中有对称的设计记录。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.i18n.yaml
deleted file mode 100644
index 00064dc95b..0000000000
--- a/.agents/notes/implemented/process/2026-06-20-generated-cordis-catalog.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/process/2026-06-20-generated-cordis-catalog.md
-2026-06-20-generated-cordis-catalog.md: 5005e50a2e23c8286a8057dc57f365554bde5056
-2026-06-20-generated-cordis-catalog.zh.md: 384e00d23aafeec7c7bed9bf572a628f77150993
diff --git a/.agents/notes/implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.i18n.yaml
deleted file mode 100644
index 4c0e0c5b0d..0000000000
--- a/.agents/notes/implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-26-eventsource-parser-for-deepseek-sse.md
-2026-07-26-eventsource-parser-for-deepseek-sse.md: e7835bc738b3dec5aefd6011848525f6604e852e
-2026-07-26-eventsource-parser-for-deepseek-sse.zh.md: 7c746079aa7012115bea05ec0191d665c8f860d2
diff --git a/.agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.i18n.yaml
deleted file mode 100644
index 17590b4a15..0000000000
--- a/.agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-26-turndown-for-tool-web-html-markdown.md
-2026-07-26-turndown-for-tool-web-html-markdown.md: 0e387021e3d3be3011cc0d64d37864b30aec4fdf
-2026-07-26-turndown-for-tool-web-html-markdown.zh.md: 6c9b9a22dbb556cdf4eef210705e2a7e265447c4
diff --git a/.agents/notes/implemented/simplification/2026-07-30-sidebar-resize-without-visible-pill.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-30-sidebar-resize-without-visible-pill.i18n.yaml
deleted file mode 100644
index 76604171be..0000000000
--- a/.agents/notes/implemented/simplification/2026-07-30-sidebar-resize-without-visible-pill.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-30-sidebar-resize-without-visible-pill.md
-2026-07-30-sidebar-resize-without-visible-pill.md: cc41898990fa23ff2937140186a8324217911d2e
-2026-07-30-sidebar-resize-without-visible-pill.zh.md: 9f1f521df2848b15f5015719bfa6f0e0e9b7be0c
diff --git a/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml
deleted file mode 100644
index 00c51f7dff..0000000000
--- a/.agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-31-web-ui-no-steer-entry-or-interjection-chrome.md
-2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md: e2d821f3951af472ef1a13b7b6df88a3aa96a318
-2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md: b55d4a271e0c5f2729222f4652fb0cb43e5cc9f9
diff --git a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml
index c0a15302a9..8ff1af7e8e 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.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 .agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
-2026-08-03-explicit-config-dsh-entrypoint.md: bbb40babf8abca726126678f4bccb40a63160568
-2026-08-03-explicit-config-dsh-entrypoint.zh.md: a97221a73bab0b181562ddfb7ddab1211f87f168
+2026-08-03-explicit-config-dsh-entrypoint.md: e0d1e954d9cef472ea59345a3d2ef5a67bd03ae8
+2026-08-03-explicit-config-dsh-entrypoint.zh.md: b5b464e3b45a6f3909bbf087f7005ad3f819424a
diff --git a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.md b/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
index bbb40babf8..e0d1e954d9 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
+++ b/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
@@ -20,7 +20,7 @@ The CLI no longer ships a TUI application. Its TUI overlay, launcher, first-run
 
 `dsh web` retains the shared base plus Web overlay and personal-or-explicit user layer. `dsh -p` retains the one-shot Web/headless composition. The reusable TUI package initially remained after this entrypoint change, then [the package-wide removal decision](2026-08-04-remove-tui-package.md) deleted it and its SDK interface.
 
-This decision supersedes the `dsh`-specific parts of the [dedicated TUI front door](../../archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md), [personal config](../feature/2026-07-20-dsh-cli-personal-config.md), [guided skill commands](../../archived/feature/2026-07-28-dsh-guided-skill-session-commands.md), [meta workspace](../../archived/feature/2026-07-28-dsh-meta-source-workspace.md), [shared config overlays](2026-07-29-shared-base-config-overlays.md), [config dump](../feature/2026-07-30-dsh-dump-config.md), [first-run welcome](../../archived/feature/2026-07-30-versioned-tui-first-run-welcome.md), and [experimental subcommand gate](../../archived/feature/2026-07-31-experimental-subcommand-gate.md) notes. The later [package-wide removal decision](2026-08-04-remove-tui-package.md) supersedes their reusable-package decisions and consolidates the deleted launcher-identity record.
+This decision supersedes the `dsh`-specific parts of the [dedicated TUI front door](../../archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md), [personal config](../feature/2026-07-20-dsh-cli-personal-config.md), [guided skill commands](../../archived/feature/2026-07-28-dsh-guided-skill-session-commands.md), [meta workspace](../../archived/feature/2026-07-28-dsh-meta-source-workspace.md), [shared config overlays](2026-07-29-shared-base-config-overlays.md), [config dump](../../archived/feature/2026-07-30-dsh-dump-config.md), [first-run welcome](../../archived/feature/2026-07-30-versioned-tui-first-run-welcome.md), and [experimental subcommand gate](../../archived/feature/2026-07-31-experimental-subcommand-gate.md) notes. The later [package-wide removal decision](2026-08-04-remove-tui-package.md) supersedes their reusable-package decisions and consolidates the deleted launcher-identity record.
 
 ## Verification
 
diff --git a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md b/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
index a97221a73b..b5b464e3b4 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
@@ -20,7 +20,7 @@ CLI 不再交付 TUI 应用。TUI overlay、启动器、首次运行 onboarding
 
 `dsh web` 保留共享 base、Web overlay 与个人或显式用户层。`dsh -p` 保留一次性 Web/headless 组合。可复用 TUI 包（package）在本入口变更后起初保留，随后[全包移除决策](2026-08-04-remove-tui-package.md)将其及 SDK 接口删除。
 
-本决策取代以下记录中专用于 `dsh` 的部分：[独立 TUI 入口](../../archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md)、[个人配置](../feature/2026-07-20-dsh-cli-personal-config.md)、[引导式 skill 命令](../../archived/feature/2026-07-28-dsh-guided-skill-session-commands.md)、[meta workspace](../../archived/feature/2026-07-28-dsh-meta-source-workspace.md)、[共享配置 overlay](2026-07-29-shared-base-config-overlays.md)、[配置转储](../feature/2026-07-30-dsh-dump-config.md)、[首次运行欢迎页](../../archived/feature/2026-07-30-versioned-tui-first-run-welcome.md)和[实验性子命令门禁](../../archived/feature/2026-07-31-experimental-subcommand-gate.md)。后续的[全包移除决策](2026-08-04-remove-tui-package.md)取代了其中关于可复用包的决策，并整合了已删除的启动器身份记录。
+本决策取代以下记录中专用于 `dsh` 的部分：[独立 TUI 入口](../../archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md)、[个人配置](../feature/2026-07-20-dsh-cli-personal-config.md)、[引导式 skill 命令](../../archived/feature/2026-07-28-dsh-guided-skill-session-commands.md)、[meta workspace](../../archived/feature/2026-07-28-dsh-meta-source-workspace.md)、[共享配置 overlay](2026-07-29-shared-base-config-overlays.md)、[配置转储](../../archived/feature/2026-07-30-dsh-dump-config.md)、[首次运行欢迎页](../../archived/feature/2026-07-30-versioned-tui-first-run-welcome.md)和[实验性子命令门禁](../../archived/feature/2026-07-31-experimental-subcommand-gate.md)。后续的[全包移除决策](2026-08-04-remove-tui-package.md)取代了其中关于可复用包的决策，并整合了已删除的启动器身份记录。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml b/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml
deleted file mode 100644
index f3676ba1ef..0000000000
--- a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
-2026-07-26-execa-for-test-subprocess-plumbing.md: 958abc4aee94adb3e6206cc299595ad92bde4044
-2026-07-26-execa-for-test-subprocess-plumbing.zh.md: 5ccadd93a182ba299be80d48881fe1c470a2d537
diff --git a/.agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.i18n.yaml b/.agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.i18n.yaml
deleted file mode 100644
index ec95910194..0000000000
--- a/.agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/rejected/architecture/2026-07-29-session-resumed-log-boundary.md
-2026-07-29-session-resumed-log-boundary.md: 877b0c780f4c92983d2762243fac4e26d945887a
-2026-07-29-session-resumed-log-boundary.zh.md: a6f6ecc0d3f3a349f1a438eec0a84f27f8f649b2
diff --git a/.agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.md b/.agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.md
deleted file mode 100644
index 877b0c780f..0000000000
--- a/.agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# Agent Note: Record the resume process boundary in the session log
-
-Status: rejected — the boundary belongs at the seeded-`Session` constructor, which also covers fork and replay; superseded by [the end-seed boundary](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)
-
-English | [中文](2026-07-29-session-resumed-log-boundary.zh.md)
-
-## Problem
-
-A session's durable log gave no evidence that it had changed processes. `session/created`, `session/disposed`, and `session/flush` are cordis runtime signals rather than `SessionEventMap` members, and `agent/session-start` carries a `SessionStartSource` but is emit-only and never logged. Reading a stored log therefore gave no hint that anything had been resumed.
-
-That gap makes one class of question unanswerable. A plugin that owns a standalone open/close pair in the log — compaction's `compact/start` … `compact/end` is the only one today — must distinguish an unmatched opening marker left by a process that died mid-operation from one an operation is holding right now. Those two states are **byte-identical in stored history**. Without a boundary the owner has to choose between refusing forever (an unmatched marker wedges the operation permanently, and because automatic compaction failure is warn-and-continue the user-visible result is that compaction silently stops working until the context window overflows) and proceeding always (which defeats the point of holding a lock).
-
-The pressure to fix this is immediate: moving `compact/start` to its real time point, before summarization, widens the crash window from a few microseconds of synchronous appends to the length of a whole model call, so orphaned brackets go from rare to routine.
-
-## Proposal
-
-`@deepseek-ai/dsh-session-persistence` declares one log-only `session/resumed` with an empty payload and appends exactly one at the end of every cold load, in the same `commitRepair` batch as any crash-repair closers and positioned after them — so every event before the boundary has a smaller seq and was written by a writer that is no longer tracking this log. Ownership lands narrowly on `loadCore()`, the cold-load path reached by `load()` and by `adopt()`. `loadLiveSnapshot()` appends nothing, and the non-mutating `inspect()`/`readFrom()` reads never write one.
-
-The predicate a bracket owner evaluates is purely a function of the log: an unmatched opening marker with a `session/resumed` after it is stale, and one with no `session/resumed` after it is live.
-
-`time` is `Date.now()` floored at the log's greatest `time`, deliberately unlike the synthetic closers, which reuse the last real event's timestamp so repair output stays a deterministic function of stored history. The wall clock is not monotonic — an NTP step, a VM restore, or a log copied from a machine that was ahead can put it behind events already stored — so the floor keeps every cross-boundary duration non-negative. The floor is durable, because the clamped boundary is stored and joins the log's maximum: one future-dated event pins every later boundary in that log to the same instant until wall time passes it.
-
-**The predicate distinguishes process succession, not concurrent writers.** `load()`'s liveness guard is `ctx.sessions.get(id)`, which only sees sessions live in *this* runtime, and no backend takes a cross-process per-session lock. So process B cold-loading a session A currently owns writes a boundary after A's still-open bracket. A consumer that must tolerate concurrent writers still needs a liveness signal beyond the log.
-
-## Why this was rejected
-
-Two reasons, found while reviewing where the marker belonged.
-
-**It covers no fork.** `sessions.fork()` and a subagent fork child construct a seeded session without touching persistence, so neither gets a boundary. A forked child inherits its parent's prefix verbatim — including an open `compact/start` the parent is still holding — which is the one case where the inherited bracket's owner is demonstrably alive. The predicate was unavailable exactly where it was most needed.
-
-**Minting the marker at load made a read path a durable write.** Every consequence the review surfaced traced to that: a revision bump on every cold load, a `commitRepair` batch on a balanced log with nothing to repair, the durable time floor above, a load that fails against a read-only store, and a marked log after a resume the caller then cancelled. None of these are wrong given the placement; they are the placement's cost.
-
-The successor keeps the problem statement and the concurrent-writer scope limit unchanged, and moves the write to `Session`'s constructor — the single waist all six seeded-start paths pass through, fork included. Because the marker then rides the ordinary seed-persistence path, the whole durable-write surface above disappears.
-
-## Alternatives considered
-
-**Use `Session.firstLiveSeq` as the staleness predicate.** Dismissed here on the grounds that it is documented as deliberately not persisted, so the same stored log yields different answers in different processes and a read-only reader cannot evaluate it at all. That reasoning was sound about the field and wrong about the conclusion: the fix is to persist a projection of it rather than to compute the boundary somewhere else. This is the alternative that became the successor.
-
-**Declare the event in core (`dsh-session`).** Rejected here because "the constructor cannot distinguish resume from fork or replay." That is true and turned out not to matter — the distinction is not needed, since inherited history is dead history in all three cases.
-
-**Teach `interruptedTurnClosers` to close `compact/*`.** Rejected: `compact/*` is plugin-owned vocabulary and core must not know it. Core closes turn, step, and tool boundaries — the relations it owns. The successor keeps this rejection.
-
-**Lazy self-repair: the owner appends a synthetic closing marker when it finds an orphan.** A write inside a read-shaped check, and it needs an invariant exception for a numbered owner whose turn has already closed.
-
-**A merge-extensible repair-contributor registry in core.** The right shape once a second consumer exists; with one consumer today, `packages/AGENTS.md` says not to split a seam preemptively.
-
-**Write the boundary only when repair actually occurred.** Rejected: the predicate must hold for an orderly restart too, where there is nothing to repair. The successor keeps this rejection.
-
-## Related
-
-The cold-session `updatedAt` skew this proposal documented is scoped in [the last-activity-index Agent Note](../../proposed/architecture/2026-07-29-durable-last-activity-index.md). That defect predates this proposal and survives its rejection: it is caused by mtime counting every durable write, not by any one boundary.
diff --git a/.agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.zh.md b/.agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.zh.md
deleted file mode 100644
index a6f6ecc0d3..0000000000
--- a/.agents/notes/rejected/architecture/2026-07-29-session-resumed-log-boundary.zh.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# Agent Note: 在会话日志中记录恢复的进程边界
-
-Status: rejected — 边界应当落在带种子 `Session` 的构造函数上，那里同时覆盖 fork 与回放；由[种子结束边界](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)取代
-
-[English](2026-07-29-session-resumed-log-boundary.md) | 中文
-
-## Problem
-
-会话的持久日志此前无法证明它换过进程。`session/created`、`session/disposed` 和 `session/flush` 是 cordis 运行时信号，而不是 `SessionEventMap` 成员；`agent/session-start` 虽然携带 `SessionStartSource`，却只用于 emit，从不记录。因此，读取一份已存储日志得不到任何关于「曾经发生过恢复」的线索。
-
-这一空缺让一类问题无法回答。在日志中拥有独立开始／结束事件对的插件必须区分两种未匹配的起始标记：一种由某个在操作中途死亡的进程留下，另一种正被当前某项操作持有；今天符合这一形态的只有压缩的 `compact/start` … `compact/end`。这两种状态**在已存储历史中逐字节相同**。没有边界，所有方只能在两种做法之间选择：永远拒绝（一个未匹配的标记会永久卡住该操作，而自动压缩失败采取警告并继续的策略，因此用户可见的结果是压缩静默停止工作，直到上下文窗口溢出），或者始终继续（这让持有锁失去了意义）。
-
-修复它的压力是即刻的：把 `compact/start` 移到摘要生成之前这个真实的时间点，会把崩溃窗口从几微秒的同步追加扩大为一整次模型调用的时长，孤儿括号也就从罕见变为常态。
-
-## Proposal
-
-`@deepseek-ai/dsh-session-persistence` 声明唯一一个纯日志事件 `session/resumed`，其载荷为空，并在每次冷加载结束时恰好追加一条：与崩溃修复产生的 closers 同处一个 `commitRepair` 批次，且排在它们之后。因此，该边界之前的每个事件都有更小的 seq，并且都是由一个不再追踪这份日志的写入方写下的。所有权狭窄地落在 `loadCore()`，也就是 `load()` 与 `adopt()` 到达的冷加载路径。`loadLiveSnapshot()` 不追加任何内容，非变更性的 `inspect()`／`readFrom()` 读取也从不写入。
-
-括号所有方求值的谓词纯粹是日志的函数：未匹配的起始标记之后有 `session/resumed` 的就是陈旧的，之后没有的就是存活的。
-
-`time` 取 `Date.now()` 并以日志的最大 `time` 为下限，刻意区别于合成 closers——后者复用最后一个真实事件的时间戳，以便修复输出始终是已存储历史的确定性函数。挂钟并非单调：一次 NTP 跳变、一次虚拟机恢复，或一份从走快的机器上拷来的日志，都可能让它落在已存储事件之后，因此这个下限让跨边界的时长都非负。该下限是持久的，因为被钳制的边界本身会被存储并加入日志的最大值：一个未来时间的事件会把该日志中之后的每个边界都钉在同一时刻，直到挂钟时间越过它。
-
-**该谓词区分的是进程接替，不是并发写入方。** `load()` 的存活性守卫是 `ctx.sessions.get(id)`，它只看到*本*运行时中存活的会话，而且没有任何后端会取跨进程的按会话锁。因此，进程 B 冷加载一个 A 当前拥有的会话时，会在 A 仍然开放的括号之后写入一个边界。必须容忍并发写入方的消费方仍然需要日志之外的存活信号。
-
-## 为什么被否决
-
-两个原因，都是在复审标记应当落在何处时发现的。
-
-**它完全覆盖不到 fork。** `sessions.fork()` 与子代理 fork 子会话在不触及持久化的情况下构造带种子会话，因此两者都拿不到边界。fork 子会话会逐字节继承父会话的前缀——包括父会话仍然持有的开放 `compact/start`——而这恰恰是继承括号的所有方明显还活着的唯一情形。谓词偏偏在最需要它的地方不可用。
-
-**在加载时铸造标记，把读取路径变成了持久写入。** 复审暴露出的每一项后果都源于此：每次冷加载都递增 revision、对一份无需修复的平衡日志也要走 `commitRepair`、上文那个持久时间下限、加载在只读存储上会失败，以及调用方随后取消的恢复也已留下标记。这些在该放置方式下都不算错，它们就是该放置方式的成本。
-
-取代方案保留问题陈述与并发写入方的适用范围限制不变，并把写入移到 `Session` 的构造函数——全部六条带种子启动路径（含 fork）必经的唯一收窄处。由于标记随后走普通的种子持久化路径，上述整个持久写入面就消失了。
-
-## Alternatives considered
-
-**用 `Session.firstLiveSeq` 作为陈旧性谓词。** 此处以「文档明确它有意不做持久化，因此同一份已存储日志在不同进程中会给出不同答案，而只读读取方根本无法对它求值」为理由否决。这个推理对字段本身是成立的，但结论错了：正确的修法是持久化它的一个投影，而不是把边界挪到别处去算。这条替代方案正是后来的取代方案。
-
-**在核心（`dsh-session`）中声明该事件。** 此处以「构造函数无法把恢复与 fork 或回放区分开」为理由否决。这句话是对的，但事实证明它无关紧要——并不需要这种区分，因为在这三种情形下继承历史都是死历史。
-
-**教 `interruptedTurnClosers` 关闭 `compact/*`。** 否决：`compact/*` 是插件所属词汇，核心不得知道它。核心只关闭轮次、步骤和工具边界，也就是它自己拥有的关系。取代方案保留这条否决。
-
-**惰性自修复：所有方发现孤儿时自行追加一条合成的关闭标记。** 这是在一次形似读取的检查中执行写入，而且需要为一个带轮次编号、其轮次却已经关闭的所有方开一个不变式例外。
-
-**在核心中建一个可合并扩展的修复贡献方注册表。** 一旦出现第二个消费方，这就是正确的形状；今天只有一个消费方，而 `packages/AGENTS.md` 要求不要预先拆分 seam。
-
-**仅在确实发生了修复时才写入边界。** 否决：该谓词对有序重启同样必须成立，而那时没有任何东西需要修复。取代方案保留这条否决。
-
-## 相关
-
-本提案记录过的冷会话 `updatedAt` 偏斜，范围界定在[最后活动索引 Agent Note](../../proposed/architecture/2026-07-29-durable-last-activity-index.md)。该缺陷早于本提案存在，并且在本提案被否决后依然存在：它的成因是 mtime 会计入每一次持久写入，而不是某一个边界。
diff --git a/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.i18n.yaml
deleted file mode 100644
index ea631fa09c..0000000000
--- a/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.md
-2026-07-04-prune-unimplemented-subagent-vocabulary.md: 276e832af695acbcf70103def8b51fb8c6e1033f
-2026-07-04-prune-unimplemented-subagent-vocabulary.zh.md: 81b79c77a055f97785c6a96b7b17802878ded623
diff --git a/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.md b/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.md
deleted file mode 100644
index 276e832af6..0000000000
--- a/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Agent Note: Prune the unimplemented subagent seam vocabulary
-
-Status: rejected — the deferred capability vocabulary (`outputSchema`/`structured`, `toolFilter`, `sendMessage`/`resume`) is intentionally reserved surface: the seam advertises the full intended contract ahead of its implementations by design, so providers and consumers grow into a stable shape rather than re-negotiating it per capability. The consumer-evidence analysis below records the decision-time state.
-
-English | [中文](2026-07-04-prune-unimplemented-subagent-vocabulary.zh.md)
-
-## Problem
-
-The [subagent seam](../../implemented/feature/2026-06-21-subagent-capability-seam.md) shipped a two-tier capability design: start-time capability flags checked by the service, and optional runtime methods on `SubagentRun`. Three start-time features and both optional runtime methods have zero implementations and zero callers:
-
-- **`outputSchema`/`structured` and `toolFilter`** (`SubagentCapabilities`, `SubagentStartRequest`, `SubagentResult` in `packages/subagent/subagent/src/types.ts`): at the decision point, every real provider declared `outputSchema: false, toolFilter: false` (`packages/subagent/subagent-spawn/src/index.ts`, `packages/subagent/subagent-fork/src/index.ts`, `packages/subagent/subagent-acp/src/index.ts`); the sole production `ctx.subagents.start` caller (`packages/subagent/tool-subagent/src/index.ts`) built `{ prompt, parent, signal?, agentOptions? }` and structurally could not set either; `structured` appeared only in the scripted test fixture. The service's capability check carried two assert rows whose only exercisers were the rejection tests.
-- **`SubagentRun.sendMessage` / `SubagentRun.resume`** (same file): implemented by NO provider — not even the mock; the spawn spec asserts their *absence*.
-
-The only reason `dsh-subagent` depended on `dsh-tools` at the decision point was `outputSchema`'s schema type (now `ObjectJsonSchema`). Three subsequent subagent workstreams (per-session snapshot replay, the fork seed boundary, the ACP backend) landed around this surface without growing a single consumer.
-
-## Proposal
-
-Remove `outputSchema`/`structured`, `toolFilter`, `sendMessage`, and `resume` from the seam; shrink `SubagentCapabilities` to `{ depthLimit }`; drop the two capability-assert rows, the all-false flags on the three providers, the scripted fixture's structured branch and capability knobs, and the tests that exist to pin the removed surface. Drop the `dsh-tools` peer/dev dependency from `packages/subagent/subagent/package.json`. Update the [subagent.md](../../../../docs/core-data-structures/subagent.md) pastes and the type-equiv manifest, plus the affected provider READMEs. The implementing PR amends the seam Agent Note's capability catalog per [implemented/AGENTS.md](../../implemented/AGENTS.md).
-
-**Keep** `depthLimit`/`maxDepth` and capability checks. The in-process backend enforces the limit, although the shipping tool does not yet set it. Recursion is a known seam risk, so the appropriate follow-up is to supply a tool default rather than delete working enforcement.
-
-Adjacent surface examined and deliberately left alone: `SubagentService.getProvider()`/`list()` have test-harness consumers only, but the [prune-dead-seam-methods implementation note](../../archived/simplification/2026-06-20-prune-dead-seam-methods.md) records precisely this shape being removed from the bash executor and reverted — a test harness IS a consumer for a one-line accessor over an already-tracked map. `SubagentRunEndInfo.lastAssistantMessage` is a recorded keep (the [subagent-observe-enrich Agent Note](../../archived/feature/2026-06-30-subagent-observe-enrich.md)'s review dropped `agentType` and kept it deliberately, as the only final-message channel for out-of-process children); its currently-unwired bridge forwarding is a gap to close or a consumer to document, not surface for this Agent Note to cut.
-
-This is the seam-vocabulary echo of [prune dead methods from the persistence seam](../../archived/simplification/2026-06-20-prune-dead-seam-methods.md): members every implementation must declare for nobody — weaker even, since here zero implementations exist.
-
-## Alternatives considered
-
-### Why not keep it?
-
-The two-kinds-of-capability design is the seam Agent Note's headline, and re-adding `outputSchema` later touches several files. But the design survives with `depthLimit` as its live example and the Agent Notes as its record, and the seam Agent Note itself concedes the shipped `toolFilter` shape is wrong (real enforcement needs a `tools/pre-execute` deny in the child's context, not schema filtering) — that deny primitive exists on the interception seams, so re-adding against a real implementing provider will pin a better contract than the current speculative one.
-
-## Acceptance criteria
-
-- The removed spellings appear only in this Agent Note and the amended seam Agent Notes; `SubagentCapabilities` is `{ depthLimit: boolean }`; the `dsh-tools` dependency edge is gone (`hygiene` green).
-- Depth-enforcement tests are unchanged and green.
-
-## Risks
-
-The subagent lifecycle events carry `lastAssistantMessage` on the end payload — that enrichment lives in the service module, not the seam vocabulary this Agent Note shrinks, and the observe-enrich Agent Note records dropping an `agentType` sibling for lacking a consumer: the judgment this Agent Note extends. The CC hooks bridge, the first outside consumer of those lifecycle events, reads only the event payloads and touches none of the surface removed here; the observe-enrich Agent Note's deferred control-flow redesign names implementing `resume` as its own future work — exactly the re-add trigger this Agent Note's pattern anticipates.
diff --git a/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.zh.md b/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.zh.md
deleted file mode 100644
index 81b79c77a0..0000000000
--- a/.agents/notes/rejected/simplification/2026-07-04-prune-unimplemented-subagent-vocabulary.zh.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Agent Note: 裁剪未实现的 subagent seam 词汇
-
-Status: rejected — 延后的能力词汇（`outputSchema`/`structured`、`toolFilter`、`sendMessage`/`resume`）是有意保留的接口面：该 seam 按设计先于实现声明完整的预期契约，使提供方与消费方沿稳定形状演进，而非针对每项能力重新协商。下方的消费方证据分析记录了决策时的状态。
-
-[English](2026-07-04-prune-unimplemented-subagent-vocabulary.md) | 中文
-
-## 问题
-
-[subagent seam](../../implemented/feature/2026-06-21-subagent-capability-seam.md) 交付了一套两层能力设计：启动时由服务检查的能力 flag，以及 `SubagentRun` 上的可选运行时方法。三个启动时功能和两个可选运行时方法的实现数与调用数均为零：
-
-- **`outputSchema`/`structured` 与 `toolFilter`**（`SubagentCapabilities`、`SubagentStartRequest`、`SubagentResult`，位于 `packages/subagent/subagent/src/types.ts`）：在作出决策时，每个真实提供方都声明 `outputSchema: false, toolFilter: false`（`packages/subagent/subagent-spawn/src/index.ts`、`packages/subagent/subagent-fork/src/index.ts`、`packages/subagent/subagent-acp/src/index.ts`）；唯一的生产环境 `ctx.subagents.start` 调用方（`packages/subagent/tool-subagent/src/index.ts`）构造 `{ prompt, parent, signal?, agentOptions? }`，结构上无法设置这两个字段；`structured` 仅出现在脚本化测试 fixture（测试前置数据）中。服务的能力检查包含两行 assert，其唯一执行者是拒绝测试。
-- **`SubagentRun.sendMessage` / `SubagentRun.resume`**（同一文件）：没有任何提供方实现——包括 mock 也没有；spawn spec 断言的正是它们的*缺失*。
-
-在作出决策时，`dsh-subagent` 依赖 `dsh-tools` 的唯一原因是 `outputSchema` 的 schema 类型（现为 `ObjectJsonSchema`）。三项后续 subagent 工作（按会话快照回放、fork seed 边界、ACP（Agent Client Protocol）后端）都围绕这块接口面落地，却连一个消费方都没有产生。
-
-## 提案
-
-从 seam 中移除 `outputSchema`/`structured`、`toolFilter`、`sendMessage` 与 `resume`；将 `SubagentCapabilities` 缩减为 `{ depthLimit }`；删除两行能力 assert、三个提供方上的 all-false flag、脚本化 fixture 的 structured 分支和能力旋钮，以及为固定被移除接口面而存在的测试。`dsh-tools` 的对等依赖（peer dependency）和开发依赖应从 `packages/subagent/subagent/package.json` 中删除。更新 [subagent.md](../../../../docs/core-data-structures/subagent.md) 中的粘贴内容与 type-equiv manifest（元数据清单），以及受影响的提供方 README。实现 PR（Pull Request）按照 [implemented/AGENTS.md](../../implemented/AGENTS.md) 修订 seam Agent Note 的能力目录。
-
-**保留** `depthLimit`/`maxDepth` 与能力检查。进程内后端已强制执行该限制，尽管当前发布的工具尚未设置它。递归是已知的 seam 风险，因此恰当的后续工作是提供一个工具默认值，而非删除正在工作的强制逻辑。
-
-审视过但有意不动的相邻接口面：`SubagentService.getProvider()`/`list()` 仅有测试 harness 消费方，但 [prune-dead-seam-methods 实现说明](../../archived/simplification/2026-06-20-prune-dead-seam-methods.md)恰好记录了这种形态从 bash 执行器中被移除后又被回退的经过——对于一个基于已跟踪 map 的单行访问器而言，测试 harness 就是消费方。`SubagentRunEndInfo.lastAssistantMessage` 是一个已记录的保留项（[subagent 观测/丰富化 Agent Note](../../archived/feature/2026-06-30-subagent-observe-enrich.md)的评审删除了 `agentType` 但有意保留了它，因为它是进程外子 agent（智能体）唯一的最终消息通道）；它当前未接通的桥接转发是一个待补的缺口或待记录的消费方，不是本 Agent Note 要裁剪的接口面。
-
-这是[从持久化 seam 裁剪死方法](../../archived/simplification/2026-06-20-prune-dead-seam-methods.md)在 seam 词汇层面的回响：每个实现都必须声明、却无人使用的成员，甚至更弱，因为这里连一个实现都没有。
-
-## 曾考虑的替代方案
-
-### 为什么不保留？
-
-两类能力的设计是 seam Agent Note 的核心亮点，日后重新添加 `outputSchema` 会涉及多个文件。但该设计以 `depthLimit` 作为活跃示例、以 Agent Note 作为记录仍然成立；而且 seam Agent Note 本身承认已交付的 `toolFilter` 形态是错误的（真正的强制需要在子 agent 上下文中实施 `tools/pre-execute` deny，而非 schema 过滤）——该 deny 原语已存在于拦截 seam 上，因此在由真实提供方实现并重新添加时，将确定一份比当前推测性契约更好的契约。
-
-## 验收标准
-
-- 被移除的拼写仅出现在本 Agent Note 和修订后的 seam Agent Note 中；`SubagentCapabilities` 为 `{ depthLimit: boolean }`；`dsh-tools` 依赖边已消除（`hygiene` 绿色）。
-- 深度强制测试不变且绿色。
-
-## 风险
-
-subagent 生命周期事件在结束载荷上携带 `lastAssistantMessage`——该增强位于服务模块中，不在本 Agent Note 缩减的 seam 词汇范围内；observe-enrich Agent Note 记录了因缺少消费方而删除 `agentType` 兄弟字段的判断，本 Agent Note 延续了这一判断。CC 钩子桥接是这些生命周期事件的第一个外部消费方，它只读取事件载荷，不涉及本文移除的任何接口面；observe-enrich Agent Note 推迟的控制流重设计将实现 `resume` 列为自身的未来工作——恰好是本 Agent Note 模式所预期的重新添加触发点。
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
index 7f8463064f..0f5dedddd2 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.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 .agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
-2026-07-26-dependency-swaps-rejected-by-nih-audit.md: 421ce93a20c567cac4d6a96f806949348dff3e6b
-2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: 8ae9eb83269a910160aef3a563dce6d83dbc7ad8
+2026-07-26-dependency-swaps-rejected-by-nih-audit.md: 538f6a41b4d2db72f867e98810e8e9382cbdac98
+2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: b3f7a1d9717397ee9ed50890bc024fba7d79fa9a
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
index 421ce93a20..538f6a41b4 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
@@ -18,7 +18,7 @@ Adopt the following dependency swaps. Rejected — per-item evidence below; a fu
 - **`vscode-languageserver-types` for lsp-local's wire-type subset**: ~80 type lines and ~45 guard lines, but upstream guards differ in both directions (accept `uri: undefined` the repo must reject; require `targetRange` the repo tolerates absent), and the initialize-result shapes live in `vscode-languageserver-protocol`, dragging `vscode-jsonrpc` in as a runtime dep — ~1 MB for 80 spec-exact lines.
 - **`json-rpc-2.0` for `dsh-jsonrpc`**: deletable correlation/dispatch is real (~100–130 lines) but the NDJSON wire must stay bit-identical for the hand-rolled Python SDK client, the package is single-maintainer, and the [GUI RPC note](../../implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md) already treats this package as a frozen narrow surface. `vscode-jsonrpc` is a worse fit still (Content-Length framing, cancellation vocabulary the protocol lacks).
 - **`jsonrpcclient` for the Python SDK client**: v4 builds/parses messages only — ~20 lines — while the 500 lines that matter (subprocess lifecycle, threaded reader, id correlation, bidirectional server-role responses) stay; the library is in low-maintenance mode.
-- **`eventsource-parser` for apiproxy's `readSse`**: only ~15 lines of framing are deletable, both wire ends are in-repo so spec conformance is moot, and it would add a dep to a browser-safe package. (Contrast with the [llm-deepseek proposal](../../implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md), where a real provider sits across the wire.)
+- **`eventsource-parser` for apiproxy's `readSse`**: only ~15 lines of framing are deletable, both wire ends are in-repo so spec conformance is moot, and it would add a dep to a browser-safe package. (Contrast with the [archived llm-deepseek dependency decision](../../archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md), where a real provider sits across the wire.)
 
 **Retry, timers, async:**
 
@@ -46,7 +46,7 @@ Adopt the following dependency swaps. Rejected — per-item evidence below; a fu
 - **`shell-quote` for POSIX single-quoting**: two 1-line quoting helpers with exhaustive tests versus a maintenance-mode package with a CVE history and different escaping output — a safety boundary is the wrong place to save one line.
 - **`strip-ansi` for pty sanitization**: the pty sanitizer is a streaming state machine with split-sequence carry across chunks and OSC `133;D` prompt-marker extraction (the shell-readiness signal); stateless strippers replace ~20 inner lines while all state machinery stays. `stripVTControlCharacters` also demonstrably leaks unterminated-OSC payloads the session-title normalizer must strip (anti-spoofing).
 - **`pidtree`/`ps-tree` for the pty process inspector**: bare PID trees; the code needs start-time identity against PID reuse plus `/proc` stdin-wait detection no package does.
-- **`execa` for the subagent-subprocess dispose ladder**: `forceKillAfterDelay` covers SIGTERM→SIGKILL but not the stdin-EOF-first cooperative tier or the reject-if-no-exit-edge contract; adopting it here rewrites spawn sites while keeping the ladder. (Test-infrastructure spawn plumbing is different — see the [execa Agent Note](../../implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.md).)
+- **`execa` for the subagent-subprocess dispose ladder**: `forceKillAfterDelay` covers SIGTERM→SIGKILL but not the stdin-EOF-first cooperative tier or the reject-if-no-exit-edge contract; adopting it here rewrites spawn sites while keeping the ladder. (Test-infrastructure spawn plumbing is different — see the [archived execa test-infrastructure decision](../../archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md).)
 - **`tree-kill` for acp-snapshot teardown and lsp process kill**: the lines are drain-ordering/error-propagation, not tree traversal; lsp/bash already use detached process groups + taskkill.
 - **node-pty everywhere for the TUI test driver**: the archived [Windows-TUI note](../../archived/feature/2026-07-20-windows-tui-support.md) explicitly rejected node-pty-on-every-host; it was already the Windows leg.
 
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
index 8ae9eb8326..b3f7a1d971 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
@@ -18,7 +18,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `vscode-languageserver-types` 承担 lsp-local 的协议类型子集**：约 80 行类型加约 45 行守卫，但上游守卫在两个方向上都与本仓库不一致（接受本仓库必须拒绝的 `uri: undefined`；强制要求本仓库容忍缺失的 `targetRange`），而且 initialize 结果的形状住在 `vscode-languageserver-protocol` 里，会把 `vscode-jsonrpc` 拖成运行时依赖——为 80 行严格贴合规范的代码付出约 1 MB。
 - **以 `json-rpc-2.0` 替换 `dsh-jsonrpc`**：可删除的关联/分发代码确实存在（约 100–130 行），但 NDJSON 协议格式（wire format）必须与手写的 Python SDK 客户端逐位一致，该包只有单一维护者，且 [GUI RPC 决策](../../implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)已把这个包当作冻结的窄接口面对待。`vscode-jsonrpc` 更不合适（Content-Length 分帧、该协议并不具备的取消词汇）。
 - **以 `jsonrpcclient` 承担 Python SDK 客户端**：v4 只做消息的构造/解析——约 20 行——而真正要紧的 500 行（子进程生命周期、线程化读取器、id 关联、双向的服务端角色应答）全都保留；该库处于低维护模式。
-- **以 `eventsource-parser` 替换 apiproxy 的 `readSse`**：可删除的分帧只有约 15 行，线路两端都在仓库内，规范符合性无关紧要，而且这会给一个浏览器安全的包添加依赖。（对比 [llm-deepseek 提案](../../implemented/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md)：那里线路对面是真实的提供方。）
+- **以 `eventsource-parser` 替换 apiproxy 的 `readSse`**：可删除的分帧只有约 15 行，线路两端都在仓库内，规范符合性无关紧要，而且这会给一个浏览器安全的包添加依赖。（对比[已归档的 llm-deepseek 依赖决策](../../archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md)：那里线路对面是真实的提供方。）
 
 **重试、定时器与异步：**
 
@@ -46,7 +46,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `shell-quote` 承担 POSIX 单引号包裹**：两个各 1 行、测试详尽的引号辅助函数，对上一个处于维护模式、有 CVE 历史、转义输出还不一样的包——安全边界不是省一行代码的地方。
 - **以 `strip-ansi` 承担 pty 净化**：pty 净化器是一台流式状态机，带跨分片的断裂序列续接和 OSC `133;D` 提示符标记提取（shell 就绪信号）；无状态的剥离器只能替掉约 20 行内层代码，全部状态机构件原样保留。`stripVTControlCharacters` 还被实证会泄漏未终止的 OSC 载荷，会话标题归一化器必须剥除它们（反欺骗）。
 - **以 `pidtree`/`ps-tree` 承担 pty 进程巡检器**：它们只给裸 PID 树；这段代码需要对抗 PID 复用的启动时间身份校验，加上 `/proc` stdin 等待检测，没有包做这些。
-- **以 `execa` 承担 subagent-subprocess 的 dispose（资源释放）阶梯**：`forceKillAfterDelay` 覆盖 SIGTERM→SIGKILL，但覆盖不了先发 stdin EOF 的协作层级，也覆盖不了「无退出沿即 reject」契约；在这里采用它意味着重写各 spawn 调用点、同时阶梯照旧保留。（测试基础设施的 spawn 管线是另一回事——见 [execa Agent Note](../../implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.md)。）
+- **以 `execa` 承担 subagent-subprocess 的 dispose（资源释放）阶梯**：`forceKillAfterDelay` 覆盖 SIGTERM→SIGKILL，但覆盖不了先发 stdin EOF 的协作层级，也覆盖不了「无退出沿即 reject」契约；在这里采用它意味着重写各 spawn 调用点、同时阶梯照旧保留。（测试基础设施的 spawn 管线是另一回事——见[已归档的 execa 测试基础设施决策](../../archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md)。）
 - **以 `tree-kill` 承担 acp-snapshot 拆除与 lsp 进程终止**：那些代码行做的是排空顺序与错误传播，不是进程树遍历；lsp/bash 已经使用分离的进程组加 taskkill。
 - **在 TUI 测试驱动器上到处使用 node-pty**：已归档的 [Windows TUI 决策](../../archived/feature/2026-07-20-windows-tui-support.md)明确否决了在每个宿主上都使用 node-pty；它当时已经是 Windows 那一条腿。
 
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 7794833aa0..32d6c6dcce 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 2d956f31a737d345393232aec9ce55b429e5b4d8
-README.zh.md: 087babe2ff878c69c668ad8fdf22b345f38ac204
+README.md: 0cf50146cc44ef0d6cc060a4c97b3d1ff454f013
+README.zh.md: b0503ed2677f2ef30a51716b1735be1fa9eabe82
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 2d956f31a7..0cf50146cc 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -16,7 +16,7 @@ Approvals take over the composer through the chain this package declares: `Appro
 
 The session header declares and renders the session-scoped `'conversation.session.header.actions'` list beside the title, allowing feature plugins to contribute controls without entering the skeleton. The composer chain currency includes the current conversation `session`; ui-subagent selects one-shot or parent-unavailable addressed sessions for reason-specific read-only copy, while the ordinary InputBar keeps every addressed child Send-only because the continuation service exposes no public per-Activation cancellation operation and `session.cancel` would bypass its ownership.
 
-Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The header shares the Tool calls geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state, summary, or keyed toolview dispatch ([disclosure decision](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
+Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The header shares the Tool calls geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state, summary, or keyed toolview dispatch ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
 
 A Think row stays collapsed by default and exposes live reasoning throughput without expanding the chain of thought: while its reasoning block is the streaming tail, the summary switches from the settled first line to the latest non-blank line and its one-line scrollport follows each delta to the inline end. Expanding the row removes the moving summary and leaves the full reasoning in ordinary page flow, so page reading never fights an internal follower; settlement restores the stable first-line summary at the left edge ([decision](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)).
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 087babe2ff..b0503ed267 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -14,7 +14,7 @@
 
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 
-已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。标题栏通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态、摘要或键控 toolview 分发（[展开项决策](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
+已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。标题栏通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态、摘要或键控 toolview 分发（[历史披露决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 47cebf796f..3829879b9d 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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/client/ui-primitives/README.md
-README.md: 7571cb48424b650a1aaa5222b33a3ee14faa69b4
-README.zh.md: fa0c3f24023ec8c1eb77553bfe191801b6698687
+README.md: c54759f98a944565959ef21ce538eb9b12fccdf1
+README.zh.md: 32275c19bca9d6e8aa510e982d535a72eb1a06a7
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 7571cb4842..c54759f98a 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -6,7 +6,7 @@ Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/
 
 ## Hover cards
 
-`HoverCard` keeps its portaled preview reachable across the anchor gap with a pointer-leave grace. A consumer may also pass `copyText`: the card then exposes button semantics for pointer and keyboard activation, includes that value after the `copyLabel` prefix in its accessible name, writes the exact value through the package clipboard helper, and temporarily replaces its content with `copiedLabel` only after the host accepts the write. A non-collapsed text selection intersecting the card suppresses pointer-click activation, while success feedback retains the original card height and clears when the card closes or after one second. `copyLabel` and `copiedLabel` are label props because this zero-cordis atom cannot read the application locale; omitting `copyText` preserves the read/select-only card. Rationale: [the hover-card copy note](../../../.agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.md).
+`HoverCard` keeps its portaled preview reachable across the anchor gap with a pointer-leave grace. A consumer may also pass `copyText`: the card then exposes button semantics for pointer and keyboard activation, includes that value after the `copyLabel` prefix in its accessible name, writes the exact value through the package clipboard helper, and temporarily replaces its content with `copiedLabel` only after the host accepts the write. A non-collapsed text selection intersecting the card suppresses pointer-click activation, while success feedback retains the original card height and clears when the card closes or after one second. `copyLabel` and `copiedLabel` are label props because this zero-cordis atom cannot read the application locale; omitting `copyText` preserves the read/select-only card. Historical rationale: [the archived hover-card copy note](../../../.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md).
 
 ## Markdown rendering
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index fa0c3f2402..32275c19bc 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 悬浮卡片
 
-`HoverCard` 通过指针离开宽限期，让采用 portal 渲染的预览在跨越与锚点之间的间隙时仍可抵达。消费方还可传入 `copyText`：此时卡片为指针与键盘激活提供按钮语义，其无障碍名称会在 `copyLabel` 前缀后包含该值，通过包内剪贴板辅助函数原样写入该值，并且只有宿主接受写入后，才会临时将内容替换为 `copiedLabel`。与卡片相交的非折叠文本选区会阻止指针点击激活；成功反馈保持卡片原有高度，并随卡片关闭或在一秒后清除。`copyLabel` 和 `copiedLabel` 采用 label prop，是因为这个 zero-cordis 原子组件无法读取应用 locale；省略 `copyText` 时，卡片维持只读且可选择文本的行为。理由见[悬浮卡片复制 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-hover-card-click-copy.md)。
+`HoverCard` 通过指针离开宽限期，让采用 portal 渲染的预览在跨越与锚点之间的间隙时仍可抵达。消费方还可传入 `copyText`：此时卡片为指针与键盘激活提供按钮语义，其无障碍名称会在 `copyLabel` 前缀后包含该值，通过包内剪贴板辅助函数原样写入该值，并且只有宿主接受写入后，才会临时将内容替换为 `copiedLabel`。与卡片相交的非折叠文本选区会阻止指针点击激活；成功反馈保持卡片原有高度，并随卡片关闭或在一秒后清除。`copyLabel` 和 `copiedLabel` 采用 label prop，是因为这个 zero-cordis 原子组件无法读取应用 locale；省略 `copyText` 时，卡片维持只读且可选择文本的行为。历史依据见[已归档的悬浮卡片复制 Agent Note](../../../.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md)。
 
 ## Markdown 渲染
 
diff --git a/packages/web/tool-web/README.i18n.yaml b/packages/web/tool-web/README.i18n.yaml
index 8f2ccbd057..eb57a7b20a 100644
--- a/packages/web/tool-web/README.i18n.yaml
+++ b/packages/web/tool-web/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/web/tool-web/README.md
-README.md: 12f5c806db66b2109888c1ec642d117f3432d0df
-README.zh.md: 27b4bc54a03af6347783a9666bd926bdc74fd0c8
+README.md: 791ea87c655444e639ef85ccce737066ead8b749
+README.zh.md: ffcf2d9813dcb94d8106b2c7d5f8ee9fc25e1aaa
diff --git a/packages/web/tool-web/README.md b/packages/web/tool-web/README.md
index 12f5c806db..791ea87c65 100644
--- a/packages/web/tool-web/README.md
+++ b/packages/web/tool-web/README.md
@@ -133,6 +133,6 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **HTML→markdown conversion degrades on inputs GFM cannot safely represent** — [turndown](https://github.com/mixmark-io/turndown) (with GFM tables/strikethrough) converts at most `fetchMaxOutputChars` source characters through a real DOM. A conservative 512-level lexical guard passes deeply or ambiguously nested bodies through as raw HTML, conversion exceptions do the same, and table `colspan` is ignored because GFM has no spanning-cell representation; these bounds avoid blocking the event loop or expanding output from an untrusted numeric attribute ([Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md)).
+- **HTML→markdown conversion degrades on inputs GFM cannot safely represent** — [turndown](https://github.com/mixmark-io/turndown) (with GFM tables/strikethrough) converts at most `fetchMaxOutputChars` source characters through a real DOM. A conservative 512-level lexical guard passes deeply or ambiguously nested bodies through as raw HTML, conversion exceptions do the same, and table `colspan` is ignored because GFM has no spanning-cell representation; these bounds avoid blocking the event loop or expanding output from an untrusted numeric attribute ([archived dependency decision](../../../.agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md)).
 - **The model-facing surface is minimal by design, with promotions deferred** — `max_results` stays a config bound (not a model argument), and `web_fetch` takes only `url` (no `format`/`prompt`/LLM-summarization mode); both are named later steps in [the seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md).
 - **No web-specific permission policy** — both tools execute without requesting `ctx.approval`; a deployment that needs confirmation must add a `tools/pre-execute` policy, and the package does not define persistent URL/domain grants.
diff --git a/packages/web/tool-web/README.zh.md b/packages/web/tool-web/README.zh.md
index 27b4bc54a0..ffcf2d9813 100644
--- a/packages/web/tool-web/README.zh.md
+++ b/packages/web/tool-web/README.zh.md
@@ -133,6 +133,6 @@ Use the web_fetch tool to retrieve the content of a specific HTTP(S) URL (for ex
 
 ## 已知限制与暂缓事项
 
-- **HTML→markdown 转换会在 GFM 无法安全表示的输入上降级**：[turndown](https://github.com/mixmark-io/turndown)（带 GFM 表格／删除线）通过真实 DOM 转换至多 `fetchMaxOutputChars` 个源字符。保守的 512 层词法守卫会将深层或嵌套有歧义的主体作为原始 HTML 直接透传，转换异常也会如此处理；表格的 `colspan` 会被忽略，因为 GFM 无法表示跨列单元格。这些限制可避免阻塞事件循环，也避免不受信任的数值属性使输出膨胀（[Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md)）。
+- **HTML→markdown 转换会在 GFM 无法安全表示的输入上降级**：[turndown](https://github.com/mixmark-io/turndown)（带 GFM 表格／删除线）通过真实 DOM 转换至多 `fetchMaxOutputChars` 个源字符。保守的 512 层词法守卫会将深层或嵌套有歧义的主体作为原始 HTML 直接透传，转换异常也会如此处理；表格的 `colspan` 会被忽略，因为 GFM 无法表示跨列单元格。这些限制可避免阻塞事件循环，也避免不受信任的数值属性使输出膨胀（[已归档的依赖决策](../../../.agents/notes/archived/simplification/2026-07-26-turndown-for-tool-web-html-markdown.md)）。
 - **面向模型的接口有意保持精简，后续扩展暂缓**：`max_results` 保持为配置上限（不是模型参数），`web_fetch` 只接受 `url`（没有 `format`／`prompt`／LLM（大语言模型）摘要模式）；两项都列为 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) 中的后续步骤。
 - **没有 web 专用权限策略**：两个工具都不会请求 `ctx.approval` 就直接执行；需要确认的部署必须添加 `tools/pre-execute` 策略，该包不定义持久化的 URL／域名授权。

From 1c23f196fefb6d68075aab73599ca988308f1ae1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:05:55 +0800
Subject: [PATCH 166/516] fix(ui): use official hero title casing

---
 apps/web/tests/details-session-lifecycle.e2e.ts               | 2 +-
 apps/web/tests/hmr-live.e2e.ts                                | 4 ++--
 apps/web/tests/lifecycle-chrome.e2e.ts                        | 2 +-
 apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md    | 2 +-
 .../tests/snapshots/lifecycle-chrome/plan-active.expected.md  | 2 +-
 apps/web/tests/startup-auto-selection.e2e.ts                  | 2 +-
 packages/client/ui-conversation/src/client/locales.ts         | 2 +-
 packages/client/ui-conversation/tests/skeleton.spec.tsx       | 2 +-
 8 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/apps/web/tests/details-session-lifecycle.e2e.ts b/apps/web/tests/details-session-lifecycle.e2e.ts
index 3bd781a5ee..c88a823fb7 100644
--- a/apps/web/tests/details-session-lifecycle.e2e.ts
+++ b/apps/web/tests/details-session-lifecycle.e2e.ts
@@ -121,7 +121,7 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S
     expect(await page.getByText('Details', { exact: true }).isVisible()).toBe(false)
 
     await page.getByRole('button', { name: /^(?:New session|新.*会话)$/ }).last().click()
-    await page.getByText('Into the unknown', { exact: false }).waitFor({ timeout: 15_000 })
+    await page.getByText('Into the Unknown', { exact: false }).waitFor({ timeout: 15_000 })
     await expect.poll(() => detailsTrack(page), { timeout: 5_000 }).toBe(0)
     expect(await page.getByText('Details', { exact: true }).isVisible()).toBe(false)
 
diff --git a/apps/web/tests/hmr-live.e2e.ts b/apps/web/tests/hmr-live.e2e.ts
index 1e8e81909f..cafd0fb474 100644
--- a/apps/web/tests/hmr-live.e2e.ts
+++ b/apps/web/tests/hmr-live.e2e.ts
@@ -75,8 +75,8 @@ it('hot-reloads a real client-plugin source edit without refreshing the page', a
   if (!existsSync(binPath)) throw new Error('HMR browser test needs the built dsh bin; run pnpm run build first')
   const originalSource = await readFile(sourcePath)
   const originalBundle = await readFile(bundlePath)
-  const oldText = 'Into the unknown'
-  const sourceNeedle = "'hero.headline': 'Into the unknown'"
+  const oldText = 'Into the Unknown'
+  const sourceNeedle = "'hero.headline': 'Into the Unknown'"
   const newText = `HMR UPDATED ${'x'.repeat(80)}`
   const updatedSource = originalSource.toString().replace(sourceNeedle, `'hero.headline': '${newText}'`)
   if (updatedSource === originalSource.toString()) throw new Error(`HMR source lacks ${JSON.stringify(sourceNeedle)}`)
diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index 90587e9e4c..1aa6b3dea9 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -159,7 +159,7 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
     }
     // The blank frame renders the hero, not the resident composer: the
     // headline plus the guidance placeholder are the empty state's anchors.
-    await expect.poll(() => page.getByText('Into the unknown', { exact: false }).count(), { timeout: 15_000 }).toBe(1)
+    await expect.poll(() => page.getByText('Into the Unknown', { exact: false }).count(), { timeout: 15_000 }).toBe(1)
     const input = page.locator('textarea').first()
     await input.waitFor({ timeout: 10_000 })
     if (MODE !== 'record') {
diff --git a/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md
index ad060c5d59..dfa23ca508 100644
--- a/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md
+++ b/apps/web/tests/snapshots/lifecycle-chrome/hero.expected.md
@@ -20,7 +20,7 @@
 - button "Settings":
   - img
   - text: Settings
-- text: Into the unknown Preview
+- text: Into the Unknown Preview
 - button "Choose workspace":
   - img
   - text: workspace
diff --git a/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md b/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md
index ce2ce36af0..3bf7e93148 100644
--- a/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md
+++ b/apps/web/tests/snapshots/lifecycle-chrome/plan-active.expected.md
@@ -20,7 +20,7 @@
 - button "Settings":
   - img
   - text: Settings
-- text: Into the unknown Preview
+- text: Into the Unknown Preview
 - button "Choose workspace":
   - img
   - text: workspace
diff --git a/apps/web/tests/startup-auto-selection.e2e.ts b/apps/web/tests/startup-auto-selection.e2e.ts
index c93ed04a40..21ad64e4ed 100644
--- a/apps/web/tests/startup-auto-selection.e2e.ts
+++ b/apps/web/tests/startup-auto-selection.e2e.ts
@@ -145,7 +145,7 @@ describe('web e2e: startup auto-selection', () => {
     // seat with `visibility:hidden`, which Playwright reports as not visible).
     await page.waitForSelector(ROOT_PHASE, { timeout: 15_000 })
     expect(await page.locator(ROOT_PHASE).first().getAttribute('data-phase')).toBe('hero')
-    expect(await page.getByText('Into the unknown').isVisible()).toBe(true)
+    expect(await page.getByText('Into the Unknown').isVisible()).toBe(true)
     expect(await page.locator('textarea').first().isVisible()).toBe(true)
 
     releaseHistory()
diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index eec25939b3..df107d2cd2 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -184,7 +184,7 @@ export const en = {
   'access.confirm.acknowledge': 'I understand the risks and want to continue',
   'access.confirm.cancel': 'Cancel',
   'access.confirm.enable': 'Enable Full access',
-  'hero.headline': 'Into the unknown',
+  'hero.headline': 'Into the Unknown',
   'hero.preview': 'Preview',
   'hero.chooseWorkspace': 'Choose workspace',
   'session.hierarchy': 'Session hierarchy',
diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx
index 1cf97bb61a..f2da8be7cb 100644
--- a/packages/client/ui-conversation/tests/skeleton.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx
@@ -242,7 +242,7 @@ function mount(
 describe('Hero chrome', () => {
   it('renders the English preview badge through the hero locale seat', () => {
     const view = render(<HeroShell t={makeTranslate(en, commonEn)} />)
-    expect(view.getByText('Into the unknown')).toBeTruthy()
+    expect(view.getByText('Into the Unknown')).toBeTruthy()
     expect(view.getByText('Preview')).toBeTruthy()
   })
 })

From 4ee93f79449d63c0e6397ceb66f6d3b9bb2d2b7f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:26:39 +0800
Subject: [PATCH 167/516] fix(config): cover shipped bundle source ownership

---
 packages/bundle/base/cordis.patch.yml         |  1 -
 .../verify-config-source-ownership.spec.ts    | 30 +++++++++++
 scripts/verify-config-source-ownership.ts     | 51 +++++++++++--------
 3 files changed, 59 insertions(+), 23 deletions(-)
 create mode 100644 scripts/verify-config-source-ownership.spec.ts

diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml
index 9ba9494c1c..9b7276b5d2 100644
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -368,7 +368,6 @@
       name: '@deepseek-ai/dsh-web-search-deepseek'
       config:
         apiKeyEnv: DEEPSEEK_API_KEY
-        baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
 
     - id: tool-web
       name: '@deepseek-ai/dsh-tool-web'
diff --git a/scripts/verify-config-source-ownership.spec.ts b/scripts/verify-config-source-ownership.spec.ts
new file mode 100644
index 0000000000..41026c5fe4
--- /dev/null
+++ b/scripts/verify-config-source-ownership.spec.ts
@@ -0,0 +1,30 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectConfigSourceOwnershipViolations } from './verify-config-source-ownership.ts'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+describe('configuration source ownership gate', () => {
+  it('rejects inline endpoints in shipped bundle patches', () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-config-source-ownership-'))
+    roots.push(root)
+    const directory = join(root, 'packages/bundle/base')
+    mkdirSync(directory, { recursive: true })
+    writeFileSync(
+      join(directory, 'cordis.patch.yml'),
+      'config:\n  baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL\n',
+    )
+
+    expect(collectConfigSourceOwnershipViolations(root)).toEqual([
+      'packages/bundle/base/cordis.patch.yml:2: inlines a credential or endpoint from the environment.'
+      + ' The adapter resolves apiKeyEnv through ctx.credentials and the endpoint through the'
+      + ' environment snapshot; inlining here bypasses both ladders.',
+    ])
+  })
+})
diff --git a/scripts/verify-config-source-ownership.ts b/scripts/verify-config-source-ownership.ts
index ffc849bba3..e027fcba61 100644
--- a/scripts/verify-config-source-ownership.ts
+++ b/scripts/verify-config-source-ownership.ts
@@ -16,6 +16,7 @@ const SHIPPED_CONFIG_GLOBS = [
   'apps/*/config/*.yml',
   'examples/*/*.cordis.yml',
   'examples/*/cordis.yml',
+  'packages/bundle/*/cordis.patch.yml',
   // The Python runtime ships its own default composition inside the wheel.
   'python/*/src/**/cordis.yml',
 ]
@@ -29,29 +30,35 @@ const SHIPPED_CONFIG_GLOBS = [
  */
 const INLINE_DENY = /^\s*(apiKey|baseURL|apiKeyEnv|authToken|headers)\s*:\s*!!js\b/
 
-const failures: string[] = []
-
-for (const glob of SHIPPED_CONFIG_GLOBS) {
-  for (const file of globSync(glob, { cwd: ROOT })) {
-    const rel = file.split(sep).join('/')
-    readFileSync(resolve(ROOT, rel), 'utf8').split('\n').forEach((line, index) => {
-      if (!INLINE_DENY.test(line)) return
-      failures.push(
-        `${rel}:${String(index + 1)}: inlines a credential or endpoint from the environment.`
-        + ' The adapter resolves apiKeyEnv through ctx.credentials and the endpoint through the'
-        + ' environment snapshot; inlining here bypasses both ladders.',
-      )
-    })
+/** Return every forbidden inline environment form in shipped configuration. */
+export function collectConfigSourceOwnershipViolations(root: string): string[] {
+  const failures: string[] = []
+  for (const glob of SHIPPED_CONFIG_GLOBS) {
+    for (const file of globSync(glob, { cwd: root })) {
+      const rel = file.split(sep).join('/')
+      readFileSync(resolve(root, rel), 'utf8').split('\n').forEach((line, index) => {
+        if (!INLINE_DENY.test(line)) return
+        failures.push(
+          `${rel}:${String(index + 1)}: inlines a credential or endpoint from the environment.`
+          + ' The adapter resolves apiKeyEnv through ctx.credentials and the endpoint through the'
+          + ' environment snapshot; inlining here bypasses both ladders.',
+        )
+      })
+    }
   }
+  return failures
 }
 
-if (failures.length > 0) {
-  process.stderr.write('verify-config-source-ownership: configuration source ownership violated:\n')
-  for (const failure of failures) process.stderr.write(`  ${failure}\n`)
-  process.exit(1)
-}
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  const failures = collectConfigSourceOwnershipViolations(ROOT)
+  if (failures.length > 0) {
+    process.stderr.write('verify-config-source-ownership: configuration source ownership violated:\n')
+    for (const failure of failures) process.stderr.write(`  ${failure}\n`)
+    process.exit(1)
+  }
 
-process.stdout.write(
-  'verify-config-source-ownership: no credential or endpoint uses the ordinary inline environment form'
-  + ' in shipped configuration.\n',
-)
+  process.stdout.write(
+    'verify-config-source-ownership: no credential or endpoint uses the ordinary inline environment form'
+    + ' in shipped configuration.\n',
+  )
+}

From 95366f61976f07d7fa447d011276a076935947ac Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:28:17 +0800
Subject: [PATCH 168/516] fix(cli): parse commands before loading environment

---
 apps/cli/src/bin.ts             |  5 ++---
 apps/cli/tests/built-bin.e2e.ts | 11 +++++++++++
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts
index 28ef96d004..4a209b2796 100644
--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -24,14 +24,13 @@ function readVersion(): string {
   return typeof manifest.version === 'string' ? manifest.version : '0.0.0'
 }
 
-const environment = loadLayeredEnv('dsh')
 const invocation = parseDshArgs(process.argv.slice(2), readVersion())
 
 switch (invocation.mode) {
   case 'profile': {
     const { runProfile } = await import('./profile-boot.ts')
     await runProfile({
-      environment,
+      environment: loadLayeredEnv('dsh'),
       profile: invocation.profile,
       patchFiles: invocation.patches,
       ...invocation.task !== undefined && { task: invocation.task },
@@ -40,7 +39,7 @@ switch (invocation.mode) {
   }
   case 'web': {
     const { runWeb } = await import('./web.ts')
-    await runWeb(invocation, environment)
+    await runWeb(invocation, loadLayeredEnv('dsh'))
     break
   }
   case 'plugin': {
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index 22fe20883e..20ed3fb160 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -190,6 +190,17 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     }
   }, 30_000)
 
+  it('does not load a project environment for --version', async () => {
+    const project = mkdtempSync(join(tmpdir(), 'dsh-version-project-'))
+    writeFileSync(join(project, '.env'), 'PATH=/project-only-path\n')
+    try {
+      const result = await runBuiltBin(['--version'], {}, project)
+      expect(result).toEqual({ code: 0, stdout: '0.0.1', stderr: '' })
+    } finally {
+      rmSync(project, { recursive: true, force: true })
+    }
+  })
+
   it('fails loud on a nonexistent profile with the plugin-command hint', async () => {
     const home = mkdtempSync(join(tmpdir(), 'dsh-missing-profile-'))
     try {

From 2c532f3b2c8accc038c1f9b38b3b15d0006cb3c4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:30:03 +0800
Subject: [PATCH 169/516] cleanup(environment): remove unused layer inventory

---
 packages/ui/app-boot/tests/app-boot.spec.ts   | 29 ++++---------------
 packages/util/environment/src/index.ts        | 15 ----------
 .../environment/tests/environment.spec.ts     | 10 -------
 3 files changed, 6 insertions(+), 48 deletions(-)

diff --git a/packages/ui/app-boot/tests/app-boot.spec.ts b/packages/ui/app-boot/tests/app-boot.spec.ts
index 864eaa600e..447b2f5949 100644
--- a/packages/ui/app-boot/tests/app-boot.spec.ts
+++ b/packages/ui/app-boot/tests/app-boot.spec.ts
@@ -151,7 +151,7 @@ describe('loadLayeredEnv', () => {
     }
   })
 
-  it('reports each layer with its absolute path', () => {
+  it('reports each file value with its absolute path', () => {
     const home = tmp()
     const project = tmp()
     writeFileSync(join(home, '.env'), `${NAMES[1]}=u\n`)
@@ -160,12 +160,8 @@ describe('loadLayeredEnv', () => {
     vi.stubEnv('DSH_HOME', home)
     try {
       const snapshot = loadLayeredEnv(NAME, project, vi.fn())
-      expect(snapshot.layers).toEqual([
-        { source: 'process' },
-        { source: 'project-env', path: join(project, '.env') },
-        { source: 'user-env', path: join(home, '.env') },
-      ])
       expect(snapshot.get(NAMES[1])).toEqual({ value: 'u', source: 'user-env', path: join(home, '.env') })
+      expect(snapshot.get(NAMES[2])).toEqual({ value: 'p', source: 'project-env', path: join(project, '.env') })
       // getFrom is a refusal, not a demotion: an omitted layer is invisible.
       expect(snapshot.getFrom(NAMES[2], ['process', 'user-env'])).toBeUndefined()
     } finally {
@@ -205,10 +201,8 @@ describe('loadLayeredEnv', () => {
     try {
       const snapshot = loadLayeredEnv(NAME, project, warn)
       expect(warn).toHaveBeenCalledWith(expect.stringContaining(`${NAME}: failed to load .env`))
-      expect(snapshot.layers).toEqual([
-        { source: 'process' },
-        { source: 'project-env', path: join(project, '.env') },
-      ])
+      expect(snapshot.get(NAMES[1])).toBeUndefined()
+      expect(snapshot.get(NAMES[2])).toEqual({ value: 'project-only', source: 'project-env', path: join(project, '.env') })
       expect(process.env[NAMES[2]]).toBe('project-only')
     } finally {
       clear()
@@ -227,10 +221,7 @@ describe('loadLayeredEnv', () => {
     try {
       const snapshot = loadLayeredEnv(NAME, project)
       expect(write).toHaveBeenCalledWith(expect.stringContaining(`${NAME}: failed to load .env`))
-      expect(snapshot.layers).toEqual([
-        { source: 'process' },
-        { source: 'project-env', path: join(project, '.env') },
-      ])
+      expect(snapshot.get(NAMES[2])).toEqual({ value: 'project-only', source: 'project-env', path: join(project, '.env') })
       expect(process.env[NAMES[2]]).toBe('project-only')
     } finally {
       write.mockRestore()
@@ -251,10 +242,7 @@ describe('loadLayeredEnv', () => {
       // layer is simply absent, and nothing is reported.
       const snapshot = loadLayeredEnv(NAME, project, warn)
       expect(warn).not.toHaveBeenCalled()
-      expect(snapshot.layers).toEqual([
-        { source: 'process' },
-        { source: 'project-env', path: join(project, '.env') },
-      ])
+      expect(snapshot.get(NAMES[2])).toEqual({ value: 'project-only', source: 'project-env', path: join(project, '.env') })
     } finally {
       clear()
       vi.unstubAllEnvs()
@@ -269,7 +257,6 @@ describe('loadLayeredEnv', () => {
     vi.stubEnv('APP_BOOT_LAYERED_INHERITED', 'inherited')
     try {
       const snapshot = loadLayeredEnv(NAME, project, vi.fn())
-      expect(snapshot.layers).toEqual([{ source: 'process' }])
       expect(snapshot.get('APP_BOOT_LAYERED_INHERITED')).toEqual({ value: 'inherited', source: 'process' })
     } finally {
       clear()
@@ -287,10 +274,6 @@ describe('loadLayeredEnv', () => {
       // is the more trusted of the two — reading it twice would otherwise
       // put the same path at two different ranks.
       const snapshot = loadLayeredEnv(NAME, both, vi.fn())
-      expect(snapshot.layers).toEqual([
-        { source: 'process' },
-        { source: 'project-env', path: join(both, '.env') },
-      ])
       expect(snapshot.get(NAMES[2])).toEqual({ value: 'one-file', source: 'project-env', path: join(both, '.env') })
     } finally {
       clear()
diff --git a/packages/util/environment/src/index.ts b/packages/util/environment/src/index.ts
index f35e32f9c5..6f051603e6 100644
--- a/packages/util/environment/src/index.ts
+++ b/packages/util/environment/src/index.ts
@@ -35,13 +35,6 @@ export interface EnvironmentEntry {
   path?: string
 }
 
-/** One environment layer's identity, for diagnostics. */
-export interface EnvironmentLayer {
-  source: EnvironmentSource
-  /** Absolute path of the file behind this layer; absent for `process`. */
-  path?: string
-}
-
 /**
  * The frozen environment of one launch. Construct through
  * {@link createEnvironmentSnapshot}; nothing mutates it afterwards, so a
@@ -65,8 +58,6 @@ export interface EnvironmentSnapshot {
    * @returns the first matching entry, or `undefined`.
    */
   getFrom(name: string, sources: readonly EnvironmentSource[]): EnvironmentEntry | undefined
-  /** The layers this snapshot was built from, most trusted first. */
-  readonly layers: readonly EnvironmentLayer[]
 }
 
 /**
@@ -121,12 +112,6 @@ export function createEnvironmentSnapshot(layers: readonly EnvironmentLayerInput
   return {
     get: name => getFrom(name, ENVIRONMENT_SOURCES),
     getFrom,
-    layers: ENVIRONMENT_SOURCES
-      .filter(source => bySource.has(source))
-      .map((source): EnvironmentLayer => {
-        const path = bySource.get(source)?.path
-        return { source, ...path === undefined ? {} : { path } }
-      }),
   }
 }
 
diff --git a/packages/util/environment/tests/environment.spec.ts b/packages/util/environment/tests/environment.spec.ts
index 27c7b16e55..7083c9891d 100644
--- a/packages/util/environment/tests/environment.spec.ts
+++ b/packages/util/environment/tests/environment.spec.ts
@@ -28,15 +28,6 @@ describe('createEnvironmentSnapshot', () => {
     expect(layered.getFrom('SHARED', [])).toBeUndefined()
   })
 
-  it('lists its layers in trust order with their paths', () => {
-    expect(layered.layers).toEqual([
-      { source: 'process' },
-      { source: 'project-env', path: '/work/.env' },
-      { source: 'user-env', path: '/home/.dsh/.env' },
-    ])
-    expect(createEnvironmentSnapshot([{ source: 'process', values: {} }]).layers).toEqual([{ source: 'process' }])
-  })
-
   it('copies each layer, so a later mutation of the source object cannot change it', () => {
     const values: Record<string, string> = { KEY: 'first' }
     const snapshot = createEnvironmentSnapshot([{ source: 'process', values }])
@@ -76,7 +67,6 @@ describe('environmentOf', () => {
       // A host that discovered no files has exactly one layer, so the trusted
       // lookups every consumer makes still find what it was launched with.
       expect(snapshot.getFrom('DSH_ENV_SPEC_FALLBACK', ['process', 'user-env'])?.value).toBe('ambient')
-      expect(snapshot.layers).toEqual([{ source: 'process' }])
     } finally {
       vi.unstubAllEnvs()
     }

From d0e052dd83e6ffd8b5b21577a84fb46ea1ac0412 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:33:11 +0800
Subject: [PATCH 170/516] cleanup(environment): keep one lookup order

---
 packages/llm/llm-deepseek/src/index.ts            |  4 ++--
 packages/llm/llm-pi-ai/src/index.ts               |  2 +-
 packages/util/environment/README.i18n.yaml        |  4 ++--
 packages/util/environment/README.md               |  4 ++--
 packages/util/environment/README.zh.md            |  4 ++--
 packages/util/environment/src/index.ts            | 13 +++++++------
 .../util/environment/tests/environment.spec.ts    | 15 +++++----------
 packages/web/web-search-deepseek/src/index.ts     |  4 ++--
 packages/web/web-search-exa/src/index.ts          |  2 +-
 packages/web/web-search-perplexity/src/index.ts   |  2 +-
 10 files changed, 25 insertions(+), 29 deletions(-)

diff --git a/packages/llm/llm-deepseek/src/index.ts b/packages/llm/llm-deepseek/src/index.ts
index c2a9360f64..6d052edc45 100644
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/packages/llm/llm-deepseek/src/index.ts
@@ -182,7 +182,7 @@ export function resolveAdapterOptions(config: Config, environment?: EnvironmentS
   return {
     apiKeyEnv: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
     baseURL: config.baseURL
-      ?? environment?.getFrom(BASE_URL_ENV, ['process', 'project-env', 'user-env'])?.value
+      ?? environment?.get(BASE_URL_ENV)?.value
       ?? PUBLIC_BASE_URL,
     defaults: {
       thinking: config.thinking,
@@ -232,7 +232,7 @@ export function apply(ctx: Context, config: Config): void {
     } else {
       // Without the seam there is no managed store to rank against, so the
       // environment is the whole credential plane.
-      const ambient = environmentOf(ctx).getFrom(ref, ['process', 'project-env', 'user-env'])
+      const ambient = environmentOf(ctx).get(ref)
       if (ambient !== undefined && ambient.value.length > 0) {
         return assertUsableApiKey(ambient.value, 'llm-deepseek', ref)
       }
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index 2f9b50a717..42102507c0 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -143,7 +143,7 @@ export function apply(ctx: Context, config: Config): void {
     const hit = credentials !== undefined
       ? (await credentials.resolve(ref))?.value
       // Without the seam the environment is the whole credential plane.
-      : environmentOf(ctx).getFrom(ref, ['process', 'project-env', 'user-env'])?.value
+      : environmentOf(ctx).get(ref)?.value
     if (hit !== undefined && hit.length > 0) return assertUsableApiKey(hit, 'llm-pi-ai', ref)
     throw new LlmError(
       `llm-pi-ai: no credential for provider route "${provider}"; its profile resolves ${ref}, which is not`
diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index ea1e025257..ecd2fca34b 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/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/util/environment/README.md
-README.md: 1bb444bc217ce1a01fb98f954d6e1c2bbc3db957
-README.zh.md: a46adf0beeb0fb2069e198c99e4c00c2e8c09c6c
+README.md: 1df857851f0f0a5a5ac52365c5e563a1c001bfca
+README.zh.md: 41ea1af3a6eb95d58456f43e0f7f0a90e4fe7ac6
diff --git a/packages/util/environment/README.md b/packages/util/environment/README.md
index 1bb444bc21..1df857851f 100644
--- a/packages/util/environment/README.md
+++ b/packages/util/environment/README.md
@@ -14,7 +14,7 @@ Values do also reach `process.env` — a user's `--config` tree and third-party
 
 ## Resolving
 
-`get(name)` searches every layer, most trusted first. `getFrom(name, sources)` searches only the layers the caller trusts.
+`get(name)` searches every layer, most trusted first. `getFrom(name, sources)` searches only the named layers without changing that trust order.
 
 **Omitting a layer is a refusal, not a demotion** — a caller that must never accept a layer leaves it out of the list, so no future reordering can let it back in. The provider adapters name all three, because the product trusts the project it runs in; the mechanism exists for the decisions where that is not true.
 
@@ -25,7 +25,7 @@ import type { Context } from 'cordis'
 import { environmentOf } from '@deepseek-ai/dsh-environment'
 
 declare const ctx: Context
-const endpoint = environmentOf(ctx).getFrom('DEEPSEEK_BASE_URL', ['process', 'project-env', 'user-env'])?.value
+const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 ```
 
 `environmentOf(ctx)` returns the launcher's snapshot when the product CLI booted the tree, and otherwise the inherited environment as the only layer. That fallback does not weaken the rules: an SDK host or a bare `cordis.yml` discovered no files, so everything it has really is the environment it was launched with.
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index a46adf0bee..41ea1af3a6 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -14,7 +14,7 @@
 
 ## 解析
 
-`get(name)` 按可信度从高到低搜索所有层。`getFrom(name, sources)` 只搜索调用方信任的层。
+`get(name)` 按可信度从高到低搜索所有层。`getFrom(name, sources)` 只搜索指定的层，不改变这一可信顺序。
 
 **省略某一层是拒绝，不是降级**——绝不能接受某一层的调用方直接不把它列进去，后续任何重新排序都无法让它回来。provider 适配器三层全列，因为产品信任它所运行的项目；该机制是为那些「并非如此」的决策准备的。
 
@@ -25,7 +25,7 @@ import type { Context } from 'cordis'
 import { environmentOf } from '@deepseek-ai/dsh-environment'
 
 declare const ctx: Context
-const endpoint = environmentOf(ctx).getFrom('DEEPSEEK_BASE_URL', ['process', 'project-env', 'user-env'])?.value
+const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 ```
 
 当产品 CLI（命令行界面）启动了这棵树时，`environmentOf(ctx)` 返回启动器的快照；否则返回只含继承环境的那一层。该回退并不削弱规则：SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，因此它拥有的一切确实就是它被启动时的环境。
diff --git a/packages/util/environment/src/index.ts b/packages/util/environment/src/index.ts
index 6f051603e6..a86689e809 100644
--- a/packages/util/environment/src/index.ts
+++ b/packages/util/environment/src/index.ts
@@ -22,8 +22,8 @@ import type { Context } from 'cordis'
  */
 export type EnvironmentSource = 'process' | 'project-env' | 'user-env'
 
-/** Layer order, most trusted first — the default search order of {@link EnvironmentSnapshot.get}. */
-export const ENVIRONMENT_SOURCES: readonly EnvironmentSource[] = ['process', 'project-env', 'user-env']
+/** Layer order, most trusted first. */
+const SOURCE_ORDER: readonly EnvironmentSource[] = ['process', 'project-env', 'user-env']
 
 /** One resolved variable and the layer it came from. */
 export interface EnvironmentEntry {
@@ -54,7 +54,7 @@ export interface EnvironmentSnapshot {
    * that must never come from a project directory omits `project-env` so no
    * ordering change can let it back in.
    * @param name - the variable name.
-   * @param sources - the layers to search, in the caller's own priority order.
+   * @param sources - the layers allowed in the canonical trust order.
    * @returns the first matching entry, or `undefined`.
    */
   getFrom(name: string, sources: readonly EnvironmentSource[]): EnvironmentEntry | undefined
@@ -81,7 +81,7 @@ export interface EnvironmentLayerInput {
 
 /**
  * Build the snapshot from each layer's contents.
- * @param layers - the layers in any order; the result searches them by {@link ENVIRONMENT_SOURCES}.
+ * @param layers - the layers in any order; the result searches them by canonical trust order.
  * @returns the immutable snapshot.
  */
 export function createEnvironmentSnapshot(layers: readonly EnvironmentLayerInput[]): EnvironmentSnapshot {
@@ -101,7 +101,8 @@ export function createEnvironmentSnapshot(layers: readonly EnvironmentLayerInput
   }
   const getFrom = (name: string, sources: readonly EnvironmentSource[]): EnvironmentEntry | undefined => {
     const key = lookupKey(name)
-    for (const source of sources) {
+    for (const source of SOURCE_ORDER) {
+      if (!sources.includes(source)) continue
       const layer = bySource.get(source)
       const value = layer?.values.get(key)
       if (value === undefined) continue
@@ -110,7 +111,7 @@ export function createEnvironmentSnapshot(layers: readonly EnvironmentLayerInput
     return undefined
   }
   return {
-    get: name => getFrom(name, ENVIRONMENT_SOURCES),
+    get: name => getFrom(name, SOURCE_ORDER),
     getFrom,
   }
 }
diff --git a/packages/util/environment/tests/environment.spec.ts b/packages/util/environment/tests/environment.spec.ts
index 7083c9891d..8ed3823832 100644
--- a/packages/util/environment/tests/environment.spec.ts
+++ b/packages/util/environment/tests/environment.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import {
-  createEnvironmentSnapshot, DSH_ENVIRONMENT_KEY, ENVIRONMENT_SOURCES, environmentOf, isBootstrapOnly,
+  createEnvironmentSnapshot, DSH_ENVIRONMENT_KEY, environmentOf, isBootstrapOnly,
 } from '../src/index.ts'
 
 const layered = createEnvironmentSnapshot([
@@ -18,13 +18,12 @@ describe('createEnvironmentSnapshot', () => {
     expect(layered.get('ABSENT')).toBeUndefined()
   })
 
-  it('treats an omitted layer as invisible, not merely lower', () => {
+  it('filters layers without changing their trust order', () => {
     // The point of getFrom: a routing field that must never come from a
     // project directory cannot be reached by reordering, only by listing it.
     expect(layered.getFrom('ONLY_PROJECT', ['process', 'user-env'])).toBeUndefined()
-    expect(layered.getFrom('SHARED', ['user-env', 'process'])).toEqual({
-      value: 'from-user', source: 'user-env', path: '/home/.dsh/.env',
-    })
+    expect(layered.getFrom('SHARED', ['user-env', 'process']))
+      .toEqual({ value: 'from-process', source: 'process' })
     expect(layered.getFrom('SHARED', [])).toBeUndefined()
   })
 
@@ -42,12 +41,11 @@ describe('createEnvironmentSnapshot', () => {
     expect(snapshot.get('EMPTY')).toEqual({ value: '', source: 'process' })
   })
 
-  it('orders lookups by ENVIRONMENT_SOURCES regardless of construction order', () => {
+  it('orders lookups canonically regardless of construction order', () => {
     const reversed = createEnvironmentSnapshot([
       { source: 'user-env', path: '/u', values: { K: 'u' } },
       { source: 'process', values: { K: 'p' } },
     ])
-    expect(ENVIRONMENT_SOURCES).toEqual(['process', 'project-env', 'user-env'])
     expect(reversed.get('K')).toEqual({ value: 'p', source: 'process' })
   })
 })
@@ -64,9 +62,6 @@ describe('environmentOf', () => {
     try {
       const snapshot = environmentOf(new Context())
       expect(snapshot.get('DSH_ENV_SPEC_FALLBACK')).toEqual({ value: 'ambient', source: 'process' })
-      // A host that discovered no files has exactly one layer, so the trusted
-      // lookups every consumer makes still find what it was launched with.
-      expect(snapshot.getFrom('DSH_ENV_SPEC_FALLBACK', ['process', 'user-env'])?.value).toBe('ambient')
     } finally {
       vi.unstubAllEnvs()
     }
diff --git a/packages/web/web-search-deepseek/src/index.ts b/packages/web/web-search-deepseek/src/index.ts
index 60b5a64692..5e55e12457 100644
--- a/packages/web/web-search-deepseek/src/index.ts
+++ b/packages/web/web-search-deepseek/src/index.ts
@@ -90,12 +90,12 @@ export function apply(ctx: Context, config: Config): void {
       const credentials = ctx.get('credentials')
       if (credentials !== undefined) return (await credentials.resolve(apiKeyEnv))?.value
       // Without the seam the environment is the whole credential plane.
-      const ambient = environmentOf(ctx).getFrom(apiKeyEnv, ['process', 'project-env', 'user-env'])
+      const ambient = environmentOf(ctx).get(apiKeyEnv)
       return ambient !== undefined && ambient.value.length > 0 ? ambient.value : undefined
     },
     apiKeyEnv,
     baseURL: config.baseURL
-      ?? environmentOf(ctx).getFrom(SEARCH_BASE_URL_ENV, ['process', 'project-env', 'user-env'])?.value
+      ?? environmentOf(ctx).get(SEARCH_BASE_URL_ENV)?.value
       ?? DEEPSEEK_DEFAULT_BASE_URL,
     model: config.model ?? DEEPSEEK_DEFAULT_MODEL,
     apiVersion: config.apiVersion ?? DEEPSEEK_DEFAULT_API_VERSION,
diff --git a/packages/web/web-search-exa/src/index.ts b/packages/web/web-search-exa/src/index.ts
index d5c8b938ac..2ecb71336a 100644
--- a/packages/web/web-search-exa/src/index.ts
+++ b/packages/web/web-search-exa/src/index.ts
@@ -61,7 +61,7 @@ export function apply(ctx: Context, config: Config): void {
   ctx.web.registerSearchProvider(new ExaSearchProvider({
     // Every environment layer may name this key: the product trusts the
     // project it is launched in, and the managed store is not involved here.
-    apiKey: config.apiKey ?? environmentOf(ctx).getFrom('EXA_API_KEY', ['process', 'project-env', 'user-env'])?.value ?? '',
+    apiKey: config.apiKey ?? environmentOf(ctx).get('EXA_API_KEY')?.value ?? '',
     baseURL: config.baseURL ?? EXA_DEFAULT_BASE_URL,
     searchType: config.searchType ?? EXA_DEFAULT_SEARCH_TYPE,
     highlightsPerResult: config.highlightsPerResult ?? EXA_DEFAULT_HIGHLIGHTS_PER_RESULT,
diff --git a/packages/web/web-search-perplexity/src/index.ts b/packages/web/web-search-perplexity/src/index.ts
index c8088a3c23..e1fe6a2606 100644
--- a/packages/web/web-search-perplexity/src/index.ts
+++ b/packages/web/web-search-perplexity/src/index.ts
@@ -55,7 +55,7 @@ export function apply(ctx: Context, config: Config): void {
   ctx.web.registerSearchProvider(new PerplexitySearchProvider({
     // Every environment layer may name this key: the product trusts the
     // project it is launched in, and the managed store is not involved here.
-    apiKey: config.apiKey ?? environmentOf(ctx).getFrom('PERPLEXITY_API_KEY', ['process', 'project-env', 'user-env'])?.value ?? '',
+    apiKey: config.apiKey ?? environmentOf(ctx).get('PERPLEXITY_API_KEY')?.value ?? '',
     baseURL: config.baseURL ?? PERPLEXITY_DEFAULT_BASE_URL,
     model: config.model ?? PERPLEXITY_DEFAULT_MODEL,
     maxTokens: config.maxTokens ?? PERPLEXITY_DEFAULT_MAX_TOKENS,

From b5fbcaccf8b1d4ec5ad334a4111b760ae17dcfa0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:37:53 +0800
Subject: [PATCH 171/516] cleanup(config): localize bootstrap policy to app
 boot

---
 ...4-configuration-source-ownership.i18n.yaml |  4 +-
 ...26-08-04-configuration-source-ownership.md |  2 +-
 ...08-04-configuration-source-ownership.zh.md |  2 +-
 packages/ui/app-boot/README.i18n.yaml         |  4 +-
 packages/ui/app-boot/README.md                |  2 +-
 packages/ui/app-boot/README.zh.md             |  2 +-
 packages/ui/app-boot/src/index.ts             | 68 ++++++++++++++++++-
 packages/util/environment/README.i18n.yaml    |  4 +-
 packages/util/environment/README.md           | 12 +---
 packages/util/environment/README.zh.md        | 12 +---
 packages/util/environment/src/index.ts        | 66 ------------------
 .../environment/tests/environment.spec.ts     | 36 +---------
 12 files changed, 80 insertions(+), 134 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 2d966fa8ea..22935b42ca 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: 0b11df50c8f00875a92b722e9f225dd27ed218b5
-2026-08-04-configuration-source-ownership.zh.md: 648cea0167bef564195597f7b2791b5211d40267
+2026-08-04-configuration-source-ownership.md: ef30a22c120af1437f348e52843e1dd45c9837ae
+2026-08-04-configuration-source-ownership.zh.md: c1567c6e823a0bc8ed8d1f9ed50a11a5d204ede8
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index 0b11df50c8..ef30a22c12 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -42,7 +42,7 @@ The launching environment wins because `DEEPSEEK_API_KEY=… dsh`, a CI secret,
 
 **The project the harness is launched in is trusted, by default and without a prompt.** A checkout may carry its own endpoint, its own ordinary variables, and its own key; the key ranks below the managed store, so a key stored through the Models page is never displaced by one a checkout happens to contain. `EnvironmentSnapshot.getFrom(name, sources)` still searches only the layers a caller names, and omitting one is a refusal rather than a demotion — the mechanism exists for the decisions where a layer must be unreachable, not because the project is one of them today.
 
-**Trust does not extend to changing the harness itself.** `isBootstrapOnly` rejects, at load and before anything is materialized, any `.env` that sets a variable governing how a process launches (`PATH`, `SHELL`, `NODE_OPTIONS`, `LD_PRELOAD`), what code a runtime executes before the program it was asked to run (`BASH_ENV`, `PERL5OPT`, `PYTHONSTARTUP`, `RUBYOPT`, `JAVA_TOOL_OPTIONS`, the Git hook commands), where model-visible instructions load from (the whole `DSH_*` namespace, `HOME`, `XDG_*`), or how the network is reached and trusted (proxy and CA variables). Matching is case-insensitive, so `https_proxy` is not a bypass.
+**Trust does not extend to changing the harness itself.** `loadLayeredEnv` rejects, at load and before anything is materialized, any `.env` that sets a variable governing how a process launches (`PATH`, `SHELL`, `NODE_OPTIONS`, `LD_PRELOAD`), what code a runtime executes before the program it was asked to run (`BASH_ENV`, `PERL5OPT`, `PYTHONSTARTUP`, `RUBYOPT`, `JAVA_TOOL_OPTIONS`, the Git hook commands), where model-visible instructions load from (the whole `DSH_*` namespace, `HOME`, `XDG_*`), or how the network is reached and trusted (proxy and CA variables). Matching is case-insensitive, so `https_proxy` is not a bypass.
 
 The line is that these take effect with no user action, before any turn, outside the permission policy and the sandbox. `DSH_PERMISSION_MODE` would switch off the approvals that make trusting a project meaningful at all, and `BASH_ENV` runs a file of the project's choosing on every single `bash -c` the bash tool issues — the project's code running under the agent's policy is the deal; the project rewriting that policy is not. Enumerating these is a losing game one variable at a time, which is why the whole `DSH_*` namespace is denied rather than an audited subset, and why the list is organised by what a variable *does* rather than by which runtime owns it. There is no opt-out: an escape hatch would have to be readable from somewhere, and anything a discovered file could set is the hole itself.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index 648cea0167..c1567c6e82 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -44,7 +44,7 @@ inherited process environment      (read-only, wins)
 
 **harness 被启动于其中的项目默认可信，且不做询问。** 一个 checkout 可以携带自己的 endpoint、自己的普通变量和自己的密钥；密钥排在受管存储之下，因此通过 Models 页存下的密钥绝不会被 checkout 中恰好带有的那一个顶掉。`EnvironmentSnapshot.getFrom(name, sources)` 仍然只搜索调用方点名的层，省略某层仍是拒绝而不是降级——该机制是为「某一层必须不可达」的那些决策准备的，而项目层今天不在其列。
 
-**信任不延伸到改变 harness 本身。** `isBootstrapOnly` 会在加载时、且在物化任何内容之前，拒绝任何设置了下列变量的 `.env`：决定进程如何启动的（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD`）、决定运行时在执行被要求运行的程序之前先执行哪些代码的（`BASH_ENV`、`PERL5OPT`、`PYTHONSTARTUP`、`RUBYOPT`、`JAVA_TOOL_OPTIONS`、Git 的钩子命令）、决定模型可见指令从哪里加载的（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），以及决定网络如何抵达与信任的（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
+**信任不延伸到改变 harness 本身。** `loadLayeredEnv` 会在加载时、且在物化任何内容之前，拒绝任何设置了下列变量的 `.env`：决定进程如何启动的（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD`）、决定运行时在执行被要求运行的程序之前先执行哪些代码的（`BASH_ENV`、`PERL5OPT`、`PYTHONSTARTUP`、`RUBYOPT`、`JAVA_TOOL_OPTIONS`、Git 的钩子命令）、决定模型可见指令从哪里加载的（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），以及决定网络如何抵达与信任的（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
 
 这条界线在于：它们无需任何用户动作、在任何一轮开始之前、且在权限策略与沙箱之外就生效。`DSH_PERMISSION_MODE` 会关掉让「信任项目」根本成立的那道审批，而 `BASH_ENV` 会在 bash 工具发出的每一次 `bash -c` 上执行项目指定的文件——项目的代码在 agent 的策略下运行是约定，项目改写那份策略不是。一个变量一个变量地枚举是必输的游戏，所以整个 `DSH_*` 命名空间被拒绝而不是只拒绝一份经审查的子集，也所以这份清单是按变量*做什么*而不是按哪个运行时拥有它来组织的。不设逃生门：逃生门本身总得从某处读取，而任何被发现的文件能设置的东西，就是那个漏洞本身。
 
diff --git a/packages/ui/app-boot/README.i18n.yaml b/packages/ui/app-boot/README.i18n.yaml
index 1c15f51109..59426a9041 100644
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/ui/app-boot/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/app-boot/README.md
-README.md: 9c2f9a8dac6b164cb23260e743eb2cdf1f29d3aa
-README.zh.md: 8422a176e682a87d1e592d5140b719e628e7d8e7
+README.md: 25e0c10932a2bede7f6c6582043af436b6153f4a
+README.zh.md: 649a60802660fdd8d4a6cd85dc64b5a65cee5a88
diff --git a/packages/ui/app-boot/README.md b/packages/ui/app-boot/README.md
index 9c2f9a8dac..25e0c10932 100644
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -37,7 +37,7 @@ A profile is a directory under `$DSH_HOME/profiles/<name>` (the Harness home res
 
 User-level machine-local preferences also live in the Harness home:
 
-- **`.env`** — the product CLI's ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. `loadLayeredEnv` snapshots each value's source, rejects bootstrap-only file variables, and materializes accepted values into `process.env` for Loader expressions and third-party libraries. Managed credentials live separately in [`.credentials.yaml`](../../credentials/credentials-local/README.md); a credential left in either `.env` remains a lower-priority fallback.
+- **`.env`** — the product CLI's ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. `loadLayeredEnv` snapshots each value's source, rejects case-insensitive bootstrap-only process/module/runtime/Git/network variables and the `DSH_`/`XDG_`/`DYLD_`/`BASH_FUNC_` namespaces, and materializes accepted values into `process.env` for Loader expressions and third-party libraries. Managed credentials live separately in [`.credentials.yaml`](../../credentials/credentials-local/README.md); a credential left in either `.env` remains a lower-priority fallback.
 - **`cordis.patch.yml`** (home level) and **`profiles/<name>/cordis.patch.yml`** — the user patch layers, applied after every bundle layer (per-profile first, then the home-level file, which therefore outranks it): an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount. A patch naming an entry id absent from the composed tree is a stderr warning. An empty or comments-only file throws (it parses to nothing, not to a list); disable the layer with `[]`.
 
 Long-lived surfaces keep `cordis.patch.yml` live through `watchUserPatches`; one-shot runs read only the startup value. The watcher targets the exact path even when the file or immediate parent does not exist, serializes bursts, and recomposes the user patches inside the caller's layer order (bundle layers below, overlay/flag patches above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
diff --git a/packages/ui/app-boot/README.zh.md b/packages/ui/app-boot/README.zh.md
index 8422a176e6..649a608026 100644
--- a/packages/ui/app-boot/README.zh.md
+++ b/packages/ui/app-boot/README.zh.md
@@ -37,7 +37,7 @@ profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`
 
 用户级的机器本地偏好同样位于 Harness home 中：
 
-- **`.env`**：产品 CLI 的普通环境层；调用目录的文件优先于 Harness home 的文件，两者都低于继承环境。`loadLayeredEnv` 记录每个值的来源，拒绝文件中的 bootstrap-only 变量，并把其余值物化进 `process.env`，供 Loader 表达式和第三方库使用。受管凭据另存于 [`.credentials.yaml`](../../credentials/credentials-local/README.md)；留在任一 `.env` 中的凭据仍是低优先级后备值。
+- **`.env`**：产品 CLI 的普通环境层；调用目录的文件优先于 Harness home 的文件，两者都低于继承环境。`loadLayeredEnv` 记录每个值的来源，按不区分大小写的方式拒绝文件中的 bootstrap-only 进程、模块、运行时、Git 与网络变量，以及整个 `DSH_`／`XDG_`／`DYLD_`／`BASH_FUNC_` 命名空间，并把其余值物化进 `process.env`，供 Loader 表达式和第三方库使用。受管凭据另存于 [`.credentials.yaml`](../../credentials/credentials-local/README.md)；留在任一 `.env` 中的凭据仍是低优先级后备值。
 - **`cordis.patch.yml`**（home 级）与 **`profiles/<name>/cordis.patch.yml`**：用户 patch 层，应用在所有组合包层之后（先应用逐 profile 的文件，再应用 home 级文件，因此后者优先级更高）：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在组合后的树中，则输出一条 stderr 警告。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用该层，请使用 `[]`。
 
 长期运行的 surface 会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay／标志 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
diff --git a/packages/ui/app-boot/src/index.ts b/packages/ui/app-boot/src/index.ts
index 240da02698..34b09949c4 100644
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -15,7 +15,7 @@ import { Context, type FiberState } from 'cordis'
 import Loader, { type Entry, type EntryOptions } from '@cordisjs/plugin-loader'
 import Include, { applyEntryPatches, entryListSchema, type PatchOptions } from '@cordisjs/plugin-include'
 import { dshHomePath, resolveDshHome } from '@deepseek-ai/dsh-paths'
-import { createEnvironmentSnapshot, isBootstrapOnly, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
+import { createEnvironmentSnapshot, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import type {} from '@cordisjs/plugin-hmr'
 // Side-effect type import: resolves `ctx.get('systemPrompt')` to the service.
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -88,6 +88,72 @@ export function loadEnv(
   }
 }
 
+/** Exact names no discovered file may set. */
+const BOOTSTRAP_NAMES = new Set([
+  // Process launch and module resolution.
+  'PATH', 'HOME', 'USERPROFILE', 'SHELL',
+  'NODE_OPTIONS', 'NODE_PATH', 'NODE_EXTRA_CA_CERTS',
+  'LD_PRELOAD', 'LD_LIBRARY_PATH', 'LD_AUDIT',
+  // Interpreter start-up hooks: each of these makes a runtime execute a file
+  // of the setter's choosing on every invocation, before the program runs.
+  // `BASH_ENV` is the sharpest — the bash tool spawns `bash -c`, which sources
+  // it every time — but every runtime an agent shells out to has one.
+  'BASH_ENV', 'ENV', 'SHELLOPTS', 'BASHOPTS',
+  'PERL5OPT', 'PERL5LIB', 'PYTHONSTARTUP', 'PYTHONPATH', 'RUBYOPT', 'RUBYLIB',
+  'JAVA_TOOL_OPTIONS', '_JAVA_OPTIONS', 'JDK_JAVA_OPTIONS',
+  'PYTHONHOME',
+  // Version-control hooks that run a command on the setter's behalf, and the
+  // config redirections that can define such a hook indirectly (a substituted
+  // git config file can set core.pager or a credential helper).
+  'GIT_SSH', 'GIT_SSH_COMMAND', 'GIT_EXTERNAL_DIFF', 'GIT_PAGER', 'GIT_EDITOR',
+  'GIT_ASKPASS', 'SSH_ASKPASS',
+  'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_COUNT',
+  'EDITOR', 'VISUAL', 'PAGER',
+  // Network reach and trust.
+  'SSL_CERT_FILE', 'SSL_CERT_DIR',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+  'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE',
+  // Turns off TLS verification outright, which is the sharpest form of
+  // "how the network is trusted".
+  'NODE_TLS_REJECT_UNAUTHORIZED',
+])
+
+/** Name prefixes no discovered file may set. */
+const BOOTSTRAP_PREFIXES = ['DSH_', 'XDG_', 'DYLD_', 'BASH_FUNC_']
+
+/**
+ * Whether a variable may come only from the inherited process environment.
+ *
+ * The invoking project is trusted to *configure* the agent's work — its
+ * endpoints, its ordinary variables, even a credential. It is not trusted to
+ * change the harness itself, and that is what a bootstrap variable does: it
+ * decides how a process launches (`PATH`, `NODE_OPTIONS`, `LD_PRELOAD`), what
+ * code a runtime executes before the program it was asked to run (`BASH_ENV`
+ * and its per-language siblings, the Git hook commands), where model-visible
+ * instructions load from (`DSH_*` covers the Harness home, the agents home,
+ * and the bundled skill root), or how the network is reached and trusted
+ * (proxy and CA variables).
+ *
+ * The distinction is that these take effect with no user action, before any
+ * turn, outside the permission policy and the sandbox — `DSH_PERMISSION_MODE`
+ * would switch off the approvals that make trusting a project meaningful at
+ * all, and `BASH_ENV` runs a file of the project's choosing on every single
+ * `bash -c` the tool issues. Trusting a project's code to run under the
+ * agent's policy is not the same as letting it rewrite that policy.
+ *
+ * They are therefore rejected at load rather than ranked below another layer:
+ * a user who wrote one into a file believes it applies, and silently ignoring
+ * it is its own failure. The whole `DSH_*` namespace is denied rather than an
+ * audited subset, because a switch added later must not become settable by
+ * being forgotten.
+ * @param name - the variable name.
+ * @returns true when only the inherited environment may supply it.
+ */
+function isBootstrapOnly(name: string): boolean {
+  const upper = name.toUpperCase()
+  return BOOTSTRAP_NAMES.has(upper) || BOOTSTRAP_PREFIXES.some(prefix => upper.startsWith(prefix))
+}
+
 /**
  * Parse one directory's `.env` without applying it, rejecting any bootstrap
  * variable it declares. A discovered file must not decide how this process
diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index ecd2fca34b..1c5f784bc4 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/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/util/environment/README.md
-README.md: 1df857851f0f0a5a5ac52365c5e563a1c001bfca
-README.zh.md: 41ea1af3a6eb95d58456f43e0f7f0a90e4fe7ac6
+README.md: af6b0d9cc66b0bdfa1ad9ffb273260d0f4f06ddc
+README.zh.md: 98c3c69ec96f835721e042960fe044fe075e6159
diff --git a/packages/util/environment/README.md b/packages/util/environment/README.md
index 1df857851f..af6b0d9cc6 100644
--- a/packages/util/environment/README.md
+++ b/packages/util/environment/README.md
@@ -30,17 +30,7 @@ const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 
 `environmentOf(ctx)` returns the launcher's snapshot when the product CLI booted the tree, and otherwise the inherited environment as the only layer. That fallback does not weaken the rules: an SDK host or a bare `cordis.yml` discovered no files, so everything it has really is the environment it was launched with.
 
-## Bootstrap variables
-
-`isBootstrapOnly(name)` names the variables only the inherited environment may set. The launcher rejects a `.env` that declares one, before applying anything.
-
-Trusting a project to configure the agent's work is not the same as letting it change the harness. A bootstrap variable decides **how a process launches** (`PATH`, `SHELL`, `NODE_OPTIONS`, `LD_PRELOAD`, `DYLD_*`), **what code a runtime executes before the program it was asked to run** (`BASH_ENV` and its per-language siblings — `PERL5OPT`, `PYTHONSTARTUP`, `RUBYOPT`, `JAVA_TOOL_OPTIONS` — plus the Git hook commands), **where model-visible instructions load from** (the whole `DSH_*` namespace, `HOME`, `XDG_*`), or **how the network is reached and trusted** (proxy and CA variables). Matching is case-insensitive, so `https_proxy` is not a bypass.
-
-These take effect with no user action, before any turn, outside the permission policy and the sandbox: `DSH_PERMISSION_MODE` would switch off the approvals that make trusting a project meaningful, and `BASH_ENV` runs a file of the project's choosing on every `bash -c` the bash tool issues.
-
-The whole `DSH_*` namespace is denied rather than an audited subset: the harness's own switches — the permission mode, the agents home, the bundled skill root — are exactly what a hostile project would want, and a switch added later must not become settable by forgetting to list it.
-
 ## Known Limitations and Deferred Work
 
-- **The snapshot is not a subprocess boundary** — every layer is also materialized into `process.env`, so ordinary project variables reach child processes under [`dsh-subprocess`](../../subprocess/subprocess/README.md)'s scrub. That is intended for ordinary variables; the code-loading hooks that would abuse it are rejected at load instead, and the deny list is the thing to extend when a new runtime hook appears.
+- **The snapshot is not a subprocess boundary** — every layer is also materialized into `process.env`, so ordinary project variables reach child processes under [`dsh-subprocess`](../../subprocess/subprocess/README.md)'s scrub. The product launcher's [`.env` contract](../../ui/app-boot/README.md#profiles) rejects bootstrap variables before materialization.
 - **No per-workspace layer** — the project layer is the *invoking* directory, fixed at launch. A workspace selected later in the Web UI contributes nothing, deliberately: following it would let a model's own workspace change the harness environment mid-session.
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index 41ea1af3a6..98c3c69ec9 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -30,17 +30,7 @@ const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 
 当产品 CLI（命令行界面）启动了这棵树时，`environmentOf(ctx)` 返回启动器的快照；否则返回只含继承环境的那一层。该回退并不削弱规则：SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，因此它拥有的一切确实就是它被启动时的环境。
 
-## bootstrap 变量
-
-`isBootstrapOnly(name)` 给出只有继承环境才能设置的变量。启动器一旦发现某个 `.env` 声明了其中之一，就会在应用任何内容之前拒绝启动。
-
-信任一个项目配置 agent 的工作，不等于让它改变 harness 本身。bootstrap 变量决定**进程如何启动**（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD`、`DYLD_*`）、**运行时在执行被要求运行的程序之前先执行哪些代码**（`BASH_ENV` 及其各语言同类——`PERL5OPT`、`PYTHONSTARTUP`、`RUBYOPT`、`JAVA_TOOL_OPTIONS`——以及 Git 的钩子命令）、**模型可见的指令从哪里加载**（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），或者**网络如何抵达与信任**（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
-
-这些变量无需任何用户动作、在任何一轮开始之前、且在权限策略与沙箱之外就生效：`DSH_PERMISSION_MODE` 会关掉让「信任项目」有意义的那道审批，而 `BASH_ENV` 会在 bash 工具发出的每一次 `bash -c` 上执行项目指定的文件。
-
-整个 `DSH_*` 命名空间被拒绝，而不是只拒绝一份经过审查的子集：harness 自己的开关——权限模式、agents home、内置 skill（技能）根目录——恰恰是敌意项目最想要的，而后来新增的开关不能因为忘记登记就变得可设置。
-
 ## Known Limitations and Deferred Work
 
-- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。这对普通变量是有意为之；会滥用这一点的代码加载钩子改为在加载时拒绝，新的运行时钩子出现时该扩展的是那份拒绝清单。
+- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 契约](../../ui/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
 - **没有按工作区划分的层**：项目层是*调用*目录，在启动时固定。之后在 Web UI 中选择的工作区不贡献任何内容，这是刻意的：跟随它等于让模型自己的工作区在会话中途改变 harness 的环境。
diff --git a/packages/util/environment/src/index.ts b/packages/util/environment/src/index.ts
index a86689e809..939ddba633 100644
--- a/packages/util/environment/src/index.ts
+++ b/packages/util/environment/src/index.ts
@@ -143,69 +143,3 @@ declare module 'cordis' {
     launcherEnvironment?: EnvironmentSnapshot
   }
 }
-
-/** Exact names no discovered file may set. */
-const BOOTSTRAP_NAMES = new Set([
-  // Process launch and module resolution.
-  'PATH', 'HOME', 'USERPROFILE', 'SHELL',
-  'NODE_OPTIONS', 'NODE_PATH', 'NODE_EXTRA_CA_CERTS',
-  'LD_PRELOAD', 'LD_LIBRARY_PATH', 'LD_AUDIT',
-  // Interpreter start-up hooks: each of these makes a runtime execute a file
-  // of the setter's choosing on every invocation, before the program runs.
-  // `BASH_ENV` is the sharpest — the bash tool spawns `bash -c`, which sources
-  // it every time — but every runtime an agent shells out to has one.
-  'BASH_ENV', 'ENV', 'SHELLOPTS', 'BASHOPTS',
-  'PERL5OPT', 'PERL5LIB', 'PYTHONSTARTUP', 'PYTHONPATH', 'RUBYOPT', 'RUBYLIB',
-  'JAVA_TOOL_OPTIONS', '_JAVA_OPTIONS', 'JDK_JAVA_OPTIONS',
-  'PYTHONHOME',
-  // Version-control hooks that run a command on the setter's behalf, and the
-  // config redirections that can define such a hook indirectly (a substituted
-  // git config file can set core.pager or a credential helper).
-  'GIT_SSH', 'GIT_SSH_COMMAND', 'GIT_EXTERNAL_DIFF', 'GIT_PAGER', 'GIT_EDITOR',
-  'GIT_ASKPASS', 'SSH_ASKPASS',
-  'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_COUNT',
-  'EDITOR', 'VISUAL', 'PAGER',
-  // Network reach and trust.
-  'SSL_CERT_FILE', 'SSL_CERT_DIR',
-  'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
-  'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE',
-  // Turns off TLS verification outright, which is the sharpest form of
-  // "how the network is trusted".
-  'NODE_TLS_REJECT_UNAUTHORIZED',
-])
-
-/** Name prefixes no discovered file may set. */
-const BOOTSTRAP_PREFIXES = ['DSH_', 'XDG_', 'DYLD_', 'BASH_FUNC_']
-
-/**
- * Whether a variable may come only from the inherited process environment.
- *
- * The invoking project is trusted to *configure* the agent's work — its
- * endpoints, its ordinary variables, even a credential. It is not trusted to
- * change the harness itself, and that is what a bootstrap variable does: it
- * decides how a process launches (`PATH`, `NODE_OPTIONS`, `LD_PRELOAD`), what
- * code a runtime executes before the program it was asked to run (`BASH_ENV`
- * and its per-language siblings, the Git hook commands), where model-visible
- * instructions load from (`DSH_*` covers the Harness home, the agents home,
- * and the bundled skill root), or how the network is reached and trusted
- * (proxy and CA variables).
- *
- * The distinction is that these take effect with no user action, before any
- * turn, outside the permission policy and the sandbox — `DSH_PERMISSION_MODE`
- * would switch off the approvals that make trusting a project meaningful at
- * all, and `BASH_ENV` runs a file of the project's choosing on every single
- * `bash -c` the tool issues. Trusting a project's code to run under the
- * agent's policy is not the same as letting it rewrite that policy.
- *
- * They are therefore rejected at load rather than ranked below another layer:
- * a user who wrote one into a file believes it applies, and silently ignoring
- * it is its own failure. The whole `DSH_*` namespace is denied rather than an
- * audited subset, because a switch added later must not become settable by
- * being forgotten.
- * @param name - the variable name.
- * @returns true when only the inherited environment may supply it.
- */
-export function isBootstrapOnly(name: string): boolean {
-  const upper = name.toUpperCase()
-  return BOOTSTRAP_NAMES.has(upper) || BOOTSTRAP_PREFIXES.some(prefix => upper.startsWith(prefix))
-}
diff --git a/packages/util/environment/tests/environment.spec.ts b/packages/util/environment/tests/environment.spec.ts
index 8ed3823832..5951484a83 100644
--- a/packages/util/environment/tests/environment.spec.ts
+++ b/packages/util/environment/tests/environment.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import {
-  createEnvironmentSnapshot, DSH_ENVIRONMENT_KEY, environmentOf, isBootstrapOnly,
+  createEnvironmentSnapshot, DSH_ENVIRONMENT_KEY, environmentOf,
 } from '../src/index.ts'
 
 const layered = createEnvironmentSnapshot([
@@ -67,37 +67,3 @@ describe('environmentOf', () => {
     }
   })
 })
-
-describe('isBootstrapOnly', () => {
-  it.each([
-    'PATH', 'HOME', 'USERPROFILE', 'SHELL',
-    'NODE_OPTIONS', 'NODE_PATH', 'NODE_EXTRA_CA_CERTS',
-    'LD_PRELOAD', 'LD_LIBRARY_PATH',
-    'SSL_CERT_FILE', 'SSL_CERT_DIR',
-    'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
-  ])('rejects %s, which decides how the process starts or reaches the network', (name) => {
-    expect(isBootstrapOnly(name)).toBe(true)
-  })
-
-  it.each([
-    ['DSH_HOME', 'the harness home'],
-    ['DSH_PERMISSION_MODE', 'the permission mode'],
-    ['DSH_AGENTS_HOME', 'a model-visible instruction root'],
-    ['DSH_ANYTHING_ADDED_LATER', 'a switch that does not exist yet'],
-    ['XDG_CONFIG_HOME', 'a state root'],
-    ['DYLD_INSERT_LIBRARIES', 'a library preload'],
-  ])('rejects the whole namespace: %s (%s)', (name) => {
-    expect(isBootstrapOnly(name)).toBe(true)
-  })
-
-  it('matches case-insensitively, so a lowercase proxy name is not a bypass', () => {
-    expect(isBootstrapOnly('https_proxy')).toBe(true)
-    expect(isBootstrapOnly('dsh_permission_mode')).toBe(true)
-  })
-
-  it('allows ordinary variables, including provider credentials and endpoints', () => {
-    for (const name of ['DEEPSEEK_API_KEY', 'DEEPSEEK_BASE_URL', 'EXA_API_KEY', 'MY_PROJECT_FLAG', 'PATHS']) {
-      expect(isBootstrapOnly(name)).toBe(false)
-    }
-  })
-})

From 62ae990c27d7dd5bc4d78380aaa655e7949cfe56 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:43:15 +0800
Subject: [PATCH 172/516] cleanup(config): consolidate source ownership
 rationale

---
 packages/ui/app-boot/README.i18n.yaml       |  4 +-
 packages/ui/app-boot/README.md              |  2 +-
 packages/ui/app-boot/README.zh.md           |  2 +-
 packages/ui/app-boot/src/index.ts           | 87 +++------------------
 packages/ui/app-boot/tests/app-boot.spec.ts | 14 +---
 packages/util/environment/src/index.ts      | 41 +++-------
 scripts/verify-config-source-ownership.ts   | 14 +---
 7 files changed, 30 insertions(+), 134 deletions(-)

diff --git a/packages/ui/app-boot/README.i18n.yaml b/packages/ui/app-boot/README.i18n.yaml
index 59426a9041..422e585575 100644
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/ui/app-boot/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/app-boot/README.md
-README.md: 25e0c10932a2bede7f6c6582043af436b6153f4a
-README.zh.md: 649a60802660fdd8d4a6cd85dc64b5a65cee5a88
+README.md: 359f05a83b41db6db5ede40db7317a0fb15de43b
+README.zh.md: a916236e30b50cc884d9d5876f27fcb1aa6f0777
diff --git a/packages/ui/app-boot/README.md b/packages/ui/app-boot/README.md
index 25e0c10932..359f05a83b 100644
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -37,7 +37,7 @@ A profile is a directory under `$DSH_HOME/profiles/<name>` (the Harness home res
 
 User-level machine-local preferences also live in the Harness home:
 
-- **`.env`** — the product CLI's ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. `loadLayeredEnv` snapshots each value's source, rejects case-insensitive bootstrap-only process/module/runtime/Git/network variables and the `DSH_`/`XDG_`/`DYLD_`/`BASH_FUNC_` namespaces, and materializes accepted values into `process.env` for Loader expressions and third-party libraries. Managed credentials live separately in [`.credentials.yaml`](../../credentials/credentials-local/README.md); a credential left in either `.env` remains a lower-priority fallback.
+- **`.env`** — the product CLI's ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. `loadLayeredEnv` snapshots each value's source, rejects [bootstrap-only file variables](../../../.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md#decision) case-insensitively, and materializes accepted values into `process.env` for Loader expressions and third-party libraries. Managed credentials live separately in [`.credentials.yaml`](../../credentials/credentials-local/README.md); a credential left in either `.env` remains a lower-priority fallback.
 - **`cordis.patch.yml`** (home level) and **`profiles/<name>/cordis.patch.yml`** — the user patch layers, applied after every bundle layer (per-profile first, then the home-level file, which therefore outranks it): an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount. A patch naming an entry id absent from the composed tree is a stderr warning. An empty or comments-only file throws (it parses to nothing, not to a list); disable the layer with `[]`.
 
 Long-lived surfaces keep `cordis.patch.yml` live through `watchUserPatches`; one-shot runs read only the startup value. The watcher targets the exact path even when the file or immediate parent does not exist, serializes bursts, and recomposes the user patches inside the caller's layer order (bundle layers below, overlay/flag patches above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
diff --git a/packages/ui/app-boot/README.zh.md b/packages/ui/app-boot/README.zh.md
index 649a608026..a916236e30 100644
--- a/packages/ui/app-boot/README.zh.md
+++ b/packages/ui/app-boot/README.zh.md
@@ -37,7 +37,7 @@ profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`
 
 用户级的机器本地偏好同样位于 Harness home 中：
 
-- **`.env`**：产品 CLI 的普通环境层；调用目录的文件优先于 Harness home 的文件，两者都低于继承环境。`loadLayeredEnv` 记录每个值的来源，按不区分大小写的方式拒绝文件中的 bootstrap-only 进程、模块、运行时、Git 与网络变量，以及整个 `DSH_`／`XDG_`／`DYLD_`／`BASH_FUNC_` 命名空间，并把其余值物化进 `process.env`，供 Loader 表达式和第三方库使用。受管凭据另存于 [`.credentials.yaml`](../../credentials/credentials-local/README.md)；留在任一 `.env` 中的凭据仍是低优先级后备值。
+- **`.env`**：产品 CLI 的普通环境层；调用目录的文件优先于 Harness home 的文件，两者都低于继承环境。`loadLayeredEnv` 记录每个值的来源，按不区分大小写的方式拒绝 [bootstrap-only 文件变量](../../../.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md#decision)，并把其余值物化进 `process.env`，供 Loader 表达式和第三方库使用。受管凭据另存于 [`.credentials.yaml`](../../credentials/credentials-local/README.md)；留在任一 `.env` 中的凭据仍是低优先级后备值。
 - **`cordis.patch.yml`**（home 级）与 **`profiles/<name>/cordis.patch.yml`**：用户 patch 层，应用在所有组合包层之后（先应用逐 profile 的文件，再应用 home 级文件，因此后者优先级更高）：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在组合后的树中，则输出一条 stderr 警告。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用该层，请使用 `[]`。
 
 长期运行的 surface 会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay／标志 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
diff --git a/packages/ui/app-boot/src/index.ts b/packages/ui/app-boot/src/index.ts
index 34b09949c4..72c2e8137f 100644
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -94,17 +94,12 @@ const BOOTSTRAP_NAMES = new Set([
   'PATH', 'HOME', 'USERPROFILE', 'SHELL',
   'NODE_OPTIONS', 'NODE_PATH', 'NODE_EXTRA_CA_CERTS',
   'LD_PRELOAD', 'LD_LIBRARY_PATH', 'LD_AUDIT',
-  // Interpreter start-up hooks: each of these makes a runtime execute a file
-  // of the setter's choosing on every invocation, before the program runs.
-  // `BASH_ENV` is the sharpest — the bash tool spawns `bash -c`, which sources
-  // it every time — but every runtime an agent shells out to has one.
+  // Interpreter startup hooks.
   'BASH_ENV', 'ENV', 'SHELLOPTS', 'BASHOPTS',
   'PERL5OPT', 'PERL5LIB', 'PYTHONSTARTUP', 'PYTHONPATH', 'RUBYOPT', 'RUBYLIB',
   'JAVA_TOOL_OPTIONS', '_JAVA_OPTIONS', 'JDK_JAVA_OPTIONS',
   'PYTHONHOME',
-  // Version-control hooks that run a command on the setter's behalf, and the
-  // config redirections that can define such a hook indirectly (a substituted
-  // git config file can set core.pager or a credential helper).
+  // Version-control command hooks and config redirects.
   'GIT_SSH', 'GIT_SSH_COMMAND', 'GIT_EXTERNAL_DIFF', 'GIT_PAGER', 'GIT_EDITOR',
   'GIT_ASKPASS', 'SSH_ASKPASS',
   'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_COUNT',
@@ -113,8 +108,6 @@ const BOOTSTRAP_NAMES = new Set([
   'SSL_CERT_FILE', 'SSL_CERT_DIR',
   'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
   'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE',
-  // Turns off TLS verification outright, which is the sharpest form of
-  // "how the network is trusted".
   'NODE_TLS_REJECT_UNAUTHORIZED',
 ])
 
@@ -122,30 +115,8 @@ const BOOTSTRAP_NAMES = new Set([
 const BOOTSTRAP_PREFIXES = ['DSH_', 'XDG_', 'DYLD_', 'BASH_FUNC_']
 
 /**
- * Whether a variable may come only from the inherited process environment.
- *
- * The invoking project is trusted to *configure* the agent's work — its
- * endpoints, its ordinary variables, even a credential. It is not trusted to
- * change the harness itself, and that is what a bootstrap variable does: it
- * decides how a process launches (`PATH`, `NODE_OPTIONS`, `LD_PRELOAD`), what
- * code a runtime executes before the program it was asked to run (`BASH_ENV`
- * and its per-language siblings, the Git hook commands), where model-visible
- * instructions load from (`DSH_*` covers the Harness home, the agents home,
- * and the bundled skill root), or how the network is reached and trusted
- * (proxy and CA variables).
- *
- * The distinction is that these take effect with no user action, before any
- * turn, outside the permission policy and the sandbox — `DSH_PERMISSION_MODE`
- * would switch off the approvals that make trusting a project meaningful at
- * all, and `BASH_ENV` runs a file of the project's choosing on every single
- * `bash -c` the tool issues. Trusting a project's code to run under the
- * agent's policy is not the same as letting it rewrite that policy.
- *
- * They are therefore rejected at load rather than ranked below another layer:
- * a user who wrote one into a file believes it applies, and silently ignoring
- * it is its own failure. The whole `DSH_*` namespace is denied rather than an
- * audited subset, because a switch added later must not become settable by
- * being forgotten.
+ * Whether a variable may come only from the inherited process environment
+ * because it changes process, runtime, VCS, or network bootstrap.
  * @param name - the variable name.
  * @returns true when only the inherited environment may supply it.
  */
@@ -155,12 +126,8 @@ function isBootstrapOnly(name: string): boolean {
 }
 
 /**
- * Parse one directory's `.env` without applying it, rejecting any bootstrap
- * variable it declares. A discovered file must not decide how this process
- * launches, where its code and model-visible instructions come from, or how it
- * reaches the network, so a violation fails the launch BEFORE anything is
- * materialized — reporting it afterwards would leave the process already
- * running under the value it refused.
+ * Parse one directory's `.env` without applying it, rejecting bootstrap-only
+ * names before any value is materialized.
  * @param binName - the diagnostic prefix on the thrown error.
  * @param dir - the directory whose `.env` to read.
  * @param warn - sink for the one-line unreadable-file diagnostic.
@@ -181,12 +148,7 @@ function readEnvLayer(
     // ENOENT (no .env) is fine — rely on the ambient environment.
     return undefined
   }
-  // `node:util`'s parseEnv is the same parser `--env-file` and
-  // `process.loadEnvFile` use. Checking with a second dialect (npm dotenv)
-  // would leave the rejection rule and the thing it guards on independently
-  // maintained parsers: a name Node accepts but the checker does not would
-  // reach `process.env` unchecked, and `BASH_ENV` there runs a file of the
-  // project's choosing on every `bash -c` the bash tool issues.
+  // Parse once so validation and materialization use exactly the same entries.
   const values = parseEnv(content) as Record<string, string>
   for (const name of Object.keys(values)) {
     if (!isBootstrapOnly(name)) continue
@@ -200,30 +162,10 @@ function readEnvLayer(
 }
 
 /**
- * Load the dsh product CLI's user environment and return it as a snapshot that
- * remembers which layer supplied each value: the invoking directory's `.env`
- * over the Harness home's `.env`, both under the inherited process
- * environment.
- *
- * Each layer is parsed once, checked, and only then applied — never replacing
- * a name already set, which is what makes the layering `user < project <
- * inherited`. The single parse is deliberate: the rejection rule and the
- * values that reach `process.env` must come from the same parser, or a name
- * one dialect accepts and the other misses would slip past the check. Values do reach
- * `process.env`, because a user's own `--config` tree and third-party
- * libraries read it; the returned snapshot is the authority for everything the
- * harness itself resolves, since `process.env` alone cannot say whether a
- * value came from the launching shell or from a file inside the workspace.
- *
- * The Harness home is resolved from the inherited environment *before* either
- * file loads, so a project `.env` can never redirect which user document is
- * read. Only the product CLI layers these files: an SDK or example bin loads
- * its own directory through {@link loadEnv} and must not inherit a developer's
- * `$DSH_HOME`.
- *
- * These are ordinary environment values with ordinary environment reach. A
- * secret the Harness should own and isolate belongs in the credentials
- * document, which is never materialized here.
+ * Load the product CLI's inherited > invoking-directory `.env` > Harness-home
+ * `.env` snapshot. The Harness home resolves before either file; both files
+ * are checked before either is applied, and accepted values are materialized
+ * without replacing inherited ones. The snapshot preserves source provenance.
  * @param binName - the diagnostic prefix on the diagnostics.
  * @param cwd - the invoking directory whose `.env` is the project layer.
  * @param warn - sink for the one-line misconfiguration diagnostics.
@@ -239,12 +181,7 @@ export function loadLayeredEnv(
   // Parse both layers first: a rejection must not leave one file applied.
   const project = readEnvLayer(binName, cwd, warn)
   const user = home === resolve(cwd) ? undefined : readEnvLayer(binName, home, warn)
-  // Assign the entries this function already parsed and checked, rather than
-  // re-reading each file through `process.loadEnvFile`. One parse means the
-  // snapshot, the rejection rule, and `process.env` can never disagree about
-  // what a file contains. Skipping names already set reproduces the
-  // never-replace behavior that makes the layering `user < project <
-  // inherited`.
+  // Apply the checked values without replacing a higher-ranked name.
   for (const layer of [project, user]) {
     if (layer === undefined) continue
     for (const [name, value] of Object.entries(layer.values)) {
diff --git a/packages/ui/app-boot/tests/app-boot.spec.ts b/packages/ui/app-boot/tests/app-boot.spec.ts
index 447b2f5949..baeb98fe77 100644
--- a/packages/ui/app-boot/tests/app-boot.spec.ts
+++ b/packages/ui/app-boot/tests/app-boot.spec.ts
@@ -114,8 +114,6 @@ describe('loadLayeredEnv', () => {
     const warn = vi.fn()
     try {
       loadLayeredEnv(NAME, project, warn)
-      // Both files load; the project layer wins the name they share, and the
-      // inherited environment wins over both.
       expect(process.env[NAMES[0]]).toBe('project')
       expect(process.env[NAMES[1]]).toBe('user-only')
       expect(process.env[NAMES[2]]).toBe('project-only')
@@ -142,8 +140,6 @@ describe('loadLayeredEnv', () => {
     vi.stubEnv('DSH_HOME', home)
     try {
       expect(() => loadLayeredEnv(NAME, project, vi.fn())).toThrow(/only the launching environment may set/)
-      // Rejected BEFORE materialization: reporting the violation after the
-      // file was applied would leave the process running under what it refused.
       expect(process.env[NAMES[1]]).toBeUndefined()
     } finally {
       clear()
@@ -162,7 +158,6 @@ describe('loadLayeredEnv', () => {
       const snapshot = loadLayeredEnv(NAME, project, vi.fn())
       expect(snapshot.get(NAMES[1])).toEqual({ value: 'u', source: 'user-env', path: join(home, '.env') })
       expect(snapshot.get(NAMES[2])).toEqual({ value: 'p', source: 'project-env', path: join(project, '.env') })
-      // getFrom is a refusal, not a demotion: an omitted layer is invisible.
       expect(snapshot.getFrom(NAMES[2], ['process', 'user-env'])).toBeUndefined()
     } finally {
       clear()
@@ -190,9 +185,7 @@ describe('loadLayeredEnv', () => {
   it('warns and continues when a layer exists but cannot be read', () => {
     const home = tmp()
     const project = tmp()
-    // A directory named `.env` is present-but-unreadable (EISDIR): unlike an
-    // absent file, it is a real misconfiguration, so it is reported rather
-    // than passed over in silence — and the other layers still load.
+    // A directory named `.env` is a present-but-unreadable layer.
     mkdirSync(join(home, '.env'))
     writeFileSync(join(project, '.env'), `${NAMES[2]}=project-only\n`)
     clear()
@@ -238,8 +231,6 @@ describe('loadLayeredEnv', () => {
     vi.stubEnv('DSH_HOME', home)
     const warn = vi.fn()
     try {
-      // No user `.env` exists, which is ordinary rather than a fault: the
-      // layer is simply absent, and nothing is reported.
       const snapshot = loadLayeredEnv(NAME, project, warn)
       expect(warn).not.toHaveBeenCalled()
       expect(snapshot.get(NAMES[2])).toEqual({ value: 'project-only', source: 'project-env', path: join(project, '.env') })
@@ -270,9 +261,6 @@ describe('loadLayeredEnv', () => {
     clear()
     vi.stubEnv('DSH_HOME', both)
     try {
-      // One file cannot be two layers. It is the project layer, because that
-      // is the more trusted of the two — reading it twice would otherwise
-      // put the same path at two different ranks.
       const snapshot = loadLayeredEnv(NAME, both, vi.fn())
       expect(snapshot.get(NAMES[2])).toEqual({ value: 'one-file', source: 'project-env', path: join(both, '.env') })
     } finally {
diff --git a/packages/util/environment/src/index.ts b/packages/util/environment/src/index.ts
index 939ddba633..741e5752cd 100644
--- a/packages/util/environment/src/index.ts
+++ b/packages/util/environment/src/index.ts
@@ -1,15 +1,8 @@
 /**
- * The launch-time environment as one immutable snapshot that remembers which
- * layer supplied each value. The harness resolves user-facing values against
- * this rather than against `process.env`, because the layers differ in how
- * much they are trusted: an inherited variable is this run's explicit intent,
- * a file discovered under the invoking directory is whatever the project
- * happens to contain, and a consumer that cannot tell them apart cannot make
- * that distinction.
- *
- * Values still reach `process.env` as well — a user's own `--config` tree and
- * third-party libraries read it — but that flattened view is not the
- * authority for anything the harness itself resolves.
+ * Immutable launch-time environment snapshot with per-value source
+ * provenance. Harness consumers resolve through it instead of a flattened
+ * `process.env`; launchers may still materialize accepted values for config
+ * expressions and third-party libraries.
  * @module @deepseek-ai/dsh-environment
  */
 
@@ -49,10 +42,8 @@ export interface EnvironmentSnapshot {
    */
   get(name: string): EnvironmentEntry | undefined
   /**
-   * Resolve one name across only the layers the caller trusts for this
-   * decision. Omitting a layer is a refusal, not a demotion: a routing field
-   * that must never come from a project directory omits `project-env` so no
-   * ordering change can let it back in.
+   * Resolve one name only from `sources`, retaining canonical trust order;
+   * omitted layers are unreachable.
    * @param name - the variable name.
    * @param sources - the layers allowed in the canonical trust order.
    * @returns the first matching entry, or `undefined`.
@@ -85,13 +76,8 @@ export interface EnvironmentLayerInput {
  * @returns the immutable snapshot.
  */
 export function createEnvironmentSnapshot(layers: readonly EnvironmentLayerInput[]): EnvironmentSnapshot {
-  // Copied per layer so a later mutation of `process.env` — or of a caller's
-  // own object — cannot change what this snapshot reports. Windows environment
-  // names are case-insensitive, so lookups there fold case: otherwise a shell
-  // that set `deepseek_api_key` would be invisible to a consumer asking for
-  // `DEEPSEEK_API_KEY`, and a lower-ranked layer spelling it in caps would win
-  // a decision the launch had already made. POSIX names are case-sensitive and
-  // must stay exact.
+  // Copy every layer so later mutations cannot change the snapshot. Fold names
+  // on Windows so case variants cannot split precedence; POSIX remains exact.
   const bySource = new Map<EnvironmentSource, { path?: string; values: Map<string, string> }>()
   for (const layer of layers) {
     bySource.set(layer.source, {
@@ -120,15 +106,8 @@ export function createEnvironmentSnapshot(layers: readonly EnvironmentLayerInput
 export const DSH_ENVIRONMENT_KEY = 'launcherEnvironment'
 
 /**
- * The snapshot to resolve against, whatever booted this tree: the launcher's
- * when the product CLI provided one, otherwise the inherited environment
- * alone.
- *
- * The fallback does not weaken the layer rules — it applies the same rules to
- * a host that has exactly one layer. An SDK embedder or a bare `cordis.yml`
- * never discovered a project or user file, so everything it has really is the
- * environment it was launched with, and `getFrom(..., ['process'])` is exactly
- * right for it.
+ * Return the launcher's snapshot, or the inherited environment as the sole
+ * layer when the host provided none.
  * @param ctx - the consuming plugin's context.
  * @returns the snapshot to resolve user-facing values against.
  */
diff --git a/scripts/verify-config-source-ownership.ts b/scripts/verify-config-source-ownership.ts
index e027fcba61..b0f4b89cdf 100644
--- a/scripts/verify-config-source-ownership.ts
+++ b/scripts/verify-config-source-ownership.ts
@@ -1,8 +1,6 @@
 /**
- * Gate: shipped Cordis configuration does not use the ordinary inline form
- * for a credential or endpoint from the environment. This narrow source-shape
- * lint prevents checked-in composition from bypassing the credential seam and
- * endpoint ladder; adapters remain responsible for actual value resolution.
+ * Gate for forbidden credential or endpoint environment inlines in shipped
+ * Cordis configuration.
  * @module scripts/verify-config-source-ownership
  */
 
@@ -21,13 +19,7 @@ const SHIPPED_CONFIG_GLOBS = [
   'python/*/src/**/cordis.yml',
 ]
 
-/**
- * Config keys that must never be inlined from the environment. Line-anchored
- * on purpose: this is a tripwire for the shape people actually write, not a
- * YAML analysis. A folded scalar or a block-literal spelling would slip past
- * it, which is acceptable because the rule it guards is also stated in the
- * owning Agent Note and enforced by the adapters' own resolution.
- */
+/** Ordinary single-line forms this narrow source-shape check rejects; not full YAML analysis. */
 const INLINE_DENY = /^\s*(apiKey|baseURL|apiKeyEnv|authToken|headers)\s*:\s*!!js\b/
 
 /** Return every forbidden inline environment form in shipped configuration. */

From 8315bfdc1f16b28f4708ff7458432d5208e53f3b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:45:28 +0800
Subject: [PATCH 173/516] fix(notes): address archive review findings

---
 ...2026-08-04-conversation-column-one-axis-scroll.i18n.yaml | 6 ------
 .agents/notes/archived/manifest.json                        | 3 ---
 ...2026-08-04-conversation-column-one-axis-scroll.i18n.yaml | 6 ++++++
 .../2026-08-04-conversation-column-one-axis-scroll.md       | 1 -
 .../2026-08-04-conversation-column-one-axis-scroll.zh.md    | 5 ++---
 .../feature/2026-07-20-dsh-cli-personal-config.i18n.yaml    | 4 ++--
 .../feature/2026-07-20-dsh-cli-personal-config.md           | 2 +-
 .../feature/2026-07-20-dsh-cli-personal-config.zh.md        | 2 +-
 packages/client/ui-conversation/README.i18n.yaml            | 2 +-
 packages/client/ui-conversation/README.zh.md                | 2 +-
 10 files changed, 14 insertions(+), 19 deletions(-)
 delete mode 100644 .agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
 rename .agents/notes/{archived => implemented}/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md (99%)
 rename .agents/notes/{archived => implemented}/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md (97%)

diff --git a/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml b/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
deleted file mode 100644
index cb05519fde..0000000000
--- a/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
-2026-08-04-conversation-column-one-axis-scroll.md: e8f80c23a2ac2230079802fb6c85fec6c8b8e807
-2026-08-04-conversation-column-one-axis-scroll.zh.md: a7378b2d5ec026d6a054a080347b155cc476a57a
diff --git a/.agents/notes/archived/manifest.json b/.agents/notes/archived/manifest.json
index 6fa5f06ceb..c46bb59b44 100644
--- a/.agents/notes/archived/manifest.json
+++ b/.agents/notes/archived/manifest.json
@@ -94,9 +94,6 @@
     "bug-fix/2026-08-03-tui-long-session-render-costs.i18n.yaml": "sha256:f65f7bf8fc84c7a1f022ee393c8d969c06d9bde8bed3a0206de86fb35b246ac6",
     "bug-fix/2026-08-03-tui-long-session-render-costs.md": "sha256:6ecf2ef831f527f361ade18a882d79bc6eccf15cc676d05728e7753f41cde051",
     "bug-fix/2026-08-03-tui-long-session-render-costs.zh.md": "sha256:5f44e707b332e13fa06d625212173ea055c1c3c0aee60888435a0ff099ec6037",
-    "bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml": "sha256:ec2ab13c899d2f138cdad0fcbbba3565395ca13bb2c6925ac0fee6518c7b1a2b",
-    "bug-fix/2026-08-04-conversation-column-one-axis-scroll.md": "sha256:7866cb16460aa47a958b81e904161aa655d54ac331b32f585d6429fffb5c700c",
-    "bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md": "sha256:e01af7c18cad86dac88720014eaeb1f5491eb7feac1e542c5a3d0fd2cc3afee5",
     "feature/2026-06-14-acp-agent-client-protocol.i18n.yaml": "sha256:006795baa43ae962a8d125cc0f1e9f134bc2ee9fb758b6e7669e3fa0126e1918",
     "feature/2026-06-14-acp-agent-client-protocol.md": "sha256:6828c0af74bb3fb96206ca6b21c0e56a000b50e4744aad4bc2c05092f3a5a31b",
     "feature/2026-06-14-acp-agent-client-protocol.zh.md": "sha256:ba104e841a1fb84edbd3b6c8119d50445b7785255a7a8d13bb9ac8a2cb4d2e69",
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
new file mode 100644
index 0000000000..754ca8bbd0
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.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-08-04-conversation-column-one-axis-scroll.md
+2026-08-04-conversation-column-one-axis-scroll.md: 9a487c506a75033d0854f08e95da24704309003d
+2026-08-04-conversation-column-one-axis-scroll.zh.md: 23441a7c8655d1f19d3c0fe0f661f81f69b55dba
diff --git a/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
similarity index 99%
rename from .agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
rename to .agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
index e8f80c23a2..9a487c506a 100644
--- a/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
@@ -1,7 +1,6 @@
 # Agent Note: The conversation column scrolls on one axis
 
 Status: implemented
-Archived: 2026-08-07
 
 English | [中文](2026-08-04-conversation-column-one-axis-scroll.zh.md)
 
diff --git a/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
similarity index 97%
rename from .agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
rename to .agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
index a7378b2d5e..23441a7c86 100644
--- a/.agents/notes/archived/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
@@ -1,7 +1,6 @@
-# Agent Note: 会话列只在一个轴上滚动
+# Agent Note：会话列只在一个轴上滚动
 
-Status: implemented
-Archived: 2026-08-07
+状态：已实现
 
 [English](2026-08-04-conversation-column-one-axis-scroll.md) | 中文
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index 661cd44ce6..ee99911ee8 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.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 .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
-2026-07-20-dsh-cli-personal-config.md: e3baa2dc5158893ddaf919b610e51a0b278b58eb
-2026-07-20-dsh-cli-personal-config.zh.md: 8417e0b27393fddeff5c75804c39deafdd1d83f8
+2026-07-20-dsh-cli-personal-config.md: 2a8ae4b235823b4493d2f082d37b85806f45b662
+2026-07-20-dsh-cli-personal-config.zh.md: d8ff6c4fcc5da8f1db6f030e990118e30ae6fe41
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
index e3baa2dc51..2a8ae4b235 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
@@ -41,7 +41,7 @@ The TUI and Web register the exact personal path through Cordis HMR after boot.
 ## Consequences
 
 - `dsh` from any directory (and `pnpm run demo:tui`) can apply personal providers, models, repository Plugins, and other Loader entries with no checkout edit; verified end-to-end against a personal Anthropic proxy with Opus 4.8, including a bash tool round trip.
-- Because an id-targeted patch replaces the whole `config`, a personal override restates the base fields it keeps and can drift when the base entry changes shape; the loader's entry-not-found/name-mismatch warnings and [`dsh --dump-config`](../simplification/2026-08-03-explicit-config-dsh-entrypoint.md) (which prints the composed tree those patches produce) are the diagnostics.
+- Because an id-targeted patch replaces the whole `config`, a personal override restates the base fields it keeps and can drift when the base entry changes shape; the loader's entry-not-found/name-mismatch warnings and [`dsh --dump-config`](../../../../apps/cli/README.md#profiles) (which prints the composed tree those patches produce) are the diagnostics.
 - Personal patches resolve ids against the booted file's own tree, so nested-include overlays (Code Mode) are not personalized; live-run parity for those leaves is deferred.
 - `dsh-app-boot` depends on `js-yaml` and imports the include's `!!js` YAML dialect (`entryListSchema`) directly, and, like `apps/cli`, depends on `@deepseek-ai/dsh-paths` for `resolveDshHome`.
 - Live watching belongs only to long-running TUI and Web processes. Headless automation gets deterministic startup configuration and exits without retaining a watcher.
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index 8417e0b273..d8ff6c4fcc 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -41,7 +41,7 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 ## Consequences
 
 - 在任意目录运行 `dsh`（以及 `pnpm run demo:tui`），无需修改 checkout，即可应用个人提供方、模型、仓库插件和其他 Loader 配置项；已针对个人 Anthropic 代理与 Opus 4.8 端到端验证，包括一次 bash 工具往返。
-- 由于按 id 定位的补丁替换整个 `config`，个人覆盖必须复述它保留的基础字段，并可能随基础配置项形态变化而漂移；诊断手段是 loader 的「配置项未找到/名称不匹配」警告和 [`dsh --dump-config`](../simplification/2026-08-03-explicit-config-dsh-entrypoint.md)（打印这些补丁合成出的配置树）。
+- 由于按 id 定位的补丁替换整个 `config`，个人覆盖必须复述它保留的基础字段，并可能随基础配置项形态变化而漂移；诊断手段是 loader 的「配置项未找到/名称不匹配」警告和 [`dsh --dump-config`](../../../../apps/cli/README.md#profiles)（打印这些补丁合成出的配置树）。
 - 个人补丁只在被启动文件自身的树里解析 id，因此嵌套 include 的 overlay（Code Mode）不会被个性化；这些叶子的实际运行等价性暂缓。
 - `dsh-app-boot` 依赖 `js-yaml`，并直接导入 include 的 `!!js` YAML 方言（`entryListSchema`）；与 `apps/cli` 一样依赖 `@deepseek-ai/dsh-paths` 以获取 `resolveDshHome`。
 - 只有长时间运行的 TUI 和 Web 进程进行实时监视。无头自动化使用确定性的启动配置，退出时不会保留 watcher。
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 32d6c6dcce..b6bf25d410 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
 README.md: 0cf50146cc44ef0d6cc060a4c97b3d1ff454f013
-README.zh.md: b0503ed2677f2ef30a51716b1735be1fa9eabe82
+README.zh.md: 8bfb96bb9326d8fcadc3c357b6abaad88c92bd17
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index b0503ed267..8bfb96bb93 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -14,7 +14,7 @@
 
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 
-已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。标题栏通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态、摘要或键控 toolview 分发（[历史披露决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
+已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。标题栏通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态、摘要或键控 toolview 分发（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 

From a8a12ffc232655d3c300d90eb0c7bd45695e6591 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 00:04:41 +0800
Subject: [PATCH 174/516] cleanup: replace FIXMEs with tracked issues

---
 ...21-mandatory-app-attribution-headers.i18n.yaml |  4 ++--
 ...026-06-21-mandatory-app-attribution-headers.md |  4 ++--
 ...-06-21-mandatory-app-attribution-headers.zh.md |  4 ++--
 .../2026-07-02-tool-render-intent-union.i18n.yaml |  4 ++--
 .../2026-07-02-tool-render-intent-union.md        |  2 +-
 .../2026-07-02-tool-render-intent-union.zh.md     |  2 +-
 ...ariables-and-tool-guidance-ownership.i18n.yaml |  4 ++--
 ...rompt-variables-and-tool-guidance-ownership.md |  2 +-
 ...pt-variables-and-tool-guidance-ownership.zh.md |  2 +-
 .../2026-07-05-reconstructable-requests.i18n.yaml |  4 ++--
 .../2026-07-05-reconstructable-requests.md        |  1 -
 .../2026-07-05-reconstructable-requests.zh.md     |  1 -
 ...026-06-18-compaction-capability-seam.i18n.yaml |  4 ++--
 .../2026-06-18-compaction-capability-seam.md      |  2 +-
 .../2026-06-18-compaction-capability-seam.zh.md   |  2 +-
 .../2026-08-02-pwsh-tool-bash-parity.i18n.yaml    |  4 ++--
 .../feature/2026-08-02-pwsh-tool-bash-parity.md   |  2 +-
 .../2026-08-02-pwsh-tool-bash-parity.zh.md        |  2 +-
 ...1-installer-adopts-existing-checkout.i18n.yaml |  4 ++--
 ...26-07-31-installer-adopts-existing-checkout.md |  2 +-
 ...07-31-installer-adopts-existing-checkout.zh.md |  2 +-
 .../2026-06-19-acp-snapshot-tests.i18n.yaml       |  4 ++--
 .../testing/2026-06-19-acp-snapshot-tests.md      |  2 +-
 .../testing/2026-06-19-acp-snapshot-tests.zh.md   |  2 +-
 .github/workflows/ci.yml                          |  3 ++-
 docs/core-data-structures/core.i18n.yaml          |  4 ++--
 docs/core-data-structures/core.md                 |  2 --
 docs/core-data-structures/core.zh.md              |  2 --
 docs/glossary.i18n.yaml                           |  4 ++--
 docs/glossary.md                                  |  2 --
 docs/glossary.zh.md                               |  2 --
 examples/acp-agent/tests/acp.snapshot.ts          |  4 ++--
 examples/headless-agent/tests/compaction.e2e.ts   |  4 ++--
 packages/client/runtime/src/client/slots.ts       | 15 +++++----------
 packages/cordis/tool-cordis/README.i18n.yaml      |  4 ++--
 packages/cordis/tool-cordis/README.md             |  2 +-
 packages/cordis/tool-cordis/README.zh.md          |  2 +-
 packages/cordis/tool-cordis/src/guard.ts          |  1 -
 packages/hooks/hooks-claude/tests/bridge.spec.ts  |  4 ++--
 packages/llm/llm/README.i18n.yaml                 |  4 ++--
 packages/llm/llm/README.md                        |  2 +-
 packages/llm/llm/README.zh.md                     |  2 +-
 packages/llm/llm/src/attribution.ts               |  4 ++--
 packages/sdk/telemetry/README.i18n.yaml           |  4 ++--
 packages/sdk/telemetry/README.md                  |  4 ++--
 packages/sdk/telemetry/README.zh.md               |  4 ++--
 packages/sdk/telemetry/src/reporter.ts            |  9 ++++-----
 scripts/install.sh                                |  2 --
 48 files changed, 69 insertions(+), 87 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index 56c9e53319..946d5a6117 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.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 .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
-2026-06-21-mandatory-app-attribution-headers.md: a8ffe91c431cdc7907626bbc3eaf8096035777de
-2026-06-21-mandatory-app-attribution-headers.zh.md: ac4affce583d5d81253f320ff022f670d4d66cc8
+2026-06-21-mandatory-app-attribution-headers.md: 28432008c354cbbb6e364746338627a26b464b0c
+2026-06-21-mandatory-app-attribution-headers.zh.md: 4fb3acd72aba4bebe751f57ac0f89f776d1f1f39
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
index a8ffe91c43..28432008c3 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
@@ -32,7 +32,7 @@ The provider-neutral identity is owned by `dsh-llm` (`packages/llm/llm/src/attri
 
 - product token for `User-Agent`: `deepseek-harness` (continuity with the pre-Agent Note wire value and the repo/org identity)
 - version: read from the owning package's manifest via `createRequire`, never a hand-copied constant
-- app URL: `https://github.com/deepseek-ai/deepseek-harness-sdk` - the planned public home; a `FIXME` in `attribution.ts` blocks release until that repository actually exists
+- app URL: `https://github.com/deepseek-ai/deepseek-harness-sdk` - the planned public home; [#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) tracks making it reachable before release
 
 The default is mandatory and non-empty. White-label deployments pass their own `AppIdentity` to `attributionHeaders(identity)` - the override seam is the function parameter, with no deployment config plumbing until a consumer needs it - and omission falls back to the harness default rather than suppressing attribution. There is no per-request API for the model, user prompt, session id, cwd, user email, API key owner, or local machine identity to influence these fields.
 
@@ -77,7 +77,7 @@ The landed contract:
 
 **Providers see that traffic comes from the harness.** That is the point, but it means deployments that previously blended into generic SDK traffic become identifiable. Mitigation: send only static public product data and let forks/white-label deployments pass their own `AppIdentity`.
 
-**The app URL points at a repository that does not exist yet.** `deepseek-ai/deepseek-harness-sdk` is the planned public home; until it is created the URL is a dangling promise. The `FIXME` marker on the constant blocks a release from shipping with it unresolved (see `docs/development.md` marker semantics).
+**The app URL points at a repository that does not exist yet.** `deepseek-ai/deepseek-harness-sdk` is the planned public home; until it is created the URL is a dangling promise. [#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) owns creating it or correcting the final URL before release.
 
 **Header support differs by client library.** The hand-rolled adapter sets headers directly; the pi-ai-backed adapter depends on pi-ai continuing to honor `StreamOptions.headers` (merged last over provider defaults). The wire-level mock-server tests are the guard: if a pi-ai upgrade stops delivering the header, the suite goes red. This is useful pressure on the abstraction: a provider adapter that cannot set mandatory headers cannot fully implement the harness LLM contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index ac4affce58..4fb3acd72a 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -32,7 +32,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 - `User-Agent` 的产品 token：`deepseek-harness`（与 Agent Note 之前的线路值及仓库/组织身份保持连续性）
 - 版本：通过 `createRequire` 从所属包的 manifest（元数据清单）读取，绝不手动复制常量
-- 应用 URL：`https://github.com/deepseek-ai/deepseek-harness-sdk`——计划中的公开主页；`attribution.ts` 中的 `FIXME` 标记在该仓库实际存在之前阻塞发布
+- 应用 URL：`https://github.com/deepseek-ai/deepseek-harness-sdk`——计划中的公开主页；[#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) 跟踪在发布前使其可访问
 
 默认值是强制的且非空。白标部署通过向 `attributionHeaders(identity)` 传入自己的 `AppIdentity` 来覆盖——覆盖 seam 就是函数参数，在有消费方需要之前不做部署配置管道——省略时回退到 harness 默认值而非抑制归属。没有逐请求 API 允许模型、用户提示词、会话 id、cwd、用户邮箱、API key 所有者或本地机器身份影响这些字段。
 
@@ -77,7 +77,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 **提供方看到流量来自 harness。** 这正是目的，但意味着此前混在通用 SDK 流量中的部署变得可识别。缓解措施：仅发送静态公开产品数据，并允许 fork/白标部署传入自己的 `AppIdentity`。
 
-**应用 URL 指向一个尚不存在的仓库。** `deepseek-ai/deepseek-harness-sdk` 是计划中的公开主页；在它创建之前，该 URL 是一个悬空承诺。常量上的 `FIXME` 标记阻塞发布，不允许带着未解决的问题出门（见 `docs/development.md` 标记语义）。
+**应用 URL 指向一个尚不存在的仓库。** `deepseek-ai/deepseek-harness-sdk` 是计划中的公开主页；在它创建之前，该 URL 是一个悬空承诺。[#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) 负责在发布前创建该仓库或校正最终 URL。
 
 **不同客户端库的头部支持有差异。** 手写适配器直接设置头部；基于 pi-ai 的适配器依赖 pi-ai 继续尊重 `StreamOptions.headers`（最后合并覆盖提供方默认值）。线路级 mock 服务器测试是守卫：如果 pi-ai 升级后不再投递该头部，套件会变红。这对抽象施加了有益的压力：一个无法设置强制头部的提供方适配器不能完整实现 harness 的 LLM 契约。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml
index 48d3522a70..072823d0dc 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.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 .agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md
-2026-07-02-tool-render-intent-union.md: d82141f519bff66df000f1316093aacd38b8e42b
-2026-07-02-tool-render-intent-union.zh.md: e145908e019e71765a475b0ca9d22414e9b42d23
+2026-07-02-tool-render-intent-union.md: 67607b2848305439513503d7e03ad5e2a2e4020a
+2026-07-02-tool-render-intent-union.zh.md: 9cbab75ce87f6d313ca4b6ac8dda043733361f0d
diff --git a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md
index d82141f519..67607b2848 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md
+++ b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md
@@ -14,7 +14,7 @@ A tool declares how its calls render in a UI (an editor's tool-call card) throug
 - Which combinations are *valid* is unwritten: a `terminal` call that also sets `content` means "description above the card"; a generic call that sets `terminal` is meaningless but representable. The type permits nonsense.
 - There is no way to express the one file-tool affordance an editor most wants — a **diff card** (`{path, oldText, newText}`, which Zed renders as an inline diff / new-file preview). `ToolCallPresentation.content` is the *LLM* `ContentBlock[]` vocabulary (text/image), so a tool literally cannot ask for a diff.
 
-The existing `FIXME(tool-presentation)` in `packages/core/tools/src/index.ts` named the fix: "redesign the type so a tool declares its render INTENT once (e.g. a tagged union over card kinds) rather than a bag of optional fields the bridge stitches together." An earlier rejected collapse-tool-owned-presentation proposal deferred it explicitly: rich rendering "should return later as a tagged render-intent union after there are at least two real tools and two real consumers to validate the vocabulary." That bar is met by multiple producer families plus the TUI and host/client-runtime (Web) consumers.
+An earlier rejected collapse-tool-owned-presentation proposal deferred rich rendering until it could "return later as a tagged render-intent union after there are at least two real tools and two real consumers to validate the vocabulary." That bar is met by multiple producer families plus the TUI and host/client-runtime (Web) consumers.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md
index e145908e01..9cbab75ce8 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 - 哪些组合是*合法的*没有文档说明：一个设置了 `content` 的 `terminal` 调用意味着「卡片上方的描述」；一个设置了 `terminal` 的 generic 调用毫无意义但类型上可表达。类型允许无意义的状态存在。
 - 无法表达编辑器最需要的文件工具能力：**diff 卡片**（`{path, oldText, newText}`，Zed 将其渲染为内联 diff / 新文件预览）。`ToolCallPresentation.content` 使用的是 *LLM（大语言模型）* 的 `ContentBlock[]` 词汇（text/image），工具根本无法请求 diff 展示。
 
-`packages/core/tools/src/index.ts` 中已有的 `FIXME(tool-presentation)` 指出了修复方向：「重新设计类型，让工具一次性声明其渲染意图（例如按卡片种类的带标签联合类型），而非一堆由 bridge 拼接的可选字段。」一个早先被否决的折叠工具自有呈现提案明确推迟了此事：富渲染「应当在至少有两个真实工具和两个真实消费方验证词汇之后，以带标签 render-intent 联合类型的形式回归。」该条件已由多个生产者族，加上 TUI 与宿主/客户端运行时（Web）这些消费方满足。
+一个早先被否决的折叠工具自有呈现提案把富渲染推迟到它能够「在至少有两个真实工具和两个真实消费方验证词汇之后，以带标签 render-intent 联合类型的形式回归」之时。该条件已由多个生产者族，加上 TUI 与宿主/客户端运行时（Web）这些消费方满足。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
index 8a2190b500..26354042d7 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.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 .agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
-2026-07-05-prompt-variables-and-tool-guidance-ownership.md: 94f5fa409e7b539b48750d12576c7a342a30c9ba
-2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 341b3a89f423c9cc7d2fc56f1ea25a1985680d0d
+2026-07-05-prompt-variables-and-tool-guidance-ownership.md: a3b5021daf323971308760bde4f97651db8edbda
+2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 490d41302ea4f4e14e11e301acbf47170f95cace
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
index 94f5fa409e..a3b5021daf 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
@@ -10,7 +10,7 @@ The assembled system prompt had four defects, all of one family: facts the harne
 
 **The model could not know its own name.** `AgentOptions.model` drives every request, but no prompt text carried it — and nothing COULD carry it: sections in `dsh-system-prompt` were context-global while the model name is per-agent, and `assemble()` took no per-agent input at all.
 
-**Tool guidance was hand-written prose in leaf YAML.** The bash/subagent/todo_write usage guidance lived in the coding-agent and ACP persona strings — two drifting copies (the ACP one was already abridged) — while `dsh-tool-fs` and `dsh-tool-web` owned their guidance as `ctx.systemPrompt.section()` contributions. Loading or dropping a tool plugin meant editing every deployment's persona by hand; both YAMLs carried a `FIXME(config-comments)` apologizing for a symptom of the split, and the old terminal welcome banner hand-enumerated the tool set too.
+**Tool guidance was hand-written prose in leaf YAML.** The bash/subagent/todo_write usage guidance lived in the coding-agent and ACP persona strings — two drifting copies (the ACP one was already abridged) — while `dsh-tool-fs` and `dsh-tool-web` owned their guidance as `ctx.systemPrompt.section()` contributions. Loading or dropping a tool plugin meant editing every deployment's persona by hand, and the old terminal welcome banner hand-enumerated the tool set too.
 
 **The persona rendered after tool guidance.** The loop string-joined `agent.options.systemPrompt` AFTER the assembled sections, so the model read "Use the read tool…" before "You are a coding agent" — backwards relative to the identity-first convention (Claude Code, Codex) and a second composition path besides the section pipeline.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
index 341b3a89f4..490d41302e 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 **模型无法知道自己的名字。** `AgentOptions.model` 驱动每个请求，但没有任何提示词文本携带它——也不可能携带：`dsh-system-prompt` 中的 section 是上下文全局的，而模型名称是 per-agent 的，`assemble()` 根本不接受任何 per-agent 输入。
 
-**工具指导是 leaf YAML 中的手写行文。** bash/subagent/todo_write 的使用指导存放在 coding-agent 和 ACP persona 字符串里——两份漂移的副本（ACP 那份已经被删减）——而 `dsh-tool-fs` 和 `dsh-tool-web` 则通过 `ctx.systemPrompt.section()` 贡献各自的指导。加载或卸载一个工具插件意味着手动编辑每个部署的 persona；两份 YAML 都带着一条 `FIXME(config-comments)` 为这种分裂的症状道歉，旧终端欢迎横幅也手动枚举了工具集。
+**工具指导是 leaf YAML 中的手写行文。** bash/subagent/todo_write 的使用指导存放在 coding-agent 和 ACP persona 字符串里——两份漂移的副本（ACP 那份已经被删减）——而 `dsh-tool-fs` 和 `dsh-tool-web` 则通过 `ctx.systemPrompt.section()` 贡献各自的指导。加载或卸载一个工具插件意味着手动编辑每个部署的 persona，旧终端欢迎横幅也手动枚举了工具集。
 
 **Persona 渲染在工具指导之后。** agent loop（智能体循环）将 `agent.options.systemPrompt` 字符串拼接在已组装的 section 之后，于是模型先读到「Use the read tool…」再读到「You are a coding agent」——与 identity-first 约定（Claude Code、Codex）相反，且是 section 流水线之外的第二条组合路径。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
index d326b413bb..2926746ee1 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.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 .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
-2026-07-05-reconstructable-requests.md: 2f559a3052b9fb84f788975a64799e4f020b0d3e
-2026-07-05-reconstructable-requests.zh.md: 26abdc024a166856e51ebf09f086c7868fc8236d
+2026-07-05-reconstructable-requests.md: ebca9b99cad791159302da9c2bbce9f4df147aab
+2026-07-05-reconstructable-requests.zh.md: 91ef3fd04502f2c2f092da60a8bd909cf7fa25df
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
index 2f559a3052..ebca9b99ca 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
@@ -53,4 +53,3 @@ Like MiniCode, the conversation advances append-only and resets only when model-
 - Tool-result trimming (planned) needs no new mechanism: a logged single-entry surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic.
 - Session logs grow one `request/header` snapshot per loop instance plus snapshots on real changes. This is larger than a delta codec but small beside chunk-heavy logs and retains one replay representation. `SESSION_FORMAT_VERSION` stays `0`; legacy delta events are rejected rather than migrated.
 - Snapshot expected outputs changed once (every transcript gains its header events); the fs-writing fixtures are stored in the normalized authored form with cwd-relative tool arguments, because replay only round-trips cwd-independent argument paths.
-- FIXME(call-config-shape): revisit `LlmCallConfig`'s exact field set — which fields are genuinely epoch-level for cache purposes (`model` certainly; the sampling scalars sit there out of caution), and where provider-specific extras (reasoning options, extra body params) belong when an adapter needs them.
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
index 26abdc024a..91ef3fd045 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
@@ -53,4 +53,3 @@ Status: implemented
 - 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存击穿由相同的压力逻辑批量处理。
 - 会话日志每个循环实例增长一个 `request/header` 快照，并在真正变更时增加快照。它比 delta 编解码器更大，但相对分片密集型日志仍然很小，并只保留一种回放表示。`SESSION_FORMAT_VERSION` 保持 `0`；旧的 delta 事件被拒绝而非迁移。
 - 快照预期输出变更一次（每个 transcript（文本记录）增加其 header 事件）；写入文件系统的 fixture（测试前置数据）以规范化的撰写形式存储，工具参数使用 cwd 相对路径，因为回放只对 cwd 无关的参数路径做往返。
-- FIXME(call-config-shape)：重新审视 `LlmCallConfig` 的确切字段集——哪些字段对缓存而言真正属于 epoch 级别（`model` 毫无疑问；采样标量出于谨慎放在那里），以及当适配器需要时，提供方特定的额外项（推理（reasoning）选项、额外 body 参数）应归属何处。
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index c981d84400..f071577bdd 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.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 .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: 26e6e2468c7bea661d85c8fb994adf8b109105ee
-2026-06-18-compaction-capability-seam.zh.md: 8f9cd1f6bc31e648a5b923e816cad75ebc1a0bd8
+2026-06-18-compaction-capability-seam.md: efb37482270a7952f6af6596f9afd12f17048bcc
+2026-06-18-compaction-capability-seam.zh.md: 214832923c4e24835e7b25a5bbf2b1bcd62dff42
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index 26e6e2468c..efb3748227 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
@@ -131,4 +131,4 @@ The lifecycle boundary makes crash state unambiguous:
 - **Loop:** Tests pin pre-step after the preceding `step/end` and before the next `step/start`, actual `agent/request` routing, closed failed steps, fresh retry numbering, and complete thrown/in-band overflow → compaction → reconstructed retry composition.
 - **Manual:** Maintenance serialization, marker ordering, injection retention, live/stale orphan classification, cancellation, close/flush failures, command mapping, and the queued TUI journey are pinned without a model key.
 - **With-key e2e:** A real model and bash session with lowered limits triggers compaction, records a complete `compact/start…end` pair, shrinks the surface, and finishes the task.
-- **Snapshot gap:** Runaway-turn compaction cannot yet replay because the summarization call records no `assistant/chunk` events or `sessionId`; interleaved summarization-call replay remains follow-up work.
+- **Snapshot gap:** The summarization call is session-associated and logs `compact/summary`, but ordinary transcript replay does not derive its auxiliary response. [#1971](https://github.com/deepseek-harness/deepseek-harness/issues/1971) tracks a keyless assembled scenario with an explicit replay override.
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index 8f9cd1f6bc..214832923c 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -131,4 +131,4 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 - **循环测试：** 测试固定 pre-step 发生在前一个 `step/end` 之后、下一个 `step/start` 之前，使用实际 `agent/request` 路由，关闭失败步骤，分配新的重试编号，并覆盖完整的抛出/带内溢出 → 压缩 → 重建重试组合。
 - **手动测试：** 无需模型密钥即可固定 maintenance 串行化、标记顺序、注入保留、活动／陈旧未匹配标记分类、取消、闭合／flush 失败、命令映射以及排队 TUI 流程。
 - **带密钥 e2e：** 真实模型和 bash 会话在降低的限制下触发压缩，记录完整的 `compact/start…end` 对，缩小 surface，并完成任务。
-- **快照缺口：** 失控轮次压缩尚无法回放，因为摘要调用未记录 `assistant/chunk` 事件或 `sessionId`；交错摘要调用的回放仍是后续工作。
+- **快照缺口：** 摘要调用与会话关联并记录 `compact/summary`，但普通 transcript（文本记录）回放不会派生其辅助响应。[#1971](https://github.com/deepseek-harness/deepseek-harness/issues/1971) 跟踪一个带显式回放 override 的无密钥组装场景。
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
index eea7ced3d2..40e24e9ac2 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.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 .agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
-2026-08-02-pwsh-tool-bash-parity.md: 945d2d5243162fe8e7fb3f76cbc3bcf0b5c2fdee
-2026-08-02-pwsh-tool-bash-parity.zh.md: f537e313a0c895927c6e2319b11b98619a70d461
+2026-08-02-pwsh-tool-bash-parity.md: e35a903892d5d50a0d3ca12b23daa53f26d6aade
+2026-08-02-pwsh-tool-bash-parity.zh.md: d7a68f0cab5281b25c3321e7ffff61c358b21a0a
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
index 945d2d5243..e35a903892 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
@@ -14,7 +14,7 @@ The first Windows-native foundation shipped `dsh-tool-pwsh` as a deliberately mi
 
 - **Rendering adopts the bash story verbatim**: stdout, a marked `[stderr]` section, truncation notices with spill paths, `(no output)` for an empty body, and exit markers only for non-zero exits — a clean exit produces no marker. The description and the `tool:pwsh` prompt section state this precisely ("Non-zero exits are reported as `[exit code: N]` markers"), deliberately not copying the bash prompt's "every result" phrasing, which its own renderer contradicts.
 - **`run_in_background` is wired through the generic task runtime** exactly like the bash tool: preflight, owner registration, `task_output`/`task_kill` control, and the same outcome mapping. `pwsh-local`'s already-mirrored `start()` handle backs it.
-- **The `DSH_*` environment is shared, not duplicated**: `BashEnvRegistry` moved out of `dsh-tool-bash` into a new tool-independent `@deepseek-ai/dsh-bash-env` package (`ctx.bashEnv` + built-ins + the session-persistence contributor), and both shell tools inject it. Contributors apply to pwsh calls exactly as they do to bash calls, resolving the bash tool's `FIXME(bash-env-ownership)`.
+- **The `DSH_*` environment is shared, not duplicated**: `BashEnvRegistry` moved out of `dsh-tool-bash` into a new tool-independent `@deepseek-ai/dsh-bash-env` package (`ctx.bashEnv` + built-ins + the session-persistence contributor), and both shell tools inject it. Contributors apply to pwsh calls exactly as they do to bash calls; shared environment ownership therefore sits outside either model-facing shell tool.
 - **Windows reality is pinned where bash has no analog**: every command runs under a UTF-8 output preamble so the Windows PowerShell 5.1 fallback cannot garble non-ASCII output through the UTF-8-decoding collector, and the prompts teach that Windows forced termination settles as exit 1 without a signal marker.
 - **Out of scope, unchanged**: sandbox escalation (waits for a Windows-confining executor) and persistent PTY shells (backends are Linux/macOS-only; ConPTY is roadmap work). The pwsh-specific terminal card with an exit pill shipped separately in the [pwsh UI presentation matches bash](2026-08-05-pwsh-ui-bash-parity.md) decision.
 
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
index f537e313a0..d7a68f0cab 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 - **渲染完全采用 bash 故事**：stdout、带标记的 `[stderr]` 段、带 spill 路径的截断通知、空体渲染 `(no output)`、退出 marker 仅限非零退出——干净退出不产生 marker。描述与 `tool:pwsh` prompt section 精确陈述这一点（"Non-zero exits are reported as `[exit code: N]` markers"），刻意不复制 bash prompt 中与其自身渲染矛盾的 "every result" 措辞。
 - **`run_in_background` 经通用任务运行时接线**，与 bash 工具完全一致：预检、owner 注册、`task_output`/`task_kill` 控制与相同的结果映射。其背后是 `pwsh-local` 早已镜像好的 `start()` 句柄。
-- **`DSH_*` 环境共享而非复制**：`BashEnvRegistry` 从 `dsh-tool-bash` 迁入新的工具无关包 `@deepseek-ai/dsh-bash-env`（`ctx.bashEnv` + 内置事实 + session-persistence contributor），两个 shell 工具都注入它。contributor 对 pwsh 调用与 bash 调用一视同仁，并消化了 bash 工具的 `FIXME(bash-env-ownership)`。
+- **`DSH_*` 环境共享而非复制**：`BashEnvRegistry` 从 `dsh-tool-bash` 迁入新的工具无关包 `@deepseek-ai/dsh-bash-env`（`ctx.bashEnv` + 内置事实 + session-persistence contributor），两个 shell 工具都注入它。contributor 对 pwsh 调用与 bash 调用一视同仁；因此，共享环境的所有权不属于任何一个面向模型的 shell 工具。
 - **Windows 现实在 bash 无对应处钉死**：每条命令都在 UTF-8 输出 preamble 下运行，使 Windows PowerShell 5.1 兜底无法经 UTF-8 解码的 collector 破坏非 ASCII 输出；prompt 教授 Windows 强制终止以无 signal 的 exit 1 结算。
 - **范围外，不变**：sandbox 升级（等待 Windows-confining 执行器）与持久 PTY shell（后端仅限 Linux/macOS；ConPTY 属路线图）。带退出 pill 的 pwsh 专属 terminal 卡已随 [pwsh UI 呈现与 bash 对齐](2026-08-05-pwsh-ui-bash-parity.md) 决策另行交付。
 
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
index 1a179748f9..79ea52067d 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.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 .agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
-2026-07-31-installer-adopts-existing-checkout.md: de3cd052f94a0d5256c7687e9a1a38ee69fd2caf
-2026-07-31-installer-adopts-existing-checkout.zh.md: 2e8be804b4af6151e77e36f8b109616aab3a18e9
+2026-07-31-installer-adopts-existing-checkout.md: ff02fe837f2ad4deb3fb852f610f3cd3ff9a23d7
+2026-07-31-installer-adopts-existing-checkout.zh.md: 28816c80764acc0d4a2fcd13b3b8a38807021fd6
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
index de3cd052f9..ff02fe837f 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
@@ -46,6 +46,6 @@ A container adopting an outside clone is also no longer self-contained: deleting
 
 ## Testing
 
-`scripts/install.sh` has no automated test, and this change does not add one: the user directed that `install.spec.ts` be left out of scope. That is a known gap on a shipped user-facing path, and the `/var` resolution defect above is exactly the class of bug a test would have caught first. The standing [`FIXME(install-ts)`](../../../../scripts/install.sh) asking for this workflow to move into a tested TypeScript entrypoint is correspondingly more pressing.
+`scripts/install.sh` now has a real-shell PTY regression suite in `apps/cli/tests/install-script.spec.ts`, covering adoption and curl-style paths with stubbed dependencies. The installer's longer-term deletion in favor of pnpm/npx is tracked in [#1890](https://github.com/deepseek-harness/deepseek-harness/issues/1890).
 
 Verification was manual, through a throwaway harness driving the real script with a stubbed `pnpm`: adopting a standalone clone; adopting from a linked worktree into its existing container; an explicit `DSH_SOURCE` still opting back into cloning; a dirty tree adopting silently with no prompt or warning while its uncommitted file stays behind; a non-git checkout failing with guidance; and a `curl`-style clone install asserting the built layout, which is the regression that caught the unresolved-`REPO_ROOT` defect. The interactive path was exercised under tmux from a dirty checkout, confirming the run reaches the launcher with no adoption prompt and ends with `dsh` running from the new staging worktree while the original checkout keeps its branch and its uncommitted file.
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
index 2e8be804b4..28816c8076 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
@@ -46,6 +46,6 @@ Status: implemented
 
 ## Testing
 
-`scripts/install.sh`没有自动化测试，本次变更也未添加：用户明确要求把`install.spec.ts`排除在范围之外。这是一条已交付的、面向用户的安装路径上的已知缺口，而上文那个`/var`解析缺陷，恰恰属于测试本应最先捕获的那类 bug。相应地，要求把这套流程迁移到有测试覆盖的 TypeScript 入口的既有[`FIXME(install-ts)`](../../../../scripts/install.sh)也变得更为紧迫。
+`scripts/install.sh` 现有一套位于 `apps/cli/tests/install-script.spec.ts` 的真实 shell PTY 回归测试，使用 stub 依赖覆盖接管路径和 curl 风格路径。[#1890](https://github.com/deepseek-harness/deepseek-harness/issues/1890) 跟踪安装器的长期删除工作，届时将改用 pnpm/npx。
 
 验证是手工完成的，通过一个一次性测试装置以打桩的`pnpm`驱动真实脚本：接管独立克隆；从 linked worktree 接管进其已有容器；显式`DSH_SOURCE`仍回到克隆路径；工作树不干净时静默接管、既不提示也不警告，且其未提交文件留在原处；非 git 检出失败并给出指引；以及`curl`式克隆安装断言所构建的布局——正是这项回归测试捕获了`REPO_ROOT`未解析的缺陷。交互路径在 tmux 下从一个不干净的检出走通，确认整个过程不出现接管提示即可到达启动器，最终`dsh`从新的 staging worktree 运行，而原检出保持其分支不变、未提交文件仍在。
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
index fe97a7b717..b7d396e007 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.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 .agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
-2026-06-19-acp-snapshot-tests.md: e118ada58230fe31fbb2a6bffb83e5612757ab1f
-2026-06-19-acp-snapshot-tests.zh.md: e292dbf3bf3c4c5198dc77d122bb6b8c36014ebf
+2026-06-19-acp-snapshot-tests.md: 39d3b7a3f4699ea96262f43c63a7d60574ba064f
+2026-06-19-acp-snapshot-tests.zh.md: 7dd3a3fa83682c35945314c7cd9531ca72bbb1fb
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
index e118ada582..39d3b7a3f4 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
@@ -80,6 +80,6 @@ Tool determinism comes from a generated cwd, scrubbed environment, fresh non-log
 
 ## Consequences
 
-The tier adds reviewed per-scenario input, session, stdout, optional override, and optional workspace fixtures, plus one file for each distinct pinned prompt and tool-schema sequence. Workspace seeds are copied into the generated cwd for both record and replay. In return the tier provides deterministic keyless coverage through the real Loader and tool composition. Most retained scenarios exercise the assembled backend rather than ACP; the [automation-only ACP decision](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary) keeps that corpus here and defers any move to a transport-neutral headless suite as an independent testing change (the suite-level FIXME marks it).
+The tier adds reviewed per-scenario input, session, stdout, optional override, and optional workspace fixtures, plus one file for each distinct pinned prompt and tool-schema sequence. Workspace seeds are copied into the generated cwd for both record and replay. In return the tier provides deterministic keyless coverage through the real Loader and tool composition. Most retained scenarios exercise the assembled backend rather than ACP; the [automation-only ACP decision](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary) keeps that corpus here, while [#1970](https://github.com/deepseek-harness/deepseek-harness/issues/1970) tracks moving it to a transport-neutral headless suite without losing coverage.
 
 This Agent Note relates to but does not supersede the [proposed determinism Agent Note](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.md): that proposal's "universal replay fixture" re-derives session *message history* after every test (an internal-consistency invariant), whereas these snapshots pin assembled behavior plus the external automation output. They are complementary until the backend corpus moves off ACP.
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
index e292dbf3bf..7dd3a3fa83 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
@@ -80,6 +80,6 @@ Status: implemented
 
 ## 后果
 
-该测试层为每个场景增加经过评审的输入、会话、stdout、可选 override 和可选 workspace fixture，并为每个不同的已固定提示词序列、每个不同的已固定工具 schema 序列各增加一个文件。记录与回放都会把 workspace seed 复制到生成的 cwd。作为回报，该层通过真实 Loader 和工具组合提供确定性的无密钥覆盖。保留下来的大多数场景测试的是组装后的后端而非 ACP；[仅面向自动化的 ACP 决策](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary)将该语料保留在此处，并把向传输无关 headless 套件的任何迁移推迟为一项独立的测试变更（套件级 FIXME 标记了这一点）。
+该测试层为每个场景增加经过评审的输入、会话、stdout、可选 override 和可选 workspace fixture，并为每个不同的已固定提示词序列、每个不同的已固定工具 schema 序列各增加一个文件。记录与回放都会把 workspace seed 复制到生成的 cwd。作为回报，该层通过真实 Loader 和工具组合提供确定性的无密钥覆盖。保留下来的大多数场景测试的是组装后的后端而非 ACP；[仅面向自动化的 ACP 决策](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary)将该语料保留在此处，而 [#1970](https://github.com/deepseek-harness/deepseek-harness/issues/1970) 跟踪在不损失覆盖的情况下将其迁移到传输无关的 headless 套件。
 
 本 Agent Note 与[拟议的确定性 Agent Note](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.md)相关，但不取代它：该提案的“通用回放 fixture”在每次测试后重新派生会话*消息历史*（内部一致性不变量），而这些快照固定组装后的行为与外部自动化输出。在后端语料迁出 ACP 之前，两者相互补充。
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 821948f873..66b3a5399e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -30,7 +30,8 @@ env:
 
 jobs:
 
-  # FIXME: Re-enable the three hosted serial reference jobs before cutting a release.
+  # https://github.com/deepseek-harness/deepseek-harness/issues/1967 tracks
+  # restoring the three hosted serial reference jobs before release.
   # The self-hosted standby remains active on every master push.
 
   # Three enterprise jobs isolate coverage, static analysis, and the
diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml
index 461d1ef4fc..e79d5dac2f 100644
--- a/docs/core-data-structures/core.i18n.yaml
+++ b/docs/core-data-structures/core.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 docs/core-data-structures/core.md
-core.md: f7cf288715a3aec2f7037f12fc983e3172a77cef
-core.zh.md: c17fd1335503c95e7f7f6f96cc286f567a8384e6
+core.md: dbd584f10b3daf873bc14210472efb6cd315717e
+core.zh.md: 1fe1616a0c96abb4e8b91417cc4eae292416e42a
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index f7cf288715..dbd584f10b 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -530,8 +530,6 @@ The loop builds each request from logged state. `EpochHeader` records call confi
 
 On the wire, a loop-built request reads the `system` slot (the rendered prompt assembly) followed by the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps. The dev invariant recomputes exactly this equation against every loop-built request.
 
-FIXME(call-config-shape): revisit which remaining fields are genuinely epoch-level for cache purposes (`model` and the model-owned reasoning effort are explicit; the sampling scalars sit here out of caution).
-
 ```ts type-equiv
 /**
  * Provider, model, reasoning effort, and sampling scalars of one conversation's
diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md
index c17fd13355..1fe1616a0c 100644
--- a/docs/core-data-structures/core.zh.md
+++ b/docs/core-data-structures/core.zh.md
@@ -536,8 +536,6 @@ interface ToolSchema {
 
 在协议格式上，循环构建的请求先读取 `system` 槽位（渲染后的提示词组装），再读取派生历史——边界快照，其尾部在轮次首步是最新的 `user/message`，在后续步骤是上一步的工具结果。开发不变式针对每个循环构建的请求精确重算此等式。
 
-FIXME(call-config-shape)：重新审视其余哪些字段出于缓存目的确实属于 epoch 层级（`model` 和模型持有的推理强度已明确属于；采样标量目前出于谨慎保留在此）。
-
 ```ts type-equiv
 /**
  * Provider, model, reasoning effort, and sampling scalars of one conversation's
diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml
index 5c6f7d4630..2dfe08c2fd 100644
--- a/docs/glossary.i18n.yaml
+++ b/docs/glossary.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 docs/glossary.md
-glossary.md: 0270a2d0dba558483e8e458a932a27b0151f2c93
-glossary.zh.md: c3584731cc08b23cf7f47c09620a77b7bff65689
+glossary.md: 16409517bff623a80d6e1e00888d95f63b42f780
+glossary.zh.md: fe3138ac81f2681d7fc69cc2aede96edeb7ec176
diff --git a/docs/glossary.md b/docs/glossary.md
index 0270a2d0db..16409517bf 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -4,8 +4,6 @@ English | [中文](glossary.zh.md)
 
 Domain vocabulary for the DeepSeek Harness SDK uses one canonical term per concept. Terms link to their entries with standard Markdown anchors; implementation detail stays in package READMEs and Agent Notes.
 
-FIXME(glossary-completeness): Expand this glossary before the first release so it covers the SDK's other core and capability subsystems, not only agent scope.
-
 ## agent-scope
 
 - **scope** — the unit of per-agent registration: a contribution (tool, prompt section, variable, restriction, listener) is either *global* (visible to every agent) or *scoped* (owned by exactly one [scope key](#scope-key)). Two levels, flat: scoped registrations do not inherit down to subagents; subtree behavior is expressed with [lineage](#lineage) data, never scope structure.
diff --git a/docs/glossary.zh.md b/docs/glossary.zh.md
index c3584731cc..fe3138ac81 100644
--- a/docs/glossary.zh.md
+++ b/docs/glossary.zh.md
@@ -4,8 +4,6 @@
 
 DeepSeek Harness SDK 的领域词汇为每个概念规定一个规范术语。各术语通过标准 Markdown 锚点链接到相应条目；实现细节留在各包的 README 与 Agent Note 中。
 
-FIXME(glossary-completeness): 首次发布前扩充本术语表，使其覆盖 SDK 的其他核心与能力子系统，而非仅限于 agent scope。
-
 ## agent-scope
 
 - **scope**：按 agent（智能体）划分的注册单位。一项贡献（工具、提示词片段、变量、限制、监听器）要么是*全局的*（对所有 agent 可见），要么是*带作用域的*（归属于恰好一个 [scope key](#scope-key)）。只有两层，采用扁平结构：带作用域的注册不会向下继承给 subagent；子树行为通过 [lineage](#lineage) 数据表达，从不通过 scope 结构。
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index bf4f7ac972..b2fd25eb4e 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -90,8 +90,8 @@ async function prepareFsSearchWorkspace(cwd: string): Promise<void> {
   }
 }
 
-// FIXME: Migrate backend-oriented scenarios to the headless stream-json suite;
-// this ACP suite should eventually retain only automation-protocol contracts.
+// https://github.com/deepseek-harness/deepseek-harness/issues/1970 tracks moving
+// backend/product scenarios to headless while retaining ACP protocol contracts here.
 
 function fixtureRecords(name: string): unknown[] {
   return readFileSync(join(SNAPSHOTS_DIR, name, 'session.jsonl'), 'utf8')
diff --git a/examples/headless-agent/tests/compaction.e2e.ts b/examples/headless-agent/tests/compaction.e2e.ts
index 07f239a73e..fdae11d2c7 100644
--- a/examples/headless-agent/tests/compaction.e2e.ts
+++ b/examples/headless-agent/tests/compaction.e2e.ts
@@ -10,9 +10,9 @@ import { SessionId } from '@deepseek-ai/dsh-session'
 /**
  * Key-gated smoke for mid-session compaction. It verifies the compact event
  * pair, replacement of older surface nodes, and a final answer after compaction.
+ * A keyless assembled snapshot with an explicit summarization replay override
+ * is tracked in https://github.com/deepseek-harness/deepseek-harness/issues/1971.
  */
-// FIXME(compaction-snapshot): this is the only full compaction coverage because
-// replay cannot serve the summarizer's unlogged model call.
 
 let workdir: string | undefined
 let ctx: Context | undefined
diff --git a/packages/client/runtime/src/client/slots.ts b/packages/client/runtime/src/client/slots.ts
index 3698f62aab..9da8755b2d 100644
--- a/packages/client/runtime/src/client/slots.ts
+++ b/packages/client/runtime/src/client/slots.ts
@@ -19,7 +19,7 @@ import type { Context } from 'cordis'
 import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
 import type {
   LocaleFace, OwnerOf, SlotEntryDef, SlotMap, SlotRenderer, SlotRendererHost,
-  SlotScope, SlotSpec, StoreDecl, StoredEntry, StoreInstanceLike,
+  SlotScope, SlotSpec, StoreDecl, StoreFactory, StoredEntry, StoreInstanceLike,
 } from '@deepseek-ai/dsh-client-ui-slots'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
@@ -35,16 +35,11 @@ export interface RootOwnerProps { children?: never }
 /** Instance key for root-scoped store records (session records key by session id, so the literal cannot collide). */
 const ROOT_INSTANCE_KEY = 'root'
 
-// FIXME(slot-parity): the engine's arbitrated persist extensions — create()
-// takes the scope key (per-session localStorage suffix) and instances expose
-// clearPersisted() — are not yet on ui-slots' StoreHandle/StoreInstanceLike;
-// these local structural faces bridge until fw-slots lifts them.
+/** Canonical type-erased store handle used by the runtime lifecycle map. */
+type EngineStoreHandle = Exclude<StoreDecl, StoreFactory>
 
-/** Store handle face as the engine actually ships it (scope-key-aware create). */
-interface EngineStoreHandle { create(scopeKey?: string): EngineStoreInstance }
-
-/** Engine instance face: the host-contract shape plus persisted-state cleanup. */
-interface EngineStoreInstance extends StoreInstanceLike { clearPersisted(): void }
+/** Canonical engine instance derived from the handle's create contract. */
+type EngineStoreInstance = ReturnType<EngineStoreHandle['create']>
 
 /** Store axis record: one per live handle, dropped when the last holding entry unloads. */
 interface StoreAxisRecord {
diff --git a/packages/cordis/tool-cordis/README.i18n.yaml b/packages/cordis/tool-cordis/README.i18n.yaml
index 0a55bfc7f6..fd2b5443ef 100644
--- a/packages/cordis/tool-cordis/README.i18n.yaml
+++ b/packages/cordis/tool-cordis/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/cordis/tool-cordis/README.md
-README.md: eda135d93e2912bbb4e111af40d176409b383b5b
-README.zh.md: 773d4100f1be6c54f491838b65205b85ec61cdbc
+README.md: 9986310160c2b56126155a4c3ef84d66018d31c2
+README.zh.md: d955306e1e5d4154f58c771704782ece44a15c99
diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md
index eda135d93e..9986310160 100644
--- a/packages/cordis/tool-cordis/README.md
+++ b/packages/cordis/tool-cordis/README.md
@@ -85,5 +85,5 @@ Mounting or unmounting a prompt or tool contribution changes later request prefi
 ## Known Limitations and Deferred Work
 
 - **The sandbox is containment for honest code, not a security boundary** — host-realm helpers on the sandbox global are reachable, so mount code can reach Node; load this plugin as deliberately as you would grant a bash tool (see § Trust stance).
-- **The `ctx` façade exposes no `effect()`** — mount code cannot register a bespoke disposer; `on`/`provide`/`tools.register` cover every mount seen so far, and a guarded `effect` waits on a real need (`FIXME(sandbox-effect)`).
+- **The `ctx` façade exposes no `effect()`** — mount code cannot register a bespoke disposer; `on`/`provide`/`tools.register` are the supported cleanup paths.
 - **`vmTimeoutMs` bounds only synchronous evaluation** — an async mount body escapes it; there is no async budget on mount code.
diff --git a/packages/cordis/tool-cordis/README.zh.md b/packages/cordis/tool-cordis/README.zh.md
index 773d4100f1..d955306e1e 100644
--- a/packages/cordis/tool-cordis/README.zh.md
+++ b/packages/cordis/tool-cordis/README.zh.md
@@ -85,5 +85,5 @@ Namespace 插件：命名导出 `name`／`inject`／`Config`／`apply`，无默
 ## 已知限制与暂缓事项
 
 - **沙箱只用于约束诚实代码，并非安全边界**：可以访问沙箱全局变量上的 host realm helper，因此挂载代码可以触达 Node；加载该插件时，应当像授予 bash 工具一样慎重（见 § 信任立场）。
-- **`ctx` façade 不公开 `effect()`**：挂载代码无法注册定制 disposer；`on`／`provide`／`tools.register` 已覆盖目前出现的每项挂载，受保护的 `effect` 会等待真实需求（`FIXME(sandbox-effect)`）。
+- **`ctx` façade 不公开 `effect()`**：挂载代码无法注册定制 disposer；`on`／`provide`／`tools.register` 是受支持的清理路径。
 - **`vmTimeoutMs` 只限制同步求值**：async 挂载主体可逃出该边界；挂载代码没有 async 预算。
diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts
index 595dc462e0..22d85936f4 100644
--- a/packages/cordis/tool-cordis/src/guard.ts
+++ b/packages/cordis/tool-cordis/src/guard.ts
@@ -749,7 +749,6 @@ export function isPlugin(value: unknown): value is Plugin {
  * @param plugin - the plugin the mount code returned.
  * @returns an equivalent plugin whose `apply` sees the sandbox context façade.
  */
-// FIXME(sandbox-effect): expose guarded custom effects when a mount needs bespoke cleanup.
 export function guardedPlugin(plugin: Plugin): Plugin {
   if (typeof plugin === 'function') {
     const functionPlugin = plugin as (ctx: Context, config?: unknown) => unknown
diff --git a/packages/hooks/hooks-claude/tests/bridge.spec.ts b/packages/hooks/hooks-claude/tests/bridge.spec.ts
index 1da2771257..244abae423 100644
--- a/packages/hooks/hooks-claude/tests/bridge.spec.ts
+++ b/packages/hooks/hooks-claude/tests/bridge.spec.ts
@@ -225,7 +225,7 @@ describe('hooks-claude bridge — PostToolUse', () => {
     expect(ctxMsg?.type === 'user/message' && ctxMsg.data.content.some(b => b.type === 'text' && b.text.includes('tool was slow'))).toBe(true)
   })
 
-  it('a PreToolUse permissionDecision:ask degrades to ask (the tool is gated, not run)', async () => {
+  it('a PreToolUse permissionDecision:ask fails closed without an approval service', async () => {
     const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
     dirs.push(dir)
     const s = join(dir, 'ask.sh')
@@ -241,7 +241,7 @@ describe('hooks-claude bridge — PostToolUse', () => {
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
-    // `ask` degrades to deny today (FIXME permissions): the tool does not run and the result is isError.
+    // No approval service is mounted, so `ask` fails closed: the tool does not run and the result is isError.
     expect(ran).toBe(false)
     const result = events(agent).find(e => e.type === 'tool/result')
     expect(result?.type === 'tool/result' && result.data.message.content[0].isError).toBe(true)
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 0ad49faa17..5225ba9d8c 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
-README.md: d15b2c996d6d47371a3d6c5542eb5c253029dbae
-README.zh.md: d965f15298f09ff9c2a953a69346c4e83136934b
+README.md: 956bfa112d6fe50c35359cebdf3710064da8c130
+README.zh.md: 42f2da18089e7dcfc9acb95076ab8786c798444b
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index d15b2c996d..956bfa112d 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -97,5 +97,5 @@ Pass-through; the registry preserves the assembled request prefix, while the sel
 - **`GenerateOptions` sampling is `temperature`/`maxTokens`/`stop` only** — no `tool_choice`, `top_p`, or penalty fields; the vocabulary grows when a producer lands ([dropped inert knobs](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)).
 - **Producer-gated variants stay out until produced** — `prefill`, per-tool `strict`, block `cache` hints, and the `agent` message-source variant were pruned as producerless ([Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)).
 - **`BlockAssembler` handles core block kinds only** — a plugin-added block type whose stream is never closed by `block-end` makes `blocks()` throw.
-- **`APP_IDENTITY.url` names a repository that does not exist yet** — `FIXME`: creating the public `deepseek-ai/deepseek-harness-sdk` repo gates the first release.
+- **`APP_IDENTITY.url` names a repository that does not exist yet** — [#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) tracks making the public home reachable before release.
 - **`GenerateOptions.sessionId` is a locally-declared brand** — importing dsh-session's `SessionId` would cycle; a future ids-owning package would dissolve the workaround.
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index d965f15298..42f2da1808 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -97,5 +97,5 @@
 - **`GenerateOptions` 采样只包含 `temperature`／`maxTokens`／`stop`**：没有 `tool_choice`、`top_p` 或 penalty 字段；有产生方落地时词汇才会增长（见 [已删除惰性旋钮](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)）。
 - **受产生方约束的变体在实际产生前不会加入**：`prefill`、每工具 `strict`、块 `cache` 提示与 `agent` 消息源变体因没有产生方而被剪除（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)）。
 - **`BlockAssembler` 只处理核心块类型**：如果插件添加块类型的流从未由 `block-end` 关闭，`blocks()` 会抛出异常。
-- **`APP_IDENTITY.url` 指向一个尚不存在的仓库**：`FIXME`：创建公开 `deepseek-ai/deepseek-harness-sdk` 仓库是首次发布的前置条件。
+- **`APP_IDENTITY.url` 指向一个尚不存在的仓库**：[#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) 跟踪在首次发布前让该公开主页可访问。
 - **`GenerateOptions.sessionId` 是本地声明的品牌类型**：导入 dsh-session 的 `SessionId` 会产生循环；未来拥有 id 的包可以消除该权宜之计。
diff --git a/packages/llm/llm/src/attribution.ts b/packages/llm/llm/src/attribution.ts
index cdaea4b96b..b9375b6ef9 100644
--- a/packages/llm/llm/src/attribution.ts
+++ b/packages/llm/llm/src/attribution.ts
@@ -40,8 +40,8 @@ export interface AppIdentity {
 export const APP_IDENTITY: AppIdentity = {
   product: 'deepseek-harness',
   version,
-  // FIXME: create the public deepseek-ai/deepseek-harness-sdk repository this
-  // URL promises before the first release ships attribution pointing at it.
+  // The public-home release blocker is tracked in
+  // https://github.com/deepseek-harness/deepseek-harness/issues/1972.
   url: 'https://github.com/deepseek-ai/deepseek-harness-sdk',
 }
 
diff --git a/packages/sdk/telemetry/README.i18n.yaml b/packages/sdk/telemetry/README.i18n.yaml
index 9baaa2ebff..987dc8197c 100644
--- a/packages/sdk/telemetry/README.i18n.yaml
+++ b/packages/sdk/telemetry/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/sdk/telemetry/README.md
-README.md: 1d33915f36e0af10eedac5f9ab34f2534268a327
-README.zh.md: af54cc2c78cb360d4305eeaf584c8330a0b7efa5
+README.md: c9f66a2415c91b75105b0ed025470da234b2523d
+README.zh.md: bfb154e4c7c017292b5479e50ff376cbb9470682
diff --git a/packages/sdk/telemetry/README.md b/packages/sdk/telemetry/README.md
index 1d33915f36..c9f66a2415 100644
--- a/packages/sdk/telemetry/README.md
+++ b/packages/sdk/telemetry/README.md
@@ -14,7 +14,7 @@ Launcher-side telemetry primitives for the dsh-sdk toolchain. This is a plain li
 
 Consent is carried by the telemetry entry in `cordis.yml`, so disabling telemetry is disabling that entry. Telemetry reports by default and is off only when a present telemetry entry is explicitly `disabled`: a missing `cordis.yml` (first `create`), an enabled entry, or a `cordis.yml` with no telemetry entry all report. `DO_NOT_TRACK`/CI always deny. The no-config and absent-entry defaults are configurable on `ConsentResolver`.
 
-The collection endpoint is a fixed constant (`DSH_TELEMETRY_ENDPOINT`); its `.invalid` placeholder must be replaced with the real endpoint before release.
+The collection endpoint is a fixed constant (`DSH_TELEMETRY_ENDPOINT`); [#1973](https://github.com/deepseek-harness/deepseek-harness/issues/1973) tracks deploying the service and replacing its fail-safe `.invalid` placeholder before release.
 
 ## Model Experience
 
@@ -26,5 +26,5 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **Placeholder endpoint** — `DSH_TELEMETRY_ENDPOINT` points at `.invalid` until the real endpoint is set.
+- **Placeholder endpoint** — `DSH_TELEMETRY_ENDPOINT` points at `.invalid` until the service tracked in [#1973](https://github.com/deepseek-harness/deepseek-harness/issues/1973) is ready.
 - **Redaction is heuristic** — a conservative backstop, not a guarantee; secrets belong in `.env`, which is never read or reported.
diff --git a/packages/sdk/telemetry/README.zh.md b/packages/sdk/telemetry/README.zh.md
index af54cc2c78..bfb154e4c7 100644
--- a/packages/sdk/telemetry/README.zh.md
+++ b/packages/sdk/telemetry/README.zh.md
@@ -14,7 +14,7 @@
 
 Consent 由 `cordis.yml` 中的 telemetry 配置项承载，因此禁用 telemetry 就是禁用该配置项。telemetry 默认上报，只有已经存在的 telemetry 配置项被显式设为 `disabled` 时才关闭：缺少 `cordis.yml`（首次 `create`）、配置项已启用，或 `cordis.yml` 中没有 telemetry 配置项时都会上报。`DO_NOT_TRACK`／CI 始终拒绝。无配置与缺少配置项的默认值可以通过 `ConsentResolver` 配置。
 
-收集端点是固定常量（`DSH_TELEMETRY_ENDPOINT`）；发布前必须将其 `.invalid` 占位值替换为真实端点。
+收集端点是固定常量（`DSH_TELEMETRY_ENDPOINT`）；[#1973](https://github.com/deepseek-harness/deepseek-harness/issues/1973) 跟踪服务部署，以及发布前将作为安全兜底的 `.invalid` 占位值替换为真实端点。
 
 ## 模型体验
 
@@ -26,5 +26,5 @@ Consent 由 `cordis.yml` 中的 telemetry 配置项承载，因此禁用 telemet
 
 ## 已知限制与暂缓事项
 
-- **占位端点**：`DSH_TELEMETRY_ENDPOINT` 指向 `.invalid`，直到设置真实端点。
+- **占位端点**：`DSH_TELEMETRY_ENDPOINT` 指向 `.invalid`，直至 [#1973](https://github.com/deepseek-harness/deepseek-harness/issues/1973) 跟踪的服务就绪。
 - **脱敏依赖启发式规则**：这只是保守后备，不是保证；密钥应存放于 `.env`，而该文件绝不会被读取或上报。
diff --git a/packages/sdk/telemetry/src/reporter.ts b/packages/sdk/telemetry/src/reporter.ts
index d41c1db9b7..3ad7b4b62e 100644
--- a/packages/sdk/telemetry/src/reporter.ts
+++ b/packages/sdk/telemetry/src/reporter.ts
@@ -16,11 +16,10 @@ import { getOrCreateAnonymousId, type AnonymousId } from './anonymous-id.ts'
 import { SecretRedactor } from './secret-redactor.ts'
 
 /**
- * Placeholder collection endpoint. This is a fixed protocol constant, not a
- * deployment tunable.
- *
- * FIXME(ccyu): replace with the real telemetry endpoint before release. The
- * `.invalid` TLD guarantees delivery fails harmlessly until then.
+ * Fail-safe placeholder collection endpoint. The `.invalid` TLD guarantees
+ * delivery fails harmlessly until the service tracked in
+ * https://github.com/deepseek-harness/deepseek-harness/issues/1973 is ready.
+ * This is a fixed protocol constant, not a deployment tunable.
  */
 export const DSH_TELEMETRY_ENDPOINT = 'https://telemetry.example.invalid/v1/dsh-sdk'
 
diff --git a/scripts/install.sh b/scripts/install.sh
index 5c9d892f73..59184d91ab 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -47,8 +47,6 @@
 #   DSH_CURRENT      stable symlink to the active worktree (default: $DSH_SOURCE/current)
 #   DSH_BIN_DIR      directory the `dsh` symlink lands in (default: ~/.local/bin)
 #   DSH_HOME         Harness home holding profiles and user patches (default: ~/.dsh)
-# FIXME(install-ts): Move the post-checkout workflow into a tested TypeScript
-# entrypoint; keep this POSIX shell file as the curl/source bootstrap.
 set -eu
 
 DSH_REF=${DSH_REF:-master}

From 510976351cb28d6ce5307a87db5c80e72de95c95 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 00:34:42 +0800
Subject: [PATCH 175/516] test(telemetry): restore expression-tag coverage

---
 packages/sdk/telemetry/tests/consent-resolver.spec.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/sdk/telemetry/tests/consent-resolver.spec.ts b/packages/sdk/telemetry/tests/consent-resolver.spec.ts
index 05442bcc0f..b9c9300e78 100644
--- a/packages/sdk/telemetry/tests/consent-resolver.spec.ts
+++ b/packages/sdk/telemetry/tests/consent-resolver.spec.ts
@@ -78,6 +78,7 @@ describe('ConsentResolver cordis.yml state', () => {
       '  name: \'@deepseek-ai/dsh-llm-deepseek\'',
       '  config:',
       '    apiKeyEnv: DEEPSEEK_API_KEY',
+      '    model: !!js process.env.DEEPSEEK_MODEL',
       '',
     ].join('\n')
     expect(await resolver.resolve(await projectDir(yml)))

From 62c308f4157d1b30cb5be9ad56e70c721c016e10 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 00:40:06 +0800
Subject: [PATCH 176/516] feat(skill): share renderSkillContent and declare the
 skill-invocation message source

The model-facing <skill_content> rendering moves from dsh-tool-skill to the
dsh-skill seam so the skill tool result and the upcoming user-explicit
invocation injection share one canonical shape. The seam also declares the
skill-invocation MessageSource kind that injection will stamp on its
user-role messages.
---
 packages/skill/skill/package.json        |  2 +
 packages/skill/skill/src/index.ts        | 91 ++++++++++++++++++++++++
 packages/skill/skill/tests/skill.spec.ts | 63 ++++++++++++++++
 packages/skill/skill/tsconfig.json       |  3 +
 packages/skill/tool-skill/src/index.ts   | 59 +--------------
 5 files changed, 162 insertions(+), 56 deletions(-)

diff --git a/packages/skill/skill/package.json b/packages/skill/skill/package.json
index 73469b89a7..f77f56f6d1 100644
--- a/packages/skill/skill/package.json
+++ b/packages/skill/skill/package.json
@@ -26,6 +26,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
@@ -33,6 +34,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/skill/skill/src/index.ts b/packages/skill/skill/src/index.ts
index 32f7112542..f44386d51c 100644
--- a/packages/skill/skill/src/index.ts
+++ b/packages/skill/skill/src/index.ts
@@ -10,6 +10,7 @@
  */
 
 import { Context, Service } from 'cordis'
+import { assertNever } from '@deepseek-ai/dsh-llm'
 import z from 'schemastery'
 import type Schema from 'schemastery'
 
@@ -119,6 +120,96 @@ export function isUserInvocable(skill: Pick<SkillSummary, 'invocation'>): boolea
   return skill.invocation.userInvocable
 }
 
+/**
+ * Durable message source for a user-explicit skill invocation: the host
+ * injects the rendered skill as a user-role message carrying this source, so
+ * transcript consumers present the invocation from metadata instead of
+ * re-parsing the model-facing text.
+ */
+export interface SkillInvocationSource {
+  readonly kind: 'skill-invocation'
+  /** Invoked skill name, validated user-invocable at the injecting boundary. */
+  readonly name: string
+  /** Trailing free text the user submitted after the skill token, when present. */
+  readonly args?: string
+}
+
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    /** A user-explicit skill invocation injected by the host. */
+    'skill-invocation': SkillInvocationSource
+  }
+}
+
+/**
+ * Render one loaded skill for the model. The output is shared verbatim by the
+ * `skill` tool result and the user-explicit invocation injection, so the model
+ * sees one canonical `<skill_content>` shape on both paths. The name rides an
+ * escaped attribute; the body is embedded verbatim (skills are trusted local
+ * content, and user-supplied invocation text stays outside this wrapper).
+ * @param skill - name, provider, optional resource base, and body to render.
+ * @returns the complete model-facing `<skill_content>` block.
+ */
+export function renderSkillContent(skill: Pick<SkillDefinition, 'name' | 'provider' | 'resourceBase' | 'content'>): string {
+  const resourceHint = renderResourceHint(skill)
+  return [
+    `<skill_content name="${escapeAttr(skill.name)}">`,
+    '<skill_resources>',
+    ...resourceHint,
+    '</skill_resources>',
+    '',
+    '<skill_instructions>',
+    skill.content,
+    '</skill_instructions>',
+    '</skill_content>',
+  ].join('\n')
+}
+
+function renderResourceHint(skill: Pick<SkillDefinition, 'provider' | 'resourceBase'>): string[] {
+  const base = skill.resourceBase
+  if (base === undefined) {
+    return [
+      `Resources for this skill are managed by provider "${escapeText(skill.provider)}".`,
+      'Load referenced resources only as needed.',
+    ]
+  }
+  switch (base.kind) {
+    case 'directory':
+      return [
+        `Base directory for this skill: ${escapeText(base.path)}`,
+        'Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.',
+      ]
+    case 'url':
+      return [
+        `Base URL for this skill: ${escapeText(base.url)}`,
+        'Resolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.',
+      ]
+    case 'opaque':
+      return [
+        `Resources for this skill: ${escapeText(base.description)}`,
+        'Load referenced resources only as needed.',
+      ]
+    /* v8 ignore start -- SkillResourceBase is a closed union; a future kind must fail compilation here. */
+    default:
+      return assertNever(base, 'SkillResourceBase.kind')
+    /* v8 ignore stop */
+  }
+}
+
+function escapeAttr(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;')
+}
+
+/**
+ * Escape model-facing prose embedded inside skill markup so provider-supplied
+ * text cannot open or close framing tags.
+ * @param value - raw prose to embed.
+ * @returns the escaped text.
+ */
+export function escapeText(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+}
+
 /** One catalog observation plus whether discovery completed within a stable catalog revision. */
 export interface SkillCatalogSnapshot {
   /** Sorted invocation-neutral summaries collected in this observation. */
diff --git a/packages/skill/skill/tests/skill.spec.ts b/packages/skill/skill/tests/skill.spec.ts
index 39ef384f3c..d48263cfe0 100644
--- a/packages/skill/skill/tests/skill.spec.ts
+++ b/packages/skill/skill/tests/skill.spec.ts
@@ -3,6 +3,7 @@ import { Context } from 'cordis'
 import SkillService, {
   isModelInvocable,
   isUserInvocable,
+  renderSkillContent,
   type SkillCandidate,
   type SkillDefinition,
   type SkillInvocationPolicy,
@@ -1013,3 +1014,65 @@ describe('SkillService registry', () => {
     expect(await ctx.skills.get('same-skill')).toBeUndefined()
   })
 })
+
+describe('renderSkillContent', () => {
+  it('renders a directory-based skill with the shared wrapper', () => {
+    const text = renderSkillContent({
+      name: 'demo-skill',
+      provider: 'memory',
+      resourceBase: { kind: 'directory', path: '/tmp/demo' },
+      content: 'Do the thing.',
+    })
+    expect(text).toBe([
+      '<skill_content name="demo-skill">',
+      '<skill_resources>',
+      'Base directory for this skill: /tmp/demo',
+      'Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.',
+      '</skill_resources>',
+      '',
+      '<skill_instructions>',
+      'Do the thing.',
+      '</skill_instructions>',
+      '</skill_content>',
+    ].join('\n'))
+  })
+
+  it('renders url and opaque resource hints', () => {
+    const url = renderSkillContent({
+      name: 'url-skill',
+      provider: 'memory',
+      resourceBase: { kind: 'url', url: 'https://example.test/base/' },
+      content: 'Body.',
+    })
+    expect(url).toContain('Base URL for this skill: https://example.test/base/')
+    expect(url).toContain('Resolve relative URLs mentioned by this skill against the base URL before using them.')
+
+    const opaque = renderSkillContent({
+      name: 'opaque-skill',
+      provider: 'memory',
+      resourceBase: { kind: 'opaque', description: 'archive <bundle>' },
+      content: 'Body.',
+    })
+    expect(opaque).toContain('Resources for this skill: archive &lt;bundle&gt;')
+  })
+
+  it('falls back to the provider hint without a resource base', () => {
+    const text = renderSkillContent({
+      name: 'provider-skill',
+      provider: 'remote <hub>',
+      content: 'Body.',
+    })
+    expect(text).toContain('Resources for this skill are managed by provider "remote &lt;hub&gt;".')
+  })
+
+  it('escapes hostile attribute names and keeps the body verbatim', () => {
+    const text = renderSkillContent({
+      name: 'x"&<y',
+      provider: 'memory',
+      resourceBase: { kind: 'directory', path: '/tmp' },
+      content: 'Keep </skill_content> and <tags> as-is.',
+    })
+    expect(text).toContain('<skill_content name="x&quot;&amp;&lt;y">')
+    expect(text).toContain('Keep </skill_content> and <tags> as-is.')
+  })
+})
diff --git a/packages/skill/skill/tsconfig.json b/packages/skill/skill/tsconfig.json
index e882ed2d72..82e62d7c91 100644
--- a/packages/skill/skill/tsconfig.json
+++ b/packages/skill/skill/tsconfig.json
@@ -15,6 +15,9 @@
     {
       "path": "../../../vendor/schemastery"
     },
+    {
+      "path": "../../llm/llm"
+    },
     {
       "path": "../../support/invariants"
     }
diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts
index ddc45d18e9..19e154143d 100644
--- a/packages/skill/tool-skill/src/index.ts
+++ b/packages/skill/tool-skill/src/index.ts
@@ -9,12 +9,13 @@ import type { Context } from 'cordis'
 import z from 'schemastery'
 import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { assertNever, createUserMessage } from '@deepseek-ai/dsh-llm'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { UserMessage } from '@deepseek-ai/dsh-session'
 import {
+  escapeText,
   isModelInvocable,
   isSkillName,
-  type SkillDefinition,
+  renderSkillContent,
   type SkillSummary,
 } from '@deepseek-ai/dsh-skill'
 
@@ -203,52 +204,6 @@ export function apply(ctx: Context, config: Config = {}): void {
   })
 }
 
-function renderSkillContent(skill: Pick<SkillDefinition, 'name' | 'provider' | 'resourceBase' | 'content'>): string {
-  const resourceHint = renderResourceHint(skill)
-  return [
-    `<skill_content name="${escapeAttr(skill.name)}">`,
-    '<skill_resources>',
-    ...resourceHint,
-    '</skill_resources>',
-    '',
-    '<skill_instructions>',
-    skill.content,
-    '</skill_instructions>',
-    '</skill_content>',
-  ].join('\n')
-}
-
-function renderResourceHint(skill: Pick<SkillDefinition, 'provider' | 'resourceBase'>): string[] {
-  const base = skill.resourceBase
-  if (base === undefined) {
-    return [
-      `Resources for this skill are managed by provider "${escapeText(skill.provider)}".`,
-      'Load referenced resources only as needed.',
-    ]
-  }
-  switch (base.kind) {
-    case 'directory':
-      return [
-        `Base directory for this skill: ${escapeText(base.path)}`,
-        'Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.',
-      ]
-    case 'url':
-      return [
-        `Base URL for this skill: ${escapeText(base.url)}`,
-        'Resolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.',
-      ]
-    case 'opaque':
-      return [
-        `Resources for this skill: ${escapeText(base.description)}`,
-        'Load referenced resources only as needed.',
-      ]
-    /* v8 ignore start -- SkillResourceBase is a closed union; a future kind must fail compilation here. */
-    default:
-      return assertNever(base, 'SkillResourceBase.kind')
-    /* v8 ignore stop */
-  }
-}
-
 function renderCatalogMessage(entries: SkillCatalogSource['entries']): UserMessage {
   return createUserMessage({
     content: [{
@@ -393,11 +348,3 @@ function assertPositiveInteger(name: string, value: number, minimum = 1): void {
     throw new Error(`tool-skill: ${name} must be an integer greater than or equal to ${minimum}`)
   }
 }
-
-function escapeAttr(value: string): string {
-  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;')
-}
-
-function escapeText(value: string): string {
-  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
-}

From 85422f44dc512ee5365f513b0aa5f44e11c62ddf Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 00:51:24 +0800
Subject: [PATCH 177/516] feat(host): user-invocable skill listing and
 skill.invoke injection RPC

skill.list now serves every user-invocable skill and carries modelInvocable
so menus can mark user-only entries; the old model-and-user intersection
hid disable-model-invocation skills from their only legitimate entry point
(issue #1470). skill.invoke enforces user-invocation policy at the host
boundary, renders the canonical <skill_content> body, and injects it as a
user-role message carrying the skill-invocation source before starting a
turn. The connection fixture mirrors both faces for client tests.
---
 .../client/connection/src/client/fixture.ts   |  21 +++-
 packages/host/apiproxy/src/api-proxy.ts       |  58 ++++++++-
 packages/host/apiproxy/src/api/rpc-map.ts     |   1 +
 packages/host/apiproxy/src/api/rpc.schema.ts  |   2 +
 packages/host/apiproxy/src/api/rpc.ts         |   4 +
 .../host/apiproxy/src/api/skills.schema.ts    |  13 ++
 packages/host/apiproxy/src/api/skills.ts      |  18 ++-
 packages/host/apiproxy/src/fetch/client.ts    |   5 +-
 packages/host/apiproxy/src/fetch/handler.ts   |   3 +-
 .../apiproxy/tests/api-proxy-commands.spec.ts | 116 +++++++++++++++++-
 .../apiproxy/tests/client-handler.spec.ts     |   2 +-
 .../host/apiproxy/tests/fetch-carrier.spec.ts |   9 +-
 .../host/apiproxy/tests/rpc-schemas.spec.ts   |  25 +++-
 13 files changed, 261 insertions(+), 16 deletions(-)

diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 776d21fd46..75653d43e3 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2449,10 +2449,28 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         if (missing !== undefined) return missing
         return ok(request, {
           skills: [
-            { name: 'fixture-demo', description: 'fixture 技能样本', whenToUse: '仅供 UI 目录渲染验收' },
+            { name: 'fixture-demo', description: 'fixture 技能样本', whenToUse: '仅供 UI 目录渲染验收', modelInvocable: true },
+            { name: 'fixture-user-only', description: 'fixture 仅用户技能样本', modelInvocable: false },
           ],
         })
       },
+      invoke: (request) => {
+        const missing = requireSession(request)
+        if (missing !== undefined) return missing
+        const { sessionId, name, text: args } = request.payload
+        const body = `<skill_content name="${name}">\n<skill_resources>\nBase directory for this skill: /fixture/skills/${name}\n</skill_resources>\n\n<skill_instructions>\nFixture ${name} instructions.\n</skill_instructions>\n</skill_content>`
+        // Mirror the host: injection is a user-role message carrying the
+        // skill-invocation source, immediately visible in the transcript.
+        // The client program cannot see the host-side MessageSourceMap merge
+        // (sources are opaque wire JSON to the UI), so the fixture stamps the
+        // durable shape through the same assertion the projections read back.
+        const source = { kind: 'skill-invocation', name, ...args === undefined ? {} : { args } } as unknown as MessageSource
+        append(sessionId, {
+          type: 'user/message', surfaceOp: 'append',
+          data: userMessage(text(args === undefined ? body : `${body}\n\n${args}`), source),
+        })
+        return ok(request, { accepted: true as const })
+      },
     },
     goals: {
       // Compatibility face only: old API Proxy payloads and acknowledgements
@@ -2761,6 +2779,7 @@ export class FixtureApiClient extends AbstractApiClient {
       case 'command.list': return this.api.commands.list(request)
       case 'command.execute': return this.api.commands.execute(request, signal)
       case 'skill.list': return this.api.skills.list(request)
+      case 'skill.invoke': return this.api.skills.invoke(request)
       case 'goal.create': return this.api.goals.create(request)
       case 'goal.edit': return this.api.goals.edit(request)
       case 'goal.pause': return this.api.goals.pause(request)
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index e4b715a0c4..6384a4d408 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -18,6 +18,8 @@ import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import { SessionQueryError, type SessionSearchCursor } from '@deepseek-ai/dsh-session-query'
 import { SubagentError } from '@deepseek-ai/dsh-subagent'
 import type { SubagentListEntry as CatalogSubagentListEntry } from '@deepseek-ai/dsh-subagent'
+import { isSkillName, isUserInvocable, renderSkillContent } from '@deepseek-ai/dsh-skill'
+import type { SkillInvocationSource } from '@deepseek-ai/dsh-skill'
 import type { Workspace, WorkspaceRecord } from '@deepseek-ai/dsh-workspace'
 import {
   workspaceDomainState, workspaceRecord, WorkspaceId as brandWorkspaceId,
@@ -2359,19 +2361,71 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           return err(request, { code: 'internal', message: 'skill registry is absent: this deployment does not mount @deepseek-ai/dsh-skill in its composition (cordis.yml or explicit assembly)', details: {} })
         }
         try {
-          const skills = (await skillRegistry.list({ cwd }))
-            .filter(skill => skill.invocation.modelInvocable && skill.invocation.userInvocable)
+          const skills = (await skillRegistry.list({ cwd })).filter(isUserInvocable)
           return ok(request, {
             skills: skills.map(skill => ({
               name: skill.name,
               description: skill.description,
               ...skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse },
+              modelInvocable: skill.invocation.modelInvocable,
             })),
           })
         } catch (error: unknown) {
           return err(request, { code: 'internal', message: `skill listing failed: ${String(error)}`, details: {} })
         }
       },
+
+      async invoke(request) {
+        const { sessionId, name, text } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        const agent = found.agent
+        // Same turn-start refusal boundary as sessions.prompt: injection
+        // starts a turn, so a route no adapter serves is refused while the
+        // composer still shows the draft.
+        const target = targetFor(agent).current
+        if (!routeServed(target.provider)) {
+          return err(request, {
+            code: 'model-unavailable',
+            message: `no adapter serves provider "${target.provider}"; select a model for this session`,
+            details: { provider: target.provider, model: target.model },
+          })
+        }
+        const skillRegistry = ctx.get('skills')
+        if (skillRegistry === undefined) {
+          return err(request, { code: 'internal', message: 'skill registry is absent: this deployment does not mount @deepseek-ai/dsh-skill in its composition (cordis.yml or explicit assembly)', details: {} })
+        }
+        const lookup = { cwd: agent.session.header.cwd }
+        // isSkillName guards the registry contract; an ill-formed name is
+        // indistinguishable from an absent one for the caller.
+        const summary = isSkillName(name)
+          ? (await skillRegistry.list(lookup)).find(skill => skill.name === name)
+          : undefined
+        if (summary === undefined) {
+          return err(request, { code: 'skill-not-found', message: `skill "${name}" is unknown in this workspace`, details: { name } })
+        }
+        // The operation boundary owns user-invocation policy: client menus
+        // filtering their candidates is an affordance, not enforcement.
+        if (!isUserInvocable(summary)) {
+          return err(request, { code: 'skill-not-invocable', message: `skill "${name}" is not available for user invocation`, details: { name } })
+        }
+        const skill = await skillRegistry.get(name, lookup)
+        if (skill === undefined) {
+          return err(request, { code: 'skill-not-found', message: `skill "${name}" is unknown in this workspace`, details: { name } })
+        }
+        const body = renderSkillContent(skill)
+        const source: SkillInvocationSource = { kind: 'skill-invocation', name, ...text === undefined ? {} : { args: text } }
+        try {
+          const message: UserMessage = createUserMessage({
+            content: [{ type: 'text', text: text === undefined ? body : `${body}\n\n${text}` }],
+            source,
+          })
+          agent.followup(message)
+        } catch (error: unknown) {
+          return err(request, { code: 'agent-busy', message: 'skill invocation rejected', details: { reason: String(error) } })
+        }
+        return ok(request, { accepted: true as const })
+      },
     },
 
     settings: {
diff --git a/packages/host/apiproxy/src/api/rpc-map.ts b/packages/host/apiproxy/src/api/rpc-map.ts
index 9a8750c722..b001d54625 100644
--- a/packages/host/apiproxy/src/api/rpc-map.ts
+++ b/packages/host/apiproxy/src/api/rpc-map.ts
@@ -50,6 +50,7 @@ export interface RpcMethodMap {
   'command.list': CommandsApi['list']
   'command.execute': CommandsApi['execute']
   'skill.list': SkillsApi['list']
+  'skill.invoke': SkillsApi['invoke']
   'goal.create': GoalsApi['create']
   'goal.edit': GoalsApi['edit']
   'goal.pause': GoalsApi['pause']
diff --git a/packages/host/apiproxy/src/api/rpc.schema.ts b/packages/host/apiproxy/src/api/rpc.schema.ts
index 2733c6e940..dd3fe7cf57 100644
--- a/packages/host/apiproxy/src/api/rpc.schema.ts
+++ b/packages/host/apiproxy/src/api/rpc.schema.ts
@@ -51,6 +51,8 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('steer-unavailable'), message: z.string(), details: z.object({ itemId: z.string() }) }),
   z.object({ code: z.literal('command-error'), message: z.string(), details: z.object({}) }),
   z.object({ code: z.literal('unknown-command'), message: z.string(), details: z.object({}) }),
+  z.object({ code: z.literal('skill-not-found'), message: z.string(), details: z.object({ name: z.string() }) }),
+  z.object({ code: z.literal('skill-not-invocable'), message: z.string(), details: z.object({ name: z.string() }) }),
   z.object({ code: z.literal('settings-rejected'), message: z.string(), details: z.object({ ns: z.string() }) }),
   z.object({ code: z.literal('settings-not-exposed'), message: z.string(), details: z.object({ ns: z.string() }) }),
   z.object({ code: z.literal('settings-conflict'), message: z.string(), details: z.object({ ns: z.string(), expected: z.number(), actual: z.number() }) }),
diff --git a/packages/host/apiproxy/src/api/rpc.ts b/packages/host/apiproxy/src/api/rpc.ts
index 54bbb5a8cc..7bf41a32e1 100644
--- a/packages/host/apiproxy/src/api/rpc.ts
+++ b/packages/host/apiproxy/src/api/rpc.ts
@@ -51,6 +51,10 @@ export interface RpcErrorDetailsMap {
   'command-error': {}
   /** A leading-/ prompt named no registered command; the message names the token. */
   'unknown-command': {}
+  /** A skill invocation named no skill in the session's workspace (unknown or ill-formed name). */
+  'skill-not-found': { name: string }
+  /** A skill invocation named a skill whose policy forbids user invocation. */
+  'skill-not-invocable': { name: string }
   /**
    * A settings write was refused (schema validation, unknown namespace,
    * read-only provider, or storage failure); the message is the seam's text.
diff --git a/packages/host/apiproxy/src/api/skills.schema.ts b/packages/host/apiproxy/src/api/skills.schema.ts
index 3bf7ad429a..c1ee1024a3 100644
--- a/packages/host/apiproxy/src/api/skills.schema.ts
+++ b/packages/host/apiproxy/src/api/skills.schema.ts
@@ -14,6 +14,7 @@ export const skillEntrySchema = z.object({
   name: z.string().min(1),
   description: z.string(),
   whenToUse: z.string().optional(),
+  modelInvocable: z.boolean(),
 }) satisfies z.ZodType<Wire<SkillEntry>>
 
 /** skill.list request payload. */
@@ -25,3 +26,15 @@ export const skillListRequestSchema = z.object({
 export const skillListValueSchema = z.object({
   skills: z.array(skillEntrySchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'skill.list'>>>
+
+/** skill.invoke request payload. */
+export const skillInvokeRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  name: z.string().min(1),
+  text: z.string().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'skill.invoke'>>>
+
+/** skill.invoke response value. */
+export const skillInvokeValueSchema = z.object({
+  accepted: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'skill.invoke'>>>
diff --git a/packages/host/apiproxy/src/api/skills.ts b/packages/host/apiproxy/src/api/skills.ts
index 33802dd4c0..2ade72efb9 100644
--- a/packages/host/apiproxy/src/api/skills.ts
+++ b/packages/host/apiproxy/src/api/skills.ts
@@ -10,16 +10,28 @@ import type { RpcRequest, RpcResponse } from './rpc.ts'
 
 /** Skill catalog row (wire projection of the host SkillSummary; provider/source vocabulary stays host-side). */
 export interface SkillEntry {
-  /** Kebab-case identifier referenced as `<skill>name</skill>` in prompts. */
+  /** Kebab-case identifier the user references as `/name` in the composer. */
   readonly name: string
   /** Short routing description. */
   readonly description: string
   /** Optional extra routing guidance. */
   readonly whenToUse?: string
+  /** False marks a user-only skill (`disable-model-invocation`): invocable here, absent from the model catalog. */
+  readonly modelInvocable: boolean
 }
 
-/** Skill-domain unary methods (the map key skill.* of RpcMethodMap). */
+/** Skill-domain unary methods (the map keys skill.* of RpcMethodMap). */
 export interface SkillsApi {
-  /** Lists skills usable by the browser's user-selected model-reference path. */
+  /** Lists the user-invocable skill catalog for the session's project. */
   list(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ skills: readonly SkillEntry[] }>>
+
+  /**
+   * Injects one user-invocable skill into the addressed agent as a user-role
+   * message (the canonical `<skill_content>` rendering, with `text` appended
+   * when present) and starts a turn. The host enforces user-invocation policy
+   * here: a model-only or unknown name is refused regardless of what a client
+   * menu offered. Session-backed subagents reject with `agent-busy`.
+   */
+  invoke(request: RpcRequest<{ sessionId: SessionId; name: string; text?: string }>):
+  Promise<RpcResponse<{ accepted: true }>>
 }
diff --git a/packages/host/apiproxy/src/fetch/client.ts b/packages/host/apiproxy/src/fetch/client.ts
index 0f54d76dbc..574206458b 100644
--- a/packages/host/apiproxy/src/fetch/client.ts
+++ b/packages/host/apiproxy/src/fetch/client.ts
@@ -39,7 +39,7 @@ import {
   workspaceRenameValueSchema,
 } from '../api/workspace.schema.ts'
 import { commandExecuteValueSchema, commandListValueSchema } from '../api/commands.schema.ts'
-import { skillListValueSchema } from '../api/skills.schema.ts'
+import { skillInvokeValueSchema, skillListValueSchema } from '../api/skills.schema.ts'
 import {
   goalCreateValueSchema,
   goalEditValueSchema,
@@ -118,6 +118,7 @@ export interface IApiClient {
   }
   skills: {
     list(payload: RequestPayload<'skill.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'skill.list'>>>
+    invoke(payload: RequestPayload<'skill.invoke'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'skill.invoke'>>>
   }
   events: {
     mux(payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>
@@ -185,6 +186,7 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'command.list': commandListValueSchema,
   'command.execute': commandExecuteValueSchema,
   'skill.list': skillListValueSchema,
+  'skill.invoke': skillInvokeValueSchema,
   'goal.create': goalCreateValueSchema,
   'goal.edit': goalEditValueSchema,
   'goal.pause': goalPauseValueSchema,
@@ -441,6 +443,7 @@ export abstract class AbstractApiClient implements IApiClient {
 
   readonly skills: IApiClient['skills'] = {
     list: (payload, signal) => this.callUnary('skill.list', payload, signal),
+    invoke: (payload, signal) => this.callUnary('skill.invoke', payload, signal),
   }
 
   readonly goals: IApiClient['goals'] = {
diff --git a/packages/host/apiproxy/src/fetch/handler.ts b/packages/host/apiproxy/src/fetch/handler.ts
index d41b51ad6d..914c425e91 100644
--- a/packages/host/apiproxy/src/fetch/handler.ts
+++ b/packages/host/apiproxy/src/fetch/handler.ts
@@ -41,7 +41,7 @@ import {
   workspaceRenameRequestSchema,
 } from '../api/workspace.schema.ts'
 import { commandExecuteRequestSchema, commandListRequestSchema } from '../api/commands.schema.ts'
-import { skillListRequestSchema } from '../api/skills.schema.ts'
+import { skillInvokeRequestSchema, skillListRequestSchema } from '../api/skills.schema.ts'
 import {
   goalCreateRequestSchema,
   goalEditRequestSchema,
@@ -109,6 +109,7 @@ const UNARY_ROUTES: UnaryRoutes = {
   'command.list': { schema: commandListRequestSchema, invoke: (api, r) => api.commands.list(r) },
   'command.execute': { schema: commandExecuteRequestSchema, invoke: (api, r, signal) => api.commands.execute(r, signal) },
   'skill.list': { schema: skillListRequestSchema, invoke: (api, r) => api.skills.list(r) },
+  'skill.invoke': { schema: skillInvokeRequestSchema, invoke: (api, r) => api.skills.invoke(r) },
   'goal.create': { schema: goalCreateRequestSchema, invoke: (api, r) => api.goals.create(r) },
   'goal.edit': { schema: goalEditRequestSchema, invoke: (api, r) => api.goals.edit(r) },
   'goal.pause': { schema: goalPauseRequestSchema, invoke: (api, r) => api.goals.pause(r) },
diff --git a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
index 55781a3e77..7d7062023e 100644
--- a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
@@ -228,7 +228,10 @@ describe('skill.list', () => {
     // touch (or resume through) the Agent registry.
     const session = ctx.sessions.create(undefined, { meta: { cwd: '/proj' } })
     const value = expectOk(await api.skills.list(request({ sessionId: session.id })))
-    expect(value.skills).toEqual([{ name: 'commit-helper', description: 'Git commits', whenToUse: 'when committing' }])
+    expect(value.skills).toEqual([
+      { name: 'commit-helper', description: 'Git commits', whenToUse: 'when committing', modelInvocable: true },
+      { name: 'user-only', description: 'User-only', modelInvocable: false },
+    ])
     expect(seenCwds).toEqual(['/proj'])
     expect(ctx.agents.get(session.id)).toBeUndefined()
   })
@@ -266,6 +269,117 @@ describe('skill.list', () => {
   })
 })
 
+describe('skill.invoke', () => {
+  /** Provider with one user-only and one model-only skill, both loadable. */
+  function registerInvokeSkills(ctx: Context): void {
+    const summaries = [
+      {
+        name: 'user-only', description: 'User-only',
+        invocation: { modelInvocable: false, userInvocable: true },
+        source: 'custom', provider: 'probe', rank: 0, locator: null,
+        resourceBase: { kind: 'directory', path: '/proj/.agents/skills/user-only' },
+      },
+      {
+        name: 'model-only', description: 'Model-only',
+        invocation: { modelInvocable: true, userInvocable: false },
+        source: 'custom', provider: 'probe', rank: 0, locator: null,
+      },
+    ] as const
+    ctx.skills.registerProvider(() => ({
+      name: 'probe',
+      list: () => Promise.resolve(summaries.map(summary => ({ ...summary }))),
+      get: candidate => Promise.resolve({
+        ...summaries.find(summary => summary.name === candidate.name)!,
+        content: 'Follow the probe instructions.',
+      }),
+    }))
+  }
+
+  /** Agent stub whose session carries a project cwd and whose followup records the injected message. */
+  function invokableAgent(ctx: Context): { agent: Agent; followup: ReturnType<typeof vi.fn> } {
+    const session = ctx.sessions.create(undefined, { meta: { cwd: '/proj' } })
+    const inbox = new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} })
+    const followup = vi.fn()
+    const agent = { id: session.id, session, inbox, status: 'idle', ctx, followup } as unknown as Agent
+    ctx.agents.register(agent)
+    return { agent, followup }
+  }
+
+  it('injects a user-invocable skill as a user message with the invocation source', async () => {
+    const ctx = await harness()
+    registerInvokeSkills(ctx)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const { agent, followup } = invokableAgent(ctx)
+    const value = expectOk(await api.skills.invoke(request({
+      sessionId: agent.id, name: 'user-only', text: 'and check the fixture',
+    })))
+    expect(value).toEqual({ accepted: true })
+    expect(followup).toHaveBeenCalledTimes(1)
+    const message = followup.mock.calls[0]?.[0] as UserMessage
+    expect(message.source).toEqual({ kind: 'skill-invocation', name: 'user-only', args: 'and check the fixture' })
+    expect(message.content).toHaveLength(1)
+    const text = (message.content[0] as { text: string }).text
+    expect(text).toContain('<skill_content name="user-only">')
+    expect(text).toContain('Base directory for this skill: /proj/.agents/skills/user-only')
+    expect(text).toContain('Follow the probe instructions.')
+    expect(text.endsWith('\n\nand check the fixture')).toBe(true)
+  })
+
+  it('omits args from the source and content when no text rides the invocation', async () => {
+    const ctx = await harness()
+    registerInvokeSkills(ctx)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const { agent, followup } = invokableAgent(ctx)
+    expectOk(await api.skills.invoke(request({ sessionId: agent.id, name: 'user-only' })))
+    const message = followup.mock.calls[0]?.[0] as UserMessage
+    expect(message.source).toEqual({ kind: 'skill-invocation', name: 'user-only' })
+    const text = (message.content[0] as { text: string }).text
+    expect(text.endsWith('</skill_content>')).toBe(true)
+  })
+
+  it('rejects a skill the user may not invoke', async () => {
+    const ctx = await harness()
+    registerInvokeSkills(ctx)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const { agent, followup } = invokableAgent(ctx)
+    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'model-only' })))
+    expect(error.code).toBe('skill-not-invocable')
+    expect(followup).not.toHaveBeenCalled()
+  })
+
+  it('rejects an unknown or invalid skill name', async () => {
+    const ctx = await harness()
+    registerInvokeSkills(ctx)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const { agent } = invokableAgent(ctx)
+    const missing = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'absent-skill' })))
+    expect(missing.code).toBe('skill-not-found')
+    const invalid = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'Not A Name' })))
+    expect(invalid.code).toBe('skill-not-found')
+  })
+
+  it('surfaces a followup refusal as agent-busy', async () => {
+    const ctx = await harness()
+    registerInvokeSkills(ctx)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const { agent, followup } = invokableAgent(ctx)
+    followup.mockImplementation(() => { throw new Error('inbox closed') })
+    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'user-only' })))
+    expect(error.code).toBe('agent-busy')
+  })
+
+  it('fails loud with internal when the skill registry is not mounted', async () => {
+    const ctx = await harness({ skills: false })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const session = ctx.sessions.create(undefined, { meta: { cwd: '/proj' } })
+    const inbox = new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} })
+    ctx.agents.register({ id: session.id, session, inbox, status: 'idle', ctx, followup: vi.fn() } as unknown as Agent)
+    const error = expectErr(await api.skills.invoke(request({ sessionId: session.id, name: 'user-only' })))
+    expect(error.code).toBe('internal')
+    expect(error.message).toContain('skill registry is absent')
+  })
+})
+
 describe('host/commands-changed frame', () => {
   it('broadcasts on registry change', async () => {
     const ctx = await harness()
diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts
index ebd56ee551..0a65c817c6 100644
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -86,7 +86,7 @@ function scriptedApi(overrides: {
       execute: r => ok(r, { matched: false }),
       ...overrides.commands,
     },
-    skills: { list: r => ok(r, { skills: [] }), ...overrides.skills },
+    skills: { list: r => ok(r, { skills: [] }), invoke: r => ok(r, { accepted: true as const }), ...overrides.skills },
     goals: {
       create: err,
       edit: err,
diff --git a/packages/host/apiproxy/tests/fetch-carrier.spec.ts b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
index 22e1650f5b..09cabdcc7f 100644
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -196,7 +196,10 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
     },
     skills: {
       async list(request) {
-        return { rpcId: request.rpcId, result: { ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits' }] } } }
+        return { rpcId: request.rpcId, result: { ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits', modelInvocable: true }] } } }
+      },
+      async invoke(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },
     },
     goals: {
@@ -381,7 +384,9 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     const miss = await c.commands.execute({ sessionId: 's' as never, line: '/nope' })
     expect(miss.result).toEqual({ ok: true, value: { matched: false } })
     const skills = await c.skills.list({ sessionId: 's' as never })
-    expect(skills.result).toEqual({ ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits' }] } })
+    expect(skills.result).toEqual({ ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits', modelInvocable: true }] } })
+    const invoked = await c.skills.invoke({ sessionId: 's' as never, name: 'commit-helper', text: 'go' })
+    expect(invoked.result).toEqual({ ok: true, value: { accepted: true } })
   })
 
   it('lets command.execute finish after the 30-second default unary deadline', async () => {
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
index 28f9138502..253ac92fdf 100644
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -31,7 +31,7 @@ import {
   commandDescriptorSchema, commandExecuteRequestSchema, commandExecuteValueSchema,
   commandListRequestSchema, commandListValueSchema,
 } from '../src/api/commands.schema.ts'
-import { skillEntrySchema, skillListRequestSchema, skillListValueSchema } from '../src/api/skills.schema.ts'
+import { skillEntrySchema, skillInvokeRequestSchema, skillInvokeValueSchema, skillListRequestSchema, skillListValueSchema } from '../src/api/skills.schema.ts'
 import { hostFrameSchema, muxFrameSchema, askUserQuestionItemSchema } from '../src/api/events.schema.ts'
 import { approvalRequestIdSchema, approvalResponsePayloadSchema } from '../src/api/approvals.schema.ts'
 import { askUserQuestionAnswerSchema, questionResponsePayloadSchema } from '../src/api/questions.schema.ts'
@@ -74,6 +74,8 @@ describe('rpcErrorSchema', () => {
     expect(rpcErrorSchema.parse({ code: 'queue-item-not-found', message: 'm', details: { itemId: 'i' } }).code).toBe('queue-item-not-found')
     expect(rpcErrorSchema.parse({ code: 'command-error', message: 'm', details: {} }).code).toBe('command-error')
     expect(rpcErrorSchema.parse({ code: 'unknown-command', message: 'm', details: {} }).code).toBe('unknown-command')
+    expect(rpcErrorSchema.parse({ code: 'skill-not-found', message: 'm', details: { name: 'n' } }).code).toBe('skill-not-found')
+    expect(rpcErrorSchema.parse({ code: 'skill-not-invocable', message: 'm', details: { name: 'n' } }).code).toBe('skill-not-invocable')
     expect(rpcErrorSchema.parse({ code: 'title-invalid', message: 'm', details: { sessionId: 's' } }).code).toBe('title-invalid')
     expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
   })
@@ -81,6 +83,7 @@ describe('rpcErrorSchema', () => {
   it('rejects a known code with missing details', () => {
     expect(() => rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: {} })).toThrow()
     expect(() => rpcErrorSchema.parse({ code: 'title-invalid', message: 'm', details: {} })).toThrow()
+    expect(() => rpcErrorSchema.parse({ code: 'skill-not-invocable', message: 'm', details: {} })).toThrow()
     expect(() => rpcErrorSchema.parse({ code: 'command-error', message: 'm' })).toThrow()
     expect(() => rpcErrorSchema.parse({ code: 'nope', message: 'm', details: {} })).toThrow()
   })
@@ -395,12 +398,26 @@ describe('skills domain schemas', () => {
     expect(() => skillListRequestSchema.parse({})).toThrow()
     expect(skillListValueSchema.parse({ skills: [] }).skills).toEqual([])
     const value = skillListValueSchema.parse({ skills: [
-      { name: 'commit-helper', description: 'Git commits', whenToUse: 'when committing' },
-      { name: 'bare', description: 'No guidance' },
+      { name: 'commit-helper', description: 'Git commits', whenToUse: 'when committing', modelInvocable: true },
+      { name: 'bare', description: 'No guidance', modelInvocable: false },
     ] })
     expect(value.skills[0]?.whenToUse).toBe('when committing')
     expect(value.skills[1]?.whenToUse).toBeUndefined()
-    expect(() => skillEntrySchema.parse({ name: '', description: 'd' })).toThrow()
+    expect(value.skills[1]?.modelInvocable).toBe(false)
+    expect(() => skillEntrySchema.parse({ name: '', description: 'd', modelInvocable: true })).toThrow()
+    // modelInvocable is required wire data: an entry without it fails.
+    expect(() => skillEntrySchema.parse({ name: 'n', description: 'd' })).toThrow()
+  })
+
+  it('validates the invoke request/value pair', () => {
+    expect(skillInvokeRequestSchema.parse({ sessionId: 's1', name: 'user-only' }))
+      .toEqual({ sessionId: 's1', name: 'user-only' })
+    expect(skillInvokeRequestSchema.parse({ sessionId: 's1', name: 'user-only', text: 'check it' }).text)
+      .toBe('check it')
+    expect(() => skillInvokeRequestSchema.parse({ sessionId: 's1', name: '' })).toThrow()
+    expect(() => skillInvokeRequestSchema.parse({ name: 'user-only' })).toThrow()
+    expect(skillInvokeValueSchema.parse({ accepted: true })).toEqual({ accepted: true })
+    expect(() => skillInvokeValueSchema.parse({ accepted: false })).toThrow()
   })
 })
 

From 0490f8bb0621cb681c9b7c219ffef1c79247db94 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 00:51:54 +0800
Subject: [PATCH 178/516] feat(llm-pi-ai): per-model reasoningEfforts and
 reasoning-dispatch compat switches
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A model entry's reasoningEfforts dict declares its selectable thinking
levels — key = offered level, value = the wire spelling dispatch sends;
only off may leave the value empty (supported, send nothing). false
strips reasoning from a catalog model; every level is materialized
explicitly into pi-ai's thinkingLevelMap so nobody has to know pi-ai's
asymmetric absent-key defaulting. compat.thinkingFormat and
compat.supportsReasoningEffort become configurable on the route and per
model (model > route > catalog entry > pi-ai's URL-derived guess),
openai-completions only, so a private gateway speaking the DeepSeek
reasoning dialect no longer depends on its URL being recognizable.
Record-typed drift gates pin both enums to pi-ai's, and an unserviceable
declaration is refused at the write that produced it, naming route,
model, and level.
---
 apps/web/tests/declared-reasoning.e2e.ts      |  95 +++++++
 apps/web/tests/declared-reasoning.overlay.yml |   8 +
 .../declared-reasoning/ui.expected.md         |   7 +
 apps/web/tsconfig.json                        |   1 +
 packages/llm/llm-pi-ai/README.i18n.yaml       |   4 +-
 packages/llm/llm-pi-ai/README.md              |  31 ++-
 packages/llm/llm-pi-ai/README.zh.md           |  31 ++-
 packages/llm/llm-pi-ai/src/catalog.ts         | 239 +++++++++++++++++-
 packages/llm/llm-pi-ai/src/config.ts          |  40 ++-
 packages/llm/llm-pi-ai/src/index.ts           |  22 +-
 packages/llm/llm-pi-ai/tests/adapter.spec.ts  | 143 +++++++++++
 packages/llm/llm-pi-ai/tests/catalog.spec.ts  | 175 ++++++++++++-
 packages/llm/llm-pi-ai/tests/config.spec.ts   |  32 ++-
 tsconfig.host.json                            |   1 +
 14 files changed, 806 insertions(+), 23 deletions(-)
 create mode 100644 apps/web/tests/declared-reasoning.e2e.ts
 create mode 100644 apps/web/tests/declared-reasoning.overlay.yml
 create mode 100644 apps/web/tests/snapshots/declared-reasoning/ui.expected.md

diff --git a/apps/web/tests/declared-reasoning.e2e.ts b/apps/web/tests/declared-reasoning.e2e.ts
new file mode 100644
index 0000000000..664f20dfe6
--- /dev/null
+++ b/apps/web/tests/declared-reasoning.e2e.ts
@@ -0,0 +1,95 @@
+// Web e2e scenario: a hand-declared model's `reasoningEfforts` reaches the
+// composer's effort pane — the levels a settings profile declares are exactly
+// what the picker offers, and picking one records it with the default route.
+// Zero model calls: declaring, describing, and switching are settings/llm
+// traffic only, so there is no fixture and a stray stream would fail loud.
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import {
+  assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
+  launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { ZH_BROWSER_LOCALE, connectFreshWorkspaceZh, saveFailureShot } from './support.ts'
+
+/** Starts the shipped default on this scenario's declared reasoning model. */
+const OVERLAY = fileURLToPath(new URL('./declared-reasoning.overlay.yml', import.meta.url))
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/declared-reasoning', import.meta.url))
+const UI_EXPECTED = fileURLToPath(new URL('./snapshots/declared-reasoning/ui.expected.md', import.meta.url))
+const MODE = webSnapshotMode()
+
+describe.skipIf(MODE === 'record')('web e2e: declared reasoning efforts reach the composer', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({ extraOverlayPath: OVERLAY })
+    // The whole reasoning offer is the profile: key = selectable level, value
+    // = the wire spelling dispatch would send (`max: ultra` renames; the
+    // valueless `off` means "supported, send nothing"). The route sets no
+    // deployment default, so the pane leads with the provider-default entry.
+    await scaffold.ctx.settings.update(settingsNamespace('llm-pi-ai'), {
+      providers: {
+        'acme-gateway': {
+          displayName: 'Acme Gateway',
+          api: 'openai-completions',
+          baseURL: 'https://gateway.acme.example/v1',
+          models: [{
+            id: 'acme-think',
+            name: 'Acme Think',
+            reasoningEfforts: { off: null, high: 'high', max: 'ultra' },
+          }],
+        },
+      },
+    })
+    browser = await chromium.launch()
+    page = await browser.newPage({ viewport: { width: 1680, height: 1000 }, locale: ZH_BROWSER_LOCALE })
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    await connectFreshWorkspaceZh(page, scaffold.workspaceCwd)
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it('offers exactly the declared levels and records the picked one', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-declared-reasoning'))
+    const trigger = page.getByRole('button', { name: /^选择模型/ })
+    await trigger.waitFor({ timeout: 15_000 })
+    await trigger.click()
+    await page.getByRole('menuitem', { name: /推理等级/ }).click()
+
+    // Declared levels, nothing else: the provider-default entry (the route
+    // configures no `reasoning`), then Off/High/Max — minimal, low, medium,
+    // and xhigh were not declared and must not be offered.
+    const levels = page.getByRole('menuitemradio')
+    await expect.poll(async () => levels.allTextContents(), { timeout: 10_000 })
+      .toEqual(['Default', 'Off', 'High', 'Max'])
+    const snapshot = await captureStableAria(page, '[role="menu"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
+
+    // Picking a level is the same gesture that saves the default target, so
+    // the effort lands in the gateway's settings section beside the route.
+    await page.getByRole('menuitemradio', { name: 'High' }).click()
+    await expect.poll(
+      async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'),
+      { timeout: 10_000 },
+    ).toContain('reasoningEffort: high')
+    await expect.poll(() => trigger.getAttribute('aria-label'), { timeout: 10_000 })
+      .toBe('选择模型，当前 Acme Think，推理等级 High')
+    expect(tripwire.pageErrors).toEqual([])
+  }, 60_000)
+
+  it('keeps its snapshot inventory closed', async () => {
+    await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md'])
+  })
+})
diff --git a/apps/web/tests/declared-reasoning.overlay.yml b/apps/web/tests/declared-reasoning.overlay.yml
new file mode 100644
index 0000000000..d90452178c
--- /dev/null
+++ b/apps/web/tests/declared-reasoning.overlay.yml
@@ -0,0 +1,8 @@
+# The fixture-less web scaffold registers no adapter, so the shipped
+# deepseek-official default would be a route nothing serves. This scenario
+# starts the default on its own declared reasoning model so the effort pane
+# describes that model from the first open.
+- id: api-gateway
+  config:
+    provider: acme-gateway
+    model: acme-think
diff --git a/apps/web/tests/snapshots/declared-reasoning/ui.expected.md b/apps/web/tests/snapshots/declared-reasoning/ui.expected.md
new file mode 100644
index 0000000000..810a6bf8b5
--- /dev/null
+++ b/apps/web/tests/snapshots/declared-reasoning/ui.expected.md
@@ -0,0 +1,7 @@
+- menu "模型与推理等级":
+  - menuitemradio "Default" [checked]:
+    - text: Default
+    - img
+  - menuitemradio "Off"
+  - menuitemradio "High"
+  - menuitemradio "Max"
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 528714a527..48275db0d6 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -38,6 +38,7 @@
     "tests/settings-chrome.e2e.ts",
     "tests/models-settings.e2e.ts",
     "tests/default-model.e2e.ts",
+    "tests/declared-reasoning.e2e.ts",
     "tests/onboarding-deepseek-config.e2e.ts",
     "tests/remote-welcome.e2e.ts",
     "tests/workspace-management.e2e.ts",
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index b57043a84d..69efba1977 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: 97bd629adedda9d63fee730bc31129b0c22cc704
-README.zh.md: 71d45b590f48f4b8162ae329b58b5ff4a9eb13b1
+README.md: 894aecc720f0a7616c0127d439b41129d94ef667
+README.zh.md: 63464f80ee3036ddec3fb6828ecccc68c5524478
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index 97bd629ade..894aecc720 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -42,18 +42,41 @@ Configure credentials, the model catalog, and deployment-specific transport sett
         apiKeyEnv: ACME_GATEWAY_API_KEY
         api: openai-completions
         baseURL: https://gateway.acme.example/v1
+        # Reasoning dialect for an endpoint whose URL pi-ai cannot recognize.
+        compat:
+          thinkingFormat: deepseek
         models:
           - id: acme-large
             name: Acme Large
             contextWindow: 65536
             maxTokens: 4096
+          - id: acme-think
+            name: Acme Think
+            contextWindow: 262144
+            maxTokens: 32768
+            # key = selectable level, value = its wire spelling; only off may
+            # leave the value empty (supported, send nothing).
+            reasoningEfforts:
+              off:
+              high: high
+              max: ultra
 ```
 
 The dict shape makes duplicate routes unrepresentable, and the pre-release array shape (with per-profile `provider` fields) fails load with migration directions. `providers` may also be empty or omitted entirely: the adapter then mounts **dormant** — zero routes, no extra catalog entries — and registers routes the moment the `llm-pi-ai:` settings section supplies profiles, dropping them again when it empties. Dormant or not, the plugin declares every installed catalog provider in the configurable-provider directory (`ctx.llm.listConfigurableProviders()`, settings path `providers.<provider>`), joined with every route the current profiles declare, so configuration surfaces can offer the full catalog before any route exists and can still address a hand-declared one. Each entry carries `declared`: whether pi-ai ships nothing under that key. It follows the installed catalog, never the settings document, because narrowing a shipped provider's models stores a profile too and that route is still one pi-ai knows — only the adapter can tell the two apart, which is why the directory answers rather than leaving a surface to infer it. Which adapters exist is composition; which providers run can be entirely the user's settings document. Registration with `ctx.llm` is atomic: a collision with any provider route already owned by another adapter fails plugin loading without registering the remaining routes. Model ids are not lifecycle config; a model the route does not configure fails before any provider request with `LlmError('UNKNOWN_MODEL')`.
 
 ## Catalog resolution
 
-A profile's `models` list *replaces* the route's installed catalog rather than extending it; omitting it (or leaving it empty) serves that catalog unchanged. Each entry defaults its unset fields from the installed model of the same `id`, so narrowing a catalog route to two models, correcting one capacity, or adding a model newer than the installed catalog are all one-line edits. Only the fields the harness consumes are configurable — `id`, `name`, `contextWindow`, and `maxTokens`. Pricing and input modalities have no harness consumer and ride the installed entry or are absent. Reasoning is not per-model configurable at all: a bare capability flag would make pi-ai advertise effort levels with no `thinkingLevelMap` to spell them, and no listing endpoint reports a model's reasoning protocol, so reasoning rides the installed catalog entry or is absent.
+A profile's `models` list *replaces* the route's installed catalog rather than extending it; omitting it (or leaving it empty) serves that catalog unchanged. Each entry defaults its unset fields from the installed model of the same `id`, so narrowing a catalog route to two models, correcting one capacity, or adding a model newer than the installed catalog are all one-line edits — but declaring any `models` list means every model the route should keep serving must appear in it, an entry of nothing but `id` being enough. The configurable entry fields are `id`, `name`, `contextWindow`, `maxTokens`, `reasoningEfforts`, and `compat`. Pricing and input modalities have no harness consumer and ride the installed entry or are absent.
+
+### Per-model reasoning efforts
+
+`reasoningEfforts` declares a model's selectable thinking levels: each key is a level selectors offer, its value the spelling dispatch sends on the wire, so `high: high` passes the canonical name through while `max: ultra` renames it for a gateway with its own vocabulary. Keys come from pi-ai's level set (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`); a level not declared is not offered. Omitting the field keeps the installed catalog entry's capability (a hand-declared model has none and does not reason); `false` declares a non-reasoning model, which is how a profile strips reasoning from a catalog model its gateway cannot serve; an empty declaration is refused rather than guessing between those two meanings.
+
+The declaration translates to pi-ai's `Model.reasoning` + `thinkingLevelMap` with every level decided explicitly — undeclared levels are pinned unsupported rather than left to pi-ai's own defaulting, which is asymmetric (an absent key means "supported" for the five base levels but "unsupported" for `xhigh`/`max`) and which a profile author should not need to know. `off` is the one three-state key: left out, the model cannot stop thinking and selectors offer no Off; declared with no value (`off:`), Off is offered and selecting it sends nothing — for the `deepseek` dialect an explicit `thinking: {type: "disabled"}` — which also covers a request naming no effort at all; declared with a value (`off: none`), that value goes on the wire as the effort parameter. There is no spelling for restoring a catalog map key to "unset": the declaration is the whole offer, so restate the catalog levels you keep.
+
+### Reasoning-dispatch compat switches
+
+How a thinking level travels — `reasoning_effort` alone, DeepSeek's `thinking: {type}` plus effort, z.ai's `thinking` object, and so on — is pi-ai's `compat.thinkingFormat`, which pi-ai guesses from the endpoint URL; a private gateway's URL says nothing, so a DeepSeek-dialect gateway would be spoken to in the OpenAI dialect with no way to correct it. `compat.thinkingFormat` and `compat.supportsReasoningEffort` are therefore configurable on the route (its models' default) and per model (winning per field), resolving model → route → installed catalog entry → pi-ai's URL-derived guess; setting a route-level switch shadows the catalog entry's value for every model on the route, and there is no spelling for handing a field back to the catalog short of restating its value. `thinkingFormat` accepts pi-ai's dispatchable formats except the two `chat-template` variants, which need `chatTemplateKwargs` this configuration does not expose. Both switches exist only on `openai-completions` — the other protocols carry their reasoning shape in the protocol itself — so a model-level switch elsewhere fails resolution, a route-level one skips models of other protocols, and a route with no `openai-completions` model at all is refused. The rest of pi-ai's compat surface (`supportsStore`, `maxTokensField`, …) stays auto-detected and is deliberately not configurable here.
 
 A model neither the entry nor the installed catalog sizes takes the route's `defaultContextWindow` (262,144) and `defaultMaxTokens` (32,768), so a listing that discloses nothing but ids still yields a serviceable route. Both fallbacks are guesses by construction, which is why they are route fields a deployment whose gateway serves smaller models corrects once rather than constants buried in the adapter; the fallback sizes the model and never becomes a per-request cap.
 
@@ -71,11 +94,11 @@ Credentials resolve per stream call: a non-empty literal `apiKey` wins, then `ap
 
 The adapter exposes each configured route's models through `ctx.llm.listModels(provider)`. This is provider-neutral selector metadata read from the same pi-ai `Models` collection the request path uses, so discovery does not create a second model registry. `ctx.llm.resolveModelInfo(provider, model)` performs that exact descriptor lookup once and returns its identity, context window, configured output cap, and selectable thinking levels, keeping authoritative metadata on the route-owning adapter rather than its consumers. A model's **configured** `maxTokens` becomes the seam's `defaultMaxTokens`, so a request that names no output cap carries the one the deployment chose; a value inherited from the installed catalog is the model's output *capability* and never becomes a request default on its own.
 
-A model that carries reasoning metadata exposes pi-ai's ordered `getSupportedThinkingLevels(model)` result without filtering or normalization, including `off` and the model-specific availability of `xhigh` or `max`. The Harness exposes each canonical pi-ai level as an opaque ID; provider/model wire spellings remain inside pi-ai's `thinkingLevelMap`.
+A model that carries reasoning metadata — from the installed catalog or from its entry's `reasoningEfforts` — exposes pi-ai's ordered `getSupportedThinkingLevels(model)` result without filtering or normalization, including `off` and the model-specific availability of `xhigh` or `max`. The Harness exposes each canonical pi-ai level as an opaque ID; provider/model wire spellings remain inside pi-ai's `thinkingLevelMap`.
 
-A model **without** that metadata — every hand-declared one, and a catalog model pi-ai marks as non-reasoning — exposes no `reasoning` at all. pi-ai reports such a model as supporting the single level `off`, but `off` is translated to *omitting* the reasoning option, which is byte-for-byte the request that naming no effort already produces: selecting it could not disable anything, so a provider whose own default is to think would keep thinking with `off` shown as selected. Reporting the capability as unavailable leaves a surface offering the provider's default and nothing that misrepresents it. The profile `reasoning` value, including `off`, is the deployment default when configured; omitting it preserves the provider default. Per-request `GenerateOptions.reasoningEffort` takes precedence, and a level absent from the exact model capability fails the REQUEST with `UNSUPPORTED_REASONING_EFFORT` before network I/O instead of being clamped. Describing a model never fails that way: the models under one provider disagree about which levels they accept, so `resolveModel` reports a profile level the exact model cannot take as no default at all rather than throwing. A throw there would take the whole provider out of every model catalog built over it — one mis-set profile field hiding even the models that do support the level — so a bad configuration surfaces where it is acted on, not where it is described. pi-ai's common stream options represent `off` by omitting `reasoning`.
+A model **without** that metadata — a hand-declared one whose entry declares no `reasoningEfforts`, and a catalog model pi-ai marks as non-reasoning — exposes no `reasoning` at all. pi-ai reports such a model as supporting the single level `off`, but `off` is translated to *omitting* the reasoning option, which is byte-for-byte the request that naming no effort already produces: selecting it could not disable anything, so a provider whose own default is to think would keep thinking with `off` shown as selected. Reporting the capability as unavailable leaves a surface offering the provider's default and nothing that misrepresents it. The profile `reasoning` value, including `off`, is the deployment default when configured; omitting it preserves the provider default. Per-request `GenerateOptions.reasoningEffort` takes precedence, and a level absent from the exact model capability fails the REQUEST with `UNSUPPORTED_REASONING_EFFORT` before network I/O instead of being clamped. Describing a model never fails that way: the models under one provider disagree about which levels they accept, so `resolveModel` reports a profile level the exact model cannot take as no default at all rather than throwing. A throw there would take the whole provider out of every model catalog built over it — one mis-set profile field hiding even the models that do support the level — so a bad configuration surfaces where it is acted on, not where it is described. pi-ai's common stream options represent `off` by omitting `reasoning`.
 
-Supported profile fields are `apiKey`, `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `defaultContextWindow`, `defaultMaxTokens`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
+Supported profile fields are `apiKey`, `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `compat`, `defaultContextWindow`, `defaultMaxTokens`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
 
 The adapter forces pi-ai's SDK `maxRetries` to zero so one `stream()` call makes one provider request. The removed profile fields `maxRetries` and `maxRetryDelayMs` fail load instead of silently multiplying or hiding the separately composed agent-level retry budget. Idle expiry aborts the SDK's stable request signal and surfaces `TIMEOUT`; an earlier caller abort remains `ABORTED`.
 
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index 71d45b590f..63464f80ee 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -42,18 +42,41 @@
         apiKeyEnv: ACME_GATEWAY_API_KEY
         api: openai-completions
         baseURL: https://gateway.acme.example/v1
+        # Reasoning dialect for an endpoint whose URL pi-ai cannot recognize.
+        compat:
+          thinkingFormat: deepseek
         models:
           - id: acme-large
             name: Acme Large
             contextWindow: 65536
             maxTokens: 4096
+          - id: acme-think
+            name: Acme Think
+            contextWindow: 262144
+            maxTokens: 32768
+            # key = selectable level, value = its wire spelling; only off may
+            # leave the value empty (supported, send nothing).
+            reasoningEfforts:
+              off:
+              high: high
+              max: ultra
 ```
 
 字典形状使重复路由无法表示，发布前的数组形状（每个 profile 携带 `provider` 字段）会加载失败并给出迁移指引。`providers` 也可以为空或整体省略：适配器将以**休眠**姿态挂载——零路由、模型选择器不多一条——一旦 `llm-pi-ai:` settings 分节提供了 profile 就即时注册路由，分节清空时随之撤销。无论是否休眠，插件都会在可配置提供方目录（`ctx.llm.listConfigurableProviders()`，settings 路径 `providers.<provider>`）中声明每个已安装 catalog 提供方，并与当前 profile 声明的每条路由取并集，因此配置界面既能在任何路由存在之前就提供完整 catalog，也能寻址一条手工声明的路由。每个条目都带上 `declared`：pi-ai 在这个键下是否什么都没有。它跟随已安装 catalog 而非设置文档，因为收窄一个内置提供方的模型同样会存下 profile，而那条路由仍然是 pi-ai 认识的——只有适配器分得清两者，所以由目录直接给出答案，而不是留给界面去猜。哪些适配器存在归组合面；哪些提供方在运行可以完全交给用户的设置文档。向 `ctx.llm` 注册具有原子性：如果与另一适配器已拥有的任何提供方路由冲突，插件会加载失败，不注册剩余路由。模型 id 不是生命周期配置；路由未配置的模型会在发起任何提供方请求前以 `LlmError('UNKNOWN_MODEL')` 失败。
 
 ## Catalog 解析
 
-profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩充它；省略它（或留空）则原样服务该 catalog。每个条目都会从同 `id` 的已安装模型继承自身未设置的字段，因此把 catalog 路由收窄到两个模型、更正某个容量，或加入一个比已安装 catalog 更新的模型，都是一行编辑。只有 harness 会消费的字段可配置——`id`、`name`、`contextWindow` 与 `maxTokens`。定价与输入模态没有 harness 消费方，因此沿用已安装条目或直接缺席。推理则完全不按模型配置：一个孤立的能力布尔量会让 pi-ai 公布出没有 `thinkingLevelMap` 可供拼写的档位，而且没有任何列表端点会报告模型的推理协议，因此推理沿用已安装 catalog 条目或直接缺席。
+profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩充它；省略它（或留空）则原样服务该 catalog。每个条目都会从同 `id` 的已安装模型继承自身未设置的字段，因此把 catalog 路由收窄到两个模型、更正某个容量，或加入一个比已安装 catalog 更新的模型，都是一行编辑——但一旦声明了 `models` 列表，该路由要继续服务的每个模型就都必须出现在其中，条目哪怕只写一个 `id` 也足够。可配置的条目字段是 `id`、`name`、`contextWindow`、`maxTokens`、`reasoningEfforts` 与 `compat`。定价与输入模态没有 harness 消费方，因此沿用已安装条目或直接缺席。
+
+### 按模型的推理档位
+
+`reasoningEfforts` 声明模型可选的思考级别：每个键是选择器提供的一个档位，其值是分派在协议中发送的拼写，因此 `high: high` 原样透传规范名称，而 `max: ultra` 则为使用自有词汇的网关改名。键取自 pi-ai 的档位集合（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`）；未声明的档位不会被提供。省略该字段会保留已安装 catalog 条目的能力（手工声明的模型没有这份能力，也不推理）；`false` 声明一个不具备推理能力的模型，profile 正是以此从其网关无法服务的 catalog 模型上剥除推理；空声明会被拒绝，而不是在这两种含义之间去猜。
+
+该声明会转换为 pi-ai 的 `Model.reasoning` + `thinkingLevelMap`，其中每个档位都被显式决定——未声明的档位一律固定为不支持，而不是留给 pi-ai 自己的默认规则：那套规则并不对称（键缺席对五个基础档位意味着「支持」，对 `xhigh`/`max` 却意味着「不支持」），也本不该要求 profile 作者了解。`off` 是唯一的三态键：不写它，模型就无法停止思考，选择器也不提供 Off；声明而不给值（`off:`），则会提供 Off，选中它时什么也不发送——对 `deepseek` 方言则是一个显式的 `thinking: {type: "disabled"}`——这同时覆盖完全不点名任何档位的请求；声明并给值（`off: none`），该值就会作为档位参数在协议中发送。没有任何写法能把 catalog 映射中的键恢复为「未设置」：这份声明就是对外提供的全部，因此把你要保留的 catalog 档位重述出来。
+
+### 推理分派的 compat 开关
+
+思考级别如何在协议中传输——单独一个 `reasoning_effort`、DeepSeek 的 `thinking: {type}` 加上档位、z.ai 的 `thinking` 对象，诸如此类——就是 pi-ai 的 `compat.thinkingFormat`，pi-ai 会从端点 URL 猜测它；私有网关的 URL 什么也说明不了，于是说 DeepSeek 方言的网关只会收到 OpenAI 方言的请求，且无从更正。因此 `compat.thinkingFormat` 与 `compat.supportsReasoningEffort` 既可配置在路由上（作为其模型的默认值），也可按模型配置（逐字段胜出），解析顺序为模型 → 路由 → 已安装 catalog 条目 → pi-ai 按 URL 得出的猜测；设置路由级开关会为路由上的每个模型遮蔽 catalog 条目的值，而且除了重述其值，没有任何写法能把某个字段交还给 catalog。`thinkingFormat` 接受 pi-ai 可分派的各种格式，但不含两个 `chat-template` 变体：它们需要的 `chatTemplateKwargs` 本配置并不暴露。两个开关都只存在于 `openai-completions` 上——其余协议的推理形状由协议本身承载——因此在其他协议的模型上设置模型级开关会使解析失败，路由级开关会跳过其他协议的模型，而完全没有 `openai-completions` 模型的路由则会被拒绝。pi-ai compat 面的其余部分（`supportsStore`、`maxTokensField`……）保持自动检测，特意不在此处开放配置。
 
 条目与已安装 catalog 都没有给出尺寸的模型，会采用该路由的 `defaultContextWindow`（262,144）与 `defaultMaxTokens`（32,768），因此一份只公布 id 的列表同样能产出可服务的路由。两个回退值本质上都是猜测，这正是它们作为路由字段、供网关服务更小模型的部署一次性更正的原因，而不是埋在适配器里的常量；回退值只用于给模型定尺寸，绝不会变成每请求上限。
 
@@ -71,11 +94,11 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 适配器通过 `ctx.llm.listModels(provider)` 公开每条已配置路由的模型。这是从请求路径所用的同一个 pi-ai `Models` 集合读取的提供方无关 selector 元数据，因此发现不会创建第二个模型注册表。`ctx.llm.resolveModelInfo(provider, model)` 会执行一次精确 descriptor 查找，并返回其身份、上下文窗口、已配置输出上限和可选思考级别，让权威元数据保留在拥有路由的适配器上，而非消费方。模型**已配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`，因此未点名输出上限的请求会携带部署选定的那一个；而从已安装 catalog 继承来的值是模型的输出**能力**，绝不会自行变成请求默认值。
 
-携带推理元数据的模型会公开 pi-ai 有序的 `getSupportedThinkingLevels(model)` 结果，不经筛选或规范化，其中包括 `off`，以及模型对 `xhigh` 或 `max` 的特定支持。Harness 将每个规范 pi-ai 级别公开为不透明 ID；提供方／模型在协议格式中的表示仍保留在 pi-ai 的 `thinkingLevelMap` 中。
+携带推理元数据的模型——来自已安装 catalog，或来自其条目的 `reasoningEfforts`——会公开 pi-ai 有序的 `getSupportedThinkingLevels(model)` 结果，不经筛选或规范化，其中包括 `off`，以及模型对 `xhigh` 或 `max` 的特定支持。Harness 将每个规范 pi-ai 级别公开为不透明 ID；提供方／模型在协议格式中的表示仍保留在 pi-ai 的 `thinkingLevelMap` 中。
 
-**没有**这份元数据的模型——每一个手工声明的模型，以及 pi-ai 标记为不具备推理能力的 catalog 模型——完全不公开 `reasoning`。pi-ai 会把这类模型报告为只支持 `off` 一档，但 `off` 会被翻译成*省略* reasoning 选项，而那与「不点名任何档位」产出的请求逐字节相同：选它关不掉任何东西，于是自身默认就在思考的提供方，会在界面显示 `off` 被选中的同时继续思考。把该能力报告为不可用，界面就只剩提供方默认这一项，不会再出现自相矛盾的控件。配置 profile 的 `reasoning` 值（包括 `off`）在存在时是部署默认值；省略它会保留提供方默认值。每次请求的 `GenerateOptions.reasoningEffort` 优先；未出现在确切模型能力中的档位会让**请求**在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败，而不会被自动调整。**描述**一个模型则从不这样失败：同一提供方下各模型接受的档位并不一致，因此 `resolveModel` 对该模型拿不下的 profile 档位报告为「没有默认值」，而不是抛错。在那里抛错会让整个提供方从任何基于它构建的模型目录中消失——一个配错的 profile 字段连支持该档位的模型也一并藏起来——所以坏配置暴露在被执行处，而不是被描述处。pi-ai 的通用流选项通过省略 `reasoning` 表示 `off`。
+**没有**这份元数据的模型——条目未声明 `reasoningEfforts` 的手工声明模型，以及 pi-ai 标记为不具备推理能力的 catalog 模型——完全不公开 `reasoning`。pi-ai 会把这类模型报告为只支持 `off` 一档，但 `off` 会被翻译成*省略* reasoning 选项，而那与「不点名任何档位」产出的请求逐字节相同：选它关不掉任何东西，于是自身默认就在思考的提供方，会在界面显示 `off` 被选中的同时继续思考。把该能力报告为不可用，界面就只剩提供方默认这一项，不会再出现自相矛盾的控件。配置 profile 的 `reasoning` 值（包括 `off`）在存在时是部署默认值；省略它会保留提供方默认值。每次请求的 `GenerateOptions.reasoningEffort` 优先；未出现在确切模型能力中的档位会让**请求**在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败，而不会被自动调整。**描述**一个模型则从不这样失败：同一提供方下各模型接受的档位并不一致，因此 `resolveModel` 对该模型拿不下的 profile 档位报告为「没有默认值」，而不是抛错。在那里抛错会让整个提供方从任何基于它构建的模型目录中消失——一个配错的 profile 字段连支持该档位的模型也一并藏起来——所以坏配置暴露在被执行处，而不是被描述处。pi-ai 的通用流选项通过省略 `reasoning` 表示 `off`。
 
-受支持的 profile 字段是 `apiKey`、`apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`defaultContextWindow`、`defaultMaxTokens`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs` 和 `retryPolicy`。每个 profile 的可选重试策略都会与该提供方路由一同捕获；省略时使用有界的常规默认值。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。若已配置标头中有同名项，则以 Harness 应用归因为准。
+受支持的 profile 字段是 `apiKey`、`apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`compat`、`defaultContextWindow`、`defaultMaxTokens`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs` 和 `retryPolicy`。每个 profile 的可选重试策略都会与该提供方路由一同捕获；省略时使用有界的常规默认值。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。若已配置标头中有同名项，则以 Harness 应用归因为准。
 
 适配器强制 pi-ai SDK `maxRetries` 为零，因此一次 `stream()` 调用只会发起一次提供方请求。已移除 profile 字段 `maxRetries` 和 `maxRetryDelayMs` 会使加载失败，而不是静默倍增或隐藏单独组合的 agent（智能体）级重试预算。空闲超时会 abort SDK 的稳定请求信号，并以 `TIMEOUT` 呈现；较早的调用方 abort 仍为 `ABORTED`。
 
diff --git a/packages/llm/llm-pi-ai/src/catalog.ts b/packages/llm/llm-pi-ai/src/catalog.ts
index 173b84dd7d..e3c9207927 100644
--- a/packages/llm/llm-pi-ai/src/catalog.ts
+++ b/packages/llm/llm-pi-ai/src/catalog.ts
@@ -14,7 +14,15 @@
 
 import { builtinProviders, getBuiltinModels, getBuiltinProviders } from '@earendil-works/pi-ai/providers/all'
 import type { BuiltinProvider } from '@earendil-works/pi-ai/providers/all'
-import type { Api, Model, ModelCost, Provider } from '@earendil-works/pi-ai'
+import type {
+  Api,
+  Model,
+  ModelCost,
+  ModelThinkingLevel,
+  OpenAICompletionsCompat,
+  Provider,
+  ThinkingLevelMap,
+} from '@earendil-works/pi-ai'
 
 /**
  * Pricing for a model the installed catalog does not describe. The harness
@@ -30,6 +38,58 @@ const NO_COST: ModelCost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
  */
 const TEXT_ONLY: Model<Api>['input'] = ['text']
 
+/**
+ * Every pi-ai thinking level, in pi-ai's canonical escalation order. The
+ * `Record` key type is a drift gate: a pi-ai upgrade that adds or removes a
+ * level fails compilation here naming the drifted key, instead of silently
+ * narrowing what a profile may declare.
+ */
+const THINKING_LEVEL_GATE: Record<ModelThinkingLevel, true> = {
+  off: true,
+  minimal: true,
+  low: true,
+  medium: true,
+  high: true,
+  xhigh: true,
+  max: true,
+}
+
+/** Every pi-ai thinking level a profile may declare, in escalation order. */
+export const THINKING_LEVELS = Object.keys(THINKING_LEVEL_GATE) as readonly ModelThinkingLevel[]
+
+/** The `compat.thinkingFormat` spellings pi-ai accepts on an `openai-completions` model. */
+type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>
+
+/**
+ * pi-ai thinking formats a profile cannot name: both drive the request through
+ * `chatTemplateKwargs`, which this configuration does not expose, so offering
+ * them would hand back a format with nothing to say.
+ */
+type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
+
+/** One reasoning-dispatch wire format a profile may name. */
+export type PiAiThinkingFormat = Exclude<PiThinkingFormat, WithheldThinkingFormat>
+
+/**
+ * The nameable reasoning-dispatch formats, most-reached first. The `Record`
+ * key type is a drift gate: a pi-ai upgrade that adds a format (0.84 added
+ * `baseten`) fails compilation here until the format is classified as offered
+ * here or withheld above, so the offer never silently lags the upstream set.
+ */
+const THINKING_FORMAT_GATE: Record<PiAiThinkingFormat, true> = {
+  'openai': true,
+  'deepseek': true,
+  'openrouter': true,
+  'together': true,
+  'zai': true,
+  'qwen': true,
+  'string-thinking': true,
+  'ant-ling': true,
+}
+
+/** Reasoning-dispatch wire formats a profile may name, most-reached first. */
+export const SUPPORTED_THINKING_FORMATS = Object.keys(THINKING_FORMAT_GATE) as readonly PiAiThinkingFormat[]
+
 let providerIndex: Map<string, Provider> | undefined
 
 /**
@@ -71,6 +131,32 @@ export function catalogModels(provider: string): Map<string, Model<Api>> {
   return new Map(models.map(model => [model.id, model]))
 }
 
+/**
+ * Selectable reasoning efforts for one model: each key is a level the model
+ * offers (and selectors show), and its value is the wire spelling dispatch
+ * sends for it. `off` alone may leave its value empty — "supported, send
+ * nothing" — because for most providers not thinking is the parameter's
+ * absence; every other declared level must name a wire value. A level absent
+ * from the dict is not offered.
+ */
+export type PiAiReasoningEfforts = Partial<Record<ModelThinkingLevel, string | null>>
+
+/**
+ * Reasoning-dispatch compatibility switches, set on the route (its models'
+ * default) or per model (winning over the route). Only the switches pi-ai's
+ * reasoning dispatch reads are offered; the rest of pi-ai's compat surface
+ * keeps its baseURL-derived auto-detection. pi-ai types both fields only on
+ * `OpenAICompletionsCompat` — the other wire protocols carry their reasoning
+ * shape in the protocol itself — so resolution rejects a model-level switch
+ * anywhere else, while a route-level default skips past models it cannot fit.
+ */
+export interface PiAiCompatProfile {
+  /** Reasoning parameter shape the endpoint expects; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+  thinkingFormat?: PiAiThinkingFormat
+  /** Whether the endpoint accepts `reasoning_effort`; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+  supportsReasoningEffort?: boolean
+}
+
 /** One configured model entry: an id plus the catalog fields it overrides. */
 export interface PiAiModelProfile {
   /** Model id sent to the provider and accepted by {@link GenerateOptions.model}. */
@@ -86,6 +172,16 @@ export interface PiAiModelProfile {
    * default on its own.
    */
   maxTokens?: number
+  /**
+   * Selectable reasoning efforts. Absent inherits the installed catalog
+   * entry's capability (a hand-declared model has none and does not reason);
+   * `false` declares a non-reasoning model, which is how a profile strips
+   * reasoning from a catalog model its gateway cannot serve; a non-empty dict
+   * declares the offered levels and their wire spellings.
+   */
+  reasoningEfforts?: false | PiAiReasoningEfforts
+  /** Reasoning-dispatch switches for this model, winning over the route's. */
+  compat?: PiAiCompatProfile
 }
 
 /** The route-level facts model materialization reads. */
@@ -98,6 +194,8 @@ export interface RouteCatalogRequest {
   baseURL?: string
   /** Configured catalog; absent means the whole installed catalog for this route. */
   models?: readonly PiAiModelProfile[]
+  /** Reasoning-dispatch switches for every `openai-completions` model on the route; entries override per field. */
+  compat?: PiAiCompatProfile
   /** Context capacity for a model neither the entry nor the catalog sizes. */
   defaultContextWindow: number
   /** Output capability for a model neither the entry nor the catalog sizes. */
@@ -123,6 +221,133 @@ function sharedCatalogApi(defaults: ReadonlyMap<string, Model<Api>>): string | u
   return apis.size === 1 ? [...apis][0] : undefined
 }
 
+/** The reasoning fields one materialized model carries. */
+interface ModelReasoning {
+  /** Whether the model reasons at all; `false` makes pi-ai ignore the map. */
+  reasoning: boolean
+  /** The map dispatch reads; absent only when the installed entry's (or none) applies. */
+  thinkingLevelMap?: ThinkingLevelMap
+}
+
+/**
+ * Resolve one model's reasoning capability from its declared efforts.
+ *
+ * A declared dict translates to pi-ai's `thinkingLevelMap` with every level
+ * decided explicitly: declared levels carry their wire spelling, undeclared
+ * levels are pinned to `null` (unsupported). Pinning matters because pi-ai's
+ * own defaulting is asymmetric — an absent key means "supported" for the five
+ * base levels but "unsupported" for `xhigh`/`max` — and a profile author
+ * should not need to know that. A declared `off` with no value is the one
+ * exception: it stays absent from the map, which pi-ai reads as "supported,
+ * send nothing" — the correct dispatch where not thinking is the parameter's
+ * absence — while `off` with a value sends that value.
+ * @param provider - provider route key, for diagnostics.
+ * @param entry - the configured model entry.
+ * @param base - the installed catalog entry of the same id, when one exists.
+ * @returns the reasoning fields the materialized model carries.
+ */
+function resolveModelReasoning(
+  provider: string,
+  entry: PiAiModelProfile,
+  base: Model<Api> | undefined,
+): ModelReasoning {
+  const efforts = entry.reasoningEfforts
+  if (efforts === undefined) {
+    // Reasoning rides the installed entry or is absent: a bare capability flag
+    // would make pi-ai advertise effort levels with no `thinkingLevelMap` to
+    // spell them, and no listing endpoint reports a model's reasoning
+    // protocol. The entry's map (when any) arrives through the `...base`
+    // spread in the model literal.
+    return { reasoning: base?.reasoning ?? false }
+  }
+  // The installed entry's map may ride along through `...base`; pi-ai never
+  // reads it on a non-reasoning model, so stripping it is not worth a field
+  // enumeration here.
+  if (efforts === false) return { reasoning: false }
+  // A YAML `reasoningEfforts:` left valueless arrives as null through the
+  // schema union — outside the field's declared type, hence the widening —
+  // while an explicit `{}` arrives as an empty dict. Both declare nothing,
+  // and neither is a spelling of "inherit" or "disable".
+  if ((efforts as unknown) === null || Object.keys(efforts).length === 0) {
+    invalid(provider, `model "${entry.id}" has an empty reasoningEfforts; declare the offered levels, set`
+      + ' false for a non-reasoning model, or omit the field to keep the installed catalog\'s capability')
+  }
+  const declared = THINKING_LEVELS.flatMap((level) => {
+    const wire = efforts[level]
+    return wire === undefined ? [] : [[level, wire] as const]
+  })
+  for (const [level, wire] of declared) {
+    if (wire === null) {
+      if (level !== 'off') {
+        invalid(provider, `model "${entry.id}" reasoningEfforts.${level} needs the wire value dispatch`
+          + ' should send; only "off" may leave it empty')
+      }
+    } else if (wire.length === 0) {
+      invalid(provider, `model "${entry.id}" reasoningEfforts.${level} must not be an empty string`)
+    }
+  }
+  if (!declared.some(([level]) => level !== 'off')) {
+    invalid(provider, `model "${entry.id}" reasoningEfforts offers no level beyond "off"; declare a thinking`
+      + ' level, or set reasoningEfforts to false for a non-reasoning model')
+  }
+  const map: ThinkingLevelMap = {}
+  for (const level of THINKING_LEVELS) {
+    const wire = efforts[level]
+    if (wire === undefined) {
+      map[level] = null
+    } else if (wire !== null) {
+      map[level] = wire
+    }
+  }
+  return { reasoning: true, thinkingLevelMap: map }
+}
+
+/**
+ * Resolve one model's compat block from the profile's reasoning switches.
+ *
+ * A model switch wins over the route switch; whatever neither sets keeps the
+ * installed entry's value, and a field no layer decides falls through to
+ * pi-ai's baseURL-derived detection. Only an `openai-completions` model takes
+ * the switches at all: a model-level switch on any other protocol fails
+ * resolution, while a route-level default skips past such models — the same
+ * posture as the route-level `reasoning` default, which also must not fail
+ * models it does not fit.
+ * @param provider - provider route key, for diagnostics.
+ * @param entry - the configured model entry.
+ * @param route - the route-level switches, when any.
+ * @param base - the installed catalog entry of the same id, when one exists.
+ * @param api - the model's resolved wire protocol.
+ * @returns a `compat` field to spread into the model, or nothing.
+ */
+function resolveModelCompat(
+  provider: string,
+  entry: PiAiModelProfile,
+  route: PiAiCompatProfile | undefined,
+  base: Model<Api> | undefined,
+  api: string,
+): { compat: OpenAICompletionsCompat } | Record<string, never> {
+  const thinkingFormat = entry.compat?.thinkingFormat ?? route?.thinkingFormat
+  const supportsReasoningEffort = entry.compat?.supportsReasoningEffort ?? route?.supportsReasoningEffort
+  if (thinkingFormat === undefined && supportsReasoningEffort === undefined) return {}
+  if (api !== 'openai-completions') {
+    if (entry.compat?.thinkingFormat !== undefined || entry.compat?.supportsReasoningEffort !== undefined) {
+      invalid(provider, `model "${entry.id}" sets compat reasoning switches, but its api is "${api}";`
+        + ' thinkingFormat and supportsReasoningEffort exist only on openai-completions')
+    }
+    return {}
+  }
+  // The installed entry's compat matches its own api, so on an
+  // openai-completions model it is the completions shape.
+  const inherited: OpenAICompletionsCompat | undefined = base?.compat
+  return {
+    compat: {
+      ...inherited,
+      ...thinkingFormat === undefined ? {} : { thinkingFormat },
+      ...supportsReasoningEffort === undefined ? {} : { supportsReasoningEffort },
+    },
+  }
+}
+
 /** One route's materialized catalog, plus the request caps its profile chose. */
 export interface RouteCatalog {
   /** The materialized models in configuration order. */
@@ -164,6 +389,8 @@ export function resolveRouteModels(request: RouteCatalogRequest): RouteCatalog {
       + ' must be listed in configuration')
   }
   const routeApi = sharedCatalogApi(defaults)
+  const routeCompatDefined = request.compat?.thinkingFormat !== undefined
+    || request.compat?.supportsReasoningEffort !== undefined
   const seen = new Set<string>()
   const configuredMaxTokens = new Map<string, number>()
   const models = entries.map((entry) => {
@@ -209,15 +436,17 @@ export function resolveRouteModels(request: RouteCatalogRequest): RouteCatalog {
       api,
       provider,
       baseUrl,
-      // Reasoning rides the installed entry or is absent: a bare boolean would
-      // make pi-ai advertise effort levels with no `thinkingLevelMap` to spell
-      // them, and no listing endpoint reports a model's reasoning protocol.
-      reasoning: base?.reasoning ?? false,
       input: base?.input ?? TEXT_ONLY,
       cost: base?.cost ?? NO_COST,
       contextWindow,
       maxTokens,
+      ...resolveModelReasoning(provider, entry, base),
+      ...resolveModelCompat(provider, entry, request.compat, base, api),
     }
   })
+  if (routeCompatDefined && !models.some(model => model.api === 'openai-completions')) {
+    invalid(provider, 'sets compat reasoning switches, but no model on the route speaks openai-completions;'
+      + ' thinkingFormat and supportsReasoningEffort exist only on that protocol')
+  }
   return { models, configuredMaxTokens }
 }
diff --git a/packages/llm/llm-pi-ai/src/config.ts b/packages/llm/llm-pi-ai/src/config.ts
index 7e8374ab9f..9d4cca089c 100644
--- a/packages/llm/llm-pi-ai/src/config.ts
+++ b/packages/llm/llm-pi-ai/src/config.ts
@@ -21,8 +21,8 @@ import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { normalizeApiKey, resolveRetryPolicy, RetryPolicySchema } from '@deepseek-ai/dsh-llm'
 import type { ResolvedRetryPolicy, RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
-import { resolveRouteModels } from './catalog.ts'
-import type { PiAiModelProfile } from './catalog.ts'
+import { resolveRouteModels, SUPPORTED_THINKING_FORMATS, THINKING_LEVELS } from './catalog.ts'
+import type { PiAiCompatProfile, PiAiModelProfile, PiAiReasoningEfforts } from './catalog.ts'
 import { buildProvider, supportedProtocols } from './provider.ts'
 
 /** Default maximum idle interval while an adapter stream read is outstanding. */
@@ -34,7 +34,7 @@ export const DEFAULT_CONTEXT_WINDOW = 262_144
 /** Output capability assumed for a model neither configuration nor the catalog sizes. */
 export const DEFAULT_MAX_TOKENS = 32_768
 
-export type { PiAiModelProfile } from './catalog.ts'
+export type { PiAiCompatProfile, PiAiModelProfile, PiAiReasoningEfforts, PiAiThinkingFormat } from './catalog.ts'
 
 /** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */
 export interface PiAiProviderProfile {
@@ -62,6 +62,13 @@ export interface PiAiProviderProfile {
    * unset fields from the installed model of the same id.
    */
   models?: PiAiModelProfile[]
+  /**
+   * Reasoning-dispatch switches for every `openai-completions` model on this
+   * route; each model's own `compat` overrides per field. What neither sets
+   * keeps the installed catalog entry's value, then pi-ai's baseURL-derived
+   * detection.
+   */
+  compat?: PiAiCompatProfile
   /**
    * Context capacity for a model this route lists that neither the entry nor
    * the installed catalog sizes (default 262,144). A guess by construction, so
@@ -139,11 +146,34 @@ const thinkingBudgets = z.object({
   high: z.number(),
 })
 
+const compatProfile: z<PiAiCompatProfile> = z.object({
+  thinkingFormat: z.union(SUPPORTED_THINKING_FORMATS),
+  supportsReasoningEffort: z.boolean(),
+})
+
+/**
+ * Keys are the offered levels, values their wire spellings. `z.const(null)`
+ * keeps a valueless key (`off:`) alive through validation — only resolution
+ * decides which levels may leave the value empty, so the diagnostic can name
+ * the route and model. The assertion narrows schemastery's `Dict`, which
+ * types every literal key as required; dict validation is per-present-key, so
+ * the runtime shape is the partial record.
+ */
+const reasoningEfforts = z.dict(
+  z.union([z.string(), z.const(null)]),
+  z.union(THINKING_LEVELS),
+) as unknown as z<PiAiReasoningEfforts>
+
 const modelProfile: z<PiAiModelProfile> = z.object({
   id: z.string().required(),
   name: z.string(),
   contextWindow: z.number().step(1).min(1),
   maxTokens: z.number().step(1).min(1),
+  // The union, not a bare dict: schemastery materializes an absent dict as
+  // `{}`, and absent must stay distinguishable — it means "inherit the
+  // installed catalog's capability", while `false` disables reasoning.
+  reasoningEfforts: z.union([z.const(false), reasoningEfforts]),
+  compat: compatProfile,
 })
 
 const profile = z.object({
@@ -153,10 +183,11 @@ const profile = z.object({
   api: z.union(supportedProtocols()),
   baseURL: z.string(),
   models: z.array(modelProfile),
+  compat: compatProfile,
   defaultContextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
   defaultMaxTokens: z.number().step(1).min(1).default(DEFAULT_MAX_TOKENS),
   headers: z.dict(z.string()),
-  reasoning: z.union(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']),
+  reasoning: z.union(THINKING_LEVELS),
   thinkingBudgets,
   cacheRetention: z.union(['none', 'short', 'long']),
   transport: z.union(['sse', 'websocket', 'websocket-cached', 'auto']),
@@ -260,6 +291,7 @@ export function resolveProfiles(
       ...source.api === undefined ? {} : { api: source.api },
       ...source.baseURL === undefined ? {} : { baseURL: source.baseURL },
       ...source.models === undefined ? {} : { models: source.models },
+      ...source.compat === undefined ? {} : { compat: source.compat },
       defaultContextWindow: source.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
       defaultMaxTokens: source.defaultMaxTokens ?? DEFAULT_MAX_TOKENS,
     })
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index 2f98d7ac70..ea81f66fec 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -32,11 +32,24 @@
  *         apiKeyEnv: ACME_GATEWAY_API_KEY
  *         api: openai-completions
  *         baseURL: https://gateway.acme.example/v1
+ *         # Reasoning dialect for a URL pi-ai cannot recognize.
+ *         compat:
+ *           thinkingFormat: deepseek
  *         models:
  *           - id: acme-large
  *             name: Acme Large
  *             contextWindow: 65536
  *             maxTokens: 4096
+ *           - id: acme-think
+ *             name: Acme Think
+ *             contextWindow: 262144
+ *             maxTokens: 32768
+ *             # key = selectable level, value = wire spelling; only off may
+ *             # leave the value empty (supported, send nothing).
+ *             reasoningEfforts:
+ *               off:
+ *               high: high
+ *               max: ultra
  * ```
  *
  * @module @deepseek-ai/dsh-llm-pi-ai
@@ -55,7 +68,14 @@ import { discoverModels } from './discovery.ts'
 export { PiAiAdapter } from './adapter.ts'
 export type { PiAiAdapterOptions } from './adapter.ts'
 export { Config } from './config.ts'
-export type { PiAiModelProfile, PiAiProviderProfile, ResolvedPiAiProviderProfile } from './config.ts'
+export type {
+  PiAiCompatProfile,
+  PiAiModelProfile,
+  PiAiProviderProfile,
+  PiAiReasoningEfforts,
+  PiAiThinkingFormat,
+  ResolvedPiAiProviderProfile,
+} from './config.ts'
 export { supportedProtocols } from './provider.ts'
 
 export const name = 'llm-pi-ai'
diff --git a/packages/llm/llm-pi-ai/tests/adapter.spec.ts b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
index 0184ca05cc..2d7798ff2e 100644
--- a/packages/llm/llm-pi-ai/tests/adapter.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
@@ -400,6 +400,149 @@ describe('provider profile lifecycle', () => {
       .resolves.toMatchObject({ reasoning: { defaultEffort: ReasoningEffortId('off') } })
   })
 
+  it('serves declared reasoning efforts to selectors and honours the profile default', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmPiAi, {
+      providers: {
+        'acme-gateway': {
+          apiKey: 'gw-key',
+          api: 'openai-completions',
+          baseURL: 'https://acme.test/v1',
+          reasoning: 'high',
+          models: [{
+            id: 'acme-think',
+            contextWindow: 65_536,
+            maxTokens: 4096,
+            reasoningEfforts: { off: null, low: 'low', high: 'high' },
+          }],
+        },
+      },
+    })
+
+    // Declared levels reach the same seam catalog metadata does, so the
+    // effort picker works for a model pi-ai has never heard of.
+    await expect(ctx.llm.resolveModelInfo('acme-gateway', 'acme-think')).resolves.toMatchObject({
+      reasoning: {
+        efforts: [
+          { id: ReasoningEffortId('off'), name: 'Off' },
+          { id: ReasoningEffortId('low'), name: 'Low' },
+          { id: ReasoningEffortId('high'), name: 'High' },
+        ],
+        defaultEffort: ReasoningEffortId('high'),
+      },
+    })
+  })
+
+  it('sends the declared wire spelling and refuses undeclared levels before network I/O', async () => {
+    const server = await mockServer([{ events: textEvents }])
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmPiAi, {
+      providers: {
+        'acme-gateway': {
+          apiKey: 'gw-key',
+          api: 'openai-completions',
+          baseURL: `${server.url}/v1`,
+          models: [{
+            id: 'acme-think',
+            contextWindow: 65_536,
+            maxTokens: 4096,
+            reasoningEfforts: { off: null, high: 'ultra' },
+          }],
+        },
+      },
+    })
+
+    await assemble(ctx, {
+      provider: 'acme-gateway',
+      model: 'acme-think',
+      reasoningEffort: ReasoningEffortId('high'),
+      messages: [],
+    })
+    // The declared value, not the canonical level name, goes on the wire.
+    expect(server.requests[0]).toMatchObject({ reasoning_effort: 'ultra' })
+
+    const undeclared = await assemble(ctx, {
+      provider: 'acme-gateway',
+      model: 'acme-think',
+      reasoningEffort: ReasoningEffortId('max'),
+      messages: [],
+    })
+    expect(undeclared.finish).toMatchObject({
+      kind: 'error',
+      failure: { code: 'UNSUPPORTED_REASONING_EFFORT' },
+    })
+    expect(server.requests).toHaveLength(1)
+  })
+
+  it('dispatches the compat-switched dialect on a declared route', async () => {
+    const server = await mockServer([{ events: textEvents }, { events: textEvents }])
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmPiAi, {
+      providers: {
+        'acme-gateway': {
+          apiKey: 'gw-key',
+          api: 'openai-completions',
+          baseURL: `${server.url}/v1`,
+          // Without the switch pi-ai guesses the dialect from the endpoint
+          // URL, and a private gateway's URL says nothing.
+          compat: { thinkingFormat: 'deepseek' },
+          models: [{
+            id: 'acme-think',
+            contextWindow: 65_536,
+            maxTokens: 4096,
+            reasoningEfforts: { off: null, high: 'high' },
+          }],
+        },
+      },
+    })
+    const prompt = (effort: string): Promise<unknown> => assemble(ctx, {
+      provider: 'acme-gateway',
+      model: 'acme-think',
+      reasoningEffort: ReasoningEffortId(effort),
+      messages: [],
+    })
+
+    await prompt('high')
+    expect(server.requests[0]).toMatchObject({ thinking: { type: 'enabled' }, reasoning_effort: 'high' })
+
+    await prompt('off')
+    expect(server.requests[1]).toMatchObject({ thinking: { type: 'disabled' } })
+    expect(server.requests[1]).not.toHaveProperty('reasoning_effort')
+  })
+
+  it('holds back reasoning_effort when the endpoint cannot take it', async () => {
+    const server = await mockServer([{ events: textEvents }])
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmPiAi, {
+      providers: {
+        'acme-gateway': {
+          apiKey: 'gw-key',
+          api: 'openai-completions',
+          baseURL: `${server.url}/v1`,
+          compat: { supportsReasoningEffort: false },
+          models: [{
+            id: 'acme-think',
+            contextWindow: 65_536,
+            maxTokens: 4096,
+            reasoningEfforts: { off: null, high: 'high' },
+          }],
+        },
+      },
+    })
+
+    await assemble(ctx, {
+      provider: 'acme-gateway',
+      model: 'acme-think',
+      reasoningEffort: ReasoningEffortId('high'),
+      messages: [],
+    })
+    expect(server.requests[0]).not.toHaveProperty('reasoning_effort')
+  })
+
   it('accepts absent credentials for pi-ai ambient authentication', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', 'ambient-key')
     const server = await mockServer([{ events: textEvents }])
diff --git a/packages/llm/llm-pi-ai/tests/catalog.spec.ts b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
index 2afbb87ec0..fbfcd653cf 100644
--- a/packages/llm/llm-pi-ai/tests/catalog.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
@@ -10,8 +10,8 @@ import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
 import { PiAiAdapter } from '@deepseek-ai/dsh-llm-pi-ai'
 import { getBuiltinModels } from '@earendil-works/pi-ai/providers/all'
-import { createModels } from '@earendil-works/pi-ai'
-import type { Api, Model, Provider } from '@earendil-works/pi-ai'
+import { createModels, getSupportedThinkingLevels } from '@earendil-works/pi-ai'
+import type { Api, Model, OpenAICompletionsCompat, Provider } from '@earendil-works/pi-ai'
 import { resolveProfiles } from '../src/config.ts'
 import { buildProvider, supportedProtocols } from '../src/provider.ts'
 import { assemble } from './assemble.ts'
@@ -475,6 +475,177 @@ describe('catalog routes with per-model configuration', () => {
   })
 })
 
+describe('per-model reasoning efforts', () => {
+  /** One hand-declared route holding exactly the given models. */
+  function declared(models: LlmPiAi.PiAiModelProfile[]): Record<string, LlmPiAi.PiAiProviderProfile> {
+    return { 'acme-gateway': { api: 'openai-completions', baseURL: 'https://acme.test', models } }
+  }
+
+  /** The first materialized model of one route, or throw. */
+  function modelOf(providers: Record<string, LlmPiAi.PiAiProviderProfile>, route = 'acme-gateway'): Model<Api> {
+    const [model] = resolveProfiles(providers).get(route)?.piProvider.getModels() ?? []
+    if (model === undefined) throw new Error(`route "${route}" resolved no models`)
+    return model
+  }
+
+  it('declares selectable levels with their wire spellings on a hand-declared model', () => {
+    const model = modelOf(declared([{
+      id: 'acme-think',
+      reasoningEfforts: { off: null, low: 'low', high: 'high', max: 'ultra' },
+    }]))
+
+    expect(model.reasoning).toBe(true)
+    // Undeclared levels are pinned null rather than left to pi-ai's own
+    // defaulting, which is asymmetric: an absent key means "supported" for the
+    // five base levels but "unsupported" for xhigh/max. A profile author
+    // should not need to know that. Declared `off` with no value stays absent
+    // from the map — supported, send nothing.
+    expect(model.thinkingLevelMap).toEqual({
+      minimal: null,
+      medium: null,
+      xhigh: null,
+      low: 'low',
+      high: 'high',
+      max: 'ultra',
+    })
+    expect(getSupportedThinkingLevels(model)).toEqual(['off', 'low', 'high', 'max'])
+  })
+
+  it('sends a declared off value on the wire instead of omitting the parameter', () => {
+    const model = modelOf(declared([{ id: 'm', reasoningEfforts: { off: 'none', high: 'high' } }]))
+    expect(model.thinkingLevelMap?.off).toBe('none')
+    expect(getSupportedThinkingLevels(model)).toEqual(['off', 'high'])
+  })
+
+  it('offers exactly the declared keys: leaving off out makes thinking mandatory', () => {
+    const model = modelOf(declared([{ id: 'm', reasoningEfforts: { high: 'high' } }]))
+    expect(getSupportedThinkingLevels(model)).toEqual(['high'])
+  })
+
+  it('narrows a catalog model’s levels in place', () => {
+    const [catalogModel] = getBuiltinModels('deepseek')
+    if (catalogModel === undefined) throw new Error('the installed catalog ships no deepseek model')
+    expect(getSupportedThinkingLevels(catalogModel as Model<Api>)).toEqual(['off', 'high', 'max'])
+
+    const model = modelOf({
+      deepseek: { models: [{ id: catalogModel.id, reasoningEfforts: { off: null, high: 'high' } }] },
+    }, 'deepseek')
+
+    expect(getSupportedThinkingLevels(model)).toEqual(['off', 'high'])
+    // Only the reasoning fields change; identity and capacities stay catalog.
+    expect(model.name).toBe(catalogModel.name)
+    expect(model.contextWindow).toBe(catalogModel.contextWindow)
+  })
+
+  it('strips reasoning from a catalog model with false', () => {
+    const [catalogModel] = getBuiltinModels('deepseek')
+    if (catalogModel === undefined) throw new Error('the installed catalog ships no deepseek model')
+    expect(catalogModel.reasoning).toBe(true)
+
+    const model = modelOf({ deepseek: { models: [{ id: catalogModel.id, reasoningEfforts: false }] } }, 'deepseek')
+
+    expect(model.reasoning).toBe(false)
+    expect(getSupportedThinkingLevels(model)).toEqual(['off'])
+  })
+
+  it('inherits the catalog capability when the field is absent', () => {
+    const [catalogModel] = getBuiltinModels('deepseek')
+    if (catalogModel === undefined) throw new Error('the installed catalog ships no deepseek model')
+
+    const model = modelOf({ deepseek: { models: [{ id: catalogModel.id }] } }, 'deepseek')
+
+    expect(model.reasoning).toBe(catalogModel.reasoning)
+    expect(model.thinkingLevelMap).toEqual(catalogModel.thinkingLevelMap)
+  })
+
+  it('rejects a declaration that offers nothing or spells a level it cannot send', () => {
+    const declare = (efforts: NonNullable<LlmPiAi.PiAiModelProfile['reasoningEfforts']>): (() => unknown) =>
+      () => resolveProfiles(declared([{ id: 'm', reasoningEfforts: efforts }]))
+
+    expect(declare({})).toThrow(/empty reasoningEfforts/)
+    // A YAML `reasoningEfforts:` left valueless arrives as null through the
+    // schema union; it declares nothing and is not a spelling of "inherit".
+    expect(declare(null as never)).toThrow(/empty reasoningEfforts/)
+    expect(declare({ off: null })).toThrow(/offers no level beyond "off"/)
+    expect(declare({ off: 'none' })).toThrow(/offers no level beyond "off"/)
+    expect(declare({ high: null })).toThrow(/only "off" may leave it empty/)
+    expect(declare({ high: '' })).toThrow(/must not be an empty string/)
+  })
+})
+
+describe('reasoning-dispatch compat switches', () => {
+  /** The materialized models of one route, keyed by id. */
+  function modelsOf(providers: Record<string, LlmPiAi.PiAiProviderProfile>, route: string): Map<string, Model<Api>> {
+    const models = resolveProfiles(providers).get(route)?.piProvider.getModels() ?? []
+    return new Map(models.map(model => [model.id, model]))
+  }
+
+  it('applies route switches to every openai-completions model, entries winning per field', () => {
+    const models = modelsOf({
+      'acme-gateway': {
+        api: 'openai-completions',
+        baseURL: 'https://acme.test',
+        compat: { thinkingFormat: 'deepseek' },
+        models: [
+          { id: 'dialect-default', reasoningEfforts: { off: null, high: 'high' } },
+          { id: 'dialect-odd', compat: { thinkingFormat: 'openai', supportsReasoningEffort: false } },
+        ],
+      },
+    }, 'acme-gateway')
+
+    expect(models.get('dialect-default')?.compat).toEqual({ thinkingFormat: 'deepseek' })
+    expect(models.get('dialect-odd')?.compat).toEqual({ thinkingFormat: 'openai', supportsReasoningEffort: false })
+  })
+
+  it('merges the switches over the catalog entry’s own compat instead of replacing it', () => {
+    const [catalogModel] = getBuiltinModels('deepseek')
+    if (catalogModel === undefined) throw new Error('the installed catalog ships no deepseek model')
+    const inherited = catalogModel.compat as OpenAICompletionsCompat
+    expect(inherited.requiresReasoningContentOnAssistantMessages).toBe(true)
+
+    const models = modelsOf({
+      deepseek: { models: [{ id: catalogModel.id, compat: { thinkingFormat: 'openai' } }] },
+    }, 'deepseek')
+
+    // The one switched field changes; the catalog's other quirks survive,
+    // because configuration has no way to restate them.
+    expect(models.get(catalogModel.id)?.compat).toEqual({ ...inherited, thinkingFormat: 'openai' })
+  })
+
+  it('skips models of other protocols on a mixed route instead of failing them', () => {
+    // xai ships both completions and responses models, so a route-level switch
+    // must land on the former without invalidating the latter.
+    const catalog = getBuiltinModels('xai') as readonly Model<Api>[]
+    const completions = catalog.find(model => model.api === 'openai-completions')
+    const responses = catalog.find(model => model.api === 'openai-responses')
+    if (completions === undefined || responses === undefined) throw new Error('xai no longer ships a mixed catalog')
+
+    const models = modelsOf({
+      xai: {
+        compat: { supportsReasoningEffort: false },
+        models: [{ id: completions.id }, { id: responses.id }],
+      },
+    }, 'xai')
+
+    expect((models.get(completions.id)?.compat as OpenAICompletionsCompat).supportsReasoningEffort).toBe(false)
+    expect(models.get(responses.id)?.compat).toEqual(responses.compat)
+  })
+
+  it('rejects a model-level switch on a protocol that has no such field', () => {
+    expect(() => resolveProfiles({
+      anthropic: {
+        models: [{ id: 'claude-sonnet-4-5', compat: { thinkingFormat: 'openai' } }],
+      },
+    })).toThrow(/exist only on openai-completions/)
+  })
+
+  it('rejects route switches no model on the route can take', () => {
+    expect(() => resolveProfiles({
+      anthropic: { compat: { thinkingFormat: 'openai' } },
+    })).toThrow(/no model on the route speaks openai-completions/)
+  })
+})
+
 describe('resolution snapshots', () => {
   it('finishes an in-flight request under the configuration it started with', async () => {
     const server = await mockServer([{ events: textEvents }])
diff --git a/packages/llm/llm-pi-ai/tests/config.spec.ts b/packages/llm/llm-pi-ai/tests/config.spec.ts
index 90f8487ad8..5d041c1562 100644
--- a/packages/llm/llm-pi-ai/tests/config.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/config.spec.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { resolveProfiles } from '../src/config.ts'
+import { Config, resolveProfiles } from '../src/config.ts'
 
 describe('API key format', () => {
   it('trims a padded literal apiKey into the resolved profile', () => {
@@ -22,3 +22,33 @@ describe('API key format', () => {
       .toThrow(/no HTTP header can carry/)
   })
 })
+
+describe('reasoning schema boundary', () => {
+  const configWith = (model: Record<string, unknown>): (() => unknown) =>
+    () => Config({
+      providers: {
+        'acme-gateway': {
+          api: 'openai-completions',
+          baseURL: 'https://acme.test',
+          models: [{ id: 'm', ...model }],
+        },
+      },
+    })
+
+  it('rejects a level pi-ai does not know at the write that produced it', () => {
+    expect(configWith({ reasoningEfforts: { ultra: 'x' } })).toThrow(/"off"/)
+    expect(configWith({ reasoningEfforts: { high: 42 } })).toThrow()
+  })
+
+  it('keeps false distinguishable from an absent declaration', () => {
+    type Materialized = { providers: Record<string, { models?: { reasoningEfforts?: unknown }[] }> }
+    const withFalse = configWith({ reasoningEfforts: false })() as Materialized
+    expect(withFalse.providers['acme-gateway']?.models?.[0]?.reasoningEfforts).toBe(false)
+    const absent = configWith({})() as Materialized
+    expect(absent.providers['acme-gateway']?.models?.[0]?.reasoningEfforts).toBeUndefined()
+  })
+
+  it('rejects a thinking format outside the offered set', () => {
+    expect(configWith({ compat: { thinkingFormat: 'quantum' } })).toThrow(/expected/)
+  })
+})
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 6884839536..0d87ec1fb7 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -10,6 +10,7 @@
   "include": [
     "apps/web/tests/scaffold.ts",
     "apps/web/tests/default-model.e2e.ts",
+    "apps/web/tests/declared-reasoning.e2e.ts",
     "apps/web/tests/support.ts",
     "apps/web/tests/scaffold-hermetic.e2e.ts",
     "apps/web/tests/core-web-profile.snapshot.ts",

From cc0f6e11b9e108c42fd9619bfd115863e937ef5f Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 00:55:37 +0800
Subject: [PATCH 179/516] feat(tool-skill): teach the catalog about
 user-explicit skill injection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both catalog renderings now tell the model that a directly invoked skill
arrives as an inline <skill_content> block to follow without re-loading it
through the skill tool — the seam rule that keeps the user-explicit path
and the model-autonomous path from double-injecting one skill.
---
 examples/acp-agent/tests/snapshots/skill-load/session.jsonl | 2 +-
 packages/skill/tool-skill/src/index.ts                      | 2 ++
 packages/skill/tool-skill/tests/tool-skill.spec.ts          | 1 +
 3 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/examples/acp-agent/tests/snapshots/skill-load/session.jsonl b/examples/acp-agent/tests/snapshots/skill-load/session.jsonl
index f30dc715cf..ec369b492a 100644
--- a/examples/acp-agent/tests/snapshots/skill-load/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/skill-load/session.jsonl
@@ -5,7 +5,7 @@
 {"type":"step/start","seq":3,"time":1785498773754,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":4,"time":1785498773754,"data":{"content":[{"type":"text","text":"Load the snapshot-skill skill with the skill tool, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"0ca31b92-27ac-451d-98d3-d1e5f605454b"},"surfaceOp":"append"}
 {"type":"user/message","seq":5,"time":1785498773755,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"3fc7e2f8-90fc-496c-b516-700cef1d86f1"},"surfaceOp":"append"}
-{"type":"user/message","seq":6,"time":1785730426818,"data":{"content":[{"type":"text","text":"<system-reminder>\nA skill is a reusable set of task-specific instructions. The following skills are available in this session:\n\n<available_skills>\n- `model-only-skill`: Prove user-disabled skills remain available to the model.\n- `snapshot-skill`: Exercise project skill discovery and loading in snapshot tests.\n</available_skills>\n\nIf the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.\n</system-reminder>"}],"source":{"kind":"skill-catalog","form":"catalog","entries":[{"name":"model-only-skill","description":"Prove user-disabled skills remain available to the model."},{"name":"snapshot-skill","description":"Exercise project skill discovery and loading in snapshot tests."}]},"role":"user","id":"60880315-9799-44c8-8a99-e6fe9ee5bdc5"},"surfaceOp":"append"}
+{"type":"user/message","seq":6,"time":1785730426818,"data":{"content":[{"type":"text","text":"<system-reminder>\nA skill is a reusable set of task-specific instructions. The following skills are available in this session:\n\n<available_skills>\n- `model-only-skill`: Prove user-disabled skills remain available to the model.\n- `snapshot-skill`: Exercise project skill discovery and loading in snapshot tests.\n</available_skills>\n\nIf the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.\nA user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.\n</system-reminder>"}],"source":{"kind":"skill-catalog","form":"catalog","entries":[{"name":"model-only-skill","description":"Prove user-disabled skills remain available to the model."},{"name":"snapshot-skill","description":"Exercise project skill discovery and loading in snapshot tests."}]},"role":"user","id":"60880315-9799-44c8-8a99-e6fe9ee5bdc5"},"surfaceOp":"append"}
 {"type":"session/title","seq":7,"time":1785730426818,"data":{"title":"Load the snapshot-skill skill with","messageSeqs":[4],"source":{"kind":"fallback"}}}
 {"type":"request/header","seq":8,"time":1785498773756,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
 {"type":"request/context","seq":9,"time":1785730426819,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts
index 19e154143d..aa9b509206 100644
--- a/packages/skill/tool-skill/src/index.ts
+++ b/packages/skill/tool-skill/src/index.ts
@@ -217,6 +217,7 @@ function renderCatalogMessage(entries: SkillCatalogSource['entries']): UserMessa
         '</available_skills>',
         '',
         "If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.",
+        'A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.',
         '</system-reminder>',
       ].join('\n'),
     }],
@@ -235,6 +236,7 @@ function renderCatalogUpdate(entries: SkillCatalogSource['entries']): UserMessag
     ]
     : [
       'Use only names in this replacement catalog. If the user names a listed skill, or the task clearly matches its description, call the `skill` tool with the exact name before acting.',
+      'A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.',
     ]
   return createUserMessage({
     content: [{
diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts
index 0755e398a0..9543c196af 100644
--- a/packages/skill/tool-skill/tests/tool-skill.spec.ts
+++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts
@@ -287,6 +287,7 @@ describe('dsh-tool-skill', () => {
             '</available_skills>',
             '',
             "If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.",
+            'A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.',
             '</system-reminder>',
           ].join('\n'),
         }],

From 756304322a22400e651f5be7ba1ccd294dd77ad7 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 00:57:41 +0800
Subject: [PATCH 180/516] feat(llm-pi-ai): modelOverrides reshapes catalog
 models without replacing the catalog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A route's modelOverrides dict customizes individual installed-catalog
models — key = catalog model id, value = the same fields a models entry
takes — while the rest of the catalog keeps serving, which a models list
cannot express because declaring one replaces the served set. An
override becomes the catalog entry's configuration and resolves through
the existing entry path, so capacities, reasoningEfforts, compat, and
request-default semantics are identical to a models entry's. Unlike
Pi's config layer, which ignores unknown ids, every override that lands
nowhere is refused at the write that produced it: beside a models list,
on a hand-declared route, naming a model the catalog does not describe,
or smuggling an id through the schema's unknown-key tolerance.
---
 packages/llm/llm-pi-ai/README.i18n.yaml      |  4 +-
 packages/llm/llm-pi-ai/README.md             | 13 +++-
 packages/llm/llm-pi-ai/README.zh.md          | 13 +++-
 packages/llm/llm-pi-ai/src/catalog.ts        | 39 ++++++++++-
 packages/llm/llm-pi-ai/src/config.ts         | 30 ++++++++-
 packages/llm/llm-pi-ai/src/index.ts          |  1 +
 packages/llm/llm-pi-ai/tests/catalog.spec.ts | 71 ++++++++++++++++++++
 7 files changed, 164 insertions(+), 7 deletions(-)

diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 69efba1977..c8ae1899bd 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: 894aecc720f0a7616c0127d439b41129d94ef667
-README.zh.md: 63464f80ee3036ddec3fb6828ecccc68c5524478
+README.md: f208f553ab3a1f80c5b71f4792e5fc80459f9fa5
+README.zh.md: 24ae4b0e2021eeea373eacb8cc1dfc39063fee8b
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index 894aecc720..f208f553ab 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -35,6 +35,15 @@ Configure credentials, the model catalog, and deployment-specific transport sett
         models:
           - id: claude-sonnet-4-5
             contextWindow: 200000
+      # Catalog route with one model reshaped in place; the rest of the
+      # catalog keeps serving (a models list would replace it instead).
+      deepseek:
+        apiKeyEnv: DEEPSEEK_API_KEY
+        modelOverrides:
+          deepseek-v4-pro:
+            reasoningEfforts:
+              off:
+              high: high
       # Hand-declared route: pi-ai ships nothing under this key, so the profile
       # supplies the whole provider.
       acme-gateway:
@@ -68,6 +77,8 @@ The dict shape makes duplicate routes unrepresentable, and the pre-release array
 
 A profile's `models` list *replaces* the route's installed catalog rather than extending it; omitting it (or leaving it empty) serves that catalog unchanged. Each entry defaults its unset fields from the installed model of the same `id`, so narrowing a catalog route to two models, correcting one capacity, or adding a model newer than the installed catalog are all one-line edits — but declaring any `models` list means every model the route should keep serving must appear in it, an entry of nothing but `id` being enough. The configurable entry fields are `id`, `name`, `contextWindow`, `maxTokens`, `reasoningEfforts`, and `compat`. Pricing and input modalities have no harness consumer and ride the installed entry or are absent.
 
+`modelOverrides` reshapes individual installed-catalog models without that cost: each key is a catalog model id, each value the same fields a `models` entry takes with the id living in the key, and the rest of the catalog keeps serving untouched — "correct one model, keep the other thirty-seven" as a three-line edit. An override becomes that catalog entry's configuration, so capacities, efforts, and compat resolve through the same path with the same diagnostics and the same request-default semantics as a `models` entry. Overrides are only meaningful on a catalog route serving its catalog: one set beside a `models` list (which already replaces the catalog), on a hand-declared route (whose models are fully spelled in `models`), or naming a model the catalog does not describe is refused rather than skipped, because a silently unchanged model is a typo someone would otherwise hunt for.
+
 ### Per-model reasoning efforts
 
 `reasoningEfforts` declares a model's selectable thinking levels: each key is a level selectors offer, its value the spelling dispatch sends on the wire, so `high: high` passes the canonical name through while `max: ultra` renames it for a gateway with its own vocabulary. Keys come from pi-ai's level set (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`); a level not declared is not offered. Omitting the field keeps the installed catalog entry's capability (a hand-declared model has none and does not reason); `false` declares a non-reasoning model, which is how a profile strips reasoning from a catalog model its gateway cannot serve; an empty declaration is refused rather than guessing between those two meanings.
@@ -98,7 +109,7 @@ A model that carries reasoning metadata — from the installed catalog or from i
 
 A model **without** that metadata — a hand-declared one whose entry declares no `reasoningEfforts`, and a catalog model pi-ai marks as non-reasoning — exposes no `reasoning` at all. pi-ai reports such a model as supporting the single level `off`, but `off` is translated to *omitting* the reasoning option, which is byte-for-byte the request that naming no effort already produces: selecting it could not disable anything, so a provider whose own default is to think would keep thinking with `off` shown as selected. Reporting the capability as unavailable leaves a surface offering the provider's default and nothing that misrepresents it. The profile `reasoning` value, including `off`, is the deployment default when configured; omitting it preserves the provider default. Per-request `GenerateOptions.reasoningEffort` takes precedence, and a level absent from the exact model capability fails the REQUEST with `UNSUPPORTED_REASONING_EFFORT` before network I/O instead of being clamped. Describing a model never fails that way: the models under one provider disagree about which levels they accept, so `resolveModel` reports a profile level the exact model cannot take as no default at all rather than throwing. A throw there would take the whole provider out of every model catalog built over it — one mis-set profile field hiding even the models that do support the level — so a bad configuration surfaces where it is acted on, not where it is described. pi-ai's common stream options represent `off` by omitting `reasoning`.
 
-Supported profile fields are `apiKey`, `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `compat`, `defaultContextWindow`, `defaultMaxTokens`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
+Supported profile fields are `apiKey`, `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `modelOverrides`, `compat`, `defaultContextWindow`, `defaultMaxTokens`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
 
 The adapter forces pi-ai's SDK `maxRetries` to zero so one `stream()` call makes one provider request. The removed profile fields `maxRetries` and `maxRetryDelayMs` fail load instead of silently multiplying or hiding the separately composed agent-level retry budget. Idle expiry aborts the SDK's stable request signal and surfaces `TIMEOUT`; an earlier caller abort remains `ABORTED`.
 
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index 63464f80ee..24ae4b0e20 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -35,6 +35,15 @@
         models:
           - id: claude-sonnet-4-5
             contextWindow: 200000
+      # Catalog route with one model reshaped in place; the rest of the
+      # catalog keeps serving (a models list would replace it instead).
+      deepseek:
+        apiKeyEnv: DEEPSEEK_API_KEY
+        modelOverrides:
+          deepseek-v4-pro:
+            reasoningEfforts:
+              off:
+              high: high
       # Hand-declared route: pi-ai ships nothing under this key, so the profile
       # supplies the whole provider.
       acme-gateway:
@@ -68,6 +77,8 @@
 
 profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩充它；省略它（或留空）则原样服务该 catalog。每个条目都会从同 `id` 的已安装模型继承自身未设置的字段，因此把 catalog 路由收窄到两个模型、更正某个容量，或加入一个比已安装 catalog 更新的模型，都是一行编辑——但一旦声明了 `models` 列表，该路由要继续服务的每个模型就都必须出现在其中，条目哪怕只写一个 `id` 也足够。可配置的条目字段是 `id`、`name`、`contextWindow`、`maxTokens`、`reasoningEfforts` 与 `compat`。定价与输入模态没有 harness 消费方，因此沿用已安装条目或直接缺席。
 
+`modelOverrides` 无需这份代价就能就地重塑单个已安装 catalog 模型：每个键是一个 catalog 模型 id，每个值可写 `models` 条目接受的同一批字段，只是 id 落在键上，而 catalog 的其余部分原样继续服务——「改一个模型、其余三十七个原样保留」只是一次三行编辑。一条覆盖会成为该 catalog 条目的配置，因此容量、档位与 compat 沿与 `models` 条目相同的路径解析，携带相同的诊断与相同的请求默认值语义。覆盖只在正服务自身 catalog 的 catalog 路由上才有意义：与 `models` 列表并存的一份（该列表本就替换了 catalog）、落在手工声明路由上的一份（其模型已在 `models` 中完整写出），或点名了 catalog 未描述模型的一份，都会被拒绝而非跳过，因为一个静默保持原样的模型，就是一个否则要有人费力追查的笔误。
+
 ### 按模型的推理档位
 
 `reasoningEfforts` 声明模型可选的思考级别：每个键是选择器提供的一个档位，其值是分派在协议中发送的拼写，因此 `high: high` 原样透传规范名称，而 `max: ultra` 则为使用自有词汇的网关改名。键取自 pi-ai 的档位集合（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`）；未声明的档位不会被提供。省略该字段会保留已安装 catalog 条目的能力（手工声明的模型没有这份能力，也不推理）；`false` 声明一个不具备推理能力的模型，profile 正是以此从其网关无法服务的 catalog 模型上剥除推理；空声明会被拒绝，而不是在这两种含义之间去猜。
@@ -98,7 +109,7 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 **没有**这份元数据的模型——条目未声明 `reasoningEfforts` 的手工声明模型，以及 pi-ai 标记为不具备推理能力的 catalog 模型——完全不公开 `reasoning`。pi-ai 会把这类模型报告为只支持 `off` 一档，但 `off` 会被翻译成*省略* reasoning 选项，而那与「不点名任何档位」产出的请求逐字节相同：选它关不掉任何东西，于是自身默认就在思考的提供方，会在界面显示 `off` 被选中的同时继续思考。把该能力报告为不可用，界面就只剩提供方默认这一项，不会再出现自相矛盾的控件。配置 profile 的 `reasoning` 值（包括 `off`）在存在时是部署默认值；省略它会保留提供方默认值。每次请求的 `GenerateOptions.reasoningEffort` 优先；未出现在确切模型能力中的档位会让**请求**在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败，而不会被自动调整。**描述**一个模型则从不这样失败：同一提供方下各模型接受的档位并不一致，因此 `resolveModel` 对该模型拿不下的 profile 档位报告为「没有默认值」，而不是抛错。在那里抛错会让整个提供方从任何基于它构建的模型目录中消失——一个配错的 profile 字段连支持该档位的模型也一并藏起来——所以坏配置暴露在被执行处，而不是被描述处。pi-ai 的通用流选项通过省略 `reasoning` 表示 `off`。
 
-受支持的 profile 字段是 `apiKey`、`apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`compat`、`defaultContextWindow`、`defaultMaxTokens`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs` 和 `retryPolicy`。每个 profile 的可选重试策略都会与该提供方路由一同捕获；省略时使用有界的常规默认值。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。若已配置标头中有同名项，则以 Harness 应用归因为准。
+受支持的 profile 字段是 `apiKey`、`apiKeyEnv`、`displayName`、`api`、`baseURL`、`models`、`modelOverrides`、`compat`、`defaultContextWindow`、`defaultMaxTokens`、`headers`、`reasoning`、`thinkingBudgets`、`cacheRetention`、`transport`、`timeoutMs`、`websocketConnectTimeoutMs`、`streamIdleTimeoutMs` 和 `retryPolicy`。每个 profile 的可选重试策略都会与该提供方路由一同捕获；省略时使用有界的常规默认值。流空闲间隔必须是正的有限 Node 定时器延迟，默认为五分钟，且只覆盖未完成提供方读取，不包括消费方思考时间。若已配置标头中有同名项，则以 Harness 应用归因为准。
 
 适配器强制 pi-ai SDK `maxRetries` 为零，因此一次 `stream()` 调用只会发起一次提供方请求。已移除 profile 字段 `maxRetries` 和 `maxRetryDelayMs` 会使加载失败，而不是静默倍增或隐藏单独组合的 agent（智能体）级重试预算。空闲超时会 abort SDK 的稳定请求信号，并以 `TIMEOUT` 呈现；较早的调用方 abort 仍为 `ABORTED`。
 
diff --git a/packages/llm/llm-pi-ai/src/catalog.ts b/packages/llm/llm-pi-ai/src/catalog.ts
index e3c9207927..3285d1595a 100644
--- a/packages/llm/llm-pi-ai/src/catalog.ts
+++ b/packages/llm/llm-pi-ai/src/catalog.ts
@@ -184,6 +184,15 @@ export interface PiAiModelProfile {
   compat?: PiAiCompatProfile
 }
 
+/**
+ * Customization of one installed catalog model, keyed by its id in the
+ * route's `modelOverrides` dict — the same fields a `models` entry may set,
+ * with the id living in the key. Unlike a `models` list, overrides leave the
+ * rest of the catalog serving untouched, which is what makes "correct one
+ * model, keep the other thirty-seven" a three-line edit.
+ */
+export type PiAiModelOverride = Omit<PiAiModelProfile, 'id'>
+
 /** The route-level facts model materialization reads. */
 export interface RouteCatalogRequest {
   /** Provider route key, stamped onto every materialized model. */
@@ -194,6 +203,8 @@ export interface RouteCatalogRequest {
   baseURL?: string
   /** Configured catalog; absent means the whole installed catalog for this route. */
   models?: readonly PiAiModelProfile[]
+  /** Installed-catalog customizations by model id; only meaningful while `models` is absent. */
+  modelOverrides?: Readonly<Record<string, PiAiModelOverride>>
   /** Reasoning-dispatch switches for every `openai-completions` model on the route; entries override per field. */
   compat?: PiAiCompatProfile
   /** Context capacity for a model neither the entry nor the catalog sizes. */
@@ -381,9 +392,35 @@ export function resolveRouteModels(request: RouteCatalogRequest): RouteCatalog {
   // schema materializes `[]` for the absent case, and an empty catalog could
   // serve no request anyway, so both mean "serve the installed catalog".
   const configured = request.models ?? []
+  const overrides = request.modelOverrides ?? {}
+  // Every miss is refused, never skipped: an override that lands nowhere is a
+  // typo someone would otherwise hunt for in a silently unchanged model.
+  for (const [id, override] of Object.entries(overrides)) {
+    if (id.length === 0) invalid(provider, 'has a modelOverrides entry with an empty model id')
+    if (defaults.size === 0) {
+      invalid(provider, `sets modelOverrides for "${id}", but the installed catalog does not describe this route;`
+        + ' a declared route spells every model out in its models list')
+    }
+    if (configured.length > 0) {
+      invalid(provider, `sets modelOverrides for "${id}" beside a models list; models already replaces the served`
+        + ' catalog, so declare the fields on its entries')
+    }
+    if (!defaults.has(id)) {
+      invalid(provider, `modelOverrides names "${id}", which the installed catalog does not describe`)
+    }
+    // The id lives in the dict key; a value carrying its own would quietly
+    // rename the model it meant to customize. The static shape already omits
+    // it — this guards the schema boundary, which passes unknown keys through.
+    if ('id' in override) {
+      invalid(provider, `modelOverrides entry "${id}" sets "id", which is the dict key`)
+    }
+  }
+  // An override becomes the catalog entry's configuration, so everything a
+  // models entry may declare — capacities, efforts, compat — resolves through
+  // the same path with the same diagnostics and request-default semantics.
   const entries: readonly PiAiModelProfile[] = configured.length > 0
     ? configured
-    : [...defaults.values()].map(model => ({ id: model.id }))
+    : [...defaults.values()].map(model => ({ id: model.id, ...overrides[model.id] }))
   if (entries.length === 0) {
     invalid(provider, 'resolves no models; the installed catalog does not describe this route, so its models'
       + ' must be listed in configuration')
diff --git a/packages/llm/llm-pi-ai/src/config.ts b/packages/llm/llm-pi-ai/src/config.ts
index 9d4cca089c..d93f68bcd9 100644
--- a/packages/llm/llm-pi-ai/src/config.ts
+++ b/packages/llm/llm-pi-ai/src/config.ts
@@ -22,7 +22,7 @@ import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { normalizeApiKey, resolveRetryPolicy, RetryPolicySchema } from '@deepseek-ai/dsh-llm'
 import type { ResolvedRetryPolicy, RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
 import { resolveRouteModels, SUPPORTED_THINKING_FORMATS, THINKING_LEVELS } from './catalog.ts'
-import type { PiAiCompatProfile, PiAiModelProfile, PiAiReasoningEfforts } from './catalog.ts'
+import type { PiAiCompatProfile, PiAiModelOverride, PiAiModelProfile, PiAiReasoningEfforts } from './catalog.ts'
 import { buildProvider, supportedProtocols } from './provider.ts'
 
 /** Default maximum idle interval while an adapter stream read is outstanding. */
@@ -34,7 +34,13 @@ export const DEFAULT_CONTEXT_WINDOW = 262_144
 /** Output capability assumed for a model neither configuration nor the catalog sizes. */
 export const DEFAULT_MAX_TOKENS = 32_768
 
-export type { PiAiCompatProfile, PiAiModelProfile, PiAiReasoningEfforts, PiAiThinkingFormat } from './catalog.ts'
+export type {
+  PiAiCompatProfile,
+  PiAiModelOverride,
+  PiAiModelProfile,
+  PiAiReasoningEfforts,
+  PiAiThinkingFormat,
+} from './catalog.ts'
 
 /** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */
 export interface PiAiProviderProfile {
@@ -62,6 +68,15 @@ export interface PiAiProviderProfile {
    * unset fields from the installed model of the same id.
    */
   models?: PiAiModelProfile[]
+  /**
+   * Installed-catalog customizations by model id: each entry reshapes that
+   * one model with the same fields a {@link models} entry takes, while the
+   * rest of the catalog keeps serving untouched. Only meaningful on a catalog
+   * route with no `models` list — `models` already replaces the catalog, so
+   * an override beside it, on a route the catalog does not ship, or naming a
+   * model the catalog does not describe is refused rather than skipped.
+   */
+  modelOverrides?: Record<string, PiAiModelOverride>
   /**
    * Reasoning-dispatch switches for every `openai-completions` model on this
    * route; each model's own `compat` overrides per field. What neither sets
@@ -176,6 +191,15 @@ const modelProfile: z<PiAiModelProfile> = z.object({
   compat: compatProfile,
 })
 
+/** A {@link modelProfile} whose id lives in the `modelOverrides` dict key. */
+const modelOverride: z<PiAiModelOverride> = z.object({
+  name: z.string(),
+  contextWindow: z.number().step(1).min(1),
+  maxTokens: z.number().step(1).min(1),
+  reasoningEfforts: z.union([z.const(false), reasoningEfforts]),
+  compat: compatProfile,
+})
+
 const profile = z.object({
   apiKey: z.string().role('secret'),
   apiKeyEnv: z.string().role('credential-ref'),
@@ -183,6 +207,7 @@ const profile = z.object({
   api: z.union(supportedProtocols()),
   baseURL: z.string(),
   models: z.array(modelProfile),
+  modelOverrides: z.dict(modelOverride),
   compat: compatProfile,
   defaultContextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
   defaultMaxTokens: z.number().step(1).min(1).default(DEFAULT_MAX_TOKENS),
@@ -291,6 +316,7 @@ export function resolveProfiles(
       ...source.api === undefined ? {} : { api: source.api },
       ...source.baseURL === undefined ? {} : { baseURL: source.baseURL },
       ...source.models === undefined ? {} : { models: source.models },
+      ...source.modelOverrides === undefined ? {} : { modelOverrides: source.modelOverrides },
       ...source.compat === undefined ? {} : { compat: source.compat },
       defaultContextWindow: source.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
       defaultMaxTokens: source.defaultMaxTokens ?? DEFAULT_MAX_TOKENS,
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index ea81f66fec..e00b9f3c2a 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -70,6 +70,7 @@ export type { PiAiAdapterOptions } from './adapter.ts'
 export { Config } from './config.ts'
 export type {
   PiAiCompatProfile,
+  PiAiModelOverride,
   PiAiModelProfile,
   PiAiProviderProfile,
   PiAiReasoningEfforts,
diff --git a/packages/llm/llm-pi-ai/tests/catalog.spec.ts b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
index fbfcd653cf..de806558c5 100644
--- a/packages/llm/llm-pi-ai/tests/catalog.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
@@ -573,6 +573,77 @@ describe('per-model reasoning efforts', () => {
   })
 })
 
+describe('modelOverrides', () => {
+  const deepseekModel = (): Model<Api> => {
+    const [model] = getBuiltinModels('deepseek')
+    if (model === undefined) throw new Error('the installed catalog ships no deepseek model')
+    return model
+  }
+
+  it('reshapes one catalog model while the rest of the catalog keeps serving', () => {
+    const catalogSize = getBuiltinModels('deepseek').length
+    const target = deepseekModel()
+    const resolved = resolveProfiles({
+      deepseek: {
+        modelOverrides: {
+          [target.id]: {
+            name: 'DeepSeek (proxied)',
+            maxTokens: 4096,
+            reasoningEfforts: { off: null, high: 'high' },
+          },
+        },
+      },
+    })
+    const models = resolved.get('deepseek')?.piProvider.getModels() ?? []
+    const reshaped = models.find(model => model.id === target.id)
+    if (reshaped === undefined) throw new Error('the overridden model vanished from the route')
+
+    // The whole catalog still serves — that is the difference from `models`,
+    // which replaces it.
+    expect(models).toHaveLength(catalogSize)
+    expect(reshaped.name).toBe('DeepSeek (proxied)')
+    expect(getSupportedThinkingLevels(reshaped)).toEqual(['off', 'high'])
+    // An override's cap is explicit configuration, so it becomes the request
+    // default exactly as a models entry's would.
+    expect(resolved.get('deepseek')?.configuredMaxTokens.get(target.id)).toBe(4096)
+    // A sibling the overrides do not name is byte-identical to the catalog.
+    const sibling = models.find(model => model.id !== target.id)
+    expect(sibling?.maxTokens).toBe(getBuiltinModels('deepseek').find(model => model.id === sibling?.id)?.maxTokens)
+  })
+
+  it('refuses every override that lands nowhere instead of skipping it', () => {
+    expect(() => resolveProfiles({
+      deepseek: { modelOverrides: { 'no-such-model': { name: 'ghost' } } },
+    })).toThrow(/which the installed catalog does not describe/)
+    expect(() => resolveProfiles({
+      'acme-gateway': {
+        api: 'openai-completions',
+        baseURL: 'https://acme.test',
+        models: [{ id: 'm' }],
+        modelOverrides: { m: { name: 'renamed' } },
+      },
+    })).toThrow(/a declared route spells every model out/)
+    const declaredOnly = deepseekModel()
+    expect(() => resolveProfiles({
+      deepseek: {
+        models: [{ id: declaredOnly.id }],
+        modelOverrides: { [declaredOnly.id]: { name: 'renamed' } },
+      },
+    })).toThrow(/models already replaces the served catalog/)
+    expect(() => resolveProfiles({
+      deepseek: { modelOverrides: { '': { name: 'nameless' } } },
+    })).toThrow(/empty model id/)
+    // The dict key is the id; a value smuggling its own would quietly rename
+    // the model it meant to customize. The schema passes unknown keys
+    // through, so resolution is the boundary that refuses it — the variable
+    // indirection mirrors that boundary by sidestepping the literal check.
+    const smuggled = { name: 'x', id: 'other' }
+    expect(() => resolveProfiles({
+      deepseek: { modelOverrides: { [deepseekModel().id]: smuggled } },
+    })).toThrow(/sets "id", which is the dict key/)
+  })
+})
+
 describe('reasoning-dispatch compat switches', () => {
   /** The materialized models of one route, keyed by id. */
   function modelsOf(providers: Record<string, LlmPiAi.PiAiProviderProfile>, route: string): Map<string, Model<Api>> {

From 56e9e617498a5ac9bc5a8c4b1878c776bb2c299a Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 00:59:55 +0800
Subject: [PATCH 181/516] feat(ui-skill): claim slash skill references into
 skill.invoke
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A menu pick or an entered /name line now claims the composer into an
args-tolerant skill.invoke transaction instead of shipping the literal
text and hoping the model loads the skill. This gives every user-invocable
skill a deterministic entry point — including disable-model-invocation
skills the catalog never shows the model (issue #1470). Candidates carry
a user-only hint, and the unreached legacy <skill> reference codec is
removed (decision 21 removal cut).
---
 packages/client/connection/tests/fake-api.ts  |  4 +
 packages/client/runtime/tests/fake-api.ts     |  4 +
 packages/client/ui-skill/src/client/index.ts  | 71 ++++++++++----
 .../client/ui-skill/src/client/locales.ts     |  2 +
 .../ui-skill/tests/browser-plugin.spec.ts     | 92 +++++++++++++++----
 5 files changed, 139 insertions(+), 34 deletions(-)

diff --git a/packages/client/connection/tests/fake-api.ts b/packages/client/connection/tests/fake-api.ts
index cc1062843e..bd8efaf6a4 100644
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -163,6 +163,9 @@ export class FakeApiClient implements IApiClient {
   onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
     = () => Promise.resolve(ok({ skills: [] }))
 
+  onSkillInvoke: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>>
+    = () => Promise.resolve(ok({ accepted: true as const }))
+
   readonly commands: IApiClient['commands'] = {
     list: (payload: unknown) => this.record('command.list', payload, this.onCommandList(payload)),
     execute: (payload: unknown) => this.record('command.execute', payload, this.onCommandExecute(payload)),
@@ -170,6 +173,7 @@ export class FakeApiClient implements IApiClient {
 
   readonly skills: IApiClient['skills'] = {
     list: (payload: unknown) => this.record('skill.list', payload, this.onSkillList(payload)),
+    invoke: (payload: unknown) => this.record('skill.invoke', payload, this.onSkillInvoke(payload)),
   }
 
   readonly goals: IApiClient['goals'] = {
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
index b6f2884837..def535a59a 100644
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -198,6 +198,9 @@ export class FakeApiClient implements IApiClient {
   onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
     = () => Promise.resolve(ok({ skills: [] }))
 
+  onSkillInvoke: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>>
+    = () => Promise.resolve(ok({ accepted: true as const }))
+
   readonly commands: IApiClient['commands'] = {
     list: (payload: unknown) => this.record('command.list', payload, this.onCommandList(payload)),
     execute: (payload: unknown) => this.record('command.execute', payload, this.onCommandExecute(payload)),
@@ -205,6 +208,7 @@ export class FakeApiClient implements IApiClient {
 
   readonly skills: IApiClient['skills'] = {
     list: (payload: unknown) => this.record('skill.list', payload, this.onSkillList(payload)),
+    invoke: (payload: unknown) => this.record('skill.invoke', payload, this.onSkillInvoke(payload)),
   }
 
   readonly goals: IApiClient['goals'] = {
diff --git a/packages/client/ui-skill/src/client/index.ts b/packages/client/ui-skill/src/client/index.ts
index 9631125801..7d859bf2fb 100644
--- a/packages/client/ui-skill/src/client/index.ts
+++ b/packages/client/ui-skill/src/client/index.ts
@@ -2,13 +2,15 @@
  * Skill reference plugin, browser half: registers the '/' skill source —
  * candidates from the skill.list RPC addressed by the per-call session
  * projection's sessionId (sessions are always agent-backed; the host
- * resolves cwd from the session header), pick inserts the literal `/name `
- * text (decision 21: the draft carries plain text, chip visuals are derived
- * by scanning against the source lexicon, and the prompt ships the same
- * literal — no `<skill>` tag). The RPC rides the plugin's root-context
- * connection captured at registration — the source never reads services off
- * a per-call argument. No adjudication hooks: skill references ride
- * ordinary prompts and never enter command adjudication.
+ * resolves cwd from the session header). A menu pick or an entered `/name
+ * [args]` line claims into a skill.invoke transaction: the host renders the
+ * skill body and injects it as a user message, so invocation is
+ * deterministic for every user-invocable skill — including
+ * `disable-model-invocation` skills the model-side catalog never lists
+ * (issue #1470). The RPC rides the plugin's root-context connection
+ * captured at registration — the source never reads services off a per-call
+ * argument. Draft chip visuals still derive from the lexicon scan; the
+ * legacy `<skill>` reference codec is gone (decision 21 removal cut).
  *
  * Catalog fetches are cached per session (the small twin of the ui-command
  * directory): the per-keystroke candidates re-poll filters a settled
@@ -25,7 +27,7 @@
  */
 import type { ConnectionHandle, SessionId, SkillEntry } from '@deepseek-ai/dsh-client-connection/client'
 import type { ClientContext, ISessions } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SlashServiceContract, SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
+import type { PickOutcome, SlashServiceContract, SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import { SkillRow } from './SkillRow.tsx'
@@ -119,6 +121,30 @@ export function apply(ctx: ClientContext): void {
     for (const key of [...fetches.keys()]) invalidate(key)
   }
 
+  /** User-only marker in the active language (the menu hint is plain text, resolved at candidate time). */
+  const userOnlyHint = (): string => ctx.locale.getSnapshot().active === 'zh' ? zh['menu.userOnly'] : en['menu.userOnly']
+
+  /**
+   * Args-tolerant claim for one skill: token `/name ` plus the skill.invoke
+   * transaction. Blank args stay off the wire; an RPC refusal folds into the
+   * composer's error outcome (transport failures throw).
+   */
+  const invokeClaim = (session: { readonly sessionId: SessionId }, name: string): PickOutcome => ({
+    claim: {
+      token: `/${name} `,
+      submit: async (args) => {
+        const trimmed = args.trim()
+        const { result } = await skills.invoke({
+          sessionId: session.sessionId,
+          name,
+          ...trimmed === '' ? {} : { text: trimmed },
+        })
+        if (!result.ok) return { kind: 'error', text: `${result.error.code}: ${result.error.message}` }
+        return { kind: 'success' }
+      },
+    },
+  })
+
   const source: SlashSource = {
     trigger: '/',
     name: 'skill',
@@ -129,7 +155,11 @@ export function apply(ctx: ClientContext): void {
       if (signal.aborted) return []
       return skills
         .filter(skill => skill.name.startsWith(query))
-        .map(skill => ({ name: skill.name, description: skill.description }))
+        .map(skill => ({
+          name: skill.name,
+          description: skill.description,
+          ...skill.modelInvocable ? {} : { hint: userOnlyHint() },
+        }))
     },
     warm(session) {
       // Fire-and-forget scope-birth prewarm; the shared fetch reports
@@ -149,16 +179,21 @@ export function apply(ctx: ClientContext): void {
         if (listeners.size === 0) lexiconListeners.delete(key)
       }
     },
-    onPick({ candidate }) {
-      // Decision 21: plain-text reference — the literal lands in the draft
-      // and ships to the model verbatim (trailing space closes the token).
-      // Legacy path (decision 21), retained for the removal cut, no longer reached:
-      // return { insert: { source: 'skill', ref: candidate.name, label: candidate.name, clipboardText: `/${candidate.name}` } }
-      return { text: `/${candidate.name} ` }
+    onPick({ candidate, session }) {
+      return invokeClaim(session, candidate.name)
     },
-    codec: {
-      clipboardText: ref => `/${ref}`,
-      serialize: ref => Promise.resolve(`<skill>${ref}</skill>`),
+    async matchEnter(session, line, signal) {
+      const trimmed = line.trim()
+      if (!trimmed.startsWith('/')) return undefined
+      const ws = trimmed.search(/\s/)
+      const name = (ws === -1 ? trimmed : trimmed.slice(0, ws)).slice(1)
+      if (name === '') return undefined
+      // Strong-wait the catalog: an unknown name stays a plain prompt (the
+      // default sink), never a swallowed line.
+      const catalog = await fetchCatalog(session.sessionId)
+      if (signal.aborted) return undefined
+      if (!catalog.some(skill => skill.name === name)) return undefined
+      return invokeClaim(session, name)
     },
   }
   const slash = ctx.get('slash') as SlashServiceContract
diff --git a/packages/client/ui-skill/src/client/locales.ts b/packages/client/ui-skill/src/client/locales.ts
index 53746397bc..40ef78dea5 100644
--- a/packages/client/ui-skill/src/client/locales.ts
+++ b/packages/client/ui-skill/src/client/locales.ts
@@ -9,6 +9,7 @@ export const zh = {
   'row.failed': 'skill 加载失败',
   'row.stopped': 'skill 加载已中止',
   'row.instructions': '说明',
+  'menu.userOnly': '仅用户',
 } satisfies Record<string, string>
 
 /** The skill namespace key union. */
@@ -20,4 +21,5 @@ export const en = {
   'row.failed': 'Skill load failed',
   'row.stopped': 'Skill load stopped',
   'row.instructions': 'Instructions',
+  'menu.userOnly': 'user-only',
 } satisfies Record<SkillKey, string>
diff --git a/packages/client/ui-skill/tests/browser-plugin.spec.ts b/packages/client/ui-skill/tests/browser-plugin.spec.ts
index 9b047a3713..e38adf7686 100644
--- a/packages/client/ui-skill/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts
@@ -20,11 +20,15 @@ import type { ClientSessionContext, SlashSource } from '@deepseek-ai/dsh-client-
 import { apply, inject } from '../src/client/index.ts'
 import { SkillRow as SkillToolRow } from '../src/client/SkillRow.tsx'
 
-type SkillRow = { name: string; description: string; whenToUse?: string }
+type SkillRow = { name: string; description: string; whenToUse?: string; modelInvocable?: boolean }
 type ListResult =
   | { ok: true; value: { skills: SkillRow[] } }
   | { ok: false; error: { code: string; message: string; details: object } }
 type ListFn = (payload: object, signal?: AbortSignal) => Promise<{ result: ListResult }>
+type InvokeResult =
+  | { ok: true; value: { accepted: true } }
+  | { ok: false; error: { code: string; message: string; details: object } }
+type InvokeFn = (payload: object) => Promise<{ result: InvokeResult }>
 
 interface PresentationCapture {
   slots: SlotsService
@@ -49,16 +53,18 @@ function providePresentation(ctx: Context): PresentationCapture {
       capture.dictionaries.push({ namespace, dictionaries })
       return () => { capture.localeDisposed = true }
     },
+    getSnapshot: () => ({ active: 'zh', locales: ['zh', 'en'], revision: 0 }),
   })
   return capture
 }
 
 /** Boot the plugin over fake slash/connection faces; returns the captured source and its ctx. */
-async function bench(list: ListFn, addressed?: SessionId) {
+async function bench(list: ListFn, addressed?: SessionId, invoke?: InvokeFn) {
   const ctx = new Context()
   let captured: SlashSource | undefined
   ctx.provide('slash', { registerSource: (src: SlashSource) => { captured = src; return () => {} } })
-  ctx.provide('connection', { api: { skills: { list } } })
+  const defaultInvoke: InvokeFn = () => Promise.resolve({ result: { ok: true as const, value: { accepted: true as const } } })
+  ctx.provide('connection', { api: { skills: { list, invoke: invoke ?? defaultInvoke } } })
   ctx.provide('sessions', {
     subagentAddress: (id: SessionId) => id === addressed
       ? { parentSessionId: sid('parent'), childSessionId: id, mode: 'continuable' as const }
@@ -70,9 +76,9 @@ async function bench(list: ListFn, addressed?: SessionId) {
 }
 
 const CATALOG: SkillRow[] = [
-  { name: 'commit-helper', description: 'commit flow' },
-  { name: 'code-review', description: 'review flow', whenToUse: 'reviews' },
-  { name: 'deploy', description: 'deploy flow' },
+  { name: 'commit-helper', description: 'commit flow', modelInvocable: true },
+  { name: 'code-review', description: 'review flow', whenToUse: 'reviews', modelInvocable: true },
+  { name: 'deploy', description: 'deploy flow', modelInvocable: true },
 ]
 
 const listOk = (skills: SkillRow[]): ListFn => () => Promise.resolve({ result: { ok: true as const, value: { skills } } })
@@ -117,12 +123,14 @@ describe('apply', () => {
           'row.failed': 'skill 加载失败',
           'row.stopped': 'skill 加载已中止',
           'row.instructions': '说明',
+          'menu.userOnly': '仅用户',
         },
         en: {
           'row.running': 'Loading skill',
           'row.failed': 'Skill load failed',
           'row.stopped': 'Skill load stopped',
           'row.instructions': 'Instructions',
+          'menu.userOnly': 'user-only',
         },
       },
     }])
@@ -313,9 +321,10 @@ describe('lexicon', () => {
   })
 })
 
-describe('pick and codec', () => {
-  it('onPick returns the literal /name text with a closing space (decision 21)', async () => {
-    const { source } = await bench(listOk(CATALOG))
+describe('pick claims into skill.invoke', () => {
+  it('onPick returns an args-tolerant claim whose submit invokes the skill', async () => {
+    const invoke = vi.fn(() => Promise.resolve({ result: { ok: true as const, value: { accepted: true as const } } }))
+    const { source } = await bench(listOk(CATALOG), undefined, invoke)
     const outcome = source.onPick({
       candidate: { name: 'commit-helper', description: 'commit flow' },
       session: proj('s1'),
@@ -323,21 +332,72 @@ describe('pick and codec', () => {
       via: 'menu',
       span: { start: 0, end: 4, draftRev: 7 },
     })
-    expect(outcome).toEqual({ text: '/commit-helper ' })
+    if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected a claim outcome')
+    expect(outcome.claim.token).toBe('/commit-helper ')
+    await expect(outcome.claim.submit('check the fixture', {} as never)).resolves.toEqual({ kind: 'success' })
+    expect(invoke).toHaveBeenCalledWith({ sessionId: sid('s1'), name: 'commit-helper', text: 'check the fixture' })
   })
 
-  it('codec projects clipboard `/name` and serializes the model form <skill>name</skill>', async () => {
+  it('submit omits blank args and folds an RPC refusal into an error outcome', async () => {
+    const invoke = vi.fn(() => Promise.resolve({
+      result: { ok: false as const, error: { code: 'skill-not-invocable', message: 'nope', details: { name: 'deploy' } } },
+    }))
+    const { source } = await bench(listOk(CATALOG), undefined, invoke)
+    const outcome = source.onPick({
+      candidate: { name: 'deploy', description: 'deploy flow' },
+      session: proj('s1'),
+      position: 'leading',
+      via: 'menu',
+      span: { start: 0, end: 4, draftRev: 7 },
+    })
+    if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected a claim outcome')
+    await expect(outcome.claim.submit('   ', {} as never))
+      .resolves.toEqual({ kind: 'error', text: 'skill-not-invocable: nope' })
+    expect(invoke).toHaveBeenCalledWith({ sessionId: sid('s1'), name: 'deploy' })
+  })
+
+  it('drops the legacy reference codec (decision 21 removal cut)', async () => {
     const { source } = await bench(listOk(CATALOG))
-    expect(source.codec!.clipboardText('deploy')).toBe('/deploy')
-    await expect(source.codec!.serialize('deploy', new AbortController().signal))
-      .resolves.toBe('<skill>deploy</skill>')
+    expect(source.codec).toBeUndefined()
   })
 })
 
 describe('adjudication', () => {
-  it('never participates: no matchSpace/matchEnter hooks on the skill source', async () => {
+  it('claims an entered /name line, args-tolerant, once the catalog knows the name', async () => {
+    const invoke = vi.fn(() => Promise.resolve({ result: { ok: true as const, value: { accepted: true as const } } }))
+    const { source } = await bench(listOk(CATALOG), undefined, invoke)
+    const outcome = await source.matchEnter!(proj('s1'), '/deploy run the smoke suite', new AbortController().signal)
+    if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected a claim outcome')
+    expect(outcome.claim.token).toBe('/deploy ')
+    await outcome.claim.submit('run the smoke suite', {} as never)
+    expect(invoke).toHaveBeenCalledWith({ sessionId: sid('s1'), name: 'deploy', text: 'run the smoke suite' })
+  })
+
+  it('answers undefined for unknown names, non-slash lines, and bare "/"', async () => {
+    const { source } = await bench(listOk(CATALOG))
+    const signal = new AbortController().signal
+    await expect(source.matchEnter!(proj('s1'), '/unlisted do it', signal)).resolves.toBeUndefined()
+    await expect(source.matchEnter!(proj('s1'), 'plain prose', signal)).resolves.toBeUndefined()
+    await expect(source.matchEnter!(proj('s1'), '/', signal)).resolves.toBeUndefined()
+  })
+
+  it('never claims on space (menu and enter own the skill flows)', async () => {
     const { source } = await bench(listOk(CATALOG))
     expect(typeof source.matchSpace).toBe('undefined')
-    expect(typeof source.matchEnter).toBe('undefined')
+  })
+})
+
+describe('user-only marking', () => {
+  it('carries the user-only hint on candidates the model cannot invoke', async () => {
+    const rows: SkillRow[] = [
+      { name: 'shared-skill', description: 'both surfaces', modelInvocable: true },
+      { name: 'user-only-skill', description: 'user surface only', modelInvocable: false },
+    ]
+    const { source } = await bench(listOk(rows))
+    const candidates = await source.candidates(proj('s1'), req(''))
+    expect(candidates).toEqual([
+      { name: 'shared-skill', description: 'both surfaces' },
+      { name: 'user-only-skill', description: 'user surface only', hint: '仅用户' },
+    ])
   })
 })

From 011e3e4e63f4cae663bf2aa7a4523c92c9786f68 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 01:05:08 +0800
Subject: [PATCH 182/516] feat(client): render user skill invocations as
 dedicated transcript cards

A user/message carrying the skill-invocation source materializes as its
own conversation node (name/args lifted off the source metadata, never
re-parsed from the body) and renders as a right-aligned bubble: the /name
chip plus the user's trailing text, with the injected <skill_content>
collapsed behind a disclosure. A record with an unreadable name degrades
to the injected-context row.
---
 packages/client/runtime/src/client/index.ts   |  2 +-
 .../src/client/sessions/conversation.ts       | 20 ++++++++++
 .../src/client/sessions/transcript-adapter.ts | 16 +++++++-
 .../runtime/tests/transcript-adapter.spec.ts  | 25 ++++++++++++
 .../src/client/chat/MessageItem.module.css    | 27 +++++++++++++
 .../src/client/chat/MessageItem.tsx           | 39 ++++++++++++++++++-
 .../ui-conversation/src/client/locales.ts     |  2 +
 .../tests/chat-branch-tails.spec.tsx          | 36 +++++++++++++++++
 8 files changed, 163 insertions(+), 4 deletions(-)

diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index 5a1677df96..a0aa4df482 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -49,7 +49,7 @@ export type {
   AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
   AssistantTiming, CodeSubCall, CommandNode, CompactionSummaryNode, ComposerPhase,
   ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, QueuedMessage,
-  RunningToolCall,
+  RunningToolCall, SkillInvocationNode,
   SteeringMessageNode, TodoItem, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
 export type {
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index fb2c281331..d66faf5e95 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -129,6 +129,25 @@ export interface ContextMessageNode {
   form: KnownContextForm | null
 }
 
+/**
+ * A user-explicit skill invocation: the host injected the rendered skill as a
+ * user message carrying the `skill-invocation` source, so the card presents
+ * `/name args` from source metadata and collapses the injected body.
+ */
+export interface SkillInvocationNode {
+  kind: 'skill-invocation'
+  seq: number
+  /** Unix epoch ms from the source session event. */
+  time: number
+  /** Invoked skill name read off the message source. */
+  name: string
+  /** Trailing user text read off the message source, when recorded. */
+  args?: string
+  /** Full injected model-facing content (collapsed by default in the UI). */
+  content: readonly ContentBlock[]
+  source: unknown
+}
+
 /** Durable notice that a closed failed step is waiting for a model-request retry. */
 export type ModelRetryNode = LlmRetryEventData & {
   kind: 'model-retry'
@@ -245,6 +264,7 @@ export type ConversationNode =
   | AssistantMessageNode
   | SteeringMessageNode
   | ContextMessageNode
+  | SkillInvocationNode
   | ModelRetryNode
   | TurnErrorNode
   | ToolResultNode
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index d970be596b..4a05afee06 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -57,7 +57,20 @@ function materializeNode(
   stepTimings: ReadonlyMap<string, AssistantStepMetadata>,
 ): ConversationNode {
   switch (event.type) {
-    case 'user/message':
+    case 'user/message': {
+      // A user-explicit skill invocation carries its name (and optional args)
+      // on the source; the dedicated node lets the card render `/name args`
+      // from metadata instead of re-parsing the injected body. A record whose
+      // name is unreadable degrades to injected context below.
+      const source = event.data.source as { kind?: unknown; name?: unknown; args?: unknown }
+      if (source.kind === 'skill-invocation' && typeof source.name === 'string') {
+        return {
+          kind: 'skill-invocation', seq: event.seq, time: event.time,
+          name: source.name,
+          ...typeof source.args === 'string' ? { args: source.args } : {},
+          content: event.data.content, source: event.data.source,
+        }
+      }
       // Injected context (plugin/goal source) folds to a context node, not a
       // user message; only a direct human prompt is a user node. A compaction
       // checkpoint never reaches here (isCompactCheckpoint routes it away).
@@ -80,6 +93,7 @@ function materializeNode(
         kind: 'user', seq: event.seq, time: event.time,
         content: event.data.content, source: event.data.source,
       }
+    }
     case 'assistant/message':
       return {
         kind: 'assistant', seq: event.seq, time: event.time,
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
index e4ef3b0e1a..e847c2cec7 100644
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ b/packages/client/runtime/tests/transcript-adapter.spec.ts
@@ -164,6 +164,31 @@ describe('TranscriptAdapter', () => {
     expect(adapter.nodes().map(node => node.kind)).toEqual(['user', 'user', 'context'])
   })
 
+  it('materializes a skill-invocation source as its dedicated node', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset([
+      at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+        content: [{ type: 'text', text: '<skill_content name="hidden-demo">body</skill_content>\n\ncheck the fixture' }],
+        source: { kind: 'skill-invocation', name: 'hidden-demo', args: 'check the fixture' } as never,
+      }) }),
+      at(1, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+        content: [{ type: 'text', text: '<skill_content name="bare-skill">body</skill_content>' }],
+        source: { kind: 'skill-invocation', name: 'bare-skill' } as never,
+      }) }),
+    ])
+    const nodes = adapter.nodes()
+    expect(nodes.map(node => node.kind)).toEqual(['skill-invocation', 'skill-invocation'])
+    expect(nodes[0]).toMatchObject({ name: 'hidden-demo', args: 'check the fixture' })
+    expect(nodes[1]).toMatchObject({ name: 'bare-skill' })
+    expect((nodes[1] as { args?: string }).args).toBeUndefined()
+    // A malformed record (no readable name) degrades to injected context, not a crash.
+    adapter.append(at(2, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+      content: [{ type: 'text', text: 'odd' }],
+      source: { kind: 'skill-invocation' } as never,
+    }) }))
+    expect(adapter.nodes().at(-1)?.kind).toBe('context')
+  })
+
   it('skips events core does not call surface-eligible, marker or not', () => {
     // The transcript is the append-origin surface, so log-only events (a chunk,
     // a turn boundary, a compact/* provenance record) and a future type core
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
index 5c07ace71e..4330cde32c 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
@@ -256,3 +256,30 @@
   white-space: nowrap;
   vertical-align: baseline;
 }
+
+/* User-explicit skill invocation: the injected body collapses behind a
+   disclosure inside the user bubble. */
+.skillInvocationDetails {
+  margin-top: 6px;
+}
+
+.skillInvocationSummary {
+  cursor: pointer;
+  font-size: 0.8em;
+  color: var(--dsw-alias-label-secondary);
+  user-select: none;
+}
+
+.skillInvocationBody {
+  margin: 6px 0 0;
+  padding: 8px;
+  max-height: 320px;
+  overflow: auto;
+  border-radius: 6px;
+  background: var(--dsw-alias-bg-secondary, rgba(0, 0, 0, 0.06));
+  font-family: var(--dsw-font-mono, monospace);
+  font-size: 0.78em;
+  line-height: 1.5;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
index 5473c9f8a2..661dd0cda5 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
@@ -7,8 +7,8 @@
 import { memo, useEffect, useMemo, useState } from 'react'
 import type { ReactNode } from 'react'
 import type {
-  CompactionSummaryNode, ContextMessageNode, ModelRetryNode, SteeringMessageNode,
-  TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
+  CompactionSummaryNode, ContextMessageNode, ModelRetryNode, SkillInvocationNode,
+  SteeringMessageNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { JsonBlock, MessageText, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
@@ -22,6 +22,7 @@ export interface MessageItemProps {
     | UserMessageNode
     | SteeringMessageNode
     | ContextMessageNode
+    | SkillInvocationNode
     | CompactionSummaryNode
     | ModelRetryNode
     | TurnErrorNode
@@ -193,6 +194,38 @@ function UserStyleBubble({
   )
 }
 
+/**
+ * A user-explicit skill invocation: the right-aligned bubble presents the
+ * `/name args` gesture from source metadata (never re-parsed from the body),
+ * and the injected `<skill_content>` collapses behind a disclosure — the
+ * durable content is model-facing bulk, not conversation prose.
+ */
+function SkillInvocationRow({ node, t }: {
+  node: SkillInvocationNode
+  t: ChatViewSlotProps['t']
+}): ReactNode {
+  const { text } = contentText(node.content)
+  return (
+    <div className={css.userRow} data-skill-invocation data-time-hover-root>
+      <div className={css.bubble}>
+        <span className={css.refChip} data-ref-chip="skill">{`/${node.name}`}</span>
+        {node.args !== undefined && <MessageText text={` ${node.args}`} />}
+        <details className={css.skillInvocationDetails}>
+          <summary className={css.skillInvocationSummary}>{t('message.skillInvocation.expand')}</summary>
+          <pre className={css.skillInvocationBody}>{text}</pre>
+        </details>
+      </div>
+      <MessageIconActions
+        text={text}
+        time={node.time}
+        clock="start"
+        className={css.actions}
+        t={t}
+      />
+    </div>
+  )
+}
+
 /**
  * Render one Host-authoritative pending steering item with the same visual
  * language as its eventual durable transcript node.
@@ -254,6 +287,8 @@ export const MessageItem = memo(function MessageItem({
           t={t}
         />
       )
+    case 'skill-invocation':
+      return <SkillInvocationRow node={node} t={t} />
     case 'compaction':
       return <CompactionItem node={node} t={t} />
     case 'model-retry':
diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index df107d2cd2..a340a2f634 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -79,6 +79,7 @@ export const zh = {
   'message.context.recall.counts': '保留 {retained} 条 · 省略 {omitted} 条',
   'message.context.recall.truncated': '已截断',
   'message.steering': '插话',
+  'message.skillInvocation.expand': '查看注入的 skill 内容',
   'message.compaction': '上下文已压缩',
   'message.compaction.expand': '点击查看压缩摘要',
   'message.compaction.unavailable': '压缩摘要不可用',
@@ -219,6 +220,7 @@ export const en = {
   'message.context.recall.counts': '{retained} kept · {omitted} omitted',
   'message.context.recall.truncated': 'truncated',
   'message.steering': 'Interjection',
+  'message.skillInvocation.expand': 'View injected skill content',
   'message.compaction': 'Context compacted',
   'message.compaction.expand': 'View compaction summary',
   'message.compaction.unavailable': 'Compaction summary unavailable',
diff --git a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
index 3122b0fdc7..9471461cda 100644
--- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
@@ -864,6 +864,42 @@ describe('MessageItem arms', () => {
     view.rerender(<MessageItem t={t} node={node} retryActive />)
     expect(view.getByRole('status').textContent).toBe('正在重试模型请求（1/2） · 1s')
   })
+
+  it('skill-invocation renders the /name chip, args, and a collapsed injected body', () => {
+    const body = '<skill_content name="hidden-demo">instructions</skill_content>\n\ncheck the fixture'
+    const view = render(
+      <MessageItem t={t} node={{
+        kind: 'skill-invocation', seq: 4, time: 1_000,
+        name: 'hidden-demo', args: 'check the fixture',
+        content: [{ type: 'text', text: body }] as never,
+        source: null,
+      }}
+      />,
+    )
+    const chip = view.container.querySelector('[data-ref-chip="skill"]')
+    expect(chip?.textContent).toBe('/hidden-demo')
+    const details = view.container.querySelector('details')
+    expect(details).toBeTruthy()
+    expect(details?.open).toBe(false)
+    expect(view.getByText('查看注入的 skill 内容')).toBeTruthy()
+    expect(view.container.querySelector('pre')?.textContent).toBe(body)
+    expect(view.container.querySelector('[data-skill-invocation]')).toBeTruthy()
+  })
+
+  it('skill-invocation without args renders only the chip line', () => {
+    const view = render(
+      <MessageItem t={t} node={{
+        kind: 'skill-invocation', seq: 5, time: 1_000,
+        name: 'bare-skill',
+        content: [{ type: 'text', text: '<skill_content name="bare-skill">x</skill_content>' }] as never,
+        source: null,
+      }}
+      />,
+    )
+    const bubble = view.container.querySelector('[data-skill-invocation]')
+    expect(bubble?.textContent).toContain('/bare-skill')
+    expect(bubble?.textContent).not.toContain('undefined')
+  })
 })
 
 describe('formatMessageClock', () => {

From 6d09c315b93d3a5223cc31c30f99083af5530428 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 01:10:57 +0800
Subject: [PATCH 183/516] cleanup: remove private repository references

---
 ...andatory-app-attribution-headers.i18n.yaml |  4 +-
 ...06-21-mandatory-app-attribution-headers.md |  4 +-
 ...21-mandatory-app-attribution-headers.zh.md |  4 +-
 ...7-29-pnpm-setup-runner-isolation.i18n.yaml |  4 +-
 .../2026-07-29-pnpm-setup-runner-isolation.md |  2 +-
 ...26-07-29-pnpm-setup-runner-isolation.zh.md |  2 +-
 ...06-18-compaction-capability-seam.i18n.yaml |  4 +-
 .../2026-06-18-compaction-capability-seam.md  |  2 +-
 ...026-06-18-compaction-capability-seam.zh.md |  2 +-
 ...-07-26-todo-parallel-in-progress.i18n.yaml |  4 +-
 .../2026-07-26-todo-parallel-in-progress.md   |  2 +-
 ...2026-07-26-todo-parallel-in-progress.zh.md |  2 +-
 ...6-07-30-queued-manual-compaction.i18n.yaml |  4 +-
 .../2026-07-30-queued-manual-compaction.md    |  2 +-
 .../2026-07-30-queued-manual-compaction.zh.md |  2 +-
 .../2026-08-05-pwsh-ui-bash-parity.i18n.yaml  |  4 +-
 .../feature/2026-08-05-pwsh-ui-bash-parity.md |  2 +-
 .../2026-08-05-pwsh-ui-bash-parity.zh.md      |  2 +-
 ...13-documentation-site-projection.i18n.yaml |  4 +-
 ...026-07-13-documentation-site-projection.md |  4 +-
 ...-07-13-documentation-site-projection.zh.md |  4 +-
 ...ence-based-larger-hosted-runners.i18n.yaml |  4 +-
 ...22-evidence-based-larger-hosted-runners.md |  8 +--
 ...evidence-based-larger-hosted-runners.zh.md |  8 +--
 ...efed-minimal-translation-updates.i18n.yaml |  4 +-
 ...-26-briefed-minimal-translation-updates.md |  2 +-
 ...-briefed-minimal-translation-updates.zh.md |  2 +-
 ...27-wine-windows-gates-experiment.i18n.yaml |  4 +-
 ...026-07-27-wine-windows-gates-experiment.md |  4 +-
 ...-07-27-wine-windows-gates-experiment.zh.md |  4 +-
 ...staller-adopts-existing-checkout.i18n.yaml |  4 +-
 ...7-31-installer-adopts-existing-checkout.md |  2 +-
 ...1-installer-adopts-existing-checkout.zh.md |  2 +-
 ...8-06-doc-site-carries-its-images.i18n.yaml |  4 +-
 .../2026-08-06-doc-site-carries-its-images.md |  4 +-
 ...26-08-06-doc-site-carries-its-images.zh.md |  4 +-
 .../2026-06-19-acp-snapshot-tests.i18n.yaml   |  4 +-
 .../testing/2026-06-19-acp-snapshot-tests.md  |  2 +-
 .../2026-06-19-acp-snapshot-tests.zh.md       |  2 +-
 .github/workflows/ci.yml                      |  3 +-
 .../cordis-tutorial/01-first-plugin.i18n.yaml |  4 +-
 docs/cordis-tutorial/01-first-plugin.md       |  2 +-
 docs/cordis-tutorial/01-first-plugin.zh.md    |  2 +-
 .../02-lifecycle-and-effects.i18n.yaml        |  4 +-
 .../02-lifecycle-and-effects.md               |  2 +-
 .../02-lifecycle-and-effects.zh.md            |  2 +-
 docs/cordis-tutorial/03-services.i18n.yaml    |  4 +-
 docs/cordis-tutorial/03-services.md           |  2 +-
 docs/cordis-tutorial/03-services.zh.md        |  2 +-
 docs/cordis-tutorial/04-events.i18n.yaml      |  4 +-
 docs/cordis-tutorial/04-events.md             |  2 +-
 docs/cordis-tutorial/04-events.zh.md          |  2 +-
 docs/cordis-tutorial/05-config.i18n.yaml      |  4 +-
 docs/cordis-tutorial/05-config.md             |  2 +-
 docs/cordis-tutorial/05-config.zh.md          |  2 +-
 .../06-composition-and-hmr.i18n.yaml          |  4 +-
 .../cordis-tutorial/06-composition-and-hmr.md |  2 +-
 .../06-composition-and-hmr.zh.md              |  2 +-
 .../07-into-the-harness.i18n.yaml             |  4 +-
 docs/cordis-tutorial/07-into-the-harness.md   |  2 +-
 .../cordis-tutorial/07-into-the-harness.zh.md |  2 +-
 docs/cordis-tutorial/index.i18n.yaml          |  4 +-
 docs/cordis-tutorial/index.md                 |  4 +-
 docs/cordis-tutorial/index.zh.md              |  4 +-
 docs/user/guide/quickstart.i18n.yaml          |  4 +-
 docs/user/guide/quickstart.md                 |  2 +-
 docs/user/guide/quickstart.zh.md              |  2 +-
 examples/acp-agent/tests/acp.snapshot.ts      |  4 +-
 .../headless-agent/tests/compaction.e2e.ts    |  4 +-
 examples/mcp-memory/README.i18n.yaml          |  4 +-
 examples/mcp-memory/README.md                 |  2 +-
 examples/mcp-memory/README.zh.md              |  2 +-
 package.json                                  |  1 +
 packages/llm/llm/README.i18n.yaml             |  4 +-
 packages/llm/llm/README.md                    |  2 +-
 packages/llm/llm/README.zh.md                 |  2 +-
 packages/llm/llm/src/attribution.ts           |  3 +-
 packages/llm/llm/src/call-config.ts           |  2 +
 packages/sdk/telemetry/README.i18n.yaml       |  4 +-
 packages/sdk/telemetry/README.md              |  4 +-
 packages/sdk/telemetry/README.zh.md           |  4 +-
 packages/sdk/telemetry/src/reporter.ts        |  6 +-
 scripts/install.sh                            |  4 +-
 scripts/project-doc-site.spec.ts              |  6 +-
 scripts/project-doc-site.ts                   |  4 +-
 scripts/run-gates.spec.ts                     |  6 ++
 scripts/run-gates.ts                          |  1 +
 .../verify-public-repository-links.spec.ts    | 16 +++++
 scripts/verify-public-repository-links.ts     | 64 +++++++++++++++++++
 website/.vitepress/config.ts                  |  6 +-
 90 files changed, 229 insertions(+), 137 deletions(-)
 create mode 100644 scripts/verify-public-repository-links.spec.ts
 create mode 100644 scripts/verify-public-repository-links.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index 946d5a6117..b6788a47ef 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.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 .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
-2026-06-21-mandatory-app-attribution-headers.md: 28432008c354cbbb6e364746338627a26b464b0c
-2026-06-21-mandatory-app-attribution-headers.zh.md: 4fb3acd72aba4bebe751f57ac0f89f776d1f1f39
+2026-06-21-mandatory-app-attribution-headers.md: ad9d65805c8f0c96bd811b5036310d019760627e
+2026-06-21-mandatory-app-attribution-headers.zh.md: 3021c7fcca00f2e929d997625c303f9a27dbf673
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
index 28432008c3..ad9d65805c 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
@@ -32,7 +32,7 @@ The provider-neutral identity is owned by `dsh-llm` (`packages/llm/llm/src/attri
 
 - product token for `User-Agent`: `deepseek-harness` (continuity with the pre-Agent Note wire value and the repo/org identity)
 - version: read from the owning package's manifest via `createRequire`, never a hand-copied constant
-- app URL: `https://github.com/deepseek-ai/deepseek-harness-sdk` - the planned public home; [#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) tracks making it reachable before release
+- app URL: `https://github.com/deepseek-ai/deepseek-harness-sdk` - the planned public home, which must exist before release
 
 The default is mandatory and non-empty. White-label deployments pass their own `AppIdentity` to `attributionHeaders(identity)` - the override seam is the function parameter, with no deployment config plumbing until a consumer needs it - and omission falls back to the harness default rather than suppressing attribution. There is no per-request API for the model, user prompt, session id, cwd, user email, API key owner, or local machine identity to influence these fields.
 
@@ -77,7 +77,7 @@ The landed contract:
 
 **Providers see that traffic comes from the harness.** That is the point, but it means deployments that previously blended into generic SDK traffic become identifiable. Mitigation: send only static public product data and let forks/white-label deployments pass their own `AppIdentity`.
 
-**The app URL points at a repository that does not exist yet.** `deepseek-ai/deepseek-harness-sdk` is the planned public home; until it is created the URL is a dangling promise. [#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) owns creating it or correcting the final URL before release.
+**The app URL points at a repository that does not exist yet.** `deepseek-ai/deepseek-harness-sdk` is the planned public home; until it is created the URL is a dangling promise that blocks release.
 
 **Header support differs by client library.** The hand-rolled adapter sets headers directly; the pi-ai-backed adapter depends on pi-ai continuing to honor `StreamOptions.headers` (merged last over provider defaults). The wire-level mock-server tests are the guard: if a pi-ai upgrade stops delivering the header, the suite goes red. This is useful pressure on the abstraction: a provider adapter that cannot set mandatory headers cannot fully implement the harness LLM contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index 4fb3acd72a..3021c7fcca 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -32,7 +32,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 - `User-Agent` 的产品 token：`deepseek-harness`（与 Agent Note 之前的线路值及仓库/组织身份保持连续性）
 - 版本：通过 `createRequire` 从所属包的 manifest（元数据清单）读取，绝不手动复制常量
-- 应用 URL：`https://github.com/deepseek-ai/deepseek-harness-sdk`——计划中的公开主页；[#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) 跟踪在发布前使其可访问
+- 应用 URL：`https://github.com/deepseek-ai/deepseek-harness-sdk`——计划中的公开主页，且必须在发布前实际存在
 
 默认值是强制的且非空。白标部署通过向 `attributionHeaders(identity)` 传入自己的 `AppIdentity` 来覆盖——覆盖 seam 就是函数参数，在有消费方需要之前不做部署配置管道——省略时回退到 harness 默认值而非抑制归属。没有逐请求 API 允许模型、用户提示词、会话 id、cwd、用户邮箱、API key 所有者或本地机器身份影响这些字段。
 
@@ -77,7 +77,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 **提供方看到流量来自 harness。** 这正是目的，但意味着此前混在通用 SDK 流量中的部署变得可识别。缓解措施：仅发送静态公开产品数据，并允许 fork/白标部署传入自己的 `AppIdentity`。
 
-**应用 URL 指向一个尚不存在的仓库。** `deepseek-ai/deepseek-harness-sdk` 是计划中的公开主页；在它创建之前，该 URL 是一个悬空承诺。[#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) 负责在发布前创建该仓库或校正最终 URL。
+**应用 URL 指向一个尚不存在的仓库。** `deepseek-ai/deepseek-harness-sdk` 是计划中的公开主页；在它创建之前，该 URL 是一个阻塞发布的悬空承诺。
 
 **不同客户端库的头部支持有差异。** 手写适配器直接设置头部；基于 pi-ai 的适配器依赖 pi-ai 继续尊重 `StreamOptions.headers`（最后合并覆盖提供方默认值）。线路级 mock 服务器测试是守卫：如果 pi-ai 升级后不再投递该头部，套件会变红。这对抽象施加了有益的压力：一个无法设置强制头部的提供方适配器不能完整实现 harness 的 LLM 契约。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml
index fb5ee5debc..b1bdfe74c2 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.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 .agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.md
-2026-07-29-pnpm-setup-runner-isolation.md: 743535d0394cbea0374c412ba6968910ce858de4
-2026-07-29-pnpm-setup-runner-isolation.zh.md: 1e51070f88dead17b9d3f5625e337c558786aba2
+2026-07-29-pnpm-setup-runner-isolation.md: 74b672b3f90ea445ad1a8e283a5904056059b2f8
+2026-07-29-pnpm-setup-runner-isolation.zh.md: 32c667dc09e561504e8e053bf2a338ed2190d9e8
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.md b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.md
index 743535d039..74b672b3f9 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-29-pnpm-setup-runner-isolation.zh.md)
 
 ## Problem
 
-`pnpm/action-setup@v4` defaults its install destination to `~/setup-pnpm` and replaces that directory during setup. The self-hosted CI failover runs six GitHub Actions runner services under one VM user, so concurrent jobs shared the same destination. In [run 30375670773](https://github.com/deepseek-harness/deepseek-harness/actions/runs/30375670773), three jobs entered pnpm setup within 73 milliseconds; one setup removed another process's current working directory and two jobs failed in Node's `uv_cwd` initialization. A retry on another runner passed, making the failure timing-dependent rather than a repository-test regression.
+`pnpm/action-setup@v4` defaults its install destination to `~/setup-pnpm` and replaces that directory during setup. The self-hosted CI failover runs six GitHub Actions runner services under one VM user, so concurrent jobs shared the same destination. In the reproducing run, three jobs entered pnpm setup within 73 milliseconds; one setup removed another process's current working directory and two jobs failed in Node's `uv_cwd` initialization. A retry on another runner passed, making the failure timing-dependent rather than a repository-test regression.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md
index 1e51070f88..32c667dc09 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`pnpm/action-setup@v4` 的安装目标目录默认为 `~/setup-pnpm`，并会在设置期间替换该目录。自托管 CI 故障切换在同一个 VM 用户下运行六个 GitHub Actions runner 服务，因此并发作业会共用同一目标目录。在 [run 30375670773](https://github.com/deepseek-harness/deepseek-harness/actions/runs/30375670773) 中，三个作业在 73 毫秒内进入 pnpm 设置；其中一个设置过程删除了另一个进程的当前工作目录，导致两个作业在 Node 的 `uv_cwd` 初始化阶段失败。换到另一台 runner 重试后通过，说明该故障取决于时序，并非仓库测试回归。
+`pnpm/action-setup@v4` 的安装目标目录默认为 `~/setup-pnpm`，并会在设置期间替换该目录。自托管 CI 故障切换在同一个 VM 用户下运行六个 GitHub Actions runner 服务，因此并发作业会共用同一目标目录。在复现运行中，三个作业在 73 毫秒内进入 pnpm 设置；其中一个设置过程删除了另一个进程的当前工作目录，导致两个作业在 Node 的 `uv_cwd` 初始化阶段失败。换到另一台 runner 重试后通过，说明该故障取决于时序，并非仓库测试回归。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index f071577bdd..9e195a4b1d 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.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 .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: efb37482270a7952f6af6596f9afd12f17048bcc
-2026-06-18-compaction-capability-seam.zh.md: 214832923c4e24835e7b25a5bbf2b1bcd62dff42
+2026-06-18-compaction-capability-seam.md: 8dcbe74429a620027a570124383442b969c12196
+2026-06-18-compaction-capability-seam.zh.md: 27b63f29c2e6f35637185b47c882ae42e5d41088
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index efb3748227..8dcbe74429 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
@@ -131,4 +131,4 @@ The lifecycle boundary makes crash state unambiguous:
 - **Loop:** Tests pin pre-step after the preceding `step/end` and before the next `step/start`, actual `agent/request` routing, closed failed steps, fresh retry numbering, and complete thrown/in-band overflow → compaction → reconstructed retry composition.
 - **Manual:** Maintenance serialization, marker ordering, injection retention, live/stale orphan classification, cancellation, close/flush failures, command mapping, and the queued TUI journey are pinned without a model key.
 - **With-key e2e:** A real model and bash session with lowered limits triggers compaction, records a complete `compact/start…end` pair, shrinks the surface, and finishes the task.
-- **Snapshot gap:** The summarization call is session-associated and logs `compact/summary`, but ordinary transcript replay does not derive its auxiliary response. [#1971](https://github.com/deepseek-harness/deepseek-harness/issues/1971) tracks a keyless assembled scenario with an explicit replay override.
+- **Snapshot gap:** The summarization call is session-associated and logs `compact/summary`, but ordinary transcript replay does not derive its auxiliary response; keyless assembled coverage therefore needs an explicit replay override.
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index 214832923c..27b63f29c2 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -131,4 +131,4 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 - **循环测试：** 测试固定 pre-step 发生在前一个 `step/end` 之后、下一个 `step/start` 之前，使用实际 `agent/request` 路由，关闭失败步骤，分配新的重试编号，并覆盖完整的抛出/带内溢出 → 压缩 → 重建重试组合。
 - **手动测试：** 无需模型密钥即可固定 maintenance 串行化、标记顺序、注入保留、活动／陈旧未匹配标记分类、取消、闭合／flush 失败、命令映射以及排队 TUI 流程。
 - **带密钥 e2e：** 真实模型和 bash 会话在降低的限制下触发压缩，记录完整的 `compact/start…end` 对，缩小 surface，并完成任务。
-- **快照缺口：** 摘要调用与会话关联并记录 `compact/summary`，但普通 transcript（文本记录）回放不会派生其辅助响应。[#1971](https://github.com/deepseek-harness/deepseek-harness/issues/1971) 跟踪一个带显式回放 override 的无密钥组装场景。
+- **快照缺口：** 摘要调用与会话关联并记录 `compact/summary`，但普通 transcript（文本记录）回放不会派生其辅助响应；因此，要实现无密钥的组装态覆盖，就必须显式提供回放 override。
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
index 6b0ce3f378..8a92dd2fd1 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.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 .agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
-2026-07-26-todo-parallel-in-progress.md: 2805ef894050d1b1cffe06fce59a4984d463f8d1
-2026-07-26-todo-parallel-in-progress.zh.md: 16b32daa05b10f24eacde4cec9622b2159cdef09
+2026-07-26-todo-parallel-in-progress.md: 8d047f33ab1aebd8c0de2a0a5e90e7efb1b28154
+2026-07-26-todo-parallel-in-progress.zh.md: 26b7081e7b4e3688a46a2857da91ba45328532a9
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
index 2805ef8940..8d047f33ab 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
@@ -37,7 +37,7 @@ The durable-log invariant deliberately does NOT follow the flag. A log written w
 
 ## The display surfaces are part of the change
 
-Lifting the cap makes a list shape reachable that no renderer had ever received, so this branch stacks on the [web todo display](2026-07-23-web-todo-display.md) rather than landing beside it: both change `tool-todo`, and the GUI is where a parallel plan becomes visible. Two web sites derived their one-line summary with `todos.find(t => t.status === 'in_progress')` — the collapsed plan-strip header and the `todo_write` row — and under the old cap that `find` was total, since at most one item could match. With several active it silently dropped every active item but the first: a four-item plan with three running tasks collapsed to the name of one, and the row read `1/4 已完成 · <one task>` while two others were in flight. The expanded list was always correct (it maps every item), which is why neither PR's tests caught it — only the collapsed header and the row lost information. The panel redesign in [#740](https://github.com/deepseek-harness/deepseek-harness/pull/740) has since replaced the collapsed header's named hint with `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted), which reports parallel work correctly and needs no name to truncate; the row is the one site this branch still had to fix.
+Lifting the cap makes a list shape reachable that no renderer had ever received, so this branch stacks on the [web todo display](2026-07-23-web-todo-display.md) rather than landing beside it: both change `tool-todo`, and the GUI is where a parallel plan becomes visible. Two web sites derived their one-line summary with `todos.find(t => t.status === 'in_progress')` — the collapsed plan-strip header and the `todo_write` row — and under the old cap that `find` was total, since at most one item could match. With several active it silently dropped every active item but the first: a four-item plan with three running tasks collapsed to the name of one, and the row read `1/4 已完成 · <one task>` while two others were in flight. The expanded list was always correct (it maps every item), which is why neither PR's tests caught it — only the collapsed header and the row lost information. The panel redesign replaced the collapsed header's named hint with `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted), which reports parallel work correctly and needs no name to truncate; the row is the one site this branch still had to fix.
 
 The row takes `planSummary` in `toolviews/plan-summary.ts`. It names the first active item and counts the rest, so the row reports how many tasks are running instead of implying one. Naming every active item was rejected: the row is a single line, and an unbounded join would overflow it — the count degrades predictably where a list does not. The derivation sits inside the toolviews domain rather than in `contract/`, the inter-domain face: the panel computes its own counts inline and shares nothing with the row, so a contract module would declare a sharing relationship that no longer exists.
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
index 16b32daa05..26b7081e7b 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
@@ -37,7 +37,7 @@ Status: implemented
 
 ## 展示面是本次改动的一部分
 
-解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本分支 stack（栈叠）在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个 PR 的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。其后 [#740](https://github.com/deepseek-harness/deepseek-harness/pull/740) 的面板重做已把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本分支仍需修的那一处。
+解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本分支 stack（栈叠）在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个 PR 的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。面板重做把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本分支仍需修的那一处。
 
 工具行改用 `toolviews/plan-summary.ts` 中的 `planSummary`。它给出第一个活跃条目，并计数其余活跃项，因此工具行报告的是有多少任务在跑，而不是暗示只有一个。列出全部活跃条目被否决了：工具行是单行，无上界的拼接会溢出——在列表做不到的地方，计数能够可预测地降级。该推导放在 toolviews 域内而非 `contract/`（域间共享面）：面板自行内联计算其计数，与工具行不共享任何东西，因此放进 contract 会声明一种已不存在的共享关系。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
index f06403d181..1ceb5a5213 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.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 .agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
-2026-07-30-queued-manual-compaction.md: 4b7a905712a01948146b8830dfc037185162eefc
-2026-07-30-queued-manual-compaction.zh.md: 15a42de3536f2da5304e77ce3cb282029856ba6d
+2026-07-30-queued-manual-compaction.md: 5100808ada4b7b284228113584e577d46ff91101
+2026-07-30-queued-manual-compaction.zh.md: 29c3b921d0d59527aa1d8af1c91d085b52045377
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
index 4b7a905712..5100808ada 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
@@ -75,7 +75,7 @@ Once a transaction has appended its start, every later failure makes one closing
 
 ### Reference implementation boundaries
 
-[PR #835](https://github.com/deepseek-harness/deepseek-harness/pull/835) was used as a reference implementation for the command, reservation, tests, and snapshot shape, but was not merged. Its process-local `WeakSet` lock and locked/unlocked method splits were considered and not adopted because the durable bracket is the single reachable lock.
+An unmerged reference implementation informed the command, reservation, tests, and snapshot shape. Its process-local `WeakSet` lock and locked/unlocked method splits were considered and not adopted because the durable bracket is the single reachable lock.
 
 That reference also carried client-side replacement-anchor machinery to preserve transcript placement. The log-ordered transcript projection already consumes compaction from event order and does not consult mutable surface positions, so those anchors were considered and not adopted.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
index 15a42de353..29c3b921d0 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
@@ -75,7 +75,7 @@ DSH 有意在调用摘要器前记录 `compact/start`。缓慢或崩溃的尝试
 
 ### 参考实现边界
 
-[PR #835](https://github.com/deepseek-harness/deepseek-harness/pull/835) 用作命令、预留、测试与快照结构的参考实现，但未被合并。它的进程本地 `WeakSet` 锁与 locked／unlocked 方法拆分经过评估后未被采用，因为持久标记对是唯一可达的锁。
+一个未合并的参考实现为命令、预留、测试与快照结构提供了参考。它的进程本地 `WeakSet` 锁与 locked／unlocked 方法拆分经过评估后未被采用，因为持久标记对是唯一可达的锁。
 
 该参考实现还包含客户端侧替换锚点机制，用于保留 transcript（文本记录）位置。按日志顺序排列的 transcript 投影已经从事件顺序消费压缩，并且不会查询可变 surface 位置，因此这些锚点经过评估后未被采用。
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
index dcb3a9406b..51401adfdc 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.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 .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
-2026-08-05-pwsh-ui-bash-parity.md: 6bbdb0e6bc69ef1af03a6a9146f83b84754cb2a6
-2026-08-05-pwsh-ui-bash-parity.zh.md: 75f3a3ddec002acaa1755c81114b0f122ab80593
+2026-08-05-pwsh-ui-bash-parity.md: 815b448b894e9c53b4c4a2076f6b94fdd316dd35
+2026-08-05-pwsh-ui-bash-parity.zh.md: 967c5a9e1409028043dc5028fdca640ddfeb1acc
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
index 6bbdb0e6bc..815b448b89 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-05-pwsh-ui-bash-parity.zh.md)
 
 ## Problem
 
-The [pwsh tool bash parity decision](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) made `dsh-tool-pwsh` behaviorally interchangeable with `dsh-tool-bash` for execution, markers, and background tasks, but explicitly deferred the human-visible half: a completed pwsh foreground call presented as a generic `console`-fenced card while the bash tool's completed call presented as a terminal card with a parsed exit-status pill. The roadmap that owned this gap ([Windows defaults to pwsh](../../proposed/feature/2026-08-01-windows-pwsh-default.md)) named "pwsh TUI/GUI rendering" as stage 2 — but the TUI package was removed ([`ed30088adb`](https://github.com/deepseek-harness/deepseek-harness/commit/ed30088adb)), leaving the Web surface as the only UI the gap affects.
+The [pwsh tool bash parity decision](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) made `dsh-tool-pwsh` behaviorally interchangeable with `dsh-tool-bash` for execution, markers, and background tasks, but explicitly deferred the human-visible half: a completed pwsh foreground call presented as a generic `console`-fenced card while the bash tool's completed call presented as a terminal card with a parsed exit-status pill. The roadmap that owned this gap ([Windows defaults to pwsh](../../proposed/feature/2026-08-01-windows-pwsh-default.md)) named "pwsh TUI/GUI rendering" as stage 2, but the TUI package was removed, leaving the Web surface as the only UI the gap affects.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
index 75f3a3ddec..967c5a9e14 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-[pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 让 `dsh-tool-pwsh` 在执行、marker 与后台任务上行为可互换，但明确推迟了面向人类的一半：完成的 pwsh 前台调用呈现为通用 `console` 围栏卡片，而 bash 工具的完成调用呈现为带解析退出状态 pill 的 terminal 卡。拥有此缺口的路线图（[Windows 默认改用 pwsh](../../proposed/feature/2026-08-01-windows-pwsh-default.md)）把 "pwsh TUI/GUI 渲染" 列为阶段 2——但 TUI 包已被移除（[`ed30088adb`](https://github.com/deepseek-harness/deepseek-harness/commit/ed30088adb)），Web 表面成为该缺口唯一影响的 UI。
+[pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 让 `dsh-tool-pwsh` 在执行、marker 与后台任务上行为可互换，但明确推迟了面向人类的一半：完成的 pwsh 前台调用呈现为通用 `console` 围栏卡片，而 bash 工具的完成调用呈现为带解析退出状态 pill 的 terminal 卡。拥有此缺口的路线图（[Windows 默认改用 pwsh](../../proposed/feature/2026-08-01-windows-pwsh-default.md)）把 "pwsh TUI/GUI 渲染" 列为阶段 2，但 TUI 包已被移除，使 Web 表面成为该缺口唯一影响的 UI。
 
 ## Decision
 
diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml
index 7fa4d3fbba..07e0a89d0f 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.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 .agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
-2026-07-13-documentation-site-projection.md: f19d9b309aa22821a75086dc07ee302097631ba0
-2026-07-13-documentation-site-projection.zh.md: cc5e94e709f0639fd35ad81165b199cc5c9effc0
+2026-07-13-documentation-site-projection.md: d9af915754fa6a1df51a27d18d412597472aaa73
+2026-07-13-documentation-site-projection.zh.md: 5b6de4b3425b6d20335a0f8055468ced414d4034
diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
index f19d9b309a..d9af915754 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
@@ -18,7 +18,9 @@ Canonical Markdown remains in the repository tier that owns it. Product-facing g
 
 Locale home projections retain only the canonical YAML frontmatter. The repository-facing body can keep its H1 and bilingual source links, while the VitePress home theme owns the rendered hero and features and the site navigation owns locale switching.
 
-The projector parses Markdown links without reserializing the document. A link to another published source becomes a site-relative route; a link to an unpublished repository file becomes a GitHub source link; a repository image is copied into the generated tree and referenced from there ([why](2026-08-06-doc-site-carries-its-images.md)). Missing relative targets fail projection. Unit tests pin these transformations, and `docs:check` runs the projector tests plus a production VitePress build as part of `doc-sync` and the parallel documentation gates.
+The projector parses Markdown links without reserializing the document. A link to another published source becomes a site-relative route; a link to an unpublished repository file becomes a source link under the public `deepseek-ai/deepseek-harness-sdk` home; a repository image is copied into the generated tree and referenced from there ([why](2026-08-06-doc-site-carries-its-images.md)). Missing relative targets fail projection. Unit tests pin these transformations, and `docs:check` runs the projector tests plus a production VitePress build as part of `doc-sync` and the parallel documentation gates.
+
+`verify-public-repository-links` rejects internal repository remotes from tracked files. Public source links use the public home, while work tracking stays in repository metadata and source carries a TODO only when the local boundary matters to maintainers.
 
 `website/AGENTS.md` is the only maintained Markdown file in the website subtree. The projector test enumerates tracked and unignored files and rejects any other website Markdown, so site-specific locale, route, API, or generated source copies cannot bypass the publication manifest.
 
diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
index cc5e94e709..5b6de4b342 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
@@ -18,7 +18,9 @@ Status: implemented
 
 各 locale 的首页投影只保留权威 YAML frontmatter。面向仓库的正文可以保留其 H1 和双语源文件链接，而 VitePress 首页主题负责渲染 hero 与功能区，网站导航负责切换 locale。
 
-投影器解析 Markdown 链接，但不会重新序列化文档。指向另一个已发布源文件的链接会变成站内相对路由；指向未发布仓库文件的链接会变成 GitHub 源文件链接；仓库图片会被拷贝进生成树并从那里引用（[原因](2026-08-06-doc-site-carries-its-images.md)）。相对目标不存在时，投影会失败。单元测试会锁定这些转换行为，`docs:check` 则运行投影器测试和 VitePress 生产构建，并将二者纳入 `doc-sync` 和并行文档门禁。
+投影器解析 Markdown 链接，但不会重新序列化文档。指向另一个已发布源文件的链接会变成站内相对路由；指向未发布仓库文件的链接会变成公开 `deepseek-ai/deepseek-harness-sdk` 主页下的源文件链接；仓库图片会被拷贝进生成树并从那里引用（[原因](2026-08-06-doc-site-carries-its-images.md)）。相对目标不存在时，投影会失败。单元测试会锁定这些转换行为，`docs:check` 则运行投影器测试和 VitePress 生产构建，并将二者纳入 `doc-sync` 和并行文档门禁。
+
+`verify-public-repository-links` 会拒绝已跟踪文件中的内部仓库远程链接。公开源文件链接使用公开主页，而工作跟踪留在仓库元数据中；只有本地边界对维护者有意义时，源文件才保留 TODO。
 
 `website/AGENTS.md` 是网站子树中唯一维护的 Markdown 文件。投影器测试会枚举所有已跟踪文件和未被忽略的未跟踪文件，并拒绝网站中的任何其他 Markdown，因此网站专用的 locale、路由、API 或生成源文件副本无法绕过发布 manifest。
 
diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml
index 8ccd5ca13e..1dc5d79676 100644
--- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.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 .agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md
-2026-07-22-evidence-based-larger-hosted-runners.md: d46b8291ec05e997728da76354354f9e36bd2fb4
-2026-07-22-evidence-based-larger-hosted-runners.zh.md: f43712859d8351ffff45c7b6d5eb2b65015ee4c3
+2026-07-22-evidence-based-larger-hosted-runners.md: 53cc86efce9061c8f9836a17cb35ebb128085b7a
+2026-07-22-evidence-based-larger-hosted-runners.zh.md: 0484548c76cb7eed11dc4235ef024a700499ef6a
diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md
index d46b8291ec..53cc86efce 100644
--- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md
+++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md
@@ -26,7 +26,7 @@ The artifact boundary remains explicit. `scripts/publint-all.ts` calls publint's
 
 Windows shares one 32-core setup across the blocking build and production site plus observational built-artifact contracts. Linux owns the duplicate lint, coverage, and snapshot inventories because running those observational copies on Windows extends the paid critical path without adding a blocking platform claim.
 
-An [exact-head all-size benchmark](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29908491351) ran the complete unsharded primary Node aggregate on every Linux pool before the eager-build correction:
+An exact-head all-size benchmark ran the complete unsharded primary Node aggregate on every Linux pool before the eager-build correction:
 
 | Complete Linux primary | 4 cores | 8 cores | 16 cores | 32 cores | 64 cores | 96 cores |
 |---|---:|---:|---:|---:|---:|---:|
@@ -40,13 +40,13 @@ The same benchmark measured the required Windows build surfaces across every pro
 |---|---:|---:|---:|---:|---:|---:|
 | Active time | 152 s | 104 s | 104 s | 92 s | 103 s | 110 s |
 
-Repository work gains little above 16 Windows cores, but the 32-core pool can start the complete outer inventory together. A [retargeted production validation](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29907581119/attempts/2) completed the full one-box Windows inventory in 173 seconds, including coverage and snapshot replay, so Windows remains consolidated.
+Repository work gains little above 16 Windows cores, but the 32-core pool can start the complete outer inventory together. A retargeted production validation completed the full one-box Windows inventory in 173 seconds, including coverage and snapshot replay, so Windows remains consolidated.
 
-The larger client package graph makes cache mechanics and scheduler pressure part of the measured workload. In [one exact-head candidate run](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29912577681), Linux spent 39 seconds in repository gates but 69 seconds in the complete job, while Windows spent 117 seconds in repository gates and 228 seconds in the complete job. The Windows pnpm cache downloaded its 154 MB archive in about two seconds but spent 27 seconds extracting it, followed by a 23-second install and a 14-second post-job save. A [cacheless all-size trace](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29913033155) completed the same 32-core Windows install in 27 seconds. A future larger-runner rollout therefore needs complete-job measurements rather than gate-only timing.
+The larger client package graph makes cache mechanics and scheduler pressure part of the measured workload. In one exact-head candidate run, Linux spent 39 seconds in repository gates but 69 seconds in the complete job, while Windows spent 117 seconds in repository gates and 228 seconds in the complete job. The Windows pnpm cache downloaded its 154 MB archive in about two seconds but spent 27 seconds extracting it, followed by a 23-second install and a 14-second post-job save. A cacheless all-size trace completed the same 32-core Windows install in 27 seconds. A future larger-runner rollout therefore needs complete-job measurements rather than gate-only timing.
 
 Host setup remains part of any comparison. A standard Node 26 job once spent 36 of its 67 seconds in `Set up job`, while `actions/setup-node` spent 46.56 seconds printing cached Windows environment details after finding Node in the hosted toolcache. A Linux candidate also spent 18 seconds registering a 50 KB Bubblewrap package because the hosted image scanned 202,507 package-database files. [`scripts/prepare-ci-bubblewrap.sh`](../../../../scripts/prepare-ci-bubblewrap.sh) instead verifies and extracts the pinned payload into the ephemeral runner directory, runs a functional confinement probe, and overlaps that preparation with dependency installation.
 
-Inner and outer worker limits are separate controls. An [exact-head 32-worker ESLint experiment](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29918329463) slowed lint to 52.28 seconds and coverage to 42.71 seconds, where an adapter idle-timeout test failed. A later 8-gate trace reduced coverage to 35.17 seconds but delayed the production-site build until the aggregate reached 41.06 seconds. Core count therefore does not justify copying an equally large worker limit.
+Inner and outer worker limits are separate controls. An exact-head 32-worker ESLint experiment slowed lint to 52.28 seconds and coverage to 42.71 seconds, where an adapter idle-timeout test failed. A later 8-gate trace reduced coverage to 35.17 seconds but delayed the production-site build until the aggregate reached 41.06 seconds. Core count therefore does not justify copying an equally large worker limit.
 
 The process-bound coverage project contains exactly five suite files. Thirty-two forks crashed Node 24's CJS lexer twice, and a later 16-fork run reproduced the worker loss and invalid coverage result. The single Vitest invocation therefore uses threads for the broad inventory and reserves forks for suites that exercise process-global state, `process` APIs, or timing-sensitive process I/O. That narrow fork inventory includes the local bash process-plumbing suite and the pi-ai adapter suite because aggregate contention changed timing observations in both. These failures make deterministic coverage, not advertised cores, the upper bound on worker selection.
 
diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md
index f43712859d..0484548c76 100644
--- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md
@@ -26,7 +26,7 @@ Linux 主流程使用 3 个相互独立的 32 核作业。覆盖率单独运行
 
 Windows 以一次 32 核环境设置同时承载阻塞性构建、生产网站和观测性的构建产物契约。重复的 lint、覆盖率和快照清单由 Linux 承担，因为在 Windows 上运行这些观测性副本会延长付费关键路径，却不会新增任何阻塞性平台契约。
 
-一次[分支头精确的全规格基准测试](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29908491351)在修正构建尽早启动逻辑前，对每种 Linux 池都运行了完整且未分片的主 Node 聚合流程：
+一次分支头精确的全规格基准测试在修正构建尽早启动逻辑前，对每种 Linux 池都运行了完整且未分片的主 Node 聚合流程：
 
 | Linux 完整主流程 | 4 核 | 8 核 | 16 核 | 32 核 | 64 核 | 96 核 |
 |---|---:|---:|---:|---:|---:|---:|
@@ -40,13 +40,13 @@ Windows 以一次 32 核环境设置同时承载阻塞性构建、生产网站
 |---|---:|---:|---:|---:|---:|---:|
 | 活动耗时 | 152 秒 | 104 秒 | 104 秒 | 92 秒 | 103 秒 | 110 秒 |
 
-Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完整的外层清单同时启动。一次[重新定向的生产验证](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29907581119/attempts/2)在 173 秒内完成了单机 Windows 完整清单，其中包括覆盖率和快照回放，因此 Windows 继续采用合并执行方式。
+Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完整的外层清单同时启动。一次重新定向的生产验证在 173 秒内完成了单机 Windows 完整清单，其中包括覆盖率和快照回放，因此 Windows 继续采用合并执行方式。
 
-客户端包依赖图增大后，缓存机制和调度器压力也成为实测工作负载的一部分。在[一次分支头精确的候选运行](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29912577681)中，Linux 的仓库门禁耗时 39 秒，完整作业耗时 69 秒；Windows 的仓库门禁耗时 117 秒，完整作业耗时 228 秒。Windows pnpm 缓存的 154 MB 归档下载耗时约 2 秒，但解压耗时 27 秒，随后安装耗时 23 秒，作业结束后的保存又耗时 14 秒。一次[无缓存的全规格运行轨迹](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29913033155)在 27 秒内完成了同一台 32 核 Windows 运行器上的安装。因此，未来若要启用大型运行器，需要测量完整作业，而不能只测门禁耗时。
+客户端包依赖图增大后，缓存机制和调度器压力也成为实测工作负载的一部分。在一次分支头精确的候选运行中，Linux 的仓库门禁耗时 39 秒，完整作业耗时 69 秒；Windows 的仓库门禁耗时 117 秒，完整作业耗时 228 秒。Windows pnpm 缓存的 154 MB 归档下载耗时约 2 秒，但解压耗时 27 秒，随后安装耗时 23 秒，作业结束后的保存又耗时 14 秒。一次无缓存的全规格运行轨迹在 27 秒内完成了同一台 32 核 Windows 运行器上的安装。因此，未来若要启用大型运行器，需要测量完整作业，而不能只测门禁耗时。
 
 任何比较都必须计入主机设置。一个标准 Node 26 作业曾在总共 67 秒的耗时中，把 36 秒用在 `Set up job` 上；`actions/setup-node` 从托管 toolcache 找到 Node 后，仍花费 46.56 秒输出缓存的 Windows 环境详情。一个 Linux 候选作业还在注册 50 KB 的 Bubblewrap 包时耗时 18 秒，因为托管映像扫描了 202,507 个包数据库文件。[`scripts/prepare-ci-bubblewrap.sh`](../../../../scripts/prepare-ci-bubblewrap.sh) 改为验证固定版本的 payload 并将其解压到临时运行器目录，执行功能性隔离探针，并让这项准备工作与依赖安装重叠执行。
 
-内层与外层工作线程上限是相互独立的控制机制。一次[分支头精确、使用 32 个工作线程的 ESLint 实验](https://github.com/deepseek-harness/deepseek-harness/actions/runs/29918329463)使 lint 耗时增至 52.28 秒、覆盖率耗时增至 42.71 秒；同一次运行中，一项适配器空闲超时测试失败。后来一次同时运行 8 项门禁的运行轨迹将覆盖率耗时降至 35.17 秒，但生产网站构建被延后，直到聚合流程耗时达到 41.06 秒时才完成。因此，不能仅凭核心数照搬同等规模的工作线程上限。
+内层与外层工作线程上限是相互独立的控制机制。一次分支头精确、使用 32 个工作线程的 ESLint 实验使 lint 耗时增至 52.28 秒、覆盖率耗时增至 42.71 秒；同一次运行中，一项适配器空闲超时测试失败。后来一次同时运行 8 项门禁的运行轨迹将覆盖率耗时降至 35.17 秒，但生产网站构建被延后，直到聚合流程耗时达到 41.06 秒时才完成。因此，不能仅凭核心数照搬同等规模的工作线程上限。
 
 进程约束的覆盖率项目恰好包含 5 个套件文件。32 个 fork 曾两次导致 Node 24 的 CJS 词法分析器崩溃，后来一次使用 16 个 fork 的运行又复现了工作进程丢失和无效的覆盖率结果。因此，单次 Vitest 调用会对大范围测试清单使用线程，只为涉及进程全局状态、`process` API 或对时间敏感的进程 I/O 的套件保留 fork。这份有限的 fork 清单包括本地 bash 进程通路套件和 pi-ai 适配器套件，因为聚合争用改变了二者的时序观测结果。这些故障表明，选择工作线程数量时，上限取决于能否得到确定的覆盖率结果，而非标称核心数。
 
diff --git a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml
index be725fc905..ac859f10dd 100644
--- a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.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 .agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md
-2026-07-26-briefed-minimal-translation-updates.md: a47251376771165d0eb229aaa0fb7f63589d7d77
-2026-07-26-briefed-minimal-translation-updates.zh.md: c3c1b4e845b5a45acde55884b883b1dd1e570d77
+2026-07-26-briefed-minimal-translation-updates.md: afd990b7b63adfd0e66a4726975b678d044e7cad
+2026-07-26-briefed-minimal-translation-updates.zh.md: dcdb253746041a7928ab7a544ae427293bc3f2de
diff --git a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md
index a472513767..afd990b7b6 100644
--- a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md
+++ b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md
@@ -12,7 +12,7 @@ The [bilingual pairing contract](2026-07-02-bilingual-docs-and-pairing-gate.md)
 
 Pair updates run on a generated briefing instead of the guidance corpus; only new pairs still run the whole-document workflow, which is unchanged.
 
-- **`pnpm run gen-translation-brief [--apply] [pair...]`** ([scripts/gen-translation-brief.ts](../../../../scripts/gen-translation-brief.ts), assembly in [scripts/translation-brief.ts](../../../../scripts/translation-brief.ts)) prints, per out-of-sync pair, the authored side's diff from its recorded last-confirmed blob to the working tree plus the change mapped at the narrowest safely aligned granularity, deterministically widening on mapping failure: a change confined to the pair's byte-identical code fences is computed outright (`--apply` splices it into the counterpart and validates the result against the pairing gate's structural signature before writing); otherwise changed Markdown units (headings, paragraphs, table rows, list items, code fences, block quotes, HTML blocks, thematic breaks, link definitions — matched by container-scoped kind sequences) each carry their last-confirmed source, current source, and current counterpart text with line numbers; units that do not align fall back to depth-matched heading sections; and when sections do not align either, or both sides drifted, the briefing says so and withholds the mapping instead of guessing. Terminology rows are matched against the changed spans only (word-boundary English matching with plural inflections), and for Chinese targets the briefing tracks each relevant term's document-wide first occurrence — when an edit moves it, the vacated and receiving spans join the briefing with an explanatory note, since the 首次出现 annotation must move with it. The unit mapping, code splice, and first-occurrence mechanics adopt the planner design from the [incremental prompt-pipeline work](https://github.com/deepseek-harness/deepseek-harness/pull/684), whose provider-backed bake-off independently validated the same scope ladder for the automated pipeline. The briefing is the translator's whole working set; the full sources of truth remain the escalation path for decisions the briefing cannot answer.
+- **`pnpm run gen-translation-brief [--apply] [pair...]`** ([scripts/gen-translation-brief.ts](../../../../scripts/gen-translation-brief.ts), assembly in [scripts/translation-brief.ts](../../../../scripts/translation-brief.ts)) prints, per out-of-sync pair, the authored side's diff from its recorded last-confirmed blob to the working tree plus the change mapped at the narrowest safely aligned granularity, deterministically widening on mapping failure: a change confined to the pair's byte-identical code fences is computed outright (`--apply` splices it into the counterpart and validates the result against the pairing gate's structural signature before writing); otherwise changed Markdown units (headings, paragraphs, table rows, list items, code fences, block quotes, HTML blocks, thematic breaks, link definitions — matched by container-scoped kind sequences) each carry their last-confirmed source, current source, and current counterpart text with line numbers; units that do not align fall back to depth-matched heading sections; and when sections do not align either, or both sides drifted, the briefing says so and withholds the mapping instead of guessing. Terminology rows are matched against the changed spans only (word-boundary English matching with plural inflections), and for Chinese targets the briefing tracks each relevant term's document-wide first occurrence — when an edit moves it, the vacated and receiving spans join the briefing with an explanatory note, since the 首次出现 annotation must move with it. The unit mapping, code splice, and first-occurrence mechanics adopt the planner design from the incremental prompt-pipeline work; its provider-backed bake-off independently validated the same scope ladder for the automated pipeline. The briefing is the translator's whole working set; the full sources of truth remain the escalation path for decisions the briefing cannot answer.
 - **The update path in [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)** consumes the briefing: mechanical (code-fence-only) changes are applied with `--apply`, no subagent; prose diffs go to a subagent whose prompt is the briefing, not the corpus; verification is clause-by-clause on the changed spans, not the whole document.
 - **The pairing gate takes pair arguments.** `verify-translation-pairing [pair...]` checks just the named pairs (any of a pair's three files, or the bare stem, names it); the corpus-wide sweep remains the no-argument form that `doc-sync` and CI run. `--write` now requires naming the confirmed pairs — bare `--write` refuses, and re-recording everything is an explicit `--write --all` — because the old bare form silently blessed every drifted pair in the tree, including ones the caller never looked at, and a prose-only drift would then stay green forever. Each record's comment names its own scoped command. Before recording, `--write` stores each side's exact bytes with `git hash-object -w --stdin` and pins the blob under a content-addressed local `refs/dsh/translation-pairing/snapshots/` ref; an uncommitted last-confirmed snapshot is therefore available to the briefing generator's later `git cat-file`, not merely named by a hash that Git cannot resolve or left vulnerable to garbage collection.
 
diff --git a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md
index c3c1b4e845..dcdb253746 100644
--- a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 配对更新基于生成的简报（briefing）运行，而非基于指导语料；只有新建配对仍走整篇文档工作流，后者保持不变。
 
-- **`pnpm run gen-translation-brief [--apply] [pair...]`**（[scripts/gen-translation-brief.ts](../../../../scripts/gen-translation-brief.ts)，组装逻辑在 [scripts/translation-brief.ts](../../../../scripts/translation-brief.ts)）针对每个失去同步的配对，打印被改一侧从其记录在案的上次确认 blob 到当前工作区的 diff，并附上以能安全对齐的最窄粒度映射的这次改动，映射失败时粒度确定性地逐级放宽：仅落在配对中逐字节一致的围栏代码块内的改动会直接算出（`--apply` 会把它拼接进对侧文件，并在写入前用配对门禁的结构签名校验所得结果）；否则，每个有改动的 Markdown 单元（标题、段落、表格行、列表项、围栏代码块、块引用、HTML 块、分隔线、链接定义；匹配依据是以容器为作用域的种类序列）都带上各自的上次确认源文、当前源文与当前对侧文本及行号；无法对齐的单元回退到按深度匹配的标题章节；当章节也无法对齐或两侧同时漂移时，简报会明说这一点并省略映射，而不是靠猜。术语表行只与改动块匹配（英文术语按词边界匹配，含复数变形）；当目标侧是中文时，简报还会跟踪每个相关术语在整篇文档中的首次出现：一旦某次编辑使其移位，腾出的与接收的两处区间就会附一条解释性说明加入简报，因为「首次出现」括注必须随之移动。单元映射、代码拼接与首次出现机制采纳了[增量提示词流水线工作](https://github.com/deepseek-harness/deepseek-harness/pull/684)中的规划器设计；该项工作中接入提供方的对比评测，已为自动流水线独立验证了同一套范围阶梯。简报就是译者的全部工作集；简报回答不了的决策，仍以完整的真源文档作为升级求证路径。
+- **`pnpm run gen-translation-brief [--apply] [pair...]`**（[scripts/gen-translation-brief.ts](../../../../scripts/gen-translation-brief.ts)，组装逻辑在 [scripts/translation-brief.ts](../../../../scripts/translation-brief.ts)）针对每个失去同步的配对，打印被改一侧从其记录在案的上次确认 blob 到当前工作区的 diff，并附上以能安全对齐的最窄粒度映射的这次改动，映射失败时粒度确定性地逐级放宽：仅落在配对中逐字节一致的围栏代码块内的改动会直接算出（`--apply` 会把它拼接进对侧文件，并在写入前用配对门禁的结构签名校验所得结果）；否则，每个有改动的 Markdown 单元（标题、段落、表格行、列表项、围栏代码块、块引用、HTML 块、分隔线、链接定义；匹配依据是以容器为作用域的种类序列）都带上各自的上次确认源文、当前源文与当前对侧文本及行号；无法对齐的单元回退到按深度匹配的标题章节；当章节也无法对齐或两侧同时漂移时，简报会明说这一点并省略映射，而不是靠猜。术语表行只与改动块匹配（英文术语按词边界匹配，含复数变形）；当目标侧是中文时，简报还会跟踪每个相关术语在整篇文档中的首次出现：一旦某次编辑使其移位，腾出的与接收的两处区间就会附一条解释性说明加入简报，因为「首次出现」括注必须随之移动。单元映射、代码拼接与首次出现机制采纳了增量提示词流水线工作的规划器设计；该项工作中接入提供方的对比评测，已为自动流水线独立验证了同一套范围阶梯。简报就是译者的全部工作集；简报回答不了的决策，仍以完整的真源文档作为升级求证路径。
 - **[dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 中的更新路径**消费这份简报：机械类改动（只涉及围栏代码块）用 `--apply` 应用，不动用 subagent；行文类 diff 交给 subagent，其提示词就是简报本身，而非指导语料；核验只对改动块逐句进行，不覆盖整篇文档。
 - **配对门禁接受配对参数。**`verify-translation-pairing [pair...]` 只检查被点名的配对（配对三个文件中的任意一个，或其裸词干，都能指代该配对）；全语料扫描仍是 `doc-sync`（文档同步门禁）与 CI 运行的无参数形式。`--write` 现在要求点名已确认的配对：裸 `--write` 会拒绝执行，重新记录全部配对必须显式写 `--write --all`；原因是旧的裸形式会默默为树中每一个漂移的配对背书，包括调用者从未看过的那些，纯行文层面的漂移于是可以永远保持绿灯。每份记录的注释都写明针对该配对自身的按对命令。写下记录之前，`--write` 用 `git hash-object -w --stdin` 存入每一侧的精确字节，并在内容寻址的本地 `refs/dsh/translation-pairing/snapshots/` ref 下固定该 blob；未提交的上次确认快照因此能被简报生成器之后的 `git cat-file` 取回，而不只是留下一个 Git 无法解析的 hash 名称或暴露于垃圾回收。
 
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
index 4786909a7f..19945a6580 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.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 .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
-2026-07-27-wine-windows-gates-experiment.md: 640c8e455b1a35ea4ac83454227147b9979316dc
-2026-07-27-wine-windows-gates-experiment.zh.md: 67f59a93d1b1fad98e36e6f9c51bc77abb9e3d07
+2026-07-27-wine-windows-gates-experiment.md: 1b01fe00dc1588482442a3cedc35eefa7fdb0975
+2026-07-27-wine-windows-gates-experiment.zh.md: b50739f5b63c5836248c94927037e38900abc84f
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
index 640c8e455b..1b01fe00dc 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
@@ -14,7 +14,7 @@ The question the experiment answered: can a plain Linux runner produce an equiva
 
 The required pull-request `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) (`windows node 24 / wine blocking`) runs the blocking gate commands on `ubuntu-latest` under Wine with real Windows binaries: a checksum-verified win-x64 Node.js executes `tsc -b`, `tsdown`, and the VitePress production build, so the win32 branches of the toolchain — backslash path handling, `CreateProcess` spawn semantics, PE loading of `@esbuild/win32-x64`, and the rolldown/rollup MSVC `.node` addons — actually execute. The master `serial-windows` job is untouched: the complete native-kernel inventory, including the observational portability gates this lane does not run, still executes on real `windows-2025` on every master push.
 
-Dependencies install natively on Linux with `supportedArchitectures` extended to win32-x64, which materializes the Windows platform packages in the same store; the cmd-shim layer is bypassed by invoking each tool's JavaScript entrypoint directly, the same processes `run-gates` ultimately spawns. `nodeLinker: hoisted` is load-bearing, not stylistic: the independent prototype in [PR #689](https://github.com/deepseek-harness/deepseek-harness/pull/689) kept pnpm's default isolated layout — including a faithful offline Windows-pnpm re-install over a Linux-prefetched store — and Windows Node under Wine still could not resolve `@esbuild/win32-x64` or load the koffi prebuild through the isolated symlink chain, failing before any repository gate ran. A flat layout with real files is what makes the gates reachable at all; #689's checksum pinning is adopted, while its Windows-pnpm-installs-the-tree goal is explicitly given up (the install contract stays Linux-tested here).
+Dependencies install natively on Linux with `supportedArchitectures` extended to win32-x64, which materializes the Windows platform packages in the same store; the cmd-shim layer is bypassed by invoking each tool's JavaScript entrypoint directly, the same processes `run-gates` ultimately spawns. `nodeLinker: hoisted` is load-bearing, not stylistic: an independent prototype kept pnpm's default isolated layout — including a faithful offline Windows-pnpm re-install over a Linux-prefetched store — and Windows Node under Wine still could not resolve `@esbuild/win32-x64` or load the koffi prebuild through the isolated symlink chain, failing before any repository gate ran. A flat layout with real files is what makes the gates reachable at all; the prototype's checksum pinning is adopted, while its Windows-pnpm-installs-the-tree goal is explicitly given up (the install contract stays Linux-tested here).
 
 The lane holds the wall clock of the Linux CI jobs through four levers: the master-refreshed pnpm store cache (restore-only, same key as the Linux jobs), Wine provisioning (apt install, Windows Node download, `wineboot`) running concurrently with `pnpm install`, the two blocking surfaces running concurrently — the same shape `run-gates` gives them on native Windows — and an apt-archive cache keyed on the runner image, seeded from master by the `wine apt cache` job so every pull request restores from the default-branch scope.
 
@@ -32,7 +32,7 @@ Measured on 2026-07-27, warm caches, pull-request trigger, standard 2-core `ubun
 
 **A full Windows guest under QEMU/KVM inside the Linux runner.** Real NT kernel, so full fidelity including case-insensitive NTFS and ConPTY — but tens of minutes of image download and unattended install before the first gate runs (40m19s measured end-to-end on the sibling experiment branch `exp/kvm-windows-ci`). Promotable only with disk-image caching that pressures the Actions cache budget.
 
-**Windows pnpm performing the install under Wine ([PR #689](https://github.com/deepseek-harness/deepseek-harness/pull/689)).** The higher-fidelity variant of this same idea: MinGit and pnpm staged into the prefix, a Linux prefetch filling the store, then `pnpm install --offline` run by Windows Node so the install contract itself executes as win32. It reached the install but not the gates — Wine's networking could not reach the registry directly, and the isolated `node_modules` layout defeated resolution of the Windows platform packages even after a clean offline install. This lane trades that fidelity away (hoisted layout, Linux-side install) to reach the gates; the two records are complementary halves of the same verdict.
+**Windows pnpm performing the install under Wine.** The higher-fidelity variant of this same idea: MinGit and pnpm staged into the prefix, a Linux prefetch filling the store, then `pnpm install --offline` run by Windows Node so the install contract itself executes as win32. It reached the install but not the gates — Wine's networking could not reach the registry directly, and the isolated `node_modules` layout defeated resolution of the Windows platform packages even after a clean offline install. This lane trades that fidelity away (hoisted layout, Linux-side install) to reach the gates; the two records are complementary halves of the same verdict.
 
 **Filesystem-semantics lanes on Linux (casefolded ext4, filename lint).** Catches the highest-frequency Windows breakage class for near-zero cost but proves nothing about win32 binaries. Explored as the sibling experiment branch `exp/casefold-windows-ci`; complementary to, not competitive with, this lane.
 
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
index 67f59a93d1..b50739f5b6 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
@@ -14,7 +14,7 @@ Pull request 的 Windows 通道旨在验证两个阻断性 win32 表面，即 wo
 
 [ci.yml](../../../../.github/workflows/ci.yml) 中必需的 pull request `windows` 作业（`windows node 24 / wine blocking`）在 `ubuntu-latest` 上通过 Wine 用真实 Windows 二进制运行阻断门禁命令：校验和验证过的 win-x64 Node.js 执行 `tsc -b`、`tsdown` 与 VitePress 生产构建，因此工具链的 win32 分支——反斜杠路径处理、`CreateProcess` 派生语义、`@esbuild/win32-x64` 的 PE 加载、以及 rolldown/rollup 的 MSVC `.node` 插件——都真正执行。master 的 `serial-windows` 作业原封不动：完整的原生内核清单，包括本通道不运行的观察性可移植性门禁，仍在每次 master push 时于真实 `windows-2025` 上执行。
 
-依赖在 Linux 上原生安装，`supportedArchitectures` 扩展到 win32-x64，使 Windows 平台包物化进同一个 store；通过直接调用各工具的 JavaScript 入口绕开 cmd-shim 层，这正是 `run-gates` 最终派生的那些进程。`nodeLinker: hoisted` 是承重的，不是风格问题：[PR #689](https://github.com/deepseek-harness/deepseek-harness/pull/689) 的独立原型保留了 pnpm 默认的 isolated 布局——包括在 Linux 预取的 store 上忠实地用 Windows pnpm 离线重装——而 Wine 下的 Windows Node 依然无法穿过 isolated 符号链接链解析 `@esbuild/win32-x64` 或加载 koffi 预编译产物，在任何仓库门禁运行前就失败了。扁平的真实文件布局才让门禁变得可达；本通道采纳了 #689 的校验和固定，同时明确放弃其「Windows pnpm 安装依赖树」的目标（安装契约在此仍由 Linux 侧验证）。
+依赖在 Linux 上原生安装，`supportedArchitectures` 扩展到 win32-x64，使 Windows 平台包物化进同一个 store；通过直接调用各工具的 JavaScript 入口绕开 cmd-shim 层，这正是 `run-gates` 最终派生的那些进程。`nodeLinker: hoisted` 是承重的，不是风格问题：一个独立原型保留了 pnpm 默认的 isolated 布局——包括在 Linux 预取的 store 上忠实地用 Windows pnpm 离线重装——而 Wine 下的 Windows Node 依然无法穿过 isolated 符号链接链解析 `@esbuild/win32-x64` 或加载 koffi 预编译产物，在任何仓库门禁运行前就失败了。扁平的真实文件布局才让门禁变得可达；本通道采纳了该原型的校验和固定，同时明确放弃其「Windows pnpm 安装依赖树」的目标（安装契约在此仍由 Linux 侧验证）。
 
 该通道靠四个杠杆把墙钟时间保持在与 Linux CI 作业相当的水平：master 刷新的 pnpm store 缓存（只恢复，与 Linux 作业同键）、Wine 供给（apt 安装、Windows Node 下载、`wineboot`）与 `pnpm install` 并发运行、两个阻断表面并发运行——与 `run-gates` 在原生 Windows 上给它们的形状相同——以及按 runner 镜像为键的 apt 归档缓存，由 master 的 `wine apt cache` 作业播种，使每个 pull request 都能从默认分支作用域恢复。
 
@@ -32,7 +32,7 @@ Pull request 的 Windows 通道旨在验证两个阻断性 win32 表面，即 wo
 
 **在 Linux runner 内用 QEMU/KVM 跑完整 Windows 客户机。** 真实 NT 内核，保真度完整，包括大小写不敏感的 NTFS 与 ConPTY——但首个门禁运行前要花数十分钟下载镜像并做无人值守安装（兄弟实验分支 `exp/kvm-windows-ci` 实测端到端 40 分 19 秒）。只有配上会挤压 Actions 缓存预算的磁盘镜像缓存才可投入使用。
 
-**在 Wine 下由 Windows pnpm 执行安装（[PR #689](https://github.com/deepseek-harness/deepseek-harness/pull/689)）。** 同一想法的更高保真度变体：把 MinGit 与 pnpm 放进 prefix，用 Linux 预取填充 store，再由 Windows Node 运行 `pnpm install --offline`，让安装契约本身以 win32 身份执行。它到达了安装但没到达门禁——Wine 的网络无法直接访问 registry，且 isolated 的 `node_modules` 布局即便在干净的离线安装后也挫败了 Windows 平台包的解析。本通道牺牲这份保真度（hoisted 布局、Linux 侧安装）来换取门禁可达；两份记录是同一裁决互补的两半。
+**在 Wine 下由 Windows pnpm 执行安装。** 同一想法的更高保真度变体：把 MinGit 与 pnpm 放进 prefix，用 Linux 预取填充 store，再由 Windows Node 运行 `pnpm install --offline`，让安装契约本身以 win32 身份执行。它到达了安装但没到达门禁——Wine 的网络无法直接访问 registry，且 isolated 的 `node_modules` 布局即便在干净的离线安装后也挫败了 Windows 平台包的解析。本通道牺牲这份保真度（hoisted 布局、Linux 侧安装）来换取门禁可达；两份记录是同一裁决互补的两半。
 
 **Linux 上的文件系统语义通道（casefold ext4、文件名 lint）。** 以近零成本捕获最高频的 Windows 故障类别，但对 win32 二进制什么也证明不了。作为兄弟实验分支 `exp/casefold-windows-ci` 探索；与本通道互补而非竞争。
 
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
index 79ea52067d..77003539ac 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.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 .agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
-2026-07-31-installer-adopts-existing-checkout.md: ff02fe837f2ad4deb3fb852f610f3cd3ff9a23d7
-2026-07-31-installer-adopts-existing-checkout.zh.md: 28816c80764acc0d4a2fcd13b3b8a38807021fd6
+2026-07-31-installer-adopts-existing-checkout.md: 3a213a6232e57f305910240505983421dcd288ad
+2026-07-31-installer-adopts-existing-checkout.zh.md: 7cdcd5549fb2bca2a6cb11f0cf2867687565ae79
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
index ff02fe837f..3a213a6232 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
@@ -46,6 +46,6 @@ A container adopting an outside clone is also no longer self-contained: deleting
 
 ## Testing
 
-`scripts/install.sh` now has a real-shell PTY regression suite in `apps/cli/tests/install-script.spec.ts`, covering adoption and curl-style paths with stubbed dependencies. The installer's longer-term deletion in favor of pnpm/npx is tracked in [#1890](https://github.com/deepseek-harness/deepseek-harness/issues/1890).
+`scripts/install.sh` now has a real-shell PTY regression suite in `apps/cli/tests/install-script.spec.ts`, covering adoption and curl-style paths with stubbed dependencies. Curl-style installs default to the public `deepseek-ai/deepseek-harness-sdk` source, while replacing the installer with pnpm/npx remains separate work.
 
 Verification was manual, through a throwaway harness driving the real script with a stubbed `pnpm`: adopting a standalone clone; adopting from a linked worktree into its existing container; an explicit `DSH_SOURCE` still opting back into cloning; a dirty tree adopting silently with no prompt or warning while its uncommitted file stays behind; a non-git checkout failing with guidance; and a `curl`-style clone install asserting the built layout, which is the regression that caught the unresolved-`REPO_ROOT` defect. The interactive path was exercised under tmux from a dirty checkout, confirming the run reaches the launcher with no adoption prompt and ends with `dsh` running from the new staging worktree while the original checkout keeps its branch and its uncommitted file.
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
index 28816c8076..7cdcd5549f 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
@@ -46,6 +46,6 @@ Status: implemented
 
 ## Testing
 
-`scripts/install.sh` 现有一套位于 `apps/cli/tests/install-script.spec.ts` 的真实 shell PTY 回归测试，使用 stub 依赖覆盖接管路径和 curl 风格路径。[#1890](https://github.com/deepseek-harness/deepseek-harness/issues/1890) 跟踪安装器的长期删除工作，届时将改用 pnpm/npx。
+`scripts/install.sh` 现有一套位于 `apps/cli/tests/install-script.spec.ts` 的真实 shell PTY 回归测试，使用 stub 依赖覆盖接管路径和 curl 风格路径。curl 风格安装默认使用公开的 `deepseek-ai/deepseek-harness-sdk` 源，而以 pnpm/npx 替换安装器仍是另一项工作。
 
 验证是手工完成的，通过一个一次性测试装置以打桩的`pnpm`驱动真实脚本：接管独立克隆；从 linked worktree 接管进其已有容器；显式`DSH_SOURCE`仍回到克隆路径；工作树不干净时静默接管、既不提示也不警告，且其未提交文件留在原处；非 git 检出失败并给出指引；以及`curl`式克隆安装断言所构建的布局——正是这项回归测试捕获了`REPO_ROOT`未解析的缺陷。交互路径在 tmux 下从一个不干净的检出走通，确认整个过程不出现接管提示即可到达启动器，最终`dsh`从新的 staging worktree 运行，而原检出保持其分支不变、未提交文件仍在。
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
index 32b51699e2..8ba8380bf1 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.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 .agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
-2026-08-06-doc-site-carries-its-images.md: 9109808874579b79d85c2e22b0987110f41ddc42
-2026-08-06-doc-site-carries-its-images.zh.md: d601112e8870150c363d8533e85ef86e7f3f8ffc
+2026-08-06-doc-site-carries-its-images.md: 4078a9b6251cf67456590ae25602a9f288c88dc1
+2026-08-06-doc-site-carries-its-images.zh.md: a9afb138d45d1ab991963b997e408477cf88110b
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
index 9109808874..4078a9b625 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
@@ -20,7 +20,7 @@ Only a regular file whose real path stays inside the repository is copied; anyth
 
 `docsSourceFiles()` reports the placed images alongside the Markdown, so the dev server's watcher re-projects when a screenshot is replaced instead of serving the previous copy until something touches the page.
 
-`placeImage` is optional because `rewriteMarkdown` is also called directly by its spec, where no generated tree exists. Without it the old GitHub-raw behavior stands, which keeps that seam honest: the fallback is still the correct answer for a consumer that only rewrites text.
+`placeImage` is optional because `rewriteMarkdown` is also called directly by its spec, where no generated tree exists. Without it the GitHub-raw fallback points at the public source home, which keeps that seam honest for a consumer that only rewrites text.
 
 Canonical Markdown keeps writing ordinary repository-relative image paths, so the same file renders on GitHub and on the site. No document carries a site-absolute URL to satisfy VitePress.
 
@@ -36,7 +36,7 @@ Canonical Markdown keeps writing ordinary repository-relative image paths, so th
 
 Images in published documentation now work regardless of who is reading or whether the repository is public, and the site build has no runtime dependency on GitHub for them. The generated tree grows by one copy of each referenced image per locale — the four screenshots in the model-provider guide add roughly 270 KB per locale.
 
-Images referenced from *unpublished* documents are untouched: they still resolve to GitHub raw, and still fail for a private repository. Nothing consumes them today, and a document that is not on the site has no site build to carry its assets.
+Images referenced from *unpublished* documents are untouched. A text-only projection resolves them against the public source home; a document that is not on the site has no site build to carry its assets.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
index d601112e88..a9afb138d4 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 `docsSourceFiles()` 会连同被安置的图片一起上报，于是替换截图时开发服务器的 watcher 会重新投影，而不是一直服务旧副本直到有人碰一下页面。
 
-`placeImage` 之所以可选，是因为 `rewriteMarkdown` 也被它自己的 spec 直接调用，而那里并不存在生成树。不传它时保持原有的 GitHub raw 行为，这也让该接缝保持诚实：对只改写文本的消费方而言，这个回退仍是正确答案。
+`placeImage` 之所以可选，是因为 `rewriteMarkdown` 也被它自己的 spec 直接调用，而那里并不存在生成树。不传它时，GitHub raw 回退会指向公开源主页；这让该 seam 对只改写文本的消费方保持诚实。
 
 正本 Markdown 照旧写普通的仓库相对图片路径，因此同一份文件在 GitHub 上和站点上都能正常显示。没有任何文档为了迁就 VitePress 而写站内绝对 URL。
 
@@ -36,7 +36,7 @@ Status: implemented
 
 已发布文档中的图片，现在无论谁在阅读、无论仓库是否公开都能显示，站点构建也不再为图片依赖 GitHub 的运行时可达性。生成树会为每个 locale 各增加一份被引用图片的副本——配置模型指南里的四张截图，每个 locale 约 270 KB。
 
-**未发布**文档引用的图片不受影响：它们仍解析到 GitHub raw，对私有仓库仍然失败。今天没有任何消费方用到它们，而不在站点上的文档也没有站点构建可以承载其资源。
+**未发布**文档引用的图片不受影响。纯文本投影会相对于公开源主页解析它们；不在站点上的文档没有站点构建可以承载其资源。
 
 ## Testing
 
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
index b7d396e007..202a27ed1e 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.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 .agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
-2026-06-19-acp-snapshot-tests.md: 39d3b7a3f4699ea96262f43c63a7d60574ba064f
-2026-06-19-acp-snapshot-tests.zh.md: 7dd3a3fa83682c35945314c7cd9531ca72bbb1fb
+2026-06-19-acp-snapshot-tests.md: c7b95bd68027705b99d850d596405e56eea0dfca
+2026-06-19-acp-snapshot-tests.zh.md: 43d43262684920cae5feedb5f2eb109db00f9f8c
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
index 39d3b7a3f4..c7b95bd680 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
@@ -80,6 +80,6 @@ Tool determinism comes from a generated cwd, scrubbed environment, fresh non-log
 
 ## Consequences
 
-The tier adds reviewed per-scenario input, session, stdout, optional override, and optional workspace fixtures, plus one file for each distinct pinned prompt and tool-schema sequence. Workspace seeds are copied into the generated cwd for both record and replay. In return the tier provides deterministic keyless coverage through the real Loader and tool composition. Most retained scenarios exercise the assembled backend rather than ACP; the [automation-only ACP decision](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary) keeps that corpus here, while [#1970](https://github.com/deepseek-harness/deepseek-harness/issues/1970) tracks moving it to a transport-neutral headless suite without losing coverage.
+The tier adds reviewed per-scenario input, session, stdout, optional override, and optional workspace fixtures, plus one file for each distinct pinned prompt and tool-schema sequence. Workspace seeds are copied into the generated cwd for both record and replay. In return the tier provides deterministic keyless coverage through the real Loader and tool composition. Most retained scenarios exercise the assembled backend rather than ACP; the [automation-only ACP decision](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary) keeps that corpus here until it can move to a transport-neutral headless suite without losing coverage.
 
 This Agent Note relates to but does not supersede the [proposed determinism Agent Note](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.md): that proposal's "universal replay fixture" re-derives session *message history* after every test (an internal-consistency invariant), whereas these snapshots pin assembled behavior plus the external automation output. They are complementary until the backend corpus moves off ACP.
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
index 7dd3a3fa83..43d4326268 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
@@ -80,6 +80,6 @@ Status: implemented
 
 ## 后果
 
-该测试层为每个场景增加经过评审的输入、会话、stdout、可选 override 和可选 workspace fixture，并为每个不同的已固定提示词序列、每个不同的已固定工具 schema 序列各增加一个文件。记录与回放都会把 workspace seed 复制到生成的 cwd。作为回报，该层通过真实 Loader 和工具组合提供确定性的无密钥覆盖。保留下来的大多数场景测试的是组装后的后端而非 ACP；[仅面向自动化的 ACP 决策](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary)将该语料保留在此处，而 [#1970](https://github.com/deepseek-harness/deepseek-harness/issues/1970) 跟踪在不损失覆盖的情况下将其迁移到传输无关的 headless 套件。
+该测试层为每个场景增加经过评审的输入、会话、stdout、可选 override 和可选 workspace fixture，并为每个不同的已固定提示词序列、每个不同的已固定工具 schema 序列各增加一个文件。记录与回放都会把 workspace seed 复制到生成的 cwd。作为回报，该层通过真实 Loader 和工具组合提供确定性的无密钥覆盖。保留下来的大多数场景测试的是组装后的后端而非 ACP；[仅面向自动化的 ACP 决策](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary)将该语料保留在此处，直至它能够在不损失覆盖的情况下迁移到传输无关的 headless 套件。
 
 本 Agent Note 与[拟议的确定性 Agent Note](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.md)相关，但不取代它：该提案的“通用回放 fixture”在每次测试后重新派生会话*消息历史*（内部一致性不变量），而这些快照固定组装后的行为与外部自动化输出。在后端语料迁出 ACP 之前，两者相互补充。
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 66b3a5399e..46ab8e892f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -30,8 +30,7 @@ env:
 
 jobs:
 
-  # https://github.com/deepseek-harness/deepseek-harness/issues/1967 tracks
-  # restoring the three hosted serial reference jobs before release.
+  # TODO(hosted-serial-ci): Re-enable the three hosted serial reference jobs before release.
   # The self-hosted standby remains active on every master push.
 
   # Three enterprise jobs isolate coverage, static analysis, and the
diff --git a/docs/cordis-tutorial/01-first-plugin.i18n.yaml b/docs/cordis-tutorial/01-first-plugin.i18n.yaml
index 4e829dcb8f..29e0266689 100644
--- a/docs/cordis-tutorial/01-first-plugin.i18n.yaml
+++ b/docs/cordis-tutorial/01-first-plugin.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 docs/cordis-tutorial/01-first-plugin.md
-01-first-plugin.md: c44e7f95fb11d5337ecfaf4251c8b2f2b9b14680
-01-first-plugin.zh.md: 9461884d312ad2e64af12fa42952a986e1ad5d8a
+01-first-plugin.md: 4359dfe4883f12e9cb242cf3009827fd7864768c
+01-first-plugin.zh.md: 62ccb7e5d37beb5b9636439e563cea6eaa1044a0
diff --git a/docs/cordis-tutorial/01-first-plugin.md b/docs/cordis-tutorial/01-first-plugin.md
index c44e7f95fb..4359dfe488 100644
--- a/docs/cordis-tutorial/01-first-plugin.md
+++ b/docs/cordis-tutorial/01-first-plugin.md
@@ -92,4 +92,4 @@ One caveat worth knowing early: a config entry whose module cannot be **resolved
 
 Next: [Lifecycle and effects](02-lifecycle-and-effects.md) — what happens when a plugin unloads.
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/01-first-plugin.zh.md b/docs/cordis-tutorial/01-first-plugin.zh.md
index 9461884d31..62ccb7e5d3 100644
--- a/docs/cordis-tutorial/01-first-plugin.zh.md
+++ b/docs/cordis-tutorial/01-first-plugin.zh.md
@@ -92,4 +92,4 @@ export function apply(ctx: Context) {
 
 下一章：[生命周期与 effect](02-lifecycle-and-effects.md)：插件卸载时会发生什么。
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/02-lifecycle-and-effects.i18n.yaml b/docs/cordis-tutorial/02-lifecycle-and-effects.i18n.yaml
index deed723c39..12793267e2 100644
--- a/docs/cordis-tutorial/02-lifecycle-and-effects.i18n.yaml
+++ b/docs/cordis-tutorial/02-lifecycle-and-effects.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 docs/cordis-tutorial/02-lifecycle-and-effects.md
-02-lifecycle-and-effects.md: f1b39e06e9d25c51ab2d76503025e2b6ffe90c73
-02-lifecycle-and-effects.zh.md: 2e98e3af6d2f2b1b9cbb8ea38559bc1ffbf7e43b
+02-lifecycle-and-effects.md: 7b195b63a1e8730f27b9dd9af8af6a68a588cee9
+02-lifecycle-and-effects.zh.md: 4a3f83dedd5c95c7fcb5c1aebbbb8cb2e849b9cf
diff --git a/docs/cordis-tutorial/02-lifecycle-and-effects.md b/docs/cordis-tutorial/02-lifecycle-and-effects.md
index f1b39e06e9..7b195b63a1 100644
--- a/docs/cordis-tutorial/02-lifecycle-and-effects.md
+++ b/docs/cordis-tutorial/02-lifecycle-and-effects.md
@@ -95,4 +95,4 @@ One ordering caveat: disposers start in reverse registration order, but multiple
 
 Next: [Services](03-services.md) — how plugins share capabilities.
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/02-lifecycle-and-effects.zh.md b/docs/cordis-tutorial/02-lifecycle-and-effects.zh.md
index 2e98e3af6d..4a3f83dedd 100644
--- a/docs/cordis-tutorial/02-lifecycle-and-effects.zh.md
+++ b/docs/cordis-tutorial/02-lifecycle-and-effects.zh.md
@@ -95,4 +95,4 @@ PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
 
 下一章：[服务](03-services.md)：插件如何共享功能。
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/03-services.i18n.yaml b/docs/cordis-tutorial/03-services.i18n.yaml
index b116270811..2849ed8858 100644
--- a/docs/cordis-tutorial/03-services.i18n.yaml
+++ b/docs/cordis-tutorial/03-services.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 docs/cordis-tutorial/03-services.md
-03-services.md: 5848132c6ad18338fa893954d45fc20005db6199
-03-services.zh.md: 0f599f082573364e6ad38278e1914d8faf67faa1
+03-services.md: 562b49ede0aa4cc1d58c4d6af7c7d5d1ebb2e4b1
+03-services.zh.md: 964f7e3654614d136b8765bb727f85a5a05587a8
diff --git a/docs/cordis-tutorial/03-services.md b/docs/cordis-tutorial/03-services.md
index 5848132c6a..562b49ede0 100644
--- a/docs/cordis-tutorial/03-services.md
+++ b/docs/cordis-tutorial/03-services.md
@@ -95,4 +95,4 @@ Service names live in one flat namespace per application. Prefix or namespace yo
 
 Next: [Events](04-events.md) — communication without a shared service.
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/03-services.zh.md b/docs/cordis-tutorial/03-services.zh.md
index 0f599f0825..964f7e3654 100644
--- a/docs/cordis-tutorial/03-services.zh.md
+++ b/docs/cordis-tutorial/03-services.zh.md
@@ -95,4 +95,4 @@ export function apply(ctx: Context) {
 
 下一章：[事件](04-events.md)：无需共享服务即可通信。
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/04-events.i18n.yaml b/docs/cordis-tutorial/04-events.i18n.yaml
index 6d21e5ff1b..e7dc182114 100644
--- a/docs/cordis-tutorial/04-events.i18n.yaml
+++ b/docs/cordis-tutorial/04-events.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 docs/cordis-tutorial/04-events.md
-04-events.md: 18f39dc1b693e5fb7e1793ec4b7dcac9cf24db95
-04-events.zh.md: 3fdafb50303f49dca179bcaea32db211a66241f6
+04-events.md: 28ccb85d657afaabb5c6b4b1e9b10d6cf8710918
+04-events.zh.md: f78c971dcd9674d2a256c41000b627aecb2a572a
diff --git a/docs/cordis-tutorial/04-events.md b/docs/cordis-tutorial/04-events.md
index 18f39dc1b6..28ccb85d65 100644
--- a/docs/cordis-tutorial/04-events.md
+++ b/docs/cordis-tutorial/04-events.md
@@ -141,4 +141,4 @@ The harness uses waterfalls for decisions that cooperating plugins may wrap or a
 
 Next: [Configuration](05-config.md) — plugin options from `cordis.yml`.
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/04-events.zh.md b/docs/cordis-tutorial/04-events.zh.md
index 3fdafb5030..f78c971dcd 100644
--- a/docs/cordis-tutorial/04-events.zh.md
+++ b/docs/cordis-tutorial/04-events.zh.md
@@ -141,4 +141,4 @@ harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`ag
 
 下一章：[配置](05-config.md)：来自 `cordis.yml` 的插件选项。
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/05-config.i18n.yaml b/docs/cordis-tutorial/05-config.i18n.yaml
index db300b1745..7db45165c4 100644
--- a/docs/cordis-tutorial/05-config.i18n.yaml
+++ b/docs/cordis-tutorial/05-config.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 docs/cordis-tutorial/05-config.md
-05-config.md: 8d4043e33a58fc425d82d9846ff82473bcdef4c1
-05-config.zh.md: e9463bd34e9c72dbae7b1ceb9907e35edf7b773b
+05-config.md: 834bb140cc1ff976acc8f21c8f54a7fb02636eac
+05-config.zh.md: f5cc6ac1ca4fa02eba6a1b015b9f6ae3b1a925fc
diff --git a/docs/cordis-tutorial/05-config.md b/docs/cordis-tutorial/05-config.md
index 8d4043e33a..834bb140cc 100644
--- a/docs/cordis-tutorial/05-config.md
+++ b/docs/cordis-tutorial/05-config.md
@@ -81,4 +81,4 @@ The loader used in this repo supports a `!!js` tag for config values that must b
 
 Next: [Composition and HMR](06-composition-and-hmr.md) — treating `cordis.yml` as the application.
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/05-config.zh.md b/docs/cordis-tutorial/05-config.zh.md
index e9463bd34e..f5cc6ac1ca 100644
--- a/docs/cordis-tutorial/05-config.zh.md
+++ b/docs/cordis-tutorial/05-config.zh.md
@@ -81,4 +81,4 @@ ValidationError: invalid config:
 
 下一章：[组合与 HMR（热模块替换）](06-composition-and-hmr.md)：将 `cordis.yml` 视为应用。
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml b/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml
index f7abfca742..44b59db26a 100644
--- a/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml
+++ b/docs/cordis-tutorial/06-composition-and-hmr.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 docs/cordis-tutorial/06-composition-and-hmr.md
-06-composition-and-hmr.md: 66d6a9d93fe39baa881940ba32388979e2678505
-06-composition-and-hmr.zh.md: 7c0a94b0abcc0f153f59391fd009f1e0b40500e5
+06-composition-and-hmr.md: f138918a2d217ed98fdfd4e56dffddc14e3397f0
+06-composition-and-hmr.zh.md: a678e86735c6d9e3b4f3cd0dfa46a2a64079c762
diff --git a/docs/cordis-tutorial/06-composition-and-hmr.md b/docs/cordis-tutorial/06-composition-and-hmr.md
index 66d6a9d93f..f138918a2d 100644
--- a/docs/cordis-tutorial/06-composition-and-hmr.md
+++ b/docs/cordis-tutorial/06-composition-and-hmr.md
@@ -110,4 +110,4 @@ needs-timer is PENDING — a required service is missing
 
 Next: [Into the harness](07-into-the-harness.md) — the same patterns against real harness services.
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/06-composition-and-hmr.zh.md b/docs/cordis-tutorial/06-composition-and-hmr.zh.md
index 7c0a94b0ab..a678e86735 100644
--- a/docs/cordis-tutorial/06-composition-and-hmr.zh.md
+++ b/docs/cordis-tutorial/06-composition-and-hmr.zh.md
@@ -110,4 +110,4 @@ needs-timer is PENDING — a required service is missing
 
 下一章：[进入 harness](07-into-the-harness.md)：把相同模式用于真实的 harness 服务。
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/07-into-the-harness.i18n.yaml b/docs/cordis-tutorial/07-into-the-harness.i18n.yaml
index 5faa0bf213..f3dde47f3a 100644
--- a/docs/cordis-tutorial/07-into-the-harness.i18n.yaml
+++ b/docs/cordis-tutorial/07-into-the-harness.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 docs/cordis-tutorial/07-into-the-harness.md
-07-into-the-harness.md: 6ec42c50fe5059955734fe7bc46117538dafaffc
-07-into-the-harness.zh.md: 903adb903aa4c4355b92eb34e89f218a0295767c
+07-into-the-harness.md: e02f8f8d55b3fbe9087d46f8f50baeecb592c1c6
+07-into-the-harness.zh.md: 5f770267e8f3db04cd9cb0e92b6a6278cf05d5e4
diff --git a/docs/cordis-tutorial/07-into-the-harness.md b/docs/cordis-tutorial/07-into-the-harness.md
index 6ec42c50fe..e02f8f8d55 100644
--- a/docs/cordis-tutorial/07-into-the-harness.md
+++ b/docs/cordis-tutorial/07-into-the-harness.md
@@ -104,4 +104,4 @@ Where to go next:
 - The generated [services](../cordis-catalog/services.md) and [events](../cordis-catalog/events.md) catalogs — everything you can inject and listen to.
 - [Architecture](../architecture.md) — the system map these plugins live in.
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/07-into-the-harness.zh.md b/docs/cordis-tutorial/07-into-the-harness.zh.md
index 903adb903a..5f770267e8 100644
--- a/docs/cordis-tutorial/07-into-the-harness.zh.md
+++ b/docs/cordis-tutorial/07-into-the-harness.zh.md
@@ -104,4 +104,4 @@ logger 会先触发：`tools/result` 在结果物化过程中发出，发生在
 - 生成的[服务](../cordis-catalog/services.md)与[事件](../cordis-catalog/events.md)目录：可以注入和监听的所有内容。
 - [架构](../architecture.md)：这些插件所处的系统地图。
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/index.i18n.yaml b/docs/cordis-tutorial/index.i18n.yaml
index 256bc4f629..496a3fffa5 100644
--- a/docs/cordis-tutorial/index.i18n.yaml
+++ b/docs/cordis-tutorial/index.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 docs/cordis-tutorial/index.md
-index.md: af622ad4e35829c6283c40f1b0019d7959dac973
-index.zh.md: 0b7684a9532a1efdcc3ea2d067da23852d146e2f
+index.md: a20976706f520416236ca759ee33649d1601eaa9
+index.zh.md: f6989521d4b7dffac6114867cc12371af4e4316f
diff --git a/docs/cordis-tutorial/index.md b/docs/cordis-tutorial/index.md
index af622ad4e3..a20976706f 100644
--- a/docs/cordis-tutorial/index.md
+++ b/docs/cordis-tutorial/index.md
@@ -13,7 +13,7 @@ If you want the condensed concept reference instead of a walkthrough, read the [
 You need a clone of this repository with dependencies installed — the [quick start](../user/guide/quickstart.md) covers prerequisites. No API key is needed for this tutorial; every example runs keylessly.
 
 ```sh
-git clone https://github.com/deepseek-harness/deepseek-harness.git
+git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
 cd deepseek-harness
 pnpm install
 ```
@@ -55,4 +55,4 @@ The examples use three TypeScript features beyond ordinary modern JavaScript:
 
 Chapter 5 also uses an `interface` to describe a configuration object's fields and a generic type such as `Schema<Config>` to say which object shape a schema validates. You can copy those declarations as shown; the surrounding text explains what each one connects.
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/index.zh.md b/docs/cordis-tutorial/index.zh.md
index 0b7684a953..f6989521d4 100644
--- a/docs/cordis-tutorial/index.zh.md
+++ b/docs/cordis-tutorial/index.zh.md
@@ -13,7 +13,7 @@ Cordis 是 DeepSeek Harness SDK 底层的插件框架：它是一个小型运行
 你需要克隆本仓库并安装依赖，具体前置条件见[快速入门](../user/guide/quickstart.md)。本教程不需要 API 密钥；所有示例均可在无密钥环境中运行。
 
 ```sh
-git clone https://github.com/deepseek-harness/deepseek-harness.git
+git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
 cd deepseek-harness
 pnpm install
 ```
@@ -55,4 +55,4 @@ node --import tsx ../../vendor/cordis/bin.js
 
 第 5 章还会使用 `interface` 描述配置对象的字段，并使用 `Schema<Config>` 这类泛型表示 schema 所校验的对象形状。你可以直接照写这些声明；周围的正文会解释每项声明连接了什么。
 
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml
index 27592cdb74..aefb76991f 100644
--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.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 docs/user/guide/quickstart.md
-quickstart.md: 72cc5a52c33faf81098f747799692b384fcd5f1a
-quickstart.zh.md: ebb831c1e1bec02117c78a4c2426a84af3bb9478
+quickstart.md: 8b84017ad33bf02579891bc4dcf83eaf7ec39022
+quickstart.zh.md: dfb24f8fa194866908406c709d059bf1f6595d59
diff --git a/docs/user/guide/quickstart.md b/docs/user/guide/quickstart.md
index 72cc5a52c3..8b84017ad3 100644
--- a/docs/user/guide/quickstart.md
+++ b/docs/user/guide/quickstart.md
@@ -19,7 +19,7 @@ pnpm -v
 ## Step 1: install and configure the API key
 
 ```sh
-git clone https://github.com/deepseek-harness/deepseek-harness.git
+git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
 cd deepseek-harness
 pnpm install
 ```
diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md
index ebb831c1e1..dfb24f8fa1 100644
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -19,7 +19,7 @@ pnpm -v
 ## 第一步：安装并配置 API key
 
 ```sh
-git clone https://github.com/deepseek-harness/deepseek-harness.git
+git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
 cd deepseek-harness
 pnpm install
 ```
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index b2fd25eb4e..386926e51b 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -90,8 +90,8 @@ async function prepareFsSearchWorkspace(cwd: string): Promise<void> {
   }
 }
 
-// https://github.com/deepseek-harness/deepseek-harness/issues/1970 tracks moving
-// backend/product scenarios to headless while retaining ACP protocol contracts here.
+// TODO(acp-snapshot-ownership): Move backend/product scenarios to headless while
+// retaining ACP protocol contracts here.
 
 function fixtureRecords(name: string): unknown[] {
   return readFileSync(join(SNAPSHOTS_DIR, name, 'session.jsonl'), 'utf8')
diff --git a/examples/headless-agent/tests/compaction.e2e.ts b/examples/headless-agent/tests/compaction.e2e.ts
index fdae11d2c7..39d054a2f5 100644
--- a/examples/headless-agent/tests/compaction.e2e.ts
+++ b/examples/headless-agent/tests/compaction.e2e.ts
@@ -10,8 +10,8 @@ import { SessionId } from '@deepseek-ai/dsh-session'
 /**
  * Key-gated smoke for mid-session compaction. It verifies the compact event
  * pair, replacement of older surface nodes, and a final answer after compaction.
- * A keyless assembled snapshot with an explicit summarization replay override
- * is tracked in https://github.com/deepseek-harness/deepseek-harness/issues/1971.
+ * TODO(compaction-snapshot): Add a keyless assembled snapshot with an explicit
+ * summarization replay override.
  */
 
 let workdir: string | undefined
diff --git a/examples/mcp-memory/README.i18n.yaml b/examples/mcp-memory/README.i18n.yaml
index f89035cfcc..7e8e5248e4 100644
--- a/examples/mcp-memory/README.i18n.yaml
+++ b/examples/mcp-memory/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 examples/mcp-memory/README.md
-README.md: 023e6aefce0e78cbbf52620426376e1dd0a6b8cf
-README.zh.md: 44ace680cd583f41903437a69c62e30817308ba2
+README.md: 792bb31b668b427c8734286878a9ec98071190d8
+README.zh.md: 51020f5288c4fbd245914280b8e7e4772e8cad69
diff --git a/examples/mcp-memory/README.md b/examples/mcp-memory/README.md
index 023e6aefce..792bb31b66 100644
--- a/examples/mcp-memory/README.md
+++ b/examples/mcp-memory/README.md
@@ -36,7 +36,7 @@ Without a repository checkout, download the selected overlay directly:
 mkdir -p "${DSH_HOME:-$HOME/.dsh}"
 curl --fail --location \
   --output "${DSH_HOME:-$HOME/.dsh}/memory.cordis.yml" \
-  https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/examples/mcp-memory/memorix.cordis.yml
+  https://raw.githubusercontent.com/deepseek-ai/deepseek-harness-sdk/master/examples/mcp-memory/memorix.cordis.yml
 dsh web --patch "${DSH_HOME:-$HOME/.dsh}/memory.cordis.yml"
 ```
 
diff --git a/examples/mcp-memory/README.zh.md b/examples/mcp-memory/README.zh.md
index 44ace680cd..51020f5288 100644
--- a/examples/mcp-memory/README.zh.md
+++ b/examples/mcp-memory/README.zh.md
@@ -36,7 +36,7 @@ dsh web --patch "$PWD/examples/mcp-memory/memorix.cordis.yml"
 mkdir -p "${DSH_HOME:-$HOME/.dsh}"
 curl --fail --location \
   --output "${DSH_HOME:-$HOME/.dsh}/memory.cordis.yml" \
-  https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/examples/mcp-memory/memorix.cordis.yml
+  https://raw.githubusercontent.com/deepseek-ai/deepseek-harness-sdk/master/examples/mcp-memory/memorix.cordis.yml
 dsh web --patch "${DSH_HOME:-$HOME/.dsh}/memory.cordis.yml"
 ```
 
diff --git a/package.json b/package.json
index b1ad6853fc..eaa1025974 100644
--- a/package.json
+++ b/package.json
@@ -60,6 +60,7 @@
     "doc-typecheck": "tsx scripts/doc-typecheck.ts",
     "verify-md-wrap": "tsx scripts/verify-md-wrap.ts",
     "verify-md-links": "tsx scripts/verify-md-links.ts",
+    "verify-public-repository-links": "tsx scripts/verify-public-repository-links.ts",
     "verify-doc-refs": "tsx scripts/verify-doc-refs.ts",
     "verify-package-paths": "tsx scripts/verify-package-paths.ts",
     "verify-config-source-ownership": "tsx scripts/verify-config-source-ownership.ts",
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 5225ba9d8c..30660e1032 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
-README.md: 956bfa112d6fe50c35359cebdf3710064da8c130
-README.zh.md: 42f2da18089e7dcfc9acb95076ab8786c798444b
+README.md: ddbc2ea482ca0848fb0ee0813839cf5ff1829bcc
+README.zh.md: 7a3b615d134e27d7c9892d6f411066d89938175b
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index 956bfa112d..ddbc2ea482 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -97,5 +97,5 @@ Pass-through; the registry preserves the assembled request prefix, while the sel
 - **`GenerateOptions` sampling is `temperature`/`maxTokens`/`stop` only** — no `tool_choice`, `top_p`, or penalty fields; the vocabulary grows when a producer lands ([dropped inert knobs](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)).
 - **Producer-gated variants stay out until produced** — `prefill`, per-tool `strict`, block `cache` hints, and the `agent` message-source variant were pruned as producerless ([Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)).
 - **`BlockAssembler` handles core block kinds only** — a plugin-added block type whose stream is never closed by `block-end` makes `blocks()` throw.
-- **`APP_IDENTITY.url` names a repository that does not exist yet** — [#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) tracks making the public home reachable before release.
+- **`APP_IDENTITY.url` names a repository that does not exist yet** — the public home must be reachable before release.
 - **`GenerateOptions.sessionId` is a locally-declared brand** — importing dsh-session's `SessionId` would cycle; a future ids-owning package would dissolve the workaround.
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 42f2da1808..7a3b615d13 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -97,5 +97,5 @@
 - **`GenerateOptions` 采样只包含 `temperature`／`maxTokens`／`stop`**：没有 `tool_choice`、`top_p` 或 penalty 字段；有产生方落地时词汇才会增长（见 [已删除惰性旋钮](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)）。
 - **受产生方约束的变体在实际产生前不会加入**：`prefill`、每工具 `strict`、块 `cache` 提示与 `agent` 消息源变体因没有产生方而被剪除（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)）。
 - **`BlockAssembler` 只处理核心块类型**：如果插件添加块类型的流从未由 `block-end` 关闭，`blocks()` 会抛出异常。
-- **`APP_IDENTITY.url` 指向一个尚不存在的仓库**：[#1972](https://github.com/deepseek-harness/deepseek-harness/issues/1972) 跟踪在首次发布前让该公开主页可访问。
+- **`APP_IDENTITY.url` 指向一个尚不存在的仓库**：该公开主页必须在首次发布前可访问。
 - **`GenerateOptions.sessionId` 是本地声明的品牌类型**：导入 dsh-session 的 `SessionId` 会产生循环；未来拥有 id 的包可以消除该权宜之计。
diff --git a/packages/llm/llm/src/attribution.ts b/packages/llm/llm/src/attribution.ts
index b9375b6ef9..79cef011de 100644
--- a/packages/llm/llm/src/attribution.ts
+++ b/packages/llm/llm/src/attribution.ts
@@ -40,8 +40,7 @@ export interface AppIdentity {
 export const APP_IDENTITY: AppIdentity = {
   product: 'deepseek-harness',
   version,
-  // The public-home release blocker is tracked in
-  // https://github.com/deepseek-harness/deepseek-harness/issues/1972.
+  // TODO(public-home): Ensure this public source repository exists before release.
   url: 'https://github.com/deepseek-ai/deepseek-harness-sdk',
 }
 
diff --git a/packages/llm/llm/src/call-config.ts b/packages/llm/llm/src/call-config.ts
index 2daa6d1a4c..848654ad3b 100644
--- a/packages/llm/llm/src/call-config.ts
+++ b/packages/llm/llm/src/call-config.ts
@@ -12,6 +12,8 @@ import type { ReasoningEffortId } from './brand.ts'
 /** Process-local identities of request objects assembled by dsh-agent-loop. */
 const AGENT_LOOP_REQUESTS = new WeakSet<GenerateOptions>()
 
+// TODO(call-config-shape): Revisit which fields are epoch-level for cache reuse
+// and where provider-specific request options belong.
 /**
  * Provider, model, reasoning effort, and sampling scalars of one conversation's
  * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
diff --git a/packages/sdk/telemetry/README.i18n.yaml b/packages/sdk/telemetry/README.i18n.yaml
index 987dc8197c..1604b40bf4 100644
--- a/packages/sdk/telemetry/README.i18n.yaml
+++ b/packages/sdk/telemetry/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/sdk/telemetry/README.md
-README.md: c9f66a2415c91b75105b0ed025470da234b2523d
-README.zh.md: bfb154e4c7c017292b5479e50ff376cbb9470682
+README.md: c87735a93e7659f2913f4dd325176a8ae40cf29b
+README.zh.md: 24d6e72d988f94cdbc6aa01607edbfc105213267
diff --git a/packages/sdk/telemetry/README.md b/packages/sdk/telemetry/README.md
index c9f66a2415..c87735a93e 100644
--- a/packages/sdk/telemetry/README.md
+++ b/packages/sdk/telemetry/README.md
@@ -14,7 +14,7 @@ Launcher-side telemetry primitives for the dsh-sdk toolchain. This is a plain li
 
 Consent is carried by the telemetry entry in `cordis.yml`, so disabling telemetry is disabling that entry. Telemetry reports by default and is off only when a present telemetry entry is explicitly `disabled`: a missing `cordis.yml` (first `create`), an enabled entry, or a `cordis.yml` with no telemetry entry all report. `DO_NOT_TRACK`/CI always deny. The no-config and absent-entry defaults are configurable on `ConsentResolver`.
 
-The collection endpoint is a fixed constant (`DSH_TELEMETRY_ENDPOINT`); [#1973](https://github.com/deepseek-harness/deepseek-harness/issues/1973) tracks deploying the service and replacing its fail-safe `.invalid` placeholder before release.
+The collection endpoint is a fixed constant (`DSH_TELEMETRY_ENDPOINT`); its fail-safe `.invalid` placeholder must be replaced with the real endpoint before release.
 
 ## Model Experience
 
@@ -26,5 +26,5 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **Placeholder endpoint** — `DSH_TELEMETRY_ENDPOINT` points at `.invalid` until the service tracked in [#1973](https://github.com/deepseek-harness/deepseek-harness/issues/1973) is ready.
+- **Placeholder endpoint** — `DSH_TELEMETRY_ENDPOINT` points at `.invalid` until the real endpoint is set.
 - **Redaction is heuristic** — a conservative backstop, not a guarantee; secrets belong in `.env`, which is never read or reported.
diff --git a/packages/sdk/telemetry/README.zh.md b/packages/sdk/telemetry/README.zh.md
index bfb154e4c7..24d6e72d98 100644
--- a/packages/sdk/telemetry/README.zh.md
+++ b/packages/sdk/telemetry/README.zh.md
@@ -14,7 +14,7 @@
 
 Consent 由 `cordis.yml` 中的 telemetry 配置项承载，因此禁用 telemetry 就是禁用该配置项。telemetry 默认上报，只有已经存在的 telemetry 配置项被显式设为 `disabled` 时才关闭：缺少 `cordis.yml`（首次 `create`）、配置项已启用，或 `cordis.yml` 中没有 telemetry 配置项时都会上报。`DO_NOT_TRACK`／CI 始终拒绝。无配置与缺少配置项的默认值可以通过 `ConsentResolver` 配置。
 
-收集端点是固定常量（`DSH_TELEMETRY_ENDPOINT`）；[#1973](https://github.com/deepseek-harness/deepseek-harness/issues/1973) 跟踪服务部署，以及发布前将作为安全兜底的 `.invalid` 占位值替换为真实端点。
+收集端点是固定常量（`DSH_TELEMETRY_ENDPOINT`）；发布前必须将作为安全兜底的 `.invalid` 占位值替换为真实端点。
 
 ## 模型体验
 
@@ -26,5 +26,5 @@ Consent 由 `cordis.yml` 中的 telemetry 配置项承载，因此禁用 telemet
 
 ## 已知限制与暂缓事项
 
-- **占位端点**：`DSH_TELEMETRY_ENDPOINT` 指向 `.invalid`，直至 [#1973](https://github.com/deepseek-harness/deepseek-harness/issues/1973) 跟踪的服务就绪。
+- **占位端点**：`DSH_TELEMETRY_ENDPOINT` 指向 `.invalid`，直到设置真实端点。
 - **脱敏依赖启发式规则**：这只是保守后备，不是保证；密钥应存放于 `.env`，而该文件绝不会被读取或上报。
diff --git a/packages/sdk/telemetry/src/reporter.ts b/packages/sdk/telemetry/src/reporter.ts
index 3ad7b4b62e..b7ac75a23f 100644
--- a/packages/sdk/telemetry/src/reporter.ts
+++ b/packages/sdk/telemetry/src/reporter.ts
@@ -17,10 +17,10 @@ import { SecretRedactor } from './secret-redactor.ts'
 
 /**
  * Fail-safe placeholder collection endpoint. The `.invalid` TLD guarantees
- * delivery fails harmlessly until the service tracked in
- * https://github.com/deepseek-harness/deepseek-harness/issues/1973 is ready.
- * This is a fixed protocol constant, not a deployment tunable.
+ * delivery fails harmlessly until a collector is deployed. This is a fixed
+ * protocol constant, not a deployment tunable.
  */
+// TODO(telemetry-endpoint): Replace the placeholder before release.
 export const DSH_TELEMETRY_ENDPOINT = 'https://telemetry.example.invalid/v1/dsh-sdk'
 
 /** Wire-envelope schema version; bump on any incompatible body change. */
diff --git a/scripts/install.sh b/scripts/install.sh
index 59184d91ab..f290782892 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -1,7 +1,7 @@
 #!/bin/sh
 # dsh one-line installer.
 #
-#   curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh
+#   curl -fsSL https://raw.githubusercontent.com/deepseek-ai/deepseek-harness-sdk/master/scripts/install.sh | sh
 #
 # It clones the harness under ~/.dsh/source (the master clone at
 # ~/.dsh/source/master), adds a per-install staging worktree at
@@ -50,7 +50,7 @@
 set -eu
 
 DSH_REF=${DSH_REF:-master}
-DSH_REPO=${DSH_REPO:-https://github.com/deepseek-harness/deepseek-harness.git}
+DSH_REPO=${DSH_REPO:-https://github.com/deepseek-ai/deepseek-harness-sdk.git}
 # DSH_SOURCE is the staging-worktree container and the default home of `current`.
 # DSH_MASTER names the main clone: clone mode defaults it inside DSH_SOURCE,
 # while adoption discovers an existing clone anywhere on disk. Remember whether
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 6770381526..89e417558c 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -104,7 +104,7 @@ describe('rewriteMarkdown', () => {
       repositoryRef: 'abc123',
     })).toBe(
       '[B](./reference/b.md#part) '
-      + '[source](https://github.com/deepseek-harness/deepseek-harness/blob/abc123/packages/tool.ts#L2) '
+      + '[source](https://github.com/deepseek-ai/deepseek-harness-sdk/blob/abc123/packages/tool.ts#L2) '
       + '[web](https://example.com)\n',
     )
   })
@@ -130,7 +130,7 @@ describe('rewriteMarkdown', () => {
       pages,
       repoRoot: root,
       repositoryRef: 'abc123',
-    })).toBe('![logo](https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/abc123/packages/logo.svg)\n')
+    })).toBe('![logo](https://raw.githubusercontent.com/deepseek-ai/deepseek-harness-sdk/abc123/packages/logo.svg)\n')
   })
 
   it('hands an image to the placer and uses the URL it returns', () => {
@@ -209,7 +209,7 @@ describe('rewriteMarkdown', () => {
       repositoryRef: 'abc123',
     })).toBe(
       '[title](./reference/b.md "b.md") '
-      + '[escaped](https://github.com/deepseek-harness/deepseek-harness/blob/abc123/docs/x(y).md)\n',
+      + '[escaped](https://github.com/deepseek-ai/deepseek-harness-sdk/blob/abc123/docs/x(y).md)\n',
     )
   })
 
diff --git a/scripts/project-doc-site.ts b/scripts/project-doc-site.ts
index 02a64b023a..e3397237a3 100644
--- a/scripts/project-doc-site.ts
+++ b/scripts/project-doc-site.ts
@@ -15,7 +15,7 @@ import { gfm } from 'micromark-extension-gfm'
 import type { Nodes } from 'mdast'
 import { docsPages, type DocsLocale, type DocsPage } from '../website/docs.ts'
 
-const REPOSITORY_URL = 'https://github.com/deepseek-harness/deepseek-harness'
+const REPOSITORY_URL = 'https://github.com/deepseek-ai/deepseek-harness-sdk'
 const root = resolve(import.meta.dirname, '..')
 const generatedRoot = resolve(root, 'website/.generated')
 
@@ -203,7 +203,7 @@ function githubTarget(
   image: boolean,
 ): string {
   const path = repoPath(absPath, repoRoot)
-  if (image) return `https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/${repositoryRef}/${path}${suffix}`
+  if (image) return `https://raw.githubusercontent.com/deepseek-ai/deepseek-harness-sdk/${repositoryRef}/${path}${suffix}`
   const kind = lstatSync(absPath).isDirectory() ? 'tree' : 'blob'
   const lineSuffix = line === undefined ? suffix : `#L${line}`
   return `${REPOSITORY_URL}/${kind}/${repositoryRef}/${path}${lineSuffix}`
diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts
index 84eeeb10bb..6979fb894d 100644
--- a/scripts/run-gates.spec.ts
+++ b/scripts/run-gates.spec.ts
@@ -77,6 +77,12 @@ describe('gate graph validation', () => {
     await expect(runGates(subject, subject.length, execute)).resolves.toHaveLength(subject.length)
   })
 
+  it('keeps the public repository link policy in the documentation gate', () => {
+    const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
+
+    expect(ids).toContain('public-repository-links')
+  })
+
   it.each([
     ['empty', [], /gate graph has no gates/],
     ['duplicate ids', [gate('same'), gate('same')], /duplicate gate id "same"/],
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index c1c3e1699c..30288170f9 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -572,6 +572,7 @@ function docSyncLeafGates(options: {
     pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }),
     pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }),
     pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
+    pnpmScript('public-repository-links', 'verify-public-repository-links', { label: 'public repository links' }),
     pnpmScript('doc-refs', 'verify-doc-refs', { label: 'doc refs' }),
     pnpmScript('package-paths', 'verify-package-paths', { label: 'package paths' }),
     pnpmScript('config-source-ownership', 'verify-config-source-ownership', { label: 'config source ownership' }),
diff --git a/scripts/verify-public-repository-links.spec.ts b/scripts/verify-public-repository-links.spec.ts
new file mode 100644
index 0000000000..b05dcb65d1
--- /dev/null
+++ b/scripts/verify-public-repository-links.spec.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+import { findInternalRepositoryReferences } from './verify-public-repository-links.ts'
+
+describe('public repository link policy', () => {
+  it('rejects the internal remote and accepts the public home', () => {
+    const internalRepository = ['deepseek-harness', 'deepseek-harness'].join('/')
+    const source = [
+      'https://github.com/deepseek-ai/deepseek-harness-sdk',
+      `https://github.com/${internalRepository}/issues/1`,
+    ].join('\n')
+
+    expect(findInternalRepositoryReferences('subject.md', source)).toEqual([
+      { file: 'subject.md', line: 2 },
+    ])
+  })
+})
diff --git a/scripts/verify-public-repository-links.ts b/scripts/verify-public-repository-links.ts
new file mode 100644
index 0000000000..dc8d2b3b35
--- /dev/null
+++ b/scripts/verify-public-repository-links.ts
@@ -0,0 +1,64 @@
+/** Reject tracked files that expose the internal repository remote. */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const root = resolve(import.meta.dirname, '..')
+const internalRepository = ['deepseek-harness', 'deepseek-harness'].join('/')
+
+/** One tracked reference to the internal repository. */
+export interface InternalRepositoryReference {
+  /** Repository-relative file path. */
+  file: string
+  /** One-based source line. */
+  line: number
+}
+
+/**
+ * Locate internal-repository references in one text file.
+ * @param file - Repository-relative path used in diagnostics.
+ * @param source - Text to inspect.
+ * @returns every matching source line.
+ */
+export function findInternalRepositoryReferences(file: string, source: string): InternalRepositoryReference[] {
+  const references: InternalRepositoryReference[] = []
+  for (const [index, line] of source.split('\n').entries()) {
+    if (line.includes(internalRepository)) references.push({ file, line: index + 1 })
+  }
+  return references
+}
+
+function trackedFiles(repoRoot: string): string[] {
+  return execFileSync('git', ['ls-files', '-z'], { cwd: repoRoot, encoding: 'utf8' })
+    .split('\0')
+    .filter(file => file !== '')
+}
+
+function scanRepository(repoRoot: string): InternalRepositoryReference[] {
+  const references: InternalRepositoryReference[] = []
+  for (const file of trackedFiles(repoRoot)) {
+    const path = resolve(repoRoot, file)
+    if (!existsSync(path)) continue
+    const stat = lstatSync(path)
+    if (!stat.isFile() && !stat.isSymbolicLink()) continue
+    const source = stat.isSymbolicLink() ? readlinkSync(path) : readFileSync(path, 'utf8')
+    if (source.includes('\0')) continue
+    references.push(...findInternalRepositoryReferences(file, source))
+  }
+  return references
+}
+
+const invokedPath = process.argv[1]
+const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(resolve(invokedPath)).href
+if (isMain) {
+  const references = scanRepository(root)
+  if (references.length === 0) {
+    console.log('verify-public-repository-links: tracked files expose no internal repository remote.')
+  } else {
+    console.error('verify-public-repository-links: internal repository references found:')
+    for (const reference of references) console.error(`  ${reference.file}:${String(reference.line)}`)
+    process.exitCode = 1
+  }
+}
diff --git a/website/.vitepress/config.ts b/website/.vitepress/config.ts
index da3892eaa2..4dc1a5774b 100644
--- a/website/.vitepress/config.ts
+++ b/website/.vitepress/config.ts
@@ -94,14 +94,14 @@ const sharedTheme: Pick<DefaultTheme.Config, 'search' | 'socialLinks' | 'editLin
     },
   },
   socialLinks: [
-    { icon: 'github', link: 'https://github.com/deepseek-harness/deepseek-harness' },
+    { icon: 'github', link: 'https://github.com/deepseek-ai/deepseek-harness-sdk' },
   ],
   editLink: {
     pattern: ({ frontmatter }: PageData) => {
       const data: unknown = frontmatter
       const editSource: unknown = typeof data === 'object' && data !== null ? Reflect.get(data, 'editSource') : undefined
       if (typeof editSource !== 'string') throw new Error('Projected documentation page has no editSource frontmatter.')
-      return `https://github.com/deepseek-harness/deepseek-harness/edit/master/${editSource}`
+      return `https://github.com/deepseek-ai/deepseek-harness-sdk/edit/master/${editSource}`
     },
     text: '在 GitHub 上编辑此页',
   },
@@ -161,7 +161,7 @@ export default withMermaid({
             const data: unknown = frontmatter
             const editSource: unknown = typeof data === 'object' && data !== null ? Reflect.get(data, 'editSource') : undefined
             if (typeof editSource !== 'string') throw new Error('Projected documentation page has no editSource frontmatter.')
-            return `https://github.com/deepseek-harness/deepseek-harness/edit/master/${editSource}`
+            return `https://github.com/deepseek-ai/deepseek-harness-sdk/edit/master/${editSource}`
           },
           text: 'Edit this page on GitHub',
         },

From 8ccb17690579970ff2430448860f847799c13b78 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 01:17:10 +0800
Subject: [PATCH 184/516] docs: per-model reasoning guide, config catalog, and
 the feature's Agent Note
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The user guide's model-catalog section teaches the three new knobs at
task altitude — declare levels per model, pick the reasoning dialect,
reshape catalog models with modelOverrides — with the settings.yaml
example exercising all of them, plus an UNSUPPORTED_REASONING_EFFORT
troubleshooting row. The generated plugin config catalog picks up the
new Config fields, and the bilingual Agent Note records the decision,
the alternatives considered, and the schemastery materialization
constraint that chose false over {} as the disable spelling.
---
 ...per-model-reasoning-declarations.i18n.yaml |  6 ++
 ...-pi-ai-per-model-reasoning-declarations.md | 33 ++++++++
 ...-ai-per-model-reasoning-declarations.zh.md | 33 ++++++++
 docs/config-catalog.md                        | 78 ++++++++++++++++++-
 docs/user/guide/providers.i18n.yaml           |  4 +-
 docs/user/guide/providers.md                  | 32 +++++++-
 docs/user/guide/providers.zh.md               | 32 +++++++-
 7 files changed, 210 insertions(+), 8 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md

diff --git a/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.i18n.yaml
new file mode 100644
index 0000000000..3b448f4cf1
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.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-08-08-pi-ai-per-model-reasoning-declarations.md
+2026-08-08-pi-ai-per-model-reasoning-declarations.md: 436b5f3f9f30c1bb1dc5816b12ce1596c5d01ec8
+2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md: 47b34dfd270f90fef2802a00e3632777d5636a73
diff --git a/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.md b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.md
new file mode 100644
index 0000000000..436b5f3f9f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.md
@@ -0,0 +1,33 @@
+# Agent Note: Per-Model Reasoning Declarations in llm-pi-ai
+
+Status: implemented
+
+English | [中文](2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md)
+
+## Problem
+
+A hand-declared pi-ai route's models materialized with `reasoning: false`, so `getSupportedThinkingLevels` short-circuited to `["off"]`: the composer offered no effort picker for them, and the route-level `reasoning` default — the only reasoning knob a profile had — made every request to such a model fail with `UNSUPPORTED_REASONING_EFFORT` before network I/O. The same route-level knob was also the wrong altitude for catalog routes: one provider's models disagree about which levels they accept (deepseek ships `[off, high, max]` beside catalog models with `xhigh`), so a single per-route level could not be set without breaking part of the route, which is why the Models page stopped writing it entirely (#1860) and left `settings.yaml` with no way to align efforts per model.
+
+Two adjacent gaps compounded this. pi-ai decides the reasoning *wire dialect* (`compat.thinkingFormat`, `compat.supportsReasoningEffort`) by recognizing the endpoint URL, and a private gateway's URL says nothing — a DeepSeek-dialect gateway was spoken to in the OpenAI dialect with no configuration that could correct it. And the only way to touch one catalog model was the `models` list, which *replaces* the served catalog: narrowing `gpt-5`'s levels meant restating all thirty-eight openai models or silently dropping thirty-seven.
+
+## Decision
+
+`PiAiModelProfile` gains `reasoningEfforts`: **each key is a level selectors offer, its value the spelling dispatch sends on the wire**. The declaration translates to pi-ai's `Model.reasoning` + `thinkingLevelMap` with all seven levels decided explicitly — declared levels carry their wire value, undeclared levels are pinned `null` — so the profile author never needs pi-ai's asymmetric defaulting rule (absent means "supported" for the five base levels but "unsupported" for `xhigh`/`max`). `off` is the one three-state key: left out, thinking cannot be turned off; declared valueless, Off is offered and dispatch sends nothing (the `deepseek` dialect sends `thinking: {type: "disabled"}`); declared with a value, that value goes on the wire. `false` declares a non-reasoning model; an empty declaration is refused rather than guessed at. The spelling for "disable" is `false` rather than `{}` because schemastery materializes an absent dict as `{}` — only a `z.union([z.const(false), dict])` keeps absent, disabled, and declared distinguishable, and a bare `reasoningEfforts:` (YAML null) slips through that union unvalidated, so resolution refuses it explicitly.
+
+`compat.thinkingFormat` and `compat.supportsReasoningEffort` become configurable at two levels — route (its models' default) and model (winning per field) — resolving model → route → installed catalog entry → pi-ai's URL guess. They exist only on `openai-completions` (pi-ai types them nowhere else): a model-level switch on another protocol fails resolution, a route-level default skips such models, and a route with no completions model at all is refused. The two `chat-template` formats stay withheld for want of `chatTemplateKwargs`. Both enums are pinned to pi-ai's types through `Record<UpstreamUnion, true>` drift gates, so the pi-ai upgrade that adds a format (0.84 added `baseten`) fails compilation until the new member is classified.
+
+`modelOverrides` reshapes individual catalog models without replacing the served set: key = catalog model id, value = a `models` entry minus `id`, materialized by handing the override to the existing entry path so capacities, efforts, compat, and request-default semantics stay identical. Unlike Pi's own config layer, which ignores unknown ids, every override that lands nowhere is refused — beside a `models` list, on a hand-declared route, naming an unknown model, or smuggling an `id` in the value (the schema passes unknown keys through, and a smuggled id would quietly rename the model).
+
+## Alternatives considered
+
+- **Pass `reasoning` + `thinkingLevelMap` through verbatim** (pi-ai's own radius-config shape). Rejected by the user for operator confusion: the map's `null`-marks-unsupported convention plus the asymmetric absent-key rule mean the config's meaning depends on knowledge of pi-ai internals; the chosen shape makes the key set itself the offer.
+- **A bare level list** (`reasoningEfforts: [off, high]`). Cannot express wire renames, and the catalog's own maps prove renames are real: 66 of 1230 installed map entries are non-identity (`off→none`, `minimal→low`, `low→LOW`, `high→default`).
+- **`{}` as the disable spelling.** Unimplementable: schemastery materializes an absent dict as `{}`, so every model without the field would have been force-disabled.
+- **Folding this into the route-level `reasoning` knob.** That knob is a *default selection*, not a capability set; it stays, and a declared model's efforts now bound what it can select.
+
+## Consequences
+
+- The composer's effort pane works for hand-declared models with zero UI change — `resolveModelInfo` reports declared levels through the same seam catalog metadata uses (pinned by the `declared-reasoning` web scenario).
+- #1860's deferred gap — a route-level effort a model cannot take failing its requests — now has an operator remedy: align the model's `reasoningEfforts` or drop the route default.
+- There is deliberately no spelling for returning one map key or compat field to "whatever the catalog said": the declaration is the whole offer, so keeping a catalog value means restating it. The README documents this.
+- `verify-package-invariants` is untouched: the feature adds configuration resolution, no new events or mutable runtime relations.
diff --git a/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md
new file mode 100644
index 0000000000..47b34dfd27
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: llm-pi-ai 的按模型推理声明
+
+Status: implemented
+
+[English](2026-08-08-pi-ai-per-model-reasoning-declarations.md) | 中文
+
+## 问题
+
+手工声明的 pi-ai 路由，其模型物化出来就带着 `reasoning: false`，于是 `getSupportedThinkingLevels` 短路成 `["off"]`：输入框不为它们提供档位选择器，而路由级的 `reasoning` 默认值——当时 profile 仅有的推理旋钮——让发往这类模型的每个请求都在网络 I/O 之前以 `UNSUPPORTED_REASONING_EFFORT` 失败。同一个路由级旋钮对 catalog 路由来说也放错了层级：同一提供方下各模型接受的档位并不一致（deepseek 自带 `[off, high, max]`，旁边就是带 `xhigh` 的 catalog 模型），单个路由级档位怎么设都会弄坏路由的一部分——这正是模型页彻底停写它的原因（#1860），而 `settings.yaml` 也因此没有了任何按模型对齐档位的办法。
+
+两个相邻的缺口让问题雪上加霜。pi-ai 靠识别端点 URL 来决定推理的*协议方言*（`compat.thinkingFormat`、`compat.supportsReasoningEffort`），而私有网关的 URL 什么也说明不了——说 DeepSeek 方言的网关只会收到 OpenAI 方言的请求，且没有任何配置能更正它。另外，想动单个 catalog 模型，唯一的手段是 `models` 列表，而它会*替换*所服务的 catalog：收窄 `gpt-5` 的档位，意味着要么重述全部三十八个 openai 模型，要么静默丢掉三十七个。
+
+## 决策
+
+`PiAiModelProfile` 新增 `reasoningEfforts`：**每个键是选择器提供的一个档位，其值是分派在协议中发送的拼写**。该声明会转换为 pi-ai 的 `Model.reasoning` + `thinkingLevelMap`，七个档位全部显式决定——已声明的档位携带自己的协议值，未声明的档位一律固定为 `null`——因此 profile 作者永远不需要了解 pi-ai 那条不对称的默认规则（键缺席对五个基础档位意味着「支持」，对 `xhigh`/`max` 却意味着「不支持」）。`off` 是唯一的三态键：不写，思考就关不掉；声明而不给值，则提供 Off，分派什么也不发送（`deepseek` 方言发送 `thinking: {type: "disabled"}`）；声明并给值，该值就在协议中发送。`false` 声明一个不具备推理能力的模型；空声明会被拒绝，而不是去猜。「禁用」的拼写取 `false` 而非 `{}`，因为 schemastery 会把缺席的字典物化成 `{}`——只有 `z.union([z.const(false), dict])` 才能让缺席、禁用与已声明三态保持可区分；而裸写的 `reasoningEfforts:`（YAML null）会不经校验地从该 union 溜过去，因此解析对它显式拒绝。
+
+`compat.thinkingFormat` 与 `compat.supportsReasoningEffort` 变为两级可配置——路由级（作为其模型的默认值）与模型级（逐字段胜出）——解析顺序为模型 → 路由 → 已安装 catalog 条目 → pi-ai 按 URL 得出的猜测。两者只存在于 `openai-completions` 上（pi-ai 也只在这一协议上为它们建了类型）：在其他协议的模型上设模型级开关会使解析失败，路由级默认值会跳过这类模型，而完全没有 completions 模型的路由则被拒绝。两个 `chat-template` 格式因缺 `chatTemplateKwargs` 而继续保持不开放。两个枚举都经 `Record<UpstreamUnion, true>` 漂移门禁钉在 pi-ai 的类型上，因此新增格式的 pi-ai 升级（0.84 加入了 `baseten`）会编译失败，直到新成员被归类。
+
+`modelOverrides` 就地重塑单个 catalog 模型而不替换所服务的集合：键 = catalog 模型 id，值 = 去掉 `id` 的 `models` 条目，物化时把覆盖交给既有的条目路径，因此容量、档位、compat 与请求默认值语义完全一致。与忽略未知 id 的 Pi 自有配置层不同，凡是落不到任何地方的覆盖都会被拒绝——与 `models` 列表并存、写在手工声明的路由上、点名未知模型，或在值里夹带 `id`（schema 会放行未知键，被夹带的 id 会悄悄把模型改名）。
+
+## 曾考虑的替代方案
+
+- **把 `reasoning` + `thinkingLevelMap` 原样透传**（pi-ai 自家 radius 配置的形状）。用户以运维人员困惑为由否决：map 用 `null` 标记「不支持」的约定，加上不对称的键缺席规则，意味着这份配置的含义取决于对 pi-ai 内部机制的了解；选定的形状则让键集合本身就是对外提供的全部。
+- **裸档位列表**（`reasoningEfforts: [off, high]`）。表达不了协议侧改名，而 catalog 自己的 map 证明改名真实存在：1230 条已安装 map 条目里有 66 条不是恒等映射（`off→none`、`minimal→low`、`low→LOW`、`high→default`）。
+- **用 `{}` 作为禁用拼写。** 无法实现：schemastery 会把缺席的字典物化成 `{}`，于是每个没写该字段的模型都会被强制禁用。
+- **把这件事并进路由级的 `reasoning` 旋钮。** 那个旋钮是*默认选择*，不是能力集合；它保留下来，而已声明模型的档位如今约束着它能选什么。
+
+## 后果
+
+- 输入框的档位面板对手工声明的模型直接可用，UI 零改动——`resolveModelInfo` 经 catalog 元数据所走的同一 seam 报告已声明档位（由 `declared-reasoning` web 场景钉住）。
+- #1860 暂缓的缺口——模型接不住的路由级档位会让发往它的请求失败——如今有了运维侧补救：对齐该模型的 `reasoningEfforts`，或去掉路由默认值。
+- 刻意不提供任何把单个 map 键或 compat 字段交还给「catalog 原本怎么说」的拼写：这份声明就是对外提供的全部，要保留某个 catalog 值就得重述它。README 记载了这一点。
+- `verify-package-invariants` 原封未动：该功能新增的是配置解析，没有新事件，也没有可变的运行时关系。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 21f38d18e2..ef3721a764 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -767,6 +767,22 @@ export interface PiAiProviderProfile {
    * unset fields from the installed model of the same id.
    */
   models?: PiAiModelProfile[]
+  /**
+   * Installed-catalog customizations by model id: each entry reshapes that
+   * one model with the same fields a {@link models} entry takes, while the
+   * rest of the catalog keeps serving untouched. Only meaningful on a catalog
+   * route with no `models` list — `models` already replaces the catalog, so
+   * an override beside it, on a route the catalog does not ship, or naming a
+   * model the catalog does not describe is refused rather than skipped.
+   */
+  modelOverrides?: Record<string, PiAiModelOverride>
+  /**
+   * Reasoning-dispatch switches for every `openai-completions` model on this
+   * route; each model's own `compat` overrides per field. What neither sets
+   * keeps the installed catalog entry's value, then pi-ai's baseURL-derived
+   * detection.
+   */
+  compat?: PiAiCompatProfile
   /**
    * Context capacity for a model this route lists that neither the entry nor
    * the installed catalog sizes (default 262,144). A guess by construction, so
@@ -814,12 +830,70 @@ export interface PiAiModelProfile {
    * default on its own.
    */
   maxTokens?: number
+  /**
+   * Selectable reasoning efforts. Absent inherits the installed catalog
+   * entry's capability (a hand-declared model has none and does not reason);
+   * `false` declares a non-reasoning model, which is how a profile strips
+   * reasoning from a catalog model its gateway cannot serve; a non-empty dict
+   * declares the offered levels and their wire spellings.
+   */
+  reasoningEfforts?: false | PiAiReasoningEfforts
+  /** Reasoning-dispatch switches for this model, winning over the route's. */
+  compat?: PiAiCompatProfile
 }
+
+/**
+ * Customization of one installed catalog model, keyed by its id in the
+ * route's `modelOverrides` dict — the same fields a `models` entry may set,
+ * with the id living in the key. Unlike a `models` list, overrides leave the
+ * rest of the catalog serving untouched, which is what makes "correct one
+ * model, keep the other thirty-seven" a three-line edit.
+ */
+export type PiAiModelOverride = Omit<PiAiModelProfile, 'id'>
+
+/**
+ * Reasoning-dispatch compatibility switches, set on the route (its models'
+ * default) or per model (winning over the route). Only the switches pi-ai's
+ * reasoning dispatch reads are offered; the rest of pi-ai's compat surface
+ * keeps its baseURL-derived auto-detection. pi-ai types both fields only on
+ * `OpenAICompletionsCompat` — the other wire protocols carry their reasoning
+ * shape in the protocol itself — so resolution rejects a model-level switch
+ * anywhere else, while a route-level default skips past models it cannot fit.
+ */
+export interface PiAiCompatProfile {
+  /** Reasoning parameter shape the endpoint expects; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+  thinkingFormat?: PiAiThinkingFormat
+  /** Whether the endpoint accepts `reasoning_effort`; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+  supportsReasoningEffort?: boolean
+}
+
+/**
+ * Selectable reasoning efforts for one model: each key is a level the model
+ * offers (and selectors show), and its value is the wire spelling dispatch
+ * sends for it. `off` alone may leave its value empty — "supported, send
+ * nothing" — because for most providers not thinking is the parameter's
+ * absence; every other declared level must name a wire value. A level absent
+ * from the dict is not offered.
+ */
+export type PiAiReasoningEfforts = Partial<Record<ModelThinkingLevel, string | null>>
+
+/** One reasoning-dispatch wire format a profile may name. */
+export type PiAiThinkingFormat = Exclude<PiThinkingFormat, WithheldThinkingFormat>
+
+/** The `compat.thinkingFormat` spellings pi-ai accepts on an `openai-completions` model. */
+type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>
+
+/**
+ * pi-ai thinking formats a profile cannot name: both drive the request through
+ * `chatTemplateKwargs`, which this configuration does not expose, so offering
+ * them would hand back a format with nothing to say.
+ */
+type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
 ```
 
-Depends on: `CacheRetention` (`@earendil-works/pi-ai`) · `ModelThinkingLevel` (`@earendil-works/pi-ai`) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) · `ThinkingBudgets` (`@earendil-works/pi-ai`) · `Transport` (`@earendil-works/pi-ai`)
+Depends on: `CacheRetention` (`@earendil-works/pi-ai`) · `ModelThinkingLevel` (`@earendil-works/pi-ai`) · `OpenAICompletionsCompat` (`@earendil-works/pi-ai`) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) · `ThinkingBudgets` (`@earendil-works/pi-ai`) · `Transport` (`@earendil-works/pi-ai`)
 
-Source: [`packages/llm/llm-pi-ai/src/config.ts:126`](../packages/llm/llm-pi-ai/src/config.ts)
+Source: [`packages/llm/llm-pi-ai/src/config.ts:148`](../packages/llm/llm-pi-ai/src/config.ts)
 
 ## `@deepseek-ai/dsh-llm-replay`
 
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 82c2f2781a..a24c06b8c5 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
-providers.md: 5234f5bb03755c11652eb23f3c5d677fa3cddb40
-providers.zh.md: a54819cab8524a6007c335ad70cecd6516bba25b
+providers.md: 6f44daf73037f811164f5b22b14a9c39b71d6b1a
+providers.zh.md: 6c75d70d485f55ff230f557247ed6be597a8785e
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index 5234f5bb03..6f44daf730 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -59,6 +59,16 @@ llm-pi-ai:
         - id: claude-sonnet-4-5
           contextWindow: 200000
 
+    # Catalog route with one model reshaped in place; the rest of the catalog
+    # keeps serving (a models list would replace it instead).
+    deepseek:
+      apiKeyEnv: DEEPSEEK_API_KEY
+      modelOverrides:
+        deepseek-v4-pro:
+          reasoningEfforts:
+            off:
+            high: high
+
     # Hand-declared route: pi-ai ships nothing under this key, so the profile
     # supplies the whole provider.
     acme-gateway:
@@ -66,11 +76,22 @@ llm-pi-ai:
       apiKeyEnv: ACME_GATEWAY_API_KEY
       api: openai-completions
       baseURL: https://gateway.acme.example/v1
+      # Reasoning dialect for an endpoint whose URL pi-ai cannot recognize.
+      compat:
+        thinkingFormat: deepseek
       models:
         - id: acme-large
           name: Acme Large
           contextWindow: 65536
           maxTokens: 4096
+        - id: acme-think
+          name: Acme Think
+          # key = level offered in the picker, value = what goes on the wire;
+          # only off may leave the value empty (supported, send nothing).
+          reasoningEfforts:
+            off:
+            high: high
+            max: ultra
 ```
 
 A settings section merges over the matching `cordis.yml` configuration **per provider**, so you can override one field of one route and leave the rest as the composition set them.
@@ -79,9 +100,15 @@ A profile the adapter could not serve is refused **where it is written**: a hand
 
 ## The model catalog
 
-A profile's `models` list *replaces* that route's installed catalog rather than extending it; omitting it or leaving it empty serves the catalog unchanged. Each entry defaults its unset fields from the installed model of the same `id`, so narrowing a route to two models, correcting one capacity, or adding a model newer than the installed catalog are each a one-line edit.
+A profile's `models` list *replaces* that route's installed catalog rather than extending it; omitting it or leaving it empty serves the catalog unchanged. Each entry defaults its unset fields from the installed model of the same `id`, so narrowing a route to two models, correcting one capacity, or adding a model newer than the installed catalog are each a one-line edit — but once you declare the list, every model the route should keep serving must appear in it, an entry of nothing but `id` being enough.
 
-Only the four fields the harness consumes are configurable: `id`, `name`, `contextWindow`, and `maxTokens`. Pricing and input modalities have no consumer, and reasoning is not per-model configurable at all — it rides the installed catalog entry.
+Reshaping a few catalog models while keeping the rest is `modelOverrides`' job: it is keyed by catalog model id, takes the same fields a `models` entry does, and leaves the rest of the catalog serving untouched. An override naming a model the catalog does not describe — or set beside a `models` list, or on a custom provider — is refused rather than silently skipped.
+
+The configurable model fields are `id`, `name`, `contextWindow`, `maxTokens`, `reasoningEfforts`, and `compat`. Pricing and input modalities have no consumer and ride the installed entry.
+
+**Declare reasoning levels per model.** `reasoningEfforts` lists the levels a model offers: each key appears in the composer's effort picker, and its value is what dispatch sends on the wire — `high: high` passes the name through, `max: ultra` renames it for a gateway with its own vocabulary. A level you leave out is not offered. `off` is special: declared without a value, Off appears in the picker and selecting it sends nothing; left out entirely, the model cannot stop thinking. `reasoningEfforts: false` declares a non-reasoning model, which is also how you strip reasoning from a catalog model your gateway cannot serve. Without this field a custom model does not reason and a catalog model keeps its catalog levels.
+
+**Pick the reasoning dialect.** How a level travels — plain `reasoning_effort`, DeepSeek's `thinking: {type}` plus effort, and so on — is normally guessed from the endpoint URL, and a private gateway's URL says nothing, so a DeepSeek-style gateway would be spoken to in the OpenAI dialect. `compat.thinkingFormat` sets the dialect explicitly, and `compat.supportsReasoningEffort: false` holds the parameter back from an endpoint that rejects it; both work on the route (its models' default) or per model, for `openai-completions` routes only.
 
 A model neither the entry nor the catalog sizes takes the route's `defaultContextWindow` (262,144) and `defaultMaxTokens` (32,768). Both are guesses by construction, which is why they are route fields: a deployment whose gateway serves smaller models corrects them once.
 
@@ -114,6 +141,7 @@ If the provider a saved default names is later removed, the composer says **Sele
 
 - **`MISSING_CREDENTIAL`** — the variable the profile's `apiKeyEnv` names holds no value. Store the key once through the Models page, or export the variable.
 - **`UNKNOWN_MODEL`** — the requested model is not in the route's configured catalog. Add it to `models`, or use an id the catalog already carries.
+- **`UNSUPPORTED_REASONING_EFFORT`** — the request asked the model for a level it does not offer. Pick a level the composer lists for that model, or declare the missing one in the model's `reasoningEfforts`.
 - **`settings-rejected`** — the written profile cannot be served, and the message names the route and model. For a hand-declared route, check that `api`, `baseURL`, and `models` are all present.
 - **Fetching available models answers 401** — the endpoint refused the interrogation. Check the key; if the base URL points at an Anthropic-style gateway, note that the interrogation reads only the OpenAI-compatible `GET /models`, so enter the models by hand instead.
 
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index a54819cab8..6c75d70d48 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -59,6 +59,16 @@ llm-pi-ai:
         - id: claude-sonnet-4-5
           contextWindow: 200000
 
+    # Catalog route with one model reshaped in place; the rest of the catalog
+    # keeps serving (a models list would replace it instead).
+    deepseek:
+      apiKeyEnv: DEEPSEEK_API_KEY
+      modelOverrides:
+        deepseek-v4-pro:
+          reasoningEfforts:
+            off:
+            high: high
+
     # Hand-declared route: pi-ai ships nothing under this key, so the profile
     # supplies the whole provider.
     acme-gateway:
@@ -66,11 +76,22 @@ llm-pi-ai:
       apiKeyEnv: ACME_GATEWAY_API_KEY
       api: openai-completions
       baseURL: https://gateway.acme.example/v1
+      # Reasoning dialect for an endpoint whose URL pi-ai cannot recognize.
+      compat:
+        thinkingFormat: deepseek
       models:
         - id: acme-large
           name: Acme Large
           contextWindow: 65536
           maxTokens: 4096
+        - id: acme-think
+          name: Acme Think
+          # key = level offered in the picker, value = what goes on the wire;
+          # only off may leave the value empty (supported, send nothing).
+          reasoningEfforts:
+            off:
+            high: high
+            max: ultra
 ```
 
 settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上，所以你可以只覆盖某个路由的一个字段，其余保持组合里的样子。
@@ -79,9 +100,15 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 ## 模型目录
 
-`models` 是**替换**该路由的内置目录，不是往里追加；省略或留空则原样使用内置目录。每个条目会从同 `id` 的内置模型继承自己没写的字段，所以「收窄到两个模型」「更正一个容量」「加一个比内置目录更新的模型」都是一行编辑。
+`models` 是**替换**该路由的内置目录，不是往里追加；省略或留空则原样使用内置目录。每个条目会从同 `id` 的内置模型继承自己没写的字段，所以「收窄到两个模型」「更正一个容量」「加一个比内置目录更新的模型」都是一行编辑——但一旦声明了这份列表，该路由要继续服务的每个模型就都必须出现在其中，条目哪怕只写一个 `id` 也足够。
 
-可配置的只有 harness 会消费的四个字段：`id`、`name`、`contextWindow`、`maxTokens`。定价与输入模态没有消费方，推理能力也不按模型配置——它随内置目录条目走。
+就地重塑目录里的几个模型、保留其余，归 `modelOverrides` 管：它以目录模型 id 为键，接受与 `models` 条目相同的字段，目录的其余部分原样继续服务。覆盖若点名了目录没有描述的模型，或与 `models` 列表并存，或写在自定义提供方上，都会被拒绝，而不是被静默跳过。
+
+可配置的模型字段是 `id`、`name`、`contextWindow`、`maxTokens`、`reasoningEfforts` 与 `compat`。定价与输入模态没有消费方，随内置目录条目走。
+
+**按模型声明推理档位。** `reasoningEfforts` 列出模型提供的档位：每个键都会出现在输入框的档位选择器里，其值是分派在协议中实际发送的内容——`high: high` 原样透传名称，`max: ultra` 则为使用自有词汇的网关改名。没写的档位不会被提供。`off` 比较特殊：声明而不给值，选择器里会出现 Off，选中它时什么也不发送；完全不写，模型就无法停止思考。`reasoningEfforts: false` 声明一个不具备推理能力的模型，这也是从网关服务不了的目录模型上剥除推理的办法。不写这个字段，自定义模型不推理，目录模型保留目录给出的档位。
+
+**选定推理方言。** 档位如何在协议中传输——单独一个 `reasoning_effort`、DeepSeek 的 `thinking: {type}` 加档位，诸如此类——通常靠端点 URL 来猜，而私有网关的 URL 什么也说明不了，于是 DeepSeek 风格的网关只会收到 OpenAI 方言的请求。`compat.thinkingFormat` 用来显式指定方言，`compat.supportsReasoningEffort: false` 则让该参数不再发给拒绝它的端点；两者既可设在路由上（作为其模型的默认值），也可按模型设置，且仅适用于 `openai-completions` 路由。
 
 两处容量都没给出的模型，取路由级兜底 `defaultContextWindow`（262144）与 `defaultMaxTokens`（32768）。这两个数按定义就是猜测，所以它们是路由字段：网关服务的模型更小时改一次即可。
 
@@ -114,6 +141,7 @@ api-gateway:
 
 - **`MISSING_CREDENTIAL`** — profile 里的 `apiKeyEnv` 指向的变量没有值。用模型页存一次密钥，或导出该环境变量。
 - **`UNKNOWN_MODEL`** — 请求的模型不在该路由配置的目录里。把它加进 `models`，或改用目录里已有的 id。
+- **`UNSUPPORTED_REASONING_EFFORT`** — 请求向模型要了一个它不提供的档位。从输入框为该模型列出的档位里挑一个，或把缺的那个声明进该模型的 `reasoningEfforts`。
 - **`settings-rejected`** — 写入的 profile 服务不了，错误信息会点名具体的路由和模型。手工声明的路由检查 `api`、`baseURL`、`models` 是否齐全。
 - **获取可用模型返回 401** — 端点拒绝了这次探测。检查密钥；若地址指向的是 Anthropic 风格网关，注意探测只读 OpenAI 兼容的 `GET /models`，此时手工填写模型即可。
 

From 0fb474f67206e87f90ef77968a7c3e240da8038a Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 01:27:25 +0800
Subject: [PATCH 185/516] test(web): cover user-only skill invocation end to
 end
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The policy scenario now expects the user-only quadrant in the menu with
its marker (riding the description — the hint field is claim-state ghost
text, which the menu never renders), and a new skill-user-invoke scenario
drives /name args through the composer against the real host: the claim
lands skill.invoke, the transcript shows the dedicated card with the
collapsed <skill_content> body, and a paced replay answers the injected
turn deterministically.
---
 apps/web/tests/skill-invocation-policy.e2e.ts |  11 +-
 apps/web/tests/skill-user-invoke.e2e.ts       | 145 ++++++++++++++++++
 .../skill-invocation-policy/menu.expected.md  |   1 +
 .../skill-user-invoke/ui.expected.md          |  31 ++++
 packages/client/ui-skill/src/client/index.ts  |   5 +-
 .../ui-skill/tests/browser-plugin.spec.ts     |   4 +-
 6 files changed, 189 insertions(+), 8 deletions(-)
 create mode 100644 apps/web/tests/skill-user-invoke.e2e.ts
 create mode 100644 apps/web/tests/snapshots/skill-user-invoke/ui.expected.md

diff --git a/apps/web/tests/skill-invocation-policy.e2e.ts b/apps/web/tests/skill-invocation-policy.e2e.ts
index 143bc0d4db..54cd15bf94 100644
--- a/apps/web/tests/skill-invocation-policy.e2e.ts
+++ b/apps/web/tests/skill-invocation-policy.e2e.ts
@@ -1,5 +1,6 @@
-// Web e2e scenario: the real host filters skill.list to the model-and-user
-// intersection before the browser slash source renders candidates. A real
+// Web e2e scenario: the real host serves every user-invocable skill to the
+// browser slash source — user-only (disable-model-invocation) entries appear
+// with their marker while user-disabled quadrants stay hidden. A real
 // chromium connects a fresh workspace seeded with all four policy quadrants;
 // no model call is issued, so a stray stream fails loud on the open LLM seam.
 import { mkdir, writeFile } from 'node:fs/promises'
@@ -92,7 +93,7 @@ describe('web e2e: skill invocation policy through the real host', () => {
     await scaffold?.close()
   })
 
-  it('renders only the model-and-user intersection in slash candidates', async () => {
+  it('renders every user-invocable skill and marks the user-only entry', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-skill-invocation-policy'))
     const input = page.locator('textarea').first()
     await input.fill('/policy')
@@ -102,8 +103,10 @@ describe('web e2e: skill invocation policy through the real host', () => {
       { timeout: 10_000 },
     ).toBe(1)
 
+    // The user-only quadrant is invocable here — its only entry point — and
+    // wears the user-only marker; both user-disabled quadrants stay hidden.
+    expect(await menu.getByRole('option', { name: /policy-user-only user-only · / }).count()).toBe(1)
     expect(await menu.getByRole('option', { name: /policy-model-only/ }).count()).toBe(0)
-    expect(await menu.getByRole('option', { name: /policy-user-only/ }).count()).toBe(0)
     expect(await menu.getByRole('option', { name: /policy-trusted-only/ }).count()).toBe(0)
 
     const snapshot = await captureStableAria(page, '[role="listbox"]', scaffold.workspaceCwd)
diff --git a/apps/web/tests/skill-user-invoke.e2e.ts b/apps/web/tests/skill-user-invoke.e2e.ts
new file mode 100644
index 0000000000..f722472ded
--- /dev/null
+++ b/apps/web/tests/skill-user-invoke.e2e.ts
@@ -0,0 +1,145 @@
+// Web e2e scenario: a user invokes a disable-model-invocation skill through
+// the composer (issue #1470). The entered `/name args` line claims into
+// skill.invoke: the real host renders the skill body, injects it as a
+// user-role message carrying the skill-invocation source, and starts a turn
+// answered by the replay seam. The transcript shows the dedicated invocation
+// card (chip + args, body collapsed) and the model's reply.
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import type { ReplayOverrideDoc } from '@deepseek-ai/dsh-llm-replay'
+import {
+  assertFixtureInventory,
+  captureStableAria,
+  compareOrRefreshGolden,
+  launchWebScaffold,
+  watchConsole,
+  webSnapshotMode,
+  type WebScaffold,
+} from './scaffold.ts'
+import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/skill-user-invoke', import.meta.url))
+const UI_EXPECTED = join(SNAPSHOT_DIR, 'ui.expected.md')
+const MODE = webSnapshotMode()
+
+const SKILL_NAME = 'user-invoke-demo'
+const ARGS_TEXT = 'and confirm the fixture wiring'
+const REPLY = 'USER_INVOKE_REPLY acknowledged; following the injected skill.'
+
+async function seedUserOnlySkill(workspaceCwd: string): Promise<void> {
+  const directory = join(workspaceCwd, 'workspace', '.agents', 'skills', SKILL_NAME)
+  await mkdir(directory, { recursive: true })
+  await writeFile(join(directory, 'SKILL.md'), [
+    '---',
+    `name: ${SKILL_NAME}`,
+    'description: Prove user-explicit invocation of a model-hidden skill',
+    'disable-model-invocation: true',
+    '---',
+    '',
+    'Reply with the fixture acknowledgement line.',
+    '',
+  ].join('\n'))
+}
+
+const REPLAY: ReplayOverrideDoc = [{
+  kind: 'chunks',
+  chunks: [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    { type: 'text-delta', index: 0, text: REPLY },
+    { type: 'block-end', index: 0, block: { type: 'text', text: REPLY } },
+    { type: 'usage', usage: { inputTokens: 256, outputTokens: 16 } },
+    { type: 'finish', reason: { kind: 'stop' } },
+  ],
+}]
+
+describe.skipIf(MODE === 'record')('web e2e: user-explicit skill invocation through the composer', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let replayDir: string
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    replayDir = await mkdtemp(join(tmpdir(), 'dsh-skill-user-invoke-replay-'))
+    const replayOverride = join(replayDir, 'replay.override.json')
+    await writeFile(replayOverride, JSON.stringify(REPLAY))
+    scaffold = await launchWebScaffold({
+      replayFixture: join(replayDir, 'override-only.jsonl'),
+      replayOverride,
+      // Paced replay keeps the timing-derived chrome (TTFT / tok/s) present
+      // deterministically; instant playback races it in and out of the golden.
+      paceMs: 10,
+    })
+    await seedUserOnlySkill(scaffold.workspaceCwd)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    await connectFreshWorkspace(page, scaffold.workspaceCwd)
+  }, 120_000)
+
+  afterAll(async () => {
+    const failures: unknown[] = []
+    await browser?.close().catch((error: unknown) => failures.push(error))
+    await scaffold?.close().catch((error: unknown) => failures.push(error))
+    if (replayDir !== undefined) {
+      await rm(replayDir, { recursive: true, force: true })
+        .catch((error: unknown) => failures.push(error))
+    }
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, 'skill-user-invoke e2e cleanup failed')
+  })
+
+  it('claims /name args into an injection card and a replayed answer', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-skill-user-invoke'))
+    const composer = page.locator('textarea:enabled').last()
+    await composer.waitFor({ timeout: 15_000 })
+
+    // The menu lists the user-only skill (its only entry point) before enter.
+    await composer.fill(`/${SKILL_NAME}`)
+    const menu = page.getByRole('listbox', { name: 'Trigger suggestions' })
+    await expect.poll(
+      () => menu.getByRole('option', { name: new RegExp(SKILL_NAME) }).count(),
+      { timeout: 10_000 },
+    ).toBe(1)
+
+    await composer.fill(`/${SKILL_NAME} ${ARGS_TEXT}`)
+    await composer.press('Enter')
+
+    // The injection card presents the gesture from source metadata: chip plus
+    // args, with the rendered <skill_content> collapsed behind a disclosure.
+    const card = page.locator('[data-skill-invocation]')
+    await card.waitFor({ timeout: 15_000 })
+    const chip = card.locator('[data-ref-chip="skill"]')
+    expect(await chip.textContent()).toBe(`/${SKILL_NAME}`)
+    expect(await card.textContent()).toContain(ARGS_TEXT)
+
+    const disclosure = card.locator('details')
+    expect(await disclosure.getAttribute('open')).toBeNull()
+    await card.locator('summary').click()
+    const body = card.locator('pre')
+    await body.waitFor()
+    expect(await body.textContent()).toContain(`<skill_content name="${SKILL_NAME}">`)
+    expect(await body.textContent()).toContain('Reply with the fixture acknowledgement line.')
+    expect(await body.textContent()).toContain(ARGS_TEXT)
+    await card.locator('summary').click()
+
+    // The injection started a turn; the replay seam answers it.
+    await page.getByText('USER_INVOKE_REPLY', { exact: false }).first().waitFor({ timeout: 20_000 })
+
+    const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  }, 60_000)
+
+  it('keeps its snapshot inventory closed', async () => {
+    await assertFixtureInventory(SNAPSHOT_DIR, ['ui.expected.md'])
+  })
+})
diff --git a/apps/web/tests/snapshots/skill-invocation-policy/menu.expected.md b/apps/web/tests/snapshots/skill-invocation-policy/menu.expected.md
index 11acc39ad0..ca9230b6f1 100644
--- a/apps/web/tests/snapshots/skill-invocation-policy/menu.expected.md
+++ b/apps/web/tests/snapshots/skill-invocation-policy/menu.expected.md
@@ -1,3 +1,4 @@
 - listbox "Trigger suggestions":
   - text: Skills
   - option "policy-shared Available to both model and user invocation" [selected]
+  - option "policy-user-only user-only · Available only to user invocation"
diff --git a/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md b/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md
new file mode 100644
index 0000000000..b96413f89f
--- /dev/null
+++ b/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md
@@ -0,0 +1,31 @@
+- banner:
+  - navigation "Session hierarchy":
+    - button "workspace" [disabled]
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- text: /user-invoke-demo and confirm the fixture wiring
+- group: View injected skill content
+- text: {{clock}}
+- button "Copy":
+  - img
+- button "Context injection @deepseek-ai/dsh-system-prompt":
+  - img
+  - img
+  - text: Context injection @deepseek-ai/dsh-system-prompt
+- paragraph: USER_INVOKE_REPLY acknowledged; following the injected skill.
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
+- textbox "Message the agent"
+- button "Commands":
+  - img
+- 'button "Access mode, current: Workspace Write"': Workspace Write
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
+  - img
+- button "0% of context used"
+- button "Send message" [disabled]
+- text: 1 turns · 1 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 0% Input 256 tok · Output 16 tok
diff --git a/packages/client/ui-skill/src/client/index.ts b/packages/client/ui-skill/src/client/index.ts
index 7d859bf2fb..3e23cc997b 100644
--- a/packages/client/ui-skill/src/client/index.ts
+++ b/packages/client/ui-skill/src/client/index.ts
@@ -157,8 +157,9 @@ export function apply(ctx: ClientContext): void {
         .filter(skill => skill.name.startsWith(query))
         .map(skill => ({
           name: skill.name,
-          description: skill.description,
-          ...skill.modelInvocable ? {} : { hint: userOnlyHint() },
+          // The user-only marker rides the description (the menu's only
+          // secondary text); `hint` is the claim-state ghost text, not a badge.
+          description: skill.modelInvocable ? skill.description : `${userOnlyHint()} · ${skill.description}`,
         }))
     },
     warm(session) {
diff --git a/packages/client/ui-skill/tests/browser-plugin.spec.ts b/packages/client/ui-skill/tests/browser-plugin.spec.ts
index e38adf7686..0e098a0b30 100644
--- a/packages/client/ui-skill/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts
@@ -388,7 +388,7 @@ describe('adjudication', () => {
 })
 
 describe('user-only marking', () => {
-  it('carries the user-only hint on candidates the model cannot invoke', async () => {
+  it('prefixes the description of candidates the model cannot invoke', async () => {
     const rows: SkillRow[] = [
       { name: 'shared-skill', description: 'both surfaces', modelInvocable: true },
       { name: 'user-only-skill', description: 'user surface only', modelInvocable: false },
@@ -397,7 +397,7 @@ describe('user-only marking', () => {
     const candidates = await source.candidates(proj('s1'), req(''))
     expect(candidates).toEqual([
       { name: 'shared-skill', description: 'both surfaces' },
-      { name: 'user-only-skill', description: 'user surface only', hint: '仅用户' },
+      { name: 'user-only-skill', description: '仅用户 · user surface only' },
     ])
   })
 })

From e46b082fee3aa811699ae8d623f32044b3ee029f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 01:32:27 +0800
Subject: [PATCH 186/516] test(snapshot): derive compaction replay from logs

---
 docs/config-catalog.md                        |  2 +-
 docs/module-graph.md                          |  9 +-
 .../compaction.cordis.snapshot.yml            | 25 ++++++
 .../headless-agent/tests/compaction.e2e.ts    |  4 +-
 .../headless-agent/tests/headless.snapshot.ts | 73 ++++++++++++++++
 .../snapshots/compaction-recovery/input.json  |  8 ++
 .../compaction-recovery/session.jsonl         | 32 +++++++
 .../stream-json.expected.jsonl                | 32 +++++++
 packages/support/llm-replay/README.i18n.yaml  |  4 +-
 packages/support/llm-replay/README.md         | 10 ++-
 packages/support/llm-replay/README.zh.md      | 10 ++-
 packages/support/llm-replay/package.json      |  2 +
 packages/support/llm-replay/src/index.ts      | 39 +++++++--
 .../llm-replay/tests/llm-replay.spec.ts       | 87 +++++++++++++++++++
 packages/support/llm-replay/tsconfig.json     |  3 +
 pnpm-lock.yaml                                |  3 +
 16 files changed, 317 insertions(+), 26 deletions(-)
 create mode 100644 examples/headless-agent/compaction.cordis.snapshot.yml
 create mode 100644 examples/headless-agent/tests/snapshots/compaction-recovery/input.json
 create mode 100644 examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
 create mode 100644 examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index feb8aa9d86..f4302984a8 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -857,7 +857,7 @@ export interface ReplayModelConfig {
 
 Depends on: [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
 
-Source: [`packages/support/llm-replay/src/index.ts:710`](../packages/support/llm-replay/src/index.ts)
+Source: [`packages/support/llm-replay/src/index.ts:731`](../packages/support/llm-replay/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-retry`
 
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 14a6b71dc1..d963273363 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -422,9 +422,6 @@ flowchart TD
   pkg_session_persistence --> pkg_brand
   pkg_session_persistence --> pkg_invariants
   pkg_session_persistence --> pkg_session
-  pkg_llm_replay --> pkg_invariants
-  pkg_llm_replay --> pkg_llm
-  pkg_llm_replay --> pkg_session
   pkg_app_boot --> pkg_environment
   pkg_app_boot --> pkg_invariants
   pkg_app_boot --> pkg_paths
@@ -500,6 +497,10 @@ flowchart TD
   pkg_session_title --> pkg_llm
   pkg_session_title --> pkg_session
   pkg_session_title --> pkg_session_projection
+  pkg_llm_replay --> pkg_compact
+  pkg_llm_replay --> pkg_invariants
+  pkg_llm_replay --> pkg_llm
+  pkg_llm_replay --> pkg_session
   pkg_commands --> pkg_agent
   pkg_commands --> pkg_brand
   pkg_commands --> pkg_invariants
@@ -1219,7 +1220,6 @@ flowchart TD
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`llm-replay`](../packages/support/llm-replay) | `support` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1239,6 +1239,7 @@ flowchart TD
 | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | [`session-title`](../packages/session-title/session-title) | `session-title` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
+| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`commands`](../packages/ui/commands) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
 | [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
diff --git a/examples/headless-agent/compaction.cordis.snapshot.yml b/examples/headless-agent/compaction.cordis.snapshot.yml
new file mode 100644
index 0000000000..42fc5306ac
--- /dev/null
+++ b/examples/headless-agent/compaction.cordis.snapshot.yml
@@ -0,0 +1,25 @@
+# Keyless context-overflow composition for the assembled compaction snapshot.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: llm-deepseek
+        name: '@deepseek-ai/dsh-llm-deepseek'
+        disabled: true
+      - id: compact-basic
+        name: '@deepseek-ai/dsh-compact-basic'
+        config:
+          thresholdRatio: 0.99
+          retainTokens: 20
+          maxTokens: 32
+          compactionRetries: 1
+      - insert:
+          - id: llm-replay
+            name: '@deepseek-ai/dsh-llm-replay'
+            config:
+              providers:
+                - id: deepseek-official
+                  models:
+                    - id: deepseek-v4-flash
+                      contextWindow: 128000
diff --git a/examples/headless-agent/tests/compaction.e2e.ts b/examples/headless-agent/tests/compaction.e2e.ts
index 07f239a73e..6fe6f4055b 100644
--- a/examples/headless-agent/tests/compaction.e2e.ts
+++ b/examples/headless-agent/tests/compaction.e2e.ts
@@ -11,8 +11,8 @@ import { SessionId } from '@deepseek-ai/dsh-session'
  * Key-gated smoke for mid-session compaction. It verifies the compact event
  * pair, replacement of older surface nodes, and a final answer after compaction.
  */
-// FIXME(compaction-snapshot): this is the only full compaction coverage because
-// replay cannot serve the summarizer's unlogged model call.
+// The keyless headless snapshot pins deterministic overflow recovery; this test
+// remains the independent live-provider smoke for organic pressure and summary quality.
 
 let workdir: string | undefined
 let ctx: Context | undefined
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 121bbf75ed..f9cb46111a 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -29,6 +29,10 @@ const goalScenarioDir = join(snapshotsDir, 'goal-tools')
 const goalConfigPath = fileURLToPath(new URL('../goal.cordis.snapshot.yml', import.meta.url))
 const retryScenarioDir = join(snapshotsDir, 'provider-retry')
 const retryConfigPath = fileURLToPath(new URL('../retry.cordis.snapshot.yml', import.meta.url))
+const compactionScenarioDir = join(snapshotsDir, 'compaction-recovery')
+const compactionSessionFixture = join(compactionScenarioDir, 'session.jsonl')
+const compactionStreamExpected = join(compactionScenarioDir, 'stream-json.expected.jsonl')
+const compactionConfigPath = fileURLToPath(new URL('../compaction.cordis.snapshot.yml', import.meta.url))
 const credentialsScenarioDir = join(snapshotsDir, 'missing-credential')
 const credentialsConfigPath = fileURLToPath(new URL('../credentials.cordis.snapshot.yml', import.meta.url))
 // Same keyless composition as the missing-credential scenario: the endpoint is
@@ -227,6 +231,75 @@ describe('headless stream-json snapshots', () => {
     expect(normalized).toBe(await readFile(streamExpected, 'utf8'))
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
+  it('recovers from context overflow through an assembled compaction', async () => {
+    const prompt = await scenarioPrompt(compactionScenarioDir, 'compaction-recovery')
+    let expectedSession = await readFile(compactionSessionFixture, 'utf8')
+    let runCwd = ''
+    const result = await runLoaderSmoke({
+      label: 'compaction recovery headless stream-json snapshot',
+      tempDirPrefix: 'headless-snapshot-compaction-recovery-',
+      binScript,
+      configPath: compactionConfigPath,
+      binArgs: ['--config', compactionConfigPath, '--output-format', 'stream-json', prompt],
+      tsconfigPath,
+      env: {
+        DSH_SNAPSHOT: 'replay',
+        DSH_SNAPSHOT_FILE: compactionSessionFixture,
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      prepare: (cwd) => { runCwd = cwd },
+      inspect: async (cwd) => {
+        const logs = await persistedLogs(cwd)
+        expect(logs).toHaveLength(1)
+        const actual = logs[0]
+        if (actual === undefined) throw new Error('compaction snapshot did not persist its session')
+        const records = parseJsonl(actual.content)
+        const types = records.map(record => record.type)
+        expect(types.filter(type => type === 'compact/start')).toHaveLength(1)
+        expect(types.filter(type => type === 'compact/summary')).toHaveLength(1)
+        expect(types.filter(type => type === 'compact/end')).toHaveLength(1)
+        const start = types.indexOf('compact/start')
+        const summary = types.indexOf('compact/summary')
+        const replacement = records.findIndex((record) => {
+          if (record.type !== 'user/message') return false
+          const surfaceOp = record.surfaceOp as JsonObject | undefined
+          return surfaceOp?.op === 'replace'
+        })
+        const end = types.indexOf('compact/end')
+        expect(start).toBeLessThan(summary)
+        expect(summary).toBeLessThan(replacement)
+        expect(replacement).toBeLessThan(end)
+        const summaryRecord = records[summary]
+        const summaryData = summaryRecord?.data as JsonObject | undefined
+        expect(summaryData?.shadowedSeqs).toEqual(expect.arrayContaining([expect.any(Number)]))
+        const final = [...records].reverse().find(record => record.type === 'assistant/message')
+        expect(JSON.stringify(final)).toContain('COMPACTION RECOVERED')
+
+        const actualContext = contextFromLogs([actual.content])
+        if (refreshing) {
+          const harvested: HarvestedLog = {
+            id: String(actual.header.id),
+            createdAt: Number(actual.header.createdAt),
+            content: actual.content,
+          }
+          const replacements = refreshFixtureReplacements([harvested], [expectedSession])
+          expectedSession = tokenizeSessionFixtureCwd(
+            stabilizeRefreshLog(actual.content, expectedSession, replacements, actualContext),
+          )
+          await writeFile(compactionSessionFixture, expectedSession)
+        }
+        const expectedContext = contextFromLogs([expectedSession])
+        expect(scrubRequestHeaders(normalizeSessionLog(actual.content, actualContext)))
+          .toBe(scrubRequestHeaders(normalizeSessionLog(expectedSession, expectedContext)))
+      },
+    })
+
+    expect(result.stderr).toBe('')
+    const normalized = normalizeHeadlessStream(result.stdout, runCwd)
+    if (refreshing) await writeFile(compactionStreamExpected, normalized)
+    expect(normalized).toBe(await readFile(compactionStreamExpected, 'utf8'))
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
   it('logs actionable missing-credential guidance through the one-shot app', async () => {
     const streamExpected = join(credentialsScenarioDir, 'stream-json.expected.jsonl')
     let runCwd = ''
diff --git a/examples/headless-agent/tests/snapshots/compaction-recovery/input.json b/examples/headless-agent/tests/snapshots/compaction-recovery/input.json
new file mode 100644
index 0000000000..3ccad96b83
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/compaction-recovery/input.json
@@ -0,0 +1,8 @@
+{
+  "steps": [
+    {
+      "op": "prompt",
+      "text": "Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."
+    }
+  ]
+}
diff --git a/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl b/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
new file mode 100644
index 0000000000..855e66ac14
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
@@ -0,0 +1,32 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"agent/inbox/spliced","seq":0,"time":1786123401613,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"6335ca4a-a577-47dd-8219-aa81f39cdbc0"}]}}
+{"type":"turn/start","seq":1,"time":1786123401614,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":1786123401614,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":3,"time":1786123401667,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":4,"time":1786123401667,"data":{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"6335ca4a-a577-47dd-8219-aa81f39cdbc0"},"surfaceOp":"append"}
+{"type":"session/title","seq":5,"time":1786123401667,"data":{"title":"Establish a durable compaction premise","messageSeqs":[4],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":6,"time":1786123401668,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/context","seq":7,"time":1786123401669,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":128000}}
+{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_compaction_marker","name":"bash","argumentsDelta":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}}
+{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}}}
+{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":24,"outputTokens":6}}}}
+{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":13,"time":1786123401680,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"e54f73a8-572a-40ee-b908-8a8a27b83bf8"},"usage":{"inputTokens":24,"outputTokens":6}},"sourceEventSeqs":[8,9,10,11,12],"surfaceOp":"append"}
+{"type":"tool/call","seq":14,"time":1786123401680,"data":{"turn":1,"step":1,"callId":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}
+{"type":"tool/result","seq":15,"time":1786123401700,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_compaction_marker"},"content":[{"type":"tool-result","toolCallId":"call_compaction_marker","content":[{"type":"text","text":"alpha\n"}],"isError":false}],"role":"user","id":"b4a6504e-f39d-40b0-b51a-b11fbd60b135"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"step/end","seq":16,"time":1786123401700,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":17,"time":1786123401710,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":18,"time":1786123401715,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot request exceeded the model context window","code":"CONTEXT_WINDOW_EXCEEDED"}}}}}
+{"type":"compact/start","seq":19,"time":1786123401715,"data":{"turn":1}}
+{"type":"compact/summary","seq":20,"time":1786123401725,"data":{"summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}
+{"type":"user/message","seq":21,"time":1786123401725,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"6d2afb13-a37b-48d6-9ea5-fc8734127377"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}
+{"type":"compact/end","seq":22,"time":1786123401725,"data":{"turn":1}}
+{"type":"assistant/chunk","seq":23,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":24,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"COMPACTION RECOVERED"}}}
+{"type":"assistant/chunk","seq":25,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"COMPACTION RECOVERED"}}}}
+{"type":"assistant/chunk","seq":26,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":20,"outputTokens":4}}}}
+{"type":"assistant/chunk","seq":27,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":28,"time":1786123401730,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"COMPACTION RECOVERED"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"346742d0-50e3-4594-b53c-f26c7da82c56"},"usage":{"inputTokens":20,"outputTokens":4}},"sourceEventSeqs":[23,24,25,26,27],"surfaceOp":"append"}
+{"type":"step/end","seq":29,"time":1786123401730,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":30,"time":1786123401730,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
new file mode 100644
index 0000000000..4d798adc37
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
@@ -0,0 +1,32 @@
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"agent/inbox/spliced","seq":0,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"}]}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/start","seq":1,"time":0,"data":{"turn":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"agent/inbox/spliced","seq":2,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":4,"time":0,"data":{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"session/title","seq":5,"time":0,"data":{"title":"Establish a durable compaction premise","messageSeqs":[4],"source":{"kind":"fallback"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/header","seq":6,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/context","seq":7,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":128000}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_compaction_marker","name":"bash","argumentsDelta":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":24,"outputTokens":6}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":13,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":24,"outputTokens":6}},"sourceEventSeqs":[8,9,10,11,12],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":14,"time":0,"data":{"turn":1,"step":1,"callId":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":15,"time":0,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_compaction_marker"},"content":[{"type":"tool-result","toolCallId":"call_compaction_marker","content":[{"type":"text","text":"alpha\n"}],"isError":false}],"role":"user","id":"{{sessionId}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":16,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":17,"time":0,"data":{"turn":1,"step":2}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot request exceeded the model context window","code":"CONTEXT_WINDOW_EXCEEDED"}}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/start","seq":19,"time":0,"data":{"turn":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/summary","seq":20,"time":0,"data":{"summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":21,"time":0,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"{{sessionId}}"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/end","seq":22,"time":0,"data":{"turn":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":23,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":24,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"COMPACTION RECOVERED"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":25,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"COMPACTION RECOVERED"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":26,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":20,"outputTokens":4}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":27,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":28,"time":0,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"COMPACTION RECOVERED"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":20,"outputTokens":4}},"sourceEventSeqs":[23,24,25,26,27],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":29,"time":0,"data":{"turn":1,"step":2}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":30,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
+{"type":"result","sessionId":"{{sessionId}}","output":"COMPACTION RECOVERED","usage":{"inputTokens":44,"outputTokens":10}}
diff --git a/packages/support/llm-replay/README.i18n.yaml b/packages/support/llm-replay/README.i18n.yaml
index a4729b2e69..3f3e349a84 100644
--- a/packages/support/llm-replay/README.i18n.yaml
+++ b/packages/support/llm-replay/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/support/llm-replay/README.md
-README.md: ee062d0c2804905f33f1ff476d12bb6dd57666e5
-README.zh.md: ab3420d9500a6ca77f04a2ad96095f8883aeb874
+README.md: 46d391970f320708914d11f0868cbbc5361ae196
+README.zh.md: a67b078a1396968dc3ddecb0e616a832c4faaf3a
diff --git a/packages/support/llm-replay/README.md b/packages/support/llm-replay/README.md
index ee062d0c28..46d391970f 100644
--- a/packages/support/llm-replay/README.md
+++ b/packages/support/llm-replay/README.md
@@ -8,7 +8,9 @@ Its consumers are the ACP and headless `stream-json` snapshot suites plus the We
 
 ## How the fixture works
 
-The fixture IS the persisted session log (`<scenario>/session.jsonl`). Its `assistant/chunk` events carry every `StreamChunk`, so grouping them by `(turn, step)` reconstructs each `stream()` call's chunk sequence (one model call per loop step). Recording is therefore "run the real agent once and harvest the `.jsonl`", done by the snapshot harness — this plugin does not record. A fixture may carry its `request/header` content tokenized to `{{system}}`/`{{tools}}` (the harness pins that content in one scenario and scrubs the rest); replay is indifferent — derivation reads only `assistant/chunk` events and the line-0 session header.
+The fixture IS the persisted session log (`<scenario>/session.jsonl`). Its `assistant/chunk` events carry every `StreamChunk`, so grouping them by `(turn, step)` reconstructs each agent-loop `stream()` call's chunk sequence. A successful compaction summarizer is logged differently: when `compact/summary` carries its complete `rawOutput`, replay reconstructs a canonical successful stream at that event's position using one `block-start`/`block-end` pair per block, the recorded usage when present, and a terminal `stop`. Exact provider delta partitioning is not part of the durable compaction result. A summary without `rawOutput` does not imply an LLM call because template and remote summarizers may produce it without the local adapter.
+
+Recording is therefore "run the real agent once and harvest the `.jsonl`", done by the snapshot harness — this plugin does not record. A fixture may carry its `request/header` content tokenized to `{{system}}`/`{{tools}}` (the harness pins that content in one scenario and scrubs the rest); replay is indifferent — derivation reads only `assistant/chunk` and `compact/summary` events plus the line-0 session header.
 
 Two failure modes are not reconstructable from `assistant/chunk` alone — a pure throw before any chunk (e.g. an HTTP 401, where the log holds only a `turn/end {error}` and no chunks) and a cancel/hang (timing, not chunk content). A scenario that needs those supplies an optional sidecar (`<scenario>/replay.override.json`) that either replaces the derived script (a bare `ReplayEntry[]`) or augments it (`{ patches: [{ at, entry }] }`: keep every JSONL-derived call and swap the named 0-based call indexes; `at` equal to the derived length appends the retry attempt after an injected transient throw). Patch indexes must be unique. The override document, each patch and entry, and every chunk discriminant are validated when the file loads. A `hang` entry may name `readyFile`; replay writes that empty marker after its prefix chunks reach the loop and before it waits for cancellation, so an external driver can cancel deterministically without observing a presentation update.
 
@@ -57,7 +59,7 @@ Replay keys every call by its calling session id (`GenerateOptions.sessionId`, s
 - `installLlmReplay(ctx, config)` — install the configured replay adapter or catch-all `llm/stream` listener; returns a `ReplayHandle` (`dispose()` for HMR safety plus `assertConsumed()`, the teardown check that every recorded script bound to a live session and every bound cursor drained — turning a scenario that silently drove fewer model calls than recorded into a crisp diagnostic). Use this in tests to drive replay without the Loader or env vars.
 - `loadSessionScripts(config)` — resolve the ordered `SessionScript[]` (primary + children) for a scenario, ready to bind to live sessions in first-call order.
 - `loadReplayScript(config)` — resolve the `ReplayEntry[]` for the primary session only (validated sidecar replacement/patches if present, else derived from the JSONL; fail-loud if the fixture is missing).
-- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)` / `resolveScriptedEntry(entry, messages)` — the pure helpers that turn a recorded session log into a script, read its header `id`/`createdAt`, and resolve `{{fromRequest:...}}` placeholders against one live request. A derived group must end in a `finish` chunk; a group without one is the fingerprint of a thrown `stream()` and must instead be expressed via an override sidecar.
+- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)` / `resolveScriptedEntry(entry, messages)` — the pure helpers that turn ordinary loop chunks and complete compaction outputs in a recorded session log into a script, read its header `id`/`createdAt`, and resolve `{{fromRequest:...}}` placeholders against one live request. A derived assistant group must end in a `finish` chunk; a group without one is the fingerprint of a thrown `stream()` and must instead be expressed via an override sidecar.
 - Types `ReplayEntry` / `ReplayOverrideDoc` / `ReplayOverridePatch` / `SessionScript` / `ReplayConfig` / `ReplayProviderConfig` / `ReplayModelConfig` / `ReplayHandle` / `Config`.
 
 ## Plugin export shape
@@ -74,5 +76,5 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **First-call-order script binding assumes sequential delegation** — a cut that runs sibling subagents concurrently (or a compaction summarize call landing mid-run) would bind live sessions to recorded scripts non-deterministically; a stronger keying is deferred until such a scenario exists (`XXX(concurrent-subagents)`).
-- **Only chunk-producing calls are derivable** — a pure pre-chunk throw or a cancel/hang scenario needs the `replay.override.json` sidecar. Replacement and patch forms affect only the primary session; child scripts still derive from their logs.
+- **First-call-order script binding assumes sequential delegation** — a cut that runs sibling subagents concurrently would bind live sessions to recorded scripts non-deterministically; a stronger keying is deferred until such a scenario exists (`XXX(concurrent-subagents)`).
+- **Only ordinary loop chunks and completed compaction outputs are derivable** — a pure pre-chunk throw or a cancel/hang scenario needs the `replay.override.json` sidecar. Replacement and patch forms affect only the primary session; child scripts still derive from their logs.
diff --git a/packages/support/llm-replay/README.zh.md b/packages/support/llm-replay/README.zh.md
index ab3420d950..a67b078a13 100644
--- a/packages/support/llm-replay/README.zh.md
+++ b/packages/support/llm-replay/README.zh.md
@@ -8,7 +8,9 @@
 
 ## fixture 的工作方式
 
-fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件包含每个 `StreamChunk`，因此按 `(turn, step)` 分组即可重建每次 `stream()` 调用的分片序列（每个循环步骤调用一次模型）。因此，录制就是「运行一次真实 agent 并收集 `.jsonl`」，由快照 harness 完成；该插件本身不录制。fixture 的 `request/header` 内容可能被标记化为 `{{system}}`/`{{tools}}`（harness 会在一个场景中固定该内容，并清除其余场景中的内容）；回放不受影响，因为派生过程只读取 `assistant/chunk` 事件和第 0 行的会话 header。
+fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件包含每个 `StreamChunk`，因此按 `(turn, step)` 分组即可重建每次 agent-loop `stream()` 调用的分片序列。压缩（compaction）摘要器成功时，日志记录方式有所不同：当 `compact/summary` 携带完整的 `rawOutput` 时，回放会在该事件的位置重建一条规范成功流，其中每个块各使用一对 `block-start`/`block-end`，带上已记录的 usage（如有），并以 `stop` 终止。提供方增量的精确切分不属于持久压缩结果。不带 `rawOutput` 的摘要并不意味着发生了 LLM 调用，因为模板摘要器和远程摘要器可能不经本地适配器生成该摘要。
+
+因此，录制就是「运行一次真实 agent 并收集 `.jsonl`」，由快照 harness 完成；该插件本身不录制。fixture 的 `request/header` 内容可能被标记化为 `{{system}}`/`{{tools}}`（harness 会在一个场景中固定该内容，并清除其余场景中的内容）；回放不受影响，因为派生过程只读取 `assistant/chunk` 和 `compact/summary` 事件以及第 0 行的会话 header。
 
 有两种失败模式无法仅根据 `assistant/chunk` 重建：在产生任何分片前直接抛出异常（例如 HTTP 401，此时日志只有 `turn/end {error}` 而没有分片），以及取消或挂起（差异在时序，而非分片内容）。需要这些行为的场景可提供伴随文件（`<scenario>/replay.override.json`）：它可以替换派生脚本（裸 `ReplayEntry[]`），也可以增补派生脚本（`{ patches: [{ at, entry }] }`：保留所有从 JSONL 派生的调用，只替换指定的从 0 开始计数的调用索引；当 `at` 等于派生长度时，则在注入瞬态异常后的重试位置追加一次调用）。补丁索引不得重复。文件加载时会校验覆写文档、每个补丁和条目，以及每个分片的判别标签。`hang` 条目可以指定 `readyFile`；当前缀分片到达循环后、开始等待取消前，回放会写入这个空标记，使外部驱动程序无需观察展示层更新即可确定性地取消。
 
@@ -57,7 +59,7 @@ fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `as
 - `installLlmReplay(ctx, config)`：安装已配置回放适配器或 catch-all `llm/stream` 监听器；返回 `ReplayHandle`（包含用于保证 HMR（热模块替换）安全的 `dispose()`，以及清理阶段执行的 `assertConsumed()` 检查；后者确保每个已记录脚本都绑定到实时会话，且每个已绑定游标都已耗尽，从而将场景静默驱动的模型调用少于记录数转换为明确诊断）。在测试中使用它，可以不通过 Loader 或 env var 驱动回放。
 - `loadSessionScripts(config)`：解析场景中有序的 `SessionScript[]`（主会话 + 子会话），准备按首次调用顺序绑定到实时会话。
 - `loadReplayScript(config)`：只解析主会话的 `ReplayEntry[]`（如果伴随文件存在，则使用经校验的替换或补丁；否则从 JSONL 派生；fixture 缺失时明确报错）。
-- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)` / `resolveScriptedEntry(entry, messages)`：将已记录会话日志转换为脚本、读取其 header `id`/`createdAt`、并针对单次实时请求解析 `{{fromRequest:...}}` 占位符的纯辅助工具。派生分组必须以 `finish` 分片结束；没有该分片的分组是 `stream()` 抛出异常的指纹，必须改用 override 伴随文件表达。
+- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)` / `resolveScriptedEntry(entry, messages)`：将已记录会话日志中的普通 loop 分片和完整压缩输出转换为脚本、读取其 header `id`/`createdAt`、并针对单次实时请求解析 `{{fromRequest:...}}` 占位符的纯辅助工具。派生的 assistant 分组必须以 `finish` 分片结束；没有该分片的分组是 `stream()` 抛出异常的指纹，必须改用 override 伴随文件表达。
 - 类型 `ReplayEntry` / `ReplayOverrideDoc` / `ReplayOverridePatch` / `SessionScript` / `ReplayConfig` / `ReplayProviderConfig` / `ReplayModelConfig` / `ReplayHandle` / `Config`。
 
 ## 插件导出形态
@@ -74,5 +76,5 @@ fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `as
 
 ## 已知限制与暂缓事项
 
-- **首次调用顺序脚本绑定假设串行委托**：并发运行同级 subagent 的 cut（或运行中发生的上下文压缩（context compaction）摘要调用）会非确定性地将实时会话绑定到已记录脚本；在这种场景出现前暂不实现更强的键控（`XXX(concurrent-subagents)`）。
-- **只有会产生分片的调用才能派生**：在产生分片前直接抛出异常或取消/挂起的场景需要 `replay.override.json` 伴随文件。替换和补丁两种形式都只影响主会话；子会话脚本仍从各自日志派生。
+- **首次调用顺序脚本绑定假设串行委托**：并发运行同级 subagent 的 cut 会非确定性地将实时会话绑定到已记录脚本；在这种场景出现前暂不实现更强的键控（`XXX(concurrent-subagents)`）。
+- **只有普通 loop 分片和已完成的压缩输出才能派生**：在产生分片前直接抛出异常或取消/挂起的场景需要 `replay.override.json` 伴随文件。替换和补丁两种形式都只影响主会话；子会话脚本仍从各自日志派生。
diff --git a/packages/support/llm-replay/package.json b/packages/support/llm-replay/package.json
index 708e84b57a..af5e2929f3 100644
--- a/packages/support/llm-replay/package.json
+++ b/packages/support/llm-replay/package.json
@@ -25,12 +25,14 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-compact": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/support/llm-replay/src/index.ts b/packages/support/llm-replay/src/index.ts
index ae62843492..8733a4296c 100644
--- a/packages/support/llm-replay/src/index.ts
+++ b/packages/support/llm-replay/src/index.ts
@@ -1,14 +1,16 @@
 /**
  * Keyless snapshot-test LLM replay. It derives one model-call script per
- * recorded session from `assistant/chunk` events and binds fresh live sessions
- * to parent/child scripts by first-call order. Throw and hang cases require an
- * explicit override because a session log cannot reconstruct them alone.
+ * recorded session from `assistant/chunk` events and durable compaction
+ * summaries, then binds fresh live sessions to parent/child scripts by
+ * first-call order. Throw and hang cases require an explicit override because
+ * a session log cannot reconstruct them alone.
  * @module @deepseek-ai/dsh-llm-replay
  */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { delimiter as pathDelimiter } from 'node:path'
 import type { Context } from 'cordis'
+import type {} from '@deepseek-ai/dsh-compact'
 import { decodeStorageRecord } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import type {
@@ -24,8 +26,9 @@ import { LlmAdapter, LlmError, assertNever, resolveRetryPolicy } from '@deepseek
 
 /**
  * One recorded model call. `throw` may replay prefix chunks before failing;
- * `hang` models cancellation. Only ordinary chunk entries derive from JSONL;
- * the other variants come from an override sidecar.
+ * `hang` models cancellation. Chunk entries derive from ordinary model streams
+ * and complete compaction outputs in JSONL; the other variants come from an
+ * override sidecar.
  */
 export type ReplayEntry =
   | { kind: 'chunks'; chunks: StreamChunk[] }
@@ -174,10 +177,12 @@ export function parseSessionHeader(text: string): { id: string; createdAt: numbe
  * Reconstruct the per-`stream()` replay script from a recorded session log.
  *
  * Splits `assistant/chunk` events at every `finish`, using turn and step changes
- * to detect an unterminated prior call. A missing terminator means the live
- * stream threw, so derivation rejects and the scenario must provide an explicit
- * override. Multiple calls may share one turn and step when the loop retries.
- * @param events - the recorded session's events; only `assistant/chunk` is consulted.
+ * to detect an unterminated prior call. A complete `compact/summary.rawOutput`
+ * becomes a canonical successful stream at the summary's log position. A
+ * missing assistant terminator means the live stream threw, so derivation
+ * rejects and the scenario must provide an explicit override. Multiple calls
+ * may share one turn and step when the loop retries.
+ * @param events - the recorded session's events.
  * @returns one `chunks` entry per recorded model call, in call order.
  */
 export function deriveReplayScript(events: SessionEvent[]): ReplayEntry[] {
@@ -195,6 +200,22 @@ export function deriveReplayScript(events: SessionEvent[]): ReplayEntry[] {
     script.push({ kind: 'chunks', chunks })
   }
   for (const event of events) {
+    if (event.type === 'compact/summary') {
+      close(currentKey, current)
+      currentKey = undefined
+      current = []
+      if (event.data.rawOutput !== undefined) {
+        const chunks: StreamChunk[] = []
+        for (const [index, block] of event.data.rawOutput.entries()) {
+          chunks.push({ type: 'block-start', index, blockType: block.type })
+          chunks.push({ type: 'block-end', index, block })
+        }
+        if (event.data.usage !== undefined) chunks.push({ type: 'usage', usage: event.data.usage })
+        chunks.push({ type: 'finish', reason: { kind: 'stop' } })
+        script.push({ kind: 'chunks', chunks })
+      }
+      continue
+    }
     if (event.type !== 'assistant/chunk') continue
     const { turn, step, chunk } = event.data
     const key = `${turn}/${step}`
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index 0b7d87ad13..9483a4c4f6 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -178,6 +178,93 @@ describe('deriveReplayScript', () => {
     expect(deriveReplayScript(events)).toEqual([{ kind: 'chunks', chunks: errChunks }])
   })
 
+  it('inserts compact/summary output between the calls surrounding it', () => {
+    const overflow: StreamChunk[] = [
+      { type: 'finish', reason: { kind: 'error', failure: { message: 'too large', code: 'CONTEXT_WINDOW_EXCEEDED' } } },
+    ]
+    const block = { type: 'text' as const, text: 'durable checkpoint' }
+    const rawOutput = [block]
+    const usage = { inputTokens: 9, outputTokens: 2 }
+    const summaryChunks: StreamChunk[] = [
+      { type: 'block-start', index: 0, blockType: 'text' },
+      { type: 'block-end', index: 0, block },
+      { type: 'usage', usage },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ]
+    let seq = 1
+    const events: SessionEvent[] = [
+      ...overflow.map(chunk => chunkEvent(seq++, 1, 2, chunk)),
+      { type: 'compact/start', seq: seq++, time: 0, data: { turn: 1 } },
+      {
+        type: 'compact/summary',
+        seq: seq++,
+        time: 0,
+        data: {
+          summary: rawOutput,
+          rawOutput,
+          shadowedRange: { start: 1, end: 1 },
+          shadowedSeqs: [1],
+          shadowedTokenCount: 20,
+          provider: 'mock',
+          model: 'mock',
+          usage,
+        },
+      },
+      ...TEXT_CHUNKS.map(chunk => chunkEvent(seq++, 1, 2, chunk)),
+    ]
+
+    expect(deriveReplayScript(events)).toEqual([
+      { kind: 'chunks', chunks: overflow },
+      { kind: 'chunks', chunks: summaryChunks },
+      { kind: 'chunks', chunks: TEXT_CHUNKS },
+    ])
+  })
+
+  it('does not infer an LLM call from compact/summary without raw output', () => {
+    const event: SessionEvent<'compact/summary'> = {
+      type: 'compact/summary',
+      seq: 1,
+      time: 0,
+      data: {
+        summary: [{ type: 'text', text: 'template result' }],
+        shadowedRange: { start: 1, end: 1 },
+        shadowedSeqs: [1],
+        shadowedTokenCount: 20,
+        provider: 'template',
+        model: 'template',
+      },
+    }
+
+    expect(deriveReplayScript([event])).toEqual([])
+  })
+
+  it('derives a compact/summary stream when usage is unavailable', () => {
+    const block = { type: 'text' as const, text: 'summary without usage' }
+    const event: SessionEvent<'compact/summary'> = {
+      type: 'compact/summary',
+      seq: 1,
+      time: 0,
+      data: {
+        summary: [block],
+        rawOutput: [block],
+        shadowedRange: { start: 1, end: 1 },
+        shadowedSeqs: [1],
+        shadowedTokenCount: 20,
+        provider: 'mock',
+        model: 'mock',
+      },
+    }
+
+    expect(deriveReplayScript([event])).toEqual([{
+      kind: 'chunks',
+      chunks: [
+        { type: 'block-start', index: 0, blockType: 'text' },
+        { type: 'block-end', index: 0, block },
+        { type: 'finish', reason: { kind: 'stop' } },
+      ],
+    }])
+  })
+
   it('throws on a group that lacks a terminal finish chunk (a thrown stream)', () => {
     // A thrown stream(): prefix chunks logged, then turn/end (error reason), NO finish.
     const events: SessionEvent[] = [
diff --git a/packages/support/llm-replay/tsconfig.json b/packages/support/llm-replay/tsconfig.json
index 673ee51547..b8dc74e792 100644
--- a/packages/support/llm-replay/tsconfig.json
+++ b/packages/support/llm-replay/tsconfig.json
@@ -14,6 +14,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../compact/compact"
+    },
     {
       "path": "../../llm/llm"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c3a3d5ecca..078f775ecf 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -5959,6 +5959,9 @@ importers:
 
   packages/support/llm-replay:
     devDependencies:
+      '@deepseek-ai/dsh-compact':
+        specifier: workspace:^
+        version: link:../../compact/compact
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../invariants

From 74ba0b532edd355a974541d1e1663a5f7c77f939 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 01:33:56 +0800
Subject: [PATCH 187/516] chore: sync the lockfile for the dsh-skill llm
 dependency

---
 pnpm-lock.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bd4ff1ea14..045d76aeab 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -5155,6 +5155,9 @@ importers:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis

From 95c01e6e61195c3c993fb306ffea8a5627e1224b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 01:40:14 +0800
Subject: [PATCH 188/516] cleanup: reject private issue shorthand

---
 .../2026-08-06-api-key-format-validation.i18n.yaml   |  4 ++--
 .../bug-fix/2026-08-06-api-key-format-validation.md  |  6 ++----
 .../2026-08-06-api-key-format-validation.zh.md       |  6 ++----
 scripts/verify-public-repository-links.spec.ts       |  7 +++++--
 scripts/verify-public-repository-links.ts            | 12 ++++++++----
 5 files changed, 19 insertions(+), 16 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index e1c3ac3ef8..f4f105e124 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.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 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
-2026-08-06-api-key-format-validation.md: e9ca76ede06080f2b868f6436998d163e642adbc
-2026-08-06-api-key-format-validation.zh.md: 5666a884d4c9478291072375681d8d3526b2632a
+2026-08-06-api-key-format-validation.md: 2174cb466c6af72f15005ce1ba3dec8100de6f2f
+2026-08-06-api-key-format-validation.zh.md: f9b7d6518fedc42e5264c46beaa1a78619139c58
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
index e9ca76ede0..2174cb466c 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
@@ -14,13 +14,11 @@ Pasting a key containing an emoji, CJK text, or a full-width punctuation mark in
 
 Whitespace passed every check. `ProviderEditor` tested `keyDraft.length`, so a key of three spaces was stored and then authenticated as `Bearer` plus blanks. Neither adapter checked a credential- or environment-sourced key — the path the Models page writes, and therefore the path users actually take.
 
-Sources: deepseek-harness#1594 and #1595; dsh-external#247, #249, #266, and #210.
-
 ## Decision
 
 One rule defines a legal key: **after trimming, non-empty, and every character within `[\x21-\x7E]`** — printable ASCII, space excluded.
 
-This single predicate covers every input the sources list: empty, leading and trailing whitespace, interior whitespace, C0 control characters, emoji, CJK text, and full-width punctuation. It is also exactly the constraint that produced the ByteString failure, so the two issues close on one definition rather than on two coincidentally related fixes.
+This single predicate covers every reported input: empty, leading and trailing whitespace, interior whitespace, C0 control characters, emoji, CJK text, and full-width punctuation. It is also exactly the constraint that produced the ByteString failure, so the failures share one definition rather than two coincidentally related fixes.
 
 A second, narrower rule catches a pasted environment line: input matching `^[A-Z][A-Z0-9_]*=[^=]` or wrapped in matching quotes is refused. Restricting the prefix to upper-case keeps real keys clear of it — `sk-` forms break the identifier match at the hyphen — and requiring a non-`=` character after the separator keeps base64 padding clear of it too. It reports the same format failure as an illegal character rather than its own message: the reader's next move is identical either way, so a separate line would name a cause without changing what to do.
 
@@ -76,7 +74,7 @@ The client cannot import any of this: client packages reference only client pack
 
 **Running the shape heuristic in the resolvers too.** Symmetric, and it would stop a pasted environment line written directly into `.env`. Rejected for the lockout described above: a false positive in a resolver leaves the user no working path, while a false positive in the browser leaves the environment open.
 
-**Probing the provider at save time to prove the key works.** It would close the complaint the sources actually open with — a save that reports success and fails at the first turn. Rejected as out of scope and, on the code as it stood, unbuildable: `discoverModels` short-circuits to the installed catalog before any network call for exactly the providers pi-ai ships catalogs for, so it verified nothing about the key, and the DeepSeek card has no probe at all. A verifier's value is distinguishing "key rejected" from "cannot reach", which is the distinction this change makes reliable; building it first would have produced a verifier unable to tell its own outcomes apart. Comparable products also do not verify on save, so a blocking network call there would be an unexpected behavior rather than a missing one.
+**Probing the provider at save time to prove the key works.** It would close the original complaint — a save that reports success and fails at the first turn. Rejected as out of scope and, on the code as it stood, unbuildable: `discoverModels` short-circuits to the installed catalog before any network call for exactly the providers pi-ai ships catalogs for, so it verified nothing about the key, and the DeepSeek card has no probe at all. A verifier's value is distinguishing "key rejected" from "cannot reach", which is the distinction this change makes reliable; building it first would have produced a verifier unable to tell its own outcomes apart. Comparable products also do not verify on save, so a blocking network call there would be an unexpected behavior rather than a missing one.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index 5666a884d4..f9b7d6518f 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -14,13 +14,11 @@ Status: implemented
 
 空白字符能通过每一道检查。`ProviderEditor` 判的是 `keyDraft.length`，于是三个空格构成的 Key 会被存下，随后以 `Bearer` 加若干空格去认证。两个适配器都不检查来自凭据或环境的 Key——而那正是 Models 页写入的路径，也就是用户真正走的路径。
 
-来源：deepseek-harness#1594 与 #1595；dsh-external#247、#249、#266、#210。
-
 ## Decision
 
 一条规则定义什么是合法 Key：**trim 之后非空，且每个字符都落在 `[\x21-\x7E]`**——可打印 ASCII，不含空格。
 
-这一个断言覆盖了来源列出的全部输入：空值、首尾空白、中间空白、C0 控制字符、emoji、中文、全角标点。它同时正是造成 ByteString 失败的那条约束，所以两个 issue 收敛于同一个定义，而不是两个恰好相关的修复。
+这一个断言覆盖了所有已报告的输入：空值、首尾空白、中间空白、C0 控制字符、emoji、中文、全角标点。它同时正是造成 ByteString 失败的那条约束，所以这些故障收敛于同一个定义，而不是两个恰好相关的修复。
 
 第二条更窄的规则用于识别整行粘贴的环境变量：匹配 `^[A-Z][A-Z0-9_]*=[^=]` 或首尾成对引号的输入会被拒绝。把前缀限定为全大写可以让真实 Key 与之绝缘——`sk-` 这类形态会在连字符处中断标识符匹配——而要求分隔符之后必须是非 `=` 字符，则让 base64 的 padding 也与之绝缘。它报出的是与非法字符相同的那条格式失败，而不是自己的一句：读到它的人下一步动作完全一样，因此单列一句只会点出一个原因，却不改变该怎么做。
 
@@ -76,7 +74,7 @@ Status: implemented
 
 **让形状启发式也在 resolver 中运行。** 更对称，且能拦住直接写进 `.env` 的整行环境变量。因上文所述的锁死风险而否决：resolver 中的一次误判会让用户无路可走，浏览器中的一次误判则仍留有环境变量这条路。
 
-**在保存时探测 provider 以证明 Key 可用。** 它能关掉来源真正开篇抱怨的那件事——保存报成功、第一轮才失败。因超出范围而否决，且在当时的代码上无法建成：对 pi-ai 恰好自带 catalog 的那些 provider，`discoverModels` 会在任何网络调用之前短路到内置 catalog，因而对 Key 什么都验证不了；而 DeepSeek 卡片根本没有探测。验证器的价值在于分清「Key 被拒」与「无法连通」，而这正是本次改动让其变得可靠的区分；先建验证器只会得到一个分不清自身结果的验证器。同类产品也不在保存时验证，因此保存时的阻断式网络调用会是一个意外行为，而非一处缺失。
+**在保存时探测 provider 以证明 Key 可用。** 它能关掉最初报告的那件事——保存报成功、第一轮才失败。因超出范围而否决，且在当时的代码上无法建成：对 pi-ai 恰好自带 catalog 的那些 provider，`discoverModels` 会在任何网络调用之前短路到内置 catalog，因而对 Key 什么都验证不了；而 DeepSeek 卡片根本没有探测。验证器的价值在于分清「Key 被拒」与「无法连通」，而这正是本次改动让其变得可靠的区分；先建验证器只会得到一个分不清自身结果的验证器。同类产品也不在保存时验证，因此保存时的阻断式网络调用会是一个意外行为，而非一处缺失。
 
 ## Consequences
 
diff --git a/scripts/verify-public-repository-links.spec.ts b/scripts/verify-public-repository-links.spec.ts
index b05dcb65d1..615bfa68e2 100644
--- a/scripts/verify-public-repository-links.spec.ts
+++ b/scripts/verify-public-repository-links.spec.ts
@@ -2,15 +2,18 @@ import { describe, expect, it } from 'vitest'
 import { findInternalRepositoryReferences } from './verify-public-repository-links.ts'
 
 describe('public repository link policy', () => {
-  it('rejects the internal remote and accepts the public home', () => {
-    const internalRepository = ['deepseek-harness', 'deepseek-harness'].join('/')
+  it('rejects internal repository references and accepts the public home', () => {
+    const internalOwner = ['deepseek', 'harness'].join('-')
+    const internalRepository = [internalOwner, internalOwner].join('/')
     const source = [
       'https://github.com/deepseek-ai/deepseek-harness-sdk',
       `https://github.com/${internalRepository}/issues/1`,
+      `${internalOwner}#2`,
     ].join('\n')
 
     expect(findInternalRepositoryReferences('subject.md', source)).toEqual([
       { file: 'subject.md', line: 2 },
+      { file: 'subject.md', line: 3 },
     ])
   })
 })
diff --git a/scripts/verify-public-repository-links.ts b/scripts/verify-public-repository-links.ts
index dc8d2b3b35..a57628e00c 100644
--- a/scripts/verify-public-repository-links.ts
+++ b/scripts/verify-public-repository-links.ts
@@ -1,4 +1,4 @@
-/** Reject tracked files that expose the internal repository remote. */
+/** Reject tracked files that expose the internal repository identity. */
 
 import { execFileSync } from 'node:child_process'
 import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs'
@@ -6,7 +6,9 @@ import { resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 const root = resolve(import.meta.dirname, '..')
-const internalRepository = ['deepseek-harness', 'deepseek-harness'].join('/')
+const internalOwner = ['deepseek', 'harness'].join('-')
+const internalRepository = [internalOwner, internalOwner].join('/')
+const internalIssueShorthand = `${internalOwner}#`
 
 /** One tracked reference to the internal repository. */
 export interface InternalRepositoryReference {
@@ -25,7 +27,9 @@ export interface InternalRepositoryReference {
 export function findInternalRepositoryReferences(file: string, source: string): InternalRepositoryReference[] {
   const references: InternalRepositoryReference[] = []
   for (const [index, line] of source.split('\n').entries()) {
-    if (line.includes(internalRepository)) references.push({ file, line: index + 1 })
+    if (line.includes(internalRepository) || line.includes(internalIssueShorthand)) {
+      references.push({ file, line: index + 1 })
+    }
   }
   return references
 }
@@ -55,7 +59,7 @@ const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(re
 if (isMain) {
   const references = scanRepository(root)
   if (references.length === 0) {
-    console.log('verify-public-repository-links: tracked files expose no internal repository remote.')
+    console.log('verify-public-repository-links: tracked files expose no internal repository identity.')
   } else {
     console.error('verify-public-repository-links: internal repository references found:')
     for (const reference of references) console.error(`  ${reference.file}:${String(reference.line)}`)

From eba4df1e86c4b2e94792178e5f35b3330814b3c8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 01:50:37 +0800
Subject: [PATCH 189/516] cleanup: skip redundant Issue lifecycle ready runs

---
 ...-driven-issue-lifecycle-triggers.i18n.yaml |  6 ++++
 ...-review-driven-issue-lifecycle-triggers.md | 31 +++++++++++++++++++
 ...view-driven-issue-lifecycle-triggers.zh.md | 31 +++++++++++++++++++
 .github/workflows/issue-lifecycle.yml         |  1 -
 scripts/ci-workflow.spec.ts                   | 28 +++++++++++++++++
 5 files changed, 96 insertions(+), 1 deletion(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.md
 create mode 100644 .agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.zh.md

diff --git a/.agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.i18n.yaml
new file mode 100644
index 0000000000..a82d54640c
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.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/process/2026-08-08-review-driven-issue-lifecycle-triggers.md
+2026-08-08-review-driven-issue-lifecycle-triggers.md: 8a2d48ee23da4c20bb832ae0109e2ea9912dac83
+2026-08-08-review-driven-issue-lifecycle-triggers.zh.md: 004739ff471815b0fe12e111eba0ec7aaaef9507
diff --git a/.agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.md b/.agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.md
new file mode 100644
index 0000000000..8a2d48ee23
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.md
@@ -0,0 +1,31 @@
+# Agent Note: Review-driven Issue lifecycle triggers
+
+Status: implemented
+
+English | [中文](2026-08-08-review-driven-issue-lifecycle-triggers.zh.md)
+
+## Problem
+
+The Issue lifecycle workflow reads the current pull request after each subscribed repository event and projects resolving Issues forward to `In progress` or `In review`. A resolving draft already reaches `In progress` from its `opened` event. Changing that draft to ready creates no new lifecycle outcome until a reviewer is requested or submits a review, yet subscribing to `ready_for_review` launches another hosted job and creates another GitHub App token.
+
+Draft-to-ready automation commonly submits a review moments later. In that sequence the ready job cannot advance the Issue, while the review job is still required to observe the `In review` phase.
+
+## Decision
+
+[Issue lifecycle](../../../../.github/workflows/issue-lifecycle.yml) does not subscribe to `pull_request.ready_for_review`. It retains `pull_request.review_requested` and `pull_request_review.submitted`, so either a requested reviewer or a submitted review can advance a resolving Issue to `In review`. The handler continues to fetch the live pull request instead of deriving phase from the triggering payload.
+
+[Issue policy](../../../../.github/workflows/issue-policy.yml) still subscribes to `ready_for_review`. That workflow owns the required check when a human pull request enters review; removing a lifecycle trigger does not weaken policy enforcement.
+
+The workflow test parses both files and pins this split. The lifecycle policy tests separately pin that draft and open resolving pull requests reach `In progress`, while a review request or submitted review reaches `In review`.
+
+## Alternatives considered
+
+- **Keep both events and cancel an in-progress run** - rejected because concurrency can discard a pending run but cannot combine two webhook payloads into one execution. Cancelling the earlier mutation also makes correctness depend on arrival order, while a completed ready job still consumes the full runner setup.
+- **Remove the submitted-review event** - rejected because a review may arrive without an explicit review request. In that path `pull_request_review.submitted` is the only repository event that exposes the transition to `In review`.
+- **Delay every pull request event behind a debounce dispatcher** - rejected because another queue or scheduled workflow adds latency and control-plane state to eliminate a trigger that carries no lifecycle information.
+
+## Consequences
+
+A draft becoming ready no longer launches Issue lifecycle work. The resolving Issue remains `In progress` from an earlier pull request event until a review is requested or submitted, at which point one review-driven run can advance it to `In review`. The required Issue policy check still runs at the ready boundary.
+
+If a future lifecycle phase depends on ready status itself, that change must restore the trigger and update the workflow test and this decision. Until then, omitting `ready_for_review` saves one hosted run from the common ready-then-review sequence without dropping a status transition.
diff --git a/.agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.zh.md b/.agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.zh.md
new file mode 100644
index 0000000000..004739ff47
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-review-driven-issue-lifecycle-triggers.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 由评审驱动的 Issue 生命周期触发器
+
+Status: implemented
+
+[English](2026-08-08-review-driven-issue-lifecycle-triggers.md) | 中文
+
+## 问题
+
+Issue 生命周期工作流会在每个已订阅的仓库事件发生后读取当前 PR（Pull Request），并将解决型 Issue 的状态向前推进到 `In progress` 或 `In review`。解决型草稿 PR 已通过其 `opened` 事件进入 `In progress`。在请求评审人或评审人提交评审之前，把该草稿转为可评审状态不会产生新的生命周期结果；但订阅 `ready_for_review` 仍会启动另一个托管作业，并创建另一个 GitHub App token。
+
+草稿转为可评审状态的自动化通常会在片刻后提交评审。在这一事件序列中，转为可评审状态的作业无法推进 Issue，而要观察到 `In review` 阶段，仍必须运行评审作业。
+
+## 决策
+
+[Issue 生命周期](../../../../.github/workflows/issue-lifecycle.yml)不订阅 `pull_request.ready_for_review`。它保留 `pull_request.review_requested` 和 `pull_request_review.submitted`，因此无论是请求评审人还是提交评审，都可以将解决型 Issue 推进至 `In review`。处理程序仍会获取实时 PR，而不是根据触发事件的载荷推导阶段。
+
+[Issue 政策](../../../../.github/workflows/issue-policy.yml)仍订阅 `ready_for_review`。该工作流负责在由人类发起的 PR 进入评审时执行必需检查；移除生命周期触发器不会削弱政策执行。
+
+工作流测试会解析这两个文件，并固定这种划分。生命周期政策测试另行固定以下行为：草稿及开放状态的解决型 PR 会进入 `In progress`，评审请求或已提交评审则会使其进入 `In review`。
+
+## 考虑过的替代方案
+
+- **保留两个事件并取消正在进行的工作流运行**：不予采纳，因为并发控制可以丢弃待处理的工作流运行，却无法把两个 webhook 载荷合并为一次执行。取消较早的状态变更操作也会使正确性依赖事件到达顺序；而已经完成的转为可评审状态作业仍会产生完整的运行器初始化开销。
+- **移除已提交评审事件**：不予采纳，因为评审可能在没有明确评审请求的情况下直接提交。在这条路径中，`pull_request_review.submitted` 是唯一能让系统观察到进入 `In review` 这一状态转换的仓库事件。
+- **让每个 PR 事件都先经过防抖分派器再处理**：不予采纳，因为新增一条队列或一个定时工作流会引入延迟和控制平面状态，只为消除一个不携带生命周期信息的触发器。
+
+## 后果
+
+草稿转为可评审状态后，不再启动 Issue 生命周期工作。解决型 Issue 会保持在更早的 PR 事件所设定的 `In progress`，直到请求或提交评审；届时，一次由评审驱动的工作流运行即可将其推进至 `In review`。必需的 Issue 政策检查仍会在转为可评审状态的边界运行。
+
+如果未来某个生命周期阶段依赖可评审状态本身，相关变更必须恢复该触发器，并更新工作流测试和本决策。在此之前，省略 `ready_for_review` 可使常见的先转为可评审状态、再提交评审这一序列少启动一次托管工作流运行，而不会遗漏状态转换。
diff --git a/.github/workflows/issue-lifecycle.yml b/.github/workflows/issue-lifecycle.yml
index 4dc6869e27..7a25b5223d 100644
--- a/.github/workflows/issue-lifecycle.yml
+++ b/.github/workflows/issue-lifecycle.yml
@@ -21,7 +21,6 @@ on:
       - reopened
       - labeled
       - unlabeled
-      - ready_for_review
       - review_requested
   pull_request_review:
     types:
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index 7febf0049a..baeac7a8c0 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -28,6 +28,34 @@ describe('CI workflow', () => {
   })
 })
 
+describe('Issue lifecycle workflow', () => {
+  it('uses review signals instead of rerunning when a draft becomes ready', () => {
+    const lifecycle = loadWorkflow('.github/workflows/issue-lifecycle.yml')
+    const lifecyclePullRequest = workflowEvent(lifecycle, 'pull_request')
+    const lifecycleReview = workflowEvent(lifecycle, 'pull_request_review')
+    const policy = loadWorkflow('.github/workflows/issue-policy.yml')
+    const policyPullRequest = workflowEvent(policy, 'pull_request')
+
+    expect(lifecyclePullRequest.types).not.toContain('ready_for_review')
+    expect(lifecyclePullRequest.types).toContain('review_requested')
+    expect(lifecycleReview.types).toContain('submitted')
+    expect(policyPullRequest.types).toContain('ready_for_review')
+  })
+})
+
+function loadWorkflow(path: string): Record<string, unknown> {
+  const workflow: unknown = yaml.load(readFileSync(resolve(root, path), 'utf8'))
+  if (!isRecord(workflow)) throw new TypeError(`${path} must define a workflow`)
+  return workflow
+}
+
+function workflowEvent(workflow: Record<string, unknown>, event: string): Record<string, unknown> {
+  if (!isRecord(workflow.on) || !isRecord(workflow.on[event])) {
+    throw new TypeError(`workflow must define the ${event} event`)
+  }
+  return workflow.on[event]
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }

From db146f0eba2c4b26987beff5a7a2e243a2c2ebe8 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 01:52:42 +0800
Subject: [PATCH 190/516] refactor(host): share the turn-start route refusal
 between prompt and skill.invoke

turnAgentFor owns the addressed-agent resolution and the model-unavailable
refusal both turn-starting methods repeat; the duplication gate flagged the
copied block.
---
 packages/host/apiproxy/src/api-proxy.ts | 66 +++++++++++++------------
 1 file changed, 35 insertions(+), 31 deletions(-)

diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 6384a4d408..3970a801a3 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -1248,6 +1248,35 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     return llm === undefined || llm.listProviders().some(entry => entry.id === provider)
   }
 
+  /**
+   * Resolve the addressed agent for a turn-starting method and refuse when no
+   * adapter serves its current route: a route nothing serves cannot start a
+   * turn, and letting it try spends the whole pre-step path to fail inside
+   * the adapter with a message about registration. Refusing here names the
+   * model the session is pointed at while the draft is still in the composer.
+   * This is the enforcement boundary shared by `session.prompt` and
+   * `skill.invoke`: a client that disables its input is an affordance, and
+   * both methods stay callable regardless.
+   */
+  async function turnAgentFor<T>(
+    request: RpcRequest<unknown>, sessionId: SessionId,
+  ): Promise<{ agent: Agent } | { refused: RpcResponse<T> }> {
+    const found = await agentFor(sessionId)
+    if ('error' in found) return { refused: err(request, found.error) }
+    const agent = found.agent
+    const target = targetFor(agent).current
+    if (!routeServed(target.provider)) {
+      return {
+        refused: err(request, {
+          code: 'model-unavailable',
+          message: `no adapter serves provider "${target.provider}"; select a model for this session`,
+          details: { provider: target.provider, model: target.model },
+        }),
+      }
+    }
+    return { agent }
+  }
+
   /** Missing-service report shared by the settings domain (skills-domain stance). */
   function settingsAbsent(): RpcError {
     return { code: 'internal', message: 'settings service is absent: this deployment does not mount a settings provider (e.g. @deepseek-ai/dsh-settings-local) in its composition', details: {} }
@@ -1784,23 +1813,9 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
 
       async prompt(request) {
         const { sessionId, mode, content } = request.payload
-        const found = await agentFor(sessionId)
-        if ('error' in found) return err(request, found.error)
-        const agent = found.agent
-        // A route no adapter serves cannot start a turn, and letting it try
-        // spends the whole pre-step path to fail inside the adapter with a
-        // message about registration. Refusing here names the model the
-        // session is pointed at while the draft is still in the composer.
-        // This is the enforcement boundary: a client that disables its input
-        // is an affordance, and this method stays callable regardless.
-        const target = targetFor(agent).current
-        if (!routeServed(target.provider)) {
-          return err(request, {
-            code: 'model-unavailable',
-            message: `no adapter serves provider "${target.provider}"; select a model for this session`,
-            details: { provider: target.provider, model: target.model },
-          })
-        }
+        const resolved = await turnAgentFor<{ accepted: true }>(request, sessionId)
+        if ('refused' in resolved) return resolved.refused
+        const agent = resolved.agent
         // The rpcId rides MessageSource into user/message (merge declaration in api/sessions.ts; provisional correlation).
         const source: MessageSource = { kind: 'user', rpcId: request.rpcId }
         try {
@@ -2377,20 +2392,9 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
 
       async invoke(request) {
         const { sessionId, name, text } = request.payload
-        const found = await agentFor(sessionId)
-        if ('error' in found) return err(request, found.error)
-        const agent = found.agent
-        // Same turn-start refusal boundary as sessions.prompt: injection
-        // starts a turn, so a route no adapter serves is refused while the
-        // composer still shows the draft.
-        const target = targetFor(agent).current
-        if (!routeServed(target.provider)) {
-          return err(request, {
-            code: 'model-unavailable',
-            message: `no adapter serves provider "${target.provider}"; select a model for this session`,
-            details: { provider: target.provider, model: target.model },
-          })
-        }
+        const resolved = await turnAgentFor<{ accepted: true }>(request, sessionId)
+        if ('refused' in resolved) return resolved.refused
+        const agent = resolved.agent
         const skillRegistry = ctx.get('skills')
         if (skillRegistry === undefined) {
           return err(request, { code: 'internal', message: 'skill registry is absent: this deployment does not mount @deepseek-ai/dsh-skill in its composition (cordis.yml or explicit assembly)', details: {} })

From 3584d8e08804aae652dcaa43ed63052b6cddc50c Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 01:52:43 +0800
Subject: [PATCH 191/516] docs(skill): document the user-explicit invocation
 path

Bilingual README updates for the four touched packages (ui-skill's claim
flow and deterministic-injection model experience, the apiproxy skills
domain, the shared renderSkillContent seam export, the catalog stitch
sentence), the implemented Agent Note triplet recording the decision and
its peer-product evidence, and the regenerated catalogs/graphs.
---
 ...8-user-explicit-skill-invocation.i18n.yaml |  6 ++++
 ...26-08-08-user-explicit-skill-invocation.md | 36 +++++++++++++++++++
 ...08-08-user-explicit-skill-invocation.zh.md | 36 +++++++++++++++++++
 docs/config-catalog.md                        |  4 +--
 docs/cordis-catalog/events.md                 |  2 +-
 docs/cordis-catalog/services.md               |  2 +-
 docs/event-producer-consumer.md               |  2 +-
 packages/client/ui-skill/README.i18n.yaml     |  4 +--
 packages/client/ui-skill/README.md            | 15 ++++----
 packages/client/ui-skill/README.zh.md         | 15 ++++----
 packages/host/apiproxy/README.i18n.yaml       |  4 +--
 packages/host/apiproxy/README.md              |  2 +-
 packages/host/apiproxy/README.zh.md           |  2 +-
 packages/skill/skill/README.i18n.yaml         |  4 +--
 packages/skill/skill/README.md                |  4 +++
 packages/skill/skill/README.zh.md             |  4 +++
 packages/skill/tool-skill/README.i18n.yaml    |  4 +--
 packages/skill/tool-skill/README.md           |  3 +-
 packages/skill/tool-skill/README.zh.md        |  3 +-
 19 files changed, 121 insertions(+), 31 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md

diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
new file mode 100644
index 0000000000..ed9de78dbb
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.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-08-08-user-explicit-skill-invocation.md
+2026-08-08-user-explicit-skill-invocation.md: 9249ee5c9c712e9c6aa827e97178f352728ed927
+2026-08-08-user-explicit-skill-invocation.zh.md: f15975c3b13fbf76e036fcece30253e78e7b417d
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
new file mode 100644
index 0000000000..9249ee5c9c
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
@@ -0,0 +1,36 @@
+# Agent Note: User-explicit skill invocation over skill.invoke
+
+Status: implemented
+
+English | [中文](2026-08-08-user-explicit-skill-invocation.zh.md)
+
+## Problem
+
+A `disable-model-invocation: true` skill is user-only by design: it never enters the model-facing catalog and the `skill` tool refuses to load it. Its only legitimate entry point is an explicit user gesture — yet the web client had none. `skill.list` filtered to the model-and-user intersection (hiding user-only skills from the menu), an entered `/name` line rode into the default prompt sink as plain text, and the model it reached was forbidden to load the skill — so it degraded to `read`-ing the SKILL.md file or ignoring the gesture (issue #1470). Even for ordinary skills, the decision-21 plain-text reference made user invocation a collaboration cue the model could ignore, not a guarantee.
+
+## Decision
+
+User-explicit invocation is a deterministic host-side injection, uniform for every user-invocable skill:
+
+- `skill.invoke { sessionId, name, text? }` (host apiproxy) enforces user-invocation policy at the operation boundary (`skill-not-found` / `skill-not-invocable`), renders the skill with the shared `renderSkillContent`, appends the optional trailing text after a blank line, and injects the whole as one user-role message carrying the new `skill-invocation` `MessageSource` kind (`{ name, args? }`) before starting a turn through the same route-served gate as `session.prompt`.
+- `renderSkillContent` moved from `dsh-tool-skill` to the `dsh-skill` seam: the `skill` tool result and the injection share one verbatim `<skill_content>` shape, and the catalog text gained the seam rule — an inline-injected skill must be followed, not re-loaded through the tool.
+- `skill.list` serves every user-invocable skill and carries `modelInvocable`, so the browser menu lists user-only skills with a marker (description prefix — the `hint` field is claim-state ghost text the menu never renders).
+- ui-skill claims a menu pick or an entered `/name [args]` into the invoke transaction (`matchEnter` strong-waits the catalog; unknown names stay plain prompts). The unreached legacy `<skill>name</skill>` reference codec is removed.
+- The transcript materializes the injection as a dedicated `skill-invocation` node from source metadata (never re-parsed from the body) and renders a right-aligned bubble: `/name` chip, trailing text, and the injected block collapsed behind a disclosure.
+
+Peer-product survey (Pi, OpenCode, Claude Code, Kimi Code, Codex, DeepSeek-Reasonix — local checkouts) was unanimous: user-explicit triggering is programmatic injection as a user-role message with zero model participation on every product, prompt-guided tool loading exists only on the model-autonomous track, and the disable-model-invocation equivalents gate only the model-side surfaces. Kimi's origin-metadata rendering and the Claude Code/Kimi no-reload prompt rule translate directly onto `MessageSource` and the catalog sentence.
+
+## Alternatives considered
+
+- **`agent.inject()` context injection** — no peer precedent; the gesture is a user turn, not an environment notice, and context-row presentation, compaction, and attribution all mismatch. Rejected.
+- **A host `/skill <name>` command** (command registry, plan-mode precedent) — two-token UX, no name completion, and user-only skills stay undiscoverable in the menu; the per-cwd skill catalog also fits the static command registry poorly. Rejected.
+- **Client-side expansion** (fetch body, splice into the prompt) — authorization becomes bypassable client courtesy, the log loses the invocation semantics, and Codex deleted its equivalent mechanism (custom prompts) in favor of core injection. Rejected.
+- **Host prompt-pipeline scanning for `/name`** (Codex `$name` core mentions) — duplicates the adjudication layer and risks swallowing literal slashes in prose; the claim path already covers the need. Rejected.
+- **Per-injection preamble line** (Kimi's `User activated the skill …`) — dropped in favor of a one-time catalog sentence: same context, paid once, and the injected block stays byte-identical with the tool result.
+
+## Consequences
+
+- Decision 21's plain-text reference path is superseded at submission: the draft still carries plain text and lexicon-derived chip visuals, but submit claims into a deterministic injection instead of shipping the literal and hoping. The model-autonomous track (catalog + `skill` tool) is unchanged.
+- Every user-invocable skill invocation now costs its full rendered body unconditionally — the price of determinism the peer survey showed everyone pays.
+- The `skill-invocation` source rides `user/message`, so Model-visible ⟺ logged holds with no new event type, and replay/UI read metadata rather than text markers.
+- TUI and ACP can adopt `skill.invoke` later for the same semantics; until then the TUI's client-side expansion remains its own path.
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
new file mode 100644
index 0000000000..f15975c3b1
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 经 skill.invoke 的用户显式 skill 调用
+
+Status: implemented
+
+[English](2026-08-08-user-explicit-skill-invocation.md) | 中文
+
+## 问题
+
+`disable-model-invocation: true` 的 skill（技能）在设计上就是仅限用户的：它绝不进入面向模型的目录，`skill` 工具也拒绝加载它。它唯一正当的入口是一次显式的用户手势——而 web 客户端此前没有这个入口。`skill.list` 过滤到模型与用户的交集（把仅限用户的 skill 挡在菜单之外），回车提交的 `/name` 一行以纯文本落入默认提示词 sink，而这行文本到达的模型又被禁止加载该 skill——于是退化为模型去 `read` 那份 SKILL.md 文件，或者干脆无视这次手势（issue #1470）。即使对普通 skill，决策 21 的纯文本引用也让用户调用只是模型可以忽略的协作线索，而不是保证。
+
+## 决策
+
+用户显式调用是一次确定性的宿主侧注入，对每一个用户可调用的 skill 一致：
+
+- `skill.invoke { sessionId, name, text? }`（宿主 apiproxy）在操作边界强制执行用户调用策略（`skill-not-found`/`skill-not-invocable`），用共享的 `renderSkillContent` 渲染该 skill，在一个空行之后追加可选的尾随文本，并把整体作为一条携带新增 `skill-invocation` `MessageSource` kind（`{ name, args? }`）的 user 角色消息注入，随后经由与 `session.prompt` 相同的「路由是否有适配器在服务」闸门开启一个轮次。
+- `renderSkillContent` 从 `dsh-tool-skill` 移入 `dsh-skill` seam：`skill` 工具结果与注入共享同一份逐字一致的 `<skill_content>` 形态，目录文本则新增了这条 seam 规则——已内联注入的 skill 必须被遵循，而不是再经工具重新加载。
+- `skill.list` 提供每一个用户可调用的 skill 并携带 `modelInvocable`，因此浏览器菜单会带标记地列出仅限用户的 skill（描述前缀——`hint` 字段是认领态的 ghost text，菜单从不渲染它）。
+- ui-skill 把菜单 pick 或回车提交的 `/name [args]` 认领进 invoke 事务（`matchEnter` 强等目录；未知名称保持为普通提示词）。已不可达的旧 `<skill>name</skill>` 引用 codec 被移除。
+- transcript（文本记录）依据来源元数据把这次注入物化为专用的 `skill-invocation` 节点（绝不从正文重新解析），并渲染为一个右对齐气泡：`/name` chip、尾随文本，以及收在 disclosure 之后的注入块。
+
+同类产品调研（Pi、OpenCode、Claude Code、Kimi Code、Codex、DeepSeek-Reasonix——本地检出）结论一致：在每个产品上，用户显式触发都是以 user 角色消息做程序化注入、模型零参与；提示词引导的工具加载只存在于模型自主轨道上；disable-model-invocation 的对应物只把关模型侧表层。Kimi 的来源元数据渲染与 Claude Code/Kimi 的禁止重载提示词规则，可直接平移到 `MessageSource` 与目录那句话上。
+
+## 考虑过的替代方案
+
+- **`agent.inject()` 上下文注入**——没有同类产品先例；这次手势是一个用户轮次，不是环境通知，而且上下文行呈现、压缩（compaction）与归属全都不匹配。否决。
+- **宿主 `/skill <name>` 命令**（命令注册表，plan 模式先例）——两 token 的 UX、没有名称补全、仅限用户的 skill 在菜单里仍不可发现；按 cwd 的 skill 目录也与静态命令注册表格格不入。否决。
+- **客户端展开**（拉取正文、拼进提示词）——授权沦为可被绕过的客户端善意，日志失去调用语义，而且 Codex 已删除其等价机制（custom prompts）转向核心注入。否决。
+- **宿主提示词流水线扫描 `/name`**（Codex 的 `$name` core mentions）——重复了裁决层，还有吞掉普通行文中字面斜杠的风险；认领路径已经覆盖了这一需求。否决。
+- **每次注入一条前导语**（Kimi 的 `User activated the skill …`）——弃用，改为一次性的目录句子：同样的上下文、只支付一次，且注入块与工具结果保持逐字节一致。
+
+## 后果
+
+- 决策 21 的纯文本引用路径在提交处被取代：草稿仍承载纯文本与 lexicon 派生的 chip 视觉，但提交会认领进一次确定性注入，而不是把字面文本发出去再碰运气。模型自主轨道（目录 + `skill` 工具）不变。
+- 每一次用户可调用 skill 的调用现在都无条件付出其完整渲染正文的成本——这是确定性的代价，同类调研表明所有产品都在支付。
+- `skill-invocation` 来源搭乘 `user/message`，因此「模型可见 ⟺ 已记录」在不新增事件类型的情况下继续成立，回放与 UI 读取的是元数据而非文本标记。
+- TUI 与 ACP 之后可以为同样的语义采用 `skill.invoke`；在那之前，TUI 的客户端展开仍是它自己的路径。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 21f38d18e2..9f1bf08f9d 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1471,7 +1471,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/skill/skill/src/index.ts:170`](../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:261`](../packages/skill/skill/src/index.ts)
 
 ## `@deepseek-ai/dsh-skill-local`
 
@@ -2063,7 +2063,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/skill/tool-skill/src/index.ts:58`](../packages/skill/tool-skill/src/index.ts)
+Source: [`packages/skill/tool-skill/src/index.ts:59`](../packages/skill/tool-skill/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-str-replace-editor`
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 4ad9797262..55952b3591 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -677,7 +677,7 @@ A skill provider, runtime contribution, or provider-backed catalog may have chan
 'skills/change'(): void
 ```
 
-Source: [`packages/skill/skill/src/index.ts:188`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:279`](../../packages/skill/skill/src/index.ts)
 
 ## `subagent/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 4a73dc06ad..4abd00c1fd 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -1946,7 +1946,7 @@ async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefiniti
 
 Types: [SkillCatalogSnapshot](../core-data-structures/skills.md) · [SkillDefinition](../core-data-structures/skills.md) · [SkillLookupOptions](../core-data-structures/skills.md) · [SkillProvider](../core-data-structures/skills.md) · [SkillProviderControl](../core-data-structures/skills.md) · [SkillRegistration](../core-data-structures/skills.md) · [SkillSummary](../core-data-structures/skills.md)
 
-Source: [`packages/skill/skill/src/index.ts:209`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:300`](../../packages/skill/skill/src/index.ts)
 
 ## `ctx.spillStore` — `SpillStore` (abstract seam)
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 9d486c46f6..7511ab8076 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -36,7 +36,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
-| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:188`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
+| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:279`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:160`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:134`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index ca4bc68ebf..cb9eeef56e 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/client/ui-skill/README.md
-README.md: f70bd2780f255cd8e0c64acb3da3863e10c4fa9d
-README.zh.md: 6eb6cbd3ae196a540e161a3a23f9df2136824f2e
+README.md: c888622bc92b038413c7d0ebf63abb61b483f6f5
+README.zh.md: 3bbbc90186726356c53f375bb664d678c4926988
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index f70bd2780f..c888622bc9 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -2,7 +2,9 @@
 
 English | [中文](README.zh.md)
 
-Skill reference source, browser half: registers the `/`-trigger `skill` source into `ctx.slash`. Ordinary-session candidates come from the `skill.list` RPC addressed by the per-call `ClientSessionContext` projection's `{sessionId}`, with the host resolving `cwd` from the session header. The host returns the intersection of model-invocable and user-invocable skills because this browser path inserts a model reference rather than loading the body directly. Catalog-addressed continuable children resolve no skill candidates locally because the existing skill RPC requires an attached session; viewing their persisted history must not activate them. Catalogs cache per ordinary session with a single-flight fetch; the scope-birth `warm` hook prewarms the session's entry and `connection/reset` clears everything. Results filter by `startsWith(query)`; picking a candidate lands the literal `/name ` text through the slash pipeline (decision 21 plain-text reference), and the source `codec` owns the reference's two projections: `clipboardText` → `/name`, `serialize` → the model form `<skill>name</skill>` invoked at submit time. The RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument. The source implements no `matchSpace`/`matchEnter` hooks — skill references never enter command adjudication and ride ordinary prompts into the default sink.
+Skill invocation source, browser half: registers the `/`-trigger `skill` source into `ctx.slash`. Ordinary-session candidates come from the `skill.list` RPC addressed by the per-call `ClientSessionContext` projection's `{sessionId}`, with the host resolving `cwd` from the session header. The host serves every user-invocable skill; a `modelInvocable: false` entry (a `disable-model-invocation` skill, whose only entry point is this path) wears the user-only marker as a description prefix in the active language. Catalog-addressed continuable children resolve no skill candidates locally because the existing skill RPC requires an attached session; viewing their persisted history must not activate them. Catalogs cache per ordinary session with a single-flight fetch; the scope-birth `warm` hook prewarms the session's entry and `connection/reset` clears everything. Results filter by `startsWith(query)`.
+
+A menu pick or an entered `/name [args]` line claims the composer into an args-tolerant `skill.invoke` transaction (`matchEnter` strong-waits the catalog; an unknown name answers undefined and stays a plain prompt). Submit trims the args, keeps blank args off the wire, and folds an RPC refusal into the composer's error outcome; the host renders the skill body and injects it as a user message before starting the turn, so invocation is deterministic for every user-invocable skill. The RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument. Draft chip visuals still derive from the `lexicon` scan; the legacy `<skill>name</skill>` reference codec is gone (decision 21 removal cut) and `matchSpace` stays unimplemented — menu and enter own the skill flows.
 
 A failed `skill.list` throws from `candidates`, which the slash shell logs and folds into a silent menu-group drop — the menu shows only pending/ready states.
 
@@ -14,23 +16,22 @@ The browser plugin also registers a keyed `skill` toolview in `conversation.chat
 
 ## Model Experience
 
-### Skill reference text in the user prompt
+### User-explicit skill invocation
 
 #### What the model sees
 
-A picked candidate lands the literal `/name ` in the draft (decision 21: plain text, no `<skill>` tag); the text reaches the model verbatim inside the ordinary user message (`session.prompt`), with no dedicated content block, prompt section, or host-side expansion. The association with the actual skill is model-side and non-deterministic: the session prefix already carries the skill catalog (rendered by `dsh-tool-skill`), and the reference's name matching a catalog entry is what invites the model to load it.
+A claimed invocation never ships the `/name` literal. The host (`skill.invoke`) renders the canonical `<skill_content>` block — the same `renderSkillContent` output the `skill` tool returns — appends the user's trailing text after a blank line, and injects the whole as one user-role message carrying the `skill-invocation` source, immediately starting a turn. Loading is deterministic: the model receives the full body without being asked to call the `skill` tool, and the catalog (rendered by `dsh-tool-skill`) tells it not to re-load an inline-injected skill.
 
 #### Token effect
 
-Conditional and tiny: only a pick (or hand-typing the same text) adds the reference's characters to that one user message. Menu browsing and the candidate fetch add zero model tokens.
+One invocation adds the rendered skill body plus the trailing text to that turn's user message — the same cost as the model loading the skill through the tool, paid unconditionally instead of at the model's discretion. Menu browsing and the candidate fetch add zero model tokens.
 
 #### KV Cache effect
 
-Append-only: the reference is part of a new user message appended after the reusable history prefix. This package never edits earlier request tokens.
+Append-only: the injected message lands after the reusable history prefix. This package never edits earlier request tokens.
 
 ## Known Limitations and Deferred Work
 
 - **Result-only history pages use the generic row** — keyed dispatch needs the paired call in the runtime window; pagination that leaves the call outside has no tool identity. This client presentation feature does not extend the history wire contract to recover it.
-- **Non-deterministic skill loading** — the reference is a collaboration cue, not a guarantee; the model may ignore it. The rework path when hit rate proves insufficient (a host-side `context/skill-reference` guidance package, or full-text injection) sits in the design ledger; the wire text shape would not change.
-- **First keystroke may race the prewarm** — the scope-birth warm launches the catalog fetch, but a menu opened before it settles shows no skill candidates for that keystroke. Accepted by design: skill references do not participate in enter adjudication, so nothing correctness-bearing waits on the catalog.
+- **Enter waits on the catalog once** — `matchEnter` strong-waits the session's first catalog fetch before answering, so an enter racing a cold cache resolves against the settled catalog rather than silently missing. A menu opened before the prewarm settles still shows no skill candidates for that keystroke.
 - **Text is the truth** — the reference is plain draft text; a hand-typed identical token is the same reference. Chip visuals derive from the lexicon scan; no occurrence identity or position tracking (componentized chips are a ledger item).
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 6eb6cbd3ae..3bbbc90186 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -2,7 +2,9 @@
 
 [English](README.md) | 中文
 
-skill（技能）引用 source 的浏览器端：把 `/` 触发的 `skill` source 注册进 `ctx.slash`。普通会话的候选来自 `skill.list` RPC，以每次调用的 `ClientSessionContext` 投影中的 `{sessionId}` 寻址，host 从会话 header 解析 `cwd`。宿主返回模型可调用与用户可调用 skill 的交集，因为该浏览器路径插入的是模型引用，而不是直接加载正文。由目录寻址的可继续 subagent 在客户端解析为没有 skill 候选，因为现有 skill RPC 要求会话已挂载；查看其持久化历史不得激活它。目录按普通会话缓存，拉取走 single-flight；scope 创建时的 `warm` 钩子预热该会话的缓存项，`connection/reset` 清空全部缓存。结果按 `startsWith(query)` 过滤；pick 一个候选会把字面文本 `/name ` 经 slash 流水线落进草稿（决策 21 的纯文本引用），source 的 `codec` 拥有该引用的两种投影：`clipboardText` → `/name`，`serialize` → 提交时生成的模型形式 `<skill>name</skill>`。RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务。source 不实现 `matchSpace`／`matchEnter` 钩子——skill 引用永不进入命令裁决，随普通提示词落入 default sink。
+skill（技能）调用 source 的浏览器端：把 `/` 触发的 `skill` source 注册进 `ctx.slash`。普通会话的候选来自 `skill.list` RPC，以每次调用的 `ClientSessionContext` 投影中的 `{sessionId}` 寻址，host 从会话 header 解析 `cwd`。宿主提供每一个用户可调用的 skill；`modelInvocable: false` 的条目（即 `disable-model-invocation` skill，此路径是其唯一入口）会以当前语言把仅限用户标记作为描述前缀带上。由目录寻址的可继续 subagent 在客户端解析为没有 skill 候选，因为现有 skill RPC 要求会话已挂载；查看其持久化历史不得激活它。目录按普通会话缓存，拉取走 single-flight；scope 创建时的 `warm` 钩子预热该会话的缓存项，`connection/reset` 清空全部缓存。结果按 `startsWith(query)` 过滤。
+
+菜单 pick 或回车提交的一行 `/name [args]` 会把 composer 认领进一个容忍参数的 `skill.invoke` 事务（`matchEnter` 强等目录；未知名称应答 undefined，保持为普通提示词）。提交时会修剪参数、让空白参数不上协议，并把 RPC 拒绝折叠进 composer 的错误结局；宿主在开启轮次之前渲染 skill 正文并将其作为用户消息注入，因此对每一个用户可调用的 skill，调用都是确定性的。RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务。草稿 chip 视觉仍由 `lexicon` 扫描派生；旧的 `<skill>name</skill>` 引用 codec 已经移除（决策 21 的移除裁定），`matchSpace` 保持不实现——skill 流程归菜单与回车所有。
 
 `skill.list` 失败时 `candidates` 抛出异常，slash 壳层记录日志并折叠为静默的菜单组丢弃——菜单只显示 pending／ready 状态。
 
@@ -14,23 +16,22 @@ skill（技能）引用 source 的浏览器端：把 `/` 触发的 `skill` sourc
 
 ## 模型体验
 
-### 用户提示词中的 skill 引用文本
+### 用户显式 skill 调用
 
 #### 模型看到的内容
 
-被 pick 的候选会把字面文本 `/name ` 落进草稿（决策 21：纯文本，无 `<skill>` 标签）；该文本原样进入普通用户消息（`session.prompt`）到达模型，没有专用内容块、提示词 section 或 host 侧展开。与实际 skill 的关联在模型侧建立且具有非确定性：会话前缀已携带 skill 目录（由 `dsh-tool-skill` 渲染），引用名称与目录条目匹配，正是这一点引导模型去加载它。
+被认领的调用绝不会把字面文本 `/name` 发出去。宿主（`skill.invoke`）渲染规范的 `<skill_content>` 块——与 `skill` 工具返回的 `renderSkillContent` 输出相同——在一个空行之后追加用户的尾随文本，并把整体作为一条携带 `skill-invocation` 来源的 user 角色消息注入，随即开启一个轮次。加载是确定性的：模型无需被要求调用 `skill` 工具就能收到完整正文，目录（由 `dsh-tool-skill` 渲染）也会告诉它不要重新加载已内联注入的 skill。
 
 #### Token 影响
 
-有条件且极小：只有 pick（或手动键入相同文本）会把引用的字符加进那一条用户消息。浏览菜单和拉取候选不会增加任何模型 token。
+一次调用会把渲染后的 skill 正文连同尾随文本加进该轮次的用户消息——成本与模型经由工具加载该 skill 相同，只是无条件支付，而非由模型自行裁量。浏览菜单和拉取候选不会增加任何模型 token。
 
 #### KV Cache 影响
 
-仅追加：引用是追加在可复用历史前缀之后的新用户消息的一部分。该包绝不改写较早的请求 token。
+仅追加：注入的消息落在可复用历史前缀之后。该包绝不改写较早的请求 token。
 
 ## 已知限制与暂缓事项
 
 - **仅含结果的 history 页使用通用行**：键控分派要求配对调用位于 runtime 窗口内；分页将调用留在窗口外时，结果没有工具身份。这项客户端呈现功能不会为了恢复该身份而扩展 history 协议契约。
-- **skill 加载具有非确定性**：引用是协作线索，不是保证；模型可能忽略它。针对命中率不足情况的返工路径（host 侧 `context/skill-reference` 引导包，或全文注入）记录在设计台账中；协议中的文本形态不会改变。
-- **首次击键可能与预热竞速**：scope 创建时的预热会启动目录拉取，但目录落定之前打开的菜单，在那次击键下不会显示 skill 候选。这是设计上接受的取舍：skill 引用不参与回车裁决，因此没有任何攸关正确性的环节等待目录。
+- **回车对目录只等待一次**：`matchEnter` 在应答之前强等该会话的首次目录拉取，因此与冷缓存竞速的回车会对照已落定的目录解析，而不是静默错过。预热落定之前打开的菜单，在那次击键下仍不会显示 skill 候选。
 - **文本是唯一依据**：引用是普通的草稿文本；手动键入的相同 token 就是同一个引用。chip 视觉由 lexicon 扫描派生；没有 occurrence 身份或位置跟踪（组件化 chip 是台账事项）。
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 0a0131d292..017bd32970 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 7ac7bdc6db2e2abbc60d1a8813e229c21ed39fe7
-README.zh.md: d6ece5caed752cf0cc59cc97017549ec2b1e66cb
+README.md: 8d7a24b0b8b897d94ed29d5dc9ed6e9efb250fc6
+README.zh.md: c988b7540ba719d02e50d6da9595353c93766835
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 7ac7bdc6db..8d7a24b0b8 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -46,7 +46,7 @@ Directory picking delegates to the composed `ctx.directoryPicker` backend ([the
 
 `host.openPath` opens a filesystem path with the operating system's default application (`open` on macOS, `Invoke-Item` on Windows, and `xdg-open` on desktop Linux). For `.html`, `.htm`, `.xhtml`, and `.svg`, macOS and desktop Linux prefer a named default browser and fall back to that application handoff when none can be named. WSL translates every Linux path through `wslpath -w` and hands the resulting Windows/UNC path to Windows `Invoke-Item`, including browser-renderable documents, instead of assuming a Linux desktop association. The browser carrier applies the same loopback, same-origin restriction as `host.pickDirectory`.
 
-The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the browser's user-selected model-reference path, so it returns only skills that are both model-invocable and user-invocable; this domain has no direct skill-loading RPC. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
+The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the composer's invocation path: it returns every user-invocable skill with its `modelInvocable` flag, so menus can mark user-only (`disable-model-invocation`) entries whose only entry point this is. `skill.invoke` is the user-explicit loading RPC: it enforces user-invocation policy at this boundary (`skill-not-found` / `skill-not-invocable`), renders the canonical `<skill_content>` body via the shared `renderSkillContent`, appends the optional trailing `text`, injects the whole as a user-role message carrying the `skill-invocation` source, and starts a turn through the same route-served refusal gate as `session.prompt`. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
 
 The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves the namespaces addressed by registered configurable providers (`ctx.llm.listConfigurableProviders()`) plus a small explicit allowlist — the Web preference `permission` and the product-owned `ui-onboarding`; adding a Settings registration alone never makes it remotely readable or writable. Any other namespace answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, the section's `revision`, and the boolean `hasDocument` capability flag. The browser receives no Host path: pathless `settings.openDocument` asks the provider to materialize its document and then hands the Host-resolved result to the native opener, so no browser payload can select an arbitrary filesystem target. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. `llm.discoverModels` interrogates a provider endpoint the page is still drafting: `settingsNs` selects the adapter family that knows how to read the listing, and the endpoint, protocol, and key come from the form rather than from storage. It writes nothing — the reply is candidates, and only a later `settings.mutate` decides what a route serves — so its `apiKey` is the third payload on which a secret may ride, alongside `settings.update`/`mutate` and `credentials.set`. The host never stores or returns it; like the other two it does ride the client's outgoing envelope, which `subscribeEnvelopes()` observers can see, and redacting that tap is a configuration-plane-wide change rather than this method's to make alone. Every refusal (an unserved namespace, a protocol with no readable listing, an unreachable endpoint, a rejected credential) folds into `model-discovery-failed`, whose message is the adapter's own text and whose details name the endpoint asked but never the credential offered. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired by `llm/adapters-updated` and by a change to a configurable-provider namespace, whose settings carry that provider's catalog and endpoint; a `permission` or `ui-onboarding` change emits only its settings invalidation. The browser carrier restricts the whole configuration plane, reads and native actions included (`settings.describe`/`openDocument`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index d6ece5caed..c988b7540b 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -46,7 +46,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 `host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，桌面 Linux 为 `xdg-open`）。对于 `.html`、`.htm`、`.xhtml` 与 `.svg`，macOS 和桌面 Linux 会优先使用能够确定的默认浏览器；无法确定时回退到上述应用交接。WSL 会通过 `wslpath -w` 转换每个 Linux 路径，并将所得 Windows/UNC 路径交给 Windows `Invoke-Item`，浏览器可渲染的文档也不例外，而非假定存在 Linux 桌面文件关联。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。
 
-`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于浏览器中由用户选择的模型引用路径，因此仅返回模型和用户均可调用的 skill；该领域没有直接加载 skill 的 RPC。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
+`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于 composer 的调用路径：它返回每一个用户可调用的 skill 及其 `modelInvocable` 标志，让菜单能够标出仅限用户（`disable-model-invocation`）的条目——此处是这类条目唯一的入口。`skill.invoke` 是用户显式加载 RPC：它在此边界强制执行用户调用策略（`skill-not-found`/`skill-not-invocable`），经共享的 `renderSkillContent` 渲染规范的 `<skill_content>` 正文，追加可选的尾随 `text`，把整体作为一条携带 `skill-invocation` 来源的 user 角色消息注入，并经由与 `session.prompt` 相同的「路由是否有适配器在服务」拒绝闸门开启一个轮次。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
 
 `settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个、也是最后一个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
 
diff --git a/packages/skill/skill/README.i18n.yaml b/packages/skill/skill/README.i18n.yaml
index 03d1b13fe8..fe29171cb3 100644
--- a/packages/skill/skill/README.i18n.yaml
+++ b/packages/skill/skill/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/skill/skill/README.md
-README.md: f538ae668ccff291be86348627d5547150f460df
-README.zh.md: d61a242d01df1e22270c1cb049b922536654bbd6
+README.md: 0c1b2249d8c46ad9ce8097ceeda2bd988c92eb21
+README.zh.md: 8fed350d00433206aecdb32819adc81c82745869
diff --git a/packages/skill/skill/README.md b/packages/skill/skill/README.md
index f538ae668c..0c1b2249d8 100644
--- a/packages/skill/skill/README.md
+++ b/packages/skill/skill/README.md
@@ -37,6 +37,10 @@ This package owns the `ctx.skills` interface. It does not know whether skills co
 | `{ modelInvocable: false, userInvocable: true }` | excluded | included |
 | `{ modelInvocable: false, userInvocable: false }` | excluded | excluded |
 
+### Shared model-facing rendering
+
+`renderSkillContent(skill)` renders one loaded skill as the canonical `<skill_content>` block (escaped `name` attribute, resource hints, verbatim body). It is the single truth for both loading paths: `dsh-tool-skill` returns it as the `skill` tool result, and the host's user-explicit `skill.invoke` injects it as a user message, so the model sees one shape regardless of who initiated the load. `escapeText` is exported beside it for consumers embedding prose in the same markup frame. The package also declares the `skill-invocation` `MessageSource` kind ({ name, args? }) that user-explicit injection stamps on its messages — transcript consumers present the invocation from this metadata instead of re-parsing the body.
+
 `isModelInvocable(skill)` and `isUserInvocable(skill)` read the matching positive field directly. `ctx.skills.get()` remains the trusted, policy-neutral loading primitive, so every user- or model-facing consumer must enforce the predicate that matches its surface before exposing or loading a skill.
 
 ## Provider Contract
diff --git a/packages/skill/skill/README.zh.md b/packages/skill/skill/README.zh.md
index d61a242d01..8fed350d00 100644
--- a/packages/skill/skill/README.zh.md
+++ b/packages/skill/skill/README.zh.md
@@ -37,6 +37,10 @@
 | `{ modelInvocable: false, userInvocable: true }` | 排除 | 包含 |
 | `{ modelInvocable: false, userInvocable: false }` | 排除 | 排除 |
 
+### 共享的面向模型渲染
+
+`renderSkillContent(skill)` 把一个已加载 skill 渲染为规范的 `<skill_content>` 块（转义后的 `name` 属性、资源提示、原样正文）。它是两条加载路径的唯一真源：`dsh-tool-skill` 将其作为 `skill` 工具结果返回，宿主的用户显式 `skill.invoke` 将其作为用户消息注入，因此无论加载由谁发起，模型看到的都是同一种形态。`escapeText` 随之一并导出，供要在同一标记框架中嵌入文案的消费方使用。该包还声明 `skill-invocation` 这个 `MessageSource` kind（{ name, args? }），用户显式注入会把它打在自己的消息上——transcript（文本记录）消费方依据这份元数据呈现该次调用，而不是重新解析正文。
+
 `isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 仍是受信且与策略无关的加载原语，因此每个面向用户或模型的消费方都必须先执行与自身接口匹配的判定，再暴露或加载 skill。
 
 ## 提供方契约
diff --git a/packages/skill/tool-skill/README.i18n.yaml b/packages/skill/tool-skill/README.i18n.yaml
index b57689d742..19fa44c67c 100644
--- a/packages/skill/tool-skill/README.i18n.yaml
+++ b/packages/skill/tool-skill/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/skill/tool-skill/README.md
-README.md: 8e0bff5d1c4853092d412b8f7f9528d4b00d9626
-README.zh.md: c6b815bef59eb1f14be0892078694f129366d004
+README.md: 5c6e592c670f324eb660dbe1fec168fd77e5b368
+README.zh.md: 202a621b1d4047c7d763de3b98c1a69c8c1ee1f7
diff --git a/packages/skill/tool-skill/README.md b/packages/skill/tool-skill/README.md
index 8e0bff5d1c..5c6e592c67 100644
--- a/packages/skill/tool-skill/README.md
+++ b/packages/skill/tool-skill/README.md
@@ -36,7 +36,7 @@ Tool execution does not add a synthetic context message. Its freshly loaded resu
 
 #### What the model sees
 
-If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names.
+If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names. The template's closing sentence is the seam rule against double-loading: the host's user-explicit `skill.invoke` injects the same `renderSkillContent` output (shared from `@deepseek-ai/dsh-skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same sentence.
 
 ##### Skill catalog template
 
@@ -49,6 +49,7 @@ A skill is a reusable set of task-specific instructions. The following skills ar
 </available_skills>
 
 If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.
+A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.
 </system-reminder>
 ```
 
diff --git a/packages/skill/tool-skill/README.zh.md b/packages/skill/tool-skill/README.zh.md
index c6b815bef5..202a621b1d 100644
--- a/packages/skill/tool-skill/README.zh.md
+++ b/packages/skill/tool-skill/README.zh.md
@@ -36,7 +36,7 @@
 
 #### 模型看到的内容
 
-如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。
+如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：宿主的用户显式 `skill.invoke` 会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板携带同一句话。
 
 ##### Skill 目录模板
 
@@ -49,6 +49,7 @@ A skill is a reusable set of task-specific instructions. The following skills ar
 </available_skills>
 
 If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.
+A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.
 </system-reminder>
 ```
 

From 8982d714cb2bc362af06cd1274afc1acb667c891 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 02:15:44 +0800
Subject: [PATCH 192/516] fix(snapshot): harden message id retention

---
 ...table-snapshot-refresh-volatiles.i18n.yaml |   4 +-
 ...07-27-stable-snapshot-refresh-volatiles.md |   8 +-
 ...27-stable-snapshot-refresh-volatiles.zh.md |   8 +-
 examples/jsonrpc-agent/tests/sdk.snapshot.ts  |  13 +-
 .../support/acp-snapshot/README.i18n.yaml     |   4 +-
 packages/support/acp-snapshot/README.md       |   4 +-
 packages/support/acp-snapshot/README.zh.md    |   4 +-
 packages/support/acp-snapshot/package.json    |   2 +
 packages/support/acp-snapshot/src/suite.ts    | 162 +++++++++-----
 .../support/acp-snapshot/tests/suite.spec.ts  | 199 ++++++++++++------
 packages/support/acp-snapshot/tsconfig.json   |   3 +
 pnpm-lock.yaml                                |   3 +
 12 files changed, 283 insertions(+), 131 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
index e322fba1dd..0820c01b7f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.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 .agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
-2026-07-27-stable-snapshot-refresh-volatiles.md: a0613357c698934f91598bdf53da983b1dd53f08
-2026-07-27-stable-snapshot-refresh-volatiles.zh.md: 303a4d6a4cc9f2d45448359c0e48677228a0c1f9
+2026-07-27-stable-snapshot-refresh-volatiles.md: c3eeeca01a7820b5f410bd895de998e944e58eb2
+2026-07-27-stable-snapshot-refresh-volatiles.zh.md: 388b67c67052074fa7423eae294e00b4122b2fe8
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
index a0613357c6..c3eeeca01a 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.md
@@ -12,9 +12,9 @@ Message identity needs a weaker structural precondition than aligned records: an
 
 ## Decision
 
-Before record or refresh writes session fixtures, the shared snapshot support fingerprints every complete surface message with its top-level `id` removed and groups occurrences across all parent/child logs. It reuses an existing UUID only when one fingerprint resolves to exactly one fresh ID and one existing ID, then applies that mapping to every fresh log. Repeated inherited occurrences with the same ID remain one candidate, while new, changed, duplicate-content, malformed, and conflicting messages keep their fresh IDs. ACP, JSON-RPC, and Web recorders pass fixture-ready logs through the same helper before writing.
+Before record or refresh writes session fixtures, the shared snapshot support passes fixture-ready logs to one structural message-ID owner. It recognizes surface carriers through the session package's authoritative surface-type predicate and the correlated queued copies in `agent/inbox/spliced`, fingerprints every complete message with its top-level `id` removed, and records every ID-to-fingerprint edge across all parent/child logs. It reuses an existing UUID only when both its ID and fingerprint have degree one in the fresh and existing graphs, then rewrites only validated message `id` fields in those carriers. Repeated inherited occurrences with the same ID remain one candidate, while new, changed, duplicate-content, malformed, and conflicting messages keep their fresh IDs. ACP, JSON-RPC, and Web recorders run this pass after header scrubbing and cwd tokenization, so fixture spellings rather than raw host paths determine identity.
 
-Refresh write-back uses `normalizeSessionLog` as its volatile-value authority for aligned leaves. It normalizes the original harvested records with the fresh run's ids, cwd, and every cwd alias, while normalizing fixture records with the fixture header context; literal replacements affect only the raw values being written. After existing record alignment, it recursively compares fresh and existing leaves through those normalized records: normalized-equivalent leaves retain the existing raw value, while normalized-distinct leaves retain the fresh semantic value.
+Refresh write-back uses `normalizeSessionLog` as its volatile-value authority for aligned leaves. It normalizes the original harvested records with the fresh run's ids, cwd, and every cwd alias, while normalizing fixture records with the fixture header context; literal replacements are limited to fresh-run session IDs, cwd values, and spill paths. After existing record alignment, it recursively compares fresh and existing leaves through those normalized records: normalized-equivalent leaves retain the existing raw value, while normalized-distinct leaves retain the fresh semantic value. Complete message IDs in surface or inbox carriers are excluded from this path so positional reuse and structural reuse cannot assign the same committed UUID independently.
 
 Before reuse, the complete logical-record layout must align, apart from the existing packed-chunk and inserted-title equivalences. Normalized-equivalent changed strings form a log-wide bijection: one fresh string maps to exactly one existing string and vice versa, so repeated IDs remain correlated across records. An unexplained record mismatch or conflicting mapping disables normalized string reuse for that log.
 
@@ -30,6 +30,6 @@ Object fields align by key. Array elements align only when all corresponding arr
 
 ## Consequences
 
-Record and refresh no longer rewrite an unchanged unique message UUID solely because another event changed the surrounding record layout, regardless of whether ACP, JSON-RPC, or Web owns the recording. Repeated refreshes also retain aligned fixture values that the normalizer classifies as volatile, and new volatile categories added to the normalizer automatically inherit that write-back behavior. Structural ambiguity remains conservative: unmatched records, conflicting string mappings, resized arrays, strings containing both semantic and volatile changes, and non-unique message fingerprints use fresh values rather than risk reusing misaligned data.
+Record and refresh no longer rewrite an unchanged unique message UUID solely because another event changed the surrounding record layout, regardless of whether ACP, JSON-RPC, or Web owns the recording. Repeated refreshes also retain aligned fixture values that the normalizer classifies as volatile, and new volatile categories added to the normalizer automatically inherit that write-back behavior. Structural ambiguity remains conservative: unmatched records, conflicting string mappings, resized arrays, strings containing both semantic and volatile changes, malformed messages, and any message graph with a non-unique ID or fingerprint use fresh values rather than risk reusing misaligned data.
 
-Focused unit coverage pins scenario-wide parent/child message correlation, unrelated event insertion, record write-back, new/changed/ambiguous messages, recursive object/array behavior, conflicting mappings, fresh cwd aliases, volatile strings, and fresh semantic fields. Keyless refresh coverage proves approval UUIDs, cwd aliases, spill paths, and event-read volatility leave their committed fixtures byte-identical.
+Focused unit coverage pins all authoritative surface-message shapes, durable inbox/surface correlation, scenario-wide parent/child correlation, cwd-bearing fixture-ready matching, unrelated event insertion, malformed-message isolation, both-axis graph ambiguity, single-owner write-back, recursive object/array behavior, conflicting mappings, fresh cwd aliases, volatile strings, and fresh semantic fields. Keyless refresh coverage proves approval UUIDs, cwd aliases, spill paths, and event-read volatility leave their committed fixtures byte-identical.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
index 303a4d6a4c..388b67c670 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
@@ -12,9 +12,9 @@ ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别
 
 ## 决策
 
-在录制或刷新写入会话 fixture 前，共享快照支持层会移除每条完整 surface 消息的顶层 `id` 并计算指纹，同时将所有父级/子级日志中的出现项分组。仅当一个指纹恰好对应一个本次生成的 ID 和一个现有 ID 时，才会复用现有 UUID，随后将该映射应用到每份本次生成的日志。具有相同 ID、重复出现的继承消息仍算作一个候选项；新增、发生变化、内容重复、格式错误和存在冲突的消息则保留本次生成的 ID。ACP、JSON-RPC 和 Web 录制器都会先让可写入 fixture 的日志经过同一个辅助函数，再执行写入。
+在录制或刷新写入会话 fixture 前，共享快照支持层会将可写入 fixture 的日志交给一个负责结构化处理消息 ID 的组件。该组件通过会话包的权威 surface 类型谓词识别 surface 载体，并识别 `agent/inbox/spliced` 中与这些载体关联的已排队消息副本；随后移除每条完整消息的顶层 `id` 并计算指纹，同时记录所有父级/子级日志中每条 ID 与指纹之间的关联边。仅当该 ID 与指纹在本次生成图和现有图中的度均为 1 时，才会复用现有 UUID，随后仅改写这些载体中通过验证的消息 `id` 字段。具有相同 ID、重复出现的继承消息仍算作一个候选项；新增、发生变化、内容重复、格式错误和存在冲突的消息则保留本次生成的 ID。ACP、JSON-RPC 和 Web 录制器会在擦除 header 并对 cwd 进行 token 化后执行这一步，因此消息身份取决于 fixture 中的写法，而非宿主机原始路径。
 
-刷新写回以 `normalizeSessionLog` 作为已对齐叶值的易变值判定依据。系统使用本次运行的 id、cwd 及全部 cwd 别名归一化原始收集记录，并使用 fixture 头部上下文归一化 fixture 记录；字面量替换只影响要写入的原始值。现有记录完成对齐后，系统基于这些归一化记录，递归比较本次生成记录与现有记录的叶节点：归一化后等价的叶节点保留现有原始值，归一化后不同的叶节点则保留本次生成的语义值。
+刷新写回以 `normalizeSessionLog` 作为已对齐叶值的易变值判定依据。系统使用本次运行的 id、cwd 及全部 cwd 别名归一化原始收集记录，并使用 fixture 头部上下文归一化 fixture 记录；字面量替换仅限于本次运行生成的会话 ID、cwd 值和 spill 路径。现有记录完成对齐后，系统基于这些归一化记录，递归比较本次生成记录与现有记录的叶节点：归一化后等价的叶节点保留现有原始值，归一化后不同的叶节点则保留本次生成的语义值。surface 或 inbox 载体中的完整消息 ID 不参与这一路径，以免按位置复用与结构复用各自独立分配同一个已提交 UUID。
 
 复用前必须确保完整逻辑记录布局对齐，现有的打包分片与插入标题等价情形除外。归一化后等价但发生变化的字符串在整份日志范围内形成双射：一个本次生成的字符串只映射到一个现有字符串，反向亦然，因此跨记录重复出现的 ID 仍保持关联。出现无法解释的记录不匹配或映射冲突时，该日志会停用归一化字符串复用。
 
@@ -30,6 +30,6 @@ ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别
 
 ## 后果
 
-录制和刷新不再仅仅因为另一个事件改变了周边记录布局，就改写未变化且唯一的消息 UUID，无论该录制由 ACP、JSON-RPC 还是 Web 负责。重复刷新也会保留规范化器归类为易变值的已对齐 fixture 值；以后加入规范化器的新易变值类别也会自动继承该写回行为。结构有歧义时仍采取保守策略：记录无法匹配、字符串映射冲突、数组尺寸发生变化、字符串同时包含语义变化与易变变化，或消息指纹不唯一时，均使用本次生成的值，避免冒险复用未对齐的数据。
+录制和刷新不再仅仅因为另一个事件改变了周边记录布局，就改写未变化且唯一的消息 UUID，无论该录制由 ACP、JSON-RPC 还是 Web 负责。重复刷新也会保留规范化器归类为易变值的已对齐 fixture 值；以后加入规范化器的新易变值类别也会自动继承该写回行为。结构有歧义时仍采取保守策略：记录无法匹配、字符串映射冲突、数组尺寸发生变化、字符串同时包含语义变化与易变变化、消息格式错误，或消息图中的 ID 或指纹不唯一时，均使用本次生成的值，避免冒险复用未对齐的数据。
 
-聚焦的单元测试固定了场景范围内的父级/子级消息关联、无关事件插入、录制写回、新增/发生变化/有歧义的消息、递归处理对象与数组的行为、映射冲突、本次运行的 cwd 别名、易变字符串以及本次生成的语义字段。无密钥刷新测试证明，审批 UUID、cwd 别名、spill 路径和事件读取中的易变值不会改变已提交 fixture 的任何字节。
+聚焦的单元测试固定了会话包权威谓词识别的所有 surface 消息形态、持久 inbox/surface 关联、场景范围内的父级/子级消息关联、带 cwd 的可写入 fixture 消息匹配、无关事件插入、格式错误消息隔离、消息图在 ID 与指纹两条轴上的歧义、由单一处理方负责的写回、递归处理对象与数组的行为、映射冲突、本次运行的 cwd 别名、易变字符串以及本次生成的语义字段。无密钥刷新测试证明，审批 UUID、cwd 别名、spill 路径和事件读取中的易变值不会改变已提交 fixture 的任何字节。
diff --git a/examples/jsonrpc-agent/tests/sdk.snapshot.ts b/examples/jsonrpc-agent/tests/sdk.snapshot.ts
index 1f4335402e..4a29d6eb6a 100644
--- a/examples/jsonrpc-agent/tests/sdk.snapshot.ts
+++ b/examples/jsonrpc-agent/tests/sdk.snapshot.ts
@@ -350,15 +350,18 @@ describe('TypeScript SDK snapshots over the jsonrpc runtime', () => {
           content: log.content,
         }))
         const replacements = refreshFixtureReplacements(harvested, expectedContents)
-        expectedContents = await Promise.all(ordered.map(async (log, index) => {
+        const refreshed = ordered.map((log, index) => {
           const existing = expectedContents[index]
-          const file = files[index]
-          if (existing === undefined || file === undefined) throw new Error(`no fixture for persisted log ${index}`)
-          const stable = scrubRequestHeaders(tokenizeSessionFixtureCwd(
+          if (existing === undefined) throw new Error(`no fixture for persisted log ${index}`)
+          return scrubRequestHeaders(tokenizeSessionFixtureCwd(
             stabilizeRefreshLog(log.content, existing, replacements, actualContext),
           ))
+        })
+        expectedContents = stabilizeFixtureMessageIds(refreshed, expectedContents)
+        await Promise.all(expectedContents.map(async (stable, index) => {
+          const file = files[index]
+          if (file === undefined) throw new Error(`no fixture for persisted log ${index}`)
           await writeFile(file, stable)
-          return stable
         }))
       }
 
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index bed064e909..25b54630b2 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/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/support/acp-snapshot/README.md
-README.md: 9d142dc964e60f9508b6c137525eb916cdbd969f
-README.zh.md: 2e88e7c5bb8acb0cd99a35b5fe0fbfc15d6101e3
+README.md: 0b935ef60c33fd24660d8ecf2497f5506157c724
+README.zh.md: 91be3c97bcb67ce10c61513113f683e741bc762f
diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md
index 9d142dc964..0b935ef60c 100644
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -8,8 +8,8 @@ Four layers, importable separately:
 
 - **`launchAcpTestAgent` (launcher)** — boots a source agent under tsx or a built `lib` agent under plain Node from a supplied cwd, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through startup, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. When Windows accepts forced termination but publishes its exit marker asynchronously, shutdown gives that marker a bounded grace before treating fallback refusal as a second failure. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy.
 - **`runScenario` (harness)** — drives ACP JSON-RPC stdio from a deterministic `input.json` script through the launcher, tees raw stdout for the expected-output and purity checks, and harvests every persisted raw JSONL session log (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, optional `libBinScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is outside the repo; `workspaceParent` may move the generated child cwd from the platform temp directory when that grant is itself under test. Startup failures preserve captured agent stderr in the rejected diagnostic.
-- **Normalizers** — pure functions turning captured surfaces into stable text or portable fixtures: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs and every native/JavaScript filesystem spelling of the generated cwd → tokens, longest-first; cwd-rooted separators selected as canonical `/` or host-native; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `tokenizeSessionFixtureCwd` (the generated workspace and its filesystem aliases → one canonical `{{cwd}}`, including an already-tokenized macOS `/private` alias; authored temp paths unchanged), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)), and `stabilizeFixtureMessageIds` (committed UUIDs carried into unchanged, unambiguous messages across any recorder's fixture-ready parent/child logs).
-- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario expected-output and re-persisted-log comparisons, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, a tokenized pin per header class composed with independently shared `system-prompt.expected.md` and `tool-schemas.expected.json` sidecars, and a live uniformity guard. Its fixture guards reject orphan scenario dirs, missing files, multiple pins for one class, duplicate sidecar content, noncanonical macOS-prefixed cwd tokens, unscrubbed JSONL headers, and malformed pinning headers. Before record or refresh writes fixtures, an unchanged complete message retains its committed UUID when its identity-free value resolves to exactly one fresh ID and one existing ID across the scenario's parent/child logs; new, changed, and ambiguous messages keep fresh UUIDs. Refresh evaluates fresh leaves with the harvested run's ids, cwd, and every cwd alias, then reuses normalized-equivalent leaves only when the complete logical-record layout aligns and volatile string replacements form a bijection; ambiguous logs keep fresh strings, and fresh semantic values remain authoritative. It also expands packed timing envelopes before aligning event times, so switching between packed and unpacked layouts cannot shift later records. A newly inserted `session/title` receives its preceding event's time so feature-driven insertions do not churn the remainder of a fixture. Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.
+- **Normalizers** — pure functions turning captured surfaces into stable text or portable fixtures: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs and every native/JavaScript filesystem spelling of the generated cwd → tokens, longest-first; cwd-rooted separators selected as canonical `/` or host-native; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `tokenizeSessionFixtureCwd` (the generated workspace and its filesystem aliases → one canonical `{{cwd}}`, including an already-tokenized macOS `/private` alias; authored temp paths unchanged), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)), and `stabilizeFixtureMessageIds` (committed UUIDs carried into unchanged, mutually unique messages by structurally rewriting only complete surface and durable-inbox message ID fields across any recorder's fixture-ready parent/child logs).
+- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario expected-output and re-persisted-log comparisons, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, a tokenized pin per header class composed with independently shared `system-prompt.expected.md` and `tool-schemas.expected.json` sidecars, and a live uniformity guard. Its fixture guards reject orphan scenario dirs, missing files, multiple pins for one class, duplicate sidecar content, noncanonical macOS-prefixed cwd tokens, unscrubbed JSONL headers, and malformed pinning headers. Before record or refresh writes fixtures, an unchanged complete message retains its committed UUID only when both its ID and identity-free fingerprint are unique across the scenario's fixture-ready parent/child logs; the session package's authoritative surface-type predicate selects surface carriers, correlated `agent/inbox/spliced` copies join the same mapping, and only validated `id` fields in those carriers are rewritten. New, changed, malformed, and graph-ambiguous messages keep fresh UUIDs. Refresh evaluates fresh leaves with the harvested run's ids, cwd, and every cwd alias, then reuses normalized-equivalent leaves only when the complete logical-record layout aligns and volatile string replacements form a bijection; complete message IDs in surface or inbox carriers are excluded because the later structural pass owns them, ambiguous logs keep fresh strings, and fresh semantic values remain authoritative. It also expands packed timing envelopes before aligning event times, so switching between packed and unpacked layouts cannot shift later records. A newly inserted `session/title` receives its preceding event's time so feature-driven insertions do not churn the remainder of a fixture. Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.
 
 Committed session fixtures use canonical packed rows. An in-flight branch that merges this contract runs the [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) with `pnpm run migrate:packed-session-fixtures`; its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns deletion after affected branches converge.
 
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index 2e88e7c5bb..91be3c97bc 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -8,8 +8,8 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 
 - **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动过程中公开异步 spawn 失败，对未处理权限请求快速失败，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才解析或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
 - **`runScenario`（harness）**：通过启动器从确定性 `input.json` 脚本驱动 ACP JSON-RPC stdio，将原始 stdout tee 给预期输出和纯度检查，并在优雅 stdin EOF 后收集每个持久化原始 JSONL 会话日志（父级和 subagent 子级，主级优先）。`AgentUnderTest` 提供绝对 `binScript`、可选 `libBinScript`、`configPath` 和 `tsconfigPath` 路径，因为子进程 cwd 位于仓库外。当生成子级 cwd 自身位于待测授权中时，`workspaceParent` 可以将它从平台临时目录移出。启动失败会在拒绝诊断中保留已捕获 agent stderr。
-- **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每个原生/JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，将已提交 UUID 带入未变化且无歧义的消息）。
-- **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新写入 fixture 前，如果一条未变化的完整消息去除身份后的值在场景的父级/子级日志中恰好对应一个本次生成的 ID 和一个现有 ID，它就会保留已提交的 UUID；新增、发生变化和有歧义的消息则保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用规范化后等价的叶值；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件是有序主级/子级清单；场景表不重复其数量。必须在 vitest 收集时调用。
+- **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每个原生/JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
+- **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件是有序主级/子级清单；场景表不重复其数量。必须在 vitest 收集时调用。
 
 签入仓库的会话 fixture 使用规范打包行。合并此契约的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
 
diff --git a/packages/support/acp-snapshot/package.json b/packages/support/acp-snapshot/package.json
index c231591103..b504cbe50d 100644
--- a/packages/support/acp-snapshot/package.json
+++ b/packages/support/acp-snapshot/package.json
@@ -31,10 +31,12 @@
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts
index 993aee254f..c0cfc56e24 100644
--- a/packages/support/acp-snapshot/src/suite.ts
+++ b/packages/support/acp-snapshot/src/suite.ts
@@ -20,6 +20,7 @@
 import { readFile, readdir, rm, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
+import { isSurfaceEligibleType } from '@deepseek-ai/dsh-session/surface'
 import { describe, expect, it } from 'vitest'
 import { type AgentUnderTest, type HarvestedLog, type InputScript, runScenario } from './harness.ts'
 import {
@@ -512,11 +513,11 @@ export function headerChangeCount(rawLog: string): number {
     .length
 }
 
-/** A literal string replacement used to carry an existing fixture value into fresh write-back. */
+/** A literal replacement from a fresh replay-run volatile to its existing fixture value. */
 export interface FixtureReplacement {
-  /** The fresh run's value to replace. */
+  /** The fresh replay run's volatile value. */
   from: string
-  /** The existing fixture value to keep. */
+  /** The existing fixture value retained during write-back. */
   to: string
 }
 
@@ -526,24 +527,51 @@ function parseJsonlRecords(text: string): Record<string, unknown>[] {
     .map(line => JSON.parse(line) as Record<string, unknown>)
 }
 
+/** Narrow one parsed value to the complete identified-message shape retained by fixtures. */
+function completeMessage(value: unknown): Record<string, unknown> | undefined {
+  if (
+    !isRecord(value)
+    || typeof value.id !== 'string'
+    || !UUID_RE.test(value.id)
+    || typeof value.role !== 'string'
+    || !Array.isArray(value.content)
+    || !isRecord(value.source)
+  ) return undefined
+  return value
+}
+
 /** Return the complete identified message carried by one surface event. */
-function eventMessage(record: Record<string, unknown>): Record<string, unknown> | undefined {
+function surfaceEventMessage(record: Record<string, unknown>): Record<string, unknown> | undefined {
+  const type = record.type
+  if (typeof type !== 'string' || !isSurfaceEligibleType(type)) return undefined
   const data = record.data
   if (!isRecord(data)) return undefined
-  const message = record.type === 'user/message'
-    ? data
-    : record.type === 'assistant/message' || record.type === 'tool/result' || record.type === 'steering/message'
-      ? data.message
-      : undefined
-  if (
-    !isRecord(message)
-    || typeof message.id !== 'string'
-    || !UUID_RE.test(message.id)
-    || typeof message.role !== 'string'
-    || !Array.isArray(message.content)
-    || !isRecord(message.source)
-  ) return undefined
-  return message
+  let message: unknown
+  switch (type) {
+    case 'user/message':
+      message = data
+      break
+    case 'assistant/message':
+    case 'tool/result':
+      message = data.message
+      break
+    /* v8 ignore next -- the authoritative predicate must fail loud when a new surface shape lands. */
+    default: throw new Error(`acp-snapshot: unsupported surface event type "${type}"`)
+  }
+  return completeMessage(message)
+}
+
+/** Return complete message identities structurally owned by one durable record. */
+function recordMessages(record: Record<string, unknown>): Record<string, unknown>[] {
+  const surfaceMessage = surfaceEventMessage(record)
+  if (surfaceMessage !== undefined) return [surfaceMessage]
+  if (record.type !== 'agent/inbox/spliced' || !isRecord(record.data) || !Array.isArray(record.data.inserted)) {
+    return []
+  }
+  return record.data.inserted.flatMap((value) => {
+    const message = completeMessage(value)
+    return message === undefined ? [] : [message]
+  })
 }
 
 /** Serialize parsed JSON by value rather than insertion order. */
@@ -555,42 +583,48 @@ function canonicalJson(value: unknown): string {
   return JSON.stringify(value)
 }
 
-/** Index each unambiguous identity-free message value by its sole message id. */
-function uniqueMessageIds(logs: readonly string[]): Map<string, string | undefined> {
-  const fingerprintsById = new Map<string, string | undefined>()
+/** Index identity-free message values whose ID and fingerprint are mutually unique. */
+function uniqueMessageIds(logs: readonly string[]): Map<string, string> {
+  const fingerprintsById = new Map<string, Set<string>>()
+  const idsByFingerprint = new Map<string, Set<string>>()
   for (const log of logs) {
     for (const record of parseJsonlRecords(log)) {
-      const message = eventMessage(record)
-      if (message === undefined) continue
-      const { id, ...withoutId } = message
-      const messageId = id as string
-      const fingerprint = canonicalJson(withoutId)
-      if (!fingerprintsById.has(messageId)) fingerprintsById.set(messageId, fingerprint)
-      else if (fingerprintsById.get(messageId) !== fingerprint) fingerprintsById.set(messageId, undefined)
+      for (const message of recordMessages(record)) {
+        const { id, ...withoutId } = message
+        const messageId = id as string
+        const fingerprint = canonicalJson(withoutId)
+        const fingerprints = fingerprintsById.get(messageId)
+        if (fingerprints === undefined) fingerprintsById.set(messageId, new Set([fingerprint]))
+        else fingerprints.add(fingerprint)
+        const ids = idsByFingerprint.get(fingerprint)
+        if (ids === undefined) idsByFingerprint.set(fingerprint, new Set([messageId]))
+        else ids.add(messageId)
+      }
     }
   }
 
-  const idsByFingerprint = new Map<string, string | undefined>()
-  for (const [id, fingerprint] of fingerprintsById) {
-    if (fingerprint === undefined) continue
-    if (!idsByFingerprint.has(fingerprint)) idsByFingerprint.set(fingerprint, id)
-    else idsByFingerprint.set(fingerprint, undefined)
+  const unique = new Map<string, string>()
+  for (const [id, fingerprints] of fingerprintsById) {
+    if (fingerprints.size !== 1) continue
+    const fingerprint = fingerprints.values().next().value as string
+    if (idsByFingerprint.get(fingerprint)?.size !== 1) continue
+    unique.set(fingerprint, id)
   }
-  return idsByFingerprint
+  return unique
 }
 
 /**
  * Match unchanged complete messages across a scenario's fresh and existing logs.
- * New, changed, repeated, or otherwise ambiguous messages keep their fresh ids.
+ * New, changed, duplicate-content, or otherwise ambiguous messages keep their fresh ids.
  */
-function fixtureMessageIdReplacements(logs: readonly string[], fixtures: readonly string[]): FixtureReplacement[] {
+function fixtureMessageIdReplacements(logs: readonly string[], fixtures: readonly string[]): Map<string, string> {
   const freshIds = uniqueMessageIds(logs)
   const existingIds = uniqueMessageIds(fixtures)
-  const replacements: FixtureReplacement[] = []
+  const replacements = new Map<string, string>()
   for (const [fingerprint, fresh] of freshIds) {
     const existing = existingIds.get(fingerprint)
-    if (fresh === undefined || existing === undefined || fresh === existing) continue
-    replacements.push({ from: fresh, to: existing })
+    if (existing === undefined || fresh === existing) continue
+    replacements.set(fresh, existing)
   }
   return replacements
 }
@@ -602,6 +636,22 @@ function applyFixtureReplacements(content: string, replacements: readonly Fixtur
   return stable
 }
 
+/** Rewrite only validated durable-message ID fields, leaving every other occurrence untouched. */
+function applyFixtureMessageIds(content: string, replacements: ReadonlyMap<string, string>): string {
+  return content.split('\n').map((line) => {
+    if (line.trim().length === 0) return line
+    const record = JSON.parse(line) as Record<string, unknown>
+    let changed = false
+    for (const message of recordMessages(record)) {
+      const replacement = replacements.get(message.id as string)
+      if (replacement === undefined) continue
+      message.id = replacement
+      changed = true
+    }
+    return changed ? JSON.stringify(record) : line
+  }).join('\n')
+}
+
 /**
  * Carry committed UUIDs into unchanged, unambiguous messages in fresh session fixtures.
  *
@@ -611,7 +661,7 @@ function applyFixtureReplacements(content: string, replacements: readonly Fixtur
  */
 export function stabilizeFixtureMessageIds(logs: readonly string[], fixtures: readonly string[]): string[] {
   const replacements = fixtureMessageIdReplacements(logs, fixtures)
-  return logs.map(log => applyFixtureReplacements(log, replacements))
+  return logs.map(log => applyFixtureMessageIds(log, replacements))
 }
 
 /** One packed row's member times, or `undefined` for an ordinary record. */
@@ -659,15 +709,15 @@ export function unknownToolCallIds(rawLog: string): string[] {
 }
 
 /**
- * Build refresh write-back replacements: scenario-wide unchanged message ids,
- * plus per-log session ids, cwd values, and spill paths.
+ * Build refresh write-back replacements for per-log session ids, cwd values,
+ * and spill paths. Durable message ids have a later structural owner.
  *
  * @param logs The freshly harvested logs, in fixture order.
  * @param fixtures The existing fixture contents, in matching order.
  * @returns Literal replacements from fresh values to the fixture's existing values.
  */
 export function refreshFixtureReplacements(logs: HarvestedLog[], fixtures: string[]): FixtureReplacement[] {
-  const replacements = fixtureMessageIdReplacements(logs.map(log => log.content), fixtures)
+  const replacements: FixtureReplacement[] = []
   for (let i = 0; i < logs.length; i++) {
     const fresh = parseJsonlRecords((logs[i] as HarvestedLog).content)[0]
     const existing = parseJsonlRecords(fixtures[i] ?? '')[0]
@@ -818,6 +868,7 @@ function collectNormalizedStringMappings(
   existing: unknown,
   normalizedFresh: unknown,
   normalizedExisting: unknown,
+  excludedStrings: ReadonlySet<string>,
   forward: Map<string, string>,
   reverse: Map<string, string>,
 ): boolean {
@@ -837,6 +888,7 @@ function collectNormalizedStringMappings(
       existing[index],
       normalizedFresh[index],
       normalizedExisting[index],
+      excludedStrings,
       forward,
       reverse,
     ))
@@ -856,6 +908,7 @@ function collectNormalizedStringMappings(
         existing[key],
         normalizedFresh[key],
         normalizedExisting[key],
+        excludedStrings,
         forward,
         reverse,
       ))
@@ -866,6 +919,8 @@ function collectNormalizedStringMappings(
     || typeof normalizedFresh !== 'string'
     || normalizedFresh !== normalizedExisting
     || fresh === existing
+    || excludedStrings.has(fresh)
+    || excludedStrings.has(existing)
   ) return true
   const freshKey = JSON.stringify([normalizedFresh, fresh])
   const existingKey = JSON.stringify([normalizedFresh, existing])
@@ -891,6 +946,10 @@ function normalizedStringMappings(
   freshContext: NormalizeContext,
   existingContext: NormalizeContext,
 ): Map<string, string> | undefined {
+  const excludedStrings = new Set<string>()
+  for (const record of [...freshRecords, ...existingRecords]) {
+    for (const message of recordMessages(record)) excludedStrings.add(message.id as string)
+  }
   const forward = new Map<string, string>()
   const reverse = new Map<string, string>()
   let existingIndex = 0
@@ -912,6 +971,7 @@ function normalizedStringMappings(
         existingRecord,
         normalizedRefreshRecord(freshRecords[recordIndex] as Record<string, unknown>, freshContext),
         normalizedRefreshRecord(existingRecord, existingContext),
+        excludedStrings,
         forward,
         reverse,
       )) return undefined
@@ -924,11 +984,13 @@ function normalizedStringMappings(
 /**
  * Rewrite a fresh replay-produced log so repeated refreshes do not churn
  * volatile fixture fields. Meaningful event payloads come from `fresh`; the
- * existing fixture lends normalized-equivalent values, including ids, paths,
+ * existing fixture lends normalized-equivalent values, including non-message ids, paths,
  * creation/event times, spill locators, and hook durations, only when the
  * complete record layout aligns and volatile strings form a consistent
- * bijection. Ambiguous layouts or mappings keep fresh strings. Packed timing
- * envelopes expand for alignment, so packing does not shift later records;
+ * bijection. Complete durable-message ids are excluded because the later
+ * fixture-ready structural pass owns them. Ambiguous layouts or mappings
+ * keep fresh strings. Packed timing envelopes expand for alignment, so
+ * packing does not shift later records;
  * fresh semantic values and fragment arrays remain authoritative.
  *
  * @param fresh The newly harvested session JSONL.
@@ -1158,17 +1220,15 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
           const refreshReplacements = REFRESHING
             ? refreshFixtureReplacements(result.sessionLogs, existingFixtures)
             : []
-          const outputFixtures = REFRESHING
+          const freshFixtures = REFRESHING
             ? result.sessionLogs.map((log, index) => scrub(portableFixture(stabilizeRefreshLog(
               log.content,
               existingFixtures[index] as string,
               refreshReplacements,
               ctx,
             ))))
-            : stabilizeFixtureMessageIds(
-              result.sessionLogs.map(log => scrub(portableFixture(log.content))),
-              existingFixtures,
-            )
+            : result.sessionLogs.map(log => scrub(portableFixture(log.content)))
+          const outputFixtures = stabilizeFixtureMessageIds(freshFixtures, existingFixtures)
           await Promise.all(outputFixtures.map((fixture, index) =>
             writeFile(join(dir, outputFixtureFiles[index] as string), fixture)))
           if (RECORDING) {
diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts
index a915590b5d..3cfd1c0f0a 100644
--- a/packages/support/acp-snapshot/tests/suite.spec.ts
+++ b/packages/support/acp-snapshot/tests/suite.spec.ts
@@ -7,6 +7,7 @@ import { afterAll, describe, expect, it } from 'vitest'
 import {
   defineAcpSnapshotSuite,
   stabilizeFixtureMessageIds,
+  tokenizeSessionFixtureCwd,
   type HarvestedLog,
   type Scenario,
 } from '../src/index.ts'
@@ -679,6 +680,109 @@ describe('stabilizeFixtureMessageIds', () => {
     }
   })
 
+  it('rewrites only complete messages carried by surface events or durable inbox splices', () => {
+    const ids = {
+      freshUser: '11111111-1111-4111-8111-111111111111',
+      oldUser: '22222222-2222-4222-8222-222222222222',
+      freshAssistant: '33333333-3333-4333-8333-333333333333',
+      oldAssistant: '44444444-4444-4444-8444-444444444444',
+      freshTool: '55555555-5555-4555-8555-555555555555',
+      oldTool: '66666666-6666-4666-8666-666666666666',
+      oldMalformed: '77777777-7777-4777-8777-777777777777',
+    } as const
+    const message = (id: string, role: string, text: string): Record<string, unknown> => ({
+      id,
+      role,
+      content: [{ type: 'text', text }],
+      source: { kind: role === 'user' ? 'user' : 'model' },
+    })
+    const log = (userId: string, assistantId: string, toolId: string, malformedId: string): string => [
+      JSON.stringify({ type: 'session', id: 'same', cwd: '{{cwd}}' }),
+      JSON.stringify({
+        type: 'agent/inbox/spliced',
+        data: {
+          inserted: [
+            message(userId, 'user', 'user'),
+            { ...message(userId, 'user', 'malformed inbox'), source: null },
+          ],
+        },
+      }),
+      JSON.stringify({ type: 'user/message', data: message(userId, 'user', 'user') }),
+      JSON.stringify({ type: 'assistant/message', data: { message: message(assistantId, 'assistant', 'assistant') } }),
+      JSON.stringify({ type: 'tool/result', data: { message: message(toolId, 'tool', 'tool') } }),
+      JSON.stringify({ type: 'turn/start', data: { id: userId } }),
+      JSON.stringify({ type: 'steering/message', data: message(userId, 'user', 'obsolete') }),
+      JSON.stringify({ type: 'user/message', data: { ...message(userId, 'user', 'malformed'), source: null } }),
+      JSON.stringify({ type: 'user/message', data: message(malformedId, 'user', 'non-UUID') }),
+      JSON.stringify({ type: 'assistant/message', data: null }),
+      JSON.stringify({ type: 42, data: message(userId, 'user', 'non-string type') }),
+      '',
+    ].join('\n')
+
+    const stable = stabilizeFixtureMessageIds(
+      [log(ids.freshUser, ids.freshAssistant, ids.freshTool, 'not-a-uuid')],
+      [log(ids.oldUser, ids.oldAssistant, ids.oldTool, ids.oldMalformed)],
+    )[0] as string
+    const records = stable.trim().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
+
+    const inserted = ((records[1]?.data as { inserted: Array<{ id: string }> }).inserted)
+    expect(inserted[0]?.id).toBe(ids.oldUser)
+    expect(inserted[1]?.id).toBe(ids.freshUser)
+    expect((records[2]?.data as { id: string }).id).toBe(ids.oldUser)
+    expect((records[3]?.data as { message: { id: string } }).message.id).toBe(ids.oldAssistant)
+    expect((records[4]?.data as { message: { id: string } }).message.id).toBe(ids.oldTool)
+    expect((records[5]?.data as { id: string }).id).toBe(ids.freshUser)
+    expect((records[6]?.data as { id: string }).id).toBe(ids.freshUser)
+    expect((records[7]?.data as { id: string }).id).toBe(ids.freshUser)
+    expect((records[8]?.data as { id: string }).id).toBe('not-a-uuid')
+  })
+
+  it('matches cwd-bearing messages only after the fresh log reaches fixture-ready form', () => {
+    const freshId = '11111111-1111-4111-8111-111111111111'
+    const existingId = '22222222-2222-4222-8222-222222222222'
+    const freshCwd = '/tmp/acp-snapshot-fresh-cwd'
+    const message = (id: string, path: string): Record<string, unknown> => ({
+      type: 'user/message',
+      data: {
+        id,
+        role: 'user',
+        content: [{ type: 'text', text: `read ${path}/input.txt` }],
+        source: { kind: 'user' },
+      },
+    })
+    const fresh = tokenizeSessionFixtureCwd([
+      JSON.stringify({ type: 'session', id: 'fresh', cwd: freshCwd }),
+      JSON.stringify(message(freshId, freshCwd)),
+      '',
+    ].join('\n'))
+    const existing = [
+      JSON.stringify({ type: 'session', id: 'old', cwd: '{{cwd}}' }),
+      JSON.stringify(message(existingId, '{{cwd}}')),
+      '',
+    ].join('\n')
+
+    expect(stabilizeFixtureMessageIds([fresh], [existing])[0]).toContain(`"id":"${existingId}"`)
+  })
+
+  it('rejects a fingerprint connected to an id that also identifies different content', () => {
+    const freshId = '11111111-1111-4111-8111-111111111111'
+    const conflictingId = '22222222-2222-4222-8222-222222222222'
+    const competingId = '33333333-3333-4333-8333-333333333333'
+    const message = (id: string, text: string): string => JSON.stringify({
+      type: 'user/message',
+      data: { id, role: 'user', content: [{ type: 'text', text }], source: { kind: 'user' } },
+    })
+    const fresh = `${message(freshId, 'shared')}\n`
+    const existing = [
+      message(conflictingId, 'shared'),
+      message(conflictingId, 'different'),
+      message(competingId, 'shared'),
+      '',
+    ].join('\n')
+
+    expect(stabilizeFixtureMessageIds([fresh], [existing])).toEqual([fresh])
+  })
+
   it('leaves fresh fixtures unchanged when no committed counterpart exists', () => {
     const fresh = '{"type":"session","id":"new"}\n'
     expect(stabilizeFixtureMessageIds([fresh], [''])).toEqual([fresh])
@@ -726,76 +830,28 @@ describe('refreshFixtureReplacements', () => {
     ])
   })
 
-  it('maps one inherited message id across parent and child logs', () => {
+  it('leaves complete message ids out of the literal refresh replacement list', () => {
     const freshMessageId = '11111111-1111-4111-8111-111111111111'
     const existingMessageId = '22222222-2222-4222-8222-222222222222'
-    const content = [{ type: 'text', text: 'inherited' }]
     const log = (sessionId: string, messageId: string): string => [
       JSON.stringify({ type: 'session', id: sessionId, cwd: '/same' }),
       JSON.stringify({
         type: 'user/message',
-        data: { role: 'user', content, source: { kind: 'user' }, id: messageId },
+        data: {
+          id: messageId,
+          role: 'user',
+          content: [{ type: 'text', text: 'same' }],
+          source: { kind: 'user' },
+        },
       }),
       '',
     ].join('\n')
-    const harvested = (content: string): HarvestedLog => ({ id: 'diagnostic', createdAt: 1, content })
-
     const replacements = refreshFixtureReplacements(
-      [harvested(log('fresh-parent', freshMessageId)), harvested(log('fresh-child', freshMessageId))],
-      [log('old-parent', existingMessageId), log('old-child', existingMessageId)],
+      [{ id: 'diagnostic', createdAt: 1, content: log('fresh', freshMessageId) }],
+      [log('old', existingMessageId)],
     )
 
-    expect(replacements.filter(replacement => replacement.from === freshMessageId)).toEqual([
-      { from: freshMessageId, to: existingMessageId },
-    ])
-  })
-
-  it('keeps fresh ids for new, changed, and ambiguous messages', () => {
-    const ids = {
-      new: '11111111-1111-4111-8111-111111111111',
-      changed: '22222222-2222-4222-8222-222222222222',
-      ambiguousA: '33333333-3333-4333-8333-333333333333',
-      ambiguousB: '44444444-4444-4444-8444-444444444444',
-      oldChanged: '55555555-5555-4555-8555-555555555555',
-      oldAmbiguous: '66666666-6666-4666-8666-666666666666',
-      stable: '77777777-7777-4777-8777-777777777777',
-    } as const
-    const message = (id: string, text: string): Record<string, unknown> => ({
-      type: 'user/message',
-      data: { role: 'user', content: [{ type: 'text', text }], source: { kind: 'user' }, id },
-    })
-    const log = (messages: Record<string, unknown>[]): string => [
-      JSON.stringify({ type: 'session', id: 'same', cwd: '/same' }),
-      ...messages.map(record => JSON.stringify(record)),
-      '',
-    ].join('\n')
-    const fresh = log([
-      message(ids.new, 'new'),
-      message(ids.changed, 'changed'),
-      message(ids.changed, 'changed again'),
-      message(ids.ambiguousA, 'duplicate'),
-      message(ids.ambiguousB, 'duplicate'),
-      message(ids.stable, 'stable'),
-    ])
-    const existing = log([
-      message(ids.oldChanged, 'before'),
-      message(ids.oldAmbiguous, 'duplicate'),
-      message(ids.stable, 'stable'),
-    ])
-
-    const replacements = refreshFixtureReplacements(
-      [{ id: 'diagnostic', createdAt: 1, content: fresh }],
-      [existing],
-    )
-
-    const replacedIds = replacements.map(replacement => replacement.from)
-    for (const id of [
-      ids.new,
-      ids.changed,
-      ids.ambiguousA,
-      ids.ambiguousB,
-      ids.stable,
-    ]) expect(replacedIds).not.toContain(id)
+    expect(replacements).toEqual([{ from: 'fresh', to: 'old' }])
   })
 })
 
@@ -936,13 +992,38 @@ describe('stabilizeRefreshLog', () => {
       [{ id: 'diagnostic', createdAt: 1, content: fresh }],
       [existing],
     )
-    const output = stabilize(fresh, existing, replacements).trim().split('\n')
+    const refreshed = stabilize(fresh, existing, replacements)
+    const intermediate = refreshed.trim().split('\n')
+      .map(line => JSON.parse(line) as Record<string, unknown>)
+    expect((intermediate[1]?.data as { id: string }).id).toBe(freshUserId)
+    expect(((intermediate[3]?.data as { message: { id: string } }).message).id).toBe(freshAssistantId)
+
+    const output = (stabilizeFixtureMessageIds([refreshed], [existing])[0] as string).trim().split('\n')
       .map(line => JSON.parse(line) as Record<string, unknown>)
 
     expect((output[1]?.data as { id: string }).id).toBe(existingUserId)
     expect(((output[3]?.data as { message: { id: string } }).message).id).toBe(existingAssistantId)
   })
 
+  it('leaves an aligned complete message id to the fixture-ready structural pass', () => {
+    const freshId = '11111111-1111-4111-8111-111111111111'
+    const existingId = '22222222-2222-4222-8222-222222222222'
+    const log = (id: string): string => [
+      JSON.stringify({ type: 'session', id: 'same', createdAt: 1, cwd: '/same' }),
+      JSON.stringify({
+        type: 'user/message',
+        data: { id, role: 'user', content: [{ type: 'text', text: 'same' }], source: { kind: 'user' } },
+      }),
+      '',
+    ].join('\n')
+    const fresh = log(freshId)
+    const existing = log(existingId)
+    const refreshed = stabilize(fresh, existing)
+
+    expect(refreshed).toContain(`"id":"${freshId}"`)
+    expect(stabilizeFixtureMessageIds([refreshed], [existing])[0]).toContain(`"id":"${existingId}"`)
+  })
+
   it('keeps volatile fixture fields while preserving fresh meaningful payloads', () => {
     const fresh = [
       '{"type":"session","id":"new-child","createdAt":200,"cwd":"/new","parentSession":"new-parent","seedLength":1}',
diff --git a/packages/support/acp-snapshot/tsconfig.json b/packages/support/acp-snapshot/tsconfig.json
index 893282ce51..9d85ccaf1f 100644
--- a/packages/support/acp-snapshot/tsconfig.json
+++ b/packages/support/acp-snapshot/tsconfig.json
@@ -13,6 +13,9 @@
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../core/session"
     }
   ]
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 078f775ecf..757da9b662 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -5907,6 +5907,9 @@ importers:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../invariants
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis

From de93253b148c737355f0d700843211b5916ec3fd Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 02:18:40 +0800
Subject: [PATCH 193/516] docs: refresh module graph

---
 docs/module-graph.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index d963273363..bd9bcbf070 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -300,7 +300,6 @@ flowchart TD
   pkg_timeout --> pkg_invariants
   pkg_scope --> pkg_invariants
   pkg_skill --> pkg_invariants
-  pkg_acp_snapshot --> pkg_invariants
   pkg_llm_mock_server --> pkg_invariants
   pkg_loader_smoke --> pkg_invariants
   pkg_base --> pkg_invariants
@@ -422,6 +421,8 @@ flowchart TD
   pkg_session_persistence --> pkg_brand
   pkg_session_persistence --> pkg_invariants
   pkg_session_persistence --> pkg_session
+  pkg_acp_snapshot --> pkg_invariants
+  pkg_acp_snapshot --> pkg_session
   pkg_app_boot --> pkg_environment
   pkg_app_boot --> pkg_invariants
   pkg_app_boot --> pkg_paths
@@ -1168,7 +1169,6 @@ flowchart TD
 | [`timeout`](../packages/util/timeout) | `util` | [`invariants`](../packages/support/invariants) |
 | [`scope`](../packages/core/scope) | `core` | [`invariants`](../packages/support/invariants) |
 | [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/support/invariants) |
-| [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | [`invariants`](../packages/support/invariants) |
 | [`llm-mock-server`](../packages/support/llm-mock-server) | `support` | [`invariants`](../packages/support/invariants) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`invariants`](../packages/support/invariants) |
 | [`base`](../packages/bundle/base) | `bundle` | [`invariants`](../packages/support/invariants) |
@@ -1220,6 +1220,7 @@ flowchart TD
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |

From 9c3d5725a5735f72d1e6dbbb3d22c7de5e17d758 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 03:29:12 +0800
Subject: [PATCH 194/516] build: order Host and Client compilation faces

---
 package.json                                  |   7 +-
 packages/api/remotes/tsconfig.client.json     |  22 ++++
 packages/api/remotes/tsconfig.host.json       |  36 ++++++
 packages/api/remotes/tsconfig.json            |  37 +-----
 packages/api/remotes/tsdown.config.ts         |   6 +-
 packages/client/runtime/package.json          |   3 -
 packages/client/runtime/src/client/index.ts   |   5 +-
 packages/client/runtime/tsconfig.json         |   3 -
 packages/client/schema-form/tsdown.config.ts  |   6 +
 packages/client/test-runtime/tsdown.config.ts |   6 +
 packages/client/tsdown.client.ts              | 109 ++++++++++++++++--
 packages/client/ui-goal/tsconfig.json         |   2 +-
 .../client/ui-primitives/tsdown.config.ts     |   6 +-
 packages/client/ui-slots/tsdown.config.ts     |   6 +
 packages/client/ui-theme/tsdown.config.ts     |  12 +-
 packages/client/web-react/tsdown.config.ts    |   4 +-
 packages/client/web/tsdown.config.ts          |   6 +-
 packages/host/apiproxy/tsconfig.json          |   2 +-
 .../directory-picker-native/tsdown.config.ts  |  29 ++---
 packages/typert/generator/src/analyzer.ts     |  17 ++-
 .../typert/generator/tests/type-model.spec.ts |  82 +++++++++++++
 pnpm-lock.yaml                                |   3 -
 scripts/client-bundle-css.spec.ts             |   9 +-
 scripts/client-bundle-purity.spec.ts          |  42 +++++--
 scripts/doc-typecheck.ts                      |  29 ++---
 scripts/package-invariants.spec.ts            |  14 +++
 scripts/package-invariants.ts                 |  30 ++++-
 scripts/wine-windows-gates.sh                 |  16 ++-
 tsconfig.client.json                          |   2 +-
 tsconfig.host.json                            |   1 +
 tsdown.config.ts                              |  52 ++++-----
 tsdown.typert-host.config.ts                  |  20 ----
 32 files changed, 440 insertions(+), 184 deletions(-)
 create mode 100644 packages/api/remotes/tsconfig.client.json
 create mode 100644 packages/api/remotes/tsconfig.host.json
 create mode 100644 packages/client/schema-form/tsdown.config.ts
 create mode 100644 packages/client/test-runtime/tsdown.config.ts
 create mode 100644 packages/client/ui-slots/tsdown.config.ts
 delete mode 100644 tsdown.typert-host.config.ts

diff --git a/package.json b/package.json
index b1ad6853fc..def6e5bdcb 100644
--- a/package.json
+++ b/package.json
@@ -16,13 +16,12 @@
   "scripts": {
     "build": "npm run build:lib && npm run build:web",
     "build:lib": "npm run build:lib:host && npm run build:lib:client",
-    "build:lib:host": "npm run build:lib:contracts && tsc -b tsconfig.host.json",
-    "build:lib:contracts": "tsc -b packages/typert/generator && tsdown --config tsdown.typert-host.config.ts",
-    "build:lib:client": "tsc -b tsconfig.client.json && tsdown",
+    "build:lib:host": "tsc -b tsconfig.host.json && tsdown --env.DSH_BUILD_FACE host",
+    "build:lib:client": "tsc -b tsconfig.client.json && tsdown --env.DSH_BUILD_FACE client",
     "build:web": "pnpm --filter @deepseek-ai/dsh-frontend run build",
     "clean": "tsx scripts/clean.ts",
     "change-scope": "tsx scripts/change-scope.ts",
-    "typecheck": "npm run build:lib:contracts && tsc -b",
+    "typecheck": "npm run build:lib:host && tsc -b tsconfig.client.json",
     "lint": "tsx scripts/run-oxlint.ts .",
     "lint:fix": "eslint --config eslint.format.config.mjs --fix . && tsx scripts/run-oxlint.ts . --fix",
     "duplication": "jscpd --config .jscpd.json packages scripts",
diff --git a/packages/api/remotes/tsconfig.client.json b/packages/api/remotes/tsconfig.client.json
new file mode 100644
index 0000000000..bc26c0b13f
--- /dev/null
+++ b/packages/api/remotes/tsconfig.client.json
@@ -0,0 +1,22 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo"
+  },
+  "files": [
+    "src/client/index.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../goal/goal"
+    },
+    {
+      "path": "../../typert/type-meta"
+    }
+  ]
+}
diff --git a/packages/api/remotes/tsconfig.host.json b/packages/api/remotes/tsconfig.host.json
new file mode 100644
index 0000000000..1d4c35a9e2
--- /dev/null
+++ b/packages/api/remotes/tsconfig.host.json
@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo"
+  },
+  "files": [
+    "src/agent-lookup.ts",
+    "src/index.ts",
+    "src/invariant.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../session-persistence/session-persistence"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../typert/registry"
+    },
+    {
+      "path": "../../typert/type-meta"
+    }
+  ]
+}
diff --git a/packages/api/remotes/tsconfig.json b/packages/api/remotes/tsconfig.json
index 148804dc0f..2eca820546 100644
--- a/packages/api/remotes/tsconfig.json
+++ b/packages/api/remotes/tsconfig.json
@@ -1,42 +1,11 @@
 {
-  "extends": "../../../tsconfig.base.client.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": [
-    "src"
-  ],
+  "files": [],
   "references": [
     {
-      "path": "../../../vendor/cordis"
+      "path": "./tsconfig.host.json"
     },
     {
-      "path": "../../core/agent"
-    },
-    {
-      "path": "../../core/session"
-    },
-    {
-      "path": "../../session-persistence/session-persistence"
-    },
-    {
-      "path": "../../typert/type-meta"
-    },
-    {
-      "path": "../../typert/registry"
-    },
-    {
-      "path": "../../ui/commands"
-    },
-    {
-      "path": "../../goal/goal"
-    },
-    {
-      "path": "../../session-title/session-title"
-    },
-    {
-      "path": "../../support/invariants"
+      "path": "./tsconfig.client.json"
     }
   ]
 }
diff --git a/packages/api/remotes/tsdown.config.ts b/packages/api/remotes/tsdown.config.ts
index 287b2c7975..3c72df8718 100644
--- a/packages/api/remotes/tsdown.config.ts
+++ b/packages/api/remotes/tsdown.config.ts
@@ -1,3 +1,7 @@
 import { clientBundle } from '../../client/tsdown.client.ts'
 
-export default clientBundle('@deepseek-ai/dsh-api-remotes', ['lib/types/index.js', 'lib/types/invariant.js'])
+export default clientBundle(
+  '@deepseek-ai/dsh-api-remotes',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+  { hostPhase: true },
+)
diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
index 711510b705..3d97e70de5 100644
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -25,7 +25,6 @@
   "dshClient": {
     "inject": [
       "@deepseek-ai/dsh-client-connection",
-      "@deepseek-ai/dsh-api-remotes",
       "@deepseek-ai/dsh-typert-registry"
     ],
     "platform": "web",
@@ -49,14 +48,12 @@
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-api-remotes": "^0.0.1",
     "@deepseek-ai/dsh-type-meta": "^0.0.1",
     "@deepseek-ai/dsh-typert-registry": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-api-remotes": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
     "@deepseek-ai/dsh-type-meta": "workspace:^",
     "@deepseek-ai/dsh-typert-registry": "workspace:^",
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index 5a1677df96..e4f8e57b04 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -1,7 +1,6 @@
 /** Browser runtime services for slots, sessions, workspaces, and connection-stream delivery. */
 import type { Context } from 'cordis'
 import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
-import type {} from '@deepseek-ai/dsh-api-remotes/client'
 import type { TypeRTContext } from '@deepseek-ai/dsh-type-meta'
 import type { MaybeSnapshotSelectorHook, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from './slots.ts'
@@ -179,8 +178,8 @@ declare module 'cordis' {
   }
 }
 
-/** Required services: the Remote root, wire handle, and Client TypeRT registry. */
-export const inject = ['remote', 'connection', 'typert']
+/** Required services: the wire handle and Client TypeRT registry. */
+export const inject = ['connection', 'typert']
 
 /** Mounts the browser runtime services and connection stream.
  * @param ctx - Client Cordis context.
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index efbf7c26d7..f93546e855 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -20,9 +20,6 @@
     {
       "path": "../connection"
     },
-    {
-      "path": "../../api/remotes"
-    },
     {
       "path": "../../host/apiproxy"
     },
diff --git a/packages/client/schema-form/tsdown.config.ts b/packages/client/schema-form/tsdown.config.ts
new file mode 100644
index 0000000000..b03542c74e
--- /dev/null
+++ b/packages/client/schema-form/tsdown.config.ts
@@ -0,0 +1,6 @@
+import { clientLibrary } from '../tsdown.client.ts'
+
+export default clientLibrary(
+  '@deepseek-ai/dsh-client-schema-form',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+)
diff --git a/packages/client/test-runtime/tsdown.config.ts b/packages/client/test-runtime/tsdown.config.ts
new file mode 100644
index 0000000000..e2cb484ffb
--- /dev/null
+++ b/packages/client/test-runtime/tsdown.config.ts
@@ -0,0 +1,6 @@
+import { clientLibrary } from '../tsdown.client.ts'
+
+export default clientLibrary(
+  '@deepseek-ai/dsh-client-test-runtime',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+)
diff --git a/packages/client/tsdown.client.ts b/packages/client/tsdown.client.ts
index 74facbd69b..f2b7b7a3e6 100644
--- a/packages/client/tsdown.client.ts
+++ b/packages/client/tsdown.client.ts
@@ -9,6 +9,7 @@
  * The virtual loader registers each real stylesheet as a watch dependency.
  */
 import { readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
 import { basename, dirname, relative, resolve as resolvePath, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { UserConfig } from 'tsdown'
@@ -34,6 +35,12 @@ export const INLINE_SAFE = /^@deepseek-ai\/dsh-(host-apiproxy|session|llm|tools|
 /** Generated descriptor/codec contribution with no shared runtime identity. */
 const GENERATED_REMOTE = /^@deepseek-ai\/dsh-[a-z0-9]+(?:-[a-z0-9]+)*\/remote$/
 
+/**
+ * Workspace mode replaces an empty config array with the root defaults. A
+ * falsey entry instead removes this package before entry resolution.
+ */
+const SKIP_WORKSPACE_BUILD: UserConfig = { entry: '' }
+
 /**
  * Documented TEMPORARY exemption, not a platform module (hence not in
  * platform.ts): the snapshot-store engine (createSnapshotStore/defineStore/
@@ -61,19 +68,83 @@ function browserSourcePath(source: string, sourcemapPath: string): string {
 
 /**
  * Build the tsdown config for one UI plugin package: the node-half lib build
- * plus the browser client bundle. A package-level tsdown.config.ts REPLACES
- * the root workspace shape, so the lib half must be restated here — dropping
- * it leaves the package without lib/index.js and the host Loader cannot
- * import its node half.
+ * plus the browser client bundle. Client packages emit both halves during the
+ * Client pass by default; packages needed for Host reflection may opt into the
+ * earlier Host pass. A package-level tsdown.config.ts REPLACES the root
+ * workspace shape, so the lib half must be restated here — dropping it leaves
+ * the package without lib/index.js and the host Loader cannot import its node
+ * half.
  * @param id - plugin id (package name), stamped into the __ModuleLoader__.load
  * handoff and onto the injected style tags.
  * @param libEntry - node-half entries, spelled at the call site so the
  * package-invariants gate can see `lib/types/invariant.js` in each package's
  * own tsdown.config.ts (a preset-side glob hides it from the mechanical check).
- * @returns tsdown user configs emitting lib/*.js and lib/client.js.
+ * @param options - phase placement, lib overrides, and companion Node configs.
+ * @returns ENV-selected tsdown config for the current build face.
  */
-export function clientBundle(id: string, libEntry: readonly string[]): [UserConfig, UserConfig] {
-  return [{
+export function clientBundle(
+  id: string,
+  libEntry: readonly string[],
+  options: ClientBundleOptions = {},
+): BuildFaceConfig {
+  const lib = clientLibraryConfig(id, libEntry, options.lib)
+  return ({ env }) => {
+    const face = buildFace(env?.DSH_BUILD_FACE)
+    const client = clientConfig(id, face === undefined
+      ? 'src/client/index.ts'
+      : 'lib/types/client/index.js')
+    const host = [lib, ...(options.host ?? [])]
+    if (face === 'host') return options.hostPhase === true ? host : [SKIP_WORKSPACE_BUILD]
+    if (face === 'client') return options.hostPhase === true ? [client] : [...host, client]
+    return [...host, client]
+  }
+}
+
+/**
+ * Build a Client-only Node library during the Client pass.
+ * @param id - Package name used in tsdown diagnostics.
+ * @param libEntry - Emitted JavaScript entries consumed from `lib/types`.
+ * @returns ENV-selected tsdown config for the Client build face.
+ */
+export function clientLibrary(id: string, libEntry: readonly string[]): BuildFaceConfig {
+  const lib = clientLibraryConfig(id, libEntry)
+  return clientOnly([lib])
+}
+
+/**
+ * Select arbitrary package-local configs only during the Client pass.
+ * @param configs - Node-side configs emitted after Client tsc.
+ * @returns ENV-selected tsdown config for the Client build face.
+ */
+export function clientOnly(configs: readonly UserConfig[]): BuildFaceConfig {
+  return ({ env }) => buildFace(env?.DSH_BUILD_FACE) === 'host'
+    ? [SKIP_WORKSPACE_BUILD]
+    : [...configs]
+}
+
+interface ClientBundleOptions {
+  /** Emit the Node-side artifacts during the Host pass instead of the Client pass. */
+  readonly hostPhase?: boolean
+  readonly host?: readonly UserConfig[]
+  readonly lib?: UserConfig
+}
+
+type BuildFace = 'host' | 'client' | undefined
+
+type BuildFaceConfig = (inlineConfig: Pick<UserConfig, 'env'>) => UserConfig[]
+
+function buildFace(value: unknown): BuildFace {
+  if (value === undefined || value === 'host' || value === 'client') return value
+  throw new Error(`tsdown: --env.DSH_BUILD_FACE must be host or client, received ${String(value)}`)
+}
+
+function clientLibraryConfig(
+  id: string,
+  libEntry: readonly string[],
+  overrides: UserConfig = {},
+): UserConfig {
+  return {
+    name: id,
     entry: [...libEntry],
     outDir: 'lib',
     format: ['esm'],
@@ -82,8 +153,14 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
     fixedExtension: false,
     dts: false,
     clean: false,
-  }, {
-    entry: { client: 'src/client/index.ts' },
+    ...overrides,
+  }
+}
+
+function clientConfig(id: string, entry: string): UserConfig {
+  return {
+    name: `${id}/client`,
+    entry: { client: entry },
     // Browser bundle lands next to the node half (single lib/ artifact dir;
     // the entryFileNames pin keeps it exactly lib/client.js). clean must stay
     // off — a default clean would wipe the node-half output emitted above.
@@ -139,7 +216,7 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
       name: 'dsh-css-modules-inline',
       resolveId(source: string, importer: string | undefined) {
         if (!source.endsWith('.module.css')) return null
-        const abs = importer !== undefined ? resolvePath(dirname(importer), source) : source
+        const abs = importer !== undefined ? sourceAssetPath(source, importer) : source
         return CSS_VIRTUAL_PREFIX + abs + CSS_VIRTUAL_SUFFIX
       },
       async load(virtualId: string) {
@@ -182,5 +259,15 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
       footer: `return module.exports; } });`,
       intro: 'var module = { exports: {} }; var exports = module.exports;',
     },
-  }]
+  }
+}
+
+/** Resolve an emitted JS asset import against its source-tree counterpart. */
+function sourceAssetPath(source: string, importer: string): string {
+  const emitted = resolvePath(dirname(importer), source)
+  if (existsSync(emitted)) return emitted
+  const marker = `${sep}lib${sep}types${sep}`
+  const boundary = emitted.indexOf(marker)
+  if (boundary < 0) return emitted
+  return resolvePath(emitted.slice(0, boundary), 'src', emitted.slice(boundary + marker.length))
 }
diff --git a/packages/client/ui-goal/tsconfig.json b/packages/client/ui-goal/tsconfig.json
index 263dfceb26..1c89771abf 100644
--- a/packages/client/ui-goal/tsconfig.json
+++ b/packages/client/ui-goal/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../locale"
     },
     {
-      "path": "../../api/remotes"
+      "path": "../../api/remotes/tsconfig.client.json"
     },
     {
       "path": "../runtime"
diff --git a/packages/client/ui-primitives/tsdown.config.ts b/packages/client/ui-primitives/tsdown.config.ts
index 1532f5e5f6..cbabf4f2a1 100644
--- a/packages/client/ui-primitives/tsdown.config.ts
+++ b/packages/client/ui-primitives/tsdown.config.ts
@@ -1,4 +1,4 @@
-import { defineConfig } from 'tsdown'
+import { clientOnly } from '../tsdown.client.ts'
 
 /**
  * ui-primitives is browser-only, but its lib bundle IS imported under plain
@@ -8,7 +8,7 @@ import { defineConfig } from 'tsdown'
  * (loader module table / vite source paths), which compile src directly and
  * never read lib.
  */
-export default defineConfig({
+export default clientOnly([{
   entry: ['lib/types/index.js', 'lib/types/invariant.js'],
   outDir: 'lib',
   format: ['esm'],
@@ -28,4 +28,4 @@ export default defineConfig({
       return 'export default {};'
     },
   }],
-})
+}])
diff --git a/packages/client/ui-slots/tsdown.config.ts b/packages/client/ui-slots/tsdown.config.ts
new file mode 100644
index 0000000000..b199e31976
--- /dev/null
+++ b/packages/client/ui-slots/tsdown.config.ts
@@ -0,0 +1,6 @@
+import { clientLibrary } from '../tsdown.client.ts'
+
+export default clientLibrary(
+  '@deepseek-ai/dsh-client-ui-slots',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+)
diff --git a/packages/client/ui-theme/tsdown.config.ts b/packages/client/ui-theme/tsdown.config.ts
index 08616753ce..25b80eef68 100644
--- a/packages/client/ui-theme/tsdown.config.ts
+++ b/packages/client/ui-theme/tsdown.config.ts
@@ -1,11 +1,11 @@
 import { clientBundle } from '../tsdown.client.ts'
 
-const [lib, client] = clientBundle(
+export default clientBundle(
   '@deepseek-ai/dsh-client-ui-theme',
   ['lib/types/index.js', 'lib/types/invariant.js'],
+  {
+    lib: {
+      copy: [{ from: 'src/styles/*', to: 'lib/styles' }],
+    },
+  },
 )
-
-export default [{
-  ...lib,
-  copy: [{ from: 'src/styles/*', to: 'lib/styles' }],
-}, client]
diff --git a/packages/client/web-react/tsdown.config.ts b/packages/client/web-react/tsdown.config.ts
index 65378be678..676d6ce415 100644
--- a/packages/client/web-react/tsdown.config.ts
+++ b/packages/client/web-react/tsdown.config.ts
@@ -1,4 +1,4 @@
-import { defineConfig } from 'tsdown'
+import { clientOnly } from '../tsdown.client.ts'
 
 /**
  * Root and invariant shapes as SEPARATE single-entry bundles: a multi-entry
@@ -8,7 +8,7 @@ import { defineConfig } from 'tsdown'
  * runtime — browser consumers resolve this package through the loader module
  * table.
  */
-export default defineConfig([
+export default clientOnly([
   {
     entry: { index: 'lib/types/index.js' },
     outDir: 'lib',
diff --git a/packages/client/web/tsdown.config.ts b/packages/client/web/tsdown.config.ts
index 8040221e14..78527fba80 100644
--- a/packages/client/web/tsdown.config.ts
+++ b/packages/client/web/tsdown.config.ts
@@ -1,4 +1,4 @@
-import { defineConfig } from 'tsdown'
+import { clientOnly } from '../tsdown.client.ts'
 
 /**
  * Root-shape lib build plus a css stub: the shell's components import
@@ -8,7 +8,7 @@ import { defineConfig } from 'tsdown'
  * this node lib build stubs every css import to an empty module — importing
  * the lib under plain node must not crash on an asset specifier.
  */
-export default defineConfig({
+export default clientOnly([{
   entry: ['lib/types/index.js', 'lib/types/invariant.js'],
   outDir: 'lib',
   format: ['esm'],
@@ -28,4 +28,4 @@ export default defineConfig({
       return 'export default {};'
     },
   }],
-})
+}])
diff --git a/packages/host/apiproxy/tsconfig.json b/packages/host/apiproxy/tsconfig.json
index 912f2cd794..8686a9e468 100644
--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../../vendor/schemastery"
     },
     {
-      "path": "../../api/remotes"
+      "path": "../../api/remotes/tsconfig.host.json"
     },
     {
       "path": "../../util/brand"
diff --git a/packages/host/directory-picker-native/tsdown.config.ts b/packages/host/directory-picker-native/tsdown.config.ts
index 529fb7b2ac..4a4727a5aa 100644
--- a/packages/host/directory-picker-native/tsdown.config.ts
+++ b/packages/host/directory-picker-native/tsdown.config.ts
@@ -3,18 +3,21 @@ import { clientBundle } from '../../client/tsdown.client.ts'
 // The Win32 dialog worker builds as its own CJS entry (mirroring
 // dsh-workflow-workerthread's worker): path-loaded by the driver, inlining
 // the dialog logic while koffi stays an external native require.
-export default [
-  ...clientBundle('@deepseek-ai/dsh-host-directory-picker-native', ['lib/types/index.js', 'lib/types/invariant.js']),
+export default clientBundle(
+  '@deepseek-ai/dsh-host-directory-picker-native',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
   {
-    // The artifact is lib/worker.cjs (the ./worker export the workspace
-    // constraint keys on), bundled from the descriptive source entry.
-    entry: { worker: 'lib/types/win32-dialog-worker.js' },
-    outDir: 'lib',
-    format: ['cjs'] as ['cjs'],
-    platform: 'node' as const,
-    target: 'es2024',
-    fixedExtension: false,
-    dts: false,
-    clean: false,
+    host: [{
+      // The artifact is lib/worker.cjs (the ./worker export the workspace
+      // constraint keys on), bundled from the descriptive source entry.
+      entry: { worker: 'lib/types/win32-dialog-worker.js' },
+      outDir: 'lib',
+      format: ['cjs'],
+      platform: 'node',
+      target: 'es2024',
+      fixedExtension: false,
+      dts: false,
+      clean: false,
+    }],
   },
-]
+)
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index c5d89b3726..6f495aa318 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -476,11 +476,20 @@ export class WorkspaceAnalyzer {
           config: this.caches.config(configPath),
           manifest,
         }
-        if (isDualFacePackage(manifest)) {
-          registrations.push({ ...registration, face: 'host', exportSubpaths: hostExportSubpaths(manifest) })
-          registrations.push({ ...registration, face: 'client', exportSubpaths: clientExportSubpaths(manifest) })
-        } else {
+        if (!isDualFacePackage(manifest)) {
           registrations.push(registration)
+        } else if (configPath === join(packageRoot, 'tsconfig.json')) {
+          registrations.push(
+            { ...registration, face: 'host', exportSubpaths: hostExportSubpaths(manifest) },
+            { ...registration, face: 'client', exportSubpaths: clientExportSubpaths(manifest) },
+          )
+        } else {
+          registrations.push({
+            ...registration,
+            exportSubpaths: face === 'host'
+              ? hostExportSubpaths(manifest)
+              : clientExportSubpaths(manifest),
+          })
         }
       }
     }
diff --git a/packages/typert/generator/tests/type-model.spec.ts b/packages/typert/generator/tests/type-model.spec.ts
index ca37cd1bbe..40a91e3ef5 100644
--- a/packages/typert/generator/tests/type-model.spec.ts
+++ b/packages/typert/generator/tests/type-model.spec.ts
@@ -864,6 +864,31 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
       .toEqual(['@fixture/host'])
   })
 
+  it('keeps both runtime faces for an ordinary dshClient project', () => {
+    const root = copyFixture('typert-dual-runtime-')
+    configureDualRuntimeClient(root, false)
+
+    expect(new WorkspaceAnalyzer({ root }).discoverPackages()).toContainEqual({
+      package: '@fixture/client',
+      root: 'packages/client',
+      faces: ['client', 'host'],
+    })
+  })
+
+  it('confines explicit face projects to their selected TypeRT face', () => {
+    const root = copyFixture('typert-split-project-')
+    configureDualRuntimeClient(root, true)
+
+    const markers = new WorkspaceAnalyzer({ root }).indexSourceDeclarations()
+      .filter(declaration => declaration.package === '@fixture/client'
+        && declaration.name.endsWith('OnlyMarker'))
+      .map(declaration => ({ face: declaration.face, name: declaration.name }))
+    expect(markers).toEqual([
+      { face: 'client', name: 'ClientOnlyMarker' },
+      { face: 'host', name: 'HostOnlyMarker' },
+    ])
+  })
+
   it('accepts package export forms while skipping artifact-only rows and unexported packages', { timeout: 180_000 }, () => {
     const root = copyFixture('typert-export-forms-')
     const hostRoot = join(root, 'packages/host')
@@ -1193,6 +1218,63 @@ function copyFixture(prefix: string): string {
   return root
 }
 
+function configureDualRuntimeClient(root: string, splitProjects: boolean): void {
+  const packageRoot = join(root, 'packages/client')
+  const manifestPath = join(packageRoot, 'package.json')
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as {
+    dshClient?: object
+    exports: Record<string, unknown>
+  }
+  manifest.dshClient = {}
+  manifest.exports['./client'] = {
+    types: './lib/types/client.d.ts',
+    default: './lib/client.js',
+  }
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  writeFileSync(join(packageRoot, 'src/client.ts'), [
+    "import { Service } from 'cordis'",
+    'export interface ClientOnlyMarker { readonly client: true }',
+    'export class BrowserBridge extends Service {}',
+    "declare module 'cordis' { interface Context { browserBridge: BrowserBridge } }",
+    '',
+  ].join('\n'))
+  const indexPath = join(packageRoot, 'src/index.ts')
+  writeFileSync(indexPath, `${readFileSync(indexPath, 'utf8')}\nexport interface HostOnlyMarker { readonly host: true }\n`)
+  if (!splitProjects) return
+
+  const project = JSON.parse(readFileSync(join(packageRoot, 'tsconfig.json'), 'utf8')) as Record<string, unknown>
+  delete project.include
+  writeFileSync(join(packageRoot, 'tsconfig.host.json'), `${JSON.stringify({
+    ...project,
+    files: ['src/index.ts'],
+  }, null, 2)}\n`)
+  writeFileSync(join(packageRoot, 'tsconfig.client.json'), `${JSON.stringify({
+    ...project,
+    files: ['src/client.ts'],
+  }, null, 2)}\n`)
+  writeFileSync(join(packageRoot, 'tsconfig.json'), `${JSON.stringify({
+    files: [],
+    references: [
+      { path: './tsconfig.host.json' },
+      { path: './tsconfig.client.json' },
+    ],
+  }, null, 2)}\n`)
+
+  const hostAggregatePath = join(root, 'tsconfig.host.json')
+  const hostAggregate = JSON.parse(readFileSync(hostAggregatePath, 'utf8')) as {
+    references: { path: string }[]
+  }
+  hostAggregate.references.push({ path: './packages/client/tsconfig.host.json' })
+  writeFileSync(hostAggregatePath, `${JSON.stringify(hostAggregate, null, 2)}\n`)
+
+  const clientAggregatePath = join(root, 'tsconfig.client.json')
+  const clientAggregate = JSON.parse(readFileSync(clientAggregatePath, 'utf8')) as {
+    references: { path: string }[]
+  }
+  clientAggregate.references = [{ path: './packages/client/tsconfig.client.json' }]
+  writeFileSync(clientAggregatePath, `${JSON.stringify(clientAggregate, null, 2)}\n`)
+}
+
 function addSameFacePackage(root: string, specifier: string, importedName: string): void {
   const packageRoot = join(root, 'packages/consumer')
   mkdirSync(join(packageRoot, 'src'), { recursive: true })
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 078f775ecf..4e50be7e35 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1446,9 +1446,6 @@ importers:
         specifier: ~4.4.7
         version: 4.4.7(@types/react@18.3.31)(immer@10.2.0)(react@18.3.1)
     devDependencies:
-      '@deepseek-ai/dsh-api-remotes':
-        specifier: workspace:^
-        version: link:../../api/remotes
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
diff --git a/scripts/client-bundle-css.spec.ts b/scripts/client-bundle-css.spec.ts
index 30350241fc..41b3eb3679 100644
--- a/scripts/client-bundle-css.spec.ts
+++ b/scripts/client-bundle-css.spec.ts
@@ -15,8 +15,13 @@ interface CssPlugin {
 }
 
 function cssPlugin(): CssPlugin {
-  const configs = clientBundle('@deepseek-ai/dsh-client-test', ['lib/types/index.js', 'lib/types/invariant.js'])
-  const plugins = (configs[1] as { plugins: CssPlugin[] }).plugins
+  const configs = clientBundle(
+    '@deepseek-ai/dsh-client-test',
+    ['lib/types/index.js', 'lib/types/invariant.js'],
+  )({ env: { DSH_BUILD_FACE: 'client' } })
+  const client = configs.find(config => config.platform === 'browser')
+  if (client === undefined) throw new Error('client config missing')
+  const plugins = (client as { plugins: CssPlugin[] }).plugins
   const plugin = plugins.find(candidate => candidate.name === 'dsh-css-modules-inline')
   if (plugin === undefined) throw new Error('CSS Modules plugin missing from client config')
   return plugin
diff --git a/scripts/client-bundle-purity.spec.ts b/scripts/client-bundle-purity.spec.ts
index fb47f8a9c8..aa3bae0b6d 100644
--- a/scripts/client-bundle-purity.spec.ts
+++ b/scripts/client-bundle-purity.spec.ts
@@ -14,6 +14,24 @@ interface CssModulePlugin {
   load?: (this: { addWatchFile: (id: string) => void }, id: string) => Promise<unknown>
 }
 
+function clientConfigs(id = '@deepseek-ai/dsh-client-test') {
+  return clientBundle(id, ['lib/types/index.js', 'lib/types/invariant.js'])(
+    { env: { DSH_BUILD_FACE: 'client' } },
+  ).filter(config => config.platform === 'browser')
+}
+
+describe('client bundle build faces', () => {
+  it('watches source in development and consumes emitted JavaScript in the Client build', () => {
+    const bundle = clientBundle('@deepseek-ai/dsh-client-test', ['lib/types/index.js'])
+    const development = bundle({ env: {} }).find(config => config.platform === 'browser')
+    const artifact = bundle({ env: { DSH_BUILD_FACE: 'client' } })
+      .find(config => config.platform === 'browser')
+
+    expect(development?.entry).toEqual({ client: 'src/client/index.ts' })
+    expect(artifact?.entry).toEqual({ client: 'lib/types/client/index.js' })
+  })
+})
+
 function clientSourceMapPath(packagePath: string): string {
   return fileURLToPath(new URL(`../packages/${packagePath}/lib/client.js.map`, import.meta.url))
 }
@@ -21,16 +39,16 @@ function clientSourceMapPath(packagePath: string): string {
 function purityResolveId(): ResolveId {
   // libEntry is spelled at every call site (no default) so the
   // package-invariants text check can see the invariant entry per package.
-  const configs = clientBundle('@deepseek-ai/dsh-client-test', ['lib/types/index.js', 'lib/types/invariant.js'])
-  const plugins = (configs[1] as { plugins: { name: string; resolveId?: unknown }[] }).plugins
+  const configs = clientConfigs()
+  const plugins = (configs[0] as { plugins: { name: string; resolveId?: unknown }[] }).plugins
   const gate = plugins.find(p => p.name === 'dsh-client-bundle-purity')
   if (gate?.resolveId === undefined) throw new Error('purity plugin missing from client config')
   return gate.resolveId as ResolveId
 }
 
 function cssModulePlugin(): CssModulePlugin {
-  const configs = clientBundle('@deepseek-ai/dsh-client-test', ['lib/types/index.js', 'lib/types/invariant.js'])
-  const plugins = (configs[1] as { plugins: CssModulePlugin[] }).plugins
+  const configs = clientConfigs()
+  const plugins = (configs[0] as { plugins: CssModulePlugin[] }).plugins
   const plugin = plugins.find(candidate => candidate.name === 'dsh-css-modules-inline')
   if (plugin?.resolveId === undefined || plugin.load === undefined) {
     throw new Error('CSS Modules plugin missing from client config')
@@ -87,13 +105,13 @@ describe('client bundle purity gate', () => {
 
 describe('client bundle debug artifacts', () => {
   it('emits source maps for plugin TS and TSX outside the Vite module graph', () => {
-    const configs = clientBundle('@deepseek-ai/dsh-client-test', ['lib/types/index.js', 'lib/types/invariant.js'])
-    expect(configs[1]?.sourcemap).toBe(true)
+    const configs = clientConfigs()
+    expect(configs[0]?.sourcemap).toBe(true)
   })
 
   it('maps first-party sources to their repository package paths', () => {
-    const configs = clientBundle('@deepseek-ai/dsh-client-ui-goal', ['lib/types/index.js', 'lib/types/invariant.js'])
-    const outputOptions = configs[1]?.outputOptions
+    const configs = clientConfigs('@deepseek-ai/dsh-client-ui-goal')
+    const outputOptions = configs[0]?.outputOptions
     if (typeof outputOptions !== 'object' || outputOptions === null) throw new Error('client output options missing')
     const transform = outputOptions.sourcemapPathTransform
     if (transform === undefined) throw new Error('client sourcemap path transform missing')
@@ -105,8 +123,8 @@ describe('client bundle debug artifacts', () => {
   })
 
   it('maps dual-face host sources to the host package group', () => {
-    const configs = clientBundle('@deepseek-ai/dsh-host-directory-picker-native', ['lib/types/index.js'])
-    const outputOptions = configs[1]?.outputOptions
+    const configs = clientConfigs('@deepseek-ai/dsh-host-directory-picker-native')
+    const outputOptions = configs[0]?.outputOptions
     if (typeof outputOptions !== 'object' || outputOptions === null) throw new Error('client output options missing')
     const transform = outputOptions.sourcemapPathTransform
     if (transform === undefined) throw new Error('client sourcemap path transform missing')
@@ -116,8 +134,8 @@ describe('client bundle debug artifacts', () => {
   })
 
   it('maps inlined workspace sources to packages and leaves dependencies outside it unchanged', () => {
-    const configs = clientBundle('@deepseek-ai/dsh-client-connection', ['lib/types/index.js'])
-    const outputOptions = configs[1]?.outputOptions
+    const configs = clientConfigs('@deepseek-ai/dsh-client-connection')
+    const outputOptions = configs[0]?.outputOptions
     if (typeof outputOptions !== 'object' || outputOptions === null) throw new Error('client output options missing')
     const transform = outputOptions.sourcemapPathTransform
     if (transform === undefined) throw new Error('client sourcemap path transform missing')
diff --git a/scripts/doc-typecheck.ts b/scripts/doc-typecheck.ts
index 6ae08150fb..456dedecfe 100644
--- a/scripts/doc-typecheck.ts
+++ b/scripts/doc-typecheck.ts
@@ -136,22 +136,25 @@ function formatDiagnostics(diagnostics: readonly ts.Diagnostic[], blocks: Block[
 }
 
 /**
- * Reuse the host-aggregate references from a temp project one directory below
- * root. Doc fragments speak the host vocabulary, so the standalone project
- * seeds tsconfig.host.json (never the root solution: flattening host+client
- * into one program collides the cordis Context merges).
+ * Reuse both aggregate reference sets from a temp project one directory below
+ * root. Each referenced package remains its own program, while documentation
+ * examples can import either the Host or Client API.
  */
 function workspaceReferences(): { path: string }[] {
-  const file = join(root, 'tsconfig.host.json')
-  // Parse with TypeScript's own JSONC reader: a regex comment stripper corrupts the `/*/` path
-  // candidate in the workspace wildcard.
-  const result = ts.readConfigFile(file, path => readFileSync(path, 'utf8'))
-  if (result.error) {
-    throw new Error(`doc-typecheck: cannot read ${file}: ${ts.flattenDiagnosticMessageText(result.error.messageText, '\n')}`)
+  const paths = new Set<string>()
+  for (const aggregate of ['tsconfig.host.json', 'tsconfig.client.json']) {
+    const file = join(root, aggregate)
+    // Parse with TypeScript's own JSONC reader: a regex comment stripper corrupts the `/*/` path
+    // candidate in the workspace wildcard.
+    const result = ts.readConfigFile(file, path => readFileSync(path, 'utf8'))
+    if (result.error) {
+      throw new Error(`doc-typecheck: cannot read ${file}: ${ts.flattenDiagnosticMessageText(result.error.messageText, '\n')}`)
+    }
+    // `config` is typed `any` by the TS API; narrow it to the one field read here.
+    const { references } = result.config as { references: { path: string }[] }
+    for (const { path } of references) paths.add(path)
   }
-  // `config` is typed `any` by the TS API; narrow it to the one field read here.
-  const { references } = result.config as { references: { path: string }[] }
-  return references.map(({ path }) => ({
+  return [...paths].map(path => ({
     path: path.startsWith('./') ? `../${path.slice(2)}` : `../${path}`,
   }))
 }
diff --git a/scripts/package-invariants.spec.ts b/scripts/package-invariants.spec.ts
index 32705c4c87..59e56976e6 100644
--- a/scripts/package-invariants.spec.ts
+++ b/scripts/package-invariants.spec.ts
@@ -72,6 +72,20 @@ describe('package invariant gate', () => {
     expect(collectPackageInvariantViolations(fixture())).toEqual([])
   })
 
+  it('accepts an invariant reference owned by a package-local leaf project', () => {
+    const root = fixture({ invariantReference: false })
+    const dir = join(root, 'packages/core/probe')
+    writeFileSync(join(dir, 'tsconfig.json'), `${JSON.stringify({
+      files: [],
+      references: [{ path: './tsconfig.host.json' }],
+    }, null, 2)}\n`)
+    writeFileSync(join(dir, 'tsconfig.host.json'), `${JSON.stringify({
+      references: [{ path: '../../support/invariants' }],
+    }, null, 2)}\n`)
+
+    expect(collectPackageInvariantViolations(root)).toEqual([])
+  })
+
   it('rejects missing publication metadata and build output', () => {
     const violations = collectPackageInvariantViolations(fixture({
       invariantExport: false,
diff --git a/scripts/package-invariants.ts b/scripts/package-invariants.ts
index 21bc5931ec..54318ca94f 100644
--- a/scripts/package-invariants.ts
+++ b/scripts/package-invariants.ts
@@ -118,11 +118,8 @@ function checkBuild(
   violations: PackageInvariantViolation[],
 ): void {
   const tsconfigPath = `${owner.dir}/tsconfig.json`
-  const tsconfig = JSON.parse(readFileSync(resolve(root, tsconfigPath), 'utf8')) as {
-    references?: Array<{ path?: string }>
-  }
   if (owner.packageName !== '@deepseek-ai/dsh-invariants'
-    && !tsconfig.references?.some(reference => reference.path === '../../support/invariants')) {
+    && !projectReferencesInvariants(root, owner.dir, tsconfigPath)) {
     addViolation(
       violations,
       tsconfigPath,
@@ -138,6 +135,31 @@ function checkBuild(
   }
 }
 
+function projectReferencesInvariants(root: string, ownerDir: string, entryPath: string): boolean {
+  const ownerRoot = resolve(root, ownerDir)
+  const target = resolve(root, 'packages/support/invariants')
+  const pending = [resolve(root, entryPath)]
+  const visited = new Set<string>()
+  while (pending.length > 0) {
+    const configPath = pending.pop()
+    if (configPath === undefined) break
+    if (visited.has(configPath)) continue
+    visited.add(configPath)
+    const config = JSON.parse(readFileSync(configPath, 'utf8')) as {
+      references?: Array<{ path?: string }>
+    }
+    for (const reference of config.references ?? []) {
+      if (reference.path === undefined) continue
+      const referenced = resolve(dirname(configPath), reference.path)
+      if (referenced === target) return true
+      if (!referenced.startsWith(`${ownerRoot}${sep}`)) continue
+      const childConfig = referenced.endsWith('.json') ? referenced : resolve(referenced, 'tsconfig.json')
+      if (existsSync(childConfig)) pending.push(childConfig)
+    }
+  }
+  return false
+}
+
 function checkSource(
   owner: PackageInvariantOwner,
   root: string,
diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
index 1f5de1dcbd..b6d8ffffb0 100755
--- a/scripts/wine-windows-gates.sh
+++ b/scripts/wine-windows-gates.sh
@@ -204,15 +204,14 @@ cat "$scratch/logs/smoke.log"
 grep -q '^smoke: win32 x64' "$scratch/logs/smoke.log" || { echo 'wine-windows-gates: Windows Node smoke did not report win32 x64' >&2; exit 1; }
 
 # ---- the two blocking surfaces, concurrently ------------------------------
-# The build preserves the face order from package.json: generate Host contracts
-# before either aggregate typecheck, then bundle the completed workspace.
+# The build preserves the face order from package.json: compile and bundle the
+# Host face before compiling and bundling the Client face.
 # Both statuses are captured so one failure cannot hide the other's result.
 build_gate() {
-  wine_node "$scratch/logs/contracts-tsc.log" "$tsc_js" -b packages/typert/generator --pretty false || return $?
-  wine_node "$scratch/logs/contracts-tsdown.log" "$tsdown_js" --config tsdown.typert-host.config.ts || return $?
   wine_node "$scratch/logs/host-tsc.log" "$tsc_js" -b tsconfig.host.json --pretty false || return $?
+  wine_node "$scratch/logs/host-tsdown.log" "$tsdown_js" --env.DSH_BUILD_FACE host || return $?
   wine_node "$scratch/logs/client-tsc.log" "$tsc_js" -b tsconfig.client.json --pretty false || return $?
-  wine_node "$scratch/logs/tsdown.log" "$tsdown_js"
+  wine_node "$scratch/logs/client-tsdown.log" "$tsdown_js" --env.DSH_BUILD_FACE client
 }
 site_gate() {
   cd website
@@ -238,12 +237,11 @@ report() {
     for log in "$@"; do tail -n 200 "$log" >&2 || true; done
   fi
 }
-report 'build (contract prepass, tsc, tsdown)' "$build_status" \
-  "$scratch/logs/contracts-tsc.log" \
-  "$scratch/logs/contracts-tsdown.log" \
+report 'build (Host tsc/tsdown, Client tsc/tsdown)' "$build_status" \
   "$scratch/logs/host-tsc.log" \
+  "$scratch/logs/host-tsdown.log" \
   "$scratch/logs/client-tsc.log" \
-  "$scratch/logs/tsdown.log"
+  "$scratch/logs/client-tsdown.log"
 report 'production site (vitepress build)' "$site_status" "$scratch/logs/site.log"
 if (( build_status != 0 )); then exit "$build_status"; fi
 exit "$site_status"
diff --git a/tsconfig.client.json b/tsconfig.client.json
index 9821c0e41b..2a2b16e2e7 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -53,7 +53,7 @@
     { "path": "./packages/client/connection" },
     { "path": "./packages/typert/registry" },
     { "path": "./packages/api/gateway" },
-    { "path": "./packages/api/remotes" },
+    { "path": "./packages/api/remotes/tsconfig.client.json" },
     { "path": "./packages/client/runtime" },
     { "path": "./packages/client/test-runtime" },
     { "path": "./packages/client/ui-layout" },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 61e42e2fc6..7e7cd982fc 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -104,6 +104,7 @@
     { "path": "./packages/typert/type-meta" },
     { "path": "./packages/typert/registry" },
     { "path": "./packages/api/gateway" },
+    { "path": "./packages/api/remotes/tsconfig.host.json" },
     { "path": "./packages/typert/loader" },
     { "path": "./packages/session-persistence/session-persistence" },
     { "path": "./packages/session-persistence/session-checkpoint-policy" },
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 0d503c62d3..2042e81db3 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -1,34 +1,30 @@
 import { defineConfig } from 'tsdown'
 import { typertPlugin } from './packages/typert/generator/lib/types/tsdown-plugin.js'
 
+function isBuildFaceClient(value: unknown): boolean {
+  if (value === undefined || value === 'host') return false
+  if (value === 'client') return true
+  throw new Error(`tsdown: --env.DSH_BUILD_FACE must be host or client, received ${String(value)}`)
+}
+
 /**
- * JS bundling for vendored Cordis and Harness TypeScript packages.
- * TypeScript source is compiled first by `tsc -b` (the root solution); tsdown
- * reads only the emitted JS under lib/types and writes the package root and
- * invariant companion runtime bundles. Declarations are NOT produced here,
- * hence `dts: false`.
- *
- * Per-package shape overrides live in `<package>/tsdown.config.ts`
- * (schemastery: dual ESM+CJS; logger-console: extra browser entry).
+ * The ordinary workspace build consumes JavaScript emitted by the Host
+ * TypeScript project and runs TypeRT. The Client pass selects packages that
+ * declare a browser bundle and lets their package-local configs emit both
+ * their Node loader entry and browser artifact.
  */
-export default defineConfig({
-  // Explicit globs keep bundling to vendored Cordis, the TypeScript package tree, and
-  // the Node CLI assembly. `apps/web` is a Vite application with no lib/types entry;
-  // `workspace: true` or `apps/*` would incorrectly treat it as a package bundle.
-  workspace: ['vendor/*', 'packages/*/*', 'apps/cli'],
-  // The brace glob admits the package companion when present while retaining the
-  // index-only build for vendored Cordis packages outside the Harness package tree.
-  entry: ['lib/types/{index,invariant}.js'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  // All packages set "type": "module"; fixedExtension false keeps ESM output
-  // at .js (not .mjs), matching the package.json main/exports fields.
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-  // The final pass sees both independent TypeScript faces. Workspace mode
-  // writes only packages that explicitly publish a Typert/Remote subpath.
-  plugins: [typertPlugin({ mode: 'workspace' })],
+export default defineConfig(({ env }) => {
+  const client = isBuildFaceClient(env?.DSH_BUILD_FACE)
+  return {
+    workspace: ['vendor/*', 'packages/*/*', 'apps/cli'],
+    entry: client ? '' : ['lib/types/{index,invariant}.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+    plugins: client ? [] : [typertPlugin({ mode: 'workspace', faces: ['host'] })],
+  }
 })
diff --git a/tsdown.typert-host.config.ts b/tsdown.typert-host.config.ts
deleted file mode 100644
index 8c8ae11dd1..0000000000
--- a/tsdown.typert-host.config.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { defineConfig } from 'tsdown'
-import { typertPlugin } from './packages/typert/generator/lib/types/tsdown-plugin.js'
-
-/**
- * Host-only TypeRT contract prepass. The generator and its project references
- * are compiled first; the plugin then analyzes Host source and emits local and
- * Host-for-Client artifacts before either aggregate consumes Remote subpaths.
- */
-export default defineConfig({
-  workspace: ['packages/typert/generator'],
-  entry: ['lib/types/{index,invariant}.js'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-  plugins: [typertPlugin({ mode: 'workspace', faces: ['host'] })],
-})

From 8865548ee2397927866e0ca6ddc6d777069f6af4 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 03:41:35 +0800
Subject: [PATCH 195/516] docs: explain generated Remote build order

---
 .../2026-06-17-ts-build-config.i18n.yaml      |   4 +-
 .../process/2026-06-17-ts-build-config.md     |  29 +-
 .../process/2026-06-17-ts-build-config.zh.md  |  29 +-
 ...fig-solution-root-two-aggregates.i18n.yaml |   6 +-
 ...2-tsconfig-solution-root-two-aggregates.md |   6 +-
 ...sconfig-solution-root-two-aggregates.zh.md |   6 +-
 ...remotes-generated-contract-build.i18n.yaml |   6 +
 ...08-api-remotes-generated-contract-build.md |  80 ++++
 ...api-remotes-generated-contract-build.zh.md |  80 ++++
 AGENTS.md                                     |   2 +-
 docs/api-gateway.i18n.yaml                    |   4 +-
 docs/api-gateway.md                           |  12 +-
 docs/api-gateway.zh.md                        |  12 +-
 docs/cookbook/adding-a-package.i18n.yaml      |   4 +-
 docs/cookbook/adding-a-package.md             |   2 +-
 docs/cookbook/adding-a-package.zh.md          |   2 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |  35 +-
 docs/development.zh.md                        |  35 +-
 docs/module-graph.md                          | 343 +++++++++---------
 packages/AGENTS.md                            |   2 +-
 packages/api/remotes/README.i18n.yaml         |   4 +-
 packages/api/remotes/README.md                |   8 +
 packages/api/remotes/README.zh.md             |   8 +
 packages/typert/generator/README.i18n.yaml    |   4 +-
 packages/typert/generator/README.md           |   4 +-
 packages/typert/generator/README.zh.md        |   4 +-
 .../request-response.expected.json            |   4 +-
 28 files changed, 480 insertions(+), 259 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
 create mode 100644 .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md

diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
index fe42a92f75..a126f8c0d0 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.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 .agents/notes/implemented/process/2026-06-17-ts-build-config.md
-2026-06-17-ts-build-config.md: ec4c6a4aeb1074a69d45b2cf4b4c733b410ccceb
-2026-06-17-ts-build-config.zh.md: 8115bb2557eea967d57eb6693e2bb288188792a8
+2026-06-17-ts-build-config.md: f25731921aaa6da7a4c9760244f73dc0670dc1d3
+2026-06-17-ts-build-config.zh.md: 41791129647b6a5bfeb966e05ee2c5b9132c45ef
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.md b/.agents/notes/implemented/process/2026-06-17-ts-build-config.md
index ec4c6a4aeb..f25731921a 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.md
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-06-17-ts-build-config.zh.md)
 
-> Root project topology (which tsconfig owns which graph) has since moved to a solution root over two aggregate programs; see the [solution-root note](2026-07-22-tsconfig-solution-root-two-aggregates.md). The tsc-first pipeline decided here is unchanged.
+> Root project topology uses a solution root over two aggregate programs; see the [solution-root note](2026-07-22-tsconfig-solution-root-two-aggregates.md). The [API Remotes build note](2026-08-08-api-remotes-generated-contract-build.md) defines the current command order in which the Host generates Remote contracts before the Client compiles. The tsc-first ownership decided here is unchanged.
 
 ## Problem
 
@@ -30,18 +30,15 @@ Validation found several concrete technical issues and possible routes:
 
 In-package relative imports use explicit `.ts` specifiers.
 
-`pnpm run build` is a two-stage build:
+`pnpm run build` orders Host lib, Client lib, and Web; each lib phase keeps tsc emission before tsdown bundling:
 
-- Stage 1: `tsc -b` over the root solution emits per-module `.js`, declarations `.d.ts`, JS sourcemaps `.js.map`, and declaration sourcemaps `.d.ts.map` into each package's `lib/types`. This is the authoritative TypeScript compilation result. Publication keeps `.d.ts`; packages whose runtime exports explicitly point into the emitted tree also keep its `.js` files. `.js.map` and `.d.ts.map` remain in the local build tree.
-    - The graph is the project-reference graph reachable from the root solution `tsconfig.json` through the two aggregates ([topology](2026-07-22-tsconfig-solution-root-two-aggregates.md)). It validates and emits package/vendor build results.
-- Stage 2: a bundler reads the emitted JS under `lib/types` and writes the bundled runtime entry as `lib/index.js` or `lib/index.mjs` (follow current behavior). This stage is bundling only. It must not read TypeScript source or emit declarations.
+- Host tsc runs `tsc -b` against `tsconfig.host.json`, emitting per-module `.js`, `.d.ts`, `.js.map`, and `.d.ts.map` into `lib/types` for each package in the Host graph; Host tsdown then reads that JavaScript, produces published entries, and runs Host TypeRT.
+- Client tsc runs `tsc -b` against `tsconfig.client.json` after Host TypeRT has generated the Remote Client declarations; Client tsdown then reads the JavaScript emitted by the Client graph and produces the Client packages' Node loader entries and browser bundles.
+- The Web build starts only after both lib phases complete.
 
 `tsdown` is no longer the owner of TypeScript compilation or declaration output.
 
-`pnpm run typecheck` runs the same `tsc -b` graph.
-- The aggregates (`tsconfig.host.json`, `tsconfig.client.json`) typecheck examples, tests, and scripts with `noEmit`, and validate package/vendor source through references.
-- Referenced package/vendor projects keep the same emit behavior as build, so typecheck refreshes their `lib/types` outputs instead of using a separate no-emit graph. Project-specific strictness changes live in the owning `packages/*/*/tsconfig.json` or `vendor/*/tsconfig.json`.
-- The no-emit aggregates disable `rewriteRelativeImportExtensions`; they emit nothing and include tests that import helpers across project-reference boundaries. Package/vendor emit projects keep the rewrite enabled.
+`pnpm run typecheck` first runs the Host lib phase to generate the Remote declarations required by Client typechecking, then runs `tsc -b` against `tsconfig.client.json`. The two aggregates themselves check their respective examples, tests, and scripts with `noEmit`; referenced package/vendor projects retain the same emit behavior as the build.
 
 Composite projects keep their incremental build information inside their project-local `lib/` output. `pnpm run clean` derives live output directories from the root TypeScript project-reference graph, removes legacy root build information, and removes deleted `packages/*/*` directories that contain only known generated residue. Before removing an existing target, it resolves the target's parent and refuses it if that resolved parent is outside the repository, so a symlinked project reference cannot redirect cleanup outside the checkout. It preserves `node_modules` for every package that still has a `package.json`, and refuses to remove a manifest-less directory containing unknown files. Build does not invoke clean automatically, so ordinary builds retain incremental state.
 
@@ -49,14 +46,18 @@ The command orchestration shape is:
 
 ```sh
 pnpm run build:
-tsc -b
-tsdown
+tsc -b tsconfig.host.json
+tsdown --env.DSH_BUILD_FACE host
+tsc -b tsconfig.client.json
+tsdown --env.DSH_BUILD_FACE client
+pnpm run build:web
 
 pnpm run verify-node-next-types:
 tsx scripts/verify-node-next-types.ts
 
 pnpm run typecheck:
-tsc -b
+pnpm run build:lib:host
+tsc -b tsconfig.client.json
 
 pnpm run clean:
 tsx scripts/clean.ts
@@ -75,8 +76,8 @@ The source-mode demos run through their declared TypeScript launchers and the ro
 
 Build responsibilities are clearer:
 
-- Each module under `packages/<group>/<pkg>` and `vendor/*` has one local tsconfig for build, typecheck, and tools that run source directly, such as the `dsh` source loader, `tsx`, and `vitest`.
-- The `build` command drives the root solution graph. `tsc -b` owns the publishable per-module `.js` and `.d.ts` output, and the bundler owns only `lib/index.*`.
+- Each ordinary module under `packages/<group>/<pkg>` and `vendor/*` has one local tsconfig for build, typecheck, and tools that run source directly, such as the `dsh` source loader, `tsx`, and `vitest`. `api/remotes` is the sole exception: generated-contract ordering requires one solution and two mutually exclusive emitting projects.
+- The `build` command runs the Host and Client Project Reference graphs in order. In each phase, `tsc -b` owns the publishable per-module `.js` and `.d.ts` output, while the bundler owns only the published runtime bundles.
     - `lib/types/*.d.ts` is the publish declaration output; `.d.ts.map` remains only as a local compilation artifact.
     - `lib/types/*.d.ts` uses explicit `.ts` relative specifiers, which TypeScript's NodeNext/Node16 resolver maps to sibling `.d.ts` files.
     - `lib/types/*.js` is normally only a bundler input. It is published only when an explicit runtime export points into the emitted tree.
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
index 8115bb2557..4179112964 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-06-17-ts-build-config.md) | 中文
 
-> 根项目拓扑（即哪个 tsconfig 拥有哪张图）后来改为由一个 solution 根文件统辖两个聚合 program；见[solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。本文确定的 TSC 优先流水线保持不变。
+> 根项目拓扑由一个 solution 根文件统辖两个 aggregate program；见 [solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。Host 生成 Remote 契约后再编译 Client 的当前命令顺序见 [API Remotes 构建 Agent Note](2026-08-08-api-remotes-generated-contract-build.md)。本文确定的 tsc-first 职责保持不变。
 
 ## 问题
 
@@ -30,18 +30,15 @@ Status: implemented
 
 包内相对导入使用显式 `.ts` 说明符。
 
-`pnpm run build` 是两阶段构建：
+`pnpm run build` 按 Host lib、Client lib 和 Web 排序；每个 lib 阶段都保持 tsc 先发射、tsdown 后打包：
 
-- 阶段 1：在根 solution 上执行 `tsc -b`，将逐模块的 `.js`、声明文件 `.d.ts`、JS sourcemap `.js.map` 和声明 sourcemap `.d.ts.map` 输出到各包的 `lib/types`。这是权威的 TypeScript 编译结果。发布时保留 `.d.ts`；如果包的运行时 export 显式指向该输出树，也会保留其中的 `.js` 文件。`.js.map` 和 `.d.ts.map` 留在本地构建树中。
-    - 该图是从根 solution `tsconfig.json` 经两个聚合可达的 project-reference 图（[拓扑](2026-07-22-tsconfig-solution-root-two-aggregates.md)），用于校验并输出包/vendor 的构建结果。
-- 阶段 2：打包器读取 `lib/types` 下输出的 JS，将打包后的运行时入口写为 `lib/index.js` 或 `lib/index.mjs`（沿用当前行为）。此阶段仅做打包，禁止读取 TypeScript 源码或输出声明文件。
+- Host tsc 对 `tsconfig.host.json` 执行 `tsc -b`，把逐模块 `.js`、`.d.ts`、`.js.map` 与 `.d.ts.map` 输出到 Host 图各 package 的 `lib/types`；Host tsdown 随后读取这些 JS，生成发布入口并运行 Host TypeRT。
+- Client tsc 在 Host TypeRT 已生成 Remote Client 声明后对 `tsconfig.client.json` 执行 `tsc -b`；Client tsdown 再读取 Client 图发射的 JS，生成 Client package 的 Node loader 入口与 browser bundle。
+- Web build 只在两个 lib 阶段完成后启动。
 
 `tsdown` 不再负责 TypeScript 编译或声明文件输出。
 
-`pnpm run typecheck` 运行同一张 `tsc -b` 图。
-- 两个聚合（`tsconfig.host.json`、`tsconfig.client.json`）以 `noEmit` 方式检查示例、测试和脚本，并通过 references 校验包/vendor 源码。
-- 被引用的包/vendor 项目保持与构建相同的输出行为，因此类型检查会刷新它们的 `lib/types` 输出，而无需使用独立的 no-emit 图。项目特定的严格度变更放在各自的 `packages/*/*/tsconfig.json` 或 `vendor/*/tsconfig.json` 中。
-- 两个 no-emit 聚合禁用 `rewriteRelativeImportExtensions`；它们不输出任何文件，且包含跨 project-reference 边界导入 helper 的测试。包/vendor 的 emit 项目保持重写开启。
+`pnpm run typecheck` 先执行 Host lib 阶段，以生成 Client 类型检查所需的 Remote 声明，再对 `tsconfig.client.json` 执行 `tsc -b`。两个 aggregate 本身以 `noEmit` 方式检查各自的示例、测试与脚本；被引用的 package/vendor project 保持与构建相同的发射行为。
 
 复合项目将增量构建信息保存在各项目本地的 `lib/` 输出中。`pnpm run clean` 会根据根 TypeScript project-reference 图确定当前有效的输出目录，删除遗留的根目录构建信息，并删除已删除包留下且仅包含已知生成残留的 `packages/*/*` 目录。在删除现有目标前，该命令会解析目标父目录的真实路径；如果解析后的父目录位于仓库之外，则拒绝删除，防止使用符号链接的 project reference 将清理操作重定向到工作副本之外。对于仍有 `package.json` 的每个包，该命令都会保留 `node_modules`；如果不含 `package.json` 的目录中存在未知文件，则拒绝删除。构建不会自动调用 clean，因此常规构建会保留增量状态。
 
@@ -49,14 +46,18 @@ Status: implemented
 
 ```sh
 pnpm run build:
-tsc -b
-tsdown
+tsc -b tsconfig.host.json
+tsdown --env.DSH_BUILD_FACE host
+tsc -b tsconfig.client.json
+tsdown --env.DSH_BUILD_FACE client
+pnpm run build:web
 
 pnpm run verify-node-next-types:
 tsx scripts/verify-node-next-types.ts
 
 pnpm run typecheck:
-tsc -b
+pnpm run build:lib:host
+tsc -b tsconfig.client.json
 
 pnpm run clean:
 tsx scripts/clean.ts
@@ -75,8 +76,8 @@ tsx scripts/clean.ts
 
 构建职责更加清晰：
 
-- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。
-- `build` 命令驱动根 solution 图。`tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责 `lib/index.*`。
+- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个普通模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。`api/remotes` 因生成契约顺序使用一个 solution 和两个互斥的 emitting project，是唯一例外。
+- `build` 命令按 Host 与 Client Project Reference 图执行。每个阶段都由 `tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责发布 runtime bundle。
     - `lib/types/*.d.ts` 是发布用的声明输出；`.d.ts.map` 只作为本地编译产物保留。
     - `lib/types/*.d.ts` 使用显式 `.ts` 相对说明符，TypeScript 的 NodeNext/Node16 解析器会将其映射到同级的 `.d.ts` 文件。
     - `lib/types/*.js` 通常仅作为打包器输入。只有显式运行时 export 指向该输出树时，才会发布这些文件。
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
index d191386725..2a6cdcc2d0 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.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-22-tsconfig-solution-root-two-aggregates.md: 19c229693b98ff3825caf935fa647ab85aff0f56
-2026-07-22-tsconfig-solution-root-two-aggregates.zh.md: becc43de1ef2f6a53b0f6c2285eb64d9b42604f1
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md
+2026-07-22-tsconfig-solution-root-two-aggregates.md: 6e8d192b5fea1c7045ade6935fd0e2dc8434c502
+2026-07-22-tsconfig-solution-root-two-aggregates.zh.md: 60581e3de55227a393e2528ce7d3c8fa1bf9c570
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md
index 19c229693b..6e8d192b5f 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md
@@ -27,7 +27,7 @@ One solution root, two check units, one shared base pair, no separate build or v
 
 The load-bearing principle: **cordis `Context` declaration-merge collisions exist only inside a `ts.Program`, never in module resolution.** A solution file forms no program, so referencing both aggregates from one root cannot collide the merges; vite-tsconfig-paths reads only `paths` and `include` and discards types, so one facade may span both sides. The only way to explode is to flatten both sides into a single program — hence two derived disciplines: `tsconfig.base.json` never gains `include`/`files` (it would leak into every extending package and narrow the facade), and every repo-wide `ts.Program` consumer (`scripts/ts-project.ts`, doc-typecheck standalone mode) seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly, never the root solution. Program-backed generators and semantic gates intentionally stay host-only; the client side gets program-backed gates only when a real need arrives.
 
-Commands collapse to one graph and keep the config name explicit: `typecheck` = `tsc -b tsconfig.json`, `build` = `tsc -b tsconfig.json && tsdown`, lefthook pre-push stays `tsc -b tsconfig.json --pretty false` unchanged (the same line now covers both sides through the solution). `tsconfig.build.json` and `tsconfig.vitest.json` are deleted; all vitest configs point vite-tsconfig-paths at `tsconfig.base.json`.
+The root `tsconfig.json` remains the solution entry for explicitly running the complete Project Reference graph, and lefthook pre-push incrementally covers both sides through `tsc -b tsconfig.json --pretty false`. Because the Client depends on Remote contracts generated by Host tsdown, the repository's `build` and `typecheck` commands run the Host and Client in order; the [API Remotes build note](2026-08-08-api-remotes-generated-contract-build.md) owns the exact orchestration. `tsconfig.build.json` and `tsconfig.vitest.json` are deleted; all vitest configs point vite-tsconfig-paths at `tsconfig.base.json`.
 
 The solution root `extends` the base deliberately: `examples/` and `scripts/` have no nearer tsconfig, so tsx (get-tsconfig) resolves their workspace imports through the root file. `extends` restores the `paths` map there while `files: []` keeps the file program-less. Their *type checking* is unaffected by this: examples, scripts, and website files are included by the host aggregate.
 
@@ -41,5 +41,5 @@ The solution root `extends` the base deliberately: `examples/` and `scripts/` ha
 
 - `docs/development.md#typescript-project-layout` is the authoritative description; root `AGENTS.md` carries the two disciplines as conventions.
 - The [ts-build-config note](2026-06-17-ts-build-config.md) keeps ownership of the tsc-first build pipeline (tsc emits, tsdown bundles, `.ts` specifiers with `rewriteRelativeImportExtensions`); its former "one root typecheck project" shape is superseded by this note.
-- Adding a package registers it in exactly one aggregate's references (host packages in `tsconfig.host.json`, client packages in `tsconfig.client.json`); the build graph needs no separate registration.
-- The build gate depends on the typecheck gate: both now drive the same `tsc -b` graph, so running them concurrently would race the same `.tsbuildinfo` files.
+- Adding an ordinary package registers it in exactly one aggregate's references: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`. `api/remotes` is the only explicit split exception because the Host generates a contract that the Client consumes later; its two concrete projects are registered separately, while its package-root solution enters neither aggregate.
+- The Host and Client build phases must run serially: Client tsc cannot begin until Host tsdown has generated the contract. Each phase reuses its projects' incremental state instead of processing the same graph concurrently.
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
index becc43de1e..60581e3de5 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
@@ -27,7 +27,7 @@ GUI 拆分引入了第二个聚合 program（`tsconfig.client.json`，见[分层
 
 整个方案立足的原则：**cordis `Context` 的声明合并冲突只存在于同一个 `ts.Program` 内部，从不发生在模块解析中。** solution 文件不构成 program，因此从一个根文件同时引用两个聚合不会让两侧的声明合并相撞；vite-tsconfig-paths 只读取 `paths` 与 `include`、丢弃全部类型信息，因此一个门面可以横跨两侧。唯一会爆炸的做法是把两侧压平进同一个 program，由此推出两条派生纪律：`tsconfig.base.json` 永远不得添加 `include`/`files`（否则会泄漏进每个继承它的包，并收窄门面范围）；每个全仓级 `ts.Program` 消费方（`scripts/ts-project.ts`、doc-typecheck 独立模式）都显式以 `tsconfig.host.json` 或 `tsconfig.client.json` 为种子，绝不使用根 solution。基于 program 的生成器与语义门禁有意只留在宿主侧；客户端侧只有在真实需求出现时才引入基于 program 的门禁。
 
-各命令收敛到一张图，且显式写出配置名：`typecheck` = `tsc -b tsconfig.json`，`build` = `tsc -b tsconfig.json && tsdown`，lefthook pre-push 保持 `tsc -b tsconfig.json --pretty false` 不变（经由 solution，这同一行命令现已覆盖两侧）。`tsconfig.build.json` 与 `tsconfig.vitest.json` 删除；所有 vitest 配置都把 vite-tsconfig-paths 指向 `tsconfig.base.json`。
+根 `tsconfig.json` 仍是显式执行完整 Project Reference 图的 solution 入口，lefthook pre-push 通过 `tsc -b tsconfig.json --pretty false` 增量覆盖两侧。仓库的 `build` 与 `typecheck` 命令因 Client 依赖 Host tsdown 生成的 Remote 契约而按 Host、Client 顺序运行，具体编排由 [API Remotes 构建 Note](2026-08-08-api-remotes-generated-contract-build.md)负责。`tsconfig.build.json` 与 `tsconfig.vitest.json` 已删除；所有 vitest 配置都把 vite-tsconfig-paths 指向 `tsconfig.base.json`。
 
 solution 根文件刻意 `extends` base：`examples/` 与 `scripts/` 没有更近的 tsconfig，tsx（get-tsconfig）通过根文件解析它们的 workspace 导入。`extends` 把 `paths` 映射带回根文件，`files: []` 则让它始终不构成 program。这不影响两者的*类型检查*：examples、scripts 与 website 的文件由宿主聚合纳入。
 
@@ -41,5 +41,5 @@ solution 根文件刻意 `extends` base：`examples/` 与 `scripts/` 没有更
 
 - `docs/development.md#typescript-project-layout` 是权威描述；根 `AGENTS.md` 以约定形式收录上述两条纪律。
 - [ts-build-config Agent Note](2026-06-17-ts-build-config.md) 继续拥有 tsc 先行的构建流水线（tsc 负责输出，tsdown 负责打包，`.ts` 说明符配合 `rewriteRelativeImportExtensions`）；其原先「单一根类型检查项目」的形态由本文取代。
-- 新增一个包只登记进恰好一个聚合的 references（宿主包进 `tsconfig.host.json`，客户端包进 `tsconfig.client.json`）；构建图无需另行登记。
-- 构建门禁依赖类型检查门禁：两者现在驱动同一张 `tsc -b` 图，并发运行会在同一批 `.tsbuildinfo` 文件上竞态。
+- 新增一个普通 package 只登记进恰好一个 aggregate 的 references（Host package 进 `tsconfig.host.json`，Client package 进 `tsconfig.client.json`）。`api/remotes` 因 Host 生成契约与 Client 消费契约的顺序关系成为唯一显式拆分例外；其两个具体 project 分别登记，包根 solution 不进入任一 aggregate。
+- Host 与 Client 构建阶段必须串行：Host tsdown 生成契约后 Client tsc 才能开始。各阶段复用各 project 的增量状态，不通过并发重复处理同一张图。
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
new file mode 100644
index 0000000000..8b1bbf8b4d
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.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/process/2026-08-08-api-remotes-generated-contract-build.md
+2026-08-08-api-remotes-generated-contract-build.md: ac9bb445917e11a4b57280da513d36b0f434bbaf
+2026-08-08-api-remotes-generated-contract-build.zh.md: 4f9760078c209a22b9e03837fd81769e156b5df9
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
new file mode 100644
index 0000000000..ac9bb44591
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
@@ -0,0 +1,80 @@
+# Agent Note: Ordered Build for API Remotes Generated Contracts
+
+Status: implemented
+
+English | [中文](2026-08-08-api-remotes-generated-contract-build.zh.md)
+
+## Problem
+
+TypeRT must generate `/remote` declarations and runtime contributions from the Host's `@Remote` methods before the Client's `api-remotes/src/client/index.ts` can typecheck and bundle those contributions. If the root build hands both the Host and Client Project Reference graphs to tsc together, the Client compiles before the generated artifacts exist. Adding a separate contracts preprocessing step would instead compile the generator again outside the normal Host graph and let stale artifacts hide incorrect dependencies.
+
+This ordering dependency must not change the repository's ordinary package rule. A normal package belongs to exactly one TypeScript face: Host packages are registered in `tsconfig.host.json`, and Client packages in `tsconfig.client.json`. A Client plugin having both a Node loader entry and a browser entry describes its bundled artifact shapes, not a reason to split its TypeScript project.
+
+## Decision
+
+The root build completes Host tsc and Host tsdown first, with Host tsdown running TypeRT and generating the Remote Client contract. It then completes Client tsc, Client tsdown, and the Web build:
+
+~~~text
+tsc -b tsconfig.host.json
+tsdown --env.DSH_BUILD_FACE host
+tsc -b tsconfig.client.json
+tsdown --env.DSH_BUILD_FACE client
+Vite Web build
+~~~
+
+`build:lib:host` owns the first two steps, `build:lib:client` owns the middle two, and `build:web` runs last. `typecheck` must also run the complete Host lib phase first because Client tsc requires declarations generated by Host tsdown; it does not need Client tsdown or the Web build.
+
+Each tsc phase is the sole TypeScript compiler path and emits JavaScript, declarations, and incremental state to `lib/types`. Tsdown reads only that JavaScript and produces published bundles; it neither reads source nor emits declarations.
+
+## The sole package exception
+
+`api/remotes` is the only package with both Host and Client composite projects. The Host project contains the Agent/Session lookup policy, Host plugin entry, and invariant; the Client project contains only `src/client/index.ts`, which must wait for the generated contract:
+
+~~~text
+packages/api/remotes/
+├─ tsconfig.json
+├─ tsconfig.host.json
+├─ tsconfig.client.json
+└─ src/
+   ├─ index.ts
+   ├─ agent-lookup.ts
+   ├─ invariant.ts
+   └─ client/
+      └─ index.ts
+~~~
+
+The package-root `tsconfig.json` is a solution that only references the two concrete projects; it enters neither aggregate nor any direct consumer's dependency graph. The root Host aggregate and `host/apiproxy` reference `api/remotes/tsconfig.host.json`, while the root Client aggregate and `client/ui-goal` reference `api/remotes/tsconfig.client.json`. `ui-goal` itself remains an ordinary single Client project.
+
+The two projects use disjoint `files` and separate `.tsbuildinfo` files, so they can share `lib/types` without emitting any source file twice. If both sides later need a shared implementation, move that implementation into a neutral package instead of giving the same source to two emitting projects.
+
+This exception follows from the real generated-contract ordering and is not a template available to ordinary packages. New packages remain restricted to one aggregate; adding another exception requires changing this decision and proving another generated dependency that cannot be eliminated.
+
+## TypeRT and tsdown
+
+Host tsdown enables `typertPlugin({ mode: 'workspace', faces: ['host'] })` in the normal root config. The generator uses only `tsconfig.host.json` as its program seed and produces both `typert.host.*` and the `typert.remote-client.*` projection of Host contracts; Client tsdown neither starts TypeRT nor analyzes the Client aggregate.
+
+The TypeRT analyzer distinguishes compiler faces from runtime faces. Direct Project References in the aggregate determine which compiler face analyzes a project; only a split project explicitly referenced through `tsconfig.host.json` or `tsconfig.client.json` is restricted to that corresponding face. Runtime models follow package subpath contributions instead, so an ordinary single-project `dshClient` package may contribute both Host and Client runtime models.
+
+Both the Host and Client tsdown passes receive the same complete workspace of `vendor/*`, `packages/*/*`, and `apps/cli`. The root config does not scan `lib/types/client/index.js`, maintain a package classification table, or use a tsdown filter; package-local configs return entries for the current phase according to `DSH_BUILD_FACE`.
+
+An ordinary Client plugin returns an empty config during the Host pass and produces both its Node loader entry and browser bundle during the Client pass. The `clientBundle(..., { hostPhase: true })` used by `api-remotes` is the only phase exception: the Host pass produces its Host entry, and the Client pass produces only its browser bundle. Package-local tsdown without `DSH_BUILD_FACE` still returns that package's normal entries together for local single-package development.
+
+## Alternatives considered
+
+**Keep a separate contracts preprocessing step.** This would compile the generator again outside the normal Host Project Reference graph and let residual generated artifacts hide the Client entering the Host graph too early.
+
+**Run the root `tsc -b tsconfig.json` once before tsdown.** Client tsc would run before Host tsdown and could not obtain `/remote` declarations from a clean worktree.
+
+**Split every package containing `src/client/index.ts`.** Separate Node and browser entries are the normal Client plugin bundling convention and do not create a compilation ordering dependency; splitting them universally would only increase the maintenance cost of references and incremental state.
+
+**Scan Client compilation artifacts or maintain two workspace lists.** Artifact scanning would make package participation depend on residual files, while hand-maintained lists and package-name filters would drift as directories change. A complete workspace with package-local face selection already provides deterministic behavior.
+
+**Run TypeRT again during the Client pass.** Remote Client is a projection of the Host contract and has no independent Client reflection source; a second TypeRT program would only duplicate work and increase the risk of mixing both sides' declarations into one analysis.
+
+## Consequences
+
+A clean build is the authoritative check of ordering correctness: with no existing `/remote` artifacts, Host tsc must succeed first, Host tsdown must generate the contract, and then Client tsc, Client tsdown, and the Web build must succeed. No phase may write artifacts into `src`.
+
+The tsc-first ownership established by the [TypeScript build config note](2026-06-17-ts-build-config.md) remains unchanged, but this note replaces its command shape of one whole-graph tsc pass followed by bundling with ordered phases. The ordinary-package single-aggregate rule established by the [two-aggregate solution note](2026-07-22-tsconfig-solution-root-two-aggregates.md) also remains unchanged; this note creates one explicit exception for `api/remotes`.
+
+An independent Client build is no longer a self-contained entry on a clean worktree; repository commands, CI, and release flows must run the Host lib phase first. Developers of ordinary packages do not need to understand or copy this exception and continue to choose one aggregate according to the package's runtime environment.
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
new file mode 100644
index 0000000000..4f9760078c
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
@@ -0,0 +1,80 @@
+# Agent Note: API Remotes 生成契约的有序构建
+
+Status: implemented
+
+[English](2026-08-08-api-remotes-generated-contract-build.md) | 中文
+
+## 问题
+
+Host 的 `@Remote` 方法需要先由 TypeRT 生成 `/remote` 声明和运行时贡献，Client 的 `api-remotes/src/client/index.ts` 才能通过类型检查并打包这些贡献。若根构建先把 Host 与 Client 两张 Project Reference 图一起交给 tsc，Client 会在生成产物存在之前编译；若增加独立 contracts 预处理，又会让 generator 脱离正常 Host 图重复编译，并允许陈旧产物掩盖错误依赖。
+
+该顺序依赖不能改变仓库的普通 package 规则。正常 package 只属于一个 TypeScript face：Host package 登记在 `tsconfig.host.json`，Client package 登记在 `tsconfig.client.json`。一个 Client plugin 同时具有 Node loader 入口与 browser 入口，只是打包产物形态，不是拆分 TypeScript project 的理由。
+
+## 决策
+
+根构建先完成 Host tsc 和 Host tsdown，由 Host tsdown 运行 TypeRT 并生成 Remote Client 契约；随后完成 Client tsc、Client tsdown 和 Web 构建：
+
+~~~text
+tsc -b tsconfig.host.json
+tsdown --env.DSH_BUILD_FACE host
+tsc -b tsconfig.client.json
+tsdown --env.DSH_BUILD_FACE client
+Vite Web build
+~~~
+
+`build:lib:host` 负责前两步，`build:lib:client` 负责中间两步，`build:web` 最后运行。`typecheck` 也必须先执行完整 Host lib 阶段，因为 Client tsc 需要 Host tsdown 生成的声明；它不需要运行 Client tsdown 或 Web build。
+
+每个 tsc 阶段都是唯一的 TypeScript 编译器路径，负责向 `lib/types` 发射 JavaScript、声明和增量状态。tsdown 只读取这些 JavaScript 并生成发布 bundle，不读取源码，也不生成声明。
+
+## 唯一的 package 特例
+
+`api/remotes` 是唯一同时拥有 Host 与 Client composite project 的 package。Host project 包含 Agent/Session lookup 策略、Host 插件入口和 invariant；Client project 只包含需要等待生成契约的 `src/client/index.ts`：
+
+~~~text
+packages/api/remotes/
+├─ tsconfig.json
+├─ tsconfig.host.json
+├─ tsconfig.client.json
+└─ src/
+   ├─ index.ts
+   ├─ agent-lookup.ts
+   ├─ invariant.ts
+   └─ client/
+      └─ index.ts
+~~~
+
+包根 `tsconfig.json` 是只引用两个具体 project 的 solution，不进入任何 aggregate 或直接消费方的依赖图。根 Host aggregate 与 `host/apiproxy` 引用 `api/remotes/tsconfig.host.json`；根 Client aggregate 与 `client/ui-goal` 引用 `api/remotes/tsconfig.client.json`。`ui-goal` 本身仍是普通的单一 Client project。
+
+两个 project 使用互不重叠的 `files` 和不同的 `.tsbuildinfo`，因此可以共享 `lib/types` 而不重复发射任何源码。若未来需要两侧共用一份实现，应把实现移入中立 package，不能把同一源码同时交给两个 emitting project。
+
+这个例外由生成契约的真实先后关系决定，不是可供普通 package 选择的模板。新增 package 仍只能登记进一个 aggregate；只有修改本决策并证明存在另一条不可消除的生成依赖，才能增加例外。
+
+## TypeRT 与 tsdown
+
+Host tsdown 在普通根配置中启用 `typertPlugin({ mode: 'workspace', faces: ['host'] })`。generator 只以 `tsconfig.host.json` 为 program 种子，生成 `typert.host.*` 以及 Host 契约投影出的 `typert.remote-client.*`；Client tsdown 不启动 TypeRT，也不分析 Client aggregate。
+
+TypeScript compiler face 与 TypeRT 运行时产物 face 是两层概念。普通 `dshClient` package 即使只有一个 compiler project，也可以按公开 subpath 同时贡献 Host 与 Client 运行时模型；aggregate 显式引用 `tsconfig.host.json` 或 `tsconfig.client.json` 时，analyzer 才把该 project 限定到对应 face。因此 `api-remotes` 的 Host 分析不会顺带注册其 Client 入口，普通双入口 package 的 Host 模型也不会丢失。
+
+Host 与 Client 两次 tsdown 都接收 `vendor/*`、`packages/*/*` 和 `apps/cli` 这组完整 workspace。根配置不扫描 `lib/types/client/index.js`，不维护 package 分类表，也不使用 tsdown filter；包内配置根据 `DSH_BUILD_FACE` 返回本阶段入口。
+
+普通 Client plugin 在 Host pass 返回空配置，在 Client pass 同时生成 Node loader 入口与 browser bundle。`api-remotes` 的 `clientBundle(..., { hostPhase: true })` 是唯一阶段例外：Host pass 生成其 Host 入口，Client pass 只生成 browser bundle。未指定 `DSH_BUILD_FACE` 的 package-local tsdown 仍同时返回该 package 的正常入口，供本地单包开发使用。
+
+## 考虑过的替代方案
+
+**保留独立 contracts 预处理。** 这会在正常 Host Project Reference 图之外额外编译 generator，并让残留生成物掩盖 Client 过早进入 Host 图的问题。
+
+**一次执行根 `tsc -b tsconfig.json` 后再运行 tsdown。** Client tsc 在 Host tsdown 之前发生，无法从干净工作树获得 `/remote` 声明。
+
+**拆分所有包含 `src/client/index.ts` 的 package。** Node 与 browser 双入口是普通 Client plugin 的打包约定，不形成编译顺序依赖；普遍拆分只会增加 references 和增量状态的维护成本。
+
+**扫描 Client 编译产物或维护两份 workspace 清单。** 产物扫描会让 package 是否参与构建取决于残留文件，手工清单和 package 名过滤则会随目录调整产生漂移。完整 workspace 加包内 face 选择已经提供确定行为。
+
+**在 Client pass 再运行 TypeRT。** Remote Client 是 Host 契约的投影，没有独立 Client 反射源；第二个 TypeRT program 只会重复工作并增加两侧声明混入同一分析的风险。
+
+## 后果
+
+干净构建成为顺序正确性的权威验证：没有任何既存 `/remote` 产物时，Host tsc 必须先成功，Host tsdown 必须生成契约，随后 Client tsc、Client tsdown 与 Web build 必须成功。任何阶段都不得把产物写进 `src`。
+
+[TypeScript 构建配置 Note](2026-06-17-ts-build-config.md)确定的 tsc-first 职责保持不变，但其单次全图 tsc 后再打包的命令形态由本文的有序阶段取代。[双 aggregate solution Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)确定的普通 package 单 aggregate 规则保持不变，本文只为 `api/remotes` 建立一个显式例外。
+
+Client 的独立构建不再是干净工作树上的自足入口；仓库命令、CI 和发布流程必须先运行 Host lib 阶段。普通 package 的开发者无需理解或复制该例外，仍按所属运行环境选择一个 aggregate。
diff --git a/AGENTS.md b/AGENTS.md
index c265d3cf32..d77f5c5b16 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -109,7 +109,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string`.
 - **Trust TypeScript at typed same-process seams.** Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.
 - **Source plane vs artifact plane, never mixed.** Static gates and tests resolve workspace imports through tsconfig `paths` to `src` and pass on a clean tree; gates consuming built `lib/` declare that dependency ([layout](docs/development.md#typescript-project-layout)).
-- **`ts.Program` consumers seed `tsconfig.host.json` or `tsconfig.client.json`, never the root solution** — one program holding both sides collides the cordis `Context` merges ([layout](docs/development.md#typescript-project-layout)).
+- **Keep compiler faces explicit.** Each package uses one aggregate except `api/remotes`; repo-wide programs seed a face config, never the root solution ([layout](docs/development.md#typescript-project-layout)).
 - **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement.
 - **Prefer symmetry for parallel values**; unexplained asymmetry usually signals a missed extraction.
 - **Tests describe behavior, not correctness.** Change obsolete behavior with its tests; explain why in the PR.
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index 074644ff3e..6bf3151311 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.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 docs/api-gateway.md
-api-gateway.md: 33dfb30c9da25e46b660a3fa54ef37f587cbda08
-api-gateway.zh.md: 633eb10c0f2f065ecf27545813cc17d79f391865
+api-gateway.md: 7d5c5b7e46a66b2bf56ee1a1bbd57e7758a4c520
+api-gateway.zh.md: cbf62258b7bf4a1d2f657cf1fc08a8dbc0a1a939
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index 33dfb30c9d..7d5c5b7e46 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -94,7 +94,11 @@ The API Gateway package owns the Host dispatcher and Client Remote endpoint as p
 
 ## Strict generation pipeline
 
-The root build orders `build:lib:host`, `build:lib:client`, and `build:web`. The Host lib build first runs `build:lib:contracts`: it compiles the TypeRT generator, then starts a Host `ts.Program` through `tsdown.typert-host.config.ts` with `tsconfig.host.json` as its seed. The generator does not put the Host and Client aggregates in the same program, so it does not trigger conflicts between the two Cordis `Context` declaration merges.
+The root build runs `build:lib:host`, `build:lib:client`, and `build:web` in order. The Host lib phase first runs `tsc -b tsconfig.host.json`, then `tsdown --env.DSH_BUILD_FACE host`; the normal Host Project Reference graph compiles the TypeRT generator, which runs during this tsdown pass with the Host aggregate as its only `ts.Program` seed. The Client lib phase then runs `tsc -b tsconfig.client.json` and `tsdown --env.DSH_BUILD_FACE client`, consuming the newly generated Remote Client declarations and runtime contributions without starting TypeRT again.
+
+Both tsdown passes receive the complete workspace and bundle only JavaScript emitted to `lib/types` by the corresponding tsc phase. The root config does not scan Client artifacts, classify package names, or pass a maintained filter to tsdown; package-local configs return entries for the current phase based on `DSH_BUILD_FACE`. An ordinary Client plugin produces both its Node loader entry and browser bundle during the Client phase.
+
+`api-remotes` is the only package with split TypeScript faces. Its Host project owns the Agent/Session lookup policy, while its Client project depends on `/remote` declarations generated for business packages during Host tsdown; root aggregates and direct consumers must reference `api/remotes/tsconfig.host.json` or `api/remotes/tsconfig.client.json` respectively. The package's `clientBundle(..., { hostPhase: true })` produces its Host entry during Host tsdown and leaves only the browser entry for Client tsdown. Every other package remains registered in one aggregate.
 
 Each contributing business package writes generated files to its own `lib/` directory, not to its source directory:
 
@@ -149,13 +153,13 @@ pnpm run dev:web
 
 `dsh` starts the Host source through tsx, so the Host can use the SRC fallback; `dev:web` watches only Client plugins with a `dshClient` declaration and rewrites their `lib/client.js`. It does not analyze Host decorators or generate Remote Client DTS.
 
-Changing only a Remote method's implementation body without changing its contract does not require regenerating the TypeRT files. After adding or removing a decorator or changing an export name, namespace, parameter, return value, lookup, Context, or cancellation signature, regenerate the strict contracts before the Client bundle consumes the new artifacts:
+Changing only a Remote method's implementation body without changing its contract does not require regenerating the TypeRT files. After adding or removing a decorator or changing an export name, namespace, parameter, return value, lookup, Context, or cancellation signature, rerun the ordered lib build so the Host generates the strict contract before the Client compiles and bundles the new contribution:
 
 ```sh
-pnpm run build:lib:contracts
+pnpm run build:lib
 ```
 
-The running Client watcher consumes these generated files when it rebundles; without a watcher, run `pnpm run build:lib:client`. Recompiling only the frontend source cannot infer new types from Host decorators. `pnpm run typecheck` includes `build:lib:contracts` as a prerequisite, and CI and release builds also use the strict generation pipeline.
+The running Client watcher consumes these generated files when it rebundles. If `pnpm run build:lib:host` has already refreshed the Host contract, `pnpm run build:lib:client` can complete the Client side; a clean worktree cannot skip the Host phase. Recompiling only the frontend source cannot infer new types from Host decorators. `pnpm run typecheck` runs the Host lib phase before Client tsc, and CI and release builds use the same order.
 
 ## Boundaries
 
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 633eb10c0f..cbf62258b7 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -94,7 +94,11 @@ API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对
 
 ## 严格生成链路
 
-根构建按 `build:lib:host`、`build:lib:client`、`build:web` 排序。Host lib 构建首先运行 `build:lib:contracts`：它先编译 TypeRT generator，再通过 `tsdown.typert-host.config.ts` 以 `tsconfig.host.json` 为种子启动 Host `ts.Program`。生成器不会把 Host 与 Client 聚合放入同一个 program，因而不会触发两侧 Cordis `Context` 声明合并冲突。
+根构建依次执行 `build:lib:host`、`build:lib:client` 与 `build:web`。Host lib 阶段先运行 `tsc -b tsconfig.host.json`，再运行 `tsdown --env.DSH_BUILD_FACE host`；TypeRT generator 由正常 Host Project Reference 图编译，并在这次 tsdown 中以 Host aggregate 为唯一 `ts.Program` 种子运行。Client lib 阶段随后运行 `tsc -b tsconfig.client.json` 与 `tsdown --env.DSH_BUILD_FACE client`，使用刚生成的 Remote Client 声明和运行时贡献，但不再次启动 TypeRT。
+
+两次 tsdown 都接收完整 workspace，且都只打包 `lib/types` 中由对应 tsc 阶段发射的 JavaScript。根配置不扫描 Client 产物、不按 package 名分类，也不向 tsdown 传维护式 filter；各包的本地配置根据 `DSH_BUILD_FACE` 返回当前阶段的入口。普通 Client plugin 在 Client 阶段一起生成 Node loader 入口与 browser bundle。
+
+`api-remotes` 是唯一拆分 TypeScript face 的 package 特例。它的 Host project 负责 Agent/Session lookup 策略，Client project 则依赖业务包在 Host tsdown 中生成的 `/remote` 声明；根 aggregate 与直接消费方必须分别引用 `api/remotes/tsconfig.host.json` 或 `api/remotes/tsconfig.client.json`。包内 `clientBundle(..., { hostPhase: true })` 让 Host 入口在 Host tsdown 中生成，让 Client tsdown 只生成 browser 入口。其他 package 仍只登记在一个 aggregate 中。
 
 每个贡献业务包把生成文件写入自己的 `lib/`，而不是源码目录：
 
@@ -149,13 +153,13 @@ pnpm run dev:web
 
 `dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 只监听带 `dshClient` 声明的 Client plugin 并重写其 `lib/client.js`，它不会分析 Host decorator，也不会生成 Remote Client DTS。
 
-只修改 Remote 方法实现体而不改变契约时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，先重新生成严格契约，再让 Client bundle 使用新的产物：
+只修改 Remote 方法实现体而不改变契约时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格契约，再让 Client 编译并打包新的贡献：
 
 ```sh
-pnpm run build:lib:contracts
+pnpm run build:lib
 ```
 
-运行中的 Client watcher 会在重新打包时消费这些生成文件；没有 watcher 时运行 `pnpm run build:lib:client`。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 自带 `build:lib:contracts` 前置步骤，CI 与发布构建也使用严格生成链路。
+运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 契约，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净工作树不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
 
 ## 边界
 
diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml
index 85c1af757b..0c26b8be17 100644
--- a/docs/cookbook/adding-a-package.i18n.yaml
+++ b/docs/cookbook/adding-a-package.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-package.md
-adding-a-package.md: a45b222f6aed905a18ef9b480c989e6045029afe
-adding-a-package.zh.md: af0e4d0779fa99ce43ebccba00c33eab16c4d362
+adding-a-package.md: 8ab603ea7b235bd2a582c9232afaca281a969448
+adding-a-package.zh.md: 8c0bc9dbd02b18a388f8e6ce91af10753c0210a2
diff --git a/docs/cookbook/adding-a-package.md b/docs/cookbook/adding-a-package.md
index a45b222f6a..8ab603ea7b 100644
--- a/docs/cookbook/adding-a-package.md
+++ b/docs/cookbook/adding-a-package.md
@@ -31,7 +31,7 @@ In-package relative imports use explicit `.ts` specifiers in source (for example
 | File | Change |
 |---|---|
 | `tsconfig.base.json` | no edit for an existing group; for a new group, add a `./packages/<group>/*/src` candidate to the `@deepseek-ai/dsh-*` wildcard |
-| `tsconfig.host.json` (host-side package) or `tsconfig.client.json` (client-side package) | add `{ "path": "./packages/<group>/<pkg>" }` to `references` — exactly one aggregate, never both ([layout](../development.md#typescript-project-layout)) |
+| `tsconfig.host.json` (Host package) or `tsconfig.client.json` (Client package) | add `{ "path": "./packages/<group>/<pkg>" }` to `references` — an ordinary package belongs to exactly one aggregate, never both. `api/remotes` uses a repository-specific split because the Host generates a contract that the Client consumes in a later phase; new packages must not copy it ([layout](../development.md#typescript-project-layout)) |
 | `knip.json` | only if the package has entrypoints that repository discovery does not already cover |
 
 A `packages/client/*` package additionally extends `tsconfig.base.client.json` instead of `tsconfig.base.json`, and a client plugin package declares `dshClient` in package.json, exports `./client`, and calls the shared tsdown preset (`packages/client/tsdown.client.ts`) — see [packages/client/AGENTS.md](../../packages/client/AGENTS.md) for the client-side contract.
diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md
index af0e4d0779..8c0bc9dbd0 100644
--- a/docs/cookbook/adding-a-package.zh.md
+++ b/docs/cookbook/adding-a-package.zh.md
@@ -31,7 +31,7 @@ package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-c
 | 文件 | 变更 |
 |---|---|
 | `tsconfig.base.json` | 已有分组无需编辑；新分组需为 `@deepseek-ai/dsh-*` 通配符添加 `./packages/<group>/*/src` 候选路径 |
-| `tsconfig.host.json`（host 侧包）或 `tsconfig.client.json`（client 侧包） | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }`——恰好一个聚合，绝不两个都加（[布局](../development.md#typescript-project-layout)） |
+| `tsconfig.host.json`（Host 包）或 `tsconfig.client.json`（Client 包） | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }`——普通包恰好属于一个 aggregate，绝不两个都加。`api/remotes` 因 Host 生成契约与 Client 消费契约之间存在顺序依赖而使用仓库专属拆分，新增包不得仿照（[布局](../development.md#typescript-project-layout)） |
 | `knip.json` | 仅当包有仓库发现机制尚未覆盖的入口时需要 |
 
 `packages/client/*` 包改为 extends `tsconfig.base.client.json`（而非 `tsconfig.base.json`）；client 插件包还需在 package.json 声明 `dshClient`、导出 `./client`、调用共享 tsdown preset（`packages/client/tsdown.client.ts`）——client 侧见 [packages/client/AGENTS.md](../../packages/client/AGENTS.md)。
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index b66552b175..5a1024e657 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: b7ecab3536d739c105f11a640a07ea83a22f4398
-development.zh.md: 33ceba9f05c45c06acae7c83425a30c5e26ca433
+development.md: acf279d182ca580c6e372be6fbdca8f46afdc445
+development.zh.md: 927c72be2de78f9e7f67565b9524db85c5aa1669
diff --git a/docs/development.md b/docs/development.md
index b7ecab3536..acf279d182 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -43,24 +43,39 @@ Setup is complete when `pnpm run typecheck` exits successfully.
 
 ### TypeScript project layout
 
-The repository typecheck runs the whole-repo `tsc -b` graph: it emits every package/vendor `lib/types` and checks examples, tests, and scripts through two no-emit aggregates.
-
-The repository's TypeScript configuration has exactly three roles; every tsconfig file plays one of them.
+The repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.
 
 | File | Role | Forms a program? |
 |---|---|---|
-| `tsconfig.json` | Solution root: `extends` base, `files: []`, references to the two aggregates. The whole-repo `tsc -b tsconfig.json` graph, the tsserver discovery entry, and — through the inherited `paths` — the resolution config for tsx running `examples/` and `scripts/` (their nearest tsconfig is this file). | No |
-| `tsconfig.host.json` | Host aggregate: host-side packages (via references), examples, tests, scripts, website. Excludes `packages/client`. | Yes |
-| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`. | Yes |
+| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |
+| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |
+| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |
 | `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |
-| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the client aggregate and every `packages/client/*` package. | No |
+| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |
 
-Host and client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Two disciplines follow:
+Host and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:
 
 - `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.
-- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges. Program-backed generators and gates (`scripts/ts-project.ts` consumers, doc-typecheck standalone mode) are host-only by decision; the client side gains program-backed tooling only with a concrete need.
+- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.
+- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.
 
-Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).
+`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.
+
+The root build follows the generated dependency order:
+
+```sh
+tsc -b tsconfig.host.json
+tsdown --env.DSH_BUILD_FACE host
+tsc -b tsconfig.client.json
+tsdown --env.DSH_BUILD_FACE client
+pnpm run build:web
+```
+
+Both tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.
+
+TypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.
+
+Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology and the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership.
 
 Business services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 33ceba9f05..927c72be2d 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -43,24 +43,39 @@ pnpm run typecheck
 
 ### TypeScript 项目布局
 
-仓库类型检查会执行全仓 `tsc -b` 图：它会发射每个 package/vendor 的 `lib/types`，并通过两个 no-emit 聚合检查示例、测试和脚本。
-
-仓库的 TypeScript 配置只有三种角色；每个 tsconfig 文件恰好扮演其中一种。
+仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。
 
 | 文件 | 角色 | 是否构成 program？ |
 |---|---|---|
-| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个聚合。全仓 `tsc -b tsconfig.json` 图、tsserver 发现入口，并经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置（它们最近的 tsconfig 就是此文件）。 | 否 |
-| `tsconfig.host.json` | host 聚合：host 侧各包（经 references）、示例、测试、脚本、website。排除 `packages/client`。 | 是 |
-| `tsconfig.client.json` | client 聚合：`packages/client/*` 各包及其测试、`apps/web`。 | 是 |
+| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |
+| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |
+| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |
 | `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |
-| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 client 聚合和每个 `packages/client/*` 包 extends。 | 否 |
+| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |
 
-host 与 client 保持两个聚合 program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个聚合，一个 paths 门面也可以横跨两侧。由此推出两条纪律：
+Host 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：
 
 - `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。
-- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个聚合展平进一个 program 会撞上 `Context` 合并冲突。基于 program 的生成器与门禁（`scripts/ts-project.ts` 的消费者、doc-typecheck standalone 模式）按决策仅覆盖 host 侧；client 侧只在出现真实需求时再获得基于 program 的工具。
+- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。
+- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。
 
-静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。
+`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。
+
+根构建按生成依赖排序：
+
+```sh
+tsc -b tsconfig.host.json
+tsdown --env.DSH_BUILD_FACE host
+tsc -b tsconfig.client.json
+tsdown --env.DSH_BUILD_FACE client
+pnpm run build:web
+```
+
+两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。
+
+TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
+
+静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。
 
 业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
 
diff --git a/docs/module-graph.md b/docs/module-graph.md
index d963273363..ab9fc97a71 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -328,6 +328,9 @@ flowchart TD
   pkg_client_hmr --> pkg_client_modules
   pkg_client_hmr --> pkg_host_webserver
   pkg_client_hmr --> pkg_invariants
+  pkg_client_runtime --> pkg_invariants
+  pkg_client_runtime --> pkg_type_meta
+  pkg_client_runtime --> pkg_typert_registry
   pkg_credentials --> pkg_brand
   pkg_credentials --> pkg_invariants
   pkg_frontend_static --> pkg_host_webserver
@@ -376,6 +379,29 @@ flowchart TD
   pkg_api_gateway --> pkg_client_connection
   pkg_api_gateway --> pkg_invariants
   pkg_api_gateway --> pkg_typert_registry
+  pkg_client_locale --> pkg_client_runtime
+  pkg_client_locale --> pkg_client_ui_primitives
+  pkg_client_locale --> pkg_client_ui_slots
+  pkg_client_locale --> pkg_invariants
+  pkg_client_test_runtime --> pkg_client_runtime
+  pkg_client_test_runtime --> pkg_client_ui_slots
+  pkg_client_test_runtime --> pkg_client_web_react
+  pkg_client_test_runtime --> pkg_host_apiproxy
+  pkg_client_test_runtime --> pkg_invariants
+  pkg_client_ui_models --> pkg_client_connection
+  pkg_client_ui_models --> pkg_client_runtime
+  pkg_client_ui_models --> pkg_client_schema_form
+  pkg_client_ui_models --> pkg_client_ui_primitives
+  pkg_client_ui_models --> pkg_client_ui_slots
+  pkg_client_ui_models --> pkg_client_web_react
+  pkg_client_ui_models --> pkg_invariants
+  pkg_client_ui_settings --> pkg_client_runtime
+  pkg_client_ui_settings --> pkg_client_ui_primitives
+  pkg_client_ui_settings --> pkg_client_ui_slots
+  pkg_client_ui_settings --> pkg_invariants
+  pkg_client_ui_trajectory --> pkg_client_runtime
+  pkg_client_ui_trajectory --> pkg_client_ui_primitives
+  pkg_client_ui_trajectory --> pkg_invariants
   pkg_credentials_local --> pkg_atomic_write
   pkg_credentials_local --> pkg_credentials
   pkg_credentials_local --> pkg_environment
@@ -426,6 +452,36 @@ flowchart TD
   pkg_app_boot --> pkg_invariants
   pkg_app_boot --> pkg_paths
   pkg_app_boot --> pkg_system_prompt
+  pkg_client_ui_question --> pkg_client_locale
+  pkg_client_ui_question --> pkg_invariants
+  pkg_client_ui_settings_general --> pkg_client_connection
+  pkg_client_ui_settings_general --> pkg_client_locale
+  pkg_client_ui_settings_general --> pkg_client_runtime
+  pkg_client_ui_settings_general --> pkg_client_ui_primitives
+  pkg_client_ui_settings_general --> pkg_client_ui_settings
+  pkg_client_ui_settings_general --> pkg_client_ui_slots
+  pkg_client_ui_settings_general --> pkg_client_web_react
+  pkg_client_ui_settings_general --> pkg_invariants
+  pkg_client_ui_sidebar --> pkg_client_locale
+  pkg_client_ui_sidebar --> pkg_client_runtime
+  pkg_client_ui_sidebar --> pkg_client_ui_primitives
+  pkg_client_ui_sidebar --> pkg_client_ui_slots
+  pkg_client_ui_sidebar --> pkg_invariants
+  pkg_client_ui_slash --> pkg_client_locale
+  pkg_client_ui_slash --> pkg_client_runtime
+  pkg_client_ui_slash --> pkg_client_ui_primitives
+  pkg_client_ui_slash --> pkg_client_ui_slots
+  pkg_client_ui_slash --> pkg_invariants
+  pkg_client_ui_theme --> pkg_client_locale
+  pkg_client_ui_theme --> pkg_client_runtime
+  pkg_client_ui_theme --> pkg_client_ui_primitives
+  pkg_client_ui_theme --> pkg_client_ui_slots
+  pkg_client_ui_theme --> pkg_invariants
+  pkg_client_ui_workspace --> pkg_client_locale
+  pkg_client_ui_workspace --> pkg_client_runtime
+  pkg_client_ui_workspace --> pkg_client_ui_primitives
+  pkg_client_ui_workspace --> pkg_client_ui_slots
+  pkg_client_ui_workspace --> pkg_invariants
   pkg_code_runtime_worker --> pkg_code_runtime
   pkg_code_runtime_worker --> pkg_invariants
   pkg_code_runtime_worker --> pkg_session
@@ -521,6 +577,10 @@ flowchart TD
   pkg_headless --> pkg_host_webserver
   pkg_headless --> pkg_invariants
   pkg_headless --> pkg_session
+  pkg_client_ui_layout --> pkg_client_runtime
+  pkg_client_ui_layout --> pkg_client_ui_slots
+  pkg_client_ui_layout --> pkg_client_ui_theme
+  pkg_client_ui_layout --> pkg_invariants
   pkg_time_context --> pkg_agent
   pkg_time_context --> pkg_invariants
   pkg_time_context --> pkg_session
@@ -528,6 +588,16 @@ flowchart TD
   pkg_tmux_context --> pkg_bash
   pkg_tmux_context --> pkg_invariants
   pkg_tmux_context --> pkg_session
+  pkg_host_directory_picker_browse --> pkg_client_locale
+  pkg_host_directory_picker_browse --> pkg_client_runtime
+  pkg_host_directory_picker_browse --> pkg_client_ui_primitives
+  pkg_host_directory_picker_browse --> pkg_client_ui_slots
+  pkg_host_directory_picker_browse --> pkg_client_ui_workspace
+  pkg_host_directory_picker_browse --> pkg_invariants
+  pkg_host_directory_picker_native --> pkg_client_runtime
+  pkg_host_directory_picker_native --> pkg_client_ui_slots
+  pkg_host_directory_picker_native --> pkg_client_ui_workspace
+  pkg_host_directory_picker_native --> pkg_invariants
   pkg_pty --> pkg_agent
   pkg_pty --> pkg_brand
   pkg_pty --> pkg_invariants
@@ -625,9 +695,20 @@ flowchart TD
   pkg_api_remotes --> pkg_session
   pkg_api_remotes --> pkg_session_persistence
   pkg_api_remotes --> pkg_typert_registry
+  pkg_client_ui_conversation --> pkg_client_locale
+  pkg_client_ui_conversation --> pkg_client_runtime
+  pkg_client_ui_conversation --> pkg_client_ui_primitives
+  pkg_client_ui_conversation --> pkg_client_ui_slash
+  pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_token_meter
   pkg_command_feedback --> pkg_commands
   pkg_command_feedback --> pkg_invariants
   pkg_command_feedback --> pkg_session
+  pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse
+  pkg_host_directory_picker_auto --> pkg_host_directory_picker_native
+  pkg_host_directory_picker_auto --> pkg_host_webserver
+  pkg_host_directory_picker_auto --> pkg_invariants
   pkg_pty_local --> pkg_agent
   pkg_pty_local --> pkg_invariants
   pkg_pty_local --> pkg_pty
@@ -781,10 +862,35 @@ flowchart TD
   pkg_tool_ask_user --> pkg_invariants
   pkg_tool_ask_user --> pkg_tools
   pkg_tool_ask_user --> pkg_user_interaction
-  pkg_client_runtime --> pkg_api_remotes
-  pkg_client_runtime --> pkg_invariants
-  pkg_client_runtime --> pkg_type_meta
-  pkg_client_runtime --> pkg_typert_registry
+  pkg_client_ui_command --> pkg_client_connection
+  pkg_client_ui_command --> pkg_client_locale
+  pkg_client_ui_command --> pkg_client_runtime
+  pkg_client_ui_command --> pkg_client_ui_conversation
+  pkg_client_ui_command --> pkg_client_ui_primitives
+  pkg_client_ui_command --> pkg_client_ui_slash
+  pkg_client_ui_command --> pkg_client_ui_slots
+  pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_deliverables --> pkg_client_locale
+  pkg_client_ui_deliverables --> pkg_client_runtime
+  pkg_client_ui_deliverables --> pkg_client_ui_conversation
+  pkg_client_ui_deliverables --> pkg_client_ui_slots
+  pkg_client_ui_deliverables --> pkg_invariants
+  pkg_client_ui_goal --> pkg_api_remotes
+  pkg_client_ui_goal --> pkg_client_locale
+  pkg_client_ui_goal --> pkg_client_runtime
+  pkg_client_ui_goal --> pkg_client_ui_conversation
+  pkg_client_ui_goal --> pkg_client_ui_primitives
+  pkg_client_ui_goal --> pkg_client_ui_slots
+  pkg_client_ui_goal --> pkg_goal
+  pkg_client_ui_goal --> pkg_invariants
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_locale
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_conversation
+  pkg_client_ui_skill --> pkg_client_ui_primitives
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_invariants
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compact
   pkg_session_reference --> pkg_invariants
@@ -916,29 +1022,42 @@ flowchart TD
   pkg_web_app --> pkg_bash_env
   pkg_web_app --> pkg_invariants
   pkg_web_app --> pkg_system_prompt
-  pkg_client_locale --> pkg_client_runtime
-  pkg_client_locale --> pkg_client_ui_primitives
-  pkg_client_locale --> pkg_client_ui_slots
-  pkg_client_locale --> pkg_invariants
-  pkg_client_test_runtime --> pkg_client_runtime
-  pkg_client_test_runtime --> pkg_client_ui_slots
-  pkg_client_test_runtime --> pkg_client_web_react
-  pkg_client_test_runtime --> pkg_host_apiproxy
-  pkg_client_test_runtime --> pkg_invariants
-  pkg_client_ui_models --> pkg_client_connection
-  pkg_client_ui_models --> pkg_client_runtime
-  pkg_client_ui_models --> pkg_client_schema_form
-  pkg_client_ui_models --> pkg_client_ui_primitives
-  pkg_client_ui_models --> pkg_client_ui_slots
-  pkg_client_ui_models --> pkg_client_web_react
-  pkg_client_ui_models --> pkg_invariants
-  pkg_client_ui_settings --> pkg_client_runtime
-  pkg_client_ui_settings --> pkg_client_ui_primitives
-  pkg_client_ui_settings --> pkg_client_ui_slots
-  pkg_client_ui_settings --> pkg_invariants
-  pkg_client_ui_trajectory --> pkg_client_runtime
-  pkg_client_ui_trajectory --> pkg_client_ui_primitives
-  pkg_client_ui_trajectory --> pkg_invariants
+  pkg_client_ui_model --> pkg_client_connection
+  pkg_client_ui_model --> pkg_client_locale
+  pkg_client_ui_model --> pkg_client_runtime
+  pkg_client_ui_model --> pkg_client_ui_command
+  pkg_client_ui_model --> pkg_client_ui_conversation
+  pkg_client_ui_model --> pkg_client_ui_primitives
+  pkg_client_ui_model --> pkg_client_ui_slash
+  pkg_client_ui_model --> pkg_client_ui_slots
+  pkg_client_ui_model --> pkg_invariants
+  pkg_client_ui_permission --> pkg_client_connection
+  pkg_client_ui_permission --> pkg_client_locale
+  pkg_client_ui_permission --> pkg_client_runtime
+  pkg_client_ui_permission --> pkg_client_schema_form
+  pkg_client_ui_permission --> pkg_client_ui_command
+  pkg_client_ui_permission --> pkg_client_ui_primitives
+  pkg_client_ui_permission --> pkg_client_ui_slash
+  pkg_client_ui_permission --> pkg_client_ui_slots
+  pkg_client_ui_permission --> pkg_invariants
+  pkg_client_ui_permission --> pkg_permission
+  pkg_client_ui_plan --> pkg_client_connection
+  pkg_client_ui_plan --> pkg_client_locale
+  pkg_client_ui_plan --> pkg_client_runtime
+  pkg_client_ui_plan --> pkg_client_ui_conversation
+  pkg_client_ui_plan --> pkg_client_ui_primitives
+  pkg_client_ui_plan --> pkg_client_ui_slots
+  pkg_client_ui_plan --> pkg_invariants
+  pkg_client_ui_plan --> pkg_plan_mode
+  pkg_client_ui_subagent --> pkg_client_locale
+  pkg_client_ui_subagent --> pkg_client_runtime
+  pkg_client_ui_subagent --> pkg_client_ui_conversation
+  pkg_client_ui_subagent --> pkg_client_ui_primitives
+  pkg_client_ui_subagent --> pkg_client_ui_slash
+  pkg_client_ui_subagent --> pkg_client_ui_slots
+  pkg_client_ui_subagent --> pkg_invariants
+  pkg_client_ui_subagent --> pkg_subagent
+  pkg_client_ui_subagent --> pkg_token_meter
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -981,36 +1100,6 @@ flowchart TD
   pkg_jsonrpc --> pkg_sdk_protocol
   pkg_jsonrpc --> pkg_session
   pkg_jsonrpc --> pkg_subagent
-  pkg_client_ui_question --> pkg_client_locale
-  pkg_client_ui_question --> pkg_invariants
-  pkg_client_ui_settings_general --> pkg_client_connection
-  pkg_client_ui_settings_general --> pkg_client_locale
-  pkg_client_ui_settings_general --> pkg_client_runtime
-  pkg_client_ui_settings_general --> pkg_client_ui_primitives
-  pkg_client_ui_settings_general --> pkg_client_ui_settings
-  pkg_client_ui_settings_general --> pkg_client_ui_slots
-  pkg_client_ui_settings_general --> pkg_client_web_react
-  pkg_client_ui_settings_general --> pkg_invariants
-  pkg_client_ui_sidebar --> pkg_client_locale
-  pkg_client_ui_sidebar --> pkg_client_runtime
-  pkg_client_ui_sidebar --> pkg_client_ui_primitives
-  pkg_client_ui_sidebar --> pkg_client_ui_slots
-  pkg_client_ui_sidebar --> pkg_invariants
-  pkg_client_ui_slash --> pkg_client_locale
-  pkg_client_ui_slash --> pkg_client_runtime
-  pkg_client_ui_slash --> pkg_client_ui_primitives
-  pkg_client_ui_slash --> pkg_client_ui_slots
-  pkg_client_ui_slash --> pkg_invariants
-  pkg_client_ui_theme --> pkg_client_locale
-  pkg_client_ui_theme --> pkg_client_runtime
-  pkg_client_ui_theme --> pkg_client_ui_primitives
-  pkg_client_ui_theme --> pkg_client_ui_slots
-  pkg_client_ui_theme --> pkg_invariants
-  pkg_client_ui_workspace --> pkg_client_locale
-  pkg_client_ui_workspace --> pkg_client_runtime
-  pkg_client_ui_workspace --> pkg_client_ui_primitives
-  pkg_client_ui_workspace --> pkg_client_ui_slots
-  pkg_client_ui_workspace --> pkg_invariants
   pkg_agent_spine_demo --> pkg_agent
   pkg_agent_spine_demo --> pkg_agent_loop
   pkg_agent_spine_demo --> pkg_bash_env
@@ -1044,17 +1133,6 @@ flowchart TD
   pkg_subagent_dsh_sdk --> pkg_session
   pkg_subagent_dsh_sdk --> pkg_subagent
   pkg_subagent_dsh_sdk --> pkg_subprocess
-  pkg_client_ui_conversation --> pkg_client_locale
-  pkg_client_ui_conversation --> pkg_client_runtime
-  pkg_client_ui_conversation --> pkg_client_ui_primitives
-  pkg_client_ui_conversation --> pkg_client_ui_slash
-  pkg_client_ui_conversation --> pkg_client_ui_slots
-  pkg_client_ui_conversation --> pkg_invariants
-  pkg_client_ui_conversation --> pkg_token_meter
-  pkg_client_ui_layout --> pkg_client_runtime
-  pkg_client_ui_layout --> pkg_client_ui_slots
-  pkg_client_ui_layout --> pkg_client_ui_theme
-  pkg_client_ui_layout --> pkg_invariants
   pkg_acp_demo --> pkg_acp
   pkg_acp_demo --> pkg_agent_spine_demo
   pkg_acp_demo --> pkg_app_boot
@@ -1075,85 +1153,6 @@ flowchart TD
   pkg_cli_demo --> pkg_session_persistence_jsonl
   pkg_cli_demo --> pkg_tools
   pkg_cli_demo --> pkg_workspace_context
-  pkg_host_directory_picker_browse --> pkg_client_locale
-  pkg_host_directory_picker_browse --> pkg_client_runtime
-  pkg_host_directory_picker_browse --> pkg_client_ui_primitives
-  pkg_host_directory_picker_browse --> pkg_client_ui_slots
-  pkg_host_directory_picker_browse --> pkg_client_ui_workspace
-  pkg_host_directory_picker_browse --> pkg_invariants
-  pkg_host_directory_picker_native --> pkg_client_runtime
-  pkg_host_directory_picker_native --> pkg_client_ui_slots
-  pkg_host_directory_picker_native --> pkg_client_ui_workspace
-  pkg_host_directory_picker_native --> pkg_invariants
-  pkg_client_ui_command --> pkg_client_connection
-  pkg_client_ui_command --> pkg_client_locale
-  pkg_client_ui_command --> pkg_client_runtime
-  pkg_client_ui_command --> pkg_client_ui_conversation
-  pkg_client_ui_command --> pkg_client_ui_primitives
-  pkg_client_ui_command --> pkg_client_ui_slash
-  pkg_client_ui_command --> pkg_client_ui_slots
-  pkg_client_ui_command --> pkg_invariants
-  pkg_client_ui_deliverables --> pkg_client_locale
-  pkg_client_ui_deliverables --> pkg_client_runtime
-  pkg_client_ui_deliverables --> pkg_client_ui_conversation
-  pkg_client_ui_deliverables --> pkg_client_ui_slots
-  pkg_client_ui_deliverables --> pkg_invariants
-  pkg_client_ui_goal --> pkg_api_remotes
-  pkg_client_ui_goal --> pkg_client_locale
-  pkg_client_ui_goal --> pkg_client_runtime
-  pkg_client_ui_goal --> pkg_client_ui_conversation
-  pkg_client_ui_goal --> pkg_client_ui_primitives
-  pkg_client_ui_goal --> pkg_client_ui_slots
-  pkg_client_ui_goal --> pkg_goal
-  pkg_client_ui_goal --> pkg_invariants
-  pkg_client_ui_plan --> pkg_client_connection
-  pkg_client_ui_plan --> pkg_client_locale
-  pkg_client_ui_plan --> pkg_client_runtime
-  pkg_client_ui_plan --> pkg_client_ui_conversation
-  pkg_client_ui_plan --> pkg_client_ui_primitives
-  pkg_client_ui_plan --> pkg_client_ui_slots
-  pkg_client_ui_plan --> pkg_invariants
-  pkg_client_ui_plan --> pkg_plan_mode
-  pkg_client_ui_skill --> pkg_client_connection
-  pkg_client_ui_skill --> pkg_client_locale
-  pkg_client_ui_skill --> pkg_client_runtime
-  pkg_client_ui_skill --> pkg_client_ui_conversation
-  pkg_client_ui_skill --> pkg_client_ui_primitives
-  pkg_client_ui_skill --> pkg_client_ui_slash
-  pkg_client_ui_skill --> pkg_client_ui_slots
-  pkg_client_ui_skill --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_client_locale
-  pkg_client_ui_subagent --> pkg_client_runtime
-  pkg_client_ui_subagent --> pkg_client_ui_conversation
-  pkg_client_ui_subagent --> pkg_client_ui_primitives
-  pkg_client_ui_subagent --> pkg_client_ui_slash
-  pkg_client_ui_subagent --> pkg_client_ui_slots
-  pkg_client_ui_subagent --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_subagent
-  pkg_client_ui_subagent --> pkg_token_meter
-  pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse
-  pkg_host_directory_picker_auto --> pkg_host_directory_picker_native
-  pkg_host_directory_picker_auto --> pkg_host_webserver
-  pkg_host_directory_picker_auto --> pkg_invariants
-  pkg_client_ui_model --> pkg_client_connection
-  pkg_client_ui_model --> pkg_client_locale
-  pkg_client_ui_model --> pkg_client_runtime
-  pkg_client_ui_model --> pkg_client_ui_command
-  pkg_client_ui_model --> pkg_client_ui_conversation
-  pkg_client_ui_model --> pkg_client_ui_primitives
-  pkg_client_ui_model --> pkg_client_ui_slash
-  pkg_client_ui_model --> pkg_client_ui_slots
-  pkg_client_ui_model --> pkg_invariants
-  pkg_client_ui_permission --> pkg_client_connection
-  pkg_client_ui_permission --> pkg_client_locale
-  pkg_client_ui_permission --> pkg_client_runtime
-  pkg_client_ui_permission --> pkg_client_schema_form
-  pkg_client_ui_permission --> pkg_client_ui_command
-  pkg_client_ui_permission --> pkg_client_ui_primitives
-  pkg_client_ui_permission --> pkg_client_ui_slash
-  pkg_client_ui_permission --> pkg_client_ui_slots
-  pkg_client_ui_permission --> pkg_invariants
-  pkg_client_ui_permission --> pkg_permission
 ```
 
 | Package | Group | Depends on |
@@ -1191,6 +1190,7 @@ flowchart TD
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout) |
 | [`client-connection`](../packages/client/connection) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`client-runtime`](../packages/client/runtime) | `client` | [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
@@ -1207,6 +1207,11 @@ flowchart TD
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
+| [`client-locale`](../packages/client/locale) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-test-runtime`](../packages/client/test-runtime) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/support/invariants) |
+| [`client-ui-models`](../packages/client/ui-models) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
+| [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`invariants`](../packages/support/invariants) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
@@ -1221,6 +1226,12 @@ flowchart TD
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
+| [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |
+| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
+| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
@@ -1244,8 +1255,11 @@ flowchart TD
 | [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants) |
@@ -1266,7 +1280,9 @@ flowchart TD
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
 | [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/ui/user-approval) |
 | [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`typert-registry`](../packages/typert/registry) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -1292,7 +1308,10 @@ flowchart TD
 | [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`session-title-llm`](../packages/session-title/session-title-llm) |
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
-| [`client-runtime`](../packages/client/runtime) | `client` | [`api-remotes`](../packages/api/remotes), [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
+| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
@@ -1314,11 +1333,10 @@ flowchart TD
 | [`repository-plugin`](../packages/cordis/repository-plugin) | `cordis` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
-| [`client-locale`](../packages/client/locale) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-test-runtime`](../packages/client/test-runtime) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/support/invariants) |
-| [`client-ui-models`](../packages/client/ui-models) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
-| [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`invariants`](../packages/support/invariants) |
+| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/ui/permission) |
+| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
+| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
 | [`sdk-protocol`](../packages/sdk/sdk-protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
@@ -1326,27 +1344,8 @@ flowchart TD
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
-| [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |
-| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
-| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`sdk-client`](../packages/sdk/sdk-client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/sdk-client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
-| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
-| [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`cli-demo`](../packages/examples/cli-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
-| [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
-| [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
-| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
-| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
-| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
-| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
-| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/ui/permission) |
diff --git a/packages/AGENTS.md b/packages/AGENTS.md
index 0e8c62841e..58db577ee5 100644
--- a/packages/AGENTS.md
+++ b/packages/AGENTS.md
@@ -19,7 +19,7 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md
 
 Naming notes:
 
-- **Package tsconfig shape:** extends `tsconfig.base.json` (client: `tsconfig.base.client.json`), `rootDir: src`, `outDir: lib/types`, a `references` entry per workspace dependency plus `support/invariants`; registered in exactly one aggregate — host packages in `tsconfig.host.json`, client in `tsconfig.client.json` ([layout](../docs/development.md#typescript-project-layout)).
+- **Package tsconfig:** extends `tsconfig.base.json` (Client: `tsconfig.base.client.json`), uses `rootDir: src`, `outDir: lib/types`, and references each workspace dependency plus `support/invariants`; registers in exactly one aggregate. Only `api/remotes` splits for generated contracts; ordinary two-entry Client plugins do not ([layout](../docs/development.md#typescript-project-layout)).
 - `src/types.ts` contains only types — no runtime code.
 - Tests live at package level under `tests/`, not `src/__tests__/`.
 - A package's README and JSDoc are part of the change: altered behavior (config keys, defaults, error codes, wire fields) updates them in the same commit. `doc-sync` gates what it can; apply [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for complete, concise prose and verify accuracy against code.
diff --git a/packages/api/remotes/README.i18n.yaml b/packages/api/remotes/README.i18n.yaml
index 82947331c5..f8f7a6400b 100644
--- a/packages/api/remotes/README.i18n.yaml
+++ b/packages/api/remotes/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/api/remotes/README.md
-README.md: 7f6a2114d900413d972584c0f1c141b7f835ba36
-README.zh.md: cce263747d696570f362811556fa6f5c0be0a0f5
+README.md: 3d9de0955faefe37c95ff8bb792d57c4fa1f1a3a
+README.zh.md: 7490d68781d3a7b0002b73fe06056ec86c144575
diff --git a/packages/api/remotes/README.md b/packages/api/remotes/README.md
index 7f6a2114d9..3d9de0955f 100644
--- a/packages/api/remotes/README.md
+++ b/packages/api/remotes/README.md
@@ -10,6 +10,14 @@ The current Client assembly mounts only the Goal Remote contribution. Cordis eff
 
 This package contains no transport or Host service discovery logic. Its Client face can be reused by Web or a future TUI that provides the same React-free `ctx.remote` contract.
 
+## Build boundary
+
+An ordinary repository package belongs to one TypeScript face: Host packages are registered in the root `tsconfig.host.json`, and Client packages in the root `tsconfig.client.json`. `api-remotes` is the only deliberate exception because its Host entry must participate in the Host TypeRT graph, while `src/client/index.ts` cannot compile until Host tsdown has generated the business packages' `/remote` declarations.
+
+This package's root `tsconfig.json` is only a solution that references `tsconfig.host.json` and `tsconfig.client.json`. The Host aggregate and direct Host consumers reference the former, while the Client aggregate and direct Client consumers reference the latter; the package-root solution must not enter either aggregate's dependency graph. The two projects own disjoint source files and `.tsbuildinfo` files but share the `lib/types` output directory.
+
+The package-local `clientBundle(..., { hostPhase: true })` makes Host tsdown bundle the Host entry and the later Client tsdown bundle only the browser entry. Ordinary Client plugins remain single Client projects and produce both their Node loader entry and browser bundle during Client tsdown; do not copy this package's split merely because a package has both `src/index.ts` and `src/client/index.ts`.
+
 ## Model Experience
 
 None, as this BFF selects Remote application methods and identity policy but registers no model surface.
diff --git a/packages/api/remotes/README.zh.md b/packages/api/remotes/README.zh.md
index cce263747d..7490d68781 100644
--- a/packages/api/remotes/README.zh.md
+++ b/packages/api/remotes/README.zh.md
@@ -10,6 +10,14 @@
 
 本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 契约，均可复用其 Client face。
 
+## 构建边界
+
+仓库中的普通包只属于一个 TypeScript face：Host 包登记在根 `tsconfig.host.json`，Client 包登记在根 `tsconfig.client.json`。`api-remotes` 是唯一刻意拆分的特例，因为它的 Host 入口要参与 Host TypeRT 图，而 `src/client/index.ts` 必须等 Host tsdown 生成业务包的 `/remote` 声明后才能编译。
+
+本包根 `tsconfig.json` 只是引用 `tsconfig.host.json` 与 `tsconfig.client.json` 的 solution。Host aggregate 和 Host 直接消费方引用前者，Client aggregate 和 Client 直接消费方引用后者；禁止把包根 solution 放进任一 aggregate 的依赖图。两个 project 拥有互不重叠的源码和 `.tsbuildinfo`，但共享 `lib/types` 输出目录。
+
+包内 `clientBundle(..., { hostPhase: true })` 让 Host tsdown 打包 Host 入口，让后续 Client tsdown 只打包 browser 入口。普通 Client 插件仍使用单一 Client project，并在 Client tsdown 阶段一起生成 Node loader 入口和 browser bundle；不得因一个包同时存在 `src/index.ts` 与 `src/client/index.ts` 就复制本包的拆分。
+
 ## 模型体验
 
 无，因为该 BFF 只选择 Remote 应用方法和身份策略，不注册任何模型接口。
diff --git a/packages/typert/generator/README.i18n.yaml b/packages/typert/generator/README.i18n.yaml
index cd6588c0ab..583835a63b 100644
--- a/packages/typert/generator/README.i18n.yaml
+++ b/packages/typert/generator/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/typert/generator/README.md
-README.md: c343fd9475a9407159037f0a10e3a0586a77c3da
-README.zh.md: f9f863fe67d256b9744d7caeda0680f715808714
+README.md: 38030c2b7e07c70ab79001086640b6581943dbd9
+README.zh.md: afa45820b7c7fba77704b86902c8752cd45777e6
diff --git a/packages/typert/generator/README.md b/packages/typert/generator/README.md
index c343fd9475..38030c2b7e 100644
--- a/packages/typert/generator/README.md
+++ b/packages/typert/generator/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 TypeScript project analyzer and model-driven Typert generator. It converts the developer-authored source type tree into compiler-independent `FaceModel` and `TypeGraph` data before any artifact is rendered. Static analysis can consume that model without Cordis; emitters never receive TypeScript AST or checker objects.
 
-Host and client use independent `ts.Program` instances seeded from `tsconfig.host.json` and `tsconfig.client.json`. Direct project references establish face membership, `package.json#exports` establishes every cross-package public boundary, and source imports or re-exports are the only allowed cross-face edges. Types owned by NPM dependencies, including global declarations from `@types` packages, remain `external` references instead of being expanded.
+The analyzer can use independent `ts.Program` instances seeded from `tsconfig.host.json` or `tsconfig.client.json`. Direct project references establish compiler-face membership, while package subpaths establish TypeRT runtime-face contributions: an ordinary single-project `dshClient` package may contribute both Host and Client runtime models, and only a split project explicitly referenced through `tsconfig.host.json` or `tsconfig.client.json` is restricted to that corresponding face. `package.json#exports` establishes every cross-package public boundary, and source imports or re-exports are the only allowed cross-face edges. Types owned by NPM dependencies, including global declarations from `@types` packages, remain `external` references instead of being expanded.
 
 ## Analysis Model
 
@@ -18,7 +18,7 @@ Each face contains package exports, Cordis services and events, explicitly tagge
 
 `WorkspaceTypertGenerator` discovers contributors by walking package public exports reachable from Cordis `Context` or `Events` augmentations and explicit `@typert` declarations. When invoked for artifact publication, it requires host artifacts at `lib/typert.host.{js,d.ts}` exposed as `package/typert`, and client artifacts at `lib/typert.client.{js,d.ts}` exposed as `package/client/typert`. Generated declarations expose `TYPERT` as `unknown`, so contributing business packages do not depend on the runtime registry.
 
-Publication is package opt-in. The root build and typecheck do not generate Typert artifacts or require every business package to add Typert exports. Static consumers can call `WorkspaceAnalyzer` directly, select host/client and package subsets, and use bounded package batches without publishing or loading runtime artifacts.
+Publication is package opt-in, and business packages without the corresponding public entry do not need Typert artifacts. The repository's Host tsdown runs workspace TypeRT generation with `tsconfig.host.json` as its only program seed; it produces both Host reflection artifacts and the `typert.remote-client.*` projection of Host Remote contracts for the Client. The subsequent Client tsdown neither starts TypeRT nor analyzes `tsconfig.client.json`. Static consumers can still call `WorkspaceAnalyzer` directly, explicitly select a face and package subset, and process packages in batches without publishing or loading runtime artifacts.
 
 ## Repository-specific Cordis projection
 
diff --git a/packages/typert/generator/README.zh.md b/packages/typert/generator/README.zh.md
index f9f863fe67..afa45820b7 100644
--- a/packages/typert/generator/README.zh.md
+++ b/packages/typert/generator/README.zh.md
@@ -4,7 +4,7 @@
 
 TypeScript 项目分析器和模型驱动的 Typert 生成器。在生成任何产物之前，它会先将开发者编写的源类型树转换为独立于编译器的 `FaceModel` 和 `TypeGraph` 数据。静态分析无需 Cordis 即可消费该模型；各产物生成组件均不会接收 TypeScript 抽象语法树（AST）或类型检查器对象。
 
-宿主侧与客户端侧分别使用独立的 `ts.Program` 实例，二者以 `tsconfig.host.json` 和 `tsconfig.client.json` 初始化。直接项目引用确定各包所属的 face，`package.json#exports` 确定所有跨包公开边界，跨 face 的边则只能来自源码中的导入或重新导出。NPM 依赖拥有的类型（包括 `@types` 包中的全局声明）继续以 `external` 引用表示，不会被展开。
+分析器可以分别使用由 `tsconfig.host.json` 或 `tsconfig.client.json` 初始化的独立 `ts.Program`。直接 Project Reference 确定 compiler project 成员关系；带 `dshClient` 的普通单 project package 可按公开 subpath 同时贡献 Host 与 Client 运行时 face，显式引用 `tsconfig.host.json` 或 `tsconfig.client.json` 的拆分 project 则只贡献所选 face。`package.json#exports` 确定所有跨包公开边界，跨 face 的边只能来自源码导入或重新导出。NPM 依赖拥有的类型（包括 `@types` 包中的全局声明）继续以 `external` 引用表示，不会被展开。
 
 ## 分析模型
 
@@ -18,7 +18,7 @@ TypeScript 项目分析器和模型驱动的 Typert 生成器。在生成任何
 
 `WorkspaceTypertGenerator` 会遍历从 Cordis `Context` 或 `Events` 扩充声明及显式 `@typert` 声明可达的包公开导出，以发现贡献方。发布产物时，它要求宿主侧产物位于 `lib/typert.host.{js,d.ts}` 并以 `package/typert` 暴露，客户端侧产物位于 `lib/typert.client.{js,d.ts}` 并以 `package/client/typert` 暴露。生成的声明将 `TYPERT` 暴露为 `unknown`，因此参与贡献的业务包无需依赖运行时注册表。
 
-各包可自行选择是否发布。根目录的构建和类型检查不会生成 Typert 产物，也不要求每个业务包添加 Typert 导出。静态消费方可以直接调用 `WorkspaceAnalyzer`，选择宿主侧／客户端侧及包子集，并在不发布或加载运行时产物的情况下分批处理包，同时限制每批数量。
+各包可自行选择是否发布，未提供对应公开入口的业务包无需生成 Typert 产物。仓库的 Host tsdown 会以 `tsconfig.host.json` 为唯一 program 种子运行 workspace TypeRT 生成；它既生成 Host 反射产物，也把 Host Remote 契约投影为 Client 使用的 `typert.remote-client.*`。后续 Client tsdown 不启动 TypeRT，也不分析 `tsconfig.client.json`。静态消费方仍可直接调用 `WorkspaceAnalyzer`，显式选择 face 与包子集，并在不发布或加载运行时产物的情况下分批处理包。
 
 ## 本仓库的 Cordis 投影
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 91509f3267..b2adbc38aa 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository typecheck runs the whole-repo `tsc -b` graph: it emits every package/vendor `lib/types` and checks examples, tests, and scripts through two no-emit aggregates.\n\nThe repository's TypeScript configuration has exactly three roles; every tsconfig file plays one of them.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, references to the two aggregates. The whole-repo `tsc -b tsconfig.json` graph, the tsserver discovery entry, and — through the inherited `paths` — the resolution config for tsx running `examples/` and `scripts/` (their nearest tsconfig is this file). | No |\n| `tsconfig.host.json` | Host aggregate: host-side packages (via references), examples, tests, scripts, website. Excludes `packages/client`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the client aggregate and every `packages/client/*` package. | No |\n\nHost and client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Two disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges. Program-backed generators and gates (`scripts/ts-project.ts` consumers, doc-typecheck standalone mode) are host-only by decision; the client side gains program-backed tooling only with a concrete need.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Decision record: [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md); the tsc-first emit pipeline is the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md).\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology and the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库类型检查会执行全仓 `tsc -b` 图：它会发射每个 package/vendor 的 `lib/types`，并通过两个 no-emit 聚合检查示例、测试和脚本。\n\n仓库的 TypeScript 配置只有三种角色；每个 tsconfig 文件恰好扮演其中一种。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个聚合。全仓 `tsc -b tsconfig.json` 图、tsserver 发现入口，并经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置（它们最近的 tsconfig 就是此文件）。 | 否 |\n| `tsconfig.host.json` | host 聚合：host 侧各包（经 references）、示例、测试、脚本、website。排除 `packages/client`。 | 是 |\n| `tsconfig.client.json` | client 聚合：`packages/client/*` 各包及其测试、`apps/web`。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 client 聚合和每个 `packages/client/*` 包 extends。 | 否 |\n\nhost 与 client 保持两个聚合 program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个聚合，一个 paths 门面也可以横跨两侧。由此推出两条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个聚合展平进一个 program 会撞上 `Context` 合并冲突。基于 program 的生成器与门禁（`scripts/ts-project.ts` 的消费者、doc-typecheck standalone 模式）按决策仅覆盖 host 侧；client 侧只在出现真实需求时再获得基于 program 的工具。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。决策记录：[solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)；tsc-first 发射管线见 [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",

From 69bd00ae76f0cc83b2f3837955cf4463cf53bfd8 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 10:28:30 +0800
Subject: [PATCH 196/516] chore(web): register the skill-user-invoke scenario
 in both typecheck planes

The web app project excludes every e2e file (they are host-plane programs)
and tsconfig.host.json includes them one by one; the new scenario joins
both lists so it keeps typecheck coverage without dragging host sources
into the client project.
---
 apps/web/tsconfig.json | 1 +
 tsconfig.host.json     | 1 +
 2 files changed, 2 insertions(+)

diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 528714a527..41224d21e4 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -57,6 +57,7 @@
     "tests/markdown-inline-code-links.e2e.ts",
     "tests/queue-actions.e2e.ts",
     "tests/skill-invocation-policy.e2e.ts",
+    "tests/skill-user-invoke.e2e.ts",
     "tests/permission-policy-context.e2e.ts",
     "tests/access-confirmation.e2e.ts",
     "tests/shipped-composition.e2e.ts",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 6884839536..9a06566fa2 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -44,6 +44,7 @@
     "apps/web/tests/markdown-inline-code-links.e2e.ts",
     "apps/web/tests/queue-actions.e2e.ts",
     "apps/web/tests/skill-invocation-policy.e2e.ts",
+    "apps/web/tests/skill-user-invoke.e2e.ts",
     "apps/web/tests/permission-policy-context.e2e.ts",
     "apps/web/tests/access-confirmation.e2e.ts",
     "apps/web/tests/shipped-composition.e2e.ts",

From ae9d31d098f473fe3ed369043c5d9fedc0e8839d Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 10:46:58 +0800
Subject: [PATCH 197/516] review: pin off-value wire contract, scope compat
 inheritance to the entry's api, update the superseded note
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review findings on #1977, each verified before acting: the 2026-08-03
declared-provider-catalog note is updated in place and cross-linked both
ways now that reasoningEfforts/compat reopened half of its rejected
alternative; resolveModelCompat inherits the catalog entry's compat only
while the resolved api still is the entry's own, so a route-level api
repoint no longer merges another protocol's shape as a completions base;
the off-with-value promise gains a request-boundary test proving pi-ai
reads thinkingLevelMap.off when the reasoning option is absent (and the
catalog-level test name stops overclaiming); the cannot-stop-thinking
wording narrows to what is actually enforced (no Off offered, explicit
Off refused — an effortless request goes out bare); the z.const(null)
comment attributes null passthrough to schemastery's nullable
short-circuit; the baseten drift-gate claim names its verification
source; and the layered-merge delete gap for dict keys is documented
under Known Limitations with the atomic-leaf follow-up in #2003.
---
 ...-pi-ai-declared-provider-catalog.i18n.yaml |  4 +--
 ...6-08-03-pi-ai-declared-provider-catalog.md |  6 ++--
 ...8-03-pi-ai-declared-provider-catalog.zh.md |  6 ++--
 ...per-model-reasoning-declarations.i18n.yaml |  4 +--
 ...-pi-ai-per-model-reasoning-declarations.md |  6 ++--
 ...-ai-per-model-reasoning-declarations.zh.md |  6 ++--
 docs/user/guide/providers.i18n.yaml           |  4 +--
 docs/user/guide/providers.md                  |  2 +-
 docs/user/guide/providers.zh.md               |  2 +-
 packages/llm/llm-pi-ai/README.i18n.yaml       |  4 +--
 packages/llm/llm-pi-ai/README.md              |  3 +-
 packages/llm/llm-pi-ai/README.zh.md           |  3 +-
 packages/llm/llm-pi-ai/src/catalog.ts         | 10 ++++--
 packages/llm/llm-pi-ai/src/config.ts          | 14 ++++----
 packages/llm/llm-pi-ai/tests/adapter.spec.ts  | 33 +++++++++++++++++++
 packages/llm/llm-pi-ai/tests/catalog.spec.ts  |  2 +-
 16 files changed, 75 insertions(+), 34 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
index 9300571e28..2969995da6 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.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 .agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
-2026-08-03-pi-ai-declared-provider-catalog.md: d75b6bdb91d60026636bf320f8c6625590849a41
-2026-08-03-pi-ai-declared-provider-catalog.zh.md: f8dba9900b1a7a3abcb16c70a35cc18f0c44219f
+2026-08-03-pi-ai-declared-provider-catalog.md: f908eb6293b77680193fcd8f7be7a9089477855a
+2026-08-03-pi-ai-declared-provider-catalog.zh.md: ce91abd6dc71f790c72766cd3f819096d596182c
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
index d75b6bdb91..f908eb6293 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
@@ -14,7 +14,7 @@ The adapter also streamed through `streamSimple` from `@earendil-works/pi-ai/com
 
 A provider route is a **declaration**, and the installed catalog is its default. `resolveProfiles` no longer checks route keys against `getBuiltinProviders()`. Instead each route resolves to a materialized model list plus the pi-ai `Provider` that serves it:
 
-- `catalog.ts` merges the installed catalog under the profile's own entries. A profile's `models` list *replaces* the route's catalog (an absent or empty list serves it unchanged), and each entry defaults its unset fields from the installed model of the same `id`. Only the fields the harness consumes are configurable — `id`, `name`, `contextWindow`, `maxTokens`. Pricing and input modalities are absent from the surface because nothing reads them: `replay.ts` zeroes pi-ai's cost metadata and `context.ts` keeps only text blocks. Reasoning is absent for a different reason: a bare capability flag would make pi-ai advertise effort levels with no `thinkingLevelMap` to spell them, so it rides the installed entry or is absent. Materialization spreads the installed entry and overrides those four fields, rather than enumerating the result: an enumerated rebuild silently drops every `Model` field this package does not model, which is how `headers` went missing from an nvidia route once already.
+- `catalog.ts` merges the installed catalog under the profile's own entries. A profile's `models` list *replaces* the route's catalog (an absent or empty list serves it unchanged), and each entry defaults its unset fields from the installed model of the same `id`. Only the fields the harness consumes are configurable — at this note's writing `id`, `name`, `contextWindow`, `maxTokens`; [[2026-08-08-pi-ai-per-model-reasoning-declarations]] later added `reasoningEfforts` and `compat`, which is also where the original "reasoning rides the installed entry or is absent" stance was revisited (a bare capability flag stays rejected; a full per-level declaration with wire spellings does not have its problem). Pricing and input modalities remain absent from the surface because nothing reads them: `replay.ts` zeroes pi-ai's cost metadata and `context.ts` keeps only text blocks. Materialization spreads the installed entry and overrides the configured fields, rather than enumerating the result: an enumerated rebuild silently drops every `Model` field this package does not model, which is how `headers` went missing from an nvidia route once already.
 - `provider.ts` builds the route's `Provider`. A catalog route that keeps its catalog protocol **reuses** the installed provider with `getModels()` replaced; every other route is built by `createProvider()` over a protocol table whose entries are the same `@earendil-works/pi-ai/api/*.lazy` factories pi-ai's own provider factories use. That table is narrower than pi-ai's full API set on purpose — it holds only protocols a profile can completely describe with a key, an endpoint, and headers, so Bedrock (SigV4 plus a region), Vertex (project, location, ADC), Azure (provider environment plus an api-version), and Codex (OAuth) are absent rather than offered as routes that cannot authenticate. Catalog routes still reach them through their own provider; only an explicit override is refused.
 - `adapter.ts` turns each resolution into an **immutable snapshot** — the profiles plus a `createModels()` collection holding those providers — and every operation captures a whole snapshot before its first `await`.
 - A model's **explicitly configured** `maxTokens` becomes the seam's `defaultMaxTokens`. The value inherited from the installed catalog does not: pi-ai requires `Model.maxTokens` as the model's output *capability*, while `defaultMaxTokens` is a cap the deployment chose to send on requests that name none, and materializing the former as the latter would start capping every request at a number nobody picked.
@@ -35,7 +35,7 @@ The configurable-provider directory is now the installed catalog **joined with**
 
 pi-ai reports a model with no reasoning metadata as supporting the single level `off`, and the adapter used to pass that straight through. It reaches the seam as a one-item effort list, which every surface renders as a picker holding one selectable control — and that control is a lie: `off` becomes an *omitted* reasoning option at dispatch, byte-for-byte the request that naming no effort already produces. A provider whose own default is to think keeps thinking while the surface shows `off` selected.
 
-`reasoningInfo` therefore omits the seam's `reasoning` field whenever `model.reasoning` is falsy. The condition is the model's own metadata, not where the model came from, so this covers every hand-declared model **and** the 251 installed-catalog models pi-ai marks as non-reasoning. Those previously offered the lone `off`; they now offer nothing, and the surface shows the provider default alone. Models that do carry reasoning metadata are untouched — their level list still crosses the seam unfiltered, `off` included, because there it selects between real alternatives.
+`reasoningInfo` therefore omits the seam's `reasoning` field whenever `model.reasoning` is falsy. The condition is the model's own metadata, not where the model came from, so this covers every hand-declared model whose entry declares no `reasoningEfforts` ([[2026-08-08-pi-ai-per-model-reasoning-declarations]] made declared efforts carry that metadata) **and** the 251 installed-catalog models pi-ai marks as non-reasoning. Those previously offered the lone `off`; they now offer nothing, and the surface shows the provider default alone. Models that do carry reasoning metadata are untouched — their level list still crosses the seam unfiltered, `off` included, because there it selects between real alternatives.
 
 ### Credentials stay outside pi-ai
 
@@ -50,7 +50,7 @@ A route's auth follows from that. A catalog route keeps the installed provider's
 - **Keep `createProvider()` but skip the `Models` collection**, streaming through `provider.streamSimple(model, ctx, {apiKey})`. Smallest diff and the credential path is untouched, but `createProvider`'s `auth` is a required field that this path never invokes — a required-by-signature implementation with no caller. It also leaves `refreshModels` needing a hand-built `RefreshModelsContext`, and keeps the adapter off the runtime pi-ai actually supports.
 - **Reuse the installed provider for catalog routes and `createProvider()` only for declared ones**, with no shared resolution. Zero risk to catalog behavior, but catalog materialization, endpoint override, and per-model configuration would each exist twice, and a catalog route that repoints its protocol would have to jump paths mid-resolution. The chosen split confines the asymmetry to provider construction, where it is forced by pi-ai not exposing a built provider's API implementations.
 - **Rebuild every route through `createProvider()`**, including catalog ones. Fully symmetric, but a built `Provider` does not expose its `api`, so the protocol table would become the ceiling on which providers work — Bedrock loads its Smithy module through a separate entry point and would silently stop working.
-- **Expose pi-ai's whole `Model` shape** (cost, input modalities, `thinkingLevelMap`, `compat`). Maximum configurability, but no current consumer reads those fields, so a configured price or modality would change nothing while reading as supported.
+- **Expose pi-ai's whole `Model` shape** (cost, input modalities, `thinkingLevelMap`, `compat`). Maximum configurability, but no current consumer read those fields then, so a configured price or modality would change nothing while reading as supported. The consumer-driven half of this arrived later: [[2026-08-08-pi-ai-per-model-reasoning-declarations]] opened reasoning (as `reasoningEfforts`, not a raw `thinkingLevelMap`) and the two reasoning-dispatch `compat` switches once selectors and dispatch actually consumed them; cost and modalities stay closed for the original reason.
 
 - **Keep one mutable `Models` collection and re-sync it.** Fewer allocations, and correct for every operation that resolves synchronously. It is exactly wrong for the one that does not: `stream()` awaits a credential between capturing its model and dispatching it.
 - **Simulate an atomic directory swap with dispose-then-register.** No seam change, and it works whenever the new set is valid — which is the case that never needed atomicity.
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
index f8dba9900b..ce91abd6dc 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 提供方路由是一份**声明**，已安装 catalog 是它的默认值。`resolveProfiles` 不再拿路由键去核对 `getBuiltinProviders()`，而是把每条路由解析成一份物化模型列表，外加服务它的 pi-ai `Provider`：
 
-- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——`id`、`name`、`contextWindow`、`maxTokens`。定价与输入模态不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。推理缺席则是另一个理由：一个孤立的能力布尔量会让 pi-ai 公布出没有 `thinkingLevelMap` 可供拼写的档位，因此它沿用已安装条目或直接缺席。物化时以已安装条目铺底、再覆盖那四个字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
+- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——本 note 写就时为 `id`、`name`、`contextWindow`、`maxTokens`；[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 之后加入了 `reasoningEfforts` 与 `compat`，当初「推理沿用已安装条目或直接缺席」的立场也在那里被重新审视（孤立的能力布尔量仍被拒绝；带 wire 拼写的逐档位完整声明没有它那个问题）。定价与输入模态仍不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。物化时以已安装条目铺底、再覆盖已配置的字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
 - `provider.ts` 构造路由的 `Provider`。保持 catalog 协议不变的 catalog 路由会**复用**已安装提供方，只替换 `getModels()`；其余路由都由 `createProvider()` 基于一张协议表构造，表中条目正是 pi-ai 自己的提供方工厂所用的 `@earendil-works/pi-ai/api/*.lazy` factory。该表刻意窄于 pi-ai 的完整 API 集合——只保留 profile 能用密钥、端点与标头完整描述的协议，因此 Bedrock（SigV4 加 region）、Vertex（project、location、ADC）、Azure（提供方环境加 api-version）与 Codex（OAuth）不在其中，而不是被当作无法认证的路由提供出去。catalog 路由仍可经自己的 provider 抵达它们；被拒的只有显式覆盖。
 - `adapter.ts` 把每次解析变成一份**不可变快照**——profiles 加上持有这些 provider 的 `createModels()` 集合——每个操作都在自己第一个 `await` 之前整体捕获一份。
 - 模型**显式配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`；从已安装 catalog 继承来的那份不会：pi-ai 要求 `Model.maxTokens` 表示模型的输出**能力**，而 `defaultMaxTokens` 是部署选定、发给未点名上限的请求的那个值，把前者物化成后者会让每个请求都被一个无人选择的数字封顶。
@@ -35,7 +35,7 @@ Status: implemented
 
 pi-ai 把没有推理元数据的模型报告为只支持 `off` 一档，而适配器此前原样透传。它抵达 seam 时是一个单元素的 effort 列表，任何界面都会把它渲染成一个只有一项可选控件的选择器——而这个控件在撒谎：`off` 在派发时变成被*省略*的 reasoning 选项，与「不点名任何档位」产出的请求逐字节相同。自身默认就在思考的提供方会继续思考，界面却显示 `off` 已选中。
 
-因此只要 `model.reasoning` 为假，`reasoningInfo` 就省略 seam 的 `reasoning` 字段。判据是模型自身的元数据，而非模型的来源，所以它覆盖每一个手工声明的模型**以及** pi-ai 标记为不具备推理能力的那 251 个已安装 catalog 模型。它们此前提供那个孤零零的 `off`，现在什么也不提供，界面只剩提供方默认。携带推理元数据的模型不受影响——其档位列表仍不经筛选地穿过 seam、`off` 也在内，因为在那里它是在真实备选之间做选择。
+因此只要 `model.reasoning` 为假，`reasoningInfo` 就省略 seam 的 `reasoning` 字段。判据是模型自身的元数据，而非模型的来源，所以它覆盖条目未声明 `reasoningEfforts` 的每一个手工声明模型（[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 让声明的档位携带这份元数据）**以及** pi-ai 标记为不具备推理能力的那 251 个已安装 catalog 模型。它们此前提供那个孤零零的 `off`，现在什么也不提供，界面只剩提供方默认。携带推理元数据的模型不受影响——其档位列表仍不经筛选地穿过 seam、`off` 也在内，因为在那里它是在真实备选之间做选择。
 
 ### 凭据留在 pi-ai 之外
 
@@ -50,7 +50,7 @@ pi-ai 的 `Models` 自带一套凭据概念——按提供方 id 索引的 `Cred
 - **保留 `createProvider()` 但不建 `Models` 集合**，改由 `provider.streamSimple(model, ctx, {apiKey})` 发起。改动最小且凭据路径原封不动，但 `createProvider` 的 `auth` 是必填字段，这条路上它永远不会被调用——一份因签名而必填、却没有调用方的实现。它还让 `refreshModels` 需要手工构造 `RefreshModelsContext`，并使适配器始终不在 pi-ai 真正支持的运行时上。
 - **catalog 路由复用已安装提供方，只有声明式路由走 `createProvider()`**，且两者不共享解析。对 catalog 行为零风险，但 catalog 物化、端点覆盖与每模型配置这三件事都要各写两遍，而改指协议的 catalog 路由还得在解析中途跳到另一条路径。已采纳的拆法把不对称收敛在提供方构造这一处——那里的不对称是 pi-ai 不暴露已构造提供方的 API 实现所强加的。
 - **让每条路由都经 `createProvider()` 重建**，包括 catalog 路由。完全对称，但已构造的 `Provider` 不暴露自己的 `api`，于是协议表会成为「哪些提供方能用」的天花板——Bedrock 经独立入口加载其 Smithy 模块，会因此静默失效。
-- **完整暴露 pi-ai 的 `Model` 形状**（成本、输入模态、`thinkingLevelMap`、`compat`）。可配置性最大，但这些字段当前没有任何读取方，因此配了价格或模态什么也不会改变，却看起来像是受支持的。
+- **完整暴露 pi-ai 的 `Model` 形状**（成本、输入模态、`thinkingLevelMap`、`compat`）。可配置性最大，但这些字段当时没有任何读取方，因此配了价格或模态什么也不会改变，却看起来像是受支持的。这条否决里由消费方驱动的那一半后来兑现了：[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 在选择器与分派真正消费之后开放了推理（以 `reasoningEfforts` 的形态，而非裸 `thinkingLevelMap`）和两个推理分派 `compat` 开关；成本与模态仍因原有理由保持关闭。
 
 - **保留单个可变 `Models` 集合并重新同步。** 分配更少，且对每个同步完成解析的操作都是正确的；唯独对那个不同步的操作恰恰是错的：`stream()` 会在捕获模型与派发模型之间 await 一次凭据。
 - **用「先 dispose 再注册」模拟目录原子替换。** 无需改 seam，且在新集合有效时确实可用——而那正是从不需要原子性的那种情形。
diff --git a/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.i18n.yaml
index 3b448f4cf1..3639c8da6b 100644
--- a/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.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 .agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.md
-2026-08-08-pi-ai-per-model-reasoning-declarations.md: 436b5f3f9f30c1bb1dc5816b12ce1596c5d01ec8
-2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md: 47b34dfd270f90fef2802a00e3632777d5636a73
+2026-08-08-pi-ai-per-model-reasoning-declarations.md: b6264feeb724e3693078fa3fc3e3fc16ed01aacb
+2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md: 1b30f7e0c42974c777a535e133a47caa217e2e5e
diff --git a/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.md b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.md
index 436b5f3f9f..b6264feeb7 100644
--- a/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.md
+++ b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.md
@@ -6,15 +6,15 @@ English | [中文](2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md)
 
 ## Problem
 
-A hand-declared pi-ai route's models materialized with `reasoning: false`, so `getSupportedThinkingLevels` short-circuited to `["off"]`: the composer offered no effort picker for them, and the route-level `reasoning` default — the only reasoning knob a profile had — made every request to such a model fail with `UNSUPPORTED_REASONING_EFFORT` before network I/O. The same route-level knob was also the wrong altitude for catalog routes: one provider's models disagree about which levels they accept (deepseek ships `[off, high, max]` beside catalog models with `xhigh`), so a single per-route level could not be set without breaking part of the route, which is why the Models page stopped writing it entirely (#1860) and left `settings.yaml` with no way to align efforts per model.
+Under the declared-provider catalog ([[2026-08-03-pi-ai-declared-provider-catalog]], which deliberately kept reasoning out of the configurable fields), a hand-declared pi-ai route's models materialized with `reasoning: false`, so `getSupportedThinkingLevels` short-circuited to `["off"]`: the composer offered no effort picker for them, and the route-level `reasoning` default — the only reasoning knob a profile had — made every request to such a model fail with `UNSUPPORTED_REASONING_EFFORT` before network I/O. The same route-level knob was also the wrong altitude for catalog routes: one provider's models disagree about which levels they accept (deepseek ships `[off, high, max]` beside catalog models with `xhigh`), so a single per-route level could not be set without breaking part of the route, which is why the Models page stopped writing it entirely (#1860) and left `settings.yaml` with no way to align efforts per model.
 
 Two adjacent gaps compounded this. pi-ai decides the reasoning *wire dialect* (`compat.thinkingFormat`, `compat.supportsReasoningEffort`) by recognizing the endpoint URL, and a private gateway's URL says nothing — a DeepSeek-dialect gateway was spoken to in the OpenAI dialect with no configuration that could correct it. And the only way to touch one catalog model was the `models` list, which *replaces* the served catalog: narrowing `gpt-5`'s levels meant restating all thirty-eight openai models or silently dropping thirty-seven.
 
 ## Decision
 
-`PiAiModelProfile` gains `reasoningEfforts`: **each key is a level selectors offer, its value the spelling dispatch sends on the wire**. The declaration translates to pi-ai's `Model.reasoning` + `thinkingLevelMap` with all seven levels decided explicitly — declared levels carry their wire value, undeclared levels are pinned `null` — so the profile author never needs pi-ai's asymmetric defaulting rule (absent means "supported" for the five base levels but "unsupported" for `xhigh`/`max`). `off` is the one three-state key: left out, thinking cannot be turned off; declared valueless, Off is offered and dispatch sends nothing (the `deepseek` dialect sends `thinking: {type: "disabled"}`); declared with a value, that value goes on the wire. `false` declares a non-reasoning model; an empty declaration is refused rather than guessed at. The spelling for "disable" is `false` rather than `{}` because schemastery materializes an absent dict as `{}` — only a `z.union([z.const(false), dict])` keeps absent, disabled, and declared distinguishable, and a bare `reasoningEfforts:` (YAML null) slips through that union unvalidated, so resolution refuses it explicitly.
+`PiAiModelProfile` gains `reasoningEfforts`: **each key is a level selectors offer, its value the spelling dispatch sends on the wire**. The declaration translates to pi-ai's `Model.reasoning` + `thinkingLevelMap` with all seven levels decided explicitly — declared levels carry their wire value, undeclared levels are pinned `null` — so the profile author never needs pi-ai's asymmetric defaulting rule (absent means "supported" for the five base levels but "unsupported" for `xhigh`/`max`). `off` is the one three-state key: left out, no Off is offered and an explicit Off request is refused (an effortless request still goes out bare, leaving the provider its default); declared valueless, Off is offered and dispatch sends nothing (the `deepseek` dialect sends `thinking: {type: "disabled"}`); declared with a value, that value goes on the wire. `false` declares a non-reasoning model; an empty declaration is refused rather than guessed at. The spelling for "disable" is `false` rather than `{}` because schemastery materializes an absent dict as `{}` — only a `z.union([z.const(false), dict])` keeps absent, disabled, and declared distinguishable, and a bare `reasoningEfforts:` (YAML null) slips through that union unvalidated, so resolution refuses it explicitly.
 
-`compat.thinkingFormat` and `compat.supportsReasoningEffort` become configurable at two levels — route (its models' default) and model (winning per field) — resolving model → route → installed catalog entry → pi-ai's URL guess. They exist only on `openai-completions` (pi-ai types them nowhere else): a model-level switch on another protocol fails resolution, a route-level default skips such models, and a route with no completions model at all is refused. The two `chat-template` formats stay withheld for want of `chatTemplateKwargs`. Both enums are pinned to pi-ai's types through `Record<UpstreamUnion, true>` drift gates, so the pi-ai upgrade that adds a format (0.84 added `baseten`) fails compilation until the new member is classified.
+`compat.thinkingFormat` and `compat.supportsReasoningEffort` become configurable at two levels — route (its models' default) and model (winning per field) — resolving model → route → installed catalog entry → pi-ai's URL guess. They exist only on `openai-completions` (pi-ai types them nowhere else): a model-level switch on another protocol fails resolution, a route-level default skips such models, and a route with no completions model at all is refused. The two `chat-template` formats stay withheld for want of `chatTemplateKwargs`. Both enums are pinned to pi-ai's types through `Record<UpstreamUnion, true>` drift gates, so a pi-ai upgrade that adds a format fails compilation until the new member is classified (verified against the published 0.84.1 tarball, whose `thinkingFormat` union adds `baseten` over the pinned 0.82.1).
 
 `modelOverrides` reshapes individual catalog models without replacing the served set: key = catalog model id, value = a `models` entry minus `id`, materialized by handing the override to the existing entry path so capacities, efforts, compat, and request-default semantics stay identical. Unlike Pi's own config layer, which ignores unknown ids, every override that lands nowhere is refused — beside a `models` list, on a hand-declared route, naming an unknown model, or smuggling an `id` in the value (the schema passes unknown keys through, and a smuggled id would quietly rename the model).
 
diff --git a/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md
index 47b34dfd27..1b30f7e0c4 100644
--- a/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-pi-ai-per-model-reasoning-declarations.zh.md
@@ -6,15 +6,15 @@ Status: implemented
 
 ## 问题
 
-手工声明的 pi-ai 路由，其模型物化出来就带着 `reasoning: false`，于是 `getSupportedThinkingLevels` 短路成 `["off"]`：输入框不为它们提供档位选择器，而路由级的 `reasoning` 默认值——当时 profile 仅有的推理旋钮——让发往这类模型的每个请求都在网络 I/O 之前以 `UNSUPPORTED_REASONING_EFFORT` 失败。同一个路由级旋钮对 catalog 路由来说也放错了层级：同一提供方下各模型接受的档位并不一致（deepseek 自带 `[off, high, max]`，旁边就是带 `xhigh` 的 catalog 模型），单个路由级档位怎么设都会弄坏路由的一部分——这正是模型页彻底停写它的原因（#1860），而 `settings.yaml` 也因此没有了任何按模型对齐档位的办法。
+在声明式提供方 catalog（[[2026-08-03-pi-ai-declared-provider-catalog]]，它刻意把推理排除在可配置字段之外）之下，手工声明的 pi-ai 路由，其模型物化出来就带着 `reasoning: false`，于是 `getSupportedThinkingLevels` 短路成 `["off"]`：输入框不为它们提供档位选择器，而路由级的 `reasoning` 默认值——当时 profile 仅有的推理旋钮——让发往这类模型的每个请求都在网络 I/O 之前以 `UNSUPPORTED_REASONING_EFFORT` 失败。同一个路由级旋钮对 catalog 路由来说也放错了层级：同一提供方下各模型接受的档位并不一致（deepseek 自带 `[off, high, max]`，旁边就是带 `xhigh` 的 catalog 模型），单个路由级档位怎么设都会弄坏路由的一部分——这正是模型页彻底停写它的原因（#1860），而 `settings.yaml` 也因此没有了任何按模型对齐档位的办法。
 
 两个相邻的缺口让问题雪上加霜。pi-ai 靠识别端点 URL 来决定推理的*协议方言*（`compat.thinkingFormat`、`compat.supportsReasoningEffort`），而私有网关的 URL 什么也说明不了——说 DeepSeek 方言的网关只会收到 OpenAI 方言的请求，且没有任何配置能更正它。另外，想动单个 catalog 模型，唯一的手段是 `models` 列表，而它会*替换*所服务的 catalog：收窄 `gpt-5` 的档位，意味着要么重述全部三十八个 openai 模型，要么静默丢掉三十七个。
 
 ## 决策
 
-`PiAiModelProfile` 新增 `reasoningEfforts`：**每个键是选择器提供的一个档位，其值是分派在协议中发送的拼写**。该声明会转换为 pi-ai 的 `Model.reasoning` + `thinkingLevelMap`，七个档位全部显式决定——已声明的档位携带自己的协议值，未声明的档位一律固定为 `null`——因此 profile 作者永远不需要了解 pi-ai 那条不对称的默认规则（键缺席对五个基础档位意味着「支持」，对 `xhigh`/`max` 却意味着「不支持」）。`off` 是唯一的三态键：不写，思考就关不掉；声明而不给值，则提供 Off，分派什么也不发送（`deepseek` 方言发送 `thinking: {type: "disabled"}`）；声明并给值，该值就在协议中发送。`false` 声明一个不具备推理能力的模型；空声明会被拒绝，而不是去猜。「禁用」的拼写取 `false` 而非 `{}`，因为 schemastery 会把缺席的字典物化成 `{}`——只有 `z.union([z.const(false), dict])` 才能让缺席、禁用与已声明三态保持可区分；而裸写的 `reasoningEfforts:`（YAML null）会不经校验地从该 union 溜过去，因此解析对它显式拒绝。
+`PiAiModelProfile` 新增 `reasoningEfforts`：**每个键是选择器提供的一个档位，其值是分派在协议中发送的拼写**。该声明会转换为 pi-ai 的 `Model.reasoning` + `thinkingLevelMap`，七个档位全部显式决定——已声明的档位携带自己的协议值，未声明的档位一律固定为 `null`——因此 profile 作者永远不需要了解 pi-ai 那条不对称的默认规则（键缺席对五个基础档位意味着「支持」，对 `xhigh`/`max` 却意味着「不支持」）。`off` 是唯一的三态键：不写，选择器不提供 Off，显式请求 Off 会被拒绝（不点名档位的请求仍会不带参数地发出，提供方保留自己的默认行为）；声明而不给值，则提供 Off，分派什么也不发送（`deepseek` 方言发送 `thinking: {type: "disabled"}`）；声明并给值，该值就在协议中发送。`false` 声明一个不具备推理能力的模型；空声明会被拒绝，而不是去猜。「禁用」的拼写取 `false` 而非 `{}`，因为 schemastery 会把缺席的字典物化成 `{}`——只有 `z.union([z.const(false), dict])` 才能让缺席、禁用与已声明三态保持可区分；而裸写的 `reasoningEfforts:`（YAML null）会不经校验地从该 union 溜过去，因此解析对它显式拒绝。
 
-`compat.thinkingFormat` 与 `compat.supportsReasoningEffort` 变为两级可配置——路由级（作为其模型的默认值）与模型级（逐字段胜出）——解析顺序为模型 → 路由 → 已安装 catalog 条目 → pi-ai 按 URL 得出的猜测。两者只存在于 `openai-completions` 上（pi-ai 也只在这一协议上为它们建了类型）：在其他协议的模型上设模型级开关会使解析失败，路由级默认值会跳过这类模型，而完全没有 completions 模型的路由则被拒绝。两个 `chat-template` 格式因缺 `chatTemplateKwargs` 而继续保持不开放。两个枚举都经 `Record<UpstreamUnion, true>` 漂移门禁钉在 pi-ai 的类型上，因此新增格式的 pi-ai 升级（0.84 加入了 `baseten`）会编译失败，直到新成员被归类。
+`compat.thinkingFormat` 与 `compat.supportsReasoningEffort` 变为两级可配置——路由级（作为其模型的默认值）与模型级（逐字段胜出）——解析顺序为模型 → 路由 → 已安装 catalog 条目 → pi-ai 按 URL 得出的猜测。两者只存在于 `openai-completions` 上（pi-ai 也只在这一协议上为它们建了类型）：在其他协议的模型上设模型级开关会使解析失败，路由级默认值会跳过这类模型，而完全没有 completions 模型的路由则被拒绝。两个 `chat-template` 格式因缺 `chatTemplateKwargs` 而继续保持不开放。两个枚举都经 `Record<UpstreamUnion, true>` 漂移门禁钉在 pi-ai 的类型上，因此新增格式的 pi-ai 升级会编译失败，直到新成员被归类（对照已发布的 0.84.1 tarball 验证过：其 `thinkingFormat` 联合类型相对钉住的 0.82.1 新增了 `baseten`）。
 
 `modelOverrides` 就地重塑单个 catalog 模型而不替换所服务的集合：键 = catalog 模型 id，值 = 去掉 `id` 的 `models` 条目，物化时把覆盖交给既有的条目路径，因此容量、档位、compat 与请求默认值语义完全一致。与忽略未知 id 的 Pi 自有配置层不同，凡是落不到任何地方的覆盖都会被拒绝——与 `models` 列表并存、写在手工声明的路由上、点名未知模型，或在值里夹带 `id`（schema 会放行未知键，被夹带的 id 会悄悄把模型改名）。
 
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 787f3ec1d6..38df7fb986 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
-providers.md: c2c578b8489621004d5ceab8330f63b4e371b1f6
-providers.zh.md: df50cdd39321b7267089ca12a68a42696f7f8f66
+providers.md: 8b52044e64411e3081d56c1ee1849d0b24cd1cda
+providers.zh.md: f4a42a4093d253b4b230e4a838ba275a0ce58ac9
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index c2c578b848..8b52044e64 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -106,7 +106,7 @@ Reshaping a few catalog models while keeping the rest is `modelOverrides`' job:
 
 The configurable model fields are `id`, `name`, `contextWindow`, `maxTokens`, `reasoningEfforts`, and `compat`. Pricing and input modalities have no consumer and ride the installed entry.
 
-**Declare reasoning levels per model.** `reasoningEfforts` lists the levels a model offers: each key appears in the composer's effort picker, and its value is what dispatch sends on the wire — `high: high` passes the name through, `max: ultra` renames it for a gateway with its own vocabulary. A level you leave out is not offered. `off` is special: declared without a value, Off appears in the picker and selecting it sends nothing; left out entirely, the model cannot stop thinking. `reasoningEfforts: false` declares a non-reasoning model, which is also how you strip reasoning from a catalog model your gateway cannot serve. Without this field a custom model does not reason and a catalog model keeps its catalog levels.
+**Declare reasoning levels per model.** `reasoningEfforts` lists the levels a model offers: each key appears in the composer's effort picker, and its value is what dispatch sends on the wire — `high: high` passes the name through, `max: ultra` renames it for a gateway with its own vocabulary. A level you leave out is not offered. `off` is special: declared without a value, Off appears in the picker and selecting it sends nothing; left out entirely, the picker offers no Off and requests carry no off switch — the provider's own default decides. `reasoningEfforts: false` declares a non-reasoning model, which is also how you strip reasoning from a catalog model your gateway cannot serve. Without this field a custom model does not reason and a catalog model keeps its catalog levels.
 
 **Pick the reasoning dialect.** How a level travels — plain `reasoning_effort`, DeepSeek's `thinking: {type}` plus effort, and so on — is normally guessed from the endpoint URL, and a private gateway's URL says nothing, so a DeepSeek-style gateway would be spoken to in the OpenAI dialect. `compat.thinkingFormat` sets the dialect explicitly, and `compat.supportsReasoningEffort: false` holds the parameter back from an endpoint that rejects it; both work on the route (its models' default) or per model, for `openai-completions` routes only.
 
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index df50cdd393..f4a42a4093 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -106,7 +106,7 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 可配置的模型字段是 `id`、`name`、`contextWindow`、`maxTokens`、`reasoningEfforts` 与 `compat`。定价与输入模态没有消费方，随内置目录条目走。
 
-**按模型声明推理档位。** `reasoningEfforts` 列出模型提供的档位：每个键都会出现在输入框的档位选择器里，其值是分派在协议中实际发送的内容——`high: high` 原样透传名称，`max: ultra` 则为使用自有词汇的网关改名。没写的档位不会被提供。`off` 比较特殊：声明而不给值，选择器里会出现 Off，选中它时什么也不发送；完全不写，模型就无法停止思考。`reasoningEfforts: false` 声明一个不具备推理能力的模型，这也是从网关服务不了的目录模型上剥除推理的办法。不写这个字段，自定义模型不推理，目录模型保留目录给出的档位。
+**按模型声明推理档位。** `reasoningEfforts` 列出模型提供的档位：每个键都会出现在输入框的档位选择器里，其值是分派在协议中实际发送的内容——`high: high` 原样透传名称，`max: ultra` 则为使用自有词汇的网关改名。没写的档位不会被提供。`off` 比较特殊：声明而不给值，选择器里会出现 Off，选中它时什么也不发送；完全不写，选择器不提供 Off，请求也不携带关闭开关——由提供方自己的默认行为决定。`reasoningEfforts: false` 声明一个不具备推理能力的模型，这也是从网关服务不了的目录模型上剥除推理的办法。不写这个字段，自定义模型不推理，目录模型保留目录给出的档位。
 
 **选定推理方言。** 档位如何在协议中传输——单独一个 `reasoning_effort`、DeepSeek 的 `thinking: {type}` 加档位，诸如此类——通常靠端点 URL 来猜，而私有网关的 URL 什么也说明不了，于是 DeepSeek 风格的网关只会收到 OpenAI 方言的请求。`compat.thinkingFormat` 用来显式指定方言，`compat.supportsReasoningEffort: false` 则让该参数不再发给拒绝它的端点；两者既可设在路由上（作为其模型的默认值），也可按模型设置，且仅适用于 `openai-completions` 路由。
 
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 05c7376c8e..1fe2902388 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: 196c347dc557d3d3993756e165f45c9212cd2d36
-README.zh.md: cee6fce7bd13d9da5fdbe5312c7c7e7f4ddf8ab5
+README.md: c5ebca23ccb4162b65a6e18132970eaf01a50b84
+README.zh.md: f916462bca915bea37c59f7a33a08e1dcc18c4c7
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index 196c347dc5..c5ebca23cc 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -83,7 +83,7 @@ A profile's `models` list *replaces* the route's installed catalog rather than e
 
 `reasoningEfforts` declares a model's selectable thinking levels: each key is a level selectors offer, its value the spelling dispatch sends on the wire, so `high: high` passes the canonical name through while `max: ultra` renames it for a gateway with its own vocabulary. Keys come from pi-ai's level set (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`); a level not declared is not offered. Omitting the field keeps the installed catalog entry's capability (a hand-declared model has none and does not reason); `false` declares a non-reasoning model, which is how a profile strips reasoning from a catalog model its gateway cannot serve; an empty declaration is refused rather than guessing between those two meanings.
 
-The declaration translates to pi-ai's `Model.reasoning` + `thinkingLevelMap` with every level decided explicitly — undeclared levels are pinned unsupported rather than left to pi-ai's own defaulting, which is asymmetric (an absent key means "supported" for the five base levels but "unsupported" for `xhigh`/`max`) and which a profile author should not need to know. `off` is the one three-state key: left out, the model cannot stop thinking and selectors offer no Off; declared with no value (`off:`), Off is offered and selecting it sends nothing — for the `deepseek` dialect an explicit `thinking: {type: "disabled"}` — which also covers a request naming no effort at all; declared with a value (`off: none`), that value goes on the wire as the effort parameter. There is no spelling for restoring a catalog map key to "unset": the declaration is the whole offer, so restate the catalog levels you keep.
+The declaration translates to pi-ai's `Model.reasoning` + `thinkingLevelMap` with every level decided explicitly — undeclared levels are pinned unsupported rather than left to pi-ai's own defaulting, which is asymmetric (an absent key means "supported" for the five base levels but "unsupported" for `xhigh`/`max`) and which a profile author should not need to know. `off` is the one three-state key: left out, selectors offer no Off and an explicit Off request is refused — a request naming no effort still goes out without the parameter, so what the provider then does is its own default; declared with no value (`off:`), Off is offered and selecting it sends nothing — for the `deepseek` dialect an explicit `thinking: {type: "disabled"}` — which also covers a request naming no effort at all; declared with a value (`off: none`), that value goes on the wire as the effort parameter. There is no spelling for restoring a catalog map key to "unset": the declaration is the whole offer, so restate the catalog levels you keep.
 
 ### Reasoning-dispatch compat switches
 
@@ -186,6 +186,7 @@ Recorded response content appends to the next request and does not invalidate it
 ## Known Limitations and Deferred Work
 
 - **Settings can add or override routes, not remove composition routes** — the user layer merges over the composition `base`, so deleting a `cordis.yml`-provided provider is a composition change; `replace` on the namespace only resets the user layer.
+- **The layered merge has no delete for dict keys** — the settings seam merges the composition `base` and the user layer per key, recursively, so a `reasoningEfforts` level, `modelOverrides` entry, or `compat` field the base declares cannot be removed by the user layer, only overridden — and for `reasoningEfforts` absence *is* the meaning ("not offered"), so a base-declared level stays offered. A `models` list is an array and replaces wholesale, which is the workaround: declare the model there instead. Atomic-leaf merge semantics at the settings seam are tracked in [#2003](https://github.com/deepseek-harness/deepseek-harness/issues/2003).
 - **`headers` can carry a credential the redactor never sees** — the profile's `headers` dict is plain strings, so `Authorization` or `api-key` set there is returned verbatim by a redacted `describe()` and rendered by any configuration UI. Store credentials as `apiKeyEnv` references; making the dict write-only is deferred with the rest of the [wire-boundary work](../llm/README.md#known-limitations-and-deferred-work).
 - **A route's catalog never refreshes itself** — the catalog is whatever `settings.yaml` says, so a model list is only as current as its last edit. Nothing here queries a provider for the models it serves; a route gains a model when someone writes one.
 - **One wire protocol per route** — `api` applies to the whole route, so a mixed-protocol catalog route (an OpenAI-style catalog spanning Responses and Chat Completions) cannot host a model of the other protocol, and adding a model such a route does not describe requires naming `api` and moving every model onto it. Splitting the provider across two route keys is the workaround.
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index cee6fce7bd..f916462bca 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -83,7 +83,7 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 `reasoningEfforts` 声明模型可选的思考级别：每个键是选择器提供的一个档位，其值是分派在协议中发送的拼写，因此 `high: high` 原样透传规范名称，而 `max: ultra` 则为使用自有词汇的网关改名。键取自 pi-ai 的档位集合（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`）；未声明的档位不会被提供。省略该字段会保留已安装 catalog 条目的能力（手工声明的模型没有这份能力，也不推理）；`false` 声明一个不具备推理能力的模型，profile 正是以此从其网关无法服务的 catalog 模型上剥除推理；空声明会被拒绝，而不是在这两种含义之间去猜。
 
-该声明会转换为 pi-ai 的 `Model.reasoning` + `thinkingLevelMap`，其中每个档位都被显式决定——未声明的档位一律固定为不支持，而不是留给 pi-ai 自己的默认规则：那套规则并不对称（键缺席对五个基础档位意味着「支持」，对 `xhigh`/`max` 却意味着「不支持」），也本不该要求 profile 作者了解。`off` 是唯一的三态键：不写它，模型就无法停止思考，选择器也不提供 Off；声明而不给值（`off:`），则会提供 Off，选中它时什么也不发送——对 `deepseek` 方言则是一个显式的 `thinking: {type: "disabled"}`——这同时覆盖完全不点名任何档位的请求；声明并给值（`off: none`），该值就会作为档位参数在协议中发送。没有任何写法能把 catalog 映射中的键恢复为「未设置」：这份声明就是对外提供的全部，因此把你要保留的 catalog 档位重述出来。
+该声明会转换为 pi-ai 的 `Model.reasoning` + `thinkingLevelMap`，其中每个档位都被显式决定——未声明的档位一律固定为不支持，而不是留给 pi-ai 自己的默认规则：那套规则并不对称（键缺席对五个基础档位意味着「支持」，对 `xhigh`/`max` 却意味着「不支持」），也本不该要求 profile 作者了解。`off` 是唯一的三态键：不写它，选择器不提供 Off，显式请求 Off 会被拒绝——不点名任何档位的请求仍会在不带该参数的情况下发出，提供方随后做什么是它自己的默认行为；声明而不给值（`off:`），则会提供 Off，选中它时什么也不发送——对 `deepseek` 方言则是一个显式的 `thinking: {type: "disabled"}`——这同时覆盖完全不点名任何档位的请求；声明并给值（`off: none`），该值就会作为档位参数在协议中发送。没有任何写法能把 catalog 映射中的键恢复为「未设置」：这份声明就是对外提供的全部，因此把你要保留的 catalog 档位重述出来。
 
 ### 推理分派的 compat 开关
 
@@ -186,6 +186,7 @@ pi-ai 事件会变为 harness 推理、文本、工具调用、usage 与 finish
 ## 已知限制与暂缓事项
 
 - **settings 能新增或覆盖路由，但不能移除组合路由**：用户层合并在组合 `base` 之上，因此删除 `cordis.yml` 提供的提供方属于组合变更；对该 namespace 执行 `replace` 只会重置用户层。
+- **分层合并对字典键没有删除语义**：settings seam 把组合 `base` 与用户层按键递归合并，因此 base 声明的某个 `reasoningEfforts` 档位、`modelOverrides` 条目或 `compat` 字段，用户层只能覆盖、无法移除——而 `reasoningEfforts` 里缺席本身*就是*语义（「不提供」），于是 base 声明过的档位会一直被提供。`models` 列表是数组、整体替换，这也是规避写法：把该模型改到那里声明。settings seam 的原子叶合并语义在 [#2003](https://github.com/deepseek-harness/deepseek-harness/issues/2003) 跟进。
 - **`headers` 可能承载一条脱敏器看不见的凭据**：profile 的 `headers` 是纯字符串字典，因此设在其中的 `Authorization` 或 `api-key` 会被脱敏后的 `describe()` 原样返回，并被任何配置 UI 渲染出来。请把凭据存为 `apiKeyEnv` 引用；把该字典整体改为只写与其余[协议边界工作](../llm/README.md#known-limitations-and-deferred-work)一并暂缓。
 - **路由的 catalog 不会自我刷新**：catalog 就是 `settings.yaml` 所写的内容，因此模型列表的新鲜度只到最近一次编辑为止。这里没有任何环节会去问提供方它服务哪些模型；路由要多一个模型，得有人写进去。
 - **每条路由只有一种协议格式**：`api` 作用于整条路由，因此混合协议的 catalog 路由（跨 Responses 与 Chat Completions 的 OpenAI 式 catalog）无法承载另一种协议的模型，向这类路由添加它未描述的模型必须点名 `api` 并把全部模型一起迁过去。把该提供方拆成两个路由键是变通办法。
diff --git a/packages/llm/llm-pi-ai/src/catalog.ts b/packages/llm/llm-pi-ai/src/catalog.ts
index 3285d1595a..8f1bc1a43c 100644
--- a/packages/llm/llm-pi-ai/src/catalog.ts
+++ b/packages/llm/llm-pi-ai/src/catalog.ts
@@ -347,9 +347,13 @@ function resolveModelCompat(
     }
     return {}
   }
-  // The installed entry's compat matches its own api, so on an
-  // openai-completions model it is the completions shape.
-  const inherited: OpenAICompletionsCompat | undefined = base?.compat
+  // The installed entry's compat matches the entry's OWN api — a route-level
+  // `api` repoint (an anthropic catalog served through an OpenAI-compatible
+  // gateway) leaves `base.compat` in the other protocol's shape, so it is
+  // inherited only while the resolved api still is the entry's. A repointed
+  // model starts from pi-ai's baseURL-derived detection instead, which is
+  // what a protocol change means for every other compat field too.
+  const inherited: OpenAICompletionsCompat | undefined = base?.api === api ? base.compat : undefined
   return {
     compat: {
       ...inherited,
diff --git a/packages/llm/llm-pi-ai/src/config.ts b/packages/llm/llm-pi-ai/src/config.ts
index 2b824f4cae..7bce3b6376 100644
--- a/packages/llm/llm-pi-ai/src/config.ts
+++ b/packages/llm/llm-pi-ai/src/config.ts
@@ -161,12 +161,14 @@ const compatProfile: z<PiAiCompatProfile> = z.object({
 })
 
 /**
- * Keys are the offered levels, values their wire spellings. `z.const(null)`
- * keeps a valueless key (`off:`) alive through validation — only resolution
- * decides which levels may leave the value empty, so the diagnostic can name
- * the route and model. The assertion narrows schemastery's `Dict`, which
- * types every literal key as required; dict validation is per-present-key, so
- * the runtime shape is the partial record.
+ * Keys are the offered levels, values their wire spellings. A valueless key
+ * (`off:`) survives validation because schemastery passes nullable data
+ * through before any member schema runs — `z.const(null)` only shapes the
+ * error for non-null wrong values and what a configuration surface renders.
+ * Only resolution decides which levels may leave the value empty, so the
+ * diagnostic can name the route and model. The assertion narrows
+ * schemastery's `Dict`, which types every literal key as required; dict
+ * validation is per-present-key, so the runtime shape is the partial record.
  */
 const reasoningEfforts = z.dict(
   z.union([z.string(), z.const(null)]),
diff --git a/packages/llm/llm-pi-ai/tests/adapter.spec.ts b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
index 6f8c2ab116..d2e101505d 100644
--- a/packages/llm/llm-pi-ai/tests/adapter.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
@@ -524,6 +524,39 @@ describe('provider profile lifecycle', () => {
     expect(server.requests[1]).not.toHaveProperty('reasoning_effort')
   })
 
+  it('sends a declared off value as the effort parameter instead of omitting it', async () => {
+    vi.stubEnv('PI_TEST_KEY', 'test-key')
+    const server = await mockServer([{ events: textEvents }])
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmPiAi, {
+      providers: {
+        'acme-gateway': {
+          apiKeyEnv: 'PI_TEST_KEY',
+          api: 'openai-completions',
+          baseURL: `${server.url}/v1`,
+          models: [{
+            id: 'acme-think',
+            contextWindow: 65_536,
+            maxTokens: 4096,
+            reasoningEfforts: { off: 'none', high: 'high' },
+          }],
+        },
+      },
+    })
+
+    // The adapter strips a selected Off to "no reasoning option", and pi-ai's
+    // dispatch reads thinkingLevelMap.off exactly then — so the declared value
+    // still reaches the wire, which is the README's promise for `off: none`.
+    await assemble(ctx, {
+      provider: 'acme-gateway',
+      model: 'acme-think',
+      reasoningEffort: ReasoningEffortId('off'),
+      messages: [],
+    })
+    expect(server.requests[0]).toMatchObject({ reasoning_effort: 'none' })
+  })
+
   it('holds back reasoning_effort when the endpoint cannot take it', async () => {
     vi.stubEnv('PI_TEST_KEY', 'test-key')
     const server = await mockServer([{ events: textEvents }])
diff --git a/packages/llm/llm-pi-ai/tests/catalog.spec.ts b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
index 790e59c260..14cb10df76 100644
--- a/packages/llm/llm-pi-ai/tests/catalog.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
@@ -520,7 +520,7 @@ describe('per-model reasoning efforts', () => {
     expect(getSupportedThinkingLevels(model)).toEqual(['off', 'low', 'high', 'max'])
   })
 
-  it('sends a declared off value on the wire instead of omitting the parameter', () => {
+  it('keeps a declared off value in the map for dispatch to send', () => {
     const model = modelOf(declared([{ id: 'm', reasoningEfforts: { off: 'none', high: 'high' } }]))
     expect(model.thinkingLevelMap?.off).toBe('none')
     expect(getSupportedThinkingLevels(model)).toEqual(['off', 'high'])

From e5d0089d5be77ac193defdd8a43c849222f28c95 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 10:55:11 +0800
Subject: [PATCH 198/516] cleanup(llm-pi-ai): share the model-entry field
 schemas between models and modelOverrides

The duplication gate caught the two schema literals diverging only by
the id field; the shared dict is now the single home, with the id added
where it lives (the entry) and omitted where the dict key carries it.
---
 packages/llm/llm-pi-ai/src/config.ts | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/packages/llm/llm-pi-ai/src/config.ts b/packages/llm/llm-pi-ai/src/config.ts
index 7bce3b6376..e52af4a3f4 100644
--- a/packages/llm/llm-pi-ai/src/config.ts
+++ b/packages/llm/llm-pi-ai/src/config.ts
@@ -175,8 +175,8 @@ const reasoningEfforts = z.dict(
   z.union(THINKING_LEVELS),
 ) as unknown as z<PiAiReasoningEfforts>
 
-const modelProfile: z<PiAiModelProfile> = z.object({
-  id: z.string().required(),
+/** The fields a `models` entry and a `modelOverrides` value share; only the id's home differs. */
+const modelFields = {
   name: z.string(),
   contextWindow: z.number().step(1).min(1),
   maxTokens: z.number().step(1).min(1),
@@ -185,16 +185,15 @@ const modelProfile: z<PiAiModelProfile> = z.object({
   // installed catalog's capability", while `false` disables reasoning.
   reasoningEfforts: z.union([z.const(false), reasoningEfforts]),
   compat: compatProfile,
+}
+
+const modelProfile: z<PiAiModelProfile> = z.object({
+  id: z.string().required(),
+  ...modelFields,
 })
 
 /** A {@link modelProfile} whose id lives in the `modelOverrides` dict key. */
-const modelOverride: z<PiAiModelOverride> = z.object({
-  name: z.string(),
-  contextWindow: z.number().step(1).min(1),
-  maxTokens: z.number().step(1).min(1),
-  reasoningEfforts: z.union([z.const(false), reasoningEfforts]),
-  compat: compatProfile,
-})
+const modelOverride: z<PiAiModelOverride> = z.object(modelFields)
 
 const profile = z.object({
   apiKeyEnv: z.string().role('credential-ref'),

From c480796db4d8ca94f8766f268d09ddf02fc93df3 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 11:06:29 +0800
Subject: [PATCH 199/516] docs(llm-pi-ai): state the composition-base
 assumption for the dict-merge limitation

Maintainer ruling on the review's merge-semantics warning: per-model
reasoning fields belong to the settings document, not cordis.yml entry
config (the shipped composition mounts the adapter dormant), so the
recursive-merge delete gap is a documented posture rather than a tracked
fix; the Known Limitations entry now states the assumption instead of
pointing at the closed #2003.
---
 packages/llm/llm-pi-ai/README.i18n.yaml | 4 ++--
 packages/llm/llm-pi-ai/README.md        | 2 +-
 packages/llm/llm-pi-ai/README.zh.md     | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 1fe2902388..790989c5d6 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: c5ebca23ccb4162b65a6e18132970eaf01a50b84
-README.zh.md: f916462bca915bea37c59f7a33a08e1dcc18c4c7
+README.md: eb67ce889193aadbd694d7aae53e47c7d20703be
+README.zh.md: b4b3e3c208702fa10e5f434a70608702d0576fbd
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index c5ebca23cc..eb67ce8891 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -186,7 +186,7 @@ Recorded response content appends to the next request and does not invalidate it
 ## Known Limitations and Deferred Work
 
 - **Settings can add or override routes, not remove composition routes** — the user layer merges over the composition `base`, so deleting a `cordis.yml`-provided provider is a composition change; `replace` on the namespace only resets the user layer.
-- **The layered merge has no delete for dict keys** — the settings seam merges the composition `base` and the user layer per key, recursively, so a `reasoningEfforts` level, `modelOverrides` entry, or `compat` field the base declares cannot be removed by the user layer, only overridden — and for `reasoningEfforts` absence *is* the meaning ("not offered"), so a base-declared level stays offered. A `models` list is an array and replaces wholesale, which is the workaround: declare the model there instead. Atomic-leaf merge semantics at the settings seam are tracked in [#2003](https://github.com/deepseek-harness/deepseek-harness/issues/2003).
+- **The layered merge has no delete for dict keys** — the settings seam merges the composition `base` and the user layer per key, recursively, so a `reasoningEfforts` level, `modelOverrides` entry, or `compat` field the base declares cannot be removed by the user layer, only overridden — and for `reasoningEfforts` absence *is* the meaning ("not offered"), so a base-declared level stays offered. This only triggers when a `cordis.yml` entry config declares per-model reasoning fields for the same model the user layer edits; the supported posture is to leave those to the settings document (the shipped composition mounts the adapter dormant), and a `models` list is an array replacing wholesale, which is the in-band escape.
 - **`headers` can carry a credential the redactor never sees** — the profile's `headers` dict is plain strings, so `Authorization` or `api-key` set there is returned verbatim by a redacted `describe()` and rendered by any configuration UI. Store credentials as `apiKeyEnv` references; making the dict write-only is deferred with the rest of the [wire-boundary work](../llm/README.md#known-limitations-and-deferred-work).
 - **A route's catalog never refreshes itself** — the catalog is whatever `settings.yaml` says, so a model list is only as current as its last edit. Nothing here queries a provider for the models it serves; a route gains a model when someone writes one.
 - **One wire protocol per route** — `api` applies to the whole route, so a mixed-protocol catalog route (an OpenAI-style catalog spanning Responses and Chat Completions) cannot host a model of the other protocol, and adding a model such a route does not describe requires naming `api` and moving every model onto it. Splitting the provider across two route keys is the workaround.
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index f916462bca..b4b3e3c208 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -186,7 +186,7 @@ pi-ai 事件会变为 harness 推理、文本、工具调用、usage 与 finish
 ## 已知限制与暂缓事项
 
 - **settings 能新增或覆盖路由，但不能移除组合路由**：用户层合并在组合 `base` 之上，因此删除 `cordis.yml` 提供的提供方属于组合变更；对该 namespace 执行 `replace` 只会重置用户层。
-- **分层合并对字典键没有删除语义**：settings seam 把组合 `base` 与用户层按键递归合并，因此 base 声明的某个 `reasoningEfforts` 档位、`modelOverrides` 条目或 `compat` 字段，用户层只能覆盖、无法移除——而 `reasoningEfforts` 里缺席本身*就是*语义（「不提供」），于是 base 声明过的档位会一直被提供。`models` 列表是数组、整体替换，这也是规避写法：把该模型改到那里声明。settings seam 的原子叶合并语义在 [#2003](https://github.com/deepseek-harness/deepseek-harness/issues/2003) 跟进。
+- **分层合并对字典键没有删除语义**：settings seam 把组合 `base` 与用户层按键递归合并，因此 base 声明的某个 `reasoningEfforts` 档位、`modelOverrides` 条目或 `compat` 字段，用户层只能覆盖、无法移除——而 `reasoningEfforts` 里缺席本身*就是*语义（「不提供」），于是 base 声明过的档位会一直被提供。只有 `cordis.yml` entry config 为用户层正在编辑的同一模型声明了按模型推理字段才会触发；受支持的姿态是把这些字段留给 settings 文档（shipped 组合以休眠方式挂载该适配器），且 `models` 列表是数组、整体替换，这是体制内的出口。
 - **`headers` 可能承载一条脱敏器看不见的凭据**：profile 的 `headers` 是纯字符串字典，因此设在其中的 `Authorization` 或 `api-key` 会被脱敏后的 `describe()` 原样返回，并被任何配置 UI 渲染出来。请把凭据存为 `apiKeyEnv` 引用；把该字典整体改为只写与其余[协议边界工作](../llm/README.md#known-limitations-and-deferred-work)一并暂缓。
 - **路由的 catalog 不会自我刷新**：catalog 就是 `settings.yaml` 所写的内容，因此模型列表的新鲜度只到最近一次编辑为止。这里没有任何环节会去问提供方它服务哪些模型；路由要多一个模型，得有人写进去。
 - **每条路由只有一种协议格式**：`api` 作用于整条路由，因此混合协议的 catalog 路由（跨 Responses 与 Chat Completions 的 OpenAI 式 catalog）无法承载另一种协议的模型，向这类路由添加它未描述的模型必须点名 `api` 并把全部模型一起迁过去。把该提供方拆成两个路由键是变通办法。

From c4c2355b5047675e67b1921591f40eb066fa69a2 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 11:30:14 +0800
Subject: [PATCH 200/516] fix(host): harden skill.invoke at the enforcement
 boundary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review fixes: recheck isUserInvocable on the loaded definition (list and
get collect independently, so a provider change between them could swap in
a user-disabled body — the skill-tool execute template's second check);
thread the carrier signal through the lookup and refuse an abandoned
caller's turn as cancelled; fold lookup/loader failures into the
structured internal error the list face already uses; refuse cwd-less
sessions with the skill.list stance; and reject blank trailing text at the
wire schema instead of relying on client trimming.
---
 packages/host/apiproxy/src/api-proxy.ts       |  60 +++++++---
 .../host/apiproxy/src/api/skills.schema.ts    |   7 +-
 packages/host/apiproxy/src/api/skills.ts      |  10 +-
 packages/host/apiproxy/src/fetch/handler.ts   |   2 +-
 .../apiproxy/tests/api-proxy-commands.spec.ts | 104 ++++++++++++++++--
 .../host/apiproxy/tests/rpc-schemas.spec.ts   |   2 +
 6 files changed, 155 insertions(+), 30 deletions(-)

diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 3970a801a3..0abfb8c9c0 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -2390,32 +2390,58 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         }
       },
 
-      async invoke(request) {
+      async invoke(request, signal) {
         const { sessionId, name, text } = request.payload
         const resolved = await turnAgentFor<{ accepted: true }>(request, sessionId)
         if ('refused' in resolved) return resolved.refused
         const agent = resolved.agent
+        if (agent.session.header.cwd === undefined) {
+          // Same stance as skill.list: a cwd-less header is a pre-project
+          // legacy log, and skill discovery has no root to resolve against.
+          return err(request, { code: 'internal', message: `session "${sessionId}" has no project cwd`, details: {} })
+        }
         const skillRegistry = ctx.get('skills')
         if (skillRegistry === undefined) {
           return err(request, { code: 'internal', message: 'skill registry is absent: this deployment does not mount @deepseek-ai/dsh-skill in its composition (cordis.yml or explicit assembly)', details: {} })
         }
-        const lookup = { cwd: agent.session.header.cwd }
-        // isSkillName guards the registry contract; an ill-formed name is
-        // indistinguishable from an absent one for the caller.
-        const summary = isSkillName(name)
-          ? (await skillRegistry.list(lookup)).find(skill => skill.name === name)
-          : undefined
-        if (summary === undefined) {
-          return err(request, { code: 'skill-not-found', message: `skill "${name}" is unknown in this workspace`, details: { name } })
+        const lookup = { cwd: agent.session.header.cwd, signal }
+        let skill
+        try {
+          // isSkillName guards the registry contract; an ill-formed name is
+          // indistinguishable from an absent one for the caller.
+          const summary = isSkillName(name)
+            ? (await skillRegistry.list(lookup)).find(candidate => candidate.name === name)
+            : undefined
+          if (summary === undefined) {
+            return err(request, { code: 'skill-not-found', message: `skill "${name}" is unknown in this workspace`, details: { name } })
+          }
+          // The operation boundary owns user-invocation policy: client menus
+          // filtering their candidates is an affordance, not enforcement.
+          if (!isUserInvocable(summary)) {
+            return err(request, { code: 'skill-not-invocable', message: `skill "${name}" is not available for user invocation`, details: { name } })
+          }
+          const loaded = await skillRegistry.get(name, lookup)
+          if (loaded === undefined) {
+            return err(request, { code: 'skill-not-found', message: `skill "${name}" is unknown in this workspace`, details: { name } })
+          }
+          // Recheck on the loaded definition (the skill-tool execute template):
+          // list and get collect independently, so a provider change between
+          // the two awaits can swap the winning candidate for a user-disabled
+          // one — the boundary must judge what it actually injects.
+          if (!isUserInvocable(loaded)) {
+            return err(request, { code: 'skill-not-invocable', message: `skill "${name}" is not available for user invocation`, details: { name } })
+          }
+          skill = loaded
+        } catch (error: unknown) {
+          if (signal.aborted) {
+            return err(request, { code: 'cancelled', message: 'skill invocation cancelled', details: {} })
+          }
+          return err(request, { code: 'internal', message: `skill invocation failed: ${String(error)}`, details: {} })
         }
-        // The operation boundary owns user-invocation policy: client menus
-        // filtering their candidates is an affordance, not enforcement.
-        if (!isUserInvocable(summary)) {
-          return err(request, { code: 'skill-not-invocable', message: `skill "${name}" is not available for user invocation`, details: { name } })
-        }
-        const skill = await skillRegistry.get(name, lookup)
-        if (skill === undefined) {
-          return err(request, { code: 'skill-not-found', message: `skill "${name}" is unknown in this workspace`, details: { name } })
+        if (signal.aborted) {
+          // The caller already gave up (unary deadline or navigation): a turn
+          // it will never observe must not start.
+          return err(request, { code: 'cancelled', message: 'skill invocation cancelled', details: {} })
         }
         const body = renderSkillContent(skill)
         const source: SkillInvocationSource = { kind: 'skill-invocation', name, ...text === undefined ? {} : { args: text } }
diff --git a/packages/host/apiproxy/src/api/skills.schema.ts b/packages/host/apiproxy/src/api/skills.schema.ts
index c1ee1024a3..1741a93a46 100644
--- a/packages/host/apiproxy/src/api/skills.schema.ts
+++ b/packages/host/apiproxy/src/api/skills.schema.ts
@@ -27,11 +27,14 @@ export const skillListValueSchema = z.object({
   skills: z.array(skillEntrySchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'skill.list'>>>
 
-/** skill.invoke request payload. */
+/**
+ * skill.invoke request payload. `text` is the user's trailing message; a
+ * blank one stays off the wire (the boundary, not client courtesy, refuses it).
+ */
 export const skillInvokeRequestSchema = z.object({
   sessionId: sessionIdSchema,
   name: z.string().min(1),
-  text: z.string().optional(),
+  text: z.string().min(1).optional(),
 }) satisfies z.ZodType<Wire<RequestPayload<'skill.invoke'>>>
 
 /** skill.invoke response value. */
diff --git a/packages/host/apiproxy/src/api/skills.ts b/packages/host/apiproxy/src/api/skills.ts
index 2ade72efb9..698a9f0190 100644
--- a/packages/host/apiproxy/src/api/skills.ts
+++ b/packages/host/apiproxy/src/api/skills.ts
@@ -29,9 +29,13 @@ export interface SkillsApi {
    * Injects one user-invocable skill into the addressed agent as a user-role
    * message (the canonical `<skill_content>` rendering, with `text` appended
    * when present) and starts a turn. The host enforces user-invocation policy
-   * here: a model-only or unknown name is refused regardless of what a client
-   * menu offered. Session-backed subagents reject with `agent-busy`.
+   * here — on the discovery summary and again on the loaded definition, so a
+   * catalog change between the two lookups cannot slip a user-disabled body
+   * through — a model-only or unknown name is refused regardless of what a
+   * client menu offered. The carrier's request signal aborts the skill
+   * lookup and refuses injection once the caller has given up (`cancelled`).
+   * Session-backed subagents reject with `agent-busy`.
    */
-  invoke(request: RpcRequest<{ sessionId: SessionId; name: string; text?: string }>):
+  invoke(request: RpcRequest<{ sessionId: SessionId; name: string; text?: string }>, signal: AbortSignal):
   Promise<RpcResponse<{ accepted: true }>>
 }
diff --git a/packages/host/apiproxy/src/fetch/handler.ts b/packages/host/apiproxy/src/fetch/handler.ts
index 914c425e91..8e098680fa 100644
--- a/packages/host/apiproxy/src/fetch/handler.ts
+++ b/packages/host/apiproxy/src/fetch/handler.ts
@@ -109,7 +109,7 @@ const UNARY_ROUTES: UnaryRoutes = {
   'command.list': { schema: commandListRequestSchema, invoke: (api, r) => api.commands.list(r) },
   'command.execute': { schema: commandExecuteRequestSchema, invoke: (api, r, signal) => api.commands.execute(r, signal) },
   'skill.list': { schema: skillListRequestSchema, invoke: (api, r) => api.skills.list(r) },
-  'skill.invoke': { schema: skillInvokeRequestSchema, invoke: (api, r) => api.skills.invoke(r) },
+  'skill.invoke': { schema: skillInvokeRequestSchema, invoke: (api, r, signal) => api.skills.invoke(r, signal) },
   'goal.create': { schema: goalCreateRequestSchema, invoke: (api, r) => api.goals.create(r) },
   'goal.edit': { schema: goalEditRequestSchema, invoke: (api, r) => api.goals.edit(r) },
   'goal.pause': { schema: goalPauseRequestSchema, invoke: (api, r) => api.goals.pause(r) },
diff --git a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
index 7d7062023e..5b61011370 100644
--- a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
@@ -305,6 +305,8 @@ describe('skill.invoke', () => {
     return { agent, followup }
   }
 
+  const live = () => new AbortController().signal
+
   it('injects a user-invocable skill as a user message with the invocation source', async () => {
     const ctx = await harness()
     registerInvokeSkills(ctx)
@@ -312,7 +314,7 @@ describe('skill.invoke', () => {
     const { agent, followup } = invokableAgent(ctx)
     const value = expectOk(await api.skills.invoke(request({
       sessionId: agent.id, name: 'user-only', text: 'and check the fixture',
-    })))
+    }), live()))
     expect(value).toEqual({ accepted: true })
     expect(followup).toHaveBeenCalledTimes(1)
     const message = followup.mock.calls[0]?.[0] as UserMessage
@@ -330,7 +332,7 @@ describe('skill.invoke', () => {
     registerInvokeSkills(ctx)
     const api = createApiProxy(ctx, DEFAULTS)
     const { agent, followup } = invokableAgent(ctx)
-    expectOk(await api.skills.invoke(request({ sessionId: agent.id, name: 'user-only' })))
+    expectOk(await api.skills.invoke(request({ sessionId: agent.id, name: 'user-only' }), live()))
     const message = followup.mock.calls[0]?.[0] as UserMessage
     expect(message.source).toEqual({ kind: 'skill-invocation', name: 'user-only' })
     const text = (message.content[0] as { text: string }).text
@@ -342,39 +344,127 @@ describe('skill.invoke', () => {
     registerInvokeSkills(ctx)
     const api = createApiProxy(ctx, DEFAULTS)
     const { agent, followup } = invokableAgent(ctx)
-    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'model-only' })))
+    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'model-only' }), live()))
     expect(error.code).toBe('skill-not-invocable')
     expect(followup).not.toHaveBeenCalled()
   })
 
+  it('rechecks user policy on the loaded definition (list/get race)', async () => {
+    const ctx = await harness()
+    // The provider flips the skill user-invocable in list but user-disabled
+    // in get — the window a provider change between the two collects opens.
+    ctx.skills.registerProvider(() => ({
+      name: 'flipping',
+      list: () => Promise.resolve([{
+        name: 'flipper', description: 'Race probe',
+        invocation: { modelInvocable: false, userInvocable: true },
+        source: 'custom', provider: 'flipping', rank: 0, locator: null,
+      }]),
+      get: () => Promise.resolve({
+        name: 'flipper', description: 'Race probe',
+        invocation: { modelInvocable: false, userInvocable: false },
+        source: 'custom', provider: 'flipping',
+        content: 'Must never inject.',
+      }),
+    }))
+    const api = createApiProxy(ctx, DEFAULTS)
+    const { agent, followup } = invokableAgent(ctx)
+    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'flipper' }), live()))
+    expect(error.code).toBe('skill-not-invocable')
+    expect(followup).not.toHaveBeenCalled()
+  })
+
+  it('reports skill-not-found when the summary wins but the load returns nothing', async () => {
+    const ctx = await harness()
+    ctx.skills.registerProvider(() => ({
+      name: 'vanishing',
+      list: () => Promise.resolve([{
+        name: 'ghost', description: 'Vanishes on load',
+        invocation: { modelInvocable: false, userInvocable: true },
+        source: 'custom', provider: 'vanishing', rank: 0, locator: null,
+      }]),
+      get: () => Promise.resolve(undefined),
+    }))
+    const api = createApiProxy(ctx, DEFAULTS)
+    const { agent, followup } = invokableAgent(ctx)
+    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'ghost' }), live()))
+    expect(error.code).toBe('skill-not-found')
+    expect(followup).not.toHaveBeenCalled()
+  })
+
   it('rejects an unknown or invalid skill name', async () => {
     const ctx = await harness()
     registerInvokeSkills(ctx)
     const api = createApiProxy(ctx, DEFAULTS)
     const { agent } = invokableAgent(ctx)
-    const missing = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'absent-skill' })))
+    const missing = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'absent-skill' }), live()))
     expect(missing.code).toBe('skill-not-found')
-    const invalid = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'Not A Name' })))
+    const invalid = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'Not A Name' }), live()))
     expect(invalid.code).toBe('skill-not-found')
   })
 
+  it('folds a loader failure into a structured internal error', async () => {
+    const ctx = await harness()
+    ctx.skills.registerProvider(() => ({
+      name: 'exploding',
+      list: () => Promise.resolve([{
+        name: 'grenade', description: 'Loader throws',
+        invocation: { modelInvocable: false, userInvocable: true },
+        source: 'custom', provider: 'exploding', rank: 0, locator: null,
+      }]),
+      get: () => Promise.reject(new Error('disk exploded')),
+    }))
+    const api = createApiProxy(ctx, DEFAULTS)
+    const { agent, followup } = invokableAgent(ctx)
+    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'grenade' }), live()))
+    expect(error.code).toBe('internal')
+    expect(error.message).toContain('skill invocation failed')
+    expect(followup).not.toHaveBeenCalled()
+  })
+
+  it('refuses to start a turn the caller already abandoned', async () => {
+    const ctx = await harness()
+    registerInvokeSkills(ctx)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const { agent, followup } = invokableAgent(ctx)
+    const abort = new AbortController()
+    abort.abort()
+    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'user-only' }), abort.signal))
+    expect(error.code).toBe('cancelled')
+    expect(followup).not.toHaveBeenCalled()
+  })
+
   it('surfaces a followup refusal as agent-busy', async () => {
     const ctx = await harness()
     registerInvokeSkills(ctx)
     const api = createApiProxy(ctx, DEFAULTS)
     const { agent, followup } = invokableAgent(ctx)
     followup.mockImplementation(() => { throw new Error('inbox closed') })
-    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'user-only' })))
+    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'user-only' }), live()))
     expect(error.code).toBe('agent-busy')
   })
 
+  it('refuses a cwd-less session with the skill.list stance', async () => {
+    const ctx = await harness()
+    registerInvokeSkills(ctx)
+    const api = createApiProxy(ctx, DEFAULTS)
+    const session = ctx.sessions.create(undefined)
+    const inbox = new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} })
+    const followup = vi.fn()
+    ctx.agents.register({ id: session.id, session, inbox, status: 'idle', ctx, followup } as unknown as Agent)
+    const error = expectErr(await api.skills.invoke(request({ sessionId: session.id, name: 'user-only' }), live()))
+    expect(error.code).toBe('internal')
+    expect(error.message).toContain('has no project cwd')
+    expect(followup).not.toHaveBeenCalled()
+  })
+
   it('fails loud with internal when the skill registry is not mounted', async () => {
     const ctx = await harness({ skills: false })
     const api = createApiProxy(ctx, DEFAULTS)
     const session = ctx.sessions.create(undefined, { meta: { cwd: '/proj' } })
     const inbox = new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} })
     ctx.agents.register({ id: session.id, session, inbox, status: 'idle', ctx, followup: vi.fn() } as unknown as Agent)
-    const error = expectErr(await api.skills.invoke(request({ sessionId: session.id, name: 'user-only' })))
+    const error = expectErr(await api.skills.invoke(request({ sessionId: session.id, name: 'user-only' }), live()))
     expect(error.code).toBe('internal')
     expect(error.message).toContain('skill registry is absent')
   })
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
index 253ac92fdf..972ccd3621 100644
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -416,6 +416,8 @@ describe('skills domain schemas', () => {
       .toBe('check it')
     expect(() => skillInvokeRequestSchema.parse({ sessionId: 's1', name: '' })).toThrow()
     expect(() => skillInvokeRequestSchema.parse({ name: 'user-only' })).toThrow()
+    // A blank trailing text is refused at the wire boundary, not by client courtesy.
+    expect(() => skillInvokeRequestSchema.parse({ sessionId: 's1', name: 'user-only', text: '' })).toThrow()
     expect(skillInvokeValueSchema.parse({ accepted: true })).toEqual({ accepted: true })
     expect(() => skillInvokeValueSchema.parse({ accepted: false })).toThrow()
   })

From 31ed85900d0707b309e3859484a5b3f4964721fb Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 11:30:16 +0800
Subject: [PATCH 201/516] fix(client): review fixes for invocation rendering
 and turn boundaries
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The user-turn predicate (opensUserTurn) unifies the three parallel
consumers a new node kind silently missed — produced-files turn reset,
retry liveness, own-words force-scroll — so a skill invocation behaves as
the turn opener it is. The menu marker resolves through ctx.locale.bind
instead of a hand-rolled snapshot lookup; the dead legacy <skill> render
arm goes with the removal cut; command-over-skill name precedence is now
documented at the matchEnter seam; and the emptied replacement catalog
keeps the no-reload sentence, with the never-published residual recorded
in the Agent Note.
---
 ...8-user-explicit-skill-invocation.i18n.yaml |  4 ++--
 ...26-08-08-user-explicit-skill-invocation.md |  1 +
 ...08-08-user-explicit-skill-invocation.zh.md |  1 +
 .../client/connection/src/client/fixture.ts   |  2 +-
 packages/client/runtime/src/client/index.ts   |  1 +
 .../src/client/sessions/conversation.ts       | 14 +++++++++++++
 .../src/client/chat/ChatView.tsx              | 10 +++++----
 .../src/client/chat/MessageItem.tsx           | 20 ++++++++----------
 .../src/client/turn-deliverables.ts           |  3 ++-
 .../tests/produced-files.spec.tsx             | 21 +++++++++++++++++++
 packages/client/ui-skill/README.i18n.yaml     |  4 ++--
 packages/client/ui-skill/README.md            |  2 +-
 packages/client/ui-skill/README.zh.md         |  2 +-
 packages/client/ui-skill/src/client/index.ts  | 11 +++++++---
 .../ui-skill/tests/browser-plugin.spec.ts     |  3 ++-
 packages/skill/tool-skill/README.i18n.yaml    |  4 ++--
 packages/skill/tool-skill/README.md           |  2 +-
 packages/skill/tool-skill/README.zh.md        |  2 +-
 packages/skill/tool-skill/src/index.ts        |  1 +
 19 files changed, 77 insertions(+), 31 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
index ed9de78dbb..4c36032f35 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.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 .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
-2026-08-08-user-explicit-skill-invocation.md: 9249ee5c9c712e9c6aa827e97178f352728ed927
-2026-08-08-user-explicit-skill-invocation.zh.md: f15975c3b13fbf76e036fcece30253e78e7b417d
+2026-08-08-user-explicit-skill-invocation.md: abe6a05283359b81ff1c3cab754d0230e599e4a0
+2026-08-08-user-explicit-skill-invocation.zh.md: e72e49236ffd2c6f664e01abbd69665eec8328e9
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
index 9249ee5c9c..abe6a05283 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
@@ -34,3 +34,4 @@ Peer-product survey (Pi, OpenCode, Claude Code, Kimi Code, Codex, DeepSeek-Reaso
 - Every user-invocable skill invocation now costs its full rendered body unconditionally — the price of determinism the peer survey showed everyone pays.
 - The `skill-invocation` source rides `user/message`, so Model-visible ⟺ logged holds with no new event type, and replay/UI read metadata rather than text markers.
 - TUI and ACP can adopt `skill.invoke` later for the same semantics; until then the TUI's client-side expansion remains its own path.
+- Accepted residual of dropping the per-injection preamble: the no-reload framing rides only the catalog, and a workspace whose skills are all user-only never publishes a first catalog — an injection can arrive with no framing at all, and the model may redundantly try the `skill` tool once (the replacement catalog's empty arm carries the sentence; the never-published case does not). Publishing a catalog for framing alone was judged worse than that one recoverable error.
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
index f15975c3b1..e72e49236f 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
@@ -34,3 +34,4 @@ Status: implemented
 - 每一次用户可调用 skill 的调用现在都无条件付出其完整渲染正文的成本——这是确定性的代价，同类调研表明所有产品都在支付。
 - `skill-invocation` 来源搭乘 `user/message`，因此「模型可见 ⟺ 已记录」在不新增事件类型的情况下继续成立，回放与 UI 读取的是元数据而非文本标记。
 - TUI 与 ACP 之后可以为同样的语义采用 `skill.invoke`；在那之前，TUI 的客户端展开仍是它自己的路径。
+- 放弃逐次注入前导语后被接受的残余：no-reload framing 只搭乘目录，而 skill 全部为仅用户的工作区永远不会发布首个目录——注入可能在完全没有 framing 的情况下到达，模型可能多余地调用一次 `skill` 工具（替换目录的空臂携带该句；从未发布的情形没有）。仅为 framing 而发布目录被判定比这一次可恢复的错误更糟。
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 75653d43e3..23b1931cfc 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2779,7 +2779,7 @@ export class FixtureApiClient extends AbstractApiClient {
       case 'command.list': return this.api.commands.list(request)
       case 'command.execute': return this.api.commands.execute(request, signal)
       case 'skill.list': return this.api.skills.list(request)
-      case 'skill.invoke': return this.api.skills.invoke(request)
+      case 'skill.invoke': return this.api.skills.invoke(request, signal)
       case 'goal.create': return this.api.goals.create(request)
       case 'goal.edit': return this.api.goals.edit(request)
       case 'goal.pause': return this.api.goals.pause(request)
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index a0aa4df482..3864338e28 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -45,6 +45,7 @@ export { createSnapshotStore, defineStore, shallowEqual } from './contract/store
 export type {
   EngineStoreHandle, EngineStoreInstance, ObservableSnapshot, SnapshotStore,
 } from './contract/store.ts'
+export { opensUserTurn } from './sessions/conversation.ts'
 export type {
   AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
   AssistantTiming, CodeSubCall, CommandNode, CompactionSummaryNode, ComposerPhase,
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index d66faf5e95..1ced1b916e 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -258,6 +258,20 @@ export interface CommandNode {
   outcome: { kind: 'success' | 'error'; text?: string } | null
 }
 
+/**
+ * Whether a node opens a user turn on the transcript surface. A direct user
+ * message and a user-explicit skill invocation both start the turn the next
+ * assistant answer closes; parallel consumers (turn boundaries, retry
+ * liveness, own-words scrolling) share this one predicate instead of each
+ * re-encoding the kind list. Steering stays out: an interjection lands
+ * mid-turn and closes nothing.
+ * @param node - any conversation node.
+ * @returns true for the user-turn-opening kinds.
+ */
+export function opensUserTurn(node: Pick<ConversationNode, 'kind'>): boolean {
+  return node.kind === 'user' || node.kind === 'skill-invocation'
+}
+
 /** Finalized conversation node union (kind discriminates; seq is the React key). */
 export type ConversationNode =
   | UserMessageNode
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index b0907f5a80..a841ba6751 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -24,6 +24,7 @@
 import {
   memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
 } from 'react'
+import { opensUserTurn } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   CodeSubCall, CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -118,7 +119,7 @@ function activeRetrySeq(nodes: readonly ConversationNode[], running: boolean): n
     const node = nodes[index]
     if (node === undefined) continue
     if (node.kind === 'model-retry') return node.retryState === 'cancelled' ? null : node.seq
-    if (node.kind === 'assistant' || node.kind === 'user') return null
+    if (node.kind === 'assistant' || opensUserTurn(node)) return null
   }
   return null
 }
@@ -447,10 +448,11 @@ export function ChatView({
       return
     }
     firstSeqRef.current = firstSeq
-    // Own words must be visible: a new trailing user node force-scrolls
-    // (send lives in the composer, so arrival is detected here, not armed there).
+    // Own words must be visible: a new trailing user-turn node (a prompt or an
+    // explicit skill invocation) force-scrolls (send lives in the composer, so
+    // arrival is detected here, not armed there).
     const appendedUser = lastKey !== lastKeyRef.current
-      && lastItem !== undefined && lastItem.kind === 'node' && lastItem.node.kind === 'user'
+      && lastItem !== undefined && lastItem.kind === 'node' && opensUserTurn(lastItem.node)
     const appendedSteering = lastSteeringId !== null && lastSteeringId !== lastSteeringIdRef.current
     const tipMoved = followSigRef.current !== followSig
     lastKeyRef.current = lastKey
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
index 661dd0cda5..af2afd9792 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
@@ -138,29 +138,27 @@ function TurnErrorItem({ node, t }: {
 /**
  * Display projection of reference forms in a user bubble (free geometry — no
  * textarea alignment constraint here); everything else stays plain text. The
- * logged model text remains the single truth; this is presentation only. Two
- * shapes decorate: legacy `<skill>name</skill>` spans (pre-decision-21
- * history) and plain-text `/name` / `@name` word-boundary tokens (decision
- * 21: the sent text IS the reference — the bubble uses the same plainest
- * token scan as the composer, minus the lexicon: sent tokens were validated
- * at compose time, so shape alone decorates).
+ * logged model text remains the single truth; this is presentation only.
+ * Plain-text `/name` / `@name` word-boundary tokens decorate (decision 21:
+ * the sent text IS the reference — the bubble uses the same plainest token
+ * scan as the composer, minus the lexicon: sent tokens were validated at
+ * compose time, so shape alone decorates).
  */
 function projectUserText(text: string): ReactNode {
-  const re = /<skill>([^<]+)<\/skill>|(^|\s)([/@][\w-]+)(?=\s|$)/g
+  const re = /(^|\s)([/@][\w-]+)(?=\s|$)/g
   const parts: ReactNode[] = []
   let cursor = 0
   let m: RegExpExecArray | null
   while ((m = re.exec(text)) !== null) {
-    const legacy = m[1] !== undefined
-    const tokenStart = legacy ? m.index : m.index + (m[2]?.length ?? 0)
-    const label = legacy ? `/${m[1]}` : m[3] ?? ''
+    const tokenStart = m.index + (m[1]?.length ?? 0)
+    const label = m[2] ?? ''
     if (tokenStart > cursor) parts.push(<MessageText key={cursor} text={text.slice(cursor, tokenStart)} />)
     parts.push(
       <span key={tokenStart} className={css.refChip} data-ref-chip={label.startsWith('@') ? 'subagent' : 'skill'}>
         {label}
       </span>,
     )
-    cursor = legacy ? m.index + m[0].length : tokenStart + label.length
+    cursor = tokenStart + label.length
   }
   if (parts.length === 0) return <MessageText text={text} />
   if (cursor < text.length) parts.push(<MessageText key={cursor} text={text.slice(cursor)} />)
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index c9754d1da4..b8886be0df 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -3,6 +3,7 @@
  * nodes. Client-only and model-free: the vocabulary is the mutation tools'
  * own follow-along `locations`, never the closing prose.
  */
+import { opensUserTurn } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
@@ -62,7 +63,7 @@ export function producedForClosing(nodes: readonly ConversationNode[], seq: numb
       }
       continue
     }
-    if (node.kind === 'user') {
+    if (opensUserTurn(node)) {
       turn = undefined
       pending = []
       seen = new Set()
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index 49e41ebd86..473defc4e6 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -73,6 +73,27 @@ describe('producedForClosing derivation', () => {
     expect(producedForClosing(nodes, 999)).toEqual([])
   })
 
+  it('treats a user-explicit skill invocation as a turn boundary', () => {
+    // The injection opens a user turn exactly like a typed prompt: files
+    // written before it must not spill into the turn its answer closes.
+    const skillInvocation = {
+      kind: 'skill-invocation' as const, seq: 4, time: 4_000,
+      name: 'hidden-demo',
+      content: [{ type: 'text', text: '<skill_content name="hidden-demo">x</skill_content>' }] as never,
+      source: null,
+    }
+    const nodes: ConversationNode[] = [
+      user(1, 'write things'),
+      assistant(2, 'wrote', 1),
+      wrote(3, 'a', 'stale.txt'),
+      skillInvocation,
+      wrote(5, 'b', 'fresh.txt'),
+      assistant(6, 'followed the skill', 2),
+    ]
+    expect(producedForClosing(nodes, 6)).toEqual(['fresh.txt'])
+    expect(producedForClosing(nodes, 6)).not.toContain('stale.txt')
+  })
+
   it('counts a generic edit and never spills across the turn boundary', () => {
     const inserted = (seq: number, callId: string, path: string): ToolResultNode => ({
       ...toolResult(seq, callId, 'str_replace_editor'),
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index cb9eeef56e..5b80baa912 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/client/ui-skill/README.md
-README.md: c888622bc92b038413c7d0ebf63abb61b483f6f5
-README.zh.md: 3bbbc90186726356c53f375bb664d678c4926988
+README.md: ea3dbf3592995903422ec951e20c911082370dbe
+README.zh.md: 5b8886e67973af9a594ff6aa2e9295f112a9f3e3
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index c888622bc9..ea3dbf3592 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Skill invocation source, browser half: registers the `/`-trigger `skill` source into `ctx.slash`. Ordinary-session candidates come from the `skill.list` RPC addressed by the per-call `ClientSessionContext` projection's `{sessionId}`, with the host resolving `cwd` from the session header. The host serves every user-invocable skill; a `modelInvocable: false` entry (a `disable-model-invocation` skill, whose only entry point is this path) wears the user-only marker as a description prefix in the active language. Catalog-addressed continuable children resolve no skill candidates locally because the existing skill RPC requires an attached session; viewing their persisted history must not activate them. Catalogs cache per ordinary session with a single-flight fetch; the scope-birth `warm` hook prewarms the session's entry and `connection/reset` clears everything. Results filter by `startsWith(query)`.
 
-A menu pick or an entered `/name [args]` line claims the composer into an args-tolerant `skill.invoke` transaction (`matchEnter` strong-waits the catalog; an unknown name answers undefined and stays a plain prompt). Submit trims the args, keeps blank args off the wire, and folds an RPC refusal into the composer's error outcome; the host renders the skill body and injects it as a user message before starting the turn, so invocation is deterministic for every user-invocable skill. The RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument. Draft chip visuals still derive from the `lexicon` scan; the legacy `<skill>name</skill>` reference codec is gone (decision 21 removal cut) and `matchSpace` stays unimplemented — menu and enter own the skill flows.
+A menu pick or an entered `/name [args]` line claims the composer into an args-tolerant `skill.invoke` transaction (`matchEnter` strong-waits the catalog; an unknown name answers undefined and stays a plain prompt). A skill name shared with a host command resolves to the command: adjudication polls sources in registration order and the web bundle mounts ui-command ahead of this source — deliberate precedence, matching peer products. Submit trims the args, keeps blank args off the wire, and folds an RPC refusal into the composer's error outcome; the host renders the skill body and injects it as a user message before starting the turn, so invocation is deterministic for every user-invocable skill. The RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument. Draft chip visuals still derive from the `lexicon` scan; the legacy `<skill>name</skill>` reference codec is gone (decision 21 removal cut) and `matchSpace` stays unimplemented — menu and enter own the skill flows.
 
 A failed `skill.list` throws from `candidates`, which the slash shell logs and folds into a silent menu-group drop — the menu shows only pending/ready states.
 
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 3bbbc90186..5b8886e679 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -4,7 +4,7 @@
 
 skill（技能）调用 source 的浏览器端：把 `/` 触发的 `skill` source 注册进 `ctx.slash`。普通会话的候选来自 `skill.list` RPC，以每次调用的 `ClientSessionContext` 投影中的 `{sessionId}` 寻址，host 从会话 header 解析 `cwd`。宿主提供每一个用户可调用的 skill；`modelInvocable: false` 的条目（即 `disable-model-invocation` skill，此路径是其唯一入口）会以当前语言把仅限用户标记作为描述前缀带上。由目录寻址的可继续 subagent 在客户端解析为没有 skill 候选，因为现有 skill RPC 要求会话已挂载；查看其持久化历史不得激活它。目录按普通会话缓存，拉取走 single-flight；scope 创建时的 `warm` 钩子预热该会话的缓存项，`connection/reset` 清空全部缓存。结果按 `startsWith(query)` 过滤。
 
-菜单 pick 或回车提交的一行 `/name [args]` 会把 composer 认领进一个容忍参数的 `skill.invoke` 事务（`matchEnter` 强等目录；未知名称应答 undefined，保持为普通提示词）。提交时会修剪参数、让空白参数不上协议，并把 RPC 拒绝折叠进 composer 的错误结局；宿主在开启轮次之前渲染 skill 正文并将其作为用户消息注入，因此对每一个用户可调用的 skill，调用都是确定性的。RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务。草稿 chip 视觉仍由 `lexicon` 扫描派生；旧的 `<skill>name</skill>` 引用 codec 已经移除（决策 21 的移除裁定），`matchSpace` 保持不实现——skill 流程归菜单与回车所有。
+菜单 pick 或回车提交的一行 `/name [args]` 会把 composer 认领进一个容忍参数的 `skill.invoke` 事务（`matchEnter` 强等目录；未知名称应答 undefined，保持为普通提示词）。与宿主命令同名的 skill 名解析为命令：裁决按注册顺序轮询各 source，而 web bundle 把 ui-command 挂载在本 source 之前——这是有意的优先级，与同行产品一致。提交时会修剪参数、让空白参数不上协议，并把 RPC 拒绝折叠进 composer 的错误结局；宿主在开启轮次之前渲染 skill 正文并将其作为用户消息注入，因此对每一个用户可调用的 skill，调用都是确定性的。RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务。草稿 chip 视觉仍由 `lexicon` 扫描派生；旧的 `<skill>name</skill>` 引用 codec 已经移除（决策 21 的移除裁定），`matchSpace` 保持不实现——skill 流程归菜单与回车所有。
 
 `skill.list` 失败时 `candidates` 抛出异常，slash 壳层记录日志并折叠为静默的菜单组丢弃——菜单只显示 pending／ready 状态。
 
diff --git a/packages/client/ui-skill/src/client/index.ts b/packages/client/ui-skill/src/client/index.ts
index 3e23cc997b..a73370b8ff 100644
--- a/packages/client/ui-skill/src/client/index.ts
+++ b/packages/client/ui-skill/src/client/index.ts
@@ -121,8 +121,9 @@ export function apply(ctx: ClientContext): void {
     for (const key of [...fetches.keys()]) invalidate(key)
   }
 
-  /** User-only marker in the active language (the menu hint is plain text, resolved at candidate time). */
-  const userOnlyHint = (): string => ctx.locale.getSnapshot().active === 'zh' ? zh['menu.userOnly'] : en['menu.userOnly']
+  // The bound translate resolves against the registered dictionaries with the
+  // locale service's own fallback ladder; candidate-time reads stay plain text.
+  const t = ctx.locale.bind(NS)
 
   /**
    * Args-tolerant claim for one skill: token `/name ` plus the skill.invoke
@@ -159,7 +160,7 @@ export function apply(ctx: ClientContext): void {
           name: skill.name,
           // The user-only marker rides the description (the menu's only
           // secondary text); `hint` is the claim-state ghost text, not a badge.
-          description: skill.modelInvocable ? skill.description : `${userOnlyHint()} · ${skill.description}`,
+          description: skill.modelInvocable ? skill.description : `${t('menu.userOnly')} · ${skill.description}`,
         }))
     },
     warm(session) {
@@ -183,6 +184,10 @@ export function apply(ctx: ClientContext): void {
     onPick({ candidate, session }) {
       return invokeClaim(session, candidate.name)
     },
+    // Adjudication polls sources in registration order and the web bundle
+    // mounts ui-command first, so a name shared with a host command claims as
+    // the command — deliberate precedence (commands are explicit host
+    // features; peer products resolve the collision the same way), not a race.
     async matchEnter(session, line, signal) {
       const trimmed = line.trim()
       if (!trimmed.startsWith('/')) return undefined
diff --git a/packages/client/ui-skill/tests/browser-plugin.spec.ts b/packages/client/ui-skill/tests/browser-plugin.spec.ts
index 0e098a0b30..da99ed70d3 100644
--- a/packages/client/ui-skill/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts
@@ -53,7 +53,8 @@ function providePresentation(ctx: Context): PresentationCapture {
       capture.dictionaries.push({ namespace, dictionaries })
       return () => { capture.localeDisposed = true }
     },
-    getSnapshot: () => ({ active: 'zh', locales: ['zh', 'en'], revision: 0 }),
+    // Minimal bound-translate fake: zh dictionary lookup, key passthrough on miss.
+    bind: () => (key: string) => key === 'menu.userOnly' ? '仅用户' : key,
   })
   return capture
 }
diff --git a/packages/skill/tool-skill/README.i18n.yaml b/packages/skill/tool-skill/README.i18n.yaml
index 19fa44c67c..7094272679 100644
--- a/packages/skill/tool-skill/README.i18n.yaml
+++ b/packages/skill/tool-skill/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/skill/tool-skill/README.md
-README.md: 5c6e592c670f324eb660dbe1fec168fd77e5b368
-README.zh.md: 202a621b1d4047c7d763de3b98c1a69c8c1ee1f7
+README.md: 21c3521aeff8b55940b04e804d5b8469850ec6da
+README.zh.md: 74137ce7e577a4b5c6d3592b60bac3c5901a9159
diff --git a/packages/skill/tool-skill/README.md b/packages/skill/tool-skill/README.md
index 5c6e592c67..21c3521aef 100644
--- a/packages/skill/tool-skill/README.md
+++ b/packages/skill/tool-skill/README.md
@@ -36,7 +36,7 @@ Tool execution does not add a synthetic context message. Its freshly loaded resu
 
 #### What the model sees
 
-If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names. The template's closing sentence is the seam rule against double-loading: the host's user-explicit `skill.invoke` injects the same `renderSkillContent` output (shared from `@deepseek-ai/dsh-skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same sentence.
+If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names. The template's closing sentence is the seam rule against double-loading: the host's user-explicit `skill.invoke` injects the same `renderSkillContent` output (shared from `@deepseek-ai/dsh-skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same sentence in both arms, including the emptied catalog.
 
 ##### Skill catalog template
 
diff --git a/packages/skill/tool-skill/README.zh.md b/packages/skill/tool-skill/README.zh.md
index 202a621b1d..74137ce7e5 100644
--- a/packages/skill/tool-skill/README.zh.md
+++ b/packages/skill/tool-skill/README.zh.md
@@ -36,7 +36,7 @@
 
 #### 模型看到的内容
 
-如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：宿主的用户显式 `skill.invoke` 会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板携带同一句话。
+如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：宿主的用户显式 `skill.invoke` 会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个臂——包括清空后的目录——都携带同一句话。
 
 ##### Skill 目录模板
 
diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts
index aa9b509206..1d3d26a7c9 100644
--- a/packages/skill/tool-skill/src/index.ts
+++ b/packages/skill/tool-skill/src/index.ts
@@ -233,6 +233,7 @@ function renderCatalogUpdate(entries: SkillCatalogSource['entries']): UserMessag
   const availability = entries.length === 0
     ? [
       'No skills are currently available through the `skill` tool. Do not use names from earlier skill catalogs.',
+      'A user may still invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool for it.',
     ]
     : [
       'Use only names in this replacement catalog. If the user names a listed skill, or the task clearly matches its description, call the `skill` tool with the exact name before acting.',

From 7750789c8e9e797718c447e7a9483727aae1b191 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 11:32:28 +0800
Subject: [PATCH 202/516] docs: regenerate the module graph for the dsh-skill
 llm dependency

---
 docs/module-graph.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index 9cf6f4c895..bbd0af9d8a 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -297,7 +297,6 @@ flowchart TD
   pkg_retention --> pkg_invariants
   pkg_timeout --> pkg_invariants
   pkg_scope --> pkg_invariants
-  pkg_skill --> pkg_invariants
   pkg_acp_snapshot --> pkg_invariants
   pkg_llm_mock_server --> pkg_invariants
   pkg_loader_smoke --> pkg_invariants
@@ -367,6 +366,8 @@ flowchart TD
   pkg_system_prompt --> pkg_invariants
   pkg_system_prompt --> pkg_llm
   pkg_system_prompt --> pkg_scope
+  pkg_skill --> pkg_invariants
+  pkg_skill --> pkg_llm
   pkg_web --> pkg_invariants
   pkg_web --> pkg_llm
   pkg_api_gateway --> pkg_client_connection
@@ -1156,7 +1157,6 @@ flowchart TD
 | [`retention`](../packages/util/retention) | `util` | [`invariants`](../packages/support/invariants) |
 | [`timeout`](../packages/util/timeout) | `util` | [`invariants`](../packages/support/invariants) |
 | [`scope`](../packages/core/scope) | `core` | [`invariants`](../packages/support/invariants) |
-| [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/support/invariants) |
 | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | [`invariants`](../packages/support/invariants) |
 | [`llm-mock-server`](../packages/support/llm-mock-server) | `support` | [`invariants`](../packages/support/invariants) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`invariants`](../packages/support/invariants) |
@@ -1194,6 +1194,7 @@ flowchart TD
 | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`type-meta`](../packages/typert/type-meta) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
+| [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |

From 2a7c1175be1c63023d62904d315bbff9463e1cd0 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 11:52:18 +0800
Subject: [PATCH 203/516] fix(docs): keep doc typecheck on Host sources

---
 docs/api-gateway.i18n.yaml |  4 ++--
 docs/api-gateway.md        |  2 +-
 docs/api-gateway.zh.md     |  2 +-
 scripts/doc-typecheck.ts   | 28 ++++++++++++----------------
 4 files changed, 16 insertions(+), 20 deletions(-)

diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index 6bf3151311..360e4b32e4 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.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 docs/api-gateway.md
-api-gateway.md: 7d5c5b7e46a66b2bf56ee1a1bbd57e7758a4c520
-api-gateway.zh.md: cbf62258b7bf4a1d2f657cf1fc08a8dbc0a1a939
+api-gateway.md: e8aafc173dced3c4ead07421d92401411565ece6
+api-gateway.zh.md: 92681b72ffc573cde834cece19568ec3f1d515ce
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index 7d5c5b7e46..e8aafc173d 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -57,7 +57,7 @@ Remote methods may return a value synchronously or return a Promise. For coopera
 
 The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct and scoped calls appear under `ctx.remote.<namespace>` and `agentCtx.remote.<namespace>`. Each namespace is a traced Cordis child Service registered as `remote.<namespace>`; the Client assembly mounts contributions through `ctx.remote.$mount()`, and the namespace unloads after its last method is withdrawn. Dependency declarations belong to the actual caller: only a business package that reads `ctx.remote.<namespace>` or `agentCtx.remote.<namespace>` declares both `remote` and `remote.<namespace>` in its own `inject`; assemblies that only mount contributions and higher-level runtimes that do not call that namespace do not declare the namespace dependency on the business package's behalf. When an `@Remote` method has exactly one lookup parameter and a same-named `TypeRTContextMap` uses the same wire identity, the generated scoped signature omits that identity parameter. `@RemoteScope` generates only the scoped invocation interface.
 
-```ts
+```ts ignore-check
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { AgentContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { Context } from 'cordis'
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index cbf62258b7..92681b72ff 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -57,7 +57,7 @@ Remote 方法可以同步返回或返回 Promise。若需要协作式取消，Ho
 
 Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子 Service；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，最后一个方法撤回后该 namespace 随即卸载。依赖声明归实际调用方所有：只有读取 `ctx.remote.<namespace>` 或 `agentCtx.remote.<namespace>` 的业务包才在自己的 `inject` 中同时声明 `remote` 与 `remote.<namespace>`；只负责挂载 contribution 的 assembly，以及不调用该 namespace 的上层 runtime，不代业务包声明 namespace 依赖。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用界面。
 
-```ts
+```ts ignore-check
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { AgentContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { Context } from 'cordis'
diff --git a/scripts/doc-typecheck.ts b/scripts/doc-typecheck.ts
index 456dedecfe..efdb03eaad 100644
--- a/scripts/doc-typecheck.ts
+++ b/scripts/doc-typecheck.ts
@@ -136,25 +136,21 @@ function formatDiagnostics(diagnostics: readonly ts.Diagnostic[], blocks: Block[
 }
 
 /**
- * Reuse both aggregate reference sets from a temp project one directory below
- * root. Each referenced package remains its own program, while documentation
- * examples can import either the Host or Client API.
+ * Reuse the Host aggregate references from a temp project one directory below
+ * root. Generated Client API examples opt out because their declarations do
+ * not exist until Host tsdown has run.
  */
 function workspaceReferences(): { path: string }[] {
-  const paths = new Set<string>()
-  for (const aggregate of ['tsconfig.host.json', 'tsconfig.client.json']) {
-    const file = join(root, aggregate)
-    // Parse with TypeScript's own JSONC reader: a regex comment stripper corrupts the `/*/` path
-    // candidate in the workspace wildcard.
-    const result = ts.readConfigFile(file, path => readFileSync(path, 'utf8'))
-    if (result.error) {
-      throw new Error(`doc-typecheck: cannot read ${file}: ${ts.flattenDiagnosticMessageText(result.error.messageText, '\n')}`)
-    }
-    // `config` is typed `any` by the TS API; narrow it to the one field read here.
-    const { references } = result.config as { references: { path: string }[] }
-    for (const { path } of references) paths.add(path)
+  const file = join(root, 'tsconfig.host.json')
+  // Parse with TypeScript's own JSONC reader: a regex comment stripper corrupts the `/*/` path
+  // candidate in the workspace wildcard.
+  const result = ts.readConfigFile(file, path => readFileSync(path, 'utf8'))
+  if (result.error) {
+    throw new Error(`doc-typecheck: cannot read ${file}: ${ts.flattenDiagnosticMessageText(result.error.messageText, '\n')}`)
   }
-  return [...paths].map(path => ({
+  // `config` is typed `any` by the TS API; narrow it to the one field read here.
+  const { references } = result.config as { references: { path: string }[] }
+  return references.map(({ path }) => ({
     path: path.startsWith('./') ? `../${path.slice(2)}` : `../${path}`,
   }))
 }

From d85d0806cddd8a28110b5a401453feb3477a984b Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 12:02:58 +0800
Subject: [PATCH 204/516] fix(build): align Client build metadata

---
 ...08-api-remotes-generated-contract-build.i18n.yaml |  2 +-
 ...026-08-08-api-remotes-generated-contract-build.md |  2 +-
 apps/web/tests/assembled-boot.ts                     |  2 +-
 packages/client/tsdown.client.ts                     | 12 +++++++-----
 .../host/directory-picker-native/tsdown.config.ts    |  2 +-
 scripts/run-gates.ts                                 |  4 ++--
 6 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
index 8b1bbf8b4d..5c1337a60c 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.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 .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
-2026-08-08-api-remotes-generated-contract-build.md: ac9bb445917e11a4b57280da513d36b0f434bbaf
+2026-08-08-api-remotes-generated-contract-build.md: 83848290400441f0272b220ed0d396570e1ce2dc
 2026-08-08-api-remotes-generated-contract-build.zh.md: 4f9760078c209a22b9e03837fd81769e156b5df9
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
index ac9bb44591..8384829040 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
@@ -53,7 +53,7 @@ This exception follows from the real generated-contract ordering and is not a te
 
 Host tsdown enables `typertPlugin({ mode: 'workspace', faces: ['host'] })` in the normal root config. The generator uses only `tsconfig.host.json` as its program seed and produces both `typert.host.*` and the `typert.remote-client.*` projection of Host contracts; Client tsdown neither starts TypeRT nor analyzes the Client aggregate.
 
-The TypeRT analyzer distinguishes compiler faces from runtime faces. Direct Project References in the aggregate determine which compiler face analyzes a project; only a split project explicitly referenced through `tsconfig.host.json` or `tsconfig.client.json` is restricted to that corresponding face. Runtime models follow package subpath contributions instead, so an ordinary single-project `dshClient` package may contribute both Host and Client runtime models.
+The TypeRT analyzer distinguishes compiler faces from runtime faces. Direct Project References in the aggregate determine which compiler face analyzes a project; only a split project explicitly referenced through `tsconfig.host.json` or `tsconfig.client.json` is restricted to that corresponding face. Runtime models follow package subpath contributions instead, so an ordinary single-project `dshClient` package may contribute both Host and Client runtime models. Consequently, Host analysis of `api-remotes` does not also register its Client entry, while an ordinary dual-entry package does not lose its Host model.
 
 Both the Host and Client tsdown passes receive the same complete workspace of `vendor/*`, `packages/*/*`, and `apps/cli`. The root config does not scan `lib/types/client/index.js`, maintain a package classification table, or use a tsdown filter; package-local configs return entries for the current phase according to `DSH_BUILD_FACE`.
 
diff --git a/apps/web/tests/assembled-boot.ts b/apps/web/tests/assembled-boot.ts
index 729428e47b..53f976af09 100644
--- a/apps/web/tests/assembled-boot.ts
+++ b/apps/web/tests/assembled-boot.ts
@@ -20,7 +20,7 @@ const PLUGINS: readonly (WebBootEntry & { bundlePath: string })[] = [
   { id: '@deepseek-ai/dsh-client-connection', bundlePath: 'packages/client/connection/lib/client.js', url: '/plugins/connection.js', rev: 'fx', inject: [], immediately: true },
   { id: '@deepseek-ai/dsh-api-gateway', bundlePath: 'packages/api/gateway/lib/client.js', url: '/plugins/api-gateway.js', rev: 'fx', inject: ['@deepseek-ai/dsh-typert-registry', '@deepseek-ai/dsh-client-connection'], immediately: true },
   { id: '@deepseek-ai/dsh-api-remotes', bundlePath: 'packages/api/remotes/lib/client.js', url: '/plugins/api-remotes.js', rev: 'fx', inject: ['@deepseek-ai/dsh-api-gateway'], immediately: true },
-  { id: '@deepseek-ai/dsh-client-runtime', bundlePath: 'packages/client/runtime/lib/client.js', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection', '@deepseek-ai/dsh-api-remotes', '@deepseek-ai/dsh-typert-registry'], immediately: true },
+  { id: '@deepseek-ai/dsh-client-runtime', bundlePath: 'packages/client/runtime/lib/client.js', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection', '@deepseek-ai/dsh-typert-registry'], immediately: true },
   { id: '@deepseek-ai/dsh-client-ui-theme', bundlePath: 'packages/client/ui-theme/lib/client.js', url: '/plugins/ui-theme.js', rev: 'fx', inject: [], immediately: true },
   { id: '@deepseek-ai/dsh-client-locale', bundlePath: 'packages/client/locale/lib/client.js', url: '/plugins/locale.js', rev: 'fx', inject: [], immediately: true },
   { id: '@deepseek-ai/dsh-client-ui-layout', bundlePath: 'packages/client/ui-layout/lib/client.js', url: '/plugins/ui-layout.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime'] },
diff --git a/packages/client/tsdown.client.ts b/packages/client/tsdown.client.ts
index f2b7b7a3e6..2eebcc5308 100644
--- a/packages/client/tsdown.client.ts
+++ b/packages/client/tsdown.client.ts
@@ -93,10 +93,10 @@ export function clientBundle(
     const client = clientConfig(id, face === undefined
       ? 'src/client/index.ts'
       : 'lib/types/client/index.js')
-    const host = [lib, ...(options.host ?? [])]
-    if (face === 'host') return options.hostPhase === true ? host : [SKIP_WORKSPACE_BUILD]
-    if (face === 'client') return options.hostPhase === true ? [client] : [...host, client]
-    return [...host, client]
+    const node = [lib, ...(options.companions ?? [])]
+    if (face === 'host') return options.hostPhase === true ? node : [SKIP_WORKSPACE_BUILD]
+    if (face === 'client') return options.hostPhase === true ? [client] : [...node, client]
+    return [...node, client]
   }
 }
 
@@ -125,7 +125,9 @@ export function clientOnly(configs: readonly UserConfig[]): BuildFaceConfig {
 interface ClientBundleOptions {
   /** Emit the Node-side artifacts during the Host pass instead of the Client pass. */
   readonly hostPhase?: boolean
-  readonly host?: readonly UserConfig[]
+  /** Additional Node-side configs emitted alongside the package library. */
+  readonly companions?: readonly UserConfig[]
+  /** Overrides for the package's primary Node-side library config. */
   readonly lib?: UserConfig
 }
 
diff --git a/packages/host/directory-picker-native/tsdown.config.ts b/packages/host/directory-picker-native/tsdown.config.ts
index 4a4727a5aa..6d02727f4e 100644
--- a/packages/host/directory-picker-native/tsdown.config.ts
+++ b/packages/host/directory-picker-native/tsdown.config.ts
@@ -7,7 +7,7 @@ export default clientBundle(
   '@deepseek-ai/dsh-host-directory-picker-native',
   ['lib/types/index.js', 'lib/types/invariant.js'],
   {
-    host: [{
+    companions: [{
       // The artifact is lib/worker.cjs (the ./worker export the workspace
       // constraint keys on), bundled from the descriptive source entry.
       entry: { worker: 'lib/types/win32-dialog-worker.js' },
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index c1c3e1699c..03064cb242 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -263,8 +263,8 @@ function ciPrimaryGates(): Gate[] {
     ...docSyncLeafGates(),
     pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
     pnpmScript('knip', 'knip'),
-    // typecheck and build now drive the same root solution graph; without the
-    // dependency two concurrent `tsc -b` runs race the same tsbuildinfo files.
+    // typecheck and build both drive the Host and Client tsc graphs; without
+    // the dependency concurrent runs race the same tsbuildinfo files.
     // The tsc step is an incremental no-op after typecheck.
     pnpmScript('build', 'build', { needs: ['typecheck'] }),
     pnpmScript('publint', 'publint', { needs: ['build'] }),

From 863abcb42796cfab67e3fd722206905f9785251e Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 12:25:41 +0800
Subject: [PATCH 205/516] build: enforce split project reference faces

---
 ...remotes-generated-contract-build.i18n.yaml |   4 +-
 ...08-api-remotes-generated-contract-build.md |   2 +-
 ...api-remotes-generated-contract-build.zh.md |   2 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +-
 docs/development.zh.md                        |   2 +-
 scripts/check-workspace-constraints.ts        |   2 +
 scripts/project-reference-faces.spec.ts       | 100 ++++++++++++++
 scripts/project-reference-faces.ts            | 129 ++++++++++++++++++
 9 files changed, 239 insertions(+), 8 deletions(-)
 create mode 100644 scripts/project-reference-faces.spec.ts
 create mode 100644 scripts/project-reference-faces.ts

diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
index 5c1337a60c..dec1b79d6a 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.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 .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
-2026-08-08-api-remotes-generated-contract-build.md: 83848290400441f0272b220ed0d396570e1ce2dc
-2026-08-08-api-remotes-generated-contract-build.zh.md: 4f9760078c209a22b9e03837fd81769e156b5df9
+2026-08-08-api-remotes-generated-contract-build.md: 947465b19a7c399038ae8a3106f7563592365a8d
+2026-08-08-api-remotes-generated-contract-build.zh.md: 7b559cd966c4acc055d41379c15f46fdfc649a00
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
index 8384829040..947465b19a 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
@@ -43,7 +43,7 @@ packages/api/remotes/
       └─ index.ts
 ~~~
 
-The package-root `tsconfig.json` is a solution that only references the two concrete projects; it enters neither aggregate nor any direct consumer's dependency graph. The root Host aggregate and `host/apiproxy` reference `api/remotes/tsconfig.host.json`, while the root Client aggregate and `client/ui-goal` reference `api/remotes/tsconfig.client.json`. `ui-goal` itself remains an ordinary single Client project.
+The package-root `tsconfig.json` is a solution that only references the two concrete projects; it enters neither aggregate nor any direct consumer's dependency graph. The root Host aggregate and `host/apiproxy` reference `api/remotes/tsconfig.host.json`, while the root Client aggregate and `client/ui-goal` reference `api/remotes/tsconfig.client.json`. `ui-goal` itself remains an ordinary single Client project. The workspace constraints gate walks the reachable Project Reference graph and rejects any face-declared project that references a split package's solution root or opposite leaf; targets with only `tsconfig.json` remain valid from either face.
 
 The two projects use disjoint `files` and separate `.tsbuildinfo` files, so they can share `lib/types` without emitting any source file twice. If both sides later need a shared implementation, move that implementation into a neutral package instead of giving the same source to two emitting projects.
 
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
index 4f9760078c..7b559cd966 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
@@ -43,7 +43,7 @@ packages/api/remotes/
       └─ index.ts
 ~~~
 
-包根 `tsconfig.json` 是只引用两个具体 project 的 solution，不进入任何 aggregate 或直接消费方的依赖图。根 Host aggregate 与 `host/apiproxy` 引用 `api/remotes/tsconfig.host.json`；根 Client aggregate 与 `client/ui-goal` 引用 `api/remotes/tsconfig.client.json`。`ui-goal` 本身仍是普通的单一 Client project。
+包根 `tsconfig.json` 是只引用两个具体 project 的 solution，不进入任何 aggregate 或直接消费方的依赖图。根 Host aggregate 与 `host/apiproxy` 引用 `api/remotes/tsconfig.host.json`；根 Client aggregate 与 `client/ui-goal` 引用 `api/remotes/tsconfig.client.json`。`ui-goal` 本身仍是普通的单一 Client project。workspace constraints 门禁遍历可达的 Project Reference 图；凡已声明 face 的 project 引用了拆分包的 solution 根或另一侧 leaf，门禁都会拒绝，而只有 `tsconfig.json` 的目标仍可由任一 face 引用。
 
 两个 project 使用互不重叠的 `files` 和不同的 `.tsbuildinfo`，因此可以共享 `lib/types` 而不重复发射任何源码。若未来需要两侧共用一份实现，应把实现移入中立 package，不能把同一源码同时交给两个 emitting project。
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 5a1024e657..4ef3010835 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: acf279d182ca580c6e372be6fbdca8f46afdc445
-development.zh.md: 927c72be2de78f9e7f67565b9524db85c5aa1669
+development.md: 60a7ccc87e2c33e66b3d966a2907d31bb0b1efd8
+development.zh.md: 6607705be7e9f548b4f44555ad8c6cc8c2d34964
diff --git a/docs/development.md b/docs/development.md
index acf279d182..60a7ccc87e 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -59,7 +59,7 @@ Host and Client stay two aggregate programs because both sides declaration-merge
 - A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.
 - A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.
 
-`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.
+`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.
 
 The root build follows the generated dependency order:
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 927c72be2d..6607705be7 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -59,7 +59,7 @@ Host 与 Client 保持两个 aggregate program，是因为两侧在相同键下
 - 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。
 - 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。
 
-`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。
+`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。
 
 根构建按生成依赖排序：
 
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 9be97f53e6..05e3d5a9ce 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -8,6 +8,7 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join, relative, resolve } from 'node:path'
 import { hasTypeRTRemoteNavigation, isForbiddenPublicationFile } from './publication-payload.ts'
+import { collectProjectReferenceFaceViolations } from './project-reference-faces.ts'
 
 const root = resolve(import.meta.dirname, '..')
 // vendor/* is single-level; packages/<group>/<pkg> nests one level deeper
@@ -305,6 +306,7 @@ const errors = [
   ...checkRepositoryVersion(),
   ...workspaceManifests().flatMap(checkWorkspace),
   ...checkHierarchyShape(),
+  ...collectProjectReferenceFaceViolations(root),
 ]
 if (errors.length > 0) {
   console.error(errors.join('\n'))
diff --git a/scripts/project-reference-faces.spec.ts b/scripts/project-reference-faces.spec.ts
new file mode 100644
index 0000000000..93b3ab8c5f
--- /dev/null
+++ b/scripts/project-reference-faces.spec.ts
@@ -0,0 +1,100 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectProjectReferenceFaceViolations } from './project-reference-faces.ts'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function writeJson(path: string, value: unknown): void {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+function workspaceFixture(options: {
+  readonly host: readonly string[]
+  readonly client: readonly string[]
+}): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-project-reference-faces-'))
+  roots.push(root)
+  const shared = join(root, 'packages/core/shared')
+  const split = join(root, 'packages/api/split')
+  mkdirSync(shared, { recursive: true })
+  mkdirSync(split, { recursive: true })
+  writeJson(join(root, 'tsconfig.base.json'), {})
+  writeJson(join(root, 'tsconfig.base.client.json'), { extends: './tsconfig.base.json' })
+  writeJson(join(shared, 'package.json'), { name: '@deepseek-ai/dsh-shared' })
+  writeJson(join(shared, 'tsconfig.json'), {
+    extends: '../../../tsconfig.base.json',
+    references: [],
+  })
+  writeJson(join(split, 'package.json'), { name: '@deepseek-ai/dsh-split' })
+  writeJson(join(split, 'tsconfig.json'), {
+    files: [],
+    references: [{ path: './tsconfig.host.json' }, { path: './tsconfig.client.json' }],
+  })
+  writeJson(join(split, 'tsconfig.host.json'), { references: [{ path: '../../core/shared' }] })
+  writeJson(join(split, 'tsconfig.client.json'), { references: [{ path: '../../core/shared' }] })
+  writeJson(join(root, 'tsconfig.host.json'), {
+    references: options.host.map(path => ({ path })),
+  })
+  writeJson(join(root, 'tsconfig.client.json'), {
+    references: options.client.map(path => ({ path })),
+  })
+  return root
+}
+
+describe('Project Reference compiler faces', () => {
+  it('allows neutral projects in either graph and matching split leaves', () => {
+    const root = workspaceFixture({
+      host: ['./packages/core/shared', './packages/api/split/tsconfig.host.json'],
+      client: ['./packages/core/shared', './packages/api/split/tsconfig.client.json'],
+    })
+
+    expect(collectProjectReferenceFaceViolations(root)).toEqual([])
+  })
+
+  it('rejects the opposite leaf and the solution root of a split project', () => {
+    const root = workspaceFixture({
+      host: [
+        './packages/api/split/tsconfig.host.json',
+        './packages/api/split/tsconfig.client.json',
+      ],
+      client: ['./packages/api/split'],
+    })
+
+    expect(collectProjectReferenceFaceViolations(root)).toEqual([
+      'tsconfig.client.json: Project Reference "./packages/api/split" enters split project packages/api/split from a Client config; reference "packages/api/split/tsconfig.client.json" instead',
+      'tsconfig.host.json: Project Reference "./packages/api/split/tsconfig.client.json" enters split project packages/api/split from a Host config; reference "packages/api/split/tsconfig.host.json" instead',
+    ])
+  })
+
+  it('uses the referencing project face throughout the reachable graph', () => {
+    const root = workspaceFixture({
+      host: ['./packages/core/host-consumer'],
+      client: ['./packages/core/client-consumer'],
+    })
+    const hostConsumer = join(root, 'packages/core/host-consumer')
+    mkdirSync(hostConsumer, { recursive: true })
+    writeJson(join(hostConsumer, 'package.json'), { name: '@deepseek-ai/dsh-host-consumer' })
+    writeJson(join(hostConsumer, 'tsconfig.json'), {
+      extends: '../../../tsconfig.base.json',
+      references: [{ path: '../../api/split/tsconfig.client.json' }],
+    })
+    const clientConsumer = join(root, 'packages/core/client-consumer')
+    mkdirSync(clientConsumer, { recursive: true })
+    writeJson(join(clientConsumer, 'package.json'), { name: '@deepseek-ai/dsh-client-consumer' })
+    writeJson(join(clientConsumer, 'tsconfig.json'), {
+      extends: '../../../tsconfig.base.client.json',
+      references: [{ path: '../../api/split/tsconfig.host.json' }],
+    })
+
+    expect(collectProjectReferenceFaceViolations(root)).toEqual([
+      'packages/core/client-consumer/tsconfig.json: Project Reference "../../api/split/tsconfig.host.json" enters split project packages/api/split from a Client config; reference "packages/api/split/tsconfig.client.json" instead',
+      'packages/core/host-consumer/tsconfig.json: Project Reference "../../api/split/tsconfig.client.json" enters split project packages/api/split from a Host config; reference "packages/api/split/tsconfig.host.json" instead',
+    ])
+  })
+})
diff --git a/scripts/project-reference-faces.ts b/scripts/project-reference-faces.ts
new file mode 100644
index 0000000000..0cff0dfa9e
--- /dev/null
+++ b/scripts/project-reference-faces.ts
@@ -0,0 +1,129 @@
+/** Validate compiler-face isolation across workspace Project Reference graphs. */
+
+import { existsSync, globSync } from 'node:fs'
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import ts from 'typescript'
+
+type ProjectFace = 'host' | 'client'
+
+interface ProjectReferenceConfig {
+  readonly extends?: unknown
+  readonly references?: ReadonlyArray<{ readonly path?: unknown }>
+}
+
+const WORKSPACE_MANIFESTS = [
+  'packages/*/*/package.json',
+  'apps/*/package.json',
+  'vendor/*/package.json',
+] as const
+
+/**
+ * Find references that enter the wrong leaf of a split Host/Client project.
+ *
+ * A single-config project is neutral and may participate in either graph. Once
+ * a package declares both face configs, every reachable reference must name
+ * the leaf matching the aggregate from which traversal began.
+ *
+ * @param root - Repository root containing both aggregate tsconfigs.
+ * @returns Repo-relative diagnostics for every mismatched reference edge.
+ */
+export function collectProjectReferenceFaceViolations(root: string): string[] {
+  const splitRoots = splitProjectRoots(root)
+  const violations: string[] = []
+  const pending = [resolve(root, 'tsconfig.host.json'), resolve(root, 'tsconfig.client.json')]
+  const visited = new Set<string>()
+  for (let configPath = pending.pop(); configPath !== undefined; configPath = pending.pop()) {
+    if (visited.has(configPath) || !existsSync(configPath)) continue
+    visited.add(configPath)
+    const config = projectConfig(root, configPath)
+    const face = projectFace(root, configPath, config)
+    for (const reference of projectReferences(config)) {
+      const targetConfig = referenceConfigPath(configPath, reference)
+      const splitRoot = containingSplitRoot(splitRoots, targetConfig)
+      if (splitRoot !== undefined) {
+        if (face === undefined) {
+          violations.push(
+            `${repoPath(root, configPath)}: Project Reference ${JSON.stringify(reference)} enters split project ${repoPath(root, splitRoot)} from a config with no Host/Client face`,
+          )
+          continue
+        }
+        const expected = resolve(splitRoot, `tsconfig.${face}.json`)
+        if (targetConfig !== expected) {
+          violations.push(
+            `${repoPath(root, configPath)}: Project Reference ${JSON.stringify(reference)} enters split project ${repoPath(root, splitRoot)} from a ${faceLabel(face)} config; reference ${JSON.stringify(repoPath(root, expected))} instead`,
+          )
+          continue
+        }
+      }
+      pending.push(targetConfig)
+    }
+  }
+
+  return violations.sort()
+}
+
+function splitProjectRoots(root: string): string[] {
+  return globSync(WORKSPACE_MANIFESTS, { cwd: root })
+    .map(manifest => resolve(root, dirname(manifest)))
+    .filter(dir => existsSync(resolve(dir, 'tsconfig.host.json'))
+      && existsSync(resolve(dir, 'tsconfig.client.json')))
+    .sort((left, right) => right.length - left.length)
+}
+
+function projectConfig(root: string, configPath: string): ProjectReferenceConfig {
+  const read = ts.readConfigFile(configPath, path => ts.sys.readFile(path))
+  if (read.error !== undefined) {
+    const message = ts.flattenDiagnosticMessageText(read.error.messageText, '\n')
+    throw new Error(`${repoPath(root, configPath)}: ${message}`)
+  }
+  return read.config as ProjectReferenceConfig
+}
+
+function projectReferences(config: ProjectReferenceConfig): string[] {
+  return (config.references ?? [])
+    .map(reference => reference.path)
+    .filter((path): path is string => typeof path === 'string')
+}
+
+function projectFace(
+  root: string,
+  configPath: string,
+  config: ProjectReferenceConfig,
+  seen = new Set<string>(),
+): ProjectFace | undefined {
+  if (basename(configPath) === 'tsconfig.host.json') return 'host'
+  if (basename(configPath) === 'tsconfig.client.json') return 'client'
+  if (configPath === resolve(root, 'tsconfig.base.json')) return 'host'
+  if (configPath === resolve(root, 'tsconfig.base.client.json')) return 'client'
+  if (seen.has(configPath)) return undefined
+  seen.add(configPath)
+  const parent = localExtendsConfig(configPath, config.extends)
+  if (parent === undefined || !existsSync(parent)) return undefined
+  return projectFace(root, parent, projectConfig(root, parent), seen)
+}
+
+function localExtendsConfig(configPath: string, value: unknown): string | undefined {
+  if (typeof value !== 'string' || !value.startsWith('.')) return undefined
+  const target = resolve(dirname(configPath), value)
+  return target.endsWith('.json') ? target : `${target}.json`
+}
+
+function referenceConfigPath(sourceConfig: string, reference: string): string {
+  const target = resolve(dirname(sourceConfig), reference)
+  return target.endsWith('.json') ? target : resolve(target, 'tsconfig.json')
+}
+
+function containingSplitRoot(splitRoots: readonly string[], targetConfig: string): string | undefined {
+  return splitRoots.find((root) => {
+    const path = relative(root, targetConfig)
+    return path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path)
+  })
+}
+
+function repoPath(root: string, path: string): string {
+  return relative(root, path).split(sep).join('/')
+}
+
+function faceLabel(face: ProjectFace): string {
+  return face === 'host' ? 'Host' : 'Client'
+}

From 8fc9032d715c2840eae39c79c520c9e8a0d4c3ac Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 12:36:50 +0800
Subject: [PATCH 206/516] test: refresh translation prompt snapshot

---
 .../translation-prompt-v4/request-response.expected.json      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index b2adbc38aa..0748e762dd 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology and the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology and the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",

From c08fa27e5ca3c5bfeb7e3e931a39b8e8249b1f27 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 13:14:49 +0800
Subject: [PATCH 207/516] feat(tool-skill): inject user-invoked skills at the
 pre-step gesture boundary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A whitespace-bounded /name token anywhere in a claimed user message,
naming a user-invocable skill in the workspace directory, now injects that
skill's renderSkillContent as instructions context appended after every
other injection of the step — the same agent/pre-step seam the catalog,
workspace instructions, and the runtime snapshot ride. Closed-set matching
mirrors the command registry (a miss stays plain prose), only user-source
messages are scanned, the policy check runs on the loaded definition, and
this is the sole entry point for disable-model-invocation skills. The
catalog's no-reload sentence now names the gesture boundary.
---
 packages/host/apiproxy/src/api-proxy.ts       |  75 +------------
 packages/skill/skill/README.i18n.yaml         |   4 +-
 packages/skill/skill/README.md                |   2 +-
 packages/skill/skill/README.zh.md             |   2 +-
 packages/skill/skill/src/index.ts             |  13 ++-
 packages/skill/tool-skill/README.i18n.yaml    |   4 +-
 packages/skill/tool-skill/README.md           |  16 ++-
 packages/skill/tool-skill/README.zh.md        |  16 ++-
 packages/skill/tool-skill/src/index.ts        |  76 +++++++++++++
 .../skill/tool-skill/tests/tool-skill.spec.ts | 103 ++++++++++++++++++
 10 files changed, 225 insertions(+), 86 deletions(-)

diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 0abfb8c9c0..cfcae423bc 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -18,8 +18,7 @@ import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import { SessionQueryError, type SessionSearchCursor } from '@deepseek-ai/dsh-session-query'
 import { SubagentError } from '@deepseek-ai/dsh-subagent'
 import type { SubagentListEntry as CatalogSubagentListEntry } from '@deepseek-ai/dsh-subagent'
-import { isSkillName, isUserInvocable, renderSkillContent } from '@deepseek-ai/dsh-skill'
-import type { SkillInvocationSource } from '@deepseek-ai/dsh-skill'
+import { isUserInvocable } from '@deepseek-ai/dsh-skill'
 import type { Workspace, WorkspaceRecord } from '@deepseek-ai/dsh-workspace'
 import {
   workspaceDomainState, workspaceRecord, WorkspaceId as brandWorkspaceId,
@@ -1254,9 +1253,8 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
    * turn, and letting it try spends the whole pre-step path to fail inside
    * the adapter with a message about registration. Refusing here names the
    * model the session is pointed at while the draft is still in the composer.
-   * This is the enforcement boundary shared by `session.prompt` and
-   * `skill.invoke`: a client that disables its input is an affordance, and
-   * both methods stay callable regardless.
+   * This is `session.prompt`'s enforcement boundary: a client that disables
+   * its input is an affordance, and the method stays callable regardless.
    */
   async function turnAgentFor<T>(
     request: RpcRequest<unknown>, sessionId: SessionId,
@@ -2389,73 +2387,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           return err(request, { code: 'internal', message: `skill listing failed: ${String(error)}`, details: {} })
         }
       },
-
-      async invoke(request, signal) {
-        const { sessionId, name, text } = request.payload
-        const resolved = await turnAgentFor<{ accepted: true }>(request, sessionId)
-        if ('refused' in resolved) return resolved.refused
-        const agent = resolved.agent
-        if (agent.session.header.cwd === undefined) {
-          // Same stance as skill.list: a cwd-less header is a pre-project
-          // legacy log, and skill discovery has no root to resolve against.
-          return err(request, { code: 'internal', message: `session "${sessionId}" has no project cwd`, details: {} })
-        }
-        const skillRegistry = ctx.get('skills')
-        if (skillRegistry === undefined) {
-          return err(request, { code: 'internal', message: 'skill registry is absent: this deployment does not mount @deepseek-ai/dsh-skill in its composition (cordis.yml or explicit assembly)', details: {} })
-        }
-        const lookup = { cwd: agent.session.header.cwd, signal }
-        let skill
-        try {
-          // isSkillName guards the registry contract; an ill-formed name is
-          // indistinguishable from an absent one for the caller.
-          const summary = isSkillName(name)
-            ? (await skillRegistry.list(lookup)).find(candidate => candidate.name === name)
-            : undefined
-          if (summary === undefined) {
-            return err(request, { code: 'skill-not-found', message: `skill "${name}" is unknown in this workspace`, details: { name } })
-          }
-          // The operation boundary owns user-invocation policy: client menus
-          // filtering their candidates is an affordance, not enforcement.
-          if (!isUserInvocable(summary)) {
-            return err(request, { code: 'skill-not-invocable', message: `skill "${name}" is not available for user invocation`, details: { name } })
-          }
-          const loaded = await skillRegistry.get(name, lookup)
-          if (loaded === undefined) {
-            return err(request, { code: 'skill-not-found', message: `skill "${name}" is unknown in this workspace`, details: { name } })
-          }
-          // Recheck on the loaded definition (the skill-tool execute template):
-          // list and get collect independently, so a provider change between
-          // the two awaits can swap the winning candidate for a user-disabled
-          // one — the boundary must judge what it actually injects.
-          if (!isUserInvocable(loaded)) {
-            return err(request, { code: 'skill-not-invocable', message: `skill "${name}" is not available for user invocation`, details: { name } })
-          }
-          skill = loaded
-        } catch (error: unknown) {
-          if (signal.aborted) {
-            return err(request, { code: 'cancelled', message: 'skill invocation cancelled', details: {} })
-          }
-          return err(request, { code: 'internal', message: `skill invocation failed: ${String(error)}`, details: {} })
-        }
-        if (signal.aborted) {
-          // The caller already gave up (unary deadline or navigation): a turn
-          // it will never observe must not start.
-          return err(request, { code: 'cancelled', message: 'skill invocation cancelled', details: {} })
-        }
-        const body = renderSkillContent(skill)
-        const source: SkillInvocationSource = { kind: 'skill-invocation', name, ...text === undefined ? {} : { args: text } }
-        try {
-          const message: UserMessage = createUserMessage({
-            content: [{ type: 'text', text: text === undefined ? body : `${body}\n\n${text}` }],
-            source,
-          })
-          agent.followup(message)
-        } catch (error: unknown) {
-          return err(request, { code: 'agent-busy', message: 'skill invocation rejected', details: { reason: String(error) } })
-        }
-        return ok(request, { accepted: true as const })
-      },
     },
 
     settings: {
diff --git a/packages/skill/skill/README.i18n.yaml b/packages/skill/skill/README.i18n.yaml
index fe29171cb3..2ca9cbac01 100644
--- a/packages/skill/skill/README.i18n.yaml
+++ b/packages/skill/skill/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/skill/skill/README.md
-README.md: 0c1b2249d8c46ad9ce8097ceeda2bd988c92eb21
-README.zh.md: 8fed350d00433206aecdb32819adc81c82745869
+README.md: 3dc2bcfa5775736717bdebcb92329d5655198234
+README.zh.md: d11f90d5a8356f06df63aa249a1f8b5851f36f5f
diff --git a/packages/skill/skill/README.md b/packages/skill/skill/README.md
index 0c1b2249d8..3dc2bcfa57 100644
--- a/packages/skill/skill/README.md
+++ b/packages/skill/skill/README.md
@@ -39,7 +39,7 @@ This package owns the `ctx.skills` interface. It does not know whether skills co
 
 ### Shared model-facing rendering
 
-`renderSkillContent(skill)` renders one loaded skill as the canonical `<skill_content>` block (escaped `name` attribute, resource hints, verbatim body). It is the single truth for both loading paths: `dsh-tool-skill` returns it as the `skill` tool result, and the host's user-explicit `skill.invoke` injects it as a user message, so the model sees one shape regardless of who initiated the load. `escapeText` is exported beside it for consumers embedding prose in the same markup frame. The package also declares the `skill-invocation` `MessageSource` kind ({ name, args? }) that user-explicit injection stamps on its messages — transcript consumers present the invocation from this metadata instead of re-parsing the body.
+`renderSkillContent(skill)` renders one loaded skill as the canonical `<skill_content>` block (escaped `name` attribute, resource hints, verbatim body). It is the single truth for both loading paths: `dsh-tool-skill` returns it as the `skill` tool result and injects it at the user-explicit gesture boundary, so the model sees one shape regardless of who initiated the load. `escapeText` is exported beside it for consumers embedding prose in the same markup frame. The package also declares the `skill-invocation` `MessageSource` kind ({ name, form: 'instructions' }) that user-explicit injection stamps on its messages — transcript consumers present the invocation from this metadata instead of re-parsing the body.
 
 `isModelInvocable(skill)` and `isUserInvocable(skill)` read the matching positive field directly. `ctx.skills.get()` remains the trusted, policy-neutral loading primitive, so every user- or model-facing consumer must enforce the predicate that matches its surface before exposing or loading a skill.
 
diff --git a/packages/skill/skill/README.zh.md b/packages/skill/skill/README.zh.md
index 8fed350d00..d11f90d5a8 100644
--- a/packages/skill/skill/README.zh.md
+++ b/packages/skill/skill/README.zh.md
@@ -39,7 +39,7 @@
 
 ### 共享的面向模型渲染
 
-`renderSkillContent(skill)` 把一个已加载 skill 渲染为规范的 `<skill_content>` 块（转义后的 `name` 属性、资源提示、原样正文）。它是两条加载路径的唯一真源：`dsh-tool-skill` 将其作为 `skill` 工具结果返回，宿主的用户显式 `skill.invoke` 将其作为用户消息注入，因此无论加载由谁发起，模型看到的都是同一种形态。`escapeText` 随之一并导出，供要在同一标记框架中嵌入文案的消费方使用。该包还声明 `skill-invocation` 这个 `MessageSource` kind（{ name, args? }），用户显式注入会把它打在自己的消息上——transcript（文本记录）消费方依据这份元数据呈现该次调用，而不是重新解析正文。
+`renderSkillContent(skill)` 把一个已加载 skill 渲染为规范的 `<skill_content>` 块（转义后的 `name` 属性、资源提示、原样正文）。它是两条加载路径的唯一真源：`dsh-tool-skill` 将其作为 `skill` 工具结果返回，并在用户显式的手势边界将其注入，因此无论加载由谁发起，模型看到的都是同一种形态。`escapeText` 随之一并导出，供要在同一标记框架中嵌入文案的消费方使用。该包还声明 `skill-invocation` 这个 `MessageSource` kind（{ name, form: 'instructions' }），用户显式注入会把它打在自己的消息上——transcript（文本记录）消费方依据这份元数据呈现该次调用，而不是重新解析正文。
 
 `isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 仍是受信且与策略无关的加载原语，因此每个面向用户或模型的消费方都必须先执行与自身接口匹配的判定，再暴露或加载 skill。
 
diff --git a/packages/skill/skill/src/index.ts b/packages/skill/skill/src/index.ts
index f44386d51c..42478279b4 100644
--- a/packages/skill/skill/src/index.ts
+++ b/packages/skill/skill/src/index.ts
@@ -121,17 +121,18 @@ export function isUserInvocable(skill: Pick<SkillSummary, 'invocation'>): boolea
 }
 
 /**
- * Durable message source for a user-explicit skill invocation: the host
- * injects the rendered skill as a user-role message carrying this source, so
- * transcript consumers present the invocation from metadata instead of
- * re-parsing the model-facing text.
+ * Durable source for the context message a user-explicit skill invocation
+ * injects: the user's own words ride a plain user message, and the rendered
+ * skill body follows as injected `instructions`-form context carrying this
+ * source, so transcript consumers present the injection from metadata
+ * instead of re-parsing the model-facing text.
  */
 export interface SkillInvocationSource {
   readonly kind: 'skill-invocation'
   /** Invoked skill name, validated user-invocable at the injecting boundary. */
   readonly name: string
-  /** Trailing free text the user submitted after the skill token, when present. */
-  readonly args?: string
+  /** Injected skill bodies are instructions for the model to follow. */
+  readonly form: 'instructions'
 }
 
 declare module '@deepseek-ai/dsh-llm' {
diff --git a/packages/skill/tool-skill/README.i18n.yaml b/packages/skill/tool-skill/README.i18n.yaml
index 7094272679..b9aa148fd1 100644
--- a/packages/skill/tool-skill/README.i18n.yaml
+++ b/packages/skill/tool-skill/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/skill/tool-skill/README.md
-README.md: 21c3521aeff8b55940b04e804d5b8469850ec6da
-README.zh.md: 74137ce7e577a4b5c6d3592b60bac3c5901a9159
+README.md: b7309657d85a3d2a19de78a4ee6173d742519daa
+README.zh.md: f430f4027c917c5c9b97a56d1a7d7a617670b25c
diff --git a/packages/skill/tool-skill/README.md b/packages/skill/tool-skill/README.md
index 21c3521aef..b7309657d8 100644
--- a/packages/skill/tool-skill/README.md
+++ b/packages/skill/tool-skill/README.md
@@ -36,7 +36,7 @@ Tool execution does not add a synthetic context message. Its freshly loaded resu
 
 #### What the model sees
 
-If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names. The template's closing sentence is the seam rule against double-loading: the host's user-explicit `skill.invoke` injects the same `renderSkillContent` output (shared from `@deepseek-ai/dsh-skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same sentence in both arms, including the emptied catalog.
+If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names. The template's closing sentence is the seam rule against double-loading: the user-explicit gesture boundary (the pre-step listener below) injects the same `renderSkillContent` output (shared from `@deepseek-ai/dsh-skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same sentence in both arms, including the emptied catalog.
 
 ##### Skill catalog template
 
@@ -145,6 +145,20 @@ Only a failing call adds these retained tokens.
 
 Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
+### User-explicit invocation injection
+
+#### What the model sees
+
+A whitespace-bounded `/name` token anywhere in a claimed user message, naming a user-invocable skill in the workspace catalog, injects that skill's full `<skill_content>` rendering (the exact result-template shape above) as a `user`-role instructions context appended after every other injection of that step — background first, the material to act on last. Only direct user input is scanned, the check runs on the loaded definition, and unknown or user-disabled names stay ordinary prose. This is the sole entry point for `disable-model-invocation` skills, which the catalog and the `skill` tool never expose; the catalog's closing sentence tells the model to follow the injected block instead of re-loading it.
+
+#### Token effect
+
+Each gesture adds one rendered skill body to that turn as injected context — the same size as the tool result for the same skill, paid deterministically at the user's request instead of at the model's discretion. Repeated gestures for one skill within one step inject once.
+
+#### KV Cache effect
+
+Append-only; the injection lands after the reusable request prefix inside the step's message batch and does not invalidate existing KV-cache entries.
+
 ## Known Limitations and Deferred Work
 
 - **The catalog omits `whenToUse`, source, and provider metadata** — routing is based only on name and a capped description; `whenToUse` remains provider metadata and is not rendered by the loaded wrapper either.
diff --git a/packages/skill/tool-skill/README.zh.md b/packages/skill/tool-skill/README.zh.md
index 74137ce7e5..f430f4027c 100644
--- a/packages/skill/tool-skill/README.zh.md
+++ b/packages/skill/tool-skill/README.zh.md
@@ -36,7 +36,7 @@
 
 #### 模型看到的内容
 
-如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：宿主的用户显式 `skill.invoke` 会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个臂——包括清空后的目录——都携带同一句话。
+如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：用户显式的手势边界（下文的 pre-step 监听器）会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个臂——包括清空后的目录——都携带同一句话。
 
 ##### Skill 目录模板
 
@@ -145,6 +145,20 @@ Load referenced resources only as needed.
 
 仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV Cache 条目失效。
 
+### 用户显式调用注入
+
+#### 模型看到的内容
+
+已认领用户消息中任意位置、以空白为界、指名工作区目录中某个用户可调用 skill 的 `/name` token，会把该 skill 的完整 `<skill_content>` 渲染（与上文结果模板完全相同的形态）作为 `user` 角色的指令上下文注入，追加在该步骤所有其他注入之后——背景在前，模型要着手处理的材料在最后。只扫描直接的用户输入，检查在已加载定义上进行，未知名称和用户不可调用的名称保持为普通行文。这是 `disable-model-invocation` skill 唯一的入口，目录和 `skill` 工具永不暴露这类 skill；目录的结尾一句会告诉模型遵循注入块，而不是重新加载它。
+
+#### Token 影响
+
+每次手势会把一份渲染后的 skill 正文作为注入上下文加进该轮次——尺寸与同一 skill 的工具结果相同，按用户的请求确定性地支付，而非由模型自行裁量。同一步骤内对同一 skill 的重复手势只注入一次。
+
+#### KV Cache 影响
+
+仅追加；注入落在该步骤的消息批次中、可重用请求前缀之后，不会使现有 KV Cache 条目失效。
+
 ## 已知限制与暂缓事项
 
 - **目录省略 `whenToUse`、来源和提供方元数据**：路由只基于名称和有长度上限的描述；`whenToUse` 仍是提供方元数据，加载后的包装层也不渲染它。
diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts
index 1d3d26a7c9..604cd63bcf 100644
--- a/packages/skill/tool-skill/src/index.ts
+++ b/packages/skill/tool-skill/src/index.ts
@@ -15,7 +15,9 @@ import {
   escapeText,
   isModelInvocable,
   isSkillName,
+  isUserInvocable,
   renderSkillContent,
+  type SkillInvocationSource,
   type SkillSummary,
 } from '@deepseek-ai/dsh-skill'
 
@@ -161,6 +163,49 @@ export function apply(ctx: Context, config: Config = {}): void {
     throw new Error('dsh-tool-skill: registered skill tool is not visible in the global registry')
   }
 
+  // User-explicit skill invocation: a claimed user message whose first line
+  // starts with `/<name>` naming a user-invocable skill is a deterministic
+  // load gesture. The rendered body enters this step as injected
+  // instructions context appended after every other injection — background
+  // first (workspace rules, runtime policy, the catalog), the material the
+  // model must act on last, closest to its answer. Registration order makes
+  // that placement deterministic: this listener registers before the catalog
+  // listener, so the waterfall hands it the catalog-bearing list to extend.
+  // Only `source.kind === 'user'` messages are scanned — external text
+  // cannot forge the gesture — and a token naming no user-invocable skill
+  // stays ordinary prose (the command registry is a different closed
+  // namespace, resolved client-side before a line ever becomes a prompt).
+  // This is the only entry point for `disable-model-invocation` skills; the
+  // catalog and the `skill` tool below never see them.
+  ctx.on('agent/pre-step', async (
+    { agent, messages, signal },
+    next,
+  ): Promise<PreStepDecision> => {
+    const decision = await next()
+    if (decision.kind === 'reject') return decision
+    const names = invokedSkillNames(messages)
+    if (names.length === 0) return decision
+    signal.throwIfAborted()
+    const lookup = { cwd: agent.session.header.cwd, signal }
+    const injections: UserMessage[] = []
+    for (const name of names) {
+      const skill = await ctx.skills.get(name, lookup)
+      signal.throwIfAborted()
+      // Unknown names and user-disabled skills stay plain prose: the
+      // gesture was never a claim this boundary recognizes. The check sits
+      // on the loaded definition — the single lookup that produces what is
+      // actually injected.
+      if (skill === undefined || !isUserInvocable(skill)) continue
+      const source: SkillInvocationSource = { kind: 'skill-invocation', name, form: 'instructions' }
+      injections.push(createUserMessage({
+        content: [{ type: 'text', text: renderSkillContent(skill) }],
+        source,
+      }))
+    }
+    if (injections.length === 0) return decision
+    return { kind: 'enter', messages: [...decision.messages, ...injections] }
+  })
+
   // Register after the tool so reverse teardown removes guidance first. Exact definition
   // identity prevents a scoped shadow merely named `skill` from inheriting this catalog.
   ctx.on('agent/pre-step', async (
@@ -351,3 +396,34 @@ function assertPositiveInteger(name: string, value: number, minimum = 1): void {
     throw new Error(`tool-skill: ${name} must be an integer greater than or equal to ${minimum}`)
   }
 }
+
+/**
+ * A whitespace-bounded `/name` token (the public skill-name grammar) anywhere
+ * in the text — the same word-boundary shape the transcript chip decoration
+ * uses, so a gesture reads as one wherever it sits in the sentence. A second
+ * `/` or any non-boundary character breaks the match, which keeps file paths
+ * (`/usr/bin`) and fractions (`5/8`) out.
+ */
+const SKILL_GESTURE = /(^|\s)\/([a-z0-9]+(?:-[a-z0-9]+)*)(?=\s|$)/g
+
+/**
+ * `/name` gesture tokens from the claimed user messages, deduplicated in
+ * first-seen order. Every text block of direct user input is scanned; no
+ * other source can forge a gesture.
+ * @param messages - the step's claimed batch.
+ * @returns candidate skill names, unvalidated against the registry.
+ */
+function invokedSkillNames(messages: readonly UserMessage[]): string[] {
+  const names: string[] = []
+  for (const message of messages) {
+    if ((message.source as { kind?: unknown }).kind !== 'user') continue
+    for (const block of message.content) {
+      if (block.type !== 'text') continue
+      for (const match of block.text.matchAll(SKILL_GESTURE)) {
+        const name = match[2]
+        if (name !== undefined && !names.includes(name)) names.push(name)
+      }
+    }
+  }
+  return names
+}
diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts
index 9543c196af..fe356da5da 100644
--- a/packages/skill/tool-skill/tests/tool-skill.spec.ts
+++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts
@@ -915,3 +915,106 @@ describe('dsh-tool-skill', () => {
     expect(vanishedBlock.text).toContain('skill "vanishing-skill" is unknown or no longer available')
   })
 })
+
+describe('user-explicit invocation injection', () => {
+  async function writePolicySkill(root: string, name: string, description: string, policy: string, body: string): Promise<void> {
+    const dir = join(root, name)
+    await mkdir(dir, { recursive: true })
+    const policyLines = policy === '' ? '' : `${policy}\n`
+    await writeFile(join(dir, 'SKILL.md'), `---\nname: ${name}\ndescription: ${description}\n${policyLines}---\n\n${body}\n`)
+  }
+
+  function gesture(text: string): UserMessage {
+    return createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
+  }
+
+  async function invokeHarness(): Promise<{ ctx: Context; agent: Agent }> {
+    const home = await tempDir('invoke')
+    const skillsRoot = join(home, '.agents', 'skills')
+    await writePolicySkill(skillsRoot, 'hidden-demo', 'User-only demo', 'disable-model-invocation: true', 'Say the magic word: PINEAPPLE.')
+    await writePolicySkill(skillsRoot, 'shared-skill', 'Ordinary skill', '', 'Shared instructions.')
+    await writePolicySkill(skillsRoot, 'model-only-skill', 'Model only', 'user-invocable: false', 'Model-only instructions.')
+    const ctx = await setup(home)
+    return { ctx, agent: agentForCwd(home) }
+  }
+
+  it('injects a user-invocable skill named by a leading /token, after every other injection', async () => {
+    const { ctx, agent } = await invokeHarness()
+    const first = gesture('/hidden-demo what does this do')
+    const second = gesture('plain follow-up prose')
+    const decision = await proposeStep(ctx, agent, [first, second])
+    if (decision.kind !== 'enter') throw new Error('expected enter')
+    const kinds = decision.messages.map(message => (message.source as { kind: string }).kind)
+    // Background injections (the catalog here) sit between the claimed batch
+    // and the invoked body: the material the model must act on comes last.
+    expect(kinds.slice(0, 2)).toEqual(['user', 'user'])
+    expect(kinds.at(-1)).toBe('skill-invocation')
+    expect(kinds.indexOf('skill-catalog')).toBeLessThan(kinds.indexOf('skill-invocation'))
+    const injection = decision.messages.at(-1)!
+    expect(injection.source).toMatchObject({ kind: 'skill-invocation', name: 'hidden-demo', form: 'instructions' })
+    const block = injection.content[0]
+    if (block?.type !== 'text') throw new Error('expected text injection')
+    expect(block.text).toContain('<skill_content name="hidden-demo">')
+    expect(block.text).toContain('Say the magic word: PINEAPPLE.')
+    expect(block.text).not.toContain('what does this do')
+  })
+
+  it('injects an ordinary skill the same way (one uniform user-explicit path)', async () => {
+    const { ctx, agent } = await invokeHarness()
+    const decision = await proposeStep(ctx, agent, [gesture('/shared-skill go')])
+    if (decision.kind !== 'enter') throw new Error('expected enter')
+    expect(decision.messages.some(message =>
+      (message.source as { kind?: string; name?: string }).kind === 'skill-invocation'
+      && (message.source as { name?: string }).name === 'shared-skill')).toBe(true)
+  })
+
+  it('recognizes a mid-sentence gesture but not paths, fractions, or broken boundaries', async () => {
+    const { ctx, agent } = await invokeHarness()
+    const decision = await proposeStep(ctx, agent, [
+      gesture('please use /hidden-demo to answer this'),
+    ])
+    if (decision.kind !== 'enter') throw new Error('expected enter')
+    expect(decision.messages.some(message =>
+      (message.source as { kind?: string; name?: string }).kind === 'skill-invocation'
+      && (message.source as { name?: string }).name === 'hidden-demo')).toBe(true)
+
+    const negative = await proposeStep(ctx, agent, [
+      gesture('look under /hidden-demo/refs for the data'),
+      gesture('the odds are 5/8 at best'),
+      gesture('see foo/hidden-demo too'),
+    ])
+    if (negative.kind !== 'enter') throw new Error('expected enter')
+    expect(negative.messages.some(message =>
+      (message.source as { kind?: string }).kind === 'skill-invocation')).toBe(false)
+  })
+
+  it('leaves unknown names and user-disabled skills as plain prose', async () => {
+    const { ctx, agent } = await invokeHarness()
+    const decision = await proposeStep(ctx, agent, [
+      gesture('/absent-skill do a thing'),
+      gesture('/model-only-skill run'),
+    ])
+    if (decision.kind !== 'enter') throw new Error('expected enter')
+    // No injection joins the step (the catalog listener may still add its
+    // own skill-catalog message; only skill-invocation sources matter here).
+    expect(decision.messages.some(message =>
+      (message.source as { kind?: string }).kind === 'skill-invocation')).toBe(false)
+  })
+
+  it('never scans non-user sources and dedupes repeated gestures', async () => {
+    const { ctx, agent } = await invokeHarness()
+    const forged = createUserMessage({
+      content: [{ type: 'text', text: '/hidden-demo forged' }],
+      source: { kind: 'skill-catalog', form: 'catalog', entries: [] },
+    })
+    const decision = await proposeStep(ctx, agent, [
+      forged,
+      gesture('/hidden-demo once'),
+      gesture('/hidden-demo twice'),
+    ])
+    if (decision.kind !== 'enter') throw new Error('expected enter')
+    const injections = decision.messages.filter(message =>
+      (message.source as { kind?: string }).kind === 'skill-invocation')
+    expect(injections).toHaveLength(1)
+  })
+})

From 0d53752c49975b5210fa20279601d79ad964877c Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 13:15:52 +0800
Subject: [PATCH 208/516] refactor(host)!: retire the skill.invoke RPC for the
 gesture boundary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Invocation is an ordinary session.prompt again: the pre-step gesture
boundary makes it deterministic host-side for every front end, so the
dedicated RPC (handler, wire schema, error codes, client face, fixtures)
and ui-skill's claim machinery are net deletions. The menu keeps decision
21 exactly — a pick lands literal /name text — plus the user-only marker
from skill.list's modelInvocable flag.
---
 ...8-user-explicit-skill-invocation.i18n.yaml |   4 +-
 ...26-08-08-user-explicit-skill-invocation.md |  27 ++-
 ...08-08-user-explicit-skill-invocation.zh.md |  25 ++-
 apps/web/tests/skill-user-invoke.e2e.ts       |  45 ++--
 .../skill-user-invoke/ui.expected.md          |  10 +-
 docs/config-catalog.md                        |   4 +-
 docs/cordis-catalog/events.md                 |   2 +-
 docs/cordis-catalog/services.md               |   2 +-
 docs/event-producer-consumer.md               |   2 +-
 .../client/connection/src/client/fixture.ts   |  18 --
 packages/client/connection/tests/fake-api.ts  |   3 -
 packages/client/runtime/src/client/index.ts   |   3 +-
 .../src/client/sessions/context-provenance.ts |   3 +
 .../src/client/sessions/conversation.ts       |  34 ---
 .../src/client/sessions/transcript-adapter.ts |  20 +-
 packages/client/runtime/tests/fake-api.ts     |   3 -
 .../runtime/tests/transcript-adapter.spec.ts  |  27 ++-
 .../src/client/chat/ChatView.tsx              |  10 +-
 .../src/client/chat/MessageItem.module.css    |  27 ---
 .../src/client/chat/MessageItem.tsx           |  39 +---
 .../ui-conversation/src/client/locales.ts     |   2 -
 .../tests/chat-branch-tails.spec.tsx          |  35 ---
 .../src/client/turn-deliverables.ts           |   3 +-
 .../tests/produced-files.spec.tsx             |  20 --
 packages/client/ui-skill/README.i18n.yaml     |   4 +-
 packages/client/ui-skill/README.md            |  10 +-
 packages/client/ui-skill/README.zh.md         |  10 +-
 packages/client/ui-skill/src/client/index.ts  |  69 ++----
 .../ui-skill/tests/browser-plugin.spec.ts     |  59 +----
 packages/host/apiproxy/README.i18n.yaml       |   4 +-
 packages/host/apiproxy/README.md              |   2 +-
 packages/host/apiproxy/README.zh.md           |   2 +-
 packages/host/apiproxy/src/api/rpc-map.ts     |   1 -
 packages/host/apiproxy/src/api/rpc.schema.ts  |   2 -
 packages/host/apiproxy/src/api/rpc.ts         |   4 -
 .../host/apiproxy/src/api/skills.schema.ts    |  15 --
 packages/host/apiproxy/src/api/skills.ts      |  22 +-
 packages/host/apiproxy/src/fetch/client.ts    |   5 +-
 packages/host/apiproxy/src/fetch/handler.ts   |   3 +-
 .../apiproxy/tests/api-proxy-commands.spec.ts | 201 ------------------
 .../apiproxy/tests/client-handler.spec.ts     |   2 +-
 .../host/apiproxy/tests/fetch-carrier.spec.ts |   5 -
 .../host/apiproxy/tests/rpc-schemas.spec.ts   |  18 +-
 43 files changed, 143 insertions(+), 663 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
index 4c36032f35..3774ba6e69 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.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 .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
-2026-08-08-user-explicit-skill-invocation.md: abe6a05283359b81ff1c3cab754d0230e599e4a0
-2026-08-08-user-explicit-skill-invocation.zh.md: e72e49236ffd2c6f664e01abbd69665eec8328e9
+2026-08-08-user-explicit-skill-invocation.md: d925938279923282170dc99934f4fa44d8ecf2b4
+2026-08-08-user-explicit-skill-invocation.zh.md: 64e23be0b42519fb9681adefcd0f05074d3aa35e
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
index abe6a05283..d925938279 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
@@ -1,4 +1,4 @@
-# Agent Note: User-explicit skill invocation over skill.invoke
+# Agent Note: User-explicit skill invocation at the pre-step gesture boundary
 
 Status: implemented
 
@@ -10,28 +10,27 @@ A `disable-model-invocation: true` skill is user-only by design: it never enters
 
 ## Decision
 
-User-explicit invocation is a deterministic host-side injection, uniform for every user-invocable skill:
+User-explicit invocation is a host-side pre-step injection, uniform for every user-invocable skill and every front end:
 
-- `skill.invoke { sessionId, name, text? }` (host apiproxy) enforces user-invocation policy at the operation boundary (`skill-not-found` / `skill-not-invocable`), renders the skill with the shared `renderSkillContent`, appends the optional trailing text after a blank line, and injects the whole as one user-role message carrying the new `skill-invocation` `MessageSource` kind (`{ name, args? }`) before starting a turn through the same route-served gate as `session.prompt`.
-- `renderSkillContent` moved from `dsh-tool-skill` to the `dsh-skill` seam: the `skill` tool result and the injection share one verbatim `<skill_content>` shape, and the catalog text gained the seam rule — an inline-injected skill must be followed, not re-loaded through the tool.
-- `skill.list` serves every user-invocable skill and carries `modelInvocable`, so the browser menu lists user-only skills with a marker (description prefix — the `hint` field is claim-state ghost text the menu never renders).
-- ui-skill claims a menu pick or an entered `/name [args]` into the invoke transaction (`matchEnter` strong-waits the catalog; unknown names stay plain prompts). The unreached legacy `<skill>name</skill>` reference codec is removed.
-- The transcript materializes the injection as a dedicated `skill-invocation` node from source metadata (never re-parsed from the body) and renders a right-aligned bubble: `/name` chip, trailing text, and the injected block collapsed behind a disclosure.
+- `dsh-tool-skill` registers a second `agent/pre-step` listener (beside its catalog listener, the same seam `workspace-instructions` and the runtime-context snapshot ride): it scans the step's claimed messages for whitespace-bounded `/name` tokens — anywhere in the text, the same word-boundary shape the transcript chip decoration uses — collects first-seen-deduplicated names, loads each through `ctx.skills.get`, checks `isUserInvocable` on the loaded definition (the single lookup that produces what is injected), renders it with the shared `renderSkillContent`, and appends the injections after every other injection of the step: background first (workspace rules, runtime policy, catalog), the material the model must act on last, closest to its answer. Registration order pins the placement — the gesture listener registers before the catalog listener, so the waterfall hands it the catalog-bearing list to extend.
+- Precision is closed-set matching, exactly like slash commands: `/goal` resolves against the command registry, `/name` against the workspace's user-invocable skill directory; a miss stays ordinary prose, so nothing is ever guessed. Only `source.kind === 'user'` messages are scanned — external text cannot forge a gesture. Paths (`/usr/bin`), fractions (`5/8`), and prefixed tokens (`foo/name`) all break the boundary.
+- The client stays decision 21: a menu pick lands the literal `/name ` and the prompt ships it verbatim; ui-skill implements no adjudication hooks and no reference codec. `skill.list` (now the domain's only RPC) serves every user-invocable skill with `modelInvocable` so menus mark user-only entries. A name shared with a host command resolves to the command — adjudication claims the line client-side before it becomes a prompt.
+- The injection is a `user`-role message carrying the `skill-invocation` source (`{ name, form: 'instructions' }`), so `user/message` logging, the context-injection transcript row (labelled with the skill name), and replay all come free; `renderSkillContent` lives in the `dsh-skill` seam, shared verbatim with the `skill` tool result, and the catalog's closing sentence tells the model to follow an injected block instead of re-loading it.
 
-Peer-product survey (Pi, OpenCode, Claude Code, Kimi Code, Codex, DeepSeek-Reasonix — local checkouts) was unanimous: user-explicit triggering is programmatic injection as a user-role message with zero model participation on every product, prompt-guided tool loading exists only on the model-autonomous track, and the disable-model-invocation equivalents gate only the model-side surfaces. Kimi's origin-metadata rendering and the Claude Code/Kimi no-reload prompt rule translate directly onto `MessageSource` and the catalog sentence.
+Peer-product survey (Pi, OpenCode, Claude Code, Kimi Code, Codex, DeepSeek-Reasonix — local checkouts) was unanimous that user-explicit triggering is programmatic injection with zero model participation; the final shape is closest to Codex's core-side `$name` mention scanning, which likewise frees every front end from implementing recognition.
 
 ## Alternatives considered
 
-- **`agent.inject()` context injection** — no peer precedent; the gesture is a user turn, not an environment notice, and context-row presentation, compaction, and attribution all mismatch. Rejected.
+- **`skill.invoke` RPC (host injects, client claims)** — implemented first, in two iterations: a single mixed message (user text folded into the body), then a gesture prompt plus injection delivered through inbox primitives. Rejected after real-session testing: the mixed message polluted the injection with user prose; the two-message form depended on wake-ordering subtleties (`followup` claims the whole next-turn queue synchronously inside the first waking call, stranding any later message in the next turn — reproduced live), and the dedicated RPC duplicated a path `session.prompt` already provides while leaving TUI/ACP to reimplement recognition. The pre-step seam removes the RPC, the claim machinery, and the ordering hazard outright.
+- **`agent.inject()` from the RPC handler** — the inject queue (`next-step`, wake-free) is claimed ahead of the next-turn prompt, putting the injection above the gesture in the log; and pairing it with a waking `followup` reintroduces the same ordering coupling. The pre-step listener injects inside the step assembly, where ordering is explicit.
 - **A host `/skill <name>` command** (command registry, plan-mode precedent) — two-token UX, no name completion, and user-only skills stay undiscoverable in the menu; the per-cwd skill catalog also fits the static command registry poorly. Rejected.
 - **Client-side expansion** (fetch body, splice into the prompt) — authorization becomes bypassable client courtesy, the log loses the invocation semantics, and Codex deleted its equivalent mechanism (custom prompts) in favor of core injection. Rejected.
-- **Host prompt-pipeline scanning for `/name`** (Codex `$name` core mentions) — duplicates the adjudication layer and risks swallowing literal slashes in prose; the claim path already covers the need. Rejected.
-- **Per-injection preamble line** (Kimi's `User activated the skill …`) — dropped in favor of a one-time catalog sentence: same context, paid once, and the injected block stays byte-identical with the tool result.
+- **Structured reference payload on the prompt wire** (Codex's `UserInput::Skill` analogue: the client ships `{skills: [...]}` beside the text and the boundary prefers it over scanning) — considered and deferred: the existing slash-command system is itself line-text on the wire, and closed-set directory matching already removes the guesswork; recorded as a ledger item should gesture precision ever need client intent.
+- **Per-injection preamble line** (Kimi's `User activated the skill …`) — dropped in favor of the one-time catalog sentence: same context, paid once, and the injected block stays byte-identical with the tool result.
 
 ## Consequences
 
-- Decision 21's plain-text reference path is superseded at submission: the draft still carries plain text and lexicon-derived chip visuals, but submit claims into a deterministic injection instead of shipping the literal and hoping. The model-autonomous track (catalog + `skill` tool) is unchanged.
-- Every user-invocable skill invocation now costs its full rendered body unconditionally — the price of determinism the peer survey showed everyone pays.
+- Decision 21's plain-text reference is now the whole client story: the draft carries plain text, chip visuals derive from the lexicon, and the sent text is judged by the host boundary — a hand-typed gesture, a menu pick, and a TUI prompt are indistinguishable and equally deterministic.
+- Every user-invocable skill invocation costs its full rendered body unconditionally — the price of determinism the peer survey showed everyone pays. Mentioning a known skill name mid-sentence loads it; that is the Codex mention semantic, accepted deliberately.
 - The `skill-invocation` source rides `user/message`, so Model-visible ⟺ logged holds with no new event type, and replay/UI read metadata rather than text markers.
-- TUI and ACP can adopt `skill.invoke` later for the same semantics; until then the TUI's client-side expansion remains its own path.
 - Accepted residual of dropping the per-injection preamble: the no-reload framing rides only the catalog, and a workspace whose skills are all user-only never publishes a first catalog — an injection can arrive with no framing at all, and the model may redundantly try the `skill` tool once (the replacement catalog's empty arm carries the sentence; the never-published case does not). Publishing a catalog for framing alone was judged worse than that one recoverable error.
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
index e72e49236f..64e23be0b4 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 经 skill.invoke 的用户显式 skill 调用
+# Agent Note: pre-step 手势边界上的用户显式 skill 调用
 
 Status: implemented
 
@@ -10,28 +10,27 @@ Status: implemented
 
 ## 决策
 
-用户显式调用是一次确定性的宿主侧注入，对每一个用户可调用的 skill 一致：
+用户显式调用是一次宿主侧的 pre-step 注入，对每一个用户可调用的 skill 和每一种前端一致：
 
-- `skill.invoke { sessionId, name, text? }`（宿主 apiproxy）在操作边界强制执行用户调用策略（`skill-not-found`/`skill-not-invocable`），用共享的 `renderSkillContent` 渲染该 skill，在一个空行之后追加可选的尾随文本，并把整体作为一条携带新增 `skill-invocation` `MessageSource` kind（`{ name, args? }`）的 user 角色消息注入，随后经由与 `session.prompt` 相同的「路由是否有适配器在服务」闸门开启一个轮次。
-- `renderSkillContent` 从 `dsh-tool-skill` 移入 `dsh-skill` seam：`skill` 工具结果与注入共享同一份逐字一致的 `<skill_content>` 形态，目录文本则新增了这条 seam 规则——已内联注入的 skill 必须被遵循，而不是再经工具重新加载。
-- `skill.list` 提供每一个用户可调用的 skill 并携带 `modelInvocable`，因此浏览器菜单会带标记地列出仅限用户的 skill（描述前缀——`hint` 字段是认领态的 ghost text，菜单从不渲染它）。
-- ui-skill 把菜单 pick 或回车提交的 `/name [args]` 认领进 invoke 事务（`matchEnter` 强等目录；未知名称保持为普通提示词）。已不可达的旧 `<skill>name</skill>` 引用 codec 被移除。
-- transcript（文本记录）依据来源元数据把这次注入物化为专用的 `skill-invocation` 节点（绝不从正文重新解析），并渲染为一个右对齐气泡：`/name` chip、尾随文本，以及收在 disclosure 之后的注入块。
+- `dsh-tool-skill` 注册第二个 `agent/pre-step` 监听器（与其目录监听器并列，也是 `workspace-instructions` 与运行时上下文快照搭乘的同一 seam）：它在该步骤已认领的消息中扫描以空白为界的 `/name` token——文本中任意位置均可，与 transcript（文本记录）chip 装饰所用的词边界形状相同——收集按首见去重的名称，逐个经 `ctx.skills.get` 加载，在已加载定义上检查 `isUserInvocable`（产生注入内容的正是这同一次查找），用共享的 `renderSkillContent` 渲染，并把注入追加在该步骤所有其他注入之后：背景在前（工作区规则、运行时策略、目录），模型必须着手处理的材料在最后、最贴近它的回答。注册顺序钉住了这一位置——手势监听器先于目录监听器注册，因此 waterfall 会把携带目录的列表交给它来扩展。
+- 精确性来自封闭集合匹配，与斜杠命令完全一致：`/goal` 对照命令注册表解析，`/name` 对照工作区的用户可调用 skill 目录解析；未命中即保持为普通行文，因此绝不猜测。只扫描 `source.kind === 'user'` 的消息——外部文本无法伪造手势。路径（`/usr/bin`）、分数（`5/8`）与带前缀的 token（`foo/name`）都会破坏该边界。
+- 客户端停留在决策 21：菜单 pick 落下字面文本 `/name `，提示词将其原样发出；ui-skill 不实现任何裁决钩子，也没有引用 codec。`skill.list`（现在是该领域唯一的 RPC）提供每一个用户可调用的 skill 并携带 `modelInvocable`，供菜单标出仅限用户的条目。与宿主命令同名的名称解析为命令——裁决在客户端把该行认领走，它尚未成为提示词。
+- 注入是一条携带 `skill-invocation` 来源（`{ name, form: 'instructions' }`）的 `user` 角色消息，因此 `user/message` 落账、上下文注入的 transcript 行（以 skill 名称标注）与回放全部免费获得；`renderSkillContent` 位于 `dsh-skill` seam，与 `skill` 工具结果逐字共享，目录的结尾一句会告诉模型遵循注入块而不是重新加载。
 
-同类产品调研（Pi、OpenCode、Claude Code、Kimi Code、Codex、DeepSeek-Reasonix——本地检出）结论一致：在每个产品上，用户显式触发都是以 user 角色消息做程序化注入、模型零参与；提示词引导的工具加载只存在于模型自主轨道上；disable-model-invocation 的对应物只把关模型侧表层。Kimi 的来源元数据渲染与 Claude Code/Kimi 的禁止重载提示词规则，可直接平移到 `MessageSource` 与目录那句话上。
+同类产品调研（Pi、OpenCode、Claude Code、Kimi Code、Codex、DeepSeek-Reasonix——本地检出）一致表明：用户显式触发都是模型零参与的程序化注入；最终形态最接近 Codex 核心侧的 `$name` mention 扫描——它同样让每一种前端免于自行实现识别。
 
 ## 考虑过的替代方案
 
-- **`agent.inject()` 上下文注入**——没有同类产品先例；这次手势是一个用户轮次，不是环境通知，而且上下文行呈现、压缩（compaction）与归属全都不匹配。否决。
+- **`skill.invoke` RPC（宿主注入、客户端认领）**——最先实现，共两轮迭代：先是单条混合消息（用户文本折进正文），后是经 inbox 原语投递的手势提示词加注入两条消息。经真实会话测试后否决：混合消息让用户行文污染了注入；两条消息的形态依赖唤醒顺序的微妙之处（`followup` 在第一个唤醒调用内同步认领整个 next-turn 队列，把之后的消息滞留到下一轮次——已实际复现），而专设 RPC 复制了 `session.prompt` 已提供的路径，还让 TUI/ACP 不得不各自重新实现识别。pre-step seam 把 RPC、认领机制与顺序隐患一并干净移除。
+- **从 RPC 处理器调用 `agent.inject()`**——inject 队列（`next-step`，不唤醒）会在 next-turn 提示词之前被认领，使注入在日志中排到手势之上；而与会唤醒的 `followup` 搭配又会重新引入同样的顺序耦合。pre-step 监听器在步骤组装内部注入，那里的顺序是显式的。
 - **宿主 `/skill <name>` 命令**（命令注册表，plan 模式先例）——两 token 的 UX、没有名称补全、仅限用户的 skill 在菜单里仍不可发现；按 cwd 的 skill 目录也与静态命令注册表格格不入。否决。
 - **客户端展开**（拉取正文、拼进提示词）——授权沦为可被绕过的客户端善意，日志失去调用语义，而且 Codex 已删除其等价机制（custom prompts）转向核心注入。否决。
-- **宿主提示词流水线扫描 `/name`**（Codex 的 `$name` core mentions）——重复了裁决层，还有吞掉普通行文中字面斜杠的风险；认领路径已经覆盖了这一需求。否决。
+- **提示词协议上的结构化引用载荷**（Codex `UserInput::Skill` 的类似物：客户端在文本旁附带 `{skills: [...]}`，边界优先采用它而不是扫描）——考虑过并暂缓：现有斜杠命令体系在协议上本身就是行文本，封闭集合的目录匹配已经消除了猜测；已记为台账事项，以备手势精确性某天需要客户端意图。
 - **每次注入一条前导语**（Kimi 的 `User activated the skill …`）——弃用，改为一次性的目录句子：同样的上下文、只支付一次，且注入块与工具结果保持逐字节一致。
 
 ## 后果
 
-- 决策 21 的纯文本引用路径在提交处被取代：草稿仍承载纯文本与 lexicon 派生的 chip 视觉，但提交会认领进一次确定性注入，而不是把字面文本发出去再碰运气。模型自主轨道（目录 + `skill` 工具）不变。
-- 每一次用户可调用 skill 的调用现在都无条件付出其完整渲染正文的成本——这是确定性的代价，同类调研表明所有产品都在支付。
+- 决策 21 的纯文本引用如今就是客户端的全部故事：草稿承载纯文本，chip 视觉由 lexicon 派生，发出的文本由宿主边界评判——手动键入的手势、菜单 pick 与 TUI 提示词无从区分，也同等确定。
+- 每一次用户可调用 skill 的调用都无条件付出其完整渲染正文的成本——这是确定性的代价，同类调研表明所有产品都在支付。在句子中间提到一个已知 skill 名称也会加载它；这就是 Codex 的 mention 语义，属于有意接受。
 - `skill-invocation` 来源搭乘 `user/message`，因此「模型可见 ⟺ 已记录」在不新增事件类型的情况下继续成立，回放与 UI 读取的是元数据而非文本标记。
-- TUI 与 ACP 之后可以为同样的语义采用 `skill.invoke`；在那之前，TUI 的客户端展开仍是它自己的路径。
 - 放弃逐次注入前导语后被接受的残余：no-reload framing 只搭乘目录，而 skill 全部为仅用户的工作区永远不会发布首个目录——注入可能在完全没有 framing 的情况下到达，模型可能多余地调用一次 `skill` 工具（替换目录的空臂携带该句；从未发布的情形没有）。仅为 framing 而发布目录被判定比这一次可恢复的错误更糟。
diff --git a/apps/web/tests/skill-user-invoke.e2e.ts b/apps/web/tests/skill-user-invoke.e2e.ts
index f722472ded..2d5a039623 100644
--- a/apps/web/tests/skill-user-invoke.e2e.ts
+++ b/apps/web/tests/skill-user-invoke.e2e.ts
@@ -1,9 +1,9 @@
 // Web e2e scenario: a user invokes a disable-model-invocation skill through
 // the composer (issue #1470). The entered `/name args` line claims into
-// skill.invoke: the real host renders the skill body, injects it as a
-// user-role message carrying the skill-invocation source, and starts a turn
-// answered by the replay seam. The transcript shows the dedicated invocation
-// card (chip + args, body collapsed) and the model's reply.
+// skill.invoke: the real host forwards the gesture as an ordinary user
+// prompt, injects the rendered body as instructions context named after the
+// skill, and starts a turn answered by the replay seam. The transcript shows
+// the gesture bubble, the collapsed context-injection row, and the reply.
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
@@ -96,7 +96,7 @@ describe.skipIf(MODE === 'record')('web e2e: user-explicit skill invocation thro
     if (failures.length > 1) throw new AggregateError(failures, 'skill-user-invoke e2e cleanup failed')
   })
 
-  it('claims /name args into an injection card and a replayed answer', async () => {
+  it('claims /name args into a gesture bubble, an injection row, and a replayed answer', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-skill-user-invoke'))
     const composer = page.locator('textarea:enabled').last()
     await composer.waitFor({ timeout: 15_000 })
@@ -112,23 +112,26 @@ describe.skipIf(MODE === 'record')('web e2e: user-explicit skill invocation thro
     await composer.fill(`/${SKILL_NAME} ${ARGS_TEXT}`)
     await composer.press('Enter')
 
-    // The injection card presents the gesture from source metadata: chip plus
-    // args, with the rendered <skill_content> collapsed behind a disclosure.
-    const card = page.locator('[data-skill-invocation]')
-    await card.waitFor({ timeout: 15_000 })
-    const chip = card.locator('[data-ref-chip="skill"]')
-    expect(await chip.textContent()).toBe(`/${SKILL_NAME}`)
-    expect(await card.textContent()).toContain(ARGS_TEXT)
+    // The gesture stays an ordinary user bubble (decorated /name token plus
+    // the trailing text), ahead of the injected context.
+    const bubble = page.locator('[data-ref-chip="skill"]').first()
+    await bubble.waitFor({ timeout: 15_000 })
+    expect(await bubble.textContent()).toBe(`/${SKILL_NAME}`)
 
-    const disclosure = card.locator('details')
-    expect(await disclosure.getAttribute('open')).toBeNull()
-    await card.locator('summary').click()
-    const body = card.locator('pre')
-    await body.waitFor()
-    expect(await body.textContent()).toContain(`<skill_content name="${SKILL_NAME}">`)
-    expect(await body.textContent()).toContain('Reply with the fixture acknowledgement line.')
-    expect(await body.textContent()).toContain(ARGS_TEXT)
-    await card.locator('summary').click()
+    // The rendered body arrives as a context-injection row named after the
+    // skill; expanding it reveals the canonical <skill_content> block, and
+    // the user's text is NOT folded into it.
+    const injectionRow = page.getByRole('button', { name: `Context injection ${SKILL_NAME}` })
+    await injectionRow.waitFor({ timeout: 15_000 })
+    await injectionRow.click()
+    const injectionBody = page
+      .locator('[data-context-injection-body]')
+      .filter({ hasText: `<skill_content name="${SKILL_NAME}">` })
+    await injectionBody.waitFor({ timeout: 10_000 })
+    const injected = await injectionBody.textContent()
+    expect(injected).toContain('Reply with the fixture acknowledgement line.')
+    expect(injected).not.toContain(ARGS_TEXT)
+    await injectionRow.click()
 
     // The injection started a turn; the replay seam answers it.
     await page.getByText('USER_INVOKE_REPLY', { exact: false }).first().waitFor({ timeout: 20_000 })
diff --git a/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md b/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md
index b96413f89f..c77081584a 100644
--- a/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md
+++ b/apps/web/tests/snapshots/skill-user-invoke/ui.expected.md
@@ -1,18 +1,20 @@
 - banner:
   - navigation "Session hierarchy":
-    - button "workspace" [disabled]
+    - button "/user-invoke-demo and confirm the fixtur" [disabled]
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- text: /user-invoke-demo and confirm the fixture wiring
-- group: View injected skill content
-- text: {{clock}}
+- text: /user-invoke-demo and confirm the fixture wiring {{clock}}
 - button "Copy":
   - img
 - button "Context injection @deepseek-ai/dsh-system-prompt":
   - img
   - img
   - text: Context injection @deepseek-ai/dsh-system-prompt
+- button "Context injection user-invoke-demo":
+  - img
+  - img
+  - text: Context injection user-invoke-demo
 - paragraph: USER_INVOKE_REPLY acknowledged; following the injected skill.
 - button "Copy":
   - img
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 9f1bf08f9d..470e1d4816 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1471,7 +1471,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/skill/skill/src/index.ts:261`](../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:262`](../packages/skill/skill/src/index.ts)
 
 ## `@deepseek-ai/dsh-skill-local`
 
@@ -2063,7 +2063,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/skill/tool-skill/src/index.ts:59`](../packages/skill/tool-skill/src/index.ts)
+Source: [`packages/skill/tool-skill/src/index.ts:61`](../packages/skill/tool-skill/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-str-replace-editor`
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 55952b3591..6b79018c22 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -677,7 +677,7 @@ A skill provider, runtime contribution, or provider-backed catalog may have chan
 'skills/change'(): void
 ```
 
-Source: [`packages/skill/skill/src/index.ts:279`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:280`](../../packages/skill/skill/src/index.ts)
 
 ## `subagent/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 4abd00c1fd..8820a0329c 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -1946,7 +1946,7 @@ async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefiniti
 
 Types: [SkillCatalogSnapshot](../core-data-structures/skills.md) · [SkillDefinition](../core-data-structures/skills.md) · [SkillLookupOptions](../core-data-structures/skills.md) · [SkillProvider](../core-data-structures/skills.md) · [SkillProviderControl](../core-data-structures/skills.md) · [SkillRegistration](../core-data-structures/skills.md) · [SkillSummary](../core-data-structures/skills.md)
 
-Source: [`packages/skill/skill/src/index.ts:300`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:301`](../../packages/skill/skill/src/index.ts)
 
 ## `ctx.spillStore` — `SpillStore` (abstract seam)
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 7511ab8076..fd8ed3b1fa 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -36,7 +36,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
-| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:279`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
+| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:280`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:160`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:134`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 23b1931cfc..a6cf9c1d7c 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2454,23 +2454,6 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
           ],
         })
       },
-      invoke: (request) => {
-        const missing = requireSession(request)
-        if (missing !== undefined) return missing
-        const { sessionId, name, text: args } = request.payload
-        const body = `<skill_content name="${name}">\n<skill_resources>\nBase directory for this skill: /fixture/skills/${name}\n</skill_resources>\n\n<skill_instructions>\nFixture ${name} instructions.\n</skill_instructions>\n</skill_content>`
-        // Mirror the host: injection is a user-role message carrying the
-        // skill-invocation source, immediately visible in the transcript.
-        // The client program cannot see the host-side MessageSourceMap merge
-        // (sources are opaque wire JSON to the UI), so the fixture stamps the
-        // durable shape through the same assertion the projections read back.
-        const source = { kind: 'skill-invocation', name, ...args === undefined ? {} : { args } } as unknown as MessageSource
-        append(sessionId, {
-          type: 'user/message', surfaceOp: 'append',
-          data: userMessage(text(args === undefined ? body : `${body}\n\n${args}`), source),
-        })
-        return ok(request, { accepted: true as const })
-      },
     },
     goals: {
       // Compatibility face only: old API Proxy payloads and acknowledgements
@@ -2779,7 +2762,6 @@ export class FixtureApiClient extends AbstractApiClient {
       case 'command.list': return this.api.commands.list(request)
       case 'command.execute': return this.api.commands.execute(request, signal)
       case 'skill.list': return this.api.skills.list(request)
-      case 'skill.invoke': return this.api.skills.invoke(request, signal)
       case 'goal.create': return this.api.goals.create(request)
       case 'goal.edit': return this.api.goals.edit(request)
       case 'goal.pause': return this.api.goals.pause(request)
diff --git a/packages/client/connection/tests/fake-api.ts b/packages/client/connection/tests/fake-api.ts
index bd8efaf6a4..cc4504e538 100644
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -163,8 +163,6 @@ export class FakeApiClient implements IApiClient {
   onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
     = () => Promise.resolve(ok({ skills: [] }))
 
-  onSkillInvoke: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>>
-    = () => Promise.resolve(ok({ accepted: true as const }))
 
   readonly commands: IApiClient['commands'] = {
     list: (payload: unknown) => this.record('command.list', payload, this.onCommandList(payload)),
@@ -173,7 +171,6 @@ export class FakeApiClient implements IApiClient {
 
   readonly skills: IApiClient['skills'] = {
     list: (payload: unknown) => this.record('skill.list', payload, this.onSkillList(payload)),
-    invoke: (payload: unknown) => this.record('skill.invoke', payload, this.onSkillInvoke(payload)),
   }
 
   readonly goals: IApiClient['goals'] = {
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index 3864338e28..5a1677df96 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -45,12 +45,11 @@ export { createSnapshotStore, defineStore, shallowEqual } from './contract/store
 export type {
   EngineStoreHandle, EngineStoreInstance, ObservableSnapshot, SnapshotStore,
 } from './contract/store.ts'
-export { opensUserTurn } from './sessions/conversation.ts'
 export type {
   AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
   AssistantTiming, CodeSubCall, CommandNode, CompactionSummaryNode, ComposerPhase,
   ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, QueuedMessage,
-  RunningToolCall, SkillInvocationNode,
+  RunningToolCall,
   SteeringMessageNode, TodoItem, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
 export type {
diff --git a/packages/client/runtime/src/client/sessions/context-provenance.ts b/packages/client/runtime/src/client/sessions/context-provenance.ts
index 5d231b6bd8..6f46a510c1 100644
--- a/packages/client/runtime/src/client/sessions/context-provenance.ts
+++ b/packages/client/runtime/src/client/sessions/context-provenance.ts
@@ -83,6 +83,9 @@ export function contextProvenance(source: unknown): ContextProvenanceView {
       return { role: 'inject', label: joined(collect(record, 'changes', 'path')) ?? kind }
     case 'plugin':
       return { role: 'inject', label: readString(record, 'plugin') ?? kind }
+    // A user-explicit skill invocation names the skill it injected.
+    case 'skill-invocation':
+      return { role: 'inject', label: readString(record, 'name') ?? kind }
     // Documented default arm of the merge-extensible source map: an unknown
     // producer still identifies itself by its own durable kind.
     default:
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index 1ced1b916e..fb2c281331 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -129,25 +129,6 @@ export interface ContextMessageNode {
   form: KnownContextForm | null
 }
 
-/**
- * A user-explicit skill invocation: the host injected the rendered skill as a
- * user message carrying the `skill-invocation` source, so the card presents
- * `/name args` from source metadata and collapses the injected body.
- */
-export interface SkillInvocationNode {
-  kind: 'skill-invocation'
-  seq: number
-  /** Unix epoch ms from the source session event. */
-  time: number
-  /** Invoked skill name read off the message source. */
-  name: string
-  /** Trailing user text read off the message source, when recorded. */
-  args?: string
-  /** Full injected model-facing content (collapsed by default in the UI). */
-  content: readonly ContentBlock[]
-  source: unknown
-}
-
 /** Durable notice that a closed failed step is waiting for a model-request retry. */
 export type ModelRetryNode = LlmRetryEventData & {
   kind: 'model-retry'
@@ -258,27 +239,12 @@ export interface CommandNode {
   outcome: { kind: 'success' | 'error'; text?: string } | null
 }
 
-/**
- * Whether a node opens a user turn on the transcript surface. A direct user
- * message and a user-explicit skill invocation both start the turn the next
- * assistant answer closes; parallel consumers (turn boundaries, retry
- * liveness, own-words scrolling) share this one predicate instead of each
- * re-encoding the kind list. Steering stays out: an interjection lands
- * mid-turn and closes nothing.
- * @param node - any conversation node.
- * @returns true for the user-turn-opening kinds.
- */
-export function opensUserTurn(node: Pick<ConversationNode, 'kind'>): boolean {
-  return node.kind === 'user' || node.kind === 'skill-invocation'
-}
-
 /** Finalized conversation node union (kind discriminates; seq is the React key). */
 export type ConversationNode =
   | UserMessageNode
   | AssistantMessageNode
   | SteeringMessageNode
   | ContextMessageNode
-  | SkillInvocationNode
   | ModelRetryNode
   | TurnErrorNode
   | ToolResultNode
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index 4a05afee06..8b77807c96 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -58,22 +58,10 @@ function materializeNode(
 ): ConversationNode {
   switch (event.type) {
     case 'user/message': {
-      // A user-explicit skill invocation carries its name (and optional args)
-      // on the source; the dedicated node lets the card render `/name args`
-      // from metadata instead of re-parsing the injected body. A record whose
-      // name is unreadable degrades to injected context below.
-      const source = event.data.source as { kind?: unknown; name?: unknown; args?: unknown }
-      if (source.kind === 'skill-invocation' && typeof source.name === 'string') {
-        return {
-          kind: 'skill-invocation', seq: event.seq, time: event.time,
-          name: source.name,
-          ...typeof source.args === 'string' ? { args: source.args } : {},
-          content: event.data.content, source: event.data.source,
-        }
-      }
-      // Injected context (plugin/goal source) folds to a context node, not a
-      // user message; only a direct human prompt is a user node. A compaction
-      // checkpoint never reaches here (isCompactCheckpoint routes it away).
+      // Injected context (plugin/goal/skill-invocation source) folds to a
+      // context node, not a user message; only a direct human prompt is a
+      // user node. A compaction checkpoint never reaches here
+      // (isCompactCheckpoint routes it away).
       if (event.data.source.kind !== 'user') {
         return {
           kind: 'context', seq: event.seq, time: event.time,
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
index def535a59a..2f4299ce6c 100644
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -198,8 +198,6 @@ export class FakeApiClient implements IApiClient {
   onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
     = () => Promise.resolve(ok({ skills: [] }))
 
-  onSkillInvoke: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>>
-    = () => Promise.resolve(ok({ accepted: true as const }))
 
   readonly commands: IApiClient['commands'] = {
     list: (payload: unknown) => this.record('command.list', payload, this.onCommandList(payload)),
@@ -208,7 +206,6 @@ export class FakeApiClient implements IApiClient {
 
   readonly skills: IApiClient['skills'] = {
     list: (payload: unknown) => this.record('skill.list', payload, this.onSkillList(payload)),
-    invoke: (payload: unknown) => this.record('skill.invoke', payload, this.onSkillInvoke(payload)),
   }
 
   readonly goals: IApiClient['goals'] = {
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
index e847c2cec7..a5b423c58d 100644
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ b/packages/client/runtime/tests/transcript-adapter.spec.ts
@@ -164,29 +164,26 @@ describe('TranscriptAdapter', () => {
     expect(adapter.nodes().map(node => node.kind)).toEqual(['user', 'user', 'context'])
   })
 
-  it('materializes a skill-invocation source as its dedicated node', () => {
+  it('materializes a skill-invocation injection as a named instructions context', () => {
     const adapter = new TranscriptAdapter()
     adapter.reset([
       at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '<skill_content name="hidden-demo">body</skill_content>\n\ncheck the fixture' }],
-        source: { kind: 'skill-invocation', name: 'hidden-demo', args: 'check the fixture' } as never,
+        content: [{ type: 'text', text: '/hidden-demo check the fixture' }],
+        source: { kind: 'user' },
       }) }),
       at(1, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '<skill_content name="bare-skill">body</skill_content>' }],
-        source: { kind: 'skill-invocation', name: 'bare-skill' } as never,
+        content: [{ type: 'text', text: '<skill_content name="hidden-demo">body</skill_content>' }],
+        source: { kind: 'skill-invocation', name: 'hidden-demo', form: 'instructions' } as never,
       }) }),
     ])
     const nodes = adapter.nodes()
-    expect(nodes.map(node => node.kind)).toEqual(['skill-invocation', 'skill-invocation'])
-    expect(nodes[0]).toMatchObject({ name: 'hidden-demo', args: 'check the fixture' })
-    expect(nodes[1]).toMatchObject({ name: 'bare-skill' })
-    expect((nodes[1] as { args?: string }).args).toBeUndefined()
-    // A malformed record (no readable name) degrades to injected context, not a crash.
-    adapter.append(at(2, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-      content: [{ type: 'text', text: 'odd' }],
-      source: { kind: 'skill-invocation' } as never,
-    }) }))
-    expect(adapter.nodes().at(-1)?.kind).toBe('context')
+    // The gesture stays a user bubble; the injected body folds to a context
+    // row named after the skill, presented as instructions.
+    expect(nodes.map(node => node.kind)).toEqual(['user', 'context'])
+    expect(nodes[1]).toMatchObject({
+      provenance: { role: 'inject', label: 'hidden-demo' },
+      form: 'instructions',
+    })
   })
 
   it('skips events core does not call surface-eligible, marker or not', () => {
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index a841ba6751..b0907f5a80 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -24,7 +24,6 @@
 import {
   memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
 } from 'react'
-import { opensUserTurn } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   CodeSubCall, CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -119,7 +118,7 @@ function activeRetrySeq(nodes: readonly ConversationNode[], running: boolean): n
     const node = nodes[index]
     if (node === undefined) continue
     if (node.kind === 'model-retry') return node.retryState === 'cancelled' ? null : node.seq
-    if (node.kind === 'assistant' || opensUserTurn(node)) return null
+    if (node.kind === 'assistant' || node.kind === 'user') return null
   }
   return null
 }
@@ -448,11 +447,10 @@ export function ChatView({
       return
     }
     firstSeqRef.current = firstSeq
-    // Own words must be visible: a new trailing user-turn node (a prompt or an
-    // explicit skill invocation) force-scrolls (send lives in the composer, so
-    // arrival is detected here, not armed there).
+    // Own words must be visible: a new trailing user node force-scrolls
+    // (send lives in the composer, so arrival is detected here, not armed there).
     const appendedUser = lastKey !== lastKeyRef.current
-      && lastItem !== undefined && lastItem.kind === 'node' && opensUserTurn(lastItem.node)
+      && lastItem !== undefined && lastItem.kind === 'node' && lastItem.node.kind === 'user'
     const appendedSteering = lastSteeringId !== null && lastSteeringId !== lastSteeringIdRef.current
     const tipMoved = followSigRef.current !== followSig
     lastKeyRef.current = lastKey
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
index 4330cde32c..5c07ace71e 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
@@ -256,30 +256,3 @@
   white-space: nowrap;
   vertical-align: baseline;
 }
-
-/* User-explicit skill invocation: the injected body collapses behind a
-   disclosure inside the user bubble. */
-.skillInvocationDetails {
-  margin-top: 6px;
-}
-
-.skillInvocationSummary {
-  cursor: pointer;
-  font-size: 0.8em;
-  color: var(--dsw-alias-label-secondary);
-  user-select: none;
-}
-
-.skillInvocationBody {
-  margin: 6px 0 0;
-  padding: 8px;
-  max-height: 320px;
-  overflow: auto;
-  border-radius: 6px;
-  background: var(--dsw-alias-bg-secondary, rgba(0, 0, 0, 0.06));
-  font-family: var(--dsw-font-mono, monospace);
-  font-size: 0.78em;
-  line-height: 1.5;
-  white-space: pre-wrap;
-  word-break: break-word;
-}
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
index af2afd9792..30b51b3870 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
@@ -7,8 +7,8 @@
 import { memo, useEffect, useMemo, useState } from 'react'
 import type { ReactNode } from 'react'
 import type {
-  CompactionSummaryNode, ContextMessageNode, ModelRetryNode, SkillInvocationNode,
-  SteeringMessageNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
+  CompactionSummaryNode, ContextMessageNode, ModelRetryNode, SteeringMessageNode,
+  TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { JsonBlock, MessageText, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
@@ -22,7 +22,6 @@ export interface MessageItemProps {
     | UserMessageNode
     | SteeringMessageNode
     | ContextMessageNode
-    | SkillInvocationNode
     | CompactionSummaryNode
     | ModelRetryNode
     | TurnErrorNode
@@ -192,38 +191,6 @@ function UserStyleBubble({
   )
 }
 
-/**
- * A user-explicit skill invocation: the right-aligned bubble presents the
- * `/name args` gesture from source metadata (never re-parsed from the body),
- * and the injected `<skill_content>` collapses behind a disclosure — the
- * durable content is model-facing bulk, not conversation prose.
- */
-function SkillInvocationRow({ node, t }: {
-  node: SkillInvocationNode
-  t: ChatViewSlotProps['t']
-}): ReactNode {
-  const { text } = contentText(node.content)
-  return (
-    <div className={css.userRow} data-skill-invocation data-time-hover-root>
-      <div className={css.bubble}>
-        <span className={css.refChip} data-ref-chip="skill">{`/${node.name}`}</span>
-        {node.args !== undefined && <MessageText text={` ${node.args}`} />}
-        <details className={css.skillInvocationDetails}>
-          <summary className={css.skillInvocationSummary}>{t('message.skillInvocation.expand')}</summary>
-          <pre className={css.skillInvocationBody}>{text}</pre>
-        </details>
-      </div>
-      <MessageIconActions
-        text={text}
-        time={node.time}
-        clock="start"
-        className={css.actions}
-        t={t}
-      />
-    </div>
-  )
-}
-
 /**
  * Render one Host-authoritative pending steering item with the same visual
  * language as its eventual durable transcript node.
@@ -285,8 +252,6 @@ export const MessageItem = memo(function MessageItem({
           t={t}
         />
       )
-    case 'skill-invocation':
-      return <SkillInvocationRow node={node} t={t} />
     case 'compaction':
       return <CompactionItem node={node} t={t} />
     case 'model-retry':
diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index a340a2f634..df107d2cd2 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -79,7 +79,6 @@ export const zh = {
   'message.context.recall.counts': '保留 {retained} 条 · 省略 {omitted} 条',
   'message.context.recall.truncated': '已截断',
   'message.steering': '插话',
-  'message.skillInvocation.expand': '查看注入的 skill 内容',
   'message.compaction': '上下文已压缩',
   'message.compaction.expand': '点击查看压缩摘要',
   'message.compaction.unavailable': '压缩摘要不可用',
@@ -220,7 +219,6 @@ export const en = {
   'message.context.recall.counts': '{retained} kept · {omitted} omitted',
   'message.context.recall.truncated': 'truncated',
   'message.steering': 'Interjection',
-  'message.skillInvocation.expand': 'View injected skill content',
   'message.compaction': 'Context compacted',
   'message.compaction.expand': 'View compaction summary',
   'message.compaction.unavailable': 'Compaction summary unavailable',
diff --git a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
index 9471461cda..28b0501141 100644
--- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
@@ -865,41 +865,6 @@ describe('MessageItem arms', () => {
     expect(view.getByRole('status').textContent).toBe('正在重试模型请求（1/2） · 1s')
   })
 
-  it('skill-invocation renders the /name chip, args, and a collapsed injected body', () => {
-    const body = '<skill_content name="hidden-demo">instructions</skill_content>\n\ncheck the fixture'
-    const view = render(
-      <MessageItem t={t} node={{
-        kind: 'skill-invocation', seq: 4, time: 1_000,
-        name: 'hidden-demo', args: 'check the fixture',
-        content: [{ type: 'text', text: body }] as never,
-        source: null,
-      }}
-      />,
-    )
-    const chip = view.container.querySelector('[data-ref-chip="skill"]')
-    expect(chip?.textContent).toBe('/hidden-demo')
-    const details = view.container.querySelector('details')
-    expect(details).toBeTruthy()
-    expect(details?.open).toBe(false)
-    expect(view.getByText('查看注入的 skill 内容')).toBeTruthy()
-    expect(view.container.querySelector('pre')?.textContent).toBe(body)
-    expect(view.container.querySelector('[data-skill-invocation]')).toBeTruthy()
-  })
-
-  it('skill-invocation without args renders only the chip line', () => {
-    const view = render(
-      <MessageItem t={t} node={{
-        kind: 'skill-invocation', seq: 5, time: 1_000,
-        name: 'bare-skill',
-        content: [{ type: 'text', text: '<skill_content name="bare-skill">x</skill_content>' }] as never,
-        source: null,
-      }}
-      />,
-    )
-    const bubble = view.container.querySelector('[data-skill-invocation]')
-    expect(bubble?.textContent).toContain('/bare-skill')
-    expect(bubble?.textContent).not.toContain('undefined')
-  })
 })
 
 describe('formatMessageClock', () => {
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index b8886be0df..c9754d1da4 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -3,7 +3,6 @@
  * nodes. Client-only and model-free: the vocabulary is the mutation tools'
  * own follow-along `locations`, never the closing prose.
  */
-import { opensUserTurn } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
@@ -63,7 +62,7 @@ export function producedForClosing(nodes: readonly ConversationNode[], seq: numb
       }
       continue
     }
-    if (opensUserTurn(node)) {
+    if (node.kind === 'user') {
       turn = undefined
       pending = []
       seen = new Set()
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index 473defc4e6..845e6099c8 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -73,26 +73,6 @@ describe('producedForClosing derivation', () => {
     expect(producedForClosing(nodes, 999)).toEqual([])
   })
 
-  it('treats a user-explicit skill invocation as a turn boundary', () => {
-    // The injection opens a user turn exactly like a typed prompt: files
-    // written before it must not spill into the turn its answer closes.
-    const skillInvocation = {
-      kind: 'skill-invocation' as const, seq: 4, time: 4_000,
-      name: 'hidden-demo',
-      content: [{ type: 'text', text: '<skill_content name="hidden-demo">x</skill_content>' }] as never,
-      source: null,
-    }
-    const nodes: ConversationNode[] = [
-      user(1, 'write things'),
-      assistant(2, 'wrote', 1),
-      wrote(3, 'a', 'stale.txt'),
-      skillInvocation,
-      wrote(5, 'b', 'fresh.txt'),
-      assistant(6, 'followed the skill', 2),
-    ]
-    expect(producedForClosing(nodes, 6)).toEqual(['fresh.txt'])
-    expect(producedForClosing(nodes, 6)).not.toContain('stale.txt')
-  })
 
   it('counts a generic edit and never spills across the turn boundary', () => {
     const inserted = (seq: number, callId: string, path: string): ToolResultNode => ({
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index 5b80baa912..a1d1a2c9d5 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/client/ui-skill/README.md
-README.md: ea3dbf3592995903422ec951e20c911082370dbe
-README.zh.md: 5b8886e67973af9a594ff6aa2e9295f112a9f3e3
+README.md: bdd772662acda1f8cf1b7d8a7c5532f9b37123dd
+README.zh.md: 959ff0ede6d545150fb22710c8af75859966caa9
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index ea3dbf3592..bdd772662a 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Skill invocation source, browser half: registers the `/`-trigger `skill` source into `ctx.slash`. Ordinary-session candidates come from the `skill.list` RPC addressed by the per-call `ClientSessionContext` projection's `{sessionId}`, with the host resolving `cwd` from the session header. The host serves every user-invocable skill; a `modelInvocable: false` entry (a `disable-model-invocation` skill, whose only entry point is this path) wears the user-only marker as a description prefix in the active language. Catalog-addressed continuable children resolve no skill candidates locally because the existing skill RPC requires an attached session; viewing their persisted history must not activate them. Catalogs cache per ordinary session with a single-flight fetch; the scope-birth `warm` hook prewarms the session's entry and `connection/reset` clears everything. Results filter by `startsWith(query)`.
 
-A menu pick or an entered `/name [args]` line claims the composer into an args-tolerant `skill.invoke` transaction (`matchEnter` strong-waits the catalog; an unknown name answers undefined and stays a plain prompt). A skill name shared with a host command resolves to the command: adjudication polls sources in registration order and the web bundle mounts ui-command ahead of this source — deliberate precedence, matching peer products. Submit trims the args, keeps blank args off the wire, and folds an RPC refusal into the composer's error outcome; the host renders the skill body and injects it as a user message before starting the turn, so invocation is deterministic for every user-invocable skill. The RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument. Draft chip visuals still derive from the `lexicon` scan; the legacy `<skill>name</skill>` reference codec is gone (decision 21 removal cut) and `matchSpace` stays unimplemented — menu and enter own the skill flows.
+A pick lands the literal `/name ` text and the prompt ships the same literal (decision 21) — this source implements no adjudication hooks and no reference codec (the legacy `<skill>name</skill>` form is gone with the removal cut). Determinism lives host-side: the pre-step gesture boundary (`dsh-tool-skill`) recognizes whitespace-bounded `/name` tokens naming user-invocable skills anywhere in a user message and injects the rendered `<skill_content>` for every front end, so a menu pick, a hand-typed token, and a TUI/ACP prompt all load the skill the same way. A name shared with a host command still resolves to the command: adjudication claims the line client-side before it ever becomes a prompt — deliberate precedence, matching peer products. The list RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument; draft chip visuals derive from the `lexicon` scan.
 
 A failed `skill.list` throws from `candidates`, which the slash shell logs and folds into a silent menu-group drop — the menu shows only pending/ready states.
 
@@ -20,11 +20,11 @@ The browser plugin also registers a keyed `skill` toolview in `conversation.chat
 
 #### What the model sees
 
-A claimed invocation never ships the `/name` literal. The host (`skill.invoke`) renders the canonical `<skill_content>` block — the same `renderSkillContent` output the `skill` tool returns — appends the user's trailing text after a blank line, and injects the whole as one user-role message carrying the `skill-invocation` source, immediately starting a turn. Loading is deterministic: the model receives the full body without being asked to call the `skill` tool, and the catalog (rendered by `dsh-tool-skill`) tells it not to re-load an inline-injected skill.
+The user's message reaches the model verbatim, `/name` literal included. The host's pre-step boundary (`dsh-tool-skill`) then appends the canonical `<skill_content>` block — the same `renderSkillContent` output the `skill` tool returns — as injected instructions context at the end of that step's injections, closest to the model's answer. Loading is deterministic: the model receives the full body without being asked to call the `skill` tool, and the catalog tells it not to re-load an inline-injected skill.
 
 #### Token effect
 
-One invocation adds the rendered skill body plus the trailing text to that turn's user message — the same cost as the model loading the skill through the tool, paid unconditionally instead of at the model's discretion. Menu browsing and the candidate fetch add zero model tokens.
+One invocation adds the rendered skill body to that turn as injected context — the same cost as the model loading the skill through the tool, paid unconditionally instead of at the model's discretion. Menu browsing and the candidate fetch add zero model tokens.
 
 #### KV Cache effect
 
@@ -33,5 +33,5 @@ Append-only: the injected message lands after the reusable history prefix. This
 ## Known Limitations and Deferred Work
 
 - **Result-only history pages use the generic row** — keyed dispatch needs the paired call in the runtime window; pagination that leaves the call outside has no tool identity. This client presentation feature does not extend the history wire contract to recover it.
-- **Enter waits on the catalog once** — `matchEnter` strong-waits the session's first catalog fetch before answering, so an enter racing a cold cache resolves against the settled catalog rather than silently missing. A menu opened before the prewarm settles still shows no skill candidates for that keystroke.
-- **Text is the truth** — the reference is plain draft text; a hand-typed identical token is the same reference. Chip visuals derive from the lexicon scan; no occurrence identity or position tracking (componentized chips are a ledger item).
+- **Text is the truth** — the reference is plain draft text; a hand-typed identical token is the same reference, and the host gesture boundary judges the sent text, not the menu interaction. Chip visuals derive from the lexicon scan; no occurrence identity, position tracking, or structured reference payload on the prompt wire (both are ledger items).
+- **A menu opened before the prewarm settles** shows no skill candidates for that keystroke; the next keystroke re-polls the settled cache.
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 5b8886e679..959ff0ede6 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -4,7 +4,7 @@
 
 skill（技能）调用 source 的浏览器端：把 `/` 触发的 `skill` source 注册进 `ctx.slash`。普通会话的候选来自 `skill.list` RPC，以每次调用的 `ClientSessionContext` 投影中的 `{sessionId}` 寻址，host 从会话 header 解析 `cwd`。宿主提供每一个用户可调用的 skill；`modelInvocable: false` 的条目（即 `disable-model-invocation` skill，此路径是其唯一入口）会以当前语言把仅限用户标记作为描述前缀带上。由目录寻址的可继续 subagent 在客户端解析为没有 skill 候选，因为现有 skill RPC 要求会话已挂载；查看其持久化历史不得激活它。目录按普通会话缓存，拉取走 single-flight；scope 创建时的 `warm` 钩子预热该会话的缓存项，`connection/reset` 清空全部缓存。结果按 `startsWith(query)` 过滤。
 
-菜单 pick 或回车提交的一行 `/name [args]` 会把 composer 认领进一个容忍参数的 `skill.invoke` 事务（`matchEnter` 强等目录；未知名称应答 undefined，保持为普通提示词）。与宿主命令同名的 skill 名解析为命令：裁决按注册顺序轮询各 source，而 web bundle 把 ui-command 挂载在本 source 之前——这是有意的优先级，与同行产品一致。提交时会修剪参数、让空白参数不上协议，并把 RPC 拒绝折叠进 composer 的错误结局；宿主在开启轮次之前渲染 skill 正文并将其作为用户消息注入，因此对每一个用户可调用的 skill，调用都是确定性的。RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务。草稿 chip 视觉仍由 `lexicon` 扫描派生；旧的 `<skill>name</skill>` 引用 codec 已经移除（决策 21 的移除裁定），`matchSpace` 保持不实现——skill 流程归菜单与回车所有。
+pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文本（决策 21）——本 source 不实现任何裁决钩子，也没有引用 codec（旧的 `<skill>name</skill>` 形式已随移除裁定消失）。确定性在宿主侧：pre-step 手势边界（`dsh-tool-skill`）识别用户消息中任意位置、以空白为界、指名用户可调用 skill 的 `/name` token，并为每一种前端注入渲染后的 `<skill_content>`，因此菜单 pick、手动键入的 token 与 TUI/ACP 提示词都以同一种方式加载 skill。与宿主命令同名的名称仍解析为命令：裁决在客户端把该行认领走，它根本不会成为提示词——这是有意的优先级，与同行产品一致。列表 RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务；草稿 chip 视觉由 `lexicon` 扫描派生。
 
 `skill.list` 失败时 `candidates` 抛出异常，slash 壳层记录日志并折叠为静默的菜单组丢弃——菜单只显示 pending／ready 状态。
 
@@ -20,11 +20,11 @@ skill（技能）调用 source 的浏览器端：把 `/` 触发的 `skill` sourc
 
 #### 模型看到的内容
 
-被认领的调用绝不会把字面文本 `/name` 发出去。宿主（`skill.invoke`）渲染规范的 `<skill_content>` 块——与 `skill` 工具返回的 `renderSkillContent` 输出相同——在一个空行之后追加用户的尾随文本，并把整体作为一条携带 `skill-invocation` 来源的 user 角色消息注入，随即开启一个轮次。加载是确定性的：模型无需被要求调用 `skill` 工具就能收到完整正文，目录（由 `dsh-tool-skill` 渲染）也会告诉它不要重新加载已内联注入的 skill。
+用户消息原样到达模型，字面文本 `/name` 也包含在内。随后宿主的 pre-step 边界（`dsh-tool-skill`）把规范的 `<skill_content>` 块——与 `skill` 工具返回的 `renderSkillContent` 输出相同——作为注入的指令上下文追加在该步骤各项注入的末尾，最贴近模型的回答。加载是确定性的：模型无需被要求调用 `skill` 工具就能收到完整正文，目录也会告诉它不要重新加载已内联注入的 skill。
 
 #### Token 影响
 
-一次调用会把渲染后的 skill 正文连同尾随文本加进该轮次的用户消息——成本与模型经由工具加载该 skill 相同，只是无条件支付，而非由模型自行裁量。浏览菜单和拉取候选不会增加任何模型 token。
+一次调用会把渲染后的 skill 正文作为注入上下文加进该轮次——成本与模型经由工具加载该 skill 相同，只是无条件支付，而非由模型自行裁量。浏览菜单和拉取候选不会增加任何模型 token。
 
 #### KV Cache 影响
 
@@ -33,5 +33,5 @@ skill（技能）调用 source 的浏览器端：把 `/` 触发的 `skill` sourc
 ## 已知限制与暂缓事项
 
 - **仅含结果的 history 页使用通用行**：键控分派要求配对调用位于 runtime 窗口内；分页将调用留在窗口外时，结果没有工具身份。这项客户端呈现功能不会为了恢复该身份而扩展 history 协议契约。
-- **回车对目录只等待一次**：`matchEnter` 在应答之前强等该会话的首次目录拉取，因此与冷缓存竞速的回车会对照已落定的目录解析，而不是静默错过。预热落定之前打开的菜单，在那次击键下仍不会显示 skill 候选。
-- **文本是唯一依据**：引用是普通的草稿文本；手动键入的相同 token 就是同一个引用。chip 视觉由 lexicon 扫描派生；没有 occurrence 身份或位置跟踪（组件化 chip 是台账事项）。
+- **文本是唯一依据**：引用是普通的草稿文本；手动键入的相同 token 就是同一个引用，宿主手势边界评判的是发出的文本，而不是菜单交互。chip 视觉由 lexicon 扫描派生；没有 occurrence 身份、位置跟踪，也没有提示词协议上的结构化引用载荷（两者都是台账事项）。
+- **预热落定之前打开的菜单**：在那次击键下不显示 skill 候选；下一次击键会重新轮询已落定的缓存。
diff --git a/packages/client/ui-skill/src/client/index.ts b/packages/client/ui-skill/src/client/index.ts
index a73370b8ff..4e23be06be 100644
--- a/packages/client/ui-skill/src/client/index.ts
+++ b/packages/client/ui-skill/src/client/index.ts
@@ -2,15 +2,16 @@
  * Skill reference plugin, browser half: registers the '/' skill source —
  * candidates from the skill.list RPC addressed by the per-call session
  * projection's sessionId (sessions are always agent-backed; the host
- * resolves cwd from the session header). A menu pick or an entered `/name
- * [args]` line claims into a skill.invoke transaction: the host renders the
- * skill body and injects it as a user message, so invocation is
- * deterministic for every user-invocable skill — including
- * `disable-model-invocation` skills the model-side catalog never lists
- * (issue #1470). The RPC rides the plugin's root-context connection
- * captured at registration — the source never reads services off a per-call
- * argument. Draft chip visuals still derive from the lexicon scan; the
- * legacy `<skill>` reference codec is gone (decision 21 removal cut).
+ * resolves cwd from the session header). A pick lands the literal `/name `
+ * text and the prompt ships the same literal (decision 21); determinism
+ * lives host-side — the pre-step boundary (`dsh-tool-skill`) recognizes a
+ * leading `/name` naming a user-invocable skill and injects the rendered
+ * body for every front end, including `disable-model-invocation` skills the
+ * model-side catalog never lists (issue #1470). The RPC rides the plugin's
+ * root-context connection captured at registration — the source never reads
+ * services off a per-call argument. Draft chip visuals still derive from
+ * the lexicon scan; the legacy `<skill>` reference codec is gone (decision
+ * 21 removal cut).
  *
  * Catalog fetches are cached per session (the small twin of the ui-command
  * directory): the per-keystroke candidates re-poll filters a settled
@@ -27,7 +28,7 @@
  */
 import type { ConnectionHandle, SessionId, SkillEntry } from '@deepseek-ai/dsh-client-connection/client'
 import type { ClientContext, ISessions } from '@deepseek-ai/dsh-client-runtime/client'
-import type { PickOutcome, SlashServiceContract, SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
+import type { SlashServiceContract, SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import { SkillRow } from './SkillRow.tsx'
@@ -125,27 +126,6 @@ export function apply(ctx: ClientContext): void {
   // locale service's own fallback ladder; candidate-time reads stay plain text.
   const t = ctx.locale.bind(NS)
 
-  /**
-   * Args-tolerant claim for one skill: token `/name ` plus the skill.invoke
-   * transaction. Blank args stay off the wire; an RPC refusal folds into the
-   * composer's error outcome (transport failures throw).
-   */
-  const invokeClaim = (session: { readonly sessionId: SessionId }, name: string): PickOutcome => ({
-    claim: {
-      token: `/${name} `,
-      submit: async (args) => {
-        const trimmed = args.trim()
-        const { result } = await skills.invoke({
-          sessionId: session.sessionId,
-          name,
-          ...trimmed === '' ? {} : { text: trimmed },
-        })
-        if (!result.ok) return { kind: 'error', text: `${result.error.code}: ${result.error.message}` }
-        return { kind: 'success' }
-      },
-    },
-  })
-
   const source: SlashSource = {
     trigger: '/',
     name: 'skill',
@@ -181,25 +161,14 @@ export function apply(ctx: ClientContext): void {
         if (listeners.size === 0) lexiconListeners.delete(key)
       }
     },
-    onPick({ candidate, session }) {
-      return invokeClaim(session, candidate.name)
-    },
-    // Adjudication polls sources in registration order and the web bundle
-    // mounts ui-command first, so a name shared with a host command claims as
-    // the command — deliberate precedence (commands are explicit host
-    // features; peer products resolve the collision the same way), not a race.
-    async matchEnter(session, line, signal) {
-      const trimmed = line.trim()
-      if (!trimmed.startsWith('/')) return undefined
-      const ws = trimmed.search(/\s/)
-      const name = (ws === -1 ? trimmed : trimmed.slice(0, ws)).slice(1)
-      if (name === '') return undefined
-      // Strong-wait the catalog: an unknown name stays a plain prompt (the
-      // default sink), never a swallowed line.
-      const catalog = await fetchCatalog(session.sessionId)
-      if (signal.aborted) return undefined
-      if (!catalog.some(skill => skill.name === name)) return undefined
-      return invokeClaim(session, name)
+    onPick({ candidate }) {
+      // Decision 21: the pick lands plain text and the prompt ships the same
+      // literal. Determinism no longer rides the client — the host's
+      // pre-step boundary (dsh-tool-skill) recognizes the leading /name and
+      // injects the rendered body for every front end. A name shared with a
+      // host command still resolves to the command: adjudication claims the
+      // line client-side before it ever becomes a prompt.
+      return { text: `/${candidate.name} ` }
     },
   }
   const slash = ctx.get('slash') as SlashServiceContract
diff --git a/packages/client/ui-skill/tests/browser-plugin.spec.ts b/packages/client/ui-skill/tests/browser-plugin.spec.ts
index da99ed70d3..f73a8d8bda 100644
--- a/packages/client/ui-skill/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts
@@ -322,10 +322,9 @@ describe('lexicon', () => {
   })
 })
 
-describe('pick claims into skill.invoke', () => {
-  it('onPick returns an args-tolerant claim whose submit invokes the skill', async () => {
-    const invoke = vi.fn(() => Promise.resolve({ result: { ok: true as const, value: { accepted: true as const } } }))
-    const { source } = await bench(listOk(CATALOG), undefined, invoke)
+describe('pick lands plain text (decision 21)', () => {
+  it('onPick returns the literal /name text with a closing space', async () => {
+    const { source } = await bench(listOk(CATALOG))
     const outcome = source.onPick({
       candidate: { name: 'commit-helper', description: 'commit flow' },
       session: proj('s1'),
@@ -333,58 +332,16 @@ describe('pick claims into skill.invoke', () => {
       via: 'menu',
       span: { start: 0, end: 4, draftRev: 7 },
     })
-    if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected a claim outcome')
-    expect(outcome.claim.token).toBe('/commit-helper ')
-    await expect(outcome.claim.submit('check the fixture', {} as never)).resolves.toEqual({ kind: 'success' })
-    expect(invoke).toHaveBeenCalledWith({ sessionId: sid('s1'), name: 'commit-helper', text: 'check the fixture' })
+    expect(outcome).toEqual({ text: '/commit-helper ' })
   })
 
-  it('submit omits blank args and folds an RPC refusal into an error outcome', async () => {
-    const invoke = vi.fn(() => Promise.resolve({
-      result: { ok: false as const, error: { code: 'skill-not-invocable', message: 'nope', details: { name: 'deploy' } } },
-    }))
-    const { source } = await bench(listOk(CATALOG), undefined, invoke)
-    const outcome = source.onPick({
-      candidate: { name: 'deploy', description: 'deploy flow' },
-      session: proj('s1'),
-      position: 'leading',
-      via: 'menu',
-      span: { start: 0, end: 4, draftRev: 7 },
-    })
-    if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected a claim outcome')
-    await expect(outcome.claim.submit('   ', {} as never))
-      .resolves.toEqual({ kind: 'error', text: 'skill-not-invocable: nope' })
-    expect(invoke).toHaveBeenCalledWith({ sessionId: sid('s1'), name: 'deploy' })
-  })
-
-  it('drops the legacy reference codec (decision 21 removal cut)', async () => {
+  it('keeps the legacy reference codec removed and stays out of adjudication', async () => {
     const { source } = await bench(listOk(CATALOG))
+    // Determinism lives host-side (the pre-step gesture boundary), so the
+    // source neither claims lines nor serializes reference markup.
     expect(source.codec).toBeUndefined()
-  })
-})
-
-describe('adjudication', () => {
-  it('claims an entered /name line, args-tolerant, once the catalog knows the name', async () => {
-    const invoke = vi.fn(() => Promise.resolve({ result: { ok: true as const, value: { accepted: true as const } } }))
-    const { source } = await bench(listOk(CATALOG), undefined, invoke)
-    const outcome = await source.matchEnter!(proj('s1'), '/deploy run the smoke suite', new AbortController().signal)
-    if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected a claim outcome')
-    expect(outcome.claim.token).toBe('/deploy ')
-    await outcome.claim.submit('run the smoke suite', {} as never)
-    expect(invoke).toHaveBeenCalledWith({ sessionId: sid('s1'), name: 'deploy', text: 'run the smoke suite' })
-  })
-
-  it('answers undefined for unknown names, non-slash lines, and bare "/"', async () => {
-    const { source } = await bench(listOk(CATALOG))
-    const signal = new AbortController().signal
-    await expect(source.matchEnter!(proj('s1'), '/unlisted do it', signal)).resolves.toBeUndefined()
-    await expect(source.matchEnter!(proj('s1'), 'plain prose', signal)).resolves.toBeUndefined()
-    await expect(source.matchEnter!(proj('s1'), '/', signal)).resolves.toBeUndefined()
-  })
-
-  it('never claims on space (menu and enter own the skill flows)', async () => {
-    const { source } = await bench(listOk(CATALOG))
     expect(typeof source.matchSpace).toBe('undefined')
+    expect(typeof source.matchEnter).toBe('undefined')
   })
 })
 
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 017bd32970..961b48dd0b 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 8d7a24b0b8b897d94ed29d5dc9ed6e9efb250fc6
-README.zh.md: c988b7540ba719d02e50d6da9595353c93766835
+README.md: 5506cbef7b778a870e1e28c3f9fdf1713f89d65f
+README.zh.md: de31f653944097e9b47a966f56c418dc9fa9b1b9
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 8d7a24b0b8..5506cbef7b 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -46,7 +46,7 @@ Directory picking delegates to the composed `ctx.directoryPicker` backend ([the
 
 `host.openPath` opens a filesystem path with the operating system's default application (`open` on macOS, `Invoke-Item` on Windows, and `xdg-open` on desktop Linux). For `.html`, `.htm`, `.xhtml`, and `.svg`, macOS and desktop Linux prefer a named default browser and fall back to that application handoff when none can be named. WSL translates every Linux path through `wslpath -w` and hands the resulting Windows/UNC path to Windows `Invoke-Item`, including browser-renderable documents, instead of assuming a Linux desktop association. The browser carrier applies the same loopback, same-origin restriction as `host.pickDirectory`.
 
-The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the composer's invocation path: it returns every user-invocable skill with its `modelInvocable` flag, so menus can mark user-only (`disable-model-invocation`) entries whose only entry point this is. `skill.invoke` is the user-explicit loading RPC: it enforces user-invocation policy at this boundary (`skill-not-found` / `skill-not-invocable`), renders the canonical `<skill_content>` body via the shared `renderSkillContent`, appends the optional trailing `text`, injects the whole as a user-role message carrying the `skill-invocation` source, and starts a turn through the same route-served refusal gate as `session.prompt`. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
+The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the composer's menu: it returns every user-invocable skill with its `modelInvocable` flag, so menus can mark user-only (`disable-model-invocation`) entries whose only entry point the slash gesture is. Listing is the skill domain's only RPC — invocation itself is an ordinary `session.prompt` whose whitespace-bounded `/name` tokens `dsh-tool-skill` recognizes at the pre-step boundary and answers with injected `<skill_content>` context, so every front end (web, TUI, ACP, hand-typed text) shares one deterministic path with no dedicated invocation wire. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
 
 The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves the namespaces addressed by registered configurable providers (`ctx.llm.listConfigurableProviders()`) plus a small explicit allowlist — the Web preference `permission` and the product-owned `ui-onboarding`; adding a Settings registration alone never makes it remotely readable or writable. Any other namespace answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, the section's `revision`, and the boolean `hasDocument` capability flag. The browser receives no Host path: pathless `settings.openDocument` asks the provider to materialize its document and then hands the Host-resolved result to the native opener, so no browser payload can select an arbitrary filesystem target. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. `llm.discoverModels` interrogates a provider endpoint the page is still drafting: `settingsNs` selects the adapter family that knows how to read the listing, and the endpoint, protocol, and key come from the form rather than from storage. It writes nothing — the reply is candidates, and only a later `settings.mutate` decides what a route serves — so its `apiKey` is the third payload on which a secret may ride, alongside `settings.update`/`mutate` and `credentials.set`. The host never stores or returns it; like the other two it does ride the client's outgoing envelope, which `subscribeEnvelopes()` observers can see, and redacting that tap is a configuration-plane-wide change rather than this method's to make alone. Every refusal (an unserved namespace, a protocol with no readable listing, an unreachable endpoint, a rejected credential) folds into `model-discovery-failed`, whose message is the adapter's own text and whose details name the endpoint asked but never the credential offered. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired by `llm/adapters-updated` and by a change to a configurable-provider namespace, whose settings carry that provider's catalog and endpoint; a `permission` or `ui-onboarding` change emits only its settings invalidation. The browser carrier restricts the whole configuration plane, reads and native actions included (`settings.describe`/`openDocument`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index c988b7540b..de31f65394 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -46,7 +46,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 `host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，桌面 Linux 为 `xdg-open`）。对于 `.html`、`.htm`、`.xhtml` 与 `.svg`，macOS 和桌面 Linux 会优先使用能够确定的默认浏览器；无法确定时回退到上述应用交接。WSL 会通过 `wslpath -w` 转换每个 Linux 路径，并将所得 Windows/UNC 路径交给 Windows `Invoke-Item`，浏览器可渲染的文档也不例外，而非假定存在 Linux 桌面文件关联。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。
 
-`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于 composer 的调用路径：它返回每一个用户可调用的 skill 及其 `modelInvocable` 标志，让菜单能够标出仅限用户（`disable-model-invocation`）的条目——此处是这类条目唯一的入口。`skill.invoke` 是用户显式加载 RPC：它在此边界强制执行用户调用策略（`skill-not-found`/`skill-not-invocable`），经共享的 `renderSkillContent` 渲染规范的 `<skill_content>` 正文，追加可选的尾随 `text`，把整体作为一条携带 `skill-invocation` 来源的 user 角色消息注入，并经由与 `session.prompt` 相同的「路由是否有适配器在服务」拒绝闸门开启一个轮次。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
+`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于 composer 的菜单：它返回每一个用户可调用的 skill 及其 `modelInvocable` 标志，让菜单能够标出仅限用户（`disable-model-invocation`）的条目——斜杠手势是这类条目唯一的入口。列表是 skill 领域唯一的 RPC——调用本身就是一次普通的 `session.prompt`，`dsh-tool-skill` 会在 pre-step 边界识别其中以空白为界的 `/name` token，并以注入的 `<skill_content>` 上下文作答，因此每一种前端（web、TUI、ACP、手动键入的文本）共享同一条确定性路径，没有专设的调用协议。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
 
 `settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个、也是最后一个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
 
diff --git a/packages/host/apiproxy/src/api/rpc-map.ts b/packages/host/apiproxy/src/api/rpc-map.ts
index b001d54625..9a8750c722 100644
--- a/packages/host/apiproxy/src/api/rpc-map.ts
+++ b/packages/host/apiproxy/src/api/rpc-map.ts
@@ -50,7 +50,6 @@ export interface RpcMethodMap {
   'command.list': CommandsApi['list']
   'command.execute': CommandsApi['execute']
   'skill.list': SkillsApi['list']
-  'skill.invoke': SkillsApi['invoke']
   'goal.create': GoalsApi['create']
   'goal.edit': GoalsApi['edit']
   'goal.pause': GoalsApi['pause']
diff --git a/packages/host/apiproxy/src/api/rpc.schema.ts b/packages/host/apiproxy/src/api/rpc.schema.ts
index dd3fe7cf57..2733c6e940 100644
--- a/packages/host/apiproxy/src/api/rpc.schema.ts
+++ b/packages/host/apiproxy/src/api/rpc.schema.ts
@@ -51,8 +51,6 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('steer-unavailable'), message: z.string(), details: z.object({ itemId: z.string() }) }),
   z.object({ code: z.literal('command-error'), message: z.string(), details: z.object({}) }),
   z.object({ code: z.literal('unknown-command'), message: z.string(), details: z.object({}) }),
-  z.object({ code: z.literal('skill-not-found'), message: z.string(), details: z.object({ name: z.string() }) }),
-  z.object({ code: z.literal('skill-not-invocable'), message: z.string(), details: z.object({ name: z.string() }) }),
   z.object({ code: z.literal('settings-rejected'), message: z.string(), details: z.object({ ns: z.string() }) }),
   z.object({ code: z.literal('settings-not-exposed'), message: z.string(), details: z.object({ ns: z.string() }) }),
   z.object({ code: z.literal('settings-conflict'), message: z.string(), details: z.object({ ns: z.string(), expected: z.number(), actual: z.number() }) }),
diff --git a/packages/host/apiproxy/src/api/rpc.ts b/packages/host/apiproxy/src/api/rpc.ts
index 7bf41a32e1..54bbb5a8cc 100644
--- a/packages/host/apiproxy/src/api/rpc.ts
+++ b/packages/host/apiproxy/src/api/rpc.ts
@@ -51,10 +51,6 @@ export interface RpcErrorDetailsMap {
   'command-error': {}
   /** A leading-/ prompt named no registered command; the message names the token. */
   'unknown-command': {}
-  /** A skill invocation named no skill in the session's workspace (unknown or ill-formed name). */
-  'skill-not-found': { name: string }
-  /** A skill invocation named a skill whose policy forbids user invocation. */
-  'skill-not-invocable': { name: string }
   /**
    * A settings write was refused (schema validation, unknown namespace,
    * read-only provider, or storage failure); the message is the seam's text.
diff --git a/packages/host/apiproxy/src/api/skills.schema.ts b/packages/host/apiproxy/src/api/skills.schema.ts
index 1741a93a46..747bf19bad 100644
--- a/packages/host/apiproxy/src/api/skills.schema.ts
+++ b/packages/host/apiproxy/src/api/skills.schema.ts
@@ -26,18 +26,3 @@ export const skillListRequestSchema = z.object({
 export const skillListValueSchema = z.object({
   skills: z.array(skillEntrySchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'skill.list'>>>
-
-/**
- * skill.invoke request payload. `text` is the user's trailing message; a
- * blank one stays off the wire (the boundary, not client courtesy, refuses it).
- */
-export const skillInvokeRequestSchema = z.object({
-  sessionId: sessionIdSchema,
-  name: z.string().min(1),
-  text: z.string().min(1).optional(),
-}) satisfies z.ZodType<Wire<RequestPayload<'skill.invoke'>>>
-
-/** skill.invoke response value. */
-export const skillInvokeValueSchema = z.object({
-  accepted: z.literal(true),
-}) satisfies z.ZodType<Wire<ResponseValue<'skill.invoke'>>>
diff --git a/packages/host/apiproxy/src/api/skills.ts b/packages/host/apiproxy/src/api/skills.ts
index 698a9f0190..3b3e711a93 100644
--- a/packages/host/apiproxy/src/api/skills.ts
+++ b/packages/host/apiproxy/src/api/skills.ts
@@ -20,22 +20,14 @@ export interface SkillEntry {
   readonly modelInvocable: boolean
 }
 
-/** Skill-domain unary methods (the map keys skill.* of RpcMethodMap). */
+/**
+ * Skill-domain unary methods (the map key skill.* of RpcMethodMap). Listing
+ * is the domain's only RPC: invocation itself is a plain `session.prompt`
+ * whose leading `/name` token the host recognizes at the pre-step boundary
+ * (`dsh-tool-skill` injects the rendered body there), so every client shares
+ * one deterministic path with no dedicated invocation wire.
+ */
 export interface SkillsApi {
   /** Lists the user-invocable skill catalog for the session's project. */
   list(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ skills: readonly SkillEntry[] }>>
-
-  /**
-   * Injects one user-invocable skill into the addressed agent as a user-role
-   * message (the canonical `<skill_content>` rendering, with `text` appended
-   * when present) and starts a turn. The host enforces user-invocation policy
-   * here — on the discovery summary and again on the loaded definition, so a
-   * catalog change between the two lookups cannot slip a user-disabled body
-   * through — a model-only or unknown name is refused regardless of what a
-   * client menu offered. The carrier's request signal aborts the skill
-   * lookup and refuses injection once the caller has given up (`cancelled`).
-   * Session-backed subagents reject with `agent-busy`.
-   */
-  invoke(request: RpcRequest<{ sessionId: SessionId; name: string; text?: string }>, signal: AbortSignal):
-  Promise<RpcResponse<{ accepted: true }>>
 }
diff --git a/packages/host/apiproxy/src/fetch/client.ts b/packages/host/apiproxy/src/fetch/client.ts
index 574206458b..0f54d76dbc 100644
--- a/packages/host/apiproxy/src/fetch/client.ts
+++ b/packages/host/apiproxy/src/fetch/client.ts
@@ -39,7 +39,7 @@ import {
   workspaceRenameValueSchema,
 } from '../api/workspace.schema.ts'
 import { commandExecuteValueSchema, commandListValueSchema } from '../api/commands.schema.ts'
-import { skillInvokeValueSchema, skillListValueSchema } from '../api/skills.schema.ts'
+import { skillListValueSchema } from '../api/skills.schema.ts'
 import {
   goalCreateValueSchema,
   goalEditValueSchema,
@@ -118,7 +118,6 @@ export interface IApiClient {
   }
   skills: {
     list(payload: RequestPayload<'skill.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'skill.list'>>>
-    invoke(payload: RequestPayload<'skill.invoke'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'skill.invoke'>>>
   }
   events: {
     mux(payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>
@@ -186,7 +185,6 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'command.list': commandListValueSchema,
   'command.execute': commandExecuteValueSchema,
   'skill.list': skillListValueSchema,
-  'skill.invoke': skillInvokeValueSchema,
   'goal.create': goalCreateValueSchema,
   'goal.edit': goalEditValueSchema,
   'goal.pause': goalPauseValueSchema,
@@ -443,7 +441,6 @@ export abstract class AbstractApiClient implements IApiClient {
 
   readonly skills: IApiClient['skills'] = {
     list: (payload, signal) => this.callUnary('skill.list', payload, signal),
-    invoke: (payload, signal) => this.callUnary('skill.invoke', payload, signal),
   }
 
   readonly goals: IApiClient['goals'] = {
diff --git a/packages/host/apiproxy/src/fetch/handler.ts b/packages/host/apiproxy/src/fetch/handler.ts
index 8e098680fa..d41b51ad6d 100644
--- a/packages/host/apiproxy/src/fetch/handler.ts
+++ b/packages/host/apiproxy/src/fetch/handler.ts
@@ -41,7 +41,7 @@ import {
   workspaceRenameRequestSchema,
 } from '../api/workspace.schema.ts'
 import { commandExecuteRequestSchema, commandListRequestSchema } from '../api/commands.schema.ts'
-import { skillInvokeRequestSchema, skillListRequestSchema } from '../api/skills.schema.ts'
+import { skillListRequestSchema } from '../api/skills.schema.ts'
 import {
   goalCreateRequestSchema,
   goalEditRequestSchema,
@@ -109,7 +109,6 @@ const UNARY_ROUTES: UnaryRoutes = {
   'command.list': { schema: commandListRequestSchema, invoke: (api, r) => api.commands.list(r) },
   'command.execute': { schema: commandExecuteRequestSchema, invoke: (api, r, signal) => api.commands.execute(r, signal) },
   'skill.list': { schema: skillListRequestSchema, invoke: (api, r) => api.skills.list(r) },
-  'skill.invoke': { schema: skillInvokeRequestSchema, invoke: (api, r, signal) => api.skills.invoke(r, signal) },
   'goal.create': { schema: goalCreateRequestSchema, invoke: (api, r) => api.goals.create(r) },
   'goal.edit': { schema: goalEditRequestSchema, invoke: (api, r) => api.goals.edit(r) },
   'goal.pause': { schema: goalPauseRequestSchema, invoke: (api, r) => api.goals.pause(r) },
diff --git a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
index 5b61011370..09526c5a87 100644
--- a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
@@ -269,207 +269,6 @@ describe('skill.list', () => {
   })
 })
 
-describe('skill.invoke', () => {
-  /** Provider with one user-only and one model-only skill, both loadable. */
-  function registerInvokeSkills(ctx: Context): void {
-    const summaries = [
-      {
-        name: 'user-only', description: 'User-only',
-        invocation: { modelInvocable: false, userInvocable: true },
-        source: 'custom', provider: 'probe', rank: 0, locator: null,
-        resourceBase: { kind: 'directory', path: '/proj/.agents/skills/user-only' },
-      },
-      {
-        name: 'model-only', description: 'Model-only',
-        invocation: { modelInvocable: true, userInvocable: false },
-        source: 'custom', provider: 'probe', rank: 0, locator: null,
-      },
-    ] as const
-    ctx.skills.registerProvider(() => ({
-      name: 'probe',
-      list: () => Promise.resolve(summaries.map(summary => ({ ...summary }))),
-      get: candidate => Promise.resolve({
-        ...summaries.find(summary => summary.name === candidate.name)!,
-        content: 'Follow the probe instructions.',
-      }),
-    }))
-  }
-
-  /** Agent stub whose session carries a project cwd and whose followup records the injected message. */
-  function invokableAgent(ctx: Context): { agent: Agent; followup: ReturnType<typeof vi.fn> } {
-    const session = ctx.sessions.create(undefined, { meta: { cwd: '/proj' } })
-    const inbox = new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} })
-    const followup = vi.fn()
-    const agent = { id: session.id, session, inbox, status: 'idle', ctx, followup } as unknown as Agent
-    ctx.agents.register(agent)
-    return { agent, followup }
-  }
-
-  const live = () => new AbortController().signal
-
-  it('injects a user-invocable skill as a user message with the invocation source', async () => {
-    const ctx = await harness()
-    registerInvokeSkills(ctx)
-    const api = createApiProxy(ctx, DEFAULTS)
-    const { agent, followup } = invokableAgent(ctx)
-    const value = expectOk(await api.skills.invoke(request({
-      sessionId: agent.id, name: 'user-only', text: 'and check the fixture',
-    }), live()))
-    expect(value).toEqual({ accepted: true })
-    expect(followup).toHaveBeenCalledTimes(1)
-    const message = followup.mock.calls[0]?.[0] as UserMessage
-    expect(message.source).toEqual({ kind: 'skill-invocation', name: 'user-only', args: 'and check the fixture' })
-    expect(message.content).toHaveLength(1)
-    const text = (message.content[0] as { text: string }).text
-    expect(text).toContain('<skill_content name="user-only">')
-    expect(text).toContain('Base directory for this skill: /proj/.agents/skills/user-only')
-    expect(text).toContain('Follow the probe instructions.')
-    expect(text.endsWith('\n\nand check the fixture')).toBe(true)
-  })
-
-  it('omits args from the source and content when no text rides the invocation', async () => {
-    const ctx = await harness()
-    registerInvokeSkills(ctx)
-    const api = createApiProxy(ctx, DEFAULTS)
-    const { agent, followup } = invokableAgent(ctx)
-    expectOk(await api.skills.invoke(request({ sessionId: agent.id, name: 'user-only' }), live()))
-    const message = followup.mock.calls[0]?.[0] as UserMessage
-    expect(message.source).toEqual({ kind: 'skill-invocation', name: 'user-only' })
-    const text = (message.content[0] as { text: string }).text
-    expect(text.endsWith('</skill_content>')).toBe(true)
-  })
-
-  it('rejects a skill the user may not invoke', async () => {
-    const ctx = await harness()
-    registerInvokeSkills(ctx)
-    const api = createApiProxy(ctx, DEFAULTS)
-    const { agent, followup } = invokableAgent(ctx)
-    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'model-only' }), live()))
-    expect(error.code).toBe('skill-not-invocable')
-    expect(followup).not.toHaveBeenCalled()
-  })
-
-  it('rechecks user policy on the loaded definition (list/get race)', async () => {
-    const ctx = await harness()
-    // The provider flips the skill user-invocable in list but user-disabled
-    // in get — the window a provider change between the two collects opens.
-    ctx.skills.registerProvider(() => ({
-      name: 'flipping',
-      list: () => Promise.resolve([{
-        name: 'flipper', description: 'Race probe',
-        invocation: { modelInvocable: false, userInvocable: true },
-        source: 'custom', provider: 'flipping', rank: 0, locator: null,
-      }]),
-      get: () => Promise.resolve({
-        name: 'flipper', description: 'Race probe',
-        invocation: { modelInvocable: false, userInvocable: false },
-        source: 'custom', provider: 'flipping',
-        content: 'Must never inject.',
-      }),
-    }))
-    const api = createApiProxy(ctx, DEFAULTS)
-    const { agent, followup } = invokableAgent(ctx)
-    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'flipper' }), live()))
-    expect(error.code).toBe('skill-not-invocable')
-    expect(followup).not.toHaveBeenCalled()
-  })
-
-  it('reports skill-not-found when the summary wins but the load returns nothing', async () => {
-    const ctx = await harness()
-    ctx.skills.registerProvider(() => ({
-      name: 'vanishing',
-      list: () => Promise.resolve([{
-        name: 'ghost', description: 'Vanishes on load',
-        invocation: { modelInvocable: false, userInvocable: true },
-        source: 'custom', provider: 'vanishing', rank: 0, locator: null,
-      }]),
-      get: () => Promise.resolve(undefined),
-    }))
-    const api = createApiProxy(ctx, DEFAULTS)
-    const { agent, followup } = invokableAgent(ctx)
-    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'ghost' }), live()))
-    expect(error.code).toBe('skill-not-found')
-    expect(followup).not.toHaveBeenCalled()
-  })
-
-  it('rejects an unknown or invalid skill name', async () => {
-    const ctx = await harness()
-    registerInvokeSkills(ctx)
-    const api = createApiProxy(ctx, DEFAULTS)
-    const { agent } = invokableAgent(ctx)
-    const missing = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'absent-skill' }), live()))
-    expect(missing.code).toBe('skill-not-found')
-    const invalid = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'Not A Name' }), live()))
-    expect(invalid.code).toBe('skill-not-found')
-  })
-
-  it('folds a loader failure into a structured internal error', async () => {
-    const ctx = await harness()
-    ctx.skills.registerProvider(() => ({
-      name: 'exploding',
-      list: () => Promise.resolve([{
-        name: 'grenade', description: 'Loader throws',
-        invocation: { modelInvocable: false, userInvocable: true },
-        source: 'custom', provider: 'exploding', rank: 0, locator: null,
-      }]),
-      get: () => Promise.reject(new Error('disk exploded')),
-    }))
-    const api = createApiProxy(ctx, DEFAULTS)
-    const { agent, followup } = invokableAgent(ctx)
-    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'grenade' }), live()))
-    expect(error.code).toBe('internal')
-    expect(error.message).toContain('skill invocation failed')
-    expect(followup).not.toHaveBeenCalled()
-  })
-
-  it('refuses to start a turn the caller already abandoned', async () => {
-    const ctx = await harness()
-    registerInvokeSkills(ctx)
-    const api = createApiProxy(ctx, DEFAULTS)
-    const { agent, followup } = invokableAgent(ctx)
-    const abort = new AbortController()
-    abort.abort()
-    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'user-only' }), abort.signal))
-    expect(error.code).toBe('cancelled')
-    expect(followup).not.toHaveBeenCalled()
-  })
-
-  it('surfaces a followup refusal as agent-busy', async () => {
-    const ctx = await harness()
-    registerInvokeSkills(ctx)
-    const api = createApiProxy(ctx, DEFAULTS)
-    const { agent, followup } = invokableAgent(ctx)
-    followup.mockImplementation(() => { throw new Error('inbox closed') })
-    const error = expectErr(await api.skills.invoke(request({ sessionId: agent.id, name: 'user-only' }), live()))
-    expect(error.code).toBe('agent-busy')
-  })
-
-  it('refuses a cwd-less session with the skill.list stance', async () => {
-    const ctx = await harness()
-    registerInvokeSkills(ctx)
-    const api = createApiProxy(ctx, DEFAULTS)
-    const session = ctx.sessions.create(undefined)
-    const inbox = new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} })
-    const followup = vi.fn()
-    ctx.agents.register({ id: session.id, session, inbox, status: 'idle', ctx, followup } as unknown as Agent)
-    const error = expectErr(await api.skills.invoke(request({ sessionId: session.id, name: 'user-only' }), live()))
-    expect(error.code).toBe('internal')
-    expect(error.message).toContain('has no project cwd')
-    expect(followup).not.toHaveBeenCalled()
-  })
-
-  it('fails loud with internal when the skill registry is not mounted', async () => {
-    const ctx = await harness({ skills: false })
-    const api = createApiProxy(ctx, DEFAULTS)
-    const session = ctx.sessions.create(undefined, { meta: { cwd: '/proj' } })
-    const inbox = new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} })
-    ctx.agents.register({ id: session.id, session, inbox, status: 'idle', ctx, followup: vi.fn() } as unknown as Agent)
-    const error = expectErr(await api.skills.invoke(request({ sessionId: session.id, name: 'user-only' }), live()))
-    expect(error.code).toBe('internal')
-    expect(error.message).toContain('skill registry is absent')
-  })
-})
-
 describe('host/commands-changed frame', () => {
   it('broadcasts on registry change', async () => {
     const ctx = await harness()
diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts
index 0a65c817c6..ebd56ee551 100644
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -86,7 +86,7 @@ function scriptedApi(overrides: {
       execute: r => ok(r, { matched: false }),
       ...overrides.commands,
     },
-    skills: { list: r => ok(r, { skills: [] }), invoke: r => ok(r, { accepted: true as const }), ...overrides.skills },
+    skills: { list: r => ok(r, { skills: [] }), ...overrides.skills },
     goals: {
       create: err,
       edit: err,
diff --git a/packages/host/apiproxy/tests/fetch-carrier.spec.ts b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
index 09cabdcc7f..6481d75837 100644
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -198,9 +198,6 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
       async list(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits', modelInvocable: true }] } } }
       },
-      async invoke(request) {
-        return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
-      },
     },
     goals: {
       async create(request) {
@@ -385,8 +382,6 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     expect(miss.result).toEqual({ ok: true, value: { matched: false } })
     const skills = await c.skills.list({ sessionId: 's' as never })
     expect(skills.result).toEqual({ ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits', modelInvocable: true }] } })
-    const invoked = await c.skills.invoke({ sessionId: 's' as never, name: 'commit-helper', text: 'go' })
-    expect(invoked.result).toEqual({ ok: true, value: { accepted: true } })
   })
 
   it('lets command.execute finish after the 30-second default unary deadline', async () => {
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
index 972ccd3621..75b6dff3f7 100644
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -31,7 +31,7 @@ import {
   commandDescriptorSchema, commandExecuteRequestSchema, commandExecuteValueSchema,
   commandListRequestSchema, commandListValueSchema,
 } from '../src/api/commands.schema.ts'
-import { skillEntrySchema, skillInvokeRequestSchema, skillInvokeValueSchema, skillListRequestSchema, skillListValueSchema } from '../src/api/skills.schema.ts'
+import { skillEntrySchema, skillListRequestSchema, skillListValueSchema } from '../src/api/skills.schema.ts'
 import { hostFrameSchema, muxFrameSchema, askUserQuestionItemSchema } from '../src/api/events.schema.ts'
 import { approvalRequestIdSchema, approvalResponsePayloadSchema } from '../src/api/approvals.schema.ts'
 import { askUserQuestionAnswerSchema, questionResponsePayloadSchema } from '../src/api/questions.schema.ts'
@@ -74,8 +74,6 @@ describe('rpcErrorSchema', () => {
     expect(rpcErrorSchema.parse({ code: 'queue-item-not-found', message: 'm', details: { itemId: 'i' } }).code).toBe('queue-item-not-found')
     expect(rpcErrorSchema.parse({ code: 'command-error', message: 'm', details: {} }).code).toBe('command-error')
     expect(rpcErrorSchema.parse({ code: 'unknown-command', message: 'm', details: {} }).code).toBe('unknown-command')
-    expect(rpcErrorSchema.parse({ code: 'skill-not-found', message: 'm', details: { name: 'n' } }).code).toBe('skill-not-found')
-    expect(rpcErrorSchema.parse({ code: 'skill-not-invocable', message: 'm', details: { name: 'n' } }).code).toBe('skill-not-invocable')
     expect(rpcErrorSchema.parse({ code: 'title-invalid', message: 'm', details: { sessionId: 's' } }).code).toBe('title-invalid')
     expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
   })
@@ -83,7 +81,6 @@ describe('rpcErrorSchema', () => {
   it('rejects a known code with missing details', () => {
     expect(() => rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: {} })).toThrow()
     expect(() => rpcErrorSchema.parse({ code: 'title-invalid', message: 'm', details: {} })).toThrow()
-    expect(() => rpcErrorSchema.parse({ code: 'skill-not-invocable', message: 'm', details: {} })).toThrow()
     expect(() => rpcErrorSchema.parse({ code: 'command-error', message: 'm' })).toThrow()
     expect(() => rpcErrorSchema.parse({ code: 'nope', message: 'm', details: {} })).toThrow()
   })
@@ -408,19 +405,6 @@ describe('skills domain schemas', () => {
     // modelInvocable is required wire data: an entry without it fails.
     expect(() => skillEntrySchema.parse({ name: 'n', description: 'd' })).toThrow()
   })
-
-  it('validates the invoke request/value pair', () => {
-    expect(skillInvokeRequestSchema.parse({ sessionId: 's1', name: 'user-only' }))
-      .toEqual({ sessionId: 's1', name: 'user-only' })
-    expect(skillInvokeRequestSchema.parse({ sessionId: 's1', name: 'user-only', text: 'check it' }).text)
-      .toBe('check it')
-    expect(() => skillInvokeRequestSchema.parse({ sessionId: 's1', name: '' })).toThrow()
-    expect(() => skillInvokeRequestSchema.parse({ name: 'user-only' })).toThrow()
-    // A blank trailing text is refused at the wire boundary, not by client courtesy.
-    expect(() => skillInvokeRequestSchema.parse({ sessionId: 's1', name: 'user-only', text: '' })).toThrow()
-    expect(skillInvokeValueSchema.parse({ accepted: true })).toEqual({ accepted: true })
-    expect(() => skillInvokeValueSchema.parse({ accepted: false })).toThrow()
-  })
 })
 
 describe('goals domain schemas', () => {

From 2b6836a6fe2a29dcaa6ae5d78b715ba911e164f1 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 13:16:27 +0800
Subject: [PATCH 209/516] fix(vendor): widen include's writeTask for
 exactOptionalPropertyTypes

The debounced writer assigns undefined on flush, which a plain optional
NodeJS.Timeout rejects under exactOptionalPropertyTypes; the error had
been masked by stale build state until a residue cleanup invalidated it.
Logged as local modification 14 in the vendor manifest.
---
 vendor/README.md            | 1 +
 vendor/include/src/index.ts | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/vendor/README.md b/vendor/README.md
index 9fa97413c2..4bf1d43f46 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -43,6 +43,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/ui/app-boot/tests/config-reload.spec.ts`.
 13. **`include/src/index.ts` serialized child-tree mutation and `hmr/src/index.ts` main-watcher initial-scan suppression**: every Include child-tree mutation (initial apply, refresh, `internal/update` patch re-application) runs through one per-Include queue, because the group's transactional `update` is not reentrant — two concurrent applies interleave create and rollback on the same entries and strand the Include fiber without ever settling. The HMR main watcher passes `ignoreInitial: true`: the initial scan re-announced files boot had just consumed, and its `add` for a config file refreshed an Include mid-initial-apply; once serialized, a failing initial apply's rollback disposed HMR, whose teardown drain waited on the queued refresh sitting behind that same apply — a deadlock that exited 13 with no diagnostic. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a user patch layer present at registration must apply once. Covered by the patch-overlay boot-failure built-bin case in `apps/cli/tests/built-bin.e2e.ts`.
+14. **`include/src/index.ts` `writeTask` type**: widened the optional `writeTask?: NodeJS.Timeout` property to `NodeJS.Timeout | undefined` — the debounced writer assigns `undefined` on flush, which `exactOptionalPropertyTypes` rejects on a plain optional. Type-only; no behavior change.
 
 ## Sync procedure
 
diff --git a/vendor/include/src/index.ts b/vendor/include/src/index.ts
index 26b9305c52..5eece997c9 100644
--- a/vendor/include/src/index.ts
+++ b/vendor/include/src/index.ts
@@ -170,7 +170,7 @@ export class Include extends EntryTree {
   private readonly: boolean
   private content?: string
   private data?: EntryOptions[]
-  private writeTask?: NodeJS.Timeout
+  private writeTask?: NodeJS.Timeout | undefined
   private applyQueue: Promise<unknown> = Promise.resolve()
 
   constructor(ctx: Context, public config: Include.Config) {

From 7f138f3f5c2fb4a91871079a10b02c71d699dba9 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 13:52:47 +0800
Subject: [PATCH 210/516] test(examples): re-record catalog stitch sentence in
 agent-spine inline snapshot

---
 packages/examples/agent-spine-demo/tests/agent-core.spec.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
index 87fd17c36b..3224487b60 100644
--- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
@@ -527,6 +527,7 @@ describe('dsh-agent-spine-demo bundle', () => {
         </available_skills>
 
         If the user names a skill, or the task clearly matches a skill's description, call the \`skill\` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.
+        A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the \`skill\` tool again for that skill.
         </system-reminder>",
             "type": "user/message",
           },

From ed492077a5a1bcbda4d97706f9436e2356637f76 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 14:03:03 +0800
Subject: [PATCH 211/516] test(tool-skill): cover reject passthrough and
 non-text block scanning

---
 .../skill/tool-skill/tests/tool-skill.spec.ts | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts
index fe356da5da..5e0fe58855 100644
--- a/packages/skill/tool-skill/tests/tool-skill.spec.ts
+++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts
@@ -1017,4 +1017,32 @@ describe('user-explicit invocation injection', () => {
       (message.source as { kind?: string }).kind === 'skill-invocation')
     expect(injections).toHaveLength(1)
   })
+
+  it('passes a downstream reject through both pre-step listeners untouched', async () => {
+    const { ctx, agent } = await invokeHarness()
+    const signal = new AbortController().signal
+    const decision = await agentEvents(ctx, agent).waterfall(
+      'agent/pre-step',
+      { messages: [gesture('/hidden-demo blocked step')], turn: 1, step: 1, signal },
+      () => Promise.resolve({ kind: 'reject' as const }),
+    )
+    expect(decision).toEqual({ kind: 'reject' })
+  })
+
+  it('scans only text blocks of a user message', async () => {
+    const { ctx, agent } = await invokeHarness()
+    const mixed = createUserMessage({
+      content: [
+        { type: 'reasoning', text: '/hidden-demo inside a non-text block' },
+        { type: 'text', text: '/shared-skill go' },
+      ],
+      source: { kind: 'user' },
+    })
+    const decision = await proposeStep(ctx, agent, [mixed])
+    if (decision.kind !== 'enter') throw new Error('expected enter')
+    const invoked = decision.messages
+      .filter(message => (message.source as { kind?: string }).kind === 'skill-invocation')
+      .map(message => (message.source as { name: string }).name)
+    expect(invoked).toEqual(['shared-skill'])
+  })
 })

From 1db327ea6ca2c976d12117cd7d18a19ac12ddc88 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 14:11:17 +0800
Subject: [PATCH 212/516] feat(web): merge compact status and summary cards

---
 ...ranscript-log-ordered-projection.i18n.yaml |   4 +-
 ...0-web-transcript-log-ordered-projection.md |  14 +-
 ...eb-transcript-log-ordered-projection.zh.md |  14 +-
 apps/web/tests/seeded-history.e2e.ts          |  54 ++++---
 .../seeded-history/command-row.expected.md    |   4 +-
 .../snapshots/seeded-history/ui.expected.md   |   4 +-
 docs/cordis-catalog/events.md                 |   2 +-
 docs/cordis-catalog/services.md               |   2 +-
 docs/core-data-structures/commands.i18n.yaml  |   4 +-
 docs/core-data-structures/commands.md         |   9 +-
 docs/core-data-structures/commands.zh.md      |   9 +-
 docs/event-producer-consumer.md               |   2 +-
 docs/persistence-catalog.md                   |  14 +-
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |   2 +-
 packages/client/runtime/README.zh.md          |   2 +-
 .../src/client/sessions/conversation.ts       |  13 +-
 .../src/client/sessions/transcript-adapter.ts |  59 +++++++-
 .../tests/compact-checkpoint-pin.spec.ts      |   5 +-
 packages/client/runtime/tests/event-script.ts |  15 +-
 .../runtime/tests/transcript-adapter.spec.ts  |  34 +++--
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   3 +-
 packages/client/ui-conversation/README.zh.md  |   3 +-
 .../src/client/chat/ChatView.tsx              |  33 ++++-
 .../src/client/chat/CompactionCommandCard.tsx |  40 ++++++
 .../src/client/chat/CompactionItem.tsx        |  24 +++-
 .../src/client/chat/chat-flow.ts              |  65 ++++++++-
 .../src/client/contract/slots.ts              |  12 +-
 .../ui-conversation/src/client/locales.ts     |   4 +
 .../tests/chat-branch-tails.spec.tsx          |   9 +-
 .../ui-conversation/tests/chat-view.spec.tsx  | 132 +++++++++++++++++-
 .../ui-trajectory/tests/layout.spec.tsx       |   5 +-
 .../compact/command-compact/README.i18n.yaml  |   4 +-
 packages/compact/command-compact/README.md    |   2 +-
 packages/compact/command-compact/README.zh.md |   2 +-
 packages/compact/command-compact/src/index.ts |   1 +
 .../tests/command-compact.spec.ts             |  31 +++-
 .../tests/loader-composition.spec.ts          |  35 ++++-
 .../cordis/tool-cordis/src/api-catalog.ts     |   2 +-
 packages/ui/commands/README.i18n.yaml         |   4 +-
 packages/ui/commands/README.md                |   4 +-
 packages/ui/commands/README.zh.md             |   4 +-
 packages/ui/commands/src/index.ts             |  32 ++++-
 packages/ui/commands/src/invariant.ts         |  10 ++
 packages/ui/commands/tests/commands.spec.ts   |  22 +++
 packages/ui/commands/tests/invariant.spec.ts  |  89 ++++++++++++
 47 files changed, 725 insertions(+), 121 deletions(-)
 create mode 100644 packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
 create mode 100644 packages/ui/commands/tests/invariant.spec.ts

diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index 26108d6850..cede7ea5d9 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: 558d60cf6f6638c3e776396dd754d31b95819b28
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 2eb216fd1970700fb54a2aa17ec5ce515869e5b0
+2026-07-30-web-transcript-log-ordered-projection.md: 3b7aaeb1178ff79e38a1b9646a9dc78efaeae48b
+2026-07-30-web-transcript-log-ordered-projection.zh.md: acd198b6d3f3c5d57e233e09ee66f5d151e4f8f1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index 558d60cf6f..3b7aaeb117 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -18,9 +18,11 @@ Node order is seq-monotonic by construction, and three things follow. The log-on
 
 `foldDegraded` is gone from `ConversationSnapshot`, and with it the padding sentinels, the `baseSeq` arithmetic they needed, and `degradedSeqs()`. They existed only to satisfy the core fold's `seq === index` assertion and to survive its throw; the fold they describe is no longer run. Deleting the flag is part of the fix, not cleanup after it — `degradedSeqs()` was already almost the log-ordered projection, reached after a thrown error instead of intended.
 
-The marker's summary text comes from the checkpoint's own `compact/summary` provenance, never from the framed checkpoint payload, which is an instruction envelope written for the model. A window cut that left the provenance outside makes the row non-expandable rather than empty, the same soft-fall as a call-less tool result, and a later page supplying the provenance resolves the text.
+The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's own `compact/summary` provenance, never from the framed checkpoint payload, which is an instruction envelope written for the model. A window cut that left the provenance outside makes those fields unavailable, the same soft-fall as a call-less tool result, and a later page supplying the provenance resolves them.
 
-No persisted event, RPC envelope, compaction transaction, or model-visible surface changed, and no migration is required.
+The [manual compaction command](../feature/2026-07-30-queued-manual-compaction.md) returns the summary event's seq as the successful `CommandResult.sourceEventSeq`, and `command/done` persists that optional reference. Chat pairs only a successful named `/compact` command whose reference equals exactly one loaded `CompactionSummaryNode.summaryEventSeq`. The running command first renders `compact · Compacting context…`; after the checkpoint lands, the same React key renders one collapsed `compact` disclosure at the checkpoint's flow position with the count and token estimate. Input rejection, no compactable history, cancellation, and failure remain generic command rows with complete handler-authored text. Automatic compaction has no command reference and keeps the standalone context-compacted marker.
+
+The explicit event reference matters because manual compaction permits durable context injection while its asynchronous summary is running: command and checkpoint rows are not guaranteed to be adjacent. The command lifecycle event gains one optional field, but the compaction transaction, RPC envelope, and model-visible surface do not change; pre-release persisted logs without the field keep the former two-row soft-fall and require no migration.
 
 ## Recognizing a checkpoint: one declaration, pinned at compile time
 
@@ -57,6 +59,10 @@ The unmerged manual-compaction-queueing branch fixes the same interleaving bug b
 
 **Keep `foldDegraded` as a defensive flag.** Rejected: it described a specific failure of a fold that no longer runs. A flag no consumer can act on, reachable only through a `console.error`, is a false contract.
 
+**Pair the nearest `/compact` row with the next checkpoint.** Rejected: context injection may land between them, and concurrent or malformed lifecycle records must degrade without stealing another checkpoint. The command result instead names the authoritative summary event, and ambiguous references pair nothing.
+
+**Parse the English settlement text for item and token counts.** Rejected: handler copy is presentation text, not a stable data contract. The marker reads the structured `compact/summary` payload already owning both values.
+
 ## Consequences
 
 Compaction no longer erases web history; a session compacted several times shows one marker per landed compaction, in log order, and the same window renders identically live and after a cold resume. The pagination hole is closed by construction rather than defended against, and `ConversationSnapshot` loses a published field, which touched thirteen files.
@@ -65,8 +71,8 @@ Compaction no longer erases web history; a session compacted several times shows
 
 The performance contract is unchanged and now simpler to state: one append materializes one node, an event that changes no node keeps the previous array reference — so a chunk storm costs nothing and `nodes()` is not even recomputed — and unchanged nodes keep their object identity. The window still grows with session length rather than with the surface, which is the trade the fix exists to make; a compaction used to bound the projection for exactly the long sessions compaction serves.
 
-The web e2e scenario now seeds a real compaction transaction over its recorded turn, so the aria golden pins both halves of the fix through the real host and a real browser: the recorded prompt and full tool output are still on screen, and one marker sits after them. The seed recording itself is untouched and stays model-authentic — replay derives the compacted turn from the recording's own surface.
+The web e2e scenario now seeds a real manual command lifecycle around a compaction transaction over its recorded turn, so the aria golden pins the complete behavior through the real host and a real browser: the recorded prompt and full tool output are still on screen, exactly one `compact` row reports scale after them, and its disclosure opens the exact summary. The seed recording itself is untouched and stays model-authentic — replay derives the manual compaction from the recording's own surface.
 
 ## Deferred
 
-The terminal's [archived compaction progress decision](../../archived/feature/2026-07-30-compaction-progress-visibility.md) uses the live standalone bracket to drive a one-cell indicator and does not change this browser projection. The marker still carries no **scale**: the checkpoint's `sourceEventSeqs` hold the shadowed count, so a separately justified count or range can be added without coupling it to progress.
+The terminal's [archived compaction progress decision](../../archived/feature/2026-07-30-compaction-progress-visibility.md) uses the live standalone bracket to drive a one-cell indicator and does not change this browser projection.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 2eb216fd19..acd198b6d3 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -18,9 +18,11 @@ surface 顺序还让另外两个问题成为结构性的。一次替换之后它
 
 `foldDegraded` 从 `ConversationSnapshot` 消失，随之消失的是哨兵填充、它们所需的 `baseSeq` 算术，以及 `degradedSeqs()`。它们的存在只为满足核心 fold 的 `seq === index` 断言并在其抛错时存活；它们所描述的 fold 已不再运行。删除该标志是修复的一部分，而非修复之后的清理——`degradedSeqs()` 本身已几乎就是按日志顺序的投影，只是作为抛错后的落点而非本意到达。
 
-标记的摘要文本来自检查点自己的 `compact/summary` 溯源，绝不取自成框的检查点载荷——那是为模型撰写的指令信封。窗口切分把溯源留在窗口外时该行不可展开而非空白，与无调用的工具结果同一种软退让；后续补上溯源的分页会解析出文本。
+标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点自己的 `compact/summary` 溯源，绝不取自成框的检查点载荷——那是为模型撰写的指令信封。窗口切分把溯源留在窗口外时这些字段不可用，与无调用的工具结果同一种软退让；后续补上溯源的分页会解析出它们。
 
-没有任何持久化事件、RPC 信封、压缩事务或模型可见 surface 发生变化，也不需要迁移。
+[手动压缩命令](../feature/2026-07-30-queued-manual-compaction.md)会把摘要事件的 seq 作为成功结果的 `CommandResult.sourceEventSeq` 返回，`command/done` 则持久化这项可选引用。Chat 只会配对成功且名称为 `/compact`、其引用恰好等于唯一一个已加载 `CompactionSummaryNode.summaryEventSeq` 的命令。运行中的命令先渲染为 `compact · Compacting context…`；检查点落地后，同一个 React key 会在检查点的消息流位置渲染一条收起的 `compact` 展开项，并显示条目数量和 token 估算值。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行，并保留处理器撰写的完整文本。自动压缩没有命令引用，继续使用独立的上下文已压缩标记。
+
+显式事件引用之所以重要，是因为手动压缩允许在异步摘要运行期间注入持久上下文：命令行与检查点行不保证相邻。命令生命周期事件增加一个可选字段，但压缩事务、RPC 信封和模型可见 surface 均不变化；不含该字段的预发布持久日志继续采用原先的两行软退让，无须迁移。
 
 ## 识别检查点：同一份声明，在编译期钉住
 
@@ -57,6 +59,10 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 **把 `foldDegraded` 留作一个防御性标志。** 已拒绝：它描述的是一个已不再运行的 fold 的特定失败。一个消费方无法据以行动、只能通过 `console.error` 到达的标志，是一份虚假契约。
 
+**把最近的 `/compact` 行与下一个检查点配对。** 已拒绝：两者之间可能落入上下文注入，并发或格式异常的生命周期记录也必须降级而不误取其他检查点。命令结果则指明权威摘要事件；引用存在歧义时不配对任何内容。
+
+**解析英文结算文本中的条目数量和 token 数量。** 已拒绝：处理器文案是呈现文本，而非稳定的数据契约。标记读取本已持有这两个值的结构化 `compact/summary` 载荷。
+
 ## Consequences
 
 压缩不再抹掉 Web 历史；一个被压缩多次的会话按日志顺序显示每次落地压缩一个标记，而同一窗口在实时与冷恢复之后渲染完全相同。分页缺口是被构造性闭合而非被防御，`ConversationSnapshot` 少了一个已发布字段，这触及十三个文件。
@@ -65,8 +71,8 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 性能契约未变，且现在更易表述：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用——因此分片风暴零成本、`nodes()` 甚至不会重算——未变化的节点保持其对象标识。窗口仍随会话长度而非随 surface 增长，这正是本修复存在所要做的交换；一次压缩过去恰好为压缩所服务的长会话限制了投影规模。
 
-Web e2e 场景现在在它录制的那一轮之上播种一次真实的压缩事务，因此 aria 基准经真实宿主与真实浏览器钉住修复的两半：录制的提问与完整工具输出仍在屏幕上，其后坐着一个标记。录制本身未被触碰、保持模型真实——回放从录制自身的 surface 派生出被压缩的那一轮。
+Web e2e 场景现在围绕它录制的那一轮上的压缩事务播种一次真实的手动命令生命周期，因此 aria 基准经真实宿主与真实浏览器钉住完整行为：录制的提问与完整工具输出仍在屏幕上，其后恰好一条 `compact` 行报告规模，展开后会显示确切摘要。录制本身未被触碰、保持模型真实——回放从录制自身的 surface 派生出手动压缩。
 
 ## Deferred
 
-终端的[已归档压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用实时独立标记对驱动单格指示器，并不改变此浏览器投影。标记仍不携带**规模**信息：检查点的 `sourceEventSeqs` 保存被遮蔽的数量，因此可以另行论证后添加计数或区间，而无须将其与进度耦合。
+终端的[已归档压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用实时独立标记对驱动单格指示器，并不改变此浏览器投影。
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index 799503ef1c..fac240fbe1 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -4,8 +4,9 @@
 // history RPC, history-page tool views, and the client's log-ordered transcript
 // events — with ZERO model calls in replay (no replay fixture; a stray stream
 // fails loud on the open llm seam). The cold session also carries the one
-// keyless command-row surface: an Access-chip pick runs `/permission` on the
-// host, so the settled row's copy has a golden here. The seed is a recorded
+// keyless command-row surfaces: the seeded manual `/compact` lifecycle folds
+// into its checkpoint, while an Access-chip pick later runs `/permission` on
+// the host. The seed is a recorded
 // fixture under the
 // same record discipline as every other: DSH_SNAPSHOT=record drives the turn
 // live through the composer (real read tool against seeded workspace files)
@@ -39,18 +40,18 @@ const SEED_ID = 'seeded-history-web-e2e'
 const PROMPT = 'Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop.'
 
 /**
- * Append a complete, valid compaction transaction over the recorded turn's own
- * surface. The recording stays model-authentic and reusable; replay adds this
- * deterministic condition before seeding it cold, so the scenario pins the bug
- * this change fixes — a landed compaction must not erase history the reader
- * already saw — through the real host and the real browser.
+ * Append a complete manual `/compact` lifecycle and valid compaction transaction
+ * over the recorded turn's own surface. The recording stays model-authentic and
+ * reusable; replay adds this deterministic condition before seeding it cold, so
+ * the scenario pins both the log-preserving marker and its single-card command
+ * presentation through the real host and browser.
  * @param raw - the seed fixture text, already realized (placeholder-free) so
  * the shadow price below is computed from the exact strings the host folds.
  * @param meter - the composed token meter; the appended `compact/summary`'s
  * shadow price must be the exact heuristic price of the shadowed nodes, the
  * way compact-basic derives it, because the token-meter projections subtract
  * it verbatim.
- * @returns the fixture with a compacted turn appended.
+ * @returns the fixture with a manual compaction lifecycle appended.
  */
 function withCompaction(raw: string, meter: TokenMeterService): string {
   const lines = raw.trimEnd().split('\n')
@@ -73,14 +74,10 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
   if (first === undefined || last === undefined || tail === undefined) {
     throw new Error('seeded-history compaction requires a non-empty closed surface')
   }
-  // The transaction opens the turn after the recording's last closed one; read
-  // it from the fixture so a re-recording with a different turn count stays
-  // valid instead of appending a duplicate turn number.
   const lastTurn = events.filter(event => event.type === 'turn/end').at(-1)?.data?.turn
   if (typeof lastTurn !== 'number') {
     throw new Error('seeded-history compaction requires a recording ending on a closed turn')
   }
-  const turn = lastTurn + 1
   let seq = tail.seq + 1
   let time = tail.time + 1
   /**
@@ -93,8 +90,12 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
     lines.push(JSON.stringify({ ...event, seq: taken, time: time++ }))
     return taken
   }
-  at({ type: 'turn/start', data: { turn } })
-  const startSeq = at({ type: 'compact/start', data: { turn } })
+  const commandId = 'cmd-seeded-manual-compact'
+  at({
+    type: 'command/run',
+    data: { commandId, name: 'compact', args: '', source: { kind: 'user' } },
+  })
+  const startSeq = at({ type: 'compact/start', data: { turn: null } })
   // Load-bearing exactness: the projections subtract this count verbatim, so
   // it must equal what the host's fold prices for these nodes. The estimator
   // prices message CONTENT only, so a minimal wrapper per storage shape is
@@ -146,8 +147,21 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
     surfaceOp: { op: 'replace', start: first, end: last },
     sourceEventSeqs: [startSeq, summarySeq, ...surfaceSeqs],
   })
-  at({ type: 'compact/end', data: { turn } })
-  at({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
+  at({ type: 'compact/end', data: { turn: null } })
+  at({
+    type: 'command/done',
+    data: {
+      commandId,
+      kind: 'success',
+      text: `Compacted ${surfaceSeqs.length} history items (~${shadowedTokenCount} tokens).`,
+      sourceEventSeq: summarySeq,
+    },
+  })
+  // The persistence seed helper requires a terminal turn/end. Keep the manual
+  // command standalone, then add a closed zero-step fixture boundary after it.
+  const closureTurn = lastTurn + 1
+  at({ type: 'turn/start', data: { turn: closureTurn } })
+  at({ type: 'turn/end', data: { turn: closureTurn, reason: { kind: 'completed' } } })
   return `${lines.join('\n')}\n`
 }
 
@@ -239,7 +253,11 @@ describe('web e2e: seeded history renders through cold resume', () => {
     await sessionRow.click()
     // Settled barrier for history: the recorded final assistant text renders.
     await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBe(1)
-    await expect.poll(() => page.getByText('Context compacted', { exact: true }).count(), { timeout: 10_000 }).toBe(1)
+    await expect.poll(() => page.getByText('compact', { exact: true }).count(), { timeout: 10_000 }).toBe(1)
+    await expect.poll(() => page.getByText(/^Compacted \d+ history items \(~\d+ tokens\)$/).count(), {
+      timeout: 10_000,
+    }).toBe(1)
+    expect(await page.getByText('Context compacted', { exact: true }).count()).toBe(0)
     // Tool cards render from logged tool/call + tool/result alone (views are
     // host-recomputed per page; the generic card is the documented default).
     const toolRows = page.locator('[data-variant], [data-sample]')
@@ -363,7 +381,7 @@ describe('web e2e: seeded history renders through cold resume', () => {
 
   it.skipIf(MODE === 'record')('expands the cold-resumed compact summary', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-seeded-compaction'))
-    const marker = page.getByRole('button', { name: /Context compacted/ })
+    const marker = page.getByRole('button', { name: /compact Compacted \d+ history items/ })
     await marker.waitFor({ timeout: 10_000 })
     expect(await marker.getAttribute('aria-expanded')).toBe('false')
     await marker.click()
diff --git a/apps/web/tests/snapshots/seeded-history/command-row.expected.md b/apps/web/tests/snapshots/seeded-history/command-row.expected.md
index fe58587913..21b9cefeec 100644
--- a/apps/web/tests/snapshots/seeded-history/command-row.expected.md
+++ b/apps/web/tests/snapshots/seeded-history/command-row.expected.md
@@ -31,9 +31,9 @@
 - button "Branch into a new conversation":
   - img
 - text: 7/25 {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
-- button "Context compacted View compaction summary":
+- button "compact Compacted 5 history items (~247 tokens)":
   - img
-  - text: Context compacted View compaction summary
+  - text: compact Compacted 5 history items (~247 tokens)
 - button "Context injection AGENTS.md":
   - img
   - img
diff --git a/apps/web/tests/snapshots/seeded-history/ui.expected.md b/apps/web/tests/snapshots/seeded-history/ui.expected.md
index ce2921eac2..2502d90f90 100644
--- a/apps/web/tests/snapshots/seeded-history/ui.expected.md
+++ b/apps/web/tests/snapshots/seeded-history/ui.expected.md
@@ -31,9 +31,9 @@
 - button "Branch into a new conversation":
   - img
 - text: 7/25 {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
-- button "Context compacted View compaction summary":
+- button "compact Compacted 5 history items (~247 tokens)":
   - img
-  - text: Context compacted View compaction summary
+  - text: compact Compacted 5 history items (~247 tokens)
 - button "Context injection AGENTS.md":
   - img
   - img
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 4ad9797262..7fd91874d3 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -343,7 +343,7 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/ui/commands/src/index.ts:161`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/ui/commands/src/index.ts:172`](../../packages/ui/commands/src/index.ts)
 
 ## `credentials/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 4a73dc06ad..6e75b2a345 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -451,7 +451,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](../core-data-structures/core.md) · [CommandDefinition](../core-data-structures/commands.md) · [CommandDescriptor](../core-data-structures/commands.md)
 
-Source: [`packages/ui/commands/src/index.ts:286`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/ui/commands/src/index.ts:305`](../../packages/ui/commands/src/index.ts)
 
 ## `ctx.compact` — `CompactService` (abstract seam)
 
diff --git a/docs/core-data-structures/commands.i18n.yaml b/docs/core-data-structures/commands.i18n.yaml
index f454a69873..532151ef70 100644
--- a/docs/core-data-structures/commands.i18n.yaml
+++ b/docs/core-data-structures/commands.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 docs/core-data-structures/commands.md
-commands.md: bc7cf676232a4271d7bc21d6688bc598d9325957
-commands.zh.md: a2f82c06ac7ca87c5d5cfa525aaf9afa8777e9c9
+commands.md: 1390f736ff582a997ee710cfd27fce4e7db3461f
+commands.zh.md: 53aec9bd138773df7fceb45e5d6c30b7205dd0d9
diff --git a/docs/core-data-structures/commands.md b/docs/core-data-structures/commands.md
index bc7cf67623..1390f736ff 100644
--- a/docs/core-data-structures/commands.md
+++ b/docs/core-data-structures/commands.md
@@ -61,10 +61,17 @@ interface CommandInvocation {
 ```ts type-equiv
 /** Expected command outcome rendered directly by the dispatching UI. */
 type CommandResult =
-  | { readonly kind: 'success'; readonly text?: string }
+  | {
+    readonly kind: 'success'
+    readonly text?: string
+    /** Earlier authoritative domain event that owns a richer presentation. */
+    readonly sourceEventSeq?: number
+  }
   | { readonly kind: 'error'; readonly text: string }
 ```
 
+`sourceEventSeq` is optional and success-only. When present, it names an earlier non-command event in the receiving session log; `command/done` persists the same reference so a client can combine the command lifecycle with that domain projection without parsing `text` or relying on adjacent rows.
+
 ## Discovery and parsing views
 
 Adapters receive handler-free immutable descriptors after scope resolution. `parseCommand()` returns `ParsedCommand` before registry resolution; syntax-valid input can still name an unavailable command.
diff --git a/docs/core-data-structures/commands.zh.md b/docs/core-data-structures/commands.zh.md
index a2f82c06ac..53aec9bd13 100644
--- a/docs/core-data-structures/commands.zh.md
+++ b/docs/core-data-structures/commands.zh.md
@@ -61,10 +61,17 @@ interface CommandInvocation {
 ```ts type-equiv
 /** Expected command outcome rendered directly by the dispatching UI. */
 type CommandResult =
-  | { readonly kind: 'success'; readonly text?: string }
+  | {
+    readonly kind: 'success'
+    readonly text?: string
+    /** Earlier authoritative domain event that owns a richer presentation. */
+    readonly sourceEventSeq?: number
+  }
   | { readonly kind: 'error'; readonly text: string }
 ```
 
+`sourceEventSeq` 是可选字段，且只用于成功结果。存在时，它指向接收会话日志中更早的一条非命令事件；`command/done` 会持久化同一引用，让客户端能够将命令生命周期与该领域投影合并，而无须解析 `text` 或依赖相邻行。
+
 ## 发现与解析视图
 
 作用域解析后，适配器会获得不含处理器的不可变描述符。`parseCommand()` 在注册表解析前返回 `ParsedCommand`；语法有效的输入仍可能指向不可用的命令。
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 9d486c46f6..84451e275a 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -21,7 +21,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/status` | `emit` | [`packages/core/agent/src/types.ts:173`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), [`jsonrpc`](../packages/ui/jsonrpc) |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:273`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:30`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:161`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy` |
+| `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:172`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:62`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 48732dbbb0..e7ea90f4a4 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -200,12 +200,18 @@ Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/
 /**
  * The paired command settled. `kind`/`text` carry the handler's verbatim
  * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
- * rendered failure); presentation stays client-computed at render time.
+ * rendered failure). A successful command may identify the earlier
+ * authoritative domain event for a richer client-computed presentation.
  */
-'command/done': { commandId: CommandId; kind: 'success' | 'error'; text?: string }
+'command/done': {
+  commandId: CommandId
+  kind: 'success' | 'error'
+  text?: string
+  sourceEventSeq?: number
+}
 ```
 
-Source: [`packages/ui/commands/src/index.ts:145`](../packages/ui/commands/src/index.ts)
+Source: [`packages/ui/commands/src/index.ts:151`](../packages/ui/commands/src/index.ts)
 
 #### `command/run` — log-only
 
@@ -223,7 +229,7 @@ Source: [`packages/ui/commands/src/index.ts:145`](../packages/ui/commands/src/in
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-Source: [`packages/ui/commands/src/index.ts:139`](../packages/ui/commands/src/index.ts)
+Source: [`packages/ui/commands/src/index.ts:144`](../packages/ui/commands/src/index.ts)
 
 ### `compact/*`
 
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 23c867e4c0..f4b0f31a48 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: 8ac29a4258bbd7456b20c61e547d48c570e84d27
-README.zh.md: 0e065e43ecc571e68d3976d2100eb43959cb2e3d
+README.md: 7b7b983c0047a54457089fc084f2532bb990b4d2
+README.zh.md: 9c3c6ec04c8ba20ac6357b3701d7a39eafaf9fd2
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index 8ac29a4258..7b7b983c00 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -36,7 +36,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 `ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
 
-Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text comes from the checkpoint's `compact/summary` provenance; a window cut that left the provenance outside makes the row non-expandable rather than empty, and a later page that supplies it resolves the text. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
+Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's `compact/summary` provenance; a window cut that left the provenance outside makes those fields unavailable, and a later page that supplies it resolves them. `CommandNode.outcome.sourceEventSeq` preserves a successful command's explicit reference to that summary event, allowing the presentation layer to pair `/compact` with its checkpoint without parsing settlement copy or assuming the two rows are adjacent. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
 
 ## Request inspection
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 0e065e43ec..9c3c6ec04c 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -36,7 +36,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 `ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并以相同身份落成 `user/message` 时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
 
-由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时该行不可展开而非空白，后续补上溯源的分页会解析出文本。性能契约：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
+由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时这些字段不可用，后续补上溯源的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能契约：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
 
 ## 请求检查
 
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index fb2c281331..a881158525 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -192,6 +192,12 @@ export interface CompactionSummaryNode {
   /** Summary text from the checkpoint's `compact/summary` provenance; null when
    *  the window cut left that provenance outside (the marker is then not expandable). */
   summary: string | null
+  /** Seq of the loaded `compact/summary` event, or null when that provenance is outside the window. */
+  summaryEventSeq: number | null
+  /** Number of surface items replaced, or null when summary provenance is unavailable or malformed. */
+  shadowedItemCount: number | null
+  /** Estimated token price of the replaced items, or null when summary provenance is unavailable or malformed. */
+  shadowedTokenCount: number | null
 }
 
 /**
@@ -236,7 +242,12 @@ export interface CommandNode {
    */
   args: string | null
   /** Settlement outcome (done payload); null while the command is still executing. */
-  outcome: { kind: 'success' | 'error'; text?: string } | null
+  outcome: {
+    kind: 'success' | 'error'
+    text?: string
+    /** Earlier authoritative domain event for a richer client-computed presentation. */
+    sourceEventSeq?: number
+  } | null
 }
 
 /** Finalized conversation node union (kind discriminates; seq is the React key). */
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index d970be596b..b596c681a9 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -156,6 +156,29 @@ function compactSummaryText(event: SessionEvent): string | null {
   return text.trim() === '' ? null : text
 }
 
+interface CompactSummaryDetails {
+  readonly summary: string | null
+  readonly shadowedItemCount: number | null
+  readonly shadowedTokenCount: number | null
+}
+
+/** Recover human-facing summary material from one structurally narrowed wire event. */
+function compactSummaryDetails(event: SessionEvent): CompactSummaryDetails {
+  const data = event.data as unknown as { shadowedSeqs?: unknown; shadowedTokenCount?: unknown }
+  const shadowedSeqs = data.shadowedSeqs
+  const tokenCount = data.shadowedTokenCount
+  return {
+    summary: compactSummaryText(event),
+    shadowedItemCount: Array.isArray(shadowedSeqs)
+      && shadowedSeqs.every((seq: unknown) => Number.isSafeInteger(seq) && (seq as number) >= 0)
+      ? shadowedSeqs.length
+      : null,
+    shadowedTokenCount: Number.isSafeInteger(tokenCount) && (tokenCount as number) >= 0
+      ? tokenCount as number
+      : null,
+  }
+}
+
 /**
  * One landed checkpoint -> the human-facing compaction marker. The summary text
  * comes from the checkpoint's own provenance (`sourceEventSeqs` names the
@@ -170,13 +193,28 @@ function materializeCompaction(
 ): CompactionSummaryNode {
   const sources = (checkpoint as SessionEvent & { sourceEventSeqs?: number[] }).sourceEventSeqs
   let summary: string | null = null
+  let summaryEventSeq: number | null = null
+  let shadowedItemCount: number | null = null
+  let shadowedTokenCount: number | null = null
   for (const seq of sources ?? []) {
     const candidate = eventIndex.get(seq)
     if (candidate === undefined || (candidate.type as string) !== 'compact/summary') continue
-    summary = compactSummaryText(candidate)
+    const details = compactSummaryDetails(candidate)
+    summary = details.summary
+    summaryEventSeq = candidate.seq
+    shadowedItemCount = details.shadowedItemCount
+    shadowedTokenCount = details.shadowedTokenCount
     break
   }
-  return { kind: 'compaction', seq: checkpoint.seq, time: checkpoint.time, summary }
+  return {
+    kind: 'compaction',
+    seq: checkpoint.seq,
+    time: checkpoint.time,
+    summary,
+    summaryEventSeq,
+    shadowedItemCount,
+    shadowedTokenCount,
+  }
 }
 
 /** Log-ordered human transcript over a paged raw event window (never consults surface order). */
@@ -321,9 +359,22 @@ export class TranscriptAdapter {
       return true
     }
     if ((event.type as string) !== 'command/done') return false
-    const data = event.data as unknown as { commandId: CommandId; kind: 'success' | 'error'; text?: string }
+    const data = event.data as unknown as {
+      commandId: CommandId
+      kind: 'success' | 'error'
+      text?: string
+      sourceEventSeq?: number
+    }
     const run = this.commandIdx.get(data.commandId)
-    const outcome = { kind: data.kind, ...data.text === undefined ? {} : { text: data.text } }
+    const sourceEventSeq = data.kind === 'success'
+      && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
+      ? data.sourceEventSeq as number
+      : undefined
+    const outcome = {
+      kind: data.kind,
+      ...data.text === undefined ? {} : { text: data.text },
+      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
+    }
     if (run === undefined) {
       // Cross-window cut: the run page fell out of the window — build the
       // node from the done alone (same soft-fall as a call-less tool result).
diff --git a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
index ddc6c8adc5..aed658af51 100644
--- a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
+++ b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
@@ -36,7 +36,10 @@ describe('compaction checkpoint recognition', () => {
   it('recognizes a checkpoint carrying the seam-canonical source', () => {
     const adapter = new TranscriptAdapter()
     adapter.reset([canonicalCheckpoint(1)])
-    expect(adapter.nodes()).toEqual([{ kind: 'compaction', seq: 1, time: 1_700_000_000_001, summary: null }])
+    expect(adapter.nodes()).toEqual([{
+      kind: 'compaction', seq: 1, time: 1_700_000_000_001, summary: null,
+      summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
+    }])
   })
 
   it("agrees with the seam's own predicate on the source it recognizes", () => {
diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts
index 51e982e8f4..bc3c10e762 100644
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -92,8 +92,19 @@ export const ev = {
     at(seq, { type: 'command/run', data: { commandId, name, args, source: { kind: 'user' } } }),
   commandRunWithoutInput: (seq: number, commandId: string, name: string): SessionEvent =>
     at(seq, { type: 'command/run', data: { commandId, name, source: { kind: 'user' } } }),
-  commandDone: (seq: number, commandId: string, kind: 'success' | 'error' = 'success', text?: string): SessionEvent =>
-    at(seq, { type: 'command/done', data: { commandId, kind, ...text === undefined ? {} : { text } } }),
+  commandDone: (
+    seq: number,
+    commandId: string,
+    kind: 'success' | 'error' = 'success',
+    text?: string,
+    sourceEventSeq?: number,
+  ): SessionEvent =>
+    at(seq, { type: 'command/done', data: {
+      commandId,
+      kind,
+      ...text === undefined ? {} : { text },
+      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
+    } }),
   /** A compaction's log-only `compact/summary` provenance record. */
   compactSummary: (seq: number, summary: string, start: number, end: number): SessionEvent =>
     at(seq, { type: 'compact/summary', data: {
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
index e4ef3b0e1a..626c7792f7 100644
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ b/packages/client/runtime/tests/transcript-adapter.spec.ts
@@ -223,8 +223,14 @@ describe('TranscriptAdapter', () => {
         checkpoint(5, 4, { start: 2, end: 3, sourceEventSeqs: [4, 2, 3] }),
       ])
       expect(adapter.nodes().filter(n => n.kind === 'compaction')).toEqual([
-        { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: 'first' },
-        { kind: 'compaction', seq: 5, time: 1_700_000_000_005, summary: 'second' },
+        {
+          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: 'first',
+          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
+        },
+        {
+          kind: 'compaction', seq: 5, time: 1_700_000_000_005, summary: 'second',
+          summaryEventSeq: 4, shadowedItemCount: 2, shadowedTokenCount: 100,
+        },
       ])
     })
 
@@ -296,7 +302,7 @@ describe('TranscriptAdapter', () => {
         ...(summary === undefined ? [] : [summary]),
         checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
       ])
-      expect(adapter.nodes()).toEqual([
+      expect(adapter.nodes()).toMatchObject([
         { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null },
       ])
     })
@@ -310,7 +316,10 @@ describe('TranscriptAdapter', () => {
         checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
       ])
       expect(adapter.nodes()).toEqual([
-        { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: '可用摘要' },
+        {
+          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: '可用摘要',
+          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
+        },
       ])
     })
 
@@ -324,7 +333,10 @@ describe('TranscriptAdapter', () => {
           source: { kind: 'plugin', plugin: 'compact' },
         }),
       })])
-      expect(adapter.nodes()).toEqual([{ kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null }])
+      expect(adapter.nodes()).toEqual([{
+        kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null,
+        summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
+      }])
     })
 
     it('skips a non-summary provenance seq before reaching the real one', () => {
@@ -468,20 +480,22 @@ describe('TranscriptAdapter', () => {
       expect(adapter.nodes().map(n => n.kind)).toEqual(['user', 'command'])
     })
 
-    it('renders the /compact row alongside the marker its own command produced', () => {
-      // The row that reports the compaction is a command node; dropping command
-      // folding would delete it together with every other slash-command row.
+    it('preserves the domain-event link for the UI to fold a /compact row into its marker', () => {
       const adapter = new TranscriptAdapter()
       adapter.reset([
         ev.user(0, '压缩前的问题'),
         ev.commandRun(1, 'cmd-compact', 'compact'),
         compactSummary(2, [{ type: 'text', text: '手动压缩摘要' }]),
         checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [2, 0] }),
-        ev.commandDone(4, 'cmd-compact', 'success', '已压缩'),
+        ev.commandDone(4, 'cmd-compact', 'success', '已压缩', 2),
       ])
       const nodes = adapter.nodes()
       expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['compaction', 3]])
-      expect(nodes[1]).toMatchObject({ name: 'compact', outcome: { kind: 'success', text: '已压缩' } })
+      expect(nodes[1]).toMatchObject({
+        name: 'compact',
+        outcome: { kind: 'success', text: '已压缩', sourceEventSeq: 2 },
+      })
+      expect(nodes[2]).toMatchObject({ kind: 'compaction', summaryEventSeq: 2 })
     })
   })
 
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index b6bf25d410..ca3289ba55 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 0cf50146cc44ef0d6cc060a4c97b3d1ff454f013
-README.zh.md: 8bfb96bb9326d8fcadc3c357b6abaad88c92bd17
+README.md: 5b37065097ef60c2edf14725f4e1e1c6a52c4366
+README.zh.md: 4ec26155a124497db0fc7f351d20ecb451a18763
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 0cf50146cc..5b37065097 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, an animated left-to-right gradient `Deep diving...` turn status, per-tool row slot with a bash sample registrant and the todo row), composer dock (session stats sticky with the input), input dock (hairline-separated queue rows plus the todo plan strip), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares).
 
-Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. The disclosure renders the checkpoint's `compact/summary` provenance; when that event is outside the loaded window, the row remains visible but non-expandable. The framed checkpoint payload is model-facing and never renders.
+Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key, showing the replaced-item and estimated-token counts and disclosing the summary on click. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when summary provenance is outside the loaded window, the checkpoint remains visible but non-expandable.
 
 The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
 
@@ -64,7 +64,6 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **Compaction markers show no scale** — the row does not yet report how many messages or which range the checkpoint replaced.
 - **Stats-line durations and speeds cover the in-window flow only** — LLM and tool wall times plus the TTFT and throughput averages fold the snapshot's assistant `timing` and tool call/result pairs, so nodes outside the loaded event window (older history) are not counted.
 - **The details panel has no entry point** — `ChatViewInjected.openDetails` is implemented but uncalled, so the raw selected-call display is unreachable in the assembled application. There is no Input/Output/Metadata switch, Prev/Next stepping, or trajectory deep link.
 - **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / clock / branch) ships under the last content-text assistant of each turn that has ended; mid-turn narration, Think-only nodes, and every node of a turn still producing steps stay chrome-free. Branch stays disabled unless that message is also the last transcript node of a completed turn; when enabled, it forks through that turn, increments the inherited title on the client, and opens the child. A fork or rename failure leaves the source selected ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)).
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 8bfb96bb93..4ec26155a1 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -4,7 +4,7 @@
 
 会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、带从左到右动态渐变的 `Deep diving...` 轮次状态、逐工具行 slot 及一个 bash 示例注册方与 todo 行）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（带发丝分界线的队列行加 todo 计划条）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。
 
-压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。展开内容来自检查点溯源的 `compact/summary`；该事件位于已加载窗口之外时，标记仍然可见但不可展开。面向模型的带框检查点载荷绝不渲染。
+压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行，显示被替换条目数量和估算 token 数量，并可点击展开摘要。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
@@ -64,7 +64,6 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 ## 已知限制与暂缓事项
 
-- **压缩标记不显示规模**：该行尚不报告检查点替换了多少条消息或哪段范围。
 - **统计行的耗时与速率只覆盖窗口内消息流**：LLM 与工具墙钟时间以及 TTFT 与吞吐平均值由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。
 - **详情面板没有入口**：`ChatViewInjected.openDetails` 虽已实现却无人调用，因此以原始形式显示已选择调用的那部分在组装后的应用中不可达。没有 Input/Output/Metadata 切换、Prev/Next 步进，也没有 trajectory 深链接。
 - **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／时钟／分支）只挂在每个已结束轮次中最后一条带 text 内容的 assistant 下；轮次中间的叙述、纯 Think 节点，以及仍在产出步骤的轮次里的所有节点都不带 chrome。除非该消息同时也是已完成轮次的最后一个 transcript 节点，否则分支保持禁用；启用后，它会 fork 到该轮次末尾，在 client 端递增继承标题并打开子会话。fork 或改名失败时源会话保持选中（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)）。
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index b0907f5a80..b15bc20cdb 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -32,6 +32,7 @@ import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
 import { assistantActionsSeqs, assistantBranchSeqs, deriveChatFlow, runningTurnStartTime, type ChatFlowItem } from './chat-flow.ts'
 import { AssistantMarkdown } from './AssistantMarkdown.tsx'
+import { CompactionCommandCard } from './CompactionCommandCard.tsx'
 import { GenericCommandCard } from './GenericCommandCard.tsx'
 import { GenericToolCard } from './GenericToolCard.tsx'
 import { MessageItem, PendingSteeringBubble } from './MessageItem.tsx'
@@ -267,17 +268,21 @@ const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selec
 /** One command lifecycle row: keyed dispatch on the command name with the
  *  generic card as the render-site fallback (zero registration required). A
  *  run-less cross-window node has no name and always lands on the fallback. */
-const CommandRow = memo(function CommandRow({ renderSlot, node, t }: {
+const CommandRow = memo(function CommandRow({ renderSlot, node, compaction, t }: {
   renderSlot: RenderToolRow
   node: CommandNode
+  compaction?: Extract<ConversationNode, { kind: 'compaction' }>
   t: ChatViewSlotProps['t']
 }) {
-  const owner = useMemo(() => ({ node }), [node])
+  const owner = useMemo(() => ({ node, ...compaction === undefined ? {} : { compaction } }), [compaction, node])
+  const fallback = node.name === 'compact' || compaction !== undefined
+    ? <CompactionCommandCard {...owner} t={t} />
+    : <GenericCommandCard {...owner} t={t} />
   return (
     <div className={css.callRow}>
       {renderSlot('conversation.chat.commandview', owner, {
         entryKey: node.name ?? '',
-        fallback: <GenericCommandCard {...owner} t={t} />,
+        fallback,
       })}
     </div>
   )
@@ -580,6 +585,16 @@ export function ChatView({
         />
       )
     }
+    if (item.kind === 'command-compaction') {
+      return (
+        <CommandRow
+          renderSlot={renderSlot}
+          node={item.command}
+          compaction={item.compaction}
+          t={t}
+        />
+      )
+    }
     const node: ConversationNode = item.node
     if (node.kind === 'assistant') {
       const timing = actionSeqs.has(node.seq) ? turnTimings.get(node.turn) : undefined
@@ -642,9 +657,17 @@ export function ChatView({
             <div
               key={item.key}
               className={css.flowItem}
-              data-chat-anchor-key={item.kind === 'node' ? `node:${String(item.node.seq)}` : undefined}
+              data-chat-anchor-key={item.kind === 'node'
+                ? `node:${String(item.node.seq)}`
+                : item.kind === 'command-compaction'
+                  ? `node:${String(item.compaction.seq)}`
+                  : undefined}
               data-chat-flow-key={item.key}
-              data-chat-flow-kind={item.kind === 'node' ? item.node.kind : 'tool-group'}
+              data-chat-flow-kind={item.kind === 'node'
+                ? item.node.kind
+                : item.kind === 'command-compaction'
+                  ? item.kind
+                  : 'tool-group'}
             >
               {renderItem(item)}
             </div>
diff --git a/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
new file mode 100644
index 0000000000..d2401e49c6
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
@@ -0,0 +1,40 @@
+// CompactionCommandCard: the `/compact` command's running row and its
+// successful checkpoint disclosure. Outcomes without a checkpoint keep the
+// generic command card so no-history, cancellation, and failures retain their
+// complete handler-authored text.
+
+import { IconApiOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
+import { CompactionItem } from './CompactionItem.tsx'
+import { GenericCommandCard } from './GenericCommandCard.tsx'
+import { ToolRow } from './ToolRow.tsx'
+
+interface CompactionCommandCardProps extends CommandRowOwnerProps {
+  t: ChatViewSlotProps['t']
+}
+
+/** Render one manual compaction lifecycle without duplicating its checkpoint marker. */
+export function CompactionCommandCard({ node, compaction, t }: CompactionCommandCardProps) {
+  if (compaction !== undefined) {
+    return (
+      <CompactionItem
+        node={compaction}
+        title={node.name ?? 'compact'}
+        fallbackSummary={node.outcome?.text ?? null}
+        t={t}
+      />
+    )
+  }
+  if (node.outcome !== null) return <GenericCommandCard node={node} t={t} />
+  return (
+    <ToolRow
+      t={t}
+      variant="others"
+      icon={<IconApiOutline14 size={14} />}
+      title={node.name ?? 'compact'}
+      summary={t('message.compaction.running')}
+      body={null}
+      state="running"
+    />
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
index 82922dd97e..7049688cc0 100644
--- a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
@@ -18,6 +18,10 @@ import css from './MessageItem.module.css'
 
 interface CompactionItemProps {
   node: CompactionSummaryNode
+  /** Optional command title for a manual compaction folded into this marker. */
+  title?: string
+  /** Command settlement text used only when the summary provenance page is absent. */
+  fallbackSummary?: string | null
   /** The owning view's locale seat. */
   t: ChatViewSlotProps['t']
 }
@@ -27,10 +31,22 @@ interface CompactionItemProps {
  * @param props - the marker node off the snapshot cache.
  * @returns the marker row, with the summary disclosure when one is available.
  */
-export const CompactionItem = memo(function CompactionItem({ node, t }: CompactionItemProps) {
+export const CompactionItem = memo(function CompactionItem({
+  node,
+  title,
+  fallbackSummary,
+  t,
+}: CompactionItemProps) {
   const [expanded, setExpanded] = useState(false)
   const expandable = node.summary !== null
   const open = expandable && expanded
+  const summary = node.shadowedItemCount !== null && node.shadowedTokenCount !== null
+    ? t('message.compaction.completed', {
+      items: node.shadowedItemCount,
+      tokens: node.shadowedTokenCount,
+    })
+    : fallbackSummary
+      ?? (expandable ? t('message.compaction.expand') : t('message.compaction.unavailable'))
   return (
     <div className={css.compactionRow}>
       <button
@@ -43,11 +59,9 @@ export const CompactionItem = memo(function CompactionItem({ node, t }: Compacti
         <span className={css.compactionLeading}>
           {open ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
         </span>
-        <span className={css.compactionTitle}>{t('message.compaction')}</span>
+        <span className={css.compactionTitle}>{title ?? t('message.compaction')}</span>
         <span className={css.compactionSep} aria-hidden />
-        <span className={css.compactionSummary}>
-          {expandable ? t('message.compaction.expand') : t('message.compaction.unavailable')}
-        </span>
+        <span className={css.compactionSummary}>{summary}</span>
       </button>
       {open && node.summary !== null
         && <div className={css.compactionBody}><MarkdownText text={node.summary} /></div>}
diff --git a/packages/client/ui-conversation/src/client/chat/chat-flow.ts b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
index e3b8e5ba2c..22146ddb31 100644
--- a/packages/client/ui-conversation/src/client/chat/chat-flow.ts
+++ b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
@@ -9,13 +9,48 @@
  * flow share their gates.
  */
 import type {
-  AssistantBlock, ConversationNode, ConversationSnapshot, ToolResultNode,
+  AssistantBlock, CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 
 /** One renderable flow item; key is the React key and the parent's identity unit. */
 export type ChatFlowItem =
   | { kind: 'node'; key: string; node: ConversationNode }
   | { kind: 'tool-group'; key: string; results: readonly ToolResultNode[] }
+  | {
+    kind: 'command-compaction'
+    key: string
+    command: CommandNode
+    compaction: CompactionSummaryNode
+  }
+
+/** Match explicit command outcome references to exactly one compaction checkpoint. */
+function commandCompactionPairs(nodes: readonly ConversationNode[]): {
+  readonly byCommandId: ReadonlyMap<string, CompactionSummaryNode>
+  readonly byCompactionSeq: ReadonlyMap<number, CommandNode>
+} {
+  const commandsBySource = new Map<number, CommandNode | null>()
+  for (const node of nodes) {
+    if (node.kind !== 'command' || node.name !== 'compact' || node.outcome?.kind !== 'success') continue
+    const source = node.outcome.sourceEventSeq
+    if (source === undefined) continue
+    commandsBySource.set(source, commandsBySource.has(source) ? null : node)
+  }
+  const compactionsBySummary = new Map<number, CompactionSummaryNode | null>()
+  for (const node of nodes) {
+    if (node.kind !== 'compaction' || node.summaryEventSeq === null) continue
+    const summary = node.summaryEventSeq
+    compactionsBySummary.set(summary, compactionsBySummary.has(summary) ? null : node)
+  }
+  const byCommandId = new Map<string, CompactionSummaryNode>()
+  const byCompactionSeq = new Map<number, CommandNode>()
+  for (const [source, command] of commandsBySource) {
+    const compaction = compactionsBySummary.get(source)
+    if (command === null || compaction === undefined || compaction === null) continue
+    byCommandId.set(command.commandId, compaction)
+    byCompactionSeq.set(compaction.seq, command)
+  }
+  return { byCommandId, byCompactionSeq }
+}
 
 /**
  * True when the node has model-visible text content worth IconActions chrome.
@@ -115,9 +150,29 @@ export function assistantBranchSeqs(
  */
 export function deriveChatFlow(nodes: readonly ConversationNode[]): ChatFlowItem[] {
   const items: ChatFlowItem[] = []
+  const pairs = commandCompactionPairs(nodes)
   let group: ToolResultNode[] | null = null
   for (const node of nodes) {
     if (rendersNothing(node)) continue
+    if (node.kind === 'command' && pairs.byCommandId.has(node.commandId)) {
+      group = null
+      continue
+    }
+    if (node.kind === 'compaction') {
+      group = null
+      const command = pairs.byCompactionSeq.get(node.seq)
+      if (command !== undefined) {
+        items.push({
+          kind: 'command-compaction',
+          key: `c${command.commandId}`,
+          command,
+          compaction: node,
+        })
+      } else {
+        items.push({ kind: 'node', key: `n${node.seq}`, node })
+      }
+      continue
+    }
     if (node.kind === 'tool-result') {
       if (group === null) {
         group = [node]
@@ -138,7 +193,13 @@ export function deriveChatFlow(nodes: readonly ConversationNode[]): ChatFlowItem
       }
     } else {
       group = null
-      items.push({ kind: 'node', key: `n${node.seq}`, node })
+      items.push({
+        kind: 'node',
+        key: node.kind === 'command' && node.name === 'compact'
+          ? `c${node.commandId}`
+          : `n${node.seq}`,
+        node,
+      })
     }
   }
   return items
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 0284784e6e..be57f08523 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -3,7 +3,7 @@ import type { ReactNode, RefObject } from 'react'
 import type {
   InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook,
 } from '@deepseek-ai/dsh-client-ui-slots'
-import type { CommandNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { ComposerBlock } from '../input/blocks.ts'
 import type { ComposerKeyboard, EditSelection, InputActions, InputNotice, InputState } from '../input/contract.ts'
@@ -217,14 +217,16 @@ export type ToolRowProps = PropsRuntime<'conversation.chat.toolview'>
 /**
  * Owner share of the per-command row slot: the frozen {@link CommandNode}
  * slice off the snapshot (cache-stable reference — memo premise). The node
- * carries the whole lifecycle (structured name/args, pairing id,
- * outcome-or-executing), so a
- * registrant needs no second data channel; domain state arrives through its
- * own projection cell.
+ * carries the whole lifecycle (structured name/args, pairing id, and
+ * outcome-or-executing). A successful domain command may also carry the
+ * explicitly linked projection node needed to fold two log records into one
+ * presentation row.
  */
 export interface CommandRowOwnerProps {
   /** Folded command lifecycle node (run + optional done). */
   node: CommandNode
+  /** Explicitly linked compaction checkpoint for the settled `/compact` presentation. */
+  compaction?: CompactionSummaryNode
 }
 
 /** Full props of a registered command-row component (same shape rule as {@link ToolRowProps}). */
diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index df107d2cd2..11e852a8b6 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -80,6 +80,8 @@ export const zh = {
   'message.context.recall.truncated': '已截断',
   'message.steering': '插话',
   'message.compaction': '上下文已压缩',
+  'message.compaction.running': '正在压缩…',
+  'message.compaction.completed': '已压缩 {items} 条历史记录（约 {tokens} tokens）',
   'message.compaction.expand': '点击查看压缩摘要',
   'message.compaction.unavailable': '压缩摘要不可用',
   'message.unknownSurface': '未知 surface 事件：{type}',
@@ -220,6 +222,8 @@ export const en = {
   'message.context.recall.truncated': 'truncated',
   'message.steering': 'Interjection',
   'message.compaction': 'Context compacted',
+  'message.compaction.running': 'Compacting context…',
+  'message.compaction.completed': 'Compacted {items} history items (~{tokens} tokens)',
   'message.compaction.expand': 'View compaction summary',
   'message.compaction.unavailable': 'Compaction summary unavailable',
   'message.unknownSurface': 'Unknown surface event: {type}',
diff --git a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
index 3122b0fdc7..7d5ba6a528 100644
--- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
@@ -691,11 +691,15 @@ describe('MessageItem arms', () => {
       <MessageItem t={t} node={{
         kind: 'compaction', seq: 5, time: 1_000,
         summary: '## 摘要标题\n\n保留的事实。',
+        summaryEventSeq: 4,
+        shadowedItemCount: 16,
+        shadowedTokenCount: 11_309,
       }}
       />,
     )
     const row = view.getByRole('button', { name: /上下文已压缩/ })
     expect(row.getAttribute('aria-expanded')).toBe('false')
+    expect(view.getByText('已压缩 16 条历史记录（约 11309 tokens）')).toBeTruthy()
     expect(view.queryByText(/保留的事实/)).toBeNull()
     fireEvent.click(row)
     expect(row.getAttribute('aria-expanded')).toBe('true')
@@ -705,7 +709,10 @@ describe('MessageItem arms', () => {
   })
 
   it('a marker whose provenance fell outside the window is not expandable', () => {
-    const view = render(<MessageItem t={t} node={{ kind: 'compaction', seq: 6, time: 1_000, summary: null }} />)
+    const view = render(<MessageItem t={t} node={{
+      kind: 'compaction', seq: 6, time: 1_000, summary: null,
+      summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
+    }} />)
     const row = view.getByRole('button', { name: /上下文已压缩/ })
     expect(row).toHaveProperty('disabled', true)
     expect(row.getAttribute('aria-expanded')).toBeNull()
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index b8cd94de52..a0213a2407 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -7,7 +7,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Profiler } from 'react'
 import { act, cleanup, fireEvent, render, within } from '@testing-library/react'
 import type {
-  AssistantMessageNode, CommandNode, ConversationNode, ConversationSnapshot,
+  AssistantMessageNode, CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot,
   ModelRetryNode, RunningToolCall, SessionId, SessionListState, ToolResultNode, TurnErrorNode,
   UserMessageNode, WorkspaceListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -93,6 +93,19 @@ const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode
 const runningCall = (callId: string, name = 'bash'): RunningToolCall => ({
   callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, time: 1_000, callView: null,
 })
+const command = (over: Partial<CommandNode> = {}): CommandNode => ({
+  kind: 'command', seq: 5, time: 5_000, commandId: 'cmd-1' as CommandNode['commandId'],
+  name: 'plan', args: '', outcome: { kind: 'success', text: '已进入 plan mode' },
+  ...over,
+})
+const compaction = (over: Partial<CompactionSummaryNode> = {}): CompactionSummaryNode => ({
+  kind: 'compaction', seq: 8, time: 8_000,
+  summary: '## 压缩摘要\n\n保留的事实。',
+  summaryEventSeq: 7,
+  shadowedItemCount: 16,
+  shadowedTokenCount: 11_309,
+  ...over,
+})
 
 /** Empty sessions-list hook for the global standard-kit seat. */
 function emptySessions() {
@@ -212,6 +225,60 @@ describe('chat-flow derivation', () => {
     expect(updated[1]?.kind === 'node' && updated[1].node).toBe(second)
   })
 
+  it('folds a successful /compact lifecycle into its explicitly linked checkpoint', () => {
+    const running = command({
+      seq: 1,
+      commandId: 'cmd-compact' as CommandNode['commandId'],
+      name: 'compact',
+      outcome: null,
+    })
+    expect(flowKeys(deriveChatFlow([user(0, 'before'), running]))).toBe('n0|ccmd-compact')
+
+    const settled = {
+      ...running,
+      outcome: { kind: 'success' as const, text: 'Compacted 16 history items.', sourceEventSeq: 3 },
+    }
+    const checkpoint = compaction({ seq: 4, summaryEventSeq: 3 })
+    const items = deriveChatFlow([user(0, 'before'), settled, user(2, 'injected while compacting'), checkpoint])
+    expect(flowKeys(items)).toBe('n0|n2|ccmd-compact')
+    expect(items.at(-1)).toEqual({
+      kind: 'command-compaction',
+      key: 'ccmd-compact',
+      command: settled,
+      compaction: checkpoint,
+    })
+  })
+
+  it('keeps automatic, unlinked, and ambiguously linked compactions as separate rows', () => {
+    const automatic = compaction({ seq: 2, summaryEventSeq: 1 })
+    expect(flowKeys(deriveChatFlow([automatic]))).toBe('n2')
+
+    const first = command({
+      seq: 3,
+      commandId: 'cmd-a' as CommandNode['commandId'],
+      name: 'compact',
+      outcome: { kind: 'success', sourceEventSeq: 9 },
+    })
+    const second = command({
+      seq: 4,
+      commandId: 'cmd-b' as CommandNode['commandId'],
+      name: 'compact',
+      outcome: { kind: 'success', sourceEventSeq: 9 },
+    })
+    const ambiguous = compaction({ seq: 10, summaryEventSeq: 9 })
+    expect(flowKeys(deriveChatFlow([first, second, ambiguous]))).toBe('ccmd-a|ccmd-b|n10')
+
+    const sole = command({
+      seq: 11,
+      commandId: 'cmd-sole' as CommandNode['commandId'],
+      name: 'compact',
+      outcome: { kind: 'success', sourceEventSeq: 12 },
+    })
+    const duplicateA = compaction({ seq: 13, summaryEventSeq: 12 })
+    const duplicateB = compaction({ seq: 14, summaryEventSeq: 12 })
+    expect(flowKeys(deriveChatFlow([sole, duplicateA, duplicateB]))).toBe('ccmd-sole|n13|n14')
+  })
+
   it('skips render-nothing assistant nodes so tool runs stay one group', () => {
     // A tool-call-only step message (and blank text/reasoning) renders nothing:
     // it must not split the run into two groups with an empty line between.
@@ -1172,11 +1239,6 @@ describe('ChatView', () => {
   })
 
   it('renders command nodes as durable rows: settled text, error state, executing spinner, run-less soft-fall', () => {
-    const command = (over: Partial<CommandNode>): CommandNode => ({
-      kind: 'command', seq: 5, time: 5_000, commandId: 'cmd-1' as CommandNode['commandId'],
-      name: 'plan', args: '', outcome: { kind: 'success', text: '已进入 plan mode' },
-      ...over,
-    })
     // Settled success: the bare command name is the title, the outcome text
     // the summary — neither the dispatched `/` nor its arguments reach the row
     // (the settlement text already says what the command did).
@@ -1211,4 +1273,62 @@ describe('ChatView', () => {
     expect(ov.getByText('命令')).toBeTruthy()
     expect(ov.getByText('已完成')).toBeTruthy()
   })
+
+  it('renders /compact as one stateful disclosure from running through completion', () => {
+    const running = command({
+      commandId: 'cmd-compact' as CommandNode['commandId'],
+      name: 'compact',
+      outcome: null,
+    })
+    const h = makeHarness({ nodes: [running] })
+    const view = render(<h.ChatView {...h.props} />)
+    expect(view.getByText('正在压缩…')).toBeTruthy()
+    expect(view.container.querySelector('[data-state="running"]')).not.toBeNull()
+
+    act(() => {
+      h.set({
+        nodes: [{
+          ...running,
+          outcome: {
+            kind: 'success',
+            text: 'Compacted 16 history items (~11309 tokens).',
+            sourceEventSeq: 7,
+          },
+        }, compaction()],
+      })
+    })
+
+    expect(view.queryByText('正在压缩…')).toBeNull()
+    expect(view.queryByText('上下文已压缩')).toBeNull()
+    expect(view.getByText('已压缩 16 条历史记录（约 11309 tokens）')).toBeTruthy()
+    const row = view.getByRole('button', { name: /compact/ })
+    expect(row.getAttribute('aria-expanded')).toBe('false')
+    expect(view.queryByText('保留的事实。')).toBeNull()
+    fireEvent.click(row)
+    expect(row.getAttribute('aria-expanded')).toBe('true')
+    expect(view.getByRole('heading', { name: '压缩摘要' })).toBeTruthy()
+  })
+
+  it('keeps /compact no-history and error settlements on the generic command row', () => {
+    const noHistory = makeHarness({
+      nodes: [command({
+        name: 'compact',
+        outcome: { kind: 'success', text: 'No compactable history yet.' },
+      })],
+    })
+    const noHistoryView = render(<noHistory.ChatView {...noHistory.props} />)
+    expect(noHistoryView.getByText('No compactable history yet.')).toBeTruthy()
+    expect(noHistoryView.queryByRole('button')).toBeNull()
+
+    const failed = makeHarness({
+      nodes: [command({
+        commandId: 'cmd-compact-failed' as CommandNode['commandId'],
+        name: 'compact',
+        outcome: { kind: 'error', text: 'Compaction cancelled.' },
+      })],
+    })
+    const failedView = render(<failed.ChatView {...failed.props} />)
+    expect(failedView.getByText('Compaction cancelled.')).toBeTruthy()
+    expect(failedView.container.querySelector('[data-state="error"]')).not.toBeNull()
+  })
 })
diff --git a/packages/client/ui-trajectory/tests/layout.spec.tsx b/packages/client/ui-trajectory/tests/layout.spec.tsx
index bd25cc4d51..544199e345 100644
--- a/packages/client/ui-trajectory/tests/layout.spec.tsx
+++ b/packages/client/ui-trajectory/tests/layout.spec.tsx
@@ -324,7 +324,10 @@ describe('deriveTrajectoryLayout', () => {
       },
       // A landed compaction renders no cell, but is still a real log position,
       // so it moves the cursor after the visible context row.
-      { kind: 'compaction', seq: 5, time: 9_500, summary: 'checkpoint facts' },
+      {
+        kind: 'compaction', seq: 5, time: 9_500, summary: 'checkpoint facts',
+        summaryEventSeq: 4, shadowedItemCount: 2, shadowedTokenCount: 100,
+      },
       {
         kind: 'assistant', seq: 6, time: 10_000, turn: 1, step: 0,
         blocks: [{ kind: 'text', text: 'done' }],
diff --git a/packages/compact/command-compact/README.i18n.yaml b/packages/compact/command-compact/README.i18n.yaml
index c39570db18..35ebe66e2b 100644
--- a/packages/compact/command-compact/README.i18n.yaml
+++ b/packages/compact/command-compact/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/compact/command-compact/README.md
-README.md: a32a6aeb9957f0fd5f8cff58b1edbb9bc29a4e3d
-README.zh.md: c678f522115d9b0fd414b2f290b3cb54ce690722
+README.md: 54f341e39447a423964b7d7435cfb638857eda6e
+README.zh.md: d4a122b8a19cdf907212ad019b2528ae52d03886
diff --git a/packages/compact/command-compact/README.md b/packages/compact/command-compact/README.md
index a32a6aeb99..54f341e394 100644
--- a/packages/compact/command-compact/README.md
+++ b/packages/compact/command-compact/README.md
@@ -12,7 +12,7 @@ Human-facing `/compact` control over [`ctx.compact`](../compact/README.md). The
 | `/compact` with no compactable history | `No compactable history yet.` — no marker or surface mutation is written. |
 | `/compact <anything>` | `Usage: /compact (no arguments)` — the command takes no arguments and calls no compaction backend. |
 
-The command is backend-independent: it depends only on `compactNow(agent, signal)`. The invoking agent is the exact target, and the dispatching UI's cancellation signal is forwarded through the seam. Every resolved invocation records the executor-owned log-only pair `command/run` / `command/done`; neither event joins model history.
+The command is backend-independent: it depends only on `compactNow(agent, signal)`. The invoking agent is the exact target, and the dispatching UI's cancellation signal is forwarded through the seam. Every resolved invocation records the executor-owned log-only pair `command/run` / `command/done`; neither event joins model history. On success, `command/done.sourceEventSeq` names the transaction's `compact/summary` event so a presentation can fold the command lifecycle into its checkpoint without parsing result text or assuming adjacent rows.
 
 Expected `ManualCompactionError` codes become stable direct errors:
 
diff --git a/packages/compact/command-compact/README.zh.md b/packages/compact/command-compact/README.zh.md
index c678f52211..d4a122b8a1 100644
--- a/packages/compact/command-compact/README.zh.md
+++ b/packages/compact/command-compact/README.zh.md
@@ -12,7 +12,7 @@
 | `/compact`，但没有可压缩历史 | `No compactable history yet.`：不会写入标记，也不会变更 surface。 |
 | `/compact <anything>` | `Usage: /compact (no arguments)`：该命令不接受参数，也不会调用压缩后端。 |
 
-该命令与后端无关，只依赖 `compactNow(agent, signal)`。调用该命令的 agent（智能体）就是操作的确切目标，发起分发的 UI 会通过 seam 转发取消信号。每次完成的调用都会记录执行器所属的纯日志事件对 `command/run` / `command/done`；两者都不进入模型历史。
+该命令与后端无关，只依赖 `compactNow(agent, signal)`。调用该命令的 agent（智能体）就是操作的确切目标，发起分发的 UI 会通过 seam 转发取消信号。每次完成的调用都会记录执行器所属的纯日志事件对 `command/run` / `command/done`；两者都不进入模型历史。成功时，`command/done.sourceEventSeq` 会指明该事务的 `compact/summary` 事件，让呈现层无须解析结果文本或假定两行相邻，即可将命令生命周期归并到对应检查点中。
 
 预期的 `ManualCompactionError` 代码会成为稳定的直接错误：
 
diff --git a/packages/compact/command-compact/src/index.ts b/packages/compact/command-compact/src/index.ts
index 2390833bff..4ac171a689 100644
--- a/packages/compact/command-compact/src/index.ts
+++ b/packages/compact/command-compact/src/index.ts
@@ -68,6 +68,7 @@ async function executeCompact(
     return {
       kind: 'success',
       text: `Compacted ${result.shadowedSeqs.length} history items (~${result.shadowedTokenCount} tokens).`,
+      sourceEventSeq: result.summarySeq,
     }
   } catch (error: unknown) {
     if (invocation.signal.aborted) return { kind: 'error', text: 'Compaction cancelled.' }
diff --git a/packages/compact/command-compact/tests/command-compact.spec.ts b/packages/compact/command-compact/tests/command-compact.spec.ts
index 71af9534e4..6922778a26 100644
--- a/packages/compact/command-compact/tests/command-compact.spec.ts
+++ b/packages/compact/command-compact/tests/command-compact.spec.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import CommandService from '@deepseek-ai/dsh-commands'
+import CommandService, { type CommandResult } from '@deepseek-ai/dsh-commands'
 import {
   CompactService,
   ManualCompactionError,
@@ -15,9 +15,9 @@ import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import * as commandCompact from '@deepseek-ai/dsh-command-compact'
 
 const RESULT: CompactionResult = {
-  startSeq: 10,
-  summarySeq: 11,
-  endSeq: 13,
+  startSeq: 1,
+  summarySeq: 2,
+  endSeq: 3,
   summary: [{ type: 'text', text: 'summary' }],
   shadowedRange: { start: 1, end: 7 },
   shadowedSeqs: [1, 3, 7],
@@ -49,10 +49,24 @@ class StubCompactService extends CompactService {
     this.calls.push({ agent, signal })
     if (this.operation !== undefined) return this.operation()
     return this.failure === undefined
-      ? Promise.resolve(this.result)
+      ? Promise.resolve(this.result === null ? null : this.appendResult(agent, this.result))
       // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- exercise arbitrary backend rejection values.
       : Promise.reject(this.failure)
   }
+
+  private appendResult(agent: ManualCompactAgentContext, result: CompactionResult): CompactionResult {
+    agent.session.append('compact/start', { turn: null })
+    agent.session.append('compact/summary', {
+      summary: result.summary,
+      shadowedRange: result.shadowedRange,
+      shadowedSeqs: result.shadowedSeqs,
+      shadowedTokenCount: result.shadowedTokenCount,
+      provider: 'command-test',
+      model: 'command-test',
+    })
+    agent.session.append('compact/end', { turn: null })
+    return result
+  }
 }
 
 interface Harness {
@@ -91,9 +105,11 @@ async function run(
 function expectLastLifecycle(
   test: Harness,
   args: string,
-  outcome: { readonly kind: 'success' | 'error'; readonly text?: string },
+  outcome: CommandResult,
 ): string {
-  const lifecycle = test.agent.session.events.slice(-2)
+  const lifecycle = test.agent.session.events
+    .filter(event => event.type === 'command/run' || event.type === 'command/done')
+    .slice(-2)
   const runEvent = lifecycle[0]
   const doneEvent = lifecycle[1]
   if (runEvent?.type !== 'command/run' || doneEvent?.type !== 'command/done') {
@@ -149,6 +165,7 @@ describe('/compact human command', () => {
     expect(execution.result).toEqual({
       kind: 'success',
       text: 'Compacted 3 history items (~42 tokens).',
+      sourceEventSeq: RESULT.summarySeq,
     })
     expect(execution.commandId).toBe(expectLastLifecycle(test, '', execution.result))
     expect(test.compact.calls).toEqual([{ agent: test.agent, signal: controller.signal }])
diff --git a/packages/compact/command-compact/tests/loader-composition.spec.ts b/packages/compact/command-compact/tests/loader-composition.spec.ts
index bbd9bcfcb1..5a5d37d8b1 100644
--- a/packages/compact/command-compact/tests/loader-composition.spec.ts
+++ b/packages/compact/command-compact/tests/loader-composition.spec.ts
@@ -21,7 +21,7 @@ import { Session, SessionId } from '@deepseek-ai/dsh-session'
 const RESULT: CompactionResult = {
   startSeq: 1,
   summarySeq: 2,
-  endSeq: 4,
+  endSeq: 3,
   summary: [{ type: 'text', text: 'loader summary' }],
   shadowedRange: { start: 3, end: 8 },
   shadowedSeqs: [3, 5, 8],
@@ -42,9 +42,19 @@ class LoaderCompactService extends CompactService {
   }
 
   override compactNow(
-    _agent: ManualCompactAgentContext,
+    agent: ManualCompactAgentContext,
     _signal: AbortSignal,
   ): Promise<CompactionResult | null> {
+    agent.session.append('compact/start', { turn: null })
+    agent.session.append('compact/summary', {
+      summary: RESULT.summary,
+      shadowedRange: RESULT.shadowedRange,
+      shadowedSeqs: RESULT.shadowedSeqs,
+      shadowedTokenCount: RESULT.shadowedTokenCount,
+      provider: 'loader-test',
+      model: 'loader-test',
+    })
+    agent.session.append('compact/end', { turn: null })
     return Promise.resolve(RESULT)
   }
 }
@@ -108,6 +118,7 @@ describe('command-compact real Loader composition', () => {
     expect(execution.result).toEqual({
       kind: 'success',
       text: 'Compacted 3 history items (~99 tokens).',
+      sourceEventSeq: RESULT.summarySeq,
     })
     expect(session.events.map(event => ({ type: event.type, data: event.data }))).toEqual([
       {
@@ -119,12 +130,32 @@ describe('command-compact real Loader composition', () => {
           source: { kind: 'user' },
         },
       },
+      {
+        type: 'compact/start',
+        data: { turn: null },
+      },
+      {
+        type: 'compact/summary',
+        data: {
+          summary: RESULT.summary,
+          shadowedRange: RESULT.shadowedRange,
+          shadowedSeqs: RESULT.shadowedSeqs,
+          shadowedTokenCount: RESULT.shadowedTokenCount,
+          provider: 'loader-test',
+          model: 'loader-test',
+        },
+      },
+      {
+        type: 'compact/end',
+        data: { turn: null },
+      },
       {
         type: 'command/done',
         data: {
           commandId: execution.commandId,
           kind: 'success',
           text: 'Compacted 3 history items (~99 tokens).',
+          sourceEventSeq: RESULT.summarySeq,
         },
       },
     ])
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index b7fd6d3c5a..01ccdc5bf6 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -1793,7 +1793,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'CommandResult',
-    declaration: 'export type CommandResult = {\n    readonly kind: \'success\';\n    readonly text?: string;\n} | {\n    readonly kind: \'error\';\n    readonly text: string;\n};',
+    declaration: 'export type CommandResult = {\n    readonly kind: \'success\';\n    readonly text?: string;\n    readonly sourceEventSeq?: number;\n} | {\n    readonly kind: \'error\';\n    readonly text: string;\n};',
   },
   {
     name: 'CompactAgentContext',
diff --git a/packages/ui/commands/README.i18n.yaml b/packages/ui/commands/README.i18n.yaml
index 751344084c..be55a19ca3 100644
--- a/packages/ui/commands/README.i18n.yaml
+++ b/packages/ui/commands/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/commands/README.md
-README.md: 3105ae1a866e03f3c8f621bfe588df15ee38957e
-README.zh.md: 704a2daefb65fde12ca85d1c9051ad762c5ccc70
+README.md: 1709bdcdce4e43d98cfea5ff3972ab95bfd3c33b
+README.zh.md: 569f2aa8293793b26d63ee16e3ea7600e04a8397
diff --git a/packages/ui/commands/README.md b/packages/ui/commands/README.md
index 3105ae1a86..1709bdcdce 100644
--- a/packages/ui/commands/README.md
+++ b/packages/ui/commands/README.md
@@ -8,11 +8,11 @@ Plugin-owned human-command registry consumed by interactive UI adapters. The [pl
 
 `ctx.commands.register(definition)` registers one lowercase command name, description, optional unstructured-input hint, optional `recordInput` policy, and abortable handler. `recordInput` defaults to true; a command whose authoritative domain event owns the payload sets it to false so `command/run` omits `args` instead of duplicating the input. A registered command is available to every composed command adapter; a plugin that is incompatible with a deployment does not register there. A plain-context registration is global. A command-producing plugin mounted beneath `agent.ctx` declares its own `commands` injection and creates an exact agent-scoped definition; it shadows a global definition with the same name. This child-injection shape preserves the agent scope without making the core agent loop depend on a UI service. Duplicate names within one layer fail during registration. Every disposer is the exact Cordis effect disposer, and registration or removal notifies every `commands/change` observer so live adapters can refresh discovery; observer failures are logged and cannot veto the registry mutation or starve later observers.
 
-`list(agent)` returns immutable, name-sorted descriptors after scoped shadowing. `find(agent, name)` returns the corresponding definition. `execute(agent, line, signal)` uses `parseCommand()` and runs only a known command, returning the settled `CommandExecution` (the normalized result plus the lifecycle pairing `commandId`) or `undefined` for invalid syntax or unknown names. A resolved command's lifecycle is logged on the receiving agent's session as the log-only pair `command/run` (before the handler, with a minted `commandId`, the parser's structured name, the issuing `CommandSource`, and `args` unless `recordInput` is false) and `command/done` (at settlement, with the outcome kind and verbatim text; a thrown or aborted handler settles as `kind: 'error'`). Admission misses log nothing. Both are direct standalone appends on the receiving agent's session: no turn wraps them, and persistence drains them through ordinary checkpoints and teardown.
+`list(agent)` returns immutable, name-sorted descriptors after scoped shadowing. `find(agent, name)` returns the corresponding definition. `execute(agent, line, signal)` uses `parseCommand()` and runs only a known command, returning the settled `CommandExecution` (the normalized result plus the lifecycle pairing `commandId`) or `undefined` for invalid syntax or unknown names. A resolved command's lifecycle is logged on the receiving agent's session as the log-only pair `command/run` (before the handler, with a minted `commandId`, the parser's structured name, the issuing `CommandSource`, and `args` unless `recordInput` is false) and `command/done` (at settlement, with the outcome kind and verbatim text; a successful result may also name an earlier non-command authoritative domain event through `sourceEventSeq`; a thrown or aborted handler settles as `kind: 'error'`). Admission misses log nothing. Both are direct standalone appends on the receiving agent's session: no turn wraps them, and persistence drains them through ordinary checkpoints and teardown.
 
 `parseCommand()` recognizes a slash at byte zero, a lowercase name containing letters, digits, `_`, or `-`, and either end-of-input or whitespace. It returns every byte after the name as `rawInput`, including separator whitespace; consumers own their command-specific grammar and may normalize only what that grammar permits.
 
-Handlers return `success` or `error` plus optional UI text. Results are rendered directly by the adapter and never enter model history. The registry never submits `rawInput` to the agent implicitly; a command producer may explicitly schedule model-visible work through the receiving `Agent`, in which case that producer owns the resulting message contract. The registry races handler completion against the supplied abort signal, but an uncooperative handler may continue its own external side effects after the caller stops awaiting it.
+Handlers return `success` or `error` plus optional UI text. A successful handler may also return `sourceEventSeq` when an earlier domain event owns a richer presentation; the lifecycle invariant requires that reference to be a prior non-command event in the same session. Results are rendered directly by the adapter and never enter model history. The registry never submits `rawInput` to the agent implicitly; a command producer may explicitly schedule model-visible work through the receiving `Agent`, in which case that producer owns the resulting message contract. The registry races handler completion against the supplied abort signal, but an uncooperative handler may continue its own external side effects after the caller stops awaiting it.
 
 ## Composition
 
diff --git a/packages/ui/commands/README.zh.md b/packages/ui/commands/README.zh.md
index 704a2daefb..569f2aa829 100644
--- a/packages/ui/commands/README.zh.md
+++ b/packages/ui/commands/README.zh.md
@@ -8,11 +8,11 @@
 
 `ctx.commands.register(definition)` 注册一个小写命令名称、描述、可选的非结构化输入提示、可选的 `recordInput` 策略，以及可中止的处理器。`recordInput` 默认为 true；若载荷由命令的权威领域事件持有，该命令会将 `recordInput` 设为 false，让 `command/run` 省略 `args`，避免重复记录输入。每个已注册命令都可供所有已组合的命令适配器使用；与某项部署不兼容的插件不会在此注册。普通上下文中的注册全局生效。在 `agent.ctx` 下挂载的命令生产插件会声明自身的 `commands` 注入，并创建精确限定到该 agent（智能体）的定义；该定义会遮蔽同名的全局定义。这种子级注入形态保留了 agent 作用域，同时不会让核心 agent loop（智能体循环）依赖 UI 服务。同一层中的名称重复会在注册时失败。每个 disposer 都是 Cordis effect 返回的确切 disposer；注册或移除命令时，系统会通知每个 `commands/change` 观察者，使运行中的适配器能够刷新发现结果。观察者失败会写入日志，既不能否决注册表变更，也不能阻止后续观察者运行。
 
-`list(agent)` 在应用作用域遮蔽后，返回按名称排序的不可变描述符。`find(agent, name)` 返回相应定义。`execute(agent, line, signal)` 使用 `parseCommand()`，且只运行已知命令，返回已结算的 `CommandExecution`（规范化结果加生命周期配对 `commandId`）；语法无效或名称未知时返回 `undefined`。已解析命令的生命周期会以 log-only 事件对的形式记录在接收 agent 的会话日志中：`command/run`（进入处理器前记录，携带新生成的 `commandId`、解析器的结构化名称、发起方 `CommandSource`，以及 `args`（`recordInput` 为 false 时省略））与 `command/done`（结算时记录，携带结果类型与原样文本；处理器抛出或被中止时以 `kind: 'error'` 结算）。未通过准入的输入不记录任何事件。两者都直接独立追加到接收 agent 的会话中：没有轮次包裹它们，持久化机制会在常规检查点和销毁期间排空这些事件。
+`list(agent)` 在应用作用域遮蔽后，返回按名称排序的不可变描述符。`find(agent, name)` 返回相应定义。`execute(agent, line, signal)` 使用 `parseCommand()`，且只运行已知命令，返回已结算的 `CommandExecution`（规范化结果加生命周期配对 `commandId`）；语法无效或名称未知时返回 `undefined`。已解析命令的生命周期会以 log-only 事件对的形式记录在接收 agent 的会话日志中：`command/run`（进入处理器前记录，携带新生成的 `commandId`、解析器的结构化名称、发起方 `CommandSource`，以及 `args`（`recordInput` 为 false 时省略））与 `command/done`（结算时记录，携带结果类型与原样文本；成功结果还可通过 `sourceEventSeq` 指向更早的一条非命令权威领域事件；处理器抛出或被中止时以 `kind: 'error'` 结算）。未通过准入的输入不记录任何事件。两者都直接独立追加到接收 agent 的会话中：没有轮次包裹它们，持久化机制会在常规检查点和销毁期间排空这些事件。
 
 `parseCommand()` 识别位于第 0 字节的斜杠、由小写字母、数字、`_` 或 `-` 构成的名称，以及名称后紧接输入末尾或空白的形式。它将名称后的每个字节作为 `rawInput` 返回，其中包括分隔空白；消费方负责各命令专用的语法，只能执行该语法允许的规范化。
 
-处理器返回 `success` 或 `error`，并可附带 UI 文本。适配器直接渲染结果，结果绝不进入模型历史。注册表绝不会隐式地把 `rawInput` 提交给 agent；命令生产方可以通过接收命令的 `Agent` 显式安排模型可见工作，此时该生产方负责由此产生的消息契约。注册表会同时等待处理器完成和所提供的中止信号，以先发生者为准，但不响应中止的处理器可能在调用方停止等待后继续产生自身的外部副作用。
+处理器返回 `success` 或 `error`，并可附带 UI 文本。若更丰富的呈现由一条更早的领域事件持有，成功的处理器还可返回 `sourceEventSeq`；生命周期不变量要求该引用指向同一会话中更早的一条非命令事件。适配器直接渲染结果，结果绝不进入模型历史。注册表绝不会隐式地把 `rawInput` 提交给 agent；命令生产方可以通过接收命令的 `Agent` 显式安排模型可见工作，此时该生产方负责由此产生的消息契约。注册表会同时等待处理器完成和所提供的中止信号，以先发生者为准，但不响应中止的处理器可能在调用方停止等待后继续产生自身的外部副作用。
 
 ## 组合
 
diff --git a/packages/ui/commands/src/index.ts b/packages/ui/commands/src/index.ts
index b6dea581eb..64a9f8e8c8 100644
--- a/packages/ui/commands/src/index.ts
+++ b/packages/ui/commands/src/index.ts
@@ -47,7 +47,12 @@ export interface CommandInvocation {
 
 /** Expected command outcome rendered directly by the dispatching UI. */
 export type CommandResult =
-  | { readonly kind: 'success'; readonly text?: string }
+  | {
+    readonly kind: 'success'
+    readonly text?: string
+    /** Earlier authoritative domain event that owns a richer presentation. */
+    readonly sourceEventSeq?: number
+  }
   | { readonly kind: 'error'; readonly text: string }
 
 /**
@@ -140,9 +145,15 @@ declare module '@deepseek-ai/dsh-session' {
     /**
      * The paired command settled. `kind`/`text` carry the handler's verbatim
      * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
-     * rendered failure); presentation stays client-computed at render time.
+     * rendered failure). A successful command may identify the earlier
+     * authoritative domain event for a richer client-computed presentation.
      */
-    'command/done': { commandId: CommandId; kind: 'success' | 'error'; text?: string }
+    'command/done': {
+      commandId: CommandId
+      kind: 'success' | 'error'
+      text?: string
+      sourceEventSeq?: number
+    }
   }
 }
 
@@ -262,12 +273,20 @@ function normalizeResult(command: string, value: unknown): CommandResult {
   if (typeof value !== 'object' || value === null || !('kind' in value)) {
     throw new TypeError(`command "${command}" handler must return a CommandResult`)
   }
-  const result = value as { kind?: unknown; text?: unknown }
+  const result = value as { kind?: unknown; text?: unknown; sourceEventSeq?: unknown }
   if (result.kind === 'success') {
     if (result.text !== undefined && typeof result.text !== 'string') {
       throw new TypeError(`command "${command}" success text must be a string when supplied`)
     }
-    return Object.freeze(result.text === undefined ? { kind: 'success' } : { kind: 'success', text: result.text })
+    if (result.sourceEventSeq !== undefined
+      && (!Number.isSafeInteger(result.sourceEventSeq) || (result.sourceEventSeq as number) < 0)) {
+      throw new TypeError(`command "${command}" success sourceEventSeq must be a non-negative safe integer when supplied`)
+    }
+    return Object.freeze({
+      kind: 'success',
+      ...result.text === undefined ? {} : { text: result.text },
+      ...result.sourceEventSeq === undefined ? {} : { sourceEventSeq: result.sourceEventSeq as number },
+    })
   }
   if (result.kind === 'error') {
     if (typeof result.text !== 'string' || result.text.trim().length === 0) {
@@ -389,6 +408,9 @@ export class CommandService extends Service {
     this.appendLifecycle(agent.session, 'command/done', {
       commandId, kind: result.kind,
       ...result.text === undefined ? {} : { text: result.text },
+      ...result.kind === 'success' && result.sourceEventSeq !== undefined
+        ? { sourceEventSeq: result.sourceEventSeq }
+        : {},
     })
     return Object.freeze({ commandId, result })
   }
diff --git a/packages/ui/commands/src/invariant.ts b/packages/ui/commands/src/invariant.ts
index 858c31591c..792733c199 100644
--- a/packages/ui/commands/src/invariant.ts
+++ b/packages/ui/commands/src/invariant.ts
@@ -34,6 +34,16 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
     if (runIds.get(session)?.has(event.data.commandId) !== true) {
       fail(`command/done ${JSON.stringify(event.data.commandId)} pairs no prior command/run in this log`)
     }
+    const source = event.data.sourceEventSeq
+    const sourceEvent = source === undefined ? undefined : session.events[source]
+    if (source !== undefined
+      && (event.data.kind !== 'success'
+        || !Number.isSafeInteger(source) || source < 0 || source >= event.seq
+        || sourceEvent?.seq !== source
+        || sourceEvent.type === 'command/run'
+        || sourceEvent.type === 'command/done')) {
+      fail(`command/done ${JSON.stringify(event.data.commandId)} has invalid sourceEventSeq ${String(source)}`)
+    }
   }
   for (const session of ctx.sessions.list()) {
     for (const event of session.events) validateEvent(session, event)
diff --git a/packages/ui/commands/tests/commands.spec.ts b/packages/ui/commands/tests/commands.spec.ts
index 7412325ab6..54b4227d19 100644
--- a/packages/ui/commands/tests/commands.spec.ts
+++ b/packages/ui/commands/tests/commands.spec.ts
@@ -320,6 +320,25 @@ describe('CommandService', () => {
     ])
   })
 
+  it('preserves an earlier authoritative domain-event reference on successful settlement', async () => {
+    const ctx = await mount()
+    const { agent } = await mintAgentScope(ctx, 'a')
+    const source = agent.session.append('turn/start', { turn: 1 })
+    ctx.commands.register({
+      name: 'linked',
+      description: 'Link outcome',
+      handler: () => ({ kind: 'success', text: 'linked', sourceEventSeq: source.seq }),
+    })
+
+    const execution = await ctx.commands.execute(agent, '/linked', new AbortController().signal)
+
+    expect(execution?.result).toEqual({ kind: 'success', text: 'linked', sourceEventSeq: source.seq })
+    expect(lifecycleOf(agent)).toMatchObject([
+      { type: 'command/run', data: { name: 'linked' } },
+      { type: 'command/done', data: { kind: 'success', text: 'linked', sourceEventSeq: source.seq } },
+    ])
+  })
+
   it('omits raw input from command/run when an authoritative domain event owns it', async () => {
     const ctx = await mount()
     const { agent } = await mintAgentScope(ctx, 'a')
@@ -427,6 +446,9 @@ describe('CommandService', () => {
     [null, /CommandResult/],
     [{}, /CommandResult/],
     [{ kind: 'success', text: 1 }, /success text/],
+    [{ kind: 'success', sourceEventSeq: -1 }, /sourceEventSeq/],
+    [{ kind: 'success', sourceEventSeq: 1.5 }, /sourceEventSeq/],
+    [{ kind: 'success', sourceEventSeq: '1' }, /sourceEventSeq/],
     [{ kind: 'error', text: '' }, /error text/],
     [{ kind: 'error', text: 1 }, /error text/],
     [{ kind: 'future', text: 'x' }, /unknown result kind/],
diff --git a/packages/ui/commands/tests/invariant.spec.ts b/packages/ui/commands/tests/invariant.spec.ts
new file mode 100644
index 0000000000..8772a3b71e
--- /dev/null
+++ b/packages/ui/commands/tests/invariant.spec.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as CommandInvariant from '@deepseek-ai/dsh-commands/invariant'
+import InvariantService, { InvariantError } from '@deepseek-ai/dsh-invariants'
+import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session'
+import { CommandId } from '@deepseek-ai/dsh-commands'
+
+async function mount(installCompanion = true): Promise<{ ctx: Context; session: Session }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  const session = ctx.sessions.create(SessionId('commands-invariant'))
+  await ctx.plugin(InvariantService, { enabled: true })
+  if (installCompanion) await ctx.plugin(CommandInvariant)
+  return { ctx, session }
+}
+
+function appendRun(session: Session, id: string): void {
+  session.append('command/run', {
+    commandId: CommandId(id),
+    name: 'linked',
+    args: '',
+    source: { kind: 'user' },
+  })
+}
+
+describe('command lifecycle invariants', () => {
+  it('accepts a success outcome linked to an earlier non-command domain event', async () => {
+    const { session } = await mount()
+    const source = session.append('turn/start', { turn: 1 })
+    appendRun(session, 'cmd-valid')
+
+    expect(() => {
+      session.append('command/done', {
+        commandId: CommandId('cmd-valid'),
+        kind: 'success',
+        sourceEventSeq: source.seq,
+      })
+    }).not.toThrow()
+  })
+
+  it.each([-1, 1.5, 1])('rejects invalid or command-owned sourceEventSeq %s', async (sourceEventSeq) => {
+    const { session } = await mount()
+    appendRun(session, 'cmd-invalid')
+
+    expect(() => {
+      session.append('command/done', {
+        commandId: CommandId('cmd-invalid'),
+        kind: 'success',
+        sourceEventSeq,
+      })
+    }).toThrow(expect.objectContaining<Partial<InvariantError>>({
+      code: 'INVARIANT',
+      packageName: '@deepseek-ai/dsh-commands',
+    }))
+  })
+
+  it('rejects an error settlement carrying a success-only source reference', async () => {
+    const { session } = await mount()
+    const source = session.append('turn/start', { turn: 1 })
+    appendRun(session, 'cmd-error-source')
+
+    expect(() => {
+      session.append('command/done', {
+        commandId: CommandId('cmd-error-source'),
+        kind: 'error',
+        text: 'failed',
+        sourceEventSeq: source.seq,
+      })
+    }).toThrow(expect.objectContaining<Partial<InvariantError>>({
+      code: 'INVARIANT',
+      packageName: '@deepseek-ai/dsh-commands',
+    }))
+  })
+
+  it('attributes an invalid durable prefix during late companion loading', async () => {
+    const { ctx, session } = await mount(false)
+    appendRun(session, 'cmd-late')
+    session.append('command/done', {
+      commandId: CommandId('cmd-late'),
+      kind: 'success',
+      sourceEventSeq: 0,
+    })
+
+    await expect(ctx.plugin(CommandInvariant)).rejects.toMatchObject({
+      code: 'INVARIANT',
+      packageName: '@deepseek-ai/dsh-commands',
+    })
+  })
+})

From f32aa54aeb0b526c6c04dd1212cce33e8751afa5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 02:07:11 +0800
Subject: [PATCH 213/516] feat(cli)!: make dsh run the headless entrypoint

---
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |  4 +-
 ...026-07-19-gui-layering-and-rpc-protocol.md |  6 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |  6 +-
 ...026-08-05-profile-plugin-bundles.i18n.yaml |  4 +-
 .../2026-08-05-profile-plugin-bundles.md      |  2 +-
 .../2026-08-05-profile-plugin-bundles.zh.md   |  2 +-
 ...3-cli-signal-shutdown-escalation.i18n.yaml |  4 +-
 ...26-08-03-cli-signal-shutdown-escalation.md |  4 +-
 ...08-03-cli-signal-shutdown-escalation.zh.md |  4 +-
 ...6-08-08-dsh-run-headless-command.i18n.yaml |  6 ++
 .../2026-08-08-dsh-run-headless-command.md    | 39 ++++++++++
 .../2026-08-08-dsh-run-headless-command.zh.md | 39 ++++++++++
 ...3-explicit-config-dsh-entrypoint.i18n.yaml |  2 +-
 ...08-03-explicit-config-dsh-entrypoint.zh.md |  2 +-
 README.i18n.yaml                              |  4 +-
 README.md                                     |  2 +-
 README.zh.md                                  |  2 +-
 apps/cli/README.i18n.yaml                     |  4 +-
 apps/cli/README.md                            |  4 +-
 apps/cli/README.zh.md                         |  4 +-
 apps/cli/reference/README.i18n.yaml           |  4 +-
 apps/cli/reference/README.md                  | 10 ++-
 apps/cli/reference/README.zh.md               | 10 ++-
 apps/cli/src/args.ts                          | 58 ++++++++++-----
 apps/cli/src/bin.ts                           | 11 ++-
 apps/cli/src/profile-boot.ts                  |  6 +-
 apps/cli/tests/args.spec.ts                   | 18 ++++-
 apps/cli/tests/built-bin.e2e.ts               | 44 +++++++++++-
 apps/cli/tests/headless-shutdown.e2e.ts       |  4 +-
 docs/config-catalog.md                        |  2 +-
 .../tests/fixtures/dsh-run.cordis.yml         |  8 +++
 .../headless-agent/tests/headless.snapshot.ts | 65 +++++++++++++++--
 .../snapshots/dsh-run/session.expected.jsonl  | 33 +++++++++
 packages/bundle/headless/README.i18n.yaml     |  4 +-
 packages/bundle/headless/README.md            |  2 +-
 packages/bundle/headless/README.zh.md         |  2 +-
 packages/bundle/headless/src/index.ts         | 25 ++++---
 .../bundle/headless/tests/headless.spec.ts    | 72 ++++++++++++++-----
 packages/host/apiproxy/README.i18n.yaml       |  4 +-
 packages/host/apiproxy/README.md              |  2 +-
 packages/host/apiproxy/README.zh.md           |  2 +-
 41 files changed, 429 insertions(+), 101 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
 create mode 100644 examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
 create mode 100644 examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index bdb07d5f8a..65cbe478ae 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: 34077302c53081f6ee9171d64dce9af342710d71
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: bc51542ac8159ee7cba234b4ee8b4db47a7f9b58
+2026-07-19-gui-layering-and-rpc-protocol.md: 8e020e4fe9b60100671c0cf0e98e28532d850f94
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 55fa8084083aa83fbb4a38f8e41d2e5624b6e58e
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
index 34077302c5..8e020e4fe9 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -10,7 +10,7 @@ English | [中文](2026-07-19-gui-layering-and-rpc-protocol.zh.md)
 
 We need a UI integration layer. Beyond the existing ACP/stdio baseline, more product UI shapes are coming — Web (server), Electron, and others. We call these shapes Clients, uniformly, and want the following capabilities:
 
-- One `dsh` process supporting both `dsh web` (serve) and `dsh -p` (headless) — one process, two modes (a design reservation)
+- One `dsh` process supporting both `dsh web` (serve) and `dsh run` (headless) — one process, two modes (a design reservation)
 - Launching inside Electron with the same Web technology shape as `dsh web`
 
 That demands a stable layered responsibility model in the engineering codebase, so future client shapes plug in cleanly.
@@ -31,7 +31,7 @@ Directories layer as follows:
     - **Fetch-arrival plugin packages** (`ui-layout`, `ui-sidebar`, `ui-conversation`, `ui-trajectory`): dual-entry — the root index is the node half (an empty `apply`, existing so the host Loader governs lifecycle and the web plugin registry discovers the package.json `dshClient` declaration); the implementation lives under `src/client/`, shipped as the `./client` subpath (a tsdown closure-factory bundle). Cross-plugin consumption of `/client` is type-only; value cooperation goes through cordis services.
 - `apps/` holds the externally exported application shapes, assembled from Client / Host mixtures.
     - `apps/web` (`dsh-frontend`) is the vite application: a thin `main.ts` over the shell surface exported by `dsh-client-web`.
-    - `apps/cli` (`@deepseek-ai/dsh`) dispatches shapes: `dsh web` = startHost + webserver + the built `dsh-frontend` dist; `dsh -p` = headless in-process calls, zero HTTP.
+    - `apps/cli` (`@deepseek-ai/dsh`) dispatches shapes: `dsh web` = startHost + webserver + the built `dsh-frontend` dist; `dsh run` = headless in-process calls, zero HTTP.
     - A future Electron shape reuses the same web client packages over an IPC fetch carrier.
 
 ```
@@ -215,7 +215,7 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 
 | Subclass | Package | doFetch | Purpose |
 |---|---|---|---|
-| `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing — `dsh -p` headless is the protocol's second real consumer |
+| `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing — `dsh run` headless is the protocol's second real consumer |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` uplink + one same-origin WebSocket downlink per logical stream | the browser shape; physical boundary in the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | unused (protocol-layer override) | serverless UI development (`?fixture`): overrides the `callUnary`/`openMux`/`openHost`/`respond` virtuals and is itself the fake server (frame rpcIds minted by it, semantics self-consistent) |
 | (future) IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index bc51542ac8..55fa808408 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -9,7 +9,7 @@ Status: implemented
 ## Problem
 
 需要提供 UI 对接层，除已有 ACP/stdio基础版本外，还需要 Web(server) 、 Electron 、等其他产品 UI 形态。我们把这些形态统一称为 Client。希望有如下能力支持:
-- 以 `dsh` 进程，同时支持 `dsh web`(启动) 和 `dsh -p`(headless) ，一个进程两种模式（设计预留）
+- 以 `dsh` 进程，同时支持 `dsh web`(启动) 和 `dsh run`(headless) ，一个进程两种模式（设计预留）
 - 以与 `dsh web` 同构的 Web 技术形态，在 Electron 中启动
 
 那么当前的工程代码需要稳定的分层职责模型，便于以后接入各类 client 形态。
@@ -29,7 +29,7 @@ Status: implemented
     - **fetch 到达插件包**（`ui-layout`、`ui-sidebar`、`ui-conversation`、`ui-trajectory`）：双入口——根入口是 node 半边（空 `apply`，其存在是为了让 host Loader 管辖生命周期、让 web 插件注册表发现 package.json 的 `dshClient` 声明）；实现住在 `src/client/` 下，经 `./client` 子路径发布（tsdown 闭包工厂 bundle）。跨插件消费 `/client` 只限类型；值层面的协作走 cordis 服务。
 - `apps/` 作为对外导出的应用形态入口，可以由 Client / Host 混合组装。
     - `apps/web`（`dsh-frontend`）是 vite 应用：`dsh-client-web` 导出的壳表面之上的一层薄 `main.ts`。
-    - `apps/cli`（`@deepseek-ai/dsh`）做形态分发：`dsh web` = startHost + webserver + 构建出的 `dsh-frontend` dist；`dsh -p` = headless 进程内直调，零 HTTP。
+    - `apps/cli`（`@deepseek-ai/dsh`）做形态分发：`dsh web` = startHost + webserver + 构建出的 `dsh-frontend` dist；`dsh run` = headless 进程内直调，零 HTTP。
     - 将来的 Electron 形态经由 IPC fetch 载体复用同一套 web client 包。
 
 ```
@@ -213,7 +213,7 @@ export type ResponseValue<K> =
 
 | 子类 | 所在包 | doFetch | 用途 |
 |---|---|---|---|
-| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh -p` headless 即协议第二真实消费者 |
+| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh run` headless 即协议第二真实消费者 |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
 | （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，契约/基类零改 |
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index eed6bee5f0..7fa37eeb8e 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.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 .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
-2026-08-05-profile-plugin-bundles.md: 11a8ac3d4005371ca9596ba237aaf42a8e770dee
-2026-08-05-profile-plugin-bundles.zh.md: 0e9ebf657ccb9d05967d90a935b356acf287a24c
+2026-08-05-profile-plugin-bundles.md: b5bf5411d22ab99b598f667886b3c29ba8ee7b06
+2026-08-05-profile-plugin-bundles.zh.md: ae790028b5768c05c57acd27d7f68bdc4d612c11
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
index 11a8ac3d40..b5bf5411d2 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
@@ -12,7 +12,7 @@ The `dsh` launcher hardcoded its compositions: `base.cordis.yml` + `web.cordis.y
 
 Everything becomes a **profile**: a directory `$DSH_HOME/profiles/<name>` with a `package.json` (pnpm-managed out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list) and a user `cordis.patch.yml`. A **bundle** is an npm package declaring `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; the two manifest kinds live under distinct `dsh.profile` / `dsh.bundle` keys so a package.json states which role it plays. The tree composes over an empty root by applying each bundle's patch in `dsh.profile.bundles` order, then the user layer, then `--patch` overlays, then flag patches — one `applyEntryPatches` call, identical for boot, flag derivation, and `--dump-config`.
 
-The shipped compositions became bundles: `@deepseek-ai/dsh-base` (the former base rows as one insert), `@deepseek-ai/dsh-web-app` (the former web overlay plus a runtime glue plugin that owns what used to be launcher code — frontend-dist resolution, the web-surface prompt section, bash runtime variables, the URL line), and `@deepseek-ai/dsh-headless` (a one-shot runner plugin over base + web-app). `dsh web` stays as an alias for `--profile web` carrying the Web flag family; `dsh --profile headless "task"` replaces `-p`; `dsh --config` is removed (its uses migrate to `--patch`). `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` after `add`/`remove` (a bundle-less package warns and stays a plain dependency).
+The shipped compositions became bundles: `@deepseek-ai/dsh-base` (the former base rows as one insert), `@deepseek-ai/dsh-web-app` (the former web overlay plus a runtime glue plugin that owns what used to be launcher code — frontend-dist resolution, the web-surface prompt section, bash runtime variables, the URL line), and `@deepseek-ai/dsh-headless` (a one-shot runner plugin over base + web-app). `dsh web` stays as an alias for `--profile web` carrying the Web flag family; `dsh run [--profile <name>] "task"` owns one-shot execution and defaults to the headless profile, while generic `dsh --profile <name>` boots without a task; `dsh --config` is removed (its uses migrate to `--patch`). `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` after `add`/`remove` (a bundle-less package warns and stays a plain dependency).
 
 Resolution is two-anchored by construction: `dsh.profile.bundles` names resolve from the dsh installation first, then the profile directory — so in-box bundles always come from the same installation as the running `dsh` and pnpm never manages them — while bare plugin names in patch rows resolve through the profile directory's Node parent-walk into the maintained flat fallback `$DSH_HOME/profiles/node_modules` (one symlink per package the installation's app and bundles depend on, healed on every launch).
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index 0e9ebf657c..ae790028b5 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
 
-已交付的组合改造成了组合包：`@deepseek-ai/dsh-base`（原有基础行合并为一次插入）、`@deepseek-ai/dsh-web-app`（原 web overlay，外加一个接管原启动器代码的运行时粘合插件——前端 dist 解析、web 表层提示词段落、bash 运行时变量、URL 行）、`@deepseek-ai/dsh-headless`（叠加在 base + web-app 之上的一次性 runner 插件）。`dsh web` 保留为携带 Web flag 家族的 `--profile web` 别名；`dsh --profile headless "task"` 取代 `-p`；`dsh --config` 被移除（其用途迁移到 `--patch`）。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并在 `add`／`remove` 后调和 `dsh.profile.bundles`（没有组合包声明的包会给出警告，保持为普通依赖）。
+已交付的组合改造成了组合包：`@deepseek-ai/dsh-base`（原有基础行合并为一次插入）、`@deepseek-ai/dsh-web-app`（原 web overlay，外加一个接管原启动器代码的运行时粘合插件——前端 dist 解析、web 表层提示词段落、bash 运行时变量、URL 行）、`@deepseek-ai/dsh-headless`（叠加在 base + web-app 之上的一次性 runner 插件）。`dsh web` 保留为携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile，而通用的 `dsh --profile <name>` 只启动 profile，不携带任务；`dsh --config` 被移除（其用途迁移到 `--patch`）。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并在 `add`／`remove` 后调和 `dsh.profile.bundles`（没有组合包声明的包会给出警告，保持为普通依赖）。
 
 解析在构造上就是双锚点的：`dsh.profile.bundles` 中的名称先从 dsh 安装目录解析，再从 profile 目录解析——因此内置组合包始终来自与运行中 `dsh` 相同的安装，pnpm 从不管理它们——而 patch 行中的裸插件名称经 profile 目录的 Node 父目录逐级查找，落到受维护的扁平回退目录 `$DSH_HOME/profiles/node_modules`（安装目录的应用与各组合包所依赖的每个包各一个符号链接，每次启动时修复）。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
index 59e98bc061..4752010ef6 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.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 .agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
-2026-08-03-cli-signal-shutdown-escalation.md: 2746b5784baad0f3b14258280cd56a621db07c15
-2026-08-03-cli-signal-shutdown-escalation.zh.md: 0bda83327d4cc8fe2edb61f8145a89138610901e
+2026-08-03-cli-signal-shutdown-escalation.md: 7c9715c37ee57be9fa0f67af0c19f0bfa84845da
+2026-08-03-cli-signal-shutdown-escalation.zh.md: f3485edc9e453c0b774f442bfce6d678d63f2224
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
index 2746b5784b..7c9715c37e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
@@ -6,9 +6,9 @@ English | [中文](2026-08-03-cli-signal-shutdown-escalation.zh.md)
 
 ## Problem
 
-The default telemetry mount added SIGINT/SIGTERM handlers to `dsh web` and `dsh -p` so process exit could drain the Cordis tree instead of dropping queued telemetry. Each handler used a one-way boolean latch and exited only after `ctx.fiber.dispose()` settled. Headless normal completion also awaited that disposal without a bound.
+The default telemetry mount added SIGINT/SIGTERM handlers to `dsh web` and the headless command (now `dsh run`) so process exit could drain the Cordis tree instead of dropping queued telemetry. Each handler used a one-way boolean latch and exited only after `ctx.fiber.dispose()` settled. Headless normal completion also awaited that disposal without a bound.
 
-A user then reproduced `dsh -p` hanging immediately after the observation URL and ignoring repeated `Ctrl+C`; `DSH_TELEMETRY_DISABLED=1` removed the hang, while a standalone Node handler in the same Linux sandbox received SIGINT. This isolated the pending disposer to telemetry rather than terminal signal forwarding. OTel's `BatchLogRecordProcessor.shutdown()` awaits `exporter.forceFlush()` before the `exportTimeoutMillis`-bounded completion promise, and the OTLP exporter's `forceFlush()` waits directly on its in-flight HTTP Promise. A proxy/sandbox connection that never obtains a socket can therefore leave provider shutdown pending despite both configured SDK timeouts.
+A user then reproduced the headless command hanging immediately after the observation URL and ignoring repeated `Ctrl+C`; `DSH_TELEMETRY_DISABLED=1` removed the hang, while a standalone Node handler in the same Linux sandbox received SIGINT. This isolated the pending disposer to telemetry rather than terminal signal forwarding. OTel's `BatchLogRecordProcessor.shutdown()` awaits `exporter.forceFlush()` before the `exportTimeoutMillis`-bounded completion promise, and the OTLP exporter's `forceFlush()` waits directly on its in-flight HTTP Promise. A proxy/sandbox connection that never obtains a socket can therefore leave provider shutdown pending despite both configured SDK timeouts.
 
 The latch then turned that telemetry defect into an unkillable CLI: normal completion was already awaiting the single-shot root disposal; the first SIGINT joined the same pending disposal and set the signal latch; later SIGINTs returned at the latch, so the process had no remaining escape. A signal received before normal completion had the same unbounded wait. Web used the same latch shape.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
index 0bda83327d..f3485edc9e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
@@ -6,9 +6,9 @@
 
 ## 问题
 
-默认挂载遥测后，`dsh web` 与 `dsh -p` 新增了 SIGINT/SIGTERM 处理器，使进程退出时可以排空 Cordis 插件树，而不是丢弃排队中的遥测数据。每个处理器都使用单向布尔闩锁（latch），并且只有在 `ctx.fiber.dispose()` 结算后才退出。headless 正常完成时同样会无界等待整棵树执行 dispose（资源释放）。
+默认挂载遥测后，`dsh web` 与 headless 命令（现为 `dsh run`）新增了 SIGINT/SIGTERM 处理器，使进程退出时可以排空 Cordis 插件树，而不是丢弃排队中的遥测数据。每个处理器都使用单向布尔闩锁（latch），并且只有在 `ctx.fiber.dispose()` 结算后才退出。headless 正常完成时同样会无界等待整棵树执行 dispose（资源释放）。
 
-随后有用户复现，`dsh -p` 在打印观察 URL 后立即卡死，重复按 `Ctrl+C` 也没有反应；设置 `DSH_TELEMETRY_DISABLED=1` 后不再卡死，而同一 Linux 沙箱中的独立 Node 信号处理器能够收到 SIGINT。这将待结算的 disposer 定位到遥测，而非终端信号转发。OTel 的 `BatchLogRecordProcessor.shutdown()` 会先等待 `exporter.forceFlush()`，再进入受 `exportTimeoutMillis` 限制的完成 promise；OTLP 导出器的 `forceFlush()` 则直接等待正在进行的 HTTP Promise。因此，代理／沙箱连接始终无法取得 socket 时，即使已经配置两项 SDK 超时，也会让提供方关闭一直待结算。
+随后有用户复现，headless 命令在打印观察 URL 后立即卡死，重复按 `Ctrl+C` 也没有反应；设置 `DSH_TELEMETRY_DISABLED=1` 后不再卡死，而同一 Linux 沙箱中的独立 Node 信号处理器能够收到 SIGINT。这将待结算的 disposer 定位到遥测，而非终端信号转发。OTel 的 `BatchLogRecordProcessor.shutdown()` 会先等待 `exporter.forceFlush()`，再进入受 `exportTimeoutMillis` 限制的完成 promise；OTLP 导出器的 `forceFlush()` 则直接等待正在进行的 HTTP Promise。因此，代理／沙箱连接始终无法取得 socket 时，即使已经配置两项 SDK 超时，也会让提供方关闭一直待结算。
 
 闩锁随后把这个遥测缺陷变成无法终止的 CLI（命令行界面）：正常完成流程已经在等待单次根级 dispose；第一次 SIGINT 会加入同一个待结算的 dispose，并设置信号闩锁；后续 SIGINT 在闩锁处直接返回，因此进程再无退出途径。正常完成之前收到信号时，同样会陷入无界等待。Web 使用的闩锁结构与此相同。
 
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
new file mode 100644
index 0000000000..8d5ec1c9f6
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-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 .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
+2026-08-08-dsh-run-headless-command.md: aac2a473760509626d315df8d57eb405eb547abf
+2026-08-08-dsh-run-headless-command.zh.md: d71d2a34addf1c64b8cb37c54117be5b9c643370
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
new file mode 100644
index 0000000000..aac2a47376
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
@@ -0,0 +1,39 @@
+# Agent Note: `dsh run` owns one-shot headless execution
+
+Status: implemented
+
+English | [中文](2026-08-08-dsh-run-headless-command.zh.md)
+
+## Problem
+
+The product launcher attached optional task text to its generic profile boot: `dsh --profile headless "task"`. That made one argv shape mean either a long-lived profile or a one-shot run according to a row discovered only after composition. The parser's `ProfileInvocation` carried optional task state, help presented a profile implementation detail as the user command, and a custom profile could accept a task only through the same overloaded root.
+
+The former `dsh -p` spelling was already absent from the parser, so restoring it or detecting it specially would add compatibility machinery to a pre-release interface. A separate application-file proposal also used the `run` verb, leaving two incompatible owners for one top-level command.
+
+## Decision
+
+One-shot execution owns an explicit grammar:
+
+```text
+dsh run [--profile <name>] [--patch <path>...] <task...>
+```
+
+`--profile` defaults to `headless` and remains available for custom one-shot compositions. `--patch` is repeatable and occupies the existing overlay layer. Commander joins the variadic task arguments with spaces and rejects a missing or blank task before boot.
+
+`RunInvocation` is a separate `DshInvocation` member. The generic profile invocation no longer carries task text, and its root command accepts no positional arguments. Both dispatch paths call the existing deep `runProfile` module: `profile` omits `task`, while `run` supplies it. There is no shallow `run.ts` forwarding module and no alias, warning, or custom detector for former spellings; they fail through the ordinary Commander grammar. A one-shot profile without `headless-runner` still fails through the existing composed-row check, while booting a profile that contains that row without a task points to `dsh run --profile <name> "<task>"`.
+
+The `run` verb belongs to one-shot task execution. Launching an application file must choose another command name; two top-level meanings selected by positional shape would recreate the ambiguity this command removes.
+
+The runner's user-visible contract stays the same: a fresh persisted session, browser observation URL on stderr, final assistant text on stdout, completed/non-completed exit mapping, and bounded signal shutdown. The product-level keyless acceptance exposed that the in-process mux consumer could lag the same-process `agent/status: idle` notification and derive output before reading the final frames. The idle notification now captures the authoritative final session sequence, and the runner waits until the ordered mux reaches that boundary (or the stream ends) before deriving text and exit reason. This enforces the existing idle-to-idle contract without adding a wire field or a timing delay.
+
+## Alternatives considered
+
+- **Keep task text on `dsh --profile`.** Rejected because profile boot and one-shot execution remain one grammar whose meaning depends on a late composition check.
+- **Preserve `dsh -p` or the positional profile form as aliases.** Rejected under the pre-release stance: compatibility branches would outlive the interface they were meant to retire.
+- **Make `--profile headless` mandatory under `run`.** Rejected because the shipped one-shot surface should have the shortest canonical spelling, while optional `--profile` preserves plugin-defined one-shot compositions.
+- **Give `dsh run` to application-file launch and choose another headless verb.** Rejected because `run` describes executing a task through the harness; application-file ownership would make the product's primary one-shot command less direct and collide with custom one-shot profiles.
+- **Add `apps/cli/src/run.ts`.** Rejected because it would only forward to `runProfile`, splitting command ownership without hiding any complexity.
+
+## Consequences
+
+This is an intentional breaking CLI change. Documentation, help, parser tests, built-bin acceptance, PTY shutdown coverage, and the assembled keyless snapshot use `dsh run`. Existing custom one-shot profiles keep working through `--profile`; long-lived profiles and config dumps retain their existing root grammar. The competing application-file command must be renamed and rebased separately rather than sharing or overloading `run`.
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
new file mode 100644
index 0000000000..d71d2a34ad
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
@@ -0,0 +1,39 @@
+# Agent Note: `dsh run` 负责一次性 headless 执行
+
+Status: implemented
+
+[English](2026-08-08-dsh-run-headless-command.md) | 中文
+
+## 问题
+
+产品启动器过去把可选任务文本挂在通用 profile 启动命令上：`dsh --profile headless "task"`。于是，同一种 argv 形态会表示常驻 profile 或一次性运行，具体含义取决于组合完成后才发现的配置行。解析器的 `ProfileInvocation` 携带可选任务状态，帮助信息把 profile 的实现细节呈现为用户命令，自定义 profile 也只能通过同一个过载的根命令接收任务。
+
+解析器中已经没有原来的 `dsh -p` 写法，因此恢复该写法或加入特殊检测，会给预发布接口增加兼容机制。另一个应用文件提案也使用 `run` 动词，使同一个顶层命令同时归属两个互不兼容的功能。
+
+## 决策
+
+一次性执行采用明确语法：
+
+```text
+dsh run [--profile <name>] [--patch <path>...] <task...>
+```
+
+`--profile` 默认为 `headless`，同时保留对自定义一次性组合的支持。`--patch` 可重复使用，并沿用既有 overlay 层的位置。Commander 用空格拼接可变数量的任务参数，并在启动前拒绝缺失或空白任务。
+
+`RunInvocation` 是单独的 `DshInvocation` 成员。通用 profile 调用不再携带任务文本，其根命令也不接受位置参数。两条分派路径都调用已有的深层 `runProfile` 模块：`profile` 省略 `task`，`run` 则提供该字段。实现中没有只负责转发的浅层 `run.ts` 模块，也没有面向旧写法的别名、警告或自定义检测器；旧写法会按普通 Commander 语法失败。缺少 `headless-runner` 的一次性 profile 仍会触发既有的组合行检查；如果启动的 profile 包含该行却未提供任务，错误会指向 `dsh run --profile <name> "<task>"`。
+
+`run` 动词只负责一次性任务执行。应用文件启动必须选择其他命令名；如果让两个顶层含义由位置参数形态决定，就会重新引入本命令消除的歧义。
+
+运行器面向用户的契约保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 契约。
+
+## 考虑过的替代方案
+
+- **把任务文本保留在 `dsh --profile` 上。** 不予采纳：profile 启动和一次性执行仍共用同一套语法，其含义取决于较晚发生的组合检查。
+- **保留 `dsh -p` 或位置参数 profile 形式作为别名。** 不予采纳：根据预发布立场，这些兼容分支会比本应退役的接口存续更久。
+- **要求在 `run` 下必须指定 `--profile headless`。** 不予采纳：已交付的一次性接口应采用最短的规范写法，同时用可选的 `--profile` 保留插件定义的一次性组合。
+- **把 `dsh run` 交给应用文件启动，并为 headless 选择另一个动词。** 不予采纳：`run` 描述的是通过 harness 执行任务；若归应用文件所有，产品的主要一次性命令会更不直接，并与自定义一次性 profile 冲突。
+- **新增 `apps/cli/src/run.ts`。** 不予采纳：它只会转发到 `runProfile`，拆分命令归属，却没有隐藏任何复杂度。
+
+## 后果
+
+这是一次有意为之的 CLI（命令行界面）破坏性变更。文档、帮助信息、解析器测试、构建后二进制验收、PTY 关闭覆盖和组装应用的无密钥快照都使用 `dsh run`。现有自定义一次性 profile 可继续通过 `--profile` 工作；常驻 profile 和配置 dump 保留既有的根命令语法。与之竞争的应用文件命令必须单独改名并 rebase，不得共享或重载 `run`。
diff --git a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml
index 8ff1af7e8e..ee43f9465c 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
 2026-08-03-explicit-config-dsh-entrypoint.md: e0d1e954d9cef472ea59345a3d2ef5a67bd03ae8
-2026-08-03-explicit-config-dsh-entrypoint.zh.md: b5b464e3b45a6f3909bbf087f7005ad3f819424a
+2026-08-03-explicit-config-dsh-entrypoint.zh.md: 614c2d8600731d85c83d6559bc577350da25e872
diff --git a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md b/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
index b5b464e3b4..614c2d8600 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：显式配置的 dsh 入口
+# Agent Note: 显式配置的 dsh 入口
 
 Status: implemented
 
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 0a7c3e49fe..c4ad1f0fd9 100644
--- a/README.i18n.yaml
+++ b/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write README.md
-README.md: d8d3e767d5a9805f34f4df57a5b1f8ff7fdaa955
-README.zh.md: 89abf8d817deeed2bf4416035790c8696c8c8e33
+README.md: 64f06c0aec0905fa7deabbec0deea61e1c7a40d4
+README.zh.md: fee03118926028833c828809764ebb5f6375259e
diff --git a/README.md b/README.md
index d8d3e767d5..64f06c0aec 100644
--- a/README.md
+++ b/README.md
@@ -56,7 +56,7 @@ The [CLI contract](apps/cli/README.md#profiles) describes profile layout, layer
 Run one task, print the final answer, and exit:
 
 ```sh
-dsh --profile headless "summarize this workspace"
+dsh run "summarize this workspace"
 ```
 
 ### Automation and SDKs
diff --git a/README.zh.md b/README.zh.md
index 89abf8d817..fee0311892 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -56,7 +56,7 @@ profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）
 运行一项任务，打印最终答案后退出：
 
 ```sh
-dsh --profile headless "summarize this workspace"
+dsh run "summarize this workspace"
 ```
 
 ### 自动化与 SDK
diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index cbc74b6d0a..801560e7d7 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/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 apps/cli/README.md
-README.md: f50f26ec5de54e094e17221f7cd355483483754e
-README.zh.md: 242e64a0c42064b9f0b7621e665e85fe44523fe5
+README.md: 12108fcbff4e649d0bcb3e01e688fa334ab91b14
+README.zh.md: 9518feed1d5d40c3e5ec2d346b929118ccc08810
diff --git a/apps/cli/README.md b/apps/cli/README.md
index f50f26ec5d..12108fcbff 100644
--- a/apps/cli/README.md
+++ b/apps/cli/README.md
@@ -9,11 +9,11 @@ The `dsh` command is the product launcher for profiles: ordered stacks of plugin
 | Command | Purpose |
 |---|---|
 | `dsh --profile <name>` | Boot the named profile under `$DSH_HOME/profiles/<name>`. |
-| `dsh --profile headless "task"` | Run one fresh persisted session, print the final answer, and exit. |
+| `dsh run [--profile <name>] [--patch <path>...] "task"` | Run one fresh persisted session, print the final answer, and exit; the profile defaults to `headless`. |
 | `dsh web` | Alias of `--profile web` with the Web flag family (`--host`, `--port`, `--dev`, ...). |
 | `dsh plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
 
-The invoking directory is the default workspace root. The `web` and `headless` profiles auto-initialize on first use from shipped templates; any other profile must be created through `dsh plugin`.
+The invoking directory is the default workspace root. `dsh run` requires non-blank task text and the selected profile must mount the `headless-runner` row; `--profile` preserves custom one-shot profiles. The `web` and `headless` profiles auto-initialize on first use from shipped templates; any other profile must be created through `dsh plugin`.
 
 ## Profiles
 
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 242e64a0c4..9518feed1d 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -9,11 +9,11 @@
 | 命令 | 用途 |
 |---|---|
 | `dsh --profile <name>` | 启动位于 `$DSH_HOME/profiles/<name>` 的指定 profile。 |
-| `dsh --profile headless "task"` | 运行一个新的持久化会话，打印最终答案并退出。 |
+| `dsh run [--profile <name>] [--patch <path>...] "task"` | 运行一个新的持久化会话，打印最终答案并退出；profile 默认为 `headless`。 |
 | `dsh web` | `--profile web` 的别名，附带 Web flag 系列（`--host`、`--port`、`--dev` 等）。 |
 | `dsh plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
 
-调用目录是默认 workspace 根目录。`web` 和 `headless` profile 在首次使用时会从随附模板自动初始化；其他任何 profile 都必须通过 `dsh plugin` 创建。
+调用目录是默认 workspace 根目录。`dsh run` 要求任务文本非空白，且所选 profile 必须挂载 `headless-runner` 行；`--profile` 保留对自定义一次性 profile 的支持。`web` 和 `headless` profile 在首次使用时会从随附模板自动初始化；其他任何 profile 都必须通过 `dsh plugin` 创建。
 
 ## Profile
 
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index e64141c31d..27e391320a 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
-README.md: c7c7b2aa231d4c9f4b3fbf31663237c8457eb051
-README.zh.md: 5439aa78b74415c8e6264d21f5c52e5cee5b38ee
+README.md: 496cecdb64e3254a2a77690f55f760b4cd90b521
+README.zh.md: 4673bf764347307a9b91e2a5474a8439cf67b481
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index c7c7b2aa23..496cecdb64 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-This reference defines the profile, web-alias, plugin-management, and config-dump command modes. Argv is parsed once through [`src/args.ts`](../src/args.ts), and [`src/bin.ts`](../src/bin.ts) dynamically imports only the selected runner.
+This reference defines the profile, one-shot run, web-alias, plugin-management, and config-dump command modes. Argv is parsed once through [`src/args.ts`](../src/args.ts), and [`src/bin.ts`](../src/bin.ts) dynamically imports only the selected runner.
 
 ## Profile boot
 
@@ -12,7 +12,7 @@ Bundle names resolve from the dsh installation first, then from the profile dire
 
 The `web` and `headless` profiles auto-initialize from shipped templates on first use (`web`: base + web-app; `headless`: base + web-app + headless). Any other missing profile fails loud with a hint to run `dsh plugin --profile <name> add <package>`.
 
-A positional task (`dsh --profile headless "run the tests"`) requires the composition to mount the one-shot runner row (`headless-runner`); the launcher patches the task text into that row, the runner drives one fresh persisted session through the in-process API carrier, prints the final assistant text on stdout, and exits 0 on a completed turn, else 1. The session's Web host runs on an OS-assigned port and is announced on stderr, so the run is observable in a browser.
+Profile boot accepts no positional task. A profile that mounts the one-shot runner row (`headless-runner`) therefore fails loud with the canonical `dsh run --profile <name> "<task>"` command instead of reaching the row's raw required-field error.
 
 Inspect the composed tree without booting it:
 
@@ -23,6 +23,12 @@ dsh --profile web --patch ./extra.yml --dump-config
 
 `--dump-default-config` prints only the bundle layers; `--dump-config` adds the profile's `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and `--patch` overlays. Both print provenance comments per layer; `!!js` expressions remain unevaluated, and unmatched patch targets are reported on stderr.
 
+## One-shot run
+
+`dsh run [--profile <name>] [--patch <path>...] <task...>` joins the task arguments with spaces, rejects a missing or blank task, and defaults `--profile` to `headless`. Repeatable `--patch` overlays occupy the same layer position as profile-boot overlays. A custom selected profile must mount `headless-runner`; otherwise launch fails before boot with a diagnostic naming that missing row.
+
+The launcher patches the task text into the runner row, which drives one fresh persisted session through the in-process API carrier, prints the final assistant text on stdout, and exits 0 on a completed turn, else 1. At the idle boundary, the runner waits until its mux consumer has observed the session's final event sequence before deriving that output and exit reason. The session's Web host runs on an OS-assigned port and is announced on stderr, so the run is observable in a browser.
+
 ## Plugin management
 
 `dsh plugin --profile <name> <args...>` initializes the profile when missing (shipped template, or `@deepseek-ai/dsh-base` alone for other names), then forwards `<args...>` to `pnpm` with the profile directory as working directory — `add`, `remove`, `why`, `update`, and every other pnpm verb work unchanged; pnpm must be on PATH. Relative path specs (`.`, `../plugin`, and their `file:`/`link:` forms) are anchored to the invoking directory first, so `add .` from a plugin checkout installs that checkout, not the profile. After every successful run, `dsh.profile.bundles` is reconciled against the installed state: each dependency resolving to a package whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` joins the layer stack (so an `update` that gains the declaration activates it), a bundle-less dependency stays plain with a one-time warning, and a removed dependency leaves the stack.
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index 5439aa78b7..4673bf7643 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本参考定义 profile、web 别名、插件管理和配置 dump 命令模式。参数由 [`src/args.ts`](../src/args.ts) 统一解析，[`src/bin.ts`](../src/bin.ts) 只动态导入选中的运行器。
+本参考定义 profile、一次性运行、web 别名、插件管理和配置 dump 命令模式。参数由 [`src/args.ts`](../src/args.ts) 统一解析，[`src/bin.ts`](../src/bin.ts) 只动态导入选中的运行器。
 
 ## Profile 启动
 
@@ -12,7 +12,7 @@
 
 `web` 和 `headless` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app；`headless`：base + web-app + headless）。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
 
-位置参数任务（`dsh --profile headless "run the tests"`）要求组合挂载一次性运行器行（`headless-runner`）；启动器把任务文本 patch 进该行，运行器通过进程内 API 载体驱动一个全新的持久化会话，在 stdout 打印最终 assistant 文本，并在轮次完成时以 0 退出，否则以 1 退出。会话的 Web 宿主运行在 OS 分配的端口上并公布到 stderr，因此该次运行可在浏览器中观察。
+Profile 启动不接受位置参数任务。因此，挂载了一次性运行器行（`headless-runner`）的 profile 会显式报错，并提示规范命令 `dsh run --profile <name> "<task>"`，而不会触发该行原始的必填字段错误。
 
 可在不启动的情况下检查组合出的配置树：
 
@@ -23,6 +23,12 @@ dsh --profile web --patch ./extra.yml --dump-config
 
 `--dump-default-config` 只打印组合包各层；`--dump-config` 额外加上 profile 的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 和 `--patch` overlay。两者都会按层打印来源注释；`!!js` 表达式保持未求值，找不到目标的 patch 会报告到 stderr。
 
+## 一次性运行
+
+`dsh run [--profile <name>] [--patch <path>...] <task...>` 会用空格拼接任务参数，拒绝缺失或空白任务，并让 `--profile` 默认为 `headless`。可重复使用的 `--patch` overlay 与 profile 启动的 overlay 位于同一层。所选的自定义 profile 必须挂载 `headless-runner`；否则启动器会在启动前失败，并在诊断中指明缺少该行。
+
+启动器把任务文本 patch 进运行器行，运行器再通过进程内 API 载体驱动一个全新的持久化会话，在 stdout 打印最终 assistant 文本，并在轮次完成时以 0 退出，否则以 1 退出。到达 idle 边界时，运行器会等到 mux 消费方观察到会话的最终事件序号，再生成输出与退出原因。会话的 Web 宿主运行在 OS 分配的端口上并公布到 stderr，因此该次运行可在浏览器中观察。
+
 ## 插件管理
 
 `dsh plugin --profile <name> <args...>` 在 profile 缺失时先初始化它（有随附模板的用模板，其他名称只装 `@deepseek-ai/dsh-base`），然后以 profile 目录为工作目录，把 `<args...>` 转发给 `pnpm`：`add`、`remove`、`why`、`update` 及其他所有 pnpm 子命令都照常可用；pnpm 必须在 PATH 上。相对路径 spec（`.`、`../plugin` 及其 `file:`/`link:` 形式）会先锚定到调用目录，因此在插件 checkout 中执行 `add .` 安装的是该 checkout，而不是 profile。每次成功运行后，`dsh.profile.bundles` 都会与已安装状态对齐：每个解析到 manifest 中声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的包的依赖加入层栈（因此让包获得该声明的 `update` 会将其激活），没有组合包声明的依赖保持为普通依赖并给出一次性警告，已移除的依赖则退出层栈。
diff --git a/apps/cli/src/args.ts b/apps/cli/src/args.ts
index 310b5b03a2..0b72f76c6a 100644
--- a/apps/cli/src/args.ts
+++ b/apps/cli/src/args.ts
@@ -1,10 +1,10 @@
 /**
  * Commander adapter for the `dsh` command-line entry. The default command
  * boots a named profile (`--profile <name>`), optionally with extra `--patch`
- * overlays and a positional task (one-shot mode for profiles mounting the
- * headless runner). `web` is a hardcoded alias for `--profile web` that adds
- * the Web flag family; `plugin` manages a profile's plugin dependencies by
- * forwarding to pnpm. Commander owns help, version, and parse errors.
+ * overlays. `run` owns one-shot task execution, defaulting to the headless
+ * profile; `web` is a hardcoded alias for `--profile web` that adds the Web
+ * flag family; `plugin` manages a profile's plugin dependencies by forwarding
+ * to pnpm. Commander owns help, version, and parse errors.
  * @module @deepseek-ai/dsh/args
  */
 
@@ -16,8 +16,16 @@ interface ProfileInvocation {
   profile: string
   /** Extra patch-list overlays applied after the profile's own layer, in argv order. */
   patches: string[]
-  /** Positional task text joined by spaces; non-empty only for one-shot runs. */
-  task?: string
+}
+
+/** Run one task through a profile mounting the headless runner. */
+interface RunInvocation {
+  mode: 'run'
+  profile: string
+  /** Extra patch-list overlays applied after the profile's own layer, in argv order. */
+  patches: string[]
+  /** Non-blank task text joined from the variadic positional arguments. */
+  task: string
 }
 
 /** Print a composed profile tree and exit without booting. */
@@ -54,7 +62,7 @@ interface PluginInvocation {
 }
 
 /** The resolved `dsh` invocation. Help, version, and errors exit inside {@link parseDshArgs}. */
-export type DshInvocation = ProfileInvocation | DumpConfigInvocation | WebInvocation | PluginInvocation
+export type DshInvocation = ProfileInvocation | RunInvocation | DumpConfigInvocation | WebInvocation | PluginInvocation
 
 /** Raw web-subcommand options straight from Commander. */
 interface WebOptions {
@@ -68,6 +76,12 @@ interface WebOptions {
   dumpDefaultConfig?: boolean
 }
 
+/** Raw run-subcommand options straight from Commander. */
+interface RunOptions {
+  profile?: string
+  patch?: string[]
+}
+
 /**
  * Repeatable single-value collector: `--patch a.yml --patch b.yml`. Never
  * variadic — a variadic `--patch` would swallow a following positional task.
@@ -90,19 +104,19 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
     .addHelpText('after', `
 Examples:
   dsh --profile web                          boot the web profile (same as: dsh web)
-  dsh --profile headless "run the tests"     answer one task, print the result, and exit
+  dsh run "run the tests"                    answer one task, print the result, and exit
+  dsh run --profile custom "run the tests"   run one task through a custom one-shot profile
   dsh --profile tui --patch ./extra.yml      boot a custom profile with one extra overlay
   dsh plugin --profile tui add <package>     install a plugin into the tui profile
   dsh web --port 8080                        the web alias with its flag family
 `)
     .exitOverride()
     .enablePositionalOptions()
-    .argument('[task...]', 'one-shot task text for profiles mounting the headless runner')
     .option('--profile <name>', 'the profile under $DSH_HOME/profiles to boot')
     .option('--patch <path>', 'extra patch-list overlay applied after the profile layer (repeatable)', collect)
     .option('--dump-config', 'print the composed profile tree and exit')
     .option('--dump-default-config', 'print the profile tree without its user layer or --patch overlays and exit')
-    .action((task: string[], options: {
+    .action((options: {
       profile?: string
       patch?: string[]
       dumpConfig?: boolean
@@ -116,7 +130,6 @@ Examples:
         if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
           program.error('error: --dump-config and --dump-default-config are mutually exclusive')
         }
-        if (task.length > 0) program.error('error: --dump-config/--dump-default-config take no task')
         const defaultOnly = options.dumpDefaultConfig === true
         if (defaultOnly && patches.length > 0) {
           program.error('error: --dump-default-config prints the bundle layers and takes no --patch')
@@ -124,12 +137,7 @@ Examples:
         resolved = { mode: 'dump-config', profile, defaultOnly, patches }
         return
       }
-      resolved = {
-        mode: 'profile',
-        profile,
-        patches,
-        ...task.length > 0 ? { task: task.join(' ') } : {},
-      }
+      resolved = { mode: 'profile', profile, patches }
     })
 
   /** Reject parent options that crossed a subcommand boundary. */
@@ -146,6 +154,22 @@ Examples:
     }
   }
 
+  const run = program.command('run').description('run one task through a profile mounting the headless runner')
+  run
+    .option('--profile <name>', 'one-shot profile under $DSH_HOME/profiles', 'headless')
+    .option('--patch <path>', 'extra patch-list overlay applied after the profile layer (repeatable)', collect)
+    .argument('<task...>', 'task text')
+    .action((task: string[], options: RunOptions) => {
+      rejectParentOptions('run')
+      const profile = options.profile ?? 'headless'
+      if (profile === '') program.error('error: --profile needs a name')
+      const patches = options.patch ?? []
+      if (patches.includes('')) program.error('error: --patch needs a path')
+      const joined = task.join(' ')
+      if (joined.trim() === '') program.error('error: run needs a non-blank task')
+      resolved = { mode: 'run', profile, patches, task: joined }
+    })
+
   const web = program.command('web').description('serve the browser UI (alias of --profile web) on the configured host and port')
   web
     .option('--patch <path>', 'extra patch-list overlay applied after the profile layer (repeatable)', collect)
diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts
index 4a209b2796..b332a64615 100644
--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -33,7 +33,16 @@ switch (invocation.mode) {
       environment: loadLayeredEnv('dsh'),
       profile: invocation.profile,
       patchFiles: invocation.patches,
-      ...invocation.task !== undefined && { task: invocation.task },
+    })
+    break
+  }
+  case 'run': {
+    const { runProfile } = await import('./profile-boot.ts')
+    await runProfile({
+      environment: loadLayeredEnv('dsh'),
+      profile: invocation.profile,
+      patchFiles: invocation.patches,
+      task: invocation.task,
     })
     break
   }
diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts
index 742bf29db4..4730ec7073 100644
--- a/apps/cli/src/profile-boot.ts
+++ b/apps/cli/src/profile-boot.ts
@@ -47,7 +47,7 @@ export const INSTALL_ANCHOR = fileURLToPath(new URL('../package.json', import.me
 /** The session-telemetry row id the DSH_TELEMETRY_DISABLED switch targets. */
 const TELEMETRY_ROW_ID = 'telemetry-otel'
 
-/** The one-shot runner row a positional task requires and configures. */
+/** The one-shot runner row a `dsh run` task requires and configures. */
 const HEADLESS_ROW_ID = 'headless-runner'
 
 /** The empty root entry list every profile tree patches over. */
@@ -160,7 +160,7 @@ export interface RunProfileOptions {
   patchFiles: readonly string[]
   /** Launcher hook turning the pre-flag composed rows into flag patches (the web alias's flag family). */
   deriveFlagPatches?: (rows: ProfileRows) => PatchOptions[]
-  /** One-shot task text; requires the composition to mount the headless runner row. */
+  /** `dsh run` task text; requires the composition to mount the headless runner row. */
   task?: string
   /** Surface setup registered after Loader installation and before any config-tree entry mounts. */
   prepare?: (ctx: Context, rows: ProfileRows) => Promise<void> | void
@@ -190,7 +190,7 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
     // error naming no fix.
     throw new Error(
       `dsh: profile ${JSON.stringify(options.profile)} mounts the one-shot runner and needs a task: `
-      + `dsh --profile ${options.profile} "<task>"`,
+      + `dsh run --profile ${options.profile} "<task>"`,
     )
   }
 
diff --git a/apps/cli/tests/args.spec.ts b/apps/cli/tests/args.spec.ts
index 93bfb62cc6..c9b3dc18f1 100644
--- a/apps/cli/tests/args.spec.ts
+++ b/apps/cli/tests/args.spec.ts
@@ -21,12 +21,16 @@ function exitCode(argv: string[]): number {
 afterEach(() => { vi.restoreAllMocks() })
 
 describe('parseDshArgs', () => {
-  it('routes profile boots, one-shot tasks, and the web alias', () => {
+  it('routes profile boots, one-shot runs, and the web alias', () => {
     expect(parse(['--profile', 'tui'])).toEqual({ mode: 'profile', profile: 'tui', patches: [] })
-    expect(parse(['--profile', 'headless', 'run', 'the', 'tests']))
-      .toEqual({ mode: 'profile', profile: 'headless', patches: [], task: 'run the tests' })
     expect(parse(['--profile', 'tui', '--patch', 'a.yml', '--patch', 'b.yml']))
       .toEqual({ mode: 'profile', profile: 'tui', patches: ['a.yml', 'b.yml'] })
+    expect(parse(['run', 'run', 'the', 'tests']))
+      .toEqual({ mode: 'run', profile: 'headless', patches: [], task: 'run the tests' })
+    expect(parse(['run', '--profile', 'custom', '--patch', 'a.yml', '--patch', 'b.yml', 'run', 'the', 'tests']))
+      .toEqual({ mode: 'run', profile: 'custom', patches: ['a.yml', 'b.yml'], task: 'run the tests' })
+    expect(parse(['run', '--', '--profile', 'is', 'task', 'text']))
+      .toEqual({ mode: 'run', profile: 'headless', patches: [], task: '--profile is task text' })
     expect(parse(['web'])).toEqual({ mode: 'web', dev: false, patches: [] })
     expect(parse(['web', '--patch', 'web.yml'])).toEqual({ mode: 'web', dev: false, patches: ['web.yml'] })
     expect(parse(['web', '--host', '0.0.0.0', '--port', '8080', '--dev', '--workspace-root', '/w']))
@@ -65,6 +69,13 @@ describe('parseDshArgs', () => {
     expect(exitCode(['tui'])).toBe(1) // a bare word is a task without --profile
     expect(exitCode(['--config', 'c.yml'])).toBe(1) // removed
     expect(exitCode(['-p', 'task'])).toBe(1) // removed
+    expect(exitCode(['--profile', 'headless', 'task'])).toBe(1) // tasks belong to `run`
+    expect(exitCode(['run'])).toBe(1)
+    expect(exitCode(['run', ''])).toBe(1)
+    expect(exitCode(['run', '--profile', '', 'task'])).toBe(1)
+    expect(exitCode(['run', '--patch=', 'task'])).toBe(1)
+    expect(exitCode(['--profile', 'headless', 'run', 'task'])).toBe(1)
+    expect(exitCode(['--patch', 'parent.yml', 'run', 'task'])).toBe(1)
     expect(exitCode(['--profile', ''])).toBe(1)
     expect(exitCode(['--profile', 'x', '--patch='])).toBe(1)
     expect(exitCode(['--dump-config'])).toBe(1)
@@ -90,6 +101,7 @@ describe('parseDshArgs', () => {
 
   it('exits 0 for help and version', () => {
     expect(exitCode(['--help'])).toBe(0)
+    expect(exitCode(['run', '--help'])).toBe(0)
     expect(exitCode(['--version'])).toBe(0)
   })
 })
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index 20ed3fb160..a42780581f 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -182,14 +182,56 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     const help = await runBuiltBin(['--help'])
     expect(help.code).toBe(0)
     expect(help.stdout).toContain('dsh --profile web')
+    expect(help.stdout).toContain('dsh run "run the tests"')
     expect(help.stdout).toContain('dsh plugin --profile')
     expect(help.stdout).not.toMatch(/^\s+(?:tui|meta|upgrade)\b/mu)
-    for (const removed of [['tui'], ['--config', 'x.yml'], ['-p', 'task']]) {
+    for (const removed of [['tui'], ['--config', 'x.yml'], ['-p', 'task'], ['--profile', 'headless', 'task']]) {
       const result = await runBuiltBin(removed)
       expect(result.code).toBe(1)
     }
   }, 30_000)
 
+  it('prints run help without initializing the selected profile', async () => {
+    const parent = mkdtempSync(join(tmpdir(), 'dsh-run-help-'))
+    const home = join(parent, 'not-created')
+    try {
+      const result = await runBuiltBin(['run', '--help'], { DSH_HOME: home })
+      expect(result.code).toBe(0)
+      expect(result.stderr).toBe('')
+      expect(result.stdout).toContain('Usage: dsh run [options] <task...>')
+      expect(existsSync(home)).toBe(false)
+    } finally {
+      rmSync(parent, { recursive: true, force: true })
+    }
+  })
+
+  it('runs the default headless profile through the published run command', async () => {
+    const apiKey = 'built-dsh-run-key'
+    const server = await startMockLlmServer({
+      sequence: ['success'],
+      apiKey,
+      successText: 'published dsh run reached the mock',
+    })
+    const home = mkdtempSync(join(tmpdir(), 'dsh-built-run-'))
+    try {
+      const result = await runBuiltBin(['run', 'answer', 'from', 'the', 'published', 'entry'], {
+        DSH_HOME: home,
+        DSH_TELEMETRY_DISABLED: '1',
+        DEEPSEEK_API_KEY: apiKey,
+        DEEPSEEK_BASE_URL: server.baseURL,
+      })
+      expect(result.code, result.stderr).toBe(0)
+      expect(result.stdout).toBe('published dsh run reached the mock')
+      expect(result.stderr).toMatch(/^dsh: observing at http:\/\/127\.0\.0\.1:\d+$/u)
+      expect(server.requests.length).toBeGreaterThan(0)
+      expect(server.requests.every(request => request.path === '/chat/completions')).toBe(true)
+      expect(JSON.stringify(server.requests.map(request => request.body))).toContain('answer from the published entry')
+    } finally {
+      await server.close()
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, 30_000)
+
   it('does not load a project environment for --version', async () => {
     const project = mkdtempSync(join(tmpdir(), 'dsh-version-project-'))
     writeFileSync(join(project, '.env'), 'PATH=/project-only-path\n')
diff --git a/apps/cli/tests/headless-shutdown.e2e.ts b/apps/cli/tests/headless-shutdown.e2e.ts
index cfa87b03de..237554864c 100644
--- a/apps/cli/tests/headless-shutdown.e2e.ts
+++ b/apps/cli/tests/headless-shutdown.e2e.ts
@@ -66,7 +66,7 @@ async function runHeadlessPtySmoke(): Promise<string> {
   try {
     const home = join(cwd, '.dsh')
     // Pre-initialize the headless profile with the never-dispose row in its
-    // user patch layer (the same file `dsh --profile headless` hot-reloads).
+    // user patch layer (the same file a long-lived profile boot hot-reloads).
     const profileDir = join(home, 'profiles', 'headless')
     await mkdir(profileDir, { recursive: true })
     await writeFile(join(profileDir, 'package.json'), JSON.stringify({
@@ -83,7 +83,7 @@ async function runHeadlessPtySmoke(): Promise<string> {
     ].join('\n'))
     const launch = resolveExampleLaunch({
       srcBin: dshBinScript,
-      configArgs: ['--profile', 'headless', 'never complete'],
+      configArgs: ['run', 'never complete'],
       tsconfigPath,
       env: {
         DSH_HOME: home,
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 42c2f52565..eda24bb29f 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -509,7 +509,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/bundle/headless/src/index.ts:33`](../packages/bundle/headless/src/index.ts)
+Source: [`packages/bundle/headless/src/index.ts:32`](../packages/bundle/headless/src/index.ts)
 
 ## `@deepseek-ai/dsh-hooks-claude`
 
diff --git a/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml b/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
new file mode 100644
index 0000000000..e67630c029
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
@@ -0,0 +1,8 @@
+- id: api-gateway
+  config:
+    provider: cli-mock
+    model: cli-mock
+
+- insert:
+    - id: cli-mock-llm
+      name: !!js process.env.DSH_RUN_MOCK_PLUGIN_URL
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index f9cb46111a..9145c52f5a 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -2,7 +2,7 @@ import { readFile, readdir, writeFile } from 'node:fs/promises'
 import { createServer } from 'node:http'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { delimiter, dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import {
   normalizeSessionLog,
   normalizeStdout,
@@ -14,6 +14,10 @@ import {
   type NormalizeContext,
 } from '@deepseek-ai/dsh-acp-snapshot'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+import {
+  decompressZstdFrame,
+  scanZstdFrames,
+} from '@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts'
 import { describe, expect, it } from 'vitest'
 
 const snapshotsDir = join(dirname(fileURLToPath(import.meta.url)), 'snapshots')
@@ -44,9 +48,15 @@ const ralphConfigPath = fileURLToPath(new URL('../ralph.cordis.snapshot.yml', im
 const startupFailureConfigPath = fileURLToPath(new URL('./fixtures/startup-activation-error/cordis.yml', import.meta.url))
 const startupFailureExpected = join(snapshotsDir, 'startup-activation-error', 'stderr.expected.txt')
 const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const dshBinScript = fileURLToPath(new URL('../../../apps/cli/src/bin.ts', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 const reasoningConfigPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', import.meta.url))
 const deepseekDefaultsConfigPath = fileURLToPath(new URL('./fixtures/deepseek-defaults.cordis.yml', import.meta.url))
+const dshRunOverlayPath = fileURLToPath(new URL('./fixtures/dsh-run.cordis.yml', import.meta.url))
+const dshRunSessionExpected = join(snapshotsDir, 'dsh-run', 'session.expected.jsonl')
+const cliMockLlmPluginUrl = pathToFileURL(
+  fileURLToPath(new URL('./fixtures/cli-mock-llm.ts', import.meta.url)),
+).href
 const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
 
 interface JsonObject {
@@ -167,16 +177,61 @@ async function scenarioPrompt(dir: string, label: string): Promise<string> {
   return prompt
 }
 
-async function persistedLogs(cwd: string): Promise<PersistedLog[]> {
-  const root = join(cwd, '.sessions')
-  const files = (await readdir(root, { recursive: true })).filter(file => file.endsWith('.jsonl'))
+async function readPersistedLog(file: string): Promise<string> {
+  const content = await readFile(file)
+  if (!file.endsWith('.zstd')) return content.toString('utf8')
+  const scan = scanZstdFrames(content)
+  if (scan.tornStart !== undefined) throw new Error(`persisted snapshot log has a torn Zstandard frame: ${file}`)
+  const decoded: Buffer[] = []
+  for (const frame of scan.frames) {
+    decoded.push(await decompressZstdFrame(content.subarray(frame.start, frame.end)))
+  }
+  return Buffer.concat(decoded).toString('utf8')
+}
+
+async function persistedLogs(cwd: string, root: string = join(cwd, '.sessions')): Promise<PersistedLog[]> {
+  const files = (await readdir(root, { recursive: true }))
+    .filter(file => file.endsWith('.jsonl') || file.endsWith('.jsonl.zstd'))
   return Promise.all(files.map(async (file) => {
-    const content = await readFile(join(root, file), 'utf8')
+    const content = await readPersistedLog(join(root, file))
     return { content, header: parseJsonl(content)[0] ?? {} }
   }))
 }
 
 describe('headless stream-json snapshots', () => {
+  it('runs one task through the product dsh run command', async () => {
+    const task = 'Prove the product dsh run path with one real tool round trip.'
+    const result = await runLoaderSmoke({
+      label: 'product dsh run snapshot',
+      tempDirPrefix: 'headless-snapshot-dsh-run-',
+      binScript: dshBinScript,
+      configPath: dshRunOverlayPath,
+      binArgs: ['run', '--patch', dshRunOverlayPath, task],
+      tsconfigPath,
+      env: {
+        DSH_RUN_MOCK_PLUGIN_URL: cliMockLlmPluginUrl,
+        DSH_PERMISSION_MODE: 'danger-full-access',
+        DSH_TELEMETRY_DISABLED: '1',
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      inspect: async (cwd) => {
+        const logs = await persistedLogs(cwd, join(cwd, '.dsh', 'sessions'))
+        expect(logs).toHaveLength(1)
+        const actual = logs[0]
+        if (actual === undefined) throw new Error('dsh run did not persist its session')
+        const context = contextFromLogs([actual.content])
+        const session = scrubRequestHeaders(normalizeSessionLog(actual.content, context))
+        if (refreshing) await writeFile(dshRunSessionExpected, session)
+        expect(session).toBe(await readFile(dshRunSessionExpected, 'utf8'))
+        expect(session).toContain(task)
+        expect(session).toContain('CLI tool round trip complete: CLI_TOOL_ROUND_TRIP')
+      },
+    })
+
+    expect(result.stdout).toBe('CLI tool round trip complete: CLI_TOOL_ROUND_TRIP\n')
+    expect(result.stderr).toMatch(/^dsh: observing at http:\/\/127\.0\.0\.1:\d+\n$/u)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
   it('prints the original Loader activation error through the assembled one-shot app', async () => {
     const result = await runLoaderSmoke({
       label: 'headless startup activation error snapshot',
diff --git a/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl b/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl
new file mode 100644
index 0000000000..1312eb6511
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl
@@ -0,0 +1,33 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"permission/preset","seq":0,"time":0,"data":{"preset":"danger-full-access"}}
+{"type":"sandbox/mode","seq":1,"time":0,"data":{"mode":"danger-full-access"}}
+{"type":"approval/policy","seq":2,"time":0,"data":{"policy":"never"}}
+{"type":"agent/inbox/spliced","seq":3,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user","rpcId":"{{sessionId}}"},"role":"user","id":"{{sessionId}}"}]}}
+{"type":"turn/start","seq":4,"time":0,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":5,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":6,"time":0,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":7,"time":0,"data":{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user","rpcId":"{{sessionId}}"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":8,"time":0,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"session/title","seq":9,"time":0,"data":{"title":"Prove the product dsh run","messageSeqs":[7],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":10,"time":0,"data":{"header":{"config":{"provider":"cli-mock","model":"cli-mock","reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","seq":11,"time":0,"data":{"provider":"cli-mock","model":"cli-mock"}}
+{"type":"session/title-llm-request","seq":12,"time":0,"data":{"titleProvider":"session-title-first-message-llm","messageSeqs":[7],"route":{"provider":"cli-mock","model":"cli-mock"},"system":"Create a concise title for an AI coding-assistant session from the supplied human messages.\nReturn only the title on one line, **in plain text of natural language**, with no quotes, prefix, explanation, Markdown, XML, or terminal control codes. No code is allowed.\nUse the language of the messages.\nAim for about 5 words in non-CJK languages or 10 CJK characters.","messages":[{"content":[{"type":"text","text":"Generate the session title from this JSON array of human messages:\n[{\"seq\":7,\"text\":\"Prove the product dsh run path with one real tool round trip.\"}]"}],"source":{"kind":"plugin","plugin":"dsh-session-title-llm"},"role":"user","id":"{{sessionId}}"}],"maxTokens":64}}
+{"type":"assistant/chunk","seq":13,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"cli-smoke-call","name":"bash","argumentsDelta":"{\"command\":\"printf CLI_TOOL_ROUND_TRIP\",\"description\":\"Prove the CLI tool round trip.\"}"}}}
+{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"cli-smoke-call","name":"bash","arguments":"{\"command\":\"printf CLI_TOOL_ROUND_TRIP\",\"description\":\"Prove the CLI tool round trip.\"}"}}}}
+{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":11,"outputTokens":3,"cacheReadTokens":2}}}}
+{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":18,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"cli-smoke-call","name":"bash","arguments":"{\"command\":\"printf CLI_TOOL_ROUND_TRIP\",\"description\":\"Prove the CLI tool round trip.\"}"}],"source":{"kind":"model","provider":"cli-mock","model":"cli-mock"},"id":"{{sessionId}}"},"usage":{"inputTokens":11,"outputTokens":3,"cacheReadTokens":2}},"sourceEventSeqs":[13,14,15,16,17],"surfaceOp":"append"}
+{"type":"tool/call","seq":19,"time":0,"data":{"turn":1,"step":1,"callId":"cli-smoke-call","name":"bash","arguments":"{\"command\":\"printf CLI_TOOL_ROUND_TRIP\",\"description\":\"Prove the CLI tool round trip.\"}"}}
+{"type":"tool/result","seq":20,"time":0,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"cli-smoke-call"},"content":[{"type":"tool-result","toolCallId":"cli-smoke-call","content":[{"type":"text","text":"CLI_TOOL_ROUND_TRIP"}],"isError":false}],"role":"user","id":"{{sessionId}}"}},"sourceEventSeqs":[19],"surfaceOp":"append"}
+{"type":"step/end","seq":21,"time":0,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":22,"time":0,"data":{"turn":1,"step":2}}
+{"type":"request/header","seq":23,"time":0,"data":{"header":{"config":{"provider":"cli-mock","model":"cli-mock","reasoningEffort":"off"},"system":"{{system}}","tools":"{{tools}}"},"reason":"change"}}
+{"type":"assistant/chunk","seq":24,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":25,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"CLI tool round trip complete: CLI_TOOL_ROUND_TRIP"}}}
+{"type":"assistant/chunk","seq":26,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CLI tool round trip complete: CLI_TOOL_ROUND_TRIP"}}}}
+{"type":"assistant/chunk","seq":27,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":7,"outputTokens":5,"reasoningTokens":1}}}}
+{"type":"assistant/chunk","seq":28,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":29,"time":0,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"CLI tool round trip complete: CLI_TOOL_ROUND_TRIP"}],"source":{"kind":"model","provider":"cli-mock","model":"cli-mock"},"id":"{{sessionId}}"},"usage":{"inputTokens":7,"outputTokens":5,"reasoningTokens":1}},"sourceEventSeqs":[24,25,26,27,28],"surfaceOp":"append"}
+{"type":"step/end","seq":30,"time":0,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":31,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/packages/bundle/headless/README.i18n.yaml b/packages/bundle/headless/README.i18n.yaml
index 08e4a5a5b5..f1a9d53be8 100644
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/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/bundle/headless/README.md
-README.md: d08fb08e2aca3c4e5ccd733b37fc415d492974ca
-README.zh.md: 99a64ef04c4fd8fb0c6a979d3f09f1bd98b434a0
+README.md: 661b377817482d22f58f22b573075722646729a2
+README.zh.md: a6b91a8e60fdcc06ba23e07dcb2f4208ea1020f7
diff --git a/packages/bundle/headless/README.md b/packages/bundle/headless/README.md
index d08fb08e2a..661b377817 100644
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md): it moves the webserver to an OS-assigned port (parallel runs never collide), silences the URL line, and inserts this package's `headless-runner` plugin (config `{task}`). The runner drives one task turn through the in-process API carrier (`InProcessApiClient` over `toFetchHandler(ctx.apiProxy)`, so the full wire chain — serialization, zod, SSE framing — really runs), aggregates the turn's final assistant text, writes it to stdout, and requests exit (completed → 0, else 1) through the launcher-provided `ctx.headlessIo` seam. The Web composition stays mounted, so the running session is observable in a browser at the stderr-announced URL. The launcher patches the task text in (`dsh --profile headless "task"`), and fails loud when a task is given to a profile without this row.
+The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md): it moves the webserver to an OS-assigned port (parallel runs never collide), silences the URL line, and inserts this package's `headless-runner` plugin (config `{task}`). The runner drives one task turn through the in-process API carrier (`InProcessApiClient` over `toFetchHandler(ctx.apiProxy)`, so the full wire chain — serialization, zod, SSE framing — really runs), waits at idle until that mux has consumed the session's final event sequence, aggregates the turn's final assistant text, writes it to stdout, and requests exit (completed → 0, else 1) through the launcher-provided `ctx.headlessIo` seam. The Web composition stays mounted, so the running session is observable in a browser at the stderr-announced URL. The launcher patches the task text in (`dsh run "task"`), and fails loud when the selected profile lacks this row.
 
 ## Model Experience
 
diff --git a/packages/bundle/headless/README.zh.md b/packages/bundle/headless/README.zh.md
index 99a64ef04c..a6b91a8e60 100644
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md) 之上：把 webserver 移到 OS 分配的端口（并行运行绝不冲突），关闭 URL 行输出，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。runner 通过进程内 API 载体（架在 `toFetchHandler(ctx.apiProxy)` 之上的 `InProcessApiClient`，因此序列化、zod、SSE（Server-Sent Events）帧封装这整条 wire 链路都会真实运行）驱动一个任务轮次，聚合该轮次最终的 assistant 文本，写到 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（完成 → 0，否则 1）。Web 组合保持挂载，因此运行中的会话可在浏览器中通过 stderr 公告的 URL 观察。启动器把任务文本 patch 进来（`dsh --profile headless "task"`）；如果向没有这一行的 profile 传入任务，则大声失败。
+dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md) 之上：把 webserver 移到 OS 分配的端口（并行运行绝不冲突），关闭 URL 行输出，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。runner 通过进程内 API 载体（架在 `toFetchHandler(ctx.apiProxy)` 之上的 `InProcessApiClient`，因此序列化、zod、SSE（Server-Sent Events）帧封装这整条 wire 链路都会真实运行）驱动一个任务轮次，在 idle 时等待该 mux 消费完会话的最终事件序号，再聚合该轮次最终的 assistant 文本，写到 stdout，并经启动器提供的 `ctx.headlessIo` seam 请求退出（完成 → 0，否则 1）。Web 组合保持挂载，因此运行中的会话可在浏览器中通过 stderr 公告的 URL 观察。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
 
 ## 模型体验
 
diff --git a/packages/bundle/headless/src/index.ts b/packages/bundle/headless/src/index.ts
index 572f11b487..8db505c3ac 100644
--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -6,8 +6,7 @@
  * (InProcessApiClient over toFetchHandler(ctx.apiProxy), so the full wire
  * chain — serialization, zod, SSE framing — really runs), prints the final
  * assistant text at agent quiescence, and exits (completed → 0, else 1). The
- * task text arrives as launcher-patched config
- * (`dsh --profile headless "task"`).
+ * task text arrives as launcher-patched config (`dsh run "task"`).
  * @module @deepseek-ai/dsh-headless
  */
 
@@ -86,26 +85,31 @@ async function unwrap<T>(response: RpcResponse<T>, io: HeadlessIo): Promise<T> {
  * `agent/status` subscription; the stream itself carries no status frame.
  * @param frames - the mux stream opened before the prompt.
  * @param sessionId - the headless session.
- * @param idle - resolves when the agent reaches quiescence.
+ * @param idle - resolves to the final session-event sequence when the agent reaches quiescence.
  * @param io - process-facing effects for stream diagnostics.
  * @returns the aggregated outcome.
  */
 async function consumeUntilIdle(
   frames: AsyncIterable<RpcRequest<MuxFrame>>,
   sessionId: SessionId,
-  idle: Promise<void>,
+  idle: Promise<number>,
   io: HeadlessIo,
 ): Promise<TurnOutcome> {
   let started = false
   let text = ''
   let reason: string = 'error'
-  void (async () => {
+  let observedSeq = -1
+  let resolveProgress: (() => void) | undefined
+  const streamDone = (async () => {
     try {
       for await (const frame of frames) {
         const payload = frame.payload
         if (payload.type === 'stream/error') return
         if (payload.type !== 'session/event' || payload.sessionId !== sessionId) continue
         const event = payload.event
+        observedSeq = event.seq
+        resolveProgress?.()
+        resolveProgress = undefined
         if (event.type === 'turn/start') {
           started = true
           continue
@@ -121,7 +125,12 @@ async function consumeUntilIdle(
       io.stderr.write(`dsh: event stream failed: ${String(error)}\n`)
     }
   })()
-  await idle
+  const streamEnded = streamDone.then(() => 'ended' as const)
+  const idleSeq = await idle
+  while (observedSeq < idleSeq) {
+    const progress = new Promise<'progress'>((resolve) => { resolveProgress = () => { resolve('progress') } })
+    if (await Promise.race([progress, streamEnded]) === 'ended') break
+  }
   return { text, reason }
 }
 
@@ -154,9 +163,9 @@ export function apply(ctx: Context, config: Config): void {
     // port of this runner must replace it with a wire-visible idle signal.
     const abort = new AbortController()
     const frames = api.events.mux({}, abort.signal)
-    const idle = new Promise<void>((resolve) => {
+    const idle = new Promise<number>((resolve) => {
       ctx.on('agent/status', ({ agent, status }) => {
-        if (agent.id === created.sessionId && status === 'idle') resolve()
+        if (agent.id === created.sessionId && status === 'idle') resolve(agent.session.seq - 1)
       })
     })
     const done = consumeUntilIdle(frames, created.sessionId, idle, io)
diff --git a/packages/bundle/headless/tests/headless.spec.ts b/packages/bundle/headless/tests/headless.spec.ts
index 6ff96619ff..9408ee62bf 100644
--- a/packages/bundle/headless/tests/headless.spec.ts
+++ b/packages/bundle/headless/tests/headless.spec.ts
@@ -21,26 +21,45 @@ function stamped(event: ScriptedEvent): ScriptedEvent {
 
 interface RpcShapedRequest { rpcId: string }
 
+interface ScriptedApiOptions {
+  promptFails?: boolean
+  framesAfterPrompt?: boolean
+  onPrompt?: () => void
+}
+
 /** Build a fake apiProxy (echoing rpcIds like the real gateway) whose mux stream replays `events` for the created session. */
-function scriptedApi(events: ScriptedEvent[], options: { promptFails?: boolean } = {}): unknown {
+function scriptedApi(events: ScriptedEvent[], options: ScriptedApiOptions = {}): unknown {
+  let releaseFrames = (): void => {}
+  const framesReady = options.framesAfterPrompt === true
+    ? new Promise<void>((resolve) => { releaseFrames = resolve })
+    : Promise.resolve()
+  const prepared = events.map((event) => {
+    if (event.type === 'stream/error') return { streamError: true } as const
+    const { sessionId = 'S1', ...rest } = event
+    return { streamError: false, sessionId, event: stamped(rest) } as const
+  })
   return {
     sessions: {
       create: (request: RpcShapedRequest) =>
         Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
-      prompt: (request: RpcShapedRequest) => Promise.resolve(options.promptFails === true
-        // A code from the closed wire union: the carrier schema rejects invented codes.
-        ? { rpcId: request.rpcId, result: { ok: false, error: { code: 'agent-busy', message: 'agent is busy', details: { reason: 'test' } } } }
-        : { rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } }),
+      prompt: (request: RpcShapedRequest) => {
+        releaseFrames()
+        options.onPrompt?.()
+        return Promise.resolve(options.promptFails === true
+          // A code from the closed wire union: the carrier schema rejects invented codes.
+          ? { rpcId: request.rpcId, result: { ok: false, error: { code: 'agent-busy', message: 'agent is busy', details: { reason: 'test' } } } }
+          : { rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } })
+      },
     },
     events: {
       mux: async function* () {
-        for (const event of events) {
-          if (event.type === 'stream/error') {
+        await framesReady
+        for (const item of prepared) {
+          if (item.streamError) {
             yield { rpcId: 'e', payload: { type: 'stream/error', error: { code: 'cancelled', message: 'stream broke', details: {} } } }
             continue
           }
-          const { sessionId = 'S1', ...rest } = event
-          yield { rpcId: 'e', payload: { type: 'session/event', sessionId, event: stamped(rest) } }
+          yield { rpcId: 'e', payload: { type: 'session/event', sessionId: item.sessionId, event: item.event } }
         }
       },
     },
@@ -51,7 +70,10 @@ function scriptedApi(events: ScriptedEvent[], options: { promptFails?: boolean }
  * Mount the runner against a scripted API, emit the idle transition after the
  * scripted frames drain, and wait for its exit request.
  */
-async function run(events: ScriptedEvent[], options: { promptFails?: boolean } = {}): Promise<{ code: number; out: string; err: string }> {
+async function run(
+  events: ScriptedEvent[],
+  options: { promptFails?: boolean; framesAfterPrompt?: boolean; idleInPrompt?: boolean } = {},
+): Promise<{ code: number; out: string; err: string }> {
   const ctx = new Context()
   let out = ''
   let err = ''
@@ -63,16 +85,25 @@ async function run(events: ScriptedEvent[], options: { promptFails?: boolean } =
     }
     ctx.provide('headlessIo', io)
   })
-  ctx.provide('apiProxy', scriptedApi(events, options) as never)
+  const emitIdle = (): void => {
+    ctx.emit('agent/status', { agent: { id: 'S1', session: { seq: nextSeq + 1 } } as Agent, status: 'idle' })
+  }
+  ctx.provide('apiProxy', scriptedApi(events, {
+    ...options.promptFails === undefined ? {} : { promptFails: options.promptFails },
+    ...options.framesAfterPrompt === undefined ? {} : { framesAfterPrompt: options.framesAfterPrompt },
+    ...options.idleInPrompt === true ? { onPrompt: emitIdle } : {},
+  }) as never)
   ctx.provide('httpServer', { port: 12345 } as never)
   apply(ctx, { task: 'do the thing' })
   // Quiescence is out of band: give the scripted stream a beat to drain, then
   // flip the agent idle exactly as the loop would. Foreign agents and
   // non-idle transitions must not settle the run.
-  await new Promise(resolve => setTimeout(resolve, 10))
-  ctx.emit('agent/status', { agent: { id: 'OTHER' } as Agent, status: 'idle' })
-  ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'running' })
-  ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'idle' })
+  if (options.idleInPrompt !== true) {
+    await new Promise(resolve => setTimeout(resolve, 10))
+    ctx.emit('agent/status', { agent: { id: 'OTHER' } as Agent, status: 'idle' })
+    ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'running' })
+    emitIdle()
+  }
   const code = await exited
   await ctx.fiber.dispose()
   return { code, out, err }
@@ -106,6 +137,15 @@ describe('headless runner', () => {
     expect(err).toContain('observing at http://127.0.0.1:12345')
   })
 
+  it('consumes through the idle sequence when queued frames arrive after the status transition', async () => {
+    const { code, out } = await run(
+      [messageTurn, text(1, 'race-free answer'), end(1, 'completed')],
+      { framesAfterPrompt: true, idleInPrompt: true },
+    )
+    expect(code).toBe(0)
+    expect(out).toBe('race-free answer\n')
+  })
+
   it('exits 1 when the final turn ends for any other reason', async () => {
     const { code } = await run([messageTurn, end(1, 'aborted')])
     expect(code).toBe(1)
@@ -168,7 +208,7 @@ describe('headless runner', () => {
     ctx.provide('httpServer', { port: 1 } as never)
     apply(ctx, { task: 't' })
     await new Promise(resolve => setTimeout(resolve, 10))
-    ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'idle' })
+    ctx.emit('agent/status', { agent: { id: 'S1', session: { seq: nextSeq + 1 } } as Agent, status: 'idle' })
     expect(await exited).toBe(1)
     expect(err).toContain('event stream failed')
     await ctx.fiber.dispose()
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 961b48dd0b..627f624235 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 5506cbef7b778a870e1e28c3f9fdf1713f89d65f
-README.zh.md: de31f653944097e9b47a966f56c418dc9fa9b1b9
+README.md: a3c9f214690144ec0f39a8690e4fd346f5e315e2
+README.zh.md: aeaf1b29e5a71674c9feedb30b67f9ce11c47340
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 5506cbef7b..a3c9f21469 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -52,7 +52,7 @@ The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-pag
 
 ## Carrier layer (`/client` + root)
 
-`AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh -p` headless.
+`AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh run` headless.
 
 ## Model Experience
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index de31f65394..aeaf1b29e5 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -52,7 +52,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 ## 载体层（`/client` + 根路径）
 
-`AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供 `dsh -p` headless 模式使用。
+`AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供 `dsh run` headless 模式使用。
 
 ## 模型体验
 

From 21c380be52886cd2250878f49e4ff92cfa78f5f8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 02:08:31 +0800
Subject: [PATCH 214/516] docs(agent-notes): archive superseded dsh entrypoint
 decision

---
 .agents/notes/archived/manifest.json                          | 3 +++
 .../2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml       | 4 ++--
 .../2026-08-03-explicit-config-dsh-entrypoint.md              | 1 +
 .../2026-08-03-explicit-config-dsh-entrypoint.zh.md           | 1 +
 .../simplification/2026-08-04-remove-tui-package.i18n.yaml    | 4 ++--
 .../simplification/2026-08-04-remove-tui-package.md           | 2 +-
 .../simplification/2026-08-04-remove-tui-package.zh.md        | 2 +-
 7 files changed, 11 insertions(+), 6 deletions(-)
 rename .agents/notes/{implemented => archived}/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml (68%)
 rename .agents/notes/{implemented => archived}/simplification/2026-08-03-explicit-config-dsh-entrypoint.md (99%)
 rename .agents/notes/{implemented => archived}/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md (99%)

diff --git a/.agents/notes/archived/manifest.json b/.agents/notes/archived/manifest.json
index c46bb59b44..1adde54c7b 100644
--- a/.agents/notes/archived/manifest.json
+++ b/.agents/notes/archived/manifest.json
@@ -376,6 +376,9 @@
     "simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.i18n.yaml": "sha256:531c446f0e95054f8ced17be9a180f8b0a823f7e9d5ce466c94c2f9cff90a111",
     "simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md": "sha256:a35a6372aabdf7cbc211f1bd5820d85d3467c9ed50f84e05caa3339382379ce7",
     "simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md": "sha256:a6ed9530289a783c3d7a1ddb038fba6b7daf7feb773298a57e811791e354d438",
+    "simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml": "sha256:5466161f3fb8f2e8117fe8ff242675cc9fe9ef264d1e29b9bc586891c73c051a",
+    "simplification/2026-08-03-explicit-config-dsh-entrypoint.md": "sha256:f23accae7d05c2e75cb73ec69b492307f1ce7526ecfa9f6b12a621e02fd1a0c3",
+    "simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md": "sha256:a32d2c6ecf748a16a2c35b59cd2da2fda75769e3ab24be6a2e026d8655466db4",
     "testing/2026-06-20-remove-redundant-snapshot-log-expected-output.i18n.yaml": "sha256:4177012c0821a8c22499852ecdf096af56d7263cb91c5d9d1bcd552cc26a3e00",
     "testing/2026-06-20-remove-redundant-snapshot-log-expected-output.md": "sha256:45234e7cc04b6010c6141f8d5924c04547300098f96262d423c50108e7c7011a",
     "testing/2026-06-20-remove-redundant-snapshot-log-expected-output.zh.md": "sha256:15e5a4ad3dee0bb711480cabe45cd97ec37bbdba19c2c2b47d1e9c203b07a48b",
diff --git a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml b/.agents/notes/archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml
similarity index 68%
rename from .agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml
rename to .agents/notes/archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml
index ee43f9465c..b699495f93 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.i18n.yaml
+++ b/.agents/notes/archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.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 .agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
-2026-08-03-explicit-config-dsh-entrypoint.md: e0d1e954d9cef472ea59345a3d2ef5a67bd03ae8
-2026-08-03-explicit-config-dsh-entrypoint.zh.md: 614c2d8600731d85c83d6559bc577350da25e872
+2026-08-03-explicit-config-dsh-entrypoint.md: 4474e786b3a99ff0ee81ac54fcb6eb5aaff5ee04
+2026-08-03-explicit-config-dsh-entrypoint.zh.md: 11b7b27c7560aaa43a9fdcfb12a9a17f9433e619
diff --git a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.md b/.agents/notes/archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
similarity index 99%
rename from .agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
rename to .agents/notes/archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
index e0d1e954d9..4474e786b3 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
+++ b/.agents/notes/archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md
@@ -1,6 +1,7 @@
 # Agent Note: Explicit-config dsh entrypoint
 
 Status: implemented
+Archived: 2026-08-08
 
 English | [中文](2026-08-03-explicit-config-dsh-entrypoint.zh.md)
 
diff --git a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md b/.agents/notes/archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
similarity index 99%
rename from .agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
rename to .agents/notes/archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
index 614c2d8600..11b7b27c75 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
+++ b/.agents/notes/archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 显式配置的 dsh 入口
 
 Status: implemented
+Archived: 2026-08-08
 
 [English](2026-08-03-explicit-config-dsh-entrypoint.md) | 中文
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
index cd1133483c..e71be9bcf0 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
-2026-08-04-remove-tui-package.md: 7f7a0dd86ddd36e940ed8b7d6154185d9740341c
-2026-08-04-remove-tui-package.zh.md: 36cb4b6a5e4eddd152eccee92c913bcca5b7fbae
+2026-08-04-remove-tui-package.md: 1057243c70f6f2775a5d0c5f5eddcb72cbad699e
+2026-08-04-remove-tui-package.zh.md: 0e03d6913aafaa3ce01c0f5732935d2c304c8e0e
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
index 7f7a0dd86d..1057243c70 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
@@ -16,7 +16,7 @@ The `packages/ui/tui` package is deleted without a compatibility package or alia
 
 The SDK run-interface union now contains only `acp` and `embed`. `create-sdk` defaults to ACP, generated templates contain no terminal startup, resume, session-environment, or model-argument branch, and the builtin `ask-user` feature is removed because neither remaining generated interface supplies a `UserInteractionProvider`. Host applications may still mount the provider-neutral `dsh-user-interaction`, `dsh-commands`, and presentation seams directly.
 
-This decision supersedes the reusable-package retention in [the explicit-config `dsh` entrypoint decision](2026-08-03-explicit-config-dsh-entrypoint.md) and the current applicability of the archived TUI implementation notes. Their historical records remain frozen, but they are not authority for the supported package or application inventory.
+This decision supersedes the reusable-package retention in [the explicit-config `dsh` entrypoint decision](../../archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md) and the current applicability of the archived TUI implementation notes. Their historical records remain frozen, but they are not authority for the supported package or application inventory.
 
 This note consolidates the deleted package-only records that could not remain current after removal. The terminal UI had kept session identity visible during long conversations, removed duplicate model labels, attached elapsed timing and phase status to messages, showed workspace and branch context beside the prompt, and conservatively parsed complete XML wrappers for human-readable fallback output. Those choices improved one terminal frontend but do not justify retaining it without a deployment. A future XML fallback must still use a real parser rather than regular expressions.
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
index 36cb4b6a5e..0e03d6913a 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 SDK 的运行接口联合类型现在只包含 `acp` 与 `embed`。`create-sdk` 默认使用 ACP，生成的模板不再包含终端启动、恢复、会话环境或模型参数分支；内置的 `ask-user` 功能也被移除，因为剩余两个生成接口都不提供 `UserInteractionProvider`。宿主应用仍可直接挂载提供方无关的 `dsh-user-interaction`、`dsh-commands` 和呈现 seam。
 
-本决策取代[显式配置 `dsh` 入口决策](2026-08-03-explicit-config-dsh-entrypoint.md)中保留可复用包的决定，也使已归档 TUI 实现记录不再适用于当前状态。这些历史记录继续保持冻结，但不再作为受支持包或应用清单的依据。
+本决策取代[显式配置 `dsh` 入口决策](../../archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md)中保留可复用包的决定，也使已归档 TUI 实现记录不再适用于当前状态。这些历史记录继续保持冻结，但不再作为受支持包或应用清单的依据。
 
 本记录汇总了删除后无法继续保持当前状态的仅限包记录。终端 UI 曾在长对话期间保持会话身份可见、移除重复模型标签、为消息附加耗时与阶段状态、在提示词旁显示 workspace 与分支上下文，并保守地解析完整 XML 包装层，以生成人类可读的回退输出。这些选择改善了一个终端前端，但没有部署时不足以证明应保留它。未来的 XML 回退仍必须使用真实解析器而非正则表达式。
 

From 33a7b1284e490e6445f5212d016070613a85be07 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 02:20:11 +0800
Subject: [PATCH 215/516] test(snapshot): keep dsh run plugin metadata static

---
 .../tests/fixtures/dsh-run.cordis.yml           |  2 +-
 .../headless-agent/tests/headless.snapshot.ts   | 17 +++++++++++------
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml b/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
index e67630c029..7d411f7a0f 100644
--- a/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
@@ -5,4 +5,4 @@
 
 - insert:
     - id: cli-mock-llm
-      name: !!js process.env.DSH_RUN_MOCK_PLUGIN_URL
+      name: './snapshot-fixtures/cli-mock-llm.ts'
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 9145c52f5a..e8561b0196 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -1,8 +1,8 @@
-import { readFile, readdir, writeFile } from 'node:fs/promises'
+import { copyFile, mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
 import { createServer } from 'node:http'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { delimiter, dirname, join } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
+import { fileURLToPath } from 'node:url'
 import {
   normalizeSessionLog,
   normalizeStdout,
@@ -54,9 +54,7 @@ const reasoningConfigPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', i
 const deepseekDefaultsConfigPath = fileURLToPath(new URL('./fixtures/deepseek-defaults.cordis.yml', import.meta.url))
 const dshRunOverlayPath = fileURLToPath(new URL('./fixtures/dsh-run.cordis.yml', import.meta.url))
 const dshRunSessionExpected = join(snapshotsDir, 'dsh-run', 'session.expected.jsonl')
-const cliMockLlmPluginUrl = pathToFileURL(
-  fileURLToPath(new URL('./fixtures/cli-mock-llm.ts', import.meta.url)),
-).href
+const cliMockLlmPluginPath = fileURLToPath(new URL('./fixtures/cli-mock-llm.ts', import.meta.url))
 const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
 
 interface JsonObject {
@@ -209,11 +207,18 @@ describe('headless stream-json snapshots', () => {
       binArgs: ['run', '--patch', dshRunOverlayPath, task],
       tsconfigPath,
       env: {
-        DSH_RUN_MOCK_PLUGIN_URL: cliMockLlmPluginUrl,
         DSH_PERMISSION_MODE: 'danger-full-access',
         DSH_TELEMETRY_DISABLED: '1',
         NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
       },
+      prepare: async (cwd) => {
+        const fixtureDir = join(cwd, '.dsh', 'profiles', 'headless', 'snapshot-fixtures')
+        await mkdir(fixtureDir, { recursive: true })
+        await Promise.all([
+          copyFile(cliMockLlmPluginPath, join(fixtureDir, 'cli-mock-llm.ts')),
+          writeFile(join(fixtureDir, 'package.json'), '{"type":"module"}\n'),
+        ])
+      },
       inspect: async (cwd) => {
         const logs = await persistedLogs(cwd, join(cwd, '.dsh', 'sessions'))
         expect(logs).toHaveLength(1)

From e8ee305b7b68063a9246b8eaf3554d8e0a0052fe Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 02:30:52 +0800
Subject: [PATCH 216/516] test(snapshot): refresh dsh run translation prompt
 fixture

---
 .../translation-prompt-v4/request-response.expected.json      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 0748e762dd..f0a9390b78 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -8,11 +8,11 @@
       },
       {
         "role": "user",
-        "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Install\n\nClone the repository, then run the installer:\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\nThe installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, prompts for a DeepSeek API key, builds the required repository artifacts, and launches the Web UI.\n\nThe default active checkout is `~/.dsh/source/current`, and the launcher is linked into `~/.local/bin`. Re-run the installer to update. [`scripts/install.sh`](scripts/install.sh) owns alternate locations, update mechanics, and recovery options.\n\n## Use DeepSeek Harness\n\n### Web UI\n\nFor the recommended local interface, choose Web UI when the installer finishes. To start it later, or after updating the active checkout, build the repository and run:\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\nThe path above is the installer's default. If you set `DSH_SOURCE` or `DSH_CURRENT`, or reused an existing checkout, replace `~/.dsh/source/current` with that checkout path; see [`scripts/install.sh`](scripts/install.sh) for details. The Web UI is served at `http://127.0.0.1:3080` by default.\n\n### Profiles\n\n`dsh` boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nThe [CLI contract](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh --profile headless \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/cordis/tool-cordis/README.md).\n\n## Community\n\nFollow <a href=\"https://x.com/Deepseekharness\">DeepSeek Harness on Twitter</a> for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently in internal testing.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n"
+        "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Install\n\nClone the repository, then run the installer:\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\nThe installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, prompts for a DeepSeek API key, builds the required repository artifacts, and launches the Web UI.\n\nThe default active checkout is `~/.dsh/source/current`, and the launcher is linked into `~/.local/bin`. Re-run the installer to update. [`scripts/install.sh`](scripts/install.sh) owns alternate locations, update mechanics, and recovery options.\n\n## Use DeepSeek Harness\n\n### Web UI\n\nFor the recommended local interface, choose Web UI when the installer finishes. To start it later, or after updating the active checkout, build the repository and run:\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\nThe path above is the installer's default. If you set `DSH_SOURCE` or `DSH_CURRENT`, or reused an existing checkout, replace `~/.dsh/source/current` with that checkout path; see [`scripts/install.sh`](scripts/install.sh) for details. The Web UI is served at `http://127.0.0.1:3080` by default.\n\n### Profiles\n\n`dsh` boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nThe [CLI contract](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/cordis/tool-cordis/README.md).\n\n## Community\n\nFollow <a href=\"https://x.com/Deepseekharness\">DeepSeek Harness on Twitter</a> for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently in internal testing.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n"
       },
       {
         "role": "assistant",
-        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh --profile headless \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
+        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
       },
       {
         "role": "user",

From a8879430f0407bc12b120d9bc5efcff400ab6175 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 14:20:06 +0800
Subject: [PATCH 217/516] ci: harden private repository link gate

---
 .../verify-public-repository-links.spec.ts    | 21 ++++++++++++----
 scripts/verify-public-repository-links.ts     | 24 ++++++++++++++++++-
 2 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/scripts/verify-public-repository-links.spec.ts b/scripts/verify-public-repository-links.spec.ts
index 615bfa68e2..ec12f38427 100644
--- a/scripts/verify-public-repository-links.spec.ts
+++ b/scripts/verify-public-repository-links.spec.ts
@@ -2,18 +2,31 @@ import { describe, expect, it } from 'vitest'
 import { findInternalRepositoryReferences } from './verify-public-repository-links.ts'
 
 describe('public repository link policy', () => {
-  it('rejects internal repository references and accepts the public home', () => {
+  it('rejects encoded and case-varied internal identities without blocking public repositories', () => {
     const internalOwner = ['deepseek', 'harness'].join('-')
     const internalRepository = [internalOwner, internalOwner].join('/')
+    const encodedRepository = internalRepository.replaceAll('-', '%2D').replace('/', '%2F')
+    const htmlEncodedRepository = internalRepository.replace('/', '&#x2f;')
+    const jsonEscapedRepository = internalRepository.replace('/', '\\/')
+    const unicodeEscapedRepository = internalRepository.replace('/', String.raw`\u002f`)
     const source = [
       'https://github.com/deepseek-ai/deepseek-harness-sdk',
-      `https://github.com/${internalRepository}/issues/1`,
-      `${internalOwner}#2`,
+      `https://github.com/${internalOwner}/cordis`,
+      `https://github.com/${internalRepository.toUpperCase()}/issues/1`,
+      `https://github.com/${encodedRepository}/issues/2`,
+      `https://github.com/${htmlEncodedRepository}/issues/3`,
+      `"https:\\/\\/github.com\\/${jsonEscapedRepository}\\/issues\\/4"`,
+      `"https:\\/\\/github.com\\/${unicodeEscapedRepository}\\/issues\\/5"`,
+      `${internalOwner.toUpperCase()}#6`,
     ].join('\n')
 
     expect(findInternalRepositoryReferences('subject.md', source)).toEqual([
-      { file: 'subject.md', line: 2 },
       { file: 'subject.md', line: 3 },
+      { file: 'subject.md', line: 4 },
+      { file: 'subject.md', line: 5 },
+      { file: 'subject.md', line: 6 },
+      { file: 'subject.md', line: 7 },
+      { file: 'subject.md', line: 8 },
     ])
   })
 })
diff --git a/scripts/verify-public-repository-links.ts b/scripts/verify-public-repository-links.ts
index a57628e00c..6d1e537733 100644
--- a/scripts/verify-public-repository-links.ts
+++ b/scripts/verify-public-repository-links.ts
@@ -10,6 +10,27 @@ const internalOwner = ['deepseek', 'harness'].join('-')
 const internalRepository = [internalOwner, internalOwner].join('/')
 const internalIssueShorthand = `${internalOwner}#`
 
+const namedReferenceCharacters: Readonly<Record<string, string>> = {
+  hyphen: '-',
+  num: '#',
+  sol: '/',
+}
+
+/** Normalize source spellings that render or decode to repository separators. */
+function canonicalReferenceText(source: string): string {
+  return source
+    .replaceAll('\\/', '/')
+    .replace(/\\u(0023|002d|002f)/gi, (_match, code: string) => String.fromCodePoint(Number.parseInt(code, 16)))
+    .replace(/%(23|2d|2f)/gi, (_match, code: string) => String.fromCodePoint(Number.parseInt(code, 16)))
+    .replace(/&#(?:(\d+)|x([\da-f]+));/gi, (entity, decimal: string | undefined, hexadecimal: string | undefined) => {
+      const code = Number.parseInt(decimal ?? hexadecimal ?? '', decimal === undefined ? 16 : 10)
+      return code === 35 || code === 45 || code === 47 ? String.fromCodePoint(code) : entity
+    })
+    .replace(/&(hyphen|num|sol);/gi, (entity, name: string) => namedReferenceCharacters[name.toLowerCase()] ?? entity)
+    .normalize('NFKC')
+    .toLowerCase()
+}
+
 /** One tracked reference to the internal repository. */
 export interface InternalRepositoryReference {
   /** Repository-relative file path. */
@@ -27,7 +48,8 @@ export interface InternalRepositoryReference {
 export function findInternalRepositoryReferences(file: string, source: string): InternalRepositoryReference[] {
   const references: InternalRepositoryReference[] = []
   for (const [index, line] of source.split('\n').entries()) {
-    if (line.includes(internalRepository) || line.includes(internalIssueShorthand)) {
+    const canonicalLine = canonicalReferenceText(line)
+    if (canonicalLine.includes(internalRepository) || canonicalLine.includes(internalIssueShorthand)) {
       references.push({ file, line: index + 1 })
     }
   }

From 63f88997bb796a492b02a322733c2e0c87fc0d5b Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 14:36:03 +0800
Subject: [PATCH 218/516] fix(web): preserve compact icon until hover

---
 .../client/ui-conversation/README.i18n.yaml   |  4 +--
 packages/client/ui-conversation/README.md     |  2 +-
 packages/client/ui-conversation/README.zh.md  |  2 +-
 .../src/client/chat/CompactionItem.tsx        | 13 ++++++--
 .../src/client/chat/MessageItem.module.css    | 33 +++++++++++++++----
 .../ui-conversation/tests/chat-view.spec.tsx  |  3 ++
 6 files changed, 45 insertions(+), 12 deletions(-)

diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index ca3289ba55..d29623d0f2 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 5b37065097ef60c2edf14725f4e1e1c6a52c4366
-README.zh.md: 4ec26155a124497db0fc7f351d20ecb451a18763
+README.md: 985c78e97a8c7f46451252e67095c91e990aa694
+README.zh.md: 36a2f7a13c3f60692f9547ccf5a51ad6356d26d8
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 5b37065097..985c78e97a 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, an animated left-to-right gradient `Deep diving...` turn status, per-tool row slot with a bash sample registrant and the todo row), composer dock (session stats sticky with the input), input dock (hairline-separated queue rows plus the todo plan strip), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares).
 
-Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key, showing the replaced-item and estimated-token counts and disclosing the summary on click. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when summary provenance is outside the loaded window, the checkpoint remains visible but non-expandable.
+Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key, showing the replaced-item and estimated-token counts and disclosing the summary on click. A completed checkpoint keeps the context-compaction icon at rest and replaces it with the collapsed or expanded disclosure only on hover or keyboard focus. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when summary provenance is outside the loaded window, the checkpoint remains visible but non-expandable.
 
 The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 4ec26155a1..36a2f7a13c 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -4,7 +4,7 @@
 
 会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、带从左到右动态渐变的 `Deep diving...` 轮次状态、逐工具行 slot 及一个 bash 示例注册方与 todo 行）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（带发丝分界线的队列行加 todo 计划条）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。
 
-压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行，显示被替换条目数量和估算 token 数量，并可点击展开摘要。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。
+压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行，显示被替换条目数量和估算 token 数量，并可点击展开摘要。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
diff --git a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
index 7049688cc0..5e5f0c87b7 100644
--- a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
@@ -9,6 +9,7 @@
 import { memo, useState } from 'react'
 import type { CompactionSummaryNode } from '@deepseek-ai/dsh-client-runtime/client'
 import {
+  IconApiOutline14,
   IconChevronDownOutline14,
   IconChevronRightOutline14,
   MarkdownText,
@@ -56,8 +57,16 @@ export const CompactionItem = memo(function CompactionItem({
         aria-expanded={expandable ? open : undefined}
         onClick={() => { setExpanded(value => !value) }}
       >
-        <span className={css.compactionLeading}>
-          {open ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
+        <span className={css.compactionLeading} aria-hidden>
+          <span className={css.compactionContextIcon} data-compaction-icon="context">
+            <IconApiOutline14 />
+          </span>
+          <span
+            className={css.compactionDisclosureIcon}
+            data-compaction-disclosure={open ? 'expanded' : 'collapsed'}
+          >
+            {open ? <IconChevronDownOutline14 /> : <IconChevronRightOutline14 />}
+          </span>
         </span>
         <span className={css.compactionTitle}>{title ?? t('message.compaction')}</span>
         <span className={css.compactionSep} aria-hidden />
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
index 5c07ace71e..c6ca35bb2c 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.module.css
@@ -33,9 +33,9 @@
   padding: 2px 0;
 }
 
-/* Compaction marker: one dim 24px row with a chevron disclosure for the
-   summary body. Dimmed title (not label-primary) — the row is a boundary
-   notice, not conversation content. */
+/* Compaction marker: one dim 24px row with a context icon at rest and a
+   hover/focus disclosure for the summary body. Dimmed title (not
+   label-primary) — the row is a boundary notice, not conversation content. */
 .compactionRow {
   padding: 2px 0;
 }
@@ -65,15 +65,36 @@
 
 .compactionLeading {
   flex: none;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
+  display: inline-grid;
+  place-items: center;
   width: 16px;
   height: 16px;
   margin-right: 6px;
   color: var(--dsw-alias-label-secondary);
 }
 
+.compactionContextIcon,
+.compactionDisclosureIcon {
+  display: inline-flex;
+  grid-area: 1 / 1;
+  align-items: center;
+  justify-content: center;
+}
+
+.compactionDisclosureIcon {
+  opacity: 0;
+}
+
+.compactionButton:not(:disabled):hover .compactionContextIcon,
+.compactionButton:not(:disabled):focus-visible .compactionContextIcon {
+  opacity: 0;
+}
+
+.compactionButton:not(:disabled):hover .compactionDisclosureIcon,
+.compactionButton:not(:disabled):focus-visible .compactionDisclosureIcon {
+  opacity: 1;
+}
+
 .compactionTitle {
   flex: none;
   font-size: 14px;
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index a0213a2407..b16a0b9317 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -1303,9 +1303,12 @@ describe('ChatView', () => {
     expect(view.getByText('已压缩 16 条历史记录（约 11309 tokens）')).toBeTruthy()
     const row = view.getByRole('button', { name: /compact/ })
     expect(row.getAttribute('aria-expanded')).toBe('false')
+    expect(row.querySelector('[data-compaction-icon="context"]')).not.toBeNull()
+    expect(row.querySelector('[data-compaction-disclosure="collapsed"]')).not.toBeNull()
     expect(view.queryByText('保留的事实。')).toBeNull()
     fireEvent.click(row)
     expect(row.getAttribute('aria-expanded')).toBe('true')
+    expect(row.querySelector('[data-compaction-disclosure="expanded"]')).not.toBeNull()
     expect(view.getByRole('heading', { name: '压缩摘要' })).toBeTruthy()
   })
 

From 04e6a9806450426203a71e316a3398ee0f358ddd Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 14:42:07 +0800
Subject: [PATCH 219/516] feat(client): surface subagent activity in sidebar

---
 ...07-27-web-subagent-conversations.i18n.yaml |  4 +-
 .../2026-07-27-web-subagent-conversations.md  |  6 +-
 ...026-07-27-web-subagent-conversations.zh.md |  6 +-
 .../sidebar-running.expected.md               |  5 ++
 apps/web/tests/subagent-conversation.e2e.ts   | 10 +++
 packages/client/runtime/README.i18n.yaml      |  4 +-
 packages/client/runtime/README.md             |  2 +
 packages/client/runtime/README.zh.md          |  2 +
 packages/client/runtime/src/client/index.ts   |  2 +
 .../src/client/sessions/subagent-lineage.ts   | 50 +++++++++++
 .../runtime/tests/subagent-lineage.spec.ts    | 53 ++++++++++++
 .../src/client/SubagentCatalogAction.tsx      | 46 +++-------
 packages/client/ui-workspace/README.i18n.yaml |  4 +-
 packages/client/ui-workspace/README.md        |  2 +-
 packages/client/ui-workspace/README.zh.md     |  2 +-
 .../client/ui-workspace/src/client/locales.ts |  4 +
 .../ui-workspace/src/client/rows/Rows.tsx     | 86 +++++++++++++------
 .../client/ui-workspace/src/client/tree.ts    | 25 ++++--
 .../client/ui-workspace/tests/rows.spec.tsx   | 72 +++++++++++++---
 .../client/ui-workspace/tests/tree.spec.ts    | 28 +++++-
 20 files changed, 320 insertions(+), 93 deletions(-)
 create mode 100644 apps/web/tests/snapshots/subagent-conversation/sidebar-running.expected.md
 create mode 100644 packages/client/runtime/src/client/sessions/subagent-lineage.ts
 create mode 100644 packages/client/runtime/tests/subagent-lineage.spec.ts

diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index abb388a410..ac7fc12150 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: 03c805d30dbdbbdb33d0b06ba8036ec181035ac6
-2026-07-27-web-subagent-conversations.zh.md: e83f07fb21f58ad175ab3e5638981648fa4cef05
+2026-07-27-web-subagent-conversations.md: 60717365244ff3ca3ebc4a400b15bfc81062212c
+2026-07-27-web-subagent-conversations.zh.md: 217ed44249c0d1beb731e24e52054f200fae4b9b
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index 03c805d30d..6071736524 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -37,7 +37,7 @@ The Figma [subagent list](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Ha
 
 ## Product contract
 
-The header action is absent only when a complete empty direct-catalog response agrees with the session-summary projection that no subagent descendants are known. Its trigger counts every known session-summary descendant reached through an uninterrupted `origin: 'subagent'` lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. Every healthy direct-catalog row carries a read-time `hasChildren` hint derived only from direct lineage headers with durable `origin: 'subagent'`; normal healthy and diagnostic subagent candidates carry that marker, while ordinary forks do not. This lookahead reads no descendant event log, and the descriptor-backed catalog loaded after disclosure remains authoritative. When summaries establish descendants before that catalog exists or after a stale empty response, the action stays visible and exposes only disabled loading rows until opening it refreshes the catalog; summary-only rows never grant navigation. The UI omits disclosure for a known leaf before interaction; the hint does not promise that the child will remain a leaf. While an expanded direct catalog is loading, known lineage reserves one disabled loading row per direct descendant without recursively fetching descendant catalogs. The tree then presents continuable and one-shot rows, falling back to the session id when an optional one-shot label is absent. Corrupt, unsupported, and unavailable candidates remain visible as disabled diagnostic rows.
+The header action is absent only when a complete empty direct-catalog response agrees with the session-summary projection that no subagent descendants are known. Its trigger counts every known session-summary descendant reached through an uninterrupted `origin: 'subagent'` lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. Because ordinary sidebar rows hide subagent-origin sessions, the Workspace browser indexes the same uninterrupted lineage onto each visible ordinary row: any running descendant supplies its blue activity indicator and exact count in hover and assistive text without describing an idle parent as running. An ordinary fork starts a separate aggregation subtree. Parent running and pending interaction remain distinct primary statuses; descendant activity becomes a second hover and assistive status when either is present. Every healthy direct-catalog row carries a read-time `hasChildren` hint derived only from direct lineage headers with durable `origin: 'subagent'`; normal healthy and diagnostic subagent candidates carry that marker, while ordinary forks do not. This lookahead reads no descendant event log, and the descriptor-backed catalog loaded after disclosure remains authoritative. When summaries establish descendants before that catalog exists or after a stale empty response, the action stays visible and exposes only disabled loading rows until opening it refreshes the catalog; summary-only rows never grant navigation. The UI omits disclosure for a known leaf before interaction; the hint does not promise that the child will remain a leaf. While an expanded direct catalog is loading, known lineage reserves one disabled loading row per direct descendant without recursively fetching descendant catalogs. The tree then presents continuable and one-shot rows, falling back to the session id when an optional one-shot label is absent. Corrupt, unsupported, and unavailable candidates remain visible as disabled diagnostic rows.
 
 `running` means the exact child Agent driver is draining work at the Host sampling boundary; `inactive` means that driver is idle or absent. The UI does not translate either value into success, failure, cancellation, completeness, or resumability. `subagent.list` supplies the current driver-status baseline, `host/session-status` updates known activity in place, request-local replay prevents an older in-flight list response from overwriting a newer transition, and `host/session-removed` returns a known row to `inactive`; reconnect reads a fresh baseline. A `host/session-added` frame for a direct subagent immediately flips any loaded parent row to `hasChildren: true`, and that positive hint survives an older in-flight catalog response; membership, labels, mode, diagnostics, and the authoritative snapshot still require a debounced `subagent.list` refresh while the affected branch is open. A prompt response remains delivery-time authority.
 
@@ -104,8 +104,8 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 - Host protocol tests pin schemas including required boolean expandability, id echoing, mode verification, non-activating history, exact-parent enforcement, FIFO admission receipts, cancellation, and sanitized failure mapping.
 - Generic Host tests pin attached and cold history and forks without Agent publication, cold projection folding, descriptor/origin/runtime-owner denial, explicit-id adoption denial, and the direct queue-control fence.
 - Client object tests pin retained and restored addresses, one-shot read-only rejection, history routing, continuable prompt routing, no addressed cancellation, suppression of Agent-bound model controls, live activity flips including in-flight response replay and detach fallback, subagent-parent expandability flips, and membership refresh.
-- jsdom tests pin the aggregate descendant count and activity, token totals, second-precision running and frozen inactive durations, adaptive long-duration units with exact accessible text, the summary-backed root action across absent and stale-empty catalogs, known loading-row shape, mixed-mode rows, pre-click leaf disclosure, diagnostics, lazy descendant disclosure, direct-parent addresses, keyboard behavior, and both read-only reasons.
-- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, and aggregate running transition, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only.
+- jsdom tests pin the aggregate descendant count and activity, sidebar propagation across nested lineage and ordinary-fork boundaries, row-status precedence, token totals, second-precision running and frozen inactive durations, adaptive long-duration units with exact accessible text, the summary-backed root action across absent and stale-empty catalogs, known loading-row shape, mixed-mode rows, pre-click leaf disclosure, diagnostics, lazy descendant disclosure, direct-parent addresses, keyboard behavior, and both read-only reasons.
+- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, aggregate running transition in the header and owner sidebar row, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only.
 - Navigation tests pin subagent-only breadcrumbs, workspace placement for forks created from subagents, and `origin: 'subagent'` sidebar filtering without hiding ordinary forks.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index e83f07fb21..217ed44249 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -37,7 +37,7 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 ## 产品契约
 
-只有当完整的直接目录空响应与会话摘要投影相符，二者均表明没有已知的 subagent 后代时，才不显示页头操作。其触发器会统计经不间断的 `origin: 'subagent'` 谱系可达的每个已知会话摘要后代，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。每个健康的直接目录行都携带读取时的 `hasChildren` 提示，该值只根据持久化 `origin: 'subagent'` 的直接谱系 header 派生；正常的健康与 diagnostic subagent 候选都会携带该标记，而普通 fork 不会。该预查不读取任何后代事件日志，展开后仍以描述符支撑的目录为权威依据。当摘要在该目录尚不存在时或在一次陈旧的空响应后确认已有后代时，该操作会保持可见，并且在打开它以刷新目录之前仅显示禁用的加载行；仅由摘要支撑的行绝不会提供导航能力。UI 会在交互前就省略已知叶子节点的展开控件；该提示不承诺 child 会一直是叶子。已展开的直接目录加载期间，已知谱系会为每个直接后代预留一行禁用的加载行，而不会递归获取后代目录。随后树会呈现可继续与 one-shot 行；one-shot 的可选 label 缺失时，回退到其会话 id。损坏、不受支持或不可用的候选仍以禁用的 diagnostic 行显示。
+只有当完整的直接目录空响应与会话摘要投影相符，二者均表明没有已知的 subagent 后代时，才不显示页头操作。其触发器会统计经不间断的 `origin: 'subagent'` 谱系可达的每个已知会话摘要后代，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。由于普通侧边栏行会隐藏 origin 为 subagent 的会话，Workspace 浏览器会在每个可见的普通行上索引同一条不间断谱系：任何运行中的后代都会让该行显示蓝色活动指示器，并在悬停与无障碍文本中给出确切数量，同时不会把空闲 parent 描述为正在运行。普通 fork 会开启单独的聚合子树。parent 的运行中状态与待处理交互仍是彼此不同的主要状态；只要其中任一存在，后代活动就成为悬停与无障碍状态中的第二项。每个健康的直接目录行都携带读取时的 `hasChildren` 提示，该值只根据持久化 `origin: 'subagent'` 的直接谱系 header 派生；正常的健康与 diagnostic subagent 候选都会携带该标记，而普通 fork 不会。该预查不读取任何后代事件日志，展开后仍以描述符支撑的目录为权威依据。当摘要在该目录尚不存在时或在一次陈旧的空响应后确认已有后代时，该操作会保持可见，并且在打开它以刷新目录之前仅显示禁用的加载行；仅由摘要支撑的行绝不会提供导航能力。UI 会在交互前就省略已知叶子节点的展开控件；该提示不承诺 child 会一直是叶子。已展开的直接目录加载期间，已知谱系会为每个直接后代预留一行禁用的加载行，而不会递归获取后代目录。随后树会呈现可继续与 one-shot 行；one-shot 的可选 label 缺失时，回退到其会话 id。损坏、不受支持或不可用的候选仍以禁用的 diagnostic 行显示。
 
 `running` 表示在 Host 采样边界，确切 child Agent driver 正在处理工作；`inactive` 表示该 driver 空闲或不存在。UI 不会把任一值解释为成功、失败、取消、完成状态或可恢复性。`subagent.list` 提供当前 driver 状态基线，`host/session-status` 会就地更新已知活动状态，请求内回放会阻止更早发起但尚未完成的列表响应覆盖较新的状态转换，`host/session-removed` 则会使已知行恢复为 `inactive`；重连时会读取新的基线。直接 subagent 的 `host/session-added` 帧会立即把任何已加载的 parent 行翻转为 `hasChildren: true`，并使这项正向提示不被更早发起但尚未完成的目录响应覆盖；受影响分支打开期间，成员、label、mode、diagnostic 与权威快照仍需要通过去抖动的 `subagent.list` 刷新来更新。消息投递时仍以提示词响应为权威依据。
 
@@ -104,8 +104,8 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 - 宿主协议测试固定 schema（包括必需的布尔可展开性）、id 回显、mode 校验、非激活式历史、确切 parent 强制要求、FIFO 准入回执、取消与脱敏后的失败映射。
 - 通用 Host 测试固定在不发布 Agent 的情况下读取已附加与冷态历史及执行 fork、冷态投影归并、按描述符／origin／运行时 owner 拒绝、拒绝显式 id 接纳，以及直接队列控制栅栏。
 - 客户端对象测试固定已保留与已恢复的地址、one-shot 只读拒绝、历史路由、可继续提示词路由、已寻址对话不提供取消、屏蔽绑定到 agent 的模型控件、实时活动状态翻转（包括在途响应回放与 detach 回退）、subagent parent 可展开性翻转与成员刷新。
-- jsdom 测试固定后代聚合计数与活动状态、token 用量总计、精确到秒的运行中耗时与冻结后 inactive 耗时、采用自适应单位的长耗时及其精确无障碍文本、目录缺失或为陈旧空目录时由摘要支撑的根操作、已知加载行的形态、混合 mode 行、点击前的叶子展开控件、diagnostic、后代懒加载展开、直接 parent 地址、键盘行为与两种只读原因。
-- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现以及聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。
+- jsdom 测试固定后代聚合计数与活动状态、侧边栏活动在嵌套谱系中的传播与普通 fork 边界、行状态优先级、token 用量总计、精确到秒的运行中耗时与冻结后 inactive 耗时、采用自适应单位的长耗时及其精确无障碍文本、目录缺失或为陈旧空目录时由摘要支撑的根操作、已知加载行的形态、混合 mode 行、点击前的叶子展开控件、diagnostic、后代懒加载展开、直接 parent 地址、键盘行为与两种只读原因。
+- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现以及页头和 owner 侧边栏行中的聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。
 - 导航测试固定仅含 subagent 的面包屑导航、从 subagent 创建 fork 时的 Workspace 归属，以及 `origin: 'subagent'` 侧边栏过滤，同时不隐藏普通 fork。
 
 ## 后果
diff --git a/apps/web/tests/snapshots/subagent-conversation/sidebar-running.expected.md b/apps/web/tests/snapshots/subagent-conversation/sidebar-running.expected.md
new file mode 100644
index 0000000000..fec6fe658e
--- /dev/null
+++ b/apps/web/tests/snapshots/subagent-conversation/sidebar-running.expected.md
@@ -0,0 +1,5 @@
+- tree "Sessions":
+  - treeitem "workspace 1 session" [expanded]:
+    - img
+    - text: workspace 1 session
+  - treeitem "1 subagent running Ask a research subagent to now" [selected]
diff --git a/apps/web/tests/subagent-conversation.e2e.ts b/apps/web/tests/subagent-conversation.e2e.ts
index 0049cb2791..69250ed6b6 100644
--- a/apps/web/tests/subagent-conversation.e2e.ts
+++ b/apps/web/tests/subagent-conversation.e2e.ts
@@ -23,6 +23,7 @@ const TREE_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/t
 const BRANCHLESS_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/branchless.expected.md', import.meta.url))
 const STALE_CATALOG_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/stale-catalog.expected.md', import.meta.url))
 const SIDEBAR_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/sidebar.expected.md', import.meta.url))
+const RUNNING_SIDEBAR_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/sidebar-running.expected.md', import.meta.url))
 const UNAVAILABLE_GRANDCHILD_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/nested.expected.md', import.meta.url))
 const FORK_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/fork.expected.md', import.meta.url))
 const MODE = webSnapshotMode()
@@ -367,6 +368,15 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
     ).toBe('running')
     const hierarchy = page.getByRole('navigation', { name: 'Session hierarchy' })
     await hierarchy.getByRole('button').first().click()
+    const runningOwnerRow = page.getByRole('tree', { name: 'Sessions' })
+      .getByRole('treeitem', { name: /1 subagent running/ })
+    await runningOwnerRow.waitFor({ timeout: 10_000 })
+    expect(await runningOwnerRow.locator('[data-state="ongoing"]').count()).toBe(1)
+    await compareOrRefreshGolden(
+      RUNNING_SIDEBAR_EXPECTED,
+      await captureStableAria(page, '[role="tree"][aria-label="Sessions"]', scaffold.workspaceCwd),
+      MODE,
+    )
     const runningTrigger = page.getByRole('button', { name: '3 subagents running' })
     await runningTrigger.waitFor({ timeout: 10_000 })
     expect(await runningTrigger.locator('[data-state="ongoing"]').count()).toBe(1)
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 23c867e4c0..8556e393b6 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: 8ac29a4258bbd7456b20c61e547d48c570e84d27
-README.zh.md: 0e065e43ecc571e68d3976d2100eb43959cb2e3d
+README.md: 00427f33b1dfc23b157c8fe4cfefb42cf313ee66
+README.zh.md: 0a27602a4408792e7f02ecd3995aeb5946e81aab
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index 8ac29a4258..00427f33b1 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -22,6 +22,8 @@ Workspace and Session lists have independent monotone `pending` → `ready` base
 
 SlotsService gives the renderer separate bare observables for `useSessions` and `useWorkspaces`; web-react creates the hooks. Workspace business state does not enter `SessionListState` or an entry store.
 
+`indexSubagentDescendants()` derives per-parent total and running descendant counts from the retained list mirror. It follows only uninterrupted `origin: 'subagent'` ancestry, so an ordinary fork starts a separate ownership subtree; cycles stop without throwing, and a missing parent remains a harmless key until its summary arrives.
+
 `SessionsService.search(query, signal)` is a stateless one-shot action over the `session.search` RPC. It returns ranked session/snippet pairs without putting query, loading, or error state into the shared Session list, so each UI owner controls debounce, cancellation, stale-response suppression, and fallback presentation. `searchResultLimit` re-exposes `SESSION_SEARCH_RESULT_LIMIT` — the bound the response schema itself enforces — as injected presentation data, so client plugins do not duplicate it. It is a protocol constant rather than per-connection state, so the connection handle does not carry it.
 
 ## New Session and the blank mirror
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 0e065e43ec..0a27602a44 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -22,6 +22,8 @@ Workspace 和 Session 列表各自具有单调的 `pending` → `ready` 基线
 
 SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 observable；web-react 创建钩子。Workspace 业务状态不会进入 `SessionListState` 或配置项 store。
 
+`indexSubagentDescendants()` 从保留的列表镜像中派生每个 parent 的后代总数与运行中后代数。它只沿不间断的 `origin: 'subagent'` 祖先链追踪，因此普通 fork 会开启独立的归属子树；遇到环时，追踪会停止但不会抛出异常，缺失的 parent 则会保留为无害的键，直至其摘要到达。
+
 `SessionsService.search(query, signal)` 是基于 `session.search` RPC 的无状态单次操作。它返回经过排序的会话／snippet 对，但不会将查询条件、加载状态或错误状态写入共享 Session 列表，因此每个 UI 所有者都自行负责防抖、取消、抑制陈旧响应和回退呈现。`searchResultLimit` 将 `SESSION_SEARCH_RESULT_LIMIT`——即响应 schema 自身强制执行的上限——作为注入的呈现数据重新公开，使客户端插件无需复制该值。它是协议常量而非逐连接状态，因此连接 handle 不携带它。
 
 ## New Session 与 blank 镜像
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index e4f8e57b04..ceee6a1f10 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -15,6 +15,8 @@ export { SlotsService } from './slots.ts'
 export type { RootOwnerProps } from './slots.ts'
 export { SessionCreateError, SessionsService, scopeOf, workspaceTitleOf } from './sessions/service.ts'
 export { SessionHistoryService } from './session-history/service.ts'
+export { indexSubagentDescendants } from './sessions/subagent-lineage.ts'
+export type { SubagentDescendantSummary } from './sessions/subagent-lineage.ts'
 // The provide channel is shared with the client test runtime (one
 // materialization/projection implementation; no test-side mirror to drift).
 export { SessionProvideChannel } from './sessions/provide.ts'
diff --git a/packages/client/runtime/src/client/sessions/subagent-lineage.ts b/packages/client/runtime/src/client/sessions/subagent-lineage.ts
new file mode 100644
index 0000000000..fb56b4eb8c
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/subagent-lineage.ts
@@ -0,0 +1,50 @@
+/**
+ * Pure subagent-lineage aggregation over the retained session-list mirror.
+ * Ordinary forks terminate propagation so each visible session owns only its
+ * uninterrupted subagent subtree.
+ * @module @deepseek-ai/dsh-client-runtime/client/sessions/subagent-lineage
+ */
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionSummary } from './service.ts'
+
+/** Descendant counts projected for one possible parent session. */
+export interface SubagentDescendantSummary {
+  /** All descendants connected through uninterrupted subagent-origin lineage. */
+  readonly count: number
+  /** Descendants whose exact session summary is currently running. */
+  readonly runningCount: number
+}
+
+/**
+ * Index every subagent descendant under each ancestor it reaches through an
+ * uninterrupted subagent-origin chain. Cycles fail soft and orphan owners
+ * remain harmless map keys until their summaries arrive.
+ * @param summaries - retained session summaries keyed by id.
+ * @returns descendant totals and running totals keyed by possible parent id.
+ */
+export function indexSubagentDescendants(
+  summaries: Readonly<Record<SessionId, SessionSummary>>,
+): ReadonlyMap<SessionId, SubagentDescendantSummary> {
+  const indexed = new Map<SessionId, { count: number; runningCount: number }>()
+  for (const descendant of Object.values(summaries)) {
+    if (descendant.origin !== 'subagent') continue
+    const seen = new Set<SessionId>()
+    let current: SessionSummary | undefined = descendant
+    while (current?.origin === 'subagent' && current.parentId !== undefined
+      && !seen.has(current.id)) {
+      seen.add(current.id)
+      const aggregate = indexed.get(current.parentId)
+      if (aggregate === undefined) {
+        indexed.set(current.parentId, {
+          count: 1,
+          runningCount: descendant.running ? 1 : 0,
+        })
+      } else {
+        aggregate.count += 1
+        if (descendant.running) aggregate.runningCount += 1
+      }
+      current = summaries[current.parentId]
+    }
+  }
+  return indexed
+}
diff --git a/packages/client/runtime/tests/subagent-lineage.spec.ts b/packages/client/runtime/tests/subagent-lineage.spec.ts
new file mode 100644
index 0000000000..05881576bf
--- /dev/null
+++ b/packages/client/runtime/tests/subagent-lineage.spec.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import type { SessionId, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
+import { indexSubagentDescendants } from '@deepseek-ai/dsh-client-runtime/client'
+
+const sid = (id: string) => id as SessionId
+
+function summary(
+  id: string,
+  parentId?: SessionId,
+  origin?: 'subagent',
+  running = false,
+): SessionSummary {
+  return {
+    id: sid(id), displayTitle: id, running, blank: false, updatedAt: 0,
+    ...(parentId === undefined ? {} : { parentId }),
+    ...(origin === undefined ? {} : { origin }),
+  }
+}
+
+function index(...summaries: SessionSummary[]) {
+  return indexSubagentDescendants(Object.fromEntries(
+    summaries.map(item => [item.id, item]),
+  ))
+}
+
+describe('indexSubagentDescendants', () => {
+  it('counts every nested descendant and its exact running state', () => {
+    const owner = summary('owner')
+    const child = summary('child', owner.id, 'subagent')
+    const grandchild = summary('grandchild', child.id, 'subagent', true)
+
+    const result = index(owner, child, grandchild)
+    expect(result.get(owner.id)).toEqual({ count: 2, runningCount: 1 })
+    expect(result.get(child.id)).toEqual({ count: 1, runningCount: 1 })
+  })
+
+  it('stops at ordinary forks and fails soft on cycles and missing parents', () => {
+    const owner = summary('owner')
+    const child = summary('child', owner.id, 'subagent', true)
+    const fork = summary('fork', child.id)
+    const forkChild = summary('fork-child', fork.id, 'subagent', true)
+    const orphan = summary('orphan', sid('missing'), 'subagent', true)
+    const cycleA = summary('cycle-a', sid('cycle-b'), 'subagent')
+    const cycleB = summary('cycle-b', sid('cycle-a'), 'subagent')
+
+    const result = index(owner, child, fork, forkChild, orphan, cycleA, cycleB)
+    expect(result.get(owner.id)).toEqual({ count: 1, runningCount: 1 })
+    expect(result.get(fork.id)).toEqual({ count: 1, runningCount: 1 })
+    expect(result.get(sid('missing'))).toEqual({ count: 1, runningCount: 1 })
+    expect(result.get(cycleA.id)).toEqual({ count: 2, runningCount: 0 })
+    expect(result.get(cycleB.id)).toEqual({ count: 2, runningCount: 0 })
+  })
+})
diff --git a/packages/client/ui-subagent/src/client/SubagentCatalogAction.tsx b/packages/client/ui-subagent/src/client/SubagentCatalogAction.tsx
index 76a216ebd8..50850f0b98 100644
--- a/packages/client/ui-subagent/src/client/SubagentCatalogAction.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentCatalogAction.tsx
@@ -1,9 +1,9 @@
 import {
-  useEffect, useRef, useState, type KeyboardEvent, type MouseEvent,
+  useEffect, useMemo, useRef, useState, type KeyboardEvent, type MouseEvent,
 } from 'react'
-import type {
-  SessionId, SessionListState, SessionProjectionMap, SessionSummary, SubagentAddress,
-  SubagentCatalogSnapshot,
+import {
+  indexSubagentDescendants, type SessionId, type SessionListState, type SessionProjectionMap,
+  type SessionSummary, type SubagentAddress, type SubagentCatalogSnapshot,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import {
   IconChevronDownOutline14, IconChevronRightOutline14, IconRefreshOutline14, StateDot,
@@ -171,30 +171,7 @@ function formatExactDuration(ms: number, t: TranslateNS<typeof NS>): string {
     })
 }
 
-/** Aggregate the complete subagent-only descendant subtree from flat summaries. */
-function summarizeDescendants(
-  sessionId: SessionId,
-  summaries: Readonly<Record<SessionId, SessionSummary>>,
-): { count: number; running: boolean } {
-  let count = 0
-  let running = false
-  for (const summary of Object.values(summaries)) {
-    if (summary.origin !== 'subagent') continue
-    const seen = new Set<SessionId>()
-    let current: SessionSummary | undefined = summary
-    while (current?.origin === 'subagent' && current.parentId !== undefined
-      && !seen.has(current.id)) {
-      seen.add(current.id)
-      if (current.parentId === sessionId) {
-        count += 1
-        running ||= summary.running
-        break
-      }
-      current = summaries[current.parentId]
-    }
-  }
-  return { count, running }
-}
+const NO_DESCENDANTS = { count: 0, runningCount: 0 } as const
 
 /** Render the known direct-child shape while its authoritative catalog hydrates. */
 function CatalogLoadingRows({
@@ -448,7 +425,10 @@ export function SubagentCatalogAction({
   const setCatalogOpenRef = useRef(setCatalogOpen)
   setCatalogOpenRef.current = setCatalogOpen
   const healthy = catalog?.entries.filter(entry => entry.kind === 'child') ?? []
-  const descendants = summarizeDescendants(sessionId, summaries)
+  const descendants = useMemo(
+    () => indexSubagentDescendants(summaries).get(sessionId) ?? NO_DESCENDANTS,
+    [sessionId, summaries],
+  )
   // The catalog can arrive before the session-list baseline; never undercount
   // the already-visible direct rows during that short bootstrap window.
   const descendantCount = Math.max(healthy.length, descendants.count)
@@ -527,10 +507,10 @@ export function SubagentCatalogAction({
   }, [open])
 
   useEffect(() => {
-    if (!open || !descendants.running) return
+    if (!open || descendants.runningCount === 0) return
     const timer = setInterval(() => { setNow(Date.now()) }, 1_000)
     return () => { clearInterval(timer) }
-  }, [open, descendants.running])
+  }, [open, descendants.runningCount])
 
   useEffect(() => () => {
     for (const parentSessionId of observedCatalogs.current) {
@@ -584,7 +564,7 @@ export function SubagentCatalogAction({
         className={css.trigger}
         aria-haspopup="tree"
         aria-expanded={open}
-        aria-label={t(descendants.running ? runningCountKey : totalCountKey, { count: descendantCount })}
+        aria-label={t(descendants.runningCount > 0 ? runningCountKey : totalCountKey, { count: descendantCount })}
         onClick={() => { changeOpen(!open) }}
         onKeyDown={(event) => {
           if (event.key !== 'ArrowDown') return
@@ -594,7 +574,7 @@ export function SubagentCatalogAction({
         }}
       >
         <span className={css.activitySlot}>
-          {descendants.running && <StateDot state="ongoing" />}
+          {descendants.runningCount > 0 && <StateDot state="ongoing" />}
         </span>
         <span className={css.count}>{t(totalCountKey, { count: descendantCount })}</span>
         <IconChevronDownOutline14 className={open ? css.triggerOpen : undefined} />
diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml
index fee956b683..c5cfc89ea5 100644
--- a/packages/client/ui-workspace/README.i18n.yaml
+++ b/packages/client/ui-workspace/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/client/ui-workspace/README.md
-README.md: bd7313b560e76378e4fff274c99bb976819aebae
-README.zh.md: 734a897b9cb9c3469d8f402b13bff4b62753f9b2
+README.md: b2baea049c30f46c3194009e71c70b38973dc526
+README.zh.md: cc50ba3691db10a533337b0e99689fba72a679ca
diff --git a/packages/client/ui-workspace/README.md b/packages/client/ui-workspace/README.md
index bd7313b560..b2baea049c 100644
--- a/packages/client/ui-workspace/README.md
+++ b/packages/client/ui-workspace/README.md
@@ -16,7 +16,7 @@ Session rows render the runtime's live `pendingInteraction` classification: appr
 
 Both target slots are declared by other plugins, so `apply` uses `slots.inject()` to register for each declaration lifetime and re-register after a declaring slot is restored.
 
-The shared sidebar projection hides rows whose durable Session summary has `origin: 'subagent'`; users enter those conversations through the selected parent's subagent header catalog. Ordinary forks remain visible because lineage alone does not set that origin. The runtime keeps hidden rows available for conversation, title, and addressed transport state.
+The shared sidebar projection hides rows whose durable Session summary has `origin: 'subagent'`; users enter those conversations through the selected parent's subagent header catalog. Each visible ordinary row inherits the blue activity indicator while any descendant reached through uninterrupted subagent-origin lineage is running, and its hover and assistive text report the exact running-descendant count without describing an idle parent as running. Ordinary forks remain visible and terminate this aggregation because lineage alone does not set their origin. Pending user interaction remains the primary row marker while descendant activity stays available as a separate hover and assistive status. The runtime keeps hidden rows available for conversation, title, and addressed transport state.
 
 ## Model Experience
 
diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md
index 734a897b9c..cc50ba3691 100644
--- a/packages/client/ui-workspace/README.zh.md
+++ b/packages/client/ui-workspace/README.zh.md
@@ -16,7 +16,7 @@ Session 行渲染运行时的实时 `pendingInteraction` 分类：审批显示**
 
 两个目标 slot 都由其他插件声明，因此 `apply` 使用 `slots.inject()` 在各自的声明生命周期内完成注册，并在目标 slot 的声明恢复后重新注册。
 
-共享侧边栏投影会隐藏持久化 Session 摘要中带有 `origin: 'subagent'` 的行；用户从所选 parent 的 subagent 页头目录进入这些对话。普通 fork 仍然可见，因为仅有谱系不会设置该 origin。运行时仍保留隐藏行，供对话、标题与已寻址传输状态使用。
+共享侧边栏投影会隐藏持久化 Session 摘要中带有 `origin: 'subagent'` 的行；用户从所选 parent 的 subagent 页头目录进入这些对话。每个可见的普通行都会在经不间断的 subagent 谱系可达的任一后代运行时继承蓝色活动指示器；其悬停与无障碍文本会报告确切的运行中后代数量，同时不会把空闲 parent 描述为正在运行。普通 fork 仍然可见，并会终止此聚合，因为仅有谱系不会设置该 origin。待处理的用户交互仍是主要行标记，而后代活动会作为独立的悬停与无障碍状态保留。运行时仍保留隐藏行，供对话、标题与已寻址传输状态使用。
 
 ## 模型体验
 
diff --git a/packages/client/ui-workspace/src/client/locales.ts b/packages/client/ui-workspace/src/client/locales.ts
index d9c70de729..30fe6bfcc0 100644
--- a/packages/client/ui-workspace/src/client/locales.ts
+++ b/packages/client/ui-workspace/src/client/locales.ts
@@ -45,6 +45,8 @@ export const zh = {
   'actions.session.aria': '会话“{name}”的操作',
   'actions.newSession.aria': '在“{name}”中新建会话',
   'status.running': '进行中',
+  'status.subagentsRunning.one': '{n} 个子代理运行中',
+  'status.subagentsRunning.other': '{n} 个子代理运行中',
   'status.idle': '空闲',
   'status.waitingApproval': '等待审批',
   'status.planReview': '计划待审',
@@ -106,6 +108,8 @@ export const en = {
   'actions.session.aria': 'Session actions for {name}',
   'actions.newSession.aria': 'New session in {name}',
   'status.running': 'Running',
+  'status.subagentsRunning.one': '{n} subagent running',
+  'status.subagentsRunning.other': '{n} subagents running',
   'status.idle': 'Idle',
   'status.waitingApproval': 'Waiting for approval',
   'status.planReview': 'Plan awaiting review',
diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx
index fb64a0be42..3d3b40403d 100644
--- a/packages/client/ui-workspace/src/client/rows/Rows.tsx
+++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx
@@ -171,37 +171,67 @@ function assertNever(value: never): never {
   throw new Error(`unknown pending interaction: ${String(value)}`)
 }
 
-/** Session status presentation; pending user interaction outranks the running state. */
-function sessionStatus(
-  node: Pick<SessionNode, 'pendingInteraction' | 'running' | 'completed'>,
+interface SessionStatus {
+  state: StateDotState
+  label: string
+}
+
+/** Session status presentation; pending user interaction remains primary. */
+function sessionStatuses(
+  node: Pick<SessionNode, 'pendingInteraction' | 'running' | 'runningSubagentCount' | 'completed'>,
   t: RowTranslate,
-): { state: StateDotState; label: string } {
+): readonly [SessionStatus, ...SessionStatus[]] {
+  const subagents: SessionStatus | undefined = node.runningSubagentCount === 0
+    ? undefined
+    : {
+      state: 'ongoing',
+      label: t(
+        node.runningSubagentCount === 1
+          ? 'status.subagentsRunning.one'
+          : 'status.subagentsRunning.other',
+        { n: node.runningSubagentCount },
+      ),
+    }
+  let pending: SessionStatus | undefined
   switch (node.pendingInteraction) {
-    case 'approval': return { state: 'warning', label: t('status.waitingApproval') }
-    case 'plan-review': return { state: 'warning', label: t('status.planReview') }
-    case 'question': return { state: 'warning', label: t('status.waitingAnswer') }
+    case 'approval':
+      pending = { state: 'warning', label: t('status.waitingApproval') }
+      break
+    case 'plan-review':
+      pending = { state: 'warning', label: t('status.planReview') }
+      break
+    case 'question':
+      pending = { state: 'warning', label: t('status.waitingAnswer') }
+      break
     case undefined: break
     /* v8 ignore next -- closed PendingInteractionStatus union */
     default: return assertNever(node.pendingInteraction)
   }
-  if (node.running) return { state: 'ongoing', label: t('status.running') }
-  if (node.completed) return { state: 'done', label: t('status.completed') }
-  return { state: 'done', label: t('status.idle') }
+  if (pending !== undefined) return subagents === undefined ? [pending] : [pending, subagents]
+  if (node.running) {
+    const primary: SessionStatus = { state: 'ongoing', label: t('status.running') }
+    return subagents === undefined ? [primary] : [primary, subagents]
+  }
+  if (subagents !== undefined) return [subagents]
+  if (node.completed) return [{ state: 'done', label: t('status.completed') }]
+  return [{ state: 'done', label: t('status.idle') }]
 }
 
-/** Hover-card body: full title, relative time, and interaction/running/completed/idle status. */
+/** Hover-card body: full title, relative time, and every relevant live status. */
 function SessionHoverContent({ node, now, t }: { node: SessionNode; now: number; t: RowTranslate }) {
-  const status = sessionStatus(node, t)
+  const statuses = sessionStatuses(node, t)
   return (
     <div className={css.hoverContent}>
       <div className={css.hoverTitle}>{displayTitle(node, t)}</div>
       {/* Same placeholder rule as the row's trailing cell: no timestamp
           before the first prompt. */}
       {!node.blank && <div className={css.hoverTime}>{hoverTimeLabel(node.updatedAt, now, t)}</div>}
-      <div className={css.hoverStatus}>
-        <StateDot state={status.state} />
-        <span>{status.label}</span>
-      </div>
+      {statuses.map(status => (
+        <div className={css.hoverStatus} key={status.label}>
+          <StateDot state={status.state} />
+          <span>{status.label}</span>
+        </div>
+      ))}
     </div>
   )
 }
@@ -241,7 +271,8 @@ export function SearchResultItem({ result, currentId, onOpen, t }: {
   t: RowTranslate
 }) {
   const selected = result.id === currentId
-  const status = sessionStatus(result, t)
+  const statuses = sessionStatuses(result, t)
+  const primaryStatus = statuses[0]
   return (
     <button
       type="button"
@@ -252,10 +283,12 @@ export function SearchResultItem({ result, currentId, onOpen, t }: {
     >
       <span className={css.searchResultHeading}>
         <span className={css.slot}>
-          {(status.state !== 'done' || result.completed) && (
+          {(primaryStatus.state !== 'done' || result.completed) && (
             <>
-              <StateDot state={status.state} />
-              <span className={css.visuallyHidden}>{status.label}</span>
+              <StateDot state={primaryStatus.state} />
+              {statuses.map(status => (
+                <span className={css.visuallyHidden} key={status.label}>{status.label}</span>
+              ))}
             </>
           )}
         </span>
@@ -277,7 +310,7 @@ function rowHalf(e: { clientY: number; currentTarget: HTMLElement }): 'before' |
 
 /**
  * One top-level 34px session row: status dot (pending user interaction outranks
- * running), title, relative time, and the row actions menu.
+ * own or descendant activity), title, relative time, and the row actions menu.
  * @param props.node - derived session node.
  * @param props.currentId - selected session id (row highlight).
  * @param props.now - epoch ms for relative-time formatting.
@@ -307,7 +340,8 @@ export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork
   const row = node
   const title = displayTitle(node, t)
   const selected = node.id === currentId
-  const status = sessionStatus(node, t)
+  const statuses = sessionStatuses(node, t)
+  const primaryStatus = statuses[0]
   const [menuOpen, setMenuOpen] = useState(false)
   // Archive replaces the former Delete placeholder: it hides the row through
   // the registry-global archive set and never touches the session log, so it
@@ -356,10 +390,12 @@ export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork
           finished-but-unviewed session shows the green done reminder dot
           (cleared by opening the session). */}
       <span className={css.slot}>
-        {(status.state !== 'done' || row.completed) && (
+        {(primaryStatus.state !== 'done' || row.completed) && (
           <>
-            <StateDot state={status.state} />
-            <span className={css.visuallyHidden}>{status.label}</span>
+            <StateDot state={primaryStatus.state} />
+            {statuses.map(status => (
+              <span className={css.visuallyHidden} key={status.label}>{status.label}</span>
+            ))}
           </>
         )}
       </span>
diff --git a/packages/client/ui-workspace/src/client/tree.ts b/packages/client/ui-workspace/src/client/tree.ts
index 90153211ea..008ab687f7 100644
--- a/packages/client/ui-workspace/src/client/tree.ts
+++ b/packages/client/ui-workspace/src/client/tree.ts
@@ -3,9 +3,10 @@
  * Unassigned Sessions trail under Ungrouped; only the selected blank Session
  * remains visible.
  */
-import type {
-  PendingInteractionStatus, SessionId, SessionListState, SessionSearchResultItem, SessionSummary,
-  WorkspaceId, WorkspaceView,
+import {
+  indexSubagentDescendants, type PendingInteractionStatus, type SessionId, type SessionListState,
+  type SessionSearchResultItem, type SessionSummary, type SubagentDescendantSummary,
+  type WorkspaceId, type WorkspaceView,
 } from '@deepseek-ai/dsh-client-runtime/client'
 
 /** Group key for Sessions outside every Workspace. */
@@ -24,6 +25,8 @@ export interface SessionNode {
   /** The runtime Session list reports an interaction awaiting this user. */
   pendingInteraction?: PendingInteractionStatus
   running: boolean
+  /** Running descendants connected through uninterrupted subagent-origin lineage. */
+  runningSubagentCount: number
   /** Finished running while not selected and not yet opened (the green "done" reminder dot). */
   completed: boolean
   updatedAt: number
@@ -56,6 +59,8 @@ export interface SearchResultNode {
   /** The runtime Session list reports an interaction awaiting this user. */
   pendingInteraction?: PendingInteractionStatus
   running: boolean
+  /** Running descendants connected through uninterrupted subagent-origin lineage. */
+  runningSubagentCount: number
   /** Finished running while not selected and not yet opened (the green "done" reminder dot). */
   completed: boolean
   snippet?: string
@@ -173,12 +178,16 @@ function groupByWorkspace(
   return groups
 }
 
-function sessionNode(s: SessionSummary): SessionNode {
+function sessionNode(
+  s: SessionSummary,
+  descendants: ReadonlyMap<SessionId, SubagentDescendantSummary>,
+): SessionNode {
   return {
     id: s.id,
     title: sessionTitle(s),
     blank: s.blank,
     running: s.running,
+    runningSubagentCount: descendants.get(s.id)?.runningCount ?? 0,
     completed: s.completed === true,
     updatedAt: s.updatedAt,
     ...(s.pendingInteraction === undefined ? {} : { pendingInteraction: s.pendingInteraction }),
@@ -207,6 +216,7 @@ export function deriveGroups(
 ): GroupNode[] {
   const archived = new Set(archivedSessionIds)
   const expandedProjects = new Set(view.expandedProjects)
+  const descendants = indexSubagentDescendants(list.byId)
   const currentGroup = list.current === undefined
     ? undefined
     : (workspaces.find(w => w.sessionIds.includes(list.current as SessionId))?.workspaceId as string | undefined)
@@ -223,7 +233,7 @@ export function deriveGroups(
       sessionCount: g.sessions.length,
       expanded,
       containsCurrent: g.key === currentGroup,
-      sessions: expanded ? g.sessions.map(sessionNode) : [],
+      sessions: expanded ? g.sessions.map(session => sessionNode(session, descendants)) : [],
     })
   }
   return groups
@@ -240,6 +250,7 @@ export function deriveGroups(
  */
 export function deriveFlat(list: SessionListState, archivedSessionIds: readonly SessionId[]): SessionNode[] {
   const archived = new Set(archivedSessionIds)
+  const descendants = indexSubagentDescendants(list.byId)
   const rows: SessionSummary[] = []
   for (const id of list.ids) {
     const s = list.byId[id]
@@ -247,7 +258,7 @@ export function deriveFlat(list: SessionListState, archivedSessionIds: readonly
     rows.push(s)
   }
   rows.sort(byRecency)
-  return rows.map(sessionNode)
+  return rows.map(session => sessionNode(session, descendants))
 }
 
 /** Relative-time bucket of a session row's trailing label. */
@@ -282,6 +293,7 @@ export function deriveSearchResults(
   const q = query.trim().toLowerCase()
   if (q === '') return { items: [], hasMore: false }
   const archived = new Set(archivedSessionIds)
+  const descendants = indexSubagentDescendants(list.byId)
 
   const workspaceBySession = new Map<SessionId, string>()
   for (const workspace of workspaces) {
@@ -332,6 +344,7 @@ export function deriveSearchResults(
         title: sessionTitle(summary),
         workspace: labelOf(summary),
         running: summary.running,
+        runningSubagentCount: descendants.get(summary.id)?.runningCount ?? 0,
         ...(summary.pendingInteraction === undefined
           ? {}
           : { pendingInteraction: summary.pendingInteraction }),
diff --git a/packages/client/ui-workspace/tests/rows.spec.tsx b/packages/client/ui-workspace/tests/rows.spec.tsx
index 1c8fd1f703..46eb8b2dba 100644
--- a/packages/client/ui-workspace/tests/rows.spec.tsx
+++ b/packages/client/ui-workspace/tests/rows.spec.tsx
@@ -64,6 +64,7 @@ describe('workspace browser rows', () => {
       title: 'Result title',
       workspace: 'Workspace context',
       running: true,
+      runningSubagentCount: 0,
       completed: false,
       snippet: 'matching message excerpt',
     }
@@ -86,7 +87,7 @@ describe('workspace browser rows', () => {
   ] as const)('shows %s ahead of running in search results', (pendingInteraction, label) => {
     const result: SearchResultNode = {
       id: sid(pendingInteraction), title: 'Needs input', workspace: 'Project',
-      pendingInteraction, running: true, completed: false,
+      pendingInteraction, running: true, runningSubagentCount: 0, completed: false,
     }
     render(<SearchResultItem result={result} currentId={undefined} onOpen={vi.fn()} t={t} />)
     const row = screen.getByRole('treeitem')
@@ -115,7 +116,8 @@ describe('workspace browser rows', () => {
 
   it('renders and opens a selected running Session row', () => {
     const node: SessionNode = {
-      id: sid('session'), title: 'Session', blank: false, running: true, completed: false, updatedAt: 0,
+      id: sid('session'), title: 'Session', blank: false, running: true,
+      runningSubagentCount: 0, completed: false, updatedAt: 0,
     }
     const onOpen = vi.fn()
     render(
@@ -134,7 +136,10 @@ describe('workspace browser rows', () => {
   it('shows the green done dot only on a finished, unviewed session (running wins the slot)', () => {
     const renderRow = (over: Partial<SessionNode>) => render(
       <SessionNodeItem
-        node={{ id: sid('s1'), title: 'One', blank: false, running: false, completed: false, updatedAt: 0, ...over }}
+        node={{
+          id: sid('s1'), title: 'One', blank: false, running: false,
+          runningSubagentCount: 0, completed: false, updatedAt: 0, ...over,
+        }}
         currentId={undefined} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t}
       />,
@@ -155,9 +160,48 @@ describe('workspace browser rows', () => {
     expect(running.container.querySelector('[data-state="done"]')).toBeNull()
   })
 
+  it('shows descendant activity without describing an idle parent as running', () => {
+    vi.useFakeTimers()
+    try {
+      const node: SessionNode = {
+        id: sid('owner'), title: 'Delegating', blank: false, running: false,
+        runningSubagentCount: 2, completed: false, updatedAt: 0,
+      }
+      render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
+      const row = screen.getByRole('treeitem')
+      expect(row.querySelector('[data-state="ongoing"]')).not.toBeNull()
+      expect(screen.getByText('2 个子代理运行中')).toBeTruthy()
+      expect(screen.queryByText('进行中')).toBeNull()
+
+      fireEvent.pointerEnter(row.parentElement as HTMLElement)
+      act(() => { vi.advanceTimersByTime(500) })
+      expect(screen.getAllByText('2 个子代理运行中')).toHaveLength(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('keeps child activity as a secondary status while user attention is primary', () => {
+    const node: SessionNode = {
+      id: sid('owner'), title: 'Needs input', blank: false, pendingInteraction: 'question',
+      running: false, runningSubagentCount: 1, completed: false, updatedAt: 0,
+    }
+    render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+      onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
+    const row = screen.getByRole('treeitem')
+    expect(row.querySelector('[data-state="warning"]')).not.toBeNull()
+    expect(row.querySelector('[data-state="ongoing"]')).toBeNull()
+    expect(screen.getByText('等待回答')).toBeTruthy()
+    expect(screen.getByText('1 个子代理运行中')).toBeTruthy()
+  })
+
   it('shows the green done dot on a finished search result row', () => {
     render(<SearchResultItem
-      result={{ id: sid('result'), title: 'Done', workspace: 'Workspace', running: false, completed: true }}
+      result={{
+        id: sid('result'), title: 'Done', workspace: 'Workspace', running: false,
+        runningSubagentCount: 0, completed: true,
+      }}
       currentId={undefined} onOpen={vi.fn()} t={t}
     />)
     expect(screen.getByRole('treeitem').querySelector('[data-state="done"]')).not.toBeNull()
@@ -231,7 +275,8 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s-blank'), title: 'ignored', blank: true, running: false, completed: false, updatedAt: 0,
+        id: sid('s-blank'), title: 'ignored', blank: true, running: false,
+        runningSubagentCount: 0, completed: false, updatedAt: 0,
       }
       render(<SessionNodeItem node={node} currentId={node.id} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -257,7 +302,8 @@ describe('workspace browser rows', () => {
     const onFork = vi.fn()
     const onArchive = vi.fn()
     const node: SessionNode = {
-      id: sid('s1'), title: 'One', blank: false, running: false, completed: false, updatedAt: 0,
+      id: sid('s1'), title: 'One', blank: false, running: false,
+      runningSubagentCount: 0, completed: false, updatedAt: 0,
     }
     render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={onOpen}
       onRename={onRename} onFork={onFork} onArchive={onArchive} t={t} />)
@@ -290,7 +336,8 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s1'), title: 'Hovered', blank: false, running: true, completed: false, updatedAt: 0,
+        id: sid('s1'), title: 'Hovered', blank: false, running: true,
+        runningSubagentCount: 0, completed: false, updatedAt: 0,
       }
       render(<SessionNodeItem node={node} currentId={undefined} now={60_000} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -321,7 +368,7 @@ describe('workspace browser rows', () => {
     try {
       const node: SessionNode = {
         id: sid(pendingInteraction), title: 'Needs input', blank: false,
-        pendingInteraction, running: true, completed: false, updatedAt: 0,
+        pendingInteraction, running: true, runningSubagentCount: 0, completed: false, updatedAt: 0,
       }
       const view = render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -347,7 +394,8 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s1'), title: 'Quiet', blank: false, running: false, completed: false, updatedAt: 0,
+        id: sid('s1'), title: 'Quiet', blank: false, running: false,
+        runningSubagentCount: 0, completed: false, updatedAt: 0,
       }
       render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -364,7 +412,8 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s1'), title: 'Done', blank: false, running: false, completed: true, updatedAt: 0,
+        id: sid('s1'), title: 'Done', blank: false, running: false,
+        runningSubagentCount: 0, completed: true, updatedAt: 0,
       }
       render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -379,7 +428,8 @@ describe('workspace browser rows', () => {
 
   it('draggable row wires start/end and gates hover/drop on an active same-group drag', () => {
     const node: SessionNode = {
-      id: sid('s1'), title: 'Drag me', blank: false, running: false, completed: false, updatedAt: 0,
+      id: sid('s1'), title: 'Drag me', blank: false, running: false,
+      runningSubagentCount: 0, completed: false, updatedAt: 0,
     }
     const inactive = dragProps()
     const { rerender } = render(
diff --git a/packages/client/ui-workspace/tests/tree.spec.ts b/packages/client/ui-workspace/tests/tree.spec.ts
index fed1c03eec..647e29f6d3 100644
--- a/packages/client/ui-workspace/tests/tree.spec.ts
+++ b/packages/client/ui-workspace/tests/tree.spec.ts
@@ -95,18 +95,35 @@ describe('deriveGroups', () => {
 
   it('hides subagent-origin sessions without hiding ordinary forks', () => {
     const parent = summary('parent', 1)
-    const fork = { ...summary('fork', 2), parentId: parent.id }
-    const subagent = { ...summary('subagent', 3), parentId: parent.id, origin: 'subagent' as const }
-    const sessions = { ...list(parent, fork, subagent), current: subagent.id }
+    const subagent = {
+      ...summary('subagent', 3), parentId: parent.id, origin: 'subagent' as const, running: true,
+    }
+    const grandchild = {
+      ...summary('grandchild', 4), parentId: subagent.id, origin: 'subagent' as const, running: true,
+    }
+    const fork = { ...summary('fork', 2), parentId: subagent.id }
+    const forkChild = {
+      ...summary('fork-child', 5), parentId: fork.id, origin: 'subagent' as const, running: true,
+    }
+    const sessions = { ...list(parent, fork, subagent, grandchild, forkChild), current: subagent.id }
     const groups = deriveGroups(
       sessions,
-      [workspace('first', ['parent', 'fork', 'subagent'])],
+      [workspace('first', ['parent', 'fork', 'subagent', 'grandchild', 'fork-child'])],
       noArchive,
       view(['first']),
     )
 
     expect(groups[0]!.sessions.map(node => node.id)).toEqual([parent.id, fork.id])
     expect(groups[0]!.sessionCount).toBe(2)
+    expect(groups[0]!.sessions[0]).toMatchObject({ running: false, runningSubagentCount: 2 })
+    expect(groups[0]!.sessions[1]).toMatchObject({ running: false, runningSubagentCount: 1 })
+    expect(deriveFlat(sessions, noArchive).map(node => [node.id, node.runningSubagentCount])).toEqual([
+      [fork.id, 1], [parent.id, 2],
+    ])
+    expect(deriveSearchResults(
+      sessions, [workspace('first', ['parent', 'fork'])], 'parent', noArchive,
+      { items: [], hasMore: false }, 10,
+    ).items[0]).toMatchObject({ id: parent.id, runningSubagentCount: 2 })
   })
 
   it('ignores fork lineage and sorts every ungrouped session as a top-level row', () => {
@@ -274,6 +291,7 @@ describe('deriveSearchResults', () => {
           title: 'Needle title',
           workspace: 'Alpha',
           running: false,
+          runningSubagentCount: 0,
           pendingInteraction: 'plan-review',
           completed: false,
           snippet: 'title session body excerpt',
@@ -283,6 +301,7 @@ describe('deriveSearchResults', () => {
           title: 'Ordinary title',
           workspace: 'Needle Workspace',
           running: false,
+          runningSubagentCount: 0,
           completed: false,
         },
         {
@@ -290,6 +309,7 @@ describe('deriveSearchResults', () => {
           title: 'content-hit',
           workspace: 'c',
           running: false,
+          runningSubagentCount: 0,
           completed: false,
           snippet: 'body needle excerpt',
         },

From f91fd2269dbd305699ac745be100b65d0cd5aca7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 02:25:26 +0800
Subject: [PATCH 220/516] fix(typert): prepare remote contracts for source
 gates

---
 ...ompiler-independent-typert-model.i18n.yaml |  6 +--
 ...07-27-compiler-independent-typert-model.md |  4 +-
 ...27-compiler-independent-typert-model.zh.md |  4 +-
 ...08-02-typert-remote-method-calls.i18n.yaml |  4 +-
 .../2026-08-02-typert-remote-method-calls.md  |  5 +-
 ...026-08-02-typert-remote-method-calls.zh.md |  5 +-
 docs/development.i18n.yaml                    |  4 +-
 docs/development.md                           |  4 +-
 docs/development.zh.md                        |  4 +-
 lefthook.yml                                  |  2 +-
 package.json                                  | 13 +++--
 scripts/run-gates.spec.ts                     | 52 +++++++++++++++++++
 scripts/run-gates.ts                          | 52 +++++++++++++------
 13 files changed, 122 insertions(+), 37 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
index c462dcec34..1c6a23eec8 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.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-27-compiler-independent-typert-model.md: 338476924dfb5d9832d0b64bf01b8d3c297cd6d6
-2026-07-27-compiler-independent-typert-model.zh.md: a88f4dbba50696071552ea12a63b69ecac202418
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.md
+2026-07-27-compiler-independent-typert-model.md: 15641e5f785c5d2daecbfc2d5cffedd64d8384a7
+2026-07-27-compiler-independent-typert-model.zh.md: 7bddd3ffde343346c163f55ef493c32bad1e8314
diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.md b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.md
index 338476924d..15641e5f78 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.md
@@ -22,7 +22,7 @@ PackageModel recognizes Cordis services, events, `@typert object` reference obje
 
 [`dsh-typert-registry`](../../../../packages/typert/registry/README.md) provides `ctx.typert` and handles runtime registration only: one contribution atomically carries package-face reflection and an optional Zod schema, and Cordis effect disposal revokes it. The registry neither analyzes TypeScript nor merges the two faces. JSON Schema is an on-demand projection of registered Zod schemas.
 
-Package artifact publication is explicit opt-in. When invoked, `WorkspaceTypertGenerator` validates that each requested host face exposes the user-facing subpath `package/typert` from the root artifact `package/lib/typert.host.{js,d.ts}`, or that each requested client face exposes `package/client/typert` from `package/lib/typert.client.{js,d.ts}`. It neither edits exports nor runs as part of the ordinary root build or typecheck, so those commands do not generate whole-workspace Typert artifacts. Generated declarations keep `TYPERT` typed as `unknown`, so business packages do not depend on the registry.
+Package artifact publication remains explicit opt-in through package exports. When invoked, `WorkspaceTypertGenerator` validates that each requested host face exposes the user-facing subpath `package/typert` from the root artifact `package/lib/typert.host.{js,d.ts}`, or that each requested client face exposes `package/client/typert` from `package/lib/typert.client.{js,d.ts}`; it never edits those exports. The later [TypeRT Remote design](2026-08-02-typert-remote-method-calls.md) adds a whole-workspace Host contract pass to root build, typecheck, lint, and documentation typecheck. For opted-in Host packages, that pass emits both local reflection and strict Host-for-Client `/remote` contracts before consumers resolve them. Generated local declarations keep `TYPERT` typed as `unknown`, so business packages do not depend on the registry.
 
 At build time, `CordisCatalogProjector` consumes the analyzed `FaceModel` and `TypeGraph` once to generate `docs/cordis-catalog/events.md`, `docs/cordis-catalog/services.md`, and the static `SERVICE_API`, `EVENT_API`, and `TYPE_API` catalog committed for `tool-cordis`. `tool-cordis` reads that static catalog and has no runtime dependency on `ctx.typert`. [`dsh-typert-loader`](../../../../packages/typert/loader/README.md) and the registry remain an independent runtime path: the loader follows Cordis Loader entry lifecycle events, imports an explicitly published `./typert` host artifact, and registers it through `ctx.typert`; neither component supplies the current `cordis_inspect` catalog.
 
@@ -50,4 +50,4 @@ For each supported node kind and literal category, Zod emitter tests run both su
 
 New generation targets and static checks can reuse the same TypeGraph, and business categories can extend PackageModel without parsing the AST again. Preserving pre-evaluation types and independent faces makes the model more complex than a flattened schema; emitters must explicitly declare their supported scope and fail on missing capabilities.
 
-Explicit opt-in keeps artifact publication and package exports under package ownership, while ordinary root builds and typechecks incur no whole-workspace Typert generation phase. The static Cordis catalogs remain reproducible from the canonical model without coupling `tool-cordis` to runtime registry state. `ctx.typert` reflects only artifacts mounted in the current runtime, and unloading does not control Zod instances that consumers retain after importing them directly.
+Explicit package opt-in keeps artifact publication and exports under package ownership. Repository orchestration may still run the whole-workspace Host contract pass for every opted-in package; that pass remains owned by the later Remote Gateway Agent Note. The static Cordis catalogs remain reproducible from the canonical model without coupling `tool-cordis` to runtime registry state. `ctx.typert` reflects only artifacts mounted in the current runtime, and unloading does not control Zod instances that consumers retain after importing them directly.
diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
index a88f4dbba5..7bddd3ffde 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
@@ -22,7 +22,7 @@ PackageModel 识别 Cordis service、event、`@typert object` 引用对象和 `@
 
 [`dsh-typert-registry`](../../../../packages/typert/registry/README.md) 提供 `ctx.typert`，且只负责运行时注册：一个 contribution 原子携带 package-face reflection 与可选 Zod schema，并随 Cordis effect 撤销。注册表不分析 TypeScript，也不合并两个 face。JSON Schema 是对已注册 Zod schema 的按需投影。
 
-包产物发布采用显式 opt-in。`WorkspaceTypertGenerator` 仅在被调用时校验所请求 face 的根目录产物协议：host face 必须通过面向用户的 subpath `package/typert` 暴露 `package/lib/typert.host.{js,d.ts}`，client face 必须通过 `package/client/typert` 暴露 `package/lib/typert.client.{js,d.ts}`。它既不修改 exports，也不作为根目录普通 build 或 typecheck 的一部分运行，因此这些命令不会生成全仓 Typert 产物。生成的声明将 `TYPERT` 类型保持为 `unknown`，因此业务包不依赖注册表。
+包产物发布仍通过 package exports 采用显式 opt-in。`WorkspaceTypertGenerator` 仅在被调用时校验所请求 face 的根目录产物协议：host face 必须通过面向用户的 subpath `package/typert` 暴露 `package/lib/typert.host.{js,d.ts}`，client face 必须通过 `package/client/typert` 暴露 `package/lib/typert.client.{js,d.ts}`；它不会修改这些 exports。后续的 [TypeRT Remote 设计](2026-08-02-typert-remote-method-calls.md) 为根目录 build、typecheck、lint 与文档类型检查增加了全仓 Host 契约 pass。对于已 opt-in 的 Host 包，该 pass 会在消费方解析两者之前生成本地反射产物与严格的 Host-for-Client `/remote` 契约。生成的本地声明将 `TYPERT` 类型保持为 `unknown`，因此业务包不依赖注册表。
 
 构建期的 `CordisCatalogProjector` 一次消费分析后的 `FaceModel` 与 `TypeGraph`，生成 `docs/cordis-catalog/events.md`、`docs/cordis-catalog/services.md`，以及为 `tool-cordis` 提交的静态 `SERVICE_API`、`EVENT_API` 和 `TYPE_API` catalog。`tool-cordis` 读取该静态 catalog，运行时不依赖 `ctx.typert`。[`dsh-typert-loader`](../../../../packages/typert/loader/README.md) 与注册表仍是独立的运行时路径：loader 监听 Cordis Loader 配置项生命周期事件，导入显式发布的 `./typert` host 产物，并通过 `ctx.typert` 注册；两者都不是当前 `cordis_inspect` catalog 的数据源。
 
@@ -50,4 +50,4 @@ Zod emitter 对支持的节点和各类 literal 逐类执行成功与失败 pars
 
 新增生成目标或静态检查可复用同一 TypeGraph，业务类目也可在 PackageModel 上扩展，而无需再次解析 AST。保留计算前类型和独立 face 的代价是模型比打平后的 schema 更复杂，emitter 必须显式声明支持范围并对缺失能力失败。
 
-显式 opt-in 使产物发布与 package exports 由各包自行管理，根目录普通 build 和 typecheck 不会引入全仓 Typert 生成阶段。静态 Cordis catalog 可从标准模型复现，同时不把 `tool-cordis` 与运行时注册表状态耦合。`ctx.typert` 只反映当前运行时中已挂载的产物；对于消费方直接导入后仍持有的 Zod 实例，卸载流程无法控制。
+包级显式 opt-in 使产物发布与 exports 由各包自行管理。仓库编排仍可为每个已 opt-in 的包运行全仓 Host 契约 pass；该 pass 仍由后续 Remote Gateway Agent Note 负责说明。静态 Cordis catalog 可从标准模型复现，同时不把 `tool-cordis` 与运行时注册表状态耦合。`ctx.typert` 只反映当前运行时中已挂载的产物；对于消费方直接导入后仍持有的 Zod 实例，卸载流程无法控制。
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 71ded0fa8d..d3f73c3b5c 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: 215c647bcd7413b92625ee670022dc7316e3045a
-2026-08-02-typert-remote-method-calls.zh.md: 0ce431b7cbc948e937f722f2769b15a1d26dcec9
+2026-08-02-typert-remote-method-calls.md: f3db8b9eec5eb8fb610fc58edad9313e4f715326
+2026-08-02-typert-remote-method-calls.zh.md: da4459432e8c9e08821bcded2921cbd33fc5e8c8
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index 215c647bcd..f3db8b9eec 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -217,6 +217,8 @@ Host lib build
 
 The existing top-level `build` still runs `build:lib` before `build:web`, but `build:lib` must complete the Host and Remote artifacts before starting Client TypeScript compilation. A clean build must not depend on stale `.d.ts` files from an earlier build.
 
+Compiler-backed repository gates that resolve the consumer surface have the same prerequisite even when their primary inputs are source files. The public `typecheck`, `lint`, and `doc-typecheck` commands run the Host contract pass first. The gate scheduler may use their `*:contracts-ready` variants only after an explicit TypeRT-contract or complete-build dependency, so parallel lanes neither read missing declarations nor run concurrent generators against the same outputs.
+
 ## The `/remote` package entry
 
 Every business package that provides Remote methods exports a generated `/remote` subpath:
@@ -490,6 +492,7 @@ The package topology is `api/remotes → api/gateway → client/connection → h
 
 - Goal Service directly decorates mutation methods whose business signatures already match the Remote contract and keeps `remoteExportCreate(...)` only to adapt `GoalView` into `CreateGoalResult`, without a second route, codec, or Client method list.
 - A clean `build:lib` emits Host and consumer Remote artifacts before Client compilation, including the business package's JS, DTS, and declaration map under `/remote`.
+- After `clean`, standalone `typecheck`, `lint`, and `doc-typecheck` regenerate the Remote contracts; the pre-push hook uses the same prepared typecheck, and CI source consumers wait for one shared contract pass.
 - Importing `@deepseek-ai/dsh-goal/remote` adds the strict `ctx.remote.goals.create(...)` type and declaration navigation to `remoteExportCreate`; omitting that import omits the namespace.
 - Mounting the same import's JS contribution supplies endpoint, parameter, result, lookup, Context, and Zod reflection and materializes the call without a handwritten stub.
 - Root and Agent-scoped calls cross the real shared `/api` carrier, resolve `agentId` to the live Agent, invoke the original Goal receiver, and return through the existing RPC envelope.
@@ -501,7 +504,7 @@ The package topology is `api/remotes → api/gateway → client/connection → h
 
 ## Consequences
 
-Remote API types depend on generated `lib` declarations. Build orchestration must finish the Host contract pass before compiling Host and Client consumers; an incorrect order makes a clean build depend on stale artifacts.
+Remote API types depend on generated `lib` declarations. Build and gate orchestration must finish the Host contract pass before compiling or semantically analyzing Host and Client consumers; an incorrect order makes a clean command depend on stale artifacts.
 
 Source navigation requires a Remote package to publish both its declaration map and the `src` file referenced by the map. If package `files` omits either side, types still compile but consumer navigation stops at the generated DTS. The workspace manifest check must therefore treat both as one publication contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 0ce431b7cb..da4459432e 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -217,6 +217,8 @@ Host lib build
 
 现有顶层 `build` 仍表现为先 `build:lib`、再 `build:web`，但 `build:lib` 内部必须先完成 Host 与 Remote artifact，再启动 Client TypeScript 编译。一次干净构建不能依赖上次残留的 `.d.ts`。
 
+即使主要输入是源文件，需要通过编译器解析消费方 surface 的仓库门禁也有相同的前置条件。公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先执行 Host 契约 pass。门禁调度器仅可在显式的 TypeRT 契约依赖或完整构建依赖完成后使用对应的 `*:contracts-ready` 变体，使并行 lane 既不会读取缺失的声明，也不会针对同一输出并发运行多个生成器。
+
 ## `/remote` 包入口
 
 每个提供 Remote 方法的业务包导出生成的 `/remote` 子路径：
@@ -490,6 +492,7 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 - Goal Service 直接装饰业务签名已经符合 Remote 契约的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
 - 一次干净的 `build:lib` 会在 Client 编译前生成 Host 与消费方 Remote 产物，包括业务包 `/remote` 下的 JS、DTS 和 declaration map。
+- `clean` 后，单独运行 `typecheck`、`lint` 或 `doc-typecheck` 都会重新生成 Remote 契约；pre-push 钩子使用同一个已包含契约准备步骤的 typecheck，CI 中的源码消费方则等待一次共享的契约 pass。
 - 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `ctx.remote.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
 - 挂载同一次 import 得到的 JS contribution 会提供 endpoint、参数、结果、lookup、Context 和 Zod 反射，并在无需手写 stub 的情况下实体化调用。
 - Root 与 Agent-scoped 调用会经过真实的共享 `/api` carrier，将 `agentId` 解析为活 Agent，调用原始 Goal receiver，并通过既有 RPC envelope 返回。
@@ -501,7 +504,7 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 ## 后果
 
-Remote API 类型依赖生成的 `lib` 声明，构建编排必须在 Host 和 Client 消费端编译前完成 contract pass；顺序错误会让干净构建依赖陈旧产物。
+Remote API 类型依赖生成的 `lib` 声明，构建与门禁编排必须在对 Host 和 Client 消费方进行编译或语义分析之前完成 Host 契约 pass；顺序错误会使干净环境中的命令依赖陈旧产物。
 
 源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布契约。
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 4ef3010835..8ca8d518e3 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: 60a7ccc87e2c33e66b3d966a2907d31bb0b1efd8
-development.zh.md: 6607705be7e9f548b4f44555ad8c6cc8c2d34964
+development.md: 172d3bd3298f286e621da5fde0ec1620c10583ac
+development.zh.md: c9c594836319816fdcb5cf9d5ceada74e17ef97b
diff --git a/docs/development.md b/docs/development.md
index 60a7ccc87e..172d3bd329 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -75,7 +75,7 @@ Both tsdown passes use the same complete workspace match. They neither scan buil
 
 TypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.
 
-Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology and the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership.
+Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while scheduler-only `*:contracts-ready` scripts run only after an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.
 
 Business services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
 
@@ -103,7 +103,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 lefthook is configured in `lefthook.yml` as a fast local checkpoint:
 
 - `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
-- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).
+- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.
 
 The vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 6607705be7..c9c5948363 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -75,7 +75,7 @@ pnpm run build:web
 
 TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
 
-静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。
+静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而仅供调度器使用的 `*:contracts-ready` 脚本只会在显式依赖 TypeRT 契约 pass 或完整构建后运行。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
 
 业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
 
@@ -103,7 +103,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
 - `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
-- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。
+- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
 
diff --git a/lefthook.yml b/lefthook.yml
index bdab57a9a3..fda1df0b95 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -37,4 +37,4 @@ pre-commit:
 pre-push:
   jobs:
     - name: typecheck
-      run: node_modules/.bin/tsc -b --pretty false
+      run: pnpm run typecheck
diff --git a/package.json b/package.json
index 981ce68707..9ba13ce689 100644
--- a/package.json
+++ b/package.json
@@ -21,9 +21,12 @@
     "build:web": "pnpm --filter @deepseek-ai/dsh-frontend run build",
     "clean": "tsx scripts/clean.ts",
     "change-scope": "tsx scripts/change-scope.ts",
-    "typecheck": "npm run build:lib:host && tsc -b tsconfig.client.json",
-    "lint": "tsx scripts/run-oxlint.ts .",
-    "lint:fix": "eslint --config eslint.format.config.mjs --fix . && tsx scripts/run-oxlint.ts . --fix",
+    "typecheck": "npm run build:lib:host && npm run typecheck:contracts-ready",
+    "typecheck:contracts-ready": "tsc -b tsconfig.client.json",
+    "lint": "npm run build:lib:host && npm run lint:contracts-ready",
+    "lint:contracts-ready": "tsx scripts/run-oxlint.ts .",
+    "lint:fix": "npm run build:lib:host && npm run lint:fix:contracts-ready",
+    "lint:fix:contracts-ready": "eslint --config eslint.format.config.mjs --fix . && tsx scripts/run-oxlint.ts . --fix",
     "duplication": "jscpd --config .jscpd.json packages scripts",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
@@ -45,6 +48,7 @@
     "check:ci:linux-primary": "tsx scripts/run-gates.ts ci-linux-primary",
     "check:ci:static": "tsx scripts/run-gates.ts ci-static",
     "check:ci:lint": "tsx scripts/run-gates.ts ci-lint",
+    "check:ci:lint:contracts-ready": "tsx scripts/run-gates.ts ci-lint-contracts-ready",
     "check:ci:coverage": "tsx scripts/run-gates.ts ci-coverage",
     "check:ci:snapshot": "tsx scripts/run-gates.ts ci-snapshot",
     "check:ci:artifacts": "tsx scripts/run-gates.ts ci-artifacts",
@@ -56,7 +60,8 @@
     "check:node-compat": "tsx scripts/run-gates.ts node-compat",
     "knip": "knip --treat-config-hints-as-errors",
     "publint": "tsx scripts/publint-all.ts",
-    "doc-typecheck": "tsx scripts/doc-typecheck.ts",
+    "doc-typecheck": "npm run build:lib:host && npm run doc-typecheck:contracts-ready",
+    "doc-typecheck:contracts-ready": "tsx scripts/doc-typecheck.ts",
     "verify-md-wrap": "tsx scripts/verify-md-wrap.ts",
     "verify-md-links": "tsx scripts/verify-md-links.ts",
     "verify-public-repository-links": "tsx scripts/verify-public-repository-links.ts",
diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts
index 6979fb894d..d0389af483 100644
--- a/scripts/run-gates.spec.ts
+++ b/scripts/run-gates.spec.ts
@@ -60,6 +60,7 @@ describe('gate graph validation', () => {
     'ci-linux-primary',
     'ci-static',
     'ci-lint',
+    'ci-lint-contracts-ready',
     'ci-coverage',
     'ci-snapshot',
     'ci-artifacts',
@@ -141,6 +142,57 @@ describe('Oxlint gate', () => {
   })
 })
 
+describe('TypeRT contract preparation', () => {
+  it('prepares primary source consumers once before they run', () => {
+    const subject = withPnpmEntrypoint(() => gatesForMode('ci-primary'))
+
+    expect(subject.find(item => item.id === 'typert-contracts')).toMatchObject({
+      displayCommand: 'pnpm run build:lib:host',
+      args: ['/private/pnpm.cjs', 'run', 'build:lib:host'],
+    })
+    for (const [id, script] of [
+      ['typecheck', 'typecheck:contracts-ready'],
+      ['lint', 'lint:contracts-ready'],
+      ['doc-typecheck', 'doc-typecheck:contracts-ready'],
+    ] as const) {
+      expect(subject.find(item => item.id === id)).toMatchObject({
+        displayCommand: `pnpm run ${script}`,
+        args: ['/private/pnpm.cjs', 'run', script],
+        needs: ['typert-contracts'],
+      })
+    }
+    expect(subject.find(item => item.id === 'build')?.needs).toEqual([
+      'typecheck',
+      'lint',
+      'doc-typecheck',
+    ])
+  })
+
+  it('reuses contracts from the validated consumer build', () => {
+    const subject = withPnpmEntrypoint(() => gatesForMode('ci-consumers'))
+
+    expect(subject.find(item => item.id === 'lint-and-duplication')).toMatchObject({
+      displayCommand: 'pnpm run check:ci:lint:contracts-ready',
+      args: ['/private/pnpm.cjs', 'run', 'check:ci:lint:contracts-ready'],
+    })
+    expect(subject.find(item => item.id === 'doc-typecheck')).toMatchObject({
+      displayCommand: 'pnpm run doc-typecheck:contracts-ready',
+      args: ['/private/pnpm.cjs', 'run', 'doc-typecheck:contracts-ready'],
+    })
+  })
+
+  it('keeps standalone aggregates responsible for preparation', () => {
+    const lint = withPnpmEntrypoint(() => gatesForMode('ci-lint')[0])
+    const preparedLint = withPnpmEntrypoint(() => gatesForMode('ci-lint-contracts-ready')[0])
+    const docTypecheck = withPnpmEntrypoint(() =>
+      gatesForMode('doc-sync').find(item => item.id === 'doc-typecheck'))
+
+    expect(lint?.displayCommand).toBe('pnpm run lint')
+    expect(preparedLint?.displayCommand).toBe('pnpm run lint:contracts-ready')
+    expect(docTypecheck?.displayCommand).toBe('pnpm run doc-typecheck')
+  })
+})
+
 describe('Node compatibility graph', () => {
   it('runs the jsdom environment smoke on every advertised Node line', () => {
     const subject = withPnpmEntrypoint(() => gatesForMode('node-compat'))
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 8e6f336e96..f3ef6850b1 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -17,6 +17,7 @@ export type Mode =
   | 'ci-linux-primary'
   | 'ci-static'
   | 'ci-lint'
+  | 'ci-lint-contracts-ready'
   | 'ci-coverage'
   | 'ci-snapshot'
   | 'ci-artifacts'
@@ -102,6 +103,7 @@ function parseMode(raw: string | undefined): Mode {
     case 'ci-linux-primary':
     case 'ci-static':
     case 'ci-lint':
+    case 'ci-lint-contracts-ready':
     case 'ci-coverage':
     case 'ci-snapshot':
     case 'ci-artifacts':
@@ -115,7 +117,7 @@ function parseMode(raw: string | undefined): Mode {
       return raw
     default:
       throw new Error(
-        `run-gates: expected mode ci-primary | ci-linux-primary | ci-static | ci-lint | ci-coverage | ci-snapshot | ci-artifacts | ci-consumers | ci-windows-blocking | ci-windows-complete | ci-windows-observational | node-compat | check-all | doc-sync, got ${JSON.stringify(raw)}.`,
+        `run-gates: expected mode ci-primary | ci-linux-primary | ci-static | ci-lint | ci-lint-contracts-ready | ci-coverage | ci-snapshot | ci-artifacts | ci-consumers | ci-windows-blocking | ci-windows-complete | ci-windows-observational | node-compat | check-all | doc-sync, got ${JSON.stringify(raw)}.`,
       )
   }
 }
@@ -202,6 +204,11 @@ export function gatesForMode(selected: Mode): Gate[] {
         lintGate(),
         pnpmScript('duplication', 'duplication'),
       ]
+    case 'ci-lint-contracts-ready':
+      return [
+        lintGate({ contractsReady: true }),
+        pnpmScript('duplication', 'duplication'),
+      ]
     case 'ci-coverage':
       return coverageGates()
     case 'ci-snapshot':
@@ -233,6 +240,7 @@ export function gatesForMode(selected: Mode): Gate[] {
         ...docSyncLeafGates({
           docTypecheckNeeds: ['build'],
           docTypecheckEnv: { DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1' },
+          docTypecheckScript: 'doc-typecheck:contracts-ready',
         }),
         pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
       ]
@@ -254,19 +262,23 @@ function ciSharedStaticGates(): Gate[] {
 function ciPrimaryGates(): Gate[] {
   return [
     ...ciSharedStaticGates(),
-    pnpmScript('typecheck', 'typecheck'),
-    lintGate(),
+    typertContractsGate(),
+    pnpmScript('typecheck', 'typecheck:contracts-ready', { needs: ['typert-contracts'] }),
+    lintGate({ contractsReady: true, needs: ['typert-contracts'] }),
     pnpmScript('duplication', 'duplication'),
     ...coverageGates(),
     ...nodeCompatSmokeGates(),
     snapshotGate(),
-    ...docSyncLeafGates(),
+    ...docSyncLeafGates({
+      docTypecheckNeeds: ['typert-contracts'],
+      docTypecheckScript: 'doc-typecheck:contracts-ready',
+    }),
     pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
     pnpmScript('knip', 'knip'),
-    // typecheck and build both drive the Host and Client tsc graphs; without
-    // the dependency concurrent runs race the same tsbuildinfo files.
-    // The tsc step is an incremental no-op after typecheck.
-    pnpmScript('build', 'build', { needs: ['typecheck'] }),
+    // The prepared typecheck and build both drive Client tsc, while build also
+    // repeats the Host contract pass. Wait for all three consumers so build
+    // neither races tsbuildinfo nor replaces declarations while they are read.
+    pnpmScript('build', 'build', { needs: ['typecheck', 'lint', 'doc-typecheck'] }),
     pnpmScript('publint', 'publint', { needs: ['build'] }),
     pnpmScript('node-next-types', 'verify-node-next-types', {
       label: 'node-next types',
@@ -355,6 +367,7 @@ function ciStaticGates(options: { ownsBuild: boolean }): Gate[] {
         ? {
           docTypecheckNeeds: ['build'],
           docTypecheckEnv: { DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1' },
+          docTypecheckScript: 'doc-typecheck:contracts-ready',
         }
         : {},
       docsBuildScript: 'docs:build:mpa',
@@ -385,13 +398,13 @@ function ciConsumerGates(): Gate[] {
     pnpmScript('node-compat', 'check:node-compat', { label: 'Node compatibility' }),
     pnpmScript('publint', 'publint', { needs: builtTree }),
     builtPackageInvariantsGate(['publint']),
-    pnpmScript('lint-and-duplication', 'check:ci:lint', {
+    pnpmScript('lint-and-duplication', 'check:ci:lint:contracts-ready', {
       label: 'lint and duplication',
       needs: validatedBuild,
     }),
     snapshotGate(validatedBuild),
     webSnapshotGate(validatedBuild),
-    pnpmScript('doc-typecheck', 'doc-typecheck', {
+    pnpmScript('doc-typecheck', 'doc-typecheck:contracts-ready', {
       needs: validatedBuild,
       env: { DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1' },
     }),
@@ -447,11 +460,19 @@ function ciWindowsObservationalGates(): Gate[] {
   ]
 }
 
-function lintGate(): Gate {
+function typertContractsGate(): Gate {
+  return pnpmScript('typert-contracts', 'build:lib:host', { label: 'TypeRT contracts' })
+}
+
+function lintGate(options: { contractsReady?: boolean; needs?: string[] } = {}): Gate {
   const raw = process.env.DSH_OXLINT_THREADS
-  return pnpmScript('lint', 'lint', raw === undefined || raw === ''
-    ? {}
-    : { displayCommand: `DSH_OXLINT_THREADS=${raw} pnpm run lint` })
+  const script = options.contractsReady === true ? 'lint:contracts-ready' : 'lint'
+  return pnpmScript('lint', script, {
+    ...raw === undefined || raw === ''
+      ? {}
+      : { displayCommand: `DSH_OXLINT_THREADS=${raw} pnpm run ${script}` },
+    ...options.needs === undefined ? {} : { needs: options.needs },
+  })
 }
 
 // The heavy suites run uninstrumented beside the thresholded gate: their
@@ -554,6 +575,7 @@ function docSyncLeafGates(options: {
   includeDocTypecheck?: boolean
   docTypecheckNeeds?: string[]
   docTypecheckEnv?: Record<string, string | undefined>
+  docTypecheckScript?: 'doc-typecheck' | 'doc-typecheck:contracts-ready'
   docsBuildScript?: 'docs:build' | 'docs:build:mpa'
 } = {}): Gate[] {
   const docTypecheckOptions: Partial<Gate> = {}
@@ -562,7 +584,7 @@ function docSyncLeafGates(options: {
   return [
     ...options.includeDocTypecheck === false
       ? []
-      : [pnpmScript('doc-typecheck', 'doc-typecheck', docTypecheckOptions)],
+      : [pnpmScript('doc-typecheck', options.docTypecheckScript ?? 'doc-typecheck', docTypecheckOptions)],
     pnpmScript('cordis-catalog', 'verify-cordis-catalog', { label: 'cordis catalog' }),
     pnpmScript('export-jsdoc', 'verify-export-jsdoc', { label: 'export jsdoc' }),
     pnpmScript('tool-catalog', 'verify-tool-catalog', { label: 'tool catalog' }),

From 00ed703c21fd7afb492fa9eecec88459d5cfac2c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 02:35:02 +0800
Subject: [PATCH 221/516] test(i18n): refresh development prompt snapshot

---
 .../translation-prompt-v4/request-response.expected.json      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 0748e762dd..43611a4cd5 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology and the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs only the incremental repository typecheck (`tsc -b` over the root solution, covering both the host and client aggregates).\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while scheduler-only `*:contracts-ready` scripts run only after an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 只运行仓库增量类型检查（对根 solution 执行 `tsc -b`，覆盖 host 与 client 两个聚合）。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而仅供调度器使用的 `*:contracts-ready` 脚本只会在显式依赖 TypeRT 契约 pass 或完整构建后运行。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",

From 4b73aa153eb079e32e54b9dbcc7dac8b6fdb805a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 14:29:09 +0800
Subject: [PATCH 222/516] test(gates): isolate TypeRT graph assertions

---
 scripts/run-gates.spec.ts | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts
index d0389af483..e45383b481 100644
--- a/scripts/run-gates.spec.ts
+++ b/scripts/run-gates.spec.ts
@@ -144,7 +144,8 @@ describe('Oxlint gate', () => {
 
 describe('TypeRT contract preparation', () => {
   it('prepares primary source consumers once before they run', () => {
-    const subject = withPnpmEntrypoint(() => gatesForMode('ci-primary'))
+    const subject = withEnv('DSH_OXLINT_THREADS', undefined, () =>
+      withPnpmEntrypoint(() => gatesForMode('ci-primary')))
 
     expect(subject.find(item => item.id === 'typert-contracts')).toMatchObject({
       displayCommand: 'pnpm run build:lib:host',
@@ -182,10 +183,11 @@ describe('TypeRT contract preparation', () => {
   })
 
   it('keeps standalone aggregates responsible for preparation', () => {
-    const lint = withPnpmEntrypoint(() => gatesForMode('ci-lint')[0])
-    const preparedLint = withPnpmEntrypoint(() => gatesForMode('ci-lint-contracts-ready')[0])
-    const docTypecheck = withPnpmEntrypoint(() =>
-      gatesForMode('doc-sync').find(item => item.id === 'doc-typecheck'))
+    const [lint, preparedLint, docTypecheck] = withEnv('DSH_OXLINT_THREADS', undefined, () => [
+      withPnpmEntrypoint(() => gatesForMode('ci-lint')[0]),
+      withPnpmEntrypoint(() => gatesForMode('ci-lint-contracts-ready')[0]),
+      withPnpmEntrypoint(() => gatesForMode('doc-sync').find(item => item.id === 'doc-typecheck')),
+    ])
 
     expect(lint?.displayCommand).toBe('pnpm run lint')
     expect(preparedLint?.displayCommand).toBe('pnpm run lint:contracts-ready')

From 041119648924750dd4a8eb44afe3bbd5219a58ca Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:03:14 +0800
Subject: [PATCH 223/516] fix(gates): address TypeRT review gaps

---
 .../2026-07-22-fast-local-git-hooks.i18n.yaml |  4 +--
 .../2026-07-22-fast-local-git-hooks.md        |  6 ++--
 .../2026-07-22-fast-local-git-hooks.zh.md     |  6 ++--
 .../2026-07-29-oxlint-linter.i18n.yaml        |  4 +--
 .../process/2026-07-29-oxlint-linter.md       |  8 ++---
 .../process/2026-07-29-oxlint-linter.zh.md    |  8 ++---
 .oxlintrc.staged.json                         |  7 ++++
 docs/development.i18n.yaml                    |  4 +--
 docs/development.md                           |  4 +--
 docs/development.zh.md                        |  4 +--
 lefthook.yml                                  |  2 +-
 package.json                                  |  1 -
 scripts/oxlint-contract.spec.ts               | 33 +++++++++++++++++++
 scripts/run-gates.spec.ts                     | 24 +++++---------
 scripts/run-gates.ts                          | 17 +++-------
 .../request-response.expected.json            |  4 +--
 16 files changed, 81 insertions(+), 55 deletions(-)
 create mode 100644 .oxlintrc.staged.json

diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
index d712a411b9..e7f76356e2 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.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 .agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
-2026-07-22-fast-local-git-hooks.md: 838024c4293372b1430d357774feb06cd9742b9b
-2026-07-22-fast-local-git-hooks.zh.md: 26968dd19ffb42f4a618dc760b2a6edeb4900393
+2026-07-22-fast-local-git-hooks.md: af8a9380fc3cbf4f672ca0b32faa7b187522cf11
+2026-07-22-fast-local-git-hooks.zh.md: 04f3a407e421c4d585b8b78b16b9055fd19ac756
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
index 838024c429..af8a9380fc 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
@@ -12,9 +12,9 @@ Fast hooks still need to reject cheap, high-confidence defects before work leave
 
 ## Decision
 
-[lefthook.yml](../../../../lefthook.yml) keeps both hooks as bounded local checkpoints. Pre-commit runs sequentially: a formatting-only ESLint config fixes and re-stages changed JavaScript and TypeScript, [Oxlint](2026-07-29-oxlint-linter.md) validates those files and applies native safe fixes, `git diff --cached --check` rejects staged whitespace errors, and the vendor manifest guard checks vendored-source metadata. Pre-push invokes the repository TypeScript binary directly in incremental build mode.
+[lefthook.yml](../../../../lefthook.yml) keeps both hooks as bounded local checkpoints. Pre-commit runs sequentially: a formatting-only ESLint config fixes and re-stages changed JavaScript and TypeScript, a project-free [Oxlint](2026-07-29-oxlint-linter.md) profile validates those files and applies native safe fixes, `git diff --cached --check` rejects staged whitespace errors, and the vendor manifest guard checks vendored-source metadata. Pre-push runs `pnpm run typecheck`, which prepares the generated Host TypeRT contracts before the Client incremental typecheck.
 
-Neither hook runs tests, snapshots, documentation checks, builds, hygiene, or the gate scheduler. The opt-in `check:all` package script selects the `check-all` scheduler inventory in [scripts/run-gates.ts](../../../../scripts/run-gates.ts) independently of the hooks; it is a contributor command, not an agent instruction.
+Pre-commit does not run type analysis, tests, snapshots, documentation checks, builds, hygiene, or the gate scheduler. Pre-push adds only the Host contract build required by repository typecheck. The opt-in `check:all` package script selects the `check-all` scheduler inventory in [scripts/run-gates.ts](../../../../scripts/run-gates.ts) independently of the hooks; it is a contributor command, not an agent instruction.
 
 Agents inspect the outgoing diff and run the narrowest tests and checks that cover its behavior once. CI owns exhaustive coverage, built-artifact checks, and the platform matrix. A complete local rehearsal is reserved for an explicit request, CI diagnosis, or a repository-wide change that cannot be validated credibly by narrower evidence.
 
@@ -31,6 +31,6 @@ This decision supersedes the local-hook portion of [Parallel pre-push gates](202
 
 ## Consequences
 
-Normal commits take the staged formatter-and-lint critical path, and warm pushes take the incremental typecheck critical path. Contributors retain a one-command opt-in rehearsal without widening the hook critical paths or the agent-required validation set. Hook latency is observed in development and PR evidence rather than enforced by a timing test whose result would depend on host load and cache state.
+Normal commits take the project-free staged formatter-and-lint critical path, and warm pushes take the prepared incremental typecheck critical path. Contributors retain a one-command opt-in rehearsal without widening the hook critical paths or the agent-required validation set. Hook latency is observed in development and PR evidence rather than enforced by a timing test whose result would depend on host load and cache state.
 
 Local publication no longer proves the exhaustive repository matrix. Agents must select relevant behavioral evidence, reviewers must evaluate whether that selection matches the diff, and CI supplies the comprehensive signal once per pushed revision.
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
index 26968dd19f..04f3a407e4 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
@@ -12,9 +12,9 @@ agent（智能体）已经会运行能够覆盖自身改动的测试和检查，
 
 ## 决策
 
-[lefthook.yml](../../../../lefthook.yml) 将两个钩子都保留为有界的本地检查点。Pre-commit 按顺序运行：仅用于格式化的 ESLint 配置修复改动过的 JavaScript 和 TypeScript 文件并重新暂存，[Oxlint](2026-07-29-oxlint-linter.md) 验证这些文件并应用原生安全修复，`git diff --cached --check` 拒绝暂存 diff 中的空白错误，vendor manifest（元数据清单）守卫检查 vendor 源码元数据。Pre-push 直接调用仓库内的 TypeScript 二进制，并启用增量构建模式。
+[lefthook.yml](../../../../lefthook.yml) 将两个钩子都保留为有界的本地检查点。Pre-commit 按顺序运行：仅用于格式化的 ESLint 配置修复改动过的 JavaScript 和 TypeScript 文件并重新暂存，不加载项目的 [Oxlint](2026-07-29-oxlint-linter.md) 配置验证这些文件并应用原生安全修复，`git diff --cached --check` 拒绝暂存 diff 中的空白错误，vendor manifest（元数据清单）守卫检查 vendor 源码元数据。Pre-push 运行 `pnpm run typecheck`；该命令会先准备好生成的 Host TypeRT 契约，再运行 Client 增量类型检查。
 
-两个钩子都不运行测试、快照、文档检查、构建、`hygiene` 或门禁调度器。可选运行的 `check:all` 包脚本独立于这些钩子，从 [scripts/run-gates.ts](../../../../scripts/run-gates.ts) 中选择 `check-all` 调度器清单；它是贡献者命令，而非对 agent 的指令。
+Pre-commit 不运行类型分析、测试、快照、文档检查、构建、`hygiene` 或门禁调度器。Pre-push 只增加仓库类型检查所需的 Host 契约构建。可选运行的 `check:all` 包脚本独立于这些钩子，从 [scripts/run-gates.ts](../../../../scripts/run-gates.ts) 中选择 `check-all` 调度器清单；它是贡献者命令，而非对 agent 的指令。
 
 agent 检查待推送的 diff，并仅运行一次能够覆盖其行为的最小范围测试和检查。CI 负责全量覆盖率门禁、构建产物检查与平台矩阵。只有在明确要求、诊断 CI，或涉及全仓库的改动无法由范围更窄的证据得到可信验证时，才完整运行一遍本地检查矩阵。
 
@@ -31,6 +31,6 @@ agent 检查待推送的 diff，并仅运行一次能够覆盖其行为的最小
 
 ## 结果
 
-普通提交的关键路径是暂存文件格式化与 lint，缓存已预热时推送的关键路径是增量类型检查。贡献者仍可选择用一条命令完整演练，且不会扩展钩子关键路径或 agent 必须运行的验证集合。钩子耗时只作为开发观察数据和 PR（Pull Request）证据记录，不设置会受主机负载与缓存状态影响的计时测试。
+普通提交的关键路径是不加载项目的暂存文件格式化与 lint，缓存已预热时推送的关键路径是经过准备的增量类型检查。贡献者仍可选择用一条命令完整演练，且不会扩展钩子关键路径或 agent 必须运行的验证集合。钩子耗时只作为开发观察数据和 PR（Pull Request）证据记录，不设置会受主机负载与缓存状态影响的计时测试。
 
 从本地推送成功不再能证明仓库完整矩阵已通过。agent 必须选择相关的行为证据，评审人必须判断该选择是否与 diff 相符，CI 则对每个推送版本提供一次全面信号。
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
index ae7c705d5d..4aec3f6a4f 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.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 .agents/notes/implemented/process/2026-07-29-oxlint-linter.md
-2026-07-29-oxlint-linter.md: 41a50a9d08819809f954aa99007081f270692f38
-2026-07-29-oxlint-linter.zh.md: 85d053af867353ff1b4c53822013f55660c89cca
+2026-07-29-oxlint-linter.md: 3e3de24be33b8f9461cea2967b0fa18f59ddb52a
+2026-07-29-oxlint-linter.zh.md: 5388416b54a5ff44b9ab9551d726705a84a8b1a1
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md
index 41a50a9d08..3e3de24be3 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md
@@ -12,19 +12,19 @@ A faster runner cannot justify losing rules. The migration must preserve the str
 
 ## Decision
 
-The root [`.oxlintrc.json`](../../../../.oxlintrc.json) is the authoritative repository lint configuration. The `lint` package script, gate scheduler, CI, and lefthook invoke Oxlint through [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts) for repository-wide, type-aware, or staged validation. The `lint:fix` script and lefthook first invoke the formatting-only [`eslint.format.config.mjs`](../../../../eslint.format.config.mjs), then run Oxlint. The direct `eslint` and `@typescript-eslint/parser` development dependencies exist only for this parser-without-project formatting pass; their exact versions pin the tested parser/fixer pairing, and that config contains no correctness or type-aware rules.
+The root [`.oxlintrc.json`](../../../../.oxlintrc.json) is the authoritative type-aware repository lint configuration. The project-free [`.oxlintrc.staged.json`](../../../../.oxlintrc.staged.json) profile inherits its source rules but disables type analysis for the bounded pre-commit path. The `lint` package script, gate scheduler, CI, and lefthook invoke Oxlint through [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts); `lint:fix` and lefthook first invoke the formatting-only [`eslint.format.config.mjs`](../../../../eslint.format.config.mjs). The direct `eslint` and `@typescript-eslint/parser` development dependencies exist only for this parser-without-project formatting pass; their exact versions pin the tested parser/fixer pairing, and that config contains no correctness or type-aware rules.
 
 `options.typeAware` enables `oxlint-tsgolint`. Its backend performs per-file TypeScript-project discovery: package sources use their package projects, host tests/examples/website use `tsconfig.host.json`, and client tests plus `scripts/client-bundle-purity.spec.ts` use `tsconfig.client.json`. The program-less root solution is never flattened. Oxlint's `--tsconfig` override affects import resolution but is ignored by type-aware linting, so this repository does not set it. The configuration explicitly carries the migrated strict-type-checked rules and repository overrides instead of enabling broad Oxlint categories whose contents may change. `typescript/no-unnecessary-condition` remains enabled from Oxlint's nursery set because it was an enforced repository rule before migration.
 
 Oxlint's JavaScript-plugin compatibility layer runs `@stylistic/eslint-plugin` and `eslint-plugin-sonarjs` so the existing formatting and file-local duplicate-logic rules remain enforced. The compatibility layer reports `@stylistic` violations but does not execute their fixers, so the formatting-only ESLint pass owns only the corresponding auto-fixes; an executable parity check keeps those fixable rule definitions aligned while `max-len` remains validation-only. Owned-source suppressions use `oxlint-*` directives and the `typescript/*` namespace, and unused directives remain warnings; vendored sources keep their upstream directives because Oxlint excludes `vendor/**`.
 
-CI does not restore or save a lint-result cache. `DSH_OXLINT_THREADS` makes the shared runner pass the same bound to Oxlint's `--threads` option and the type-aware backend's `GOMAXPROCS` environment variable; ordinary local runs use both defaults. Pre-commit applies the formatting-only ESLint fixes, runs Oxlint validation and native safe fixes, accepts selections containing only ignored files, and re-stages the result through lefthook.
+CI does not restore or save a lint-result cache. `DSH_OXLINT_THREADS` makes the shared runner pass the same bound to Oxlint's `--threads` option and the type-aware backend's `GOMAXPROCS` environment variable; ordinary local runs use both defaults. Pre-commit applies the formatting-only ESLint fixes, runs project-free Oxlint validation and native safe fixes, accepts selections containing only ignored files, and re-stages the result through lefthook. Public `lint` and CI retain the complete type-aware rules after preparing generated declarations.
 
 ## Verification
 
 The migrated configuration reports the same clean owned-source baseline after resolving two analyzer differences: one redundant test assertion was removed, while one structural cast required by `tsc` carries a narrow Oxlint suppression. A one-time audit against the exact deleted ESLint configuration blob established source 88-to-88, examples 87-to-87, and tests 83-to-83 after the rule-name translations. The committed fingerprint pins those audited Oxlint profiles and the complete override shape; it neither executes the deleted configuration nor propagates later upstream preset changes. Evaluating `typescript-eslint@8.61.0` also confirms that `strictTypeChecked` did not enable `@typescript-eslint/no-empty-function`; the deleted tests-only `off` entry was inert.
 
-Executable contract tests require type-aware diagnostics from the package, host, and client projects; assert the client-only script's project; reject unmatched fallback analysis; and exercise the Stylistic, SonarJS, and nursery compatibility paths. They also pin unused-suppression reporting, ignored-only staged selections, formatter/validator rule parity, and final formatted bytes. Runner tests pin both worker controls, and typecheck confirms that migration-driven source edits preserve the TypeScript programs.
+Executable contract tests require type-aware diagnostics from the package, host, and client projects; assert the client-only script's project; reject unmatched fallback analysis; and exercise the Stylistic, SonarJS, and nursery compatibility paths. They also pin the staged profile's project-free inheritance, unused-suppression reporting, ignored-only staged selections, formatter/validator rule parity, and final formatted bytes. Runner tests pin both worker controls, and typecheck confirms that migration-driven source edits preserve the TypeScript programs.
 
 ## Alternatives considered
 
@@ -42,4 +42,4 @@ Local migration measurements reduced a clean type-aware lint run from about 61 s
 
 Type-aware diagnostics now come from the TypeScript Go analyzer bundled through `oxlint-tsgolint`, so edge-case inference can differ from typescript-eslint even when `tsc` accepts the same program. Lint and typecheck remain separate required evidence.
 
-The JavaScript-plugin compatibility API and staged formatter are additional boundaries to maintain. Commits pay one project-free ESLint startup before Oxlint, and the root development graph retains ESLint plus the TypeScript parser. Repository-wide validation, type-aware analysis, cache policy, worker control, and inline directives remain Oxlint-owned.
+The JavaScript-plugin compatibility API, staged profile, and staged formatter are additional boundaries to maintain. Commits defer type-aware diagnostics to public lint and CI, pay one project-free ESLint startup before Oxlint, and avoid depending on generated declarations. The root development graph retains ESLint plus the TypeScript parser. Repository-wide validation, type-aware analysis, cache policy, worker control, and inline directives remain Oxlint-owned.
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
index 85d053af86..5388416b54 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
@@ -12,19 +12,19 @@ Status: implemented
 
 ## 决策
 
-根目录的 [`.oxlintrc.json`](../../../../.oxlintrc.json) 是仓库 lint 配置的权威来源。`lint` 包脚本、门禁调度器、CI 和 lefthook 通过 [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts) 调用 Oxlint，进行全仓库、类型感知或暂存验证。`lint:fix` 脚本和 lefthook 先调用仅用于格式化的 [`eslint.format.config.mjs`](../../../../eslint.format.config.mjs)，再运行 Oxlint。直接的 `eslint` 和 `@typescript-eslint/parser` 开发依赖仅用于这次不加载项目的格式化流程；其精确版本锁定经过测试的解析器与修复器配对，该配置不包含正确性规则或类型感知规则。
+根目录的 [`.oxlintrc.json`](../../../../.oxlintrc.json) 是仓库类型感知 lint 配置的权威来源。不加载项目的 [`.oxlintrc.staged.json`](../../../../.oxlintrc.staged.json) 配置继承其源码规则，但会为有界的 pre-commit 路径禁用类型分析。`lint` 包脚本、门禁调度器、CI 和 lefthook 通过 [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts) 调用 Oxlint；`lint:fix` 和 lefthook 会先调用仅用于格式化的 [`eslint.format.config.mjs`](../../../../eslint.format.config.mjs)。直接的 `eslint` 和 `@typescript-eslint/parser` 开发依赖仅用于这次不加载项目的格式化流程；其精确版本锁定经过测试的解析器与修复器配对，该配置不包含正确性规则或类型感知规则。
 
 `options.typeAware` 启用 `oxlint-tsgolint`。其后端按文件发现 TypeScript 项目：包源码使用各自的包项目，host 测试、示例和网站使用 `tsconfig.host.json`，client 测试及 `scripts/client-bundle-purity.spec.ts` 使用 `tsconfig.client.json`。不含程序的根解决方案绝不会被扁平化。Oxlint 的 `--tsconfig` 覆盖项会影响导入解析，但类型感知 lint 会忽略它，因此本仓库不设置该选项。该配置显式载入迁移后的严格类型检查规则和仓库覆盖配置，而不启用内容可能发生变化的 Oxlint 宽泛类别。`typescript/no-unnecessary-condition` 仍从 Oxlint 的 nursery 规则集中启用，因为它在迁移前就是仓库强制执行的规则。
 
 Oxlint 的 JavaScript 插件兼容层运行 `@stylistic/eslint-plugin` 和 `eslint-plugin-sonarjs`，从而继续强制执行现有的格式和文件内重复逻辑规则。兼容层会报告 `@stylistic` 违规，但不会执行其修复器，因此仅用于格式化的 ESLint 流程只负责相应的自动修复；一项可执行检查确保这些可修复规则定义保持一致，而 `max-len` 仅用于验证。自有源码中的抑制指令使用 `oxlint-*` 指令和 `typescript/*` 命名空间，未使用的指令仍作为警告报告；vendor 源码保留其上游指令，因为 Oxlint 会排除 `vendor/**`。
 
-CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行器将同一上限传给 Oxlint 的 `--threads` 选项和类型感知后端的 `GOMAXPROCS` 环境变量；普通本地运行对两者均采用默认值。Pre-commit 应用仅用于格式化的 ESLint 修复，运行 Oxlint 验证和原生安全修复，接受仅含已忽略文件的文件选择，并通过 lefthook 重新暂存结果。
+CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行器将同一上限传给 Oxlint 的 `--threads` 选项和类型感知后端的 `GOMAXPROCS` 环境变量；普通本地运行对两者均采用默认值。Pre-commit 应用仅用于格式化的 ESLint 修复，运行不加载项目的 Oxlint 验证并应用原生安全修复，接受仅含已忽略文件的文件选择，并通过 lefthook 重新暂存结果。公共 `lint` 和 CI 会先准备生成的声明，并保留完整的类型感知规则。
 
 ## 验证
 
 解决两处分析器差异后，迁移后的配置报告与迁移前一致的自有源码无问题基线：移除了一项冗余测试断言，而 `tsc` 要求的一处结构性类型转换使用了窄范围的 Oxlint 抑制指令。以已删除 ESLint 配置的精确 blob 为基准进行的一次性审核在完成规则名映射后确认：源码为 88 项对 88 项，示例为 87 项对 87 项，测试为 83 项对 83 项。已提交的指纹锁定这些经审核的 Oxlint 规则配置及完整的覆盖结构；它既不执行已删除的配置，也不纳入后续的上游预设变更。对 `typescript-eslint@8.61.0` 的评估还确认，`strictTypeChecked` 并未启用 `@typescript-eslint/no-empty-function`；已删除、仅用于测试的 `off` 条目不起作用。
 
-可执行契约测试要求包、host 和 client 项目产生类型感知诊断，断言 client 专用脚本所用的项目，拒绝未匹配的回退分析，并检验 Stylistic、SonarJS 和 nursery 兼容路径。它们还锁定未使用抑制指令的报告行为、仅选择已忽略暂存文件的情况、格式化器与验证器之间的规则一致性，以及最终格式化后的字节。运行器测试锁定两项工作线程控制，类型检查则确认迁移引发的源码改动没有破坏 TypeScript 程序。
+可执行契约测试要求包、host 和 client 项目产生类型感知诊断，断言 client 专用脚本所用的项目，拒绝未匹配的回退分析，并检验 Stylistic、SonarJS 和 nursery 兼容路径。它们还锁定暂存配置不加载项目的继承行为、未使用抑制指令的报告行为、仅选择已忽略暂存文件的情况、格式化器与验证器之间的规则一致性，以及最终格式化后的字节。运行器测试锁定两项工作线程控制，类型检查则确认迁移引发的源码改动没有破坏 TypeScript 程序。
 
 ## 考虑过的替代方案
 
@@ -42,4 +42,4 @@ CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行
 
 类型感知诊断现在来自通过 `oxlint-tsgolint` 捆绑的 TypeScript Go 分析器，因此即使 `tsc` 接受同一程序，边界场景下的类型推断也可能与 typescript-eslint 不同。lint 与类型检查仍是两项相互独立的必要证据。
 
-JavaScript 插件兼容 API 和暂存文件格式化器是需要维护的额外边界。每次提交在 Oxlint 之前需要启动一次不加载项目的 ESLint，根目录开发依赖图仍保留 ESLint 和 TypeScript 解析器。全仓库验证、类型感知分析、缓存政策、工作线程控制和内联指令仍由 Oxlint 负责。
+JavaScript 插件兼容 API、暂存配置和暂存文件格式化器是需要维护的额外边界。每次提交把类型感知诊断留给公共 lint 和 CI，在 Oxlint 之前启动一次不加载项目的 ESLint，并避免依赖生成的声明。根目录开发依赖图仍保留 ESLint 和 TypeScript 解析器。全仓库验证、类型感知分析、缓存政策、工作线程控制和内联指令仍由 Oxlint 负责。
diff --git a/.oxlintrc.staged.json b/.oxlintrc.staged.json
new file mode 100644
index 0000000000..db79a933fa
--- /dev/null
+++ b/.oxlintrc.staged.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "extends": ["./.oxlintrc.json"],
+  "options": {
+    "typeAware": false
+  }
+}
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 8ca8d518e3..676c78bb90 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: 172d3bd3298f286e621da5fde0ec1620c10583ac
-development.zh.md: c9c594836319816fdcb5cf9d5ceada74e17ef97b
+development.md: a9edd80abfbd53c9fc0495b4b495fa495207ca95
+development.zh.md: 405942c26ef3600209bc14a300c94a98d4f2b9f3
diff --git a/docs/development.md b/docs/development.md
index 172d3bd329..a9edd80abf 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -75,7 +75,7 @@ Both tsdown passes use the same complete workspace match. They neither scan buil
 
 TypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.
 
-Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while scheduler-only `*:contracts-ready` scripts run only after an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.
+Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.
 
 Business services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.
 
@@ -102,7 +102,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 lefthook is configured in `lefthook.yml` as a fast local checkpoint:
 
-- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
+- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
 - `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.
 
 The vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.
diff --git a/docs/development.zh.md b/docs/development.zh.md
index c9c5948363..405942c26e 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -75,7 +75,7 @@ pnpm run build:web
 
 TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
 
-静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而仅供调度器使用的 `*:contracts-ready` 脚本只会在显式依赖 TypeRT 契约 pass 或完整构建后运行。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
+静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
 
 业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
 
@@ -102,7 +102,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
-- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
+- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
 - `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
diff --git a/lefthook.yml b/lefthook.yml
index fda1df0b95..c2249adbde 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -15,7 +15,7 @@ pre-commit:
       glob: '*.{ts,tsx,mts,cts,mjs}'
       exclude:
         - 'vendor/*/src/**'
-      run: node_modules/.bin/tsx scripts/run-oxlint.ts --fix --no-error-on-unmatched-pattern {staged_files}
+      run: node_modules/.bin/tsx scripts/run-oxlint.ts --config .oxlintrc.staged.json --fix --no-error-on-unmatched-pattern {staged_files}
       stage_fixed: true
 
     # Regenerate rather than reject: a dependency edit that forgot the notices
diff --git a/package.json b/package.json
index 9ba13ce689..5884d8058a 100644
--- a/package.json
+++ b/package.json
@@ -47,7 +47,6 @@
     "check:ci": "tsx scripts/run-gates.ts ci-primary",
     "check:ci:linux-primary": "tsx scripts/run-gates.ts ci-linux-primary",
     "check:ci:static": "tsx scripts/run-gates.ts ci-static",
-    "check:ci:lint": "tsx scripts/run-gates.ts ci-lint",
     "check:ci:lint:contracts-ready": "tsx scripts/run-gates.ts ci-lint-contracts-ready",
     "check:ci:coverage": "tsx scripts/run-gates.ts ci-coverage",
     "check:ci:snapshot": "tsx scripts/run-gates.ts ci-snapshot",
diff --git a/scripts/oxlint-contract.spec.ts b/scripts/oxlint-contract.spec.ts
index 727bc34bff..7592780881 100644
--- a/scripts/oxlint-contract.spec.ts
+++ b/scripts/oxlint-contract.spec.ts
@@ -221,6 +221,39 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
     expect(result.status, normalizedOutput(result)).toBe(0)
   })
 
+  it('keeps staged validation project-free while preserving source rules', async () => {
+    const configPath = join(repositoryRoot, '.oxlintrc.staged.json')
+    const result = parseConfigFileTextToJson(configPath, await readFile(configPath, 'utf8'))
+    if (result.error !== undefined) {
+      throw new Error(flattenDiagnosticMessageText(result.error.messageText, '\n'))
+    }
+    expect(result.config).toMatchObject({
+      extends: ['./.oxlintrc.json'],
+      options: { typeAware: false },
+    })
+
+    const suffix = randomUUID()
+    const path = join(repositoryRoot, 'scripts', `staged-lint-probe-${suffix}.ts`)
+    try {
+      await writeFile(path, 'export const value={answer:1};\n')
+      const lint = runOxlint([
+        '--config',
+        relative(repositoryRoot, configPath),
+        '--format',
+        'unix',
+        relative(repositoryRoot, path),
+      ])
+      const output = normalizedOutput(lint)
+
+      expect(lint.error).toBeUndefined()
+      expect(lint.status, output).toBe(1)
+      expect(output).toContain('@stylistic')
+      expect(output).not.toContain('typescript(')
+    } finally {
+      await rm(path, { force: true })
+    }
+  })
+
   it('applies staged stylistic fixes before Oxlint validation', async () => {
     const suffix = randomUUID()
     const configPath = await writeContractConfig(suffix)
diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts
index e45383b481..c7b8a7d2c9 100644
--- a/scripts/run-gates.spec.ts
+++ b/scripts/run-gates.spec.ts
@@ -59,7 +59,6 @@ describe('gate graph validation', () => {
     'ci-primary',
     'ci-linux-primary',
     'ci-static',
-    'ci-lint',
     'ci-lint-contracts-ready',
     'ci-coverage',
     'ci-snapshot',
@@ -119,25 +118,25 @@ describe('gate graph validation', () => {
 describe('Oxlint gate', () => {
   it('uses the package script when no worker bound is configured', () => {
     const subject = withEnv('DSH_OXLINT_THREADS', undefined, () =>
-      withPnpmEntrypoint(() => gatesForMode('ci-lint')[0]))
+      withPnpmEntrypoint(() => gatesForMode('ci-lint-contracts-ready')[0]))
 
     expect(subject).toMatchObject({
       id: 'lint',
-      displayCommand: 'pnpm run lint',
+      displayCommand: 'pnpm run lint:contracts-ready',
       command: process.execPath,
-      args: ['/private/pnpm.cjs', 'run', 'lint'],
+      args: ['/private/pnpm.cjs', 'run', 'lint:contracts-ready'],
     })
   })
 
   it('surfaces the configured worker bound on the shared package script', () => {
     const subject = withEnv('DSH_OXLINT_THREADS', '4', () =>
-      withPnpmEntrypoint(() => gatesForMode('ci-lint')[0]))
+      withPnpmEntrypoint(() => gatesForMode('ci-lint-contracts-ready')[0]))
 
     expect(subject).toMatchObject({
       id: 'lint',
-      displayCommand: 'DSH_OXLINT_THREADS=4 pnpm run lint',
+      displayCommand: 'DSH_OXLINT_THREADS=4 pnpm run lint:contracts-ready',
       command: process.execPath,
-      args: ['/private/pnpm.cjs', 'run', 'lint'],
+      args: ['/private/pnpm.cjs', 'run', 'lint:contracts-ready'],
     })
   })
 })
@@ -182,15 +181,10 @@ describe('TypeRT contract preparation', () => {
     })
   })
 
-  it('keeps standalone aggregates responsible for preparation', () => {
-    const [lint, preparedLint, docTypecheck] = withEnv('DSH_OXLINT_THREADS', undefined, () => [
-      withPnpmEntrypoint(() => gatesForMode('ci-lint')[0]),
-      withPnpmEntrypoint(() => gatesForMode('ci-lint-contracts-ready')[0]),
-      withPnpmEntrypoint(() => gatesForMode('doc-sync').find(item => item.id === 'doc-typecheck')),
-    ])
+  it('keeps standalone doc sync responsible for preparation', () => {
+    const docTypecheck = withPnpmEntrypoint(() =>
+      gatesForMode('doc-sync').find(item => item.id === 'doc-typecheck'))
 
-    expect(lint?.displayCommand).toBe('pnpm run lint')
-    expect(preparedLint?.displayCommand).toBe('pnpm run lint:contracts-ready')
     expect(docTypecheck?.displayCommand).toBe('pnpm run doc-typecheck')
   })
 })
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index f3ef6850b1..122f487abb 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -16,7 +16,6 @@ export type Mode =
   | 'ci-primary'
   | 'ci-linux-primary'
   | 'ci-static'
-  | 'ci-lint'
   | 'ci-lint-contracts-ready'
   | 'ci-coverage'
   | 'ci-snapshot'
@@ -102,7 +101,6 @@ function parseMode(raw: string | undefined): Mode {
     case 'ci-primary':
     case 'ci-linux-primary':
     case 'ci-static':
-    case 'ci-lint':
     case 'ci-lint-contracts-ready':
     case 'ci-coverage':
     case 'ci-snapshot':
@@ -117,7 +115,7 @@ function parseMode(raw: string | undefined): Mode {
       return raw
     default:
       throw new Error(
-        `run-gates: expected mode ci-primary | ci-linux-primary | ci-static | ci-lint | ci-lint-contracts-ready | ci-coverage | ci-snapshot | ci-artifacts | ci-consumers | ci-windows-blocking | ci-windows-complete | ci-windows-observational | node-compat | check-all | doc-sync, got ${JSON.stringify(raw)}.`,
+        `run-gates: expected mode ci-primary | ci-linux-primary | ci-static | ci-lint-contracts-ready | ci-coverage | ci-snapshot | ci-artifacts | ci-consumers | ci-windows-blocking | ci-windows-complete | ci-windows-observational | node-compat | check-all | doc-sync, got ${JSON.stringify(raw)}.`,
       )
   }
 }
@@ -199,14 +197,9 @@ export function gatesForMode(selected: Mode): Gate[] {
       return [...ciPrimaryGates(), webSnapshotGate(['built-package-invariants'])]
     case 'ci-static':
       return ciStaticGates({ ownsBuild: false })
-    case 'ci-lint':
-      return [
-        lintGate(),
-        pnpmScript('duplication', 'duplication'),
-      ]
     case 'ci-lint-contracts-ready':
       return [
-        lintGate({ contractsReady: true }),
+        lintGate(),
         pnpmScript('duplication', 'duplication'),
       ]
     case 'ci-coverage':
@@ -264,7 +257,7 @@ function ciPrimaryGates(): Gate[] {
     ...ciSharedStaticGates(),
     typertContractsGate(),
     pnpmScript('typecheck', 'typecheck:contracts-ready', { needs: ['typert-contracts'] }),
-    lintGate({ contractsReady: true, needs: ['typert-contracts'] }),
+    lintGate({ needs: ['typert-contracts'] }),
     pnpmScript('duplication', 'duplication'),
     ...coverageGates(),
     ...nodeCompatSmokeGates(),
@@ -464,9 +457,9 @@ function typertContractsGate(): Gate {
   return pnpmScript('typert-contracts', 'build:lib:host', { label: 'TypeRT contracts' })
 }
 
-function lintGate(options: { contractsReady?: boolean; needs?: string[] } = {}): Gate {
+function lintGate(options: { needs?: string[] } = {}): Gate {
   const raw = process.env.DSH_OXLINT_THREADS
-  const script = options.contractsReady === true ? 'lint:contracts-ready' : 'lint'
+  const script = 'lint:contracts-ready'
   return pnpmScript('lint', script, {
     ...raw === undefined || raw === ''
       ? {}
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 43611a4cd5..c7b38e2557 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while scheduler-only `*:contracts-ready` scripts run only after an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with Oxlint and applies its native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而仅供调度器使用的 `*:contracts-ready` 脚本只会在显式依赖 TypeRT 契约 pass 或完整构建后运行。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用 Oxlint 验证暂存文件并应用其原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",

From bdd2f49df780e056bc2897669e86f5f8dc37ae8c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:05:50 +0800
Subject: [PATCH 224/516] fix(cli): address dsh run review feedback

---
 .../architecture/2026-08-05-profile-plugin-bundles.i18n.yaml  | 4 ++--
 .../architecture/2026-08-05-profile-plugin-bundles.md         | 2 ++
 .../architecture/2026-08-05-profile-plugin-bundles.zh.md      | 2 ++
 .../feature/2026-08-08-dsh-run-headless-command.i18n.yaml     | 4 ++--
 .../feature/2026-08-08-dsh-run-headless-command.md            | 2 ++
 .../feature/2026-08-08-dsh-run-headless-command.zh.md         | 2 ++
 apps/cli/src/args.ts                                          | 4 ++--
 7 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index 7fa37eeb8e..3e1d038514 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.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 .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
-2026-08-05-profile-plugin-bundles.md: b5bf5411d22ab99b598f667886b3c29ba8ee7b06
-2026-08-05-profile-plugin-bundles.zh.md: ae790028b5768c05c57acd27d7f68bdc4d612c11
+2026-08-05-profile-plugin-bundles.md: 8613e600ad633818abb4319e614230340c3b3876
+2026-08-05-profile-plugin-bundles.zh.md: 03a771364c4f3262801f28e68b96ec5de633e5ec
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
index b5bf5411d2..8613e600ad 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
@@ -14,6 +14,8 @@ Everything becomes a **profile**: a directory `$DSH_HOME/profiles/<name>` with a
 
 The shipped compositions became bundles: `@deepseek-ai/dsh-base` (the former base rows as one insert), `@deepseek-ai/dsh-web-app` (the former web overlay plus a runtime glue plugin that owns what used to be launcher code — frontend-dist resolution, the web-surface prompt section, bash runtime variables, the URL line), and `@deepseek-ai/dsh-headless` (a one-shot runner plugin over base + web-app). `dsh web` stays as an alias for `--profile web` carrying the Web flag family; `dsh run [--profile <name>] "task"` owns one-shot execution and defaults to the headless profile, while generic `dsh --profile <name>` boots without a task; `dsh --config` is removed (its uses migrate to `--patch`). `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` after `add`/`remove` (a bundle-less package warns and stays a plain dependency).
 
+The [`dsh run` command decision](../feature/2026-08-08-dsh-run-headless-command.md) owns the one-shot grammar; this note owns the profile composition it selects.
+
 Resolution is two-anchored by construction: `dsh.profile.bundles` names resolve from the dsh installation first, then the profile directory — so in-box bundles always come from the same installation as the running `dsh` and pnpm never manages them — while bare plugin names in patch rows resolve through the profile directory's Node parent-walk into the maintained flat fallback `$DSH_HOME/profiles/node_modules` (one symlink per package the installation's app and bundles depend on, healed on every launch).
 
 Two supporting refactors: the webserver's built-in static dist serving became the single-owner **fallback seat** (`registerFallback`/`applyIndexTaps`), with the SPA server extracted to `@deepseek-ai/dsh-frontend-static` so the web bundle owns its dist as composition, not launcher code; and the personal-overlay machinery of the [dsh CLI personal-config decision](../feature/2026-07-20-dsh-cli-personal-config.md) (`loadPersonalPatches`, `$DSH_HOME/config.yaml`) was retargeted to the per-profile and home-level `cordis.patch.yml` layers (`loadOptionalPatches`, `watchUserPatches` taking a filename), superseding that note's entry modes and file location while keeping its Harness-home root, patch semantics, and fail-loud parsing.
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index ae790028b5..03a771364c 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -14,6 +14,8 @@ Status: implemented
 
 已交付的组合改造成了组合包：`@deepseek-ai/dsh-base`（原有基础行合并为一次插入）、`@deepseek-ai/dsh-web-app`（原 web overlay，外加一个接管原启动器代码的运行时粘合插件——前端 dist 解析、web 表层提示词段落、bash 运行时变量、URL 行）、`@deepseek-ai/dsh-headless`（叠加在 base + web-app 之上的一次性 runner 插件）。`dsh web` 保留为携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile，而通用的 `dsh --profile <name>` 只启动 profile，不携带任务；`dsh --config` 被移除（其用途迁移到 `--patch`）。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并在 `add`／`remove` 后调和 `dsh.profile.bundles`（没有组合包声明的包会给出警告，保持为普通依赖）。
 
+[`dsh run` 命令决策](../feature/2026-08-08-dsh-run-headless-command.md)负责一次性语法；本 Agent Note 负责该语法所选择的 profile 组合。
+
 解析在构造上就是双锚点的：`dsh.profile.bundles` 中的名称先从 dsh 安装目录解析，再从 profile 目录解析——因此内置组合包始终来自与运行中 `dsh` 相同的安装，pnpm 从不管理它们——而 patch 行中的裸插件名称经 profile 目录的 Node 父目录逐级查找，落到受维护的扁平回退目录 `$DSH_HOME/profiles/node_modules`（安装目录的应用与各组合包所依赖的每个包各一个符号链接，每次启动时修复）。
 
 两项配套重构：webserver 内置的静态 dist 服务改为单一所有者的**回退席位**（`registerFallback`／`applyIndexTaps`），SPA 服务器提取到 `@deepseek-ai/dsh-frontend-static`，使 web 组合包以组合的方式持有自己的 dist，而不是靠启动器代码；[dsh CLI 个人配置决策](../feature/2026-07-20-dsh-cli-personal-config.md)的个人 overlay 机制（`loadPersonalPatches`、`$DSH_HOME/config.yaml`）改为面向逐 profile 与 home 级的 `cordis.patch.yml` 层（`loadOptionalPatches`、接受文件名的 `watchUserPatches`），取代该笔记的各入口模式与文件位置，同时保留其 Harness home 根目录、patch 语义与大声失败的解析。
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
index 8d5ec1c9f6..bc2d1575ee 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-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 .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
-2026-08-08-dsh-run-headless-command.md: aac2a473760509626d315df8d57eb405eb547abf
-2026-08-08-dsh-run-headless-command.zh.md: d71d2a34addf1c64b8cb37c54117be5b9c643370
+2026-08-08-dsh-run-headless-command.md: d1cc0573d1d94bb7b30e98aa685d2b7d89878a99
+2026-08-08-dsh-run-headless-command.zh.md: 7b48dfd708efb197babcfcbeaf4f8a4ca76cde3f
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
index aac2a47376..d1cc0573d1 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
@@ -20,6 +20,8 @@ dsh run [--profile <name>] [--patch <path>...] <task...>
 
 `--profile` defaults to `headless` and remains available for custom one-shot compositions. `--patch` is repeatable and occupies the existing overlay layer. Commander joins the variadic task arguments with spaces and rejects a missing or blank task before boot.
 
+The [profile plugin bundle decision](../architecture/2026-08-05-profile-plugin-bundles.md) owns the composition selected by this grammar.
+
 `RunInvocation` is a separate `DshInvocation` member. The generic profile invocation no longer carries task text, and its root command accepts no positional arguments. Both dispatch paths call the existing deep `runProfile` module: `profile` omits `task`, while `run` supplies it. There is no shallow `run.ts` forwarding module and no alias, warning, or custom detector for former spellings; they fail through the ordinary Commander grammar. A one-shot profile without `headless-runner` still fails through the existing composed-row check, while booting a profile that contains that row without a task points to `dsh run --profile <name> "<task>"`.
 
 The `run` verb belongs to one-shot task execution. Launching an application file must choose another command name; two top-level meanings selected by positional shape would recreate the ambiguity this command removes.
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
index d71d2a34ad..7b48dfd708 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
@@ -20,6 +20,8 @@ dsh run [--profile <name>] [--patch <path>...] <task...>
 
 `--profile` 默认为 `headless`，同时保留对自定义一次性组合的支持。`--patch` 可重复使用，并沿用既有 overlay 层的位置。Commander 用空格拼接可变数量的任务参数，并在启动前拒绝缺失或空白任务。
 
+[profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)负责该语法所选择的组合。
+
 `RunInvocation` 是单独的 `DshInvocation` 成员。通用 profile 调用不再携带任务文本，其根命令也不接受位置参数。两条分派路径都调用已有的深层 `runProfile` 模块：`profile` 省略 `task`，`run` 则提供该字段。实现中没有只负责转发的浅层 `run.ts` 模块，也没有面向旧写法的别名、警告或自定义检测器；旧写法会按普通 Commander 语法失败。缺少 `headless-runner` 的一次性 profile 仍会触发既有的组合行检查；如果启动的 profile 包含该行却未提供任务，错误会指向 `dsh run --profile <name> "<task>"`。
 
 `run` 动词只负责一次性任务执行。应用文件启动必须选择其他命令名；如果让两个顶层含义由位置参数形态决定，就会重新引入本命令消除的歧义。
diff --git a/apps/cli/src/args.ts b/apps/cli/src/args.ts
index 0b72f76c6a..d96b7a503f 100644
--- a/apps/cli/src/args.ts
+++ b/apps/cli/src/args.ts
@@ -78,7 +78,7 @@ interface WebOptions {
 
 /** Raw run-subcommand options straight from Commander. */
 interface RunOptions {
-  profile?: string
+  profile: string
   patch?: string[]
 }
 
@@ -161,7 +161,7 @@ Examples:
     .argument('<task...>', 'task text')
     .action((task: string[], options: RunOptions) => {
       rejectParentOptions('run')
-      const profile = options.profile ?? 'headless'
+      const profile = options.profile
       if (profile === '') program.error('error: --profile needs a name')
       const patches = options.patch ?? []
       if (patches.includes('')) program.error('error: --patch needs a path')

From dc57f7d854bc390dfc82261c5c05cedeef292474 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 03:08:37 +0800
Subject: [PATCH 225/516] cleanup(cli): remove dsh-cli-demo

---
 ...-07-29-dsh-source-launch-tsx-esm.i18n.yaml |   4 +-
 .../2026-07-29-dsh-source-launch-tsx-esm.md   |   2 +-
 ...2026-07-29-dsh-source-launch-tsx-esm.zh.md |   2 +-
 ...20-error-cause-chain-diagnostics.i18n.yaml |   4 +-
 ...026-07-20-error-cause-chain-diagnostics.md |   2 +-
 ...-07-20-error-cause-chain-diagnostics.zh.md |   2 +-
 .../2026-07-06-node-engine-floor.i18n.yaml    |   4 +-
 .../process/2026-07-06-node-engine-floor.md   |   4 +-
 .../2026-07-06-node-engine-floor.zh.md        |   4 +-
 ...-20-remove-stdio-and-echo-agents.i18n.yaml |   4 +-
 ...2026-07-20-remove-stdio-and-echo-agents.md |   6 +-
 ...6-07-20-remove-stdio-and-echo-agents.zh.md |   6 +-
 .../2026-08-08-remove-cli-demo.i18n.yaml      |   6 +
 .../2026-08-08-remove-cli-demo.md             |  34 +
 .../2026-08-08-remove-cli-demo.zh.md          |  34 +
 docs/capability-seams.md                      |   7 +-
 docs/config-catalog.md                        |  40 --
 docs/cookbook/extension-cookbook.i18n.yaml    |   4 +-
 docs/cookbook/extension-cookbook.md           |   2 +-
 docs/cookbook/extension-cookbook.zh.md        |   4 +-
 docs/event-producer-consumer.md               |   2 +-
 docs/module-graph.md                          |  12 -
 docs/testing.i18n.yaml                        |   4 +-
 docs/testing.md                               |   4 +-
 docs/testing.zh.md                            |   4 +-
 docs/user/guide/index.i18n.yaml               |   4 +-
 docs/user/guide/index.md                      |  12 +-
 docs/user/guide/index.zh.md                   |  12 +-
 docs/user/guide/quickstart.i18n.yaml          |   4 +-
 docs/user/guide/quickstart.md                 |   6 +-
 docs/user/guide/quickstart.zh.md              |   6 +-
 .../fixtures/subagent/subagent-acp/cordis.yml |  22 +-
 .../fixtures/subagent/subagent-acp/driver.ts  |   4 +-
 .../subagent/subagent-claude-code/cordis.yml  |  19 +-
 .../subagent/subagent-codex/cordis.yml        |  19 +-
 examples/headless-agent/README.i18n.yaml      |   4 +-
 examples/headless-agent/README.md             |  14 +-
 examples/headless-agent/README.zh.md          |  14 +-
 .../advanced.cordis.snapshot.yml              |  24 +-
 examples/headless-agent/advanced.cordis.yml   |  18 +-
 examples/headless-agent/composition.md        |  23 +-
 examples/headless-agent/cordis.yml            |  30 +-
 .../tests/fixtures/cli.cordis.yml             |  16 +-
 .../fixtures/deepseek-defaults.cordis.yml     |  13 +-
 .../tests/fixtures/goal-domain/cordis.yml     |  22 +-
 .../tests/fixtures/headless-driver.ts         |  33 +
 .../headless-agent/tests/fixtures/one-shot.ts |  97 +++
 .../tests/fixtures/telemetry-otel-driver.ts   |   6 +-
 .../tests/fixtures/telemetry-otel.cordis.yml  |  22 +-
 .../tests/fixtures/time-context-driver.ts     |   6 +-
 .../tests/fixtures/time-context.cordis.yml    |  22 +-
 .../headless-agent/tests/headless.snapshot.ts |  36 +-
 .../headless-agent/tests/keyless-smoke.e2e.ts |   5 +-
 .../headless-agent/tests/real-model.e2e.ts    |   4 +-
 .../tests/semantic-checkpoint.snapshot.ts     |   5 +-
 .../stderr.expected.txt                       |   2 +-
 .../tests/subagent-diagnostic.snapshot.ts     |   5 +-
 .../tests/subagent-inheritance.snapshot.ts    |   5 +-
 .../workspace-context-resume.snapshot.ts      |   8 +-
 .../subagent/subagent-dsh-sdk/cordis.yml      |  22 +-
 .../subagent/subagent-dsh-sdk/driver.ts       |   4 +-
 examples/package.json                         |   1 -
 knip.json                                     |  10 -
 package.json                                  |   2 +-
 packages/examples/README.i18n.yaml            |   4 +-
 packages/examples/README.md                   |   3 +-
 packages/examples/README.zh.md                |   3 +-
 packages/examples/cli-demo/README.i18n.yaml   |   6 -
 packages/examples/cli-demo/README.md          |  78 ---
 packages/examples/cli-demo/README.zh.md       |  78 ---
 packages/examples/cli-demo/package.json       |  68 --
 packages/examples/cli-demo/src/bin.ts         |  34 -
 packages/examples/cli-demo/src/cli.ts         | 406 ------------
 packages/examples/cli-demo/src/index.ts       |  96 ---
 packages/examples/cli-demo/src/invariant.ts   |  30 -
 .../examples/cli-demo/tests/built-bin.e2e.ts  | 223 -------
 .../examples/cli-demo/tests/cli-demo.spec.ts  | 202 ------
 packages/examples/cli-demo/tests/cli.spec.ts  | 614 ------------------
 packages/examples/cli-demo/tsconfig.json      |  47 --
 packages/examples/cli-demo/tsdown.config.ts   |  13 -
 packages/goal/goal/tests/goal.e2e.ts          |   7 +-
 .../loader-smoke/tests/example-launch.spec.ts |   6 +-
 packages/ui/app-boot/README.i18n.yaml         |   4 +-
 packages/ui/app-boot/README.md                |   2 +-
 packages/ui/app-boot/README.zh.md             |   2 +-
 packages/ui/app-boot/src/index.ts             |   2 +-
 pnpm-lock.yaml                                |  51 --
 scripts/gen-doc-graphs.ts                     |  14 +-
 scripts/run-gates.ts                          |   1 -
 tsconfig.host.json                            |   1 -
 90 files changed, 539 insertions(+), 2238 deletions(-)
 create mode 100644 .agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
 create mode 100644 .agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
 create mode 100644 .agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
 create mode 100644 examples/headless-agent/tests/fixtures/headless-driver.ts
 create mode 100644 examples/headless-agent/tests/fixtures/one-shot.ts
 delete mode 100644 packages/examples/cli-demo/README.i18n.yaml
 delete mode 100644 packages/examples/cli-demo/README.md
 delete mode 100644 packages/examples/cli-demo/README.zh.md
 delete mode 100644 packages/examples/cli-demo/package.json
 delete mode 100644 packages/examples/cli-demo/src/bin.ts
 delete mode 100644 packages/examples/cli-demo/src/cli.ts
 delete mode 100644 packages/examples/cli-demo/src/index.ts
 delete mode 100644 packages/examples/cli-demo/src/invariant.ts
 delete mode 100644 packages/examples/cli-demo/tests/built-bin.e2e.ts
 delete mode 100644 packages/examples/cli-demo/tests/cli-demo.spec.ts
 delete mode 100644 packages/examples/cli-demo/tests/cli.spec.ts
 delete mode 100644 packages/examples/cli-demo/tsconfig.json
 delete mode 100644 packages/examples/cli-demo/tsdown.config.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
index 5a884924f9..92a30e931c 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.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 .agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
-2026-07-29-dsh-source-launch-tsx-esm.md: 21e912c7c7bbdd70142c202105d9a3035442884a
-2026-07-29-dsh-source-launch-tsx-esm.zh.md: dc6150b7017777eea99778cc9813e17402354462
+2026-07-29-dsh-source-launch-tsx-esm.md: aabe6c2d6a92b5cc6568eee1d42df3a6998cf0ca
+2026-07-29-dsh-source-launch-tsx-esm.zh.md: fdeb8a976e02bb9311a6ec9d097d09151a998a04
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
index 21e912c7c7..aabe6c2d6a 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
@@ -35,4 +35,4 @@ The node-compat CI matrix (Node 22.19 and 26) gains `dsh-source-launch-smoke` (`
 - One launch vector across the whole engines range, including future Node lines that change native TypeScript support; the smoke gate enforces it per matrix line.
 - TypeScript transformation is delegated to tsx/esbuild again, reversing the prior note's goal of proving Node-native transformation; that goal is unreachable while vendored sources use non-erasable syntax and Node ships no transform mode.
 - The runtime declared-dependency enforcement in source launches is gone; undeclared workspace imports now surface only through static gates or built-mode resolution failures.
-- Startup improves ~0.4s over the full tsx default (`demo:headless` and ACP keep `--import tsx`; their graphs were not audited for CJS-hook dependence and their launch latency is not on the interactive path).
+- Startup improves ~0.4s over the full tsx default (`demo:headless` now aliases the same `dsh run` source launch; ACP keeps `--import tsx` because its graph was not audited for CJS-hook dependence and its launch latency is not on the interactive path).
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
index dc6150b701..fdeb8a976e 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
@@ -35,4 +35,4 @@ node-compat CI 矩阵（Node 22.19 与 26）新增 `dsh-source-launch-smoke`（`
 - 整个 engines 范围（包括未来改变原生 TypeScript 支持的 Node 版本线）只有一个启动向量；冒烟门禁按矩阵行强制执行。
 - TypeScript 转换重新委托给 tsx/esbuild，逆转了前一篇 Agent Note「证明 Node 原生转换可用」的目标；在 vendor 源码使用不可擦除语法且 Node 不再提供 transform 模式的情况下，该目标不可达。
 - 源码启动中的运行时依赖声明强制不复存在；未声明的 workspace import 现在只能通过静态门禁或构建模式的解析失败暴露。
-- 启动相比完整 tsx 默认形态快约 0.4s（`demo:headless` 与 ACP 保持 `--import tsx`：其依赖图未就 CJS 钩子依赖性做审计，且其启动延迟不在交互路径上）。
+- 启动相比完整 tsx 默认形态快约 0.4s（`demo:headless` 现为同一条 `dsh run` 源码启动命令的别名；ACP 保留 `--import tsx`，因为它的依赖图尚未就 CJS 钩子依赖性做审计，且其启动延迟不在交互路径上）。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
index bdb4632744..eda7b29acf 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.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 .agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
-2026-07-20-error-cause-chain-diagnostics.md: 7de1f4f631cec90048ccc8eab7a6654560d84846
-2026-07-20-error-cause-chain-diagnostics.zh.md: 6ce642eb4a18a1a412fb63c3bb00042a921f4da3
+2026-07-20-error-cause-chain-diagnostics.md: 89edd4529cc16617fdca736dbbea4b170400d6bd
+2026-07-20-error-cause-chain-diagnostics.zh.md: 673921c913a9f1fefe6f85303cf5952f8edbcc1d
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
index 7de1f4f631..89edd4529c 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
@@ -34,4 +34,4 @@ A TUI run against an unreachable DeepSeek endpoint failed with the single notice
 - Durable `turn/end` error messages include cause detail. Existing snapshot fixtures replay byte-identically because their scripted errors carry no `cause` (for such errors `errorChain(err)` equals `err.message`); only unit-test expectation strings changed. A fixture recorded from a real transport failure would carry the chain.
 - `errorChain` renders `message` without the class name (`String(error)` rendered `Error: <message>`), so a bare `TypeError` in a log line loses its type label unless its message is empty (then the name is the fallback). The chain detail was judged worth more than the class name at these seams.
 - `dsh-stdio` output for failed turns is no longer silent; piped consumers that parsed the transcript see new `[turn …]` lines.
-- Remaining `renderThrown` copies in `dsh-subagent`, `dsh-workflow`, `dsh-skill`, `dsh-workflow-workerthread`, and `cli-demo` still render without the chain; they wrap package-local errors that carry their own messages, and can adopt `errorChain` when their diagnostics prove insufficient.
+- Remaining `renderThrown` copies in `dsh-subagent`, `dsh-workflow`, `dsh-skill`, and `dsh-workflow-workerthread` still render without the chain; they wrap package-local errors that carry their own messages, and can adopt `errorChain` when their diagnostics prove insufficient.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
index 6ce642eb4a..673921c913 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
@@ -34,4 +34,4 @@ TUI 连接不可达的 DeepSeek 端点时，失败只显示一条 `fetch failed`
 - 持久化的 `turn/end` 错误消息包含 cause 细节。现有快照 fixture（测试前置数据）字节级一致地回放，因为其脚本化错误不带 `cause`（对这类错误 `errorChain(err)` 等于 `err.message`）；只有单元测试的期望字符串有变化。从真实传输失败录制的 fixture 会携带完整链。
 - `errorChain` 渲染 `message` 而不带类名（`String(error)` 会渲染 `Error: <message>`），因此日志行里的裸 `TypeError` 会丢失类型标签，除非消息为空（此时回退到类名）。在这些诊断界面上，链细节被判断为比类名更有价值。
 - `dsh-stdio` 对失败轮次的输出不再沉默；解析 transcript 的管道消费方会看到新的 `[turn …]` 行。
-- `dsh-subagent`、`dsh-workflow`、`dsh-skill`、`dsh-workflow-workerthread`、`cli-demo` 里剩余的 `renderThrown` 副本仍不渲染链；它们包装的是自带消息的包内错误，等诊断信息证明不足时再采用 `errorChain`。
+- `dsh-subagent`、`dsh-workflow`、`dsh-skill`、`dsh-workflow-workerthread` 里剩余的 `renderThrown` 副本仍不渲染链；它们包装的是自带消息的包内错误，等诊断信息证明不足时再采用 `errorChain`。
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
index aa4c089a00..d96a3b4d6c 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.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 .agents/notes/implemented/process/2026-07-06-node-engine-floor.md
-2026-07-06-node-engine-floor.md: ef047d885a442106a35922f4716d2996d8a98ca7
-2026-07-06-node-engine-floor.zh.md: c409b006baa3451eb5fc5260be4e14ffe88776c8
+2026-07-06-node-engine-floor.md: e42b809f83fe388526ecbd74192989e0bcdbba67
+2026-07-06-node-engine-floor.zh.md: 92fa00f7a270f4506cba6c899e9edf6a2fdd3209
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md
index ef047d885a..e42b809f83 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md
@@ -15,7 +15,7 @@ Set `engines.node` to `^22.19.0 || >=24.0.0` and test keyless CI on `['22.19', 2
 Two Node features gate the source runtime:
 
 - **`node:sqlite`** — `packages/session-persistence/session-persistence-sqlite` does a top-level `import { DatabaseSync } from 'node:sqlite'`. The module dropped its `--experimental-sqlite` flag requirement at **22.13** (LTS) and **23.4** (Current); before those, importing it throws at load.
-- **Native TypeScript type-stripping** — the built-mode `examples/headless-agent/tests/keyless-smoke.e2e.ts` smoke boots `dsh-cli-demo`'s published `lib/bin.js` under plain `node` (no tsx) and loads the example's `.ts` test adapter (`cli-mock-llm.ts`). Type-stripping is the default from **22.18** (LTS) and **23.6** (Current); before those it needs `--experimental-strip-types`.
+- **Native TypeScript type-stripping** — the built-mode `examples/headless-agent/tests/keyless-smoke.e2e.ts` smoke boots its unexported `.ts` driver under plain `node` (no tsx) and loads the example's `.ts` test adapter (`cli-mock-llm.ts`). Type-stripping is the default from **22.18** (LTS) and **23.6** (Current); before those it needs `--experimental-strip-types`.
 
 Those source features clear on the 22.x line at **22.18**, but the installed Pi adapter dependency raises the advertised LTS floor. `@deepseek-ai/dsh-llm-pi-ai` depends on `@earendil-works/pi-ai@0.79.3`, whose package declares `engines.node >=22.19.0`, so the LTS floor is **22.19**. The 24.x branch remains `>=24.0.0`. The disjoint range excludes Node 23 entirely: Node 23.0–23.5 still has at least one flagged source feature, and the 23 line is non-LTS/EOL, so advertising `>=23.6` would add a dead release line and a CI leg no deployment should use.
 
@@ -25,7 +25,7 @@ Those source features clear on the 22.x line at **22.18**, but the installed Pi
 
 - The advertised LTS branch no longer undercuts the Pi adapter dependency floor.
 - CI proves the Node 22 LTS floor directly with Node 22.19, keeps primary coverage on `node: 24`, and exercises Node 26 as the next even line; focused compatibility smokes run on all three versions.
-- The built-bin smoke needs no version-conditional flag: at 22.19 type-stripping is already the default, so the test stays the plain `node lib/bin.js` path it documents.
+- The built-mode smoke needs no version-conditional flag: at 22.19 type-stripping is already the default, so the example-owned TypeScript driver stays a plain `node fixture.ts` path.
 - A future dependency or source API that raises the runtime floor must move `engines.node`, the compatibility matrix, and this Agent Note in the same change.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
index c409b006ba..92fa00f7a2 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
@@ -15,7 +15,7 @@ Status: implemented
 两个 Node 特性决定了源码运行时的门槛：
 
 - **`node:sqlite`**：`packages/session-persistence/session-persistence-sqlite` 在顶层执行 `import { DatabaseSync } from 'node:sqlite'`。该模块在 **22.13**（LTS）和 **23.4**（Current）取消了 `--experimental-sqlite` 标志要求；在此之前，导入它会在加载时抛出异常。
-- **原生 TypeScript 类型剥离**——构建模式的 `examples/headless-agent/tests/keyless-smoke.e2e.ts` 冒烟测试使用纯 `node`（无 tsx）启动 `dsh-cli-demo` 已发布的 `lib/bin.js`，并加载示例的 `.ts` 测试适配器（`cli-mock-llm.ts`）。类型剥离从 **22.18**（LTS）和 **23.6**（Current）起成为默认行为；更早版本需要 `--experimental-strip-types`。
+- **原生 TypeScript 类型剥离**——构建模式的 `examples/headless-agent/tests/keyless-smoke.e2e.ts` 冒烟测试使用纯 `node`（无 tsx）启动该示例未导出的 `.ts` driver，并加载示例的 `.ts` 测试适配器（`cli-mock-llm.ts`）。类型剥离从 **22.18**（LTS）和 **23.6**（Current）起成为默认行为；更早版本需要 `--experimental-strip-types`。
 
 这些源码特性在 22.x 线上于 **22.18** 全部就绪，但已安装的 Pi 适配器依赖将宣传的 LTS 下限进一步提高。`@deepseek-ai/dsh-llm-pi-ai` 依赖 `@earendil-works/pi-ai@0.79.3`，后者的包声明 `engines.node >=22.19.0`，因此 LTS 下限为 **22.19**。24.x 分支保持 `>=24.0.0`。该不相交范围完全排除了 Node 23：Node 23.0–23.5 至少还有一个源码特性需要标志，而 23 线是非 LTS/已 EOL 的，宣传 `>=23.6` 会增加一条已终止的发布线和一条 CI 分支，而没有任何部署应当使用它。
 
@@ -25,7 +25,7 @@ Status: implemented
 
 - 宣传的 LTS 分支不再低于 Pi 适配器依赖的下限。
 - CI 通过 Node 22.19 直接验证 Node 22 LTS 下限，将主要覆盖率任务保留在 `node: 24`，并用 Node 26 验证下一个偶数线；三个版本均运行聚焦的兼容性冒烟测试。
-- built-bin 冒烟测试无需版本条件标志：在 22.19 上类型剥离已是默认行为，因此测试保持其文档所述的纯 `node lib/bin.js` 路径。
+- 构建模式冒烟测试无需版本条件标志：在 22.19 上类型剥离已是默认行为，因此示例自有的 TypeScript driver 保持使用纯 `node fixture.ts` 路径。
 - 未来若依赖或源码 API 提高运行时下限，必须在同一变更中同步调整 `engines.node`、兼容性矩阵和本 Agent Note。
 
 ## 曾考虑的替代方案
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
index 463285cfb1..51e416d9f8 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.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 .agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
-2026-07-20-remove-stdio-and-echo-agents.md: 1c7ff4b5337341ea7678c1455dd7bbd3365df6ba
-2026-07-20-remove-stdio-and-echo-agents.zh.md: 67445d25f6a0534c92c50568da898a5bffc73a52
+2026-07-20-remove-stdio-and-echo-agents.md: 4ffeacae4afc212b0d7b739def2c0e96780d5e54
+2026-07-20-remove-stdio-and-echo-agents.zh.md: 462dc275f151dbeb41bf431fc2ee583e74f22a6b
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
index 1c7ff4b533..4ffeacae4a 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
@@ -19,18 +19,18 @@ The stdio and Echo agents are removed without compatibility packages, modes, com
 The remaining application roles are explicit:
 
 - `@deepseek-ai/dsh-tui` owns terminal-interactive execution. It rejects non-TTY streams before Loader boot; `apps/cli/config/base.cordis.yml` plus the `tui.cordis.yml` overlay own the complete coding composition, with PTY plus terminal-snapshot coverage in `apps/cli/tests/`.
-- [`@deepseek-ai/dsh-cli-demo`](../../../../packages/examples/cli-demo/README.md) owns non-interactive execution, including pipes. `examples/headless-agent` owns the real-model one-shot composition, replay snapshots, generic real-agent suites, and test-only keyless Loader fixtures.
+- [`dsh run`](../../../../apps/cli/README.md) owns non-interactive execution. Its `headless` profile is the product composition; `examples/headless-agent` owns replay snapshots, generic real-agent suites, and an unexported keyless Loader driver.
 - [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) and `@deepseek-ai/dsh-jsonrpc` own their framed protocol integrations.
 
 The SDK project model and create/config workflows replace the `stdio` run-interface option with `tui`; generated TUI projects compose `@deepseek-ai/dsh-tui` and create or resume one exact session. Repository-facing demo documentation requires a DeepSeek API key and leads with the real Headless or TUI agents.
 
-Keyless validation is test-owned. The Headless Loader smoke uses a fixture adapter to exercise a real tool round trip, the CLI built-bin suite pins output, persistence, failure, and signal semantics, and package-specific Loader tests keep deterministic adapters beside their scenarios. None is exposed as a runnable mock agent.
+Keyless validation is test-owned. The Headless Loader smoke uses a fixture adapter to exercise a real tool round trip, the `dsh` built-bin suite pins one-shot output, persistence, failure, and signal semantics, and package-specific Loader tests keep deterministic adapters beside their scenarios. None is exposed as a runnable mock agent.
 
 ## Verification
 
 TUI and Headless Loader coverage run the real app packages in source and built modes. PTY-driven subprocess coverage is reserved for the TUI lifecycle; other entry-point smokes use the one-shot pipe protocol. Headless proves its task/result and tool-call contracts. Generated graphs and repository searches reject stale package, command, leaf, SDK-interface, `createStdioChat`, and `StdioRuntime` references.
 
-The built `dsh` bin rejects a piped TUI launch before Loader boot and points at its one-shot `-p` mode; `apps/cli/tests/built-bin.e2e.ts` pins that path, while `cli-demo`'s built-bin suite runs text, JSON, and structurally parsed `stream-json` output under plain Node, persists fresh sessions, and rejects invalid arguments and missing config without contaminating stdout. Code Mode has programmatic TUI snapshots and an ACP overlay demo. Time-context integration uses the real Headless composition for two ordered turns, while its package tests own finer elapsed-time behavior.
+The built `dsh` bin rejects a piped TUI launch before Loader boot and points at `dsh run`; `apps/cli/tests/built-bin.e2e.ts` pins the product one-shot path under plain Node, including output, persistence, invalid arguments, missing configuration, and signals. The headless example's test-only JSONL driver preserves assembled canonical-event snapshots without creating a second CLI contract. Code Mode has programmatic TUI snapshots and an ACP overlay demo. Time-context integration uses the explicit Headless test composition for two ordered turns, while its package tests own finer elapsed-time behavior.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
index 67445d25f6..462dc275f1 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
@@ -19,18 +19,18 @@ DeepSeek Harness 在 TUI 和 Headless coding agent 之外，还提供了两个
 保留的应用角色均有明确归属：
 
 - `@deepseek-ai/dsh-tui` 负责终端交互式执行。它会在 Loader 启动前拒绝非 TTY 流；`apps/cli/config/base.cordis.yml` 与 `tui.cordis.yml` overlay 拥有完整 coding 组装，PTY 与终端快照覆盖则位于 `apps/cli/tests/`。
-- [`@deepseek-ai/dsh-cli-demo`](../../../../packages/examples/cli-demo/README.md) 负责非交互式执行，包括管道方式。`examples/headless-agent` 拥有真实模型的单次任务组装、回放快照、通用真实 agent 测试套件，以及仅供测试使用的无密钥 Loader fixture。
+- [`dsh run`](../../../../apps/cli/README.md) 负责非交互式执行。其 `headless` profile 是产品组装；`examples/headless-agent` 负责回放快照、通用真实 agent 测试套件和未导出的无密钥 Loader driver。
 - [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) 和 `@deepseek-ai/dsh-jsonrpc` 负责各自的分帧协议集成。
 
 SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换为 `tui`；生成的 TUI 工程组合 `@deepseek-ai/dsh-tui`，并创建或恢复一个确切会话。仓库中的演示文档要求 DeepSeek API key，并优先引导到真实的 Headless 或 TUI agent。
 
-无密钥验证由测试负责。Headless Loader 冒烟测试使用 fixture 适配器验证真实工具往返；CLI built-bin 测试套件固定输出、持久化、失败和信号语义；各包专属的 Loader 测试则将确定性适配器放在对应场景旁。其中任何一项都不会作为可运行的 mock agent 对外暴露。
+无密钥验证由测试负责。Headless Loader 冒烟测试使用 fixture 适配器验证真实工具往返；`dsh` built-bin 测试套件固定单次运行的输出、持久化、失败和信号语义；各包专属的 Loader 测试则将确定性适配器放在对应场景旁。其中任何一项都不会作为可运行的 mock agent 对外暴露。
 
 ## 验证
 
 TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果契约和工具调用契约。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
 
-构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向其单次 `-p` 模式；`apps/cli/tests/built-bin.e2e.ts` 固定了该执行路径，而 `cli-demo` 的 built-bin 套件在普通 Node 下运行文本、JSON 和经过结构化解析的 `stream-json` 输出，持久化新建会话，并在不污染 stdout 的情况下拒绝无效参数和缺失配置。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过真实 Headless 组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
+构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性路径，包括输出、持久化、无效参数、缺失配置和信号。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）契约。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
new file mode 100644
index 0000000000..ae6e47b2c1
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.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-08-08-remove-cli-demo.md
+2026-08-08-remove-cli-demo.md: 5875f47f2d2463fd6f82f66df5ca08fef8e06aed
+2026-08-08-remove-cli-demo.zh.md: 1bb9e2c8860f57e1170527cee0cbe694af9990f6
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
new file mode 100644
index 0000000000..5875f47f2d
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
@@ -0,0 +1,34 @@
+# Agent Note: Remove the separate CLI demo
+
+Status: implemented
+
+English | [中文](2026-08-08-remove-cli-demo.zh.md)
+
+## Problem
+
+After [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) became the product one-shot command, `@deepseek-ai/dsh-cli-demo` remained a second application package for the same job. It carried another executable, argument grammar, app composition, cancellation lifecycle, text/JSON/stream-JSON output contract, built artifact, documentation surface, and test suite. The two front doors also assembled different trees, so a successful demo did not prove the shipped `headless` profile and users had to choose between overlapping commands.
+
+The replay suites still need canonical session events to pin assembled backend behavior. That testing need does not require a published command or compatibility contract.
+
+## Decision
+
+Delete `@deepseek-ai/dsh-cli-demo` completely: its package, bin, parser, app plugin, output formats, tests, workspace references, generated-catalog entries, and active documentation. No alias or compatibility package remains. The root `demo:headless` script is retained only as a direct alias of `dsh run`; the product command owns final-text stdout, the observation URL on stderr, persistence, exit status, and shutdown.
+
+`examples/headless-agent` becomes an explicit test composition. Its Loader configs mount `@deepseek-ai/dsh-agent-spine-demo`, one root agent, JSONL persistence, and checkpoint policy as separate rows instead of hiding them behind an app bundle. An unexported example-owned TypeScript fixture drives a task and emits canonical events as JSONL for replay snapshots. It is launched only by tests, has no package export or bin, and is not a supported product output format.
+
+## Alternatives considered
+
+- **Keep `dsh-cli-demo` as an alias or wrapper around `dsh run`.** Rejected because a second bin and package would preserve two discoverable owners without adding capability.
+- **Move JSON and stream-JSON flags onto `dsh run`.** Rejected because no current product consumer requires them; adopting the old demo protocol would enlarge the canonical CLI contract solely to save test machinery.
+- **Delete the canonical-event snapshots with the package.** Rejected because they pin model-visible assembled behavior that final-text product acceptance cannot observe.
+- **Keep the app plugin but delete only its bin.** Rejected because the hidden composition would still duplicate the explicit headless profile and conceal which services the test leaf mounts.
+
+## Consequences
+
+This is intentionally breaking. `dsh-cli-demo`, its `--output-format` choices, and imports from `@deepseek-ai/dsh-cli-demo/src/cli.ts` no longer resolve. There is no public event-stream replacement in this change; callers use `dsh run` for one-shot execution and must choose an existing protocol surface when they need structured automation.
+
+The repository retains backend replay coverage through test-only infrastructure, while product smoke and built-bin acceptance exercise `dsh run`. A separate one-shot package may return only if it owns a genuinely independent, versioned protocol that cannot belong to the product launcher; a second spelling or output shim is not enough.
+
+## Verification
+
+Focused Loader smokes cover the explicit composition in source and plain-Node built modes, snapshot tests diff its canonical JSONL and persisted logs, product acceptance covers `dsh run`, and documentation plus generated graph/catalog gates reject live references to the removed package. The frozen Agent Note archive remains historical evidence and is not rewritten.
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
new file mode 100644
index 0000000000..1bb9e2c886
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
@@ -0,0 +1,34 @@
+# Agent Note: 移除独立的 CLI demo
+
+Status: implemented
+
+[English](2026-08-08-remove-cli-demo.md) | 中文
+
+## 问题
+
+在 [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出契约、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
+
+回放套件仍需要规范会话事件来固定组装后的后端行为。这一测试需求不需要已发布命令或兼容性契约。
+
+## 决策
+
+彻底删除 `@deepseek-ai/dsh-cli-demo`：包括它的包、bin、解析器、应用插件、输出格式、测试、workspace 引用、生成目录条目和现行文档。不保留别名或兼容包。根目录的 `demo:headless` 脚本仅作为 `dsh run` 的直接别名保留；stdout 上的最终文本、stderr 上的观察 URL、持久化、退出状态和关闭行为均由产品命令负责。
+
+`examples/headless-agent` 成为显式测试组装。其 Loader 配置把 `@deepseek-ai/dsh-agent-spine-demo`、一个根 agent（智能体）、JSONL 持久化和检查点策略挂载为独立配置行，不再将其隐藏在应用组合包之后。一个由示例自有且未导出的 TypeScript fixture（测试前置数据）会驱动任务，并以 JSONL 发出供回放快照使用的规范事件。该 fixture 只由测试启动，没有包导出或 bin，也不是受支持的产品输出格式。
+
+## 考虑过的替代方案
+
+- **保留 `dsh-cli-demo` 作为 `dsh run` 的别名或包装层。** 不予采纳：第二个 bin 和包会让同一功能继续存在两个可发现的归属方，却没有增加任何能力。
+- **把 JSON 和 stream-JSON 标志移到 `dsh run`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）契约。
+- **随包一并删除规范事件快照。** 不予采纳：这些快照固定了模型可见的组装行为，而只检查最终文本的产品验收无法观察这些行为。
+- **保留应用插件，只删除它的 bin。** 不予采纳：隐藏的组装仍会重复显式的 headless profile，并掩盖测试叶节点挂载了哪些服务。
+
+## 后果
+
+这是有意为之的破坏性变更。`dsh-cli-demo`、它的 `--output-format` 选项以及对 `@deepseek-ai/dsh-cli-demo/src/cli.ts` 的导入都不再可解析。本变更不提供公开的事件流替代接口；调用方使用 `dsh run` 执行一次性任务，需要结构化自动化时则必须选择现有的协议接口。
+
+仓库通过仅供测试的基础设施保留后端回放覆盖，产品冒烟测试和 built-bin 验收则运行 `dsh run`。只有当独立的一次性包负责一套真正独立、带版本且不能归产品启动器所有的协议时，它才可以重新引入；第二种命令写法或输出 shim 并不足以构成理由。
+
+## 验证
+
+聚焦的 Loader 冒烟测试在源码模式和由普通 Node 启动的构建模式下覆盖显式组装，快照测试对比其规范 JSONL 和持久化日志，产品验收覆盖 `dsh run`，文档检查及生成图谱／目录门禁则拒绝对已移除包的活跃引用。冻结的 Agent Note 归档保留为历史证据，不会被重写。
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 2de89ef94b..778d74d406 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -21,7 +21,6 @@ flowchart LR
   pkg_session["session"]
   svc_sessions["ctx.sessions<br/>In-memory session store"]
   pkg_agent["agent"]
-  pkg_cli_demo["cli-demo"]
   pkg_session_persistence["session-persistence"]
   pkg_session_query["session-query"]
   pkg_session_query_sqlite["session-query-sqlite"]
@@ -260,7 +259,6 @@ flowchart LR
   svc_agentLoop --> pkg_agent_spine_demo
   svc_agents --> pkg_acp
   svc_agents --> pkg_agent_loop
-  svc_agents --> pkg_cli_demo
   svc_agents --> pkg_subagent_inprocess
   svc_approval --> pkg_tool_bash
   svc_approval --> pkg_tools
@@ -307,7 +305,6 @@ flowchart LR
   svc_sessionQuery --> pkg_tool_session_query
   svc_sessions --> pkg_agent
   svc_sessions --> pkg_agent_loop
-  svc_sessions --> pkg_cli_demo
   svc_sessions --> pkg_invariants
   svc_sessions --> pkg_session_persistence
   svc_sessions --> pkg_session_query
@@ -365,7 +362,7 @@ flowchart LR
 | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compact-basic`](../packages/compact/compact-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. |
 | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements. |
 | `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
-| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
 | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
 | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
@@ -387,7 +384,7 @@ flowchart LR
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
-| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
 | `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index eda24bb29f..2998e18c48 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -249,46 +249,6 @@ Depends on: [`LocalConfig`](#deepseek-aidsh-bash-local)
 
 Source: [`packages/bash/bash-sandbox/src/index.ts:35`](../packages/bash/bash-sandbox/src/index.ts)
 
-## `@deepseek-ai/dsh-cli-demo`
-
-```ts config-catalog
-/** App config forwarded to the spine, configured agent, and JSONL backend. */
-export interface Config {
-  /** Provider route for the configured agent. */
-  provider: string
-  /** Model name for the configured agent; a matching adapter must be registered. */
-  model: string
-  /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */
-  maxParallelToolCalls?: number
-  /** Deployment persona forwarded to the system-prompt plugin. */
-  persona?: string
-  /** Explicit model-facing tool order forwarded to the system-prompt plugin. */
-  toolOrder?: string[]
-  /** Tool-registry presentation config forwarded through agent-spine-demo. */
-  tools?: ToolsConfig
-  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
-  dshHome?: string
-  /** Fallback session-title limits forwarded through agent-spine-demo. */
-  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
-  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
-  persistenceRoot?: string
-  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
-  persistenceCompression?: JsonlCompression
-  /** Skill registry, local-provider, and model-facing consumer config. */
-  skills?: agentCore.SkillConfig
-  /** Model-facing bash tool config forwarded through agent-spine-demo. */
-  toolBash?: NonNullable<agentCore.Config['toolBash']>
-  /** Generic background-task control-tool config forwarded through agent-spine-demo. */
-  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
-  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
-  workspaceContext: agentCore.Config['workspaceContext']
-}
-```
-
-Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
-
-Source: [`packages/examples/cli-demo/src/index.ts:26`](../packages/examples/cli-demo/src/index.ts)
-
 ## `@deepseek-ai/dsh-client-connection`
 
 Requires: `httpServer`
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index acc8597d68..e341244f40 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/extension-cookbook.md
-extension-cookbook.md: 26f20b8f6cb57103b8e7340fcd21089ff1b0e5f6
-extension-cookbook.zh.md: b8bafdb73e91b56dd411cc5e96c21ccf2c5db123
+extension-cookbook.md: e04f6ffcf9a32ba3ee7344db18cad113b347c667
+extension-cookbook.zh.md: c2fa2f83c39ca0eb93397f39c88265c028224c7a
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index 26f20b8f6c..e04f6ffcf9 100644
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -90,7 +90,7 @@ export function apply(ctx: Context) {
 
 ## Runnable wirings
 
-Runnable leaves load their plugin trees from `examples/*/cordis.yml`; the root `demo:*` scripts and those leaf directories are the authoritative inventory. Non-interactive leaves use [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo), ACP leaves use [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), JSON-RPC leaves use [`@deepseek-ai/dsh-jsonrpc-demo`](../../packages/examples/jsonrpc-demo), and the app packages share [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo).
+Runnable leaves load their plugin trees from `examples/*/cordis.yml`; the root `demo:*` scripts and those leaf directories are the authoritative inventory. The product `dsh` launcher owns Web and one-shot headless execution, ACP leaves use [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), and JSON-RPC leaves use [`@deepseek-ai/dsh-jsonrpc-demo`](../../packages/examples/jsonrpc-demo). The headless snapshot leaf mounts [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) and JSONL persistence explicitly, then drives them through an example-owned test fixture rather than a shipped app package.
 
 ## The feature → mechanism map
 
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index b8bafdb73e..c2fa2f83c3 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -90,7 +90,7 @@ export function apply(ctx: Context) {
 
 ## 可运行的组装示例
 
-可运行叶子从 `examples/*/cordis.yml` 加载各自的插件树；根目录的 `demo:*` 脚本和这些叶子目录是权威清单。非交互式叶子使用 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo)，ACP 叶子使用 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，JSON-RPC 叶子使用 [`@deepseek-ai/dsh-jsonrpc-demo`](../../packages/examples/jsonrpc-demo)，应用包共享 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo)。
+可运行叶子从 `examples/*/cordis.yml` 加载各自的插件树；根目录的 `demo:*` 脚本和这些叶子目录是权威清单。产品 `dsh` 启动器负责 Web 和一次性 headless 执行，ACP 叶子使用 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，JSON-RPC 叶子使用 [`@deepseek-ai/dsh-jsonrpc-demo`](../../packages/examples/jsonrpc-demo)。headless 快照叶节点显式挂载 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) 和 JSONL 持久化，再通过示例自有的测试 fixture（测试前置数据）驱动这些组件，而不是通过已交付的 app 包。
 
 ## 功能→机制映射
 
@@ -122,7 +122,7 @@ export function apply(ctx: Context) {
 | Skill（技能） | section + 工具注册；调用时通过 `inject()` 注入 skill 内容 |
 | 记忆 | section provider + 工具 |
 | 定时任务（cron） | 插件注册面向模型的调度工具；定时器触发 → 空闲时 `followup(…, {source: {kind: 'cron', …}})`／忙碌时 `inject()` 通知 |
-| UI（GUI；CLI 输出 JSONL） | 监听 `session/event`（助手分片、边界、工具活动）；输入 → `followup()` |
+| UI（GUI；CLI（命令行界面）输出 JSONL） | 监听 `session/event`（助手分片、边界、工具活动）；输入 → `followup()` |
 | 遥测 / 可回放 trace | `session/event` → JSONL；回放 = `sessions.create(id, { seed })` |
 | 模型适配器 | 通过 `registerAdapter` 注册 `LlmAdapter` 子类（`dsh-llm-deepseek`、`dsh-llm-pi-ai`） |
 | 插件热重载 | 每个注册都是一个 `ctx.effect` → vendor 的 HMR（热模块替换）直接生效 |
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index fd8ed3b1fa..b4e5fa1795 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -32,7 +32,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index ab3ae725ae..05e2bd0b5d 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -205,7 +205,6 @@ flowchart TD
   subgraph group_examples["packages/examples"]
     pkg_acp_demo["acp-demo"]
     pkg_agent_spine_demo["agent-spine-demo"]
-    pkg_cli_demo["cli-demo"]
     pkg_jsonrpc_demo["jsonrpc-demo"]
   end
   subgraph group_feedback["packages/feedback"]
@@ -1145,16 +1144,6 @@ flowchart TD
   pkg_acp_demo --> pkg_session_query_sqlite
   pkg_acp_demo --> pkg_tools
   pkg_acp_demo --> pkg_workspace_context
-  pkg_cli_demo --> pkg_agent
-  pkg_cli_demo --> pkg_agent_spine_demo
-  pkg_cli_demo --> pkg_app_boot
-  pkg_cli_demo --> pkg_invariants
-  pkg_cli_demo --> pkg_llm
-  pkg_cli_demo --> pkg_session
-  pkg_cli_demo --> pkg_session_checkpoint_policy
-  pkg_cli_demo --> pkg_session_persistence_jsonl
-  pkg_cli_demo --> pkg_tools
-  pkg_cli_demo --> pkg_workspace_context
 ```
 
 | Package | Group | Depends on |
@@ -1350,4 +1339,3 @@ flowchart TD
 | [`sdk-client`](../packages/sdk/sdk-client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/sdk-client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
-| [`cli-demo`](../packages/examples/cli-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
index 2fcbea62e4..90970c8c57 100644
--- a/docs/testing.i18n.yaml
+++ b/docs/testing.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 docs/testing.md
-testing.md: 514ca4e1df7505b02350470d5de4a5ee3647634b
-testing.zh.md: 6d24d8e74d726d53fa3500f57e34238483c5481c
+testing.md: fecf02fe887aac5c92c739523f10a0562eba6242
+testing.zh.md: a34f56fac72baa9916d5f96e83048ad54cf23d4a
diff --git a/docs/testing.md b/docs/testing.md
index 514ca4e1df..fecf02fe88 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -9,7 +9,7 @@ How this repo tests, tier by tier, and the rules that keep a green suite meaning
 - **Unit** (`pnpm run test`): vitest over package and example specs under their `tests/**` directories plus repository script specs under `scripts/**/*.spec.ts`; tests stay with the code area they exercise. Every registry gets an HMR-safety test (dispose the contributing fiber, assert cleanup). Prefer edge cases, error paths, event ordering, concurrency races, and permanent contract regressions (see `packages/core/agent-loop/tests/contract-regressions.spec.ts`).
 - **Coverage gate** (`pnpm run test:coverage`): the gating run, per-file 100% on `packages/*/*/src`. An uncovered line is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on. Line coverage is necessary, never sufficient — it proves lines ran, not that the feature works as shipped. Per-file 100% on `packages/bash/pwsh-local/src` needs a real `pwsh`: without one its executor suites self-skip and `vitest.config.ts` exempts the file so pwsh-less hosts stay green, while CI runners ship pwsh and enforce the full bar.
 - **Real-API e2e** (`pnpm run test:e2e`): with-key tests against live provider APIs — the DeepSeek model plus provider-specific smokes that gate on their own keys (`EXA_API_KEY`, `PERPLEXITY_API_KEY`, …); each suite self-skips without its key so keyless CI stays green ([real-API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md)).
-- **Snapshot** (`pnpm run test:snapshot`): keyless expected outputs cover external behavior — transport contracts and presentation, while persisted logs pin assembled backend behavior. ACP boots the real automation-server example, replays a recorded session, and diffs normalized JSON-RPC plus the re-persisted log ([ACP snapshot Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)); headless pins `stream-json` through its real one-shot process. Use `pnpm run test:snapshot:record` when a model transcript changes and `pnpm run test:snapshot:refresh` when replay input remains valid; review every JSONL and expected-output diff. One ACP scenario (`text-turn`) pins full system-prompt/tool-schema content; other fixtures tokenize it so an edit churns one line ([pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **Snapshot** (`pnpm run test:snapshot`): keyless expected outputs cover external behavior — transport contracts and presentation, while persisted logs pin assembled backend behavior. ACP boots the real automation-server example, replays a recorded session, and diffs normalized JSON-RPC plus the re-persisted log ([ACP snapshot Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)); headless backend scenarios boot their explicit example composition through an unexported JSONL test driver, while `apps/cli` separately owns product `dsh run` acceptance. Use `pnpm run test:snapshot:record` when a model transcript changes and `pnpm run test:snapshot:refresh` when replay input remains valid; review every JSONL and expected-output diff. One ACP scenario (`text-turn`) pins full system-prompt/tool-schema content; other fixtures tokenize it so an edit churns one line ([pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
 - **Web browser snapshot** (`pnpm run test:web`; required Linux PR gate): Chromium compares replayed browser output with `apps/web/tests/snapshots/`. CI forces read-only `DSH_SNAPSHOT=replay`, never writing expected outputs; record/refresh stay local and every diff is reviewed ([web e2e lane](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md), [CI gate decision](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)). `test:web` [builds first](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md) for plugin CSS.
 
 Committed session-format JSONL uses the canonical packed-row layout, and the keyless snapshot gate discovers every such fixture by its `session` header. In-flight branches carrying older fixture edits merge current `master` and run the [temporary migrator](../scripts/migrate-packed-session-fixtures.ts) through `pnpm run migrate:packed-session-fixtures`; the [removal proposal](../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) retires that command and these links after all affected branches converge.
@@ -46,4 +46,4 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword
 
 ## When a snapshot test is required
 
-Every non-trivial model-, protocol-, or human-visible change adds or updates a keyless scenario in the same PR through a runnable example's owning snapshot suite. Package tests, e2e assertions, mock/test-only compositions, and PR rationale do not replace the assembled transcript; extend the harness when needed. ACP automation scenarios use `examples/<name>/tests/snapshots/`, a scenario table over the [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) suite factory (`examples/acp-agent` is primary); `examples/headless-agent` owns the `stream-json` snapshot and replay fixtures. The `pwsh-tool-turn` ACP scenario boots real `pwsh` and skips where it is absent. Completed interactive-terminal journeys use JSONL-driven scenarios under `apps/cli/tests/snapshots/`; transient presentation uses the package-local semantic matrix, with a PTY case when input, Loader selection, or terminal teardown changes. Browser-rendered web GUI journeys use `apps/web/tests/snapshots/`. New capability seams, lifecycle shapes, or transcript surfaces name every coverage tier at plan time and verify the harness can express it before implementation.
+Every non-trivial model-, protocol-, or human-visible change adds or updates a keyless scenario in the same PR through a runnable example's owning snapshot suite. Package tests, e2e assertions, mock/test-only compositions, and PR rationale do not replace the assembled transcript; extend the harness when needed. ACP automation scenarios use `examples/<name>/tests/snapshots/`, a scenario table over the [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) suite factory (`examples/acp-agent` is primary); `examples/headless-agent` owns the internal canonical-event JSONL snapshots and replay fixtures. The `pwsh-tool-turn` ACP scenario boots real `pwsh` and skips where it is absent. Completed interactive-terminal journeys use JSONL-driven scenarios under `apps/cli/tests/snapshots/`; transient presentation uses the package-local semantic matrix, with a PTY case when input, Loader selection, or terminal teardown changes. Browser-rendered web GUI journeys use `apps/web/tests/snapshots/`. New capability seams, lifecycle shapes, or transcript surfaces name every coverage tier at plan time and verify the harness can express it before implementation.
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
index 6d24d8e74d..a34f56fac7 100644
--- a/docs/testing.zh.md
+++ b/docs/testing.zh.md
@@ -9,7 +9,7 @@
 - **单元测试**（`pnpm run test`）：vitest 运行包（package）和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及永久性契约回归（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。
 - **覆盖率门禁**（`pnpm run test:coverage`）：门禁级运行，对 `packages/*/*/src` 按文件 100% 覆盖。未覆盖的行往往是门禁正确标记出的死代码（应删除），而非需要补写的测试。行覆盖率是必要条件，但永远不是充分条件：它证明行被执行过，不证明功能按交付预期工作。`packages/bash/pwsh-local/src` 的按文件 100% 覆盖需要真实的 `pwsh`：缺少它时其 executor 套件会自动跳过，`vitest.config.ts` 会豁免该文件以使无 pwsh 的主机保持绿色，而 CI runner 自带 pwsh，仍按完整标准执行门禁。
 - **真实 API e2e**（`pnpm run test:e2e`）：带密钥测试调用真实提供方 API，包括 DeepSeek 模型以及各提供方特有的冒烟测试；这些测试各自由自己的密钥控制（`EXA_API_KEY`、`PERPLEXITY_API_KEY` 等），缺少密钥时套件会自动跳过，使 keyless CI 保持绿色（[真实 API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md)）。
-- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输契约与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 通过真实单次运行进程固定 `stream-json`。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
+- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输契约与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
 - **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 将回放后的浏览器输出与 `apps/web/tests/snapshots/` 比较。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 车道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)以交付插件 CSS。
 
 签入仓库的会话格式 JSONL 使用规范打包行布局，无密钥快照门禁会通过 `session` header 发现每一份此类 fixture。仍携带旧版 fixture 改动的在途分支应合并当前 `master`，并通过 `pnpm run migrate:packed-session-fixtures` 运行[临时迁移器](../scripts/migrate-packed-session-fixtures.ts)；待所有受影响分支收敛后，[移除提案](../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)会移除该命令及这些链接。
@@ -46,4 +46,4 @@ e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身
 
 ## 何时需要快照测试
 
-每项非平凡的模型可见、协议可见或人类可见变更，都必须在同一 PR 中，通过可运行示例所属的快照套件添加或更新无密钥场景。包测试、e2e 断言、mock 与仅测试组合、PR 理由都不能取代组装后的 transcript；必要时应扩展 harness。ACP 自动化场景使用 `examples/<name>/tests/snapshots/`，即基于 [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) 套件工厂的场景表（`examples/acp-agent` 为主套件）；`examples/headless-agent` 拥有 `stream-json` 快照与回放 fixture。`pwsh-tool-turn` ACP 场景启动真实 `pwsh`，在无 `pwsh` 的主机上跳过。已完成的交互式终端旅程使用 `apps/cli/tests/snapshots/` 下由 JSONL 驱动的场景；瞬态呈现使用包内语义矩阵，输入、Loader 选择或终端清理发生变化时还要添加 PTY 用例。新的能力 seam、生命周期形态或 transcript 呈现接口在计划阶段就要列出每个覆盖层级，并在实现前验证 harness 能够表达它们。
+每项非平凡的模型可见、协议可见或人类可见变更，都必须在同一 PR 中，通过可运行示例所属的快照套件添加或更新无密钥场景。包测试、e2e 断言、mock 与仅测试组合、PR 理由都不能取代组装后的 transcript；必要时应扩展 harness。ACP 自动化场景使用 `examples/<name>/tests/snapshots/`，即基于 [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) 套件工厂的场景表（`examples/acp-agent` 为主套件）；`examples/headless-agent` 拥有内部规范事件 JSONL 快照与回放 fixture。`pwsh-tool-turn` ACP 场景启动真实 `pwsh`，在无 `pwsh` 的主机上跳过。已完成的交互式终端旅程使用 `apps/cli/tests/snapshots/` 下由 JSONL 驱动的场景；瞬态呈现使用包内语义矩阵，输入、Loader 选择或终端清理发生变化时还要添加 PTY 用例。新的能力 seam、生命周期形态或 transcript 呈现接口在计划阶段就要列出每个覆盖层级，并在实现前验证 harness 能够表达它们。
diff --git a/docs/user/guide/index.i18n.yaml b/docs/user/guide/index.i18n.yaml
index b722161724..a48c5bf842 100644
--- a/docs/user/guide/index.i18n.yaml
+++ b/docs/user/guide/index.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 docs/user/guide/index.md
-index.md: ede09506a996193fe5cf4ae6cd9b64d3529798a6
-index.zh.md: 5f72a6d3099d2d4721eccebae92eacfe72d33bce
+index.md: a04698e29755d4a08b012f8b61accb79c470dcb0
+index.zh.md: 85990f49c7b3cdf7518237c6b558375b7a636243
diff --git a/docs/user/guide/index.md b/docs/user/guide/index.md
index ede09506a9..a04698e297 100644
--- a/docs/user/guide/index.md
+++ b/docs/user/guide/index.md
@@ -12,12 +12,14 @@ Harness implements every capability an AI agent needs—including LLM calls, too
 # Select the LLM backend
 - name: '@deepseek-ai/dsh-llm-deepseek'
 
-# Select the one-shot application
-- id: cli-agent
-  name: '@deepseek-ai/dsh-cli-demo'
+# Compose one configured agent
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
-    provider: deepseek-official
-    model: deepseek-v4-flash
+    agents:
+      - id: main
+        provider: deepseek-official
+        model: deepseek-v4-flash
     workspaceContext: false
 ```
 
diff --git a/docs/user/guide/index.zh.md b/docs/user/guide/index.zh.md
index 5f72a6d309..85990f49c7 100644
--- a/docs/user/guide/index.zh.md
+++ b/docs/user/guide/index.zh.md
@@ -12,12 +12,14 @@ Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调
 # Select the LLM backend
 - name: '@deepseek-ai/dsh-llm-deepseek'
 
-# Select the one-shot application
-- id: cli-agent
-  name: '@deepseek-ai/dsh-cli-demo'
+# Compose one configured agent
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
-    provider: deepseek-official
-    model: deepseek-v4-flash
+    agents:
+      - id: main
+        provider: deepseek-official
+        model: deepseek-v4-flash
     workspaceContext: false
 ```
 
diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml
index aefb76991f..b5ab33db5f 100644
--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.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 docs/user/guide/quickstart.md
-quickstart.md: 8b84017ad33bf02579891bc4dcf83eaf7ec39022
-quickstart.zh.md: dfb24f8fa194866908406c709d059bf1f6595d59
+quickstart.md: 2f86ce4cb7896ca75b7457186d4633066a899b83
+quickstart.zh.md: f7ddf88c74b5a32daa1d2b81feeaed192e7a3f9c
diff --git a/docs/user/guide/quickstart.md b/docs/user/guide/quickstart.md
index 8b84017ad3..2f86ce4cb7 100644
--- a/docs/user/guide/quickstart.md
+++ b/docs/user/guide/quickstart.md
@@ -35,10 +35,10 @@ DEEPSEEK_API_KEY=sk-your-key-here
 Run a non-interactive task and print its final answer:
 
 ```sh
-pnpm run demo:headless "summarize the architecture of this workspace"
+pnpm run dsh run "summarize the architecture of this workspace"
 ```
 
-Headless runs one complete model/tool turn, persists the session, prints the result, and exits. Use `--output-format stream-json` when you need the canonical event stream.
+`dsh run` creates and persists a fresh session, prints the final assistant answer, and exits. While it runs, stderr prints the local browser URL where the session can be observed.
 
 ## Step 3: use the Web UI
 
@@ -53,7 +53,7 @@ Open `http://127.0.0.1:3080`. The agent can read and write files, run commands,
 
 ## What happened
 
-headless-agent uses the `@deepseek-ai/dsh-cli-demo` app. `dsh web` instead boots the `web` profile: the [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) and [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) bundle patch layers composed over an empty root. Both select the DeepSeek model and capability plugins appropriate to their entry mode.
+`dsh run` boots the `headless` profile: [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml), [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml), and [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) compose over an empty root. `dsh web` uses the first two layers without the one-shot runner. Both select the DeepSeek model and capability plugins appropriate to their entry mode.
 
 ## Next steps
 
diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md
index dfb24f8fa1..f7ddf88c74 100644
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -35,10 +35,10 @@ DEEPSEEK_API_KEY=sk-your-key-here
 运行一个非交互式任务并打印最终回答：
 
 ```sh
-pnpm run demo:headless "summarize the architecture of this workspace"
+pnpm run dsh run "summarize the architecture of this workspace"
 ```
 
-Headless 运行一个完整的模型/工具轮次，持久化会话，打印结果后退出。需要规范事件流时可使用 `--output-format stream-json`。
+`dsh run` 创建并持久化一个新会话，打印最终 assistant 回答，然后退出。运行期间，stderr 会打印可用于观察该会话的本地浏览器 URL。
 
 ## 第三步：使用 Web UI
 
@@ -53,7 +53,7 @@ pnpm run dsh web
 
 ## 回头看
 
-headless-agent 使用 `@deepseek-ai/dsh-cli-demo` app。`dsh web` 则启动 `web` profile：由 [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) 与 [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 两个组合包的 patch 层在空根之上组合而成。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
+`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml)、[`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合。`dsh web` 使用前两层，不包含一次性 runner。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
 
 ## 下一步
 
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-acp/cordis.yml b/examples/acp-agent/tests/fixtures/subagent/subagent-acp/cordis.yml
index c69cf574f7..6575f1b145 100644
--- a/examples/acp-agent/tests/fixtures/subagent/subagent-acp/cordis.yml
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-acp/cordis.yml
@@ -34,12 +34,22 @@
     # budget, so the local numeric default cannot apply here.
     maxDepth: 'provider-managed'
 
-- id: cli-agent
-  name: '@deepseek-ai/dsh-cli-demo'
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
-    provider: mock
-    model: mock-delegate
+    agents:
+      - id: main
+        provider: mock
+        model: mock-delegate
+        cwd: !!js process.cwd()
     persona: 'Test ACP subagent cwd inheritance.'
-    persistenceRoot: './.sessions'
-    persistenceCompression: 'none'
     workspaceContext: false
+
+- id: persistence
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+    compression: 'none'
+
+- id: checkpoint-policy
+  name: '@deepseek-ai/dsh-session-checkpoint-policy'
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-acp/driver.ts b/examples/acp-agent/tests/fixtures/subagent/subagent-acp/driver.ts
index d146b8df80..4436d52b24 100644
--- a/examples/acp-agent/tests/fixtures/subagent/subagent-acp/driver.ts
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-acp/driver.ts
@@ -2,14 +2,14 @@
 /** Test driver: one delegation turn through a headless Loader composition. */
 
 import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-import { runOneShot } from '@deepseek-ai/dsh-cli-demo/src/cli.ts'
+import { runFixtureTurn } from '../../../../../headless-agent/tests/fixtures/one-shot.ts'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('acp-subagent cwd driver requires a config path')
 
 const ctx = await boot('acp-subagent-cwd-e2e', resolveConfigPath(configPath, undefined))
 try {
-  await runOneShot(ctx, { task: 'delegate' })
+  await runFixtureTurn(ctx, { task: 'delegate' })
 } finally {
   await ctx.fiber.dispose()
 }
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/cordis.yml b/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/cordis.yml
index 2bfcd2af3f..fcdc0c4fb6 100644
--- a/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/cordis.yml
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/cordis.yml
@@ -31,10 +31,21 @@
     enableRunInBackground: false
     maxDepth: 'provider-managed'
 
-- id: cli-agent
-  name: '@deepseek-ai/dsh-cli-demo'
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
-    provider: mock
-    model: mock-delegate
+    agents:
+      - id: main
+        provider: mock
+        model: mock-delegate
+        cwd: !!js process.cwd()
     persona: 'This composition test must not start a model turn.'
     workspaceContext: false
+
+- id: persistence
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+
+- id: checkpoint-policy
+  name: '@deepseek-ai/dsh-session-checkpoint-policy'
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-codex/cordis.yml b/examples/acp-agent/tests/fixtures/subagent/subagent-codex/cordis.yml
index be1af7c135..e770b11c95 100644
--- a/examples/acp-agent/tests/fixtures/subagent/subagent-codex/cordis.yml
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-codex/cordis.yml
@@ -20,10 +20,21 @@
     enableRunInBackground: false
     maxDepth: 'provider-managed'
 
-- id: cli-agent
-  name: '@deepseek-ai/dsh-cli-demo'
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
-    provider: mock
-    model: mock-delegate
+    agents:
+      - id: main
+        provider: mock
+        model: mock-delegate
+        cwd: !!js process.cwd()
     persona: 'This composition test must not start a model turn.'
     workspaceContext: false
+
+- id: persistence
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+
+- id: checkpoint-policy
+  name: '@deepseek-ai/dsh-session-checkpoint-policy'
diff --git a/examples/headless-agent/README.i18n.yaml b/examples/headless-agent/README.i18n.yaml
index de50cce818..7b6139f28b 100644
--- a/examples/headless-agent/README.i18n.yaml
+++ b/examples/headless-agent/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 examples/headless-agent/README.md
-README.md: 670a91ab402cf98585f2ece70787beb3b4aaf4dc
-README.zh.md: 6c8b3b5694403c5e09f2904f5c3ca18fe569163e
+README.md: e00f3d2d4fd21a860239f3d3a3e5eb2d7520f14a
+README.zh.md: 6cd845783b1c112ba73676474b176ec28a4d0b78
diff --git a/examples/headless-agent/README.md b/examples/headless-agent/README.md
index 670a91ab40..e00f3d2d4f 100644
--- a/examples/headless-agent/README.md
+++ b/examples/headless-agent/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Headless one-shot agent wiring: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + JSONL persistence, with [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) as the app front door.
+This directory owns the replay and real-model test composition for a headless coding agent: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + JSONL persistence. It explicitly mounts the shared agent spine, one root agent, persistence, and checkpoint policy; it is not a second product front door.
 
 ## Run it
 
@@ -10,17 +10,13 @@ Headless one-shot agent wiring: DeepSeek V4 + local bash and filesystem tools +
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run demo:headless "fix the failing test in this workspace"
-pnpm run demo:headless --output-format json -- "summarize the implementation"
-pnpm run demo:headless --output-format stream-json -- "run the focused tests"
+pnpm run dsh run "fix the failing test in this workspace"
 ```
 
-Exactly one nonblank positional task is required; quote tasks containing spaces. There is no `-p` flag. `text` prints the last text-bearing assistant message, `json` prints one DSH-native result record, and `stream-json` emits the top-level session's canonical task-turn events before that record. Child sessions surface only through parent tool events and results.
+The product command is [`dsh run`](../../apps/cli/README.md): it accepts one nonblank task, creates and persists a fresh session, prints the final assistant text, and exits. The root `demo:headless` script is only an alias of that command.
 
-Each invocation creates and persists a fresh session, runs all model and tool steps in one turn, flushes, disposes, and exits. This is non-interactive automation: there is no prompt, approval, resume, second turn, or stdin context. The configured tools can mutate the launch workspace, run commands, spawn child agents, and consume provider tokens.
+Snapshot suites run this directory's configuration through [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts), an unexported test-only process that emits canonical session events as JSONL before its result record. That stream is test infrastructure, not a supported CLI output format. Child sessions surface only through parent tool events and results.
 
 ## Advanced configuration
 
-[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the shipped leaf.
-
-The package-level [CLI contract](../../packages/examples/cli-demo/README.md) documents output records, exit status, cancellation, persistence, and model/token effects.
+[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the test composition.
diff --git a/examples/headless-agent/README.zh.md b/examples/headless-agent/README.zh.md
index 6c8b3b5694..6cd845783b 100644
--- a/examples/headless-agent/README.zh.md
+++ b/examples/headless-agent/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-无头单次 agent（智能体）接线：DeepSeek V4 + 本地 bash 与文件系统工具 + subagent 委托 + 工作流与全新 agent Ralph 迭代 + `todo_write` + JSONL 持久化，并以 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) 作为应用入口。
+本目录负责 headless coding agent（智能体）的回放和真实模型测试组装：DeepSeek V4 + 本地 bash 与文件系统工具 + subagent 委托 + 工作流与全新 agent Ralph 迭代 + `todo_write` + JSONL 持久化。本目录显式挂载共享 agent 主干、一个根 agent、持久化和检查点策略；它不是第二个产品入口。
 
 ## 运行
 
@@ -10,17 +10,13 @@
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run demo:headless "fix the failing test in this workspace"
-pnpm run demo:headless --output-format json -- "summarize the implementation"
-pnpm run demo:headless --output-format stream-json -- "run the focused tests"
+pnpm run dsh run "fix the failing test in this workspace"
 ```
 
-必须提供一个且仅一个非空的任务位置参数；含空格的任务需要加引号。没有 `-p` 标志。`text` 打印最后一条包含文本的 assistant 消息，`json` 打印一条 DSH 原生结果记录，`stream-json` 则在该记录之前发出顶层会话的规范任务轮次事件。子会话只通过父会话的工具事件和结果对外显示。
+产品命令是 [`dsh run`](../../apps/cli/README.md)：它接受一项非空任务，创建并持久化新会话，打印最终 assistant 文本，然后退出。根目录的 `demo:headless` 脚本只是该命令的别名。
 
-每次调用都会创建并持久化新会话，在一个轮次中运行所有模型和工具步骤，然后刷写持久化数据、执行 dispose（资源释放），再退出。这是非交互式自动化：没有提示符、批准、恢复、第二轮次或 stdin 上下文。已配置工具可以修改启动时所在的工作区、运行命令、spawn 子 agent，并消耗提供方 token。
+快照套件通过 [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts) 运行本目录的配置。这个未导出且仅供测试使用的进程会在结果记录之前，以 JSONL 发出规范会话事件。该事件流属于测试基础设施，不是受支持的 CLI（命令行界面）输出格式。子会话只通过父会话的工具事件和结果对外显示。
 
 ## 高级配置
 
-[`advanced.cordis.yml`](advanced.cordis.yml) 在已交付叶节点上添加 Code Mode 和 Cordis 工具。
-
-这份包级 [CLI（命令行界面）契约](../../packages/examples/cli-demo/README.md) 说明输出记录、退出状态、取消、持久化以及模型／token 影响。
+[`advanced.cordis.yml`](advanced.cordis.yml) 在测试组装中添加 Code Mode 和 Cordis 工具。
diff --git a/examples/headless-agent/advanced.cordis.snapshot.yml b/examples/headless-agent/advanced.cordis.snapshot.yml
index 2cbdeb3698..881a976e33 100644
--- a/examples/headless-agent/advanced.cordis.snapshot.yml
+++ b/examples/headless-agent/advanced.cordis.snapshot.yml
@@ -1,6 +1,6 @@
 # Replay counterpart to advanced.cordis.yml. It includes the base `cordis.yml`
 # directly — a config patch cannot target an entry behind a nested include — and
-# restates advanced.cordis.yml's overlay (the cli-agent config plus the
+# restates advanced.cordis.yml's overlay (the agent and persistence configs plus the
 # code-runtime and tool-cordis inserts) so the whole app config lives in one patch.
 # It re-pins `deepseek-v4-flash`: `cordis.yml` ships `deepseek-v4-pro`, but the
 # recorded corpus (request headers, provenance) was captured on flash, so replay
@@ -15,15 +15,14 @@
       - id: llm-deepseek
         name: '@deepseek-ai/dsh-llm-deepseek'
         disabled: true
-      - id: cli-agent
-        name: '@deepseek-ai/dsh-cli-demo'
+      - id: agent-spine
+        name: '@deepseek-ai/dsh-agent-spine-demo'
         config:
-          provider: deepseek-official
-          model: deepseek-v4-flash
-          persistenceRoot: './.sessions'
-          # Replay fixtures are raw JSONL; the whole-config patch must restate
-          # the compression choice or the default zstd frames hide the logs.
-          persistenceCompression: none
+          agents:
+            - id: main
+              provider: deepseek-official
+              model: deepseek-v4-flash
+              cwd: !!js process.cwd()
           workspaceContext:
             maxBytes: 65536
           tools:
@@ -32,6 +31,13 @@
             You are headless-agent, a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}.
 
             Verify your work by running the code or tests. Keep answers brief and factual.
+      - id: persistence
+        name: '@deepseek-ai/dsh-session-persistence-jsonl'
+        config:
+          root: './.sessions'
+          # Replay fixtures are raw JSONL; the whole-config patch must restate
+          # the compression choice or the default zstd frames hide the logs.
+          compression: none
       - insert:
           - id: code-runtime
             name: '@deepseek-ai/dsh-code-runtime-worker'
diff --git a/examples/headless-agent/advanced.cordis.yml b/examples/headless-agent/advanced.cordis.yml
index a344e5e66a..09ecec6ea2 100644
--- a/examples/headless-agent/advanced.cordis.yml
+++ b/examples/headless-agent/advanced.cordis.yml
@@ -4,13 +4,14 @@
   config:
     path: ./cordis.yml
     patches:
-      - id: cli-agent
-        name: '@deepseek-ai/dsh-cli-demo'
+      - id: agent-spine
+        name: '@deepseek-ai/dsh-agent-spine-demo'
         config:
-          provider: deepseek-official
-          model: deepseek-v4-pro
-          persistenceRoot: './.sessions'
-          persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'"
+          agents:
+            - id: main
+              provider: deepseek-official
+              model: deepseek-v4-pro
+              cwd: !!js process.cwd()
           workspaceContext:
             maxBytes: 65536
           tools:
@@ -19,6 +20,11 @@
             You are headless-agent, a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}.
 
             Verify your work by running the code or tests. Keep answers brief and factual.
+      - id: persistence
+        name: '@deepseek-ai/dsh-session-persistence-jsonl'
+        config:
+          root: './.sessions'
+          compression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'"
       - insert:
           - id: code-runtime
             name: '@deepseek-ai/dsh-code-runtime-worker'
diff --git a/examples/headless-agent/composition.md b/examples/headless-agent/composition.md
index 6ef139d3d9..d319623702 100644
--- a/examples/headless-agent/composition.md
+++ b/examples/headless-agent/composition.md
@@ -1,9 +1,9 @@
 <!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
      Run `pnpm run gen-doc-graphs` to regenerate. -->
 
-# Headless Agent App Composition
+# Headless Agent Snapshot Composition
 
-The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.
+The headless snapshot composition combines the real DeepSeek adapter and coding capabilities with one explicitly configured persisted top-level agent; its JSONL driver is test-only.
 
 ```mermaid
 flowchart LR
@@ -18,15 +18,12 @@ flowchart LR
   cfg --> plugin_headless_subprocess
   plugin_headless_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
   cfg --> plugin_headless_bash
-  plugin_headless_cli_agent["cli-agent<br/>@deepseek-ai/dsh-cli-demo"]
-  cfg --> plugin_headless_cli_agent
-  plugin_headless_cli_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
-  plugin_headless_cli_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
-  plugin_headless_cli_agent --> frontdoor_cli["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]
-  bundle_agent_core --> spine_llm["ctx.llm"]
-  bundle_agent_core --> spine_sessions["ctx.sessions"]
-  bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
-  bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+  plugin_headless_agent_spine["agent-spine<br/>@deepseek-ai/dsh-agent-spine-demo"]
+  cfg --> plugin_headless_agent_spine
+  plugin_headless_persistence["persistence<br/>@deepseek-ai/dsh-session-persistence-jsonl"]
+  cfg --> plugin_headless_persistence
+  plugin_headless_checkpoint_policy["checkpoint-policy<br/>@deepseek-ai/dsh-session-checkpoint-policy"]
+  cfg --> plugin_headless_checkpoint_policy
   plugin_headless_token_meter["token-meter<br/>@deepseek-ai/dsh-token-meter"]
   cfg --> plugin_headless_token_meter
   plugin_headless_compact_basic["compact-basic<br/>@deepseek-ai/dsh-compact-basic"]
@@ -70,7 +67,9 @@ flowchart LR
 | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
 | `subprocess` | `@deepseek-ai/dsh-subprocess-local` |
 | `bash` | `@deepseek-ai/dsh-bash-local` |
-| `cli-agent` | `@deepseek-ai/dsh-cli-demo` |
+| `agent-spine` | `@deepseek-ai/dsh-agent-spine-demo` |
+| `persistence` | `@deepseek-ai/dsh-session-persistence-jsonl` |
+| `checkpoint-policy` | `@deepseek-ai/dsh-session-checkpoint-policy` |
 | `token-meter` | `@deepseek-ai/dsh-token-meter` |
 | `compact-basic` | `@deepseek-ai/dsh-compact-basic` |
 | `session-projection` | `@deepseek-ai/dsh-session-projection` |
diff --git a/examples/headless-agent/cordis.yml b/examples/headless-agent/cordis.yml
index b229846797..b6f1b774f2 100644
--- a/examples/headless-agent/cordis.yml
+++ b/examples/headless-agent/cordis.yml
@@ -40,17 +40,18 @@
   config:
     timeoutMs: 60000
 
-# The app bundle pre-creates one fresh `main` agent per invocation.
-- id: cli-agent
-  name: '@deepseek-ai/dsh-cli-demo'
+# The example composition pre-creates one fresh `main` agent for its test driver.
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
-    provider: deepseek-official
-    # Stays on flash: the goal/ralph replay corpora were recorded on it, and
-    # their nested-include overlays cannot re-pin the app config (a config
-    # patch cannot target an entry behind a nested include).
-    model: deepseek-v4-flash
-    persistenceRoot: './.sessions'
-    persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'"
+    agents:
+      - id: main
+        provider: deepseek-official
+        # Stays on flash: the goal/ralph replay corpora were recorded on it, and
+        # their nested-include overlays cannot re-pin the app config (a config
+        # patch cannot target an entry behind a nested include).
+        model: deepseek-v4-flash
+        cwd: !!js process.cwd()
     workspaceContext:
       maxBytes: 65536
     persona: |
@@ -59,6 +60,15 @@
       Verify your work by running the code or tests. Keep answers brief and
       factual.
 
+- id: persistence
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+    compression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'"
+
+- id: checkpoint-policy
+  name: '@deepseek-ai/dsh-session-checkpoint-policy'
+
 # Summarize an older range when derived history approaches the context window.
 - id: token-meter
   name: '@deepseek-ai/dsh-token-meter'
diff --git a/examples/headless-agent/tests/fixtures/cli.cordis.yml b/examples/headless-agent/tests/fixtures/cli.cordis.yml
index 72e71ec775..21a26bcd73 100644
--- a/examples/headless-agent/tests/fixtures/cli.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/cli.cordis.yml
@@ -12,15 +12,21 @@
       - id: llm-deepseek
         name: '@deepseek-ai/dsh-llm-deepseek'
         disabled: true
-      - id: cli-agent
-        name: '@deepseek-ai/dsh-cli-demo'
+      - id: agent-spine
+        name: '@deepseek-ai/dsh-agent-spine-demo'
         config:
-          provider: cli-mock
-          model: cli-mock
-          persistenceRoot: './.sessions'
+          agents:
+            - id: main
+              provider: cli-mock
+              model: cli-mock
+              cwd: !!js process.cwd()
           workspaceContext: false
           dshHome: './.dsh-home'
           skills:
             local:
               agentsHome: './.agents-home'
           persona: 'Keyless headless-agent smoke.'
+      - id: persistence
+        name: '@deepseek-ai/dsh-session-persistence-jsonl'
+        config:
+          root: './.sessions'
diff --git a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
index c501901604..274a8804ee 100644
--- a/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/deepseek-defaults.cordis.yml
@@ -7,10 +7,15 @@
         config:
           baseURL: !!js process.env.DSH_SNAPSHOT_BASE_URL
           thinking: disabled
-      - id: cli-agent
+      - id: agent-spine
         config:
-          provider: deepseek-official
-          model: deepseek-v4-flash
-          persistenceRoot: './.sessions'
+          agents:
+            - id: main
+              provider: deepseek-official
+              model: deepseek-v4-flash
+              cwd: !!js process.cwd()
           workspaceContext: false
           persona: 'Keyless DeepSeek adapter defaults snapshot.'
+      - id: persistence
+        config:
+          root: './.sessions'
diff --git a/examples/headless-agent/tests/fixtures/goal-domain/cordis.yml b/examples/headless-agent/tests/fixtures/goal-domain/cordis.yml
index d66713526e..6502dd845f 100644
--- a/examples/headless-agent/tests/fixtures/goal-domain/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/goal-domain/cordis.yml
@@ -17,12 +17,22 @@
 - id: seed-goal
   name: './seed-goal.ts'
 
-- id: cli-agent
-  name: '@deepseek-ai/dsh-cli-demo'
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
-    provider: cli-mock
-    model: cli-mock
+    agents:
+      - id: main
+        provider: cli-mock
+        model: cli-mock
+        cwd: !!js process.cwd()
     persona: 'Test the persisted goal domain.'
-    persistenceRoot: './.sessions'
-    persistenceCompression: none
     workspaceContext: false
+
+- id: persistence
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+    compression: none
+
+- id: checkpoint-policy
+  name: '@deepseek-ai/dsh-session-checkpoint-policy'
diff --git a/examples/headless-agent/tests/fixtures/headless-driver.ts b/examples/headless-agent/tests/fixtures/headless-driver.ts
new file mode 100644
index 0000000000..d9a30afa83
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/headless-driver.ts
@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/** Snapshot-only Loader driver: stream one fixture turn as canonical JSONL. */
+
+import type { Context } from 'cordis'
+import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { runFixtureTurn } from './one-shot.ts'
+
+const NAME = 'headless-test-driver'
+const [configPath, ...taskParts] = process.argv.slice(2)
+if (configPath === undefined || taskParts.length === 0 || taskParts.every(part => part.trim() === '')) {
+  throw new Error(`${NAME}: expected <config-path> <task...>`)
+}
+
+const uninstallFailLoud = installFailLoud(NAME)
+let ctx: Context | undefined
+try {
+  loadEnv(NAME)
+  ctx = await boot(NAME, resolveConfigPath(configPath, process.env.DSH_SNAPSHOT))
+  const result = await runFixtureTurn(ctx, {
+    task: taskParts.join(' '),
+    onEvent: (sessionId: string, event: SessionEvent) => {
+      process.stdout.write(`${JSON.stringify({ type: 'session_event', sessionId, event })}\n`)
+    },
+  })
+  process.stdout.write(`${JSON.stringify(result)}\n`)
+} catch (error: unknown) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+  process.exitCode = 1
+} finally {
+  await ctx?.fiber.dispose()
+  uninstallFailLoud()
+}
diff --git a/examples/headless-agent/tests/fixtures/one-shot.ts b/examples/headless-agent/tests/fixtures/one-shot.ts
new file mode 100644
index 0000000000..79b84da36f
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/one-shot.ts
@@ -0,0 +1,97 @@
+/** Test-only direct-agent turn driver shared by assembled Loader fixtures. */
+
+import type { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { createUserMessage, type TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+/** Result envelope consumed only by snapshot and composition tests. */
+export interface FixtureTurnResult {
+  readonly type: 'result'
+  readonly sessionId: string
+  readonly output: string
+  readonly usage?: TokenUsage
+}
+
+/** Options for one fixture turn against exactly one configured root agent. */
+export interface FixtureTurnOptions {
+  readonly task: string
+  readonly onEvent?: (sessionId: string, event: SessionEvent) => void
+}
+
+function addUsage(total: TokenUsage | undefined, step: TokenUsage): TokenUsage {
+  const next: TokenUsage = {
+    inputTokens: (total?.inputTokens ?? 0) + step.inputTokens,
+    outputTokens: (total?.outputTokens ?? 0) + step.outputTokens,
+  }
+  for (const key of ['cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens'] as const) {
+    if (total?.[key] !== undefined || step[key] !== undefined) next[key] = (total?.[key] ?? 0) + (step[key] ?? 0)
+  }
+  return next
+}
+
+function assistantText(event: Extract<SessionEvent, { type: 'assistant/message' }>): string | undefined {
+  const blocks = event.data.message.content.filter(block => block.type === 'text')
+  return blocks.length === 0 ? undefined : blocks.map(block => block.text).join('')
+}
+
+function onlyRootAgent(ctx: Context): Agent {
+  const agents = ctx.get('agents')?.roots() ?? []
+  const [agent] = agents
+  if (agent === undefined || agents.length !== 1) {
+    throw new Error(`headless fixture requires exactly one top-level agent, found ${agents.length}`)
+  }
+  return agent
+}
+
+/**
+ * Drive one task from its durable inbox receipt through whole-agent idle.
+ * @param ctx - settled Loader context with exactly one configured root agent.
+ * @param options - task and optional canonical-event observer.
+ * @returns the final assistant text and accumulated model usage.
+ */
+export async function runFixtureTurn(ctx: Context, options: FixtureTurnOptions): Promise<FixtureTurnResult> {
+  const agent = onlyRootAgent(ctx)
+  await agent.whenIdle()
+
+  const message = createUserMessage({
+    content: [{ type: 'text', text: options.task }],
+    source: { kind: 'user' },
+  })
+  let received = false
+  let output = ''
+  const usageByStep = new Map<string, TokenUsage>()
+  const disposeListener = ctx.on('session/event', (session, event) => {
+    if (session !== agent.session) return
+    if (!received) {
+      if (event.type !== 'agent/inbox/spliced'
+        || !event.data.inserted.some(inserted => inserted.id === message.id)) return
+      received = true
+    }
+    options.onEvent?.(session.id, event)
+    if (event.type === 'assistant/chunk' && event.data.chunk.type === 'usage') {
+      usageByStep.set(`${event.data.turn}/${event.data.step}`, event.data.chunk.usage)
+    }
+    if (event.type === 'assistant/message') {
+      output = assistantText(event) ?? output
+      if (event.data.usage !== undefined) {
+        usageByStep.set(`${event.data.turn}/${event.data.step}`, event.data.usage)
+      }
+    }
+  })
+
+  try {
+    agent.followup(message)
+    await agent.whenIdle()
+  } finally {
+    disposeListener()
+  }
+  await ctx.sessions.flush(agent.session)
+  const usage = [...usageByStep.values()].reduce<TokenUsage | undefined>(addUsage, undefined)
+  return {
+    type: 'result',
+    sessionId: agent.session.id,
+    output,
+    ...usage === undefined ? {} : { usage },
+  }
+}
diff --git a/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts b/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts
index 72305f0724..f7e1001628 100644
--- a/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts
+++ b/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts
@@ -10,8 +10,8 @@ import { writeFile } from 'node:fs/promises'
 import { createServer } from 'node:http'
 import { once } from 'node:events'
 import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-import { runOneShot } from '@deepseek-ai/dsh-cli-demo/src/cli.ts'
 import { recordFeedback } from '@deepseek-ai/dsh-command-feedback'
+import { runFixtureTurn } from './one-shot.ts'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('telemetry-otel driver requires a config path')
@@ -35,14 +35,14 @@ const ctx = await boot('telemetry-otel-e2e', resolveConfigPath(configPath, undef
 try {
   // The fixture credential rides the model-visible user message; the exported
   // copy must scrub it while the canonical log keeps the original bytes.
-  await runOneShot(ctx, { task: 'prove telemetry with key sk-e2efixture1234567890' })
+  await runFixtureTurn(ctx, { task: 'prove telemetry with key sk-e2efixture1234567890' })
   const mode = process.env.DSH_TELEMETRY_E2E_MODE ?? 'FULL'
   if (mode !== 'FULL') {
     const [agent] = ctx.get('agents')?.roots() ?? []
     if (agent === undefined) throw new Error('telemetry-otel driver requires one root agent')
     recordFeedback(agent.session, 'fixture feedback')
     if (mode === 'FEEDBACK_ONLY') {
-      await runOneShot(ctx, { task: 'post-feedback private suffix' })
+      await runFixtureTurn(ctx, { task: 'post-feedback private suffix' })
     }
   }
 } finally {
diff --git a/examples/headless-agent/tests/fixtures/telemetry-otel.cordis.yml b/examples/headless-agent/tests/fixtures/telemetry-otel.cordis.yml
index d398c4c825..27172b40d8 100644
--- a/examples/headless-agent/tests/fixtures/telemetry-otel.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/telemetry-otel.cordis.yml
@@ -30,12 +30,22 @@
     exporter:
       url: !!js process.env.DSH_TELEMETRY_E2E_URL
 
-- id: cli-agent
-  name: '@deepseek-ai/dsh-cli-demo'
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
-    provider: cli-mock
-    model: cli-mock
+    agents:
+      - id: main
+        provider: cli-mock
+        model: cli-mock
+        cwd: !!js process.cwd()
     persona: 'Test the session-telemetry-otel plugin.'
-    persistenceRoot: './.sessions'
-    persistenceCompression: 'none'
     workspaceContext: false
+
+- id: persistence
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+    compression: 'none'
+
+- id: checkpoint-policy
+  name: '@deepseek-ai/dsh-session-checkpoint-policy'
diff --git a/examples/headless-agent/tests/fixtures/time-context-driver.ts b/examples/headless-agent/tests/fixtures/time-context-driver.ts
index cac81daeec..843bbdc2ea 100644
--- a/examples/headless-agent/tests/fixtures/time-context-driver.ts
+++ b/examples/headless-agent/tests/fixtures/time-context-driver.ts
@@ -2,15 +2,15 @@
 /** Test driver that sends two turns through one Headless Loader composition. */
 
 import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-import { runOneShot } from '@deepseek-ai/dsh-cli-demo/src/cli.ts'
+import { runFixtureTurn } from './one-shot.ts'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('time-context driver requires a config path')
 
 const ctx = await boot('time-context-e2e', resolveConfigPath(configPath, undefined))
 try {
-  await runOneShot(ctx, { task: 'first' })
-  await runOneShot(ctx, { task: 'second' })
+  await runFixtureTurn(ctx, { task: 'first' })
+  await runFixtureTurn(ctx, { task: 'second' })
 } finally {
   await ctx.fiber.dispose()
 }
diff --git a/examples/headless-agent/tests/fixtures/time-context.cordis.yml b/examples/headless-agent/tests/fixtures/time-context.cordis.yml
index a105652e9c..ec6359d167 100644
--- a/examples/headless-agent/tests/fixtures/time-context.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/time-context.cordis.yml
@@ -12,12 +12,22 @@
 - id: time-context
   name: '@deepseek-ai/dsh-time-context'
 
-- id: cli-agent
-  name: '@deepseek-ai/dsh-cli-demo'
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
-    provider: time-context-mock
-    model: time-context-mock
+    agents:
+      - id: main
+        provider: time-context-mock
+        model: time-context-mock
+        cwd: !!js process.cwd()
     persona: 'Test the time-context plugin.'
-    persistenceRoot: './.sessions'
-    persistenceCompression: 'none'
     workspaceContext: false
+
+- id: persistence
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+    compression: 'none'
+
+- id: checkpoint-policy
+  name: '@deepseek-ai/dsh-session-checkpoint-policy'
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index e8561b0196..87261439da 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -47,7 +47,7 @@ const ralphScenarioDir = join(snapshotsDir, 'ralph-loop')
 const ralphConfigPath = fileURLToPath(new URL('../ralph.cordis.snapshot.yml', import.meta.url))
 const startupFailureConfigPath = fileURLToPath(new URL('./fixtures/startup-activation-error/cordis.yml', import.meta.url))
 const startupFailureExpected = join(snapshotsDir, 'startup-activation-error', 'stderr.expected.txt')
-const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('./fixtures/headless-driver.ts', import.meta.url))
 const dshBinScript = fileURLToPath(new URL('../../../apps/cli/src/bin.ts', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 const reasoningConfigPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', import.meta.url))
@@ -242,8 +242,9 @@ describe('headless stream-json snapshots', () => {
       label: 'headless startup activation error snapshot',
       tempDirPrefix: 'headless-snapshot-startup-error-',
       binScript,
+      libBinScript: binScript,
       configPath: startupFailureConfigPath,
-      binArgs: ['--config', startupFailureConfigPath, '--output-format', 'stream-json', 'unreachable task'],
+      binArgs: [startupFailureConfigPath, 'unreachable task'],
       tsconfigPath,
       expectedExitCode: 1,
     })
@@ -259,8 +260,9 @@ describe('headless stream-json snapshots', () => {
       label: 'provider retry headless stream-json snapshot',
       tempDirPrefix: 'headless-snapshot-provider-retry-',
       binScript,
+      libBinScript: binScript,
       configPath: retryConfigPath,
-      binArgs: ['--config', retryConfigPath, '--output-format', 'stream-json', prompt],
+      binArgs: [retryConfigPath, prompt],
       tsconfigPath,
       env: {
         DSH_SNAPSHOT: 'replay',
@@ -299,8 +301,9 @@ describe('headless stream-json snapshots', () => {
       label: 'compaction recovery headless stream-json snapshot',
       tempDirPrefix: 'headless-snapshot-compaction-recovery-',
       binScript,
+      libBinScript: binScript,
       configPath: compactionConfigPath,
-      binArgs: ['--config', compactionConfigPath, '--output-format', 'stream-json', prompt],
+      binArgs: [compactionConfigPath, prompt],
       tsconfigPath,
       env: {
         DSH_SNAPSHOT: 'replay',
@@ -367,8 +370,9 @@ describe('headless stream-json snapshots', () => {
       label: 'missing-credential headless stream-json snapshot',
       tempDirPrefix: 'headless-snapshot-missing-credential-',
       binScript,
+      libBinScript: binScript,
       configPath: credentialsConfigPath,
-      binArgs: ['--config', credentialsConfigPath, '--output-format', 'stream-json', 'say pong'],
+      binArgs: [credentialsConfigPath, 'say pong'],
       tsconfigPath,
       env: {
         // First-run posture: no key in the environment, none under ./.dsh.
@@ -404,8 +408,9 @@ describe('headless stream-json snapshots', () => {
       label: 'invalid-credential headless stream-json snapshot',
       tempDirPrefix: 'headless-snapshot-invalid-credential-',
       binScript,
+      libBinScript: binScript,
       configPath: credentialsConfigPath,
-      binArgs: ['--config', credentialsConfigPath, '--output-format', 'stream-json', 'say pong'],
+      binArgs: [credentialsConfigPath, 'say pong'],
       tsconfigPath,
       env: {
         // A key that exists but no HTTP header can carry — the paste this
@@ -438,8 +443,9 @@ describe('headless stream-json snapshots', () => {
       label: 'reasoning effort headless stream-json snapshot',
       tempDirPrefix: 'headless-snapshot-reasoning-effort-',
       binScript,
+      libBinScript: binScript,
       configPath: reasoningConfigPath,
-      binArgs: ['--config', reasoningConfigPath, '--output-format', 'stream-json', 'prove dynamic reasoning effort'],
+      binArgs: [reasoningConfigPath, 'prove dynamic reasoning effort'],
       tsconfigPath,
     })
 
@@ -480,12 +486,10 @@ describe('headless stream-json snapshots', () => {
         label: 'DeepSeek adapter defaults headless stream-json snapshot',
         tempDirPrefix: 'headless-snapshot-deepseek-defaults-',
         binScript,
+        libBinScript: binScript,
         configPath: deepseekDefaultsConfigPath,
         binArgs: [
-          '--config',
           deepseekDefaultsConfigPath,
-          '--output-format',
-          'stream-json',
           'return the deterministic response',
         ],
         tsconfigPath,
@@ -540,8 +544,9 @@ describe('headless stream-json snapshots', () => {
       label: 'advanced headless stream-json snapshot',
       tempDirPrefix: 'headless-snapshot-advanced-',
       binScript,
+      libBinScript: binScript,
       configPath: advancedConfigPath,
-      binArgs: ['--config', advancedConfigPath, '--output-format', 'stream-json', prompt],
+      binArgs: [advancedConfigPath, prompt],
       tsconfigPath,
       env: {
         DSH_SNAPSHOT: 'replay',
@@ -611,8 +616,9 @@ describe('headless stream-json snapshots', () => {
       label: 'goal tools headless stream-json snapshot',
       tempDirPrefix: 'headless-snapshot-goal-tools-',
       binScript,
+      libBinScript: binScript,
       configPath: goalConfigPath,
-      binArgs: ['--config', goalConfigPath, '--output-format', 'stream-json', prompt],
+      binArgs: [goalConfigPath, prompt],
       tsconfigPath,
       env: {
         DSH_SNAPSHOT: 'replay',
@@ -667,8 +673,9 @@ describe('headless stream-json snapshots', () => {
       label: 'Ralph loop headless stream-json snapshot',
       tempDirPrefix: 'headless-snapshot-ralph-loop-',
       binScript,
+      libBinScript: binScript,
       configPath: ralphConfigPath,
-      binArgs: ['--config', ralphConfigPath, '--output-format', 'stream-json', prompt],
+      binArgs: [ralphConfigPath, prompt],
       tsconfigPath,
       env: {
         DSH_SNAPSHOT: 'replay',
@@ -748,8 +755,9 @@ describe('headless stream-json snapshots', () => {
       label: 'headless persistent PTY snapshot',
       tempDirPrefix: 'headless-snapshot-pty-',
       binScript,
+      libBinScript: binScript,
       configPath: ptyConfigPath,
-      binArgs: ['--config', ptyConfigPath, '--output-format', 'stream-json', prompt],
+      binArgs: [ptyConfigPath, prompt],
       tsconfigPath,
       env: {
         DSH_SNAPSHOT: 'replay',
diff --git a/examples/headless-agent/tests/keyless-smoke.e2e.ts b/examples/headless-agent/tests/keyless-smoke.e2e.ts
index 2547d04ac1..8b69406c53 100644
--- a/examples/headless-agent/tests/keyless-smoke.e2e.ts
+++ b/examples/headless-agent/tests/keyless-smoke.e2e.ts
@@ -9,7 +9,7 @@ import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-l
 import { PREPARED_ENTRY_FILENAME, prepareDshPlugin } from '@deepseek-ai/dsh-repository-plugin'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 
-const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('./fixtures/headless-driver.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 const decompress = promisify(zstdDecompress)
@@ -21,8 +21,9 @@ describe('headless-agent keyless smoke', () => {
       label: 'headless-agent',
       tempDirPrefix: 'headless-agent-smoke-',
       binScript,
+      libBinScript: binScript,
       configPath,
-      binArgs: ['--config', configPath, '--output-format', 'stream-json', 'prove the tool path'],
+      binArgs: [configPath, 'prove the tool path'],
       tsconfigPath,
       inspect: async (cwd) => {
         const files = await readdir(cwd, { recursive: true })
diff --git a/examples/headless-agent/tests/real-model.e2e.ts b/examples/headless-agent/tests/real-model.e2e.ts
index 653f5ab624..6276077aaa 100644
--- a/examples/headless-agent/tests/real-model.e2e.ts
+++ b/examples/headless-agent/tests/real-model.e2e.ts
@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 
-const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('./fixtures/headless-driver.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 const hasKey = Boolean(process.env.DEEPSEEK_API_KEY)
@@ -16,9 +16,9 @@ describe.skipIf(!hasKey)('headless-agent with real model', () => {
       label: 'headless-agent real model',
       tempDirPrefix: 'headless-agent-real-',
       binScript,
+      libBinScript: binScript,
       configPath,
       binArgs: [
-        '--config',
         configPath,
         'Read task.txt, replace its complete contents with exactly "value=after" followed by a newline, read it again, and report briefly.',
       ],
diff --git a/examples/headless-agent/tests/semantic-checkpoint.snapshot.ts b/examples/headless-agent/tests/semantic-checkpoint.snapshot.ts
index de41799b76..a8b8f02b9a 100644
--- a/examples/headless-agent/tests/semantic-checkpoint.snapshot.ts
+++ b/examples/headless-agent/tests/semantic-checkpoint.snapshot.ts
@@ -14,7 +14,7 @@ const replayFixture = join(fixtureDir, 'replay.jsonl')
 const replayOverride = join(fixtureDir, 'replay.override.json')
 const sessionExpected = join(fixtureDir, 'session.expected.jsonl')
 const configPath = fileURLToPath(new URL('../semantic-checkpoint.cordis.snapshot.yml', import.meta.url))
-const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('./fixtures/headless-driver.ts', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 const sessionId = SessionId('semantic-checkpoint-unknown-outcome')
 const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
@@ -87,8 +87,9 @@ describe('semantic checkpoint recovery snapshot', () => {
       label: 'semantic checkpoint headless stream-json snapshot',
       tempDirPrefix: 'dsh-semantic-snapshot-',
       binScript,
+      libBinScript: binScript,
       configPath,
-      binArgs: ['--config', configPath, '--output-format', 'stream-json', task],
+      binArgs: [configPath, task],
       tsconfigPath,
       env: {
         DSH_SNAPSHOT_FILE: replayFixture,
diff --git a/examples/headless-agent/tests/snapshots/startup-activation-error/stderr.expected.txt b/examples/headless-agent/tests/snapshots/startup-activation-error/stderr.expected.txt
index cd688cd471..f3252180b9 100644
--- a/examples/headless-agent/tests/snapshots/startup-activation-error/stderr.expected.txt
+++ b/examples/headless-agent/tests/snapshots/startup-activation-error/stderr.expected.txt
@@ -1,3 +1,3 @@
-dsh-cli-demo: dsh-cli-demo: plugin tree failed to load: failed to apply loader entry include (cordis:include): failed to apply loader entry activation-error (./activation-error.mjs): startup activation snapshot failure
+headless-test-driver: plugin tree failed to load: failed to apply loader entry include (cordis:include): failed to apply loader entry activation-error (./activation-error.mjs): startup activation snapshot failure
 Error: startup activation snapshot failure
     at activation-error-fixture
diff --git a/examples/headless-agent/tests/subagent-diagnostic.snapshot.ts b/examples/headless-agent/tests/subagent-diagnostic.snapshot.ts
index dc978b37f6..998c9129a5 100644
--- a/examples/headless-agent/tests/subagent-diagnostic.snapshot.ts
+++ b/examples/headless-agent/tests/subagent-diagnostic.snapshot.ts
@@ -19,7 +19,7 @@ const fixtureDir = fileURLToPath(new URL('./subagent-diagnostic-snapshots/descri
 const replayOverride = join(fixtureDir, 'replay.override.json')
 const parentExpected = join(fixtureDir, 'parent.expected.jsonl')
 const configPath = fileURLToPath(new URL('../subagent-diagnostic.cordis.snapshot.yml', import.meta.url))
-const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('./fixtures/headless-driver.ts', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 const parentId = SessionId('subagent-diagnostic-parent')
 const childId = SessionId('subagent-diagnostic-child')
@@ -77,8 +77,9 @@ describe('descriptor-less cold child diagnostic snapshot', () => {
       label: 'subagent diagnostic headless stream-json snapshot',
       tempDirPrefix: 'dsh-subagent-diag-',
       binScript,
+      libBinScript: binScript,
       configPath,
-      binArgs: ['--config', configPath, '--output-format', 'stream-json', task],
+      binArgs: [configPath, task],
       tsconfigPath,
       env: {
         DSH_SNAPSHOT_FILE: replayOverride,
diff --git a/examples/headless-agent/tests/subagent-inheritance.snapshot.ts b/examples/headless-agent/tests/subagent-inheritance.snapshot.ts
index e5f6994d0c..be5be2b357 100644
--- a/examples/headless-agent/tests/subagent-inheritance.snapshot.ts
+++ b/examples/headless-agent/tests/subagent-inheritance.snapshot.ts
@@ -20,7 +20,7 @@ const childReplay = join(fixtureDir, 'child.replay.jsonl')
 const parentExpected = join(fixtureDir, 'parent.expected.jsonl')
 const childExpected = join(fixtureDir, 'child.expected.jsonl')
 const configPath = fileURLToPath(new URL('../subagent-inheritance.cordis.snapshot.yml', import.meta.url))
-const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('./fixtures/headless-driver.ts', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 const sessionId = SessionId('subagent-inheritance-parent')
 const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
@@ -59,8 +59,9 @@ describe('parent-only override inheritance snapshot', () => {
       label: 'subagent inheritance headless stream-json snapshot',
       tempDirPrefix: 'dsh-subagent-inherit-',
       binScript,
+      libBinScript: binScript,
       configPath,
-      binArgs: ['--config', configPath, '--output-format', 'stream-json', task],
+      binArgs: [configPath, task],
       tsconfigPath,
       env: {
         // The primary fixture path must exist for llm-replay's config guard;
diff --git a/examples/headless-agent/tests/workspace-context-resume.snapshot.ts b/examples/headless-agent/tests/workspace-context-resume.snapshot.ts
index 789a859746..afe2ba325a 100644
--- a/examples/headless-agent/tests/workspace-context-resume.snapshot.ts
+++ b/examples/headless-agent/tests/workspace-context-resume.snapshot.ts
@@ -28,7 +28,7 @@ const replayOverride = join(fixtureDir, 'replay.override.json')
 const sessionExpected = join(fixtureDir, 'session.expected.jsonl')
 const precedenceExpected = join(dirname(fixtureDir), 'precedence-change/session.expected.jsonl')
 const configPath = fileURLToPath(new URL('../workspace-context-resume.cordis.snapshot.yml', import.meta.url))
-const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('./fixtures/headless-driver.ts', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 const sessionId = SessionId('workspace-context-resume')
 const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
@@ -119,8 +119,9 @@ describe('workspace-context resume snapshot', () => {
       label: 'workspace-context resume headless stream-json snapshot',
       tempDirPrefix: 'dsh-workspace-context-resume-',
       binScript,
+      libBinScript: binScript,
       configPath,
-      binArgs: ['--config', configPath, '--output-format', 'stream-json', 'Acknowledge the current workspace instruction.'],
+      binArgs: [configPath, 'Acknowledge the current workspace instruction.'],
       tsconfigPath,
       env: {
         DSH_SNAPSHOT_FILE: replayFixture,
@@ -175,8 +176,9 @@ describe('workspace-context resume snapshot', () => {
       label: 'workspace-context precedence-change resume snapshot',
       tempDirPrefix: 'dsh-workspace-context-precedence-',
       binScript,
+      libBinScript: binScript,
       configPath,
-      binArgs: ['--config', configPath, '--output-format', 'stream-json', 'Acknowledge the current workspace instruction.'],
+      binArgs: [configPath, 'Acknowledge the current workspace instruction.'],
       tsconfigPath,
       env: {
         DSH_SNAPSHOT_FILE: replayFixture,
diff --git a/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/cordis.yml b/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/cordis.yml
index 817196414c..9b0a7c7a36 100644
--- a/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/cordis.yml
+++ b/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/cordis.yml
@@ -32,12 +32,22 @@
     # recursion budget, so the local numeric default cannot apply here.
     maxDepth: 'provider-managed'
 
-- id: cli-agent
-  name: '@deepseek-ai/dsh-cli-demo'
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
-    provider: mock
-    model: mock-delegate
+    agents:
+      - id: main
+        provider: mock
+        model: mock-delegate
+        cwd: !!js process.cwd()
     persona: 'Test SDK subagent cwd inheritance.'
-    persistenceRoot: './.sessions'
-    persistenceCompression: 'none'
     workspaceContext: false
+
+- id: persistence
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+    compression: 'none'
+
+- id: checkpoint-policy
+  name: '@deepseek-ai/dsh-session-checkpoint-policy'
diff --git a/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/driver.ts b/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/driver.ts
index 34412c1839..4b52a0f929 100644
--- a/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/driver.ts
+++ b/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/driver.ts
@@ -2,14 +2,14 @@
 /** Test driver: one delegation turn through a headless Loader composition. */
 
 import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-import { runOneShot } from '@deepseek-ai/dsh-cli-demo/src/cli.ts'
+import { runFixtureTurn } from '../../../../../headless-agent/tests/fixtures/one-shot.ts'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('sdk-subagent cwd driver requires a config path')
 
 const ctx = await boot('sdk-subagent-cwd-e2e', resolveConfigPath(configPath, undefined))
 try {
-  await runOneShot(ctx, { task: 'delegate' })
+  await runFixtureTurn(ctx, { task: 'delegate' })
 } finally {
   await ctx.fiber.dispose()
 }
diff --git a/examples/package.json b/examples/package.json
index dea5928576..40628f0255 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -18,7 +18,6 @@
     "@deepseek-ai/dsh-bash-env": "workspace:*",
     "@deepseek-ai/dsh-bash-local": "workspace:*",
     "@deepseek-ai/dsh-bash-sandbox": "workspace:*",
-    "@deepseek-ai/dsh-cli-demo": "workspace:*",
     "@deepseek-ai/dsh-code-runtime-worker": "workspace:*",
     "@deepseek-ai/dsh-command-feedback": "workspace:*",
     "@deepseek-ai/dsh-command-goal": "workspace:*",
diff --git a/knip.json b/knip.json
index 3d7836104f..bce84f9b1c 100644
--- a/knip.json
+++ b/knip.json
@@ -519,16 +519,6 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/examples/cli-demo": {
-      "entry": [
-        "tests/**/*.spec.ts",
-        "tests/**/*.e2e.ts"
-      ],
-      "project": [
-        "src/**/*.ts",
-        "tests/**/*.ts"
-      ]
-    },
     "packages/examples/jsonrpc-demo": {
       "project": [
         "src/**/*.ts"
diff --git a/package.json b/package.json
index 981ce68707..c7f812eb9e 100644
--- a/package.json
+++ b/package.json
@@ -112,7 +112,7 @@
     "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-package-invariants && pnpm run verify-built-package-invariants && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure && pnpm run verify-vendored-links",
     "publish:npm-baseline": "tsx scripts/publish-npm-baseline.ts",
     "dsh": "node --import tsx/esm apps/cli/src/bin.ts",
-    "demo:headless": "node --import tsx packages/examples/cli-demo/src/bin.ts --config examples/headless-agent/cordis.yml",
+    "demo:headless": "node --import tsx/esm apps/cli/src/bin.ts run",
     "demo:code-mode": "node scripts/demo-code-mode.mjs",
     "demo:cordis": "node scripts/demo-cordis.mjs",
     "demo:acp": "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",
diff --git a/packages/examples/README.i18n.yaml b/packages/examples/README.i18n.yaml
index 7b75fa452d..e6a48a3a7d 100644
--- a/packages/examples/README.i18n.yaml
+++ b/packages/examples/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/examples/README.md
-README.md: 64fff8cb3f53386d48a9a831c1cbdd946ad483cc
-README.zh.md: c346a41d297a545991a2441df625286e1b830998
+README.md: 36d1c0d0ddb7a3840af10e6a69ea407d3471c661
+README.zh.md: 9886abe8eedc27a6c62728b93fd63748b2c7dea6
diff --git a/packages/examples/README.md b/packages/examples/README.md
index 64fff8cb3f..36d1c0d0dd 100644
--- a/packages/examples/README.md
+++ b/packages/examples/README.md
@@ -7,11 +7,10 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling
 | Package | npm name | Role |
 |---|---|---|
 | [`agent-spine-demo/`](agent-spine-demo/README.md) | `@deepseek-ai/dsh-agent-spine-demo` | Reusable agent-spine bundle |
-| [`cli-demo/`](cli-demo/README.md) | `@deepseek-ai/dsh-cli-demo` | Headless one-shot application bundle |
 | [`acp-demo/`](acp-demo/README.md) | `@deepseek-ai/dsh-acp-demo` | ACP automation application bundle |
 | [`jsonrpc-demo/`](jsonrpc-demo/README.md) | `@deepseek-ai/dsh-jsonrpc-demo` | External-config JSON-RPC runtime |
 
-`agent-spine-demo` is the shared bundle; `cli-demo` and `acp-demo` add their front doors, while `jsonrpc-demo` boots a deployment-owned plugin tree.
+`agent-spine-demo` is the shared bundle; `acp-demo` adds its automation front door, while `jsonrpc-demo` boots a deployment-owned plugin tree. Product one-shot execution belongs to `dsh run` rather than a package in this directory.
 
 These packages are not product API. Product seams and front doors remain in their owning groups; demo bundles select concrete compositions.
 
diff --git a/packages/examples/README.zh.md b/packages/examples/README.zh.md
index c346a41d29..9886abe8ee 100644
--- a/packages/examples/README.zh.md
+++ b/packages/examples/README.zh.md
@@ -7,11 +7,10 @@
 | 包 | npm 名称 | 角色 |
 |---|---|---|
 | [`agent-spine-demo/`](agent-spine-demo/README.md) | `@deepseek-ai/dsh-agent-spine-demo` | 可复用的 agent 主干组合包 |
-| [`cli-demo/`](cli-demo/README.md) | `@deepseek-ai/dsh-cli-demo` | 无头单次应用组合包 |
 | [`acp-demo/`](acp-demo/README.md) | `@deepseek-ai/dsh-acp-demo` | ACP 自动化应用组合包 |
 | [`jsonrpc-demo/`](jsonrpc-demo/README.md) | `@deepseek-ai/dsh-jsonrpc-demo` | 外部配置 JSON-RPC 运行时 |
 
-`agent-spine-demo` 是共享组合包；`cli-demo` 与 `acp-demo` 添加各自的前端入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。
+`agent-spine-demo` 是共享组合包；`acp-demo` 添加自动化入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。产品单次执行归 `dsh run` 所有，而不再由本目录中的 package 提供。
 
 这些包不是产品 API。产品 seam 与前端入口仍位于各自的归属组；演示组合包只选择具体组合。
 
diff --git a/packages/examples/cli-demo/README.i18n.yaml b/packages/examples/cli-demo/README.i18n.yaml
deleted file mode 100644
index 16eb75ae70..0000000000
--- a/packages/examples/cli-demo/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/examples/cli-demo/README.md
-README.md: 6e46ae81421c23806524b0784a976e9f3c8eeab8
-README.zh.md: b032023fee4bf9d992217cc51731f6356f875daf
diff --git a/packages/examples/cli-demo/README.md b/packages/examples/cli-demo/README.md
deleted file mode 100644
index 6e46ae8142..0000000000
--- a/packages/examples/cli-demo/README.md
+++ /dev/null
@@ -1,78 +0,0 @@
-# @deepseek-ai/dsh-cli-demo
-
-English | [中文](README.zh.md)
-
-Headless one-shot app and bin for running one agent task without an interactive UI or editor client. It composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), JSONL persistence, and exactly one fresh top-level agent. The bin owns one idle-to-idle activity interval, renders its selected output, disposes to quiescence, and exits.
-
-The package mounts no console logger, interactive UI, user-interaction service, or `ask_user_question` tool. Stdout is reserved for the selected output format; diagnostics use stderr.
-
-## Config
-
-| Key | Default | Routed to |
-|---|---|---|
-| `provider` | required | the configured agent's provider route |
-| `model` | required | the configured agent's model |
-| `maxParallelToolCalls` | agent-loop default | positive-integer concurrent tool-call cap; `1` is serial |
-| `persona` | — | the deployment persona in `dsh-system-prompt` |
-| `toolOrder` | lexicographic | explicit model-facing tool order in `dsh-system-prompt` |
-| `tools` | `{ mode: 'native' }` | tool-registry presentation config through `dsh-agent-spine-demo` |
-| `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery |
-| `sessionTitle` | spine example limits | Fallback title word/byte limits through `dsh-agent-spine-demo` |
-| `skills` | owner defaults | skill registry, local provider, and model-facing skill tool |
-| `toolBash` | owner defaults | model-facing bash config, including this producer's background opt-in |
-| `toolTasks` | owner defaults | generic `task_output` wait bounds |
-| `persistenceRoot` | `./.sessions` | JSONL session root |
-| `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
-| `workspaceContext` | required | workspace-instruction byte budget, or `false` to disable loading |
-
-## CLI contract
-
-```sh
-dsh-cli-demo [--config path] [--output-format text|json|stream-json] <task>
-```
-
-`--config` defaults to `./cordis.yml`; `--output-format` defaults to `text`. Exactly one nonblank positional task is required, so quote tasks containing spaces. `--help` prints usage without booting. There is no `-p` or `--print` flag.
-
-The root headless-agent example supplies its leaf:
-
-```sh
-pnpm run demo:headless "inspect the failing test and fix it"
-```
-
-Loader configs resolve bare package specifiers through the optional native helper installed by the repository, so the root command needs no special Node flags.
-
-### Output formats
-
-- `text` writes the last assistant message containing text, followed by one newline.
-- `json` writes one DSH-native result record: `{ type: "result", sessionId, output, usage? }`. `output` is the last committed assistant text in the activity interval. `usage` sums each model step in that interval once, including billed failed attempts that produced usage without a committed assistant message.
-- `stream-json` writes each canonical event from the top-level session's owned activity interval as `{ type: "session_event", sessionId, event }`, then the same result record. Child-agent activity appears only through the parent tool events and results.
-
-Normal idle completion exits successfully without assigning a turn reason to the task. Argument, boot, observation, and persistence failures leave stdout empty. SIGINT and SIGTERM cancel active work, await disposal, and exit 130 and 143 respectively.
-
-The owned activity is explicitly flushed before final output. Session logs remain under `persistenceRoot` after the process exits.
-
-## Operational safety
-
-The headless-agent leaf supplies local bash, filesystem, skill, subagent, workflow, and todo capabilities. A task can therefore mutate the launch workspace, run commands, spawn child agents, and consume provider tokens. Run the CLI from the intended project directory, review the leaf's capability and sandbox configuration, and do not treat non-interactive execution as an approval boundary.
-
-## Model Experience
-
-### One-shot activity
-
-#### What the model sees
-
-The positional task becomes one user message. Through `dsh-agent-spine-demo`, the top-level agent also receives configured workspace instructions and persona, the skill catalog, visible tool schemas, and retained tool results needed for later steps in the owned activity.
-
-#### Token effect
-
-The task, prompt sections, tool schemas, assistant output, and tool results consume tokens on each model step. JSON event streaming and final rendering add no model tokens; delegated child work has its own model usage and is not included in the parent result's `usage` total.
-
-#### KV Cache effect
-
-Tool-round history is append-only while the one-shot agent's prompt, schemas, model route, and session prefix remain fixed. Changing that composition establishes a different request prefix; JSON output mode has no cache effect.
-
-## Known Limitations and Deferred Work
-
-- **One fresh top-level session per process** — its workspace cwd is the launch directory; there is no resume, second prompt, stdin context, or concurrent top-level session in this app.
-- **No interactive question or approval provider** — tools that require a human answer cannot complete unless a different leaf composes a non-interactive provider with explicit policy.
-- **Streaming is top-level-session-only** — child sessions are not flattened into the stream, and aggregate usage covers only model steps recorded on the parent activity interval.
diff --git a/packages/examples/cli-demo/README.zh.md b/packages/examples/cli-demo/README.zh.md
deleted file mode 100644
index b032023fee..0000000000
--- a/packages/examples/cli-demo/README.zh.md
+++ /dev/null
@@ -1,78 +0,0 @@
-# @deepseek-ai/dsh-cli-demo
-
-[English](README.md) | 中文
-
-无头单次应用及 bin，用于在没有交互式 UI 或编辑器客户端的情况下运行一项 agent（智能体）任务。它组合 [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)、JSONL 持久化，以及恰好一个新建顶层 agent。bin 拥有一个从 idle 到 idle 的活动区间，渲染所选输出，执行 dispose（资源释放）直至完全停稳，然后退出。
-
-该包不挂载 console logger、交互式 UI、用户交互服务或 `ask_user_question` 工具。Stdout 专用于所选输出格式；诊断使用 stderr。
-
-## 配置
-
-| 键 | 默认值 | 路由目标 |
-|---|---|---|
-| `provider` | 必填 | 已配置 agent 的提供方路由 |
-| `model` | 必填 | 已配置 agent 的模型 |
-| `maxParallelToolCalls` | agent loop 默认值 | 正整数并发工具调用上限；`1` 表示串行 |
-| `persona` | 无 | `dsh-system-prompt` 中的部署 persona |
-| `toolOrder` | 字典序 | `dsh-system-prompt` 中显式的面向模型工具顺序 |
-| `tools` | `{ mode: 'native' }` | 通过 `dsh-agent-spine-demo` 提供的工具注册表呈现配置 |
-| `dshHome` | `$DSH_HOME` 或 `~/.dsh` | 向模型 bash 公开并用于本地 skill（技能）发现的 harness 主目录 |
-| `sessionTitle` | 主干示例限制 | 通过 `dsh-agent-spine-demo` 提供的后备标题词数／字节限制 |
-| `skills` | 拥有者默认值 | skill 注册表、本地提供方和面向模型的 skill 工具 |
-| `toolBash` | 拥有者默认值 | 面向模型的 bash 配置，包括此生产方对后台任务的显式启用 |
-| `toolTasks` | 拥有者默认值 | 通用 `task_output` 等待边界 |
-| `persistenceRoot` | `./.sessions` | JSONL 会话根目录 |
-| `persistenceCompression` | `'zstd'` | JSONL 产物编码（`'zstd'` 或原始 `'none'`） |
-| `workspaceContext` | 必填 | 工作区指令字节预算，或以 `false` 禁用加载 |
-
-## CLI（命令行界面）契约
-
-```sh
-dsh-cli-demo [--config path] [--output-format text|json|stream-json] <task>
-```
-
-`--config` 默认为 `./cordis.yml`；`--output-format` 默认为 `text`。必须恰好提供一个非空的任务位置参数，因此含空格的任务需要加引号。`--help` 在不启动的情况下打印用法。不存在 `-p` 或 `--print` 标志。
-
-根 headless-agent 示例提供其叶节点：
-
-```sh
-pnpm run demo:headless "inspect the failing test and fix it"
-```
-
-loader 配置通过仓库安装的可选原生辅助程序解析裸包说明符，因此根命令不需要特殊 Node 标志。
-
-### 输出格式
-
-- `text` 写入最后一条含文本的 assistant 消息，后跟一个换行符。
-- `json` 写入一条 DSH 原生结果记录：`{ type: "result", sessionId, output, usage? }`。`output` 是活动区间内最后提交的 assistant 文本。`usage` 对该区间中的每个模型步骤恰好求和一次，包括产生用量但没有提交 assistant 消息的已计费失败尝试。
-- `stream-json` 将顶层会话自有活动区间中的每个规范事件写成 `{ type: "session_event", sessionId, event }`，然后写入同一结果记录。子 agent 活动只通过父工具事件与结果出现。
-
-正常进入 idle 会成功退出，不会为该任务指定轮次原因。参数、启动、观测和持久化失败会让 stdout 保持为空。SIGINT 与 SIGTERM 会取消正在进行的工作，等待 dispose 完成，并分别以 130 和 143 退出。
-
-自有活动会在最终输出前显式刷新。进程退出后，会话日志仍保留在 `persistenceRoot` 下。
-
-## 操作安全
-
-headless-agent 叶节点提供本地 bash、文件系统、skill、subagent、工作流和 todo 能力。因此任务可以修改启动工作区、运行命令、spawn 子 agent，并消耗提供方 token。请从目标项目目录运行 CLI，检查叶节点的能力与沙箱配置，不要把非交互式执行当作批准边界。
-
-## 模型体验
-
-### 单次活动
-
-#### 模型看到的内容
-
-任务位置参数会成为一条用户消息。通过 `dsh-agent-spine-demo`，顶层 agent 还会收到已配置的工作区指令与 persona、skill 目录、可见工具 schema，以及自有活动后续步骤所需的保留工具结果。
-
-#### Token 影响
-
-每个模型步骤中的任务、提示词段、工具 schema、assistant 输出和工具结果都会消耗 token。JSON 事件流式输出和最终渲染不增加模型 token；委派的子工作有自己的模型用量，不计入父结果的 `usage` 总量。
-
-#### KV Cache 影响
-
-只要单次 agent 的提示词、schema、模型路由和会话前缀保持不变，工具轮次历史就仅追加。改变该组合会建立不同的请求前缀；JSON 输出模式不影响缓存。
-
-## 已知限制与暂缓事项
-
-- **每个进程只创建一个新的顶层会话**：其工作区 cwd 是启动目录；此应用不支持恢复、第二条提示词、stdin 上下文或并发顶层会话。
-- **没有交互式问题或批准提供方**：需要人工回答的工具无法完成，除非其他叶节点按显式策略组合一个非交互式提供方。
-- **流式输出仅限顶层会话**：子会话不会平铺到流中，聚合用量只涵盖父活动区间记录的模型步骤。
diff --git a/packages/examples/cli-demo/package.json b/packages/examples/cli-demo/package.json
deleted file mode 100644
index afd129aac9..0000000000
--- a/packages/examples/cli-demo/package.json
+++ /dev/null
@@ -1,68 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-cli-demo",
-  "description": "Headless one-shot agent app with text and DSH-native JSON output",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "bin": {
-    "dsh-cli-demo": "lib/bin.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
-    "./bin": {
-      "types": "./lib/types/bin.d.ts",
-      "default": "./lib/bin.js"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/bin.js",
-    "lib/types/**/*.d.ts"
-  ],
-  "license": "BSD-3-Clause",
-  "peerDependencies": {
-    "@cordisjs/plugin-include": "^1.0.4",
-    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
-    "@deepseek-ai/dsh-agent": "^0.0.1",
-    "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
-    "@deepseek-ai/dsh-app-boot": "^0.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1",
-    "@deepseek-ai/dsh-session": "^0.0.1",
-    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
-    "@deepseek-ai/dsh-tools": "^0.0.1",
-    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
-    "cordis": "^4.0.0-rc.7",
-    "schemastery": "^3.17.0"
-  },
-  "devDependencies": {
-    "@cordisjs/plugin-include": "workspace:^",
-    "@cordisjs/plugin-loader": "workspace:^",
-    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
-    "@deepseek-ai/dsh-app-boot": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-llm": "workspace:^",
-    "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
-    "@deepseek-ai/dsh-system-prompt": "workspace:^",
-    "@deepseek-ai/dsh-tools": "workspace:^",
-    "@deepseek-ai/dsh-workspace-context": "workspace:^",
-    "cordis": "^4.0.0-rc.7",
-    "schemastery": "^3.17.0"
-  }
-}
diff --git a/packages/examples/cli-demo/src/bin.ts b/packages/examples/cli-demo/src/bin.ts
deleted file mode 100644
index 5b6638ef72..0000000000
--- a/packages/examples/cli-demo/src/bin.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-#!/usr/bin/env node
-/**
- * Process wrapper for `dsh-cli-demo`; covered parsing and task execution live in
- * `cli.ts` while this entry owns Unix signal-to-exit-code mapping.
- * @module @deepseek-ai/dsh-cli-demo/bin
- */
-
-import { installFailLoud } from '@deepseek-ai/dsh-app-boot'
-import { executeCli } from './cli.ts'
-
-const NAME = 'dsh-cli-demo'
-
-/* v8 ignore start -- thin self-executing process glue; built-bin tests exercise
-   real argv, signals, Loader boot, output, and exit codes */
-const abort = new AbortController()
-let signalExitCode: number | undefined
-const interrupt = (signal: 'SIGINT' | 'SIGTERM', code: number): void => {
-  signalExitCode ??= code
-  if (!abort.signal.aborted) abort.abort(`received ${signal}`)
-}
-const onSigint = (): void => { interrupt('SIGINT', 130) }
-const onSigterm = (): void => { interrupt('SIGTERM', 143) }
-const uninstallFailLoud = installFailLoud(NAME)
-process.on('SIGINT', onSigint)
-process.on('SIGTERM', onSigterm)
-try {
-  const code = await executeCli(process.argv.slice(2), { signal: abort.signal })
-  process.exitCode = signalExitCode ?? code
-} finally {
-  process.off('SIGINT', onSigint)
-  process.off('SIGTERM', onSigterm)
-  uninstallFailLoud()
-}
-/* v8 ignore stop */
diff --git a/packages/examples/cli-demo/src/cli.ts b/packages/examples/cli-demo/src/cli.ts
deleted file mode 100644
index 68eeadae0a..0000000000
--- a/packages/examples/cli-demo/src/cli.ts
+++ /dev/null
@@ -1,406 +0,0 @@
-/**
- * Command parser and one-turn driver for `dsh-cli-demo`. The executable wrapper
- * owns process signals; this module owns output, durability, and cleanup.
- * @module @deepseek-ai/dsh-cli-demo/cli
- */
-
-import { parseArgs } from 'node:util'
-import type { Context } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import { createUserMessage, type TokenUsage } from '@deepseek-ai/dsh-llm'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { boot, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-
-const CLI_NAME = 'dsh-cli-demo'
-const DEFAULT_CONFIG_PATH = './cordis.yml'
-const OUTPUT_FORMATS = ['text', 'json', 'stream-json'] as const
-const USAGE = `Usage: ${CLI_NAME} [--config path] [--output-format text|json|stream-json] (-p <task> | <task>)\n`
-
-/** Supported CLI output encodings. */
-export type OutputFormat = typeof OUTPUT_FORMATS[number]
-
-/** Parsed command: help exits before boot; run carries one validated task. */
-export type CliCommand =
-  | { readonly kind: 'help' }
-  | {
-    readonly kind: 'run'
-    readonly configPath: string
-    readonly outputFormat: OutputFormat
-    readonly task: string
-  }
-
-/** DSH-native final record emitted by JSON modes. */
-export interface CliResult {
-  readonly type: 'result'
-  readonly sessionId: string
-  readonly output: string
-  readonly usage?: TokenUsage
-}
-
-/** Options for one turn against the configured top-level agent. */
-export interface OneShotOptions {
-  /** Exactly one nonblank user task. */
-  readonly task: string
-  /** Optional signal that cancels the selected agent. */
-  readonly signal?: AbortSignal
-  /** Synchronous task-turn observer; a throw cancels the agent and fails the run after flush. */
-  readonly onEvent?: (sessionId: string, event: SessionEvent) => void
-}
-
-/** Injectable process boundaries used by {@link executeCli}. */
-export interface CliRuntime {
-  /** Process cwd for config resolution and `.env` loading. */
-  readonly cwd?: string
-  /** Cancellation signal, normally aborted by SIGINT or SIGTERM. */
-  readonly signal?: AbortSignal
-  /** Loader boot boundary. */
-  readonly boot?: (name: string, absoluteConfigPath: string) => Promise<Context>
-  /** Optional `.env` loader boundary. */
-  readonly loadEnv?: (name: string, dir: string, warn: (line: string) => void) => void
-  /** Stdout sink; throws are treated as output failures. */
-  readonly writeStdout?: (chunk: string) => unknown
-  /** Stderr diagnostic sink. */
-  readonly writeStderr?: (chunk: string) => unknown
-  /** Context disposal boundary. */
-  readonly dispose?: (ctx: Context) => Promise<void>
-}
-
-interface ParsedArguments {
-  readonly values: {
-    readonly config?: string
-    readonly 'output-format'?: string
-    readonly help?: boolean
-    readonly prompt?: string
-  }
-  readonly positionals: string[]
-}
-
-class CliArgumentError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'CliArgumentError'
-  }
-}
-
-class CliInterruptedError extends Error {
-  constructor(reason: string) {
-    super(reason)
-    this.name = 'CliInterruptedError'
-  }
-}
-
-/** Render an arbitrary value without trusting its type traps or string coercion. */
-function renderUnknown(value: unknown): string {
-  try {
-    return String(value)
-  } catch {
-    return '[unrenderable thrown value]'
-  }
-}
-
-/** Normalize an arbitrary thrown value without letting inspection escape containment. */
-function toError(error: unknown): Error {
-  try {
-    if (error instanceof Error) return error
-  } catch {
-    // A hostile proxy may throw during instanceof; use the total renderer below.
-  }
-  return new Error(renderUnknown(error))
-}
-
-function interruptionReason(signal: AbortSignal): string {
-  return signal.reason === undefined ? 'interrupted' : renderUnknown(signal.reason)
-}
-
-/**
- * Parse the bin arguments and enforce the one-positional-task contract.
- * @param args - arguments after the executable name.
- * @returns a help or run command.
- * @throws {@link CliArgumentError} for unknown flags, invalid formats, or task cardinality.
- */
-export function parseCliArgs(args: readonly string[]): CliCommand {
-  let parsed: ParsedArguments
-  try {
-    parsed = parseArgs({
-      args: [...args],
-      options: {
-        config: { type: 'string' },
-        'output-format': { type: 'string' },
-        help: { type: 'boolean' },
-        prompt: { type: 'string', short: 'p' },
-      },
-      allowPositionals: true,
-      strict: true,
-    })
-  } catch (error: unknown) {
-    throw new CliArgumentError(toError(error).message)
-  }
-
-  if (parsed.values.help === true) return { kind: 'help' }
-  const prompt = parsed.values.prompt
-  if (prompt !== undefined && parsed.positionals.length > 0) {
-    throw new CliArgumentError('-p/--prompt and a positional task are mutually exclusive')
-  }
-  if (prompt === undefined && parsed.positionals.length !== 1) {
-    throw new CliArgumentError(`expected exactly one positional task or -p, received ${parsed.positionals.length} positional(s)`)
-  }
-  // Cardinality was checked above, so the fallback index zero exists.
-  // oxlint-disable-next-line typescript/no-non-null-assertion
-  const task = prompt ?? parsed.positionals[0]!
-  if (task.trim().length === 0) throw new CliArgumentError('task must not be blank')
-
-  const requestedFormat = parsed.values['output-format'] ?? 'text'
-  if (!OUTPUT_FORMATS.some(format => format === requestedFormat)) {
-    throw new CliArgumentError(`unsupported output format ${JSON.stringify(requestedFormat)}`)
-  }
-  return {
-    kind: 'run',
-    configPath: parsed.values.config ?? DEFAULT_CONFIG_PATH,
-    outputFormat: requestedFormat as OutputFormat,
-    task,
-  }
-}
-
-function addUsage(total: TokenUsage | undefined, step: TokenUsage): TokenUsage {
-  const next: TokenUsage = {
-    inputTokens: (total?.inputTokens ?? 0) + step.inputTokens,
-    outputTokens: (total?.outputTokens ?? 0) + step.outputTokens,
-  }
-  for (const key of ['cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens'] as const) {
-    if (total?.[key] !== undefined || step[key] !== undefined) next[key] = (total?.[key] ?? 0) + (step[key] ?? 0)
-  }
-  return next
-}
-
-function assistantText(event: Extract<SessionEvent, { type: 'assistant/message' }>): string | undefined {
-  const blocks = event.data.message.content.filter(block => block.type === 'text')
-  return blocks.length === 0 ? undefined : blocks.map(block => block.text).join('')
-}
-
-/** Wait for startup quiescence while making pre-run cancellation terminal. */
-async function waitForStartupIdle(agent: Agent, signal?: AbortSignal): Promise<void> {
-  if (signal === undefined) {
-    await agent.whenIdle()
-    return
-  }
-  if (signal.aborted) {
-    agent.cancel({ kind: 'user' })
-    throw new CliInterruptedError(interruptionReason(signal))
-  }
-  await new Promise<void>((resolve, reject) => {
-    const onAbort = (): void => {
-      agent.cancel({ kind: 'user' })
-      reject(new CliInterruptedError(interruptionReason(signal)))
-    }
-    signal.addEventListener('abort', onAbort, { once: true })
-    void agent.whenIdle().then(resolve, reject).finally(() => {
-      signal.removeEventListener('abort', onAbort)
-    })
-  })
-}
-
-/**
- * Run one owned activity interval on the configured top-level agent, from the
- * task's durable enqueue receipt through whole-agent idle.
- * @param ctx - settled Loader root containing one agent plus `ctx.sessions`.
- * @param options - task, optional cancellation, and optional stream observer.
- * @returns the DSH-native result envelope after durable quiescence.
- */
-export async function runOneShot(ctx: Context, options: OneShotOptions): Promise<CliResult> {
-  const agents = ctx.get('agents')?.roots() ?? []
-  const [agent] = agents
-  if (agent === undefined || agents.length !== 1) {
-    throw new Error(`config must create exactly one top-level agent, found ${agents.length}`)
-  }
-  await waitForStartupIdle(agent, options.signal)
-
-  const message = createUserMessage({ content: [{ type: 'text', text: options.task }], source: { kind: 'user' } })
-  let received = false
-  let output = ''
-  const usageByStep = new Map<string, TokenUsage>()
-  let outputError: Error | undefined
-  let interrupted: CliInterruptedError | undefined
-  const observe = (sessionId: string, event: SessionEvent): void => {
-    if (outputError !== undefined || options.onEvent === undefined) return
-    try {
-      options.onEvent(sessionId, event)
-    } catch (error: unknown) {
-      outputError = toError(error)
-      queueMicrotask(() => {
-        agent.cancel({ kind: 'user' })
-      })
-    }
-  }
-
-  const disposeListener = ctx.on('session/event', (session, event) => {
-    if (session !== agent.session) return
-    if (!received) {
-      if (event.type !== 'agent/inbox/spliced'
-        || !event.data.inserted.some(inserted => inserted.id === message.id)) return
-      received = true
-    }
-    observe(session.id, event)
-    if (event.type === 'assistant/chunk' && event.data.chunk.type === 'usage') {
-      usageByStep.set(`${event.data.turn}/${event.data.step}`, event.data.chunk.usage)
-    }
-    if (event.type === 'assistant/message') {
-      output = assistantText(event) ?? output
-      if (event.data.usage !== undefined) {
-        usageByStep.set(`${event.data.turn}/${event.data.step}`, event.data.usage)
-      }
-    }
-  })
-
-  const signal = options.signal
-  let onAbort: (() => void) | undefined
-  if (signal !== undefined) {
-    onAbort = (): void => {
-      interrupted ??= new CliInterruptedError(interruptionReason(signal))
-      agent.cancel({ kind: 'user' })
-    }
-    signal.addEventListener('abort', onAbort, { once: true })
-    /* v8 ignore next -- closes the race between startup-idle completion and listener registration */
-    if (signal.aborted) onAbort()
-  }
-
-  try {
-    if (interrupted === undefined) agent.followup(message)
-    await agent.whenIdle()
-  } finally {
-    if (onAbort !== undefined) signal?.removeEventListener('abort', onAbort)
-    disposeListener()
-  }
-
-  await ctx.sessions.flush(agent.session)
-  if (outputError !== undefined) throw outputError
-  if (interrupted !== undefined) throw interrupted
-  const usage = [...usageByStep.values()].reduce<TokenUsage | undefined>(addUsage, undefined)
-  return {
-    type: 'result',
-    sessionId: agent.session.id,
-    output,
-    ...usage === undefined ? {} : { usage },
-  }
-}
-
-function renderResult(outputFormat: OutputFormat, result: CliResult): string {
-  return outputFormat === 'text' ? `${result.output}\n` : `${JSON.stringify(result)}\n`
-}
-
-/**
- * Race Loader boot with cancellation without abandoning a context that becomes
- * available after the caller has been released. Waiting for that late context
- * would recreate the signal hang, so its disposal and diagnostics run detached.
- */
-async function bootInterruptibly(
-  start: () => Promise<Context>,
-  signal: AbortSignal | undefined,
-  disposeLateContext: (ctx: Context) => Promise<void>,
-  reportLateDisposalFailure: (error: unknown) => void,
-): Promise<Context> {
-  if (signal === undefined) return await start()
-  if (signal.aborted) throw new CliInterruptedError(interruptionReason(signal))
-
-  let onAbort!: () => void
-  const interruptedBoot = new Promise<never>((_resolve, reject) => {
-    onAbort = (): void => {
-      reject(new CliInterruptedError(interruptionReason(signal)))
-    }
-    signal.addEventListener('abort', onAbort, { once: true })
-    /* v8 ignore next -- closes registration against a non-standard synchronously mutating signal */
-    if (signal.aborted) onAbort()
-  })
-  const booting = Promise.resolve().then(start)
-  try {
-    return await Promise.race([booting, interruptedBoot])
-  } catch (error: unknown) {
-    // The awaited race permits the signal to change after the preflight check.
-    // oxlint-disable-next-line typescript/no-unnecessary-condition
-    if (signal.aborted) {
-      void booting.then(
-        async (lateContext) => {
-          try {
-            await disposeLateContext(lateContext)
-          } catch (error: unknown) {
-            reportLateDisposalFailure(error)
-          }
-        },
-        () => {},
-      )
-    }
-    throw error
-  } finally {
-    signal.removeEventListener('abort', onAbort)
-  }
-}
-
-/**
- * Execute one CLI invocation. Argument and boot failures never write stdout;
- * context disposal is awaited before return, and its failure does not replace
- * an earlier diagnostic.
- * @param args - arguments after the executable name.
- * @param runtime - optional injected process boundaries for tests and embedding.
- * @returns the ordinary process exit code; the thin bin overrides it for Unix signals.
- */
-export async function executeCli(args: readonly string[], runtime: CliRuntime = {}): Promise<number> {
-  /* v8 ignore next -- default process sinks are exercised by the built-bin smoke */
-  const writeStdout = runtime.writeStdout ?? (chunk => process.stdout.write(chunk))
-  /* v8 ignore next -- default process sinks are exercised by the built-bin smoke */
-  const writeStderr = runtime.writeStderr ?? (chunk => process.stderr.write(chunk))
-  let command: CliCommand
-  try {
-    command = parseCliArgs(args)
-  } catch (error: unknown) {
-    writeStderr(`${CLI_NAME}: ${toError(error).message}\n${USAGE}`)
-    return 1
-  }
-  if (command.kind === 'help') {
-    writeStdout(USAGE)
-    return 0
-  }
-
-  /* v8 ignore next -- default process cwd is exercised by the built-bin smoke */
-  const cwd = runtime.cwd ?? process.cwd()
-  /* v8 ignore next -- default env/boot boundaries are exercised by the Loader and built-bin smokes */
-  const loadEnvironment = runtime.loadEnv ?? loadEnv
-  /* v8 ignore next -- default env/boot boundaries are exercised by the Loader and built-bin smokes */
-  const bootContext = runtime.boot ?? boot
-  /* v8 ignore next -- default disposal is exercised by the built-bin smoke */
-  const disposeContext = runtime.dispose ?? (target => target.fiber.dispose())
-  let ctx: Context | undefined
-  let exitCode = 1
-  let diagnostic: string | undefined
-  try {
-    loadEnvironment(CLI_NAME, cwd, line => writeStderr(line))
-    ctx = await bootInterruptibly(
-      () => bootContext(CLI_NAME, resolveConfigPath(command.configPath, undefined, cwd)),
-      runtime.signal,
-      disposeContext,
-      error => writeStderr(`${CLI_NAME}: dispose after interrupted boot failed: ${toError(error).message}\n`),
-    )
-    const result = await runOneShot(ctx, {
-      task: command.task,
-      ...runtime.signal === undefined ? {} : { signal: runtime.signal },
-      ...command.outputFormat === 'stream-json'
-        ? { onEvent: (sessionId: string, event: SessionEvent) => {
-          writeStdout(`${JSON.stringify({ type: 'session_event', sessionId, event })}\n`)
-        } }
-        : {},
-    })
-    writeStdout(renderResult(command.outputFormat, result))
-    exitCode = 0
-  } catch (error: unknown) {
-    diagnostic = `${CLI_NAME}: ${toError(error).message}\n`
-  } finally {
-    if (ctx !== undefined) {
-      try {
-        await disposeContext(ctx)
-      } catch (error: unknown) {
-        diagnostic = `${diagnostic ?? ''}${CLI_NAME}: dispose failed: ${toError(error).message}\n`
-        exitCode = 1
-      }
-    }
-  }
-  if (diagnostic !== undefined) writeStderr(diagnostic)
-  return exitCode
-}
diff --git a/packages/examples/cli-demo/src/index.ts b/packages/examples/cli-demo/src/index.ts
deleted file mode 100644
index bfec7c9a4f..0000000000
--- a/packages/examples/cli-demo/src/index.ts
+++ /dev/null
@@ -1,96 +0,0 @@
-/**
- * Headless one-shot app composition: the default agent spine, JSONL session
- * persistence, and one fresh top-level agent. The CLI driver owns task
- * submission and output; the app deliberately mounts no interactive or logging
- * front door so stdout remains protocol-pure.
- * @module @deepseek-ai/dsh-cli-demo
- */
-
-import type { Context } from 'cordis'
-import z from 'schemastery'
-import { SessionId } from '@deepseek-ai/dsh-session'
-import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
-import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
-import SessionPersistenceJsonl, {
-  JsonlCompressionSchema,
-  type JsonlCompression,
-} from '@deepseek-ai/dsh-session-persistence-jsonl'
-import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
-import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
-
-const DEFAULT_PERSISTENCE_ROOT = './.sessions'
-
-export const name = 'cli-demo'
-
-/** App config forwarded to the spine, configured agent, and JSONL backend. */
-export interface Config {
-  /** Provider route for the configured agent. */
-  provider: string
-  /** Model name for the configured agent; a matching adapter must be registered. */
-  model: string
-  /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */
-  maxParallelToolCalls?: number
-  /** Deployment persona forwarded to the system-prompt plugin. */
-  persona?: string
-  /** Explicit model-facing tool order forwarded to the system-prompt plugin. */
-  toolOrder?: string[]
-  /** Tool-registry presentation config forwarded through agent-spine-demo. */
-  tools?: ToolsConfig
-  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
-  dshHome?: string
-  /** Fallback session-title limits forwarded through agent-spine-demo. */
-  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
-  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
-  persistenceRoot?: string
-  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
-  persistenceCompression?: JsonlCompression
-  /** Skill registry, local-provider, and model-facing consumer config. */
-  skills?: agentCore.SkillConfig
-  /** Model-facing bash tool config forwarded through agent-spine-demo. */
-  toolBash?: NonNullable<agentCore.Config['toolBash']>
-  /** Generic background-task control-tool config forwarded through agent-spine-demo. */
-  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
-  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
-  workspaceContext: agentCore.Config['workspaceContext']
-}
-
-// Each front door keeps a complete Loader schema so its deployment contract is
-// readable without a cross-package config facade.
-/* jscpd:ignore-start */
-export const Config: z<Config> = z.object({
-  provider: z.string().required(),
-  model: z.string().required(),
-  maxParallelToolCalls: z.number().step(1).min(1),
-  persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
-  persistenceCompression: JsonlCompressionSchema,
-  persona: z.string(),
-  dshHome: z.string(),
-  sessionTitle: agentCore.SessionTitleConfigSchema,
-  skills: agentCore.SkillConfigSchema,
-  // Absent means lexicographic order; schemastery's native array default is [].
-  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
-  tools: ToolRegistry.Config,
-  toolBash: agentCore.ToolBashConfigSchema,
-  toolTasks: z.union([z.const(false), agentCore.ToolTasksConfigSchema]),
-  workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
-})
-/* jscpd:ignore-end */
-
-/**
- * Compose the UI-less spine, a fresh top-level agent rooted at the process cwd,
- * and JSONL persistence. Swappable adapters, executors, and product tools stay
- * in the leaf `cordis.yml`.
- * @param ctx - app context that owns the composed child plugins.
- * @param config - validated app configuration.
- */
-export function apply(ctx: Context, config: Config): void {
-  ctx.plugin(agentCore, {
-    ...agentCore.pickSpineConfig(config),
-    agents: [{ id: SessionId('main'), provider: config.provider, model: config.model, cwd: process.cwd() }],
-  })
-  ctx.plugin(SessionPersistenceJsonl, {
-    root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
-    ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
-  })
-  ctx.plugin(sessionCheckpointPolicy)
-}
diff --git a/packages/examples/cli-demo/src/invariant.ts b/packages/examples/cli-demo/src/invariant.ts
deleted file mode 100644
index 8eb40e9268..0000000000
--- a/packages/examples/cli-demo/src/invariant.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-/**
- * Package-owned invariant companion for `@deepseek-ai/dsh-cli-demo`.
- * @module @deepseek-ai/dsh-cli-demo/invariant
- */
-
-/* jscpd:ignore-start */
-import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-cli-demo'
-
-/** Cordis companion plugin name. */
-export const name = 'cli-demo-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/**
- * No runtime invariant: this composition package owns no independent event stream or mutable data;
- * Loader and built-entry tests cover its wiring.
- */
-const install: InvariantInstaller = () => {}
-
-/**
- * Register this package's invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export const apply = (ctx: Context): Promise<() => void> =>
-  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-/* jscpd:ignore-end */
diff --git a/packages/examples/cli-demo/tests/built-bin.e2e.ts b/packages/examples/cli-demo/tests/built-bin.e2e.ts
deleted file mode 100644
index c58d2657fb..0000000000
--- a/packages/examples/cli-demo/tests/built-bin.e2e.ts
+++ /dev/null
@@ -1,223 +0,0 @@
-import { existsSync } from 'node:fs'
-import { mkdtemp, mkdir, readFile, readdir, rm, symlink, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-import { promisify } from 'node:util'
-import { fileURLToPath } from 'node:url'
-import { zstdDecompress } from 'node:zlib'
-import { execa } from 'execa'
-import { afterEach, describe, expect, it } from 'vitest'
-
-/**
- * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer.
- * The consumer's mock model is an example-local TypeScript plugin (Node 22.19+ — the engines
- * floor — strips types natively, so plain `node` loads it), its config carries a `disabled:
- * true` unresolvable entry (the fail-loud entry-load guard must not mistake an intentionally
- * fiber-less entry for a failed import), and the optional spill pair loads from the consumer
- * install — so every passing boot proves all three alongside the CLI's own output contract.
- */
-
-const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const cliBin = join(repoRoot, 'packages/examples/cli-demo/lib/bin.js')
-const decompress = promisify(zstdDecompress)
-const dshPackages = [
-  'examples/agent-spine-demo', 'examples/cli-demo', 'core/agent', 'core/session',
-  'core/system-prompt', 'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash',
-  'bash/bash-local', 'bash/tool-bash', 'subprocess/subprocess', 'subprocess/subprocess-local', 'support/invariants', 'ui/app-boot',
-  'session-persistence/session-persistence', 'session-persistence/session-checkpoint-policy',
-  'session-persistence/session-persistence-jsonl',
-  'context/workspace-context',
-  'spill/spill', 'spill/spill-local', 'spill/spill-policy', 'util/retention',
-]
-const vendorPackages = ['cordis', 'loader', 'include', 'timer', 'schemastery', 'cosmokit']
-
-async function packageName(dir: string): Promise<string> {
-  return (JSON.parse(await readFile(join(dir, 'package.json'), 'utf8')) as { name: string }).name
-}
-
-async function linkPackage(dir: string, nodeModules: string): Promise<void> {
-  const target = join(nodeModules, await packageName(dir))
-  await mkdir(dirname(target), { recursive: true })
-  await symlink(dir, target)
-}
-
-async function makeConsumer(): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), 'cli-built-bin-'))
-  const nodeModules = join(dir, 'node_modules')
-  for (const rel of dshPackages) await linkPackage(join(repoRoot, 'packages', rel), nodeModules)
-  for (const rel of vendorPackages) await linkPackage(join(repoRoot, 'vendor', rel), nodeModules)
-  await writeFile(join(dir, 'mock-llm.ts'), [
-    // Real type annotations: this file exists to prove plain Node's type
-    // stripping loads an example-local TS plugin from a built consumer.
-    "import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'",
-    "import type { Context } from 'cordis'",
-    'class Mock extends LlmAdapter {',
-    '  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {',
-    "    const text: string = options.messages.flatMap(message => message.content).filter(block => block.type === 'text').at(-1)?.text ?? ''",
-    "    yield { type: 'block-start', index: 0, blockType: 'text' }",
-    "    if (text === 'hang') {",
-    "      yield { type: 'text-delta', index: 0, text: 'partial' }",
-    '      await new Promise<never>((resolve, reject) => {',
-    "        const timer = setTimeout(() => reject(new Error('hang timeout')), 30000)",
-    "        const onAbort = () => { clearTimeout(timer); reject(new Error('aborted')) }",
-    '        if (options.signal.aborted) onAbort()',
-    "        else options.signal.addEventListener('abort', onAbort, { once: true })",
-    '      })',
-    '      return',
-    '    }',
-    '    const reply = `BUILT: ${text}`',
-    "    yield { type: 'text-delta', index: 0, text: reply }",
-    "    yield { type: 'block-end', index: 0, block: { type: 'text', text: reply } }",
-    "    yield { type: 'usage', usage: { inputTokens: 4, outputTokens: 2 } }",
-    "    yield { type: 'finish', reason: { kind: 'stop' } }",
-    '  }',
-    '}',
-    "export const name = 'built-cli-mock'",
-    "export const inject = ['llm']",
-    "export function apply(ctx: Context) { ctx.llm.registerAdapter(['built-cli-mock'], new Mock()) }",
-    '',
-  ].join('\n'))
-  await writeFile(join(dir, 'cordis.yml'), [
-    '- id: mock-llm',
-    "  name: './mock-llm.ts'",
-    '- id: subprocess',
-    "  name: '@deepseek-ai/dsh-subprocess-local'",
-    '- id: bash',
-    "  name: '@deepseek-ai/dsh-bash-local'",
-    '- id: cli-agent',
-    "  name: '@deepseek-ai/dsh-cli-demo'",
-    '  config:',
-    '    provider: built-cli-mock',
-    '    model: built-cli-mock',
-    "    persona: 'built CLI test'",
-    "    persistenceRoot: './.sessions'",
-    '    workspaceContext: false',
-    '- id: spill-local',
-    "  name: '@deepseek-ai/dsh-spill-local'",
-    '- id: spill-policy',
-    "  name: '@deepseek-ai/dsh-spill-policy'",
-    '  config:',
-    '    maxInlineBytes: 50000',
-    // A `disabled: true` entry settles without a fiber by design; the fail-loud
-    // entry-load guard must not mistake it for a failed import. The nonexistent
-    // path makes that distinction observable while a clean run proves boot continued.
-    '- id: off',
-    "  name: './does-not-exist.ts'",
-    '  disabled: true',
-    '',
-  ].join('\n'))
-  return dir
-}
-
-interface BinResult {
-  readonly code: number
-  readonly signal: NodeJS.Signals | null
-  readonly stdout: string
-  readonly stderr: string
-}
-
-async function runBuiltBin(cwd: string, args: readonly string[], interrupt?: NodeJS.Signals): Promise<BinResult> {
-  const subprocess = execa(process.execPath, [cliBin, ...args], {
-    cwd,
-    env: { DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
-    stdin: 'ignore',
-    timeout: 25_000,
-    killSignal: 'SIGKILL',
-    reject: false,
-    stripFinalNewline: false,
-  })
-  // Genuinely custom mid-stream logic: the signal cases deliver `interrupt`
-  // once the first streamed chunk proves the turn is in flight.
-  if (interrupt !== undefined) {
-    let streamed = ''
-    let interrupted = false
-    subprocess.stdout.on('data', (chunk: Buffer) => {
-      streamed += chunk.toString('utf8')
-      if (!interrupted && streamed.includes('assistant/chunk')) {
-        interrupted = true
-        subprocess.kill(interrupt)
-      }
-    })
-  }
-  const result = await subprocess
-  if (result.timedOut) {
-    throw new Error(`built CLI did not exit. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
-  }
-  return { code: result.exitCode ?? -1, signal: result.signal ?? null, stdout: result.stdout, stderr: result.stderr }
-}
-
-let consumer: string | undefined
-
-afterEach(async () => {
-  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
-  consumer = undefined
-})
-
-describe.skipIf(!existsSync(cliBin))('dsh-cli-demo BUILT bin', () => {
-  it('runs text, json, and stream-json under plain Node and persists fresh sessions', async () => {
-    consumer = await makeConsumer()
-    const text = await runBuiltBin(consumer, ['--config', './cordis.yml', 'hello'])
-    expect(text).toMatchObject({ code: 0, signal: null, stdout: 'BUILT: hello\n', stderr: '' })
-
-    const json = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'json', 'json task'])
-    expect(JSON.parse(json.stdout)).toMatchObject({
-      type: 'result', output: 'BUILT: json task',
-      usage: { inputTokens: 4, outputTokens: 2 },
-    })
-
-    const stream = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'stream-json', 'stream task'])
-    const lines = stream.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
-    expect(lines[0]).toMatchObject({
-      type: 'session_event',
-      event: {
-        type: 'agent/inbox/spliced',
-        data: {
-          target: 'next-turn',
-          start: 0,
-          inserted: [{ content: [{ type: 'text', text: 'stream task' }], source: { kind: 'user' } }],
-        },
-      },
-    })
-    expect(lines.findIndex(line =>
-      (line['event'] as { type?: string } | undefined)?.type === 'turn/start')).toBeGreaterThan(0)
-    expect(lines.at(-1)).toMatchObject({ type: 'result', output: 'BUILT: stream task' })
-    const sessionsRoot = join(consumer, '.sessions')
-    const files = await readdir(sessionsRoot, { recursive: true })
-    const logs = files.filter(file => file.endsWith('.jsonl.zstd'))
-    expect(logs).toHaveLength(3)
-    const compressed = await readFile(join(sessionsRoot, logs[0]!))
-    expect(compressed.subarray(0, 4).toString('hex')).toBe('28b52ffd')
-    expect(JSON.parse((await decompress(compressed)).toString())).toMatchObject({ type: 'session' })
-  }, 30_000)
-
-  it('keeps stdout empty for invalid argv and missing config', async () => {
-    consumer = await makeConsumer()
-    for (const args of [
-      ['--config', './cordis.yml'],
-      ['--config', './cordis.yml', 'one', 'two'],
-      ['--config', './missing.yml', 'task'],
-    ]) {
-      const result = await runBuiltBin(consumer, args)
-      expect(result.code).not.toBe(0)
-      expect(result.stdout).toBe('')
-      expect(result.stderr.length).toBeGreaterThan(0)
-    }
-  }, 30_000)
-
-  describe.skipIf(process.platform === 'win32')('POSIX signal delivery', () => {
-    it.each([
-      ['SIGINT', 130],
-      ['SIGTERM', 143],
-    ] as const)('cancels and disposes on %s with exit %i', async (signal, code) => {
-      consumer = await makeConsumer()
-      const result = await runBuiltBin(
-        consumer,
-        ['--config', './cordis.yml', '--output-format', 'stream-json', 'hang'],
-        signal,
-      )
-      expect(result, JSON.stringify(result)).toMatchObject({ code, signal: null })
-      expect(result.stdout).toContain('"kind":"aborted"')
-      expect(result.stderr).toBe(`dsh-cli-demo: received ${signal}\n`)
-    }, 30_000)
-  })
-})
diff --git a/packages/examples/cli-demo/tests/cli-demo.spec.ts b/packages/examples/cli-demo/tests/cli-demo.spec.ts
deleted file mode 100644
index 574e18c583..0000000000
--- a/packages/examples/cli-demo/tests/cli-demo.spec.ts
+++ /dev/null
@@ -1,202 +0,0 @@
-import { mkdtemp } from 'node:fs/promises'
-import { randomUUID } from 'node:crypto'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-import { agentEvents } from '@deepseek-ai/dsh-agent'
-import { SessionId } from '@deepseek-ai/dsh-session'
-import { CallId, type Message } from '@deepseek-ai/dsh-llm'
-import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
-import type { ToolExecution } from '@deepseek-ai/dsh-tools'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import * as cliDemo from '../src/index.ts'
-
-const testToolSignal = new AbortController().signal
-
-const contexts: Context[] = []
-
-async function skillConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<cliDemo.Config['skills']>> {
-  const home = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-skills-'))
-  return {
-    local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') },
-    ...catalogDescriptionMaxLength === undefined ? {} : { tool: { catalogDescriptionMaxLength } },
-  }
-}
-
-async function mount(config: cliDemo.Config, withBash = false): Promise<Context> {
-  const ctx = new Context()
-  if (withBash) {
-    ctx.provide('bash', {
-      sandboxMode: undefined,
-      resolve() { throw new Error('composition test does not execute bash') },
-      run() { throw new Error('composition test does not execute bash') },
-      start() { throw new Error('composition test does not execute bash') },
-    })
-  }
-  contexts.push(ctx)
-  config.persistenceRoot ??= await mkdtemp(join(tmpdir(), 'dsh-cli-demo-persistence-'))
-  await ctx.plugin(cliDemo, config)
-  await new Promise(resolve => setTimeout(resolve, 80))
-  return ctx
-}
-
-async function composePrefix(ctx: Context): Promise<Message[]> {
-  const agent = ctx.agentLoop.create(SessionId(`cli-demo-prefix-${randomUUID()}`), {}, { cwd: '/tmp' })
-  const signal = new AbortController().signal
-  const decision = await agentEvents(ctx, agent).waterfall(
-    'agent/pre-step', { messages: [], turn: 1, step: 1, signal },
-    () => Promise.resolve({ kind: 'enter', messages: [] }),
-  )
-  if (decision.kind === 'enter') {
-    for (const message of decision.messages) {
-      agent.session.append('user/message', message, { surfaceOp: 'append' })
-    }
-  }
-  return agent.session.deriveMessages()
-}
-
-afterEach(async () => {
-  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
-})
-
-describe('dsh-cli-demo app composition', () => {
-  it('composes the UI-less spine, JSONL persistence, and a main agent', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-compose-'))
-    const ctx = await mount({
-      provider: 'mock',
-      model: 'mock',
-      persona: 'Headless.',
-      tools: { mode: 'native' },
-      persistenceRoot: root,
-      persistenceCompression: 'none',
-      skills: await skillConfig(),
-      workspaceContext: false,
-    })
-    const [agent] = ctx.get('agents')?.roots() ?? []
-    expect(ctx.get('agentLoop')).toBeDefined()
-    expect(ctx.get('sessionPersistence')).toBeDefined()
-    expect((ctx.get('sessionPersistence') as unknown as { config: { compression?: string } }).config.compression).toBe('none')
-    expect(agent?.session.header.cwd).toBe(process.cwd())
-    expect(ctx.get('userInteraction')).toBeUndefined()
-    expect(ctx.get('tools')?.get('ask_user_question')).toBeUndefined()
-  })
-
-  it('covers direct-apply defaults and forwards skill and tool-order config', async () => {
-    const oldDshHome = process.env.DSH_HOME
-    const oldAgentsHome = process.env.DSH_AGENTS_HOME
-    const home = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-defaults-'))
-    process.env.DSH_HOME = join(home, '.dsh')
-    process.env.DSH_AGENTS_HOME = join(home, '.agents')
-    try {
-      const ctx = new Context()
-      contexts.push(ctx)
-      cliDemo.apply(ctx, { provider: 'mock', model: 'mock', workspaceContext: false })
-      await new Promise(resolve => setTimeout(resolve, 80))
-      expect(ctx.get('sessionPersistence')).toBeDefined()
-      const [agent] = ctx.get('agents')?.roots() ?? []
-      expect(agent?.session.id).toMatch(/^main-session-/)
-      expect(await ctx.skills.list()).toEqual([])
-    } finally {
-      if (oldDshHome === undefined) delete process.env.DSH_HOME
-      else process.env.DSH_HOME = oldDshHome
-      if (oldAgentsHome === undefined) delete process.env.DSH_AGENTS_HOME
-      else process.env.DSH_AGENTS_HOME = oldAgentsHome
-    }
-
-    const ctx = await mount({
-      provider: 'mock',
-      model: 'mock',
-      toolOrder: ['zulu', TOOL_ORDER_REST],
-      skills: await skillConfig(6),
-      workspaceContext: false,
-    })
-    ctx.skills.register({ name: 'cli-skill', description: 'CLI skill', source: 'runtime', content: 'body' })
-    for (const name of ['alpha', 'zulu']) {
-      ctx.tools.register({
-        name,
-        description: name,
-        parameters: {},
-        output: { schema: { type: 'null' }, render: () => [] },
-        execute: async () => null,
-      })
-    }
-    expect(JSON.stringify(await composePrefix(ctx))).toContain('- `cli-skill`: CLI...')
-    expect((await ctx.systemPrompt.assemble()).tools.map(tool => tool.name)).toEqual([
-      'zulu',
-      'alpha',
-      'skill',
-      'task_kill',
-      'task_list',
-      'task_output',
-    ])
-  })
-
-  it('forwards the complete shared spine configuration', async () => {
-    const dshHome = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-home-'))
-    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-agents-'))
-    const ctx = await mount({
-      provider: 'mock',
-      model: 'mock',
-      maxParallelToolCalls: 3,
-      dshHome,
-      skills: { local: { agentsHome } },
-      toolBash: { enableRunInBackground: false },
-      toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
-      workspaceContext: false,
-    }, true)
-
-    expect(ctx.get('agentLoop')?.config.maxParallelToolCalls).toBe(3)
-    const execution: ToolExecution = {
-      signal: testToolSignal,
-      token: Symbol('cli-demo-dsh-home-test') as ToolExecution['token'],
-      callId: CallId('cli-demo-dsh-home'),
-      name: 'bash',
-      arguments: { command: 'true' },
-    }
-    expect(ctx.bashEnv.collect(execution)).toMatchObject({ DSH_HOME: dshHome })
-    const bash = ctx.tools.schemas().find(tool => tool.name === 'bash')
-    expect(Object.keys((bash!.parameters as { properties: Record<string, unknown> }).properties))
-      .not.toContain('run_in_background')
-
-    const id = ctx.tasks.start({
-      kind: 'bash',
-      label: 'config forwarding probe',
-      run: () => ({ cancel: () => {}, done: Promise.resolve({ status: 'completed' }) }),
-    })
-    const wait = vi.spyOn(ctx.tasks, 'wait')
-    await ctx.tools.execute({
-      signal: testToolSignal,
-      callId: CallId('cli-demo-task-config'),
-      name: 'task_output',
-      arguments: { task_id: id, wait: true },
-    })
-    expect(wait).toHaveBeenCalledWith(id, 7, undefined, testToolSignal)
-  })
-
-  it('accepts false to keep task services without model-facing task controls', async () => {
-    const ctx = await mount({
-      provider: 'mock',
-      model: 'mock',
-      skills: { enabled: false },
-      toolTasks: false,
-      workspaceContext: false,
-    })
-
-    expect(ctx.get('tasks')).toBeDefined()
-    expect(ctx.get('tools')?.get('task_output')).toBeUndefined()
-    expect(ctx.get('tools')?.get('task_list')).toBeUndefined()
-    expect(ctx.get('tools')?.get('task_kill')).toBeUndefined()
-  })
-
-  it('exposes the Loader-safe namespace plugin shape and schema', () => {
-    expect(cliDemo.name).toBe('cli-demo')
-    expect(cliDemo.Config).toBeDefined()
-    expect('default' in cliDemo).toBe(false)
-    const loader = Object.create(Loader.prototype) as Loader
-    const unwrapped = loader.unwrapExports(cliDemo) as Record<string, unknown>
-    expect(unwrapped).toBe(cliDemo)
-    expect(unwrapped.name).toBe('cli-demo')
-    expect(typeof unwrapped.apply).toBe('function')
-  })
-})
diff --git a/packages/examples/cli-demo/tests/cli.spec.ts b/packages/examples/cli-demo/tests/cli.spec.ts
deleted file mode 100644
index 9fd87aaf52..0000000000
--- a/packages/examples/cli-demo/tests/cli.spec.ts
+++ /dev/null
@@ -1,614 +0,0 @@
-import { readdir, mkdtemp } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
-import { Context } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import { createUserMessage,
-  CallId,
-  LlmAdapter,
-  resolveRetryPolicy,
-  type GenerateOptions,
-  type ResolvedRetryPolicy,
-  type StreamChunk,
-  type TokenUsage,
-} from '@deepseek-ai/dsh-llm'
-import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
-import { afterEach, describe, expect, it } from 'vitest'
-import * as cliDemo from '../src/index.ts'
-import {
-  executeCli,
-  parseCliArgs,
-  runOneShot,
-  type CliResult,
-} from '../src/cli.ts'
-
-type ScriptEntry = readonly StreamChunk[] | 'hang'
-
-class ScriptedAdapter extends LlmAdapter {
-  readonly requests: GenerateOptions[] = []
-  private cursor = 0
-  private readonly retryPolicy = resolveRetryPolicy({
-    mode: 'normal',
-    backoff: { initialDelayMs: 1, maxDelayMs: 1, jitterRatio: 0 },
-  }, 'cli test provider retryPolicy')
-
-  constructor(private readonly script: readonly ScriptEntry[]) {
-    super()
-  }
-
-  override providerRetryPolicy(_provider: string): ResolvedRetryPolicy {
-    return this.retryPolicy
-  }
-
-  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    this.requests.push(options)
-    const entry = this.script[this.cursor++]
-    if (entry === undefined) throw new Error('script exhausted')
-    if (entry === 'hang') {
-      yield { type: 'block-start', index: 0, blockType: 'text' }
-      yield { type: 'text-delta', index: 0, text: 'partial' }
-      await new Promise<void>((_resolve, reject) => {
-        if (options.signal?.aborted === true) {
-          reject(new Error('aborted'))
-          return
-        }
-        options.signal?.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
-      })
-      return
-    }
-    for (const chunk of entry) yield chunk
-  }
-}
-
-function textResponse(text: string, usage?: TokenUsage, finish: 'stop' | 'max-tokens' = 'stop'): StreamChunk[] {
-  return [
-    { type: 'block-start', index: 0, blockType: 'text' },
-    { type: 'text-delta', index: 0, text },
-    { type: 'block-end', index: 0, block: { type: 'text', text } },
-    ...usage === undefined ? [] : [{ type: 'usage', usage } as const],
-    { type: 'finish', reason: { kind: finish } },
-  ]
-}
-
-function toolResponse(usage: TokenUsage): StreamChunk[] {
-  const id = CallId('cli-call')
-  const args = JSON.stringify({ text: 'round trip' })
-  return [
-    { type: 'block-start', index: 0, blockType: 'text' },
-    { type: 'text-delta', index: 0, text: 'working' },
-    { type: 'block-end', index: 0, block: { type: 'text', text: 'working' } },
-    { type: 'block-start', index: 1, blockType: 'tool-call' },
-    { type: 'tool-call-delta', index: 1, id, name: 'echo', argumentsDelta: args },
-    { type: 'block-end', index: 1, block: { type: 'tool-call', id, name: 'echo', arguments: args } },
-    { type: 'usage', usage },
-    { type: 'finish', reason: { kind: 'tool-calls' } },
-  ]
-}
-
-function failedResponse(usage: TokenUsage): StreamChunk[] {
-  return [
-    { type: 'block-start', index: 0, blockType: 'text' },
-    { type: 'text-delta', index: 0, text: 'discarded' },
-    { type: 'usage', usage },
-    { type: 'finish', reason: { kind: 'error', failure: { message: 'temporary', code: 'SERVER' } } },
-  ]
-}
-
-function reasoningResponse(text: string): StreamChunk[] {
-  return [
-    { type: 'block-start', index: 0, blockType: 'reasoning' },
-    { type: 'reasoning-delta', index: 0, text },
-    { type: 'block-end', index: 0, block: { type: 'reasoning', text } },
-    { type: 'finish', reason: { kind: 'stop' } },
-  ]
-}
-
-interface Harness {
-  readonly ctx: Context
-  readonly agent: Agent
-  readonly persistenceRoot: string
-}
-
-const liveContexts: Context[] = []
-
-async function harness(script: readonly ScriptEntry[]): Promise<Harness> {
-  const root = await mkdtemp(join(tmpdir(), 'dsh-cli-runner-'))
-  const ctx = new Context()
-  liveContexts.push(ctx)
-  await ctx.plugin(cliDemo, {
-    provider: 'mock',
-    model: 'mock',
-    persistenceRoot: root,
-    skills: { enabled: false },
-    workspaceContext: false,
-  })
-  await new Promise(resolve => setTimeout(resolve, 80))
-  ctx.llm.registerAdapter(['mock'], new ScriptedAdapter(script))
-  ctx.tools.register({
-    name: 'echo',
-    description: 'Echo text.',
-    parameters: { text: { type: 'string', required: true } },
-    output: {
-      schema: { type: 'string' },
-      render: (_args, value) => [{ type: 'text', text: value as string }],
-    },
-    execute: async args => `ECHO: ${(args as { text: string }).text}`,
-  })
-  const [agent] = ctx.agents.roots()
-  if (agent === undefined) throw new Error('test main agent missing')
-  return { ctx, agent, persistenceRoot: root }
-}
-
-async function invoke(
-  ctx: Context,
-  args: readonly string[],
-  options: { signal?: AbortSignal; failStdout?: boolean; failDispose?: boolean } = {},
-): Promise<{ code: number; stdout: string; stderr: string }> {
-  let stdout = ''
-  let stderr = ''
-  const code = await executeCli(args, {
-    cwd: '/tmp/cli-cwd',
-    ...options.signal === undefined ? {} : { signal: options.signal },
-    boot: async () => ctx,
-    loadEnv: () => {},
-    writeStdout: (chunk) => {
-      if (options.failStdout === true) throw new Error('stdout closed')
-      stdout += chunk
-    },
-    writeStderr: (chunk) => { stderr += chunk },
-    ...options.failDispose === true
-      ? { dispose: async (target: Context) => {
-        await target.fiber.dispose()
-        throw new Error('dispose exploded')
-      } }
-      : {},
-  })
-  return { code, stdout, stderr }
-}
-
-afterEach(async () => {
-  await Promise.all(liveContexts.splice(0).map(ctx => ctx.fiber.dispose()))
-})
-
-describe('parseCliArgs', () => {
-  it('parses defaults, explicit options, spaces, and an option-like task after --', () => {
-    expect(parseCliArgs(['task with spaces'])).toEqual({
-      kind: 'run', configPath: './cordis.yml', outputFormat: 'text', task: 'task with spaces',
-    })
-    expect(parseCliArgs(['--config', 'custom.yml', '--output-format', 'stream-json', 'do it'])).toEqual({
-      kind: 'run', configPath: 'custom.yml', outputFormat: 'stream-json', task: 'do it',
-    })
-    expect(parseCliArgs(['--', '-task'])).toMatchObject({ task: '-task' })
-    expect(parseCliArgs(['-p', 'flag task'])).toMatchObject({ task: 'flag task' })
-    expect(parseCliArgs(['--prompt', 'long-flag task'])).toMatchObject({ task: 'long-flag task' })
-    expect(parseCliArgs(['--help', 'ignored'])).toEqual({ kind: 'help' })
-  })
-
-  it('rejects missing, blank, extra, invalid-format, and unsupported flags', () => {
-    expect(() => parseCliArgs([])).toThrow('received 0')
-    expect(() => parseCliArgs(['   '])).toThrow('must not be blank')
-    expect(() => parseCliArgs(['-p', '   '])).toThrow('must not be blank')
-    expect(() => parseCliArgs(['one', 'two'])).toThrow('received 2')
-    expect(() => parseCliArgs(['-p', 'task', 'positional'])).toThrow('mutually exclusive')
-    expect(() => parseCliArgs(['--output-format', 'xml', 'task'])).toThrow('unsupported output format')
-    expect(() => parseCliArgs(['-x', 'task'])).toThrow('Unknown option')
-  })
-})
-
-describe('runOneShot and executeCli', () => {
-  it('prints help and argument diagnostics without booting or contaminating stdout', async () => {
-    let booted = false
-    let stdout = ''
-    let stderr = ''
-    const runtime = {
-      boot: async (): Promise<Context> => { booted = true; throw new Error('unexpected') },
-      writeStdout: (chunk: string): void => { stdout += chunk },
-      writeStderr: (chunk: string): void => { stderr += chunk },
-    }
-    expect(await executeCli(['--help'], runtime)).toBe(0)
-    expect(stdout).toContain('Usage: dsh-cli-demo')
-    stdout = ''
-    expect(await executeCli([], runtime)).toBe(1)
-    expect(stdout).toBe('')
-    expect(stderr).toContain('received 0')
-    expect(booted).toBe(false)
-  })
-
-  it('leaves stdout empty for environment and boot failures and resolves the default config', async () => {
-    let bootPath = ''
-    let stderr = ''
-    const code = await executeCli(['task'], {
-      cwd: '/tmp/cli-work',
-      loadEnv: (_name, _dir, warn) => { warn('env warning\n') },
-      boot: async (_name, path) => { bootPath = path; throw 'boot exploded' },
-      writeStdout: () => { throw new Error('stdout must stay empty') },
-      writeStderr: (chunk) => { stderr += chunk },
-    })
-    expect(code).toBe(1)
-    expect(bootPath).toBe(resolve('/tmp/cli-work/cordis.yml'))
-    expect(stderr).toContain('env warning')
-    expect(stderr).toContain('boot exploded')
-  })
-
-  it('contains a thrown value whose inspection and coercion both fail', async () => {
-    const hostile = new Proxy({}, {
-      getPrototypeOf: () => { throw new Error('prototype trap escaped') },
-      get: (target, key, receiver) => {
-        if (key === Symbol.toPrimitive) throw new Error('coercion escaped')
-        return Reflect.get(target, key, receiver) as unknown
-      },
-    })
-    let stdout = ''
-    let stderr = ''
-    const code = await executeCli(['task'], {
-      boot: async () => { throw hostile },
-      loadEnv: () => {},
-      writeStdout: (chunk) => { stdout += chunk },
-      writeStderr: (chunk) => { stderr += chunk },
-    })
-    expect(code).toBe(1)
-    expect(stdout).toBe('')
-    expect(stderr).toBe('dsh-cli-demo: [unrenderable thrown value]\n')
-  })
-
-  it('interrupts Loader boot and contains every late boot outcome', async () => {
-    const abort = new AbortController()
-    const lateContext = new Context()
-    liveContexts.push(lateContext)
-    const boot = Promise.withResolvers<Context>()
-    const disposed = Promise.withResolvers<undefined>()
-    let disposeCalls = 0
-    let stderr = ''
-    const running = executeCli(['task'], {
-      signal: abort.signal,
-      boot: () => boot.promise,
-      loadEnv: () => {},
-      writeStdout: () => {},
-      writeStderr: (chunk) => { stderr += chunk },
-      dispose: async (ctx) => {
-        disposeCalls += 1
-        await ctx.fiber.dispose()
-        disposed.resolve(undefined)
-      },
-    })
-    abort.abort('received SIGTERM')
-    await expect(running).resolves.toBe(1)
-    expect(stderr).toContain('received SIGTERM')
-    expect(disposeCalls).toBe(0)
-    boot.resolve(lateContext)
-    await disposed.promise
-    expect(disposeCalls).toBe(1)
-
-    const rejectedBoot = Promise.withResolvers<Context>()
-    const rejectedAbort = new AbortController()
-    const rejected = executeCli(['task'], {
-      signal: rejectedAbort.signal,
-      boot: () => rejectedBoot.promise,
-      loadEnv: () => {},
-      writeStdout: () => {},
-      writeStderr: () => {},
-    })
-    rejectedAbort.abort('stop rejected boot')
-    await expect(rejected).resolves.toBe(1)
-    rejectedBoot.reject(new Error('late boot rejection'))
-    await Promise.resolve()
-
-    let ordinaryBootStderr = ''
-    const ordinaryBootFailure = await executeCli(['task'], {
-      signal: new AbortController().signal,
-      boot: async () => { throw new Error('ordinary boot failure') },
-      loadEnv: () => {},
-      writeStdout: () => {},
-      writeStderr: (chunk) => { ordinaryBootStderr += chunk },
-    })
-    expect(ordinaryBootFailure).toBe(1)
-    expect(ordinaryBootStderr).toContain('ordinary boot failure')
-
-    const failedCleanupBoot = Promise.withResolvers<Context>()
-    const failedCleanupAbort = new AbortController()
-    const cleanupFailure = Promise.withResolvers<undefined>()
-    const failedCleanupContext = new Context()
-    liveContexts.push(failedCleanupContext)
-    const failedCleanup = executeCli(['task'], {
-      signal: failedCleanupAbort.signal,
-      boot: () => failedCleanupBoot.promise,
-      loadEnv: () => {},
-      writeStdout: () => {},
-      writeStderr: (chunk) => {
-        if (chunk.includes('dispose after interrupted boot failed: late cleanup')) cleanupFailure.resolve(undefined)
-      },
-      dispose: async (ctx) => {
-        await ctx.fiber.dispose()
-        throw new Error('late cleanup')
-      },
-    })
-    failedCleanupAbort.abort('stop failed cleanup boot')
-    await expect(failedCleanup).resolves.toBe(1)
-    failedCleanupBoot.resolve(failedCleanupContext)
-    await cleanupFailure.promise
-  })
-
-  it('renders text, flushes a persisted fresh session, and disposes the context', async () => {
-    const { ctx, agent, persistenceRoot } = await harness([textResponse('final answer')])
-    const output = await invoke(ctx, ['task'])
-    expect(output).toEqual({ code: 0, stdout: 'final answer\n', stderr: '' })
-    expect(agent.status).toBe('idle')
-    const files = await readdir(persistenceRoot, { recursive: true })
-    expect(files.some(file => file.endsWith('.jsonl.zstd'))).toBe(true)
-  })
-
-  it('writes correlated session events in stream-json mode', async () => {
-    const { ctx } = await harness([textResponse('streamed answer')])
-    const output = await invoke(ctx, ['--output-format', 'stream-json', 'task'])
-    const records = output.stdout.trim().split('\n').map(line => JSON.parse(line) as { type: string })
-
-    expect(output.code).toBe(0)
-    expect(records.some(record => record.type === 'session_event')).toBe(true)
-    expect(records.at(-1)).toMatchObject({ type: 'result', output: 'streamed answer' })
-  })
-
-  it('sums usage across tool steps and selects the last text-bearing assistant message', async () => {
-    const first = { inputTokens: 10, outputTokens: 3, cacheReadTokens: 2, cacheWriteTokens: 1 }
-    const second = { inputTokens: 7, outputTokens: 5, cacheReadTokens: 4, reasoningTokens: 6 }
-    const { ctx } = await harness([toolResponse(first), textResponse('done', second)])
-    const output = await invoke(ctx, ['--output-format', 'json', 'task'])
-    const result = JSON.parse(output.stdout) as CliResult
-    expect(output.code).toBe(0)
-    expect(result).toMatchObject({ type: 'result', output: 'done' })
-    expect(result.usage).toEqual({
-      inputTokens: 17,
-      outputTokens: 8,
-      cacheReadTokens: 6,
-      cacheWriteTokens: 1,
-      reasoningTokens: 6,
-    })
-  })
-
-  it('reports usage committed by the recovered assistant message', async () => {
-    const failed = { inputTokens: 11, outputTokens: 2, cacheReadTokens: 3 }
-    const recovered = { inputTokens: 7, outputTokens: 5, reasoningTokens: 4 }
-    const { ctx } = await harness([failedResponse(failed), textResponse('done', recovered)])
-
-    const result = await runOneShot(ctx, { task: 'task' })
-
-    expect(result.usage).toEqual({
-      inputTokens: 7,
-      outputTokens: 5,
-      reasoningTokens: 4,
-    })
-  })
-
-  it('keeps the prior text when a later assistant message has no text blocks', async () => {
-    const { ctx } = await harness([
-      toolResponse({ inputTokens: 1, outputTokens: 1 }),
-      reasoningResponse('reasoning only'),
-    ])
-    const result = await runOneShot(ctx, { task: 'task' })
-    expect(result.output).toBe('working')
-  })
-
-  it('observes only the correlated main message turn', async () => {
-    const { ctx, agent } = await harness([
-      textResponse('startup'),
-      textResponse('autonomous'),
-      textResponse('streamed'),
-    ])
-    const other = ctx.sessions.create(SessionId('unrelated'))
-    let startupStarted!: () => void
-    const started = new Promise<void>((resolve) => { startupStarted = resolve })
-    const releaseStartup = Promise.withResolvers<undefined>()
-    ctx.on('session/event', (session, event) => {
-      if (session === agent.session && event.type === 'assistant/message'
-        && event.data.turn === 1) startupStarted()
-    })
-    ctx.on('agent/turn-stopping', async ({ agent: subject, turn }) => {
-      if (subject === agent && turn === 1) await releaseStartup.promise
-    })
-    agent.followup(createUserMessage({
-      content: [{ type: 'text', text: 'startup' }],
-      source: { kind: 'plugin', plugin: 'startup' },
-    }))
-    await started
-
-    const followup = agent.followup.bind(agent)
-    let injectedBeforeReceipt = false
-    agent.followup = (input) => {
-      if (!injectedBeforeReceipt && input.source.kind === 'user') {
-        injectedBeforeReceipt = true
-        agent.inbox.append('next-step', createUserMessage({
-          content: [{ type: 'text', text: 'wrong receipt' }],
-          source: { kind: 'plugin', plugin: 'test-wrong-receipt' },
-        }))
-        other.append('user/message', createUserMessage({
-          content: [{ type: 'text', text: 'unrelated session event' }],
-          source: { kind: 'plugin', plugin: 'test' },
-        }), { surfaceOp: 'append' })
-        agent.session.append('user/message', createUserMessage({
-          content: [{ type: 'text', text: 'uncorrelated main-session event' }],
-          source: { kind: 'plugin', plugin: 'test-before-receipt' },
-        }), { surfaceOp: 'append' })
-      }
-      followup(input)
-    }
-
-    let replacementQueued = false
-    ctx.on('agent/status', ({ agent: subject, status }) => {
-      if (subject !== agent || status !== 'idle' || replacementQueued) return
-      replacementQueued = true
-      agent.followup(createUserMessage({
-        content: [{ type: 'text', text: 'autonomous' }],
-        source: { kind: 'plugin', plugin: 'test' },
-      }))
-      other.append('turn/start', { turn: 1 })
-      other.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    })
-    const streamed: { sessionId: string; event: SessionEvent }[] = []
-    const result = runOneShot(ctx, {
-      task: 'task',
-      onEvent: (sessionId, event) => { streamed.push({ sessionId, event }) },
-    })
-    releaseStartup.resolve(undefined)
-
-    const outcome = await result
-    expect(outcome).toMatchObject({ type: 'result', output: 'streamed' })
-    const events = streamed.map(item => item.event)
-    expect(events.find(event => event.type === 'turn/start'))
-      .toMatchObject({ type: 'turn/start', data: { turn: 3 } })
-    expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 3 } })
-    expect(streamed.every(item => item.sessionId === agent.session.id)).toBe(true)
-    expect(events.some(event => event.type === 'user/message'
-      && event.data.source.kind === 'plugin'
-      && event.data.source.plugin === 'test')).toBe(false)
-    expect(events.some(event => event.type === 'user/message'
-      && event.data.source.kind === 'plugin'
-      && event.data.source.plugin === 'test-before-receipt')).toBe(false)
-  })
-
-  it('correlates a task whose step history is replaced', async () => {
-    const { ctx } = await harness([textResponse('rewritten answer')])
-    ctx.on('agent/pre-step', async () => ({
-      kind: 'enter',
-      messages: [createUserMessage({
-        content: [{ type: 'text', text: 'rewritten task' }],
-        source: { kind: 'plugin', plugin: 'test' },
-      })],
-    }))
-
-    await expect(runOneShot(ctx, { task: 'original task' })).resolves.toMatchObject({
-      type: 'result',
-      output: 'rewritten answer',
-    })
-  })
-
-  it('settles rejected tasks at whole-agent idle without attributing a result', async () => {
-    const blocked = await harness([])
-    blocked.ctx.on('agent/pre-step', async () => ({
-      kind: 'reject' as const,
-    }))
-    await expect(runOneShot(blocked.ctx, { task: 'task' })).resolves.toMatchObject({ output: '' })
-
-    const failed = await harness([])
-    failed.ctx.on('agent/pre-step', async () => { throw new Error('pre-step exploded') })
-    await expect(runOneShot(failed.ctx, { task: 'task' })).resolves.toMatchObject({ output: '' })
-  })
-
-  it('emits partial data without attributing a turn outcome', async () => {
-    const { ctx } = await harness([textResponse('partial', { inputTokens: 2, outputTokens: 3 }, 'max-tokens')])
-    const output = await invoke(ctx, ['--output-format', 'json', 'task'])
-    expect(JSON.parse(output.stdout)).toMatchObject({ type: 'result', output: 'partial' })
-    expect(output.code).toBe(0)
-    expect(output.stderr).toBe('')
-  })
-
-  it('cancels an active turn, emits its durable aborted result, and disposes', async () => {
-    const { ctx, agent } = await harness(['hang'])
-    const abort = new AbortController()
-    let started!: () => void
-    const running = new Promise<void>((resolveStarted) => { started = resolveStarted })
-    ctx.on('session/event', (session, event) => {
-      if (session === agent.session && event.type === 'assistant/chunk') started()
-    })
-    const outcome = invoke(ctx, ['--output-format', 'json', 'task'], { signal: abort.signal })
-    await running
-    abort.abort('received SIGINT')
-    const output = await outcome
-    expect(output.stdout).toBe('')
-    expect(output.code).toBe(1)
-    expect(output.stderr).toContain('received SIGINT')
-    expect(agent.status).toBe('idle')
-  })
-
-  it('contains stream-writer failures, cancels, flushes, and returns the output error', async () => {
-    const { ctx, agent } = await harness(['hang'])
-    await expect(runOneShot(ctx, {
-      task: 'task',
-      onEvent: () => { throw new Error('stream sink failed') },
-    })).rejects.toThrow('stream sink failed')
-    expect(agent.status).toBe('idle')
-  })
-
-  it('handles cancellation before submission, a missing main agent, and final-output failure', async () => {
-    const early = await harness([textResponse('unused')])
-    const fakeSignal = {
-      aborted: true,
-      reason: undefined,
-    } as unknown as AbortSignal
-    await expect(runOneShot(early.ctx, { task: 'task', signal: fakeSignal })).rejects.toThrow('interrupted')
-
-    const raced = await harness([textResponse('unused')])
-    let registrations = 0
-    const racedSignal = {
-      aborted: false,
-      reason: 'cancel before followup',
-      addEventListener: (_type: string, listener: () => void) => {
-        registrations += 1
-        if (registrations === 2) listener()
-      },
-      removeEventListener: () => {},
-    } as unknown as AbortSignal
-    await expect(runOneShot(raced.ctx, { task: 'task', signal: racedSignal }))
-      .rejects.toThrow('cancel before followup')
-    expect(raced.agent.session.events.some(event => event.type === 'turn/start')).toBe(false)
-
-    const preBootAbort = new AbortController()
-    preBootAbort.abort('before boot completed')
-    const preBoot = await invoke(early.ctx, ['task'], { signal: preBootAbort.signal })
-    expect(preBoot).toMatchObject({ code: 1, stdout: '' })
-    expect(preBoot.stderr).toContain('before boot completed')
-
-    const empty = new Context()
-    liveContexts.push(empty)
-    await expect(runOneShot(empty, { task: 'task' })).rejects.toThrow('exactly one top-level agent')
-
-    const final = await harness([textResponse('answer')])
-    const output = await invoke(final.ctx, ['task'], { failStdout: true })
-    expect(output.code).toBe(1)
-    expect(output.stdout).toBe('')
-    expect(output.stderr).toContain('stdout closed')
-    expect(final.agent.status).toBe('idle')
-
-    const disposal = await harness([textResponse('answer')])
-    const disposalOutput = await invoke(disposal.ctx, ['task'], { failDispose: true })
-    expect(disposalOutput).toMatchObject({ code: 1, stdout: 'answer\n' })
-    expect(disposalOutput.stderr).toContain('dispose exploded')
-  })
-
-  it('reports disposal failure alongside an earlier run failure', async () => {
-    const ctx = new Context()
-    liveContexts.push(ctx)
-    const output = await invoke(ctx, ['task'], { failDispose: true })
-    expect(output).toEqual({
-      code: 1,
-      stdout: '',
-      stderr: 'dsh-cli-demo: config must create exactly one top-level agent, found 0\n'
-        + 'dsh-cli-demo: dispose failed: dispose exploded\n',
-    })
-  })
-
-  it('cancels startup work and queued work before the correlated turn begins', async () => {
-    const startup = await harness(['hang'])
-    let started!: () => void
-    const running = new Promise<void>((resolveStarted) => { started = resolveStarted })
-    startup.ctx.on('session/event', (session, event) => {
-      if (session === startup.agent.session && event.type === 'assistant/chunk') started()
-    })
-    startup.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'first' }], source: { kind: 'user' } }))
-    await running
-    const startupAbort = new AbortController()
-    const waiting = runOneShot(startup.ctx, { task: 'second', signal: startupAbort.signal })
-    startupAbort.abort('cancel startup')
-    await expect(waiting).rejects.toThrow('cancel startup')
-    await startup.agent.whenIdle()
-
-    const queued = await harness([textResponse('unused')])
-    const queuedAbort = new AbortController()
-    queued.ctx.on('session/event', (session, event) => {
-      if (session === queued.agent.session && event.type === 'agent/inbox/spliced'
-        && event.data.inserted.some(message => message.source.kind === 'user')) {
-        queueMicrotask(() => { queuedAbort.abort('cancel queued') })
-      }
-    })
-    await expect(runOneShot(queued.ctx, { task: 'task', signal: queuedAbort.signal })).rejects.toThrow('cancel queued')
-    await queued.agent.whenIdle()
-  })
-})
diff --git a/packages/examples/cli-demo/tsconfig.json b/packages/examples/cli-demo/tsconfig.json
deleted file mode 100644
index 095f7ce6a3..0000000000
--- a/packages/examples/cli-demo/tsconfig.json
+++ /dev/null
@@ -1,47 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "composite": true,
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src/**/*.ts"],
-  "references": [
-    {
-      "path": "../../../vendor/schemastery"
-    },
-    {
-      "path": "../../../vendor/cordis"
-    },
-    {
-      "path": "../../llm/llm"
-    },
-    {
-      "path": "../../core/session"
-    },
-    {
-      "path": "../../core/agent"
-    },
-    {
-      "path": "../../core/system-prompt"
-    },
-    {
-      "path": "../../core/tools"
-    },
-    {
-      "path": "../agent-spine-demo"
-    },
-    {
-      "path": "../../session-persistence/session-checkpoint-policy"
-    },
-    {
-      "path": "../../session-persistence/session-persistence-jsonl"
-    },
-    {
-      "path": "../../ui/app-boot"
-    },
-    {
-      "path": "../../support/invariants"
-    }
-  ]
-}
diff --git a/packages/examples/cli-demo/tsdown.config.ts b/packages/examples/cli-demo/tsdown.config.ts
deleted file mode 100644
index 646855bea9..0000000000
--- a/packages/examples/cli-demo/tsdown.config.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import { defineConfig } from 'tsdown'
-
-/** Builds the plugin and executable entries from declarations emitted by `tsc -b`. */
-export default defineConfig({
-  entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-})
diff --git a/packages/goal/goal/tests/goal.e2e.ts b/packages/goal/goal/tests/goal.e2e.ts
index 92a155c2cd..0d164acdbb 100644
--- a/packages/goal/goal/tests/goal.e2e.ts
+++ b/packages/goal/goal/tests/goal.e2e.ts
@@ -6,7 +6,7 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { decodeGoalChange } from '@deepseek-ai/dsh-goal'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 
-const binScript = fileURLToPath(new URL('../../../examples/cli-demo/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../../examples/headless-agent/tests/fixtures/headless-driver.ts', import.meta.url))
 const configPath = fileURLToPath(new URL(
   '../../../../examples/headless-agent/tests/fixtures/goal-domain/cordis.yml',
   import.meta.url,
@@ -30,8 +30,9 @@ describe('goal domain through a real cordis.yml and headless process', () => {
       label: 'goal-domain',
       tempDirPrefix: 'goal-domain-e2e-',
       binScript,
+      libBinScript: binScript,
       configPath,
-      binArgs: ['--config', configPath, '--output-format', 'json', 'prove the persisted goal domain'],
+      binArgs: [configPath, 'prove the persisted goal domain'],
       tsconfigPath: repoTsconfig,
       inspect: async (cwd) => {
         const logs = await jsonlFiles(join(cwd, '.sessions'))
@@ -41,7 +42,7 @@ describe('goal domain through a real cordis.yml and headless process', () => {
       },
     })
     expect(stderr).toBe('')
-    const result = JSON.parse(stdout) as Record<string, unknown>
+    const result = JSON.parse(stdout.trimEnd().split('\n').at(-1) ?? '') as Record<string, unknown>
     expect(result).toMatchObject({
       type: 'result',
     })
diff --git a/packages/support/loader-smoke/tests/example-launch.spec.ts b/packages/support/loader-smoke/tests/example-launch.spec.ts
index 8cf75d3be9..48bb58b09d 100644
--- a/packages/support/loader-smoke/tests/example-launch.spec.ts
+++ b/packages/support/loader-smoke/tests/example-launch.spec.ts
@@ -5,7 +5,7 @@ import {
   resolveExampleMode,
 } from '@deepseek-ai/dsh-loader-smoke'
 
-const SRC_BIN = '/repo/packages/examples/cli-demo/src/bin.ts'
+const SRC_BIN = '/repo/packages/examples/acp-demo/src/bin.ts'
 const TSCONFIG = '/repo/tsconfig.json'
 
 const originalMode = process.env[EXAMPLE_MODE_ENV]
@@ -65,7 +65,7 @@ describe('resolveExampleLaunch', () => {
       env: { DSH_HOME: '/tmp/home' },
     })
     expect(args).not.toContain('--import')
-    expect(args).toContain('/repo/packages/examples/cli-demo/lib/bin.js')
+    expect(args).toContain('/repo/packages/examples/acp-demo/lib/bin.js')
     expect(args.slice(-2)).toEqual(['--config', './cordis.yml'])
     expect(env.TSX_TSCONFIG_PATH).toBeUndefined()
     expect(env.DSH_HOME).toBe('/tmp/home')
@@ -100,6 +100,6 @@ describe('resolveExampleLaunch', () => {
   it('defaults the mode from the environment', () => {
     process.env[EXAMPLE_MODE_ENV] = 'lib'
     const { args } = resolveExampleLaunch({ srcBin: SRC_BIN })
-    expect(args).toContain('/repo/packages/examples/cli-demo/lib/bin.js')
+    expect(args).toContain('/repo/packages/examples/acp-demo/lib/bin.js')
   })
 })
diff --git a/packages/ui/app-boot/README.i18n.yaml b/packages/ui/app-boot/README.i18n.yaml
index 422e585575..24f04a21c1 100644
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/ui/app-boot/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/app-boot/README.md
-README.md: 359f05a83b41db6db5ede40db7317a0fb15de43b
-README.zh.md: a916236e30b50cc884d9d5876f27fcb1aa6f0777
+README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
+README.zh.md: 88d1c4ad0ced2f5a6440a1b64e34e738a842f938
diff --git a/packages/ui/app-boot/README.md b/packages/ui/app-boot/README.md
index 359f05a83b..c256b89288 100644
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-cli-demo`](../../examples/cli-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)): each bin is a thin self-executing composition over these helpers, parameterized by its diagnostic prefix, so loader-failure behavior has one owner instead of drifting between published artifacts.
+Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md) and [`dsh-acp-demo`](../../examples/acp-demo/README.md)): each bin is a thin self-executing composition over these helpers, parameterized by its diagnostic prefix, so loader-failure behavior has one owner instead of drifting between published artifacts.
 
 | Export | Role |
 |---|---|
diff --git a/packages/ui/app-boot/README.zh.md b/packages/ui/app-boot/README.zh.md
index a916236e30..88d1c4ad0c 100644
--- a/packages/ui/app-boot/README.zh.md
+++ b/packages/ui/app-boot/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-供 app bin（[`dsh`](../../../apps/cli/README.md)、[`dsh-cli-demo`](../../examples/cli-demo/README.md)、[`dsh-acp-demo`](../../examples/acp-demo/README.md)）共用的启动粘合层：每个 bin 都是在这些 helper 上构建的精简自执行组合，并以自身诊断前缀参数化。这样，Loader 故障行为只由一处负责，不会在已发布产物之间逐渐分化。
+供 app bin（[`dsh`](../../../apps/cli/README.md) 与 [`dsh-acp-demo`](../../examples/acp-demo/README.md)）共用的启动粘合层：每个 bin 都是在这些 helper 上构建的精简自执行组合，并以自身诊断前缀参数化。这样，Loader 故障行为只由一处负责，不会在已发布产物之间逐渐分化。
 
 | 导出 | 职责 |
 |---|---|
diff --git a/packages/ui/app-boot/src/index.ts b/packages/ui/app-boot/src/index.ts
index 72c2e8137f..5f90a5ee30 100644
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Shared boot glue for the app bins (`dsh`, `dsh-cli-demo`, `dsh-acp-demo`): load the gitignored
+ * Shared boot glue for the app bins (`dsh`, `dsh-acp-demo`): load the gitignored
  * `.env`, install the fail-loud Loader guards, resolve the config path (snapshot-aware), load the
  * optional user patch layers from the Harness home (`~/.dsh`), expose its path resolver to
  * config expressions, and drive the Cordis Loader against a leaf `cordis.yml` until the tree settles.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6b7cd40f94..9957263083 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -313,9 +313,6 @@ importers:
       '@deepseek-ai/dsh-bash-sandbox':
         specifier: workspace:*
         version: link:../packages/bash/bash-sandbox
-      '@deepseek-ai/dsh-cli-demo':
-        specifier: workspace:*
-        version: link:../packages/examples/cli-demo
       '@deepseek-ai/dsh-code-runtime-worker':
         specifier: workspace:*
         version: link:../packages/code-runtime/code-runtime-worker
@@ -3203,54 +3200,6 @@ importers:
         specifier: 0.0.0-test.0
         version: 0.0.0-test.0
 
-  packages/examples/cli-demo:
-    devDependencies:
-      '@cordisjs/plugin-include':
-        specifier: workspace:^
-        version: link:../../../vendor/include
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-agent-spine-demo':
-        specifier: workspace:^
-        version: link:../agent-spine-demo
-      '@deepseek-ai/dsh-app-boot':
-        specifier: workspace:^
-        version: link:../../ui/app-boot
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-checkpoint-policy':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-checkpoint-policy
-      '@deepseek-ai/dsh-session-persistence-jsonl':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
-      '@deepseek-ai/dsh-workspace-context':
-        specifier: workspace:^
-        version: link:../../context/workspace-context
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-      schemastery:
-        specifier: ^3.17.0
-        version: link:../../../vendor/schemastery
-
   packages/examples/jsonrpc-demo:
     dependencies:
       '@deepseek-ai/dsh-app-boot':
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 151aadb278..1edbc0b36a 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -124,7 +124,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session',
     title: 'In-memory session store',
     mode: 'core',
-    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
+    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
     note: 'Owns append-only Session instances and emits the durable session event feed.',
   },
   {
@@ -303,7 +303,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'agent',
     title: 'Agent service',
     mode: 'core',
-    consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess'],
+    consumers: ['agent-loop', 'acp', 'subagent-inprocess'],
     note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
   },
   {
@@ -635,10 +635,10 @@ const APP_EXAMPLES = [
   {
     id: 'headless',
     rel: 'examples/headless-agent/composition.md',
-    title: 'Headless Agent App Composition',
+    title: 'Headless Agent Snapshot Composition',
     label: 'examples/headless-agent',
     config: 'examples/headless-agent/cordis.yml',
-    summary: 'The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.',
+    summary: 'The headless snapshot composition combines the real DeepSeek adapter and coding capabilities with one explicitly configured persisted top-level agent; its JSONL driver is test-only.',
   },
   {
     id: 'acp',
@@ -657,9 +657,7 @@ function renderAppExpansion(lines: string[], appNode: string, pluginName: string
   const jsonl = nodeId('bundle', 'jsonl')
   lines.push(`  ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`)
   lines.push(`  ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
-  if (pluginName === '@deepseek-ai/dsh-cli-demo') {
-    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'cli')}["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]`)
-  } else if (pluginName === '@deepseek-ai/dsh-acp-demo') {
+  if (pluginName === '@deepseek-ai/dsh-acp-demo') {
     lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>automation-only JSON-RPC stdio<br/>fresh sessions created by client"]`)
   }
   lines.push(
@@ -685,7 +683,7 @@ function renderAppComposition(example: AppExample): string {
     const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
     lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
     lines.push(`  cfg --> ${pluginNode}`)
-    if (plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
+    if (plugin.name === '@deepseek-ai/dsh-acp-demo') {
       renderAppExpansion(lines, pluginNode, plugin.name)
     }
   }
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 8e6f336e96..aebf6ca641 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -602,7 +602,6 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'vitest.e2e.config.ts',
     'examples/headless-agent/tests/keyless-smoke.e2e.ts',
     'apps/cli/tests/built-bin.e2e.ts',
-    'packages/examples/cli-demo/tests/built-bin.e2e.ts',
     'packages/examples/acp-demo/tests/built-bin.e2e.ts',
     'packages/host/directory-picker-native/tests/built-worker.e2e.ts',
     'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts',
diff --git a/tsconfig.host.json b/tsconfig.host.json
index a44a792179..dba5222b32 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -154,7 +154,6 @@
     { "path": "./packages/core/agent-loop" },
     { "path": "./packages/llm/llm-retry" },
     { "path": "./packages/examples/agent-spine-demo" },
-    { "path": "./packages/examples/cli-demo" },
     { "path": "./packages/subprocess/subprocess" },
     { "path": "./packages/subprocess/subprocess-local" },
     { "path": "./packages/bash/bash" },

From be3e4ac455bd1760d873d530c09d0796a89b6abf Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:06:01 +0800
Subject: [PATCH 226/516] fix(test): address cli demo cleanup review feedback

---
 ...-20-remove-stdio-and-echo-agents.i18n.yaml |   4 +-
 ...2026-07-20-remove-stdio-and-echo-agents.md |   4 +-
 ...6-07-20-remove-stdio-and-echo-agents.zh.md |   4 +-
 .../2026-08-08-remove-cli-demo.i18n.yaml      |   4 +-
 .../2026-08-08-remove-cli-demo.md             |   2 +-
 .../2026-08-08-remove-cli-demo.zh.md          |   2 +-
 docs/event-producer-consumer.md               |   2 +-
 docs/user/guide/quickstart.i18n.yaml          |   4 +-
 docs/user/guide/quickstart.md                 |   4 +-
 docs/user/guide/quickstart.zh.md              |   4 +-
 .../fixtures/subagent/subagent-acp/driver.ts  |   2 +-
 .../tests/fixtures/headless-driver.ts         |   4 +-
 .../tests/fixtures/telemetry-otel-driver.ts   |   2 +-
 .../tests/fixtures/time-context-driver.ts     |   2 +-
 .../subagent/subagent-dsh-sdk/driver.ts       |   2 +-
 examples/package.json                         |   1 +
 packages/examples/README.i18n.yaml            |   4 +-
 packages/examples/README.md                   |   2 +-
 packages/examples/README.zh.md                |   2 +-
 .../support/loader-smoke/README.i18n.yaml     |   4 +-
 packages/support/loader-smoke/README.md       |   6 +-
 packages/support/loader-smoke/README.zh.md    |   6 +-
 packages/support/loader-smoke/package.json    |   8 +-
 .../support/loader-smoke/src/agent-turn.ts    |   7 +-
 packages/support/loader-smoke/src/index.ts    |   6 +
 .../loader-smoke/tests/agent-turn.spec.ts     | 160 ++++++++++++++++++
 packages/support/loader-smoke/tsconfig.json   |   9 +
 pnpm-lock.yaml                                |  12 ++
 .../verify-package-readme-model-experience.ts |   2 +-
 29 files changed, 238 insertions(+), 37 deletions(-)
 rename examples/headless-agent/tests/fixtures/one-shot.ts => packages/support/loader-smoke/src/agent-turn.ts (93%)
 create mode 100644 packages/support/loader-smoke/tests/agent-turn.spec.ts

diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
index 51e416d9f8..a21ac5cfe9 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.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 .agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
-2026-07-20-remove-stdio-and-echo-agents.md: 4ffeacae4afc212b0d7b739def2c0e96780d5e54
-2026-07-20-remove-stdio-and-echo-agents.zh.md: 462dc275f151dbeb41bf431fc2ee583e74f22a6b
+2026-07-20-remove-stdio-and-echo-agents.md: 256e626f4ff41016d0227eef7cc3e4e51e15058b
+2026-07-20-remove-stdio-and-echo-agents.zh.md: bb7a2abd8be73ac3ea089121592b3f26162bf619
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
index 4ffeacae4a..256e626f4f 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
@@ -24,13 +24,13 @@ The remaining application roles are explicit:
 
 The SDK project model and create/config workflows replace the `stdio` run-interface option with `tui`; generated TUI projects compose `@deepseek-ai/dsh-tui` and create or resume one exact session. Repository-facing demo documentation requires a DeepSeek API key and leads with the real Headless or TUI agents.
 
-Keyless validation is test-owned. The Headless Loader smoke uses a fixture adapter to exercise a real tool round trip, the `dsh` built-bin suite pins one-shot output, persistence, failure, and signal semantics, and package-specific Loader tests keep deterministic adapters beside their scenarios. None is exposed as a runnable mock agent.
+Keyless validation is test-owned. The Headless Loader smoke uses a fixture adapter to exercise a real tool round trip, the `dsh` built-bin suite pins the published one-shot entry and output, the product Headless snapshot pins persistence, and the Headless PTY shutdown e2e pins signal escalation. Package-specific Loader tests keep deterministic adapters beside their scenarios. None is exposed as a runnable mock agent.
 
 ## Verification
 
 TUI and Headless Loader coverage run the real app packages in source and built modes. PTY-driven subprocess coverage is reserved for the TUI lifecycle; other entry-point smokes use the one-shot pipe protocol. Headless proves its task/result and tool-call contracts. Generated graphs and repository searches reject stale package, command, leaf, SDK-interface, `createStdioChat`, and `StdioRuntime` references.
 
-The built `dsh` bin rejects a piped TUI launch before Loader boot and points at `dsh run`; `apps/cli/tests/built-bin.e2e.ts` pins the product one-shot path under plain Node, including output, persistence, invalid arguments, missing configuration, and signals. The headless example's test-only JSONL driver preserves assembled canonical-event snapshots without creating a second CLI contract. Code Mode has programmatic TUI snapshots and an ACP overlay demo. Time-context integration uses the explicit Headless test composition for two ordered turns, while its package tests own finer elapsed-time behavior.
+The built `dsh` bin rejects a piped TUI launch before Loader boot and points at `dsh run`; `apps/cli/tests/built-bin.e2e.ts` pins the product one-shot entry under plain Node, including output and invalid arguments. `examples/headless-agent/tests/headless.snapshot.ts` pins product persistence, while `apps/cli/tests/headless-shutdown.e2e.ts` owns bounded signal escalation. The headless example's test-only JSONL driver preserves assembled canonical-event snapshots without creating a second CLI contract. Code Mode has programmatic TUI snapshots and an ACP overlay demo. Time-context integration uses the explicit Headless test composition for two ordered turns, while its package tests own finer elapsed-time behavior.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
index 462dc275f1..bb7a2abd8b 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
@@ -24,13 +24,13 @@ DeepSeek Harness 在 TUI 和 Headless coding agent 之外，还提供了两个
 
 SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换为 `tui`；生成的 TUI 工程组合 `@deepseek-ai/dsh-tui`，并创建或恢复一个确切会话。仓库中的演示文档要求 DeepSeek API key，并优先引导到真实的 Headless 或 TUI agent。
 
-无密钥验证由测试负责。Headless Loader 冒烟测试使用 fixture 适配器验证真实工具往返；`dsh` built-bin 测试套件固定单次运行的输出、持久化、失败和信号语义；各包专属的 Loader 测试则将确定性适配器放在对应场景旁。其中任何一项都不会作为可运行的 mock agent 对外暴露。
+无密钥验证由测试负责。Headless Loader 冒烟测试使用 fixture 适配器验证真实工具往返；`dsh` built-bin 测试套件固定已发布的一次性入口和输出；产品 Headless 快照固定持久化；Headless PTY 关闭 e2e 固定信号升级。各包专属的 Loader 测试则将确定性适配器放在对应场景旁。其中任何一项都不会作为可运行的 mock agent 对外暴露。
 
 ## 验证
 
 TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果契约和工具调用契约。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
 
-构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性路径，包括输出、持久化、无效参数、缺失配置和信号。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）契约。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
+构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口，包括输出和无效参数。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）契约。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
index ae6e47b2c1..cd43c3a27b 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.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 .agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
-2026-08-08-remove-cli-demo.md: 5875f47f2d2463fd6f82f66df5ca08fef8e06aed
-2026-08-08-remove-cli-demo.zh.md: 1bb9e2c8860f57e1170527cee0cbe694af9990f6
+2026-08-08-remove-cli-demo.md: c1153f5e9fcc89585e926f8f088829c849d1f6c1
+2026-08-08-remove-cli-demo.zh.md: 1f9719b176c05009900a268a5bb2d2d7fcc79df3
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
index 5875f47f2d..c1153f5e9f 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
@@ -14,7 +14,7 @@ The replay suites still need canonical session events to pin assembled backend b
 
 Delete `@deepseek-ai/dsh-cli-demo` completely: its package, bin, parser, app plugin, output formats, tests, workspace references, generated-catalog entries, and active documentation. No alias or compatibility package remains. The root `demo:headless` script is retained only as a direct alias of `dsh run`; the product command owns final-text stdout, the observation URL on stderr, persistence, exit status, and shutdown.
 
-`examples/headless-agent` becomes an explicit test composition. Its Loader configs mount `@deepseek-ai/dsh-agent-spine-demo`, one root agent, JSONL persistence, and checkpoint policy as separate rows instead of hiding them behind an app bundle. An unexported example-owned TypeScript fixture drives a task and emits canonical events as JSONL for replay snapshots. It is launched only by tests, has no package export or bin, and is not a supported product output format.
+`examples/headless-agent` becomes an explicit test composition. Its Loader configs mount `@deepseek-ai/dsh-agent-spine-demo`, one root agent, JSONL persistence, and checkpoint policy as separate rows instead of hiding them behind an app bundle. The support-tier `@deepseek-ai/dsh-loader-smoke` package owns the shared direct-agent turn helper; unexported example-local drivers select their Loader configuration and render canonical events as JSONL. They are launched only by tests, have no bin, and do not define a supported product output format.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
index 1bb9e2c886..1f9719b176 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 彻底删除 `@deepseek-ai/dsh-cli-demo`：包括它的包、bin、解析器、应用插件、输出格式、测试、workspace 引用、生成目录条目和现行文档。不保留别名或兼容包。根目录的 `demo:headless` 脚本仅作为 `dsh run` 的直接别名保留；stdout 上的最终文本、stderr 上的观察 URL、持久化、退出状态和关闭行为均由产品命令负责。
 
-`examples/headless-agent` 成为显式测试组装。其 Loader 配置把 `@deepseek-ai/dsh-agent-spine-demo`、一个根 agent（智能体）、JSONL 持久化和检查点策略挂载为独立配置行，不再将其隐藏在应用组合包之后。一个由示例自有且未导出的 TypeScript fixture（测试前置数据）会驱动任务，并以 JSONL 发出供回放快照使用的规范事件。该 fixture 只由测试启动，没有包导出或 bin，也不是受支持的产品输出格式。
+`examples/headless-agent` 成为显式测试组装。其 Loader 配置把 `@deepseek-ai/dsh-agent-spine-demo`、一个根 agent（智能体）、JSONL 持久化和检查点策略挂载为独立配置行，不再将其隐藏在应用组合包之后。支持层的 `@deepseek-ai/dsh-loader-smoke` 包负责共享的直接 agent 轮次 helper；未导出的示例本地 driver 选择各自的 Loader 配置，并将规范事件渲染为 JSONL。这些 driver 只由测试启动，不提供 bin，也不定义受支持的产品输出格式。
 
 ## 考虑过的替代方案
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index b4e5fa1795..13e96e9dd8 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -32,7 +32,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`loader-smoke`](../packages/support/loader-smoke), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml
index b5ab33db5f..dfdba88bec 100644
--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.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 docs/user/guide/quickstart.md
-quickstart.md: 2f86ce4cb7896ca75b7457186d4633066a899b83
-quickstart.zh.md: f7ddf88c74b5a32daa1d2b81feeaed192e7a3f9c
+quickstart.md: 9d1a04f0a094919bb008a7e94564a6612e10732d
+quickstart.zh.md: 7182f63586f4f08524c643a7c6c1ad599b2de098
diff --git a/docs/user/guide/quickstart.md b/docs/user/guide/quickstart.md
index 2f86ce4cb7..9d1a04f0a0 100644
--- a/docs/user/guide/quickstart.md
+++ b/docs/user/guide/quickstart.md
@@ -22,6 +22,7 @@ pnpm -v
 git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
 cd deepseek-harness
 pnpm install
+pnpm run build
 ```
 
 Create the gitignored repository-root `.env`:
@@ -42,10 +43,9 @@ pnpm run dsh run "summarize the architecture of this workspace"
 
 ## Step 3: use the Web UI
 
-Build and start the browser interface:
+Start the browser interface:
 
 ```sh
-pnpm run build
 pnpm run dsh web
 ```
 
diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md
index f7ddf88c74..7182f63586 100644
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -22,6 +22,7 @@ pnpm -v
 git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
 cd deepseek-harness
 pnpm install
+pnpm run build
 ```
 
 在仓库根目录创建已被 Git 忽略的 `.env`：
@@ -42,10 +43,9 @@ pnpm run dsh run "summarize the architecture of this workspace"
 
 ## 第三步：使用 Web UI
 
-构建并启动浏览器界面：
+启动浏览器界面：
 
 ```sh
-pnpm run build
 pnpm run dsh web
 ```
 
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-acp/driver.ts b/examples/acp-agent/tests/fixtures/subagent/subagent-acp/driver.ts
index 4436d52b24..18f7691d55 100644
--- a/examples/acp-agent/tests/fixtures/subagent/subagent-acp/driver.ts
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-acp/driver.ts
@@ -2,7 +2,7 @@
 /** Test driver: one delegation turn through a headless Loader composition. */
 
 import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-import { runFixtureTurn } from '../../../../../headless-agent/tests/fixtures/one-shot.ts'
+import { runFixtureTurn } from '@deepseek-ai/dsh-loader-smoke'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('acp-subagent cwd driver requires a config path')
diff --git a/examples/headless-agent/tests/fixtures/headless-driver.ts b/examples/headless-agent/tests/fixtures/headless-driver.ts
index d9a30afa83..88d7d73b67 100644
--- a/examples/headless-agent/tests/fixtures/headless-driver.ts
+++ b/examples/headless-agent/tests/fixtures/headless-driver.ts
@@ -3,8 +3,8 @@
 
 import type { Context } from 'cordis'
 import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import { runFixtureTurn } from '@deepseek-ai/dsh-loader-smoke'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { runFixtureTurn } from './one-shot.ts'
 
 const NAME = 'headless-test-driver'
 const [configPath, ...taskParts] = process.argv.slice(2)
@@ -16,7 +16,7 @@ const uninstallFailLoud = installFailLoud(NAME)
 let ctx: Context | undefined
 try {
   loadEnv(NAME)
-  ctx = await boot(NAME, resolveConfigPath(configPath, process.env.DSH_SNAPSHOT))
+  ctx = await boot(NAME, resolveConfigPath(configPath, undefined))
   const result = await runFixtureTurn(ctx, {
     task: taskParts.join(' '),
     onEvent: (sessionId: string, event: SessionEvent) => {
diff --git a/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts b/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts
index f7e1001628..afb00b0eca 100644
--- a/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts
+++ b/examples/headless-agent/tests/fixtures/telemetry-otel-driver.ts
@@ -11,7 +11,7 @@ import { createServer } from 'node:http'
 import { once } from 'node:events'
 import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 import { recordFeedback } from '@deepseek-ai/dsh-command-feedback'
-import { runFixtureTurn } from './one-shot.ts'
+import { runFixtureTurn } from '@deepseek-ai/dsh-loader-smoke'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('telemetry-otel driver requires a config path')
diff --git a/examples/headless-agent/tests/fixtures/time-context-driver.ts b/examples/headless-agent/tests/fixtures/time-context-driver.ts
index 843bbdc2ea..00479b4221 100644
--- a/examples/headless-agent/tests/fixtures/time-context-driver.ts
+++ b/examples/headless-agent/tests/fixtures/time-context-driver.ts
@@ -2,7 +2,7 @@
 /** Test driver that sends two turns through one Headless Loader composition. */
 
 import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-import { runFixtureTurn } from './one-shot.ts'
+import { runFixtureTurn } from '@deepseek-ai/dsh-loader-smoke'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('time-context driver requires a config path')
diff --git a/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/driver.ts b/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/driver.ts
index 4b52a0f929..7ed378b8b5 100644
--- a/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/driver.ts
+++ b/examples/jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/driver.ts
@@ -2,7 +2,7 @@
 /** Test driver: one delegation turn through a headless Loader composition. */
 
 import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-import { runFixtureTurn } from '../../../../../headless-agent/tests/fixtures/one-shot.ts'
+import { runFixtureTurn } from '@deepseek-ai/dsh-loader-smoke'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('sdk-subagent cwd driver requires a config path')
diff --git a/examples/package.json b/examples/package.json
index 40628f0255..1f6e99d240 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -39,6 +39,7 @@
     "@deepseek-ai/dsh-llm-deepseek": "workspace:*",
     "@deepseek-ai/dsh-llm-pi-ai": "workspace:*",
     "@deepseek-ai/dsh-llm-replay": "workspace:*",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:*",
     "@deepseek-ai/dsh-lsp": "workspace:*",
     "@deepseek-ai/dsh-lsp-local": "workspace:*",
     "@deepseek-ai/dsh-permission": "workspace:*",
diff --git a/packages/examples/README.i18n.yaml b/packages/examples/README.i18n.yaml
index e6a48a3a7d..506e867ef5 100644
--- a/packages/examples/README.i18n.yaml
+++ b/packages/examples/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/examples/README.md
-README.md: 36d1c0d0ddb7a3840af10e6a69ea407d3471c661
-README.zh.md: 9886abe8eedc27a6c62728b93fd63748b2c7dea6
+README.md: 2d672dcc307bb280cf3803f29128eba4988a8da0
+README.zh.md: e827e7cff4ff9d6521e5889e48270e06641ef38c
diff --git a/packages/examples/README.md b/packages/examples/README.md
index 36d1c0d0dd..2d672dcc30 100644
--- a/packages/examples/README.md
+++ b/packages/examples/README.md
@@ -10,7 +10,7 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling
 | [`acp-demo/`](acp-demo/README.md) | `@deepseek-ai/dsh-acp-demo` | ACP automation application bundle |
 | [`jsonrpc-demo/`](jsonrpc-demo/README.md) | `@deepseek-ai/dsh-jsonrpc-demo` | External-config JSON-RPC runtime |
 
-`agent-spine-demo` is the shared bundle; `acp-demo` adds its automation front door, while `jsonrpc-demo` boots a deployment-owned plugin tree. Product one-shot execution belongs to `dsh run` rather than a package in this directory.
+`agent-spine-demo` is the shared bundle; `acp-demo` adds its automation front door, while `jsonrpc-demo` boots a deployment-owned plugin tree. Product one-shot execution belongs to `dsh run`; no package in this directory provides it.
 
 These packages are not product API. Product seams and front doors remain in their owning groups; demo bundles select concrete compositions.
 
diff --git a/packages/examples/README.zh.md b/packages/examples/README.zh.md
index 9886abe8ee..e827e7cff4 100644
--- a/packages/examples/README.zh.md
+++ b/packages/examples/README.zh.md
@@ -10,7 +10,7 @@
 | [`acp-demo/`](acp-demo/README.md) | `@deepseek-ai/dsh-acp-demo` | ACP 自动化应用组合包 |
 | [`jsonrpc-demo/`](jsonrpc-demo/README.md) | `@deepseek-ai/dsh-jsonrpc-demo` | 外部配置 JSON-RPC 运行时 |
 
-`agent-spine-demo` 是共享组合包；`acp-demo` 添加自动化入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。产品单次执行归 `dsh run` 所有，而不再由本目录中的 package 提供。
+`agent-spine-demo` 是共享组合包；`acp-demo` 添加自动化入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。产品单次执行归 `dsh run` 所有；本目录没有任何包提供该功能。
 
 这些包不是产品 API。产品 seam 与前端入口仍位于各自的归属组；演示组合包只选择具体组合。
 
diff --git a/packages/support/loader-smoke/README.i18n.yaml b/packages/support/loader-smoke/README.i18n.yaml
index 2c99378710..4e49d185bc 100644
--- a/packages/support/loader-smoke/README.i18n.yaml
+++ b/packages/support/loader-smoke/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/support/loader-smoke/README.md
-README.md: 73610ce50ebac4c6fc7bb9135f7b41b347c60685
-README.zh.md: 9254cd1592d4bf3f119d350f04165228db87b1cf
+README.md: e5a33beb95f4e5940364cf309c8ea5fea60686f1
+README.zh.md: 1f3c6235175b3cfdcefec111eac39b2361b0e05b
diff --git a/packages/support/loader-smoke/README.md b/packages/support/loader-smoke/README.md
index 73610ce50e..e5a33beb95 100644
--- a/packages/support/loader-smoke/README.md
+++ b/packages/support/loader-smoke/README.md
@@ -6,15 +6,17 @@ Shared subprocess harness for tests that boot an app and `cordis.yml` through th
 
 `runLoaderSmoke` accepts bin and config paths, optional complete bin arguments, environment overrides, stdin, pre-run setup, and pre-cleanup inspection. It owns the isolated cwd, DSH homes, diagnostics, deadline, termination, EOF, and cleanup; it returns both streams after a zero exit and rejects with both streams on failure.
 
+`runFixtureTurn` drives one task through exactly one configured root agent, forwards canonical events after that task reaches the durable inbox, flushes the session, and returns the final assistant text plus accumulated usage. Example-local drivers retain configuration, rendering, and assertion ownership.
+
 This is support-tier test infrastructure, not product API.
 
 ## Model Experience
 
-None, as this test-only harness boots example processes and inspects their streams without changing an assembled model request.
+None, as the test harness submits only the consuming test's ordinary user task and delegates prompt and tool composition to the loaded tree.
 
 #### KV Cache effect
 
-None; this package neither assembles nor sends a provider request.
+None beyond the loaded tree; the helper neither changes the request prefix nor retains state across runs.
 
 ## Known Limitations and Deferred Work
 
diff --git a/packages/support/loader-smoke/README.zh.md b/packages/support/loader-smoke/README.zh.md
index 9254cd1592..1f3c623517 100644
--- a/packages/support/loader-smoke/README.zh.md
+++ b/packages/support/loader-smoke/README.zh.md
@@ -6,15 +6,17 @@
 
 `runLoaderSmoke` 接受可执行文件路径和配置路径、可选的完整可执行文件参数、环境变量覆盖、标准输入、运行前准备和清理前检查。它负责隔离工作目录、DSH 主目录、诊断、截止时间、终止、EOF 和清理；进程以零状态退出后返回两个流，失败时则返回拒绝并附带两个流。
 
+`runFixtureTurn` 通过恰好一个已配置的根 agent（智能体）驱动一项任务，在该任务进入持久收件箱后转发规范事件，刷写会话，并返回最终 assistant 文本和累计用量。示例本地 driver 继续负责配置、渲染和断言。
+
 这是支持层测试基础设施，而非产品 API。
 
 ## 模型体验
 
-无。该测试专用 harness 启动示例进程并检查它们的流，不会改变组装后的模型请求。
+无，因为测试 harness 仅提交调用方测试的普通用户任务，并将提示词和工具组装交由已加载的插件树负责。
 
 #### KV Cache 影响
 
-无；该包既不组装也不发送提供方请求。
+除已加载树本身的影响外，无其他影响；该 helper 既不更改请求前缀，也不跨运行保留状态。
 
 ## 已知限制与暂缓事项
 
diff --git a/packages/support/loader-smoke/package.json b/packages/support/loader-smoke/package.json
index 1eeabb950d..5cb8ef96a2 100644
--- a/packages/support/loader-smoke/package.json
+++ b/packages/support/loader-smoke/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-loader-smoke",
-  "description": "Shared subprocess harness for keyless real-Loader example smoke tests",
+  "description": "Shared subprocess and direct-agent harness for keyless real-Loader example smoke tests",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -29,11 +29,17 @@
     "tsx": "^4.22.4"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }
 }
diff --git a/examples/headless-agent/tests/fixtures/one-shot.ts b/packages/support/loader-smoke/src/agent-turn.ts
similarity index 93%
rename from examples/headless-agent/tests/fixtures/one-shot.ts
rename to packages/support/loader-smoke/src/agent-turn.ts
index 79b84da36f..ea3a65d725 100644
--- a/examples/headless-agent/tests/fixtures/one-shot.ts
+++ b/packages/support/loader-smoke/src/agent-turn.ts
@@ -1,4 +1,7 @@
-/** Test-only direct-agent turn driver shared by assembled Loader fixtures. */
+/**
+ * Test-only direct-agent turn driver shared by assembled Loader fixtures.
+ * @module @deepseek-ai/dsh-loader-smoke/agent-turn
+ */
 
 import type { Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -39,7 +42,7 @@ function onlyRootAgent(ctx: Context): Agent {
   const agents = ctx.get('agents')?.roots() ?? []
   const [agent] = agents
   if (agent === undefined || agents.length !== 1) {
-    throw new Error(`headless fixture requires exactly one top-level agent, found ${agents.length}`)
+    throw new Error(`fixture turn requires exactly one top-level agent, found ${agents.length}`)
   }
   return agent
 }
diff --git a/packages/support/loader-smoke/src/index.ts b/packages/support/loader-smoke/src/index.ts
index 4ee5cfec7d..33ec56ec0e 100644
--- a/packages/support/loader-smoke/src/index.ts
+++ b/packages/support/loader-smoke/src/index.ts
@@ -16,6 +16,12 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { execa } from 'execa'
 
+export {
+  runFixtureTurn,
+  type FixtureTurnOptions,
+  type FixtureTurnResult,
+} from './agent-turn.ts'
+
 const DEFAULT_PROCESS_TIMEOUT_MS = 30_000
 
 /** Vitest deadline that leaves room for the subprocess-owned 30-second diagnostic timeout. */
diff --git a/packages/support/loader-smoke/tests/agent-turn.spec.ts b/packages/support/loader-smoke/tests/agent-turn.spec.ts
new file mode 100644
index 0000000000..481b4ef566
--- /dev/null
+++ b/packages/support/loader-smoke/tests/agent-turn.spec.ts
@@ -0,0 +1,160 @@
+import type { Context } from 'cordis'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { describe, expect, it, vi } from 'vitest'
+import { runFixtureTurn } from '../src/agent-turn.ts'
+
+type Listener = (session: unknown, event: SessionEvent) => void
+
+const event = (value: object): SessionEvent => value as unknown as SessionEvent
+
+function turnHarness(): {
+  readonly ctx: Context
+  readonly session: { readonly id: string }
+  readonly foreignSession: object
+  readonly emit: (session: unknown, value: object) => void
+  readonly setFollowup: (callback: (message: { readonly id: unknown }) => void) => void
+  readonly whenIdle: ReturnType<typeof vi.fn>
+  readonly disposeListener: ReturnType<typeof vi.fn>
+  readonly flush: ReturnType<typeof vi.fn>
+} {
+  const session = { id: 'fixture-session' }
+  const foreignSession = {}
+  let listener: Listener | undefined
+  let followup = (_message: { readonly id: unknown }): void => {}
+  const whenIdle = vi.fn(async () => {})
+  const disposeListener = vi.fn()
+  const flush = vi.fn(async () => {})
+  const agent = {
+    session,
+    whenIdle,
+    followup: vi.fn((message: { readonly id: unknown }) => { followup(message) }),
+  }
+  const ctx = {
+    get: (name: string) => name === 'agents' ? { roots: () => [agent] } : undefined,
+    on: (_name: string, callback: Listener) => {
+      listener = callback
+      return disposeListener
+    },
+    sessions: { flush },
+  } as unknown as Context
+  return {
+    ctx,
+    session,
+    foreignSession,
+    emit: (target, value) => { listener?.(target, event(value)) },
+    setFollowup: (callback) => { followup = callback },
+    whenIdle,
+    disposeListener,
+    flush,
+  }
+}
+
+describe('runFixtureTurn', () => {
+  it.each([
+    ['no agent registry', undefined, 0],
+    ['multiple roots', { roots: () => [{}, {}] }, 2],
+  ])('rejects %s', async (_label, registry, count) => {
+    const ctx = { get: () => registry } as unknown as Context
+    await expect(runFixtureTurn(ctx, { task: 'ignored' }))
+      .rejects.toThrow(`fixture turn requires exactly one top-level agent, found ${count}`)
+  })
+
+  it('observes only the owned interval and returns its final text and deduplicated usage', async () => {
+    const harness = turnHarness()
+    const observed: SessionEvent[] = []
+    harness.setFollowup((message) => {
+      harness.emit(harness.foreignSession, {
+        type: 'assistant/message', seq: 0, time: 0, data: { message: { content: [] } },
+      })
+      harness.emit(harness.session, {
+        type: 'step/start', seq: 0, time: 0, data: { turn: 1, step: 1 },
+      })
+      harness.emit(harness.session, {
+        type: 'agent/inbox/spliced', seq: 1, time: 1, data: { inserted: [{ id: 'other' }] },
+      })
+      harness.emit(harness.session, {
+        type: 'agent/inbox/spliced', seq: 2, time: 2, data: { inserted: [message] },
+      })
+      harness.emit(harness.session, {
+        type: 'assistant/chunk', seq: 3, time: 3,
+        data: { turn: 1, step: 1, chunk: { type: 'text-delta', text: 'partial' } },
+      })
+      harness.emit(harness.session, {
+        type: 'assistant/chunk', seq: 4, time: 4,
+        data: {
+          turn: 1,
+          step: 1,
+          chunk: { type: 'usage', usage: { inputTokens: 2, outputTokens: 3, reasoningTokens: 1 } },
+        },
+      })
+      harness.emit(harness.session, {
+        type: 'assistant/message', seq: 5, time: 5,
+        data: {
+          turn: 1,
+          step: 1,
+          message: { content: [{ type: 'text', text: 'final answer' }] },
+          usage: { inputTokens: 4, outputTokens: 5, cacheReadTokens: 6 },
+        },
+      })
+      harness.emit(harness.session, {
+        type: 'assistant/chunk', seq: 6, time: 6,
+        data: {
+          turn: 1,
+          step: 2,
+          chunk: { type: 'usage', usage: { inputTokens: 1, outputTokens: 2, cacheWriteTokens: 7, reasoningTokens: 2 } },
+        },
+      })
+      harness.emit(harness.session, {
+        type: 'assistant/message', seq: 7, time: 7,
+        data: { turn: 1, step: 2, message: { content: [{ type: 'tool-call' }] } },
+      })
+      harness.emit(harness.foreignSession, {
+        type: 'assistant/message', seq: 8, time: 8, data: { message: { content: [] } },
+      })
+    })
+
+    await expect(runFixtureTurn(harness.ctx, {
+      task: 'prove the fixture',
+      onEvent: (_sessionId, current) => { observed.push(current) },
+    })).resolves.toEqual({
+      type: 'result',
+      sessionId: 'fixture-session',
+      output: 'final answer',
+      usage: {
+        inputTokens: 5,
+        outputTokens: 7,
+        cacheReadTokens: 6,
+        cacheWriteTokens: 7,
+        reasoningTokens: 2,
+      },
+    })
+    expect(observed.map(current => current.seq)).toEqual([2, 3, 4, 5, 6, 7])
+    expect(harness.whenIdle).toHaveBeenCalledTimes(2)
+    expect(harness.flush).toHaveBeenCalledWith(harness.session)
+    expect(harness.disposeListener).toHaveBeenCalledOnce()
+  })
+
+  it('omits usage when the interval records none', async () => {
+    const harness = turnHarness()
+    harness.setFollowup((message) => {
+      harness.emit(harness.session, {
+        type: 'agent/inbox/spliced', seq: 0, time: 0, data: { inserted: [message] },
+      })
+    })
+
+    await expect(runFixtureTurn(harness.ctx, { task: 'no model step' })).resolves.toEqual({
+      type: 'result',
+      sessionId: 'fixture-session',
+      output: '',
+    })
+  })
+
+  it('always removes its listener when the turn fails', async () => {
+    const harness = turnHarness()
+    harness.whenIdle.mockResolvedValueOnce(undefined).mockRejectedValueOnce(new Error('turn failed'))
+
+    await expect(runFixtureTurn(harness.ctx, { task: 'fail' })).rejects.toThrow('turn failed')
+    expect(harness.disposeListener).toHaveBeenCalledOnce()
+    expect(harness.flush).not.toHaveBeenCalled()
+  })
+})
diff --git a/packages/support/loader-smoke/tsconfig.json b/packages/support/loader-smoke/tsconfig.json
index d970a00263..52ec32ca67 100644
--- a/packages/support/loader-smoke/tsconfig.json
+++ b/packages/support/loader-smoke/tsconfig.json
@@ -8,6 +8,15 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
     {
       "path": "../../support/invariants"
     }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9957263083..8af4853536 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -376,6 +376,9 @@ importers:
       '@deepseek-ai/dsh-llm-replay':
         specifier: workspace:*
         version: link:../packages/support/llm-replay
+      '@deepseek-ai/dsh-loader-smoke':
+        specifier: workspace:*
+        version: link:../packages/support/loader-smoke
       '@deepseek-ai/dsh-lsp':
         specifier: workspace:*
         version: link:../packages/lsp/lsp
@@ -5936,9 +5939,18 @@ importers:
         specifier: ^4.22.4
         version: 4.22.4
     devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
       cordis:
         specifier: ^4.0.0-rc.6
         version: link:../../../vendor/cordis
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 429beb5480..67af38455e 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -124,7 +124,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/support/acp-snapshot': { kind: 'none', reason: 'The test harness observes and normalizes transcripts without changing live requests.' },
   'packages/support/agent-loop-testkit': { kind: 'none', reason: 'The test helper mounts services but neither drives nor modifies model requests.' },
   'packages/support/invariants': { kind: 'none', reason: 'The observer validates requests but never rewrites their context.' },
-  'packages/support/loader-smoke': { kind: 'none', reason: 'The test harness observes child-process streams without changing live requests.' },
+  'packages/support/loader-smoke': { kind: 'none', reason: 'The test harness submits an ordinary user task but delegates prompt and tool composition to the loaded tree.' },
   'packages/support/llm-mock-server': { kind: 'none', reason: 'The test server substitutes provider wire behavior without invoking a real model.' },
   'packages/support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
   'packages/api/gateway': { kind: 'none', reason: 'Remote dispatch infrastructure; invoked business methods own any model-visible effect.' },

From b3a53c1e512600f6a46adf8228de191bf6df9567 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 15:14:29 +0800
Subject: [PATCH 227/516] fix(client): address sidebar activity review

---
 ...07-27-web-subagent-conversations.i18n.yaml |  4 +--
 .../2026-07-27-web-subagent-conversations.md  |  2 +-
 ...026-07-27-web-subagent-conversations.zh.md |  2 +-
 .../src/client/SubagentCatalogAction.tsx      |  7 +++--
 .../tests/conversation-ui.spec.tsx            | 11 ++++---
 packages/client/ui-workspace/README.i18n.yaml |  4 +--
 packages/client/ui-workspace/README.md        |  2 +-
 packages/client/ui-workspace/README.zh.md     |  2 +-
 .../ui-workspace/src/client/rows/Rows.tsx     | 11 ++++---
 .../client/ui-workspace/tests/rows.spec.tsx   | 30 ++++++++++++++++++-
 10 files changed, 56 insertions(+), 19 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index ac7fc12150..f93d3a4a34 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: 60717365244ff3ca3ebc4a400b15bfc81062212c
-2026-07-27-web-subagent-conversations.zh.md: 217ed44249c0d1beb731e24e52054f200fae4b9b
+2026-07-27-web-subagent-conversations.md: 1b9bbfbc566e77932629af9f1e0714819973f111
+2026-07-27-web-subagent-conversations.zh.md: a9ed0e20f3617f7f5f8ae9d0f2d77c7ba8aef9ea
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index 6071736524..1b9bbfbc56 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -37,7 +37,7 @@ The Figma [subagent list](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Ha
 
 ## Product contract
 
-The header action is absent only when a complete empty direct-catalog response agrees with the session-summary projection that no subagent descendants are known. Its trigger counts every known session-summary descendant reached through an uninterrupted `origin: 'subagent'` lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. Because ordinary sidebar rows hide subagent-origin sessions, the Workspace browser indexes the same uninterrupted lineage onto each visible ordinary row: any running descendant supplies its blue activity indicator and exact count in hover and assistive text without describing an idle parent as running. An ordinary fork starts a separate aggregation subtree. Parent running and pending interaction remain distinct primary statuses; descendant activity becomes a second hover and assistive status when either is present. Every healthy direct-catalog row carries a read-time `hasChildren` hint derived only from direct lineage headers with durable `origin: 'subagent'`; normal healthy and diagnostic subagent candidates carry that marker, while ordinary forks do not. This lookahead reads no descendant event log, and the descriptor-backed catalog loaded after disclosure remains authoritative. When summaries establish descendants before that catalog exists or after a stale empty response, the action stays visible and exposes only disabled loading rows until opening it refreshes the catalog; summary-only rows never grant navigation. The UI omits disclosure for a known leaf before interaction; the hint does not promise that the child will remain a leaf. While an expanded direct catalog is loading, known lineage reserves one disabled loading row per direct descendant without recursively fetching descendant catalogs. The tree then presents continuable and one-shot rows, falling back to the session id when an optional one-shot label is absent. Corrupt, unsupported, and unavailable candidates remain visible as disabled diagnostic rows.
+The header action is absent only when a complete empty direct-catalog response agrees with the session-summary projection that no subagent descendants are known. Its trigger counts every known session-summary descendant reached through an uninterrupted `origin: 'subagent'` lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. Because ordinary sidebar rows hide subagent-origin sessions, the Workspace browser indexes the same uninterrupted lineage onto each visible ordinary row: any running descendant supplies its blue activity indicator and exact count in hover and assistive text without describing an idle parent as running. An ordinary fork starts a separate aggregation subtree. Pending interaction outranks parent running; either remains primary while descendant activity becomes a second hover and assistive status. With neither present, descendant activity outranks an unviewed completion reminder, which returns after the last running descendant stops. Every healthy direct-catalog row carries a read-time `hasChildren` hint derived only from direct lineage headers with durable `origin: 'subagent'`; normal healthy and diagnostic subagent candidates carry that marker, while ordinary forks do not. This lookahead reads no descendant event log, and the descriptor-backed catalog loaded after disclosure remains authoritative. When summaries establish descendants before that catalog exists or after a stale empty response, the action stays visible and exposes only disabled loading rows until opening it refreshes the catalog; summary-only rows never grant navigation. The UI omits disclosure for a known leaf before interaction; the hint does not promise that the child will remain a leaf. While an expanded direct catalog is loading, known lineage reserves one disabled loading row per direct descendant without recursively fetching descendant catalogs. The tree then presents continuable and one-shot rows, falling back to the session id when an optional one-shot label is absent. Corrupt, unsupported, and unavailable candidates remain visible as disabled diagnostic rows.
 
 `running` means the exact child Agent driver is draining work at the Host sampling boundary; `inactive` means that driver is idle or absent. The UI does not translate either value into success, failure, cancellation, completeness, or resumability. `subagent.list` supplies the current driver-status baseline, `host/session-status` updates known activity in place, request-local replay prevents an older in-flight list response from overwriting a newer transition, and `host/session-removed` returns a known row to `inactive`; reconnect reads a fresh baseline. A `host/session-added` frame for a direct subagent immediately flips any loaded parent row to `hasChildren: true`, and that positive hint survives an older in-flight catalog response; membership, labels, mode, diagnostics, and the authoritative snapshot still require a debounced `subagent.list` refresh while the affected branch is open. A prompt response remains delivery-time authority.
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index 217ed44249..a9ed0e20f3 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -37,7 +37,7 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 ## 产品契约
 
-只有当完整的直接目录空响应与会话摘要投影相符，二者均表明没有已知的 subagent 后代时，才不显示页头操作。其触发器会统计经不间断的 `origin: 'subagent'` 谱系可达的每个已知会话摘要后代，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。由于普通侧边栏行会隐藏 origin 为 subagent 的会话，Workspace 浏览器会在每个可见的普通行上索引同一条不间断谱系：任何运行中的后代都会让该行显示蓝色活动指示器，并在悬停与无障碍文本中给出确切数量，同时不会把空闲 parent 描述为正在运行。普通 fork 会开启单独的聚合子树。parent 的运行中状态与待处理交互仍是彼此不同的主要状态；只要其中任一存在，后代活动就成为悬停与无障碍状态中的第二项。每个健康的直接目录行都携带读取时的 `hasChildren` 提示，该值只根据持久化 `origin: 'subagent'` 的直接谱系 header 派生；正常的健康与 diagnostic subagent 候选都会携带该标记，而普通 fork 不会。该预查不读取任何后代事件日志，展开后仍以描述符支撑的目录为权威依据。当摘要在该目录尚不存在时或在一次陈旧的空响应后确认已有后代时，该操作会保持可见，并且在打开它以刷新目录之前仅显示禁用的加载行；仅由摘要支撑的行绝不会提供导航能力。UI 会在交互前就省略已知叶子节点的展开控件；该提示不承诺 child 会一直是叶子。已展开的直接目录加载期间，已知谱系会为每个直接后代预留一行禁用的加载行，而不会递归获取后代目录。随后树会呈现可继续与 one-shot 行；one-shot 的可选 label 缺失时，回退到其会话 id。损坏、不受支持或不可用的候选仍以禁用的 diagnostic 行显示。
+只有当完整的直接目录空响应与会话摘要投影相符，二者均表明没有已知的 subagent 后代时，才不显示页头操作。其触发器会统计经不间断的 `origin: 'subagent'` 谱系可达的每个已知会话摘要后代，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。由于普通侧边栏行会隐藏 origin 为 subagent 的会话，Workspace 浏览器会在每个可见的普通行上索引同一条不间断谱系：任何运行中的后代都会让该行显示蓝色活动指示器，并在悬停与无障碍文本中给出确切数量，同时不会把空闲 parent 描述为正在运行。普通 fork 会开启单独的聚合子树。待处理交互优先于 parent 的运行中状态；二者无论哪一项存在都会保持为主要状态，而后代活动则成为悬停与无障碍状态中的第二项。两者均不存在时，后代活动优先于未查看的完成提醒；最后一个运行中的后代停止后，该提醒会恢复。每个健康的直接目录行都携带读取时的 `hasChildren` 提示，该值只根据持久化 `origin: 'subagent'` 的直接谱系 header 派生；正常的健康与 diagnostic subagent 候选都会携带该标记，而普通 fork 不会。该预查不读取任何后代事件日志，展开后仍以描述符支撑的目录为权威依据。当摘要在该目录尚不存在时或在一次陈旧的空响应后确认已有后代时，该操作会保持可见，并且在打开它以刷新目录之前仅显示禁用的加载行；仅由摘要支撑的行绝不会提供导航能力。UI 会在交互前就省略已知叶子节点的展开控件；该提示不承诺 child 会一直是叶子。已展开的直接目录加载期间，已知谱系会为每个直接后代预留一行禁用的加载行，而不会递归获取后代目录。随后树会呈现可继续与 one-shot 行；one-shot 的可选 label 缺失时，回退到其会话 id。损坏、不受支持或不可用的候选仍以禁用的 diagnostic 行显示。
 
 `running` 表示在 Host 采样边界，确切 child Agent driver 正在处理工作；`inactive` 表示该 driver 空闲或不存在。UI 不会把任一值解释为成功、失败、取消、完成状态或可恢复性。`subagent.list` 提供当前 driver 状态基线，`host/session-status` 会就地更新已知活动状态，请求内回放会阻止更早发起但尚未完成的列表响应覆盖较新的状态转换，`host/session-removed` 则会使已知行恢复为 `inactive`；重连时会读取新的基线。直接 subagent 的 `host/session-added` 帧会立即把任何已加载的 parent 行翻转为 `hasChildren: true`，并使这项正向提示不被更早发起但尚未完成的目录响应覆盖；受影响分支打开期间，成员、label、mode、diagnostic 与权威快照仍需要通过去抖动的 `subagent.list` 刷新来更新。消息投递时仍以提示词响应为权威依据。
 
diff --git a/packages/client/ui-subagent/src/client/SubagentCatalogAction.tsx b/packages/client/ui-subagent/src/client/SubagentCatalogAction.tsx
index 50850f0b98..3a6ace14a5 100644
--- a/packages/client/ui-subagent/src/client/SubagentCatalogAction.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentCatalogAction.tsx
@@ -433,7 +433,7 @@ export function SubagentCatalogAction({
   // the already-visible direct rows during that short bootstrap window.
   const descendantCount = Math.max(healthy.length, descendants.count)
   const totalCountKey = descendantCount === 1 ? 'count.total.one' : 'count.total.other'
-  const runningCountKey = descendantCount === 1 ? 'count.running.one' : 'count.running.other'
+  const runningCountKey = descendants.runningCount === 1 ? 'count.running.one' : 'count.running.other'
   // Session summaries can announce membership before the descriptor-backed catalog catches up.
   // Keep that entry point visible through disabled loading rows; only catalog rows are navigable.
   const summaryBackedLoading = descendants.count > 0
@@ -564,7 +564,10 @@ export function SubagentCatalogAction({
         className={css.trigger}
         aria-haspopup="tree"
         aria-expanded={open}
-        aria-label={t(descendants.runningCount > 0 ? runningCountKey : totalCountKey, { count: descendantCount })}
+        aria-label={t(
+          descendants.runningCount > 0 ? runningCountKey : totalCountKey,
+          { count: descendants.runningCount > 0 ? descendants.runningCount : descendantCount },
+        )}
         onClick={() => { changeOpen(!open) }}
         onKeyDown={(event) => {
           if (event.key !== 'ArrowDown') return
diff --git a/packages/client/ui-subagent/tests/conversation-ui.spec.tsx b/packages/client/ui-subagent/tests/conversation-ui.spec.tsx
index e0610d3379..c300e423e6 100644
--- a/packages/client/ui-subagent/tests/conversation-ui.spec.tsx
+++ b/packages/client/ui-subagent/tests/conversation-ui.spec.tsx
@@ -108,7 +108,7 @@ describe('SubagentCatalogAction', () => {
     }
     const view = render(<SubagentCatalogAction {...props(catalog(), {}, summaries)} />)
 
-    const trigger = screen.getByRole('button', { name: '3 个子代理，正在运行' })
+    const trigger = screen.getByRole('button', { name: '1 个子代理，正在运行' })
     expect(trigger.querySelector('[data-state="ongoing"]')).not.toBeNull()
 
     view.rerender(<SubagentCatalogAction {...props(catalog(), {}, {
@@ -322,7 +322,9 @@ describe('SubagentCatalogAction', () => {
     })) as Record<SessionId, SessionSummary>
     const input = props(catalog({ entries }), {}, summaries)
     render(<SubagentCatalogAction {...input} />)
-    fireEvent.click(screen.getByRole('button', { name: /9 个子代理/ }))
+    const trigger = screen.getByRole('button', { name: '1 个子代理，正在运行' })
+    expect(within(trigger).getByText('9 个子代理')).toBeTruthy()
+    fireEvent.click(trigger)
 
     const runningRow = screen.getByRole('treeitem', { name: /running.*4\.6K tok · 1分10秒/ })
     const runningMetrics = within(runningRow)
@@ -506,7 +508,8 @@ describe('SubagentCatalogAction', () => {
     const absent = props(undefined, {}, summaries)
     const view = render(<SubagentCatalogAction {...absent} />)
 
-    const trigger = screen.getByRole('button', { name: '2 个子代理，正在运行' })
+    const trigger = screen.getByRole('button', { name: '1 个子代理，正在运行' })
+    expect(within(trigger).getByText('2 个子代理')).toBeTruthy()
     fireEvent.click(trigger)
     expect(absent.setCatalogOpen).toHaveBeenCalledWith(PARENT, true)
     expect(screen.getAllByRole('treeitem', { name: '正在加载子代理' })).toHaveLength(2)
@@ -514,7 +517,7 @@ describe('SubagentCatalogAction', () => {
 
     const staleEmpty = props(catalog({ entries: [] }), {}, summaries)
     view.rerender(<SubagentCatalogAction {...staleEmpty} />)
-    expect(screen.getByRole('button', { name: '2 个子代理，正在运行' })).toBeTruthy()
+    expect(screen.getByRole('button', { name: '1 个子代理，正在运行' })).toBeTruthy()
     expect(screen.getAllByRole('treeitem', { name: '正在加载子代理' })).toHaveLength(2)
     expect(staleEmpty.openChild).not.toHaveBeenCalled()
   })
diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml
index c5cfc89ea5..047513c346 100644
--- a/packages/client/ui-workspace/README.i18n.yaml
+++ b/packages/client/ui-workspace/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/client/ui-workspace/README.md
-README.md: b2baea049c30f46c3194009e71c70b38973dc526
-README.zh.md: cc50ba3691db10a533337b0e99689fba72a679ca
+README.md: 1ec07bd41e72bb5a26b2cfc3bf90e57e7d92db08
+README.zh.md: 18d9e356a9e5deb38624f377d41b2fc8bc677294
diff --git a/packages/client/ui-workspace/README.md b/packages/client/ui-workspace/README.md
index b2baea049c..1ec07bd41e 100644
--- a/packages/client/ui-workspace/README.md
+++ b/packages/client/ui-workspace/README.md
@@ -16,7 +16,7 @@ Session rows render the runtime's live `pendingInteraction` classification: appr
 
 Both target slots are declared by other plugins, so `apply` uses `slots.inject()` to register for each declaration lifetime and re-register after a declaring slot is restored.
 
-The shared sidebar projection hides rows whose durable Session summary has `origin: 'subagent'`; users enter those conversations through the selected parent's subagent header catalog. Each visible ordinary row inherits the blue activity indicator while any descendant reached through uninterrupted subagent-origin lineage is running, and its hover and assistive text report the exact running-descendant count without describing an idle parent as running. Ordinary forks remain visible and terminate this aggregation because lineage alone does not set their origin. Pending user interaction remains the primary row marker while descendant activity stays available as a separate hover and assistive status. The runtime keeps hidden rows available for conversation, title, and addressed transport state.
+The shared sidebar projection hides rows whose durable Session summary has `origin: 'subagent'`; users enter those conversations through the selected parent's subagent header catalog. Each visible ordinary row inherits the blue activity indicator while any descendant reached through uninterrupted subagent-origin lineage is running, and its hover and assistive text report the exact running-descendant count without describing an idle parent as running. Ordinary forks remain visible and terminate this aggregation because lineage alone does not set their origin. Pending user interaction outranks the session's own running state, and either remains the primary row status while descendant activity stays available as a separate hover and assistive status. With neither present, descendant activity outranks the green unviewed-completion reminder; the reminder returns once no descendant is running. The runtime keeps hidden rows available for conversation, title, and addressed transport state.
 
 ## Model Experience
 
diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md
index cc50ba3691..18d9e356a9 100644
--- a/packages/client/ui-workspace/README.zh.md
+++ b/packages/client/ui-workspace/README.zh.md
@@ -16,7 +16,7 @@ Session 行渲染运行时的实时 `pendingInteraction` 分类：审批显示**
 
 两个目标 slot 都由其他插件声明，因此 `apply` 使用 `slots.inject()` 在各自的声明生命周期内完成注册，并在目标 slot 的声明恢复后重新注册。
 
-共享侧边栏投影会隐藏持久化 Session 摘要中带有 `origin: 'subagent'` 的行；用户从所选 parent 的 subagent 页头目录进入这些对话。每个可见的普通行都会在经不间断的 subagent 谱系可达的任一后代运行时继承蓝色活动指示器；其悬停与无障碍文本会报告确切的运行中后代数量，同时不会把空闲 parent 描述为正在运行。普通 fork 仍然可见，并会终止此聚合，因为仅有谱系不会设置该 origin。待处理的用户交互仍是主要行标记，而后代活动会作为独立的悬停与无障碍状态保留。运行时仍保留隐藏行，供对话、标题与已寻址传输状态使用。
+共享侧边栏投影会隐藏持久化 Session 摘要中带有 `origin: 'subagent'` 的行；用户从所选 parent 的 subagent 页头目录进入这些对话。每个可见的普通行都会在经不间断的 subagent 谱系可达的任一后代运行时继承蓝色活动指示器；其悬停与无障碍文本会报告确切的运行中后代数量，同时不会把空闲 parent 描述为正在运行。普通 fork 仍然可见，并会终止此聚合，因为仅有谱系不会设置该 origin。待处理的用户交互优先于会话自身的运行中状态，二者无论哪一项存在都会保持为行的主要状态，而后代活动仍作为独立的悬停与无障碍状态保留。两者均不存在时，后代活动优先于绿色的未查看完成提醒；最后一个运行中的后代停止后，该提醒会重新出现。运行时仍保留隐藏行，供对话、标题与已寻址传输状态使用。
 
 ## 模型体验
 
diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx
index 3d3b40403d..40ef1e8883 100644
--- a/packages/client/ui-workspace/src/client/rows/Rows.tsx
+++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx
@@ -176,7 +176,10 @@ interface SessionStatus {
   label: string
 }
 
-/** Session status presentation; pending user interaction remains primary. */
+/**
+ * Session status presentation; pending interaction is primary and live activity
+ * outranks completion reminders.
+ */
 function sessionStatuses(
   node: Pick<SessionNode, 'pendingInteraction' | 'running' | 'runningSubagentCount' | 'completed'>,
   t: RowTranslate,
@@ -386,9 +389,9 @@ export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork
           drag.drop(rowHalf(e))
         }}
     >
-      {/* Pending interactions and running outrank the idle state; a
-          finished-but-unviewed session shows the green done reminder dot
-          (cleared by opening the session). */}
+      {/* Pending interaction and own or descendant activity outrank the
+          finished-but-unviewed reminder, which returns after activity stops
+          and is cleared by opening the session. */}
       <span className={css.slot}>
         {(primaryStatus.state !== 'done' || row.completed) && (
           <>
diff --git a/packages/client/ui-workspace/tests/rows.spec.tsx b/packages/client/ui-workspace/tests/rows.spec.tsx
index 46eb8b2dba..7e0971cf72 100644
--- a/packages/client/ui-workspace/tests/rows.spec.tsx
+++ b/packages/client/ui-workspace/tests/rows.spec.tsx
@@ -133,7 +133,7 @@ describe('workspace browser rows', () => {
     expect(onOpen).toHaveBeenCalledWith(node.id)
   })
 
-  it('shows the green done dot only on a finished, unviewed session (running wins the slot)', () => {
+  it('shows the green done dot only on a finished, unviewed session (live activity wins the slot)', () => {
     const renderRow = (over: Partial<SessionNode>) => render(
       <SessionNodeItem
         node={{
@@ -158,6 +158,11 @@ describe('workspace browser rows', () => {
     const running = renderRow({ completed: true, running: true })
     expect(running.container.querySelector('[data-state="ongoing"]')).not.toBeNull()
     expect(running.container.querySelector('[data-state="done"]')).toBeNull()
+    running.unmount()
+    // Descendant activity also wins until the last running descendant stops.
+    const delegated = renderRow({ completed: true, runningSubagentCount: 1 })
+    expect(delegated.container.querySelector('[data-state="ongoing"]')).not.toBeNull()
+    expect(delegated.container.querySelector('[data-state="done"]')).toBeNull()
   })
 
   it('shows descendant activity without describing an idle parent as running', () => {
@@ -182,6 +187,29 @@ describe('workspace browser rows', () => {
     }
   })
 
+  it('keeps descendant activity secondary while the parent is running', () => {
+    vi.useFakeTimers()
+    try {
+      const node: SessionNode = {
+        id: sid('owner'), title: 'Delegating', blank: false, running: true,
+        runningSubagentCount: 1, completed: false, updatedAt: 0,
+      }
+      render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
+      const row = screen.getByRole('treeitem')
+      expect(row.querySelectorAll('[data-state="ongoing"]')).toHaveLength(1)
+      expect(screen.getByText('进行中')).toBeTruthy()
+      expect(screen.getByText('1 个子代理运行中')).toBeTruthy()
+
+      fireEvent.pointerEnter(row.parentElement as HTMLElement)
+      act(() => { vi.advanceTimersByTime(500) })
+      expect(screen.getAllByText('进行中')).toHaveLength(2)
+      expect(screen.getAllByText('1 个子代理运行中')).toHaveLength(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it('keeps child activity as a secondary status while user attention is primary', () => {
     const node: SessionNode = {
       id: sid('owner'), title: 'Needs input', blank: false, pendingInteraction: 'question',

From 90f90380619122ee03206ffa58066952f730035b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:14:59 +0800
Subject: [PATCH 228/516] docs(graph): refresh loader-smoke dependencies

---
 docs/module-graph.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index 05e2bd0b5d..c268ad317f 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -299,7 +299,6 @@ flowchart TD
   pkg_timeout --> pkg_invariants
   pkg_scope --> pkg_invariants
   pkg_llm_mock_server --> pkg_invariants
-  pkg_loader_smoke --> pkg_invariants
   pkg_base --> pkg_invariants
   pkg_client_modules --> pkg_invariants
   pkg_client_schema_form --> pkg_invariants
@@ -558,6 +557,10 @@ flowchart TD
   pkg_llm_replay --> pkg_invariants
   pkg_llm_replay --> pkg_llm
   pkg_llm_replay --> pkg_session
+  pkg_loader_smoke --> pkg_agent
+  pkg_loader_smoke --> pkg_invariants
+  pkg_loader_smoke --> pkg_llm
+  pkg_loader_smoke --> pkg_session
   pkg_commands --> pkg_agent
   pkg_commands --> pkg_brand
   pkg_commands --> pkg_invariants
@@ -1158,7 +1161,6 @@ flowchart TD
 | [`timeout`](../packages/util/timeout) | `util` | [`invariants`](../packages/support/invariants) |
 | [`scope`](../packages/core/scope) | `core` | [`invariants`](../packages/support/invariants) |
 | [`llm-mock-server`](../packages/support/llm-mock-server) | `support` | [`invariants`](../packages/support/invariants) |
-| [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`invariants`](../packages/support/invariants) |
 | [`base`](../packages/bundle/base) | `bundle` | [`invariants`](../packages/support/invariants) |
 | [`client-modules`](../packages/client/modules) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-schema-form`](../packages/client/schema-form) | `client` | [`invariants`](../packages/support/invariants) |
@@ -1242,6 +1244,7 @@ flowchart TD
 | [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | [`session-title`](../packages/session-title/session-title) | `session-title` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`commands`](../packages/ui/commands) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
 | [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |

From ebd3a87834fd163109ca9f1dd9e07478dac55d6a Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 15:24:50 +0800
Subject: [PATCH 229/516] fix(web): stabilize compact card snapshots

---
 apps/web/tests/scaffold.ts                    |  8 ++++++--
 .../seeded-history/command-row.expected.md    |  4 +---
 .../snapshots/seeded-history/ui.expected.md   |  4 +---
 .../client/ui-conversation/README.i18n.yaml   |  4 ++--
 packages/client/ui-conversation/README.md     |  2 +-
 packages/client/ui-conversation/README.zh.md  |  2 +-
 .../src/client/chat/ChatView.tsx              |  2 +-
 .../src/client/chat/CompactionCommandCard.tsx |  4 ++--
 .../src/client/chat/CompactionItem.tsx        |  2 +-
 .../src/client/chat/chat-flow.ts              |  1 -
 .../ui-conversation/tests/chat-view.spec.tsx  | 19 +++++++++++++++++++
 packages/ui/commands/tests/invariant.spec.ts  |  2 +-
 12 files changed, 36 insertions(+), 18 deletions(-)

diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 11ba23a99f..6a8ff82ff1 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -620,8 +620,9 @@ export async function seedSession(scaffold: WebScaffold, fixtureText: string, id
 }
 
 /**
- * Normalize an aria snapshot: uuid, cwd, workspace-basename, duration, and
- * decode-throughput volatility collapse to stable tokens.
+ * Normalize an aria snapshot: uuid, cwd, workspace-basename, duration,
+ * decode-throughput, and path-sensitive compaction estimates collapse to
+ * stable tokens.
  *
  * Throughput needs a token for the same reason durations do, and no fixture
  * can supply one: the figure divides a replayed step's output tokens by the
@@ -648,6 +649,9 @@ function normalizeAria(snapshot: string, workspaceCwd: string): string {
       duration => duration.startsWith('约') ? duration : '{{duration}}',
     )
     .replace(/\d+(?:\.\d+)?(?= tok\/s(?!\w))/g, '{{throughput}}')
+    // Seeded compaction prices realized file paths, whose length differs
+    // between local worktrees and CI scratch directories.
+    .replace(/(Compacted \d+ history items \(~)\d+( tokens\))/g, '$1{{tokens}}$2')
     // Message IconActions clocks widen by calendar day/year; collapse every
     // shape so goldens stay stable across midnight and year boundaries.
     .replace(/\d{4}年\d{1,2}月\d{1,2}日 \d{2}:\d{2}/g, '{{clock}}')
diff --git a/apps/web/tests/snapshots/seeded-history/command-row.expected.md b/apps/web/tests/snapshots/seeded-history/command-row.expected.md
index 21b9cefeec..3aa9e2d738 100644
--- a/apps/web/tests/snapshots/seeded-history/command-row.expected.md
+++ b/apps/web/tests/snapshots/seeded-history/command-row.expected.md
@@ -31,9 +31,7 @@
 - button "Branch into a new conversation":
   - img
 - text: 7/25 {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
-- button "compact Compacted 5 history items (~247 tokens)":
-  - img
-  - text: compact Compacted 5 history items (~247 tokens)
+- button "compact Compacted 5 history items (~{{tokens}} tokens)"
 - button "Context injection AGENTS.md":
   - img
   - img
diff --git a/apps/web/tests/snapshots/seeded-history/ui.expected.md b/apps/web/tests/snapshots/seeded-history/ui.expected.md
index 2502d90f90..a30ae29e1e 100644
--- a/apps/web/tests/snapshots/seeded-history/ui.expected.md
+++ b/apps/web/tests/snapshots/seeded-history/ui.expected.md
@@ -31,9 +31,7 @@
 - button "Branch into a new conversation":
   - img
 - text: 7/25 {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s
-- button "compact Compacted 5 history items (~247 tokens)":
-  - img
-  - text: compact Compacted 5 history items (~247 tokens)
+- button "compact Compacted 5 history items (~{{tokens}} tokens)"
 - button "Context injection AGENTS.md":
   - img
   - img
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index d29623d0f2..db7db5db5f 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 985c78e97a8c7f46451252e67095c91e990aa694
-README.zh.md: 36a2f7a13c3f60692f9547ccf5a51ad6356d26d8
+README.md: 6b541b840ed67ee6fd735a0643dde8c60f1ec22d
+README.zh.md: 01692c395cdb0f50e0fd41ab92f51d9e3ceecb4f
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 985c78e97a..6b541b840e 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, an animated left-to-right gradient `Deep diving...` turn status, per-tool row slot with a bash sample registrant and the todo row), composer dock (session stats sticky with the input), input dock (hairline-separated queue rows plus the todo plan strip), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares).
 
-Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key, showing the replaced-item and estimated-token counts and disclosing the summary on click. A completed checkpoint keeps the context-compaction icon at rest and replaces it with the collapsed or expanded disclosure only on hover or keyboard focus. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when summary provenance is outside the loaded window, the checkpoint remains visible but non-expandable.
+Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Every completed marker with structured summary provenance shows the replaced-item and estimated-token counts and discloses the summary on click. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key. A completed checkpoint keeps the context-compaction icon at rest and replaces it with the collapsed or expanded disclosure only on hover or keyboard focus. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when summary provenance is outside the loaded window, the checkpoint remains visible but non-expandable.
 
 The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 36a2f7a13c..01692c395c 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -4,7 +4,7 @@
 
 会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、带从左到右动态渐变的 `Deep diving...` 轮次状态、逐工具行 slot 及一个 bash 示例注册方与 todo 行）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（带发丝分界线的队列行加 todo 计划条）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。
 
-压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行，显示被替换条目数量和估算 token 数量，并可点击展开摘要。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。
+压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。每个具备结构化摘要溯源的完成标记都会显示被替换条目数量和估算 token 数量，并可点击展开摘要。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index b15bc20cdb..18fba234de 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -275,7 +275,7 @@ const CommandRow = memo(function CommandRow({ renderSlot, node, compaction, t }:
   t: ChatViewSlotProps['t']
 }) {
   const owner = useMemo(() => ({ node, ...compaction === undefined ? {} : { compaction } }), [compaction, node])
-  const fallback = node.name === 'compact' || compaction !== undefined
+  const fallback = node.name === 'compact'
     ? <CompactionCommandCard {...owner} t={t} />
     : <GenericCommandCard {...owner} t={t} />
   return (
diff --git a/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
index d2401e49c6..8012834541 100644
--- a/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
@@ -19,7 +19,7 @@ export function CompactionCommandCard({ node, compaction, t }: CompactionCommand
     return (
       <CompactionItem
         node={compaction}
-        title={node.name ?? 'compact'}
+        title="compact"
         fallbackSummary={node.outcome?.text ?? null}
         t={t}
       />
@@ -31,7 +31,7 @@ export function CompactionCommandCard({ node, compaction, t }: CompactionCommand
       t={t}
       variant="others"
       icon={<IconApiOutline14 size={14} />}
-      title={node.name ?? 'compact'}
+      title="compact"
       summary={t('message.compaction.running')}
       body={null}
       state="running"
diff --git a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
index 5e5f0c87b7..5bd5a081cf 100644
--- a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
@@ -21,7 +21,7 @@ interface CompactionItemProps {
   node: CompactionSummaryNode
   /** Optional command title for a manual compaction folded into this marker. */
   title?: string
-  /** Command settlement text used only when the summary provenance page is absent. */
+  /** Command settlement text used when structured compaction counts are unavailable. */
   fallbackSummary?: string | null
   /** The owning view's locale seat. */
   t: ChatViewSlotProps['t']
diff --git a/packages/client/ui-conversation/src/client/chat/chat-flow.ts b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
index 22146ddb31..a9b12cbe2d 100644
--- a/packages/client/ui-conversation/src/client/chat/chat-flow.ts
+++ b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
@@ -155,7 +155,6 @@ export function deriveChatFlow(nodes: readonly ConversationNode[]): ChatFlowItem
   for (const node of nodes) {
     if (rendersNothing(node)) continue
     if (node.kind === 'command' && pairs.byCommandId.has(node.commandId)) {
-      group = null
       continue
     }
     if (node.kind === 'compaction') {
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index b16a0b9317..f42aed6731 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -249,6 +249,25 @@ describe('chat-flow derivation', () => {
     })
   })
 
+  it('does not split adjacent tool results around a folded /compact command', () => {
+    const folded = command({
+      seq: 2,
+      commandId: 'cmd-compact' as CommandNode['commandId'],
+      name: 'compact',
+      outcome: { kind: 'success', sourceEventSeq: 4 },
+    })
+    const items = deriveChatFlow([
+      toolResult(1, 'a'),
+      folded,
+      toolResult(3, 'b'),
+      compaction({ seq: 5, summaryEventSeq: 4 }),
+    ])
+    expect(flowKeys(items)).toBe('g1|ccmd-compact')
+    expect(
+      items[0]?.kind === 'tool-group' && items[0].results.map(result => result.callId),
+    ).toEqual(['a', 'b'])
+  })
+
   it('keeps automatic, unlinked, and ambiguously linked compactions as separate rows', () => {
     const automatic = compaction({ seq: 2, summaryEventSeq: 1 })
     expect(flowKeys(deriveChatFlow([automatic]))).toBe('n2')
diff --git a/packages/ui/commands/tests/invariant.spec.ts b/packages/ui/commands/tests/invariant.spec.ts
index 8772a3b71e..556be701e8 100644
--- a/packages/ui/commands/tests/invariant.spec.ts
+++ b/packages/ui/commands/tests/invariant.spec.ts
@@ -38,7 +38,7 @@ describe('command lifecycle invariants', () => {
     }).not.toThrow()
   })
 
-  it.each([-1, 1.5, 1])('rejects invalid or command-owned sourceEventSeq %s', async (sourceEventSeq) => {
+  it.each([-1, 1.5, 1])('rejects invalid or non-prior sourceEventSeq %s', async (sourceEventSeq) => {
     const { session } = await mount()
     appendRun(session, 'cmd-invalid')
 

From 8dcfe5c4065e4f99511c3886cce68d147de8efbb Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 02:16:17 +0800
Subject: [PATCH 230/516] fix(replay): mark local compaction calls

---
 ...ction-summary-prefix-cache-reuse.i18n.yaml |  4 +-
 ...1-compaction-summary-prefix-cache-reuse.md |  4 +-
 ...ompaction-summary-prefix-cache-reuse.zh.md |  4 +-
 ...06-18-compaction-capability-seam.i18n.yaml |  4 +-
 .../2026-06-18-compaction-capability-seam.md  |  6 +-
 ...026-06-18-compaction-capability-seam.zh.md |  6 +-
 .../2026-06-19-acp-snapshot-tests.i18n.yaml   |  4 +-
 .../testing/2026-06-19-acp-snapshot-tests.md  |  7 ++-
 .../2026-06-19-acp-snapshot-tests.zh.md       |  7 ++-
 docs/config-catalog.md                        |  2 +-
 .../core-data-structures/compaction.i18n.yaml |  4 +-
 docs/core-data-structures/compaction.md       |  2 +-
 docs/core-data-structures/compaction.zh.md    |  2 +-
 docs/persistence-catalog.md                   | 14 ++++-
 .../compaction.cordis.snapshot.yml            |  1 -
 .../compaction-recovery/session.jsonl         |  2 +-
 .../stream-json.expected.jsonl                |  2 +-
 .../compact/compact-basic/README.i18n.yaml    |  4 +-
 packages/compact/compact-basic/README.md      |  2 +-
 packages/compact/compact-basic/README.zh.md   |  2 +-
 packages/compact/compact-basic/src/region.ts  |  2 +
 .../compact/compact-basic/src/summarizer.ts   | 11 +++-
 .../compact-basic/tests/compact-basic.spec.ts |  3 +
 packages/compact/compact/src/types.ts         | 10 ++-
 packages/support/llm-replay/README.i18n.yaml  |  4 +-
 packages/support/llm-replay/README.md         |  6 +-
 packages/support/llm-replay/README.zh.md      |  6 +-
 packages/support/llm-replay/src/index.ts      | 10 ++-
 .../llm-replay/tests/llm-replay.spec.ts       | 62 +++++++++++++++++++
 29 files changed, 147 insertions(+), 50 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml
index b8ab8490d0..2ede6629d7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.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 .agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md
-2026-07-21-compaction-summary-prefix-cache-reuse.md: d05d25cfa7c3984ce0ce75c38068a91a0e07dfe8
-2026-07-21-compaction-summary-prefix-cache-reuse.zh.md: f31c33e680b3db60a6fb758a522addca63224fea
+2026-07-21-compaction-summary-prefix-cache-reuse.md: fb6524846f837b783423b3ed0e043cd4e1f7849d
+2026-07-21-compaction-summary-prefix-cache-reuse.zh.md: e6072313b7089b9dda14c298fcb94db786220501
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md
index d05d25cfa7..fb6524846f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md
@@ -29,7 +29,7 @@ Auto-compaction always anchors at the surface head, so the shadowed region is th
 - **Keep the summarizer system prompt but reuse the rest** — rejected: the system slot is the very first token region a provider caches on, so a distinct summarizer system prompt invalidates the whole prefix regardless of what follows. Only moving the directive off the front recovers the cache.
 - **Send only the shadowed region without the `system`/`tools` head** — rejected: a differently-headed sequence still diverges from the cached request at the first token, so it caches no better while losing the framing the summary needs.
 - **Omit `tools` from the summarization request** (the model never calls one) — rejected: tool schemas are part of the cached token sequence; omitting them misaligns every following token and defeats reuse.
-- **A dedicated `assistant/chunk`-emitting summarization sub-session for snapshot replay** — out of scope here; the replay gap predates this change and is tracked in the [compaction-seam note](../feature/2026-06-18-compaction-capability-seam.md).
+- **A dedicated `assistant/chunk`-emitting summarization sub-session for snapshot replay** — rejected: the durable `compact/summary` event records the successful local call's position and complete output, while its explicit call marker prevents replay from treating template or remote output as a local stream.
 
 ## Consequences
 
@@ -42,4 +42,4 @@ Auto-compaction always anchors at the surface head, so the shadowed region is th
 
 - **Unit:** `compact-basic.spec.ts` asserts the auxiliary call forwards `system`/`tools`/leading messages and appends the compaction instruction as the final message, and that `compactRegion` replays the latest routed header prefix. Existing content assertions read the summarizer input through the replayed messages rather than a transcript string.
 - **Loop:** `compact-loop-repro.spec.ts` classifies the summarization request by the compaction instruction in its trailing user message, and the overflow-recovery tests continue to pin conversation-vs-summary request counts across the real loop.
-- **Snapshot gap unchanged:** the summarization call still emits no `assistant/chunk` events, so it remains outside keyless replay; the pre-existing gap is owned by the [compaction-seam note](../feature/2026-06-18-compaction-capability-seam.md).
+- **Snapshot:** keyless replay reconstructs one canonical successful stream from a marked `compact/summary`; the [compaction-seam note](../feature/2026-06-18-compaction-capability-seam.md) owns the durable marker contract.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md
index f31c33e680..e6072313b7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md
@@ -29,7 +29,7 @@ Status: implemented
 - **保留摘要器系统提示词但复用其余部分**——否决：system 槽位正是提供方最先做缓存的 token 区域，因此一个不同的摘要器系统提示词无论后面跟着什么都会使整个前缀失效。只有把指令移离前端才能恢复缓存。
 - **只发送被遮蔽区域而不带 `system`/`tools` 头部**——否决：头部不同的序列在第一个 token 处仍然与已缓存请求分叉，因此缓存效果并不更好，反而丢失了摘要所需的框架。
 - **从摘要请求中省略 `tools`**（模型从不调用任何工具）——否决：工具 schema 是已缓存 token 序列的一部分；省略它们会让后续每个 token 失去对齐，破坏复用。
-- **为快照回放专门建立一个发出 `assistant/chunk` 的摘要子会话**——此处超出范围；该回放缺口早于本次改动，记录在 [compaction-seam Agent Note](../feature/2026-06-18-compaction-capability-seam.md) 中。
+- **为快照回放专门建立一个发出 `assistant/chunk` 的摘要子会话**——否决：持久的 `compact/summary` 事件会记录成功本地调用的位置和完整输出，而显式调用标记可防止回放把模板或远程输出当作本地流。
 
 ## 后果
 
@@ -42,4 +42,4 @@ Status: implemented
 
 - **单元：** `compact-basic.spec.ts` 断言辅助调用转发 `system`/`tools`/前导消息，并把压缩指令作为最后一条消息追加，且 `compactRegion` 回放最新的已路由 header 前缀。现有的内容断言通过回放的消息而非 transcript 字符串来读取摘要器输入。
 - **循环：** `compact-loop-repro.spec.ts` 依据摘要请求尾部 user 消息中的压缩指令对其分类，溢出恢复测试则继续在真实循环中固定对话请求与摘要请求的数量。
-- **快照缺口未变：** 摘要调用仍然不发出 `assistant/chunk` 事件，因此它仍处于无密钥回放之外；这一既有缺口归 [compaction-seam Agent Note](../feature/2026-06-18-compaction-capability-seam.md) 所有。
+- **快照：** 无密钥回放会从带标记的 `compact/summary` 重建一条规范成功流；[compaction-seam Agent Note](../feature/2026-06-18-compaction-capability-seam.md) 负责持久标记契约。
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index 9e195a4b1d..1917b118da 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.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 .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: 8dcbe74429a620027a570124383442b969c12196
-2026-06-18-compaction-capability-seam.zh.md: 27b63f29c2e6f35637185b47c882ae42e5d41088
+2026-06-18-compaction-capability-seam.md: 390d091fd6e6f7fa1694ba78b90522b70948fe92
+2026-06-18-compaction-capability-seam.zh.md: d72793e6adde911a8623ac1c6b65df899381923e
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index 8dcbe74429..390d091fd6 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
@@ -33,7 +33,7 @@ This is not a coupling smell — it is the contract's domain. The "only cordis"
 
 An earlier draft put the full algorithm (the retention walk, token-summing, text extraction) as concrete methods on the interface. That recouples the contract to one strategy: a backend that wants a different retention policy or event sequence would have to fight inherited concrete code. Making all three operations abstract puts every *how* decision in the backend and keeps the interface a statement of *what*. Token measurement is not a compaction hook at all; the singleton service lets multiple consumers share one per-session replay fold.
 
-`compactIfNeeded(agent, trigger, signal)` takes an explicit `'pressure' | 'context-overflow'` trigger and cancellation. It reads only the latest durable routed request; no header means no work, while any routed provider/model target uses the singleton estimator. `compactNow(agent, signal)` requires an idle agent and performs one useful balanced reduction even below pressure, returning `null` without writes when none exists. `compactRegion(start, end, agent, signal?)` uses `agent.session` as its single session identity and keeps an optional signal for explicit callers. The default summarizer resolves its target from explicit config, the latest logged routed target, then agent options, and records the provider/model pair after any `llm/stream` routing. It replays the routed request's prefix and appends the compaction directive as a trailing user message so the provider's warm KV cache is reused — see the [summary prefix-cache Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md). The call sets the provider-neutral `GenerateOptions.purpose` to `compaction`; adapters may map that purpose to model-hidden transport metadata, and the DeepSeek adapter sends `x-deepseek-harness-compact: 1`.
+`compactIfNeeded(agent, trigger, signal)` takes an explicit `'pressure' | 'context-overflow'` trigger and cancellation. It reads only the latest durable routed request; no header means no work, while any routed provider/model target uses the singleton estimator. `compactNow(agent, signal)` requires an idle agent and performs one useful balanced reduction even below pressure, returning `null` without writes when none exists. `compactRegion(start, end, agent, signal?)` uses `agent.session` as its single session identity and keeps an optional signal for explicit callers. The default summarizer resolves its target from explicit config, the latest logged routed target, then agent options, and records the provider/model pair after any `llm/stream` routing. It replays the routed request's prefix and appends the compaction directive as a trailing user message so the provider's warm KV cache is reused — see the [summary prefix-cache Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md). The result carries `llmStreamCall: true` because it consumed exactly one call through this context's LLM service; a subclass sets that marker only under the same condition, since retained `rawOutput` alone does not identify the call path. The call sets the provider-neutral `GenerateOptions.purpose` to `compaction`; adapters may map that purpose to model-hidden transport metadata, and the DeepSeek adapter sends `x-deepseek-harness-compact: 1`.
 
 ### Automatic pressure runs after successful durable step work
 
@@ -76,7 +76,7 @@ Because `SurfaceEventType` is closed, the summary cannot ride on a `compact/*` e
 ```
 compact/start    → log-only. Acquires the lock.
 [summarize older range via the backend]
-compact/summary  → log-only. Provenance: raw summary, range, shadowed seqs, token count.
+compact/summary  → log-only. Provenance: raw summary, local-call marker, range, shadowed seqs, token count.
 user/message     → canonical checkpoint source + surfaceOp { op:'replace', start, end }.
                    THE surface mutation (framed summary).
                    deriveMessages() renders it as a user-role message.
@@ -131,4 +131,4 @@ The lifecycle boundary makes crash state unambiguous:
 - **Loop:** Tests pin pre-step after the preceding `step/end` and before the next `step/start`, actual `agent/request` routing, closed failed steps, fresh retry numbering, and complete thrown/in-band overflow → compaction → reconstructed retry composition.
 - **Manual:** Maintenance serialization, marker ordering, injection retention, live/stale orphan classification, cancellation, close/flush failures, command mapping, and the queued TUI journey are pinned without a model key.
 - **With-key e2e:** A real model and bash session with lowered limits triggers compaction, records a complete `compact/start…end` pair, shrinks the surface, and finishes the task.
-- **Snapshot gap:** The summarization call is session-associated and logs `compact/summary`, but ordinary transcript replay does not derive its auxiliary response; keyless assembled coverage therefore needs an explicit replay override.
+- **Snapshot:** The assembled context-overflow scenario derives the auxiliary call from `compact/summary` only when `llmStreamCall: true` proves that the local LLM service consumed it; canonical reconstructed blocks pin the complete recovery without provider delta partitioning.
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index 27b63f29c2..d72793e6ad 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -33,7 +33,7 @@ Status: implemented
 
 早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将契约重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
 
-`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
+`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
 
 ### 成功的持久步骤工作完成后运行自动压力检查
 
@@ -76,7 +76,7 @@ retry → next numbered step/start      ⟵ derives from the replacement surface
 ```
 compact/start    → log-only. Acquires the lock.
 [summarize older range via the backend]
-compact/summary  → log-only. Provenance: raw summary, range, shadowed seqs, token count.
+compact/summary  → log-only. Provenance: raw summary, local-call marker, range, shadowed seqs, token count.
 user/message     → canonical checkpoint source + surfaceOp { op:'replace', start, end }.
                    THE surface mutation (framed summary).
                    deriveMessages() renders it as a user-role message.
@@ -131,4 +131,4 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 - **循环测试：** 测试固定 pre-step 发生在前一个 `step/end` 之后、下一个 `step/start` 之前，使用实际 `agent/request` 路由，关闭失败步骤，分配新的重试编号，并覆盖完整的抛出/带内溢出 → 压缩 → 重建重试组合。
 - **手动测试：** 无需模型密钥即可固定 maintenance 串行化、标记顺序、注入保留、活动／陈旧未匹配标记分类、取消、闭合／flush 失败、命令映射以及排队 TUI 流程。
 - **带密钥 e2e：** 真实模型和 bash 会话在降低的限制下触发压缩，记录完整的 `compact/start…end` 对，缩小 surface，并完成任务。
-- **快照缺口：** 摘要调用与会话关联并记录 `compact/summary`，但普通 transcript（文本记录）回放不会派生其辅助响应；因此，要实现无密钥的组装态覆盖，就必须显式提供回放 override。
+- **快照：** 组装后的上下文溢出场景仅在 `llmStreamCall: true` 证明本地 LLM 服务执行了辅助调用时，才从 `compact/summary` 派生该调用；规范重建的块在不固定提供方增量切分的情况下固定完整恢复过程。
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
index 202a27ed1e..e5e6b3d67e 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.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 .agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
-2026-06-19-acp-snapshot-tests.md: c7b95bd68027705b99d850d596405e56eea0dfca
-2026-06-19-acp-snapshot-tests.zh.md: 43d43262684920cae5feedb5f2eb109db00f9f8c
+2026-06-19-acp-snapshot-tests.md: c6e81dc4a51083ed37ad6f837fe7dbb08c212e23
+2026-06-19-acp-snapshot-tests.zh.md: 5a579c3373442dc4cfc7d661ea2f2f398b804dc7
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
index c7b95bd680..c6e81dc4a5 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
@@ -24,7 +24,7 @@ Every committed session-format fixture uses the canonical packed physical layout
 
 ### Replay derives the model script from the log
 
-`llm-replay` short-circuits the provider-agnostic `llm/stream` waterfall. `deriveReplayScript()` groups recorded chunks by `(turn, step)` and serves one group per model call. The loop makes one stream call per step, so the grouping is exact and includes error finish chunks without special handling.
+`llm-replay` short-circuits the provider-agnostic `llm/stream` waterfall. `deriveReplayScript()` splits recorded `assistant/chunk` events at terminal `finish` chunks and uses `(turn, step)` changes to reject an unterminated prior call. A `compact/summary` with `llmStreamCall: true` contributes one call at its durable log position: replay reconstructs canonical block boundaries from `rawOutput`, retains recorded usage when present, and supplies a terminal `stop`. The marker distinguishes that local call from template or remote summaries whose retained `rawOutput` did not consume this context's adapter.
 
 ### The in-memory replay entry honors the full LLM contract
 
@@ -36,7 +36,7 @@ Every committed session-format fixture uses the canonical packed physical layout
 | { kind: 'hang' }
 ```
 
-Logs derive chunk entries. Pre-stream throws and hangs have no reconstructable chunk representation, so those scenarios provide `replay.override.json`. A throw entry may include prefix chunks for mid-stream failure. Explicit overrides avoid inferring adapter behavior from lossy turn-end reasons.
+Logs derive chunk entries from finished assistant streams and explicitly marked compaction calls. Pre-stream throws, hangs, and external summarizer calls have no reconstructable local chunk representation, so those scenarios provide `replay.override.json`. A throw entry may include prefix chunks for mid-stream failure. Explicit overrides avoid inferring adapter behavior from lossy turn-end reasons or provider output alone.
 
 ### Positional replay, one in-flight stream
 
@@ -74,12 +74,13 @@ Tool determinism comes from a generated cwd, scrubbed environment, fresh non-log
 ## Alternatives considered
 
 - **A hand-authored `llm.json` of model chunks** — the earlier draft; reusing the real session log makes the fixture a genuine product of the system rather than a hand-built mock, and doubles it as a behavioral expected output.
+- **A compulsory replay override for every compaction summary** — rejected: the durable summary event already fixes a successful local call's position, complete output, and optional usage. An explicit local-call marker preserves that single-source fixture without inventing a call for template or remote summarizers.
 - **A byte-level HTTP-record library (Polly/nock/MSW)** — rejected: adapter-specific, awkward with streaming SSE, and lower-level than the thing under test.
 - **Synthesizing throw/cancel entries from `turn/end {kind:'error'|'aborted'}`** — rejected: it couples `llm-replay` to loop-internal turn-closing semantics, and the `turn/end` reason is lossy (it cannot distinguish a thrown 401 from a finish-error); the explicit `replay.override.json` sidecar is the cleaner seam.
 - **Copying both request-header sidecars beside every class pin** — rejected: prompt and tool-schema composition vary independently, so a change to one shared component would churn byte-identical files across unrelated class pins. Explicit per-component sources retain one structural pin per class without duplicating content.
 
 ## Consequences
 
-The tier adds reviewed per-scenario input, session, stdout, optional override, and optional workspace fixtures, plus one file for each distinct pinned prompt and tool-schema sequence. Workspace seeds are copied into the generated cwd for both record and replay. In return the tier provides deterministic keyless coverage through the real Loader and tool composition. Most retained scenarios exercise the assembled backend rather than ACP; the [automation-only ACP decision](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary) keeps that corpus here until it can move to a transport-neutral headless suite without losing coverage.
+The tier adds reviewed per-scenario input, session, stdout, optional override, and optional workspace fixtures, plus one file for each distinct pinned prompt and tool-schema sequence. Workspace seeds are copied into the generated cwd for both record and replay. In return the tier provides deterministic keyless coverage through the real Loader and tool composition, including an assembled context-overflow recovery whose marked compaction summary supplies the auxiliary call. Most retained scenarios exercise the assembled backend rather than ACP; the [automation-only ACP decision](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary) keeps that corpus here until it can move to a transport-neutral headless suite without losing coverage.
 
 This Agent Note relates to but does not supersede the [proposed determinism Agent Note](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.md): that proposal's "universal replay fixture" re-derives session *message history* after every test (an internal-consistency invariant), whereas these snapshots pin assembled behavior plus the external automation output. They are complementary until the backend corpus moves off ACP.
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
index 43d4326268..5a579c3373 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 ### 回放从日志推导模型脚本
 
-`llm-replay` 短路了提供方无关的 `llm/stream` waterfall（瀑布式事件）。`deriveReplayScript()` 按 `(turn, step)` 对已录制的分片分组，每次模型调用服务一组。agent loop（智能体循环）每个步骤发起一次流调用，因此分组精确对应，错误结束分片也无需特殊处理。
+`llm-replay` 短路了提供方无关的 `llm/stream` waterfall（瀑布式事件）。`deriveReplayScript()` 在终止的 `finish` 分片处切分已记录的 `assistant/chunk` 事件，并用 `(turn, step)` 变化拒绝前一条未终止的调用。携带 `llmStreamCall: true` 的 `compact/summary` 会在其持久日志位置贡献一次调用：回放根据 `rawOutput` 重建规范块边界，保留已记录的 usage（如有），并提供终止的 `stop`。该标记将这次本地调用与模板摘要或远程摘要区分开；后两者即使保留了 `rawOutput`，也未使用此上下文的适配器。
 
 ### 内存中的回放条目遵守完整的 LLM 契约
 
@@ -36,7 +36,7 @@ Status: implemented
 | { kind: 'hang' }
 ```
 
-日志推导出分片条目。流开始前的抛出和挂起没有可重建的分片表示，因此这些场景提供 `replay.override.json`。throw 条目可以包含前缀分片以模拟流中途失败。显式覆盖避免了从有损的轮次结束原因推断适配器行为。
+日志从已结束的 assistant 流和显式标记的压缩（compaction）调用推导分片条目。流开始前的抛出、挂起和外部摘要器调用没有可重建的本地分片表示，因此这些场景提供 `replay.override.json`。throw 条目可以包含前缀分片以模拟流中途失败。显式覆盖避免了从有损的轮次结束原因或单独的提供方输出推断适配器行为。
 
 ### 位置式回放，单个在途流
 
@@ -74,12 +74,13 @@ Status: implemented
 ## 曾考虑的替代方案
 
 - **手工编写包含模型分片的 `llm.json`**——早期草案；复用真实会话日志，使 fixture 成为系统的真实产物而非手工构建的 mock，并让它同时充当行为预期输出。
+- **为每个压缩摘要强制提供回放 override**——否决：持久摘要事件已经固定成功本地调用的位置、完整输出与可选 usage。显式的本地调用标记保留了这份单一来源 fixture，而不会为模板摘要器或远程摘要器凭空构造调用。
 - **字节级 HTTP 录制库（Polly/nock/MSW）**：否决。与适配器耦合，处理流式 SSE（Server-Sent Events）时笨拙，且层级低于被测对象。
 - **从 `turn/end {kind:'error'|'aborted'}` 合成抛错/取消条目**：否决。这会将 `llm-replay` 耦合到 loop 内部的轮次关闭语义，且 `turn/end` 原因是有损的（无法区分抛出的 401 与 finish-error）；显式的 `replay.override.json` 伴随文件是更清晰的 seam。
 - **在每个类别 pin 旁复制两个请求头伴随文件**：否决。提示词与工具 schema 的组合各自独立变化，因此一个共享组件发生变更，就会使不相关类别 pin 中字节完全相同的文件产生无意义改动。显式的分组件来源可在不重复内容的情况下，为每个类别保留一个结构性 pin。
 
 ## 后果
 
-该测试层为每个场景增加经过评审的输入、会话、stdout、可选 override 和可选 workspace fixture，并为每个不同的已固定提示词序列、每个不同的已固定工具 schema 序列各增加一个文件。记录与回放都会把 workspace seed 复制到生成的 cwd。作为回报，该层通过真实 Loader 和工具组合提供确定性的无密钥覆盖。保留下来的大多数场景测试的是组装后的后端而非 ACP；[仅面向自动化的 ACP 决策](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary)将该语料保留在此处，直至它能够在不损失覆盖的情况下迁移到传输无关的 headless 套件。
+该测试层为每个场景增加经过评审的输入、会话、stdout、可选 override 和可选 workspace fixture，并为每个不同的已固定提示词序列、每个不同的已固定工具 schema 序列各增加一个文件。记录与回放都会把 workspace seed 复制到生成的 cwd。作为回报，该层通过真实 Loader 和工具组合提供确定性的无密钥覆盖，其中包括一个组装后的上下文溢出恢复场景，其带标记的压缩摘要提供辅助调用。保留下来的大多数场景测试的是组装后的后端而非 ACP；[仅面向自动化的 ACP 决策](../simplification/2026-07-23-acp-automation-only-protocol.md#snapshot-boundary)将该语料保留在此处，直至它能够在不损失覆盖的情况下迁移到传输无关的 headless 套件。
 
 本 Agent Note 与[拟议的确定性 Agent Note](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.md)相关，但不取代它：该提案的“通用回放 fixture”在每次测试后重新派生会话*消息历史*（内部一致性不变量），而这些快照固定组装后的行为与外部自动化输出。在后端语料迁出 ACP 之前，两者相互补充。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 4a9bafeb83..afc8cd302a 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -891,7 +891,7 @@ export interface ReplayModelConfig {
 
 Depends on: [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
 
-Source: [`packages/support/llm-replay/src/index.ts:731`](../packages/support/llm-replay/src/index.ts)
+Source: [`packages/support/llm-replay/src/index.ts:735`](../packages/support/llm-replay/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-retry`
 
diff --git a/docs/core-data-structures/compaction.i18n.yaml b/docs/core-data-structures/compaction.i18n.yaml
index a0c3f27f88..c5cd2a0b38 100644
--- a/docs/core-data-structures/compaction.i18n.yaml
+++ b/docs/core-data-structures/compaction.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 docs/core-data-structures/compaction.md
-compaction.md: fe64ffe2707ab4a41f1db186965b944d525684c3
-compaction.zh.md: ea694f30dcc50ef48847ffbd5efdeed36aa234c5
+compaction.md: b17dfc03c62c0453c45ca2810ef90bdce9ae9ac7
+compaction.zh.md: b904cdd3ad5bf63e968fc22fccb32c5220ab8763
diff --git a/docs/core-data-structures/compaction.md b/docs/core-data-structures/compaction.md
index fe64ffe270..b17dfc03c6 100644
--- a/docs/core-data-structures/compaction.md
+++ b/docs/core-data-structures/compaction.md
@@ -13,7 +13,7 @@ Compaction extends [`SessionEventMap`](session.md) with three event types via de
 | Event | Payload | Role |
 |---|---|---|
 | `compact/start` | `{ turn }` | acquires the log-recorded lock; a number identifies the open automatic turn, while `null` identifies a standalone manual attempt |
-| `compact/summary` | `{ summary, rawOutput?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance: the safe summary projection, optional complete provider output and usage, the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note) |
+| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance: the safe summary projection, optional complete provider output and usage, an `llmStreamCall: true` marker when producing the result consumed exactly one call through this context's `ctx.llm.stream()`, the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note); `rawOutput` alone does not identify the call path |
 | `compact/end` | `{ turn, error? }` | releases the lock with the same numeric-or-null owner (`error` records an unsuccessful attempt) |
 
 The lock brackets the **whole** operation: `compact/start` is appended first, then summarization, the `compact/summary` provenance record, and the `user/message` replacement all land, and only then `compact/end`. Releasing the lock last turns a crash mid-operation into a detectable orphaned lock (a `compact/start` with no matching `compact/end`) rather than a `compact/end` that falsely claims compaction finished.
diff --git a/docs/core-data-structures/compaction.zh.md b/docs/core-data-structures/compaction.zh.md
index ea694f30dc..b904cdd3ad 100644
--- a/docs/core-data-structures/compaction.zh.md
+++ b/docs/core-data-structures/compaction.zh.md
@@ -13,7 +13,7 @@
 | 事件 | 载荷 | 作用 |
 |---|---|---|
 | `compact/start` | `{ turn }` | 获取日志记录的锁；数字标识打开的自动轮次，`null` 标识独立手动尝试 |
-| `compact/summary` | `{ summary, rawOutput?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance：安全摘要投影、可选的完整 provider 输出与 usage、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note） |
+| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance：安全摘要投影、可选的完整 provider 输出与 usage、生成结果时恰好通过此上下文的 `ctx.llm.stream()` 发起一次调用所带的 `llmStreamCall: true` 标记、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note）；单有 `rawOutput` 并不能判定调用路径 |
 | `compact/end` | `{ turn, error? }` | 使用相同的数字或 `null` 归属值释放锁（`error` 记录失败尝试） |
 
 锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 来源记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 48732dbbb0..808a03b6f4 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -237,7 +237,7 @@ Source: [`packages/ui/commands/src/index.ts:139`](../packages/ui/commands/src/in
 'compact/end': { turn: number | null; error?: string }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:54`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:62`](../packages/compact/compact/src/types.ts)
 
 #### `compact/prune` — log-only
 
@@ -261,7 +261,7 @@ Source: [`packages/compact/compact/src/types.ts:54`](../packages/compact/compact
 }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:64`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:72`](../packages/compact/compact/src/types.ts)
 
 #### `compact/start` — log-only
 
@@ -290,8 +290,16 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
  */
 'compact/summary': {
   summary: ContentBlock[]
-  /** Complete provider output before the backend's safe summary projection. */
+  /**
+   * Complete provider output before the backend's safe summary projection;
+   * this alone does not identify the call path.
+   */
   rawOutput?: ContentBlock[]
+  /**
+   * Present only when producing the summary consumed exactly one call
+   * through this context's `ctx.llm.stream()`.
+   */
+  llmStreamCall?: true
   shadowedRange: { start: number; end: number }
   shadowedSeqs: number[]
   shadowedTokenCount: number
diff --git a/examples/headless-agent/compaction.cordis.snapshot.yml b/examples/headless-agent/compaction.cordis.snapshot.yml
index 42fc5306ac..13515cf5cc 100644
--- a/examples/headless-agent/compaction.cordis.snapshot.yml
+++ b/examples/headless-agent/compaction.cordis.snapshot.yml
@@ -13,7 +13,6 @@
           thresholdRatio: 0.99
           retainTokens: 20
           maxTokens: 32
-          compactionRetries: 1
       - insert:
           - id: llm-replay
             name: '@deepseek-ai/dsh-llm-replay'
diff --git a/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl b/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
index 855e66ac14..38056019e2 100644
--- a/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
@@ -19,7 +19,7 @@
 {"type":"step/start","seq":17,"time":1786123401710,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":18,"time":1786123401715,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot request exceeded the model context window","code":"CONTEXT_WINDOW_EXCEEDED"}}}}}
 {"type":"compact/start","seq":19,"time":1786123401715,"data":{"turn":1}}
-{"type":"compact/summary","seq":20,"time":1786123401725,"data":{"summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}
+{"type":"compact/summary","seq":20,"time":1786123401725,"data":{"summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}
 {"type":"user/message","seq":21,"time":1786123401725,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"6d2afb13-a37b-48d6-9ea5-fc8734127377"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}
 {"type":"compact/end","seq":22,"time":1786123401725,"data":{"turn":1}}
 {"type":"assistant/chunk","seq":23,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
diff --git a/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
index 4d798adc37..62cc357cc7 100644
--- a/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
@@ -18,7 +18,7 @@
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":17,"time":0,"data":{"turn":1,"step":2}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot request exceeded the model context window","code":"CONTEXT_WINDOW_EXCEEDED"}}}}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/start","seq":19,"time":0,"data":{"turn":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/summary","seq":20,"time":0,"data":{"summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/summary","seq":20,"time":0,"data":{"summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":21,"time":0,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"{{sessionId}}"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/end","seq":22,"time":0,"data":{"turn":1}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":23,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
diff --git a/packages/compact/compact-basic/README.i18n.yaml b/packages/compact/compact-basic/README.i18n.yaml
index 8c8b85f323..062021a4c1 100644
--- a/packages/compact/compact-basic/README.i18n.yaml
+++ b/packages/compact/compact-basic/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/compact/compact-basic/README.md
-README.md: 0c7b009255dc2d41dc81cf2c7ff745e02ef28b9a
-README.zh.md: 4af584a059c99725882afd6206bdf9c984c7d4e3
+README.md: d1c1dfb509ae0750e1237532a829a35de5084c5e
+README.zh.md: a78887daad04d534ffed9cbd0357b76bdd908f5e
diff --git a/packages/compact/compact-basic/README.md b/packages/compact/compact-basic/README.md
index 0c7b009255..d1c1dfb509 100644
--- a/packages/compact/compact-basic/README.md
+++ b/packages/compact/compact-basic/README.md
@@ -21,7 +21,7 @@ This backend owns the compaction policy:
 - **Overflow recovery** — provider-confirmed overflow needs no capacity metadata: it bypasses normal pressure and retention, prunes, then attempts one maximal balanced head reduction while leaving the newest indivisible unit. Retry is authorized whenever `surface.replaceGeneration` advances, including when pruning lands before later summary work throws. No replacement, an exhausted target-specific cap, cancellation, or an unknown/noncanonical error preserves the original provider failure.
 - **Failure handling** — a live unmatched `compact/start` is the durable lock. An unmatched marker before a newer `session/end-seed` is stale evidence from a prior lifecycle and does not block; one after that boundary reports `busy`. Summary and changed-span failures close with an error and leave the conversation surface untouched, though the attempt remains in the log. A failed close deliberately leaves a blocking orphan. Operational pressure failures warn and continue, while overflow-recovery failure preserves the original provider error only when no earlier replacement advanced the surface. Cancellation remains authoritative after cleanup and durability.
 
-The protected `summarize()` method is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, provenance, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the safe summary plus the complete provider output, call envelope, and usage when available (`{ summary, rawOutput?, provider, model, maxTokens?, usage? }`); the transaction preserves those fields on `compact/summary`.
+The protected `summarize()` method is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, provenance, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the safe summary plus the complete provider output, call envelope, and usage when available (`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`); `llmStreamCall: true` means producing that result consumed exactly one call through this context's `ctx.llm.stream()`, while `rawOutput` alone does not identify the call path. The transaction preserves those fields on `compact/summary`.
 
 ## Config (`BasicCompactConfig`)
 
diff --git a/packages/compact/compact-basic/README.zh.md b/packages/compact/compact-basic/README.zh.md
index 4af584a059..a78887daad 100644
--- a/packages/compact/compact-basic/README.zh.md
+++ b/packages/compact/compact-basic/README.zh.md
@@ -21,7 +21,7 @@
 - **溢出恢复**：提供方已确认的溢出不需容量元数据。它会绕过常规压力与保留，执行剪枝，再尝试一次最大平衡头部缩减，并留下最新不可分单元。只要 `surface.replaceGeneration` 前进，就允许重试，包括剪枝在后续摘要工作抛出异常前已落地的情况。如果没有替换、目标特定上限已耗尽、已取消，或遇到未知／非规范错误，则保留原始提供方失败。
 - **失败处理**：活动的未匹配 `compact/start` 是持久锁。位于较新 `session/end-seed` 之前的未匹配标记，是先前生命周期留下的陈旧证据，不会阻塞；位于该边界之后的标记报告 `busy`。摘要和 span 变更失败会以错误闭合，并保持会话表层不变，但日志中仍保留该尝试。闭合失败会有意留下阻塞性的未匹配标记。压力检查中的运行故障会发出警告并继续；只有此前没有替换推进表层时，溢出恢复失败才保留原始提供方错误。完成清理与持久化后，取消仍具有最终决定权。
 
-受保护的 `summarize()` 方法是唯一的子类钩子。基于模板或远程摘要器的子类可以覆盖该方法，同时压力、保留、溯源、缩减验证与已遮蔽 token 计量仍由 `ctx.tokenMeter` 负责。钩子返回安全摘要，以及完整提供方输出、调用 envelope 和可用时的 usage（`{ summary, rawOutput?, provider, model, maxTokens?, usage? }`）；事务会在 `compact/summary` 上保留这些字段。
+受保护的 `summarize()` 方法是唯一的子类钩子。基于模板或远程摘要器的子类可以覆盖该方法，同时压力、保留、溯源、缩减验证与已遮蔽 token 计量仍由 `ctx.tokenMeter` 负责。钩子返回安全摘要，以及完整提供方输出、调用 envelope 和可用时的 usage（`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`）；`llmStreamCall: true` 表示生成该结果时恰好通过此上下文的 `ctx.llm.stream()` 发起了一次调用，而单有 `rawOutput` 并不能判定调用路径。事务会在 `compact/summary` 上保留这些字段。
 
 ## 配置（`BasicCompactConfig`）
 
diff --git a/packages/compact/compact-basic/src/region.ts b/packages/compact/compact-basic/src/region.ts
index 2132081557..67516a830d 100644
--- a/packages/compact/compact-basic/src/region.ts
+++ b/packages/compact/compact-basic/src/region.ts
@@ -416,6 +416,7 @@ function commitCompactionBody(
     shadowedTokenCount,
     summary,
     rawOutput,
+    llmStreamCall,
     provider,
     model,
     maxTokens,
@@ -425,6 +426,7 @@ function commitCompactionBody(
   const summaryEvent = session.append('compact/summary', {
     summary,
     ...rawOutput === undefined ? {} : { rawOutput },
+    ...llmStreamCall === undefined ? {} : { llmStreamCall },
     shadowedRange: { start, end },
     shadowedSeqs: [...shadowedSeqs],
     shadowedTokenCount,
diff --git a/packages/compact/compact-basic/src/summarizer.ts b/packages/compact/compact-basic/src/summarizer.ts
index ba3dad5592..08aa810433 100644
--- a/packages/compact/compact-basic/src/summarizer.ts
+++ b/packages/compact/compact-basic/src/summarizer.ts
@@ -87,8 +87,16 @@ export interface SummarizationInput {
 /** Safe summary content plus the exact auxiliary call envelope recorded in provenance. */
 export interface SummaryResult {
   summary: ContentBlock[]
-  /** Complete provider output before the text-only summary projection. */
+  /**
+   * Complete provider output before the text-only summary projection; this
+   * alone does not identify the call path.
+   */
   rawOutput?: ContentBlock[]
+  /**
+   * Present only when producing the summary consumed exactly one call through
+   * this context's `ctx.llm.stream()`.
+   */
+  llmStreamCall?: true
   provider: string
   model: string
   maxTokens?: number
@@ -162,6 +170,7 @@ export async function summarizeWithLlm(
   return {
     summary,
     rawOutput,
+    llmStreamCall: true,
     provider: options.provider,
     model: options.model,
     maxTokens: config.maxTokens,
diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts
index a8efad741b..bd04335964 100644
--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -868,6 +868,7 @@ describe('compaction region transaction', () => {
       rawOutput: compact.rawOutput,
       usage: compact.usage,
     })
+    expect(summary?.data).not.toHaveProperty('llmStreamCall')
     const head = session.deriveMessages()[0]!
     expect(head.content[0]?.type).toBe('text')
     expect(head.content[0]?.type === 'text' ? head.content[0].text : '').toContain('<compacted-summary>')
@@ -1187,6 +1188,7 @@ describe('default one-shot summarizer', () => {
         { type: 'text', text: 'public summary' },
         { type: 'tool-call', id: CallId('unexpected'), name: 'x', arguments: '{}' },
       ],
+      llmStreamCall: true,
       provider: MODEL,
       model: MODEL,
       maxTokens: 321,
@@ -1300,6 +1302,7 @@ describe('default one-shot summarizer', () => {
     await compact.compactRegion(nodes[0]!, nodes[3]!, agent(session, MODEL), SIGNAL)
     expect(session.events.findLast(event => event.type === 'compact/summary')?.data).toMatchObject({
       summary: [{ type: 'text', text: 'routed summary' }],
+      llmStreamCall: true,
       provider: 'routed-summary-provider',
       model: 'routed-summary-model',
     })
diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index 4a856a6848..4ed12d1e5f 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -28,8 +28,16 @@ declare module '@deepseek-ai/dsh-session' {
      */
     'compact/summary': {
       summary: ContentBlock[]
-      /** Complete provider output before the backend's safe summary projection. */
+      /**
+       * Complete provider output before the backend's safe summary projection;
+       * this alone does not identify the call path.
+       */
       rawOutput?: ContentBlock[]
+      /**
+       * Present only when producing the summary consumed exactly one call
+       * through this context's `ctx.llm.stream()`.
+       */
+      llmStreamCall?: true
       shadowedRange: { start: number; end: number }
       shadowedSeqs: number[]
       shadowedTokenCount: number
diff --git a/packages/support/llm-replay/README.i18n.yaml b/packages/support/llm-replay/README.i18n.yaml
index 3f3e349a84..e120b5007b 100644
--- a/packages/support/llm-replay/README.i18n.yaml
+++ b/packages/support/llm-replay/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/support/llm-replay/README.md
-README.md: 46d391970f320708914d11f0868cbbc5361ae196
-README.zh.md: a67b078a1396968dc3ddecb0e616a832c4faaf3a
+README.md: a6c087778b8e64124590fb6be7a652b58e1b6343
+README.zh.md: 241edb9c9b2400519155ccd7161eb7f34b9f5bbe
diff --git a/packages/support/llm-replay/README.md b/packages/support/llm-replay/README.md
index 46d391970f..a6c087778b 100644
--- a/packages/support/llm-replay/README.md
+++ b/packages/support/llm-replay/README.md
@@ -8,7 +8,7 @@ Its consumers are the ACP and headless `stream-json` snapshot suites plus the We
 
 ## How the fixture works
 
-The fixture IS the persisted session log (`<scenario>/session.jsonl`). Its `assistant/chunk` events carry every `StreamChunk`, so grouping them by `(turn, step)` reconstructs each agent-loop `stream()` call's chunk sequence. A successful compaction summarizer is logged differently: when `compact/summary` carries its complete `rawOutput`, replay reconstructs a canonical successful stream at that event's position using one `block-start`/`block-end` pair per block, the recorded usage when present, and a terminal `stop`. Exact provider delta partitioning is not part of the durable compaction result. A summary without `rawOutput` does not imply an LLM call because template and remote summarizers may produce it without the local adapter.
+The fixture IS the persisted session log (`<scenario>/session.jsonl`). Its `assistant/chunk` events carry every `StreamChunk`, so grouping them by `(turn, step)` reconstructs each agent-loop `stream()` call's chunk sequence. A successful compaction summarizer is logged differently: when `compact/summary` carries `llmStreamCall: true` and its complete `rawOutput`, replay reconstructs a canonical successful stream at that event's position using one `block-start`/`block-end` pair per block, the recorded usage when present, and a terminal `stop`. Exact provider delta partitioning is not part of the durable compaction result. `rawOutput` without the marker does not imply a local LLM call because template and remote summarizers may retain complete output without using this context's adapter.
 
 Recording is therefore "run the real agent once and harvest the `.jsonl`", done by the snapshot harness — this plugin does not record. A fixture may carry its `request/header` content tokenized to `{{system}}`/`{{tools}}` (the harness pins that content in one scenario and scrubs the rest); replay is indifferent — derivation reads only `assistant/chunk` and `compact/summary` events plus the line-0 session header.
 
@@ -59,7 +59,7 @@ Replay keys every call by its calling session id (`GenerateOptions.sessionId`, s
 - `installLlmReplay(ctx, config)` — install the configured replay adapter or catch-all `llm/stream` listener; returns a `ReplayHandle` (`dispose()` for HMR safety plus `assertConsumed()`, the teardown check that every recorded script bound to a live session and every bound cursor drained — turning a scenario that silently drove fewer model calls than recorded into a crisp diagnostic). Use this in tests to drive replay without the Loader or env vars.
 - `loadSessionScripts(config)` — resolve the ordered `SessionScript[]` (primary + children) for a scenario, ready to bind to live sessions in first-call order.
 - `loadReplayScript(config)` — resolve the `ReplayEntry[]` for the primary session only (validated sidecar replacement/patches if present, else derived from the JSONL; fail-loud if the fixture is missing).
-- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)` / `resolveScriptedEntry(entry, messages)` — the pure helpers that turn ordinary loop chunks and complete compaction outputs in a recorded session log into a script, read its header `id`/`createdAt`, and resolve `{{fromRequest:...}}` placeholders against one live request. A derived assistant group must end in a `finish` chunk; a group without one is the fingerprint of a thrown `stream()` and must instead be expressed via an override sidecar.
+- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)` / `resolveScriptedEntry(entry, messages)` — the pure helpers that turn ordinary loop chunks and explicitly marked local compaction outputs in a recorded session log into a script, read its header `id`/`createdAt`, and resolve `{{fromRequest:...}}` placeholders against one live request. A derived assistant group must end in a `finish` chunk; a group without one is the fingerprint of a thrown `stream()` and must instead be expressed via an override sidecar.
 - Types `ReplayEntry` / `ReplayOverrideDoc` / `ReplayOverridePatch` / `SessionScript` / `ReplayConfig` / `ReplayProviderConfig` / `ReplayModelConfig` / `ReplayHandle` / `Config`.
 
 ## Plugin export shape
@@ -77,4 +77,4 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **First-call-order script binding assumes sequential delegation** — a cut that runs sibling subagents concurrently would bind live sessions to recorded scripts non-deterministically; a stronger keying is deferred until such a scenario exists (`XXX(concurrent-subagents)`).
-- **Only ordinary loop chunks and completed compaction outputs are derivable** — a pure pre-chunk throw or a cancel/hang scenario needs the `replay.override.json` sidecar. Replacement and patch forms affect only the primary session; child scripts still derive from their logs.
+- **Only ordinary loop chunks and marked local compaction outputs are derivable** — a pure pre-chunk throw, a cancel/hang, or an unmarked external summarizer call needs the `replay.override.json` sidecar. Replacement and patch forms affect only the primary session; child scripts still derive from their logs.
diff --git a/packages/support/llm-replay/README.zh.md b/packages/support/llm-replay/README.zh.md
index a67b078a13..241edb9c9b 100644
--- a/packages/support/llm-replay/README.zh.md
+++ b/packages/support/llm-replay/README.zh.md
@@ -8,7 +8,7 @@
 
 ## fixture 的工作方式
 
-fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件包含每个 `StreamChunk`，因此按 `(turn, step)` 分组即可重建每次 agent-loop `stream()` 调用的分片序列。压缩（compaction）摘要器成功时，日志记录方式有所不同：当 `compact/summary` 携带完整的 `rawOutput` 时，回放会在该事件的位置重建一条规范成功流，其中每个块各使用一对 `block-start`/`block-end`，带上已记录的 usage（如有），并以 `stop` 终止。提供方增量的精确切分不属于持久压缩结果。不带 `rawOutput` 的摘要并不意味着发生了 LLM 调用，因为模板摘要器和远程摘要器可能不经本地适配器生成该摘要。
+fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件包含每个 `StreamChunk`，因此按 `(turn, step)` 分组即可重建每次 agent-loop `stream()` 调用的分片序列。压缩（compaction）摘要器成功时，日志记录方式有所不同：当 `compact/summary` 携带 `llmStreamCall: true` 和完整的 `rawOutput` 时，回放会在该事件的位置重建一条规范成功流，其中每个块各使用一对 `block-start`/`block-end`，带上已记录的 usage（如有），并以 `stop` 终止。提供方增量的精确切分不属于持久压缩结果。不带该标记的 `rawOutput` 并不意味着发生了本地 LLM 调用，因为模板摘要器和远程摘要器即使未使用此上下文的适配器，也可能保留完整输出。
 
 因此，录制就是「运行一次真实 agent 并收集 `.jsonl`」，由快照 harness 完成；该插件本身不录制。fixture 的 `request/header` 内容可能被标记化为 `{{system}}`/`{{tools}}`（harness 会在一个场景中固定该内容，并清除其余场景中的内容）；回放不受影响，因为派生过程只读取 `assistant/chunk` 和 `compact/summary` 事件以及第 0 行的会话 header。
 
@@ -59,7 +59,7 @@ fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `as
 - `installLlmReplay(ctx, config)`：安装已配置回放适配器或 catch-all `llm/stream` 监听器；返回 `ReplayHandle`（包含用于保证 HMR（热模块替换）安全的 `dispose()`，以及清理阶段执行的 `assertConsumed()` 检查；后者确保每个已记录脚本都绑定到实时会话，且每个已绑定游标都已耗尽，从而将场景静默驱动的模型调用少于记录数转换为明确诊断）。在测试中使用它，可以不通过 Loader 或 env var 驱动回放。
 - `loadSessionScripts(config)`：解析场景中有序的 `SessionScript[]`（主会话 + 子会话），准备按首次调用顺序绑定到实时会话。
 - `loadReplayScript(config)`：只解析主会话的 `ReplayEntry[]`（如果伴随文件存在，则使用经校验的替换或补丁；否则从 JSONL 派生；fixture 缺失时明确报错）。
-- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)` / `resolveScriptedEntry(entry, messages)`：将已记录会话日志中的普通 loop 分片和完整压缩输出转换为脚本、读取其 header `id`/`createdAt`、并针对单次实时请求解析 `{{fromRequest:...}}` 占位符的纯辅助工具。派生的 assistant 分组必须以 `finish` 分片结束；没有该分片的分组是 `stream()` 抛出异常的指纹，必须改用 override 伴随文件表达。
+- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)` / `resolveScriptedEntry(entry, messages)`：将已记录会话日志中的普通 loop 分片和显式标记的本地压缩输出转换为脚本、读取其 header `id`/`createdAt`、并针对单次实时请求解析 `{{fromRequest:...}}` 占位符的纯辅助工具。派生的 assistant 分组必须以 `finish` 分片结束；没有该分片的分组是 `stream()` 抛出异常的指纹，必须改用 override 伴随文件表达。
 - 类型 `ReplayEntry` / `ReplayOverrideDoc` / `ReplayOverridePatch` / `SessionScript` / `ReplayConfig` / `ReplayProviderConfig` / `ReplayModelConfig` / `ReplayHandle` / `Config`。
 
 ## 插件导出形态
@@ -77,4 +77,4 @@ fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `as
 ## 已知限制与暂缓事项
 
 - **首次调用顺序脚本绑定假设串行委托**：并发运行同级 subagent 的 cut 会非确定性地将实时会话绑定到已记录脚本；在这种场景出现前暂不实现更强的键控（`XXX(concurrent-subagents)`）。
-- **只有普通 loop 分片和已完成的压缩输出才能派生**：在产生分片前直接抛出异常或取消/挂起的场景需要 `replay.override.json` 伴随文件。替换和补丁两种形式都只影响主会话；子会话脚本仍从各自日志派生。
+- **只有普通 loop 分片和带标记的本地压缩输出才能派生**：在产生分片前直接抛出异常、取消/挂起，或未标记的外部摘要器调用场景需要 `replay.override.json` 伴随文件。替换和补丁两种形式都只影响主会话；子会话脚本仍从各自日志派生。
diff --git a/packages/support/llm-replay/src/index.ts b/packages/support/llm-replay/src/index.ts
index 8733a4296c..abed4258af 100644
--- a/packages/support/llm-replay/src/index.ts
+++ b/packages/support/llm-replay/src/index.ts
@@ -177,8 +177,9 @@ export function parseSessionHeader(text: string): { id: string; createdAt: numbe
  * Reconstruct the per-`stream()` replay script from a recorded session log.
  *
  * Splits `assistant/chunk` events at every `finish`, using turn and step changes
- * to detect an unterminated prior call. A complete `compact/summary.rawOutput`
- * becomes a canonical successful stream at the summary's log position. A
+ * to detect an unterminated prior call. A `compact/summary` explicitly marked
+ * as one local LLM-stream call becomes a canonical successful stream from its
+ * complete `rawOutput` at the summary's log position. A
  * missing assistant terminator means the live stream threw, so derivation
  * rejects and the scenario must provide an explicit override. Multiple calls
  * may share one turn and step when the loop retries.
@@ -204,7 +205,10 @@ export function deriveReplayScript(events: SessionEvent[]): ReplayEntry[] {
       close(currentKey, current)
       currentKey = undefined
       current = []
-      if (event.data.rawOutput !== undefined) {
+      if (event.data.llmStreamCall === true) {
+        if (event.data.rawOutput === undefined) {
+          throw new Error('llm-replay: compact/summary marks an LLM stream call without rawOutput')
+        }
         const chunks: StreamChunk[] = []
         for (const [index, block] of event.data.rawOutput.entries()) {
           chunks.push({ type: 'block-start', index, blockType: block.type })
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index 9483a4c4f6..7baa6249b9 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -202,6 +202,7 @@ describe('deriveReplayScript', () => {
         data: {
           summary: rawOutput,
           rawOutput,
+          llmStreamCall: true,
           shadowedRange: { start: 1, end: 1 },
           shadowedSeqs: [1],
           shadowedTokenCount: 20,
@@ -238,6 +239,45 @@ describe('deriveReplayScript', () => {
     expect(deriveReplayScript([event])).toEqual([])
   })
 
+  it('does not infer a local LLM call from external compact output', () => {
+    const block = { type: 'text' as const, text: 'remote summary' }
+    const event: SessionEvent<'compact/summary'> = {
+      type: 'compact/summary',
+      seq: 1,
+      time: 0,
+      data: {
+        summary: [block],
+        rawOutput: [block],
+        shadowedRange: { start: 1, end: 1 },
+        shadowedSeqs: [1],
+        shadowedTokenCount: 20,
+        provider: 'remote',
+        model: 'remote',
+      },
+    }
+
+    expect(deriveReplayScript([event])).toEqual([])
+  })
+
+  it('rejects a marked compact LLM call without its complete output', () => {
+    const event: SessionEvent<'compact/summary'> = {
+      type: 'compact/summary',
+      seq: 1,
+      time: 0,
+      data: {
+        summary: [{ type: 'text', text: 'incomplete provenance' }],
+        llmStreamCall: true,
+        shadowedRange: { start: 1, end: 1 },
+        shadowedSeqs: [1],
+        shadowedTokenCount: 20,
+        provider: 'mock',
+        model: 'mock',
+      },
+    }
+
+    expect(() => deriveReplayScript([event])).toThrow(/LLM stream call without rawOutput/)
+  })
+
   it('derives a compact/summary stream when usage is unavailable', () => {
     const block = { type: 'text' as const, text: 'summary without usage' }
     const event: SessionEvent<'compact/summary'> = {
@@ -247,6 +287,7 @@ describe('deriveReplayScript', () => {
       data: {
         summary: [block],
         rawOutput: [block],
+        llmStreamCall: true,
         shadowedRange: { start: 1, end: 1 },
         shadowedSeqs: [1],
         shadowedTokenCount: 20,
@@ -289,6 +330,27 @@ describe('deriveReplayScript', () => {
     ]
     expect(() => deriveReplayScript(events)).toThrow(/model call 1\/1 ended without a finish chunk/)
   })
+
+  it('rejects an unfinished call at a compact summary boundary', () => {
+    const events: SessionEvent[] = [
+      chunkEvent(1, 1, 1, { type: 'block-start', index: 0, blockType: 'text' }),
+      {
+        type: 'compact/summary',
+        seq: 2,
+        time: 0,
+        data: {
+          summary: [{ type: 'text', text: 'external checkpoint' }],
+          shadowedRange: { start: 1, end: 1 },
+          shadowedSeqs: [1],
+          shadowedTokenCount: 20,
+          provider: 'external',
+          model: 'external',
+        },
+      },
+    ]
+
+    expect(() => deriveReplayScript(events)).toThrow(/model call 1\/1 ended without a finish chunk/)
+  })
 })
 
 describe('loadReplayScript', () => {

From 37e4e1585b9e2cc123b9f47d7b996318d022da7f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 14:45:23 +0800
Subject: [PATCH 231/516] fix(compact): enforce replay provenance

---
 .../core-data-structures/compaction.i18n.yaml |  4 +--
 docs/core-data-structures/compaction.md       |  2 +-
 docs/core-data-structures/compaction.zh.md    |  2 +-
 docs/persistence-catalog.md                   | 29 ++++++++-------
 .../compact/compact-basic/README.i18n.yaml    |  4 +--
 packages/compact/compact-basic/README.md      |  2 +-
 packages/compact/compact-basic/README.zh.md   |  2 +-
 packages/compact/compact-basic/src/region.ts  | 10 +++---
 .../compact/compact-basic/src/summarizer.ts   | 27 +++++++-------
 .../compact-basic/tests/compact-basic.spec.ts | 13 +++++--
 packages/compact/compact/src/types.ts         | 25 +++++++------
 packages/support/llm-replay/src/index.ts      | 27 +++++++++-----
 .../llm-replay/tests/llm-replay.spec.ts       | 36 ++++++++++---------
 13 files changed, 107 insertions(+), 76 deletions(-)

diff --git a/docs/core-data-structures/compaction.i18n.yaml b/docs/core-data-structures/compaction.i18n.yaml
index c5cd2a0b38..2ad9ea8e8a 100644
--- a/docs/core-data-structures/compaction.i18n.yaml
+++ b/docs/core-data-structures/compaction.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 docs/core-data-structures/compaction.md
-compaction.md: b17dfc03c62c0453c45ca2810ef90bdce9ae9ac7
-compaction.zh.md: b904cdd3ad5bf63e968fc22fccb32c5220ab8763
+compaction.md: f1df5b83bd43136af60988dabd9dc68fe32467a2
+compaction.zh.md: 52540250d466f81f51cf7c681bb6f1436e29a12d
diff --git a/docs/core-data-structures/compaction.md b/docs/core-data-structures/compaction.md
index b17dfc03c6..f1df5b83bd 100644
--- a/docs/core-data-structures/compaction.md
+++ b/docs/core-data-structures/compaction.md
@@ -13,7 +13,7 @@ Compaction extends [`SessionEventMap`](session.md) with three event types via de
 | Event | Payload | Role |
 |---|---|---|
 | `compact/start` | `{ turn }` | acquires the log-recorded lock; a number identifies the open automatic turn, while `null` identifies a standalone manual attempt |
-| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance: the safe summary projection, optional complete provider output and usage, an `llmStreamCall: true` marker when producing the result consumed exactly one call through this context's `ctx.llm.stream()`, the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note); `rawOutput` alone does not identify the call path |
+| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance: the safe summary projection, optional complete provider output and usage, an `llmStreamCall: true` marker when producing the result consumed exactly one call through this context's `ctx.llm.stream()` (which requires complete `rawOutput`), the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note); unmarked `rawOutput` does not identify the call path |
 | `compact/end` | `{ turn, error? }` | releases the lock with the same numeric-or-null owner (`error` records an unsuccessful attempt) |
 
 The lock brackets the **whole** operation: `compact/start` is appended first, then summarization, the `compact/summary` provenance record, and the `user/message` replacement all land, and only then `compact/end`. Releasing the lock last turns a crash mid-operation into a detectable orphaned lock (a `compact/start` with no matching `compact/end`) rather than a `compact/end` that falsely claims compaction finished.
diff --git a/docs/core-data-structures/compaction.zh.md b/docs/core-data-structures/compaction.zh.md
index b904cdd3ad..52540250d4 100644
--- a/docs/core-data-structures/compaction.zh.md
+++ b/docs/core-data-structures/compaction.zh.md
@@ -13,7 +13,7 @@
 | 事件 | 载荷 | 作用 |
 |---|---|---|
 | `compact/start` | `{ turn }` | 获取日志记录的锁；数字标识打开的自动轮次，`null` 标识独立手动尝试 |
-| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance：安全摘要投影、可选的完整 provider 输出与 usage、生成结果时恰好通过此上下文的 `ctx.llm.stream()` 发起一次调用所带的 `llmStreamCall: true` 标记、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note）；单有 `rawOutput` 并不能判定调用路径 |
+| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance：安全摘要投影、可选的完整 provider 输出与 usage、生成结果时恰好通过此上下文的 `ctx.llm.stream()` 发起一次调用所带的 `llmStreamCall: true` 标记（此时必须提供完整的 `rawOutput`）、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note）；未带标记的 `rawOutput` 并不能判定调用路径 |
 | `compact/end` | `{ turn, error? }` | 使用相同的数字或 `null` 归属值释放锁（`error` 记录失败尝试） |
 
 锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 来源记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 808a03b6f4..7538892445 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -237,7 +237,7 @@ Source: [`packages/ui/commands/src/index.ts:139`](../packages/ui/commands/src/in
 'compact/end': { turn: number | null; error?: string }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:62`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:65`](../packages/compact/compact/src/types.ts)
 
 #### `compact/prune` — log-only
 
@@ -261,7 +261,7 @@ Source: [`packages/compact/compact/src/types.ts:62`](../packages/compact/compact
 }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:72`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:75`](../packages/compact/compact/src/types.ts)
 
 #### `compact/start` — log-only
 
@@ -290,16 +290,6 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
  */
 'compact/summary': {
   summary: ContentBlock[]
-  /**
-   * Complete provider output before the backend's safe summary projection;
-   * this alone does not identify the call path.
-   */
-  rawOutput?: ContentBlock[]
-  /**
-   * Present only when producing the summary consumed exactly one call
-   * through this context's `ctx.llm.stream()`.
-   */
-  llmStreamCall?: true
   shadowedRange: { start: number; end: number }
   shadowedSeqs: number[]
   shadowedTokenCount: number
@@ -316,7 +306,20 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
   maxTokens?: number
   /** Provider-reported token usage for the summarization request, when emitted. */
   usage?: TokenUsage
-}
+} & (
+  | {
+    /** Complete provider output before the backend's safe summary projection. */
+    rawOutput: ContentBlock[]
+    /** Identifies exactly one call through this context's `ctx.llm.stream()`. */
+    llmStreamCall: true
+  }
+  | {
+    /** Optional complete output from an unmarked template, remote, or other summarizer. */
+    rawOutput?: ContentBlock[]
+    /** An unmarked summary does not identify a call through this context's LLM seam. */
+    llmStreamCall?: never
+  }
+)
 ```
 
 Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md)
diff --git a/packages/compact/compact-basic/README.i18n.yaml b/packages/compact/compact-basic/README.i18n.yaml
index 062021a4c1..61b6e4e6fb 100644
--- a/packages/compact/compact-basic/README.i18n.yaml
+++ b/packages/compact/compact-basic/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/compact/compact-basic/README.md
-README.md: d1c1dfb509ae0750e1237532a829a35de5084c5e
-README.zh.md: a78887daad04d534ffed9cbd0357b76bdd908f5e
+README.md: 4241899788998a744801bb0406a15ecd70af6401
+README.zh.md: c1df4afaa1837a3b689da80cc1b49df43f60e513
diff --git a/packages/compact/compact-basic/README.md b/packages/compact/compact-basic/README.md
index d1c1dfb509..4241899788 100644
--- a/packages/compact/compact-basic/README.md
+++ b/packages/compact/compact-basic/README.md
@@ -21,7 +21,7 @@ This backend owns the compaction policy:
 - **Overflow recovery** — provider-confirmed overflow needs no capacity metadata: it bypasses normal pressure and retention, prunes, then attempts one maximal balanced head reduction while leaving the newest indivisible unit. Retry is authorized whenever `surface.replaceGeneration` advances, including when pruning lands before later summary work throws. No replacement, an exhausted target-specific cap, cancellation, or an unknown/noncanonical error preserves the original provider failure.
 - **Failure handling** — a live unmatched `compact/start` is the durable lock. An unmatched marker before a newer `session/end-seed` is stale evidence from a prior lifecycle and does not block; one after that boundary reports `busy`. Summary and changed-span failures close with an error and leave the conversation surface untouched, though the attempt remains in the log. A failed close deliberately leaves a blocking orphan. Operational pressure failures warn and continue, while overflow-recovery failure preserves the original provider error only when no earlier replacement advanced the surface. Cancellation remains authoritative after cleanup and durability.
 
-The protected `summarize()` method is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, provenance, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the safe summary plus the complete provider output, call envelope, and usage when available (`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`); `llmStreamCall: true` means producing that result consumed exactly one call through this context's `ctx.llm.stream()`, while `rawOutput` alone does not identify the call path. The transaction preserves those fields on `compact/summary`.
+The protected `summarize()` method is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, provenance, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the safe summary plus the complete provider output, call envelope, and usage when available (`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`); `llmStreamCall: true` means producing that result consumed exactly one call through this context's `ctx.llm.stream()` and requires complete `rawOutput`, while unmarked `rawOutput` does not identify the call path. The transaction preserves those fields on `compact/summary`.
 
 ## Config (`BasicCompactConfig`)
 
diff --git a/packages/compact/compact-basic/README.zh.md b/packages/compact/compact-basic/README.zh.md
index a78887daad..c1df4afaa1 100644
--- a/packages/compact/compact-basic/README.zh.md
+++ b/packages/compact/compact-basic/README.zh.md
@@ -21,7 +21,7 @@
 - **溢出恢复**：提供方已确认的溢出不需容量元数据。它会绕过常规压力与保留，执行剪枝，再尝试一次最大平衡头部缩减，并留下最新不可分单元。只要 `surface.replaceGeneration` 前进，就允许重试，包括剪枝在后续摘要工作抛出异常前已落地的情况。如果没有替换、目标特定上限已耗尽、已取消，或遇到未知／非规范错误，则保留原始提供方失败。
 - **失败处理**：活动的未匹配 `compact/start` 是持久锁。位于较新 `session/end-seed` 之前的未匹配标记，是先前生命周期留下的陈旧证据，不会阻塞；位于该边界之后的标记报告 `busy`。摘要和 span 变更失败会以错误闭合，并保持会话表层不变，但日志中仍保留该尝试。闭合失败会有意留下阻塞性的未匹配标记。压力检查中的运行故障会发出警告并继续；只有此前没有替换推进表层时，溢出恢复失败才保留原始提供方错误。完成清理与持久化后，取消仍具有最终决定权。
 
-受保护的 `summarize()` 方法是唯一的子类钩子。基于模板或远程摘要器的子类可以覆盖该方法，同时压力、保留、溯源、缩减验证与已遮蔽 token 计量仍由 `ctx.tokenMeter` 负责。钩子返回安全摘要，以及完整提供方输出、调用 envelope 和可用时的 usage（`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`）；`llmStreamCall: true` 表示生成该结果时恰好通过此上下文的 `ctx.llm.stream()` 发起了一次调用，而单有 `rawOutput` 并不能判定调用路径。事务会在 `compact/summary` 上保留这些字段。
+受保护的 `summarize()` 方法是唯一的子类钩子。基于模板或远程摘要器的子类可以覆盖该方法，同时压力、保留、溯源、缩减验证与已遮蔽 token 计量仍由 `ctx.tokenMeter` 负责。钩子返回安全摘要，以及完整提供方输出、调用 envelope 和可用时的 usage（`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`）；`llmStreamCall: true` 表示生成该结果时恰好通过此上下文的 `ctx.llm.stream()` 发起了一次调用，且必须提供完整的 `rawOutput`；未带标记的 `rawOutput` 并不能判定调用路径。事务会在 `compact/summary` 上保留这些字段。
 
 ## 配置（`BasicCompactConfig`）
 
diff --git a/packages/compact/compact-basic/src/region.ts b/packages/compact/compact-basic/src/region.ts
index 67516a830d..352603579b 100644
--- a/packages/compact/compact-basic/src/region.ts
+++ b/packages/compact/compact-basic/src/region.ts
@@ -43,7 +43,7 @@ interface PreparedCompaction extends SurfaceSelection {
   readonly input: SummarizationInput
 }
 
-interface SummarizedCompaction extends PreparedCompaction, SummaryResult {
+type SummarizedCompaction = PreparedCompaction & SummaryResult & {
   readonly checkpointMessage: UserMessage
 }
 
@@ -415,18 +415,18 @@ function commitCompactionBody(
     shadowedSeqs,
     shadowedTokenCount,
     summary,
-    rawOutput,
-    llmStreamCall,
     provider,
     model,
     maxTokens,
     usage,
     checkpointMessage,
   } = summarized
+  const callProvenance = summarized.llmStreamCall === true
+    ? { rawOutput: summarized.rawOutput, llmStreamCall: true as const }
+    : summarized.rawOutput === undefined ? {} : { rawOutput: summarized.rawOutput }
   const summaryEvent = session.append('compact/summary', {
     summary,
-    ...rawOutput === undefined ? {} : { rawOutput },
-    ...llmStreamCall === undefined ? {} : { llmStreamCall },
+    ...callProvenance,
     shadowedRange: { start, end },
     shadowedSeqs: [...shadowedSeqs],
     shadowedTokenCount,
diff --git a/packages/compact/compact-basic/src/summarizer.ts b/packages/compact/compact-basic/src/summarizer.ts
index 08aa810433..8113dcd439 100644
--- a/packages/compact/compact-basic/src/summarizer.ts
+++ b/packages/compact/compact-basic/src/summarizer.ts
@@ -85,24 +85,27 @@ export interface SummarizationInput {
 }
 
 /** Safe summary content plus the exact auxiliary call envelope recorded in provenance. */
-export interface SummaryResult {
+export type SummaryResult = {
   summary: ContentBlock[]
-  /**
-   * Complete provider output before the text-only summary projection; this
-   * alone does not identify the call path.
-   */
-  rawOutput?: ContentBlock[]
-  /**
-   * Present only when producing the summary consumed exactly one call through
-   * this context's `ctx.llm.stream()`.
-   */
-  llmStreamCall?: true
   provider: string
   model: string
   maxTokens?: number
   /** Provider-reported usage for this summarization request. */
   usage?: TokenUsage
-}
+} & (
+  | {
+    /** Complete provider output before the text-only summary projection. */
+    rawOutput: ContentBlock[]
+    /** Identifies exactly one call through this context's `ctx.llm.stream()`. */
+    llmStreamCall: true
+  }
+  | {
+    /** Optional complete output from an unmarked template, remote, or other summarizer. */
+    rawOutput?: ContentBlock[]
+    /** An unmarked result does not identify a call through this context's LLM seam. */
+    llmStreamCall?: never
+  }
+)
 
 /**
  * Run the default cache-reusing `ctx.llm.stream()` summarization call: replay
diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts
index bd04335964..0e74a77e04 100644
--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -1,9 +1,9 @@
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import BasicCompactService from '@deepseek-ai/dsh-compact-basic'
 import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic'
 import { selectCompactableRange } from '@deepseek-ai/dsh-compact-basic/src/region.ts'
-import type { SummarizationInput } from '@deepseek-ai/dsh-compact-basic/src/summarizer.ts'
+import type { SummarizationInput, SummaryResult } from '@deepseek-ai/dsh-compact-basic/src/summarizer.ts'
 import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
 import {
   resolveCompactSpec,
@@ -1166,6 +1166,15 @@ async function summarizerHarness(
 }
 
 describe('default one-shot summarizer', () => {
+  it('requires complete raw output when a subclass marks one local LLM stream call', () => {
+    expectTypeOf<{
+      summary: ContentBlock[]
+      llmStreamCall: true
+      provider: string
+      model: string
+    }>().not.toExtend<SummaryResult>()
+  })
+
   it('uses configured model/default cap, forwards cancellation, and keeps only safe text', async () => {
     const { adapter, compact } = await summarizerHarness([
       { type: 'reasoning', text: 'private' },
diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index 4ed12d1e5f..c235507c6a 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -28,16 +28,6 @@ declare module '@deepseek-ai/dsh-session' {
      */
     'compact/summary': {
       summary: ContentBlock[]
-      /**
-       * Complete provider output before the backend's safe summary projection;
-       * this alone does not identify the call path.
-       */
-      rawOutput?: ContentBlock[]
-      /**
-       * Present only when producing the summary consumed exactly one call
-       * through this context's `ctx.llm.stream()`.
-       */
-      llmStreamCall?: true
       shadowedRange: { start: number; end: number }
       shadowedSeqs: number[]
       shadowedTokenCount: number
@@ -54,7 +44,20 @@ declare module '@deepseek-ai/dsh-session' {
       maxTokens?: number
       /** Provider-reported token usage for the summarization request, when emitted. */
       usage?: TokenUsage
-    }
+    } & (
+      | {
+        /** Complete provider output before the backend's safe summary projection. */
+        rawOutput: ContentBlock[]
+        /** Identifies exactly one call through this context's `ctx.llm.stream()`. */
+        llmStreamCall: true
+      }
+      | {
+        /** Optional complete output from an unmarked template, remote, or other summarizer. */
+        rawOutput?: ContentBlock[]
+        /** An unmarked summary does not identify a call through this context's LLM seam. */
+        llmStreamCall?: never
+      }
+    )
     /**
      * Marks the end of a compaction — log-only, releases the lock. Its owner
      * matches `compact/start`; `error` records an unsuccessful attempt.
diff --git a/packages/support/llm-replay/src/index.ts b/packages/support/llm-replay/src/index.ts
index abed4258af..9af72bbbec 100644
--- a/packages/support/llm-replay/src/index.ts
+++ b/packages/support/llm-replay/src/index.ts
@@ -1,7 +1,7 @@
 /**
  * Keyless snapshot-test LLM replay. It derives one model-call script per
- * recorded session from `assistant/chunk` events and durable compaction
- * summaries, then binds fresh live sessions to parent/child scripts by
+ * recorded session from `assistant/chunk` events and explicitly marked local
+ * compaction calls, then binds fresh live sessions to parent/child scripts by
  * first-call order. Throw and hang cases require an explicit override because
  * a session log cannot reconstruct them alone.
  * @module @deepseek-ai/dsh-llm-replay
@@ -14,6 +14,7 @@ import type {} from '@deepseek-ai/dsh-compact'
 import { decodeStorageRecord } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import type {
+  ContentBlock,
   GenerateOptions,
   LlmModelInfo,
   LlmProviderInfo,
@@ -21,14 +22,15 @@ import type {
   ResolvedRetryPolicy,
   RetryPolicyConfig,
   StreamChunk,
+  TokenUsage,
 } from '@deepseek-ai/dsh-llm'
 import { LlmAdapter, LlmError, assertNever, resolveRetryPolicy } from '@deepseek-ai/dsh-llm'
 
 /**
  * One recorded model call. `throw` may replay prefix chunks before failing;
- * `hang` models cancellation. Chunk entries derive from ordinary model streams
- * and complete compaction outputs in JSONL; the other variants come from an
- * override sidecar.
+ * `hang` models cancellation. Derived chunk entries come from ordinary model
+ * streams and complete outputs of explicitly marked local compaction calls;
+ * an override sidecar can supply any variant.
  */
 export type ReplayEntry =
   | { kind: 'chunks'; chunks: StreamChunk[] }
@@ -205,16 +207,23 @@ export function deriveReplayScript(events: SessionEvent[]): ReplayEntry[] {
       close(currentKey, current)
       currentKey = undefined
       current = []
-      if (event.data.llmStreamCall === true) {
-        if (event.data.rawOutput === undefined) {
+      // JSONL decoding crosses an untyped durable boundary, so retain its wider
+      // shape even though current in-process producers enforce this correlation.
+      const persisted: {
+        readonly llmStreamCall?: true
+        readonly rawOutput?: ContentBlock[]
+        readonly usage?: TokenUsage
+      } = event.data
+      if (persisted.llmStreamCall === true) {
+        if (persisted.rawOutput === undefined) {
           throw new Error('llm-replay: compact/summary marks an LLM stream call without rawOutput')
         }
         const chunks: StreamChunk[] = []
-        for (const [index, block] of event.data.rawOutput.entries()) {
+        for (const [index, block] of persisted.rawOutput.entries()) {
           chunks.push({ type: 'block-start', index, blockType: block.type })
           chunks.push({ type: 'block-end', index, block })
         }
-        if (event.data.usage !== undefined) chunks.push({ type: 'usage', usage: event.data.usage })
+        if (persisted.usage !== undefined) chunks.push({ type: 'usage', usage: persisted.usage })
         chunks.push({ type: 'finish', reason: { kind: 'stop' } })
         script.push({ kind: 'chunks', chunks })
       }
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index 7baa6249b9..4be9e01c9d 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -259,23 +259,27 @@ describe('deriveReplayScript', () => {
     expect(deriveReplayScript([event])).toEqual([])
   })
 
-  it('rejects a marked compact LLM call without its complete output', () => {
-    const event: SessionEvent<'compact/summary'> = {
-      type: 'compact/summary',
-      seq: 1,
-      time: 0,
-      data: {
-        summary: [{ type: 'text', text: 'incomplete provenance' }],
-        llmStreamCall: true,
-        shadowedRange: { start: 1, end: 1 },
-        shadowedSeqs: [1],
-        shadowedTokenCount: 20,
-        provider: 'mock',
-        model: 'mock',
-      },
-    }
+  it('rejects a persisted marked compact LLM call without its complete output', () => {
+    const [event] = parseSessionLog([
+      JSON.stringify({ type: 'session', version: 0, id: 'invalid-compact', createdAt: 0 }),
+      JSON.stringify({
+        type: 'compact/summary',
+        seq: 1,
+        time: 0,
+        data: {
+          summary: [{ type: 'text', text: 'incomplete provenance' }],
+          llmStreamCall: true,
+          shadowedRange: { start: 1, end: 1 },
+          shadowedSeqs: [1],
+          shadowedTokenCount: 20,
+          provider: 'mock',
+          model: 'mock',
+        },
+      }),
+    ].join('\n'))
 
-    expect(() => deriveReplayScript([event])).toThrow(/LLM stream call without rawOutput/)
+    expect(() => deriveReplayScript(event === undefined ? [] : [event]))
+      .toThrow(/LLM stream call without rawOutput/)
   })
 
   it('derives a compact/summary stream when usage is unavailable', () => {

From 49dff10abd50452666f994714eec298974738aa6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 14:45:37 +0800
Subject: [PATCH 232/516] fix(workspace-context): commit projections after tool
 steps

---
 .../2026-06-24-workspace-context.i18n.yaml    |   4 +-
 .../feature/2026-06-24-workspace-context.md   |  10 +-
 .../2026-06-24-workspace-context.zh.md        |  10 +-
 docs/event-producer-consumer.md               |   2 +-
 .../workspace-context/README.i18n.yaml        |   4 +-
 packages/context/workspace-context/README.md  |   6 +-
 .../context/workspace-context/README.zh.md    |   6 +-
 .../context/workspace-context/src/index.ts    |  68 ++++++++++-
 .../tests/workspace-context.spec.ts           | 106 +++++++++++++++++-
 9 files changed, 188 insertions(+), 28 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
index 170631b6a4..0369670aea 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.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 .agents/notes/implemented/feature/2026-06-24-workspace-context.md
-2026-06-24-workspace-context.md: 3c21b7599e6bb2dd759e4a040c1b999f1b0516cd
-2026-06-24-workspace-context.zh.md: e913ecb22b4692e1ee7b96d4f5effe2606775cf8
+2026-06-24-workspace-context.md: 53a580aee50752b7c6daeff5caa42ba6409c8885
+2026-06-24-workspace-context.zh.md: dc1d6b5dc2c9f576e7298c891a3a1145f123a8db
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.md
index 3c21b7599e..53a580aee5 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.md
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.md
@@ -14,7 +14,7 @@ The lifecycle has two distinct classes of content. The initial applicable chain
 
 ## Decision
 
-The implementation lives in `packages/context/workspace-context` as `@deepseek-ai/dsh-workspace-context`. It is a request-context extension, not a core service or a filesystem backend. The shared demo spine and Host Runtime mount it from an explicit `{ maxBytes } | false` deployment choice; `dsh web` enables a 65,536-byte budget while the Host Runtime's headless consumer disables it. The plugin consumes `agent/pre-step`, `tools/post-execute`, and the optional `ctx.fs` capability.
+The implementation lives in `packages/context/workspace-context` as `@deepseek-ai/dsh-workspace-context`. It is a request-context extension, not a core service or a filesystem backend. The shared demo spine and Host Runtime mount it from an explicit `{ maxBytes } | false` deployment choice; `dsh web` enables a 65,536-byte budget while the Host Runtime's headless consumer disables it. The plugin consumes `agent/pre-step`, immutable `tools/result` outcomes, `session/event` boundaries, and the optional `ctx.fs` capability.
 
 The plugin does not statically inject `fs`. Providerless product trees therefore boot normally and the plugin no-ops until a filesystem provider exists. All production reads go through that provider. Candidate probes resolve each path and stat the result, so a final-component symlink is followed to its target: a link to a regular file loads, while a missing path or a non-file target is a confirmed absence. Following repository-owned links across the trust boundary is a deliberate reversal of the original no-follow probe; the [instruction-symlink follow note](2026-07-21-follow-instruction-symlinks.md) owns that decision and its residual risk. The step signal and dynamic tool execution signal propagate through resolution, metadata probes, and streaming reads, so cancellation does not wait for an unrelated filesystem scan. A resolve or stat exception is classified as unavailable: it skips only that candidate and is never interpreted as the deletion of an already-loaded scope.
 
@@ -38,7 +38,7 @@ The baseline is a user-role `<system-reminder>` with `Instructions from: <path>`
 
 ### Dynamic Discovery And Refresh
 
-After a successful first-party `read`, `write`, or `edit` call, the `tools/post-execute` listener reconciles the touched descendant chain and every scope already known to the session. A newly reached scope is returned through `additionalContexts` for the next request using an `Additional instructions from: <path>` system-reminder. Under Code Mode, `run_code` defers sub-dispatch contexts onto its outer result, so the same update is appended only after the parent result rather than being injected mid-call.
+After a successful first-party `read`, `write`, or `edit` call, the immutable `tools/result` observer reconciles the touched descendant chain and every scope already known to the session, then queues an `Additional instructions from: <path>` system-reminder in the agent inbox for the next request. Under Code Mode, successful sub-dispatch touches bubble through opaque parent execution tokens until the top-level result settles. A touch produced inside an agent-loop step does not begin its asynchronous projection until the durable `step/end`; a direct tool execution outside an open step projects immediately. The two boundaries keep result and step adjacency deterministic without making the tool pipeline await filesystem discovery.
 
 A content edit appends `Updated instructions from: <path>`, states that the new content replaces the previous content, and includes the complete current file. If precedence changes from one candidate to another, the message also names the previous path and says it no longer applies. If no candidate remains, the plugin appends `Instructions removed: <path>` and states that the previously loaded instructions no longer apply.
 
@@ -50,7 +50,7 @@ Shell commands are not discovery triggers. Local bash calls start fresh shells,
 
 Every workspace context event stores versioned metadata with `{ action, scope, path, digest? }`, where `digest` is SHA-1 over the loaded content. Complete baselines additionally carry `baseline: true` and `baselineIdentity`. The model-facing prompt has no HTML comments, hidden markers, or headings that are parsed back into state.
 
-At reconciliation time the plugin scans workspace-sourced `user/message` events and derives the latest state for each visible scope. A short per-session pending map begins only after the immutable top-level `tools/result` proves an `additionalContexts` entry survived every post-execute listener, then covers the interval before the loop appends that context to the log. Each entry records the open `{ turn, step }`: an equal durable `user/message` at or after its sequence boundary confirms and removes it, while a matching `step/end` arriving first means the loop discarded its context buffer, so the plugin removes both the pending entry and its version-cache fast path. A nested Code Mode result stages its changes under the parent's opaque execution token so repeated sub-dispatches in one run do not duplicate them; the parent result rolls that provisional state back and commits only contexts retained by outer policy.
+At reconciliation time the plugin scans workspace-sourced `user/message` events and derives the latest state for each visible scope. Successful nested touches aggregate under their parent execution token, including when a later composite result is blocked; the top-level result transfers them either to the open session step or directly to a per-agent projection queue. A `step/end` releases its staged touches only after that boundary is durable, and the next `agent/pre-step` waits for the serialized projections. Each projection composes against visible history plus the current inbox and replaces the single pending workspace context instead of accumulating intermediate renderings.
 
 An unchanged path and digest is suppressed. A logged removal is a tombstone, so a reappearing candidate becomes a new `set`. Resume works from persisted metadata: a compatible visible baseline supplies comparison state rather than causing another complete baseline to be appended. If compaction removes an instruction event from the visible surface, that state no longer suppresses a later load, matching the fact that the model can no longer see it. Only changes actually included under the byte budget enter metadata or pending state, so an omitted file remains eligible on a later touch.
 
@@ -62,7 +62,7 @@ There is intentionally no watcher. Detection occurs at the next successful struc
 
 `maxBytes` is required and applies separately to a rendered baseline or one dynamic reconciliation batch; there is no implicit or unbounded render budget. Non-positive and non-finite values disable loading. When content exceeds the budget, broader files are omitted before the most-specific file is truncated. A visible `Workspace instruction budget ...` notice names omitted and truncated paths and byte counts, and output never exceeds the configured bytes.
 
-`maxSourceBytes` is a positive per-file cap with a 1 MiB default. The loader checks reported size before reading and still consumes content through `streamText()` with a running UTF-8 byte count, so missing/stale metadata cannot force an unbounded allocation. An oversized winning candidate is unavailable rather than a reason to fall through to another same-directory name. The plugin deliberately keeps no process-wide cache and never retains instruction prose. It keeps only `{ path, version, digest }` per effective scope in a `WeakMap<Session, Map<scope, state>>`: a matching provider `FsVersion` plus matching effective prompt state skips the read, while a changed version triggers a bounded read and SHA-1 confirmation. SHA-1 remains the cross-provider content identity persisted in visible structured metadata; provider versions are only an in-memory invalidation fast path. Cache transitions for model-visible changes commit only when the corresponding context survives the complete tool-result policy chain, and are invalidated if that accepted context is later dropped with its aborted step before reaching the log.
+`maxSourceBytes` is a positive per-file cap with a 1 MiB default. The loader checks reported size before reading and still consumes content through `streamText()` with a running UTF-8 byte count, so missing/stale metadata cannot force an unbounded allocation. An oversized winning candidate is unavailable rather than a reason to fall through to another same-directory name. The plugin deliberately keeps no process-wide cache and never retains instruction prose. It keeps only `{ path, version, digest }` per effective scope in a `WeakMap<Session, Map<scope, state>>`: a matching provider `FsVersion` plus matching effective prompt state skips the read, while a changed version triggers a bounded read and SHA-1 confirmation. SHA-1 remains the cross-provider content identity persisted in visible structured metadata; provider versions are only an in-memory invalidation fast path. Dynamic cache transitions occur while a serialized projection composes the one desired inbox context, and the next pre-step waits for that projection before deciding what enters the request.
 
 ## Alternatives considered
 
@@ -78,7 +78,7 @@ There is intentionally no watcher. Detection occurs at the next successful struc
 
 ## Consequences
 
-Workspace guidance is isolated per session and shared by the demo front doors, Web Host, and every tool presentation mode. Initial, nested, and changed instructions are durable and replayable. The generic session/agent context contract carries typed source data through injected messages and post-tool `additionalContexts` arrays without flattening entries.
+Workspace guidance is isolated per session and shared by the demo front doors, Web Host, and every tool presentation mode. Initial, nested, and changed instructions are durable and replayable. The generic session/agent context contract carries typed source data through inbox-staged and durably entered user messages without flattening entries.
 
 Repository text remains untrusted input. Lower-authority user-role framing, explicit precedence language, and delimiter escaping reduce risk but do not eliminate prompt injection. Following a candidate symlink to its target widens that surface to off-tree content, so the permission and sandbox layers that confine `ctx.fs` to trusted roots are the boundary that treats workspace files as data rather than authority (the [instruction-symlink follow note](2026-07-21-follow-instruction-symlinks.md) owns the residual risk).
 
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
index e913ecb22b..dc1d6b5dc2 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-该实现在 `packages/context/workspace-context` 中，包（package）名为 `@deepseek-ai/dsh-workspace-context`。它是请求上下文扩展，不是核心服务或文件系统后端。共享 demo 主干与 Host Runtime 根据显式的 `{ maxBytes } | false` 部署选择挂载它；`dsh web` 启用 65,536 字节预算，Host Runtime 的 headless 消费方则禁用它。该插件使用 `agent/pre-step`、`tools/post-execute` 和可选的 `ctx.fs` 功能。
+该实现在 `packages/context/workspace-context` 中，包（package）名为 `@deepseek-ai/dsh-workspace-context`。它是请求上下文扩展，不是核心服务或文件系统后端。共享 demo 主干与 Host Runtime 根据显式的 `{ maxBytes } | false` 部署选择挂载它；`dsh web` 启用 65,536 字节预算，Host Runtime 的 headless 消费方则禁用它。该插件使用 `agent/pre-step`、不可变的 `tools/result` 结果、`session/event` 边界和可选的 `ctx.fs` 功能。
 
 插件不会静态注入 `fs`。因此，不带提供方的产品树仍能正常启动；在文件系统提供方出现之前，插件保持无操作。所有生产读取都通过该提供方完成。候选项探测会解析每个路径并对结果执行 stat，因此会跟随最终路径组件的符号链接至其目标：指向普通文件的链接会被加载，缺失路径或非文件目标则确认为不存在。允许仓库拥有的链接跨越信任边界，是对最初不跟随探测方式的刻意反转；[跟随指令符号链接记录](2026-07-21-follow-instruction-symlinks.md)负责说明该决策及其残余风险。步骤信号与动态工具执行信号会贯穿解析、元数据探测和流式读取，因此取消不会等待无关的文件系统扫描。解析或 stat 异常归类为不可用：它只跳过该候选项，绝不被解释为已经加载的作用域被删除。
 
@@ -38,7 +38,7 @@ Status: implemented
 
 ### 动态发现与刷新
 
-第一方 `read`、`write` 或 `edit` 调用成功后，`tools/post-execute` 监听器会协调被触及的后代路径链，以及该会话已经知道的每个作用域。新到达的作用域通过 `additionalContexts` 返回，并在下一次请求中使用 `Additional instructions from: <path>` system-reminder。在 Code Mode 下，`run_code` 会把子分发上下文延后至其外层结果，因此同一更新只会在父结果之后追加，而不会在调用中途注入。
+第一方 `read`、`write` 或 `edit` 调用成功后，不可变的 `tools/result` 观察器会协调被触及的后代路径链，以及该会话已经知道的每个作用域，然后在 agent inbox 中排入一条 `Additional instructions from: <path>` system-reminder，供下一次请求使用。在 Code Mode 下，成功的子分派 touch 会沿不透明的父级执行 token 逐层上浮，直到顶层结果落定。在 agent loop 步骤内产生的 touch，须等持久 `step/end` 后才开始异步投影；打开的步骤之外直接执行工具时，则立即投影。这两个边界在不让工具流水线等待文件系统发现的前提下，保证结果／步骤的相邻关系具有确定性。
 
 内容编辑会追加 `Updated instructions from: <path>`，说明新内容取代先前内容，并包含当前的完整文件。如果优先级从一个候选项变为另一个，消息还会指出先前路径并说明它不再适用。如果没有候选项保留，插件会追加 `Instructions removed: <path>`，并说明先前加载的指令不再适用。
 
@@ -50,7 +50,7 @@ shell 命令不会触发发现。本地 bash 调用会启动全新的 shell，
 
 每个工作区上下文事件都会存储带版本的元数据，其形态为 `{ action, scope, path, digest? }`；`digest` 是对已加载内容计算的 SHA-1。完整基线还会额外携带 `baseline: true` 和 `baselineIdentity`。模型可见提示词中没有 HTML 注释、隐藏标记，也没有会被解析回状态的标题。
 
-协调时，插件扫描带工作区来源的 `user/message` 事件，并派生每个可见作用域的最新状态。一个简短的逐会话待处理映射只会在不可变的顶层 `tools/result` 证明某个 `additionalContexts` 条目经过所有 post-execute 监听器后仍然保留时开始记录；随后，它覆盖循环将该上下文追加到日志之前的间隔。每个条目记录开启状态的 `{ turn, step }`：如果相同的持久 `user/message` 出现在其序列边界或之后，该条目得到确认并被移除；如果匹配的 `step/end` 先到达，则说明循环丢弃了上下文缓冲区，插件会同时移除待处理条目及其版本缓存快速路径。嵌套的 Code Mode 结果会把变更暂存在父级的不透明执行 token 下，确保一次运行中的重复子分发不会产生重复项；父级结果会回滚这份临时状态，并且只提交外层策略保留的上下文。
+协调时，插件扫描带工作区来源的 `user/message` 事件，并派生每个可见作用域的最新状态。即使后续复合结果被拦截，成功的嵌套 touch 也会聚合到父级执行 token 下；顶层结果会将它们交给打开的会话步骤，或直接交给逐 agent 投影队列。`step/end` 只会在自身边界持久化后释放其暂存的 touch；下一次 `agent/pre-step` 会等待串行投影完成。每次投影都会根据可见历史和当前 inbox 进行组合，并替换唯一一条待处理工作区上下文，而不会累积中间渲染结果。
 
 路径和 digest 均未变化时会被抑制。日志中的移除操作是一条墓碑记录，因此重新出现的候选项会成为新的 `set`。恢复操作从持久化元数据继续工作：兼容的可见基线会提供比较状态，而不会导致再次追加完整基线。如果压缩从可见表面移除某条指令事件，该状态不再抑制后续加载，这与模型已经无法看见它的事实一致。只有真正纳入字节预算的变更才会进入元数据或待处理状态，因此被省略的文件在之后的触碰中仍有资格加载。
 
@@ -62,7 +62,7 @@ shell 命令不会触发发现。本地 bash 调用会启动全新的 shell，
 
 `maxBytes` 是必填项，分别作用于渲染后的基线或单个动态协调批次；系统不存在隐式或无界的渲染预算。非正数或非有限值会禁用加载。内容超过预算时，系统会先省略较宽泛的文件，再截断最具体的文件。可见的 `Workspace instruction budget ...` 提示会指出被省略和截断的路径与字节数，并且输出绝不超过配置字节数。
 
-`maxSourceBytes` 是正数的逐文件上限，默认为 1 MiB。loader 会在读取前检查报告的大小，同时仍通过 `streamText()` 消费内容并持续统计 UTF-8 字节数，因此缺失／陈旧的元数据无法迫使其进行无界分配。过大的胜出候选项会被视为不可用，而不是改为同目录中的下一个名称。插件刻意不保留进程级缓存，也绝不保留指令正文。它只为每个有效作用域保存 `{ path, version, digest }`，并将这些状态放在 `WeakMap<Session, Map<scope, state>>` 中：提供方 `FsVersion` 与有效提示词状态同时匹配时跳过读取；版本变化则触发有界读取和 SHA-1 确认。SHA-1 仍是持久化在可见结构化元数据中的跨提供方内容标识；提供方版本只作为内存中的失效快速路径。模型可见变更的缓存转换只有在相应上下文通过完整的工具结果策略链后才会提交；如果该已接受上下文随后与中止步骤一起被丢弃、未能进入日志，缓存转换就会失效。
+`maxSourceBytes` 是正数的逐文件上限，默认为 1 MiB。loader 会在读取前检查报告的大小，同时仍通过 `streamText()` 消费内容并持续统计 UTF-8 字节数，因此缺失／陈旧的元数据无法迫使其进行无界分配。过大的胜出候选项会被视为不可用，而不是改为同目录中的下一个名称。插件刻意不保留进程级缓存，也绝不保留指令正文。它只为每个有效作用域保存 `{ path, version, digest }`，并将这些状态放在 `WeakMap<Session, Map<scope, state>>` 中：提供方 `FsVersion` 与有效提示词状态同时匹配时跳过读取；版本变化则触发有界读取和 SHA-1 确认。SHA-1 仍是持久化在可见结构化元数据中的跨提供方内容标识；提供方版本只作为内存中的失效快速路径。动态缓存转换发生在串行投影组合唯一一条目标 inbox 上下文时；下一次 pre-step 会等待该投影完成，再决定哪些内容进入请求。
 
 ## 考虑过的替代方案
 
@@ -78,7 +78,7 @@ shell 命令不会触发发现。本地 bash 调用会启动全新的 shell，
 
 ## 后果
 
-工作区指引按会话隔离，并由 demo 入口、Web Host 与每一种工具展示模式共享。初始、嵌套与变更指令都保持持久且可回放。通用的会话／agent 上下文契约通过注入消息与工具执行后的 `additionalContexts` 数组携带带类型的来源数据，而不会把条目展平。
+工作区指引按会话隔离，并由 demo 入口、Web Host 与每一种工具展示模式共享。初始、嵌套与变更指令都保持持久且可回放。通用的会话／agent 上下文契约通过先在 inbox 中暂存、再持久进入的 user 消息携带带类型的来源数据，而不会把条目展平。
 
 仓库文本仍是不受信任的输入。低权威 user 角色框架、显式优先级说明和分隔符转义可以降低风险，但无法消除提示词注入。跟随候选符号链接到目标，会把该攻击面扩大至树外内容；因此，把 `ctx.fs` 限制在可信根目录内的权限与沙箱层才是真正的边界，它们让系统把工作区文件当作数据而不是权威（[跟随指令符号链接记录](2026-07-21-follow-instruction-symlinks.md)负责说明残余风险）。
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 13e96e9dd8..c46ee92578 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -32,7 +32,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`loader-smoke`](../packages/support/loader-smoke), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`loader-smoke`](../packages/support/loader-smoke), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
diff --git a/packages/context/workspace-context/README.i18n.yaml b/packages/context/workspace-context/README.i18n.yaml
index 753836e528..08b1d7a675 100644
--- a/packages/context/workspace-context/README.i18n.yaml
+++ b/packages/context/workspace-context/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/context/workspace-context/README.md
-README.md: 82aee27a8fbd6a1ab0f0860226b081e28ba72e6e
-README.zh.md: 9d983f95f4e018cb8fe983d9862cf5f31f83c5f2
+README.md: 7ab21bbf8c72f8424bc8d4fdad9153c7ed8bb7e9
+README.zh.md: 7ad68759ab811cdc5e848fd686c7fad612c9b6d9
diff --git a/packages/context/workspace-context/README.md b/packages/context/workspace-context/README.md
index 82aee27a8f..7ab21bbf8c 100644
--- a/packages/context/workspace-context/README.md
+++ b/packages/context/workspace-context/README.md
@@ -8,7 +8,7 @@ Per-session workspace instruction loading for `AGENTS.md`-compatible files. The
 
 The first eligible `agent/pre-step` of each live session composes the baseline. When the downstream decision enters a nonempty first-step batch, the plugin folds the baseline into that final batch right after the claimed prompt, so the direct prompt and the durable baseline enter step 1 and reach the first request together. A rejected or empty first-step decision leaves the baseline in the agent's `next-step` inbox for a later wakeup. The loader reads `$DSH_HOME/AGENTS.md` followed by, in each directory from the project root to `agent.session.header.cwd`, every existing base candidate and then every existing local-overlay candidate. Within one directory, candidates whose content is byte-identical after trimming leading and trailing whitespace collapse to the earliest candidate in configured order, so a `CLAUDE.md` that merely duplicates its sibling `AGENTS.md` is rendered once. If a previously queued workspace context is still pending, the plugin removes and replaces that exact inbox item instead of accumulating duplicates. A resumed session retains one compatible visible baseline and appends only current-file transitions; a changed discovery, precedence, project-root, or budget identity instead folds one explicitly superseding complete baseline into the entering batch.
 
-The plugin also listens on `tools/post-execute` for successful first-party `read`, `write`, and `edit` calls. Each touch checks newly reached descendant scopes and every previously loaded scope. Each configured candidate name is an independent scope in its directory: a newly present file is attached through the result's `additionalContexts`; a changed file appends a replacement; a file that disappears or becomes a per-directory duplicate of an earlier candidate appends a removal notice. Native calls and Code Mode sub-dispatches share this path: `run_code` defers each nested context until its outer result, so the loop still appends updates after tool-call/result adjacency is complete. This follows structured filesystem activity rather than shell `cd`, because each local bash call starts a fresh shell and parsing arbitrary shell syntax would be unreliable.
+The plugin also observes immutable `tools/result` outcomes for successful first-party `read`, `write`, and `edit` calls. Each accepted touch checks newly reached descendant scopes and every previously loaded scope. Each configured candidate name is an independent scope in its directory: a newly present file queues an addition in the agent inbox; a changed file queues a replacement; a file that disappears or becomes a per-directory duplicate of an earlier candidate queues a removal notice. Native calls and Code Mode sub-dispatches share this path: nested touches bubble through opaque parent execution tokens until the top-level result settles, and touches produced inside an agent-loop step do not begin their asynchronous projection until the durable `step/end`. Direct tool executions outside an open step project immediately. This preserves tool-call/result/step adjacency without depending on filesystem timing. Discovery follows structured filesystem activity rather than shell `cd`, because each local bash call starts a fresh shell and parsing arbitrary shell syntax would be unreliable.
 
 Instruction reads use the optional `ctx.fs` provider. The plugin does not statically inject `fs`, so providerless product trees still boot and instruction loading becomes a no-op until a provider is present. It resolves each candidate and stats the result, so a final-component symlink is followed to its target: a link to a regular file loads that target's content, while a missing path or a non-file target (including a link to a directory) is a confirmed absence. A resolve or stat exception instead marks that candidate's scope temporarily unavailable. Prefix cancellation and dynamic tool cancellation propagate through resolution, metadata probes, and streaming reads. A provider failure after a file was loaded is treated as temporarily unavailable, not as proof that the file was deleted.
 
@@ -48,7 +48,7 @@ The plugin owns the complete `<system-reminder>` framing, and every injected `us
 
 ## State And Refresh
 
-Model-visible text contains no hidden state markers. Each baseline or dynamic context event instead carries a typed `workspace-instructions` source with a list of `{ action, scope, path, digest? }` changes; a complete baseline also carries `baseline: true` and a `baselineIdentity` derived from normalized discovery, precedence, project-root, and budget configuration. A matching durable `user/message` confirms a queued baseline and its candidate versions. An entering pre-step folds newly composed context into its final batch immediately after the claimed messages and removes the pending inbox copy; rejection keeps the current context queued. If a listener rewrites away a claimed workspace message without entering its replacement, a later boundary recomposes the current context. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. If the owning `step/end` arrives before a matching dynamic context reaches the log, the plugin clears that pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.
+Model-visible text contains no hidden state markers. Each baseline or dynamic context event instead carries a typed `workspace-instructions` source with a list of `{ action, scope, path, digest? }` changes; a complete baseline also carries `baseline: true` and a `baselineIdentity` derived from normalized discovery, precedence, project-root, and budget configuration. A matching durable `user/message` confirms a queued baseline and its candidate versions. An entering pre-step waits for every queued projection, folds newly composed context into its final batch immediately after the claimed messages, and removes the pending inbox copy; rejection keeps the current context queued. If a listener rewrites away a claimed workspace message without entering its replacement, a later boundary recomposes the current context. Nested results aggregate successful file touches under their parent execution token, including when a later composite result is blocked; the top-level result transfers those touches either to the currently open session step or directly to the per-agent projection queue. A `step/end` releases its staged touches only after that boundary is in durable history, and serialized projections reconcile against visible session events plus the current inbox before replacing the single pending workspace context.
 
 An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope provider cache stores only `{ path, version, digest, trimmedDigest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. The `trimmedDigest` — SHA-1 over the whitespace-trimmed content — is the per-directory duplicate key, so an unchanged file can still be removed when an earlier candidate converges on its content. Resume works because SHA-1 state is persisted in the typed source, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter the source, pending state, and version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates only the provider cache.
 
@@ -129,7 +129,7 @@ These instructions apply to work under `packages/app`. Use them as guidance when
 
 #### Token effect
 
-Each discovered scope adds bounded history tokens until compaction. Unchanged content is suppressed by visible session state plus version/digest comparison, and Code Mode defers the same message until after the outer `run_code` result.
+Each discovered scope adds bounded history tokens until compaction. Unchanged content is suppressed by visible session state plus version/digest comparison, and Code Mode defers the same message until after the outer `run_code` result and its enclosing durable step.
 
 #### KV Cache effect
 
diff --git a/packages/context/workspace-context/README.zh.md b/packages/context/workspace-context/README.zh.md
index 9d983f95f4..7ad68759ab 100644
--- a/packages/context/workspace-context/README.zh.md
+++ b/packages/context/workspace-context/README.zh.md
@@ -8,7 +8,7 @@
 
 每个实时会话第一次符合条件的 `agent/pre-step` 会组合基线。当下游决策让非空的第一步批次进入时，插件会将基线折入最终批次、紧随已领取的直接提示词之后，使直接提示词与持久基线一同进入步骤 1，并共同抵达第一次请求。reject 或空的第一步决策会将基线留在 agent 的 `next-step` inbox，等待后续唤醒。loader 先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。若之前排队的 workspace 上下文仍在等待，插件会删除并替换该确切 inbox 条目，而不会不断累积副本。恢复后的会话会保留一条兼容的可见基线，并只追加当前文件的转换；如果发现、优先级、项目根目录或预算标识发生变化，则会将一条明确取代旧基线的完整基线折入进入步骤的批次。
 
-该插件还会监听 `tools/post-execute` 中成功的第一方 `read`、`write` 和 `edit` 调用。每次 touch 都会检查新达到的后代 scope 以及之前加载的每个 scope。每个已配置候选名称都是所在目录中的独立 scope：新出现的文件通过结果的 `additionalContexts` 附加；已改变文件追加替换；文件消失或成为同一目录中较早候选文件的重复项时，追加移除通知。原生调用与 Code Mode 子分派共享该路径：`run_code` 将每个嵌套上下文延迟到外层结果，因此 loop 仍会在工具调用／结果相邻关系完成后追加更新。这种发现跟随结构化文件系统活动，而不是 shell `cd`，因为每次本地 bash 调用都启动新 shell，解析任意 shell 语法也不可靠。
+该插件还会观察第一方 `read`、`write` 和 `edit` 调用成功后产生的不可变 `tools/result`。每个已接受的 touch 都会检查新达到的后代 scope 以及之前加载的每个 scope。每个已配置候选名称都是所在目录中的独立 scope：新出现的文件会在 agent inbox 中排入一项新增；已改变文件会排入一项替换；文件消失或成为同一目录中较早候选文件的重复项时，会排入一则移除通知。原生调用与 Code Mode 子分派共享该路径：嵌套 touch 会沿不透明的父级执行 token 逐层上浮，直到顶层结果落定；在 agent loop 步骤内产生的 touch，须等持久 `step/end` 后才开始异步投影。打开的步骤之外直接执行工具时，则立即投影。这样无需依赖文件系统时序，也能保持工具调用／结果／步骤的相邻关系。这种发现跟随结构化文件系统活动，而不是 shell `cd`，因为每次本地 bash 调用都启动新 shell，解析任意 shell 语法也不可靠。
 
 指令读取使用可选 `ctx.fs` 提供方。该插件不会静态注入 `fs`，因此没有提供方的产品树仍可启动，指令加载在提供方出现前不执行任何操作。它会解析每个候选文件并对解析结果执行 stat，因此会跟随路径最后一段的 symlink 到其目标：指向常规文件的链接会加载目标内容，缺失路径或非文件目标（包括指向目录的链接）则已确认不存在。resolve 或 stat 异常会改为将该候选文件的 scope 标记为暂时不可用。前缀取消与动态工具取消会传播到解析、元数据探测与流式读取。文件加载后的提供方失败会视为暂时不可用，而非文件已删除的证据。
 
@@ -48,7 +48,7 @@ These instructions apply to work under `packages/app`. Use them as guidance when
 
 ## 状态与刷新
 
-模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整基线还会携带 `baseline: true`，以及从规范化的发现、优先级、项目根目录和预算配置派生的 `baselineIdentity`。匹配的持久 `user/message` 会确认已排队基线及其候选版本。进入步骤的 pre-step 会把新组合的上下文折入最终批次，位置紧随已领取的消息，并移除 inbox 中仍待处理的副本；reject 则让当前上下文继续排队。若监听器改写掉已领取的 workspace 消息，又没有让替代消息进入，后续边界会重新组合当前上下文。每次相关工具 touch 时，插件会从可见会话事件重建已加载状态，并叠加一个短暂内存 pending 窗口，用于不可变顶层 `tools/result` 上存在但 loop 尚未追加的上下文。如果所属 `step/end` 在匹配的动态上下文进入日志之前到达，插件会清除该 pending 转换及其版本快速路径，使下一次成功 touch 可以重新加载。嵌套 Code Mode 结果会在外层执行 token 下暂存 pending 变更，用于抑制同次运行中的重复项；外层结果会回滚该状态，再只重新提交经过外层策略的上下文。
+模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整基线还会携带 `baseline: true`，以及从规范化的发现、优先级、项目根目录和预算配置派生的 `baselineIdentity`。匹配的持久 `user/message` 会确认已排队基线及其候选版本。进入步骤的 pre-step 会等待所有已排队投影完成，再把新组合的上下文折入最终批次，位置紧随已领取的消息，并移除 inbox 中仍待处理的副本；reject 则让当前上下文继续排队。若监听器改写掉已领取的 workspace 消息，又没有让替代消息进入，后续边界会重新组合当前上下文。即使后续复合结果被拦截，成功的嵌套文件 touch 也会聚合到父级执行 token 下；顶层结果会将这些 touch 交给当前打开的会话步骤，或直接交给逐 agent 投影队列。`step/end` 只会在自身边界进入持久历史后释放其暂存的 touch；串行投影会根据可见会话事件和当前 inbox 协调状态，再替换唯一一条待处理工作区上下文。
 
 路径与 SHA-1 内容 digest 都未变时，不会重复注入。每会话、每 scope 提供方 cache 只存储 `{ path, version, digest, trimmedDigest }`：当提供方的不透明 `FsVersion` 与有效可见状态都匹配时，对账会跳过内容读取；版本改变会在任何模型可见更新之前触发有界读取与 SHA-1 确认。`trimmedDigest` 是针对去除空白后内容的 SHA-1，也是每目录重复 key，因此较早候选文件与某个未更改文件的内容收敛后，后者仍可被移除。恢复可行，因为 SHA-1 状态持久化在带类型的来源中，而空的内存版本 cache 只会导致一次确认读取。压缩（compaction）会在 scope 的上下文事件离开可见表层后重新启用它，即使缓存版本未变。移除是 tombstone，因此候选文件之后重新出现时会重新加载。只有在字节预算内实际渲染的模型可见变更才会进入来源、pending 状态和版本 cache；已省略变更仍可在后续 touch 处理，而相同 digest 的版本刷新只更新提供方 cache。
 
@@ -129,7 +129,7 @@ These instructions apply to work under `packages/app`. Use them as guidance when
 
 #### Token 影响
 
-每个已发现 scope 都会添加有界历史 token，直到压缩。可见会话状态与版本／digest 比较会抑制未更改内容，Code Mode 将同一消息延迟到外层 `run_code` 结果之后。
+每个已发现 scope 都会添加有界历史 token，直到压缩。可见会话状态与版本／digest 比较会抑制未更改内容，Code Mode 将同一消息延迟至外层 `run_code` 结果及其所属持久步骤之后。
 
 #### KV Cache 影响
 
diff --git a/packages/context/workspace-context/src/index.ts b/packages/context/workspace-context/src/index.ts
index ac1f2b638e..fee08f2c08 100644
--- a/packages/context/workspace-context/src/index.ts
+++ b/packages/context/workspace-context/src/index.ts
@@ -14,7 +14,7 @@ import { isDeepStrictEqual } from 'node:util'
 import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
-import type { ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+import type { ToolExecution, ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
 import { Config, resolveConfig, workspaceBaselineIdentity, type ResolvedConfig } from './config.ts'
 import { findProjectRoot, loadBaselineInstructionSet } from './files.ts'
 import {
@@ -85,15 +85,22 @@ export function apply(ctx: Context, config: Config): void {
     excludedScopes: ReadonlySet<string>
   }>()
   const projectionLifecycle = new AbortController()
+  type ProjectionTouch = { agent: Agent; path: string }
+  const executionTouches = new Map<ToolExecutionToken, ProjectionTouch[]>()
   ctx.effect(
     () => () => {
       projectionLifecycle.abort(new Error('workspace-context disposed'))
+      executionTouches.clear()
     },
     'workspace-context.projectionLifecycle',
   )
   // Emit listeners are not awaited, so each projection must compose against the
   // inbox produced by earlier file results for the same agent.
   const projectionTails = new WeakMap<Agent, Promise<void>>()
+  // Execution ancestry and the enclosing durable step are the two commit
+  // boundaries before an asynchronous projection may mutate the agent inbox.
+  const openSteps = new WeakMap<Session, boolean>()
+  const stepTouches = new WeakMap<Session, ProjectionTouch[]>()
 
   const compose = async (
     agent: Agent,
@@ -272,6 +279,46 @@ export function apply(ctx: Context, config: Config): void {
     while ((projection = projectionTails.get(agent)) !== undefined) await projection
   }
 
+  const stepIsOpen = (session: Session): boolean => {
+    const known = openSteps.get(session)
+    if (known !== undefined) return known
+    let open = false
+    for (const event of session.events) {
+      if (event.type === 'step/start') open = true
+      else if (event.type === 'step/end' || event.type === 'turn/end') open = false
+    }
+    openSteps.set(session, open)
+    return open
+  }
+
+  const projectTouch = (touch: ProjectionTouch): void => {
+    const session = touch.agent.session
+    if (!stepIsOpen(session)) {
+      queueProjection(touch.agent, touch.path)
+      return
+    }
+    const pending = stepTouches.get(session)
+    if (pending === undefined) stepTouches.set(session, [touch])
+    else pending.push(touch)
+  }
+
+  ctx.on('session/event', (session, event) => {
+    if (event.type === 'step/start') {
+      openSteps.set(session, true)
+      return
+    }
+    if (event.type === 'turn/end') {
+      openSteps.set(session, false)
+      return
+    }
+    if (event.type !== 'step/end') return
+    openSteps.set(session, false)
+    const pending = stepTouches.get(session)
+    if (pending === undefined) return
+    stepTouches.delete(session)
+    for (const touch of pending) queueProjection(touch.agent, touch.path)
+  })
+
   ctx.on('agent/pre-step', async (
     { agent, messages, step, signal },
     next,
@@ -301,9 +348,20 @@ export function apply(ctx: Context, config: Config): void {
   })
 
   ctx.on('tools/result', (exec: ToolExecution, result: ToolExecutionResult) => {
-    if (result.isError || exec.agent === undefined || exec.signal.aborted) return
-    const ownPath = filePathFromExecution(exec)
-    if (ownPath === undefined) return
-    queueProjection(exec.agent, ownPath)
+    const touches = executionTouches.get(exec.token) ?? []
+    executionTouches.delete(exec.token)
+    if (!result.isError && exec.agent !== undefined && !exec.signal.aborted) {
+      const ownPath = filePathFromExecution(exec)
+      if (ownPath !== undefined) touches.push({ agent: exec.agent, path: ownPath })
+    }
+    if (exec.parent !== undefined) {
+      if (touches.length > 0) {
+        const parentTouches = executionTouches.get(exec.parent)
+        if (parentTouches === undefined) executionTouches.set(exec.parent, touches)
+        else parentTouches.push(...touches)
+      }
+      return
+    }
+    for (const touch of touches) projectTouch(touch)
   })
 }
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 20bb993447..0af12596cc 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -187,9 +187,11 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent {
   }
 }
 
-function stubToolExecution(input: Omit<ToolExecution, 'token'>): ToolExecution {
+function stubToolExecution(
+  input: Omit<ToolExecution, 'token'> & { token?: ToolExecutionToken },
+): ToolExecution {
   return {
-    token: Symbol('workspace-context-test-execution') as ToolExecutionToken,
+    token: input.token ?? Symbol('workspace-context-test-execution') as ToolExecutionToken,
     ...input,
   }
 }
@@ -3948,6 +3950,106 @@ describe('dynamic nested workspace context injection', () => {
     }
   })
 
+  it('defers a nested file projection until the enclosing step commits', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    const ctx = new Context()
+    try {
+      await ctx.plugin(RecordingFileSystem)
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
+      const fs = ctx.fs as RecordingFileSystem
+      fs.entries.set(join(root, '.git'), { type: 'directory' })
+      fs.entries.set(join(root, 'pkg/AGENTS.md'), { type: 'file', content: 'nested package rule' })
+      const agent = stubAgent(root)
+      const turnStart = agent.session.append('turn/start', { turn: 1 })
+      ctx.emit('session/event', agent.session, turnStart)
+      const stepStart = agent.session.append('step/start', { turn: 1, step: 1 })
+      ctx.emit('session/event', agent.session, stepStart)
+      const outerToken = Symbol('outer-code-run') as ToolExecutionToken
+
+      ctx.emit('tools/result', stubToolExecution({
+        token: Symbol('nested-read') as ToolExecutionToken,
+        parent: outerToken,
+        signal: testToolSignal,
+        callId: CallId('nested-read'),
+        name: 'read',
+        arguments: { file_path: join('pkg', 'file.txt') },
+        agent,
+      }), { content: [], isError: false, value: null })
+      ctx.emit('tools/result', stubToolExecution({
+        token: Symbol('nested-non-file') as ToolExecutionToken,
+        parent: outerToken,
+        signal: testToolSignal,
+        callId: CallId('nested-non-file'),
+        name: 'search',
+        arguments: {},
+        agent,
+      }), { content: [], isError: false, value: null })
+      ctx.emit('tools/result', stubToolExecution({
+        token: Symbol('second-nested-read') as ToolExecutionToken,
+        parent: outerToken,
+        signal: testToolSignal,
+        callId: CallId('second-nested-read'),
+        name: 'read',
+        arguments: { file_path: join('pkg', 'second.txt') },
+        agent,
+      }), { content: [], isError: false, value: null })
+      ctx.emit('tools/result', stubToolExecution({
+        token: outerToken,
+        signal: testToolSignal,
+        callId: CallId('outer-code-run'),
+        name: 'run_code',
+        arguments: {},
+        agent,
+      }), { content: [], isError: false, value: null })
+
+      await syncWorkspaceContext(ctx, agent)
+      expect(agent.inbox.nextStep).toEqual([])
+
+      const stepEnd = agent.session.append('step/end', { turn: 1, step: 1 })
+      ctx.emit('session/event', agent.session, stepEnd)
+      expect(blocksText((await syncedWorkspaceContext(ctx, agent)).content))
+        .toContain('nested package rule')
+    } finally {
+      await ctx.fiber.dispose()
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('seeds closed step state from existing session history', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    const ctx = new Context()
+    try {
+      await ctx.plugin(RecordingFileSystem)
+      const fs = ctx.fs as RecordingFileSystem
+      fs.entries.set(join(root, '.git'), { type: 'directory' })
+      fs.entries.set(join(root, 'pkg/AGENTS.md'), { type: 'file', content: 'nested package rule' })
+      const agent = stubAgent(root)
+      agent.session.append('turn/start', { turn: 1 })
+      agent.session.append('step/start', { turn: 1, step: 1 })
+      agent.session.append('step/end', { turn: 1, step: 1 })
+      agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
+
+      ctx.emit('tools/result', stubToolExecution({
+        signal: testToolSignal,
+        callId: CallId('read-after-closed-step'),
+        name: 'read',
+        arguments: { file_path: join('pkg', 'file.txt') },
+        agent,
+      }), { content: [], isError: false, value: null })
+
+      expect(blocksText((await syncedWorkspaceContext(ctx, agent)).content))
+        .toContain('nested package rule')
+    } finally {
+      await ctx.fiber.dispose()
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
   it('ignores failed, aborted, agentless, and non-file final results', async () => {
     const ctx = new Context()
     try {

From ec556b7cedf51a8f264534033e6d9656dfd82ab4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 14:52:11 +0800
Subject: [PATCH 233/516] docs: refresh replay config source link

---
 docs/config-catalog.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index afc8cd302a..649f425c36 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -891,7 +891,7 @@ export interface ReplayModelConfig {
 
 Depends on: [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
 
-Source: [`packages/support/llm-replay/src/index.ts:735`](../packages/support/llm-replay/src/index.ts)
+Source: [`packages/support/llm-replay/src/index.ts:744`](../packages/support/llm-replay/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-retry`
 

From 408de0f5883970d91f9daf9b76bc437e2447a4d5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:29:53 +0800
Subject: [PATCH 234/516] docs: propose semantic composer chain phases

---
 ...8-semantic-composer-chain-phases.i18n.yaml |  6 +++
 ...26-08-08-semantic-composer-chain-phases.md | 46 +++++++++++++++++++
 ...08-08-semantic-composer-chain-phases.zh.md | 46 +++++++++++++++++++
 3 files changed, 98 insertions(+)
 create mode 100644 .agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
 create mode 100644 .agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.md
 create mode 100644 .agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md

diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
new file mode 100644
index 0000000000..c70cbb870b
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.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/proposed/architecture/2026-08-08-semantic-composer-chain-phases.md
+2026-08-08-semantic-composer-chain-phases.md: 7d85518e9d5e5aa3e44e443cb1b90b325b0ffc6a
+2026-08-08-semantic-composer-chain-phases.zh.md: a202b9bfeb9276cdccaa7b438036cd1236a33317
diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.md b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.md
new file mode 100644
index 0000000000..7d85518e9d
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.md
@@ -0,0 +1,46 @@
+# Agent Note: Semantic phases for composer-chain election
+
+Status: proposed
+
+English | [中文](2026-08-08-semantic-composer-chain-phases.zh.md)
+
+## Problem
+
+The browser's `conversation.composer` chain orders every candidate by one global numeric `priority`, then elects the first selector returning a match. Question uses the default priority `0`, approval uses `1`, and the one-shot or unavailable-parent read-only subagent composer uses `-10`. A selected one-shot history can therefore show the read-only explanation while an answerable question or approval is pending underneath it.
+
+The defect is not one incorrect number. The chain currently uses the same scalar for two different decisions: whether a candidate resolves an existing interaction or restricts starting new work, and the local preference between candidates of the same semantic kind. Any numeric repair preserves that hidden coupling and lets a later registrant recreate the bug.
+
+## Proposal
+
+A chain declaration may define an ordered tuple of domain-owned phases. `conversation.composer` declares `['interaction', 'restriction']`; every registration on that phased chain must name one phase, and its numeric `priority` orders entries only within that phase. `SlotCore` sorts by declared phase index, then local priority, then stable registration order. Registration fails immediately when a phased chain entry omits its phase or names one outside the declaration. Unphased chains retain their current numeric behavior.
+
+Question and approval register in `interaction`, retaining their current within-phase order of question before approval. `SubagentReadOnlyComposer` registers in `restriction` with an ordinary local priority. The domain rule is precise: an interaction resolves a live Host wait that already exists; a restriction prevents the user from initiating work through the ordinary composer. Resolving an existing wait is not a new follow-up to the one-shot child, so the interaction phase goes first. Once the wait resolves, the chain re-elects and the read-only restriction becomes visible again.
+
+The phase vocabulary belongs to the declaring slot, not to the slot framework globally. `SlotMap` carries the exact phase tuple for compile-time registration, and the runtime `SlotSpec` repeats that tuple as the sorting authority. Other chains acquire no composer terminology and need no migration unless they deliberately declare phases.
+
+This proposal extends the [Web subagent conversation](../../implemented/feature/2026-07-27-web-subagent-conversations.md), [Web permission and approval](../../implemented/feature/2026-07-23-web-permission-and-approval.md), and [plan-review presentation](../../implemented/feature/2026-07-30-plan-review-presentation-intent.md) contracts; it supersedes none of them. The [runtime-owned child guard](../../implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md) remains the authority that prevents new child-owned human waits. No active Agent Note should be archived when this proposal lands.
+
+## Alternatives considered
+
+**Move the read-only priority after question and approval.** This is the smallest tactical fix, but it leaves semantic dominance encoded as undocumented number spacing and makes the next composer kind guess at the same global scale.
+
+**Make the read-only selector decline whenever `interactions` is non-empty.** This fixes the current pair but makes a restriction plugin understand every actionable domain and duplicates election policy across selectors. A new interaction kind would require edits in unrelated restrictions.
+
+**Rely only on the runtime child guard.** The guard fixes new model calls but cannot define browser ordering for already-pending waits, rolling-version overlap, or other interaction kinds such as approval. Runtime authority and presentation election are separate invariants.
+
+**Render all matching takeovers as a stack.** The composer has one action seat. Stacking question, approval, and read-only surfaces makes keyboard focus and answer ownership ambiguous instead of selecting one current action.
+
+## Acceptance criteria
+
+- `SlotCore` tests prove phase order dominates arbitrary local priorities, local priority and stable registration order still work within a phase, unknown or omitted phases fail loud, and unphased chains are unchanged.
+- Composer tests cover question plus read-only, approval plus read-only, question plus approval plus read-only, resolution back to read-only, and the all-declined InputBar fallback. Question remains ahead of approval within `interaction`.
+- Disposal, HMR re-registration, and reconnect replay cannot leave a stale elected phase; election remains a pure function of the current owner props and current registrations.
+- A keyless assembled Web snapshot pins a one-shot addressed conversation with a pending interaction, the interaction surface winning, its resolution, and the read-only surface returning afterward.
+- Slot, conversation, question, permission, and subagent README/JSDoc contracts describe phase ownership and the interaction-before-restriction rule together.
+- The change modifies no model-visible tool definition, system-prompt section, request routing, or session event. Browser election therefore has no token cost and no KV-cache invalidation; tests compare the model request header before and after the client-only transition.
+
+## Risks
+
+Phase names can become a vague substitute for design. Each phased slot therefore owns a short ordering rule and rejects entries that cannot state which side they belong to. A future hard safety surface that must preempt answering should not be mislabeled `restriction`; it needs an explicit earlier phase or a boundary outside this composer chain.
+
+The generic slot types and stored-entry shape gain one conditional field, so an incomplete migration could compile in one face yet fail at runtime. The exact tuple is repeated in the runtime declaration specifically to make that drift mechanically rejectable. Concurrent questions and approvals remain a single-surface policy; this proposal preserves their current order rather than solving multi-interaction queueing.
diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
new file mode 100644
index 0000000000..a202b9bfeb
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
@@ -0,0 +1,46 @@
+# Agent Note: composer 链选举的语义阶段
+
+Status: proposed
+
+[English](2026-08-08-semantic-composer-chain-phases.md) | 中文
+
+## 问题
+
+浏览器的 `conversation.composer` 链先按一个全局数值 `priority` 对所有候选项排序，再选出第一个返回匹配项的选择器。问题采用默认优先级 `0`，审批采用 `1`，一次性或父级不可用时使用的只读 subagent composer 采用 `-10`。因此，选中一次性 subagent 历史记录后，即使其下方有等待应答的问题或审批，界面仍可能显示只读说明。
+
+该缺陷并非某个数值有误。当前链用同一个标量作出两项不同的决策：候选项究竟用于解决现有交互，还是用于限制发起新工作；以及如何确定同一语义类别内各候选项的局部优先顺序。任何数值修复都会保留这种隐式耦合，让后续注册方可以再次引入同一缺陷。
+
+## 提案
+
+链声明可以定义由所属领域拥有的有序阶段元组。`conversation.composer` 声明 `['interaction', 'restriction']`；该分阶段链上的每项注册都必须指名一个阶段，其数值 `priority` 只在该阶段内排序。`SlotCore` 依次按声明的阶段索引、局部优先级和稳定注册顺序排序。如果分阶段链的注册项省略阶段，或指名声明外的阶段，注册会立即失败。未分阶段的链继续沿用当前的数值排序行为。
+
+问题与审批注册到 `interaction`，并保留问题先于审批的现有阶段内顺序。`SubagentReadOnlyComposer` 以普通局部优先级注册到 `restriction`。领域规则定义明确：交互用于使 Host 上已经存在且仍有效的等待完成；限制则阻止用户通过普通 composer 发起工作。完成现有等待并非向一次性子级发送新的后续消息，因此交互阶段排在前面。等待完成后，链会重新选举，只读限制会再次出现。
+
+阶段词汇归声明该 slot 的领域所有，而不属于全局 slot 框架。`SlotMap` 携带确切的阶段元组，用于编译期注册；运行时 `SlotSpec` 重复该元组，作为排序依据。其他链不会获得任何 composer 术语，也无需迁移，除非它们主动声明阶段。
+
+本提案扩展 [Web subagent 对话](../../implemented/feature/2026-07-27-web-subagent-conversations.md)、[Web 权限与审批](../../implemented/feature/2026-07-23-web-permission-and-approval.md)和[计划审阅呈现](../../implemented/feature/2026-07-30-plan-review-presentation-intent.md)契约，但不取代其中任何一项。[运行时所有权子级守卫](../../implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md)仍然是防止子级新建自己负责的人类等待的权威机制。本提案落地时，不应归档任何活跃 Agent Note。
+
+## 备选方案
+
+**把只读项的优先级移到问题和审批之后。** 这是最小的战术修复，但它仍以未记载的数值间距编码语义支配关系，并迫使下一种 composer 类型在同一个全局尺度上猜测自身位置。
+
+**当 `interactions` 非空时，让只读选择器拒绝匹配。** 这可以修复当前这一对组件，但会迫使限制插件理解每个可操作领域，并在各选择器中重复选举策略。每新增一种交互类型，都需要修改与其无关的限制项。
+
+**只依赖运行时子级守卫。** 该守卫可以修复新的模型调用，但无法定义浏览器对已有待处理等待、滚动升级中的版本重叠或审批等其他交互类型的排序。运行时权限与呈现选举是两项独立的不变量。
+
+**把所有匹配的接管界面渲染成一个栈。** composer 只有一个操作席位。同时堆叠问题、审批和只读界面，会使键盘焦点与回答所有权含混不清，而不是选出一个当前操作。
+
+## 验收标准
+
+- `SlotCore` 测试证明阶段顺序优先于任意局部优先级；局部优先级和稳定注册顺序在阶段内仍然有效；未知或缺失的阶段会明确失败；未分阶段的链保持不变。
+- Composer 测试覆盖问题加只读项、审批加只读项、问题加审批加只读项、解决后回到只读项，以及所有选择器均拒绝匹配时回退到 InputBar。问题在 `interaction` 内仍排在审批之前。
+- dispose（资源释放）、HMR（热模块替换）重新注册和重新连接回放均不能留下陈旧的当选阶段；选举仍是当前所有者 props 与当前注册项的纯函数。
+- 一项无密钥组装 Web 快照固定已寻址的 one-shot 对话及其待处理交互：交互界面胜出，解决该交互后，只读界面再次出现。
+- slot、conversation、question、permission 和 subagent 的 README／JSDoc 契约共同描述阶段所有权以及交互先于限制的规则。
+- 该变更不修改任何模型可见的工具定义、系统提示词章节、请求路由或会话事件。因此，浏览器选举既不产生 token 开销，也不会使 KV Cache 失效；测试会比较仅在客户端发生状态转换前后的模型请求 header。
+
+## 风险
+
+阶段名称可能沦为含混的设计替代品。因此，每个分阶段 slot 都要拥有一条简短的排序规则，并拒绝无法说明自身归属哪一侧的注册项。未来如有必须优先于回答操作的硬性安全界面，不应将其误标为 `restriction`；它需要一个显式排在更前的阶段，或位于该 composer 链以外的边界。
+
+通用 slot 类型与已存储条目形态会增加一个条件字段，因此迁移不完整时，代码可能在一个 face 中通过编译，却在运行时失败。之所以在运行时声明中重复确切元组，正是为了让系统能以机械方式拒绝这种漂移。并发问题与审批仍采用单界面策略；本提案保留其当前顺序，不解决多交互排队问题。

From dc64c5f1c2d5146c6905863fd39040e3689948e6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:30:08 +0800
Subject: [PATCH 235/516] fix: guard human interaction by runtime ownership

---
 ...-ask-user-delegated-caller-guard.i18n.yaml |   4 +-
 ...6-08-01-ask-user-delegated-caller-guard.md |  26 +-
 ...8-01-ask-user-delegated-caller-guard.zh.md |  26 +-
 docs/cordis-catalog/services.md               |  14 +-
 .../user-interaction.i18n.yaml                |   4 +-
 docs/core-data-structures/user-interaction.md |   4 +-
 .../user-interaction.zh.md                    |   4 +-
 .../child-question.cordis.snapshot.yml        |  50 ++
 examples/acp-agent/child-question.cordis.yml  |  14 +
 examples/acp-agent/tests/acp.snapshot.ts      |  14 +
 .../tests/fixtures/child-question-tripwire.ts |  17 +
 .../input.json                                |   7 +
 .../session.1.jsonl                           |  29 +
 .../session.jsonl                             |  28 +
 .../stdout.expected.jsonl                     |   4 +
 .../tool-schemas.expected.json                | 565 ++++++++++++++++++
 .../cordis/tool-cordis/src/api-catalog.ts     |   2 +-
 .../plan/plan-mode/tests/plan-mode.spec.ts    |  42 +-
 packages/ui/tool-ask-user/README.i18n.yaml    |   4 +-
 packages/ui/tool-ask-user/README.md           |   2 +-
 packages/ui/tool-ask-user/README.zh.md        |   2 +-
 .../tool-ask-user/tests/tool-ask-user.spec.ts |  34 +-
 packages/ui/user-interaction/README.i18n.yaml |   4 +-
 packages/ui/user-interaction/README.md        |   8 +-
 packages/ui/user-interaction/README.zh.md     |   8 +-
 packages/ui/user-interaction/src/index.ts     |  34 +-
 .../tests/user-interaction.spec.ts            |  66 +-
 27 files changed, 935 insertions(+), 81 deletions(-)
 create mode 100644 examples/acp-agent/child-question.cordis.snapshot.yml
 create mode 100644 examples/acp-agent/child-question.cordis.yml
 create mode 100644 examples/acp-agent/tests/fixtures/child-question-tripwire.ts
 create mode 100644 examples/acp-agent/tests/snapshots/subagent-child-question-rejection/input.json
 create mode 100644 examples/acp-agent/tests/snapshots/subagent-child-question-rejection/session.1.jsonl
 create mode 100644 examples/acp-agent/tests/snapshots/subagent-child-question-rejection/session.jsonl
 create mode 100644 examples/acp-agent/tests/snapshots/subagent-child-question-rejection/stdout.expected.jsonl
 create mode 100644 examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json

diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
index 800a575f3b..39bf79e628 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.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 .agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
-2026-08-01-ask-user-delegated-caller-guard.md: 17c5e42a1d12c018507c6cf410129bb17099e967
-2026-08-01-ask-user-delegated-caller-guard.zh.md: 38f059ba87ac5208cca6cb94ba9ee5223a6987b0
+2026-08-01-ask-user-delegated-caller-guard.md: 0350a7383f7ace6ecd742c98db18f8b977720cf9
+2026-08-01-ask-user-delegated-caller-guard.zh.md: 9c19722feb4586e07845fd20279574301267542d
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
index 17c5e42a1d..0350a7383f 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
@@ -1,4 +1,4 @@
-# Agent Note: Reject ask_user_question from delegated subagents
+# Agent Note: Reject human interaction from runtime-owned subagents
 
 Status: implemented
 
@@ -6,24 +6,34 @@ English | [中文](2026-08-01-ask-user-delegated-caller-guard.zh.md)
 
 ## Problem
 
-A delegated subagent that calls the `ask_user_question` tool blocks indefinitely. The tool pauses for a human answer, but a child context has no human answerer, so no answer ever arrives and the subagent run hangs until it is cancelled externally.
+A one-shot subagent that calls `ask_user_question` can block indefinitely. The call waits for a human answer, but the child has no independently owned human channel, so the child's completion and the parent waiting on that completion both stall.
+
+Durable session lineage cannot decide whether an answerer exists. A child session may later be resumed as a new top-level runtime root, while a live runtime-owned child may carry a zero or absent durable delegation depth. Error guidance at the shared seam must also fit every consumer: `exit_plan_mode` uses `ctx.userInteraction.ask()` without calling `ask_user_question`.
 
 ## Decision
 
-`UserInteractionService.ask()` rejects any request whose calling agent is a delegated subagent — `request.agent.session.header.delegationDepth > 0` — with a new `UserInteractionError` code `DELEGATED_CALLER` and the message `ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent`. The check runs at the top of `ask()`, after the aborted/empty guards and before intent validation, so no provider interaction happens for a rejected child. This mirrors the goal tools' top-level-only authority (`create_goal` rejects non-top-level agents with a direct-human-turn requirement).
+When `AskUserQuestionRequest.agent` is present, `UserInteractionService.ask()` authenticates the exact live agent through `ctx.agents` and admits it only when `ctx.agents.roots()` contains that instance. A missing registry or stale same-id object fails with `CALLER_NOT_LIVE`; a live agent owned by another live agent fails with `DELEGATED_CALLER`. The check runs after the existing aborted and empty-batch guards and before intent validation or provider dispatch, so an owned child never creates a UI wait.
+
+Runtime ownership is the authority. A lineage-bearing session resumed without an owner is a runtime root and may ask; a live child remains ineligible even when its durable `delegationDepth` is zero. Agentless programmatic calls retain the existing provider path.
+
+The shared failure text is consumer-neutral and actionable: the child includes the unresolved question or decision in its final result. The parent already receives that result through the delegation contract and can decide whether to ask the human. Neither the service nor a child claims an upward messaging or answer-forwarding capability that does not exist.
+
+This safety boundary is independent of the browser's composer election. The proposed [semantic composer phases](../../proposed/architecture/2026-08-08-semantic-composer-chain-phases.md) address how an already-pending interaction and a read-only subagent surface should be ordered; they do not weaken this runtime guard.
 
 ## Alternatives considered
 
-**Leave the child blocked until the parent forwards an answer.** Rejected: no answerer exists in the child context and no forwarding seam exists; the observed behavior is a permanent hang.
+**Use `session.header.delegationDepth > 0`.** Rejected because durable lineage survives resume and does not attest the current process-local owner. It rejects valid resumed roots and can admit a live child whose durable header is incomplete.
 
-**Reject inside the tool (`dsh-tool-ask-user`) instead of the service.** Rejected: that consumer seam is bypassed by direct callers of `ctx.userInteraction.ask()`; the operation boundary that owns the decision is the service itself.
+**Reject only inside `dsh-tool-ask-user`.** Rejected because `exit_plan_mode` and direct callers share `ctx.userInteraction.ask()`. The service is the narrow operation boundary common to every human-interaction consumer.
 
-**Warn children off via the model-facing description.** Rejected: the rejection is already a loud, self-explanatory error, and a description edit would not stop the hang for a model that calls anyway.
+**Tell the child to delegate upward or wait for forwarding.** Rejected because one-shot delegation exposes no child-to-parent request channel and no answer-forwarding protocol. The only guaranteed return path is the child's final result.
+
+**Rely on the browser composer fix.** Rejected because presentation cannot make an ownerless human channel exist, and non-browser deployments still need the call to terminate.
 
 ## Consequences
 
-Delegated subagent calls fail fast with a stable error instead of hanging; a child that needs a decision must delegate the question to the top-level agent. Programmatic askers without an agent and top-level agents (`delegationDepth` absent or 0) are unaffected and still reach the provider. The `DELEGATED_CALLER` code joins the documented `UserInteractionError` taxonomy in the package READMEs, and the model-facing description is unchanged.
+Runtime-owned child calls fail fast with a stable structured error instead of hanging. Exact live roots and agentless programmatic calls remain eligible, including resumed sessions with historical child lineage. `ask_user_question` and `exit_plan_mode` receive the same neutral corrective guidance, while their model-visible schemas and system-prompt prefixes remain unchanged; only the appended error result differs, so existing KV-cache prefixes remain reusable.
 
 ## Testing
 
-Two new unit tests exercise the guard: `user-interaction.spec.ts` asserts that `ask()` rejects with `DELEGATED_CALLER` and never calls the provider for a session created with `{ meta: { delegationDepth: 1 } }`, plus a positive control at `delegationDepth: 0`; `tool-ask-user.spec.ts` asserts that a tool call from a delegated agent surfaces the structured error and never reaches the provider. Both packages pass, as does the parent `packages/ui` scope, and the two touched `src` files hold 100% per-file coverage.
+Service tests cover a zero-depth live child, a depth-one resumed runtime root, a missing registry, a stale same-id object, and provider non-invocation on every rejection. Tool and plan-mode tests prove both consumers surface the neutral `DELEGATED_CALLER` result and never reach the provider. The keyless assembled snapshot delegates to a child that attempts `ask_user_question`, pins the child's error tool result and final handoff, and proves the parent completes instead of waiting for an answer.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
index 38f059ba87..9c19722feb 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 拒绝委托子代理调用 ask_user_question
+# Agent Note: 拒绝运行时中归属于其他 agent 的 subagent 向人类发起交互
 
 Status: implemented
 
@@ -6,24 +6,34 @@ Status: implemented
 
 ## 问题
 
-委托子代理调用 `ask_user_question` 工具时会无限阻塞。该工具会暂停等待人类回答，但子代理上下文中没有人类应答者，因此永远等不到回答，子代理运行只能被外部取消。
+一次性 subagent 调用 `ask_user_question` 时可能无限阻塞。该调用会等待人类回答，但子级没有由自身独立拥有的人类交互通道，因此子级无法完成，等待其完成的父级也会随之停滞。
+
+持久化会话谱系无法判断应答者是否存在。子会话之后可能恢复为新的顶层运行时根，而运行时中归属于其他 agent（智能体）的存活子级，其持久化委托深度却可能为零或缺失。共享 seam 上的错误指引还必须适用于每个消费方：`exit_plan_mode` 会使用 `ctx.userInteraction.ask()`，但不会调用 `ask_user_question`。
 
 ## 决策
 
-`UserInteractionService.ask()` 拒绝任何调用方为委托子代理的请求 —— `request.agent.session.header.delegationDepth > 0` —— 抛出新的 `UserInteractionError`，代码为 `DELEGATED_CALLER`，消息为 `ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent`。该检查位于 `ask()` 开头，在已中止/空问题守卫之后、意图校验之前，因此被拒绝的子代理不会触发任何提供方交互。这与 goal 工具仅限顶层代理的权限保持一致（`create_goal` 以直接人工回合要求拒绝非顶层代理）。
+如果存在 `AskUserQuestionRequest.agent`，`UserInteractionService.ask()` 会通过 `ctx.agents` 验证该 agent 就是注册表中的存活实例，并且只在 `ctx.agents.roots()` 包含该实例时才允许调用。缺失注册表或传入仅 id 相同的陈旧对象时，以 `CALLER_NOT_LIVE` 失败；存活 agent 归属于另一个存活 agent 时，以 `DELEGATED_CALLER` 失败。该检查位于现有的已中止和空批次守卫之后、意图校验或提供方分派之前，因此归属于其他 agent 的子级绝不会触发 UI 等待。
+
+以运行时所有权为权限依据。携带谱系的会话在无所有者的情况下恢复时就是运行时根，可以提问；存活子级即使持久化 `delegationDepth` 为零，仍无资格提问。不带 agent 的程序化调用继续沿用现有提供方路径。
+
+共享失败文本与具体消费方无关，并给出可执行指引：子级把尚未解决的问题或决策写入最终结果。委托契约本就会把该结果传给父级，父级可据此决定是否询问人类。服务和子级都不会宣称存在实际上并不存在的向上消息传递或回答转发能力。
+
+该安全边界与浏览器的 composer 选举相互独立。提议的[语义 composer 阶段](../../proposed/architecture/2026-08-08-semantic-composer-chain-phases.md)解决已有待处理交互与只读 subagent 界面的排序方式；它不会削弱此运行时守卫。
 
 ## 备选方案
 
-**让子代理一直阻塞，直到父代理转发回答。** 不予采用：子代理上下文中不存在应答者，也没有任何转发 seam；实际观察到的行为就是永久挂起。
+**使用 `session.header.delegationDepth > 0`。** 不予采用：持久化谱系会在恢复后继续存在，却不能证明当前进程内所有者。该方案会拒绝有效的已恢复根，也可能放行持久化 header 不完整的存活子级。
 
-**在工具（`dsh-tool-ask-user`）而非服务中拒绝。** 不予采用：直接调用 `ctx.userInteraction.ask()` 的调用方会绕过该消费方 seam；拥有此决策权的操作边界是服务本身。
+**仅在 `dsh-tool-ask-user` 内拒绝。** 不予采用：`exit_plan_mode` 与直接调用方共用 `ctx.userInteraction.ask()`。服务是所有人机交互消费方共同经过的最窄操作边界。
 
-**通过模型侧描述来警告子代理。** 不予采用：拒绝本身已是响亮且自解释的错误，而且修改描述并不能阻止仍然去调用的模型造成挂起。
+**让子级向上委托或等待转发。** 不予采用：一次性委托没有公开从子级向父级请求的通道，也没有回答转发协议。唯一有保证的返回路径是子级的最终结果。
+
+**依赖浏览器的 composer 修复。** 不予采用：呈现方式无法凭空产生由所有者负责的人类通道，非浏览器部署仍然需要该调用能够终止。
 
 ## 影响
 
-委托子代理的调用会以稳定错误快速失败，而不是挂起；需要决策的子代理必须把问题转交给顶层代理。不带 agent 的程序化调用方以及顶层代理（`delegationDepth` 缺省或为 0）不受影响，仍会到达提供方。`DELEGATED_CALLER` 代码已加入包 README 中记载的 `UserInteractionError` 分类，模型侧描述保持不变。
+运行时中归属于其他 agent 的子级调用会以稳定的结构化错误快速失败，而不是挂起。注册表中的确切存活根和不带 agent 的程序化调用仍有资格提问，包括带有历史子级谱系的已恢复会话。`ask_user_question` 与 `exit_plan_mode` 会收到相同的中性纠正指引，而其模型可见 schema 和系统提示词前缀保持不变；只有追加的错误结果发生变化，因此现有 KV Cache 前缀仍可复用。
 
 ## Testing
 
-两个新的单元测试覆盖该守卫：`user-interaction.spec.ts` 断言以 `{ meta: { delegationDepth: 1 } }` 创建的会话调用 `ask()` 会以 `DELEGATED_CALLER` 拒绝且绝不调用提供方，并补充了 `delegationDepth: 0` 的正向对照；`tool-ask-user.spec.ts` 断言委托子代理发出的工具调用会呈现结构化错误且绝不触达提供方。两个包均通过，父级 `packages/ui` 作用域也通过，且两个被改动的 `src` 文件保持 100% 逐文件覆盖率。
+服务测试覆盖持久化深度为零的存活子级、深度为一的已恢复运行时根、缺失注册表、仅 id 相同的陈旧对象，以及每次拒绝都不调用提供方。工具与 plan-mode 测试证明两个消费方都会呈现中性的 `DELEGATED_CALLER` 结果，且绝不触达提供方。无密钥组装快照委托一个尝试调用 `ask_user_question` 的子级，固定其错误工具结果和最终交接，并证明父级可以完成，而不是一直等待回答。
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 1b13e21948..c46b3e8521 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2627,15 +2627,17 @@ registerProvider(provider: UserInteractionProvider): () => void
 /**
  * Ask the active UI provider and wait for the user's answer.
  *
- * Human-interaction requests are only valid from a top-level agent: a
- * delegated subagent has no human answerer in its own context, so asking
- * there would block forever. This mirrors the goal tools' top-level-only
- * authority (`create_goal` rejects non-top-level agents).
+ * When a caller supplies an agent, human interaction is valid only for the
+ * exact live runtime root. Runtime ownership, not durable session lineage,
+ * decides this boundary: an owned child has no human answerer and would
+ * block forever, while a lineage-bearing session resumed as a new runtime
+ * root may ask normally.
  *
  * @param request Questions, owner agent, and abort signal.
  * @returns The answer chosen or typed by the human.
- * @throws {UserInteractionError} code `DELEGATED_CALLER` when the calling
- *   agent is a delegated subagent (`session.header.delegationDepth > 0`).
+ * @throws {UserInteractionError} code `CALLER_NOT_LIVE` when a supplied
+ *   agent is not the registry's exact live instance, or `DELEGATED_CALLER`
+ *   when that live agent is owned by another agent.
  */
 async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 ```
diff --git a/docs/core-data-structures/user-interaction.i18n.yaml b/docs/core-data-structures/user-interaction.i18n.yaml
index 50087c9f56..5480052231 100644
--- a/docs/core-data-structures/user-interaction.i18n.yaml
+++ b/docs/core-data-structures/user-interaction.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 docs/core-data-structures/user-interaction.md
-user-interaction.md: dd9dc4f98e6517e016d224e6bed25a511c2a4256
-user-interaction.zh.md: 669fbe04c76039e637a162e4de817dc5704fedeb
+user-interaction.md: 73727cbb754f10633d3213f67f7c3c9fdb215500
+user-interaction.zh.md: b6e95af4026e58c63c713d87ee9a86b3712b311f
diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md
index dd9dc4f98e..73727cbb75 100644
--- a/docs/core-data-structures/user-interaction.md
+++ b/docs/core-data-structures/user-interaction.md
@@ -70,14 +70,14 @@ interface AskUserQuestionItem {
 
 ## Ask request
 
-`AskUserQuestionRequest` is the cross-package request. `questions` is an array so a UI can present related prompts in one flow while preserving a stable id per answer.
+`AskUserQuestionRequest` is the cross-package request. `questions` is an array so a UI can present related prompts in one flow while preserving a stable id per answer. When present, `agent` is the exact live caller; the interaction seam admits it only while the live registry identifies that instance as a runtime root.
 
 ```ts type-equiv
 /** Request for a human answer. */
 interface AskUserQuestionRequest {
   /** Questions to display. */
   questions: AskUserQuestionItem[]
-  /** Calling agent, when the request came from an agent tool call. */
+  /** Exact live calling agent, when the request came from an agent tool call. */
   agent?: Agent
   /** Abort signal for the owning tool/step. */
   signal?: AbortSignal
diff --git a/docs/core-data-structures/user-interaction.zh.md b/docs/core-data-structures/user-interaction.zh.md
index 669fbe04c7..b6e95af402 100644
--- a/docs/core-data-structures/user-interaction.zh.md
+++ b/docs/core-data-structures/user-interaction.zh.md
@@ -70,14 +70,14 @@ interface AskUserQuestionItem {
 
 ## 提问请求
 
-`AskUserQuestionRequest` 是跨包（package）的请求。`questions` 是数组，这样 UI 可以在一个流程中呈现相关提示，同时保持每个回答有稳定的 id。
+`AskUserQuestionRequest` 是跨包（package）的请求。`questions` 是数组，这样 UI 可以在一个流程中呈现相关提示，同时保持每个回答有稳定的 id。如提供 `agent`，它必须与存活调用方是同一实例；只有当当前注册表将该实例识别为运行时根时，交互 seam 才会接纳该 agent。
 
 ```ts type-equiv
 /** Request for a human answer. */
 interface AskUserQuestionRequest {
   /** Questions to display. */
   questions: AskUserQuestionItem[]
-  /** Calling agent, when the request came from an agent tool call. */
+  /** Exact live calling agent, when the request came from an agent tool call. */
   agent?: Agent
   /** Abort signal for the owning tool/step. */
   signal?: AbortSignal
diff --git a/examples/acp-agent/child-question.cordis.snapshot.yml b/examples/acp-agent/child-question.cordis.snapshot.yml
new file mode 100644
index 0000000000..4eb0c5bfb4
--- /dev/null
+++ b/examples/acp-agent/child-question.cordis.snapshot.yml
@@ -0,0 +1,50 @@
+# Keyless counterpart to child-question.cordis.yml: keep the real interaction
+# seam, model-facing tool, and tripwire provider while replacing DeepSeek with
+# per-session replay.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: llm-deepseek
+        name: '@deepseek-ai/dsh-llm-deepseek'
+        disabled: true
+      - id: sandbox
+        name: '@deepseek-ai/dsh-sandbox-local'
+        config:
+          runnerCommand:
+            - bash
+            - -c
+            - while [ "$1" != "--" ]; do shift; done; shift; exec "$@"
+            - passthrough-runner
+          runnerFailureSignatures:
+            - 'passthrough-runner: profile rejected'
+      - id: acp-agent
+        name: '@deepseek-ai/dsh-acp-demo'
+        config:
+          provider: deepseek-official
+          model: deepseek-v4-flash
+          persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
+          persistenceCompression: none
+          workspaceContext:
+            maxBytes: 65536
+          persona: |
+            You are a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}. Your bash tool runs under a file sandbox — a `[sandbox: file access denied …]` result is policy, not a command bug.
+
+            Verify your work by running the code or tests. Keep answers brief and factual.
+      - insert:
+          - id: llm-replay
+            name: '@deepseek-ai/dsh-llm-replay'
+            config:
+              providers:
+                - id: deepseek-official
+                  name: DeepSeek
+                  models:
+                    - id: deepseek-v4-flash
+                    - id: deepseek-v4-pro
+          - id: user-interaction
+            name: '@deepseek-ai/dsh-user-interaction'
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: child-question-tripwire
+            name: './tests/fixtures/child-question-tripwire.ts'
diff --git a/examples/acp-agent/child-question.cordis.yml b/examples/acp-agent/child-question.cordis.yml
new file mode 100644
index 0000000000..803d21c35d
--- /dev/null
+++ b/examples/acp-agent/child-question.cordis.yml
@@ -0,0 +1,14 @@
+# Snapshot-only human-interaction composition. The provider is a tripwire: the
+# runtime-owned child must be rejected by the seam before any UI wait begins.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - insert:
+          - id: user-interaction
+            name: '@deepseek-ai/dsh-user-interaction'
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: child-question-tripwire
+            name: './tests/fixtures/child-question-tripwire.ts'
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index 386926e51b..c09dd7d2ed 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -40,6 +40,7 @@ const FS_CONFIG = fileURLToPath(new URL('../fs.cordis.yml', import.meta.url))
 const SESSION_QUERY_CONFIG = fileURLToPath(new URL('../session-query.cordis.yml', import.meta.url))
 const PTY_CONFIG = fileURLToPath(new URL('../pty.cordis.yml', import.meta.url))
 const DEPTH_TWO_CONFIG = fileURLToPath(new URL('../depth-two.cordis.yml', import.meta.url))
+const CHILD_QUESTION_CONFIG = fileURLToPath(new URL('../child-question.cordis.yml', import.meta.url))
 const SESSION_SANDBOX_ROOT_CONFIG = fileURLToPath(new URL('../session-sandbox-root.cordis.yml', import.meta.url))
 const RETRY_CONFIG = fileURLToPath(new URL('../retry.cordis.yml', import.meta.url))
 const SESSION_TITLE_CONFIG = fileURLToPath(new URL('../session-title.cordis.yml', import.meta.url))
@@ -351,6 +352,19 @@ const SCENARIOS: Scenario[] = [
     overridden: true,
     configPath: DEPTH_TWO_CONFIG,
   },
+  // Authored keyless replay through the assembled app: a one-shot child calls
+  // the real ask_user_question tool, the runtime-ownership guard rejects before
+  // the tripwire provider, and the child carries the unresolved decision in its
+  // final result so the parent can complete instead of waiting forever.
+  {
+    name: 'subagent-child-question-rejection',
+    hasModelTurn: true,
+    recorded: false,
+    pinsHeader: true,
+    headerClass: 'child-question',
+    systemPromptSource: 'text-turn',
+    configPath: CHILD_QUESTION_CONFIG,
+  },
   // The workflow tool: the model writes a one-child orchestration script; the
   // child runs as a spawn subagent under the worker-thread engine (its session is the
   // child fixture), and the tool result carries the script's return value.
diff --git a/examples/acp-agent/tests/fixtures/child-question-tripwire.ts b/examples/acp-agent/tests/fixtures/child-question-tripwire.ts
new file mode 100644
index 0000000000..7eb15ac551
--- /dev/null
+++ b/examples/acp-agent/tests/fixtures/child-question-tripwire.ts
@@ -0,0 +1,17 @@
+import type { Context } from 'cordis'
+import '@deepseek-ai/dsh-user-interaction'
+
+/** Snapshot-only provider whose invocation means the child guard failed. */
+export const name = 'child-question-tripwire'
+
+/** User-interaction service required by the tripwire provider. */
+export const inject = ['userInteraction']
+
+/** Register a provider that must remain unreachable for the delegated call. */
+export function apply(ctx: Context): void {
+  ctx.userInteraction.registerProvider({
+    async ask() {
+      throw new Error('snapshot tripwire: delegated question reached the UI provider')
+    },
+  })
+}
diff --git a/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/input.json b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/input.json
new file mode 100644
index 0000000000..d61b79c3ee
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/input.json
@@ -0,0 +1,7 @@
+{
+  "steps": [
+    { "op": "initialize" },
+    { "op": "newSession" },
+    { "op": "prompt", "text": "Delegate one question check. Ask the child to call ask_user_question once about the CUDA fallback and return any unresolved question in its final result." }
+  ]
+}
diff --git a/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/session.1.jsonl b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/session.1.jsonl
new file mode 100644
index 0000000000..68527f63ac
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/session.1.jsonl
@@ -0,0 +1,29 @@
+{"type":"session","version":0,"id":"55555555-5555-4555-8555-555555555555","createdAt":2001,"cwd":"{{cwd}}","parentSession":"44444444-4444-4444-8444-444444444444","origin":"subagent","delegationDepth":1}
+{"type":"agent/inbox/spliced","seq":0,"time":1786173701247,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Call ask_user_question once to ask whether deployment should use the CUDA fallback. If the tool returns an error, include the unresolved question verbatim in your final result."}],"source":{"kind":"user"},"role":"user","id":"106c2785-219e-46e8-8386-497ac6a98f68"}]}}
+{"type":"turn/start","seq":1,"time":1786173701247,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":1786173701247,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"subagent/descriptor","seq":3,"time":1786173701270,"data":{"version":2,"mode":"one-shot","provider":"spawn","label":"Check deployment question"}}
+{"type":"step/start","seq":4,"time":1786173701272,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":5,"time":1786173701272,"data":{"content":[{"type":"text","text":"Call ask_user_question once to ask whether deployment should use the CUDA fallback. If the tool returns an error, include the unresolved question verbatim in your final result."}],"source":{"kind":"user"},"role":"user","id":"106c2785-219e-46e8-8386-497ac6a98f68"},"surfaceOp":"append"}
+{"type":"user/message","seq":6,"time":1786173701272,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"fafefa37-7640-4c80-a00a-6a0c3ce46281"},"surfaceOp":"append"}
+{"type":"session/title","seq":7,"time":1786173701272,"data":{"title":"Call ask_user_question once to ask","messageSeqs":[5],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":8,"time":1786173701272,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","seq":9,"time":1786173701273,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":11,"time":1786173701278,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_child_question","name":"ask_user_question","argumentsDelta":"{\"questions\":[{\"id\":\"cuda-fallback\",\"header\":\"Deployment\",\"question\":\"Should deployment use the CUDA fallback?\"}]}"}}}
+{"type":"assistant/chunk","seq":12,"time":1786173701279,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_child_question","name":"ask_user_question","arguments":"{\"questions\":[{\"id\":\"cuda-fallback\",\"header\":\"Deployment\",\"question\":\"Should deployment use the CUDA fallback?\"}]}"}}}}
+{"type":"assistant/chunk","seq":13,"time":1786173701279,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":14,"time":1786173701279,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":15,"time":1786173701279,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_child_question","name":"ask_user_question","arguments":"{\"questions\":[{\"id\":\"cuda-fallback\",\"header\":\"Deployment\",\"question\":\"Should deployment use the CUDA fallback?\"}]}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"301e1969-74b2-45d8-a764-604b806f1c01"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[10,11,12,13,14],"surfaceOp":"append"}
+{"type":"tool/call","seq":16,"time":1786173701279,"data":{"turn":1,"step":1,"callId":"call_child_question","name":"ask_user_question","arguments":"{\"questions\":[{\"id\":\"cuda-fallback\",\"header\":\"Deployment\",\"question\":\"Should deployment use the CUDA fallback?\"}]}"}}
+{"type":"tool/result","seq":17,"time":1786173701292,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_child_question"},"content":[{"type":"tool-result","toolCallId":"call_child_question","content":[{"type":"text","text":"Error: human interaction is unavailable while the calling agent is owned by another live agent; include the unresolved question or decision in the child agent's final result"}],"isError":true}],"role":"user","id":"b9fc0a38-47bb-4335-a8e4-c881ed66bbc3"},"error":{"name":"UserInteractionError","code":"DELEGATED_CALLER"}},"sourceEventSeqs":[16],"surfaceOp":"append"}
+{"type":"step/end","seq":18,"time":1786173701292,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":19,"time":1786173701309,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":20,"time":1786173701314,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":21,"time":1786173701314,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"UNRESOLVED: Should deployment use the CUDA fallback?"}}}
+{"type":"assistant/chunk","seq":22,"time":1786173701314,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"UNRESOLVED: Should deployment use the CUDA fallback?"}}}}
+{"type":"assistant/chunk","seq":23,"time":1786173701314,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":4}}}}
+{"type":"assistant/chunk","seq":24,"time":1786173701315,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":25,"time":1786173701315,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"UNRESOLVED: Should deployment use the CUDA fallback?"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"5f2ada85-5967-4ed8-9e16-eaff2af847b5"},"usage":{"inputTokens":10,"outputTokens":4}},"sourceEventSeqs":[20,21,22,23,24],"surfaceOp":"append"}
+{"type":"step/end","seq":26,"time":1786173701315,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":27,"time":1786173701315,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/session.jsonl
new file mode 100644
index 0000000000..ed155f158f
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/session.jsonl
@@ -0,0 +1,28 @@
+{"type":"session","version":0,"id":"44444444-4444-4444-8444-444444444444","createdAt":2000,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"agent/inbox/spliced","seq":0,"time":1786173701174,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Delegate one question check. Ask the child to call ask_user_question once about the CUDA fallback and return any unresolved question in its final result."}],"source":{"kind":"user"},"role":"user","id":"851bea02-2961-471a-84ec-3b068c451db0"}]}}
+{"type":"turn/start","seq":1,"time":1786173701175,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":1786173701175,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":3,"time":1786173701216,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":4,"time":1786173701216,"data":{"content":[{"type":"text","text":"Delegate one question check. Ask the child to call ask_user_question once about the CUDA fallback and return any unresolved question in its final result."}],"source":{"kind":"user"},"role":"user","id":"851bea02-2961-471a-84ec-3b068c451db0"},"surfaceOp":"append"}
+{"type":"user/message","seq":5,"time":1786173701217,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"8ef74c46-9e80-475c-9093-0e85ba92e346"},"surfaceOp":"append"}
+{"type":"session/title","seq":6,"time":1786173701217,"data":{"title":"Delegate one question check. Ask","messageSeqs":[4],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":7,"time":1786173701218,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","seq":8,"time":1786173701219,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_question_child","name":"subagent","argumentsDelta":"{\"description\":\"Check deployment question\",\"prompt\":\"Call ask_user_question once to ask whether deployment should use the CUDA fallback. If the tool returns an error, include the unresolved question verbatim in your final result.\"}"}}}
+{"type":"assistant/chunk","seq":11,"time":1786173701233,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_question_child","name":"subagent","arguments":"{\"description\":\"Check deployment question\",\"prompt\":\"Call ask_user_question once to ask whether deployment should use the CUDA fallback. If the tool returns an error, include the unresolved question verbatim in your final result.\"}"}}}}
+{"type":"assistant/chunk","seq":12,"time":1786173701233,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":13,"time":1786173701233,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":14,"time":1786173701233,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_question_child","name":"subagent","arguments":"{\"description\":\"Check deployment question\",\"prompt\":\"Call ask_user_question once to ask whether deployment should use the CUDA fallback. If the tool returns an error, include the unresolved question verbatim in your final result.\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"f8909de9-23ae-4dbe-a8c1-eaf1e8f2aba5"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[9,10,11,12,13],"surfaceOp":"append"}
+{"type":"tool/call","seq":15,"time":1786173701234,"data":{"turn":1,"step":1,"callId":"call_question_child","name":"subagent","arguments":"{\"description\":\"Check deployment question\",\"prompt\":\"Call ask_user_question once to ask whether deployment should use the CUDA fallback. If the tool returns an error, include the unresolved question verbatim in your final result.\"}"}}
+{"type":"tool/result","seq":16,"time":1786173701316,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_question_child"},"content":[{"type":"tool-result","toolCallId":"call_question_child","content":[{"type":"text","text":"UNRESOLVED: Should deployment use the CUDA fallback?"}],"isError":false}],"role":"user","id":"fdc5b075-574b-48c6-bdda-1b6442edfbef"}},"sourceEventSeqs":[15],"surfaceOp":"append"}
+{"type":"step/end","seq":17,"time":1786173701317,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":18,"time":1786173701334,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":19,"time":1786173701339,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":20,"time":1786173701339,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"PARENT_COMPLETED"}}}
+{"type":"assistant/chunk","seq":21,"time":1786173701340,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"PARENT_COMPLETED"}}}}
+{"type":"assistant/chunk","seq":22,"time":1786173701340,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}}}
+{"type":"assistant/chunk","seq":23,"time":1786173701340,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":24,"time":1786173701340,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"PARENT_COMPLETED"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"700b9e56-965e-406a-bf5c-2db06b96c536"},"usage":{"inputTokens":10,"outputTokens":2}},"sourceEventSeqs":[19,20,21,22,23],"surfaceOp":"append"}
+{"type":"step/end","seq":25,"time":1786173701340,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":26,"time":1786173701340,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/stdout.expected.jsonl
new file mode 100644
index 0000000000..ef130490e8
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/stdout.expected.jsonl
@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"PARENT_COMPLETED"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
diff --git a/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json
new file mode 100644
index 0000000000..81f30ee5ec
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json
@@ -0,0 +1,565 @@
+{
+  "initial": [
+    {
+      "name": "ask_user_question",
+      "description": "Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "questions": {
+            "type": "array",
+            "description": "Questions to ask the user before continuing.",
+            "items": {
+              "type": "object",
+              "additionalProperties": true,
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "Stable id for this question; echoed in the answer."
+                },
+                "question": {
+                  "type": "string",
+                  "description": "The specific question to ask the user."
+                },
+                "header": {
+                  "type": "string",
+                  "description": "Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."
+                },
+                "options": {
+                  "type": "array",
+                  "description": "Optional choices to show the user. If you recommend one, put it first and append \"(Recommended)\" to that label.",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "properties": {
+                      "label": {
+                        "type": "string",
+                        "description": "Short user-facing option label."
+                      },
+                      "description": {
+                        "type": "string",
+                        "description": "One sentence explaining the tradeoff or impact."
+                      }
+                    },
+                    "required": [
+                      "label"
+                    ]
+                  }
+                },
+                "multi_select": {
+                  "type": "boolean",
+                  "description": "Whether the user may select more than one option. Defaults to false."
+                }
+              },
+              "required": [
+                "id",
+                "question"
+              ]
+            }
+          }
+        },
+        "required": [
+          "questions"
+        ]
+      }
+    },
+    {
+      "name": "bash",
+      "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "command": {
+            "type": "string",
+            "description": "The bash command to execute."
+          },
+          "description": {
+            "type": "string",
+            "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."
+          },
+          "timeoutMs": {
+            "type": "number",
+            "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+          },
+          "workdir": {
+            "type": "string",
+            "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+          },
+          "run_in_background": {
+            "type": "boolean",
+            "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
+          },
+          "sandbox_permissions": {
+            "type": "string",
+            "description": "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.",
+            "enum": [
+              "workspace-write",
+              "danger-full-access"
+            ]
+          },
+          "justification": {
+            "type": "string",
+            "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
+          }
+        },
+        "required": [
+          "command",
+          "description"
+        ]
+      }
+    },
+    {
+      "name": "create_goal",
+      "description": "Create one persisted same-session completion goal when the current direct human request is a long-running objective that should continue across autonomous goal rounds. You may infer that intent without requiring the user to say \"create a goal\". Do not use this for trivial single-turn work. Execution rejects non-human and subagent authority.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "objective": {
+            "type": "string",
+            "description": "The concrete completion objective inferred from the direct human request."
+          },
+          "max_goal_rounds": {
+            "type": "number",
+            "description": "Optional positive safe-integer limit on automatic continuation rounds."
+          }
+        },
+        "required": [
+          "objective"
+        ]
+      }
+    },
+    {
+      "name": "edit",
+      "description": "Edit an existing UTF-8 text file by replacing literal text.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "file_path": {
+            "type": "string",
+            "description": "Path to edit, resolved by the filesystem backend."
+          },
+          "old_string": {
+            "type": "string",
+            "description": "Literal text to replace. Must match exactly."
+          },
+          "new_string": {
+            "type": "string",
+            "description": "Literal replacement text. Use an empty string to delete the match."
+          },
+          "replace_all": {
+            "type": "boolean",
+            "description": "Replace all matches. Defaults to false; when false, old_string must appear exactly once."
+          },
+          "sandbox_permissions": {
+            "type": "string",
+            "description": "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.",
+            "enum": [
+              "workspace-write",
+              "danger-full-access"
+            ]
+          },
+          "justification": {
+            "type": "string",
+            "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access."
+          }
+        },
+        "required": [
+          "file_path",
+          "old_string",
+          "new_string"
+        ]
+      }
+    },
+    {
+      "name": "get_goal",
+      "description": "Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal.",
+      "parameters": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "parameters": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "ralph",
+      "description": "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "objective": {
+            "type": "string",
+            "description": "The immutable completion objective for every fresh Ralph round."
+          },
+          "maxRounds": {
+            "type": "number",
+            "description": "Optional positive safe-integer round cap, bounded by the deployment ceiling."
+          }
+        },
+        "required": [
+          "objective"
+        ]
+      }
+    },
+    {
+      "name": "read",
+      "description": "Read a UTF-8 text file and return line-numbered content.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "file_path": {
+            "type": "string",
+            "description": "Path to read, resolved by the filesystem backend."
+          },
+          "offset": {
+            "type": "number",
+            "description": "1-based first line to return. Defaults to 1."
+          },
+          "limit": {
+            "type": "number",
+            "description": "Maximum number of lines to return. Defaults to 2000."
+          }
+        },
+        "required": [
+          "file_path"
+        ]
+      }
+    },
+    {
+      "name": "send_message",
+      "description": "Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "subagent_id": {
+            "type": "string",
+            "description": "The subagent id returned when the background subagent was started."
+          },
+          "message": {
+            "type": "string",
+            "description": "The message to deliver to the subagent."
+          }
+        },
+        "required": [
+          "subagent_id",
+          "message"
+        ]
+      }
+    },
+    {
+      "name": "skill",
+      "description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "The exact skill name from the available skills list."
+          }
+        },
+        "required": [
+          "name"
+        ]
+      }
+    },
+    {
+      "name": "subagent",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "A short (3-5 word) description of the delegated task, for display."
+          },
+          "prompt": {
+            "type": "string",
+            "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+          },
+          "run_in_background": {
+            "type": "boolean",
+            "description": "Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."
+          }
+        },
+        "required": [
+          "description",
+          "prompt"
+        ]
+      }
+    },
+    {
+      "name": "subagent_fork",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "A short (3-5 word) description of the delegated task, for display."
+          },
+          "prompt": {
+            "type": "string",
+            "description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
+          },
+          "run_in_background": {
+            "type": "boolean",
+            "description": "Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."
+          }
+        },
+        "required": [
+          "description",
+          "prompt"
+        ]
+      }
+    },
+    {
+      "name": "task_kill",
+      "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "task_id": {
+            "type": "string",
+            "description": "Task id returned by the tool that started the background work."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Optional short reason, recorded in the log and forwarded to the task."
+          }
+        },
+        "required": [
+          "task_id"
+        ]
+      }
+    },
+    {
+      "name": "task_list",
+      "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.",
+      "parameters": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "task_output",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "task_id": {
+            "type": "string",
+            "description": "Task id returned by the tool that started the background work."
+          },
+          "wait": {
+            "type": "boolean",
+            "description": "Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."
+          },
+          "timeout_ms": {
+            "type": "number",
+            "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+          }
+        },
+        "required": [
+          "task_id"
+        ]
+      }
+    },
+    {
+      "name": "todo_write",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "todos": {
+            "type": "array",
+            "description": "The COMPLETE task list, replacing any previous list.",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "content": {
+                  "type": "string",
+                  "description": "What the task is — a short imperative line."
+                },
+                "status": {
+                  "type": "string",
+                  "description": "pending (not started) | in_progress (now) | completed (done).",
+                  "enum": [
+                    "pending",
+                    "in_progress",
+                    "completed"
+                  ]
+                }
+              },
+              "required": [
+                "content",
+                "status"
+              ]
+            }
+          }
+        },
+        "required": [
+          "todos"
+        ]
+      }
+    },
+    {
+      "name": "update_goal",
+      "description": "Update the exact current goal revision. edit, pause, and resume require a direct top-level human request. During an automatic continuation of the current goal, complete and blocked are also allowed. blocked is rejected before the configured minimum round count; the model remains responsible for judging that the same condition persisted across those rounds and must explain it in blocked_reason.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "goal_id": {
+            "type": "string",
+            "description": "Exact id returned by get_goal."
+          },
+          "revision": {
+            "type": "number",
+            "description": "Exact positive revision returned by get_goal."
+          },
+          "action": {
+            "type": "string",
+            "description": "edit | pause | resume | complete | blocked",
+            "enum": [
+              "edit",
+              "pause",
+              "resume",
+              "complete",
+              "blocked"
+            ]
+          },
+          "objective": {
+            "type": "string",
+            "description": "Replacement objective; valid only with action edit."
+          },
+          "max_goal_rounds": {
+            "type": "number",
+            "description": "Replacement cap; valid only with action edit."
+          },
+          "blocked_reason": {
+            "type": "string",
+            "description": "Concrete blocking condition; required only with action blocked."
+          }
+        },
+        "required": [
+          "goal_id",
+          "revision",
+          "action"
+        ]
+      }
+    },
+    {
+      "name": "workflow",
+      "description": "Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "script": {
+            "type": "string",
+            "description": "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."
+          },
+          "meta": {
+            "type": "object",
+            "description": "The workflow identity block (plain JSON — never code).",
+            "additionalProperties": true,
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Short kebab-case workflow name."
+              },
+              "description": {
+                "type": "string",
+                "description": "One-line description of what the workflow does."
+              },
+              "whenToUse": {
+                "type": "string",
+                "description": "Optional guidance on when this workflow applies."
+              },
+              "phases": {
+                "type": "array",
+                "description": "Optional phase declarations matched by phase() calls.",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "properties": {
+                    "title": {
+                      "type": "string",
+                      "description": "The phase title phase() calls match by exact string."
+                    },
+                    "detail": {
+                      "type": "string",
+                      "description": "Optional one-line description of the phase."
+                    },
+                    "provider": {
+                      "type": "string",
+                      "description": "Optional provider override this phase is expected to use."
+                    },
+                    "model": {
+                      "type": "string",
+                      "description": "Optional model override this phase is expected to use."
+                    }
+                  },
+                  "required": [
+                    "title"
+                  ]
+                }
+              }
+            },
+            "required": [
+              "name",
+              "description"
+            ]
+          },
+          "args": {
+            "type": "object",
+            "description": "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).",
+            "additionalProperties": true
+          }
+        },
+        "required": [
+          "script",
+          "meta"
+        ]
+      }
+    },
+    {
+      "name": "write",
+      "description": "Create or fully replace a UTF-8 text file.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "file_path": {
+            "type": "string",
+            "description": "Path to write, resolved by the filesystem backend."
+          },
+          "content": {
+            "type": "string",
+            "description": "Full UTF-8 text content to write."
+          },
+          "sandbox_permissions": {
+            "type": "string",
+            "description": "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval.",
+            "enum": [
+              "workspace-write",
+              "danger-full-access"
+            ]
+          },
+          "justification": {
+            "type": "string",
+            "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access."
+          }
+        },
+        "required": [
+          "file_path",
+          "content"
+        ]
+      }
+    }
+  ],
+  "changes": []
+}
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 1acdfbbf08..c4970a6c8e 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -1174,7 +1174,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>',
-        jsDoc: '/**\n * Ask the active UI provider and wait for the user\'s answer.\n *\n * Human-interaction requests are only valid from a top-level agent: a\n * delegated subagent has no human answerer in its own context, so asking\n * there would block forever. This mirrors the goal tools\' top-level-only\n * authority (`create_goal` rejects non-top-level agents).\n *\n * @param request Questions, owner agent, and abort signal.\n * @returns The answer chosen or typed by the human.\n * @throws {UserInteractionError} code `DELEGATED_CALLER` when the calling\n *   agent is a delegated subagent (`session.header.delegationDepth > 0`).\n */',
+        jsDoc: '/**\n * Ask the active UI provider and wait for the user\'s answer.\n *\n * When a caller supplies an agent, human interaction is valid only for the\n * exact live runtime root. Runtime ownership, not durable session lineage,\n * decides this boundary: an owned child has no human answerer and would\n * block forever, while a lineage-bearing session resumed as a new runtime\n * root may ask normally.\n *\n * @param request Questions, owner agent, and abort signal.\n * @returns The answer chosen or typed by the human.\n * @throws {UserInteractionError} code `CALLER_NOT_LIVE` when a supplied\n *   agent is not the registry\'s exact live instance, or `DELEGATED_CALLER`\n *   when that live agent is owned by another agent.\n */',
       },
     ],
   },
diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts
index 63abed59ea..3a18e44088 100644
--- a/packages/plan/plan-mode/tests/plan-mode.spec.ts
+++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts
@@ -4,7 +4,7 @@ import { createUserMessage, CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { RUN_CODE_NAME, defineContentToolFixture } from '@deepseek-ai/dsh-tools'
 import { Session, SessionId, type UserMessage } from '@deepseek-ai/dsh-session'
-import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import { createScope } from '@deepseek-ai/dsh-scope'
 import UserInteractionService, {
   UserInteractionError, type AskUserQuestionRequest,
@@ -25,7 +25,11 @@ const PLAN_CONFIG = { section: TEST_PLAN_SECTION } satisfies PlanModeConfig
  * and the following `step/start` session event used by the loop.
  */
 
-async function agentWithSession(ctx: Context, id = 'agent-1', { active }: { active?: boolean } = {}): Promise<Agent & { session: Session }> {
+async function agentWithSession(
+  ctx: Context,
+  id = 'agent-1',
+  { active, owner }: { active?: boolean; owner?: Agent } = {},
+): Promise<Agent & { session: Session }> {
   // A live store session when a store is mounted (the command executor logs
   // lifecycle events through it); bare otherwise (fold/tool-only benches).
   const session = Session.create(SessionId(id))
@@ -44,8 +48,15 @@ async function agentWithSession(ctx: Context, id = 'agent-1', { active }: { acti
   ;(agent as { ctx?: Context }).ctx = scoped
   // Seeded plan state lands before the creation announcement, matching resume.
   if (active !== undefined) session.append('plan/mode', { active })
-  // The loop announces creation after publication.
-  ctx.emit('agent/created', { agent })
+  // The loop publishes through the live registry when it is composed; narrow
+  // fold-only benches retain the direct lifecycle event used before it exists.
+  const agents = ctx.get('agents')
+  if (agents === undefined) {
+    ctx.emit('agent/created', { agent })
+  } else {
+    agents.enter(agent, owner)
+    agents.announce(agent)
+  }
   return agent
 }
 
@@ -653,6 +664,7 @@ describe('/plan', () => {
 describe('exit_plan_mode', () => {
   async function setupWithReview(answer?: { selected: string[]; custom?: string }) {
     const ctx = await setup()
+    await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)
     const asked: AskUserQuestionRequest[] = []
     if (answer !== undefined) {
@@ -730,6 +742,26 @@ describe('exit_plan_mode', () => {
     expect(foldPlanMode(agent.session.events)).toBe(true)
   })
 
+  it('rejects review from a runtime-owned agent with consumer-neutral guidance', async () => {
+    const ctx = await setup()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const ask = vi.fn(async () => ({ answers: [{ id: 'plan-review', selected: ['Approve'] }] }))
+    ctx.userInteraction.registerProvider({ ask })
+    const root = await agentWithSession(ctx, 'review-root')
+    const child = await agentWithSession(ctx, 'review-child', { active: true, owner: root })
+
+    const result = await callExit(ctx, child)
+
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{
+      type: 'text',
+      text: "Error: human interaction is unavailable while the calling agent is owned by another live agent; include the unresolved question or decision in the child agent's final result",
+    }])
+    expect(ask).not.toHaveBeenCalled()
+    expect(foldPlanMode(child.session.events)).toBe(true)
+  })
+
   it('approve: records the boundary-applied switch and confirms (the fold flips at the flush)', async () => {
     const { ctx, agent, asked } = await setupWithReview({ selected: ['Approve'] })
     const result = await callExit(ctx, agent)
@@ -765,6 +797,7 @@ describe('exit_plan_mode', () => {
     await ctx.plugin(ToolRegistry, { mode: 'code' })
     await ctx.plugin(ExitRuntime)
     await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)
     const asked: AskUserQuestionRequest[] = []
     ctx.userInteraction.registerProvider({
@@ -939,6 +972,7 @@ describe('exit_plan_mode', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     const fiber = await ctx.plugin(PlanModeService, PLAN_CONFIG)
+    await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)
     let answer!: (value: { answers: { id: string; selected: string[] }[] }) => void
     ctx.userInteraction.registerProvider({
diff --git a/packages/ui/tool-ask-user/README.i18n.yaml b/packages/ui/tool-ask-user/README.i18n.yaml
index 56a4d487a4..bbd0ba0561 100644
--- a/packages/ui/tool-ask-user/README.i18n.yaml
+++ b/packages/ui/tool-ask-user/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/tool-ask-user/README.md
-README.md: cb1cc11bba4010c885f320fc5569509ff48fccc0
-README.zh.md: 7558816a2874509717c50e22b93a548697f86ef7
+README.md: 7af356263ea6582a081e7c6de22fd317ca8b96df
+README.zh.md: 3f7b814b83c8c6957a4b2574ee69e87d45f65ae6
diff --git a/packages/ui/tool-ask-user/README.md b/packages/ui/tool-ask-user/README.md
index cb1cc11bba..7af356263e 100644
--- a/packages/ui/tool-ask-user/README.md
+++ b/packages/ui/tool-ask-user/README.md
@@ -54,5 +54,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **A pending question blocks the tool call until the human answers** — the tool declares no `timeout-policy` budget; cancellation rides the turn's `exec.signal` only.
-- **Delegated subagents cannot ask the user** — `ask_user_question` rejects calls from a delegated subagent with `DELEGATED_CALLER`; a child that needs a decision must delegate the question to the top-level agent.
+- **Runtime-owned subagents cannot ask the user** — `ask_user_question` rejects a live child owned by another agent with `DELEGATED_CALLER`; the child must include the unresolved question or decision in its final result. Durable lineage does not decide this boundary, so a lineage-bearing session resumed as a runtime root may ask normally.
 - **Native answers render as JSON text** — the canonical value remains structured, but the model-facing result uses compact JSON rather than a richer content-block vocabulary.
diff --git a/packages/ui/tool-ask-user/README.zh.md b/packages/ui/tool-ask-user/README.zh.md
index 7558816a28..3f7b814b83 100644
--- a/packages/ui/tool-ask-user/README.zh.md
+++ b/packages/ui/tool-ask-user/README.zh.md
@@ -54,5 +54,5 @@
 ## 已知限制与暂缓事项
 
 - **待处理问题会阻塞工具调用，直至用户作答**：该工具未声明 `timeout-policy` 预算；取消仅沿用当前轮次的 `exec.signal`。
-- **委托的子代理不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝来自委托子代理的调用；需要决策的子代理必须把问题转交给顶层代理。
+- **运行时中归属于其他 agent 的 subagent 不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝由另一个 agent 所有的存活子级；该子级必须在最终结果中包含尚未解决的问题或决策。持久化会话谱系不能决定这一边界，因此带有谱系的会话恢复为运行时根后可以正常提问。
 - **Native 回答渲染为 JSON 文本**：规范值仍为结构化数据，但模型侧结果使用紧凑 JSON，而非更丰富的内容块词汇。
diff --git a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts
index 9459f7753c..14e71ae15b 100644
--- a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts
+++ b/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts
@@ -1,8 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import SessionStore from '@deepseek-ai/dsh-session'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import UserInteractionService, { type AskUserQuestionRequest } from '@deepseek-ai/dsh-user-interaction'
@@ -28,6 +27,7 @@ interface OptionSchemaShape {
 
 async function setup() {
   const ctx = new Context()
+  await ctx.plugin(AgentRegistry)
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(UserInteractionService)
@@ -35,6 +35,14 @@ async function setup() {
   return ctx
 }
 
+function stubAgent(id: string, delegationDepth = 0): Agent {
+  const agentId = id as Agent['id']
+  return {
+    id: agentId,
+    session: { id: agentId, header: { delegationDepth } },
+  } as unknown as Agent
+}
+
 describe('ask_user_question tool', () => {
   it('registers a model-facing tool schema', async () => {
     const ctx = await setup()
@@ -208,9 +216,8 @@ describe('ask_user_question tool', () => {
     expect(seen[0]?.signal).toBe(controller.signal)
   })
 
-  it('passes optional header and agent through to the user-interaction request', async () => {
+  it('passes optional header and a resumed runtime root through to the user-interaction request', async () => {
     const ctx = await setup()
-    await ctx.plugin(SessionStore)
     const seen: AskUserQuestionRequest[] = []
     ctx.userInteraction.registerProvider({
       async ask(request) {
@@ -218,8 +225,8 @@ describe('ask_user_question tool', () => {
         return { answers: [{ id: 'continue', selected: ['ok'] }] }
       },
     })
-    const session = ctx.sessions.create(undefined, { meta: { delegationDepth: 0 } })
-    const agent = { session } as unknown as Agent
+    const agent = stubAgent('resumed-root', 1)
+    ctx.agents.enter(agent, undefined)
 
     const result = await ctx.tools.execute({
       signal: testToolSignal,
@@ -249,9 +256,8 @@ describe('ask_user_question tool', () => {
     })
   })
 
-  it('rejects a delegated subagent with a structured DELEGATED_CALLER error', async () => {
+  it('rejects a live runtime-owned agent with a structured DELEGATED_CALLER error', async () => {
     const ctx = await setup()
-    await ctx.plugin(SessionStore)
     const seen: AskUserQuestionRequest[] = []
     ctx.userInteraction.registerProvider({
       async ask(request) {
@@ -259,20 +265,26 @@ describe('ask_user_question tool', () => {
         return { answers: [{ id: 'continue', selected: ['ok'] }] }
       },
     })
-    const session = ctx.sessions.create(undefined, { meta: { delegationDepth: 1 } })
-    const agent = { session } as unknown as Agent
+    const root = stubAgent('root', 0)
+    const child = stubAgent('child', 0)
+    ctx.agents.enter(root, undefined)
+    ctx.agents.enter(child, root)
 
     const result = await ctx.tools.execute({
       signal: testToolSignal,
       callId: CallId('ask-delegated'),
       name: 'ask_user_question',
       arguments: { questions: [{ id: 'continue', question: 'Continue?' }] },
-      agent,
+      agent: child,
     })
 
     expect(result).toMatchObject({
       isError: true,
       error: { info: { name: 'UserInteractionError', code: 'DELEGATED_CALLER' } },
+      content: [{
+        type: 'text',
+        text: "Error: human interaction is unavailable while the calling agent is owned by another live agent; include the unresolved question or decision in the child agent's final result",
+      }],
     })
     expect(seen).toHaveLength(0)
   })
diff --git a/packages/ui/user-interaction/README.i18n.yaml b/packages/ui/user-interaction/README.i18n.yaml
index 4cf5d5b92f..1da849ed9b 100644
--- a/packages/ui/user-interaction/README.i18n.yaml
+++ b/packages/ui/user-interaction/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/user-interaction/README.md
-README.md: d5b2353485b47b3077af74699a57728063f6ce22
-README.zh.md: 460feed0e8b0634372d5e7712e4bfca19e0f5523
+README.md: cba015e782623b3a5adf018303823577a0b96774
+README.zh.md: a5f944850c5ac4e05da59e8478167eef91796610
diff --git a/packages/ui/user-interaction/README.md b/packages/ui/user-interaction/README.md
index d5b2353485..cba015e782 100644
--- a/packages/ui/user-interaction/README.md
+++ b/packages/ui/user-interaction/README.md
@@ -13,15 +13,17 @@ Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a mod
 
 ### Key Types
 
-- `AskUserQuestionRequest` — `{ questions: [{ id, question, detail?, header?, options?, multiSelect?, intent? }], agent?, signal? }`; `detail` supplies supporting text that providers render with the question without turning it into an option label.
+- `AskUserQuestionRequest` — `{ questions: [{ id, question, detail?, header?, options?, multiSelect?, intent? }], agent?, signal? }`; `detail` supplies supporting text that providers render with the question without turning it into an option label. When present, `agent` must be the registry's exact live runtime root.
 - `AskUserQuestionOption` — `{ label, description? }`.
 - `AskUserQuestionIntent` — `{ kind: 'plan-review', approve }`; the tagged presentation intent below.
 - `AskUserQuestionAnswer` — `{ answers: [{ id, selected, custom? }] }`.
 - `UserInteractionProvider` — UI implementation with `ask(request)`.
-- `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `BAD_INTENT`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, `ASK_ABORTED`, and `DELEGATED_CALLER`.
+- `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `BAD_INTENT`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, `ASK_ABORTED`, `CALLER_NOT_LIVE`, and `DELEGATED_CALLER`.
 
 For a single-select question, `custom` overrides the selected choice and `selected` is empty. For a multi-select question, `custom` may supplement the labels in `selected`. A UI may preserve a skipped item as `{ id, selected: [] }`, keeping the existing answer shape while retaining other answers in the batch.
 
+When a request carries an agent, `ask()` authenticates its exact identity through the live `AgentRegistry` and admits only a runtime root. Durable lineage is not authority: a session with historical delegation depth may ask after it is resumed as a new runtime root, while a live child owned by another agent is rejected even if its durable depth is zero. Agentless programmatic requests retain the existing provider path.
+
 ### Presentation intent
 
 `intent` declares that a question IS a decision of a known shape, so a UI that recognises the tag may present it as such — `plan-review` says `detail` is a plan under review, and `dsh-plan-mode` sets it on the `exit_plan_mode` question. An intent shapes presentation only: a UI honouring it answers with the same option labels a generic UI would send, and a UI that does not know the tag renders the generic option list, so callers read one answer shape either way. `approve` names the label that approves rather than relying on option order. `ask()` rejects with `BAD_INTENT` the two assertions no type can carry: an `approve` naming none of that question's own options, and an intent on a question with no `detail` — the thing it declares itself a review of.
@@ -32,7 +34,7 @@ This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-
 
 ## Model Experience
 
-Indirectly, through `dsh-tool-ask-user`, which retains a successful provider answer as compact JSON or one of these failures: `Error: ask_user_question was aborted before the user answered`, `Error: ask_user_question requires at least one question`, `Error: ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent`, `Error: no user-interaction provider is registered`, or `Error: <message>`. Waiting for the human adds no tokens.
+Indirectly, through `dsh-tool-ask-user`, which retains a successful provider answer as compact JSON or one of these failures: `Error: ask_user_question was aborted before the user answered`, `Error: ask_user_question requires at least one question`, `Error: human interaction requires the exact live calling agent when an agent is supplied`, `Error: human interaction is unavailable while the calling agent is owned by another live agent; include the unresolved question or decision in the child agent's final result`, `Error: no user-interaction provider is registered`, or `Error: <message>`. Waiting for the human adds no tokens.
 
 #### KV Cache effect
 
diff --git a/packages/ui/user-interaction/README.zh.md b/packages/ui/user-interaction/README.zh.md
index 460feed0e8..a5f944850c 100644
--- a/packages/ui/user-interaction/README.zh.md
+++ b/packages/ui/user-interaction/README.zh.md
@@ -13,15 +13,17 @@
 
 ### 关键类型
 
-- `AskUserQuestionRequest`：`{ questions: [{ id, question, detail?, header?, options?, multiSelect?, intent? }], agent?, signal? }`；`detail` 提供辅助文本，提供方会将其随问题一起渲染，而不会将其变成选项标签。
+- `AskUserQuestionRequest`：`{ questions: [{ id, question, detail?, header?, options?, multiSelect?, intent? }], agent?, signal? }`；`detail` 提供辅助文本，提供方会将其随问题一起渲染，而不会将其变成选项标签。如提供 `agent`，它必须与注册表中的存活运行时根 agent（智能体）是同一对象。
 - `AskUserQuestionOption`：`{ label, description? }`。
 - `AskUserQuestionIntent`：`{ kind: 'plan-review', approve }`；即下文的带标签呈现意图。
 - `AskUserQuestionAnswer`：`{ answers: [{ id, selected, custom? }] }`。
 - `UserInteractionProvider`：包含 `ask(request)` 的 UI 实现。
-- `UserInteractionError`：`HarnessError` 的子类，包含 `EMPTY_QUESTIONS`、`BAD_INTENT`、`NO_PROVIDER`、`DUPLICATE_PROVIDER`、`ASK_ABORTED` 和 `DELEGATED_CALLER` 等代码。
+- `UserInteractionError`：`HarnessError` 的子类，包含 `EMPTY_QUESTIONS`、`BAD_INTENT`、`NO_PROVIDER`、`DUPLICATE_PROVIDER`、`ASK_ABORTED`、`CALLER_NOT_LIVE` 和 `DELEGATED_CALLER` 等代码。
 
 对于单选题，`custom` 会覆盖选中的选项，且 `selected` 为空。对于多选题，`custom` 可以补充 `selected` 中的标签。UI 可以把跳过的条目保留为 `{ id, selected: [] }`，既维持现有回答形态，也保留该批次中的其他回答。
 
+请求包含 agent 时，`ask()` 会通过当前 `AgentRegistry` 验证该 agent 与注册表中的存活实例是同一对象，并且只允许运行时根调用。持久化会话谱系不构成权限依据：带有历史委托深度的会话恢复为新的运行时根后可以提问；由另一个 agent 所有的存活子级即使持久化深度为零也会被拒绝。不含 agent 的程序化请求继续沿用现有提供方路径。
+
 ### 呈现意图
 
 `intent` 声明某个问题本身就是一种已知形态的决策，因此认识该标签的 UI 可以照此呈现——`plan-review` 表示 `detail` 是一份待审阅的计划，`dsh-plan-mode` 会在 `exit_plan_mode` 的问题上设置它。意图只塑造呈现：遵循它的 UI 回答的仍是通用 UI 会发送的那些选项标签，不认识该标签的 UI 渲染通用选项列表，因此调用方两种情况下读到的都是同一种回答形态。`approve` 指名表示批准的标签，而不依赖选项顺序。有两项断言是任何类型都承载不了的，`ask()` 会以 `BAD_INTENT` 拒绝它们：`approve` 未命中该问题自身的任一选项，以及意图落在没有 `detail` 的问题上——而 `detail` 正是它自称在审阅的东西。
@@ -32,7 +34,7 @@
 
 ## 模型体验
 
-间接地，通过 `dsh-tool-ask-user`：它会将成功的提供方回答保留为紧凑 JSON，或返回以下失败之一：`Error: ask_user_question was aborted before the user answered`、`Error: ask_user_question requires at least one question`、`Error: ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent`、`Error: no user-interaction provider is registered` 或 `Error: <message>`。等待人类回答不会增加 token。
+间接地，通过 `dsh-tool-ask-user`：它会将成功的提供方回答保留为紧凑 JSON，或返回以下失败之一：`Error: ask_user_question was aborted before the user answered`、`Error: ask_user_question requires at least one question`、`Error: human interaction requires the exact live calling agent when an agent is supplied`、`Error: human interaction is unavailable while the calling agent is owned by another live agent; include the unresolved question or decision in the child agent's final result`、`Error: no user-interaction provider is registered` 或 `Error: <message>`。等待人类回答不会增加 token。
 
 #### KV Cache 影响
 
diff --git a/packages/ui/user-interaction/src/index.ts b/packages/ui/user-interaction/src/index.ts
index b7e76c1d47..761db57c65 100644
--- a/packages/ui/user-interaction/src/index.ts
+++ b/packages/ui/user-interaction/src/index.ts
@@ -28,7 +28,7 @@ export type {
 export interface AskUserQuestionRequest {
   /** Questions to display. */
   questions: AskUserQuestionItem[]
-  /** Calling agent, when the request came from an agent tool call. */
+  /** Exact live calling agent, when the request came from an agent tool call. */
   agent?: Agent
   /** Abort signal for the owning tool/step. */
   signal?: AbortSignal
@@ -77,15 +77,17 @@ export class UserInteractionService extends Service {
   /**
    * Ask the active UI provider and wait for the user's answer.
    *
-   * Human-interaction requests are only valid from a top-level agent: a
-   * delegated subagent has no human answerer in its own context, so asking
-   * there would block forever. This mirrors the goal tools' top-level-only
-   * authority (`create_goal` rejects non-top-level agents).
+   * When a caller supplies an agent, human interaction is valid only for the
+   * exact live runtime root. Runtime ownership, not durable session lineage,
+   * decides this boundary: an owned child has no human answerer and would
+   * block forever, while a lineage-bearing session resumed as a new runtime
+   * root may ask normally.
    *
    * @param request Questions, owner agent, and abort signal.
    * @returns The answer chosen or typed by the human.
-   * @throws {UserInteractionError} code `DELEGATED_CALLER` when the calling
-   *   agent is a delegated subagent (`session.header.delegationDepth > 0`).
+   * @throws {UserInteractionError} code `CALLER_NOT_LIVE` when a supplied
+   *   agent is not the registry's exact live instance, or `DELEGATED_CALLER`
+   *   when that live agent is owned by another agent.
    */
   async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer> {
     if (request.signal?.aborted) {
@@ -94,10 +96,20 @@ export class UserInteractionService extends Service {
     if (request.questions.length === 0) {
       throw new UserInteractionError('ask_user_question requires at least one question', 'EMPTY_QUESTIONS')
     }
-    if ((request.agent?.session.header.delegationDepth ?? 0) > 0) {
-      throw new UserInteractionError(
-        'ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent',
-        'DELEGATED_CALLER')
+    const agent = request.agent
+    if (agent !== undefined) {
+      const agents = this.ctx.get('agents')
+      if (agents === undefined || agents.get(agent.id) !== agent) {
+        throw new UserInteractionError(
+          'human interaction requires the exact live calling agent when an agent is supplied',
+          'CALLER_NOT_LIVE')
+      }
+      if (!agents.roots().includes(agent)) {
+        throw new UserInteractionError(
+          'human interaction is unavailable while the calling agent is owned by another live agent; '
+          + "include the unresolved question or decision in the child agent's final result",
+          'DELEGATED_CALLER')
+      }
     }
     // A presentation intent asserts two things the types cannot: that the
     // named approve label is one of this question's own options, and that a
diff --git a/packages/ui/user-interaction/tests/user-interaction.spec.ts b/packages/ui/user-interaction/tests/user-interaction.spec.ts
index 30fdf49a7e..8270b81bfd 100644
--- a/packages/ui/user-interaction/tests/user-interaction.spec.ts
+++ b/packages/ui/user-interaction/tests/user-interaction.spec.ts
@@ -1,7 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import SessionStore from '@deepseek-ai/dsh-session'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import UserInteractionService, {
   UserInteractionError,
   type AskUserQuestionRequest,
@@ -19,6 +18,14 @@ function provider(answer = 'approved'): UserInteractionProvider & { seen: AskUse
   }
 }
 
+function stubAgent(id: string, delegationDepth = 0): Agent {
+  const agentId = id as Agent['id']
+  return {
+    id: agentId,
+    session: { id: agentId, header: { delegationDepth } },
+  } as unknown as Agent
+}
+
 describe('UserInteractionService', () => {
   it('delegates ask requests to the registered provider', async () => {
     const ctx = new Context()
@@ -86,30 +93,36 @@ describe('UserInteractionService', () => {
     expect(p.ask).not.toHaveBeenCalled()
   })
 
-  it('rejects a delegated subagent before reaching the provider', async () => {
+  it('rejects a live runtime-owned agent before reaching the provider', async () => {
     const ctx = new Context()
-    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)
     const p = { ask: vi.fn(async () => ({ answers: [] })) }
     ctx.userInteraction.registerProvider(p)
-    const session = ctx.sessions.create(undefined, { meta: { delegationDepth: 1 } })
-    const agent = { session } as unknown as Agent
+    const root = stubAgent('root', 0)
+    const child = stubAgent('child', 0)
+    ctx.agents.enter(root, undefined)
+    ctx.agents.enter(child, root)
 
     await expect(ctx.userInteraction.ask({
       questions: [{ id: 'confirm', question: 'Proceed?' }],
-      agent,
-    })).rejects.toMatchObject({ name: 'UserInteractionError', code: 'DELEGATED_CALLER' })
+      agent: child,
+    })).rejects.toMatchObject({
+      name: 'UserInteractionError',
+      code: 'DELEGATED_CALLER',
+      message: "human interaction is unavailable while the calling agent is owned by another live agent; include the unresolved question or decision in the child agent's final result",
+    })
     expect(p.ask).not.toHaveBeenCalled()
   })
 
-  it('still reaches the provider for a top-level agent (delegationDepth 0)', async () => {
+  it('reaches the provider for a lineage-bearing session resumed as a runtime root', async () => {
     const ctx = new Context()
-    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)
     const p = provider('yes')
     ctx.userInteraction.registerProvider(p)
-    const session = ctx.sessions.create(undefined, { meta: { delegationDepth: 0 } })
-    const agent = { session } as unknown as Agent
+    const agent = stubAgent('resumed-root', 1)
+    ctx.agents.enter(agent, undefined)
 
     const result = await ctx.userInteraction.ask({
       questions: [{ id: 'confirm', question: 'Proceed?' }],
@@ -119,6 +132,35 @@ describe('UserInteractionService', () => {
     expect(result).toEqual({ answers: [{ id: 'confirm', selected: ['yes'] }] })
   })
 
+  it('rejects a supplied agent when no live registry can attest it', async () => {
+    const ctx = new Context()
+    await ctx.plugin(UserInteractionService)
+    const p = { ask: vi.fn(async () => ({ answers: [] })) }
+    ctx.userInteraction.registerProvider(p)
+
+    await expect(ctx.userInteraction.ask({
+      questions: [{ id: 'confirm', question: 'Proceed?' }],
+      agent: stubAgent('unattested'),
+    })).rejects.toMatchObject({ name: 'UserInteractionError', code: 'CALLER_NOT_LIVE' })
+    expect(p.ask).not.toHaveBeenCalled()
+  })
+
+  it('rejects a stale agent object that reuses a live id', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const p = { ask: vi.fn(async () => ({ answers: [] })) }
+    ctx.userInteraction.registerProvider(p)
+    const live = stubAgent('same-id')
+    ctx.agents.enter(live, undefined)
+
+    await expect(ctx.userInteraction.ask({
+      questions: [{ id: 'confirm', question: 'Proceed?' }],
+      agent: stubAgent('same-id'),
+    })).rejects.toMatchObject({ name: 'UserInteractionError', code: 'CALLER_NOT_LIVE' })
+    expect(p.ask).not.toHaveBeenCalled()
+  })
+
   it('rejects an intent whose approve label names none of its own options', async () => {
     const ctx = new Context()
     await ctx.plugin(UserInteractionService)

From b9e7db5abfe67a2b9cfd2732a57ebd8264b2ad36 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:39:19 +0800
Subject: [PATCH 236/516] fix(skill-badge): align with current base contracts

---
 apps/cli/tests/dsh-badge.snapshot.ts           | 9 +++++----
 packages/skill/skill-badge/assets/dsh-badge.md | 4 ++--
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/apps/cli/tests/dsh-badge.snapshot.ts b/apps/cli/tests/dsh-badge.snapshot.ts
index abd66e6f79..00d5278f82 100644
--- a/apps/cli/tests/dsh-badge.snapshot.ts
+++ b/apps/cli/tests/dsh-badge.snapshot.ts
@@ -62,6 +62,7 @@ describe('dsh badge assembled snapshot', () => {
       </available_skills>
 
       If the user names a skill, or the task clearly matches a skill's description, call the \`skill\` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.
+      A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the \`skill\` tool again for that skill.
       </system-reminder>",
             "type": "text",
           },
@@ -84,14 +85,14 @@ describe('dsh badge assembled snapshot', () => {
 
       - Local PNG: [\`dsh-badge.png\`](dsh-badge.png), 726×120 source image; render at 121×20
       - Shields.io image URL: \`https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white\`
-      - Project URL: \`https://github.com/deepseek-harness/deepseek-harness\`
+      - Project URL: \`https://github.com/deepseek-ai/deepseek-harness-sdk\`
 
       ## Markdown
 
       Use this linked badge in Markdown:
 
       \`\`\`markdown
-      [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+      [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
       \`\`\`
 
       If attribution should not be linked, use:
@@ -123,14 +124,14 @@ describe('dsh badge assembled snapshot', () => {
 
       - Local PNG: [\`dsh-badge.png\`](dsh-badge.png), 726×120 source image; render at 121×20
       - Shields.io image URL: \`https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white\`
-      - Project URL: \`https://github.com/deepseek-harness/deepseek-harness\`
+      - Project URL: \`https://github.com/deepseek-ai/deepseek-harness-sdk\`
 
       ## Markdown
 
       Use this linked badge in Markdown:
 
       \`\`\`markdown
-      [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+      [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
       \`\`\`
 
       If attribution should not be linked, use:
diff --git a/packages/skill/skill-badge/assets/dsh-badge.md b/packages/skill/skill-badge/assets/dsh-badge.md
index 9905de1ed9..5a789fac2f 100644
--- a/packages/skill/skill-badge/assets/dsh-badge.md
+++ b/packages/skill/skill-badge/assets/dsh-badge.md
@@ -6,14 +6,14 @@ Add the official “powered by dsh” badge without recreating or restyling it.
 
 - Local PNG: [`dsh-badge.png`](dsh-badge.png), 726×120 source image; render at 121×20
 - Shields.io image URL: `https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white`
-- Project URL: `https://github.com/deepseek-harness/deepseek-harness`
+- Project URL: `https://github.com/deepseek-ai/deepseek-harness-sdk`
 
 ## Markdown
 
 Use this linked badge in Markdown:
 
 ```markdown
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
 ```
 
 If attribution should not be linked, use:

From f6db2eb1aba6ee96839f528ea564bd14c6a19a91 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:40:01 +0800
Subject: [PATCH 237/516] chore: declare child-question snapshot fixture

---
 knip.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/knip.json b/knip.json
index bce84f9b1c..248066d8e4 100644
--- a/knip.json
+++ b/knip.json
@@ -45,6 +45,7 @@
         "headless-agent/tests/fixtures/telemetry-otel-driver.ts",
         "headless-agent/tests/fixtures/telemetry-redact-rule.ts",
         "acp-agent/tests/snapshots/lsp-definition/workspace/subject.ts",
+        "acp-agent/tests/fixtures/child-question-tripwire.ts",
         "acp-agent/tests/fixtures/partial-landlock-sandbox.ts",
         "acp-agent/tests/fixtures/subagent-durability-failure.ts",
         "acp-agent/tests/fixtures/subagent-settlement-marker.ts",

From f6449c838c17ef8fe4eca3a06ac312de2c3e7f36 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:43:06 +0800
Subject: [PATCH 238/516] docs: document delegated plan review failure

---
 packages/plan/plan-mode/README.i18n.yaml | 4 ++--
 packages/plan/plan-mode/README.md        | 1 +
 packages/plan/plan-mode/README.zh.md     | 1 +
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/plan/plan-mode/README.i18n.yaml b/packages/plan/plan-mode/README.i18n.yaml
index b29223b8e1..b24d4b1954 100644
--- a/packages/plan/plan-mode/README.i18n.yaml
+++ b/packages/plan/plan-mode/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/plan/plan-mode/README.md
-README.md: b22e218d1a0350d9dfb6e64fcaed426deaceb33e
-README.zh.md: 57ac85577a690d5c560bec39bef851692be03efd
+README.md: f2a78fe98b6a85ce91d727e95ddf62e6f77546b7
+README.zh.md: e1b5f111fd8f761fdd8f25558463c0cc327a14be
diff --git a/packages/plan/plan-mode/README.md b/packages/plan/plan-mode/README.md
index b22e218d1a..f2a78fe98b 100644
--- a/packages/plan/plan-mode/README.md
+++ b/packages/plan/plan-mode/README.md
@@ -94,4 +94,5 @@ Mode transitions do not change the tool catalog; plan arguments and review resul
 - Plan mode guides rather than enforces; deployments needing a hard boundary must combine independent sandbox and approval controls.
 - A pending selection made while idle is lost if the process exits before the next boundary, so the UI must reapply it.
 - Forked agents inherit logged plan state, while newly spawned agents begin inactive; there is no creation-time plan option.
+- A live child owned by another agent cannot open the `exit_plan_mode` review. The failed call tells the child to include the unresolved decision in its final result; durable fork lineage alone does not prevent a session resumed as a runtime root from opening the review.
 - Only the Web UI has a specialized `plan-review` renderer; another interaction provider may present the same request through its generic option flow.
diff --git a/packages/plan/plan-mode/README.zh.md b/packages/plan/plan-mode/README.zh.md
index 57ac85577a..e1b5f111fd 100644
--- a/packages/plan/plan-mode/README.zh.md
+++ b/packages/plan/plan-mode/README.zh.md
@@ -94,4 +94,5 @@ mode 转换不改变工具目录；plan 参数与评审结果按常规方式扩
 - Plan mode 只进行引导，而不强制执行；需要硬边界的部署必须组合独立的沙箱与批准控制。
 - 如果进程在下一个边界之前退出，空闲时作出的待生效选择会丢失，因此 UI 必须重新应用它。
 - Fork 的 agent 会继承已记录的 plan 状态，新 spawn 的 agent 则从未激活状态开始；不存在创建时 plan 选项。
+- 由另一个 agent 所有的存活子级无法打开 `exit_plan_mode` 审阅。该调用失败时会提示子级在最终结果中包含尚未解决的决策；仅有持久化 fork 谱系并不会阻止恢复为运行时根的会话打开该审阅。
 - 只有 Web UI 具备专用的 `plan-review` 渲染器；其他交互提供方可以通过通用选项流程呈现同一请求。

From 924c954469bd85945dfe11bd2fde5b7dd829d396 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:43:52 +0800
Subject: [PATCH 239/516] feat(session): bound persistence write batching

---
 ...ed-persistence-write-coordinator.i18n.yaml |   4 +-
 ...18-shared-persistence-write-coordinator.md |   6 +-
 ...shared-persistence-write-coordinator.zh.md |   6 +-
 ...ssion-persistence-write-batching.i18n.yaml |   6 +
 ...nded-session-persistence-write-batching.md |  59 ++++
 ...d-session-persistence-write-batching.zh.md |  59 ++++
 ...-07-21-log-backed-session-titles.i18n.yaml |   4 +-
 .../2026-07-21-log-backed-session-titles.md   |   2 +-
 ...2026-07-21-log-backed-session-titles.zh.md |   2 +-
 .../2026-07-28-feedback-command.i18n.yaml     |   4 +-
 .../feature/2026-07-28-feedback-command.md    |   2 +-
 .../feature/2026-07-28-feedback-command.zh.md |   2 +-
 ...collapse-persistence-flush-state.i18n.yaml |   4 +-
 ...-07-23-collapse-persistence-flush-state.md |  14 +-
 ...-23-collapse-persistence-flush-state.zh.md |  14 +-
 ...-remove-synthetic-log-only-turns.i18n.yaml |   4 +-
 ...6-07-28-remove-synthetic-log-only-turns.md |   4 +-
 ...7-28-remove-synthetic-log-only-turns.zh.md |   4 +-
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   4 +-
 docs/architecture.zh.md                       |   4 +-
 docs/config-catalog.md                        |   8 +-
 docs/cordis-catalog/services.md               |   2 +-
 .../persistence.i18n.yaml                     |   4 +-
 docs/core-data-structures/persistence.md      |   2 +-
 docs/core-data-structures/persistence.zh.md   |   2 +-
 docs/core-data-structures/session.i18n.yaml   |   4 +-
 docs/core-data-structures/session.md          |   2 +-
 docs/core-data-structures/session.zh.md       |   2 +-
 .../README.i18n.yaml                          |   4 +-
 .../session-checkpoint-policy/README.md       |   4 +-
 .../session-checkpoint-policy/README.zh.md    |   4 +-
 .../README.i18n.yaml                          |   4 +-
 .../session-persistence-jsonl/README.md       |   3 +-
 .../session-persistence-jsonl/README.zh.md    |   3 +-
 .../session-persistence-jsonl/src/index.ts    |  10 +-
 .../tests/jsonl.spec.ts                       |   1 +
 .../README.i18n.yaml                          |   4 +-
 .../session-persistence-sqlite/README.md      |   3 +-
 .../session-persistence-sqlite/README.zh.md   |   3 +-
 .../session-persistence-sqlite/src/index.ts   |  10 +-
 .../tests/sqlite.spec.ts                      |   1 +
 .../session-persistence/README.i18n.yaml      |   4 +-
 .../session-persistence/README.md             |   4 +-
 .../session-persistence/README.zh.md          |   4 +-
 .../session-persistence/package.json          |   2 +
 .../session-persistence/src/coordinator.ts    |  95 ++++---
 .../session-persistence/src/index.ts          |   2 +
 .../session-persistence/src/write-behind.ts   | 153 +++++++++++
 .../tests/persistence.spec.ts                 |  78 +++++-
 .../tests/write-behind.spec.ts                | 252 ++++++++++++++++++
 pnpm-lock.yaml                                |   3 +
 52 files changed, 763 insertions(+), 126 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
 create mode 100644 packages/session-persistence/session-persistence/src/write-behind.ts
 create mode 100644 packages/session-persistence/session-persistence/tests/write-behind.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index 7216c38d38..d1ae953836 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.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 .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
-2026-06-18-shared-persistence-write-coordinator.md: 66b73b60ceec9497f1f1226747b8cebd831eb426
-2026-06-18-shared-persistence-write-coordinator.zh.md: 424ce6ec7384e8af7b979a29f58c31379a1d1850
+2026-06-18-shared-persistence-write-coordinator.md: 12131ebf8380fb8ba816618f0cbaf72cb004623a
+2026-06-18-shared-persistence-write-coordinator.zh.md: a11926b602651d8a7dc641f61371e882685b508b
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
index 66b73b60ce..12131ebf83 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
@@ -14,7 +14,7 @@ Extract a backend-agnostic `PersistenceCoordinator` into `dsh-session-persistenc
 
 Composition, not inheritance. The coordinator is a concrete class the backend holds, not a base class the backend extends. The Agent Note's risk — "a coordinator must not make unusual backends fight an inheritance hierarchy" — is avoided: a backend exposes only the hooks and cannot reach the coordinator's private orchestration state. A third-party backend MAY still implement the abstract service directly without the coordinator, including immutable logical inspection and the default preparation fallback through `load`.
 
-The coordinator holds one controller for each exact live `Session`; the controller combines initialization, pending events, and the shared flush promise. Each `session/event` starts an eager drain, and `session/flush` observes quiescence rather than initiating the ordinary write path. The [flush-controller simplification](../simplification/2026-07-23-collapse-persistence-flush-state.md) owns this lifecycle.
+The coordinator holds one lifecycle entry for each exact live `Session`: initialization plus a package-private write controller that owns pending events, a fixed batching deadline, the active write, failure retention, and the shared flush barrier. Each `session/event` enters that bounded write path, and `session/flush` bypasses the wait to observe quiescence. The [flush-controller simplification](../simplification/2026-07-23-collapse-persistence-flush-state.md) owns controller consolidation; the [bounded batching decision](2026-08-08-bounded-session-persistence-write-batching.md) owns scheduling cadence.
 
 The coordinator retires a session from `session/disposed`: it waits for the controller's initialization and current flush, serializes a final drain, and removes the controller and owned per-id state only after success. A failure leaves the controller discoverable for backend teardown to retry. Settled per-id chain tails remove themselves only when they are still current, so a completion cannot erase a newer operation for the same id. Backend teardown unregisters write-path listeners, flushes every remaining controller, awaits per-id operations, and then closes the backend.
 
@@ -35,7 +35,7 @@ The single design choice that keeps the seam clean: the crash-repair "where is t
 
 ## Testing
 
-The shared `runPersistenceContract` (public-API contract) runs for every backend and proves that `inspect` balances an interrupted logical view without changing storage or revisions before `prepare` or `load` commits recovery. `runCoordinatorContract` (`tests/coordinator-contract.ts`) covers adoption, HMR, collision, session and backend disposal drains, and crash-tail repair through an in-memory reference, JSONL, and SQLite. `persistence.spec.ts` and `preparations.spec.ts` cover preparation reuse and reservation, bounded prepared-state eviction, eager follow-up batches, live-controller cleanup, same-id chain-tail races, failed-drain retry, and close ordering. The per-backend specs retain storage mechanics only. A through-coordinator torn-tail repair test per real backend keeps the opaque-marker branch covered because the contract crash case produces synthetic closers without a torn marker.
+The shared `runPersistenceContract` (public-API contract) runs for every backend and proves that `inspect` balances an interrupted logical view without changing storage or revisions before `prepare` or `load` commits recovery. `runCoordinatorContract` (`tests/coordinator-contract.ts`) covers adoption, HMR, collision, session and backend disposal drains, and crash-tail repair through an in-memory reference, JSONL, and SQLite. `persistence.spec.ts`, `preparations.spec.ts`, and `write-behind.spec.ts` cover preparation reuse and reservation, bounded prepared-state eviction, fixed-window follow-up batches, live-controller cleanup, same-id chain-tail races, failed-batch retry, and close ordering. The per-backend specs retain storage mechanics only. A through-coordinator torn-tail repair test per real backend keeps the opaque-marker branch covered because the contract crash case produces synthetic closers without a torn marker.
 
 ## Alternatives considered
 
@@ -44,4 +44,4 @@ The shared `runPersistenceContract` (public-API contract) runs for every backend
 
 ## Consequences
 
-The coordinator adds one indirection, an opaque torn marker, detached session-retirement tasks, and bounded prepared Session state, but centralizes correctness-heavy orchestration previously duplicated by every backend. Session disposal remains an observe-only event, so the session owner does not await persistence retirement; the coordinator contains failures, preserves pending events in the live controller, and makes backend teardown the quiescence boundary. Its hook surface stays narrow: identity, adoption, collision checks, preparation, and immutable inspection reuse `loadStored`; materialization stays atomic inside `appendBatch`; and listing bypasses the coordinator. Read models use `inspect` rather than `load`, so observing a persisted open turn does not commit interruption closers; the [Session preparation decision](2026-08-05-session-preparation.md) owns reuse, reservation, and publication. New backends implement storage primitives rather than copy the eager write lifecycle.
+The coordinator adds one indirection, an opaque torn marker, detached session-retirement tasks, and bounded prepared Session state, but centralizes correctness-heavy orchestration previously duplicated by every backend. Session disposal remains an observe-only event, so the session owner does not await persistence retirement; the coordinator contains failures, preserves pending events in the live controller, and makes backend teardown the quiescence boundary. Its hook surface stays narrow: identity, adoption, collision checks, preparation, and immutable inspection reuse `loadStored`; materialization stays atomic inside `appendBatch`; and listing bypasses the coordinator. Read models use `inspect` rather than `load`, so observing a persisted open turn does not commit interruption closers; the [Session preparation decision](2026-08-05-session-preparation.md) owns reuse, reservation, and publication. New backends implement storage primitives rather than copy the bounded write lifecycle.
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
index 424ce6ec73..a11926b602 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不可变逻辑检查，以及通过 `load` 实现的默认准备回退。
 
-协调器为每个存活的 `Session` 实例持有一个控制器；该控制器统合初始化、待处理事件与共享 flush promise。每个 `session/event` 都会立即启动排空，而 `session/flush` 只观察完全停稳，不会发起常规写入路径。[flush 控制器简化](../simplification/2026-07-23-collapse-persistence-flush-state.md)定义该生命周期。
+协调器为每个存活的 `Session` 实例持有一个生命周期条目：初始化，加上一个包私有写入控制器，后者负责待处理事件、固定批处理截止时间、活跃写入、失败保留和共享 flush 屏障。每个 `session/event` 都进入这条有界写入路径，`session/flush` 则绕过等待以观察完全停稳。控制器归并由 [flush 控制器简化](../simplification/2026-07-23-collapse-persistence-flush-state.md)定义；调度节奏由[有界批处理决策](2026-08-08-bounded-session-persistence-write-batching.md)定义。
 
 协调器通过 `session/disposed` 退役会话：它等待控制器完成初始化和当前 flush，串行执行最后一次排空，且仅在成功后才移除控制器与其拥有的每 id 状态。失败时保持控制器可被找到，以供后端 teardown（拆除）重试。每个 id 的已结算链尾仅在其仍是当前链尾时才移除自身，因此旧操作完成后不会抹除同一 id 的新操作。后端 teardown 会注销写入路径监听器、flush 每个剩余的控制器、等待所有按 id 串行化的操作，最后关闭后端。
 
@@ -35,7 +35,7 @@ Status: implemented
 
 ## 测试
 
-共享的 `runPersistenceContract`（公开 API 契约）为每个后端运行，并证明 `inspect` 会配平被中断的逻辑视图但不改变存储或修订版本，随后由 `prepare` 或 `load` 提交恢复。`runCoordinatorContract`（`tests/coordinator-contract.ts`）通过内存参考实现、JSONL 与 SQLite 覆盖接管、HMR、碰撞、会话与后端 dispose 排空和崩溃尾部修复。`persistence.spec.ts` 与 `preparations.spec.ts` 覆盖准备复用与预留、有界准备状态淘汰、立即执行的后续批次、存活控制器清理、同 id 链尾竞态、排空失败重试与关闭顺序。各后端自身的测试规格只保留存储机制。每个真实后端都有一个经由协调器的崩溃尾部修复测试，以覆盖不透明 marker 分支，因为契约中的崩溃用例会产生合成 closers，却不会产生 torn marker。
+共享的 `runPersistenceContract`（公开 API 契约）为每个后端运行，并证明 `inspect` 会配平被中断的逻辑视图但不改变存储或修订版本，随后由 `prepare` 或 `load` 提交恢复。`runCoordinatorContract`（`tests/coordinator-contract.ts`）通过内存参考实现、JSONL 与 SQLite 覆盖接管、HMR、碰撞、会话与后端 dispose 排空和崩溃尾部修复。`persistence.spec.ts`、`preparations.spec.ts` 与 `write-behind.spec.ts` 覆盖准备复用与预留、有界准备状态淘汰、固定窗口后续批次、存活控制器清理、同 id 链尾竞态、失败批次重试与关闭顺序。各后端自身的测试规格只保留存储机制。每个真实后端都有一个经由协调器的崩溃尾部修复测试，以覆盖不透明 marker 分支，因为契约中的崩溃用例会产生合成 closers，却不会产生 torn marker。
 
 ## 曾考虑的替代方案
 
@@ -44,4 +44,4 @@ Status: implemented
 
 ## 后果
 
-协调器增加了一层间接、一个不透明的 torn marker、脱离会话生命周期的退役任务，以及有界的已准备 Session 状态，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查、准备与不可变检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时不会提交中断 closers；复用、预留与发布由 [Session 准备阶段决策](2026-08-05-session-preparation.md)定义。新后端只需实现存储原语，而无需复制立即写入生命周期。
+协调器增加了一层间接、一个不透明的 torn marker、脱离会话生命周期的退役任务，以及有界的已准备 Session 状态，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查、准备与不可变检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时不会提交中断 closers；复用、预留与发布由 [Session 准备阶段决策](2026-08-05-session-preparation.md)定义。新后端只需实现存储原语，而无需复制有界写入生命周期。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
new file mode 100644
index 0000000000..05c9a1fdd2
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.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/architecture/2026-08-08-bounded-session-persistence-write-batching.md
+2026-08-08-bounded-session-persistence-write-batching.md: 46dc612492fa1bfa805f77f865f14b168f52776f
+2026-08-08-bounded-session-persistence-write-batching.zh.md: 4aafdd652aad87cfe74a449428cdbbf13312d260
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
new file mode 100644
index 0000000000..46dc612492
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
@@ -0,0 +1,59 @@
+# Agent Note: Bounded session persistence write batching
+
+Status: implemented
+
+English | [中文](2026-08-08-bounded-session-persistence-write-batching.zh.md)
+
+## Problem
+
+Streaming responses can emit many `assistant/chunk` events in a short interval. The persistence coordinator previously scheduled a backend append as soon as an idle queue received one event. Events arriving while that append was active shared a follow-up batch, but a fast backend could still produce many small durable appends. Each JSONL append creates and syncs a Zstandard frame or raw suffix, while each SQLite append opens and commits a transaction and increments the session revision.
+
+Dropping chunk events or replacing them with assembled messages would reduce logical storage, but it would also change the event log, replay, sequence numbers, timestamps, and provenance. The write-amplification problem does not require that larger semantic change.
+
+### Quantified baseline
+
+Repository fixtures make the logical volume concrete. Decoding the current packed rows in [`goal-multi-turn-actions`](../../../../apps/web/tests/snapshots/goal-multi-turn-actions/session.jsonl) yields 2,098 events: 2,017 chunks (96.1%). Their unpacked JSONL lines occupy 332,647 of 379,225 event bytes (87.7%), while chunk packing reduces the committed file to 89,176 bytes and 182 storage rows, including 23 packed chunk rows. [`permission-policy-context`](../../../../apps/web/tests/snapshots/permission-policy-context/session.jsonl) yields 813 events: 746 chunks (91.8%) and 118,935 of 184,821 unpacked event bytes (64.4%); its packed file is 84,917 bytes and 123 storage rows, including 14 packed rows. These are tracked deterministic fixtures, not a production workload distribution, but they demonstrate why deleting chunks would reduce logical volume and why the existing packed-row layout already removes much of their JSON envelope cost.
+
+SQLite stores one row per logical event, so those same logical logs would retain 2,098 and 813 event rows respectively; batching does not change those counts. JSONL writes one Zstandard frame and fsync per durable append batch, while SQLite performs one transaction and one session-revision increment per batch. Runtime files do not record former append boundaries, so fixture row counts cannot honestly be presented as fsync or transaction counts.
+
+The scheduling bound is deterministic. With an immediately resolving sink, the former immediate controller could issue one append for each event arriving after the previous append completed. A controller test admits 20 events 10 ms apart: the 200 ms fixed window hands all 20 to one append. This is a 20-to-1 reduction for that cadence, not a universal ratio. Sparse events, mandatory flushes, slow prior writes, and different arrival rates produce different batch sizes.
+
+## Decision
+
+The first-party JSONL and SQLite plugins expose `writeBatchMaxDelayMs`, a positive integer no greater than Node's timer limit. Its default is `200`. Each plugin resolves the value at load and passes it to `PersistenceCoordinator`; the coordinator remains the single owner of batching behavior.
+
+Each live Session receives a package-private `SessionWriteBehind`. When its pending queue changes from empty to non-empty, the controller starts one fixed window. Later events join that batch without resetting the deadline: this is bounded coalescing, not debounce. When the deadline expires, the controller hands the complete pending prefix to the existing per-id serialization and `appendBatch` path. At most one write for a Session is active. Events admitted during that write form a new pending prefix with their own fixed deadline; if that deadline expires before the active write completes, the new prefix starts immediately after it.
+
+`writeBatchMaxDelayMs` bounds only the controller's intentional batching wait. Event-loop scheduling, initialization, an earlier serialized operation, and backend I/O can delay durable completion, so the option is not a hard fsync or crash-loss SLA.
+
+`session/flush` cancels any remaining wait and becomes a shared quiescence barrier. It drains the active attempt and every event admitted while the barrier is running before it resolves. Session retirement and backend disposal use that same barrier, so lifecycle teardown never waits for the batching timer. The checkpoint policy continues to place mandatory barriers before model requests and top-level tool side effects.
+
+Every event remains durable in its original order and shape. The controller copies each event on admission; no `assistant/chunk`, `seq`, `time`, surface metadata, or storage record is removed or rewritten. JSONL can therefore encode more events in one append frame, and SQLite can insert more event rows in one transaction, without changing either on-disk format or schema version.
+
+A failed background append restores its complete batch before any newer pending events, reports the failure once, and pauses automatic retry. The next newly admitted event opens a fresh fixed window; an explicit flush, retirement, or disposal retries immediately and surfaces a repeated failure to its caller. This avoids a timer-driven failure loop while preserving the existing recoverable flush boundary.
+
+This decision supersedes only the immediate scheduling cadence in [Collapse live persistence into one flush controller](../simplification/2026-07-23-collapse-persistence-flush-state.md). That note remains authoritative for one controller per live Session, retained failed batches, per-id serialization, retirement, and quiescent disposal. The [shared persistence coordinator](2026-06-18-shared-persistence-write-coordinator.md) remains the owner of the backend hook boundary.
+
+## Alternatives considered
+
+**Do not persist streaming chunk events.** Rejected here: it changes the event-sourced authority and recovery semantics rather than only physical write cadence. The existing [assembled-message rejection](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md) remains the guardrail until a no-information-loss replacement defines replay, fork, provenance, sequence, and crash behavior independently. The [packed-row decision](2026-07-26-packed-chunk-rows-by-default.md) remains the complementary JSONL storage-size optimization.
+
+**Write only at semantic checkpoints.** Rejected: it maximizes batching but makes the ordinary crash-loss window depend on a separately mounted policy. Bounded background writes preserve progress between checkpoints while mandatory flushes keep their stronger ordering contract.
+
+**Debounce from the latest event.** Rejected: a continuously streaming response could postpone its first write indefinitely. A fixed window from the first pending event provides a real upper bound on intentional coalescing wait.
+
+**Implement timers separately in JSONL and SQLite.** Rejected: scheduling, failure retention, flush races, and teardown are backend-neutral lifecycle concerns. Duplicating them would reopen the drift that `PersistenceCoordinator` removed.
+
+## Verification
+
+The controller tests use a fake clock to prove the fixed, non-resetting 200 ms window; immediate and shared flush barriers; events admitted during a barrier; an over-budget tail behind an active write; ordered failure retention; paused automatic retry; and explicit retry of an overlapping background failure. Coordinator tests run the controller through Session notifications, retirement, collision reclamation, and teardown. The JSONL and SQLite suites retain their storage-format, transaction, recovery, and shared persistence-contract coverage.
+
+## Consequences
+
+High-frequency event bursts normally produce fewer durable append operations while preserving the exact logical event count. The reduction depends on arrival rate and backend latency: a burst inside one 200 ms window becomes one batch, while mandatory flushes and sparse events can still produce small batches.
+
+This decision does not cap pending event count or bytes behind a slow backend, and it does not reduce SQLite rows or the decoded logical log. A demonstrated memory bound or logical-retention policy would require its own failure and replay contract rather than another hidden timer rule.
+
+An admitted event can remain only in memory during the configured window, and then while scheduling or backend work is outstanding. Deployments choose a smaller value for a narrower ordinary loss window or a larger value for stronger batching. Explicit durability boundaries remain unchanged and bypass the wait.
+
+The new deep module gives the timer, active write, pending prefix, retry pause, and barrier one owner. `PersistenceCoordinator` retains initialization and identity serialization; backends retain only durable storage primitives. Neither `SESSION_FORMAT_VERSION` nor SQLite `SCHEMA_VERSION` changes.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
new file mode 100644
index 0000000000..4aafdd652a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
@@ -0,0 +1,59 @@
+# Agent Note: 为会话持久化写入批处理设定上界
+
+Status: implemented
+
+[English](2026-08-08-bounded-session-persistence-write-batching.md) | 中文
+
+## 问题
+
+流式响应可能会在短时间内发出大量 `assistant/chunk` 事件。此前，只要空闲队列收到一个事件，持久化协调器就会立即调度一次后端追加。该追加仍在进行时到达的事件会共用一个后续批次，但如果后端速度很快，仍可能产生大量小规模的持久化追加。每次 JSONL 追加都会创建并同步一个 Zstandard 帧或原始格式后缀，而每次 SQLite 追加都会打开并提交一个事务，同时递增会话修订版本。
+
+丢弃分片事件或用组装后的消息替代它们可以减少逻辑存储量，但也会改变事件日志、回放、序列号、时间戳和来源信息。写放大问题不要求采取这项语义变化更大的方案。
+
+### 量化基线
+
+仓库 fixture（测试前置数据）让逻辑数据量有了具体依据。对当前 [`goal-multi-turn-actions`](../../../../apps/web/tests/snapshots/goal-multi-turn-actions/session.jsonl) 中的打包行进行解码，可得到 2,098 个事件，其中 2,017 个是分片（96.1%）。这些分片解包后的 JSONL 行共 332,647 字节，占全部事件 379,225 字节的 87.7%；分片打包则把仓库中的已提交文件缩小到 89,176 字节和 182 个存储行，其中包括 23 个打包分片行。[`permission-policy-context`](../../../../apps/web/tests/snapshots/permission-policy-context/session.jsonl) 可得到 813 个事件，其中 746 个是分片（91.8%）；这些分片解包后的 JSONL 行共 118,935 字节，占全部事件 184,821 字节的 64.4%。其打包文件为 84,917 字节，共 123 个存储行，其中包括 14 个打包行。这些是纳入版本控制的确定性 fixture，不代表生产工作负载分布；但它们说明了删除分片为何会降低逻辑数据量，也说明现有打包行布局已经消除了大量 JSON 包装开销。
+
+SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保留 2,098 和 813 个事件行；批处理不会改变这些数量。JSONL 每个持久化追加批次会写入一个 Zstandard 帧并执行一次 fsync，SQLite 每个批次会执行一次事务并递增一次会话修订版本。运行时文件不记录原有追加边界，因此不能把 fixture 的存储行数当作 fsync 或事务次数。
+
+调度上界是确定的。当写入端会立即完成每次操作时，原来的即时控制器可能对每个在前一次追加完成后到达的事件分别发起一次追加。一个控制器测试以 10 ms 的间隔接纳 20 个事件：200 ms 固定窗口会把全部 20 个事件交给一次追加。对于这种到达节奏，追加次数从 20 次降至 1 次，但这不是普遍比例。稀疏事件、强制 flush、较慢的前序写入和不同到达速率都会产生不同的批次大小。
+
+## 决策
+
+第一方 JSONL 与 SQLite 插件公开 `writeBatchMaxDelayMs`，其值必须是一个不超过 Node 计时器上限的正整数，默认值为 `200`。每个插件都会在加载时解析该值，再传给 `PersistenceCoordinator`；批处理行为仍只由协调器负责。
+
+每个活跃的 Session 都有一个包私有 `SessionWriteBehind`。当其待处理队列从空变为非空时，控制器会启动一个固定窗口。后续事件加入该批次但不会重置截止时间：这属于有界合并，而不是防抖。截止时间到达后，控制器会把完整的待处理前缀交给现有的按 id 串行化机制，并沿 `appendBatch` 路径写入。同一 Session 同时最多有一个活跃写入。该写入期间接纳的事件会形成新的待处理前缀，并拥有自己的固定截止时间；如果该截止时间在活跃写入完成前到期，新前缀会在前一次写入完成后立即开始写入。
+
+`writeBatchMaxDelayMs` 只限制控制器为批处理而主动等待的时间。事件循环调度、初始化、此前的串行化操作和后端 I/O 都可能延后持久化完成时间，因此该选项并不对 fsync 完成时间或崩溃数据丢失提供硬性 SLA。
+
+`session/flush` 会取消剩余等待，并充当共享的完全停稳屏障。它会在完成前等待活跃写入尝试，并排空屏障运行期间接纳的每个事件。Session 退役与后端 dispose（资源释放）共用该屏障，因此生命周期 teardown 绝不会等待批处理计时器。检查点策略仍会在模型请求与顶层工具副作用之前设置强制屏障。
+
+每个事件仍会按原有顺序和形态持久化。控制器会在接纳时复制每个事件；任何 `assistant/chunk`、`seq`、`time`、surface 元数据或存储记录都不会被删除或重写。因此，JSONL 可以在一个追加帧中编码更多事件，SQLite 可以在一个事务中插入更多事件行，而无需改变任一种磁盘格式或 schema 版本。
+
+后台追加失败后，控制器会把完整批次恢复到所有较新的待处理事件之前，报告一次该失败，并暂停自动重试。随后新接纳的第一个事件会开启新的固定窗口；显式 flush、退役或 dispose 会立即重试，如果故障再次发生，则会向调用方暴露该故障。这可以避免计时器驱动的失败循环，同时保留现有可恢复的 flush 边界。
+
+本决策仅取代[将实时持久化归并到单个刷新控制器](../simplification/2026-07-23-collapse-persistence-flush-state.md)中的即时调度节奏。对于每个活跃 Session 使用一个控制器、保留失败批次、按 id 串行化、退役和完全停稳的 dispose，原 Agent Note 仍是权威记录。后端钩子边界仍由[共享持久化协调器](2026-06-18-shared-persistence-write-coordinator.md)定义。
+
+## 备选方案
+
+**不持久化流式分片事件。** 这里不采纳：这会改变事件日志作为真源的地位及恢复语义，而不只是改变物理写入节奏。在无信息损失的替代方案独立定义回放、fork、来源信息、序列和崩溃行为之前，现有的[拒绝仅保留组装消息的决策](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)仍是防护规则。[打包行决策](2026-07-26-packed-chunk-rows-by-default.md)仍是配套的 JSONL 存储体积优化。
+
+**仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序契约。
+
+**按最新事件重置防抖窗口。** 不采纳：持续不断的流式响应可能无限期推迟首次写入。由第一个待处理事件启动的固定窗口，为主动合并等待提供了真正的上界。
+
+**分别在 JSONL 与 SQLite 中实现计时器。** 不采纳：调度、失败保留、flush 竞态和 teardown 都是后端无关的生命周期问题。重复实现这些机制会重新引入 `PersistenceCoordinator` 已消除的实现漂移。
+
+## 验证
+
+控制器测试使用假时钟证明固定且不会重置的 200 ms 窗口、即时且可共享的 flush 屏障、屏障运行期间接纳的事件、在活跃写入之后已超过窗口时限的尾部批次、有序保留失败批次、暂停自动重试，以及显式 flush 会重试与其重叠发生的后台失败。协调器测试会在 Session 通知、退役、冲突回收和 teardown 路径中验证该控制器。JSONL 与 SQLite 测试套件继续覆盖存储格式、事务、恢复和共享持久化契约。
+
+## 后果
+
+高频事件突发通常会减少持久化追加操作，同时保持逻辑事件数量完全不变。减少幅度取决于事件到达速率和后端延迟：位于同一 200 ms 窗口内的突发事件会成为一个批次，而强制 flush 与稀疏事件仍可能产生小批次。
+
+本决策不会限制因后端缓慢而积压的待处理事件数量或字节数，也不会减少 SQLite 行数或解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放契约，而不是再引入一条隐式计时器规则。
+
+接纳后的事件在配置窗口内可能只存在于内存中，此后在等待调度或后端工作完成期间也可能如此。部署可以选择较小的值以缩短普通丢失窗口，也可以选择较大的值以加强批处理。显式持久性边界保持不变，并会绕过等待。
+
+新的 deep module 让计时器、活跃写入、待处理前缀、重试暂停和屏障由一个所有方统一负责。`PersistenceCoordinator` 继续负责初始化和按标识串行化；后端仍只负责持久存储原语。`SESSION_FORMAT_VERSION` 与 SQLite `SCHEMA_VERSION` 均不变。
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
index 36468994e1..5c5054b0c9 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.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 .agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
-2026-07-21-log-backed-session-titles.md: 81ac687c6f55dd0ca1eaeb9d84c811edcfe17b5c
-2026-07-21-log-backed-session-titles.zh.md: a3a8cb6fa4b766657176f2827a3641d4874b834b
+2026-07-21-log-backed-session-titles.md: 5f4c53a5fb866663bbfaae6b3fdafb4660424804
+2026-07-21-log-backed-session-titles.zh.md: f9629c1109c8428c74270de9475423d29b99e8f1
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
index 81ac687c6f..5f4c53a5fb 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
@@ -18,7 +18,7 @@ The [`session-title` capability family](../../../../packages/session-title/READM
 
 Every accepted revision is a log-only `session/title` event. Its payload contains normalized non-empty text, the exact eligible human `user/message` seqs used to derive it, and either fallback provenance or the registered provider id plus optional provider/model route. Before an auxiliary title-model dispatch, the shared helper appends a log-only `session/title-llm-request` event containing the title-provider id, exact source seqs, route, system prompt, messages, and output-token cap; a later generation failure leaves the request auditable. The dispatched envelope is deep-frozen to preserve exact agreement with that record but carries no process-local agent-loop request identity, so loop-only reconstruction checks do not compare it with the main conversation header. Validation failures that never reach dispatch create no request event. `foldSessionTitle()` selects the latest title event and adds that event's seq and timestamp as `SessionTitleSnapshot`. Neither event enters `session.surface` or `deriveMessages()`.
 
-The title service appends `session/title` directly after checking its current revision and exact live session; the bundled model helper likewise appends its literal `session/title-llm-request` record before dispatch. Both records may sit between turns without inventing an execution boundary. Persistence observes them eagerly and drains through ordinary checkpoints and lifecycle teardown; title publication does not force a per-event flush. No generic marker, cast, or settlement queue sits between the event owner and `Session.append()`. This is the domain-specific application of the [standalone log-only event decision](../simplification/2026-07-28-remove-synthetic-log-only-turns.md).
+The title service appends `session/title` directly after checking its current revision and exact live session; the bundled model helper likewise appends its literal `session/title-llm-request` record before dispatch. Both records may sit between turns without inventing an execution boundary. Persistence admits them to bounded background batches and drains through ordinary checkpoints and lifecycle teardown; title publication does not force a per-event flush. No generic marker, cast, or settlement queue sits between the event owner and `Session.append()`. This is the domain-specific application of the [standalone log-only event decision](../simplification/2026-07-28-remove-synthetic-log-only-turns.md).
 
 ### Input and asynchronous timing
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
index a3a8cb6fa4..f9629c1109 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 每个已接受的修订都是纯日志 `session/title` 事件。其载荷包含规范化后的非空文本、用于派生标题的所有合格且来源为人类的 `user/message` 的准确 seq，以及回退来源信息，或已注册的提供方 id 加可选的提供方和模型路由。辅助标题模型发起调用前，共享辅助组件会追加一个纯日志 `session/title-llm-request` 事件，其载荷包含标题提供方 id、准确的源 seq、路由、系统提示词、消息和输出 token 上限；即使后续生成失败，这次请求仍可审计。发送的请求信封经过深度冻结，以确保其与该记录精确一致，但它有意不携带进程本地的 agent loop（智能体循环）请求身份，因此仅针对 agent loop 的重建检查不会将它与主对话请求头进行比较。未进入调用阶段的验证失败不会创建请求事件。`foldSessionTitle()` 选择最新的标题事件，并将该事件的 seq 和时间戳加入 `SessionTitleSnapshot`。这两类事件都不会进入 `session.surface` 或 `deriveMessages()`。
 
-标题服务会在检查当前修订和确切的实时会话后，直接追加 `session/title`；随附模型辅助函数同样会在发起调用前追加其字面量 `session/title-llm-request` 记录。两类记录都可以位于轮次之间，而无需虚构执行边界。持久化会尽快观察它们，并通过常规检查点和生命周期 teardown 排空；标题发布不会强制逐事件 flush。事件所有方与 `Session.append()` 之间不存在通用标记、类型断言或结算队列。这是[独立纯日志事件决策](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)在特定领域中的应用。
+标题服务会在检查当前修订和确切的实时会话后，直接追加 `session/title`；随附模型辅助函数同样会在发起调用前追加其字面量 `session/title-llm-request` 记录。两类记录都可以位于轮次之间，而无需虚构执行边界。持久化会将它们接纳到有界后台批次中，并通过常规检查点和生命周期 teardown 排空；标题发布不会强制逐事件 flush。事件所有方与 `Session.append()` 之间不存在通用标记、类型断言或结算队列。这是[独立纯日志事件决策](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)在特定领域中的应用。
 
 ### 输入与异步时序
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
index b1dceca3b2..8374a59b63 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-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 .agents/notes/implemented/feature/2026-07-28-feedback-command.md
-2026-07-28-feedback-command.md: 770c72954d66c9e26e03c47f99c261626e6ed09b
-2026-07-28-feedback-command.zh.md: c8bd57ddb5e94bfb826ec40b771547ca9625c8e3
+2026-07-28-feedback-command.md: 56660b3796c44d3d510dd2901e6a155498673d88
+2026-07-28-feedback-command.zh.md: ec03a5c4a0e96d5350085c3d8d26f2523962f1b5
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
index 770c72954d..56660b3796 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
@@ -16,7 +16,7 @@ The capture surface has to be usable at the moment of annoyance, which rules out
 
 The package declares the log-only `feedback/record { text }` session event and exports `recordFeedback(session, text)` as its command-independent producer. The producer discards surrounding whitespace, rejects an empty result, and appends exactly one event. `/feedback` delegates to it, so another UI, hook, or host integration can record the same domain fact without constructing a slash command.
 
-`dsh-commands` still writes its `command/run` / `command/done` lifecycle pair around `/feedback`, but this command sets `recordInput: false`. Its `command/run` therefore carries the command identity and source without `args`; the feedback text exists only in `feedback/record`, while `command/done` carries the acknowledgement outcome. All three records are log-only and non-surface. Their appends start persistence's ordinary eager drain; nothing forces a flush, so acknowledgement reports that the feedback is in the log rather than already on disk.
+`dsh-commands` still writes its `command/run` / `command/done` lifecycle pair around `/feedback`, but this command sets `recordInput: false`. Its `command/run` therefore carries the command identity and source without `args`; the feedback text exists only in `feedback/record`, while `command/done` carries the acknowledgement outcome. All three records are log-only and non-surface. Their appends enter persistence's ordinary bounded write path; nothing forces a flush, so acknowledgement reports that the feedback is in the log rather than already on disk.
 
 Capture remains inert for the running agent and model. The optional OTel telemetry package later adds one infrastructure consumer: it observes `feedback/record` as a release trigger in `FEEDBACK_ONLY` mode and as the local-only warning trigger in `DISABLED` mode, without changing the feedback event or command path. See [Feedback-gated session telemetry](2026-08-05-feedback-gated-session-telemetry.md).
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
index c8bd57ddb5..ec03a5c4a0 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 本包（package）声明仅写入日志的 `feedback/record { text }` 会话事件，并导出 `recordFeedback(session, text)`，作为不依赖命令的生产方。该生产方丢弃前后空白，拒绝空结果，并且恰好追加一个事件。`/feedback` 委托给它，因此其他 UI、钩子或 host 集成无需构造斜杠命令也能记录同一个领域事实。
 
-`dsh-commands` 仍会围绕 `/feedback` 写入 `command/run` / `command/done` 生命周期配对，但该命令设置了 `recordInput: false`。因此，它的 `command/run` 携带命令标识与来源，但不携带 `args`；反馈文本只存在于 `feedback/record` 中，而 `command/done` 携带确认结果。三个记录都仅写入日志且非 surface。它们的追加会启动持久化的常规即时排空；没有任何环节强制 flush，因此确认文本报告的是反馈已进入日志，而非已经落盘。
+`dsh-commands` 仍会围绕 `/feedback` 写入 `command/run` / `command/done` 生命周期配对，但该命令设置了 `recordInput: false`。因此，它的 `command/run` 携带命令标识与来源，但不携带 `args`；反馈文本只存在于 `feedback/record` 中，而 `command/done` 携带确认结果。三个记录都仅写入日志且非 surface。它们的追加会进入持久化的常规有界写入路径；没有任何环节强制 flush，因此确认文本报告的是反馈已进入日志，而非已经落盘。
 
 采集对正在运行的 agent 与模型仍不产生后续动作。可选的 OTel 遥测包后续增加了一个基础设施消费方：它在 `FEEDBACK_ONLY` 模式下将 `feedback/record` 作为释放触发器，在 `DISABLED` 模式下将其作为本地警告触发器，且不改变反馈事件或命令路径。见[反馈门控的会话遥测](2026-08-05-feedback-gated-session-telemetry.md)。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
index a570637be3..45d89e4af1 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.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 .agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
-2026-07-23-collapse-persistence-flush-state.md: a9b0f6847712f47d46adb6b01c57563033738964
-2026-07-23-collapse-persistence-flush-state.zh.md: e665d164fb66b2bce97a4f6ded88f2ee07324e61
+2026-07-23-collapse-persistence-flush-state.md: 2801079e5b322d076eced3a0113e7958d9b4c3b9
+2026-07-23-collapse-persistence-flush-state.zh.md: dfc8fc9576416b1f51f4f9c978f49aee4f39f938
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
index a9b0f68477..2801079e5b 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
@@ -4,15 +4,17 @@ Status: implemented
 
 English | [中文](2026-07-23-collapse-persistence-flush-state.zh.md)
 
+The [bounded write-batching decision](../architecture/2026-08-08-bounded-session-persistence-write-batching.md) supersedes this note's immediate scheduling cadence. The single-controller ownership, failure retention, per-id serialization, retirement, and quiescent-disposal decisions remain current.
+
 ## Problem
 
 The persistence coordinator represented one live session's write lifecycle with separate buffer, initialization, and retirement containers plus the per-id operation chain. Those structures mirrored the same fact: whether that exact `Session` still had initialization or events that must settle before its state could be released. The checkpoint-only drain also kept every event volatile until another plugin requested `session/flush`, even though the backend could begin durability work without blocking the synchronous producer.
 
 ## Decision
 
-Each live `Session` has one controller containing `pending`, `init`, and the optional current `flush` promise. A `session/event` listener copies the frozen event into `pending` and immediately schedules `ensureFlush()`. Calls during an active write reuse the same promise. The drain snapshots one stable pending prefix and removes it only after `appendBatch` commits; events admitted during the write remain after that prefix and schedule one follow-up batch.
+Each live `Session` has one lifecycle entry containing initialization and one package-private write controller. The controller owns `pending`, the fixed batching timer, the optional active write, automatic-retry pause, and the shared flush barrier. A `session/event` listener copies the frozen event into `pending`; the first event starts a fixed deadline, and later events join without resetting it. A write takes one stable pending prefix; events admitted while it runs remain pending for a separately bounded follow-up batch.
 
-`session/flush` is an observation barrier. It waits for initialization and repeatedly awaits or starts the controller's flush until neither a current promise nor pending events remain. An eager failure is logged without rejecting the synchronous event producer, retains the complete batch, and is retried by the next explicit flush, retirement attempt, or backend teardown. Explicit flush and teardown still surface the failure if that retry rejects.
+`session/flush` is an immediate quiescence barrier. It waits for initialization, cancels the batching timer, joins any active attempt, and drains pending events, including events admitted while the barrier runs. A background failure is logged without rejecting the synchronous event producer, restores the complete ordered batch, and pauses automatic retry. A new event starts a fresh fixed window; explicit flush, retirement, or backend teardown retries immediately and surfaces a repeated failure.
 
 Initialization now enters the existing per-id operation chain once and calls the unserialized core operations while it owns that turn. The chain remains separate from the live controller because detached public `create`/`append`/`load` calls can race without a `Session` object and still require identity-level serialization.
 
@@ -22,17 +24,17 @@ The live-controller map is also the retirement registry. Successful retirement d
 
 ## Alternatives considered
 
-**Keep checkpoint-only write-behind.** This can form larger batches, but makes durability depend on a separately mounted checkpoint policy and maximizes the crash-loss window between checkpoints. Eager scheduling still coalesces synchronous bursts and events arriving during an active write.
+**Keep checkpoint-only write-behind.** This can form larger batches, but makes durability depend on a separately mounted checkpoint policy and maximizes the crash-loss window between checkpoints. Bounded background scheduling still coalesces bursts and persists progress between mandatory barriers.
 
 **Use one coordinator-wide flush promise.** The attachment pattern works for one file, but a global promise would serialize unrelated sessions. One controller per live session preserves independent backend progress while the per-id chain protects same-identity operations.
 
-**Latch the first eager error permanently.** This makes every later flush deterministic, but prevents the existing teardown retry from recovering a transient storage failure. Retaining the batch without latching the error preserves both observability and retry.
+**Latch the first background error permanently.** This makes every later flush deterministic, but prevents the existing teardown retry from recovering a transient storage failure. Retaining the batch without latching the error preserves both observability and retry.
 
 **Reject every live load.** This is safe but removes established balanced live snapshots used by persistence consumers and tests. Snapshot-before-flush gives the call a stable linearization point: successful flush proves exactly that snapshot is durable, while the live path never invokes crash repair.
 
 ## Verification
 
-- A focused coordinator test gates the first append, admits another event during that write, and observes an automatic second durable batch without calling `session/flush`.
+- Focused controller tests use a fake clock to prove the non-resetting fixed window, gate the first append, admit another event during that write, and observe an automatic second durable batch without calling `session/flush`.
 - The shared coordinator contract still covers live adoption, collisions, crash repair, and session/backend disposal over the in-memory, JSONL, and SQLite backends.
 - Failure and teardown tests keep rejected batches pending, retry them before close, and prove an in-flight controller delays backend close.
 - The shared backend contract persists an open live turn, proves `load` rejects without writing synthetic closers, completes and retires the owner, then reloads the exact completed turn.
@@ -42,6 +44,6 @@ The live-controller map is also the retirement registry. Successful retirement d
 
 ## Consequences
 
-The coordinator has three long-lived containers: persisted identity state, live-session controllers, and per-id operation chains. Eager writes reduce the ordinary crash-loss window and remove separate buffer, initialization, and retirement registries. They can produce more backend batches than checkpoint-only draining; same-tick bursts and events admitted during one write still coalesce.
+The live-session entry keeps initialization beside one controller for pending events, its timer, active write, retry pause, and flush barrier. Separate coordinator containers retain persisted identity state, prepared cold Sessions, retiring identity waiters, and per-id operation chains because those lifecycles also exist without one writable live Session. Bounded writes reduce the ordinary crash-loss window and produce fewer backend batches than immediate scheduling, while mandatory barriers remain unchanged.
 
 `session/flush` no longer chooses when ordinary persistence begins. It remains the ordering and error-observation boundary used by the loop and checkpoint policy, so a successful checkpoint still means every event admitted before its completion is durable.
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
index e665d164fb..dfc8fc9576 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
@@ -4,15 +4,17 @@ Status: implemented
 
 [English](2026-07-23-collapse-persistence-flush-state.md) | 中文
 
+[有界写入批处理决策](../architecture/2026-08-08-bounded-session-persistence-write-batching.md)取代了本 Agent Note 中的即时调度节奏。单控制器归属、失败保留、按 id 串行化、退役和完全停稳的资源释放决策仍然有效。
+
 ## 问题
 
 持久化协调器使用彼此独立的缓冲区、初始化容器和退役容器，以及按 id 划分的操作链，表示一个活跃会话的写入生命周期。这些结构反映的是同一个事实：该 `Session` 是否仍有初始化操作或事件必须完成，之后才能释放其状态。仅由检查点触发的排空还会让每个事件都停留在易失状态，直至另一个插件请求 `session/flush`，尽管后端可以在不阻塞同步生产方的情况下开始持久化工作。
 
 ## 决策
 
-每个活跃的 `Session` 都有一个控制器，其中包含 `pending`、`init` 和可选的当前 `flush` promise。`session/event` 监听器将冻结的事件复制到 `pending`，并立即调度 `ensureFlush()`。活跃写入期间的调用复用同一个 promise。排空操作会对待处理事件中一个稳定的前缀生成快照，并且只在 `appendBatch` 提交后移除该前缀；写入期间接纳的事件保留在该前缀之后，并调度一个后续批次。
+每个活跃的 `Session` 都有一个生命周期条目，其中包含初始化和一个包私有写入控制器。该控制器负责 `pending`、固定批处理计时器、可选的活跃写入、自动重试暂停和共享 flush 屏障。`session/event` 监听器将冻结的事件复制到 `pending`；第一个事件设定固定截止时间，后续事件加入但不会重置。一次写入会取出一个稳定的待处理前缀；写入期间接纳的事件仍留在待处理队列中，并形成另一个独立有界的后续批次。
 
-`session/flush` 是观测屏障。它等待初始化完成，并反复等待或启动控制器的刷新，直至当前 promise 和待处理事件均不存在。即时写入失败会被记录，但不会拒绝同步事件生产方；完整批次会保留下来，由下一次显式刷新、退役尝试或后端资源销毁重试。若该次重试仍失败，显式刷新和资源销毁仍会向调用方暴露失败。
+`session/flush` 是即时完全停稳屏障。它等待初始化完成、取消批处理计时器、等待任何活跃尝试完成，并排空待处理事件，包括屏障运行期间接纳的事件。后台写入失败会被记录，但不会拒绝同步事件生产方；系统会恢复完整且顺序不变的批次，并暂停自动重试。新事件会开启新的固定窗口；显式 flush、退役或后端资源销毁会立即重试，并在失败再次发生时向调用方暴露失败。
 
 初始化只进入现有的按 id 操作链一次，并在占有该轮执行权时调用未串行化的核心操作。该操作链与活跃控制器保持分离，因为公共 `create`、`append`、`load` 调用即使没有 `Session` 对象仍可能发生竞态，依然需要按标识串行执行。
 
@@ -22,17 +24,17 @@ Status: implemented
 
 ## 备选方案
 
-**保留仅由检查点触发的延后写入。** 这种方式可以形成更大的批次，但会让持久性依赖另行挂载的检查点策略，并使检查点之间因崩溃而丢失数据的窗口达到最大。即时调度仍会合并同步突发事件，以及活跃写入期间到达的事件。
+**保留仅由检查点触发的延后写入。** 这种方式可以形成更大的批次，但会让持久性依赖另行挂载的检查点策略，并使检查点之间因崩溃而丢失数据的窗口达到最大。有界后台调度仍会合并突发事件，并在强制屏障之间持久化进度。
 
 **在整个协调器范围内使用一个刷新 promise。** 这种挂接方式适用于单个文件，但全局 promise 会串行化互不相关的会话。每个活跃会话各有一个控制器，既能让不同会话的后端操作独立推进，又由按 id 操作链保护同一标识的操作。
 
-**永久锁存首次即时写入错误。** 这会让后续每次刷新都得到确定的结果，却会阻止现有的资源销毁重试从暂时性存储故障中恢复。保留批次但不锁存错误，可以同时保留可观测性和重试能力。
+**永久锁存首次后台写入错误。** 这会让后续每次刷新都得到确定的结果，却会阻止现有的资源销毁重试从暂时性存储故障中恢复。保留批次但不锁存错误，可以同时保留可观测性和重试能力。
 
 **拒绝对所有活跃会话的加载。** 这样做很安全，但会让持久化消费方和测试无法再使用既有的闭合活跃会话快照。先生成快照再刷新，为调用提供了稳定的线性化点：刷新成功即可证明正是该快照已持久化，而活跃路径绝不调用崩溃修复。
 
 ## 验证
 
-- 一个针对协调器的测试会阻塞第一次追加，在该次写入期间接纳另一个事件，并在不调用 `session/flush` 的情况下观测到自动执行的第二个持久批次。
+- 针对控制器的测试使用假时钟证明固定窗口不会重置，随后阻塞第一次追加，在该次写入期间接纳另一个事件，并在不调用 `session/flush` 的情况下观测到自动执行的第二个持久批次。
 - 共享协调器契约仍覆盖内存、JSONL 和 SQLite 后端上的活跃会话接管、冲突、崩溃修复，以及会话和后端的资源释放。
 - 失败和资源销毁测试会让写入失败的批次保持待处理，在关闭前重试这些批次，并证明尚在执行的控制器会延迟后端关闭。
 - 共享后端契约会持久化一个仍打开的活跃轮次，证明 `load` 会拒绝且不会写入合成闭合事件，随后完成该轮次并让其所有者退役，最后重新加载完全相同的已完成轮次。
@@ -42,6 +44,6 @@ Status: implemented
 
 ## 后果
 
-协调器有三个长生命周期容器：持久化的标识状态、活跃会话控制器和按 id 操作链。即时写入缩短了通常情况下因崩溃而丢失数据的窗口，并移除了彼此独立的缓冲区、初始化注册表和退役注册表。与仅由检查点触发的排空相比，这种方式可能产生更多后端批次；同一轮事件循环内的突发事件和一次写入期间接纳的事件仍会合并。
+活跃会话条目把初始化与一个控制器放在一起；该控制器负责待处理事件、计时器、活跃写入、重试暂停和 flush 屏障。协调器仍以独立容器保存已持久化的标识状态、准备好的冷态 Session、标识退役等待方和按 id 操作链，因为即使不存在可写的活跃 Session，这些生命周期仍然存在。有界写入缩短了通常情况下因崩溃而丢失数据的窗口，相比即时调度产生更少的后端批次，同时不改变强制屏障。
 
 `session/flush` 不再决定普通持久化何时开始。它仍是循环和检查点策略使用的顺序与错误观测边界，因此检查点成功仍表示在其完成前接纳的每个事件都已持久化。
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
index b4df206f13..7b65dc0445 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.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 .agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
-2026-07-28-remove-synthetic-log-only-turns.md: 720aa6bbe246ea960a61f6d6f67d36d1f85af08a
-2026-07-28-remove-synthetic-log-only-turns.zh.md: 587165a58ae322192b9ed1a9b3312f61e0b21ce6
+2026-07-28-remove-synthetic-log-only-turns.md: 61c1aa4b1599fe020e0cd96c32daea01d419e95a
+2026-07-28-remove-synthetic-log-only-turns.zh.md: 1661045ca9fb340ebffc9b749263262cb178eae4
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
index 720aa6bbe2..61c1aa4b15 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
@@ -18,7 +18,7 @@ The generic seam also duplicated domain policy. Its marker map said which plugin
 
 Core session invariants continue to enforce core-owned execution relations: turn and step numbering, enclosure of steering, assistant, tool, todo, and request-header events, and same-step tool call/result pairing. Core permits merge-extensible events between turns because only their declaring plugin knows whether they are execution-scoped or standalone. Plugin invariant companions remain responsible for their own event relations.
 
-The title service appends `session/title` directly after its existing service, revision, cancellation, and live-session checks. The bundled model helper appends its literal `session/title-llm-request` record before dispatch. Persistence observes both through the eager `session/event` path and drains them at ordinary checkpoints and lifecycle teardown; neither append forces a flush merely because it is between turns. A fallback, auxiliary request record, or accepted provider title may therefore appear after `turn/end` and before the next `turn/start`. Manual compaction uses the same between-turn capability for a `compact/* { turn: null }` bracket, but explicitly flushes the closed attempt because `/compact` promises durability before releasing queued prompt admission.
+The title service appends `session/title` directly after its existing service, revision, cancellation, and live-session checks. The bundled model helper appends its literal `session/title-llm-request` record before dispatch. Persistence admits both through the bounded `session/event` path and drains them at ordinary checkpoints and lifecycle teardown; neither append forces a flush merely because it is between turns. A fallback, auxiliary request record, or accepted provider title may therefore appear after `turn/end` and before the next `turn/start`. Manual compaction uses the same between-turn capability for a `compact/* { turn: null }` bracket, but explicitly flushes the closed attempt because `/compact` promises durability before releasing queued prompt admission.
 
 A session fork may end at any stable event position outside an open turn, not only at `turn/end`. This preserves standalone title and other plugin-owned log-only records in a default fork while still rejecting a prefix cut through active execution.
 
@@ -40,4 +40,4 @@ Core invariant tests accept an unknown plugin event between turns while continui
 
 ## Consequences
 
-Turn counts and outcomes again describe model-loop executions only. Standalone events and manual compaction brackets consume session seqs without consuming a turn number, start eager persistence like every other append, and require owners to request an explicit durability barrier only when their operation promises one. Generic plugin mistakes no longer fail under a core default enclosure rule, so each plugin that needs an execution relation must state and test that relation itself. The title capability keeps revision ordering and lifecycle persistence with less core state, and manual compaction gains durable control with no synthetic-turn or turn-number collision.
+Turn counts and outcomes again describe model-loop executions only. Standalone events and manual compaction brackets consume session seqs without consuming a turn number, enter bounded persistence like every other append, and require owners to request an explicit durability barrier only when their operation promises one. Generic plugin mistakes no longer fail under a core default enclosure rule, so each plugin that needs an execution relation must state and test that relation itself. The title capability keeps revision ordering and lifecycle persistence with less core state, and manual compaction gains durable control with no synthetic-turn or turn-number collision.
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
index 587165a58a..1661045ca9 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 核心会话不变量继续强制核心所属的执行关系：轮次与步骤编号、steering、助手、工具、待办和请求头事件的封闭，以及同一步骤内的工具调用／结果配对。核心允许可合并扩展事件位于轮次之间，因为只有声明它们的插件知道这些事件受执行作用域约束，还是可以独立存在。插件的不变量配套组件仍负责其自身的事件关系。
 
-标题服务会在完成既有的服务状态、修订、取消和实时会话检查后，直接追加 `session/title`。随附模型辅助函数会在发起调用前追加其字面量 `session/title-llm-request` 记录。持久化通过尽快处理的 `session/event` 路径观察两者，并在常规检查点与生命周期 teardown 时排空；二者都不会仅因为位于轮次之间就强制 flush。因此，回退标题、辅助请求记录或已接受的提供方标题可以出现在 `turn/end` 之后、下一个 `turn/start` 之前。手动压缩（compaction）利用同一项轮次间能力记录 `compact/* { turn: null }` 标记对，但会显式 flush 已闭合的尝试，因为 `/compact` 承诺在释放排队提示词接纳预留前完成持久化。
+标题服务会在完成既有的服务状态、修订、取消和实时会话检查后，直接追加 `session/title`。随附模型辅助函数会在发起调用前追加其字面量 `session/title-llm-request` 记录。持久化通过有界 `session/event` 路径接纳两者，并在常规检查点与生命周期 teardown 时排空；二者都不会仅因为位于轮次之间就强制 flush。因此，回退标题、辅助请求记录或已接受的提供方标题可以出现在 `turn/end` 之后、下一个 `turn/start` 之前。手动压缩（compaction）利用同一项轮次间能力记录 `compact/* { turn: null }` 标记对，但会显式 flush 已闭合的尝试，因为 `/compact` 承诺在释放排队提示词接纳预留前完成持久化。
 
 会话 fork 可以结束于开放轮次之外的任意稳定事件位置，而不限于 `turn/end`。这样，默认 fork 会保留独立标题和其他插件所属的纯日志记录，同时仍拒绝在活跃执行过程中截断前缀。
 
@@ -40,4 +40,4 @@ Status: implemented
 
 ## 后果
 
-轮次计数和结果重新只描述模型循环执行。独立事件和手动压缩标记对会占用会话 seq，但不占用轮次编号；它们像其他追加一样启动尽快持久化，并且仅当操作承诺持久性时，才要求事件所有方请求显式持久性屏障。通用插件错误不再因核心默认的封闭规则而失败，因此每个需要执行关系的插件都必须自行声明并测试该关系。标题功能保留修订排序和生命周期持久化，同时减少了核心状态；手动压缩则获得持久控制，不产生合成轮次或轮次编号冲突。
+轮次计数和结果重新只描述模型循环执行。独立事件和手动压缩标记对会占用会话 seq，但不占用轮次编号；它们像其他追加一样进入有界持久化，并且仅当操作承诺持久性时，才要求事件所有方请求显式持久性屏障。通用插件错误不再因核心默认的封闭规则而失败，因此每个需要执行关系的插件都必须自行声明并测试该关系。标题功能保留修订排序和生命周期持久化，同时减少了核心状态；手动压缩则获得持久控制，不产生合成轮次或轮次编号冲突。
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 0164acefcf..ca91a80b7e 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 35a73d4a307f5f48cc41cc496742a2ac210e8877
-architecture.zh.md: 185958221a477bb690e3ab5c91c33ba892ab2d73
+architecture.md: 3080d21a24310cc8851d64719d862ec719150ab6
+architecture.zh.md: 6e2bf0c155c68e84580aecc6b7783eeffa25c640
diff --git a/docs/architecture.md b/docs/architecture.md
index 35a73d4a30..3080d21a24 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -141,9 +141,9 @@ The session log is authoritative. `deriveMessages()` projects model history; raw
 
 **Model-visible ⟺ logged**: messages entering at `step/start` plus the folded `request/header` reconstruct every request. The header marks adapter defaults so later proposals discard them and re-resolve the route without losing explicit settings. `request/context` separately records registration-bound provider, model, and capacity metadata when the route changes; it does not participate in request reconstruction or header equality. `dsh-agent-loop/invariant` asserts reconstructability through `ctx.invariants` ([reconstructability](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)).
 
-Durability is a plugin concern. Backends eagerly drain synchronous `session/event` notifications. `session/flush` precedes requests and top-level tool dispatch, and follows `turn/end` before another turn or idle. `SessionPersistence` stores events and header metadata; JSONL defaults to checksummed Zstandard and SQLite shares the contract ([decision](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)).
+Durability is a plugin concern. Backends copy synchronous `session/event` notifications into fixed-window durable batches; `session/flush` bypasses the wait before requests and top-level tool dispatch, and after `turn/end` before another turn or idle. `SessionPersistence` stores events and header metadata; JSONL defaults to checksummed Zstandard and SQLite shares the contract ([checkpoint decision](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md), [batching decision](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
 
-Between turns, owners append log-only events through `Session`, flushing only for durability. `session/title` needs eager persistence and lifecycle drains; manual compaction flushes its bracket before the operation completes. Title work never delays responses; latest wins with provenance. Title records are inherited fork boundaries ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)).
+Between turns, owners append log-only events through `Session`, flushing only for durability. `session/title` relies on bounded background persistence and lifecycle drains; manual compaction flushes its bracket before the operation completes. Title work never delays responses; latest wins with provenance. Title records are inherited fork boundaries ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)).
 
 ### Model Content
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 185958221a..6e2bf0c155 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -141,9 +141,9 @@ idle inject:
 
 **模型可见 ⟺ 已记录**：在 `step/start` 进入的消息加上折叠后的 `request/header` 可以重建每个请求。该 header 会标记适配器默认值，使后续提议丢弃这些值并重新解析路由，同时不丢失显式设置。`request/context` 会在路由变化时另行记录与注册项绑定的提供方、模型及容量元数据；它不参与请求重建或 header 相等性判断。`dsh-agent-loop/invariant` 通过 `ctx.invariants` 断言可重建性（[可重建性](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)）。
 
-持久性由插件负责。后端会尽快排空同步的 `session/event` 通知。`session/flush` 位于请求与顶层工具分发之前，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一契约（[决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)）。
+持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一契约（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
 
-在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 需要尽快持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
+在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
 
 ### 模型内容
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index b4a4e15dc5..3a542068bb 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1289,13 +1289,15 @@ export interface Config {
   compression?: JsonlCompression
   /** Maximum cold Session preparations retained for history-to-resume reuse. */
   preparedSessionCacheSize?: number
+  /** Fixed live-event coalescing window; not a backend completion deadline. */
+  writeBatchMaxDelayMs?: number
 }
 
 /** Physical encoding selected for JSONL session artifacts. */
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:58`](../packages/session-persistence/session-persistence-jsonl/src/index.ts)
+Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:59`](../packages/session-persistence/session-persistence-jsonl/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-persistence-sqlite`
 
@@ -1323,6 +1325,8 @@ export interface Config {
   journalMode?: JournalMode
   /** Maximum cold Session preparations retained for history-to-resume reuse. */
   preparedSessionCacheSize?: number
+  /** Fixed live-event coalescing window; not a backend completion deadline. */
+  writeBatchMaxDelayMs?: number
 }
 
 /**
@@ -1336,7 +1340,7 @@ export interface Config {
 export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 ```
 
-Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:66`](../packages/session-persistence/session-persistence-sqlite/src/index.ts)
+Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:67`](../packages/session-persistence/session-persistence-sqlite/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-projection-cache`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 8820a0329c..cd9dd5cf5a 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -1309,7 +1309,7 @@ abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot
 
 Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) · [SessionInspection](../core-data-structures/persistence.md) · [SessionLocation](../core-data-structures/persistence.md) · [SessionPersistenceSnapshot](../core-data-structures/persistence.md) · [SessionPreparation](../core-data-structures/persistence.md)
 
-Source: [`packages/session-persistence/session-persistence/src/index.ts:70`](../../packages/session-persistence/session-persistence/src/index.ts)
+Source: [`packages/session-persistence/session-persistence/src/index.ts:72`](../../packages/session-persistence/session-persistence/src/index.ts)
 
 ## `ctx.sessionProjectionCache` — `SessionProjectionCache`
 
diff --git a/docs/core-data-structures/persistence.i18n.yaml b/docs/core-data-structures/persistence.i18n.yaml
index 58321e0f22..fe28a36f40 100644
--- a/docs/core-data-structures/persistence.i18n.yaml
+++ b/docs/core-data-structures/persistence.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 docs/core-data-structures/persistence.md
-persistence.md: 0968496201defa869d94925e8e5ae3c5da1bbd37
-persistence.zh.md: efb01427b4355e531fb9b86922223cf27d3b3db0
+persistence.md: 3d2bc7ff3b45cd3f38fca0b880a0df9adb928bad
+persistence.zh.md: 035f46d76e0189bd686e991c3d56d486b6f309d5
diff --git a/docs/core-data-structures/persistence.md b/docs/core-data-structures/persistence.md
index 0968496201..3d2bc7ff3b 100644
--- a/docs/core-data-structures/persistence.md
+++ b/docs/core-data-structures/persistence.md
@@ -8,7 +8,7 @@ The seam is a textbook [capability seam](../../.agents/notes/implemented/archite
 
 ## The flush checkpoint
 
-`session/event` is a *synchronous* notification; persistence plugins copy the event into a per-session controller and start an eager write without blocking the producer. Concurrent events share the current batch, and events admitted during that write trigger a follow-up batch. `session/flush` waits until no current or pending batch remains, so the loop still uses it as the ordering and error-observation checkpoint before claiming the next ordinary turn. A rejected eager write retains its events; an explicit flush retries them and reports failure through `agent/error` and the logger, never as a session event past the closed turn. Disposal performs the same final drain.
+`session/event` is a *synchronous* notification; persistence plugins copy the event into a per-session controller without blocking the producer. The first pending event starts a fixed batching window, and later events join without resetting its deadline. Expiry starts one durable batch; events admitted during that write receive their own deadline and form a follow-up batch. `session/flush` cancels the wait and drains through quiescence, so the loop still uses it as the ordering and error-observation checkpoint before claiming the next ordinary turn. A rejected background write retains its events and pauses automatic retry; a new event starts a fresh window, while explicit flush retries immediately and reports failure through `agent/error` and the logger, never as a session event past the closed turn. Disposal performs the same final drain. The configured maximum bounds only intentional batching wait, not event-loop scheduling or backend durability latency ([decision](../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
 
 ## Crash recovery preserves an interrupted turn
 
diff --git a/docs/core-data-structures/persistence.zh.md b/docs/core-data-structures/persistence.zh.md
index efb01427b4..035f46d76e 100644
--- a/docs/core-data-structures/persistence.zh.md
+++ b/docs/core-data-structures/persistence.zh.md
@@ -8,7 +8,7 @@
 
 ## flush 检查点
 
-`session/event` 是一个*同步*通知；持久化插件会将事件复制到逐会话控制器，并立即启动写入而不阻塞生产方。并发事件会加入当前批次；在该批次写入期间接纳的事件会触发后续批次。`session/flush` 会等待当前与待处理批次全部清空，因此循环仍将其用作在领取下一个普通轮次之前的顺序与错误观察检查点。立即写入被拒绝时会保留对应事件；显式 flush 会重试这些事件，并通过 `agent/error` 和 logger 报告失败，绝不会把失败记录成已关闭轮次之后的会话事件。dispose（资源释放）会执行同样的最终排空。
+`session/event` 是一个*同步*通知；持久化插件会将事件复制到逐会话控制器，而不阻塞生产方。第一个待处理事件会开启固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个持久化批次；该次写入期间接纳的事件会获得自己的截止时间，并形成后续批次。`session/flush` 会取消等待并排空至完全停稳，因此循环仍将其用作在领取下一个普通轮次之前的顺序与错误观察检查点。后台写入被拒绝时会保留对应事件并暂停自动重试；新事件会开启新的固定窗口，而显式 flush 会立即重试，并通过 `agent/error` 和 logger 报告失败，绝不会把失败记录成已关闭轮次之后的会话事件。dispose（资源释放）会执行同样的最终排空。配置的最大值只限制有意的批处理等待，不限制事件循环调度或后端完成持久化的延迟（[决策](../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
 
 ## 崩溃恢复保留被中断的轮次
 
diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/core-data-structures/session.i18n.yaml
index 78626957f6..16e969bd94 100644
--- a/docs/core-data-structures/session.i18n.yaml
+++ b/docs/core-data-structures/session.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 docs/core-data-structures/session.md
-session.md: fb04ff3eb3c15d1f3c923ee73d4ba19537d36f11
-session.zh.md: 138159d97a5c368f28821715512632e0ca95b29e
+session.md: 5d54b03df8ec3345e8bf04702f242e3aacf8ec39
+session.zh.md: 5a867cfe302bf02994bfe5a5a704bed55222e8ea
diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md
index fb04ff3eb3..5d54b03df8 100644
--- a/docs/core-data-structures/session.md
+++ b/docs/core-data-structures/session.md
@@ -561,7 +561,7 @@ interface TurnEndReasonMap {
 
 ## Execution enclosure and standalone events
 
-A turn encloses one model-loop execution, not the whole session log. AgentLoop records injected `user/message` events only from entering pre-step batches inside a turn; plugin-owned log-only events may still appear between `turn/end` and the next `turn/start`, consuming event seqs without incrementing turn numbers. Persistence eagerly records every contiguous accepted event, while crash repair closes only a genuinely open trailing turn. A producer that needs a durability barrier explicitly awaits `ctx.sessions.flush(session)`.
+A turn encloses one model-loop execution, not the whole session log. AgentLoop records injected `user/message` events only from entering pre-step batches inside a turn; plugin-owned log-only events may still appear between `turn/end` and the next `turn/start`, consuming event seqs without incrementing turn numbers. Persistence admits every contiguous accepted event into a bounded durable batch, while crash repair closes only a genuinely open trailing turn. A producer that needs an immediate durability barrier explicitly awaits `ctx.sessions.flush(session)`.
 
 The optional `dsh-session/invariant` companion enforces the relations owned by core: turn and step numbering, execution-event enclosure, and same-step tool call/result pairing. Merge-extensible event relations belong to the plugin that declares them, so core does not reject an unknown event merely because no turn is open. See [the standalone-event decision](../../.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md).
 
diff --git a/docs/core-data-structures/session.zh.md b/docs/core-data-structures/session.zh.md
index 138159d97a..5a867cfe30 100644
--- a/docs/core-data-structures/session.zh.md
+++ b/docs/core-data-structures/session.zh.md
@@ -565,7 +565,7 @@ interface TurnEndReasonMap {
 
 ## 执行封闭与独立事件
 
-一个轮次包围一次模型循环执行，而不是整个会话日志。AgentLoop 只会从轮次内返回 enter 的 pre-step 批次记录注入的 `user/message` 事件；插件所属的纯日志事件仍可出现在 `turn/end` 与下一个 `turn/start` 之间，占用事件 seq 但不递增轮次编号。持久化会尽快记录每个连续且已接受的事件，而崩溃修复只关闭确实仍处于开放状态的尾部轮次。需要持久性屏障的生产方会显式等待 `ctx.sessions.flush(session)`。
+一个轮次包围一次模型循环执行，而不是整个会话日志。AgentLoop 只会从轮次内返回 enter 的 pre-step 批次记录注入的 `user/message` 事件；插件所属的纯日志事件仍可出现在 `turn/end` 与下一个 `turn/start` 之间，占用事件 seq 但不递增轮次编号。持久化会将每个连续且已接受的事件纳入有界持久化批次，而崩溃修复只关闭确实仍处于开放状态的尾部轮次。需要即时持久性屏障的生产方会显式等待 `ctx.sessions.flush(session)`。
 
 可选的 `dsh-session/invariant` 配套插件会强制核心拥有的关系：轮次与步骤编号、执行事件封闭，以及同一步骤内的工具调用／结果配对。可合并扩展事件的关系由声明它的插件拥有，因此核心不会仅因没有开放轮次就拒绝未知事件。见[独立事件决策](../../.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md)。
 
diff --git a/packages/session-persistence/session-checkpoint-policy/README.i18n.yaml b/packages/session-persistence/session-checkpoint-policy/README.i18n.yaml
index 5e55be6a54..e435cf36d3 100644
--- a/packages/session-persistence/session-checkpoint-policy/README.i18n.yaml
+++ b/packages/session-persistence/session-checkpoint-policy/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/session-persistence/session-checkpoint-policy/README.md
-README.md: 57be9e78236775c39971c925f4972398c0b20a97
-README.zh.md: 66508382783c36c41be65afc758398d406c3a58f
+README.md: 01ed3c694967b1a86245d01b9d9f7eecd1193348
+README.zh.md: e2c197c0cc1d942a045c1ea22c1fb257f6e4059d
diff --git a/packages/session-persistence/session-checkpoint-policy/README.md b/packages/session-persistence/session-checkpoint-policy/README.md
index 57be9e7823..01ed3c6949 100644
--- a/packages/session-persistence/session-checkpoint-policy/README.md
+++ b/packages/session-persistence/session-checkpoint-policy/README.md
@@ -16,7 +16,7 @@ This zero-config function plugin consumes `ctx.sessions`, `ctx.llm`, `ctx.tools`
   name: '@deepseek-ai/dsh-session-checkpoint-policy'
 ```
 
-Persistence and checkpoint scheduling are intentionally separate Cordis plugins. A persistence backend eagerly writes `session/event` appends and makes each requested `session/flush` an observation barrier; this policy chooses the request, tool-dispatch, and next-step barriers. Loading a backend without this policy is valid, but a crash may lose the latest eagerly buffered events. First-party persisted apps and runtimes mount both plugins explicitly; a specialized deployment may deliberately omit or replace the policy.
+Persistence and checkpoint scheduling are intentionally separate Cordis plugins. A persistence backend starts bounded background batches for `session/event` appends and makes each requested `session/flush` an immediate quiescence barrier; this policy chooses the request, tool-dispatch, and next-step barriers. Loading a backend without this policy is valid, but a crash may lose events still inside the configured batching window or an outstanding write. First-party persisted apps and runtimes mount both plugins explicitly; a specialized deployment may deliberately omit or replace the policy.
 
 The policy wraps `llm/stream` lazily, so the downstream stream is not constructed until the live session's buffered request events are durable. It wraps `tools/execute` after pre-execute policy and guards; a top-level tool body runs only after its recorded call is durable. If cancellation lands while that flush is pending, the wrapper returns the canonical `ABORTED_BEFORE_DISPATCH` result without entering the tool body. Nested tool dispatches reuse the outer model-visible call's checkpoint. `agent/pre-step` persists the preceding response/result batch before request derivation.
 
@@ -41,5 +41,5 @@ The repair result is appended after the reusable prefix, so it does not invalida
 ## Known Limitations and Deferred Work
 
 - The policy durably records execution intent, not generic exactly-once effects. Side-effecting tools should forward `exec.callId` as an idempotency key when their provider supports one.
-- Streaming `assistant/chunk` events have no per-chunk checkpoint. They reach storage with the next semantic checkpoint, so a hard crash may lose the current partial response.
+- Streaming `assistant/chunk` events have no per-chunk checkpoint. Bounded background batches normally persist them before the next semantic checkpoint, but a hard crash may lose the current in-memory batch or outstanding write.
 - A persisted call without a result cannot prove whether its external effect completed. Recovery therefore records an unknown outcome instead of retrying automatically.
diff --git a/packages/session-persistence/session-checkpoint-policy/README.zh.md b/packages/session-persistence/session-checkpoint-policy/README.zh.md
index 6650838278..e2c197c0cc 100644
--- a/packages/session-persistence/session-checkpoint-policy/README.zh.md
+++ b/packages/session-persistence/session-checkpoint-policy/README.zh.md
@@ -16,7 +16,7 @@
   name: '@deepseek-ai/dsh-session-checkpoint-policy'
 ```
 
-持久化与检查点调度刻意拆分为独立 Cordis 插件。持久化后端会主动写入追加的 `session/event`，并把每个已请求 `session/flush` 变成观测屏障；该策略选择请求、工具分派和下一步骤屏障。不带此策略加载后端是有效的，但崩溃可能丢失最新的已缓冲事件。第一方持久化应用和运行时显式挂载两个插件；专用部署可以刻意省略或替换策略。
+持久化与检查点调度刻意拆分为独立 Cordis 插件。持久化后端会为追加的 `session/event` 启动有界后台批次，并把每个已请求的 `session/flush` 变成即时完全停稳屏障；该策略选择请求、工具分派和下一步骤屏障。不带此策略加载后端是有效的，但崩溃可能丢失仍位于已配置批处理窗口内的事件，或尚未完成的写入。第一方持久化应用和运行时显式挂载两个插件；专用部署可以刻意省略或替换策略。
 
 策略延迟包装 `llm/stream`，因此下游流只会在活动会话中缓冲的请求事件已持久化后构造。它在预执行策略和防护机制之后包装 `tools/execute`；只有在已记录调用已持久化后，顶层工具正文才会运行。如果取消在 flush 等待期间到达，包装层会返回规范的 `ABORTED_BEFORE_DISPATCH` 结果，不进入工具正文。嵌套工具分派重用外层模型可见调用的检查点。`agent/pre-step` 在派生请求前持久化前一响应/结果批次。
 
@@ -41,5 +41,5 @@
 ## 已知限制与暂缓事项
 
 - 该策略以持久方式记录执行意图，而非为通用副作用提供恰好一次保证。当提供方支持时，有副作用的工具应将 `exec.callId` 作为幂等键转发。
-- 流式 `assistant/chunk` 事件没有每分片检查点。它们在下一个语义检查点到达存储，因此硬崩溃可能丢失当前部分响应。
+- 流式 `assistant/chunk` 事件没有逐分片检查点。有界后台批次通常会在下一个语义检查点之前将其持久化，但硬崩溃可能丢失当前内存批次或尚未完成的写入。
 - 已持久化的调用没有结果时，无法证明其外部副作用是否完成。因此，恢复会记录未知结果，而不是自动重试。
diff --git a/packages/session-persistence/session-persistence-jsonl/README.i18n.yaml b/packages/session-persistence/session-persistence-jsonl/README.i18n.yaml
index 763b55a1a4..2ab76b4da9 100644
--- a/packages/session-persistence/session-persistence-jsonl/README.i18n.yaml
+++ b/packages/session-persistence/session-persistence-jsonl/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/session-persistence/session-persistence-jsonl/README.md
-README.md: cd087539bde2433fcdb70b2c511ff30880a877e1
-README.zh.md: 144b404e04f8a5fd3623d9329e4fbcafd328524d
+README.md: b7fa8fc2918711dd24eeba67132a267452d401f9
+README.zh.md: 59d21c6171e857849c4ab48940d66962fffbfdeb
diff --git a/packages/session-persistence/session-persistence-jsonl/README.md b/packages/session-persistence/session-persistence-jsonl/README.md
index cd087539bd..b7fa8fc291 100644
--- a/packages/session-persistence/session-persistence-jsonl/README.md
+++ b/packages/session-persistence/session-persistence-jsonl/README.md
@@ -27,6 +27,7 @@ The JSONL durable session-persistence backend — a concrete `SessionPersistence
 | `packChunks` | `boolean` (default `true`) | Write eligible delta-chunk runs as packed rows (~60% smaller logical logs measured on a real coding session). Set `false` for one-event-per-line diagnostics; reading packed rows works regardless of this write-side switch. |
 | `compression` | `'zstd' \| 'none'` | Defaults to `'zstd'`; `'none'` retains newline-delimited UTF-8 text. |
 | `preparedSessionCacheSize` | positive integer (default `5`) | Maximum unpublished Sessions retained after cold history inspection for reuse by resume. |
+| `writeBatchMaxDelayMs` | positive integer (default `200`) | Fixed coalescing window after an idle live-event queue receives work. Later events do not reset it; flush and teardown bypass it. It does not bound event-loop, serialized-operation, or backend latency. At most Node's `2_147_483_647` ms timer limit. |
 
 `locate(meta)` returns `{ kind: 'jsonl', path }` for the fixed transcript inside the resolved project/session directories. It performs no filesystem I/O: the target can be returned before the directory or file exists, and an existing file contains only the last flushed prefix.
 
@@ -48,7 +49,7 @@ A root belongs to one encoding. Startup discovery and targeted lookup reject the
 
 ## Write path
 
-The plugin copies frozen session events into one controller per live session and starts an eager drain. Concurrent events share the current write; events admitted during it form a follow-up batch, while `session/flush` waits until both current and pending batches are durable. A per-session cursor prevents resumed sessions from re-appending stored events, and live sessions are seeded when the plugin loads. The owning backend instance serializes operations for one session; disposal drains every retained controller before teardown.
+The plugin copies frozen session events into one controller per live session. The first pending event starts the configured fixed batching window, and later events join without resetting it. Expiry starts one durable append; events admitted during that write form a separately bounded follow-up batch. `session/flush` cancels the wait and drains current and pending batches. A per-session cursor prevents resumed sessions from re-appending stored events, and live sessions are seeded when the plugin loads. The owning backend instance serializes operations for one session; disposal drains every retained controller before teardown. Every logical event remains present: batching only lets one compressed frame or raw fsync carry more records.
 
 ## Model Experience
 
diff --git a/packages/session-persistence/session-persistence-jsonl/README.zh.md b/packages/session-persistence/session-persistence-jsonl/README.zh.md
index 144b404e04..59d21c6171 100644
--- a/packages/session-persistence/session-persistence-jsonl/README.zh.md
+++ b/packages/session-persistence/session-persistence-jsonl/README.zh.md
@@ -27,6 +27,7 @@ JSONL 持久会话存储后端：`SessionPersistence` 的一个具体实现（`d
 | `packChunks` | `boolean`（默认 `true`） | 将符合条件的 delta 分片连续段写为打包行（在真实编码会话上测得逻辑日志约小 60%）。设为 `false` 可用于每事件一行诊断；无论该写入侧开关如何，都能读取打包行。 |
 | `compression` | `'zstd' \| 'none'` | 默认 `'zstd'`；`'none'` 保留换行分隔 UTF-8 文本。 |
 | `preparedSessionCacheSize` | 正整数（默认 `5`） | 冷历史检查后保留、供恢复复用的未发布 Session 数量上限。 |
+| `writeBatchMaxDelayMs` | 正整数（默认 `200`） | 空闲的活动事件队列收到待写入事件后开启的固定合并窗口。后续事件不会重置窗口；flush 与 teardown 会绕过它。该值不限制事件循环、串行化操作或后端延迟。最大值为 Node 计时器上限 `2_147_483_647` ms。 |
 
 `locate(meta)` 返回已解析项目/会话目录内固定 transcript 的 `{ kind: 'jsonl', path }`。它不执行文件系统 I/O：可以在目录或文件存在前返回目标，现有文件也只包含最近一次 flush 完成的前缀。
 
@@ -48,7 +49,7 @@ JSONL 持久会话存储后端：`SessionPersistence` 的一个具体实现（`d
 
 ## 写入路径
 
-插件将冻结的会话事件复制到每个活动会话各自的 controller，并启动主动排空流程。并发事件共享当前写入；期间接纳的事件形成后续批次，`session/flush` 则等待当前和待处理批次完成持久化。每会话游标防止恢复后的会话重新 append 已存储事件，插件加载时会为活动会话设置初始状态。所属后端实例串行化单会话操作；dispose（资源释放）会在拆卸前排空每个保留的 controller。
+插件将冻结的会话事件复制到每个活动会话各自的 controller。第一个待处理事件会开启配置的固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一次持久化追加；该次写入期间接纳的事件会形成另一个独立有界的后续批次。`session/flush` 会取消等待并排空当前与待处理批次。每会话游标防止恢复后的会话重新 append 已存储事件，插件加载时会为活动会话设置初始状态。所属后端实例串行化单会话操作；dispose（资源释放）会在拆卸前排空每个保留的 controller。每个逻辑事件都会保留：批处理只让单个压缩帧或一次原始 JSONL fsync 承载更多记录。
 
 ## 模型体验
 
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts
index 130d684208..3534382316 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -15,7 +15,8 @@ import { performance } from 'node:perf_hooks'
 import { scheduler } from 'node:timers/promises'
 import { randomBytes } from 'node:crypto'
 import {
-  DEFAULT_PREPARED_SESSION_CACHE_SIZE, SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
+  DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS,
+  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
   type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot,
   type SessionInspection, type SessionPersistenceRevision as PersistenceRevision, type StoredPrefix,
 } from '@deepseek-ai/dsh-session-persistence'
@@ -76,6 +77,8 @@ export interface Config {
   compression?: JsonlCompression
   /** Maximum cold Session preparations retained for history-to-resume reuse. */
   preparedSessionCacheSize?: number
+  /** Fixed live-event coalescing window; not a backend completion deadline. */
+  writeBatchMaxDelayMs?: number
 }
 
 /** Opaque coordinator token for replacing bytes recovered from a torn frame. */
@@ -122,6 +125,8 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     packChunks: z.boolean().default(DEFAULT_PACK_CHUNKS),
     compression: JsonlCompressionSchema,
     preparedSessionCacheSize: z.number().step(1).min(1).default(DEFAULT_PREPARED_SESSION_CACHE_SIZE),
+    writeBatchMaxDelayMs: z.number().step(1).min(1).max(MAX_WRITE_BATCH_DELAY_MS)
+      .default(DEFAULT_WRITE_BATCH_MAX_DELAY_MS),
   })
 
   /**
@@ -144,11 +149,14 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     // Programmatic wrappers may construct the backend without Schemastery normalization.
     const preparedSessionCacheSize = config.preparedSessionCacheSize
       ?? DEFAULT_PREPARED_SESSION_CACHE_SIZE
+    const writeBatchMaxDelayMs = config.writeBatchMaxDelayMs
+      ?? DEFAULT_WRITE_BATCH_MAX_DELAY_MS
     this.packChunks = config.packChunks ?? DEFAULT_PACK_CHUNKS
     this.compression = config.compression ?? DEFAULT_COMPRESSION
     this.assertUsableRoot()
     this.coordinator = new PersistenceCoordinator<JsonlTornMarker>(this.ctx, this, {
       preparedSessionCacheSize,
+      writeBatchMaxDelayMs,
     })
   }
 
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
index 03a7f90d65..24ed94a3fb 100644
--- a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -166,6 +166,7 @@ describe('SessionPersistenceJsonl: format helpers', () => {
     const fiber = await ctx.plugin(SessionPersistenceJsonl, {
       root: relative(process.cwd(), absoluteRoot),
       compression: 'none',
+      writeBatchMaxDelayMs: 1,
     })
     const m = meta('relative-location', '/work')
     expect(ctx.sessionPersistence.locate(m)).toEqual({
diff --git a/packages/session-persistence/session-persistence-sqlite/README.i18n.yaml b/packages/session-persistence/session-persistence-sqlite/README.i18n.yaml
index 3dbbf87a2d..f6d2d2926b 100644
--- a/packages/session-persistence/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session-persistence/session-persistence-sqlite/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/session-persistence/session-persistence-sqlite/README.md
-README.md: d01ba6ebfa1f59a9e4d58f3032bbe1d016970290
-README.zh.md: c11bef5467a3401948b58d5fd8e3301b72ff3d03
+README.md: 4961f62bf6854c343d35b8406c9d721590274534
+README.zh.md: 8610ef56f737bac8781536ea26a5b48dbf67ed48
diff --git a/packages/session-persistence/session-persistence-sqlite/README.md b/packages/session-persistence/session-persistence-sqlite/README.md
index d01ba6ebfa..4961f62bf6 100644
--- a/packages/session-persistence/session-persistence-sqlite/README.md
+++ b/packages/session-persistence/session-persistence-sqlite/README.md
@@ -31,12 +31,13 @@ interface Config {
   path: string   // SQLite database file path, or ':memory:' for an in-process DB
   journalMode?: 'wal' | 'delete' | 'truncate' | 'persist'   // journal_mode pragma; default 'wal'
   preparedSessionCacheSize?: number   // positive integer; default 5
+  writeBatchMaxDelayMs?: number   // positive integer; default 200; maximum 2_147_483_647
 }
 ```
 
 ## Write path
 
-Like the JSONL backend, the plugin copies each frozen `session/event` into one controller per live session and starts an eager drain. Concurrent events share the current transaction; events admitted during it form a follow-up batch, while `session/flush` waits until both current and pending batches are durable. The controller persists a fork's seed once, keeps a write cursor so resume never re-appends stored events, and seeds live sessions on apply because HMR does not replay `session/created`. Dispose drains every retained controller before closing the database.
+Like the JSONL backend, the plugin copies each frozen `session/event` into one controller per live session. The first pending event starts the configured fixed batching window, and later events join without resetting it. Expiry starts one transaction; events admitted during that write form a separately bounded follow-up batch. `session/flush` cancels the wait and drains current and pending batches. The controller persists a fork's seed once, keeps a write cursor so resume never re-appends stored events, and seeds live sessions on apply because HMR does not replay `session/created`. Dispose drains every retained controller before closing the database. Every event remains a separate SQLite row; batching only groups more INSERTs into one transaction and revision increment.
 
 ## Model Experience
 
diff --git a/packages/session-persistence/session-persistence-sqlite/README.zh.md b/packages/session-persistence/session-persistence-sqlite/README.zh.md
index c11bef5467..8610ef56f7 100644
--- a/packages/session-persistence/session-persistence-sqlite/README.zh.md
+++ b/packages/session-persistence/session-persistence-sqlite/README.zh.md
@@ -31,12 +31,13 @@ interface Config {
   path: string   // SQLite database file path, or ':memory:' for an in-process DB
   journalMode?: 'wal' | 'delete' | 'truncate' | 'persist'   // journal_mode pragma; default 'wal'
   preparedSessionCacheSize?: number   // positive integer; default 5
+  writeBatchMaxDelayMs?: number   // positive integer; default 200; maximum 2_147_483_647
 }
 ```
 
 ## 写入路径
 
-与 JSONL 后端一样，插件将每个冻结的 `session/event` 复制到每个活动会话各自的 controller，并启动主动排空流程。并发事件共享当前事务；期间接纳的事件形成后续批次，`session/flush` 则等待当前和待处理批次完成持久化。Controller 会持久化一次 fork 种子，并保留写入游标，使恢复操作绝不重新 append 已存储事件；它还会在 apply 时为活动会话设置初始状态，因为 HMR（热模块替换）不回放 `session/created`。dispose（资源释放）会在关闭数据库前排空每个保留的 controller。
+与 JSONL 后端一样，插件将每个冻结的 `session/event` 复制到每个活动会话各自的 controller。第一个待处理事件会开启配置的固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个事务；该次写入期间接纳的事件会形成另一个独立有界的后续批次。`session/flush` 会取消等待并排空当前与待处理批次。Controller 会持久化一次 fork 种子，并保留写入游标，使恢复操作绝不重新 append 已存储事件；它还会在 apply 时为活动会话设置初始状态，因为 HMR（热模块替换）不回放 `session/created`。dispose（资源释放）会在关闭数据库前排空每个保留的 controller。每个事件仍各占一行 SQLite 记录；批处理只把更多 INSERT 归入同一个事务和同一次修订版本递增。
 
 ## 模型体验
 
diff --git a/packages/session-persistence/session-persistence-sqlite/src/index.ts b/packages/session-persistence/session-persistence-sqlite/src/index.ts
index 173d1bf857..fc2b10fa96 100644
--- a/packages/session-persistence/session-persistence-sqlite/src/index.ts
+++ b/packages/session-persistence/session-persistence-sqlite/src/index.ts
@@ -14,7 +14,8 @@ import { DatabaseSync } from 'node:sqlite'
 import { mkdir, open } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 import {
-  DEFAULT_PREPARED_SESSION_CACHE_SIZE, SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
+  DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS,
+  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
   type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot,
   type SessionInspection, type SessionPersistenceRevision as PersistenceRevision,
   type StoredPrefix, type StoredSuffix,
@@ -83,6 +84,8 @@ export interface Config {
   journalMode?: JournalMode
   /** Maximum cold Session preparations retained for history-to-resume reuse. */
   preparedSessionCacheSize?: number
+  /** Fixed live-event coalescing window; not a backend completion deadline. */
+  writeBatchMaxDelayMs?: number
 }
 
 /**
@@ -97,6 +100,8 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     path: z.string().required(),
     journalMode: z.union(['wal', 'delete', 'truncate', 'persist'] as const).default('wal'),
     preparedSessionCacheSize: z.number().step(1).min(1).default(DEFAULT_PREPARED_SESSION_CACHE_SIZE),
+    writeBatchMaxDelayMs: z.number().step(1).min(1).max(MAX_WRITE_BATCH_DELAY_MS)
+      .default(DEFAULT_WRITE_BATCH_MAX_DELAY_MS),
   })
 
   /**
@@ -116,11 +121,14 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     // Programmatic wrappers may construct the backend without Schemastery normalization.
     const preparedSessionCacheSize = config.preparedSessionCacheSize
       ?? DEFAULT_PREPARED_SESSION_CACHE_SIZE
+    const writeBatchMaxDelayMs = config.writeBatchMaxDelayMs
+      ?? DEFAULT_WRITE_BATCH_MAX_DELAY_MS
     // Open asynchronously so directory creation does not block plugin apply;
     // every storage hook awaits the same readiness promise.
     this.ready = this.openDb(config.path, (config as Required<Config>).journalMode)
     this.coordinator = new PersistenceCoordinator<number>(this.ctx, this, {
       preparedSessionCacheSize,
+      writeBatchMaxDelayMs,
     })
   }
 
diff --git a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
index d215696748..ab602e1c4d 100644
--- a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
+++ b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
@@ -675,6 +675,7 @@ describe('SessionPersistenceSqlite: edge cases', () => {
     const fiber = await ctx.plugin(SessionPersistenceSqlite, {
       path: ':memory:',
       preparedSessionCacheSize: 1,
+      writeBatchMaxDelayMs: 1,
     })
     const m = meta('sqlite-preparation-cache')
     await ctx.sessionPersistence.create(m)
diff --git a/packages/session-persistence/session-persistence/README.i18n.yaml b/packages/session-persistence/session-persistence/README.i18n.yaml
index 7c96b1a541..5b131371b8 100644
--- a/packages/session-persistence/session-persistence/README.i18n.yaml
+++ b/packages/session-persistence/session-persistence/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/session-persistence/session-persistence/README.md
-README.md: b29ff5ba17f384e8d3b1700ed3ad6c80aeeb184c
-README.zh.md: 8ca4b6a7128383fdca706f35914a06eb1f26de02
+README.md: 89c7cd5ebaff6f9ce9df9b60a50121dff4ddeeb5
+README.zh.md: 1ef7eb6c6c507167f61bb5df7c4ce8183aac5d0d
diff --git a/packages/session-persistence/session-persistence/README.md b/packages/session-persistence/session-persistence/README.md
index b29ff5ba17..89c7cd5eba 100644
--- a/packages/session-persistence/session-persistence/README.md
+++ b/packages/session-persistence/session-persistence/README.md
@@ -29,9 +29,9 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 
 ## The write coordinator
 
-`PersistenceCoordinator` owns per-id state and serialization, one eager write controller per live session, lazy materialization, crash-tail repair, session adoption, and quiescent disposal. A first-party backend composes one, implements the small `PersistenceBackend` storage hook interface, and delegates its stateful methods. JSONL and SQLite therefore share lifecycle correctness while retaining different storage primitives; see the [coordinator Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md) and [flush-controller simplification](../../../.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md).
+`PersistenceCoordinator` owns per-id state and serialization, one bounded write controller per live session, lazy materialization, crash-tail repair, session adoption, and quiescent disposal. A first-party backend composes one, implements the small `PersistenceBackend` storage hook interface, and delegates its stateful methods. JSONL and SQLite therefore share lifecycle correctness while retaining different storage primitives; see the [coordinator Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md), [flush-controller simplification](../../../.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md), and [bounded batching decision](../../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md).
 
-Each `session/event` copies its event into the session controller and starts an eager drain without blocking the producer. Concurrent notifications share the current drain; events admitted during a write remain pending and trigger the next batch. `session/flush` is an observation barrier that waits until the controller has no current or pending batch. An eager failure is logged and retains the batch; the next explicit flush or backend teardown retries it and surfaces failure to its caller.
+Each `session/event` copies its event into the session controller. The first pending event starts a fixed batching window; later events join without resetting its deadline. The configured `writeBatchMaxDelayMs` bounds this intentional wait, not event-loop, initialization, serialized-operation, or backend latency. Events admitted during a write form a new bounded batch. `session/flush` cancels the wait and is a shared quiescence barrier that drains events admitted while it runs. A background failure is logged once, retains the ordered batch, and pauses automatic retry; a new event starts a fresh window, while explicit flush or backend teardown retries immediately and surfaces a repeated failure.
 
 Crash repair is cold-only. For a live id, `load(id)` snapshots the authoritative in-memory log, waits for that snapshot to become durable, and returns it only when balanced; an open live turn rejects instead of receiving synthetic interruption closers. For a cold id, inspection reads, validates, freezes, and constructs one unpublished Session; repeated inspection reuses that object graph only while its source revision remains current. `prepare(id)` performs the same check before repair, reserves the exact Session, commits any pending torn-tail/interrupted-turn repair, and returns it for publication. HMR adoption reads through `loadStored`, applies the coordinator's cwd check, and never closes the active turn.
 
diff --git a/packages/session-persistence/session-persistence/README.zh.md b/packages/session-persistence/session-persistence/README.zh.md
index 8ca4b6a712..1ef7eb6c6c 100644
--- a/packages/session-persistence/session-persistence/README.zh.md
+++ b/packages/session-persistence/session-persistence/README.zh.md
@@ -29,9 +29,9 @@
 
 ## 写入协调器
 
-`PersistenceCoordinator` 负责每 id 状态和串行化、每个活动会话各自的主动写入 controller、延迟实体化、崩溃尾部修复、会话接管和完全停稳的 dispose（资源释放）。第一方后端组合一个协调器，实现小型 `PersistenceBackend` 存储钩子接口，并委托其有状态方法。因此 JSONL 和 SQLite 共享生命周期正确性，同时保留不同存储原语；见[协调器 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md) 和 [flush controller 简化](../../../.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md)。
+`PersistenceCoordinator` 负责每 id 状态和串行化、每个活动会话各自的有界写入 controller、延迟实体化、崩溃尾部修复、会话接管和完全停稳的 dispose（资源释放）。第一方后端组合一个协调器，实现小型 `PersistenceBackend` 存储钩子接口，并委托其有状态方法。因此 JSONL 和 SQLite 共享生命周期正确性，同时保留不同存储原语；见[协调器 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)、[flush controller 简化](../../../.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md)和[有界批处理决策](../../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)。
 
-每个 `session/event` 将事件复制到会话 controller，并在不阻塞生产者的情况下立即启动 drain。并发通知共享当前 drain；写入期间接纳的事件保持 pending，并触发下一批。`session/flush` 是观察屏障，会等待 controller 无当前或 pending 批次。即时写入失败会记录日志并保留批次；下一次显式 flush 或后端拆卸会重试该批次，并将失败返回给调用方。
+每个 `session/event` 将事件复制到会话 controller。第一个待处理事件会开启固定批处理窗口；后续事件会加入该批次，但不会重置截止时间。配置的 `writeBatchMaxDelayMs` 只限制这段有意等待，而不限制事件循环、初始化、串行化操作或后端延迟。写入期间接纳的事件会形成一个新的有界批次。`session/flush` 会取消等待，并作为共享的完全停稳屏障，排空屏障运行期间接纳的事件。后台写入失败只记录一次日志，保留顺序不变的批次，并暂停自动重试；新事件会开启新的固定窗口，而显式 flush 或后端拆卸会立即重试，并在失败再次发生时向调用方暴露失败。
 
 崩溃修复只适用于冷状态。对于实时 id，`load(id)` 为权威内存日志制作快照，等待该快照持久，并只在平衡时返回；开放实时轮次会被拒绝，而不会收到合成中断 closer。对于冷 id，检查只读取、验证、冻结并构造一次未发布 Session；只有来源 revision 仍然是当前值时，重复检查才会复用该对象图。`prepare(id)` 在修复前执行相同校验，预留精确 Session，提交任何待处理的撕裂尾部或中断轮次修复，并将其返回用于发布。HMR 接管通过 `loadStored` 读取，应用协调器 cwd 检查，并绝不关闭活动轮次。
 
diff --git a/packages/session-persistence/session-persistence/package.json b/packages/session-persistence/session-persistence/package.json
index d1977d4512..10517be615 100644
--- a/packages/session-persistence/session-persistence/package.json
+++ b/packages/session-persistence/session-persistence/package.json
@@ -28,6 +28,7 @@
     "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
@@ -35,6 +36,7 @@
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/session-persistence/session-persistence/src/coordinator.ts b/packages/session-persistence/session-persistence/src/coordinator.ts
index 1ff5d0d3eb..0eabaaa8c0 100644
--- a/packages/session-persistence/session-persistence/src/coordinator.ts
+++ b/packages/session-persistence/session-persistence/src/coordinator.ts
@@ -15,14 +15,22 @@ import {
   snapshotSessionEvent,
 } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type { SessionInspection } from './index.ts'
 import type { SessionPersistenceRevision } from './revision.ts'
 import { observeQueuedAbort, SessionPreparations } from './preparations.ts'
 import type { SessionPreparationReservation } from './preparations.ts'
+import { SessionWriteBehind } from './write-behind.ts'
 
 /** Default number of detached session preparations retained by a coordinator. */
 export const DEFAULT_PREPARED_SESSION_CACHE_SIZE = 5
 
+/** Default maximum intentional wait before a live session batch starts writing. */
+export const DEFAULT_WRITE_BATCH_MAX_DELAY_MS = 200
+
+/** Largest write batching delay accepted by Node's timer implementation. */
+export const MAX_WRITE_BATCH_DELAY_MS = MAX_TIMER_DELAY_MS
+
 /** Durable session contents failed validation after a successful backend read. */
 export class SessionPersistenceCorruptionError extends Error {
   /**
@@ -39,6 +47,8 @@ export class SessionPersistenceCorruptionError extends Error {
 export interface PersistenceCoordinatorOptions {
   /** Maximum completed unpublished preparations retained for reuse. */
   readonly preparedSessionCacheSize: number
+  /** Maximum intentional batching wait after an idle live queue receives work. */
+  readonly writeBatchMaxDelayMs: number
 }
 
 /**
@@ -174,11 +184,10 @@ interface SessionState {
   owner?: Session
 }
 
-/** One live session's initialization and eager write-behind controller. */
+/** One live session's initialization and bounded write-behind controller. */
 interface LiveSessionState {
-  pending: SessionEvent[]
   init: Promise<void>
-  flush: Promise<void> | undefined
+  writes: SessionWriteBehind
 }
 
 /** One validated cold source and the exact unpublished Session built from it. */
@@ -531,7 +540,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   private states = new Map<SessionId, SessionState>()
   /** Lifecycle and write-behind state keyed by the exact live Session. */
   private live = new Map<Session, LiveSessionState>()
-  /** Exact disposed lifecycles whose eager tail is still draining. */
+  /** Exact disposed lifecycles whose buffered tail is still draining. */
   private retirements = new Map<SessionId, Promise<void>>()
   /** Shared cold reads, unpublished reservations, and completed LRU entries. */
   private readonly preparations: SessionPreparations<PreparedSessionSource<TornMarker>, SessionState>
@@ -540,18 +549,27 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    * same id, so writes for one session never interleave. Keyed by session id.
    */
   private chains = new Map<SessionId, Promise<unknown>>()
+  /** Resolved fixed write-batching window shared by per-session controllers. */
+  private readonly writeBatchMaxDelayMs: number
 
   constructor(
     private ctx: Context,
     private backend: PersistenceBackend<TornMarker>,
     options: PersistenceCoordinatorOptions = {
       preparedSessionCacheSize: DEFAULT_PREPARED_SESSION_CACHE_SIZE,
+      writeBatchMaxDelayMs: DEFAULT_WRITE_BATCH_MAX_DELAY_MS,
     },
   ) {
     if (!Number.isSafeInteger(options.preparedSessionCacheSize)
       || options.preparedSessionCacheSize < 1) {
       throw new TypeError('preparedSessionCacheSize must be a positive safe integer')
     }
+    if (!Number.isSafeInteger(options.writeBatchMaxDelayMs)
+      || options.writeBatchMaxDelayMs < 1
+      || options.writeBatchMaxDelayMs > MAX_WRITE_BATCH_DELAY_MS) {
+      throw new TypeError(`writeBatchMaxDelayMs must be an integer between 1 and ${MAX_WRITE_BATCH_DELAY_MS}`)
+    }
+    this.writeBatchMaxDelayMs = options.writeBatchMaxDelayMs
     this.preparations = new SessionPreparations(options.preparedSessionCacheSize)
     this.installWritePath()
   }
@@ -1014,14 +1032,13 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       void this.initFor(session)
     })
 
-    // Keep a persistence-owned copy of each frozen event and start an eager drain.
+    // Keep a persistence-owned copy of each frozen event and start its bounded window.
     ctx.on('session/event', (session, event) => {
       const live = this.initFor(session)
-      live.pending.push(structuredClone(event))
-      if (live.flush === undefined) this.scheduleDrain(session, live)
+      live.writes.enqueue(event)
     })
 
-    // Callers use flush as the observation barrier for the eager write path.
+    // Callers use flush as the immediate durability barrier for buffered writes.
     ctx.on('session/flush', session => this.flush(session))
 
     // Session disposal is observe-only, so retirement contains its own failure.
@@ -1067,9 +1084,14 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       return restored
     }
     const seed = session.events.map(e => structuredClone(e))
-    const live: LiveSessionState = { pending: [], init: Promise.resolve(), flush: undefined }
+    let init = Promise.resolve()
+    const live: LiveSessionState = {
+      init,
+      writes: this.createWriteBehind(session, () => init),
+    }
     this.live.set(session, live)
-    live.init = this.serialize(session.header.id, () => this.onCreated(session, seed))
+    init = this.serialize(session.header.id, () => this.onCreated(session, seed))
+    live.init = init
     live.init.catch(() => { /* observed by flush/dispose through the controller */ })
     return live
   }
@@ -1088,9 +1110,14 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     const suffix = session.events.slice(state.cursor).map(event => structuredClone(event))
     this.preparations.attach(reservation)
     state.owner = session
-    const live: LiveSessionState = { pending: [], init: Promise.resolve(), flush: undefined }
+    let init = Promise.resolve()
+    const live: LiveSessionState = {
+      init,
+      writes: this.createWriteBehind(session, () => init),
+    }
     if (suffix.length > 0) {
-      live.init = this.serialize(session.id, () => this.appendCore(session.id, suffix))
+      init = this.serialize(session.id, () => this.appendCore(session.id, suffix))
+      live.init = init
       live.init.catch(() => { /* observed by flush/dispose through the controller */ })
     }
     return live
@@ -1152,7 +1179,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
         return
       }
       const owner = this.live.get(tracked.owner)
-      if (!tracked.materialized && !owner?.pending.length) {
+      if (!tracked.materialized && !owner?.writes.hasWork) {
         this.states.delete(id)
       } else {
         throw new Error(`session "${id}" is already bound to a different live session in this backend (id collision)`)
@@ -1214,41 +1241,29 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   private async flush(session: Session): Promise<void> {
     const live = this.initFor(session)
     await live.init
-    const overlapping = live.flush
-    if (overlapping !== undefined) await Promise.allSettled([overlapping])
-    while (live.flush !== undefined || live.pending.length > 0) {
-      if (live.flush !== undefined) await live.flush
-      else await this.ensureFlush(session, live)
-    }
+    await live.writes.flush()
   }
 
-  /** Start an eager drain without exposing its failure to the synchronous append. */
-  private scheduleDrain(session: Session, live: LiveSessionState): void {
-    void this.ensureFlush(session, live).catch((error: unknown) => {
-      this.ctx.logger.warn(`${this.backend.name}: eager drain for session "${session.id}" failed (buffered events retained): ${String(error)}`)
+  /** Build one package-private write controller around initialization and id serialization. */
+  private createWriteBehind(session: Session, ready: () => Promise<void>): SessionWriteBehind {
+    return new SessionWriteBehind({
+      maxDelayMs: this.writeBatchMaxDelayMs,
+      write: async (batch) => {
+        await ready()
+        await this.serialize(session.header.id, () => this.appendLiveBatch(session.header.id, batch))
+      },
+      reportBackgroundFailure: (error) => {
+        this.ctx.logger.warn(`${this.backend.name}: background write for session "${session.id}" failed (buffered events retained): ${String(error)}`)
+      },
     })
   }
 
-  /** Start one drain for the complete pending batch. */
-  private ensureFlush(session: Session, live: LiveSessionState): Promise<void> {
-    const flush = live.init
-      .then(() => this.serialize(session.header.id, () => this.drain(session.header.id, live)))
-      .finally(() => { live.flush = undefined })
-    live.flush = flush
-    void flush.then(() => {
-      if (live.pending.length > 0) this.scheduleDrain(session, live)
-    }, () => {})
-    return flush
-  }
-
-  /** Drain one stable prefix; events admitted during the write remain pending. */
-  private async drain(id: SessionId, live: LiveSessionState): Promise<void> {
-    const batch = live.pending.slice()
+  /** Append one controller-owned prefix after filtering events initialization already stored. */
+  private async appendLiveBatch(id: SessionId, batch: readonly SessionEvent[]): Promise<void> {
     const state = this.states.get(id)
-    /* v8 ignore next -- state is always set by the awaited init before flush */
+    /* v8 ignore next -- state is always set by the awaited initialization */
     const cursor = state?.cursor ?? 0
     const fresh = batch.filter(e => e.seq >= cursor)
     await this.appendCore(id, fresh)
-    live.pending.splice(0, batch.length)
   }
 }
diff --git a/packages/session-persistence/session-persistence/src/index.ts b/packages/session-persistence/session-persistence/src/index.ts
index 94596855df..1d1cf01331 100644
--- a/packages/session-persistence/session-persistence/src/index.ts
+++ b/packages/session-persistence/session-persistence/src/index.ts
@@ -33,6 +33,8 @@ export interface SessionInspection {
 // The backend-agnostic write-path orchestration first-party backends compose.
 export {
   DEFAULT_PREPARED_SESSION_CACHE_SIZE,
+  DEFAULT_WRITE_BATCH_MAX_DELAY_MS,
+  MAX_WRITE_BATCH_DELAY_MS,
   PersistenceCoordinator,
   SessionPersistenceCorruptionError,
 } from './coordinator.ts'
diff --git a/packages/session-persistence/session-persistence/src/write-behind.ts b/packages/session-persistence/session-persistence/src/write-behind.ts
new file mode 100644
index 0000000000..60665455dc
--- /dev/null
+++ b/packages/session-persistence/session-persistence/src/write-behind.ts
@@ -0,0 +1,153 @@
+/**
+ * Bounded per-session write batching for the shared persistence coordinator.
+ * @module @deepseek-ai/dsh-session-persistence/write-behind
+ */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+/** Dependencies and scheduling policy for one live session's write controller. */
+export interface SessionWriteBehindOptions {
+  /** Maximum intentional batching wait after an idle queue receives work. */
+  readonly maxDelayMs: number
+  /** Persist one stable ordered prefix; resolves only after backend durability. */
+  readonly write: (events: readonly SessionEvent[]) => Promise<void>
+  /** Observe a detached background write failure without rejecting the producer. */
+  readonly reportBackgroundFailure: (error: unknown) => void
+}
+
+/**
+ * Owns one live session's pending events, fixed batching deadline, active write,
+ * failure retention, and explicit quiescence barrier.
+ */
+export class SessionWriteBehind {
+  private pending: SessionEvent[] = []
+  private timer: ReturnType<typeof setTimeout> | undefined
+  private active: Promise<void> | undefined
+  private barrier: Promise<void> | undefined
+  private deadlineExpired = false
+  private automaticPaused = false
+
+  /**
+   * @param options - fixed scheduling policy and durable batch sink.
+   */
+  constructor(private readonly options: SessionWriteBehindOptions) {}
+
+  /** Whether this controller owns queued events or an active durable write. */
+  get hasWork(): boolean {
+    return this.pending.length > 0 || this.active !== undefined
+  }
+
+  /**
+   * Copy one event into the persistence-owned queue and start a fixed deadline
+   * when the automatic path is idle.
+   * @param event - frozen live event to retain independently of its producer.
+   */
+  enqueue(event: SessionEvent): void {
+    const wasEmpty = this.pending.length === 0
+    this.pending.push(structuredClone(event))
+    if (this.barrier !== undefined) return
+    if (this.automaticPaused) {
+      this.automaticPaused = false
+      this.deadlineExpired = false
+      this.armTimer()
+    } else if (wasEmpty) {
+      this.armTimer()
+    }
+  }
+
+  /**
+   * Cancel the batching wait and durably drain through a quiescent point.
+   * Concurrent callers join the same barrier.
+   * @returns a promise that rejects if the barrier's durable retry fails.
+   */
+  flush(): Promise<void> {
+    if (this.barrier !== undefined) return this.barrier
+    this.cancelTimer()
+    this.deadlineExpired = false
+    this.automaticPaused = false
+    const barrier = Promise.withResolvers<void>()
+    this.barrier = barrier.promise
+    void this.drainBarrier(barrier.resolve, barrier.reject)
+    return barrier.promise
+  }
+
+  /** Start the one fixed window for the current pending prefix. */
+  private armTimer(): void {
+    this.timer = setTimeout(() => { this.onDeadline() }, this.options.maxDelayMs)
+  }
+
+  /** Cancel any pending automatic deadline. */
+  private cancelTimer(): void {
+    if (this.timer === undefined) return
+    clearTimeout(this.timer)
+    this.timer = undefined
+  }
+
+  /** Start a background write now, or remember that an active write used the budget. */
+  private onDeadline(): void {
+    this.timer = undefined
+    if (this.active !== undefined) {
+      this.deadlineExpired = true
+      return
+    }
+    this.startBackground()
+  }
+
+  /** Start one detached write whose failure is reported and retained. */
+  private startBackground(): void {
+    const active = this.startWrite(true)
+    void active.then(() => { this.continueAutomatic() }, () => {})
+  }
+
+  /** Continue immediately after an over-budget active write, otherwise keep its timer. */
+  private continueAutomatic(): void {
+    if (this.barrier !== undefined || this.pending.length === 0) return
+    if (this.deadlineExpired) {
+      this.deadlineExpired = false
+      this.startBackground()
+    }
+  }
+
+  /** Await overlapping work, drain to quiescence, and settle the shared barrier. */
+  private async drainBarrier(resolve: () => void, reject: (reason?: unknown) => void): Promise<void> {
+    try {
+      const overlapping = this.active
+      if (overlapping !== undefined) {
+        await Promise.allSettled([overlapping])
+        this.automaticPaused = false
+      }
+      while (this.pending.length > 0) await this.startWrite(false)
+    } catch (error: unknown) {
+      this.barrier = undefined
+      reject(error)
+      return
+    }
+    // Close admission to this barrier in the same job that observes the empty
+    // queue, before resolving callers. A later enqueue therefore starts its own
+    // automatic window instead of being stranded behind a settled barrier.
+    this.barrier = undefined
+    resolve()
+  }
+
+  /** Start one stable pending prefix, retaining it in order if durability fails. */
+  private startWrite(background: boolean): Promise<void> {
+    const batch = this.pending.splice(0)
+    this.cancelTimer()
+    this.deadlineExpired = false
+    const operation = Promise.resolve().then(() => this.options.write(batch))
+    const active = operation
+      .catch((error: unknown) => {
+        this.pending.unshift(...batch)
+        this.cancelTimer()
+        this.deadlineExpired = false
+        this.automaticPaused = true
+        if (background) this.options.reportBackgroundFailure(error)
+        throw error
+      })
+      .finally(() => {
+        this.active = undefined
+      })
+    this.active = active
+    return active
+  }
+}
diff --git a/packages/session-persistence/session-persistence/tests/persistence.spec.ts b/packages/session-persistence/session-persistence/tests/persistence.spec.ts
index 8fac982591..14b4f9b951 100644
--- a/packages/session-persistence/session-persistence/tests/persistence.spec.ts
+++ b/packages/session-persistence/session-persistence/tests/persistence.spec.ts
@@ -3,6 +3,7 @@ import { Context } from 'cordis'
 import SessionStore, { Session, SessionId, isJsonValue } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import {
+  DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS,
   SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
   type PersistenceBackend, type SessionPersistenceSnapshot, type StoredPrefix, type StoredSuffix,
 } from '../src/index.ts'
@@ -53,7 +54,9 @@ interface MemoryConfig { store?: MemoryStore }
 /** Test-only view of the coordinator containers whose retirement is the contract under test. */
 interface CoordinatorInternals {
   states: Map<unknown, unknown>
-  live: Map<unknown, { pending: unknown[]; flush: Promise<void> | undefined }>
+  live: Map<unknown, {
+    writes: { pending: unknown[]; active: Promise<void> | undefined; hasWork: boolean }
+  }>
   chains: Map<unknown, unknown>
   retirements: Map<unknown, Promise<void>>
 }
@@ -253,7 +256,7 @@ runCoordinatorContract('memory', async (): Promise<CoordinatorFixture> => {
   }
 })
 
-describe('PersistenceCoordinator eager writes', () => {
+describe('PersistenceCoordinator bounded writes', () => {
   it('starts a follow-up batch for events admitted during an in-flight write', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
@@ -263,11 +266,14 @@ describe('PersistenceCoordinator eager writes', () => {
       if (attempt === 1) await appendGate.promise
     }
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      new PersistenceCoordinator(inner, backend)
+      new PersistenceCoordinator(inner, backend, {
+        preparedSessionCacheSize: DEFAULT_PREPARED_SESSION_CACHE_SIZE,
+        writeBatchMaxDelayMs: 1,
+      })
     }, { inject: ['sessions'] }))
 
     try {
-      const session = ctx.sessions.create(SessionId('eager-follow-up'))
+      const session = ctx.sessions.create(SessionId('bounded-follow-up'))
       await ctx.sessions.flush(session)
       session.append('turn/start', { turn: 1 })
       await vi.waitFor(() => { expect(backend.appendAttempts).toBe(1) })
@@ -286,7 +292,7 @@ describe('PersistenceCoordinator eager writes', () => {
     }
   })
 
-  it('retries a failed overlapping eager write at the explicit flush barrier', async () => {
+  it('retries a failed overlapping background write at the explicit flush barrier', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const backend = new ControlledBackend()
@@ -294,15 +300,18 @@ describe('PersistenceCoordinator eager writes', () => {
     backend.beforeAppend = async (attempt) => {
       if (attempt === 1) {
         await appendGate.promise
-        throw new Error('transient eager failure')
+        throw new Error('transient background failure')
       }
     }
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      new PersistenceCoordinator(inner, backend)
+      new PersistenceCoordinator(inner, backend, {
+        preparedSessionCacheSize: DEFAULT_PREPARED_SESSION_CACHE_SIZE,
+        writeBatchMaxDelayMs: 1,
+      })
     }, { inject: ['sessions'] }))
 
     try {
-      const session = ctx.sessions.create(SessionId('eager-flush-retry'))
+      const session = ctx.sessions.create(SessionId('bounded-flush-retry'))
       await ctx.sessions.flush(session)
       session.append('turn/start', { turn: 1 })
       session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
@@ -401,9 +410,20 @@ describe('PersistenceCoordinator session preparations', () => {
 
     expect(() => new PersistenceCoordinator(ctx, backend, {
       preparedSessionCacheSize: capacity,
+      writeBatchMaxDelayMs: DEFAULT_WRITE_BATCH_MAX_DELAY_MS,
     })).toThrow(/positive safe integer/)
   })
 
+  it.each([0, 1.5, MAX_WRITE_BATCH_DELAY_MS + 1])('rejects invalid write batch delay %s', (delay) => {
+    const ctx = new Context()
+    const backend = new ControlledBackend()
+
+    expect(() => new PersistenceCoordinator(ctx, backend, {
+      preparedSessionCacheSize: DEFAULT_PREPARED_SESSION_CACHE_SIZE,
+      writeBatchMaxDelayMs: delay,
+    })).toThrow(/writeBatchMaxDelayMs must be an integer between/)
+  })
+
   it('retries invalidated prepare and load reservations', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
@@ -592,6 +612,39 @@ describe('PersistenceCoordinator session preparations', () => {
     }
   })
 
+  it('writes new events after publishing a preparation with no unpublished suffix', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const id = SessionId('prepared-live-write')
+    const stored = [
+      ...oneTurnLog(),
+      { type: 'session/end-seed', seq: 6, time: 7, data: {} } as SessionEvent,
+    ]
+    backend.store.set(id, { meta: meta(id), events: stored })
+    let coordinator!: PersistenceCoordinator<never>
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      coordinator = new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+    const preparation = await coordinator.prepare(id)
+    const detach = ctx.sessions.enter(preparation.session)
+
+    try {
+      ctx.sessions.announce(preparation.session)
+      preparation.session.append('turn/start', { turn: 2 })
+      preparation.session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
+
+      await expect(ctx.sessions.flush(preparation.session)).resolves.toBe(true)
+      expect(backend.store.get(id)?.events.map(event => event.seq))
+        .toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8])
+    } finally {
+      detach()
+      preparation[Symbol.dispose]()
+      await fiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+
   it('reuses the exact Session from inspect through repeated unpublished prepare calls', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
@@ -1004,7 +1057,10 @@ describe('PersistenceCoordinator session preparations', () => {
     backend.store.set(secondId, { meta: meta(secondId), events: oneTurnLog() })
     let coordinator!: PersistenceCoordinator<never>
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      coordinator = new PersistenceCoordinator(inner, backend, { preparedSessionCacheSize: 1 })
+      coordinator = new PersistenceCoordinator(inner, backend, {
+        preparedSessionCacheSize: 1,
+        writeBatchMaxDelayMs: DEFAULT_WRITE_BATCH_MAX_DELAY_MS,
+      })
     }, { inject: ['sessions'] }))
 
     try {
@@ -1529,7 +1585,7 @@ describe('PersistenceCoordinator retirement', () => {
 
       await vi.waitFor(() => {
         expect(backend.appendAttempts).toBeGreaterThanOrEqual(1)
-        expect([...internals.live.values()][0]?.pending).toEqual(expect.arrayContaining([
+        expect([...internals.live.values()][0]?.writes.pending).toEqual(expect.arrayContaining([
           expect.objectContaining({ seq: 0 }),
           expect.objectContaining({ seq: 1 }),
         ]))
@@ -1573,7 +1629,7 @@ describe('PersistenceCoordinator retirement', () => {
       await vi.waitFor(() => {
         expect(backend.appendAttempts).toBe(1)
         expect(internals.live.size).toBe(1)
-        expect([...internals.live.values()][0]?.flush).toBeInstanceOf(Promise)
+        expect([...internals.live.values()][0]?.writes.active).toBeInstanceOf(Promise)
       })
 
       let disposed = false
diff --git a/packages/session-persistence/session-persistence/tests/write-behind.spec.ts b/packages/session-persistence/session-persistence/tests/write-behind.spec.ts
new file mode 100644
index 0000000000..b93b3824ae
--- /dev/null
+++ b/packages/session-persistence/session-persistence/tests/write-behind.spec.ts
@@ -0,0 +1,252 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { SessionWriteBehind } from '../src/write-behind.ts'
+
+/** Minimal ordered event fixture; batching does not interpret event vocabulary. */
+function event(seq: number): SessionEvent<'turn/start'> {
+  return {
+    type: 'turn/start',
+    seq,
+    time: seq,
+    data: { turn: seq + 1 },
+  }
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('SessionWriteBehind', () => {
+  it('uses one fixed window from the first queued event and owns its copy', async () => {
+    vi.useFakeTimers()
+    const batches: SessionEvent[][] = []
+    const controller = new SessionWriteBehind({
+      maxDelayMs: 200,
+      write: async (events) => { batches.push(structuredClone(events) as SessionEvent[]) },
+      reportBackgroundFailure: vi.fn(),
+    })
+    const first = event(0)
+
+    controller.enqueue(first)
+    first.data.turn = 99
+    await vi.advanceTimersByTimeAsync(150)
+    controller.enqueue(event(1))
+    await vi.advanceTimersByTimeAsync(49)
+    expect(batches).toEqual([])
+
+    await vi.advanceTimersByTimeAsync(1)
+    expect(batches).toEqual([[
+      expect.objectContaining({ seq: 0, data: { turn: 1 } }),
+      expect.objectContaining({ seq: 1 }),
+    ]])
+    expect(controller.hasWork).toBe(false)
+  })
+
+  it('coalesces twenty events admitted ten milliseconds apart into one 200 ms batch', async () => {
+    vi.useFakeTimers()
+    const batches: number[][] = []
+    const controller = new SessionWriteBehind({
+      maxDelayMs: 200,
+      write: async (events) => { batches.push(events.map(item => item.seq)) },
+      reportBackgroundFailure: vi.fn(),
+    })
+
+    controller.enqueue(event(0))
+    for (let seq = 1; seq < 20; seq += 1) {
+      await vi.advanceTimersByTimeAsync(10)
+      controller.enqueue(event(seq))
+    }
+    expect(batches).toEqual([])
+
+    await vi.advanceTimersByTimeAsync(10)
+    expect(batches).toEqual([Array.from({ length: 20 }, (_, seq) => seq)])
+    await controller.flush()
+  })
+
+  it('makes concurrent flushes one immediate barrier that drains admitted tails', async () => {
+    vi.useFakeTimers()
+    const gate = Promise.withResolvers<boolean>()
+    const batches: number[][] = []
+    const controller = new SessionWriteBehind({
+      maxDelayMs: 200,
+      write: async (events) => {
+        batches.push(events.map(item => item.seq))
+        if (batches.length === 1) await gate.promise
+      },
+      reportBackgroundFailure: vi.fn(),
+    })
+
+    controller.enqueue(event(0))
+    const first = controller.flush()
+    const second = controller.flush()
+    expect(second).toBe(first)
+    await Promise.resolve()
+    expect(batches).toEqual([[0]])
+
+    controller.enqueue(event(1))
+    gate.resolve(true)
+    await first
+    expect(batches).toEqual([[0], [1]])
+    expect(controller.hasWork).toBe(false)
+    expect(vi.getTimerCount()).toBe(0)
+  })
+
+  it('starts a new window for work admitted after an already-quiescent barrier', async () => {
+    vi.useFakeTimers()
+    const batches: number[][] = []
+    const controller = new SessionWriteBehind({
+      maxDelayMs: 200,
+      write: async (events) => { batches.push(events.map(item => item.seq)) },
+      reportBackgroundFailure: vi.fn(),
+    })
+
+    const barrier = controller.flush()
+    controller.enqueue(event(0))
+    await barrier
+    expect(batches).toEqual([])
+    expect(vi.getTimerCount()).toBe(1)
+
+    await vi.advanceTimersByTimeAsync(200)
+    expect(batches).toEqual([[0]])
+    expect(controller.hasWork).toBe(false)
+  })
+
+  it('starts an over-budget tail immediately after the active write', async () => {
+    vi.useFakeTimers()
+    const gate = Promise.withResolvers<boolean>()
+    const batches: number[][] = []
+    const controller = new SessionWriteBehind({
+      maxDelayMs: 200,
+      write: async (events) => {
+        batches.push(events.map(item => item.seq))
+        if (batches.length === 1) await gate.promise
+      },
+      reportBackgroundFailure: vi.fn(),
+    })
+
+    controller.enqueue(event(0))
+    await vi.advanceTimersByTimeAsync(200)
+    expect(batches).toEqual([[0]])
+    controller.enqueue(event(1))
+    await vi.advanceTimersByTimeAsync(200)
+    expect(batches).toEqual([[0]])
+
+    gate.resolve(true)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(batches).toEqual([[0], [1]])
+    await controller.flush()
+  })
+
+  it('keeps a tail deadline that has not expired when the active write finishes', async () => {
+    vi.useFakeTimers()
+    const gate = Promise.withResolvers<boolean>()
+    const batches: number[][] = []
+    const controller = new SessionWriteBehind({
+      maxDelayMs: 200,
+      write: async (events) => {
+        batches.push(events.map(item => item.seq))
+        if (batches.length === 1) await gate.promise
+      },
+      reportBackgroundFailure: vi.fn(),
+    })
+
+    controller.enqueue(event(0))
+    await vi.advanceTimersByTimeAsync(200)
+    controller.enqueue(event(1))
+    await vi.advanceTimersByTimeAsync(50)
+    gate.resolve(true)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(batches).toEqual([[0]])
+
+    await vi.advanceTimersByTimeAsync(149)
+    expect(batches).toEqual([[0]])
+    await vi.advanceTimersByTimeAsync(1)
+    expect(batches).toEqual([[0], [1]])
+    await controller.flush()
+  })
+
+  it('pauses automatic retries after failure and preserves order for new work', async () => {
+    vi.useFakeTimers()
+    const failure = new Error('storage unavailable')
+    const report = vi.fn()
+    const batches: number[][] = []
+    let attempt = 0
+    const controller = new SessionWriteBehind({
+      maxDelayMs: 200,
+      write: async (events) => {
+        batches.push(events.map(item => item.seq))
+        if (++attempt === 1) throw failure
+      },
+      reportBackgroundFailure: report,
+    })
+
+    controller.enqueue(event(0))
+    await vi.advanceTimersByTimeAsync(200)
+    expect(report).toHaveBeenCalledWith(failure)
+    expect(controller.hasWork).toBe(true)
+    await vi.advanceTimersByTimeAsync(1_000)
+    expect(batches).toEqual([[0]])
+
+    controller.enqueue(event(1))
+    await vi.advanceTimersByTimeAsync(199)
+    expect(batches).toEqual([[0]])
+    await vi.advanceTimersByTimeAsync(1)
+    expect(batches).toEqual([[0], [0, 1]])
+    await controller.flush()
+  })
+
+  it('observes an overlapping background failure and retries it inside flush', async () => {
+    vi.useFakeTimers()
+    const gate = Promise.withResolvers<boolean>()
+    const report = vi.fn()
+    const batches: number[][] = []
+    const controller = new SessionWriteBehind({
+      maxDelayMs: 200,
+      write: async (events) => {
+        batches.push(events.map(item => item.seq))
+        if (batches.length === 1) {
+          await gate.promise
+          throw new Error('transient')
+        }
+      },
+      reportBackgroundFailure: report,
+    })
+
+    controller.enqueue(event(0))
+    await vi.advanceTimersByTimeAsync(200)
+    const first = controller.flush()
+    const second = controller.flush()
+    gate.resolve(true)
+
+    await expect(Promise.all([first, second])).resolves.toEqual([undefined, undefined])
+    expect(batches).toEqual([[0], [0]])
+    expect(report).toHaveBeenCalledOnce()
+    expect(controller.hasWork).toBe(false)
+  })
+
+  it('surfaces a barrier failure without detached logging and retains its batch', async () => {
+    vi.useFakeTimers()
+    const failure = new Error('durability failed')
+    const report = vi.fn()
+    const batches: number[][] = []
+    let attempt = 0
+    const controller = new SessionWriteBehind({
+      maxDelayMs: 200,
+      write: async (events) => {
+        batches.push(events.map(item => item.seq))
+        if (++attempt === 1) throw failure
+      },
+      reportBackgroundFailure: report,
+    })
+
+    controller.enqueue(event(0))
+    await expect(controller.flush()).rejects.toBe(failure)
+    expect(report).not.toHaveBeenCalled()
+    expect(controller.hasWork).toBe(true)
+
+    controller.enqueue(event(1))
+    await vi.advanceTimersByTimeAsync(200)
+    expect(batches).toEqual([[0], [0, 1]])
+    await controller.flush()
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6b7cd40f94..05ac9ec74b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4801,6 +4801,9 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis

From 81d32bf52cff95d219c8987a01cccfa76225d1e3 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 15:46:08 +0800
Subject: [PATCH 240/516] test(web): isolate sidebar subagent activity snapshot

---
 ...07-27-web-subagent-conversations.i18n.yaml |   4 +-
 .../2026-07-27-web-subagent-conversations.md  |   2 +-
 ...026-07-27-web-subagent-conversations.zh.md |   2 +-
 .../tests/sidebar-subagent-activity.e2e.ts    | 152 ++++++++++++++++++
 .../owner-running.expected.md                 |   6 +
 .../sidebar-running.expected.md               |   5 -
 apps/web/tests/subagent-conversation.e2e.ts   |  10 --
 apps/web/tsconfig.json                        |   1 +
 tsconfig.host.json                            |   1 +
 9 files changed, 164 insertions(+), 19 deletions(-)
 create mode 100644 apps/web/tests/sidebar-subagent-activity.e2e.ts
 create mode 100644 apps/web/tests/snapshots/sidebar-subagent-activity/owner-running.expected.md
 delete mode 100644 apps/web/tests/snapshots/subagent-conversation/sidebar-running.expected.md

diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index f93d3a4a34..05b99f0d68 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: 1b9bbfbc566e77932629af9f1e0714819973f111
-2026-07-27-web-subagent-conversations.zh.md: a9ed0e20f3617f7f5f8ae9d0f2d77c7ba8aef9ea
+2026-07-27-web-subagent-conversations.md: bcfaf5d958d2e886082d24c37da7600abb47953c
+2026-07-27-web-subagent-conversations.zh.md: 6b7299b4089c6413b99d2bedbc2bb8961b27735c
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index 1b9bbfbc56..bcfaf5d958 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -105,7 +105,7 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 - Generic Host tests pin attached and cold history and forks without Agent publication, cold projection folding, descriptor/origin/runtime-owner denial, explicit-id adoption denial, and the direct queue-control fence.
 - Client object tests pin retained and restored addresses, one-shot read-only rejection, history routing, continuable prompt routing, no addressed cancellation, suppression of Agent-bound model controls, live activity flips including in-flight response replay and detach fallback, subagent-parent expandability flips, and membership refresh.
 - jsdom tests pin the aggregate descendant count and activity, sidebar propagation across nested lineage and ordinary-fork boundaries, row-status precedence, token totals, second-precision running and frozen inactive durations, adaptive long-duration units with exact accessible text, the summary-backed root action across absent and stale-empty catalogs, known loading-row shape, mixed-mode rows, pre-click leaf disclosure, diagnostics, lazy descendant disclosure, direct-parent addresses, keyboard behavior, and both read-only reasons.
-- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, aggregate running transition in the header and owner sidebar row, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only.
+- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, and the header's aggregate running transition, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the model seam while it pins the visible idle owner's aggregate running state, then cancels the turn during teardown.
 - Navigation tests pin subagent-only breadcrumbs, workspace placement for forks created from subagents, and `origin: 'subagent'` sidebar filtering without hiding ordinary forks.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index a9ed0e20f3..6b7299b408 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -105,7 +105,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 - 通用 Host 测试固定在不发布 Agent 的情况下读取已附加与冷态历史及执行 fork、冷态投影归并、按描述符／origin／运行时 owner 拒绝、拒绝显式 id 接纳，以及直接队列控制栅栏。
 - 客户端对象测试固定已保留与已恢复的地址、one-shot 只读拒绝、历史路由、可继续提示词路由、已寻址对话不提供取消、屏蔽绑定到 agent 的模型控件、实时活动状态翻转（包括在途响应回放与 detach 回退）、subagent parent 可展开性翻转与成员刷新。
 - jsdom 测试固定后代聚合计数与活动状态、侧边栏活动在嵌套谱系中的传播与普通 fork 边界、行状态优先级、token 用量总计、精确到秒的运行中耗时与冻结后 inactive 耗时、采用自适应单位的长耗时及其精确无障碍文本、目录缺失或为陈旧空目录时由摘要支撑的根操作、已知加载行的形态、混合 mode 行、点击前的叶子展开控件、diagnostic、后代懒加载展开、直接 parent 地址、键盘行为与两种只读原因。
-- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现以及页头和 owner 侧边栏行中的聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。
+- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现以及页头中的聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 model seam 处保持一个真实的 child Agent 轮次进行中，同时固定可见空闲 owner 的聚合运行状态，随后在 teardown 期间取消该轮次。
 - 导航测试固定仅含 subagent 的面包屑导航、从 subagent 创建 fork 时的 Workspace 归属，以及 `origin: 'subagent'` 侧边栏过滤，同时不隐藏普通 fork。
 
 ## 后果
diff --git a/apps/web/tests/sidebar-subagent-activity.e2e.ts b/apps/web/tests/sidebar-subagent-activity.e2e.ts
new file mode 100644
index 0000000000..b7d24b6a09
--- /dev/null
+++ b/apps/web/tests/sidebar-subagent-activity.e2e.ts
@@ -0,0 +1,152 @@
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import type { AgentHandle } from '@deepseek-ai/dsh-agent'
+import { createUserMessage, LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { SessionId, type SessionId as SessionIdValue } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-subagent'
+import type {} from '@deepseek-ai/dsh-workspace'
+import {
+  assertFixtureInventory,
+  captureStableAria,
+  compareOrRefreshGolden,
+  launchWebScaffold,
+  watchConsole,
+  webSnapshotMode,
+  type WebScaffold,
+} from './scaffold.ts'
+import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/sidebar-subagent-activity', import.meta.url))
+const RUNNING_OWNER_EXPECTED = join(SNAPSHOT_DIR, 'owner-running.expected.md')
+const MODE = webSnapshotMode()
+const HOLD_PROVIDER = 'web-test-hold'
+const HOLD_MODEL = 'hold'
+
+/** Model seam that completes the owner turn, then holds its delegated child open. */
+class StagedAdapter extends LlmAdapter {
+  activeCalls = 0
+  private calls = 0
+
+  override async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    if (this.calls === 0) {
+      this.calls += 1
+      yield { type: 'finish', reason: { kind: 'stop' } }
+      return
+    }
+    this.calls += 1
+    const signal = options.signal
+    if (signal === undefined) throw new Error('staged Web adapter requires a turn signal')
+    this.activeCalls += 1
+    try {
+      await new Promise<never>((_resolve, reject) => {
+        const abort = (): void => {
+          reject(signal.reason instanceof Error ? signal.reason : new Error('holding Web adapter aborted'))
+        }
+        if (signal.aborted) abort()
+        else signal.addEventListener('abort', abort, { once: true })
+      })
+    } finally {
+      this.activeCalls -= 1
+    }
+  }
+}
+
+async function waitForRunningChild(
+  scaffold: WebScaffold,
+  adapter: StagedAdapter,
+  childId: SessionIdValue,
+): Promise<void> {
+  const deadline = Date.now() + 10_000
+  while (adapter.activeCalls !== 1 || scaffold.ctx.agents.get(childId)?.status !== 'running') {
+    if (Date.now() >= deadline) throw new Error('held child did not enter its running model call')
+    await new Promise<void>(resolve => setTimeout(resolve, 10))
+  }
+}
+
+describe('web e2e: sidebar subagent activity', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let parentHandle: AgentHandle
+  let childId: SessionIdValue
+  let adapter: StagedAdapter
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold()
+    adapter = new StagedAdapter()
+    scaffold.ctx.effect(
+      () => scaffold.ctx.llm.registerAdapter([HOLD_PROVIDER], adapter),
+      'sidebar subagent activity staged adapter',
+    )
+    const cwd = join(scaffold.workspaceCwd, 'workspace')
+    await mkdir(cwd)
+    parentHandle = await scaffold.ctx.agents.create({
+      sessionId: SessionId('sidebar-activity-owner'),
+      meta: { cwd },
+      agentOptions: { provider: HOLD_PROVIDER, model: HOLD_MODEL },
+    })
+    parentHandle.agent.followup(createUserMessage({
+      content: [{ type: 'text', text: 'Delegate a background task.' }],
+      source: { kind: 'user' },
+    }))
+    await parentHandle.agent.whenIdle()
+    const started = await scaffold.ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'sidebar activity child',
+      signal: new AbortController().signal,
+      request: {
+        prompt: [{ type: 'text', text: 'Hold this delegated task open.' }],
+        parent: parentHandle.agent,
+      },
+    })
+    childId = started.childId
+    await waitForRunningChild(scaffold, adapter, childId)
+
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    await connectFreshWorkspace(page, scaffold.workspaceCwd)
+    const workspace = await scaffold.ctx.workspace.resolveByPath(cwd)
+    if (workspace === undefined) throw new Error('connected Web workspace was not registered')
+    await workspace.attachSession(parentHandle.agent.session.id)
+  }, 60_000)
+
+  afterAll(async () => {
+    const failures: unknown[] = []
+    const child = childId === undefined ? undefined : scaffold?.ctx.agents.get(childId)
+    if (child !== undefined) {
+      child.cancel({ kind: 'user' })
+      await child.whenIdle().catch((error: unknown) => failures.push(error))
+    }
+    await browser?.close().catch((error: unknown) => failures.push(error))
+    await parentHandle?.dispose().catch((error: unknown) => failures.push(error))
+    await scaffold?.close().catch((error: unknown) => failures.push(error))
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, 'sidebar subagent activity teardown failed')
+  })
+
+  it('pins a running descendant on its visible idle owner row', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-subagent-activity'))
+    const sidebar = page.getByRole('tree', { name: 'Sessions' })
+    const ownerRow = sidebar.getByRole('treeitem', { name: /1 subagent running Delegate a background task/ })
+    await ownerRow.waitFor({ timeout: 10_000 })
+    expect(parentHandle.agent.status).toBe('idle')
+    await compareOrRefreshGolden(
+      RUNNING_OWNER_EXPECTED,
+      await captureStableAria(page, '[role="tree"][aria-label="Sessions"]', scaffold.workspaceCwd),
+      MODE,
+    )
+    expect(await ownerRow.locator('[data-state="ongoing"]').count()).toBe(1)
+    await assertFixtureInventory(SNAPSHOT_DIR, ['owner-running.expected.md'])
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  })
+})
diff --git a/apps/web/tests/snapshots/sidebar-subagent-activity/owner-running.expected.md b/apps/web/tests/snapshots/sidebar-subagent-activity/owner-running.expected.md
new file mode 100644
index 0000000000..c5a2766750
--- /dev/null
+++ b/apps/web/tests/snapshots/sidebar-subagent-activity/owner-running.expected.md
@@ -0,0 +1,6 @@
+- tree "Sessions":
+  - treeitem "workspace 2 sessions" [expanded]:
+    - img
+    - text: workspace 2 sessions
+  - treeitem "1 subagent running Delegate a background task. now"
+  - treeitem "New Session" [selected]
diff --git a/apps/web/tests/snapshots/subagent-conversation/sidebar-running.expected.md b/apps/web/tests/snapshots/subagent-conversation/sidebar-running.expected.md
deleted file mode 100644
index fec6fe658e..0000000000
--- a/apps/web/tests/snapshots/subagent-conversation/sidebar-running.expected.md
+++ /dev/null
@@ -1,5 +0,0 @@
-- tree "Sessions":
-  - treeitem "workspace 1 session" [expanded]:
-    - img
-    - text: workspace 1 session
-  - treeitem "1 subagent running Ask a research subagent to now" [selected]
diff --git a/apps/web/tests/subagent-conversation.e2e.ts b/apps/web/tests/subagent-conversation.e2e.ts
index 69250ed6b6..0049cb2791 100644
--- a/apps/web/tests/subagent-conversation.e2e.ts
+++ b/apps/web/tests/subagent-conversation.e2e.ts
@@ -23,7 +23,6 @@ const TREE_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/t
 const BRANCHLESS_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/branchless.expected.md', import.meta.url))
 const STALE_CATALOG_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/stale-catalog.expected.md', import.meta.url))
 const SIDEBAR_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/sidebar.expected.md', import.meta.url))
-const RUNNING_SIDEBAR_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/sidebar-running.expected.md', import.meta.url))
 const UNAVAILABLE_GRANDCHILD_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/nested.expected.md', import.meta.url))
 const FORK_EXPECTED = fileURLToPath(new URL('./snapshots/subagent-conversation/fork.expected.md', import.meta.url))
 const MODE = webSnapshotMode()
@@ -368,15 +367,6 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
     ).toBe('running')
     const hierarchy = page.getByRole('navigation', { name: 'Session hierarchy' })
     await hierarchy.getByRole('button').first().click()
-    const runningOwnerRow = page.getByRole('tree', { name: 'Sessions' })
-      .getByRole('treeitem', { name: /1 subagent running/ })
-    await runningOwnerRow.waitFor({ timeout: 10_000 })
-    expect(await runningOwnerRow.locator('[data-state="ongoing"]').count()).toBe(1)
-    await compareOrRefreshGolden(
-      RUNNING_SIDEBAR_EXPECTED,
-      await captureStableAria(page, '[role="tree"][aria-label="Sessions"]', scaffold.workspaceCwd),
-      MODE,
-    )
     const runningTrigger = page.getByRole('button', { name: '3 subagents running' })
     await runningTrigger.waitFor({ timeout: 10_000 })
     expect(await runningTrigger.locator('[data-state="ongoing"]').count()).toBe(1)
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 781cb57a2e..354781e934 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -66,6 +66,7 @@
     "tests/produced-files.e2e.ts",
     "tests/goal-bar.e2e.ts",
     "tests/subagent-conversation.e2e.ts",
+    "tests/sidebar-subagent-activity.e2e.ts",
     "tests/bash-abort-row.e2e.ts",
     "tests/skill-tool-row.e2e.ts",
     "tests/turn-tail-actions.e2e.ts",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 1467555ed1..f3a3493b3a 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -53,6 +53,7 @@
     "apps/web/tests/startup-auto-selection.e2e.ts",
     "apps/web/tests/produced-files.e2e.ts",
     "apps/web/tests/subagent-conversation.e2e.ts",
+    "apps/web/tests/sidebar-subagent-activity.e2e.ts",
     "apps/web/tests/bash-abort-row.e2e.ts",
     "apps/web/tests/skill-tool-row.e2e.ts",
     "apps/web/tests/turn-tail-actions.e2e.ts",

From b837e30a80d939693fc2f1aa386554560d4f27ea Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:48:22 +0800
Subject: [PATCH 241/516] test(apiproxy): register question callers

---
 .../host/apiproxy/tests/api-proxy-question.spec.ts | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/packages/host/apiproxy/tests/api-proxy-question.spec.ts b/packages/host/apiproxy/tests/api-proxy-question.spec.ts
index ee5747039f..32835f5054 100644
--- a/packages/host/apiproxy/tests/api-proxy-question.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-question.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { ApiProxy, MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -10,6 +10,7 @@ import { createApiProxy } from '../src/api-proxy.ts'
 async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
   await ctx.plugin(UserInteractionService)
   return {
     ctx,
@@ -17,8 +18,11 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
   }
 }
 
-function agent(id: string): Agent {
-  return { id } as unknown as Agent
+function agent(ctx: Context): Agent {
+  const session = ctx.sessions.create()
+  const value = { id: session.id, session, status: 'idle', ctx } as Agent
+  ctx.agents.register(value)
+  return value
 }
 
 function openMux(api: ApiProxy, abort: AbortController): {
@@ -71,7 +75,7 @@ describe('question response validation', () => {
     const abort = new AbortController()
     const mux = openMux(api, abort)
     const asked = ctx.userInteraction.ask({
-      agent: agent('session-multi'),
+      agent: agent(ctx),
       questions: [{
         id: 'targets',
         question: 'Choose targets and add another',
@@ -95,7 +99,7 @@ describe('question response validation', () => {
     const abort = new AbortController()
     const mux = openMux(api, abort)
     const asked = ctx.userInteraction.ask({
-      agent: agent('session-single'),
+      agent: agent(ctx),
       questions: [{
         id: 'target',
         question: 'Choose one target',

From fb1d2305181b84ea4bee32d68653d2cf2bf28b92 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 8 Aug 2026 15:56:36 +0800
Subject: [PATCH 242/516] test(web): avoid replay timing assertions

---
 ...026-07-27-web-subagent-conversations.i18n.yaml |  4 ++--
 .../2026-07-27-web-subagent-conversations.md      |  2 +-
 .../2026-07-27-web-subagent-conversations.zh.md   |  2 +-
 apps/web/tests/sidebar-subagent-activity.e2e.ts   |  4 ++++
 apps/web/tests/subagent-conversation.e2e.ts       | 15 ---------------
 5 files changed, 8 insertions(+), 19 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index 05b99f0d68..56952f8b69 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: bcfaf5d958d2e886082d24c37da7600abb47953c
-2026-07-27-web-subagent-conversations.zh.md: 6b7299b4089c6413b99d2bedbc2bb8961b27735c
+2026-07-27-web-subagent-conversations.md: edaaa97bbfcf0ce1751db84d8fc2d3ab07af8b03
+2026-07-27-web-subagent-conversations.zh.md: 4c5e670cc46621b889d8463daa90afbf43bde30f
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index bcfaf5d958..edaaa97bbf 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -105,7 +105,7 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 - Generic Host tests pin attached and cold history and forks without Agent publication, cold projection folding, descriptor/origin/runtime-owner denial, explicit-id adoption denial, and the direct queue-control fence.
 - Client object tests pin retained and restored addresses, one-shot read-only rejection, history routing, continuable prompt routing, no addressed cancellation, suppression of Agent-bound model controls, live activity flips including in-flight response replay and detach fallback, subagent-parent expandability flips, and membership refresh.
 - jsdom tests pin the aggregate descendant count and activity, sidebar propagation across nested lineage and ordinary-fork boundaries, row-status precedence, token totals, second-precision running and frozen inactive durations, adaptive long-duration units with exact accessible text, the summary-backed root action across absent and stale-empty catalogs, known loading-row shape, mixed-mode rows, pre-click leaf disclosure, diagnostics, lazy descendant disclosure, direct-parent addresses, keyboard behavior, and both read-only reasons.
-- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, and the header's aggregate running transition, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the model seam while it pins the visible idle owner's aggregate running state, then cancels the turn during teardown.
+- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, and adaptive long-duration presentation, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the model seam while it pins the aggregate running state in both the header and visible idle owner row, then cancels the turn during teardown.
 - Navigation tests pin subagent-only breadcrumbs, workspace placement for forks created from subagents, and `origin: 'subagent'` sidebar filtering without hiding ordinary forks.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index 6b7299b408..4c5e670cc4 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -105,7 +105,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 - 通用 Host 测试固定在不发布 Agent 的情况下读取已附加与冷态历史及执行 fork、冷态投影归并、按描述符／origin／运行时 owner 拒绝、拒绝显式 id 接纳，以及直接队列控制栅栏。
 - 客户端对象测试固定已保留与已恢复的地址、one-shot 只读拒绝、历史路由、可继续提示词路由、已寻址对话不提供取消、屏蔽绑定到 agent 的模型控件、实时活动状态翻转（包括在途响应回放与 detach 回退）、subagent parent 可展开性翻转与成员刷新。
 - jsdom 测试固定后代聚合计数与活动状态、侧边栏活动在嵌套谱系中的传播与普通 fork 边界、行状态优先级、token 用量总计、精确到秒的运行中耗时与冻结后 inactive 耗时、采用自适应单位的长耗时及其精确无障碍文本、目录缺失或为陈旧空目录时由摘要支撑的根操作、已知加载行的形态、混合 mode 行、点击前的叶子展开控件、diagnostic、后代懒加载展开、直接 parent 地址、键盘行为与两种只读原因。
-- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现以及页头中的聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 model seam 处保持一个真实的 child Agent 轮次进行中，同时固定可见空闲 owner 的聚合运行状态，随后在 teardown 期间取消该轮次。
+- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行及自适应长耗时呈现，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 model seam 处保持一个真实的 child Agent 轮次进行中，同时固定页头和可见空闲 owner 行中的聚合运行状态，随后在 teardown 期间取消该轮次。
 - 导航测试固定仅含 subagent 的面包屑导航、从 subagent 创建 fork 时的 Workspace 归属，以及 `origin: 'subagent'` 侧边栏过滤，同时不隐藏普通 fork。
 
 ## 后果
diff --git a/apps/web/tests/sidebar-subagent-activity.e2e.ts b/apps/web/tests/sidebar-subagent-activity.e2e.ts
index b7d24b6a09..4c37ea6fc1 100644
--- a/apps/web/tests/sidebar-subagent-activity.e2e.ts
+++ b/apps/web/tests/sidebar-subagent-activity.e2e.ts
@@ -145,6 +145,10 @@ describe('web e2e: sidebar subagent activity', () => {
       MODE,
     )
     expect(await ownerRow.locator('[data-state="ongoing"]').count()).toBe(1)
+    await ownerRow.click()
+    const runningTrigger = page.getByRole('button', { name: '1 subagent running' })
+    await runningTrigger.waitFor({ timeout: 10_000 })
+    expect(await runningTrigger.locator('[data-state="ongoing"]').count()).toBe(1)
     await assertFixtureInventory(SNAPSHOT_DIR, ['owner-running.expected.md'])
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
diff --git a/apps/web/tests/subagent-conversation.e2e.ts b/apps/web/tests/subagent-conversation.e2e.ts
index 0049cb2791..324cde1227 100644
--- a/apps/web/tests/subagent-conversation.e2e.ts
+++ b/apps/web/tests/subagent-conversation.e2e.ts
@@ -365,22 +365,7 @@ describe('web e2e: persisted subagent conversation and human continuation', () =
       () => scaffold.ctx.agents.get(childId)?.status,
       { timeout: 10_000 },
     ).toBe('running')
-    const hierarchy = page.getByRole('navigation', { name: 'Session hierarchy' })
-    await hierarchy.getByRole('button').first().click()
-    const runningTrigger = page.getByRole('button', { name: '3 subagents running' })
-    await runningTrigger.waitFor({ timeout: 10_000 })
-    expect(await runningTrigger.locator('[data-state="ongoing"]').count()).toBe(1)
-    await runningTrigger.click()
-    await page.getByRole('treeitem', {
-      name: new RegExp(`${LABEL}.*running`),
-    }).waitFor({ timeout: 10_000 })
     await ended
-    await page.getByRole('treeitem', {
-      name: new RegExp(`${LABEL}.*not running`),
-    }).waitFor({ timeout: 10_000 })
-    expect(await page.getByRole('button', { name: '3 subagents' })
-      .locator('[data-state="ongoing"]').count()).toBe(0)
-    await page.getByRole('treeitem', { name: new RegExp(LABEL) }).click()
     await expect.poll(() => page.getByText(FOLLOWUP, { exact: true }).count(), { timeout: 10_000 }).toBe(1)
     await expect.poll(() => scaffold.ctx.agents.get(childId), { timeout: 10_000 }).toBeUndefined()
     expect(await page.getByRole('button', { name: 'Stop generating' }).count()).toBe(0)

From 8dcbabc3a45d78565aba5650162d8e0febd9be85 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 16:04:24 +0800
Subject: [PATCH 243/516] docs: refresh module graph

---
 docs/module-graph.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index 8abb5b3393..2d5300f312 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -320,8 +320,6 @@ flowchart TD
   pkg_llm --> pkg_brand
   pkg_llm --> pkg_invariants
   pkg_llm --> pkg_timeout
-  pkg_skill_badge --> pkg_invariants
-  pkg_skill_badge --> pkg_skill
   pkg_client_connection --> pkg_host_webserver
   pkg_client_connection --> pkg_invariants
   pkg_client_hmr --> pkg_client_modules
@@ -430,6 +428,8 @@ flowchart TD
   pkg_fs --> pkg_invariants
   pkg_fs --> pkg_llm
   pkg_fs --> pkg_sandbox
+  pkg_skill_badge --> pkg_invariants
+  pkg_skill_badge --> pkg_skill
   pkg_compact --> pkg_invariants
   pkg_compact --> pkg_llm
   pkg_compact --> pkg_session
@@ -1182,7 +1182,6 @@ flowchart TD
 | [`typert-generator`](../packages/typert/generator) | `typert` | [`invariants`](../packages/support/invariants) |
 | [`typert-registry`](../packages/typert/registry) | `typert` | [`invariants`](../packages/support/invariants) |
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout) |
-| [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/support/invariants), [`skill`](../packages/skill/skill) |
 | [`client-connection`](../packages/client/connection) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-runtime`](../packages/client/runtime) | `client` | [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
@@ -1215,6 +1214,7 @@ flowchart TD
 | [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`type-meta`](../packages/typert/type-meta) |
 | [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`subprocess`](../packages/subprocess/subprocess) |
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
+| [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/support/invariants), [`skill`](../packages/skill/skill) |
 | [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |

From 9614bce6c6f215a6a168fc130529fb26fdbc9901 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 16:08:03 +0800
Subject: [PATCH 244/516] docs(graph): refresh session persistence dependency

---
 docs/module-graph.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/module-graph.md b/docs/module-graph.md
index c268ad317f..b669c2a7b8 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -446,6 +446,7 @@ flowchart TD
   pkg_session_persistence --> pkg_brand
   pkg_session_persistence --> pkg_invariants
   pkg_session_persistence --> pkg_session
+  pkg_session_persistence --> pkg_timeout
   pkg_acp_snapshot --> pkg_invariants
   pkg_acp_snapshot --> pkg_session
   pkg_app_boot --> pkg_environment
@@ -1216,7 +1217,7 @@ flowchart TD
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |

From 1627728eff0acd837c7b5cf0a63043f3668779ee Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 16:15:00 +0800
Subject: [PATCH 245/516] fix: allow audited publishing repository links

---
 .../verify-public-repository-links.spec.ts    | 28 +++++++++++++++++++
 scripts/verify-public-repository-links.ts     | 21 ++++++++++----
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/scripts/verify-public-repository-links.spec.ts b/scripts/verify-public-repository-links.spec.ts
index ec12f38427..372018d7cf 100644
--- a/scripts/verify-public-repository-links.spec.ts
+++ b/scripts/verify-public-repository-links.spec.ts
@@ -29,4 +29,32 @@ describe('public repository link policy', () => {
       { file: 'subject.md', line: 8 },
     ])
   })
+
+  it('allows only the exact audited trusted-publishing repository declarations', () => {
+    const internalOwner = ['deepseek', 'harness'].join('-')
+    const internalRepository = [internalOwner, internalOwner].join('/')
+    const repositoryUrl = `git+https://github.com/${internalRepository}.git`
+    const manifestLine = `  "url": "${repositoryUrl}",`
+    const constraintLine = `const repositoryUrl = '${repositoryUrl}'`
+    const allowedDeclarations = [
+      ['native/landlock-run/packages/entry/package.json', manifestLine],
+      ['native/landlock-run/packages/linux-arm64/package.json', manifestLine],
+      ['native/landlock-run/packages/linux-x64/package.json', manifestLine],
+      ['scripts/check-workspace-constraints.ts', constraintLine],
+    ] as const
+
+    for (const [file, source] of allowedDeclarations) {
+      expect(findInternalRepositoryReferences(file, source)).toEqual([])
+    }
+
+    const wrongFile = 'native/landlock-run/package.json'
+    expect(findInternalRepositoryReferences(wrongFile, manifestLine)).toEqual([{ file: wrongFile, line: 1 }])
+
+    const manifestFile = 'native/landlock-run/packages/entry/package.json'
+    const wrongField = `  "homepage": "${repositoryUrl}",`
+    expect(findInternalRepositoryReferences(manifestFile, wrongField)).toEqual([{ file: manifestFile, line: 1 }])
+
+    const encodedLine = manifestLine.replace('github.com/', 'github.com\\/')
+    expect(findInternalRepositoryReferences(manifestFile, encodedLine)).toEqual([{ file: manifestFile, line: 1 }])
+  })
 })
diff --git a/scripts/verify-public-repository-links.ts b/scripts/verify-public-repository-links.ts
index 6d1e537733..e612e6641f 100644
--- a/scripts/verify-public-repository-links.ts
+++ b/scripts/verify-public-repository-links.ts
@@ -1,4 +1,4 @@
-/** Reject tracked files that expose the internal repository identity. */
+/** Reject tracked files that expose the internal repository identity outside audited publishing declarations. */
 
 import { execFileSync } from 'node:child_process'
 import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs'
@@ -9,6 +9,15 @@ const root = resolve(import.meta.dirname, '..')
 const internalOwner = ['deepseek', 'harness'].join('-')
 const internalRepository = [internalOwner, internalOwner].join('/')
 const internalIssueShorthand = `${internalOwner}#`
+const trustedPublishingRepositoryUrl = `git+https://github.com/${internalRepository}.git`
+
+/** Exact declarations that intentionally expose the source repository for trusted publishing. */
+const allowedInternalRepositoryLineByFile: Readonly<Record<string, string>> = {
+  'native/landlock-run/packages/entry/package.json': `"url": "${trustedPublishingRepositoryUrl}",`,
+  'native/landlock-run/packages/linux-arm64/package.json': `"url": "${trustedPublishingRepositoryUrl}",`,
+  'native/landlock-run/packages/linux-x64/package.json': `"url": "${trustedPublishingRepositoryUrl}",`,
+  'scripts/check-workspace-constraints.ts': `const repositoryUrl = '${trustedPublishingRepositoryUrl}'`,
+}
 
 const namedReferenceCharacters: Readonly<Record<string, string>> = {
   hyphen: '-',
@@ -40,7 +49,7 @@ export interface InternalRepositoryReference {
 }
 
 /**
- * Locate internal-repository references in one text file.
+ * Locate unaudited internal-repository references in one text file.
  * @param file - Repository-relative path used in diagnostics.
  * @param source - Text to inspect.
  * @returns every matching source line.
@@ -49,7 +58,9 @@ export function findInternalRepositoryReferences(file: string, source: string):
   const references: InternalRepositoryReference[] = []
   for (const [index, line] of source.split('\n').entries()) {
     const canonicalLine = canonicalReferenceText(line)
-    if (canonicalLine.includes(internalRepository) || canonicalLine.includes(internalIssueShorthand)) {
+    const isAllowedPublishingDeclaration = line.trim() === allowedInternalRepositoryLineByFile[file]
+    if (!isAllowedPublishingDeclaration
+      && (canonicalLine.includes(internalRepository) || canonicalLine.includes(internalIssueShorthand))) {
       references.push({ file, line: index + 1 })
     }
   }
@@ -81,9 +92,9 @@ const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(re
 if (isMain) {
   const references = scanRepository(root)
   if (references.length === 0) {
-    console.log('verify-public-repository-links: tracked files expose no internal repository identity.')
+    console.log('verify-public-repository-links: tracked files expose no unexpected internal repository identity.')
   } else {
-    console.error('verify-public-repository-links: internal repository references found:')
+    console.error('verify-public-repository-links: unexpected internal repository references found:')
     for (const reference of references) console.error(`  ${reference.file}:${String(reference.line)}`)
     process.exitCode = 1
   }

From 1576d049ed0ecddea72b3064644513f1c976b7e9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 16:43:37 +0800
Subject: [PATCH 246/516] fix(session-persistence): close batching failure gaps

---
 .../session-persistence/src/coordinator.ts    | 26 +++++++-----
 .../session-persistence/src/write-behind.ts   |  8 +++-
 .../tests/persistence.spec.ts                 | 42 +++++++++++++++++++
 .../tests/write-behind.spec.ts                | 23 ++++++++++
 4 files changed, 87 insertions(+), 12 deletions(-)

diff --git a/packages/session-persistence/session-persistence/src/coordinator.ts b/packages/session-persistence/session-persistence/src/coordinator.ts
index 0eabaaa8c0..cf013887d3 100644
--- a/packages/session-persistence/session-persistence/src/coordinator.ts
+++ b/packages/session-persistence/session-persistence/src/coordinator.ts
@@ -1084,14 +1084,12 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       return restored
     }
     const seed = session.events.map(e => structuredClone(e))
-    let init = Promise.resolve()
     const live: LiveSessionState = {
-      init,
-      writes: this.createWriteBehind(session, () => init),
+      init: Promise.resolve(),
+      writes: this.createWriteBehind(session, () => live.init),
     }
     this.live.set(session, live)
-    init = this.serialize(session.header.id, () => this.onCreated(session, seed))
-    live.init = init
+    live.init = this.serialize(session.header.id, () => this.onCreated(session, seed))
     live.init.catch(() => { /* observed by flush/dispose through the controller */ })
     return live
   }
@@ -1110,14 +1108,12 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     const suffix = session.events.slice(state.cursor).map(event => structuredClone(event))
     this.preparations.attach(reservation)
     state.owner = session
-    let init = Promise.resolve()
     const live: LiveSessionState = {
-      init,
-      writes: this.createWriteBehind(session, () => init),
+      init: Promise.resolve(),
+      writes: this.createWriteBehind(session, () => live.init),
     }
     if (suffix.length > 0) {
-      init = this.serialize(session.id, () => this.appendCore(session.id, suffix))
-      live.init = init
+      live.init = this.serialize(session.id, () => this.appendCore(session.id, suffix))
       live.init.catch(() => { /* observed by flush/dispose through the controller */ })
     }
     return live
@@ -1240,7 +1236,15 @@ export class PersistenceCoordinator<TornMarker = unknown> {
 
   private async flush(session: Session): Promise<void> {
     const live = this.initFor(session)
-    await live.init
+    live.writes.cancelAutomaticWait()
+    try {
+      await live.init
+    } catch (error: unknown) {
+      // Admission is closed during retirement/teardown, but an ordinary flush
+      // may have raced one last enqueue while initialization was pending.
+      live.writes.cancelAutomaticWait()
+      throw error
+    }
     await live.writes.flush()
   }
 
diff --git a/packages/session-persistence/session-persistence/src/write-behind.ts b/packages/session-persistence/session-persistence/src/write-behind.ts
index 60665455dc..97797732f6 100644
--- a/packages/session-persistence/session-persistence/src/write-behind.ts
+++ b/packages/session-persistence/session-persistence/src/write-behind.ts
@@ -71,6 +71,12 @@ export class SessionWriteBehind {
     return barrier.promise
   }
 
+  /** Cancel the current automatic deadline without draining retained work. */
+  cancelAutomaticWait(): void {
+    this.cancelTimer()
+    this.deadlineExpired = false
+  }
+
   /** Start the one fixed window for the current pending prefix. */
   private armTimer(): void {
     this.timer = setTimeout(() => { this.onDeadline() }, this.options.maxDelayMs)
@@ -137,7 +143,7 @@ export class SessionWriteBehind {
     const operation = Promise.resolve().then(() => this.options.write(batch))
     const active = operation
       .catch((error: unknown) => {
-        this.pending.unshift(...batch)
+        this.pending = batch.concat(this.pending)
         this.cancelTimer()
         this.deadlineExpired = false
         this.automaticPaused = true
diff --git a/packages/session-persistence/session-persistence/tests/persistence.spec.ts b/packages/session-persistence/session-persistence/tests/persistence.spec.ts
index 14b4f9b951..75455abe81 100644
--- a/packages/session-persistence/session-persistence/tests/persistence.spec.ts
+++ b/packages/session-persistence/session-persistence/tests/persistence.spec.ts
@@ -257,6 +257,48 @@ runCoordinatorContract('memory', async (): Promise<CoordinatorFixture> => {
 })
 
 describe('PersistenceCoordinator bounded writes', () => {
+  it('cancels the batching deadline when live initialization rejects', async () => {
+    vi.useFakeTimers()
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const failure = new Error('initialization failed')
+    backend.beforeLoadStored = () => Promise.reject(failure)
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      new PersistenceCoordinator(inner, backend, {
+        preparedSessionCacheSize: DEFAULT_PREPARED_SESSION_CACHE_SIZE,
+        writeBatchMaxDelayMs: MAX_WRITE_BATCH_DELAY_MS,
+      })
+    }, { inject: ['sessions'] }))
+
+    try {
+      const session = ctx.sessions.create(SessionId('bounded-init-failure'))
+      session.append('turn/start', { turn: 1 })
+
+      await expect(ctx.sessions.flush(session)).rejects.toBe(failure)
+      expect(vi.getTimerCount()).toBe(0)
+      try {
+        await fiber.dispose()
+      } catch {
+        // The initialization failure was already asserted at the flush boundary.
+      }
+      expect(vi.getTimerCount()).toBe(0)
+    } finally {
+      try {
+        await fiber.dispose()
+      } catch {
+        // The expected initialization failure was asserted above; cleanup only
+        // needs to release any remaining parent effects.
+      }
+      try {
+        await ctx.fiber.dispose()
+      } catch {
+        // The child failure was already asserted through the backend fiber.
+      }
+      vi.useRealTimers()
+    }
+  })
+
   it('starts a follow-up batch for events admitted during an in-flight write', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
diff --git a/packages/session-persistence/session-persistence/tests/write-behind.spec.ts b/packages/session-persistence/session-persistence/tests/write-behind.spec.ts
index b93b3824ae..df445e0cf7 100644
--- a/packages/session-persistence/session-persistence/tests/write-behind.spec.ts
+++ b/packages/session-persistence/session-persistence/tests/write-behind.spec.ts
@@ -249,4 +249,27 @@ describe('SessionWriteBehind', () => {
     expect(batches).toEqual([[0], [0, 1]])
     await controller.flush()
   })
+
+  it('retains a failed batch larger than the engine call-argument limit', async () => {
+    const failure = new Error('durability failed')
+    const batchSize = 150_000
+    const sizes: number[] = []
+    let attempt = 0
+    const controller = new SessionWriteBehind({
+      maxDelayMs: 200,
+      write: async (events) => {
+        sizes.push(events.length)
+        if (++attempt === 1) throw failure
+      },
+      reportBackgroundFailure: vi.fn(),
+    })
+
+    for (let seq = 0; seq < batchSize; seq += 1) controller.enqueue(event(seq))
+    await expect(controller.flush()).rejects.toBe(failure)
+    expect(controller.hasWork).toBe(true)
+
+    await controller.flush()
+    expect(sizes).toEqual([batchSize, batchSize])
+    expect(controller.hasWork).toBe(false)
+  })
 })

From 1674af147e5fe6990ec0f7b37a21716fd07ba174 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:18:04 +0800
Subject: [PATCH 247/516] cleanup(client): detach conversation rows from Tool
 presentation

---
 .../src/client/chat/AssistantMarkdown.tsx     |  34 +-----
 .../src/client/chat/DisclosureRow.module.css  |   2 +-
 .../src/client/chat/DisclosureRow.tsx         |   4 +-
 .../client/chat/GenericCommandCard.module.css |  86 +++++++++++++
 .../src/client/chat/GenericCommandCard.tsx    |  52 +++++---
 .../src/client/chat/ReasoningRow.module.css   |  81 ++++++++++++
 .../src/client/chat/ReasoningRow.tsx          |  62 ++++++++++
 .../chat/use-throttled-visual-update.ts       |   4 +-
 .../tests/reasoning-row.spec.tsx              | 115 ++++++++++++++++++
 9 files changed, 389 insertions(+), 51 deletions(-)
 create mode 100644 packages/client/ui-conversation/src/client/chat/GenericCommandCard.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/ReasoningRow.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
 create mode 100644 packages/client/ui-conversation/tests/reasoning-row.spec.tsx

diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index bc1c6c7e32..9d0c26506e 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -12,13 +12,11 @@
 import { memo, useMemo } from 'react'
 import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
-import {
-  IconThinkOutline14, JsonBlock, MarkdownText,
-} from '@deepseek-ai/dsh-client-ui-primitives'
+import { JsonBlock, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps, TurnTailOwnerProps } from '../contract/slots.ts'
 import { hasContentText } from './chat-flow.ts'
 import { MessageIconActions } from './MessageIconActions.tsx'
-import { ToolRow } from './ToolRow.tsx'
+import { ReasoningRow } from './ReasoningRow.tsx'
 import css from './AssistantMarkdown.module.css'
 
 export interface AssistantMarkdownProps {
@@ -49,18 +47,6 @@ export interface AssistantMarkdownProps {
   t: ChatViewSlotProps['t']
 }
 
-function firstLine(text: string): string {
-  const nl = text.indexOf('\n')
-  return nl === -1 ? text : text.slice(0, nl)
-}
-
-/** Latest non-blank reasoning line while the block is still streaming. */
-function latestLine(text: string): string {
-  const visible = text.trimEnd()
-  const nl = visible.lastIndexOf('\n')
-  return nl === -1 ? visible : visible.slice(nl + 1)
-}
-
 /** Joined text blocks for the copy action (reasoning / tool heads stay out). */
 function copyText(blocks: readonly AssistantBlock[]): string {
   const parts: string[] = []
@@ -71,20 +57,6 @@ function copyText(blocks: readonly AssistantBlock[]): string {
 }
 
 /** Reasoning block as the Think variant summary row (figma 39:28304). */
-function ThinkRow({ text, running, t }: { text: string; running: boolean; t: AssistantMarkdownProps['t'] }) {
-  return (
-    <ToolRow
-      t={t}
-      variant="think"
-      icon={<IconThinkOutline14 size={14} />}
-      title="Think"
-      summary={running ? latestLine(text) : firstLine(text)}
-      body={text}
-      state={running ? 'running' : 'ok'}
-    />
-  )
-}
-
 export const AssistantMarkdown = memo(function AssistantMarkdown({
   blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, turnTail, t,
 }: AssistantMarkdownProps) {
@@ -109,7 +81,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
             case 'text': return (
               <MarkdownText key={i} text={block.text} streaming={streaming} codeLabels={codeLabels} />
             )
-            case 'reasoning': return <ThinkRow key={i} text={block.text} running={streaming && i === last} t={t} />
+            case 'reasoning': return <ReasoningRow key={i} text={block.text} running={streaming && i === last} />
             // Grouped into tool rows by ChatView; hasVisible above skips an empty shell.
             case 'tool-call': return null
             default: return (
diff --git a/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css b/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css
index 04f2d18d0a..51937ab462 100644
--- a/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css
+++ b/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css
@@ -1,4 +1,4 @@
-/* Shared Tool calls disclosure header: [16px leading] gap 6 [title 14/24]. */
+/* Shared conversation disclosure header: [16px leading] gap 6 [title 14/24]. */
 
 .root {
   display: flex;
diff --git a/packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx b/packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx
index 361fb24517..a95114ff2f 100644
--- a/packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx
@@ -14,7 +14,7 @@ export interface DisclosureRowProps {
   expandOnRowClick?: boolean | undefined
   /** Replaces the collapsed icon with a chevron while the row is hovered. */
   previewChevron?: boolean | undefined
-  /** Keeps `collapsedContent` inline while open (ToolRow's summary stays readable next to the expanded card). */
+  /** Keeps `collapsedContent` inline while open. */
   keepContentWhenOpen?: boolean | undefined
   collapsedContent?: ReactNode
   children?: ReactNode
@@ -28,7 +28,7 @@ export interface DisclosureRowProps {
 /**
  * Render one disclosure header and its controlled expanded content.
  * @param props - Visual content, controlled state, and interaction policy.
- * @returns The disclosure row.
+ * @returns the disclosure row.
  */
 export function DisclosureRow({
   icon,
diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.module.css b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.module.css
new file mode 100644
index 0000000000..d090c890b2
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.module.css
@@ -0,0 +1,86 @@
+.root {
+  display: flex;
+  flex-direction: column;
+}
+
+.row {
+  position: relative;
+  overflow: hidden;
+}
+
+.root[data-state='running'] .row::after {
+  content: '';
+  position: absolute;
+  inset-block: 0;
+  left: 0;
+  width: 300px;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    color-mix(in srgb, var(--dsw-alias-bg-base) 60%, transparent) 55%,
+    transparent 100%
+  );
+  animation: dsh-command-row-sweep 2.6s ease-out infinite;
+  pointer-events: none;
+}
+
+@keyframes dsh-command-row-sweep {
+  0% { left: -300px; }
+  90%, 100% { left: 100%; }
+}
+
+.leading {
+  flex-shrink: 0;
+}
+
+.chevron {
+  color: var(--dsw-alias-label-secondary);
+}
+
+.title {
+  font-weight: 400;
+}
+
+.separator {
+  flex: none;
+  width: 2px;
+  height: 2px;
+  margin: 0 8px;
+  border-radius: 1px;
+  background: var(--dsw-alias-label-caption);
+}
+
+.summary {
+  min-width: 0;
+  overflow: hidden;
+  flex: 1 1 auto;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 14px;
+  line-height: 24px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.summary[data-error],
+.body[data-error] {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.body {
+  max-height: 260px;
+  margin: 4px 0 4px 4px;
+  padding: 12px 16px;
+  overflow: auto;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 12px;
+  background: var(--dsw-alias-markdown-code-block);
+  color: var(--dsw-alias-label-primary);
+  font: var(--dsw-font-markdown-code-block-small);
+  white-space: pre-wrap;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .root[data-state='running'] .row::after {
+    animation: none;
+  }
+}
diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index aa236c87ca..7bf7d74d2f 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -4,23 +4,31 @@
 // fallback (an unregistered command name lands here); registrants may compose
 // it as a base, feeding the same owner payload through.
 
-import { ToolRow } from './ToolRow.tsx'
-import type { ToolRowState } from '../contract/tool-call-model.ts'
+import { useState, type ReactNode } from 'react'
 import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
-import { IconApiOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconApiOutline14, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
+import { DisclosureRow } from './DisclosureRow.tsx'
+import css from './GenericCommandCard.module.css'
+
+type CommandRowState = 'running' | 'ok' | 'error'
 
 /** Node state → row state semantic (running while unsettled; outcome kind after). */
-function stateOf(outcome: CommandRowOwnerProps['node']['outcome']): ToolRowState {
+function stateOf(outcome: CommandRowOwnerProps['node']['outcome']): CommandRowState {
   if (outcome === null) return 'running'
   return outcome.kind === 'error' ? 'error' : 'ok'
 }
 
+function leadingFor(state: CommandRowState): ReactNode {
+  return state === 'error' ? <StateDot state="error" /> : <IconApiOutline14 size={14} />
+}
+
 /** Card props: the owner payload plus the render site's locale seat (plain prop). */
 export interface GenericCommandCardProps extends CommandRowOwnerProps {
   t: ChatViewSlotProps['t']
 }
 
 export function GenericCommandCard({ node, t }: GenericCommandCardProps) {
+  const [expanded, setExpanded] = useState(false)
   const text = node.outcome?.text
   const summary = node.outcome === null
     ? t('command.running')
@@ -30,16 +38,32 @@ export function GenericCommandCard({ node, t }: GenericCommandCardProps) {
   // settlement text says (`permission · preset workspace-write`). A
   // cross-window node whose run page fell out of the window has no name.
   const title = node.name ?? t('command.title')
+  const state = stateOf(node.outcome)
+  const body = text !== undefined && text.includes('\n') ? text : null
+  const open = expanded && body !== null
   return (
-    <ToolRow
-      t={t}
-      variant="others"
-      icon={<IconApiOutline14 size={14} />}
-      title={title}
-      summary={summary}
-      // Expandable only when the outcome text overflows a one-line summary.
-      body={text !== undefined && text.includes('\n') ? text : null}
-      state={stateOf(node.outcome)}
-    />
+    <div className={css.root} data-state={state}>
+      <DisclosureRow
+        rowClassName={css.row}
+        leadingClassName={css.leading}
+        titleClassName={css.title}
+        chevronClassName={css.chevron}
+        icon={leadingFor(state)}
+        title={title}
+        open={open}
+        expandable={body !== null}
+        expandOnRowClick
+        keepContentWhenOpen
+        onToggle={() => { setExpanded(value => !value) }}
+        collapsedContent={(
+          <>
+            <span className={css.separator} aria-hidden />
+            <span className={css.summary} data-error={state === 'error' || undefined}>{summary}</span>
+          </>
+        )}
+      >
+        <pre className={css.body} data-error={state === 'error' || undefined}>{body}</pre>
+      </DisclosureRow>
+    </div>
   )
 }
diff --git a/packages/client/ui-conversation/src/client/chat/ReasoningRow.module.css b/packages/client/ui-conversation/src/client/chat/ReasoningRow.module.css
new file mode 100644
index 0000000000..6b2f6c0cd3
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/ReasoningRow.module.css
@@ -0,0 +1,81 @@
+.root {
+  display: flex;
+  flex-direction: column;
+}
+
+.row {
+  position: relative;
+  overflow: hidden;
+}
+
+.root[data-state='running'] .row::after {
+  content: '';
+  position: absolute;
+  inset-block: 0;
+  left: 0;
+  width: 300px;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    color-mix(in srgb, var(--dsw-alias-bg-base) 60%, transparent) 55%,
+    transparent 100%
+  );
+  animation: dsh-reasoning-row-sweep 2.6s ease-out infinite;
+  pointer-events: none;
+}
+
+@keyframes dsh-reasoning-row-sweep {
+  0% { left: -300px; }
+  90%, 100% { left: 100%; }
+}
+
+.leading {
+  flex-shrink: 0;
+}
+
+.chevron {
+  color: var(--dsw-alias-label-secondary);
+}
+
+.title {
+  font-weight: 400;
+}
+
+.separator {
+  flex: none;
+  width: 2px;
+  height: 2px;
+  margin: 0 8px;
+  border-radius: 1px;
+  background: var(--dsw-alias-label-caption);
+}
+
+.summary {
+  min-width: 0;
+  overflow: hidden;
+  flex: 1 1 auto;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 14px;
+  line-height: 24px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.summary[data-follow-end] {
+  text-overflow: clip;
+}
+
+.thinkBody {
+  padding: 4px 0 4px 22px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 14px;
+  line-height: 24px;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .root[data-state='running'] .row::after {
+    animation: none;
+  }
+}
diff --git a/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx b/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
new file mode 100644
index 0000000000..d02bd855b4
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
@@ -0,0 +1,62 @@
+/** Assistant reasoning disclosure, independent of Tool-call presentation. */
+import { useEffect, useRef, useState } from 'react'
+import { IconThinkOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { DisclosureRow } from './DisclosureRow.tsx'
+import { useThrottledVisualUpdate } from './use-throttled-visual-update.ts'
+import css from './ReasoningRow.module.css'
+
+function firstLine(text: string): string {
+  const newline = text.indexOf('\n')
+  return newline === -1 ? text : text.slice(0, newline)
+}
+
+function latestLine(text: string): string {
+  const visible = text.trimEnd()
+  const newline = visible.lastIndexOf('\n')
+  return newline === -1 ? visible : visible.slice(newline + 1)
+}
+
+/**
+ * Render one assistant reasoning block as the Think disclosure row.
+ * @param props.text - complete or streaming reasoning text.
+ * @param props.running - whether this block is the streaming tail.
+ * @returns the reasoning disclosure.
+ */
+export function ReasoningRow({ text, running }: { text: string; running: boolean }) {
+  const [expanded, setExpanded] = useState(false)
+  const summaryRef = useRef<HTMLSpanElement>(null)
+  const summary = running ? latestLine(text) : firstLine(text)
+  const scheduleSummaryScroll = useThrottledVisualUpdate(() => {
+    const element = summaryRef.current
+    if (element === null) return
+    element.scrollLeft = running ? element.scrollWidth - element.clientWidth : 0
+  })
+  useEffect(() => {
+    scheduleSummaryScroll()
+  }, [running, scheduleSummaryScroll, summary])
+
+  return (
+    <div className={css.root} data-state={running ? 'running' : 'ok'}>
+      <DisclosureRow
+        rowClassName={css.row}
+        leadingClassName={css.leading}
+        titleClassName={css.title}
+        chevronClassName={css.chevron}
+        icon={<IconThinkOutline14 size={14} />}
+        title="Think"
+        open={expanded}
+        expandable
+        expandOnRowClick
+        onToggle={() => { setExpanded(value => !value) }}
+        collapsedContent={(
+          <>
+            <span className={css.separator} aria-hidden />
+            <span ref={summaryRef} className={css.summary} data-follow-end={running || undefined}>{summary}</span>
+          </>
+        )}
+      >
+        <div className={css.thinkBody}>{text}</div>
+      </DisclosureRow>
+    </div>
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/chat/use-throttled-visual-update.ts b/packages/client/ui-conversation/src/client/chat/use-throttled-visual-update.ts
index e282b4b087..8fec1832d1 100644
--- a/packages/client/ui-conversation/src/client/chat/use-throttled-visual-update.ts
+++ b/packages/client/ui-conversation/src/client/chat/use-throttled-visual-update.ts
@@ -1,14 +1,12 @@
 /** Frame-throttled scheduling for non-essential visual alignment. */
-
 import { useCallback, useLayoutEffect, useRef } from 'react'
 
 const DEFAULT_INTERVAL_FRAMES = 3
 
 /**
  * Return a stable scheduler that coalesces visual updates over a frame interval.
- * Repeated calls retain the latest callback, and unmount cancels pending work.
  * @param update - DOM alignment to run after the throttle interval.
- * @param intervalFrames - Frames to wait before applying the latest alignment.
+ * @param intervalFrames - frames to wait before applying the latest alignment.
  * @returns a stable function that schedules the latest update.
  */
 export function useThrottledVisualUpdate(
diff --git a/packages/client/ui-conversation/tests/reasoning-row.spec.tsx b/packages/client/ui-conversation/tests/reasoning-row.spec.tsx
new file mode 100644
index 0000000000..243b665ce2
--- /dev/null
+++ b/packages/client/ui-conversation/tests/reasoning-row.spec.tsx
@@ -0,0 +1,115 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
+import { zh } from '../src/client/locales.ts'
+
+let nextAnimationFrameId = 1
+let animationFrames = new Map<number, FrameRequestCallback>()
+
+function flushAnimationFrames(count: number): void {
+  for (let index = 0; index < count; index += 1) {
+    const callbacks = [...animationFrames.values()]
+    animationFrames.clear()
+    for (const callback of callbacks) callback(index)
+  }
+}
+
+beforeEach(() => {
+  nextAnimationFrameId = 1
+  animationFrames = new Map()
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+    const id = nextAnimationFrameId
+    nextAnimationFrameId += 1
+    animationFrames.set(id, callback)
+    return id
+  })
+  vi.stubGlobal('cancelAnimationFrame', (id: number) => {
+    animationFrames.delete(id)
+  })
+})
+
+afterEach(() => {
+  cleanup()
+  vi.unstubAllGlobals()
+})
+
+const t = makeTranslate(zh, commonZh)
+
+describe('ReasoningRow', () => {
+  it('follows the latest streaming line, scrolls to its end, then restores the settled first line', () => {
+    const view = render(
+      <AssistantMarkdown
+        t={t}
+        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nNewest reasoning tokens' }]}
+        streaming
+      />,
+    )
+    const summary = view.getByText('Newest reasoning tokens')
+    Object.defineProperties(summary, {
+      scrollWidth: { configurable: true, value: 300 },
+      clientWidth: { configurable: true, value: 100 },
+    })
+
+    view.rerender(
+      <AssistantMarkdown
+        t={t}
+        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nNewest reasoning tokens keep arriving' }]}
+        streaming
+      />,
+    )
+    expect(summary.scrollLeft).toBe(0)
+    flushAnimationFrames(2)
+    expect(summary.scrollLeft).toBe(0)
+    flushAnimationFrames(1)
+    expect(summary.scrollLeft).toBe(200)
+    expect(summary.getAttribute('data-follow-end')).toBe('true')
+
+    view.rerender(
+      <AssistantMarkdown
+        t={t}
+        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nNewest reasoning tokens keep arriving\n' }]}
+        streaming={false}
+      />,
+    )
+    flushAnimationFrames(3)
+    expect(view.getByText('Inspect the session')).toBeTruthy()
+    expect(summary.scrollLeft).toBe(0)
+    expect(summary.hasAttribute('data-follow-end')).toBe(false)
+  })
+
+  it('expands from either Think or the reasoning summary', () => {
+    const view = render(
+      <AssistantMarkdown
+        t={t}
+        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nCheck persistence' }]}
+        streaming={false}
+      />,
+    )
+    const row = view.getByRole('button')
+
+    fireEvent.click(view.getByText('Inspect the session'))
+    expect(row.getAttribute('aria-expanded')).toBe('true')
+    expect(view.getByText(/Check persistence/)).toBeTruthy()
+
+    fireEvent.click(view.getByText('Think'))
+    expect(row.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('expanded Think drops the inline summary and renders plain prose, no IN card', () => {
+    const view = render(
+      <AssistantMarkdown
+        t={t}
+        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nCheck persistence' }]}
+        streaming={false}
+      />,
+    )
+    fireEvent.click(view.getByText('Think'))
+    expect(view.getAllByText(/Inspect the session/)).toHaveLength(1)
+    expect(view.queryByText('IN')).toBeNull()
+    expect(view.container.querySelector('[class*="ioCard"]')).toBeNull()
+    expect(view.container.querySelector('[class*="thinkBody"]')).not.toBeNull()
+  })
+})

From 7cc554ef16b4a77aeff4d728d878160d674fb033 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:18:52 +0800
Subject: [PATCH 248/516] cleanup(client): extract Tool presentation into
 ui-tool

---
 packages/bundle/web-app/cordis.patch.yml      |   4 +
 packages/bundle/web-app/package.json          |   1 +
 packages/client/AGENTS.md                     |   2 +-
 packages/client/README.i18n.yaml              |   4 +-
 packages/client/README.md                     |   1 +
 packages/client/README.zh.md                  |   1 +
 .../client/connection/src/client/fixture.ts   |  22 +--
 packages/client/runtime/src/client/index.ts   |   2 +-
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |  22 +--
 packages/client/ui-conversation/README.zh.md  |  22 +--
 packages/client/ui-conversation/package.json  |   2 +-
 .../ui-conversation/src/client/apply.ts       |  50 +-----
 .../src/client/chat/ChatView.module.css       |  11 --
 .../src/client/chat/ChatView.tsx              | 135 +++------------
 .../src/client/contract/slots.ts              |  62 ++++---
 .../src/client/contract/tool-path.ts          |  15 ++
 .../ui-conversation/src/client/index.ts       |   7 +-
 .../client/skeleton/DetailsPanel.module.css   |  33 ----
 .../src/client/skeleton/DetailsPanel.tsx      | 113 +++----------
 .../client/ui-conversation/src/invariant.ts   |   2 +-
 .../tests/assembly-surfaces.spec.tsx          | 134 +--------------
 .../ui-conversation/tests/chat-apply.spec.tsx |  24 ++-
 ...sh-sample.spec.tsx => chat-stats.spec.tsx} |  53 +-----
 .../ui-conversation/tests/chat-view.spec.tsx  | 122 +++++++-------
 .../tests/coverage-tails.spec.tsx             |  90 +---------
 .../tests/gate-branch-tails.spec.tsx          |  32 +++-
 .../ui-conversation/tests/todo-panel.spec.tsx | 157 +----------------
 .../tests/views-type-chain.spec.tsx           |  37 +---
 packages/client/ui-skill/README.i18n.yaml     |   4 +-
 packages/client/ui-skill/README.md            |   2 +-
 packages/client/ui-skill/README.zh.md         |   2 +-
 packages/client/ui-skill/package.json         |   6 +-
 .../client/ui-skill/src/client/SkillRow.tsx   |  12 +-
 packages/client/ui-skill/src/client/index.ts  |   4 +-
 .../ui-skill/tests/browser-plugin.spec.ts     |   6 +-
 packages/client/ui-skill/tsconfig.json        |   2 +-
 packages/client/ui-tool/README.i18n.yaml      |   6 +
 packages/client/ui-tool/README.md             |  44 +++++
 packages/client/ui-tool/README.zh.md          |  44 +++++
 packages/client/ui-tool/package.json          |  73 ++++++++
 packages/client/ui-tool/src/client/apply.ts   |  43 +++++
 .../ui-tool/src/client/contract/slots.ts      |  39 +++++
 packages/client/ui-tool/src/client/index.ts   |   3 +
 packages/client/ui-tool/src/client/locale.ts  |   2 +
 .../src/client/tool/ToolCallTree.module.css   |  12 ++
 .../ui-tool/src/client/tool/ToolCallTree.tsx  |  88 ++++++++++
 .../src/client/tool/ToolDetails.module.css    |  46 +++++
 .../ui-tool/src/client/tool/ToolDetails.tsx   |  66 ++++++++
 .../tool/components/DisclosureRow.module.css  |  69 ++++++++
 .../client/tool/components/DisclosureRow.tsx  | 104 ++++++++++++
 .../tool/components}/ToolRow.module.css       |  18 --
 .../src/client/tool/components}/ToolRow.tsx   | 106 +++++-------
 .../client/tool/models}/diff-card-model.ts    |   0
 .../client/tool/models}/read-card-model.ts    |   0
 .../client/tool/models}/search-card-model.ts  |   0
 .../tool/models}/terminal-card-model.ts       |   0
 .../client/tool/models}/tool-call-model.ts    |  10 +-
 .../src/client/tool/models}/web-card-model.ts |   0
 .../tool/toolviews}/GenericToolCard.tsx       |  28 ++--
 .../tool}/toolviews/ask-question-row.tsx      |  18 +-
 .../tool}/toolviews/bash-sample.module.css    |   0
 .../client/tool}/toolviews/bash-sample.tsx    |  16 +-
 .../tool}/toolviews/file-mutation-row.tsx     |  20 +--
 .../client/tool}/toolviews/plan-summary.ts    |   0
 .../src/client/tool}/toolviews/read-row.tsx   |  20 +--
 .../src/client/tool}/toolviews/search-row.tsx |  22 +--
 .../src/client/tool}/toolviews/todo-row.tsx   |  20 +--
 .../src/client/tool}/toolviews/web-row.tsx    |  20 +--
 packages/client/ui-tool/src/css-modules.d.ts  |   4 +
 packages/client/ui-tool/src/index.ts          |   4 +
 packages/client/ui-tool/src/invariant.ts      |  30 ++++
 .../tests/ask-question-row.spec.tsx           |   8 +-
 .../ui-tool/tests/assembly-surfaces.spec.tsx  | 149 +++++++++++++++++
 .../tests/chat-code-subcalls.spec.tsx         |  11 +-
 .../ui-tool/tests/coverage-tails.spec.tsx     | 116 +++++++++++++
 .../tests/diff-card.spec.tsx                  |  15 +-
 .../tests/read-card.spec.tsx                  |  17 +-
 .../tests/search-card.spec.tsx                |  15 +-
 .../tests/terminal-card.spec.tsx              |  17 +-
 .../client/ui-tool/tests/todo-row.spec.tsx    | 158 ++++++++++++++++++
 .../ui-tool/tests/tool-call-tree.spec.tsx     |  63 +++++++
 .../ui-tool/tests/tool-details-render.tsx     |  22 +++
 .../tests/tool-row-styles.spec.ts             |   2 +-
 .../tests/tool-row.spec.tsx}                  | 114 +------------
 .../tests/toolview-slot.spec.tsx}             |  37 ++--
 .../tests/toolview-type-chain.spec.tsx        |  34 ++++
 .../tests/web-card.spec.tsx                   |  20 ++-
 packages/client/ui-tool/tsconfig.json         |  33 ++++
 packages/client/ui-tool/tsdown.config.ts      |   3 +
 pnpm-lock.yaml                                |  58 ++++++-
 tsconfig.base.json                            |   1 +
 tsconfig.client.json                          |   1 +
 vitest.config.ts                              |   1 +
 94 files changed, 1797 insertions(+), 1275 deletions(-)
 create mode 100644 packages/client/ui-conversation/src/client/contract/tool-path.ts
 rename packages/client/ui-conversation/tests/{chat-stats-bash-sample.spec.tsx => chat-stats.spec.tsx} (87%)
 create mode 100644 packages/client/ui-tool/README.i18n.yaml
 create mode 100644 packages/client/ui-tool/README.md
 create mode 100644 packages/client/ui-tool/README.zh.md
 create mode 100644 packages/client/ui-tool/package.json
 create mode 100644 packages/client/ui-tool/src/client/apply.ts
 create mode 100644 packages/client/ui-tool/src/client/contract/slots.ts
 create mode 100644 packages/client/ui-tool/src/client/index.ts
 create mode 100644 packages/client/ui-tool/src/client/locale.ts
 create mode 100644 packages/client/ui-tool/src/client/tool/ToolCallTree.module.css
 create mode 100644 packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
 create mode 100644 packages/client/ui-tool/src/client/tool/ToolDetails.module.css
 create mode 100644 packages/client/ui-tool/src/client/tool/ToolDetails.tsx
 create mode 100644 packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css
 create mode 100644 packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx
 rename packages/client/{ui-conversation/src/client/chat => ui-tool/src/client/tool/components}/ToolRow.module.css (94%)
 rename packages/client/{ui-conversation/src/client/chat => ui-tool/src/client/tool/components}/ToolRow.tsx (76%)
 rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/diff-card-model.ts (100%)
 rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/read-card-model.ts (100%)
 rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/search-card-model.ts (100%)
 rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/terminal-card-model.ts (100%)
 rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/tool-call-model.ts (95%)
 rename packages/client/{ui-conversation/src/client/contract => ui-tool/src/client/tool/models}/web-card-model.ts (100%)
 rename packages/client/{ui-conversation/src/client/chat => ui-tool/src/client/tool/toolviews}/GenericToolCard.tsx (76%)
 rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/ask-question-row.tsx (85%)
 rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/bash-sample.module.css (100%)
 rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/bash-sample.tsx (93%)
 rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/file-mutation-row.tsx (77%)
 rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/plan-summary.ts (100%)
 rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/read-row.tsx (75%)
 rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/search-row.tsx (80%)
 rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/todo-row.tsx (83%)
 rename packages/client/{ui-conversation/src/client => ui-tool/src/client/tool}/toolviews/web-row.tsx (77%)
 create mode 100644 packages/client/ui-tool/src/css-modules.d.ts
 create mode 100644 packages/client/ui-tool/src/index.ts
 create mode 100644 packages/client/ui-tool/src/invariant.ts
 rename packages/client/{ui-conversation => ui-tool}/tests/ask-question-row.spec.tsx (95%)
 create mode 100644 packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
 rename packages/client/{ui-conversation => ui-tool}/tests/chat-code-subcalls.spec.tsx (96%)
 create mode 100644 packages/client/ui-tool/tests/coverage-tails.spec.tsx
 rename packages/client/{ui-conversation => ui-tool}/tests/diff-card.spec.tsx (97%)
 rename packages/client/{ui-conversation => ui-tool}/tests/read-card.spec.tsx (95%)
 rename packages/client/{ui-conversation => ui-tool}/tests/search-card.spec.tsx (97%)
 rename packages/client/{ui-conversation => ui-tool}/tests/terminal-card.spec.tsx (98%)
 create mode 100644 packages/client/ui-tool/tests/todo-row.spec.tsx
 create mode 100644 packages/client/ui-tool/tests/tool-call-tree.spec.tsx
 create mode 100644 packages/client/ui-tool/tests/tool-details-render.tsx
 rename packages/client/{ui-conversation => ui-tool}/tests/tool-row-styles.spec.ts (94%)
 rename packages/client/{ui-conversation/tests/chat-tool-row.spec.tsx => ui-tool/tests/tool-row.spec.tsx} (83%)
 rename packages/client/{ui-conversation/tests/chat-toolview-slot.spec.tsx => ui-tool/tests/toolview-slot.spec.tsx} (84%)
 create mode 100644 packages/client/ui-tool/tests/toolview-type-chain.spec.tsx
 rename packages/client/{ui-conversation => ui-tool}/tests/web-card.spec.tsx (94%)
 create mode 100644 packages/client/ui-tool/tsconfig.json
 create mode 100644 packages/client/ui-tool/tsdown.config.ts

diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 739f045ce6..62ed35bd49 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -149,6 +149,10 @@
     - id: ui-conversation
       name: '@deepseek-ai/dsh-client-ui-conversation'
 
+    # Tool call tree, generic fallback, and keyed business Tool views.
+    - id: ui-tool
+      name: '@deepseek-ai/dsh-client-ui-tool'
+
     # Turn tail: the produced-files row under each closing assistant message.
     # Remove this entry to turn the surface off; the tail hole renders empty.
     - id: ui-deliverables
diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json
index 4e2d9cf70b..9b8e15fd66 100644
--- a/packages/bundle/web-app/package.json
+++ b/packages/bundle/web-app/package.json
@@ -55,6 +55,7 @@
     "@deepseek-ai/dsh-client-ui-slash": "workspace:^",
     "@deepseek-ai/dsh-client-ui-subagent": "workspace:^",
     "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-tool": "workspace:^",
     "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
     "@deepseek-ai/dsh-client-ui-workspace": "workspace:^",
     "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index df7374d7c7..d534e5bb83 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -9,7 +9,7 @@ Packages here are named with the directory prefix: `@deepseek-ai/dsh-client-<nam
 The [slot system standard](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md) owns the full design; these are the rules you must not violate when writing or reviewing client code:
 
 1. **One API**: a plugin composes UI only through `ctx.slots.register({ name, children?, store?, inject? }, Component)`. There is no separate slot-definition call, no whitelist face object, no face-minting helper. The shell alone renders `'root'`.
-2. **children = declaration + authorization**: the slots your component renders are exactly the keys of your register call's `children` object (spec values: `kind`/`scope`). Rendering a slot you didn't declare, or declaring one someone else declared, fails at load — do not work around it; the conflict is the design speaking. Slot names mirror the composition path: `<domain>.<entry>.<hole>` (e.g. `'conversation.chat.toolview'`).
+2. **children = declaration + authorization**: the slots your component renders are exactly the keys of your register call's `children` object (spec values: `kind`/`scope`). Rendering a slot you didn't declare, or declaring one someone else declared, fails at load — do not work around it; the conflict is the design speaking. Slot names mirror the composition path: `<domain>.<entry>.<hole>` (e.g. `'tool.call.toolview'`).
 3. **Component props are the four shares, all derived**: `PropsRuntime<K>` (SlotMap: owner params + `useSession`/`sessionId` on session scope + global `useSessions`/`useWorkspaces`) & `PropsRenderSlots<S>` (children keys) & `PropsStore<H>` (store factory) & the inject face. Never hand-write a member a share already derives; never re-type a share locally.
 4. **Hooks are framework-made only**: `useSession`, `useSessions`, `useWorkspaces`, `useStore`, `renderSlot` are the five standing seats, plus the `use<Name>` hooks the renderer binds from provide contributions and inject `hooks` compartments. Business code never creates a hook or selector as a prop value — pass plain data and callbacks. (Component-internal behavioral hooks that subscribe to nothing external are fine.)
 5. **Live data has exactly three channels**: parent knows it → owner props at the renderSlot site; only the component knows it → local state; shared across entries or survives remounts → a store declared at register. Derived data is a pure function over framework-hook data (`useMemo`), never its own subscription.
diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml
index 503a747087..e65d5246a4 100644
--- a/packages/client/README.i18n.yaml
+++ b/packages/client/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/client/README.md
-README.md: b950772d4cad6d873426f8aee6416fa56afca2ee
-README.zh.md: 8f1f7f46777b7037e8baa04c9ec16ef74ffd478d
+README.md: b6fa426fbe541e2b22d2bf5f19d4397361cf0899
+README.zh.md: 5a55bb8c2c31b5215fc73e75e1c4f3aca79add64
diff --git a/packages/client/README.md b/packages/client/README.md
index b950772d4c..b6fa426fbe 100644
--- a/packages/client/README.md
+++ b/packages/client/README.md
@@ -22,6 +22,7 @@ The browser side of the dsh web GUI: shell boot, browser-host communication, sha
 | [`ui-sidebar/`](ui-sidebar/README.md) | Presents workspace and session navigation. |
 | [`ui-workspace/`](ui-workspace/README.md) | Provides workspace selection and creation surfaces. |
 | [`ui-conversation/`](ui-conversation/README.md) | Presents the active conversation and its input surface. |
+| [`ui-tool/`](ui-tool/README.md) | Composes Tool call trees and keyed per-Tool views. |
 | [`ui-goal/`](ui-goal/README.md) | Presents and manages the current goal. |
 | [`ui-trajectory/`](ui-trajectory/README.md) | Presents alternate views of agent activity. |
 | [`ui-command/`](ui-command/README.md) | Provides session-aware command discovery and dispatch. |
diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md
index 8f1f7f4677..5a55bb8c2c 100644
--- a/packages/client/README.zh.md
+++ b/packages/client/README.zh.md
@@ -22,6 +22,7 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
 | [`ui-sidebar/`](ui-sidebar/README.md) | 展示 Workspace 与会话导航。 |
 | [`ui-workspace/`](ui-workspace/README.md) | 提供 Workspace 选择与创建界面。 |
 | [`ui-conversation/`](ui-conversation/README.md) | 展示当前会话及其输入界面。 |
+| [`ui-tool/`](ui-tool/README.md) | 编排 Tool 调用树和按 Tool 键控的视图。 |
 | [`ui-goal/`](ui-goal/README.md) | 展示和管理当前目标。 |
 | [`ui-trajectory/`](ui-trajectory/README.md) | 提供 agent（智能体）活动的其他视图。 |
 | [`ui-command/`](ui-command/README.md) | 提供会话感知的命令发现与分发。 |
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index a6cf9c1d7c..ec3199ee02 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -157,19 +157,19 @@ const SEARCH_MATCHES_FIXTURE: { path: string; matches: { lineNumber: number; lin
     ],
   },
   {
-    path: 'packages/client/ui-conversation/src/client/contract/search-card-model.ts',
+    path: 'packages/client/ui-tool/src/client/tool/models/search-card-model.ts',
     matches: [
-      { lineNumber: 24, line: 'export const CHAT_SEARCH_MAX_LINES = 8' },
-      { lineNumber: 60, line: 'export function searchCardModel(block: ToolCallBlock): SearchCardModel | null {' },
+      { lineNumber: 45, line: 'export const CHAT_SEARCH_MAX_LINES = 8' },
+      { lineNumber: 130, line: 'export function searchCardModel(block: ToolCallBlock): SearchCardModel | null {' },
     ],
   },
   {
-    path: 'packages/client/ui-conversation/src/client/toolviews/search-row.tsx',
+    path: 'packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx',
     matches: [
-      { lineNumber: 33, line: 'export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {' },
-      { lineNumber: 35, line: '  const search = searchCardModel(block)' },
-      { lineNumber: 52, line: '      search={search}' },
-      { lineNumber: 78, line: "      yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep', locale: NS }, SearchRow)" },
+      { lineNumber: 34, line: 'export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {' },
+      { lineNumber: 36, line: '  const search = searchCardModel(block)' },
+      { lineNumber: 56, line: '      search={search}' },
+      { lineNumber: 78, line: "      yield ctx.slots.register({ name: 'tool.call.toolview', key: 'grep', locale: NS }, SearchRow)" },
     ],
   },
 ]
@@ -197,9 +197,9 @@ const SEARCH_MATCHES_TEXT = [
 const SEARCH_PATHS_FIXTURE = [
   'packages/client/ui-primitives/src/SearchBlock.tsx',
   'packages/client/ui-primitives/src/SearchBlock.module.css',
-  'packages/client/ui-conversation/src/client/contract/search-card-model.ts',
-  'packages/client/ui-conversation/src/client/toolviews/search-row.tsx',
-  'packages/client/ui-conversation/tests/search-card.spec.tsx',
+  'packages/client/ui-tool/src/client/tool/models/search-card-model.ts',
+  'packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx',
+  'packages/client/ui-tool/tests/search-card.spec.tsx',
 ]
 
 /**
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index ceee6a1f10..67e6c0e61c 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -85,7 +85,7 @@ declare module '@deepseek-ai/dsh-type-meta' {
   }
 }
 
-/** The conversation-snapshot selector hook (ConvViewProps/ToolRowProps take this). */
+/** The conversation-snapshot selector hook supplied to session-scoped UI entries. */
 export type UseConversationSession = SnapshotSelectorHook<ConversationSnapshot>
 
 /**
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index db7db5db5f..126729ad9d 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 6b541b840ed67ee6fd735a0643dde8c60f1ec22d
-README.zh.md: 01692c395cdb0f50e0fd41ab92f51d9e3ceecb4f
+README.md: 3aade8409e74c38cb86a66076cca50d51a1ccbf8
+README.zh.md: 19d08bbc072f1f242417b91ae4dd771f970244b1
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 6b541b840e..fa0c4b7b9b 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, an animated left-to-right gradient `Deep diving...` turn status, per-tool row slot with a bash sample registrant and the todo row), composer dock (session stats sticky with the input), input dock (hairline-separated queue rows plus the todo plan strip), minimal details panel, scope-addressed ConversationService. Contract: api-contracts v3 §7 plus the slot terminal design (store seat / props shares).
+Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, and turn status), composer dock (session stats sticky with the input), input dock (queue rows plus the todo plan strip), details shell, and scope-addressed ConversationService. Tool presentation belongs to [`ui-tool`](../ui-tool/README.md).
 
 Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Every completed marker with structured summary provenance shows the replaced-item and estimated-token counts and discloses the summary on click. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key. A completed checkpoint keeps the context-compaction icon at rest and replaces it with the collapsed or expanded disclosure only on hover or keyboard focus. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when summary provenance is outside the loaded window, the checkpoint remains visible but non-expandable.
 
@@ -16,27 +16,15 @@ Approvals take over the composer through the chain this package declares: `Appro
 
 The session header declares and renders the session-scoped `'conversation.session.header.actions'` list beside the title, allowing feature plugins to contribute controls without entering the skeleton. The composer chain currency includes the current conversation `session`; ui-subagent selects one-shot or parent-unavailable addressed sessions for reason-specific read-only copy, while the ordinary InputBar keeps every addressed child Send-only because the continuation service exposes no public per-Activation cancellation operation and `session.cancel` would bypass its ownership.
 
-Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The header shares the Tool calls geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state, summary, or keyed toolview dispatch ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
+Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The package-internal `DisclosureRow` gives this context surface the same compact geometry as other flow rows while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state or summary ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
 
 A Think row stays collapsed by default and exposes live reasoning throughput without expanding the chain of thought: while its reasoning block is the streaming tail, the summary switches from the settled first line to the latest non-blank line and its one-line scrollport follows each delta to the inline end. Expanding the row removes the moving summary and leaves the full reasoning in ordinary page flow, so page reading never fights an internal follower; settlement restores the stable first-line summary at the left edge ([decision](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)).
 
-Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is an underlined link — it reads as one at rest, not only on hover, because a path styled like the surrounding prose is an affordance nobody finds — and it opens the file through the Host (`host.openPath`, relative paths resolve against the session cwd). A document a browser renders prefers the default browser where the Host platform can name one; Windows and WSL use the Windows registered association. The Host opens it on the Host's own machine: a client reached over a network sees nothing, which is the deliberate scope of this surface. Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
-
-A tool call declaring the `terminal` render intent renders its command output inline, at both conversation render sites, through ui-primitives' `TerminalBlock`. `contract/terminal-card-model.ts` is the single derivation from the snapshot's `callView`/`resultView` pair, so the sites cannot disagree about a command, its cwd, or its exit status; it yields null — the generic path — for any other card tag, including one this client version does not know. Both sites therefore also show the card's run-state dot, which is the same `StateDot` semantic a tool row's leading icon carries, so a row and its own card always agree about one command's state. A multi-line command gets one prompt row per line, with the dot marking the call once on the first row — the exit status is the whole call's, so a dot per line would claim a per-line outcome bash does not report. The keyed `BashRow` carries the card below its summary row; tool rows are summary surfaces, so the card's copy and expand controls are the row's only interactions. The render-site fallback row keeps the card behind its existing expand control. Rows cap at `CHAT_TERMINAL_MAX_LINES` (8) against the panel's 16, which keeps the summary bounded; the panel stays the single-call reading surface. Inline output is licensed per render intent — the terminal and web cards, each with its own bound. A Bash execution failure that settles on the generic path instead exposes its original arguments and full error through the same bounded IN/OUT disclosure, while successful generic results such as a background-start acknowledgement remain summary-only ([decision](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)).
-
-A tool call declaring the `web` render intent renders its web retrieval inline, at both conversation render sites, through ui-primitives' `WebBlock`. `contract/web-card-model.ts` is the single derivation from the snapshot's `resultView`, mirroring the terminal card, so the sites cannot disagree about what a web call shows; it yields null — the generic path — for a running call, a non-web result view, a generic result view, a `card` tag this client version does not know, or a web card whose `kind` this client version does not know (a newer host's value, which the wire cannot be trusted to be `search` or `fetch`). The keyed `WebRow` registers one component under both `web_search` and `web_fetch`, discriminating on the tool name only for its icon and title; it composes the shared `ToolRow`, feeding the card as ToolRow's `web` body, so the retrieval is the row's collapsed-by-default expanded card (the same unified expand every card row has). A web-declaring tool without a keyed row lands on the `GenericToolCard` fallback, which routes the card through ToolRow the same way, and the details panel renders it and, below the card, the flattened model-visible result content — a fetch body is readable only there, since its card carries only the URL and status. Both render sites show the same complete source list — the one the tool returned and the model saw — bounded only by the card's own scroll container height, with no row-versus-panel cap ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md), [source scroll](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)).
-
-A `read` call declaring the `read` render intent renders the returned file window inline, at both conversation render sites, through ui-primitives' `ReadBlock` — the line-numbered, syntax-highlighted content the tool projects. `contract/read-card-model.ts` is the single derivation from the snapshot's `resultView`; the read card is result-side only (a call carries no file content until `execute` returns), so a running read shows its summary alone and it yields null — the generic path — for a non-read result view or a `card` tag this client version does not know. The keyed `ReadRow` composes the shared `ToolRow`, feeding the card as ToolRow's `read` body, so it is the row's collapsed-by-default expanded card; the summary stays a path link that opens the file through the host. The render-site fallback and the details panel are read-aware too. Rows cap at `CHAT_READ_MAX_LINES` (8) against the panel's 16 ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)).
-
-A tool call declaring the `diff` render intent (the `write`/`edit` tools) renders its applied change inline through ui-primitives' `DiffBlock`, the same four-layer shape. `contract/diff-card-model.ts` is the single derivation from the `callView`/`resultView` pair; the settled result's hunks replace the call-time diff, and it yields null — the generic path — for any other card tag or a generic result view (write/edit's execution errors). The keyed `FileMutationRow` (registered under both `write` and `edit`) composes the shared `ToolRow`, feeding the diff as ToolRow's `diff` body, so it is the row's collapsed-by-default expanded card; the summary path link still opens the file through the host, and an errored mutation (no diff card) surfaces its error text through ToolRow's Output section with the first line in the collapsed summary. The render-site fallback and the details panel are diff-aware too. Rows cap at `CHAT_DIFF_MAX_LINES` (8) against the panel's 16 ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)).
+The chat view keeps Tool placement but delegates Tool presentation. It passes each ordered root call through `conversation.chat.tool`, and the details shell passes the selected call through `conversation.details.tool`. The assembled Web bundle fills the whole-Tool seat with [`ui-tool`](../ui-tool/README.md), which selects Runtime-projected Code Dispatch children and owns root/child composition, per-name dispatch, generic rendering, and render-intent cards; the details seat alone retains a raw-result fallback when that renderer is absent.
 
 The chat flow projects consecutive model-retry nodes across retry turns into one stable, muted status row updated to the latest attempt; every retry event remains in the runtime snapshot and session log. Its frontend countdown anchors the scheduled delay to client receipt, avoiding host/browser clock skew, rounds remaining time up to seconds, and has a one-second floor. The latest unresolved retry uses a left-to-right text shimmer. Subsequent turn facts distinguish an attempt that started from one cancelled during backoff, while the Host running bit only controls the live animation; the row then shows a static completed or cancelled label. Normal policy rows show the finite retry maximum; always policy rows show `∞`. Activating the row reveals the latest exact retry delay and failure message. The client runtime removes each failed step's streaming tail before its retry node arrives, while the status remains visible after a later attempt succeeds. An unretried terminal failure renders as a persistent inline status at its turn boundary, showing the display-safe durable message and optional error code without offering an action the Host cannot fulfill; AUTH copy never echoes provider-supplied credential fragments.
 
-A `grep`/`glob` call declaring the `search` render intent renders its result inline, at the same render sites, through ui-primitives' `SearchBlock` — grep's matches grouped by file (each a collapsible header of `lineNumber: line` rows), glob's flat path list. `contract/search-card-model.ts` is the single derivation from the snapshot's `resultView`; unlike the terminal card it reads no `callView`, since a search has no matches or paths before `execute`, so a running search shows its summary alone. It yields null — the generic path — for any non-search result view, a `card` or `kind` this client version does not compile, and (because those ride the untrusted wire frame) a known kind whose `files`/`paths` is malformed. The keyed `SearchRow`, registered under both `grep` and `glob` since the derived `kind` decides the shape, composes the shared `ToolRow`, feeding the card as ToolRow's `search` body, so it is the row's collapsed-by-default expanded card; the render-site fallback routes it the same way. Both cap at `CHAT_SEARCH_MAX_LINES` (8) against the panel's 16. A capped search drops rows from the card, but the locator to the rest — grep/glob's `Full … stored at …` footer — lives only in the result text, so the derivation surfaces that as a recovery footer below the card when (and only when) the result was truncated; a settled call with no card at all (an errored search, a nested `run_code` sub-dispatch, a legacy generic result) surfaces its flattened result text through ToolRow's Output section so nothing is lost behind a bare summary ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md)).
-
-Tool rows use the keyed, session-scoped `'conversation.chat.toolview'` slot; its render site dispatches via `entryKey: toolName` with `GenericToolCard` as the call-site fallback. The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openFile`), and `ToolRowProps` composes it with the session standard kit. A registrant is a plain plugin with only the slot service edge: `ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row))`. The declaration is the activation and reload dependency; `ConversationService` is required only by registrations that call its actions. Trajectory and waterfall toolview slots share this shape and use their own render sites; RendersCheck rejects a declaration nobody renders.
-
-The todo surfaces are two registrations over that shape, both using slot declaration injection without a `ConversationService` edge. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> completed · <active item>` plus a `+<n>` count of the other active ones, parsed from its args through `toolviews/plan-summary.ts` `planSummary`, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). When the deployment permits parallel work, several items may be `in_progress` at once, so `planSummary` names the first and counts the rest, and deliberately returns the two unjoined: the row ellipsizes its summary text, so a count concatenated onto the end of the task name would be the first thing a narrow row clips. The row hands the count to `ToolRow`'s `summarySuffix`, the shared row's non-shrinking slot beside that ellipsized text (an error row drops it, since its collapsed summary is the failure line). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: 0` — before Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus its own `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted; status glyphs are the figma check / progress / dashed-pending set), so it reports the parallel count without needing a name to truncate. The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
+`TodoDock` takes the `'conversation.input.dock'` list slot at `order: 0` — before Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus its own `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted). The dock adapter owns selection so the panel stays a pure function of its props. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included. The `todo_write` Tool row belongs to [`ui-tool`](../ui-tool/README.md).
 
 `QueueDock` is the terminal input-dock entry at `order: 20`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `"<n> 条排队消息"` header whose button expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Each visible ordinary-session row remains a single-line preview with its exact-occurrence edit, delete, and strict-steer actions; addressed subagents retain the rows as a read-only projection because their continuation transport does not expose queue mutation. If strict steer loses to a closed window, the original occurrence remains queued for normal delivery; if the driver already claimed it, normal delivery is already underway. Neither converged race displays a failure, while transport and unknown failures do.
 
@@ -50,7 +38,7 @@ The composer bar declares session-scoped single seats for `'conversation.input.p
 
 The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. The same window fold averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy moved off the row onto the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation.
 
-`src/client/` is organized by domain. `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations and composed props, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` directories import contract files and never each other. `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components and the store factory stay internal and reach the page through apply's slot registrations.
+`src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` export surface contains only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations.
 
 A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 01692c395c..6dc803ee72 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离、带从左到右动态渐变的 `Deep diving...` 轮次状态、逐工具行 slot 及一个 bash 示例注册方与 todo 行）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（带发丝分界线的队列行加 todo 计划条）、最小详情面板、按 scope 寻址的 ConversationService。契约：api-contracts v3 §7 加 slot 终端设计（store seat／props share）。
+会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离与轮次状态）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（队列行加 todo 计划条）、详情壳层，以及按 scope 寻址的 ConversationService。Tool 展示属于 [`ui-tool`](../ui-tool/README.md)。
 
 压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。每个具备结构化摘要溯源的完成标记都会显示被替换条目数量和估算 token 数量，并可点击展开摘要。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。
 
@@ -14,29 +14,17 @@
 
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 
-已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。标题栏通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态、摘要或键控 toolview 分发（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
+已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。包内部的 `DisclosureRow` 让该上下文界面与消息流中的其他紧凑行保持相同几何，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态或摘要（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 
-通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是带下划线的链接——静止状态下就读得出是链接，而不只在悬停时，因为一条与周围正文同样样式的路径是没人会发现的交互——点击即经由 Host 打开文件（`host.openPath`，相对路径相对会话 cwd 解析）。浏览器能渲染的文档会在 Host 平台能够确定默认浏览器时优先使用它；Windows 与 WSL 则使用 Windows 注册的文件关联。Host 在它自己的机器上打开：经网络访问的客户端看不到任何东西，这是本交互面刻意划定的范围。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
-
-声明 `terminal` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `TerminalBlock` 内联渲染其命令输出。`contract/terminal-card-model.ts` 是从快照的 `callView`／`resultView` 对推导的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧；对任何其他 card 标签——包括当前客户端版本不认识的标签——它返回 null，落回通用路径。因此两个渲染点也都显示卡片的运行状态点，它与工具行行首图标承载同一套 `StateDot` 语义，所以一行与其自身的卡片对同一条命令的状态总是一致。多行命令的每一行各占一个提示行，状态点只在第一行为整次调用标记一次——退出状态属于整次调用，因此每行一枚就会声称一个 bash 并不报告的逐行结果。键控的 `BashRow` 把卡片放在摘要行下方；工具行是摘要 surface，因此卡片的复制与展开控件是该行唯一的交互。渲染点兜底行则保持其既有的展开控件。行的上限是 `CHAT_TERMINAL_MAX_LINES`（8），面板为 16，因此摘要保持有界；面板仍是单次调用的阅读 surface。内联输出按渲染意图开放——终端卡片与 web 卡片各有自己的上限。若 Bash 执行失败时落在通用路径，则改用同样有界的 IN/OUT 展开区暴露原始参数和完整错误；后台启动确认等成功的通用结果仍只显示摘要（[决策](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)）。
-
-声明 `web` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `WebBlock` 内联渲染其 web 检索。`contract/web-card-model.ts` 是从快照的 `resultView` 推导的唯一位置，镜像终端卡片，因此两个渲染点不可能对一次 web 调用的显示产生分歧；对运行中的调用、非 web 的 result view、generic result view、本客户端版本不认识的 `card` 标签，或本客户端版本不认识 `kind` 的 web 卡片（更新的 host 发来的值，wire 上不可信其为 `search` 或 `fetch`），它返回 null，落回通用路径。键控的 `WebRow` 把一个组件注册在 `web_search` 与 `web_fetch` 两个键下，仅根据工具名判别以选取图标与标题；它组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `web` body 传入，因此检索成为该行默认折叠的展开卡片（与每个卡片行相同的统一展开交互）。没有自己键控行的 web 声明工具落到 `GenericToolCard` 兜底，它以同样方式经 ToolRow 渲染卡片，详情面板渲染它，并在卡片下方渲染摊平的模型可见结果内容——fetch 正文只在此处可读，因为其卡片只携带 URL 和状态。两个渲染点显示同一份完整来源列表——工具返回、模型看到的那一份——仅受卡片自身滚动容器的高度约束，不存在行与面板的两级上限（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)、[来源滚动](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)）。
-
-声明 `read` 渲染意图的 `read` 调用，会在两个对话渲染点上都通过 ui-primitives 的 `ReadBlock` 内联渲染返回的文件窗口——工具投影出的带行号、语法高亮的内容。`contract/read-card-model.ts` 是从快照的 `resultView` 推导的唯一位置；read 卡片是仅结果侧的(调用在 `execute` 返回前不携带文件内容)，所以运行中的 read 只显示摘要，且对非 read 的 result view 或本客户端版本不认识的 `card` 标签返回 null，落回通用路径。键控的 `ReadRow` 组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `read` body 传入，因此它是该行默认折叠的展开卡片；摘要仍是一个经 host 打开文件的路径链接。渲染点兜底行与详情面板同样感知 read。行的上限是 `CHAT_READ_MAX_LINES`（8），面板为 16（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)）。
-
-声明 `diff` 渲染意图的工具调用（`write`／`edit` 工具），通过 ui-primitives 的 `DiffBlock` 内联渲染其已应用的改动，采用同一套四层结构。`contract/diff-card-model.ts` 是从 `callView`／`resultView` 对推导的唯一位置；已结算 result 的 hunk 替换 call 时 diff，对任何其他 card 标签或 generic result view（write/edit 的执行错误）它返回 null，落回通用路径。键控的 `FileMutationRow`（在 `write` 与 `edit` 下都注册）组合共享的 `ToolRow`，把 diff 作为 ToolRow 的 `diff` body 传入，因此它是该行默认折叠的展开卡片；摘要路径链接仍经 host 打开文件，而出错的改动（没有 diff 卡片）经 ToolRow 的 Output 区呈现其错误文本，首行进入折叠摘要。渲染点兜底行与详情面板同样感知 diff。行的上限是 `CHAT_DIFF_MAX_LINES`（8），面板为 16（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)）。
+聊天视图保留 Tool 的消息流位置，但委托其展示。它通过 `conversation.chat.tool` 传递每个已排序的 root call；详情壳层则通过 `conversation.details.tool` 传递当前选中的调用。组装后的 Web bundle 由 [`ui-tool`](../ui-tool/README.md) 填充整体 Tool 席位，并由后者选择 Runtime 已投影的 Code Dispatch 子调用，负责 root/child 编排、按名称分发、通用展示和 render-intent 卡片；只有详情席位会在该 renderer 缺席时保留 raw-result fallback。
 
 聊天流会将跨重试轮次连续出现的模型重试节点投影为一个稳定的弱化状态行，并用最新一次尝试更新该行；每个重试事件仍保留在运行时快照与会话日志中。前端倒计时以客户端收到事件的时刻为计划延迟的起点，避免 Host 与浏览器的时钟偏差；剩余时间向上取整到秒，且下限为 1 秒。最近一次尚未完成的重试会显示从左到右的文字渐变动画。后续轮次事实用于区分已开始的尝试与在退避期间取消的尝试，Host 的 running 位只控制实时动画；随后该行会显示静态的已完成或已取消标签。normal 策略行显示有限重试上限；always 策略行显示 `∞`。激活该行会显示最近一次重试的精确延迟和失败消息。客户端运行时会在相应重试节点到达前移除每个失败步骤的流式输出尾部；后续某次尝试成功后，该状态仍保持可见。未进入重试的终态失败会在其轮次边界渲染为持久的内联状态，展示适合显示的持久消息与可选错误码，但不会提供 Host 无法兑现的操作；AUTH 文案绝不会回显提供方给出的凭据片段。
 
-声明 `search` 渲染意图的 `grep`／`glob` 调用，会在同样的渲染点上通过 ui-primitives 的 `SearchBlock` 内联渲染其结果——grep 的匹配按文件分组（每个是一个可折叠的头，下辖 `lineNumber: line` 行），glob 是扁平路径列表。`contract/search-card-model.ts` 是从快照的 `resultView` 推导的唯一位置；与终端卡片不同，它不读 `callView`，因为搜索在 `execute` 前没有匹配或路径，所以运行中的搜索只显示摘要。对任何非搜索的结果视图、当前客户端版本无法编译的 `card` 或 `kind`、以及（因为这些都与不可信的 wire 帧同行）一个 `files`／`paths` 格式错误的已知 kind，它都返回 null，落回通用路径。键控的 `SearchRow` 因推导出的 `kind` 决定形态而同时注册在 `grep` 与 `glob` 下，组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `search` body 传入，因此它是该行默认折叠的展开卡片；渲染点兜底行以同样方式渲染它。两者上限都是 `CHAT_SEARCH_MAX_LINES`（8），面板为 16。被截断的搜索会从卡片里丢掉一些行，但通往其余部分的定位符——grep/glob 的 `Full … stored at …` 脚注——只存在于结果文本里，因此推导在（且仅在）结果被截断时把它作为恢复脚注画在卡片下方；一个完全没有卡片的已结算调用（出错的搜索、嵌套 `run_code` 子派发、旧日志的 generic 结果）则经 ToolRow 的 Output 区呈现其压平后的结果文本，从而不让任何内容丢失在一个光秃秃的摘要之后（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md)）。
-
-工具行使用键控、Session scope 的 `'conversation.chat.toolview'` slot；其渲染点通过 `entryKey: toolName` 分发，并以 `GenericToolCard` 作为调用点 fallback。owner 载荷是统一的 `ToolRowOwnerProps`（`callId`／`toolName`／`block`／`openFile`），`ToolRowProps` 将其与 Session 标准工具包组合。注册方是只依赖 slot 服务的普通插件：`ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row))`。声明本身就是激活与重载依赖；只有调用 `ConversationService` 操作的注册项才需要该服务。Trajectory 与 waterfall（瀑布式事件）工具视图 slot 共享此形状并使用各自的渲染点；RendersCheck 会拒绝没有任何渲染方的声明。
-
 审批经由本包声明的链接管编辑器：`ApprovalPanel` 注册为按选择器路由的 `'conversation.composer'` 配置项（ui-question 模式），在审批等待未决期间取代 InputBar 占据编辑器（琥珀色条、理由标题、来自运行中调用参数的配对命令行、一次性的拒绝／允许）。`contract/slots.ts` 中的 `PendingApproval` 领域面在运行时 `PendingWait` 载体之上拥有 wire 编码——带审计关联的 `ApprovalResponsePayload` 值；广播的 `approval/resolved` 帧使等待落定并恢复编辑器。运行时 manager 会将所有审批或问题等待通过 `SessionSummary.pendingInteraction` 投影出来，未实例化的 Session 也不例外；`ui-workspace` 负责其侧边栏呈现。未决等待完全离开消息流：问题（ui-question）与审批（ApprovalPanel）都经编辑器接管作答，不再保留只读占位卡。编辑器底行的 Access 席位挂载 `PermissionSelect`，由 host 计算的 `permissions` 投影经标准工具包 `useProjection` 供数（key 缺席即隐藏 chip）；chip 打开 Menu 原语下拉，其中 kebab-case 预设名渲染为 Title Case 标签；普通安全预设会立即经输入栏注入的 `command` 回调提交 `/permission <preset>`，而 `danger-full-access` 在界面中显示为 `Full access`，选择后先打开页面内的 Modal 风险确认。用户勾选确认项前启用按钮始终不可用；取消、Escape、关闭按钮与点击遮罩都不会提交命令。
 
-todo 两个面就是在该形状上的两个注册项，都使用 slot 声明注入，不依赖 `ConversationService`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 经 `toolviews/plan-summary.ts` 的 `planSummary` 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`，以及「其余活跃项的数量」`+<n>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。部署允许并行工作时，可以有多个条目同时处于 `in_progress`，因此 `planSummary` 给出第一个活跃条目并计数其余，且刻意不把两者拼成一个字符串：行会对摘要文本做省略号截断，把数量接在任务名末尾时，窄行最先裁掉的正是这个数量。该行把数量交给 `ToolRow` 的 `summarySuffix`——共享行在被截断文本旁的不收缩位（出错的行会丢弃它，因为其折叠摘要是失败首行）。`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加它自行计算的、以 `·` 连接的各状态计数（本地化，形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略；状态图标为 figma 的勾选／进行中／虚线未开始一组），因此它无需一个可被截断的任务名即可报告并行数量。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。
+`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），作为计划条读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`。面板接收纯列表，列表为空时自我隐藏；列表非空时默认折叠，表头显示标题及以 `·` 连接的各状态计数（如 `1 已完成 · 2 进行中 · 1 待处理`，省略零计数）。dock adapter 拥有 selection，因此面板保持为 props 的纯函数。输入区 composer 链隐藏的一切也会隐藏整个 dock。`todo_write` Tool 行属于 [`ui-tool`](../ui-tool/README.md)。
 
 `QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `"<n> 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。普通会话中的每条可见行仍是单行预览，并提供针对精确单次入队项的编辑、删除和严格 steering 操作；已寻址 subagent 则保留只读行，因为其继续执行传输不提供 Queue 变更。如果严格 steering 输给已关闭的窗口，原单次入队项会留在 Queue 中正常投递；如果驱动器已经认领该项，正常投递就已开始。这两种已收敛的竞态都不显示失败，传输和未知错误仍会显示。
 
@@ -50,7 +38,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。同一次窗口折算还会把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率从统计行移到了 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当分子与路由容量都已知时才渲染；点击弹出的面板把「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列。圆环与标题读取 `projectedTokens`——把提供方样本沿此后表层的增减推进到当下——因此压缩会立刻反映出来，而不必再等一整轮；组成明细行仍是纯启发式，因此加起来依然不等于标题数字（[原理](../../llm/token-meter/README.md)）。占用率是刻意为之的近似值：分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测。
 
-`src/client/` 按领域组织。`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明与组合后的 props、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/` 目录只导入 contract 文件，彼此之间从不互相导入。`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件与 store factory 保持内部，经 apply 的 slot 注册抵达页面。
+`src/client/` 按领域组织。`contract/` 是 slot 声明、组合 props 与跨领域类型的共享表层；`skeleton/`、`chat/`、`input/`、`queue/` 和 `settings/` 保持内部实现，`apply.ts` 是它们的组装点。`/client` 导出表层只包含 loader entry、service class 和 contract 类型；组件与 store factory 经 slot 注册抵达页面。
 
 完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。
 
diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
index ff4e74da5e..2ff87cc0e2 100644
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-conversation",
-  "description": "Conversation domain: skeleton (header/tabs/composer), chat view, ctx.toolviews registry, minimal details panel",
+  "description": "Conversation domain: skeleton, ordered chat flow, composer, and details host",
   "version": "0.0.1",
   "private": true,
   "type": "module",
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index b6a3fc791c..74533b5e2d 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -11,7 +11,7 @@ import type {
   ConversationSessionHeaderInjected, ConversationSessionInjected, DetailsInjected,
 } from './contract/slots.ts'
 import type { InputNotice } from './input/contract.ts'
-import { resolveToolPath } from './contract/tool-call-model.ts'
+import { resolveToolPath } from './contract/tool-path.ts'
 import { createChatStore } from './stores.ts'
 import { ConversationService } from './service.ts'
 import type { IConversation } from './service.ts'
@@ -24,14 +24,7 @@ import { EnterBehaviorRow } from './settings/EnterBehaviorRow.tsx'
 import type { EnterBehaviorRowInjected } from './settings/EnterBehaviorRow.tsx'
 import { ChatView } from './chat/ChatView.tsx'
 import { StatsLine } from './chat/StatsLine.tsx'
-import { bashToolviewSample } from './toolviews/bash-sample.tsx'
-import { readToolview } from './toolviews/read-row.tsx'
-import { fileMutationToolview } from './toolviews/file-mutation-row.tsx'
-import { searchToolview } from './toolviews/search-row.tsx'
-import { webToolview } from './toolviews/web-row.tsx'
 import { ApprovalPanel } from './skeleton/ApprovalPanel.tsx'
-import { todoToolview } from './toolviews/todo-row.tsx'
-import { askQuestionToolview } from './toolviews/ask-question-row.tsx'
 import { todoDockEntry } from './skeleton/TodoPanel.tsx'
 import { queueDockEntry } from './queue/QueueDock.tsx'
 import { ConversationRoot } from './skeleton/ConversationRoot.tsx'
@@ -41,7 +34,7 @@ import { en, NS, zh, type ConversationKey } from './locales.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
-    /** The conversation surfaces' copy (skeleton, chat view, toolviews, docks). */
+    /** The conversation skeleton, chat flow, commands, details, and docks copy. */
     conversation: ConversationKey
   }
 }
@@ -304,10 +297,8 @@ export function apply(ctx: Context): void {
   slots.register({ name: 'conversation.composer', select: selectApproval, priority: 1, locale: NS }, ApprovalPanel)
 
   // The chat view: first entry of the ring this package just declared.
-  // Declaring the keyed toolview hole here is claiming it: ChatView is the
-  // only component authorized to render per-tool rows. Shares the chat
-  // store, so its selection writes land in the same per-session instance the
-  // details panel reads.
+  // ChatView owns ordered Tool placement but delegates each whole root call
+  // to ui-tool, which owns root/subcall composition and atomic dispatch.
   slots.register({
     name: 'conversation.view',
     id: 'chat',
@@ -315,7 +306,7 @@ export function apply(ctx: Context): void {
     label: () => t('view.chat'),
     locale: NS,
     children: {
-      'conversation.chat.toolview': { kind: 'keyed', scope: 'session' },
+      'conversation.chat.tool': { kind: 'single', scope: 'session' },
       'conversation.chat.commandview': { kind: 'keyed', scope: 'session' },
       'conversation.chat.turnTail': { kind: 'chain', scope: 'session' },
     },
@@ -368,34 +359,6 @@ export function apply(ctx: Context): void {
   // this service remains only where conversation actions are required.
   ctx.plugin(ConversationService, { input: inputHub, blocks: composerBlocks })
 
-  // The bash sample rides the same declaration seam, in third-party posture
-  // (ToolRow-matching Bash · {description} chrome).
-  ctx.plugin(bashToolviewSample)
-
-  // The read row rides the same seam (a product registration, not a sample):
-  // Read · {path} chrome with the file's read card resident below it.
-  ctx.plugin(readToolview)
-
-  // The write/edit rows ride the same seam: a file-mutation call declares the
-  // diff render intent, so these rows stack the applied diff card under their
-  // path-link summary (the terminal card's posture, applied to diffs).
-  ctx.plugin(fileMutationToolview)
-
-  // The grep/glob search row rides the same seam: one component registered
-  // under both tool names, since both declare the same search render intent.
-  ctx.plugin(searchToolview)
-
-  // The web rows ride the same seam: one WebRow registered under both
-  // web_search and web_fetch, rendering the completed retrieval's web card
-  // resident under the summary (a product registration, not a sample).
-  ctx.plugin(webToolview)
-
-  // The todo_write row rides the same seam (a product registration, not a sample).
-  ctx.plugin(todoToolview)
-
-  // The ask_user_question row: waiting/answered/cancelled interaction outcome.
-  ctx.plugin(askQuestionToolview)
-
   // The plan strip rides the input dock above the queue rows (same posture).
   ctx.plugin(todoDockEntry)
 
@@ -406,6 +369,9 @@ export function apply(ctx: Context): void {
   slots.register({
     name: 'details',
     locale: NS,
+    children: {
+      'conversation.details.tool': { kind: 'single', scope: 'session' },
+    },
     store: chatStore,
     inject: (): DetailsInjected => ({
       closeDetails: () => { layout.closeDetails() },
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.module.css b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
index 1b5b58ce47..c600b3b0aa 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.module.css
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
@@ -64,17 +64,6 @@
 /* Selection still sets data-selected for details linkage; no outline —
    tool rows match Think chrome (no selected ring). */
 
-/* run_code sub-dispatch rows: indented under the parent row, left-edged so
-   the code turn reads as one unit; each nested row is itself a .callRow. */
-.subCalls {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  margin: 4px 0 2px 22px;
-  padding-left: 8px;
-  border-left: 1px solid var(--dsw-alias-border-l2);
-}
-
 /* Turn activity keeps the former loader's one-line footprint. A pale
    brand-blue band sweeps from left to right; reduced-motion keeps it static. */
 .turnStatus {
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index 18fba234de..c52a4623be 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -2,10 +2,9 @@
 // assistant narration, tool summary rows grouped into step runs, pending
 // cards, paging, and bottom-follow. Session stats live on
 // 'conversation.composer.dock' (sticky with the composer). Pure component
-// registered directly; its registration declares the keyed
-// 'conversation.chat.toolview' hole, so tool rows render through the props
-// renderSlot share (entryKey = tool name, GenericToolCard as the render-site
-// fallback).
+// registered directly; its registration declares the whole-Tool
+// 'conversation.chat.tool' seat. ui-tool owns root/subcall composition and
+// keyed per-tool dispatch behind that boundary.
 //
 // Scroll: when nested under `[data-conversation-scroll]` (active conversation
 // column), that host is the scrollport and this view is flow content; when
@@ -25,7 +24,7 @@ import {
   memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
 } from 'react'
 import type {
-  CodeSubCall, CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode,
+  CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -34,7 +33,6 @@ import { assistantActionsSeqs, assistantBranchSeqs, deriveChatFlow, runningTurnS
 import { AssistantMarkdown } from './AssistantMarkdown.tsx'
 import { CompactionCommandCard } from './CompactionCommandCard.tsx'
 import { GenericCommandCard } from './GenericCommandCard.tsx'
-import { GenericToolCard } from './GenericToolCard.tsx'
 import { MessageItem, PendingSteeringBubble } from './MessageItem.tsx'
 import { formatRunDuration } from './message-chrome.ts'
 import { deriveTurnMetrics } from './turn-metrics.ts'
@@ -104,8 +102,8 @@ type OpenFile = (path: string) => void
 
 type InspectCall = (callId: string) => void
 
-/** The declared toolview hole's render share (stable framework binding, passed through memoized rows). */
-type RenderToolRow = ChatViewSlotProps['renderSlot']
+/** Declared child-slot render share (stable framework binding). */
+type RenderChatSlot = ChatViewSlotProps['renderSlot']
 
 type ChatScrollPosition = NonNullable<ReturnType<ChatViewSlotProps['chatScroll']['read']>>
 
@@ -136,129 +134,49 @@ function scrollPosition(list: HTMLElement, scrollport: HTMLElement): ChatScrollP
   }
 }
 
-/** One `run_code` sub-dispatch row: the identical keyed-slot dispatch as a
- *  top-level call (same registrations, same fallback), nested by the parent.
- *  A started-but-unsettled sub-call arrives as the RunningToolCall shape and
- *  renders the running state exactly as a native in-flight row. */
-const SubCallRow = memo(function SubCallRow({ renderSlot, node, openFile, selected, cwd, inspectCall, t }: {
-  renderSlot: RenderToolRow
-  node: CodeSubCall
-  openFile: OpenFile
-  selected: boolean
-  cwd: string | undefined
-  inspectCall: InspectCall
-  t: ChatViewSlotProps['t']
-}) {
-  const settled = 'kind' in node
-  const toolName = settled ? node.call?.name ?? '' : node.name
-  const owner = useMemo(() => ({
-    callId: node.callId, toolName, block: node, openFile, cwd,
-    inspect: () => { inspectCall(node.callId) },
-  }), [node, toolName, openFile, cwd, inspectCall])
-  return (
-    <div
-      className={css.callRow}
-      data-chat-anchor-key={`call:${node.callId}`}
-      data-chat-call-id={node.callId}
-      data-selected={selected || undefined}
-    >
-      {renderSlot('conversation.chat.toolview', owner, {
-        entryKey: toolName,
-        fallback: <GenericToolCard {...owner} t={t} />,
-      })}
-    </div>
-  )
-})
-
-/** One tool call row (result or running): dispatches through the keyed
- *  toolview slot with the owner payload; unregistered tools fall back to
- *  GenericToolCard at this render site. A `run_code` call additionally
- *  renders its logged sub-dispatches as always-visible indented rows —
- *  each one the same keyed-slot dispatch as a native top-level call. */
-const CallRow = memo(function CallRow({
-  renderSlot, callId, toolName, block, openFile, selected, subCalls, selectedCallId, cwd, inspectCall, t,
+/** One ordered root Tool call handed intact to the Tool presentation plugin. */
+const ToolSeat = memo(function ToolSeat({
+  renderSlot, callId, toolName, block, openFile, selectedCallId, cwd, inspectCall,
 }: {
-  renderSlot: RenderToolRow
+  renderSlot: RenderChatSlot
   callId: string
   toolName: string
   block: ToolResultNode | RunningToolCall
   openFile: OpenFile
-  selected: boolean
-  /** `run_code` sub-dispatches in dispatch order (reference-stable per
-   *  parent; running entries settle in place); undefined for ordinary calls. */
-  subCalls?: readonly CodeSubCall[] | undefined
-  /** The store's selected callId, matched against sub-rows (undefined when no sub-row here is selected). */
   selectedCallId?: string | undefined
-  /** Session workspace root for path-relative summaries. */
   cwd: string | undefined
   inspectCall: InspectCall
-  t: ChatViewSlotProps['t']
 }) {
   const owner = useMemo(() => ({
-    callId, toolName, block, openFile, cwd,
-    inspect: () => { inspectCall(callId) },
-  }), [callId, toolName, block, openFile, cwd, inspectCall])
-  return (
-    <div
-      className={css.callRow}
-      data-chat-anchor-key={`call:${callId}`}
-      data-chat-call-id={callId}
-      data-selected={selected || undefined}
-    >
-      {renderSlot('conversation.chat.toolview', owner, {
-        entryKey: toolName,
-        fallback: <GenericToolCard {...owner} t={t} />,
-      })}
-      {subCalls !== undefined && subCalls.length > 0 && (
-        <div className={css.subCalls} data-subcalls>
-          {subCalls.map(node => (
-            <SubCallRow
-              key={node.callId}
-              renderSlot={renderSlot}
-              node={node}
-              openFile={openFile}
-              selected={node.callId === selectedCallId}
-              cwd={cwd}
-              inspectCall={inspectCall}
-              t={t}
-            />
-          ))}
-        </div>
-      )}
-    </div>
-  )
+    callId, toolName, block, selectedCallId, cwd, openFile, inspectCall,
+  }), [callId, toolName, block, selectedCallId, cwd, openFile, inspectCall])
+  return renderSlot('conversation.chat.tool', owner)
 })
 
 /** Consecutive tool results as one step-run group (uniform 16px rhythm). */
-const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selectedCallId, codeDispatches, cwd, inspectCall, t }: {
-  renderSlot: RenderToolRow
+const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selectedCallId, cwd, inspectCall }: {
+  renderSlot: RenderChatSlot
   results: readonly ToolResultNode[]
   openFile: OpenFile
-  /** Only set when the selected call lives in THIS group, top-level or nested (memo economy). */
+  /** Tool ownership resolves whether the selection is this root or one of its children. */
   selectedCallId: string | undefined
-  /** Sub-dispatch index off the snapshot (map reference is chunk-storm stable). */
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
   /** Session workspace root for path-relative summaries. */
   cwd: string | undefined
   inspectCall: InspectCall
-  t: ChatViewSlotProps['t']
 }) {
   return (
     <div className={css.toolGroup}>
       {results.map(node => (
-        <CallRow
+        <ToolSeat
           key={node.callId}
           renderSlot={renderSlot}
           callId={node.callId}
           toolName={node.call?.name ?? ''}
           block={node}
           openFile={openFile}
-          selected={node.callId === selectedCallId}
-          subCalls={codeDispatches.get(node.callId)}
           selectedCallId={selectedCallId}
           cwd={cwd}
           inspectCall={inspectCall}
-          t={t}
         />
       ))}
     </div>
@@ -269,7 +187,7 @@ const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selec
  *  generic card as the render-site fallback (zero registration required). A
  *  run-less cross-window node has no name and always lands on the fallback. */
 const CommandRow = memo(function CommandRow({ renderSlot, node, compaction, t }: {
-  renderSlot: RenderToolRow
+  renderSlot: RenderChatSlot
   node: CommandNode
   compaction?: Extract<ConversationNode, { kind: 'compaction' }>
   t: ChatViewSlotProps['t']
@@ -336,8 +254,8 @@ function StreamingTail({ useSession, t }: {
 }
 
 /**
- * The chat view slot entry: pure component over the composed props (tool rows
- * render through the declared keyed hole's renderSlot share).
+ * The chat view slot entry: pure component over the composed props; each
+ * ordered root Tool call crosses the declared whole-Tool render seat.
  */
 export function ChatView({
   useSession, useSessions, useStore, renderSlot, renderSlotChain, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt, t,
@@ -350,7 +268,6 @@ export function ChatView({
   const cwd = useSessions(s => s.byId[sessionId]?.cwd)
   const running = useSession(s => s.running)
   const runningCalls = useSession(s => s.runningCalls)
-  const codeDispatches = useSession(s => s.codeDispatches)
   const openState = useSession(s => s.openState)
   const openError = useSession(s => s.openError)
   const hasMore = useSession(s => s.hasMore)
@@ -569,19 +486,14 @@ export function ChatView({
 
   const renderItem = (item: ChatFlowItem): ReactNode => {
     if (item.kind === 'tool-group') {
-      const inGroup = selectedCallId !== undefined
-        && item.results.some(r => r.callId === selectedCallId
-          || codeDispatches.get(r.callId)?.some(sub => sub.callId === selectedCallId) === true)
       return (
         <ToolGroup
           renderSlot={renderSlot}
           results={item.results}
           openFile={openFile}
-          selectedCallId={inGroup ? selectedCallId : undefined}
-          codeDispatches={codeDispatches}
+          selectedCallId={selectedCallId}
           cwd={cwd}
           inspectCall={inspectCall}
-          t={t}
         />
       )
     }
@@ -676,19 +588,16 @@ export function ChatView({
           {runningCalls.length > 0 && (
             <div className={css.toolGroup}>
               {runningCalls.map(call => (
-                <CallRow
+                <ToolSeat
                   key={call.callId}
                   renderSlot={renderSlot}
                   callId={call.callId}
                   toolName={call.name}
                   block={call}
                   openFile={openFile}
-                  selected={call.callId === selectedCallId}
-                  subCalls={codeDispatches.get(call.callId)}
                   selectedCallId={selectedCallId}
                   cwd={cwd}
                   inspectCall={inspectCall}
-                  t={t}
                 />
               ))}
             </div>
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index be57f08523..2ef67f4aa8 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -31,13 +31,10 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      */
     'conversation.view': { kind: 'list'; scope: 'session'; owner: ConvViewOwnerProps }
     /**
-     * The chat view's per-tool row hole: keyed dispatch on the wire tool name
-     * (the key space is runtime-open — SlotMap declares slots, never keys).
-     * Declared by the chat view entry (declaring is claiming); the render
-     * site dispatches via `entryKey: toolName` with GenericToolCard as the
-     * `fallback` for unregistered tools.
+     * One root Tool call at its ordered ChatFlow position. The chat view owns
+     * placement; ui-tool owns root/subcall composition and keyed dispatch.
      */
-    'conversation.chat.toolview': { kind: 'keyed'; scope: 'session'; owner: ToolRowOwnerProps }
+    'conversation.chat.tool': { kind: 'single'; scope: 'session'; owner: ToolTreeOwnerProps }
     /**
      * The chat view's per-command row hole: keyed dispatch on the command
      * name (`command/run.name`; a run-less cross-window node has none and
@@ -55,6 +52,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * to return null; an all-declined chain renders nothing.
      */
     'conversation.chat.turnTail': { kind: 'chain'; scope: 'session'; owner: TurnTailOwnerProps }
+    /** Selected Tool call output inside the details panel. */
+    'conversation.details.tool': { kind: 'single'; scope: 'session'; owner: DetailsToolOwnerProps }
     /**
      * The composer takeover chain: entries are selector-routed replacements
      * of the default InputBar. Declared by this package's 'conversation'
@@ -177,42 +176,36 @@ export interface TurnTailOwnerProps {
   openFile: (path: string) => void
 }
 
-/**
- * Owner share of a per-view toolview slot: the call material the rendering
- * view supplies per row. Uniform across views — the trajectory/waterfall
- * toolview slots (same kind/scope/owner, names fixed by the slot-naming
- * discipline) land with their own row render sites; today only the chat slot
- * is declared (RendersCheck rejects a declaration nobody renders).
- */
-export interface ToolRowOwnerProps {
-  /** Tool call identity (details linkage; stable across running → settled). */
+/** Owner currency of the chat view's whole-Tool rendering seat. */
+export interface ToolTreeOwnerProps {
+  /** Root Tool call identity, stable across running → settled. */
   callId: CallId
-  /** Wire tool name (also the keyed dispatch key at the render site). */
+  /** Root wire Tool name. */
   toolName: string
-  /** Frozen call slice: the running call or the settled result node. */
+  /** Frozen root call slice: running call or settled result node. */
   block: ToolCallBlock
+  /** Selected call id; the Tool owner resolves whether it is root or child. */
+  selectedCallId?: CallId | undefined
   /** Session workspace root; path summaries display relative to it. */
   cwd?: string | undefined
   /**
    * Open a tool-arg filesystem path with the host OS default application.
-   * The chat view resolves relative paths against the session cwd.
+   * The conversation owner resolves relative paths against the session cwd.
    */
   openFile: (path: string) => void
   /**
-   * Jump to this call's record in the trajectory view (the expanded row's
-   * hover Inspect affordance). Undefined when no trajectory jump is wired.
+   * Jump to any call in this tree in the trajectory view.
    */
-  inspect?: (() => void) | undefined
+  inspectCall: (callId: CallId) => void
 }
 
-/**
- * Full props of a registered tool-row component: the slot's runtime share
- * (owner payload + session standard kit + global seat). Registrants type
- * their component `FC<ToolRowProps & I>` with `I` inferred from their inject
- * factory. Declared against the chat slot; the three per-view toolview slots
- * share one declaration shape, so this alias serves them all.
- */
-export type ToolRowProps = PropsRuntime<'conversation.chat.toolview'>
+/** Owner currency of the details panel's Tool output renderer. */
+export interface DetailsToolOwnerProps {
+  /** Frozen selected call slice. */
+  block: ToolCallBlock
+  /** Session workspace root for card cwd and relative-path display. */
+  cwd?: string | undefined
+}
 
 /**
  * Owner share of the per-command row slot: the frozen {@link CommandNode}
@@ -229,7 +222,7 @@ export interface CommandRowOwnerProps {
   compaction?: CompactionSummaryNode
 }
 
-/** Full props of a registered command-row component (same shape rule as {@link ToolRowProps}). */
+/** Full props of a registered command-row component. */
 export type CommandRowProps = PropsRuntime<'conversation.chat.commandview'>
 
 /**
@@ -521,9 +514,9 @@ export interface ChatViewInjected {
   forkAt: (seq: number) => void
 }
 
-/** Full chat-view component props: runtime & the declared toolview/commandview holes' render share & store & injected & locale seat. */
+/** Full chat-view component props: runtime & its Tool/command/tail render shares & store & injected & locale seat. */
 export type ChatViewSlotProps =
-  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.toolview' | 'conversation.chat.commandview' | 'conversation.chat.turnTail'>
+  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.tool' | 'conversation.chat.commandview' | 'conversation.chat.turnTail'>
   & PropsStore<ChatStore> & ChatViewInjected & PropsLocale<'conversation'>
 
 /**
@@ -535,8 +528,9 @@ export interface DetailsInjected {
   closeDetails: () => void
 }
 
-/** Full details-slot component props: selection rides the shared store, call material useSession; copy the locale seat. */
-export type DetailsSlotProps = PropsRuntime<'details'> & PropsStore<ChatStore> & DetailsInjected & PropsLocale<'conversation'>
+/** Full details-slot props: selection store, Tool output seat, injected close callback, and locale. */
+export type DetailsSlotProps = PropsRuntime<'details'> & PropsRenderSlots<'conversation.details.tool'>
+  & PropsStore<ChatStore> & DetailsInjected & PropsLocale<'conversation'>
 
 /** Owner share common to the hero / New-Session Workspace pickers. */
 export interface EmptyWorkspaceOwnerProps {
diff --git a/packages/client/ui-conversation/src/client/contract/tool-path.ts b/packages/client/ui-conversation/src/client/contract/tool-path.ts
new file mode 100644
index 0000000000..38a55937d3
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/contract/tool-path.ts
@@ -0,0 +1,15 @@
+/** Resolve a Tool argument path against the session workspace. */
+
+/**
+ * Resolve a Tool argument path for the Host opener.
+ * @param cwd - session workspace root, when known.
+ * @param path - path carried by the Tool arguments.
+ * @returns an absolute-or-workspace-relative Host path.
+ */
+export function resolveToolPath(cwd: string | undefined, path: string): string {
+  if (path.startsWith('/') || /^[A-Za-z]:[/\\]/.test(path) || path.startsWith('\\\\')) return path
+  if (cwd === undefined || cwd === '') return path
+  const base = cwd.replace(/[/\\]+$/, '')
+  const rel = path.replace(/^[/\\]+/, '')
+  return `${base}/${rel}`
+}
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index 725868d57a..b91628b825 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -10,14 +10,13 @@ export type { IConversation } from './service.ts'
 export type {
   CallId, ChatStoreState, SelectionTarget, ViewTab,
 } from './contract/views.ts'
-export type { ToolCallBlock } from './contract/tool-call-model.ts'
 export type { ConversationKey } from './locales.ts'
 export type {
   ChatStore, ChatViewInjected, ChatViewSlotProps, CommandRowOwnerProps, CommandRowProps, ComposerBarInjected,
   ComposerChainProps, ConversationInjected,
-  ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps,
-  ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps,
-  EmptyWorkspaceOwnerProps, ToolRowOwnerProps, ToolRowProps, TurnTailOwnerProps,
+  ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps, ConvViewOwnerProps,
+  ConvViewProps, DetailsInjected, DetailsSlotProps, DetailsToolOwnerProps, EmptyWorkspaceOwnerProps,
+  ToolTreeOwnerProps, TurnTailOwnerProps,
 } from './contract/slots.ts'
 // Export discipline: packages/client/AGENTS.md.
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
index fbaebd1193..abdece3e25 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
@@ -92,36 +92,3 @@
 .code[data-error] {
   color: var(--dsw-alias-state-error-primary);
 }
-
-/* Above the card, which is where the render-intent contract puts a terminal
-   call's description; the panel has no summary row to carry it. */
-.terminalDescription {
-  margin: 0 0 6px;
-  color: var(--dsw-alias-label-secondary);
-  font: var(--dsw-font-xs-13);
-}
-
-/* A card body (terminal, diff, or search) sits directly under its section
-   label, so it drops the primitive's standalone vertical margin; the section
-   owns the spacing. Card-neutral: no card-kind-specific value. */
-.cardBody {
-  margin: 0;
-}
-
-/* The recovery footer for a capped search: the result text (its `Full … stored
-   at …` locator) below the card in the muted tone, since the card holds only the
-   retained rows. */
-.searchRecovery {
-  margin: 6px 0 0;
-  white-space: pre-wrap;
-  overflow-wrap: anywhere;
-  color: var(--dsw-alias-label-tertiary);
-  font: var(--dsw-font-xs-13);
-}
-
-/* The read and web cards sit directly under their section label, same as the
-   terminal card: drop the primitive's standalone vertical margin. */
-.read,
-.web {
-  margin: 0;
-}
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index 1114236143..c2104c23c7 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -7,16 +7,11 @@
 // share the store seat exists for) and derives the call material from the
 // session snapshot — no data of its own.
 
-import { CodeBlock, DiffBlock, ReadBlock, SearchBlock, TerminalBlock, WebBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import { Fragment } from 'react'
+import { CodeBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import { shallowEqual } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConversationSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { DetailsSlotProps } from '../contract/slots.ts'
-import { readCardModel } from '../contract/read-card-model.ts'
-import { diffCardModel } from '../contract/diff-card-model.ts'
-import { searchCardModel } from '../contract/search-card-model.ts'
-import { terminalBlockLabels, terminalCardModel } from '../contract/terminal-card-model.ts'
-import { webCardModel } from '../contract/web-card-model.ts'
-import { resultText, type ToolCallBlock } from '../contract/tool-call-model.ts'
 import css from './DetailsPanel.module.css'
 
 /** Full props composed by reference from the contract (automatic shares & injected share). */
@@ -72,7 +67,15 @@ function pretty(raw: string): string {
   }
 }
 
-export function DetailsPanel({ useSession, useSessions, sessionId, useStore, closeDetails, t }: DetailsPanelProps) {
+/** Flatten a settled result for the no-ui-tool fallback. */
+function rawResultText(block: ToolCallBlock): string {
+  if (!('kind' in block)) return ''
+  const parts = block.content.map(item => item.type === 'text' ? item.text : JSON.stringify(item, null, 2))
+  if (parts.length === 0 && block.error !== undefined) parts.push(`${block.error.name}: ${block.error.code}`)
+  return parts.join('\n')
+}
+
+export function DetailsPanel({ useSession, useSessions, sessionId, useStore, renderSlot, closeDetails, t }: DetailsPanelProps) {
   const selection = useStore(s => s.selection)
   // Session workspace root: an omitted or relative terminal cwd resolves
   // against it, which the pure presenter cannot see.
@@ -118,7 +121,17 @@ export function DetailsPanel({ useSession, useSessions, sessionId, useStore, clo
                       state (the terminal card's expand and copy), which React
                       would otherwise carry into the next selection because the
                       panel does not unmount between calls. */}
-                  <OutputBody key={callId} material={material} cwd={sessionCwd} t={t} />
+                  <Fragment key={callId}>
+                    {renderSlot('conversation.details.tool', { block: material.block, cwd: sessionCwd }, {
+                      fallback: 'kind' in material.block
+                        ? (
+                          <pre className={css.code} data-error={material.block.isError || undefined}>
+                            {rawResultText(material.block)}
+                          </pre>
+                        )
+                        : <div className={css.empty}>{t('details.running')}</div>,
+                    })}
+                  </Fragment>
                 </section>
               </>
             )}
@@ -126,83 +139,3 @@ export function DetailsPanel({ useSession, useSessions, sessionId, useStore, clo
     </div>
   )
 }
-
-/**
- * The Output section's body for the selected call. A terminal-card call — a
- * shell command's call/result views — renders through the shared TerminalBlock
- * at the primitive's own full height allowance, so column-aligned output keeps
- * its alignment and scrolls sideways instead of folding. A read-card call
- * renders through the shared ReadBlock at that same full height, so the whole
- * returned window is line-numbered and highlighted. A diff-card call — a
- * write/edit's applied change — renders through the shared DiffBlock at the same
- * full height. A search-card call — a `grep`/`glob` result view — renders
- * through the shared SearchBlock at the same full height allowance, with a
- * capped search's recovery footer below it. A web-card call — a
- * `web_search`/`web_fetch` result — renders through WebBlock at its own full
- * source-list allowance. Every other call, and a running call with no card yet,
- * keeps the flattened text form.
- * @param props.material - the selected call's material from {@link materialFor}.
- * @param props.cwd - the session workspace root, resolving the terminal view's cwd.
- * @param props.t - the panel's locale seat, passed down as a plain prop.
- * @returns the Output section's body element.
- */
-function OutputBody({ material, cwd, t }: { material: CallMaterial; cwd: string | undefined; t: DetailsPanelProps['t'] }) {
-  const terminal = terminalCardModel(material.block, cwd)
-  if (terminal !== null) {
-    // The contract renders the presenter's description above the card, and the
-    // panel has no summary row to carry it, so it is drawn here.
-    return (
-      <>
-        {terminal.description !== undefined && (
-          <div className={css.terminalDescription}>{terminal.description}</div>
-        )}
-        <TerminalBlock {...terminal.card} labels={terminalBlockLabels(t)} className={css.cardBody} />
-      </>
-    )
-  }
-  const read = readCardModel(material.block, cwd)
-  // The panel takes the primitive's own default cap, not the row's tighter one:
-  // it is the single-call reading surface, so the whole window is available.
-  if (read !== null) return <ReadBlock {...read} className={css.read} />
-  const diff = diffCardModel(material.block)
-  if (diff !== null) return <DiffBlock {...diff.card} className={css.cardBody} />
-  const search = searchCardModel(material.block)
-  if (search !== null) {
-    return (
-      <>
-        <SearchBlock {...search.card} className={css.cardBody} />
-        {/* A capped search's recovery locator lives only in the result text;
-            show it below the card so the dropped rows stay reachable. */}
-        {search.recovery !== undefined && (
-          <div className={css.searchRecovery}>{search.recovery}</div>
-        )}
-      </>
-    )
-  }
-  const web = webCardModel(material.block)
-  // The card shows every source the tool returned (the same list the model saw),
-  // scrolling within its own capped height. Below the card the panel also renders
-  // the flattened result content — the model-visible text the card does not carry
-  // verbatim (a web_fetch card shows only the URL and status, so its fetched body
-  // lives only here; a search card's answer and sources are structured, so the
-  // flattened form repeats them as the raw text the model saw).
-  if (web !== null) {
-    const settled = 'kind' in material.block ? material.block : null
-    const body = settled === null ? '' : resultText(settled)
-    return (
-      <>
-        <WebBlock {...web} className={css.web} />
-        {body !== '' && <pre className={css.code}>{body}</pre>}
-      </>
-    )
-  }
-  // A settled call always carries the result node the flattened form needs;
-  // the running shape has no result to flatten.
-  if (!('kind' in material.block)) return <div className={css.empty}>{t('details.running')}</div>
-  const result = material.block
-  return (
-    <pre className={css.code} data-error={result.isError || undefined}>
-      {resultText(result)}
-    </pre>
-  )
-}
diff --git a/packages/client/ui-conversation/src/invariant.ts b/packages/client/ui-conversation/src/invariant.ts
index f4ecd7e260..f9a7d46553 100644
--- a/packages/client/ui-conversation/src/invariant.ts
+++ b/packages/client/ui-conversation/src/invariant.ts
@@ -17,7 +17,7 @@ export const inject = ['invariants']
 /**
  * No runtime invariant: the conversation service emits no cordis events, and
  * both rings this package owns (the 'conversation.view' tab ring and the
- * 'conversation.chat.toolview' row hole) ride the slot system, whose ledger
+ * 'conversation.chat.tool' whole-call seat) ride the slot system, whose ledger
  * invariants live with the runtime slots package.
  */
 const install: InvariantInstaller = () => {}
diff --git a/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx b/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx
index 16163065eb..9ea1c937ff 100644
--- a/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx
+++ b/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx
@@ -1,35 +1,14 @@
 // @vitest-environment jsdom
-/**
- * Assembly-level acceptance on SlotTestRuntime (real apply, real slot
- * machinery, real renderer; data fed as fixtures) for surfaces that were
- * previously pinned only by the assembled-app jsdom snapshots
- * (apps/web/tests/{todo-display,terminal-card,slash-flow}.snapshot.ts):
- *
- * - the todo_write turn reaches BOTH surfaces through the product
- *   registrations (keyed toolview row in the flow, plan strip in the input
- *   dock via the 'todos' projection) and the strip follows projection
- *   retirement;
- * - the bash keyed row carries its resident terminal card, and the fallback
- *   row reaches the same card through its expand control;
- * - the resident composer textarea survives the blank→active conversion as
- *   the SAME DOM node (focus/IME continuity rides React reconciliation:
- *   component identity + tree position, which this assembled tree pins).
- *
- * Component-level behavior (collapse interaction, card model arms, summary
- * derivations) lives in todo-panel.spec.tsx / terminal-card.spec.tsx; this
- * suite only proves the assembled wiring.
- */
+/** Conversation assembly acceptance independent of Tool presentation. */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, waitFor, within } from '@testing-library/react'
 import { useState } from 'react'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
-import type { ISession, SessionId, TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ISession, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject, type EmptyWorkspaceOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
-// The service reads its initial locale from the browser; these specs assert
-// the shipped Chinese copy, so they state the browser they assume.
 usePinnedBrowserLanguages('zh-CN')
 
 const SID = 's1' as SessionId
@@ -50,30 +29,6 @@ beforeEach(() => {
   vi.stubGlobal('ResizeObserver', ResizeObserverStub)
 })
 
-const TODOS: TodoItem[] = [
-  { content: '梳理需求', status: 'completed' },
-  { content: '实现 fixture 样本', status: 'in_progress' },
-  { content: '浏览器验收', status: 'pending' },
-]
-
-const todoResult = (seq: number): ToolResultNode => ({
-  kind: 'tool-result', seq, time: seq * 1_000, callId: `todo-${seq}`,
-  call: { name: 'todo_write', argsRaw: JSON.stringify({ todos: TODOS }) },
-  callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null,
-})
-
-const bashResult = (seq: number, callId: string, over?: Partial<ToolResultNode>): ToolResultNode => ({
-  kind: 'tool-result', seq, time: seq * 1_000, callId,
-  call: { name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}' },
-  callTime: seq * 1_000 - 500,
-  content: [{ type: 'text', text: 'total 2\ndemo.txt\n' }], isError: false,
-  callView: { card: 'terminal', title: 'ls -la', description: 'List files' },
-  resultView: { card: 'terminal', output: 'total 2\ndemo.txt\n', exitCode: 0 },
-  ...over,
-})
-
-/** Test-owned AppFrame role: declares and renders the resident conversation area. */
 type AppRootProps = PropsRenderSlots<'conversation' | 'details'>
 function AppRoot({ renderSlot }: AppRootProps) {
   return <>{renderSlot('conversation', {})}</>
@@ -84,7 +39,6 @@ const LAYOUT_CHILDREN = {
   'details': { kind: 'single', scope: 'session' },
 } as const
 
-/** Stateful occupant proving the root-scoped Hero workspace outlet is not rebuilt. */
 function WorkspaceProbe({ open }: EmptyWorkspaceOwnerProps) {
   const [count, setCount] = useState(0)
   return (
@@ -94,7 +48,7 @@ function WorkspaceProbe({ open }: EmptyWorkspaceOwnerProps) {
   )
 }
 
-async function bench(nodes: ToolResultNode[], opts?: { blank?: boolean }) {
+async function bench(opts?: { blank?: boolean }) {
   const runtime = await SlotTestRuntime.create()
   runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
   const locale = new LocaleService(runtime.ctx)
@@ -104,7 +58,7 @@ async function bench(nodes: ToolResultNode[], opts?: { blank?: boolean }) {
     id: SID,
     summary: { title: 'S', displayTitle: 'S', cwd: '/proj' },
     snapshot: {
-      nodes,
+      nodes: [],
       ...(opts?.blank === true ? { blank: true, composerPhase: 'blank' as const } : {}),
     },
     session: {
@@ -117,69 +71,6 @@ async function bench(nodes: ToolResultNode[], opts?: { blank?: boolean }) {
   return runtime
 }
 
-describe('todo_write assembly (product registrations, no outlet twins)', () => {
-  it('reaches the keyed toolview row and the dock plan strip, and the strip follows projection retirement', async () => {
-    const runtime = await bench([todoResult(3)])
-    // The dock strip reads the host-computed 'todos' projection.
-    runtime.sessions.behavior(SID).projections.set('todos', TODOS)
-    const view = runtime.renderRoot()
-
-    // Keyed toolview registration took the row (summary derived from args).
-    const row = view.container.querySelector('[data-tool="todo_write"]')
-    expect(row).not.toBeNull()
-    expect(row!.textContent).toContain('1/3 已完成 · 实现 fixture 样本')
-
-    // The plan strip sits in the input dock, fed by the projection
-    // (default-collapsed: the header summary shows; rows appear on expand).
-    const panel = view.container.querySelector('[data-testid="todo-panel"]')
-    expect(panel).not.toBeNull()
-    expect(panel!.textContent).toContain('1 已完成\u2002·\u20021 进行中\u2002·\u20021 待处理')
-    fireEvent.click(panel!.querySelector('button')!)
-    expect([...panel!.querySelectorAll('li')].map(li => li.getAttribute('data-status')))
-      .toEqual(['completed', 'in_progress', 'pending'])
-
-    // Next turn retires the standing plan (host pushes null): the strip
-    // clears while the historical row stays in the flow.
-    await runtime.flush()
-    runtime.sessions.behavior(SID).projections.set('todos', null)
-    await waitFor(() => {
-      expect(view.container.querySelector('[data-testid="todo-panel"]')).toBeNull()
-    })
-    expect(view.container.querySelector('[data-tool="todo_write"]')).not.toBeNull()
-    await runtime.dispose()
-  })
-})
-
-describe('terminal card assembly', () => {
-  it('both the keyed bash row and the fallback row reach the terminal card through the whole-row expand', async () => {
-    const runtime = await bench([
-      bashResult(3, 'c-keyed'),
-      // An unregistered tool with terminal views: GenericToolCard fallback.
-      bashResult(4, 'c-fallback', { call: { name: 'fx-bash', argsRaw: '{"command":"ls -la"}' } }),
-    ])
-    const view = runtime.renderRoot()
-
-    // Keyed BashRow: collapsed by default, the whole summary row is the toggle.
-    const keyedRow = view.container.querySelector('[data-sample="bash"]')
-    const keyed = keyedRow?.parentElement
-    expect(keyed?.querySelector('[data-terminal]')).toBeNull()
-    fireEvent.click(keyedRow!)
-    await waitFor(() => {
-      expect(keyed!.querySelector('[data-terminal]')).not.toBeNull()
-    })
-
-    // Fallback row: same unified expand interaction.
-    const fallback = view.container.querySelector('[data-tool="fx-bash"]')
-    expect(fallback).not.toBeNull()
-    expect(fallback!.querySelector('[data-terminal]')).toBeNull()
-    fireEvent.click(fallback!.querySelector('[data-expandable]')!)
-    await waitFor(() => {
-      expect(fallback!.querySelector('[data-terminal]')).not.toBeNull()
-    })
-    await runtime.dispose()
-  })
-})
-
 describe('resident composer', () => {
   it('renders the locked view state while no session exists at all', async () => {
     const runtime = await SlotTestRuntime.create()
@@ -190,8 +81,6 @@ describe('resident composer', () => {
     await runtime.root.declare(LAYOUT_CHILDREN, AppRoot)
     await runtime.mount({ inject: [...inject], apply })
     const view = runtime.renderRoot()
-    // No session entity: the inert twin renders (disabled textarea), and the
-    // workspace picker chip is the only live control.
     const textarea = view.container.querySelector('textarea')
     expect(textarea).not.toBeNull()
     expect(textarea!.disabled).toBe(true)
@@ -242,12 +131,8 @@ describe('resident composer', () => {
     await runtime.dispose()
   })
 
-
   it('the textarea survives the blank→active conversion as the same DOM node', async () => {
-    const runtime = await bench([], { blank: true })
-    // The hero renders the LIVE composer only when the blank session's
-    // workspace resolves a chip title; an ownerless blank session shows the
-    // disabled twin instead (deleted-workspace semantics).
+    const runtime = await bench({ blank: true })
     await runtime.workspaces.update((draft) => {
       draft.items = [{ workspaceId: 'w1', title: 'Proj', path: '/proj', sessionIds: [SID] }] as never
     })
@@ -256,13 +141,11 @@ describe('resident composer', () => {
     expect(hero).not.toBeNull()
     expect(hero!.disabled).toBe(false)
 
-    // First acceptance: the session leaves blank and the composer docks.
     await runtime.sessions.updateSnapshot(SID, (draft) => {
       draft.blank = false
       draft.composerPhase = 'active'
     })
-    const docked = view.container.querySelector('textarea')
-    expect(docked).toBe(hero)
+    expect(view.container.querySelector('textarea')).toBe(hero)
     await runtime.dispose()
   })
 })
@@ -291,8 +174,6 @@ describe('prompt rejection through the assembled composer', () => {
     fireEvent.keyDown(composer, { key: 'Enter' })
     await waitFor(() => { expect(prompt).toHaveBeenCalledOnce() })
 
-    // The rejection lands in snapshot.promptError (the Session's own path);
-    // the fixture mirrors that hop — the assembled InputBar renders it.
     await runtime.sessions.updateSnapshot(SID, (draft) => {
       draft.promptError = {
         op: 'send',
@@ -301,7 +182,6 @@ describe('prompt rejection through the assembled composer', () => {
     })
     const alert = await view.findByRole('alert')
     expect(alert.textContent).toContain('prompt rejected before acceptance (agent-busy)')
-    // Failure restore: the machine returned the draft to the same textarea.
     await waitFor(() => {
       expect((view.container.querySelector('textarea'))!.value).toBe('do not lose this')
     })
@@ -311,7 +191,7 @@ describe('prompt rejection through the assembled composer', () => {
 
 describe('title projection across assembled surfaces', () => {
   it('one summary update re-labels the current-session crumb', async () => {
-    const runtime = await bench([])
+    const runtime = await bench()
     const view = runtime.renderRoot()
     const hierarchy = view.getByRole('navigation', { name: '会话层级' })
     expect(within(hierarchy).getByRole('button', { name: 'S' }).hasAttribute('disabled')).toBe(true)
diff --git a/packages/client/ui-conversation/tests/chat-apply.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
index df8fff6719..00001275d2 100644
--- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
@@ -1,12 +1,9 @@
 // @vitest-environment jsdom
 // apply wiring: the conversation service provided, the chat view registered
-// as the first 'conversation.view' ring entry declaring the keyed toolview
-// hole, the slot registrations land against a root entry's children
-// declarations (the AppFrame role), the shared store handle rides all strict
-// session entries, and the bash sample + todo row mount through declaration
-// injection as keyed entries. Full-chain rendering belongs to the
-// machinery spec (chat-toolview-slot.spec.tsx) and the shell e2e; this spec
-// stops at the assembly surface.
+// as the first 'conversation.view' ring entry declaring the whole-Tool seat,
+// the slot registrations land against a root entry's children declarations
+// (the AppFrame role), and the shared store handle rides all strict session
+// entries. Tool composition belongs to ui-tool and its machinery spec.
 
 import { describe, expect, it, vi } from 'vitest'
 import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
@@ -56,7 +53,7 @@ describe('apply wiring', () => {
     await b.runtime.dispose()
   })
 
-  it('registers the chat view as the first ring entry, declaring the keyed toolview hole', async () => {
+  it('registers the chat view as the first ring entry, declaring the whole-Tool seat', async () => {
     const b = await bench()
     const entries = b.slots.entries('conversation.view')
     expect(entries.map(e => e.options.id)).toEqual(['chat'])
@@ -65,7 +62,7 @@ describe('apply wiring', () => {
     expect(entries[0]?.options.order).toBe(0)
     // Declaring is claiming: the chat entry's registration put the hole on
     // the ledger with the contract's kind/scope.
-    expect(b.slots.spec('conversation.chat.toolview')).toEqual({ kind: 'keyed', scope: 'session' })
+    expect(b.slots.spec('conversation.chat.tool')).toEqual({ kind: 'single', scope: 'session' })
     await b.runtime.dispose()
   })
 
@@ -92,14 +89,13 @@ describe('apply wiring', () => {
     await b.runtime.dispose()
   })
 
-  it('mounts the tool rows as keyed entries through declaration injection', async () => {
+  it('leaves per-Tool rows to the ui-tool plugin', async () => {
     const b = await bench()
     // The actual toolview declaration activates every registrant. The
     // file-mutation registrant claims both write and edit for the diff card; the
     // one search row registers under both grep and glob; the web rows register
     // one component under both web tool names.
-    const entries = b.slots.entries('conversation.chat.toolview')
-    expect(entries.map(e => e.options.key)).toEqual(['bash', 'read', 'edit', 'write', 'grep', 'glob', 'web_search', 'web_fetch', 'todo_write', 'ask_user_question'])
+    expect(b.slots.entries('conversation.chat.tool')).toHaveLength(0)
     // Stats stick with the composer (not inside ChatView).
     expect(b.slots.entries('conversation.composer.dock').map(e => e.options.id)).toEqual(['stats'])
     await b.runtime.dispose()
@@ -112,8 +108,8 @@ describe('apply wiring', () => {
     // The declared ring collapses with its declaring entry, and the chat
     // entry's keyed hole (with the sample's registration) collapses with it.
     expect(b.slots.entries('conversation.view')).toHaveLength(0)
-    expect(b.slots.entries('conversation.chat.toolview')).toHaveLength(0)
-    expect(b.slots.spec('conversation.chat.toolview')).toBeUndefined()
+    expect(b.slots.entries('conversation.chat.tool')).toHaveLength(0)
+    expect(b.slots.spec('conversation.chat.tool')).toBeUndefined()
     expect(b.slots.entries('details')).toHaveLength(0)
     expect(b.slots.entries('settings.general.item')).toHaveLength(0)
     expect(b.runtime.ctx.get('conversation')).toBeUndefined()
diff --git a/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx b/packages/client/ui-conversation/tests/chat-stats.spec.tsx
similarity index 87%
rename from packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx
rename to packages/client/ui-conversation/tests/chat-stats.spec.tsx
index 7187851420..cdb0ffa8c9 100644
--- a/packages/client/ui-conversation/tests/chat-stats-bash-sample.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-stats.spec.tsx
@@ -1,26 +1,21 @@
 // @vitest-environment jsdom
-// StatsLine (composer.dock entry): totals derivation + the RFC
-// hard acceptance — zero renders during streaming. Bash sample row: ToolRow
-// chrome (Bash · description) without a row click target.
+// StatsLine (composer.dock entry): totals derivation + the RFC hard
+// acceptance — zero renders during streaming.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import type {
-  AssistantMessageNode, ConversationSnapshot, SessionId, SessionListState, ToolResultNode,
+  AssistantMessageNode, ConversationSnapshot, SessionId, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { StatsLine, contextOccupancy, deriveStats, formatDuration, formatTokens, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
-import { BashRow } from '../src/client/toolviews/bash-sample.tsx'
 import { en, zh } from '../src/client/locales.ts'
 
-type BashRowProps = Parameters<typeof BashRow>[0]
-
 // Mirrors the real lookup chain (conversation namespace, then common).
-const t: BashRowProps['t'] = makeTranslate(zh, commonZh)
+const t: StatsLineProps['t'] = makeTranslate(zh, commonZh)
 const tEn: StatsLineProps['t'] = makeTranslate(en, commonEn)
 
 /** jsdom has no ResizeObserver; StatsLine watches its row for ellipsis truncation through one. */
@@ -301,43 +296,3 @@ describe('StatsLine', () => {
     expect(renders).toBe(before)
   })
 })
-
-describe('bash sample row', () => {
-  const SID = 'root-1' as SessionId
-
-  const result = (callId: string): ToolResultNode => ({
-    kind: 'tool-result', seq: 3, time: 3_000, callId,
-    call: { name: 'bash', argsRaw: '{"command":"make build","description":"Build"}' },
-    callTime: 2_000,
-    content: [], isError: false, callView: null, resultView: null,
-  })
-
-  function listStore() {
-    return createSnapshotStore<SessionListState>({
-      ids: [SID],
-      byId: {
-        [SID]: { id: SID, title: 'r', displayTitle: 'r', running: false, blank: false, updatedAt: 0 },
-      },
-      current: undefined,
-      phase: 'ready',
-      subagentsByParent: {},
-      currentAddress: undefined,
-    })
-  }
-
-  const rowProps = (): BashRowProps => ({
-    callId: 'c1', toolName: 'bash', block: result('c1'),
-    openFile: vi.fn(),
-    sessionId: SID,
-    useSessions: bindSnapshotSelector(listStore()),
-    t,
-  } as unknown as BashRowProps)
-
-  it('summarizes as Bash · description without a row click target', () => {
-    const view = render(<BashRow {...rowProps()} />)
-    const row = view.container.querySelector('[data-sample="bash"]')!
-    expect(row.textContent).toContain('Bash')
-    expect(row.textContent).toContain('Build')
-    expect(row.getAttribute('data-clickable')).toBeNull()
-  })
-})
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index f42aed6731..0a25e9b198 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 // ChatView behavior: flow derivation, streaming isolation (Profiler counts),
-// toolview dispatch and selection handoff — driven through a scripted
-// ObservableSnapshot fake, no wire.
+// Tool seat ownership and selection handoff — driven through a scripted
+// ObservableSnapshot fake, no wire or Tool presentation plugin.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Profiler } from 'react'
@@ -14,7 +14,7 @@ import type {
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { createSnapshotStore, PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
-import type { ChatViewSlotProps, SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ChatViewSlotProps, SelectionTarget, ToolTreeOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { createChatStore } from '../src/client/stores.ts'
@@ -137,12 +137,25 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
   const forkAt = vi.fn()
   // Selection rides the REAL chat store (same construction path as
   // production; the view reads it through the PropsStore useStore share).
-  // renderSlot stub renders the render-site fallback (an empty keyed ledger:
-  // every tool lands on GenericToolCard); keyed dispatch to registered rows
-  // is the slot machinery's behavior, covered by its own specs.
   const chat = createChatStore().create()
-  const renderSlot = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
-    opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlot']
+  const t = makeTranslate(zh, commonZh)
+  const toolOwners: ToolTreeOwnerProps[] = []
+  const renderSlot = ((key: string, owner: object, opts?: { fallback?: React.ReactNode }) => {
+    if (key !== 'conversation.chat.tool') return opts?.fallback ?? null
+    const tool = owner as ToolTreeOwnerProps
+    toolOwners.push(tool)
+    // Tool providers own their subtree. The host double carries only the
+    // semantic anchor required by ChatView's prepend-position contract.
+    return (
+      <div
+        data-testid={`tool-seat-${tool.callId}`}
+        data-chat-anchor-key={`call:${tool.callId}`}
+        data-chat-call-id={tool.callId}
+      >
+        {tool.toolName || '(unnamed)'}:{tool.callId}
+      </div>
+    )
+  }) as unknown as ChatViewSlotProps['renderSlot']
   const renderSlotChain = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
     opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlotChain']
   // SessionProvider seat arrives with the session-scope child declaration;
@@ -168,10 +181,13 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     chatScroll,
     forkAt,
     // Mirrors the real lookup chain (conversation namespace, then common).
-    t: makeTranslate(zh, commonZh),
+    t,
   }
   const setSelection = (next: SelectionTarget | null): void => { chat.actions.select(next) }
-  return { set, ChatView, props, openDetails, openFile, loadOlder, inspectCall, chatScroll, forkAt, setSelection }
+  return {
+    set, ChatView, props, openDetails, openFile, loadOlder, inspectCall,
+    chatScroll, forkAt, setSelection, toolOwners,
+  }
 }
 
 /** Simulate reader input (any device): a delivered position that deviates
@@ -374,14 +390,13 @@ describe('chat-flow derivation', () => {
 })
 
 describe('ChatView', () => {
-  it('a windowless tool result (call head truncated) renders with an empty tool name', () => {
+  it('hands a windowless tool result to the Tool seat with an empty tool name', () => {
     const h = makeHarness({
       nodes: [{ ...toolResult(3, 'w1'), call: null }],
     })
     const view = render(<h.ChatView {...h.props} />)
-    // classifyTool('') → others; the summary slot falls back to the callId.
-    expect(view.container.querySelector('[data-variant="others"]')).not.toBeNull()
-    expect(view.getByText('w1')).toBeTruthy()
+    expect(view.getByTestId('tool-seat-w1')).toBeTruthy()
+    expect(h.toolOwners[0]).toMatchObject({ callId: 'w1', toolName: '' })
   })
 
   it('prepend keeps the reader\'s latest pending-request scroll position anchored', () => {
@@ -423,8 +438,8 @@ describe('ChatView', () => {
     const view = render(<h.ChatView {...h.props} />)
     expect(view.getByText('do the thing')).toBeTruthy()
     expect(view.getByText('running tools')).toBeTruthy()
-    expect(view.getAllByText('Bash')).toHaveLength(2)
-    expect(view.getByText('run a')).toBeTruthy()
+    expect(view.getByTestId('tool-seat-a').textContent).toBe('bash:a')
+    expect(view.getByTestId('tool-seat-b').textContent).toBe('bash:b')
     expect([...view.container.querySelectorAll('[data-chat-flow-key]')].map(row => ({
       key: row.getAttribute('data-chat-flow-key'),
       kind: row.getAttribute('data-chat-flow-kind'),
@@ -590,14 +605,12 @@ describe('ChatView', () => {
     ])
   })
 
-  it('the expanded row Inspect pill hands the call id to inspectCall', () => {
+  it('hands the trajectory callback to the Tool seat', () => {
     const h = makeHarness({
       nodes: [toolResult(3, 'a')],
     })
-    const view = render(<h.ChatView {...h.props} />)
-    fireEvent.click(view.getByRole('button', { name: /Bash/ }))
-    fireEvent.click(view.getByText('Inspect'))
-    expect(h.inspectCall).toHaveBeenCalledWith('a')
+    render(<h.ChatView {...h.props} />)
+    expect(h.toolOwners[0]?.inspectCall).toBe(h.inspectCall)
   })
 
   it('shows assistant IconActions only on the last content message of each turn', () => {
@@ -822,7 +835,7 @@ describe('ChatView', () => {
     // not re-render, so the row's renderSlot call count freezes during chunks.
     let rowRenders = 0
     h.props.renderSlot = ((key: string, _owner: object) => {
-      if (key !== 'conversation.chat.toolview') return null
+      if (key !== 'conversation.chat.tool') return null
       rowRenders += 1
       return <div data-testid="counting-row" />
     })
@@ -838,44 +851,19 @@ describe('ChatView', () => {
     expect(rowRenders).toBe(afterMount)
   })
 
-  it('tool row expands to the args body via the whole-row toggle', () => {
+  it('updates the selected call id handed to the Tool seat', () => {
     const h = makeHarness({ nodes: [toolResult(3, 'a')] })
-    const view = render(<h.ChatView {...h.props} />)
-    expect(view.queryByText(/"command": "cmd-a"/)).toBeNull()
-    fireEvent.click(view.container.querySelector('[data-expandable]')!)
-    expect(view.getByText(/"command": "cmd-a"/)).toBeTruthy()
-  })
-
-  it('clicking a bash summary does not open details; selection still marks data-selected', () => {
-    const h = makeHarness({ nodes: [toolResult(3, 'a')] })
-    const view = render(<h.ChatView {...h.props} />)
-    fireEvent.click(view.getByText('run a'))
-    expect(h.openDetails).not.toHaveBeenCalled()
-    expect(h.openFile).not.toHaveBeenCalled()
-    expect(view.container.querySelector('[data-selected]')).toBeNull()
+    render(<h.ChatView {...h.props} />)
+    expect(h.toolOwners.at(-1)?.selectedCallId).toBeUndefined()
     act(() => { h.setSelection({ turnSeq: 3, callId: 'a', toolName: 'bash' }) })
-    expect(view.container.querySelector('[data-selected]')).not.toBeNull()
+    expect(h.toolOwners.at(-1)?.selectedCallId).toBe('a')
   })
 
-  it('clicking a file-tool path summary opens the host file, not details', () => {
-    const h = makeHarness({
-      nodes: [{
-        kind: 'tool-result', seq: 3, time: 3_000, callId: 'r1',
-        call: { name: 'read', argsRaw: '{"path":"src/a.ts"}' },
-        callTime: 2_500, content: [], isError: false, callView: null, resultView: null,
-      }],
-    })
-    const view = render(<h.ChatView {...h.props} />)
-    fireEvent.click(view.getByText('src/a.ts'))
-    expect(h.openFile).toHaveBeenCalledWith('src/a.ts')
-    expect(h.openDetails).not.toHaveBeenCalled()
-  })
-
-  it('running calls render as a live tool group with the running state', () => {
+  it('hands running calls to a live Tool group', () => {
     const h = makeHarness({ runningCalls: [runningCall('r1')], running: true })
     const view = render(<h.ChatView {...h.props} />)
-    expect(view.container.querySelector('[data-state="running"]')).not.toBeNull()
-    expect(view.getByText('cmd-r1')).toBeTruthy()
+    expect(view.getByTestId('tool-seat-r1')).toBeTruthy()
+    expect(h.toolOwners[0]?.block).toMatchObject({ callId: 'r1', argsRaw: '{"command":"cmd-r1"}' })
     expect(view.getByRole('status').textContent).toBe('Deep diving...')
   })
 
@@ -903,19 +891,25 @@ describe('ChatView', () => {
     expect(status.textContent).toMatch(/^Deep diving\.\.\.2分0\d秒$/)
   })
 
-  it('dispatches each tool row through the keyed slot with the tool name as entryKey', () => {
-    const h = makeHarness({ nodes: [toolResult(3, 'a')] })
-    const calls: { key: string; entryKey?: string }[] = []
-    h.props.renderSlot = ((key: string, _owner: object, opts?: { entryKey?: string; fallback?: React.ReactNode }) => {
-      calls.push({ key, ...(opts?.entryKey !== undefined ? { entryKey: opts.entryKey } : {}) })
+  it('hands each ordered root call to the whole-Tool slot', () => {
+    const block = toolResult(3, 'a')
+    const h = makeHarness({ nodes: [block] })
+    const calls: { key: string; owner: object; entryKey?: string }[] = []
+    h.props.renderSlot = ((key: string, owner: object, opts?: { entryKey?: string; fallback?: React.ReactNode }) => {
+      calls.push({ key, owner, ...(opts?.entryKey !== undefined ? { entryKey: opts.entryKey } : {}) })
       return opts?.fallback ?? null
     })
     render(<h.ChatView {...h.props} />)
-    // Keyed dispatch: slot name is the declared hole, entryKey the wire tool
-    // name, and the fallback (GenericToolCard) renders on an empty ledger.
-    // (Registered-row takeover and live unload are slot machinery behavior,
-    // owned by the slot system's own specs.)
-    expect(calls).toEqual([{ key: 'conversation.chat.toolview', entryKey: 'bash' }])
+    expect(calls).toHaveLength(1)
+    expect(calls[0]).toMatchObject({
+      key: 'conversation.chat.tool',
+      owner: { callId: 'a', toolName: 'bash', selectedCallId: undefined },
+    })
+    const owner = calls[0]?.owner as ToolTreeOwnerProps
+    expect(owner.block).toBe(block)
+    expect(owner.openFile).toBe(h.openFile)
+    expect(owner.inspectCall).toBe(h.inspectCall)
+    expect(calls[0]?.entryKey).toBeUndefined()
   })
 
   it('prepend preserves a semantic row; a trailing user node force-scrolls', () => {
diff --git a/packages/client/ui-conversation/tests/coverage-tails.spec.tsx b/packages/client/ui-conversation/tests/coverage-tails.spec.tsx
index c92e43db6c..88e6c04141 100644
--- a/packages/client/ui-conversation/tests/coverage-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/coverage-tails.spec.tsx
@@ -1,26 +1,17 @@
 // @vitest-environment jsdom
-// Branch tails the acceptance specs do not reach: ToolRow stopped-state dot,
-// bash sample state dots, the node-half empty apply, and AssistantMarkdown
-// reasoning/unknown block arms.
+// Branch tails the acceptance specs do not reach: the node-half empty apply
+// and AssistantMarkdown reasoning/unknown block arms.
 
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-import type { RunningToolCall, SessionId, SessionListState, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { apply as nodeApply } from '../src/index.ts'
-import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx'
-import { ToolRow } from '../src/client/chat/ToolRow.tsx'
-import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
-import { BashRow } from '../src/client/toolviews/bash-sample.tsx'
+import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/chat/AssistantMarkdown.tsx'
 import { zh } from '../src/client/locales.ts'
 
-type BashRowProps = Parameters<typeof BashRow>[0]
-
 // Mirrors the real lookup chain (conversation namespace, then common).
-const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
+const t: AssistantMarkdownProps['t'] = makeTranslate(zh, commonZh)
 
 afterEach(cleanup)
 
@@ -29,14 +20,6 @@ describe('tails', () => {
     expect(() => { nodeApply() }).not.toThrow()
   })
 
-  it('ToolRow stopped state renders the warning dot in the leading slot', () => {
-    const view = render(
-      <ToolRow t={t} variant="bash" icon={<i data-testid="icon" />} title="Bash" summary="s" body={null} state="stopped" />,
-    )
-    expect(view.queryByTestId('icon')).toBeNull()
-    expect(view.container.querySelector('[data-state="stopped"]')).not.toBeNull()
-  })
-
   it('AssistantMarkdown renders reasoning as a Think row and unknown blocks as JSON fallback', () => {
     const view = render(
       <AssistantMarkdown
@@ -73,67 +56,4 @@ describe('tails', () => {
     expect(blank.container.firstChild).toBeNull()
   })
 
-  it('a settled others-variant row renders the sparkle icon in the leading slot', () => {
-    const settled: ToolResultNode = {
-      kind: 'tool-result', seq: 2, time: 2_000, callId: 'c5',
-      call: { name: 'todo_write', argsRaw: '{"note":"x"}' },
-      callTime: 1_000,
-      content: [], isError: false, callView: null, resultView: null,
-    }
-    const props: GenericToolCardProps = {
-      callId: 'c5', toolName: 'todo_write', block: settled, openFile: vi.fn(), t,
-    }
-    const view = render(<GenericToolCard {...props} />)
-    // Settled ok state keeps the variant icon (sparkle) instead of a StateDot.
-    expect(view.container.querySelector('[data-variant="others"] svg')).not.toBeNull()
-    expect(view.container.querySelector('[data-state="ok"]')).not.toBeNull()
-  })
-
-  it('BashRow carries data-state for running (row sweep) and StateDots for error/stopped', () => {
-    const sid = 'root-1' as SessionId
-    const list = createSnapshotStore<SessionListState>({
-      ids: [sid],
-      byId: { [sid]: { id: sid, title: 'r', displayTitle: 'r', running: false, blank: false, updatedAt: 0 } },
-      current: undefined,
-      phase: 'ready',
-      subagentsByParent: {},
-      currentAddress: undefined,
-    })
-    const props = (block: RunningToolCall | ToolResultNode) => ({
-      callId: 'c1', toolName: 'bash', block, openFile: vi.fn(),
-      sessionId: sid, useSessions: bindSnapshotSelector(list),
-      t,
-    } as unknown as BashRowProps)
-
-    const running: RunningToolCall = {
-      callId: 'c1', name: 'bash', argsRaw: '{"command":"ls","description":"List"}',
-      turn: 1, step: 1, time: 1_000, callView: null,
-    }
-    const errorResult: ToolResultNode = {
-      kind: 'tool-result', seq: 1, time: 1_000, callId: 'c1',
-      call: { name: 'bash', argsRaw: '{"command":"boom"}' },
-      callTime: 500,
-      content: [], isError: true, callView: null, resultView: null,
-    }
-    const stoppedResult: ToolResultNode = {
-      ...errorResult,
-      error: { name: 'E', code: 'interrupted' },
-    }
-
-    const runningView = render(<BashRow {...props(running)} />)
-    expect(runningView.container.querySelector('[data-state="running"]')).not.toBeNull()
-    expect(runningView.getByText('Bash')).toBeTruthy()
-    expect(runningView.getByText('List')).toBeTruthy()
-    runningView.unmount()
-
-    const errorView = render(<BashRow {...props(errorResult)} />)
-    expect(errorView.container.querySelector('[data-sample="bash"]')).not.toBeNull()
-    expect(errorView.container.querySelector('[data-state="error"]')).not.toBeNull()
-    expect(errorView.getByText('失败')).toBeTruthy()
-    errorView.unmount()
-
-    const stoppedView = render(<BashRow {...props(stoppedResult)} />)
-    expect(stoppedView.container.querySelector('[data-state="stopped"]')).not.toBeNull()
-    expect(stoppedView.getByText('已停止')).toBeTruthy()
-  })
 })
diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
index 5adb4d817e..eacd2a754a 100644
--- a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
@@ -6,7 +6,8 @@ import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
 import type { ConversationSnapshot, SessionId, SessionListState, WorkspaceListState } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { SessionProviderComponent } from '@deepseek-ai/dsh-client-ui-slots'
+import type { DetailsSlotProps, DetailsToolOwnerProps, SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { createChatStore } from '../src/client/stores.ts'
@@ -33,6 +34,17 @@ afterEach(() => {
 
 const SID = 's1' as SessionId
 
+/** Minimal framework seat for direct DetailsPanel host tests. */
+const SessionProviderStub: SessionProviderComponent = ({ children }) => children(SID)
+
+/** Observe the owner currency without importing the Tool details renderer. */
+function renderToolDetailsProbe(owners?: DetailsToolOwnerProps[]): DetailsSlotProps['renderSlot'] {
+  return (_key, owner) => {
+    owners?.push(owner as DetailsToolOwnerProps)
+    return <div data-testid="tool-details-seat" />
+  }
+}
+
 function snapshotBase(): ConversationSnapshot {
   return {
     sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
@@ -95,6 +107,8 @@ describe('render branch tails', () => {
     })
     const view = render(
       <DetailsPanel
+        SessionProvider={SessionProviderStub}
+        renderSlot={renderToolDetailsProbe()}
         sessionId={SID}
         useSession={bindSnapshotSelector({ getSnapshot: () => snap, subscribe: () => () => {} })}
         useSessions={bindSnapshotSelector(emptyList)}
@@ -130,8 +144,11 @@ describe('render branch tails', () => {
       items: [], archivedSessionIds: [], state: 'idle', phase: 'ready', error: null,
       baselinesReady: true, recentWorkspaceId: undefined,
     })
+    const owners: DetailsToolOwnerProps[] = []
     const view = render(
       <DetailsPanel
+        SessionProvider={SessionProviderStub}
+        renderSlot={renderToolDetailsProbe(owners)}
         sessionId={SID}
         useSession={bindSnapshotSelector({ getSnapshot: () => snap, subscribe: () => () => {} })}
         useSessions={bindSnapshotSelector(emptyList)}
@@ -145,10 +162,15 @@ describe('render branch tails', () => {
         t={t}
       />,
     )
-    // Sub-call material: the sub-tool name titles the panel, args pretty-print,
-    // and the COMPLETE logged output renders (no truncation anywhere).
+    // Conversation resolves the selected sub-call and hands its complete
+    // frozen block to the Tool-owned details seat.
     expect(view.getByText('read')).toBeTruthy()
-    expect(view.getByText(/notes\/demo\.txt/)).toBeTruthy()
-    expect(view.getByText(longText)).toBeTruthy()
+    expect(view.getByTestId('tool-details-seat')).toBeTruthy()
+    expect(owners).toHaveLength(1)
+    expect(owners[0]?.block).toMatchObject({
+      callId: 'p1:code:1',
+      call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
+      content: [{ type: 'text', text: longText }],
+    })
   })
 })
diff --git a/packages/client/ui-conversation/tests/todo-panel.spec.tsx b/packages/client/ui-conversation/tests/todo-panel.spec.tsx
index 3ab95168a7..445d8139e6 100644
--- a/packages/client/ui-conversation/tests/todo-panel.spec.tsx
+++ b/packages/client/ui-conversation/tests/todo-panel.spec.tsx
@@ -1,30 +1,20 @@
 // @vitest-environment jsdom
 /**
  * Todo display acceptance: the TodoPanel plan strip (empty-hidden, status rows
- * including several `in_progress` at once, collapse), its TodoDock adapter
- * (selects the plan off the session snapshot and follows changes), the row's
- * plan summary (counts plus the two halves of the active summary — the named
- * task and the `+N` count that parallel work adds, kept apart so the row never
- * ellipsizes the count away), and the todo_write toolview row (progress summary
- * from args, generic fallback on malformed JSON, shared ToolRow state dots and
- * leading expansion).
+ * including several `in_progress` at once, collapse), and its TodoDock
+ * adapter (selects the plan off the session snapshot and follows changes).
  */
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import type { TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { TodoItem } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-// Export discipline: packages/client/AGENTS.md.
-import { TodoRow, todoToolview } from '../src/client/toolviews/todo-row.tsx'
 import type { TodoDockProps } from '../src/client/skeleton/TodoPanel.tsx'
 import { TodoDock, TodoPanel, todoDockEntry } from '../src/client/skeleton/TodoPanel.tsx'
-import { planSummary } from '../src/client/toolviews/plan-summary.ts'
 import { NS, zh } from '../src/client/locales.ts'
 
-type TodoRowProps = Parameters<typeof TodoRow>[0]
-
 // Mirrors the real lookup chain (conversation namespace, then common).
 const t: TodoDockProps['t'] = makeTranslate(zh, commonZh)
 
@@ -45,40 +35,6 @@ const PARALLEL: TodoItem[] = [
   { content: '补测试', status: 'pending' },
 ]
 
-describe('planSummary', () => {
-  it('counts done/total and names the single active item with no extra count', () => {
-    expect(planSummary(LIST)).toEqual({ done: 1, total: 3, activeContent: '写组件', activeExtra: 0 })
-  })
-
-  it('reports the extra active count separately when several items are in progress', () => {
-    // Parallel work marks several: naming one and hiding the rest would lose
-    // them, and the count stays unjoined so the row cannot ellipsize it.
-    expect(planSummary(PARALLEL)).toEqual({ done: 1, total: 5, activeContent: '写组件', activeExtra: 2 })
-  })
-
-  it('has no hint when nothing is in progress', () => {
-    expect(planSummary([{ content: '都完了', status: 'completed' }]))
-      .toEqual({ done: 1, total: 1, activeContent: null, activeExtra: 0 })
-  })
-
-  it('has no hint when the first active item carries no usable content (model JSON)', () => {
-    // Unvalidated args: a missing, mistyped, empty, or whitespace-only content
-    // yields no hint — and no orphan count, even with a second active item to
-    // count. Whitespace-only is the tool's own rejection rule (trimmed
-    // non-empty), and a rejected call keeps its args verbatim.
-    expect(planSummary([{ status: 'in_progress' }, { content: 'x', status: 'in_progress' }]))
-      .toMatchObject({ activeContent: null, activeExtra: 0 })
-    expect(planSummary([{ content: 42, status: 'in_progress' }]).activeContent).toBeNull()
-    expect(planSummary([{ content: '', status: 'in_progress' }]).activeContent).toBeNull()
-    expect(planSummary([{ content: '   ', status: 'in_progress' }, { content: 'x', status: 'in_progress' }]))
-      .toMatchObject({ activeContent: null, activeExtra: 0 })
-  })
-
-  it('is empty-safe', () => {
-    expect(planSummary([])).toEqual({ done: 0, total: 0, activeContent: null, activeExtra: 0 })
-  })
-})
-
 describe('TodoPanel', () => {
   it('renders nothing while the list is empty', () => {
     const { container } = render(<TodoPanel todos={[]} t={t} />)
@@ -178,110 +134,3 @@ describe('TodoDock', () => {
     expect(register).toHaveBeenCalledWith({ name: 'conversation.input.dock', id: 'todo', order: 0, locale: NS }, TodoDock)
   })
 })
-
-const resultNode = (argsRaw: string, over?: Partial<ToolResultNode>): ToolResultNode => ({
-  kind: 'tool-result', seq: 10, time: 2_000, callTime: 1_000, callId: 'c1',
-  call: { name: 'todo_write', argsRaw },
-  content: [], isError: false, callView: null, resultView: null, ...over,
-})
-
-function rowProps(block: unknown): TodoRowProps {
-  return {
-    callId: 'c1', toolName: 'todo_write', block,
-    openFile: vi.fn(),
-    sessionId: 's1',
-    useSessions: () => undefined,
-    t,
-  } as unknown as TodoRowProps
-}
-
-describe('TodoRow', () => {
-  const ARGS = JSON.stringify({ todos: LIST })
-
-  it('summarizes counts and the active item from the call args', () => {
-    render(<TodoRow {...rowProps(resultNode(ARGS))} />)
-    expect(screen.getByText('更新任务清单')).toBeTruthy()
-    expect(screen.getByText('1/3 已完成 · 写组件')).toBeTruthy()
-  })
-
-  it('reports the extra active count outside the ellipsized summary text', () => {
-    const { container } = render(<TodoRow {...rowProps(resultNode(JSON.stringify({ todos: PARALLEL })))} />)
-    const text = screen.getByText('1/5 已完成 · 写组件')
-    const extra = screen.getByText('+2')
-    // Separate spans: .summary truncates, the count must not travel inside it.
-    expect(text.contains(extra)).toBe(false)
-    expect(container.textContent).toContain('1/5 已完成 · 写组件+2')
-  })
-
-  it('omits the active clause when no item is in progress and reads running-call args', () => {
-    const args = JSON.stringify({ todos: [{ content: 'x', status: 'completed' }] })
-    render(<TodoRow {...rowProps({ callId: 'c1', name: 'todo_write', argsRaw: args, turn: 1, step: 1, time: 1_000, callView: null })} />)
-    expect(screen.getByText('1/1 已完成')).toBeTruthy()
-  })
-
-  it('keeps the counts when an active item has unusable content, instead of the generic summary', () => {
-    // planSummary yields activeContent null here, but the counts are known good,
-    // so the row drops only the active clause — `?? model.summary` never runs.
-    const args = JSON.stringify({ todos: [{ content: 'done', status: 'completed' }, { content: 42, status: 'in_progress' }] })
-    const { container } = render(<TodoRow {...rowProps(resultNode(args))} />)
-    expect(screen.getByText('1/2 已完成')).toBeTruthy()
-    expect(container.textContent).not.toContain('+')
-  })
-
-  it('keeps the non-ok execution states visible through the shared row states', () => {
-    // A running call (no result yet) carries the running state (row sweep).
-    const args = JSON.stringify({ todos: LIST })
-    const running = render(<TodoRow {...rowProps({ callId: 'c1', name: 'todo_write', argsRaw: args, turn: 1, step: 1, time: 1_000, callView: null })} />)
-    expect(running.container.querySelector('[data-state="running"]')).not.toBeNull()
-    expect(running.container.querySelector('[data-state="running"] svg')).not.toBeNull()
-    running.unmount()
-    // A cancelled call wrote no todo/write: the row must not read as a completed update.
-    const stopped = render(<TodoRow {...rowProps(resultNode(args, { isError: true, error: { name: 'Interrupted', code: 'interrupted' } }))} />)
-    expect(stopped.container.querySelector('[data-state="stopped"]')).not.toBeNull()
-  })
-
-  it('falls back to the generic summary on malformed args and marks the error state', () => {
-    const view = render(<TodoRow {...rowProps(resultNode('not json', { isError: true }))} />)
-    expect(view.container.querySelector('[data-state="error"]')).not.toBeNull()
-    // Generic others summary: "<tool> · <raw>".
-    expect(screen.getByText('todo_write · not json')).toBeTruthy()
-  })
-
-  it('falls back when parsed args carry no todos array', () => {
-    render(<TodoRow {...rowProps(resultNode('{"other":1}'))} />)
-    expect(screen.getByText('todo_write · {"other":1}')).toBeTruthy()
-  })
-
-  it('leading toggle expands the raw args body', () => {
-    render(<TodoRow {...rowProps(resultNode(ARGS))} />)
-    fireEvent.click(screen.getByRole('button', { expanded: false }))
-    expect(screen.getByRole('button', { expanded: true })).toBeTruthy()
-    // The expanded body is the pretty-printed args, not the tool output.
-    expect(screen.getByText(/搭骨架/)).toBeTruthy()
-  })
-
-  it.each([
-    { label: 'null root', argsRaw: 'null' },
-    { label: 'non-object root', argsRaw: '42' },
-    { label: 'null items', argsRaw: '{"todos":[null]}' },
-  ])('falls back to the generic summary on valid JSON with an invalid shape ($label)', ({ argsRaw }) => {
-    render(<TodoRow {...rowProps(resultNode(argsRaw))} />)
-    // No throw, and the generic others summary carries the raw args verbatim.
-    expect(screen.getByText(`todo_write · ${argsRaw}`)).toBeTruthy()
-  })
-
-  it('window-truncated result (call head lost) falls back to the callId summary', () => {
-    render(<TodoRow {...rowProps(resultNode('', { call: null }))} />)
-    expect(screen.getByText('todo_write · c1')).toBeTruthy()
-  })
-
-  it('todoToolview injects the toolview declaration directly', () => {
-    expect(todoToolview.name).toBe('todo-toolview')
-    expect(todoToolview.inject).toEqual(['slots'])
-    const register = vi.fn(() => () => undefined)
-    const inject = vi.fn((_name: string, callback: () => () => void) => callback())
-    todoToolview.apply({ slots: { inject, register } } as never)
-    expect(inject).toHaveBeenCalledWith('conversation.chat.toolview', expect.any(Function))
-    expect(register).toHaveBeenCalledWith({ name: 'conversation.chat.toolview', key: 'todo_write', locale: NS }, TodoRow)
-  })
-})
diff --git a/packages/client/ui-conversation/tests/views-type-chain.spec.tsx b/packages/client/ui-conversation/tests/views-type-chain.spec.tsx
index 69e8355870..b055c51560 100644
--- a/packages/client/ui-conversation/tests/views-type-chain.spec.tsx
+++ b/packages/client/ui-conversation/tests/views-type-chain.spec.tsx
@@ -1,16 +1,11 @@
-// View-ring + toolview-hole type-chain samples, slot form: both are declared
-// slots, so the register→inject→render chain and its compile-time locks are
-// the slot system's (ui-slots/tests/type-chain.spec.tsx owns the generic
-// duals). This spec pins the package-specific surface: the SlotMap rows
-// (kind/scope/owner), list- and keyed-kind registration shapes, the ChatView
-// and tool-row composed-props contracts, and the runtime dual — a real
-// SlotsService ledger driving registration/order/disposal the way
-// ConversationRoot's tab projection consumes it.
+// View-ring type-chain samples. This spec pins the conversation-owned SlotMap
+// row, list-kind registration shape, composed view props, and the runtime
+// ledger projection consumed by ConversationRoot.
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import type { ReactNode } from 'react'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ChatViewSlotProps, ConvViewProps, ToolRowProps } from '../src/client/contract/slots.ts'
+import type { ChatViewSlotProps, ConvViewProps } from '../src/client/contract/slots.ts'
 
 describe('view-ring type negatives (compile-time; body never runs)', () => {
   it('holds the negative samples as expect-error sites', () => {
@@ -54,30 +49,6 @@ describe('view-ring type negatives (compile-time; body never runs)', () => {
         return null
       }
       void chatProps
-      // 7. Keyed hole registration requires the key shape field.
-      // @ts-expect-error missing `key` on a keyed-slot registration
-      slots.register({ name: 'conversation.chat.toolview' }, (_p: ToolRowProps) => null)
-      // 8. A list-kind shape field is rejected on the keyed hole.
-      slots.register(
-        // @ts-expect-error `id`/`order` belong to list slots, not the keyed hole
-        { name: 'conversation.chat.toolview', key: 'k', order: 1 },
-        (_p: ToolRowProps) => null)
-      // 9. Tool-row components stay within their composed contract: the
-      //    owner share + standard kit supply no chat-view members.
-      const overreaching = (props: ToolRowProps): ReactNode => {
-        // @ts-expect-error loadOlder lives on ChatViewSlotProps, not the row contract
-        void props.loadOlder
-        return null
-      }
-      void overreaching
-      // 10. Owner-share drift is red at the row component seam: block is the
-      //     call union, not arbitrary payload.
-      const drifted = (props: ToolRowProps): ReactNode => {
-        // @ts-expect-error the block union has no `argsParsed` member
-        void props.block.argsParsed
-        return null
-      }
-      void drifted
       return null as ReactNode
     }
     expect(negatives).toBeTypeOf('function')
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index a1d1a2c9d5..5aa997d003 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/client/ui-skill/README.md
-README.md: bdd772662acda1f8cf1b7d8a7c5532f9b37123dd
-README.zh.md: 959ff0ede6d545150fb22710c8af75859966caa9
+README.md: 44953fe36ad337d0dd70e4d8c0cc2372b8924c9b
+README.zh.md: 8c21ef35eded61324d139dd32b7c1e38f8709d55
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index bdd772662a..44953fe36a 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -12,7 +12,7 @@ The `/client` export surface is the plugin body (`apply`/`inject`) only; the sou
 
 ## Skill tool row
 
-The browser plugin also registers a keyed `skill` toolview in `conversation.chat.toolview`. A collapsed row renders the 14-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from a paired call/result slice in the current runtime window, never from the current catalog, so replay remains stable when installed skills or their descriptions change.
+The browser plugin also registers the `skill` wire name in `ui-tool`'s keyed `tool.call.toolview` slot. A collapsed row renders the 14-pixel skill document-and-sparkle glyph, `Skill` title, separator, and requested skill name with the same neutral hierarchy as the Bash row; running calls carry the transcript shimmer, failures replace the name with the first error line, and interrupted calls use the warning state. A settled row expands as one whole-row disclosure into a bounded `Instructions` card containing the exact durable tool output, with the standard trajectory `Inspect` affordance when available. The row derives its name, lifecycle, and body only from the frozen call/result slice supplied by `ui-tool`, never from the current catalog, so replay remains stable when installed skills or their descriptions change.
 
 ## Model Experience
 
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 959ff0ede6..8c21ef35ed 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -12,7 +12,7 @@ pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文
 
 ## skill 工具行
 
-浏览器插件还会把一个 key 为 `skill` 的 toolview 注册进 `conversation.chat.toolview`。收起的行以与 Bash 行相同的中性色层级显示 14 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自当前 runtime 窗口中已配对的调用／结果片段，绝不读取当前 skill 目录，因此即使已安装的 skill 或其描述发生变化，回放仍保持稳定。
+浏览器插件还会把 `skill` wire 名称注册进 `ui-tool` 的 keyed `tool.call.toolview` slot。收起的行以与 Bash 行相同的中性色层级显示 14 像素的 skill 文档与闪光组合图标、`Skill` 标题、分隔符和请求加载的 skill 名称；运行中的调用带有 transcript（文本记录）的扫光效果，失败时用错误首行替换名称，中断调用则使用警告状态。已结算的行以整行作为展开入口，展开后显示一个尺寸受限的 `Instructions` 卡片，其中原样呈现持久化的工具输出；可用时还会提供标准执行轨迹的 `Inspect` 入口。该行的名称、生命周期和正文只派生自 `ui-tool` 提供的冻结 call/result slice，绝不读取当前 skill 目录，因此即使已安装的 skill 或其描述发生变化，回放仍保持稳定。
 
 ## 模型体验
 
diff --git a/packages/client/ui-skill/package.json b/packages/client/ui-skill/package.json
index c9d2dd4ed8..420b1c4322 100644
--- a/packages/client/ui-skill/package.json
+++ b/packages/client/ui-skill/package.json
@@ -26,7 +26,7 @@
     "inject": [
       "@deepseek-ai/dsh-client-runtime",
       "@deepseek-ai/dsh-client-locale",
-      "@deepseek-ai/dsh-client-ui-conversation",
+      "@deepseek-ai/dsh-client-ui-tool",
       "@deepseek-ai/dsh-client-ui-slash"
     ],
     "platform": "web"
@@ -40,7 +40,7 @@
     "@deepseek-ai/dsh-client-connection": "^0.0.1",
     "@deepseek-ai/dsh-client-locale": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-tool": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slash": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
@@ -53,7 +53,7 @@
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-tool": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slash": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
diff --git a/packages/client/ui-skill/src/client/SkillRow.tsx b/packages/client/ui-skill/src/client/SkillRow.tsx
index 65b474825a..a26c41ada5 100644
--- a/packages/client/ui-skill/src/client/SkillRow.tsx
+++ b/packages/client/ui-skill/src/client/SkillRow.tsx
@@ -6,7 +6,7 @@ import { useState, type KeyboardEvent, type ReactNode } from 'react'
 import {
   IconChevronDownOutline14, IconInspectOutline12, IconSkillOutline16, StateDot,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import css from './SkillRow.module.css'
 
@@ -14,7 +14,7 @@ import css from './SkillRow.module.css'
 type SkillRowState = 'running' | 'ok' | 'error' | 'stopped'
 
 /** Full row props: the toolview runtime share plus this package's locale seat. */
-type SkillRowProps = ToolRowProps & PropsLocale<'skill'>
+type SkillRowProps = ToolCallViewProps & PropsLocale<'skill'>
 
 /** Compact, replay-stable view model for the dedicated row. */
 interface SkillRowModel {
@@ -45,9 +45,9 @@ function skillName(argsRaw: string, callId: string): string {
   return argsRaw === '' ? callId : firstLine(argsRaw)
 }
 
-/** Flatten durable result blocks under the generic tool-row text contract.
- *  Keep aligned with ui-conversation's contract/tool-call-model.ts `resultText`. */
-function resultText(block: ToolRowProps['block']): string | null {
+/** Flatten durable result blocks under the generic Tool-row text contract.
+ *  Keep aligned with ui-tool's models/tool-call-model.ts `resultText`. */
+function resultText(block: ToolCallViewProps['block']): string | null {
   if (!('kind' in block)) return null
   const parts: string[] = []
   for (const item of block.content) {
@@ -60,7 +60,7 @@ function resultText(block: ToolRowProps['block']): string | null {
 }
 
 /** Derive display state without consulting the live skill catalog. */
-function skillRowModel(block: ToolRowProps['block']): SkillRowModel {
+function skillRowModel(block: ToolCallViewProps['block']): SkillRowModel {
   const settled = 'kind' in block
   const argsRaw = (settled ? block.call?.argsRaw : block.argsRaw) ?? ''
   const state: SkillRowState = !settled
diff --git a/packages/client/ui-skill/src/client/index.ts b/packages/client/ui-skill/src/client/index.ts
index 4e23be06be..139398b648 100644
--- a/packages/client/ui-skill/src/client/index.ts
+++ b/packages/client/ui-skill/src/client/index.ts
@@ -58,8 +58,8 @@ export const inject = ['slash', 'connection', 'sessions', 'slots', 'locale']
  */
 export function apply(ctx: ClientContext): void {
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-skill: dictionaries')
-  ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register(
-    { name: 'conversation.chat.toolview', key: 'skill', locale: NS },
+  ctx.slots.inject('tool.call.toolview', () => ctx.slots.register(
+    { name: 'tool.call.toolview', key: 'skill', locale: NS },
     SkillRow,
   ))
 
diff --git a/packages/client/ui-skill/tests/browser-plugin.spec.ts b/packages/client/ui-skill/tests/browser-plugin.spec.ts
index f73a8d8bda..4679ef2c98 100644
--- a/packages/client/ui-skill/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts
@@ -41,7 +41,7 @@ function providePresentation(ctx: Context): PresentationCapture {
   const slots = new SlotsService(ctx)
   slots.register({
     name: 'root',
-    children: { 'conversation.chat.toolview': { kind: 'keyed', scope: 'session' } },
+    children: { 'tool.call.toolview': { kind: 'keyed', scope: 'session' } },
   } as never, () => null)
   const capture: PresentationCapture = {
     slots,
@@ -113,7 +113,7 @@ describe('apply', () => {
     ctx.provide('sessions', { subagentAddress: () => undefined })
     const presentation = providePresentation(ctx)
     await ctx.plugin({ inject: [...inject], apply }).await()
-    const entry = presentation.slots.entries('conversation.chat.toolview')[0]
+    const entry = presentation.slots.entries('tool.call.toolview')[0]
     expect(entry?.options).toMatchObject({ key: 'skill' })
     expect(entry?.locale).toBe('skill')
     expect(entry?.component).toBe(SkillToolRow)
@@ -158,7 +158,7 @@ describe('apply', () => {
     // …and fiber teardown releases it.
     await fiber.dispose()
     expect(() => slash.registerSource(rival)).not.toThrow()
-    expect(presentation.slots.entries('conversation.chat.toolview')).toHaveLength(0)
+    expect(presentation.slots.entries('tool.call.toolview')).toHaveLength(0)
     expect(presentation.localeDisposed).toBe(true)
   })
 })
diff --git a/packages/client/ui-skill/tsconfig.json b/packages/client/ui-skill/tsconfig.json
index f83486aa36..d6ec931648 100644
--- a/packages/client/ui-skill/tsconfig.json
+++ b/packages/client/ui-skill/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../runtime"
     },
     {
-      "path": "../ui-conversation"
+      "path": "../ui-tool"
     },
     {
       "path": "../ui-primitives"
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
new file mode 100644
index 0000000000..828cfa25ef
--- /dev/null
+++ b/packages/client/ui-tool/README.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 packages/client/ui-tool/README.md
+README.md: 381253f4eddaa57b89318dd23da3a049505fdd15
+README.zh.md: ae539131198771bc1d0e280bbfaa76ec0ec60792
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
new file mode 100644
index 0000000000..381253f4ed
--- /dev/null
+++ b/packages/client/ui-tool/README.md
@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-client-ui-tool
+
+English | [中文](README.zh.md)
+
+Client Tool presentation plugin. `ui-conversation` supplies one ordered root call through `conversation.chat.tool`; this package renders that root and its Code Dispatch children, then dispatches every atomic call through the keyed `tool.call.toolview` slot. Unregistered Tool names use the generic card.
+
+Business UI packages register only their wire Tool names and atomic views. They do not pair Session events, rebuild the transcript, or own root/subcall topology. The Runtime remains authoritative for call/result pairing, lifecycle, and `codeDispatches`; the conversation view remains authoritative for ChatFlow placement.
+
+## Rendering contract
+
+`ToolCallTree` receives one root `ToolCallBlock`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. Through its standard session slot props it selects the Runtime-projected `codeDispatches[rootCallId]` array, then sends the root and every child through the same atomic dispatch path. The Runtime currently exposes only one Code Dispatch child level, so the renderer preserves that shape instead of inventing recursive data.
+
+The package also fills `conversation.details.tool` with `ToolDetails`. The row and details renderers share the same pure card models for `terminal`, `read`, `diff`, `search`, and `web` render intents. Unknown intent tags and malformed wire card data fall back to flattened Tool result text.
+
+Generic rows classify known Tool names into search, read, shell, write, edit, code, or generic variants. Running, successful, failed, and interrupted lifecycle states come only from the frozen call/result slice. File paths resolve against the session `cwd` only when the user invokes the Host open-file callback; presentation code does not read Session services.
+
+## Atomic Tool views
+
+An owning business package registers its wire Tool name into `tool.call.toolview`:
+
+```ts ignore-check
+ctx.slots.inject('tool.call.toolview', () =>
+  ctx.slots.register({
+    name: 'tool.call.toolview',
+    key: '<wire tool name>',
+  }, BusinessToolRow))
+```
+
+The owner payload is `ToolCallOwnerProps`: `callId`, `toolName`, the frozen `block`, optional `cwd`, and plain `openFile`/`inspect` callbacks. The registration receives the normal session slot runtime share. It does not receive React nodes, Runtime services, or root/subcall knowledge.
+
+This package currently owns the generic fallback and the built-in bash/pwsh, read, write/edit, grep/glob, web, todo, question, and Code Dispatch presentations. `ui-skill` demonstrates a business-owned registration for `skill`.
+
+## Model Experience
+
+None. This package renders already logged Tool calls and results and does not alter model requests, Tool execution, or session events.
+
+#### KV Cache effect
+
+None. The package is client-only presentation.
+
+## Known Limitations and Deferred Work
+
+- The Runtime currently exposes one level of Code Dispatch children. The renderer sends roots and children through the same atomic path, but it does not claim an arbitrary recursive wire topology.
+- Existing first-party Tool views are initially colocated here and can move to their owning business packages independently through the keyed slot.
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
new file mode 100644
index 0000000000..ae53913119
--- /dev/null
+++ b/packages/client/ui-tool/README.zh.md
@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-client-ui-tool
+
+[English](README.md) | 中文
+
+Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交付一个已经排好位置的 root call；本包渲染该 root 及其 Code Dispatch 子调用，并把每个原子调用通过 keyed slot `tool.call.toolview` 分发。没有注册的 Tool 名称使用通用卡片。
+
+业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和 `codeDispatches`；conversation view 继续负责 ChatFlow 位置。
+
+## 渲染契约
+
+`ToolCallTree` 接收一个 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它通过标准 session slot props 选择 Runtime 投影的 `codeDispatches[rootCallId]` 数组，再让 root 与每个 child 经过同一条原子分发路径。Runtime 当前只暴露一层 Code Dispatch child，因此 renderer 保留该形状，不自行发明递归数据。
+
+本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 为 `terminal`、`read`、`diff`、`search` 和 `web` render intent 共用同一组纯 card model。本版本不认识的 intent 标签和格式错误的 wire card 数据都会回退为压平的 Tool result 文本。
+
+通用行把已知 Tool 名称归类为 search、read、shell、write、edit、code 或 generic 变体。运行中、成功、失败和中断状态只来自冻结的 call/result slice。只有用户调用 Host 打开文件回调时，文件路径才相对会话 `cwd` 解析；展示代码不读取 Session service。
+
+## 原子 Tool 视图
+
+业务所有方把自己的 wire Tool 名称注册进 `tool.call.toolview`：
+
+```ts ignore-check
+ctx.slots.inject('tool.call.toolview', () =>
+  ctx.slots.register({
+    name: 'tool.call.toolview',
+    key: '<wire tool name>',
+  }, BusinessToolRow))
+```
+
+owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`、可选 `cwd`，以及普通的 `openFile`／`inspect` 回调。注册项会收到正常的 Session slot runtime share，但不会收到 React node、Runtime service 或 root/subcall 知识。
+
+本包当前拥有 generic fallback，以及 bash/pwsh、read、write/edit、grep/glob、web、todo、question 和 Code Dispatch 的内置展示。`ui-skill` 展示了业务包如何拥有 `skill` 注册。
+
+## 模型体验
+
+无。本包只渲染已经记录的 Tool 调用和结果，不改变模型请求、Tool 执行或 Session Event。
+
+#### KV Cache 影响
+
+无。本包只负责 Client 展示。
+
+## 已知限制与后续工作
+
+- Runtime 当前只暴露一层 Code Dispatch 子调用。renderer 会让 root 和 child 经过同一个原子分发路径，但不宣称 wire 拓扑已经支持任意递归。
+- 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
diff --git a/packages/client/ui-tool/package.json b/packages/client/ui-tool/package.json
new file mode 100644
index 0000000000..965a084cd2
--- /dev/null
+++ b/packages/client/ui-tool/package.json
@@ -0,0 +1,73 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-tool",
+  "description": "Client Tool call-tree renderer and keyed per-tool presentation slot",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-locale",
+      "@deepseek-ai/dsh-client-ui-conversation"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "clsx": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-locale": "^0.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ]
+}
diff --git a/packages/client/ui-tool/src/client/apply.ts b/packages/client/ui-tool/src/client/apply.ts
new file mode 100644
index 0000000000..48a9a4c812
--- /dev/null
+++ b/packages/client/ui-tool/src/client/apply.ts
@@ -0,0 +1,43 @@
+/** Register the Tool call tree, details renderer, and built-in atomic views. */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { ToolCallTree } from './tool/ToolCallTree.tsx'
+import { ToolDetails } from './tool/ToolDetails.tsx'
+import { CONVERSATION_NS as NS } from './locale.ts'
+import { askQuestionToolview } from './tool/toolviews/ask-question-row.tsx'
+import { bashToolviewSample } from './tool/toolviews/bash-sample.tsx'
+import { fileMutationToolview } from './tool/toolviews/file-mutation-row.tsx'
+import { readToolview } from './tool/toolviews/read-row.tsx'
+import { searchToolview } from './tool/toolviews/search-row.tsx'
+import { todoToolview } from './tool/toolviews/todo-row.tsx'
+import { webToolview } from './tool/toolviews/web-row.tsx'
+
+/** Required service: the slot registry that owns both Tool render seats. */
+export const inject = ['slots']
+
+/**
+ * Mount the whole-Tool renderers and built-in atomic Tool registrations.
+ * @param ctx - Client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.slots.inject('conversation.chat.tool', () => ctx.slots.register({
+    name: 'conversation.chat.tool',
+    locale: NS,
+    children: {
+      'tool.call.toolview': { kind: 'keyed', scope: 'session' },
+    },
+  }, ToolCallTree))
+
+  ctx.slots.inject('conversation.details.tool', () => ctx.slots.register({
+    name: 'conversation.details.tool',
+    locale: NS,
+  }, ToolDetails))
+
+  ctx.plugin(bashToolviewSample)
+  ctx.plugin(readToolview)
+  ctx.plugin(fileMutationToolview)
+  ctx.plugin(searchToolview)
+  ctx.plugin(webToolview)
+  ctx.plugin(todoToolview)
+  ctx.plugin(askQuestionToolview)
+}
diff --git a/packages/client/ui-tool/src/client/contract/slots.ts b/packages/client/ui-tool/src/client/contract/slots.ts
new file mode 100644
index 0000000000..4b74055b2c
--- /dev/null
+++ b/packages/client/ui-tool/src/client/contract/slots.ts
@@ -0,0 +1,39 @@
+/** Tool UI slot declarations and their composed component props. */
+import type { PropsLocale, PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /** Keyed atomic Tool call view, dispatched by the wire Tool name. */
+    'tool.call.toolview': { kind: 'keyed'; scope: 'session'; owner: ToolCallOwnerProps }
+  }
+}
+
+/** Standard owner currency supplied to every atomic Tool view. */
+export interface ToolCallOwnerProps {
+  /** Tool call identity, stable across running and settled forms. */
+  callId: string
+  /** Wire Tool name and keyed dispatch value. */
+  toolName: string
+  /** Frozen running call or settled result node. */
+  block: ToolCallBlock
+  /** Session workspace root for relative summaries. */
+  cwd?: string | undefined
+  /** Open a Tool argument path through the Host. */
+  openFile: (path: string) => void
+  /** Inspect this call in the trajectory view when available. */
+  inspect?: (() => void) | undefined
+}
+
+/** Full props of a registered atomic Tool view. */
+export type ToolCallViewProps = PropsRuntime<'tool.call.toolview'>
+
+/** Full props of the Tool call-tree renderer registered into the chat flow. */
+export type ToolTreeProps = PropsRuntime<'conversation.chat.tool'>
+  & PropsRenderSlots<'tool.call.toolview'>
+  & PropsLocale<'conversation'>
+
+/** Full props of the selected Tool output renderer in the details panel. */
+export type ToolDetailsProps = PropsRuntime<'conversation.details.tool'> & PropsLocale<'conversation'>
diff --git a/packages/client/ui-tool/src/client/index.ts b/packages/client/ui-tool/src/client/index.ts
new file mode 100644
index 0000000000..357506b1db
--- /dev/null
+++ b/packages/client/ui-tool/src/client/index.ts
@@ -0,0 +1,3 @@
+/** Browser Tool plugin: whole-call composition and keyed atomic Tool views. */
+export { apply, inject } from './apply.ts'
+export type { ToolCallOwnerProps, ToolCallViewProps, ToolDetailsProps, ToolTreeProps } from './contract/slots.ts'
diff --git a/packages/client/ui-tool/src/client/locale.ts b/packages/client/ui-tool/src/client/locale.ts
new file mode 100644
index 0000000000..0dd6721101
--- /dev/null
+++ b/packages/client/ui-tool/src/client/locale.ts
@@ -0,0 +1,2 @@
+/** Locale namespace supplied by the conversation owner to Tool renderers. */
+export const CONVERSATION_NS = 'conversation'
diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.module.css b/packages/client/ui-tool/src/client/tool/ToolCallTree.module.css
new file mode 100644
index 0000000000..b33fb477c1
--- /dev/null
+++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.module.css
@@ -0,0 +1,12 @@
+.callRow {
+  border-radius: 6px;
+}
+
+.subCalls {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin: 4px 0 2px 22px;
+  padding-left: 8px;
+  border-left: 1px solid var(--dsw-alias-border-l2);
+}
diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
new file mode 100644
index 0000000000..8091f26dff
--- /dev/null
+++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
@@ -0,0 +1,88 @@
+/** Root/subcall Tool composition with one keyed atomic dispatch path. */
+import { memo, useMemo } from 'react'
+import type { CodeSubCall, ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolCallOwnerProps, ToolTreeProps } from '../contract/slots.ts'
+import { GenericToolCard } from './toolviews/GenericToolCard.tsx'
+import css from './ToolCallTree.module.css'
+
+/** Resolve a Code Dispatch child's wire Tool name from either lifecycle form. */
+function subCallName(node: CodeSubCall): string {
+  return 'kind' in node ? node.call?.name ?? '' : node.name
+}
+
+/** One atomic call dispatched through the Tool-owned keyed slot. */
+const ToolCall = memo(function ToolCall({
+  renderSlot, callId, toolName, block, openFile, selected, cwd, inspectCall, t,
+}: Pick<ToolTreeProps, 'renderSlot' | 'openFile' | 'cwd' | 'inspectCall' | 't'> & {
+  callId: string
+  toolName: string
+  block: ToolCallBlock
+  selected: boolean
+}) {
+  const owner: ToolCallOwnerProps = useMemo(() => ({
+    callId,
+    toolName,
+    block,
+    openFile,
+    cwd,
+    inspect: () => { inspectCall(callId) },
+  }), [callId, toolName, block, openFile, cwd, inspectCall])
+  return (
+    <div
+      className={css.callRow}
+      data-chat-anchor-key={`call:${callId}`}
+      data-chat-call-id={callId}
+      data-selected={selected || undefined}
+    >
+      {renderSlot('tool.call.toolview', owner, {
+        entryKey: toolName,
+        fallback: <GenericToolCard {...owner} t={t} />,
+      })}
+    </div>
+  )
+})
+
+/**
+ * Render one root Tool call and its currently supported one-level Code
+ * Dispatch children. Root and children use the same atomic keyed dispatch.
+ * @param props - whole-Tool owner data and the Tool-owned child-slot share.
+ * @returns the Tool call tree.
+ */
+export function ToolCallTree({
+  useSession, renderSlot, callId, toolName, block, selectedCallId, cwd, openFile, inspectCall, t,
+}: ToolTreeProps) {
+  const subCalls = useSession(snapshot => snapshot.codeDispatches.get(callId))
+  return (
+    <>
+      <ToolCall
+        renderSlot={renderSlot}
+        callId={callId}
+        toolName={toolName}
+        block={block}
+        openFile={openFile}
+        selected={callId === selectedCallId}
+        cwd={cwd}
+        inspectCall={inspectCall}
+        t={t}
+      />
+      {subCalls !== undefined && subCalls.length > 0 ? (
+        <div className={css.subCalls} data-subcalls>
+          {subCalls.map(node => (
+            <ToolCall
+              key={node.callId}
+              renderSlot={renderSlot}
+              callId={node.callId}
+              toolName={subCallName(node)}
+              block={node}
+              openFile={openFile}
+              selected={node.callId === selectedCallId}
+              cwd={cwd}
+              inspectCall={inspectCall}
+              t={t}
+            />
+          ))}
+        </div>
+      ) : null}
+    </>
+  )
+}
diff --git a/packages/client/ui-tool/src/client/tool/ToolDetails.module.css b/packages/client/ui-tool/src/client/tool/ToolDetails.module.css
new file mode 100644
index 0000000000..ebfb3afb07
--- /dev/null
+++ b/packages/client/ui-tool/src/client/tool/ToolDetails.module.css
@@ -0,0 +1,46 @@
+.description {
+  margin: 0 0 6px;
+  color: var(--dsw-alias-label-secondary);
+  font: var(--dsw-font-xs-13);
+}
+
+.cardBody {
+  margin: 0;
+}
+
+.recovery {
+  margin: 6px 0 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  color: var(--dsw-alias-label-tertiary);
+  font: var(--dsw-font-xs-13);
+}
+
+.code {
+  margin: 0;
+  padding: 16px;
+  border-radius: 12px;
+  background: var(--dsw-alias-markdown-code-block);
+  font-family: var(--ds-font-family-code);
+  font-size: 13px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.code[data-error] {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.read,
+.web {
+  margin: 0;
+}
+
+.empty {
+  padding: 8px 0;
+  font-size: 13px;
+  line-height: 20px;
+  color: var(--dsw-alias-label-tertiary);
+}
diff --git a/packages/client/ui-tool/src/client/tool/ToolDetails.tsx b/packages/client/ui-tool/src/client/tool/ToolDetails.tsx
new file mode 100644
index 0000000000..f496801daa
--- /dev/null
+++ b/packages/client/ui-tool/src/client/tool/ToolDetails.tsx
@@ -0,0 +1,66 @@
+/** Card-aware output body for the selected Tool call in details. */
+import { DiffBlock, ReadBlock, SearchBlock, TerminalBlock, WebBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolDetailsProps } from '../contract/slots.ts'
+import { diffCardModel } from './models/diff-card-model.ts'
+import { readCardModel } from './models/read-card-model.ts'
+import { searchCardModel } from './models/search-card-model.ts'
+import { terminalBlockLabels, terminalCardModel } from './models/terminal-card-model.ts'
+import { resultText } from './models/tool-call-model.ts'
+import { webCardModel } from './models/web-card-model.ts'
+import css from './ToolDetails.module.css'
+
+/** Pure details-body inputs; framework session seats stay at the slot boundary. */
+interface ToolDetailsContentProps {
+  block: ToolDetailsProps['block']
+  cwd?: ToolDetailsProps['cwd']
+  t: ToolDetailsProps['t']
+}
+
+/**
+ * Render the selected Tool call's structured output when its presentation
+ * intent is known, otherwise preserve the flattened result text.
+ * @param props - selected call slice, workspace root, and locale seat.
+ * @returns the details output body.
+ */
+export function ToolDetails({ block, cwd, t }: ToolDetailsContentProps) {
+  const terminal = terminalCardModel(block, cwd)
+  if (terminal !== null) {
+    return (
+      <>
+        {terminal.description !== undefined ? (
+          <div className={css.description}>{terminal.description}</div>
+        ) : null}
+        <TerminalBlock {...terminal.card} labels={terminalBlockLabels(t)} className={css.cardBody} />
+      </>
+    )
+  }
+  const read = readCardModel(block, cwd)
+  if (read !== null) return <ReadBlock {...read} className={css.read} />
+  const diff = diffCardModel(block)
+  if (diff !== null) return <DiffBlock {...diff.card} className={css.cardBody} />
+  const search = searchCardModel(block)
+  if (search !== null) {
+    return (
+      <>
+        <SearchBlock {...search.card} className={css.cardBody} />
+        {search.recovery !== undefined ? <div className={css.recovery}>{search.recovery}</div> : null}
+      </>
+    )
+  }
+  const web = webCardModel(block)
+  if (web !== null) {
+    const body = 'kind' in block ? resultText(block) : ''
+    return (
+      <>
+        <WebBlock {...web} className={css.web} />
+        {body !== '' ? <pre className={css.code}>{body}</pre> : null}
+      </>
+    )
+  }
+  if (!('kind' in block)) return <div className={css.empty}>{t('details.running')}</div>
+  return (
+    <pre className={css.code} data-error={block.isError || undefined}>
+      {resultText(block)}
+    </pre>
+  )
+}
diff --git a/packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css b/packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css
new file mode 100644
index 0000000000..04f2d18d0a
--- /dev/null
+++ b/packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css
@@ -0,0 +1,69 @@
+/* Shared Tool calls disclosure header: [16px leading] gap 6 [title 14/24]. */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  min-width: 0;
+}
+
+.row {
+  position: relative;
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  height: 24px;
+  min-width: 0;
+}
+
+.row[data-expandable] {
+  cursor: pointer;
+}
+
+.leading {
+  position: relative;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-right: 6px;
+  padding: 0;
+  border: none;
+  background: none;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+button.leading {
+  cursor: pointer;
+}
+
+.iconIdle {
+  display: inline-flex;
+  opacity: 1;
+  transition: opacity 100ms ease;
+}
+
+.chevronHover {
+  position: absolute;
+  inset: 0;
+  margin: auto;
+  opacity: 0;
+  transition: opacity 100ms ease;
+}
+
+.row:hover .iconIdle {
+  opacity: 0;
+}
+
+.row:hover .chevronHover {
+  opacity: 1;
+}
+
+.title {
+  flex: none;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-secondary);
+}
diff --git a/packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx b/packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx
new file mode 100644
index 0000000000..361fb24517
--- /dev/null
+++ b/packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx
@@ -0,0 +1,104 @@
+import { type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
+import clsx from 'clsx'
+import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import css from './DisclosureRow.module.css'
+
+/** Shared 24px disclosure chrome for conversation flow rows. */
+export interface DisclosureRowProps {
+  icon: ReactNode
+  title: string
+  open: boolean
+  expandable: boolean
+  onToggle: () => void
+  /** Makes the complete title row the disclosure target. */
+  expandOnRowClick?: boolean | undefined
+  /** Replaces the collapsed icon with a chevron while the row is hovered. */
+  previewChevron?: boolean | undefined
+  /** Keeps `collapsedContent` inline while open (ToolRow's summary stays readable next to the expanded card). */
+  keepContentWhenOpen?: boolean | undefined
+  collapsedContent?: ReactNode
+  children?: ReactNode
+  className?: string | undefined
+  rowClassName?: string | undefined
+  leadingClassName?: string | undefined
+  chevronClassName?: string | undefined
+  titleClassName?: string | undefined
+}
+
+/**
+ * Render one disclosure header and its controlled expanded content.
+ * @param props - Visual content, controlled state, and interaction policy.
+ * @returns The disclosure row.
+ */
+export function DisclosureRow({
+  icon,
+  title,
+  open,
+  expandable,
+  onToggle,
+  expandOnRowClick = false,
+  previewChevron = expandable,
+  keepContentWhenOpen = false,
+  collapsedContent,
+  children,
+  className,
+  rowClassName,
+  leadingClassName,
+  chevronClassName,
+  titleClassName,
+}: DisclosureRowProps) {
+  const rowExpands = expandable && expandOnRowClick
+  const toggleFromLeading = (event: MouseEvent<HTMLButtonElement>) => {
+    event.stopPropagation()
+    onToggle()
+  }
+  const toggleFromKeyboard = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (!rowExpands || (event.key !== 'Enter' && event.key !== ' ')) return
+    event.preventDefault()
+    onToggle()
+  }
+  const collapsedLeading = previewChevron
+    ? (
+      <>
+        <span className={css.iconIdle}>{icon}</span>
+        <IconChevronDownOutline14 className={clsx(chevronClassName, css.chevronHover)} />
+      </>
+    )
+    : icon
+  const leading = open
+    ? <IconChevronDownOutline14 className={chevronClassName} />
+    : collapsedLeading
+
+  return (
+    <div className={clsx(css.root, className)} data-open={open || undefined}>
+      <div
+        className={clsx(css.row, rowClassName)}
+        data-disclosure-row
+        data-expandable={rowExpands || undefined}
+        role={rowExpands ? 'button' : undefined}
+        tabIndex={rowExpands ? 0 : undefined}
+        aria-expanded={rowExpands ? open : undefined}
+        onClick={rowExpands ? onToggle : undefined}
+        onKeyDown={rowExpands ? toggleFromKeyboard : undefined}
+      >
+        {expandable && !rowExpands ? (
+          <button
+            type="button"
+            className={clsx(css.leading, leadingClassName)}
+            aria-expanded={open}
+            onClick={toggleFromLeading}
+          >
+            {leading}
+          </button>
+        ) : (
+          <span className={clsx(css.leading, leadingClassName)}>
+            {leading}
+          </span>
+        )}
+        <span className={clsx(css.title, titleClassName)}>{title}</span>
+        {(keepContentWhenOpen || !open) && collapsedContent}
+      </div>
+      {open && children}
+    </div>
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css b/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css
similarity index 94%
rename from packages/client/ui-conversation/src/client/chat/ToolRow.module.css
rename to packages/client/ui-tool/src/client/tool/components/ToolRow.module.css
index 36f4c2b76a..9d9bce9eed 100644
--- a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
+++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css
@@ -84,11 +84,6 @@
   color: var(--dsw-alias-label-tertiary);
 }
 
-/* Live reasoning follows its one-line summary to the inline end. */
-.summary[data-follow-end] {
-  text-overflow: clip;
-}
-
 /* Trailing summary fragment kept out of .summary's ellipsis, for a count whose
    whole value is that it survives a narrow row (the todo row's parallel-active
    `+n`). Repeats .summary's type because it sits beside that text, and its
@@ -184,19 +179,6 @@
   overflow-y: auto;
 }
 
-/* Think expanded body: plain indented gray reasoning prose — no IN/OUT card
-   (the reasoning is not an input payload), pre-wrapped at the row's indent.
-   Uncapped: reasoning reads as message prose, so it flows with the page
-   instead of scrolling in a box. */
-.thinkBody {
-  padding: 4px 0 4px 22px;
-  font-size: 14px;
-  line-height: 24px;
-  white-space: pre-wrap;
-  word-break: break-word;
-  color: var(--dsw-alias-label-tertiary);
-}
-
 /* Expanded input/output card (figma 1249:35657): the code-block surface and
    radius from the TerminalBlock/CodeBlock family. The card itself is a plain
    column — the padding and the IN/OUT gutter-label grid live on each section
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
similarity index 76%
rename from packages/client/ui-conversation/src/client/chat/ToolRow.tsx
rename to packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
index 48c0c825cb..61c677ea98 100644
--- a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
+++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
@@ -4,36 +4,32 @@
 // DisclosureRow chrome with the whole row as the expand toggle (click /
 // Enter / Space, icon→chevron hover preview). The collapsed row is always
 // one line; every row with body, output, or a card material (terminal, diff,
-// read, search, web) is expandable; the summary stays inline while open,
-// except Think, where the running collapsed row follows the latest line at its
-// scroll end and the summary yields while open to avoid repeating the body.
+// read, search, web) is expandable; the summary stays inline while open.
 // The expanded body — an IN/OUT gutter-labeled card (figma 1249:35657) for
 // text input/output, the run_code program through CodeBlock, or a card
 // primitive (TerminalBlock, DiffBlock, ReadBlock, SearchBlock, WebBlock) for a
 // call that declared that render intent — lives in a max-height scroll
 // container so a long payload scrolls internally instead of taking over the
-// message flow; Think's prose is the exception and flows uncapped like message
-// text. Every card kind starts collapsed, so a run of tool calls stays
+// message flow. Every card kind starts collapsed, so a run of tool calls stays
 // scannable; the details panel is the single-call full-height reading surface.
 // Expand state is component-local view state. File-tool summaries are path
 // links that open through the host (stopPropagation keeps the two gestures
 // independent); an error row's collapsed summary is the failure's first line in
 // the error color.
 
-import { useEffect, useRef, useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
+import { useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
 import clsx from 'clsx'
 import {
   CodeBlock, DiffBlock, IconInspectOutline12, ReadBlock, SearchBlock, StateDot, TerminalBlock, WebBlock,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { WebBlockProps } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
-import { CHAT_DIFF_MAX_LINES, type DiffCardModel } from '../contract/diff-card-model.ts'
-import { CHAT_READ_MAX_LINES, type ReadCardModel } from '../contract/read-card-model.ts'
-import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../contract/search-card-model.ts'
-import { terminalBlockLabels, type TerminalCardModel } from '../contract/terminal-card-model.ts'
-import type { ToolRowState, ToolRowVariant } from '../contract/tool-call-model.ts'
+import { CHAT_DIFF_MAX_LINES, type DiffCardModel } from '../models/diff-card-model.ts'
+import { CHAT_READ_MAX_LINES, type ReadCardModel } from '../models/read-card-model.ts'
+import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../models/search-card-model.ts'
+import { terminalBlockLabels, type TerminalCardModel } from '../models/terminal-card-model.ts'
+import type { ToolRowState, ToolRowVariant } from '../models/tool-call-model.ts'
 import { DisclosureRow } from './DisclosureRow.tsx'
-import { useThrottledVisualUpdate } from './use-throttled-visual-update.ts'
 import css from './ToolRow.module.css'
 
 export interface ToolRowProps {
@@ -101,8 +97,7 @@ export interface ToolRowProps {
   onOpenFile?: ((path: string) => void) | undefined
   /**
    * Jump to this call in the trajectory view: a hover-revealed Inspect pill
-   * over the expanded body. Absent = no affordance (rows without a call
-   * identity, like Think).
+   * over the expanded body. Absent = no affordance.
    */
   inspect?: (() => void) | undefined
 }
@@ -153,7 +148,6 @@ export function ToolRow({
   inspect,
 }: ToolRowProps) {
   const [expanded, setExpanded] = useState(false)
-  const summaryRef = useRef<HTMLSpanElement>(null)
   const terminalBody = terminal ?? null
   const diffBody = diff ?? null
   const readBody = read ?? null
@@ -178,19 +172,6 @@ export function ToolRow({
   const suffix = failureLine === null ? summarySuffix ?? null : null
   // The failure line is error prose, not the path: no open-file affordance.
   const fileLink = filePath !== undefined && onOpenFile !== undefined && failureLine === null
-  const isThink = variant === 'think'
-  const followSummaryEnd = isThink && state === 'running' && !open
-  const scheduleSummaryScroll = useThrottledVisualUpdate(() => {
-    const summaryElement = summaryRef.current
-    if (summaryElement === null) return
-    summaryElement.scrollLeft = followSummaryEnd
-      ? summaryElement.scrollWidth - summaryElement.clientWidth
-      : 0
-  })
-  useEffect(() => {
-    if (!isThink) return
-    scheduleSummaryScroll()
-  }, [followSummaryEnd, isThink, scheduleSummaryScroll, summaryText])
   const toggleExpand = () => {
     setExpanded(v => !v)
   }
@@ -205,9 +186,6 @@ export function ToolRow({
   const fileLinkKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
     if (event.key === 'Enter' || event.key === ' ') event.stopPropagation()
   }
-  // Think reasoning is prose, not an input payload: expanded, it renders as
-  // plain indented text (no IN/OUT card) and the inline summary yields to avoid
-  // repeating the body.
   // The code variant's program renders through CodeBlock (shiki), so only its
   // output joins the IN/OUT card; every other variant's input does too.
   const cardBody = variant === 'code' ? null : body
@@ -227,7 +205,7 @@ export function ToolRow({
         open={open}
         expandable={expandable}
         expandOnRowClick
-        keepContentWhenOpen={!isThink}
+        keepContentWhenOpen
         onToggle={toggleExpand}
         collapsedContent={summaryText !== '' && (
           /* An empty summary drops the separator with it (a row that is only
@@ -245,9 +223,7 @@ export function ToolRow({
               </button>
             ) : (
               <span
-                ref={isThink ? summaryRef : undefined}
                 className={clsx(css.summary, failureLine !== null && css.errorSummary)}
-                data-follow-end={followSummaryEnd || undefined}
               >
                 {summaryText}
               </span>
@@ -285,38 +261,36 @@ export function ToolRow({
                   )
                   : webBody !== null
                     ? <WebBlock {...webBody} className={css.webBody} />
-                    : isThink
-                      ? <div className={css.thinkBody}>{body}</div>
-                      : (
-                        <>
-                          {variant === 'code' && body !== null && (
-                            <div className={css.bodyScroll}>
-                              <CodeBlock code={body} lang="typescript" copyLabel={t('copy')} copiedLabel={t('copied')} className={css.codeBody} />
-                            </div>
-                          )}
-                          {(cardBody !== null || outputText !== null) && (
-                            <div className={css.ioCard}>
-                              {cardBody !== null && (
-                                <div className={css.ioSection}>
-                                  <span className={css.ioLabel}>IN</span>
-                                  <span className={css.ioText}>{cardBody}</span>
-                                </div>
-                              )}
-                              {cardBody !== null && outputText !== null && (
-                                <span className={css.ioDivider} aria-hidden />
-                              )}
-                              {outputText !== null && (
-                                <div className={css.ioSection}>
-                                  <span className={css.ioLabel}>OUT</span>
-                                  <span className={css.ioText} data-error={state === 'error' || undefined}>
-                                    {outputText}
-                                  </span>
-                                </div>
-                              )}
-                            </div>
-                          )}
-                        </>
-                      )}
+                    : (
+                      <>
+                        {variant === 'code' && body !== null && (
+                          <div className={css.bodyScroll}>
+                            <CodeBlock code={body} lang="typescript" copyLabel={t('copy')} copiedLabel={t('copied')} className={css.codeBody} />
+                          </div>
+                        )}
+                        {(cardBody !== null || outputText !== null) && (
+                          <div className={css.ioCard}>
+                            {cardBody !== null && (
+                              <div className={css.ioSection}>
+                                <span className={css.ioLabel}>IN</span>
+                                <span className={css.ioText}>{cardBody}</span>
+                              </div>
+                            )}
+                            {cardBody !== null && outputText !== null && (
+                              <span className={css.ioDivider} aria-hidden />
+                            )}
+                            {outputText !== null && (
+                              <div className={css.ioSection}>
+                                <span className={css.ioLabel}>OUT</span>
+                                <span className={css.ioText} data-error={state === 'error' || undefined}>
+                                  {outputText}
+                                </span>
+                              </div>
+                            )}
+                          </div>
+                        )}
+                      </>
+                    )}
           {inspect !== undefined && (
             <button
               type="button"
diff --git a/packages/client/ui-conversation/src/client/contract/diff-card-model.ts b/packages/client/ui-tool/src/client/tool/models/diff-card-model.ts
similarity index 100%
rename from packages/client/ui-conversation/src/client/contract/diff-card-model.ts
rename to packages/client/ui-tool/src/client/tool/models/diff-card-model.ts
diff --git a/packages/client/ui-conversation/src/client/contract/read-card-model.ts b/packages/client/ui-tool/src/client/tool/models/read-card-model.ts
similarity index 100%
rename from packages/client/ui-conversation/src/client/contract/read-card-model.ts
rename to packages/client/ui-tool/src/client/tool/models/read-card-model.ts
diff --git a/packages/client/ui-conversation/src/client/contract/search-card-model.ts b/packages/client/ui-tool/src/client/tool/models/search-card-model.ts
similarity index 100%
rename from packages/client/ui-conversation/src/client/contract/search-card-model.ts
rename to packages/client/ui-tool/src/client/tool/models/search-card-model.ts
diff --git a/packages/client/ui-conversation/src/client/contract/terminal-card-model.ts b/packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts
similarity index 100%
rename from packages/client/ui-conversation/src/client/contract/terminal-card-model.ts
rename to packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts
diff --git a/packages/client/ui-conversation/src/client/contract/tool-call-model.ts b/packages/client/ui-tool/src/client/tool/models/tool-call-model.ts
similarity index 95%
rename from packages/client/ui-conversation/src/client/contract/tool-call-model.ts
rename to packages/client/ui-tool/src/client/tool/models/tool-call-model.ts
index 9ae5c4c85b..151ef3b45f 100644
--- a/packages/client/ui-conversation/src/client/contract/tool-call-model.ts
+++ b/packages/client/ui-tool/src/client/tool/models/tool-call-model.ts
@@ -13,18 +13,15 @@ import type { ToolCallBlock, ToolResultNode } from '@deepseek-ai/dsh-client-runt
 
 export type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
 
-/** The frozen slice the chat view hands to toolview components as `block`
- *  (both members are cache-stable references off ConversationSnapshot). */
-
-/** The eight row variants (think is fed by reasoning blocks, not tool calls). */
-export type ToolRowVariant = 'think' | 'search' | 'read' | 'bash' | 'write' | 'edit' | 'code' | 'others'
+/** Tool-call row variants selected by the generic atomic renderer. */
+export type ToolRowVariant = 'search' | 'read' | 'bash' | 'write' | 'edit' | 'code' | 'others'
 
 /** Row state semantic; colors self-supplied via StateDot (design gives none). */
 export type ToolRowState = 'running' | 'ok' | 'error' | 'stopped'
 
 /** Figma row titles per variant (design literals, not translatable copy). */
 export const VARIANT_TITLES: Record<ToolRowVariant, string> = {
-  think: 'Think', search: 'Search', read: 'Read', bash: 'Bash',
+  search: 'Search', read: 'Read', bash: 'Bash',
   write: 'Write', edit: 'Edit', code: 'Code', others: 'Tool call',
 }
 
@@ -130,7 +127,6 @@ const SUMMARY_KEYS: Record<ToolRowVariant, readonly string[]> = {
   bash: ['description', 'command'],
   read: ['path', 'file_path', 'url'],
   search: ['query', 'pattern', 'url'],
-  think: [],
   write: ['path', 'file_path'],
   edit: ['path', 'file_path'],
   code: ['description'],
diff --git a/packages/client/ui-conversation/src/client/contract/web-card-model.ts b/packages/client/ui-tool/src/client/tool/models/web-card-model.ts
similarity index 100%
rename from packages/client/ui-conversation/src/client/contract/web-card-model.ts
rename to packages/client/ui-tool/src/client/tool/models/web-card-model.ts
diff --git a/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx b/packages/client/ui-tool/src/client/tool/toolviews/GenericToolCard.tsx
similarity index 76%
rename from packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
rename to packages/client/ui-tool/src/client/tool/toolviews/GenericToolCard.tsx
index 705d1d039f..ae4d18eec8 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/GenericToolCard.tsx
@@ -1,26 +1,24 @@
-// GenericToolCard: the default tool row — classifies the tool into one of
-// the five figma row variants and renders the summary row. Supplied by the
-// chat view as the keyed toolview slot's render-site fallback (an
+// GenericToolCard: the default tool row — classifies the tool into a visual
+// variant and renders the summary row. Supplied by the Tool call tree as the
+// keyed atomic-view slot's render-site fallback (an
 // unregistered tool name lands here); registrants may also compose it as a
 // base, feeding the same owner payload through.
 
 import type { ReactNode } from 'react'
 import {
   IconApiOutline14, IconBrowseOutline16, IconCodeOutline16, IconEditOutline16, IconSearchOutline16, IconSparkle16,
-  IconThinkOutline14,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps, ToolRowOwnerProps } from '../contract/slots.ts'
-import { readCardModel } from '../contract/read-card-model.ts'
-import { diffCardModel } from '../contract/diff-card-model.ts'
-import { searchCardModel } from '../contract/search-card-model.ts'
-import { terminalCardModel, terminalFailed } from '../contract/terminal-card-model.ts'
-import { webCardModel } from '../contract/web-card-model.ts'
-import { toolRowModel, type ToolRowVariant } from '../contract/tool-call-model.ts'
-import { ToolRow } from './ToolRow.tsx'
+import type { ToolCallOwnerProps, ToolTreeProps } from '../../contract/slots.ts'
+import { readCardModel } from '../models/read-card-model.ts'
+import { diffCardModel } from '../models/diff-card-model.ts'
+import { searchCardModel } from '../models/search-card-model.ts'
+import { terminalCardModel, terminalFailed } from '../models/terminal-card-model.ts'
+import { webCardModel } from '../models/web-card-model.ts'
+import { toolRowModel, type ToolRowVariant } from '../models/tool-call-model.ts'
+import { ToolRow } from '../components/ToolRow.tsx'
 
 /** Variant leading icons (figma table); all glyphs render at 14 inside the 16px leading box. */
 const VARIANT_ICONS: Record<ToolRowVariant, ReactNode> = {
-  think: <IconThinkOutline14 size={14} />,
   search: <IconSearchOutline16 size={14} />,
   read: <IconBrowseOutline16 size={14} />,
   bash: <IconApiOutline14 size={14} />,
@@ -31,8 +29,8 @@ const VARIANT_ICONS: Record<ToolRowVariant, ReactNode> = {
 }
 
 /** Card props: the owner payload plus the render site's locale seat (plain prop). */
-export interface GenericToolCardProps extends ToolRowOwnerProps {
-  t: ChatViewSlotProps['t']
+export interface GenericToolCardProps extends ToolCallOwnerProps {
+  t: ToolTreeProps['t']
 }
 
 export function GenericToolCard({ toolName, block, cwd, openFile, inspect, t }: GenericToolCardProps) {
diff --git a/packages/client/ui-conversation/src/client/toolviews/ask-question-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/ask-question-row.tsx
similarity index 85%
rename from packages/client/ui-conversation/src/client/toolviews/ask-question-row.tsx
rename to packages/client/ui-tool/src/client/tool/toolviews/ask-question-row.tsx
index 727e1e53ad..8f45bf3a49 100644
--- a/packages/client/ui-conversation/src/client/toolviews/ask-question-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/ask-question-row.tsx
@@ -1,6 +1,6 @@
 // ask_user_question toolview: question-flavored summary row replacing the
 // generic "Tool call" card, registered into the keyed
-// 'conversation.chat.toolview' hole like todo-row. The row composes ToolRow
+// 'tool.call.toolview' hole like todo-row. The row composes ToolRow
 // (chrome, running sweep, whole-row expand) and swaps in the interaction
 // outcome — `waiting` while pending, answered-count once settled, `cancelled`
 // when the user dismissed the whole set — because the questions themselves
@@ -9,10 +9,10 @@
 import { IconQuestionOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { Context } from 'cordis'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ToolRowProps } from '../contract/slots.ts'
-import { toolRowModel } from '../contract/tool-call-model.ts'
-import { ToolRow } from '../chat/ToolRow.tsx'
-import { NS } from '../locales.ts'
+import type { ToolCallViewProps } from '../../contract/slots.ts'
+import { toolRowModel } from '../models/tool-call-model.ts'
+import { ToolRow } from '../components/ToolRow.tsx'
+import { CONVERSATION_NS as NS } from '../../locale.ts'
 
 /** One parsed answer entry, shape-checked (result JSON crosses the wire). */
 interface AnswerEntry { selected?: unknown; custom?: unknown }
@@ -40,7 +40,7 @@ function answeredSummary(text: string, t: AskQuestionRowProps['t']): string | nu
 }
 
 /** Full row props: the toolview runtime share plus the standard locale seat. */
-type AskQuestionRowProps = ToolRowProps & PropsLocale<'conversation'>
+type AskQuestionRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 /** One-line question-interaction row (the whole row toggles the call's
  *  Input/Output sections, ToolRow's unified expand). */
@@ -90,12 +90,12 @@ export const askQuestionToolview = {
   name: 'ask-question-toolview',
   inject: ['slots'],
   /**
-   * Register the ask-question row into the chat view's keyed toolview hole.
+   * Register the ask-question row into the Tool-owned keyed view slot.
    * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
    */
   apply(ctx: Context): void {
-    ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({
-      name: 'conversation.chat.toolview', key: 'ask_user_question', locale: NS,
+    ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({
+      name: 'tool.call.toolview', key: 'ask_user_question', locale: NS,
     }, AskQuestionRow))
   },
 }
diff --git a/packages/client/ui-conversation/src/client/toolviews/bash-sample.module.css b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.module.css
similarity index 100%
rename from packages/client/ui-conversation/src/client/toolviews/bash-sample.module.css
rename to packages/client/ui-tool/src/client/tool/toolviews/bash-sample.module.css
diff --git a/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx
similarity index 93%
rename from packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx
rename to packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx
index adf4ac4355..71a8503e69 100644
--- a/packages/client/ui-conversation/src/client/toolviews/bash-sample.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx
@@ -20,14 +20,14 @@ import {
   IconApiOutline14, IconChevronDownOutline14, IconInspectOutline12, StateDot, TerminalBlock,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ToolRowProps } from '../contract/slots.ts'
-import { terminalBlockLabels, terminalCardModel, terminalFailed } from '../contract/terminal-card-model.ts'
-import { toolRowModel, type ToolRowState } from '../contract/tool-call-model.ts'
-import { NS } from '../locales.ts'
+import type { ToolCallViewProps } from '../../contract/slots.ts'
+import { terminalBlockLabels, terminalCardModel, terminalFailed } from '../models/terminal-card-model.ts'
+import { toolRowModel, type ToolRowState } from '../models/tool-call-model.ts'
+import { CONVERSATION_NS as NS } from '../../locale.ts'
 import css from './bash-sample.module.css'
 
 /** Bash row props: the toolview runtime share plus the standard locale seat. */
-type BashRowProps = ToolRowProps & PropsLocale<'conversation'>
+type BashRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 function leadingFor(state: ToolRowState) {
   switch (state) {
@@ -171,11 +171,11 @@ export const bashToolviewSample = {
   name: 'bash-toolview-sample',
   inject: ['slots'],
   /**
-   * Register the bash row into the chat view's keyed toolview hole.
+   * Register the bash row into the Tool-owned keyed view slot.
    * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
    */
   apply(ctx: Context): void {
-    ctx.slots.inject('conversation.chat.toolview', () =>
-      ctx.slots.register({ name: 'conversation.chat.toolview', key: 'bash', locale: NS }, BashRow))
+    ctx.slots.inject('tool.call.toolview', () =>
+      ctx.slots.register({ name: 'tool.call.toolview', key: 'bash', locale: NS }, BashRow))
   },
 }
diff --git a/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/file-mutation-row.tsx
similarity index 77%
rename from packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
rename to packages/client/ui-tool/src/client/tool/toolviews/file-mutation-row.tsx
index fccb776c78..8dd7a37306 100644
--- a/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/file-mutation-row.tsx
@@ -11,14 +11,14 @@
 import type { Context } from 'cordis'
 import { IconEditOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ToolRowProps } from '../contract/slots.ts'
-import { diffCardModel } from '../contract/diff-card-model.ts'
-import { toolRowModel } from '../contract/tool-call-model.ts'
-import { ToolRow } from '../chat/ToolRow.tsx'
-import { NS } from '../locales.ts'
+import type { ToolCallViewProps } from '../../contract/slots.ts'
+import { diffCardModel } from '../models/diff-card-model.ts'
+import { toolRowModel } from '../models/tool-call-model.ts'
+import { ToolRow } from '../components/ToolRow.tsx'
+import { CONVERSATION_NS as NS } from '../../locale.ts'
 
 /** Full row props: the toolview runtime share plus the standard locale seat. */
-type FileMutationRowProps = ToolRowProps & PropsLocale<'conversation'>
+type FileMutationRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 /**
  * File-mutation row: icon + {Edit,Write} · {path} in the shared ToolRow chrome,
@@ -60,14 +60,14 @@ export const fileMutationToolview = {
   name: 'file-mutation-toolview',
   inject: ['slots'],
   /**
-   * Register the file-mutation row into the chat view's keyed toolview hole
+   * Register the file-mutation row into the Tool-owned keyed view slot
    * under both mutation tool names.
    * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
    */
   apply(ctx: Context): void {
-    ctx.slots.inject('conversation.chat.toolview', function* () {
-      yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'edit', locale: NS }, FileMutationRow)
-      yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'write', locale: NS }, FileMutationRow)
+    ctx.slots.inject('tool.call.toolview', function* () {
+      yield ctx.slots.register({ name: 'tool.call.toolview', key: 'edit', locale: NS }, FileMutationRow)
+      yield ctx.slots.register({ name: 'tool.call.toolview', key: 'write', locale: NS }, FileMutationRow)
     })
   },
 }
diff --git a/packages/client/ui-conversation/src/client/toolviews/plan-summary.ts b/packages/client/ui-tool/src/client/tool/toolviews/plan-summary.ts
similarity index 100%
rename from packages/client/ui-conversation/src/client/toolviews/plan-summary.ts
rename to packages/client/ui-tool/src/client/tool/toolviews/plan-summary.ts
diff --git a/packages/client/ui-conversation/src/client/toolviews/read-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx
similarity index 75%
rename from packages/client/ui-conversation/src/client/toolviews/read-row.tsx
rename to packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx
index 6d234ed82a..c404f535e5 100644
--- a/packages/client/ui-conversation/src/client/toolviews/read-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx
@@ -10,14 +10,14 @@
 import type { Context } from 'cordis'
 import { IconBrowseOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ToolRowProps } from '../contract/slots.ts'
-import { readCardModel } from '../contract/read-card-model.ts'
-import { toolRowModel } from '../contract/tool-call-model.ts'
-import { ToolRow } from '../chat/ToolRow.tsx'
-import { NS } from '../locales.ts'
+import type { ToolCallViewProps } from '../../contract/slots.ts'
+import { readCardModel } from '../models/read-card-model.ts'
+import { toolRowModel } from '../models/tool-call-model.ts'
+import { ToolRow } from '../components/ToolRow.tsx'
+import { CONVERSATION_NS as NS } from '../../locale.ts'
 
 /** Full row props: the toolview runtime share plus the standard locale seat. */
-type ReadRowProps = ToolRowProps & PropsLocale<'conversation'>
+type ReadRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 /**
  * Read row: icon + Read · {path} in the shared ToolRow chrome, with the file's
@@ -48,18 +48,18 @@ export function ReadRow({ toolName, block, cwd, openFile, inspect, t }: ReadRowP
 }
 
 /**
- * The read row as a plain registrant plugin following the chat toolview
+ * The read row as a plain registrant plugin following the atomic Tool-view
  * declaration across independent activation and reload lifetimes.
  */
 export const readToolview = {
   name: 'read-toolview',
   inject: ['slots'],
   /**
-   * Register the read row into the chat view's keyed toolview hole.
+   * Register the read row into the Tool-owned keyed view slot.
    * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
    */
   apply(ctx: Context): void {
-    ctx.slots.inject('conversation.chat.toolview', () =>
-      ctx.slots.register({ name: 'conversation.chat.toolview', key: 'read', locale: NS }, ReadRow))
+    ctx.slots.inject('tool.call.toolview', () =>
+      ctx.slots.register({ name: 'tool.call.toolview', key: 'read', locale: NS }, ReadRow))
   },
 }
diff --git a/packages/client/ui-conversation/src/client/toolviews/search-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
similarity index 80%
rename from packages/client/ui-conversation/src/client/toolviews/search-row.tsx
rename to packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
index d2f9eba089..f94809939a 100644
--- a/packages/client/ui-conversation/src/client/toolviews/search-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
@@ -14,14 +14,14 @@
 import type { Context } from 'cordis'
 import { IconSearchOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ToolRowProps } from '../contract/slots.ts'
-import { searchCardModel } from '../contract/search-card-model.ts'
-import { toolRowModel } from '../contract/tool-call-model.ts'
-import { ToolRow } from '../chat/ToolRow.tsx'
-import { NS } from '../locales.ts'
+import type { ToolCallViewProps } from '../../contract/slots.ts'
+import { searchCardModel } from '../models/search-card-model.ts'
+import { toolRowModel } from '../models/tool-call-model.ts'
+import { ToolRow } from '../components/ToolRow.tsx'
+import { CONVERSATION_NS as NS } from '../../locale.ts'
 
 /** Full row props: the toolview runtime share plus the standard locale seat. */
-type SearchRowProps = ToolRowProps & PropsLocale<'conversation'>
+type SearchRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 /**
  * Search row: icon + Search · {summary} in the shared ToolRow chrome, with the
@@ -61,7 +61,7 @@ export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {
 }
 
 /**
- * The search toolview follows the chat toolview declaration across activation
+ * The search view follows the atomic Tool-view declaration across activation
  * and reload. One component registers under both keys because `grep` and
  * `glob` are the same visual object discriminated by the result view's `kind`.
  */
@@ -69,14 +69,14 @@ export const searchToolview = {
   name: 'search-toolview',
   inject: ['slots'],
   /**
-   * Register the search row into the chat view's keyed toolview hole under both
+   * Register the search row into the Tool-owned keyed view slot under both
    * the `grep` and `glob` tool names.
    * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
    */
   apply(ctx: Context): void {
-    ctx.slots.inject('conversation.chat.toolview', function* () {
-      yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep', locale: NS }, SearchRow)
-      yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'glob', locale: NS }, SearchRow)
+    ctx.slots.inject('tool.call.toolview', function* () {
+      yield ctx.slots.register({ name: 'tool.call.toolview', key: 'grep', locale: NS }, SearchRow)
+      yield ctx.slots.register({ name: 'tool.call.toolview', key: 'glob', locale: NS }, SearchRow)
     })
   },
 }
diff --git a/packages/client/ui-conversation/src/client/toolviews/todo-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/todo-row.tsx
similarity index 83%
rename from packages/client/ui-conversation/src/client/toolviews/todo-row.tsx
rename to packages/client/ui-tool/src/client/tool/toolviews/todo-row.tsx
index d1072e2b4f..2556cfd8b4 100644
--- a/packages/client/ui-conversation/src/client/toolviews/todo-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/todo-row.tsx
@@ -1,5 +1,5 @@
 // todo_write toolview: plan-flavored summary row replacing the generic
-// "Tool call" card, registered into the keyed 'conversation.chat.toolview'
+// "Tool call" card, registered into the keyed 'tool.call.toolview'
 // hole like the bash sample (a product registration, not a sample). The row
 // composes ToolRow (chrome, running sweep, whole-row expand) and swaps in a
 // summary of the written list (counts + active items) from the call args, with
@@ -10,14 +10,14 @@
 import { IconChecklistOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { Context } from 'cordis'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ToolRowProps } from '../contract/slots.ts'
-import { toolRowModel } from '../contract/tool-call-model.ts'
-import { ToolRow } from '../chat/ToolRow.tsx'
-import { NS } from '../locales.ts'
+import type { ToolCallViewProps } from '../../contract/slots.ts'
+import { toolRowModel } from '../models/tool-call-model.ts'
+import { ToolRow } from '../components/ToolRow.tsx'
+import { CONVERSATION_NS as NS } from '../../locale.ts'
 import { planSummary, type PlanItemLike } from './plan-summary.ts'
 
 /** Todo row props: the toolview runtime share plus the standard locale seat. */
-type TodoRowProps = ToolRowProps & PropsLocale<'conversation'>
+type TodoRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 function isItem(value: unknown): value is PlanItemLike {
   return typeof value === 'object' && value !== null
@@ -81,18 +81,18 @@ export function TodoRow({ toolName, block, inspect, t }: TodoRowProps) {
 }
 
 /**
- * The todo row as a plain registrant plugin following the chat toolview
+ * The todo row as a plain registrant plugin following the atomic Tool-view
  * declaration across independent activation and reload lifetimes.
  */
 export const todoToolview = {
   name: 'todo-toolview',
   inject: ['slots'],
   /**
-   * Register the todo row into the chat view's keyed toolview hole.
+   * Register the todo row into the Tool-owned keyed view slot.
    * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
    */
   apply(ctx: Context): void {
-    ctx.slots.inject('conversation.chat.toolview', () =>
-      ctx.slots.register({ name: 'conversation.chat.toolview', key: 'todo_write', locale: NS }, TodoRow))
+    ctx.slots.inject('tool.call.toolview', () =>
+      ctx.slots.register({ name: 'tool.call.toolview', key: 'todo_write', locale: NS }, TodoRow))
   },
 }
diff --git a/packages/client/ui-conversation/src/client/toolviews/web-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/web-row.tsx
similarity index 77%
rename from packages/client/ui-conversation/src/client/toolviews/web-row.tsx
rename to packages/client/ui-tool/src/client/tool/toolviews/web-row.tsx
index ea323b7ee6..80489c478f 100644
--- a/packages/client/ui-conversation/src/client/toolviews/web-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/web-row.tsx
@@ -12,14 +12,14 @@
 import type { Context } from 'cordis'
 import { IconBrowseOutline16, IconSearchOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ToolRowProps } from '../contract/slots.ts'
-import { webCardModel } from '../contract/web-card-model.ts'
-import { toolRowModel } from '../contract/tool-call-model.ts'
-import { ToolRow } from '../chat/ToolRow.tsx'
-import { NS } from '../locales.ts'
+import type { ToolCallViewProps } from '../../contract/slots.ts'
+import { webCardModel } from '../models/web-card-model.ts'
+import { toolRowModel } from '../models/tool-call-model.ts'
+import { ToolRow } from '../components/ToolRow.tsx'
+import { CONVERSATION_NS as NS } from '../../locale.ts'
 
 /** Full row props: the toolview runtime share plus the standard locale seat. */
-type WebRowProps = ToolRowProps & PropsLocale<'conversation'>
+type WebRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 /** web_fetch reads one URL; web_search queries. Titles are figma literals. */
 const WEB_TITLES: Record<string, string> = {
@@ -55,7 +55,7 @@ export function WebRow({ toolName, block, inspect, t }: WebRowProps) {
 }
 
 /**
- * The web rows follow the chat toolview declaration across activation and
+ * The web rows follow the atomic Tool-view declaration across activation and
  * reload. One WebRow component registers under both web tool names.
  */
 export const webToolview = {
@@ -66,9 +66,9 @@ export const webToolview = {
    * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
    */
   apply(ctx: Context): void {
-    ctx.slots.inject('conversation.chat.toolview', function* () {
-      yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'web_search', locale: NS }, WebRow)
-      yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'web_fetch', locale: NS }, WebRow)
+    ctx.slots.inject('tool.call.toolview', function* () {
+      yield ctx.slots.register({ name: 'tool.call.toolview', key: 'web_search', locale: NS }, WebRow)
+      yield ctx.slots.register({ name: 'tool.call.toolview', key: 'web_fetch', locale: NS }, WebRow)
     })
   },
 }
diff --git a/packages/client/ui-tool/src/css-modules.d.ts b/packages/client/ui-tool/src/css-modules.d.ts
new file mode 100644
index 0000000000..8811db1264
--- /dev/null
+++ b/packages/client/ui-tool/src/css-modules.d.ts
@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
diff --git a/packages/client/ui-tool/src/index.ts b/packages/client/ui-tool/src/index.ts
new file mode 100644
index 0000000000..3f893bdf6a
--- /dev/null
+++ b/packages/client/ui-tool/src/index.ts
@@ -0,0 +1,4 @@
+/** Host loader entry for the browser-only Tool UI plugin. */
+
+/** Provides no host-side behavior. */
+export function apply(): void {}
diff --git a/packages/client/ui-tool/src/invariant.ts b/packages/client/ui-tool/src/invariant.ts
new file mode 100644
index 0000000000..bfee949195
--- /dev/null
+++ b/packages/client/ui-tool/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-tool`.
+ * @module @deepseek-ai/dsh-client-ui-tool/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-tool'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-tool-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: Tool composition is browser-only and contributes no
+ * events or cross-plugin mutable state; slot ownership is checked by ui-slots.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/client/ui-conversation/tests/ask-question-row.spec.tsx b/packages/client/ui-tool/tests/ask-question-row.spec.tsx
similarity index 95%
rename from packages/client/ui-conversation/tests/ask-question-row.spec.tsx
rename to packages/client/ui-tool/tests/ask-question-row.spec.tsx
index c6b7c60ba5..745bc2ff90 100644
--- a/packages/client/ui-conversation/tests/ask-question-row.spec.tsx
+++ b/packages/client/ui-tool/tests/ask-question-row.spec.tsx
@@ -13,8 +13,8 @@ import type { ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 // Export discipline: packages/client/AGENTS.md.
-import { AskQuestionRow, askQuestionToolview } from '../src/client/toolviews/ask-question-row.tsx'
-import { zh } from '../src/client/locales.ts'
+import { AskQuestionRow, askQuestionToolview } from '../src/client/tool/toolviews/ask-question-row.tsx'
+import { zh } from '../../ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
@@ -130,9 +130,9 @@ describe('AskQuestionRow', () => {
     const register = vi.fn(() => () => undefined)
     const inject = vi.fn((_name: string, callback: () => () => void) => callback())
     askQuestionToolview.apply({ slots: { inject, register } } as never)
-    expect(inject).toHaveBeenCalledWith('conversation.chat.toolview', expect.any(Function))
+    expect(inject).toHaveBeenCalledWith('tool.call.toolview', expect.any(Function))
     expect(register).toHaveBeenCalledWith(
-      { name: 'conversation.chat.toolview', key: 'ask_user_question', locale: 'conversation' },
+      { name: 'tool.call.toolview', key: 'ask_user_question', locale: 'conversation' },
       AskQuestionRow,
     )
   })
diff --git a/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
new file mode 100644
index 0000000000..dd733ba323
--- /dev/null
+++ b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
@@ -0,0 +1,149 @@
+// @vitest-environment jsdom
+/** Tool assembly acceptance through the real ui-conversation host. */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, waitFor } from '@testing-library/react'
+import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import type { ISession, SessionId, TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { apply as applyTool, inject as injectTool } from '../src/client/apply.ts'
+
+// The service reads its initial locale from the browser; these specs assert
+// the shipped Chinese copy, so they state the browser they assume.
+usePinnedBrowserLanguages('zh-CN')
+
+const SID = 's1' as SessionId
+
+/** jsdom has no ResizeObserver; the composer seat publishes its height through one. */
+class ResizeObserverStub {
+  observe(): void {}
+  unobserve(): void {}
+  disconnect(): void {}
+}
+
+afterEach(() => {
+  cleanup()
+  vi.unstubAllGlobals()
+})
+beforeEach(() => {
+  localStorage.clear()
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+})
+const TODOS: TodoItem[] = [
+  { content: '梳理需求', status: 'completed' },
+  { content: '实现 fixture 样本', status: 'in_progress' },
+  { content: '浏览器验收', status: 'pending' },
+]
+
+const todoResult = (seq: number): ToolResultNode => ({
+  kind: 'tool-result', seq, time: seq * 1_000, callId: `todo-${seq}`,
+  call: { name: 'todo_write', argsRaw: JSON.stringify({ todos: TODOS }) },
+  callTime: seq * 1_000 - 500,
+  content: [], isError: false, callView: null, resultView: null,
+})
+
+const bashResult = (seq: number, callId: string, over?: Partial<ToolResultNode>): ToolResultNode => ({
+  kind: 'tool-result', seq, time: seq * 1_000, callId,
+  call: { name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}' },
+  callTime: seq * 1_000 - 500,
+  content: [{ type: 'text', text: 'total 2\ndemo.txt\n' }], isError: false,
+  callView: { card: 'terminal', title: 'ls -la', description: 'List files' },
+  resultView: { card: 'terminal', output: 'total 2\ndemo.txt\n', exitCode: 0 },
+  ...over,
+})
+
+/** Test-owned AppFrame role: declares and renders the resident conversation area. */
+type AppRootProps = PropsRenderSlots<'conversation' | 'details'>
+function AppRoot({ renderSlot }: AppRootProps) {
+  return <>{renderSlot('conversation', {})}</>
+}
+
+const LAYOUT_CHILDREN = {
+  'conversation': { kind: 'single', scope: 'session-maybe' },
+  'details': { kind: 'single', scope: 'session' },
+} as const
+
+async function bench(nodes: ToolResultNode[]) {
+  const runtime = await SlotTestRuntime.create()
+  runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
+  const locale = new LocaleService(runtime.ctx)
+  runtime.provide('locale', locale)
+  runtime.slots.installLocale(locale)
+  await runtime.sessions.add({
+    id: SID,
+    summary: { title: 'S', displayTitle: 'S', cwd: '/proj' },
+    snapshot: { nodes },
+    session: {
+      loadOlder: vi.fn<ISession['loadOlder']>(),
+      prompt: vi.fn<ISession['prompt']>(async () => ({ ok: true, value: { accepted: true } })),
+    },
+  })
+  await runtime.root.declare(LAYOUT_CHILDREN, AppRoot)
+  await runtime.mount({ inject: [...injectConversation], apply: applyConversation })
+  await runtime.mount({ inject: [...injectTool], apply: applyTool })
+  return runtime
+}
+
+describe('todo_write assembly (product registrations, no outlet twins)', () => {
+  it('reaches the keyed toolview row and the dock plan strip, and the strip follows projection retirement', async () => {
+    const runtime = await bench([todoResult(3)])
+    // The dock strip reads the host-computed 'todos' projection.
+    runtime.sessions.behavior(SID).projections.set('todos', TODOS)
+    const view = runtime.renderRoot()
+
+    // Keyed toolview registration took the row (summary derived from args).
+    const row = view.container.querySelector('[data-tool="todo_write"]')
+    expect(row).not.toBeNull()
+    expect(row!.textContent).toContain('1/3 已完成 · 实现 fixture 样本')
+
+    // The plan strip sits in the input dock, fed by the projection
+    // (default-collapsed: the header summary shows; rows appear on expand).
+    const panel = view.container.querySelector('[data-testid="todo-panel"]')
+    expect(panel).not.toBeNull()
+    expect(panel!.textContent).toContain('1 已完成\u2002·\u20021 进行中\u2002·\u20021 待处理')
+    fireEvent.click(panel!.querySelector('button')!)
+    expect([...panel!.querySelectorAll('li')].map(li => li.getAttribute('data-status')))
+      .toEqual(['completed', 'in_progress', 'pending'])
+
+    // Next turn retires the standing plan (host pushes null): the strip
+    // clears while the historical row stays in the flow.
+    await runtime.flush()
+    runtime.sessions.behavior(SID).projections.set('todos', null)
+    await waitFor(() => {
+      expect(view.container.querySelector('[data-testid="todo-panel"]')).toBeNull()
+    })
+    expect(view.container.querySelector('[data-tool="todo_write"]')).not.toBeNull()
+    await runtime.dispose()
+  })
+})
+
+describe('terminal card assembly', () => {
+  it('both the keyed bash row and the fallback row reach the terminal card through the whole-row expand', async () => {
+    const runtime = await bench([
+      bashResult(3, 'c-keyed'),
+      // An unregistered tool with terminal views: GenericToolCard fallback.
+      bashResult(4, 'c-fallback', { call: { name: 'fx-bash', argsRaw: '{"command":"ls -la"}' } }),
+    ])
+    const view = runtime.renderRoot()
+
+    // Keyed BashRow: collapsed by default, the whole summary row is the toggle.
+    const keyedRow = view.container.querySelector('[data-sample="bash"]')
+    const keyed = keyedRow?.parentElement
+    expect(keyed?.querySelector('[data-terminal]')).toBeNull()
+    fireEvent.click(keyedRow!)
+    await waitFor(() => {
+      expect(keyed!.querySelector('[data-terminal]')).not.toBeNull()
+    })
+
+    // Fallback row: same unified expand interaction.
+    const fallback = view.container.querySelector('[data-tool="fx-bash"]')
+    expect(fallback).not.toBeNull()
+    expect(fallback!.querySelector('[data-terminal]')).toBeNull()
+    fireEvent.click(fallback!.querySelector('[data-expandable]')!)
+    await waitFor(() => {
+      expect(fallback!.querySelector('[data-terminal]')).not.toBeNull()
+    })
+    await runtime.dispose()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
similarity index 96%
rename from packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
rename to packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
index 8c4af6a921..8a1df2fd7b 100644
--- a/packages/client/ui-conversation/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
@@ -19,7 +19,8 @@ import type {
 import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
-import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { apply as applyTool, inject as injectTool } from '../src/client/apply.ts'
 
 const SID = 's1' as SessionId
 
@@ -80,7 +81,7 @@ function AppRoot({ renderSlot }: AppRootProps) {
   return <>{renderSlot('conversation', {})}</>
 }
 
-/** Same real-stack bench as the toolview-slot spec: SlotsService + renderer + this package's apply; fakes only at service seams. */
+/** Same real-stack bench as the toolview-slot spec: SlotsService + renderer + both owning package applies; fakes only at service seams. */
 async function bench(snapshot: ConversationSnapshot) {
   const ctx = new Context()
   const slotsFiber = ctx.plugin(SlotsService)
@@ -150,9 +151,11 @@ async function bench(snapshot: ConversationSnapshot) {
     },
   }, AppRoot)
 
-  const fiber = ctx.plugin({ inject: [...inject], apply })
+  const fiber = ctx.plugin({ inject: [...injectConversation], apply: applyConversation })
   await fiber.await()
-  return { ctx, slots, fiber, session, layout, workspaces }
+  const toolFiber = ctx.plugin({ inject: [...injectTool], apply: applyTool })
+  await toolFiber.await()
+  return { ctx, slots, fiber, toolFiber, session, layout, workspaces }
 }
 
 function mountApp(slots: SlotsService) {
diff --git a/packages/client/ui-tool/tests/coverage-tails.spec.tsx b/packages/client/ui-tool/tests/coverage-tails.spec.tsx
new file mode 100644
index 0000000000..720fa23255
--- /dev/null
+++ b/packages/client/ui-tool/tests/coverage-tails.spec.tsx
@@ -0,0 +1,116 @@
+// @vitest-environment jsdom
+// Tool presentation branch tails not reached by the main acceptance specs.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import type { RunningToolCall, SessionId, SessionListState, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
+import { ToolRow } from '../src/client/tool/components/ToolRow.tsx'
+import { BashRow } from '../src/client/tool/toolviews/bash-sample.tsx'
+import { zh } from '../../ui-conversation/src/client/locales.ts'
+
+type BashRowProps = Parameters<typeof BashRow>[0]
+
+// Mirrors the real lookup chain (conversation namespace, then common).
+const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
+
+afterEach(cleanup)
+
+const SID = 'root-1' as SessionId
+
+function listStore() {
+  return createSnapshotStore<SessionListState>({
+    ids: [SID],
+    byId: {
+      [SID]: { id: SID, title: 'r', displayTitle: 'r', running: false, blank: false, updatedAt: 0 },
+    },
+    current: undefined,
+    phase: 'ready',
+    subagentsByParent: {},
+    currentAddress: undefined,
+  })
+}
+
+function bashProps(block: RunningToolCall | ToolResultNode): BashRowProps {
+  return {
+    callId: 'c1', toolName: 'bash', block, openFile: vi.fn(),
+    sessionId: SID, useSessions: bindSnapshotSelector(listStore()),
+    t,
+  } as unknown as BashRowProps
+}
+
+describe('Tool presentation tails', () => {
+  it('ToolRow stopped state renders the warning dot in the leading slot', () => {
+    const view = render(
+      <ToolRow t={t} variant="bash" icon={<i data-testid="icon" />} title="Bash" summary="s" body={null} state="stopped" />,
+    )
+    expect(view.queryByTestId('icon')).toBeNull()
+    expect(view.container.querySelector('[data-state="stopped"]')).not.toBeNull()
+  })
+
+  it('a settled others-variant row renders the sparkle icon in the leading slot', () => {
+    const settled: ToolResultNode = {
+      kind: 'tool-result', seq: 2, time: 2_000, callId: 'c5',
+      call: { name: 'todo_write', argsRaw: '{"note":"x"}' },
+      callTime: 1_000,
+      content: [], isError: false, callView: null, resultView: null,
+    }
+    const props: GenericToolCardProps = {
+      callId: 'c5', toolName: 'todo_write', block: settled, openFile: vi.fn(), t,
+    }
+    const view = render(<GenericToolCard {...props} />)
+    expect(view.container.querySelector('[data-variant="others"] svg')).not.toBeNull()
+    expect(view.container.querySelector('[data-state="ok"]')).not.toBeNull()
+  })
+
+  it('BashRow summarizes the description without a row click target', () => {
+    const settled: ToolResultNode = {
+      kind: 'tool-result', seq: 3, time: 3_000, callId: 'c1',
+      call: { name: 'bash', argsRaw: '{"command":"make build","description":"Build"}' },
+      callTime: 2_000,
+      content: [], isError: false, callView: null, resultView: null,
+    }
+    const view = render(<BashRow {...bashProps(settled)} />)
+    const row = view.container.querySelector('[data-sample="bash"]')!
+    expect(row.textContent).toContain('Bash')
+    expect(row.textContent).toContain('Build')
+    expect(row.getAttribute('data-clickable')).toBeNull()
+  })
+
+  it('BashRow carries data-state for running and StateDots for error/stopped', () => {
+    const running: RunningToolCall = {
+      callId: 'c1', name: 'bash', argsRaw: '{"command":"ls","description":"List"}',
+      turn: 1, step: 1, time: 1_000, callView: null,
+    }
+    const errorResult: ToolResultNode = {
+      kind: 'tool-result', seq: 1, time: 1_000, callId: 'c1',
+      call: { name: 'bash', argsRaw: '{"command":"boom"}' },
+      callTime: 500,
+      content: [], isError: true, callView: null, resultView: null,
+    }
+    const stoppedResult: ToolResultNode = {
+      ...errorResult,
+      error: { name: 'E', code: 'interrupted' },
+    }
+
+    const runningView = render(<BashRow {...bashProps(running)} />)
+    expect(runningView.container.querySelector('[data-state="running"]')).not.toBeNull()
+    expect(runningView.getByText('Bash')).toBeTruthy()
+    expect(runningView.getByText('List')).toBeTruthy()
+    runningView.unmount()
+
+    const errorView = render(<BashRow {...bashProps(errorResult)} />)
+    expect(errorView.container.querySelector('[data-sample="bash"]')).not.toBeNull()
+    expect(errorView.container.querySelector('[data-state="error"]')).not.toBeNull()
+    expect(errorView.getByText('失败')).toBeTruthy()
+    errorView.unmount()
+
+    const stoppedView = render(<BashRow {...bashProps(stoppedResult)} />)
+    expect(stoppedView.container.querySelector('[data-state="stopped"]')).not.toBeNull()
+    expect(stoppedView.getByText('已停止')).toBeTruthy()
+  })
+})
diff --git a/packages/client/ui-conversation/tests/diff-card.spec.tsx b/packages/client/ui-tool/tests/diff-card.spec.tsx
similarity index 97%
rename from packages/client/ui-conversation/tests/diff-card.spec.tsx
rename to packages/client/ui-tool/tests/diff-card.spec.tsx
index 46d5e80524..0fe95c9564 100644
--- a/packages/client/ui-conversation/tests/diff-card.spec.tsx
+++ b/packages/client/ui-tool/tests/diff-card.spec.tsx
@@ -15,12 +15,13 @@ import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-client-conne
 import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../src/client/contract/diff-card-model.ts'
-import { createChatStore } from '../src/client/stores.ts'
-import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx'
-import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
-import { FileMutationRow, fileMutationToolview } from '../src/client/toolviews/file-mutation-row.tsx'
-import { zh } from '../src/client/locales.ts'
+import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../src/client/tool/models/diff-card-model.ts'
+import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
+import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { FileMutationRow, fileMutationToolview } from '../src/client/tool/toolviews/file-mutation-row.tsx'
+import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { zh } from '../../ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
@@ -323,6 +324,8 @@ describe('DetailsPanel diff Output section', () => {
     })
     return render(
       <DetailsPanel
+        SessionProvider={SessionProviderStub}
+        renderSlot={renderToolDetails(t)}
         sessionId={SID}
         useSession={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
         useSessions={bindSnapshotSelector(sessions)}
diff --git a/packages/client/ui-conversation/tests/read-card.spec.tsx b/packages/client/ui-tool/tests/read-card.spec.tsx
similarity index 95%
rename from packages/client/ui-conversation/tests/read-card.spec.tsx
rename to packages/client/ui-tool/tests/read-card.spec.tsx
index 786b437134..8b528355a5 100644
--- a/packages/client/ui-conversation/tests/read-card.spec.tsx
+++ b/packages/client/ui-tool/tests/read-card.spec.tsx
@@ -18,12 +18,13 @@ import type {
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
 import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { CHAT_READ_MAX_LINES, readCardModel } from '../src/client/contract/read-card-model.ts'
-import { createChatStore } from '../src/client/stores.ts'
-import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx'
-import { zh } from '../src/client/locales.ts'
-import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
-import { ReadRow, readToolview } from '../src/client/toolviews/read-row.tsx'
+import { CHAT_READ_MAX_LINES, readCardModel } from '../src/client/tool/models/read-card-model.ts'
+import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
+import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { ReadRow, readToolview } from '../src/client/tool/toolviews/read-row.tsx'
+import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
 
 afterEach(cleanup)
 
@@ -243,7 +244,7 @@ describe('ReadRow keyed toolview', () => {
     } } as unknown as Context
     readToolview.apply(ctx)
     // The row composes ToolRow, so it declares its locale namespace at the seat.
-    expect(registered).toEqual([{ name: 'conversation.chat.toolview', key: 'read', locale: 'conversation' }])
+    expect(registered).toEqual([{ name: 'tool.call.toolview', key: 'read', locale: 'conversation' }])
     expect(readToolview.inject).toEqual(['slots'])
   })
 })
@@ -269,6 +270,8 @@ describe('DetailsPanel Output section (read)', () => {
     })
     return render(
       <DetailsPanel
+        SessionProvider={SessionProviderStub}
+        renderSlot={renderToolDetails(t)}
         sessionId={SID}
         t={t}
         useSession={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
diff --git a/packages/client/ui-conversation/tests/search-card.spec.tsx b/packages/client/ui-tool/tests/search-card.spec.tsx
similarity index 97%
rename from packages/client/ui-conversation/tests/search-card.spec.tsx
rename to packages/client/ui-tool/tests/search-card.spec.tsx
index dcc6ca37ee..02d3eab476 100644
--- a/packages/client/ui-conversation/tests/search-card.spec.tsx
+++ b/packages/client/ui-tool/tests/search-card.spec.tsx
@@ -17,12 +17,13 @@ import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
 import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { CHAT_SEARCH_MAX_LINES, searchCardModel } from '../src/client/contract/search-card-model.ts'
-import { zh } from '../src/client/locales.ts'
-import { createChatStore } from '../src/client/stores.ts'
-import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx'
-import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
-import { SearchRow, searchToolview } from '../src/client/toolviews/search-row.tsx'
+import { CHAT_SEARCH_MAX_LINES, searchCardModel } from '../src/client/tool/models/search-card-model.ts'
+import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
+import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { SearchRow, searchToolview } from '../src/client/tool/toolviews/search-row.tsx'
+import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
 
 /** SearchRow now composes ToolRow, so its props include the locale `t` seat. */
 type SearchRowProps = Parameters<typeof SearchRow>[0]
@@ -385,6 +386,8 @@ describe('DetailsPanel Output section (search)', () => {
     })
     return render(
       <DetailsPanel
+        SessionProvider={SessionProviderStub}
+        renderSlot={renderToolDetails(t)}
         sessionId={SID}
         useSession={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
         useSessions={bindSnapshotSelector(sessions)}
diff --git a/packages/client/ui-conversation/tests/terminal-card.spec.tsx b/packages/client/ui-tool/tests/terminal-card.spec.tsx
similarity index 98%
rename from packages/client/ui-conversation/tests/terminal-card.spec.tsx
rename to packages/client/ui-tool/tests/terminal-card.spec.tsx
index f655979518..34c5744c01 100644
--- a/packages/client/ui-conversation/tests/terminal-card.spec.tsx
+++ b/packages/client/ui-tool/tests/terminal-card.spec.tsx
@@ -15,12 +15,13 @@ import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-client-conne
 import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { terminalCardModel, terminalFailed } from '../src/client/contract/terminal-card-model.ts'
-import { createChatStore } from '../src/client/stores.ts'
-import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx'
-import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
-import { BashRow } from '../src/client/toolviews/bash-sample.tsx'
-import { zh } from '../src/client/locales.ts'
+import { terminalCardModel, terminalFailed } from '../src/client/tool/models/terminal-card-model.ts'
+import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
+import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { BashRow } from '../src/client/tool/toolviews/bash-sample.tsx'
+import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { zh } from '../../ui-conversation/src/client/locales.ts'
 
 type BashRowProps = Parameters<typeof BashRow>[0]
 
@@ -460,6 +461,8 @@ describe('DetailsPanel Output section', () => {
     })
     return render(
       <DetailsPanel
+        SessionProvider={SessionProviderStub}
+        renderSlot={renderToolDetails(t)}
         sessionId={SID}
         useSession={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
         useSessions={bindSnapshotSelector(sessions)}
@@ -628,6 +631,8 @@ describe('DetailsPanel Output section', () => {
     const snap = snapshot()
     const view = render(
       <DetailsPanel
+        SessionProvider={SessionProviderStub}
+        renderSlot={renderToolDetails(t)}
         sessionId={SID}
         useSession={bindSnapshotSelector({ getSnapshot: () => snap, subscribe: () => () => {} })}
         useSessions={bindSnapshotSelector(createSnapshotStore<SessionListState>(
diff --git a/packages/client/ui-tool/tests/todo-row.spec.tsx b/packages/client/ui-tool/tests/todo-row.spec.tsx
new file mode 100644
index 0000000000..326821fc4e
--- /dev/null
+++ b/packages/client/ui-tool/tests/todo-row.spec.tsx
@@ -0,0 +1,158 @@
+// @vitest-environment jsdom
+/** todo_write atomic Tool presentation and its plan-summary model. */
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import { TodoRow, todoToolview } from '../src/client/tool/toolviews/todo-row.tsx'
+import { planSummary } from '../src/client/tool/toolviews/plan-summary.ts'
+import { CONVERSATION_NS as NS } from '../src/client/locale.ts'
+import { zh } from '../../ui-conversation/src/client/locales.ts'
+
+type TodoRowProps = Parameters<typeof TodoRow>[0]
+
+const t: TodoRowProps['t'] = makeTranslate(zh, commonZh)
+
+afterEach(cleanup)
+
+const LIST: TodoItem[] = [
+  { content: '搭骨架', status: 'completed' },
+  { content: '写组件', status: 'in_progress' },
+  { content: '补测试', status: 'pending' },
+]
+
+const PARALLEL: TodoItem[] = [
+  { content: '搭骨架', status: 'completed' },
+  { content: '写组件', status: 'in_progress' },
+  { content: '跑后台构建', status: 'in_progress' },
+  { content: '读源码', status: 'in_progress' },
+  { content: '补测试', status: 'pending' },
+]
+
+describe('planSummary', () => {
+  it('counts done/total and names the single active item with no extra count', () => {
+    expect(planSummary(LIST)).toEqual({ done: 1, total: 3, activeContent: '写组件', activeExtra: 0 })
+  })
+
+  it('reports the extra active count separately when several items are in progress', () => {
+    expect(planSummary(PARALLEL)).toEqual({ done: 1, total: 5, activeContent: '写组件', activeExtra: 2 })
+  })
+
+  it('has no hint when nothing is in progress', () => {
+    expect(planSummary([{ content: '都完了', status: 'completed' }]))
+      .toEqual({ done: 1, total: 1, activeContent: null, activeExtra: 0 })
+  })
+
+  it('has no hint when the first active item carries no usable content', () => {
+    expect(planSummary([{ status: 'in_progress' }, { content: 'x', status: 'in_progress' }]))
+      .toMatchObject({ activeContent: null, activeExtra: 0 })
+    expect(planSummary([{ content: 42, status: 'in_progress' }]).activeContent).toBeNull()
+    expect(planSummary([{ content: '', status: 'in_progress' }]).activeContent).toBeNull()
+    expect(planSummary([{ content: '   ', status: 'in_progress' }, { content: 'x', status: 'in_progress' }]))
+      .toMatchObject({ activeContent: null, activeExtra: 0 })
+  })
+
+  it('is empty-safe', () => {
+    expect(planSummary([])).toEqual({ done: 0, total: 0, activeContent: null, activeExtra: 0 })
+  })
+})
+
+const resultNode = (argsRaw: string, over?: Partial<ToolResultNode>): ToolResultNode => ({
+  kind: 'tool-result', seq: 10, time: 2_000, callTime: 1_000, callId: 'c1',
+  call: { name: 'todo_write', argsRaw },
+  content: [], isError: false, callView: null, resultView: null, ...over,
+})
+
+function rowProps(block: unknown): TodoRowProps {
+  return {
+    callId: 'c1', toolName: 'todo_write', block,
+    openFile: vi.fn(),
+    sessionId: 's1',
+    useSessions: () => undefined,
+    t,
+  } as unknown as TodoRowProps
+}
+
+describe('TodoRow', () => {
+  const ARGS = JSON.stringify({ todos: LIST })
+
+  it('summarizes counts and the active item from the call args', () => {
+    render(<TodoRow {...rowProps(resultNode(ARGS))} />)
+    expect(screen.getByText('更新任务清单')).toBeTruthy()
+    expect(screen.getByText('1/3 已完成 · 写组件')).toBeTruthy()
+  })
+
+  it('reports the extra active count outside the ellipsized summary text', () => {
+    const { container } = render(<TodoRow {...rowProps(resultNode(JSON.stringify({ todos: PARALLEL })))} />)
+    const text = screen.getByText('1/5 已完成 · 写组件')
+    const extra = screen.getByText('+2')
+    expect(text.contains(extra)).toBe(false)
+    expect(container.textContent).toContain('1/5 已完成 · 写组件+2')
+  })
+
+  it('omits the active clause when no item is in progress and reads running-call args', () => {
+    const args = JSON.stringify({ todos: [{ content: 'x', status: 'completed' }] })
+    render(<TodoRow {...rowProps({ callId: 'c1', name: 'todo_write', argsRaw: args, turn: 1, step: 1, time: 1_000, callView: null })} />)
+    expect(screen.getByText('1/1 已完成')).toBeTruthy()
+  })
+
+  it('keeps the counts when an active item has unusable content', () => {
+    const args = JSON.stringify({ todos: [{ content: 'done', status: 'completed' }, { content: 42, status: 'in_progress' }] })
+    const { container } = render(<TodoRow {...rowProps(resultNode(args))} />)
+    expect(screen.getByText('1/2 已完成')).toBeTruthy()
+    expect(container.textContent).not.toContain('+')
+  })
+
+  it('keeps non-ok execution states visible through the shared row states', () => {
+    const args = JSON.stringify({ todos: LIST })
+    const running = render(<TodoRow {...rowProps({ callId: 'c1', name: 'todo_write', argsRaw: args, turn: 1, step: 1, time: 1_000, callView: null })} />)
+    expect(running.container.querySelector('[data-state="running"]')).not.toBeNull()
+    expect(running.container.querySelector('[data-state="running"] svg')).not.toBeNull()
+    running.unmount()
+    const stopped = render(<TodoRow {...rowProps(resultNode(args, { isError: true, error: { name: 'Interrupted', code: 'interrupted' } }))} />)
+    expect(stopped.container.querySelector('[data-state="stopped"]')).not.toBeNull()
+  })
+
+  it('falls back to the generic summary on malformed args and marks the error state', () => {
+    const view = render(<TodoRow {...rowProps(resultNode('not json', { isError: true }))} />)
+    expect(view.container.querySelector('[data-state="error"]')).not.toBeNull()
+    expect(screen.getByText('todo_write · not json')).toBeTruthy()
+  })
+
+  it('falls back when parsed args carry no todos array', () => {
+    render(<TodoRow {...rowProps(resultNode('{"other":1}'))} />)
+    expect(screen.getByText('todo_write · {"other":1}')).toBeTruthy()
+  })
+
+  it('leading toggle expands the raw args body', () => {
+    render(<TodoRow {...rowProps(resultNode(ARGS))} />)
+    fireEvent.click(screen.getByRole('button', { expanded: false }))
+    expect(screen.getByRole('button', { expanded: true })).toBeTruthy()
+    expect(screen.getByText(/搭骨架/)).toBeTruthy()
+  })
+
+  it.each([
+    { label: 'null root', argsRaw: 'null' },
+    { label: 'non-object root', argsRaw: '42' },
+    { label: 'null items', argsRaw: '{"todos":[null]}' },
+  ])('falls back to the generic summary on valid JSON with an invalid shape ($label)', ({ argsRaw }) => {
+    render(<TodoRow {...rowProps(resultNode(argsRaw))} />)
+    expect(screen.getByText(`todo_write · ${argsRaw}`)).toBeTruthy()
+  })
+
+  it('window-truncated result falls back to the callId summary', () => {
+    render(<TodoRow {...rowProps(resultNode('', { call: null }))} />)
+    expect(screen.getByText('todo_write · c1')).toBeTruthy()
+  })
+
+  it('injects the keyed toolview declaration directly', () => {
+    expect(todoToolview.name).toBe('todo-toolview')
+    expect(todoToolview.inject).toEqual(['slots'])
+    const register = vi.fn(() => () => undefined)
+    const inject = vi.fn((_name: string, callback: () => () => void) => callback())
+    todoToolview.apply({ slots: { inject, register } } as never)
+    expect(inject).toHaveBeenCalledWith('tool.call.toolview', expect.any(Function))
+    expect(register).toHaveBeenCalledWith({ name: 'tool.call.toolview', key: 'todo_write', locale: NS }, TodoRow)
+  })
+})
diff --git a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
new file mode 100644
index 0000000000..76b24bc7ac
--- /dev/null
+++ b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
@@ -0,0 +1,63 @@
+// @vitest-environment jsdom
+/** ToolCallTree-owned root/subcall markers and selection projection. */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import type { CodeSubCall, ConversationSnapshot, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import type { ToolTreeProps } from '../src/client/contract/slots.ts'
+import { ToolCallTree } from '../src/client/tool/ToolCallTree.tsx'
+import { zh } from '../../ui-conversation/src/client/locales.ts'
+
+afterEach(cleanup)
+
+const t: ToolTreeProps['t'] = makeTranslate(zh, commonZh)
+
+const root = (callId: string, call: ToolResultNode['call']): ToolResultNode => ({
+  kind: 'tool-result', seq: 3, time: 3_000, callId, call, callTime: 2_000,
+  content: [], isError: false, callView: null, resultView: null,
+})
+
+function props(
+  block: ToolResultNode,
+  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]> = new Map(),
+  selectedCallId?: string,
+): ToolTreeProps {
+  const snapshot = { codeDispatches } as ConversationSnapshot
+  const useSession = ((selector: (value: ConversationSnapshot) => unknown) => selector(snapshot)) as ToolTreeProps['useSession']
+  const renderSlot = ((_key: string, _owner: object, options?: { fallback?: React.ReactNode }) =>
+    options?.fallback ?? null) as unknown as ToolTreeProps['renderSlot']
+  return {
+    useSession,
+    renderSlot,
+    callId: block.callId,
+    toolName: block.call?.name ?? '',
+    block,
+    selectedCallId,
+    openFile: vi.fn(),
+    inspectCall: vi.fn(),
+    t,
+  } as unknown as ToolTreeProps
+}
+
+describe('ToolCallTree', () => {
+  it('owns the root marker, generic fallback, and selected state for a window-truncated call', () => {
+    const block = root('w1', null)
+    const view = render(<ToolCallTree {...props(block, new Map(), 'w1')} />)
+    const row = view.container.querySelector('[data-chat-call-id="w1"]')
+    expect(row?.getAttribute('data-chat-anchor-key')).toBe('call:w1')
+    expect(row?.getAttribute('data-selected')).toBe('true')
+    expect(view.container.querySelector('[data-variant="others"]')).not.toBeNull()
+    expect(view.getByText('w1')).toBeTruthy()
+  })
+
+  it('marks a selected subcall without selecting its root', () => {
+    const block = root('parent', { name: 'run_code', argsRaw: '{"code":"return 1"}' })
+    const child: CodeSubCall = root('parent:code:1', { name: 'read', argsRaw: '{"path":"a.ts"}' })
+    const view = render(
+      <ToolCallTree {...props(block, new Map([['parent', [child]]]), child.callId)} />,
+    )
+    expect(view.container.querySelector('[data-chat-call-id="parent"]')?.hasAttribute('data-selected')).toBe(false)
+    expect(view.container.querySelector('[data-chat-call-id="parent:code:1"]')?.getAttribute('data-selected')).toBe('true')
+  })
+})
diff --git a/packages/client/ui-tool/tests/tool-details-render.tsx b/packages/client/ui-tool/tests/tool-details-render.tsx
new file mode 100644
index 0000000000..e61cd0aaa7
--- /dev/null
+++ b/packages/client/ui-tool/tests/tool-details-render.tsx
@@ -0,0 +1,22 @@
+/** Test adapter for the production conversation.details.tool registration. */
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionProviderComponent, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import type { DetailsSlotProps, DetailsToolOwnerProps } from '../../ui-conversation/src/client/contract/slots.ts'
+import { ToolDetails } from '../src/client/tool/ToolDetails.tsx'
+
+/** Framework session-area seat used by direct DetailsPanel tests. */
+export const SessionProviderStub: SessionProviderComponent = ({ children }) => children('s1' as SessionId)
+
+/**
+ * Bind ui-tool's details renderer to the conversation slot callback shape.
+ * @param t - conversation locale seat used by Tool cards.
+ * @returns a direct-test renderSlot implementation.
+ */
+export function renderToolDetails(t: TranslateNS<'conversation'>): DetailsSlotProps['renderSlot'] {
+  return (_key, owner) => {
+    // PropsRenderSlots keeps its key generic even for this one-key share;
+    // recover the concrete owner selected by the adapter's fixed slot.
+    const details = owner as DetailsToolOwnerProps
+    return <ToolDetails block={details.block} cwd={details.cwd} t={t} />
+  }
+}
diff --git a/packages/client/ui-conversation/tests/tool-row-styles.spec.ts b/packages/client/ui-tool/tests/tool-row-styles.spec.ts
similarity index 94%
rename from packages/client/ui-conversation/tests/tool-row-styles.spec.ts
rename to packages/client/ui-tool/tests/tool-row-styles.spec.ts
index 300266a69a..d187941049 100644
--- a/packages/client/ui-conversation/tests/tool-row-styles.spec.ts
+++ b/packages/client/ui-tool/tests/tool-row-styles.spec.ts
@@ -8,7 +8,7 @@ import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 
-const css = readFileSync(fileURLToPath(new URL('../src/client/chat/ToolRow.module.css', import.meta.url)), 'utf8')
+const css = readFileSync(fileURLToPath(new URL('../src/client/tool/components/ToolRow.module.css', import.meta.url)), 'utf8')
 /** Declarations only: the sheet's prose names the properties it explains. */
 const declarationText = css.replace(/\/\*[\s\S]*?\*\//g, ' ')
 
diff --git a/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx b/packages/client/ui-tool/tests/tool-row.spec.tsx
similarity index 83%
rename from packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
rename to packages/client/ui-tool/tests/tool-row.spec.tsx
index 246c79950d..ab7e1c80f7 100644
--- a/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.spec.tsx
@@ -1,44 +1,17 @@
 // @vitest-environment jsdom
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
 
 import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { classifyTool, resolveToolPath, resultText, toolRowModel } from '../src/client/contract/tool-call-model.ts'
-import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
-import { ToolRow } from '../src/client/chat/ToolRow.tsx'
-import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx'
-import { zh } from '../src/client/locales.ts'
-
-let nextAnimationFrameId = 1
-let animationFrames = new Map<number, FrameRequestCallback>()
-
-function flushAnimationFrames(count: number): void {
-  for (let index = 0; index < count; index += 1) {
-    const callbacks = [...animationFrames.values()]
-    animationFrames.clear()
-    for (const callback of callbacks) callback(index)
-  }
-}
-
-beforeEach(() => {
-  nextAnimationFrameId = 1
-  animationFrames = new Map()
-  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
-    const id = nextAnimationFrameId
-    nextAnimationFrameId += 1
-    animationFrames.set(id, callback)
-    return id
-  })
-  vi.stubGlobal('cancelAnimationFrame', (id: number) => {
-    animationFrames.delete(id)
-  })
-})
+import { classifyTool, resolveToolPath, resultText, toolRowModel } from '../src/client/tool/models/tool-call-model.ts'
+import { ToolRow } from '../src/client/tool/components/ToolRow.tsx'
+import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
+import { zh } from '../../ui-conversation/src/client/locales.ts'
 
 afterEach(() => {
   cleanup()
-  vi.unstubAllGlobals()
 })
 
 // Mirrors the real lookup chain (conversation namespace, then common).
@@ -369,83 +342,6 @@ describe('ToolRow', () => {
   })
 })
 
-describe('ThinkRow', () => {
-  it('follows the latest streaming line, scrolls to its end, then restores the settled first line', () => {
-    const view = render(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nNewest reasoning tokens' }]}
-        streaming
-      />,
-    )
-    const summary = view.getByText('Newest reasoning tokens')
-    Object.defineProperties(summary, {
-      scrollWidth: { configurable: true, value: 300 },
-      clientWidth: { configurable: true, value: 100 },
-    })
-
-    view.rerender(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nNewest reasoning tokens keep arriving' }]}
-        streaming
-      />,
-    )
-    expect(summary.scrollLeft).toBe(0)
-    flushAnimationFrames(2)
-    expect(summary.scrollLeft).toBe(0)
-    flushAnimationFrames(1)
-    expect(summary.scrollLeft).toBe(200)
-    expect(summary.getAttribute('data-follow-end')).toBe('true')
-
-    view.rerender(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nNewest reasoning tokens keep arriving\n' }]}
-        streaming={false}
-      />,
-    )
-    flushAnimationFrames(3)
-    expect(view.getByText('Inspect the session')).toBeTruthy()
-    expect(summary.scrollLeft).toBe(0)
-    expect(summary.hasAttribute('data-follow-end')).toBe(false)
-  })
-
-  it('expands from either Think or the reasoning summary', () => {
-    const view = render(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nCheck persistence' }]}
-        streaming={false}
-      />,
-    )
-    const row = view.getByRole('button')
-
-    fireEvent.click(view.getByText('Inspect the session'))
-    expect(row.getAttribute('aria-expanded')).toBe('true')
-    expect(view.getByText(/Check persistence/)).toBeTruthy()
-
-    fireEvent.click(view.getByText('Think'))
-    expect(row.getAttribute('aria-expanded')).toBe('false')
-  })
-
-  it('expanded Think drops the inline summary and renders plain prose, no IN card', () => {
-    const view = render(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nCheck persistence' }]}
-        streaming={false}
-      />,
-    )
-    fireEvent.click(view.getByText('Think'))
-    // The summary (first line) is gone from the row; only the body carries it.
-    expect(view.getAllByText(/Inspect the session/)).toHaveLength(1)
-    expect(view.queryByText('IN')).toBeNull()
-    expect(view.container.querySelector('[class*="ioCard"]')).toBeNull()
-    expect(view.container.querySelector('[class*="thinkBody"]')).not.toBeNull()
-  })
-})
-
 describe('GenericToolCard', () => {
   const props = (toolName: string, block: RunningToolCall | ToolResultNode): GenericToolCardProps => ({
     callId: 'c1', toolName, block, openFile: vi.fn(), t,
diff --git a/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
similarity index 84%
rename from packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
rename to packages/client/ui-tool/tests/toolview-slot.spec.tsx
index e2319157ea..846f81cc45 100644
--- a/packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx
+++ b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
@@ -1,8 +1,8 @@
 // @vitest-environment jsdom
-// The dissolved tool ring's acceptance chain on the REAL machinery stack:
+// The Tool presentation package's acceptance chain on the REAL machinery stack:
 // SlotTestRuntime (cordis Context + SlotsService ledger + the web-react
-// renderer) + this package's own apply — no outlet twins. Proves the keyed
-// 'conversation.chat.toolview' hole end to end: registered rows dispatch by
+// renderer) + ui-conversation and ui-tool apply — no outlet twins. Proves the
+// keyed 'tool.call.toolview' hole end to end: registered rows dispatch by
 // entryKey (the bash sample lands through its plugin), unregistered tools
 // fall back to GenericToolCard at the render site, live registration/unload
 // flips rows in place, duplicate keys fail loud, the inject channel feeds
@@ -15,8 +15,9 @@ import type { ISession, SessionId, ToolResultNode } from '@deepseek-ai/dsh-clien
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
-import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { apply as applyTool, inject as injectTool } from '@deepseek-ai/dsh-client-ui-tool/client'
+import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client'
 
 const SID = 's1' as SessionId
 
@@ -77,8 +78,9 @@ async function bench(nodes: ToolResultNode[]) {
     },
   })
   await runtime.root.declare(LAYOUT_CHILDREN, AppRoot)
-  const feature = await runtime.mount({ inject: [...inject], apply })
-  return { runtime, slots: runtime.slots, feature, layout }
+  await runtime.mount({ inject: [...injectConversation], apply: applyConversation })
+  await runtime.mount({ inject: [...injectTool], apply: applyTool })
+  return { runtime, slots: runtime.slots, layout }
 }
 
 describe('keyed toolview hole through the real machinery', () => {
@@ -144,7 +146,7 @@ describe('keyed toolview hole through the real machinery', () => {
     expect(view.getByText('Tool call')).toBeTruthy()
     let dispose = (): void => {}
     dispose = b.slots.register(
-      { name: 'conversation.chat.toolview', key: 'mystery' },
+      { name: 'tool.call.toolview', key: 'mystery' },
       () => <div data-testid="mystery-row" />)
     await b.runtime.flush()
     // Per-key version tick: the row flipped without a remount of the view.
@@ -160,7 +162,7 @@ describe('keyed toolview hole through the real machinery', () => {
   it('a duplicate key registration fails loud at load', async () => {
     const b = await bench([])
     expect(() => b.slots.register(
-      { name: 'conversation.chat.toolview', key: 'bash' },
+      { name: 'tool.call.toolview', key: 'bash' },
       () => null,
     )).toThrow(/key "bash"/)
     await b.runtime.dispose()
@@ -170,7 +172,7 @@ describe('keyed toolview hole through the real machinery', () => {
     const b = await bench([toolResult(3, 'c3', 'probe', '{"x":1}')])
     const poked: string[] = []
     b.slots.register({
-      name: 'conversation.chat.toolview',
+      name: 'tool.call.toolview',
       key: 'probe',
       // Two-way business face: data derived from the session id out, a
       // callback closing over it back in — the askuser-pattern inject shape.
@@ -178,7 +180,7 @@ describe('keyed toolview hole through the real machinery', () => {
         mark: `for:${sessionId}`,
         poke: () => { poked.push(sessionId) },
       }),
-    }, ({ mark, poke }: ToolRowProps & { mark: string; poke: () => void }) => (
+    }, ({ mark, poke }: ToolCallViewProps & { mark: string; poke: () => void }) => (
       <button data-testid="probe-row" onClick={poke}>{mark}</button>
     ))
     const view = b.runtime.renderRoot()
@@ -191,7 +193,7 @@ describe('keyed toolview hole through the real machinery', () => {
 })
 
 describe('registrant declaration injection', () => {
-  it('runs the plugin before ui-conversation and waits on the actual toolview declaration', async () => {
+  it('runs a registrant before ui-tool and waits on the actual toolview declaration', async () => {
     const runtime = await SlotTestRuntime.create()
     runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
     const locale = new LocaleService(runtime.ctx)
@@ -204,8 +206,8 @@ describe('registrant declaration injection', () => {
     let applyRuns = 0
     const registrantApply = (registrantCtx: typeof runtime.ctx): void => {
       applyRuns += 1
-      registrantCtx.slots.inject('conversation.chat.toolview', () => registrantCtx.slots.register(
-        { name: 'conversation.chat.toolview', key: 'late' }, () => null))
+      registrantCtx.slots.inject('tool.call.toolview', () => registrantCtx.slots.register(
+        { name: 'tool.call.toolview', key: 'late' }, () => null))
     }
     const late = runtime.ctx.plugin({
       name: 'late-registrant',
@@ -215,11 +217,12 @@ describe('registrant declaration injection', () => {
     await Promise.resolve()
     await late.await()
     expect(applyRuns).toBe(1)
-    expect(runtime.slots.entries('conversation.chat.toolview')).toHaveLength(0)
+    expect(runtime.slots.entries('tool.call.toolview')).toHaveLength(0)
 
     // Mounting the package declares the slot and activates the waiting entry.
-    await runtime.mount({ inject: [...inject], apply })
-    expect(runtime.slots.entries('conversation.chat.toolview').map(e => e.options.key))
+    await runtime.mount({ inject: [...injectConversation], apply: applyConversation })
+    await runtime.mount({ inject: [...injectTool], apply: applyTool })
+    expect(runtime.slots.entries('tool.call.toolview').map(e => e.options.key))
       .toEqual(expect.arrayContaining(['bash', 'late']))
     await runtime.dispose()
   })
diff --git a/packages/client/ui-tool/tests/toolview-type-chain.spec.tsx b/packages/client/ui-tool/tests/toolview-type-chain.spec.tsx
new file mode 100644
index 0000000000..b1aa7b9464
--- /dev/null
+++ b/packages/client/ui-tool/tests/toolview-type-chain.spec.tsx
@@ -0,0 +1,34 @@
+// The Tool-owned keyed-slot type chain: registration shape and composed
+// atomic-view props. Generic slot-system duals live in ui-slots tests.
+import { describe, expect, it } from 'vitest'
+import type { ReactNode } from 'react'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolCallViewProps } from '../src/client/contract/slots.ts'
+
+describe('toolview type negatives (compile-time; body never runs)', () => {
+  it('holds the negative samples as expect-error sites', () => {
+    const negatives = (slots: SlotsService) => {
+      // Keyed registration requires the key shape field.
+      // @ts-expect-error missing `key` on a keyed-slot registration
+      slots.register({ name: 'tool.call.toolview' }, (_p: ToolCallViewProps) => null)
+      slots.register(
+        // @ts-expect-error `id`/`order` belong to list slots, not the keyed hole
+        { name: 'tool.call.toolview', key: 'k', order: 1 },
+        (_p: ToolCallViewProps) => null)
+      const overreaching = (props: ToolCallViewProps): ReactNode => {
+        // @ts-expect-error loadOlder belongs to the conversation host, not an atomic Tool view
+        void props.loadOlder
+        return null
+      }
+      void overreaching
+      const drifted = (props: ToolCallViewProps): ReactNode => {
+        // @ts-expect-error the Tool call union has no pre-parsed args member
+        void props.block.argsParsed
+        return null
+      }
+      void drifted
+      return null as ReactNode
+    }
+    expect(negatives).toBeTypeOf('function')
+  })
+})
diff --git a/packages/client/ui-conversation/tests/web-card.spec.tsx b/packages/client/ui-tool/tests/web-card.spec.tsx
similarity index 94%
rename from packages/client/ui-conversation/tests/web-card.spec.tsx
rename to packages/client/ui-tool/tests/web-card.spec.tsx
index 220661ff88..743b450ca7 100644
--- a/packages/client/ui-conversation/tests/web-card.spec.tsx
+++ b/packages/client/ui-tool/tests/web-card.spec.tsx
@@ -16,15 +16,17 @@ import type {
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-import type { SelectionTarget, ToolRowOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { webCardModel } from '../src/client/contract/web-card-model.ts'
-import { createChatStore } from '../src/client/stores.ts'
-import { GenericToolCard } from '../src/client/chat/GenericToolCard.tsx'
-import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
-import { WebRow, webToolview } from '../src/client/toolviews/web-row.tsx'
+import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ToolCallOwnerProps } from '@deepseek-ai/dsh-client-ui-tool/client'
+import { webCardModel } from '../src/client/tool/models/web-card-model.ts'
+import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { GenericToolCard } from '../src/client/tool/toolviews/GenericToolCard.tsx'
+import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { WebRow, webToolview } from '../src/client/tool/toolviews/web-row.tsx'
+import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { zh } from '../src/client/locales.ts'
+import { zh } from '../../ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
@@ -121,7 +123,7 @@ describe('webCardModel', () => {
 })
 
 describe('chat row web body', () => {
-  const ownerProps = (block: RunningToolCall | ToolResultNode, toolName: string): ToolRowOwnerProps => ({
+  const ownerProps = (block: RunningToolCall | ToolResultNode, toolName: string): ToolCallOwnerProps => ({
     callId: block.callId, toolName, block, openFile: vi.fn(),
   })
   // WebRow reads only toolName/block off the full runtime share plus the locale
@@ -214,6 +216,8 @@ describe('DetailsPanel web Output section', () => {
     })
     return render(
       <DetailsPanel
+        SessionProvider={SessionProviderStub}
+        renderSlot={renderToolDetails(t)}
         sessionId={SID}
         useSession={bindSnapshotSelector({ getSnapshot: () => snapshot, subscribe: () => () => {} })}
         useSessions={bindSnapshotSelector(sessions)}
diff --git a/packages/client/ui-tool/tsconfig.json b/packages/client/ui-tool/tsconfig.json
new file mode 100644
index 0000000000..17516295fb
--- /dev/null
+++ b/packages/client/ui-tool/tsconfig.json
@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../locale"
+    },
+    {
+      "path": "../ui-conversation"
+    },
+    {
+      "path": "../ui-primitives"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/client/ui-tool/tsdown.config.ts b/packages/client/ui-tool/tsdown.config.ts
new file mode 100644
index 0000000000..1c66514f9a
--- /dev/null
+++ b/packages/client/ui-tool/tsdown.config.ts
@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-tool', ['lib/types/index.js', 'lib/types/invariant.js'])
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d604545dfd..ccbc67c764 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1284,6 +1284,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-theme':
         specifier: workspace:^
         version: link:../../client/ui-theme
+      '@deepseek-ai/dsh-client-ui-tool':
+        specifier: workspace:^
+        version: link:../../client/ui-tool
       '@deepseek-ai/dsh-client-ui-trajectory':
         specifier: workspace:^
         version: link:../../client/ui-trajectory
@@ -2201,9 +2204,6 @@ importers:
       '@deepseek-ai/dsh-client-test-runtime':
         specifier: workspace:^
         version: link:../test-runtime
-      '@deepseek-ai/dsh-client-ui-conversation':
-        specifier: workspace:^
-        version: link:../ui-conversation
       '@deepseek-ai/dsh-client-ui-primitives':
         specifier: workspace:^
         version: link:../ui-primitives
@@ -2213,6 +2213,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-client-ui-tool':
+        specifier: workspace:^
+        version: link:../ui-tool
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -2355,6 +2358,55 @@ importers:
         specifier: ^18.2.0
         version: 18.3.1
 
+  packages/client/ui-tool:
+    dependencies:
+      clsx:
+        specifier: ^2.0.0
+        version: 2.1.1
+    devDependencies:
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../connection
+      '@deepseek-ai/dsh-client-locale':
+        specifier: workspace:^
+        version: link:../locale
+      '@deepseek-ai/dsh-client-runtime':
+        specifier: workspace:^
+        version: link:../runtime
+      '@deepseek-ai/dsh-client-test-runtime':
+        specifier: workspace:^
+        version: link:../test-runtime
+      '@deepseek-ai/dsh-client-ui-conversation':
+        specifier: workspace:^
+        version: link:../ui-conversation
+      '@deepseek-ai/dsh-client-ui-primitives':
+        specifier: workspace:^
+        version: link:../ui-primitives
+      '@deepseek-ai/dsh-client-ui-slots':
+        specifier: workspace:^
+        version: link:../ui-slots
+      '@deepseek-ai/dsh-client-web-react':
+        specifier: workspace:^
+        version: link:../web-react
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@testing-library/react':
+        specifier: ^16.1.0
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@types/react':
+        specifier: ~18.3.1
+        version: 18.3.31
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+      react:
+        specifier: ^18.2.0
+        version: 18.3.1
+      react-dom:
+        specifier: ^18.2.0
+        version: 18.3.1(react@18.3.1)
+
   packages/client/ui-trajectory:
     dependencies:
       '@tanstack/react-virtual':
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 75719f1ecc..de9b63459c 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -162,6 +162,7 @@
       "@deepseek-ai/dsh-client-ui-layout": ["./packages/client/ui-layout/src"],
       "@deepseek-ai/dsh-client-ui-sidebar": ["./packages/client/ui-sidebar/src"],
       "@deepseek-ai/dsh-client-ui-conversation": ["./packages/client/ui-conversation/src"],
+      "@deepseek-ai/dsh-client-ui-tool": ["./packages/client/ui-tool/src"],
       "@deepseek-ai/dsh-client-ui-deliverables": ["./packages/client/ui-deliverables/src"],
       "@deepseek-ai/dsh-client-ui-slash": ["./packages/client/ui-slash/src"],
       "@deepseek-ai/dsh-client-ui-command": ["./packages/client/ui-command/src"],
diff --git a/tsconfig.client.json b/tsconfig.client.json
index 2a2b16e2e7..9ce72753c1 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -59,6 +59,7 @@
     { "path": "./packages/client/ui-layout" },
     { "path": "./packages/client/ui-sidebar" },
     { "path": "./packages/client/ui-conversation" },
+    { "path": "./packages/client/ui-tool" },
     { "path": "./packages/client/ui-deliverables" },
     { "path": "./packages/client/ui-workspace" },
     { "path": "./packages/client/ui-slash" },
diff --git a/vitest.config.ts b/vitest.config.ts
index f5a86ac7a9..597bca5618 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -162,6 +162,7 @@ export default defineConfig({
         'packages/client/web-react/src/*',
         'packages/client/runtime/src/*',
         'packages/client/ui-conversation/src/*',
+        'packages/client/ui-tool/src/*',
         'packages/client/ui-slots/src/*',
         'packages/client/ui-layout/src/*',
         'packages/client/web/src/*',

From fafd54fc03d1d44e3bab07cedeb913d8e636e077 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:19:27 +0800
Subject: [PATCH 249/516] docs(client): record Tool presentation ownership

---
 ...7-19-gui-web-client-architecture.i18n.yaml |   4 +-
 .../2026-07-19-gui-web-client-architecture.md |  24 ++--
 ...26-07-19-gui-web-client-architecture.zh.md |  24 ++--
 .../2026-07-23-toolview-dissolution.i18n.yaml |   4 +-
 .../2026-07-23-toolview-dissolution.md        |  16 ++-
 .../2026-07-23-toolview-dissolution.zh.md     |  16 ++-
 ...ient-tool-presentation-ownership.i18n.yaml |   6 +
 ...8-08-client-tool-presentation-ownership.md | 103 ++++++++++++++++++
 ...8-client-tool-presentation-ownership.zh.md | 103 ++++++++++++++++++
 9 files changed, 256 insertions(+), 44 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index 5376a626e6..2dccd44aae 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: 1a91d88818c374a1637b546fb3ddf6647af68570
-2026-07-19-gui-web-client-architecture.zh.md: 5c0bacde9836d45812895f5d9c89a0e8974ed7a1
+2026-07-19-gui-web-client-architecture.md: 4dc4558ea245baa17646f92b9b5e4c9a45b6a419
+2026-07-19-gui-web-client-architecture.zh.md: a306b5c82891840b96340f5464267cc9d861ef7e
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index 1a91d88818..4dc4558ea2 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -44,7 +44,7 @@ Implementation homes: registry core and the props-share types in `packages/clien
 
 A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer install seam), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
-There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. A tool row is a keyed child slot each view declares for itself — today `'conversation.chat.toolview'` (keyed/session), declared by the chat entry's `children` table; the key space is runtime-open (SlotMap declares slots, never keys), which is what the tool ring's open tool-name set required. The render site dispatches per row via `entryKey: toolName` with `GenericToolCard` as the call-site `fallback`; the owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openDetails`), and `ToolRowProps` composes it with the session standard kit for registrant components. Registrants are plain plugins with zero dedicated machinery: `ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency, independently from `ConversationService` ([decision](2026-08-05-slot-declaration-injection.md)). Interaction drafts and other row state ride the ordinary store seat. Trajectory/waterfall get same-shaped slots (names fixed by the slot-naming discipline `<domain>.<entry>.<hole>`, one shared owner type) that land with their own row render sites — RendersCheck rejects a declaration nobody renders, so the two slots cannot be declared early.
+There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: ui-conversation places each ordered root call into the single `'conversation.chat.tool'` seat and passes the Runtime-projected Code Dispatch children without interpreting their Tool names; ui-tool renders that root/child shape and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and both roots and children dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
 
 **Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport).
 
@@ -86,22 +86,24 @@ The glue package is the whole ctx↔React boundary; components stay framework-fr
 
 ## Directory shape
 
-Twelve `packages/client/*` packages (ui-slots, ui-primitives, web-react, connection, runtime, ui-layout, ui-sidebar, ui-conversation, ui-trajectory, ui-theme, i18n, web) plus `apps/web` — the vite application, a thin `main` over the shell's boot export. Plugin packages keep their browser half under `src/client/`; **every build artifact lands in `lib/`** — the node half as `lib/index.js`/`lib/invariant.js`, the browser bundle as `lib/client.js` (the shared tsdown client preset emits both; there is no `dist/` directory, and `exports["./client"]` points at `./lib/client.js`). Dependency direction: `ui-slots ← web-react ← runtime ← ui-* (peers) ← web`, with ui-primitives/ui-theme/i18n as zero-dependency side paths.
+Client packages live under `packages/client/*`, with `apps/web` as the thin Vite application over the shell's boot export. Plugin packages keep their browser half under `src/client/`; **every build artifact lands in `lib/`** — the node half as `lib/index.js`/`lib/invariant.js`, the browser bundle as `lib/client.js` (the shared tsdown client preset emits both; there is no `dist/` directory, and `exports["./client"]` points at `./lib/client.js`). `ui-slots`, web-react, and runtime form the infrastructure direction; feature plugins cooperate through services and slots rather than importing presentation implementations.
 
 A multi-domain plugin package additionally splits its client half by future package boundaries — ui-conversation is the exemplar:
 
 ```
 src/client/
-  contract/    the only shared face between domains (types + composed props shares)
-  service.ts   cross-domain orchestration (imports contract only)
-  skeleton/    domain: shell components (ConversationRoot/InputBar/EmptyState/DetailsPanel)
-  chat/        domain: the chat view
-  toolviews/   domain: sample tool-row registrants (third-party posture)
-  apply.ts     the ONLY file allowed to import across domains (assembly point)
-  index.ts     thin re-export shell (contract + apply + components)
+  contract/    shared slot and cross-domain types
+  service.ts   cross-domain orchestration
+  skeleton/    conversation shell and details host
+  chat/        ordered conversation view
+  input/       composer state machine
+  queue/       queued-message presentation
+  settings/    conversation settings rows
+  apply.ts     cross-domain assembly point
+  index.ts     public contract surface
 ```
 
-Domain implementation files never import a sibling domain — shared surfaces route through `contract/` (e.g. the toolviews samples take `ToolRowProps` from the contract, never chat internals). `scripts/verify-client-domain-graph.ts` enforces the layering (contract=0, domains=1, apply/index=2; imports may only point at levels ≤ own; sibling-domain edges fail). A future package split promotes each domain directory to a package and mechanically rewrites import paths.
+Domain implementation files never import a sibling domain; shared surfaces route through `contract/`. `scripts/verify-client-domain-graph.ts` enforces the layering (contract=0, domains=1, apply/index=2; imports may only point at levels ≤ own; sibling-domain edges fail). Tool presentation is already a separate `ui-tool` package and reaches chat and details only through the slots ui-conversation declares.
 
 ## How to develop
 
@@ -122,5 +124,5 @@ Token streams no longer shake the render tree: a frame storm costs unsubscribed
 | One statically-linked SPA bundle | Plugins must be host-composable at runtime (config-driven); a monolith re-couples every UI feature to one build |
 | window globals / import maps for shared deps | The DI require table keeps sharing explicit, fail-loud, and swappable; globals leak identity and version silently |
 | Business data in zustand slices | The event window/accumulator is a behavioral state machine, not a flat slice; the object layer keeps snapshot granularity and batching controllable |
-| String-keyed global component registry for tool rows | Per-view keyed child slots plus in-component session branching carry the same need with the one registration model; a parallel registry does not come back ([toolview dissolution](2026-07-23-toolview-dissolution.md)) |
+| Parallel string-keyed component registry for Tool rows | ui-tool's keyed child slot carries the runtime-open Tool-name set through the one slot registration model ([toolview dissolution](2026-07-23-toolview-dissolution.md)) |
 | Progressive/Suspense boot in P-I | One-flip boot is strictly simpler; the loader's per-plugin status face is kept so progressive lighting can land later without re-architecture |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index 5c0bacde98..a306b5c828 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -44,7 +44,7 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-
 
 服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。工具行是各视图自己声明的 keyed 子槽——今天是 `'conversation.chat.toolview'`（keyed/session），由 chat 条目的 `children` 表声明；key 空间运行时开放（SlotMap 声明槽、从不声明 key），这正是工具环「tool 名开放集」的原需求。渲染点逐行以 `entryKey: toolName` 分发、以 `GenericToolCard` 作调用点 `fallback`；owner 载荷是统一的 `ToolRowOwnerProps`（`callId`/`toolName`/`block`/`openDetails`），`ToolRowProps` 把它与 session 标配 kit 预组合供注册方组件取用。注册方就是普通插件、零专用设施：`ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row))`；声明本身就是加载与重载依赖，不依赖 `ConversationService`（[决策](2026-08-05-slot-declaration-injection.md)）。交互草稿等行内状态走普通 store 席位。trajectory/waterfall 得同形槽（槽名按槽名纪律 `<域>.<条目>.<孔位>` 已定死，共用一张 owner 类型），随各自的行渲染点落地——RendersCheck 拒绝无人渲染的声明，两槽无法提前声明。
+slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：ui-conversation 把每个已排序 root call 放进 single `'conversation.chat.tool'` seat，并透传 Runtime 已投影的 Code Dispatch child，不解释其 Tool 名称；ui-tool 渲染该 root/child 形状，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与 child 都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
 
 **scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 
@@ -86,22 +86,24 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 
 ## 目录形态
 
-十二个 `packages/client/*` 包（ui-slots、ui-primitives、web-react、connection、runtime、ui-layout、ui-sidebar、ui-conversation、ui-trajectory、ui-theme、i18n、web）加 `apps/web`——vite 应用，壳 boot 导出之上的薄 `main`。插件包的浏览器半边在 `src/client/` 下；**一切构建产物落 `lib/`**——node 半边为 `lib/index.js`/`lib/invariant.js`，浏览器 bundle 为 `lib/client.js`（共享 tsdown client 预设两者皆出；无 `dist/` 目录，`exports["./client"]` 指向 `./lib/client.js`）。依赖方向：`ui-slots ← web-react ← runtime ← ui-*（并列）← web`，ui-primitives/ui-theme/i18n 为零依赖旁路。
+Client 包位于 `packages/client/*`，`apps/web` 是壳 boot 导出之上的薄 Vite 应用。插件包的浏览器半边在 `src/client/` 下；**一切构建产物落 `lib/`**——node 半边为 `lib/index.js`/`lib/invariant.js`，浏览器 bundle 为 `lib/client.js`（共享 tsdown client 预设两者皆出；无 `dist/` 目录，`exports["./client"]` 指向 `./lib/client.js`）。`ui-slots`、web-react 与 runtime 构成基础设施方向；功能插件通过 service 与 slot 协作，不导入展示实现。
 
 多域插件包的 client 半边还按未来包边界再拆——ui-conversation 即样板：
 
 ```
 src/client/
-  contract/    the only shared face between domains (types + composed props shares)
-  service.ts   cross-domain orchestration (imports contract only)
-  skeleton/    domain: shell components (ConversationRoot/InputBar/EmptyState/DetailsPanel)
-  chat/        domain: the chat view
-  toolviews/   domain: sample tool-row registrants (third-party posture)
-  apply.ts     the ONLY file allowed to import across domains (assembly point)
-  index.ts     thin re-export shell (contract + apply + components)
+  contract/    shared slot and cross-domain types
+  service.ts   cross-domain orchestration
+  skeleton/    conversation shell and details host
+  chat/        ordered conversation view
+  input/       composer state machine
+  queue/       queued-message presentation
+  settings/    conversation settings rows
+  apply.ts     cross-domain assembly point
+  index.ts     public contract surface
 ```
 
-域实现文件永不 import 兄弟域——共享面一律走 `contract/`（如 toolviews 样例从契约取 `ToolRowProps`，永不碰 chat 内部）。`scripts/verify-client-domain-graph.ts` 把守分层（contract=0、域=1、apply/index=2；import 只准指向 ≤ 自己的层级；兄弟域边即失败）。将来拆包=每个域目录升格为包+机械改写 import 路径。
+各领域实现文件不 import 兄弟领域；共享面统一经过 `contract/`。`scripts/verify-client-domain-graph.ts` 把守分层（contract=0、domain=1、apply/index=2；import 只准指向不高于自身的层级；兄弟领域依赖会失败）。Tool 展示已经拆为独立 `ui-tool` 包，只通过 ui-conversation 声明的 slot 到达 chat 与 details。
 
 ## 怎么开发
 
@@ -122,5 +124,5 @@ token 流不再震荡渲染树：帧风暴对未订阅会话只花一个脏位
 | 静态链接的单 SPA bundle | 插件必须由 host 在运行时按配置组合；单体把每个 UI 功能重新耦回一次构建 |
 | window 全局变量 / import map 供共享依赖 | DI require 表让共享显式、大声失败、可替换；全局变量静默泄漏身份与版本 |
 | 业务数据进 zustand 切片 | 事件窗口/累积器是行为状态机，不是扁平切片；对象层保住快照粒度与合批的可控性 |
-| 工具行走字符串键的全局组件注册表 | per-view keyed 子槽 + 组件内会话分支以唯一注册模型承载同一需求；平行 registry 不复活（[toolview 溶解](2026-07-23-toolview-dissolution.md)） |
+| Tool 行使用平行的字符串键组件注册表 | ui-tool 的 keyed 子 slot 通过唯一的 slot 注册模型承载运行时开放的 Tool 名称集合（[toolview 溶解](2026-07-23-toolview-dissolution.md)） |
 | P-I 就做渐进/Suspense 启动 | 一次成型严格更简单；loader 的按插件状态面已保留，渐进点亮日后可落地而无需重构 |
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
index 90d13fcfea..09f0c27732 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.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 .agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
-2026-07-23-toolview-dissolution.md: 97d8beb4de43d9bc6348d942e5460d0321592b32
-2026-07-23-toolview-dissolution.zh.md: db93c6252d5d42d1fd85ce81ad430d95f4324cf2
+2026-07-23-toolview-dissolution.md: be1bd9d161714194855988d76a632c667fae8c84
+2026-07-23-toolview-dissolution.zh.md: afe5e03e8345fca2a0f097d86873974f6d417ff2
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
index 97d8beb4de..be1bd9d161 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-23-toolview-dissolution.zh.md)
 
-> Scope: why the standalone tool ring (ToolViewRegistry/ctx.toolviews/outlet) was retired and what replaced it. The [web client architecture note](2026-07-19-gui-web-client-architecture.md) carries the shipped-state narrative this decision produced; the [slot system standard](2026-07-22-slot-type-chain-implementation.md) owns the registration model everything now runs on.
+> Scope: why the standalone tool ring (ToolViewRegistry/ctx.toolviews/outlet) was retired and what replaced it. The [web client architecture note](2026-07-19-gui-web-client-architecture.md) carries the shipped-state narrative this decision produced; the [slot system standard](2026-07-22-slot-type-chain-implementation.md) owns the registration model everything now runs on. The later [Client Tool presentation ownership](2026-08-08-client-tool-presentation-ownership.md) decision supersedes only this note's per-view placement: Tool-name dispatch remains a keyed slot rather than a parallel registry.
 
 ## Problem
 
@@ -14,24 +14,22 @@ After the view ring dissolved into the slot system, the client kept exactly one
 
 The tool ring is gone as independent infrastructure: a tool row is a **keyed child slot each view declares for itself**, and the client has exactly one registration model. The justification above was hollow — a keyed slot's *key space* is already runtime-open (SlotMap declares slots, never keys; the ask-user composer's `key: 'question'` was the precedent), so the open tool-name set fits `entryKey` dispatch natively.
 
-Shipped shape (current-state narrative also in the [architecture note](2026-07-19-gui-web-client-architecture.md)): the chat entry's `children` table declares `'conversation.chat.toolview'` (keyed/session); the render site dispatches per row via `entryKey: toolName` with `GenericToolCard` as the call-site `fallback` (the default card is domain property; the fallback option is ordinary renderSlot grammar). The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openDetails` — details being a session-level facility, not chat-private), and `ToolRowProps` pre-composes it with the session standard kit for registrant components. A registrant is a plain plugin using `ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row))`; the declaration itself governs activation and replacement, without a false `ConversationService` edge ([decision](2026-08-05-slot-declaration-injection.md)). The bash sample is the third-party-posture exemplar and paints the same ToolRow chrome as Think (`Bash · {description}`). Trajectory/waterfall toolview slots share this exact shape (names fixed by the slot-naming discipline `<domain>.<entry>.<hole>`, one shared owner type) and land with their own row render sites — RendersCheck rejects a declaration nobody renders, so the type system, not convention, blocks early empty declarations.
-
-Registry-era responsibilities all have successor homes: inject caching and row error isolation ride the framework renderer (entry×scope cache, per-entry `SlotErrorBoundary`); subscribe/getVersion ride the slot core's per-key version machinery; the future "store seat" is the ordinary store seat keyed slots already have (interaction-draft durability is its first named consumer); miss fallback is the call-site `fallback` option.
+This decision originally placed `'conversation.chat.toolview'` under the chat entry and made the chat render site dispatch each row. The follow-up [Tool presentation ownership](2026-08-08-client-tool-presentation-ownership.md) moves that placement into a whole-Tool seat and gives `ui-tool` one keyed `'tool.call.toolview'` child slot. That follow-up changes the presentation owner, not this decision's core constraint: Tool registration continues to use ordinary keyed-slot machinery, with framework-owned activation, replacement, caching, error isolation, versioning, and fallback behavior.
 
 ## Accepted semantic changes
 
-Four behavioral deltas were accepted deliberately, not overlooked. Cross-view appearance is per-view registration — a row must adapt to each view's layout anyway, so one registration per view is the correct coupling, and reuse is the same component in two register calls. Same-key double registration is a loud throw where the registry let later-wins silently override — a discipline correction, not a loss. Session-dimension dispatch, when a row needs it, belongs inside the component (the standard kit already carries `useSessions`), not in registry predicates — there is no shipped session-variant exemplar today. Registry-level shape override by third parties (a scoped registration shadowing a global one) has no equivalent; a real future need routes through key-naming conventions or a small in-component resolver, never a revived parallel registry.
+Four behavioral deltas were accepted deliberately, not overlooked. Cross-view appearance was initially per-view registration; the follow-up note records why root/subcall composition later justified one Tool-wide presentation owner. Same-key double registration is a loud throw where the registry let later-wins silently override — a discipline correction, not a loss. Session-dimension dispatch, when a row needs it, belongs inside the component (the standard kit already carries `useSessions`), not in registry predicates — there is no shipped session-variant exemplar today. Registry-level shape override by third parties (a scoped registration shadowing a global one) has no equivalent; a real future need routes through key-naming conventions or a small in-component resolver, never a revived parallel registry.
 
 ## Alternatives considered
 
-**Keep the standalone registry (the original shape).** Rejected: each of its multi-dimensional dispatch axes has a more correct home — the view dimension belongs to each view's own declared child slot (declaring is claiming, so specialization ownership lands right), and the session dimension belongs inside the component, which already holds the standard kit. What remained after both moves was a second copy of slot machinery with no distinguishing capability.
+**Keep the standalone registry (the original shape).** Rejected: each of its multi-dimensional dispatch axes has a more correct home — presentation ownership belongs to an explicitly declared child slot, and the session dimension belongs inside the component, which already holds the standard kit. What remains is a second copy of slot machinery with no distinguishing capability.
 
-**Promote `renderToolView` into the standard kit and move the registry into the runtime package.** Rejected: "tool row" is a conversation-domain concept; hoisting it into runtime would leak a domain vocabulary into the framework layer and still leave two registration models.
+**Promote `renderToolView` into the standard kit and move the registry into the runtime package.** Rejected: Tool presentation is Client UI vocabulary; hoisting it into runtime would leak presentation into the data object layer and still leave two registration models.
 
 **Derive slot declarations from subscription refCounts** (declare the slot implicitly when the first registrant subscribes). Rejected for implicit coupling and debounce complexity; noted as a possible revisit only if a genuinely multi-viewer surface appears.
 
-**A thin `registerToolView` facade over slots.register.** Deferred, not rejected: after dissolution the facade would carry only compile-time sugar (slot-name literal narrowing, tool→key vocabulary, props pre-composition) with zero runtime. Per "enforce at the operation boundary" (a facade is not an enforcement point) and "don't split preemptively" (today's registrant population is one bash sample), it stays unbuilt; the type sugar ships as the exported `ToolRowProps` alias. Regret clause: if registrants grow to three-to-five or a bulk-registration pattern appears, the facade is ten lines added without disturbing direct registration.
+**A thin `registerToolView` facade over slots.register.** Deferred, not rejected: after dissolution the facade would carry only compile-time sugar (slot-name literal narrowing, tool→key vocabulary, props pre-composition) with zero runtime. Per "enforce at the operation boundary" (a facade is not an enforcement point), it stays unbuilt; the useful type composition ships as the exported Tool view props alias. A later facade can be added without disturbing direct registration if repeated registration ceremony justifies it.
 
 ## Consequences
 
-The client has one registration model; auditing who renders tool rows = reading register calls, the same audit as every other slot. Registrants get the framework's error isolation, inject caching, and store seat for free — no capability ships twice. The costs are the accepted semantic changes above (chiefly: per-view registration for cross-view rows, and no third-party registry-level override). Independent registrants name the typed slot in `ctx.slots.inject`, so the dependency is explicit and follows declaration replacement without a service-order convention.
+The client has one registration model; auditing who renders Tool calls means reading slot register calls, the same audit as every other slot. Registrants get the framework's error isolation, inject caching, and store seat for free — no capability ships twice. The costs are the accepted semantic changes above, chiefly loud duplicate-key failure and no third-party registry-level override. Independent registrants name the typed slot in `ctx.slots.inject`, so the dependency is explicit and follows declaration replacement without a service-order convention.
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
index db93c6252d..afe5e03e83 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-23-toolview-dissolution.md) | 中文
 
-> 范围：独立工具环（ToolViewRegistry/ctx.toolviews/outlet）为何退役、被什么取代。本决策产出的落地态叙述归 [Web 客户端架构注](2026-07-19-gui-web-client-architecture.md)；一切现在所运行其上的注册模型归 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 所有。
+> 范围：独立工具环（ToolViewRegistry/ctx.toolviews/outlet）为何退役、被什么取代。本决策产出的落地态叙述归 [Web 客户端架构注](2026-07-19-gui-web-client-architecture.md)；一切现在所运行其上的注册模型归 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md)所有。后续的 [Client Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)决策仅取代本篇的 per-view 放置方式：Tool 名称分发仍使用 keyed slot，而非平行注册表。
 
 ## Problem
 
@@ -14,24 +14,22 @@ Status: implemented
 
 工具环作为独立基础设施已消失：工具行是**各视图为自己声明的 keyed 子槽**，client 全域只剩一种注册模型。上述理由是空的——keyed slot 的 *key 空间*本就运行时开放（SlotMap 声明槽、从不声明 key；ask-user composer 的 `key: 'question'` 即先例），开放的 tool 名集合天然适配 `entryKey` 分发。
 
-落地形态（现状叙述同见[架构注](2026-07-19-gui-web-client-architecture.md)）：chat 条目的 `children` 表声明 `'conversation.chat.toolview'`（keyed/session）；渲染点逐行以 `entryKey: toolName` 分发、以 `GenericToolCard` 作调用点 `fallback`（默认卡片是域产权；fallback 选项就是普通 renderSlot 文法）。owner 载荷是统一的 `ToolRowOwnerProps`（`callId`/`toolName`/`block`/`openDetails`——details 是会话级设施，非 chat 私货），`ToolRowProps` 把它与 session 标配 kit 预组合供注册方组件取用。注册方是使用 `ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row))` 的普通插件；声明本身控制激活与替换，不再引入虚假的 `ConversationService` 依赖（[决策](2026-08-05-slot-declaration-injection.md)）。bash 样例即第三方姿态的样板，并与 Think 绘制同一套 ToolRow chrome（`Bash · {description}`）。trajectory/waterfall 的 toolview 槽共用这套形状（槽名按槽名纪律 `<域>.<条目>.<孔位>` 定死，共用一张 owner 类型），随各自的行渲染点落地——RendersCheck 拒绝无人渲染的声明，挡住提前空声明的是类型系统而非约定。
-
-registry 时代的职责各有后继居所：inject 缓存与行错误隔离乘框架渲染器（entry×scope 缓存、per-entry `SlotErrorBoundary`）；subscribe/getVersion 乘 slot core 的 per-key 版本机；将来的「store 席位」就是 keyed slot 本就拥有的普通 store 席位（交互草稿耐久性是其首个具名消费者）；miss 兜底即调用点 `fallback` 选项。
+本决策最初把 `'conversation.chat.toolview'` 放在 chat 条目下，由 chat 渲染点逐行分发。后续的 [Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)引入整体 Tool 席位，并让 `ui-tool` 拥有唯一的 keyed `'tool.call.toolview'` 子 slot。后续决策改变的是展示所有者，而非本决策的核心约束：Tool 注册继续使用普通 keyed-slot 机制，激活、替换、缓存、错误隔离、版本与 fallback 行为仍归框架所有。
 
 ## 接受的语义变化
 
-四项行为增量是刻意接受而非疏漏。跨视图出场=逐视图注册——行本须适配各视图版式，一视图一注册是正确耦合，复用即同一组件写两次 register。同 key 重复注册从注册表的 later-wins 静默覆盖变为 loud throw——纪律修正而非损失。会话维分发若行需要，归组件内部（标配 kit 已带 `useSessions`），不走注册表谓词——今天没有已落地的会话变体样例。第三方在 registry 级覆盖形态（scoped 注册压过 global）不复存在；真出现的未来需求走 key 命名空间约定或组件内小 resolver，永不复活平行注册表。
+四项行为增量是刻意接受而非疏漏。跨视图出场最初采用逐视图注册；后续 Note 记录了 root/subcall 编排为何足以支持一个 Tool 级展示所有者。同 key 重复注册从注册表的 later-wins 静默覆盖变为 loud throw——纪律修正而非损失。会话维分发若行需要，归组件内部（标配 kit 已带 `useSessions`），不走注册表谓词——今天没有已落地的会话变体样例。第三方在 registry 级覆盖形态（scoped 注册压过 global）不复存在；真出现的未来需求走 key 命名空间约定或组件内小 resolver，永不复活平行注册表。
 
 ## Alternatives considered
 
-**保留独立注册表（原形态）。** 拒绝：其多维分发的每一维都有更正确的家——视图维归各视图自己声明的子槽（declaring is claiming，特化面权属自然落对），会话维归已持有标配 kit 的组件内部。两步移完后剩下的只是一份没有任何独有能力的 slot 机器副本。
+**保留独立注册表（原形态）。** 拒绝：其多维分发的每一维都有更正确的家——展示所有权归显式声明的子 slot，会话维归已持有标配 kit 的组件内部。两步移完后剩下的只是一份没有任何独有能力的 slot 机器副本。
 
-**把 `renderToolView` 提进标配 kit、注册表迁入 runtime 包。** 拒绝：「工具行」是 conversation 域概念；上提进 runtime 会把域词汇泄漏进框架层，且依然留着两套注册模型。
+**把 `renderToolView` 提进标配 kit、注册表迁入 runtime 包。** 拒绝：Tool 展示是 Client UI 词汇；上提进 runtime 会把展示概念泄漏进数据对象层，且依然留着两套注册模型。
 
 **以订阅 refCount 推导槽声明**（首个注册方订阅时隐式声明槽）。拒绝：隐式耦合加去抖复杂度；记为将来真出现多观看面时的备选。
 
-**slots.register 之上的薄 `registerToolView` 门面。** 缓建而非拒绝：溶解后该门面只剩编译期三糖（槽名字面量收窄、tool→key 词汇翻译、props 预组合），运行时为零。按「enforce at the operation boundary」（门面不是强制点）与「don't split preemptively」（今天注册方人口只有一个 bash 样例）保持不建；类型糖以导出的 `ToolRowProps` 别名兑现。后悔药条款：注册方长到三五家或出现批量注册模式时，门面十行可补，不扰直注。
+**slots.register 之上的薄 `registerToolView` 门面。** 缓建而非拒绝：溶解后该门面只剩编译期语法糖（slot 名字面量收窄、tool→key 词汇翻译、props 预组合），运行时为零。按「enforce at the operation boundary」（门面不是强制点）保持不建；有用的类型组合以导出的 Tool view props 别名兑现。若重复注册仪式今后足以证明其价值，可在不扰动直接注册的前提下补充门面。
 
 ## Consequences
 
-client 只有一种注册模型；审计谁渲染工具行 = 读 register 调用，与其他所有 slot 同一套审计。注册方免费获得框架的错误隔离、inject 缓存与 store 席位——没有能力要建两遍。代价即上文接受的语义变化（主要是：跨视图行要逐视图注册、第三方无 registry 级覆盖）。独立注册方在 `ctx.slots.inject` 中点名有类型约束的 slot，因此依赖关系既显式，又能跟随声明替换，无需服务顺序约定。
+client 只有一种注册模型；审计谁渲染 Tool 调用就是读 slot register 调用，与其他所有 slot 同一套审计。注册方免费获得框架的错误隔离、inject 缓存与 store 席位——没有能力要建两遍。代价即上文接受的语义变化，主要是重复 key 会 loud failure，且第三方无 registry 级覆盖。独立注册方在 `ctx.slots.inject` 中点名有类型约束的 slot，因此依赖关系既显式，又能跟随声明替换，无需服务顺序约定。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
new file mode 100644
index 0000000000..47adf75d40
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.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/architecture/2026-08-08-client-tool-presentation-ownership.md
+2026-08-08-client-tool-presentation-ownership.md: 4d06450a10c4198f20d7139aef815def9e7cb362
+2026-08-08-client-tool-presentation-ownership.zh.md: 3d3bf3bc3204aca6871a82c7b7ae330b6381a3e4
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
new file mode 100644
index 0000000000..4d06450a10
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
@@ -0,0 +1,103 @@
+# Agent Note: Client Tool presentation ownership
+
+Status: implemented
+
+English | [中文](2026-08-08-client-tool-presentation-ownership.zh.md)
+
+## Problem
+
+The Client Runtime already projects Tool calls into a stable lifecycle: it pairs call/result events by `callId`, preserves running and settled forms, and indexes Code Dispatch children by their root call. The chat view nevertheless owned the entire presentation stack. It placed root calls in ChatFlow, composed each root with its subcalls, dispatched every atomic call by Tool name, carried the generic fallback and card models, registered first-party Tool views, and reused those models in the details panel.
+
+That ownership made `ui-conversation` interpret business Tool names and made subcalls an orphaned concern if an atomic Tool view moved elsewhere. A business package such as `ui-skill` could register a row, but it still depended on conversation's Tool-specific composition contract. Adding Tool-specific Session projection would duplicate a data model the Runtime already owns, while moving only individual React components would leave the composition and model coupling in place.
+
+## Decision
+
+Tool is a first-class Client UI concept with one presentation owner, `@deepseek-ai/dsh-client-ui-tool`. Session Event, projection, fold, `ConversationSnapshot` construction and caching, historical paging, and Code Dispatch indexing remain unchanged.
+
+“First-class concept” describes UI ownership only; it adds no Runtime data kind. `ConversationNode` remains the transcript projection, `ChatFlowItem` remains the render unit produced when conversation sorts and groups nodes, `ToolCallBlock` remains the standard data for one call, and `ToolCallTree` only composes root/subcall presentation within Tool. Command continues to render through the separate `'conversation.chat.commandview'` seat and does not become Tool.
+
+`ui-conversation` owns ordered placement. `deriveChatFlow()` still decides where a settled Tool group appears, and `ChatView` still appends running calls, maintains scroll anchors and selection, and supplies host actions. For each root call it renders the single/session `'conversation.chat.tool'` seat with the root block, selected call id, session cwd, and open-file/inspect callbacks. It does not read Code Dispatch children, branch on Tool names, or import Tool-specific views and card models.
+
+`ui-tool` occupies that whole-Tool seat. Through its standard session slot props, `ToolCallTree` selects the Runtime-projected `codeDispatches[rootCallId]` array, renders the root followed by that one currently supported child level, and routes both forms through one keyed/session `'tool.call.toolview'` child slot using `entryKey: toolName`. An absent business registration renders `GenericToolCard`. This is deliberately one-level composition, not a claim that the Runtime supports an arbitrary recursive call graph.
+
+Business plugins register only atomic views against `'tool.call.toolview'`. Their owner payload is the standard Tool call block plus identity, cwd, and host actions; it carries no Session projector or conversation service. Skill remains an ordinary Tool and `ui-skill` registers the `skill` key through this seam. Existing first-party views live in `ui-tool` until a business package has a reason to own one independently.
+
+The details panel is a second Tool presentation site but not a call-tree owner. `ui-conversation` delegates its selected output body through the single/session `'conversation.details.tool'` seat; `ui-tool` renders the card-aware output and the seat fallback preserves raw result text when the plugin is absent. Card models therefore have one production owner without introducing a reverse implementation import.
+
+The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch stays a top-level official concept because it changes `codeDispatches` and parent/child identity; ordinary Tool business differences stay at the keyed presentation seam. This package boundary does not add a Tool projector/fold registry.
+
+## Runtime and render path
+
+This boundary starts at the Client's `ConversationSnapshot`; the full render path is:
+
+```text
+ConversationSnapshot.nodes
+  -> deriveChatFlow()
+  -> settled tool-group positions ----+
+                                      |
+ConversationSnapshot.runningCalls     |
+  -> ChatView flow tail ---------------+-> ToolSeat
+                                           -> conversation.chat.tool
+                                           -> ToolCallTree
+ConversationSnapshot.codeDispatches[rootCallId] -+
+                                                  +-> root ToolCall + one-level child ToolCall
+                                                      -> tool.call.toolview(entryKey = toolName)
+                                                           |- registered atomic view
+                                                           `- GenericToolCard fallback
+```
+
+The live Session's [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) caches arrays or maps such as `nodes`, `runningCalls`, and `codeDispatches` against independent revisions. Their references stay stable when the corresponding business state has not changed, allowing React selectors and memoization to skip unrelated updates. The historical projection's [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) reconstructs the same running-call and Code Dispatch shapes from entries in its window. Tool UI consumes the snapshot shapes already unified by those paths; presentation packages do not repeat call/result pairing, historical replay, or cache indexing.
+
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) reruns [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts) only when the `nodes` reference changes. It groups consecutive settled Tool results into a `tool-group`, while running root calls append at the flow tail. Both paths ultimately enter the same `ToolSeat`, so settled and running forms share the whole-Tool seat. `ToolCallTree` selects only the current root's `codeDispatches[rootCallId]`; it does not introduce a business projector for presentation of other roots.
+
+## Code and responsibility boundaries
+
+| Owner | Primary code | Owns | Explicitly does not own |
+|---|---|---|---|
+| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts), [`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result pairing, running/settled lifecycle, Code Dispatch parent/child index, snapshot reference stability | Business views selected by Tool name |
+| `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts), [`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx), [`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow order, settled groups, running tail, scroll anchors, selection and host actions, whole-Tool seat declaration | subcall composition, `toolName` dispatch, Generic fallback, Tool card models |
+| `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts), [`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx), [`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall composition, atomic keyed dispatch, Generic fallback, Tool card models and built-in Tool views | ChatFlow ordering, Session Event fold |
+| Business Tool plugins | [`ui-skill` registration example](../../../../packages/client/ui-skill/src/client/index.ts) | Atomic views for one or more wire Tool names | root/subcall placement and lifecycle pairing |
+| Details path | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx), [`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected-call lookup, card-aware output, and raw fallback | chat call-tree composition |
+
+## Slot and owner contract
+
+A slot declaration also constrains render ownership. The conversation chat entry declares `'conversation.chat.tool'` through `children`, so only `ChatView` places the whole-Tool seat. When `ui-tool` registers that seat, its `children` declares `'tool.call.toolview'`, so only `ToolCallTree` renders the atomic Tool seat. Business plugins register keyed entries only; they neither participate in root/subcall composition nor establish a registry parallel to slots.
+
+The whole seat's `ToolTreeOwnerProps` carries the root `callId`, `toolName`, `ToolCallBlock`, `selectedCallId`, session `cwd`, `openFile(path)`, and `inspectCall(callId)`. `ToolCallTree` converts either a root or child into the same `ToolCallOwnerProps` and narrows inspect to a callback for that call. The atomic owner carries no `ReactNode`, Cordis `Context`, Session service, or projector; a business view consumes only one standard call block and host actions.
+
+Business plugins use one registration shape:
+
+```text
+ctx.slots.inject('tool.call.toolview', () =>
+  ctx.slots.register({
+    name: 'tool.call.toolview',
+    key: '<wire tool name>',
+  }, BusinessToolRow))
+```
+
+`ui-tool`'s [`apply()`](../../../../packages/client/ui-tool/src/client/apply.ts) registers the whole-Tool renderer, details renderer, and existing built-in atomic views. An existing independent business package can move only its keyed registration, as `ui-skill` does, without changing `ui-conversation` or Session.
+
+## Details path
+
+[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) still locates the selected call in `nodes`, `runningCalls`, and `codeDispatches`, and it owns input arguments, empty states, and panel lifecycle. It passes only `{ block, cwd }` to `'conversation.details.tool'`; [`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) reuses Tool card models to render the output. When `ui-tool` is absent, a settled call falls back to raw result text and a running call shows conversation's running fallback, so details never imports the Tool implementation in reverse.
+
+## Verification
+
+Test ownership follows production ownership. `ui-conversation` tests install a local whole-Tool seat probe and assert only ChatFlow placement, owner payload, and host contracts such as selection, open-file, and inspect; they do not import `ui-tool` production code or test helpers. `ui-tool` tests mount a real conversation host and verify root/subcall composition, keyed dispatch, generic fallback, concrete Tool UI, and plugin lifecycle.
+
+## Alternatives considered
+
+**Keep atomic Tool slots under every conversation view.** Rejected: each view would have to reproduce root/subcall composition, and a Tool registration would be isolated by view even though its business meaning is Tool-wide. A whole-Tool seat preserves view-owned placement while giving the call tree one owner. This supersedes the per-view placement selected by the earlier [toolview dissolution](2026-07-23-toolview-dissolution.md), while retaining its keyed-slot and no-parallel-registry decisions.
+
+**Move only the Tool React components and card models.** Rejected: `ChatView` would still own Tool-name dispatch and Code Dispatch composition, so the dependency would change file paths without changing responsibility.
+
+**Add business-specific Session projectors or folds.** Rejected: ordinary Tool views consume the standard call block already reconstructed by Runtime. A second registry would create two authorities for call identity and historical replay. Only a feature that changes logged topology or lifecycle earns a Runtime-level extension.
+
+**Make each atomic Tool view render its own subcalls recursively.** Rejected: the atomic registrant receives one Tool call and should not know whether it is a root or child. Root/child composition belongs to `ui-tool`, and the current wire/runtime shape only supports one Code Dispatch child level.
+
+**Import `ui-tool` components directly from `ui-conversation`.** Rejected: it would reverse the intended feature direction and make Tool presentation mandatory. Declared slots retain lifecycle ownership, fallback behavior, and independent plugin loading.
+
+## Consequences
+
+`ui-conversation` becomes independent of Tool-name business presentation while retaining ChatFlow, selection, and host interaction responsibilities. Root calls and subcalls cannot drift onto different dispatch paths, and business packages can own atomic Tool presentation without Session changes. The cost is one new Client package and two cross-package slot seams; `ui-tool` also deliberately depends on conversation's declared seats and locale namespace. The assembled Web bundle therefore mounts `ui-tool`; omitting it leaves chat Tool seats empty while the details seat keeps its raw-result fallback, without changing Session reconstruction.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
new file mode 100644
index 0000000000..3d3bf3bc32
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -0,0 +1,103 @@
+# Agent Note: Client Tool 展示所有权
+
+Status: implemented
+
+[English](2026-08-08-client-tool-presentation-ownership.md) | 中文
+
+## Problem
+
+Client Runtime 已经把 Tool 调用投影成稳定的生命周期：它按 `callId` 配对 call/result 事件，保留 running 与 settled 两种形态，并按 root call 索引 Code Dispatch 子调用。但 chat view 仍拥有整套展示链路：它在 ChatFlow 中放置 root call，把每个 root 与 subcall 编排在一起，按 Tool 名称分发每个原子调用，携带通用 fallback 与 card model，注册第一方 Tool view，并在 details panel 中复用这些 model。
+
+这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的 Tool 专属编排契约。增加 Tool 专属 Session projection 会重复 Runtime 已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
+
+## Decision
+
+Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。Session Event、projection、fold、`ConversationSnapshot` 构建与缓存、历史分页及 Code Dispatch 索引保持不变。
+
+这里的“一级概念”只描述 UI 所有权，不增加 Runtime 数据种类。`ConversationNode` 仍是 transcript projection，`ChatFlowItem` 仍是 conversation 对节点进行排序与分组后得到的渲染单元，`ToolCallBlock` 仍是单次调用的标准数据，而 `ToolCallTree` 只负责 Tool 内部的 root/subcall 展示编排。Command 继续通过独立的 `'conversation.chat.commandview'` 席位渲染，不并入 Tool。
+
+`ui-conversation` 拥有有序放置。`deriveChatFlow()` 仍决定 settled Tool group 在哪里出现，`ChatView` 仍追加 running call、维护滚动 anchor 与 selection，并提供宿主动作。对于每个 root call，它使用 root block、selected call id、session cwd 以及 open-file/inspect 回调渲染 single/session 的 `'conversation.chat.tool'` 席位。它不读取 Code Dispatch child、不按 Tool 名称分支，也不导入 Tool 专属 view 或 card model。
+
+`ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 通过标准 session slot props 选择 Runtime 投影的 `codeDispatches[rootCallId]` 数组，先渲染 root，再渲染当前支持的一层 child；两种调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。这里刻意只编排一层，并不声称 Runtime 已支持任意递归调用图。
+
+业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 seam 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
+
+details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 通过 single/session 的 `'conversation.details.tool'` 席位委托 selected output body；`ui-tool` 渲染能够识别 card 的输出，插件缺席时由席位 fallback 保留 raw result text。因此 card model 只有一个生产代码所有者，也不需要引入反向实现依赖。
+
+Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 会改变 `codeDispatches` 与 parent/child identity，因此继续作为官方顶级概念；普通 Tool 业务差异停留在 keyed 展示 seam。这个包边界不会增加 Tool projector/fold registry。
+
+## Runtime 与渲染链路
+
+这项边界从 Client 的 `ConversationSnapshot` 开始，完整渲染链路如下：
+
+```text
+ConversationSnapshot.nodes
+  -> deriveChatFlow()
+  -> settled tool-group positions ----+
+                                      |
+ConversationSnapshot.runningCalls     |
+  -> ChatView flow tail ---------------+-> ToolSeat
+                                           -> conversation.chat.tool
+                                           -> ToolCallTree
+ConversationSnapshot.codeDispatches[rootCallId] -+
+                                                  +-> root ToolCall + one-level child ToolCall
+                                                      -> tool.call.toolview(entryKey = toolName)
+                                                           |- registered atomic view
+                                                           `- GenericToolCard fallback
+```
+
+Live Session 的 [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 按独立 revision 缓存 `nodes`、`runningCalls`、`codeDispatches` 等数组或 map；没有对应业务变化时，它们保持引用稳定，供 React selector 与 memo 跳过无关更新。历史 projection 的 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 从窗口内 entry 重建相同的 running call 与 Code Dispatch 形态。Tool UI 直接消费这两个路径已经统一的 snapshot，不在展示包中重复 call/result 配对、历史 replay 或缓存索引。
+
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只在 `nodes` 引用变化时重新执行 [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)，把连续 settled Tool result 合为 `tool-group`；running root call 则追加在 flow tail。两条路径最终都进入同一个 `ToolSeat`，因此 settled/running 形态共享整体 Tool 席位。`ToolCallTree` 只选择当前 root 的 `codeDispatches[rootCallId]`，不会因其他 root 的展示逻辑引入业务 projector。
+
+## 代码与职责边界
+
+| 所有者 | 主要代码 | 拥有的责任 | 明确不拥有 |
+|---|---|---|---|
+| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、Code Dispatch parent/child 索引、snapshot 引用稳定性 | Tool 名称对应的业务视图 |
+| `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)、[`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx)、[`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow 顺序、settled group、running tail、scroll anchor、selection 与宿主动作、整体 Tool 席位声明 | subcall 组合、按 `toolName` 分发、Generic fallback、Tool card model |
+| `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts)、[`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx)、[`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall 组合、原子 keyed dispatch、Generic fallback、Tool card model 与内置 Tool view | ChatFlow 排序、Session Event fold |
+| 业务 Tool 插件 | [`ui-skill` 注册例](../../../../packages/client/ui-skill/src/client/index.ts) | 一个或多个 wire Tool name 的原子 view | root/subcall 位置与生命周期配对 |
+| details 路径 | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx)、[`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected call 定位、card-aware output 与 raw fallback | chat 调用树编排 |
+
+## Slot 与 owner 契约
+
+slot 声明同时限定渲染所有权。conversation chat entry 通过 `children` 声明 `'conversation.chat.tool'`，因此只有 `ChatView` 放置整体 Tool 席位；`ui-tool` 注册该席位时再通过 `children` 声明 `'tool.call.toolview'`，因此只有 `ToolCallTree` 渲染原子 Tool 席位。业务插件只注册 keyed entry，不参与 root/subcall 编排，也不建立与 slot 平行的 registry。
+
+整体席位的 `ToolTreeOwnerProps` 携带 root `callId`、`toolName`、`ToolCallBlock`、`selectedCallId`、session `cwd`、`openFile(path)` 与 `inspectCall(callId)`。`ToolCallTree` 把 root 或 child 转成相同的 `ToolCallOwnerProps`，并把 inspect 收窄成当前 call 的回调。原子 owner 不携带 `ReactNode`、Cordis `Context`、Session service 或 projector；业务 view 只消费一个标准调用块和宿主动作。
+
+业务插件遵循同一个注册形态：
+
+```text
+ctx.slots.inject('tool.call.toolview', () =>
+  ctx.slots.register({
+    name: 'tool.call.toolview',
+    key: '<wire tool name>',
+  }, BusinessToolRow))
+```
+
+`ui-tool` 的 [`apply()`](../../../../packages/client/ui-tool/src/client/apply.ts) 注册整体 Tool renderer、details renderer 与现有内置原子 view；已有独立业务包可以像 `ui-skill` 一样只迁走自己的 keyed 注册，无需改动 `ui-conversation` 或 Session。
+
+## Details 路径
+
+[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) 仍从 `nodes`、`runningCalls` 与 `codeDispatches` 中定位选中的 call，并拥有 input 参数、空态和面板生命周期。它只把 `{ block, cwd }` 交给 `'conversation.details.tool'`；[`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) 复用 Tool card model 渲染 output。`ui-tool` 缺席时，settled call 回退为 raw result text，running call 显示 conversation 的 running fallback，因此 details 不反向导入 Tool 实现。
+
+## Verification
+
+测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主契约；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
+
+## Alternatives considered
+
+**在每个 conversation view 下保留原子 Tool slot。** 拒绝：每个 view 都必须重复 root/subcall 编排，而且 Tool 注册会按 view 隔离，即使它的业务语义本应是 Tool 级。整体 Tool 席位保留 view 对放置位置的所有权，同时让调用树只有一个所有者。它取代了早期 [toolview 溶解](2026-07-23-toolview-dissolution.md)所选择的 per-view 放置方式，但保留 keyed slot 与不设平行 registry 的决策。
+
+**只移动 Tool React 组件与 card model。** 拒绝：`ChatView` 仍会拥有 Tool 名称分发与 Code Dispatch 编排，只是改变文件路径，没有改变责任。
+
+**增加业务专属 Session projector 或 fold。** 拒绝：普通 Tool view 消费 Runtime 已重建的标准 call block。第二套 registry 会为 call identity 与历史 replay 建立两个权威。只有会改变日志拓扑或生命周期的能力才应获得 Runtime 级扩展。
+
+**让每个原子 Tool view 递归渲染自己的 subcall。** 拒绝：原子注册方只接收一个 Tool call，不应知道自己是 root 还是 child。root/child 编排归 `ui-tool`，且当前 wire/runtime 形态只支持一层 Code Dispatch child。
+
+**让 `ui-conversation` 直接导入 `ui-tool` 组件。** 拒绝：这会反转预期的 feature 依赖方向，并把 Tool 展示变成必选能力。声明式 slot 能保留生命周期所有权、fallback 行为与独立插件装载。
+
+## Consequences
+
+`ui-conversation` 不再依赖 Tool 名称对应的业务展示，同时保留 ChatFlow、selection 与宿主交互责任。root call 与 subcall 不会漂移到不同分发路径，业务包无需修改 Session 即可拥有原子 Tool 展示。代价是新增一个 Client package 与两个跨包 slot seam；`ui-tool` 也明确依赖 conversation 声明的席位与 locale namespace。因此组装后的 Web bundle 会挂载 `ui-tool`；省略该插件时，chat Tool 席位为空，details 席位则保留 raw-result fallback，且 Session 重建不受影响。

From cd64cc7ecdd955ee77bc1c67cf6a36bcd1043770 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:19:40 +0800
Subject: [PATCH 250/516] docs(notes): update Tool UI implementation references

---
 .../2026-08-05-context-meter-blind-to-compaction.i18n.yaml  | 4 ++--
 .../bug-fix/2026-08-05-context-meter-blind-to-compaction.md | 2 +-
 .../2026-08-05-context-meter-blind-to-compaction.zh.md      | 2 +-
 .../feature/2026-07-23-web-todo-display.i18n.yaml           | 4 ++--
 .../implemented/feature/2026-07-23-web-todo-display.md      | 2 +-
 .../implemented/feature/2026-07-23-web-todo-display.zh.md   | 2 +-
 .../2026-07-26-code-mode-chat-subcall-rows.i18n.yaml        | 4 ++--
 .../feature/2026-07-26-code-mode-chat-subcall-rows.md       | 2 +-
 .../feature/2026-07-26-code-mode-chat-subcall-rows.zh.md    | 2 +-
 .../feature/2026-07-28-web-terminal-card.i18n.yaml          | 4 ++--
 .../implemented/feature/2026-07-28-web-terminal-card.md     | 4 ++--
 .../implemented/feature/2026-07-28-web-terminal-card.zh.md  | 4 ++--
 .../2026-07-29-ask-question-web-presentation.i18n.yaml      | 4 ++--
 .../feature/2026-07-29-ask-question-web-presentation.md     | 2 +-
 .../feature/2026-07-29-ask-question-web-presentation.zh.md  | 2 +-
 .../implemented/feature/2026-07-30-web-diff-card.i18n.yaml  | 4 ++--
 .../notes/implemented/feature/2026-07-30-web-diff-card.md   | 4 ++--
 .../implemented/feature/2026-07-30-web-diff-card.zh.md      | 4 ++--
 .../feature/2026-07-30-web-read-card-frontend.i18n.yaml     | 4 ++--
 .../feature/2026-07-30-web-read-card-frontend.md            | 4 ++--
 .../feature/2026-07-30-web-read-card-frontend.zh.md         | 4 ++--
 .../feature/2026-07-30-web-result-card-frontend.i18n.yaml   | 4 ++--
 .../feature/2026-07-30-web-result-card-frontend.md          | 4 ++--
 .../feature/2026-07-30-web-result-card-frontend.zh.md       | 4 ++--
 .../feature/2026-07-30-web-search-card.i18n.yaml            | 4 ++--
 .../notes/implemented/feature/2026-07-30-web-search-card.md | 6 +++---
 .../implemented/feature/2026-07-30-web-search-card.zh.md    | 6 +++---
 ...-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml | 4 ++--
 .../2026-07-30-web-tool-row-unified-expand-and-inspect.md   | 4 ++--
 ...2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md | 4 ++--
 .../feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml   | 4 ++--
 .../feature/2026-08-02-web-thinking-tail-scroll.md          | 2 +-
 .../feature/2026-08-02-web-thinking-tail-scroll.zh.md       | 2 +-
 .../feature/2026-08-03-web-search-source-scroll.i18n.yaml   | 4 ++--
 .../feature/2026-08-03-web-search-source-scroll.md          | 2 +-
 .../feature/2026-08-03-web-search-source-scroll.zh.md       | 2 +-
 .../feature/2026-08-06-web-skill-tool-row.i18n.yaml         | 4 ++--
 .../implemented/feature/2026-08-06-web-skill-tool-row.md    | 2 +-
 .../implemented/feature/2026-08-06-web-skill-tool-row.zh.md | 2 +-
 39 files changed, 66 insertions(+), 66 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
index 3d9fef5b34..dfaaea4ab7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.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 .agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
-2026-08-05-context-meter-blind-to-compaction.md: ab39ae4e109f238960fd60de5e5b61075344f525
-2026-08-05-context-meter-blind-to-compaction.zh.md: c93aa509530e48acf906b18ba85bab4c7d355d69
+2026-08-05-context-meter-blind-to-compaction.md: 8f4845c3c9bf52c5c3a2d39dee2ff25bda30c7bd
+2026-08-05-context-meter-blind-to-compaction.zh.md: 94ada0a9118db63876d5805ef5a8197d9c764102
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
index ab39ae4e10..8f4845c3c9 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
@@ -43,4 +43,4 @@ The panel's composition rows still do not sum to the header, and now for one cle
 
 ## Testing
 
-`packages/llm/token-meter/tests/token-usage-projection.spec.ts` covers the carry-forward across surface growth and a compaction (the sample holding still while the projection shrinks) and the zero clamp when heuristic error would drive the figure negative. `packages/client/ui-conversation/tests/context-meter.spec.tsx` pins the ring reading the projected figure, and `chat-stats-bash-sample.spec.tsx` pins `contextOccupancy`'s preference and its fallback. The end-to-end numbers above came from driving `BasicCompactService.compactNow` through a real `AgentLoop` with the projection registry mounted.
+`packages/llm/token-meter/tests/token-usage-projection.spec.ts` covers the carry-forward across surface growth and a compaction (the sample holding still while the projection shrinks) and the zero clamp when heuristic error would drive the figure negative. `packages/client/ui-conversation/tests/context-meter.spec.tsx` pins the ring reading the projected figure, and `chat-stats.spec.tsx` pins `contextOccupancy`'s preference and its fallback. The end-to-end numbers above came from driving `BasicCompactService.compactNow` through a real `AgentLoop` with the projection registry mounted.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
index c93aa50953..94ada0a911 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
@@ -43,4 +43,4 @@ AFTER  compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messag
 
 ## 测试
 
-`packages/llm/token-meter/tests/token-usage-projection.spec.ts` 覆盖了样本在表层增长与一次压缩上的推进（样本保持不动而投影值缩小），以及启发式误差会把数字压到负数时的零钳制。`packages/client/ui-conversation/tests/context-meter.spec.tsx` 钉住圆环读取投影值这一点，`chat-stats-bash-sample.spec.tsx` 钉住 `contextOccupancy` 的优先级与回退。上面那组端到端数字来自在挂载了投影注册表的真实 `AgentLoop` 上驱动 `BasicCompactService.compactNow`。
+`packages/llm/token-meter/tests/token-usage-projection.spec.ts` 覆盖了样本在表层增长与一次压缩上的推进（样本保持不动而投影值缩小），以及启发式误差会把数字压到负数时的零钳制。`packages/client/ui-conversation/tests/context-meter.spec.tsx` 钉住圆环读取投影值这一点，`chat-stats.spec.tsx` 钉住 `contextOccupancy` 的优先级与回退。上面那组端到端数字来自在挂载了投影注册表的真实 `AgentLoop` 上驱动 `BasicCompactService.compactNow`。
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml
index cc872a60c3..f90cfe79db 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.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 .agents/notes/implemented/feature/2026-07-23-web-todo-display.md
-2026-07-23-web-todo-display.md: 9e6e4914cd24d1db9271baa3d3fb6fdc56a9ac65
-2026-07-23-web-todo-display.zh.md: 5a5ac554b37c255a7d8c1ce821ebeb1b3f9f091f
+2026-07-23-web-todo-display.md: bb66ef8512badea090b3b22030eef3f43f3b1119
+2026-07-23-web-todo-display.zh.md: 7270874d1e96bb0a553d57ba24b3bc2bb38a7a71
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md
index 9e6e4914cd..bb66ef8512 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md
@@ -22,7 +22,7 @@ The panel mounts through the `conversation.input.dock` slot (a plain registrant
 
 ### TodoRow: the per-call row through the keyed toolview slot
 
-The dedicated `todo_write` chat row is a plain registrant plugin (`todoToolview`, mounted from `apply`) that registers into the keyed `conversation.chat.toolview` slot through `ctx.slots.inject`, the same declaration-lifetime posture as the bash sample but a product registration. The summary derives from call args (`N/M done · first active item`, with a `+<n>` count of the other active ones in `ToolRow`'s non-shrinking `summarySuffix` slot); unparseable args fall back to the generic row summary; clicking opens the details column with the raw args. No `ToolEventView` is added for todo — presentation is client-owned, and the durable list renders from the session event, not the tool card.
+The dedicated `todo_write` chat row is a plain registrant plugin (`todoToolview`, mounted from `apply`) that registers into the keyed `tool.call.toolview` slot through `ctx.slots.inject`, the same declaration-lifetime posture as the bash sample but a product registration. The summary derives from call args (`N/M done · first active item`, with a `+<n>` count of the other active ones in `ToolRow`'s non-shrinking `summarySuffix` slot); unparseable args fall back to the generic row summary; clicking opens the details column with the raw args. No `ToolEventView` is added for todo — presentation is client-owned, and the durable list renders from the session event, not the tool card.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
index 5a5ac554b3..7270874d1e 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 ### TodoRow：经 keyed toolview slot 的逐调用行
 
-专用的 `todo_write` 对话行是一个普通注册者插件（`todoToolview`，由 `apply` 挂载），经 `ctx.slots.inject` 注册进 keyed 的 `conversation.chat.toolview` slot，遵循与 bash 样例相同的声明生命周期，但属产品级注册。摘要由调用 args 推导（`N/M done · first active item`，其余活跃项的 `+<n>` 计数放在 `ToolRow` 的不收缩 `summarySuffix` 位里）；无法解析的 args 回退到通用行摘要；点击会以原始 args 打开 details 列。todo 不新增任何 `ToolEventView`——呈现归客户端所有，常驻列表从会话事件渲染，而非工具卡。
+专用的 `todo_write` 对话行是一个普通注册者插件（`todoToolview`，由 `apply` 挂载），经 `ctx.slots.inject` 注册进 keyed 的 `tool.call.toolview` slot，遵循与 bash 样例相同的声明生命周期，但属产品级注册。摘要由调用 args 推导（`N/M done · first active item`，其余活跃项的 `+<n>` 计数放在 `ToolRow` 的不收缩 `summarySuffix` 位里）；无法解析的 args 回退到通用行摘要；点击会以原始 args 打开 details 列。todo 不新增任何 `ToolEventView`——呈现归客户端所有，常驻列表从会话事件渲染，而非工具卡。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml
index 9086e891db..d550ad1fb6 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.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 .agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
-2026-07-26-code-mode-chat-subcall-rows.md: 7d666f0a9e4b8bdb9bd6f5d0d0984fee0c4b21e2
-2026-07-26-code-mode-chat-subcall-rows.zh.md: b6b7de6c34673a0a0fa801681d642067a324d4cd
+2026-07-26-code-mode-chat-subcall-rows.md: dc09e8fda9dbfb156b6218dec67584ee7bfead75
+2026-07-26-code-mode-chat-subcall-rows.zh.md: d445ddac4704fb940550d27ef7400e79d859393b
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
index 7d666f0a9e..dc09e8fda9 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
@@ -15,7 +15,7 @@ With Code Mode enabled, the chat view showed one opaque `run_code` row: raw prog
 **Sub-calls are `ToolResultNode`s indexed off the surface flow, rendered through the same keyed slot as native rows, nested always-visible under their parent.**
 
 - **Data layer**: `Session.applyEventSideEffects` folds each in-window `tool/code-dispatch` into `ConversationSnapshot.codeDispatches: ReadonlyMap<parentCallId, readonly CodeSubCall[]>`, where `CodeSubCall` IS `ToolResultNode` (the sub-call id as `callId`, the logged args JSON-stringified into `call.argsRaw`, the full logged `content`/`isError`). Live mux frames and history replay build the identical index (`rebuildDerivedFromWindow` clears and re-derives; copy-on-write per-parent arrays keep snapshot references memo-stable). Sub-calls never join `nodes` — the surface flow remains exactly the model-visible turn structure. The event is narrowed structurally at the wire-consumer boundary (dsh-tools' host types cannot enter the client program — the host/client `Context` merges collide), the same posture as every cross-wire payload.
-- **Render layer**: `ChatView`'s `CallRow` renders the parent, then — for parents present in the index — a `[data-subcalls]` nest of `SubCallRow`s, each dispatching through the SAME `'conversation.chat.toolview'` keyed hole with `entryKey = sub-tool name` and the same `GenericToolCard` fallback. Identity with native rows holds by construction: a keyed registration (e.g. the bash sample) takes over sub-rows exactly as it takes over top-level rows, with zero registration changes. Running parents (`runningCalls`) nest their so-far dispatches the same way, so sub-rows stream in live during the run (PR1 logs each dispatch as it completes).
+- **Render layer**: `ChatView` passes each parent and its indexed children through the whole-Tool `'conversation.chat.tool'` seat. ui-tool's `ToolCallTree` renders the parent followed by a `[data-subcalls]` nest, and every atomic call dispatches through the same `'tool.call.toolview'` keyed slot with `entryKey = Tool name` and the same `GenericToolCard` fallback. A keyed registration therefore takes over child and top-level calls without registration changes. Running parents (`runningCalls`) receive their accumulated dispatches through the same owner payload, so child rows stream in during the run.
 - **`run_code` presentation**: a new `code` row variant (classifier `run_code → code`, `Code` title, `IconCodeOutline16`) summarizes with the model-authored `description` and expands to the program itself (monospace on the markdown code-block fill) rather than the args JSON envelope.
 - **Details panel**: `materialFor` falls through nodes → runningCalls → the dispatch index, so a selected sub-callId resolves to full args and complete output through the identical rendering path as a native settled call.
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
index b6b7de6c34..d445ddac47 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
@@ -15,7 +15,7 @@ Status: implemented
 **子调用在界面流之外单独索引为 `ToolResultNode`，经由与原生行相同的 keyed slot 渲染，以始终可见的方式嵌套在父行之下。**
 
 - **数据层**：`Session.applyEventSideEffects` 把窗口内的每条 `tool/code-dispatch` 折入 `ConversationSnapshot.codeDispatches: ReadonlyMap<parentCallId, readonly CodeSubCall[]>`，其中 `CodeSubCall` 本身就是 `ToolResultNode`（子调用 id 充当 `callId`，已记录的参数经 JSON 字符串化写入 `call.argsRaw`，完整记录的 `content`/`isError` 原样携带）。实时多路复用帧与历史回放构建出同一份索引（`rebuildDerivedFromWindow` 先清空再重新推导；逐父级的写时复制（copy-on-write）数组保持快照引用稳定，便于 memo 化）。子调用永不进入 `nodes`——surface 流始终精确等于模型可见的轮次结构。该事件在 wire 消费方边界作结构性收窄（dsh-tools 的宿主类型无法进入客户端程序——宿主端/客户端两侧的 `Context` 声明合并会冲突），姿态与所有跨 wire 载荷一致。
-- **渲染层**：`ChatView` 的 `CallRow` 先渲染父行，随后对索引中出现的父级渲染一组 `[data-subcalls]` 嵌套的 `SubCallRow`，每一行都经由同一个 `'conversation.chat.toolview'` keyed slot、以 `entryKey = sub-tool name` 分发，并共用同一个 `GenericToolCard` 后备组件。与原生行的同一性由构造保证：一个 keyed 注册（例如 bash 样例）接管子行与接管顶层行的方式完全相同，注册本身零改动。运行中的父调用（`runningCalls`）也以同样的方式嵌套目前已产生的分发，因此子行在运行期间实时流入（PR1 在每次分发完成时即记录该分发）。
+- **渲染层**：`ChatView` 通过整体 Tool seat `'conversation.chat.tool'` 传递每个 parent 及其已索引的 child。ui-tool 的 `ToolCallTree` 先渲染 parent，再渲染一组 `[data-subcalls]` 嵌套；每个原子调用都通过同一个 `'tool.call.toolview'` keyed slot，以 Tool 名称作为 `entryKey`，并共用 `GenericToolCard` fallback。一个 keyed 注册因此无需变化即可同时接管 child 与顶层调用。运行中的 parent（`runningCalls`）通过同一 owner 载荷接收已累积的 dispatch，使 child 行在运行期间实时流入。
 - **`run_code` 的呈现**：新增一种 `code` 行变体（分类器映射 `run_code → code`、标题 `Code`、图标 `IconCodeOutline16`），以模型撰写的 `description` 作摘要，展开后显示程序本身（在 markdown 代码块的填充底色上以等宽字体呈现），而非参数的 JSON 封装。
 - **详情面板**：`materialFor` 按 nodes → runningCalls → 分发索引的顺序逐级回落，因此被选中的子调用 callId 会经由与已完结的原生调用完全相同的渲染路径，解析出完整参数与完整输出。
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
index 5e079bc180..0a7fb2b3ef 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.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 .agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
-2026-07-28-web-terminal-card.md: 0e5f3e2157ebfc4e71aead26c15b6ee91958a5d5
-2026-07-28-web-terminal-card.zh.md: 1285d3fbb46ebd32ff163feac632cd487e8a04f1
+2026-07-28-web-terminal-card.md: 0493db4b86ce869ce5e699359e66dda70e526116
+2026-07-28-web-terminal-card.zh.md: 10137f83a25860a42e80a7b807a8aed68e86ce18
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
index 0e5f3e2157..0493db4b86 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
@@ -12,7 +12,7 @@ The Web client ignored it. `packages/client/ui-conversation/src/client/contract/
 
 ## Decision
 
-`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `ui-conversation/src/client/contract/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs at this seam; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means.
+`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `ui-tool/src/client/models/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs at this seam; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means.
 
 The component's contract:
 
@@ -57,7 +57,7 @@ Inline rendering is licensed for the terminal intent alone. A future intent that
 
 `packages/client/ui-primitives/tests/ansi.spec.ts` pins the parse layer: token mapping for the basic colors, literal rgb for the values with no token, the background-run pair, every decoration and the `textDecoration` collision between two of them, the sanitizing of OSC strings and non-CSI escapes and inert controls, the cursor replay (redraws leaving a longer frame's tail standing, a trailing backspace erasing nothing, erase-in-line in all three parameter forms, tab stops, wide characters, SGR threading across lines, and a cursor/erase sequence never entering a cell style), and CRLF preservation. Each replay case was checked against a real terminal first. `packages/client/ui-primitives/tests/terminal-block.spec.tsx` pins the component: cwd shortening, the running/empty/settled arms, signal outranking exit code, the trailing-newline terminator rule, the head/tail cap with its `aria-expanded` toggle, the run-state dot across all three reachable states plus its position ahead of the prompt label, the one-row-per-command-line prompt and its single dot on the first row, and the copy control asserting raw output on both the accepted and refused clipboard paths, plus `writeClipboard` directly.
 
-`packages/client/ui-conversation/tests/terminal-card.spec.tsx` pins the wiring at every render site: `terminalCardModel`'s derivation and each of its null arms, the result title replacing the pending one, the cwd resolving against the session workspace across all four of its cases, the panel resetting the card's expand state when the selection changes, the chat row's expand-gated body against the panel's full-height one, `BashRow`'s resident card and its agreement with its own summary row's state dot, and the panel's Output section including the run_code sub-dispatch and the out-of-window head. That file is written against no gate pressure — `packages/client/ui-conversation/src/*` sits on the coverage `exclude` list in `vitest.config.ts`, so a coverage run over this package measures none of these files.
+`packages/client/ui-tool/tests/terminal-card.spec.tsx` pins the wiring at every render site: `terminalCardModel`'s derivation and each of its null arms, the result title replacing the pending one, the cwd resolving against the session workspace across all four of its cases, the panel resetting the card's expand state when the selection changes, the chat row's expand-gated body against the panel's full-height one, `BashRow`'s resident card and its agreement with its own summary row's state dot, and the panel's Output section including the run_code sub-dispatch and the out-of-window head. That file is written against no gate pressure — `packages/client/ui-tool/src/*` sits on the coverage `exclude` list in `vitest.config.ts`, so a coverage run over this package measures none of these files.
 
 `apps/web/tests/terminal-card.snapshot.ts` pins the assembled application over the built client bundles: the same render intent at both conversation render sites and in both chat-row shapes, because a bash call reaches a resident card only through the keyed `BashRow` registration and every other terminal-declaring tool name lands on the render-site fallback row, whose body is expand-gated. Fixture turn 65 was named `bash` and turn 60 left as `fx-bash` so one fixture covers both shapes, and turn 60's command was made two lines so the built-bundle snapshot pins the per-line prompt and its single dot (`dotsPerPromptRow: [1, 0]`). That terminal turn is ordered BEFORE the todo turn on purpose: the standing plan retires at the next `turn/start`, so appending it after would have emptied the dock's plan strip and taken the todo surfaces' own coverage with it; that turn also carries what turn 60's two prompt rows cannot — SGR runs resolved to `--dsw-*` tokens, output past the chat cap, a nested cwd, and a non-zero exit authored beside the sample. The sample's body deliberately carries NO `[exit code: N]` line: the real bash presenter consumes that marker out of the body precisely because the card shows the exit as its own pill, so leaving it in would pin a frame showing the exit twice — one the product path cannot produce.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index 1285d3fbb4..10137f83a2 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -12,7 +12,7 @@ Web client 却对它视而不见。`packages/client/ui-conversation/src/client/c
 
 ## Decision
 
-`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`ui-conversation/src/client/contract/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
+`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`ui-tool/src/client/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
 
 该组件的契约：
 
@@ -57,7 +57,7 @@ Web client 却对它视而不见。`packages/client/ui-conversation/src/client/c
 
 `packages/client/ui-primitives/tests/ansi.spec.ts` 固定解析层：基本色的 token 映射、无对应 token 取值的字面 rgb、带背景分段的前后景配对、每一项装饰以及其中两项之间的 `textDecoration` 冲突、OSC 串与非 CSI 转义及无显示意义控制符的剥除、光标重放（较短重绘让上一帧尾巴留存、末尾退格不擦除任何东西、行内擦除的全部三种参数形式、制表位、宽字符、SGR 跨行延续，以及光标／擦除序列绝不进入单元格样式），以及 CRLF 的保留。每一条重放用例都先对照真实终端核实过。`packages/client/ui-primitives/tests/terminal-block.spec.tsx` 固定组件：cwd 缩短、运行中／空／已落定三条分支、信号优先于退出码、末尾终止符规则、首尾高度上限及其 `aria-expanded` 开关、运行状态点全部三种可达状态及其位于提示符标签之前的位置、每条命令行一行的提示区及其位于第一行的单枚状态点，以及复制控件在剪贴板接受与拒绝两条路径上都断言原始输出，另有对 `writeClipboard` 的直接固定。
 
-`packages/client/ui-conversation/tests/terminal-card.spec.tsx` 固定每个渲染点上的接线：`terminalCardModel` 的推导及其每一处 null 分支、结果标题替换待定标题、cwd 针对会话 workspace 解析的全部四种情形、切换选中调用时面板重置卡片展开态、对话行受展开控制的输出体与面板的全高输出体的对比、`BashRow` 的常驻卡片及其与自身摘要行状态点的一致性，以及面板 Output 区段（含 run_code 子派发与超出窗口的调用头）。该文件在没有门禁压力的情况下写成——`packages/client/ui-conversation/src/*` 位于 `vitest.config.ts` 的覆盖率 `exclude` 列表中，因此覆盖率运行不会统计其中任何文件。
+`packages/client/ui-tool/tests/terminal-card.spec.tsx` 固定每个渲染点上的接线：`terminalCardModel` 的推导及其每一处 null 分支、结果标题替换待定标题、cwd 针对会话 workspace 解析的全部四种情形、切换选中调用时面板重置卡片展开态、对话行受展开控制的输出体与面板的全高输出体的对比、`BashRow` 的常驻卡片及其与自身摘要行状态点的一致性，以及面板 Output 区段（含 run_code 子派发与超出窗口的调用头）。该文件在没有门禁压力的情况下写成——`packages/client/ui-tool/src/*` 位于 `vitest.config.ts` 的覆盖率 `exclude` 列表中，因此覆盖率运行不会统计其中任何文件。
 
 `apps/web/tests/terminal-card.snapshot.ts` 在构建后的客户端产物上固定组装完整的应用：同一渲染意图在两个对话渲染点、以及两种对话行形态下的表现——因为 bash 调用只有经由带键的 `BashRow` 注册才得到常驻卡片，而其他任何声明 terminal 的工具名都落到渲染点兜底行上，其输出体受展开控制。fixture 第 65 轮改名为 `bash`、第 60 轮保留 `fx-bash`，于是一份 fixture 覆盖两种形态，并把第 60 轮的命令改为两行，使构建产物快照钉住逐行提示区及其单枚状态点（`dotsPerPromptRow: [1, 0]`）。该终端轮有意排在 todo 轮**之前**：站立计划会在下一次 `turn/start` 时退役，若追加在其后就会让 dock 的计划条变空，并连带毁掉 todo 表面自身的覆盖；该轮还承载第 60 轮两个提示行无法覆盖的部分——解析到 `--dsw-*` token 的 SGR 分段、超出对话上限的输出、嵌套 cwd，以及在样本旁另行标注的非零退出码。样本正文有意**不含** `[exit code: N]` 行：真实的 bash presenter 正是因为卡片以徽章单独呈现退出状态，才把该标记从正文中消费掉；若保留它，钉住的将是一帧把退出状态显示两次的画面——而产品路径产不出这一帧。
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
index 161e7b7fe7..35c6e070a6 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.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 .agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
-2026-07-29-ask-question-web-presentation.md: 90eeb3cdcc1a851b7d5e184c0f31cbccd82cbf55
-2026-07-29-ask-question-web-presentation.zh.md: d1d18c030fd6cd9fc7832f82c19b49e4e8e04d30
+2026-07-29-ask-question-web-presentation.md: 11471bba08b723620b83af0e14e64a759d11c520
+2026-07-29-ask-question-web-presentation.zh.md: 50f0dffa1a1f9cbd29b676cc1f21ba0298f6bf23
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
index 90eeb3cdcc..11471bba08 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
@@ -12,7 +12,7 @@ Separately, the composer visuals had drifted from the current design: an expand-
 
 ## Decision
 
-A pending question owns exactly two surfaces: the composer takeover collects the answers, and a dedicated `ask_user_question` toolview row in the transcript names the interaction outcome. The row registers into the keyed `conversation.chat.toolview` hole exactly like `todo_write` and composes the shared `ToolRow` (chrome, running sweep, leading expansion). Its summary is the interaction verdict rather than args: `waiting` while running, `N/M answered` from the result JSON once settled (a skipped answer — empty `selected`, no `custom` — stays out of the count), `cancelled` for `ASK_CANCELLED`, and `interrupted` with the shared amber stopped semantics for `ASK_ABORTED`. Malformed or truncated results fall back to the generic summary. `PendingCard` narrows to `PendingWait<'approval'>` and `ChatView` filters the pending list to approval waits, so the placeholder card now exists only for the approval takeover still on the roadmap.
+A pending question owns exactly two surfaces: the composer takeover collects the answers, and a dedicated `ask_user_question` toolview row in the transcript names the interaction outcome. The row registers into the keyed `tool.call.toolview` hole exactly like `todo_write` and composes the shared `ToolRow` (chrome, running sweep, leading expansion). Its summary is the interaction verdict rather than args: `waiting` while running, `N/M answered` from the result JSON once settled (a skipped answer — empty `selected`, no `custom` — stays out of the count), `cancelled` for `ASK_CANCELLED`, and `interrupted` with the shared amber stopped semantics for `ASK_ABORTED`. Malformed or truncated results fall back to the generic summary. `PendingCard` narrows to `PendingWait<'approval'>` and `ChatView` filters the pending list to approval waits, so the placeholder card now exists only for the approval takeover still on the roadmap.
 
 The composer redesign moves paging into the footer next to the actions, renders multi-select options with explicit checkboxes, keeps single-select numbered rows, and replaces the expand-to-open custom entry with an always-visible custom input row (textarea for optionless questions). The `parseQuestionTitle` multi-select suffix convention is deleted; `multi_select` is already structured metadata, so the title renders verbatim.
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
index d1d18c030f..50f0dffa1a 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
@@ -12,7 +12,7 @@ Web GUI 已经可以通过 `QuestionComposer` 的输入区接管收集回答，
 
 ## 决定
 
-一个待回答的问题恰好拥有两个界面：输入区接管收集回答，会话记录中一个专门的 `ask_user_question` toolview 行陈述交互结果。该行与 `todo_write` 完全一样注册进带 key 的 `conversation.chat.toolview` 槽位，并复用共享的 `ToolRow`（外观、运行扫光、前导展开）。其摘要是交互裁决而非参数：运行中显示 `waiting`，结算后从结果 JSON 得出 `N/M answered`（被跳过的回答 —— `selected` 为空且无 `custom` —— 不计入），`ASK_CANCELLED` 显示 `cancelled`，`ASK_ABORTED` 显示 `interrupted` 并沿用共享的琥珀色 stopped 语义。畸形或截断的结果回退到通用摘要。`PendingCard` 收窄为 `PendingWait<'approval'>`，`ChatView` 将待处理列表过滤为仅审批等待，占位卡片从此只服务于仍在路线图上的审批接管。
+一个待回答的问题恰好拥有两个界面：输入区接管收集回答，会话记录中一个专门的 `ask_user_question` toolview 行陈述交互结果。该行与 `todo_write` 完全一样注册进带 key 的 `tool.call.toolview` 槽位，并复用共享的 `ToolRow`（外观、运行扫光、前导展开）。其摘要是交互裁决而非参数：运行中显示 `waiting`，结算后从结果 JSON 得出 `N/M answered`（被跳过的回答 —— `selected` 为空且无 `custom` —— 不计入），`ASK_CANCELLED` 显示 `cancelled`，`ASK_ABORTED` 显示 `interrupted` 并沿用共享的琥珀色 stopped 语义。畸形或截断的结果回退到通用摘要。`PendingCard` 收窄为 `PendingWait<'approval'>`，`ChatView` 将待处理列表过滤为仅审批等待，占位卡片从此只服务于仍在路线图上的审批接管。
 
 输入区重设计将分页移到底部操作区旁，多选选项渲染显式复选框，单选保留编号行，并用始终可见的自定义输入行取代展开式自定义入口（无选项问题用多行文本框）。删除 `parseQuestionTitle` 的多选后缀约定；`multi_select` 已是结构化元数据，标题原样渲染。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index 388a8de9cd..ef2b3e55a0 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.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 .agents/notes/implemented/feature/2026-07-30-web-diff-card.md
-2026-07-30-web-diff-card.md: eb43e09d6173ca2270df97cecaab6da36c70a679
-2026-07-30-web-diff-card.zh.md: 669cd49abc8eba8637705cd7c9f331cc51607755
+2026-07-30-web-diff-card.md: c8aed2aa59d82520a2a52523edb9b66d0bb34bf0
+2026-07-30-web-diff-card.zh.md: c2127844165e5f5c162eb3707fa5c86aa3a536c0
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
index eb43e09d61..c8aed2aa59 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
@@ -14,7 +14,7 @@ This is the [terminal card](2026-07-28-web-terminal-card.md) done for the `diff`
 
 ## Decision
 
-`DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-conversation/src/client/contract/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change.
+`DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-tool/src/client/models/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change.
 
 The component shares the TUI's single-column framing, line-terminator rule, and distinct-path file count. Line classification differs: Web renders the complete old and new sides, while the TUI derives neutral context and exact changed rows when its bounded comparison completes and labels its whole-side fallback approximate.
 
@@ -46,7 +46,7 @@ The multi-file arm of `DiffBlock` (one card, several path headers) has no produc
 
 `packages/client/ui-primitives/tests/diff-block.spec.tsx` pins the component: the create arm (added-only, no removed side), the edit arm (removed above added), the same-file `⋯` gap versus a new file's own header, the empty-diffs null render, the footer counts and their singular/plural, the head/tail cap with its `aria-expanded` toggle, and the copy control asserting the prefixed diff text on both the accepted and refused clipboard paths. Per-file 100%.
 
-`packages/client/ui-conversation/tests/diff-card.spec.tsx` pins the wiring at every render site: `diffCardModel`'s derivation and each of its null arms, the result hunks replacing the call-time diff, a window-truncated call still rendering from the result, the chat row's diff body, `FileMutationRow`'s resident card and its path link opening cwd-resolved through the host, its registration under both `write` and `edit`, and the panel's Output section.
+`packages/client/ui-tool/tests/diff-card.spec.tsx` pins the wiring at every render site: `diffCardModel`'s derivation and each of its null arms, the result hunks replacing the call-time diff, a window-truncated call still rendering from the result, the chat row's diff body, `FileMutationRow`'s resident card and its path link opening cwd-resolved through the host, its registration under both `write` and `edit`, and the panel's Output section.
 
 The fixture (`packages/client/connection/src/client/fixture.ts`) carries three diff turns so a `?fixture` server and the per-package wiring suite exercise all three arms at both render sites: a single-hunk edit (turn 62, keyed `FileMutationRow`), a create/write (turn 63), and a multi-hunk edit (turn 67, the `⋯` gap between two scattered hunks in one file). The built-boot snapshot (`apps/web/tests/built-boot.snapshot.ts`) is a boot-assembly smoke that asserts only that the graph mounts and reaches chat content (`data-sample="bash-global"`); by its own contract it carries no diff-behavior assertions, which the wiring suite owns.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index 669cd49abc..c212784416 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -14,7 +14,7 @@ Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行
 
 ## Decision
 
-`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-conversation/src/client/contract/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
+`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-tool/src/client/models/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
 
 该组件与 TUI 共用单栏框架、行终止符规则和去重路径计数。两者的行分类不同：Web 渲染完整的变更前后两侧，而 TUI 会在有界比较完成时派生中性上下文和精确变更行，并把整侧回退标记为近似结果。
 
@@ -46,7 +46,7 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX
 
 `packages/client/ui-primitives/tests/diff-block.spec.tsx` 钉住组件：新建支路（只有新增、无删除侧）、编辑支路（删除在新增之上）、同文件 `⋯` gap 对比新文件自己的头、空 diffs 的 null 渲染、页脚计数及其单复数、头尾上限及其 `aria-expanded` 切换、以及复制控件在接受与拒绝两条剪贴板路径上断言带前缀的 diff 文本。Per-file 100%。
 
-`packages/client/ui-conversation/tests/diff-card.spec.tsx` 钉住每个渲染点的接线：`diffCardModel` 的派生及其每个 null 支路、result hunk 替换 call 时 diff、窗口截断的 call 仍从 result 渲染、chat 行的 diff 体、`FileMutationRow` 的常驻卡片及其路径链接经 host 以 cwd 解析打开、其在 `write` 与 `edit` 下的注册、以及面板的 Output 区。
+`packages/client/ui-tool/tests/diff-card.spec.tsx` 钉住每个渲染点的接线：`diffCardModel` 的派生及其每个 null 支路、result hunk 替换 call 时 diff、窗口截断的 call 仍从 result 渲染、chat 行的 diff 体、`FileMutationRow` 的常驻卡片及其路径链接经 host 以 cwd 解析打开、其在 `write` 与 `edit` 下的注册、以及面板的 Output 区。
 
 fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot snapshot（`apps/web/tests/built-boot.snapshot.ts`）是启动装配 smoke，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身契约它不带 diff 行为断言，那由接线套件负责。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
index 388eb85ef8..71ea2aabaf 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.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 .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
-2026-07-30-web-read-card-frontend.md: 06559d70c655b86a6aa70c8a9e948f4f21a1f522
-2026-07-30-web-read-card-frontend.zh.md: 92fb724658d4c23b915f61efc3b482fdf1ce7c7b
+2026-07-30-web-read-card-frontend.md: 10ed9d3eaa54c2440cf3fbd00a7e44b76c1acfe9
+2026-07-30-web-read-card-frontend.zh.md: 931316135470b7e7257f7f9d016b24fe741fdbf5
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
index 06559d70c6..10ed9d3eaa 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
@@ -10,7 +10,7 @@ The [read backend](2026-07-30-web-read-card.md) added a fourth render-intent car
 
 ## Decision
 
-`ReadBlock` is a `ui-primitives` component that renders a read result as a line-numbered, optionally syntax-highlighted file view, and both Web render sites for a read consume the read render intent through it: the chat tool row (resident under the summary line) and the details panel's Output section. `ui-conversation/src/client/contract/read-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so the two sites cannot disagree.
+`ReadBlock` is a `ui-primitives` component that renders a read result as a line-numbered, optionally syntax-highlighted file view, and both Web render sites for a read consume the read render intent through it: the chat tool row (resident under the summary line) and the details panel's Output section. `ui-tool/src/client/models/read-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so the two sites cannot disagree.
 
 **A new `ReadBlock` primitive, not an extension of `CodeBlock`.** `CodeBlock` already does shiki highlighting with a language banner and a copy control, but a read view needs a per-line gutter carrying each line's own file number, which `CodeBlock` renders as a single `<pre>` tree with no per-line structure. Extending `CodeBlock` with an optional gutter would push a read-specific concern (windowed line numbers, a "showing N of M" note, a height cap) onto every markdown fence and every `run_code` body that shares that component. Instead `ReadBlock` reuses the part that is genuinely shared: the shiki grammar singleton in `markdown/highlight.ts`. A new `highlightLines(code, lang)` there tokenizes into shiki's own per-line token arrays (`codeToTokens`) rather than the single-`<pre>` HTML `highlightToHtml` produces, so the block can place one gutter number per line and still color the content through the same `--shiki-*` custom properties on the same grammar allowlist. The height cap and its head/tail expand arithmetic are copied from `TerminalBlock` (`ceil(max/2)` head plus the remaining tail), so a long read and a long command output collapse at the same place. The copy control writes the window's raw text (the lines joined by newlines), never the gutter numbers or the banner.
 
@@ -42,7 +42,7 @@ A read row in the Web chat now carries the file content resident, a deliberate d
 
 `packages/client/ui-primitives/tests/read-block.spec.tsx` pins the primitive and the token path: `highlightLines`' per-line css-variables runs, its trailing-terminator-line drop and the genuinely-blank-final-line case, its `undefined` for an unknown/absent language, and its lazy path (a lazy grammar returns plain on first touch, then highlights after the import registers and the subscriber fires); and `ReadBlock`'s gutter-numbered rows keeping the file's own numbers, the highlighted-vs-plain content arms, the banner (label, language, the count note only when the read is a window), the head/tail height cap with its `aria-expanded` toggle, the copy control writing the window's raw text on both the accepted and refused clipboard paths, and the empty-window arm hiding the copy control. `code-block.spec.tsx` covers `highlightToHtml` including its lazy path over every read-card grammar (each dynamic import thunk touched once). Both `ReadBlock.tsx` and `highlight.ts` (and `CodeBlock.tsx`) hold per-file 100% coverage across the two specs.
 
-`packages/client/ui-conversation/tests/read-card.spec.tsx` pins the wiring at every render site: `readCardModel`'s derivation and each null arm (running read, no view, generic view, unknown card), the result title replacing the relativized path, the path relativization against the workspace, the copy-not-alias of the frozen line array; the resident card in `GenericToolCard`'s fallback and in the keyed `ReadRow` (plus its path link opening the host, its running/error/stopped states, and its `read`-key registration); and the panel's Output section rendering the read card at full height while keeping the JSON Input section, with the running-read placeholder and non-read flattened-pre arms. That file sits on the coverage `exclude` list (`ui-conversation/src/*`), so it is written against no gate pressure.
+`packages/client/ui-tool/tests/read-card.spec.tsx` pins the wiring at every render site: `readCardModel`'s derivation and each null arm (running read, no view, generic view, unknown card), the result title replacing the relativized path, the path relativization against the workspace, the copy-not-alias of the frozen line array; the resident card in `GenericToolCard`'s fallback and in the keyed `ReadRow` (plus its path link opening the host, its running/error/stopped states, and its `read`-key registration); and the panel's Output section rendering the read card at full height while keeping the JSON Input section, with the running-read placeholder and non-read flattened-pre arms. That file sits on the coverage `exclude` list (`ui-tool/src/*`), so it is written against no gate pressure.
 
 The fixture (`packages/client/connection/src/client/fixture.ts`) gains turn 66, a `read` call whose result view is a windowed read (lines starting at file line 41, `totalLines` 180, a `ts` hint), so the built-boot snapshot and a live `?fixture` server show the read card with its gutter numbers, highlighting, and count note. It is named `read` to exercise the keyed `ReadRow`. The turn 64 `run_code` sample's nested read sub-dispatches do not exercise the render-site fallback read card: `session.ts` folds them with `resultView: null`, so they cover only the fallback row's generic row shape, not a read card inside it; the fallback-row read card is pinned by `read-card.spec.tsx`'s `web_fetch` case. Turn 66 is ordered before the todo turn (now 67) for the same reason the terminal sample is: the standing plan retires at the next `turn/start`.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
index 92fb724658..9313161354 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-`ReadBlock` 是一个 `ui-primitives` 组件，把一次读取结果渲染成带行号、可选语法高亮的文件视图，读取的两个 Web 渲染点都通过它消费读取渲染意图：聊天工具行（常驻在摘要行之下）与详情面板的 Output 区段。`ui-conversation/src/client/contract/read-card-model.ts` 是把快照的 `resultView` 转成组件 props 的唯一位置，因此两个渲染点不会产生分歧。
+`ReadBlock` 是一个 `ui-primitives` 组件，把一次读取结果渲染成带行号、可选语法高亮的文件视图，读取的两个 Web 渲染点都通过它消费读取渲染意图：聊天工具行（常驻在摘要行之下）与详情面板的 Output 区段。`ui-tool/src/client/models/read-card-model.ts` 是把快照的 `resultView` 转成组件 props 的唯一位置，因此两个渲染点不会产生分歧。
 
 **新建一个 `ReadBlock` primitive，而不是扩展 `CodeBlock`。** `CodeBlock` 已经带语言横幅和复制控件做 shiki 高亮，但读取视图需要一个每行带该行自身文件行号的行号栏，而 `CodeBlock` 把内容渲染为单个 `<pre>` 树、没有逐行结构。给 `CodeBlock` 加一个可选行号栏会把读取专属的关切（窗口行号、"显示 N / M"提示、高度上限）强加给共享该组件的每个 markdown 代码围栏和每个 `run_code` 程序体。`ReadBlock` 转而复用真正共享的部分：`markdown/highlight.ts` 里的 shiki 语法单例。那里新增的 `highlightLines(code, lang)` 把代码切成 shiki 自己的逐行 token 数组（`codeToTokens`），而不是 `highlightToHtml` 产出的单 `<pre>` HTML，于是该 block 能每行放一个行号、同时用同一套 `--shiki-*` 自定义属性、同一份语法白名单给内容上色。高度上限及其头/尾展开算法照抄自 `TerminalBlock`（`ceil(max/2)` 行头部加剩余的尾部），因此长读取和长命令输出在同一处折叠。复制控件写入窗口的原始文本（各行以换行拼接），绝不含行号栏或横幅。
 
@@ -42,7 +42,7 @@ Web 聊天里的读取行现在常驻承载文件内容，是相对纯摘要行
 
 `packages/client/ui-primitives/tests/read-block.spec.tsx` 固定 primitive 与 token 路径：`highlightLines` 的逐行 css-variables 运行、它对尾部终止行的丢弃与真正空白末行的情形、它对未知/缺省语言返回 `undefined`、以及它的 lazy 路径（lazy 语法首次触碰返回纯文本，import 注册且订阅者触发后再高亮）；还有 `ReadBlock` 的带行号行保留文件自身编号、高亮与纯文本两条内容分支、横幅（标签、语言、仅当读取是窗口时的计数提示）、头/尾高度上限及其 `aria-expanded` 切换、复制控件在接受与拒绝两条剪贴板路径上写入窗口原始文本、以及空窗口分支隐藏复制控件。`code-block.spec.tsx` 覆盖 `highlightToHtml`，含它对每种读取卡片语法的 lazy 路径（每个动态 import thunk 各触碰一次）。`ReadBlock.tsx`、`highlight.ts`（及 `CodeBlock.tsx`）在这两个 spec 上均保持每文件 100% 覆盖。
 
-`packages/client/ui-conversation/tests/read-card.spec.tsx` 固定每个渲染点的接线：`readCardModel` 的派生与每条 null 分支（运行中读取、无视图、通用视图、未知卡片）、结果标题替换化简后的路径、路径相对工作区的化简、冻结行数组的复制而非别名；`GenericToolCard` 回退中与 keyed `ReadRow` 中的常驻卡片（外加其路径链接打开宿主、其 running/error/stopped 状态、以及其 `read` 键注册）；还有面板 Output 区段以全高渲染读取卡片同时保留 JSON Input 区段，含运行中读取占位与非读取摊平 pre 两条分支。该文件位于覆盖 `exclude` 列表（`ui-conversation/src/*`），因此不承受门槛压力。
+`packages/client/ui-tool/tests/read-card.spec.tsx` 固定每个渲染点的接线：`readCardModel` 的派生与每条 null 分支（运行中读取、无视图、通用视图、未知卡片）、结果标题替换化简后的路径、路径相对工作区的化简、冻结行数组的复制而非别名；`GenericToolCard` 回退中与 keyed `ReadRow` 中的常驻卡片（外加其路径链接打开宿主、其 running/error/stopped 状态、以及其 `read` 键注册）；还有面板 Output 区段以全高渲染读取卡片同时保留 JSON Input 区段，含运行中读取占位与非读取摊平 pre 两条分支。该文件位于覆盖 `exclude` 列表（`ui-tool/src/*`），因此不承受门槛压力。
 
 fixture（`packages/client/connection/src/client/fixture.ts`）增加 turn 66，一次 `read` 调用，其结果视图是窗口读取（行号从文件行 41 起、`totalLines` 180、`ts` 提示），使内置启动快照和实时 `?fixture` 服务器展示带行号、高亮和计数提示的读取卡片。它命名为 `read` 以驱动 keyed `ReadRow`。turn 64 的 `run_code` 样例中的嵌套读取子派发并不驱动渲染点回退读取卡片：`session.ts` 把它们折叠为 `resultView: null`，因此它们只覆盖回退行的通用行形状，而非回退行内的读取卡片；回退行读取卡片由 `read-card.spec.tsx` 的 `web_fetch` 用例钉住。turn 66 排在 todo turn（现为 67）之前，与终端样例同因：常驻计划在下一次 `turn/start` 退场。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index aab320ac99..ded72420fc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.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 .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
-2026-07-30-web-result-card-frontend.md: 7457f30f71e811960ecadeb49caedef276682505
-2026-07-30-web-result-card-frontend.zh.md: 5fa53c4ecbeda40bd18a3c4e59ec75bd4358662d
+2026-07-30-web-result-card-frontend.md: 1d58710dbce3ed1aa9337e1841940195f71db40a
+2026-07-30-web-result-card-frontend.zh.md: 8705aa05557c1fdf642f498939bc2ceddde91f1f
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
index 7457f30f71..1d58710dbc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
@@ -10,7 +10,7 @@ The `web_search` and `web_fetch` tools declare a `card: 'web'` result view ([web
 
 ## Decision
 
-`WebBlock` is a `ui-primitives` component that renders a completed web retrieval, and every Web render site for a web call consumes the `web` render intent through it: the keyed chat tool rows (`web_search`/`web_fetch`), the `GenericToolCard` render-site fallback, and the details panel's Output section. `ui-conversation/src/client/contract/web-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, mirroring `terminal-card-model.ts`, so no two sites disagree about what a web call shows. It returns null — the generic path — for a running call (the web card is result-only, since the tools keep a generic pending view), for a settled call whose result view is not a web card including a `card` value this client version does not know (which arrives over the wire and so cannot be trusted to be a compiled variant), for a generic result view (a web tool's error path returns the generic card, whose text the generic path preserves), and for a web card whose `kind` this client version does not know (a newer host's value off the wire, which reading as a fetch would draw as an empty URL and `HTTP undefined`).
+`WebBlock` is a `ui-primitives` component that renders a completed web retrieval, and every Web render site for a web call consumes the `web` render intent through it: the keyed chat tool rows (`web_search`/`web_fetch`), the `GenericToolCard` render-site fallback, and the details panel's Output section. `ui-tool/src/client/models/web-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, mirroring `terminal-card-model.ts`, so no two sites disagree about what a web call shows. It returns null — the generic path — for a running call (the web card is result-only, since the tools keep a generic pending view), for a settled call whose result view is not a web card including a `card` value this client version does not know (which arrives over the wire and so cannot be trusted to be a compiled variant), for a generic result view (a web tool's error path returns the generic card, whose text the generic path preserves), and for a web card whose `kind` this client version does not know (a newer host's value off the wire, which reading as a fetch would draw as an empty URL and `HTTP undefined`).
 
 One component draws both kinds, discriminated by `kind`. A `search` shows the answer as markdown above a citation list; each source is a safe external link labelled by its title, or its hostname when the provider gave none, with the snippet and publication date below it, and a `来源列表已截断` indicator when the tool capped the list. A `fetch` shows a compact summary: the linked final URL, its HTTP status, and a `内容已截断` indicator. One component rather than two because both are web retrieval rendered as one card family, which is exactly the reason the contract carries them under one `card` tag with a `kind` discriminant.
 
@@ -38,7 +38,7 @@ A separate later PR unifies the whole-row collapse/expand interaction and will f
 
 `packages/client/ui-primitives/tests/web-block.spec.tsx` pins the component per-file to the 100% gate: both kinds; the title-or-hostname-or-raw-URL label fallback; the safe-link attributes on both kinds (an http(s) URL becoming an external anchor with `target`/`rel`, a `javascript:`/`file:`/unparseable URL rendering as a plain span with no href); the snippet and date shown or omitted on present/empty/absent; the truncation indicator gated on the flag; and the full source list rendering inside one scroll container with no expand control and `<li value>` numbering every source contiguously from 1.
 
-`packages/client/ui-conversation/tests/web-card.spec.tsx` mirrors `terminal-card.spec.tsx` at every wiring seam: `webCardModel`'s derivation projecting every source field, its truncation and absent-answer arms, the fetch derivation, and each null arm (running, null result view, generic result view, unknown card tag, unknown web `kind`); the keyed `WebRow`'s resident card for both kinds, its summary-row-alone running and failed arms; the `GenericToolCard` fallback growing the resident card for a web-declaring tool and keeping the plain row for a non-web call; the details panel's Output section for both kinds — including a `web_fetch`'s body flattened below its URL/status card — and its flattened fallback for a non-web result; and the keyed registration under both `web_search` and `web_fetch` with one component. That file sits on the coverage `exclude` list (`ui-conversation/src/*`), so a coverage run measures none of it.
+`packages/client/ui-tool/tests/web-card.spec.tsx` mirrors `terminal-card.spec.tsx` at every wiring seam: `webCardModel`'s derivation projecting every source field, its truncation and absent-answer arms, the fetch derivation, and each null arm (running, null result view, generic result view, unknown card tag, unknown web `kind`); the keyed `WebRow`'s resident card for both kinds, its summary-row-alone running and failed arms; the `GenericToolCard` fallback growing the resident card for a web-declaring tool and keeping the plain row for a non-web call; the details panel's Output section for both kinds — including a `web_fetch`'s body flattened below its URL/status card — and its flattened fallback for a non-web result; and the keyed registration under both `web_search` and `web_fetch` with one component. That file sits on the coverage `exclude` list (`ui-tool/src/*`), so a coverage run measures none of it.
 
 The fixture (`packages/client/connection/src/client/fixture.ts`) adds turns 66 (`web_search`) and 67 (`web_fetch`), authored inline because the client-side fixture cannot import the web tool: turn 66's result view carries an answer and three sources exercising the citation list (a titled source with a snippet and date, a source with no title so its hostname labels the link, and a source with a date but no snippet) with the capped indicator on; turn 67's carries the fetched URL and a 200 status. Both keep a generic pending call view and add the `web` card only at result time, matching the contract's result-only web shape, and are named after the real tools so they hit the keyed `WebRow`. They are ordered before the todo turn (renumbered to 68) for the same reason the terminal turn is: the standing plan retires at the next `turn/start`, so a turn appended after it would empty the dock's plan strip. This drives the built-boot snapshot and a live `?fixture` server.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index 5fa53c4ecb..8705aa0555 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-conversation/src/client/contract/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
+`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
 
 一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是契约把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
 
@@ -38,7 +38,7 @@ Status: implemented
 
 `packages/client/ui-primitives/tests/web-block.spec.tsx` 把组件钉到 per-file 100% 门槛:两种 kind;标题-或-主机名-或-原始 URL 的标签回退;两种 kind 上的安全链接属性（http(s) URL 成为带 `target`/`rel` 的外链,`javascript:`/`file:`/无法解析的 URL 渲染为无 href 的纯 span）;snippet 与日期在存在/为空/缺失时的显示或省略;由标志位控制的截断提示;以及完整 source 列表渲染在单个滚动容器内、无展开控件、`<li value>` 从 1 起为每条 source 连续编号。
 
-`packages/client/ui-conversation/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-conversation/src/*`）,因此覆盖率运行不度量它。
+`packages/client/ui-tool/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-tool/src/*`）,因此覆盖率运行不度量它。
 
 fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配契约的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
index 2d2b338b6f..1578f0c73e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.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 .agents/notes/implemented/feature/2026-07-30-web-search-card.md
-2026-07-30-web-search-card.md: 4c7ae6c8c658f4f10f0667b12853cb2e70df15b1
-2026-07-30-web-search-card.zh.md: b129d411b9b402b18d6b4ec94dad544effd3bb8c
+2026-07-30-web-search-card.md: a350756a22d2ba5da8a0ff5d3a4cb3f257ac566b
+2026-07-30-web-search-card.zh.md: d6ec2a08eb02a92a50d4742c3d87c22f42c095d4
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
index 4c7ae6c8c6..a350756a22 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
@@ -12,7 +12,7 @@ This is the follow-up the search render card note names: that PR was the backend
 
 ## Decision
 
-`SearchBlock` is a `ui-primitives` component that renders a completed search as either shape, and the Web render sites for a `grep`/`glob` call consume the search render intent through it. `ui-conversation/src/client/contract/search-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so no render site re-derives the shape. It returns null — the generic path — whenever the result view is not a search card, including a still-running call (a search card is result-time only, so there is nothing before `execute`), a generic result a `grep`/`glob` failure or a nested `run_code` dispatch produces, a terminal result view, a `card` value this client version does not know, a `card: 'search'` view whose `shape` this version does not compile, and — because `shape` and the grouped/flat contents ride the same untrusted wire frame the host schema only string-checks — a known `shape` whose `files`/`paths` is missing or malformed (which would otherwise crash `SearchBlock` at `.reduce`/`.map`). The result-view discriminant is `shape` (not `kind`, which the backend reserves for the call view's icon-picking tag); `SearchBlock`'s own prop stays `kind`, mapped from `shape` in this derivation.
+`SearchBlock` is a `ui-primitives` component that renders a completed search as either shape, and the Web render sites for a `grep`/`glob` call consume the search render intent through it. `ui-tool/src/client/models/search-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so no render site re-derives the shape. It returns null — the generic path — whenever the result view is not a search card, including a still-running call (a search card is result-time only, so there is nothing before `execute`), a generic result a `grep`/`glob` failure or a nested `run_code` dispatch produces, a terminal result view, a `card` value this client version does not know, a `card: 'search'` view whose `shape` this version does not compile, and — because `shape` and the grouped/flat contents ride the same untrusted wire frame the host schema only string-checks — a known `shape` whose `files`/`paths` is missing or malformed (which would otherwise crash `SearchBlock` at `.reduce`/`.map`). The result-view discriminant is `shape` (not `kind`, which the backend reserves for the call view's icon-picking tag); `SearchBlock`'s own prop stays `kind`, mapped from `shape` in this derivation.
 
 The asymmetry with the terminal card is deliberate and inherited from the backend contract: `terminalCardModel` reads both `callView` and `resultView` because a command, cwd, and description exist at call time; `searchCardModel` reads only `resultView` because a search's matches or paths exist only after execution. A running search row therefore shows its summary alone, with no card.
 
@@ -34,7 +34,7 @@ Geometry, radius, and fonts mirror `CodeBlock` and `TerminalBlock`, so a search
 
 Three sites consume the derivation, mirroring the terminal card's placement exactly:
 
-- **The keyed `SearchRow`** (`toolviews/search-row.tsx`) registers ONE component under both `grep` and `glob` in the `conversation.chat.toolview` keyed hole, and renders the card RESIDENT under the summary row, capped at `CHAT_SEARCH_MAX_LINES` (8) — the same posture `BashRow` takes for its terminal card. Both tool names get the same row because the derived `kind` decides the shape, so a second component would duplicate it. A capped result's recovery footer sits below the card. Because the keyed row owns this render slot, a settled call with no search card — an errored search (grep/glob emit no result view on error), a successful nested `run_code` sub-dispatch (the backend computes no `presentationMeta`, so `resultView` is null), or a legacy generic result — would otherwise show only its summary with its content lost; the row surfaces that model-facing text as a fallback body, keyed on `search === null && settled` rather than on the error state alone. (This resident posture matches the current terminal/diff cards; a separate later PR unifies the whole-row collapse/expand interaction and flips all resident cards at once — out of scope here.)
+- **The keyed `SearchRow`** (`toolviews/search-row.tsx`) registers ONE component under both `grep` and `glob` in the `tool.call.toolview` keyed hole, and renders the card RESIDENT under the summary row, capped at `CHAT_SEARCH_MAX_LINES` (8) — the same posture `BashRow` takes for its terminal card. Both tool names get the same row because the derived `kind` decides the shape, so a second component would duplicate it. A capped result's recovery footer sits below the card. Because the keyed row owns this render slot, a settled call with no search card — an errored search (grep/glob emit no result view on error), a successful nested `run_code` sub-dispatch (the backend computes no `presentationMeta`, so `resultView` is null), or a legacy generic result — would otherwise show only its summary with its content lost; the row surfaces that model-facing text as a fallback body, keyed on `search === null && settled` rather than on the error state alone. (This resident posture matches the current terminal/diff cards; a separate later PR unifies the whole-row collapse/expand interaction and flips all resident cards at once — out of scope here.)
 - **The generic fallback** (`chat/GenericToolCard` → `chat/ToolRow`) threads the derived model as an expand-gated body, the same arm `terminal` uses: a `grep`/`glob` result with no keyed row (none in the shipped app, since both are registered) still renders its card, with the recovery footer, behind the row's expand toggle.
 - **The details panel** (`skeleton/DetailsPanel`) renders the card at the primitive's own full height in the Output section, with the recovery footer below it, keeping the JSON Input section.
 
@@ -56,7 +56,7 @@ Three sites consume the derivation, mirroring the terminal card's placement exac
 
 `packages/client/ui-primitives/tests/search-block.spec.tsx` pins the component at per-file 100%: both kinds, the folded pre-cap total in the summary, the empty arm, per-file collapse/re-expand without touching neighbours, a file header counting as one capped row alongside its matches, the tail slice restoring its owning file header when the cut falls mid-file, the head/tail cap and its expand control across both shapes and the no-tail and default-cap edges, and the copy control writing the whole structured result on the accepted and refused clipboard paths.
 
-`packages/client/ui-conversation/tests/search-card.spec.tsx` pins the wiring at every render site: `searchCardModel`'s derivation for both kinds, the truncation signal, the replacement title, the recovery text surfaced only when capped, each null arm (running, no views, generic, terminal, unknown card, an uncompiled `kind`, and a known kind with a missing/malformed shape); the chat row's expand-gated matches and paths bodies through `GenericToolCard` (with the recovery footer) against the non-search args-JSON body; `SearchRow`'s resident card for both kinds, its recovery footer, its fallback body for both an errored search and a settled cardless result, its agreement with the summary row's run state, the replacement-title precedence, and the keyed registration under both `grep` and `glob` with one component; and the details panel's Output section for both kinds (with the recovery footer) against the non-search flattened form. `packages/client/ui-conversation/src/*` sits on the coverage exclude list, so this file is written against no gate pressure. `packages/client/connection/src/client/fixture.ts` gains a `grep` turn emitting `kind: 'matches'` (three files, twelve rows over the row cap, `truncated` with a spill-recovery footer, so it exercises the head/tail cap and the recovery footer in the assembled snapshot) and a `glob` turn emitting `kind: 'paths'`, both driving the built-boot snapshot and the live `?fixture` server. `apps/web/tests/search-card.snapshot.ts` is the assembled-output check the repo contract asks for: it boots the real built `client.js` bundles through the keyless fixture transport, opens the fixture session, and pins the grep card's assembled shape — kind, truncation summary, the head/tail slice, and its expand control — under `apps/web/tests/snapshots/search-card/`, so a broken SearchRow registration or a dropped card fails a golden the built-boot smoke (boot-only by contract) cannot.
+`packages/client/ui-tool/tests/search-card.spec.tsx` pins the wiring at every render site: `searchCardModel`'s derivation for both kinds, the truncation signal, the replacement title, the recovery text surfaced only when capped, each null arm (running, no views, generic, terminal, unknown card, an uncompiled `kind`, and a known kind with a missing/malformed shape); the chat row's expand-gated matches and paths bodies through `GenericToolCard` (with the recovery footer) against the non-search args-JSON body; `SearchRow`'s resident card for both kinds, its recovery footer, its fallback body for both an errored search and a settled cardless result, its agreement with the summary row's run state, the replacement-title precedence, and the keyed registration under both `grep` and `glob` with one component; and the details panel's Output section for both kinds (with the recovery footer) against the non-search flattened form. `packages/client/ui-tool/src/*` sits on the coverage exclude list, so this file is written against no gate pressure. `packages/client/connection/src/client/fixture.ts` gains a `grep` turn emitting `kind: 'matches'` (three files, twelve rows over the row cap, `truncated` with a spill-recovery footer, so it exercises the head/tail cap and the recovery footer in the assembled snapshot) and a `glob` turn emitting `kind: 'paths'`, both driving the built-boot snapshot and the live `?fixture` server. `apps/web/tests/search-card.snapshot.ts` is the assembled-output check the repo contract asks for: it boots the real built `client.js` bundles through the keyless fixture transport, opens the fixture session, and pins the grep card's assembled shape — kind, truncation summary, the head/tail slice, and its expand control — under `apps/web/tests/snapshots/search-card/`, so a broken SearchRow registration or a dropped card fails a golden the built-boot smoke (boot-only by contract) cannot.
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
index b129d411b9..d6ec2a08eb 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## Decision
 
-`SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-conversation/src/client/contract/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
+`SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-tool/src/client/models/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
 
 与终端卡片的不对称是刻意的，继承自后端契约：`terminalCardModel` 同时读 `callView` 和 `resultView`，因为命令、cwd、description 在调用时就存在；`searchCardModel` 只读 `resultView`，因为搜索的匹配或路径只在执行后存在。因此运行中的搜索行只显示摘要，没有卡片。
 
@@ -34,7 +34,7 @@ Status: implemented
 
 三个渲染点消费该推导，与终端卡片的落位完全一致：
 
-- **keyed `SearchRow`**（`toolviews/search-row.tsx`）把一个组件同时注册到 `conversation.chat.toolview` keyed hole 的 `grep` 与 `glob` 键下，并把卡片作为常驻（resident）渲染在摘要行下方，上限为 `CHAT_SEARCH_MAX_LINES`（8）—— 与 `BashRow` 对其终端卡片采取的姿态相同。两个工具名共用同一行，因为推导出的 `kind` 决定形态，第二个组件只会重复它。被截断结果的恢复脚注画在卡片下方。因为 keyed 行占据了这个渲染槽，一个没有搜索卡片的已结算调用 —— 出错的搜索（grep/glob 出错时不产出结果视图）、成功的嵌套 `run_code` 子派发（后端不为其计算 `presentationMeta`，故 `resultView` 为 null）、或旧日志的 generic 结果 —— 否则只会显示摘要而丢失内容；该行把这段面向模型的文本作为 fallback body 暴露出来，判据是 `search === null && 已结算`，而非仅凭错误状态。（该常驻姿态与当前的 terminal/diff 卡片一致；一个单独的后续 PR 会统一整行折叠/展开交互并一次性翻转所有常驻卡片 —— 不在本 PR 范围内。）
+- **keyed `SearchRow`**（`toolviews/search-row.tsx`）把一个组件同时注册到 `tool.call.toolview` keyed hole 的 `grep` 与 `glob` 键下，并把卡片作为常驻（resident）渲染在摘要行下方，上限为 `CHAT_SEARCH_MAX_LINES`（8）—— 与 `BashRow` 对其终端卡片采取的姿态相同。两个工具名共用同一行，因为推导出的 `kind` 决定形态，第二个组件只会重复它。被截断结果的恢复脚注画在卡片下方。因为 keyed 行占据了这个渲染槽，一个没有搜索卡片的已结算调用 —— 出错的搜索（grep/glob 出错时不产出结果视图）、成功的嵌套 `run_code` 子派发（后端不为其计算 `presentationMeta`，故 `resultView` 为 null）、或旧日志的 generic 结果 —— 否则只会显示摘要而丢失内容；该行把这段面向模型的文本作为 fallback body 暴露出来，判据是 `search === null && 已结算`，而非仅凭错误状态。（该常驻姿态与当前的 terminal/diff 卡片一致；一个单独的后续 PR 会统一整行折叠/展开交互并一次性翻转所有常驻卡片 —— 不在本 PR 范围内。）
 - **generic fallback**（`chat/GenericToolCard` → `chat/ToolRow`）把推导出的 model 作为展开门控的 body 传入，与 `terminal` 用的是同一分支：没有 keyed 行的 `grep`/`glob` 结果（发布应用里没有，因为两者都注册了）仍在行的展开开关后渲染其卡片，并带恢复脚注。
 - **details panel**（`skeleton/DetailsPanel`）在 Output 段以 primitive 自身的完整高度渲染卡片，恢复脚注画在其下方，保留 JSON Input 段。
 
@@ -56,7 +56,7 @@ Status: implemented
 
 `packages/client/ui-primitives/tests/search-block.spec.tsx` 以 per-file 100% 覆盖固定组件：两种 kind、折入摘要的截断前总数、空结果分支、逐文件折叠/再展开且不影响邻居、一个文件头与其匹配一起计为一个被截断行、切口落在文件中间时尾部切片恢复其所属文件头、跨两种形态的头/尾上限及其展开控件（含无尾与默认上限的边界），以及复制控件在接受与拒绝的剪贴板路径上写入整个结构化结果。
 
-`packages/client/ui-conversation/tests/search-card.spec.tsx` 固定每个渲染点的接线：`searchCardModel` 对两种 kind 的推导、截断信号、替换标题、仅在截断时暴露的恢复文本，以及每个 null 分支（运行中、无视图、generic、terminal、未知卡片、本版本无法编译的 `kind`、以及一个形态缺失/错误的已知 kind）；通过 `GenericToolCard` 的展开门控 matches 与 paths body（含恢复脚注），对照非搜索的 args-JSON body；`SearchRow` 对两种 kind 的常驻卡片、它的恢复脚注、它对出错搜索与已结算无卡片结果两者的 fallback body、它与摘要行运行状态的一致、替换标题优先级，以及一个组件在 `grep` 与 `glob` 两个键下的 keyed 注册；以及 details panel 的 Output 段对两种 kind（含恢复脚注），对照非搜索的压平形态。`packages/client/ui-conversation/src/*` 在覆盖排除清单上，因此该文件不受 gate 压力。`packages/client/connection/src/client/fixture.ts` 新增一个发出 `kind: 'matches'` 的 `grep` turn（三个文件、十二行超过行内上限、`truncated` 且带溢出恢复脚注，因此在组装快照里同时演练头/尾上限与恢复脚注）与一个发出 `kind: 'paths'` 的 `glob` turn，两者都驱动 built-boot snapshot 与实时 `?fixture` 服务。`apps/web/tests/search-card.snapshot.ts` 是仓库契约要求的组装输出检查：它通过 keyless fixture 传输启动真实构建的 `client.js` bundle，打开 fixture 会话，并把 grep 卡片的组装形态——kind、截断摘要、头/尾切片及其展开控件——固定在 `apps/web/tests/snapshots/search-card/` 下，因此一个损坏的 SearchRow 注册或被丢弃的卡片会让一个 golden 失败，而 built-boot smoke（按契约只测启动）无法捕获它。
+`packages/client/ui-tool/tests/search-card.spec.tsx` 固定每个渲染点的接线：`searchCardModel` 对两种 kind 的推导、截断信号、替换标题、仅在截断时暴露的恢复文本，以及每个 null 分支（运行中、无视图、generic、terminal、未知卡片、本版本无法编译的 `kind`、以及一个形态缺失/错误的已知 kind）；通过 `GenericToolCard` 的展开门控 matches 与 paths body（含恢复脚注），对照非搜索的 args-JSON body；`SearchRow` 对两种 kind 的常驻卡片、它的恢复脚注、它对出错搜索与已结算无卡片结果两者的 fallback body、它与摘要行运行状态的一致、替换标题优先级，以及一个组件在 `grep` 与 `glob` 两个键下的 keyed 注册；以及 details panel 的 Output 段对两种 kind（含恢复脚注），对照非搜索的压平形态。`packages/client/ui-tool/src/*` 在覆盖排除清单上，因此该文件不受 gate 压力。`packages/client/connection/src/client/fixture.ts` 新增一个发出 `kind: 'matches'` 的 `grep` turn（三个文件、十二行超过行内上限、`truncated` 且带溢出恢复脚注，因此在组装快照里同时演练头/尾上限与恢复脚注）与一个发出 `kind: 'paths'` 的 `glob` turn，两者都驱动 built-boot snapshot 与实时 `?fixture` 服务。`apps/web/tests/search-card.snapshot.ts` 是仓库契约要求的组装输出检查：它通过 keyless fixture 传输启动真实构建的 `client.js` bundle，打开 fixture 会话，并把 grep 卡片的组装形态——kind、截断摘要、头/尾切片及其展开控件——固定在 `apps/web/tests/snapshots/search-card/` 下，因此一个损坏的 SearchRow 注册或被丢弃的卡片会让一个 golden 失败，而 built-boot smoke（按契约只测启动）无法捕获它。
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
index a2710c73f9..255dd08832 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.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 .agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
-2026-07-30-web-tool-row-unified-expand-and-inspect.md: 98f1595564f0bd0d22f1ca4318b4c7fe15c6900d
-2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: 8f00349a975f777cc4d556ade3a9abe9676b8848
+2026-07-30-web-tool-row-unified-expand-and-inspect.md: 4fcf1e9a567b73cd04f1bbed170c391aaedd9e73
+2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: 92d70f5aa6bd09e6f9e54015dafc38d8d3690a9e
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
index 98f1595564..4fcf1e9a56 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
@@ -16,7 +16,7 @@ The chat view's tool rows had drifted into per-surface interaction dialects: Too
 - The expanded card (figma 1249:35657) is a column of IN/OUT sections: each section is its own scrollport (max-height 150px) with a sticky gutter label, and the l2 divider spans the full card width. Think prose and the run_code CodeBlock keep their non-card bodies; context injection reuses the row with a label-less `plainBody` card.
 - `terminalFailed` reads a settled terminal card's exit status so BashRow and GenericToolCard surface a failing command as the row's red state dot — the only failure signal the collapsed row has, since the call itself settles `isError:false`.
 - TerminalBlock's banner joins the same reading model: it shares the card surface (no banner token), an l2 hairline separates it from the body, the command column caps at 150px and scrolls with sticky copy/status controls top-aligned to the first prompt row.
-- Inspect: `ToolRowOwnerProps.inspect` (absent for rows without a call identity) renders a pill in real flow under the expanded body's bottom-left, revealed by hovering anywhere on the tool call. Clicking writes `{ callId }` to the chat store's one-shot `inspect` field and switches to the trajectory view; TrajectoryTable finds the record, opens its summary, and acknowledges by clearing the field.
+- Inspect: `ToolCallOwnerProps.inspect` (absent for rows without a call identity) renders a pill in real flow under the expanded body's bottom-left, revealed by hovering anywhere on the tool call. Clicking writes `{ callId }` to the chat store's one-shot `inspect` field and switches to the trajectory view; TrajectoryTable finds the record, opens its summary, and acknowledges by clearing the field.
 - Scroll preservation: on every non-bottom scroll, the chat view saves `{ anchorKey, anchorTop, scrollTop }` into an apply-scope per-session map exposed as `chatScroll`; a remount first uses `scrollTop` to reach the approximate window, then corrects by the stable node/call anchor's rectangle delta so width reflow keeps the same reading row in place. Every pinned path, including Back to bottom, clears the entry synchronously before a tab or session switch. The map remains deliberately unpersisted — a fresh page load keeps the open-jump-to-bottom default.
 
 ## Alternatives considered
@@ -31,4 +31,4 @@ The chat view's tool rows had drifted into per-surface interaction dialects: Too
 
 ## Consequences
 
-Any registered toolview gets input AND output inspection in place, with the details panel and trajectory remaining the deep-dive surfaces. The unified interaction is contract-visible (`ToolRowProps.output/errorSummary/inspect`), so third-party rows opt in by passing model fields through. The bash sample intentionally re-replicates the new CSS (registrant posture), so future interaction changes still touch it by hand. `--dsw-font-markdown-code-block-small` (12/18) is a hand-added token pending a design-platform export. The web-cordis `distIndex` fix (plain concatenation, not URL.pathname) unblocks preview boots from a cwd with spaces.
+Built-in ui-tool views get input and output inspection in place, with the details panel and trajectory remaining the deep-dive surfaces. The shared `ToolRow` interaction is internal to ui-tool; an external atomic view receives `ToolCallViewProps` and may expose the supplied `inspect` callback through its own chrome. The bash view keeps its separate CSS, so future interaction changes still touch it explicitly. `--dsw-font-markdown-code-block-small` (12/18) is a hand-added token pending a design-platform export. The web-cordis `distIndex` fix (plain concatenation, not URL.pathname) unblocks preview boots from a cwd with spaces.
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
index 8f00349a97..92d70f5aa6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
@@ -16,7 +16,7 @@
 - 展开卡片（figma 1249:35657）是 IN/OUT 分区列：每个分区是独立滚动区（max-height 150px），侧栏标签 sticky 固定，l2 分割线横贯整卡宽度。Think 的推理文本和 run_code 的 CodeBlock 保持非卡片体；上下文注入复用此行并以无标签的 `plainBody` 卡片展开。
 - `terminalFailed` 读取已结算 terminal 卡片的退出状态，让 BashRow 和 GenericToolCard 把失败命令显示为行的红色状态点——这是折叠行唯一的失败信号，因为调用本身结算为 `isError:false`。
 - TerminalBlock 的横幅并入同一阅读模型：与卡片共用同一表面（不再用 banner token），与正文之间是 l2 细线，命令列上限 150px 内部滚动，复制/状态控件 sticky 且顶对齐第一行提示符。
-- Inspect：`ToolRowOwnerProps.inspect`（无调用身份的行不提供）在展开体左下角以真实布局位置渲染胶囊，hover 整个 tool call 任意位置显示。点击将 `{ callId }` 写入 chat store 的一次性 `inspect` 字段并切换到 trajectory 视图；TrajectoryTable 找到记录、打开其摘要，并通过清空字段确认。
+- Inspect：`ToolCallOwnerProps.inspect`（无调用身份的行不提供）在展开体左下角以真实布局位置渲染胶囊，hover 整个 tool call 任意位置显示。点击将 `{ callId }` 写入 chat store 的一次性 `inspect` 字段并切换到 trajectory 视图；TrajectoryTable 找到记录、打开其摘要，并通过清空字段确认。
 - 滚动保留：每次非贴底滚动时，聊天视图把 `{ anchorKey, anchorTop, scrollTop }` 保存到 apply 作用域的按会话 Map，并经注入 props 的 `chatScroll` 暴露；重挂载时先用 `scrollTop` 到达近似窗口，再按稳定 node／call 锚点的矩形差值校正，因此宽度重排后仍把同一阅读行保持在原位。包括「回到底部」在内的每条贴底路径都会在切换 tab 或会话前同步清除该项。Map 仍刻意不持久化——新页面加载保持打开即贴底的默认行为。
 
 ## 曾考虑的替代方案
@@ -31,4 +31,4 @@
 
 ## 后果
 
-任何已注册 toolview 都能就地查看输入与输出，详情面板和 trajectory 仍是深查表面。统一交互契约可见（`ToolRowProps.output/errorSummary/inspect`），第三方行透传模型字段即可接入。bash 示例有意重新复刻新 CSS（注册方姿态），未来交互变更仍需手动同步它。`--dsw-font-markdown-code-block-small`（12/18）是手工补充的 token，待设计平台导出后替换。web-cordis 的 `distIndex` 修复（纯拼接而非 URL.pathname）解除了含空格 cwd 下预览无法启动的问题。
+ui-tool 内置视图都能就地检查输入与输出，详情面板和 trajectory 仍是深查界面。共享 `ToolRow` 交互是 ui-tool 内部实现；外部原子视图接收 `ToolCallViewProps`，可以通过自己的 chrome 暴露其中的 `inspect` 回调。bash 视图保留独立 CSS，因此未来交互变化仍需显式同步。`--dsw-font-markdown-code-block-small`（12/18）是手工补充的 token，待设计平台导出后替换。web-cordis 的 `distIndex` 修复（纯拼接而非 URL.pathname）解除了含空格 cwd 下预览无法启动的问题。
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
index f4f0ef3891..c12de68dc8 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.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 .agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
-2026-08-02-web-thinking-tail-scroll.md: c45840731153627b4ce460ee140257ba33d2c007
-2026-08-02-web-thinking-tail-scroll.zh.md: b8d0444d62294e123bec1d26cb4c07538bbf966f
+2026-08-02-web-thinking-tail-scroll.md: 18e94b2e0075bf7099b9b48177de2e274896942a
+2026-08-02-web-thinking-tail-scroll.zh.md: 9b1428af7d3ab3c25509696619de75adc1cd7b7f
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
index c458407311..18e94b2e00 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
@@ -28,4 +28,4 @@ The collapsed row now communicates provider cadence through content motion as we
 
 ## Testing
 
-`packages/client/ui-conversation/tests/chat-tool-row.spec.tsx` pins the latest-line selection, the calculated right-edge scroll position, and the settlement reset to the first line and `scrollLeft = 0`. The keyless assembled Chromium scenario in `apps/web/tests/lifecycle-chrome.e2e.ts` replays real recorded reasoning chunks at observable pacing, narrows the viewport until the summary overflows, and asserts that the live collapsed Think row reaches its actual browser scroll extent. Its settled replay golden remains unchanged, proving the historical summary contract stays stable.
+`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` pins the latest-line selection, the calculated right-edge scroll position, and the settlement reset to the first line and `scrollLeft = 0`. The keyless assembled Chromium scenario in `apps/web/tests/lifecycle-chrome.e2e.ts` replays real recorded reasoning chunks at observable pacing, narrows the viewport until the summary overflows, and asserts that the live collapsed Think row reaches its actual browser scroll extent. Its settled replay golden remains unchanged, proving the historical summary contract stays stable.
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
index b8d0444d62..9b1428af7d 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
@@ -28,4 +28,4 @@ Web Think 行在结算与流式 block 中都把 reasoning 首行渲染成折叠
 
 ## 测试
 
-`packages/client/ui-conversation/tests/chat-tool-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的 keyless 完整 Chromium 场景以可观察节奏回放真实录制的 reasoning chunks，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态 replay golden 保持不变，证明历史摘要契约仍然稳定。
+`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的 keyless 完整 Chromium 场景以可观察节奏回放真实录制的 reasoning chunks，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态 replay golden 保持不变，证明历史摘要契约仍然稳定。
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
index 80f7ed4ab4..2ba0af23c4 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.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 .agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
-2026-08-03-web-search-source-scroll.md: c11bb2317b6ae6cad8017a4b76cb0b9ccebd6fc0
-2026-08-03-web-search-source-scroll.zh.md: add012216589b33cf244d8a14053a5b6d60631a6
+2026-08-03-web-search-source-scroll.md: 3215302b2f6c7a4e6d6cd7440a0c7f5048b72a80
+2026-08-03-web-search-source-scroll.zh.md: cf75a5e34632872d09a13e1667ecac5f01428e18
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
index c11bb2317b..3215302b2f 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
@@ -36,7 +36,7 @@ Every source the tool returned is always in the DOM, so no source the view carri
 
 ## Testing
 
-`packages/client/ui-primitives/tests/web-block.spec.tsx` drops the collapse cases (head/tail slice, expand-on-click, collapsed-tail numbering, expander-out-of-numbering, head-alone, default cap) and adds: a 30-source card renders all 30 `<li>` with no `[aria-expanded]` and no `<button>`, every `<ol>` child is a source `<li>`, and `<li value>` numbers 1..N contiguously. `packages/client/ui-conversation/tests/web-card.spec.tsx` drops the `CHAT_WEB_MAX_SOURCES` cap assertion; the WebRow expansion test still asserts the card shows every source field. The `packages/web/tool-web` tests are unchanged — the model side did not move.
+`packages/client/ui-primitives/tests/web-block.spec.tsx` drops the collapse cases (head/tail slice, expand-on-click, collapsed-tail numbering, expander-out-of-numbering, head-alone, default cap) and adds: a 30-source card renders all 30 `<li>` with no `[aria-expanded]` and no `<button>`, every `<ol>` child is a source `<li>`, and `<li value>` numbers 1..N contiguously. `packages/client/ui-tool/tests/web-card.spec.tsx` drops the `CHAT_WEB_MAX_SOURCES` cap assertion; the WebRow expansion test still asserts the card shows every source field. The `packages/web/tool-web` tests are unchanged — the model side did not move.
 
 jsdom resolves no CSS Modules layout, so it reports `scrollHeight === clientHeight` for every element and cannot witness the scroll at all. The geometry is pinned in the assembled browser instead, by `apps/web/tests/web-search-round.e2e.ts`: its deterministic search double returns 12 provider results, each with a title, a citation snippet, and a date. That first pins the seam's cap end to end in a real composition — the shipped `searchMaxResults` keeps 8, the model-visible render text carries the 8 kept titles and none of the 4 dropped URLs plus `(Showing the first 8 sources. Refine the query for more.)`, and `meta.truncated` is true. A case after the aria golden then expands the `web_search` row and asserts on the card's `<ol>`: 8 `<li>`, no `<button>` anywhere in the card, the `来源列表已截断` indicator visible, and computed `max-height: 320px` with `overflow-y: auto` over `scrollHeight` 574 against `clientHeight` 320. A further case measures a `999. ` marker in the list's own inherited font and requires the computed `padding-left` to be at least that wide, so the marker room the scroll container cannot clip back is pinned against the widest marker rather than against one fixture's source count. Neither the recorded stream nor the aria golden moved: replay is a positional cursor over the fixture's `assistant/chunk` entries and the search double is a separate local endpoint the provider reaches by `fetch`, while the card is collapsed at capture time so its `<ol>` is out of the DOM and the summary row carries no source count.
 
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
index add0122165..cf75a5e346 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
@@ -36,7 +36,7 @@ Status: implemented
 
 ## Testing
 
-`packages/client/ui-primitives/tests/web-block.spec.tsx` 删去折叠相关用例（首尾切片、点击展开、折叠尾部编号、展开器不计入编号、仅首部、默认上限），并新增：一个 30 条来源的卡片渲染出全部 30 个 `<li>`，无 `[aria-expanded]`、无 `<button>`，每个 `<ol>` 子元素都是一条来源 `<li>`，且 `<li value>` 从 1 到 N 连续编号。`packages/client/ui-conversation/tests/web-card.spec.tsx` 删去 `CHAT_WEB_MAX_SOURCES` 上限断言；WebRow 展开测试仍断言卡片展示每一个来源字段。`packages/web/tool-web` 的测试不变——模型侧未曾移动。
+`packages/client/ui-primitives/tests/web-block.spec.tsx` 删去折叠相关用例（首尾切片、点击展开、折叠尾部编号、展开器不计入编号、仅首部、默认上限），并新增：一个 30 条来源的卡片渲染出全部 30 个 `<li>`，无 `[aria-expanded]`、无 `<button>`，每个 `<ol>` 子元素都是一条来源 `<li>`，且 `<li value>` 从 1 到 N 连续编号。`packages/client/ui-tool/tests/web-card.spec.tsx` 删去 `CHAT_WEB_MAX_SOURCES` 上限断言；WebRow 展开测试仍断言卡片展示每一个来源字段。`packages/web/tool-web` 的测试不变——模型侧未曾移动。
 
 jsdom 不解析 CSS Modules 布局，对任何元素都报 `scrollHeight === clientHeight`，因此它根本无从见证这次滚动。几何改由组装态浏览器钉住，位于 `apps/web/tests/web-search-round.e2e.ts`：其确定性 search double 返回 12 条 provider 结果，每条带标题、引用摘录与日期。这首先在真实组合里端到端钉住 seam 的裁剪——出厂 `searchMaxResults` 保留 8 条，面向模型的 render 文本含这 8 条标题、不含被丢弃的 4 条 URL，并含 `(Showing the first 8 sources. Refine the query for more.)`，`meta.truncated` 为 true。随后位于 aria golden 之后的一个用例展开 `web_search` 行，对卡片的 `<ol>` 断言：8 个 `<li>`、卡片内任何位置都没有 `<button>`、`来源列表已截断` 指示可见，以及计算样式 `max-height: 320px` 与 `overflow-y: auto`，`scrollHeight` 为 574、`clientHeight` 为 320。再后一个用例在列表自身继承的字体下量出 `999. ` 序号的宽度，要求计算后的 `padding-left` 不小于该宽度，从而把滚动容器无从滚回的那段序号空间钉在最宽序号上，而非钉在某一份 fixture 的来源条数上。录制的模型流与 aria golden 都未变动：replay 是对 fixture 中 `assistant/chunk` 条目的位置游标，而 search double 是 provider 经 `fetch` 抵达的另一个本地端点；捕获时卡片处于折叠状态，其 `<ol>` 不在 DOM 中，摘要行也不携带来源数量。
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
index 3be2c476e5..7ea7b3b14f 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.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 .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
-2026-08-06-web-skill-tool-row.md: fcf5c3b5b61c94b0823fe54624c3dc906c520348
-2026-08-06-web-skill-tool-row.zh.md: bef36df44d97af3993c9760a6b6d3add7b7c932c
+2026-08-06-web-skill-tool-row.md: 04e8ffcd6e506142b569e60458af144233810bbd
+2026-08-06-web-skill-tool-row.zh.md: b96b3879f989f4f1934cdffaec83a283d74aa220
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
index fcf5c3b5b6..04e8ffcd6e 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
@@ -10,7 +10,7 @@ The Web transcript renders `skill` calls through the generic fallback row, so a
 
 ## Decision
 
-`ui-skill` registers a component under the existing `conversation.chat.toolview` keyed slot with key `skill`. The component owns its row chrome from the public `ToolRowProps` contract, matching the independent registrant posture used by the Bash sample instead of importing conversation-private components.
+`ui-skill` registers a component under ui-tool's `tool.call.toolview` keyed slot with key `skill`. The component consumes the public `ToolCallViewProps` owner contract and owns its row chrome without importing ui-tool presentation internals.
 
 The collapsed row uses a 14-pixel document-and-sparkle glyph and the Bash row's neutral hierarchy: tertiary glyph, secondary `Skill` title, caption separator, and tertiary skill name. Running, failed, and interrupted calls retain the transcript's shimmer, error dot and first-line summary, and warning dot semantics. A settled call expands through the whole summary row into a 260-pixel bounded `Instructions` card containing the exact durable result text; the existing trajectory `Inspect` handoff remains available below the card.
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
index bef36df44d..b96b3879f9 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
@@ -10,7 +10,7 @@ Web transcript（文本记录）通过通用后备行渲染 `skill` 调用，使
 
 ## 决策
 
-`ui-skill` 在现有的 `conversation.chat.toolview` 键控 slot 下注册 key 为 `skill` 的组件。该组件基于公开的 `ToolRowProps` 契约自行实现行 chrome，沿用 Bash 示例的独立注册方姿态，而不导入 conversation 私有组件。
+`ui-skill` 在 ui-tool 的 `tool.call.toolview` keyed slot 下注册 key 为 `skill` 的组件。该组件消费公开的 `ToolCallViewProps` owner 契约，并自行实现行 chrome，不导入 ui-tool 的展示内部实现。
 
 收起的行使用 14 像素的文档与闪光组合图标，并沿用 Bash 行的中性色层级：图标采用三级色，`Skill` 标题采用二级色，分隔符采用 caption 色，skill 名称采用三级色。运行、失败和中断调用分别沿用 transcript 的扫光、错误状态点加首行摘要，以及警告状态点语义。已结算调用可以通过整个摘要行展开一个高度上限为 260 像素的 `Instructions` 卡片，其中原样呈现持久化结果文本；用于跳转至 trajectory 的现有 `Inspect` 入口仍保留在卡片下方。
 

From 67c753dcb79ad6a0896b2b0748f24b7fde6de265 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:29:26 +0800
Subject: [PATCH 251/516] fix(client): restore built Tool presentation
 snapshots

---
 apps/web/tests/assembled-boot.ts              |   3 +-
 apps/web/tests/built-boot.snapshot.ts         |   2 +-
 .../search-card/grep-card.expected.txt        |  24 ++--
 packages/client/runtime/src/client/index.ts   |   1 +
 .../src/client/workspaces/path.ts}            |  10 +-
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +-
 packages/client/ui-conversation/README.zh.md  |   2 +-
 .../ui-conversation/src/client/apply.ts       |   5 +-
 .../src/client/chat/ContextInjectionRow.tsx   |   3 +-
 .../src/client/chat/DisclosureRow.module.css  |  69 ------------
 .../src/client/chat/GenericCommandCard.tsx    |   3 +-
 .../src/client/chat/ReasoningRow.tsx          |   3 +-
 .../client/ui-primitives/README.i18n.yaml     |   4 +-
 packages/client/ui-primitives/README.md       |   2 +-
 packages/client/ui-primitives/README.zh.md    |   2 +-
 .../src}/DisclosureRow.module.css             |   2 +-
 .../src}/DisclosureRow.tsx                    |   4 +-
 packages/client/ui-primitives/src/index.ts    |   2 +
 .../client/tool/components/DisclosureRow.tsx  | 104 ------------------
 .../src/client/tool/components/ToolRow.tsx    |   3 +-
 .../client/tool/models/terminal-card-model.ts |   5 +-
 .../src/client/tool/models/tool-call-model.ts |  15 ---
 .../client/ui-tool/tests/tool-row.spec.tsx    |  13 ++-
 24 files changed, 49 insertions(+), 238 deletions(-)
 rename packages/client/{ui-conversation/src/client/contract/tool-path.ts => runtime/src/client/workspaces/path.ts} (50%)
 delete mode 100644 packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css
 rename packages/client/{ui-tool/src/client/tool/components => ui-primitives/src}/DisclosureRow.module.css (92%)
 rename packages/client/{ui-conversation/src/client/chat => ui-primitives/src}/DisclosureRow.tsx (95%)
 delete mode 100644 packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx

diff --git a/apps/web/tests/assembled-boot.ts b/apps/web/tests/assembled-boot.ts
index 53f976af09..631196c652 100644
--- a/apps/web/tests/assembled-boot.ts
+++ b/apps/web/tests/assembled-boot.ts
@@ -26,6 +26,7 @@ const PLUGINS: readonly (WebBootEntry & { bundlePath: string })[] = [
   { id: '@deepseek-ai/dsh-client-ui-layout', bundlePath: 'packages/client/ui-layout/lib/client.js', url: '/plugins/ui-layout.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime'] },
   { id: '@deepseek-ai/dsh-client-ui-sidebar', bundlePath: 'packages/client/ui-sidebar/lib/client.js', url: '/plugins/ui-sidebar.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
   { id: '@deepseek-ai/dsh-client-ui-conversation', bundlePath: 'packages/client/ui-conversation/lib/client.js', url: '/plugins/ui-conversation.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
+  { id: '@deepseek-ai/dsh-client-ui-tool', bundlePath: 'packages/client/ui-tool/lib/client.js', url: '/plugins/ui-tool.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime', '@deepseek-ai/dsh-client-locale', '@deepseek-ai/dsh-client-ui-conversation'] },
   {
     id: '@deepseek-ai/dsh-client-ui-workspace',
     bundlePath: 'packages/client/ui-workspace/lib/client.js',
@@ -118,7 +119,7 @@ export function mountAssembledApp(): void {
  * Match a CSS-module class by its logical name.
  * Module class names carry a per-build hash in one of two schemes —
  * ui-primitives emits `_<name>_<hash>` (name bounded by underscores),
- * ui-conversation emits `<hash>_<name>` (name at the end) — and a longer name
+ * feature bundles emit `<hash>_<name>` (name at the end) — and a longer name
  * containing this one must not match (`line` must not hit `lineNumber`).
  * @param el - element whose class list is inspected.
  * @param name - logical (unhashed) module class name.
diff --git a/apps/web/tests/built-boot.snapshot.ts b/apps/web/tests/built-boot.snapshot.ts
index 3d1536e923..80661a0b13 100644
--- a/apps/web/tests/built-boot.snapshot.ts
+++ b/apps/web/tests/built-boot.snapshot.ts
@@ -95,7 +95,7 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn
   // Every bundle injected its plugin-owned style tag (the loader's CSS path).
   const styleOwners = [...document.head.querySelectorAll('style[data-plugin]')]
     .map(style => style.getAttribute('data-plugin'))
-  for (const plugin of ['@deepseek-ai/dsh-client-ui-layout', '@deepseek-ai/dsh-client-ui-sidebar', '@deepseek-ai/dsh-client-ui-conversation']) {
+  for (const plugin of ['@deepseek-ai/dsh-client-ui-layout', '@deepseek-ai/dsh-client-ui-sidebar', '@deepseek-ai/dsh-client-ui-conversation', '@deepseek-ai/dsh-client-ui-tool']) {
     expect(styleOwners).toContain(plugin)
   }
 })
diff --git a/apps/web/tests/snapshots/search-card/grep-card.expected.txt b/apps/web/tests/snapshots/search-card/grep-card.expected.txt
index fbb20677df..160251e62e 100644
--- a/apps/web/tests/snapshots/search-card/grep-card.expected.txt
+++ b/apps/web/tests/snapshots/search-card/grep-card.expected.txt
@@ -1,13 +1,13 @@
 kind=matches
 summary=显示 9 / 共 42 处匹配 · 3 个文件
 file=packages/client/ui-primitives/src/SearchBlock.tsx3
-file=packages/client/ui-conversation/src/client/toolviews/search-row.tsx4
+file=packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx4
 line=16: export const DEFAULT_SEARCH_MAX_LINES = 16
 line=138: export function SearchBlock(props: SearchBlockProps) {
 line=141:   const [collapsed, setCollapsed] = useState<ReadonlySet<number>>(() => new Set())
-line=35:   const search = searchCardModel(block)
-line=52:       search={search}
-line=78:       yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep', locale: NS }, SearchRow)
+line=36:   const search = searchCardModel(block)
+line=56:       search={search}
+line=78:       yield ctx.slots.register({ name: 'tool.call.toolview', key: 'grep', locale: NS }, SearchRow)
 expand=… 其余 4 行
 recovery=Found 9 of 42 matches
 
@@ -15,13 +15,13 @@ packages/client/ui-primitives/src/SearchBlock.tsx
 Line 16: export const DEFAULT_SEARCH_MAX_LINES = 16
 Line 138: export function SearchBlock(props: SearchBlockProps) {
 Line 141:   const [collapsed, setCollapsed] = useState<ReadonlySet<number>>(() => new Set())
-packages/client/ui-conversation/src/client/contract/search-card-model.ts
-Line 24: export const CHAT_SEARCH_MAX_LINES = 8
-Line 60: export function searchCardModel(block: ToolCallBlock): SearchCardModel | null {
-packages/client/ui-conversation/src/client/toolviews/search-row.tsx
-Line 33: export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {
-Line 35:   const search = searchCardModel(block)
-Line 52:       search={search}
-Line 78:       yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep', locale: NS }, SearchRow)
+packages/client/ui-tool/src/client/tool/models/search-card-model.ts
+Line 45: export const CHAT_SEARCH_MAX_LINES = 8
+Line 130: export function searchCardModel(block: ToolCallBlock): SearchCardModel | null {
+packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
+Line 34: export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {
+Line 36:   const search = searchCardModel(block)
+Line 56:       search={search}
+Line 78:       yield ctx.slots.register({ name: 'tool.call.toolview', key: 'grep', locale: NS }, SearchRow)
 
 (Full grep result stored at: fixture://spill/grep-66. Read it to see every match.)
\ No newline at end of file
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index 67e6c0e61c..3c4e8e0bf4 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -24,6 +24,7 @@ export type { SessionProvideChannelHost } from './sessions/provide.ts'
 export { createScope } from './agents/scope.ts'
 export type { AgentScopeHandle } from './agents/scope.ts'
 export { DirectoryBrowseError, WorkspaceCreateError, WorkspacesService } from './workspaces/service.ts'
+export { resolveWorkspacePath } from './workspaces/path.ts'
 export type { Session } from './sessions/session.ts'
 export type { ISession, ProjectionsFace, SessionFace } from './contract/session.ts'
 export type {
diff --git a/packages/client/ui-conversation/src/client/contract/tool-path.ts b/packages/client/runtime/src/client/workspaces/path.ts
similarity index 50%
rename from packages/client/ui-conversation/src/client/contract/tool-path.ts
rename to packages/client/runtime/src/client/workspaces/path.ts
index 38a55937d3..d1512177ad 100644
--- a/packages/client/ui-conversation/src/client/contract/tool-path.ts
+++ b/packages/client/runtime/src/client/workspaces/path.ts
@@ -1,12 +1,10 @@
-/** Resolve a Tool argument path against the session workspace. */
-
 /**
- * Resolve a Tool argument path for the Host opener.
+ * Resolve a workspace-relative path into the Host-facing spelling used by openPath.
  * @param cwd - session workspace root, when known.
- * @param path - path carried by the Tool arguments.
- * @returns an absolute-or-workspace-relative Host path.
+ * @param path - absolute or workspace-relative path.
+ * @returns an absolute path when a workspace root is available, otherwise the original path.
  */
-export function resolveToolPath(cwd: string | undefined, path: string): string {
+export function resolveWorkspacePath(cwd: string | undefined, path: string): string {
   if (path.startsWith('/') || /^[A-Za-z]:[/\\]/.test(path) || path.startsWith('\\\\')) return path
   if (cwd === undefined || cwd === '') return path
   const base = cwd.replace(/[/\\]+$/, '')
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 126729ad9d..2a396a8404 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 3aade8409e74c38cb86a66076cca50d51a1ccbf8
-README.zh.md: 19d08bbc072f1f242417b91ae4dd771f970244b1
+README.md: c4c7a0363c0a2760cf478744073eab96d837b719
+README.zh.md: a34f99f7e4e50750b2ecf024ed9e898c8de09529
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index fa0c4b7b9b..837edaa097 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -16,7 +16,7 @@ Approvals take over the composer through the chain this package declares: `Appro
 
 The session header declares and renders the session-scoped `'conversation.session.header.actions'` list beside the title, allowing feature plugins to contribute controls without entering the skeleton. The composer chain currency includes the current conversation `session`; ui-subagent selects one-shot or parent-unavailable addressed sessions for reason-specific read-only copy, while the ordinary InputBar keeps every addressed child Send-only because the continuation service exposes no public per-Activation cancellation operation and `session.cancel` would bypass its ownership.
 
-Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The package-internal `DisclosureRow` gives this context surface the same compact geometry as other flow rows while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state or summary ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
+Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The shared `DisclosureRow` primitive gives this context surface the same compact geometry as other flow rows while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state or summary ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
 
 A Think row stays collapsed by default and exposes live reasoning throughput without expanding the chain of thought: while its reasoning block is the streaming tail, the summary switches from the settled first line to the latest non-blank line and its one-line scrollport follows each delta to the inline end. Expanding the row removes the moving summary and leaves the full reasoning in ordinary page flow, so page reading never fights an internal follower; settlement restores the stable first-line summary at the left edge ([decision](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)).
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 6dc803ee72..419799666d 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -14,7 +14,7 @@
 
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 
-已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。包内部的 `DisclosureRow` 让该上下文界面与消息流中的其他紧凑行保持相同几何，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态或摘要（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
+已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。共享的 `DisclosureRow` 原子组件让该上下文界面与消息流中的其他紧凑行保持相同几何，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态或摘要（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 74533b5e2d..20056757e6 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -1,7 +1,7 @@
 /** Registers the conversation components, shared store, and service callbacks. */
 import type { Context } from 'cordis'
 import { resolveSlotLabel, type BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ISessions, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { resolveWorkspacePath, type ISessions, type SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
@@ -11,7 +11,6 @@ import type {
   ConversationSessionHeaderInjected, ConversationSessionInjected, DetailsInjected,
 } from './contract/slots.ts'
 import type { InputNotice } from './input/contract.ts'
-import { resolveToolPath } from './contract/tool-path.ts'
 import { createChatStore } from './stores.ts'
 import { ConversationService } from './service.ts'
 import type { IConversation } from './service.ts'
@@ -320,7 +319,7 @@ export function apply(ctx: Context): void {
         },
         openFile: (path) => {
           const cwd = sessions.list.getSnapshot().byId[sessionId]?.cwd
-          void workspaces.openPath(resolveToolPath(cwd, path)).catch(() => {
+          void workspaces.openPath(resolveWorkspacePath(cwd, path)).catch(() => {
             // Host/OS open failures stay silent in the chat row; the native
             // app surfaces its own error dialog when the path is unusable.
           })
diff --git a/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx b/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx
index 6cfc1eebfb..1afdad37f1 100644
--- a/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx
@@ -1,8 +1,7 @@
 import { useState } from 'react'
 import type { ContextMessageNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
-import { IconBrowseOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
-import { DisclosureRow } from './DisclosureRow.tsx'
+import { DisclosureRow, IconBrowseOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import { contextBody } from './ContextBody.tsx'
 import css from './ContextInjectionRow.module.css'
 
diff --git a/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css b/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css
deleted file mode 100644
index 51937ab462..0000000000
--- a/packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css
+++ /dev/null
@@ -1,69 +0,0 @@
-/* Shared conversation disclosure header: [16px leading] gap 6 [title 14/24]. */
-
-.root {
-  display: flex;
-  flex-direction: column;
-  width: 100%;
-  min-width: 0;
-}
-
-.row {
-  position: relative;
-  overflow: hidden;
-  display: flex;
-  align-items: center;
-  height: 24px;
-  min-width: 0;
-}
-
-.row[data-expandable] {
-  cursor: pointer;
-}
-
-.leading {
-  position: relative;
-  flex: none;
-  width: 16px;
-  height: 16px;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  margin-right: 6px;
-  padding: 0;
-  border: none;
-  background: none;
-  color: var(--dsw-alias-label-tertiary);
-}
-
-button.leading {
-  cursor: pointer;
-}
-
-.iconIdle {
-  display: inline-flex;
-  opacity: 1;
-  transition: opacity 100ms ease;
-}
-
-.chevronHover {
-  position: absolute;
-  inset: 0;
-  margin: auto;
-  opacity: 0;
-  transition: opacity 100ms ease;
-}
-
-.row:hover .iconIdle {
-  opacity: 0;
-}
-
-.row:hover .chevronHover {
-  opacity: 1;
-}
-
-.title {
-  flex: none;
-  font-size: 14px;
-  line-height: 24px;
-  color: var(--dsw-alias-label-secondary);
-}
diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index 7bf7d74d2f..b16d838e77 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -6,8 +6,7 @@
 
 import { useState, type ReactNode } from 'react'
 import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
-import { IconApiOutline14, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
-import { DisclosureRow } from './DisclosureRow.tsx'
+import { DisclosureRow, IconApiOutline14, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
 import css from './GenericCommandCard.module.css'
 
 type CommandRowState = 'running' | 'ok' | 'error'
diff --git a/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx b/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
index d02bd855b4..d888451ff7 100644
--- a/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
@@ -1,7 +1,6 @@
 /** Assistant reasoning disclosure, independent of Tool-call presentation. */
 import { useEffect, useRef, useState } from 'react'
-import { IconThinkOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
-import { DisclosureRow } from './DisclosureRow.tsx'
+import { DisclosureRow, IconThinkOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import { useThrottledVisualUpdate } from './use-throttled-visual-update.ts'
 import css from './ReasoningRow.module.css'
 
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 3829879b9d..29ddfa1014 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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/client/ui-primitives/README.md
-README.md: c54759f98a944565959ef21ce538eb9b12fccdf1
-README.zh.md: 32275c19bca9d6e8aa510e982d535a72eb1a06a7
+README.md: fae49d5764d4001f1852cb43aab730064febf2d2
+README.zh.md: 37984b9020df08b8804306111ca13ec0e92e5ce7
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index c54759f98a..fae49d5764 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the OnboardingSurface first-run takeover (body-portaled mask + opaque stage that holds `#root` inert for exactly its own lifetime), the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock. Contract: api-contracts v3 §8.
+Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the OnboardingSurface first-run takeover (body-portaled mask + opaque stage that holds `#root` inert for exactly its own lifetime), the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock. Contract: api-contracts v3 §8.
 
 ## Hover cards
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index 32275c19bc..37984b9020 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。契约：api-contracts v3 §8。
+纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。契约：api-contracts v3 §8。
 
 ## 悬浮卡片
 
diff --git a/packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css b/packages/client/ui-primitives/src/DisclosureRow.module.css
similarity index 92%
rename from packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css
rename to packages/client/ui-primitives/src/DisclosureRow.module.css
index 04f2d18d0a..1aa932826f 100644
--- a/packages/client/ui-tool/src/client/tool/components/DisclosureRow.module.css
+++ b/packages/client/ui-primitives/src/DisclosureRow.module.css
@@ -1,4 +1,4 @@
-/* Shared Tool calls disclosure header: [16px leading] gap 6 [title 14/24]. */
+/* Shared disclosure header: [16px leading] gap 6 [title 14/24]. */
 
 .root {
   display: flex;
diff --git a/packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx b/packages/client/ui-primitives/src/DisclosureRow.tsx
similarity index 95%
rename from packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx
rename to packages/client/ui-primitives/src/DisclosureRow.tsx
index a95114ff2f..f04ad8986a 100644
--- a/packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx
+++ b/packages/client/ui-primitives/src/DisclosureRow.tsx
@@ -1,9 +1,9 @@
 import { type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
 import clsx from 'clsx'
-import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconChevronDownOutline14 } from './icons/index.tsx'
 import css from './DisclosureRow.module.css'
 
-/** Shared 24px disclosure chrome for conversation flow rows. */
+/** Shared 24px disclosure chrome for compact flow rows. */
 export interface DisclosureRowProps {
   icon: ReactNode
   title: string
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index fe0235c496..9aac5da45f 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -4,6 +4,8 @@
 
 export { StateDot } from './StateDot.tsx'
 export type { StateDotState } from './StateDot.tsx'
+export { DisclosureRow } from './DisclosureRow.tsx'
+export type { DisclosureRowProps } from './DisclosureRow.tsx'
 export { Button } from './Button.tsx'
 export type { ButtonVariant } from './Button.tsx'
 export { Pill } from './Pill.tsx'
diff --git a/packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx b/packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx
deleted file mode 100644
index 361fb24517..0000000000
--- a/packages/client/ui-tool/src/client/tool/components/DisclosureRow.tsx
+++ /dev/null
@@ -1,104 +0,0 @@
-import { type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
-import clsx from 'clsx'
-import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
-import css from './DisclosureRow.module.css'
-
-/** Shared 24px disclosure chrome for conversation flow rows. */
-export interface DisclosureRowProps {
-  icon: ReactNode
-  title: string
-  open: boolean
-  expandable: boolean
-  onToggle: () => void
-  /** Makes the complete title row the disclosure target. */
-  expandOnRowClick?: boolean | undefined
-  /** Replaces the collapsed icon with a chevron while the row is hovered. */
-  previewChevron?: boolean | undefined
-  /** Keeps `collapsedContent` inline while open (ToolRow's summary stays readable next to the expanded card). */
-  keepContentWhenOpen?: boolean | undefined
-  collapsedContent?: ReactNode
-  children?: ReactNode
-  className?: string | undefined
-  rowClassName?: string | undefined
-  leadingClassName?: string | undefined
-  chevronClassName?: string | undefined
-  titleClassName?: string | undefined
-}
-
-/**
- * Render one disclosure header and its controlled expanded content.
- * @param props - Visual content, controlled state, and interaction policy.
- * @returns The disclosure row.
- */
-export function DisclosureRow({
-  icon,
-  title,
-  open,
-  expandable,
-  onToggle,
-  expandOnRowClick = false,
-  previewChevron = expandable,
-  keepContentWhenOpen = false,
-  collapsedContent,
-  children,
-  className,
-  rowClassName,
-  leadingClassName,
-  chevronClassName,
-  titleClassName,
-}: DisclosureRowProps) {
-  const rowExpands = expandable && expandOnRowClick
-  const toggleFromLeading = (event: MouseEvent<HTMLButtonElement>) => {
-    event.stopPropagation()
-    onToggle()
-  }
-  const toggleFromKeyboard = (event: KeyboardEvent<HTMLDivElement>) => {
-    if (!rowExpands || (event.key !== 'Enter' && event.key !== ' ')) return
-    event.preventDefault()
-    onToggle()
-  }
-  const collapsedLeading = previewChevron
-    ? (
-      <>
-        <span className={css.iconIdle}>{icon}</span>
-        <IconChevronDownOutline14 className={clsx(chevronClassName, css.chevronHover)} />
-      </>
-    )
-    : icon
-  const leading = open
-    ? <IconChevronDownOutline14 className={chevronClassName} />
-    : collapsedLeading
-
-  return (
-    <div className={clsx(css.root, className)} data-open={open || undefined}>
-      <div
-        className={clsx(css.row, rowClassName)}
-        data-disclosure-row
-        data-expandable={rowExpands || undefined}
-        role={rowExpands ? 'button' : undefined}
-        tabIndex={rowExpands ? 0 : undefined}
-        aria-expanded={rowExpands ? open : undefined}
-        onClick={rowExpands ? onToggle : undefined}
-        onKeyDown={rowExpands ? toggleFromKeyboard : undefined}
-      >
-        {expandable && !rowExpands ? (
-          <button
-            type="button"
-            className={clsx(css.leading, leadingClassName)}
-            aria-expanded={open}
-            onClick={toggleFromLeading}
-          >
-            {leading}
-          </button>
-        ) : (
-          <span className={clsx(css.leading, leadingClassName)}>
-            {leading}
-          </span>
-        )}
-        <span className={clsx(css.title, titleClassName)}>{title}</span>
-        {(keepContentWhenOpen || !open) && collapsedContent}
-      </div>
-      {open && children}
-    </div>
-  )
-}
diff --git a/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
index 61c677ea98..bd4add4234 100644
--- a/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
+++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
@@ -20,7 +20,7 @@
 import { useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
 import clsx from 'clsx'
 import {
-  CodeBlock, DiffBlock, IconInspectOutline12, ReadBlock, SearchBlock, StateDot, TerminalBlock, WebBlock,
+  CodeBlock, DiffBlock, DisclosureRow, IconInspectOutline12, ReadBlock, SearchBlock, StateDot, TerminalBlock, WebBlock,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { WebBlockProps } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
@@ -29,7 +29,6 @@ import { CHAT_READ_MAX_LINES, type ReadCardModel } from '../models/read-card-mod
 import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../models/search-card-model.ts'
 import { terminalBlockLabels, type TerminalCardModel } from '../models/terminal-card-model.ts'
 import type { ToolRowState, ToolRowVariant } from '../models/tool-call-model.ts'
-import { DisclosureRow } from './DisclosureRow.tsx'
 import css from './ToolRow.module.css'
 
 export interface ToolRowProps {
diff --git a/packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts b/packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts
index 8a0c887990..e0609191b7 100644
--- a/packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts
+++ b/packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts
@@ -8,9 +8,10 @@
  * are derived once.
  * @module
  */
+import { resolveWorkspacePath } from '@deepseek-ai/dsh-client-runtime/client'
 import type { TerminalBlockLabels, TerminalBlockProps } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
-import { resolveToolPath, type ToolCallBlock } from './tool-call-model.ts'
+import type { ToolCallBlock } from './tool-call-model.ts'
 
 /**
  * Build the TerminalBlock display copy from the conversation locale seat —
@@ -88,7 +89,7 @@ export function terminalFailed(model: TerminalCardModel): boolean {
 function resolveTerminalCwd(viewCwd: string | undefined, sessionCwd: string | undefined): string | undefined {
   if (viewCwd === undefined || viewCwd === '') return sessionCwd
   if (sessionCwd === undefined || sessionCwd === '') return normalizeSegments(viewCwd)
-  return normalizeSegments(resolveToolPath(sessionCwd, viewCwd))
+  return normalizeSegments(resolveWorkspacePath(sessionCwd, viewCwd))
 }
 
 /**
diff --git a/packages/client/ui-tool/src/client/tool/models/tool-call-model.ts b/packages/client/ui-tool/src/client/tool/models/tool-call-model.ts
index 151ef3b45f..f201f4aac4 100644
--- a/packages/client/ui-tool/src/client/tool/models/tool-call-model.ts
+++ b/packages/client/ui-tool/src/client/tool/models/tool-call-model.ts
@@ -172,21 +172,6 @@ function deriveFilePath(variant: ToolRowVariant, argsRaw: string): string | unde
   return picked === undefined ? undefined : firstLine(picked)
 }
 
-/**
- * Resolve a tool-arg path against the session cwd for host.openPath.
- * Absolute POSIX/Windows paths pass through; relative paths join under cwd.
- * @param cwd - session working directory (may be absent for ungrouped sessions).
- * @param path - path as carried in tool args.
- * @returns a host-facing path string.
- */
-export function resolveToolPath(cwd: string | undefined, path: string): string {
-  if (path.startsWith('/') || /^[A-Za-z]:[/\\]/.test(path) || path.startsWith('\\\\')) return path
-  if (cwd === undefined || cwd === '') return path
-  const base = cwd.replace(/[/\\]+$/, '')
-  const rel = path.replace(/^[/\\]+/, '')
-  return `${base}/${rel}`
-}
-
 function deriveBody(variant: ToolRowVariant, argsRaw: string): string | null {
   if (argsRaw === '') return null
   const parsed = parseArgs(argsRaw)
diff --git a/packages/client/ui-tool/tests/tool-row.spec.tsx b/packages/client/ui-tool/tests/tool-row.spec.tsx
index ab7e1c80f7..f53bcb11f7 100644
--- a/packages/client/ui-tool/tests/tool-row.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.spec.tsx
@@ -5,7 +5,8 @@ import { cleanup, fireEvent, render } from '@testing-library/react'
 import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { classifyTool, resolveToolPath, resultText, toolRowModel } from '../src/client/tool/models/tool-call-model.ts'
+import { resolveWorkspacePath } from '@deepseek-ai/dsh-client-runtime/client'
+import { classifyTool, resultText, toolRowModel } from '../src/client/tool/models/tool-call-model.ts'
 import { ToolRow } from '../src/client/tool/components/ToolRow.tsx'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { zh } from '../../ui-conversation/src/client/locales.ts'
@@ -87,11 +88,11 @@ describe('tool-call-model', () => {
     expect(toolRowModel('bash', running()).filePath).toBeUndefined()
   })
 
-  it('resolveToolPath joins relative paths under cwd and passes absolute through', () => {
-    expect(resolveToolPath('/w', 'src/a.ts')).toBe('/w/src/a.ts')
-    expect(resolveToolPath('/w/', '/abs/a.ts')).toBe('/abs/a.ts')
-    expect(resolveToolPath(undefined, 'src/a.ts')).toBe('src/a.ts')
-    expect(resolveToolPath('/w', 'C:\\x\\a.ts')).toBe('C:\\x\\a.ts')
+  it('resolveWorkspacePath joins relative paths under cwd and passes absolute through', () => {
+    expect(resolveWorkspacePath('/w', 'src/a.ts')).toBe('/w/src/a.ts')
+    expect(resolveWorkspacePath('/w/', '/abs/a.ts')).toBe('/abs/a.ts')
+    expect(resolveWorkspacePath(undefined, 'src/a.ts')).toBe('src/a.ts')
+    expect(resolveWorkspacePath('/w', 'C:\\x\\a.ts')).toBe('C:\\x\\a.ts')
   })
 
   it('displays workspace-rooted paths relative to the session cwd', () => {

From 61f3982348d4117e7f99eb8ce2b20375a568c188 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:31:41 +0800
Subject: [PATCH 252/516] fix: gen docs

---
 docs/config-catalog.md |  1 +
 docs/module-graph.md   | 26 +++++++++++++++++---------
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 43b8bbc4d9..1f81974b21 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2566,6 +2566,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-client-ui-slash` ([`packages/client/ui-slash/src/index.ts`](../packages/client/ui-slash/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-subagent` ([`packages/client/ui-subagent/src/index.ts`](../packages/client/ui-subagent/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-theme` ([`packages/client/ui-theme/src/index.ts`](../packages/client/ui-theme/src/index.ts))
+- `@deepseek-ai/dsh-client-ui-tool` ([`packages/client/ui-tool/src/index.ts`](../packages/client/ui-tool/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-trajectory` ([`packages/client/ui-trajectory/src/index.ts`](../packages/client/ui-trajectory/src/index.ts))
 - `@deepseek-ai/dsh-client-ui-workspace` ([`packages/client/ui-workspace/src/index.ts`](../packages/client/ui-workspace/src/index.ts))
 - `@deepseek-ai/dsh-command-compact` — requires `commands` · `compact` ([`packages/compact/command-compact/src/index.ts`](../packages/compact/command-compact/src/index.ts))
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 14cad0163a..22af77f9c5 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -184,6 +184,7 @@ flowchart TD
     pkg_client_ui_slots["client-ui-slots"]
     pkg_client_ui_subagent["client-ui-subagent"]
     pkg_client_ui_theme["client-ui-theme"]
+    pkg_client_ui_tool["client-ui-tool"]
     pkg_client_ui_trajectory["client-ui-trajectory"]
     pkg_client_ui_workspace["client-ui-workspace"]
     pkg_client_web["client-web"]
@@ -891,14 +892,12 @@ flowchart TD
   pkg_client_ui_goal --> pkg_client_ui_slots
   pkg_client_ui_goal --> pkg_goal
   pkg_client_ui_goal --> pkg_invariants
-  pkg_client_ui_skill --> pkg_client_connection
-  pkg_client_ui_skill --> pkg_client_locale
-  pkg_client_ui_skill --> pkg_client_runtime
-  pkg_client_ui_skill --> pkg_client_ui_conversation
-  pkg_client_ui_skill --> pkg_client_ui_primitives
-  pkg_client_ui_skill --> pkg_client_ui_slash
-  pkg_client_ui_skill --> pkg_client_ui_slots
-  pkg_client_ui_skill --> pkg_invariants
+  pkg_client_ui_tool --> pkg_client_locale
+  pkg_client_ui_tool --> pkg_client_runtime
+  pkg_client_ui_tool --> pkg_client_ui_conversation
+  pkg_client_ui_tool --> pkg_client_ui_primitives
+  pkg_client_ui_tool --> pkg_client_ui_slots
+  pkg_client_ui_tool --> pkg_invariants
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compact
   pkg_session_reference --> pkg_invariants
@@ -1057,6 +1056,14 @@ flowchart TD
   pkg_client_ui_plan --> pkg_client_ui_slots
   pkg_client_ui_plan --> pkg_invariants
   pkg_client_ui_plan --> pkg_plan_mode
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_locale
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_primitives
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_client_ui_tool
+  pkg_client_ui_skill --> pkg_invariants
   pkg_client_ui_subagent --> pkg_client_locale
   pkg_client_ui_subagent --> pkg_client_runtime
   pkg_client_ui_subagent --> pkg_client_ui_conversation
@@ -1310,7 +1317,7 @@ flowchart TD
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
-| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
@@ -1335,6 +1342,7 @@ flowchart TD
 | [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/ui/permission) |
 | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
 | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
 | [`sdk-protocol`](../packages/sdk/sdk-protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |

From 9c109253407eb1ff5e6e668f55b3c12061db912b Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:33:51 +0800
Subject: [PATCH 253/516] fix(docs): align ui-tool package contracts

---
 .../feature/2026-07-28-web-terminal-card.i18n.yaml          | 4 ++--
 .../implemented/feature/2026-07-28-web-terminal-card.md     | 6 +++---
 .../implemented/feature/2026-07-28-web-terminal-card.zh.md  | 6 +++---
 packages/client/ui-tool/README.i18n.yaml                    | 4 ++--
 packages/client/ui-tool/README.md                           | 2 +-
 packages/client/ui-tool/README.zh.md                        | 2 +-
 scripts/verify-package-readme-model-experience.ts           | 1 +
 7 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
index 0a7fb2b3ef..53dba67c61 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.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 .agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
-2026-07-28-web-terminal-card.md: 0493db4b86ce869ce5e699359e66dda70e526116
-2026-07-28-web-terminal-card.zh.md: 10137f83a25860a42e80a7b807a8aed68e86ce18
+2026-07-28-web-terminal-card.md: 026b32fed2c79533abfadc58314e2844ff556414
+2026-07-28-web-terminal-card.zh.md: 4c74d880c5795cf85f32391b27e6ffd2c5074870
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
index 0493db4b86..026b32fed2 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
@@ -8,11 +8,11 @@ English | [中文](2026-07-28-web-terminal-card.zh.md)
 
 The bash tool declares `card: 'terminal'` for both its call and its result ([render-intent union](../architecture/2026-07-02-tool-render-intent-union.md)): the call view carries the command, an optional model-authored description, and the working directory; the result view carries the output, exit code, and terminating signal. That view already reaches the browser — host, connection, and runtime deliver it onto `ConversationSnapshot` as `callView`/`resultView` — and the former TUI rendered it as a `$`-prompt card with an exit line and a head/tail height cap.
 
-The Web client ignored it. `packages/client/ui-conversation/src/client/contract/tool-call-model.ts` derived every row from raw tool args, and `skeleton/DetailsPanel.tsx` flattened every tool's content blocks into one `<pre>` with `white-space: pre-wrap; word-break: break-word`. Two defects followed from soft-wrapping and from having no height bound: multi-column output (`ls`, a table, box drawing) folded into a paragraph and lost the column alignment that is the whole point of that output, and a long single-column listing stretched the details panel to the length of the listing.
+The Web client ignored it. `packages/client/ui-tool/src/client/tool/models/tool-call-model.ts` derived every row from raw tool args, and `skeleton/DetailsPanel.tsx` flattened every tool's content blocks into one `<pre>` with `white-space: pre-wrap; word-break: break-word`. Two defects followed from soft-wrapping and from having no height bound: multi-column output (`ls`, a table, box drawing) folded into a paragraph and lost the column alignment that is the whole point of that output, and a long single-column listing stretched the details panel to the length of the listing.
 
 ## Decision
 
-`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `ui-tool/src/client/models/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs at this seam; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means.
+`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs at this seam; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means.
 
 The component's contract:
 
@@ -27,7 +27,7 @@ Geometry, radius, and fonts mirror `CodeBlock`, so a terminal card and a fenced
 
 ### Inline output in the chat row reverses a stated convention
 
-`chat/ToolRow.tsx` and `contract/tool-call-model.ts` asserted "no inline output ever — full results live in the details panel". Showing the terminal block in the row reverses that, on the owner's explicit decision.
+`packages/client/ui-tool/src/client/tool/components/ToolRow.tsx` and `packages/client/ui-tool/src/client/tool/models/tool-call-model.ts` asserted "no inline output ever — full results live in the details panel". Showing the terminal block in the row reverses that, on the owner's explicit decision.
 
 The reason the reversal holds: for a shell command the output *is* the result the user is reading, so routing it exclusively to a panel makes the common case a two-step interaction. A bounded, height-capped, non-wrapping terminal block in the row is what makes a bash-heavy transcript readable in one pass. The old rule's actual concern was a row whose height was unbounded by the length of the output, and the height cap plus expand control is what keeps that from returning.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index 10137f83a2..4c74d880c5 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -8,11 +8,11 @@ Status: implemented
 
 bash 工具的调用与结果都声明 `card: 'terminal'`（[渲染意图联合类型](../architecture/2026-07-02-tool-render-intent-union.md)）：调用视图携带命令、一段可选的模型撰写描述以及工作目录，结果视图携带输出、退出码与终止信号。该视图早已抵达浏览器——host、connection 与 runtime 把它投递到 `ConversationSnapshot` 的 `callView`/`resultView` 上——原 TUI 曾把它渲染为带 `$` 提示符的卡片，附退出行与首尾高度上限。
 
-Web client 却对它视而不见。`packages/client/ui-conversation/src/client/contract/tool-call-model.ts` 仅从原始工具参数推导每一行，`skeleton/DetailsPanel.tsx` 则把所有工具的内容块压平进一个 `<pre>`，样式为 `white-space: pre-wrap; word-break: break-word`。软换行加上没有高度约束，带来两个缺陷：多列输出（`ls`、表格、制表符绘图）被折成一段文字，丢掉了这类输出赖以存在的列对齐；而单列的长列表会把详情面板拉长到与列表等长。
+Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/models/tool-call-model.ts` 仅从原始工具参数推导每一行，`skeleton/DetailsPanel.tsx` 则把所有工具的内容块压平进一个 `<pre>`，样式为 `white-space: pre-wrap; word-break: break-word`。软换行加上没有高度约束，带来两个缺陷：多列输出（`ls`、表格、制表符绘图）被折成一段文字，丢掉了这类输出赖以存在的列对齐；而单列的长列表会把详情面板拉长到与列表等长。
 
 ## Decision
 
-`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`ui-tool/src/client/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
+`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
 
 该组件的契约：
 
@@ -27,7 +27,7 @@ Web client 却对它视而不见。`packages/client/ui-conversation/src/client/c
 
 ### 聊天行内嵌输出推翻了一条既有约定
 
-`chat/ToolRow.tsx` 与 `contract/tool-call-model.ts` 都断言过「绝不内嵌输出——完整结果在详情面板」。在行内显示终端块推翻了这一点，依据是 owner 的明确决定。
+`packages/client/ui-tool/src/client/tool/components/ToolRow.tsx` 与 `packages/client/ui-tool/src/client/tool/models/tool-call-model.ts` 都断言过「绝不内嵌输出——完整结果在详情面板」。在行内显示终端块推翻了这一点，依据是 owner 的明确决定。
 
 这次推翻成立的理由：对 shell 命令而言，输出**就是**用户要读的结果，把它专门收进面板会让最常见的情形变成两步交互。行内一个有界、限高、不换行的终端块，正是让 bash 密集的 transcript 一遍读完的条件。旧规则真正担心的是行高不受输出长度约束，而高度上限加展开控件正是防止其复现的机制。
 
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 828cfa25ef..eca4d1cb7b 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/client/ui-tool/README.md
-README.md: 381253f4eddaa57b89318dd23da3a049505fdd15
-README.zh.md: ae539131198771bc1d0e280bbfaa76ec0ec60792
+README.md: 69d6931d33788f2df593919d160c4bfeaef8d15c
+README.zh.md: eb49465a743711bd48358bf3953a485f9ef037eb
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index 381253f4ed..69d6931d33 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -32,7 +32,7 @@ This package currently owns the generic fallback and the built-in bash/pwsh, rea
 
 ## Model Experience
 
-None. This package renders already logged Tool calls and results and does not alter model requests, Tool execution, or session events.
+None, as this package renders already logged Tool calls and results without altering model requests, Tool execution, or session events.
 
 #### KV Cache effect
 
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index ae53913119..eb49465a74 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -32,7 +32,7 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ## 模型体验
 
-无。本包只渲染已经记录的 Tool 调用和结果，不改变模型请求、Tool 执行或 Session Event。
+无，因为本包只渲染已经记录的 Tool 调用和结果，不改变模型请求、Tool 执行或 Session Event。
 
 #### KV Cache 影响
 
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index ddbd7b66f8..3ca0317cf4 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -63,6 +63,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-conversation': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-tool': { kind: 'none', reason: 'Browser-side Tool presentation layer; renders logged calls without changing model context.' },
   'packages/client/ui-deliverables': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-slash': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-command': { kind: 'indirect', reason: 'The dispatch paths trigger the host command.execute RPC; each command handler\'s host package owns any model-visible effect.' },

From ab50037b93008ff2ac87b5c2df6ab8f6f632a9fa Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:59:13 +0800
Subject: [PATCH 254/516] fix(client): address tool presentation review

---
 .../2026-07-19-gui-web-client-architecture.i18n.yaml     | 4 ++--
 .../2026-07-19-gui-web-client-architecture.md            | 2 +-
 .../2026-07-19-gui-web-client-architecture.zh.md         | 2 +-
 ...26-08-08-client-tool-presentation-ownership.i18n.yaml | 4 ++--
 .../2026-08-08-client-tool-presentation-ownership.md     | 2 ++
 .../2026-08-08-client-tool-presentation-ownership.zh.md  | 2 ++
 .../feature/2026-07-30-web-diff-card.i18n.yaml           | 4 ++--
 .../implemented/feature/2026-07-30-web-diff-card.md      | 2 +-
 .../implemented/feature/2026-07-30-web-diff-card.zh.md   | 2 +-
 .../feature/2026-07-30-web-read-card-frontend.i18n.yaml  | 4 ++--
 .../feature/2026-07-30-web-read-card-frontend.md         | 2 +-
 .../feature/2026-07-30-web-read-card-frontend.zh.md      | 2 +-
 .../2026-07-30-web-result-card-frontend.i18n.yaml        | 4 ++--
 .../feature/2026-07-30-web-result-card-frontend.md       | 2 +-
 .../feature/2026-07-30-web-result-card-frontend.zh.md    | 2 +-
 .../feature/2026-07-30-web-search-card.i18n.yaml         | 4 ++--
 .../implemented/feature/2026-07-30-web-search-card.md    | 2 +-
 .../implemented/feature/2026-07-30-web-search-card.zh.md | 2 +-
 .../src/client/chat/AssistantMarkdown.tsx                | 2 +-
 .../src/client/chat/GenericCommandCard.tsx               | 2 ++
 .../ui-conversation/src/client/chat/ReasoningRow.tsx     | 6 +++++-
 .../src/client/chat/accessibility.module.css             | 8 ++++++++
 .../client/ui-conversation/src/client/contract/slots.ts  | 9 ++++++++-
 packages/client/ui-conversation/tests/chat-view.spec.tsx | 1 +
 .../client/ui-conversation/tests/reasoning-row.spec.tsx  | 2 ++
 packages/client/ui-tool/README.i18n.yaml                 | 4 ++--
 packages/client/ui-tool/README.md                        | 5 +++++
 packages/client/ui-tool/README.zh.md                     | 5 +++++
 packages/client/ui-tool/tests/ask-question-row.spec.tsx  | 2 +-
 packages/client/ui-tool/tests/coverage-tails.spec.tsx    | 2 +-
 packages/client/ui-tool/tests/diff-card.spec.tsx         | 6 +++---
 packages/client/ui-tool/tests/read-card.spec.tsx         | 6 +++---
 packages/client/ui-tool/tests/search-card.spec.tsx       | 6 +++---
 packages/client/ui-tool/tests/terminal-card.spec.tsx     | 6 +++---
 packages/client/ui-tool/tests/todo-row.spec.tsx          | 2 +-
 packages/client/ui-tool/tests/tool-call-tree.spec.tsx    | 2 +-
 packages/client/ui-tool/tests/tool-details-render.tsx    | 2 +-
 packages/client/ui-tool/tests/tool-row.spec.tsx          | 2 +-
 packages/client/ui-tool/tests/web-card.spec.tsx          | 6 +++---
 vitest.config.ts                                         | 1 +
 40 files changed, 87 insertions(+), 48 deletions(-)
 create mode 100644 packages/client/ui-conversation/src/client/chat/accessibility.module.css

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index 2dccd44aae..2357aa30f2 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: 4dc4558ea245baa17646f92b9b5e4c9a45b6a419
-2026-07-19-gui-web-client-architecture.zh.md: a306b5c82891840b96340f5464267cc9d861ef7e
+2026-07-19-gui-web-client-architecture.md: cba029ea74e89b277f9079ebb3765deeeb105b47
+2026-07-19-gui-web-client-architecture.zh.md: f700cc04fe1479d43957456c14b3abb4014d99c5
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index 4dc4558ea2..cba029ea74 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -44,7 +44,7 @@ Implementation homes: registry core and the props-share types in `packages/clien
 
 A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer install seam), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
-There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: ui-conversation places each ordered root call into the single `'conversation.chat.tool'` seat and passes the Runtime-projected Code Dispatch children without interpreting their Tool names; ui-tool renders that root/child shape and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and both roots and children dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
+There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: ui-conversation places each ordered root call into the single `'conversation.chat.tool'` seat without interpreting Tool names or Code Dispatch topology; ui-tool selects `codeDispatches[rootCallId]` from the Runtime snapshot, renders that root/child shape, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and both roots and children dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
 
 **Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport).
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index a306b5c828..f700cc04fe 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -44,7 +44,7 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-
 
 服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：ui-conversation 把每个已排序 root call 放进 single `'conversation.chat.tool'` seat，并透传 Runtime 已投影的 Code Dispatch child，不解释其 Tool 名称；ui-tool 渲染该 root/child 形状，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与 child 都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
+slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：ui-conversation 把每个已排序 root call 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或 Code Dispatch 拓扑；ui-tool 从 Runtime snapshot 选择 `codeDispatches[rootCallId]`、渲染 root/child 形状，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与 child 都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
 
 **scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index 47adf75d40..5097b9e8a9 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.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 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
-2026-08-08-client-tool-presentation-ownership.md: 4d06450a10c4198f20d7139aef815def9e7cb362
-2026-08-08-client-tool-presentation-ownership.zh.md: 3d3bf3bc3204aca6871a82c7b7ae330b6381a3e4
+2026-08-08-client-tool-presentation-ownership.md: e61c2030457cc9f0fda214e896b76afb37d0d2bc
+2026-08-08-client-tool-presentation-ownership.zh.md: 5c56b8c17ef5ca6695f3b28f6b93218dade356c7
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
index 4d06450a10..e61c203045 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
@@ -66,6 +66,8 @@ A slot declaration also constrains render ownership. The conversation chat entry
 
 The whole seat's `ToolTreeOwnerProps` carries the root `callId`, `toolName`, `ToolCallBlock`, `selectedCallId`, session `cwd`, `openFile(path)`, and `inspectCall(callId)`. `ToolCallTree` converts either a root or child into the same `ToolCallOwnerProps` and narrows inspect to a callback for that call. The atomic owner carries no `ReactNode`, Cordis `Context`, Session service, or projector; a business view consumes only one standard call block and host actions.
 
+The seat filler also preserves the conversation DOM contract on every root and child wrapper: `data-chat-anchor-key="call:<callId>"`, `data-chat-call-id`, and `data-selected="true"` on the selected call. `ChatView` consumes the anchor key to restore prepend/paging position; the Tool owner emits it because it alone composes child wrappers.
+
 Business plugins use one registration shape:
 
 ```text
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index 3d3bf3bc32..5c56b8c17e 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -66,6 +66,8 @@ slot 声明同时限定渲染所有权。conversation chat entry 通过 `childre
 
 整体席位的 `ToolTreeOwnerProps` 携带 root `callId`、`toolName`、`ToolCallBlock`、`selectedCallId`、session `cwd`、`openFile(path)` 与 `inspectCall(callId)`。`ToolCallTree` 把 root 或 child 转成相同的 `ToolCallOwnerProps`，并把 inspect 收窄成当前 call 的回调。原子 owner 不携带 `ReactNode`、Cordis `Context`、Session service 或 projector；业务 view 只消费一个标准调用块和宿主动作。
 
+席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 契约：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
+
 业务插件遵循同一个注册形态：
 
 ```text
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index ef2b3e55a0..d78733bb33 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.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 .agents/notes/implemented/feature/2026-07-30-web-diff-card.md
-2026-07-30-web-diff-card.md: c8aed2aa59d82520a2a52523edb9b66d0bb34bf0
-2026-07-30-web-diff-card.zh.md: c2127844165e5f5c162eb3707fa5c86aa3a536c0
+2026-07-30-web-diff-card.md: b078da8d0e688d705683599467bd98b5c6a0be48
+2026-07-30-web-diff-card.zh.md: a9c710df99c1060bbf50b591b2f62120dc7dcbef
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
index c8aed2aa59..b078da8d0e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
@@ -14,7 +14,7 @@ This is the [terminal card](2026-07-28-web-terminal-card.md) done for the `diff`
 
 ## Decision
 
-`DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-tool/src/client/models/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change.
+`DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-tool/src/client/tool/models/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change.
 
 The component shares the TUI's single-column framing, line-terminator rule, and distinct-path file count. Line classification differs: Web renders the complete old and new sides, while the TUI derives neutral context and exact changed rows when its bounded comparison completes and labels its whole-side fallback approximate.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index c212784416..a9c710df99 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -14,7 +14,7 @@ Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行
 
 ## Decision
 
-`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-tool/src/client/models/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
+`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-tool/src/client/tool/models/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
 
 该组件与 TUI 共用单栏框架、行终止符规则和去重路径计数。两者的行分类不同：Web 渲染完整的变更前后两侧，而 TUI 会在有界比较完成时派生中性上下文和精确变更行，并把整侧回退标记为近似结果。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
index 71ea2aabaf..3415ace63b 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.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 .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
-2026-07-30-web-read-card-frontend.md: 10ed9d3eaa54c2440cf3fbd00a7e44b76c1acfe9
-2026-07-30-web-read-card-frontend.zh.md: 931316135470b7e7257f7f9d016b24fe741fdbf5
+2026-07-30-web-read-card-frontend.md: e659645066b706f35709fead4c11023eb4fe9554
+2026-07-30-web-read-card-frontend.zh.md: 4fc02e23b45399c01b5c99d388f5ae1726b026c0
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
index 10ed9d3eaa..e659645066 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
@@ -10,7 +10,7 @@ The [read backend](2026-07-30-web-read-card.md) added a fourth render-intent car
 
 ## Decision
 
-`ReadBlock` is a `ui-primitives` component that renders a read result as a line-numbered, optionally syntax-highlighted file view, and both Web render sites for a read consume the read render intent through it: the chat tool row (resident under the summary line) and the details panel's Output section. `ui-tool/src/client/models/read-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so the two sites cannot disagree.
+`ReadBlock` is a `ui-primitives` component that renders a read result as a line-numbered, optionally syntax-highlighted file view, and both Web render sites for a read consume the read render intent through it: the chat tool row (resident under the summary line) and the details panel's Output section. `ui-tool/src/client/tool/models/read-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so the two sites cannot disagree.
 
 **A new `ReadBlock` primitive, not an extension of `CodeBlock`.** `CodeBlock` already does shiki highlighting with a language banner and a copy control, but a read view needs a per-line gutter carrying each line's own file number, which `CodeBlock` renders as a single `<pre>` tree with no per-line structure. Extending `CodeBlock` with an optional gutter would push a read-specific concern (windowed line numbers, a "showing N of M" note, a height cap) onto every markdown fence and every `run_code` body that shares that component. Instead `ReadBlock` reuses the part that is genuinely shared: the shiki grammar singleton in `markdown/highlight.ts`. A new `highlightLines(code, lang)` there tokenizes into shiki's own per-line token arrays (`codeToTokens`) rather than the single-`<pre>` HTML `highlightToHtml` produces, so the block can place one gutter number per line and still color the content through the same `--shiki-*` custom properties on the same grammar allowlist. The height cap and its head/tail expand arithmetic are copied from `TerminalBlock` (`ceil(max/2)` head plus the remaining tail), so a long read and a long command output collapse at the same place. The copy control writes the window's raw text (the lines joined by newlines), never the gutter numbers or the banner.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
index 9313161354..4fc02e23b4 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-`ReadBlock` 是一个 `ui-primitives` 组件，把一次读取结果渲染成带行号、可选语法高亮的文件视图，读取的两个 Web 渲染点都通过它消费读取渲染意图：聊天工具行（常驻在摘要行之下）与详情面板的 Output 区段。`ui-tool/src/client/models/read-card-model.ts` 是把快照的 `resultView` 转成组件 props 的唯一位置，因此两个渲染点不会产生分歧。
+`ReadBlock` 是一个 `ui-primitives` 组件，把一次读取结果渲染成带行号、可选语法高亮的文件视图，读取的两个 Web 渲染点都通过它消费读取渲染意图：聊天工具行（常驻在摘要行之下）与详情面板的 Output 区段。`ui-tool/src/client/tool/models/read-card-model.ts` 是把快照的 `resultView` 转成组件 props 的唯一位置，因此两个渲染点不会产生分歧。
 
 **新建一个 `ReadBlock` primitive，而不是扩展 `CodeBlock`。** `CodeBlock` 已经带语言横幅和复制控件做 shiki 高亮，但读取视图需要一个每行带该行自身文件行号的行号栏，而 `CodeBlock` 把内容渲染为单个 `<pre>` 树、没有逐行结构。给 `CodeBlock` 加一个可选行号栏会把读取专属的关切（窗口行号、"显示 N / M"提示、高度上限）强加给共享该组件的每个 markdown 代码围栏和每个 `run_code` 程序体。`ReadBlock` 转而复用真正共享的部分：`markdown/highlight.ts` 里的 shiki 语法单例。那里新增的 `highlightLines(code, lang)` 把代码切成 shiki 自己的逐行 token 数组（`codeToTokens`），而不是 `highlightToHtml` 产出的单 `<pre>` HTML，于是该 block 能每行放一个行号、同时用同一套 `--shiki-*` 自定义属性、同一份语法白名单给内容上色。高度上限及其头/尾展开算法照抄自 `TerminalBlock`（`ceil(max/2)` 行头部加剩余的尾部），因此长读取和长命令输出在同一处折叠。复制控件写入窗口的原始文本（各行以换行拼接），绝不含行号栏或横幅。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index ded72420fc..6f3a5d895b 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.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 .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
-2026-07-30-web-result-card-frontend.md: 1d58710dbce3ed1aa9337e1841940195f71db40a
-2026-07-30-web-result-card-frontend.zh.md: 8705aa05557c1fdf642f498939bc2ceddde91f1f
+2026-07-30-web-result-card-frontend.md: c7e63220d824cf0bd3ac3536c528707d0db379bc
+2026-07-30-web-result-card-frontend.zh.md: 4cec11371e8d0848f2f03ded0b093d80cc25a7a5
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
index 1d58710dbc..c7e63220d8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
@@ -10,7 +10,7 @@ The `web_search` and `web_fetch` tools declare a `card: 'web'` result view ([web
 
 ## Decision
 
-`WebBlock` is a `ui-primitives` component that renders a completed web retrieval, and every Web render site for a web call consumes the `web` render intent through it: the keyed chat tool rows (`web_search`/`web_fetch`), the `GenericToolCard` render-site fallback, and the details panel's Output section. `ui-tool/src/client/models/web-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, mirroring `terminal-card-model.ts`, so no two sites disagree about what a web call shows. It returns null — the generic path — for a running call (the web card is result-only, since the tools keep a generic pending view), for a settled call whose result view is not a web card including a `card` value this client version does not know (which arrives over the wire and so cannot be trusted to be a compiled variant), for a generic result view (a web tool's error path returns the generic card, whose text the generic path preserves), and for a web card whose `kind` this client version does not know (a newer host's value off the wire, which reading as a fetch would draw as an empty URL and `HTTP undefined`).
+`WebBlock` is a `ui-primitives` component that renders a completed web retrieval, and every Web render site for a web call consumes the `web` render intent through it: the keyed chat tool rows (`web_search`/`web_fetch`), the `GenericToolCard` render-site fallback, and the details panel's Output section. `ui-tool/src/client/tool/models/web-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, mirroring `terminal-card-model.ts`, so no two sites disagree about what a web call shows. It returns null — the generic path — for a running call (the web card is result-only, since the tools keep a generic pending view), for a settled call whose result view is not a web card including a `card` value this client version does not know (which arrives over the wire and so cannot be trusted to be a compiled variant), for a generic result view (a web tool's error path returns the generic card, whose text the generic path preserves), and for a web card whose `kind` this client version does not know (a newer host's value off the wire, which reading as a fetch would draw as an empty URL and `HTTP undefined`).
 
 One component draws both kinds, discriminated by `kind`. A `search` shows the answer as markdown above a citation list; each source is a safe external link labelled by its title, or its hostname when the provider gave none, with the snippet and publication date below it, and a `来源列表已截断` indicator when the tool capped the list. A `fetch` shows a compact summary: the linked final URL, its HTTP status, and a `内容已截断` indicator. One component rather than two because both are web retrieval rendered as one card family, which is exactly the reason the contract carries them under one `card` tag with a `kind` discriminant.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index 8705aa0555..4cec11371e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
+`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/tool/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
 
 一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是契约把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
index 1578f0c73e..0cfb6b01bd 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.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 .agents/notes/implemented/feature/2026-07-30-web-search-card.md
-2026-07-30-web-search-card.md: a350756a22d2ba5da8a0ff5d3a4cb3f257ac566b
-2026-07-30-web-search-card.zh.md: d6ec2a08eb02a92a50d4742c3d87c22f42c095d4
+2026-07-30-web-search-card.md: e0be857df69dfd46b6e936c775c6bae1476c26dc
+2026-07-30-web-search-card.zh.md: 1704b8f04c519511d5afa32ae6683c1e48ce7992
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
index a350756a22..e0be857df6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
@@ -12,7 +12,7 @@ This is the follow-up the search render card note names: that PR was the backend
 
 ## Decision
 
-`SearchBlock` is a `ui-primitives` component that renders a completed search as either shape, and the Web render sites for a `grep`/`glob` call consume the search render intent through it. `ui-tool/src/client/models/search-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so no render site re-derives the shape. It returns null — the generic path — whenever the result view is not a search card, including a still-running call (a search card is result-time only, so there is nothing before `execute`), a generic result a `grep`/`glob` failure or a nested `run_code` dispatch produces, a terminal result view, a `card` value this client version does not know, a `card: 'search'` view whose `shape` this version does not compile, and — because `shape` and the grouped/flat contents ride the same untrusted wire frame the host schema only string-checks — a known `shape` whose `files`/`paths` is missing or malformed (which would otherwise crash `SearchBlock` at `.reduce`/`.map`). The result-view discriminant is `shape` (not `kind`, which the backend reserves for the call view's icon-picking tag); `SearchBlock`'s own prop stays `kind`, mapped from `shape` in this derivation.
+`SearchBlock` is a `ui-primitives` component that renders a completed search as either shape, and the Web render sites for a `grep`/`glob` call consume the search render intent through it. `ui-tool/src/client/tool/models/search-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so no render site re-derives the shape. It returns null — the generic path — whenever the result view is not a search card, including a still-running call (a search card is result-time only, so there is nothing before `execute`), a generic result a `grep`/`glob` failure or a nested `run_code` dispatch produces, a terminal result view, a `card` value this client version does not know, a `card: 'search'` view whose `shape` this version does not compile, and — because `shape` and the grouped/flat contents ride the same untrusted wire frame the host schema only string-checks — a known `shape` whose `files`/`paths` is missing or malformed (which would otherwise crash `SearchBlock` at `.reduce`/`.map`). The result-view discriminant is `shape` (not `kind`, which the backend reserves for the call view's icon-picking tag); `SearchBlock`'s own prop stays `kind`, mapped from `shape` in this derivation.
 
 The asymmetry with the terminal card is deliberate and inherited from the backend contract: `terminalCardModel` reads both `callView` and `resultView` because a command, cwd, and description exist at call time; `searchCardModel` reads only `resultView` because a search's matches or paths exist only after execution. A running search row therefore shows its summary alone, with no card.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
index d6ec2a08eb..1704b8f04c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## Decision
 
-`SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-tool/src/client/models/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
+`SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-tool/src/client/tool/models/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
 
 与终端卡片的不对称是刻意的，继承自后端契约：`terminalCardModel` 同时读 `callView` 和 `resultView`，因为命令、cwd、description 在调用时就存在；`searchCardModel` 只读 `resultView`，因为搜索的匹配或路径只在执行后存在。因此运行中的搜索行只显示摘要，没有卡片。
 
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index 9d0c26506e..bbd4caa2c3 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -81,7 +81,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
             case 'text': return (
               <MarkdownText key={i} text={block.text} streaming={streaming} codeLabels={codeLabels} />
             )
-            case 'reasoning': return <ReasoningRow key={i} text={block.text} running={streaming && i === last} />
+            case 'reasoning': return <ReasoningRow key={i} text={block.text} running={streaming && i === last} t={t} />
             // Grouped into tool rows by ChatView; hasVisible above skips an empty shell.
             case 'tool-call': return null
             default: return (
diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index b16d838e77..d487123558 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -7,6 +7,7 @@
 import { useState, type ReactNode } from 'react'
 import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
 import { DisclosureRow, IconApiOutline14, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
+import a11yCss from './accessibility.module.css'
 import css from './GenericCommandCard.module.css'
 
 type CommandRowState = 'running' | 'ok' | 'error'
@@ -42,6 +43,7 @@ export function GenericCommandCard({ node, t }: GenericCommandCardProps) {
   const open = expanded && body !== null
   return (
     <div className={css.root} data-state={state}>
+      {state === 'error' && <span className={a11yCss.visuallyHidden}>{t('row.failed')}</span>}
       <DisclosureRow
         rowClassName={css.row}
         leadingClassName={css.leading}
diff --git a/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx b/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
index d888451ff7..77e64a2106 100644
--- a/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
@@ -1,7 +1,9 @@
 /** Assistant reasoning disclosure, independent of Tool-call presentation. */
 import { useEffect, useRef, useState } from 'react'
 import { DisclosureRow, IconThinkOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ChatViewSlotProps } from '../contract/slots.ts'
 import { useThrottledVisualUpdate } from './use-throttled-visual-update.ts'
+import a11yCss from './accessibility.module.css'
 import css from './ReasoningRow.module.css'
 
 function firstLine(text: string): string {
@@ -19,9 +21,10 @@ function latestLine(text: string): string {
  * Render one assistant reasoning block as the Think disclosure row.
  * @param props.text - complete or streaming reasoning text.
  * @param props.running - whether this block is the streaming tail.
+ * @param props.t - conversation locale seat for the running status.
  * @returns the reasoning disclosure.
  */
-export function ReasoningRow({ text, running }: { text: string; running: boolean }) {
+export function ReasoningRow({ text, running, t }: { text: string; running: boolean; t: ChatViewSlotProps['t'] }) {
   const [expanded, setExpanded] = useState(false)
   const summaryRef = useRef<HTMLSpanElement>(null)
   const summary = running ? latestLine(text) : firstLine(text)
@@ -36,6 +39,7 @@ export function ReasoningRow({ text, running }: { text: string; running: boolean
 
   return (
     <div className={css.root} data-state={running ? 'running' : 'ok'}>
+      {running && <span className={a11yCss.visuallyHidden}>{t('row.running')}</span>}
       <DisclosureRow
         rowClassName={css.row}
         leadingClassName={css.leading}
diff --git a/packages/client/ui-conversation/src/client/chat/accessibility.module.css b/packages/client/ui-conversation/src/client/chat/accessibility.module.css
new file mode 100644
index 0000000000..cf2556157f
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/accessibility.module.css
@@ -0,0 +1,8 @@
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 2ef67f4aa8..47093ee77b 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -33,6 +33,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     /**
      * One root Tool call at its ordered ChatFlow position. The chat view owns
      * placement; ui-tool owns root/subcall composition and keyed dispatch.
+     * The filler preserves the call-anchor DOM contract documented by
+     * {@link ToolTreeOwnerProps} for every root and child wrapper.
      */
     'conversation.chat.tool': { kind: 'single'; scope: 'session'; owner: ToolTreeOwnerProps }
     /**
@@ -176,7 +178,12 @@ export interface TurnTailOwnerProps {
   openFile: (path: string) => void
 }
 
-/** Owner currency of the chat view's whole-Tool rendering seat. */
+/**
+ * Owner currency of the chat view's whole-Tool rendering seat. The filler
+ * wraps every rendered root and child with `data-chat-anchor-key="call:<id>"`
+ * and `data-chat-call-id="<id>"`, plus `data-selected="true"` for the selected
+ * call. ChatView consumes those anchors to restore prepend/paging position.
+ */
 export interface ToolTreeOwnerProps {
   /** Root Tool call identity, stable across running → settled. */
   callId: CallId
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index 0a25e9b198..d2589122e8 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -1269,6 +1269,7 @@ describe('ChatView', () => {
     const fv = render(<failed.ChatView {...failed.props} />)
     expect(fv.container.querySelector('[data-state="error"]')).not.toBeNull()
     expect(fv.getByText('命令失败')).toBeTruthy()
+    expect(fv.getByText('失败')).toBeTruthy()
 
     // Still executing: running state with the executing copy.
     const executing = makeHarness({
diff --git a/packages/client/ui-conversation/tests/reasoning-row.spec.tsx b/packages/client/ui-conversation/tests/reasoning-row.spec.tsx
index 243b665ce2..62e6ac7848 100644
--- a/packages/client/ui-conversation/tests/reasoning-row.spec.tsx
+++ b/packages/client/ui-conversation/tests/reasoning-row.spec.tsx
@@ -47,6 +47,7 @@ describe('ReasoningRow', () => {
         streaming
       />,
     )
+    expect(view.getByText('运行中')).toBeTruthy()
     const summary = view.getByText('Newest reasoning tokens')
     Object.defineProperties(summary, {
       scrollWidth: { configurable: true, value: 300 },
@@ -76,6 +77,7 @@ describe('ReasoningRow', () => {
     )
     flushAnimationFrames(3)
     expect(view.getByText('Inspect the session')).toBeTruthy()
+    expect(view.queryByText('运行中')).toBeNull()
     expect(summary.scrollLeft).toBe(0)
     expect(summary.hasAttribute('data-follow-end')).toBe(false)
   })
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index eca4d1cb7b..79a4eef640 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/client/ui-tool/README.md
-README.md: 69d6931d33788f2df593919d160c4bfeaef8d15c
-README.zh.md: eb49465a743711bd48358bf3953a485f9ef037eb
+README.md: bf6213ebfacd8f7963463b2c443524c631c28bcd
+README.zh.md: 06a46a525eead005375bcf67794a1ceecde678bc
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index 69d6931d33..bf6213ebfa 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -10,6 +10,8 @@ Business UI packages register only their wire Tool names and atomic views. They
 
 `ToolCallTree` receives one root `ToolCallBlock`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. Through its standard session slot props it selects the Runtime-projected `codeDispatches[rootCallId]` array, then sends the root and every child through the same atomic dispatch path. The Runtime currently exposes only one Code Dispatch child level, so the renderer preserves that shape instead of inventing recursive data.
 
+Each root and child wrapper preserves the `conversation.chat.tool` call-anchor DOM contract used for paging and selection.
+
 The package also fills `conversation.details.tool` with `ToolDetails`. The row and details renderers share the same pure card models for `terminal`, `read`, `diff`, `search`, and `web` render intents. Unknown intent tags and malformed wire card data fall back to flattened Tool result text.
 
 Generic rows classify known Tool names into search, read, shell, write, edit, code, or generic variants. Running, successful, failed, and interrupted lifecycle states come only from the frozen call/result slice. File paths resolve against the session `cwd` only when the user invokes the Host open-file callback; presentation code does not read Session services.
@@ -30,6 +32,8 @@ The owner payload is `ToolCallOwnerProps`: `callId`, `toolName`, the frozen `blo
 
 This package currently owns the generic fallback and the built-in bash/pwsh, read, write/edit, grep/glob, web, todo, question, and Code Dispatch presentations. `ui-skill` demonstrates a business-owned registration for `skill`.
 
+Card-specific limits and fallback rules remain in the owning [terminal](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md), [diff](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md), [read](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md), [search](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md), and [web](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) notes.
+
 ## Model Experience
 
 None, as this package renders already logged Tool calls and results without altering model requests, Tool execution, or session events.
@@ -42,3 +46,4 @@ None. The package is client-only presentation.
 
 - The Runtime currently exposes one level of Code Dispatch children. The renderer sends roots and children through the same atomic path, but it does not claim an arbitrary recursive wire topology.
 - Existing first-party Tool views are initially colocated here and can move to their owning business packages independently through the keyed slot.
+- Tool copy temporarily reuses the `ui-conversation` locale namespace.
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index eb49465a74..06a46a525e 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -10,6 +10,8 @@ Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交
 
 `ToolCallTree` 接收一个 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它通过标准 session slot props 选择 Runtime 投影的 `codeDispatches[rootCallId]` 数组，再让 root 与每个 child 经过同一条原子分发路径。Runtime 当前只暴露一层 Code Dispatch child，因此 renderer 保留该形状，不自行发明递归数据。
 
+每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 契约，供分页和 selection 使用。
+
 本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 为 `terminal`、`read`、`diff`、`search` 和 `web` render intent 共用同一组纯 card model。本版本不认识的 intent 标签和格式错误的 wire card 数据都会回退为压平的 Tool result 文本。
 
 通用行把已知 Tool 名称归类为 search、read、shell、write、edit、code 或 generic 变体。运行中、成功、失败和中断状态只来自冻结的 call/result slice。只有用户调用 Host 打开文件回调时，文件路径才相对会话 `cwd` 解析；展示代码不读取 Session service。
@@ -30,6 +32,8 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 本包当前拥有 generic fallback，以及 bash/pwsh、read、write/edit、grep/glob、web、todo、question 和 Code Dispatch 的内置展示。`ui-skill` 展示了业务包如何拥有 `skill` 注册。
 
+各类卡片的上限与 fallback 规则仍由对应的 [terminal](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)、[diff](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)、[read](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)、[search](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md) 和 [web](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) Note 负责。
+
 ## 模型体验
 
 无，因为本包只渲染已经记录的 Tool 调用和结果，不改变模型请求、Tool 执行或 Session Event。
@@ -42,3 +46,4 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 - Runtime 当前只暴露一层 Code Dispatch 子调用。renderer 会让 root 和 child 经过同一个原子分发路径，但不宣称 wire 拓扑已经支持任意递归。
 - 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
+- Tool 文案暂时复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-tool/tests/ask-question-row.spec.tsx b/packages/client/ui-tool/tests/ask-question-row.spec.tsx
index 745bc2ff90..f3ab8fd3fd 100644
--- a/packages/client/ui-tool/tests/ask-question-row.spec.tsx
+++ b/packages/client/ui-tool/tests/ask-question-row.spec.tsx
@@ -14,7 +14,7 @@ import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 // Export discipline: packages/client/AGENTS.md.
 import { AskQuestionRow, askQuestionToolview } from '../src/client/tool/toolviews/ask-question-row.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
diff --git a/packages/client/ui-tool/tests/coverage-tails.spec.tsx b/packages/client/ui-tool/tests/coverage-tails.spec.tsx
index 720fa23255..024f97ce76 100644
--- a/packages/client/ui-tool/tests/coverage-tails.spec.tsx
+++ b/packages/client/ui-tool/tests/coverage-tails.spec.tsx
@@ -11,7 +11,7 @@ import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { ToolRow } from '../src/client/tool/components/ToolRow.tsx'
 import { BashRow } from '../src/client/tool/toolviews/bash-sample.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 type BashRowProps = Parameters<typeof BashRow>[0]
 
diff --git a/packages/client/ui-tool/tests/diff-card.spec.tsx b/packages/client/ui-tool/tests/diff-card.spec.tsx
index 0fe95c9564..a0dee040c1 100644
--- a/packages/client/ui-tool/tests/diff-card.spec.tsx
+++ b/packages/client/ui-tool/tests/diff-card.spec.tsx
@@ -16,12 +16,12 @@ import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/cl
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../src/client/tool/models/diff-card-model.ts'
-import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { FileMutationRow, fileMutationToolview } from '../src/client/tool/toolviews/file-mutation-row.tsx'
 import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
diff --git a/packages/client/ui-tool/tests/read-card.spec.tsx b/packages/client/ui-tool/tests/read-card.spec.tsx
index 8b528355a5..826bd72892 100644
--- a/packages/client/ui-tool/tests/read-card.spec.tsx
+++ b/packages/client/ui-tool/tests/read-card.spec.tsx
@@ -19,10 +19,10 @@ import type {
 import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
 import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { CHAT_READ_MAX_LINES, readCardModel } from '../src/client/tool/models/read-card-model.ts'
-import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
-import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
+import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { ReadRow, readToolview } from '../src/client/tool/toolviews/read-row.tsx'
 import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
 
diff --git a/packages/client/ui-tool/tests/search-card.spec.tsx b/packages/client/ui-tool/tests/search-card.spec.tsx
index 02d3eab476..72e25ac32b 100644
--- a/packages/client/ui-tool/tests/search-card.spec.tsx
+++ b/packages/client/ui-tool/tests/search-card.spec.tsx
@@ -18,10 +18,10 @@ import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/cl
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { CHAT_SEARCH_MAX_LINES, searchCardModel } from '../src/client/tool/models/search-card-model.ts'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
-import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
+import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { SearchRow, searchToolview } from '../src/client/tool/toolviews/search-row.tsx'
 import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
 
diff --git a/packages/client/ui-tool/tests/terminal-card.spec.tsx b/packages/client/ui-tool/tests/terminal-card.spec.tsx
index 34c5744c01..93a538c5c0 100644
--- a/packages/client/ui-tool/tests/terminal-card.spec.tsx
+++ b/packages/client/ui-tool/tests/terminal-card.spec.tsx
@@ -16,12 +16,12 @@ import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/cl
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { terminalCardModel, terminalFailed } from '../src/client/tool/models/terminal-card-model.ts'
-import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { BashRow } from '../src/client/tool/toolviews/bash-sample.tsx'
 import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 type BashRowProps = Parameters<typeof BashRow>[0]
 
diff --git a/packages/client/ui-tool/tests/todo-row.spec.tsx b/packages/client/ui-tool/tests/todo-row.spec.tsx
index 326821fc4e..ef3253a947 100644
--- a/packages/client/ui-tool/tests/todo-row.spec.tsx
+++ b/packages/client/ui-tool/tests/todo-row.spec.tsx
@@ -8,7 +8,7 @@ import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts
 import { TodoRow, todoToolview } from '../src/client/tool/toolviews/todo-row.tsx'
 import { planSummary } from '../src/client/tool/toolviews/plan-summary.ts'
 import { CONVERSATION_NS as NS } from '../src/client/locale.ts'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 type TodoRowProps = Parameters<typeof TodoRow>[0]
 
diff --git a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
index 76b24bc7ac..0720ba5642 100644
--- a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
@@ -7,7 +7,7 @@ import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import type { ToolTreeProps } from '../src/client/contract/slots.ts'
 import { ToolCallTree } from '../src/client/tool/ToolCallTree.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
diff --git a/packages/client/ui-tool/tests/tool-details-render.tsx b/packages/client/ui-tool/tests/tool-details-render.tsx
index e61cd0aaa7..0aeb3c5321 100644
--- a/packages/client/ui-tool/tests/tool-details-render.tsx
+++ b/packages/client/ui-tool/tests/tool-details-render.tsx
@@ -1,7 +1,7 @@
 /** Test adapter for the production conversation.details.tool registration. */
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionProviderComponent, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
-import type { DetailsSlotProps, DetailsToolOwnerProps } from '../../ui-conversation/src/client/contract/slots.ts'
+import type { DetailsSlotProps, DetailsToolOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/src/client/contract/slots.ts'
 import { ToolDetails } from '../src/client/tool/ToolDetails.tsx'
 
 /** Framework session-area seat used by direct DetailsPanel tests. */
diff --git a/packages/client/ui-tool/tests/tool-row.spec.tsx b/packages/client/ui-tool/tests/tool-row.spec.tsx
index f53bcb11f7..02189e3634 100644
--- a/packages/client/ui-tool/tests/tool-row.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.spec.tsx
@@ -9,7 +9,7 @@ import { resolveWorkspacePath } from '@deepseek-ai/dsh-client-runtime/client'
 import { classifyTool, resultText, toolRowModel } from '../src/client/tool/models/tool-call-model.ts'
 import { ToolRow } from '../src/client/tool/components/ToolRow.tsx'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(() => {
   cleanup()
diff --git a/packages/client/ui-tool/tests/web-card.spec.tsx b/packages/client/ui-tool/tests/web-card.spec.tsx
index 743b450ca7..b8a5a4e06c 100644
--- a/packages/client/ui-tool/tests/web-card.spec.tsx
+++ b/packages/client/ui-tool/tests/web-card.spec.tsx
@@ -19,14 +19,14 @@ import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import type { SelectionTarget } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { ToolCallOwnerProps } from '@deepseek-ai/dsh-client-ui-tool/client'
 import { webCardModel } from '../src/client/tool/models/web-card-model.ts'
-import { createChatStore } from '../../ui-conversation/src/client/stores.ts'
+import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { GenericToolCard } from '../src/client/tool/toolviews/GenericToolCard.tsx'
-import { DetailsPanel } from '../../ui-conversation/src/client/skeleton/DetailsPanel.tsx'
+import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { WebRow, webToolview } from '../src/client/tool/toolviews/web-row.tsx'
 import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
-import { zh } from '../../ui-conversation/src/client/locales.ts'
+import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
 
diff --git a/vitest.config.ts b/vitest.config.ts
index 597bca5618..6eb1bda354 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -162,6 +162,7 @@ export default defineConfig({
         'packages/client/web-react/src/*',
         'packages/client/runtime/src/*',
         'packages/client/ui-conversation/src/*',
+        'packages/client/ui-primitives/src/DisclosureRow.tsx',
         'packages/client/ui-tool/src/*',
         'packages/client/ui-slots/src/*',
         'packages/client/ui-layout/src/*',

From 810bfc4b5e2287349256cc9a35a170b4351a9f35 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 16:27:09 +0800
Subject: [PATCH 255/516] fix: ci

---
 .../ui-conversation/src/client/chat/GenericCommandCard.tsx      | 2 +-
 .../client/ui-conversation/src/client/chat/ReasoningRow.tsx     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index d487123558..9d34ef3015 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -42,7 +42,7 @@ export function GenericCommandCard({ node, t }: GenericCommandCardProps) {
   const body = text !== undefined && text.includes('\n') ? text : null
   const open = expanded && body !== null
   return (
-    <div className={css.root} data-state={state}>
+    <div className={css.root} data-variant="others" data-state={state}>
       {state === 'error' && <span className={a11yCss.visuallyHidden}>{t('row.failed')}</span>}
       <DisclosureRow
         rowClassName={css.row}
diff --git a/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx b/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
index 77e64a2106..f8a340d20c 100644
--- a/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ReasoningRow.tsx
@@ -38,7 +38,7 @@ export function ReasoningRow({ text, running, t }: { text: string; running: bool
   }, [running, scheduleSummaryScroll, summary])
 
   return (
-    <div className={css.root} data-state={running ? 'running' : 'ok'}>
+    <div className={css.root} data-variant="think" data-state={running ? 'running' : 'ok'}>
       {running && <span className={a11yCss.visuallyHidden}>{t('row.running')}</span>}
       <DisclosureRow
         rowClassName={css.row}

From c5b37f6845a753509640c857443c5ad95a5794b0 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 16:43:29 +0800
Subject: [PATCH 256/516] fix(client): keep compact row in conversation package

---
 .../src/client/chat/CompactionCommandCard.tsx      | 14 +-------------
 .../src/client/chat/GenericCommandCard.tsx         |  6 ++++--
 2 files changed, 5 insertions(+), 15 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
index 8012834541..c2f0191d85 100644
--- a/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
@@ -3,11 +3,9 @@
 // generic command card so no-history, cancellation, and failures retain their
 // complete handler-authored text.
 
-import { IconApiOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
 import { CompactionItem } from './CompactionItem.tsx'
 import { GenericCommandCard } from './GenericCommandCard.tsx'
-import { ToolRow } from './ToolRow.tsx'
 
 interface CompactionCommandCardProps extends CommandRowOwnerProps {
   t: ChatViewSlotProps['t']
@@ -26,15 +24,5 @@ export function CompactionCommandCard({ node, compaction, t }: CompactionCommand
     )
   }
   if (node.outcome !== null) return <GenericCommandCard node={node} t={t} />
-  return (
-    <ToolRow
-      t={t}
-      variant="others"
-      icon={<IconApiOutline14 size={14} />}
-      title="compact"
-      summary={t('message.compaction.running')}
-      body={null}
-      state="running"
-    />
-  )
+  return <GenericCommandCard node={node} t={t} runningSummary={t('message.compaction.running')} />
 }
diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index 9d34ef3015..9137181265 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -25,13 +25,15 @@ function leadingFor(state: CommandRowState): ReactNode {
 /** Card props: the owner payload plus the render site's locale seat (plain prop). */
 export interface GenericCommandCardProps extends CommandRowOwnerProps {
   t: ChatViewSlotProps['t']
+  /** Command-specific running copy; absent uses the generic command label. */
+  runningSummary?: string | undefined
 }
 
-export function GenericCommandCard({ node, t }: GenericCommandCardProps) {
+export function GenericCommandCard({ node, t, runningSummary }: GenericCommandCardProps) {
   const [expanded, setExpanded] = useState(false)
   const text = node.outcome?.text
   const summary = node.outcome === null
-    ? t('command.running')
+    ? runningSummary ?? t('command.running')
     : text ?? (node.outcome.kind === 'error' ? t('command.failed') : t('command.done'))
   // Title is the bare command name: the row already reads `name · outcome`,
   // and the dispatched line's own `/` and arguments only restate what the

From 3b31b2eba19c702ecd455ebc22ea8741c03ef2af Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 16:50:30 +0800
Subject: [PATCH 257/516] fix: ci

---
 packages/client/ui-conversation/README.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 2a396a8404..24e7e70f27 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: c4c7a0363c0a2760cf478744073eab96d837b719
-README.zh.md: a34f99f7e4e50750b2ecf024ed9e898c8de09529
+README.md: 837edaa097d47ebfb72d027616a18fdfeed8a488
+README.zh.md: 419799666dc0689f8fe754d4c9de6d5dcf7fb09c

From 871c59c3bcfd0f76e671f9eba4ca1a49451db272 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:12:54 +0800
Subject: [PATCH 258/516] fix(client): address tool tree review

---
 .../src/client/chat/GenericCommandCard.tsx    |  1 +
 .../ui-conversation/tests/chat-view.spec.tsx  |  1 +
 .../ui-tool/src/client/tool/ToolCallTree.tsx  | 31 ++++++++++---------
 .../ui-tool/tests/tool-call-tree.spec.tsx     |  2 ++
 4 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index 9137181265..676e433fa5 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -45,6 +45,7 @@ export function GenericCommandCard({ node, t, runningSummary }: GenericCommandCa
   const open = expanded && body !== null
   return (
     <div className={css.root} data-variant="others" data-state={state}>
+      {state === 'running' && <span className={a11yCss.visuallyHidden}>{t('row.running')}</span>}
       {state === 'error' && <span className={a11yCss.visuallyHidden}>{t('row.failed')}</span>}
       <DisclosureRow
         rowClassName={css.row}
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index d2589122e8..c828eeaeb8 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -1278,6 +1278,7 @@ describe('ChatView', () => {
     const xv = render(<executing.ChatView {...executing.props} />)
     expect(xv.container.querySelector('[data-state="running"]')).not.toBeNull()
     expect(xv.getByText('执行中…')).toBeTruthy()
+    expect(xv.getByText('运行中')).toBeTruthy()
 
     // Cross-window soft-fall (run page truncated): generic title, outcome preserved.
     const orphan = makeHarness({
diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
index 8091f26dff..3c71e2f4d4 100644
--- a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
+++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
@@ -1,5 +1,5 @@
 /** Root/subcall Tool composition with one keyed atomic dispatch path. */
-import { memo, useMemo } from 'react'
+import { memo, useMemo, type ReactNode } from 'react'
 import type { CodeSubCall, ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ToolCallOwnerProps, ToolTreeProps } from '../contract/slots.ts'
 import { GenericToolCard } from './toolviews/GenericToolCard.tsx'
@@ -12,12 +12,13 @@ function subCallName(node: CodeSubCall): string {
 
 /** One atomic call dispatched through the Tool-owned keyed slot. */
 const ToolCall = memo(function ToolCall({
-  renderSlot, callId, toolName, block, openFile, selected, cwd, inspectCall, t,
+  renderSlot, callId, toolName, block, openFile, selected, cwd, inspectCall, t, children,
 }: Pick<ToolTreeProps, 'renderSlot' | 'openFile' | 'cwd' | 'inspectCall' | 't'> & {
   callId: string
   toolName: string
   block: ToolCallBlock
   selected: boolean
+  children?: ReactNode
 }) {
   const owner: ToolCallOwnerProps = useMemo(() => ({
     callId,
@@ -38,6 +39,7 @@ const ToolCall = memo(function ToolCall({
         entryKey: toolName,
         fallback: <GenericToolCard {...owner} t={t} />,
       })}
+      {children}
     </div>
   )
 })
@@ -53,18 +55,17 @@ export function ToolCallTree({
 }: ToolTreeProps) {
   const subCalls = useSession(snapshot => snapshot.codeDispatches.get(callId))
   return (
-    <>
-      <ToolCall
-        renderSlot={renderSlot}
-        callId={callId}
-        toolName={toolName}
-        block={block}
-        openFile={openFile}
-        selected={callId === selectedCallId}
-        cwd={cwd}
-        inspectCall={inspectCall}
-        t={t}
-      />
+    <ToolCall
+      renderSlot={renderSlot}
+      callId={callId}
+      toolName={toolName}
+      block={block}
+      openFile={openFile}
+      selected={callId === selectedCallId}
+      cwd={cwd}
+      inspectCall={inspectCall}
+      t={t}
+    >
       {subCalls !== undefined && subCalls.length > 0 ? (
         <div className={css.subCalls} data-subcalls>
           {subCalls.map(node => (
@@ -83,6 +84,6 @@ export function ToolCallTree({
           ))}
         </div>
       ) : null}
-    </>
+    </ToolCall>
   )
 }
diff --git a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
index 0720ba5642..c8c31ad365 100644
--- a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
@@ -57,6 +57,8 @@ describe('ToolCallTree', () => {
     const view = render(
       <ToolCallTree {...props(block, new Map([['parent', [child]]]), child.callId)} />,
     )
+    expect(view.container.querySelector('[data-subcalls]')?.parentElement)
+      .toBe(view.container.querySelector('[data-chat-call-id="parent"]'))
     expect(view.container.querySelector('[data-chat-call-id="parent"]')?.hasAttribute('data-selected')).toBe(false)
     expect(view.container.querySelector('[data-chat-call-id="parent:code:1"]')?.getAttribute('data-selected')).toBe('true')
   })

From 5934bbc32e34d733a81a57a9daf0e9a9a31caa9a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:17:14 +0800
Subject: [PATCH 259/516] docs(skills): preserve browser GIF evidence chains

---
 ...08-08-browser-gif-evidence-chain.i18n.yaml |  6 +++
 .../2026-08-08-browser-gif-evidence-chain.md  | 37 +++++++++++++++++++
 ...026-08-08-browser-gif-evidence-chain.zh.md | 37 +++++++++++++++++++
 .agents/skills/record-browser-gif/SKILL.md    | 32 ++++++++++------
 4 files changed, 100 insertions(+), 12 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
 create mode 100644 .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md

diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
new file mode 100644
index 0000000000..ea763ef0e8
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.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/process/2026-08-08-browser-gif-evidence-chain.md
+2026-08-08-browser-gif-evidence-chain.md: 9fe24b211e7094d4769af50c8b0ceae5c43fb4be
+2026-08-08-browser-gif-evidence-chain.zh.md: a84ea46373d8684389ce0c8c61887906e1fdc025
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
new file mode 100644
index 0000000000..9fe24b211e
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
@@ -0,0 +1,37 @@
+# Agent Note: Browser GIFs preserve one evidence chain
+
+Status: implemented
+
+English | [中文](2026-08-08-browser-gif-evidence-chain.zh.md)
+
+## Problem
+
+A browser-demo storyboard can contain individually truthful screenshots without proving one truthful execution. Reusing global application state can admit old settings or sessions, capture automation can accidentally combine frames from separate model runs, and a chat transcript can show a successful fallback without exposing the tool rejection that caused it. Fuzzy accessible-name matching can also accept prompt echoes or descendant text instead of the intended result.
+
+Headless production recording has two further boundaries. A product default may open a native operating-system surface that automation cannot drive, while replacing that surface with a mock or test hook would change the provenance. After publication, a successful git push does not prove that a private-repository GIF is fetchable or that GitHub recognizes the pull-request Markdown as an image.
+
+## Decision
+
+The [`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) workflow treats one storyboard as one evidence chain pinned to an exact pull-request head. Each run uses fresh `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, and session state, and every published frame comes from the same server and model-backed scenario run. A failed capture run is discarded and repeated from fresh roots rather than combined with another run.
+
+Browser automation waits for unique, exact semantic states. When the claim concerns a tool call, rejection, or recovery, the storyboard includes a detail or trajectory frame that identifies the tool, shows its status or stable error code, and shows the downstream result. The final encoded GIF remains the verification subject; when a viewer cannot animate it, representative frames are decoded from that GIF instead of treating source screenshots as equivalent evidence.
+
+The available browser-control workflow remains preferred. When it is unavailable, the recorder uses the repository-declared Playwright dependency in an isolated headless browser rather than installing another driver or opening the user's browser. A native production surface may be replaced only through normal application configuration with an official browser-operable production backend, and that override is stated in the provenance. Fixtures, mock transports, synthetic events, and test-only hooks do not substantiate a real-production claim.
+
+Publication verifies the boundary again. The assets branch contains media only, the staged and published bytes match the verified artifact, and a private-repository asset is checked through authenticated API or raw requests for its path, byte size, checksum, response status, and media type. This proves the repository-member review path only; the [documentation-site image decision](2026-08-06-doc-site-carries-its-images.md) owns why a public site cannot depend on a private raw URL. Immediately before the pull-request body changes, the live head must still equal the recorded head; GitHub's Markdown renderer must then produce the expected image without changing that code head.
+
+## Alternatives considered
+
+**Allow frames from separate runs when their visible states look equivalent.** Visual similarity does not establish shared state, causal order, or one scenario execution. Re-recording costs another real round but preserves the claim the storyboard makes.
+
+**Use the chat transcript as sufficient proof of tool recovery.** A final answer proves that the task completed, but it can hide which tool ran, whether the failure was structured, and whether the model recovered from that failure. A trajectory or detail frame carries those facts directly.
+
+**Replace inaccessible native UI with a fixture or test hook.** That makes automation easier by changing the product path under observation. Selecting an official production backend through normal configuration keeps the exercised implementation real and makes the narrower mode explicit.
+
+**Trust a successful assets-branch push or an anonymous fetch.** A push proves only that git accepted bytes, while private repositories intentionally reject unauthenticated raw requests. Authenticated byte verification plus GitHub Markdown rendering tests the two publication boundaries that reviewers use.
+
+## Consequences
+
+GUI evidence now establishes one causal execution rather than a collage of plausible states, and reviewers can inspect both a structured tool failure and the completed result. Publication detects stale pull-request heads, corrupted or misplaced media, and invalid image Markdown before the body is treated as finished.
+
+The workflow spends additional scratch state, may repeat a real model round after a capture failure, and usually adds a detail frame plus authenticated publication checks. Headless recordings can use fewer production backends than an interactive desktop, and every such selection remains part of the stated provenance.
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
new file mode 100644
index 0000000000..a84ea46373
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 浏览器 GIF 保留单一证据链
+
+Status: implemented
+
+[English](2026-08-08-browser-gif-evidence-chain.md) | 中文
+
+## 问题
+
+浏览器演示的分镜可以由每张都真实的截图组成，却无法证明这些截图来自同一次真实执行。复用应用全局状态可能引入旧设置或旧会话；录制自动化可能误将不同模型运行的画面合并；聊天 transcript（文本记录）可能显示降级处理成功，却没有揭示触发降级的工具拒绝。按无障碍名称进行模糊匹配，还可能误把提示词回显或后代文本当成预期结果。
+
+无头模式下的生产环境录制还有两道边界。产品默认配置可能打开自动化无法操控的原生操作系统界面，而用 mock 或测试钩子替换该界面会改变证据来源。发布之后，git 推送成功也不能证明私有仓库中的 GIF 可以获取，或 GitHub 能将 PR（Pull Request）的 Markdown 识别为图片。
+
+## 决策
+
+[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区和会话状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
+
+浏览器自动化会等待唯一且精确的语义状态。如果需要证明工具调用、拒绝或恢复，分镜就必须包含详情帧或轨迹帧：标明工具、显示其状态或稳定错误码，并展示后续结果。最终编码出的 GIF 始终是验证对象；如果查看器无法播放动画，应从该 GIF 中解码出代表性帧，而不能将源截图视为等效证据。
+
+仍应优先使用已有的浏览器控制工作流。如果该工作流不可用，录制程序应在隔离的无头浏览器中使用仓库已声明的 Playwright 依赖，而不是安装其他驱动或打开用户的浏览器。只有通过正常应用配置选用官方且可由浏览器操作的生产后端，才能替换原生生产界面，并且必须在证据来源说明中注明这一覆盖。fixture（测试前置数据）、mock 传输层、合成事件和测试专用钩子均不能支撑真实生产实现的主张。
+
+发布环节会再次验证边界。资产分支只包含媒体文件，暂存和发布的字节必须与已验证产物一致；对于私有仓库中的资产，应通过经身份验证的 API 或原始内容请求，检查其路径、字节大小、校验和、响应状态和媒体类型。这只能证明仓库成员的评审访问路径；[文档站点图片决策](2026-08-06-doc-site-carries-its-images.md)解释了公共站点为何不能依赖私有的原始内容 URL。修改 PR 正文之前，必须再次确认在线 head 仍与录制时的 head 相同；随后还必须确认 GitHub 的 Markdown 渲染器生成了预期图片，且代码 head 没有改变。
+
+## 曾考虑的替代方案
+
+**只要可见状态看起来等价，就允许使用不同运行的画面。**视觉相似不能证明各画面共享同一状态、具有因果顺序或来自同一次场景执行。重新录制需要再执行一次真实模型场景，但能维持整套分镜所表达的主张。
+
+**将聊天 transcript 视为工具恢复的充分证据。**最终答案能证明任务已经完成，却可能隐藏调用了哪个工具、失败是否为结构化失败，以及模型是否从该失败中恢复。轨迹帧或详情帧可以直接承载这些事实。
+
+**使用 fixture 或测试钩子替换无法访问的原生 UI。**这种做法通过改变被观察的产品路径来简化自动化。通过正常配置选用官方生产后端，既能保持受测实现真实，也能明确表述所采用的较窄运行模式。
+
+**相信资产分支推送成功或匿名请求成功。**推送只能证明 git 接受了相应字节，而私有仓库会有意拒绝未经身份验证的原始内容请求。经身份验证的字节校验与 GitHub Markdown 渲染验证，覆盖了评审者实际使用的两道发布边界。
+
+## 后果
+
+GUI 证据现在能证明一次具有因果关系的执行，而不是将若干可信状态拼成集合；评审者既可以检查结构化的工具失败，也可以检查最终完成的结果。在 PR 正文被视为完成之前，发布验证可以发现陈旧的 PR head、损坏或位置错误的媒体文件，以及无效的图片 Markdown。
+
+该工作流会占用额外的临时状态；录制失败后，可能需要重新执行一次由真实模型驱动的场景；通常还会增加一张详情帧和经身份验证的发布检查。相比交互式桌面，无头录制可使用的生产后端更少；每次选择这类后端时，都必须将其写入证据来源说明。
diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md
index 074b8b176e..c34c47d9d7 100644
--- a/.agents/skills/record-browser-gif/SKILL.md
+++ b/.agents/skills/record-browser-gif/SKILL.md
@@ -7,6 +7,8 @@ description: Record browser or Web UI interaction demos as optimized GIFs using
 
 Produce a short, truthful UI demonstration as a local GIF, and — only when the task includes attaching it to a pull request — publish it through the assets-branch workflow at the end of this skill. Use the browser-control skill for interaction and the bundled encoder for repeatable timing, dimensions, and size.
 
+The [evidence-chain decision](../../notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md) owns why one storyboard comes from one isolated run and why publication revalidates both the artifact and the demonstrated pull-request head.
+
 ## Every GUI pull request includes a GIF
 
 A pull request that changes product-user-visible GUI behavior MUST include a demonstration GIF recorded with this skill and embedded in the pull request body via [the assets-branch workflow](#publish-to-an-assets-branch).
@@ -25,22 +27,24 @@ The GIF's provenance is part of the evidence and must be real: a real server boo
 A GIF for a specific pull request demonstrates that pull request's tree, so stage per pull request:
 
 1. Build the branch tree being demonstrated — here, `pnpm run build && pnpm run build:web` — from the worktree that holds that branch. A GIF recorded against another branch's build misattributes the evidence.
-2. Boot one server per port from that tree, giving each recording a fresh scratch workspace directory so leftover sessions cannot appear in frames. Source the root `.env` for the API key through the application's normal path; never echo the key.
-3. Start a new session for each recorded scenario so earlier turns do not pollute the frames.
+2. Boot one server per port from that tree with fresh scratch `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, and session state so settings or sessions from another run cannot affect the evidence. Source the root `.env` for the API key through the application's normal path; never echo the key.
+3. Treat one storyboard as one evidence run: every published frame comes from that server and those state roots, workspace, session, and model-backed scenario run. If capture automation fails, discard its frames and rerun from fresh roots; never splice frames from separate runs.
 4. When switching between pull requests, stop the old server by PID or an exact match on its command line. A broad `pkill -f` pattern can match and kill the shell that launched it — including your own.
 
 ## Record the flow
 
-1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. Use the user's existing Chrome state only when requested or required.
+1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. If it is unavailable, use the repository-declared Playwright dependency in an isolated headless browser; do not install another driver or launch the user's browser. State that fallback in the provenance.
 2. Resolve the evidence boundary before recording: identify the exact origin, whether the app is built or in development, the transport, and any fixture or mock mode. Record only claims that the observed setup supports.
-3. Choose three to six states that tell one story, such as typed, running, settled, and detail. Prefer semantic state changes over continuous capture; omit loading churn that does not help the viewer.
-4. Keep one viewport and crop for every frame, and name frames lexically: `00-initial.png`, `01-typed.png`, and so on.
-5. Store frames under the repository's gitignored `.playwright-mcp/` directory — browser-tool screenshots can only be written under the tool's allowed roots, and relative filenames resolve against the repository root. Create the frame subdirectory first (`mkdir -p .playwright-mcp/gif-frames-<label>`); writing into a missing directory fails with ENOENT at capture time.
-6. Before each screenshot, wait for a concrete UI condition such as a unique label, enabled control, changed document title, or completed response. Do not use a fixed delay as proof that the application reached the state.
-7. Make completion predicates match an exact-text element — for example, an element whose trimmed text equals the expected reply — never a substring check such as `body.textContent.includes(...)`, which the echo of the user's own prompt also satisfies.
-8. Capture a transient state (spinner, running row) by driving a slow foreground operation — for example, a `sleep 15` bash command — and polling a concrete DOM marker (a `data-*` attribute) inside one browser-script call that also takes the screenshot. State polled across separate tool calls is lost, because the turn settles between calls.
-9. Engineer the prompt so the state you need actually occurs: instruct the model to wait in the foreground when it would otherwise background a slow command, and give it a settle sentinel such as "reply with the single word done" to anchor the completion predicate.
-10. Capture no secrets, personal data, unrelated tabs, or transient notifications. Stop any unnecessarily long real-API run after the demonstrated state is visible.
+3. When a production default opens a native operating-system surface that headless automation cannot drive, select an official browser-operable production backend through the application's normal configuration. State the override in the provenance; a fixture, mock transport, or test-only hook is not an acceptable substitute.
+4. Choose three to six states that tell one story, such as typed, running, settled, and detail. Prefer semantic state changes over continuous capture; omit loading churn that does not help the viewer.
+5. Keep one viewport and crop for every frame, and name frames lexically: `00-initial.png`, `01-typed.png`, and so on.
+6. Store frames under the repository's gitignored `.playwright-mcp/` directory — browser-tool screenshots can only be written under the tool's allowed roots, and relative filenames resolve against the repository root. Create the frame subdirectory first (`mkdir -p .playwright-mcp/gif-frames-<label>`); writing into a missing directory fails with ENOENT at capture time.
+7. Before each screenshot, wait for a concrete UI condition such as a unique label, enabled control, changed document title, or completed response. Require the locator to resolve exactly one element; for Playwright accessible-name locators, use `exact: true` when equality is intended because descendant text or a prompt echo can otherwise create a false match. Do not use a fixed delay as proof that the application reached the state.
+8. Make completion predicates match an exact-text element — for example, an element whose trimmed text equals the expected reply — never a substring check such as `body.textContent.includes(...)`, which the echo of the user's own prompt also satisfies.
+9. When the claim involves a tool call, rejection, or recovery, include a detail or trajectory frame that shows the tool identity, status or stable error code, and the downstream result. A chat-only outcome does not prove why the tool path behaved that way.
+10. Capture a transient state (spinner, running row) by driving a slow foreground operation — for example, a `sleep 15` bash command — and polling a concrete DOM marker (a `data-*` attribute) inside one browser-script call that also takes the screenshot. State polled across separate tool calls is lost, because the turn settles between calls.
+11. Engineer the prompt so the state you need actually occurs: instruct the model to wait in the foreground when it would otherwise background a slow command, and give it a settle sentinel such as "reply with the single word done" to anchor the completion predicate.
+12. Capture no secrets, personal data, unrelated tabs, or transient notifications. Stop any unnecessarily long real-API run after the demonstrated state is visible.
 
 Use the browser's own screenshot API. When it returns image bytes, save those bytes directly; the encoder detects image content independently of the filename extension.
 
@@ -68,7 +72,7 @@ For a large artifact, reduce `--max-width` first, then `--colors` or `--fps`; re
 ## Verify the artifact
 
 1. Read the encoder's JSON summary and confirm the output path, source and encoded frame counts, dimensions, duration, and byte size.
-2. Visually read the encoded GIF itself, not only the source frames. Confirm that the transition is legible, the last state is held long enough, and no sensitive content appears.
+2. Visually read the encoded GIF itself, not only the source frames. Confirm that the transition is legible, the last state is held long enough, and no sensitive content appears. If the viewer renders only the first frame, decode representative frames from the encoded GIF with `ffmpeg` and inspect those; the pre-encode screenshots do not prove the encoded order, palette, or final hold.
 3. Run `git status --short` and confirm frames and the artifact landed only under ignored paths.
 4. Return the absolute GIF path, render it when the client supports local media, and state whether the recording used a real API, fixture, or another transport. When the task does not include attaching the GIF to a pull request, stop here.
 
@@ -91,6 +95,10 @@ git push origin <assets-branch>
 
 For a new series, make a fresh shallow scratch clone (`git clone --depth 1 <repo-url> /tmp/assets-checkout`), create the orphan branch with `git switch --orphan <assets-branch>`, then add the GIF, commit, and push the same way.
 
+Before pushing, verify that the assets branch contains media only and that the staged GIF's checksum matches the verified local artifact. After pushing, use authenticated GitHub API or raw requests to confirm the remote path, byte size, checksum, `200` response, and `image/gif` content type. An anonymous `404` does not disprove a private-repository asset; authenticate the verification instead. This proves the repository-member review path, not public availability.
+
+Immediately before editing the pull-request body, re-read its live head and compare it with the head recorded in the GIF provenance. Stop and re-record when it moved. After the edit, render the body through GitHub's Markdown API and confirm that the expected `<img>` is present without changing the pull request's code head.
+
 Embed the GIF in the pull request body with the raw blob URL; the `?raw=true` suffix is required, because the plain blob URL renders GitHub's file page instead of the image:
 
 ```markdown

From 40ea07a33b7a9bc0757fed06751817543421f103 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:35:21 +0800
Subject: [PATCH 260/516] docs(skills): tighten GIF evidence boundaries

---
 ...2026-08-08-browser-gif-evidence-chain.i18n.yaml |  4 ++--
 .../2026-08-08-browser-gif-evidence-chain.md       |  4 ++--
 .../2026-08-08-browser-gif-evidence-chain.zh.md    |  4 ++--
 .agents/skills/record-browser-gif/SKILL.md         | 14 ++++++++------
 4 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
index ea763ef0e8..21006b51db 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.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 .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
-2026-08-08-browser-gif-evidence-chain.md: 9fe24b211e7094d4769af50c8b0ceae5c43fb4be
-2026-08-08-browser-gif-evidence-chain.zh.md: a84ea46373d8684389ce0c8c61887906e1fdc025
+2026-08-08-browser-gif-evidence-chain.md: 93dfad76b3c4d0934120a164ab22dd4b898e2e01
+2026-08-08-browser-gif-evidence-chain.zh.md: 8aafc842e55775bade8885a792ce7b92dfc8df4e
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
index 9fe24b211e..93dfad76b3 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
@@ -12,13 +12,13 @@ Headless production recording has two further boundaries. A product default may
 
 ## Decision
 
-The [`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) workflow treats one storyboard as one evidence chain pinned to an exact pull-request head. Each run uses fresh `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, and session state, and every published frame comes from the same server and model-backed scenario run. A failed capture run is discarded and repeated from fresh roots rather than combined with another run.
+The [`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) workflow treats one storyboard as one evidence chain pinned to an exact pull-request head. Before building, it requires a clean worktree and records that commit SHA. Each run uses fresh `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, session, and isolated browser state, and every published frame comes from the same server and model-backed scenario run. When a fresh browser context is unavailable, the exact origin's cookies and site storage are cleared before navigation. Existing user browser state is used only when requested or required, is declared in the provenance, and does not substantiate fresh client state. A failed capture run is discarded and repeated from fresh roots rather than combined with another run.
 
 Browser automation waits for unique, exact semantic states. When the claim concerns a tool call, rejection, or recovery, the storyboard includes a detail or trajectory frame that identifies the tool, shows its status or stable error code, and shows the downstream result. The final encoded GIF remains the verification subject; when a viewer cannot animate it, representative frames are decoded from that GIF instead of treating source screenshots as equivalent evidence.
 
 The available browser-control workflow remains preferred. When it is unavailable, the recorder uses the repository-declared Playwright dependency in an isolated headless browser rather than installing another driver or opening the user's browser. A native production surface may be replaced only through normal application configuration with an official browser-operable production backend, and that override is stated in the provenance. Fixtures, mock transports, synthetic events, and test-only hooks do not substantiate a real-production claim.
 
-Publication verifies the boundary again. The assets branch contains media only, the staged and published bytes match the verified artifact, and a private-repository asset is checked through authenticated API or raw requests for its path, byte size, checksum, response status, and media type. This proves the repository-member review path only; the [documentation-site image decision](2026-08-06-doc-site-carries-its-images.md) owns why a public site cannot depend on a private raw URL. Immediately before the pull-request body changes, the live head must still equal the recorded head; GitHub's Markdown renderer must then produce the expected image without changing that code head.
+Publication verifies the boundary again. The assets branch contains media only, the staged and published bytes match the verified artifact, and a private-repository asset is checked through authenticated API or raw requests for its path, byte size, checksum, response status, and media type. This proves the repository-member review path only; the [documentation-site image decision](2026-08-06-doc-site-carries-its-images.md) owns why a public site cannot depend on a private raw URL. Immediately before the pull-request body changes, the live head must still equal the recorded head. After the edit, the live head is checked again and must remain at that recorded value; GitHub's Markdown renderer separately must produce the expected image.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
index a84ea46373..8aafc842e5 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
@@ -12,13 +12,13 @@ Status: implemented
 
 ## 决策
 
-[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区和会话状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
+[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求工作树干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器 context 时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
 
 浏览器自动化会等待唯一且精确的语义状态。如果需要证明工具调用、拒绝或恢复，分镜就必须包含详情帧或轨迹帧：标明工具、显示其状态或稳定错误码，并展示后续结果。最终编码出的 GIF 始终是验证对象；如果查看器无法播放动画，应从该 GIF 中解码出代表性帧，而不能将源截图视为等效证据。
 
 仍应优先使用已有的浏览器控制工作流。如果该工作流不可用，录制程序应在隔离的无头浏览器中使用仓库已声明的 Playwright 依赖，而不是安装其他驱动或打开用户的浏览器。只有通过正常应用配置选用官方且可由浏览器操作的生产后端，才能替换原生生产界面，并且必须在证据来源说明中注明这一覆盖。fixture（测试前置数据）、mock 传输层、合成事件和测试专用钩子均不能支撑真实生产实现的主张。
 
-发布环节会再次验证边界。资产分支只包含媒体文件，暂存和发布的字节必须与已验证产物一致；对于私有仓库中的资产，应通过经身份验证的 API 或原始内容请求，检查其路径、字节大小、校验和、响应状态和媒体类型。这只能证明仓库成员的评审访问路径；[文档站点图片决策](2026-08-06-doc-site-carries-its-images.md)解释了公共站点为何不能依赖私有的原始内容 URL。修改 PR 正文之前，必须再次确认在线 head 仍与录制时的 head 相同；随后还必须确认 GitHub 的 Markdown 渲染器生成了预期图片，且代码 head 没有改变。
+发布环节会再次验证边界。资产分支只包含媒体文件，暂存和发布的字节必须与已验证产物一致；对于私有仓库中的资产，应通过经身份验证的 API 或原始内容请求，检查其路径、字节大小、校验和、响应状态和媒体类型。这只能证明仓库成员的评审访问路径；[文档站点图片决策](2026-08-06-doc-site-carries-its-images.md)解释了公共站点为何不能依赖私有的原始内容 URL。修改 PR 正文之前，必须再次确认在线 head 仍与录制时的 head 相同。编辑后还要再次检查在线 head，且它必须保持为该记录值；GitHub 的 Markdown 渲染器则须单独生成预期图片。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md
index c34c47d9d7..90862b113e 100644
--- a/.agents/skills/record-browser-gif/SKILL.md
+++ b/.agents/skills/record-browser-gif/SKILL.md
@@ -13,7 +13,7 @@ The [evidence-chain decision](../../notes/implemented/process/2026-08-08-browser
 
 A pull request that changes product-user-visible GUI behavior MUST include a demonstration GIF recorded with this skill and embedded in the pull request body via [the assets-branch workflow](#publish-to-an-assets-branch).
 
-The GIF's provenance is part of the evidence and must be real: a real server booted from that pull request's own branch tree, a real API key, and real model rounds. Never substitute fixture queries, mock transports, synthetic event injection, or test-only hooks unless the user explicitly asked for fixture provenance. State the provenance next to the embed — which tree served, which mode flags, that a real model round ran — so reviewers know exactly what the recording proves.
+The GIF's provenance is part of the evidence and must be real: a real server booted from that pull request's own branch tree, a real API key, and real model rounds. Never substitute fixture queries, mock transports, synthetic event injection, or test-only hooks unless the user explicitly asked for fixture provenance. State the provenance next to the embed — the exact demonstrated commit SHA, which tree and origin served, which mode flags or browser-state exceptions applied, and that a real model round ran — so reviewers know exactly what the recording proves.
 
 ## Keep the boundary explicit
 
@@ -26,14 +26,14 @@ The GIF's provenance is part of the evidence and must be real: a real server boo
 
 A GIF for a specific pull request demonstrates that pull request's tree, so stage per pull request:
 
-1. Build the branch tree being demonstrated — here, `pnpm run build && pnpm run build:web` — from the worktree that holds that branch. A GIF recorded against another branch's build misattributes the evidence.
-2. Boot one server per port from that tree with fresh scratch `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, and session state so settings or sessions from another run cannot affect the evidence. Source the root `.env` for the API key through the application's normal path; never echo the key.
+1. Require a clean worktree, record its exact commit with `git rev-parse HEAD`, then build that recorded tree — here, `pnpm run build && pnpm run build:web`. A GIF recorded against another commit's build misattributes the evidence.
+2. Boot one server per port from that tree with fresh scratch `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, and session state. Give the browser a fresh isolated context or profile as well; if the browser workflow cannot create one, clear that origin's cookies and site storage before navigation so persisted client state cannot affect the evidence. Source the root `.env` for the API key through the application's normal path; never echo the key.
 3. Treat one storyboard as one evidence run: every published frame comes from that server and those state roots, workspace, session, and model-backed scenario run. If capture automation fails, discard its frames and rerun from fresh roots; never splice frames from separate runs.
 4. When switching between pull requests, stop the old server by PID or an exact match on its command line. A broad `pkill -f` pattern can match and kill the shell that launched it — including your own.
 
 ## Record the flow
 
-1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. If it is unavailable, use the repository-declared Playwright dependency in an isolated headless browser; do not install another driver or launch the user's browser. State that fallback in the provenance.
+1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. Use the user's existing Chrome state only when requested or required; state that exception in the provenance and do not claim fresh client state. If browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser; do not install another driver or launch the user's browser. State that fallback in the provenance.
 2. Resolve the evidence boundary before recording: identify the exact origin, whether the app is built or in development, the transport, and any fixture or mock mode. Record only claims that the observed setup supports.
 3. When a production default opens a native operating-system surface that headless automation cannot drive, select an official browser-operable production backend through the application's normal configuration. State the override in the provenance; a fixture, mock transport, or test-only hook is not an acceptable substitute.
 4. Choose three to six states that tell one story, such as typed, running, settled, and detail. Prefer semantic state changes over continuous capture; omit loading churn that does not help the viewer.
@@ -82,6 +82,8 @@ Perform this step only when the task includes attaching the GIF to a pull reques
 
 Never commit a GIF to the pull request's own branch or any branch that merges into a long-lived branch: binary media committed there bloats the repository history for every future clone. GIFs live on a dedicated orphan assets branch — a branch with no parent commit and nothing but media — and one assets branch serves a whole pull request series (existing branches: `code-mode-ui-assets`, `pr-613-assets`).
 
+Before either workflow below pushes, verify that the assets branch contains media only and that the staged GIF's checksum matches the verified local artifact.
+
 For an existing assets branch, work in a shallow single-branch scratch clone so the publication cannot touch your working tree:
 
 ```sh
@@ -95,9 +97,9 @@ git push origin <assets-branch>
 
 For a new series, make a fresh shallow scratch clone (`git clone --depth 1 <repo-url> /tmp/assets-checkout`), create the orphan branch with `git switch --orphan <assets-branch>`, then add the GIF, commit, and push the same way.
 
-Before pushing, verify that the assets branch contains media only and that the staged GIF's checksum matches the verified local artifact. After pushing, use authenticated GitHub API or raw requests to confirm the remote path, byte size, checksum, `200` response, and `image/gif` content type. An anonymous `404` does not disprove a private-repository asset; authenticate the verification instead. This proves the repository-member review path, not public availability.
+After pushing, use authenticated GitHub API or raw requests to confirm the remote path, byte size, checksum, `200` response, and `image/gif` content type. An anonymous `404` does not disprove a private-repository asset; authenticate the verification instead. This proves the repository-member review path, not public availability.
 
-Immediately before editing the pull-request body, re-read its live head and compare it with the head recorded in the GIF provenance. Stop and re-record when it moved. After the edit, render the body through GitHub's Markdown API and confirm that the expected `<img>` is present without changing the pull request's code head.
+Immediately before editing the pull-request body, re-read its live head and compare it with the commit recorded in the GIF provenance. Stop and re-record when it moved. After the edit, re-read the live head and require it to remain at that recorded commit. Separately, render the body through GitHub's Markdown API and confirm that the expected `<img>` is present.
 
 Embed the GIF in the pull request body with the raw blob URL; the `?raw=true` suffix is required, because the plain blob URL renders GitHub's file page instead of the image:
 

From 9ed33dfe4f8e784536e0741ed447af638e8e26d4 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:08:22 +0800
Subject: [PATCH 261/516] refactor(client): localize nested Tool call trees

---
 ...ient-tool-presentation-ownership.i18n.yaml |   4 +-
 ...8-08-client-tool-presentation-ownership.md |  26 +--
 ...8-client-tool-presentation-ownership.zh.md |  26 +--
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |   4 +-
 packages/client/runtime/README.zh.md          |   4 +-
 packages/client/runtime/src/client/index.ts   |  13 +-
 .../client/session-history/history-fold.ts    |  92 +++-------
 .../src/client/sessions/conversation.ts       |  28 +--
 .../runtime/src/client/sessions/history.ts    |   6 +-
 .../runtime/src/client/sessions/session.ts    |  87 ++-------
 .../src/client/sessions/tool-call-tree.ts     | 171 ++++++++++++++++++
 .../src/client/sessions/transcript-adapter.ts |   1 +
 packages/client/runtime/tests/session.spec.ts |  81 +++++++--
 packages/client/test-runtime/src/fixtures.ts  |   1 -
 .../src/client/chat/ChatView.tsx              |  11 +-
 .../src/client/skeleton/DetailsPanel.tsx      |  28 ++-
 .../ui-conversation/tests/chat-stats.spec.tsx |   6 +-
 .../ui-conversation/tests/chat-view.spec.tsx  |   6 +-
 .../tests/gate-branch-tails.spec.tsx          |  26 ++-
 .../ui-conversation/tests/input-bar.spec.tsx  |   2 +-
 .../tests/input-matrix.spec.tsx               |   2 +-
 .../tests/input-scenarios.spec.tsx            |   2 +-
 .../ui-conversation/tests/queue-dock.spec.tsx |   2 +-
 .../ui-conversation/tests/skeleton.spec.tsx   |   2 +-
 .../tests/produced-files.spec.tsx             |   2 +-
 .../client/ui-skill/tests/skill-row.spec.tsx  |   3 +-
 packages/client/ui-tool/README.i18n.yaml      |   4 +-
 packages/client/ui-tool/README.md             |   5 +-
 packages/client/ui-tool/README.zh.md          |   5 +-
 .../ui-tool/src/client/tool/ToolCallTree.tsx  |  65 ++++---
 .../ui-tool/tests/ask-question-row.spec.tsx   |   4 +-
 .../ui-tool/tests/assembly-surfaces.spec.tsx  |   3 +-
 .../ui-tool/tests/chat-code-subcalls.spec.tsx |  59 +++---
 .../ui-tool/tests/coverage-tails.spec.tsx     |   8 +-
 .../client/ui-tool/tests/diff-card.spec.tsx   |   6 +-
 .../client/ui-tool/tests/read-card.spec.tsx   |   6 +-
 .../client/ui-tool/tests/search-card.spec.tsx |   8 +-
 .../ui-tool/tests/terminal-card.spec.tsx      |  17 +-
 .../client/ui-tool/tests/todo-row.spec.tsx    |   4 +-
 .../ui-tool/tests/tool-call-tree.spec.tsx     |  35 ++--
 .../client/ui-tool/tests/tool-row.spec.tsx    |   4 +-
 .../ui-tool/tests/toolview-slot.spec.tsx      |   2 +-
 .../client/ui-tool/tests/web-card.spec.tsx    |   8 +-
 .../src/client/TrajectoryView.tsx             |   4 +-
 .../client/ui-trajectory/src/client/layout.ts |  48 +++--
 .../ui-trajectory/tests/layout.spec.tsx       |  59 ++++--
 .../client/ui-trajectory/tests/views.spec.tsx |   5 +-
 48 files changed, 586 insertions(+), 413 deletions(-)
 create mode 100644 packages/client/runtime/src/client/sessions/tool-call-tree.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index 5097b9e8a9..e1beb13c2c 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.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 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
-2026-08-08-client-tool-presentation-ownership.md: e61c2030457cc9f0fda214e896b76afb37d0d2bc
-2026-08-08-client-tool-presentation-ownership.zh.md: 5c56b8c17ef5ca6695f3b28f6b93218dade356c7
+2026-08-08-client-tool-presentation-ownership.md: 9ea7d7dfc5e18e541550569795c5e1db84d6ad91
+2026-08-08-client-tool-presentation-ownership.zh.md: 11a42ad69e4374afa6dccd3af74b8bd1b5e5c6f1
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
index e61c203045..9ea7d7dfc5 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
@@ -12,19 +12,19 @@ That ownership made `ui-conversation` interpret business Tool names and made sub
 
 ## Decision
 
-Tool is a first-class Client UI concept with one presentation owner, `@deepseek-ai/dsh-client-ui-tool`. Session Event, projection, fold, `ConversationSnapshot` construction and caching, historical paging, and Code Dispatch indexing remain unchanged.
+Tool is a first-class Client UI concept with one presentation owner, `@deepseek-ai/dsh-client-ui-tool`. Runtime normalizes Code Dispatch into recursive `ToolCallBlock` values: every root or child owns its next level through `subCalls`, and `ConversationSnapshot` exposes no separate parent-to-children map.
 
 “First-class concept” describes UI ownership only; it adds no Runtime data kind. `ConversationNode` remains the transcript projection, `ChatFlowItem` remains the render unit produced when conversation sorts and groups nodes, `ToolCallBlock` remains the standard data for one call, and `ToolCallTree` only composes root/subcall presentation within Tool. Command continues to render through the separate `'conversation.chat.commandview'` seat and does not become Tool.
 
 `ui-conversation` owns ordered placement. `deriveChatFlow()` still decides where a settled Tool group appears, and `ChatView` still appends running calls, maintains scroll anchors and selection, and supplies host actions. For each root call it renders the single/session `'conversation.chat.tool'` seat with the root block, selected call id, session cwd, and open-file/inspect callbacks. It does not read Code Dispatch children, branch on Tool names, or import Tool-specific views and card models.
 
-`ui-tool` occupies that whole-Tool seat. Through its standard session slot props, `ToolCallTree` selects the Runtime-projected `codeDispatches[rootCallId]` array, renders the root followed by that one currently supported child level, and routes both forms through one keyed/session `'tool.call.toolview'` child slot using `entryKey: toolName`. An absent business registration renders `GenericToolCard`. This is deliberately one-level composition, not a claim that the Runtime supports an arbitrary recursive call graph.
+`ui-tool` occupies that whole-Tool seat. `ToolCallTree` recursively walks the root block's `subCalls` and routes every level through one keyed/session `'tool.call.toolview'` child slot using `entryKey: toolName`. An absent business registration renders `GenericToolCard`. It neither reads Session nor maintains a second call topology.
 
 Business plugins register only atomic views against `'tool.call.toolview'`. Their owner payload is the standard Tool call block plus identity, cwd, and host actions; it carries no Session projector or conversation service. Skill remains an ordinary Tool and `ui-skill` registers the `skill` key through this seam. Existing first-party views live in `ui-tool` until a business package has a reason to own one independently.
 
 The details panel is a second Tool presentation site but not a call-tree owner. `ui-conversation` delegates its selected output body through the single/session `'conversation.details.tool'` seat; `ui-tool` renders the card-aware output and the seat fallback preserves raw result text when the plugin is absent. Card models therefore have one production owner without introducing a reverse implementation import.
 
-The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch stays a top-level official concept because it changes `codeDispatches` and parent/child identity; ordinary Tool business differences stay at the keyed presentation seam. This package boundary does not add a Tool projector/fold registry.
+The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch is an official top-level concept because it changes parent/child identity; a private `ToolCallTree` shares one fold between live and history paths and projects its index into standard recursive call blocks. Ordinary Tool business differences stay at the keyed presentation seam, and this package boundary adds no Tool projector/fold registry.
 
 ## Runtime and render path
 
@@ -39,22 +39,22 @@ ConversationSnapshot.runningCalls     |
   -> ChatView flow tail ---------------+-> ToolSeat
                                            -> conversation.chat.tool
                                            -> ToolCallTree
-ConversationSnapshot.codeDispatches[rootCallId] -+
-                                                  +-> root ToolCall + one-level child ToolCall
-                                                      -> tool.call.toolview(entryKey = toolName)
-                                                           |- registered atomic view
-                                                           `- GenericToolCard fallback
+                                                -> root ToolCallBlock
+                                                     `- subCalls[] (recursive)
+                                                          -> tool.call.toolview(entryKey = toolName)
+                                                               |- registered atomic view
+                                                               `- GenericToolCard fallback
 ```
 
-The live Session's [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) caches arrays or maps such as `nodes`, `runningCalls`, and `codeDispatches` against independent revisions. Their references stay stable when the corresponding business state has not changed, allowing React selectors and memoization to skip unrelated updates. The historical projection's [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) reconstructs the same running-call and Code Dispatch shapes from entries in its window. Tool UI consumes the snapshot shapes already unified by those paths; presentation packages do not repeat call/result pairing, historical replay, or cache indexing.
+Runtime's [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) privately indexes child lifecycles by parent callId and is shared by the live [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) and historical [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) paths. It recursively projects children onto root `ToolCallBlock` values and copies only the owning ancestor path when a child changes. Unchanged siblings, other roots, and snapshot references with no Tool-topology change stay stable so React selectors and memoization can skip unrelated updates. Tool UI consumes this unified tree without repeating call/result pairing, historical replay, or cache indexing.
 
-[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) reruns [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts) only when the `nodes` reference changes. It groups consecutive settled Tool results into a `tool-group`, while running root calls append at the flow tail. Both paths ultimately enter the same `ToolSeat`, so settled and running forms share the whole-Tool seat. `ToolCallTree` selects only the current root's `codeDispatches[rootCallId]`; it does not introduce a business projector for presentation of other roots.
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) reruns [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts) only when the `nodes` reference changes. It groups consecutive settled Tool results into a `tool-group`, while running root calls append at the flow tail. Both paths ultimately enter the same `ToolSeat`, so settled and running forms share the whole-Tool seat. Selection is passed only to the root containing that call, and `ToolCallTree` then renders recursively within that local tree.
 
 ## Code and responsibility boundaries
 
 | Owner | Primary code | Owns | Explicitly does not own |
 |---|---|---|---|
-| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts), [`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result pairing, running/settled lifecycle, Code Dispatch parent/child index, snapshot reference stability | Business views selected by Tool name |
+| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts), [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts), [`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result pairing, running/settled lifecycle, recursive parent/child tree, snapshot structural sharing | Business views selected by Tool name |
 | `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts), [`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx), [`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow order, settled groups, running tail, scroll anchors, selection and host actions, whole-Tool seat declaration | subcall composition, `toolName` dispatch, Generic fallback, Tool card models |
 | `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts), [`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx), [`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall composition, atomic keyed dispatch, Generic fallback, Tool card models and built-in Tool views | ChatFlow ordering, Session Event fold |
 | Business Tool plugins | [`ui-skill` registration example](../../../../packages/client/ui-skill/src/client/index.ts) | Atomic views for one or more wire Tool names | root/subcall placement and lifecycle pairing |
@@ -82,7 +82,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 ## Details path
 
-[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) still locates the selected call in `nodes`, `runningCalls`, and `codeDispatches`, and it owns input arguments, empty states, and panel lifecycle. It passes only `{ block, cwd }` to `'conversation.details.tool'`; [`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) reuses Tool card models to render the output. When `ui-tool` is absent, a settled call falls back to raw result text and a running call shows conversation's running fallback, so details never imports the Tool implementation in reverse.
+[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) locates the selected call recursively in `nodes` and `runningCalls` through their `subCalls`, and it owns input arguments, empty states, and panel lifecycle. It passes only `{ block, cwd }` to `'conversation.details.tool'`; [`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) reuses Tool card models to render the output. When `ui-tool` is absent, a settled call falls back to raw result text and a running call shows conversation's running fallback, so details never imports the Tool implementation in reverse.
 
 ## Verification
 
@@ -96,7 +96,7 @@ Test ownership follows production ownership. `ui-conversation` tests install a l
 
 **Add business-specific Session projectors or folds.** Rejected: ordinary Tool views consume the standard call block already reconstructed by Runtime. A second registry would create two authorities for call identity and historical replay. Only a feature that changes logged topology or lifecycle earns a Runtime-level extension.
 
-**Make each atomic Tool view render its own subcalls recursively.** Rejected: the atomic registrant receives one Tool call and should not know whether it is a root or child. Root/child composition belongs to `ui-tool`, and the current wire/runtime shape only supports one Code Dispatch child level.
+**Make each atomic Tool view render its own subcalls recursively.** Rejected: the atomic registrant receives one Tool call and should not know whether it is a root or child. Recursive root/child composition belongs centrally to `ui-tool`'s `ToolCallTree`.
 
 **Import `ui-tool` components directly from `ui-conversation`.** Rejected: it would reverse the intended feature direction and make Tool presentation mandatory. Declared slots retain lifecycle ownership, fallback behavior, and independent plugin loading.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index 5c56b8c17e..11a42ad69e 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -12,19 +12,19 @@ Client Runtime 已经把 Tool 调用投影成稳定的生命周期：它按 `cal
 
 ## Decision
 
-Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。Session Event、projection、fold、`ConversationSnapshot` 构建与缓存、历史分页及 Code Dispatch 索引保持不变。
+Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。Runtime 将 Code Dispatch 规范化为递归 `ToolCallBlock`：每个 root 或 child 通过自己的 `subCalls` 拥有下一层调用，`ConversationSnapshot` 不再公开单独的 parent-to-children map。
 
 这里的“一级概念”只描述 UI 所有权，不增加 Runtime 数据种类。`ConversationNode` 仍是 transcript projection，`ChatFlowItem` 仍是 conversation 对节点进行排序与分组后得到的渲染单元，`ToolCallBlock` 仍是单次调用的标准数据，而 `ToolCallTree` 只负责 Tool 内部的 root/subcall 展示编排。Command 继续通过独立的 `'conversation.chat.commandview'` 席位渲染，不并入 Tool。
 
 `ui-conversation` 拥有有序放置。`deriveChatFlow()` 仍决定 settled Tool group 在哪里出现，`ChatView` 仍追加 running call、维护滚动 anchor 与 selection，并提供宿主动作。对于每个 root call，它使用 root block、selected call id、session cwd 以及 open-file/inspect 回调渲染 single/session 的 `'conversation.chat.tool'` 席位。它不读取 Code Dispatch child、不按 Tool 名称分支，也不导入 Tool 专属 view 或 card model。
 
-`ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 通过标准 session slot props 选择 Runtime 投影的 `codeDispatches[rootCallId]` 数组，先渲染 root，再渲染当前支持的一层 child；两种调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。这里刻意只编排一层，并不声称 Runtime 已支持任意递归调用图。
+`ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 直接递归遍历 root block 的 `subCalls`，并让每一层调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。它不读取 Session，也不维护第二份调用拓扑。
 
 业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 seam 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
 
 details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 通过 single/session 的 `'conversation.details.tool'` 席位委托 selected output body；`ui-tool` 渲染能够识别 card 的输出，插件缺席时由席位 fallback 保留 raw result text。因此 card model 只有一个生产代码所有者，也不需要引入反向实现依赖。
 
-Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 会改变 `codeDispatches` 与 parent/child identity，因此继续作为官方顶级概念；普通 Tool 业务差异停留在 keyed 展示 seam。这个包边界不会增加 Tool projector/fold registry。
+Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 作为官方顶级概念改变 parent/child identity；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示 seam，这个包边界不会增加 Tool projector/fold registry。
 
 ## Runtime 与渲染链路
 
@@ -39,22 +39,22 @@ ConversationSnapshot.runningCalls     |
   -> ChatView flow tail ---------------+-> ToolSeat
                                            -> conversation.chat.tool
                                            -> ToolCallTree
-ConversationSnapshot.codeDispatches[rootCallId] -+
-                                                  +-> root ToolCall + one-level child ToolCall
-                                                      -> tool.call.toolview(entryKey = toolName)
-                                                           |- registered atomic view
-                                                           `- GenericToolCard fallback
+                                                -> root ToolCallBlock
+                                                     `- subCalls[] (recursive)
+                                                          -> tool.call.toolview(entryKey = toolName)
+                                                               |- registered atomic view
+                                                               `- GenericToolCard fallback
 ```
 
-Live Session 的 [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 按独立 revision 缓存 `nodes`、`runningCalls`、`codeDispatches` 等数组或 map；没有对应业务变化时，它们保持引用稳定，供 React selector 与 memo 跳过无关更新。历史 projection 的 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 从窗口内 entry 重建相同的 running call 与 Code Dispatch 形态。Tool UI 直接消费这两个路径已经统一的 snapshot，不在展示包中重复 call/result 配对、历史 replay 或缓存索引。
+Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) 私下按 parent callId 索引 child lifecycle，并供 Live [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 与历史 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 共用。它把 children 递归投影到 root `ToolCallBlock`，child 变化时只复制所属祖先路径；未变化的 sibling、其他 root，以及没有 Tool 拓扑变化的 snapshot 引用保持稳定，供 React selector 与 memo 跳过无关更新。Tool UI 直接消费这两个路径统一后的树，不重复 call/result 配对、历史 replay 或缓存索引。
 
-[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只在 `nodes` 引用变化时重新执行 [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)，把连续 settled Tool result 合为 `tool-group`；running root call 则追加在 flow tail。两条路径最终都进入同一个 `ToolSeat`，因此 settled/running 形态共享整体 Tool 席位。`ToolCallTree` 只选择当前 root 的 `codeDispatches[rootCallId]`，不会因其他 root 的展示逻辑引入业务 projector。
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只在 `nodes` 引用变化时重新执行 [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)，把连续 settled Tool result 合为 `tool-group`；running root call 则追加在 flow tail。两条路径最终都进入同一个 `ToolSeat`，因此 settled/running 形态共享整体 Tool 席位。selection 只传给包含该 call 的 root，`ToolCallTree` 再沿该 root 的局部树递归渲染。
 
 ## 代码与职责边界
 
 | 所有者 | 主要代码 | 拥有的责任 | 明确不拥有 |
 |---|---|---|---|
-| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、Code Dispatch parent/child 索引、snapshot 引用稳定性 | Tool 名称对应的业务视图 |
+| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、递归 parent/child 树、snapshot 结构共享 | Tool 名称对应的业务视图 |
 | `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)、[`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx)、[`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow 顺序、settled group、running tail、scroll anchor、selection 与宿主动作、整体 Tool 席位声明 | subcall 组合、按 `toolName` 分发、Generic fallback、Tool card model |
 | `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts)、[`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx)、[`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall 组合、原子 keyed dispatch、Generic fallback、Tool card model 与内置 Tool view | ChatFlow 排序、Session Event fold |
 | 业务 Tool 插件 | [`ui-skill` 注册例](../../../../packages/client/ui-skill/src/client/index.ts) | 一个或多个 wire Tool name 的原子 view | root/subcall 位置与生命周期配对 |
@@ -82,7 +82,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 ## Details 路径
 
-[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) 仍从 `nodes`、`runningCalls` 与 `codeDispatches` 中定位选中的 call，并拥有 input 参数、空态和面板生命周期。它只把 `{ block, cwd }` 交给 `'conversation.details.tool'`；[`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) 复用 Tool card model 渲染 output。`ui-tool` 缺席时，settled call 回退为 raw result text，running call 显示 conversation 的 running fallback，因此 details 不反向导入 Tool 实现。
+[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) 在 `nodes` 与 `runningCalls` 的递归 `subCalls` 中定位 selected call，并拥有 input 参数、空态和面板生命周期。它只把 `{ block, cwd }` 交给 `'conversation.details.tool'`；[`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) 复用 Tool card model 渲染 output。`ui-tool` 缺席时，settled call 回退为 raw result text，running call 显示 conversation 的 running fallback，因此 details 不反向导入 Tool 实现。
 
 ## Verification
 
@@ -96,7 +96,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 **增加业务专属 Session projector 或 fold。** 拒绝：普通 Tool view 消费 Runtime 已重建的标准 call block。第二套 registry 会为 call identity 与历史 replay 建立两个权威。只有会改变日志拓扑或生命周期的能力才应获得 Runtime 级扩展。
 
-**让每个原子 Tool view 递归渲染自己的 subcall。** 拒绝：原子注册方只接收一个 Tool call，不应知道自己是 root 还是 child。root/child 编排归 `ui-tool`，且当前 wire/runtime 形态只支持一层 Code Dispatch child。
+**让每个原子 Tool view 递归渲染自己的 subcall。** 拒绝：原子注册方只接收一个 Tool call，不应知道自己是 root 还是 child。递归 root/child 编排统一归 `ui-tool` 的 `ToolCallTree`。
 
 **让 `ui-conversation` 直接导入 `ui-tool` 组件。** 拒绝：这会反转预期的 feature 依赖方向，并把 Tool 展示变成必选能力。声明式 slot 能保留生命周期所有权、fallback 行为与独立插件装载。
 
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index f45ceb712d..bb64a12d4e 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: bb85d3c7b45eb0d82d789a9133bba787f1d6c5e9
-README.zh.md: 18aedbb487a490c85ce68ccc460fd82218157843
+README.md: fad0f6e4f948ebf412b2bd837a4f68e6dc805ec8
+README.zh.md: 4ede12a320082a5023ec121306650fce72a12663
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index bb85d3c7b4..fad0f6e4f9 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -44,9 +44,9 @@ Because the projection is log-ordered, the node array is seq-monotonic by constr
 
 `SessionHistoryInspection.requests` is one chronological, purpose-discriminated provider-request stream. Assistant requests always carry their numeric `turn` and `step`; compaction requests carry `step: 0` and a `turn` owner that may be `null`. That null owner means a manual compaction ran standalone between turns, not that it belongs to either adjacent turn. A `session/end-seed` boundary closes an unmatched compaction request as an error at the boundary time with `Compaction was interrupted before completion.`; a later start projects as an independent request instead of overwriting the orphan.
 
-## Code Mode sub-dispatch index
+## Code Mode child-call tree
 
-`ConversationSnapshot.codeDispatches` groups a `run_code` call's sub-dispatches under their parent callId, in start order, using the native call-block shapes: a `tool/code-dispatch-start` event lands the `RunningToolCall` form (rows derive the running ring from the shape) and its `tool/code-dispatch` settlement replaces it in place with the `ToolResultNode` form, `callTime` carrying the paired start's time. A settle whose start fell outside the replay window appends directly with `callTime: null` (duration unknown — never a fabricated zero). Live mux frames and history replay build the identical index; sub-calls never join the transcript `nodes` flow; per-parent array and map references are memo-stable across unrelated snapshot swaps.
+Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Runtime's `ToolCallTree` privately maintains the parent-callId-to-children index: a `tool/code-dispatch-start` event lands as a `RunningToolCall`, and the matching `tool/code-dispatch` settlement replaces it in place with a `ToolResultNode` whose `callTime` comes from the paired start. When the start fell outside the replay window, the settlement appends directly with `callTime: null`; Runtime never fabricates a zero duration. Live mux frames and history replay share this fold and tree projection, and child calls never become independent roots in transcript `nodes`. A child update copies only its ancestor path to the owning root; unchanged siblings and other roots retain object identity.
 
 ## Session title projection
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 18aedbb487..4ede12a320 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -44,9 +44,9 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 `SessionHistoryInspection.requests` 是一条按时间顺序排列、以用途为判别字段的提供方请求流。助手请求始终携带数值型 `turn` 与 `step`；压缩请求携带 `step: 0`，其 `turn` 所有者可以是 `null`。这个 null 所有者表示手动压缩独立运行在两个轮次之间，并不表示它属于任一相邻轮次。`session/end-seed` 边界会在边界时刻将未匹配的压缩请求以错误状态结束，错误固定为 `Compaction was interrupted before completion.`；后续 start 会投影为独立请求，而不会覆盖这项遗留的未匹配请求。
 
-## Code Mode 子调用索引
+## Code Mode 子调用树
 
-`ConversationSnapshot.codeDispatches` 按父调用的 callId 和启动顺序，用原生调用块形状组织一个 `run_code` 调用的子调用：`tool/code-dispatch-start` 事件落成 `RunningToolCall` 形状（行组件从该形状推导运行中的转圈状态），其 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode` 形状，`callTime` 携带成对 start 事件的时间。start 落在回放窗口之外的完结事件则直接追加，`callTime: null`（耗时未知——绝不伪造零耗时）。live mux 帧与历史回放构建相同的索引；子调用永不进入 transcript 的 `nodes` 流；无关快照交换不会改变每个父调用对应的数组引用和映射引用，两者均保持 memo 稳定。
+每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Runtime 的 `ToolCallTree` 私下维护 parent callId 到 child 的索引：`tool/code-dispatch-start` 事件落成 `RunningToolCall`，对应的 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode`，其 `callTime` 来自成对 start 事件；start 落在回放窗口之外时，完结事件会以 `callTime: null` 直接追加，绝不伪造零耗时。live mux 帧与历史回放共用这套 fold 和树投影；子调用不会成为 transcript `nodes` 中的独立 root。一次 child 变化只会复制从该 child 到所属 root 的祖先链，未变化的 sibling 和其他 root 保持对象引用稳定。
 
 ## Session 标题投影
 
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index 3c4e8e0bf4..b7226c0085 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -8,7 +8,7 @@ import { SessionsService } from './sessions/service.ts'
 import type { SessionListState } from './sessions/service.ts'
 import { SessionHistoryService } from './session-history/service.ts'
 import { WorkspacesService } from './workspaces/service.ts'
-import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from './sessions/conversation.ts'
+import type { ConversationSnapshot } from './sessions/conversation.ts'
 import type { UseProjection } from './sessions/projection-store.ts'
 
 export { SlotsService } from './slots.ts'
@@ -49,10 +49,10 @@ export type {
 } from './contract/store.ts'
 export type {
   AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
-  AssistantTiming, CodeSubCall, CommandNode, CompactionSummaryNode, ComposerPhase,
+  AssistantTiming, CommandNode, CompactionSummaryNode, ComposerPhase,
   ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, QueuedMessage,
   RunningToolCall,
-  SteeringMessageNode, TodoItem, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
+  SteeringMessageNode, TodoItem, ToolCallBlock, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
 export type {
   ConversationContext, ConversationContextOriginKind,
@@ -89,13 +89,6 @@ declare module '@deepseek-ai/dsh-type-meta' {
 /** The conversation-snapshot selector hook supplied to session-scoped UI entries. */
 export type UseConversationSession = SnapshotSelectorHook<ConversationSnapshot>
 
-/**
- * One tool call as the chat flow renders it: still-running (spinner card) or
- * settled (result node). The fold produces both shapes; toolview components
- * narrow on the discriminant fields.
- */
-export type ToolCallBlock = RunningToolCall | ToolResultNode
-
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   /**
    * Session standard kit, real members (ui-slots declares the empty seat;
diff --git a/packages/client/runtime/src/client/session-history/history-fold.ts b/packages/client/runtime/src/client/session-history/history-fold.ts
index d792fd2b76..42aaa37027 100644
--- a/packages/client/runtime/src/client/session-history/history-fold.ts
+++ b/packages/client/runtime/src/client/session-history/history-fold.ts
@@ -1,4 +1,3 @@
-import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import {
   SurfaceManager, isSurfaceEligibleType, isSurfaceEvent,
@@ -7,7 +6,7 @@ import type {
   HistoryEntry, ToolCallView, ToolResultView,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type {
-  AssistantRequestConfig, AssistantTiming, CodeSubCall, ConversationNode,
+  AssistantRequestConfig, AssistantTiming, ConversationNode,
   PartialAssistant, RunningToolCall,
 } from '../sessions/conversation.ts'
 import { toAssistantBlocks } from '../sessions/conversation.ts'
@@ -20,6 +19,7 @@ import type { ConversationPromptSnapshot } from '../sessions/request-inspection.
 import { PartialAccumulator } from '../sessions/partial.ts'
 import type { AssistantStepMetadata } from '../sessions/assistant-timing.ts'
 import { indexAssistantStepTiming, settledAssistantTiming } from '../sessions/assistant-timing.ts'
+import { ToolCallTree } from '../sessions/tool-call-tree.ts'
 
 interface CallIndexEntry {
   name: string
@@ -41,7 +41,6 @@ export interface ConversationHistoryProjection {
   interruptedNodes: readonly ConversationNode[]
   partial: PartialAssistant | null
   runningCalls: readonly RunningToolCall[]
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
 }
 
 function replacementCrossesWindowHead(event: SessionEvent, baseSeq: number): boolean {
@@ -177,6 +176,7 @@ function materializeNode(
         meta: event.data.meta,
         callView: call?.callView ?? null,
         resultView,
+        subCalls: [],
       }
     }
     default:
@@ -188,74 +188,22 @@ function materializeNode(
 }
 /* jscpd:ignore-end */
 
-function projectTransient(entries: readonly HistoryEntry[]): Pick<
+interface TransientProjection extends Pick<
   ConversationHistoryProjection,
-  'interruptedNodes' | 'partial' | 'runningCalls' | 'codeDispatches'
+  'interruptedNodes' | 'partial' | 'runningCalls'
 > {
+  toolCallTree: ToolCallTree
+}
+
+function projectTransient(entries: readonly HistoryEntry[]): TransientProjection {
   let partial: PartialAccumulator | null = null
   const openCalls = new Map<string, RunningToolCall>()
   const interruptedNodes: ConversationNode[] = []
-  const codeDispatches = new Map<string, readonly CodeSubCall[]>()
+  const toolCallTree = new ToolCallTree()
 
   for (const entry of entries) {
     const { event } = entry
-    if ((event.type as string) === 'tool/code-dispatch-start') {
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-      }
-      const siblings = codeDispatches.get(data.parentCallId) ?? []
-      // The independent replay emits the same public running-call shape as
-      // Chat without reading or mutating Session's live index.
-      /* jscpd:ignore-start */
-      codeDispatches.set(data.parentCallId, [...siblings, {
-        callId: data.subCallId,
-        name: data.name,
-        argsRaw: JSON.stringify(data.arguments),
-        turn: 0,
-        step: 0,
-        time: event.time,
-        callView: null,
-      }])
-      /* jscpd:ignore-end */
-      continue
-    }
-    if ((event.type as string) === 'tool/code-dispatch') {
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-        isError: boolean
-        content: ContentBlock[]
-      }
-      const siblings = codeDispatches.get(data.parentCallId) ?? []
-      const at = siblings.findIndex(sub => sub.callId === data.subCallId)
-      const started = at === -1 ? undefined : siblings[at]
-      // History independently reproduces the public settled-call shape instead
-      // of consuming Session's live code-dispatch projection.
-      /* jscpd:ignore-start */
-      const settled: CodeSubCall = {
-        kind: 'tool-result', seq: event.seq, time: event.time,
-        callId: data.subCallId,
-        call: { name: data.name, argsRaw: JSON.stringify(data.arguments) },
-        callTime: started?.time ?? null,
-        content: data.content,
-        isError: data.isError,
-        callView: null,
-        resultView: null,
-      }
-      codeDispatches.set(
-        data.parentCallId,
-        at === -1
-          ? [...siblings, settled]
-          : siblings.map((sub, index) => index === at ? settled : sub),
-      )
-      /* jscpd:ignore-end */
-      continue
-    }
+    if (toolCallTree.apply(event)) continue
     switch (event.type) {
       case 'assistant/chunk': {
         const { turn, step, chunk } = event.data
@@ -280,6 +228,7 @@ function projectTransient(entries: readonly HistoryEntry[]): Pick<
           step: event.data.step,
           time: event.time,
           callView: entry.view?.for === 'call' ? entry.view.view : null,
+          subCalls: [],
         })
         /* jscpd:ignore-end */
         break
@@ -317,6 +266,7 @@ function projectTransient(entries: readonly HistoryEntry[]): Pick<
             error: { name: 'Interrupted', code: 'interrupted' },
             callView: call.callView,
             resultView: null,
+            subCalls: [],
           })
           /* jscpd:ignore-end */
         }
@@ -331,7 +281,7 @@ function projectTransient(entries: readonly HistoryEntry[]): Pick<
     interruptedNodes,
     partial: partial?.toPartial() ?? null,
     runningCalls: [...openCalls.values()],
-    codeDispatches,
+    toolCallTree,
   }
 }
 
@@ -462,9 +412,17 @@ export function projectConversationHistory(
     }
   }
 
+  const transient = projectTransient(entries)
+  const projectedEventNodes = transient.toolCallTree.projectNodes(eventNodes)
+  const projectedContexts = contexts.map((context): ConversationContext => {
+    const nodes = transient.toolCallTree.projectNodes(context.nodes)
+    return nodes === context.nodes ? context : { ...context, nodes }
+  })
   return {
-    eventNodes,
-    contexts,
-    ...projectTransient(entries),
+    eventNodes: projectedEventNodes,
+    contexts: projectedContexts,
+    interruptedNodes: transient.toolCallTree.projectNodes(transient.interruptedNodes),
+    partial: transient.partial,
+    runningCalls: transient.toolCallTree.projectRunningCalls(transient.runningCalls),
   }
 }
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index a881158525..dba9ec9513 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -174,6 +174,8 @@ export interface ToolResultNode {
   callView: ToolCallView | null
   /** Host-computed render intent from this tool/result's wire view; null = same default. */
   resultView: ToolResultView | null
+  /** Child calls owned by this call, in dispatch order. */
+  subCalls: readonly ToolCallBlock[]
 }
 
 /**
@@ -263,21 +265,6 @@ export type ConversationNode =
   | CompactionSummaryNode
   | UnknownSurfaceNode
 
-/**
- * One `run_code` sub-dispatch materialized in the native call-block shapes so
- * every consumer (tool rows, details panel) renders it through the exact
- * components that render a native call: a started-but-unsettled sub-call is a
- * {@link RunningToolCall} (rows derive the running state from the shape,
- * exactly as for native calls) and its `tool/code-dispatch` settlement
- * replaces it in place with the {@link ToolResultNode} form. Never part of
- * the transcript `nodes` flow — sub-calls live under their parent via
- * {@link ConversationSnapshot.codeDispatches}. `callId` is the deterministic
- * sub-call id (`<parent>:code:<n>`); the call side carries the sub-tool name
- * and its JSON-stringified logged arguments; `content`/`isError` are the
- * settled sub-call's complete logged outcome.
- */
-export type CodeSubCall = RunningToolCall | ToolResultNode
-
 /** In-flight tool card material: tool/call seen, tool/result not yet. */
 export interface RunningToolCall {
   callId: string
@@ -289,8 +276,12 @@ export interface RunningToolCall {
   time: number
   /** Host-computed render intent riding the tool/call frame; null = generic JSON card. */
   callView: ToolCallView | null
+  /** Child calls owned by this call, in dispatch order. */
+  subCalls: readonly ToolCallBlock[]
 }
 
+/** One running or settled call, recursively owning its child calls. */
+export type ToolCallBlock = RunningToolCall | ToolResultNode
 
 /** One transient inbox occurrence from the authoritative `session/queue` snapshot. */
 export interface QueuedMessage {
@@ -355,13 +346,6 @@ export interface ConversationSnapshot {
   turnEnds: ReadonlyMap<number, number>
   partial: PartialAssistant | null
   runningCalls: readonly RunningToolCall[]
-  /**
-   * `run_code` sub-dispatches grouped under their parent callId, in dispatch
-   * order. Populated from in-window `tool/code-dispatch` events (live and
-   * replay identically); the per-parent array reference is stable across
-   * unrelated snapshot swaps (memo premise, same regime as `nodes`).
-   */
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
   pending: readonly PendingInteraction[]
   /** Authoritative transient inbox snapshot, including queued and steering placements. */
   queue: readonly QueuedMessage[]
diff --git a/packages/client/runtime/src/client/sessions/history.ts b/packages/client/runtime/src/client/sessions/history.ts
index fbf7b08f3d..8609481d33 100644
--- a/packages/client/runtime/src/client/sessions/history.ts
+++ b/packages/client/runtime/src/client/sessions/history.ts
@@ -1,7 +1,7 @@
 import type { ToolSchema } from '@deepseek-ai/dsh-llm/types'
 import type { HistoryEntry } from '@deepseek-ai/dsh-client-connection/client'
 import type {
-  CodeSubCall, ConversationNode, PartialAssistant, RunningToolCall,
+  ConversationNode, PartialAssistant, RunningToolCall,
 } from './conversation.ts'
 import type { ConversationContext } from './conversation-context.ts'
 import { projectConversationHistory } from '../session-history/history-fold.ts'
@@ -34,7 +34,6 @@ export interface SessionHistoryInspection {
   interruptedNodes: readonly ConversationNode[]
   partial: PartialAssistant | null
   runningCalls: readonly RunningToolCall[]
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>
 }
 
 /**
@@ -112,9 +111,6 @@ export function createHistoryInspection(
     get runningCalls() {
       return conversationProjection().runningCalls
     },
-    get codeDispatches() {
-      return conversationProjection().codeDispatches
-    },
     get requests() {
       return requestProjection().requests
     },
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 776f4494fd..075fd686ea 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -13,7 +13,7 @@ import type {
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { SessionFace } from '../contract/session.ts'
 import type {
-  CodeSubCall, ComposerPhase, ConversationNode, ConversationSnapshot, ModelRetryNode,
+  ComposerPhase, ConversationNode, ConversationSnapshot, ModelRetryNode,
   OpenState, PromptError, QueuedMessage, RunningToolCall,
 } from './conversation.ts'
 import type { PendingInteraction } from './pending.ts'
@@ -24,6 +24,7 @@ import { Notifier } from './notifier.ts'
 import { isVisibleAssistantChunk, PartialAccumulator } from './partial.ts'
 import { ProjectionValueStore } from './projection-store.ts'
 import type { ProjectionsBaseline } from './projection-store.ts'
+import { ToolCallTree } from './tool-call-tree.ts'
 
 /** Messages requested per history page. */
 export const PAGE_MESSAGES = 50
@@ -129,11 +130,8 @@ export class Session implements SessionFace {
   private queued: QueuedMessage[] = []
   private queueRev = 0
   private queueCache: { rev: number; value: QueuedMessage[] } | null = null
-  /** `run_code` sub-dispatches by parent callId (window-derived, like openCalls). Appends
-   *  copy-on-write the per-parent array so published snapshot references never mutate. */
-  private codeDispatches = new Map<string, readonly CodeSubCall[]>()
-  private dispatchesRev = 0
-  private dispatchesCache: { rev: number; value: ReadonlyMap<string, readonly CodeSubCall[]> } | null = null
+  /** Window-derived child-call lifecycle and immutable tree projection. */
+  private readonly toolCallTree = new ToolCallTree()
   private running = false
   private address: SubagentAddress | undefined
   private parentAvailable = false
@@ -746,65 +744,10 @@ export class Session implements SessionFace {
       this.derivedRev++
       return
     }
-    // The `tool/code-dispatch-start`/`tool/code-dispatch` pair is declared by
-    // the host-side dsh-tools plugin whose types cannot enter the client
-    // program (its host Context merges collide with the client's), so this
-    // wire consumer narrows them structurally — the same posture as every
-    // other cross-wire event payload.
-    if ((event.type as string) === 'tool/code-dispatch-start') {
-      // A started sub-dispatch enters the index as a RunningToolCall — the
-      // exact shape a native in-flight call renders from — under its parent
-      // run_code callId; it never joins the surface flow.
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-      }
-      const running: CodeSubCall = {
-        callId: data.subCallId, name: data.name,
-        argsRaw: JSON.stringify(data.arguments),
-        turn: 0, step: 0, time: event.time, callView: null,
-      }
-      const siblings = this.codeDispatches.get(data.parentCallId) ?? []
-      this.codeDispatches.set(data.parentCallId, [...siblings, running])
-      this.dispatchesRev++
-      return
-    }
-    if ((event.type as string) === 'tool/code-dispatch') {
-      // Settlement replaces the running entry in place (same array position,
-      // so parallel sub-calls keep their start order) with the
-      // ToolResultNode form; a settle with no observed start (history window
-      // cut mid-pair, or a pre-start-event log) appends directly.
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-        isError: boolean
-        content: ContentBlock[]
-      }
-      const siblings = this.codeDispatches.get(data.parentCallId) ?? []
-      const at = siblings.findIndex(sub => sub.callId === data.subCallId)
-      const started = at === -1 ? undefined : siblings[at]
-      const settled: CodeSubCall = {
-        kind: 'tool-result', seq: event.seq, time: event.time,
-        callId: data.subCallId,
-        call: { name: data.name, argsRaw: JSON.stringify(data.arguments) },
-        // Duration source: the paired start's time when observed; null =
-        // unknown (settle-only window), matching the native tool-result
-        // contract so views never present a fabricated zero duration.
-        callTime: started === undefined ? null : started.time,
-        content: data.content, isError: data.isError,
-        callView: null, resultView: null,
-      }
-      this.codeDispatches.set(
-        data.parentCallId,
-        at === -1 ? [...siblings, settled] : siblings.map((sub, index) => (index === at ? settled : sub)),
-      )
-      this.dispatchesRev++
-      return
-    }
+    // These lifecycle events are declared by a host-only plugin whose Context
+    // types cannot enter the client program. ToolCallTree owns their structural
+    // wire narrowing, pairing, and nested snapshot projection.
+    if (this.toolCallTree.apply(event)) return
     switch (event.type) {
       case 'turn/start':
         this.lastStepByTurn.set(event.data.turn, 0)
@@ -834,6 +777,7 @@ export class Session implements SessionFace {
           callId: String(event.data.callId), name: event.data.name, argsRaw: event.data.arguments,
           turn: event.data.turn, step: event.data.step, time: event.time,
           callView: view?.for === 'call' ? view.view : null,
+          subCalls: [],
         })
         this.callsRev++
         return
@@ -901,7 +845,7 @@ export class Session implements SessionFace {
             call: { name: call.name, argsRaw: call.argsRaw },
             callTime: call.time,
             content: [], isError: true, error: { name: 'Interrupted', code: 'interrupted' },
-            callView: call.callView, resultView: null,
+            callView: call.callView, resultView: null, subCalls: [],
           })
           this.derivedRev++
         }
@@ -948,8 +892,7 @@ export class Session implements SessionFace {
     this.turnTimingsRev++
     this.turnEnds = new Map()
     this.turnEndsRev++
-    this.codeDispatches = new Map()
-    this.dispatchesRev++
+    this.toolCallTree.reset()
     for (let i = 0; i < this.events.length; i++) {
       const event = this.events[i]
       /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
@@ -988,22 +931,18 @@ export class Session implements SessionFace {
     if (this.pendingCache === null || this.pendingCache.rev !== this.pendingRev) {
       this.pendingCache = { rev: this.pendingRev, value: [...this.pending.values()] }
     }
-    if (this.dispatchesCache === null || this.dispatchesCache.rev !== this.dispatchesRev) {
-      this.dispatchesCache = { rev: this.dispatchesRev, value: new Map(this.codeDispatches) }
-    }
     if (this.queueCache === null || this.queueCache.rev !== this.queueRev) {
       this.queueCache = { rev: this.queueRev, value: this.queued }
     }
     const partial = this.partial?.toPartial() ?? null
     return {
       sessionId: this.sessionId,
-      nodes,
+      nodes: this.toolCallTree.projectNodes(nodes),
       turnTimings: this.turnTimingsCache.value,
       turnEnds: this.turnEndsCache.value,
       partial,
-      runningCalls: this.callsCache.value,
+      runningCalls: this.toolCallTree.projectRunningCalls(this.callsCache.value),
       pending: this.pendingCache.value,
-      codeDispatches: this.dispatchesCache.value,
       queue: this.queueCache.value,
       running: this.running,
       subagent: this.address === undefined
diff --git a/packages/client/runtime/src/client/sessions/tool-call-tree.ts b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
new file mode 100644
index 0000000000..ef25ba3da2
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
@@ -0,0 +1,171 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {
+  ConversationNode, RunningToolCall, ToolCallBlock, ToolResultNode,
+} from './conversation.ts'
+
+interface ProjectedBlock {
+  source: ToolCallBlock
+  children: readonly ToolCallBlock[]
+  value: ToolCallBlock
+}
+
+function sameBlocks(
+  left: readonly ToolCallBlock[],
+  right: readonly ToolCallBlock[],
+): boolean {
+  return left.length === right.length
+    && left.every((block, index) => block === right[index])
+}
+
+/**
+ * Owns Code Dispatch pairing and projects its private parent index into the
+ * recursive Tool call contract exposed by conversation snapshots.
+ */
+export class ToolCallTree {
+  private readonly childrenByParent = new Map<string, readonly ToolCallBlock[]>()
+  private readonly projectedByCall = new Map<string, ProjectedBlock>()
+  private revision = 0
+  private nodesCache: {
+    source: readonly ConversationNode[]
+    revision: number
+    value: readonly ConversationNode[]
+  } | null = null
+  private runningCache: {
+    source: readonly RunningToolCall[]
+    revision: number
+    value: readonly RunningToolCall[]
+  } | null = null
+
+  /** Forget all event-derived child calls before replaying a new window. */
+  reset(): void {
+    this.childrenByParent.clear()
+    this.projectedByCall.clear()
+    this.revision++
+  }
+
+  /**
+   * Fold one event when it belongs to the Code Dispatch lifecycle.
+   * @param event - Session event from the current live or history window.
+   * @returns Whether the event was consumed as a child-call lifecycle event.
+   */
+  apply(event: SessionEvent): boolean {
+    if ((event.type as string) === 'tool/code-dispatch-start') {
+      const data = event.data as unknown as {
+        parentCallId: string
+        subCallId: string
+        name: string
+        arguments: unknown
+      }
+      const running: RunningToolCall = {
+        callId: data.subCallId,
+        name: data.name,
+        argsRaw: JSON.stringify(data.arguments),
+        turn: 0,
+        step: 0,
+        time: event.time,
+        callView: null,
+        subCalls: [],
+      }
+      const siblings = this.childrenByParent.get(data.parentCallId) ?? []
+      this.childrenByParent.set(data.parentCallId, [...siblings, running])
+      this.revision++
+      return true
+    }
+    if ((event.type as string) !== 'tool/code-dispatch') return false
+    const data = event.data as unknown as {
+      parentCallId: string
+      subCallId: string
+      name: string
+      arguments: unknown
+      isError: boolean
+      content: ContentBlock[]
+    }
+    const siblings = this.childrenByParent.get(data.parentCallId) ?? []
+    const at = siblings.findIndex(sub => sub.callId === data.subCallId)
+    const started = at === -1 ? undefined : siblings[at]
+    const settled: ToolResultNode = {
+      kind: 'tool-result',
+      seq: event.seq,
+      time: event.time,
+      callId: data.subCallId,
+      call: { name: data.name, argsRaw: JSON.stringify(data.arguments) },
+      callTime: started?.time ?? null,
+      content: data.content,
+      isError: data.isError,
+      callView: null,
+      resultView: null,
+      subCalls: [],
+    }
+    this.childrenByParent.set(
+      data.parentCallId,
+      at === -1
+        ? [...siblings, settled]
+        : siblings.map((sub, index) => index === at ? settled : sub),
+    )
+    this.revision++
+    return true
+  }
+
+  /**
+   * Attach recursively projected children to all settled roots in a node list.
+   * @param nodes - Cache-stable base conversation nodes.
+   * @returns The original list when no root changed, otherwise a structurally shared list.
+   */
+  projectNodes(nodes: readonly ConversationNode[]): readonly ConversationNode[] {
+    if (this.nodesCache?.source === nodes && this.nodesCache.revision === this.revision) {
+      return this.nodesCache.value
+    }
+    let changed = false
+    const projected = nodes.map((node): ConversationNode => {
+      if (node.kind !== 'tool-result') return node
+      const value = this.projectBlock(node) as ToolResultNode
+      changed ||= value !== node
+      return value
+    })
+    const value = changed ? projected : nodes
+    this.nodesCache = { source: nodes, revision: this.revision, value }
+    return value
+  }
+
+  /**
+   * Attach recursively projected children to all running root calls.
+   * @param calls - Cache-stable base running calls.
+   * @returns The original list when no root changed, otherwise a structurally shared list.
+   */
+  projectRunningCalls(calls: readonly RunningToolCall[]): readonly RunningToolCall[] {
+    if (this.runningCache?.source === calls && this.runningCache.revision === this.revision) {
+      return this.runningCache.value
+    }
+    let changed = false
+    const projected = calls.map((call): RunningToolCall => {
+      const value = this.projectBlock(call) as RunningToolCall
+      changed ||= value !== call
+      return value
+    })
+    const value = changed ? projected : calls
+    this.runningCache = { source: calls, revision: this.revision, value }
+    return value
+  }
+
+  private projectBlock(block: ToolCallBlock): ToolCallBlock {
+    const children = this.childrenByParent.get(block.callId) ?? block.subCalls
+    const projectedChildren = children.map(child => this.projectBlock(child))
+    const childValue = sameBlocks(children, projectedChildren)
+      ? children
+      : projectedChildren
+    const cached = this.projectedByCall.get(block.callId)
+    if (cached?.source === block && sameBlocks(cached.children, childValue)) {
+      return cached.value
+    }
+    const value: ToolCallBlock = block.subCalls === childValue
+      ? block
+      : { ...block, subCalls: childValue }
+    this.projectedByCall.set(block.callId, {
+      source: block,
+      children: childValue,
+      value,
+    })
+    return value
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index ae7643f0de..25fade8633 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -103,6 +103,7 @@ function materializeNode(
         meta: event.data.meta,
         callView: call?.callView ?? null,
         resultView,
+        subCalls: [],
       }
     }
     /* v8 ignore next 2 -- defensive arm: only the four surface-eligible types
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index c288c044ee..b5400ecff9 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -1151,7 +1151,17 @@ describe('resync', () => {
 
 })
 
-describe('run_code sub-dispatch indexing', () => {
+describe('nested run_code sub-dispatches', () => {
+  const subCallsOf = (session: Session, callId: string) => {
+    const snapshot = session.getSnapshot()
+    const running = snapshot.runningCalls.find(call => call.callId === callId)
+    if (running !== undefined) return running.subCalls
+    for (const node of snapshot.nodes) {
+      if (node.kind === 'tool-result' && node.callId === callId) return node.subCalls
+    }
+    return undefined
+  }
+
   it('a start event lands as a running-shaped sub-call and its settle replaces it in place', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
@@ -1161,19 +1171,19 @@ describe('run_code sub-dispatch indexing', () => {
     feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
     feed(ev.codeDispatchStart(8, 'p1', 1, 'bash', { command: 'sleep' }))
     feed(ev.codeDispatchStart(9, 'p1', 2, 'read', { path: 'a.txt' }))
-    const live = session.getSnapshot().codeDispatches.get('p1')
+    const live = subCallsOf(session, 'p1')
     expect(live).toHaveLength(2)
     // Running shape (no 'kind'): the exact RunningToolCall form native rows use.
     expect(live?.[0]).toMatchObject({ callId: 'p1:code:1', name: 'bash', argsRaw: '{"command":"sleep"}' })
     expect(live?.[0] !== undefined && 'kind' in live[0]).toBe(false)
     // Settle out of order (parallel run): #2 first — replaces in place, keeping start order.
     feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'a.txt' }, 'alpha'))
-    const mixed = session.getSnapshot().codeDispatches.get('p1')
+    const mixed = subCallsOf(session, 'p1')
     expect(mixed?.map(sub => 'kind' in sub)).toEqual([false, true])
     expect(mixed?.[1]).toMatchObject({ callId: 'p1:code:2', content: [{ type: 'text', text: 'alpha' }] })
     // The settle carries the paired start's time as callTime (duration source).
     feed(ev.codeDispatch(11, 'p1', 1, 'bash', { command: 'sleep' }, 'done'))
-    const settled = session.getSnapshot().codeDispatches.get('p1')
+    const settled = subCallsOf(session, 'p1')
     expect(settled?.map(sub => 'kind' in sub)).toEqual([true, true])
     expect(settled?.[0]).toMatchObject({ callId: 'p1:code:1', callTime: 1_700_000_000_008 })
   })
@@ -1187,7 +1197,7 @@ describe('run_code sub-dispatch indexing', () => {
     feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'))
     feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls', description: '列目录' }, 'demo.txt'))
     feed(ev.codeDispatch(9, 'p1', 2, 'read', { path: 'a.txt' }, 'Error: ENOENT', true))
-    const subs = session.getSnapshot().codeDispatches.get('p1')
+    const subs = subCallsOf(session, 'p1')
     expect(subs).toHaveLength(2)
     expect(subs?.[0]).toMatchObject({
       kind: 'tool-result', callId: 'p1:code:1',
@@ -1205,23 +1215,29 @@ describe('run_code sub-dispatch indexing', () => {
     expect(session.getSnapshot().nodes.some(n => n.kind === 'tool-result' && n.callId.includes(':code:'))).toBe(false)
   })
 
-  it('rebuilds the same index from a history window (replay parity)', async () => {
+  it('rebuilds the same nested tree from a history window (replay parity)', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse([
       ...plainTurn(0, 0, '问', '答'),
       ev.turnStart(6, 1),
       ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'),
-      ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls' }, 'demo.txt'),
-      ev.toolResult(9, 1, 'p1', '{"done":true}'),
-      ev.turnEnd(10, 1),
+      ev.codeDispatchStart(8, 'p1', 1, 'run_code', { code: 'return tools.read({ path: "a.txt" })' }),
+      ev.codeDispatch(9, 'p1:code:1', 1, 'read', { path: 'a.txt' }, 'alpha'),
+      ev.codeDispatch(10, 'p1', 1, 'run_code', { code: 'return tools.read({ path: "a.txt" })' }, 'alpha'),
+      ev.toolResult(11, 1, 'p1', '{"done":true}'),
+      ev.turnEnd(12, 1),
     ])
     await session.open()
-    const subs = session.getSnapshot().codeDispatches.get('p1')
+    const subs = subCallsOf(session, 'p1')
     expect(subs).toHaveLength(1)
-    expect(subs?.[0]).toMatchObject({ callId: 'p1:code:1', call: { name: 'bash' } })
+    expect(subs?.[0]).toMatchObject({
+      callId: 'p1:code:1',
+      call: { name: 'run_code' },
+      subCalls: [{ callId: 'p1:code:1:code:1', call: { name: 'read' } }],
+    })
   })
 
-  it('keeps the dispatch map reference across unrelated changes and swaps it on a new dispatch', async () => {
+  it('keeps an unaffected root reference and path-copies it on a new child', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
     await session.open()
@@ -1230,13 +1246,48 @@ describe('run_code sub-dispatch indexing', () => {
     feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
     feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls' }, 'x'))
     const before = session.getSnapshot()
+    const beforeRoot = before.runningCalls.find(call => call.callId === 'p1')!
     feed(ev.chunkStart(9, 1))
     feed(ev.chunkText(10, 1, '流式'))
     const after = session.getSnapshot()
-    expect(after.codeDispatches).toBe(before.codeDispatches)
+    const afterRoot = after.runningCalls.find(call => call.callId === 'p1')!
+    expect(afterRoot).toBe(beforeRoot)
     feed(ev.codeDispatch(11, 'p1', 2, 'read', { path: 'a' }, 'y'))
-    expect(session.getSnapshot().codeDispatches).not.toBe(after.codeDispatches)
-    expect(session.getSnapshot().codeDispatches.get('p1')).toHaveLength(2)
+    const changedRoot = session.getSnapshot().runningCalls.find(call => call.callId === 'p1')!
+    expect(changedRoot).not.toBe(afterRoot)
+    expect(changedRoot.subCalls[0]).toBe(afterRoot.subCalls[0])
+    expect(changedRoot.subCalls).toHaveLength(2)
+  })
+
+  it('path-copies only the owning branch when a nested child changes', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '树', '结构'))
+    await session.open()
+    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
+    feed(ev.turnStart(6, 1))
+    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"first"}'))
+    feed(ev.toolCall(8, 1, 'p2', 'run_code', '{"code":"2","description":"second"}'))
+    feed(ev.codeDispatch(9, 'p1', 1, 'run_code', { code: 'nested' }, 'child'))
+    feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'sibling' }, 'sibling'))
+    feed(ev.codeDispatch(11, 'p2', 1, 'bash', { command: 'pwd' }, 'root two'))
+    const before = session.getSnapshot()
+    const beforeFirst = before.runningCalls.find(call => call.callId === 'p1')!
+    const beforeSecond = before.runningCalls.find(call => call.callId === 'p2')!
+    const beforeChild = beforeFirst.subCalls[0]!
+    const beforeSibling = beforeFirst.subCalls[1]!
+
+    feed(ev.codeDispatch(12, 'p1:code:1', 1, 'read', { path: 'nested' }, 'leaf'))
+    const after = session.getSnapshot()
+    const afterFirst = after.runningCalls.find(call => call.callId === 'p1')!
+    const afterSecond = after.runningCalls.find(call => call.callId === 'p2')!
+
+    expect(afterFirst).not.toBe(beforeFirst)
+    expect(afterSecond).toBe(beforeSecond)
+    expect(afterFirst.subCalls[0]).not.toBe(beforeChild)
+    expect(afterFirst.subCalls[1]).toBe(beforeSibling)
+    expect(afterFirst.subCalls[0]?.subCalls).toMatchObject([
+      { callId: 'p1:code:1:code:1', call: { name: 'read' } },
+    ])
   })
 })
 
diff --git a/packages/client/test-runtime/src/fixtures.ts b/packages/client/test-runtime/src/fixtures.ts
index 9cf025192c..ea01893346 100644
--- a/packages/client/test-runtime/src/fixtures.ts
+++ b/packages/client/test-runtime/src/fixtures.ts
@@ -50,7 +50,6 @@ export function conversationSnapshot(sessionId: SessionId): ConversationSnapshot
     turnEnds: new Map(),
     partial: null,
     runningCalls: [],
-    codeDispatches: new Map(),
     pending: [],
     queue: [],
     running: false,
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index c52a4623be..d021e2f388 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -24,7 +24,7 @@ import {
   memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
 } from 'react'
 import type {
-  CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolResultNode,
+  CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -111,6 +111,11 @@ type ChatScrollPosition = NonNullable<ReturnType<ChatViewSlotProps['chatScroll']
  *  chat view narrows once to the runtime snapshot the binding actually feeds. */
 type UseConversation = SnapshotSelectorHook<ConversationSnapshot>
 
+function treeContainsCall(block: ToolCallBlock, callId: string | undefined): boolean {
+  return callId !== undefined
+    && (block.callId === callId || block.subCalls.some(child => treeContainsCall(child, callId)))
+}
+
 function activeRetrySeq(nodes: readonly ConversationNode[], running: boolean): number | null {
   if (!running) return null
   for (let index = nodes.length - 1; index >= 0; index -= 1) {
@@ -174,7 +179,7 @@ const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selec
           toolName={node.call?.name ?? ''}
           block={node}
           openFile={openFile}
-          selectedCallId={selectedCallId}
+          selectedCallId={treeContainsCall(node, selectedCallId) ? selectedCallId : undefined}
           cwd={cwd}
           inspectCall={inspectCall}
         />
@@ -595,7 +600,7 @@ export function ChatView({
                   toolName={call.name}
                   block={call}
                   openFile={openFile}
-                  selectedCallId={selectedCallId}
+                  selectedCallId={treeContainsCall(call, selectedCallId) ? selectedCallId : undefined}
                   cwd={cwd}
                   inspectCall={inspectCall}
                 />
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index c2104c23c7..a04e9ba9e8 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -40,19 +40,27 @@ function runningMaterial(call: RunningToolCall): CallMaterial {
   return { name: call.name, argsRaw: call.argsRaw, block: call }
 }
 
+function findCall(block: ToolCallBlock, callId: string): ToolCallBlock | undefined {
+  if (block.callId === callId) return block
+  for (const child of block.subCalls) {
+    const found = findCall(child, callId)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
+
 function materialFor(s: ConversationSnapshot, callId: string): CallMaterial | null {
   for (const node of s.nodes) {
-    if (node.kind === 'tool-result' && node.callId === callId) return settledMaterial(node, callId)
+    if (node.kind !== 'tool-result') continue
+    const found = findCall(node, callId)
+    if (found !== undefined) {
+      return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
+    }
   }
-  const open = s.runningCalls.find(c => c.callId === callId)
-  if (open !== undefined) return runningMaterial(open)
-  // run_code sub-dispatches: the native call-block shapes, so a selected
-  // sub-row resolves through the same material as a native call — the
-  // settled ToolResultNode form, or the RunningToolCall form mid-flight.
-  for (const subs of s.codeDispatches.values()) {
-    for (const sub of subs) {
-      if (sub.callId !== callId) continue
-      return 'kind' in sub ? settledMaterial(sub, callId) : runningMaterial(sub)
+  for (const root of s.runningCalls) {
+    const found = findCall(root, callId)
+    if (found !== undefined) {
+      return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
     }
   }
   return null
diff --git a/packages/client/ui-conversation/tests/chat-stats.spec.tsx b/packages/client/ui-conversation/tests/chat-stats.spec.tsx
index cdb0ffa8c9..78fbf43c5e 100644
--- a/packages/client/ui-conversation/tests/chat-stats.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-stats.spec.tsx
@@ -42,7 +42,7 @@ const assistant = (seq: number, turn: number, usage?: unknown): AssistantMessage
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
@@ -86,7 +86,7 @@ describe('deriveStats', () => {
   it('ignores tool results with no call time', () => {
     const tool: ToolResultNode = {
       kind: 'tool-result', seq: 5, time: 5_000, callId: 'c', call: null, callTime: null, content: [],
-      isError: false, callView: null, resultView: null,
+      isError: false, callView: null, resultView: null, subCalls: [],
     }
     const stats = deriveStats([tool, assistant(1, 1)])
     expect(stats.steps).toBe(1)
@@ -104,7 +104,7 @@ describe('deriveStats', () => {
     }
     const tool: ToolResultNode = {
       kind: 'tool-result', seq: 5, time: 7_000, callId: 'c', call: null, callTime: 4_000, content: [],
-      isError: false, callView: null, resultView: null,
+      isError: false, callView: null, resultView: null, subCalls: [],
     }
     const stats = deriveStats([timed, untimed, tool])
     expect(stats.llmMs).toBe(2_500)
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index c828eeaeb8..38d643292e 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -37,7 +37,7 @@ const SID = 's1' as SessionId
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
@@ -88,10 +88,10 @@ const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode
   kind: 'tool-result', seq, time: seq * 1_000, callId,
   call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` },
   callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [],
 })
 const runningCall = (callId: string, name = 'bash'): RunningToolCall => ({
-  callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, time: 1_000, callView: null,
+  callId, name, argsRaw: `{"command":"cmd-${callId}"}`, turn: 2, step: 1, time: 1_000, callView: null, subCalls: [],
 })
 const command = (over: Partial<CommandNode> = {}): CommandNode => ({
   kind: 'command', seq: 5, time: 5_000, commandId: 'cmd-1' as CommandNode['commandId'],
diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
index eacd2a754a..a89f724dd4 100644
--- a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
@@ -47,7 +47,7 @@ function renderToolDetailsProbe(owners?: DetailsToolOwnerProps[]): DetailsSlotPr
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
@@ -126,18 +126,28 @@ describe('render branch tails', () => {
     expect(view.getByText('该调用不在当前窗口内')).toBeTruthy()
   })
 
-  it('DetailsPanel resolves a run_code sub-callId to its full logged args and output', () => {
+  it('DetailsPanel resolves a nested run_code leaf to its full logged args and output', () => {
     localStorage.clear()
     const snap = snapshotBase()
     const longText = 'x'.repeat(1_000)
-    snap.codeDispatches = new Map([['p1', [{
+    snap.runningCalls = [{
+      callId: 'p1', name: 'run_code', argsRaw: '{}', turn: 1, step: 1,
+      time: 7_000, callView: null, subCalls: [{
       kind: 'tool-result', seq: 8, time: 8_000, callId: 'p1:code:1',
-      call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
+      call: { name: 'run_code', argsRaw: '{"code":"return 1"}' },
       callTime: 8_000,
-      content: [{ type: 'text', text: longText }], isError: false, callView: null, resultView: null,
-    }]]])
+      content: [], isError: false, callView: null, resultView: null,
+      subCalls: [{
+        kind: 'tool-result', seq: 9, time: 9_000, callId: 'p1:code:1:code:1',
+        call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
+        callTime: 8_500,
+        content: [{ type: 'text', text: longText }], isError: false, callView: null, resultView: null,
+        subCalls: [],
+      }],
+    }],
+    }]
     const chat = createChatStore().create()
-    chat.actions.select({ turnSeq: 8, callId: 'p1:code:1', toolName: 'read' } satisfies SelectionTarget)
+    chat.actions.select({ turnSeq: 9, callId: 'p1:code:1:code:1', toolName: 'read' } satisfies SelectionTarget)
     const emptyList = createSnapshotStore<SessionListState>(
       { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined })
     const emptyWorkspaces = createSnapshotStore<WorkspaceListState>({
@@ -168,7 +178,7 @@ describe('render branch tails', () => {
     expect(view.getByTestId('tool-details-seat')).toBeTruthy()
     expect(owners).toHaveLength(1)
     expect(owners[0]?.block).toMatchObject({
-      callId: 'p1:code:1',
+      callId: 'p1:code:1:code:1',
       call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
       content: [{ type: 'text', text: longText }],
     })
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index bc276174a3..47791a6090 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -35,7 +35,7 @@ const SID = 's1' as SessionId
 
 function snapshotOf(overrides: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/input-matrix.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
index be385d41d5..f197528a2b 100644
--- a/packages/client/ui-conversation/tests/input-matrix.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
@@ -26,7 +26,7 @@ const SID = 's1' as SessionId
 /** Standard-props InputBar mount over a real shell (the composer-bar entry shape). */
 function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled?: boolean }) {
   const session = createSnapshotStore<ConversationSnapshot>({
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: over?.running ?? false, composerPhase: 'active',
     removed: over?.disabled ?? false, openState: 'open', openError: null, hasMore: false,
     loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
index 58acf3a863..c47b726b66 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
@@ -112,7 +112,7 @@ async function scopedBench(register?: (slash: SlashService) => void) {
   actx.on('slash/input-consume-token', req => shell.consumeToken(req.guard) ? true : undefined)
   const wiring = shell
   const sessionStore = createSnapshotStore<ConversationSnapshot>({
-    sessionId, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/queue-dock.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.spec.tsx
index 8c04651e77..826abaf846 100644
--- a/packages/client/ui-conversation/tests/queue-dock.spec.tsx
+++ b/packages/client/ui-conversation/tests/queue-dock.spec.tsx
@@ -32,7 +32,7 @@ function row(id: string, text: string | null, preview = text ?? '[image]'): Queu
 
 function snapshotWith(queue: QueuedMessage[]): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue, running: true, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx
index ea35284ad8..70b6d96710 100644
--- a/packages/client/ui-conversation/tests/skeleton.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx
@@ -70,7 +70,7 @@ const workspaceState = (items: readonly WorkspaceView[]): WorkspaceListState =>
 
 function conversationSnapshot(overrides: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index 845e6099c8..8a7514d644 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -37,7 +37,7 @@ const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode
   kind: 'tool-result', seq, time: seq * 1_000, callId,
   call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` },
   callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [],
 })
 const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
   ...toolResult(seq, callId, 'write'),
diff --git a/packages/client/ui-skill/tests/skill-row.spec.tsx b/packages/client/ui-skill/tests/skill-row.spec.tsx
index 05b84ceda5..431055101c 100644
--- a/packages/client/ui-skill/tests/skill-row.spec.tsx
+++ b/packages/client/ui-skill/tests/skill-row.spec.tsx
@@ -28,13 +28,14 @@ function settled(over: Partial<ToolResultNode> = {}): ToolResultNode {
     isError: false,
     callView: null,
     resultView: null,
+    subCalls: [],
     ...over,
   }
 }
 
 function running(argsRaw = '{"name":"dsh-manage-issues"}'): RunningToolCall {
   return {
-    callId: 'call-skill', name: 'skill', argsRaw, turn: 1, step: 1, time: 2_000, callView: null,
+    callId: 'call-skill', name: 'skill', argsRaw, turn: 1, step: 1, time: 2_000, callView: null, subCalls: [],
   }
 }
 
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 79a4eef640..5407a43717 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/client/ui-tool/README.md
-README.md: bf6213ebfacd8f7963463b2c443524c631c28bcd
-README.zh.md: 06a46a525eead005375bcf67794a1ceecde678bc
+README.md: bab3f92e4f6780b041cee2e682cb8ece3386ef15
+README.zh.md: 9187510fa354ba072835271d4b1153c8ee1105c0
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index bf6213ebfa..bab3f92e4f 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -4,11 +4,11 @@ English | [中文](README.zh.md)
 
 Client Tool presentation plugin. `ui-conversation` supplies one ordered root call through `conversation.chat.tool`; this package renders that root and its Code Dispatch children, then dispatches every atomic call through the keyed `tool.call.toolview` slot. Unregistered Tool names use the generic card.
 
-Business UI packages register only their wire Tool names and atomic views. They do not pair Session events, rebuild the transcript, or own root/subcall topology. The Runtime remains authoritative for call/result pairing, lifecycle, and `codeDispatches`; the conversation view remains authoritative for ChatFlow placement.
+Business UI packages register only their wire Tool names and atomic views. They do not pair Session events, rebuild the transcript, or own root/subcall topology. The Runtime remains authoritative for call/result pairing, lifecycle, and recursive `subCalls` projection; the conversation view remains authoritative for ChatFlow placement.
 
 ## Rendering contract
 
-`ToolCallTree` receives one root `ToolCallBlock`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. Through its standard session slot props it selects the Runtime-projected `codeDispatches[rootCallId]` array, then sends the root and every child through the same atomic dispatch path. The Runtime currently exposes only one Code Dispatch child level, so the renderer preserves that shape instead of inventing recursive data.
+`ToolCallTree` receives one root `ToolCallBlock` that already contains recursive `subCalls`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. It recursively walks the standard call blocks and sends the root and children at every depth through the same atomic dispatch path, without subscribing to a separate parent-to-children map.
 
 Each root and child wrapper preserves the `conversation.chat.tool` call-anchor DOM contract used for paging and selection.
 
@@ -44,6 +44,5 @@ None. The package is client-only presentation.
 
 ## Known Limitations and Deferred Work
 
-- The Runtime currently exposes one level of Code Dispatch children. The renderer sends roots and children through the same atomic path, but it does not claim an arbitrary recursive wire topology.
 - Existing first-party Tool views are initially colocated here and can move to their owning business packages independently through the keyed slot.
 - Tool copy temporarily reuses the `ui-conversation` locale namespace.
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index 06a46a525e..9187510fa3 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -4,11 +4,11 @@
 
 Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交付一个已经排好位置的 root call；本包渲染该 root 及其 Code Dispatch 子调用，并把每个原子调用通过 keyed slot `tool.call.toolview` 分发。没有注册的 Tool 名称使用通用卡片。
 
-业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和 `codeDispatches`；conversation view 继续负责 ChatFlow 位置。
+业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和递归 `subCalls` 投影；conversation view 继续负责 ChatFlow 位置。
 
 ## 渲染契约
 
-`ToolCallTree` 接收一个 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它通过标准 session slot props 选择 Runtime 投影的 `codeDispatches[rootCallId]` 数组，再让 root 与每个 child 经过同一条原子分发路径。Runtime 当前只暴露一层 Code Dispatch child，因此 renderer 保留该形状，不自行发明递归数据。
+`ToolCallTree` 接收一个已经包含递归 `subCalls` 的 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准 call block，让 root 与任意深度的 child 经过同一条原子分发路径，不再订阅独立的 parent-to-children map。
 
 每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 契约，供分页和 selection 使用。
 
@@ -44,6 +44,5 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ## 已知限制与后续工作
 
-- Runtime 当前只暴露一层 Code Dispatch 子调用。renderer 会让 root 和 child 经过同一个原子分发路径，但不宣称 wire 拓扑已经支持任意递归。
 - 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
 - Tool 文案暂时复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
index 3c71e2f4d4..278be7dacf 100644
--- a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
+++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
@@ -1,12 +1,12 @@
 /** Root/subcall Tool composition with one keyed atomic dispatch path. */
 import { memo, useMemo, type ReactNode } from 'react'
-import type { CodeSubCall, ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ToolCallOwnerProps, ToolTreeProps } from '../contract/slots.ts'
 import { GenericToolCard } from './toolviews/GenericToolCard.tsx'
 import css from './ToolCallTree.module.css'
 
-/** Resolve a Code Dispatch child's wire Tool name from either lifecycle form. */
-function subCallName(node: CodeSubCall): string {
+/** Resolve a Tool call's wire name from either lifecycle form. */
+function callName(node: ToolCallBlock): string {
   return 'kind' in node ? node.call?.name ?? '' : node.name
 }
 
@@ -44,40 +44,33 @@ const ToolCall = memo(function ToolCall({
   )
 })
 
-/**
- * Render one root Tool call and its currently supported one-level Code
- * Dispatch children. Root and children use the same atomic keyed dispatch.
- * @param props - whole-Tool owner data and the Tool-owned child-slot share.
- * @returns the Tool call tree.
- */
-export function ToolCallTree({
-  useSession, renderSlot, callId, toolName, block, selectedCallId, cwd, openFile, inspectCall, t,
-}: ToolTreeProps) {
-  const subCalls = useSession(snapshot => snapshot.codeDispatches.get(callId))
+const ToolCallBranch = memo(function ToolCallBranch({
+  renderSlot, block, selectedCallId, cwd, openFile, inspectCall, t,
+}: Pick<ToolTreeProps, 'renderSlot' | 'selectedCallId' | 'cwd' | 'openFile' | 'inspectCall' | 't'> & {
+  block: ToolCallBlock
+}) {
   return (
     <ToolCall
       renderSlot={renderSlot}
-      callId={callId}
-      toolName={toolName}
+      callId={block.callId}
+      toolName={callName(block)}
       block={block}
       openFile={openFile}
-      selected={callId === selectedCallId}
+      selected={block.callId === selectedCallId}
       cwd={cwd}
       inspectCall={inspectCall}
       t={t}
     >
-      {subCalls !== undefined && subCalls.length > 0 ? (
+      {block.subCalls.length > 0 ? (
         <div className={css.subCalls} data-subcalls>
-          {subCalls.map(node => (
-            <ToolCall
-              key={node.callId}
+          {block.subCalls.map(child => (
+            <ToolCallBranch
+              key={child.callId}
               renderSlot={renderSlot}
-              callId={node.callId}
-              toolName={subCallName(node)}
-              block={node}
-              openFile={openFile}
-              selected={node.callId === selectedCallId}
+              block={child}
+              selectedCallId={selectedCallId}
               cwd={cwd}
+              openFile={openFile}
               inspectCall={inspectCall}
               t={t}
             />
@@ -86,4 +79,26 @@ export function ToolCallTree({
       ) : null}
     </ToolCall>
   )
+})
+
+/**
+ * Render one root Tool call and its recursive children through the same
+ * atomic keyed dispatch.
+ * @param props - whole-Tool owner data and the Tool-owned child-slot share.
+ * @returns the Tool call tree.
+ */
+export function ToolCallTree({
+  renderSlot, block, selectedCallId, cwd, openFile, inspectCall, t,
+}: ToolTreeProps) {
+  return (
+    <ToolCallBranch
+      renderSlot={renderSlot}
+      block={block}
+      selectedCallId={selectedCallId}
+      cwd={cwd}
+      openFile={openFile}
+      inspectCall={inspectCall}
+      t={t}
+    />
+  )
 }
diff --git a/packages/client/ui-tool/tests/ask-question-row.spec.tsx b/packages/client/ui-tool/tests/ask-question-row.spec.tsx
index f3ab8fd3fd..e6b91823c5 100644
--- a/packages/client/ui-tool/tests/ask-question-row.spec.tsx
+++ b/packages/client/ui-tool/tests/ask-question-row.spec.tsx
@@ -24,11 +24,11 @@ const resultNode = (argsRaw: string, resultText: string | null, over?: Partial<T
   kind: 'tool-result', seq: 10, time: 2_000, callTime: 1_000, callId: 'c1',
   call: { name: 'ask_user_question', argsRaw },
   content: resultText === null ? [] : [{ type: 'text', text: resultText }],
-  isError: false, callView: null, resultView: null, ...over,
+  isError: false, callView: null, resultView: null, subCalls: [], ...over,
 })
 
 const runningCall = (argsRaw: string) =>
-  ({ callId: 'c1', name: 'ask_user_question', argsRaw, turn: 1, step: 1, time: 1_000, callView: null })
+  ({ callId: 'c1', name: 'ask_user_question', argsRaw, turn: 1, step: 1, time: 1_000, callView: null, subCalls: [] })
 
 // Standard locale seat stub mirroring the real ns → common → key chain.
 const t = makeTranslate(zh, commonZh)
diff --git a/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
index dd733ba323..9cbdfe3f1d 100644
--- a/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
+++ b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
@@ -40,7 +40,7 @@ const todoResult = (seq: number): ToolResultNode => ({
   kind: 'tool-result', seq, time: seq * 1_000, callId: `todo-${seq}`,
   call: { name: 'todo_write', argsRaw: JSON.stringify({ todos: TODOS }) },
   callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [],
 })
 
 const bashResult = (seq: number, callId: string, over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -50,6 +50,7 @@ const bashResult = (seq: number, callId: string, over?: Partial<ToolResultNode>)
   content: [{ type: 'text', text: 'total 2\ndemo.txt\n' }], isError: false,
   callView: { card: 'terminal', title: 'ls -la', description: 'List files' },
   resultView: { card: 'terminal', output: 'total 2\ndemo.txt\n', exitCode: 0 },
+  subCalls: [],
   ...over,
 })
 
diff --git a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
index 8a1df2fd7b..2bc97425e2 100644
--- a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
@@ -13,8 +13,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
 import { createSnapshotStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
-  CodeSubCall, ConversationSnapshot, RunningToolCall, SessionId, SessionListState,
-  ToolResultNode, WorkspaceListState,
+  ConversationSnapshot, RunningToolCall, SessionId, SessionListState,
+  ToolCallBlock, ToolResultNode, WorkspaceListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
@@ -48,27 +48,33 @@ const codeResult = (seq: number, callId: string): ToolResultNode => ({
   call: { name: 'run_code', argsRaw: RUN_CODE_ARGS },
   callTime: seq * 1_000 - 500,
   content: [{ type: 'text', text: 'demo.txt' }], isError: false, callView: null, resultView: null,
+  subCalls: [],
 })
 
 const runningCode = (callId: string): RunningToolCall => ({
   callId, name: 'run_code', argsRaw: RUN_CODE_ARGS, turn: 9, step: 0, time: 9_000, callView: null,
+  subCalls: [],
 })
 
-const subCall = (seq: number, parent: string, n: number, name: string, args: object, resultText: string, isError = false): CodeSubCall => ({
+const subCall = (seq: number, parent: string, n: number, name: string, args: object, resultText: string, isError = false): ToolCallBlock => ({
   kind: 'tool-result', seq, time: seq * 1_000,
   callId: `${parent}:code:${n}`,
   call: { name, argsRaw: JSON.stringify(args) },
   callTime: seq * 1_000,
   content: [{ type: 'text', text: resultText }], isError, callView: null, resultView: null,
+  subCalls: [],
 })
 
 function snapshotWith(
   nodes: ToolResultNode[],
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]>,
+  subCalls: readonly ToolCallBlock[],
   runningCalls: RunningToolCall[] = [],
 ): ConversationSnapshot {
+  const nestedNodes = nodes.map(node => ({ ...node, subCalls }))
+  const nestedRunningCalls = runningCalls.map(call => ({ ...call, subCalls }))
   return {
-    sessionId: SID, nodes, turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls, codeDispatches,
+    sessionId: SID, nodes: nestedNodes, turnTimings: new Map(), turnEnds: new Map(), partial: null,
+    runningCalls: nestedRunningCalls,
     pending: [], queue: [], running: runningCalls.length > 0, composerPhase: 'active', removed: false,
     openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
@@ -165,11 +171,11 @@ function mountApp(slots: SlotsService) {
 describe('run_code sub-calls through the real chat machinery', () => {
   it('renders the code-variant parent row with the description summary and nested sub-rows', async () => {
     const parent = 'call-64'
-    const dispatches = new Map([[parent, [
+    const subCalls = [
       subCall(11, parent, 1, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt'),
       subCall(12, parent, 2, 'mystery', { n: 1 }, 'ok'),
-    ]]])
-    const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
+    ]
+    const b = await bench(snapshotWith([codeResult(10, parent)], subCalls))
     const view = mountApp(b.slots)
 
     // Parent row: the code variant with the model-authored description.
@@ -193,12 +199,12 @@ describe('run_code sub-calls through the real chat machinery', () => {
   it('renders Cordis sub-calls with lifecycle titles over the generic variants', async () => {
     const parent = 'call-cordis'
     const code = 'return { name: "audit", apply(ctx) {} }'
-    const dispatches = new Map([[parent, [
+    const subCalls = [
       subCall(11, parent, 1, 'cordis_inspect', { what: 'temporary' }, '## Temporary Plugins'),
       subCall(12, parent, 2, 'cordis_mount', { code }, 'Temporary Plugin dyn-2 is running'),
       subCall(13, parent, 3, 'cordis_unmount', { id: 'dyn-2' }, 'Temporary Plugin dyn-2 was unmounted and removed.'),
-    ]]])
-    const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
+    ]
+    const b = await bench(snapshotWith([codeResult(10, parent)], subCalls))
     const view = mountApp(b.slots)
     const nest = view.container.querySelector('[data-subcalls]')!
 
@@ -214,7 +220,7 @@ describe('run_code sub-calls through the real chat machinery', () => {
 
   it('expanding the code row reveals the program body verbatim (shiki-tokenized)', async () => {
     const parent = 'call-64'
-    const b = await bench(snapshotWith([codeResult(10, parent)], new Map()))
+    const b = await bench(snapshotWith([codeResult(10, parent)], []))
     const view = mountApp(b.slots)
     // The code row is expandable via the whole summary row (body = the program).
     const toggle = view.container.querySelector('[data-variant="code"] [data-expandable]')
@@ -230,10 +236,10 @@ describe('run_code sub-calls through the real chat machinery', () => {
 
   it('an isError sub-call renders the error state dot exactly like a failed native row', async () => {
     const parent = 'call-64'
-    const dispatches = new Map([[parent, [
+    const subCalls = [
       subCall(11, parent, 1, 'mystery', { n: 1 }, 'Error: boom', true),
-    ]]])
-    const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
+    ]
+    const b = await bench(snapshotWith([codeResult(10, parent)], subCalls))
     const view = mountApp(b.slots)
     const nested = view.container.querySelector('[data-subcalls] [data-variant][data-state="error"]')
     expect(nested).not.toBeNull()
@@ -241,11 +247,11 @@ describe('run_code sub-calls through the real chat machinery', () => {
 
   it('a file sub-row click opens the host path; bash sub-rows do not open details', async () => {
     const parent = 'call-64'
-    const dispatches = new Map([[parent, [
+    const subCalls = [
       subCall(11, parent, 1, 'read', { path: 'notes/demo.txt' }, 'ok'),
       subCall(12, parent, 2, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt'),
-    ]]])
-    const b = await bench(snapshotWith([codeResult(10, parent)], dispatches))
+    ]
+    const b = await bench(snapshotWith([codeResult(10, parent)], subCalls))
     const view = mountApp(b.slots)
     view.getByText('notes/demo.txt').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
@@ -258,10 +264,10 @@ describe('run_code sub-calls through the real chat machinery', () => {
 
   it('a RUNNING run_code call nests its so-far dispatches under the spinner row', async () => {
     const parent = 'call-live'
-    const dispatches = new Map([[parent, [
+    const subCalls = [
       subCall(21, parent, 1, 'bash', { command: 'ls notes', description: 'List notes' }, 'demo.txt'),
-    ]]])
-    const b = await bench(snapshotWith([], dispatches, [runningCode(parent)]))
+    ]
+    const b = await bench(snapshotWith([], subCalls, [runningCode(parent)]))
     const view = mountApp(b.slots)
     const running = view.container.querySelector('[data-variant="code"][data-state="running"]')
     expect(running).not.toBeNull()
@@ -272,12 +278,11 @@ describe('run_code sub-calls through the real chat machinery', () => {
 
   it('a started-but-unsettled sub-call renders the running state exactly like a native in-flight row', async () => {
     const parent = 'call-live'
-    const runningSub: CodeSubCall = {
+    const runningSub: ToolCallBlock = {
       callId: `${parent}:code:1`, name: 'grep', argsRaw: '{"pattern":"todo"}',
-      turn: 0, step: 0, time: 21_000, callView: null,
+      turn: 0, step: 0, time: 21_000, callView: null, subCalls: [],
     }
-    const dispatches = new Map([[parent, [runningSub]]])
-    const b = await bench(snapshotWith([], dispatches, [runningCode(parent)]))
+    const b = await bench(snapshotWith([], [runningSub], [runningCode(parent)]))
     const view = mountApp(b.slots)
     // The nested row derives 'running' from the RunningToolCall shape — the
     // same data-state chrome (row sweep) a native in-flight row wears.
@@ -291,9 +296,9 @@ describe('run_code sub-calls through the real chat machinery', () => {
       kind: 'tool-result', seq: 10, time: 10_000, callId: parent,
       call: { name: 'mystery', argsRaw: '{"n":1}' },
       callTime: 9_500,
-      content: [], isError: false, callView: null, resultView: null,
+      content: [], isError: false, callView: null, resultView: null, subCalls: [],
     }
-    const b = await bench(snapshotWith([plain], new Map()))
+    const b = await bench(snapshotWith([plain], []))
     const view = mountApp(b.slots)
     expect(view.container.querySelector('[data-subcalls]')).toBeNull()
   })
diff --git a/packages/client/ui-tool/tests/coverage-tails.spec.tsx b/packages/client/ui-tool/tests/coverage-tails.spec.tsx
index 024f97ce76..ab1a0a9632 100644
--- a/packages/client/ui-tool/tests/coverage-tails.spec.tsx
+++ b/packages/client/ui-tool/tests/coverage-tails.spec.tsx
@@ -57,7 +57,7 @@ describe('Tool presentation tails', () => {
       kind: 'tool-result', seq: 2, time: 2_000, callId: 'c5',
       call: { name: 'todo_write', argsRaw: '{"note":"x"}' },
       callTime: 1_000,
-      content: [], isError: false, callView: null, resultView: null,
+      content: [], isError: false, callView: null, resultView: null, subCalls: [],
     }
     const props: GenericToolCardProps = {
       callId: 'c5', toolName: 'todo_write', block: settled, openFile: vi.fn(), t,
@@ -72,7 +72,7 @@ describe('Tool presentation tails', () => {
       kind: 'tool-result', seq: 3, time: 3_000, callId: 'c1',
       call: { name: 'bash', argsRaw: '{"command":"make build","description":"Build"}' },
       callTime: 2_000,
-      content: [], isError: false, callView: null, resultView: null,
+      content: [], isError: false, callView: null, resultView: null, subCalls: [],
     }
     const view = render(<BashRow {...bashProps(settled)} />)
     const row = view.container.querySelector('[data-sample="bash"]')!
@@ -84,13 +84,13 @@ describe('Tool presentation tails', () => {
   it('BashRow carries data-state for running and StateDots for error/stopped', () => {
     const running: RunningToolCall = {
       callId: 'c1', name: 'bash', argsRaw: '{"command":"ls","description":"List"}',
-      turn: 1, step: 1, time: 1_000, callView: null,
+      turn: 1, step: 1, time: 1_000, callView: null, subCalls: [],
     }
     const errorResult: ToolResultNode = {
       kind: 'tool-result', seq: 1, time: 1_000, callId: 'c1',
       call: { name: 'bash', argsRaw: '{"command":"boom"}' },
       callTime: 500,
-      content: [], isError: true, callView: null, resultView: null,
+      content: [], isError: true, callView: null, resultView: null, subCalls: [],
     }
     const stoppedResult: ToolResultNode = {
       ...errorResult,
diff --git a/packages/client/ui-tool/tests/diff-card.spec.tsx b/packages/client/ui-tool/tests/diff-card.spec.tsx
index a0dee040c1..7713bedaec 100644
--- a/packages/client/ui-tool/tests/diff-card.spec.tsx
+++ b/packages/client/ui-tool/tests/diff-card.spec.tsx
@@ -48,7 +48,7 @@ const resultDiff = (over?: Partial<Extract<ToolResultView, { card: 'diff' }>>):
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'edit', argsRaw: ARGS,
-  turn: 1, step: 1, time: 1_000, callView: callDiff(), ...over,
+  turn: 1, step: 1, time: 1_000, callView: callDiff(), subCalls: [], ...over,
 })
 
 const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -56,7 +56,7 @@ const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'edit', argsRaw: ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'The file notes/demo.txt has been updated successfully.' }], isError: false,
-  callView: callDiff(), resultView: resultDiff(), ...over,
+  callView: callDiff(), resultView: resultDiff(), subCalls: [], ...over,
 })
 
 describe('diffCardModel', () => {
@@ -343,7 +343,7 @@ describe('DetailsPanel diff Output section', () => {
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/read-card.spec.tsx b/packages/client/ui-tool/tests/read-card.spec.tsx
index 826bd72892..739a787a03 100644
--- a/packages/client/ui-tool/tests/read-card.spec.tsx
+++ b/packages/client/ui-tool/tests/read-card.spec.tsx
@@ -59,7 +59,7 @@ const resultRead = (over?: Partial<Extract<ToolResultView, { card: 'read' }>>):
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'read', argsRaw: ARGS,
-  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, ...over,
+  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, subCalls: [], ...over,
 })
 
 const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -67,7 +67,7 @@ const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'read', argsRaw: ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: '41: export const a = 1' }], isError: false,
-  callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, resultView: resultRead(), ...over,
+  callView: { card: 'generic', title: 'Read src/a.ts', kind: 'read' }, resultView: resultRead(), subCalls: [], ...over,
 })
 
 describe('readCardModel', () => {
@@ -289,7 +289,7 @@ describe('DetailsPanel Output section (read)', () => {
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/search-card.spec.tsx b/packages/client/ui-tool/tests/search-card.spec.tsx
index 72e25ac32b..51cab2d440 100644
--- a/packages/client/ui-tool/tests/search-card.spec.tsx
+++ b/packages/client/ui-tool/tests/search-card.spec.tsx
@@ -65,7 +65,7 @@ const resultPaths = (over?: Partial<Extract<ToolResultView, { card: 'search'; sh
 
 const runningGrep = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'grep', argsRaw: GREP_ARGS,
-  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, ...over,
+  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, subCalls: [], ...over,
 })
 
 const settledGrep = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -73,7 +73,7 @@ const settledGrep = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'grep', argsRaw: GREP_ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'a.ts\n  Line 12: const foo = 1' }], isError: false,
-  callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, resultView: resultMatches(), ...over,
+  callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, resultView: resultMatches(), subCalls: [], ...over,
 })
 
 const settledGlob = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -81,7 +81,7 @@ const settledGlob = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'glob', argsRaw: GLOB_ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'src/a.ts\nsrc/b.ts' }], isError: false,
-  callView: { card: 'generic', title: 'Glob **/*.ts', kind: 'search' }, resultView: resultPaths(), ...over,
+  callView: { card: 'generic', title: 'Glob **/*.ts', kind: 'search' }, resultView: resultPaths(), subCalls: [], ...over,
 })
 
 describe('searchCardModel', () => {
@@ -405,7 +405,7 @@ describe('DetailsPanel Output section (search)', () => {
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/terminal-card.spec.tsx b/packages/client/ui-tool/tests/terminal-card.spec.tsx
index 93a538c5c0..c9e2875a34 100644
--- a/packages/client/ui-tool/tests/terminal-card.spec.tsx
+++ b/packages/client/ui-tool/tests/terminal-card.spec.tsx
@@ -58,7 +58,7 @@ const resultTerminal = (over?: Partial<Extract<ToolResultView, { card: 'terminal
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'bash', argsRaw: ARGS,
-  turn: 1, step: 1, time: 1_000, callView: callTerminal(), ...over,
+  turn: 1, step: 1, time: 1_000, callView: callTerminal(), subCalls: [], ...over,
 })
 
 const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -66,7 +66,7 @@ const settled = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'bash', argsRaw: ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'a.ts  b.ts\nc.ts  d.ts\n' }], isError: false,
-  callView: callTerminal(), resultView: resultTerminal(), ...over,
+  callView: callTerminal(), resultView: resultTerminal(), subCalls: [], ...over,
 })
 
 describe('terminalCardModel', () => {
@@ -480,7 +480,7 @@ describe('DetailsPanel Output section', () => {
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
@@ -568,15 +568,17 @@ describe('DetailsPanel Output section', () => {
   // pins the resolution path with views injected directly, and the arm below
   // pins what the shipped path actually shows today.
   it('a run_code sub-dispatch resolves to its own terminal card once views reach it', () => {
+    const child = settled({ callId: 'c1' })
     const view = mount(snapshot({
-      codeDispatches: new Map([['p1', [settled({ callId: 'c1' })]]]),
+      runningCalls: [running({ callId: 'p1', subCalls: [child] })],
     }), target)
     expect(view.getByText('a.ts  b.ts', RAW)).toBeTruthy()
   })
 
   it('a sub-dispatch as the wire actually delivers it (no views) keeps the flattened form', () => {
+    const child = settled({ callId: 'c1', callView: null, resultView: null })
     const view = mount(snapshot({
-      codeDispatches: new Map([['p1', [settled({ callId: 'c1', callView: null, resultView: null })]]]),
+      runningCalls: [running({ callId: 'p1', subCalls: [child] })],
     }), target)
     // No terminal card: the generic path renders the result text in the Output
     // section's <pre> (the Input section has its own, hence the scoping).
@@ -588,7 +590,10 @@ describe('DetailsPanel Output section', () => {
   it('a running run_code sub-dispatch resolves through the running material', () => {
     const view = mount(snapshot({
       // The leading non-matching sub-call exercises the scan's skip.
-      codeDispatches: new Map([['p1', [running({ callId: 'other' }), running()]]]),
+      runningCalls: [running({
+        callId: 'p1',
+        subCalls: [running({ callId: 'other' }), running()],
+      })],
     }), target)
     expect(view.getByText('ls -la')).toBeTruthy()
   })
diff --git a/packages/client/ui-tool/tests/todo-row.spec.tsx b/packages/client/ui-tool/tests/todo-row.spec.tsx
index ef3253a947..db720ed056 100644
--- a/packages/client/ui-tool/tests/todo-row.spec.tsx
+++ b/packages/client/ui-tool/tests/todo-row.spec.tsx
@@ -61,7 +61,7 @@ describe('planSummary', () => {
 const resultNode = (argsRaw: string, over?: Partial<ToolResultNode>): ToolResultNode => ({
   kind: 'tool-result', seq: 10, time: 2_000, callTime: 1_000, callId: 'c1',
   call: { name: 'todo_write', argsRaw },
-  content: [], isError: false, callView: null, resultView: null, ...over,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [], ...over,
 })
 
 function rowProps(block: unknown): TodoRowProps {
@@ -106,7 +106,7 @@ describe('TodoRow', () => {
 
   it('keeps non-ok execution states visible through the shared row states', () => {
     const args = JSON.stringify({ todos: LIST })
-    const running = render(<TodoRow {...rowProps({ callId: 'c1', name: 'todo_write', argsRaw: args, turn: 1, step: 1, time: 1_000, callView: null })} />)
+    const running = render(<TodoRow {...rowProps({ callId: 'c1', name: 'todo_write', argsRaw: args, turn: 1, step: 1, time: 1_000, callView: null, subCalls: [] })} />)
     expect(running.container.querySelector('[data-state="running"]')).not.toBeNull()
     expect(running.container.querySelector('[data-state="running"] svg')).not.toBeNull()
     running.unmount()
diff --git a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
index c8c31ad365..393b9f8f46 100644
--- a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
@@ -2,7 +2,7 @@
 /** ToolCallTree-owned root/subcall markers and selection projection. */
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
-import type { CodeSubCall, ConversationSnapshot, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConversationSnapshot, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import type { ToolTreeProps } from '../src/client/contract/slots.ts'
@@ -15,15 +15,14 @@ const t: ToolTreeProps['t'] = makeTranslate(zh, commonZh)
 
 const root = (callId: string, call: ToolResultNode['call']): ToolResultNode => ({
   kind: 'tool-result', seq: 3, time: 3_000, callId, call, callTime: 2_000,
-  content: [], isError: false, callView: null, resultView: null,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [],
 })
 
 function props(
   block: ToolResultNode,
-  codeDispatches: ReadonlyMap<string, readonly CodeSubCall[]> = new Map(),
   selectedCallId?: string,
 ): ToolTreeProps {
-  const snapshot = { codeDispatches } as ConversationSnapshot
+  const snapshot = {} as ConversationSnapshot
   const useSession = ((selector: (value: ConversationSnapshot) => unknown) => selector(snapshot)) as ToolTreeProps['useSession']
   const renderSlot = ((_key: string, _owner: object, options?: { fallback?: React.ReactNode }) =>
     options?.fallback ?? null) as unknown as ToolTreeProps['renderSlot']
@@ -43,7 +42,7 @@ function props(
 describe('ToolCallTree', () => {
   it('owns the root marker, generic fallback, and selected state for a window-truncated call', () => {
     const block = root('w1', null)
-    const view = render(<ToolCallTree {...props(block, new Map(), 'w1')} />)
+    const view = render(<ToolCallTree {...props(block, 'w1')} />)
     const row = view.container.querySelector('[data-chat-call-id="w1"]')
     expect(row?.getAttribute('data-chat-anchor-key')).toBe('call:w1')
     expect(row?.getAttribute('data-selected')).toBe('true')
@@ -51,15 +50,23 @@ describe('ToolCallTree', () => {
     expect(view.getByText('w1')).toBeTruthy()
   })
 
-  it('marks a selected subcall without selecting its root', () => {
-    const block = root('parent', { name: 'run_code', argsRaw: '{"code":"return 1"}' })
-    const child: CodeSubCall = root('parent:code:1', { name: 'read', argsRaw: '{"path":"a.ts"}' })
-    const view = render(
-      <ToolCallTree {...props(block, new Map([['parent', [child]]]), child.callId)} />,
-    )
-    expect(view.container.querySelector('[data-subcalls]')?.parentElement)
-      .toBe(view.container.querySelector('[data-chat-call-id="parent"]'))
+  it('recursively renders a selected leaf without selecting its ancestors', () => {
+    const leaf = root('parent:code:1:code:1', { name: 'read', argsRaw: '{"path":"a.ts"}' })
+    const child = {
+      ...root('parent:code:1', { name: 'run_code', argsRaw: '{"code":"return 1"}' }),
+      subCalls: [leaf],
+    }
+    const block = {
+      ...root('parent', { name: 'run_code', argsRaw: '{"code":"return 1"}' }),
+      subCalls: [child],
+    }
+    const view = render(<ToolCallTree {...props(block, leaf.callId)} />)
+    const nests = view.container.querySelectorAll('[data-subcalls]')
+    expect(nests[0]?.parentElement).toBe(view.container.querySelector('[data-chat-call-id="parent"]'))
+    expect(nests[1]?.parentElement).toBe(view.container.querySelector('[data-chat-call-id="parent:code:1"]'))
     expect(view.container.querySelector('[data-chat-call-id="parent"]')?.hasAttribute('data-selected')).toBe(false)
-    expect(view.container.querySelector('[data-chat-call-id="parent:code:1"]')?.getAttribute('data-selected')).toBe('true')
+    expect(view.container.querySelector('[data-chat-call-id="parent:code:1"]')?.hasAttribute('data-selected')).toBe(false)
+    expect(view.container.querySelector('[data-chat-call-id="parent:code:1:code:1"]')?.getAttribute('data-selected')).toBe('true')
+    expect(nests).toHaveLength(2)
   })
 })
diff --git a/packages/client/ui-tool/tests/tool-row.spec.tsx b/packages/client/ui-tool/tests/tool-row.spec.tsx
index 02189e3634..9fed8e3720 100644
--- a/packages/client/ui-tool/tests/tool-row.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.spec.tsx
@@ -20,14 +20,14 @@ const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}',
-  turn: 1, step: 1, time: 1_000, callView: null, ...over,
+  turn: 1, step: 1, time: 1_000, callView: null, subCalls: [], ...over,
 })
 
 const result = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   kind: 'tool-result', seq: 10, time: 2_000, callId: 'c1',
   call: { name: 'bash', argsRaw: '{"command":"ls -la","description":"List files"}' },
   callTime: 1_000,
-  content: [], isError: false, callView: null, resultView: null, ...over,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [], ...over,
 })
 
 describe('tool-call-model', () => {
diff --git a/packages/client/ui-tool/tests/toolview-slot.spec.tsx b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
index 846f81cc45..e96c460576 100644
--- a/packages/client/ui-tool/tests/toolview-slot.spec.tsx
+++ b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
@@ -42,7 +42,7 @@ const toolResult = (seq: number, callId: string, name: string, args = '{"command
   kind: 'tool-result', seq, time: seq * 1_000, callId,
   call: { name, argsRaw: args },
   callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null,
+  content: [], isError: false, callView: null, resultView: null, subCalls: [],
 })
 
 /** Test-owned AppFrame role: declares and renders the resident conversation area. */
diff --git a/packages/client/ui-tool/tests/web-card.spec.tsx b/packages/client/ui-tool/tests/web-card.spec.tsx
index b8a5a4e06c..7856ae9d6f 100644
--- a/packages/client/ui-tool/tests/web-card.spec.tsx
+++ b/packages/client/ui-tool/tests/web-card.spec.tsx
@@ -56,7 +56,7 @@ const resultFetch = (over?: Partial<Extract<ToolResultView, { card: 'web'; kind:
 
 const runningSearch = (over?: Partial<RunningToolCall>): RunningToolCall => ({
   callId: 'c1', name: 'web_search', argsRaw: SEARCH_ARGS,
-  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Search', kind: 'search' }, ...over,
+  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Search', kind: 'search' }, subCalls: [], ...over,
 })
 
 const settledSearch = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -64,7 +64,7 @@ const settledSearch = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'web_search', argsRaw: SEARCH_ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'search text' }], isError: false,
-  callView: { card: 'generic', title: 'Search', kind: 'search' }, resultView: resultSearch(), ...over,
+  callView: { card: 'generic', title: 'Search', kind: 'search' }, resultView: resultSearch(), subCalls: [], ...over,
 })
 
 const settledFetch = (over?: Partial<ToolResultNode>): ToolResultNode => ({
@@ -72,7 +72,7 @@ const settledFetch = (over?: Partial<ToolResultNode>): ToolResultNode => ({
   call: { name: 'web_fetch', argsRaw: FETCH_ARGS },
   callTime: 1_000,
   content: [{ type: 'text', text: 'fetch body' }], isError: false,
-  callView: { card: 'generic', title: 'Fetch', kind: 'fetch' }, resultView: resultFetch(), ...over,
+  callView: { card: 'generic', title: 'Fetch', kind: 'fetch' }, resultView: resultFetch(), subCalls: [], ...over,
 })
 
 describe('webCardModel', () => {
@@ -235,7 +235,7 @@ describe('DetailsPanel web Output section', () => {
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [], codeDispatches: new Map(),
+      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
index 81b4f9d7f0..ff63b860b9 100644
--- a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
+++ b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx
@@ -211,7 +211,6 @@ export function TrajectoryView({
   const nodes = inspection.eventNodes
   const partial = inspection.partial
   const runningCalls = inspection.runningCalls
-  const codeDispatches = inspection.codeDispatches
   const loadHistoryTailRef = useRef(loadHistoryTail)
   loadHistoryTailRef.current = loadHistoryTail
   const historyControllerRef = useRef<AbortController | null>(null)
@@ -366,12 +365,11 @@ export function TrajectoryView({
       runningCalls,
       requests: selectedRequests,
       callSchemas,
-      codeDispatches,
     })
     return { turns, lastIndex: lastCellIndex(turns) }
   }, [
     selectedNodes, partialTurn, partialStep,
-    runningCalls, selectedRequests, callSchemas, codeDispatches,
+    runningCalls, selectedRequests, callSchemas,
   ])
   const timelinePartialSignature = partialStructureSignature(partial)
   const timelinePartial = useMemo<ConversationSnapshot['partial']>(() => partial === null
diff --git a/packages/client/ui-trajectory/src/client/layout.ts b/packages/client/ui-trajectory/src/client/layout.ts
index 273b4fc32a..6853199aa1 100644
--- a/packages/client/ui-trajectory/src/client/layout.ts
+++ b/packages/client/ui-trajectory/src/client/layout.ts
@@ -5,11 +5,11 @@
 import type {
   AssistantBlock,
   AssistantMessageNode,
-  CodeSubCall,
   ConversationSnapshot,
   RequestInspectionSnapshot,
   RequestPromptChange,
   RequestView,
+  ToolCallBlock,
   ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { extractMarkdownPlainText } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -39,8 +39,6 @@ export interface TrajectoryLayoutInput {
   runningCalls: ConversationSnapshot['runningCalls']
   requests?: readonly RequestView[]
   callSchemas?: RequestInspectionSnapshot['callSchemas']
-  /** run_code sub-dispatches by parent callId (sub-cells nest under the parent Tool cell). */
-  codeDispatches: ConversationSnapshot['codeDispatches']
 }
 
 interface UsageLike {
@@ -57,6 +55,7 @@ interface LaidCell {
   absTime: number | null
   toolName?: string
   callId?: string
+  subCalls?: readonly ToolCallBlock[]
 }
 
 interface LaidGroup {
@@ -131,9 +130,11 @@ function inputCellDetail(node: InputNode): Pick<
  */
 export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly TrajectoryTurnModel[] {
   const {
-    nodes, partial, runningCalls, requests = [], callSchemas, codeDispatches,
+    nodes, partial, runningCalls, requests = [], callSchemas,
   } = input
   const resultByCall = indexResults(nodes)
+  const callById = new Map<string, ToolCallBlock>(resultByCall)
+  for (const call of runningCalls) callById.set(call.callId, call)
   const emittedCallIds = indexAssistantCallIds(nodes)
   const callStartById = new Map<string, number>()
   for (const result of resultByCall.values()) {
@@ -344,8 +345,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
     }
     if (node.kind === 'assistant') {
       const laidList = withSubCalls(
-        expandAssistant(node, index + 1, prevAbsTime, resultByCall, callStartById),
-        codeDispatches,
+        expandAssistant(node, index + 1, prevAbsTime, resultByCall, callStartById, callById),
       )
       if (node.step > 0) pushStep(node.turn, node.step, laidList)
       else for (const laid of laidList) pushMessage(node.turn, laid)
@@ -381,6 +381,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
           absTime: finiteTime(node.callTime ?? node.time),
           ...(toolName !== undefined ? { toolName } : {}),
           callId: node.callId,
+          subCalls: node.subCalls,
           cell: {
             index: ++index,
             kind: 'tool',
@@ -398,7 +399,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
             startedAt: finiteTime(node.callTime),
           },
         }]
-        for (const laid of expandSubCalls(codeDispatches.get(node.callId), index)) {
+        for (const laid of expandSubCalls(node.subCalls, index)) {
           laidList.push(laid)
           index = laid.cell.index
         }
@@ -413,14 +414,15 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
       kind: 'assistant', seq: Number.MAX_SAFE_INTEGER, time: 0,
       turn: partial.turn, step: partial.step, blocks: partial.blocks,
     }
-    const laidList = expandAssistant(
+    const laidList = withSubCalls(expandAssistant(
       fake,
       index + 1,
       prevAbsTime,
       resultByCall,
       callStartById,
+      callById,
       { streaming: true },
-    )
+    ))
     if (partial.step > 0) pushStep(partial.turn, partial.step, laidList)
     else for (const laid of laidList) pushMessage(partial.turn, laid)
     const last = laidList[laidList.length - 1]
@@ -434,6 +436,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
       absTime: null,
       toolName: call.name,
       callId: call.callId,
+      subCalls: call.subCalls,
       cell: {
         index: ++index,
         kind: 'tool',
@@ -444,7 +447,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
         startedAt: finiteTime(call.time),
       },
     }]
-    for (const laid of expandSubCalls(codeDispatches.get(call.callId), index)) {
+    for (const laid of expandSubCalls(call.subCalls, index)) {
       laidList.push(laid)
       index = laid.cell.index
     }
@@ -491,7 +494,6 @@ export function appendTrajectoryPartialLayout(
     nodes: [],
     partial,
     runningCalls: [],
-    codeDispatches: new Map(),
   }).at(0)
   if (partialTurn === undefined) return turns
   const streamed: TrajectoryTurnModel = {
@@ -622,6 +624,7 @@ function expandAssistant(
   prevAbsTime: number | null,
   results: Map<string, ToolResultNode>,
   callStarts: ReadonlyMap<string, number>,
+  calls: ReadonlyMap<string, ToolCallBlock>,
   opts?: { streaming?: boolean },
 ): LaidCell[] {
   if (opts?.streaming === true && node.blocks.length === 0) return []
@@ -677,10 +680,12 @@ function expandAssistant(
       ? null
       : durationSeconds(result.time, result.callTime)
     const callAbs = finiteTime(callStarts.get(block.callId))
+    const call = calls.get(block.callId)
     out.push({
       absTime: callAbs,
       toolName: block.name,
       callId: block.callId,
+      ...(call === undefined ? {} : { subCalls: call.subCalls }),
       cell: {
         index: ++index, kind: 'tool',
         text: summarizeCall(block.name, block.argsRaw),
@@ -883,15 +888,14 @@ function collectCallIds(
 
 
 
-/** Interleave each tool cell's run_code sub-dispatch cells right after it, reindexing followers. */
-function withSubCalls(laidList: LaidCell[], codeDispatches: ConversationSnapshot['codeDispatches']): LaidCell[] {
-  if (codeDispatches.size === 0) return laidList
+/** Interleave each tool cell's nested child calls right after it, reindexing followers. */
+function withSubCalls(laidList: LaidCell[]): LaidCell[] {
+  if (!laidList.some(laid => laid.subCalls !== undefined && laid.subCalls.length > 0)) return laidList
   const out: LaidCell[] = []
   let index = laidList[0] !== undefined ? laidList[0].cell.index - 1 : 0
   for (const laid of laidList) {
     out.push({ ...laid, cell: { ...laid.cell, index: ++index } })
-    if (laid.callId === undefined) continue
-    for (const sub of expandSubCalls(codeDispatches.get(laid.callId), index)) {
+    for (const sub of expandSubCalls(laid.subCalls, index)) {
       out.push(sub)
       index = sub.cell.index
     }
@@ -901,7 +905,7 @@ function withSubCalls(laidList: LaidCell[], codeDispatches: ConversationSnapshot
 
 /** Sub-dispatch cells for one run_code parent, in start order (running = null duration). */
 function expandSubCalls(
-  subs: readonly CodeSubCall[] | undefined,
+  subs: readonly ToolCallBlock[] | undefined,
   startIndex: number,
 ): LaidCell[] {
   if (subs === undefined || subs.length === 0) return []
@@ -909,10 +913,11 @@ function expandSubCalls(
   let index = startIndex
   for (const sub of subs) {
     const settled = 'kind' in sub
-    out.push({
+    const laid: LaidCell = {
       absTime: settled ? finiteTime(sub.callTime ?? sub.time) : finiteTime(sub.time),
       toolName: settled ? sub.call?.name ?? sub.callId : sub.name,
       callId: sub.callId,
+      subCalls: sub.subCalls,
       cell: {
         index: ++index,
         kind: 'subtool',
@@ -938,7 +943,12 @@ function expandSubCalls(
           ? finiteTime(sub.callTime)
           : finiteTime(sub.time),
       },
-    })
+    }
+    out.push(laid)
+    for (const child of expandSubCalls(sub.subCalls, index)) {
+      out.push(child)
+      index = child.cell.index
+    }
   }
   return out
 }
diff --git a/packages/client/ui-trajectory/tests/layout.spec.tsx b/packages/client/ui-trajectory/tests/layout.spec.tsx
index 544199e345..4c49b07907 100644
--- a/packages/client/ui-trajectory/tests/layout.spec.tsx
+++ b/packages/client/ui-trajectory/tests/layout.spec.tsx
@@ -74,7 +74,7 @@ describe('deriveTrajectoryLayout', () => {
         content: [{ type: 'text', text: 'a.txt' }], isError: false, callView: null, resultView: null,
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     expect(turns).toHaveLength(1)
     expect(turns[0]?.turn).toBe(1)
     const kinds = turns[0]?.groups.flatMap(g => g.cells.map(c => c.kind))
@@ -90,12 +90,11 @@ describe('deriveTrajectoryLayout', () => {
 
   it('adds runningCalls not already present and leaves their time blank', () => {
     const turns = deriveTrajectoryLayout({
-      codeDispatches: new Map(),
       nodes: [],
       partial: null,
       runningCalls: [{
         callId: 'r1', name: 'bash', argsRaw: '{"command":"pwd"}',
-        turn: 1, step: 2, time: 9_000, callView: null,
+        turn: 1, step: 2, time: 9_000, callView: null, subCalls: [],
       }],
     })
     expect(turns[0]?.groups.map(g => g.title)).toEqual(['Step 2'])
@@ -119,7 +118,6 @@ describe('deriveTrajectoryLayout', () => {
       startedAt: 3_000, completedAt: null, status: 'running',
     } as unknown as RequestView
     const base = deriveTrajectoryLayout({
-      codeDispatches: new Map(),
       nodes,
       partial: { ...partial, blocks: [] },
       requests: [request],
@@ -152,12 +150,11 @@ describe('deriveTrajectoryLayout', () => {
       }],
     }
     const base = deriveTrajectoryLayout({
-      codeDispatches: new Map(),
       nodes: [],
       partial: { ...partial, blocks: [] },
       runningCalls: [{
         callId: 'c1', name: 'bash', argsRaw: '{"command":"pwd"}',
-        turn: 1, step: 1, time: 9_000, callView: null,
+        turn: 1, step: 1, time: 9_000, callView: null, subCalls: [],
       }],
     })
 
@@ -180,7 +177,7 @@ describe('deriveTrajectoryLayout', () => {
         usage: { inputTokens: 1, outputTokens: 2, reasoningTokens: 3 },
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     const cells = turns[0]?.groups.flatMap(g => g.cells) ?? []
     expect(cells.find(c => c.kind === 'message')?.timeSeconds).toBeNull()
     expect(turns[0]?.groups.find(g => g.title === 'Step 1')?.description).toBeUndefined()
@@ -206,7 +203,7 @@ describe('deriveTrajectoryLayout', () => {
         content: [], isError: false, callView: null, resultView: null,
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     expect(turns[0]?.groups[0]?.description).toBe('3,000 ms bash×2')
   })
 
@@ -223,7 +220,7 @@ describe('deriveTrajectoryLayout', () => {
         blocks: [{ kind: 'text', text: 'ok2' }],
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     expect(turns.map(t => t.turn)).toEqual([1, 2])
     expect(turns[0]?.groups.flatMap(g => g.cells.map(c => c.text))).toEqual(['first', 'ok1'])
     expect(turns[1]?.groups.flatMap(g => g.cells.map(c => c.text))).toEqual(['second', 'ok2'])
@@ -254,7 +251,6 @@ describe('deriveTrajectoryLayout', () => {
     }
 
     const turns = deriveTrajectoryLayout({
-      codeDispatches: new Map(),
       nodes,
       partial: null,
       runningCalls: [],
@@ -280,7 +276,7 @@ describe('deriveTrajectoryLayout', () => {
         usage: { inputTokens: 11, outputTokens: 22, reasoningTokens: 3 },
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     const message = turns[0]?.groups.flatMap(g => g.cells).find(c => c.kind === 'message')
     expect(message).toMatchObject({
       text: '…', input: 11, output: 22, think: 3,
@@ -295,7 +291,7 @@ describe('deriveTrajectoryLayout', () => {
     }] as unknown as ConversationSnapshot['nodes']
 
     const turns = deriveTrajectoryLayout({
-      codeDispatches: new Map(), nodes, partial: null, runningCalls: [],
+      nodes, partial: null, runningCalls: [],
     })
     const message = turns[0]?.groups.flatMap(group => group.cells)
       .find(cell => cell.kind === 'message')
@@ -333,7 +329,7 @@ describe('deriveTrajectoryLayout', () => {
         blocks: [{ kind: 'text', text: 'done' }],
       },
     ] as unknown as ConversationSnapshot['nodes']
-    const turns = deriveTrajectoryLayout({ codeDispatches: new Map(), nodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes, partial: null, runningCalls: [] })
     const cells = turns[0]?.groups.flatMap(g => g.cells) ?? []
     const message = cells.find(c => c.kind === 'message' && c.text === 'done')
     // From the compaction marker at 9.5s, not from context at 9s or the earlier surfaces.
@@ -352,7 +348,7 @@ describe('deriveTrajectoryLayout', () => {
       },
     ] as unknown as ConversationSnapshot['nodes']
     const turns = deriveTrajectoryLayout({
-      codeDispatches: new Map(), nodes, partial: null, runningCalls: [],
+      nodes, partial: null, runningCalls: [],
     })
     const message = turns[0]?.groups.flatMap(group => group.cells)
       .find(cell => cell.kind === 'message')
@@ -372,6 +368,7 @@ describe('run_code sub-dispatch cells', () => {
       kind: 'tool-result', seq: 3, time: 9_000, callId: 'p1',
       call: { name: 'run_code', argsRaw: '{"code":"…","description":"批量读取"}' }, callTime: 6_200,
       content: [{ type: 'text', text: 'done' }], isError: false, callView: null, resultView: null,
+      subCalls: [],
     },
   ] as unknown as ConversationSnapshot['nodes']
 
@@ -380,14 +377,18 @@ describe('run_code sub-dispatch cells', () => {
     callId: `p1:code:${n}`,
     call: { name, argsRaw: '{"x":1}' }, callTime: start,
     content: [{ type: 'text' as const, text: 'ok' }], isError: false, callView: null, resultView: null,
+    subCalls: [],
   })
 
+  const withSubCalls = (subCalls: readonly ReturnType<typeof settledSub>[] | readonly object[]) =>
+    runCodeNodes.map(node => node.kind === 'tool-result' ? { ...node, subCalls } : node) as ConversationSnapshot['nodes']
+
   it('nests settled sub-cells after their parent Tool cell with real durations', () => {
-    const codeDispatches = new Map([['p1', [
+    const subCalls = [
       settledSub(1, 'bash', 6_300, 7_300),
       settledSub(2, 'read', 7_300, 7_800),
-    ]]]) as unknown as ConversationSnapshot['codeDispatches']
-    const turns = deriveTrajectoryLayout({ codeDispatches, nodes: runCodeNodes, partial: null, runningCalls: [] })
+    ]
+    const turns = deriveTrajectoryLayout({ nodes: withSubCalls(subCalls), partial: null, runningCalls: [] })
     const cells = turns[0]!.groups.flatMap(g => g.cells)
     expect(cells.map(c => c.kind)).toEqual(['message', 'tool', 'subtool', 'subtool'])
     expect(cells[0]?.text).toBe('Tool call only')
@@ -400,11 +401,29 @@ describe('run_code sub-dispatch cells', () => {
   it('a running (unsettled) sub-call renders a subtool cell with blank time', () => {
     const running = {
       callId: 'p1:code:1', name: 'grep', argsRaw: '{"pattern":"x"}',
-      turn: 0, step: 0, time: 6_400, callView: null,
+      turn: 0, step: 0, time: 6_400, callView: null, subCalls: [],
     }
-    const codeDispatches = new Map([['p1', [running]]]) as unknown as ConversationSnapshot['codeDispatches']
-    const turns = deriveTrajectoryLayout({ codeDispatches, nodes: runCodeNodes, partial: null, runningCalls: [] })
+    const turns = deriveTrajectoryLayout({ nodes: withSubCalls([running]), partial: null, runningCalls: [] })
     const sub = turns[0]!.groups.flatMap(g => g.cells).find(c => c.kind === 'subtool')
     expect(sub).toMatchObject({ text: 'grep · {"pattern":"x"}', timeSeconds: null })
   })
+
+  it('recursively flattens nested child calls immediately after their parent', () => {
+    const leaf = {
+      ...settledSub(2, 'read', 7_300, 7_800),
+      callId: 'p1:code:1:code:1',
+    }
+    const child = {
+      ...settledSub(1, 'run_code', 6_300, 8_000),
+      subCalls: [leaf],
+    }
+    const turns = deriveTrajectoryLayout({ nodes: withSubCalls([child]), partial: null, runningCalls: [] })
+    const cells = turns[0]!.groups.flatMap(group => group.cells)
+    expect(cells.map(cell => cell.kind)).toEqual(['message', 'tool', 'subtool', 'subtool'])
+    expect(cells.slice(2).map(cell => cell.callId)).toEqual([
+      'p1:code:1',
+      'p1:code:1:code:1',
+    ])
+    expect(cells.map(cell => cell.index)).toEqual([1, 2, 3, 4])
+  })
 })
diff --git a/packages/client/ui-trajectory/tests/views.spec.tsx b/packages/client/ui-trajectory/tests/views.spec.tsx
index 56a9ee90cf..2a0ec68ec0 100644
--- a/packages/client/ui-trajectory/tests/views.spec.tsx
+++ b/packages/client/ui-trajectory/tests/views.spec.tsx
@@ -82,7 +82,6 @@ function historySnapshot(
       interruptedNodes: [],
       partial: null,
       runningCalls: [],
-      codeDispatches: new Map(),
       ...inspection,
     },
   }
@@ -115,7 +114,7 @@ function standaloneDuration(): Pick<
 function fakeSession(nodes: ConversationSnapshot['nodes']) {
   const store = createSnapshotStore({
     nodes, pending: [], partial: null,
-    runningCalls: [] as ConversationSnapshot['runningCalls'], codeDispatches: new Map(),
+    runningCalls: [] as ConversationSnapshot['runningCalls'],
   })
   return { store, useSession: bindSnapshotSelector(store) as unknown as UseSession<ConversationSnapshot> }
 }
@@ -186,7 +185,7 @@ function mount(slots: SlotsService, nodes: ConversationSnapshot['nodes'] = NODES
     running: false, removed: false, promptError: null, nodes,
     pending: [],
     openState: 'open' as const, hasMore: true, loadingOlder: false,
-    partial: null, runningCalls: [] as ConversationSnapshot['runningCalls'], codeDispatches: new Map(),
+    partial: null, runningCalls: [] as ConversationSnapshot['runningCalls'],
   })
   const useSession = bindSnapshotSelector(sessionSnapshot) as unknown as UseSession<ConversationSnapshot>
   const chat = createChatStore().create()

From 091b9931984581278e2b8f28547dd912026b68cd Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:46:50 +0800
Subject: [PATCH 262/516] fix(client): harden nested Tool call projection

---
 ...7-19-gui-web-client-architecture.i18n.yaml |  4 +-
 .../2026-07-19-gui-web-client-architecture.md |  2 +-
 ...26-07-19-gui-web-client-architecture.zh.md |  2 +-
 ...7-26-code-mode-chat-subcall-rows.i18n.yaml |  4 +-
 .../2026-07-26-code-mode-chat-subcall-rows.md | 10 +--
 ...26-07-26-code-mode-chat-subcall-rows.zh.md | 10 +--
 ...code-mode-live-parallel-dispatch.i18n.yaml |  4 +-
 ...-07-26-code-mode-live-parallel-dispatch.md |  2 +-
 ...-26-code-mode-live-parallel-dispatch.zh.md |  2 +-
 .../src/client/sessions/tool-call-tree.ts     | 43 +++++++-----
 .../client/runtime/tests/history-fold.spec.ts | 31 +++++++++
 .../runtime/tests/tool-call-tree.spec.ts      | 65 +++++++++++++++++++
 .../tests/gate-branch-tails.spec.tsx          | 22 +++----
 packages/client/ui-tool/README.i18n.yaml      |  4 +-
 packages/client/ui-tool/README.md             |  1 +
 packages/client/ui-tool/README.zh.md          |  1 +
 .../ui-tool/tests/chat-code-subcalls.spec.tsx |  4 +-
 .../client/ui-trajectory/src/client/layout.ts |  1 -
 18 files changed, 160 insertions(+), 52 deletions(-)
 create mode 100644 packages/client/runtime/tests/tool-call-tree.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index 2357aa30f2..d3bbc7da9d 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: cba029ea74e89b277f9079ebb3765deeeb105b47
-2026-07-19-gui-web-client-architecture.zh.md: f700cc04fe1479d43957456c14b3abb4014d99c5
+2026-07-19-gui-web-client-architecture.md: e25d002b92df2016faf4073108aa905b65a1b115
+2026-07-19-gui-web-client-architecture.zh.md: cf31220aad61e4845f7fe90b73bf5da4432e53de
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index cba029ea74..e25d002b92 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -44,7 +44,7 @@ Implementation homes: registry core and the props-share types in `packages/clien
 
 A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer install seam), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
-There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: ui-conversation places each ordered root call into the single `'conversation.chat.tool'` seat without interpreting Tool names or Code Dispatch topology; ui-tool selects `codeDispatches[rootCallId]` from the Runtime snapshot, renders that root/child shape, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and both roots and children dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
+There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: Runtime projects Code Dispatch topology into each root's recursive `subCalls`; ui-conversation places that ordered root into the single `'conversation.chat.tool'` seat without interpreting Tool names or topology; ui-tool renders the supplied tree and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
 
 **Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport).
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index f700cc04fe..cf31220aad 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -44,7 +44,7 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-
 
 服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：ui-conversation 把每个已排序 root call 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或 Code Dispatch 拓扑；ui-tool 从 Runtime snapshot 选择 `codeDispatches[rootCallId]`、渲染 root/child 形状，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与 child 都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
+slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：运行时把 Code Dispatch 拓扑投影进每个 root 递归的 `subCalls`；ui-conversation 把这个已排序 root 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或拓扑；ui-tool 渲染传入的树，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
 
 **scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml
index d550ad1fb6..390144b4bd 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.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 .agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
-2026-07-26-code-mode-chat-subcall-rows.md: dc09e8fda9dbfb156b6218dec67584ee7bfead75
-2026-07-26-code-mode-chat-subcall-rows.zh.md: d445ddac4704fb940550d27ef7400e79d859393b
+2026-07-26-code-mode-chat-subcall-rows.md: 40b4b8fd8c5cea8e9aea01731d7eceff692db188
+2026-07-26-code-mode-chat-subcall-rows.zh.md: 9981fded054f663dd539660ed2a2eca68a9d3138
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
index dc09e8fda9..40b4b8fd8c 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
@@ -12,12 +12,12 @@ With Code Mode enabled, the chat view showed one opaque `run_code` row: raw prog
 
 ## Decision
 
-**Sub-calls are `ToolResultNode`s indexed off the surface flow, rendered through the same keyed slot as native rows, nested always-visible under their parent.**
+**Sub-calls are standard Tool call blocks attached recursively to their parent outside the surface flow, rendered through the same keyed slot as native rows, and always visible under their parent.**
 
-- **Data layer**: `Session.applyEventSideEffects` folds each in-window `tool/code-dispatch` into `ConversationSnapshot.codeDispatches: ReadonlyMap<parentCallId, readonly CodeSubCall[]>`, where `CodeSubCall` IS `ToolResultNode` (the sub-call id as `callId`, the logged args JSON-stringified into `call.argsRaw`, the full logged `content`/`isError`). Live mux frames and history replay build the identical index (`rebuildDerivedFromWindow` clears and re-derives; copy-on-write per-parent arrays keep snapshot references memo-stable). Sub-calls never join `nodes` — the surface flow remains exactly the model-visible turn structure. The event is narrowed structurally at the wire-consumer boundary (dsh-tools' host types cannot enter the client program — the host/client `Context` merges collide), the same posture as every cross-wire payload.
-- **Render layer**: `ChatView` passes each parent and its indexed children through the whole-Tool `'conversation.chat.tool'` seat. ui-tool's `ToolCallTree` renders the parent followed by a `[data-subcalls]` nest, and every atomic call dispatches through the same `'tool.call.toolview'` keyed slot with `entryKey = Tool name` and the same `GenericToolCard` fallback. A keyed registration therefore takes over child and top-level calls without registration changes. Running parents (`runningCalls`) receive their accumulated dispatches through the same owner payload, so child rows stream in during the run.
+- **Data layer**: Runtime's `ToolCallTree` folds in-window `tool/code-dispatch-start` and `tool/code-dispatch` events into a private per-parent index, then projects running and settled children onto recursive `ToolCallBlock.subCalls`. Live Session projection and `projectConversationHistory` share that fold; copy-on-write parent arrays and path-copy projection keep unrelated roots and siblings reference-stable. Sub-calls never join `nodes` — the surface flow remains exactly the model-visible turn structure. The events are narrowed structurally at the wire-consumer boundary, which also rejects cyclic parent relationships (dsh-tools' host types cannot enter the client program because the host/client `Context` merges collide).
+- **Render layer**: `ChatView` passes each parent with its recursive children through the whole-Tool `'conversation.chat.tool'` seat. ui-tool's `ToolCallTree` renders the parent followed by `[data-subcalls]` nests, and every atomic call dispatches through the same `'tool.call.toolview'` keyed slot with `entryKey = Tool name` and the same `GenericToolCard` fallback. A keyed registration therefore takes over descendant and top-level calls without registration changes. Running parents (`runningCalls`) receive accumulated dispatches in the same recursive block, so child rows stream in during the run.
 - **`run_code` presentation**: a new `code` row variant (classifier `run_code → code`, `Code` title, `IconCodeOutline16`) summarizes with the model-authored `description` and expands to the program itself (monospace on the markdown code-block fill) rather than the args JSON envelope.
-- **Details panel**: `materialFor` falls through nodes → runningCalls → the dispatch index, so a selected sub-callId resolves to full args and complete output through the identical rendering path as a native settled call.
+- **Details panel**: `materialFor` recursively searches `nodes` and `runningCalls`, so a selected descendant callId resolves to full args and complete output through the identical rendering path as a native settled call.
 
 ## Alternatives considered
 
@@ -29,4 +29,4 @@ With Code Mode enabled, the chat view showed one opaque `run_code` row: raw prog
 
 ## Consequences
 
-Custom toolview registrations apply to sub-calls for free — and deliberately: there is no per-registration opt-out short of the component reading its own context, which no current consumer needs. Selection highlighting reaches nested rows through the same `selectedCallId` channel (group membership tests both levels). Trajectory/waterfall still render `run_code` as a single row — their sub-call spans are deferred to the PR that adds dispatch timing (start/end events), without which a waterfall span would be a lie. Fixture turn 64 (`?fixture`) plus the `code-mode-round` browser e2e (recorded real round, keyless replay) pin the full surface; the jsdom suites pin the slot dispatch, error states, details resolution, and index reference stability.
+Custom toolview registrations apply to sub-calls for free — and deliberately: there is no per-registration opt-out short of the component reading its own context, which no current consumer needs. Selection highlighting reaches nested rows through the same `selectedCallId` channel (group membership searches the whole tree). Trajectory/waterfall still render `run_code` as a single row — their sub-call spans are deferred to the PR that adds dispatch timing (start/end events), without which a waterfall span would be a lie. Fixture turn 64 (`?fixture`) plus the `code-mode-round` browser e2e (recorded real round, keyless replay) pin the full surface; the jsdom and Runtime suites pin slot dispatch, error states, recursive details resolution, history projection, and reference-stable path copying.
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
index d445ddac47..9981fded05 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
@@ -12,12 +12,12 @@ Status: implemented
 
 ## 决策
 
-**子调用在界面流之外单独索引为 `ToolResultNode`，经由与原生行相同的 keyed slot 渲染，以始终可见的方式嵌套在父行之下。**
+**子调用是在 surface 流之外递归附着到父级的标准 Tool 调用块，经由与原生行相同的 keyed slot 渲染，并始终显示在父级之下。**
 
-- **数据层**：`Session.applyEventSideEffects` 把窗口内的每条 `tool/code-dispatch` 折入 `ConversationSnapshot.codeDispatches: ReadonlyMap<parentCallId, readonly CodeSubCall[]>`，其中 `CodeSubCall` 本身就是 `ToolResultNode`（子调用 id 充当 `callId`，已记录的参数经 JSON 字符串化写入 `call.argsRaw`，完整记录的 `content`/`isError` 原样携带）。实时多路复用帧与历史回放构建出同一份索引（`rebuildDerivedFromWindow` 先清空再重新推导；逐父级的写时复制（copy-on-write）数组保持快照引用稳定，便于 memo 化）。子调用永不进入 `nodes`——surface 流始终精确等于模型可见的轮次结构。该事件在 wire 消费方边界作结构性收窄（dsh-tools 的宿主类型无法进入客户端程序——宿主端/客户端两侧的 `Context` 声明合并会冲突），姿态与所有跨 wire 载荷一致。
-- **渲染层**：`ChatView` 通过整体 Tool seat `'conversation.chat.tool'` 传递每个 parent 及其已索引的 child。ui-tool 的 `ToolCallTree` 先渲染 parent，再渲染一组 `[data-subcalls]` 嵌套；每个原子调用都通过同一个 `'tool.call.toolview'` keyed slot，以 Tool 名称作为 `entryKey`，并共用 `GenericToolCard` fallback。一个 keyed 注册因此无需变化即可同时接管 child 与顶层调用。运行中的 parent（`runningCalls`）通过同一 owner 载荷接收已累积的 dispatch，使 child 行在运行期间实时流入。
+- **数据层**：运行时的 `ToolCallTree` 把窗口内的 `tool/code-dispatch-start` 与 `tool/code-dispatch` 事件折入私有的逐父级索引，再把运行中和已结算的子级投影到递归的 `ToolCallBlock.subCalls` 上。实时 Session 投影与 `projectConversationHistory` 共享这一折叠过程；逐父级的写时复制数组和路径复制投影让无关 root 与 sibling 保持引用稳定。子调用永不进入 `nodes`——surface 流始终精确等于模型可见的轮次结构。这些事件在 wire 消费方边界作结构性收窄，该边界也会拒绝成环的父子关系（dsh-tools 的宿主类型无法进入客户端程序，因为宿主端与客户端两侧的 `Context` 声明合并会冲突）。
+- **渲染层**：`ChatView` 通过整体 Tool seat `'conversation.chat.tool'` 传递每个 parent 及其递归 child。ui-tool 的 `ToolCallTree` 先渲染 parent，再渲染 `[data-subcalls]` 嵌套；每个原子调用都通过同一个 `'tool.call.toolview'` keyed slot，以 Tool 名称作为 `entryKey`，并共用 `GenericToolCard` fallback。一个 keyed 注册因此无需变化即可同时接管任意后代与顶层调用。运行中的 parent（`runningCalls`）在同一个递归块中接收已累积的 dispatch，使 child 行在运行期间实时流入。
 - **`run_code` 的呈现**：新增一种 `code` 行变体（分类器映射 `run_code → code`、标题 `Code`、图标 `IconCodeOutline16`），以模型撰写的 `description` 作摘要，展开后显示程序本身（在 markdown 代码块的填充底色上以等宽字体呈现），而非参数的 JSON 封装。
-- **详情面板**：`materialFor` 按 nodes → runningCalls → 分发索引的顺序逐级回落，因此被选中的子调用 callId 会经由与已完结的原生调用完全相同的渲染路径，解析出完整参数与完整输出。
+- **详情面板**：`materialFor` 递归搜索 `nodes` 与 `runningCalls`，因此被选中的后代 callId 会经由与已完结的原生调用完全相同的渲染路径，解析出完整参数与完整输出。
 
 ## 曾考虑的替代方案
 
@@ -29,4 +29,4 @@ Status: implemented
 
 ## 后果
 
-自定义 toolview 注册免费适用于子调用——而且是刻意为之：不存在按注册粒度的退出机制，唯一的出路是组件自行读取自身上下文，而当前没有任何消费方需要这么做。选中高亮经由同一条 `selectedCallId` 通道到达嵌套行（分组归属判断会同时检验两个层级）。trajectory/waterfall 仍把 `run_code` 渲染为单独一行——它们的子调用 span 推迟到增加分发计时（start/end 事件）的那个 PR；缺少计时，waterfall 上的 span 就是在撒谎。fixture（测试前置数据）的轮次 64（`?fixture`），加上 `code-mode-round` 浏览器 e2e（录制的真实轮次、无密钥回放），共同锁定整个界面；jsdom 测试套件则锁定 slot 分发、错误状态、详情解析与索引引用稳定性。
+自定义 toolview 注册免费适用于子调用——而且是刻意为之：不存在按注册粒度的退出机制，唯一的出路是组件自行读取自身上下文，而当前没有任何消费方需要这么做。选中高亮经由同一条 `selectedCallId` 通道到达嵌套行（分组归属会搜索整棵树）。trajectory/waterfall 仍把 `run_code` 渲染为单独一行——它们的子调用 span 推迟到增加分发计时（start/end 事件）的那个 PR；缺少计时，waterfall 上的 span 就是在撒谎。fixture（测试前置数据）的轮次 64（`?fixture`），加上 `code-mode-round` 浏览器 e2e（录制的真实轮次、无密钥回放），共同锁定整个界面；jsdom 与运行时测试套件则锁定 slot 分发、错误状态、递归详情解析、历史投影与引用稳定的路径复制。
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
index 2d3d73f65d..ed15fd5c36 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.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 .agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
-2026-07-26-code-mode-live-parallel-dispatch.md: b4afc21be902d8ed3e5bee2ad1a540413a864f25
-2026-07-26-code-mode-live-parallel-dispatch.zh.md: b6169e6d243163f8444ffc7b87b741ade7631198
+2026-07-26-code-mode-live-parallel-dispatch.md: e85d1f99f58f1aae28091cd8875ee87a6df5a1e7
+2026-07-26-code-mode-live-parallel-dispatch.zh.md: 39da98d9c3630d549f13df0ea555687614f3065a
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
index b4afc21be9..e85d1f99f5 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
@@ -16,7 +16,7 @@ Two gaps remained after the first two PRs. Sub-call rows appeared only when each
 
 - **Event pair**: `tool/code-dispatch-start` (parent/sub ids, name, normalized args) is appended when the scheduler actually starts a call — not at submission, so a queued call abandoned by run settlement logs nothing. The existing `tool/code-dispatch` settles the pair (same `subCallId`); every started call settles exactly once (aborts settle as `isError` outcomes through the pipeline). Timing = the two events' `time` fields. Both stay log-only; model context is untouched; format stays v0.
 - **Bridge scheduler**: submitted calls are classified at start time via `registry.executionMode` (the SAME fail-closed `isConcurrencySafe` contract the loop uses) and start strictly in submission order. One single-lane driver owns every ORDERED stage — the start append, `prepare` (pre-execute/guards), the head-of-line `finalize`/`finish` commit (post-execute + context deferral + settle append) — so ordered policy stages never overlap each other and only the around-dispatch/body stage runs concurrently, exactly the native loop's sequencing (`fillPool` awaits `startCall` then `commitReady`). Consecutive parallel-classified calls overlap up to `maxParallelSubCalls` (a `Config` field validated by the Loader schema AND re-validated at direct construction, default 10 — the loop scheduler's own default; `1` restores serial dispatch); an exclusive call drains the pool, runs alone, and holds its barrier until its COMMIT completes (post-execute included), like a native exclusive group. Run settlement aborts in-flight dispatches and abandons queued-unstarted ones (binding rejection, no events), then drains to quiescence — including a commit already mid-flight when the program returned — before the outer result closes the turn.
-- **Client**: `CodeSubCall` widens to `RunningToolCall | ToolResultNode` — a start event lands the running shape in the dispatch index (rows derive the running ring from the shape, exactly as for native in-flight calls), and its settle replaces the entry in place, preserving start order under parallel completion and carrying the start's `time` as `callTime` (duration source). A settle with no observed start (window cut mid-pair, or a pre-start-event log) appends directly, so old logs keep rendering.
+- **Client**: Runtime's `ToolCallTree` stores a start event as a `RunningToolCall` child and projects it through the parent's recursive `subCalls` (rows derive the running ring from that shape, exactly as for native in-flight calls). Its settle replaces the private-index entry in place, preserving start order under parallel completion and carrying the start's `time` as `callTime` (duration source). A settle with no observed start (window cut mid-pair, or a pre-start-event log) appends directly, so old logs keep rendering.
 - **SDK prompt**: the model-facing "calls execute sequentially" sentence is replaced with the true contract (independent safe calls may overlap under `Promise.all`; dependent work sequences with `await`) — a model-visible change, re-recorded across every code-mode snapshot.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
index b6169e6d24..39da98d9c3 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 - **事件对**：`tool/code-dispatch-start`（父/子 id、名称、规范化参数）在调度器真正启动某个调用时才追加，而非在提交时，因此因 run 结算而被放弃的排队调用不会留下任何日志。既有的 `tool/code-dispatch` 结算该事件对（`subCallId` 相同）；每个已启动的调用恰好结算一次（中止也会作为 `isError` 结果经由流水线结算）。计时即这两个事件的 `time` 字段。两个事件都保持仅日志；模型上下文不受影响；格式保持 v0。
 - **桥接层调度器**：已提交的调用在启动那一刻经 `registry.executionMode` 分类（与 loop 所用完全相同、故障时默认判为不安全的 `isConcurrencySafe` 契约），并严格按提交顺序启动。所有有序阶段——start 事件追加、`prepare`（pre-execute/守卫）、队首 `finalize`/`finish` 提交（post-execute + 上下文延迟提交 + settle 事件追加）——由单通道驱动器独占执行，因此有序策略阶段彼此绝不重叠，只有 around-dispatch/工具体阶段并发运行，与原生 loop 的时序完全一致（`fillPool` 先 await `startCall` 再 `commitReady`）。连续被分类为可并行的调用可以重叠执行，上限为 `maxParallelSubCalls`（`Config` 字段，Loader schema 校验之外直接构造时也重新校验，默认值 10，即 loop 调度器自身的默认值；设为 `1` 即恢复串行分发）；独占调用则先排空池、独自运行，且其屏障保持到自身提交（含 post-execute）完成为止，与原生独占分组一致。run 结算时会中止仍在运行的分发，并放弃已排队未启动的分发（绑定调用被拒绝，不产生事件），随后排空到完全停稳——包括程序返回时已在途的提交——之后外层结果才结束该轮次。
-- **客户端侧**：`CodeSubCall` 拓宽为 `RunningToolCall | ToolResultNode`：start 事件把运行中形状写入分发索引（行组件从该形状推导出运行指示环，与原生运行中的调用处理完全一致），其结算事件则原位替换该条目，即使并行完成也保持启动顺序不变，并把 start 事件的 `time` 作为 `callTime`（时长来源）带入。未观察到对应 start 的结算事件（窗口切在事件对中间，或日志录制于 start 事件引入之前）会直接追加，因此旧日志仍能照常渲染。
+- **客户端侧**：运行时的 `ToolCallTree` 把 start 事件存为 `RunningToolCall` 子级，并通过父级递归的 `subCalls` 投影出来（行组件从该形状推导出运行指示环，与原生运行中的调用处理完全一致）。其结算事件会原位替换私有索引中的条目，即使并行完成也保持启动顺序不变，并把 start 事件的 `time` 作为 `callTime`（时长来源）带入。未观察到对应 start 的结算事件（窗口切在事件对中间，或日志录制于 start 事件引入之前）会直接追加，因此旧日志仍能照常渲染。
 - **SDK 提示词**：面向模型的「调用按顺序执行」一句替换为真实契约（相互独立的安全调用可以在 `Promise.all` 下重叠执行；相互依赖的工作以 `await` 顺序衔接）；这是模型可见的变更，每一份 Code Mode 快照都已重新录制。
 
 ## 曾考虑的替代方案
diff --git a/packages/client/runtime/src/client/sessions/tool-call-tree.ts b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
index ef25ba3da2..574a10dd92 100644
--- a/packages/client/runtime/src/client/sessions/tool-call-tree.ts
+++ b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
@@ -10,9 +10,9 @@ interface ProjectedBlock {
   value: ToolCallBlock
 }
 
-function sameBlocks(
-  left: readonly ToolCallBlock[],
-  right: readonly ToolCallBlock[],
+function sameReferences<T>(
+  left: readonly T[],
+  right: readonly T[],
 ): boolean {
   return left.length === right.length
     && left.every((block, index) => block === right[index])
@@ -68,6 +68,7 @@ export class ToolCallTree {
         subCalls: [],
       }
       const siblings = this.childrenByParent.get(data.parentCallId) ?? []
+      if (this.wouldCreateCycle(data.parentCallId, data.subCallId)) return true
       this.childrenByParent.set(data.parentCallId, [...siblings, running])
       this.revision++
       return true
@@ -83,6 +84,7 @@ export class ToolCallTree {
     }
     const siblings = this.childrenByParent.get(data.parentCallId) ?? []
     const at = siblings.findIndex(sub => sub.callId === data.subCallId)
+    if (at === -1 && this.wouldCreateCycle(data.parentCallId, data.subCallId)) return true
     const started = at === -1 ? undefined : siblings[at]
     const settled: ToolResultNode = {
       kind: 'tool-result',
@@ -116,14 +118,11 @@ export class ToolCallTree {
     if (this.nodesCache?.source === nodes && this.nodesCache.revision === this.revision) {
       return this.nodesCache.value
     }
-    let changed = false
     const projected = nodes.map((node): ConversationNode => {
       if (node.kind !== 'tool-result') return node
-      const value = this.projectBlock(node) as ToolResultNode
-      changed ||= value !== node
-      return value
+      return this.projectBlock(node) as ToolResultNode
     })
-    const value = changed ? projected : nodes
+    const value = sameReferences(nodes, projected) ? nodes : projected
     this.nodesCache = { source: nodes, revision: this.revision, value }
     return value
   }
@@ -137,13 +136,8 @@ export class ToolCallTree {
     if (this.runningCache?.source === calls && this.runningCache.revision === this.revision) {
       return this.runningCache.value
     }
-    let changed = false
-    const projected = calls.map((call): RunningToolCall => {
-      const value = this.projectBlock(call) as RunningToolCall
-      changed ||= value !== call
-      return value
-    })
-    const value = changed ? projected : calls
+    const projected = calls.map(call => this.projectBlock(call) as RunningToolCall)
+    const value = sameReferences(calls, projected) ? calls : projected
     this.runningCache = { source: calls, revision: this.revision, value }
     return value
   }
@@ -151,11 +145,11 @@ export class ToolCallTree {
   private projectBlock(block: ToolCallBlock): ToolCallBlock {
     const children = this.childrenByParent.get(block.callId) ?? block.subCalls
     const projectedChildren = children.map(child => this.projectBlock(child))
-    const childValue = sameBlocks(children, projectedChildren)
+    const childValue = sameReferences(children, projectedChildren)
       ? children
       : projectedChildren
     const cached = this.projectedByCall.get(block.callId)
-    if (cached?.source === block && sameBlocks(cached.children, childValue)) {
+    if (cached?.source === block && sameReferences(cached.children, childValue)) {
       return cached.value
     }
     const value: ToolCallBlock = block.subCalls === childValue
@@ -168,4 +162,19 @@ export class ToolCallTree {
     })
     return value
   }
+
+  private wouldCreateCycle(parentCallId: string, subCallId: string): boolean {
+    if (parentCallId === subCallId) return true
+    const pending = [subCallId]
+    const visited = new Set(pending)
+    for (const callId of pending) {
+      for (const child of this.childrenByParent.get(callId) ?? []) {
+        if (child.callId === parentCallId) return true
+        if (visited.has(child.callId)) continue
+        visited.add(child.callId)
+        pending.push(child.callId)
+      }
+    }
+    return false
+  }
 }
diff --git a/packages/client/runtime/tests/history-fold.spec.ts b/packages/client/runtime/tests/history-fold.spec.ts
index 083bdc3566..37a1060fec 100644
--- a/packages/client/runtime/tests/history-fold.spec.ts
+++ b/packages/client/runtime/tests/history-fold.spec.ts
@@ -168,6 +168,37 @@ describe('projectConversationHistory', () => {
     })
   })
 
+  it('projects nested dispatches onto settled and interrupted history calls', () => {
+    const projection = projectConversationHistory([
+      ev.turnStart(0, 1),
+      ev.toolCall(1, 1, 'settled', 'run_code', '{}'),
+      ev.codeDispatchStart(2, 'settled', 1, 'run_code', { code: 'nested' }),
+      ev.codeDispatchStart(3, 'settled:code:1', 1, 'read', { path: 'a.txt' }),
+      ev.codeDispatch(4, 'settled:code:1', 1, 'read', { path: 'a.txt' }, 'alpha'),
+      ev.codeDispatch(5, 'settled', 1, 'run_code', { code: 'nested' }, 'alpha'),
+      ev.toolResult(6, 1, 'settled', 'done'),
+      ev.turnEnd(7, 1),
+      ev.turnStart(8, 2),
+      ev.toolCall(9, 2, 'interrupted', 'run_code', '{}'),
+      ev.codeDispatchStart(10, 'interrupted', 1, 'bash', { command: 'sleep 1' }),
+      ev.turnEnd(11, 2, 'aborted'),
+    ].map(event => ({ event })))
+
+    const settled = {
+      callId: 'settled',
+      subCalls: [{
+        callId: 'settled:code:1',
+        subCalls: [{ callId: 'settled:code:1:code:1', call: { name: 'read' } }],
+      }],
+    }
+    expect(projection.eventNodes).toMatchObject([settled])
+    expect(projection.contexts[0]?.nodes).toMatchObject([settled])
+    expect(projection.interruptedNodes).toMatchObject([{
+      callId: 'interrupted',
+      subCalls: [{ callId: 'interrupted:code:1', name: 'bash' }],
+    }])
+  })
+
   it('drops completed token payloads without changing inspection projections', () => {
     const events = [
       ev.user(0, 'before'),
diff --git a/packages/client/runtime/tests/tool-call-tree.spec.ts b/packages/client/runtime/tests/tool-call-tree.spec.ts
new file mode 100644
index 0000000000..56e7f96694
--- /dev/null
+++ b/packages/client/runtime/tests/tool-call-tree.spec.ts
@@ -0,0 +1,65 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { describe, expect, it } from 'vitest'
+import type { RunningToolCall } from '../src/client/sessions/conversation.ts'
+import { ToolCallTree } from '../src/client/sessions/tool-call-tree.ts'
+
+const at = (seq: number, type: string, data: Record<string, unknown>): SessionEvent =>
+  ({ seq, time: 1_700_000_000_000 + seq, type, data }) as unknown as SessionEvent
+
+const start = (seq: number, parentCallId: string, subCallId: string): SessionEvent =>
+  at(seq, 'tool/code-dispatch-start', {
+    parentCallId, subCallId, name: 'run_code', arguments: {},
+  })
+
+const settle = (seq: number, parentCallId: string, subCallId: string): SessionEvent =>
+  at(seq, 'tool/code-dispatch', {
+    parentCallId, subCallId, name: 'run_code', arguments: {},
+    isError: false, content: [],
+  })
+
+const root = (callId: string): RunningToolCall => ({
+  callId, name: 'run_code', argsRaw: '{}', turn: 1, step: 1,
+  time: 1_700_000_000_000, callView: null, subCalls: [],
+})
+
+describe('ToolCallTree', () => {
+  it('rejects a self-parenting dispatch edge', () => {
+    const tree = new ToolCallTree()
+    const roots = [root('root')]
+
+    expect(tree.apply(start(0, 'root', 'root'))).toBe(true)
+    expect(tree.projectRunningCalls(roots)).toBe(roots)
+  })
+
+  it('rejects a settling edge that would close a multi-call cycle', () => {
+    const tree = new ToolCallTree()
+    tree.apply(start(0, 'a', 'b'))
+    tree.apply(start(1, 'b', 'c'))
+
+    expect(tree.apply(settle(2, 'c', 'a'))).toBe(true)
+    expect(tree.projectRunningCalls([root('a')])).toMatchObject([{
+      callId: 'a',
+      subCalls: [{
+        callId: 'b',
+        subCalls: [{ callId: 'c', subCalls: [] }],
+      }],
+    }])
+  })
+
+  it('accepts an acyclic graph with a shared descendant', () => {
+    const tree = new ToolCallTree()
+    tree.apply(start(0, 'a', 'b'))
+    tree.apply(start(1, 'a', 'c'))
+    tree.apply(start(2, 'b', 'd'))
+    tree.apply(start(3, 'c', 'd'))
+
+    expect(tree.apply(start(4, 'root', 'a'))).toBe(true)
+    expect(tree.projectRunningCalls([root('root')])).toMatchObject([{
+      callId: 'root',
+      subCalls: [{
+        callId: 'a',
+        subCalls: [{ callId: 'b' }, { callId: 'c' }],
+      }],
+    }])
+  })
+})
diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
index a89f724dd4..3afe471d50 100644
--- a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
@@ -133,18 +133,18 @@ describe('render branch tails', () => {
     snap.runningCalls = [{
       callId: 'p1', name: 'run_code', argsRaw: '{}', turn: 1, step: 1,
       time: 7_000, callView: null, subCalls: [{
-      kind: 'tool-result', seq: 8, time: 8_000, callId: 'p1:code:1',
-      call: { name: 'run_code', argsRaw: '{"code":"return 1"}' },
-      callTime: 8_000,
-      content: [], isError: false, callView: null, resultView: null,
-      subCalls: [{
-        kind: 'tool-result', seq: 9, time: 9_000, callId: 'p1:code:1:code:1',
-        call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
-        callTime: 8_500,
-        content: [{ type: 'text', text: longText }], isError: false, callView: null, resultView: null,
-        subCalls: [],
+        kind: 'tool-result', seq: 8, time: 8_000, callId: 'p1:code:1',
+        call: { name: 'run_code', argsRaw: '{"code":"return 1"}' },
+        callTime: 8_000,
+        content: [], isError: false, callView: null, resultView: null,
+        subCalls: [{
+          kind: 'tool-result', seq: 9, time: 9_000, callId: 'p1:code:1:code:1',
+          call: { name: 'read', argsRaw: '{"path":"notes/demo.txt"}' },
+          callTime: 8_500,
+          content: [{ type: 'text', text: longText }], isError: false, callView: null, resultView: null,
+          subCalls: [],
+        }],
       }],
-    }],
     }]
     const chat = createChatStore().create()
     chat.actions.select({ turnSeq: 9, callId: 'p1:code:1:code:1', toolName: 'read' } satisfies SelectionTarget)
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 5407a43717..97008e3e0c 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/client/ui-tool/README.md
-README.md: bab3f92e4f6780b041cee2e682cb8ece3386ef15
-README.zh.md: 9187510fa354ba072835271d4b1153c8ee1105c0
+README.md: d6bc0f248cffaf4c65ecf6d97c7a4afb17fc8941
+README.zh.md: f4e8044fe6e10e1fbdfb70987efe07c884fa9ac8
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index bab3f92e4f..d6bc0f248c 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -44,5 +44,6 @@ None. The package is client-only presentation.
 
 ## Known Limitations and Deferred Work
 
+- The Host excludes `run_code` from Code Mode program bindings, so production events currently produce one dispatch level; the recursive Runtime/UI contract is ready for future nested producers.
 - Existing first-party Tool views are initially colocated here and can move to their owning business packages independently through the keyed slot.
 - Tool copy temporarily reuses the `ui-conversation` locale namespace.
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index 9187510fa3..f4e8044fe6 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -44,5 +44,6 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ## 已知限制与后续工作
 
+- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时/UI 契约已为未来的嵌套生产者做好准备。
 - 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
 - Tool 文案暂时复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
index 2bc97425e2..2f5efae420 100644
--- a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
@@ -56,7 +56,9 @@ const runningCode = (callId: string): RunningToolCall => ({
   subCalls: [],
 })
 
-const subCall = (seq: number, parent: string, n: number, name: string, args: object, resultText: string, isError = false): ToolCallBlock => ({
+const subCall = (
+  seq: number, parent: string, n: number, name: string, args: object, resultText: string, isError = false,
+): ToolCallBlock => ({
   kind: 'tool-result', seq, time: seq * 1_000,
   callId: `${parent}:code:${n}`,
   call: { name, argsRaw: JSON.stringify(args) },
diff --git a/packages/client/ui-trajectory/src/client/layout.ts b/packages/client/ui-trajectory/src/client/layout.ts
index 6853199aa1..4e110a5888 100644
--- a/packages/client/ui-trajectory/src/client/layout.ts
+++ b/packages/client/ui-trajectory/src/client/layout.ts
@@ -917,7 +917,6 @@ function expandSubCalls(
       absTime: settled ? finiteTime(sub.callTime ?? sub.time) : finiteTime(sub.time),
       toolName: settled ? sub.call?.name ?? sub.callId : sub.name,
       callId: sub.callId,
-      subCalls: sub.subCalls,
       cell: {
         index: ++index,
         kind: 'subtool',

From 4de2de98e49517733a2fa57530ce2d73a8a649b5 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:15:34 +0800
Subject: [PATCH 263/516] fix(client): bound nested Tool call depth

---
 packages/client/runtime/README.i18n.yaml      |  4 +--
 packages/client/runtime/README.md             |  2 +-
 packages/client/runtime/README.zh.md          |  2 +-
 .../src/client/sessions/tool-call-tree.ts     | 36 +++++++++++++++++--
 .../runtime/tests/tool-call-tree.spec.ts      | 28 +++++++++++++--
 5 files changed, 64 insertions(+), 8 deletions(-)

diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index bb64a12d4e..1edac07d5e 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: fad0f6e4f948ebf412b2bd837a4f68e6dc805ec8
-README.zh.md: 4ede12a320082a5023ec121306650fce72a12663
+README.md: a9b604974595b1b7856f74b72d36093491ec1bd1
+README.zh.md: 6eee14bdbe7a9fb86b0a12355e7d0a45cd500774
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index fad0f6e4f9..a9b6049745 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -46,7 +46,7 @@ Because the projection is log-ordered, the node array is seq-monotonic by constr
 
 ## Code Mode child-call tree
 
-Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Runtime's `ToolCallTree` privately maintains the parent-callId-to-children index: a `tool/code-dispatch-start` event lands as a `RunningToolCall`, and the matching `tool/code-dispatch` settlement replaces it in place with a `ToolResultNode` whose `callTime` comes from the paired start. When the start fell outside the replay window, the settlement appends directly with `callTime: null`; Runtime never fabricates a zero duration. Live mux frames and history replay share this fold and tree projection, and child calls never become independent roots in transcript `nodes`. A child update copies only its ancestor path to the owning root; unchanged siblings and other roots retain object identity.
+Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Runtime's `ToolCallTree` privately maintains the parent-callId-to-children index: a `tool/code-dispatch-start` event lands as a `RunningToolCall`, and the matching `tool/code-dispatch` settlement replaces it in place with a `ToolResultNode` whose `callTime` comes from the paired start. When the start fell outside the replay window, the settlement appends directly with `callTime: null`; Runtime never fabricates a zero duration. Live mux frames and history replay share this fold and tree projection, and child calls never become independent roots in transcript `nodes`. A child update copies only its ancestor path to the owning root; unchanged siblings and other roots retain object identity. Wire or history edges that would introduce a cycle or exceed the fixed 256-call recursive-depth safety limit are consumed without mutating the tree, so the rest of the session remains renderable.
 
 ## Session title projection
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 4ede12a320..6eee14bdbe 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -46,7 +46,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## Code Mode 子调用树
 
-每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Runtime 的 `ToolCallTree` 私下维护 parent callId 到 child 的索引：`tool/code-dispatch-start` 事件落成 `RunningToolCall`，对应的 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode`，其 `callTime` 来自成对 start 事件；start 落在回放窗口之外时，完结事件会以 `callTime: null` 直接追加，绝不伪造零耗时。live mux 帧与历史回放共用这套 fold 和树投影；子调用不会成为 transcript `nodes` 中的独立 root。一次 child 变化只会复制从该 child 到所属 root 的祖先链，未变化的 sibling 和其他 root 保持对象引用稳定。
+每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Runtime 的 `ToolCallTree` 私下维护 parent callId 到 child 的索引：`tool/code-dispatch-start` 事件落成 `RunningToolCall`，对应的 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode`，其 `callTime` 来自成对 start 事件；start 落在回放窗口之外时，完结事件会以 `callTime: null` 直接追加，绝不伪造零耗时。live mux 帧与历史回放共用这套 fold 和树投影；子调用不会成为 transcript `nodes` 中的独立 root。一次 child 变化只会复制从该 child 到所属 root 的祖先链，未变化的 sibling 和其他 root 保持对象引用稳定。会引入环，或使递归深度超过 256 个调用这一固定安全上限的协议或历史记录边会被视为已消费，但不会修改树，因此会话其余部分仍可渲染。
 
 ## Session 标题投影
 
diff --git a/packages/client/runtime/src/client/sessions/tool-call-tree.ts b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
index 574a10dd92..fbc32e0cef 100644
--- a/packages/client/runtime/src/client/sessions/tool-call-tree.ts
+++ b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
@@ -10,6 +10,9 @@ interface ProjectedBlock {
   value: ToolCallBlock
 }
 
+/** Fixed wire-safety ceiling for every recursive Tool call consumer. */
+export const MAX_TOOL_CALL_TREE_DEPTH = 256
+
 function sameReferences<T>(
   left: readonly T[],
   right: readonly T[],
@@ -24,6 +27,7 @@ function sameReferences<T>(
  */
 export class ToolCallTree {
   private readonly childrenByParent = new Map<string, readonly ToolCallBlock[]>()
+  private readonly depthByCall = new Map<string, number>()
   private readonly projectedByCall = new Map<string, ProjectedBlock>()
   private revision = 0
   private nodesCache: {
@@ -40,6 +44,7 @@ export class ToolCallTree {
   /** Forget all event-derived child calls before replaying a new window. */
   reset(): void {
     this.childrenByParent.clear()
+    this.depthByCall.clear()
     this.projectedByCall.clear()
     this.revision++
   }
@@ -68,7 +73,7 @@ export class ToolCallTree {
         subCalls: [],
       }
       const siblings = this.childrenByParent.get(data.parentCallId) ?? []
-      if (this.wouldCreateCycle(data.parentCallId, data.subCallId)) return true
+      if (!this.acceptEdge(data.parentCallId, data.subCallId)) return true
       this.childrenByParent.set(data.parentCallId, [...siblings, running])
       this.revision++
       return true
@@ -84,7 +89,7 @@ export class ToolCallTree {
     }
     const siblings = this.childrenByParent.get(data.parentCallId) ?? []
     const at = siblings.findIndex(sub => sub.callId === data.subCallId)
-    if (at === -1 && this.wouldCreateCycle(data.parentCallId, data.subCallId)) return true
+    if (at === -1 && !this.acceptEdge(data.parentCallId, data.subCallId)) return true
     const started = at === -1 ? undefined : siblings[at]
     const settled: ToolResultNode = {
       kind: 'tool-result',
@@ -163,6 +168,33 @@ export class ToolCallTree {
     return value
   }
 
+  /**
+   * Accept an edge only when every recursive consumer can traverse it safely.
+   * Host-minted ids exclude cycles and current bindings emit one level; a
+   * malformed wire/history edge is consumed without hiding the rest of the session.
+   */
+  private acceptEdge(parentCallId: string, subCallId: string): boolean {
+    if (this.wouldCreateCycle(parentCallId, subCallId)) return false
+    const pending = [{
+      callId: subCallId,
+      depth: (this.depthByCall.get(parentCallId) ?? 1) + 1,
+    }]
+    const updates = new Map<string, number>()
+    for (const candidate of pending) {
+      const knownDepth = updates.get(candidate.callId)
+        ?? this.depthByCall.get(candidate.callId)
+        ?? 1
+      if (candidate.depth <= knownDepth) continue
+      if (candidate.depth > MAX_TOOL_CALL_TREE_DEPTH) return false
+      updates.set(candidate.callId, candidate.depth)
+      for (const child of this.childrenByParent.get(candidate.callId) ?? []) {
+        pending.push({ callId: child.callId, depth: candidate.depth + 1 })
+      }
+    }
+    for (const [callId, depth] of updates) this.depthByCall.set(callId, depth)
+    return true
+  }
+
   private wouldCreateCycle(parentCallId: string, subCallId: string): boolean {
     if (parentCallId === subCallId) return true
     const pending = [subCallId]
diff --git a/packages/client/runtime/tests/tool-call-tree.spec.ts b/packages/client/runtime/tests/tool-call-tree.spec.ts
index 56e7f96694..541e6b2e19 100644
--- a/packages/client/runtime/tests/tool-call-tree.spec.ts
+++ b/packages/client/runtime/tests/tool-call-tree.spec.ts
@@ -1,7 +1,9 @@
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import { describe, expect, it } from 'vitest'
-import type { RunningToolCall } from '../src/client/sessions/conversation.ts'
-import { ToolCallTree } from '../src/client/sessions/tool-call-tree.ts'
+import type { RunningToolCall, ToolCallBlock } from '../src/client/sessions/conversation.ts'
+import {
+  MAX_TOOL_CALL_TREE_DEPTH, ToolCallTree,
+} from '../src/client/sessions/tool-call-tree.ts'
 
 const at = (seq: number, type: string, data: Record<string, unknown>): SessionEvent =>
   ({ seq, time: 1_700_000_000_000 + seq, type, data }) as unknown as SessionEvent
@@ -62,4 +64,26 @@ describe('ToolCallTree', () => {
       }],
     }])
   })
+
+  it('rejects an edge beyond the recursive depth safety limit', () => {
+    const tree = new ToolCallTree()
+    for (let depth = 1; depth < MAX_TOOL_CALL_TREE_DEPTH; depth++) {
+      tree.apply(start(depth, `call-${depth - 1}`, `call-${depth}`))
+    }
+
+    expect(tree.apply(start(
+      MAX_TOOL_CALL_TREE_DEPTH,
+      `call-${MAX_TOOL_CALL_TREE_DEPTH - 1}`,
+      `call-${MAX_TOOL_CALL_TREE_DEPTH}`,
+    ))).toBe(true)
+
+    let current: ToolCallBlock = tree.projectRunningCalls([root('call-0')])[0]!
+    let depth = 1
+    while (current.subCalls.length > 0) {
+      current = current.subCalls[0]!
+      depth++
+    }
+    expect(depth).toBe(MAX_TOOL_CALL_TREE_DEPTH)
+    expect(current.callId).toBe(`call-${MAX_TOOL_CALL_TREE_DEPTH - 1}`)
+  })
 })

From 9b169f7555433ee762b39ab385072265e284aa64 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:37:32 +0800
Subject: [PATCH 264/516] ci: run required checks on native Windows

---
 .agents/notes/archived/manifest.json          |   3 +
 ...27-wine-windows-gates-experiment.i18n.yaml |   4 +-
 ...026-07-27-wine-windows-gates-experiment.md |   1 +
 ...-07-27-wine-windows-gates-experiment.zh.md |   1 +
 ...rial-cross-platform-ci-reference.i18n.yaml |   4 +-
 ...7-21-serial-cross-platform-ci-reference.md |   2 +-
 ...1-serial-cross-platform-ci-reference.zh.md |   2 +-
 ...ortable-required-pull-request-ci.i18n.yaml |   4 +-
 ...07-23-portable-required-pull-request-ci.md |   6 +-
 ...23-portable-required-pull-request-ci.zh.md |   6 +-
 ...n-setup-for-symmetric-ci-caching.i18n.yaml |   4 +-
 ...m-action-setup-for-symmetric-ci-caching.md |   4 +-
 ...ction-setup-for-symmetric-ci-caching.zh.md |   4 +-
 ...8-native-windows-pull-request-ci.i18n.yaml |   6 +
 ...26-08-08-native-windows-pull-request-ci.md |  33 +++
 ...08-08-native-windows-pull-request-ci.zh.md |  33 +++
 .github/AGENTS.md                             |   2 +-
 .github/workflows/ci.yml                      | 117 ++-------
 AGENTS.md                                     |   1 -
 package.json                                  |   1 -
 scripts/ci-workflow.spec.ts                   |  22 ++
 scripts/wine-windows-gates.sh                 | 247 ------------------
 22 files changed, 144 insertions(+), 363 deletions(-)
 rename .agents/notes/{implemented => archived}/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml (67%)
 rename .agents/notes/{implemented => archived}/process/2026-07-27-wine-windows-gates-experiment.md (99%)
 rename .agents/notes/{implemented => archived}/process/2026-07-27-wine-windows-gates-experiment.zh.md (99%)
 create mode 100644 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
 create mode 100644 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
 delete mode 100755 scripts/wine-windows-gates.sh

diff --git a/.agents/notes/archived/manifest.json b/.agents/notes/archived/manifest.json
index 1adde54c7b..638d87373d 100644
--- a/.agents/notes/archived/manifest.json
+++ b/.agents/notes/archived/manifest.json
@@ -298,6 +298,9 @@
     "process/2026-07-26-gui-pr-gif-evidence-and-assets-branch.i18n.yaml": "sha256:89b6dc255cb0dd9d97ae6f34f37d185412d4260d7bf2f87d6b25e340f01dc26e",
     "process/2026-07-26-gui-pr-gif-evidence-and-assets-branch.md": "sha256:1742e09435ade4a09349c8843eb381e870a2be2d51b74449f08260422c8096b3",
     "process/2026-07-26-gui-pr-gif-evidence-and-assets-branch.zh.md": "sha256:220bd53a88617b09ee8970627c46540fa8951724b102acfe296a7ed7d0f7b5fe",
+    "process/2026-07-27-wine-windows-gates-experiment.i18n.yaml": "sha256:6f4cbc12ee9cddbb297bf7e138ccabcd204f66898a0f7411b1633f03d5a9eab5",
+    "process/2026-07-27-wine-windows-gates-experiment.md": "sha256:8d37dcdab058098c7de3da1de00ce61bef92bbc8d6ee71add959474c6fb3e936",
+    "process/2026-07-27-wine-windows-gates-experiment.zh.md": "sha256:77fbf04df36af09e55007a93bd6b22d08ff99869efe8de3e97dac5b4701e0a9e",
     "simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.i18n.yaml": "sha256:ad3d1263cb0051b885173bf064de62065e2c646ccaae2d7250723da3b4eab90c",
     "simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md": "sha256:8fb061d51c8c23b47d2367814bab3623c6d5b972f38d207a273caa9030b579bd",
     "simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.zh.md": "sha256:2ffeaca91f82844a5616d6dcce6b4af514bb8a7c46f78e47f668b204ac6edc04",
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
similarity index 67%
rename from .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
rename to .agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
index 19945a6580..f7995fd9cf 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
+++ b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.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 .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
-2026-07-27-wine-windows-gates-experiment.md: 1b01fe00dc1588482442a3cedc35eefa7fdb0975
-2026-07-27-wine-windows-gates-experiment.zh.md: b50739f5b63c5836248c94927037e38900abc84f
+2026-07-27-wine-windows-gates-experiment.md: ce2ad1ad4506f59083de5731677d052161849e3d
+2026-07-27-wine-windows-gates-experiment.zh.md: a0a5e8e7cce078adf2c961fe4d8cc50edc28355c
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.md
similarity index 99%
rename from .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
rename to .agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.md
index 1b01fe00dc..ce2ad1ad45 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
+++ b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.md
@@ -1,6 +1,7 @@
 # Agent Note: Wine-run Windows blocking gates on Linux runners
 
 Status: implemented
+Archived: 2026-08-08
 
 English | [中文](2026-07-27-wine-windows-gates-experiment.zh.md)
 
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.zh.md
similarity index 99%
rename from .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
rename to .agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.zh.md
index b50739f5b6..a0a5e8e7cc 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
+++ b/.agents/notes/archived/process/2026-07-27-wine-windows-gates-experiment.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 在 Linux runner 上用 Wine 运行 Windows 阻断门禁
 
 Status: implemented
+Archived: 2026-08-08
 
 [English](2026-07-27-wine-windows-gates-experiment.md) | 中文
 
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
index a1c49fdcae..dcb6e18e88 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.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 .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
-2026-07-21-serial-cross-platform-ci-reference.md: 71b364f72a094f7899a0929eec29f3a16ccc8a93
-2026-07-21-serial-cross-platform-ci-reference.zh.md: 4f5920ffc150ce16d5567ca05128f7524c2a2b21
+2026-07-21-serial-cross-platform-ci-reference.md: dfd762ad4d4eec61bc3a17d96865ccc4ac936ab3
+2026-07-21-serial-cross-platform-ci-reference.zh.md: 580340db2fbfc14458a4bbfbfa157db75e74e027
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
index 71b364f72a..dfd762ad4d 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
@@ -28,7 +28,7 @@ The standalone [Sandbox](../../../../.github/workflows/sandbox.yml) workflow bel
 
 Master reference jobs are diagnostic and do not participate in the pull request's required `all checks passed` result. The CI and Sandbox workflows keep their cross-platform references on master pushes. Performance is evaluated from completed hosted-job timestamps and reported as a measurement; it is not encoded as a `timeout-minutes` value.
 
-The portable reference uses GitHub's standard `ubuntu-latest`, `macos-latest`, and `windows-2025` labels; `serial / windows` is the one remaining native-Windows job, the complete-kernel oracle behind the Wine-hosted pull-request lane ([Wine lane decision](2026-07-27-wine-windows-gates-experiment.md)). Required pull-request jobs use portable standard capacity under the [required-CI decision](2026-07-23-portable-required-pull-request-ci.md). Higher-core hosted runners remain manual benchmarks because a correctness path must remain runnable without repository-external runner configuration.
+The portable reference uses GitHub's standard `ubuntu-latest`, `macos-latest`, and `windows-2025` labels. The required pull-request Windows job also runs on standard `windows-2025` under the [native Windows decision](2026-08-08-native-windows-pull-request-ci.md); when enabled, `serial / windows` remains a second complete, unsharded native-kernel oracle. Required pull-request jobs use portable standard capacity under the [required-CI decision](2026-07-23-portable-required-pull-request-ci.md). Higher-core hosted runners remain manual benchmarks because a correctness path must remain runnable without repository-external runner configuration.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
index 4f5920ffc1..580340db2f 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
@@ -28,7 +28,7 @@ macOS 参考流程使用 fork 进程运行常规 Vitest 项目。macOS arm64 上
 
 master 分支的参考作业仅用于诊断，不参与拉取请求所要求的 `all checks passed` 结果。CI 与 Sandbox 工作流把跨平台参考流程保留在 master 推送上。系统根据已完成托管作业的时间戳评估性能，并将其报告为测量结果，而不是写成 `timeout-minutes` 值。
 
-可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签；`serial / windows` 是仅存的原生 Windows 作业，是 Wine 托管拉取请求通道背后的完整内核标尺（[Wine 通道决策](2026-07-27-wine-windows-gates-experiment.md)）。依据[必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，拉取请求必需作业使用可移植的标准容量。更高核心数的托管运行器仍仅用于手动基准测试，因为正确性路径必须无需仓库外部的运行器配置即可运行。
+可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签。依据[原生 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)，拉取请求必需的 Windows 作业也在标准 `windows-2025` 上运行；`serial / windows` 启用时，仍作为第二个完整且未分片的原生内核标尺。依据[必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，拉取请求必需作业使用可移植的标准容量。更高核心数的托管运行器仍仅用于手动基准测试，因为正确性路径必须无需仓库外部的运行器配置即可运行。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
index 440691d218..768e4298c7 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.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 .agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
-2026-07-23-portable-required-pull-request-ci.md: 1a6939e8386e381cba114a7be71993a644457a45
-2026-07-23-portable-required-pull-request-ci.zh.md: f7a95ced2353ca7aaee9a586cc4f0bb297cbf7d4
+2026-07-23-portable-required-pull-request-ci.md: 11de2b1dcbbdbdd7f9423131cd84c2940ac9218d
+2026-07-23-portable-required-pull-request-ci.zh.md: 02f5d758e1259d6a8e7cba70e439775bd1df2b28
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
index 1a6939e838..11de2b1dcb 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
@@ -12,9 +12,9 @@ Billing health, a runner definition's `Ready` state, and a large autoscaling cei
 
 ## Decision
 
-[CI](../../../../.github/workflows/ci.yml) runs the required primary Node 24 jobs, plus the stable `all checks passed` aggregate, on repo-restricted enterprise 32-core pools. The aggregate performs no checkout or repository gate, but sharing the enterprise pool prevents the required verdict from introducing a separate standard-hosted billing dependency after its substantive jobs have already succeeded. The required Windows job runs Windows Node under Wine on standard `ubuntu-latest` for the blocking surfaces ([Wine lane decision](2026-07-27-wine-windows-gates-experiment.md)), keeping the pull-request Windows contract independent of any Windows runner allocation; the complete native-kernel Windows inventory lives in the master serial reference. Standard `ubuntu-latest` jobs retain Node 22.19, Node 26, and Python SDK compatibility, and `master` runs complete serial Linux, macOS, and Windows references. Those standard-hosted jobs keep the portable execution boundary observable without duplicating the primary inventory on every pull request.
+[CI](../../../../.github/workflows/ci.yml) runs the required primary Node 24 jobs, plus the stable `all checks passed` aggregate, on repo-restricted enterprise 32-core pools. The aggregate performs no checkout or repository gate, but sharing the enterprise pool prevents the required verdict from introducing a separate standard-hosted billing dependency after its substantive jobs have already succeeded. The required Windows job runs on standard `windows-2025` under native Windows for the blocking surfaces and broader observational inventory ([native Windows decision](2026-08-08-native-windows-pull-request-ci.md)). Standard `ubuntu-latest` jobs retain Node 22.19, Node 26, and Python SDK compatibility, and the serial references remain the complete unsharded cross-platform definitions. Those standard-hosted jobs keep the portable execution boundary observable without duplicating the primary inventory on every pull request.
 
-The two Linux primary jobs, Node compatibility, Python SDK, and `windows node 24 / wine blocking` remain dependencies of `all checks passed`; branch protection continues to require `e2e` and `all checks passed`. There is no automatic fallback when a remaining enterprise Linux label cannot allocate: the standard jobs continue to report their own contracts, but they cannot manufacture the missing required result.
+The two Linux primary jobs, Node compatibility, Python SDK, and `windows node 24 / native complete` remain dependencies of `all checks passed`; branch protection continues to require `e2e` and `all checks passed`. There is no automatic fallback when a remaining enterprise Linux label cannot allocate: the standard jobs continue to report their own contracts, but they cannot manufacture the missing required result.
 
 The [larger-runner decision](2026-07-22-evidence-based-larger-hosted-runners.md) owns the current primary topology and its measurements. The [serial cross-platform reference](2026-07-21-serial-cross-platform-ci-reference.md) remains the independent standard-hosted completeness check, and the manual larger-runner suites retain size comparisons without expanding the ordinary required matrix.
 
@@ -30,6 +30,6 @@ The [larger-runner decision](2026-07-22-evidence-based-larger-hosted-runners.md)
 
 ## Consequences
 
-Ordinary pull requests spend enterprise capacity on the Linux critical path while the Wine-hosted Windows job keeps its verdict on standard Linux allocation. A live exact-head run proves the same commands that branch protection consumes; queue delay is reported separately from each job's `startedAt` to `completedAt` execution interval.
+Ordinary pull requests spend enterprise capacity on the Linux critical path while the native Windows job uses standard Windows allocation. A live exact-head run proves the same commands that branch protection consumes; queue delay is reported separately from each job's `startedAt` to `completedAt` execution interval.
 
 Standard compatibility and required Windows jobs remain useful when enterprise allocation is degraded, but they do not make a blocked required Linux job or aggregate green. Recovering Linux availability may require restoring the complete standard-hosted topology; changing a pool definition's status alone is insufficient evidence that it can receive work.
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
index f7a95ced23..02f5d758e1 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `ubuntu-latest` 上通过 Wine 运行 Windows Node 以覆盖阻断性检查范围（[Wine 通道决策](2026-07-27-wine-windows-gates-experiment.md)），使拉取请求的 Windows 契约不依赖任何 Windows 运行器分配；完整的原生内核 Windows 清单位于 master 串行参考流程中。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，`master` 则运行完整的 Linux、macOS 和 Windows 串行参考流程。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
+[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `windows-2025` 上以原生 Windows 环境运行，覆盖阻断性检查范围和更广泛的观测性清单（[原生 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)）。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，串行参考流程仍是完整且未分片的跨平台定义。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
 
-两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / wine blocking` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
+两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / native complete` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
 
 当前主拓扑及其测量结果由[大型运行器决策](2026-07-22-evidence-based-larger-hosted-runners.md)记录。[跨平台串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)继续作为独立的标准托管完整性检查，手动大型运行器套件则保留规格比较，同时不扩大普通必需矩阵。
 
@@ -30,6 +30,6 @@ Status: implemented
 
 ## 后果
 
-普通拉取请求会将企业级运行器容量用于 Linux 关键路径，而 Wine 托管的 Windows 作业让其判定保持在标准 Linux 运行器分配上。一次实际的分支头精确运行能够证明分支保护使用的同一组命令；排队延迟与每个作业从 `startedAt` 到 `completedAt` 的执行区间分开报告。
+普通拉取请求会将企业级运行器容量用于 Linux 关键路径，而原生 Windows 作业使用标准 Windows 运行器容量。一次实际的分支头精确运行能够证明分支保护使用的同一组命令；排队延迟与每个作业从 `startedAt` 到 `completedAt` 的执行区间分开报告。
 
 企业级运行器分配能力下降时，标准兼容性作业和必需的 Windows 作业仍能提供有用证据，但无法让受阻的必需 Linux 作业或聚合流程变绿。恢复 Linux 可用性时，可能需要恢复完整的标准托管拓扑；仅改变运行器池定义的状态，不足以证明它可以接收作业。
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
index 7005f08ce0..224544c058 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.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 .agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 006360cedfd4d1e2c2b67ede98062a375e316f47
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: 2258a1fe5f91b27b8a3b636c7f3ad26f502a98df
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 6fba2ce3b508d9d6fc879460a63c0e12673bd866
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: d9da8a4abe13772f3cc282392c03cdea54726c01
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
index 006360cedf..6fba2ce3b5 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
@@ -13,8 +13,8 @@ Outside `landlock-run.yml`, each workflow that installed pnpm hand-provisioned i
 `pnpm/action-setup@v4` is the only pnpm provisioning mechanism in CI: no workflow runs `corepack enable`. The root dev dependency on `@yarnpkg/cli-dist` separately supplies the modern Yarn CLI exercised by the generated-project e2e; package-manager coverage therefore does not inherit the runner image's Yarn Classic. Caching remains per-job policy on top of pnpm provisioning, in three deliberate shapes:
 
 - **Symmetric cache** (restore and save): `actions/setup-node` with `cache: pnpm` — `e2e.yml`, `docs-pages.yml`, `pi-ai-provider-e2e.yml`, `build-exe-for-python-sdk.yml`, and the node-compat and two benchmark jobs of `ci.yml`. The larger-runner benchmark keeps its store cache Linux-only through a conditional `cache:` input; the consolidated benchmark caches on both platforms.
-- **Restore-only / producer pairing** (hand-rolled `actions/cache` steps): the three enterprise-runner PR jobs and the Wine-based pull-request Windows job restore without saving, keeping cache compression/upload off their latency-sensitive paths — an asymmetry `setup-node`'s cache cannot express. Each configures a store outside the action's replaceable install directory and resolves that path, matching the master-push serial-linux producer's path and exact key; the enterprise jobs skip restore during self-hosted failover because that VM's persistent store is already warm.
-- **Cache-less or persistent** (no store-cache action): native serial-windows and serial-macos plus `sandbox.yml` install from a cold or runner-local store. The self-hosted standby and failover jobs reuse their VM's persistent pnpm store without transferring a hosted cache archive.
+- **Restore-only / producer pairing** (hand-rolled `actions/cache` steps): the three enterprise-runner PR jobs restore without saving, keeping cache compression/upload off their latency-sensitive paths — an asymmetry `setup-node`'s cache cannot express. Each configures a store outside the action's replaceable install directory and resolves that path, matching the master-push serial-linux producer's path and exact key; the enterprise jobs skip restore during self-hosted failover because that VM's persistent store is already warm.
+- **Cache-less or persistent** (no store-cache action): the required native Windows job, native serial-windows and serial-macos, plus `sandbox.yml` install from a cold or runner-local store. Extracting the many-file pnpm store costs more than a clean Windows install; the self-hosted standby and failover jobs instead reuse their VM's persistent pnpm store without transferring a hosted cache archive.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
index 2258a1fe5f..d9da8a4abe 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
@@ -13,8 +13,8 @@ Status: implemented
 `pnpm/action-setup@v4` 是 CI 中提供 pnpm 的唯一机制：没有任何工作流运行 `corepack enable`。根目录的 `@yarnpkg/cli-dist` 开发依赖另行提供 generated-project e2e 所运行的现代 Yarn CLI（命令行界面）；因此，用于包管理器覆盖率的 Yarn 不会沿用 runner 镜像里的 Yarn Classic。缓存仍是叠加在 pnpm 提供机制上的按作业政策，保持三种刻意的形态：
 
 - **对称缓存**（既恢复也保存）：带 `cache: pnpm` 的 `actions/setup-node`——`e2e.yml`、`docs-pages.yml`、`pi-ai-provider-e2e.yml`、`build-exe-for-python-sdk.yml`，以及 `ci.yml` 的 node-compat 与两个 benchmark 作业。larger-runner benchmark 通过条件化的 `cache:` 输入让 store 缓存仅限 Linux；consolidated benchmark 在两个平台上都启用缓存。
-- **只恢复不上传／生产者配对**（手写的 `actions/cache` 步骤）：企业 runner 上的三个 PR（Pull Request）作业与基于 Wine 的拉取请求 Windows 作业只恢复不保存，把缓存压缩／上传挡在它们的延迟敏感路径之外——这种不对称是 `setup-node` 的缓存无法表达的。每个作业都在 action 可替换的安装目录之外配置 store，并解析该路径，从而与 master 推送触发的 serial-linux 生产者所用的路径和精确键匹配；企业作业在自托管故障切换期间跳过恢复，因为该 VM 的持久 store 已经预热。
-- **无缓存或持久化**（不使用 store 缓存 action）：原生 serial-windows 和 serial-macos 加上 `sandbox.yml` 从冷 store 或 runner 本地 store 安装。自托管热备与故障切换作业复用其 VM 的持久 pnpm store，不传输托管缓存归档。
+- **只恢复不上传／生产者配对**（手写的 `actions/cache` 步骤）：企业 runner 上的三个 PR（Pull Request）作业只恢复不保存，把缓存压缩／上传挡在它们的延迟敏感路径之外——这种不对称是 `setup-node` 的缓存无法表达的。每个作业都在 action 可替换的安装目录之外配置 store，并解析该路径，从而与 master 推送触发的 serial-linux 生产者所用的路径和精确键匹配；企业作业在自托管故障切换期间跳过恢复，因为该 VM 的持久 store 已经预热。
+- **无缓存或持久化**（不使用 store 缓存 action）：必需的原生 Windows 作业、原生 serial-windows 和 serial-macos，以及 `sandbox.yml` 均从冷 store 或 runner 本地 store 安装。解压含有大量文件的 pnpm store，成本高于在 Windows 上进行一次全新安装；自托管热备与故障切换作业则复用其 VM 的持久 pnpm store，不传输托管缓存归档。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
new file mode 100644
index 0000000000..3b3d2dc1dd
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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/process/2026-08-08-native-windows-pull-request-ci.md
+2026-08-08-native-windows-pull-request-ci.md: 926eec04cff63aaf25d1e85b3dcbc41464f25660
+2026-08-08-native-windows-pull-request-ci.zh.md: 8728f0eb08adcb1501f036bb19ff523ded406ccc
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
new file mode 100644
index 0000000000..926eec04cf
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -0,0 +1,33 @@
+# Agent Note: Native Windows pull-request CI
+
+Status: implemented
+
+English | [中文](2026-08-08-native-windows-pull-request-ci.zh.md)
+
+## Problem
+
+The required pull-request Windows verdict must protect behavior that depends on the operating system, not only toolchain branches selected by `process.platform`. The Wine lane executed Windows Node and PE binaries over a Linux kernel and case-sensitive ext4, required a hoisted dependency layout and host-created symlinks, and omitted NTFS, DACL, ConPTY, crash-durability, and the broader observational Windows inventory. With the native serial references disabled, ordinary CI had no real Windows-kernel signal.
+
+## Decision
+
+The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) runs on GitHub's standard `windows-2025` image under native PowerShell. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete`. The stable `windows` job id remains a dependency of `all checks passed`; its display name is `windows node 24 / native complete`.
+
+The aggregate keeps workspace build and production-site failures blocking while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
+
+Wine-only infrastructure is absent from the supported workflow: there is no apt-cache producer, compatibility script, hoisted snapshot install, Windows Node download, or local `check:windows-wine` command. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) remains historical evidence for its measured latency and fidelity trade-offs, not a current execution path.
+
+## Alternatives considered
+
+**Keep Wine on the required path.** Its warm wall clock was close to Linux CI and it selected win32 toolchain branches, but the compatibility-specific layout and kernel gaps could report green while supported native behavior was broken. Latency no longer outweighs that missing signal.
+
+**Restore the pre-Wine workflow verbatim.** The old definition captured the right runner boundary but also carried then-current provisioning and topology assumptions. Reconstructing the native job against the current actions, pnpm setup, gate graph, and aggregate dependency avoids reviving obsolete machinery.
+
+**Run native Windows only after merge.** A post-merge reference diagnoses portability regressions after they enter `master`; it cannot protect a pull request while those references are disabled or delayed.
+
+**Use an organization-owned larger Windows runner.** Larger images can reduce wall clock, but a required correctness path would then depend on repository-external labels and allocation. Standard `windows-2025` is the portable recovery boundary; larger runners remain benchmark targets.
+
+## Consequences
+
+Pull requests receive a real NT kernel, NTFS, PowerShell, Windows process, and native addon signal before the aggregate can pass. The job is slower than the Wine compatibility lane and can queue on Windows capacity, but its green result now describes the supported host rather than an approximation.
+
+Removing the Wine cache producer and local script deletes a separate install topology and its recurring compatibility failures. Native coverage and snapshots remain a named gap rather than being implied by the job name; they require their own tested contract before becoming part of this required lane.
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
new file mode 100644
index 0000000000..8728f0eb08
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 原生 Windows 拉取请求 CI
+
+Status: implemented
+
+[English](2026-08-08-native-windows-pull-request-ci.md) | 中文
+
+## 问题
+
+拉取请求必需的 Windows 判定必须为依赖操作系统的行为提供保障，而不能只覆盖由 `process.platform` 选择的工具链分支。Wine 通道在 Linux 内核与区分大小写的 ext4 之上执行 Windows Node 和 PE 二进制文件，要求采用 hoisted 依赖布局和由宿主侧创建的符号链接，也没有覆盖 NTFS、DACL、ConPTY、崩溃持久性与更广泛的观测性 Windows 清单。原生串行参考流程停用期间，常规 CI 没有任何真实的 Windows 内核信号。
+
+## 决策
+
+[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业在 GitHub 标准 `windows-2025` 镜像上使用原生 PowerShell 运行。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并运行 `pnpm run check:ci:windows-complete`。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项；其显示名称为 `windows node 24 / native complete`。
+
+聚合作业继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
+
+受支持的工作流不含 Wine 专属基础设施：不存在 apt 缓存生产者、兼容性脚本、对仓库快照执行的 hoisted 安装、Windows Node 下载或本地 `check:windows-wine` 命令。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)仍作为其实测延迟与保真度取舍的历史证据，而非当前执行路径。
+
+## 曾考虑的替代方案
+
+**在必需路径上保留 Wine。** 其热运行墙钟时间接近 Linux CI，也会选择 win32 工具链分支；但兼容性专属布局和内核缺口可能在受支持的原生行为已经损坏时仍报告绿灯。这项延迟收益不足以抵消该信号缺失的代价。
+
+**逐字恢复 Wine 之前的工作流。** 旧定义确实捕获了正确的运行器边界，但也携带了当时的供应方式与拓扑假设。按照当前 action、pnpm 设置、门禁图和聚合依赖关系重新构建原生作业，可以避免重新引入过时机制。
+
+**只在合并后运行原生 Windows。** 合并后的参考流程只能在可移植性回归进入 `master` 后进行诊断；当这些参考流程被停用或延迟时，无法在拉取请求阶段提供保护。
+
+**使用组织自有的大型 Windows 运行器。** 更大规格的运行器镜像可以缩短墙钟时间，但必需的正确性路径将因此依赖仓库外部的运行器标签与分配能力。标准 `windows-2025` 是可移植恢复边界；大型运行器仍作为基准测试目标。
+
+## 后果
+
+在聚合作业通过之前，拉取请求会获得来自真实 NT 内核、NTFS、PowerShell、Windows 进程和原生插件的信号。该作业比 Wine 兼容性通道更慢，也可能因 Windows 容量而排队，但其绿灯结果描述的是受支持的宿主，而非近似环境。
+
+移除 Wine 缓存生产者和本地脚本后，独立的安装拓扑及其反复出现的兼容性故障也随之消失。原生 Windows 覆盖率与快照仍是明确列出的缺口，不会仅由作业名称暗示已经纳入；二者都必须先建立各自经过测试的契约，才能成为该必需通道的一部分。
diff --git a/.github/AGENTS.md b/.github/AGENTS.md
index ff4fd4e6b2..c95b85e8e2 100644
--- a/.github/AGENTS.md
+++ b/.github/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — GitHub Actions
 
-Run jobs on Windows runners (`windows-*` labels) under native `pwsh`. The pull-request `windows` job is not one of them: it runs Windows Node under Wine on hosted Linux, so its steps are bash — see the [Wine lane Agent Note](../.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md).
+Run jobs on Windows runners (`windows-*` labels) under native `pwsh`.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 46ab8e892f..0e96d50e50 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -300,27 +300,29 @@ jobs:
       - name: Run complete keyless Python suite
         run: uv run --python 3.10 --group test --project python/sdk pytest
 
-  # The required pull-request Windows signal: the two blocking win32 surfaces
-  # (workspace build, production site) execute with real, checksum-verified
-  # Windows Node under Wine on standard hosted Linux. The master
-  # serial-windows job below normally keeps the complete native-kernel
-  # inventory — including the observational portability gates this lane does
-  # not run —
-  # on real windows-2025. This job only provisions runner state (caches,
-  # apt); scripts/wine-windows-gates.sh owns the gate logic and is the same
-  # script the optional local gate `pnpm run check:windows-wine` runs.
-  # Layout, fidelity limits, and measured timings live in
-  # .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
+  # One standard Windows box shares setup across the required build/site checks
+  # and the observational portability inventory. Serial worker bounds keep this
+  # recovery path portable; Linux owns duplicate lint, coverage, and snapshots.
+  # See the native-Windows pull-request CI decision:
+  # .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
   windows:
     if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
-    name: windows node 24 / wine blocking
-    timeout-minutes: 15
+    runs-on: windows-2025
+    name: windows node 24 / native complete
+    env:
+      DSH_GATE_CONCURRENCY: '1'
+      DSH_PUBLINT_CONCURRENCY: '1'
     steps:
       - uses: actions/checkout@v6
         with:
           persist-credentials: false
 
+      - name: Enable Developer Mode (symlink support)
+        shell: pwsh
+        run: >-
+          reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
+          /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
+
       - uses: pnpm/action-setup@v4
         with:
           dest: ${{ runner.temp }}/setup-pnpm
@@ -329,86 +331,15 @@ jobs:
         with:
           node-version: ${{ env.PRIMARY_NODE_VERSION }}
 
-      - name: Configure pnpm store path
-        id: pnpm-store
-        run: |
-          store_root="$HOME/.local/share/pnpm/store"
-          echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV"
-          store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)
-          echo "path=$store_path" >> "$GITHUB_OUTPUT"
+      # Extracting the many-file pnpm store cache is slower than a clean install,
+      # and saving it adds more latency after the gates.
+      - name: Install (immutable)
+        shell: pwsh
+        run: pnpm install --frozen-lockfile
 
-      - uses: actions/cache/restore@v4
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
-
-      # Master's wine-apt-cache job seeds the default-branch scope every pull
-      # request can read; a save from this job only reaches reruns of the
-      # same merge ref.
-      - name: Compose Wine apt cache key
-        id: wine-cache-key
-        run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
-
-      - uses: actions/cache@v4
-        with:
-          path: ~/wine-debs
-          key: ${{ steps.wine-cache-key.outputs.key }}
-
-      # Runner provisioning only — a developer machine installs Wine through
-      # its own package manager; the gate script assumes a wine binary and
-      # fails loud without one. Wine from the apt cache when present; else
-      # download the full dependency closure once and keep it for the next
-      # run. The `wine` dispatcher package (not bare `wine64`) is what puts a
-      # binary on PATH.
-      - name: Install Wine
-        run: |
-          if compgen -G "$HOME/wine-debs/*.deb" > /dev/null; then
-            sudo apt-get install -y --no-install-recommends "$HOME"/wine-debs/*.deb
-          else
-            sudo apt-get update
-            sudo apt-get install -y --no-install-recommends --download-only wine
-            mkdir -p "$HOME/wine-debs"
-            cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/" 2>/dev/null || true
-            sudo apt-get install -y --no-install-recommends wine
-          fi
-
-      - name: Run the Wine Windows gates
-        run: bash scripts/wine-windows-gates.sh
-
-      - name: Shut down wineserver
-        if: always()
-        run: wineserver -k 2>/dev/null || true
-
-  # Master seeds the Wine apt-archive cache in the default-branch scope,
-  # which every pull request's windows job can restore; saves from
-  # pull-request runs are scoped to their own merge ref and help nobody
-  # else. Runs in seconds when the image version already has a cache.
-  wine-apt-cache:
-    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
-    name: wine apt cache
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - name: Compose Wine apt cache key
-        id: wine-cache-key
-        run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
-
-      - uses: actions/cache@v4
-        id: wine-cache
-        with:
-          path: ~/wine-debs
-          key: ${{ steps.wine-cache-key.outputs.key }}
-
-      - name: Download the Wine dependency closure
-        if: steps.wine-cache.outputs.cache-hit != 'true'
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends --download-only wine
-          mkdir -p "$HOME/wine-debs"
-          cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/"
-          du -sh "$HOME/wine-debs"
+      - name: Run blocking and observational Windows gates concurrently
+        shell: pwsh
+        run: pnpm run check:ci:windows-complete
 
   # The hosted reference jobs below are temporarily disabled; the self-hosted
   # standby remains active. Each enabled host executes the complete, unsharded
diff --git a/AGENTS.md b/AGENTS.md
index 64f2e944a8..575538bca7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -65,7 +65,6 @@ pnpm run typecheck
 pnpm run lint
 pnpm run duplication    # cross-file TypeScript clone detection
 pnpm run build          # tsc emits lib/types, tsdown bundles runtime
-pnpm run check:windows-wine  # ONLY when diagnosing a known Windows failure (needs wine); CI owns this signal
 pnpm run hygiene        # knip + publint + workspace constraints + NodeNext consumer check
 pnpm run doc-sync       # all documentation gates; leaf list in scripts/run-gates.ts
 pnpm run website:build  # VitePress build (doubles as dead-link check)
diff --git a/package.json b/package.json
index 423cbf813c..193e83dc1c 100644
--- a/package.json
+++ b/package.json
@@ -57,7 +57,6 @@
     "check:ci:windows-blocking": "tsx scripts/run-gates.ts ci-windows-blocking",
     "check:ci:windows-complete": "tsx scripts/run-gates.ts ci-windows-complete",
     "check:ci:windows-observational": "tsx scripts/run-gates.ts ci-windows-observational",
-    "check:windows-wine": "bash scripts/wine-windows-gates.sh",
     "check:node-compat": "tsx scripts/run-gates.ts node-compat",
     "knip": "knip --treat-config-hints-as-errors",
     "publint": "tsx scripts/publint-all.ts",
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index baeac7a8c0..b5d161dae7 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -26,6 +26,28 @@ describe('CI workflow', () => {
       })
     }
   })
+
+  it('runs the required Windows contract on a native hosted runner', () => {
+    const workflow = loadWorkflow('.github/workflows/ci.yml')
+    if (!isRecord(workflow.jobs) || !isRecord(workflow.jobs.windows)) {
+      throw new TypeError('CI workflow must define the windows job')
+    }
+
+    const windows = workflow.jobs.windows
+    if (!Array.isArray(windows.steps)) throw new TypeError('windows job must define steps')
+    const steps: unknown[] = windows.steps
+    const commandSteps = steps.filter((step): step is Record<string, unknown> & { run: string } => (
+      isRecord(step) && typeof step.run === 'string'
+    ))
+
+    expect(windows['runs-on']).toBe('windows-2025')
+    expect(windows.name).toBe('windows node 24 / native complete')
+    expect(commandSteps).toHaveLength(3)
+    expect(commandSteps.every(step => step.shell === 'pwsh')).toBe(true)
+    expect(commandSteps.map(step => step.run)).toContain('pnpm run check:ci:windows-complete')
+    expect(JSON.stringify(windows)).not.toMatch(/wine/i)
+    expect(workflow.jobs).not.toHaveProperty('wine-apt-cache')
+  })
 })
 
 describe('Issue lifecycle workflow', () => {
diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
deleted file mode 100755
index b6d8ffffb0..0000000000
--- a/scripts/wine-windows-gates.sh
+++ /dev/null
@@ -1,247 +0,0 @@
-#!/usr/bin/env bash
-# Run the blocking Windows gates (workspace build, production site) with real
-# win-x64 Node.js under Wine — the same script the pull-request `windows` job
-# in ci.yml executes and the optional local gate `pnpm run check:windows-wine`
-# wraps. Owning rationale, fidelity limits, and measured timings:
-# .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
-#
-# The working tree is never mutated: tracked plus untracked-unignored files
-# are snapshotted into a scratch directory, the Wine-specific pnpm overrides
-# (hoisted layout, win32-x64 platform packages) are appended to the SNAPSHOT's
-# pnpm-workspace.yaml, and the install and gates run there against the shared
-# pnpm store. The Wine prefix and the checksum-verified Windows Node zip
-# persist in .cache/wine-windows/ so reruns skip provisioning.
-#
-# Environment: DSH_WINE_NODE_MAJOR (default $PRIMARY_NODE_VERSION, then 24)
-# picks the Windows Node line; DSH_WINE_GATE_CACHE_DIR relocates the cache;
-# DSH_WINE_GATE_KEEP=1 preserves the scratch tree for inspection.
-
-set -euo pipefail
-
-repo_root="$(git rev-parse --show-toplevel)"
-node_major="${DSH_WINE_NODE_MAJOR:-${PRIMARY_NODE_VERSION:-24}}"
-cache_dir="${DSH_WINE_GATE_CACHE_DIR:-$repo_root/.cache/wine-windows}"
-
-export WINEDEBUG='-all'
-export WINEARCH=win64
-# Skip Wine Mono / Gecko installers: Node needs neither.
-export WINEDLLOVERRIDES='mscoree,mshtml='
-export WINEPREFIX="$cache_dir/prefix"
-
-# ---- preflight: fail loud before any expensive work --------------------
-wine_bin=''
-for candidate in "$(command -v wine || true)" "$(command -v wine64 || true)" /usr/lib/wine/wine64; do
-  if [ -n "$candidate" ] && [ -x "$candidate" ]; then wine_bin="$candidate"; break; fi
-done
-# GNU coreutils sha256sum on Linux; perl shasum ships with macOS. Both
-# accept the same "<hash>  <file>" --check input.
-checksum_tool=''
-if command -v sha256sum > /dev/null; then
-  checksum_tool='sha256sum'
-elif command -v shasum > /dev/null; then
-  checksum_tool='shasum'
-fi
-missing=()
-[ -n "$wine_bin" ] || missing+=('wine (apt: wine | brew: wine-stable)')
-command -v curl > /dev/null || missing+=('curl')
-command -v unzip > /dev/null || missing+=('unzip')
-[ -n "$checksum_tool" ] || missing+=('sha256sum or shasum (apt: coreutils | macOS ships shasum)')
-if ! command -v pnpm > /dev/null; then corepack enable > /dev/null 2>&1 || true; fi
-command -v pnpm > /dev/null || missing+=('pnpm (corepack enable)')
-if (( ${#missing[@]} > 0 )); then
-  printf 'wine-windows-gates: missing required tool: %s\n' "${missing[@]}" >&2
-  exit 1
-fi
-
-# Verify file $2 against SHA-256 hex $1 with whichever tool preflight found.
-verify_sha256() {
-  case "$checksum_tool" in
-    sha256sum) printf '%s  %s\n' "$1" "$2" | sha256sum --check - > /dev/null ;;
-    shasum) printf '%s  %s\n' "$1" "$2" | shasum -a 256 --check - > /dev/null ;;
-  esac
-}
-
-scratch="$(mktemp -d "${TMPDIR:-/tmp}/dsh-wine-gates.XXXXXX")"
-cleanup() {
-  wineserver -k > /dev/null 2>&1 || true
-  if [ "${DSH_WINE_GATE_KEEP:-0}" = '1' ]; then
-    echo "wine-windows-gates: scratch tree kept at $scratch"
-  else
-    rm -rf "$scratch"
-  fi
-}
-trap cleanup EXIT
-mkdir -p "$cache_dir" "$scratch/logs"
-
-# ---- provision Windows Node, boot Wine, snapshot + install concurrently ----
-provision_node() {
-  # Latest release of the primary line, checksum-verified against the same
-  # dist directory. Offline runs fall back to the newest cached zip, loudly.
-  local version zip
-  version="$(curl -fsSL --max-time 30 https://nodejs.org/dist/index.json 2> /dev/null \
-    | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const v=JSON.parse(d).find(r=>r.version.startsWith('v$node_major.'));if(v)console.log(v.version)})" \
-    || true)"
-  if [ -n "$version" ]; then
-    zip="$cache_dir/node-$version-win-x64.zip"
-    if [ ! -f "$zip" ]; then
-      curl -fsSL -o "$zip.tmp" "https://nodejs.org/dist/$version/node-$version-win-x64.zip"
-      local expected
-      expected="$(curl -fsSL "https://nodejs.org/dist/$version/SHASUMS256.txt" \
-        | awk -v a="node-$version-win-x64.zip" '$2 == a { print $1; exit }')"
-      [ -n "$expected" ] || { echo "wine-windows-gates: no SHASUMS256 entry for node-$version-win-x64.zip" >&2; exit 1; }
-      verify_sha256 "$expected" "$zip.tmp"
-      mv "$zip.tmp" "$zip"
-    fi
-  else
-    zip="$(ls -t "$cache_dir"/node-v"$node_major".*-win-x64.zip 2> /dev/null | head -1 || true)"
-    [ -n "$zip" ] || { echo "wine-windows-gates: nodejs.org unreachable and no cached Windows Node v$node_major zip in $cache_dir" >&2; exit 1; }
-    echo "wine-windows-gates: nodejs.org unreachable; using cached $(basename "$zip")" >&2
-  fi
-  unzip -q -o "$zip" -d "$scratch/node-win"
-  echo "$scratch/node-win/$(basename "$zip" .zip)/node.exe" > "$scratch/node-win-path"
-}
-
-boot_wine() {
-  "$wine_bin" wineboot --init > /dev/null 2>&1 || true
-  wineserver -w || true
-}
-
-snapshot_and_install() {
-  # Tracked + untracked-unignored files, minus agent-session litter; the
-  # existence filter drops paths staged as deleted. Then the Wine-specific
-  # install-time overrides go on the SNAPSHOT only: hoisted because Windows
-  # Node under Wine does not realpath pnpm's isolated-layout symlinks, and
-  # win32-x64 so the Windows esbuild/rolldown/rollup binaries materialize.
-  # Neither is recorded in the lockfile, so --frozen-lockfile stays valid;
-  # --ignore-scripts skips host lifecycle scripts no gate loads.
-  git -C "$repo_root" ls-files -z --cached --others --exclude-standard -- . ':!:.claude' ':!:.codex' \
-    | while IFS= read -r -d '' file; do [ -e "$repo_root/$file" ] && printf '%s\0' "$file"; done \
-    | tar -C "$repo_root" --null --files-from=- -cf - \
-    | tar -C "$scratch/tree" -xf -
-  cat >> "$scratch/tree/pnpm-workspace.yaml" << 'EOF'
-
-nodeLinker: hoisted
-supportedArchitectures:
-  os: [current, win32]
-  cpu: [current, x64]
-EOF
-  # The hoisted linker — used only by this lane — has an upstream rename
-  # race (pnpm/pnpm#12880): parallel linkers staging a nested package copy
-  # (observed on the tree's nested esbuild versions) rename their _tmp_*
-  # directory onto a path another racer already claimed, and the loser
-  # exits ERR_PNPM_ENOENT although an identical re-install succeeds.
-  # Exactly that signature earns up to two retries on a clean tree — the
-  # snapshot contains no node_modules, so wiping them restores the
-  # pre-install state; any other failure, or the race still standing after
-  # the final attempt, fails loud with the log tail.
-  local attempt
-  for attempt in 1 2 3; do
-    (cd "$scratch/tree" && pnpm install --frozen-lockfile --ignore-scripts > "$scratch/logs/install.log" 2>&1) \
-      && return 0
-    grep -q 'ERR_PNPM_ENOENT.*rename.*_tmp_' "$scratch/logs/install.log" || break
-    (( attempt < 3 )) || break
-    echo "wine-windows-gates: pnpm hoisted-linker rename race (pnpm/pnpm#12880) on install attempt $attempt; retrying on a clean tree" >&2
-    find "$scratch/tree" -name node_modules -type d -prune -exec rm -rf {} +
-  done
-  tail -40 "$scratch/logs/install.log" >&2
-  return 1
-}
-
-mkdir "$scratch/tree"
-start=$SECONDS
-provision_node & node_pid=$!
-boot_wine & wine_pid=$!
-snapshot_and_install & install_pid=$!
-# Wait for EVERY child before judging any: a bare `wait` under set -e would
-# exit on the first failure and let the EXIT trap delete $scratch while the
-# other children still run inside it. Named statuses also make the report
-# point at the root cause instead of a downstream symptom.
-node_status=0; wait "$node_pid" || node_status=$?
-wine_status=0; wait "$wine_pid" || wine_status=$?
-install_status=0; wait "$install_pid" || install_status=$?
-provision_failed=0
-report_provision() {
-  if (( $2 != 0 )); then
-    echo "wine-windows-gates: FAILED $1 (exit $2)" >&2
-    provision_failed=$2
-  fi
-}
-report_provision 'Windows Node provisioning' "$node_status"
-report_provision 'wineboot' "$wine_status"
-report_provision 'workspace snapshot + pnpm install' "$install_status"
-if (( provision_failed != 0 )); then exit "$provision_failed"; fi
-node_win="$(cat "$scratch/node-win-path")"
-echo "wine-windows-gates: provisioned in $((SECONDS - start))s (wine $("$wine_bin" --version 2> /dev/null), node $(basename "$(dirname "$node_win")"))"
-
-# ---- resolve entrypoints, lay the vue link, smoke ------------------------
-# Node under Wine cannot attach stdio to pipes the caller owns (Socket open
-# EBADF at bootstrap), so every invocation routes stdio through a file.
-wine_node() {
-  local log="$1"
-  shift
-  local status=0
-  "$wine_bin" "$node_win" "$@" < /dev/null > "$log" 2>&1 || status=$?
-  return "$status"
-}
-
-cd "$scratch/tree"
-tsc_js='node_modules/typescript/bin/tsc'
-tsdown_js='node_modules/tsdown/dist/run.mjs'
-vitepress_js='node_modules/vitepress/bin/vitepress.js'
-[ -f "$vitepress_js" ] || vitepress_js='website/node_modules/vitepress/bin/vitepress.js'
-for entry in "$tsc_js" "$tsdown_js" "$vitepress_js"; do
-  [ -f "$entry" ] || { echo "wine-windows-gates: expected entrypoint missing after hoisted install: $entry" >&2; exit 1; }
-done
-# VitePress links vue into the site's node_modules at build time; Wine cannot
-# CREATE Windows symlinks (ENOTSUP) but follows pre-existing Unix ones.
-if [ -d node_modules/vue ] && [ ! -e website/node_modules/vue ]; then
-  mkdir -p website/node_modules
-  ln -s ../../node_modules/vue website/node_modules/vue
-fi
-
-wine_node "$scratch/logs/smoke.log" -p "'smoke: ' + process.platform + ' ' + process.arch + ' ' + process.version"
-cat "$scratch/logs/smoke.log"
-grep -q '^smoke: win32 x64' "$scratch/logs/smoke.log" || { echo 'wine-windows-gates: Windows Node smoke did not report win32 x64' >&2; exit 1; }
-
-# ---- the two blocking surfaces, concurrently ------------------------------
-# The build preserves the face order from package.json: compile and bundle the
-# Host face before compiling and bundling the Client face.
-# Both statuses are captured so one failure cannot hide the other's result.
-build_gate() {
-  wine_node "$scratch/logs/host-tsc.log" "$tsc_js" -b tsconfig.host.json --pretty false || return $?
-  wine_node "$scratch/logs/host-tsdown.log" "$tsdown_js" --env.DSH_BUILD_FACE host || return $?
-  wine_node "$scratch/logs/client-tsc.log" "$tsc_js" -b tsconfig.client.json --pretty false || return $?
-  wine_node "$scratch/logs/client-tsdown.log" "$tsdown_js" --env.DSH_BUILD_FACE client
-}
-site_gate() {
-  cd website
-  wine_node "$scratch/logs/site.log" "../$vitepress_js" build .
-}
-
-start=$SECONDS
-build_gate & build_pid=$!
-site_gate & site_pid=$!
-build_status=0
-wait "$build_pid" || build_status=$?
-site_status=0
-wait "$site_pid" || site_status=$?
-elapsed=$((SECONDS - start))
-
-report() {
-  local label="$1" status="$2"
-  shift 2
-  if (( status == 0 )); then
-    echo "wine-windows-gates: PASS $label (${elapsed}s window)"
-  else
-    echo "== FAILED $label (exit $status) ==" >&2
-    for log in "$@"; do tail -n 200 "$log" >&2 || true; done
-  fi
-}
-report 'build (Host tsc/tsdown, Client tsc/tsdown)' "$build_status" \
-  "$scratch/logs/host-tsc.log" \
-  "$scratch/logs/host-tsdown.log" \
-  "$scratch/logs/client-tsc.log" \
-  "$scratch/logs/client-tsdown.log"
-report 'production site (vitepress build)' "$site_status" "$scratch/logs/site.log"
-if (( build_status != 0 )); then exit "$build_status"; fi
-exit "$site_status"

From b0eb7f8f35e385ad32b0a8af6e407de8f859c65f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 01:23:26 +0800
Subject: [PATCH 265/516] docs: define unified GitHub label taxonomy

---
 ...07-25-semantic-pr-label-taxonomy.i18n.yaml |  4 +-
 .../2026-07-25-semantic-pr-label-taxonomy.md  | 65 +++++++------------
 ...026-07-25-semantic-pr-label-taxonomy.zh.md | 65 +++++++------------
 AGENTS.md                                     |  2 +-
 4 files changed, 53 insertions(+), 83 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml
index 1aaa9f992b..a83236521c 100644
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.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 .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
-2026-07-25-semantic-pr-label-taxonomy.md: 3217b405e968d4d2c1eba1f1a5a08008b18ba514
-2026-07-25-semantic-pr-label-taxonomy.zh.md: 978f11af9402f248679e2087ff7fb513321b69b9
+2026-07-25-semantic-pr-label-taxonomy.md: 6aef5ecbb80005d1fcd90b4ee673bbbebb92cba6
+2026-07-25-semantic-pr-label-taxonomy.zh.md: 0bd3fbcaeca37fa894e92ce5a4e78c4125056ac9
diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
index 3217b405e9..6aef5ecbb8 100644
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
+++ b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
@@ -6,66 +6,51 @@ English | [中文](2026-07-25-semantic-pr-label-taxonomy.zh.md)
 
 ## Problem
 
-Pull requests need two different signals: what kind of change they make and which repository domains they affect. A flat or broadly named label set conflates those questions, hides work in distinct areas such as `session` and `llm`, and gives reviewers and automation weak inputs.
+Pull request labels answer two independent questions: what kind of change the work makes and which durable repository domains it materially affects. Mixing those dimensions or keeping synonymous labels makes queries ambiguous, while a closed area inventory forces new domains into inaccurate categories.
 
-The repository also gains new domains over time. Treating today's area labels as a closed set would force future work into inaccurate labels or a generic catch-all.
+Issues already have a native Type and a separate source taxonomy. Reusing pull request kind or source labels across both object types duplicates metadata and weakens the meaning of each label family.
 
 ## Decision
 
-Every open or merged pull request carries exactly one kind and every materially affected area. Closed pull requests that were never merged are outside the maintained historical corpus. Other operational labels may coexist, but they do not satisfy either dimension.
+Every open or merged pull request carries exactly one canonical `kind/*` label and at least one materially affected `area/*` label. Closed pull requests that were never merged retain migrated historical assignments but do not receive invented missing classification. Operational labels may coexist without satisfying either dimension.
 
 ### Kinds
 
+The kind set is closed and mutually exclusive:
+
 | Kind | Meaning |
 |---|---|
-| `feature` | Adds or intentionally changes behavior. |
-| `bug-fix` | Corrects incorrect behavior. |
-| `doc` | Makes documentation the dominant intent. |
-| `testing` | Changes tests or testing infrastructure without changing product behavior. |
-| `cleanup` | Preserves behavior while maintaining or simplifying the implementation or repository process. |
+| `kind/feature` | Adds or intentionally changes behavior. |
+| `kind/bug-fix` | Corrects incorrect behavior. |
+| `kind/doc` | Makes documentation the dominant intent. |
+| `kind/testing` | Changes tests or testing infrastructure without changing product behavior. |
+| `kind/cleanup` | Preserves behavior while maintaining or simplifying implementation or repository process. |
+| `kind/dependency` | Updates dependencies without another dominant intent. |
 
-The kind records the change's dominant intent: accompanying tests and documentation do not turn a feature or bug fix into a testing or documentation change.
+The kind records the dominant intent. Accompanying tests, documentation, cleanup, or dependency movement do not override a feature or bug fix.
 
-Areas record semantic repository domains rather than temporary initiatives, ownership, or every path touched incidentally. Area labels are not a hierarchy: a pull request may carry several when it changes distinct contracts, but an umbrella and a narrower label do not both describe the same work.
+### Areas
 
-### Current areas
+Areas name durable semantic domains rather than temporary initiatives, ownership, or every path touched incidentally. A pull request carries multiple areas when it changes distinct contracts, but it does not combine an umbrella and a narrower label for the same contract. GitHub's live `area/*` names and descriptions own the current inventory.
 
-The 46 current areas are listed below. The group names organize the list for readability; they are not labels or another taxonomy level.
+The area set is intentionally extensible. When no existing description honestly covers a durable and reusable repository domain, an agent is empowered to create a concise `area/<lowercase-kebab-case>` label without separate approval. The agent must not create an area for one pull request, an incidental path, a temporary project, a status, or a person or team, and must report the new label after applying it. Reusing an inaccurate area merely to avoid a justified addition is not acceptable.
 
-| Group | Areas |
-|---|---|
-| Agent and model | `agent`, `agent-loop`, `session`, `llm`, `model-context`, `compaction`, `tools`, `persistence` |
-| Orchestration | `subagent`, `workflow`, `planning`, `tasks`, `schedule`, `telemetry`, `storage`, `workspace` |
-| Capabilities | `bash`, `subprocess`, `pty`, `filesystem`, `lsp`, `skills`, `web-search`, `code-mode`, `artifact`, `attachment`, `sandbox`, `mcp`, `hooks`, `cordis` |
-| Interfaces | `ui`, `gui`, `tui`, `acp`, `json-rpc`, `cli`, `python-sdk`, `vscode`, `website` |
-| Repository and release | `dev-infra`, `ci`, `build`, `dependencies`, `platform`, `i18n`, `release` |
+Kinds are not extended this way. A new kind changes the mutually exclusive classification contract and requires an explicit taxonomy change with corresponding policy enforcement.
 
-`gui` covers browser and Electron graphical applications, including standalone graphical developer tools; `vscode` remains the editor extension integration. `ui` covers shared cross-interface commands, approval interaction, presentation, and app boot; it coexists with `gui`, `tui`, or a protocol area only when the pull request also changes that shared contract.
+### Issues and operational labels
 
-`tasks` owns background work tied to a running process, while `schedule` owns durable time-triggered jobs. `tools` owns generic registry, schema, and execution contracts; a concrete capability receives `tools` only when it changes one of those contracts. `attachment` owns durable media references and multimodal input delivery, while `artifact` owns model-declared deliverable identity and preview lifecycle; neither borrows `tools` or `ui` for its implementation parts.
+Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record Issue provenance and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
 
-Names follow semantic ownership rather than lexical resemblance. `hooks` means the Claude Code and Codex agent bridges, not local Git hooks; `platform` means product portability, not CI runner selection; and `build` means compilation, bundling, and built package artifacts, not documentation generators.
-
-### Extensibility
-
-The area set is intentionally extensible. Add an area when a recurring, meaningful repository domain is missing; do not add a label for one pull request, a temporary project, a status, or a person or team. Rename, split, or retire an area when the domain model changes, and update this list and the affected open and merged pull requests together.
-
-The kind set stays narrow because kinds are mutually exclusive. A new kind requires a distinct change intent that cannot be represented by the current five; it is not a substitute for an area.
+Label migrations preserve meaning before removing aliases: add the canonical replacement, verify the labelable, then remove the obsolete assignment. A label is deleted only after no pull request or Issue still uses it, and unrelated labels are never replaced as a set.
 
 ## Alternatives considered
 
-- **One undifferentiated label set.** Rejected because kind and area answer different questions; mixing them makes the presence of one label say nothing about whether the other dimension was considered.
-- **A fixed, closed area set.** Rejected because repository domains evolve. A closed set would preserve spelling at the cost of semantic accuracy.
-- **One broad `core` area or package-derived labels.** Rejected because domains such as `session`, `llm`, and `agent` remain independently meaningful across package boundaries, while incidental file paths are not the scope reviewers or automation need.
-- **Separate browser and desktop areas.** Rejected because browser delivery and Electron packaging expose one graphical client domain; splitting them classifies the delivery shell rather than the semantic work.
-- **Broad implementation areas in place of a domain.** Rejected because a durable scheduled job is not a background task, an attachment is not merely its source interface or filesystem implementation, and an artifact is not merely its declaring tool or preview interface.
-- **Umbrella and leaf areas for the same contract.** Rejected because duplicate labels inflate scope without adding information. Multiple areas remain correct when a pull request changes genuinely distinct contracts.
-- **Exactly one area per pull request.** Rejected because coherent changes can legitimately span several domains, and dropping secondary areas hides affected contracts.
+- **Unprefixed labels.** Rejected because a flat name does not identify whether it classifies intent, domain, source, priority, or automation, and synonymous plain and prefixed labels caused ambiguous queries.
+- **A fixed area allowlist in repository policy.** Rejected because durable repository domains evolve. The `area/*` namespace remains mechanically recognizable while live descriptions carry the extensible inventory.
+- **Kinds on Issues.** Rejected because native Issue Type already owns that classification; duplicating it as a label creates drift.
+- **Automatic areas from paths.** Rejected because areas describe semantic impact across package boundaries, while changed paths include incidental tests, documentation, and support files.
+- **Exactly one area per pull request.** Rejected because coherent changes can materially affect several independent contracts.
 
 ## Consequences
 
-- Reviewers and automation receive one stable intent signal plus a complete semantic scope.
-- `gui` queries cover browser and desktop delivery together, while `ui` queries retain only shared cross-interface contracts.
-- `schedule`, `attachment`, and `artifact` queries identify those domains directly instead of approximating them through implementation dependencies.
-- Selecting labels remains a judgment call: paths and title prefixes can suggest areas, but they cannot replace reading the change.
-- Taxonomy changes carry maintenance work. Area additions, renames, splits, and removals update this decision record and backfill open and merged pull requests so historical queries keep their meaning.
+Reviewers and automation can query intent, semantic scope, provenance, priority, and operational triggers independently. Maintainers must read the change and live label descriptions rather than infer classification from title prefixes or paths, and taxonomy migrations carry an explicit historical backfill and verification cost.
diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
index 978f11af94..0bd3fbcaec 100644
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
+++ b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
@@ -6,66 +6,51 @@ Status: implemented
 
 ## 问题
 
-PR（Pull Request）需要传达两个不同的信号：它带来哪一类变更，以及会影响仓库中的哪些领域。一套扁平或命名宽泛的标签会混淆这两个问题，掩盖 `session`、`llm` 等不同领域的工作，也让评审人和自动化流程得到的输入缺乏有效信息。
+PR（Pull Request）标签回答两个相互独立的问题：工作带来哪一类变更，以及会对哪些持久的仓库领域产生实质影响。混用这两个维度或保留同义标签会使查询含义模糊，而封闭的领域清单会迫使新领域被归入不准确的类别。
 
-仓库还会随时间发展出新的领域。如果把当前的领域标签视为封闭集合，未来的工作就只能归入不准确的标签或通用兜底标签。
+Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对象上复用 PR 类型或来源标签会产生重复元数据，并削弱每个标签族的含义。
 
 ## 决策
 
-每项开放或已合并的 PR 都带有恰好一个类型标签，以及所有受到实质影响的领域标签。未合并即关闭的 PR 不属于持续维护的历史记录集合。其他管理用途的标签可以并存，但都不能满足这两个维度中的任一个。
+每项开放或已合并的 PR 都带有恰好一个规范的 `kind/*` 标签，以及至少一个受到实质影响的 `area/*` 标签。未合并即关闭的 PR 保留经迁移的历史标签关系，但不会凭空补充缺失分类。管理用途的标签可以并存，但不能满足这两个维度中的任一个。
 
 ### 类型
 
+类型集合封闭且互斥：
+
 | 类型 | 含义 |
 |---|---|
-| `feature` | 新增行为或有意改变行为。 |
-| `bug-fix` | 修正错误行为。 |
-| `doc` | 以文档变更为主要意图。 |
-| `testing` | 修改测试或测试基础设施，但不改变产品行为。 |
-| `cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
+| `kind/feature` | 新增行为或有意改变行为。 |
+| `kind/bug-fix` | 修正错误行为。 |
+| `kind/doc` | 以文档变更为主要意图。 |
+| `kind/testing` | 修改测试或测试基础设施，但不改变产品行为。 |
+| `kind/cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
+| `kind/dependency` | 在没有其他主要意图时更新依赖。 |
 
-类型记录变更的主要意图：配套测试与文档并不会把一项功能或缺陷修复变成测试或文档变更。
+类型记录主要意图。配套测试、文档、清理或依赖调整不会覆盖一项功能或缺陷修复的主要意图。
 
-领域记录仓库中的语义领域，而不是临时项目、归属关系或偶然触及的每条路径。领域标签不构成层级：一项 PR 修改不同契约时可以带有多个领域标签，但不能用一个总括标签和一个较窄标签重复描述同一项工作。
+### 领域
 
-### 当前领域
+领域表示持久的语义领域，而不是临时项目、归属关系或偶然触及的每条路径。一项 PR 修改不同契约时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项契约。当前分类清单以 GitHub 上实时的 `area/*` 名称和描述为准。
 
-当前的 46 个领域如下。分组名称仅用于提高列表的可读性；它们既不是标签，也不是分类体系中的另一个层级。
+领域集合有意保持可扩展。当现有描述都无法准确涵盖一个持久且可复用的仓库领域时，agent（智能体）有权无须另行批准，直接创建简洁的 `area/<lowercase-kebab-case>` 标签。agent 不得为单个 PR、偶然涉及的路径、临时项目、状态、个人或团队创建领域，并且必须在应用新标签后报告。仅为避免新增一个确有必要的标签而复用不准确的领域，不可接受。
 
-| 分组 | 领域 |
-|---|---|
-| agent（智能体）与模型 | `agent`, `agent-loop`, `session`, `llm`, `model-context`, `compaction`, `tools`, `persistence` |
-| 编排 | `subagent`, `workflow`, `planning`, `tasks`, `schedule`, `telemetry`, `storage`, `workspace` |
-| 能力 | `bash`, `subprocess`, `pty`, `filesystem`, `lsp`, `skills`, `web-search`, `code-mode`, `artifact`, `attachment`, `sandbox`, `mcp`, `hooks`, `cordis` |
-| 接口 | `ui`, `gui`, `tui`, `acp`, `json-rpc`, `cli`, `python-sdk`, `vscode`, `website` |
-| 仓库与发布 | `dev-infra`, `ci`, `build`, `dependencies`, `platform`, `i18n`, `release` |
+类型不以这种方式扩展。新增类型会改变互斥的分类契约，必须明确修改分类体系并同步调整策略强制校验。
 
-`gui` 涵盖浏览器和 Electron 图形应用，包括独立的图形化开发者工具；`vscode` 仍表示编辑器扩展集成。`ui` 涵盖共享的跨接口命令、审批交互、呈现和应用启动；只有当 PR 还修改这项共享契约时，它才与 `gui`、`tui` 或某个协议领域并用。
+### Issue 与管理用途标签
 
-`tasks` 负责与运行中进程绑定的后台工作，`schedule` 则负责持久化的定时作业。`tools` 负责通用的注册表契约、schema 契约和执行契约；具体能力只有在修改其中一项契约时才带有 `tools`。`attachment` 负责持久化的媒体引用和多模态输入传递，`artifact` 则负责模型声明的交付物标识和预览生命周期；二者都不会因实现包含工具或界面部分而借用 `tools` 或 `ui`。
+Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍为可选。`source/*` 标签记录 Issue 来源，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
 
-标签名称以语义归属为准，而不是词面相似性。`hooks` 指 Claude Code 和 Codex 的 agent 桥接，而不是本地 Git 钩子；`platform` 指产品可移植性，而不是 CI 运行器选择；`build` 指编译、打包和已构建的包产物，而不是文档生成器。
-
-### 可扩展性
-
-领域集合有意保持可扩展。当分类体系缺少一个会反复涉及且具有实际意义的仓库领域时，就新增领域；不要仅为一项 PR、临时项目、状态、个人或团队新增标签。当领域模型发生变化时，重命名、拆分或退役相应领域，同时更新本列表以及所有受影响的开放和已合并 PR。
-
-类型集合保持精简，因为各类型互斥。新增类型的前提是存在一种当前五类无法表达的独立变更意图；类型不能用来替代领域。
+迁移标签时，须先保留语义，再移除别名：先添加规范替代标签并验证对象，再移除废弃的标签关系。只有在所有 PR 和 Issue 都不再使用某个标签后才能将其删除，且绝不整组替换无关标签。
 
 ## 曾考虑的替代方案
 
-- **一套不区分维度的标签。** 不予采纳，因为类型与领域回答的是不同问题；两者混在一起时，存在一个维度的标签并不表示另一个维度也经过了考虑。
-- **一套固定、封闭的领域集合。** 不予采纳，因为仓库领域会持续演变。封闭集合会以牺牲语义准确性为代价来维持拼写不变。
-- **一个宽泛的 `core` 领域，或从包结构派生的标签。** 不予采纳，因为 `session`、`llm` 和 `agent` 等领域在跨越包边界时仍各自具有意义，而偶然涉及的文件路径并不是评审人或自动化流程所需的范围信息。
-- **为浏览器和桌面端分别设置领域。** 不予采纳，因为浏览器交付和 Electron 打包共同呈现同一个图形客户端领域；拆开二者将按交付形态而非工作的语义进行分类。
-- **以宽泛的实现领域替代语义领域。** 不予采纳，因为持久化的定时作业不是后台任务，附件不只是其来源接口或文件系统实现，产物也不只是声明它的工具或预览接口。
-- **同一项契约同时使用总括领域与细分领域。** 不予采纳，因为重复标签只会虚增范围，不会增加信息。一项 PR 确实修改不同契约时，多个领域标签仍然合理。
-- **每项 PR 恰好一个领域。** 不予采纳，因为一项内聚的变更可以合理地跨越多个领域；省略次要领域会隐藏受影响的契约。
+- **无前缀标签。** 不予采纳，因为扁平名称无法表明其表示的是意图、领域、来源、优先级还是自动化用途，而同义的无前缀和带前缀标签会使查询含义模糊。
+- **在仓库策略中使用固定的领域允许列表。** 不予采纳，因为持久的仓库领域会持续演变。`area/*` 命名空间仍可由机制识别，而实时描述负责承载可扩展的分类清单。
+- **在 Issue 上使用类型标签。** 不予采纳，因为原生 Issue Type 已负责这项分类；再用标签重复表示会产生漂移。
+- **从路径自动生成领域。** 不予采纳，因为领域描述跨越包边界的语义影响，而变更路径还会包含偶然涉及的测试、文档和支持文件。
+- **每项 PR 恰好一个领域。** 不予采纳，因为一项内聚的变更可以对多个独立契约产生实质影响。
 
 ## 后果
 
-- 评审人和自动化流程获得一个稳定的意图信号，以及完整的语义范围。
-- `gui` 查询会同时覆盖浏览器与桌面端交付，`ui` 查询则只涵盖共享的跨接口契约。
-- `schedule`、`attachment` 与 `artifact` 查询直接对应各自领域，无需通过实现依赖近似归类。
-- 选择标签仍然需要判断：路径和标题前缀可以提示领域，但不能替代阅读变更内容。
-- 变更分类体系会产生维护工作。新增、重命名、拆分或移除领域时，需要更新本决策记录，并回填开放和已合并的 PR，使历史查询保持原有含义。
+评审人和自动化流程可以分别查询意图、语义范围、来源、优先级和工作流触发器。维护者必须阅读变更内容和实时标签描述，而不能根据标题前缀或路径推断分类；迁移分类体系还会产生明确的历史回填与验证成本。
diff --git a/AGENTS.md b/AGENTS.md
index 64f2e944a8..90b2ab4a67 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -118,7 +118,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
 - **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
-- **Label PRs:** one kind (`feature`/`bug-fix`/`doc`/`testing`/`cleanup`), each matching area; the [taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md) is extensible.
+- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([workflow](.agents/skills/dsh-labeling/SKILL.md)).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
 

From a9abb62195f438c61b163fa2e9b8133b1523e4a9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 01:23:36 +0800
Subject: [PATCH 266/516] chore: enforce unified GitHub labels

---
 .github/dependabot.yml                   |   6 +-
 .github/issue-management/policy.mjs      |  43 +++++++++-
 .github/issue-management/policy.test.mjs | 100 ++++++++++++++++++++---
 AGENTS.md                                |   2 +-
 4 files changed, 132 insertions(+), 19 deletions(-)

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 524d7912e2..dd91db8bf1 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -13,7 +13,7 @@ updates:
     cooldown:
       default-days: 30
     labels:
-      - "cleanup"
+      - "kind/dependency"
       - "area/infra"
 
   - package-ecosystem: "uv"
@@ -25,7 +25,7 @@ updates:
     cooldown:
       default-days: 30
     labels:
-      - "cleanup"
+      - "kind/dependency"
       - "area/infra"
 
   - package-ecosystem: "github-actions"
@@ -37,5 +37,5 @@ updates:
     cooldown:
       default-days: 30
     labels:
-      - "cleanup"
+      - "kind/dependency"
       - "area/infra"
diff --git a/.github/issue-management/policy.mjs b/.github/issue-management/policy.mjs
index 608291c4f8..18a9b03628 100644
--- a/.github/issue-management/policy.mjs
+++ b/.github/issue-management/policy.mjs
@@ -12,6 +12,27 @@ const AUDIT_MARKER = '<!-- dsh-issue-policy -->'
 const OWNER_LINE = /^Owner: @([A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?)$/
 const TYPES = new Set(['Idea', 'Feature', 'Bug', 'Research', 'Task'])
 const PRIORITIES = ['p0', 'p1', 'p2', 'p3']
+const PR_KINDS = new Set([
+  'kind/feature',
+  'kind/bug-fix',
+  'kind/doc',
+  'kind/testing',
+  'kind/cleanup',
+  'kind/dependency',
+])
+const LEGACY_LABELS = new Set([
+  'kind/bug',
+  'kind/documentation',
+  'bug-fix',
+  'doc',
+  'cleanup',
+  'testing',
+  'dependencies',
+  'ci',
+  'cli',
+  'llm',
+  'web-search',
+])
 const TERMINAL_STATUSES = new Set(['Done', 'No action'])
 const ACTIVE_STATUS_ORDER = config.statuses.filter((status) => !TERMINAL_STATUSES.has(status))
 
@@ -224,8 +245,14 @@ export function retainIssueReferences(references, issues) {
 export function validateIssue(issue) {
   const errors = validateBody(issue)
   const status = issue.status
+  const invalidLabels = issue.labels.filter(
+    (label) => label.startsWith('kind/') || LEGACY_LABELS.has(label),
+  )
 
   if (!/\p{Script=Han}/u.test(issue.title)) errors.push('Issue 标题必须包含中文')
+  if (invalidLabels.length > 0) {
+    errors.push(`Issue 不得使用 PR kind 或旧版标签：${invalidLabels.join(', ')}`)
+  }
   if (
     /^\s*(?:\[(?:Idea|Feature|Bug|Research|Task|P[0-3]|Inbox|Backlog|Ready|In progress|In review|Done|No action|Owner|area\/[^\]]+)[^\]]*\]|(?:Idea|Feature|Bug|Research|Task|P[0-3]|Inbox|Backlog|Ready|In progress|In review|Done|No action|Owner|area\/[^:： ]+)\s*[:：-])/iu.test(
       issue.title,
@@ -261,12 +288,24 @@ export function validateIssue(issue) {
 export function validatePullRequest(input) {
   if (!requiresPullRequestPolicy(input)) return []
   const errors = []
-  const kinds = input.labels.filter((label) => label.startsWith('kind/'))
+  const kinds = input.labels.filter((label) => PR_KINDS.has(label))
+  const unknownKinds = input.labels.filter(
+    (label) => label.startsWith('kind/') && !PR_KINDS.has(label) && !LEGACY_LABELS.has(label),
+  )
+  const legacyLabels = input.labels.filter((label) => LEGACY_LABELS.has(label))
+  const sourceLabels = input.labels.filter((label) => label.startsWith('source/'))
   const priorities = input.labels.filter((label) => PRIORITIES.includes(label))
   const areas = input.labels.filter((label) => label.startsWith('area/'))
 
   if (input.references.all.length === 0) errors.push('PR 正文必须引用至少一个同仓库 Issue')
-  if (kinds.length !== 1) errors.push(`PR 必须恰好有一个 kind/*，当前为 ${kinds.length}`)
+  if (kinds.length !== 1) {
+    errors.push(`PR 必须恰好有一个允许的 kind/*，当前为 ${kinds.length}`)
+  }
+  if (unknownKinds.length > 0) {
+    errors.push(`PR 含不支持的 kind/*：${unknownKinds.join(', ')}`)
+  }
+  if (legacyLabels.length > 0) errors.push(`PR 含旧版标签：${legacyLabels.join(', ')}`)
+  if (sourceLabels.length > 0) errors.push(`source/* 仅用于 Issue：${sourceLabels.join(', ')}`)
   if (priorities.length > 1) errors.push(`PR 最多有一个 p0–p3，当前为 ${priorities.length}`)
   if (areas.length === 0) errors.push('PR 必须至少有一个 area/*')
   for (const number of input.references.all) {
diff --git a/.github/issue-management/policy.test.mjs b/.github/issue-management/policy.test.mjs
index 86750127a7..bcaf450afa 100644
--- a/.github/issue-management/policy.test.mjs
+++ b/.github/issue-management/policy.test.mjs
@@ -27,6 +27,25 @@ const legalIssue = {
   stateReason: null,
 }
 
+const canonicalKinds = [
+  'kind/feature',
+  'kind/bug-fix',
+  'kind/doc',
+  'kind/testing',
+  'kind/cleanup',
+  'kind/dependency',
+]
+
+const reviewedPull = (labels) => ({
+  isDraft: false,
+  authorType: 'User',
+  reviewRequestCount: 1,
+  reviewCount: 0,
+  labels,
+  references: { all: [2], resolving: [], related: [2] },
+  issues: new Map([[2, { priority: null }]]),
+})
+
 test('counts only text outside details', () => {
   assert.deepEqual(countVisibleUnits('支持 GitHub Project。<details>隐藏文字</details>'), {
     units: 4,
@@ -92,6 +111,32 @@ test('rejects metadata prefixes in an Issue title', () => {
   assert.ok(errors.includes('Issue 标题不得带 Type、Priority、Status、area 或 Owner 前缀'))
 })
 
+test('reserves PR kind and legacy labels for pull requests', () => {
+  for (const label of [
+    ...canonicalKinds,
+    'kind/experimental',
+    'kind/bug',
+    'kind/documentation',
+    'bug-fix',
+    'doc',
+    'cleanup',
+    'testing',
+    'dependencies',
+    'ci',
+    'cli',
+    'llm',
+    'web-search',
+  ]) {
+    assert.ok(
+      validateIssue({ ...legalIssue, labels: [label] }).some((error) =>
+        error.startsWith('Issue 不得使用 PR kind 或旧版标签：'),
+      ),
+      label,
+    )
+  }
+  assert.deepEqual(validateIssue({ ...legalIssue, labels: ['area/web', 'source/member'] }), [])
+})
+
 test('keeps terminal Status aligned with the native close reason', () => {
   assert.deepEqual(
     validateIssue({ ...legalIssue, status: 'Done', state: 'closed', stateReason: 'completed' }),
@@ -260,22 +305,51 @@ test('requires repository PR labels in the enforcement scope', () => {
     references: { all: [2], resolving: [], related: [2] },
     issues: new Map([[2, { priority: null }]]),
   })
-  assert.ok(errors.includes('PR 必须恰好有一个 kind/*，当前为 0'))
+  assert.ok(errors.includes('PR 必须恰好有一个允许的 kind/*，当前为 0'))
   assert.ok(errors.includes('PR 必须至少有一个 area/*'))
 })
 
-test('accepts repository-extensible kind labels', () => {
-  assert.deepEqual(
-    validatePullRequest({
-      isDraft: false,
-      authorType: 'User',
-      reviewRequestCount: 1,
-      reviewCount: 0,
-      labels: ['kind/dependency', 'area/infra'],
-      references: { all: [2], resolving: [], related: [2] },
-      issues: new Map([[2, { priority: null }]]),
-    }),
-    [],
+test('accepts exactly the canonical kinds with extensible areas', () => {
+  for (const kind of canonicalKinds) {
+    assert.deepEqual(validatePullRequest(reviewedPull([kind, 'area/future-domain'])), [], kind)
+  }
+})
+
+test('rejects multiple, unknown, legacy, and Issue-source PR labels', () => {
+  assert.ok(
+    validatePullRequest(
+      reviewedPull(['kind/feature', 'kind/doc', 'area/web']),
+    ).includes('PR 必须恰好有一个允许的 kind/*，当前为 2'),
+  )
+  assert.ok(
+    validatePullRequest(reviewedPull(['kind/experimental', 'area/web'])).includes(
+      'PR 含不支持的 kind/*：kind/experimental',
+    ),
+  )
+  for (const label of [
+    'kind/bug',
+    'kind/documentation',
+    'bug-fix',
+    'doc',
+    'cleanup',
+    'testing',
+    'dependencies',
+    'ci',
+    'cli',
+    'llm',
+    'web-search',
+  ]) {
+    assert.ok(
+      validatePullRequest(reviewedPull(['kind/feature', 'area/web', label])).some((error) =>
+        error.startsWith('PR 含旧版标签：'),
+      ),
+      label,
+    )
+  }
+  assert.ok(
+    validatePullRequest(
+      reviewedPull(['kind/feature', 'area/web', 'source/internal-pr']),
+    ).includes('source/* 仅用于 Issue：source/internal-pr'),
   )
 })
 
diff --git a/AGENTS.md b/AGENTS.md
index 90b2ab4a67..9344e2e6e2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -118,7 +118,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
 - **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
-- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([workflow](.agents/skills/dsh-labeling/SKILL.md)).
+- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md)).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
 

From 07ac5e6d4cbf06e5078e73844e38e97684788a75 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:00:10 +0800
Subject: [PATCH 267/516] fix(labels): address taxonomy review findings

---
 .../2026-07-25-semantic-pr-label-taxonomy.md  | 56 ---------------
 ...026-07-25-semantic-pr-label-taxonomy.zh.md | 56 ---------------
 ...07-27-dependabot-version-updates.i18n.yaml |  4 +-
 .../2026-07-27-dependabot-version-updates.md  |  2 +-
 ...026-07-27-dependabot-version-updates.zh.md |  2 +-
 ...8-unified-github-label-taxonomy.i18n.yaml} |  6 +-
 ...026-08-08-unified-github-label-taxonomy.md | 72 +++++++++++++++++++
 ...-08-08-unified-github-label-taxonomy.zh.md | 72 +++++++++++++++++++
 .github/issue-management/policy.mjs           |  2 +
 .github/issue-management/policy.test.mjs      | 42 +++++------
 AGENTS.md                                     |  2 +-
 11 files changed, 172 insertions(+), 144 deletions(-)
 delete mode 100644 .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
 delete mode 100644 .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
 rename .agents/notes/implemented/process/{2026-07-25-semantic-pr-label-taxonomy.i18n.yaml => 2026-08-08-unified-github-label-taxonomy.i18n.yaml} (56%)
 create mode 100644 .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
 create mode 100644 .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md

diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
deleted file mode 100644
index 6aef5ecbb8..0000000000
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# Agent Note: Semantic pull request label taxonomy
-
-Status: implemented
-
-English | [中文](2026-07-25-semantic-pr-label-taxonomy.zh.md)
-
-## Problem
-
-Pull request labels answer two independent questions: what kind of change the work makes and which durable repository domains it materially affects. Mixing those dimensions or keeping synonymous labels makes queries ambiguous, while a closed area inventory forces new domains into inaccurate categories.
-
-Issues already have a native Type and a separate source taxonomy. Reusing pull request kind or source labels across both object types duplicates metadata and weakens the meaning of each label family.
-
-## Decision
-
-Every open or merged pull request carries exactly one canonical `kind/*` label and at least one materially affected `area/*` label. Closed pull requests that were never merged retain migrated historical assignments but do not receive invented missing classification. Operational labels may coexist without satisfying either dimension.
-
-### Kinds
-
-The kind set is closed and mutually exclusive:
-
-| Kind | Meaning |
-|---|---|
-| `kind/feature` | Adds or intentionally changes behavior. |
-| `kind/bug-fix` | Corrects incorrect behavior. |
-| `kind/doc` | Makes documentation the dominant intent. |
-| `kind/testing` | Changes tests or testing infrastructure without changing product behavior. |
-| `kind/cleanup` | Preserves behavior while maintaining or simplifying implementation or repository process. |
-| `kind/dependency` | Updates dependencies without another dominant intent. |
-
-The kind records the dominant intent. Accompanying tests, documentation, cleanup, or dependency movement do not override a feature or bug fix.
-
-### Areas
-
-Areas name durable semantic domains rather than temporary initiatives, ownership, or every path touched incidentally. A pull request carries multiple areas when it changes distinct contracts, but it does not combine an umbrella and a narrower label for the same contract. GitHub's live `area/*` names and descriptions own the current inventory.
-
-The area set is intentionally extensible. When no existing description honestly covers a durable and reusable repository domain, an agent is empowered to create a concise `area/<lowercase-kebab-case>` label without separate approval. The agent must not create an area for one pull request, an incidental path, a temporary project, a status, or a person or team, and must report the new label after applying it. Reusing an inaccurate area merely to avoid a justified addition is not acceptable.
-
-Kinds are not extended this way. A new kind changes the mutually exclusive classification contract and requires an explicit taxonomy change with corresponding policy enforcement.
-
-### Issues and operational labels
-
-Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record Issue provenance and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
-
-Label migrations preserve meaning before removing aliases: add the canonical replacement, verify the labelable, then remove the obsolete assignment. A label is deleted only after no pull request or Issue still uses it, and unrelated labels are never replaced as a set.
-
-## Alternatives considered
-
-- **Unprefixed labels.** Rejected because a flat name does not identify whether it classifies intent, domain, source, priority, or automation, and synonymous plain and prefixed labels caused ambiguous queries.
-- **A fixed area allowlist in repository policy.** Rejected because durable repository domains evolve. The `area/*` namespace remains mechanically recognizable while live descriptions carry the extensible inventory.
-- **Kinds on Issues.** Rejected because native Issue Type already owns that classification; duplicating it as a label creates drift.
-- **Automatic areas from paths.** Rejected because areas describe semantic impact across package boundaries, while changed paths include incidental tests, documentation, and support files.
-- **Exactly one area per pull request.** Rejected because coherent changes can materially affect several independent contracts.
-
-## Consequences
-
-Reviewers and automation can query intent, semantic scope, provenance, priority, and operational triggers independently. Maintainers must read the change and live label descriptions rather than infer classification from title prefixes or paths, and taxonomy migrations carry an explicit historical backfill and verification cost.
diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md b/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
deleted file mode 100644
index 0bd3fbcaec..0000000000
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.zh.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# Agent Note: 语义化 PR 标签分类体系
-
-Status: implemented
-
-[English](2026-07-25-semantic-pr-label-taxonomy.md) | 中文
-
-## 问题
-
-PR（Pull Request）标签回答两个相互独立的问题：工作带来哪一类变更，以及会对哪些持久的仓库领域产生实质影响。混用这两个维度或保留同义标签会使查询含义模糊，而封闭的领域清单会迫使新领域被归入不准确的类别。
-
-Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对象上复用 PR 类型或来源标签会产生重复元数据，并削弱每个标签族的含义。
-
-## 决策
-
-每项开放或已合并的 PR 都带有恰好一个规范的 `kind/*` 标签，以及至少一个受到实质影响的 `area/*` 标签。未合并即关闭的 PR 保留经迁移的历史标签关系，但不会凭空补充缺失分类。管理用途的标签可以并存，但不能满足这两个维度中的任一个。
-
-### 类型
-
-类型集合封闭且互斥：
-
-| 类型 | 含义 |
-|---|---|
-| `kind/feature` | 新增行为或有意改变行为。 |
-| `kind/bug-fix` | 修正错误行为。 |
-| `kind/doc` | 以文档变更为主要意图。 |
-| `kind/testing` | 修改测试或测试基础设施，但不改变产品行为。 |
-| `kind/cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
-| `kind/dependency` | 在没有其他主要意图时更新依赖。 |
-
-类型记录主要意图。配套测试、文档、清理或依赖调整不会覆盖一项功能或缺陷修复的主要意图。
-
-### 领域
-
-领域表示持久的语义领域，而不是临时项目、归属关系或偶然触及的每条路径。一项 PR 修改不同契约时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项契约。当前分类清单以 GitHub 上实时的 `area/*` 名称和描述为准。
-
-领域集合有意保持可扩展。当现有描述都无法准确涵盖一个持久且可复用的仓库领域时，agent（智能体）有权无须另行批准，直接创建简洁的 `area/<lowercase-kebab-case>` 标签。agent 不得为单个 PR、偶然涉及的路径、临时项目、状态、个人或团队创建领域，并且必须在应用新标签后报告。仅为避免新增一个确有必要的标签而复用不准确的领域，不可接受。
-
-类型不以这种方式扩展。新增类型会改变互斥的分类契约，必须明确修改分类体系并同步调整策略强制校验。
-
-### Issue 与管理用途标签
-
-Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍为可选。`source/*` 标签记录 Issue 来源，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
-
-迁移标签时，须先保留语义，再移除别名：先添加规范替代标签并验证对象，再移除废弃的标签关系。只有在所有 PR 和 Issue 都不再使用某个标签后才能将其删除，且绝不整组替换无关标签。
-
-## 曾考虑的替代方案
-
-- **无前缀标签。** 不予采纳，因为扁平名称无法表明其表示的是意图、领域、来源、优先级还是自动化用途，而同义的无前缀和带前缀标签会使查询含义模糊。
-- **在仓库策略中使用固定的领域允许列表。** 不予采纳，因为持久的仓库领域会持续演变。`area/*` 命名空间仍可由机制识别，而实时描述负责承载可扩展的分类清单。
-- **在 Issue 上使用类型标签。** 不予采纳，因为原生 Issue Type 已负责这项分类；再用标签重复表示会产生漂移。
-- **从路径自动生成领域。** 不予采纳，因为领域描述跨越包边界的语义影响，而变更路径还会包含偶然涉及的测试、文档和支持文件。
-- **每项 PR 恰好一个领域。** 不予采纳，因为一项内聚的变更可以对多个独立契约产生实质影响。
-
-## 后果
-
-评审人和自动化流程可以分别查询意图、语义范围、来源、优先级和工作流触发器。维护者必须阅读变更内容和实时标签描述，而不能根据标题前缀或路径推断分类；迁移分类体系还会产生明确的历史回填与验证成本。
diff --git a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.i18n.yaml
index 316c31771e..dea250de53 100644
--- a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.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 .agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
-2026-07-27-dependabot-version-updates.md: 5d42563788d9f1e72da65c8e9750d6b1ecba06a5
-2026-07-27-dependabot-version-updates.zh.md: 4847059944e7e35de5719a6cbfd3d5b133467ccb
+2026-07-27-dependabot-version-updates.md: bba83c9e720cf87f91638131d7f9580422ea7f76
+2026-07-27-dependabot-version-updates.zh.md: 74b399778fdd06cbbe38234f7bddc5c28c4fd600
diff --git a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
index 5d42563788..bba83c9e72 100644
--- a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
+++ b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
@@ -12,7 +12,7 @@ Maintained registry and GitHub Actions dependencies need a regular update path.
 
 The default branch carries [`.github/dependabot.yml`](../../../../.github/dependabot.yml) with weekly version-update checks for the root pnpm workspace, including `native/landlock-run`, the `python/sdk` uv project, and GitHub Actions. Every entry sets `cooldown.default-days` to `30`, so a version release becomes eligible only after it is at least 30 days old and is proposed on the next weekly check. The [in-repository Landlock release decision](2026-08-06-in-repository-landlock-release.md) owns the shared-workspace boundary.
 
-The root pnpm version-update scan excludes `vendor/**`, whose source and manifests move only through the [vendoring procedure](../../../../vendor/README.md). GitHub applies `exclude-paths` only to version updates; a security pull request that touches a vendored manifest is replaced through the vendoring procedure instead of being merged as generated. Dependabot pull requests receive the repository's `cleanup` kind and `area/infra` area labels, run the normal pull-request checks, and remain subject to maintainer review; this automation does not merge them.
+The root pnpm version-update scan excludes `vendor/**`, whose source and manifests move only through the [vendoring procedure](../../../../vendor/README.md). GitHub applies `exclude-paths` only to version updates; a security pull request that touches a vendored manifest is replaced through the vendoring procedure instead of being merged as generated. Dependabot pull requests receive the repository's `kind/dependency` kind and `area/infra` area labels, run the normal pull-request checks, and remain subject to maintainer review; this automation does not merge them.
 
 Repository settings enable dependency vulnerability alerts and Dependabot security updates. GitHub does not apply version-update cooldowns to those security updates, so security fixes remain eligible immediately. A generated pnpm security pull request can still fail the repository's lockfile release-age verification when dependency resolution selects unrelated fresh transitive versions; that pull request waits or is narrowed instead of weakening the policy. The repository's coordinated fresh-release exceptions are not copied into Dependabot's cooldown exclusions: automated version updates use the uniform 30-day wait, while an explicitly reviewed manual update can still follow its owning release procedure.
 
diff --git a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md
index 4847059944..74b399778f 100644
--- a/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-27-dependabot-version-updates.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 默认分支包含 [`.github/dependabot.yml`](../../../../.github/dependabot.yml)，其中为包含 `native/landlock-run` 的根 pnpm 工作区、`python/sdk` uv 项目和 GitHub Actions 配置了每周一次的版本更新检查。每个更新项都将 `cooldown.default-days` 设为 `30`，因此某个版本只有在发布至少 30 天后才符合更新条件，并会在下一次每周检查时生成更新提案。[仓库内 Landlock 发布决策](2026-08-06-in-repository-landlock-release.md)负责共享工作区边界。
 
-根 pnpm 工作区的版本更新扫描排除 `vendor/**`，其中的源码和 manifest（元数据清单）只能通过 [vendoring 流程](../../../../vendor/README.md)变更。GitHub 仅将 `exclude-paths` 用于版本更新；如果安全更新 PR（Pull Request）涉及随源码纳入仓库的 manifest，则改由 vendoring 流程处理，以替代自动生成的 PR，而不会将其原样合并。Dependabot PR 会获得仓库的 `cleanup` 类型标签和 `area/infra` 区域标签，运行常规 PR 检查，并且仍须由维护者评审；该自动化不会合并这些 PR。
+根 pnpm 工作区的版本更新扫描排除 `vendor/**`，其中的源码和 manifest（元数据清单）只能通过 [vendoring 流程](../../../../vendor/README.md)变更。GitHub 仅将 `exclude-paths` 用于版本更新；如果安全更新 PR（Pull Request）涉及随源码纳入仓库的 manifest，则改由 vendoring 流程处理，以替代自动生成的 PR，而不会将其原样合并。Dependabot PR 会获得仓库的 `kind/dependency` 类型标签和 `area/infra` 区域标签，运行常规 PR 检查，并且仍须由维护者评审；该自动化不会合并这些 PR。
 
 仓库设置已启用依赖项漏洞警报和 Dependabot 安全更新。GitHub 不会对这些安全更新应用版本更新冷却期，因此安全修复仍可立即进入更新流程。如果依赖解析还选中了其他刚发布的传递依赖，pnpm 安全更新 PR 仍可能无法通过仓库的锁文件发布时长校验；此类 PR 应等待隔离期结束或缩小更新范围，不得因此放宽政策。仓库为协调刚发布版本而设置的例外，不会纳入 Dependabot 的冷却期排除项：自动版本更新统一等待 30 天；经过明确评审的手动更新仍可遵循相应的发布流程。
 
diff --git a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
similarity index 56%
rename from .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml
rename to .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
index a83236521c..5ee57b914f 100644
--- a/.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.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 .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
-2026-07-25-semantic-pr-label-taxonomy.md: 6aef5ecbb80005d1fcd90b4ee673bbbebb92cba6
-2026-07-25-semantic-pr-label-taxonomy.zh.md: 0bd3fbcaeca37fa894e92ce5a4e78c4125056ac9
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
+2026-08-08-unified-github-label-taxonomy.md: fddda6c99053e55d3e31a2f6e5c55add09772117
+2026-08-08-unified-github-label-taxonomy.zh.md: c8d727c9a56d6c7c25f73eacde42e0bef1c779b7
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
new file mode 100644
index 0000000000..fddda6c990
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
@@ -0,0 +1,72 @@
+# Agent Note: Unified GitHub label taxonomy
+
+Status: implemented
+
+English | [中文](2026-08-08-unified-github-label-taxonomy.zh.md)
+
+## Problem
+
+Pull request labels answer two independent questions: what kind of change the work makes and which durable repository domains it materially affects. Mixing those dimensions or retaining synonymous plain and namespaced labels makes queries ambiguous, while a closed area inventory forces new domains into inaccurate categories.
+
+Issues already have a native Type and a separate source taxonomy. Reusing pull request kind or source labels across both object types duplicates metadata and weakens the meaning of each family.
+
+## Decision
+
+Every open or merged pull request carries exactly one canonical `kind/*` label and at least one materially affected `area/*` label. Closed pull requests that were never merged retain migrated historical assignments but do not receive invented missing classification. Operational labels may coexist without satisfying either dimension.
+
+### Kinds
+
+The kind set is closed and mutually exclusive:
+
+| Kind | Meaning |
+|---|---|
+| `kind/feature` | Adds or intentionally changes behavior. |
+| `kind/bug-fix` | Corrects incorrect behavior. |
+| `kind/doc` | Makes documentation the dominant intent. |
+| `kind/testing` | Changes tests or testing infrastructure without changing product behavior. |
+| `kind/cleanup` | Preserves behavior while maintaining or simplifying implementation or repository process. |
+| `kind/dependency` | Updates dependencies without another dominant intent. |
+
+The kind records the dominant intent. Accompanying tests, documentation, cleanup, or dependency movement do not override a feature or bug fix. A new kind changes this classification contract and requires an explicit taxonomy and policy change.
+
+Repository policy rejects unsupported `kind/*` values and reserves every alias removed by the unification: `kind/bug`, `kind/documentation`, `feature`, `bug-fix`, `doc`, `cleanup`, `testing`, `dependencies`, `ci`, `cli`, `llm`, and `web-search`. Reserving the exact migrated set prevents an obsolete synonym from being recreated as an apparently unrelated operational label.
+
+### Areas
+
+Areas name durable semantic domains rather than temporary initiatives, ownership, or every path touched incidentally. A pull request carries multiple areas when it changes distinct contracts, but it does not combine an umbrella and a narrower label for the same contract. GitHub's live `area/*` names and descriptions own the current inventory; this record owns the selection rule and the non-obvious boundaries that cannot fit reliably in short label descriptions.
+
+- `area/web` covers browser and Electron graphical interfaces, `area/vscode` covers the editor extension, and `area/api` covers cross-interface protocols and language SDKs.
+- `area/planning` covers goals, plans, todos, and scheduling, while `area/workflow` covers executable workflows and background task runtimes.
+- `area/artifact` deliberately combines artifacts, attachments, and multimodal delivery. Split labels become justified only when those concerns again need independent review or queries.
+- `area/tools` applies to generic registry, schema, and execution contracts. A concrete capability uses its own area unless it also changes that generic contract.
+- `area/hooks` means the Claude Code and Codex bridges, `area/infra` covers build, release, CI, repository gates, generators, dependencies, and developer tooling, and `area/windows` covers native Windows product support rather than CI runner selection.
+
+The area set is intentionally extensible. When no existing description honestly covers a durable and reusable domain, an agent may create a concise `area/<lowercase-kebab-case>` label without separate approval. It must not create an area for one pull request, an incidental path, a temporary project, a status, or a person or team, and it reports the new label and rationale to the requester after applying it. Reusing an inaccurate area merely to avoid a justified addition is not acceptable.
+
+### Issues and migrations
+
+Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record Issue provenance and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
+
+Label migrations preserve meaning before removing aliases: add the canonical replacement, verify the labelable, then remove the obsolete assignment. A label is deleted only after no pull request or Issue still uses it, and unrelated labels are never replaced as a set.
+
+## Alternatives considered
+
+**Unprefixed labels.** Plain names reduce visual noise, but they do not identify whether a label classifies intent, domain, source, priority, or automation. Retaining both plain and namespaced synonyms also makes queries and policy enforcement ambiguous.
+
+**One undifferentiated label set.** A label's presence would not prove that both intent and semantic scope were considered.
+
+**A fixed area allowlist in repository policy.** Durable repository domains evolve. The `area/*` namespace remains mechanically recognizable while live descriptions carry the extensible inventory.
+
+**Package- or path-derived areas.** Areas describe semantic impact across package boundaries, while changed paths include incidental tests, documentation, and support files.
+
+**Separate labels for every delivery shell or media lifecycle.** Browser and Electron delivery share one graphical domain, and artifact, attachment, and multimodal delivery currently share one review/query domain. A split belongs in a later taxonomy change only when it restores useful independent classification.
+
+**Broad implementation labels in place of semantic domains.** A concrete capability is not merely its tool, interface, filesystem, or process implementation. Generic implementation areas apply only when their own contracts change.
+
+**Kinds on Issues.** Native Issue Type already owns that classification; duplicating it as a label creates drift.
+
+**Exactly one area per pull request.** Coherent changes can materially affect several independent contracts, and dropping secondary areas hides affected scope.
+
+## Consequences
+
+Reviewers and automation can query intent, semantic scope, provenance, priority, and operational triggers independently. Maintainers must read the change and the live label descriptions instead of inferring classification from title prefixes or paths. The live catalog, this rationale, and policy enforcement must move together when a kind or a non-obvious area boundary changes, and taxonomy migrations carry an explicit historical backfill and verification cost.
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
new file mode 100644
index 0000000000..c8d727c9a5
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
@@ -0,0 +1,72 @@
+# Agent Note: 统一 GitHub 标签分类体系
+
+Status: implemented
+
+[English](2026-08-08-unified-github-label-taxonomy.md) | 中文
+
+## 问题
+
+PR（Pull Request）标签回答两个相互独立的问题：工作带来哪一类变更，以及会对哪些持久的仓库领域产生实质影响。混用这两个维度，或同时保留同义的无前缀标签与带命名空间的标签，都会使查询含义模糊；封闭的领域清单则会迫使新领域归入不准确的类别。
+
+Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对象上复用 PR 类型或来源标签会产生重复元数据，并削弱每个标签族的含义。
+
+## 决策
+
+每项开放或已合并的 PR 都带有恰好一个规范的 `kind/*` 标签，以及至少一个表示实质受影响领域的 `area/*` 标签。未合并即关闭的 PR 保留经迁移的历史标签关系，但不会凭空补充缺失分类。管理用途的标签可以并存，但不能满足这两个维度中的任一个。
+
+### 变更类型
+
+类型集合封闭且互斥：
+
+| 变更类型 | 含义 |
+|---|---|
+| `kind/feature` | 新增行为或有意改变行为。 |
+| `kind/bug-fix` | 修正错误行为。 |
+| `kind/doc` | 以文档变更为主导意图。 |
+| `kind/testing` | 在不改变产品行为的前提下修改测试或测试基础设施。 |
+| `kind/cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
+| `kind/dependency` | 在没有其他主导意图时更新依赖。 |
+
+类型记录主导意图。配套测试、文档、清理或依赖调整不会盖过功能变更或缺陷修复这一主导意图。新增类型会改变这项分类契约，因此必须明确修改分类体系和政策。
+
+仓库政策会拒绝不支持的 `kind/*` 值，并将统一过程中移除的所有别名列为保留名称：`kind/bug`、`kind/documentation`、`feature`、`bug-fix`、`doc`、`cleanup`、`testing`、`dependencies`、`ci`、`cli`、`llm` 和 `web-search`。精确保留这组已迁移的名称，可以防止过时的同义名称被重新创建成看似无关的管理用途标签。
+
+### 领域
+
+领域表示持久的语义领域，而不是临时专项、归属关系或偶然触及的每条路径。一项 PR 修改不同契约时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项契约。GitHub 上现行的 `area/*` 名称和说明定义当前清单；本记录定义选择规则，以及简短标签说明无法可靠容纳的非显然边界。
+
+- `area/web` 覆盖浏览器与 Electron 图形界面，`area/vscode` 覆盖编辑器扩展，`area/api` 覆盖跨界面协议与各语言 SDK。
+- `area/planning` 覆盖目标、计划、待办和调度，`area/workflow` 则覆盖可执行工作流与后台任务运行时。
+- `area/artifact` 有意合并产物、附件与多模态交付。只有当这些关注点再次需要独立评审或查询时，才有理由拆分标签。
+- `area/tools` 适用于通用注册表、schema 与执行契约。具体能力使用自身的领域标签，除非它还修改了这项通用契约。
+- `area/hooks` 表示 Claude Code 与 Codex 桥接，`area/infra` 覆盖构建、发布、CI、仓库门禁、生成器、依赖与开发者工具，`area/windows` 覆盖原生 Windows 产品支持，而不是 CI runner 的选型。
+
+领域集合有意保持可扩展。当现有说明都无法如实涵盖一个持久且可复用的领域时，agent（智能体）无需另行批准，即可创建一个简洁的 `area/<lowercase-kebab-case>` 标签。agent 不得为单个 PR、偶然涉及的路径、临时项目、状态、个人或团队创建领域，并且必须在应用新标签后向请求者报告该标签及理由。仅为避免新增一个确有必要的领域标签而复用不准确的领域，不可接受。
+
+### Issue 与迁移
+
+Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然可选。`source/*` 标签记录 Issue 来源，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
+
+迁移标签时，须先保留语义，再移除别名：先添加规范替代标签，核验可加标签对象，再移除废弃的标签关系。只有在所有 PR 和 Issue 都不再使用某个标签后才能将其删除，且绝不整组替换无关标签。
+
+## 考虑过的替代方案
+
+**无前缀标签。** 无前缀名称可以减少视觉噪声，但无法表明标签分类的是意图、领域、来源、优先级还是自动化用途。同时保留无前缀和带命名空间的同义标签，也会使查询和政策执行含义模糊。
+
+**不区分维度的单一标签集合。** 某个标签存在，并不能证明意图和语义范围都经过了考虑。
+
+**仓库政策中的固定领域允许清单。** 持久的仓库领域会演进。`area/*` 命名空间仍可机械识别，而现行说明承载可扩展清单。
+
+**按包或路径派生的领域。** 领域描述跨越包边界的语义影响，而变更路径会包含偶然涉及的测试、文档和支持文件。
+
+**为每种交付载体或媒体生命周期单设标签。** 浏览器与 Electron 交付共用一个图形界面领域，产物、附件与多模态交付目前也共用一个评审／查询领域。只有当拆分能恢复有用的独立分类时，才应在后续分类体系变更中进行。
+
+**用宽泛的实现标签取代语义领域。** 一项具体能力并不只是其工具、接口、文件系统或进程实现。通用实现领域只在其自身契约变化时适用。
+
+**在 Issue 上使用类型标签。** 原生 Issue Type 已负责这项分类；再用标签复制会造成漂移。
+
+**每个 PR 恰好一个领域。** 内聚的变更可能对多个独立契约产生实质影响，丢弃次要领域会隐藏受影响范围。
+
+## 后果
+
+评审人和自动化流程可以分别查询意图、语义范围、来源、优先级和工作流触发条件。维护者必须阅读变更内容和现行标签说明，而不能根据标题前缀或路径推断分类。当某种类型或某条非显然的领域边界发生变化时，现行标签清单、本记录中的决策依据和政策执行必须同步更新；分类体系迁移还会产生明确的历史回填和验证成本。
diff --git a/.github/issue-management/policy.mjs b/.github/issue-management/policy.mjs
index 18a9b03628..09e1bbe7fd 100644
--- a/.github/issue-management/policy.mjs
+++ b/.github/issue-management/policy.mjs
@@ -20,9 +20,11 @@ const PR_KINDS = new Set([
   'kind/cleanup',
   'kind/dependency',
 ])
+// Aliases removed by the unified taxonomy migration remain reserved so they cannot be recreated.
 const LEGACY_LABELS = new Set([
   'kind/bug',
   'kind/documentation',
+  'feature',
   'bug-fix',
   'doc',
   'cleanup',
diff --git a/.github/issue-management/policy.test.mjs b/.github/issue-management/policy.test.mjs
index bcaf450afa..8a9b0f91e6 100644
--- a/.github/issue-management/policy.test.mjs
+++ b/.github/issue-management/policy.test.mjs
@@ -36,6 +36,22 @@ const canonicalKinds = [
   'kind/dependency',
 ]
 
+// Keep an independent oracle rather than importing the implementation's reserved set.
+const legacyLabels = [
+  'kind/bug',
+  'kind/documentation',
+  'feature',
+  'bug-fix',
+  'doc',
+  'cleanup',
+  'testing',
+  'dependencies',
+  'ci',
+  'cli',
+  'llm',
+  'web-search',
+]
+
 const reviewedPull = (labels) => ({
   isDraft: false,
   authorType: 'User',
@@ -115,17 +131,7 @@ test('reserves PR kind and legacy labels for pull requests', () => {
   for (const label of [
     ...canonicalKinds,
     'kind/experimental',
-    'kind/bug',
-    'kind/documentation',
-    'bug-fix',
-    'doc',
-    'cleanup',
-    'testing',
-    'dependencies',
-    'ci',
-    'cli',
-    'llm',
-    'web-search',
+    ...legacyLabels,
   ]) {
     assert.ok(
       validateIssue({ ...legalIssue, labels: [label] }).some((error) =>
@@ -326,19 +332,7 @@ test('rejects multiple, unknown, legacy, and Issue-source PR labels', () => {
       'PR 含不支持的 kind/*：kind/experimental',
     ),
   )
-  for (const label of [
-    'kind/bug',
-    'kind/documentation',
-    'bug-fix',
-    'doc',
-    'cleanup',
-    'testing',
-    'dependencies',
-    'ci',
-    'cli',
-    'llm',
-    'web-search',
-  ]) {
+  for (const label of legacyLabels) {
     assert.ok(
       validatePullRequest(reviewedPull(['kind/feature', 'area/web', label])).some((error) =>
         error.startsWith('PR 含旧版标签：'),
diff --git a/AGENTS.md b/AGENTS.md
index 9344e2e6e2..928a118868 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -118,7 +118,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
 - **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
-- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md)).
+- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md)).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
 

From 702e2d024a0f6957c785b6f597a28ee53da458aa Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:29:43 +0800
Subject: [PATCH 268/516] fix(windows): canonicalize native watch paths

---
 ...8-native-windows-pull-request-ci.i18n.yaml |  4 +-
 ...26-08-08-native-windows-pull-request-ci.md |  4 ++
 ...08-08-native-windows-pull-request-ci.zh.md |  4 ++
 .../credentials-local/README.i18n.yaml        |  4 +-
 .../credentials/credentials-local/README.md   |  2 +-
 .../credentials-local/README.zh.md            |  2 +-
 .../credentials-local/src/index.ts            |  4 +-
 .../settings/settings-local/README.i18n.yaml  |  4 +-
 packages/settings/settings-local/README.md    |  1 +
 packages/settings/settings-local/README.zh.md |  1 +
 packages/settings/settings-local/src/index.ts |  4 +-
 packages/ui/app-boot/tests/hmr-config.spec.ts | 46 +++++++++++++++++--
 packages/util/paths/README.i18n.yaml          |  4 +-
 packages/util/paths/README.md                 |  6 ++-
 packages/util/paths/README.zh.md              |  6 ++-
 packages/util/paths/src/index.ts              | 30 +++++++++++-
 packages/util/paths/tests/paths.spec.ts       | 22 ++++++++-
 scripts/project-doc-site.spec.ts              |  6 +--
 vendor/README.md                              |  2 +-
 vendor/hmr/README.md                          |  6 +++
 vendor/hmr/src/index.ts                       | 31 ++++++++-----
 21 files changed, 157 insertions(+), 36 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index 3b3d2dc1dd..c9d06abacf 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: 926eec04cff63aaf25d1e85b3dcbc41464f25660
-2026-08-08-native-windows-pull-request-ci.zh.md: 8728f0eb08adcb1501f036bb19ff523ded406ccc
+2026-08-08-native-windows-pull-request-ci.md: 8b6766cfa8df48c6c61410c06a410340a0c9bb21
+2026-08-08-native-windows-pull-request-ci.zh.md: 29cb1f725f4212c13974d642388edaf1df16b759
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 926eec04cf..8b6766cfa8 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -14,6 +14,8 @@ The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) run
 
 The aggregate keeps workspace build and production-site failures blocking while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
 
+The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path.
+
 Wine-only infrastructure is absent from the supported workflow: there is no apt-cache producer, compatibility script, hoisted snapshot install, Windows Node download, or local `check:windows-wine` command. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) remains historical evidence for its measured latency and fidelity trade-offs, not a current execution path.
 
 ## Alternatives considered
@@ -30,4 +32,6 @@ Wine-only infrastructure is absent from the supported workflow: there is no apt-
 
 Pull requests receive a real NT kernel, NTFS, PowerShell, Windows process, and native addon signal before the aggregate can pass. The job is slower than the Wine compatibility lane and can queue on Windows capacity, but its green result now describes the supported host rather than an approximation.
 
+The native lane is also a portability inventory: its exact-head acceptance requires every blocking gate to pass and the final summary to contain no non-blocking failure. That distinction caught path contracts which a successful wrapper conclusion alone would have concealed.
+
 Removing the Wine cache producer and local script deletes a separate install topology and its recurring compatibility failures. Native coverage and snapshots remain a named gap rather than being implied by the job name; they require their own tested contract before becoming part of this required lane.
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 8728f0eb08..29cb1f725f 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -14,6 +14,8 @@ Status: implemented
 
 聚合作业继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
 
+首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。
+
 受支持的工作流不含 Wine 专属基础设施：不存在 apt 缓存生产者、兼容性脚本、对仓库快照执行的 hoisted 安装、Windows Node 下载或本地 `check:windows-wine` 命令。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)仍作为其实测延迟与保真度取舍的历史证据，而非当前执行路径。
 
 ## 曾考虑的替代方案
@@ -30,4 +32,6 @@ Status: implemented
 
 在聚合作业通过之前，拉取请求会获得来自真实 NT 内核、NTFS、PowerShell、Windows 进程和原生插件的信号。该作业比 Wine 兼容性通道更慢，也可能因 Windows 容量而排队，但其绿灯结果描述的是受支持的宿主，而非近似环境。
 
+原生通道也是一份可移植性清单：其分支头精确验收要求每个阻断门禁都通过，且最终汇总中不包含任何非阻断失败。这一区分发现了路径契约问题；若只看包装层的成功结论，这些问题本会被掩盖。
+
 移除 Wine 缓存生产者和本地脚本后，独立的安装拓扑及其反复出现的兼容性故障也随之消失。原生 Windows 覆盖率与快照仍是明确列出的缺口，不会仅由作业名称暗示已经纳入；二者都必须先建立各自经过测试的契约，才能成为该必需通道的一部分。
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index 07a3efd5c3..66ad77f648 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-local/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/credentials/credentials-local/README.md
-README.md: 8e95a890a8e38172cf8984653a01c59570f0061a
-README.zh.md: 04ad07ae4e703ab0416d1d8f1bb6a6ff90adf337
+README.md: 035d558d8cbd51ce46af72d7bd9cd56bed85ebcd
+README.zh.md: 11c772951dab3ce0cea3a13e739198d41028d598
diff --git a/packages/credentials/credentials-local/README.md b/packages/credentials/credentials-local/README.md
index 8e95a890a8..035d558d8c 100644
--- a/packages/credentials/credentials-local/README.md
+++ b/packages/credentials/credentials-local/README.md
@@ -47,7 +47,7 @@ The provider creates the directory `0700` and creates or atomically replaces the
 
 ## Hot reload
 
-External edits publish `credentials/updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable or invalid document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable or invalid file at boot fails loud.
+External edits publish `credentials/updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. Before Chokidar opens the target, the provider realpaths its deepest existing ancestor and restores any missing suffix; file access and diagnostics retain the configured path, while Windows cannot mix an 8.3 alias with long-form libuv events. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable or invalid document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable or invalid file at boot fails loud.
 
 ## Security boundary
 
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index 04ad07ae4e..11c772951d 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -47,7 +47,7 @@ OPENAI_API_KEY: sk-…
 
 ## 热重载
 
-外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。提供方自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则明确报错。
+外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。在 Chokidar 打开目标之前，提供方会对层级最深的现有祖先路径执行 realpath 解析，再拼回缺失的后缀；文件访问和诊断仍使用配置路径，从而避免 Windows 混用 8.3 别名与 libuv 的长格式事件路径。提供方自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则明确报错。
 
 ## 安全边界
 
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index e781c10f3e..67b598d7e0 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -41,7 +41,7 @@ import { mkdir, readFile, stat } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { Document, parseDocument, type YAMLError } from 'yaml'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { canonicalizeWatchPath, resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { environmentOf } from '@deepseek-ai/dsh-environment'
 import { Credentials, credentialRef } from '@deepseek-ai/dsh-credentials'
 import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/dsh-credentials'
@@ -270,7 +270,7 @@ export class CredentialsLocal extends Credentials {
     /* jscpd:ignore-start -- same watcher discipline as settings-local by design:
        the serialized-refresh and quiesce-on-dispose shape is the reviewed
        lifecycle contract, not accidental repetition. */
-    const watcher = chokidarWatch(this.spec.filename, {
+    const watcher = chokidarWatch(await canonicalizeWatchPath(this.spec.filename), {
       ignoreInitial: true,
       awaitWriteFinish: {
         stabilityThreshold: this.spec.debounceMs,
diff --git a/packages/settings/settings-local/README.i18n.yaml b/packages/settings/settings-local/README.i18n.yaml
index ec26e4241f..188e4361bb 100644
--- a/packages/settings/settings-local/README.i18n.yaml
+++ b/packages/settings/settings-local/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/settings/settings-local/README.md
-README.md: d1f3d755f9073acdf6fcfc5d1de883d74cc023c4
-README.zh.md: 03c7ef7c35312d9e1e4a86b0df71412875af7d6c
+README.md: a0bc94630f78aa7c101e3eb0795a7d07e585e347
+README.zh.md: 2d2d0828f2eadde9867ab91fe8fbd4c61dea4c11
diff --git a/packages/settings/settings-local/README.md b/packages/settings/settings-local/README.md
index d1f3d755f9..a0bc94630f 100644
--- a/packages/settings/settings-local/README.md
+++ b/packages/settings/settings-local/README.md
@@ -24,6 +24,7 @@ Defaulting is one explicit `resolveSpec(config)` step; an unsupported extension
 - **YAML edits are leaf-level diffs.** A write sets only the values that changed and deletes only the keys that were removed, so comments, anchors, and formatting survive on every untouched node and on the key of every changed pair; a changed array (or other non-map value) replaces wholesale, taking comments inside it along. JSON re-serializes without comments.
 - **Reloads and writes share one operation chain.** Watcher refreshes and persists from every namespace queue run one at a time in queue order; each render sees the text the previous operation committed.
 - **The watcher's ready signal reconciles once.** The initial load races the watcher's own setup, so a change written in between never fires an event; the reconcile at ready closes that startup gap.
+- **The native watcher receives a canonical path.** Before Chokidar opens the target, the provider realpaths its deepest existing ancestor and restores any missing suffix. File access and user-facing diagnostics retain the configured path, while Windows cannot mix an 8.3 alias with long-form event paths inside libuv.
 - **Dispose quiesces in every watch mode.** Teardown marks the provider closed, closes the watcher when present, then waits out every queued or in-flight document operation, so nothing publishes after disposal.
 - **Self-write suppression by content.** The provider caches the last good text; a watcher event whose content equals the cache (its own write included) is a no-op.
 - **Host configuration adapters receive the resolved path.** `ctx.settings.documentPath` is the absolute `resolveSpec()` filename, including a custom YAML/JSON path; `prepareDocument()` preserves an existing file or exclusively creates an absent empty file with owner-only permissions before the Host opens it. The browser receives only an availability flag, never reconstructs `$DSH_HOME`, and never submits a filesystem target.
diff --git a/packages/settings/settings-local/README.zh.md b/packages/settings/settings-local/README.zh.md
index 03c7ef7c35..2d2d0828f2 100644
--- a/packages/settings/settings-local/README.zh.md
+++ b/packages/settings/settings-local/README.zh.md
@@ -24,6 +24,7 @@
 - **YAML 编辑是叶子级 diff。** 写入只设置发生变化的值、只删除被移除的键，因此注释、锚点与排版在每个未触碰的节点上以及每个被改键值对的键上都得以保留；被改的数组（或其他非 map 值）整体替换，其中的注释随之一同被换掉。JSON 重新序列化，无注释。
 - **重载与写入共享一条操作链。** watcher 刷新与来自各 namespace 队列的 persist 按队列顺序逐个执行；每次渲染都基于上一次操作提交后的文本。
 - **watcher 的 ready 信号做一次对账。** 初始加载与 watcher 自身的建立存在竞态，因此其间写入的变更绝不会触发事件；ready 时的对账补上这个启动缺口。
+- **原生 watcher 接收规范化路径。** 在 Chokidar 打开目标之前，提供方会对层级最深的现有祖先路径执行 realpath 解析，再拼回缺失的后缀。文件访问和面向用户的诊断仍使用配置路径，从而避免 Windows 在 libuv 内部混用 8.3 别名与长格式事件路径。
 - **Dispose 在每种 watch 模式下都保证静止。** 卸载先把提供方标记为已关闭，在 watcher 存在时将其关闭，再等待所有已排队或进行中的文档操作完成，之后不再有任何发布。
 - **按内容抑制自写。** provider 缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。
 - **Host 配置适配器会收到解析后的路径。** `ctx.settings.documentPath` 是 `resolveSpec()` 得出的绝对文件名，包括自定义 YAML/JSON 路径；`prepareDocument()` 会保留现有文件，或在 Host 打开文档前，以仅属主可访问的权限独占创建缺失的空文件。浏览器只收到可用性标志，绝不重建 `$DSH_HOME`，也绝不提交文件系统目标。
diff --git a/packages/settings/settings-local/src/index.ts b/packages/settings/settings-local/src/index.ts
index 0ce07af40c..16bc641f05 100644
--- a/packages/settings/settings-local/src/index.ts
+++ b/packages/settings/settings-local/src/index.ts
@@ -14,7 +14,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, extname, join, resolve } from 'node:path'
 import { Document, parseDocument } from 'yaml'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { canonicalizeWatchPath, resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { Settings, deepEqualJson, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
 
 /** Plugin config: file location and hot-reload behavior. */
@@ -235,7 +235,7 @@ export class SettingsLocal extends Settings {
     // silently ignored or overwritten.
     yield* super[Service.init]()
     const watcher = this.spec.watch
-      ? chokidarWatch(this.spec.filename, {
+      ? chokidarWatch(await canonicalizeWatchPath(this.spec.filename), {
         ignoreInitial: true,
         awaitWriteFinish: {
           stabilityThreshold: this.spec.debounceMs,
diff --git a/packages/ui/app-boot/tests/hmr-config.spec.ts b/packages/ui/app-boot/tests/hmr-config.spec.ts
index 1892a6e73a..fe6bb556b4 100644
--- a/packages/ui/app-boot/tests/hmr-config.spec.ts
+++ b/packages/ui/app-boot/tests/hmr-config.spec.ts
@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -8,12 +8,12 @@ import Loader from '@cordisjs/plugin-loader'
 import Timer from '@cordisjs/plugin-timer'
 import { describe, expect, it } from 'vitest'
 
-async function bootHmr(dir: string): Promise<Context> {
+async function bootHmr(dir: string, root: string[] = []): Promise<Context> {
   const ctx = new Context()
   ctx.baseUrl = pathToFileURL(dir).href + '/'
   await ctx.plugin(Loader)
   await ctx.plugin(Timer)
-  await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+  await ctx.plugin(Hmr, { root, ignored: [], debounce: 0 })
   return ctx
 }
 
@@ -26,6 +26,46 @@ async function eventually(test: () => boolean, message: string): Promise<void> {
 }
 
 describe('HMR exact config paths', () => {
+  it('observes module changes when its watch base is a filesystem alias', { timeout: 20_000 }, async () => {
+    const target = mkdtempSync(join(tmpdir(), 'dsh-hmr-module-canonical-'))
+    const alias = `${target}-alias`
+    const filename = join(alias, 'module.ts')
+    symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
+    writeFileSync(filename, 'export const generation = 0\n')
+    const ctx = await bootHmr(alias, ['.'])
+    const expected = pathToFileURL(filename).href
+    const observed: string[] = []
+    ctx.on('hmr/change', (url) => { observed.push(url) })
+    try {
+      const deadline = Date.now() + 10_000
+      for (let generation = 1; !observed.includes(expected); generation += 1) {
+        if (Date.now() >= deadline) throw new Error('HMR did not observe a module change through the alias')
+        writeFileSync(filename, `export const generation = ${generation}\n`)
+        await new Promise(resolve => setTimeout(resolve, 20))
+      }
+    } finally {
+      await ctx.fiber.dispose()
+      rmSync(alias, { force: true })
+      rmSync(target, { recursive: true, force: true })
+    }
+  })
+
+  it('collapses filesystem aliases before registering an exact watch', async () => {
+    const target = mkdtempSync(join(tmpdir(), 'dsh-hmr-canonical-'))
+    const alias = `${target}-alias`
+    symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
+    const ctx = await bootHmr(alias)
+    try {
+      await ctx.hmr.registerConfig('plugins.yml', () => {})
+      await expect(ctx.hmr.registerConfig(join(realpathSync(target), 'plugins.yml'), () => {}))
+        .rejects.toThrow('config path already registered')
+    } finally {
+      await ctx.fiber.dispose()
+      rmSync(alias, { force: true })
+      rmSync(target, { recursive: true, force: true })
+    }
+  })
+
   it('observes add, change, and unlink outside its module roots', { timeout: 20_000 }, async () => {
     const dir = mkdtempSync(join(tmpdir(), 'dsh-hmr-config-'))
     const filename = join(dir, 'plugins.yml')
diff --git a/packages/util/paths/README.i18n.yaml b/packages/util/paths/README.i18n.yaml
index f79f6b2d73..6bed54f5c3 100644
--- a/packages/util/paths/README.i18n.yaml
+++ b/packages/util/paths/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/util/paths/README.md
-README.md: 2b3272e019ef2f37386da9156b06a5c151836d8c
-README.zh.md: 7fe0ec04117ae439ade653cefd1c8f5da094d8fd
+README.md: 8d10ed855a37f1205f87420b3f36f45b10e65bd3
+README.zh.md: ed3ca377bd48252fe0ef3f95186dc6eb1fb6e6a0
diff --git a/packages/util/paths/README.md b/packages/util/paths/README.md
index 2b3272e019..8d10ed855a 100644
--- a/packages/util/paths/README.md
+++ b/packages/util/paths/README.md
@@ -18,9 +18,13 @@ Shared filesystem path helpers for DeepSeek Harness user data.
 
 `expandHomePath()` expands `~`, `~/...`, and Windows-style `~\...` prefixes against the operating-system home directory. It leaves non-tilde paths and `~user/...` untouched.
 
+## Watch paths
+
+`canonicalizeWatchPath()` gives a native filesystem watcher one stable spelling of its target. It resolves the deepest existing ancestor through `fs.realpath()` and restores any missing suffix, so a file or directory may still be watched before it is created. In particular, Windows 8.3 aliases cannot be mixed with the long paths emitted by the native watcher backend.
+
 This package is intentionally small and harness-dep-free so product packages can share user-data path conventions without depending on one another.
 
 ## Known Limitations and Deferred Work
 
 - **Expansion is deliberately narrow** — only bare `~`, `~/...`, and `~\...` use the current operating-system home; named-user forms such as `~alice/...`, environment variables, and shell expressions remain unchanged.
-- **Helpers do not touch the filesystem** — callers still own directory creation, existence checks, permissions, and trust policy for the resulting path.
+- **Canonicalization reads but never mutates** — `canonicalizeWatchPath()` performs `realpath` probes and propagates errors other than absence; callers still own directory creation, permissions, and trust policy for the resulting path.
diff --git a/packages/util/paths/README.zh.md b/packages/util/paths/README.zh.md
index 7fe0ec0411..ed3ca377bd 100644
--- a/packages/util/paths/README.zh.md
+++ b/packages/util/paths/README.zh.md
@@ -18,9 +18,13 @@ DeepSeek Harness 用户数据的共享文件系统路径辅助工具。
 
 `expandHomePath()` 使用操作系统主目录展开 `~`、`~/...` 和 Windows 风格的 `~\...` 前缀。它会保留非波浪号路径和 `~user/...` 原样不变。
 
+## 监听路径
+
+`canonicalizeWatchPath()` 为原生文件系统 watcher 提供一种稳定的目标路径表示。它通过 `fs.realpath()` 解析层级最深的现有祖先路径，再拼回缺失的后缀，因此即使文件或目录尚未创建也仍可监听。尤其是，Windows 8.3 别名不能与原生 watcher 后端发出的长路径混用。
+
 该包刻意保持规模小且不依赖 harness，以便产品包共享用户数据路径约定，而不必彼此依赖。
 
 ## 已知限制与暂缓事项
 
 - **展开范围刻意保持狭窄**：只有单独的 `~`、`~/...` 和 `~\...` 使用当前操作系统主目录；`~alice/...` 等指定用户的形式、环境变量和 shell 表达式保持不变。
-- **辅助工具不会操作文件系统**：调用方仍负责目录创建、存在性检查、权限，以及对结果路径应用信任策略。
+- **规范化会读取，但绝不修改**：`canonicalizeWatchPath()` 会执行 `realpath` 探测，并传播除路径不存在以外的错误；调用方仍负责目录创建、权限，以及对结果路径应用信任策略。
diff --git a/packages/util/paths/src/index.ts b/packages/util/paths/src/index.ts
index a8f9245c72..591158d7c0 100644
--- a/packages/util/paths/src/index.ts
+++ b/packages/util/paths/src/index.ts
@@ -4,8 +4,9 @@
  * @module @deepseek-ai/dsh-paths
  */
 
+import { realpath } from 'node:fs/promises'
 import { homedir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 
 /** Directory name for the default DeepSeek Harness home under the OS home. */
 export const DSH_HOME_DIR_NAME = '.dsh'
@@ -16,6 +17,33 @@ export const DEFAULT_DSH_HOME_DISPLAY = `~/${DSH_HOME_DIR_NAME}`
 /** Environment variable that overrides the default DeepSeek Harness home. */
 export const DSH_HOME_ENV = 'DSH_HOME'
 
+/**
+ * Give a native filesystem watcher one canonical spelling of a path, even
+ * when its final components do not exist yet. The deepest existing ancestor
+ * is resolved through {@link realpath}; the missing suffix is then restored.
+ * This prevents Windows short-name aliases from being mixed with long paths
+ * emitted by the native watcher backend.
+ * @param path - Watch target or root, resolved against the current directory.
+ * @returns the target with its existing ancestor canonicalized.
+ * @throws when ancestor traversal encounters an error other than absence.
+ */
+export async function canonicalizeWatchPath(path: string): Promise<string> {
+  let current = resolve(path)
+  const missing: string[] = []
+  while (true) {
+    try {
+      return join(await realpath(current), ...missing.reverse())
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      const parent = dirname(current)
+      /* v8 ignore next -- a filesystem root exists, so traversal resolves before this guard */
+      if (parent === current) throw error
+      missing.push(basename(current))
+      current = parent
+    }
+  }
+}
+
 /**
  * Resolve the default DeepSeek Harness home using Node's platform path rules.
  * @returns the absolute default harness home path.
diff --git a/packages/util/paths/tests/paths.spec.ts b/packages/util/paths/tests/paths.spec.ts
index 08336bbcce..df5555f910 100644
--- a/packages/util/paths/tests/paths.spec.ts
+++ b/packages/util/paths/tests/paths.spec.ts
@@ -1,9 +1,11 @@
-import { homedir } from 'node:os'
+import { mkdir, mkdtemp, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
   DEFAULT_DSH_HOME_DISPLAY,
   DSH_HOME_DIR_NAME,
+  canonicalizeWatchPath,
   defaultDshHome,
   dshHomeDisplay,
   dshHomePath,
@@ -53,4 +55,22 @@ describe('dsh path helpers', () => {
     expect(dshHomeDisplay(resolve(defaultDshHome()))).toBe('~/.dsh')
     expect(dshHomeDisplay('/some/other/root')).toBe('$DSH_HOME')
   })
+
+  it('canonicalizes a watcher ancestor while preserving a missing suffix', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-watch-path-'))
+    const target = join(root, 'target')
+    const alias = join(root, 'alias')
+    try {
+      await mkdir(target)
+      await symlink(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
+      await expect(canonicalizeWatchPath(join(alias, 'later', 'config.yml'))).resolves.toBe(
+        join(await realpath(target), 'later', 'config.yml'),
+      )
+      const file = join(root, 'file')
+      await writeFile(file, 'not a directory')
+      await expect(canonicalizeWatchPath(join(file, 'child'))).rejects.toMatchObject({ code: 'ENOTDIR' })
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
 })
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 89e417558c..3b39b83897 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -3,7 +3,7 @@
 import { execFileSync } from 'node:child_process'
 import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { basename, join, resolve } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { docsPages, type DocsPage } from '../website/docs.ts'
 import {
@@ -148,7 +148,7 @@ describe('rewriteMarkdown', () => {
       repoRoot: root,
       repositoryRef: 'abc123',
       placeImage: (absPath) => {
-        const name = absPath.split('/').pop() ?? ''
+        const name = basename(absPath)
         placed.push(name)
         return `./${name}`
       },
@@ -167,7 +167,7 @@ describe('rewriteMarkdown', () => {
       pages,
       repoRoot: root,
       repositoryRef: 'abc123',
-      placeImage: absPath => `./${absPath.split('/').pop() ?? ''}`,
+      placeImage: absPath => `./${basename(absPath)}`,
     })).toBe('![logo](./logo.svg#view)\n')
   })
 
diff --git a/vendor/README.md b/vendor/README.md
index 4bf1d43f46..0a434605ae 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -38,7 +38,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 6. **`cordis/src/fiber.ts` lifecycle hardening**: locally closes three reentrant disposal gaps. An effect's owner-list wrapper is registered before its setup body runs, so an unload begun from inside setup awaits setup and every collected cleanup; synchronous setup failure removes the wrapper and rolls back collected cleanup. Async cleanup stays owner-visible until quiescence, and Cordis's internal effect composition joins an already-running cleanup while repeated public disposer calls retain their upstream single-shot result. Effect creation is rejected while the owner is `UNLOADING` (while `PENDING` and `LOADING` remain legal), preventing cleanup-time registrations from escaping the unload snapshot. Child fibers register and receive their parent-owned disposer before `internal/plugin` publication, resolve dependency declarations added by that notification before activation, drain effects attached while pending, skip plugin execution when reentrant disposal invalidates the load epoch before its first checkpoint, and contain teardown-notification failures per observer so one callback cannot starve peers or interrupt ownership cleanup. `Fiber.update()` returns its `internal/update` waterfall result, allowing Loader callers to await a restart while preserving synchronous config validation.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/ui/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
-9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/ui/app-boot/tests/hmr-config.spec.ts`.
+9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Module watches realpath their existing base directory; exact config watches realpath the deepest existing watch ancestor and restore the missing suffix. Those native paths prevent Windows short-name aliases from colliding with long-form libuv event paths while callbacks keep the requested filename. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/ui/app-boot/tests/hmr-config.spec.ts`.
 10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/ui/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git prepare run through the bundled pnpm.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/ui/app-boot/tests/config-reload.spec.ts`.
diff --git a/vendor/hmr/README.md b/vendor/hmr/README.md
index db5ac1a49a..eec6ff940f 100644
--- a/vendor/hmr/README.md
+++ b/vendor/hmr/README.md
@@ -7,6 +7,12 @@ module caches, and reloads only the plugin entries that depend on changed
 application files. Changes to framework-level dependencies fall back to
 `loader.exit()`, letting the host process restart.
 
+Module watches canonicalize their existing base directory before opening
+Chokidar. Exact config watches likewise canonicalize the deepest existing
+ancestor, then restore any missing suffix. Callbacks and diagnostics retain the
+requested absolute filename, while the native backend receives one filesystem
+spelling even when Windows supplied an 8.3 alias.
+
 ## Requirements
 
 - `@cordisjs/plugin-loader`
diff --git a/vendor/hmr/src/index.ts b/vendor/hmr/src/index.ts
index 00864cd865..c1d379e36c 100644
--- a/vendor/hmr/src/index.ts
+++ b/vendor/hmr/src/index.ts
@@ -4,7 +4,7 @@ import { ModuleLoader, type ModuleJob, type ResolveResult } from '@cordisjs/plug
 import type { Include } from '@cordisjs/plugin-include'
 import { FSWatcher, watch, type ChokidarOptions } from 'chokidar'
 import { dirname, relative, resolve } from 'node:path'
-import { stat } from 'node:fs/promises'
+import { realpath, stat } from 'node:fs/promises'
 import { handleError } from './error.ts'
 import type {} from '@cordisjs/plugin-timer'
 import { fileURLToPath, pathToFileURL } from 'node:url'
@@ -61,13 +61,18 @@ interface ConfigRegistration {
   watcher: FSWatcher
 }
 
-async function findWatchRoot(filename: string): Promise<{ root: string; depth: number }> {
+async function findWatchRoot(filename: string): Promise<{ filename: string; root: string; depth: number }> {
   let root = dirname(filename)
   let depth = 0
   while (true) {
     try {
       if (!(await stat(root)).isDirectory()) throw new Error(`config watch parent is not a directory: ${root}`)
-      return { root, depth }
+      const canonicalRoot = await realpath(root)
+      return {
+        filename: resolve(canonicalRoot, relative(root, filename)),
+        root: canonicalRoot,
+        depth,
+      }
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
       const parent = dirname(root)
@@ -129,9 +134,11 @@ class Hmr extends Service {
   async registerConfig(filename: string, refresh: () => Promise<void> | void): Promise<() => Promise<void>> {
     if (!this.watcher) throw new Error('HMR is not active')
     filename = resolve(this.baseDir, filename)
-    if (this.configs.has(filename)) throw new Error(`config path already registered: ${filename}`)
+    const target = await findWatchRoot(filename)
+    const watchFilename = target.filename
+    if (this.configs.has(watchFilename)) throw new Error(`config path already registered: ${filename}`)
 
-    const { root, depth } = await findWatchRoot(filename)
+    const { root, depth } = target
     const watcher = watch(root, {
       ...this.config,
       cwd: undefined,
@@ -140,9 +147,10 @@ class Hmr extends Service {
       ignoreInitial: false,
     })
     const registration = { watcher }
-    this.configs.set(filename, registration)
+    this.configs.set(watchFilename, registration)
     const onChange = (path: string) => {
-      if (resolve(path) !== filename) return
+      const observed = resolve(path)
+      if (observed !== filename && observed !== watchFilename) return
       this.refreshConfig(registration, filename, refresh)
     }
     watcher.on('add', onChange)
@@ -167,12 +175,12 @@ class Hmr extends Service {
     try {
       await ready.promise
       return this.ctx.effect(() => async () => {
-        if (this.configs.get(filename) === registration) this.configs.delete(filename)
+        if (this.configs.get(watchFilename) === registration) this.configs.delete(watchFilename)
         await watcher.close()
         await this.configRefreshes.get(registration)?.running
       }, 'hmr.registerConfig()')
     } catch (error) {
-      this.configs.delete(filename)
+      this.configs.delete(watchFilename)
       await watcher.close()
       throw error
     }
@@ -205,10 +213,11 @@ class Hmr extends Service {
     }
 
     const match = picomatch(ignored)
+    const watchBaseDir = await realpath(this.baseDir)
     this.watcher = watch(root, {
       ...this.config,
-      cwd: this.baseDir,
-      ignored: path => match(relative(this.baseDir, path)),
+      cwd: watchBaseDir,
+      ignored: path => match(relative(watchBaseDir, path)),
       // The initial scan re-announces files the boot just consumed: an `add`
       // for a config file refreshes an include whose initial apply may still
       // be in flight, and a failing apply then rolls this plugin back while

From df30c62e2b062da14fa0366728d821f416d72e57 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Fri, 7 Aug 2026 14:54:31 +0800
Subject: [PATCH 269/516] fix(agent-loop): latch wakes landing in the
 cancel-convergence window

---
 ...07-16-explicit-turn-cancellation.i18n.yaml |   4 +-
 .../2026-07-16-explicit-turn-cancellation.md  |   2 +-
 ...026-07-16-explicit-turn-cancellation.zh.md |   2 +-
 ...07-cancel-convergence-wake-latch.i18n.yaml |   6 +
 ...026-08-07-cancel-convergence-wake-latch.md |  29 ++++
 ...-08-07-cancel-convergence-wake-latch.zh.md |  29 ++++
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   2 +-
 docs/architecture.zh.md                       |   2 +-
 docs/cordis-catalog/events.md                 |  24 +--
 docs/core-data-structures/core.i18n.yaml      |   4 +-
 docs/core-data-structures/core.md             |   6 +-
 docs/core-data-structures/core.zh.md          |   6 +-
 docs/event-producer-consumer.md               |  24 +--
 docs/persistence-catalog.md                   |   2 +-
 packages/core/agent-loop/README.i18n.yaml     |   4 +-
 packages/core/agent-loop/README.md            |   2 +-
 packages/core/agent-loop/README.zh.md         |   2 +-
 packages/core/agent-loop/src/agent.ts         |  51 ++++--
 packages/core/agent-loop/tests/cancel.spec.ts | 154 ++++++++++++++++--
 packages/core/agent-loop/tests/loop.spec.ts   |  73 ++++++++-
 .../core/agent-loop/tests/mock-adapter.ts     |  18 +-
 packages/core/agent/src/types.ts              |   6 +-
 23 files changed, 379 insertions(+), 77 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
index 820299cf2e..2f7893a09f 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.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 .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
-2026-07-16-explicit-turn-cancellation.md: ca56c77a097e3008a50c2aec24040a4f4b6f0ba3
-2026-07-16-explicit-turn-cancellation.zh.md: bf410e5c7284a9c9914edbd14445074e71dd6943
+2026-07-16-explicit-turn-cancellation.md: 2b7cb8cc77184edf1331764d28aefe748c1614a1
+2026-07-16-explicit-turn-cancellation.zh.md: 68089e2c48d239afbff4c10cba5a202b4b6ff262
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
index ca56c77a09..2b7cb8cc77 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
@@ -18,7 +18,7 @@ An interrupted live turn ends with the coarse durable `{ kind: 'aborted' }` outc
 
 AgentLoop privately owns one `TurnCancellation` per prospective turn. It installs the holder before notifying `agent/status = running`, retains its single `AbortController` through inbox claim, `agent/pre-step`, prompt assembly, every step, model and tool execution, and `agent/turn-stopping`, then clears the exact holder immediately before publishing `turn/end`. Terminal event observers and the following durability flush therefore cannot cancel already-completed turn work even though driver status may remain `running` until the flush settles. Every participating method, event, and request value receives that same explicit signal; the next turn receives a fresh signal.
 
-The driver keeps only a cause-less pre-run marker for queued work cancelled before a turn is claimed. An effective `cancel()` emits the observe-only `agent/cancel-requested` notification with its resolved typed cause before clearing queued and steering work or aborting the holder; notification failures cannot veto the stop, and an idle call emits nothing. Work synchronously queued by a notification observer is included in that clear, while work queued by a later signal abort observer belongs to the next turn. If a `running` listener synchronously cancels old work and sends a replacement, the driver discards the aborted holder and creates a fresh one for the replacement. Repeated cancellation is first-wins for the active holder, while later calls may still clear newly queued pending work.
+The driver keeps only a cause-less pre-run marker for queued work cancelled before a turn is claimed. An effective `cancel()` emits the observe-only `agent/cancel-requested` notification with its resolved typed cause before clearing queued and steering work or aborting the holder; notification failures cannot veto the stop, and an idle call emits nothing. Work synchronously queued by a notification observer is included in that clear, while work queued by a later signal abort observer is latched and runs when the aborted activity converges to idle — a `disposed` cancel leaves it parked ([cancel-convergence wake latch](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)). If a `running` listener synchronously cancels old work and sends a replacement, the driver discards the aborted holder and creates a fresh one for the replacement. Repeated cancellation is first-wins for the active holder, while later calls may still clear newly queued pending work.
 
 The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining seams keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's process-group kill and join boundary. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
index bf410e5c72..68089e2c48 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
@@ -18,7 +18,7 @@ Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user
 
 AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它在通知 `agent/status = running` 前安装该持有者，使其中唯一的 `AbortController` 持续覆盖 inbox 领取、`agent/pre-step`、提示词组装、每个步骤、模型与工具执行以及 `agent/turn-stopping`；随后在发布 `turn/end` 前立即清除所安装的那个持有者。因此，即使驱动器状态可能在持久化刷新结算前保持 `running`，终态事件观察者及其后的持久化刷新也无法取消已完成的轮次工作。所有参与的方法、事件和请求值都会收到同一个显式 signal；下一个轮次会收到全新的 signal。
 
-对于轮次被认领前已取消的排队工作，驱动器只保留一个不携带取消原因的运行前标记。实际生效的 `cancel()` 会先发出仅供观察的 `agent/cancel-requested` 通知并携带最终确定的类型化取消原因，然后才清除排队工作和 steering（中途引导）工作或中止持有者；通知失败不能阻止此次停止，空闲状态下调用则不发出任何通知。通知观察者同步加入队列的工作也会被这次清除，而稍后由 signal 中止观察者加入队列的工作属于下一个轮次。若 `running` 监听器同步取消旧工作并发送替代提示词，驱动器会丢弃已中止的持有者，并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先，后续调用仍可清除新入队的待处理工作。
+对于轮次被认领前已取消的排队工作，驱动器只保留一个不携带取消原因的运行前标记。实际生效的 `cancel()` 会先发出仅供观察的 `agent/cancel-requested` 通知并携带最终确定的类型化取消原因，然后才清除排队工作和 steering（中途引导）工作或中止持有者；通知失败不能阻止此次停止，空闲状态下调用则不发出任何通知。通知观察者同步加入队列的工作也会被这次清除，而稍后由 signal 中止观察者加入队列的工作会被锁存，并在被中止的活动收敛到空闲时执行——`disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。若 `running` 监听器同步取消旧工作并发送替代提示词，驱动器会丢弃已中止的持有者，并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先，后续调用仍可清除新入队的待处理工作。
 
 显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 seam 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。pre-step 进入决策、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
new file mode 100644
index 0000000000..d31f344c27
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.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-08-07-cancel-convergence-wake-latch.md
+2026-08-07-cancel-convergence-wake-latch.md: fe00c78bdfadac0cc6c9c173fd04256f77a22051
+2026-08-07-cancel-convergence-wake-latch.zh.md: f76ad360e2d8b70f76c6baf53e2fde963a80b6c4
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
new file mode 100644
index 0000000000..fe00c78bdf
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
@@ -0,0 +1,29 @@
+# Agent Note: Latch wake-ups that land in the cancel-convergence window
+
+Status: implemented
+
+English | [中文](2026-08-07-cancel-convergence-wake-latch.zh.md)
+
+## Problem
+
+`Agent.cancel(cause, { keepInbox: true })` returns immediately after firing the abort signal, but the active driver may not have converged to `idle` yet: LLM stream teardown, tool cancellation, and the `turn/end` append all unwind asynchronously after `abort()` returns. A waking send arriving in that window was placed into `next-turn` while `wakeDriver()` returned early on the still-`running` phase, and the exiting driver never replayed the wake — the message stayed parked until another waking send arrived. The same dropped-wake window existed around aborted `runMaintenance` activities. Several tests enshrined the parked behavior ("waits for another wakeup"); the bug broke both `session.cancel` and the `subagent.interrupt` composition path (issue #1838). The owning cancellation and send contracts are the [explicit turn cancellation](../architecture/2026-07-16-explicit-turn-cancellation.md) and [unified send](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) decisions; the production `keepInbox` consumer is [web stop preserves queue](2026-07-31-web-stop-preserves-queue.md).
+
+## Decision
+
+The `running` phase carries a `wakeRequested` latch, mirroring the existing `maintenance` phase field. `wakeDriver()` latches whenever the current activity cannot deliver the wake — a maintenance task never reads the queue, and an aborted activity converges without restarting — while a live driver needs no latch because it claims queued work itself. The exiting activity replays the latch at its own convergence boundary (`kick`'s `finally` and `runMaintenance`'s `finally`): this placement guarantees `turn/end N` lands before the replayed driver opens `turn/start N+1`, and that `whenIdle()` sees the replayed driver through its `activityDone` loop. The replay sites run only while `inbox.hasPending`, so a latched wake removed from the inbox before convergence does not start an empty driver. A wake sent while the agent is already idle keeps its turn boundary even when its message is cleared before the driver claims — that `idle → running → idle` transition is an observable contract: the goal-session driver's pause/disarm fallback fires on the `idle` transition after a cancelled reservation (CI caught this when the guard was moved into `wakeDriver()` and suppressed the boundary). `cancel()` without `keepInbox` clears the latch together with the inbox.
+
+The `signal.aborted` discriminator is load-bearing: it separates pre-abort queued work — which `keepInbox` parks for a later wake (acceptance criterion 1) — from post-abort explicit wakes, which must run after convergence.
+
+## Alternatives considered
+
+**Have `cancel()` set the phase to `idle` immediately.** Rejected: the driver is still unwinding, so this overlaps two drivers. The replay lives in the old driver's `finally`, which then never runs — 14 of 83 tests failed, several deadlocked. Repairing it requires identity-based phase ownership plus a turn-open quiescence barrier, which is strictly more machinery and is the latch in disguise.
+
+**Latch unconditionally for every non-idle wake.** Rejected: pre-abort wakes would auto-start after a `keepInbox` cancel, violating acceptance criterion 1; the "parks queued work" test and the error-window steering test both failed.
+
+**Replay through a chained promise (`activityDone.then(...)`).** Rejected: the replay would run outside the activity's own settlement, so `whenIdle()`'s loop can resolve before the replayed driver starts; fixing that requires replacing `activityDone` at send time and depends on microtask reaction ordering — more fragile than a synchronous flag.
+
+**Wait for quiescence in the subagent adapter.** Rejected by the issue scope: the cancel/wake state machine owns the fix, not a consumer.
+
+## Consequences
+
+The `running` phase gains a `wakeRequested` field; `cancel()` without `keepInbox` clears it alongside the inbox, and a `disposed` cancel never latches, so a wake landing after disposal begins stays parked and `whenIdle()` does not wait on a full model turn over the session being torn down. A wake arriving in the sub-microtask gap between the driver's final `hasPending` check and its exit still parks — no latch fires because the phase is `running` and not aborted; closing that gap requires the unconditional latch and is deliberately out of scope. Between the aborted turn and the replayed driver, status transitions emit a transient `idle → running` pair. A waking send whose message is cleared before any driver claims it still opens an empty completed turn, preserving the observable wake boundary.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
new file mode 100644
index 0000000000..f76ad360e2
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 锁存取消收敛窗口内到达的唤醒请求
+
+Status: implemented
+
+[English](2026-08-07-cancel-convergence-wake-latch.md) | 中文
+
+## 问题
+
+`Agent.cancel(cause, { keepInbox: true })` 在触发 abort 信号后立即返回，但活动 driver 可能尚未收敛到 `idle`：LLM 流拆除、工具取消与 `turn/end` 落盘都会在 `abort()` 返回后异步展开。在该窗口内到达的唤醒 send 被放入 `next-turn`，而 `wakeDriver()` 对仍处于 `running` 的 phase 直接返回，退出的 driver 也从不重放这次唤醒——消息会一直停放到下一条唤醒 send 到达。被中止的 `runMaintenance` 活动周围也存在同样的唤醒丢失窗口。多个测试固化了停放行为（「等待下一次唤醒」）；该缺陷同时破坏了 `session.cancel` 与 `subagent.interrupt` 组合路径（issue #1838）。拥有取消与发送契约的既有决策是[显式轮次取消](../architecture/2026-07-16-explicit-turn-cancellation.md)与[统一发送](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)；生产环境中的 `keepInbox` 消费方是[Web 停止保留队列](2026-07-31-web-stop-preserves-queue.md)。
+
+## 决策
+
+`running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察契约：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 后该边界被抑制，CI 发现了这一点）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
+
+`signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（验收条件 1）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
+
+## 备选方案
+
+**让 `cancel()` 立即把 phase 置为 `idle`。** 不予采用：driver 仍在展开收尾，这会重叠两个 driver。重放逻辑位于旧 driver 的 `finally`，而该 `finally` 此后不再执行——83 个测试中有 14 个失败，多个死锁。修复它需要基于身份的 phase 所有权外加 turn 打开时的 quiescence 屏障，机制上严格更重，而且该屏障就是换了个形态的锁存。
+
+**对每个非 idle 唤醒无条件锁存。** 不予采用：中断前的唤醒会在 `keepInbox` 取消后自动启动，违反验收条件 1；「停放排队工作」测试与错误窗口的 steering 测试双双失败。
+
+**通过链式 promise（`activityDone.then(...)`）重放。** 不予采用：重放会运行在活动自身结算之外，`whenIdle()` 的循环可能在重放 driver 启动前就 resolve；修复它需要在 send 时同步替换 `activityDone`，并依赖微任务反应顺序——比同步 flag 更脆弱。
+
+**在 subagent adapter 中等待 quiescence。** 被 issue 范围否决：修复由取消/唤醒状态机拥有，而不是消费方。
+
+## 影响
+
+`running` phase 新增 `wakeRequested` 字段；不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除它，且 `disposed` 取消从不锁存——dispose 开始后到达的唤醒保持停放，`whenIdle()` 不会在拆除中的会话上等待一个完整模型 turn。落在 driver 最后一次 `hasPending` 检查与退出之间微任务间隙的唤醒仍会停放——没有锁存触发，因为 phase 是 `running` 且未 abort；关闭该间隙需要无条件锁存，刻意留作范围外。在被中止的 turn 与重放 driver 之间，状态转换会发出一次瞬态 `idle → running` 对。唤醒 send 的消息在任何 driver 认领前被清除时，仍会打开一个空的 completed turn，保留可观察的唤醒边界。
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index ca91a80b7e..de15631197 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 3080d21a24310cc8851d64719d862ec719150ab6
-architecture.zh.md: 6e2bf0c155c68e84580aecc6b7783eeffa25c640
+architecture.md: ea78faa62773a6b8ac98e5baab6e181ad6a3b7f0
+architecture.zh.md: 5a46dfaf84276de5f4dc0352a529bdd4e5d8c267
diff --git a/docs/architecture.md b/docs/architecture.md
index 3080d21a24..ea78faa627 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -121,7 +121,7 @@ Pruning precedes summaries; overflow retries require durable progress. `agent/re
 
 Adapter selection, dispatch, and iteration failures become terminal error or aborted `finish` chunks. `agent/request-error` receives request coordinates, normalized `LlmFailure`, available retry policy, and signal; middleware and consumer errors remain outside recovery. Failed chunks commit neither messages nor tool calls.
 
-Other failures use `agent/error`; cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels capability preparation; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` reports its cause before clearing and aborting; idle calls emit nothing. Durability distinguishes `aborted` cancellation from `disposed` teardown, which awaits quiescence ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)).
+Other failures use `agent/error`; cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels capability preparation; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` reports its cause before clearing and aborting; idle calls emit nothing. Waking input that lands after the abort fires but before convergence runs at the driver's convergence boundary, while a `disposed` cancel leaves it parked ([cancel-convergence wake latch](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)). Durability distinguishes `aborted` cancellation from `disposed` teardown, which awaits quiescence ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)).
 
 Turn and step events are turn-enclosed; the loop appends `user/message` events only from entered batches inside a turn. A turn opens before the initial claim and pre-step, so rejection, empty input, cancellation, or failure closes a durable turn without any step events. Standalone `compact/* { turn: null }` events consume no turn, and their lock-time markers may interleave with inbox splices. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap).
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 6e2bf0c155..5a46dfaf84 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -121,7 +121,7 @@ idle inject:
 
 适配器选择、分发与迭代失败会成为 error 或 aborted 类型的终止 `finish` 分片。`agent/request-error` 接收请求坐标、标准化 `LlmFailure`、可用的重试策略和信号；middleware 与消费方错误仍在恢复之外。失败分片既不提交消息，也不提交工具调用。
 
-其他故障使用 `agent/error`；取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消功能准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。持久化层以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
+其他故障使用 `agent/error`；取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消功能准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。abort 触发后、收敛前到达的唤醒输入会在 driver 的收敛边界执行，而 `disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。持久化层以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
 
 轮次和步骤事件均位于轮次边界内；loop 只会在轮次内从进入步骤的批次追加 `user/message`。轮次会在首次领取与 pre-step 之前打开，因此拒绝、空输入、取消或失败会关闭一个不包含任何步骤事件的持久轮次。独立的 `compact/* { turn: null }` 事件不占用轮次，其锁定时刻标记可以与 inbox splice 交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap)。
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 92c2fade12..ae16d10f07 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -33,7 +33,7 @@ A fully configured agent and live session were published. Setup is composition-o
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:154`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
 
 ### `agent/disposed` — emit
 
@@ -53,7 +53,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:163`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
 
 ### `agent/error` — emit
 
@@ -75,7 +75,7 @@ A step or turn errored. The machine reports a failure here even when the error h
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:285`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/claimed` — emit
 
@@ -97,7 +97,7 @@ One message left the inbox inside its open turn. If the proposed step is rejecte
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:192`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/discarded` — emit
 
@@ -116,7 +116,7 @@ One message was discarded from the live inbox.
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:200`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/inserted` — emit
 
@@ -135,7 +135,7 @@ One message entered the live inbox.
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:181`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
 ### `agent/pre-step` — waterfall
 
@@ -158,7 +158,7 @@ Reject a proposed step or replace the messages that enter it. Calling `next()` p
 
 Types: [Agent](../core-data-structures/core.md) · [PreStepDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:226`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request` — waterfall
 
@@ -182,7 +182,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach
 
 Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:239`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request-error` — waterfall
 
@@ -209,7 +209,7 @@ Handle one failed model-request attempt before the loop retries or closes its st
 
 Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestErrorAction](../core-data-structures/core.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:255`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
 
 ### `agent/session-start` — emit
 
@@ -231,7 +231,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:212`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
 
 ### `agent/status` — emit
 
@@ -252,7 +252,7 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running`
 
 Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:173`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
 
 ### `agent/turn-stopping` — serial
 
@@ -281,7 +281,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:273`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
 
 ## `agent-loop/*`
 
diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml
index e79d5dac2f..ee870f9334 100644
--- a/docs/core-data-structures/core.i18n.yaml
+++ b/docs/core-data-structures/core.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 docs/core-data-structures/core.md
-core.md: dbd584f10b3daf873bc14210472efb6cd315717e
-core.zh.md: 1fe1616a0c96abb4e8b91417cc4eae292416e42a
+core.md: 8f413a7a064ad6f63e0caec31354869e51139020
+core.zh.md: d0f02f0cfc2cd30fc67aacf5b17d1daf324295c5
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index dbd584f10b..8f413a7a06 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -685,7 +685,11 @@ interface Agent {
 
   /**
    * Route identified input to an inbox boundary and optionally wake the driver.
-   * Waking input submitted after active cancellation is queued for the next turn.
+   * Waking input submitted after active cancellation is queued for the next
+   * turn and runs when the aborted activity converges to idle; a `disposed`
+   * cancel leaves it parked. A wake submitted while already idle always opens
+   * its turn boundary, even when its message is cleared before the driver
+   * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
    * @param message - identified content and its producer provenance.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.
diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md
index 1fe1616a0c..d0f02f0cfc 100644
--- a/docs/core-data-structures/core.zh.md
+++ b/docs/core-data-structures/core.zh.md
@@ -693,7 +693,11 @@ interface Agent {
 
   /**
    * Route identified input to an inbox boundary and optionally wake the driver.
-   * Waking input submitted after active cancellation is queued for the next turn.
+   * Waking input submitted after active cancellation is queued for the next
+   * turn and runs when the aborted activity converges to idle; a `disposed`
+   * cancel leaves it parked. A wake submitted while already idle always opens
+   * its turn boundary, even when its message is cleared before the driver
+   * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
    * @param message - identified content and its producer provenance.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 5c60be95e1..940d89eae0 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -8,18 +8,18 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
 | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:154`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:163`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:285`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
-| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:192`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:200`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:181`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:226`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:239`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
-| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:255`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:212`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:173`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), [`jsonrpc`](../packages/ui/jsonrpc) |
-| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:273`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
+| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:185`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
+| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), [`jsonrpc`](../packages/ui/jsonrpc) |
+| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:30`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
 | `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:172`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 533ebd3a97..3845c2cb1a 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -100,7 +100,7 @@ Sources: [`packages/core/session/src/types.ts:308`](../packages/core/session/src
 }
 ```
 
-Source: [`packages/core/agent/src/types.ts:296`](../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/types.ts)
 
 ### `approval/*`
 
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index b25a0f18f1..2f165e76e4 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/core/agent-loop/README.md
-README.md: ec1948506bbaf7a3416c2031fb472a9b513b500f
-README.zh.md: 5828da301b35c95719286fb942ac239769539b67
+README.md: 2fdc60086bebc924089b5b8bd12f4b4456b1ead5
+README.zh.md: df0ba44ec5b010666737c0568bc5eeb220ff0d96
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index ec1948506b..2fdc60086b 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -67,7 +67,7 @@ Every provider call that reaches a successful finish appends exactly one `assist
 
 After `agent/request` returns a provider/model call config, the loop asks `ctx.llm.prepareCall()` to validate adapter-owned fields and materialize configured reasoning-effort and output-token defaults under the active turn signal. The prepared call retains the exact adapter registration across this asynchronous resolution, `request/header` logging, and terminal dispatch, so HMR cannot mix one adapter's capability result with another adapter's request. The header records the effective config and which fields came from the adapter. Before the next waterfall, the loop removes those marked fields from the proposal so the current exact route rematerializes its own defaults; unmarked explicit settings persist across steps and route changes. A route with no registered adapter preserves the proposed config so an `llm/stream` listener can own and short-circuit it; unhandled terminal dispatch still fails with `NO_ADAPTER`. A new loop instance applies the same provenance rule when resuming.
 
-Plugin failure ends the current turn, not the loop. Final adapter selection, dispatch, and iteration failures arrive from `ctx.llm` as terminal error or aborted finishes and enter `agent/request-error`; middleware, result processing, tools, and other extension failures remain thrown and close directly. Recovery receives request coordinates, immutable provider facts, the immutable retry policy captured by the prepared adapter registration, and the turn signal; the policy is absent when middleware owns an unprepared route. A handling listener returns `{ kind: 'retry' }`; an unhandled failure is terminal. AgentLoop owns one cancellation signal for the current admission or turn. An effective `cancel(cause)` clears pending work unless `keepInbox` is set and cooperatively aborts that signal; idle cancellation is a no-op. Durable `turn/end` records `aborted` for `user` and `parent`, while disposal records `disposed`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the lifecycle and race contract.
+Plugin failure ends the current turn, not the loop. Final adapter selection, dispatch, and iteration failures arrive from `ctx.llm` as terminal error or aborted finishes and enter `agent/request-error`; middleware, result processing, tools, and other extension failures remain thrown and close directly. Recovery receives request coordinates, immutable provider facts, the immutable retry policy captured by the prepared adapter registration, and the turn signal; the policy is absent when middleware owns an unprepared route. A handling listener returns `{ kind: 'retry' }`; an unhandled failure is terminal. AgentLoop owns one cancellation signal for the current admission or turn. An effective `cancel(cause)` clears pending work unless `keepInbox` is set and cooperatively aborts that signal; idle cancellation is a no-op. Waking input that lands after the abort fires but before the activity converges to idle is latched (`wakeRequested`) and replayed at the driver's own convergence boundary, so it runs without a further waking send; a `disposed` cancel never latches, and a wake submitted while already idle always opens its turn boundary (status shows a transient `idle → running → idle` pair even when the message was cleared). Durable `turn/end` records `aborted` for `user` and `parent`, while disposal records `disposed`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) and the [cancel-convergence wake latch](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md) own the lifecycle and race contract.
 
 Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and result context remain model-ordered. Abort stops new calls, drains started results, and retains their finalized result context without distinguishing the cancellation cause. An internal scheduler failure stops new dispatches, waits for already-started dispatches, and reaches the turn error boundary without fabricating tool results.
 
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index 5828da301b..df0ba44ec5 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -67,7 +67,7 @@ interface Config {
 
 在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的字段，并填入配置的推理（reasoning）强度和输出 token 默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。请求 header 会记录生效配置以及哪些字段来自适配器。下一次 waterfall（瀑布式事件）前，循环会从提议中移除这些带标记字段，使当前精确路由重新填入自身默认值；未带标记的显式设置会跨步骤和路由变化保留。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例在恢复时会应用同一来源规则。
 
-插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会由 `ctx.llm` 作为终止 error 或 aborted finish 返回，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose（资源释放）则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)规定生命周期与竞态契约。
+插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会由 `ctx.llm` 作为终止 error 或 aborted finish 返回，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。abort 触发后、活动收敛到空闲前到达的唤醒输入会被锁存（`wakeRequested`），并在 driver 自身的收敛边界重放，无需再发一条唤醒 send 即可执行；`disposed` 取消从不锁存，而 agent 已处于空闲时发送的唤醒总是打开自己的 turn 边界（即使消息已被清除，状态也会显示瞬态 `idle → running → idle` 对）。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose（资源释放）则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)与[取消收敛窗口唤醒锁存](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)规定生命周期与竞态契约。
 
 在步骤内，独占调用形成屏障；并行安全调用使用有界滚动池，并在启动前重新分类。只有分发／主体会重叠。策略、持久结果和结果上下文仍保持模型顺序。中止会停止新调用，drain 已启动的结果，并保留其已定案的结果上下文，不区分取消原因。内部调度器故障会停止新的分发，等待已启动的分发，然后在不虚构工具结果的情况下到达轮次错误边界。
 
diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts
index cfac8262c2..6701777a0f 100644
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -43,7 +43,7 @@ type Phase =
     lastTurn: number
     wakeRequested: boolean
   }
-  | { kind: 'running'; abort: AbortController; turn: number; step: number }
+  | { kind: 'running'; abort: AbortController; turn: number; step: number; wakeRequested: boolean }
 
 type StepEndReason = Extract<TurnEndReason, { kind: 'completed' | 'max-tokens' }>
 
@@ -112,10 +112,12 @@ export class ReactLoopAgent implements Agent {
 
   send(message: UserMessage, target: InboxTarget, wakeup: boolean): void {
     // Waking input cannot join an aborted activity, so it starts the next turn.
+    // The classification is captured BEFORE the insertion: a reentrant cancel
+    // from a synchronous splice observer must not reclassify this wake.
     const wakingAfterAbort = wakeup && this.phase.kind !== 'idle' && this.phase.abort.signal.aborted
     const resolvedTarget = wakingAfterAbort ? 'next-turn' : target
     this.inbox.splice(resolvedTarget, Infinity, 0, [message])
-    if (wakeup) this.wakeDriver()
+    if (wakeup) this.wakeDriver(wakingAfterAbort)
   }
 
   followup(input: UserMessage): void {
@@ -133,7 +135,7 @@ export class ReactLoopAgent implements Agent {
   cancel(cause: AgentCancelCause, options: CancelOptions = {}): void {
     if (!options.keepInbox) {
       this.inbox.clear()
-      if (this.phase.kind === 'maintenance') this.phase.wakeRequested = false
+      if (this.phase.kind !== 'idle') this.phase.wakeRequested = false
     }
     if (this.phase.kind !== 'idle') this.phase.abort.abort(cause)
   }
@@ -154,22 +156,44 @@ export class ReactLoopAgent implements Agent {
         return await task(maintenance.abort.signal)
       } finally {
         this.setPhase({ kind: 'idle', lastTurn: maintenance.lastTurn })
-        if (maintenance.wakeRequested) this.wakeDriver()
+        if (maintenance.wakeRequested && this.inbox.hasPending) this.wakeDriver()
         done.resolve()
       }
     })()
   }
 
-  /** Start one driver, or remember its wake behind maintenance. */
-  private wakeDriver(): void {
-    if (this.phase.kind === 'maintenance') {
-      if (!this.phase.abort.signal.aborted) this.phase.wakeRequested = true
+  /**
+   * Start one driver, or latch its wake behind maintenance or an aborted
+   * activity. A wake sent while idle always opens its turn boundary, even
+   * when its message is cleared before the driver claims; only a latched
+   * replay is suppressed when the queue no longer holds the wake.
+   * @param wakeAfterAbort - the send-time classification from {@link send}:
+   *   the wake landed after the abort fired. Captured before the inbox
+   *   insertion so a reentrant cancel cannot reclassify it.
+   */
+  private wakeDriver(wakeAfterAbort = false): void {
+    if (this.phase.kind !== 'idle') {
+      // The current activity cannot deliver this wake: a maintenance task
+      // never reads the queue, and an aborted activity converges without
+      // restarting — both latch for the exiting activity to replay. A live
+      // driver claims queued work itself, so it needs no latch. A disposal
+      // cancel never latches: replaying would make `whenIdle()` wait on a
+      // full model turn over a session being torn down.
+      const reason = this.phase.abort.signal.reason as AgentCancelCause | undefined
+      if (reason?.kind !== 'disposed' && (this.phase.kind === 'maintenance' || wakeAfterAbort)) {
+        this.phase.wakeRequested = true
+      }
       return
     }
-    if (this.phase.kind !== 'idle') return
     const driver = Promise.withResolvers<void>()
     this.activityDone = driver.promise
-    this.setPhase({ kind: 'running', abort: new AbortController(), turn: this.phase.lastTurn, step: 0 })
+    this.setPhase({
+      kind: 'running',
+      abort: new AbortController(),
+      turn: this.phase.lastTurn,
+      step: 0,
+      wakeRequested: false,
+    })
     this.loopCtx.agents.withInitiator(this, () => this.kick()).then(driver.resolve, driver.reject)
   }
 
@@ -196,7 +220,9 @@ export class ReactLoopAgent implements Agent {
     } finally {
       /* v8 ignore next -- kick owns a running phase until this driver boundary */
       if (this.phase.kind === 'running') {
-        this.setPhase({ kind: 'idle', lastTurn: this.phase.turn })
+        const { turn, wakeRequested } = this.phase
+        this.setPhase({ kind: 'idle', lastTurn: turn })
+        if (wakeRequested && this.inbox.hasPending) this.wakeDriver()
       }
     }
   }
@@ -302,6 +328,9 @@ export class ReactLoopAgent implements Agent {
     }
     if (!this.inbox.hasPending) return false
     phase.abort = new AbortController()
+    // The driver keeps running with a fresh controller: any latch set on the
+    // old one is stale, and the live driver claims the queue itself.
+    phase.wakeRequested = false
     phase.step = 0
     return true
   }
diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts
index 5c0deed621..79bc65a105 100644
--- a/packages/core/agent-loop/tests/cancel.spec.ts
+++ b/packages/core/agent-loop/tests/cancel.spec.ts
@@ -126,6 +126,121 @@ describe('Agent.cancel()', () => {
     expect(adapter.requests).toHaveLength(3)
   })
 
+  it('cancel({ keepInbox: true }) latches a waking send landing in the abort-to-idle window', async () => {
+    const adapter = new MockAdapter(['hang', textResponse('B reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('latch-window'), { provider: 'mock', model: 'mock' })
+
+    send(agent, 'active')
+    await new Promise(resolve => setTimeout(resolve, 30))
+
+    // The abort signal is set but the driver has not converged to idle yet:
+    // the waking send must be latched, not parked until another wake.
+    agent.cancel({ kind: 'user' }, { keepInbox: true })
+    send(agent, 'B')
+
+    await agent.whenIdle()
+
+    expect(userTexts(agent)).toEqual(['active', 'B'])
+    expect(adapter.requests).toHaveLength(2)
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(agent.session.events.filter(e => e.type === 'turn/end').map(e =>
+      e.type === 'turn/end' ? e.data.reason : null)).toEqual([
+      { kind: 'aborted', reason: { kind: 'user' } },
+      { kind: 'completed' },
+    ])
+  })
+
+  it('cancel() without keepInbox clears a latched wake alongside the inbox', async () => {
+    const adapter = new MockAdapter(['hang', textResponse('C reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('latch-cleared'), { provider: 'mock', model: 'mock' })
+
+    send(agent, 'active')
+    await new Promise(resolve => setTimeout(resolve, 30))
+    agent.cancel({ kind: 'user' }, { keepInbox: true })
+    send(agent, 'B') // latched behind the aborted activity
+    agent.cancel({ kind: 'user' }) // drops the inbox and the latch with it
+    await agent.whenIdle()
+
+    expect(userTexts(agent)).toEqual(['active'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(adapter.requests).toHaveLength(1)
+
+    send(agent, 'C')
+    await agent.whenIdle()
+    expect(userTexts(agent)).toEqual(['active', 'C'])
+    expect(adapter.requests).toHaveLength(2)
+  })
+
+  it('removing the latched wake before convergence suppresses the replay', async () => {
+    const adapter = new MockAdapter(['hang'])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('removed-latched-wake'), { provider: 'mock', model: 'mock' })
+
+    send(agent, 'active')
+    await new Promise(resolve => setTimeout(resolve, 30))
+
+    agent.cancel({ kind: 'user' }, { keepInbox: true })
+    const steer = createUserMessage({ content: [{ type: 'text', text: 'steer me' }], source: { kind: 'user' } })
+    agent.steer(steer) // latched behind the aborted activity
+    agent.inbox.remove(steer.id) // the wake is retracted before convergence
+
+    await agent.whenIdle()
+
+    expect(userTexts(agent)).toEqual(['active'])
+    expect(adapter.requests).toHaveLength(1)
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(agent.status).toBe('idle')
+    // No replay with nothing to run: the latched message is gone, so no
+    // empty follow-up turn is recorded.
+    expect(agent.session.events.filter(e => e.type === 'turn/start')).toHaveLength(1)
+  })
+
+  it('latches a wake arriving deep into a slow abort convergence', async () => {
+    // The stream notices the abort only after 50ms, so the driver stays in
+    // the abort-to-idle window long after `cancel()` returned: the wake must
+    // be latched across the whole window, not just the same-tick case.
+    const adapter = new MockAdapter(['hang-slow', textResponse('B reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('slow-convergence'), { provider: 'mock', model: 'mock' })
+
+    send(agent, 'A')
+    await new Promise(resolve => setTimeout(resolve, 30))
+
+    agent.cancel({ kind: 'user' }, { keepInbox: true })
+    await new Promise(resolve => setTimeout(resolve, 10))
+    send(agent, 'B')
+
+    await agent.whenIdle()
+    expect(userTexts(agent)).toEqual(['A', 'B'])
+    expect(adapter.requests).toHaveLength(2)
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+  })
+
+  it('does not latch a wake landing after disposal begins', async () => {
+    const adapter = new MockAdapter(['hang-slow', textResponse('late reply')])
+    const ctx = await harness(adapter)
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('dispose-window-wake'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const agent = handle.agent
+
+    send(agent, 'active')
+    await new Promise(resolve => setTimeout(resolve, 30))
+
+    // Dispose cancels with `{ kind: 'disposed' }`; a wake landing in the
+    // abort-to-idle window must not latch, so `whenIdle()` does not wait on
+    // a model turn over the session being torn down.
+    const disposal = handle.dispose()
+    setTimeout(() => { send(agent, 'late wake') }, 10)
+    await disposal
+
+    expect(adapter.requests).toHaveLength(1)
+    expect(userTexts(agent)).toEqual(['active'])
+  })
+
   it('cancel after waking send closes its synchronously opened turn without a step', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
@@ -228,7 +343,7 @@ describe('Agent.cancel()', () => {
     expect(userTexts(agent)).toEqual(['first', 'later'])
   })
 
-  it('replacement work queued after idle-listener cancellation waits for another wakeup', async () => {
+  it('replacement work queued after idle-listener cancellation replays at convergence', async () => {
     const adapter = new MockAdapter([
       textResponse('first reply'),
       textResponse('replacement reply'),
@@ -253,9 +368,11 @@ describe('Agent.cancel()', () => {
     if (replacementIdle === undefined) throw new Error('idle listener did not register replacement work')
     await replacementIdle
 
-    expect(adapter.requests).toHaveLength(1)
-    expect(userTexts(agent)).toEqual(['first'])
-    expect(agent.inbox.nextTurn).toHaveLength(1)
+    // The wake sent after the cancel fired is latched: the surviving
+    // replacement runs at convergence without a third message.
+    expect(adapter.requests).toHaveLength(2)
+    expect(userTexts(agent)).toEqual(['first', 'surviving replacement'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
 
     const idle = waitForIdle(ctx, agent)
     send(agent, 'wake it')
@@ -479,7 +596,7 @@ describe('Agent.cancel()', () => {
     expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false)
   })
 
-  it('a running-listener cancellation parks replacement work until another wakeup', async () => {
+  it('a running-listener cancellation replays replacement work at convergence', async () => {
     const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
@@ -497,17 +614,20 @@ describe('Agent.cancel()', () => {
     await idle
     dispose()
 
-    expect(userTexts(agent)).toEqual([])
-    expect(agent.inbox.nextTurn).toHaveLength(1)
+    // B's wake was latched behind the cancelled driver: it runs on its own.
+    expect(userTexts(agent)).toEqual(['B'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(adapter.requests).toHaveLength(1)
 
     const replacementIdle = waitForIdle(ctx, agent)
     send(agent, 'C')
     await replacementIdle
     expect(userTexts(agent)).toEqual(['B', 'C'])
+    expect(adapter.requests).toHaveLength(2)
     expect(agent.session.events.filter(event => event.type === 'turn/end')).toHaveLength(2)
   })
 
-  it('a prompt queued during pre-step cancellation waits for another wakeup', async () => {
+  it('a prompt queued during pre-step cancellation replays at convergence', async () => {
     const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
@@ -518,13 +638,15 @@ describe('Agent.cancel()', () => {
     send(agent, 'B')
 
     await idle
-    expect(userTexts(agent)).toEqual([])
-    expect(agent.inbox.nextTurn).toHaveLength(1)
+    expect(userTexts(agent)).toEqual(['B'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(adapter.requests).toHaveLength(1)
 
     const replacementIdle = waitForIdle(ctx, agent)
     send(agent, 'C')
     await replacementIdle
     expect(userTexts(agent)).toEqual(['B', 'C'])
+    expect(adapter.requests).toHaveLength(2)
     expect(agent.session.events.filter(event => event.type === 'turn/end')).toHaveLength(3)
   })
 
@@ -556,7 +678,7 @@ describe('Agent.cancel()', () => {
     expect(flat).not.toContain('steer text')
   })
 
-  it('parks replacement work queued synchronously by an abort observer', async () => {
+  it('replays replacement work queued synchronously by an abort observer', async () => {
     const adapter = new MockAdapter([
       'hang',
       textResponse('replacement reply'),
@@ -586,13 +708,15 @@ describe('Agent.cancel()', () => {
       }),
     ])
 
-    expect(adapter.requests).toHaveLength(1)
-    expect(userTexts(agent)).toEqual(['original'])
-    expect(agent.inbox.nextTurn).toHaveLength(1)
+    // The abort-observer wake was latched: replacement runs at convergence,
+    // so the original turn is followed by a completed replacement turn.
+    expect(adapter.requests).toHaveLength(2)
+    expect(userTexts(agent)).toEqual(['original', 'replacement'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
     const reasons = agent.session.events
       .filter(event => event.type === 'turn/end')
       .map(event => event.type === 'turn/end' ? event.data.reason : undefined)
-    expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }])
+    expect(reasons).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }, { kind: 'completed' }])
 
     const replacementIdle = waitForIdle(ctx, agent)
     send(agent, 'wake it')
diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts
index c8d048ca47..1173607ae9 100644
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -41,6 +41,14 @@ function send(agent: Agent, text: string) {
   agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } }))
 }
 
+/** All user-message texts recorded in the log (to assert what actually ran). */
+function userTexts(agent: Agent): string[] {
+  return agent.session.events
+    .filter(e => e.type === 'user/message')
+    .flatMap(e => e.type === 'user/message' ? e.data.content : [])
+    .flatMap(b => b.type === 'text' ? [b.text] : [])
+}
+
 describe('agent loop', () => {
   it.each([0, -1, 1.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1])(
     'rejects invalid AgentOptions.maxTokens %s before publication',
@@ -70,7 +78,7 @@ describe('agent loop', () => {
   })
 
   it('cancels queued wakeup work together with an active maintenance task', async () => {
-    const adapter = new MockAdapter([textResponse('unused')])
+    const adapter = new MockAdapter([textResponse('park reply')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('cancel-maintenance-wakeup'), {
       provider: 'mock',
@@ -87,15 +95,68 @@ describe('agent loop', () => {
     })
     await started.promise
 
-    send(agent, 'discard this wakeup')
-    agent.cancel({ kind: 'user' })
-    send(agent, 'park after cancellation')
+    send(agent, 'discard this wakeup') // latched behind the live maintenance task
+    agent.cancel({ kind: 'user' }) // drops the queue and the latch, aborts maintenance
+    send(agent, 'park after cancellation') // newer intent: re-latched, replays at convergence
 
     await expect(maintenance).rejects.toThrow('maintenance aborted')
     await agent.whenIdle()
-    expect(agent.inbox.nextTurn).toHaveLength(1)
+
+    // The pre-cancel wakeup is gone; the post-cancel wake replays at convergence.
+    expect(userTexts(agent)).toEqual(['park after cancellation'])
+    expect(agent.inbox.nextTurn).toHaveLength(0)
+    expect(adapter.requests).toHaveLength(1)
+  })
+
+  it('replays a wake latched behind maintenance at convergence', async () => {
+    const adapter = new MockAdapter([textResponse('wake reply')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('maintenance-wake-replay'), {
+      provider: 'mock',
+      model: 'mock',
+    })
+    const started = Promise.withResolvers<undefined>()
+    const finish = Promise.withResolvers<undefined>()
+    const maintenance = agent.runMaintenance(async () => {
+      started.resolve(undefined)
+      await finish.promise
+    })
+    await started.promise
+
+    send(agent, 'wake behind maintenance')
+    finish.resolve(undefined)
+    await maintenance
+    await agent.whenIdle()
+
+    expect(userTexts(agent)).toEqual(['wake behind maintenance'])
+    expect(adapter.requests).toHaveLength(1)
+  })
+
+  it('suppresses the replay when a latched maintenance wake is removed', async () => {
+    const adapter = new MockAdapter([])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('maintenance-wake-removed'), {
+      provider: 'mock',
+      model: 'mock',
+    })
+    const started = Promise.withResolvers<undefined>()
+    const finish = Promise.withResolvers<undefined>()
+    const maintenance = agent.runMaintenance(async () => {
+      started.resolve(undefined)
+      await finish.promise
+    })
+    await started.promise
+
+    const wake = createUserMessage({ content: [{ type: 'text', text: 'removed wake' }], source: { kind: 'user' } })
+    agent.followup(wake)
+    agent.inbox.remove(wake.id)
+    finish.resolve(undefined)
+    await maintenance
+    await agent.whenIdle()
+
+    expect(userTexts(agent)).toEqual([])
     expect(adapter.requests).toEqual([])
-    agent.cancel({ kind: 'user' })
+    expect(agent.session.events.filter(e => e.type === 'turn/start')).toHaveLength(0)
   })
 
   it('runs a simple turn: queued message → model → idle, with ordered events', async () => {
diff --git a/packages/core/agent-loop/tests/mock-adapter.ts b/packages/core/agent-loop/tests/mock-adapter.ts
index 6e592d9311..69dc78990c 100644
--- a/packages/core/agent-loop/tests/mock-adapter.ts
+++ b/packages/core/agent-loop/tests/mock-adapter.ts
@@ -58,14 +58,16 @@ export function toolCallResponse(rawCallId: string, name: string, args: object,
 /**
  * Mock adapter driven by a script: each model call consumes the next entry.
  * Records every request it receives for assertions. An entry may be a
- * function to compute chunks from the request, or a 'hang' marker that
- * streams one chunk then waits until aborted.
+ * function to compute chunks from the request, a 'hang' marker that
+ * streams one chunk then waits until aborted, or 'hang-slow' which takes
+ * 50ms to notice the abort — a stand-in for slow real-world teardown
+ * (LLM stream cancellation, tool unwinding).
  */
 export class MockAdapter extends LlmAdapter {
   requests: GenerateOptions[] = []
 
   constructor(
-    private script: (StreamChunk[] | ((options: GenerateOptions) => StreamChunk[]) | 'hang')[],
+    private script: (StreamChunk[] | ((options: GenerateOptions) => StreamChunk[]) | 'hang' | 'hang-slow')[],
     private readonly reasoning?: LlmModelReasoningInfo,
     private readonly defaultMaxTokens?: number,
   ) {
@@ -98,6 +100,16 @@ export class MockAdapter extends LlmAdapter {
       })
       return
     }
+    if (entry === 'hang-slow') {
+      yield { type: 'block-start', index: 0, blockType: 'text' }
+      yield { type: 'text-delta', index: 0, text: 'partial' }
+      await new Promise<void>((_resolve, reject) => {
+        const fail = (): void => { reject(new Error('aborted')) }
+        if (options.signal?.aborted) { setTimeout(fail, 50); return }
+        options.signal?.addEventListener('abort', () => { setTimeout(fail, 50) }, { once: true })
+      })
+      return
+    }
     const chunks = typeof entry === 'function' ? entry(options) : entry
     for (const chunk of chunks) {
       if (options.signal?.aborted) throw new Error('aborted')
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index fae9267347..d8cb5c4114 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -104,7 +104,11 @@ export interface Agent {
 
   /**
    * Route identified input to an inbox boundary and optionally wake the driver.
-   * Waking input submitted after active cancellation is queued for the next turn.
+   * Waking input submitted after active cancellation is queued for the next
+   * turn and runs when the aborted activity converges to idle; a `disposed`
+   * cancel leaves it parked. A wake submitted while already idle always opens
+   * its turn boundary, even when its message is cleared before the driver
+   * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
    * @param message - identified content and its producer provenance.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.

From 853f929704222cf5ce186cbce277c6fa298c7f59 Mon Sep 17 00:00:00 2001
From: _Kerman <kermanx@qq.com>
Date: Fri, 7 Aug 2026 16:25:23 +0800
Subject: [PATCH 270/516] refactor(agent-loop): tighten wake-latch comments

---
 packages/core/agent-loop/src/agent.ts | 24 +++++++++---------------
 1 file changed, 9 insertions(+), 15 deletions(-)

diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts
index 6701777a0f..6ef965e59e 100644
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -112,8 +112,7 @@ export class ReactLoopAgent implements Agent {
 
   send(message: UserMessage, target: InboxTarget, wakeup: boolean): void {
     // Waking input cannot join an aborted activity, so it starts the next turn.
-    // The classification is captured BEFORE the insertion: a reentrant cancel
-    // from a synchronous splice observer must not reclassify this wake.
+    // Captured before the insertion so a reentrant cancel from a splice observer cannot reclassify it.
     const wakingAfterAbort = wakeup && this.phase.kind !== 'idle' && this.phase.abort.signal.aborted
     const resolvedTarget = wakingAfterAbort ? 'next-turn' : target
     this.inbox.splice(resolvedTarget, Infinity, 0, [message])
@@ -165,20 +164,16 @@ export class ReactLoopAgent implements Agent {
   /**
    * Start one driver, or latch its wake behind maintenance or an aborted
    * activity. A wake sent while idle always opens its turn boundary, even
-   * when its message is cleared before the driver claims; only a latched
-   * replay is suppressed when the queue no longer holds the wake.
-   * @param wakeAfterAbort - the send-time classification from {@link send}:
-   *   the wake landed after the abort fired. Captured before the inbox
-   *   insertion so a reentrant cancel cannot reclassify it.
+   * when its message was cleared; only a latched replay is suppressed when
+   * the queue no longer holds the wake.
+   * @param wakeAfterAbort - the {@link send} classification, captured before
+   *   the inbox insertion so a reentrant cancel cannot reclassify it.
    */
   private wakeDriver(wakeAfterAbort = false): void {
     if (this.phase.kind !== 'idle') {
-      // The current activity cannot deliver this wake: a maintenance task
-      // never reads the queue, and an aborted activity converges without
-      // restarting — both latch for the exiting activity to replay. A live
-      // driver claims queued work itself, so it needs no latch. A disposal
-      // cancel never latches: replaying would make `whenIdle()` wait on a
-      // full model turn over a session being torn down.
+      // Maintenance and aborted drivers cannot deliver the wake: latch it for
+      // replay at convergence. Live drivers claim queued work themselves;
+      // disposal never latches, so teardown waits on no model turn.
       const reason = this.phase.abort.signal.reason as AgentCancelCause | undefined
       if (reason?.kind !== 'disposed' && (this.phase.kind === 'maintenance' || wakeAfterAbort)) {
         this.phase.wakeRequested = true
@@ -328,8 +323,7 @@ export class ReactLoopAgent implements Agent {
     }
     if (!this.inbox.hasPending) return false
     phase.abort = new AbortController()
-    // The driver keeps running with a fresh controller: any latch set on the
-    // old one is stale, and the live driver claims the queue itself.
+    // A fresh controller makes a latch set on the old one stale: the live driver claims the queue itself.
     phase.wakeRequested = false
     phase.step = 0
     return true

From bdbc6c3da4b2579973574a0bea54a4d851b32a8e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:57:31 +0800
Subject: [PATCH 271/516] fix(windows): preserve graceful CLI shutdown

---
 ...8-native-windows-pull-request-ci.i18n.yaml |  4 +-
 ...26-08-08-native-windows-pull-request-ci.md |  2 +
 ...08-08-native-windows-pull-request-ci.zh.md |  2 +
 apps/cli/src/profile-boot.ts                  | 69 +++++++++++--------
 apps/cli/tests/built-bin.e2e.ts               | 37 +++++++---
 5 files changed, 76 insertions(+), 38 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index c9d06abacf..b1b0079115 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: 8b6766cfa8df48c6c61410c06a410340a0c9bb21
-2026-08-08-native-windows-pull-request-ci.zh.md: 29cb1f725f4212c13974d642388edaf1df16b759
+2026-08-08-native-windows-pull-request-ci.md: 80fccabdc9ddebba2204732677da31363b74a184
+2026-08-08-native-windows-pull-request-ci.zh.md: 9d00f4fad6eb817968609c3af1f278cc6794e7c7
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 8b6766cfa8..80fccabdc9 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -16,6 +16,8 @@ The aggregate keeps workspace build and production-site failures blocking while
 
 The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path.
 
+The next exact-head run exposed one remaining observational built-bin failure: its lifecycle fixtures used `process.kill()` or `subprocess.kill()` to send `SIGTERM`, which unconditionally terminates a Windows target instead of delivering the registered process event for graceful disposal. POSIX acceptance still sends the real signal. On Windows the fixture requests that same registered event from inside the child, directly for a self-terminating probe and through a marker for parent-controlled lifecycle cases, so the assembled shutdown and disposal path remains covered without asserting an operating-system facility that does not exist. That acceptance then exposed the underlying early-shutdown race: a signal could dispose the root after boot returned while fallback HMR watchers were mounting, and the resulting inactive-service error escaped as a boot failure. Post-boot setup now admits work only while the authoritative root fiber is active and contains a concurrent setup error only when the same invocation's recorded signal already owns shutdown; unrelated HMR failures remain loud.
+
 Wine-only infrastructure is absent from the supported workflow: there is no apt-cache producer, compatibility script, hoisted snapshot install, Windows Node download, or local `check:windows-wine` command. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) remains historical evidence for its measured latency and fidelity trade-offs, not a current execution path.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 29cb1f725f..9d00f4fad6 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -16,6 +16,8 @@ Status: implemented
 
 首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。
 
+下一次分支头精确运行暴露出观测项中剩余的一项 built-bin 故障：其生命周期 fixture（测试前置数据）通过 `process.kill()` 或 `subprocess.kill()` 发送 `SIGTERM`；在 Windows 上，这种调用会无条件终止目标进程，而不会交付为优雅释放所注册的进程事件。POSIX 验收仍发送真实信号。在 Windows 上，fixture 改为从子进程内部请求同一个已注册事件：自终止探测直接请求，由父进程控制的生命周期场景则通过标记请求；因此，完整组装后的关闭与释放路径仍得到覆盖，也无需断言操作系统提供了本不存在的信号机制。该项验收随即暴露出底层的提前关闭竞态：boot 返回后，回退 HMR watcher 仍在挂载，此时信号可能对根 fiber 执行 dispose（资源释放），由此产生的服务未激活错误会逸出并被报告为 boot 失败。boot 后 setup 现在只会在权威根 fiber 仍处于活跃状态时接纳工作；只有当本次调用所记录的信号已取得关闭流程所有权时，才会隔离并发 setup 错误，无关的 HMR 故障仍会响亮失败。
+
 受支持的工作流不含 Wine 专属基础设施：不存在 apt 缓存生产者、兼容性脚本、对仓库快照执行的 hoisted 安装、Windows Node 下载或本地 `check:windows-wine` 命令。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)仍作为其实测延迟与保真度取舍的历史证据，而非当前执行路径。
 
 ## 曾考虑的替代方案
diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts
index 4730ec7073..b49bd37535 100644
--- a/apps/cli/src/profile-boot.ts
+++ b/apps/cli/src/profile-boot.ts
@@ -10,7 +10,7 @@
 import { writeFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { Context } from 'cordis'
+import { FiberState, type Context } from 'cordis'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import {
   boot,
@@ -168,6 +168,10 @@ export interface RunProfileOptions {
   environment: EnvironmentSnapshot
 }
 
+function suppressSignalShutdownError(signal: AbortSignal, error: unknown): void {
+  if (!signal.aborted) throw error
+}
+
 /**
  * Boot one profile invocation end to end and leave process lifetime to the
  * mounted plugins (or to the one-shot runner when `task` is present).
@@ -196,11 +200,16 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
 
   const app: { current?: Context } = {}
   const shutdown = createProcessShutdown(async () => { await app.current?.fiber.dispose() })
+  const signalShutdown = new AbortController()
+  const interrupt = (code: number): void => {
+    signalShutdown.abort()
+    shutdown.interrupt(code)
+  }
   // Signals own teardown throughout the startup window, not only after boot()
   // settles: an inserted front door can publish readiness before sibling rows
   // finish mounting.
-  process.on('SIGTERM', () => { shutdown.interrupt(options.task === undefined ? 0 : 143) })
-  process.on('SIGINT', () => { shutdown.interrupt(130) })
+  process.on('SIGTERM', () => { interrupt(options.task === undefined ? 0 : 143) })
+  process.on('SIGINT', () => { interrupt(130) })
   installFailLoud(NAME, process, async () => {
     await app.current?.fiber.dispose()
   })
@@ -243,33 +252,37 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
     await options.prepare?.(hostCtx, composed.rows)
   })
   app.current = ctx
-  // A surface can dispose the whole tree while startup was still in flight
-  // (early SIGTERM); the Loader service goes with it and there is nothing to
-  // keep live.
-  if (watchProfilePatch && ctx.get('loader') !== undefined) {
-    // Config-only HMR for the live profile patch layer: the web bundle
-    // disables the shared module-reload `hmr` row (its reload lifecycle is
-    // untested), so when the composition leaves no HMR service, mount a
-    // watch-only instance with no module roots — cordis.patch.yml edits stay
-    // live on every long-lived surface. A silent skip would break the
-    // documented hot-reload contract. HMR injects the timer service, which a
-    // bare custom profile may not mount either.
-    if (ctx.get('hmr') === undefined) {
-      if (ctx.get('timer') === undefined) {
-        await ctx.loader.create({ name: '@cordisjs/plugin-timer' })
+  // A surface can dispose the whole tree while startup or this post-boot
+  // watcher setup is still in flight. Fiber state owns liveness; the local
+  // signal fact distinguishes that expected exit race from a real HMR error.
+  if (watchProfilePatch && !signalShutdown.signal.aborted && ctx.fiber.state === FiberState.ACTIVE) {
+    try {
+      // Config-only HMR for the live profile patch layer: the web bundle
+      // disables the shared module-reload `hmr` row (its reload lifecycle is
+      // untested), so when the composition leaves no HMR service, mount a
+      // watch-only instance with no module roots — cordis.patch.yml edits stay
+      // live on every long-lived surface. A silent skip would break the
+      // documented hot-reload contract. HMR injects the timer service, which a
+      // bare custom profile may not mount either.
+      if (ctx.get('hmr') === undefined) {
+        if (ctx.get('timer') === undefined) {
+          await ctx.loader.create({ name: '@cordisjs/plugin-timer' })
+        }
+        await ctx.loader.create({ name: '@cordisjs/plugin-hmr', config: { root: [] } })
       }
-      await ctx.loader.create({ name: '@cordisjs/plugin-hmr', config: { root: [] } })
+      await watchUserPatches(ctx, {
+        binName: NAME,
+        filename: composed.profile.patchPath,
+        compose: composeLive,
+      })
+      await watchUserPatches(ctx, {
+        binName: NAME,
+        filename: homePatchPath(),
+        compose: composeLive,
+      })
+    } catch (error) {
+      suppressSignalShutdownError(signalShutdown.signal, error)
     }
-    await watchUserPatches(ctx, {
-      binName: NAME,
-      filename: composed.profile.patchPath,
-      compose: composeLive,
-    })
-    await watchUserPatches(ctx, {
-      binName: NAME,
-      filename: homePatchPath(),
-      compose: composeLive,
-    })
   }
   return { ctx, shutdown }
 }
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index a42780581f..05e248a8f6 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -49,6 +49,7 @@ interface ProfileLifecycleFixture {
   ready: string
   settled: string
   disposed: string
+  interrupt: string
 }
 
 /**
@@ -61,16 +62,23 @@ function createProfileLifecycleFixture(): ProfileLifecycleFixture {
   const ready = join(home, 'ready')
   const settled = join(home, 'settled')
   const disposed = join(home, 'disposed')
+  const interrupt = join(home, 'interrupt')
   const bundleDir = join(home, 'lifecycle-bundle')
   mkdirSync(bundleDir, { recursive: true })
   writeFileSync(join(bundleDir, 'plugin.mjs'), [
-    "import { writeFileSync } from 'node:fs'",
+    "import { existsSync, writeFileSync } from 'node:fs'",
     "import { join } from 'node:path'",
     "export const name = 'profile-lifecycle-fixture'",
     'export function apply(ctx, config = {}) {',
     '  let active = true',
     '  // Keep the event loop alive so process lifetime is signal-owned, like a real surface.',
-    '  const heartbeat = setInterval(() => {}, 1000)',
+    '  // Windows has no deliverable SIGTERM; the marker emits the same process event there.',
+    '  let interrupted = false',
+    '  const heartbeat = setInterval(() => {',
+    '    if (interrupted || !existsSync(process.env.RAW_INTERRUPT_FILE)) return',
+    '    interrupted = true',
+    "    process.emit('SIGTERM')",
+    '  }, 20)',
     '  // Echo the mounted generation so the hot-reload e2e can assert both an',
     '  // applied override and its removal reverting to this bundle default.',
     "  writeFileSync(join(process.env.DSH_HOME, 'config-echo'), String(config.generation ?? 'bundle-default'))",
@@ -118,7 +126,7 @@ function createProfileLifecycleFixture(): ProfileLifecycleFixture {
   for (const file of ['package.json', 'cordis.patch.yml', 'plugin.mjs']) {
     writeFileSync(join(linkTarget, file), readFileSync(join(bundleDir, file)))
   }
-  return { home, ready, settled, disposed }
+  return { home, ready, settled, disposed, interrupt }
 }
 
 function startProfileLifecycle(fixture: ProfileLifecycleFixture) {
@@ -131,10 +139,22 @@ function startProfileLifecycle(fixture: ProfileLifecycleFixture) {
       RAW_READY_FILE: fixture.ready,
       RAW_SETTLED_FILE: fixture.settled,
       RAW_DISPOSED_FILE: fixture.disposed,
+      RAW_INTERRUPT_FILE: fixture.interrupt,
     },
   })
 }
 
+function requestProfileShutdown(
+  child: ReturnType<typeof startProfileLifecycle>,
+  fixture: ProfileLifecycleFixture,
+): void {
+  if (process.platform === 'win32') {
+    writeFileSync(fixture.interrupt, 'interrupt')
+    return
+  }
+  child.kill('SIGTERM')
+}
+
 function createEnvironmentProbeProfile(home: string, project: string): void {
   const pluginFile = join(project, 'environment-probe.mjs')
   writeFileSync(pluginFile, [
@@ -152,7 +172,8 @@ function createEnvironmentProbeProfile(home: string, project: string): void {
     "      if (chunk.type === 'text-delta') text += chunk.text",
     '    }',
     '    process.stdout.write(`${text}\\n`)',
-    "    process.kill(process.pid, 'SIGTERM')",
+    "    if (process.platform === 'win32') process.emit('SIGTERM')",
+    "    else process.kill(process.pid, 'SIGTERM')",
     '  })',
     '}',
     '',
@@ -321,9 +342,9 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     const child = startProfileLifecycle(fixture)
     try {
       await waitForFile(fixture.ready)
-      child.kill('SIGTERM')
+      requestProfileShutdown(child, fixture)
       const result = await child
-      expect(result.exitCode).toBe(0)
+      expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}\nsignal: ${String(result.signal)}`).toBe(0)
       expect(result.signal).toBeUndefined()
       expect(existsSync(fixture.disposed)).toBe(true)
     } finally {
@@ -373,9 +394,9 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       ].join('\n'))
       await waitForFile(fixture.ready)
       expect(readFileSync(configFile, 'utf8')).toBe('home')
-      child.kill('SIGTERM')
+      requestProfileShutdown(child, fixture)
       const result = await child
-      expect(result.exitCode).toBe(0)
+      expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}\nsignal: ${String(result.signal)}`).toBe(0)
       expect(result.signal).toBeUndefined()
       expect(existsSync(fixture.disposed)).toBe(true)
     } finally {

From 66a21a38b13a051af3d856cde2033e84af5a3aba Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 11:59:19 +0800
Subject: [PATCH 272/516] feat(subagent): add current-turn interrupt RPC
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ctx.subagents.interrupt() stops one live continuable child's current turn
via Agent.cancel(cause, { keepInbox: true }) under either a human durable
parent address or an exact live ancestor Agent. Fire-and-return: admission
is synchronous, quiescence is not awaited. Pending inbox work, the
Activation, and published descendants are preserved; only a later waking
send resumes the parked FIFO queue. Absent, one-shot, and disposing
targets are accepted no-ops.

The new Host RPC subagent.interrupt calls only that primitive with user
authority — no catalog, history, persistence, or parent-registry lookup —
so a live child stays stoppable while its parent Agent is offline.

Refs #1535
---
 ...6-continuable-subagent-interrupt.i18n.yaml |   6 +
 ...26-08-06-continuable-subagent-interrupt.md |  42 ++++
 ...08-06-continuable-subagent-interrupt.zh.md |  42 ++++
 docs/cordis-catalog/events.md                 |   8 +-
 docs/cordis-catalog/services.md               |  20 +-
 .../client/connection/src/client/fixture.ts   |   2 +
 packages/client/connection/tests/fake-api.ts  |   3 +
 packages/client/runtime/tests/fake-api.ts     |   4 +
 .../cordis/tool-cordis/src/api-catalog.ts     |   8 +
 packages/host/apiproxy/src/api-proxy.ts       |  25 ++
 packages/host/apiproxy/src/api/index.ts       |   3 +-
 packages/host/apiproxy/src/api/rpc-map.ts     |   1 +
 .../host/apiproxy/src/api/subagents.schema.ts |  12 +
 packages/host/apiproxy/src/api/subagents.ts   |  18 ++
 packages/host/apiproxy/src/fetch/client.ts    |   4 +
 packages/host/apiproxy/src/fetch/handler.ts   |   2 +
 .../tests/api-proxy-subagents.spec.ts         |  55 ++++-
 .../apiproxy/tests/client-handler.spec.ts     |  27 +++
 .../host/apiproxy/tests/fetch-carrier.spec.ts |   8 +
 packages/subagent/subagent/README.i18n.yaml   |   4 +-
 packages/subagent/subagent/README.md          |   7 +-
 packages/subagent/subagent/README.zh.md       |   7 +-
 .../subagent/subagent/src/continuation.ts     |  71 ++++++
 packages/subagent/subagent/src/index.ts       |  20 ++
 .../subagent/tests/continuation.spec.ts       | 220 ++++++++++++++++++
 .../subagent/subagent/tests/service.spec.ts   |  10 +
 scripts/gen-cordis-catalog.ts                 |   1 +
 27 files changed, 613 insertions(+), 17 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
 create mode 100644 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md

diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
new file mode 100644
index 0000000000..fe6e8870f5
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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-08-06-continuable-subagent-interrupt.md
+2026-08-06-continuable-subagent-interrupt.md: 729f1eb8259aa28aa771ed71872ebce9cadd4ed8
+2026-08-06-continuable-subagent-interrupt.zh.md: 15fe34d8b5e1d67623aabfe08710f341739e92e1
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
new file mode 100644
index 0000000000..729f1eb825
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -0,0 +1,42 @@
+# Agent Note: Continuable subagent current-turn interrupt
+
+Status: implemented
+
+English | [中文](2026-08-06-continuable-subagent-interrupt.zh.md)
+
+## Problem
+
+A running continuable subagent could not be stopped without destroying it. The continuation manager cancels child Agents only inside whole-Activation teardown (settlement, drain, scoped drain), `send_message`/`subagent.prompt` only add work, and the Web composer's Stop button was deliberately limited to ordinary sessions. A human watching a continuable child burn tokens on a wrong path had no lever short of killing the parent tree, and when the direct parent Agent was offline the child was entirely untouchable even though its Activation stayed live. One-shot runs have holder-owned disposal and task-kill; continuable children had no analogous current-turn control.
+
+## Decision
+
+`ctx.subagents.interrupt(targetSessionId, authority)` stops only the live target's current turn. The manager primitive authorizes synchronously, calls the existing `Agent.cancel(cause, { keepInbox: true })`, and returns `void` — fire-and-return: the cancel signal is guaranteed issued, target quiescence is not awaited. Nothing else changes: no Activation disposal, no handle release, no descendant cascade, no inbox clearing, and no `AgentLoop` or `CancelOptions` change. Because `keepInbox` parks the pending queue at idle, an interrupt never auto-starts the next queued follow-up; only a later explicit waking send resumes the preserved FIFO order.
+
+Authority is a closed two-variant union, deliberately wider than delivery authority because stopping a turn is idempotent and delivers no content:
+
+- `{ kind: 'user', parentSessionId }` — a human presents the durable direct-parent address. The live target's `session.header.parentSession` must match; no live parent Agent, catalog read, or persistence access is involved, which is exactly what keeps a live child stoppable while its parent Agent is offline. Cancel cause `user`.
+- `{ kind: 'ancestor', agent }` — an exact live ancestor Agent (direct parent or deeper). The caller must be the registry's current entry for its id (stale callers are rejected even for absent targets), must not be the target itself, and must appear in the Activation's materialization-time `ancestry` WeakSet. Cancel cause `parent`.
+
+Targets are resolved only in the manager's process-local Activation map. An absent id — unknown, one-shot, or naturally settled — is an accepted no-op, which uniformly covers completion races and repeat requests without leaking durable-catalog information; a target whose disposal transaction is already open is likewise an accepted no-op after authorization. One-shot lifecycle (holder `dispose()`, task-kill) is untouched. `SubagentService.interrupt()` treats a manager-less composition as an accepted no-op rather than `CONTINUATION_UNAVAILABLE`, because without a manager no manager-owned live Activation can exist.
+
+The Host RPC `subagent.interrupt` takes the continuable `SubagentAddress` and returns `{ accepted: true }`. Its implementation calls only the core primitive with `user` authority — deliberately no `catalogChild()`, `listChildren()`, `sessionQuery`, or parent-registry lookup. A live target with a mismatched parent address maps to `subagent-unauthorized`; unexpected failures map to `internal` without leaking error text onto the wire.
+
+## Alternatives considered
+
+**Route human interrupts through `session.cancel`.** The generic session cancel requires an attached ordinary session and rejects subagent-owned sessions; widening it would entangle subagent authority rules with ordinary session routing. A subagent-domain RPC keeps the address-based authorization and the parent-offline guarantee explicit.
+
+**Await target quiescence and return the turn outcome.** Cancellation is cooperative, so quiescence is unbounded; holding the RPC (and a `ChildLock` slot) open invites timeouts and convoying against delivery and disposal. Acceptance-of-signal is the only fact the caller needs, and races (natural completion, disposal) already settle idempotently.
+
+**Reuse whole-Activation disposal for interrupt.** Disposal cancels without `keepInbox`, flushes, captures, and releases the handle — it destroys queued work and the child's residency. Interrupt is a control operation on one turn, not a lifecycle operation on the Activation.
+
+**Extend `send_message`/`followup` authority to ancestors while at it.** Delivery injects content into a conversation and is not idempotent; its exact-direct-parent authority stays unchanged. Only interrupt gets the wider ancestor and address-based user authority.
+
+**Auto-resume the parked queue after an interrupt.** Immediately starting queued follow-up B after aborting A would make the interrupt look ignored and steal the human's window to redirect the child. Parking until an explicit waking send keeps the stop observable and the FIFO order intact.
+
+## Consequences
+
+A human or ancestor can now stop a runaway continuable turn without losing the child, its queued work, or its running descendants; the cost is a deliberately weak postcondition (`accepted` means "signal issued", so a target may remain visibly `running` until it observes the signal) that clients must render honestly. The parked-queue rule means an interrupted child sits idle with retained work until someone sends a waking message — an intentional human-in-the-loop pause, not a scheduler defect. The Web Stop action and the model-facing `interrupt_agent` tool build on this primitive in the stacked follow-up PRs for issue #1535.
+
+## Testing
+
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
new file mode 100644
index 0000000000..15fe34d8b5
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -0,0 +1,42 @@
+# Agent Note: Continuable subagent 当前轮次中断
+
+Status: implemented
+
+[English](2026-08-06-continuable-subagent-interrupt.md) | 中文
+
+## Problem
+
+一个正在运行的 continuable subagent 无法在不销毁它的前提下被停止。继续执行管理器只在整个 Activation 拆除（结算、drain、scoped drain）内部取消子 Agent，`send_message`／`subagent.prompt` 只能增加工作，而 Web composer 的 Stop 按钮被刻意限制在普通会话。人类眼看着一个 continuable child 在错误路径上烧 token，除了干掉整个 parent 树没有任何手段；当直接 parent Agent 离线时，即使 child 的 Activation 仍然在线，它也完全不可触及。一次性运行有持有方拥有的 disposal 和 task-kill；continuable child 没有对应的当前轮次控制。
+
+## Decision
+
+`ctx.subagents.interrupt(targetSessionId, authority)` 只停止在线目标的当前轮次。管理器原语同步完成鉴权，调用现有的 `Agent.cancel(cause, { keepInbox: true })`，然后返回 `void`——fire-and-return：保证取消信号已发出，但不等待目标静止。其余一切不变：不 dispose Activation、不释放 handle、不级联后代、不清空 inbox，也不改动 `AgentLoop` 或 `CancelOptions`。由于 `keepInbox` 让待处理队列停在 idle，中断绝不会自动启动下一个排队的 follow-up；只有之后一次显式唤醒发送才按保留的 FIFO 顺序恢复。
+
+授权是一个封闭的双变体 union，刻意比投递权限更宽，因为停止一个轮次是幂等的且不投递任何内容：
+
+- `{ kind: 'user', parentSessionId }`——人类出示持久化直接 parent 地址。在线目标的 `session.header.parentSession` 必须匹配；不涉及在线 parent Agent、目录读取或持久化访问，这正是 parent Agent 离线时在线 child 仍可被停止的原因。取消 cause 为 `user`。
+- `{ kind: 'ancestor', agent }`——一个确切在线的 ancestor Agent（直接 parent 或更深）。调用方必须是注册表中其 id 的当前条目（过期调用方即使目标不存在也被拒绝），不得是目标本身，并且必须出现在 Activation 物化时记录的 `ancestry` WeakSet 中。取消 cause 为 `parent`。
+
+目标只在管理器进程本地的 Activation map 中解析。不存在的 id——未知、一次性或已自然结算——是被接受的 no-op，统一覆盖完成竞态和重复请求而不泄露持久化目录信息；disposal 事务已打开的目标在鉴权后同样是被接受的 no-op。一次性生命周期（持有方 `dispose()`、task-kill）不受影响。`SubagentService.interrupt()` 把未绑定管理器的组合视为被接受的 no-op 而不是 `CONTINUATION_UNAVAILABLE`，因为没有管理器就不可能存在管理器拥有的在线 Activation。
+
+Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回 `{ accepted: true }`。它的实现只以 `user` 授权调用核心原语——刻意不调用 `catalogChild()`、`listChildren()`、`sessionQuery` 或 parent 注册表查找。parent 地址不匹配的在线目标映射为 `subagent-unauthorized`；意外失败映射为 `internal`，不把错误文本泄漏到 wire。
+
+## Alternatives considered
+
+**让人类中断走 `session.cancel`。** 通用会话取消要求附着的普通会话并拒绝 subagent 拥有的会话；放宽它会把 subagent 权限规则缠进普通会话路由。subagent 域的 RPC 让基于地址的鉴权和 parent 离线保证保持显式。
+
+**等待目标静止并返回轮次结果。** 取消是协作式的，静止时间无上界；让 RPC（以及一个 `ChildLock` 槽位）保持打开会招致超时并与投递、disposal 形成排队。调用方需要的唯一事实是信号已被接受，而竞态（自然完成、disposal）本就幂等收敛。
+
+**复用整个 Activation 的 disposal 来做中断。** disposal 的取消不带 `keepInbox`，还会 flush、capture 并释放 handle——它销毁排队工作和 child 的驻留。中断是针对一个轮次的控制操作，不是针对 Activation 的生命周期操作。
+
+**顺手把 `send_message`／`followup` 权限扩展到 ancestor。** 投递向对话注入内容且不幂等；其确切直接 parent 权限保持不变。只有中断获得更宽的 ancestor 与基于地址的用户授权。
+
+**中断后自动恢复被暂停的队列。** 在中止 A 后立即启动排队的 follow-up B 会让中断看起来被忽略，并夺走人类重新引导 child 的窗口。暂停到显式唤醒发送为止，让停止可观察且 FIFO 顺序完整。
+
+## Consequences
+
+人类或 ancestor 现在可以停止一个失控的 continuable 轮次，而不丢失 child、其排队工作或正在运行的后代；代价是一个刻意保持弱的后置条件（`accepted` 表示"信号已发出"，目标在观察到信号前可能仍显示 `running`），客户端必须如实呈现。暂停队列规则意味着被中断的 child 会带着保留的工作停在 idle，直到有人发送唤醒消息——这是有意的 human-in-the-loop 暂停，不是调度器缺陷。Web 的 Stop 操作和面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
+
+## Testing
+
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index ae16d10f07..edfd046430 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -699,7 +699,7 @@ A published child settled. Scope-filtered dispatch uses the same delegating pare
 
 Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md)
 
-Source: [`packages/subagent/subagent/src/index.ts:160`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/provider-added` — emit
 
@@ -716,7 +716,7 @@ A provider became resolvable in the registry.
 
 Types: [SubagentProvider](../core-data-structures/subagent.md)
 
-Source: [`packages/subagent/subagent/src/index.ts:134`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/provider-removed` — emit
 
@@ -731,7 +731,7 @@ A provider left the registry. Accepted runs remain holder-owned.
 'subagent/provider-removed'(name: string): void
 ```
 
-Source: [`packages/subagent/subagent/src/index.ts:140`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:142`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/start` — emit
 
@@ -753,7 +753,7 @@ A provider established a published child. For in-process providers, `ctx.agents.
 
 Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md)
 
-Source: [`packages/subagent/subagent/src/index.ts:151`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
 
 ## `system-prompt/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index a22c3464eb..caf081b5a6 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2071,6 +2071,22 @@ async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
  */
 async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>
 
+/**
+ * Interrupt one live continuable child's current turn under a human parent
+ * address or an exact live ancestor Agent. Fire-and-return: the cancel
+ * signal is issued before this returns, but the target may keep running
+ * until it observes the signal. Pending inbox work, the Activation, and
+ * published descendants are preserved; only a later waking send resumes the
+ * parked FIFO queue. An absent target — including a one-shot or unknown id —
+ * is an accepted no-op, as is a manager-less composition, which cannot own a
+ * live Activation.
+ * @param targetSessionId - the durable child session id to interrupt.
+ * @param authority - the human parent address or exact live ancestor Agent.
+ * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
+ *   live target.
+ */
+interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
+
 /**
  * Deliver selected content from one live continuable child to its durable
  * direct parent. The child is the authority credential; callers cannot name a
@@ -2171,9 +2187,9 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
+Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentInterruptAuthority](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
 
-Source: [`packages/subagent/subagent/src/index.ts:165`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
 
 ## `ctx.subprocess` — `SubprocessService` (abstract seam)
 
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index ec3199ee02..2a081284b2 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -2203,6 +2203,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
       prompt: request => Promise.resolve(ok(request, {
         messageId: `fixture-message-${request.payload.childSessionId}` as never,
       })),
+      interrupt: request => Promise.resolve(ok(request, { accepted: true as const })),
     },
     host: {
       describe: request => ok(request, { version: '0.0.0-fixture', cwd: '/tmp/fixture', attachedSessions }),
@@ -2748,6 +2749,7 @@ export class FixtureApiClient extends AbstractApiClient {
       case 'subagent.list': return this.api.subagents.list(request)
       case 'subagent.history': return this.api.subagents.history(request)
       case 'subagent.prompt': return this.api.subagents.prompt(request, signal)
+      case 'subagent.interrupt': return this.api.subagents.interrupt(request)
       case 'host.describe': return this.api.host.describe(request)
       case 'host.pickDirectory': return this.api.host.pickDirectory(request, new AbortController().signal)
       case 'host.listDirectory': return this.api.host.listDirectory(request, new AbortController().signal)
diff --git a/packages/client/connection/tests/fake-api.ts b/packages/client/connection/tests/fake-api.ts
index cc4504e538..ef5071316e 100644
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -126,6 +126,9 @@ export class FakeApiClient implements IApiClient {
     prompt: (payload: unknown) => this.record('subagent.prompt', payload, Promise.resolve(ok({
       messageId: 'fake-message' as never,
     }))),
+    interrupt: (payload: unknown) => this.record('subagent.interrupt', payload, Promise.resolve(ok({
+      accepted: true as const,
+    }))),
   }
 
   readonly host: IApiClient['host'] = {
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
index 2f4299ce6c..5e510c0012 100644
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -140,10 +140,14 @@ export class FakeApiClient implements IApiClient {
   onSubagentPrompt: (payload: unknown) => Promise<RpcResponse<{ messageId: never }>>
     = () => Promise.resolve(ok({ messageId: 'fake-message' as never }))
 
+  onSubagentInterrupt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>>
+    = () => Promise.resolve(ok({ accepted: true as const }))
+
   readonly subagents: IApiClient['subagents'] = {
     list: (payload: unknown) => this.record('subagent.list', payload, this.onSubagentList(payload)),
     history: (payload: unknown) => this.record('subagent.history', payload, this.onSubagentHistory(payload)),
     prompt: (payload: unknown) => this.record('subagent.prompt', payload, this.onSubagentPrompt(payload)),
+    interrupt: (payload: unknown) => this.record('subagent.interrupt', payload, this.onSubagentInterrupt(payload)),
   }
 
   readonly host: IApiClient['host'] = {
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index dec95f3b5f..acaefa5d5f 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -928,6 +928,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>',
         jsDoc: '/**\n * Deliver one later message to a continuable child as its next FIFO turn. A\n * resident child\'s Agent inbox accepts it directly (waking a `waiting`\n * Activation), while an absent one is cold-resumed from its persisted\n * Session. The Agent inbox is the only queue, so every accepted message has\n * one observable order.\n * @param parent - the exact live direct parent authorizing this delivery.\n * @param childId - durable child session id.\n * @param content - user-role content to deliver.\n * @param options - durable provenance and caller cancellation, which stops the\n *   operation only before inbox acceptance.\n * @returns the accepted message\'s inbox id.\n * @throws when continuation services are unavailable, parent authority is\n *   rejected, or the message was not admitted.\n */',
       },
+      {
+        signature: 'interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void',
+        jsDoc: '/**\n * Interrupt one live continuable child\'s current turn under a human parent\n * address or an exact live ancestor Agent. Fire-and-return: the cancel\n * signal is issued before this returns, but the target may keep running\n * until it observes the signal. Pending inbox work, the Activation, and\n * published descendants are preserved; only a later waking send resumes the\n * parked FIFO queue. An absent target — including a one-shot or unknown id —\n * is an accepted no-op, as is a manager-less composition, which cannot own a\n * live Activation.\n * @param targetSessionId - the durable child session id to interrupt.\n * @param authority - the human parent address or exact live ancestor Agent.\n * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the\n *   live target.\n */',
+      },
       {
         signature: 'async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>',
         jsDoc: '/**\n * Deliver selected content from one live continuable child to its durable\n * direct parent. The child is the authority credential; callers cannot name a\n * recipient. Reporting does not conclude the child\'s turn or Activation.\n * @param child - exact live reporting child.\n * @param content - selected model-facing content.\n * @param options - parent scheduling and pre-acceptance cancellation.\n * @returns the stable identity of the parent-accepted message.\n * @throws when continuation services are unavailable, sender authorization\n *   fails, or the direct parent is not live.\n */',
@@ -2787,6 +2791,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SubagentFollowupOptions',
     declaration: 'export interface SubagentFollowupOptions {\n    readonly source: MessageSource;\n    readonly signal: AbortSignal;\n}',
   },
+  {
+    name: 'SubagentInterruptAuthority',
+    declaration: 'export type SubagentInterruptAuthority = {\n    readonly kind: \'user\';\n    readonly parentSessionId: SessionId;\n} | {\n    readonly kind: \'ancestor\';\n    readonly agent: Agent;\n};',
+  },
   {
     name: 'SubagentListEntry',
     declaration: 'export type SubagentListEntry = {\n    readonly kind: \'child\';\n    readonly id: SessionId;\n    readonly activity: \'running\' | \'inactive\';\n    readonly hasChildren: boolean;\n} & ({\n    readonly mode: \'one-shot\';\n    readonly label?: string;\n} | {\n    readonly mode: \'continuable\';\n    readonly label: string;\n}) | {\n    readonly kind: \'diagnostic\';\n    readonly id: SessionId;\n    readonly reason: \'corrupt\' | \'unsupported\' | \'unavailable\';\n};',
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index cfcae423bc..52236b0f29 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -2013,6 +2013,31 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           return subagentPromptError(request, error, signal)
         }
       },
+
+      // Deliberately no catalog, history, persistence, or parent Agent lookup:
+      // the core primitive alone authorizes the durable address against the
+      // live Activation, which is what keeps a live child interruptible while
+      // its parent Agent is offline. Absent targets are accepted no-ops there.
+      interrupt(request) {
+        const { parentSessionId, childSessionId } = request.payload
+        try {
+          ctx.subagents.interrupt(childSessionId, { kind: 'user', parentSessionId })
+        } catch (error: unknown) {
+          if (error instanceof SubagentError && error.code === 'UNAUTHORIZED') {
+            return Promise.resolve(err(request, {
+              code: 'subagent-unauthorized',
+              message: 'subagent does not belong to this parent',
+              details: { childSessionId },
+            }))
+          }
+          return Promise.resolve(err(request, {
+            code: 'internal',
+            message: 'subagent interrupt failed',
+            details: {},
+          }))
+        }
+        return Promise.resolve(ok(request, { accepted: true as const }))
+      },
     },
 
     workspace: {
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index cb83c5328d..5537a0e382 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -42,7 +42,8 @@ export type {
 } from './sessions.ts'
 export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts'
 export type {
-  SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt, SubagentsApi,
+  SubagentAddress, SubagentCatalog, SubagentInterruptReceipt, SubagentListEntry,
+  SubagentPromptReceipt, SubagentsApi,
 } from './subagents.ts'
 export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
 export type { CommandsApi, CommandDescriptor } from './commands.ts'
diff --git a/packages/host/apiproxy/src/api/rpc-map.ts b/packages/host/apiproxy/src/api/rpc-map.ts
index 9a8750c722..deb963db07 100644
--- a/packages/host/apiproxy/src/api/rpc-map.ts
+++ b/packages/host/apiproxy/src/api/rpc-map.ts
@@ -36,6 +36,7 @@ export interface RpcMethodMap {
   'subagent.list': SubagentsApi['list']
   'subagent.history': SubagentsApi['history']
   'subagent.prompt': SubagentsApi['prompt']
+  'subagent.interrupt': SubagentsApi['interrupt']
   'host.describe': HostApi['describe']
   'host.pickDirectory': HostApi['pickDirectory']
   'host.listDirectory': HostApi['listDirectory']
diff --git a/packages/host/apiproxy/src/api/subagents.schema.ts b/packages/host/apiproxy/src/api/subagents.schema.ts
index 1987d568d3..6ed8bd3263 100644
--- a/packages/host/apiproxy/src/api/subagents.schema.ts
+++ b/packages/host/apiproxy/src/api/subagents.schema.ts
@@ -69,6 +69,18 @@ export const subagentPromptRequestSchema = z.object({
   content: z.array(contentBlockSchema),
 }) as unknown as z.ZodType<RequestPayload<'subagent.prompt'>>
 
+/** subagent.interrupt request payload. */
+export const subagentInterruptRequestSchema = z.object({
+  parentSessionId: sessionIdSchema,
+  childSessionId: sessionIdSchema,
+  mode: z.literal('continuable'),
+}) satisfies z.ZodType<Wire<RequestPayload<'subagent.interrupt'>>>
+
+/** subagent.interrupt response value. */
+export const subagentInterruptValueSchema = z.object({
+  accepted: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'subagent.interrupt'>>>
+
 const messageIdSchema = z.string() as unknown as z.ZodType<MessageId>
 
 /** subagent.prompt response value. */
diff --git a/packages/host/apiproxy/src/api/subagents.ts b/packages/host/apiproxy/src/api/subagents.ts
index 4c251dca7c..8efb452c2e 100644
--- a/packages/host/apiproxy/src/api/subagents.ts
+++ b/packages/host/apiproxy/src/api/subagents.ts
@@ -40,6 +40,11 @@ export interface SubagentPromptReceipt {
   messageId: MessageId
 }
 
+/** Uniform acknowledgement that one interrupt request was admitted. */
+export interface SubagentInterruptReceipt {
+  accepted: true
+}
+
 /** Durable parent/child address that selects subagent transport in the client. */
 export type SubagentAddress =
   & {
@@ -94,4 +99,17 @@ export interface SubagentsApi {
     >,
     signal: AbortSignal,
   ): Promise<RpcResponse<SubagentPromptReceipt>>
+
+  /**
+   * Interrupts a live continuable child's current turn under the address's
+   * durable direct-parent authority, without requiring a live parent Agent,
+   * consulting the catalog, or resuming anything. Fire-and-return: `accepted`
+   * acknowledges the admitted cancel signal, not target quiescence, so the
+   * child may remain visibly running briefly. Queued follow-ups are kept and
+   * parked; an absent, idle, or already-completed target is likewise
+   * `accepted`.
+   */
+  interrupt(
+    request: RpcRequest<Extract<SubagentAddress, { mode: 'continuable' }>>,
+  ): Promise<RpcResponse<SubagentInterruptReceipt>>
 }
diff --git a/packages/host/apiproxy/src/fetch/client.ts b/packages/host/apiproxy/src/fetch/client.ts
index 0f54d76dbc..0ce935809f 100644
--- a/packages/host/apiproxy/src/fetch/client.ts
+++ b/packages/host/apiproxy/src/fetch/client.ts
@@ -58,6 +58,7 @@ import {
 import { llmDiscoverModelsValueSchema, llmModelsValueSchema, llmProvidersValueSchema } from '../api/llm.schema.ts'
 import {
   subagentHistoryValueSchema,
+  subagentInterruptValueSchema,
   subagentListValueSchema,
   subagentPromptValueSchema,
 } from '../api/subagents.schema.ts'
@@ -96,6 +97,7 @@ export interface IApiClient {
     list(payload: RequestPayload<'subagent.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.list'>>>
     history(payload: RequestPayload<'subagent.history'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.history'>>>
     prompt(payload: RequestPayload<'subagent.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.prompt'>>>
+    interrupt(payload: RequestPayload<'subagent.interrupt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'subagent.interrupt'>>>
   }
   host: {
     describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
@@ -171,6 +173,7 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'subagent.list': subagentListValueSchema,
   'subagent.history': subagentHistoryValueSchema,
   'subagent.prompt': subagentPromptValueSchema,
+  'subagent.interrupt': subagentInterruptValueSchema,
   'host.describe': hostDescribeValueSchema,
   'host.pickDirectory': hostPickDirectoryValueSchema,
   'host.listDirectory': hostListDirectoryValueSchema,
@@ -407,6 +410,7 @@ export abstract class AbstractApiClient implements IApiClient {
     list: (payload, signal) => this.callUnary('subagent.list', payload, signal),
     history: (payload, signal) => this.callUnary('subagent.history', payload, signal),
     prompt: (payload, signal) => this.callUnary('subagent.prompt', payload, signal),
+    interrupt: (payload, signal) => this.callUnary('subagent.interrupt', payload, signal),
   }
 
   readonly host: IApiClient['host'] = {
diff --git a/packages/host/apiproxy/src/fetch/handler.ts b/packages/host/apiproxy/src/fetch/handler.ts
index d41b51ad6d..bd3bc3827a 100644
--- a/packages/host/apiproxy/src/fetch/handler.ts
+++ b/packages/host/apiproxy/src/fetch/handler.ts
@@ -60,6 +60,7 @@ import {
 import { llmDiscoverModelsRequestSchema, llmModelsRequestSchema, llmProvidersRequestSchema } from '../api/llm.schema.ts'
 import {
   subagentHistoryRequestSchema,
+  subagentInterruptRequestSchema,
   subagentListRequestSchema,
   subagentPromptRequestSchema,
 } from '../api/subagents.schema.ts'
@@ -95,6 +96,7 @@ const UNARY_ROUTES: UnaryRoutes = {
   'subagent.list': { schema: subagentListRequestSchema, invoke: (api, r, signal) => api.subagents.list(r, signal) },
   'subagent.history': { schema: subagentHistoryRequestSchema, invoke: (api, r, signal) => api.subagents.history(r, signal) },
   'subagent.prompt': { schema: subagentPromptRequestSchema, invoke: (api, r, signal) => api.subagents.prompt(r, signal) },
+  'subagent.interrupt': { schema: subagentInterruptRequestSchema, invoke: (api, r) => api.subagents.interrupt(r) },
   'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
   'host.pickDirectory': { schema: hostPickDirectoryRequestSchema, invoke: (api, r, signal) => api.host.pickDirectory(r, signal) },
   'host.listDirectory': { schema: hostListDirectoryRequestSchema, invoke: (api, r, signal) => api.host.listDirectory(r, signal) },
diff --git a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
index feb9ecb073..62c7e653e0 100644
--- a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
@@ -19,6 +19,7 @@ function bench(options: {
   childStatus?: 'idle' | 'running'
   entries?: object[]
   followupError?: Error
+  interruptError?: Error
   listError?: Error
   /** Persistence forgets the child entirely (the vanished-mid-read race). */
   storedChild?: false
@@ -53,6 +54,12 @@ function bench(options: {
   ) => options.followupError === undefined
     ? Promise.resolve('message-1')
     : Promise.reject(options.followupError))
+  const interrupt = vi.fn((
+    _targetSessionId: SessionId,
+    _authority: { kind: 'user'; parentSessionId: SessionId },
+  ) => {
+    if (options.interruptError !== undefined) throw options.interruptError
+  })
   const childHeader = {
     version: 0, id: CHILD, createdAt: 1, cwd: '/proj', parentSession: options.historyParent ?? PARENT,
   } satisfies SessionHeader
@@ -72,7 +79,7 @@ function bench(options: {
   })
   const ctx = new Context()
   ctx.provide('agents', { get: getAgent })
-  ctx.provide('subagents', { listChildren, followup })
+  ctx.provide('subagents', { listChildren, followup, interrupt })
   ctx.provide('sessions', {
     get: (id: SessionId) => options.liveChild === true && id === CHILD
       ? { id: CHILD, header: childHeader, events: childEvents }
@@ -90,7 +97,7 @@ function bench(options: {
   const api = createApiProxy(ctx, {
     defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp',
   })
-  return { api, getAgent, listChildren, inspect, snapshot, restore, followup, parent }
+  return { api, getAgent, listChildren, inspect, snapshot, restore, followup, interrupt, parent }
 }
 
 describe('subagent gateway', () => {
@@ -309,4 +316,48 @@ describe('subagent gateway', () => {
       error: { code: 'internal', message: 'subagent prompt failed' },
     })
   })
+
+  it('interrupts through the core primitive alone while the parent Agent is offline', async () => {
+    const { api, interrupt, getAgent, listChildren, inspect } = bench({ parentLive: false })
+    const response = await api.subagents.interrupt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable' as const,
+    }))
+    expect(response.rpcId).toBe('subagent-rpc')
+    expect(response.result).toEqual({ ok: true, value: { accepted: true } })
+    expect(interrupt).toHaveBeenCalledExactlyOnceWith(CHILD, { kind: 'user', parentSessionId: PARENT })
+    // No parent-registry, catalog, or history dependency: this is what keeps a
+    // live child interruptible after its parent Agent went offline.
+    expect(getAgent).not.toHaveBeenCalled()
+    expect(listChildren).not.toHaveBeenCalled()
+    expect(inspect).not.toHaveBeenCalled()
+  })
+
+  it('maps interrupt authorization rejection without touching other services', async () => {
+    const { api, listChildren } = bench({
+      interruptError: new SubagentError('secret lineage', 'UNAUTHORIZED'),
+    })
+    const response = await api.subagents.interrupt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable' as const,
+    }))
+    expect(response.result).toEqual({
+      ok: false,
+      error: {
+        code: 'subagent-unauthorized',
+        message: 'subagent does not belong to this parent',
+        details: { childSessionId: CHILD },
+      },
+    })
+    expect(listChildren).not.toHaveBeenCalled()
+  })
+
+  it('hides unexpected interrupt failures behind the internal code', async () => {
+    const { api } = bench({ interruptError: new Error('secret activation state') })
+    const response = await api.subagents.interrupt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable' as const,
+    }))
+    expect(response.result).toEqual({
+      ok: false,
+      error: { code: 'internal', message: 'subagent interrupt failed', details: {} },
+    })
+  })
 })
diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts
index ebd56ee551..476ebf344f 100644
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -63,6 +63,7 @@ function scriptedApi(overrides: {
       list: r => ok(r, { entries: [], parentAvailable: false }),
       history: r => ok(r, { events: [], hasMore: false }),
       prompt: r => ok(r, { messageId: 'message-1' as never }),
+      interrupt: r => ok(r, { accepted: true as const }),
       ...overrides.subagents,
     },
     host: {
@@ -248,6 +249,32 @@ describe('unary round trip', () => {
     }
   })
 
+  it('round-trips subagent.interrupt and rejects a one-shot or incomplete address', async () => {
+    const interrupt = vi.fn((r: RpcRequest<unknown>) => ok(r, { accepted: true as const }))
+    const api = scriptedApi({ subagents: { interrupt } })
+    const c = client(api)
+
+    const accepted = await c.subagents.interrupt({
+      parentSessionId: sid('parent'), childSessionId: sid('child'), mode: 'continuable',
+    })
+    expect(accepted.result).toEqual({ ok: true, value: { accepted: true } })
+    expect(interrupt).toHaveBeenCalledTimes(1)
+
+    // The wire schema owns the mode fence: a one-shot address never reaches the impl.
+    const oneShot = await c.subagents.interrupt({
+      parentSessionId: sid('parent'), childSessionId: sid('child'), mode: 'one-shot',
+    } as never)
+    expect(oneShot.result.ok).toBe(false)
+    if (!oneShot.result.ok) expect(oneShot.result.error.code).toBe('bad-request')
+
+    const incomplete = await c.subagents.interrupt({
+      parentSessionId: sid('parent'), mode: 'continuable',
+    } as never)
+    expect(incomplete.result.ok).toBe(false)
+    if (!incomplete.result.ok) expect(incomplete.result.error.code).toBe('bad-request')
+    expect(interrupt).toHaveBeenCalledTimes(1)
+  })
+
   it('rejects a method/path mismatch as bad-request', async () => {
     const handler = toFetchHandler(scriptedApi())
     const body = { type: 'client-request', rpcId: 'r1', method: 'session.create', payload: {} }
diff --git a/packages/host/apiproxy/tests/fetch-carrier.spec.ts b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
index 6481d75837..83ada22644 100644
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -128,6 +128,9 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
           result: { ok: true, value: { messageId: 'message-1' as never } },
         }
       },
+      async interrupt(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
+      },
     },
     host: {
       async describe(request) {
@@ -433,6 +436,11 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
       mode: 'continuable',
       content: [],
     })).result).toEqual({ ok: true, value: { messageId: 'message-1' } })
+    expect((await c.subagents.interrupt({
+      parentSessionId: 'parent' as never,
+      childSessionId: 'child' as never,
+      mode: 'continuable',
+    })).result).toEqual({ ok: true, value: { accepted: true } })
   })
 
   it('keeps caller and connection aborts on command.execute', async () => {
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index f5ceedc743..250fd1a078 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: 9d2e38c8730f7b7f26e690aa878a4466fa7c2829
-README.zh.md: 341c18617af4d040ec44814fac1ec4502d9b8902
+README.md: 7de3a5563b274e925fba931a6d5de17e68cc397c
+README.zh.md: 6067555544ec0c32729beb2b4e3f773e31b747a1
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 9d2e38c873..7de3a5563b 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -18,6 +18,7 @@ The [subagent family overview](../README.md) maps implementations and model-faci
 | `start(name, request)` | Validate an ordinary caller request, resolve its detached `one-shot` descriptor, then await the provider until a real one-shot child is published. Fulfillment returns a holder-owned `SubagentRun`; rejection means the provider has already cleaned every unpublished startup resource, while post-publication turn or infrastructure faults settle through the run. Continuable children never enter through this operation. |
 | `startContinuable(spec)` | Establish one durable continuable child and deliver its initial prompt. Resolves with `{ childId, messageId }` when the child's inbox accepts that prompt, without waiting for the turn to start or for the message to reach the Session log; any earlier failure rejects with no ids and rolls the child back entirely. Requires `ctx.agents`, session persistence, and a provider with the `prepareContinuable` capability. |
 | `followup(parent, childId, content, { source, signal })` | Deliver one later message from the exact live direct parent as the child's next FIFO turn, matching `Agent.followup()` terminology, and return the accepted `MessageId`. A resident child's inbox accepts it directly (waking a waiting Activation); an absent one cold-resumes from its persisted Session. Requires `ctx.agents`; cold resume also requires session persistence. |
+| `interrupt(targetSessionId, authority)` | Interrupt one live continuable child's current turn under a human durable parent address (`{ kind: 'user', parentSessionId }`) or an exact live ancestor Agent (`{ kind: 'ancestor', agent }`). Admission is synchronous and the effect asynchronous: it issues `Agent.cancel(cause, { keepInbox: true })` and returns without waiting for the target to observe the signal. Pending inbox work, the Activation, and published descendants are preserved; only a later waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already-settled id — and a manager-less composition are accepted no-ops; a wrong parent address or a stale, self-targeting, or non-ancestor caller rejects with `UNAUTHORIZED`. |
 | `reportFrom(child, content, { delivery, signal })` | Deliver one selected message from the exact live continuable child to its exact live direct parent and return the accepted stable `MessageId`. Quiet delivery injects context; waking delivery submits one later parent turn. |
 | `registerContinuableSetup(contribution)` | Compose an optional deployment capability into each continuable child's unpublished scope, with immediate revocation from resident children. |
 | `drainContinuableDescendants(parents)` | Close admission below exact live host-owned parent Agents, stop only their visible continuable descendants, await materializations admitted below those roots through publication or rollback, then release the selected forests child-first. The cutoff lasts until each exact parent leaves the registry; unrelated parent forests and manager-wide admission remain live. |
@@ -76,7 +77,7 @@ Run events are scoped to the delegating parent. Every listener is independently
 
 Provider additions and removals also emit `subagent/provider-added` and `subagent/provider-removed`. Consumers such as the model-facing tool use those events because Cordis may load sibling plugins concurrently; configuration order does not prove registration order.
 
-Continuable children do not create `SubagentRun` or Tasks. The continuation manager directly owns one process-local Activation and retained `AgentHandle` per resident child Session, uses the Agent inbox as the only FIFO, and cold-resumes from the durable descriptor. Exact live direct-parent identity authorizes parent-to-child delivery. Exact live child identity authorizes reports; the manager derives the recipient from durable `parentSession`, and `MessageSource` remains provenance rather than authority.
+Continuable children do not create `SubagentRun` or Tasks. The continuation manager directly owns one process-local Activation and retained `AgentHandle` per resident child Session, uses the Agent inbox as the only FIFO, and cold-resumes from the durable descriptor. Exact live direct-parent identity authorizes parent-to-child delivery. Exact live child identity authorizes reports; the manager derives the recipient from durable `parentSession`, and `MessageSource` remains provenance rather than authority. Interrupt authority is deliberately wider than delivery authority: a human presents the durable direct-parent address so a live child stays stoppable while its parent Agent is offline, and any exact live ancestor recorded in the Activation's materialization lineage may stop its descendant, because stopping a turn is idempotent and delivers no content.
 
 When `ctx.sessionProjections` is available, the service registers two projection units. `subagentTiming` resets at each descriptor so a fork seed's ancestor work cannot enter the child's total, then accumulates `turn/start` → `turn/end` active time and retains same-cut `active.since` and `active.through` bounds for an open turn; while that turn remains open, `active.through` follows the latest folded event, giving an inactive consumer a conservative crash bound without mixing in newer session metadata. `subagent` folds the durable identity — mode plus creation label — from `subagent/descriptor` events with the same last-wins reset discipline, so a fork seed's ancestor descriptor stands only until the child's own overrides it; a malformed or unrecognized-version payload folds to the serializable `null` sentinel — indistinguishable from a log with no descriptor, and surviving every JSON push frame so a consumer replaces a stale identity instead of keeping it — and never throws.
 
@@ -84,7 +85,7 @@ When `ctx.sessionProjections` is available, the service registers two projection
 
 ## Collection model
 
-The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task, no result promise, and no public subagent cancellation — a caller sends later work with the `send_message` follow-up tool, and the durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and maps service activity to its existing `running`/`complete` vocabulary. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
+The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task or result promise — a caller sends later work with the `send_message` follow-up tool, while `interrupt()` stops only the current turn without disposing the child. The durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and maps service activity to its existing `running`/`complete` vocabulary. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
 
 Continuable Activations await a best-effort final session flush without treating listener participation as durability confirmation. One-shot runs retain best-effort session checkpointing, so a completed one-shot child is discoverable after disposal only when its session actually reached persistence; the service does not invent a catalog entry from Task history when that checkpoint is absent.
 
@@ -99,7 +100,7 @@ No direct invalidation; the named consumers own any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **ACP children remain one-shot and are not trace-enumerable** — an ACP run has no local child session in the parent's session corpus. An ACP `prepareContinuable` requires persisting the remote session id in provider-specific descriptor data and a per-child continuation advertisement, since ACP `loadSession` support is negotiated per child rather than established by the method's presence. Remote providers also require a separate Activation ownership contract with equivalent authenticated control and child-first quiescence before they support continuable children.
-- **No host-user continuation** — `followup()` requires the exact live direct parent. A future host adapter needs a concrete authenticated interaction before the seam gains a separate user capability.
+- **No host-user continuation** — `followup()` requires the exact live direct parent. Only `interrupt()` accepts a durable parent-address user authority, because stopping a turn is idempotent and delivers no content; a future host adapter needs a concrete authenticated interaction before the seam gains a user delivery capability.
 - **No current-turn steering** — continuable messages and waking reports enqueue later turns; neither redirects an open turn.
 - **Process-local residency** — the Activation inbox and ownership graph do not coordinate two harness processes; concurrent access to one persistence store still requires a durable mailbox and cross-process lease protocol.
 - **No replay of accepted-but-unlogged messages** — only messages written to the child Session log are reconstructable with their admitted provenance. A crash may lose an accepted initial prompt or follow-up that never reached the log; a later authorized message can cold-resume the child, but the lost message is not replayed automatically.
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 341c18617a..6067555544 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -18,6 +18,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `start(name, request)` | 校验普通调用方请求，解析其分离的 `one-shot` 描述符，然后等待提供方，直到真实的一次性子 agent 发布。兑现时返回由持有方拥有的 `SubagentRun`；拒绝表示提供方已清理所有未发布的启动资源，而发布后的轮次或基础设施故障会通过该 run 结算。可继续子 agent 绝不通过此操作进入。 |
 | `startContinuable(spec)` | 建立一个持久化可继续子 agent，并投递其初始提示词。子 agent 的 inbox 接受该提示词时，兑现为 `{ childId, messageId }`，无需等待轮次开始或消息写入 Session 日志；此前任何失败都会以无 id 拒绝，并完全回滚该子 agent。要求 `ctx.agents`、会话持久化以及具备 `prepareContinuable` 能力的提供方。 |
 | `followup(parent, childId, content, { source, signal })` | 将来自确切在线直接父级的一条后续消息作为子 agent 的下一个 FIFO 轮次投递，术语与 `Agent.followup()` 一致，并返回被接受的 `MessageId`。驻留中的子 agent 由其 inbox 直接接受（唤醒处于 waiting 的 Activation）；不驻留的则从其持久化 Session 冷恢复。要求 `ctx.agents`；冷恢复还要求会话持久化。 |
+| `interrupt(targetSessionId, authority)` | 以人类持久化 parent 地址（`{ kind: 'user', parentSessionId }`）或确切在线 ancestor Agent（`{ kind: 'ancestor', agent }`）为授权，中断一个在线可继续 child 的当前轮次。准入是同步的、生效是异步的：它发出 `Agent.cancel(cause, { keepInbox: true })` 后立即返回，不等待目标观察到信号。待处理的 inbox 工作、Activation 与已发布的后代均保持不变；只有之后的一次唤醒发送才会恢复被暂停的 FIFO 队列。目标不存在——未知、一次性或已结算的 id——以及未绑定管理器的组合都是被接受的 no-op；错误的 parent 地址，或过期、指向自身、非 ancestor 的调用方会以 `UNAUTHORIZED` 拒绝。 |
 | `reportFrom(child, content, { delivery, signal })` | 从确切在线可继续 child 向其确切在线直接 parent 投递一条选中消息，并返回已接受的稳定 `MessageId`。静默投递会注入上下文；唤醒投递会提交一个后续 parent 轮次。 |
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
@@ -76,7 +77,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 提供方新增和移除还会发出 `subagent/provider-added` 与 `subagent/provider-removed`。面向模型的工具等消费方使用这些事件，因为 Cordis 可能并发加载同级插件；配置顺序不能证明注册顺序。
 
-可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。
+可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代——因为停止一个轮次是幂等的，且不投递任何内容。
 
 当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置纪律从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，让消费方以之替换掉手中过时的身份而非永久滞留——绝不抛错。
 
@@ -84,7 +85,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 收集模型
 
-面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、没有结果 promise，也没有公开的子 agent 取消操作——调用方通过 `send_message` 后续操作工具发送后续工作，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，并将服务活动状态映射到现有的 `running`／`complete` 词汇。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
+面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task 或结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，而 `interrupt()` 只停止当前轮次，不 dispose 子 agent。持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，并将服务活动状态映射到现有的 `running`／`complete` 词汇。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
 
 可继续 Activation 会等待 best-effort 的最终会话 flush，但不会把 listener 参与视为持久性确认。一次性运行保留尽力执行的会话检查点，因此已完成的一次性 child 只有在其会话确实进入持久化存储时，才可在 dispose 后继续被发现；如果该检查点缺失，服务不会根据 Task 历史虚构目录条目。
 
@@ -99,7 +100,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 ## 已知限制与暂缓事项
 
 - **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，以及逐子 agent 的继续执行能力声明，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权契约，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
-- **无 host-user 继续执行**：`followup()` 要求确切在线直接父级。未来 host 适配器需要具体的经认证交互，才能让该 seam 获得单独的用户能力。
+- **无 host-user 继续执行**：`followup()` 要求确切在线直接父级。只有 `interrupt()` 接受持久化 parent 地址形式的用户授权，因为停止一个轮次是幂等的且不投递任何内容；未来 host 适配器需要具体的经认证交互，才能让该 seam 获得用户投递能力。
 - **不对当前轮次进行 steering**：可继续消息和唤醒式 report 会排入后续轮次，均不会重定向正在进行的轮次。
 - **驻留仅限进程内**：Activation inbox 与所有权图不会在两个 harness 进程之间协调；对单个持久化存储的并发访问仍然需要持久化邮箱和跨进程租约协议。
 - **不重放已接受但未记录的消息**：只有写入子 agent Session 日志的消息才能连同其被接受时的来源一起重建。崩溃可能丢失从未写入日志、已被接受的初始提示词或后续消息；此后一条经授权的消息可以冷恢复该子 agent，但丢失的消息不会自动重放。
diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts
index 212536e713..ebac0a1296 100644
--- a/packages/subagent/subagent/src/continuation.ts
+++ b/packages/subagent/subagent/src/continuation.ts
@@ -103,6 +103,15 @@ export interface ContinuableStart {
   readonly messageId: MessageId
 }
 
+/**
+ * Authority under which one interrupt request is admitted. `user` carries the
+ * durable direct-parent address a human client presented; `ancestor` carries
+ * the exact live Agent object whose recorded lineage must contain the caller.
+ */
+export type SubagentInterruptAuthority =
+  | { readonly kind: 'user'; readonly parentSessionId: SessionId }
+  | { readonly kind: 'ancestor'; readonly agent: Agent }
+
 /** Options for following up with one continuable child. */
 export interface SubagentFollowupOptions {
   /** Durable attribution retained on the delivered message; it grants no authority. */
@@ -412,6 +421,68 @@ export class SubagentContinuationManager {
     }
   }
 
+  /**
+   * Interrupt one live continuable child's current turn. Admission is
+   * synchronous and the effect is asynchronous: this authorizes the caller,
+   * requests `Agent.cancel(cause, { keepInbox: true })` on the target, and
+   * returns without waiting for the target to observe the signal or reach
+   * quiescence. The Activation, its handle, accepted pending inbox work, and
+   * already-published descendants are untouched; the parked queue resumes only
+   * on a later waking send.
+   *
+   * An absent target is an accepted no-op, which uniformly covers natural
+   * completion races, repeated requests, one-shot ids, and unknown ids without
+   * consulting the durable catalog. A target whose disposal transaction is
+   * already open is likewise an accepted no-op after authorization.
+   * @param targetSessionId - the durable child session id to interrupt.
+   * @param authority - the human parent address or exact live ancestor Agent.
+   * @throws {SubagentError} `UNAUTHORIZED` when the presented authority does
+   *   not own the live target: a stale or self-targeting ancestor caller, a
+   *   parent address that is not the live target's durable direct parent, or
+   *   an ancestor outside the target's recorded live lineage.
+   */
+  interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void {
+    if (authority.kind === 'ancestor') {
+      const caller = authority.agent
+      // A stale caller is rejected even when the target is absent, so a
+      // replaced same-id Agent can never probe this manager's state.
+      if (this.ctx.agents.get(caller.id) !== caller) {
+        throw new SubagentError(
+          `interrupting "${targetSessionId}" requires the exact live ancestor agent`,
+          'UNAUTHORIZED',
+        )
+      }
+      if (caller.id === targetSessionId) {
+        throw new SubagentError(
+          `agent "${caller.id}" cannot interrupt itself`,
+          'UNAUTHORIZED',
+        )
+      }
+    }
+    const activation = this.activations.get(targetSessionId)
+    if (activation === undefined) return
+    if (authority.kind === 'user') {
+      if (activation.handle.agent.session.header.parentSession !== authority.parentSessionId) {
+        throw new SubagentError(
+          `subagent "${targetSessionId}" belongs to another parent session`,
+          'UNAUTHORIZED',
+        )
+      }
+    } else if (!activation.ancestry.has(authority.agent)) {
+      throw new SubagentError(
+        `subagent "${targetSessionId}" is not a live descendant of agent "${authority.agent.id}"`,
+        'UNAUTHORIZED',
+      )
+    }
+    // Disposal already stopped the target with a whole-Activation teardown;
+    // a second cancel would be a redundant signal on a closing handle.
+    if (activation.disposal !== undefined) return
+    activation.handle.agent.cancel(
+      authority.kind === 'user' ? { kind: 'user' } : { kind: 'parent' },
+      { keepInbox: true },
+    )
+  }
+
   /**
    * Deliver explicitly selected content from one resident continuable child to
    * its durable direct parent. Sender authorization, parent resolution, and
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 5bcd53d6a5..e179bfd8b4 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -58,6 +58,7 @@ import type {
   ContinuableStart,
   ContinuableStartSpec,
   SubagentFollowupOptions,
+  SubagentInterruptAuthority,
   SubagentReportOptions,
 } from './continuation.ts'
 import SubagentActivationSetupRegistry from './activation-setup-registry.ts'
@@ -111,6 +112,7 @@ export type {
   ContinuableStartSpec,
   CoordinatorMessageSource,
   SubagentFollowupOptions,
+  SubagentInterruptAuthority,
   SubagentReportDelivery,
   SubagentReportMessageSource,
   SubagentReportOptions,
@@ -231,6 +233,24 @@ export class SubagentService extends Service {
     return this.requireContinuations().followup(parent, childId, content, options)
   }
 
+  /**
+   * Interrupt one live continuable child's current turn under a human parent
+   * address or an exact live ancestor Agent. Fire-and-return: the cancel
+   * signal is issued before this returns, but the target may keep running
+   * until it observes the signal. Pending inbox work, the Activation, and
+   * published descendants are preserved; only a later waking send resumes the
+   * parked FIFO queue. An absent target — including a one-shot or unknown id —
+   * is an accepted no-op, as is a manager-less composition, which cannot own a
+   * live Activation.
+   * @param targetSessionId - the durable child session id to interrupt.
+   * @param authority - the human parent address or exact live ancestor Agent.
+   * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
+   *   live target.
+   */
+  interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void {
+    this.continuations?.interrupt(targetSessionId, authority)
+  }
+
   /**
    * Deliver selected content from one live continuable child to its durable
    * direct parent. The child is the authority credential; callers cannot name a
diff --git a/packages/subagent/subagent/tests/continuation.spec.ts b/packages/subagent/subagent/tests/continuation.spec.ts
index dca06add38..9370676f76 100644
--- a/packages/subagent/subagent/tests/continuation.spec.ts
+++ b/packages/subagent/subagent/tests/continuation.spec.ts
@@ -1717,3 +1717,223 @@ describe('continuable errors', () => {
     expect(ctx.agents.get(started.childId)).toBeUndefined()
   })
 })
+
+describe('SubagentService.interrupt', () => {
+  it('aborts the current turn durably, parks accepted follow-ups, and resumes them only on a waking send', async () => {
+    const releaseFirst = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('first'), gate: releaseFirst.promise },
+      { chunks: textResponse('second') },
+      { chunks: textResponse('third') },
+      { chunks: textResponse('fourth') },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    await followup(ctx, parent, started.childId, message('parked B'))
+    await followup(ctx, parent, started.childId, message('parked C'))
+    const cancelSpy = vi.spyOn(child, 'cancel')
+
+    ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id })
+
+    expect(cancelSpy).toHaveBeenCalledTimes(1)
+    expect(cancelSpy).toHaveBeenCalledWith({ kind: 'user' }, { keepInbox: true })
+    // Cancellation is cooperative: the held model call observes it on release.
+    releaseFirst.resolve(undefined)
+    await child.whenIdle()
+    // Parked, not resumed: no second model request follows the abort, the
+    // accepted follow-ups stay pending, and the same Activation stays resident.
+    expect(adapter.requests).toHaveLength(1)
+    expect(child.inbox.nextTurn).toHaveLength(2)
+    expect(child.status).toBe('idle')
+    expect(ctx.agents.get(started.childId)).toBe(child)
+
+    // Only an explicit waking send restores the driver; the parked items then
+    // run before it in the existing FIFO order.
+    await followup(ctx, parent, started.childId, message('waking D'))
+    await waitNoActivation(ctx, started.childId)
+    const loaded = await ctx.sessionPersistence.load(started.childId)
+    expect(userTexts(loaded.events)).toEqual(['child task', 'parked B', 'parked C', 'waking D'])
+    const turnEnds = loaded.events
+      .filter(event => event.type === 'turn/end')
+      .map(event => (event).data.reason.kind)
+    expect(turnEnds).toEqual(['aborted', 'completed', 'completed', 'completed'])
+  })
+
+  it('interrupts only the target while its resident descendant keeps running', async () => {
+    const releaseChild = Promise.withResolvers<undefined>()
+    const releaseGrandchild = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child'), gate: releaseChild.promise },
+      { chunks: textResponse('grandchild'), gate: releaseGrandchild.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const grandchild = await ctx.subagents.startContinuable(startSpec(child))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    const grandchildAgent = ctx.agents.get(grandchild.childId)!
+    const childCancel = vi.spyOn(child, 'cancel')
+    const grandchildCancel = vi.spyOn(grandchildAgent, 'cancel')
+
+    ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id })
+
+    expect(childCancel).toHaveBeenCalledTimes(1)
+    releaseChild.resolve(undefined)
+    await child.whenIdle()
+    // The target parks as a waiting owner; the published descendant was never
+    // signalled and keeps its own turn open.
+    expect(grandchildCancel).not.toHaveBeenCalled()
+    expect(ctx.agents.get(started.childId)).toBe(child)
+    expect(ctx.agents.get(grandchild.childId)).toBe(grandchildAgent)
+
+    releaseGrandchild.resolve(undefined)
+    await waitNoActivation(ctx, grandchild.childId)
+    await waitNoActivation(ctx, started.childId)
+    const loaded = await ctx.sessionPersistence.load(grandchild.childId)
+    const turnEnds = loaded.events
+      .filter(event => event.type === 'turn/end')
+      .map(event => (event).data.reason.kind)
+    expect(turnEnds).toEqual(['completed'])
+  })
+
+  it('authorizes the human address against the live target\'s durable direct parent', async () => {
+    const hold = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: hold.promise }])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const cancelSpy = vi.spyOn(child, 'cancel')
+
+    expect(() => { ctx.subagents.interrupt(started.childId, {
+      kind: 'user',
+      parentSessionId: SessionId('stranger'),
+    }) }).toThrow(/belongs to another parent session/)
+    expect(cancelSpy).not.toHaveBeenCalled()
+
+    ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id })
+    expect(cancelSpy).toHaveBeenCalledWith({ kind: 'user' }, { keepInbox: true })
+    hold.resolve(undefined)
+    await waitNoActivation(ctx, started.childId)
+  })
+
+  it('lets a deep exact live ancestor interrupt its descendant with the parent cause', async () => {
+    const releaseChild = Promise.withResolvers<undefined>()
+    const releaseGrandchild = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child'), gate: releaseChild.promise },
+      { chunks: textResponse('grandchild'), gate: releaseGrandchild.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const grandchild = await ctx.subagents.startContinuable(startSpec(child))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    const grandchildAgent = ctx.agents.get(grandchild.childId)!
+    const childCancel = vi.spyOn(child, 'cancel')
+    const grandchildCancel = vi.spyOn(grandchildAgent, 'cancel')
+
+    // Deep ancestor: the top-level parent interrupts the grandchild.
+    ctx.subagents.interrupt(grandchild.childId, { kind: 'ancestor', agent: parent })
+    expect(grandchildCancel).toHaveBeenCalledWith({ kind: 'parent' }, { keepInbox: true })
+    // Direct ancestor: the same authority kind covers the immediate parent.
+    ctx.subagents.interrupt(started.childId, { kind: 'ancestor', agent: parent })
+    expect(childCancel).toHaveBeenCalledWith({ kind: 'parent' }, { keepInbox: true })
+
+    releaseChild.resolve(undefined)
+    releaseGrandchild.resolve(undefined)
+    await waitNoActivation(ctx, grandchild.childId)
+    await waitNoActivation(ctx, started.childId)
+  })
+
+  it('rejects self, sibling, stale, and unrelated ancestor callers without touching the target', async () => {
+    const releaseA = Promise.withResolvers<undefined>()
+    const releaseB = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('a'), gate: releaseA.promise },
+      { chunks: textResponse('b'), gate: releaseB.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const targetStart = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const target = ctx.agents.get(targetStart.childId)!
+    const siblingStart = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    const sibling = ctx.agents.get(siblingStart.childId)!
+    const stranger = ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
+    const stale = { ...parent, id: parent.id } as unknown as Agent
+    const cancelSpy = vi.spyOn(target, 'cancel')
+
+    expect(() => { ctx.subagents.interrupt(targetStart.childId, { kind: 'ancestor', agent: target }) })
+      .toThrow(/cannot interrupt itself/)
+    expect(() => { ctx.subagents.interrupt(targetStart.childId, { kind: 'ancestor', agent: sibling }) })
+      .toThrow(/not a live descendant/)
+    expect(() => { ctx.subagents.interrupt(targetStart.childId, { kind: 'ancestor', agent: stranger }) })
+      .toThrow(/not a live descendant/)
+    expect(() => { ctx.subagents.interrupt(targetStart.childId, { kind: 'ancestor', agent: stale }) })
+      .toThrow(/exact live ancestor/)
+    // A stale caller is rejected before target lookup, even for an absent id.
+    expect(() => { ctx.subagents.interrupt(SessionId('missing'), { kind: 'ancestor', agent: stale }) })
+      .toThrow(/exact live ancestor/)
+    expect(cancelSpy).not.toHaveBeenCalled()
+
+    releaseA.resolve(undefined)
+    releaseB.resolve(undefined)
+    await waitNoActivation(ctx, targetStart.childId)
+    await waitNoActivation(ctx, siblingStart.childId)
+  })
+
+  it('accepts absent and one-shot ids as no-ops without touching the one-shot Agent', async () => {
+    const { ctx, parent } = await setup([textResponse('one shot')])
+    ctx.subagents.interrupt(SessionId('missing'), { kind: 'user', parentSessionId: parent.id })
+    ctx.subagents.interrupt(SessionId('missing'), { kind: 'ancestor', agent: parent })
+
+    const run = await ctx.subagents.start('spawn', {
+      label: 'one-shot work',
+      prompt: message('one-shot work'),
+      parent,
+      signal: testSignal,
+    })
+    const oneShot = run.localAgent!
+    const cancelSpy = vi.spyOn(oneShot, 'cancel')
+    ctx.subagents.interrupt(run.id, { kind: 'user', parentSessionId: parent.id })
+    ctx.subagents.interrupt(run.id, { kind: 'ancestor', agent: parent })
+    expect(cancelSpy).not.toHaveBeenCalled()
+    await run.result
+    await run.dispose()
+  })
+
+  it('accepts an interrupt after natural completion', async () => {
+    const { ctx, parent } = await setup([textResponse('done')])
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await waitNoActivation(ctx, started.childId)
+    ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id })
+    ctx.subagents.interrupt(started.childId, { kind: 'ancestor', agent: parent })
+  })
+
+  it('accepts an interrupt that lost the race with disposal without signalling twice', async () => {
+    const hold = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([{ chunks: textResponse('working'), gate: hold.promise }])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const cancelSpy = vi.spyOn(child, 'cancel')
+
+    // Scoped teardown opens the disposal transaction synchronously and issues
+    // its own whole-Activation cancel before this call returns.
+    const drained = ctx.subagents.drainContinuableDescendants([parent])
+    expect(cancelSpy).toHaveBeenCalledTimes(1)
+
+    // Interrupt after the cutoff: accepted no-op, no second signal, no waiting.
+    ctx.subagents.interrupt(started.childId, { kind: 'user', parentSessionId: parent.id })
+    expect(cancelSpy).toHaveBeenCalledTimes(1)
+
+    hold.resolve(undefined)
+    await drained
+  })
+})
diff --git a/packages/subagent/subagent/tests/service.spec.ts b/packages/subagent/subagent/tests/service.spec.ts
index 8b90719227..a50696cf2a 100644
--- a/packages/subagent/subagent/tests/service.spec.ts
+++ b/packages/subagent/subagent/tests/service.spec.ts
@@ -133,6 +133,16 @@ describe('SubagentService', () => {
     await expect(subagents.drainContinuableDescendants([])).resolves.toBeUndefined()
   })
 
+  it('treats interrupt as an accepted no-op when no manager was bound', async () => {
+    const { subagents } = await service()
+    // Without a continuation manager no live Activation can exist, so there is
+    // nothing to stop and nothing to authorize against.
+    expect(() => { subagents.interrupt(SessionId('child'), {
+      kind: 'user',
+      parentSessionId: SessionId('parent-1'),
+    }) }).not.toThrow()
+  })
+
   it('rejects continuable operations when their runtime services are absent', async () => {
     const { subagents } = await service()
     await expect(subagents.startContinuable({
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 54581a8605..c8ddb487ef 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -173,6 +173,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ContinuableStartSpec: 'subagent.md',
   CoordinatorMessageSource: 'subagent.md',
   SubagentFollowupOptions: 'subagent.md',
+  SubagentInterruptAuthority: 'subagent.md',
   SubagentListEntry: 'subagent.md',
   SubagentProvider: 'subagent.md',
   SubagentReportDelivery: 'subagent.md',

From 82019134b1c3ff0cdcb7b4edf7d1f6a031b4ad7c Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 12:09:09 +0800
Subject: [PATCH 273/516] test(web): verify subagent.interrupt over the real
 composition

A browserless keyless-replay e2e boots the shipped web composition, holds
a continuable child's turn open with a replay hang entry, queues a
follow-up and interrupts over plain HTTP, and proves from the real
session state that the turn aborted, the follow-up parked without a new
turn, and a waking send resumed the preserved FIFO order.

Refs #1535
---
 apps/web/tests/subagent-interrupt.e2e.ts | 176 +++++++++++++++++++++++
 apps/web/tsconfig.json                   |   1 +
 tsconfig.host.json                       |   1 +
 3 files changed, 178 insertions(+)
 create mode 100644 apps/web/tests/subagent-interrupt.e2e.ts

diff --git a/apps/web/tests/subagent-interrupt.e2e.ts b/apps/web/tests/subagent-interrupt.e2e.ts
new file mode 100644
index 0000000000..e1e35e7981
--- /dev/null
+++ b/apps/web/tests/subagent-interrupt.e2e.ts
@@ -0,0 +1,176 @@
+// Web e2e scenario (browserless): the subagent.interrupt RPC against the real
+// composition. A live continuable child holds its model turn open through a
+// replay hang entry; plain HTTP queues a follow-up, interrupts the turn, and
+// proves from the real session state that the turn aborted, the follow-up
+// parked without auto-starting a new turn, and a later waking send resumed the
+// preserved FIFO order. No browser: the RPC surface is the product surface
+// under test, and PR-stacked UI coverage owns the composer interaction.
+import { existsSync } from 'node:fs'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { SessionId as sessionId, type SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-agent'
+import { launchWebScaffold, webSnapshotMode, type WebScaffold } from './scaffold.ts'
+
+const MODE = webSnapshotMode()
+const INITIAL = 'Explain event sourcing in one sentence.'
+const FOLLOWUP = 'Now give the same explanation to a human reader.'
+const WAKING = 'And add one concrete example.'
+
+type RpcResult<T> = { ok: true; value: T } | { ok: false; error: { code: string; message: string } }
+
+/** POST one unary RPC through the real HTTP carrier and unwrap its result. */
+async function rpc<T>(baseUrl: string, method: string, payload: unknown): Promise<RpcResult<T>> {
+  const response = await fetch(`${baseUrl}/api/${method}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      type: 'client-request',
+      rpcId: `interrupt-e2e-${method}-${crypto.randomUUID()}`,
+      method,
+      payload,
+    }),
+  })
+  if (!response.ok) throw new Error(`${method} failed over HTTP ${response.status}: ${await response.text()}`)
+  return (await response.json() as { result: RpcResult<T> }).result
+}
+
+/** Poll a synchronous condition (hook-safe; expect.poll is test-body only). */
+async function waitFor(predicate: () => boolean, what: string, timeoutMs = 30_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error(`timed out waiting for ${what}`)
+    await new Promise<void>(resolve => setTimeout(resolve, 10))
+  }
+}
+
+/** One text-only scripted model completion (no tool calls: real tools are mounted). */
+function textCompletion(text: string): object {
+  return {
+    kind: 'chunks',
+    chunks: [
+      { type: 'block-start', index: 0, blockType: 'text' },
+      { type: 'text-delta', index: 0, text },
+      { type: 'block-end', index: 0, block: { type: 'text', text } },
+      { type: 'usage', usage: { inputTokens: 20, outputTokens: 8 } },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ],
+  }
+}
+
+describe.skipIf(MODE === 'record')('web e2e: subagent.interrupt over the real composition', () => {
+  let scaffold: WebScaffold
+  let sidecarRoot: string
+  let readyFile: string
+  let parentId: SessionId
+  let childId: SessionId
+
+  beforeAll(async () => {
+    sidecarRoot = await mkdtemp(join(tmpdir(), 'dsh-web-subagent-interrupt-'))
+    readyFile = join(sidecarRoot, 'hang-ready')
+    // Whole-script replacement: the child's three model calls are the hang
+    // (turn 1, interrupted), the parked follow-up's turn, and the waking turn.
+    // The parent never runs a turn, so the child claims this primary script.
+    await writeFile(join(sidecarRoot, 'replay.override.json'), JSON.stringify([
+      { kind: 'hang', readyFile },
+      textCompletion('resumed response one'),
+      textCompletion('resumed response two'),
+    ]))
+    // Header-only primary fixture: the bare-array override replaces the
+    // derived script entirely; the path only anchors replay installation.
+    await writeFile(
+      join(sidecarRoot, 'session.jsonl'),
+      '{"type":"session","version":0,"id":"primary","createdAt":0}\n',
+    )
+    scaffold = await launchWebScaffold({
+      replayFixture: join(sidecarRoot, 'session.jsonl'),
+      replayOverride: join(sidecarRoot, 'replay.override.json'),
+    })
+
+    // A live parent Agent through the real API; no workspace or browser.
+    const created = await rpc<{ sessionId: string }>(scaffold.baseUrl, 'session.create', {
+      cwd: scaffold.workspaceCwd,
+    })
+    if (!created.ok) throw new Error(`session.create failed: ${created.error.code}`)
+    parentId = sessionId(created.value.sessionId)
+    const parent = scaffold.ctx.agents.get(parentId)
+    if (parent === undefined) throw new Error('created parent session did not publish a live Agent')
+
+    const started = await scaffold.ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'event-sourcing researcher',
+      signal: new AbortController().signal,
+      request: { prompt: [{ type: 'text', text: INITIAL }], parent },
+    })
+    childId = started.childId
+    // The hang entry writes readyFile after its prefix chunks, immediately
+    // before waiting for cancellation: the deterministic "turn is open" gate.
+    await waitFor(() => existsSync(readyFile), 'the held child turn to open')
+  }, 120_000)
+
+  afterAll(async () => {
+    const failures: unknown[] = []
+    await scaffold?.close().catch((error: unknown) => failures.push(error))
+    await rm(sidecarRoot, { recursive: true, force: true }).catch((error: unknown) => failures.push(error))
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, 'subagent interrupt teardown failed')
+  })
+
+  it('parks a queued follow-up on interrupt and resumes it FIFO on a waking send', async () => {
+    // Queue the follow-up while the turn is still open, then interrupt.
+    const queued = await rpc<{ messageId: string }>(scaffold.baseUrl, 'subagent.prompt', {
+      parentSessionId: parentId,
+      childSessionId: childId,
+      mode: 'continuable',
+      content: [{ type: 'text', text: FOLLOWUP }],
+    })
+    expect(queued).toMatchObject({ ok: true })
+
+    const settled = scaffold.whenTurnSettled()
+    const interrupted = await rpc<{ accepted: true }>(scaffold.baseUrl, 'subagent.interrupt', {
+      parentSessionId: parentId,
+      childSessionId: childId,
+      mode: 'continuable',
+    })
+    expect(interrupted).toMatchObject({ ok: true, value: { accepted: true } })
+    // accepted acknowledges the admitted cancel, not quiescence: wait for the
+    // aborted turn/end (the composition's first turn/end) before asserting.
+    expect(await settled).toBe(childId)
+
+    // Parked, not resumed: the Activation stays resident with an idle driver,
+    // the follow-up is retained, and no second turn opened.
+    const child = scaffold.ctx.agents.get(childId)
+    expect(child).toBeDefined()
+    expect(child!.status).toBe('idle')
+    expect(child!.inbox.nextTurn).toHaveLength(1)
+    expect(child!.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1)
+    const lastEnd = child!.session.events.filter(event => event.type === 'turn/end').at(-1)
+    expect((lastEnd)?.data.reason.kind).toBe('aborted')
+
+    // Only an explicit waking send resumes the parked queue, FIFO, then the
+    // child runs both turns to completion and settles.
+    const waking = await rpc<{ messageId: string }>(scaffold.baseUrl, 'subagent.prompt', {
+      parentSessionId: parentId,
+      childSessionId: childId,
+      mode: 'continuable',
+      content: [{ type: 'text', text: WAKING }],
+    })
+    expect(waking).toMatchObject({ ok: true })
+    await expect.poll(() => scaffold.ctx.agents.get(childId), { timeout: 60_000 }).toBeUndefined()
+
+    const loaded = await scaffold.ctx.sessionPersistence.load(childId)
+    // Human-origin messages only: the real composition also injects
+    // runtime-context snapshots as non-user-source messages.
+    const userTexts = loaded.events.flatMap(event => event.type === 'user/message'
+      && event.data.source.kind === 'user'
+      ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
+      : [])
+    expect(userTexts).toEqual([INITIAL, FOLLOWUP, WAKING])
+    const turnEndKinds = loaded.events
+      .filter(event => event.type === 'turn/end')
+      .map(event => (event).data.reason.kind)
+    expect(turnEndKinds).toEqual(['aborted', 'completed', 'completed'])
+  }, 120_000)
+})
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 7fb84f1507..3fa6ba8905 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -67,6 +67,7 @@
     "tests/produced-file-mentions.e2e.ts",
     "tests/goal-bar.e2e.ts",
     "tests/subagent-conversation.e2e.ts",
+    "tests/subagent-interrupt.e2e.ts",
     "tests/sidebar-subagent-activity.e2e.ts",
     "tests/bash-abort-row.e2e.ts",
     "tests/skill-tool-row.e2e.ts",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 81f660c317..1997f0ea47 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -54,6 +54,7 @@
     "apps/web/tests/produced-files.e2e.ts",
     "apps/web/tests/produced-file-mentions.e2e.ts",
     "apps/web/tests/subagent-conversation.e2e.ts",
+    "apps/web/tests/subagent-interrupt.e2e.ts",
     "apps/web/tests/sidebar-subagent-activity.e2e.ts",
     "apps/web/tests/bash-abort-row.e2e.ts",
     "apps/web/tests/skill-tool-row.e2e.ts",

From 57e9e6977c3065c461d3c5da38a2b841d6bb1ea1 Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 12:50:44 +0800
Subject: [PATCH 274/516] docs(subagent): record the public interrupt in the
 continuation contract docs

The continuable-subagent core-data page and the continuation lifecycle
Agent Note claimed no public subagent cancellation existed; interrupt()
is now that one public stop. Both pages and their Chinese counterparts
state the shipped contract and link the owning interrupt note.

Refs #1535
---
 ...8-continuable-subagent-conversations.i18n.yaml |  4 ++--
 ...26-07-28-continuable-subagent-conversations.md |  6 +++---
 ...07-28-continuable-subagent-conversations.zh.md |  6 +++---
 docs/core-data-structures/subagent.i18n.yaml      |  4 ++--
 docs/core-data-structures/subagent.md             | 15 ++++++++++++++-
 docs/core-data-structures/subagent.zh.md          | 15 ++++++++++++++-
 scripts/type-equiv.manifest.json                  |  5 +++++
 7 files changed, 43 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index 99629a74c0..82639d4aa8 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
-2026-07-28-continuable-subagent-conversations.md: a5a900c3bb30a8d965aabc0bf498f8399ee70e7a
-2026-07-28-continuable-subagent-conversations.zh.md: bde8e874ba27950dc0fab8449c6ba2ee49737d41
+2026-07-28-continuable-subagent-conversations.md: 56d9abb2b09577b2fba14b9a655a941417e0c493
+2026-07-28-continuable-subagent-conversations.zh.md: 77f497ceeef35dcc519242dca30c81759cc3b907
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
index a5a900c3bb..56d9abb2b0 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
@@ -131,7 +131,7 @@ Parent-originated delivery requires the parent to be live when admitted and keep
 
 ### Durability, disposal, and recovery
 
-Without Tasks there is no `task_output`, `task_kill`, Task status, per-message result promise, or public subagent cancellation operation. The caller signal can abort start or follow-up only before inbox acceptance. After acceptance, the parent cannot cancel the message, turn, or Activation through `ctx.subagents`; `Agent.cancel()` remains a lower-level Agent capability that this version does not expose through the subagent service.
+Without Tasks there is no `task_output`, `task_kill`, Task status, or per-message result promise. The caller signal can abort start or follow-up only before inbox acceptance. After acceptance, the parent cannot cancel the accepted message or dispose the Activation through `ctx.subagents`; the only public stop is the later [current-turn interrupt](2026-08-06-continuable-subagent-interrupt.md), which cancels the live target's current turn with `keepInbox` and leaves residency, pending work, and descendants intact.
 
 Host and manager teardown remains the lifecycle stop path. Manager unload applies it globally; a host applies it only below the exact top-level Agents it owns. Each form closes the applicable admission scope, stops the selected visible Activations, awaits admitted materializations in that scope, releases child-first, and preserves the durable Sessions.
 
@@ -145,7 +145,7 @@ Session and descriptor persistence survive restart. Activation state, Agent inbo
 
 This version covers continuable in-process children and leaves one-shot delegation unchanged. Remote providers require a separate Activation handle with equivalent authenticated control and child-first quiescence contracts before they can support the same behavior.
 
-It adds no host-user continuation, subagent steering operation, durable mailbox, cross-process lease, automatic replay of interrupted inbox work, team authority, workflow authority, public subagent cancellation operation, public residency query, new live-Activation or descendant limit, or runtime cache. Existing delegation-depth policy remains unchanged. Optional child-to-parent reporting is a later consumer of this lifecycle rather than part of the base continuable capability.
+It adds no host-user continuation, subagent steering operation, durable mailbox, cross-process lease, automatic replay of interrupted inbox work, team authority, workflow authority, public residency query, new live-Activation or descendant limit, or runtime cache; the later [current-turn interrupt](2026-08-06-continuable-subagent-interrupt.md) added the one public stop operation on top of this lifecycle. Existing delegation-depth policy remains unchanged. Optional child-to-parent reporting is a later consumer of this lifecycle rather than part of the base continuable capability.
 
 ## Alternatives considered
 
@@ -186,7 +186,7 @@ The implementation pins these behaviors:
 - `followup()` accepts only the exact live direct parent and rechecks that identity at the final no-await inbox-admission boundary after any materialization; durable message provenance cannot authorize delivery.
 - Continuation messages always use `Agent.followup()` and share its inbox FIFO, including when the child already has an open turn.
 - `ctx.subagents.followup()` and its `send_message` adapter return only the accepted `MessageId`; the continuation layer accepts no delivery target and defines no subagent-specific route result.
-- This version exposes no public subagent cancellation operation; caller signals stop start and follow-up only before inbox acceptance, while host-scoped and manager-global teardown retain child-first cleanup.
+- Caller signals stop start and follow-up only before inbox acceptance, while host-scoped and manager-global teardown retain child-first cleanup; the [current-turn interrupt](2026-08-06-continuable-subagent-interrupt.md) is the one public stop and does not enter teardown.
 - This version exposes no subagent steering operation or current-turn controller state.
 - An idle Agent with live owned children yields a `waiting` Activation whose `AgentHandle` remains retained.
 - A `next-turn` delivered to `waiting` wakes the same Activation; delivery after completed disposal cold-resumes a new Activation.
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index bde8e874ba..77f497ceee 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -131,7 +131,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ### 持久性、dispose 与恢复
 
-没有 Task 后，系统不再提供 `task_output`、`task_kill`、Task 状态、逐消息结果 promise 或公开 subagent 取消操作。调用方 signal 只能在 inbox 接受消息前中止 start 或 follow-up。消息被接受后，parent 不能通过 `ctx.subagents` 取消该消息、轮次或激活；`Agent.cancel()` 仍是底层 Agent 能力，但本版本不通过 subagent 服务暴露它。
+没有 Task 后，系统不再提供 `task_output`、`task_kill`、Task 状态或逐消息结果 promise。调用方 signal 只能在 inbox 接受消息前中止 start 或 follow-up。消息被接受后，parent 不能通过 `ctx.subagents` 取消已接受的消息或 dispose 激活；唯一的公开停止操作是后来的[当前轮次中断](2026-08-06-continuable-subagent-interrupt.md)，它以 `keepInbox` 取消在线目标的当前轮次，驻留、待处理工作与后代均保持不变。
 
 宿主和管理器拆卸仍是生命周期停止路径。管理器卸载会全局应用它；宿主只会在自己确切拥有的顶层 Agent 之下应用它。两种形式都会关闭适用的准入作用域，停止选中的可见 Activation，等待该作用域中已获准的物化过程，按 child-first 顺序释放，并保留持久化 Session。
 
@@ -145,7 +145,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 本版本覆盖可继续的进程内 child，一次性委派保持不变。远程提供方必须具备单独的激活 handle，以及等价的认证控制与 child-first 完全停稳契约，才能支持同样的行为。
 
-它不新增 host-user 继续执行、subagent steering 操作、持久化邮箱、跨进程 lease、中断 inbox 工作的自动回放、团队权限、工作流权限、公开 subagent 取消操作、公开驻留查询、新的在线激活数量或后代总数限制，以及运行时缓存。现有委派深度策略保持不变。可选的 child 到 parent 报告是后续消费该生命周期的功能，不属于基础可继续能力。
+它不新增 host-user 继续执行、subagent steering 操作、持久化邮箱、跨进程 lease、中断 inbox 工作的自动回放、团队权限、工作流权限、公开驻留查询、新的在线激活数量或后代总数限制，以及运行时缓存；后来的[当前轮次中断](2026-08-06-continuable-subagent-interrupt.md)在此生命周期之上补充了唯一的公开停止操作。现有委派深度策略保持不变。可选的 child 到 parent 报告是后续消费该生命周期的功能，不属于基础可继续能力。
 
 ## 曾考虑的替代方案
 
@@ -186,7 +186,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 - `followup()` 只接受确切的在线直接 parent，并在任何物化之后的最终无 await 的 inbox 准入边界再次检查该身份；持久化消息来源信息不能授权投递。
 - 继续执行消息始终使用 `Agent.followup()` 并共享其 inbox FIFO，包括 child 已有开放轮次的情况。
 - `ctx.subagents.followup()` 及其 `send_message` 适配器只返回已接受的 `MessageId`；继续执行层不接受投递 target，也不定义 subagent 专属路由结果。
-- 本版本不暴露公开 subagent 取消操作；调用方 signal 只能在 inbox 接受消息前停止 start 和 follow-up，限定到宿主的拆卸与管理器全局拆卸则保留 child-first 清理。
+- 调用方 signal 只能在 inbox 接受消息前停止 start 和 follow-up，限定到宿主的拆卸与管理器全局拆卸则保留 child-first 清理；[当前轮次中断](2026-08-06-continuable-subagent-interrupt.md)是唯一的公开停止操作，且不进入拆卸流程。
 - 本版本不暴露 subagent steering 操作或当前轮次控制方状态。
 - 带有在线所持 child 的空闲 Agent 会产生 `waiting` 激活，其 `AgentHandle` 继续保留。
 - 向 `waiting` 投递 `next-turn` 会唤醒同一个激活；完成 dispose 后投递消息会冷恢复新激活。
diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/core-data-structures/subagent.i18n.yaml
index eb708f33da..8c3aa46364 100644
--- a/docs/core-data-structures/subagent.i18n.yaml
+++ b/docs/core-data-structures/subagent.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 docs/core-data-structures/subagent.md
-subagent.md: 4d7552eb5749284d90e31e62d8ac02e3d7a21b1d
-subagent.zh.md: ebcb1ce445c164352109d6613028c7a36c10d6d4
+subagent.md: fba934233fb7e890d6a68bd4cc7d37f90ab913ed
+subagent.zh.md: 70651397f82e2cf4c0fe18aa26ff8247484ca0aa
diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md
index 4d7552eb57..fba934233f 100644
--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -139,7 +139,20 @@ The Agent inbox is the only queue. Every continuation message becomes one `Agent
 
 Follow-up authority comes from an exact live Agent tool context. The authenticated Agent must be the durable child's direct parent recorded in `SessionHeader.parentSession`. `MessageSource` and `senderSessionId` are durable provenance after admission and grant no authority; the optional model-facing tool uses `CoordinatorMessageSource`.
 
-For both operations the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child, and the seam exposes no public subagent cancellation or steering operation.
+For both operations the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child, and the seam exposes no steering operation.
+
+`SubagentService.interrupt(targetSessionId, authority)` is the one public stop: it authorizes synchronously, issues `Agent.cancel(cause, { keepInbox: true })` on the live target, and returns without awaiting quiescence. The Activation, its pending inbox work, and published descendants are untouched; only a later waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already settled — and a manager-less composition are accepted no-ops; a wrong parent address or a stale, self-targeting, or non-ancestor caller rejects with `UNAUTHORIZED`.
+
+```ts type-equiv
+/**
+ * Authority under which one interrupt request is admitted. `user` carries the
+ * durable direct-parent address a human client presented; `ancestor` carries
+ * the exact live Agent object whose recorded lineage must contain the caller.
+ */
+type SubagentInterruptAuthority =
+  | { readonly kind: 'user'; readonly parentSessionId: SessionId }
+  | { readonly kind: 'ancestor'; readonly agent: Agent }
+```
 
 Every Activation owns its `AgentHandle` and an `ownedChildren: Set<SessionId>`; because one Session has at most one live Activation, the child Session id identifies the live child without another runtime-incarnation reference. Starting a child or submitting parent-originated work registers the child in a continuation-managed parent's set before the child can run, and that parent cannot settle while the set is non-empty. A top-level or other non-continuation Agent has no Activation and stays outside the waiting graph. Child release happens only after the child Agent is quiescent, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal.
 
diff --git a/docs/core-data-structures/subagent.zh.md b/docs/core-data-structures/subagent.zh.md
index ebcb1ce445..70651397f8 100644
--- a/docs/core-data-structures/subagent.zh.md
+++ b/docs/core-data-structures/subagent.zh.md
@@ -139,7 +139,20 @@ Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `
 
 后续操作的权限来自确切的在线 Agent 工具上下文。已认证的 Agent 必须是持久化子 agent 在 `SessionHeader.parentSession` 中记录的直接父级。`MessageSource` 与 `senderSessionId` 在准入之后是持久的来源凭据，不授予任何权限；可选的面向模型工具使用 `CoordinatorMessageSource`。
 
-对于这两种操作，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent，并且该 seam 不对外暴露任何 subagent 取消或 steering（中途引导）操作。
+对于这两种操作，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent，并且该 seam 不对外暴露任何 steering（中途引导）操作。
+
+`SubagentService.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待静止即返回。Activation、其待处理的 inbox 工作与已发布的后代均不受影响；只有之后的一次唤醒发送才会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op；错误的 parent 地址，或过期、指向自身、非 ancestor 的调用方会以 `UNAUTHORIZED` 拒绝。
+
+```ts type-equiv
+/**
+ * Authority under which one interrupt request is admitted. `user` carries the
+ * durable direct-parent address a human client presented; `ancestor` carries
+ * the exact live Agent object whose recorded lineage must contain the caller.
+ */
+type SubagentInterruptAuthority =
+  | { readonly kind: 'user'; readonly parentSessionId: SessionId }
+  | { readonly kind: 'ancestor'; readonly agent: Agent }
+```
 
 每个 Activation 都拥有自己的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`；由于一份会话至多有一个存活 Activation，子会话 id 无需另一个运行时化身引用即可标识存活的子 agent。启动子 agent 或提交源自 parent 的工作，会在子 agent 能够运行之前将其注册到受继续执行管理的父级集合中；只要该集合非空，该父级就无法 settle。顶层或其他非继续执行的 Agent 没有 Activation，处于 waiting 图之外。只有当子 Agent 已停稳、该子 agent 的每个子级都已 dispose、best-effort 的最终会话 flush 结算完毕，且子 agent 的 `AgentHandle` 完成 dispose 之后，才会释放子 agent。
 
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 095fa25b4f..5c2f3eb454 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1150,6 +1150,11 @@
       "symbol": "SubagentFollowupOptions",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentInterruptAuthority",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
     {
       "doc": "docs/core-data-structures/subagent.md",
       "symbol": "ContinuableStart",

From 336c84baf0ead4e5fefbd7d40725de982e05c1ae Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 10:27:43 +0800
Subject: [PATCH 275/516] docs(subagent): clarify interrupt edge cases

---
 .../2026-08-06-continuable-subagent-interrupt.i18n.yaml   | 4 ++--
 .../feature/2026-08-06-continuable-subagent-interrupt.md  | 8 ++++++--
 .../2026-08-06-continuable-subagent-interrupt.zh.md       | 8 ++++++--
 docs/cordis-catalog/services.md                           | 7 ++++---
 docs/core-data-structures/subagent.i18n.yaml              | 4 ++--
 docs/core-data-structures/subagent.md                     | 2 +-
 docs/core-data-structures/subagent.zh.md                  | 2 +-
 docs/event-producer-consumer.md                           | 8 ++++----
 packages/cordis/tool-cordis/src/api-catalog.ts            | 2 +-
 packages/host/apiproxy/src/api/subagents.ts               | 4 ++--
 packages/subagent/subagent/README.i18n.yaml               | 4 ++--
 packages/subagent/subagent/README.md                      | 3 ++-
 packages/subagent/subagent/README.zh.md                   | 3 ++-
 packages/subagent/subagent/src/continuation.ts            | 7 ++++---
 packages/subagent/subagent/src/index.ts                   | 7 ++++---
 15 files changed, 43 insertions(+), 30 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index fe6e8870f5..643bb9f9ac 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 729f1eb8259aa28aa771ed71872ebce9cadd4ed8
-2026-08-06-continuable-subagent-interrupt.zh.md: 15fe34d8b5e1d67623aabfe08710f341739e92e1
+2026-08-06-continuable-subagent-interrupt.md: 7bbc6ecf6736e9e34924113be984a3bf7436b9b9
+2026-08-06-continuable-subagent-interrupt.zh.md: 22a71bf4cd3d9b949ae8cf458a3c83b65739d396
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 729f1eb825..7bbc6ecf67 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -10,7 +10,7 @@ A running continuable subagent could not be stopped without destroying it. The c
 
 ## Decision
 
-`ctx.subagents.interrupt(targetSessionId, authority)` stops only the live target's current turn. The manager primitive authorizes synchronously, calls the existing `Agent.cancel(cause, { keepInbox: true })`, and returns `void` — fire-and-return: the cancel signal is guaranteed issued, target quiescence is not awaited. Nothing else changes: no Activation disposal, no handle release, no descendant cascade, no inbox clearing, and no `AgentLoop` or `CancelOptions` change. Because `keepInbox` parks the pending queue at idle, an interrupt never auto-starts the next queued follow-up; only a later explicit waking send resumes the preserved FIFO order.
+`ctx.subagents.interrupt(targetSessionId, authority)` stops only the live target's current turn. The manager primitive authorizes synchronously, calls the existing `Agent.cancel(cause, { keepInbox: true })`, and returns `void` — fire-and-return: the cancel signal is guaranteed issued, target quiescence is not awaited. Nothing else changes: no Activation disposal, no handle release, no descendant cascade, no inbox clearing, and no `AgentLoop` or `CancelOptions` change. Because `keepInbox` parks the unclaimed pending queue at idle, an interrupt never auto-starts the next queued follow-up; work already claimed into the interrupted turn belongs to that turn and is not requeued. Once the interrupted driver is idle, an explicit waking send resumes the preserved FIFO order.
 
 Authority is a closed two-variant union, deliberately wider than delivery authority because stopping a turn is idempotent and delivers no content:
 
@@ -35,7 +35,11 @@ The Host RPC `subagent.interrupt` takes the continuable `SubagentAddress` and re
 
 ## Consequences
 
-A human or ancestor can now stop a runaway continuable turn without losing the child, its queued work, or its running descendants; the cost is a deliberately weak postcondition (`accepted` means "signal issued", so a target may remain visibly `running` until it observes the signal) that clients must render honestly. The parked-queue rule means an interrupted child sits idle with retained work until someone sends a waking message — an intentional human-in-the-loop pause, not a scheduler defect. The Web Stop action and the model-facing `interrupt_agent` tool build on this primitive in the stacked follow-up PRs for issue #1535.
+A human or ancestor can stop a runaway continuable turn without losing the child, its unclaimed queued work, or its running descendants; the cost is a deliberately weak postcondition (`accepted` means "signal issued", so a target may remain visibly `running` until it observes the signal) that clients must render honestly. The parked-queue rule means an interrupted child sits idle with retained work until a waking message arrives after the driver is idle — an intentional human-in-the-loop pause, not a scheduler defect. A waking send accepted during abort convergence currently remains queued without latching wake; Issue #1838 tracks the shared agent-loop correction.
+
+The address-only RPC exposes one bit of live residency: an absent target is accepted while a live target under a mismatched parent returns `subagent-unauthorized`. The single-user local Host trust model accepts that observability; a future multi-principal Host must revisit both authority and response indistinguishability.
+
+The Web Stop action and the model-facing `interrupt_agent` tool build on this primitive in the stacked follow-up PRs for issue #1535.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index 15fe34d8b5..22a71bf4cd 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-`ctx.subagents.interrupt(targetSessionId, authority)` 只停止在线目标的当前轮次。管理器原语同步完成鉴权，调用现有的 `Agent.cancel(cause, { keepInbox: true })`，然后返回 `void`——fire-and-return：保证取消信号已发出，但不等待目标静止。其余一切不变：不 dispose Activation、不释放 handle、不级联后代、不清空 inbox，也不改动 `AgentLoop` 或 `CancelOptions`。由于 `keepInbox` 让待处理队列停在 idle，中断绝不会自动启动下一个排队的 follow-up；只有之后一次显式唤醒发送才按保留的 FIFO 顺序恢复。
+`ctx.subagents.interrupt(targetSessionId, authority)` 只停止在线目标的当前轮次。管理器原语同步完成鉴权，调用现有的 `Agent.cancel(cause, { keepInbox: true })`，然后返回 `void`——fire-and-return：保证取消信号已发出，但不等待目标静止。其余一切不变：不 dispose Activation、不释放 handle、不级联后代、不清空 inbox，也不改动 `AgentLoop` 或 `CancelOptions`。由于 `keepInbox` 让尚未领取的待处理队列停在 idle，中断绝不会自动启动下一个排队的 follow-up；已被领取进入中断轮次的工作属于该轮次，不会重新入队。被中断的 driver 进入 idle 后，一次显式唤醒发送会按保留的 FIFO 顺序恢复。
 
 授权是一个封闭的双变体 union，刻意比投递权限更宽，因为停止一个轮次是幂等的且不投递任何内容：
 
@@ -35,7 +35,11 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 ## Consequences
 
-人类或 ancestor 现在可以停止一个失控的 continuable 轮次，而不丢失 child、其排队工作或正在运行的后代；代价是一个刻意保持弱的后置条件（`accepted` 表示"信号已发出"，目标在观察到信号前可能仍显示 `running`），客户端必须如实呈现。暂停队列规则意味着被中断的 child 会带着保留的工作停在 idle，直到有人发送唤醒消息——这是有意的 human-in-the-loop 暂停，不是调度器缺陷。Web 的 Stop 操作和面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
+人类或 ancestor 可以停止一个失控的 continuable 轮次，而不丢失 child、其尚未领取的排队工作或正在运行的后代；代价是一个刻意保持弱的后置条件（`accepted` 表示“信号已发出”，目标在观察到信号前可能仍显示 `running`），客户端必须如实呈现。暂停队列规则意味着被中断的 child 会带着保留的工作停在 idle，直到 driver 进入 idle 后收到唤醒消息——这是有意的 human-in-the-loop 暂停，不是调度器缺陷。在 abort 收敛期间被接受的唤醒发送目前会保持排队而不锁存 wake；Issue #1838 跟踪共享的 agent-loop 修正。
+
+仅凭地址的 RPC 会暴露一位在线驻留信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
+
+Web 的 Stop 操作和面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
 
 ## Testing
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index caf081b5a6..59a9cf527d 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2075,9 +2075,10 @@ async followup( parent: Agent, childId: SessionId, content: ContentBlock[], opti
  * Interrupt one live continuable child's current turn under a human parent
  * address or an exact live ancestor Agent. Fire-and-return: the cancel
  * signal is issued before this returns, but the target may keep running
- * until it observes the signal. Pending inbox work, the Activation, and
- * published descendants are preserved; only a later waking send resumes the
- * parked FIFO queue. An absent target — including a one-shot or unknown id —
+ * until it observes the signal. Unclaimed pending inbox work, the Activation,
+ * and published descendants are preserved; claimed work is not requeued.
+ * Once the interrupted driver is idle, a waking send resumes the parked FIFO
+ * queue. An absent target — including a one-shot or unknown id —
  * is an accepted no-op, as is a manager-less composition, which cannot own a
  * live Activation.
  * @param targetSessionId - the durable child session id to interrupt.
diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/core-data-structures/subagent.i18n.yaml
index 8c3aa46364..15d5e19578 100644
--- a/docs/core-data-structures/subagent.i18n.yaml
+++ b/docs/core-data-structures/subagent.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 docs/core-data-structures/subagent.md
-subagent.md: fba934233fb7e890d6a68bd4cc7d37f90ab913ed
-subagent.zh.md: 70651397f82e2cf4c0fe18aa26ff8247484ca0aa
+subagent.md: 4de77c6232d73d4b4e9dd87e9afc7a077e61f1a0
+subagent.zh.md: 3310bb4bf8cad1314ec26eef9042955959aba5fe
diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md
index fba934233f..4de77c6232 100644
--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -141,7 +141,7 @@ Follow-up authority comes from an exact live Agent tool context. The authenticat
 
 For both operations the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child, and the seam exposes no steering operation.
 
-`SubagentService.interrupt(targetSessionId, authority)` is the one public stop: it authorizes synchronously, issues `Agent.cancel(cause, { keepInbox: true })` on the live target, and returns without awaiting quiescence. The Activation, its pending inbox work, and published descendants are untouched; only a later waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already settled — and a manager-less composition are accepted no-ops; a wrong parent address or a stale, self-targeting, or non-ancestor caller rejects with `UNAUTHORIZED`.
+`SubagentService.interrupt(targetSessionId, authority)` is the one public stop: it authorizes synchronously, issues `Agent.cancel(cause, { keepInbox: true })` on the live target, and returns without awaiting quiescence. The Activation, its unclaimed pending inbox work, and published descendants are untouched; work already claimed into the interrupted turn is not requeued. Once the interrupted driver is idle, a waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already settled — and a manager-less composition are accepted no-ops. For a live target, a mismatched parent address or caller outside its live ancestry rejects with `UNAUTHORIZED`; stale ancestor objects and self-targeting ancestor requests reject before target lookup.
 
 ```ts type-equiv
 /**
diff --git a/docs/core-data-structures/subagent.zh.md b/docs/core-data-structures/subagent.zh.md
index 70651397f8..3310bb4bf8 100644
--- a/docs/core-data-structures/subagent.zh.md
+++ b/docs/core-data-structures/subagent.zh.md
@@ -141,7 +141,7 @@ Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `
 
 对于这两种操作，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent，并且该 seam 不对外暴露任何 steering（中途引导）操作。
 
-`SubagentService.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待静止即返回。Activation、其待处理的 inbox 工作与已发布的后代均不受影响；只有之后的一次唤醒发送才会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op；错误的 parent 地址，或过期、指向自身、非 ancestor 的调用方会以 `UNAUTHORIZED` 拒绝。
+`SubagentService.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待静止即返回。Activation、其尚未领取的待处理 inbox 工作与已发布的后代均不受影响；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；过期的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。
 
 ```ts type-equiv
 /**
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 940d89eae0..acd2bc5e91 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -37,10 +37,10 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:283`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
-| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:160`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
-| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:134`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:151`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
+| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:136`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:43`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - |
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index acaefa5d5f..1fd08a5c95 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -930,7 +930,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void',
-        jsDoc: '/**\n * Interrupt one live continuable child\'s current turn under a human parent\n * address or an exact live ancestor Agent. Fire-and-return: the cancel\n * signal is issued before this returns, but the target may keep running\n * until it observes the signal. Pending inbox work, the Activation, and\n * published descendants are preserved; only a later waking send resumes the\n * parked FIFO queue. An absent target — including a one-shot or unknown id —\n * is an accepted no-op, as is a manager-less composition, which cannot own a\n * live Activation.\n * @param targetSessionId - the durable child session id to interrupt.\n * @param authority - the human parent address or exact live ancestor Agent.\n * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the\n *   live target.\n */',
+        jsDoc: '/**\n * Interrupt one live continuable child\'s current turn under a human parent\n * address or an exact live ancestor Agent. Fire-and-return: the cancel\n * signal is issued before this returns, but the target may keep running\n * until it observes the signal. Unclaimed pending inbox work, the Activation,\n * and published descendants are preserved; claimed work is not requeued.\n * Once the interrupted driver is idle, a waking send resumes the parked FIFO\n * queue. An absent target — including a one-shot or unknown id —\n * is an accepted no-op, as is a manager-less composition, which cannot own a\n * live Activation.\n * @param targetSessionId - the durable child session id to interrupt.\n * @param authority - the human parent address or exact live ancestor Agent.\n * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the\n *   live target.\n */',
       },
       {
         signature: 'async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>',
diff --git a/packages/host/apiproxy/src/api/subagents.ts b/packages/host/apiproxy/src/api/subagents.ts
index 8efb452c2e..a85f4bc750 100644
--- a/packages/host/apiproxy/src/api/subagents.ts
+++ b/packages/host/apiproxy/src/api/subagents.ts
@@ -105,8 +105,8 @@ export interface SubagentsApi {
    * durable direct-parent authority, without requiring a live parent Agent,
    * consulting the catalog, or resuming anything. Fire-and-return: `accepted`
    * acknowledges the admitted cancel signal, not target quiescence, so the
-   * child may remain visibly running briefly. Queued follow-ups are kept and
-   * parked; an absent, idle, or already-completed target is likewise
+   * child may remain visibly running briefly. Unclaimed queued follow-ups are
+   * kept and parked; an absent, idle, or already-completed target is likewise
    * `accepted`.
    */
   interrupt(
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 250fd1a078..9b9843af87 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: 7de3a5563b274e925fba931a6d5de17e68cc397c
-README.zh.md: 6067555544ec0c32729beb2b4e3f773e31b747a1
+README.md: eb1baa39231a2c058b3ada1a23b7b87e2bb2e384
+README.zh.md: 8402df3e4ff2559898dfd4dd512ab1601c9ec61d
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 7de3a5563b..eb1baa3923 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -18,7 +18,7 @@ The [subagent family overview](../README.md) maps implementations and model-faci
 | `start(name, request)` | Validate an ordinary caller request, resolve its detached `one-shot` descriptor, then await the provider until a real one-shot child is published. Fulfillment returns a holder-owned `SubagentRun`; rejection means the provider has already cleaned every unpublished startup resource, while post-publication turn or infrastructure faults settle through the run. Continuable children never enter through this operation. |
 | `startContinuable(spec)` | Establish one durable continuable child and deliver its initial prompt. Resolves with `{ childId, messageId }` when the child's inbox accepts that prompt, without waiting for the turn to start or for the message to reach the Session log; any earlier failure rejects with no ids and rolls the child back entirely. Requires `ctx.agents`, session persistence, and a provider with the `prepareContinuable` capability. |
 | `followup(parent, childId, content, { source, signal })` | Deliver one later message from the exact live direct parent as the child's next FIFO turn, matching `Agent.followup()` terminology, and return the accepted `MessageId`. A resident child's inbox accepts it directly (waking a waiting Activation); an absent one cold-resumes from its persisted Session. Requires `ctx.agents`; cold resume also requires session persistence. |
-| `interrupt(targetSessionId, authority)` | Interrupt one live continuable child's current turn under a human durable parent address (`{ kind: 'user', parentSessionId }`) or an exact live ancestor Agent (`{ kind: 'ancestor', agent }`). Admission is synchronous and the effect asynchronous: it issues `Agent.cancel(cause, { keepInbox: true })` and returns without waiting for the target to observe the signal. Pending inbox work, the Activation, and published descendants are preserved; only a later waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already-settled id — and a manager-less composition are accepted no-ops; a wrong parent address or a stale, self-targeting, or non-ancestor caller rejects with `UNAUTHORIZED`. |
+| `interrupt(targetSessionId, authority)` | Interrupt one live continuable child's current turn under a human durable parent address (`{ kind: 'user', parentSessionId }`) or an exact live ancestor Agent (`{ kind: 'ancestor', agent }`). Admission is synchronous and the effect asynchronous: it issues `Agent.cancel(cause, { keepInbox: true })` and returns without waiting for the target to observe the signal. Unclaimed pending inbox work, the Activation, and published descendants are preserved; work already claimed into the interrupted turn is not requeued. Once the interrupted driver is idle, a waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already-settled id — and a manager-less composition are accepted no-ops. For a live target, a mismatched parent address or caller outside its live ancestry rejects with `UNAUTHORIZED`; stale ancestor objects and self-targeting ancestor requests reject before target lookup. |
 | `reportFrom(child, content, { delivery, signal })` | Deliver one selected message from the exact live continuable child to its exact live direct parent and return the accepted stable `MessageId`. Quiet delivery injects context; waking delivery submits one later parent turn. |
 | `registerContinuableSetup(contribution)` | Compose an optional deployment capability into each continuable child's unpublished scope, with immediate revocation from resident children. |
 | `drainContinuableDescendants(parents)` | Close admission below exact live host-owned parent Agents, stop only their visible continuable descendants, await materializations admitted below those roots through publication or rollback, then release the selected forests child-first. The cutoff lasts until each exact parent leaves the registry; unrelated parent forests and manager-wide admission remain live. |
@@ -102,6 +102,7 @@ No direct invalidation; the named consumers own any request-prefix changes.
 - **ACP children remain one-shot and are not trace-enumerable** — an ACP run has no local child session in the parent's session corpus. An ACP `prepareContinuable` requires persisting the remote session id in provider-specific descriptor data and a per-child continuation advertisement, since ACP `loadSession` support is negotiated per child rather than established by the method's presence. Remote providers also require a separate Activation ownership contract with equivalent authenticated control and child-first quiescence before they support continuable children.
 - **No host-user continuation** — `followup()` requires the exact live direct parent. Only `interrupt()` accepts a durable parent-address user authority, because stopping a turn is idempotent and delivers no content; a future host adapter needs a concrete authenticated interaction before the seam gains a user delivery capability.
 - **No current-turn steering** — continuable messages and waking reports enqueue later turns; neither redirects an open turn.
+- **Wake gap during cancellation convergence** — a waking follow-up accepted after the interrupt signal is issued but before the active driver becomes idle remains queued until another waking send. Issue #1838 owns the agent-loop wake latch, which also affects ordinary session cancellation.
 - **Process-local residency** — the Activation inbox and ownership graph do not coordinate two harness processes; concurrent access to one persistence store still requires a durable mailbox and cross-process lease protocol.
 - **No replay of accepted-but-unlogged messages** — only messages written to the child Session log are reconstructable with their admitted provenance. A crash may lose an accepted initial prompt or follow-up that never reached the log; a later authorized message can cold-resume the child, but the lost message is not replayed automatically.
 - **No durable report mailbox** — reports require a live direct parent and provide acceptance identity rather than exactly-once delivery or a read receipt.
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 6067555544..8402df3e4f 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -18,7 +18,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `start(name, request)` | 校验普通调用方请求，解析其分离的 `one-shot` 描述符，然后等待提供方，直到真实的一次性子 agent 发布。兑现时返回由持有方拥有的 `SubagentRun`；拒绝表示提供方已清理所有未发布的启动资源，而发布后的轮次或基础设施故障会通过该 run 结算。可继续子 agent 绝不通过此操作进入。 |
 | `startContinuable(spec)` | 建立一个持久化可继续子 agent，并投递其初始提示词。子 agent 的 inbox 接受该提示词时，兑现为 `{ childId, messageId }`，无需等待轮次开始或消息写入 Session 日志；此前任何失败都会以无 id 拒绝，并完全回滚该子 agent。要求 `ctx.agents`、会话持久化以及具备 `prepareContinuable` 能力的提供方。 |
 | `followup(parent, childId, content, { source, signal })` | 将来自确切在线直接父级的一条后续消息作为子 agent 的下一个 FIFO 轮次投递，术语与 `Agent.followup()` 一致，并返回被接受的 `MessageId`。驻留中的子 agent 由其 inbox 直接接受（唤醒处于 waiting 的 Activation）；不驻留的则从其持久化 Session 冷恢复。要求 `ctx.agents`；冷恢复还要求会话持久化。 |
-| `interrupt(targetSessionId, authority)` | 以人类持久化 parent 地址（`{ kind: 'user', parentSessionId }`）或确切在线 ancestor Agent（`{ kind: 'ancestor', agent }`）为授权，中断一个在线可继续 child 的当前轮次。准入是同步的、生效是异步的：它发出 `Agent.cancel(cause, { keepInbox: true })` 后立即返回，不等待目标观察到信号。待处理的 inbox 工作、Activation 与已发布的后代均保持不变；只有之后的一次唤醒发送才会恢复被暂停的 FIFO 队列。目标不存在——未知、一次性或已结算的 id——以及未绑定管理器的组合都是被接受的 no-op；错误的 parent 地址，或过期、指向自身、非 ancestor 的调用方会以 `UNAUTHORIZED` 拒绝。 |
+| `interrupt(targetSessionId, authority)` | 以人类持久化 parent 地址（`{ kind: 'user', parentSessionId }`）或确切在线 ancestor Agent（`{ kind: 'ancestor', agent }`）为授权，中断一个在线可继续 child 的当前轮次。准入是同步的、生效是异步的：它发出 `Agent.cancel(cause, { keepInbox: true })` 后立即返回，不等待目标观察到信号。尚未领取的待处理 inbox 工作、Activation 与已发布的后代均保持不变；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。目标不存在——未知、一次性或已结算的 id——以及未绑定管理器的组合都是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；过期的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。 |
 | `reportFrom(child, content, { delivery, signal })` | 从确切在线可继续 child 向其确切在线直接 parent 投递一条选中消息，并返回已接受的稳定 `MessageId`。静默投递会注入上下文；唤醒投递会提交一个后续 parent 轮次。 |
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
@@ -102,6 +102,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 - **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，以及逐子 agent 的继续执行能力声明，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权契约，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
 - **无 host-user 继续执行**：`followup()` 要求确切在线直接父级。只有 `interrupt()` 接受持久化 parent 地址形式的用户授权，因为停止一个轮次是幂等的且不投递任何内容；未来 host 适配器需要具体的经认证交互，才能让该 seam 获得用户投递能力。
 - **不对当前轮次进行 steering**：可继续消息和唤醒式 report 会排入后续轮次，均不会重定向正在进行的轮次。
+- **取消收敛期间存在唤醒缺口**：中断信号发出后、活动 driver 进入 idle 前被接受的唤醒型 follow-up 会保持排队，直到另一条唤醒发送到达。Issue #1838 负责 agent-loop 的唤醒锁存；普通会话取消也受此影响。
 - **驻留仅限进程内**：Activation inbox 与所有权图不会在两个 harness 进程之间协调；对单个持久化存储的并发访问仍然需要持久化邮箱和跨进程租约协议。
 - **不重放已接受但未记录的消息**：只有写入子 agent Session 日志的消息才能连同其被接受时的来源一起重建。崩溃可能丢失从未写入日志、已被接受的初始提示词或后续消息；此后一条经授权的消息可以冷恢复该子 agent，但丢失的消息不会自动重放。
 - **没有持久化的上报 mailbox**：上报需要实时直接父级，提供的是接受标识，不保证恰好一次投递，也不提供已读回执。
diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts
index ebac0a1296..67cc177fe1 100644
--- a/packages/subagent/subagent/src/continuation.ts
+++ b/packages/subagent/subagent/src/continuation.ts
@@ -426,9 +426,10 @@ export class SubagentContinuationManager {
    * synchronous and the effect is asynchronous: this authorizes the caller,
    * requests `Agent.cancel(cause, { keepInbox: true })` on the target, and
    * returns without waiting for the target to observe the signal or reach
-   * quiescence. The Activation, its handle, accepted pending inbox work, and
-   * already-published descendants are untouched; the parked queue resumes only
-   * on a later waking send.
+   * quiescence. The Activation, its handle, accepted unclaimed inbox work, and
+   * already-published descendants are untouched; work already claimed into the
+   * interrupted turn is not requeued. Once the interrupted driver is idle, a
+   * waking send resumes the parked queue.
    *
    * An absent target is an accepted no-op, which uniformly covers natural
    * completion races, repeated requests, one-shot ids, and unknown ids without
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index e179bfd8b4..8bf4efb5d0 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -237,9 +237,10 @@ export class SubagentService extends Service {
    * Interrupt one live continuable child's current turn under a human parent
    * address or an exact live ancestor Agent. Fire-and-return: the cancel
    * signal is issued before this returns, but the target may keep running
-   * until it observes the signal. Pending inbox work, the Activation, and
-   * published descendants are preserved; only a later waking send resumes the
-   * parked FIFO queue. An absent target — including a one-shot or unknown id —
+   * until it observes the signal. Unclaimed pending inbox work, the Activation,
+   * and published descendants are preserved; claimed work is not requeued.
+   * Once the interrupted driver is idle, a waking send resumes the parked FIFO
+   * queue. An absent target — including a one-shot or unknown id —
    * is an accepted no-op, as is a manager-less composition, which cannot own a
    * live Activation.
    * @param targetSessionId - the durable child session id to interrupt.

From 5793614b866de1e7af82a9627728d8b733da6c1b Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 12:45:37 +0800
Subject: [PATCH 276/516] feat(web): expose continuable subagent interrupt

The composer's single primary action now stops a running continuable
child: Session.cancel() routes a continuable address through
subagent.interrupt (ordinary sessions keep session.cancel; one-shot
addresses stay uncancellable), and InputBar switches the same Send button
to Stop while a continuable child runs. A running parent-offline child
keeps the default composer with disabled input so that Stop stays
reachable; the read-only takeover returns once it stops.

Refs #1535
---
 ...07-27-web-subagent-conversations.i18n.yaml |   4 +-
 .../2026-07-27-web-subagent-conversations.md  |  12 +-
 ...026-07-27-web-subagent-conversations.zh.md |  12 +-
 ...6-continuable-subagent-interrupt.i18n.yaml |   4 +-
 ...26-08-06-continuable-subagent-interrupt.md |   4 +-
 ...08-06-continuable-subagent-interrupt.zh.md |   4 +-
 .../offline-composer.expected.md              |  25 ++
 apps/web/tests/subagent-interrupt-ui.e2e.ts   | 271 ++++++++++++++++++
 apps/web/tsconfig.json                        |   1 +
 .../runtime/src/client/sessions/session.ts    |  15 +-
 packages/client/runtime/tests/session.spec.ts |  30 +-
 .../ui-conversation/src/client/locales.ts     |   2 +
 .../src/client/skeleton/InputBar.tsx          |  25 +-
 .../ui-conversation/tests/input-bar.spec.tsx  |  46 ++-
 packages/client/ui-subagent/README.i18n.yaml  |   4 +-
 packages/client/ui-subagent/README.md         |   4 +-
 packages/client/ui-subagent/README.zh.md      |   4 +-
 .../client/ui-subagent/src/client/index.ts    |   6 +-
 .../ui-subagent/tests/browser-plugin.spec.ts  |   9 +-
 tsconfig.host.json                            |   1 +
 20 files changed, 433 insertions(+), 50 deletions(-)
 create mode 100644 apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
 create mode 100644 apps/web/tests/subagent-interrupt-ui.e2e.ts

diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index 56952f8b69..4ec9a77d72 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: edaaa97bbfcf0ce1751db84d8fc2d3ab07af8b03
-2026-07-27-web-subagent-conversations.zh.md: 4c5e670cc46621b889d8463daa90afbf43bde30f
+2026-07-27-web-subagent-conversations.md: da4de7d4bcd23f61459eba3fee8108b0af1c95f9
+2026-07-27-web-subagent-conversations.zh.md: 43d9710ec2b63a09bd3db029f172746d63d91cfe
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index edaaa97bbf..da4de7d4bc 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -20,7 +20,7 @@ Every opened child carries a catalog-derived address `{ parentSessionId, childSe
 
 The generic Host domain preserves the same ownership boundary. `session.history` and the source side of `session.fork` read an attached Session or inspect persistence without acquiring an Agent; history folds cold projection values from that exact inspected prefix, while a fork publishes an ordinary independent session. Generic Agent-bound session, command, and goal routes return `agent-busy` for session-backed subagents, as do explicit-id `session.create` adoption and attached-only queue controls. The denial classifier accepts the coarse `origin` marker, a `subagent/descriptor` in the session's own suffix, or exact live runtime ownership by the parent; these signals only prevent generic ownership and never replace catalog mode or direct-parent authorization.
 
-The ordinary Stop action is absent from addressed child conversations. `SubagentService.followup()` owns admission only until inbox acceptance and intentionally exposes no public child cancellation operation. A later cancellation design needs an explicit authority and lifecycle contract rather than falling through to `session.cancel`.
+Stopping an addressed child never falls through to `session.cancel`. `SubagentService.followup()` owns admission only until inbox acceptance and grants no cancellation handle; a running continuable child is stopped through the dedicated `subagent.interrupt` route under the [current-turn interrupt contract](2026-08-06-continuable-subagent-interrupt.md), which parks pending work instead of discarding it. One-shot children remain uncancellable from the Web.
 
 This decision covers Web discovery, transcript viewing, and parent-authorized human continuation. It does not make a subagent independently user-owned; that product remains [interactive side sessions](../../proposed/feature/2026-07-08-interactive-side-sessions.md).
 
@@ -45,7 +45,7 @@ Healthy rows reuse the standard session projections retained in the list mirror.
 
 Selecting a row records its exact address before opening the resident client `Session`. History pagination, event folding, tool render intents, titles, and live mux reconciliation reuse the ordinary conversation machinery. Breadcrumbs use catalog labels, follow parent links only through `origin: 'subagent'` rows, include the first ordinary owner, and keep ordinary forks single-level. Forking an addressed subagent creates an ordinary fork with direct source lineage and attaches it to the nearest workspace-owning ancestor. The catalog is an ARIA tree with lazy ArrowRight/ArrowLeft disclosure, linear ArrowUp/ArrowDown navigation, Home/End, Escape, and focus restoration.
 
-A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false. When enabled, its Send action admits another FIFO turn even if the child is currently running; it never becomes Stop. Prompt failures retain the draft through the ordinary error behavior.
+A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false and the child is not running; a running parent-offline child keeps the ordinary composer with its input disabled so the same primary Stop stays reachable, and the read-only takeover returns once it stops. With a live parent, Enter admits another FIFO turn even while the child runs, and the single primary action follows the ordinary running convention: Send while idle, Stop while running, routed through `subagent.interrupt` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Prompt failures retain the draft through the ordinary error behavior.
 
 Agent-bound auxiliary controls are unavailable in addressed child views. In particular, the model selector and `/model` contribution do not call ordinary `session.models` or `session.selectModel`; the Host also rejects any accidental call instead of activating persisted child history outside the direct-parent continuation seam.
 
@@ -89,7 +89,7 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 
 **Auto-resume an absent parent.** Rejected because continuation requires the exact live direct parent. Child navigation must not mutate the parent lifecycle.
 
-**Expose ordinary cancellation.** Rejected because the accepted inbox turn outlives its admission request and the continuation seam exposes no authority-safe cancellation handle.
+**Expose ordinary cancellation.** Rejected because the accepted inbox turn outlives its admission request and, at this decision's time, the continuation seam exposed no authority-safe cancellation handle. The later [current-turn interrupt contract](2026-08-06-continuable-subagent-interrupt.md) added that explicit authority as a dedicated subagent route; falling through to `session.cancel` remains rejected.
 
 **Show only continuable children.** Rejected because the durable catalog deliberately describes both session-backed modes. One-shot transcripts remain useful even though they never accept follow-ups.
 
@@ -103,9 +103,9 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 
 - Host protocol tests pin schemas including required boolean expandability, id echoing, mode verification, non-activating history, exact-parent enforcement, FIFO admission receipts, cancellation, and sanitized failure mapping.
 - Generic Host tests pin attached and cold history and forks without Agent publication, cold projection folding, descriptor/origin/runtime-owner denial, explicit-id adoption denial, and the direct queue-control fence.
-- Client object tests pin retained and restored addresses, one-shot read-only rejection, history routing, continuable prompt routing, no addressed cancellation, suppression of Agent-bound model controls, live activity flips including in-flight response replay and detach fallback, subagent-parent expandability flips, and membership refresh.
+- Client object tests pin retained and restored addresses, one-shot read-only and cancel rejection, history routing, continuable prompt and interrupt routing, suppression of Agent-bound model controls, live activity flips including in-flight response replay and detach fallback, subagent-parent expandability flips, and membership refresh.
 - jsdom tests pin the aggregate descendant count and activity, sidebar propagation across nested lineage and ordinary-fork boundaries, row-status precedence, token totals, second-precision running and frozen inactive durations, adaptive long-duration units with exact accessible text, the summary-backed root action across absent and stale-empty catalogs, known loading-row shape, mixed-mode rows, pre-click leaf disclosure, diagnostics, lazy descendant disclosure, direct-parent addresses, keyboard behavior, and both read-only reasons.
-- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, and adaptive long-duration presentation, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the model seam while it pins the aggregate running state in both the header and visible idle owner row, then cancels the turn during teardown.
+- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, and the aggregate running transition, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the model seam while it pins the aggregate running state in both the header and visible idle owner row, then cancels the turn during teardown.
 - Navigation tests pin subagent-only breadcrumbs, workspace placement for forks created from subagents, and `origin: 'subagent'` sidebar filtering without hiding ordinary forks.
 
 ## Consequences
@@ -114,4 +114,4 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 - Parent availability, child activity, and `hasChildren` are snapshots. Publication, disposal, another sender, or another process may win after listing; typed prompt failure remains expected.
 - A child may publish between history fetch and mux subscription, so the existing sequence reconciliation also covers the cold-to-live addressed path.
 - Persisted origin adds one deliberately weak product-classification field to child headers and list projections; it cannot become an authorization shortcut.
-- The UI has no child cancellation, durable outcome, Activation identity, deletion, or independently interactive offline mode, and its text must not imply those capabilities. Active-turn duration measures logged work rather than Activation residency.
+- Beyond the current-turn Stop of a running continuable child ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)), the UI has no child cancellation, durable outcome, Activation identity, deletion, or independently interactive offline mode, and its text must not imply those capabilities. Active-turn duration measures logged work rather than Activation residency.
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index 4c5e670cc4..43d9710ec2 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -20,7 +20,7 @@ Web 产品通过页头操作公开选中会话中由会话支撑的直接 subage
 
 通用 Host 领域遵守同一所有权边界。`session.history` 与 `session.fork` 的源端会读取已附加 Session 或检查持久化存储，而不获取 Agent；history 从所检查的确切前缀归并冷态投影值，fork 则发布一个普通的独立会话。绑定到 Agent 的通用会话、命令与目标路由会对由会话支撑的 subagent 返回 `agent-busy`；显式 id 的 `session.create` 接纳与仅针对已附加会话的队列控件亦然。拒绝分类器接受粗粒度 `origin` 标记、会话自身后缀中的 `subagent/descriptor`，或 parent 对其确切的存活运行时所有权；这些信号只会阻止通用路径取得所有权，绝不取代目录 mode 或直接 parent 授权。
 
-已寻址 child 对话不提供普通 Stop 操作。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，并有意不公开任何 child 取消操作。后续取消设计需要显式的授权与生命周期契约，而不能回退到 `session.cancel`。
+停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)，该契约会暂停而非丢弃待处理工作。one-shot child 在 Web 端仍不可取消。
 
 本决策涵盖 Web 端发现、transcript 查看与经 parent 授权的用户继续交互。它不会让 subagent 成为用户独立所有的对象；这类产品仍然属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)。
 
@@ -45,7 +45,7 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 选择一行后，系统会先记录其确切地址，再打开常驻客户端 `Session`。历史分页、事件 fold、工具渲染意图、title 与实时 mux 归并都会复用普通对话机制。面包屑导航使用目录 label，只会沿 `origin: 'subagent'` 行的父链接逐级回溯，包含第一个普通 owner，并让普通 fork 保持单层。从已寻址 subagent 创建 fork 时，会生成具有直接源谱系的普通 fork，并将其附加到最近拥有 Workspace 的祖先。目录是一棵 ARIA 树，支持懒加载式 ArrowRight／ArrowLeft 展开与折叠、线性 ArrowUp／ArrowDown 导航、Home／End、Escape 以及焦点恢复。
 
-one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 时如此。启用后，即使 child 正在运行，其 Send 操作也会准入另一个 FIFO 轮次，绝不会变成 Stop。提示词失败会通过普通错误行为保留草稿。
+one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，只禁用其输入区，让同一个 primary Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 也会准入另一个 FIFO 轮次，而唯一的 primary 操作遵循普通运行约定：空闲时为 Send，运行时为 Stop，经由 `subagent.interrupt` 路由（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
 
 已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
@@ -89,7 +89,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 **自动恢复缺失的 parent。** 不予采纳，因为继续执行要求确切的存活直接 parent。child 导航不得改变 parent 生命周期。
 
-**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，而继续执行 seam 不会公开具备安全授权的取消句柄。
+**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
 
 **只显示可继续 child。** 不予采纳，因为持久化目录有意描述由会话支撑的两种 mode。one-shot transcript 即使绝不接受后续消息，仍然有用。
 
@@ -103,9 +103,9 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 - 宿主协议测试固定 schema（包括必需的布尔可展开性）、id 回显、mode 校验、非激活式历史、确切 parent 强制要求、FIFO 准入回执、取消与脱敏后的失败映射。
 - 通用 Host 测试固定在不发布 Agent 的情况下读取已附加与冷态历史及执行 fork、冷态投影归并、按描述符／origin／运行时 owner 拒绝、拒绝显式 id 接纳，以及直接队列控制栅栏。
-- 客户端对象测试固定已保留与已恢复的地址、one-shot 只读拒绝、历史路由、可继续提示词路由、已寻址对话不提供取消、屏蔽绑定到 agent 的模型控件、实时活动状态翻转（包括在途响应回放与 detach 回退）、subagent parent 可展开性翻转与成员刷新。
+- 客户端对象测试固定已保留与已恢复的地址、one-shot 只读与取消拒绝、历史路由、可继续提示词与中断路由、屏蔽绑定到 agent 的模型控件、实时活动状态翻转（包括在途响应回放与 detach 回退）、subagent parent 可展开性翻转与成员刷新。
 - jsdom 测试固定后代聚合计数与活动状态、侧边栏活动在嵌套谱系中的传播与普通 fork 边界、行状态优先级、token 用量总计、精确到秒的运行中耗时与冻结后 inactive 耗时、采用自适应单位的长耗时及其精确无障碍文本、目录缺失或为陈旧空目录时由摘要支撑的根操作、已知加载行的形态、混合 mode 行、点击前的叶子展开控件、diagnostic、后代懒加载展开、直接 parent 地址、键盘行为与两种只读原因。
-- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行及自适应长耗时呈现，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 model seam 处保持一个真实的 child Agent 轮次进行中，同时固定页头和可见空闲 owner 行中的聚合运行状态，随后在 teardown 期间取消该轮次。
+- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现及聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 model seam 处保持一个真实的 child Agent 轮次进行中，同时固定页头和可见空闲 owner 行中的聚合运行状态，随后在 teardown 期间取消该轮次。
 - 导航测试固定仅含 subagent 的面包屑导航、从 subagent 创建 fork 时的 Workspace 归属，以及 `origin: 'subagent'` 侧边栏过滤，同时不隐藏普通 fork。
 
 ## 后果
@@ -114,4 +114,4 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 - parent 可用性、child 活动状态与 `hasChildren` 都是快照。列出之后，发布、dispose、其他发送方或其他进程都可能抢先改变状态；类型化提示词失败仍属预期行为。
 - child 可能在历史获取与 mux 订阅之间发布，因此现有序号归并也涵盖从冷态转为存活的已寻址路径。
 - 持久化 origin 会为 child header 与列表投影添加一个有意保持弱约束的产品分类字段；它不能变成授权捷径。
-- UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
+- 除对正在运行的可继续 child 的当前轮次 Stop（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）之外，UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 643bb9f9ac..5cf5601fc0 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 7bbc6ecf6736e9e34924113be984a3bf7436b9b9
-2026-08-06-continuable-subagent-interrupt.zh.md: 22a71bf4cd3d9b949ae8cf458a3c83b65739d396
+2026-08-06-continuable-subagent-interrupt.md: 1792d4c6d25858c861be0ff920206d0d4e684f41
+2026-08-06-continuable-subagent-interrupt.zh.md: ff9887481d1ded2743c7c8f9f162413fb6581d70
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 7bbc6ecf67..1792d4c6d2 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -39,8 +39,8 @@ A human or ancestor can stop a runaway continuable turn without losing the child
 
 The address-only RPC exposes one bit of live residency: an absent target is accepted while a live target under a mismatched parent returns `subagent-unauthorized`. The single-user local Host trust model accepts that observability; a future multi-principal Host must revisit both authority and response indistinguishability.
 
-The Web Stop action and the model-facing `interrupt_agent` tool build on this primitive in the stacked follow-up PRs for issue #1535.
+The Web surface reuses the existing primary Send/Stop toggle rather than adding a second action: the client `Session.cancel()` routes a continuable address through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep `session.cancel`), and a running parent-offline continuable child keeps the default composer with disabled input so that same primary Stop remains reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract). The model-facing `interrupt_agent` tool builds on this primitive in the stacked follow-up PR for issue #1535.
 
 ## Testing
 
-Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips.
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar Send/Stop toggle with the parent-offline locked-input state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index 22a71bf4cd..ff9887481d 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -39,8 +39,8 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 仅凭地址的 RPC 会暴露一位在线驻留信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
 
-Web 的 Stop 操作和面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
+Web 侧复用现有的 primary Send/Stop 切换而不新增第二个操作：客户端 `Session.cancel()` 将 continuable 地址路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍走 `session.cancel`）；parent 离线但仍在运行的 continuable child 保留默认 composer 并禁用其输入区，让同一个 primary Stop 保持可达，停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
 
 ## Testing
 
-`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的 Send/Stop 切换及 parent 离线时锁定输入的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。
diff --git a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
new file mode 100644
index 0000000000..6ea7b83bff
--- /dev/null
+++ b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
@@ -0,0 +1,25 @@
+- banner:
+  - navigation "Session hierarchy":
+    - button "Ask a research subagent to"
+    - text: /
+    - button "event-sourcing researcher" [disabled]
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- text: Explain event sourcing in one sentence. {{clock}}
+- button "Copy":
+  - img
+- button "Branch into a new conversation" [disabled]:
+  - img
+- text: Available only on the last message of a completed turn
+- button "Context injection @deepseek-ai/dsh-system-prompt":
+  - img
+  - img
+  - text: Context injection @deepseek-ai/dsh-system-prompt
+- paragraph: partial
+- status: Deep diving...
+- textbox "Parent session offline; sending is unavailable but you can still stop the run" [disabled]
+- button "Commands" [disabled]:
+  - img
+- 'button "Access mode, current: Workspace Write" [disabled]': Workspace Write
+- button "Stop generating"
diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts
new file mode 100644
index 0000000000..be72f6546b
--- /dev/null
+++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts
@@ -0,0 +1,271 @@
+// Web e2e scenario: the composer's primary action interrupts a running
+// continuable child. The child holds its model turn open through a replay
+// hang entry; the browser proves the single primary Send/Stop toggle, the
+// parent-offline disabled-input-with-Stop composer, the subagent.interrupt
+// (never session.cancel) transport, the parked follow-up, and the FIFO resume
+// on a waking send.
+//
+// Replay-binding note: only the PRIMARY script can hang, and scripts bind by
+// first-call order, so the child issues the composition's first model call
+// (claiming the overridden primary) and the parent's one UI prompt — needed
+// so the non-blank parent renders its header catalog — binds to a derived
+// child fixture afterwards.
+import { existsSync } from 'node:fs'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-agent'
+import {
+  acknowledgeReloadConnectionLoss, assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
+  launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
+
+const BASE_FIXTURE = fileURLToPath(new URL('./snapshots/live-interactions/session.jsonl', import.meta.url))
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/subagent-interrupt', import.meta.url))
+const OFFLINE_COMPOSER_EXPECTED = join(SNAPSHOT_DIR, 'offline-composer.expected.md')
+const MODE = webSnapshotMode()
+const LABEL = 'event-sourcing researcher'
+const INITIAL = 'Explain event sourcing in one sentence.'
+const FOLLOWUP = 'Now give the same explanation to a human reader.'
+const WAKING = 'And add one concrete example.'
+const PARKED_ANSWER = 'parked follow-up answer'
+const WAKING_ANSWER = 'waking answer'
+
+/** Poll a synchronous condition (hook-safe; expect.poll is test-body only). */
+async function waitFor(predicate: () => boolean, what: string, timeoutMs = 30_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error(`timed out waiting for ${what}`)
+    await new Promise<void>(resolve => setTimeout(resolve, 10))
+  }
+}
+
+/** One text-only scripted model completion (no tool calls: real tools are mounted). */
+function textCompletion(text: string): object {
+  return {
+    kind: 'chunks',
+    chunks: [
+      { type: 'block-start', index: 0, blockType: 'text' },
+      { type: 'text-delta', index: 0, text },
+      { type: 'block-end', index: 0, block: { type: 'text', text } },
+      { type: 'usage', usage: { inputTokens: 20, outputTokens: 8 } },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ],
+  }
+}
+
+describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running continuable child', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let sidecarRoot: string
+  let childId: SessionId
+  let tripwire: ReturnType<typeof watchConsole>
+  const apiCalls: string[] = []
+
+  beforeAll(async () => {
+    sidecarRoot = await mkdtemp(join(tmpdir(), 'dsh-web-subagent-interrupt-ui-'))
+    const readyFile = join(sidecarRoot, 'hang-ready')
+    // The child claims this whole-script replacement: held turn 1, then the
+    // parked follow-up and waking turns.
+    await writeFile(join(sidecarRoot, 'replay.override.json'), JSON.stringify([
+      { kind: 'hang', readyFile },
+      textCompletion(PARKED_ANSWER),
+      textCompletion(WAKING_ANSWER),
+    ]))
+    await writeFile(
+      join(sidecarRoot, 'session.jsonl'),
+      '{"type":"session","version":0,"id":"primary","createdAt":0}\n',
+    )
+    // The parent's one prompted turn replays this recorded single text-only
+    // call (binding is positional, not lineage-aware).
+    const parentTurnPath = join(sidecarRoot, 'parent-turn.jsonl')
+    const base = await readFile(BASE_FIXTURE, 'utf8')
+    const [header, ...events] = base.trimEnd().split('\n')
+    if (header === undefined) throw new Error('base replay fixture has no header')
+    await writeFile(parentTurnPath, [
+      header
+        .replace('"id":"{{sessionId}}"', '"id":"recorded-parent-turn"')
+        .replace(/"createdAt":\d+/, '"createdAt":1784998084442'),
+      ...events,
+      '',
+    ].join('\n'))
+    scaffold = await launchWebScaffold({
+      replayFixture: join(sidecarRoot, 'session.jsonl'),
+      replayOverride: join(sidecarRoot, 'replay.override.json'),
+      replayChildFixtures: [parentTurnPath],
+    })
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    page.on('request', (request) => {
+      const path = new URL(request.url()).pathname
+      if (path.startsWith('/api/')) apiCalls.push(path)
+    })
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    await connectFreshWorkspace(page, scaffold.workspaceCwd)
+
+    const parent = scaffold.ctx.agents.roots()[0]
+    if (parent === undefined) throw new Error('fresh workspace did not publish its parent Agent')
+    // The child's first model call claims the primary override and holds.
+    const started = await scaffold.ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: LABEL,
+      signal: new AbortController().signal,
+      request: { prompt: [{ type: 'text', text: INITIAL }], parent },
+    })
+    childId = started.childId
+    await waitFor(() => existsSync(readyFile), 'the held child turn to open')
+
+    // One prompted parent turn makes the parent non-blank so the session
+    // header (and its subagent catalog action) renders.
+    const parentSettled = scaffold.whenTurnSettled()
+    const parentInput = page.locator('textarea:enabled').first()
+    await parentInput.fill('Ask a research subagent to explain event sourcing.')
+    await parentInput.press('Enter')
+    expect(await parentSettled).toBe(parent.id)
+
+    // Reload onto the restart baseline (the proven route to a freshly
+    // discovered catalog), with the child still live and running host-side.
+    const warningStart = tripwire.warnings.length
+    await page.reload({ waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+    await page.getByRole('button', { name: /1 subagent/ }).waitFor({ timeout: 15_000 })
+    acknowledgeReloadConnectionLoss(tripwire, warningStart)
+    expect(scaffold.ctx.agents.get(childId)?.status).toBe('running')
+  }, 120_000)
+
+  afterAll(async () => {
+    const failures: unknown[] = []
+    await browser?.close().catch((error: unknown) => failures.push(error))
+    await scaffold?.close().catch((error: unknown) => failures.push(error))
+    if (sidecarRoot !== undefined) {
+      await rm(sidecarRoot, { recursive: true, force: true })
+        .catch((error: unknown) => failures.push(error))
+    }
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, 'subagent interrupt UI teardown failed')
+  })
+
+  it('locks input but keeps the same primary Stop when the parent is offline', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-offline'))
+    // Simulate a parent that went offline: the catalog delivers
+    // parentAvailable: false while the child Activation stays live (the
+    // interrupt RPC itself needs no live parent — PR 1's host coverage).
+    const pattern = '**/api/subagent.list'
+    await page.route(pattern, async (route) => {
+      const response = await route.fetch()
+      const body = await response.json() as {
+        result: { ok: true; value: { parentAvailable: boolean } } | { ok: false }
+      }
+      if (body.result.ok) body.result.value.parentAvailable = false
+      await route.fulfill({ response, json: body })
+    })
+    try {
+      await page.getByRole('button', { name: /1 subagent/ }).click()
+      await page.getByRole('treeitem', { name: new RegExp(LABEL) }).click()
+      const input = page.getByRole('textbox', {
+        name: 'Parent session offline; sending is unavailable but you can still stop the run',
+      })
+      await input.waitFor({ timeout: 15_000 })
+      expect(await input.isDisabled()).toBe(true)
+      // Still exactly one primary action, and it is an enabled Stop.
+      const stop = page.getByRole('button', { name: 'Stop generating' })
+      expect(await stop.count()).toBe(1)
+      expect(await stop.isEnabled()).toBe(true)
+      expect(await page.getByRole('button', { name: 'Send message' }).count()).toBe(0)
+      await compareOrRefreshGolden(
+        OFFLINE_COMPOSER_EXPECTED,
+        await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd),
+        MODE,
+      )
+    } finally {
+      await page.unroute(pattern)
+    }
+  }, 60_000)
+
+  it('interrupts through subagent.interrupt, parks the follow-up, and resumes it FIFO', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-flow'))
+    // Reselect the child with the truthful catalog: parent available again.
+    await page.getByRole('navigation', { name: 'Session hierarchy' })
+      .getByRole('button').first().click()
+    await page.getByRole('button', { name: /1 subagent/ }).click()
+    await page.getByRole('treeitem', { name: new RegExp(LABEL) }).click()
+    const input = page.getByRole('textbox', { name: 'Message the agent' })
+    await input.waitFor({ timeout: 15_000 })
+    expect(await input.isDisabled()).toBe(false)
+
+    // Queue a follow-up while the turn is open; the primary stays Stop.
+    const promptResponse = page.waitForResponse(response =>
+      new URL(response.url()).pathname === '/api/subagent.prompt')
+    await input.fill(FOLLOWUP)
+    await input.press('Enter')
+    expect(((await (await promptResponse).json()) as { result: { ok: boolean } }).result)
+      .toMatchObject({ ok: true })
+
+    const aborted = new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off()
+        reject(new Error('interrupt did not reach an aborted turn/end'))
+      }, 30_000)
+      const off = scaffold.ctx.on('session/event', (session: { id: SessionId }, event: SessionEvent) => {
+        if (session.id !== childId || event.type !== 'turn/end') return
+        clearTimeout(timer)
+        off()
+        if (event.data.reason.kind === 'aborted') resolve()
+        else reject(new Error(`expected an aborted turn/end, got ${event.data.reason.kind}`))
+      })
+    })
+    const stop = page.getByRole('button', { name: 'Stop generating' })
+    expect(await stop.count()).toBe(1)
+    const interruptResponse = page.waitForResponse(response =>
+      new URL(response.url()).pathname === '/api/subagent.interrupt')
+    await stop.click()
+    expect(((await (await interruptResponse).json()) as {
+      result: { ok: boolean; value?: { accepted: boolean } }
+    }).result).toMatchObject({ ok: true, value: { accepted: true } })
+    // The addressed child stops through its own RPC, never the generic one.
+    expect(apiCalls.filter(path => path === '/api/session.cancel')).toEqual([])
+    await aborted
+
+    // Parked: the Activation stays resident and idle with the retained
+    // follow-up; the primary returns to Send without a new turn starting.
+    await expect.poll(() => scaffold.ctx.agents.get(childId)?.status, { timeout: 15_000 }).toBe('idle')
+    const child = scaffold.ctx.agents.get(childId)
+    expect(child).toBeDefined()
+    expect(child!.inbox.nextTurn).toHaveLength(1)
+    expect(child!.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1)
+    await page.getByRole('button', { name: 'Send message' }).waitFor({ timeout: 15_000 })
+
+    // Only the waking send resumes the parked queue, FIFO, to settlement.
+    await input.fill(WAKING)
+    await input.press('Enter')
+    await expect.poll(() => page.getByText(PARKED_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
+    await expect.poll(() => page.getByText(WAKING_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
+    await expect.poll(() => scaffold.ctx.agents.get(childId), { timeout: 60_000 }).toBeUndefined()
+
+    const loaded = await scaffold.ctx.sessionPersistence.load(childId)
+    const userTexts = loaded.events.flatMap(event => event.type === 'user/message'
+      && event.data.source.kind === 'user'
+      ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
+      : [])
+    expect(userTexts).toEqual([INITIAL, FOLLOWUP, WAKING])
+    const turnEndKinds = loaded.events
+      .filter(event => event.type === 'turn/end')
+      .map(event => event.data.reason.kind)
+    expect(turnEndKinds).toEqual(['aborted', 'completed', 'completed'])
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
+  it('keeps its snapshot inventory closed', async () => {
+    await assertFixtureInventory(SNAPSHOT_DIR, ['offline-composer.expected.md'])
+  })
+})
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 3fa6ba8905..606f257e56 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -68,6 +68,7 @@
     "tests/goal-bar.e2e.ts",
     "tests/subagent-conversation.e2e.ts",
     "tests/subagent-interrupt.e2e.ts",
+    "tests/subagent-interrupt-ui.e2e.ts",
     "tests/sidebar-subagent-activity.e2e.ts",
     "tests/bash-abort-row.e2e.ts",
     "tests/skill-tool-row.e2e.ts",
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 075fd686ea..659afcac4a 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -281,17 +281,22 @@ export class Session implements SessionFace {
 
   /**
    * Stop the active turn while the Host preserves pending inbox work; failures
-   * land in promptError (same error-strip display slot).
+   * land in promptError (same error-strip display slot). A continuable
+   * subagent address routes through `subagent.interrupt`, whose durable
+   * parent-address authority works without a live parent Agent; a one-shot
+   * address stays uncancellable (the UI offers no stop action, so this arm is
+   * defensive).
    * @returns the cancel result.
    */
   async cancel(): Promise<RpcResult<{ accepted: true }>> {
-    if (this.address !== undefined) {
+    const address = this.address
+    if (address !== undefined && address.mode === 'one-shot') {
       const result: RpcResult<{ accepted: true }> = {
         ok: false,
         error: {
           code: 'subagent-delivery-unavailable',
           message: 'subagent activation cancellation is unavailable',
-          details: { childSessionId: this.address.childSessionId },
+          details: { childSessionId: address.childSessionId },
         },
       }
       this.promptError = { op: 'stop', error: result.error }
@@ -300,7 +305,9 @@ export class Session implements SessionFace {
     }
     let result: RpcResult<{ accepted: true }>
     try {
-      result = (await this.api.sessions.cancel({ sessionId: this.sessionId })).result
+      result = address !== undefined
+        ? (await this.api.subagents.interrupt(address)).result
+        : (await this.api.sessions.cancel({ sessionId: this.sessionId })).result
     } catch (error) {
       result = transportError(error)
     }
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index b5400ecff9..5d5f292f92 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -639,7 +639,7 @@ describe('paging', () => {
 })
 
 describe('prompt and cancel errors', () => {
-  it('routes an addressed child through non-activating history and continuation prompt only', async () => {
+  it('routes an addressed child through non-activating history, continuation prompt, and interrupt only', async () => {
     const api = new FakeApiClient()
     const session = new Session(SID, api, {
       address: { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable' },
@@ -650,7 +650,7 @@ describe('prompt and cancel errors', () => {
     const cancelled = await session.cancel()
 
     expect(prompted).toEqual({ ok: true, value: { accepted: true } })
-    expect(cancelled).toMatchObject({ ok: false, error: { code: 'subagent-delivery-unavailable' } })
+    expect(cancelled).toEqual({ ok: true, value: { accepted: true } })
     expect(api.callsOf('subagent.history')).toEqual([
       { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable', maxMessages: 50 },
     ])
@@ -660,15 +660,37 @@ describe('prompt and cancel errors', () => {
         content: [{ type: 'text', text: '继续' }],
       },
     ])
+    expect(api.callsOf('subagent.interrupt')).toEqual([
+      { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable' },
+    ])
     expect(api.callsOf('session.history')).toEqual([])
     expect(api.callsOf('session.prompt')).toEqual([])
     expect(api.callsOf('session.cancel')).toEqual([])
+    // A successful interrupt leaves no stop error behind.
+    expect(session.getSnapshot().promptError).toBeNull()
     expect(session.getSnapshot().subagent).toEqual({
       address: { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable' },
       parentAvailable: true,
     })
   })
 
+  it('lands an interrupt business failure in promptError with op=stop', async () => {
+    const api = new FakeApiClient()
+    api.onSubagentInterrupt = () => Promise.resolve(err({
+      code: 'subagent-unauthorized', message: 'nope', details: { childSessionId: SID },
+    }) as never)
+    const session = new Session(SID, api, {
+      address: { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable' },
+      parentAvailable: true,
+    })
+    await session.open()
+    const cancelled = await session.cancel()
+    expect(cancelled).toMatchObject({ ok: false, error: { code: 'subagent-unauthorized' } })
+    expect(session.getSnapshot().promptError).toMatchObject({
+      op: 'stop', error: { code: 'subagent-unauthorized' },
+    })
+  })
+
   it('keeps one-shot history readable without exposing prompt or cancel transport', async () => {
     const api = new FakeApiClient()
     const session = new Session(SID, api, {
@@ -676,12 +698,16 @@ describe('prompt and cancel errors', () => {
     })
     await session.open()
     const prompted = await session.prompt([{ type: 'text', text: '继续' }], 'queue')
+    const cancelled = await session.cancel()
 
     expect(prompted).toMatchObject({ ok: false, error: { code: 'subagent-not-resumable' } })
+    expect(cancelled).toMatchObject({ ok: false, error: { code: 'subagent-delivery-unavailable' } })
     expect(api.callsOf('subagent.history')).toEqual([
       { parentSessionId: PARENT, childSessionId: SID, mode: 'one-shot', maxMessages: 50 },
     ])
     expect(api.callsOf('subagent.prompt')).toEqual([])
+    expect(api.callsOf('subagent.interrupt')).toEqual([])
+    expect(api.callsOf('session.cancel')).toEqual([])
   })
 
   it('sends content through session.prompt; composerPhase steps blank → engaging synchronously at send entry', async () => {
diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index 11e852a8b6..a67b816012 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -17,6 +17,7 @@ export const zh = {
   'placeholder.plan': PLAN_NEXT_ACTION_ZH,
   'placeholder.default': '给智能体发消息',
   'placeholder.unavailable': '会话不可用',
+  'placeholder.parentOffline': '父会话已离线，无法继续发送；仍可停止当前运行',
   'placeholder.hero': '描述你想要构建的内容',
   'placeholder.workspace': '选择一个工作区开始',
   'input.commands': '命令',
@@ -159,6 +160,7 @@ export const en = {
   'placeholder.plan': PLAN_NEXT_ACTION_EN,
   'placeholder.default': 'Message the agent',
   'placeholder.unavailable': 'Session unavailable',
+  'placeholder.parentOffline': 'Parent session offline; sending is unavailable but you can still stop the run',
   'placeholder.hero': 'Describe what you want to build',
   'placeholder.workspace': 'Choose a workspace to start',
   'input.commands': 'Commands',
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 7b24c09684..21abce0e38 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -83,11 +83,15 @@ export function InputBar({
   // (undefined = capability absent → the chip renders nothing).
   const permissions = useProjection('permissions')
 
+  // A continuable child without its live parent cannot accept human input,
+  // but its primary Stop below stays available while it runs.
+  const continuable = subagent?.address.mode === 'continuable'
+  const parentOffline = continuable && !subagent.parentAvailable
   // Queue cut 1: running input stays free; locked = session removed, the
-  // inert no-workspace state, or the machine faces absent (no session). The
-  // transient machine locks (adjudicating pending / submitting) render
-  // read-only — the draft stays visible and focused, keystrokes drop.
-  const disabled = removed || inert || !live || blocked !== undefined
+  // inert no-workspace state, the machine faces absent (no session), or a
+  // parent-offline continuable child. An owner block also disables input;
+  // adjudicating and submitting render read-only so the draft stays visible.
+  const disabled = removed || inert || !live || blocked !== undefined || parentOffline
   const locked = disabled
   // The model seat is the ONE control a block leaves live: every block this
   // contract has is cleared by choosing a model, so locking it too would leave
@@ -350,8 +354,9 @@ export function InputBar({
     if (el !== null) toggleCommandMenu?.(selectionOf(el))
   }
 
-  const ordinary = subagent === null
-  const stopping = running && ordinary
+  // Ordinary sessions and continuable children stop through the same primary
+  // action; one-shot children stay send-and-stop-free (read-only takeover).
+  const stopping = running && (subagent === null || continuable)
   const primaryLabel = stopping ? t('input.stop') : t('input.send')
   const onPrimary = (): void => {
     if (stopping) {
@@ -478,9 +483,11 @@ export function InputBar({
               disabled={locked}
               readOnly={machineBusy}
               data-phase={input?.phase ?? 'inert'}
-              placeholder={placeholder ?? (disabled
-                ? t('placeholder.unavailable')
-                : planActive ? t('placeholder.plan') : t('placeholder.default'))}
+              placeholder={placeholder ?? (parentOffline
+                ? t('placeholder.parentOffline')
+                : disabled
+                  ? t('placeholder.unavailable')
+                  : planActive ? t('placeholder.plan') : t('placeholder.default'))}
               rows={2}
               onChange={onChange}
               onKeyDown={onKeyDown}
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index 47791a6090..89f0d0a5f4 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -143,7 +143,8 @@ function bench(over?: BenchOptions) {
   }
   const view = render(<InputBar {...props} />)
   const textarea = view.container.querySelector('textarea')!
-  const stopping = over?.running === true && over.subagent === undefined
+  const stopping = over?.running === true
+    && (over.subagent === undefined || over.subagent.address.mode === 'continuable')
   const button = view.container.querySelector<HTMLButtonElement>(
     `button[aria-label="${stopping ? '停止生成' : '发送消息'}"]`,
   )!
@@ -250,8 +251,8 @@ describe('running and lock semantics (queue cut 1)', () => {
     expect(ctrl.sink).toHaveBeenCalledWith('also queue', 'queue')
   })
 
-  it('running subagent primary admits a follow-up instead of exposing Stop', () => {
-    const { button, sink, stop } = bench({
+  it('running continuable subagent turns the same primary into Stop while typing stays free', () => {
+    const { button, textarea, sink, stop } = bench({
       running: true,
       draft: '后续消息',
       subagent: {
@@ -263,23 +264,54 @@ describe('running and lock semantics (queue cut 1)', () => {
         parentAvailable: true,
       },
     })
-    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    // One primary action only: Send switched to Stop, no side-by-side interrupt.
+    expect(button.getAttribute('aria-label')).toBe('停止生成')
+    expect(textarea.disabled).toBe(false)
     fireEvent.click(button)
+    expect(stop).toHaveBeenCalledTimes(1)
+    expect(sink).not.toHaveBeenCalled()
+    // Enter still queues the follow-up while the primary offers Stop.
+    fireEvent.keyDown(textarea, { key: 'Enter' })
     expect(sink).toHaveBeenCalledWith('后续消息', 'queue')
-    expect(stop).not.toHaveBeenCalled()
+  })
 
-    const empty = bench({
+  it('parent-offline running continuable locks the input but keeps the same primary Stop usable', () => {
+    const { button, textarea, stop, view } = bench({
       running: true,
+      draft: '',
       subagent: {
         address: {
           parentSessionId: 'parent' as SessionId,
           childSessionId: SID,
           mode: 'continuable',
         },
+        parentAvailable: false,
+      },
+    })
+    expect(textarea.disabled).toBe(true)
+    expect(textarea.placeholder).toBe('父会话已离线，无法继续发送；仍可停止当前运行')
+    expect((view.getByLabelText('命令') as HTMLButtonElement).disabled).toBe(true)
+    expect(button.getAttribute('aria-label')).toBe('停止生成')
+    expect(button.disabled).toBe(false)
+    fireEvent.click(button)
+    expect(stop).toHaveBeenCalledTimes(1)
+  })
+
+  it('running one-shot subagent never exposes Stop', () => {
+    const { button, stop } = bench({
+      running: true,
+      draft: '不可停止',
+      subagent: {
+        address: {
+          parentSessionId: 'parent' as SessionId,
+          childSessionId: SID,
+          mode: 'one-shot',
+        },
         parentAvailable: true,
       },
     })
-    expect(empty.button.disabled).toBe(true)
+    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(stop).not.toHaveBeenCalled()
   })
 
   it('keeps both running subagent Enter gestures on Queue transport', () => {
diff --git a/packages/client/ui-subagent/README.i18n.yaml b/packages/client/ui-subagent/README.i18n.yaml
index 8bb19b2ba2..d1b0852953 100644
--- a/packages/client/ui-subagent/README.i18n.yaml
+++ b/packages/client/ui-subagent/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/client/ui-subagent/README.md
-README.md: cb210b219a8c66985eb4e1370468372eed9614b4
-README.zh.md: 857e92d05a7ed2d0df9398acc9698db13b0c6eb2
+README.md: de55963bbe356e18a4e2b653be823cc5015c1bb7
+README.zh.md: ce4244db094bb8b602b854289ec000477bf45f0b
diff --git a/packages/client/ui-subagent/README.md b/packages/client/ui-subagent/README.md
index cb210b219a..de55963bbe 100644
--- a/packages/client/ui-subagent/README.md
+++ b/packages/client/ui-subagent/README.md
@@ -6,7 +6,7 @@ Web subagent feature owner: contributes the lazily expandable catalog tree to `c
 
 The header action reads `subagentsByParent` and session summaries through the standard `useSessions` hook. After a non-empty direct catalog arrives, its trigger counts the complete subagent-only descendant lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. The compact tree remains direct-catalog authoritative: continuable and one-shot rows display mode plus `running`/`inactive` activity and an optional log-backed title, while the trailing column stacks total durable provider usage above active-turn duration. Token totals sum the four disjoint `tokenUsage` buckets. Visual duration stays exact to the second below one day, then uses at most two adjacent units—days/hours, approximate months/days, or approximate years/months—while hover and the accessible name retain the exact day/hour/minute/second value. Duration sums completed `subagentTiming` turns, advances once per second only for an open turn on a running child, and freezes after the child becomes inactive; an interrupted open turn is bounded by its same-cut `active.through`, never by newer session metadata. An unlabeled one-shot row falls back to its session id, while corrupt, unsupported, or unavailable rows remain readable but disabled. Each healthy row's `hasChildren` hint determines disclosure before interaction, so known leaves never show an arrow; a catalog level reserves the disclosure column only when at least one healthy row is a branch, allowing branchless levels to start at the leading status marker. Expanding a branch immediately reserves one disabled loading row per known direct descendant, then lazily replaces them with that child's authoritative catalog. Every visible branch is reported to the runtime so membership frames cause a debounced refresh only where the tree is being consumed. Selecting any depth calls `SessionsService.openSubagent()` with the row's exact `{parentSessionId, childSessionId, mode}` address. Component-local state owns tree visibility, expanded branches, keyboard focus, and the running-duration clock. ArrowRight/ArrowLeft expand and collapse branches; ArrowUp/ArrowDown, Home, End, and Escape navigate or close the tree; closing returns focus to the trigger. Styling uses tokens only.
 
-A one-shot child always elects a read-only composer that identifies the transcript as a completed execution record. A continuable child does so only when its exact parent is unavailable, with copy explaining the recovery path. A continuable child with a live parent keeps the ordinary input chrome, whose Session routes through `subagent.prompt`; running input remains Send because every follow-up joins the child's FIFO inbox, and addressed sessions never expose Stop. This package never receives host context or calls a model-facing tool. The catalog and composer behavior are specified by the [Web subagent conversations Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md).
+A one-shot child always elects a read-only composer that identifies the transcript as a completed execution record. A continuable child does so only when its exact parent is unavailable and the child is not running, with copy explaining the recovery path; while such a child still runs, the selector yields to the ordinary composer, whose input is disabled but whose primary Stop stays usable, and the takeover returns once it stops. A continuable child with a live parent keeps the ordinary input chrome, whose Session routes prompts through `subagent.prompt`: typing stays free while the child runs because every follow-up joins the child's FIFO inbox, and the single primary action follows the ordinary convention — Send while idle, Stop while running, routed through `subagent.interrupt`. This package never receives host context or calls a model-facing tool. The catalog and composer behavior are specified by the [Web subagent conversations Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) and the [current-turn interrupt Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md).
 
 Subagent-origin Session rows are omitted from the ordinary sidebar, so the parent header catalog is their navigation entry point. Ordinary forks remain in the sidebar.
 
@@ -30,5 +30,5 @@ Append-only. This package never edits earlier request tokens.
 
 ## Known Limitations and Deferred Work
 
-- **The catalog has no durable outcome** — activity and timing do not distinguish completion, failure, or cancellation, and the UI exposes neither Activation identity nor an authority-safe cancel button.
+- **The catalog has no durable outcome** — activity and timing do not distinguish completion, failure, or cancellation, and the UI exposes no Activation identity; stopping is limited to the composer's current-turn Stop for a running continuable child.
 - **`@` references remain display-title text** — duplicate or renamed labels are ambiguous, so they intentionally do not acquire continuation semantics.
diff --git a/packages/client/ui-subagent/README.zh.md b/packages/client/ui-subagent/README.zh.md
index 857e92d05a..ce4244db09 100644
--- a/packages/client/ui-subagent/README.zh.md
+++ b/packages/client/ui-subagent/README.zh.md
@@ -6,7 +6,7 @@ Web subagent 功能 owner：向 `conversation.session.header.actions` 贡献可
 
 页头操作通过标准 `useSessions` 钩子读取 `subagentsByParent` 与会话摘要。非空直接目录到达后，其触发器会统计仅含 subagent 的完整后代谱系，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。紧凑树仍以直接目录为权威依据：可继续和 one-shot 行会显示 mode、`running`／`inactive` 活动状态和由日志支撑的可选 title，尾随列则在上行显示提供方的持久化 token 用量总计，在下行显示活跃轮次耗时。token 用量总计为四个互不重叠的 `tokenUsage` 桶之和。视觉耗时在不足一天时精确到秒，达到一天后则最多使用两个相邻单位——天／小时、近似月份／天或近似年份／月份——而悬停信息与无障碍名称会保留精确的天／小时／分钟／秒数值。耗时会累加已完成的 `subagentTiming` 轮次，仅在运行中 child 存在未结束轮次时每秒递增一次，并在 child 变为 inactive 后冻结；被中断的未结束轮次以其同一切面的 `active.through` 为上界，绝不使用更新的会话元数据。没有 label 的 one-shot 行会回退到其会话 id，而损坏、不受支持或不可用的行仍保持可读但禁用。每个健康行的 `hasChildren` 提示会在交互前决定是否显示展开控件，因此已知叶子节点从不显示箭头；每层目录仅在其中至少一个健康行是分支时才预留展开列，使完全不含分支的层级能从最前面的状态标记开始。展开分支时，会立即为每个已知直接后代预留一行禁用的加载行，随后再用该 child 的权威目录懒加载结果替换这些占位行。每个可见分支都会上报给运行时，使成员帧只在树正被消费的位置触发去抖动刷新。选择任意深度的条目都会使用该行的确切地址 `{parentSessionId, childSessionId, mode}` 调用 `SessionsService.openSubagent()`。组件局部状态负责树的可见性、已展开分支、键盘焦点与运行中耗时时钟。ArrowRight／ArrowLeft 展开和折叠分支；ArrowUp／ArrowDown、Home、End 与 Escape 用于导航或关闭树；关闭后焦点返回触发器。样式只使用 token。
 
-one-shot child 始终选用只读编辑器，并将 transcript（文本记录）说明为已完成的执行记录。可继续 child 仅在其确切 parent 不可用时选用只读编辑器，并以文案说明恢复路径。确切 parent 存活时，可继续 child 保留普通输入 chrome，其会话会通过 `subagent.prompt` 路由；child 运行期间，输入操作仍为 Send，因为每条后续消息都会进入 child 的 FIFO inbox，且已寻址会话绝不公开 Stop。本包绝不接收宿主上下文，也不调用面向模型的工具。目录与编辑器行为由 [Web subagent 对话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) 规定。
+one-shot child 始终选用只读编辑器，并将 transcript（文本记录）说明为已完成的执行记录。可继续 child 仅在其确切 parent 不可用且 child 未在运行时选用只读编辑器，并以文案说明恢复路径；此类 child 仍在运行期间，selector 会让位给普通编辑器——其输入区被禁用，但 primary Stop 保持可用，停止后只读替代恢复。确切 parent 存活时，可继续 child 保留普通输入 chrome，其会话通过 `subagent.prompt` 路由提示词：child 运行期间输入保持自由，因为每条后续消息都会进入 child 的 FIFO inbox，而唯一的 primary 操作遵循普通约定——空闲时为 Send，运行时为 Stop，经由 `subagent.interrupt` 路由。本包绝不接收宿主上下文，也不调用面向模型的工具。目录与编辑器行为由 [Web subagent 对话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) 与[当前轮次中断 Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md) 规定。
 
 普通侧边栏会省略带 subagent origin 的会话行，因此 parent 页头目录是它们的导航入口。普通 fork 仍保留在侧边栏中。
 
@@ -30,5 +30,5 @@ one-shot child 始终选用只读编辑器，并将 transcript（文本记录）
 
 ## 已知限制与暂缓事项
 
-- **目录没有持久化结果**：活动状态与计时无法区分完成、失败或取消，且 UI 既不公开 Activation 身份，也不公开符合授权边界的取消按钮。
+- **目录没有持久化结果**：活动状态与计时无法区分完成、失败或取消，且 UI 不公开 Activation 身份；停止能力仅限编辑器上针对运行中可继续 child 的当前轮次 Stop。
 - **`@` 引用仍是显示标题文本**：重复或改名后的 label 会有歧义，因此它们刻意不获得继续执行语义。
diff --git a/packages/client/ui-subagent/src/client/index.ts b/packages/client/ui-subagent/src/client/index.ts
index 95626cbaf1..73c7f9a6cc 100644
--- a/packages/client/ui-subagent/src/client/index.ts
+++ b/packages/client/ui-subagent/src/client/index.ts
@@ -43,7 +43,11 @@ function selectReadOnlySubagent(owner: ComposerChainProps): SubagentReadOnlyMatc
   const subagent = owner.session?.subagent
   if (subagent === undefined || subagent === null) return null
   if (subagent.address.mode === 'one-shot') return { reason: 'one-shot' }
-  return subagent.parentAvailable ? null : { reason: 'parent-unavailable' }
+  if (subagent.parentAvailable) return null
+  // A RUNNING parent-offline continuable child keeps the default composer:
+  // its input is disabled there, but the same primary Stop stays available so
+  // the child can be interrupted. Once it stops, this takeover returns.
+  return owner.session?.running === true ? null : { reason: 'parent-unavailable' }
 }
 
 /**
diff --git a/packages/client/ui-subagent/tests/browser-plugin.spec.ts b/packages/client/ui-subagent/tests/browser-plugin.spec.ts
index 09221e1e94..861546c19c 100644
--- a/packages/client/ui-subagent/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-subagent/tests/browser-plugin.spec.ts
@@ -161,19 +161,26 @@ describe('apply', () => {
     const select = composerEntry.select as (owner: ComposerChainProps) => SubagentReadOnlyMatch | null
     const owner = (
       subagent: ConversationSnapshot['subagent'] | undefined,
+      running = false,
     ): ComposerChainProps => ({
       interactions: [],
       session: subagent === undefined
         ? undefined
-        : ({ subagent } as unknown as ConversationSnapshot),
+        : ({ subagent, running } as unknown as ConversationSnapshot),
     })
     expect(select(owner(undefined))).toBeNull()
     expect(select(owner(null))).toBeNull()
     expect(select(owner({ address: { ...address, mode: 'one-shot' }, parentAvailable: true })))
       .toEqual({ reason: 'one-shot' })
+    // One-shot stays read-only even while running: it has no stop action.
+    expect(select(owner({ address: { ...address, mode: 'one-shot' }, parentAvailable: true }, true)))
+      .toEqual({ reason: 'one-shot' })
     expect(select(owner({ address, parentAvailable: true }))).toBeNull()
     expect(select(owner({ address, parentAvailable: false })))
       .toEqual({ reason: 'parent-unavailable' })
+    // A RUNNING parent-offline continuable yields the default composer, whose
+    // disabled input still carries the primary Stop; stopped, it takes back over.
+    expect(select(owner({ address, parentAvailable: false }, true))).toBeNull()
   })
 })
 
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 1997f0ea47..1a8ef6508a 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -55,6 +55,7 @@
     "apps/web/tests/produced-file-mentions.e2e.ts",
     "apps/web/tests/subagent-conversation.e2e.ts",
     "apps/web/tests/subagent-interrupt.e2e.ts",
+    "apps/web/tests/subagent-interrupt-ui.e2e.ts",
     "apps/web/tests/sidebar-subagent-activity.e2e.ts",
     "apps/web/tests/bash-abort-row.e2e.ts",
     "apps/web/tests/skill-tool-row.e2e.ts",

From 4b29f9ca7a7a72f1f6289717d5460ffff8b690cb Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 16:13:54 +0800
Subject: [PATCH 277/516] test(web): refresh interrupt UI golden after master
 merge

---
 .../snapshots/subagent-interrupt/offline-composer.expected.md  | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
index 6ea7b83bff..a0baa9a44f 100644
--- a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
+++ b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
@@ -9,9 +9,6 @@
 - text: Explain event sourcing in one sentence. {{clock}}
 - button "Copy":
   - img
-- button "Branch into a new conversation" [disabled]:
-  - img
-- text: Available only on the last message of a completed turn
 - button "Context injection @deepseek-ai/dsh-system-prompt":
   - img
   - img

From d769d3cbb7c32cc4f1a4ff32cf5b30af96ea9f34 Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 6 Aug 2026 13:46:55 +0800
Subject: [PATCH 278/516] feat(subagent): let ancestors interrupt descendants
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

interrupt_agent(agent_id) passes the calling agent as the ancestor
authority for ctx.subagents.interrupt(); the service verifies live
registry identity and recorded lineage, so a direct child or deeper
descendant stops with the same generic parameter while send_message keeps
its exact-direct-parent authority.

Discovery: list_agents gains an optional scope. descendants walks the new
SubagentService.listDescendants() — one lineage trace flattened in stable
pre-order across ordinary and one-shot intermediates, each entry carrying
its verified parentId and depth — and every status now comes from the
live Agent registry (running/idle/complete).

Refs #1535
---
 ...subagent-catalog-and-list-agents.i18n.yaml |   4 +-
 ...urable-subagent-catalog-and-list-agents.md |   8 +-
 ...ble-subagent-catalog-and-list-agents.zh.md |   8 +-
 ...6-continuable-subagent-interrupt.i18n.yaml |   4 +-
 ...26-08-06-continuable-subagent-interrupt.md |   6 +-
 ...08-06-continuable-subagent-interrupt.zh.md |   6 +-
 apps/web/tests/shipped-composition.e2e.ts     |   1 +
 docs/cordis-catalog/services.md               |  19 +-
 docs/core-data-structures/subagent.i18n.yaml  |   4 +-
 docs/core-data-structures/subagent.md         |  23 +-
 docs/core-data-structures/subagent.zh.md      |  23 +-
 .../system-prompt.expected.md                 |  21 +-
 .../tool-schemas.expected.json                |  31 ++-
 .../both-mode-turn/tool-schemas.expected.json |  31 ++-
 .../code-mode-turn/system-prompt.expected.md  |  21 +-
 .../lsp-definition/tool-schemas.expected.json |  31 ++-
 .../pty-tools/tool-schemas.expected.json      |  31 ++-
 .../tool-schemas.expected.json                |  31 ++-
 .../tool-schemas.1.expected.json              |  31 ++-
 .../tool-schemas.1.expected.json              |  31 ++-
 .../tool-schemas.1.expected.json              |  31 ++-
 .../text-turn/tool-schemas.expected.json      |  31 ++-
 .../web-fetch/tool-schemas.expected.json      |  31 ++-
 .../cordis/tool-cordis/src/api-catalog.ts     |   8 +
 .../core/tools/tests/gen-tool-catalog.spec.ts |   3 +-
 packages/subagent/subagent/README.i18n.yaml   |   4 +-
 packages/subagent/subagent/README.md          |   5 +-
 packages/subagent/subagent/README.zh.md       |   7 +-
 packages/subagent/subagent/src/index.ts       |  31 ++-
 .../subagent/subagent/src/list-children.ts    | 159 ++++++++++++--
 .../subagent/tests/list-children.spec.ts      | 194 +++++++++++++++++
 .../tool-subagent-control/README.i18n.yaml    |   4 +-
 .../subagent/tool-subagent-control/README.md  |  28 ++-
 .../tool-subagent-control/README.zh.md        |  28 ++-
 .../tool-subagent-control/src/index.ts        |  56 ++++-
 .../tool-subagent-control/src/list-agents.ts  | 124 ++++++++---
 .../tests/list-agents.spec.ts                 | 165 +++++++++++++-
 .../tests/tool-subagent-control.spec.ts       | 202 +++++++++++++++++-
 scripts/gen-cordis-catalog.ts                 |   1 +
 scripts/gen-tool-catalog.ts                   |   5 +-
 scripts/type-equiv.manifest.json              |   5 +
 41 files changed, 1325 insertions(+), 162 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
index 2acc3dd5b5..c525cc8f43 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.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 .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
-2026-07-22-durable-subagent-catalog-and-list-agents.md: b96d6e1dd36c58af67c8e93e62515672790ad009
-2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: 856bac615db84bfe2898ec0838094c6bc29f77b2
+2026-07-22-durable-subagent-catalog-and-list-agents.md: 8337a926238bf7fc4395896fcd4ca180c9c1ac1c
+2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: bcf2895a9a69c8cff949788c78158bfccd198c5c
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
index b96d6e1dd3..8337a92623 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
@@ -23,7 +23,7 @@ Parent-to-child enumeration is a service capability with consumer-specific proje
 - report corpus activity separately as `running` or `inactive`, without implying completion or resumability;
 - return every resulting child in stable `createdAt` ascending, child-id ascending order.
 
-Every ordinary local start receives a `one-shot` descriptor with an optional caller-owned display label, while the continuation manager persists a labeled `continuable` descriptor containing its additional reconstruction fields. The model-facing delegation tool already owns a short `description` and supplies it for one-shot display; lower-level callers such as workflows need not invent presentation metadata. The model-facing `list_agents` adapter filters the service result to continuable children and maps `inactive` to its existing `complete` presentation; a UI can consume both modes and choose an id-based fallback for unlabeled one-shot history. Descriptor persistence, by-id lookup, direct-parent authorization, and provider-independent cold resume remain owned by the implemented Activation contract. Listing consumes those facts but cannot weaken them or invent a second descriptor representation.
+Every ordinary local start receives a `one-shot` descriptor with an optional caller-owned display label, while the continuation manager persists a labeled `continuable` descriptor containing its additional reconstruction fields. The model-facing delegation tool already owns a short `description` and supplies it for one-shot display; lower-level callers such as workflows need not invent presentation metadata. The model-facing `list_agents` adapter filters the service result to continuable children and refines status through the live Agent registry (`running`/`idle`/`complete`); a UI can consume both modes and choose an id-based fallback for unlabeled one-shot history. Descriptor persistence, by-id lookup, direct-parent authorization, and provider-independent cold resume remain owned by the implemented Activation contract. Listing consumes those facts but cannot weaken them or invent a second descriptor representation.
 
 ### Enumeration decision
 
@@ -52,7 +52,7 @@ If measured scale later requires an index, that index is derived state: session
 
 A valid descriptor produces one child entry, a per-child inspection failure produces one diagnostic entry, and a candidate without a descriptor produces no entry. `mode` is durable creation policy; `activity` is a process-local corpus snapshot. Activity is neither `AgentStatus`, the manager's internal Activation state, nor a durable outcome, and the result does not expose the internal `createdAt` sorting key. Exact Activation states and durable outcomes such as successful completion, failure, cancellation, and stop reason require a separate durable activation record and are outside this feature.
 
-The model-facing `list_agents` tool takes no arguments, derives `parentSessionId` from the current execution Agent, and is a thin adapter in `@deepseek-ai/dsh-tool-subagent-control`. It keeps diagnostics, drops `one-shot` child entries, maps a continuable child's `running` activity to `running` and `inactive` activity to `complete`, then renders `<id> [<status>] — <label>` or `<id> [diagnostic: <reason>]` in the surviving trace order. An empty projection renders `(no subagents)`.
+The model-facing `list_agents` tool takes one optional `scope: 'children' | 'descendants'` argument, derives the root id from the current execution Agent, and is a thin adapter in `@deepseek-ai/dsh-tool-subagent-control`. It keeps diagnostics, drops `one-shot` child entries, derives status from the live Agent registry — `running` for an active driver, `idle` for a resident Agent between turns, and `complete` when no live Agent remains — then renders `<id> [<status>] — <label>` or `<id> [diagnostic: <reason>]` in stable catalog order. The `descendants` scope reads `SubagentService.listDescendants(rootSessionId)`, which flattens the complete tree from one live-preferred corpus in stable pre-order, traverses ordinary and one-shot intermediates so deeper continuable agents are discovered, revalidates each cold candidate against its enumerated lifecycle, and adds `parentId`/`depth` to every entry. The tool inserts ` parent=<id> depth=<n>` before the label; `parent` is the durable direct-parent session id and may name an omitted ordinary session. For the current caller, only depth-1 child rows are `send_message` candidates, while deeper child rows may be selected for `interrupt_agent` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Discovery is a hint only — follow-up authority stays exact-direct-parent, and interrupt authority stays with the service's live-lineage check. An empty projection renders `(no subagents)`.
 
 Diagnostics use three fixed reasons. Malformed event surfaces, conflicting headers discovered during an exact child load, a read result whose immutable header differs from the traced candidate or no longer names the requested direct parent, a target that is no longer the located descriptor event, malformed descriptor content, and multiple descriptor events map to `corrupt`. An unknown descriptor version maps to `unsupported`. `SESSION_QUERY_SESSION_NOT_FOUND`, `SESSION_QUERY_EVENT_NOT_FOUND`, and `SESSION_QUERY_PERSISTENCE_FAILED` from a per-child read map to `unavailable`. This phase boundary is intentional: a persistence outage during the initial trace fails the operation, while the same outage beginning during candidate reads may produce one identical `unavailable` diagnostic per affected child; the first version neither coalesces those diagnostics nor promotes them to a global failure. A missing descriptor is instead a non-subagent exclusion without a diagnostic. Configuration/window errors and unrecognized failures are not child diagnostics and propagate as operation failures. Each diagnostic identifies the child id and reason without exposing model-hidden descriptor content; the candidate is omitted while healthy siblings remain visible. Sessions outside the trace's direct descendants are never read and produce no diagnostic.
 
@@ -93,8 +93,8 @@ The first version has no child deletion operation. If later product behavior del
 ## Testing
 
 - `packages/subagent/subagent/tests/service.spec.ts` pins descriptor v2 parsing for both modes and proves an unlabeled raw start resolves a one-shot descriptor before provider dispatch. `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` proves the local driver appends that descriptor inside the initial turn, returns the published id when cancellation lands in the factory-to-run handoff, and keeps result and handle-disposal failures on separate channels. Delegation-tool tests pin propagation of their existing display description and preserve independent result and disposal diagnostics.
-- `packages/subagent/subagent/tests/list-children.spec.ts` pins the current read path against a real composition of the session store, JSONL persistence, spawn/fork providers, the subagent service, and the projection registry — no query service — keylessly: live-only listing without persistence; loud `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` even with zero children; the three-rung ladder (a live child never inspected, a cold child inspected exactly once, and the cache-hit, absent-key, absent-service, and poisoned-row second-rung cases); last-wins over multiple descriptors; malformed payloads and unknown versions diagnosed as `corrupt`; a failed cold inspection as one `unavailable` diagnostic retried on the next listing; a fork seed's ancestor descriptor listed under that identity; foreign-unit fold failures contained per child as `corrupt` on both the live and cold paths; `createdAt`-then-id ordering without ordinary forks; provider absence without child omission; compacted/uncompacted twins listing identically; a persisted-listing failure failing the whole enumeration; cancellation normalized to stable `CANCELLED`; and typed stable error codes. A companion spec (retired together with the query-backed read path) rejected eager evaluation of the optional session-query runtime while importing the ordinary subagent surface.
-- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` pins the `list_agents` schema (no parameters), the continuable-only projection that omits a healthy one-shot sibling while preserving diagnostics, the fixed child/diagnostic/empty text forms, an end-to-end settled-child listing with its durable label, forwarding of the tool cancellation signal, the no-agent rejection, the narrowed load requirement without `sessionQuery`, and HMR disposal.
+- `packages/subagent/subagent/tests/list-children.spec.ts` pins the current read path against a real composition of the session store, JSONL persistence, spawn/fork providers, the subagent service, and the projection registry — no query service — keylessly: live-only listing without persistence; loud `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` even with zero children; the three-rung ladder (a live child never inspected, a cold child inspected exactly once, and the cache-hit, absent-key, absent-service, and poisoned-row second-rung cases); last-wins over multiple descriptors; malformed payloads and unknown versions diagnosed as `corrupt`; a failed cold inspection as one `unavailable` diagnostic retried on the next listing; a fork seed's ancestor descriptor listed under that identity; foreign-unit fold failures contained per child as `corrupt` on both the live and cold paths; `createdAt`-then-id ordering without ordinary forks; provider absence without child omission; compacted/uncompacted twins listing identically; a persisted-listing failure failing the whole enumeration; cancellation normalized to stable `CANCELLED`; typed stable error codes; and descendant listing's iterative stable pre-order, traversal through ordinary and one-shot intermediates, positioned diagnostics, lifecycle revalidation, and cancellation. A companion spec (retired together with the query-backed read path) rejected eager evaluation of the optional session-query runtime while importing the ordinary subagent surface.
+- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` pins the `list_agents` schema (one optional `scope` enum), the continuable-only projection that omits a healthy one-shot sibling while preserving diagnostics, registry-derived child/diagnostic/empty text forms, an end-to-end settled-child listing with its durable label, the descendants scope's pre-order parent/depth annotations across a live waiting branch, cancellation forwarding to both scopes, the no-agent rejection, the `agents` load requirement without `sessionQuery`, and HMR disposal.
 - The keyless ACP snapshot scenario `subagent-list-agents` (examples/acp-agent) fences its second parent turn on a snapshot-only `subagent/end` marker, then executes `list_agents` for real against the subagent service, the projection registry, and JSONL persistence, rendering `<id> [complete] — <label>`.
 - The keyless snapshot scenario `subagent-diagnostic` (examples/headless-agent) pins the current listing's model-visible diagnostic classification, including a descriptor-less settled child surfacing as a `corrupt` diagnostic.
 - The keyless ACP snapshot scenario `subagent-published-run-failure` publishes a real one-shot child, injects independent run-result and handle-disposal failures, and preserves both diagnostics in the parent tool result.
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
index 856bac615d..bcf2895a9a 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
@@ -23,7 +23,7 @@ parent 到 child 的枚举是一项带消费方专用投影的服务功能。`Su
 - 将语料活动状态单独报告为 `running` 或 `inactive`，但不暗示已完成或可恢复；
 - 按 `createdAt` 升序、再按 child id 升序稳定返回所有结果 child。
 
-每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并将 `inactive` 映射为其现有的 `complete` 表示；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 契约负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
+每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`）；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 契约负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
 
 ### 枚举决策
 
@@ -52,7 +52,7 @@ subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务
 
 有效描述符产生一个 child 条目，逐 child 检查失败产生一个 diagnostic 条目，缺少描述符的候选不产生条目。`mode` 是持久化创建策略；`activity` 是进程本地语料快照。活动状态既不是 `AgentStatus`、管理器内部的 Activation 状态，也不是持久化结果，结果不公开内部 `createdAt` 排序键。成功完成、失败、取消和停止原因等精确 Activation 状态与持久化结果需要单独的持久化激活记录，不在本功能范围内。
 
-面向模型的 `list_agents` 工具不接受参数，从当前正在执行的 Agent 推导 `parentSessionId`，并作为 `@deepseek-ai/dsh-tool-subagent-control` 中的轻量适配器。它保留 diagnostic，丢弃 `one-shot` child 条目，将可继续 child 的 `running` 活动状态映射为 `running`、`inactive` 活动状态映射为 `complete`，然后按剩余的追踪顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。空投影渲染为 `(no subagents)`。
+面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并作为 `@deepseek-ai/dsh-tool-subagent-control` 中的轻量适配器。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 读取 `SubagentService.listDescendants(rootSessionId)`：它从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
 
 diagnostic 使用三种固定原因。格式错误的事件 surface、精确加载 child 时发现的 header 冲突、读取结果中的不可变 header 与追踪到的候选不一致或不再指向请求的直接 parent、读取目标不再是先前定位的描述符事件、格式错误的描述符内容和多个描述符事件映射为 `corrupt`。未知描述符版本映射为 `unsupported`。逐 child 读取产生的 `SESSION_QUERY_SESSION_NOT_FOUND`、`SESSION_QUERY_EVENT_NOT_FOUND` 和 `SESSION_QUERY_PERSISTENCE_FAILED` 映射为 `unavailable`。这项阶段边界是有意为之：初始追踪期间发生持久化故障会让操作失败，而同一故障如果始于候选读取期间，可能会让每个受影响的 child 分别产生一条相同的 `unavailable` diagnostic；第一版既不合并这些 diagnostic，也不会把它们提升为全局失败。缺少描述符则作为非 subagent 排除，且不产生 diagnostic。配置错误、窗口错误和未识别的失败不属于 child diagnostic，会作为操作失败继续向上传播。每条 diagnostic 都标识 child id 及原因，不暴露对模型隐藏的描述符内容；系统会排除该候选，而其他健康的 sibling 仍然可见。系统绝不会读取不属于追踪结果直接后代的会话，也不会为它们产生 diagnostic。
 
@@ -93,8 +93,8 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 ## 测试
 
 - `packages/subagent/subagent/tests/service.spec.ts` 固定两种模式下的描述符 v2 解析，并证明无标签的底层启动会在分发给提供方之前解析出一次性描述符。`packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 证明本地驱动会在初始轮次内追加该描述符，在取消落入工厂到 run 的交接窗口时返回已发布 id，并让结果与句柄释放失败保留在独立通道中。委派工具测试固定其现有显示说明的传递，并保留相互独立的结果与 dispose diagnostic。
-- `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；以及带类型的稳定错误码。一个伴随规格(已随查询式读取路径一起退役)曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
-- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（无参数）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、child／diagnostic／空结果的固定文本形式、带持久化 label 的已结束 child 端到端列表、工具取消信号的转发、无调用 agent 时的拒绝、收窄后的加载要求（不再注入 `sessionQuery`），以及 HMR dispose。
+- `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；带类型的稳定错误码；以及后代列表的迭代式稳定 pre-order、穿过普通与一次性中间节点、带位置 diagnostic、生命周期复验与取消。一个伴随规格(已随查询式读取路径一起退役)曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
+- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（一个可选 `scope` 枚举）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、由注册表推导的 child／diagnostic／空结果文本形式、带持久化 label 的已结束 child 端到端列表、descendants scope 在在线 waiting 分支上的 pre-order parent/depth 注释、两个 scope 的取消信号转发、无调用 agent 时的拒绝、要求 `agents` 但不再注入 `sessionQuery` 的加载契约，以及 HMR dispose。
 - 无密钥 ACP 快照场景 `subagent-list-agents`（examples/acp-agent）使用仅限快照的 `subagent/end` 标记为第二个 parent 轮次设置边界，随后针对 subagent 服务、投影注册表和 JSONL 持久化真实执行 `list_agents`，渲染 `<id> [complete] — <label>`。
 - 无密钥快照场景 `subagent-diagnostic`（examples/headless-agent）钉住现行列表的模型可见诊断分类，包括无描述符的定局 child 以 `corrupt` diagnostic 出现。
 - 无密钥 ACP 快照场景 `subagent-published-run-failure` 会发布一个真实的一次性 child，注入相互独立的 run result 与 handle dispose 失败，并在 parent 工具结果中保留两项 diagnostic。
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 5cf5601fc0..dfdc2338ae 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 1792d4c6d25858c861be0ff920206d0d4e684f41
-2026-08-06-continuable-subagent-interrupt.zh.md: ff9887481d1ded2743c7c8f9f162413fb6581d70
+2026-08-06-continuable-subagent-interrupt.md: 0f663ac6a58b9c3d658aa572ca2fea18dbef6449
+2026-08-06-continuable-subagent-interrupt.zh.md: b8a5b557b73b2845e3c0b1dabdec0163f56eca48
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 1792d4c6d2..0f663ac6a5 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -39,8 +39,10 @@ A human or ancestor can stop a runaway continuable turn without losing the child
 
 The address-only RPC exposes one bit of live residency: an absent target is accepted while a live target under a mismatched parent returns `subagent-unauthorized`. The single-user local Host trust model accepts that observability; a future multi-principal Host must revisit both authority and response indistinguishability.
 
-The Web surface reuses the existing primary Send/Stop toggle rather than adding a second action: the client `Session.cancel()` routes a continuable address through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep `session.cancel`), and a running parent-offline continuable child keeps the default composer with disabled input so that same primary Stop remains reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract). The model-facing `interrupt_agent` tool builds on this primitive in the stacked follow-up PR for issue #1535.
+The Web surface reuses the existing primary Send/Stop toggle rather than adding a second action: the client `Session.cancel()` routes a continuable address through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep `session.cancel`), and a running parent-offline continuable child keeps the default composer with disabled input so that same primary Stop remains reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract).
+
+The model-facing `interrupt_agent(agent_id)` tool in `dsh-tool-subagent-control` passes `exec.agent` as the `ancestor` authority and adds none of its own: the core primitive verifies live registry identity and recorded lineage, so the tool can name a direct child or a deeper descendant with the same generic `agent_id` parameter — deliberately not `subagent_id`, which would imply direct children only. Discovery rides `list_agents({ scope: 'descendants' })` over the new `SubagentService.listDescendants()` one-trace pre-order walk with verified `parentId`/`depth` per entry ([durable catalog note](2026-07-22-durable-subagent-catalog-and-list-agents.md) owns the listing contract); discovery is a hint, never authority. `send_message` keeps its exact-direct-parent authority — only interrupt is ancestor-wide.
 
 ## Testing
 
-Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar Send/Stop toggle with the parent-offline locked-input state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end.
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar Send/Stop toggle with the parent-offline locked-input state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index ff9887481d..b8a5b557b7 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -39,8 +39,10 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 仅凭地址的 RPC 会暴露一位在线驻留信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
 
-Web 侧复用现有的 primary Send/Stop 切换而不新增第二个操作：客户端 `Session.cancel()` 将 continuable 地址路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍走 `session.cancel`）；parent 离线但仍在运行的 continuable child 保留默认 composer 并禁用其输入区，让同一个 primary Stop 保持可达，停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。面向模型的 `interrupt_agent` 工具在 issue #1535 的后续 stacked PR 中基于此原语构建。
+Web 侧复用现有的 primary Send/Stop 切换而不新增第二个操作：客户端 `Session.cancel()` 将 continuable 地址路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍走 `session.cancel`）；parent 离线但仍在运行的 continuable child 保留默认 composer 并禁用其输入区，让同一个 primary Stop 保持可达，停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。
+
+`dsh-tool-subagent-control` 中面向模型的 `interrupt_agent(agent_id)` 工具把 `exec.agent` 作为 `ancestor` 授权传入，自身不增加任何权限：核心原语校验在线注册表身份与记录的 lineage，因此该工具可以用同一个通用 `agent_id` 参数指定直接 child 或更深的后代——刻意不用会暗示仅限直接 child 的 `subagent_id`。发现依赖 `list_agents({ scope: 'descendants' })`，其底层是新的 `SubagentService.listDescendants()` 单次追踪 pre-order 遍历，每个条目带经校验的 `parentId`／`depth`（列表契约由[持久化目录 note](2026-07-22-durable-subagent-catalog-and-list-agents.md)拥有）；发现只是提示，绝非权限。`send_message` 保持其确切直接 parent 权限——只有中断是 ancestor 级的。
 
 ## Testing
 
-`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的 Send/Stop 切换及 parent 离线时锁定输入的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的 Send/Stop 切换及 parent 离线时锁定输入的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
diff --git a/apps/web/tests/shipped-composition.e2e.ts b/apps/web/tests/shipped-composition.e2e.ts
index 447f14ae44..11bbdcfd82 100644
--- a/apps/web/tests/shipped-composition.e2e.ts
+++ b/apps/web/tests/shipped-composition.e2e.ts
@@ -30,6 +30,7 @@ const EXPECTED_TOOLS = [
   'edit',
   'exit_plan_mode',
   'get_goal',
+  'interrupt_agent',
   'list_agents',
   'ralph',
   'read',
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 59a9cf527d..f4eead6f8e 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2153,6 +2153,23 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
  */
 listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>
 
+/**
+ * Enumerate the root's complete session-backed subagent tree in stable
+ * pre-order from one lineage trace, without loading or resuming an Agent.
+ * Ordinary sessions and one-shot children are traversed so continuable
+ * descendants below them are discovered; each returned entry adds its
+ * verified `parentId` and root-relative `depth`. Cancellation follows the
+ * same contract as {@link listChildren}.
+ * @param rootSessionId - session whose complete descendant tree is listed.
+ * @param signal - caller-owned cancellation forwarded where supported and
+ *   observed around every query await.
+ * @returns children and per-candidate diagnostics with tree position, in
+ *   stable pre-order.
+ * @throws {@link SubagentError} when session query is unavailable or the
+ *   caller cancels the scan.
+ */
+listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
+
 /**
  * Register a provider under its name. Registration is effect-scoped and HMR
  * safe; removing a provider blocks new starts but does not revoke runs that
@@ -2188,7 +2205,7 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentInterruptAuthority](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
+Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentDescendantListEntry](../core-data-structures/subagent.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentInterruptAuthority](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
 
diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/core-data-structures/subagent.i18n.yaml
index 15d5e19578..57b960da91 100644
--- a/docs/core-data-structures/subagent.i18n.yaml
+++ b/docs/core-data-structures/subagent.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 docs/core-data-structures/subagent.md
-subagent.md: 4de77c6232d73d4b4e9dd87e9afc7a077e61f1a0
-subagent.zh.md: 3310bb4bf8cad1314ec26eef9042955959aba5fe
+subagent.md: b26a12d1d50305d86d7ada29cac83474009d81ce
+subagent.zh.md: 6c4c64ff22050b73699a97093acd0032668fde3d
diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md
index 4de77c6232..b26a12d1d5 100644
--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -4,7 +4,7 @@ English | [中文](subagent.zh.md)
 
 The subagent seam — an agent delegating work to a child agent. Like [bash](bash.md) it is **one optional capability**, not part of the agent-loop spine, so its vocabulary lives here rather than in [core.md](core.md). But it differs from every other seam on one axis: **multiple provider implementations coexist** in one context, registered by name (`ctx.subagents`), where bash allows only one executor. The registry shape mirrors the [LLM adapter registry](llm-streaming.md), not the single-service bash executor.
 
-Interface: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Implementations are sibling packages (`dsh-subagent-spawn`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message` and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only direct-child discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
+Interface: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Implementations are sibling packages (`dsh-subagent-spawn`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message`, `interrupt_agent`, and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only child and descendant discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
 
 Sources: [`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts), [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts), and [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
@@ -263,9 +263,26 @@ The descriptor (`SubagentDescriptorData` in [descriptor.ts](../../packages/subag
 
 A local one-shot provider appends the descriptor inside the child's initial turn before its first request. The continuation manager appends the descriptor after any provider-supplied lineage and before the initial prompt is admitted; `header.seedLength` remains the fork-lineage boundary: resume-time descriptor authority reads the child's own suffix, while the list-serving identity projection folds `subagent/descriptor` last-wins so the child's own descriptor overrides a fork-seeded ancestor's. The event is log-only: no `surfaceOp`, never in model history, and retained across compaction by the append-only log. Malformed current-version descriptors are corrupt; unsupported versions cannot be classified by this runtime.
 
-## Durable enumeration: `listChildren()` and `SubagentListEntry`
+## Durable enumeration: `listChildren()`, `listDescendants()`, and their entries
+
+`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query seam, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry's `running`/`idle`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
+
+`SubagentService.listDescendants(rootSessionId)` applies the same live-preferred corpus and projection-backed interpretation to the root's complete descendant tree in stable pre-order. Ordinary sessions and one-shot children remain traversal nodes, so continuable descendants below them are discovered; only `origin: 'subagent'` candidates produce rows. Each returned child or diagnostic adds its position from the enumerated durable header, while a cold inspection revalidates that complete lifecycle before serving identity:
+
+```ts type-equiv
+/**
+ * One entry of a descendant listing: the interpreted subagent facts plus its
+ * position in the complete session tree. `parentId` is the durable direct
+ * parent from the enumerated header, and `depth` counts edges from the root.
+ */
+type SubagentDescendantListEntry = SubagentListEntry & {
+  /** Durable direct parent of this candidate in the enumerated tree. */
+  readonly parentId: SessionId
+  /** Edge distance from the requested root; direct children are `1`. */
+  readonly depth: number
+}
+```
 
-`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query seam, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and maps activity to its existing `running`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
 
 ## The terminal result: `SubagentResult`
 
diff --git a/docs/core-data-structures/subagent.zh.md b/docs/core-data-structures/subagent.zh.md
index 3310bb4bf8..6c4c64ff22 100644
--- a/docs/core-data-structures/subagent.zh.md
+++ b/docs/core-data-structures/subagent.zh.md
@@ -4,7 +4,7 @@
 
 subagent seam：一个 agent（智能体）将工作委派给子 agent。与 [bash](bash.md) 一样，它是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。但它在一个维度上与其他所有 seam 不同：**同一上下文中可共存多个提供方实现**，按名称注册（`ctx.subagents`），而 bash 只允许一个执行器。注册表的形状参照 [LLM（大语言模型）适配器注册表](llm-streaming.md)，而非单服务的 bash 执行器。
 
-接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包（package）：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接从会话存储与可选的会话持久化负责只读的直接 child 发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
+接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包（package）：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接从会话存储与可选的会话持久化负责只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
 
 源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)、[`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)和 [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
@@ -263,9 +263,26 @@ interface ContinuableCreateSpec {
 
 本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始 prompt 获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
 
-## 持久化枚举：`listChildren()` 与 `SubagentListEntry`
+## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
+
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 契约负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
+
+`SubagentService.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
+
+```ts type-equiv
+/**
+ * One entry of a descendant listing: the interpreted subagent facts plus its
+ * position in the complete session tree. `parentId` is the durable direct
+ * parent from the enumerated header, and `depth` counts edges from the root.
+ */
+type SubagentDescendantListEntry = SubagentListEntry & {
+  /** Durable direct parent of this candidate in the enumerated tree. */
+  readonly parentId: SessionId
+  /** Edge distance from the requested root; direct children are `1`. */
+  readonly depth: number
+}
+```
 
-`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 契约负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时只要求 `ctx.subagents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并将活动状态映射到现有的 `running`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 ## 终态结果：`SubagentResult`
 
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
index e63807db59..2f33c0c6a5 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
@@ -94,8 +94,16 @@ interface ToolArgsMap {
   } & Record<string, JsonValue>;
   /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */
   get_goal: Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. */
-  list_agents: Record<string, JsonValue>;
+  /** Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op. */
+  interrupt_agent: {
+    /** The agent id of the running agent to interrupt. */
+    agent_id: string;
+  } & Record<string, JsonValue>;
+  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent. */
+  list_agents: {
+    /** children (default) lists direct children only; descendants walks the complete tree below you. */
+    scope?: "children" | "descendants";
+  } & Record<string, JsonValue>;
   /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */
   ralph: {
     /** The immutable completion objective for every fresh Ralph round. */
@@ -304,15 +312,22 @@ interface ToolOutputMap {
     };
     activation: "armed" | "disarmed";
   };
+  interrupt_agent: {
+    accepted: boolean;
+  };
   list_agents: ({
     kind: "child";
     id: string;
     label: string;
-    status: "running" | "complete";
+    status: "running" | "idle" | "complete";
+    parent?: string;
+    depth?: number;
   } | {
     kind: "diagnostic";
     id: string;
     reason: "corrupt" | "unsupported" | "unavailable";
+    parent?: string;
+    depth?: number;
   })[];
   ralph: {
     runId: string;
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
index 98b866f841..d1e5b75e45 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
@@ -173,11 +173,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
index 7588c353cc..890f3ee000 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
index 70a71c3673..5b74a88512 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
@@ -77,8 +77,16 @@ interface ToolArgsMap {
   } & Record<string, JsonValue>;
   /** Read the current same-session goal, including its exact id/revision, objective, phase, completed continuation rounds, round limit, blocker reason when present, and whether another continuation is armed. Call this before updating a goal. */
   get_goal: Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. */
-  list_agents: Record<string, JsonValue>;
+  /** Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op. */
+  interrupt_agent: {
+    /** The agent id of the running agent to interrupt. */
+    agent_id: string;
+  } & Record<string, JsonValue>;
+  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent. */
+  list_agents: {
+    /** children (default) lists direct children only; descendants walks the complete tree below you. */
+    scope?: "children" | "descendants";
+  } & Record<string, JsonValue>;
   /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */
   ralph: {
     /** The immutable completion objective for every fresh Ralph round. */
@@ -275,15 +283,22 @@ interface ToolOutputMap {
     };
     activation: "armed" | "disarmed";
   };
+  interrupt_agent: {
+    accepted: boolean;
+  };
   list_agents: ({
     kind: "child";
     id: string;
     label: string;
-    status: "running" | "complete";
+    status: "running" | "idle" | "complete";
+    parent?: string;
+    depth?: number;
   } | {
     kind: "diagnostic";
     id: string;
     reason: "corrupt" | "unsupported" | "unavailable";
+    parent?: string;
+    depth?: number;
   })[];
   ralph: {
     runId: string;
diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
index 1fba9e71d5..e41987451b 100644
--- a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
index 48b72040a0..713353b91c 100644
--- a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
index 41fb8718c9..09c637f077 100644
--- a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
index 519e8eac8c..3283d98600 100644
--- a/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
index 519e8eac8c..3283d98600 100644
--- a/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
index 519e8eac8c..3283d98600 100644
--- a/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
index 08c1451f60..6cea6864cd 100644
--- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
index c242366100..f11131eb87 100644
--- a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
@@ -116,11 +116,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 1fd08a5c95..f942e6650e 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -948,6 +948,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>',
         jsDoc: '/**\n * Enumerate the parent\'s direct session-backed subagents without loading or\n * resuming an Agent and without any query seam: the listing merges the live\n * session store with optional session persistence (live-preferred) and\n * serves each child\'s durable mode/label from the registered `subagent`\n * projection unit down a three-rung ladder — the registry\'s watermark\n * snapshot for a live child; for a cold one, a durable projection-cache\n * row when the optional cache serves an own-suffix identity (its `seq`\n * gate proves the value postdates the fork seed, where a child\'s own\n * descriptor is immutable once appended), else one persistence inspection\n * folded through the registry. The\n * projection fold is the single classification authority; per-child\n * diagnostics relay a fold that served no identity or a failed inspection,\n * never a list-time descriptor parse. Absent persistence, enumeration is\n * live-only (a cold child cannot be resumed then either, so its absence is\n * capability absence, not an error). This service consults no Agent\n * registrations, Activations, or providers.\n *\n * Every persistence read receives `signal`, and the listing rechecks\n * cancellation around each of those awaits. Read rejections that settle\n * after an abort become a stable `SubagentError` with code `CANCELLED`.\n * @param parentSessionId - parent session whose direct children are listed.\n * @param signal - caller-owned cancellation forwarded to persistence reads\n *   and observed around every read await.\n * @returns children and per-child diagnostics ordered by `createdAt`, then id.\n * @throws {@link SubagentError} when the projection registry or the session\n *   store is not mounted, or the caller cancels the listing.\n */',
       },
+      {
+        signature: 'listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>',
+        jsDoc: '/**\n * Enumerate the root\'s complete session-backed subagent tree in stable\n * pre-order from one lineage trace, without loading or resuming an Agent.\n * Ordinary sessions and one-shot children are traversed so continuable\n * descendants below them are discovered; each returned entry adds its\n * verified `parentId` and root-relative `depth`. Cancellation follows the\n * same contract as {@link listChildren}.\n * @param rootSessionId - session whose complete descendant tree is listed.\n * @param signal - caller-owned cancellation forwarded where supported and\n *   observed around every query await.\n * @returns children and per-candidate diagnostics with tree position, in\n *   stable pre-order.\n * @throws {@link SubagentError} when session query is unavailable or the\n *   caller cancels the scan.\n */',
+      },
       {
         signature: 'registerProvider(provider: SubagentProvider): () => void',
         jsDoc: '/**\n * Register a provider under its name. Registration is effect-scoped and HMR\n * safe; removing a provider blocks new starts but does not revoke runs that\n * were already returned to their holders.\n * @param provider - the trusted provider implementation.\n * @returns the exact Cordis effect disposer.\n */',
@@ -2783,6 +2787,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SubagentCapabilities',
     declaration: 'export interface SubagentCapabilities {\n    readonly outputSchema: boolean;\n    readonly depthLimit: boolean;\n    readonly toolFilter: boolean;\n    readonly persona: boolean;\n}',
   },
+  {
+    name: 'SubagentDescendantListEntry',
+    declaration: 'export type SubagentDescendantListEntry = SubagentListEntry & {\n    readonly parentId: SessionId;\n    readonly depth: number;\n};',
+  },
   {
     name: 'SubagentDescriptorData',
     declaration: 'export type SubagentDescriptorData = OneShotSubagentDescriptorData | ContinuableSubagentDescriptorData;',
diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts
index dae09f0591..2e59ffe32e 100644
--- a/packages/core/tools/tests/gen-tool-catalog.spec.ts
+++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts
@@ -23,7 +23,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
   it('boots every shipped tool package and harvests its model-facing schemas', async () => {
     const catalog = await collectToolCatalog()
     const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
-    expect(names).toEqual(['ask_user_question', 'bash', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'list_agents', 'lsp', 'pwsh', 'ralph', 'read', 'report', 'run_code', 'send_message', 'session_event_read', 'session_event_search', 'session_event_trace', 'session_search', 'session_trace', 'skill', 'str_replace_editor', 'subagent', 'task_kill', 'task_list', 'task_output', 'terminal_close', 'terminal_list', 'terminal_open', 'terminal_read', 'terminal_send', 'terminal_signal', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write'])
+    expect(names).toEqual(['ask_user_question', 'bash', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'interrupt_agent', 'list_agents', 'lsp', 'pwsh', 'ralph', 'read', 'report', 'run_code', 'send_message', 'session_event_read', 'session_event_search', 'session_event_trace', 'session_search', 'session_trace', 'skill', 'str_replace_editor', 'subagent', 'task_kill', 'task_list', 'task_output', 'terminal_close', 'terminal_list', 'terminal_open', 'terminal_read', 'terminal_send', 'terminal_signal', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write'])
     // Every tool carries a JSON-Schema `parameters` object (what the model sees).
     for (const entry of catalog) {
       for (const schema of entry.schemas) {
@@ -49,6 +49,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
     expect(bash?.sources.bash).toBe('packages/bash/tool-bash/src/index.ts')
     const control = catalog.find(entry => entry.pkg === '@deepseek-ai/dsh-tool-subagent-control')
     expect(control?.sources).toEqual({
+      interrupt_agent: 'packages/subagent/tool-subagent-control/src/index.ts',
       list_agents: 'packages/subagent/tool-subagent-control/src/list-agents.ts',
       send_message: 'packages/subagent/tool-subagent-control/src/index.ts',
     })
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 9b9843af87..1025b0e342 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: eb1baa39231a2c058b3ada1a23b7b87e2bb2e384
-README.zh.md: 8402df3e4ff2559898dfd4dd512ab1601c9ec61d
+README.md: cd25bace16c91e8b44331dc8e5eab0987607e83a
+README.zh.md: 05b1e4dd4c74b6d62df8b0a310534fc9476f3ade
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index eb1baa3923..cd25bace16 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -18,11 +18,12 @@ The [subagent family overview](../README.md) maps implementations and model-faci
 | `start(name, request)` | Validate an ordinary caller request, resolve its detached `one-shot` descriptor, then await the provider until a real one-shot child is published. Fulfillment returns a holder-owned `SubagentRun`; rejection means the provider has already cleaned every unpublished startup resource, while post-publication turn or infrastructure faults settle through the run. Continuable children never enter through this operation. |
 | `startContinuable(spec)` | Establish one durable continuable child and deliver its initial prompt. Resolves with `{ childId, messageId }` when the child's inbox accepts that prompt, without waiting for the turn to start or for the message to reach the Session log; any earlier failure rejects with no ids and rolls the child back entirely. Requires `ctx.agents`, session persistence, and a provider with the `prepareContinuable` capability. |
 | `followup(parent, childId, content, { source, signal })` | Deliver one later message from the exact live direct parent as the child's next FIFO turn, matching `Agent.followup()` terminology, and return the accepted `MessageId`. A resident child's inbox accepts it directly (waking a waiting Activation); an absent one cold-resumes from its persisted Session. Requires `ctx.agents`; cold resume also requires session persistence. |
-| `interrupt(targetSessionId, authority)` | Interrupt one live continuable child's current turn under a human durable parent address (`{ kind: 'user', parentSessionId }`) or an exact live ancestor Agent (`{ kind: 'ancestor', agent }`). Admission is synchronous and the effect asynchronous: it issues `Agent.cancel(cause, { keepInbox: true })` and returns without waiting for the target to observe the signal. Unclaimed pending inbox work, the Activation, and published descendants are preserved; work already claimed into the interrupted turn is not requeued. Once the interrupted driver is idle, a waking send resumes the parked FIFO queue. An absent target — unknown, one-shot, or already-settled id — and a manager-less composition are accepted no-ops. For a live target, a mismatched parent address or caller outside its live ancestry rejects with `UNAUTHORIZED`; stale ancestor objects and self-targeting ancestor requests reject before target lookup. |
+| `interrupt(targetSessionId, authority)` | Interrupt one live continuable child's current turn under a human durable parent address (`{ kind: 'user', parentSessionId }`) or an exact live ancestor Agent (`{ kind: 'ancestor', agent }`). Admission is synchronous and the effect asynchronous: it issues `Agent.cancel(cause, { keepInbox: true })` and returns without waiting for the target to observe the signal. Unclaimed pending inbox work, the Activation, and published descendants are preserved; work already claimed into the interrupted turn is not requeued. An absent target is an accepted no-op; a wrong parent address or a stale, self-targeting, or non-ancestor caller rejects with `UNAUTHORIZED`. |
 | `reportFrom(child, content, { delivery, signal })` | Deliver one selected message from the exact live continuable child to its exact live direct parent and return the accepted stable `MessageId`. Quiet delivery injects context; waking delivery submits one later parent turn. |
 | `registerContinuableSetup(contribution)` | Compose an optional deployment capability into each continuable child's unpublished scope, with immediate revocation from resident children. |
 | `drainContinuableDescendants(parents)` | Close admission below exact live host-owned parent Agents, stop only their visible continuable descendants, await materializations admitted below those roots through publication or rollback, then release the selected forests child-first. The cutoff lasts until each exact parent leaves the registry; unrelated parent forests and manager-wide admission remain live. |
 | `listChildren(parentSessionId, signal?)` | List direct session-backed subagents with their `one-shot`/`continuable` mode, `running`/`inactive` activity, origin-classified one-level `hasChildren` hint, and per-child diagnostics, ordered by `createdAt` then id, without loading or resuming them. Reads the live session store and optional session persistence directly (live-only enumeration when persistence is absent) and requires the mounted `sessionProjections` registry; it does not require `ctx.agents`, the continuation manager, or any query service. |
+| `listDescendants(rootSessionId, signal?)` | Flatten the root's complete session tree in stable pre-order from the same live-preferred corpus, adding each subagent entry's durable `parentId` and root-relative `depth`. Ordinary sessions and one-shot children remain traversal nodes so continuable descendants below them are discovered. Identity, diagnostics, dependencies, and cancellation follow `listChildren()`. |
 
 `SubagentStartRequest.label` is an optional short durable display label for a session-backed one-shot child. Model-facing delegation supplies its existing `description`; lower-level callers need not invent presentation metadata. Continuable starts always carry their own required label. `signal` is required and is the canonical cancellation channel for a one-shot `start`. An abort before publication makes `start()` reject after rollback; an abort after publication cancels the returned run's remaining turn work without hiding its id. The request may also select a model, require structured output, cap delegation depth, restrict child tools, or set a child persona. For a continuable start or follow-up, the caller signal owns lookup, materialization, and admission only until inbox acceptance; afterward the manager owns the Activation independently, so later caller cancellation neither cancels the accepted turn nor disposes the child.
 
@@ -85,7 +86,7 @@ When `ctx.sessionProjections` is available, the service registers two projection
 
 ## Collection model
 
-The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task or result promise — a caller sends later work with the `send_message` follow-up tool, while `interrupt()` stops only the current turn without disposing the child. The durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and maps service activity to its existing `running`/`complete` vocabulary. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
+The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task and no result promise — a caller sends later work with the `send_message` follow-up tool, and `interrupt()` stops only the current turn without disposing the child, and the durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and refines status through the live Agent registry (`running`/`idle`/`complete`) and walks `listDescendants()` for its `descendants` scope. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
 
 Continuable Activations await a best-effort final session flush without treating listener participation as durability confirmation. One-shot runs retain best-effort session checkpointing, so a completed one-shot child is discoverable after disposal only when its session actually reached persistence; the service does not invent a catalog entry from Task history when that checkpoint is absent.
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 8402df3e4f..05b1e4dd4c 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -18,11 +18,12 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `start(name, request)` | 校验普通调用方请求，解析其分离的 `one-shot` 描述符，然后等待提供方，直到真实的一次性子 agent 发布。兑现时返回由持有方拥有的 `SubagentRun`；拒绝表示提供方已清理所有未发布的启动资源，而发布后的轮次或基础设施故障会通过该 run 结算。可继续子 agent 绝不通过此操作进入。 |
 | `startContinuable(spec)` | 建立一个持久化可继续子 agent，并投递其初始提示词。子 agent 的 inbox 接受该提示词时，兑现为 `{ childId, messageId }`，无需等待轮次开始或消息写入 Session 日志；此前任何失败都会以无 id 拒绝，并完全回滚该子 agent。要求 `ctx.agents`、会话持久化以及具备 `prepareContinuable` 能力的提供方。 |
 | `followup(parent, childId, content, { source, signal })` | 将来自确切在线直接父级的一条后续消息作为子 agent 的下一个 FIFO 轮次投递，术语与 `Agent.followup()` 一致，并返回被接受的 `MessageId`。驻留中的子 agent 由其 inbox 直接接受（唤醒处于 waiting 的 Activation）；不驻留的则从其持久化 Session 冷恢复。要求 `ctx.agents`；冷恢复还要求会话持久化。 |
-| `interrupt(targetSessionId, authority)` | 以人类持久化 parent 地址（`{ kind: 'user', parentSessionId }`）或确切在线 ancestor Agent（`{ kind: 'ancestor', agent }`）为授权，中断一个在线可继续 child 的当前轮次。准入是同步的、生效是异步的：它发出 `Agent.cancel(cause, { keepInbox: true })` 后立即返回，不等待目标观察到信号。尚未领取的待处理 inbox 工作、Activation 与已发布的后代均保持不变；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。目标不存在——未知、一次性或已结算的 id——以及未绑定管理器的组合都是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；过期的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。 |
+| `interrupt(targetSessionId, authority)` | 以人类持久化 parent 地址（`{ kind: 'user', parentSessionId }`）或确切在线 ancestor Agent（`{ kind: 'ancestor', agent }`）为授权，中断一个在线可继续 child 的当前轮次。准入同步完成、生效异步进行：它发出 `Agent.cancel(cause, { keepInbox: true })` 后立即返回，不等待目标观察到信号。尚未领取的待处理 inbox 工作、Activation 与已发布的后代均保持不变；已被领取进入中断轮次的工作不会重新入队。目标不存在时接受为 no-op；错误的 parent 地址以及过期、指向自身或非祖先调用方以 `UNAUTHORIZED` 拒绝。 |
 | `reportFrom(child, content, { delivery, signal })` | 从确切在线可继续 child 向其确切在线直接 parent 投递一条选中消息，并返回已接受的稳定 `MessageId`。静默投递会注入上下文；唤醒投递会提交一个后续 parent 轮次。 |
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
 | `listChildren(parentSessionId, signal?)` | 按 `createdAt` 再按 id 的顺序列出由会话支撑的直接 subagent，包括其 `one-shot`／`continuable` 模式、`running`／`inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic，且不会加载或恢复它们。直接读取在线会话存储与可选的会话持久化（持久化缺席时仅枚举在线 child），并要求已挂载 `sessionProjections` 注册表；不要求 `ctx.agents`、继续执行管理器或任何查询服务。 |
+| `listDescendants(rootSessionId, signal?)` | 从同一份实时优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth`。普通会话与一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现。身份、diagnostic、依赖与取消契约均沿用 `listChildren()`。 |
 
 `SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。
 
@@ -77,7 +78,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 提供方新增和移除还会发出 `subagent/provider-added` 与 `subagent/provider-removed`。面向模型的工具等消费方使用这些事件，因为 Cordis 可能并发加载同级插件；配置顺序不能证明注册顺序。
 
-可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代——因为停止一个轮次是幂等的，且不投递任何内容。
+可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代，因为停止一个轮次是幂等的，且不投递任何内容。
 
 当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置纪律从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，让消费方以之替换掉手中过时的身份而非永久滞留——绝不抛错。
 
@@ -85,7 +86,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 收集模型
 
-面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task 或结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，而 `interrupt()` 只停止当前轮次，不 dispose 子 agent。持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，并将服务活动状态映射到现有的 `running`／`complete` 词汇。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
+面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`），并在 `descendants` scope 下遍历 `listDescendants()`。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
 
 可继续 Activation 会等待 best-effort 的最终会话 flush，但不会把 listener 参与视为持久性确认。一次性运行保留尽力执行的会话检查点，因此已完成的一次性 child 只有在其会话确实进入持久化存储时，才可在 dispose 后继续被发现；如果该检查点缺失，服务不会根据 Task 历史虚构目录条目。
 
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 8bf4efb5d0..2a118565fa 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -19,9 +19,9 @@
  * resident. Continuable children never become a {@link SubagentRun}: the
  * continuation manager holds their `AgentHandle` directly and orders every turn
  * through the child's own inbox, so providers contribute only the detached
- * creation spec and see no handle, turn, or teardown. Direct-child discovery
- * reads the live session store and optional session persistence directly and
- * does not require that continuation runtime.
+ * creation spec and see no handle, turn, or teardown. Child and descendant
+ * discovery read the live session store and optional session persistence
+ * directly and do not require that continuation runtime.
  *
  * Same-process providers are trusted typed collaborators. Requests, provider
  * descriptors, results, and lifecycle payloads are borrowed immutable values;
@@ -63,8 +63,8 @@ import type {
 } from './continuation.ts'
 import SubagentActivationSetupRegistry from './activation-setup-registry.ts'
 import type { ContinuableSetupContribution } from './activation-setup-registry.ts'
-import { listChildren as listSubagentChildren } from './list-children.ts'
-import type { SubagentListEntry } from './list-children.ts'
+import { listChildren as listSubagentChildren, listDescendants as listSubagentDescendants } from './list-children.ts'
+import type { SubagentDescendantListEntry, SubagentListEntry } from './list-children.ts'
 import { snapshotSubagentDescriptor } from './descriptor.ts'
 import { subagentIdentityProjectionDefinition, subagentTimingProjectionDefinition } from './projection.ts'
 
@@ -118,7 +118,7 @@ export type {
   SubagentReportOptions,
 } from './continuation.ts'
 export type { ContinuableSetupContribution } from './activation-setup-registry.ts'
-export type { SubagentListEntry } from './list-children.ts'
+export type { SubagentDescendantListEntry, SubagentListEntry } from './list-children.ts'
 export type { SubagentRunEndInfo, SubagentRunInfo } from './types.ts'
 export type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts'
 
@@ -336,6 +336,25 @@ export class SubagentService extends Service {
     return listSubagentChildren(this.ctx, parentSessionId, signal)
   }
 
+  /**
+   * Enumerate the root's complete session-backed subagent tree in stable
+   * pre-order from one live-preferred corpus, without loading or resuming an
+   * Agent. Ordinary sessions and one-shot children remain traversal nodes so
+   * continuable descendants below them are discovered; each returned entry
+   * adds its durable `parentId` and root-relative `depth`. Identity resolution,
+   * diagnostics, optional persistence, and cancellation follow the same
+   * projection-backed contract as {@link listChildren}.
+   * @param rootSessionId - session whose complete descendant tree is listed.
+   * @param signal - caller-owned cancellation forwarded to persistence reads
+   *   and observed around every read await.
+   * @returns children and per-candidate diagnostics with tree position, in
+   *   stable pre-order.
+   * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+   */
+  listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]> {
+    return listSubagentDescendants(this.ctx, rootSessionId, signal)
+  }
+
   /**
    * Register a provider under its name. Registration is effect-scoped and HMR
    * safe; removing a provider blocks new starts but does not revoke runs that
diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index fef098f90f..db3339e197 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -1,18 +1,16 @@
 /**
- * Read-only enumeration of one parent's durable subagent children straight
- * from the live session store and optional session persistence — no query
- * seam. Candidates are the live-preferred merge of both listings filtered to
- * durable `origin: 'subagent'` under the parent; each child's mode/label is
- * the registered `subagent` projection unit's value, resolved down a
- * three-rung ladder: the registry's watermark cache for a live child, a
- * durable projection-cache row when it serves an own-suffix identity (the
+ * Read-only enumeration of durable subagent children and descendant trees
+ * straight from the live session store and optional session persistence — no
+ * query seam. Candidates come from one live-preferred corpus; each child's
+ * mode/label is the registered `subagent` projection unit's value, resolved
+ * down a three-rung ladder: the registry's watermark cache for a live child,
+ * a durable projection-cache row when it serves an own-suffix identity (the
  * seq gate), and one persistence inspection folded through the registry
- * otherwise, validated against the enumerated lifecycle. The projection
- * fold is the single
- * classification authority — this module parses no descriptor itself. Absent
- * persistence, enumeration is live-only: a cold child is unreachable for
- * resume anyway, so its absence is capability absence, not an error. The
- * module owns no catalog state and does not consult Activation,
+ * otherwise, validated against the enumerated lifecycle. The projection fold
+ * is the single classification authority — this module parses no descriptor
+ * itself. Absent persistence, enumeration is live-only: a cold child is
+ * unreachable for resume anyway, so its absence is capability absence, not an
+ * error. The module owns no catalog state and does not consult Activation,
  * Agent-registry, continuation-manager, or provider state.
  *
  * @module @deepseek-ai/dsh-subagent
@@ -88,6 +86,34 @@ export type SubagentListEntry =
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
   }
 
+/**
+ * One entry of a descendant listing: the interpreted subagent facts plus its
+ * position in the complete session tree. `parentId` is the durable direct
+ * parent from the enumerated header, and `depth` counts edges from the root.
+ */
+export type SubagentDescendantListEntry = SubagentListEntry & {
+  /** Durable direct parent of this candidate in the enumerated tree. */
+  readonly parentId: SessionId
+  /** Edge distance from the requested root; direct children are `1`. */
+  readonly depth: number
+}
+
+type CorpusRecord = { readonly header: SessionHeader; readonly live: Session | undefined }
+
+interface ListingRuntime {
+  readonly projections: SessionProjectionRegistry
+  readonly persistence: SessionPersistence | undefined
+  readonly cache: SessionProjectionCache | undefined
+  readonly corpus: ReadonlyMap<SessionId, CorpusRecord>
+  readonly subagentParents: ReadonlySet<SessionId>
+}
+
+interface PositionedCandidate {
+  readonly record: CorpusRecord
+  readonly parentId: SessionId
+  readonly depth: number
+}
+
 /**
  * Enumerate one parent's origin-classified direct children from the
  * live-preferred merge of `ctx.sessions` and optional session persistence,
@@ -110,6 +136,55 @@ export async function listChildren(
   parentSessionId: SessionId,
   signal?: AbortSignal,
 ): Promise<SubagentListEntry[]> {
+  const listing = await prepareListing(ctx, signal)
+  const candidates = [...listing.corpus.values()]
+    .filter(record => record.header.parentSession === parentSessionId
+      && record.header.origin === 'subagent')
+    .sort(compareCorpusRecords)
+  const rows = await resolveCandidateRows(candidates, listing, signal)
+  return rows.filter((row): row is SubagentListEntry => row !== undefined)
+}
+
+/**
+ * Enumerate every session-backed subagent below one root in stable pre-order.
+ * Ordinary sessions and one-shot children remain traversal nodes, so a
+ * continuable child below either is still discovered. Classification uses the
+ * same projection-backed runtime as {@link listChildren}; no Agent is loaded or
+ * resumed.
+ * @see SubagentService.listDescendants for the public cancellation and failure contract.
+ * @param ctx - context carrying the session store, projection registry, and optional persistence/cache.
+ * @param rootSessionId - session whose complete descendant tree is listed.
+ * @param signal - caller-owned cancellation observed around every persistence read.
+ * @returns interpreted subagents with durable direct-parent and root-relative depth.
+ * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+ */
+export async function listDescendants(
+  ctx: Context,
+  rootSessionId: SessionId,
+  signal?: AbortSignal,
+): Promise<SubagentDescendantListEntry[]> {
+  const listing = await prepareListing(ctx, signal)
+  const positioned = descendantCandidates(listing.corpus, rootSessionId)
+  const rows = await resolveCandidateRows(
+    positioned.map(candidate => candidate.record),
+    listing,
+    signal,
+  )
+  const entries: SubagentDescendantListEntry[] = []
+  positioned.forEach((position, index) => {
+    const row = rows[index]
+    if (row !== undefined) {
+      entries.push({ ...row, parentId: position.parentId, depth: position.depth })
+    }
+  })
+  return entries
+}
+
+/** Resolve listing services once and build one live-preferred session corpus. */
+async function prepareListing(
+  ctx: Context,
+  signal: AbortSignal | undefined,
+): Promise<ListingRuntime> {
   const projections = ctx.get('sessionProjections')
   // Checked before any read, even with zero candidates: mode/label are the
   // row's strong contract, so a missing fold capability is a deterministic
@@ -150,7 +225,7 @@ export async function listChildren(
   }
   // Live-preferred merge without header reconciliation: a live record wins
   // its id wholesale, exactly as a live-preferred corpus would serve it.
-  const corpus = new Map<SessionId, { header: SessionHeader; live: Session | undefined }>()
+  const corpus = new Map<SessionId, CorpusRecord>()
   for (const header of persistedHeaders) corpus.set(header.id, { header, live: undefined })
   for (const session of sessions.list()) {
     corpus.set(session.header.id, { header: session.header, live: session })
@@ -161,12 +236,16 @@ export async function listChildren(
       subagentParents.add(record.header.parentSession)
     }
   }
-  const candidates = [...corpus.values()]
-    .filter(record => record.header.parentSession === parentSessionId
-      && record.header.origin === 'subagent')
-    .sort((a, b) => a.header.createdAt - b.header.createdAt
-      || a.header.id.localeCompare(b.header.id))
+  return { projections, persistence, cache, corpus, subagentParents }
+}
 
+/** Resolve projection-backed rows for aligned candidates with bounded cold reads. */
+async function resolveCandidateRows(
+  candidates: readonly CorpusRecord[],
+  listing: ListingRuntime,
+  signal: AbortSignal | undefined,
+): Promise<(SubagentListEntry | undefined)[]> {
+  const { projections, persistence, cache, subagentParents } = listing
   const rows: (SubagentListEntry | undefined)[] = Array.from({ length: candidates.length })
   const coldReads: { index: number; header: SessionHeader }[] = []
   candidates.forEach((candidate, index) => {
@@ -212,7 +291,47 @@ export async function listChildren(
     ))
   }
   assertListingNotCancelled(signal)
-  return rows.filter((row): row is SubagentListEntry => row !== undefined)
+  return rows
+}
+
+/** Build origin-classified candidates from the complete tree without recursion. */
+function descendantCandidates(
+  corpus: ReadonlyMap<SessionId, CorpusRecord>,
+  rootSessionId: SessionId,
+): PositionedCandidate[] {
+  const children = new Map<SessionId, CorpusRecord[]>()
+  for (const record of corpus.values()) {
+    const parentId = record.header.parentSession
+    if (parentId === undefined) continue
+    const siblings = children.get(parentId)
+    if (siblings === undefined) children.set(parentId, [record])
+    else siblings.push(record)
+  }
+  for (const siblings of children.values()) siblings.sort(compareCorpusRecords)
+
+  const positioned: PositionedCandidate[] = []
+  const stack: PositionedCandidate[] = (children.get(rootSessionId) ?? [])
+    .map(record => ({ record, parentId: rootSessionId, depth: 1 }))
+    .reverse()
+  const visited = new Set<SessionId>([rootSessionId])
+  while (stack.length > 0) {
+    const position = stack.pop()
+    if (position === undefined) break
+    const id = position.record.header.id
+    if (visited.has(id)) continue
+    visited.add(id)
+    if (position.record.header.origin === 'subagent') positioned.push(position)
+    const descendants = children.get(id) ?? []
+    for (const record of [...descendants].reverse()) {
+      stack.push({ record, parentId: id, depth: position.depth + 1 })
+    }
+  }
+  return positioned
+}
+
+/** Compare siblings by durable creation time, then id. */
+function compareCorpusRecords(a: CorpusRecord, b: CorpusRecord): number {
+  return a.header.createdAt - b.header.createdAt || a.header.id.localeCompare(b.header.id)
 }
 
 /**
diff --git a/packages/subagent/subagent/tests/list-children.spec.ts b/packages/subagent/subagent/tests/list-children.spec.ts
index ef52883db2..31c8f1c6aa 100644
--- a/packages/subagent/subagent/tests/list-children.spec.ts
+++ b/packages/subagent/subagent/tests/list-children.spec.ts
@@ -972,3 +972,197 @@ describe('SubagentService.listChildren', () => {
     expect((caught as SubagentError).code).toBe('SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE')
   })
 })
+
+describe('SubagentService.listDescendants', () => {
+  it('flattens the complete tree in stable pre-order with verified parent and depth', async () => {
+    const { ctx, parent } = await setup([])
+    const childA = await authorChild(ctx, '00000000-0000-4000-8000-00000000aaa1', {
+      parentSession: parent.id,
+      createdAt: 1,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('branch a')))
+    const grandchild = await authorChild(ctx, '00000000-0000-4000-8000-00000000aaa2', {
+      parentSession: childA,
+      createdAt: 2,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('under a')))
+    const childB = await authorChild(ctx, '00000000-0000-4000-8000-00000000aaa3', {
+      parentSession: parent.id,
+      createdAt: 3,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('branch b')))
+
+    const entries = await ctx.subagents.listDescendants(parent.id)
+    expect(entries).toEqual([
+      {
+        kind: 'child', id: childA, label: 'branch a', mode: 'continuable',
+        activity: 'inactive', hasChildren: true, parentId: parent.id, depth: 1,
+      },
+      {
+        kind: 'child', id: grandchild, label: 'under a', mode: 'continuable',
+        activity: 'inactive', hasChildren: false, parentId: childA, depth: 2,
+      },
+      {
+        kind: 'child', id: childB, label: 'branch b', mode: 'continuable',
+        activity: 'inactive', hasChildren: false, parentId: parent.id, depth: 1,
+      },
+    ])
+  })
+
+  it('walks a deeply nested ordinary-session chain without consuming the call stack', async () => {
+    const { ctx, parent } = await setup([])
+    const depth = 10_000
+    let parentId = parent.id
+    for (let level = 1; level < depth; level += 1) {
+      const session = ctx.sessions.create(SessionId(`deep-ordinary-${level}`), {
+        meta: { createdAt: level, parentSession: parentId },
+      })
+      parentId = session.id
+    }
+    const leafId = SessionId('deep-subagent-leaf')
+    const leaf = ctx.sessions.create(leafId, {
+      meta: { createdAt: depth, parentSession: parentId, origin: 'subagent' },
+    })
+    leaf.append('turn/start', { turn: 1 })
+    leaf.append('subagent/descriptor', descriptorPayload('deep leaf'))
+
+    await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([{
+      kind: 'child', id: leafId, label: 'deep leaf', mode: 'continuable',
+      activity: 'running', hasChildren: false, parentId, depth,
+    }])
+  })
+
+  it('discovers continuable descendants below ordinary and one-shot intermediates', async () => {
+    const { ctx, parent } = await setup([textResponse('one shot')])
+    // An ordinary fork has no descriptor: omitted itself, subtree still walked.
+    const fork = ctx.sessions.fork(parent.session, undefined, SessionId('plain-fork'))
+    await ctx.sessions.flush(fork)
+    const underFork = await authorChild(ctx, '00000000-0000-4000-8000-00000000bbb1', {
+      parentSession: fork.header.id,
+      createdAt: 2,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('under the fork')))
+    // A real one-shot child, then a continuable authored below it.
+    const oneShot = await ctx.subagents.start('spawn', {
+      label: 'one-shot intermediate',
+      prompt: [{ type: 'text', text: 'one-shot task' }],
+      parent,
+      signal: testSignal,
+    })
+    await oneShot.result
+    await ctx.sessions.flush(oneShot.localAgent!.session)
+    const oneShotId = oneShot.id
+    await oneShot.dispose()
+    const underOneShot = await authorChild(ctx, '00000000-0000-4000-8000-00000000bbb2', {
+      parentSession: oneShotId,
+      createdAt: 9_999_999_999_999,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('under the one-shot')))
+
+    const entries = await ctx.subagents.listDescendants(parent.id)
+    // The fork is absent (descriptor-less); the one-shot is present with its
+    // mode so a caller can see the lineage it walked through.
+    expect(entries.map(entry => entry.id)).not.toContain(fork.header.id)
+    expect(entries).toContainEqual({
+      kind: 'child', id: underFork, label: 'under the fork', mode: 'continuable',
+      activity: 'inactive', hasChildren: false, parentId: fork.header.id, depth: 2,
+    })
+    expect(entries).toContainEqual(expect.objectContaining({
+      kind: 'child', id: oneShotId, mode: 'one-shot', parentId: parent.id, depth: 1,
+    }))
+    expect(entries).toContainEqual({
+      kind: 'child', id: underOneShot, label: 'under the one-shot', mode: 'continuable',
+      activity: 'inactive', hasChildren: false, parentId: oneShotId, depth: 2,
+    })
+    // Pre-order: every child appears after its own parent entry.
+    const position = new Map(entries.map((entry, index) => [entry.id, index]))
+    expect(position.get(underOneShot)!).toBeGreaterThan(position.get(oneShotId)!)
+  })
+
+  it('diagnoses a settled descriptor-less node while walking its subtree', async () => {
+    const { ctx, parent } = await setup([])
+    // A settled origin-marked candidate without an identity is corrupt under
+    // the projection contract, but its subtree remains independently visible.
+    const bare = await authorChild(ctx, '00000000-0000-4000-8000-00000000eee1', {
+      parentSession: parent.id,
+      createdAt: 1,
+      origin: 'subagent',
+    }, [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+    ] as SessionEvent[])
+    const below = await authorChild(ctx, '00000000-0000-4000-8000-00000000eee2', {
+      parentSession: bare,
+      createdAt: 2,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('below the bare node')))
+
+    await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([
+      { kind: 'diagnostic', id: bare, reason: 'corrupt', parentId: parent.id, depth: 1 },
+      {
+        kind: 'child', id: below, label: 'below the bare node', mode: 'continuable',
+        activity: 'inactive', hasChildren: false, parentId: bare, depth: 2,
+      },
+    ])
+  })
+
+  it('keeps traversing below a corrupt intermediate and positions its diagnostic', async () => {
+    const { ctx, parent } = await setup([])
+    const corrupt = await authorChild(ctx, '00000000-0000-4000-8000-00000000ccc1', {
+      parentSession: parent.id,
+      createdAt: 1,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('unsupported descriptor', 999)))
+    const below = await authorChild(ctx, '00000000-0000-4000-8000-00000000ccc2', {
+      parentSession: corrupt,
+      createdAt: 2,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('below the corrupt node')))
+
+    const entries = await ctx.subagents.listDescendants(parent.id)
+    expect(entries).toEqual([
+      { kind: 'diagnostic', id: corrupt, reason: 'corrupt', parentId: parent.id, depth: 1 },
+      {
+        kind: 'child', id: below, label: 'below the corrupt node', mode: 'continuable',
+        activity: 'inactive', hasChildren: false, parentId: corrupt, depth: 2,
+      },
+    ])
+  })
+
+  it('verifies a cold candidate still belongs to its enumerated lifecycle', async () => {
+    const { ctx, parent } = await setup([])
+    const childId = await authorChild(ctx, '00000000-0000-4000-8000-00000000ddd1', {
+      parentSession: parent.id,
+      createdAt: 1,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('lineage checked')))
+    const realInspect = ctx.sessionPersistence.inspect.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.inspect = async (sessionId, signal) => {
+      const inspected = await realInspect(sessionId, signal)
+      // The exact read reports a different durable parent than enumeration did.
+      return { ...inspected, meta: { ...inspected.meta, parentSession: SessionId('someone-else') } }
+    }
+    await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([
+      { kind: 'diagnostic', id: childId, reason: 'corrupt', parentId: parent.id, depth: 1 },
+    ])
+  })
+
+  it('a pre-aborted signal stops the descendant scan before persistence reads', async () => {
+    const { ctx, parent } = await setup([textResponse('done')])
+    await startChild(ctx, parent, 'never read')
+    const list = vi.spyOn(ctx.sessionPersistence, 'list')
+    const controller = new AbortController()
+    controller.abort()
+    await expect(ctx.subagents.listDescendants(parent.id, controller.signal)).rejects.toThrow(
+      expect.objectContaining({ code: 'CANCELLED' }) as Error,
+    )
+    expect(list).not.toHaveBeenCalled()
+  })
+
+  it('fails loud when the projection registry is not mounted', async () => {
+    const { ctx, parent } = await setup([], { sessionProjections: false })
+    await expect(ctx.subagents.listDescendants(parent.id)).rejects.toThrow(
+      expect.objectContaining({ code: 'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE' }) as Error,
+    )
+  })
+})
diff --git a/packages/subagent/tool-subagent-control/README.i18n.yaml b/packages/subagent/tool-subagent-control/README.i18n.yaml
index f26a290f5e..367a73fd1f 100644
--- a/packages/subagent/tool-subagent-control/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-control/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/subagent/tool-subagent-control/README.md
-README.md: ea95a45b85e01d1f5f1c478a35c80c65151724ac
-README.zh.md: 2cc876c8b39caa19fdf30eae7c8def0ba81fe7b1
+README.md: 4d9991b720bbbff8862e693b6aaed332f414af0e
+README.zh.md: dc1c81fc3313a8dfa277f33ae745702ed5b9d34b
diff --git a/packages/subagent/tool-subagent-control/README.md b/packages/subagent/tool-subagent-control/README.md
index ea95a45b85..4d9991b720 100644
--- a/packages/subagent/tool-subagent-control/README.md
+++ b/packages/subagent/tool-subagent-control/README.md
@@ -2,11 +2,13 @@
 
 English | [中文](README.zh.md)
 
-The optional, globally named `send_message` and `list_agents` tools are thin adapters over `ctx.subagents`. Provider-bound `@deepseek-ai/dsh-tool-subagent` instances register distinct delegation tools per transport; this separately loaded package registers shared control tools once, so multiple delegation tools never register duplicate global controls. The root plugin registers `send_message` and the separately loadable `./list-agents` plugin registers `list_agents`; both require only `subagents`, so a deployment can keep `send_message` while omitting the list tool. Neither tool's presence determines whether a delegation tool starts continuable work. These tools own only the parent-to-child direction; the independently installed [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) owns the child-to-parent direction.
+The optional, globally named `send_message`, `interrupt_agent`, and `list_agents` tools are thin adapters over `ctx.subagents`. Provider-bound `@deepseek-ai/dsh-tool-subagent` instances register distinct delegation tools per transport; this separately loaded package registers shared control tools once, so multiple delegation tools never register duplicate global controls. The root plugin registers `send_message` and `interrupt_agent` and requires only `subagents`; the separately loadable `./list-agents` plugin registers `list_agents` and declares `subagents` plus `agents` as load-time dependencies. Its catalog reads additionally require the session store and projection registry at call time, but no query service. A deployment can keep the root tools while omitting the list tool. No tool's presence determines whether a delegation tool starts continuable work. These tools own only the parent-to-child direction; the independently installed [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) owns the child-to-parent direction.
 
 The tool performs no lifecycle routing — residency and cold resume belong to the subagent service. It passes `exec.agent` as the exact live parent that authorizes delivery and attributes every message as durable provenance `{ kind: 'coordinator', senderSessionId: parent.id }`, which the service retains but never treats as authority. Every message becomes the subagent's next FIFO turn through `Agent.followup()`: if the child is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. The tool forwards its execution signal, which owns admission only until inbox acceptance; once the child accepts the message the accepted turn cannot be cancelled through this tool. This call returns no child reply — its transcript by that id is the source of what it did — and a child with `report` sends content on its own initiative as a separate parent message. A delivery failure becomes an errored tool result stating the message was not delivered.
 
-`list_agents` takes no arguments, derives the parent id from the calling agent, and projects `ctx.subagents.listChildren()` to continuable children without a cursor. The service result also contains one-shot session-backed subagents for consumers such as a UI, but those entries are omitted from this model tool because they cannot accept `send_message`. Diagnostics remain visible. Durable identity and mode come from each child's descriptor, while delivery-time authority and Activation ownership checks remain `send_message`'s.
+`interrupt_agent(agent_id)` passes `exec.agent` as the exact live ancestor authority for `ctx.subagents.interrupt()`: the target may be a direct child or a deeper descendant, and the service — never this tool — verifies the caller against the target Activation's recorded lineage. Only the target's current turn stops (`keepInbox`): queued messages stay parked until a later `send_message`, published descendants keep running, and the child stays available for follow-ups. The call returns as soon as the stop request is accepted, without waiting for target quiescence; an absent or already-settled target is an accepted no-op, while self, sibling, stale, and non-ancestor callers become errored results.
+
+`list_agents` takes one optional `scope` argument, derives the root id from the calling agent, and projects the service catalog to continuable children without a cursor. The default `children` scope reads `ctx.subagents.listChildren()`; `descendants` reads `ctx.subagents.listDescendants()`, whose one-corpus walk crosses ordinary sessions and one-shot children and renders surviving rows in stable pre-order with `parent=<id> depth=<n>`. The `parent` annotation is the durable direct-parent session id and may name an ordinary session omitted from the output. For the calling agent, only depth-1 child entries are `send_message` candidates; deeper child entries are `interrupt_agent` candidates only. Status comes from the live Agent registry: `running` (active driver), `idle` (resident between turns, possibly waiting on agents it started), `complete` (storage only). The service result also contains one-shot session-backed subagents for consumers such as a UI, but those entries are omitted from this model tool because they cannot accept `send_message`. Diagnostics remain visible, with positions in the descendants scope. Durable identity and mode come from each child's descriptor, while delivery-time authority and Activation ownership checks remain the service's.
 
 ## Model Experience
 
@@ -14,7 +16,7 @@ The tool performs no lifecycle routing — residency and cold resume belong to t
 
 #### What the model sees
 
-The generated [`send_message` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control): `subagent_id` and `message`, describing that the message becomes the subagent's next turn, that this call returns no answer from the subagent, and that a failure means the message was not delivered.
+The generated [schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control): `send_message` takes `subagent_id` and `message`, describing that the message becomes the subagent's next turn, that this call returns no answer from the subagent, and that a failure means the message was not delivered; `interrupt_agent` takes `agent_id`, describing that only the current turn stops, queued messages park, descendants keep running, and acceptance precedes the actual stop; `list_agents` takes the optional `scope` enum.
 
 #### Token effect
 
@@ -24,6 +26,20 @@ Fixed schema cost per parent request.
 
 Prefix-stable; the schema does not change at runtime.
 
+### Interrupt result
+
+#### What the model sees
+
+`interrupt requested for agent <agent_id>` on acceptance. An unauthorized caller — self, sibling, stale, or non-ancestor — is an errored result naming the rejection; an absent or settled target still renders the acceptance line.
+
+#### Token effect
+
+One short acknowledgement per call; the interrupted turn's abort is visible only in the child's own transcript.
+
+#### KV Cache effect
+
+Append-only; each result follows the reusable request prefix.
+
 ### Delivery result
 
 #### What the model sees
@@ -42,11 +58,11 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-One line per continuable child in the trace's stable order: `<id> [<status>] — <label>` (`running` = the logical session is live, `complete` = persisted only and resumable by `send_message`), plus `<id> [diagnostic: <reason>]` for a candidate that could not be read (`corrupt`, `unsupported`, or `unavailable`). One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection. Diagnostics never expose descriptor contents.
+One line per continuable child in stable catalog order: `<id> [<status>] — <label>` (`running` = active driver, `idle` = resident between turns, `complete` = storage only; a direct child in that state can be resumed by `send_message`), plus `<id> [diagnostic: <reason>]` for a candidate that could not be read (`corrupt`, `unsupported`, or `unavailable`). The `descendants` scope inserts ` parent=<id> depth=<n>` before the label dash on every line, in pre-order. One-shot children are intentionally absent; `(no subagents)` means no continuable child or diagnostic survived the projection. Diagnostics never expose descriptor contents.
 
 #### Token effect
 
-Grows linearly with the parent's direct continuable children; there is no cursor or cap, so long-lived parents with many persisted children pay the full list each call.
+Grows linearly with the listed continuable children — the whole tree under the `descendants` scope; there is no cursor or cap, so long-lived parents with many persisted children pay the full list each call.
 
 #### KV Cache effect
 
@@ -56,5 +72,5 @@ Append-only; each result follows the reusable request prefix.
 
 - **A queued message has no independent result** — acceptance returns only its inbox `messageId`; the child's work lands in the durable child Session and is never collected through this tool. A child granted `report` may send selected content back separately, but that message is not this call's result.
 - **No steering of the current turn** — every message opens a later FIFO turn, so a message sent while the child is working runs only after its current turn finishes and cannot redirect it.
-- **Listing is a snapshot, not a delivery promise** — it may race publication, disposal, or a later message, and another process may activate a child this process reports as `complete`; cross-process accuracy requires a shared lease.
+- **Listing is a snapshot, not a delivery promise** — it may race publication, disposal, or a later message, and another process may activate a child this process reports as `complete`; cross-process accuracy requires a shared lease. `interrupt_agent` performs the authoritative live-lineage check itself, so discovery staleness cannot grant authority.
 - **No pagination or deletion** — the complete stably ordered set is returned, and persisted children remain listed for as long as their sessions remain in persistence; a service-level bound or delete operation is a later product decision.
diff --git a/packages/subagent/tool-subagent-control/README.zh.md b/packages/subagent/tool-subagent-control/README.zh.md
index 2cc876c8b3..dc1c81fc33 100644
--- a/packages/subagent/tool-subagent-control/README.zh.md
+++ b/packages/subagent/tool-subagent-control/README.zh.md
@@ -2,11 +2,13 @@
 
 [English](README.md) | 中文
 
-可选的全局具名 `send_message` 与 `list_agents` 工具是 `ctx.subagents` 之上的轻量适配器。绑定提供方的 `@deepseek-ai/dsh-tool-subagent` 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 `send_message`，可单独加载的 `./list-agents` 插件注册 `list_agents`；两者都只要求 `subagents`，部署可保留 `send_message` 而省略列表工具。是否加载这些工具不会决定委派工具是否启动可继续工作。这些工具只负责父到子的方向；单独安装的 [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) 负责子到父的方向。
+可选的全局具名 `send_message`、`interrupt_agent` 与 `list_agents` 工具是 `ctx.subagents` 之上的轻量适配器。绑定提供方的 `@deepseek-ai/dsh-tool-subagent` 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 `send_message` 与 `interrupt_agent`，且只要求 `subagents`；可单独加载的 `./list-agents` 插件注册 `list_agents`，并将 `subagents` 与 `agents` 声明为加载时依赖。其目录读取在调用时还要求会话存储与投影注册表，但不要求任何查询服务。部署可保留根插件工具并省略列表工具。是否加载这些工具不会决定委派工具是否启动可继续工作。这些工具只负责父到子的方向；单独安装的 [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) 负责子到父的方向。
 
 本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源标记为持久化来源 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
 
-`list_agents` 不接受参数，会从调用它的 agent 推导 parent id，并且不使用 cursor，将 `ctx.subagents.listChildren()` 的结果投影为可继续 child。服务结果还包含由会话支撑的一次性 subagent，以供 UI 等消费方使用；但这些条目无法接受 `send_message`，因此会从这个模型工具中排除。diagnostic 仍然可见。持久化身份和模式来自每个子 agent 的描述符，消息送达时的鉴权和 Activation 所有权检查仍归 `send_message` 负责。
+`interrupt_agent(agent_id)` 将 `exec.agent` 作为 `ctx.subagents.interrupt()` 的确切在线 ancestor 授权传入：目标可以是直接 child 或更深的后代，由服务——而不是本工具——依据目标 Activation 记录的 lineage 校验调用方。只有目标的当前轮次会停止（`keepInbox`）：已排队的消息保持暂停直到之后的 `send_message`，已发布的后代继续运行，child 也仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标静止；目标不存在或已结算是被接受的 no-op，而 self、sibling、过期与非 ancestor 调用方会成为出错结果。
+
+`list_agents` 接受一个可选的 `scope` 参数，会从调用它的 agent 推导根 id，并且不使用 cursor，将服务目录投影为可继续 child。默认的 `children` scope 读取 `ctx.subagents.listChildren()`；`descendants` 读取 `ctx.subagents.listDescendants()`，其单份语料的遍历会穿过普通会话与一次性 child，并按稳定 pre-order 以 `parent=<id> depth=<n>` 渲染保留下来的条目。`parent` 注释是持久化直接 parent 会话 id，可能指向输出中省略的普通会话。对于调用本工具的 agent，只有 depth-1 child 条目可作为 `send_message` 候选；更深的 child 条目只能作为 `interrupt_agent` 候选。状态来自在线 Agent 注册表：`running`（driver 活跃）、`idle`（驻留但处于轮次之间，可能在等待它启动的 agent）、`complete`（仅存于存储）。服务结果还包含由会话支撑的一次性 subagent，以供 UI 等消费方使用；但这些条目无法接受 `send_message`，因此会从这个模型工具中排除。diagnostic 仍然可见，并在 descendants scope 中带有位置。持久化身份和模式来自每个子 agent 的描述符，消息送达时的鉴权和 Activation 所有权检查仍归服务负责。
 
 ## 模型体验
 
@@ -14,7 +16,7 @@
 
 #### 模型看到的内容
 
-已生成的 [`send_message` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control)：包含 `subagent_id` 和 `message`，说明消息会成为子 agent 的下一个轮次、本次调用不会返回子 agent 的回答，以及失败即表示消息未送达。
+已生成的 [schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent-control)：`send_message` 包含 `subagent_id` 和 `message`，说明消息会成为子 agent 的下一个轮次、本次调用不会返回子 agent 的回答，以及失败即表示消息未送达；`interrupt_agent` 包含 `agent_id`，说明只有当前轮次会停止、已排队消息保持暂停、后代继续运行，以及接受先于实际停止；`list_agents` 包含可选的 `scope` 枚举。
 
 #### Token 影响
 
@@ -24,6 +26,20 @@
 
 前缀保持稳定；schema 不会在运行时改变。
 
+### 中断结果
+
+#### 模型看到的内容
+
+接受时返回 `interrupt requested for agent <agent_id>`。未授权的调用方——self、sibling、过期或非 ancestor——会成为指明拒绝原因的出错结果；目标不存在或已结算仍渲染接受行。
+
+#### Token 影响
+
+每次调用产生一条简短确认消息；被中断轮次的中止只在 child 自己的 transcript 中可见。
+
+#### KV Cache 影响
+
+仅追加；每个结果都位于可复用请求前缀之后。
+
 ### 投递结果
 
 #### 模型看到的内容
@@ -42,11 +58,11 @@
 
 #### 模型看到的内容
 
-按追踪结果的稳定顺序，每个可继续 child 占一行：渲染为 `<id> [<status>] — <label>`（`running` 表示逻辑会话存活，`complete` 表示仅存在于持久化存储中，可通过 `send_message` 恢复），另为无法读取的候选项渲染 `<id> [diagnostic: <reason>]`（`corrupt`、`unsupported` 或 `unavailable`）。一次性 child 会被有意排除；`(no subagents)` 表示投影后没有留下可继续 child 或 diagnostic。诊断信息绝不会暴露描述符内容。
+按稳定目录顺序，每个可继续 child 占一行：渲染为 `<id> [<status>] — <label>`（`running` 表示 driver 活跃，`idle` 表示驻留但处于轮次之间，`complete` 表示仅存于存储；处于该状态的直接 child 可通过 `send_message` 恢复），另为无法读取的候选项渲染 `<id> [diagnostic: <reason>]`（`corrupt`、`unsupported` 或 `unavailable`）。`descendants` scope 会在每行 label 破折号之前插入 ` parent=<id> depth=<n>`，按 pre-order 排列。一次性 child 会被有意排除；`(no subagents)` 表示投影后没有留下可继续 child 或 diagnostic。诊断信息绝不会暴露描述符内容。
 
 #### Token 影响
 
-随 parent 的直接可继续 child 数量线性增长；没有 cursor 或上限，因此长期存活且有许多持久化 child 的 parent 每次调用都会承担完整列表成本。
+随所列可继续 child 数量线性增长——`descendants` scope 下为整棵树；没有 cursor 或上限，因此长期存活且有许多持久化 child 的 parent 每次调用都会承担完整列表成本。
 
 #### KV Cache 影响
 
@@ -56,5 +72,5 @@
 
 - **已排队的消息没有独立结果**：接受时只返回其 inbox `messageId`；子 agent 的工作会落入持久化子 agent 会话，绝不会通过本工具收集。获得 `report` 的子 agent 可以单独发回选定内容，但该消息不是本次调用的结果。
 - **不对当前轮次进行 steering（中途引导）**：每条消息都会开启后续 FIFO 轮次，因此在子 agent 工作时发送的消息只会在其当前轮次结束后运行，无法将其重定向。
-- **列表是快照，而非投递承诺**：它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `complete` 的 child；跨进程准确性需要共享租约。
+- **列表是快照，而非投递承诺**：它可能与发布、dispose（资源释放）或后续消息发生竞态，另一个进程也可能激活当前进程报告为 `complete` 的 child；跨进程准确性需要共享租约。`interrupt_agent` 自己执行权威的在线 lineage 检查，因此过期的发现结果不会授予权限。
 - **没有分页或删除**：系统返回完整且稳定排序的集合；只要 child 会话仍在持久化存储中，它就会继续出现在列表中，服务级上限或删除操作留待后续产品决策。
diff --git a/packages/subagent/tool-subagent-control/src/index.ts b/packages/subagent/tool-subagent-control/src/index.ts
index 95cf4e4183..43e3f52b4e 100644
--- a/packages/subagent/tool-subagent-control/src/index.ts
+++ b/packages/subagent/tool-subagent-control/src/index.ts
@@ -1,9 +1,11 @@
 /**
- * The globally named `send_message` tool: a thin model-facing adapter over
- * `ctx.subagents.followup()`. It performs no lifecycle routing of its own —
- * residency and cold resume belong to the subagent service — and it lives apart
- * from the provider-bound `@deepseek-ai/dsh-tool-subagent` instances so multiple
- * delegation tools share one control tool.
+ * The globally named `send_message` and `interrupt_agent` tools: thin
+ * model-facing adapters over `ctx.subagents.followup()` and
+ * `ctx.subagents.interrupt()`. They perform no lifecycle routing of their own —
+ * residency, cold resume, and interrupt authorization belong to the subagent
+ * service — and they live apart from the provider-bound
+ * `@deepseek-ai/dsh-tool-subagent` instances so multiple delegation tools share
+ * one control surface.
  * @module @deepseek-ai/dsh-tool-subagent-control
  */
 
@@ -17,7 +19,7 @@ export const name = 'tool-subagent-control'
 export const inject = ['tools', 'subagents']
 
 /**
- * Register the `send_message` tool.
+ * Register the `send_message` and `interrupt_agent` tools.
  * @param ctx - context carrying the tool registry and subagent service.
  */
 export function apply(ctx: Context): void {
@@ -73,4 +75,46 @@ export function apply(ctx: Context): void {
       return { messageId }
     },
   }))
+
+  ctx.tools.register(defineTool({
+    name: 'interrupt_agent',
+    description:
+      'Request cancellation of a background agent\'s current turn by its agent id. The target may be your '
+      + 'direct child or a deeper agent created under you. Only the current turn stops: messages already '
+      + 'queued for the agent stay parked until a later send_message, agents it started keep running, and '
+      + 'the agent itself stays available for follow-ups. This call returns as soon as the stop request is '
+      + 'accepted, so the target may keep running briefly; interrupting an agent that already finished is '
+      + 'an accepted no-op.',
+    parameters: {
+      agent_id: {
+        type: 'string',
+        required: true,
+        description: 'The agent id of the running agent to interrupt.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          accepted: { type: 'boolean', required: true },
+        },
+      },
+      render: (args, _value) => [{
+        type: 'text',
+        text: `interrupt requested for agent ${args.agent_id}`,
+      }],
+    },
+    execute(args, exec) {
+      const caller = exec.agent
+      if (!caller) {
+        // Ancestor authority requires an exact live calling agent.
+        throw new Error('interrupt_agent requires a calling agent (exec.agent was undefined)')
+      }
+      // The service authorizes the exact live caller against the target's
+      // recorded lineage; the tool adds no authority of its own.
+      ctx.subagents.interrupt(SessionId(args.agent_id), { kind: 'ancestor', agent: caller })
+      return Promise.resolve({ accepted: true })
+    },
+  }))
 }
diff --git a/packages/subagent/tool-subagent-control/src/list-agents.ts b/packages/subagent/tool-subagent-control/src/list-agents.ts
index bab3fb6f40..c39ebbc648 100644
--- a/packages/subagent/tool-subagent-control/src/list-agents.ts
+++ b/packages/subagent/tool-subagent-control/src/list-agents.ts
@@ -1,46 +1,95 @@
 /**
  * The globally named `list_agents` tool: a thin model-facing adapter over
- * the continuable projection of `ctx.subagents.listChildren()`. It stays
- * separately loadable from the root `send_message` plugin so a deployment
- * can register `send_message` without exposing the list tool.
+ * the continuable projection of `ctx.subagents.listChildren()` and, for the
+ * `descendants` scope, `ctx.subagents.listDescendants()`. It stays separately
+ * loadable from the root `send_message` plugin so a deployment can register
+ * continuation delivery without exposing discovery.
  * @module @deepseek-ai/dsh-tool-subagent-control/list-agents
  */
 
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type {} from '@deepseek-ai/dsh-subagent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { SubagentDescendantListEntry, SubagentListEntry } from '@deepseek-ai/dsh-subagent'
 
 export const name = 'tool-subagent-list-agents'
-export const inject = ['tools', 'subagents']
+export const inject = ['tools', 'subagents', 'agents']
 
 type ListAgentsEntry =
   | {
     readonly kind: 'child'
     readonly id: string
     readonly label: string
-    readonly status: 'running' | 'complete'
+    readonly status: 'running' | 'idle' | 'complete'
+    readonly parent?: string
+    readonly depth?: number
   }
   | {
     readonly kind: 'diagnostic'
     readonly id: string
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
+    readonly parent?: string
+    readonly depth?: number
   }
 
+/**
+ * Refine one candidate's status through the live Agent registry: `running`
+ * for an active driver, `idle` for a resident Agent between turns (possibly
+ * waiting on agents it started), and `complete` when no live Agent remains.
+ */
+function statusOf(agents: { get(id: SessionId): Agent | undefined }, id: SessionId): 'running' | 'idle' | 'complete' {
+  const agent = agents.get(id)
+  if (agent === undefined) return 'complete'
+  return agent.status === 'running' ? 'running' : 'idle'
+}
+
+/** Project one service row into the model-facing entry, or omit a one-shot child. */
+function project(
+  agents: { get(id: SessionId): Agent | undefined },
+  entry: SubagentListEntry,
+  position?: Pick<SubagentDescendantListEntry, 'parentId' | 'depth'>,
+): ListAgentsEntry | undefined {
+  const at = position === undefined ? {} : { parent: position.parentId as string, depth: position.depth }
+  if (entry.kind === 'diagnostic') {
+    return { kind: 'diagnostic', id: entry.id, reason: entry.reason, ...at }
+  }
+  // One-shot children cannot be continued by send_message, so the model
+  // never selects them; discovery still traversed them for descendants.
+  if (entry.mode !== 'continuable') return undefined
+  return {
+    kind: 'child',
+    id: entry.id,
+    label: entry.label,
+    status: statusOf(agents, entry.id),
+    ...at,
+  }
+}
+
 /**
  * Register the `list_agents` tool.
- * @param ctx - context carrying the tool registry and subagent service.
+ * @param ctx - context carrying the tool registry, subagent service, and live Agent registry.
  */
 export function apply(ctx: Context): void {
   ctx.tools.register(defineTool({
     name: 'list_agents',
     description:
-      'List your continuable background subagents by durable id and label. Status is a snapshot of the stored '
-      + 'record: running means the subagent session is currently live in this process, complete means '
-      + 'it exists only in storage and a `send_message` starts a new turn on the same conversation. '
-      + 'The snapshot is not a delivery promise — `send_message` performs the authoritative check and '
-      + 'may still fail. Children that could not be read are reported as diagnostics instead of being '
-      + 'silently dropped.',
-    parameters: {},
+      'List your continuable background subagents by durable id and label. Status comes from the live '
+      + 'registry: running means the agent is working right now, idle means it is loaded but between turns '
+      + '(it may be waiting on agents it started), and complete means it exists only in storage — a '
+      + 'direct child remains a `send_message` candidate in every status. The snapshot is not a delivery '
+      + 'promise — `send_message` performs the authoritative check and may still fail. Children that could '
+      + 'not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` '
+      + 'walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent '
+      + 'session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are '
+      + 'candidates for `interrupt_agent` only.',
+    parameters: {
+      scope: {
+        type: 'string',
+        enum: ['children', 'descendants'],
+        description: 'children (default) lists direct children only; descendants walks the complete tree below you.',
+      },
+    },
     output: {
       schema: {
         type: 'array',
@@ -53,7 +102,9 @@ export function apply(ctx: Context): void {
                 kind: { type: 'string', required: true, enum: ['child'] },
                 id: { type: 'string', required: true },
                 label: { type: 'string', required: true },
-                status: { type: 'string', required: true, enum: ['running', 'complete'] },
+                status: { type: 'string', required: true, enum: ['running', 'idle', 'complete'] },
+                parent: { type: 'string' },
+                depth: { type: 'number' },
               },
             },
             {
@@ -63,21 +114,31 @@ export function apply(ctx: Context): void {
                 kind: { type: 'string', required: true, enum: ['diagnostic'] },
                 id: { type: 'string', required: true },
                 reason: { type: 'string', required: true, enum: ['corrupt', 'unsupported', 'unavailable'] },
+                parent: { type: 'string' },
+                depth: { type: 'number' },
               },
             },
           ],
         },
       },
-      render: (_args, entries) => [{
+      render: (args, entries) => [{
         type: 'text',
         text: entries.length === 0
           ? '(no subagents)'
-          : entries.map(entry => entry.kind === 'child'
-            ? `${entry.id} [${entry.status}] — ${entry.label}`
-            : `${entry.id} [diagnostic: ${entry.reason}]`).join('\n'),
+          : entries.map((entry) => {
+            // A descendants row always carries its position; children rows
+            // never render it. String() spans the schema-optional shape
+            // without a dead fallback branch.
+            const at = args.scope === 'descendants'
+              ? ` parent=${String(entry.parent)} depth=${String(entry.depth)}`
+              : ''
+            return entry.kind === 'child'
+              ? `${entry.id} [${entry.status}]${at} — ${entry.label}`
+              : `${entry.id} [diagnostic: ${entry.reason}]${at}`
+          }).join('\n'),
       }],
     },
-    async execute(_args, exec) {
+    async execute(args, exec) {
       const parent = exec.agent
       if (!parent) {
         // Non-agent callers have no session whose children could be listed.
@@ -85,21 +146,16 @@ export function apply(ctx: Context): void {
       }
       // The registry drains started tool bodies, so the scan must observe the
       // call's signal rather than finish a slow catalog after cancellation.
-      const entries = await ctx.subagents.listChildren(parent.id, exec.signal)
-      const visible: ListAgentsEntry[] = []
-      for (const entry of entries) {
-        if (entry.kind === 'diagnostic') {
-          visible.push(entry)
-        } else if (entry.mode === 'continuable') {
-          visible.push({
-            kind: 'child',
-            id: entry.id,
-            label: entry.label,
-            status: entry.activity === 'running' ? 'running' : 'complete',
-          })
-        }
+      if (args.scope === 'descendants') {
+        const entries = await ctx.subagents.listDescendants(parent.id, exec.signal)
+        return entries
+          .map(entry => project(ctx.agents, entry, entry))
+          .filter(entry => entry !== undefined)
       }
-      return visible
+      const entries = await ctx.subagents.listChildren(parent.id, exec.signal)
+      return entries
+        .map(entry => project(ctx.agents, entry))
+        .filter(entry => entry !== undefined)
     },
   }))
 }
diff --git a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
index e734ae8222..3131809d37 100644
--- a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
@@ -12,9 +12,37 @@ import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import type { SubagentListEntry } from '@deepseek-ai/dsh-subagent'
 import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { LlmAdapter } from '@deepseek-ai/dsh-llm'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import * as tool from '../src/list-agents.ts'
 
+/** One scripted response that may wait on a caller-released gate before streaming. */
+interface GatedEntry {
+  chunks: StreamChunk[]
+  gate?: Promise<undefined>
+}
+
+/** Adapter whose entries can hold a model call open until the test releases it. */
+class GatedAdapter extends LlmAdapter {
+  readonly requests: GenerateOptions[] = []
+
+  constructor(private script: GatedEntry[]) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.requests.push(options)
+    const entry = this.script.shift()
+    if (!entry) throw new Error('GatedAdapter: script exhausted')
+    if (entry.gate) await entry.gate
+    for (const chunk of entry.chunks) {
+      if (options.signal?.aborted) throw new Error('aborted')
+      yield chunk
+    }
+  }
+}
+
 const testToolSignal = new AbortController().signal
 
 const roots: string[] = []
@@ -22,7 +50,7 @@ afterEach(() => {
   for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
 })
 
-async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
+async function setupWith(adapter: MockAdapter | GatedAdapter) {
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx)
   const root = mkdtempSync(join(tmpdir(), 'dsh-tool-list-agents-'))
@@ -33,9 +61,13 @@ async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
   await ctx.plugin(SubagentService)
   await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
   await ctx.plugin(tool)
-  ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
+  ctx.llm.registerAdapter(['mock'], adapter)
   const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
-  return { ctx, parent }
+  return { ctx, parent, adapter }
+}
+
+async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
+  return setupWith(new MockAdapter(script))
 }
 
 function text(result: { content: { type: string; text?: string }[] }): string {
@@ -67,13 +99,19 @@ async function waitNoActivation(ctx: Context, childId: SessionId): Promise<void>
 }
 
 describe('dsh-tool-subagent-control/list-agents', () => {
-  it('registers list_agents once, globally, with no parameters', async () => {
+  it('registers list_agents once, globally, with only the optional scope parameter', async () => {
     const { ctx } = await setup([])
     const schemas = ctx.tools.schemas().filter(schema => schema.name === 'list_agents')
     expect(schemas).toHaveLength(1)
-    const props = (schemas[0]!.parameters as { properties?: Record<string, unknown> }).properties ?? {}
-    expect(Object.keys(props)).toEqual([])
+    const parameters = schemas[0]!.parameters as {
+      properties?: Record<string, { enum?: string[] }>
+      required?: string[]
+    }
+    expect(Object.keys(parameters.properties ?? {})).toEqual(['scope'])
+    expect(parameters.properties?.scope?.enum).toEqual(['children', 'descendants'])
+    expect(parameters.required ?? []).toEqual([])
     expect(schemas[0]!.description).toContain('send_message')
+    expect(schemas[0]!.description).toContain('interrupt_agent')
   })
 
   it('renders the empty result as (no subagents)', async () => {
@@ -84,7 +122,7 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     expect(text(result)).toBe('(no subagents)')
   })
 
-  it('renders children and diagnostics in array order with the fixed text forms', async () => {
+  it('renders children and diagnostics in array order with registry-derived statuses', async () => {
     const { ctx, parent } = await setup([textResponse('done')])
     const started = await ctx.subagents.startContinuable({
       provider: 'spawn',
@@ -94,7 +132,8 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     })
     await waitNoActivation(ctx, started.childId)
     // Pin the render deterministically past the service: the tool is a thin
-    // adapter, so its fixed text forms are what this test pins.
+    // adapter, so its fixed text forms are what this test pins. Status comes
+    // from the live Agent registry, stubbed per candidate id.
     const entries: SubagentListEntry[] = [
       {
         kind: 'child',
@@ -120,14 +159,28 @@ describe('dsh-tool-subagent-control/list-agents', () => {
         activity: 'running',
         hasChildren: true,
       },
+      {
+        kind: 'child',
+        id: SessionId('waiting-child'),
+        label: 'waiting on descendants',
+        mode: 'continuable',
+        activity: 'running',
+        hasChildren: true,
+      },
       { kind: 'diagnostic', id: SessionId('broken-child'), reason: 'corrupt' },
     ]
     ctx.subagents.listChildren = () => Promise.resolve(entries)
+    const agents = new Map<string, { status: 'running' | 'idle' }>([
+      ['running-child', { status: 'running' }],
+      ['waiting-child', { status: 'idle' }],
+    ])
+    vi.spyOn(ctx.agents, 'get').mockImplementation(id => agents.get(id) as never)
     const result = await callTool(ctx, 'list_agents', {}, parent)
     expect(result.isError).toBe(false)
     expect(text(result)).toBe(
       `${started.childId} [complete] — real child\n`
       + 'running-child [running] — still working\n'
+      + 'waiting-child [idle] — waiting on descendants\n'
       + 'broken-child [diagnostic: corrupt]',
     )
   })
@@ -186,7 +239,101 @@ describe('dsh-tool-subagent-control/list-agents', () => {
   it('has the namespace-plugin export shape', () => {
     expect('default' in tool).toBe(false)
     expect(tool.name).toBe('tool-subagent-list-agents')
-    expect(tool.inject).toEqual(['tools', 'subagents'])
+    expect(tool.inject).toEqual(['tools', 'subagents', 'agents'])
     expect(typeof tool.apply).toBe('function')
   })
+
+  it('walks the complete descendant tree in pre-order with parent and depth annotations', async () => {
+    const releaseChild = Promise.withResolvers<undefined>()
+    const releaseGrandchild = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child'), gate: releaseChild.promise },
+      { chunks: textResponse('grandchild'), gate: releaseGrandchild.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'waiting branch',
+      request: { prompt: [{ type: 'text', text: 'branch work' }], parent },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const grandchild = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'nested leaf',
+      request: { prompt: [{ type: 'text', text: 'leaf work' }], parent: child },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    // The branch finishes its own turn but stays resident waiting on the
+    // grandchild it owns: the live-registry `idle` status.
+    releaseChild.resolve(undefined)
+    await vi.waitFor(() => {
+      expect(ctx.agents.get(started.childId)?.status).toBe('idle')
+    }, { timeout: 5_000 })
+
+    const result = await callTool(ctx, 'list_agents', { scope: 'descendants' }, parent)
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe(
+      `${started.childId} [idle] parent=${parent.id} depth=1 — waiting branch\n`
+      + `${grandchild.childId} [running] parent=${started.childId} depth=2 — nested leaf`,
+    )
+
+    releaseGrandchild.resolve(undefined)
+    await waitNoActivation(ctx, grandchild.childId)
+    await waitNoActivation(ctx, started.childId)
+  })
+
+  it('omits one-shot intermediates from descendants output while surfacing what they own', async () => {
+    const { ctx, parent } = await setup([])
+    // Deterministic service rows: a one-shot intermediate owning a continuable
+    // leaf, plus a positioned diagnostic. The tool filters only the one-shot.
+    ctx.subagents.listDescendants = () => Promise.resolve([
+      {
+        kind: 'child',
+        id: SessionId('one-shot-mid'),
+        label: 'one-shot intermediate',
+        mode: 'one-shot',
+        activity: 'inactive',
+        hasChildren: true,
+        parentId: parent.id,
+        depth: 1,
+      },
+      {
+        kind: 'child',
+        id: SessionId('deep-leaf'),
+        label: 'deep leaf',
+        mode: 'continuable',
+        activity: 'inactive',
+        hasChildren: false,
+        parentId: SessionId('one-shot-mid'),
+        depth: 2,
+      },
+      {
+        kind: 'diagnostic',
+        id: SessionId('broken-node'),
+        reason: 'unavailable',
+        parentId: parent.id,
+        depth: 1,
+      },
+    ])
+    const result = await callTool(ctx, 'list_agents', { scope: 'descendants' }, parent)
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe(
+      'deep-leaf [complete] parent=one-shot-mid depth=2 — deep leaf\n'
+      + `broken-node [diagnostic: unavailable] parent=${parent.id} depth=1`,
+    )
+  })
+
+  it('forwards the tool cancellation signal to descendant enumeration', async () => {
+    const { ctx, parent } = await setup([])
+    const signal = new AbortController().signal
+    const listDescendants = vi.spyOn(ctx.subagents, 'listDescendants').mockResolvedValue([])
+
+    const result = await callTool(ctx, 'list_agents', { scope: 'descendants' }, parent, signal)
+
+    expect(result.isError).toBe(false)
+    expect(listDescendants).toHaveBeenCalledWith(parent.id, signal)
+  })
 })
diff --git a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
index db674b0599..9b5f98dd7e 100644
--- a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
@@ -11,9 +11,37 @@ import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { LlmAdapter } from '@deepseek-ai/dsh-llm'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import * as tool from '../src/index.ts'
 
+/** One scripted response that may wait on a caller-released gate before streaming. */
+interface GatedEntry {
+  chunks: StreamChunk[]
+  gate?: Promise<undefined>
+}
+
+/** Adapter whose entries can hold a model call open until the test releases it. */
+class GatedAdapter extends LlmAdapter {
+  readonly requests: GenerateOptions[] = []
+
+  constructor(private script: GatedEntry[]) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.requests.push(options)
+    const entry = this.script.shift()
+    if (!entry) throw new Error('GatedAdapter: script exhausted')
+    if (entry.gate) await entry.gate
+    for (const chunk of entry.chunks) {
+      if (options.signal?.aborted) throw new Error('aborted')
+      yield chunk
+    }
+  }
+}
+
 const testToolSignal = new AbortController().signal
 
 const roots: string[] = []
@@ -21,7 +49,7 @@ afterEach(() => {
   for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
 })
 
-async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
+async function setupWith(adapter: MockAdapter | GatedAdapter) {
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx)
   const root = mkdtempSync(join(tmpdir(), 'dsh-tool-subagent-control-'))
@@ -32,12 +60,15 @@ async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
   await ctx.plugin(SubagentService)
   await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
   await ctx.plugin(tool)
-  const adapter = new MockAdapter(script)
   ctx.llm.registerAdapter(['mock'], adapter)
   const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent, adapter }
 }
 
+async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
+  return setupWith(new MockAdapter(script))
+}
+
 function text(result: { content: { type: string; text?: string }[] }): string {
   return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
 }
@@ -177,8 +208,10 @@ describe('dsh-tool-subagent-control', () => {
     await ctx.plugin(SubagentService)
     const fiber = await ctx.plugin(tool)
     expect(ctx.tools.schemas().some(schema => schema.name === 'send_message')).toBe(true)
+    expect(ctx.tools.schemas().some(schema => schema.name === 'interrupt_agent')).toBe(true)
     await fiber.dispose()
     expect(ctx.tools.schemas().some(schema => schema.name === 'send_message')).toBe(false)
+    expect(ctx.tools.schemas().some(schema => schema.name === 'interrupt_agent')).toBe(false)
   })
 
   it('has the namespace-plugin export shape (no stray default)', () => {
@@ -188,3 +221,168 @@ describe('dsh-tool-subagent-control', () => {
     expect(typeof tool.apply).toBe('function')
   })
 })
+
+describe('dsh-tool-subagent-control interrupt_agent', () => {
+  it('registers interrupt_agent with the single agent_id parameter and current-turn wording', async () => {
+    const { ctx } = await setup([])
+    const schemas = ctx.tools.schemas().filter(schema => schema.name === 'interrupt_agent')
+    expect(schemas).toHaveLength(1)
+    const props = (schemas[0]!.parameters as { properties?: Record<string, unknown> }).properties ?? {}
+    expect(Object.keys(props)).toEqual(['agent_id'])
+    expect(schemas[0]!.description).toContain('current turn')
+    expect(schemas[0]!.description).toContain('send_message')
+  })
+
+  it('interrupts a running direct child with the parent cause, parking its queue', async () => {
+    const releaseFirst = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('held'), gate: releaseFirst.promise },
+      { chunks: textResponse('parked answer') },
+      { chunks: textResponse('waking answer') },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'long work',
+      request: { prompt: [{ type: 'text', text: 'long work' }], parent },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const queued = await callTool(ctx, 'send_message', {
+      subagent_id: started.childId,
+      message: 'parked follow-up',
+    }, parent)
+    expect(queued.isError).toBe(false)
+    const cancelSpy = vi.spyOn(child, 'cancel')
+
+    const result = await callTool(ctx, 'interrupt_agent', { agent_id: started.childId }, parent)
+
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe(`interrupt requested for agent ${started.childId}`)
+    expect(cancelSpy).toHaveBeenCalledExactlyOnceWith({ kind: 'parent' }, { keepInbox: true })
+    releaseFirst.resolve(undefined)
+    await child.whenIdle()
+    // Parked, not resumed: the queued follow-up waits for a waking send.
+    expect(adapter.requests).toHaveLength(1)
+    expect(child.inbox.nextTurn).toHaveLength(1)
+
+    const waking = await callTool(ctx, 'send_message', {
+      subagent_id: started.childId,
+      message: 'wake up',
+    }, parent)
+    expect(waking.isError).toBe(false)
+    await waitNoActivation(ctx, started.childId)
+    const loaded = await ctx.sessionPersistence.load(started.childId)
+    const prompts = loaded.events.flatMap(event => event.type === 'user/message'
+      ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
+      : [])
+    expect(prompts).toEqual(['long work', 'parked follow-up', 'wake up'])
+  })
+
+  it('lets a deep live ancestor interrupt a descendant it did not directly create', async () => {
+    const releaseChild = Promise.withResolvers<undefined>()
+    const releaseGrandchild = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('child'), gate: releaseChild.promise },
+      { chunks: textResponse('grandchild'), gate: releaseGrandchild.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const started = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'child',
+      request: { prompt: [{ type: 'text', text: 'child work' }], parent },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const child = ctx.agents.get(started.childId)!
+    const grandchild = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'grandchild',
+      request: { prompt: [{ type: 'text', text: 'grandchild work' }], parent: child },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    const grandchildAgent = ctx.agents.get(grandchild.childId)!
+    const cancelSpy = vi.spyOn(grandchildAgent, 'cancel')
+
+    const result = await callTool(ctx, 'interrupt_agent', { agent_id: grandchild.childId }, parent)
+
+    expect(result.isError).toBe(false)
+    expect(cancelSpy).toHaveBeenCalledExactlyOnceWith({ kind: 'parent' }, { keepInbox: true })
+    releaseChild.resolve(undefined)
+    releaseGrandchild.resolve(undefined)
+    await waitNoActivation(ctx, grandchild.childId)
+    await waitNoActivation(ctx, started.childId)
+  })
+
+  it('rejects self, sibling, and unrelated callers without touching the target', async () => {
+    const releaseA = Promise.withResolvers<undefined>()
+    const releaseB = Promise.withResolvers<undefined>()
+    const adapter = new GatedAdapter([
+      { chunks: textResponse('a'), gate: releaseA.promise },
+      { chunks: textResponse('b'), gate: releaseB.promise },
+    ])
+    const { ctx, parent } = await setupWith(adapter)
+    const target = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'target',
+      request: { prompt: [{ type: 'text', text: 'a' }], parent },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
+    const sibling = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'sibling',
+      request: { prompt: [{ type: 'text', text: 'b' }], parent },
+      signal: testToolSignal,
+    })
+    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
+    const targetAgent = ctx.agents.get(target.childId)!
+    const siblingAgent = ctx.agents.get(sibling.childId)!
+    const stranger = ctx.agentLoop.create(SessionId('stranger'), { provider: 'mock', model: 'mock' })
+    const cancelSpy = vi.spyOn(targetAgent, 'cancel')
+
+    const self = await callTool(ctx, 'interrupt_agent', { agent_id: target.childId }, targetAgent)
+    expect(self.isError).toBe(true)
+    expect(text(self)).toContain('cannot interrupt itself')
+    const fromSibling = await callTool(ctx, 'interrupt_agent', { agent_id: target.childId }, siblingAgent)
+    expect(fromSibling.isError).toBe(true)
+    expect(text(fromSibling)).toContain('not a live descendant')
+    const fromStranger = await callTool(ctx, 'interrupt_agent', { agent_id: target.childId }, stranger)
+    expect(fromStranger.isError).toBe(true)
+    expect(text(fromStranger)).toContain('not a live descendant')
+    expect(cancelSpy).not.toHaveBeenCalled()
+
+    releaseA.resolve(undefined)
+    releaseB.resolve(undefined)
+    await waitNoActivation(ctx, target.childId)
+    await waitNoActivation(ctx, sibling.childId)
+  })
+
+  it('accepts an absent target as a no-op without cold-resuming it', async () => {
+    const { ctx, parent } = await setup([textResponse('done')])
+    const started = await ctx.subagents.startContinuable({
+      provider: 'spawn',
+      label: 'settled child',
+      request: { prompt: [{ type: 'text', text: 'child work' }], parent },
+      signal: testToolSignal,
+    })
+    await waitNoActivation(ctx, started.childId)
+
+    const settled = await callTool(ctx, 'interrupt_agent', { agent_id: started.childId }, parent)
+    expect(settled.isError).toBe(false)
+    expect(text(settled)).toBe(`interrupt requested for agent ${started.childId}`)
+    const unknown = await callTool(ctx, 'interrupt_agent', { agent_id: 'no-such-agent' }, parent)
+    expect(unknown.isError).toBe(false)
+    // No cold resume: the settled target never rematerialized.
+    expect(ctx.agents.get(started.childId)).toBeUndefined()
+  })
+
+  it('fails loud when invoked without a calling agent', async () => {
+    const { ctx } = await setup([])
+    const result = await callTool(ctx, 'interrupt_agent', { agent_id: 'x' })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('requires a calling agent')
+  })
+})
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index c8ddb487ef..6d9665236a 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -172,6 +172,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ContinuableStart: 'subagent.md',
   ContinuableStartSpec: 'subagent.md',
   CoordinatorMessageSource: 'subagent.md',
+  SubagentDescendantListEntry: 'subagent.md',
   SubagentFollowupOptions: 'subagent.md',
   SubagentInterruptAuthority: 'subagent.md',
   SubagentListEntry: 'subagent.md',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 74042fdf12..50419e416f 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -399,10 +399,11 @@ const TOOL_PACKAGES: ToolPackage[] = [
     pkg: '@deepseek-ai/dsh-tool-subagent-control',
     dir: 'tool-subagent-control',
     source: {
+      interrupt_agent: 'packages/subagent/tool-subagent-control/src/index.ts',
       list_agents: 'packages/subagent/tool-subagent-control/src/list-agents.ts',
       send_message: 'packages/subagent/tool-subagent-control/src/index.ts',
     },
-    requires: ['ctx.tools', 'ctx.subagents', 'ctx.sessionProjections (list_agents catalog rows)'],
+    requires: ['ctx.tools', 'ctx.subagents', 'ctx.agents and ctx.sessionProjections (list_agents only)'],
     writes: ['tool/call', 'tool/result', 'child session events through ctx.subagents'],
     async mount(ctx) {
       await ctx.plugin(SubagentService)
@@ -414,7 +415,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolSubagentListAgents)
     },
     note:
-      'The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows are served through the sessionProjections registry).',
+      'The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` and `interrupt_agent` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows use the sessionProjections and live Agent registries).',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-subagent-report',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 5c2f3eb454..9c99ed4632 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1155,6 +1155,11 @@
       "symbol": "SubagentInterruptAuthority",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentDescendantListEntry",
+      "source": "packages/subagent/subagent/src/list-children.ts"
+    },
     {
       "doc": "docs/core-data-structures/subagent.md",
       "symbol": "ContinuableStart",

From 5e1ec10d5a4f5a80bbf7c8a1c84aeef044e282de Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 15:00:35 +0800
Subject: [PATCH 279/516] fix(subagent): address descendant listing review

---
 .../snapshots/advanced-toolchain/system-prompt.expected.md      | 2 +-
 .../snapshots/advanced-toolchain/tool-schemas.expected.json     | 2 +-
 .../tests/snapshots/both-mode-turn/tool-schemas.expected.json   | 2 +-
 .../tests/snapshots/code-mode-turn/system-prompt.expected.md    | 2 +-
 .../tests/snapshots/lsp-definition/tool-schemas.expected.json   | 2 +-
 .../tests/snapshots/pty-tools/tool-schemas.expected.json        | 2 +-
 .../snapshots/session-query-spill/tool-schemas.expected.json    | 2 +-
 .../snapshots/subagent-continuable/tool-schemas.1.expected.json | 2 +-
 .../snapshots/subagent-list-agents/tool-schemas.1.expected.json | 2 +-
 .../snapshots/subagent-report/tool-schemas.1.expected.json      | 2 +-
 .../tests/snapshots/text-turn/tool-schemas.expected.json        | 2 +-
 .../tests/snapshots/web-fetch/tool-schemas.expected.json        | 2 +-
 packages/subagent/tool-subagent-control/package.json            | 2 +-
 13 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
index 2f33c0c6a5..b9fc8ec9d9 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
@@ -99,7 +99,7 @@ interface ToolArgsMap {
     /** The agent id of the running agent to interrupt. */
     agent_id: string;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent. */
+  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
index d1e5b75e45..70ab4e61f6 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
@@ -190,7 +190,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
index 890f3ee000..d5cbdc2ccc 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
index 5b74a88512..cb1b047e93 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
@@ -82,7 +82,7 @@ interface ToolArgsMap {
     /** The agent id of the running agent to interrupt. */
     agent_id: string;
   } & Record<string, JsonValue>;
-  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent. */
+  /** List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only. */
   list_agents: {
     /** children (default) lists direct children only; descendants walks the complete tree below you. */
     scope?: "children" | "descendants";
diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
index e41987451b..335be3672b 100644
--- a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
index 713353b91c..37d7d467be 100644
--- a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
index 09c637f077..7719bd3193 100644
--- a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
index 3283d98600..7dd791cf27 100644
--- a/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
index 3283d98600..7dd791cf27 100644
--- a/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
index 3283d98600..7dd791cf27 100644
--- a/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
index 6cea6864cd..e0b7a41bcf 100644
--- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
index f11131eb87..97c51af14b 100644
--- a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
@@ -133,7 +133,7 @@
     },
     {
       "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a `send_message` starts a new turn on the same conversation either way. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in creation order, annotating each entry with its parent agent id and depth so a deeper agent can be selected for send_message or interrupt_agent.",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/packages/subagent/tool-subagent-control/package.json b/packages/subagent/tool-subagent-control/package.json
index 8c7841ef63..2848a7d14d 100644
--- a/packages/subagent/tool-subagent-control/package.json
+++ b/packages/subagent/tool-subagent-control/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-tool-subagent-control",
-  "description": "Globally named send_message and list_agents tools over ctx.subagents continuations",
+  "description": "Globally named send_message, interrupt_agent, and list_agents tools over ctx.subagents continuations",
   "version": "0.0.1",
   "private": true,
   "type": "module",

From 656dbadbadda690c4aaf501a66d398287cc92bf5 Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 16:36:49 +0800
Subject: [PATCH 280/516] test(subagent): close descendant listing coverage

---
 .../subagent/subagent/src/list-children.ts    |  5 +-
 .../subagent/tests/list-children.spec.ts      | 46 +++++++++++++++++++
 2 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index db3339e197..bf259212bb 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -315,8 +315,9 @@ function descendantCandidates(
     .reverse()
   const visited = new Set<SessionId>([rootSessionId])
   while (stack.length > 0) {
-    const position = stack.pop()
-    if (position === undefined) break
+    // The length guard proves one frame exists.
+    // oxlint-disable-next-line typescript/no-non-null-assertion
+    const position = stack.pop()!
     const id = position.record.header.id
     if (visited.has(id)) continue
     visited.add(id)
diff --git a/packages/subagent/subagent/tests/list-children.spec.ts b/packages/subagent/subagent/tests/list-children.spec.ts
index 31c8f1c6aa..af37aba5f4 100644
--- a/packages/subagent/subagent/tests/list-children.spec.ts
+++ b/packages/subagent/subagent/tests/list-children.spec.ts
@@ -1009,6 +1009,52 @@ describe('SubagentService.listDescendants', () => {
     ])
   })
 
+  it('returns an empty result when the root has no descendants', async () => {
+    const { ctx, parent } = await setup([])
+    await ctx.sessions.flush(parent.session)
+    await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([])
+  })
+
+  it('omits a live creation-window candidate while continuing through its subtree', async () => {
+    const { ctx, parent } = await setup([])
+    const bareId = SessionId('live-creation-window')
+    const bare = ctx.sessions.create(bareId, {
+      meta: { createdAt: 1, parentSession: parent.id, origin: 'subagent' },
+    })
+    bare.append('turn/start', { turn: 1 })
+    const below = await authorChild(ctx, '00000000-0000-4000-8000-00000000aaaf', {
+      parentSession: bareId,
+      createdAt: 2,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('below the creation window')))
+
+    await expect(ctx.subagents.listDescendants(parent.id)).resolves.toEqual([{
+      kind: 'child', id: below, label: 'below the creation window', mode: 'continuable',
+      activity: 'inactive', hasChildren: false, parentId: bareId, depth: 2,
+    }])
+  })
+
+  it('contains a corrupt parent cycle without revisiting the requested root', async () => {
+    const { ctx } = await setup([])
+    const rootId = SessionId('cycle-root')
+    const nodeId = SessionId('cycle-node')
+    await authorChild(ctx, rootId, {
+      parentSession: nodeId,
+      createdAt: 2,
+    }, childEvents(descriptorPayload('ordinary cycle root')))
+    await authorChild(ctx, nodeId, {
+      parentSession: rootId,
+      createdAt: 1,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('cycle child')))
+
+    await expect(ctx.subagents.listDescendants(rootId)).resolves.toEqual([{
+      kind: 'child', id: nodeId, label: 'cycle child', mode: 'continuable',
+      activity: 'inactive', hasChildren: false, parentId: rootId, depth: 1,
+    }])
+  })
+
+
   it('walks a deeply nested ordinary-session chain without consuming the call stack', async () => {
     const { ctx, parent } = await setup([])
     const depth = 10_000

From 33c4d5a1641ecb09a4191cf1a7082024f6df263d Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 16:53:58 +0800
Subject: [PATCH 281/516] chore(docs): report the first stale catalog line

---
 scripts/gen-tool-catalog.ts | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 50419e416f..b59aafe5f0 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -655,6 +655,16 @@ async function main(): Promise<void> {
       process.exit(0)
     }
     console.error(`gen-tool-catalog: ${OUT} is stale. Run \`pnpm run gen-tool-catalog\` and commit ${OUT}.`)
+    const committedLines = committed?.split('\n') ?? []
+    const generatedLines = content.split('\n')
+    const lineCount = Math.max(committedLines.length, generatedLines.length)
+    for (let index = 0; index < lineCount; index += 1) {
+      if (committedLines[index] === generatedLines[index]) continue
+      console.error(`gen-tool-catalog: first difference at line ${index + 1}`)
+      console.error(`  committed: ${JSON.stringify(committedLines[index])}`)
+      console.error(`  generated: ${JSON.stringify(generatedLines[index])}`)
+      break
+    }
     process.exit(1)
   }
 

From ddea7b398ebce42020924b95df46e6d6af2e78bc Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Fri, 7 Aug 2026 17:04:10 +0800
Subject: [PATCH 282/516] docs: refresh tool catalog after stack merge

---
 docs/cordis-catalog/services.md               | 18 ++++-----
 docs/tool-catalog.md                          | 40 ++++++++++++++++---
 .../cordis/tool-cordis/src/api-catalog.ts     |  2 +-
 3 files changed, 45 insertions(+), 15 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index f4eead6f8e..a9077ae139 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2155,18 +2155,18 @@ listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<Subagent
 
 /**
  * Enumerate the root's complete session-backed subagent tree in stable
- * pre-order from one lineage trace, without loading or resuming an Agent.
- * Ordinary sessions and one-shot children are traversed so continuable
- * descendants below them are discovered; each returned entry adds its
- * verified `parentId` and root-relative `depth`. Cancellation follows the
- * same contract as {@link listChildren}.
+ * pre-order from one live-preferred corpus, without loading or resuming an
+ * Agent. Ordinary sessions and one-shot children remain traversal nodes so
+ * continuable descendants below them are discovered; each returned entry
+ * adds its durable `parentId` and root-relative `depth`. Identity resolution,
+ * diagnostics, optional persistence, and cancellation follow the same
+ * projection-backed contract as {@link listChildren}.
  * @param rootSessionId - session whose complete descendant tree is listed.
- * @param signal - caller-owned cancellation forwarded where supported and
- *   observed around every query await.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
  * @returns children and per-candidate diagnostics with tree position, in
  *   stable pre-order.
- * @throws {@link SubagentError} when session query is unavailable or the
- *   caller cancels the scan.
+ * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
  */
 listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
 
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 42b68bb6e8..adb73f104d 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -32,7 +32,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.agents`, `ctx.skills` | `tool/call`, `tool/result`, `user/message replacement catalogs via agent.inject()` | - | - |
 | `@deepseek-ai/dsh-tool-session-query` | `session_event_read`, `session_event_search`, `session_event_trace`, `session_search`, `session_trace` | `ctx.tools`, `ctx.systemPrompt`, `ctx.sessionQuery`, `a calling Agent for workspace authority` | `tool/call`, `tool/result` | - | The five read-only tools hide provider cursors and authorize every result from the immutable calling agent session. The package is opt-in; compositions that need enforced deadlines or bounded inline output also mount the generic timeout or spill policies. |
 | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `packages/bundle/base/cordis.patch.yml` and `examples/acp-agent/cordis.yml`. |
-| `@deepseek-ai/dsh-tool-subagent-control` | `list_agents`, `send_message` | `ctx.tools`, `ctx.subagents`, `ctx.sessionProjections (list_agents catalog rows)` | `tool/call`, `tool/result`, `child session events through ctx.subagents` | - | The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows are served through the sessionProjections registry). |
+| `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`, `list_agents`, `send_message` | `ctx.tools`, `ctx.subagents`, `ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`, `tool/result`, `child session events through ctx.subagents` | - | The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` and `interrupt_agent` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows use the sessionProjections and live Agent registries). |
 | `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`, `a live continuable in-process child Agent` | `tool/call`, `tool/result`, `a user-role message in the direct parent session` | - | Registered per continuable in-process child rather than globally, so this schema is visible only inside such a child and survives its global `toolFilter`. The parent-facing `send_message` tool is installed independently. |
 | `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `user/message via agent.inject() for background completion notices` | - | The kind-agnostic background-task control surface: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.start()`. |
 | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist. `allowParallelInProgress` is required with no default, so the catalog states its choice: `true`, whose description invites several `in_progress` items. A deployment choosing `false` receives the same tool with a description asking for exactly one active task. |
@@ -1193,14 +1193,44 @@ The registered tool name is the load-time `toolName` config (default `subagent`)
 
 ## `@deepseek-ai/dsh-tool-subagent-control`
 
-### `list_agents`
+### `interrupt_agent`
 
-List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.
+Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.
 
 ```json
 {
   "type": "object",
-  "properties": {}
+  "properties": {
+    "agent_id": {
+      "type": "string",
+      "description": "The agent id of the running agent to interrupt."
+    }
+  },
+  "required": [
+    "agent_id"
+  ]
+}
+```
+
+Source: [`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
+
+### `list_agents`
+
+List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "scope": {
+      "type": "string",
+      "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+      "enum": [
+        "children",
+        "descendants"
+      ]
+    }
+  }
 }
 ```
 
@@ -1232,7 +1262,7 @@ Send a message to a background subagent by its subagent id, continuing the same
 
 Source: [`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
 
-The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows are served through the sessionProjections registry).
+The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` and `interrupt_agent` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows use the sessionProjections and live Agent registries).
 
 ## `@deepseek-ai/dsh-tool-subagent-report`
 
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index f942e6650e..bf179462ee 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -950,7 +950,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>',
-        jsDoc: '/**\n * Enumerate the root\'s complete session-backed subagent tree in stable\n * pre-order from one lineage trace, without loading or resuming an Agent.\n * Ordinary sessions and one-shot children are traversed so continuable\n * descendants below them are discovered; each returned entry adds its\n * verified `parentId` and root-relative `depth`. Cancellation follows the\n * same contract as {@link listChildren}.\n * @param rootSessionId - session whose complete descendant tree is listed.\n * @param signal - caller-owned cancellation forwarded where supported and\n *   observed around every query await.\n * @returns children and per-candidate diagnostics with tree position, in\n *   stable pre-order.\n * @throws {@link SubagentError} when session query is unavailable or the\n *   caller cancels the scan.\n */',
+        jsDoc: '/**\n * Enumerate the root\'s complete session-backed subagent tree in stable\n * pre-order from one live-preferred corpus, without loading or resuming an\n * Agent. Ordinary sessions and one-shot children remain traversal nodes so\n * continuable descendants below them are discovered; each returned entry\n * adds its durable `parentId` and root-relative `depth`. Identity resolution,\n * diagnostics, optional persistence, and cancellation follow the same\n * projection-backed contract as {@link listChildren}.\n * @param rootSessionId - session whose complete descendant tree is listed.\n * @param signal - caller-owned cancellation forwarded to persistence reads\n *   and observed around every read await.\n * @returns children and per-candidate diagnostics with tree position, in\n *   stable pre-order.\n * @throws {@link SubagentError} under the same conditions as {@link listChildren}.\n */',
       },
       {
         signature: 'registerProvider(provider: SubagentProvider): () => void',

From 582fafee5a38ba16fe3440d7e1893c74a1ac49ef Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 20:25:41 +0800
Subject: [PATCH 283/516] test(snapshot): refresh subagent control schema pin

---
 .../tool-schemas.expected.json                | 31 +++++++++++++++++--
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json
index 81f30ee5ec..dc07c990aa 100644
--- a/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-child-question-rejection/tool-schemas.expected.json
@@ -179,11 +179,36 @@
       }
     },
     {
-      "name": "list_agents",
-      "description": "List your continuable background subagents by durable id and label. Status is a snapshot of the stored record: running means the subagent session is currently live in this process, complete means it exists only in storage and a `send_message` starts a new turn on the same conversation. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped.",
+      "name": "interrupt_agent",
+      "description": "Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.",
       "parameters": {
         "type": "object",
-        "properties": {}
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "The agent id of the running agent to interrupt."
+          }
+        },
+        "required": [
+          "agent_id"
+        ]
+      }
+    },
+    {
+      "name": "list_agents",
+      "description": "List your continuable background subagents by durable id and label. Status comes from the live registry: running means the agent is working right now, idle means it is loaded but between turns (it may be waiting on agents it started), and complete means it exists only in storage — a direct child remains a `send_message` candidate in every status. The snapshot is not a delivery promise — `send_message` performs the authoritative check and may still fail. Children that could not be read are reported as diagnostics instead of being silently dropped. Scope `descendants` walks the whole tree below you in stable pre-order, annotating each entry with its durable direct-parent session id and depth. You may use `send_message` only for depth-1 entries; deeper entries are candidates for `interrupt_agent` only.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+            "enum": [
+              "children",
+              "descendants"
+            ]
+          }
+        }
       }
     },
     {

From 3a05ddec7903c9562c13c350122f0dbac10a7b9b Mon Sep 17 00:00:00 2001
From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com>
Date: Sat, 8 Aug 2026 05:28:14 -0700
Subject: [PATCH 284/516] docs: compile the self-contained Task Surface model
 sketches

The doc-typecheck opt-out ratio gate now fails at 74/146 after merging
master. The model and branded-ID blocks are self-contained, so check
them as ordinary ts fences (72/146 remain opted out); re-record the
pairing sidecar.
---
 .../notes/proposed/feature/2026-08-04-task-surface.i18n.yaml  | 4 ++--
 .agents/notes/proposed/feature/2026-08-04-task-surface.md     | 4 ++--
 .agents/notes/proposed/feature/2026-08-04-task-surface.zh.md  | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml b/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
index fec93e2c36..7dc26f8fb7 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.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 .agents/notes/proposed/feature/2026-08-04-task-surface.md
-2026-08-04-task-surface.md: 0d79d7b830689a269d1aede937fba6aa647ea483
-2026-08-04-task-surface.zh.md: 7960c02dc3c112a8cd1ff626274dfac1f01f1bdb
+2026-08-04-task-surface.md: 72fc9e12f1a02f66a02d3335ad2e8d0d4c1c3dc2
+2026-08-04-task-surface.zh.md: 087c80195f75e145da93c5557afb43a421e1050d
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
index 0d79d7b830..72fc9e12f1 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.md
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.md
@@ -31,7 +31,7 @@ Short blocking questions remain with [`ask_user_question`](../../implemented/fea
 
 `TaskSurfaceModelV1` is JSON. It contains content blocks, input fields, and one submit label; it contains no code, callbacks, selectors, HTML, CSS, URLs to executable assets, or expression language. This type is unrelated to core Session's existing `SurfaceManager`/`SurfaceOp` message-reduction types; Task Surface is a product interaction protocol.
 
-```ts ignore-check
+```ts
 interface TaskSurfaceModelV1 {
   version: 1
   title: string
@@ -85,7 +85,7 @@ The tool definition omits `isConcurrencySafe`. Under the existing tool-registry
 
 The browser-safe domain package imports the type-only `Branded` primitive from `@deepseek-ai/dsh-brand` and owns all three Task Surface IDs. The canonical value is execution-local under the [canonical tool output contract](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md). Replay therefore uses `output.presentationMeta(args, value)` to persist this tagged payload with `tool/result.meta`:
 
-```ts ignore-check
+```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
 type TaskSurfaceId = Branded<'TaskSurfaceId'>
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
index 7960c02dc3..087c80195f 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
@@ -31,7 +31,7 @@ Status: proposed
 
 `TaskSurfaceModelV1` 使用 JSON。它包含内容块、输入字段和一个提交标签；不包含代码、回调、选择器、HTML、CSS、可执行产物的 URL，也不包含表达式语言。该类型与核心会话中现有的 `SurfaceManager`/`SurfaceOp` 消息归约类型无关；Task Surface 是一套产品交互协议。
 
-```ts ignore-check
+```ts
 interface TaskSurfaceModelV1 {
   version: 1
   title: string
@@ -85,7 +85,7 @@ Task Surface 服务通过受 schema 校验的配置定义限制。初始默认
 
 浏览器安全的领域包从 `@deepseek-ai/dsh-brand` 以仅类型方式导入 `Branded` 原语，并拥有全部三个 Task Surface ID。根据[规范工具输出契约](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
 
-```ts ignore-check
+```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
 type TaskSurfaceId = Branded<'TaskSurfaceId'>

From 5f755d57179f5a8386976a95835196c2ac195f9f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:16:37 +0800
Subject: [PATCH 285/516] fix(web): keep Send beside subagent Stop

---
 ...07-27-web-subagent-conversations.i18n.yaml |  4 +-
 .../2026-07-27-web-subagent-conversations.md  |  2 +-
 ...026-07-27-web-subagent-conversations.zh.md |  2 +-
 ...6-continuable-subagent-interrupt.i18n.yaml |  4 +-
 ...26-08-06-continuable-subagent-interrupt.md |  4 +-
 ...08-06-continuable-subagent-interrupt.zh.md |  4 +-
 .../offline-composer.expected.md              |  1 +
 apps/web/tests/subagent-interrupt-ui.e2e.ts   | 17 ++++----
 .../client/ui-conversation/README.i18n.yaml   |  4 +-
 packages/client/ui-conversation/README.md     |  2 +-
 packages/client/ui-conversation/README.zh.md  |  2 +-
 .../src/client/skeleton/InputBar.module.css   |  2 +-
 .../src/client/skeleton/InputBar.tsx          | 34 ++++++++++++----
 .../ui-conversation/tests/input-bar.spec.tsx  | 40 ++++++++++---------
 packages/client/ui-subagent/README.i18n.yaml  |  4 +-
 packages/client/ui-subagent/README.md         |  2 +-
 packages/client/ui-subagent/README.zh.md      |  2 +-
 17 files changed, 76 insertions(+), 54 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index 4ec9a77d72..4453cca8eb 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: da4de7d4bcd23f61459eba3fee8108b0af1c95f9
-2026-07-27-web-subagent-conversations.zh.md: 43d9710ec2b63a09bd3db029f172746d63d91cfe
+2026-07-27-web-subagent-conversations.md: 46c4949c56ebffe78e5ffda126a5784a1c648421
+2026-07-27-web-subagent-conversations.zh.md: 6b2d7bbec1133cdeb2d0cd31a6f9a43b068d21f5
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index da4de7d4bc..46c4949c56 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -45,7 +45,7 @@ Healthy rows reuse the standard session projections retained in the list mirror.
 
 Selecting a row records its exact address before opening the resident client `Session`. History pagination, event folding, tool render intents, titles, and live mux reconciliation reuse the ordinary conversation machinery. Breadcrumbs use catalog labels, follow parent links only through `origin: 'subagent'` rows, include the first ordinary owner, and keep ordinary forks single-level. Forking an addressed subagent creates an ordinary fork with direct source lineage and attaches it to the nearest workspace-owning ancestor. The catalog is an ARIA tree with lazy ArrowRight/ArrowLeft disclosure, linear ArrowUp/ArrowDown navigation, Home/End, Escape, and focus restoration.
 
-A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false and the child is not running; a running parent-offline child keeps the ordinary composer with its input disabled so the same primary Stop stays reachable, and the read-only takeover returns once it stops. With a live parent, Enter admits another FIFO turn even while the child runs, and the single primary action follows the ordinary running convention: Send while idle, Stop while running, routed through `subagent.interrupt` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Prompt failures retain the draft through the ordinary error behavior.
+A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false and the child is not running; a running parent-offline child keeps the ordinary composer with its input and Send action disabled so independent Stop stays reachable, and the read-only takeover returns once it stops. With a live parent, Enter and Send admit another FIFO turn even while the child runs, while independent Stop routes through `subagent.interrupt` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Prompt failures retain the draft through the ordinary error behavior.
 
 Agent-bound auxiliary controls are unavailable in addressed child views. In particular, the model selector and `/model` contribution do not call ordinary `session.models` or `session.selectModel`; the Host also rejects any accidental call instead of activating persisted child history outside the direct-parent continuation seam.
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index 43d9710ec2..6b2d7bbec1 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -45,7 +45,7 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 选择一行后，系统会先记录其确切地址，再打开常驻客户端 `Session`。历史分页、事件 fold、工具渲染意图、title 与实时 mux 归并都会复用普通对话机制。面包屑导航使用目录 label，只会沿 `origin: 'subagent'` 行的父链接逐级回溯，包含第一个普通 owner，并让普通 fork 保持单层。从已寻址 subagent 创建 fork 时，会生成具有直接源谱系的普通 fork，并将其附加到最近拥有 Workspace 的祖先。目录是一棵 ARIA 树，支持懒加载式 ArrowRight／ArrowLeft 展开与折叠、线性 ArrowUp／ArrowDown 导航、Home／End、Escape 以及焦点恢复。
 
-one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，只禁用其输入区，让同一个 primary Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 也会准入另一个 FIFO 轮次，而唯一的 primary 操作遵循普通运行约定：空闲时为 Send，运行时为 Stop，经由 `subagent.interrupt` 路由（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
+one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
 
 已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index dfdc2338ae..237d9fe4e4 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 0f663ac6a58b9c3d658aa572ca2fea18dbef6449
-2026-08-06-continuable-subagent-interrupt.zh.md: b8a5b557b73b2845e3c0b1dabdec0163f56eca48
+2026-08-06-continuable-subagent-interrupt.md: 5727d43526842b492633cc198f2a3bd01add126a
+2026-08-06-continuable-subagent-interrupt.zh.md: de1556acbc182e79e2afa8b7f587bb9fcc0d08e0
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 0f663ac6a5..5727d43526 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -39,10 +39,10 @@ A human or ancestor can stop a runaway continuable turn without losing the child
 
 The address-only RPC exposes one bit of live residency: an absent target is accepted while a live target under a mismatched parent returns `subagent-unauthorized`. The single-user local Host trust model accepts that observability; a future multi-principal Host must revisit both authority and response indistinguishability.
 
-The Web surface reuses the existing primary Send/Stop toggle rather than adding a second action: the client `Session.cancel()` routes a continuable address through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep `session.cancel`), and a running parent-offline continuable child keeps the default composer with disabled input so that same primary Stop remains reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract).
+The Web surface keeps Send and Stop as independent actions for a running continuable child: the client `Session.cancel()` routes Stop through `subagent.interrupt` (one-shot addresses stay uncancellable, ordinary sessions keep their existing primary Send/Stop toggle through `session.cancel`), while Send continues to queue follow-ups. A running parent-offline continuable child keeps the default composer with input and Send disabled but Stop reachable, returning to the read-only takeover once it stops ([Web subagent conversations](2026-07-27-web-subagent-conversations.md) owns the surrounding catalog and composer contract).
 
 The model-facing `interrupt_agent(agent_id)` tool in `dsh-tool-subagent-control` passes `exec.agent` as the `ancestor` authority and adds none of its own: the core primitive verifies live registry identity and recorded lineage, so the tool can name a direct child or a deeper descendant with the same generic `agent_id` parameter — deliberately not `subagent_id`, which would imply direct children only. Discovery rides `list_agents({ scope: 'descendants' })` over the new `SubagentService.listDescendants()` one-trace pre-order walk with verified `parentId`/`depth` per entry ([durable catalog note](2026-07-22-durable-subagent-catalog-and-list-agents.md) owns the listing contract); discovery is a hint, never authority. `send_message` keeps its exact-direct-parent authority — only interrupt is ancestor-wide.
 
 ## Testing
 
-Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar Send/Stop toggle with the parent-offline locked-input state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar's independent Send and Stop actions with the parent-offline locked-input/Send state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove queued Send, the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index b8a5b557b7..de1556acbc 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -39,10 +39,10 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 仅凭地址的 RPC 会暴露一位在线驻留信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
 
-Web 侧复用现有的 primary Send/Stop 切换而不新增第二个操作：客户端 `Session.cancel()` 将 continuable 地址路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍走 `session.cancel`）；parent 离线但仍在运行的 continuable child 保留默认 composer 并禁用其输入区，让同一个 primary Stop 保持可达，停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。
+在 Web 侧，正在运行的 continuable child 使用相互独立的 Send 与 Stop 操作：客户端 `Session.cancel()` 将 Stop 路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍通过 `session.cancel` 保留既有的 primary Send/Stop 切换），同时 Send 继续将后续消息加入队列。parent 离线但仍在运行的 continuable child 保留默认 composer，禁用输入区与 Send，但 Stop 仍然可达；停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。
 
 `dsh-tool-subagent-control` 中面向模型的 `interrupt_agent(agent_id)` 工具把 `exec.agent` 作为 `ancestor` 授权传入，自身不增加任何权限：核心原语校验在线注册表身份与记录的 lineage，因此该工具可以用同一个通用 `agent_id` 参数指定直接 child 或更深的后代——刻意不用会暗示仅限直接 child 的 `subagent_id`。发现依赖 `list_agents({ scope: 'descendants' })`，其底层是新的 `SubagentService.listDescendants()` 单次追踪 pre-order 遍历，每个条目带经校验的 `parentId`／`depth`（列表契约由[持久化目录 note](2026-07-22-durable-subagent-catalog-and-list-agents.md)拥有）；发现只是提示，绝非权限。`send_message` 保持其确切直接 parent 权限——只有中断是 ancestor 级的。
 
 ## Testing
 
-`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的 Send/Stop 切换及 parent 离线时锁定输入的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的独立 Send 与 Stop 操作及 parent 离线时锁定输入区和 Send 的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明 Send 入队、中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
diff --git a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
index a0baa9a44f..a977afbbea 100644
--- a/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
+++ b/apps/web/tests/snapshots/subagent-interrupt/offline-composer.expected.md
@@ -20,3 +20,4 @@
   - img
 - 'button "Access mode, current: Workspace Write" [disabled]': Workspace Write
 - button "Stop generating"
+- button "Send message" [disabled]
diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts
index be72f6546b..265462bdf7 100644
--- a/apps/web/tests/subagent-interrupt-ui.e2e.ts
+++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts
@@ -1,7 +1,7 @@
-// Web e2e scenario: the composer's primary action interrupts a running
+// Web e2e scenario: the composer's independent Stop interrupts a running
 // continuable child. The child holds its model turn open through a replay
-// hang entry; the browser proves the single primary Send/Stop toggle, the
-// parent-offline disabled-input-with-Stop composer, the subagent.interrupt
+// hang entry; the browser proves Send and Stop coexist, the parent-offline
+// disabled-Send-with-Stop composer, the subagent.interrupt
 // (never session.cancel) transport, the parked follow-up, and the FIFO resume
 // on a waking send.
 //
@@ -155,7 +155,7 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     if (failures.length > 1) throw new AggregateError(failures, 'subagent interrupt UI teardown failed')
   })
 
-  it('locks input but keeps the same primary Stop when the parent is offline', async () => {
+  it('locks Send but keeps independent Stop when the parent is offline', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-offline'))
     // Simulate a parent that went offline: the catalog delivers
     // parentAvailable: false while the child Activation stays live (the
@@ -177,11 +177,12 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
       })
       await input.waitFor({ timeout: 15_000 })
       expect(await input.isDisabled()).toBe(true)
-      // Still exactly one primary action, and it is an enabled Stop.
       const stop = page.getByRole('button', { name: 'Stop generating' })
       expect(await stop.count()).toBe(1)
       expect(await stop.isEnabled()).toBe(true)
-      expect(await page.getByRole('button', { name: 'Send message' }).count()).toBe(0)
+      const send = page.getByRole('button', { name: 'Send message' })
+      expect(await send.count()).toBe(1)
+      expect(await send.isDisabled()).toBe(true)
       await compareOrRefreshGolden(
         OFFLINE_COMPOSER_EXPECTED,
         await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd),
@@ -203,11 +204,11 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     await input.waitFor({ timeout: 15_000 })
     expect(await input.isDisabled()).toBe(false)
 
-    // Queue a follow-up while the turn is open; the primary stays Stop.
+    // Queue a follow-up through Send while independent Stop remains available.
     const promptResponse = page.waitForResponse(response =>
       new URL(response.url()).pathname === '/api/subagent.prompt')
     await input.fill(FOLLOWUP)
-    await input.press('Enter')
+    await page.getByRole('button', { name: 'Send message' }).click()
     expect(((await (await promptResponse).json()) as { result: { ok: boolean } }).result)
       .toMatchObject({ ok: true })
 
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 35cc21ba04..822a02d321 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 3e3a6b1a09cbed77700fb656882178efd3744a80
-README.zh.md: f3f25426156b3778859ec8f64e8d947362b967ab
+README.md: f5cf9b72b4f8f4ce7b1a07c0c1e30f5213edf678
+README.zh.md: 90c4dc4cc169b2cbcd7e94275a692e3d062cfe98
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 3e3a6b1a09..f5cf9b72b4 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -34,7 +34,7 @@ Keyboard message submission resolves delivery from the addressed session's runni
 
 Per-session UI state for selection and the active view lives in the declared chat store (`stores.ts` `createChatStore`); the InputHub owns the composer state machine and mirrors its draft into that store for persistence. Apply passes one store handle to the strict session subtree, chat view, and details registrations, so each session shares one instance and the framework owns its lifecycle. Components are pure: the framework standard kit supplies `useSession`/`sessionId`, global `useSessions`/`useWorkspaces`, and the input machine's `useInput`/`inputActions`; store faces and inject factories supply the remaining state and callbacks.
 
-The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop button), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The leading plus button is a Command launcher, not an attachment surface: it asks the session's `SlashController` to open only the `/` trigger's `command` source over the current textarea selection, while ui-slash's existing `MenuView` remains the sole floating menu and pick path. No file row, file input, upload protocol, or second menu component is introduced. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `conversation` locale namespace this package registers (the `placeholder.plan` / `hint.plan` keys) and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar renders inert (machine faces absent, `disabled` owner prop) instead of swapping in a parallel disabled tree, so the textarea DOM survives the workspace pick; the strict-session control seats simply stay empty until a session exists.
+The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop controls), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The leading plus button is a Command launcher, not an attachment surface: it asks the session's `SlashController` to open only the `/` trigger's `command` source over the current textarea selection, while ui-slash's existing `MenuView` remains the sole floating menu and pick path. No file row, file input, upload protocol, or second menu component is introduced. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `conversation` locale namespace this package registers (the `placeholder.plan` / `hint.plan` keys) and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar renders inert (machine faces absent, `disabled` owner prop) instead of swapping in a parallel disabled tree, so the textarea DOM survives the workspace pick; the strict-session control seats simply stay empty until a session exists.
 
 The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. The same window fold averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy moved off the row onto the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index f3f2542615..90c4dc4cc1 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -34,7 +34,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。
 
-输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止按钮之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。前置加号按钮是 Command launcher，而非附件入口：它要求当前会话的 `SlashController` 基于 textarea 当前 selection，只打开 `/` trigger 的 `command` source，同时 ui-slash 既有的 `MenuView` 仍是唯一的浮层菜单与 pick 路径。不引入 File 行、file input、上传协议或第二套菜单组件。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `conversation` locale 命名空间（`placeholder.plan` / `hint.plan` 键）本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。
+输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止控件之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。前置加号按钮是 Command launcher，而非附件入口：它要求当前会话的 `SlashController` 基于 textarea 当前 selection，只打开 `/` trigger 的 `command` source，同时 ui-slash 既有的 `MenuView` 仍是唯一的浮层菜单与 pick 路径。不引入 File 行、file input、上传协议或第二套菜单组件。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `conversation` locale 命名空间（`placeholder.plan` / `hint.plan` 键）本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。
 
 聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。同一次窗口折算还会把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率从统计行移到了 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当分子与路由容量都已知时才渲染；点击弹出的面板把「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列。圆环与标题读取 `projectedTokens`——把提供方样本沿此后表层的增减推进到当下——因此压缩会立刻反映出来，而不必再等一整轮；组成明细行仍是纯启发式，因此加起来依然不等于标题数字（[原理](../../llm/token-meter/README.md)）。占用率是刻意为之的近似值：分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测。
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index 6ab387c3eb..3bbba68dd8 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -10,7 +10,7 @@
 
 /* Floating capsule input (figma Input_Bottom 75:8208): card floats above the
    viewport bottom inside the centered message column; textarea on top, action
-   row below, one primary circle button bottom-right. Input width rides the
+   row below, primary action controls bottom-right. Input width rides the
    column (--dsh-composer-card-max-width = chat content + 32px, 16px per side,
    is a cap, not a fixed size — layout rule: the box shrinks with the center
    column keeping its clearance). Hero variant = the same card centered in the
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 21abce0e38..78db735f61 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -84,7 +84,7 @@ export function InputBar({
   const permissions = useProjection('permissions')
 
   // A continuable child without its live parent cannot accept human input,
-  // but its primary Stop below stays available while it runs.
+  // but its independent Stop below stays available while it runs.
   const continuable = subagent?.address.mode === 'continuable'
   const parentOffline = continuable && !subagent.parentAvailable
   // Queue cut 1: running input stays free; locked = session removed, the
@@ -354,12 +354,14 @@ export function InputBar({
     if (el !== null) toggleCommandMenu?.(selectionOf(el))
   }
 
-  // Ordinary sessions and continuable children stop through the same primary
-  // action; one-shot children stay send-and-stop-free (read-only takeover).
-  const stopping = running && (subagent === null || continuable)
-  const primaryLabel = stopping ? t('input.stop') : t('input.send')
+  // Ordinary sessions retain their primary Send/Stop toggle. A continuable
+  // child keeps Send as the primary action and exposes Stop independently so
+  // pointer users can queue follow-ups while its current turn is running.
+  const primaryStops = running && subagent === null
+  const interruptible = running && continuable
+  const primaryLabel = primaryStops ? t('input.stop') : t('input.send')
   const onPrimary = (): void => {
-    if (stopping) {
+    if (primaryStops) {
       stop?.()
       return
     }
@@ -528,16 +530,32 @@ export function InputBar({
             {renderSlot('conversation.input.model', { locked: modelSeatLocked })}
             <ContextMeter useProjection={useProjection} t={t} />
             {/* {machineBusy && <span className={css.pending} data-input-pending aria-label="处理中" />} */}
+            {interruptible && (
+              <Tooltip label={t('input.stop')} side="top" delayMs={500}>
+                <button
+                  type="button"
+                  className={css.primary}
+                  aria-label={t('input.stop')}
+                  disabled={stop === undefined}
+                  onMouseDown={keepFocus}
+                  onClick={stop}
+                >
+                  <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden>
+                    <rect x="3" y="3" width="10" height="10" rx="3" fill="currentColor" />
+                  </svg>
+                </button>
+              </Tooltip>
+            )}
             <Tooltip label={primaryLabel} side="top" delayMs={500}>
               <button
                 type="button"
                 className={css.primary}
                 aria-label={primaryLabel}
-                disabled={stopping ? stop === undefined : empty || disabled || machineBusy}
+                disabled={primaryStops ? stop === undefined : empty || disabled || machineBusy}
                 onMouseDown={keepFocus}
                 onClick={onPrimary}
               >
-                {stopping ? (
+                {primaryStops ? (
                   <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden>
                     <rect x="3" y="3" width="10" height="10" rx="3" fill="currentColor" />
                   </svg>
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index 89f0d0a5f4..1e7c3a1ba1 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 // InputBar behavior over the machine wiring: Enter-send semantics (IME guard,
 // Shift newline, busy Enter policy, Ctrl/Meta steering, repeat suppression), running
-// semantics (input stays free; primary turns stop), the machine pending lock,
+// semantics (input stays free; continuable children keep Send beside Stop), the machine pending lock,
 // decoration backdrop, error/notice strips, and the focus-keeping mousedown.
 
 import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest'
@@ -143,12 +143,14 @@ function bench(over?: BenchOptions) {
   }
   const view = render(<InputBar {...props} />)
   const textarea = view.container.querySelector('textarea')!
-  const stopping = over?.running === true
-    && (over.subagent === undefined || over.subagent.address.mode === 'continuable')
+  const primaryStops = over?.running === true && over.subagent === undefined
   const button = view.container.querySelector<HTMLButtonElement>(
-    `button[aria-label="${stopping ? '停止生成' : '发送消息'}"]`,
+    `button[aria-label="${primaryStops ? '停止生成' : '发送消息'}"]`,
   )!
-  return { view, textarea, button, props, sink, shell, wiring: shell, session, stop, slotCalls, menuLauncher }
+  const interruptButton = view.container.querySelector<HTMLButtonElement>('button[aria-label="停止生成"]')
+  return {
+    view, textarea, button, interruptButton, props, sink, shell, wiring: shell, session, stop, slotCalls, menuLauncher,
+  }
 }
 
 describe('Enter semantics', () => {
@@ -251,8 +253,8 @@ describe('running and lock semantics (queue cut 1)', () => {
     expect(ctrl.sink).toHaveBeenCalledWith('also queue', 'queue')
   })
 
-  it('running continuable subagent turns the same primary into Stop while typing stays free', () => {
-    const { button, textarea, sink, stop } = bench({
+  it('running continuable subagent keeps Send beside an independent Stop', () => {
+    const { button, interruptButton, textarea, sink, stop } = bench({
       running: true,
       draft: '后续消息',
       subagent: {
@@ -264,19 +266,17 @@ describe('running and lock semantics (queue cut 1)', () => {
         parentAvailable: true,
       },
     })
-    // One primary action only: Send switched to Stop, no side-by-side interrupt.
-    expect(button.getAttribute('aria-label')).toBe('停止生成')
+    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(interruptButton).not.toBeNull()
     expect(textarea.disabled).toBe(false)
     fireEvent.click(button)
-    expect(stop).toHaveBeenCalledTimes(1)
-    expect(sink).not.toHaveBeenCalled()
-    // Enter still queues the follow-up while the primary offers Stop.
-    fireEvent.keyDown(textarea, { key: 'Enter' })
     expect(sink).toHaveBeenCalledWith('后续消息', 'queue')
+    fireEvent.click(interruptButton!)
+    expect(stop).toHaveBeenCalledTimes(1)
   })
 
-  it('parent-offline running continuable locks the input but keeps the same primary Stop usable', () => {
-    const { button, textarea, stop, view } = bench({
+  it('parent-offline running continuable locks Send but keeps independent Stop usable', () => {
+    const { button, interruptButton, textarea, stop, view } = bench({
       running: true,
       draft: '',
       subagent: {
@@ -291,14 +291,15 @@ describe('running and lock semantics (queue cut 1)', () => {
     expect(textarea.disabled).toBe(true)
     expect(textarea.placeholder).toBe('父会话已离线，无法继续发送；仍可停止当前运行')
     expect((view.getByLabelText('命令') as HTMLButtonElement).disabled).toBe(true)
-    expect(button.getAttribute('aria-label')).toBe('停止生成')
-    expect(button.disabled).toBe(false)
-    fireEvent.click(button)
+    expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(button.disabled).toBe(true)
+    expect(interruptButton?.disabled).toBe(false)
+    fireEvent.click(interruptButton!)
     expect(stop).toHaveBeenCalledTimes(1)
   })
 
   it('running one-shot subagent never exposes Stop', () => {
-    const { button, stop } = bench({
+    const { button, interruptButton, stop } = bench({
       running: true,
       draft: '不可停止',
       subagent: {
@@ -311,6 +312,7 @@ describe('running and lock semantics (queue cut 1)', () => {
       },
     })
     expect(button.getAttribute('aria-label')).toBe('发送消息')
+    expect(interruptButton).toBeNull()
     expect(stop).not.toHaveBeenCalled()
   })
 
diff --git a/packages/client/ui-subagent/README.i18n.yaml b/packages/client/ui-subagent/README.i18n.yaml
index d1b0852953..992fac46f8 100644
--- a/packages/client/ui-subagent/README.i18n.yaml
+++ b/packages/client/ui-subagent/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/client/ui-subagent/README.md
-README.md: de55963bbe356e18a4e2b653be823cc5015c1bb7
-README.zh.md: ce4244db094bb8b602b854289ec000477bf45f0b
+README.md: abd94eb7a3b5e7c4d6d79f7a2ed5f95d471e64e2
+README.zh.md: 8686902819918c9637a8aa87d5135135a8dd4996
diff --git a/packages/client/ui-subagent/README.md b/packages/client/ui-subagent/README.md
index de55963bbe..abd94eb7a3 100644
--- a/packages/client/ui-subagent/README.md
+++ b/packages/client/ui-subagent/README.md
@@ -6,7 +6,7 @@ Web subagent feature owner: contributes the lazily expandable catalog tree to `c
 
 The header action reads `subagentsByParent` and session summaries through the standard `useSessions` hook. After a non-empty direct catalog arrives, its trigger counts the complete subagent-only descendant lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. The compact tree remains direct-catalog authoritative: continuable and one-shot rows display mode plus `running`/`inactive` activity and an optional log-backed title, while the trailing column stacks total durable provider usage above active-turn duration. Token totals sum the four disjoint `tokenUsage` buckets. Visual duration stays exact to the second below one day, then uses at most two adjacent units—days/hours, approximate months/days, or approximate years/months—while hover and the accessible name retain the exact day/hour/minute/second value. Duration sums completed `subagentTiming` turns, advances once per second only for an open turn on a running child, and freezes after the child becomes inactive; an interrupted open turn is bounded by its same-cut `active.through`, never by newer session metadata. An unlabeled one-shot row falls back to its session id, while corrupt, unsupported, or unavailable rows remain readable but disabled. Each healthy row's `hasChildren` hint determines disclosure before interaction, so known leaves never show an arrow; a catalog level reserves the disclosure column only when at least one healthy row is a branch, allowing branchless levels to start at the leading status marker. Expanding a branch immediately reserves one disabled loading row per known direct descendant, then lazily replaces them with that child's authoritative catalog. Every visible branch is reported to the runtime so membership frames cause a debounced refresh only where the tree is being consumed. Selecting any depth calls `SessionsService.openSubagent()` with the row's exact `{parentSessionId, childSessionId, mode}` address. Component-local state owns tree visibility, expanded branches, keyboard focus, and the running-duration clock. ArrowRight/ArrowLeft expand and collapse branches; ArrowUp/ArrowDown, Home, End, and Escape navigate or close the tree; closing returns focus to the trigger. Styling uses tokens only.
 
-A one-shot child always elects a read-only composer that identifies the transcript as a completed execution record. A continuable child does so only when its exact parent is unavailable and the child is not running, with copy explaining the recovery path; while such a child still runs, the selector yields to the ordinary composer, whose input is disabled but whose primary Stop stays usable, and the takeover returns once it stops. A continuable child with a live parent keeps the ordinary input chrome, whose Session routes prompts through `subagent.prompt`: typing stays free while the child runs because every follow-up joins the child's FIFO inbox, and the single primary action follows the ordinary convention — Send while idle, Stop while running, routed through `subagent.interrupt`. This package never receives host context or calls a model-facing tool. The catalog and composer behavior are specified by the [Web subagent conversations Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) and the [current-turn interrupt Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md).
+A one-shot child always elects a read-only composer that identifies the transcript as a completed execution record. A continuable child does so only when its exact parent is unavailable and the child is not running, with copy explaining the recovery path; while such a child still runs, the selector yields to the ordinary composer, whose input and Send action are disabled but whose independent Stop stays usable, and the takeover returns once it stops. A continuable child with a live parent keeps the ordinary input chrome, whose Session routes prompts through `subagent.prompt`: typing and Send stay available while the child runs because every follow-up joins the child's FIFO inbox, while an independent Stop routes through `subagent.interrupt`. This package never receives host context or calls a model-facing tool. The catalog and composer behavior are specified by the [Web subagent conversations Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) and the [current-turn interrupt Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md).
 
 Subagent-origin Session rows are omitted from the ordinary sidebar, so the parent header catalog is their navigation entry point. Ordinary forks remain in the sidebar.
 
diff --git a/packages/client/ui-subagent/README.zh.md b/packages/client/ui-subagent/README.zh.md
index ce4244db09..8686902819 100644
--- a/packages/client/ui-subagent/README.zh.md
+++ b/packages/client/ui-subagent/README.zh.md
@@ -6,7 +6,7 @@ Web subagent 功能 owner：向 `conversation.session.header.actions` 贡献可
 
 页头操作通过标准 `useSessions` 钩子读取 `subagentsByParent` 与会话摘要。非空直接目录到达后，其触发器会统计仅含 subagent 的完整后代谱系，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。紧凑树仍以直接目录为权威依据：可继续和 one-shot 行会显示 mode、`running`／`inactive` 活动状态和由日志支撑的可选 title，尾随列则在上行显示提供方的持久化 token 用量总计，在下行显示活跃轮次耗时。token 用量总计为四个互不重叠的 `tokenUsage` 桶之和。视觉耗时在不足一天时精确到秒，达到一天后则最多使用两个相邻单位——天／小时、近似月份／天或近似年份／月份——而悬停信息与无障碍名称会保留精确的天／小时／分钟／秒数值。耗时会累加已完成的 `subagentTiming` 轮次，仅在运行中 child 存在未结束轮次时每秒递增一次，并在 child 变为 inactive 后冻结；被中断的未结束轮次以其同一切面的 `active.through` 为上界，绝不使用更新的会话元数据。没有 label 的 one-shot 行会回退到其会话 id，而损坏、不受支持或不可用的行仍保持可读但禁用。每个健康行的 `hasChildren` 提示会在交互前决定是否显示展开控件，因此已知叶子节点从不显示箭头；每层目录仅在其中至少一个健康行是分支时才预留展开列，使完全不含分支的层级能从最前面的状态标记开始。展开分支时，会立即为每个已知直接后代预留一行禁用的加载行，随后再用该 child 的权威目录懒加载结果替换这些占位行。每个可见分支都会上报给运行时，使成员帧只在树正被消费的位置触发去抖动刷新。选择任意深度的条目都会使用该行的确切地址 `{parentSessionId, childSessionId, mode}` 调用 `SessionsService.openSubagent()`。组件局部状态负责树的可见性、已展开分支、键盘焦点与运行中耗时时钟。ArrowRight／ArrowLeft 展开和折叠分支；ArrowUp／ArrowDown、Home、End 与 Escape 用于导航或关闭树；关闭后焦点返回触发器。样式只使用 token。
 
-one-shot child 始终选用只读编辑器，并将 transcript（文本记录）说明为已完成的执行记录。可继续 child 仅在其确切 parent 不可用且 child 未在运行时选用只读编辑器，并以文案说明恢复路径；此类 child 仍在运行期间，selector 会让位给普通编辑器——其输入区被禁用，但 primary Stop 保持可用，停止后只读替代恢复。确切 parent 存活时，可继续 child 保留普通输入 chrome，其会话通过 `subagent.prompt` 路由提示词：child 运行期间输入保持自由，因为每条后续消息都会进入 child 的 FIFO inbox，而唯一的 primary 操作遵循普通约定——空闲时为 Send，运行时为 Stop，经由 `subagent.interrupt` 路由。本包绝不接收宿主上下文，也不调用面向模型的工具。目录与编辑器行为由 [Web subagent 对话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) 与[当前轮次中断 Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md) 规定。
+one-shot child 始终选用只读编辑器，并将 transcript（文本记录）说明为已完成的执行记录。可继续 child 仅在其确切 parent 不可用且 child 未在运行时选用只读编辑器，并以文案说明恢复路径；此类 child 仍在运行期间，selector 会让位给普通编辑器——其输入区与 Send 操作被禁用，但独立的 Stop 保持可用，停止后只读替代恢复。确切 parent 存活时，可继续 child 保留普通输入 chrome，其会话通过 `subagent.prompt` 路由提示词：child 运行期间输入和 Send 保持可用，因为每条后续消息都会进入 child 的 FIFO inbox，而独立的 Stop 经由 `subagent.interrupt` 路由。本包绝不接收宿主上下文，也不调用面向模型的工具。目录与编辑器行为由 [Web subagent 对话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) 与[当前轮次中断 Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md) 规定。
 
 普通侧边栏会省略带 subagent origin 的会话行，因此 parent 页头目录是它们的导航入口。普通 fork 仍保留在侧边栏中。
 

From ce16cf1b3bd943ac53c89a74d4a7602b06d217a2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:25:20 +0800
Subject: [PATCH 286/516] test(web): exercise interrupt with parent offline

---
 ...6-continuable-subagent-interrupt.i18n.yaml |  4 +-
 ...26-08-06-continuable-subagent-interrupt.md |  2 +-
 ...08-06-continuable-subagent-interrupt.zh.md |  2 +-
 apps/web/tests/subagent-interrupt-ui.e2e.ts   | 92 ++++++++++++++-----
 4 files changed, 73 insertions(+), 27 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 237d9fe4e4..6a415c2516 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 5727d43526842b492633cc198f2a3bd01add126a
-2026-08-06-continuable-subagent-interrupt.zh.md: de1556acbc182e79e2afa8b7f587bb9fcc0d08e0
+2026-08-06-continuable-subagent-interrupt.md: 79397ac58d9bc1a117053f05f1a5b7971c48cfbb
+2026-08-06-continuable-subagent-interrupt.zh.md: 2b29895c21bf2290b750bdce6979dbe2d76635a7
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 5727d43526..79397ac58d 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -45,4 +45,4 @@ The model-facing `interrupt_agent(agent_id)` tool in `dsh-tool-subagent-control`
 
 ## Testing
 
-Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar's independent Send and Stop actions with the parent-offline locked-input/Send state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold a real child turn open with a replay hang entry and prove queued Send, the interrupt transport, the aborted `turn/end`, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar's independent Send and Stop actions with the parent-offline locked-input/Send state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold real child turns open with replay hang entries and prove the parent-offline UI-to-RPC abort path, queued Send, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index de1556acbc..2b29895c21 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -45,4 +45,4 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 ## Testing
 
-`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的独立 Send 与 Stop 操作及 parent 离线时锁定输入区和 Send 的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）用 replay hang 条目保持真实 child 轮次打开，端到端证明 Send 入队、中断传输、中止的 `turn/end`、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的独立 Send 与 Stop 操作及 parent 离线时锁定输入区和 Send 的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）通过多条 replay hang 条目保持多个真实 child 轮次打开，端到端证明 parent 离线时从 UI 到 RPC 的中止路径、Send 入队、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts
index 265462bdf7..f289b062e3 100644
--- a/apps/web/tests/subagent-interrupt-ui.e2e.ts
+++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts
@@ -19,7 +19,7 @@ import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import {
   acknowledgeReloadConnectionLoss, assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
   launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
@@ -33,8 +33,11 @@ const OFFLINE_COMPOSER_EXPECTED = join(SNAPSHOT_DIR, 'offline-composer.expected.
 const MODE = webSnapshotMode()
 const LABEL = 'event-sourcing researcher'
 const INITIAL = 'Explain event sourcing in one sentence.'
+const REARM = 'Keep working until I stop you again.'
+const REARM_WAKE = 'Start that queued work now.'
 const FOLLOWUP = 'Now give the same explanation to a human reader.'
 const WAKING = 'And add one concrete example.'
+const REARMED_ANSWER = 're-armed setup answer'
 const PARKED_ANSWER = 'parked follow-up answer'
 const WAKING_ANSWER = 'waking answer'
 
@@ -47,6 +50,23 @@ async function waitFor(predicate: () => boolean, what: string, timeoutMs = 30_00
   }
 }
 
+/** Resolve on one exact child's next aborted turn end. */
+function waitForAbortedTurn(scaffold: WebScaffold, childId: SessionId): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      off()
+      reject(new Error('interrupt did not reach an aborted turn/end'))
+    }, 30_000)
+    const off = scaffold.ctx.on('session/event', (session: { id: SessionId }, event: SessionEvent) => {
+      if (session.id !== childId || event.type !== 'turn/end') return
+      clearTimeout(timer)
+      off()
+      if (event.data.reason.kind === 'aborted') resolve()
+      else reject(new Error(`expected an aborted turn/end, got ${event.data.reason.kind}`))
+    })
+  })
+}
+
 /** One text-only scripted model completion (no tool calls: real tools are mounted). */
 function textCompletion(text: string): object {
   return {
@@ -66,6 +86,8 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
   let browser: Browser
   let page: Page
   let sidecarRoot: string
+  let rearmedReadyFile: string
+  let parent: Agent
   let childId: SessionId
   let tripwire: ReturnType<typeof watchConsole>
   const apiCalls: string[] = []
@@ -73,10 +95,13 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
   beforeAll(async () => {
     sidecarRoot = await mkdtemp(join(tmpdir(), 'dsh-web-subagent-interrupt-ui-'))
     const readyFile = join(sidecarRoot, 'hang-ready')
-    // The child claims this whole-script replacement: held turn 1, then the
-    // parked follow-up and waking turns.
+    rearmedReadyFile = join(sidecarRoot, 'hang-rearmed-ready')
+    // The child claims this whole-script replacement: the offline and online
+    // interrupt paths each hold one turn, then the parked and waking turns settle.
     await writeFile(join(sidecarRoot, 'replay.override.json'), JSON.stringify([
       { kind: 'hang', readyFile },
+      { kind: 'hang', readyFile: rearmedReadyFile },
+      textCompletion(REARMED_ANSWER),
       textCompletion(PARKED_ANSWER),
       textCompletion(WAKING_ANSWER),
     ]))
@@ -113,8 +138,9 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
     await connectFreshWorkspace(page, scaffold.workspaceCwd)
 
-    const parent = scaffold.ctx.agents.roots()[0]
-    if (parent === undefined) throw new Error('fresh workspace did not publish its parent Agent')
+    const root = scaffold.ctx.agents.roots()[0]
+    if (root === undefined) throw new Error('fresh workspace did not publish its parent Agent')
+    parent = root
     // The child's first model call claims the primary override and holds.
     const started = await scaffold.ctx.subagents.startContinuable({
       provider: 'spawn',
@@ -155,7 +181,7 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     if (failures.length > 1) throw new AggregateError(failures, 'subagent interrupt UI teardown failed')
   })
 
-  it('locks Send but keeps independent Stop when the parent is offline', async () => {
+  it('interrupts the live child through the parent-offline composer', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-offline'))
     // Simulate a parent that went offline: the catalog delivers
     // parentAvailable: false while the child Activation stays live (the
@@ -188,6 +214,37 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
         await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd),
         MODE,
       )
+
+      // Keep the continuable Activation resident after this first abort. The
+      // direct setup queue does not change the parent-offline UI contract: its
+      // input and Send remain disabled throughout the exercised browser path.
+      await scaffold.ctx.subagents.followup(
+        parent,
+        childId,
+        [{ type: 'text', text: REARM }],
+        { source: { kind: 'user' }, signal: new AbortController().signal },
+      )
+      const aborted = waitForAbortedTurn(scaffold, childId)
+      const interruptResponse = page.waitForResponse(response =>
+        new URL(response.url()).pathname === '/api/subagent.interrupt')
+      await stop.click()
+      expect(((await (await interruptResponse).json()) as {
+        result: { ok: boolean; value?: { accepted: boolean } }
+      }).result).toMatchObject({ ok: true, value: { accepted: true } })
+      expect(apiCalls.filter(path => path === '/api/session.cancel')).toEqual([])
+      await aborted
+      await expect.poll(() => scaffold.ctx.agents.get(childId)?.status, { timeout: 15_000 }).toBe('idle')
+
+      // Wake the parked setup message only after cancellation converges. A
+      // second hang keeps the parent-available case independent from this stop.
+      await scaffold.ctx.subagents.followup(
+        parent,
+        childId,
+        [{ type: 'text', text: REARM_WAKE }],
+        { source: { kind: 'user' }, signal: new AbortController().signal },
+      )
+      await waitFor(() => existsSync(rearmedReadyFile), 'the re-armed child turn to open')
+      expect(scaffold.ctx.agents.get(childId)?.status).toBe('running')
     } finally {
       await page.unroute(pattern)
     }
@@ -212,19 +269,7 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     expect(((await (await promptResponse).json()) as { result: { ok: boolean } }).result)
       .toMatchObject({ ok: true })
 
-    const aborted = new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        off()
-        reject(new Error('interrupt did not reach an aborted turn/end'))
-      }, 30_000)
-      const off = scaffold.ctx.on('session/event', (session: { id: SessionId }, event: SessionEvent) => {
-        if (session.id !== childId || event.type !== 'turn/end') return
-        clearTimeout(timer)
-        off()
-        if (event.data.reason.kind === 'aborted') resolve()
-        else reject(new Error(`expected an aborted turn/end, got ${event.data.reason.kind}`))
-      })
-    })
+    const aborted = waitForAbortedTurn(scaffold, childId)
     const stop = page.getByRole('button', { name: 'Stop generating' })
     expect(await stop.count()).toBe(1)
     const interruptResponse = page.waitForResponse(response =>
@@ -242,13 +287,14 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     await expect.poll(() => scaffold.ctx.agents.get(childId)?.status, { timeout: 15_000 }).toBe('idle')
     const child = scaffold.ctx.agents.get(childId)
     expect(child).toBeDefined()
-    expect(child!.inbox.nextTurn).toHaveLength(1)
-    expect(child!.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1)
+    expect(child!.inbox.nextTurn).toHaveLength(2)
+    expect(child!.session.events.filter(event => event.type === 'turn/start')).toHaveLength(2)
     await page.getByRole('button', { name: 'Send message' }).waitFor({ timeout: 15_000 })
 
     // Only the waking send resumes the parked queue, FIFO, to settlement.
     await input.fill(WAKING)
     await input.press('Enter')
+    await expect.poll(() => page.getByText(REARMED_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
     await expect.poll(() => page.getByText(PARKED_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
     await expect.poll(() => page.getByText(WAKING_ANSWER, { exact: true }).count(), { timeout: 30_000 }).toBe(1)
     await expect.poll(() => scaffold.ctx.agents.get(childId), { timeout: 60_000 }).toBeUndefined()
@@ -258,11 +304,11 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
       && event.data.source.kind === 'user'
       ? event.data.content.flatMap(block => block.type === 'text' ? [block.text] : [])
       : [])
-    expect(userTexts).toEqual([INITIAL, FOLLOWUP, WAKING])
+    expect(userTexts).toEqual([INITIAL, REARM, REARM_WAKE, FOLLOWUP, WAKING])
     const turnEndKinds = loaded.events
       .filter(event => event.type === 'turn/end')
       .map(event => event.data.reason.kind)
-    expect(turnEndKinds).toEqual(['aborted', 'completed', 'completed'])
+    expect(turnEndKinds).toEqual(['aborted', 'aborted', 'completed', 'completed', 'completed'])
     expect(tripwire.pageErrors).toEqual([])
   }, 120_000)
 

From 07fbc2cda8132e4b68a5a8f9ce05a0ad7d6ac645 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:30:03 +0800
Subject: [PATCH 287/516] test(subagent): execute control tools in ACP replay

---
 ...6-continuable-subagent-interrupt.i18n.yaml |  4 +-
 ...26-08-06-continuable-subagent-interrupt.md |  2 +-
 ...08-06-continuable-subagent-interrupt.zh.md |  2 +-
 examples/acp-agent/tests/acp.snapshot.ts      |  7 ++--
 .../snapshots/subagent-list-agents/input.json |  2 +-
 .../subagent-list-agents/session.jsonl        | 40 ++++++++++++-------
 6 files changed, 34 insertions(+), 23 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 6a415c2516..3fccf77cc4 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.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 .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
-2026-08-06-continuable-subagent-interrupt.md: 79397ac58d9bc1a117053f05f1a5b7971c48cfbb
-2026-08-06-continuable-subagent-interrupt.zh.md: 2b29895c21bf2290b750bdce6979dbe2d76635a7
+2026-08-06-continuable-subagent-interrupt.md: cb97a77434b43ee71fa30deee9811f7a45c53f1a
+2026-08-06-continuable-subagent-interrupt.zh.md: ee05afd963584331def8c7d6acfa26830b7c1d0f
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
index 79397ac58d..cb97a77434 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
@@ -45,4 +45,4 @@ The model-facing `interrupt_agent(agent_id)` tool in `dsh-tool-subagent-control`
 
 ## Testing
 
-Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar's independent Send and Stop actions with the parent-offline locked-input/Send state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold real child turns open with replay hang entries and prove the parent-offline UI-to-RPC abort path, queued Send, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshots pin the new tool schemas in every recorded request header.
+Core coverage in `packages/subagent/subagent/tests/continuation.spec.ts` proves the durable `turn/end` abort, parked-then-FIFO-resumed queue, untouched descendant, both authority kinds with their cancel causes, self/sibling/stale/non-ancestor rejection, absent/one-shot/disposal-race no-ops, and the unchanged `keepInbox` loop behavior. Host coverage in `packages/host/apiproxy/tests` proves the RPC calls only the core primitive (no agents/catalog/history reads), the `subagent-unauthorized`/`internal` mappings, the wire schema's continuable-mode fence, and carrier round-trips. Client coverage pins the address-routed `Session.cancel()`, the InputBar's independent Send and Stop actions with the parent-offline locked-input/Send state, and the read-only-composer selector's running exception; the keyless assembled Web scenarios (`apps/web/tests/subagent-interrupt.e2e.ts`, `subagent-interrupt-ui.e2e.ts`) hold real child turns open with replay hang entries and prove the parent-offline UI-to-RPC abort path, queued Send, the parked follow-up, and the FIFO resume end to end. Tool coverage in `packages/subagent/tool-subagent-control/tests` proves direct and deep ancestor interrupts with the `parent` cause and parked queue, self/sibling/stranger rejection without touching the target, absent-target no-ops without cold resume, and the descendants listing's pre-order positions; the keyless ACP snapshot executes `list_agents({ scope: 'descendants' })` and `interrupt_agent` through the assembled application against one settled child, while recorded request headers continue to pin both schemas.
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index 2b29895c21..ee05afd963 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -45,4 +45,4 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 ## Testing
 
-`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的独立 Send 与 Stop 操作及 parent 离线时锁定输入区和 Send 的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）通过多条 replay hang 条目保持多个真实 child 轮次打开，端到端证明 parent 离线时从 UI 到 RPC 的中止路径、Send 入队、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照把新工具 schema 固定在每个已录制请求 header 中。
+`packages/subagent/subagent/tests/continuation.spec.ts` 中的核心覆盖证明了持久化 `turn/end` 中止、队列先暂停后按 FIFO 恢复、后代不受影响、两种授权及其取消 cause、self/sibling/stale/非 ancestor 拒绝、absent/一次性/disposal 竞态 no-op，以及 `keepInbox` 循环行为不变。`packages/host/apiproxy/tests` 中的 Host 覆盖证明 RPC 只调用核心原语（不读 agents/目录/历史）、`subagent-unauthorized`／`internal` 映射、wire schema 的 continuable 模式围栏以及 carrier 往返。客户端覆盖固定按地址路由的 `Session.cancel()`、InputBar 的独立 Send 与 Stop 操作及 parent 离线时锁定输入区和 Send 的状态，以及只读 composer selector 的运行例外；keyless 组装 Web 场景（`apps/web/tests/subagent-interrupt.e2e.ts`、`subagent-interrupt-ui.e2e.ts`）通过多条 replay hang 条目保持多个真实 child 轮次打开，端到端证明 parent 离线时从 UI 到 RPC 的中止路径、Send 入队、follow-up 暂停以及 FIFO 恢复。`packages/subagent/tool-subagent-control/tests` 中的工具覆盖证明直接与更深 ancestor 以 `parent` cause 中断并暂停队列、self/sibling/陌生调用方被拒绝且不触碰目标、目标不存在时 no-op 且不冷恢复，以及 descendants 列表的 pre-order 位置；keyless ACP 快照通过组装应用，针对一个已结算的 child 执行 `list_agents({ scope: 'descendants' })` 与 `interrupt_agent`，同时已录制的请求 header 仍固定这两个 schema。
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index c09dd7d2ed..62a1a674d5 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -336,9 +336,10 @@ const SCENARIOS: Scenario[] = [
   },
   // Authored durable-catalog transcript: the snapshot-only lifecycle marker
   // fences the second parent turn behind the child's Activation end, so
-  // `list_agents` deterministically reads the persisted child as complete.
-  // The tool itself executes for real against the control service, session
-  // query, and JSONL persistence; the marker is not model-visible.
+  // `list_agents({ scope: 'descendants' })` deterministically reads the
+  // persisted child as complete, then `interrupt_agent` executes its accepted
+  // no-op against that settled id. Both tools run through the assembled control
+  // service; the marker is not model-visible.
   {
     name: 'subagent-list-agents',
     hasModelTurn: true,
diff --git a/examples/acp-agent/tests/snapshots/subagent-list-agents/input.json b/examples/acp-agent/tests/snapshots/subagent-list-agents/input.json
index ff7832f3b9..b3b1d8e170 100644
--- a/examples/acp-agent/tests/snapshots/subagent-list-agents/input.json
+++ b/examples/acp-agent/tests/snapshots/subagent-list-agents/input.json
@@ -16,7 +16,7 @@
     },
     {
       "op": "prompt",
-      "text": "Call list_agents once and observe the subagent you started. Then reply with the single word DONE. Do not call any other tool."
+      "text": "Call list_agents once with scope set to descendants and observe the subagent you started. Then call interrupt_agent once with agent_id set to 33333333-3333-4333-8333-333333333333. Then reply with the single word DONE. Do not call any other tool."
     }
   ]
 }
diff --git a/examples/acp-agent/tests/snapshots/subagent-list-agents/session.jsonl b/examples/acp-agent/tests/snapshots/subagent-list-agents/session.jsonl
index 1a0113e440..f1deec5af9 100644
--- a/examples/acp-agent/tests/snapshots/subagent-list-agents/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/subagent-list-agents/session.jsonl
@@ -26,26 +26,36 @@
 {"type":"assistant/message","seq":24,"time":1785730454820,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"STARTED"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"2ee459fa-21f9-48c6-a42e-3c38eca1e4c9"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[19,20,21,22,23],"surfaceOp":"append"}
 {"type":"step/end","seq":25,"time":1785730454821,"data":{"turn":1,"step":2}}
 {"type":"turn/end","seq":26,"time":1785730454821,"data":{"turn":1,"reason":{"kind":"completed"}}}
-{"type":"agent/inbox/spliced","seq":27,"time":1785730454857,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Call list_agents once and observe the subagent you started. Then reply with the single word DONE. Do not call any other tool."}],"source":{"kind":"user"},"role":"user","id":"3bcac2a3-e0db-465b-94b4-4e2761236475"}]}}
+{"type":"agent/inbox/spliced","seq":27,"time":1785730454857,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Call list_agents once with scope set to descendants and observe the subagent you started. Then call interrupt_agent once with agent_id set to 33333333-3333-4333-8333-333333333333. Then reply with the single word DONE. Do not call any other tool."}],"source":{"kind":"user"},"role":"user","id":"3bcac2a3-e0db-465b-94b4-4e2761236475"}]}}
 {"type":"turn/start","seq":28,"time":1785821412840,"data":{"turn":2}}
 {"type":"agent/inbox/spliced","seq":29,"time":1785821412840,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","seq":30,"time":1785730454863,"data":{"turn":2,"step":1}}
-{"type":"user/message","seq":31,"time":1785730454863,"data":{"content":[{"type":"text","text":"Call list_agents once and observe the subagent you started. Then reply with the single word DONE. Do not call any other tool."}],"source":{"kind":"user"},"role":"user","id":"3bcac2a3-e0db-465b-94b4-4e2761236475"},"surfaceOp":"append"}
+{"type":"user/message","seq":31,"time":1785730454863,"data":{"content":[{"type":"text","text":"Call list_agents once with scope set to descendants and observe the subagent you started. Then call interrupt_agent once with agent_id set to 33333333-3333-4333-8333-333333333333. Then reply with the single word DONE. Do not call any other tool."}],"source":{"kind":"user"},"role":"user","id":"3bcac2a3-e0db-465b-94b4-4e2761236475"},"surfaceOp":"append"}
 {"type":"assistant/chunk","seq":32,"time":1785531795686,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":33,"time":1785536135065,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_list","name":"list_agents","argumentsDelta":"{}"}}}
-{"type":"assistant/chunk","seq":34,"time":1785730454867,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_list","name":"list_agents","arguments":"{}"}}}}
+{"type":"assistant/chunk","seq":33,"time":1785536135065,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_list","name":"list_agents","argumentsDelta":"{\"scope\":\"descendants\"}"}}}
+{"type":"assistant/chunk","seq":34,"time":1785730454867,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_list","name":"list_agents","arguments":"{\"scope\":\"descendants\"}"}}}}
 {"type":"assistant/chunk","seq":35,"time":1785730454867,"data":{"turn":2,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
 {"type":"assistant/chunk","seq":36,"time":1785730454867,"data":{"turn":2,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":37,"time":1785730454867,"data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_list","name":"list_agents","arguments":"{}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"199c7794-d782-4957-b7ed-69d094b9c0ef"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[32,33,34,35,36],"surfaceOp":"append"}
-{"type":"tool/call","seq":38,"time":1785730454867,"data":{"turn":2,"step":1,"callId":"call_list","name":"list_agents","arguments":"{}"}}
-{"type":"tool/result","seq":39,"time":1785730454893,"data":{"turn":2,"step":1,"message":{"source":{"kind":"tool","callId":"call_list"},"content":[{"type":"tool-result","toolCallId":"call_list","content":[{"type":"text","text":"33333333-3333-4333-8333-333333333333 [complete] — Reply with CHILD_OK"}],"isError":false}],"role":"user","id":"61ceb650-3e32-413e-9d7e-b6ec8a351858"}},"sourceEventSeqs":[38],"surfaceOp":"append"}
+{"type":"assistant/message","seq":37,"time":1785730454867,"data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_list","name":"list_agents","arguments":"{\"scope\":\"descendants\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"199c7794-d782-4957-b7ed-69d094b9c0ef"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[32,33,34,35,36],"surfaceOp":"append"}
+{"type":"tool/call","seq":38,"time":1785730454867,"data":{"turn":2,"step":1,"callId":"call_list","name":"list_agents","arguments":"{\"scope\":\"descendants\"}"}}
+{"type":"tool/result","seq":39,"time":1785730454893,"data":{"turn":2,"step":1,"message":{"source":{"kind":"tool","callId":"call_list"},"content":[{"type":"tool-result","toolCallId":"call_list","content":[{"type":"text","text":"33333333-3333-4333-8333-333333333333 [complete] parent=11111111-1111-4111-8111-111111111111 depth=1 — Reply with CHILD_OK"}],"isError":false}],"role":"user","id":"61ceb650-3e32-413e-9d7e-b6ec8a351858"}},"sourceEventSeqs":[38],"surfaceOp":"append"}
 {"type":"step/end","seq":40,"time":1785730454893,"data":{"turn":2,"step":1}}
 {"type":"step/start","seq":41,"time":1785730454903,"data":{"turn":2,"step":2}}
-{"type":"assistant/chunk","seq":42,"time":1785531795715,"data":{"turn":2,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":43,"time":1785536135106,"data":{"turn":2,"step":2,"chunk":{"type":"text-delta","index":0,"text":"DONE"}}}
-{"type":"assistant/chunk","seq":44,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
-{"type":"assistant/chunk","seq":45,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}}}
-{"type":"assistant/chunk","seq":46,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":47,"time":1785730454907,"data":{"turn":2,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"17c1a7c5-84f5-493e-adb5-6a65219e6ad6"},"usage":{"inputTokens":10,"outputTokens":2}},"sourceEventSeqs":[42,43,44,45,46],"surfaceOp":"append"}
-{"type":"step/end","seq":48,"time":1785730454908,"data":{"turn":2,"step":2}}
-{"type":"turn/end","seq":49,"time":1785730454908,"data":{"turn":2,"reason":{"kind":"completed"}}}
+{"type":"assistant/chunk","seq":42,"time":1785531795715,"data":{"turn":2,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":43,"time":1785536135106,"data":{"turn":2,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"call_interrupt","name":"interrupt_agent","argumentsDelta":"{\"agent_id\":\"33333333-3333-4333-8333-333333333333\"}"}}}
+{"type":"assistant/chunk","seq":44,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_interrupt","name":"interrupt_agent","arguments":"{\"agent_id\":\"33333333-3333-4333-8333-333333333333\"}"}}}}
+{"type":"assistant/chunk","seq":45,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":46,"time":1785730454907,"data":{"turn":2,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":47,"time":1785730454907,"data":{"turn":2,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_interrupt","name":"interrupt_agent","arguments":"{\"agent_id\":\"33333333-3333-4333-8333-333333333333\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"17c1a7c5-84f5-493e-adb5-6a65219e6ad6"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[42,43,44,45,46],"surfaceOp":"append"}
+{"type":"tool/call","seq":48,"time":1785730454907,"data":{"turn":2,"step":2,"callId":"call_interrupt","name":"interrupt_agent","arguments":"{\"agent_id\":\"33333333-3333-4333-8333-333333333333\"}"}}
+{"type":"tool/result","seq":49,"time":1785730454917,"data":{"turn":2,"step":2,"message":{"source":{"kind":"tool","callId":"call_interrupt"},"content":[{"type":"tool-result","toolCallId":"call_interrupt","content":[{"type":"text","text":"interrupt requested for agent 33333333-3333-4333-8333-333333333333"}],"isError":false}],"role":"user","id":"bf93cbe0-1946-4aef-a4ce-431790026c6f"}},"sourceEventSeqs":[48],"surfaceOp":"append"}
+{"type":"step/end","seq":50,"time":1785730454917,"data":{"turn":2,"step":2}}
+{"type":"step/start","seq":51,"time":1785730454927,"data":{"turn":2,"step":3}}
+{"type":"assistant/chunk","seq":52,"time":1785531795715,"data":{"turn":2,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":53,"time":1785536135106,"data":{"turn":2,"step":3,"chunk":{"type":"text-delta","index":0,"text":"DONE"}}}
+{"type":"assistant/chunk","seq":54,"time":1785730454907,"data":{"turn":2,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":55,"time":1785730454907,"data":{"turn":2,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}}}
+{"type":"assistant/chunk","seq":56,"time":1785730454907,"data":{"turn":2,"step":3,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":57,"time":1785730454907,"data":{"turn":2,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"e4c04cd6-9c23-4c99-a5f7-bac6fc141e95"},"usage":{"inputTokens":10,"outputTokens":2}},"sourceEventSeqs":[52,53,54,55,56],"surfaceOp":"append"}
+{"type":"step/end","seq":58,"time":1785730454938,"data":{"turn":2,"step":3}}
+{"type":"turn/end","seq":59,"time":1785730454938,"data":{"turn":2,"reason":{"kind":"completed"}}}

From d21917f4cf44f0a6394efb76546f4aa211963599 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:53:33 +0800
Subject: [PATCH 288/516] refactor(subagent): resolve list tool inputs
 explicitly

---
 ...subagent-catalog-and-list-agents.i18n.yaml |  4 +-
 ...urable-subagent-catalog-and-list-agents.md |  4 +-
 ...ble-subagent-catalog-and-list-agents.zh.md |  4 +-
 .../tool-subagent-control/src/list-agents.ts  | 87 ++++++++++++-------
 .../tests/list-agents.spec.ts                 |  4 +-
 5 files changed, 65 insertions(+), 38 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
index c525cc8f43..e4df6863da 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.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 .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
-2026-07-22-durable-subagent-catalog-and-list-agents.md: 8337a926238bf7fc4395896fcd4ca180c9c1ac1c
-2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: bcf2895a9a69c8cff949788c78158bfccd198c5c
+2026-07-22-durable-subagent-catalog-and-list-agents.md: 61bda2a52f2ea5db0a582fe668643a13b967f091
+2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: a2bc36200d8c67b8da9dd3d55ea4179baa72e691
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
index 8337a92623..61bda2a52f 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
@@ -52,9 +52,9 @@ If measured scale later requires an index, that index is derived state: session
 
 A valid descriptor produces one child entry, a per-child inspection failure produces one diagnostic entry, and a candidate without a descriptor produces no entry. `mode` is durable creation policy; `activity` is a process-local corpus snapshot. Activity is neither `AgentStatus`, the manager's internal Activation state, nor a durable outcome, and the result does not expose the internal `createdAt` sorting key. Exact Activation states and durable outcomes such as successful completion, failure, cancellation, and stop reason require a separate durable activation record and are outside this feature.
 
-The model-facing `list_agents` tool takes one optional `scope: 'children' | 'descendants'` argument, derives the root id from the current execution Agent, and is a thin adapter in `@deepseek-ai/dsh-tool-subagent-control`. It keeps diagnostics, drops `one-shot` child entries, derives status from the live Agent registry — `running` for an active driver, `idle` for a resident Agent between turns, and `complete` when no live Agent remains — then renders `<id> [<status>] — <label>` or `<id> [diagnostic: <reason>]` in stable catalog order. The `descendants` scope reads `SubagentService.listDescendants(rootSessionId)`, which flattens the complete tree from one live-preferred corpus in stable pre-order, traverses ordinary and one-shot intermediates so deeper continuable agents are discovered, revalidates each cold candidate against its enumerated lifecycle, and adds `parentId`/`depth` to every entry. The tool inserts ` parent=<id> depth=<n>` before the label; `parent` is the durable direct-parent session id and may name an omitted ordinary session. For the current caller, only depth-1 child rows are `send_message` candidates, while deeper child rows may be selected for `interrupt_agent` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Discovery is a hint only — follow-up authority stays exact-direct-parent, and interrupt authority stays with the service's live-lineage check. An empty projection renders `(no subagents)`.
+The model-facing `list_agents` tool takes one optional `scope: 'children' | 'descendants'` argument, derives the root id from the current execution Agent, and resolves the request through an explicit request-to-spec step (`undefined` → `children`) before either execution or rendering. The resolved `children` scope calls `SubagentService.listChildren(rootSessionId)`, while `descendants` calls `SubagentService.listDescendants(rootSessionId)`. Its internal output projection keeps `id` and `parent` as branded `SessionId` values until the tool JSON boundary. It keeps diagnostics, drops `one-shot` child entries, derives status from the live Agent registry — `running` for an active driver, `idle` for a resident Agent between turns, and `complete` when no live Agent remains — then renders `<id> [<status>] — <label>` or `<id> [diagnostic: <reason>]` in stable catalog order. The `descendants` scope flattens the complete tree from one live-preferred corpus in stable pre-order, traverses ordinary and one-shot intermediates so deeper continuable agents are discovered, revalidates each cold candidate against its enumerated lifecycle, and adds `parentId`/`depth` to every entry. The tool inserts ` parent=<id> depth=<n>` before the label; `parent` is the durable direct-parent session id and may name an omitted ordinary session. For the current caller, only depth-1 child rows are `send_message` candidates, while deeper child rows may be selected for `interrupt_agent` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Discovery is a hint only — follow-up authority stays exact-direct-parent, and interrupt authority stays with the service's live-lineage check. An empty projection renders `(no subagents)`.
 
-Diagnostics use three fixed reasons. Malformed event surfaces, conflicting headers discovered during an exact child load, a read result whose immutable header differs from the traced candidate or no longer names the requested direct parent, a target that is no longer the located descriptor event, malformed descriptor content, and multiple descriptor events map to `corrupt`. An unknown descriptor version maps to `unsupported`. `SESSION_QUERY_SESSION_NOT_FOUND`, `SESSION_QUERY_EVENT_NOT_FOUND`, and `SESSION_QUERY_PERSISTENCE_FAILED` from a per-child read map to `unavailable`. This phase boundary is intentional: a persistence outage during the initial trace fails the operation, while the same outage beginning during candidate reads may produce one identical `unavailable` diagnostic per affected child; the first version neither coalesces those diagnostics nor promotes them to a global failure. A missing descriptor is instead a non-subagent exclusion without a diagnostic. Configuration/window errors and unrecognized failures are not child diagnostics and propagate as operation failures. Each diagnostic identifies the child id and reason without exposing model-hidden descriptor content; the candidate is omitted while healthy siblings remain visible. Sessions outside the trace's direct descendants are never read and produce no diagnostic.
+In the superseded trace-based path, diagnostics used three fixed reasons. Malformed event surfaces, conflicting headers discovered during an exact child load, a read result whose immutable header differs from the traced candidate or no longer names the requested direct parent, a target that is no longer the located descriptor event, malformed descriptor content, and multiple descriptor events mapped to `corrupt`. An unknown descriptor version mapped to `unsupported`. `SESSION_QUERY_SESSION_NOT_FOUND`, `SESSION_QUERY_EVENT_NOT_FOUND`, and `SESSION_QUERY_PERSISTENCE_FAILED` from a per-child read mapped to `unavailable`. This phase boundary was intentional: a persistence outage during the initial trace failed the operation, while the same outage beginning during candidate reads could produce one identical `unavailable` diagnostic per affected child; the first version neither coalesced those diagnostics nor promoted them to a global failure. A missing descriptor was instead a non-subagent exclusion without a diagnostic. Configuration/window errors and unrecognized failures were not child diagnostics and propagated as operation failures. Each diagnostic identified the child id and reason without exposing model-hidden descriptor content; the candidate was omitted while healthy siblings remained visible. Sessions outside the trace's direct descendants were never read and produced no diagnostic.
 
 Diagnostics are transient query results, not session events or catalog state. Deriving a diagnostic performs no additional load beyond the `listEvents()` or conditional `readEvent()` operation whose result produced it.
 
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
index bcf2895a9a..a2bc36200d 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
@@ -52,9 +52,9 @@ subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务
 
 有效描述符产生一个 child 条目，逐 child 检查失败产生一个 diagnostic 条目，缺少描述符的候选不产生条目。`mode` 是持久化创建策略；`activity` 是进程本地语料快照。活动状态既不是 `AgentStatus`、管理器内部的 Activation 状态，也不是持久化结果，结果不公开内部 `createdAt` 排序键。成功完成、失败、取消和停止原因等精确 Activation 状态与持久化结果需要单独的持久化激活记录，不在本功能范围内。
 
-面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并作为 `@deepseek-ai/dsh-tool-subagent-control` 中的轻量适配器。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 读取 `SubagentService.listDescendants(rootSessionId)`：它从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
+面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并在执行或渲染前通过显式的 request-to-spec 步骤解析请求（`undefined` → `children`）。解析后的 `children` scope 调用 `SubagentService.listChildren(rootSessionId)`，`descendants` scope 则调用 `SubagentService.listDescendants(rootSessionId)`。其内部输出投影中的 `id` 与 `parent` 会一直保持为品牌化的 `SessionId` 值，直到工具 JSON 边界。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
 
-diagnostic 使用三种固定原因。格式错误的事件 surface、精确加载 child 时发现的 header 冲突、读取结果中的不可变 header 与追踪到的候选不一致或不再指向请求的直接 parent、读取目标不再是先前定位的描述符事件、格式错误的描述符内容和多个描述符事件映射为 `corrupt`。未知描述符版本映射为 `unsupported`。逐 child 读取产生的 `SESSION_QUERY_SESSION_NOT_FOUND`、`SESSION_QUERY_EVENT_NOT_FOUND` 和 `SESSION_QUERY_PERSISTENCE_FAILED` 映射为 `unavailable`。这项阶段边界是有意为之：初始追踪期间发生持久化故障会让操作失败，而同一故障如果始于候选读取期间，可能会让每个受影响的 child 分别产生一条相同的 `unavailable` diagnostic；第一版既不合并这些 diagnostic，也不会把它们提升为全局失败。缺少描述符则作为非 subagent 排除，且不产生 diagnostic。配置错误、窗口错误和未识别的失败不属于 child diagnostic，会作为操作失败继续向上传播。每条 diagnostic 都标识 child id 及原因，不暴露对模型隐藏的描述符内容；系统会排除该候选，而其他健康的 sibling 仍然可见。系统绝不会读取不属于追踪结果直接后代的会话，也不会为它们产生 diagnostic。
+在已被取代的追踪读路径中，diagnostic 使用三种固定原因。格式错误的事件 surface、精确加载 child 时发现的 header 冲突、读取结果中的不可变 header 与追踪到的候选不一致或不再指向请求的直接 parent、读取目标不再是先前定位的描述符事件、格式错误的描述符内容和多个描述符事件映射为 `corrupt`。未知描述符版本映射为 `unsupported`。逐 child 读取产生的 `SESSION_QUERY_SESSION_NOT_FOUND`、`SESSION_QUERY_EVENT_NOT_FOUND` 和 `SESSION_QUERY_PERSISTENCE_FAILED` 映射为 `unavailable`。这项阶段边界是有意为之：初始追踪期间发生持久化故障会让操作失败，而同一故障如果始于候选读取期间，可能会让每个受影响的 child 分别产生一条相同的 `unavailable` diagnostic；第一版既不合并这些 diagnostic，也不会把它们提升为全局失败。缺少描述符则作为非 subagent 排除，且不产生 diagnostic。配置错误、窗口错误和未识别的失败不属于 child diagnostic，会作为操作失败继续向上传播。每条 diagnostic 都标识 child id 及原因，不暴露对模型隐藏的描述符内容；系统会排除该候选，而其他健康的 sibling 仍然可见。系统绝不会读取不属于追踪结果直接后代的会话，也不会为它们产生 diagnostic。
 
 diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导 diagnostic 时，除了产生该结果的 `listEvents()` 或条件性 `readEvent()` 操作外，不会执行额外加载。
 
diff --git a/packages/subagent/tool-subagent-control/src/list-agents.ts b/packages/subagent/tool-subagent-control/src/list-agents.ts
index c39ebbc648..d47232b3cc 100644
--- a/packages/subagent/tool-subagent-control/src/list-agents.ts
+++ b/packages/subagent/tool-subagent-control/src/list-agents.ts
@@ -11,28 +11,44 @@ import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { SessionId } from '@deepseek-ai/dsh-session'
+import { assertNever } from '@deepseek-ai/dsh-llm'
 import type { SubagentDescendantListEntry, SubagentListEntry } from '@deepseek-ai/dsh-subagent'
 
 export const name = 'tool-subagent-list-agents'
 export const inject = ['tools', 'subagents', 'agents']
 
+type ListAgentsScope = 'children' | 'descendants'
+
+interface ListAgentsRequest {
+  readonly scope?: ListAgentsScope
+}
+
+interface ListAgentsSpec {
+  readonly scope: ListAgentsScope
+}
+
 type ListAgentsEntry =
   | {
     readonly kind: 'child'
-    readonly id: string
+    readonly id: SessionId
     readonly label: string
     readonly status: 'running' | 'idle' | 'complete'
-    readonly parent?: string
+    readonly parent?: SessionId
     readonly depth?: number
   }
   | {
     readonly kind: 'diagnostic'
-    readonly id: string
+    readonly id: SessionId
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
-    readonly parent?: string
+    readonly parent?: SessionId
     readonly depth?: number
   }
 
+/** Resolve the optional model request into an internal required-scope spec. */
+function resolveListAgentsRequest(request: ListAgentsRequest): ListAgentsSpec {
+  return { scope: request.scope ?? 'children' }
+}
+
 /**
  * Refine one candidate's status through the live Agent registry: `running`
  * for an active driver, `idle` for a resident Agent between turns (possibly
@@ -50,7 +66,7 @@ function project(
   entry: SubagentListEntry,
   position?: Pick<SubagentDescendantListEntry, 'parentId' | 'depth'>,
 ): ListAgentsEntry | undefined {
-  const at = position === undefined ? {} : { parent: position.parentId as string, depth: position.depth }
+  const at = position === undefined ? {} : { parent: position.parentId, depth: position.depth }
   if (entry.kind === 'diagnostic') {
     return { kind: 'diagnostic', id: entry.id, reason: entry.reason, ...at }
   }
@@ -121,22 +137,25 @@ export function apply(ctx: Context): void {
           ],
         },
       },
-      render: (args, entries) => [{
-        type: 'text',
-        text: entries.length === 0
-          ? '(no subagents)'
-          : entries.map((entry) => {
-            // A descendants row always carries its position; children rows
-            // never render it. String() spans the schema-optional shape
-            // without a dead fallback branch.
-            const at = args.scope === 'descendants'
-              ? ` parent=${String(entry.parent)} depth=${String(entry.depth)}`
-              : ''
-            return entry.kind === 'child'
-              ? `${entry.id} [${entry.status}]${at} — ${entry.label}`
-              : `${entry.id} [diagnostic: ${entry.reason}]${at}`
-          }).join('\n'),
-      }],
+      render: (args, entries) => {
+        const request = resolveListAgentsRequest(args)
+        return [{
+          type: 'text',
+          text: entries.length === 0
+            ? '(no subagents)'
+            : entries.map((entry) => {
+              // A descendants row always carries its position; children rows
+              // never render it. String() spans the schema-optional shape
+              // without a dead fallback branch.
+              const at = request.scope === 'descendants'
+                ? ` parent=${String(entry.parent)} depth=${String(entry.depth)}`
+                : ''
+              return entry.kind === 'child'
+                ? `${entry.id} [${entry.status}]${at} — ${entry.label}`
+                : `${entry.id} [diagnostic: ${entry.reason}]${at}`
+            }).join('\n'),
+        }]
+      },
     },
     async execute(args, exec) {
       const parent = exec.agent
@@ -144,18 +163,26 @@ export function apply(ctx: Context): void {
         // Non-agent callers have no session whose children could be listed.
         throw new Error('list_agents requires a calling agent (exec.agent was undefined)')
       }
+      const request = resolveListAgentsRequest(args)
       // The registry drains started tool bodies, so the scan must observe the
       // call's signal rather than finish a slow catalog after cancellation.
-      if (args.scope === 'descendants') {
-        const entries = await ctx.subagents.listDescendants(parent.id, exec.signal)
-        return entries
-          .map(entry => project(ctx.agents, entry, entry))
-          .filter(entry => entry !== undefined)
+      switch (request.scope) {
+        case 'children': {
+          const entries = await ctx.subagents.listChildren(parent.id, exec.signal)
+          return entries
+            .map(entry => project(ctx.agents, entry))
+            .filter(entry => entry !== undefined)
+        }
+        case 'descendants': {
+          const entries = await ctx.subagents.listDescendants(parent.id, exec.signal)
+          return entries
+            .map(entry => project(ctx.agents, entry, entry))
+            .filter(entry => entry !== undefined)
+        }
+        /* v8 ignore next 2 -- the resolver normalizes the schema-validated closed scope before dispatch. */
+        default:
+          return assertNever(request.scope, 'list_agents scope')
       }
-      const entries = await ctx.subagents.listChildren(parent.id, exec.signal)
-      return entries
-        .map(entry => project(ctx.agents, entry))
-        .filter(entry => entry !== undefined)
     },
   }))
 }
diff --git a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
index 3131809d37..0361471031 100644
--- a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
@@ -185,7 +185,7 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     )
   })
 
-  it('forwards the tool cancellation signal to child enumeration', async () => {
+  it('resolves omitted scope to children and forwards the tool cancellation signal', async () => {
     const { ctx, parent } = await setup([])
     const signal = new AbortController().signal
     const listChildren = vi.spyOn(ctx.subagents, 'listChildren').mockResolvedValue([])
@@ -326,7 +326,7 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     )
   })
 
-  it('forwards the tool cancellation signal to descendant enumeration', async () => {
+  it('preserves explicit descendants scope and forwards the tool cancellation signal', async () => {
     const { ctx, parent } = await setup([])
     const signal = new AbortController().signal
     const listDescendants = vi.spyOn(ctx.subagents, 'listDescendants').mockResolvedValue([])

From 542c029c804a71ba45e52158ec645c5eb7898a0d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:11:19 +0800
Subject: [PATCH 289/516] feat(i18n): compose pairing records during merges

---
 .gitattributes                            |   4 +
 lefthook.yml                              |  10 +
 package.json                              |   1 +
 scripts/install-lefthook.mjs              | 104 ++++++++-
 scripts/install-lefthook.spec.ts          |  64 +++++-
 scripts/merge-translation-pairing.ts      |  42 ++++
 scripts/translation-pairing-git.ts        |  33 +++
 scripts/translation-pairing-merge.spec.ts | 255 +++++++++++++++++++++
 scripts/translation-pairing-merge.ts      | 267 ++++++++++++++++++++++
 scripts/translation-pairing-record.ts     |  99 ++++++++
 scripts/translation-pairing.spec.ts       |  91 +++++++-
 scripts/translation-pairing.ts            |  20 +-
 scripts/verify-translation-pairing.ts     | 136 ++++++-----
 13 files changed, 1049 insertions(+), 77 deletions(-)
 create mode 100644 scripts/merge-translation-pairing.ts
 create mode 100644 scripts/translation-pairing-merge.spec.ts
 create mode 100644 scripts/translation-pairing-merge.ts
 create mode 100644 scripts/translation-pairing-record.ts

diff --git a/.gitattributes b/.gitattributes
index 2efafac8b8..e0a432111d 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -7,3 +7,7 @@
 * text=auto eol=lf
 
 *.pdf binary
+
+# Pairing records are generated from the three confirmed owner-blob pairs.
+# The worktree-local installer registers the fail-closed driver command.
+*.i18n.yaml merge=dsh-translation-pairing
diff --git a/lefthook.yml b/lefthook.yml
index c2249adbde..0e78d16252 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -4,6 +4,10 @@
 
 pre-commit:
   jobs:
+    - name: translation pairing (staged records)
+      glob: '*.i18n.yaml'
+      run: node_modules/.bin/tsx scripts/verify-translation-pairing.ts --cached {staged_files}
+
     - name: format (staged)
       glob: '*.{ts,tsx,mts,cts,mjs}'
       exclude:
@@ -34,6 +38,12 @@ pre-commit:
     - name: vendor manifest guard
       run: scripts/check-vendor-manifest.sh
 
+pre-merge-commit:
+  jobs:
+    - name: translation pairing (staged records)
+      glob: '*.i18n.yaml'
+      run: node_modules/.bin/tsx scripts/verify-translation-pairing.ts --cached {staged_files}
+
 pre-push:
   jobs:
     - name: typecheck
diff --git a/package.json b/package.json
index 423cbf813c..864814ffe6 100644
--- a/package.json
+++ b/package.json
@@ -79,6 +79,7 @@
     "verify-type-equiv": "tsx scripts/verify-type-equiv.ts",
     "verify-translation-prompt": "tsx scripts/verify-translation-prompt.ts",
     "verify-translation-pairing": "tsx scripts/verify-translation-pairing.ts",
+    "resolve-translation-pairing-conflicts": "tsx scripts/merge-translation-pairing.ts --resolve",
     "gen-translation-brief": "tsx scripts/gen-translation-brief.ts",
     "verify-doc-budgets": "tsx scripts/verify-doc-budgets.ts",
     "docs:dev": "pnpm --filter @deepseek-ai/website run dev",
diff --git a/scripts/install-lefthook.mjs b/scripts/install-lefthook.mjs
index 0f840de9c8..b928582a8a 100644
--- a/scripts/install-lefthook.mjs
+++ b/scripts/install-lefthook.mjs
@@ -27,6 +27,13 @@ const INSTALL_LOCK_INITIALIZATION_TIMEOUT_MS = 1_000
 const INSTALL_LOCK_POLL_MS = 50
 const ALLOW_HOOKS_PATH_OVERRIDE = 'DSH_LEFTHOOK_ALLOW_HOOKS_PATH_OVERRIDE'
 const REPOSITORY_EXTENSION_PATTERN = '^extensions\\.'
+const PAIRING_MERGE_DRIVER_CONFIG = [
+  ['merge.dsh-translation-pairing.name', 'DeepSeek Harness bilingual pairing records'],
+  [
+    'merge.dsh-translation-pairing.driver',
+    'node --import tsx/esm scripts/merge-translation-pairing.ts %O %A %B %P',
+  ],
+]
 
 function errorCode(error) {
   return typeof error === 'object' && error !== null && 'code' in error
@@ -595,6 +602,82 @@ function refuseScopedHooksPath(entry) {
   )
 }
 
+function installPairingMergeDriver(root, worktreeConfigPath) {
+  const added = []
+  try {
+    for (const [key, expected] of PAIRING_MERGE_DRIVER_CONFIG) {
+      const entries = includedFileConfigEntries(root, worktreeConfigPath, key)
+      const includedEntry = entries.find(entry => !originIsFile(entry.origin, root, worktreeConfigPath))
+      if (includedEntry !== undefined) {
+        throw new Error(
+          `refusing pairing merge-driver config from an included worktree file (${configSource(includedEntry)})`,
+        )
+      }
+      const existing = assertSingle(entries.map(entry => entry.value), `worktree ${key}`)
+      const effectiveBefore = effectiveConfigEntry(root, key)
+      if (effectiveBefore?.scope === 'command') {
+        throw new Error(
+          `refusing command-scoped ${key} (${configSource(effectiveBefore)}); `
+          + 'transient configuration cannot be replaced by the worktree installer',
+        )
+      }
+      if (existing === undefined && effectiveBefore !== undefined && effectiveBefore.value !== expected) {
+        throw new Error(
+          `refusing to mask inherited ${key} (${configSource(effectiveBefore)}); `
+          + 'remove or integrate the custom pairing merge driver explicitly',
+        )
+      }
+      if (existing !== undefined && existing !== expected) {
+        throw new Error(
+          `refusing to replace worktree ${key} value ${JSON.stringify(existing)}; `
+          + 'remove or integrate the custom pairing merge driver explicitly',
+        )
+      }
+      if (existing === undefined) {
+        git(['config', '--worktree', key, expected], root)
+        added.push(key)
+      }
+      const installed = includedFileConfigEntries(root, worktreeConfigPath, key)
+      if (
+        installed.length !== 1
+        || installed[0]?.value !== expected
+        || !originIsFile(installed[0].origin, root, worktreeConfigPath)
+      ) {
+        throw new Error(`new worktree-local ${key} did not become the direct worktree value`)
+      }
+      const effectiveAfter = effectiveConfigEntry(root, key)
+      if (
+        effectiveAfter === undefined
+        || effectiveAfter.scope !== 'worktree'
+        || effectiveAfter.value !== expected
+        || !originIsFile(effectiveAfter.origin, root, worktreeConfigPath)
+      ) {
+        throw new Error(`new worktree-local ${key} did not become the effective direct worktree value`)
+      }
+    }
+  } catch (error) {
+    const rollbackErrors = []
+    for (const key of added.reverse()) {
+      try {
+        git(['config', '--worktree', '--unset-all', key], root)
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError)
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [error, ...rollbackErrors],
+        `Pairing merge-driver configuration failed: ${String(error)}; `
+        + `rollback also failed: ${rollbackErrors.map(String).join('; ')}`,
+      )
+    }
+    throw error
+  }
+  return () => {
+    for (const key of added.reverse()) git(['config', '--worktree', '--unset-all', key], root)
+  }
+}
+
 async function main() {
   if (process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true') return
   if (typeof lefthookPackage.bin?.lefthook !== 'string') return
@@ -682,7 +765,9 @@ async function main() {
     applyWorktreeConfigMigration(root, commonConfigPath, migration)
 
     let pathChanged = false
+    let rollbackPairingMergeDriver = () => {}
     try {
+      rollbackPairingMergeDriver = installPairingMergeDriver(root, worktreeConfigPath)
       git(['config', '--worktree', 'core.hooksPath', hooksPath], root)
       pathChanged = worktreePath !== hooksPath
       const installedEntry = effectiveConfigEntry(root, 'core.hooksPath')
@@ -697,6 +782,7 @@ async function main() {
       runLefthook(root, lefthook)
       updateOwnershipMarker(ownedHooksDirectory.markerPath, hooksPath)
     } catch (error) {
+      const rollbackErrors = []
       if (pathChanged) {
         try {
           if (worktreePath === undefined) {
@@ -705,13 +791,21 @@ async function main() {
             git(['config', '--worktree', 'core.hooksPath', worktreePath], root)
           }
         } catch (rollbackError) {
-          throw new AggregateError(
-            [error, rollbackError],
-            `Lefthook installation failed: ${String(error)}; `
-            + `worktree hook rollback also failed: ${String(rollbackError)}`,
-          )
+          rollbackErrors.push(rollbackError)
         }
       }
+      try {
+        rollbackPairingMergeDriver()
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError)
+      }
+      if (rollbackErrors.length > 0) {
+        throw new AggregateError(
+          [error, ...rollbackErrors],
+          `Lefthook installation failed: ${String(error)}; `
+          + `worktree integration rollback also failed: ${rollbackErrors.map(String).join('; ')}`,
+        )
+      }
       throw error
     }
   } catch (error) {
diff --git a/scripts/install-lefthook.spec.ts b/scripts/install-lefthook.spec.ts
index ca74b91404..df9f1cd6d8 100644
--- a/scripts/install-lefthook.spec.ts
+++ b/scripts/install-lefthook.spec.ts
@@ -18,6 +18,7 @@ import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 
 const installer = fileURLToPath(new URL('./install-lefthook.mjs', import.meta.url))
+const pairingMergeDriver = 'node --import tsx/esm scripts/merge-translation-pairing.ts %O %A %B %P'
 const fixtures: string[] = []
 // Multi-worktree cases spawn several Git and Node subprocesses; coverage concurrency can
 // legitimately exceed Vitest's default deadline without changing the installer behavior.
@@ -95,7 +96,7 @@ if (!shouldFail) {
   const binary = join(root, 'node_modules', '.bin', process.platform === 'win32' ? 'lefthook.cmd' : 'lefthook')
   const config = readFileSync(join(root, 'lefthook.yml'), 'utf8').trim()
   const hook = \`#!/bin/sh\\n# root=\${root}\\n# binary=\${binary}\\n# config=\${config}\\nexit 0\\n\`
-  for (const name of ['pre-commit', 'pre-push']) writeFileSync(join(hooksPath, name), hook, { mode: 0o755 })
+  for (const name of ['pre-commit', 'pre-merge-commit', 'pre-push']) writeFileSync(join(hooksPath, name), hook, { mode: 0o755 })
 }
 if (existsSync(running)) unlinkSync(running)
 if (process.env.DSH_TEST_LEFTHOOK_BREAK_WORKTREE_CONFIG === '1') {
@@ -222,6 +223,9 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
       expect(git(fixture, fixture.main, ['config', '--get', 'core.repositoryFormatVersion'])).toBe('0')
       expect(existsSync(hooksPath(fixture, fixture.main))).toBe(false)
       expect(existsSync(join(common, 'config.worktree'))).toBe(false)
+      expect(gitResult(fixture, fixture.main, [
+        'config', '--get', 'merge.dsh-translation-pairing.driver',
+      ]).status).toBe(1)
     })
   }
 
@@ -241,6 +245,12 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(mainHooks).not.toBe(linkedHooks)
     expect(git(fixture, fixture.main, ['config', '--worktree', '--get', 'core.hooksPath'])).toBe(mainHooks)
     expect(git(fixture, fixture.linked, ['config', '--worktree', '--get', 'core.hooksPath'])).toBe(linkedHooks)
+    expect(git(fixture, fixture.main, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.driver',
+    ])).toBe(pairingMergeDriver)
+    expect(git(fixture, fixture.linked, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.driver',
+    ])).toBe(pairingMergeDriver)
 
     const mainHook = readFileSync(join(mainHooks, 'pre-commit'), 'utf8')
     const linkedHook = readFileSync(join(linkedHooks, 'pre-commit'), 'utf8')
@@ -252,6 +262,8 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(linkedHook).toContain(`# root=${canonicalLinked}`)
     expect(linkedHook).toContain('# config=linked-worktree-config')
     expect(linkedHook).not.toContain(canonicalMain)
+    expect(existsSync(join(mainHooks, 'pre-merge-commit'))).toBe(true)
+    expect(existsSync(join(linkedHooks, 'pre-merge-commit'))).toBe(true)
     expect(readFileSync(legacyHook, 'utf8')).toBe('#!/bin/sh\n# legacy hook\n')
 
     const commonConfig = join(common, 'config')
@@ -677,9 +689,50 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(result.stderr).toContain('command-scoped core.hooksPath')
     expect(readFileSync(sentinel, 'utf8')).toBe('#!/bin/sh\n# command-scope sentinel\n')
     expect(gitResult(fixture, fixture.main, ['config', '--get', 'core.hooksPath']).status).toBe(1)
+    expect(gitResult(fixture, fixture.main, [
+      'config', '--get', 'merge.dsh-translation-pairing.driver',
+    ]).status).toBe(1)
     expect(existsSync(hooksPath(fixture, fixture.main))).toBe(false)
   })
 
+  it('never replaces a custom worktree pairing merge driver', async () => {
+    const fixture = createFixture()
+    const commonConfig = join(commonDirectory(fixture), 'config')
+    git(fixture, fixture.main, ['config', '--file', commonConfig, 'core.repositoryFormatVersion', '1'])
+    git(fixture, fixture.main, ['config', '--file', commonConfig, 'extensions.worktreeConfig', 'true'])
+    git(fixture, fixture.main, [
+      'config', '--worktree', 'merge.dsh-translation-pairing.driver', 'custom-driver %A',
+    ])
+
+    const result = await runInstaller(fixture, fixture.main)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('refusing to replace worktree merge.dsh-translation-pairing.driver')
+    expect(git(fixture, fixture.main, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.driver',
+    ])).toBe('custom-driver %A')
+    expect(gitResult(fixture, fixture.main, ['config', '--get', 'core.hooksPath']).status).toBe(1)
+  })
+
+  it('never masks an inherited custom pairing merge driver', async () => {
+    const fixture = createFixture()
+    git(fixture, fixture.main, [
+      'config', '--local', 'merge.dsh-translation-pairing.driver', 'inherited-driver %A',
+    ])
+
+    const result = await runInstaller(fixture, fixture.main)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('refusing to mask inherited merge.dsh-translation-pairing.driver')
+    expect(git(fixture, fixture.main, [
+      'config', '--local', '--get', 'merge.dsh-translation-pairing.driver',
+    ])).toBe('inherited-driver %A')
+    expect(gitResult(fixture, fixture.main, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.driver',
+    ]).status).toBe(1)
+    expect(gitResult(fixture, fixture.main, ['config', '--get', 'core.hooksPath']).status).toBe(1)
+  })
+
   it('does not pass unrelated command-scoped Git config to Lefthook', async () => {
     const fixture = createFixture()
 
@@ -729,6 +782,12 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(result.stderr).toContain('exit status 77')
     expect(gitResult(fixture, fixture.main, ['config', '--worktree', '--get', 'core.hooksPath']).status).toBe(1)
     expect(gitResult(fixture, fixture.main, ['config', '--get', 'core.hooksPath']).status).toBe(1)
+    expect(gitResult(fixture, fixture.main, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.name',
+    ]).status).toBe(1)
+    expect(gitResult(fixture, fixture.main, [
+      'config', '--worktree', '--get', 'merge.dsh-translation-pairing.driver',
+    ]).status).toBe(1)
     expect(readFileSync(legacyHook, 'utf8')).toBe('#!/bin/sh\n# legacy pre-push\n')
   })
 
@@ -743,8 +802,9 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(result.status).toBe(1)
     expect(result.stderr).toContain('Lefthook installation failed')
     expect(result.stderr).toContain('exit status 77')
-    expect(result.stderr).toContain('worktree hook rollback also failed')
+    expect(result.stderr).toContain('worktree integration rollback also failed')
     expect(result.stderr).toContain('git config --worktree --unset-all core.hooksPath failed')
+    expect(result.stderr).toContain('git config --worktree --unset-all merge.dsh-translation-pairing.driver failed')
   })
 
   it('refuses an unowned directory at the reserved worktree hook path', async () => {
diff --git a/scripts/merge-translation-pairing.ts b/scripts/merge-translation-pairing.ts
new file mode 100644
index 0000000000..8d193ab9f9
--- /dev/null
+++ b/scripts/merge-translation-pairing.ts
@@ -0,0 +1,42 @@
+/** Git merge-driver and explicit conflict-resolver entrypoint for pairing records. */
+
+import { execFileSync } from 'node:child_process'
+import { readFileSync, writeFileSync } from 'node:fs'
+import {
+  mergeTranslationPairingRecords,
+  resolveTranslationPairingConflicts,
+} from './translation-pairing-merge.ts'
+
+const args = process.argv.slice(2)
+
+try {
+  const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim()
+  if (args[0] === '--resolve') {
+    if (args.length !== 1) throw new Error('--resolve takes no paths; it inspects the unmerged index')
+    const resolved = resolveTranslationPairingConflicts(root)
+    if (resolved.length === 0) {
+      console.log('merge-translation-pairing: no unresolved pairing records')
+    } else {
+      for (const path of resolved) console.log(`merge-translation-pairing: resolved ${path}`)
+    }
+  } else {
+    if (args.length !== 4) {
+      throw new Error('merge-driver mode requires <ancestor> <current> <other> <repository-path>')
+    }
+    const [ancestorPath, currentPath, otherPath, metaPath] = args
+    if (ancestorPath === undefined || currentPath === undefined || otherPath === undefined || metaPath === undefined) {
+      throw new Error('merge-driver arguments are incomplete')
+    }
+    const result = mergeTranslationPairingRecords(
+      root,
+      metaPath,
+      readFileSync(ancestorPath, 'utf8'),
+      readFileSync(currentPath, 'utf8'),
+      readFileSync(otherPath, 'utf8'),
+    )
+    writeFileSync(currentPath, result.record)
+  }
+} catch (error) {
+  console.error(`merge-translation-pairing: ${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+}
diff --git a/scripts/translation-pairing-git.ts b/scripts/translation-pairing-git.ts
index 992f0abbb9..b18b2d5778 100644
--- a/scripts/translation-pairing-git.ts
+++ b/scripts/translation-pairing-git.ts
@@ -27,6 +27,39 @@ function runGit(root: string, args: string[], operation: string, input?: Buffer)
   return result.stdout
 }
 
+/** One regular stage-zero Git index entry and its exact blob bytes. */
+export interface GitIndexBlob {
+  /** Object ID recorded in the index. */
+  objectId: string
+  /** Blob bytes stored under that object ID. */
+  content: Buffer
+}
+
+/**
+ * Read one path from the Git index without consulting working-tree bytes.
+ *
+ * @param root - Repository root.
+ * @param path - Repository-relative path.
+ * @returns The stage-zero blob, or `undefined` when the path is absent.
+ * @throws Error when the path is unmerged or has an invalid index shape.
+ */
+export function readGitIndexBlob(root: string, path: string): GitIndexBlob | undefined {
+  const output = runGit(
+    root,
+    ['ls-files', '--stage', '-z', '--', path],
+    `git ls-files --stage for ${path}`,
+  ).toString('utf8')
+  const entries = output.split('\0').filter(Boolean)
+  if (entries.length === 0) return undefined
+  if (entries.length !== 1) throw new Error(`${path} does not have exactly one resolved index entry`)
+  const match = /^(?:\d+) ([0-9a-f]+) 0\t[\s\S]+$/.exec(entries[0] ?? '')
+  if (!match?.[1]) throw new Error(`${path} remains unmerged or has an invalid index entry`)
+  return {
+    objectId: match[1],
+    content: runGit(root, ['cat-file', 'blob', match[1]], `reading staged ${path}`),
+  }
+}
+
 /**
  * Persist exact working-tree bytes so a pairing record can later recover them
  * with `git cat-file`, even when they have never appeared in the index or a
diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
new file mode 100644
index 0000000000..c6a9a5bbb7
--- /dev/null
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -0,0 +1,255 @@
+/** Integration coverage for automatic and explicit pairing-record conflict resolution. */
+
+import { execFileSync, spawnSync } from 'node:child_process'
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts'
+import {
+  mergeTranslationPairingRecords,
+  resolveTranslationPairingConflicts,
+} from './translation-pairing-merge.ts'
+import {
+  renderTranslationPairingRecord,
+  translationPairPaths,
+} from './translation-pairing-record.ts'
+
+const driver = fileURLToPath(new URL('./merge-translation-pairing.ts', import.meta.url))
+const tsxLoader = fileURLToPath(import.meta.resolve('tsx/esm'))
+const fixtures: string[] = []
+
+interface Fixture {
+  env: NodeJS.ProcessEnv
+  root: string
+}
+
+afterEach(() => {
+  for (const fixture of fixtures.splice(0)) rmSync(fixture, { recursive: true, force: true })
+})
+
+function git(fixture: Fixture, args: string[]): string {
+  return execFileSync('git', ['-C', fixture.root, ...args], {
+    encoding: 'utf8',
+    env: fixture.env,
+  }).trim()
+}
+
+function write(root: string, path: string, content: string): void {
+  const absolute = join(root, path)
+  mkdirSync(dirname(absolute), { recursive: true })
+  writeFileSync(absolute, content)
+}
+
+function shellQuote(value: string): string {
+  return `"${value.replace(/["\\$`]/g, '\\$&')}"`
+}
+
+function createFixture(attributes = true): Fixture {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-merge-'))
+  fixtures.push(root)
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    GIT_AUTHOR_EMAIL: 'pairing@example.test',
+    GIT_AUTHOR_NAME: 'Pairing Test',
+    GIT_COMMITTER_EMAIL: 'pairing@example.test',
+    GIT_COMMITTER_NAME: 'Pairing Test',
+    GIT_CONFIG_GLOBAL: join(root, 'global.gitconfig'),
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_DEFAULT_HASH: 'sha1',
+  }
+  const fixture = { env, root }
+  execFileSync('git', ['init', '--quiet', '--initial-branch=master', root], { env })
+  if (attributes) write(root, '.gitattributes', '*.i18n.yaml merge=dsh-translation-pairing\n')
+  return fixture
+}
+
+function record(root: string, path: string, source: string, zh: string): string {
+  const paths = translationPairPaths(path)
+  write(root, paths.source, source)
+  write(root, paths.zh, zh)
+  const content = renderTranslationPairingRecord(paths, {
+    sourceHash: storeGitBlob(root, Buffer.from(source)),
+    zhHash: storeGitBlob(root, Buffer.from(zh)),
+  })
+  write(root, paths.meta, content)
+  return content
+}
+
+const baseSource = '# Guide\n\nEnglish | [中文](guide.zh.md)\n\nAlpha base.\n\nBeta base.\n'
+const baseZh = '# 指南\n\n[English](guide.md) | 中文\n\n甲基础。\n\n乙基础。\n'
+const currentSource = baseSource.replace('Alpha base.', 'Alpha current.')
+const currentZh = baseZh.replace('甲基础。', '甲当前。')
+const otherSource = baseSource.replace('Beta base.', 'Beta other.')
+const otherZh = baseZh.replace('乙基础。', '乙对侧。')
+const mergedSource = currentSource.replace('Beta base.', 'Beta other.')
+const mergedZh = currentZh.replace('乙基础。', '乙对侧。')
+
+function commitPair(fixture: Fixture, source: string, zh: string, message: string): string {
+  const sidecar = record(fixture.root, 'docs/guide.md', source, zh)
+  git(fixture, ['add', '.'])
+  git(fixture, ['commit', '-m', message])
+  return sidecar
+}
+
+function createDivergedPair(fixture: Fixture): { ancestor: string; current: string; other: string } {
+  const ancestor = commitPair(fixture, baseSource, baseZh, 'base')
+  git(fixture, ['switch', '-c', 'current'])
+  const current = commitPair(fixture, currentSource, currentZh, 'current')
+  git(fixture, ['switch', 'master'])
+  const other = commitPair(fixture, otherSource, otherZh, 'other')
+  git(fixture, ['switch', 'current'])
+  return { ancestor, current, other }
+}
+
+function expectMergedPair(fixture: Fixture): void {
+  expect(readFileSync(join(fixture.root, 'docs/guide.md'), 'utf8')).toBe(mergedSource)
+  expect(readFileSync(join(fixture.root, 'docs/guide.zh.md'), 'utf8')).toBe(mergedZh)
+  expect(readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')).toBe(
+    renderTranslationPairingRecord(translationPairPaths('docs/guide.md'), {
+      sourceHash: gitBlobHash(Buffer.from(mergedSource)),
+      zhHash: gitBlobHash(Buffer.from(mergedZh)),
+    }),
+  )
+}
+
+describe('translation pairing merge composition', () => {
+  it('rejects a pairing-record path outside the repository', () => {
+    const fixture = createFixture(false)
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      '../guide.i18n.yaml',
+      '',
+      '',
+      '',
+    )).toThrow('pairing record escapes the repository')
+  })
+
+  it('merges the owner blobs named by three valid records', () => {
+    const fixture = createFixture(false)
+    const records = createDivergedPair(fixture)
+
+    const result = mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      records.ancestor,
+      records.current,
+      records.other,
+    )
+
+    expect(result.sourceContent.toString('utf8')).toBe(mergedSource)
+    expect(result.zhContent.toString('utf8')).toBe(mergedZh)
+    expect(result.sourceHash).toBe(gitBlobHash(Buffer.from(mergedSource)))
+    expect(result.zhHash).toBe(gitBlobHash(Buffer.from(mergedZh)))
+  })
+
+  it('leaves owner-content conflicts for a human', () => {
+    const fixture = createFixture(false)
+    const ancestor = record(fixture.root, 'docs/guide.md', baseSource, baseZh)
+    const current = record(
+      fixture.root,
+      'docs/guide.md',
+      baseSource.replace('Alpha base.', 'Alpha current.'),
+      baseZh.replace('甲基础。', '甲当前。'),
+    )
+    const other = record(
+      fixture.root,
+      'docs/guide.md',
+      baseSource.replace('Alpha base.', 'Alpha other.'),
+      baseZh.replace('甲基础。', '甲对侧。'),
+    )
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      ancestor,
+      current,
+      other,
+    )).toThrow('docs/guide.md has content conflicts')
+  })
+
+  it('rejects structurally divergent clean owner merges', () => {
+    const fixture = createFixture(false)
+    const ancestor = record(fixture.root, 'docs/guide.md', baseSource, baseZh)
+    const current = record(fixture.root, 'docs/guide.md', currentSource, currentZh)
+    const other = record(
+      fixture.root,
+      'docs/guide.md',
+      `${otherSource}\n## Extra\n`,
+      otherZh,
+    )
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      ancestor,
+      current,
+      other,
+    )).toThrow('clean merges diverge structurally')
+  })
+
+  it('refuses owners assigned to another merge strategy', () => {
+    const fixture = createFixture(false)
+    write(fixture.root, '.gitattributes', 'docs/*.md merge=custom-owner\n')
+    const records = createDivergedPair(fixture)
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      records.ancestor,
+      records.current,
+      records.other,
+    )).toThrow('docs/guide.md uses merge=custom-owner')
+  })
+
+  it('runs as Git\'s custom driver and commits a clean composed record', () => {
+    const fixture = createFixture()
+    createDivergedPair(fixture)
+    const command = [
+      shellQuote(process.execPath),
+      '--import', shellQuote(tsxLoader),
+      shellQuote(driver),
+      '%O', '%A', '%B', '%P',
+    ].join(' ')
+    git(fixture, ['config', 'merge.dsh-translation-pairing.driver', command])
+
+    git(fixture, ['merge', '--no-edit', 'master'])
+
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('')
+    expectMergedPair(fixture)
+  })
+
+  it('resolves an already-stopped generated-only conflict from index stages', () => {
+    const fixture = createFixture(false)
+    createDivergedPair(fixture)
+    const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+      encoding: 'utf8',
+      env: fixture.env,
+    })
+    expect(merge.status).toBe(1)
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+
+    expect(resolveTranslationPairingConflicts(fixture.root)).toEqual(['docs/guide.i18n.yaml'])
+
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('')
+    expectMergedPair(fixture)
+  })
+
+  it('refuses to confirm unstaged owner bytes after a stopped merge', () => {
+    const fixture = createFixture(false)
+    createDivergedPair(fixture)
+    const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+      encoding: 'utf8',
+      env: fixture.env,
+    })
+    expect(merge.status).toBe(1)
+    write(fixture.root, 'docs/guide.md', `${mergedSource}\nunstaged\n`)
+
+    expect(() => resolveTranslationPairingConflicts(fixture.root)).toThrow(
+      'docs/guide.md has unstaged content',
+    )
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+  })
+})
diff --git a/scripts/translation-pairing-merge.ts b/scripts/translation-pairing-merge.ts
new file mode 100644
index 0000000000..3297e30ea2
--- /dev/null
+++ b/scripts/translation-pairing-merge.ts
@@ -0,0 +1,267 @@
+/** Fail-closed composition of bilingual pairing records during Git merges. */
+
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { gitBlobHash, readGitIndexBlob, storeGitBlob } from './translation-pairing-git.ts'
+import {
+  linksTo,
+  isTranslationScopeFile,
+  parseTranslationMarkdown,
+  translationStructureDiff,
+  translationStructureSignature,
+} from './translation-pairing.ts'
+import {
+  parseTranslationPairingRecord,
+  renderTranslationPairingRecord,
+  translationPairPathsFromMeta,
+  type TranslationPairPaths,
+  type TranslationPairingRecord,
+} from './translation-pairing-record.ts'
+
+const MAX_GIT_OUTPUT = 1 << 26
+const UNMERGED_ENTRY = /^(\d+) ([0-9a-f]+) ([123])\t([\s\S]+)$/
+
+/** A mechanically composed record and the exact merged owner contents it names. */
+export interface TranslationPairingMergeResult extends TranslationPairingRecord {
+  /** Canonical generated sidecar text. */
+  record: string
+  /** Clean three-way merge of the English owner. */
+  sourceContent: Buffer
+  /** Clean three-way merge of the Simplified Chinese owner. */
+  zhContent: Buffer
+}
+
+interface UnmergedStages {
+  ancestor?: string
+  current?: string
+  other?: string
+}
+
+function runGit(root: string, args: string[], operation: string, input?: Buffer): Buffer {
+  const result = spawnSync('git', ['-C', root, ...args], {
+    input,
+    maxBuffer: MAX_GIT_OUTPUT,
+  })
+  if (result.error) throw new Error(`${operation} failed: ${result.error.message}`, { cause: result.error })
+  if (result.status !== 0) {
+    throw new Error(`${operation} failed with status ${String(result.status)}: ${result.stderr.toString('utf8').trim()}`)
+  }
+  return result.stdout
+}
+
+function readGitBlob(root: string, objectId: string, owner: string): Buffer {
+  const content = runGit(root, ['cat-file', 'blob', objectId], `reading ${owner} blob ${objectId}`)
+  if (gitBlobHash(content) !== objectId) {
+    throw new Error(`${owner} record names ${objectId}, which is not its SHA-1 git blob hash`)
+  }
+  return content
+}
+
+function assertDefaultTextMerge(root: string, paths: TranslationPairPaths): void {
+  const output = runGit(
+    root,
+    ['check-attr', '-z', 'merge', '--', paths.source, paths.zh],
+    'checking bilingual owner merge attributes',
+  ).toString('utf8')
+  const fields = output.split('\0')
+  fields.pop()
+  for (let index = 0; index < fields.length; index += 3) {
+    const path = fields[index]
+    const value = fields[index + 2]
+    if (path === undefined || value === undefined) {
+      throw new Error('git check-attr returned a malformed result')
+    }
+    if (!['unspecified', 'set', 'text'].includes(value)) {
+      throw new Error(`${path} uses merge=${value}; the pairing driver only composes Git's default text merge`)
+    }
+  }
+}
+
+function mergeBlobTriplet(
+  root: string,
+  owner: string,
+  ancestor: Buffer,
+  current: Buffer,
+  other: Buffer,
+): Buffer {
+  const temporary = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-merge-'))
+  try {
+    const ancestorPath = join(temporary, 'ancestor')
+    const currentPath = join(temporary, 'current')
+    const otherPath = join(temporary, 'other')
+    writeFileSync(ancestorPath, ancestor)
+    writeFileSync(currentPath, current)
+    writeFileSync(otherPath, other)
+    const result = spawnSync('git', [
+      '-C', root,
+      'merge-file', '-p',
+      '-L', `${owner}:current`,
+      '-L', `${owner}:ancestor`,
+      '-L', `${owner}:other`,
+      currentPath, ancestorPath, otherPath,
+    ], { maxBuffer: MAX_GIT_OUTPUT })
+    if (result.error) {
+      throw new Error(`merging ${owner} failed: ${result.error.message}`, { cause: result.error })
+    }
+    if (result.status !== 0) {
+      const kind = result.status !== null && result.status > 0 && result.status <= 127
+        ? 'has content conflicts'
+        : `failed with status ${String(result.status)}`
+      throw new Error(`${owner} ${kind}`)
+    }
+    return result.stdout
+  } finally {
+    rmSync(temporary, { recursive: true, force: true })
+  }
+}
+
+function loadRecordOwners(
+  root: string,
+  label: string,
+  content: string,
+  paths: TranslationPairPaths,
+): { source: Buffer; zh: Buffer } {
+  const record = parseTranslationPairingRecord(content, paths)
+  if (record === undefined) throw new Error(`${label} ${paths.meta} is not a valid two-hash pairing record`)
+  return {
+    source: readGitBlob(root, record.sourceHash, `${label} ${paths.source}`),
+    zh: readGitBlob(root, record.zhHash, `${label} ${paths.zh}`),
+  }
+}
+
+function assertMergedPairStructure(paths: TranslationPairPaths, source: Buffer, zh: Buffer): void {
+  const sourceTree = parseTranslationMarkdown(source.toString('utf8'))
+  const zhTree = parseTranslationMarkdown(zh.toString('utf8'))
+  if (!linksTo(sourceTree, basename(paths.zh))) {
+    throw new Error(`${paths.source} clean merge lost its language-switcher link to ${basename(paths.zh)}`)
+  }
+  if (!linksTo(zhTree, basename(paths.source))) {
+    throw new Error(`${paths.zh} clean merge lost its language-switcher link to ${basename(paths.source)}`)
+  }
+  const divergences = translationStructureDiff(
+    translationStructureSignature(sourceTree, basename(paths.zh)),
+    translationStructureSignature(zhTree, basename(paths.source)),
+  )
+  if (divergences.length > 0) {
+    throw new Error(`${paths.source} and ${paths.zh} clean merges diverge structurally: ${divergences.join('; ')}`)
+  }
+}
+
+function normalizeMetaPath(root: string, meta: string): string {
+  if (isAbsolute(meta)) throw new Error(`pairing record must be repository-relative: ${JSON.stringify(meta)}`)
+  const repositoryRelative = relative(resolve(root), resolve(root, meta))
+  if (repositoryRelative === '' || repositoryRelative === '..' || repositoryRelative.startsWith(`..${sep}`)) {
+    throw new Error(`pairing record escapes the repository: ${JSON.stringify(meta)}`)
+  }
+  return repositoryRelative.split(sep).join('/')
+}
+
+/**
+ * Compose one generated sidecar from the ancestor, current, and other records.
+ *
+ * Each input record is already a confirmation of its two owner blobs. The
+ * result exists only when Git's default text merge succeeds independently for
+ * both languages and the composed documents retain the pairing structure.
+ *
+ * @param root - Repository root containing the referenced Git objects.
+ * @param metaPath - Repository-relative sidecar path.
+ * @param ancestorRecord - Common-ancestor sidecar text.
+ * @param currentRecord - Current-side sidecar text.
+ * @param otherRecord - Other-side sidecar text.
+ * @returns The canonical record and exact merged owner contents.
+ * @throws Error when the input is not mechanically composable.
+ */
+export function mergeTranslationPairingRecords(
+  root: string,
+  metaPath: string,
+  ancestorRecord: string,
+  currentRecord: string,
+  otherRecord: string,
+): TranslationPairingMergeResult {
+  const normalizedMeta = normalizeMetaPath(root, metaPath)
+  if (!isTranslationScopeFile(normalizedMeta)) {
+    throw new Error(`${normalizedMeta} is outside the active bilingual documentation corpus`)
+  }
+  const paths = translationPairPathsFromMeta(normalizedMeta)
+  assertDefaultTextMerge(root, paths)
+  const ancestor = loadRecordOwners(root, 'ancestor', ancestorRecord, paths)
+  const current = loadRecordOwners(root, 'current', currentRecord, paths)
+  const other = loadRecordOwners(root, 'other', otherRecord, paths)
+  const sourceContent = mergeBlobTriplet(root, paths.source, ancestor.source, current.source, other.source)
+  const zhContent = mergeBlobTriplet(root, paths.zh, ancestor.zh, current.zh, other.zh)
+  assertMergedPairStructure(paths, sourceContent, zhContent)
+  const sourceHash = storeGitBlob(root, sourceContent)
+  const zhHash = storeGitBlob(root, zhContent)
+  return {
+    record: renderTranslationPairingRecord(paths, { sourceHash, zhHash }),
+    sourceContent,
+    sourceHash,
+    zhContent,
+    zhHash,
+  }
+}
+
+function unmergedSidecars(root: string): Map<string, UnmergedStages> {
+  const output = runGit(root, ['ls-files', '--unmerged', '-z'], 'listing unresolved merge entries').toString('utf8')
+  const records = new Map<string, UnmergedStages>()
+  for (const entry of output.split('\0')) {
+    if (entry === '') continue
+    const match = UNMERGED_ENTRY.exec(entry)
+    if (!match?.[2] || !match[3] || match[4] === undefined) {
+      throw new Error(`git ls-files returned a malformed unmerged entry: ${JSON.stringify(entry)}`)
+    }
+    const path = match[4]
+    if (!path.endsWith('.i18n.yaml')) continue
+    const stages = records.get(path) ?? {}
+    const field = match[3] === '1' ? 'ancestor' : match[3] === '2' ? 'current' : 'other'
+    stages[field] = match[2]
+    records.set(path, stages)
+  }
+  return records
+}
+
+/**
+ * Resolve every mechanically composable `.i18n.yaml` conflict in the index.
+ *
+ * The command first proves that Git's already-staged owner merges match the
+ * independently composed contents, then writes and stages all sidecars as one
+ * batch. Other conflicts remain untouched.
+ *
+ * @param root - Repository root with an in-progress merge-like operation.
+ * @returns Repository-relative sidecar paths resolved and staged.
+ */
+export function resolveTranslationPairingConflicts(root: string): string[] {
+  const resolutions: { path: string; record: string }[] = []
+  for (const [metaPath, stages] of [...unmergedSidecars(root)].sort(([left], [right]) => left.localeCompare(right))) {
+    if (stages.ancestor === undefined || stages.current === undefined || stages.other === undefined) {
+      throw new Error(`${metaPath} is an add/delete or incomplete-stage conflict and requires manual resolution`)
+    }
+    const result = mergeTranslationPairingRecords(
+      root,
+      metaPath,
+      readGitBlob(root, stages.ancestor, `ancestor ${metaPath}`).toString('utf8'),
+      readGitBlob(root, stages.current, `current ${metaPath}`).toString('utf8'),
+      readGitBlob(root, stages.other, `other ${metaPath}`).toString('utf8'),
+    )
+    const paths = translationPairPathsFromMeta(metaPath)
+    if (readGitIndexBlob(root, paths.source)?.objectId !== result.sourceHash) {
+      throw new Error(`${paths.source} staged merge does not match the pairing driver's clean merge`)
+    }
+    if (readGitIndexBlob(root, paths.zh)?.objectId !== result.zhHash) {
+      throw new Error(`${paths.zh} staged merge does not match the pairing driver's clean merge`)
+    }
+    for (const [path, expected] of [[paths.source, result.sourceHash], [paths.zh, result.zhHash]] as const) {
+      if (gitBlobHash(readFileSync(join(root, path))) !== expected) {
+        throw new Error(`${path} has unstaged content; refusing to confirm bytes outside the merge result`)
+      }
+    }
+    resolutions.push({ path: metaPath, record: result.record })
+  }
+  for (const resolution of resolutions) writeFileSync(join(root, resolution.path), resolution.record)
+  if (resolutions.length > 0) {
+    runGit(root, ['add', '--', ...resolutions.map(resolution => resolution.path)], 'staging resolved pairing records')
+  }
+  return resolutions.map(resolution => resolution.path)
+}
diff --git a/scripts/translation-pairing-record.ts b/scripts/translation-pairing-record.ts
new file mode 100644
index 0000000000..d4481ea5b4
--- /dev/null
+++ b/scripts/translation-pairing-record.ts
@@ -0,0 +1,99 @@
+/** Canonical paths, parsing, and rendering for bilingual pairing records. */
+
+import { basename } from 'node:path'
+
+/** The three repository-relative paths that form one bilingual pair. */
+export interface TranslationPairPaths {
+  /** English document path. */
+  source: string
+  /** Simplified Chinese document path. */
+  zh: string
+  /** Generated consistency-record path. */
+  meta: string
+}
+
+/** The two content hashes recorded for a bilingual pair. */
+export interface TranslationPairingRecord {
+  /** Git blob hash of the English document. */
+  sourceHash: string
+  /** Git blob hash of the Simplified Chinese document. */
+  zhHash: string
+}
+
+const META_LINE = /^([^:#]+\.md): ([0-9a-f]{40})$/
+
+/**
+ * Derive the counterpart and consistency-record paths from an English document.
+ *
+ * @param source - Repository-relative English Markdown path.
+ * @returns The complete three-path pair.
+ */
+export function translationPairPaths(source: string): TranslationPairPaths {
+  if (!source.endsWith('.md') || source.endsWith('.zh.md')) {
+    throw new Error(`expected an English Markdown path, received ${JSON.stringify(source)}`)
+  }
+  return {
+    source,
+    zh: source.replace(/\.md$/, '.zh.md'),
+    meta: source.replace(/\.md$/, '.i18n.yaml'),
+  }
+}
+
+/**
+ * Derive one pair from its consistency-record path.
+ *
+ * @param meta - Repository-relative `foo.i18n.yaml` path.
+ * @returns The complete three-path pair.
+ */
+export function translationPairPathsFromMeta(meta: string): TranslationPairPaths {
+  if (!meta.endsWith('.i18n.yaml')) {
+    throw new Error(`expected a bilingual consistency-record path, received ${JSON.stringify(meta)}`)
+  }
+  return translationPairPaths(meta.replace(/\.i18n\.yaml$/, '.md'))
+}
+
+/**
+ * Parse a consistency record for its expected sibling names.
+ *
+ * @param content - Complete sidecar text.
+ * @param paths - Expected sibling paths.
+ * @returns The two hashes, or `undefined` for malformed, duplicate, or unexpected keys.
+ */
+export function parseTranslationPairingRecord(
+  content: string,
+  paths: TranslationPairPaths,
+): TranslationPairingRecord | undefined {
+  const hashes = new Map<string, string>()
+  for (const line of content.split('\n')) {
+    if (line === '' || line.startsWith('#')) continue
+    const match = META_LINE.exec(line)
+    if (!match?.[1] || !match[2] || hashes.has(match[1])) return undefined
+    hashes.set(match[1], match[2])
+  }
+  const sourceHash = hashes.get(basename(paths.source))
+  const zhHash = hashes.get(basename(paths.zh))
+  if (hashes.size !== 2 || sourceHash === undefined || zhHash === undefined) return undefined
+  return { sourceHash, zhHash }
+}
+
+/**
+ * Render the canonical consistency record for a pair.
+ *
+ * @param paths - Pair paths written into the record and its recovery command.
+ * @param record - Confirmed content hashes.
+ * @returns Canonical YAML text with exactly one trailing newline.
+ */
+export function renderTranslationPairingRecord(
+  paths: TranslationPairPaths,
+  record: TranslationPairingRecord,
+): string {
+  return [
+    '# 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 ${paths.source}`,
+    `${basename(paths.source)}: ${record.sourceHash}`,
+    `${basename(paths.zh)}: ${record.zhHash}`,
+    '',
+  ].join('\n')
+}
diff --git a/scripts/translation-pairing.spec.ts b/scripts/translation-pairing.spec.ts
index 4d44266887..1073495d08 100644
--- a/scripts/translation-pairing.spec.ts
+++ b/scripts/translation-pairing.spec.ts
@@ -1,11 +1,16 @@
 /** Regression tests for bilingual snapshots, corpus scope, and structure. */
 
 import { execFileSync, spawnSync } from 'node:child_process'
-import { mkdtempSync, rmSync } from 'node:fs'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
-import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts'
+import { gitBlobHash, readGitIndexBlob, storeGitBlob } from './translation-pairing-git.ts'
+import {
+  parseTranslationPairingRecord,
+  renderTranslationPairingRecord,
+  translationPairPaths,
+} from './translation-pairing-record.ts'
 import {
   isTranslationScopeFile,
   pairAnchorOfArgument,
@@ -74,6 +79,28 @@ describe('translation pairing snapshots', () => {
     }
   })
 
+  it('reads staged bytes independently of the working tree', () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-index-'))
+    try {
+      execFileSync('git', ['init', '--quiet', root], {
+        env: { ...process.env, GIT_DEFAULT_HASH: 'sha1' },
+      })
+      execFileSync('git', ['-C', root, 'config', 'user.email', 'pairing@example.test'])
+      execFileSync('git', ['-C', root, 'config', 'user.name', 'Pairing Test'])
+      writeFileSync(join(root, 'owner.md'), 'staged')
+      execFileSync('git', ['-C', root, 'add', 'owner.md'])
+      writeFileSync(join(root, 'owner.md'), 'unstaged')
+
+      const indexed = readGitIndexBlob(root, 'owner.md')
+
+      expect(indexed?.content.toString('utf8')).toBe('staged')
+      expect(indexed?.objectId).toBe(gitBlobHash(Buffer.from('staged')))
+      expect(readGitIndexBlob(root, 'absent.md')).toBeUndefined()
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
   it.skipIf(!supportsSha256ObjectFormat)('rejects an object format that pairing records cannot represent', () => {
     const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-'))
     try {
@@ -113,6 +140,32 @@ describe('translation pairing manifest', () => {
   })
 })
 
+describe('translation pairing records', () => {
+  const paths = translationPairPaths('docs/foo.md')
+  const record = {
+    sourceHash: '1'.repeat(40),
+    zhHash: '2'.repeat(40),
+  }
+
+  it('round-trips the canonical two-hash record', () => {
+    expect(parseTranslationPairingRecord(renderTranslationPairingRecord(paths, record), paths)).toEqual(record)
+  })
+
+  it('rejects duplicate or unexpected keys', () => {
+    expect(parseTranslationPairingRecord([
+      `foo.md: ${'1'.repeat(40)}`,
+      `foo.md: ${'3'.repeat(40)}`,
+      `foo.zh.md: ${'2'.repeat(40)}`,
+      '',
+    ].join('\n'), paths)).toBeUndefined()
+    expect(parseTranslationPairingRecord([
+      `foo.md: ${'1'.repeat(40)}`,
+      `bar.zh.md: ${'2'.repeat(40)}`,
+      '',
+    ].join('\n'), paths)).toBeUndefined()
+  })
+})
+
 describe('translation scope discovery', () => {
   it.each([
     'README.md',
@@ -186,28 +239,56 @@ describe('pair CLI arguments', () => {
 
   it('scopes a check to named pairs and dedupes the three spellings', () => {
     expect(parseTranslationPairingCliArgs(['docs/foo.zh.md', 'docs/foo.i18n.yaml', 'docs/bar.md'])).toEqual({
+      input: 'worktree',
       mode: 'check',
       scope: 'pairs',
       anchors: ['docs/bar.md', 'docs/foo.md'],
     })
-    expect(parseTranslationPairingCliArgs([])).toEqual({ mode: 'check', scope: 'corpus', anchors: [] })
+    expect(parseTranslationPairingCliArgs([])).toEqual({
+      input: 'worktree',
+      mode: 'check',
+      scope: 'corpus',
+      anchors: [],
+    })
   })
 
   it('requires --write to name confirmed pairs or opt into --all', () => {
     expect(() => parseTranslationPairingCliArgs(['--write'])).toThrow('requires the pair(s) you confirmed')
     expect(parseTranslationPairingCliArgs(['--write', 'docs/foo.md'])).toEqual({
+      input: 'worktree',
       mode: 'write',
       scope: 'pairs',
       anchors: ['docs/foo.md'],
     })
-    expect(parseTranslationPairingCliArgs(['--write', '--all'])).toEqual({ mode: 'write', scope: 'corpus', anchors: [] })
+    expect(parseTranslationPairingCliArgs(['--write', '--all'])).toEqual({
+      input: 'worktree',
+      mode: 'write',
+      scope: 'corpus',
+      anchors: [],
+    })
     expect(() => parseTranslationPairingCliArgs(['--write', '--all', 'docs/foo.md'])).toThrow('not both')
   })
 
   it('keeps --list corpus-only and rejects unknown flags', () => {
-    expect(parseTranslationPairingCliArgs(['--list'])).toEqual({ mode: 'list', scope: 'corpus', anchors: [] })
+    expect(parseTranslationPairingCliArgs(['--list'])).toEqual({
+      input: 'worktree',
+      mode: 'list',
+      scope: 'corpus',
+      anchors: [],
+    })
     expect(() => parseTranslationPairingCliArgs(['--list', 'docs/foo.md'])).toThrow('takes no other flags or paths')
     expect(() => parseTranslationPairingCliArgs(['--all'])).toThrow('--all only applies to --write')
     expect(() => parseTranslationPairingCliArgs(['--frobnicate'])).toThrow('unknown flag(s): --frobnicate')
   })
+
+  it('makes cached verification a named, read-only index check', () => {
+    expect(parseTranslationPairingCliArgs(['--cached', 'docs/foo.i18n.yaml'])).toEqual({
+      input: 'index',
+      mode: 'check',
+      scope: 'pairs',
+      anchors: ['docs/foo.md'],
+    })
+    expect(() => parseTranslationPairingCliArgs(['--cached'])).toThrow('requires the staged pair paths')
+    expect(() => parseTranslationPairingCliArgs(['--cached', '--write', 'docs/foo.md'])).toThrow('read-only')
+  })
 })
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
index 7f24d9bce7..6d6893f843 100644
--- a/scripts/translation-pairing.ts
+++ b/scripts/translation-pairing.ts
@@ -120,6 +120,8 @@ export function pairAnchorOfArgument(argument: string): string {
 
 /** A parsed `verify-translation-pairing` invocation. */
 export interface TranslationPairingCliRequest {
+  /** Content plane read by the check. Writes and corpus checks use the working tree. */
+  input: 'worktree' | 'index'
   mode: 'check' | 'list' | 'write'
   /** `corpus` runs discovery over the whole tree; `pairs` touches only the named anchors. */
   scope: 'corpus' | 'pairs'
@@ -142,24 +144,32 @@ export interface TranslationPairingCliRequest {
 export function parseTranslationPairingCliArgs(argv: string[]): TranslationPairingCliRequest {
   const flags = argv.filter(argument => argument.startsWith('--'))
   const anchors = [...new Set(argv.filter(argument => !argument.startsWith('--')).map(pairAnchorOfArgument))].sort()
-  const unknown = flags.filter(flag => !['--list', '--write', '--all'].includes(flag))
+  const unknown = flags.filter(flag => !['--list', '--write', '--all', '--cached'].includes(flag))
   if (unknown.length > 0) throw new Error(`unknown flag(s): ${unknown.join(', ')}`)
   const listMode = flags.includes('--list')
   const writeMode = flags.includes('--write')
   const allMode = flags.includes('--all')
-  if (listMode && (writeMode || allMode || anchors.length > 0)) {
+  const cachedMode = flags.includes('--cached')
+  if (listMode && (writeMode || allMode || cachedMode || anchors.length > 0)) {
     throw new Error('--list reports the whole corpus and takes no other flags or paths')
   }
   if (allMode && !writeMode) throw new Error('--all only applies to --write')
+  if (cachedMode && writeMode) throw new Error('--cached is a read-only index check and cannot be combined with --write')
+  if (cachedMode && anchors.length === 0) throw new Error('--cached requires the staged pair paths to check')
   if (writeMode) {
     if (anchors.length > 0 && allMode) throw new Error('--write takes either pair paths or --all, not both')
     if (anchors.length === 0 && !allMode) {
       throw new Error('--write requires the pair(s) you confirmed (any file of a pair), or --all to re-record every complete pair; recording pairs you did not review blesses unconfirmed content')
     }
-    return { mode: 'write', scope: allMode ? 'corpus' : 'pairs', anchors }
+    return { input: 'worktree', mode: 'write', scope: allMode ? 'corpus' : 'pairs', anchors }
+  }
+  if (listMode) return { input: 'worktree', mode: 'list', scope: 'corpus', anchors: [] }
+  return {
+    input: cachedMode ? 'index' : 'worktree',
+    mode: 'check',
+    scope: anchors.length > 0 ? 'pairs' : 'corpus',
+    anchors,
   }
-  if (listMode) return { mode: 'list', scope: 'corpus', anchors: [] }
-  return { mode: 'check', scope: anchors.length > 0 ? 'pairs' : 'corpus', anchors }
 }
 
 /** The structural surface compared between the two sides of a pair. */
diff --git a/scripts/verify-translation-pairing.ts b/scripts/verify-translation-pairing.ts
index 4ebd664cb7..59818183e3 100644
--- a/scripts/verify-translation-pairing.ts
+++ b/scripts/verify-translation-pairing.ts
@@ -3,15 +3,21 @@
  * blob hashes for every in-scope document. The manifest contains only explicit
  * exclusions, which may have neither a counterpart nor a sidecar.
  * `--list` reports state; `--write <pairs...>` records the named confirmed
- * pairs (`--write --all` records every complete pair); a check or write named
- * with pair paths touches only those pairs, so update iteration does not pay
- * for a corpus scan. Translation quality remains a review responsibility.
+ * pairs (`--write --all` records every complete pair); `--cached <pairs...>`
+ * checks exact index bytes for hooks. A check or write named with pair paths
+ * touches only those pairs, so update iteration does not pay for a corpus
+ * scan. Translation quality remains a review responsibility.
  * See `docs/i18n/README.md` for the owning contract.
  */
 
 import { existsSync, globSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, join, resolve, sep } from 'node:path'
-import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts'
+import { gitBlobHash, readGitIndexBlob, storeGitBlob } from './translation-pairing-git.ts'
+import {
+  parseTranslationPairingRecord,
+  renderTranslationPairingRecord,
+  translationPairPaths,
+} from './translation-pairing-record.ts'
 import {
   linksTo,
   parseTranslationMarkdown,
@@ -33,6 +39,24 @@ try {
 }
 const listMode = request.mode === 'list'
 const writeMode = request.mode === 'write'
+const indexMode = request.input === 'index'
+
+const contentCache = new Map<string, Buffer | undefined>()
+
+/** Read one repository path from the selected worktree or index plane. */
+function readRepositoryFile(file: string): Buffer | undefined {
+  if (contentCache.has(file)) return contentCache.get(file)
+  const content = indexMode
+    ? readGitIndexBlob(root, file)?.content
+    : existsSync(join(root, file)) ? readFileSync(join(root, file)) : undefined
+  contentCache.set(file, content)
+  return content
+}
+
+/** Whether one path exists in the selected content plane. */
+function repositoryFileExists(file: string): boolean {
+  return readRepositoryFile(file) !== undefined
+}
 
 /** Discover source Markdown and pairing sidecars before applying the corpus predicate. */
 const SCOPE_PATTERNS = [
@@ -42,7 +66,11 @@ const SCOPE_PATTERNS = [
   '.agents/notes/**/*.i18n.yaml',
 ]
 
-const manifest = parseTranslationPairingManifest(readFileSync(join(root, 'scripts/translation-pairing.manifest.json'), 'utf8'))
+const manifestContent = readRepositoryFile('scripts/translation-pairing.manifest.json')
+if (manifestContent === undefined) {
+  throw new Error('scripts/translation-pairing.manifest.json is missing from the selected content plane')
+}
+const manifest = parseTranslationPairingManifest(manifestContent.toString('utf8'))
 
 /**
  * An excluded entry ending in `/` excludes the whole directory. The trailing
@@ -54,50 +82,20 @@ function isExcluded(file: string): boolean {
   return manifest.excluded.some(entry => (entry.endsWith('/') ? file.startsWith(entry) : file === entry))
 }
 
-/** The three paths of a pair, derived from the English-file path. */
-function pairPaths(source: string): { zh: string; meta: string } {
-  return { zh: source.replace(/\.md$/, '.zh.md'), meta: source.replace(/\.md$/, '.i18n.yaml') }
-}
-
-const META_LINE = /^([^:#]+\.md): ([0-9a-f]{40})$/
-
-/** Parse a `foo.i18n.yaml` consistency record: basename → recorded blob hash. */
-function parseMeta(content: string): Map<string, string> | undefined {
-  const out = new Map<string, string>()
-  for (const line of content.split('\n')) {
-    if (line === '' || line.startsWith('#')) continue
-    const match = META_LINE.exec(line)
-    if (!match?.[1] || !match[2]) return undefined
-    out.set(match[1], match[2])
-  }
-  return out
-}
-
-/** Render a `foo.i18n.yaml` consistency record. */
-function renderMeta(source: string, sourceHash: string, zh: string, zhHash: string): string {
-  return [
-    '# 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 ${source}`,
-    `${basename(source)}: ${sourceHash}`,
-    `${basename(zh)}: ${zhHash}`,
-    '',
-  ].join('\n')
-}
-
 // Enumerate the scope once: the whole corpus, or exactly the named pairs'
 // three files (a named pair whose files are absent is caught by the same
 // completeness rules that cover discovered remnants).
 const files = new Set<string>()
 if (request.scope === 'pairs') {
   for (const anchor of request.anchors) {
-    for (const file of [anchor, ...Object.values(pairPaths(anchor))]) {
-      if (existsSync(join(root, file))) files.add(file)
+    const { source, zh, meta } = translationPairPaths(anchor)
+    for (const file of [source, zh, meta]) {
+      if (repositoryFileExists(file)) files.add(file)
     }
-    // A named anchor with no files on disk still enters the source list so
-    // the check reports it instead of silently passing an empty scope.
-    if (!existsSync(join(root, anchor))) files.add(anchor)
+    // A named worktree anchor with no files still enters the source list so
+    // an interactive check reports it. An index check accepts a complete
+    // three-file deletion and still rejects every partial deletion below.
+    if (!indexMode && !repositoryFileExists(anchor)) files.add(anchor)
   }
 } else {
   for (const pattern of SCOPE_PATTERNS) {
@@ -113,8 +111,11 @@ const sources = [...files].filter(f => f.endsWith('.md') && !f.endsWith('.zh.md'
 
 if (request.scope === 'pairs') {
   const rejected = request.anchors.filter(anchor => !isTranslationScopeFile(anchor) || isExcluded(anchor))
-  const absent = request.anchors.filter(anchor => ![anchor, ...Object.values(pairPaths(anchor))].some(file => existsSync(join(root, file))))
-  if (rejected.length > 0 || absent.length > 0) {
+  const absent = request.anchors.filter((anchor) => {
+    const { source, zh, meta } = translationPairPaths(anchor)
+    return ![source, zh, meta].some(repositoryFileExists)
+  })
+  if (rejected.length > 0 || (!indexMode && absent.length > 0)) {
     for (const anchor of rejected) {
       console.error(`verify-translation-pairing: ${anchor} is not an in-scope pair (excluded or outside the documentation corpus; see docs/i18n/README.md)`)
     }
@@ -132,20 +133,25 @@ if (writeMode) {
   let written = 0
   for (const source of sources) {
     if (isExcluded(source)) continue
-    const { zh, meta } = pairPaths(source)
-    if (!existsSync(join(root, source)) || !existsSync(join(root, zh))) {
+    const paths = translationPairPaths(source)
+    const { zh, meta } = paths
+    if (!repositoryFileExists(source) || !repositoryFileExists(zh)) {
       if (request.scope === 'pairs') {
-        console.error(`verify-translation-pairing: cannot record ${source}: missing ${existsSync(join(root, source)) ? zh : source}`)
+        console.error(`verify-translation-pairing: cannot record ${source}: missing ${repositoryFileExists(source) ? zh : source}`)
         process.exit(2)
       }
       continue
     }
-    const sourceContent = readFileSync(join(root, source))
-    const zhContent = readFileSync(join(root, zh))
+    const sourceContent = readRepositoryFile(source)
+    const zhContent = readRepositoryFile(zh)
+    if (sourceContent === undefined || zhContent === undefined) throw new Error(`${source}: complete pair became unreadable`)
     // A consistency record is also a recovery pointer for the briefing
     // generator. Persist both snapshots even when the sidecar text is already
     // current, because the bytes may exist only in this working tree.
-    const record = renderMeta(source, storeGitBlob(root, sourceContent), zh, storeGitBlob(root, zhContent))
+    const record = renderTranslationPairingRecord(paths, {
+      sourceHash: storeGitBlob(root, sourceContent),
+      zhHash: storeGitBlob(root, zhContent),
+    })
     if (existsSync(join(root, meta)) && readFileSync(join(root, meta), 'utf8') === record) continue
     writeFileSync(join(root, meta), record)
     console.log(`verify-translation-pairing: recorded ${meta}`)
@@ -161,8 +167,8 @@ const state = new Map<string, 'ok' | 'out-of-sync' | 'missing'>()
 // 1. Every discovered, non-excluded source merges bilingual.
 for (const source of sources) {
   if (isExcluded(source)) continue
-  const { zh } = pairPaths(source)
-  if (!existsSync(join(root, zh))) {
+  const { zh } = translationPairPaths(source)
+  if (!repositoryFileExists(zh)) {
     errors.push(`${source}: in-scope documentation must merge bilingual (docs/i18n/README.md); add the counterpart and record the pair`)
     state.set(source, 'missing')
   }
@@ -176,8 +182,13 @@ for (const zh of translations) pairAnchors.add(zh.replace(/\.zh\.md$/, '.md'))
 for (const meta of metas) pairAnchors.add(meta.replace(/\.i18n\.yaml$/, '.md'))
 
 for (const source of [...pairAnchors].sort()) {
-  const { zh, meta } = pairPaths(source)
-  const have = { source: existsSync(join(root, source)), zh: existsSync(join(root, zh)), meta: existsSync(join(root, meta)) }
+  const paths = translationPairPaths(source)
+  const { zh, meta } = paths
+  const have = {
+    source: repositoryFileExists(source),
+    zh: repositoryFileExists(zh),
+    meta: repositoryFileExists(meta),
+  }
 
   if (isExcluded(source)) {
     if (have.zh) errors.push(`${zh}: ${source} is excluded from pairing (generated or bilingual-by-construction); this translation must not exist`)
@@ -190,10 +201,14 @@ for (const source of [...pairAnchors].sort()) {
     continue
   }
 
-  const sourceContent = readFileSync(join(root, source))
-  const zhContent = readFileSync(join(root, zh))
-  const record = parseMeta(readFileSync(join(root, meta), 'utf8'))
-  if (!record || record.size !== 2 || !record.has(basename(source)) || !record.has(basename(zh))) {
+  const sourceContent = readRepositoryFile(source)
+  const zhContent = readRepositoryFile(zh)
+  const metaContent = readRepositoryFile(meta)
+  if (sourceContent === undefined || zhContent === undefined || metaContent === undefined) {
+    throw new Error(`${source}: complete pair became unreadable`)
+  }
+  const record = parseTranslationPairingRecord(metaContent.toString('utf8'), paths)
+  if (record === undefined) {
     errors.push(`${meta}: malformed consistency record (expected exactly \`${basename(source)}: <40-hex>\` and \`${basename(zh)}: <40-hex>\`)`)
     continue
   }
@@ -201,7 +216,8 @@ for (const source of [...pairAnchors].sort()) {
   let consistent = true
   for (const [file, content] of [[source, sourceContent], [zh, zhContent]] as const) {
     const current = gitBlobHash(content)
-    if (record.get(basename(file)) !== current) {
+    const recorded = file === source ? record.sourceHash : record.zhHash
+    if (recorded !== current) {
       errors.push(`${file}: out of sync — content no longer matches the pair's last confirmed-consistent state in ${meta} (bring the other side along, then re-record with --write)`)
       consistent = false
     }
@@ -247,7 +263,7 @@ if (listMode) {
 
 if (errors.length === 0) {
   console.log(request.scope === 'pairs'
-    ? `verify-translation-pairing: ${pairAnchors.size} named pair(s) consistent; the corpus-wide check still runs in doc-sync.`
+    ? `verify-translation-pairing: ${pairAnchors.size} named ${indexMode ? 'staged ' : ''}pair(s) consistent; the corpus-wide check still runs in doc-sync.`
     : `verify-translation-pairing: ${pairAnchors.size} pair(s) checked across all in-scope documentation, all consistent.`)
   process.exit(0)
 }

From 3abe813fd36103c22aed5e3ce37cb9020cd8683c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:11:48 +0800
Subject: [PATCH 290/516] docs(i18n): document automatic pairing merges

---
 ...matic-translation-pairing-merges.i18n.yaml |  6 +++
 ...08-automatic-translation-pairing-merges.md | 41 +++++++++++++++++++
 ...automatic-translation-pairing-merges.zh.md | 41 +++++++++++++++++++
 docs/development.i18n.yaml                    |  4 +-
 docs/development.md                           | 15 ++++---
 docs/development.zh.md                        | 15 ++++---
 docs/i18n/README.i18n.yaml                    |  4 +-
 docs/i18n/README.md                           |  2 +
 docs/i18n/README.zh.md                        |  2 +
 .../request-response.expected.json            |  8 ++--
 10 files changed, 118 insertions(+), 20 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
 create mode 100644 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md

diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
new file mode 100644
index 0000000000..bbd7870d69
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.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/process/2026-08-08-automatic-translation-pairing-merges.md
+2026-08-08-automatic-translation-pairing-merges.md: a1b92c97240e2019b188b606dc079b2211a89238
+2026-08-08-automatic-translation-pairing-merges.zh.md: 5c7249dc436d24aa955d9c042c8d1bdc84655868
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
new file mode 100644
index 0000000000..a1b92c9724
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
@@ -0,0 +1,41 @@
+# Agent Note: Automatically compose translation pairing records
+
+Status: implemented
+
+English | [中文](2026-08-08-automatic-translation-pairing-merges.zh.md)
+
+## Problem
+
+A bilingual consistency record contains the two owner files' exact blob hashes. Two branches that independently update different parts of the same confirmed pair therefore conflict on both hash lines even when Git cleanly composes both Markdown owners. Selecting either side leaves stale hashes, while regenerating the record by hand repeats a deterministic operation and prevents an otherwise automatic merge.
+
+## Decision
+
+`*.i18n.yaml` uses the repository-owned `dsh-translation-pairing` merge driver. The worktree-local Git installer registers its command alongside Lefthook setup; Git configuration remains local because a tracked attribute can name a driver but cannot carry its executable command.
+
+The driver parses the ancestor, current, and other records and loads the six owner blobs named by their hashes. It independently runs Git's default three-way text merge for the English and Chinese triplets, requires both merges to be clean, verifies language switchers and the pairing structural signature, stores the two merged blobs, and writes their hashes as the canonical record. This composes confirmations already present in both parents; it never records an ordinary one-sided documentation edit.
+
+The driver fails with an ordinary unresolved sidecar when a record is malformed, an object is missing, an owner uses another merge strategy, either owner has content conflicts, or the merged pair violates structural checks. Add/delete and rename shapes remain manual because their path ownership is not the same three-record operation.
+
+`pnpm run resolve-translation-pairing-conflicts` applies the same algorithm after a merge has already stopped. Before writing any sidecar, it proves that the staged owner blob IDs and working-tree bytes equal its independent merges; then it writes and stages every safe record as one batch while leaving unrelated conflicts untouched.
+
+`pre-merge-commit` and `pre-commit` verify staged `.i18n.yaml` files against the exact index bytes of their owners. They validate driver output but do not regenerate records, so bypassing a hook cannot silently bless translation drift; the corpus-wide `doc-sync` check remains authoritative in CI.
+
+## Verification
+
+Script tests exercise clean composition through a real custom-driver Git merge, explicit recovery from an unresolved index, owner-content conflicts, record parsing, and worktree-local installation. The existing corpus verifier continues to prove that a committed record matches its two owners.
+
+## Alternatives considered
+
+**Take ours or use Git's union driver.** Either parent record names pre-merge content, while union produces duplicate or unordered hash keys. Neither represents the merged owners.
+
+**Regenerate in `post-merge` or only in a commit hook.** `post-merge` does not run after a conflicted merge and cannot affect its outcome. Commit hooks are reached only after the index has no unresolved entries, so a hook alone cannot clear the generated conflict.
+
+**Wrap every merge in a repository command.** A wrapper can resolve the conflict from the populated index, and the explicit resolver retains that recovery path, but raw Git, stack tooling, rebases, and cherry-picks would still stop before it. The merge driver is the file-level extension point shared by those operations.
+
+**Resolve on GitHub through Actions or an app.** Hosted automation could update PR branches, but it adds credentials, concurrency control, and branch mutation. Local and agent-driven merge-forward workflows already have a checkout and push authority; the repository keeps remote automation out of this mechanism.
+
+## Consequences
+
+Installed worktrees automatically remove pairing-record-only conflicts while preserving human judgment for owner conflicts and translation quality. GitHub's hosted mergeability calculation does not run the worktree-local executable, so a contributor or agent must still merge the base and push the resulting commit before the remote conflict badge clears.
+
+The installer reserves `merge.dsh-translation-pairing.*` in worktree configuration and refuses a conflicting custom value. Merge execution depends on the installed Node dependencies, like the repository's contributor hooks; missing setup fails rather than selecting stale metadata.
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
new file mode 100644
index 0000000000..5c7249dc43
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
@@ -0,0 +1,41 @@
+# Agent Note: 自动组合翻译配对记录
+
+Status: implemented
+
+[English](2026-08-08-automatic-translation-pairing-merges.md) | 中文
+
+## 问题
+
+一份双语一致性记录包含两侧 Markdown 文件的精确 blob hash。因此，当两个分支分别更新同一已确认配对的不同部分时，即使 Git 能干净合并两侧 Markdown 文件，记录中的两行 hash 仍会发生冲突。选择任一侧都会留下陈旧 hash；手工重新生成记录则会重复执行一项确定性操作，并阻止本可自动完成的合并。
+
+## 决策
+
+`*.i18n.yaml` 使用由仓库维护的 `dsh-translation-pairing` 合并驱动。worktree 本地的 Git 安装脚本在设置 Lefthook 的同时注册该驱动命令；Git 配置仍限定于当前 worktree，因为受跟踪的属性可以指定驱动，却无法携带其可执行命令。
+
+驱动会解析祖先、当前和另一侧的记录，并加载其中 hash 指向的六个 Markdown blob。它分别对英文文档的三个 blob 与中文文档的三个 blob 运行 Git 默认的三方文本合并，要求两次合并都干净完成，校验语言切换行与配对结构签名，存储两个合并后的 blob，再将其 hash 写入规范记录。这一过程组合两个父提交中已经存在的确认；它绝不会为普通的单侧文档编辑写入记录。
+
+记录格式错误、对象缺失、配对文档采用其他合并策略、任一配对文档存在内容冲突，或合并后的配对违反结构检查时，驱动会让伴随文件保持为普通的未解决冲突。新增、删除及重命名情形仍需手工处理，因为它们的路径归属关系无法由上述基于三份记录的操作处理。
+
+`pnpm run resolve-translation-pairing-conflicts` 会在合并已经停止后应用同一算法。写入任何伴随文件之前，它会先验证暂存区中配对文档的 blob ID 以及工作树中的文件字节，都与工具独立完成的合并结果一致；随后它会将所有可安全生成的记录作为一个批次写入并暂存，同时不改动无关冲突。
+
+`pre-merge-commit` 与 `pre-commit` 通过限定范围的配对检查，对照两侧文档在索引中的精确字节校验暂存的 `.i18n.yaml` 文件。这些钩子会验证驱动输出，但不会重新生成记录，因此绕过钩子也无法默默确认发生漂移的译文；CI 中全语料的 `doc-sync`（文档同步门禁）仍是权威检查。
+
+## 验证
+
+脚本测试通过一次使用真实自定义驱动的 Git 合并来覆盖无冲突组合，并覆盖从含未解决条目的索引中显式恢复、配对文档内容冲突、记录解析和 worktree 本地安装。既有的全语料校验器继续证明已提交的记录与两侧配对文档相符。
+
+## 考虑过的替代方案
+
+**选择 ours 或使用 Git 的 union 驱动。** 任一父提交的记录都指向合并前的内容，而 union 会产生重复或乱序的 hash 键。两者都无法表示合并后的配对文档。
+
+**在 `post-merge` 中或仅通过提交钩子重新生成。** 发生冲突的合并不会运行 `post-merge`，而且该钩子无法改变合并结果。只有暂存区不含未解决条目后才会触发提交钩子，因此仅用钩子无法清除生成文件冲突。
+
+**用仓库命令包装每次合并。** 包装命令可以根据已由合并填充的索引解决冲突，显式冲突解决命令也保留这条恢复路径，但直接运行 Git、stack 工具、rebase 和 cherry-pick 时仍会在此前停止。合并驱动才是这些操作共用的文件级扩展点。
+
+**通过 GitHub Actions 或应用解决。** 托管自动化可以更新 PR（Pull Request）分支，却会引入凭据、并发控制与分支修改。本地执行或由 agent（智能体）驱动的 merge-forward 工作流已经具有检出目录与推送权限，因此仓库不把远程自动化纳入该机制。
+
+## 后果
+
+完成安装的 worktree 会自动消除仅由配对记录引起的冲突，同时仍由人工处理配对文档冲突并评判翻译质量。GitHub 托管的可合并性计算不会运行 worktree 本地的可执行命令，因此仍须由贡献者或 agent 将 base 分支合入当前分支并推送结果提交，远端冲突标记才会消失。
+
+安装脚本会在 worktree 配置中预留 `merge.dsh-translation-pairing.*`，并拒绝与之冲突的自定义值。与仓库贡献者钩子一样，合并过程依赖已安装的 Node 依赖；安装未完成时，合并会失败，而不是选择陈旧元数据。
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 676c78bb90..3c57bb057c 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: a9edd80abfbd53c9fc0495b4b495fa495207ca95
-development.zh.md: 405942c26ef3600209bc14a300c94a98d4f2b9f3
+development.md: 1b0a412cd55224740a074a88734bc5663a14effc
+development.zh.md: 3c01f680dd8107fe6b3369415a979cea69cd19a0
diff --git a/docs/development.md b/docs/development.md
index a9edd80abf..1b0a412cd5 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -21,9 +21,9 @@ Install dependencies from the repo root:
 pnpm install
 ```
 
-The install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.
+The install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.
 
-If hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:
+If either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:
 
 ```sh
 node scripts/install-lefthook.mjs
@@ -98,18 +98,21 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 `DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.
 
-### Git hooks
+### Git integrations
+
+The pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files merge cleanly. It fails closed on owner conflicts or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.
 
 lefthook is configured in `lefthook.yml` as a fast local checkpoint:
 
-- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
+- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
+- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.
 - `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.
 
 The vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.
 
-The hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.
+Apart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.
 
-Contributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.
+Contributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.
 
 ### CI gates
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 405942c26e..3c01f680dd 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -21,9 +21,9 @@
 pnpm install
 ```
 
-安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。
+安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。
 
-如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：
+如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：
 
 ```sh
 node scripts/install-lefthook.mjs
@@ -98,18 +98,21 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 `DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。
 
-### Git 钩子
+### Git 集成
+
+当两种语言的文件都能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
 
 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
-- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
+- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
+- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；
 - `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
 
-这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。
+除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。
 
-贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。
+贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。
 
 ### CI 门禁
 
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index 464a3c8df0..48d27cbb41 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/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 docs/i18n/README.md
-README.md: 2bac578034441bbe786ce54c051cc622bf9275c0
-README.zh.md: b7566bf6f88e03eb06227b63011f78252b4dcd07
+README.md: 2f9d7d1112492545e4e82d8d99c3d11df383e42d
+README.zh.md: 65ac3552aa4b66cbd43e6b55b98f0e1d9491feea
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index 2bac578034..2f9d7d1112 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -16,6 +16,8 @@ This repo's documentation is read by people and agents both inside and outside t
   ```
 
   Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).
+
+  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.
 - **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.
 - **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
 
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index b7566bf6f8..65ac3552aa 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -16,6 +16,8 @@
   ```
 
   用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。
+
+  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。
 - **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
 - **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index baa648925d..b45ffe01e0 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,19 +16,19 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local lefthook hooks through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the safety and migration contract.\n\nIf hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git hooks\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nThe hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of both Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files merge cleanly. It fails closed on owner conflicts or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 lefthook 钩子。其安全与迁移契约由 [worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 钩子\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于两个 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
-        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
+        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
       },
       {
         "role": "user",

From 75570ba31e79bd5b75c1268de23e34d97d72d7a5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:26:31 +0800
Subject: [PATCH 291/516] test(i18n): deduplicate merge conflict setup

---
 scripts/translation-pairing-merge.spec.ts | 25 +++++++++++------------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
index c6a9a5bbb7..bd6d2a632b 100644
--- a/scripts/translation-pairing-merge.spec.ts
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -103,6 +103,16 @@ function createDivergedPair(fixture: Fixture): { ancestor: string; current: stri
   return { ancestor, current, other }
 }
 
+function startStoppedPairingMerge(fixture: Fixture): void {
+  createDivergedPair(fixture)
+  const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+    encoding: 'utf8',
+    env: fixture.env,
+  })
+  expect(merge.status).toBe(1)
+  expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+}
+
 function expectMergedPair(fixture: Fixture): void {
   expect(readFileSync(join(fixture.root, 'docs/guide.md'), 'utf8')).toBe(mergedSource)
   expect(readFileSync(join(fixture.root, 'docs/guide.zh.md'), 'utf8')).toBe(mergedZh)
@@ -223,13 +233,7 @@ describe('translation pairing merge composition', () => {
 
   it('resolves an already-stopped generated-only conflict from index stages', () => {
     const fixture = createFixture(false)
-    createDivergedPair(fixture)
-    const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
-      encoding: 'utf8',
-      env: fixture.env,
-    })
-    expect(merge.status).toBe(1)
-    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+    startStoppedPairingMerge(fixture)
 
     expect(resolveTranslationPairingConflicts(fixture.root)).toEqual(['docs/guide.i18n.yaml'])
 
@@ -239,12 +243,7 @@ describe('translation pairing merge composition', () => {
 
   it('refuses to confirm unstaged owner bytes after a stopped merge', () => {
     const fixture = createFixture(false)
-    createDivergedPair(fixture)
-    const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
-      encoding: 'utf8',
-      env: fixture.env,
-    })
-    expect(merge.status).toBe(1)
+    startStoppedPairingMerge(fixture)
     write(fixture.root, 'docs/guide.md', `${mergedSource}\nunstaged\n`)
 
     expect(() => resolveTranslationPairingConflicts(fixture.root)).toThrow(

From 8917ff8ef4a6f8c79d9d0f66429ab10734ca3b23 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 23:00:00 +0800
Subject: [PATCH 292/516] refactor(runtime): compose consumers over fs and
 subprocess

---
 ...06-17-filesystem-capability-seam.i18n.yaml |   4 +-
 .../2026-06-17-filesystem-capability-seam.md  |   7 +-
 ...026-06-17-filesystem-capability-seam.zh.md |  19 +-
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |   4 +-
 .../2026-07-15-lsp-capability-seam.md         |  20 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |  32 +-
 ...26-subprocess-consumer-migration.i18n.yaml |   4 +-
 ...026-07-26-subprocess-consumer-migration.md |  16 +-
 ...-07-26-subprocess-consumer-migration.zh.md |  18 +-
 .../2026-07-26-subprocess-seam.i18n.yaml      |   4 +-
 .../2026-07-26-subprocess-seam.md             |   8 +-
 .../2026-07-26-subprocess-seam.zh.md          |  18 +-
 ...rtable-execution-world-consumers.i18n.yaml |   6 +
 ...7-28-portable-execution-world-consumers.md |  48 ++
 ...8-portable-execution-world-consumers.zh.md |  48 ++
 .../feature/2026-06-15-code-mode.i18n.yaml    |   4 +-
 .../feature/2026-06-15-code-mode.md           |  28 +-
 .../feature/2026-06-15-code-mode.zh.md        |  48 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |   4 +-
 .../2026-07-16-persistent-pty-sessions.md     |  25 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  |  39 +-
 docs/config-catalog.md                        |  34 +-
 docs/cordis-catalog/events.md                 |   6 +-
 .../core-data-structures/filesystem.i18n.yaml |   4 +-
 docs/core-data-structures/filesystem.md       |   6 +-
 docs/core-data-structures/filesystem.zh.md    |   6 +-
 .../core-data-structures/subprocess.i18n.yaml |   4 +-
 docs/core-data-structures/subprocess.md       |  16 +-
 docs/core-data-structures/subprocess.zh.md    |  46 +-
 knip.json                                     |  10 +
 packages/README.i18n.yaml                     |   4 +-
 packages/README.md                            |   2 +-
 packages/README.zh.md                         |   2 +-
 .../code-runtime-worker/README.md             |   2 +-
 .../code-runtime-worker/src/runtime-host.ts   | 222 +++++++++
 .../code-runtime-worker/tsconfig.json         |   3 -
 .../code-runtime-worker/tsdown.config.ts      |  17 +-
 packages/code-runtime/code-runtime/README.md  |   4 +-
 .../tests/workspace-context.spec.ts           |  14 +
 .../cordis/tool-cordis/src/api-catalog.ts     |  40 ++
 packages/fs/README.i18n.yaml                  |   4 +-
 packages/fs/README.md                         |  21 +-
 packages/fs/README.zh.md                      |  25 +-
 packages/fs/fs-local/README.i18n.yaml         |   4 +-
 packages/fs/fs-local/README.md                |   7 +-
 packages/fs/fs-local/README.zh.md             |  19 +-
 packages/fs/fs-local/src/fsio.ts              |  73 ++-
 packages/fs/fs-local/src/index.ts             |  21 +-
 packages/fs/fs-local/tests/filesystem.spec.ts |  24 +
 packages/fs/fs-local/tests/fsio.spec.ts       |  63 ++-
 packages/fs/fs/README.i18n.yaml               |   4 +-
 packages/fs/fs/README.md                      |  27 +-
 packages/fs/fs/README.zh.md                   |  45 +-
 packages/fs/fs/src/index.ts                   |  52 +-
 packages/fs/fs/tests/service.spec.ts          |  13 +-
 packages/fs/tool-fs/tests/tools.spec.ts       |  10 +
 packages/lsp/README.i18n.yaml                 |   4 +-
 packages/lsp/README.md                        |  10 +-
 packages/lsp/README.zh.md                     |  12 +-
 packages/lsp/lsp-local/README.i18n.yaml       |   4 +-
 packages/lsp/lsp-local/README.md              |  18 +-
 packages/lsp/lsp-local/README.zh.md           |  26 +-
 packages/lsp/lsp-local/package.json           |   3 +
 packages/lsp/lsp-local/src/connection.ts      |   7 +-
 packages/lsp/lsp-local/src/host.ts            | 182 +++----
 packages/lsp/lsp-local/src/index.ts           | 115 ++---
 packages/lsp/lsp-local/src/instance.ts        |  13 +-
 packages/lsp/lsp-local/tests/built-lib.e2e.ts |   5 +-
 packages/lsp/lsp-local/tests/host.spec.ts     |  68 ++-
 packages/lsp/lsp-local/tests/instance.spec.ts |  17 +-
 .../lsp/lsp-local/tests/lifecycle.spec.ts     |   4 +
 packages/lsp/lsp-local/tests/provider.spec.ts |  13 +
 .../lsp-local/tests/typescript-server.e2e.ts  |   2 +
 packages/lsp/lsp-local/tsconfig.json          |   3 +
 packages/lsp/tool-lsp/package.json            |   2 +
 .../lsp/tool-lsp/tests/integration.spec.ts    |   2 +
 packages/pty/README.i18n.yaml                 |   4 +-
 packages/pty/README.md                        |  11 +-
 packages/pty/README.zh.md                     |  11 +-
 packages/pty/pty-local/README.i18n.yaml       |   4 +-
 packages/pty/pty-local/README.md              |  20 +-
 packages/pty/pty-local/README.zh.md           |  24 +-
 packages/pty/pty-local/package.json           |   8 +-
 packages/pty/pty-local/src/index.ts           |  69 ++-
 packages/pty/pty-local/src/session.ts         | 341 ++++++-------
 packages/pty/pty-local/tests/index.spec.ts    | 173 +++----
 packages/pty/pty-local/tests/local.spec.ts    |   2 +
 packages/pty/pty-local/tests/session.spec.ts  | 471 +++++++++++-------
 packages/pty/tool-pty/package.json            |   1 +
 .../tool-pty/tests/loader-composition.spec.ts |   3 +
 .../skill-local/tests/skill-local.spec.ts     |  14 +
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.md                 |  10 +-
 packages/subprocess/README.zh.md              |  12 +-
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |  14 +-
 .../subprocess/subprocess-local/README.zh.md  |  22 +-
 .../subprocess/subprocess-local/package.json  |   7 +
 .../scripts/ensure-spawn-helper.mjs           |   0
 .../subprocess/subprocess-local/src/index.ts  | 104 +++-
 .../src/process-inspector.ts                  |  10 +-
 .../subprocess-local/src/terminal.ts          | 226 +++++++++
 .../subprocess-local/tests/local.spec.ts      | 134 ++++-
 .../tests/process-inspector.spec.ts           |   6 +-
 .../subprocess-local/tests/terminal.spec.ts   | 275 ++++++++++
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.md      |  10 +-
 packages/subprocess/subprocess/README.zh.md   |  22 +-
 packages/subprocess/subprocess/src/index.ts   |  52 +-
 packages/subprocess/subprocess/src/types.ts   |  68 +++
 .../subprocess/tests/service.spec.ts          |  29 +-
 scripts/check-workspace-constraints.ts        |   1 +
 scripts/gen-cordis-catalog.ts                 |   3 +
 scripts/run-gates.ts                          |   7 +-
 .../verify-package-readme-model-experience.ts |   1 +
 tsconfig.host.json                            |   1 +
 116 files changed, 2828 insertions(+), 1122 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
 create mode 100644 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
 create mode 100644 packages/code-runtime/code-runtime-worker/src/runtime-host.ts
 rename packages/{pty/pty-local => subprocess/subprocess-local}/scripts/ensure-spawn-helper.mjs (100%)
 rename packages/{pty/pty-local => subprocess/subprocess-local}/src/process-inspector.ts (96%)
 create mode 100644 packages/subprocess/subprocess-local/src/terminal.ts
 rename packages/{pty/pty-local => subprocess/subprocess-local}/tests/process-inspector.spec.ts (98%)
 create mode 100644 packages/subprocess/subprocess-local/tests/terminal.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index efdb14ea94..dc9b924f54 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.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 .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
-2026-06-17-filesystem-capability-seam.md: fee0161e5e8397ac1d1c0e2850efad840c65d971
-2026-06-17-filesystem-capability-seam.zh.md: 46e3ad22c530319d0d1b6ba23a8aba8ffc2fdb8c
+2026-06-17-filesystem-capability-seam.md: 2fb360e5ad3c972f4a8de50c602a79af158dfc22
+2026-06-17-filesystem-capability-seam.zh.md: 1f70113b1583d890047ee4a17161f76b6390d8e8
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
index fee0161e5e..2fb360e5ad 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
@@ -62,8 +62,9 @@ The root `tool-fs` plugin registers the full filesystem tool suite (`read`, `wri
 The interface covers these semantic operations:
 
 - Resolve a model/plugin-supplied path into a backend-defined target.
+- Convert a resolved target to the canonical process path or `file:` URI for the same execution world, and test containment without parsing its opaque key.
 - Stat target metadata without reading file contents.
-- Read a bounded UTF-8 text page from a target.
+- Read complete or streamed UTF-8 text, including one stable-handle byte-bounded whole-file operation.
 - Create or replace a UTF-8 text file.
 - Edit an existing UTF-8 text file by literal replacement.
 
@@ -83,9 +84,11 @@ Resolved targets must expose at least three concepts:
 - An opaque `targetKey`, used for stale guards and file-state lookup. The local backend might use a realpath-like key; a remote backend might use a workspace URI or file id. Consumers must not parse or assume this is a local absolute path.
 - A `displayPath`, used for model/UI-facing output. It may be a local absolute path, workspace-relative path, or remote URI depending on the backend.
 
+`targetKey` remains opaque even when another capability shares the provider's execution world. Such consumers ask the provider for `processPath(target)`, `fileUrl(target)`, or `contains(parent, child)`; the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) owns why these facts sit on the filesystem seam.
+
 Read and mutation results must include an opaque file `version`. The local backend derives its token from bigint stat metadata (`dev`, `ino`, `size`, `mtimeNs`, and `ctimeNs`) so same-size rewrites and inode replacement invalidate consumers reliably; a remote backend can use a revision id or hash-like token. The `dsh-fs-policy` plugin records versions for stale checks; consumers may display related metadata but must not interpret the version token.
 
-The provider hands back decoded text: `readText` returns a whole regular text file, `streamText` streams the same text semantics for large files. Both own regular-file checks, bounded line/output handling is NOT theirs — line windowing, numbered-line rendering, and total-line accounting live in the executor (`dsh-tool-fs`), which reads through `ctx.fs` and renders the model-facing window. The provider owns UTF-8 decoding and binary/NUL rejection; it does not know about line windows or views.
+The provider hands back decoded text: `readText` returns a whole regular text file, `streamText` streams the same text semantics for large files, and `readTextBounded` holds one backend-owned stable handle while rejecting a complete file above its byte ceiling. Line windowing, numbered-line rendering, and total-line accounting live in the executor (`dsh-tool-fs`). The provider owns regular-file checks, UTF-8 decoding, binary/NUL rejection, and the bounded read's replacement/growth race; it does not know about line windows or views.
 
 Observed-state recording is not on `ctx.fs`: after a successful read the executor emits `fs/observed`, and the `dsh-fs-policy` plugin records `{ version }` for the deriving owner. There is no `full`/`partial` view — a read at any window records the version, and freshness (not view completeness) authorizes a later write/edit.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
index 46e3ad22c5..1f70113b15 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -16,7 +16,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 如果没有 `ctx.fs` 接口，将本地文件系统访问替换为沙箱或远程后端时，即使面向模型的契约应当保持稳定，工具 schema、演示和提示词引导也会被迫变动。这还使权限/沙箱边界更难推理：一个 `cwd` 选项看起来像沙箱，但除非有显式的后端或 `tools/execute` 策略强制隔离，否则它只是一个基础路径。
 
-我们需要文件系统工具在成为公开包接口之前，以与 bash 相同的能力 seam 形态落地。
+我们需要文件系统工具在成为公开包（package）接口之前，以与 bash 相同的能力 seam 形态落地。
 
 ## 决策
 
@@ -51,7 +51,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 `@deepseek-ai/dsh-fs-local` 依赖 `@deepseek-ai/dsh-fs` 和 `cordis`。它继承 `FileSystem`，将自身注册为 `ctx.fs`，拥有本地后端配置（如基目录），并包含所有直接的 `node:fs` / `node:path` 访问。它不持有观测状态存储——新鲜度是后端铸造、策略插件记录的版本令牌。
 
-`@deepseek-ai/dsh-tool-fs` 依赖 `@deepseek-ai/dsh-fs`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-system-prompt` 和 `cordis`。它注册面向模型的工具和提示词段落。它禁止导入 `node:fs`、`node:path` 或 `@deepseek-ai/dsh-fs-local`；文件系统执行始终通过 `ctx.fs`。如果实现需要具体的 agent（智能体）或会话辅助类型，这些依赖属于 `tool-fs`；它们禁止回漏到 `dsh-fs` 中。
+`@deepseek-ai/dsh-tool-fs` 依赖 `@deepseek-ai/dsh-fs`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-system-prompt` 和 `cordis`。它注册面向模型的工具和提示词段落。它禁止导入 `node:fs`、`node:path` 或 `@deepseek-ai/dsh-fs-local`；文件系统执行始终通过 `ctx.fs`。如果实现需要具体的 agent 或会话辅助类型，这些依赖属于 `tool-fs`；它们禁止回漏到 `dsh-fs` 中。
 
 根 `tool-fs` 插件通过组合各工具的注册辅助函数来注册完整的文件系统工具套件（`read`、`write` 和 `edit`）。它注入 `fs`，从不导入实现包。
 
@@ -62,8 +62,9 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 该接口涵盖以下语义操作：
 
 - 将模型/插件提供的路径解析为后端定义的目标。
+- 将解析后的目标转换为同一执行环境的规范进程路径或 `file:` URI，并在不解析其不透明键的情况下检查包含关系。
 - 获取目标元数据而不读取文件内容。
-- 从目标读取有界的 UTF-8 文本页。
+- 读取完整或流式 UTF-8 文本，其中包括一项持有稳定句柄、以字节为上限的全文件读取操作。
 - 创建或替换一个 UTF-8 文本文件。
 - 通过字面替换编辑一个已有的 UTF-8 文本文件。
 
@@ -83,13 +84,15 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 - 不透明的 `targetKey`，用于陈旧守护和文件状态查找。本地后端可能使用类似 realpath 的键；远程后端可能使用工作区 URI 或文件 id。消费方禁止解析或假设它是本地绝对路径。
 - `displayPath`，用于面向模型/UI 的输出。根据后端不同，它可能是本地绝对路径、工作区相对路径或远程 URI。
 
-读取和变更结果必须包含不透明的文件 `version`。本地后端从 bigint stat 元数据（`dev`、`ino`、`size`、`mtimeNs` 和 `ctimeNs`）派生令牌，因此同大小重写和 inode 替换都会可靠地使消费方持有的版本失效；远程后端可以使用 revision id 或类似 hash 的令牌。`dsh-fs-policy` 插件记录版本用于陈旧检查；消费方可以展示相关元数据但禁止解释版本令牌。
+即使另一项能力共享提供方的执行环境，`targetKey` 仍保持不透明。这类消费方通过提供方的 `processPath(target)`、`fileUrl(target)` 或 `contains(parent, child)` 获取所需事实；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)说明这些事实为何属于文件系统 seam。
 
-提供方返回已解码的文本：`readText` 返回整个常规文本文件，`streamText` 为大文件流式输出相同的文本语义。两者负责常规文件检查；有界的行/输出处理不是它们的职责——行窗口化、带行号渲染和总行数统计位于执行器（`dsh-tool-fs`）中，执行器通过 `ctx.fs` 读取并渲染面向模型的窗口。提供方负责 UTF-8 解码和二进制/NUL 拒绝；它不知道行窗口或视图。
+读取和变更结果必须包含不透明的文件 `version`。本地后端从 bigint stat 元数据（`dev`、`ino`、`size`、`mtimeNs` 和 `ctimeNs`）派生令牌，因此同大小重写和 inode 替换都会可靠地使消费方失效；远程后端可以使用 revision id 或类似 hash 的令牌。`dsh-fs-policy` 插件记录版本用于陈旧检查；消费方可以展示相关元数据但禁止解释版本令牌。
+
+提供方返回已解码的文本：`readText` 返回整个常规文本文件，`streamText` 为大文件流式传输相同的文本语义，`readTextBounded` 则持有一个归后端所有的稳定句柄，并在完整文件超过字节上限时拒绝。行窗口化、带行号渲染和总行数统计位于执行器（`dsh-tool-fs`）中。提供方负责普通文件检查、UTF-8 解码、二进制/NUL 拒绝，以及有界读取期间的路径替换／增长竞态；它不知道行窗口或视图。
 
 观测状态记录不在 `ctx.fs` 上：成功读取后，执行器发出 `fs/observed`，`dsh-fs-policy` 插件为推导出的 owner 记录 `{ version }`。没有 `full`/`partial` 视图——任何窗口的读取都记录版本，新鲜度（而非视图完整性）授权后续的写入/编辑。
 
-全文件写入创建或替换 UTF-8 文本文件。后端在支持且有文档说明时可以创建父目录。已有的非常规目标被拒绝。`writeText` 接受一个可选期望：`createIfAbsent` 创建缺失的目标并拒绝已存在的（报 `FS_NOT_OBSERVED`，这是策略处理未观测 owner 时采用的分支）；`replaceIfVersion` 仅在目标处于观测版本时替换，否则报 `FS_STALE_VERSION`；省略期望则为无条件的裸提供方创建或覆盖。策略插件根据 owner 的观测状态选择提供哪个期望。
+全文件写入创建或替换 UTF-8 文本文件。后端在支持且有文档说明时可以创建父目录。已有的非常规目标被拒绝。`writeText` 接受一个可选期望：`createIfAbsent` 创建缺失的目标并拒绝已存在的（报 `FS_NOT_OBSERVED`，这是策略为未观测 owner 使用的路径）；`replaceIfVersion` 仅在目标处于观测版本时替换，否则报 `FS_STALE_VERSION`；省略期望则为无条件的裸提供方创建或覆盖。策略插件根据 owner 的观测状态选择提供哪个期望。
 
 字面编辑是提供方原语（`editText`），而非在 `tool-fs` 中由读取加写入组合而成。字面匹配、重复匹配拒绝、CRLF 保留、二进制拒绝、可选的陈旧版本检查和原子读-改-写必须一起留在后端的变更临界区内。`editText` 接受相同的可选版本期望；陈旧检查在字面匹配之前运行，因此基于旧读取的编辑会报 `FS_STALE_VERSION`。远程后端可以将编辑实现为原生的 compare-and-edit 操作；消费方不强制本地风格的组合。
 
@@ -124,11 +127,11 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 ## 测试
 
-测试遵循包边界，而不仅是用户可见的工具：`dsh-fs` 中的服务 seam；`dsh-fs-local` 中通过 `ctx.fs` 接口测试的真实文件系统行为（解析、符号链接、流式输出、二进制/UTF-8 拒绝、无条件和版本守护的写入、字面编辑语义、行尾保留、结构化 `FsError` 错误码）；`dsh-tool-fs` 中基于真实本地提供方的消费方接口（只 mock 模型/时钟，从不 mock 协作者）；以及通过 `ctx.tools.execute()` 在有和没有 `dsh-fs-policy` 的情况下进行集成测试，通过从磁盘回读文件来验证世界状态，既不信任规范值，也不信任渲染内容。观测状态/owner 推导策略在 `dsh-fs-policy` 中测试，不在此处。
+测试遵循包边界，而不仅是用户可见的工具：`dsh-fs` 中的服务 seam；`dsh-fs-local` 中通过 `ctx.fs` 接口测试的真实文件系统行为（解析、符号链接、流式传输、二进制/UTF-8 拒绝、无条件和版本守护的写入、字面编辑语义、行尾保留、结构化 `FsError` 错误码）；`dsh-tool-fs` 中基于真实本地提供方的消费方接口（只 mock 模型/时钟，从不 mock 协作者）；以及通过 `ctx.tools.execute()` 在有和没有 `dsh-fs-policy` 的情况下进行集成测试，通过从磁盘回读文件来验证世界状态，既不信任规范值，也不信任渲染内容。观测状态/owner 推导策略在 `dsh-fs-policy` 中测试，不在此处。
 
 本仓库曾踩过的防御性模式类别被直接固定：
 
-- **原子写入临时文件安全。** 写入/编辑通过目标旁边一个私有随机 `0700` 目录中独占且仅所有者可访问（`'wx'`、`0o600`）的临时文件暂存，失败时清理，最后原子 rename——与 bash spill 文件规则一致，因为可预测的全局可读临时路径会招致符号链接竞争和信息泄露。测试断言权限，并断言已存在的临时路径不会被覆盖；此原语是 seam 的常设要求。
+- **原子写入临时文件安全。** 写入/编辑通过目标旁边一个私有随机 `0700` 目录中的独占 owner-only（`'wx'`、`0o600`）临时文件暂存，失败时清理，最后原子 rename——与 bash 溢出文件规则一致，因为可预测的 world-readable 临时路径招致符号链接竞争和信息泄露。测试断言权限，并断言已存在的临时路径不会被覆盖；此原语是 seam 的常设要求。
 - **通过符号链接的 `targetKey` 同一性。** 两个输入路径解析到同一 realpath 时共享一个观测状态条目：通过路径 A 的 `read` 满足通过符号链接路径 B 的 `edit` 的读后编辑守护，通过一个路径的陈旧写入可通过另一个路径检测到。
 - **并发/陈旧竞争。** 对同一目标的两个并发写入/编辑操作确定性地收敛——一个成功，另一个被 `FS_STALE_VERSION` 拒绝——成功的编辑刷新记录状态，使同一 owner 的下一次编辑可以继续。
 - **HMR（热模块替换）安全与 dispose（资源释放）。** dispose 后端的 fiber 会撤回 `ctx.fs` 提供方；后续的提供方以无继承状态启动。
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index 11073946ea..afb9251d33 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: d96b3a9c5139c1455a51f4fff793293d7b5a11c0
-2026-07-15-lsp-capability-seam.zh.md: 256b293f213acb06588f3ef6c655242b1c8fd5b9
+2026-07-15-lsp-capability-seam.md: a9dab45ebf034f6d5218b25a0868a7e86803719b
+2026-07-15-lsp-capability-seam.zh.md: b411a2456ea2a3838e56422f58954473da51ae23
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index d96b3a9c51..a9dab45ebf 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -79,7 +79,7 @@ interface LspService {
 
 Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `findReferences` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`; navigation results carry the provider's resolved workspace root so consumers relativize file URIs in the same canonical namespace. The seam exposes no protocol types, process or document controls, or generic request escape hatch.
 
-`dsh-lsp-local` owns host files, server configuration, JSON-RPC, process and transient-document state, and protocol translation; it depends on `dsh-lsp` and Node APIs, not `dsh-fs`. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider.
+`dsh-lsp-local` owns server configuration, JSON-RPC, process and transient-document state, and protocol translation. It reads through `ctx.fs` and launches through `ctx.subprocess`, depending on their interface packages rather than concrete providers; the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) owns that pairing. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider.
 
 ## Model-facing contract
 
@@ -112,26 +112,26 @@ Provider disposal occurs outside tool execution, so `dsh-lsp-local` keeps `shutd
 
 ## Workspace, filesystem, and document synchronization
 
-`dsh-lsp-local` canonicalizes and reads through Node APIs in the subprocess's host namespace. It rejects missing, non-regular, non-UTF-8, oversized, or canonical out-of-workspace sources and keeps one `O_NOFOLLOW | O_NONBLOCK` handle through validation and reading, so a FIFO with no writer cannot block before the regular-file check. It observes caller cancellation around each filesystem operation. It does not consume `ctx.fs` or emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
+`dsh-lsp-local` canonicalizes and reads through `ctx.fs` in the language server's execution world. It requires the workspace target to be a directory, rejects out-of-workspace sources through provider-owned containment, and uses `readTextBounded` so regular-file validation, UTF-8 decoding, the byte ceiling, and path replacement/growth safety stay one filesystem operation. It observes caller cancellation around each provider operation. It does not emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
 
 The `read` tool is unsuitable source because its output is windowed, numbered, transcript-visible, and observed. Reading in `tool-lsp` would also assign provider-specific synchronization to the consumer and preclude non-local providers.
 
 The local provider uses a compatibility-first transient-open sequence for every query. It accepts legacy `textDocumentSync` `Full` or `Incremental`, or options with `openClose: true`; omitted, `None`, or explicitly incompatible synchronization fails as unsupported before `didOpen`.
 
-1. Canonicalize and validate the host path, then read the current source with Node filesystem APIs.
+1. Resolve and contain the source through `ctx.fs`, then read its current bounded text through the same provider.
 2. Send `textDocument/didOpen` with version `1`, full text, and the configured language id. Its write remains abortable; failure or cancellation invalidates the instance and awaits bounded process termination before the pool can reuse it.
 3. Send the requested `textDocument/definition`, `textDocument/references`, `textDocument/implementation`, or `textDocument/hover` request.
 4. If `didOpen` succeeded, attempt `textDocument/didClose` in `finally` after the request settles or aborts. A close-write failure does not replace the settled result or error, but invalidates the instance and awaits bounded process termination.
 
 Documents close after each call, so the first version needs no `didChange`, `didSave`, content cache, mutation listener, or document LRU. One abortable per-workspace provider queue serializes source-read/open/query/close lifecycles, so a waiting query reads current bytes only when its turn starts; the instance also keeps protocol lifecycles serialized. Distinct workspaces may run in parallel. The server's workspace index remains responsible for closed files reached from the source.
 
-The canonical workspace `realpath` must be a directory and supplies process cwd, `rootUri`, the sole `workspaceFolders` entry, and pool identity; symlink aliases therefore share an instance. Result locations may be external, but an external path cannot become a query source. Remote, virtual, or independently sandboxed filesystems require another provider.
+The canonical workspace target must be a directory. Its target key supplies pool identity, its process path supplies cwd, and its provider-owned `file:` URI supplies `rootUri` and the sole `workspaceFolders` entry; aliases share an instance when the filesystem provider resolves them to one key. Result locations may be external, but an external path cannot become a query source. A filesystem that cannot share paths with the mounted subprocess provider is a composition error, not a reason for another LSP package.
 
 ## Local server lifecycle and protocol behavior
 
-`dsh-lsp-local` lazily single-flights one server per `(provider id, canonical workspace realpath)`. At load it resolves the executable after credential scrubbing and environment overrides, failing before registration if unavailable; server process launch stays lazy (first query spawns it) and uses no shell. `maxMessageBytes` defaults to `16_000_000`, `maxStderrBytes` to `1_000_000`, and `maxDocumentBytes` to `4_000_000`. A crash fails the active query without replay; a later query may replace the process. Each query starts at most one process, so the MVP has no cross-request restart counter.
+`dsh-lsp-local` lazily single-flights one server per `(provider id, canonical workspace target)`. At load it calls `ctx.subprocess.resolveExecutable()` with the configured environment, failing before registration if unavailable; first query launches through raw protocol pipes with no shell and a bounded collected stderr tail. `maxMessageBytes` defaults to `16_000_000`, `maxStderrBytes` to `1_000_000`, and `maxDocumentBytes` to `4_000_000`. A crash fails the active query without replay; a later query may replace the process. Each query starts at most one process, so the MVP has no cross-request restart counter.
 
-Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: { workspaceFolders: true, configuration: true }`, `textDocument.hover.contentFormat: ['markdown', 'plaintext']`, and `linkSupport: true` for definition and implementation, with no dynamic registration. Returned operation and synchronization capabilities are authoritative. An omitted server `positionEncoding` defaults to `utf-16`; any other value is a protocol error. Configuration may supply initialization options and `workspace/configuration` responses, but the client rejects `workspace/applyEdit` and never executes commands or edits.
+Initialization uses `processId: null` because the client and server may inhabit different process namespaces. It advertises `general.positionEncodings: ['utf-16']`, `workspace: { workspaceFolders: true, configuration: true }`, `textDocument.hover.contentFormat: ['markdown', 'plaintext']`, and `linkSupport: true` for definition and implementation, with no dynamic registration. Returned operation and synchronization capabilities are authoritative. An omitted server `positionEncoding` defaults to `utf-16`; any other value is a protocol error. Configuration may supply initialization options and `workspace/configuration` responses, but the client rejects `workspace/applyEdit` and never executes commands or edits.
 
 Navigation maps `Location` directly and `LocationLink` from `targetUri` plus `targetSelectionRange`. Positions must be nonnegative integers. Hover normalization accepts only valid `MarkupContent` and `MarkedString` shapes, preserves string values, renders language-tagged values as fenced code, and joins arrays with one blank line. The model-facing tool applies `maxResultChars` after rendering.
 
@@ -143,7 +143,7 @@ Symbols are deferred because they need different schemas and overlap read/search
 
 Diagnostics need separate freshness, accumulation, and transcript rules. Mutations such as rename, code actions, and formatting require separate tools with preview, permission, and write-policy integration.
 
-The local provider trusts its configured server and claims no sandbox confinement. Supporting untrusted binaries requires a later process/filesystem contract for workspace reads plus private cache and temporary writes; restricted, remote, or virtual workspaces require another provider.
+The provider trusts its configured server. Its filesystem visibility and process confinement are exactly those of the mounted execution world; LSP adds no independent sandbox policy.
 
 ## Alternatives considered
 
@@ -157,7 +157,7 @@ The local provider trusts its configured server and claims no sandbox confinemen
 
 **Wrap the signal in a per-seam execution-context object.** Web passes a bare `AbortSignal`; wrapping this single field would add unexplained asymmetry. `query()` gains a context object only when another field requires it.
 
-**Read through `ctx.fs` or the `read` tool.** This could mix the document with a server index from another filesystem namespace; tool output is also windowed, numbered, and observed. The host-local provider reads unobserved full text beside its subprocess.
+**Read through the model-facing `read` tool.** Rejected because tool output is windowed, numbered, transcript-visible, and observed. The provider reads bounded full text directly through the same `ctx.fs` execution world used by its subprocess.
 
 **Keep documents open.** Mirroring edits requires version ownership, all-path `didChange`, HMR recovery, eviction, and stale-state rules. Transient opens avoid that MVP state machine.
 
@@ -180,7 +180,7 @@ The local provider trusts its configured server and claims no sandbox confinemen
 - Synchronization tests pin UTF-16 negotiation and conversion, supported and rejected `textDocumentSync` forms, blocked and failed open writes, balanced transient open/close, close-write failure, and malformed-response rejection.
 - Timeout tests pin one `TOOL_TIMEOUT` budget, unclassified upstream cancellation, no hidden seam deadline, and bounded awaited teardown.
 - Lifecycle tests pin startup single-flight, complete-lifecycle serialization with fresh queued source reads, cross-workspace parallelism, abortable queues, crash replacement without replay, failed-stdin teardown, and quiescent disposal.
-- Host-filesystem tests pin session-cwd requirements, relative and absolute source containment through symlinks, document validation, file/non-file URI rendering, unformatted source, and no `fs/observed` event.
+- Filesystem-host tests pin session-cwd requirements, provider-owned containment and URI rendering, bounded document reads, unformatted source, and no `fs/observed` event.
 - A keyless pinned TypeScript real-server e2e exercises all four operations; runnable configuration uses the same explicit provider mapping.
 - Snapshots cover model-visible schema, prompt, results, and omissions; a built-artifact smoke test covers framing and cleanup.
 - Package and architecture docs cover configuration, security boundaries, and search/read guidance; the new `packages/lsp/` group is added to the AGENTS.md repository-layout block, the packages/README.md group table, and architecture.md in the same change.
@@ -195,4 +195,4 @@ Extension ownership is exclusive within one runtime. Two providers cannot both c
 
 UTF-16 cursor columns are exact for the protocol but difficult for a model to count around non-BMP characters. Invalid or off-symbol positions may produce empty results, so error text and prompt examples must explain the coordinate convention without encouraging broad LSP use.
 
-Direct Node access aligns the query snapshot with the server index but bypasses `ctx.fs` and its policy. Canonical containment rejects source files outside the workspace; a trusted server may still read the workspace and use caches. The first implementation therefore requires trusted host-local deployment and provides no sandbox guarantee.
+The paired filesystem/subprocess providers align the query snapshot with the server index but do not make a trusted language server safe. Canonical containment rejects query sources outside the workspace; the server itself receives the execution world's configured authority and may read other paths or use caches.
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index 256b293f21..b411a2456e 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: LSP 能力 seam 与面向模型的查询工具
+# Agent Note: LSP 能力服务边界与面向模型的查询工具
 
 Status: implemented
 
@@ -14,7 +14,7 @@ harness 已具备文本搜索与文件读取能力，但二者都无法识别程
 
 ## 决策
 
-将 LSP 建成由三个包组成的能力 seam，其中包含一个只读模型工具和一个通用本地提供方实现：
+将 LSP 建成由三个包（package）组成的能力服务边界，其中包含一个只读模型工具和一个通用本地提供方实现：
 
 1. `packages/lsp/lsp` 下的 `@deepseek-ai/dsh-lsp` 负责 `ctx.lsp`、提供方注册与选择、标准化请求与结果、执行控制，以及结构化 LSP 错误。
 2. `packages/lsp/lsp-local` 下的 `@deepseek-ai/dsh-lsp-local` 将配置的 stdio 语言服务器适配到该服务边界。一个插件实例接收具名服务器表，并为每组命令及扩展名到语言 id 的映射注册一个隔离的提供方。
@@ -79,7 +79,7 @@ interface LspService {
 
 映射键规范化为带前导点的小写扩展名，并按 `filePath` 的最后一个扩展名选择；语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`findReferences` 始终包含声明：提供方在内部执行该约束，本地映射设置 `context.includeDeclaration: true`，调用方不能配置。封闭结果联合将导航统一为位置，将 `hover` 统一为内容或 `null`；导航结果携带提供方解析后的工作区根目录，使消费方依据同一规范化根目录相对化文件 URI。服务边界不公开协议类型、进程或文档控制，也不提供通用请求逃生口。
 
-`dsh-lsp-local` 负责主机文件、服务器配置、JSON-RPC、进程与临时文档状态和协议转换；它依赖 `dsh-lsp` 与 Node API，不依赖 `dsh-fs`。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
+`dsh-lsp-local` 负责服务器配置、JSON-RPC、进程与临时文档状态和协议转换。它通过 `ctx.fs` 读取，通过 `ctx.subprocess` 启动，只依赖二者的接口包而非具体提供方；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)负责定义这种配对。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
 
 ## 面向模型的契约
 
@@ -98,9 +98,9 @@ interface LspToolInput {
 
 工具必须从会话 `header.cwd` 取得 `workspaceRoot`，没有后备值；缺失时在查询或启动前以 `LSP_WORKSPACE_REQUIRED` 失败。本地提供方基于根目录解析相对路径并直接接受绝对路径；两种路径都会进行规范化，如果目标位于规范工作区外，则在启动前拒绝。
 
-位置按文件稳定分组并渲染为 `path:line:character`。Node `fileURLToPath()` 可接受的 `file:` URI 在工作区内转换为相对路径，在工作区外转换为绝对路径；其他 URI 保持原样。`maxLocations` 默认值为 `100`，并报告省略的条目；`maxResultChars` 默认值为 `16_000`，并将每个完整渲染结果（包括截断元数据）限制在该字符数内。空位置与 `null` hover 是成功的无结果响应；服务器载荷缺失或格式错误时，以结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
+位置按文件稳定分组并渲染为 `path:line:character`。Node `fileURLToPath()` 可接受的 `file:` URI 在工作区内转换为相对路径，在工作区外转换为绝对路径；其他 URI 保持原样。`maxLocations` 默认值为 `100`，并报告省略的条目；`maxResultChars` 默认值为 `16_000`，并限制每个完整渲染结果，其中包括截断元数据。空位置与 `null` hover 是成功的无结果响应；服务器载荷缺失或格式错误时，以结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
 
-与传输方式无关的展示器使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_path, line }] }`，`title` 由参数推导并标明操作与光标。由于 `FileLocation` 没有 character，跟随位置聚焦输入行，标题保留完整光标；展示器仍为纯函数。
+与传输方式无关的展示器使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_path, line }] }`，`title` 由参数推导并标明操作与光标。由于 `FileLocation` 没有 character，跟随位置聚焦输入行，标题保留完整光标；展示保持纯函数。
 
 ## 超时归属
 
@@ -112,26 +112,26 @@ interface LspToolInput {
 
 ## 工作区、文件系统与文档同步
 
-`dsh-lsp-local` 通过 Node API 在子进程所在的主机命名空间中规范化并读取文件。它拒绝缺失、非普通、非 UTF-8、超大或规范路径越出工作区的源文件，并在校验与读取期间保持同一个 `O_NOFOLLOW | O_NONBLOCK` 句柄，因此没有写入方的 FIFO 不会在普通文件校验前造成阻塞。它在每项文件系统操作前后检查调用方是否取消。它不使用 `ctx.fs` 或发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
+`dsh-lsp-local` 在语言服务器的执行环境中通过 `ctx.fs` 规范化并读取文件。它要求工作区目标是目录，使用提供方自有的 containment 拒绝工作区外的源文件，并通过 `readTextBounded` 把普通文件校验、UTF-8 解码、字节上限和路径替换／增长安全性保留在同一项文件系统操作中。它在每项提供方操作前后检查调用方是否取消。它不发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
 
 `read` 工具的输出带窗口与行号，进入 transcript（文本记录）且已被观察，不适合作为源文件。在 `tool-lsp` 内读取还会把提供方专用同步职责交给消费方，并排除非本地提供方。
 
 本地提供方对每次查询都采用兼容优先的临时打开流程。它接受旧式 `textDocumentSync` 的 `Full` 或 `Incremental`，也接受设置了 `openClose: true` 的选项；同步能力缺失、为 `None` 或明确不兼容时，在 `didOpen` 前以不支持错误失败。
 
-1. 规范化并校验主机路径，再使用 Node 文件系统 API 读取当前源文件。
+1. 通过 `ctx.fs` 解析源文件并检查其位于工作区内，再通过同一提供方对当前文本进行有界读取。
 2. 发送 `textDocument/didOpen`，其中包含版本 `1`、完整文本和配置的语言 id。该写入仍可取消；写入失败或遭取消会使实例失效，并等待有界进程终止完成，池才能复用它。
 3. 发送所请求的 `textDocument/definition`、`textDocument/references`、`textDocument/implementation` 或 `textDocument/hover` 请求。
 4. 如果 `didOpen` 成功，则在请求完成或取消后于 `finally` 中尝试发送 `textDocument/didClose`。关闭写入失败不会覆盖已经确定的结果或错误，但会使实例失效，并等待有界进程终止完成。
 
 每次调用后都关闭文档，因此第一版不需要 `didChange`、`didSave`、内容缓存、变更监听器或文档 LRU。每个工作区的提供方队列可取消，并串行执行源文件读取、打开、查询和关闭的完整生命周期，因此等待中的查询只在轮到它时才读取当前字节；实例也会串行执行协议生命周期。不同工作区可以并行。服务器工作区索引仍负责从源文件跳转到的已关闭文件。
 
-规范工作区 `realpath` 必须是目录，并用于进程 cwd、`rootUri`、唯一的 `workspaceFolders` 条目和进程池 identity；符号链接别名因此共享实例。结果位置可以在工作区外，但外部路径不能成为查询源。远程、虚拟或独立沙箱化文件系统需要另一种提供方。
+规范工作区目标必须是目录。其目标键提供进程池 identity，进程路径提供 cwd，归提供方所有的 `file:` URI 则提供 `rootUri` 和唯一的 `workspaceFolders` 条目；文件系统提供方将别名解析为同一键时，它们共享实例。结果位置可以在工作区外，但外部路径不能成为查询源。无法与挂载的子进程提供方共享路径的文件系统属于组合错误，不是另建 LSP 包的理由。
 
 ## 本地服务器生命周期与协议行为
 
-`dsh-lsp-local` 按 `(provider id, canonical workspace realpath)` 懒启动一个服务器，并通过 single-flight 合并启动。插件加载时，它在清除凭据并应用环境变量覆盖后解析可执行文件；命令不可用时在注册前失败。服务器进程的启动保持懒执行（首次查询时才拉起），且不经过 shell。`maxMessageBytes` 默认值为 `16_000_000`，`maxStderrBytes` 默认值为 `1_000_000`，`maxDocumentBytes` 默认值为 `4_000_000`。崩溃使当前查询失败且不重放；后续查询可以替换进程。每次查询最多启动一个进程，因此 MVP 不设置跨请求重启计数器。
+`dsh-lsp-local` 按 `(provider id, canonical workspace target)` 懒启动一个服务器，并通过 single-flight 合并启动。插件加载时，它使用已配置的环境调用 `ctx.subprocess.resolveExecutable()`；命令不可用时在注册前失败。首次查询通过原始协议管道启动服务器，不经过 shell，并收集有界的 stderr 尾部。`maxMessageBytes` 默认值为 `16_000_000`，`maxStderrBytes` 默认值为 `1_000_000`，`maxDocumentBytes` 默认值为 `4_000_000`。崩溃使当前查询失败且不重放；后续查询可以替换进程。每次查询最多启动一个进程，因此 MVP 不设置跨请求重启计数器。
 
-初始化声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及 definition 与 implementation 的 `linkSupport: true`，但不支持动态注册。服务器返回的操作能力与同步能力均为真源。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值均属于协议错误。配置可以提供初始化选项和 `workspace/configuration` 响应，但客户端拒绝 `workspace/applyEdit`，绝不执行命令或编辑。
+初始化使用 `processId: null`，因为客户端与服务器可能位于不同的进程命名空间。它声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及 definition 与 implementation 的 `linkSupport: true`，但不支持动态注册。服务器返回的操作与同步能力均为真源。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值均属于协议错误。配置可以提供初始化选项和 `workspace/configuration` 响应，但客户端拒绝 `workspace/applyEdit`，绝不执行命令或编辑。
 
 导航结果直接映射 `Location`，并将 `LocationLink` 的 `targetUri` 与 `targetSelectionRange` 映射为统一位置。位置必须是非负整数。`hover` 归一化只接受有效的 `MarkupContent` 和 `MarkedString` 结构，保留字符串值，把带语言标签的值渲染为围栏代码块，并以一个空行连接数组。面向模型的工具在渲染后应用 `maxResultChars`。
 
@@ -143,7 +143,7 @@ interface LspToolInput {
 
 诊断需要独立的新鲜度、累积与 transcript 规则。重命名、代码操作和格式化等变更能力需要单独工具，并集成预览、权限和写入策略。
 
-本地提供方信任配置的服务器，不声称具备沙箱隔离。支持不受信任的二进制文件需要后续补充允许读取工作区，并执行私有缓存写入与临时写入的进程／文件系统契约；受限、远程或虚拟工作区需要另一种提供方。
+提供方信任配置的服务器。其文件系统可见性与进程隔离完全取决于挂载的执行环境；LSP 不增加独立的沙箱策略。
 
 ## 备选方案
 
@@ -155,9 +155,9 @@ interface LspToolInput {
 
 **公开 `resolve(request)` / `query(spec)`。** 没有需要填充默认值的字段时，resolve 只会暴露提供方选择，而公开 spec 可能活过提供方释放或替换。单一操作让选择与调用共用注册生命周期。
 
-**将信号包装为服务边界专用的执行上下文对象。** Web 传递裸 `AbortSignal`；仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时，`query()` 才引入上下文对象。
+**将信号包装为每服务边界的执行上下文对象。** Web 传递裸 `AbortSignal`；仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时，`query()` 才引入上下文对象。
 
-**通过 `ctx.fs` 或 `read` 工具读取。** 这可能把文档与另一文件系统命名空间中的服务器索引混合；工具输出还带窗口、行号且已被观察。host-local 提供方在子进程旁读取未观察的完整文本。
+**通过面向模型的 `read` 工具读取。**拒绝，因为工具输出带窗口与行号，会进入 transcript 且已被观察。提供方直接通过子进程所用的同一 `ctx.fs` 执行环境读取有界的完整文本。
 
 **保持文档打开。** 镜像编辑需要版本归属、覆盖所有路径的 `didChange`、HMR 恢复、淘汰和陈旧状态规则。临时打开避免在 MVP 引入这套状态机。
 
@@ -180,14 +180,14 @@ interface LspToolInput {
 - 同步测试固定 UTF-16 协商与转换、受支持和被拒绝的 `textDocumentSync` 形式、打开写入阻塞与失败、配对的临时打开/关闭、关闭写入失败和错误响应拒绝。
 - 超时测试固定一个 `TOOL_TIMEOUT` 预算、不对上游取消错误分类、服务边界无隐藏截止时间，以及受限且等待完成的清理。
 - 生命周期测试固定启动 single-flight、完整生命周期串行化及排队查询读取最新源文件、跨工作区并行、可取消队列、崩溃后不重放的替换、stdin 失败后的进程拆除，以及释放后完全停稳。
-- 主机文件系统测试固定 session cwd 要求、符号链接下相对与绝对源路径的规范 containment、文档校验、file/non-file URI 渲染、无格式源文本和不发送 `fs/observed`。
+- 文件系统宿主测试固定 session cwd 要求、提供方自有的 containment 与 URI 渲染、有界文档读取、无格式源文本和不发送 `fs/observed`。
 - 无密钥且固定版本的 TypeScript 真实服务器 e2e 覆盖四种操作；可运行配置使用同一项显式提供方映射。
 - 快照覆盖模型可见 schema、提示词、结果和省略提示；构建产物冒烟测试覆盖分帧与清理。
 - 包与架构文档覆盖配置、安全边界和搜索/读取指导；同一改动中，新的 `packages/lsp/` 包组要加入 AGENTS.md 的仓库布局块、packages/README.md 的分组表和 architecture.md。
 
 ## 影响
 
-各语言服务器对方法支持、能力解释和索引就绪时机的处理不同；LSP 没有统一的「索引完成」信号。不具备兼容临时打开同步能力的服务器不受支持，即使它能查询已关闭文档。受支持的服务器仍可能返回空结果或不完整结果，因此工具不承诺跨服务器完整性。固定的 TypeScript e2e 只建立一条兼容性基线，不代表跨语言承诺。
+各语言服务器对方法支持、能力解释和索引就绪时机的处理不同；LSP 没有统一的“索引完成”信号。无法声明兼容临时打开同步能力的服务器不受支持，即使它能查询已关闭文档。受支持的服务器仍可能返回空结果或不完整结果，因此工具不承诺跨服务器完整性。固定的 TypeScript e2e 只建立一条兼容性基线，不代表跨语言承诺。
 
 临时打开会重复解析并产生通知。实例内串行会增加并发 agent 的延迟，长期运行的工作区进程则持续占用内存直到释放。
 
@@ -195,4 +195,4 @@ interface LspToolInput {
 
 UTF-16 光标列与协议完全一致，但模型难以在包含非 BMP 字符的文本中准确计数。无效位置或不在符号上的位置可能返回空结果，因此错误文本和提示词示例必须说明坐标约定，同时避免鼓励模型广泛使用 LSP。
 
-直接访问 Node 文件系统会对齐查询快照与服务器索引，但绕过 `ctx.fs` 及其策略。规范路径 containment 会拒绝工作区外的源文件；受信任的服务器仍可读取工作区并使用缓存。因此，第一版要求受信任的 host-local 部署，不提供沙箱保证。
+配对的文件系统／子进程提供方会对齐查询快照与服务器索引，但不会因此使受信任的语言服务器变得安全。规范 containment 会拒绝工作区外的查询源；服务器本身获得执行环境所配置的权限，仍可读取其他路径或使用缓存。
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml
index daa727ccb0..469c3f9a24 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
-2026-07-26-subprocess-consumer-migration.md: 477dffc2271db08b8986b34645067b247ad7ace7
-2026-07-26-subprocess-consumer-migration.zh.md: 8e0e377fc3fe00ff452803fe7fe5f4115003f937
+2026-07-26-subprocess-consumer-migration.md: abc7c8504595641b2b821df5ddbd4645c3a15336
+2026-07-26-subprocess-consumer-migration.zh.md: 500dcfe36f63315156b1a3cc48670eaf1c204b20
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
index 477dffc227..abc7c85045 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-26-subprocess-consumer-migration.zh.md)
 
 ## Problem
 
-The [subprocess seam](2026-07-26-subprocess-seam.md) shipped shaped for exactly one consumer family: batch-collected stdout/stderr, batch stdin, a single escalating `kill()`. That was deliberate scope control, and its own note records "migrate the other spawn sites" as rejected-for-now. Review on the introducing PR reversed that deferral: the stacked follow-up should reshape the interface toward Node's API and move the remaining process-running places onto the service. The remaining spawners each carried a private copy of some slice of the same mechanics — lsp-local had its own detached-tree signalling (POSIX group + Windows taskkill + liveness polling), subagent-subprocess had the dispose ladder and its own scrub, and mcp-client, pty-local, the SDK helper, and the TUI Git probe each carried another credential scrub — and none of it was swappable or centrally testable.
+The [subprocess seam](2026-07-26-subprocess-seam.md) shipped shaped for exactly one consumer family: batch-collected stdout/stderr, batch stdin, a single escalating `kill()`. That was deliberate scope control, and its own note records "migrate the other spawn sites" as rejected-for-now. Review on the introducing PR reversed that deferral: the stacked follow-up should reshape the interface toward Node's API and move the remaining process-running places onto the service. The remaining spawners each carried a private copy of some slice of the same mechanics — lsp-local had its own detached-tree signalling (POSIX group + Windows taskkill + liveness polling), subagent-subprocess had the dispose ladder and its own scrub, mcp-client and pty-local and the SDK helper each had a third/fourth/fifth copy of the credential scrub — and none of it was swappable or centrally testable.
 
 ## Decision
 
@@ -15,24 +15,24 @@ The seam's vocabulary is now Node-shaped, and every spawner that can ride the se
 - **Per-stream stdio dispositions** on `SubprocessSpawnSpec`: `'pipe'` (the raw `Readable`/`Writable`, for consumer-owned protocol framing), `'inherit'` (diagnostics to the parent's stream), and collect mode `{ maxBytes, spill? }` — the original bounded tail-keep shape, with the spill file now optional so a diagnostic tail (a language server's stderr) buffers without touching disk. stdin is `'ignore'`, `'pipe'`, or `{ data }` (write-and-close batch).
 - **`SubprocessOutcome` carries exit facts only** (Node's close-event vocabulary); collected output stays readable through `handle.collected` after settlement (spill fds seal at the settle boundary), so batch and streaming callers share one access path and nothing is copied into the outcome.
 - **Tree-scoped termination behind one verb**: `terminate()` owns the SIGTERM→grace→SIGKILL escalation (serves the spec's abort signal too, and is a no-op once the tree is gone) — the handle exposes no single-signal `kill(signal?)`, so a consumer cannot skip the grace window; `waitForExit()` polls tree liveness (POSIX group probe; direct-child boundary on Windows); Windows tree termination (`taskkill /T`, injectable) moved in from lsp-local, so tree semantics are platform-correct for every consumer. (The stdin-EOF-first dispose ladder initially absorbed from `subagent-subprocess` later moved back out to its one consumer — see the [ladder-ownership Agent Note](2026-07-27-dispose-ladder-to-consumer.md).)
-- **One scrub definition**: `scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` live on the seam, and credential-shaped names contain `KEY`, `PASSWORD`, `SECRET`, or `TOKEN`, case-insensitively. Spawners that cannot route the spawn itself through the service — pty-local (node-pty owns the fork), mcp-client (the MCP SDK owns the transport spawn), and the TUI's synchronous Git branch probe — import the function, so environment policy is single-sourced even where process ownership is not. The SDK helper's `scrubEnvironment()` defaults through the function and applies the exported pattern when its caller supplies an explicit environment; the pattern remains public for this production consumer.
+- **One scrub definition**: `scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` live on the seam. Ordinary and terminal local spawns apply it inside `dsh-subprocess-local`; mcp-client still imports it because the MCP SDK owns that transport spawn, and the SDK helper's `scrubEnvironment()` defaults through it as well.
 
-Migrations landed with the reshape: **bash-local/bash-sandbox** (collect modes + batch stdin; the bash `kill()` maps to `terminate()` so `task_kill` keeps escalation semantics), **lsp-local** (piped protocol streams + a no-spill collected stderr tail; `LspConnection` takes the seam's spawn function; its private tree-op helpers deleted), **subagent-acp** (piped ndjson streams + inherited stderr; spawn failure surfaces through `done` rejection into the same startup race; disposal is the backend-owned `disposeAcpChild` ladder over the seam's verbs, with the plugin's configured graces). **`dsh-subagent-subprocess` is deleted** — the dispose ladder and scrub are the seam's; the unused isolated-config-dir helper died with it (no consumer existed).
+Migrations landed with the reshape: **bash-local/bash-sandbox** (collect modes + batch stdin; the bash `kill()` maps to `terminate()` so `task_kill` keeps escalation semantics), **lsp-local** (piped protocol streams + a no-spill collected stderr tail; `LspConnection` takes the seam's spawn function; its private tree-op helpers deleted), **subagent-acp** (piped ndjson streams + inherited stderr; spawn failure surfaces through `done` rejection into the same startup race; disposal is the backend-owned `disposeAcpChild` ladder over the seam's verbs, with the plugin's configured graces), and **pty-local** through the later [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) (`node-pty` allocation and process inspection sit behind `spawnTerminal()`, while readiness and terminal policy remain in the consumer). **`dsh-subagent-subprocess` is deleted** — the dispose ladder and scrub are the seam's; the unused isolated-config-dir helper died with it (no consumer existed).
 
 Compositions mounting lsp-local or subagent-acp now load `dsh-subprocess-local` (the plugins inject `'subprocess'`); the acp/lsp test fixtures gained the row.
 
 ## Alternatives considered
 
-**Keep the batch-only seam and let stream consumers stay bespoke.** The introducing note's position, rejected by review: it leaves three private copies of tree signalling and six of the scrub, and any future runner (containerized executor, remote process host) would have to pick which private copy to fork. The Node-shaped dispositions cover all three observed stream shapes without widening the outcome type or buffering piped streams.
+**Keep the batch-only seam and let stream consumers stay bespoke.** The introducing note's position, rejected by review: it leaves three private copies of tree signalling and five of the scrub, and any future runner (containerized executor, remote process host) would have to pick which private copy to fork. The Node-shaped dispositions cover all three observed stream shapes without widening the outcome type or buffering piped streams.
 
 **A single `stdio: 'pipe' | 'inherit' | 'collect'` mode for all three streams at once.** Rejected: real consumers mix modes per stream (lsp: pipe/pipe/collect; acp: pipe/pipe/inherit; bash: data/collect/collect). Per-stream dispositions are exactly Node's shape and avoid a second spawn call for the mixed cases.
 
-**Migrate pty-local and mcp-client spawns too.** Rejected on ownership grounds, not scope: node-pty's `fork()` allocates the terminal itself, and the MCP SDK's `StdioClientTransport` spawns internally — neither call site is ours to route. They adopt the shared scrub (the part that is policy), and their READMEs say why the spawn stays put.
+**Keep pty-local and mcp-client spawns outside the service.** The MCP SDK still owns its transport spawn. PTY allocation is different: the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) moves `node-pty` behind one deep terminal primitive, resolving the ownership objection without pretending an ordinary piped spawn can provide terminal semantics.
 
-**Migrate the test-support launchers (acp-snapshot, loader-smoke), the SDK package-manager runner, and the TUI Git probe.** Rejected: the support packages are deliberately dependency-light test infrastructure that must not depend on product seams; the SDK wizard's `stdio: 'inherit'`-with-redirect semantics plus its out-of-composition lifecycle (no cordis context at all) make the service a poor fit; and the TUI probe is synchronous. The production callers share the scrub instead.
+**Migrate the test-support launchers (acp-snapshot, loader-smoke) and the SDK package-manager runner.** Rejected: the support packages are deliberately dependency-light test infrastructure that must not depend on product seams, and the SDK wizard's `stdio: 'inherit'`-with-redirect semantics plus its out-of-composition lifecycle (no cordis context at all) make the service a poor fit; it shares the scrub instead.
 
 ## Consequences
 
-Bought: one implementation of tree signalling, escalation, bounded collection, and the scrub, tested once in `dsh-subprocess-local`'s suites (including injected-platform Windows coverage that lsp-local's private copy never had); lsp-local and subagent-acp shed their process plumbing and their children now survive plugin reloads and die with composition teardown like bash's; a whole package (`dsh-subagent-subprocess`) is gone. The seam README's "one consumer family" limitation is retired.
+Bought: one implementation of tree signalling, escalation, bounded collection, terminal process mechanics, and the scrub, tested once in `dsh-subprocess-local`'s suites (including injected-platform Windows coverage that lsp-local's private copy never had); lsp-local, pty-local, and subagent-acp shed provider-specific process plumbing and their children die with composition teardown like bash's; a whole package (`dsh-subagent-subprocess`) is gone. The seam README's "one consumer family" limitation is retired.
 
-Cost: the seam is wider — three stdio modes and the terminate/waitForExit/dispose lifecycle surface instead of one mode and one verb — so a future backend implements more surface; the compositions for lsp-local/subagent-acp each carry the subprocess row now; and `SubprocessOutcome` no longer carries output, a breaking shape change inside the still-unreleased stack (the PR2 layer was updated in place rather than shimmed, per the pre-release stance). pty-local/mcp-client/SDK/TUI/test-support spawns remain outside the service by ownership or execution shape, with the scrub as the shared floor and its pattern intentionally exported for explicit-environment consumers.
+Cost: the seam is wider — execution-world coordinates, executable lookup, three stdio modes, process-tree lifecycle, and one terminal primitive — so a future backend implements more surface; the compositions for lsp-local, pty-local, and subagent-acp each carry the subprocess row; and `SubprocessOutcome` no longer carries output, a breaking shape change inside the still-unreleased stack. MCP/SDK/test-support spawns remain outside the service by ownership, with the scrub as the shared floor.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md
index 8e0e377fc3..500dcfe36f 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 子进程 seam 转向 Node 形状，所有具备条件的 spawn 调用点一并迁入
+# Agent Note: 进程 seam 转向 Node 形状，所有具备条件的 spawn 调用点一并迁入
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-[子进程 seam](2026-07-26-subprocess-seam.md) 交付时恰好只为一个消费方家族塑形：批量收集的 stdout/stderr、批量 stdin、单一的升级式 `kill()`。那是有意的范围控制，其自身的 Agent Note 也把「迁移其余 spawn 调用点」记为暂缓否决项。引入该 seam 的 PR（Pull Request）上的评审推翻了这一暂缓决定：堆叠其上的后续变更应当把接口向 Node 的 API 方向重塑，并把其余运行进程之处迁到该服务上。其余各 spawn 调用点此前各自持有同一套机制中某个切片的私有副本——lsp-local 自带 detached 进程树信号发送（POSIX 进程组 + Windows taskkill + 存活轮询），subagent-subprocess 自带 dispose（资源释放）阶梯和自己的凭据清除，mcp-client、pty-local、SDK helper 与 TUI Git 探测则各自持有另一份凭据清除——而这一切既不可替换，也无法集中测试。
+[进程 seam](2026-07-26-subprocess-seam.md) 交付时恰好只为一个消费方家族塑形：批量收集的 stdout/stderr、批量 stdin、单一的升级式 `kill()`。那是有意的范围控制，其自身的 Agent Note 也把「迁移其余 spawn 调用点」记为暂缓否决项。引入该 seam 的 PR（Pull Request）上的评审推翻了这一暂缓决定：堆叠其上的后续变更应当把接口向 Node 的 API 方向重塑，并把其余运行进程之处迁到该服务上。其余各 spawn 调用点此前各自持有同一套机制中某个切片的私有副本——lsp-local 自带 detached 进程树信号发送（POSIX 进程组 + Windows taskkill + 存活轮询），subagent-subprocess 自带 dispose（资源释放）阶梯和自己的凭据清除，mcp-client、pty-local 与 SDK helper 则各自持有凭据清除的第三、第四、第五份副本——而这一切既不可替换，也无法集中测试。
 
 ## 决策
 
@@ -15,24 +15,24 @@ Status: implemented
 - **按流划分的 stdio 处置方式（disposition）**，位于 `SubprocessSpawnSpec` 上：`'pipe'`（原始的 `Readable`/`Writable`，供消费方自有的协议分帧使用）、`'inherit'`（诊断输出直通父进程的流），以及收集模式（collect）`{ maxBytes, spill? }`——即最初的有界尾部保留形状，只是 spill 文件改为可选，使诊断尾部（例如语言服务器的 stderr）无需落盘即可缓冲。stdin 则为 `'ignore'`、`'pipe'` 或 `{ data }`（写完即关闭的批量形式）。
 - **`SubprocessOutcome` 只承载退出事实**（Node close 事件的词汇）；收集到的输出在结算后仍可经 `handle.collected` 读取（spill 文件描述符在结算边界封存），因此批量与流式调用方共用一条访问路径，也没有任何内容被复制进这份结果。
 - **以进程树为范围的终止，集中在一个动词后面**：`terminate()` 拥有 SIGTERM→宽限期→SIGKILL 升级（也承接 spec 的 abort 信号，进程树消亡后为空操作）——句柄不暴露单信号的 `kill(signal?)`，因此消费方无法跳过宽限窗口；`waitForExit()` 轮询进程树存活状态（POSIX 进程组探测；Windows 上以直接子进程为界）。Windows 进程树终止（`taskkill /T`，可注入）自 lsp-local 迁入，因此每个消费方拿到的进程树语义在各平台上都正确。（最初从 `subagent-subprocess` 吸收的以 stdin EOF 打头的 dispose 阶梯，后来又移回其唯一消费方——见[阶梯归属 Agent Note](2026-07-27-dispose-ladder-to-consumer.md)。）
-- **凭据清除只有一份定义**：`scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` 定义在 seam 上，且凭据形状的名称不区分大小写地包含 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN`。无法把 spawn 本身路由到该服务的调用点——pty-local（node-pty 拥有 fork）、mcp-client（MCP SDK 拥有传输层的 spawn）与 TUI 的同步 Git 分支探测——改为导入该函数，因此即便进程所有权无法统一，环境策略仍是单一来源。SDK helper 的 `scrubEnvironment()` 默认委托给该函数，并在调用方显式传入环境时应用导出的正则；该正则因此生产消费方而保持公开。
+- **凭据清除只有一份定义**：`scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` 定义在 seam 上。普通本地 spawn 与终端本地 spawn 都在 `dsh-subprocess-local` 内部应用该定义；mcp-client 仍需导入它，因为 MCP SDK 拥有该传输层 spawn，SDK helper 的 `scrubEnvironment()` 默认同样委托给它。
 
-各项迁移随这次重塑一并落地：**bash-local/bash-sandbox**（收集模式 + 批量 stdin；bash 的 `kill()` 映射到 `terminate()`，因此 `task_kill` 保有升级语义），**lsp-local**（管道化的协议流 + 无 spill 的 stderr 收集尾部；`LspConnection` 改为接收 seam 的 spawn 函数；其私有的进程树操作辅助函数已删除），**subagent-acp**（管道化的 ndjson 流 + inherit 的 stderr；spawn 失败经 `done` 的 reject 汇入同一个启动竞态；dispose 是后端自有的 `disposeAcpChild` 阶梯，经由 seam 的动词运行，携带插件所配置的宽限期）。**`dsh-subagent-subprocess` 已删除**——dispose 阶梯与凭据清除归 seam 所有；无人使用的隔离配置目录辅助函数随之消亡（其消费方本就不存在）。
+各项迁移随这次重塑一并落地：**bash-local/bash-sandbox**（收集模式 + 批量 stdin；bash 的 `kill()` 映射到 `terminate()`，因此 `task_kill` 保有升级语义），**lsp-local**（管道化的协议流 + 无 spill 的 stderr 收集尾部；`LspConnection` 改为接收 seam 的 spawn 函数；其私有的进程树操作辅助函数已删除），**subagent-acp**（管道化的 ndjson 流 + inherit 的 stderr；spawn 失败经 `done` 的 reject 汇入同一个启动竞态；dispose 是后端自有的 `disposeAcpChild` 阶梯，经由 seam 的动词运行，携带插件所配置的宽限期），以及后来通过[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)迁移的 **pty-local**（`node-pty` 分配与进程检查位于 `spawnTerminal()` 之后，就绪状态和终端策略仍归消费方所有）。**`dsh-subagent-subprocess` 已删除**——dispose 阶梯与凭据清除归 seam 所有；无人使用的隔离配置目录辅助函数随之消亡（其消费方本就不存在）。
 
 挂载 lsp-local 或 subagent-acp 的组合如今都加载 `dsh-subprocess-local`（这两个插件注入 `'subprocess'`）；acp/lsp 测试 fixture（测试前置数据）补上了这一行组合配置。
 
 ## 曾考虑的替代方案
 
-**保持只支持批量的 seam，让流式消费方继续各自为政。**这正是引入该 seam 的 Agent Note 当初的立场，评审将其否决：这样会留下三份进程树信号发送的私有副本和六份凭据清除的私有副本，而未来任何运行器（容器化执行器、远程进程宿主）都得挑选去 fork 哪一份私有副本。Node 形状的处置方式覆盖已观察到的全部三种流形状，既不拓宽结果类型，也不缓冲管道化的流。
+**保持只支持批量的 seam，让流式消费方继续各自为政。**这正是引入该 seam 的 Agent Note 当初的立场，评审将其否决：这样会留下三份进程树信号发送的私有副本和五份凭据清除的私有副本，而未来任何运行器（容器化执行器、远程进程宿主）都得挑选去 fork 哪一份私有副本。Node 形状的处置方式覆盖已观察到的全部三种流形状，既不拓宽结果类型，也不缓冲管道化的流。
 
 **用单个 `stdio: 'pipe' | 'inherit' | 'collect'` 模式一次性统辖全部三条流。**否决：真实消费方按流混用模式（lsp：pipe/pipe/collect；acp：pipe/pipe/inherit；bash：data/collect/collect）。按流划分的处置方式恰好就是 Node 的形状，也免去了混用场景的第二个 spawn 调用。
 
-**把 pty-local 与 mcp-client 的 spawn 也一并迁移。**基于所有权而非范围否决：node-pty 的 `fork()` 自行分配终端，MCP SDK 的 `StdioClientTransport` 在内部完成 spawn——这两处调用点都不归我们路由。它们采纳共享的凭据清除（那正是属于策略的部分），并在各自的 README 中说明 spawn 为何留在原地。
+**让 pty-local 与 mcp-client 的 spawn 留在服务之外。**MCP SDK 仍拥有其传输层 spawn。PTY 分配则不同：[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)把 `node-pty` 放到一个深层终端原语之后，既解决所有权异议，也不假装普通管道化 spawn 能够提供终端语义。
 
-**迁移 test-support 启动器（acp-snapshot、loader-smoke）、SDK package-manager 运行器与 TUI Git 探测。**否决：support 各包是刻意保持轻依赖的测试基础设施，不得依赖产品 seam；SDK 向导那套附带重定向的 `stdio: 'inherit'` 语义，加上其完全脱离组合的生命周期（根本没有 cordis 上下文），使该服务并不合用；TUI 探测则是同步调用。这些生产调用点改为共享凭据清除。
+**迁移 test-support 启动器（acp-snapshot、loader-smoke）与 SDK package-manager 运行器。**否决：support 各包（package）是刻意保持轻依赖的测试基础设施，不得依赖产品 seam；而 SDK 向导那套附带重定向的 `stdio: 'inherit'` 语义，加上其完全脱离组合的生命周期（根本没有 cordis 上下文），使该服务并不合用；它改为共享凭据清除。
 
 ## 后果
 
-换来的是：进程树信号发送、升级、有界收集与凭据清除各自只剩一份实现，且只在 `dsh-subprocess-local` 的测试套件中测试一次（其中包括 lsp-local 的私有副本从未有过的、以注入平台方式实现的 Windows 覆盖）；lsp-local 与 subagent-acp 卸下了自己的进程管道，其子进程如今像 bash 的一样，在插件重载后存活、随组合拆除而终止；一个完整的包（`dsh-subagent-subprocess`）就此消失。seam README 中「只有一个消费方家族」的限制说明也随之退役。
+换来的是：进程树信号发送、升级、有界收集、终端进程机制与凭据清除各自只剩一份实现，且只在 `dsh-subprocess-local` 的测试套件中测试一次（其中包括 lsp-local 的私有副本从未有过的、以注入平台方式实现的 Windows 覆盖）；lsp-local、pty-local 与 subagent-acp 卸下了提供方专用的进程管道，其子进程如今像 bash 的一样随组合拆除而终止；一个完整的包（`dsh-subagent-subprocess`）就此消失。seam README 中「只有一个消费方家族」的限制说明也随之退役。
 
-代价是：这道 seam 变宽了（stdio 模式从一种变为三种、生命周期接口面从一个动词扩展为 terminate/waitForExit/dispose 这一组），未来的后端因此要实现更宽的接口面；lsp-local/subagent-acp 的各组合如今都多出 subprocess 这一行组合配置；`SubprocessOutcome` 也不再承载输出，这是仍未发布的堆叠变更内部的一次破坏性形状变更（依照预发布立场，PR2 那一层被就地更新，而非加 shim）。pty-local/mcp-client/SDK/TUI/test-support 的 spawn 因所有权归属或执行形状留在该服务之外，以凭据清除作为共底线，且为显式环境的生产消费方有意保持该正则导出。
+代价是：这道 seam 变宽了，涵盖执行环境坐标、可执行文件查找、三种 stdio 模式、进程树生命周期和一个终端原语，未来的后端因此要实现更宽的表面；lsp-local、pty-local 与 subagent-acp 的各组合如今都多出 subprocess 这一行组合配置；`SubprocessOutcome` 也不再承载输出，这是仍未发布的堆叠变更内部的一次破坏性形状变更。MCP／SDK／test-support 的 spawn 因所有权归属留在该服务之外，以凭据清除作为共享底线。
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index 1a918fc62c..94711572d6 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: ad2f8522be51ba16b0df155aeb334a88f493890f
-2026-07-26-subprocess-seam.zh.md: 575c02e346531824ef409ddc6155aa2b59ce4e63
+2026-07-26-subprocess-seam.md: d5dee7361e48f18f3147444b2db74da3dd1c1161
+2026-07-26-subprocess-seam.zh.md: 884c572dc65c0fbf240f7e4e3b0387038e21f5ad
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index ad2f8522be..d5dee7361e 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -12,8 +12,8 @@ English | [中文](2026-07-26-subprocess-seam.zh.md)
 
 A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it:
 
-- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess` with one method, `spawn(spec): SubprocessHandle`, and the shared vocabulary: the fully-explicit `SubprocessSpawnSpec` (argv, cwd, per-stream stdio dispositions, grace — no defaults; deployment-varying knobs stay with the calling seam's config, per the `dsh-bash` request/spec template and the no-hidden-defaults rule), `SubprocessHandle` with non-consuming offset-based readers, `SubprocessOutcome` with deliberately no timeout/cancel classification, and the shared scrub plus `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` types. `argv` is never shell-interpreted. (The [consumer-migration Agent Note](2026-07-26-subprocess-consumer-migration.md) later widened the stdio and termination vocabulary Node-ward.)
-- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`): detached groups, tail-keep truncation with private bounded spill files, credential scrub with the explicit-env merge after it, group kill escalation, and disposal that kills and joins every still-running managed process. It has no config; every limit arrives on the spec. The terminal `ENV_OVERRIDES` (`TERM=dumb` etc.) did NOT move — that is bash-tool presentation policy and stays in `dsh-bash-local`, merged through the ordinary env channel.
+- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd and runtime storage, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Its vocabulary includes per-stream stdio dispositions, process and terminal handles, exit facts with deliberately no timeout/cancel classification, and the shared scrub plus `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` types. `argv` is never shell-interpreted.
+- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, private runtime storage, foreground/session inspection, credential scrub with explicit env merged after it, tree cleanup, and disposal that terminates and joins every managed process. It has no config; every limit arrives on the spec. Bash and PTY presentation environment overrides stay in their consumers.
 - **`dsh-bash-local` (consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
 - **`dsh-bash` (seam)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
 
@@ -25,7 +25,7 @@ Background-process lifetime moved from the executor to the subprocess service: t
 
 **Leave the process plumbing inside `dsh-bash-local` (status quo).** Rejected for the same reason the [task registry split](2026-07-26-task-registry-seam.md) landed: the boundary is stable and already documented in-code (`run.ts`'s module doc said "this layer reacts to an abort signal; the executor owns deadlines and classifies causes"), and keeping it private makes every future non-shell runner either fork the mechanics or depend on a bash-named package for non-bash work. The user-visible driver for this stack was exactly this split.
 
-**Migrate the repo's other spawn sites (lsp-local, pty-local, subagent-subprocess, sdk package-manager, test-support launchers) onto `ctx.subprocess` in the same change.** Rejected as scope creep with real design risk at this PR's scale: those sites have materially different stream and lifecycle needs — node-pty ownership (pty), LSP framing over long-lived stdio with tree-kill fallbacks (lsp), stdin-EOF-first disposal ladders and no output buffering (subagent transports) — and forcing them under a handle shaped for bounded batch output would either bloat the seam or misfit the consumers. The seam shipped proven against its one real consumer family, per the shape-interfaces-around-current-consumers rule. Review then asked for exactly that follow-up as a stacked PR; the [consumer-migration Agent Note](2026-07-26-subprocess-consumer-migration.md) records the Node-ward reshape and which sites moved (and which stayed, by ownership).
+**Migrate the repo's other spawn sites in the introducing change.** Rejected as scope creep with real design risk at that scale. The later [consumer-migration](2026-07-26-subprocess-consumer-migration.md) and [portable execution-world](2026-07-28-portable-execution-world-consumers.md) decisions reshape the interface around the observed LSP, subagent, PTY, and Code Runtime consumers; SDK and test-support launchers remain outside by ownership.
 
 **Put `run_in_background`/task semantics into the process seam instead.** Rejected: that boundary already exists — `ctx.tasks` owns ids, ownership, and notices, and the bash tool adapts a `BashProcess` into task hooks. The process seam sits *below* the bash executor, not beside the task registry.
 
@@ -33,6 +33,6 @@ Background-process lifetime moved from the executor to the subprocess service: t
 
 ## Consequences
 
-Bought: "run and manage a process" is a swappable capability with the standard three-package shape (consumer count starts at two: `bash-local`, `bash-sandbox`); a containerized or remote process backend slots in without touching bash semantics; the shared `DSH_*`/output vocabulary has a non-shell home; and background processes survive executor reloads, matching the task registry's lifetime model. The spawn plumbing suite moved wholesale to `dsh-subprocess-local` (argv-based, plus argv-validation and service lifecycle/disposal suites); the executor suite now pins the bash-owned layers (classification, merge, spawn-failure note, service-owned lifetime) against the real service.
+Bought: "run and manage a process" is a swappable capability used by Bash, LSP, PTY, Code Runtime, and ACP consumers; a containerized or remote process backend slots in without changing their domain semantics; the shared `DSH_*`/output vocabulary has a non-shell home; and background processes survive executor reloads, matching the task registry's lifetime model. Process and terminal plumbing is tested through `dsh-subprocess-local`; consumer suites pin only their owned behavior against the real service.
 
 Cost: one more package pair and one more composition row everywhere a bash executor loads — a boot that loads an executor without the subprocess service leaves `ctx.bash` pending on `ctx.subprocess` (standard missing-service behavior). The moved-vocabulary re-exports keep `dsh-bash` imports working but mean two packages now name the same types; the subprocess seam is the owner and the bash seam documents the re-export. The spawn-failure note became single-delivery through the read path where the old plumbing retained it in the stderr buffer for repeated `readFrom(0)` reads — acceptable because the bash background read path was already a consuming cursor, and the note reaches the one reader that exists.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 575c02e346..884c572dc6 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 子进程服务是 bash 执行器之下的独立 seam（`dsh-subprocess` / `dsh-subprocess-local`）
+# Agent Note: 进程管理器是 bash 执行器之下的独立 seam（`dsh-subprocess` / `dsh-subprocess-local`）
 
 Status: implemented
 
@@ -6,33 +6,33 @@ Status: implemented
 
 ## 问题
 
-`dsh-bash-local` 原先把两项因不同原因而变化的能力捆绑在一起：*运行一条 bash 命令*（命令默认值补全、超时分类、对模型友好的终端环境、bash 工具所渲染的 stdout/stderr 合并）与*运行并管理一个子进程*（detached 进程组、附带 spill 文件的有界尾部保留输出、凭据清除与 `DSH_*` 合并次序、SIGTERM→宽限期→SIGKILL 升级、先终止再等待退出的 dispose（资源释放））。进程这一半（`run.ts`）约占整个包的一半，却没有属于自己的 seam：未来的非 shell 运行器（直接执行 argv 的执行器、worker supervisor）将不得不重新实现这套机制，或者探入 bash 内部；而共享的 `DSH_*`/`CollectedOutput` 词汇则存放在一个名字承诺 shell 语义的包里。这种捆绑还把后台进程的存续期系在执行器的 fiber 上：重载 bash 执行器会杀死每一个存活的后台进程。这一点不同于同级的[任务注册表](2026-07-26-task-registry-seam.md)：后者的注册存续期刻意长于生产方 fiber。
+`dsh-bash-local` 原先把两项因不同原因而变化的能力捆绑在一起：*运行一条 bash 命令*（命令默认值补全、超时分类、对模型友好的终端环境、bash 工具所渲染的 stdout/stderr 合并）与*运行并管理一个子进程*（detached 进程组、附带 spill 文件的有界尾部保留输出、凭据清除与 `DSH_*` 合并次序、SIGTERM→宽限期→SIGKILL 升级、先终止再等待退出的 dispose（资源释放））。进程这一半（`run.ts`）约占整个包（package）的一半，却没有属于自己的 seam：未来的非 shell 运行器（直接执行 argv 的执行器、worker supervisor）将不得不重新实现这套机制，或者探入 bash 内部；而共享的 `DSH_*`/`CollectedOutput` 词汇则存放在一个名字承诺 shell 语义的包里。这种捆绑还把后台进程的存续期系在执行器的 fiber 上：重载 bash 执行器会杀死每一个存活的后台进程。这一点不同于兄弟的[任务注册表](2026-07-26-task-registry-seam.md)：后者的注册存续期刻意长于生产方 fiber。
 
 ## 决策
 
 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方：
 
-- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`（仅一个方法：`spawn(spec): SubprocessHandle`），以及共享词汇：完全显式的 `SubprocessSpawnSpec`（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期，一律不设默认值；随部署变化的旋钮依照 `dsh-bash` 的 request/spec 模板与无隐藏默认值规则，留在调用方 seam 的配置里）、携带基于偏移量的非消费式读取器的 `SubprocessHandle`、刻意不含超时/取消分类的 `SubprocessOutcome`，以及共享的凭据清除与 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` 类型。`argv` 绝不经过 shell 解释。（[消费方迁移 Agent Note](2026-07-26-subprocess-consumer-migration.md) 其后将 stdio 与终止词汇拓宽为 Node 形状。）
-- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService`，构建在原 `run.ts` 管道（现为 `spawn.ts`）之上：detached 进程组、带私有有界 spill 文件的尾部保留截断、清除之后合并显式 env 的凭据清除、进程组 kill 升级，以及会终止每个仍在运行的受管进程并等待其退出的 dispose。该实现没有任何配置；每项限制都随 spec 到达。终端相关的 `ENV_OVERRIDES`（`TERM=dumb` 等）并未迁移：那是 bash 工具的呈现策略，留在 `dsh-bash-local` 里，经普通 env 通道合并。
+- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd 与运行时存储、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。其词汇包括按流划分的 stdio 处置方式（disposition）、进程与终端句柄、刻意不含超时／取消分类的退出事实，以及共享的凭据清除与 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` 类型。`argv` 绝不经过 shell 解释。
+- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、私有运行时存储、前台／会话检查、清除之后合并显式 env 的凭据清除、进程树清理，以及终止每个受管进程并等待其退出的 dispose。该实现没有任何配置；每项限制都随 spec 到达。Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
 - **`dsh-bash-local`（消费方）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
 - **`dsh-bash`（seam）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash 消费方需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
 
 如今，每个加载 bash 执行器的组合都同时加载 `@deepseek-ai/dsh-subprocess-local`：CLI（命令行界面）、各示例、Python 捆绑运行时、create-sdk 的 bash 功能资源，以及各内联测试配置。
 
-后台进程的存续期从执行器移到了子进程服务：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（服务的 dispose）仍是先终止再等待退出的边界。一条行为 seam 随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，服务会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
+后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为 seam 随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
 
 ## 曾考虑的替代方案
 
 **把进程管道留在 `dsh-bash-local` 里（维持现状）。**否决的理由与[任务注册表拆分](2026-07-26-task-registry-seam.md)得以落地的理由相同：这条边界既稳定，也早已记录在代码里（`run.ts` 的模块文档曾写明「this layer reacts to an abort signal; the executor owns deadlines and classifies causes」），而若继续将它保持私有，未来每个非 shell 运行器就只能要么 fork 这套机制，要么为非 bash 工作去依赖一个以 bash 命名的包。这组堆叠变更对用户可见的动因正是这一拆分。
 
-**在同一变更中把仓库其余 spawn 调用点（lsp-local、pty-local、subagent-subprocess、sdk package-manager、test-support 各启动器）迁到 `ctx.subprocess` 上。**在本 PR（Pull Request）的规模下，作为带有真实设计风险的范围蔓延否决。这些调用点在流与生命周期上的需求存在实质差异：node-pty 所有权（pty）、长生命周期 stdio 上的 LSP 分帧加进程树终止回退（lsp）、以 stdin EOF 打头的 dispose 阶梯和完全不缓冲输出（subagent 传输层）。把它们强行纳入一个按有界批量输出塑形的句柄之下，要么会让这道 seam 膨胀，要么会让句柄与消费方错配。依照「接口围绕当前消费方塑形」的规则，该 seam 当时在其唯一真实的消费方家族上得到验证后交付。评审随后恰恰要求以堆叠 PR 的形式完成这项后续工作；[消费方迁移 Agent Note](2026-07-26-subprocess-consumer-migration.md) 记录了向 Node 形状的重塑，以及哪些调用点迁入（哪些因所有权归属而留在原地）。
+**在引入 seam 的同一变更中迁移仓库其余 spawn 调用点。**否决，因为在当时的规模下属于带有真实设计风险的范围蔓延。后续的[消费方迁移](2026-07-26-subprocess-consumer-migration.md)与[可移植执行环境](2026-07-28-portable-execution-world-consumers.md)决策围绕已观察到的 LSP、subagent、PTY 与 Code Runtime 消费方重塑接口；SDK 与 test-support 启动器因所有权归属仍留在服务之外。
 
 **改把 `run_in_background`/任务语义放进进程 seam。**否决：那条边界已经存在。`ctx.tasks` 拥有 id、所有权与通知，bash 工具则把 `BashProcess` 适配成任务钩子。进程 seam 位于 bash 执行器*之下*，而不是与任务注册表并列。
 
-**把 `ENV_OVERRIDES`（TERM=dumb、PAGER=cat 等）移入子进程服务。**否决：通用子进程服务不得把终端呈现策略强加给非终端消费方；对环境中凭据形态名称与 `DSH_*` 名称的清除是安全与身份不变式，予以保留，但终端友好性是 bash 工具自己的选择，经 spec 的显式 env 表达，而调用方自己的条目依旧优先。
+**把 `ENV_OVERRIDES`（TERM=dumb、PAGER=cat 等）移入管理器。**否决：通用进程管理器不得把终端呈现策略强加给非终端消费方；对环境中凭据形态名称与 `DSH_*` 名称的清除是安全与身份不变式，予以保留，但终端友好性是 bash 工具自己的选择，经 spec 的显式 env 表达，而调用方自己的条目依旧优先。
 
 ## 后果
 
-换来的是：「运行并管理一个进程」成为一项具备标准三包形态的可替换能力（消费方起步就有两个：`bash-local`、`bash-sandbox`）；容器化或远程进程后端可以直接接入，而不触碰 bash 语义；共享的 `DSH_*`/输出词汇有了一个不带 shell 含义的归属；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。spawn 管道测试套件整体迁至 `dsh-subprocess-local`（现以 argv 为基础，外加 argv 校验与服务生命周期/dispose 套件）；执行器测试套件如今以真实服务为基准，固定 bash 自有的各层行为（分类、合并、spawn 失败提示、归服务所有的存续期）。
+换来的是：「运行并管理一个进程」成为 Bash、LSP、PTY、Code Runtime 与 ACP（Agent Client Protocol）消费方共用的可替换能力；容器化或远程进程后端可以直接接入，而无需改变各领域语义；共享的 `DSH_*`/输出词汇有了一个不带 shell 含义的归属；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。进程与终端管道通过 `dsh-subprocess-local` 测试；消费方测试套件只需针对真实服务固定各自拥有的行为。
 
-代价是：多出一对包，而且凡加载 bash 执行器之处都多一行组合配置。若某次启动加载了执行器却没有加载子进程服务，`ctx.bash` 会因等待 `ctx.subprocess` 而保持挂起（标准的服务缺失行为）。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包如今命名同一批类型；进程 seam 是所有者，bash seam 则记录这层重导出。spawn 失败提示经由读取路径变为单次交付，而旧管道曾把它保留在 stderr 缓冲区里，供重复的 `readFrom(0)` 读取；这一点可以接受，因为 bash 的后台读取路径本就是消费游标，该提示能到达唯一存在的那个读取方。
+代价是：多出一对包，而且凡加载 bash 执行器之处都多一行组合配置。若某次启动加载了执行器却没有加载管理器，`ctx.bash` 会因等待 `ctx.subprocess` 而保持挂起（标准的服务缺失行为）。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包如今命名同一批类型；进程 seam 是所有者，bash seam 则记录这层重导出。spawn 失败提示经由读取路径变为单次交付，而旧管道曾把它保留在 stderr 缓冲区里，供重复的 `readFrom(0)` 读取；这一点可以接受，因为 bash 的后台读取路径本就是消费游标，该提示能到达唯一存在的那个读取方。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
new file mode 100644
index 0000000000..8b4288edb4
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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/architecture/2026-07-28-portable-execution-world-consumers.md
+2026-07-28-portable-execution-world-consumers.md: 000fa1b98964eb85550d0c607281937f8d7932c6
+2026-07-28-portable-execution-world-consumers.zh.md: 94e6bfcf94e450fafea2b33e152384da400e4b63
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
new file mode 100644
index 0000000000..000fa1b989
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -0,0 +1,48 @@
+# Agent Note: Portable consumers over filesystem and subprocess execution worlds
+
+Status: implemented
+
+English | [中文](2026-07-28-portable-execution-world-consumers.zh.md)
+
+## Problem
+
+The filesystem and subprocess seams made file and ordinary process access replaceable, but several higher capabilities still reached host Node APIs directly. A remote execution provider therefore appeared to need separate PTY, LSP, and Code Runtime packages even though their domain behavior did not change. Those packages would be shallow adapters: each would duplicate an existing consumer merely to replace its file and process operations.
+
+Ordinary pipes do not cover one requirement. A persistent terminal needs PTY allocation, foreground-process-group inspection and signalling, and cleanup of the complete terminal session. Pretending those operations can be rebuilt in `dsh-pty-local` from an ordinary `spawn()` handle would either leak provider internals or weaken its lifecycle contract.
+
+## Decision
+
+`ctx.fs` and `ctx.subprocess` together define one execution world. Providers mounted together must describe the same path namespace, executables, processes, and terminal sessions; higher capabilities consume those two interfaces rather than name the provider.
+
+The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, containment, and a bounded stable-handle text read. The existing text and mutation operations remain filesystem-owned.
+
+The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns byte I/O, foreground groups, signalling, TERM-to-KILL session cleanup, and a quiescence wait. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+
+Generic consumers use that execution world:
+
+- `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
+- `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and sends provider-owned file URIs. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them.
+
+`dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
+
+## Alternatives considered
+
+**Keep one PTY, LSP, and Code Runtime package per remote provider.** Rejected because provider mechanics would be repeated above the existing seams. The deletion test exposes the problem: deleting those adapters should not scatter domain behavior into the remote provider; the generic consumers already own it.
+
+**Model a terminal as an ordinary piped subprocess.** Rejected because pipes cannot allocate a controlling terminal, resolve the current foreground process group, or prove complete terminal-session cleanup. One terminal primitive is smaller and more honest than exposing substrate-specific escape hatches.
+
+**Move PTY readiness and session policy into the subprocess service.** Rejected because those are persistent-terminal consumer semantics, not OS process mechanics. A subprocess provider owns what only its substrate can do; `dsh-pty-local` owns what a Harness terminal means.
+
+**Delete the worker-thread Code Runtime.** Rejected because portability does not erase its current deployment need. The subprocess backend requires a Node executable and filesystem materialization; the worker backend has neither requirement and remains the supported single-process path.
+
+**Run the whole harness inside the remote environment.** Rejected as a different deployment model. Making execution capabilities portable does not move model calls, session state, plugin state, or the agent loop.
+
+## Consequences
+
+A remote execution provider implements only its shared sandbox owner plus filesystem and subprocess adapters. Bash, PTY, LSP, and subprocess Code Runtime compose above them, so fixes to those capabilities remain provider-neutral.
+
+The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers.
+
+The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal still waits for exact PID-identity-fenced descendants and the top-level terminal process to reach quiescence.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
new file mode 100644
index 0000000000..94e6bfcf94
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -0,0 +1,48 @@
+# Agent Note: 基于文件系统与进程管理执行世界的可移植消费方
+
+Status: implemented
+
+[English](2026-07-28-portable-execution-world-consumers.md) | 中文
+
+## 问题
+
+文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但若干上层能力仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY、LSP 与代码运行时包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
+
+普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期契约。
+
+## 决策
+
+`ctx.fs` 与 `ctx.subprocess` 共同定义一个执行世界。共同挂载的提供方必须描述相同的路径命名空间、可执行文件、进程和终端会话；上层能力消费这两个接口，而不引用具体提供方。
+
+文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI、包含关系，以及通过稳定句柄执行的有界文本读取。现有文本与变更操作仍归文件系统负责。
+
+进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责字节 I/O、前台进程组管理、信号发送、TERM→KILL 会话清理以及等待完全停稳。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+
+通用消费方使用该执行世界：
+
+- `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
+- `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并发送由提供方负责的文件 URI。其 JSON-RPC、池化、同步、取消和规范化保持不变。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。
+
+`dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
+
+## 考虑过的替代方案
+
+**为每个远程提供方分别保留 PTY、LSP 和代码运行时包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
+
+**把终端建模为普通的管道子进程。** 不予采纳，因为管道无法分配控制终端、确定当前前台进程组或证明完整终端会话已清理。一项终端原语比公开特定于执行基底的逃生口更小，也更能如实表达契约。
+
+**把 PTY 就绪判断与会话策略移入进程管理服务。** 不予采纳，因为这些属于持久终端消费方的语义，而非 OS 进程机制。进程管理提供方负责只有其执行基底才能完成的操作；`dsh-pty-local` 负责 Harness 终端的语义。
+
+**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件和文件系统物化，而 worker 后端两者都不需要，并且仍是受支持的单进程路径。
+
+**在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop（智能体循环）。
+
+## 后果
+
+远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY、LSP 和基于进程管理的代码运行时组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
+
+基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
+
+本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）仍会等待受精确 PID 身份校验保护的后代进程和顶层终端进程完全停稳。
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index bc05e497c5..a878942993 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 99bbed3edab32512f88ece9694d6519a1f89c2dd
-2026-06-15-code-mode.zh.md: ca1bbe9ed3e412186763d1ed4fca9ed06669d4c3
+2026-06-15-code-mode.md: 7e51b9fa726afe4c34b87457b562b4092ee6c93c
+2026-06-15-code-mode.zh.md: 4ba098d87d8c944e88c4cbe11ff78ac4383d3ac5
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index 99bbed3eda..7e51b9fa72 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-15-code-mode.zh.md)
 
 ## Problem
 
-In the registry's native presentation, the agent loop advertises every visible capability as a JSON-schema function definition. `ToolRegistry` contributes its schemas to the system-prompt assembly, the assembly's `tools` land on the wire (and in the logged request header), the model invokes one `tool-call` block per step, and at the time of this note the loop dispatched each call through `ctx.tools.execute()` **sequentially** (parallel tool execution was an open TODO then; bounded parallel dispatch has since shipped — the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md), the rolling pool in [docs/architecture.md](../../../../docs/architecture.md)) — with **every** intermediate `tool-result` re-entering the model's context on the next request.
+In the registry's native presentation, the agent loop advertises every visible capability as a JSON-schema function definition. `ToolRegistry` contributes its schemas to the system-prompt assembly, the assembly's `tools` land on the wire (and in the logged request header), the model invokes one `tool-call` block per step, and the loop dispatches each call through `ctx.tools.execute()` **sequentially** (parallel tool execution is an explicit open TODO in `dsh-tools` and [docs/architecture.md](../../../../docs/architecture.md)), with **every** intermediate `tool-result` re-entering the model's context on the next request.
 
 For multi-step tool work this is token-heavy and serial. The model cannot compose tools — loop over a result set, branch on an intermediate value, fan out, post-process — without a full model round-trip per call, and each round-trip drags the entire intermediate result back into context whether the model needs it or not.
 
@@ -20,7 +20,7 @@ Three decisions, each elaborated in its own section below:
 
 1. **Code Mode is a first-class presentation mode of `ToolRegistry`** (`dsh-tools`), selected by a validated `mode` config: `'native'` (the default, contributing the visible capability schemas), `'code'` (the registry contributes only its reserved `run_code` transport plus a generated SDK `.d.ts` in the system prompt), or `'both'` (native schemas and the transport + SDK). The registry shapes its canonical contribution at the source; the cooperative prompt-assembly result remains authoritative, and the logged request header records exactly that returned presentation.
 2. **Code execution is a capability seam** — `packages/code-runtime/` contains the interface package `@deepseek-ai/dsh-code-runtime`, which owns `ctx.codeRuntime` ([capability seams](../architecture/2026-06-13-capability-seams.md); consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is another implementation package, not a redesign.
-3. **The shipped implementation is `@deepseek-ai/dsh-code-runtime-worker`**: one fresh Node worker thread per run, executing the model's TypeScript after type-strip, with bindings bridged over the message port, an empty environment, configurable heap/output/time caps, and hard termination. Its trust posture is bash-equivalent by design — no unsafe-acknowledgement flags — because the harness already ships `dsh-bash-local`, which executes arbitrary model-written shell commands with strictly *more* ambient authority.
+3. **Two implementations preserve one fresh-worker contract**: `@deepseek-ai/dsh-code-runtime-worker` runs the worker in the harness process, while `@deepseek-ai/dsh-code-runtime-subprocess` materializes a runner through `ctx.fs` and launches it through `ctx.subprocess` for another execution world. Both execute host-stripped TypeScript in a fresh Node worker with an empty environment, bridged bindings, configurable heap/output/time caps, and hard termination. Their trust posture is bash-equivalent by design; stronger isolation comes from the mounted execution world.
 
 This note owns Code Mode's presentation, composition, isolation, and settlement foundation. The later [typed tool-return Agent Note](2026-07-20-code-mode-typed-tool-returns.md) owns the generated output map, canonical binding values, `ToolCallError`, and the lossless outer-output boundary.
 
@@ -32,7 +32,7 @@ This note owns Code Mode's presentation, composition, isolation, and settlement
 
 **Interaction with `toolOrder`, stated up front:** a configured `systemPrompt.toolOrder` naming native capabilities rejects every assembly under `mode: 'code'`, because those names are outside that mode's wire-validation universe. This is correct behavior, not a bug: a deployment using Code Mode updates its order config or drops it.
 
-**SDK prompt section.** In `'code'` and `'both'`, the lazy `tools:sdk` section in the tool-guidance order band renders the loaded runtime's language declarations plus fixed usage instructions for the scope's visible capabilities (TypeScript by default; the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md) added Python and the `ctx.codeRuntime.language` renderer table). It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
+**SDK prompt section.** In `'code'` and `'both'`, the lazy `tools:sdk` section in the tool-guidance order band renders TypeScript declarations plus fixed usage instructions for the scope's visible capabilities. It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
 
 **Assembly ownership.** `run_code` and `tools:sdk` enter the trusted `system-prompt/assemble` waterfall as normal assembly inputs. A scoped `tools:sdk` section may shadow the global default before dispatch, and a listener may remove or replace either contribution. The waterfall's returned assembly is final, so whoever changes these inputs owns preserving a viable Code Mode protocol when the deployment expects Code Mode to remain usable; no restoration pass overrides deliberate composition.
 
@@ -48,7 +48,7 @@ Under `'code'` and `'both'` the registry owns `run_code` as a reserved presentat
 
 **Sub-call contexts are deferred through the parent.** Injecting inside `run_code` would break parent call/result adjacency, so `ToolRunContext.deferContext()` collects every sub-result `additionalContexts` entry in dispatch order. The registry carries that array even when the program later throws, and the loop appends each entry only after the outer result and every sibling result in the step. An outer post-execute block discards tool-deferred entries and exposes only contexts explicitly attached by the blocking decision.
 
-**Concurrency is bounded, not serialized.** Each run owns a dispatch queue that starts calls strictly in submission order and classifies each one through `registry.executionMode`, the same fail-closed `isConcurrencySafe` contract the native loop uses. Consecutive parallel-classified calls overlap up to `maxParallelSubCalls` (default 10; `1` restores serial dispatch); an exclusive call drains the pool and runs alone. Settlement abandons queued calls that have not started. This note shipped the serialized placeholder; the [live-parallel Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) owns the scheduler that replaced it.
+**Concurrency is serialized.** Each run owns a dispatch queue, so even `Promise.all` executes tool calls in submission order. Settlement abandons queued calls that have not started. Parallelism requires per-tool concurrency-safety metadata.
 
 **Presentation.** `run_code`'s render intent is decided here per the [render-intent Agent Note](../architecture/2026-07-02-tool-render-intent-union.md): `presentCall` creates a `generic` card with `kind: 'execute'`, the program text as its title, and the same program text as `rawInput`; `run_code` intentionally declares no `presentResult`, so the TUI and host/client runtime (Web) complete that card through their generic raw-content fallback using the final durable `tool/result.content`, including captured logs plus the returned value, failure, or post-policy spill preview. This is not a `terminal` card: that card's semantics are "a shell command in a working directory", which a program is not. See the [result-card completeness note](../../archived/bug-fix/2026-07-20-code-mode-result-card-completeness.md).
 
@@ -64,7 +64,7 @@ Each sub-dispatch appends a log-only `tool/code-dispatch-start` event at pool en
 - `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }` — the runtime exposes each namespace as a global object of async functions inside the program; the optional descriptor asks the runtime to inject a real program-visible rejection class without teaching the seam consumer-specific names. `CodeJsonValue` is this dependency-light seam's structural lossless-JSON type, so binding arguments and resolutions cross the implementation's serialization boundary whole.
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }` — program execution outcomes resolve as the `error` field. `run()` may reject only for caller/seam misuse (for example a duplicate binding namespace); consumers still contain a non-conforming backend rejection at their own error boundary.
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }` — orthogonal outcomes reported independently per [defensive patterns](../../../../docs/defensive-patterns.md); a timed-out run is not an exception, an abort is not a timeout, a lossy completion is not an overflow, and a substrate exit is none of them.
-- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for the first backend; a Python backend says `'python'` and pairs with its own SDK generator on the presentation side) and `isolation` (`'worker-thread'` for the shipped backend; `'process'`, `'container'`, … for future ones). `dsh-tools` accepts any `language` with a registered SDK renderer and `run_code` flavor (TypeScript and Python ship; see the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md)) and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
+- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for both shipped backends; a Python backend would pair with its own SDK generator) and `isolation` (`'worker-thread'` for both shipped backends; the subprocess provider may add a container boundary). `dsh-tools` requires `language === 'typescript'` in the MVP — its codegen emits TS — and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
 
 Requests contain every runtime input; implementations own validated timeout and cap defaults. The registry looks up the optional runtime only when Code Mode is assembled, so native mode does not depend on one. Missing or language-incompatible runtimes fail loudly. Alternate substrates or languages can replace the implementation behind the same seam, paired with the appropriate SDK generator.
 
@@ -79,21 +79,23 @@ Requests contain every runtime input; implementations own validated timeout and
 5. **Enforce independent budgets.** `computeMs` meters worker busy time, allowing slow awaited tools without excusing a hot loop. `maxWallMs` bounds total elapsed time, including unresolved waits. `maxOutputBytes` bounds only the combined serialized outer logs, completion, or diagnostic; intermediate binding values have no byte cap. Expiry, cancellation, and completion terminate the worker, and heap exits or outer overflow are explicit failures.
 6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../../docs/defensive-patterns.md).
 
+`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded base64 JSON frames on raw pipes. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
+
 ### Trust posture
 
-The worker runtime provides containment, not a security boundary: model code can reach Node APIs and has authority comparable to the bash tool. `worker.terminate()` stops the thread but not OS processes it spawned. Code Mode uses the same `tools/pre-execute` policy gate as bash and adds an empty environment, heap limits, a separate isolate, and hard termination of the program itself. Deployments that need a hard multi-tenant boundary need a container-class backend for both code and bash; the runtime's isolation descriptor lets them distinguish that backend.
+The runtimes provide containment, not an independent security boundary: model code can reach Node APIs and has the authority of its mounted execution world. Code Mode uses the same `tools/pre-execute` policy gate as bash and adds an empty worker environment, heap limits, a separate isolate, and hard termination of the program itself. Deployments that need a hard multi-tenant boundary mount container-class filesystem/subprocess providers for both code and bash.
 
 ### What the model sees
 
-The SDK instructs the model to write an async body in the loaded runtime's language (an erasable-TypeScript body by default; a Python `async` body under a Python runtime — see the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md)), call tools through `await tools.name(args)`, catch rejected tool calls when needed, and return or log only the output that should re-enter context. Both flavors state the same contract in their own primitive: independent read-only calls MAY overlap under `Promise.all` (TypeScript) or `asyncio.gather` (Python), mutating calls run alone in submission order, and dependent work sequences with `await`. The declaration prefix can be as large as native schemas, especially in `'both'`, but remains stable for provider caching.
+The SDK instructs the model to write an async erasable-TypeScript body, call tools through `await tools.name(args)`, catch rejected tool calls when needed, and return or log only the output that should re-enter context. Calls remain sequential even under `Promise.all`. The declaration prefix can be as large as native schemas, especially in `'both'`, but remains stable for provider caching.
 
 ## Consequences
 
-Deployments switching to `'code'` must update any native-only `toolOrder`. Assembly listeners own the integrity of any rewritten protocol surface. Sub-dispatch starts in submission order under a bounded overlap pool, while per-call contexts retain their source, envelope, and metadata through the outer result.
+Deployments switching to `'code'` must update any native-only `toolOrder`. Assembly listeners own the integrity of any rewritten protocol surface. Sub-dispatch remains serialized, while per-call contexts retain their source, envelope, and metadata through the outer result.
 
 ## Testing
 
-- **Worker runtime:** Real-worker tests cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger boundaries, compute and wall budgets, hostile binding traffic, empty environment, and disposal to quiescence. A built-package test runs the worker entry under plain Node.
+- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger boundaries, compute and wall budgets, hostile binding traffic, empty environment, and disposal to quiescence. Built-package tests run both the direct worker entry and the filesystem/subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
 - **Registry integration:** Tests cover code generation, all presentation modes, reserved-name and restriction rules, scoped visibility, authoritative assembly rewrites, `toolOrder`, runtime compatibility failures, full-pipeline sub-dispatch, parent-token correlation, serialization, cancellation and queue drain, JSON normalization, error propagation, log events, ordered context deferral across successful and failed programs, outer-block suppression, and HMR cleanup.
 - **With-key e2e:** A real model composes two bash calls in one program; another discovers nested workspace instructions through a Code Mode fs dispatch. The tests verify collapsed request headers, correlated dispatch events, resulting files, deferred context, and model behavior.
 - **Snapshot:** The `code-mode-turn`, `both-mode-turn`, and `code-mode-workspace-context` fixtures pin SDK text, header tool lists, dispatch events, deferred context, and result cards.
@@ -106,7 +108,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Result elision / summarization over native tool-calling.** Addresses only the context-bloat half of the problem: trimming old `tool-result`s is cheap to add as a logged surface replacement under reconstructable requests, but still pays one model round-trip per call and cannot express loops, branches, or joins. Complementary, not competing; it can layer under Code Mode for residual native calls.
 
-**Parallel native dispatch in the loop.** The other answer to round-trip cost at decision time; it was blocked on concurrency-safety metadata and offers no composition either way — it parallelizes calls the model already decided on in one step. Code Mode's queue decision kept the two compatible, and that is how it played out: the metadata landed as `isConcurrencySafe` (the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md)), and native rolling-pool dispatch and per-tool binding parallelism unlocked on the same classifier.
+**Parallel native dispatch in the loop.** The other answer to round-trip cost; still valid future work (the open TODO), still blocked on concurrency-safety metadata, and still no composition — it parallelizes calls the model already decided on in one step. Code Mode's serialized-queue decision keeps the two compatible: when the metadata lands, both native parallel dispatch and per-tool binding parallelism unlock together.
 
 **Always-exclusive (Cloudflare-faithful, no mode).** Rejected for this SDK's primary consumer: a coding agent's bread-and-butter single calls (`bash`, `read`, `edit`) are already ideal as native calls, and forcing every edit through a program taxes the common case. The mode config keeps the faithful form (`'code'`) one line away without imposing it.
 
@@ -118,7 +120,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Risks
 
-**The worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool, containment exceeds it, gating uses the same seams. Deployments needing more need a future `isolation: 'container'` backend — tracked as the seam's designed extension, not a TODO on this design.
+**A worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool and gating uses the same seams. The subprocess implementation can run inside a container-class execution world, but its worker descriptor does not itself claim that boundary.
 
 **`stripTypeScriptTypes` is marked experimental.** It is the same engine (amaro/swc) behind Node's own native `.ts` execution, exposed as an API across this repo's whole engines range. Mitigations: the runtime's unit suite pins the behaviors relied on (position preservation, erasable-only rejection message shape loosely), the call sits behind one private function, and `amaro`/`sucrase` are drop-in replacements if the API shifts. The erasable-only subset is a model-facing contract line, and the error path is a working feedback loop, not a dead end.
 
@@ -126,8 +128,8 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Registry scope growth.** `dsh-tools` absorbs codegen, a tool, a bridge, and an event. Contained by module boundaries inside the package (`ts-types.ts`, `code-mode.ts` beside `schema.ts`/`json-schema.ts`/`presentation.ts`) and by the seam: everything substrate-shaped lives behind `ctx.codeRuntime`.
 
-**Large lossless JSON values can exhaust memory.** Tool bindings snapshot lossless JSON before dispatch and return canonical JSON resolutions whole. The runtime validates both sides of the worker port and applies no per-binding byte cap; structured-clone cost and process or worker memory are the practical bounds. The combined outer-output ledger for logs, the completion value, and a failure diagnostic is the only byte-capped boundary.
+**Large lossless JSON values can exhaust memory.** Tool bindings snapshot lossless JSON before dispatch and return canonical JSON resolutions whole. The direct worker runtime applies no per-binding byte cap; the subprocess runtime bounds each transport frame with `maxFrameBytes`, but repeated or concurrent calls can still consume process or worker memory. The combined outer-output ledger for logs, the completion value, and a failure diagnostic is separately bounded by `maxOutputBytes`.
 
-**Sub-dispatch overlap is bounded by tool safety claims, not by the caller.** A program's `Promise.all` or `asyncio.gather` buys wall-clock parallelism only across calls the tool itself classifies concurrency-safe; a run of exclusive calls still costs its round-trips in sequence, and models may over-expect. Both flavors' SDK instructions state the real contract. This note shipped the serialized placeholder that made the risk absolute; the [live-parallel Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) owns the scheduler and its overlap cap.
+**Serialized-only sub-dispatch.** `Promise.all` gains no wall-clock parallelism yet, only fewer round-trips; models may over-expect. The instructions state it; lifting it is tied to the same concurrency-safety metadata the native parallel-dispatch TODO needs.
 
 **Budget metering reads the event loop, not a flag.** Busy-time polling (`eventLoopUtilization()`) is coarser than an exact CPU meter — a budget expires up to one poll interval late — and its correctness claim ("a pending dispatch cannot pause it") is load-bearing against a hostile program. Both sides are unit-tested (hot loop with a pending decoy dispatch dies at `computeMs`; idle-on-slow-binding survives to `maxWallMs`), and the poll interval is an internal constant, not config — nothing a deployment could mis-tune into a bypass. `maxWallMs` is config, and it reaches `setTimeout`, which clamps a delay above `MAX_TIMER_DELAY_MS` (2^31-1 ms) to 1 ms; a positivity check alone therefore accepts a 25-day ceiling that expires on the first tick and times out every run. The worker runtime range-checks the field at load for that reason. `computeMs` needs no upper bound because it is compared against measured utilization instead of being handed to a timer.
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index ca1bbe9ed3..4ba098d87d 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-在注册表的原生呈现方式下，agent loop（智能体循环）将每个可见能力以 JSON Schema 函数定义的形式通告给模型。`ToolRegistry` 将其 schema 贡献给系统提示词组装，组装结果中的 `tools` 落到协议格式（wire format）上（也记录在请求头日志中），模型每步调用一个 `tool-call` 块，而在本 note 写作时，循环通过 `ctx.tools.execute()` **逐个**分发每次调用（并行工具执行当时还是 open TODO；此后有界的并行分发已经交付——见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)，以及 [docs/architecture.md](../../../../docs/architecture.md) 中的 rolling pool）——且**每一个**中间 `tool-result` 都会在下一次请求时重新进入模型上下文。
+在注册表的原生呈现方式下，agent loop（智能体循环）将每个可见能力以 JSON Schema 函数定义的形式通告给模型。`ToolRegistry` 将其 schema 贡献给系统提示词组装，组装结果中的 `tools` 落到协议格式（wire format）上（也记录在请求头日志中），模型每步调用一个 `tool-call` 块，循环通过 `ctx.tools.execute()` **逐个**分发每次调用（并行工具执行是 `dsh-tools` 和 [docs/architecture.md](../../../../docs/architecture.md) 中明确标注的 open TODO），且**每一个**中间 `tool-result` 都会在下一次请求时重新进入模型上下文。
 
 对于多步工具操作，这种方式 token 开销大且串行。模型无法组合工具——遍历结果集、根据中间值分支、扇出、后处理——每次调用都需要一次完整的模型往返，而每次往返都会把完整的中间结果拖回上下文，不管模型是否需要。
 
@@ -19,8 +19,8 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 三项决策，各自在下方独立小节中展开：
 
 1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
-2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包`@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
-3. **交付的实现是 `@deepseek-ai/dsh-code-runtime-worker`**：每次运行 spawn 一个全新的 Node worker 线程，对模型的 TypeScript 进行 type-strip 后执行，绑定通过消息端口桥接，环境为空，堆/输出/时间上限可配置，并支持硬终止。其信任姿态在设计上等同于 bash——无需 unsafe-acknowledgement flag——因为 harness 已经交付了 `dsh-bash-local`，后者以严格*更高*的环境权限执行模型编写的任意 shell 命令。
+2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
+3. **两种实现保持同一份全新 worker 契约**：`@deepseek-ai/dsh-code-runtime-worker` 在 harness 进程内运行 worker，`@deepseek-ai/dsh-code-runtime-subprocess` 则通过 `ctx.fs` 物化 runner，再通过 `ctx.subprocess` 在另一执行环境中启动。二者都在具有空环境的全新 Node worker 内执行由宿主剥离类型的 TypeScript，并提供桥接绑定、可配置的堆／输出／时间上限和硬终止。其信任姿态在设计上等同于 bash；更强的隔离来自挂载的执行环境。
 
 本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
 
@@ -32,7 +32,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **与 `toolOrder` 的交互，预先说明：** 如果配置的 `systemPrompt.toolOrder` 引用了原生能力名称，在 `mode: 'code'` 下会拒绝所有组装，因为那些名称不在该模式的协议校验范围内。这是正确行为而非 bug：使用 Code Mode 的部署需要更新其 order 配置或移除它。
 
-**SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染所加载运行时语言的声明加固定的使用说明（默认 TypeScript；[语言分发 note](2026-07-31-code-mode-language-dispatch.md) 加入了 Python 与按 `ctx.codeRuntime.language` 选择的渲染器表）。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
+**SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染 TypeScript 声明加固定的使用说明。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
 
 **组装所有权。** `run_code` 和 `tools:sdk` 作为正常的组装输入进入受信任的 `system-prompt/assemble` waterfall。一个 scoped 的 `tools:sdk` 段可以在分发前遮蔽全局默认值，监听器也可以移除或替换任一贡献。waterfall 返回的组装结果是最终的，因此修改这些输入的人有责任在部署期望 Code Mode 可用时保持协议面的完整性；没有恢复 pass 会覆盖有意的组合。
 
@@ -40,7 +40,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 ### run_code 工具与分发桥
 
-在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调性守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
+在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
 
 1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，进入原生契约的分发池（调度设计由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责），以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `tool/code-dispatch-start`/`tool/code-dispatch` 事件对，其中结算侧携带完整渲染后的结果内容。成功时返回工具最终的规范 JSON 值；失败则变为程序可见的 `ToolCallError`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。
 2. **运行程序**：`ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`。运行时接收的是 run 级别的 signal 而非仅调用方的外层 signal，因此外层 run 以任何方式结算都会同时 abort 运行时内部的工作。
@@ -48,7 +48,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **子调用上下文通过父调用延后。** 在 `run_code` 内部注入会破坏父调用/结果的相邻性，因此 `ToolRunContext.deferContext()` 按分发顺序收集每个子结果的 `additionalContexts` 条目。即使程序后来抛出异常，注册表仍携带该数组；循环只在外层结果与步骤中所有兄弟结果之后追加每个条目。外层 post-execute 阻止会丢弃工具延后的条目，只暴露阻止 decision 显式附加的上下文。
 
-**并发是有界的，而非被序列化。** 每次 run 拥有一个分发队列，严格按提交顺序启动调用，并通过 `registry.executionMode` 对每个调用分类——与原生循环所用的 fail-closed `isConcurrencySafe` 契约相同。连续的 parallel 类调用最多重叠 `maxParallelSubCalls` 个（默认 10；设为 `1` 恢复串行分发）；exclusive 类调用会排空池并单独运行。结算时放弃尚未开始的排队调用。本 note 交付的是被序列化的占位实现；取代它的调度器由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
+**并发被序列化。** 每次 run 拥有一个分发队列，因此即使 `Promise.all` 也按提交顺序执行工具调用。结算时放弃尚未开始的排队调用。并行化需要每个工具的并发安全元数据。
 
 **呈现。** `run_code` 的 render intent 按[呈现意图 Agent Note](../architecture/2026-07-02-tool-render-intent-union.md)在此决定：`presentCall` 创建一个 `generic` 卡片，`kind: 'execute'`，以程序文本作为标题，并将同一程序文本作为 `rawInput`；`run_code` 有意不声明 `presentResult`，因此 TUI 和宿主/客户端运行时（Web）会通过通用原始内容回退机制，使用最终持久化的 `tool/result.content` 补全该卡片，其中包括捕获的日志，以及返回值、失败信息或 post-policy 输出落盘预览。这不是 `terminal` 卡片：该卡片的语义是「工作目录中的 shell 命令」，程序不是。参见[结果卡片完整性说明](../../archived/bug-fix/2026-07-20-code-mode-result-card-completeness.md)。
 
@@ -61,39 +61,41 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 `packages/code-runtime/code-runtime/`——`@deepseek-ai/dsh-code-runtime`，仅依赖 `cordis`。一个抽象的 `CodeRuntime extends Service`（`super(ctx, 'codeRuntime')`）加上词汇：
 
 - `CodeRunRequest = { program: string; bindings: CodeBindingNamespace[]; signal?: AbortSignal }`
-- `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }`——运行时将每个命名空间作为程序内部的全局异步函数对象暴露；可选描述符要求运行时注入真正的、程序可见的 reject 类，而无需让 seam 获知消费方专用名称。`CodeJsonValue` 是这个低依赖 seam 的结构化无损 JSON 类型，因此绑定参数与返回值可以完整跨越实现的序列化边界。
+- `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }`——运行时将每个命名空间作为程序内部的全局异步函数对象暴露；可选描述符要求运行时注入真正的、程序可见的 reject 类，而无需让 seam 获知消费方专用名称。`CodeJsonValue` 是这个低依赖 seam 的结构化无损 JSON 类型，因此绑定参数与解析值可以完整跨越实现的序列化边界。
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }`——程序执行失败时，执行 promise 仍会 fulfill，并通过 `error` 字段返回失败结果。只有调用方/seam 误用（例如重复的绑定命名空间）时，`run()` 才会 reject；消费方仍在自己的错误边界处理不合规后端的拒绝。
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }`——按[防御性模式](../../../../docs/defensive-patterns.md)独立报告的正交结果；超时的 run 不是异常，abort 不是超时，有损完成值不是溢出，基底退出也与上述情况相互独立。
-- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——首个后端为 `'typescript'`；Python 后端声明 `'python'`，并在呈现侧配对自己的 SDK 生成器）和 `isolation`（交付的后端为 `'worker-thread'`；未来可为 `'process'`、`'container'` 等）。`dsh-tools` 接受任何注册了 SDK 渲染器与 `run_code` flavor 的 `language`（TypeScript 与 Python 已交付；见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
+- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——两种已交付后端均为 `'typescript'`；Python 后端会配对自己的 SDK 生成器）和 `isolation`（两种已交付后端均为 `'worker-thread'`；子进程提供方可以增加容器边界）。`dsh-tools` 在 MVP 中要求 `language === 'typescript'`——其代码生成输出 TS——否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
 
 请求包含所有运行时输入；实现方拥有经校验的超时和上限默认值。注册表仅在组装 Code Mode 时查找可选的运行时，因此 native 模式不依赖它。缺失或语言不兼容的运行时会大声失败。替代基底或语言可以在同一 seam 背后替换实现，配对相应的 SDK 生成器。
 
 ### worker-thread 运行时
 
-`@deepseek-ai/dsh-code-runtime-worker`，`packages/code-runtime/` 组的第二个包。每次 `run()`：
+`@deepseek-ai/dsh-code-runtime-worker`，`packages/code-runtime/` 组的第二个包（package）。每次 `run()`：
 
-1. **宿主侧 type-strip**，使用 Node 内置的 `stripTypeScriptTypes`（`node:module`；在本仓库的整个引擎范围 `^22.19.0 || >=24.0.0` 内可用，且会保留源码位置，因此运行时错误行号与模型源码一致）。仅剥离模式拒绝不可擦除的语法（`enum`、namespaces）——该拒绝以 `error.kind: 'exception'` 加 Node 的消息返回，SDK 说明写明「仅限可擦除 TypeScript」，模型像处理其他程序错误一样自我修正。语法级失败不会 spawn worker。
+1. **宿主侧 type-strip**，使用 Node 内置的 `stripTypeScriptTypes`（`node:module`；在本仓库的整个引擎范围 `^22.19.0 || >=24.0.0` 内可用，且保持位置不变，因此运行时错误行号与模型源码一致）。仅剥离模式拒绝不可擦除的语法（`enum`、namespaces）——该拒绝以 `error.kind: 'exception'` 加 Node 的消息返回，SDK 说明写明「仅限可擦除 TypeScript」，模型像处理其他程序错误一样自我修正。语法级失败不会 spawn worker。
 2. **每次 run spawn 一个全新 `Worker`**，来自包自身的 bootstrap 模块：`env: {}`（真正为空——比 spawn 命令的 scrubbed-env 规则更严格），`resourceLimits` 来自配置，`stdout`/`stderr` 捕获到 `logs` 而非继承。不做池化，不跨 run 保留状态：程序的世界随 worker 消亡，这使得 run 仅从日志即可重建，状态泄漏不可表达。
 3. **在 bootstrap 中执行**：剥离后的程序成为一个 `AsyncFunction` 的函数体，其参数是绑定全局变量、消费方声明的 reject 类和一个捕获式 `console` shim，因此顶层 `await` 和 `return` 可用。Code Mode 声明 `ToolCallError`，成员属性为 `toolName`；运行时无需硬编码工具即可实体化真正的构造函数。无损 JSON 完成值会精确跨越边界；`undefined` 仍表示缺席，有损值产生 `invalid-output`，过大的外层结果产生 `output-limit`，而不会退化为检查格式化后的字符串替代品。
 4. **通过消息端口桥接绑定**：worker 中的每个绑定函数发送 `{ id, global, name, args }` 并等待回复；宿主根据请求的绑定校验名称、调用、并回复 `{ id, ok, value }` 或 `{ id, ok: false, message }`（宿主侧绑定拒绝变为程序侧 rejection）。worker 侧的命名空间对象通过 `defineProperty` 构建为 null-prototype，因此名为 `__proto__`、`constructor` 或 `toString` 的绑定是普通自有属性，而非原型链碰撞。未知名称、重复 id 和结算后消息被拒绝或忽略——端口协议假设对端是恶意的，因为对端运行的是模型代码。
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
-6. **dispose（资源释放）至完全停稳**：服务自身的 dispose 终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
+6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
+
+`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界 base64 JSON 帧承载绑定通信。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
 
 ### 信任姿态
 
-worker 运行时只能约束程序的运行，而不构成安全边界：模型代码可以访问 Node API，权限与 bash 工具相当。`worker.terminate()` 停止线程但不停止它 spawn 的 OS 进程。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署需要为代码和 bash 都使用容器级后端；运行时的 isolation 描述符让它们能区分该后端。
+这些运行时提供的是隔离，而非独立安全边界：模型代码可以访问 Node API，并拥有挂载的执行环境所授予的权限。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空 worker 环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署应当为代码和 bash 都挂载容器级文件系统／子进程提供方。
 
 ### 模型看到的内容
 
-SDK 指示模型编写一个所加载运行时语言的异步函数体（默认可擦除 TypeScript；Python 运行时下为 Python `async` 函数体——见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。两种 flavor 用各自的原语陈述同一契约：相互独立的只读调用可以在 `Promise.all`（TypeScript）或 `asyncio.gather`（Python）下重叠，有副作用的调用按提交顺序单独运行，有依赖的工作用 `await` 排序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
+SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。即使在 `Promise.all` 下调用仍保持顺序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
 
 ## 后果
 
-切换到 `'code'` 的部署必须更新任何仅限 native 的 `toolOrder`。组装监听器有责任维护任何被重写的协议面的完整性。子分发在有界的重叠池下按提交顺序启动，而每次调用的上下文会通过外层结果保留其 source、信封与元数据。
+切换到 `'code'` 的部署必须更新任何仅限 native 的 `toolOrder`。组装监听器有责任维护任何被重写的协议面的完整性。子分发保持序列化，而每次调用的上下文会通过外层结果保留其 source、信封与元数据。
 
 ## 测试
 
-- **Worker 运行时：** 真实 worker 测试覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界、compute 和 wall 预算、恶意绑定流量、空环境以及 dispose 至完全停稳。一个构建后包测试在纯 Node 下运行 worker 入口。
+- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界、compute 和 wall 预算、恶意绑定流量、空环境以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与文件系统／子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
 - **注册表集成：** 测试覆盖代码生成、所有呈现模式、保留名称和限制规则、scoped 可见性、权威组装重写、`toolOrder`、运行时兼容性失败、完整流水线子分发、parent-token 关联、序列化、取消和队列排空、JSON 规范化、错误传播、日志事件、成功与失败程序中的有序上下文延后、外层阻止抑制以及 HMR（热模块替换）清理。
 - **带密钥 e2e：** 真实模型在一个程序中组合两次 bash 调用；另一个模型通过 Code Mode fs 分发发现嵌套的工作区指令。测试验证折叠的请求头、关联的分发事件、结果文件、延后上下文和模型行为。
 - **快照：** `code-mode-turn`、`both-mode-turn` 和 `code-mode-workspace-context` fixture（测试前置数据）固定 SDK 文本、请求头工具列表、分发事件、延后上下文和结果卡片。
@@ -104,9 +106,9 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 **`node:vm` 作为参考运行时，加固推迟。** 否决：`node:vm` 不是隔离（原型链逃逸可达宿主 realm）且无法中断热循环。worker 线程提供独立 isolate、空环境、`resourceLimits` 和可靠的 `terminate()`，信任等级等同于 bash，因此参考实现和生产实现是同一个包，无需 unsafe-acknowledgement 仪式。
 
-**在原生工具调用上做结果省略/摘要。** 仅解决问题中上下文膨胀这一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
+**在原生工具调用上做结果省略/摘要。** 仅解决问题的上下文膨胀一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
 
-**循环中的并行原生分发。** 决策当时对往返成本的另一个答案；它被并发安全元数据阻塞，且无论如何都不提供组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的队列决策保持了两者兼容，后续也正是这样落地的：元数据以 `isConcurrencySafe` 的形式就绪（见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)），原生 rolling-pool 分发与每工具绑定并行化基于同一个分类器一起解锁。
+**循环中的并行原生分发。** 往返成本的另一个答案；仍是有效的未来工作（open TODO），仍被并发安全元数据阻塞，且仍无组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的序列化队列决策保持两者兼容：当元数据就绪时，原生并行分发和每工具绑定并行化一起解锁。
 
 **始终排他（忠于 Cloudflare，无模式）。** 否决，因为本 SDK 的主要消费方是编码 agent：其日常的单次调用（`bash`、`read`、`edit`）作为原生调用已经是最优的，强制每次编辑都通过程序会给常见场景增加负担。mode 配置让忠实形式（`'code'`）只需一行配置即可启用，而不强加于人。
 
@@ -114,20 +116,20 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 **SDK 中的清洁化标识符别名**（`my-tool` → `my_tool`，Cloudflare 的做法）。否决：`declare const` 上的带引号键使每个名称可达，零别名碰撞逻辑；模型能正常处理 `tools["my-tool"](…)`。
 
-**REPL 风格的持久内核**（状态跨 `run_code` 调用存活）。在 MVP 中否决：跨调用状态对会话日志不可见，破坏了「每个请求是日志的纯函数」这一可重建性保证；每次 run 均使用全新实例则维持了这一保证。内核风格的后端在未来仍可通过同一 seam 表达，配合自己的日志方案。
+**REPL 风格的持久内核**（状态跨 `run_code` 调用存活）。在 MVP 中否决：跨调用状态对会话日志不可见，破坏了「每个请求是日志的纯函数」这一可重建性保证；每次 run 全新保持了这一点。内核风格的后端在未来仍可通过同一 seam 表达，配合自己的日志方案。
 
 ## 风险
 
-**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，约束能力强于它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
+**worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，门禁使用相同的 seam。子进程实现可以在容器级执行环境中运行，但其 worker 描述符本身不声称具备该边界。
 
 **`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的契约线，错误路径是一个可工作的反馈循环，而非死胡同。
 
 **SDK 的提示词成本，尤其在 `'both'` 下。** `.d.ts` 可能与它补充的原生 schema 体量相当；`'both'` 携带两种表示。前缀稳定性 + 提供方缓存摊销了每会话成本；mode 是每部署的；本 Agent Note 不做无条件节省的声明。何时优先使用哪种模式的量化指导明确属于上线后学习。
 
-**注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 共同约束了这一增长：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
+**注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。通过包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 约束：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
 
-**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 返回值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
+**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 解析值。直接 worker 运行时不对单次绑定设置字节数上限；子进程运行时使用 `maxFrameBytes` 限制每个传输帧，但重复或并发调用仍可能消耗进程或 worker 内存。包含日志、完成值和失败诊断的组合外层输出账本另由 `maxOutputBytes` 限制。
 
-**子分发的重叠由工具自身的安全声明限定，而非由调用方决定。** 程序里的 `Promise.all` 或 `asyncio.gather` 只在工具自己分类为并发安全的调用之间换来挂钟并行性；一串 exclusive 调用仍要按顺序付出各自的往返开销，模型可能过度期望。两种 flavor 的 SDK 说明都陈述了真实契约。本 note 交付的是使该风险绝对化的序列化占位实现；调度器及其重叠上限由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
+**仅序列化的子分发。** `Promise.all` 尚未获得挂钟并行性，仅减少往返次数；模型可能过度期望。说明中已声明；解除此限制与原生并行分发 TODO 所需的并发安全元数据绑定。
 
-**预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）是抵御恶意程序的关键。两种情况均有单元测试（带 pending 诱饵分发的热循环会在耗尽 `computeMs` 预算时终止；等待慢速绑定的空闲程序则会持续运行至 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。`maxWallMs` 是配置项，且会传入 `setTimeout`，后者会把超过 `MAX_TIMER_DELAY_MS`（2^31-1 ms）的延迟夹到 1 ms；因此仅有正数校验会放行一个 25 天的上限，它在第一个 tick 就到期，使每次运行都超时。worker 运行时正因如此在加载时对该字段做范围校验。`computeMs` 不需要上界，因为它对照的是实测占用率，而不是交给定时器。
+**预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）对恶意程序是承重的。两侧都有单元测试（带 pending 诱饵分发的热循环在 `computeMs` 处死亡；在慢绑定上空闲的程序存活到 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。`maxWallMs` 是配置项，且会传入 `setTimeout`，后者会把超过 `MAX_TIMER_DELAY_MS`（2^31-1 ms）的延迟夹到 1 ms；因此仅有正数校验会放行一个 25 天的上限，它在第一个 tick 就到期，使每次运行都超时。worker 运行时正因如此在加载时对该字段做范围校验。`computeMs` 不需要上界，因为它对照的是实测占用率，而不是交给定时器。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 451a4ea0d3..6a801df865 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: d7d06dc8517780a37889e4f94dd0b99475dc5432
-2026-07-16-persistent-pty-sessions.zh.md: 84ef8988ba657a87137f904df38e45808d32b483
+2026-07-16-persistent-pty-sessions.md: 65d265b83ab5ad89c2b919364043eb28e75977c7
+2026-07-16-persistent-pty-sessions.zh.md: 6ea92da9a1b2870f3773d84e7f5629bec220dd1c
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index d7d06dc851..65d265b83a 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -23,10 +23,10 @@ The implementation supports interactive shells and line-oriented REPLs on Linux
 | Package | Role | ctx key |
 |---|---|---|
 | `dsh-pty` | `PtyService`, branded `PtySessionId`, backend registry, owner-scoped session contract, and result types | `ctx.pty` |
-| `dsh-pty-local` | [`node-pty`](https://github.com/microsoft/node-pty)-based local backend, platform process inspection, bounded terminal buffer, sandbox resolution, and process-tree supervision | registers a backend on `ctx.pty` |
+| `dsh-pty-local` | Persistent-shell backend over `ctx.subprocess.spawnTerminal()`: readiness, bounded terminal buffers, sandbox resolution, and owner-aware session lifecycle | registers a backend on `ctx.pty` |
 | `dsh-tool-pty` | Six model-facing tools, task-runtime integration for background sends, guidance, and UI render intents | registers on `ctx.tools` |
 
-Idle detection is backend behavior, not a second public seam. A remote or container backend may have authoritative readiness signals that do not resemble local `/proc` inspection; every `PtyBackend` therefore returns the common send result while owning its detection mechanism internally.
+Readiness remains PTY-backend behavior, not a second public seam. The terminal-process provider supplies only substrate facts such as the foreground process group and whether it can prove that group is waiting on input; `dsh-pty-local` combines those facts with prompt and silence evidence into the common send result.
 
 ### Agent ownership and identity
 
@@ -40,12 +40,12 @@ Agent-scope disposal closes registrations first, then awaits quiescent teardown
 
 A registered `shell` backend constrains how a terminal starts; it does not constrain commands typed after startup. `dsh-pty-local` therefore applies two protections before spawning:
 
-- It builds a scrubbed child environment using the same credential-shaped-name policy as `bash-local`, removing ambient `*KEY*`, `*PASSWORD*`, `*SECRET*`, `*TOKEN*`, and harness-managed variables unless an explicit trusted mapping supplies them.
+- It supplies only terminal-specific environment overrides; the mounted subprocess provider applies the shared credential-shaped-name scrub before merging them.
 - It requires `ctx.sandbox` and the shared `ctx.sandboxPolicy`. At spawn, the backend resolves the owner's effective session mode over the deployment default and wraps the shell argv once; that mode and workspace root remain the process boundary for the PTY lifetime. A write that would change the effective `sandbox/mode` is rejected before commit while the owner has any open PTY or unpublished spawn, with an instruction to wait for creation to settle and close those sessions first; same-effective-mode writes remain valid. The pending reservation spans backend setup through publication, so there is no race in which a wider terminal appears after a downgrade. `danger-full-access` is the existing explicit unconfined choice rather than a PTY-specific bypass.
 
 Sandboxing confines local process effects but does not make arbitrary shell input safe: network calls and other external side effects remain governed by deployment policy. Tool descriptions state that PTY sessions are less auditable than one-shot tools and should be used only when persistence or interactive stdin is necessary.
 
-The implementation uses only public `node-pty` capabilities: child PID, `data` and `exit` notifications, `write`, `resize`, and `kill`. It does not assume access to the native master fd or call `waitpid` from TypeScript. Platform process inspectors derive foreground process groups and parent/child identity from `/proc` on Linux and `ps` on macOS.
+The local subprocess terminal primitive uses only public `node-pty` capabilities: child PID, `data` and `exit` notifications, `write`, and `kill`. It does not assume access to the native master fd or call `waitpid` from TypeScript. Platform process inspectors below that primitive derive foreground process groups and parent/child identity from `/proc` on Linux and `ps` on macOS. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns this process/consumer split.
 
 ### Six model-facing tools
 
@@ -92,9 +92,9 @@ Background sends use the existing task completion notice and `task_output` resul
 
 ### Process-tree teardown
 
-The top-level `node-pty` child is the ownership anchor. On close, the backend stops callbacks, snapshots its transitive descendants by parent PID in children-first order, sends `SIGTERM`, waits, rescans for children forked during shutdown, sends `SIGKILL` to the remaining descendant tree, and verifies that every non-zombie descendant left the process table while the shell is still alive. A matching Linux zombie has no executable work and therefore counts as quiescent, allowing shell shutdown to reap or reparent it. Only then does the backend stop the shell with its own TERM/grace/KILL sequence. Every captured PID includes process-start identity so reuse cannot redirect escalation.
+The subprocess terminal handle owns the top-level terminal process and its session. On close it snapshots transitive descendants by parent PID in children-first order, sends `SIGTERM`, waits, rescans for children forked during shutdown, sends `SIGKILL` to the union, and verifies every non-zombie descendant left the process table before stopping the top-level process. A matching Linux zombie has no executable work and therefore counts as quiescent. Every captured PID includes process-start identity so reuse cannot redirect escalation.
 
-Teardown reports root exit and survivor cleanup independently. It does not claim success merely because the shell exited; disposal resolves only after no captured non-quiescent tree member remains or returns a cleanup failure naming the survivors. A failed close is not cached forever: the registry and local session each clear the fence only when it still names that failed attempt, so a later explicit or lifecycle close retries after the external survivor condition changes without disturbing a newer concurrent attempt. Service disposal still clears its backend, reservation, and owner-detacher registries when a close fails. It never broadens ownership to every member of the root PID's POSIX session.
+Teardown reports top-level exit and survivor cleanup independently. The PTY session does not claim success merely because the shell exited: it calls `SubprocessTerminalHandle.terminate()` and awaits whole-session quiescence, propagating a cleanup failure that names survivors. A failed close is not cached forever: the registry and local session clear the fence only when it still names that failed attempt, so a later explicit or lifecycle close retries without disturbing a newer concurrent attempt. Service disposal still clears its backend, reservation, and owner-detacher registries when a close fails.
 
 ### Composition and rollout
 
@@ -108,6 +108,7 @@ plugins:
       mode: workspace-write
       workspaceRoot: .
   '@deepseek-ai/dsh-pty':
+  '@deepseek-ai/dsh-subprocess-local':
   '@deepseek-ai/dsh-pty-local':
     config:
       scrollbackLines: 10000
@@ -141,11 +142,11 @@ The package ships concise tool guidance explaining persistent state, owner isola
 
 **Add persistent mode to `bash`.** Rejected. Returning on readiness rather than process exit, retaining a process tree across calls, and exposing interactive stdin create a different ownership and failure contract.
 
-**Require native master-fd access from `node-pty`.** Rejected. Its public API exposes no master fd. The local backend instead derives foreground groups and descendants from supported OS process metadata and treats unreadable metadata as a detector miss.
+**Require native master-fd access from `node-pty`.** Rejected. Its public API exposes no master fd. The local subprocess terminal adapter derives foreground groups and descendants from supported OS process metadata and treats unreadable metadata as a detector miss.
 
 **Signal every member of the root PID's POSIX session.** Rejected. `node-pty` may expose a helper PID whose session belongs to the launcher, so SID-wide teardown can signal unrelated harness or desktop processes. A PID-identity-fenced descendant tree is narrower and safe by construction.
 
-**Publish `PtyIdleDetector` as a replaceable registry.** Rejected. Only the local backend needs these platform probes, while remote backends may receive readiness over their own protocol. Backend replacement already provides the necessary extension point.
+**Publish `PtyIdleDetector` as a replaceable registry.** Rejected. Substrate-specific foreground facts come from the mounted terminal-process primitive, while prompt/silence readiness remains one private policy in `dsh-pty-local`. The filesystem/subprocess execution-world replacement is the necessary extension point.
 
 **Add a PTY-specific `sleep` tool.** Rejected. `ctx.tasks` already owns bounded waiting, cancellation, completion notices, and model-facing collection. A second general wake mechanism would cross the agent-loop boundary and duplicate that contract.
 
@@ -156,8 +157,8 @@ The package ships concise tool guidance explaining persistent state, owner isola
 ## Verification
 
 - Per-file coverage pins owner fencing, concurrent reservations, unpublished-spawn cancellation and awaited teardown, sandbox-mode change rejection, retriable lifecycle cleanup, readiness tiers, rejection of pre-write stdin waits, the configured handoff grace holding the idle fallback past one poll and its rejection below `pollIntervalMs`, sanitizer carry state, complete UTF-8 bounds, task integration, schemas, and exact render intents.
-- Linux process fixtures cover non-leader and non-main-thread stdin waits, zombie quiescence, unreadable process state, supported syscall tables, unsupported architectures, and false-positive rejection; macOS inspector logic is injected into the same unit suite.
-- Real `node-pty` tests exercise shell state, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT` after deliberately delayed child readiness under scenario-owned timing bounds, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
+- Subprocess process fixtures cover non-leader and non-main-thread stdin waits, zombie quiescence, unreadable process state, supported syscall tables, unsupported architectures, and false-positive rejection; macOS inspector logic is injected into the same unit suite.
+- Real `node-pty` and PTY-consumer tests jointly exercise shell state, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
 - A Loader-driven `cordis.yml` test mounts the real three-package composition. ACP and headless snapshots pin the six schemas, bounded results, and errors through opt-in overlays; TUI snapshots pin terminal and generic card presentation.
 - Package contracts, the architecture map, core data structures, generated catalogs, and the website API describe the same shipped surface.
 - The repository CI-equivalent sequence owns type, lint, coverage, snapshot, documentation, build, hygiene, demo, and built-entry verification.
@@ -172,10 +173,10 @@ The package ships concise tool guidance explaining persistent state, owner isola
 
 **Persistent state can drift from the model's belief.** The model may forget its cwd or active REPL. Session summaries and retained output help recovery, but no prompt can make state persistence deterministic.
 
-**A daemonized descendant can leave the captured tree.** A process that reparents before teardown is no longer discoverable from the `node-pty` root. The implementation accepts that cleanup gap instead of risking SID-wide signals to unrelated processes.
+**A daemonized descendant can leave the local provider's captured tree.** A process that reparents before teardown is no longer discoverable from the `node-pty` root. The local terminal primitive accepts that cleanup gap instead of risking SID-wide signals to unrelated processes.
 
 **A shell can cause external side effects.** Session sandboxing and environment scrubbing reduce local exposure but do not undo pushes, API calls, or messages. Deployments that cannot tolerate those effects must omit PTY or add network policy.
 
 **Process loss destroys terminal state.** In-process sessions do not survive a harness crash or restart, and raw scrollback is not durable. Important work must be committed to files or another durable system.
 
-**`node-pty` is a native dependency.** Installation, supported Node versions, prebuild availability, and platform behavior require built-artifact smokes on every supported OS.
+**`node-pty` is a native dependency of `dsh-subprocess-local`.** Installation, supported Node versions, prebuild availability, and platform behavior require built-artifact smokes on every supported OS.
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 84ef8988ba..6ea92da9a1 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -14,7 +14,7 @@ harness 可以运行前台与后台命令、编辑文件和委派工作，但无
 
 ## 决策
 
-可选的 `packages/pty/` 能力家族提供由 agent 拥有、持久化且面向行式交互的 PTY 会话。它遵循仓库的 [capability pattern](../../implemented/architecture/2026-06-13-capability-seams.md)，与现有命令和文件系统工具并存，并且不修改 `agent-loop`。
+可选的 `packages/pty/` 功能家族提供由 agent 拥有、持久化且面向行式交互的 PTY 会话。它遵循仓库的 [capability pattern](../../implemented/architecture/2026-06-13-capability-seams.md)，与现有命令和文件系统工具并存，并且不修改 `agent-loop`。
 
 当前实现在 Linux 和 macOS 上支持交互式 shell 与行式 REPL。全屏终端应用、按键序列、BEL 触发的控制流、进程丢失后的会话恢复以及跨 agent 共享会话都明确推迟。
 
@@ -23,10 +23,10 @@ harness 可以运行前台与后台命令、编辑文件和委派工作，但无
 | 包 | 角色 | ctx key |
 |---|---|---|
 | `dsh-pty` | `PtyService`、branded `PtySessionId`、后端注册表、按 owner 隔离的会话契约和结果类型 | `ctx.pty` |
-| `dsh-pty-local` | 基于 [`node-pty`](https://github.com/microsoft/node-pty) 的本地后端、平台进程检查、有界终端缓冲、沙箱解析和进程树监管 | 在 `ctx.pty` 上注册后端 |
+| `dsh-pty-local` | 基于 `ctx.subprocess.spawnTerminal()` 的持久 shell 后端：就绪状态、有界终端缓冲、沙箱解析和感知 owner 的会话生命周期 | 在 `ctx.pty` 上注册后端 |
 | `dsh-tool-pty` | 6 个面向模型的工具、后台发送的 task 运行时集成、使用指引和 UI 渲染意图 | 注册到 `ctx.tools` |
 
-idle 检测属于后端行为，不是第二条公共 seam。远程或容器后端可能拥有完全不同于本地 `/proc` 检查的权威就绪信号；因此每个 `PtyBackend` 都返回统一的发送结果，同时在内部拥有自己的检测机制。
+就绪判定仍属于 PTY 后端行为，不是第二条公共 seam。终端进程提供方只提供基底事实，例如前台进程组，以及能否证明该组正在等待输入；`dsh-pty-local` 将这些事实与提示符和静默证据组合成统一的发送结果。
 
 ### agent 所有权与身份
 
@@ -34,18 +34,18 @@ idle 检测属于后端行为，不是第二条公共 seam。远程或容器后
 
 实现不提供插件加载期 auto-start 会话。`terminal_open` 只在 agent 工具调用期间创建会话，此时所有权和所属的事件溯源会话都已确定。未来的声明式启动功能必须通过尚未发布的 agent setup 组合，而不能创建全局共享终端。
 
-agent scope dispose（资源释放）时先关闭注册，再等待全部所属 PTY 完全停稳。未发布的后端 setup 同样是受追踪的生命周期操作：owner 或服务 dispose 会中止服务自有的 signal，等待后端结算与回滚完成后才返回。即使后端 reject，或返回的会话在回滚 close 时失败，调用方取消仍会原样保留其 `AbortSignal.reason`；该清理失败不会替换调用方原因，而会继续受追踪，留待后续 owner 或服务 dispose 处理。由 lifecycle dispose 触发的回滚 close 失败会使 spawn 与该 lifecycle dispose 都 reject，而 `PtyBackendCleanupError` 让后端在不替换调用方取消的前提下，为该 lifecycle dispose 保留自身的启动清理失败。若调用方取消已完成结算，而 dispose 尚未发生，该清理失败会继续作为受追踪的 owner activity 保留，直到后续 owner 或服务 dispose 消费并报告它，因此沙箱模式策略不会把清理失败误判为完全停稳。后端或工具插件 reload 不会遗留会话：所有权持续存放在 `PtyService` 中，直到 agent 结束，与 [`ctx.tasks`](../../../../packages/tasks/tasks/README.md) 的服务持有记录模式一致。服务会先同步把会话预留给一次活跃发送，再返回该操作；后台发送同样会在 task id 对外可见前完成预留。第二次发送会以 `SEND_ACTIVE` 失败，因此输出与取消无法跨越操作所有权。
+agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出。未发布的后端 setup 同样是受追踪的生命周期操作：owner 或服务 dispose 会中止服务自有的 signal，等待后端结算与回滚完成后才返回。即使后端 reject，或返回的会话在回滚 close 时失败，调用方取消仍会原样保留其 `AbortSignal.reason`；该清理失败不会替换调用方原因，而会继续受追踪，留待后续 owner 或服务 dispose 处理。由 lifecycle dispose 触发的回滚 close 失败会使 spawn 与该 lifecycle dispose 都 reject，而 `PtyBackendCleanupError` 让后端在不替换调用方取消的前提下，为该 lifecycle dispose 保留自身的启动清理失败。若调用方取消先于 dispose 完成结算，该清理失败会继续作为受追踪的 owner activity 保留，直到后续 owner 或服务 dispose 消费并报告它，因此沙箱模式策略不会把清理失败误判为静默。后端或工具插件 reload 不会遗留会话：所有权持续存放在 `PtyService` 中，直到 agent 结束，与 [`ctx.tasks`](../../../../packages/tasks/tasks/README.md) 的服务持有记录模式一致。服务会先同步把会话预留给一次活跃发送，再返回该操作；后台发送同样会在 task id 对外可见前完成预留。第二次发送会以 `SEND_ACTIVE` 失败，因此输出与取消无法跨越操作所有权。
 
 ### 安全与进程边界
 
 注册的 `shell` 后端只约束终端如何启动，不约束启动后输入的命令。因此 `dsh-pty-local` 在 spawn 前应用两层保护：
 
-- 它使用与 `bash-local` 相同的凭证形态名称策略构建清洗后的子进程环境，移除环境中的 `*KEY*`、`*PASSWORD*`、`*SECRET*`、`*TOKEN*` 和 harness 管理的变量，除非显式的可信映射提供这些值。
+- 它只提供终端专用的环境覆盖；挂载的子进程提供方先清除名称形似凭据的环境变量，再合并这些覆盖。
 - 它要求 `ctx.sandbox` 和共享的 `ctx.sandboxPolicy`。后端在 spawn 时，以部署默认值为底折叠 owner 的有效 session mode，并只包装一次 shell argv；该 mode 与 workspace root 在 PTY 的整个生命周期中充当进程边界。只要 owner 有任何已打开的 PTY 或尚未发布的 spawn，任何会改变生效 `sandbox/mode` 的写入都会在提交前被拒绝，并提示先等待创建操作结算，再关闭这些会话；不会改变生效模式的写入仍然有效。这项进行中的预留从后端 setup 持续到发布完成，因此不存在降级后又出现权限更宽的终端这一竞态。`danger-full-access` 是现有的显式无约束选择，不另设 PTY 私有 bypass。
 
 沙箱限制本地进程副作用，但不会让任意 shell 输入自动安全：网络调用和其他外部副作用仍由部署策略治理。工具描述会说明 PTY 会话比一次性工具更难审计，只应在确实需要持久状态或交互式 stdin 时使用。
 
-实现只使用 `node-pty` 的公共功能：子进程 PID、`data` 与 `exit` 通知、`write`、`resize` 和 `kill`。它不假设能访问原生 master fd，也不从 TypeScript 调用 `waitpid`。平台进程检查器在 Linux 上通过 `/proc`、在 macOS 上通过 `ps` 推导前台进程组和父子进程身份。
+本地子进程终端原语只使用 `node-pty` 的公共功能：子进程 PID、`data` 与 `exit` 通知、`write` 和 `kill`。它不假设能访问原生 master fd，也不从 TypeScript 调用 `waitpid`。该原语下的平台进程检查器在 Linux 上通过 `/proc`、在 macOS 上通过 `ps` 推导前台进程组和父子进程身份。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)负责定义这种进程／消费方拆分。
 
 ### 6 个面向模型的工具
 
@@ -55,7 +55,7 @@ agent scope dispose（资源释放）时先关闭注册，再等待全部所属
 | `terminal_send` | 发送文本、可选提交 Enter，并等待就绪或注册一个后台任务 | 有界 viewport、等待状态和会话状态；后台模式还返回 `taskId` |
 | `terminal_read` | 从保留的 scrollback 读取一个有界页 | `{ text, totalLines, lineBegin, lineEnd, truncated }` |
 | `terminal_signal` | 向当前前台进程组发送一种允许的信号 | `{ delivered, targetPgid }` |
-| `terminal_close` | 关闭一个会话并等待进程树完全停稳 | `{ killed }` |
+| `terminal_close` | 关闭一个会话并等待进程树静默退出 | `{ killed }` |
 | `terminal_list` | 列出调用方的活会话 | 按 owner 隔离的会话摘要 |
 
 UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
@@ -66,7 +66,7 @@ UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发
 
 当 `run_in_background: true` 时，`dsh-tool-pty` 在 `ctx.tasks` 上注册进行中的发送，并立即返回 `taskId`。生产方把 `maxResultBytes` 写入 task 快照，使 `task_output`、kill 返回的终态状态和完成通知在加上通用元数据后，仍对完整结果执行同一上限。`task_output(wait: true)` 负责等待、读取增量输出并记录最终结果；`task_kill` 会解析当前前台 PGID 并发送真正的 `SIGINT`，即使应用已禁用终端 `ISIG` 也同样如此，且后续升级仍只通过 PTY 后端拥有的 teardown 路径进行。若 task 对外接口不存在，后台模式必须在写入输入前失败。设计不新增 PTY 专用的 `sleep` 工具或通用唤醒 seam。
 
-`terminal_read` 从最新保留行起，朝更早的行分页。后端同时对保留的 scrollback 和返回页载荷执行行数与 UTF-8 字节上限，因此单个超长行无法绕过后端上限；工具随后再限制包含分页与截断元数据的完整渲染页。`truncated` 用于区分保留数据丢失与普通 viewport 增量。
+`terminal_read` 从最新保留行向后分页。后端同时对保留的 scrollback 和返回页载荷执行行数与 UTF-8 字节上限，因此单个超长行无法绕过后端上限；工具随后再限制包含分页与截断元数据的完整渲染页。`truncated` 用于区分保留数据丢失与普通 viewport 增量。
 
 `terminal_signal` 接受闭合集 `SIGINT | SIGTERM | SIGKILL | SIGTSTP | SIGHUP`。后端在执行时解析终端前台进程组。当目标组是顶层 shell 时拒绝 `SIGKILL`，并指引调用方使用 `terminal_close`；进程组解析失败时操作直接失败，而不是向猜测的 PID 发送信号。
 
@@ -76,7 +76,7 @@ UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发
 
 在 Linux 上，检查器从 `/proc/<shellPid>/stat` 读取 shell 的终端前台 PGID，枚举该进程组中的每个进程与线程，并检查它们当前的 syscall。Tier 1 只有观察到 stdin 等待才返回正结果：直接 `read(0)`、获准读取且含 fd 0 的 `select`/`pselect6` 或 `poll`/`ppoll` 参数，或者含 fd 0 的 epoll interest list。终端输入前就已存在的等待并不代表写入后就绪：必须先观察到同一 PGID 脱离该等待，之后再次进入等待才能使该次 send 完成；前台 PGID 发生变化则构成新的证据。无法读取的进程内存和未识别的 syscall 都是 miss，绝不作为正向猜测。架构表只包含对应 Linux UAPI 定义的 syscall number；不支持的架构跳过 Tier 1。
 
-macOS 没有精确 syscall 层。任何前台进程组输出静默都会返回 `inferred_idle`，包括 Python 和 `gdb`；从 `ps` 推导的终端 PGID 只用于发送信号，不作为「只有 shell 才能 idle」的证明。纯进程检查逻辑可注入，并在 Linux 上进行单元测试，同时由 macOS CI job 驱动真实 PTY 和进程表路径。
+macOS 没有精确 syscall 层。任何前台进程组输出静默都会返回 `inferred_idle`，包括 Python 和 `gdb`；从 `ps` 推导的终端 PGID 只用于发送信号，不作为「只有 shell 才能 idle」的证明。纯进程检查逻辑可注入并在 Linux 上完成 unit 覆盖率，同时由 macOS CI job 驱动真实 PTY 和进程表路径。
 
 Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此 sleep 或网络阻塞的命令可能看似 ready。如果此前已经见过 prompt marker，Tier 2 会再等待 `handoffGraceMs`，使恰好落在静默边界上的 bash 前台交接仍然以精确的 `stdin_read` 归因结束，而不是退到较弱的推断；该宽限是由部署方拥有的配置字段，并被校验为至少覆盖一个 `pollIntervalMs`——短于轮询周期的宽限装不下一次就绪轮询，因此不可能改变任何结果。它只约束见过 marker 的 send，代价是这一种情况的交互返回延迟，而不是每一次 send。Tier 3 在 `timeoutMs` 后返回 `timeout`，避免前台工具调用无限占住 agent。结果保留这些区别；调用方可以通过 `ctx.tasks` 等待、向前台组发信号，或从另一个会话排查。
 
@@ -88,13 +88,13 @@ Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此
 
 现有持久化 `tool/call` 与 `tool/result` 事件是模型发送文本和返回给模型的渲染输出的真源。`terminal_open` 通过已记录的工具结果返回 MOTD；前台 `send`/`read`/`list`/`signal`/`close` 结果走同一路径记录。PTY 包不会把原始字节流重复写入自定义会话事件。
 
-后台发送复用现有后台任务完成通知和 `task_output` 结果路径，因此进入后续模型请求的任何输出同样持久化。原始终端字节只作为有界的进程内状态存在，既不持久化也不可恢复。未来的 opt-in transcript（文本记录）sink 必须拥有独立的保留、凭证和隐私契约。
+后台发送复用现有后台任务完成通知和 `task_output` 结果路径，因此进入后续模型请求的任何输出同样持久化。原始终端字节只作为有界的进程内状态存在，既不持久化也不可恢复。未来的 opt-in transcript sink 必须拥有独立的保留、凭证和隐私契约。
 
 ### 进程树 teardown
 
-顶层 `node-pty` 子进程是所有权锚点。关闭时，后端先停止 callback，再按父 PID 以子进程优先顺序捕获其传递子进程、发送 `SIGTERM` 并等待，然后重新扫描关停期间 fork 出的子进程，向剩余子孙进程树发送 `SIGKILL`，并在 shell 仍存活时验证每个非僵尸子孙进程都已离开进程表。身份匹配的 Linux 僵尸进程已无可执行工作，因此视为完全停稳；shell 关闭时会回收它或将其重新挂接给负责回收的父进程。完成这些步骤后，后端才用 shell 自身的 TERM、宽限等待、KILL 序列停止 shell。每个捕获的 PID 都包含进程启动身份，避免 PID 复用把升级信号发给无关进程。
+子进程终端句柄拥有顶层终端进程及其会话。关闭时，它按父 PID 以子进程优先顺序捕获传递后代、发送 `SIGTERM` 并等待，然后重新扫描关停期间 fork 出的子进程，向二者并集发送 `SIGKILL`，并在停止顶层进程前验证每个非僵尸后代都已离开进程表。身份匹配的 Linux 僵尸进程已无可执行工作，因此视为完全停稳。每个捕获的 PID 都包含进程启动身份，避免 PID 复用把升级信号发给无关进程。
 
-teardown 独立报告根进程退出与存活进程清理。它不会只因 shell 退出就声称成功；dispose 只有在已捕获的进程树中不再存在尚未完全停稳的成员后才完成，否则返回清理失败并列出存活者。失败的 close 不会永久缓存：注册表与本地会话各自仅在关闭围栏仍指向该次失败尝试时才将其清除，因此外部存活进程状态改变后，后续的显式 close 或生命周期 close 会重试，且不会干扰较新的并发尝试。即使某个 close 失败，服务 dispose 仍会清空其后端、预留与 owner detacher 注册表。所有权绝不会扩大到根 PID 所属 POSIX 会话的全部成员。
+teardown 独立报告顶层进程退出与存活进程清理。PTY 会话不会只因 shell 退出就声称成功：它会调用 `SubprocessTerminalHandle.terminate()` 并等待整个会话完全停稳，若清理失败则向外传播并列出存活者。失败的 close 不会永久缓存：注册表与本地会话各自仅在关闭围栏仍指向该次失败尝试时才将其清除，因此后续的显式 close 或生命周期 close 会重试，且不会干扰较新的并发尝试。即使某个 close 失败，服务 dispose 仍会清空其后端、预留与 owner detacher 注册表。
 
 ### 组合与推行
 
@@ -108,6 +108,7 @@ plugins:
       mode: workspace-write
       workspaceRoot: .
   '@deepseek-ai/dsh-pty':
+  '@deepseek-ai/dsh-subprocess-local':
   '@deepseek-ai/dsh-pty-local':
     config:
       scrollbackLines: 10000
@@ -141,11 +142,11 @@ plugins:
 
 **给 `bash` 增加持久模式。**拒绝。按就绪而不是进程退出返回、跨调用保留进程树、暴露交互式 stdin 会形成不同的所有权和失败契约。
 
-**要求从 `node-pty` 获取原生 master fd。**拒绝。它的公共 API 不暴露 master fd。本地后端改为从受支持的 OS 进程元数据推导前台组与子孙进程，并把不可读元数据视为 detector miss。
+**要求从 `node-pty` 获取原生 master fd。**拒绝。它的公共 API 不暴露 master fd。本地子进程终端适配器改为从受支持的 OS 进程元数据推导前台组与子孙进程，并把不可读元数据视为 detector miss。
 
 **向根 PID 所属 POSIX 会话的全部成员发送信号。**拒绝。`node-pty` 可能暴露属于启动器会话的 helper PID，因此按 SID 清理可能向无关的 harness 或桌面进程发送信号。带 PID 启动身份校验的子孙进程树范围更窄，其安全边界由结构保证。
 
-**发布可替换注册表 `PtyIdleDetector`。**拒绝。只有本地后端需要这些平台 probe，远程后端可能通过自己的协议接收就绪状态。替换后端已经提供所需扩展点。
+**发布可替换注册表 `PtyIdleDetector`。**拒绝。基底专用的前台事实来自挂载的终端进程原语，提示符／静默就绪判定则仍是 `dsh-pty-local` 内部的一项私有策略。替换文件系统／子进程执行环境就是所需扩展点。
 
 **新增 PTY 专用 `sleep` 工具。**拒绝。`ctx.tasks` 已经拥有有界等待、取消、完成通知和面向模型的收集。第二套通用唤醒机制会跨越 agent loop（智能体循环）边界并重复该契约。
 
@@ -155,9 +156,9 @@ plugins:
 
 ## 验证
 
-- 逐文件测试覆盖并固定 owner 隔离、并发预留、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、对写入前 stdin 等待的拒绝、配置化交接宽限把 idle fallback 顶过一次轮询以及低于 `pollIntervalMs` 时的拒绝、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。
-- Linux 进程 fixture（测试前置数据）覆盖非 leader 与非主线程的 stdin 等待、僵尸进程的完全停稳、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
-- 真实 `node-pty` 测试在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、在由场景掌控的时间界限内先有意延迟子进程就绪，再对 raw mode 前台进程发送 `SIGINT`、忽略 `SIGTERM` 的子进程，以及 dispose 返回后立即完全停稳。
+- 每文件覆盖率固定 owner 隔离、并发预留、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、对写入前 stdin 等待的拒绝、配置化交接宽限把 idle fallback 顶过一次轮询以及低于 `pollIntervalMs` 时的拒绝、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。
+- 子进程 fixture 覆盖非 leader 与非主线程的 stdin 等待、僵尸进程完全停稳、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
+- 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合。ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。
 - 包契约、架构图、核心数据结构、生成目录和 website API 描述同一个已发布接口。
 - 仓库 CI 等价序列负责类型、lint、覆盖率、快照、文档、构建、hygiene、demo 和 built-entry 验证。
@@ -172,10 +173,10 @@ plugins:
 
 **持久状态可能偏离模型认知。**模型可能忘记 cwd 或活跃 REPL。会话摘要和保留输出有助恢复，但任何 prompt 都无法让状态持久化变成确定行为。
 
-**daemonized 子进程可能离开捕获树。**在 teardown 前 reparent 的进程无法再从 `node-pty` 根进程发现。实现接受这个清理缺口，不冒险按 SID 向无关进程发送信号。
+**daemonized 后代进程可能离开本地提供方捕获的进程树。**在 teardown 前 reparent 的进程无法再从 `node-pty` 根进程发现。本地终端原语接受这个清理缺口，不冒险按 SID 向无关进程发送信号。
 
 **Shell 可以造成外部副作用。**会话沙箱和环境清洗降低本地暴露，但无法撤销 push、API 调用或消息发送。无法容忍这些副作用的部署必须省略 PTY 或增加网络策略。
 
 **进程丢失会销毁终端状态。**进程内会话无法跨 harness crash 或 restart 存活，原始 scrollback 也不持久化。重要工作必须提交到文件或其他持久系统。
 
-**`node-pty` 是原生依赖。**安装、支持的 Node 版本、prebuild 可用性和平台行为都需要在每个支持 OS 上运行构建产物冒烟测试。
+**`node-pty` 是 `dsh-subprocess-local` 的原生依赖。**安装、支持的 Node 版本、prebuild 可用性和平台行为都需要在每个支持 OS 上运行 built-artifact smoke。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 1f81974b21..c07e81089c 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -284,6 +284,30 @@ export interface Config {
 
 Source: [`packages/client/hmr/src/index.ts:29`](../packages/client/hmr/src/index.ts)
 
+## `@deepseek-ai/dsh-code-runtime-subprocess`
+
+Requires: `fs` · `subprocess`
+
+```ts config-catalog
+/** Runtime configuration; every execution and bridge bound is deployment-tunable. */
+export interface Config {
+  /** Worker measured event-loop busy-time budget. */
+  computeMs?: number
+  /** Host-observed wall-clock ceiling. */
+  maxWallMs?: number
+  /** Combined serialized outer logs/value/diagnostic cap. */
+  maxOutputBytes?: number
+  /** Worker old-generation heap cap in MiB. */
+  maxOldGenerationSizeMb?: number
+  /** Largest decoded bridge frame, including binding traffic. */
+  maxFrameBytes?: number
+  /** Process-tree TERM-to-KILL grace. */
+  killGraceMs?: number
+}
+```
+
+Source: [`packages/code-runtime/code-runtime-subprocess/src/index.ts:28`](../packages/code-runtime/code-runtime-subprocess/src/index.ts)
+
 ## `@deepseek-ai/dsh-code-runtime-worker`
 
 ```ts config-catalog
@@ -317,7 +341,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:25`](../packages/code-runtime/code-runtime-worker/src/index.ts)
+Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:30`](../packages/code-runtime/code-runtime-worker/src/index.ts)
 
 ## `@deepseek-ai/dsh-compact-basic`
 
@@ -423,7 +447,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/fs/fs-local/src/index.ts:38`](../packages/fs/fs-local/src/index.ts)
+Source: [`packages/fs/fs-local/src/index.ts:40`](../packages/fs/fs-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-fs-sandbox`
 
@@ -906,7 +930,7 @@ Source: [`packages/llm/llm-retry/src/index.ts:46`](../packages/llm/llm-retry/src
 
 ## `@deepseek-ai/dsh-lsp-local`
 
-Requires: `lsp` · `subprocess`
+Requires: `fs` · `lsp` · `subprocess`
 
 ```ts config-catalog
 /** Plugin configuration: provider id → local language-server configuration. */
@@ -942,7 +966,7 @@ export interface LspLocalServerConfig {
 }
 ```
 
-Source: [`packages/lsp/lsp-local/src/index.ts:87`](../packages/lsp/lsp-local/src/index.ts)
+Source: [`packages/lsp/lsp-local/src/index.ts:82`](../packages/lsp/lsp-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-mcp-client`
 
@@ -1048,7 +1072,7 @@ Source: [`packages/plan/plan-mode/src/index.ts:69`](../packages/plan/plan-mode/s
 
 ## `@deepseek-ai/dsh-pty-local`
 
-Requires: `pty` · `sandbox` · `sandboxPolicy`
+Requires: `pty` · `sandbox` · `sandboxPolicy` · `subprocess`
 
 ```ts config-catalog
 /** Public plugin configuration. */
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index edfd046430..7015d39bc8 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -410,7 +410,7 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 
 Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md)
 
-Source: [`packages/fs/fs/src/index.ts:62`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
 
 ### `fs/observed` — emit
 
@@ -430,7 +430,7 @@ Record a successful observation. Listeners must be synchronous recorders: throws
 
 Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md)
 
-Source: [`packages/fs/fs/src/index.ts:71`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
 
 ### `fs/write-intent` — waterfall
 
@@ -450,7 +450,7 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 
 Types: [FsTarget](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md)
 
-Source: [`packages/fs/fs/src/index.ts:54`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
 
 ## `goal/*`
 
diff --git a/docs/core-data-structures/filesystem.i18n.yaml b/docs/core-data-structures/filesystem.i18n.yaml
index 91ac0ed81d..129c5569b9 100644
--- a/docs/core-data-structures/filesystem.i18n.yaml
+++ b/docs/core-data-structures/filesystem.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 docs/core-data-structures/filesystem.md
-filesystem.md: 110c1fd428b15c5094f9dcc94050cad61c324373
-filesystem.zh.md: 010ec22a5d4a29555425c3deede08b317cba7004
+filesystem.md: 50b936bdef7535769f19d6cc0a75eb11eea9a869
+filesystem.zh.md: 61a885203b0718b34b0fd936c318b03c65ce4770
diff --git a/docs/core-data-structures/filesystem.md b/docs/core-data-structures/filesystem.md
index 110c1fd428..50b936bdef 100644
--- a/docs/core-data-structures/filesystem.md
+++ b/docs/core-data-structures/filesystem.md
@@ -12,6 +12,8 @@ Provider source: [`packages/fs/fs/src/types.ts`](../../packages/fs/fs/src/types.
 
 Every operation resolves a user-supplied path to an opaque backend target first. Consumers may display `displayPath`, but must not parse `targetKey` (a branded opaque id) or assume it is a local absolute path.
 
+Consumers that share the filesystem's execution world obtain cross-capability coordinates through the provider instead of interpreting that identity: `processPath(target)` returns the canonical absolute path a subprocess can open, `fileUrl(target)` returns its provider-platform `file:` URI, and `contains(parent, child)` tests canonical identity or descendant containment.
+
 ```ts type-equiv
 /**
  * A path resolved by a backend into a stable identity. `resolve()` produces
@@ -50,7 +52,7 @@ type FsTargetKey = Branded<'FsTargetKey'>
 type FsVersion = Branded<'FsVersion'>
 ```
 
-`stat` returns metadata (never content), or `undefined` when the target is absent. `type` lets the tool reject directories/special files before reading, and `size` lets it choose `readText` vs `streamText` without probing by failure.
+`stat` returns metadata (never content), or `undefined` when the target is absent. `type` lets the tool reject directories/special files before reading, and `size` lets it choose `readText` vs `streamText` without probing by failure. Protocol consumers use `readTextBounded(target, maxBytes)` when size validation and the complete UTF-8 read must remain one backend-owned stable operation; composing `stat` with `readText` would admit growth and replacement races.
 
 ```ts type-equiv
 /**
@@ -256,4 +258,4 @@ type FsErrorCode =
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `readTextBounded`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
diff --git a/docs/core-data-structures/filesystem.zh.md b/docs/core-data-structures/filesystem.zh.md
index 010ec22a5d..6b7642b3f7 100644
--- a/docs/core-data-structures/filesystem.zh.md
+++ b/docs/core-data-structures/filesystem.zh.md
@@ -12,6 +12,8 @@
 
 每个操作首先将用户提供的路径解析为不透明的后端目标。消费方可以显示 `displayPath`，但禁止解析 `targetKey`（一个品牌化的不透明 id），也不得假设它是本地绝对路径。
 
+与文件系统共享执行世界的消费方通过提供方获取跨能力坐标，而不是解释该身份：`processPath(target)` 返回子进程可以打开的规范化绝对路径，`fileUrl(target)` 返回采用提供方平台语法的 `file:` URI，`contains(parent, child)` 则检查规范化身份相等或后代包含关系。
+
 ```ts type-equiv
 /**
  * A path resolved by a backend into a stable identity. `resolve()` produces
@@ -50,7 +52,7 @@ type FsTargetKey = Branded<'FsTargetKey'>
 type FsVersion = Branded<'FsVersion'>
 ```
 
-`stat` 返回元数据（从不返回内容），目标不存在时返回 `undefined`。`type` 让工具在读取前拒绝目录或特殊文件；`size` 让工具无需通过失败探测即可选择 `readText` 还是 `streamText`。
+`stat` 返回元数据（从不返回内容），目标不存在时返回 `undefined`。`type` 让工具在读取前拒绝目录或特殊文件；`size` 让工具无需通过失败探测即可选择 `readText` 还是 `streamText`。当大小校验与完整 UTF-8 读取必须保持为一个由后端负责的稳定操作时，协议消费方使用 `readTextBounded(target, maxBytes)`；组合 `stat` 与 `readText` 会容许文件增长与替换竞态。
 
 ```ts type-equiv
 /**
@@ -256,4 +258,4 @@ type FsErrorCode =
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。生成的 wiring 目录在 [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam) 中展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`readTextBounded`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。生成的 wiring 目录在 [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam) 中展示确切的 `ctx.fs` 签名。
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index 5d59f6fd16..fca7947aae 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: 8189795c5acf2fc1882d9e5bc1c006f49c327e2f
-subprocess.zh.md: 370a1a05807eefbe09a896ea8bcca1e4ab0a6b83
+subprocess.md: eae497530ff54a7a259c23a2d0f665f3313488f5
+subprocess.zh.md: c3504ef7cd42448a15341f7f92d0f309a6216de1
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index 8189795c5a..c866276b8e 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -2,9 +2,13 @@
 
 English | [中文](subprocess.zh.md)
 
-The subprocess seam is split across interface ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and implementation ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its consumers are other capability seams and out-of-process backends — the [bash executor family](bash.md) (collect-mode batch output), the LSP host (piped protocol streams + a collected stderr tail), and the ACP subagent backend (piped protocol streams + inherited stderr). This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
+The subprocess seam is split across interface ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and implementation ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its consumers are other capability seams and out-of-process backends: the [bash executor family](bash.md) uses collected batch output, the LSP and Code Runtime hosts use raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
 
-Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts)
+Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) and [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
+
+## Execution-world coordinates
+
+One provider's `cwd`, `runtimeRoot`, executable paths, ordinary processes, and terminal sessions inhabit the same path and process namespace as the mounted filesystem provider. `resolveExecutable(command, env?, signal?)` verifies absolute executable paths or resolves bare names through the provider's scrubbed `PATH` plus deliberate overrides. Consumers use `runtimeRoot` for private materialized helpers and never assume a host path exists in that world.
 
 ## Managed environment namespace and captured output
 
@@ -234,6 +238,12 @@ interface SubprocessOutcome {
 }
 ```
 
+## Terminal-process primitive
+
+`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns raw UTF-8 byte transport, foreground-process-group inspection and signalling, TERM-to-KILL cleanup, and whole-session quiescence. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
+
+The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, `terminate`, and `waitForExit`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam).
+
 ## Service behavior
 
-The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines `spawn` only; [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) is the local implementation (detached trees, per-disposition wiring, credential scrub, terminate-and-join disposal). See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the seam contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for the mechanics.
+The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) implements them with temporary runtime storage, detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the interface contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 370a1a0580..c3504ef7cd 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -1,14 +1,18 @@
-# 子进程
+# 进程管理器
 
 [English](subprocess.md) | 中文
 
-子进程 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式（collect）的批量输出，LSP 主机使用管道化的协议流 + 收集的 stderr 尾部，ACP（Agent Client Protocol）subagent 后端则使用管道化的协议流 + inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
+进程管理器 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式的批量输出，LSP 与 Code Runtime 主机使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用管道化 ndjson 加 inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
 
-源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts)
+源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) 与 [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
+
+## 执行世界坐标
+
+一个提供方的 `cwd`、`runtimeRoot`、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。消费方使用 `runtimeRoot` 存放私有物化辅助程序，绝不假设该执行世界中存在某条宿主路径。
 
 ## 受管环境命名空间与捕获的输出
 
-`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的字符串条目形式到达，而显式的 `undefined` tombstone 会删除普通环境中已有的值。每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
+`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的条目形式到达，每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
 
 ```ts type-equiv
 /** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
@@ -32,7 +36,7 @@ interface CollectedOutput {
 }
 ```
 
-## Node 风格的 stdio 处置方式（disposition）
+## Node 形状的 stdio 处置方式（disposition）
 
 每条流的处置方式都显式给出，由各消费方自行选择：原始管道用于协议分帧（LSP JSON-RPC、ACP ndjson），inherit 用于直通的诊断输出，收集模式用于有界的批量输出；其中 spill 文件是可选的，因此诊断尾部（语言服务器的 stderr）可以只在内存中缓冲，不留下任何文件。
 
@@ -84,7 +88,7 @@ interface SubprocessStdio {
 
 ## 完全显式的 spawn spec
 
-该 seam 不应用任何默认值：每项处置方式、限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的子进程服务默认值决定。`argv` 绝不经过 shell 解释。
+该 seam 不应用任何默认值：每项处置方式、限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的进程管理器默认值决定。`argv` 绝不经过 shell 解释。
 
 ```ts type-equiv
 /**
@@ -101,11 +105,10 @@ interface SubprocessSpawnSpec {
   /** Per-stream stdio dispositions. */
   stdio: SubprocessStdio
   /**
-   * Positive finite grace period in milliseconds, no greater than
-   * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation
-   * and for draining still-open collected pipes after the process exits (an
-   * inherited descriptor held by a surviving descendant cannot hold the
-   * outcome open indefinitely).
+   * Grace period in milliseconds for the {@link SubprocessHandle.terminate}
+   * escalation and for draining still-open collected pipes after the process
+   * exits (an inherited descriptor held by a surviving descendant cannot hold
+   * the outcome open indefinitely).
    */
   graceMs: number
   /**
@@ -116,18 +119,19 @@ interface SubprocessSpawnSpec {
   signal?: AbortSignal | undefined
   /**
    * Explicit environment entries merged onto the implementation's scrubbed
-   * parent base (see `scrubbedParentEnv`), with no namespace validation. A
-   * string is a deliberate caller opt-in, so a forwarded credential-shaped
-   * entry or current `DSH_*` fact survives the scrub; `undefined` is a
-   * tombstone that removes an ordinary ambient entry from the child.
+   * parent base (see `scrubbedParentEnv`), with no namespace validation:
+   * every entry is a deliberate caller opt-in, so a forwarded
+   * credential-shaped entry or a current `DSH_*` fact survives precisely
+   * because this layer merges after the scrub that drops its ambient
+   * namesake.
    */
-  env?: NodeJS.ProcessEnv | undefined
+  env?: Record<string, string> | undefined
 }
 ```
 
 ## 句柄：流、读取器与以进程树为范围的终止
 
-spawn 会立即返回一个活动句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树。这足以让消费方构建自己的拆卸阶梯；ACP 后端的 `disposeAcpChild` 以 stdin EOF 开始，即为仓库内模板。
+spawn 会立即返回一个实时句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树——这足以让消费方构建自己的拆卸阶梯（ACP 后端以 stdin EOF 打头的 `disposeAcpChild` 即是模板）。
 
 ```ts type-equiv
 /**
@@ -234,6 +238,12 @@ interface SubprocessOutcome {
 }
 ```
 
+## 终端进程原语
+
+`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责原始 UTF-8 字节传输、前台进程组检查与信号发送、TERM→KILL 清理，以及整个会话的完全停稳。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
+
+终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground`、`terminate` 和 `waitForExit`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam)中。
+
 ## 服务行为
 
-抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 只定义 `spawn`；[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 是本地实现（detached 进程树、按处置方式接线的流、凭据清除、先终止再等待退出的 dispose（资源释放））。seam 契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，具体机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以临时运行时存储、detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
diff --git a/knip.json b/knip.json
index ede8b2c738..20bcb5ff2d 100644
--- a/knip.json
+++ b/knip.json
@@ -383,6 +383,16 @@
         "tests/**/*.ts"
       ]
     },
+    "packages/code-runtime/code-runtime-subprocess": {
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
+    },
     "packages/llm/llm-deepseek": {
       "entry": [
         "tests/**/*.spec.ts",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 8aa9b92b91..c5be7e67d6 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 229feae568ba6e40a9c633696097eff46fd5bc95
-README.zh.md: b84aef020a7e3edf305df709d399fbc7b093b6a3
+README.md: 7fcd98bd19ca3291f0472af57841f2f763bb346f
+README.zh.md: 7c4aed9b343ec57001883e094ea3dd0d73e2a920
diff --git a/packages/README.md b/packages/README.md
index 229feae568..a711e4d303 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -19,7 +19,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: runtime seam plus local worker and filesystem/subprocess backends | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
 | [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index b84aef020a..41380317f8 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -19,7 +19,7 @@
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：运行时 seam、本地 worker 后端及文件系统／进程管理后端 | 产品：稳定表面 |
 | [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
 | [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
 | [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index 590b79dcd1..3de3bc622e 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -34,7 +34,7 @@ Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at
 
 Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local and session-owned JSON boundaries both flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. The repository-wide requirement to exercise this published entry path belongs to the [testing policy](../../../docs/testing.md).
 
-The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
+The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The `./runtime-host` subpath shares type stripping, binding validation/dispatch, lossless JSON transport, and output accounting with sibling worker-based implementations; it is implementation support, not a plugin. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers remain source-private.
 
 ## Model Experience
 
diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
new file mode 100644
index 0000000000..334bd82e38
--- /dev/null
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -0,0 +1,222 @@
+/** Shared host mechanics for local and subprocess-hosted TypeScript worker runtimes. */
+
+import { stripTypeScriptTypes } from 'node:module'
+import type {
+  CodeBindingNamespace,
+  CodeJsonValue,
+  CodeRunFailure,
+  CodeRunRequest,
+  CodeRunResult,
+} from '@deepseek-ai/dsh-code-runtime'
+import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
+import { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
+import type { WorkerJsonWire } from './worker-json.ts'
+
+/** Smallest cap that can represent an empty log array and failure message. */
+export const MIN_RUNTIME_OUTPUT_BYTES = 4
+
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+const RESERVED_WORDS = new Set([
+  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
+  'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in',
+  'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
+  'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface', 'package',
+  'private', 'protected', 'public', 'arguments', 'eval',
+])
+const RESERVED_ERROR_PROPERTIES = new Set(['name', 'message', 'stack'])
+const STRIP_WRAP = { prefix: 'async function __dsh_program__() {\n', suffix: '\n}' } as const
+
+/** One validated binding call received from an isolated worker. */
+export interface RuntimeBindingCall {
+  /** Correlation id supplied by the isolated worker. */
+  readonly id: number
+  /** Injected namespace global. */
+  readonly global: string
+  /** Declared namespace function. */
+  readonly name: string
+  /** Untrusted lossless-JSON wire payload. */
+  readonly args: unknown
+}
+
+/** One host reply to an isolated worker binding call. */
+export type RuntimeBindingReply =
+  | { readonly type: 'reply'; readonly id: number; readonly ok: true; readonly value: WorkerJsonWire }
+  | { readonly type: 'reply'; readonly id: number; readonly ok: false; readonly message: string }
+
+/**
+ * Render an unknown thrown value without assuming it is an Error.
+ * @param error - thrown or rejected value.
+ * @returns the caller-facing diagnostic text.
+ */
+export function runtimeErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Strip erasable TypeScript while preserving the program's body coordinates.
+ * @param program - model-written async-function body.
+ * @returns JavaScript source with the wrapper removed.
+ */
+export function stripRuntimeProgram(program: string): string {
+  const stripped = stripTypeScriptTypes(STRIP_WRAP.prefix + program + STRIP_WRAP.suffix)
+  return stripped.slice(STRIP_WRAP.prefix.length, stripped.length - STRIP_WRAP.suffix.length)
+}
+
+/**
+ * Validate binding globals and typed-error declarations shared by worker runtimes.
+ * @param request - code-runtime request carrying the namespaces.
+ * @param implementationName - package name used in seam-misuse diagnostics.
+ * @returns namespaces indexed by their injected global.
+ */
+export function validateRuntimeBindings(
+  request: CodeRunRequest,
+  implementationName: string,
+): Map<string, CodeBindingNamespace> {
+  const bindings = new Map<string, CodeBindingNamespace>()
+  for (const namespace of request.bindings) {
+    if (!IDENTIFIER.test(namespace.global) || RESERVED_WORDS.has(namespace.global)) {
+      throw new Error(`${implementationName}: binding global ${JSON.stringify(namespace.global)} is not a usable identifier`)
+    }
+    if (namespace.global === 'console' || bindings.has(namespace.global)) {
+      throw new Error(`${implementationName}: duplicate binding global ${JSON.stringify(namespace.global)}`)
+    }
+    bindings.set(namespace.global, namespace)
+  }
+
+  const errorClassNames = new Set<string>()
+  for (const namespace of request.bindings) {
+    const descriptor = namespace.errorClass
+    if (descriptor === undefined) continue
+    if (!IDENTIFIER.test(descriptor.name) || RESERVED_WORDS.has(descriptor.name)) {
+      throw new Error(`${implementationName}: binding error class ${JSON.stringify(descriptor.name)} is not a usable identifier`)
+    }
+    if (descriptor.name === 'console' || bindings.has(descriptor.name) || errorClassNames.has(descriptor.name)) {
+      throw new Error(`${implementationName}: duplicate injected global ${JSON.stringify(descriptor.name)}`)
+    }
+    if (descriptor.memberNameProperty.length === 0 || RESERVED_ERROR_PROPERTIES.has(descriptor.memberNameProperty)) {
+      throw new Error(`${implementationName}: binding error member property ${JSON.stringify(descriptor.memberNameProperty)} is not usable`)
+    }
+    errorClassNames.add(descriptor.name)
+  }
+  return bindings
+}
+
+/**
+ * Resolve one untrusted worker call through a declared host binding.
+ * @param call - parsed call envelope from the isolated worker.
+ * @param bindings - namespaces returned by {@link validateRuntimeBindings}.
+ * @returns a lossless-JSON success or stable rejection reply.
+ */
+export async function invokeRuntimeBinding(
+  call: RuntimeBindingCall,
+  bindings: ReadonlyMap<string, CodeBindingNamespace>,
+): Promise<RuntimeBindingReply> {
+  const functions = bindings.get(call.global)?.functions
+  const fn = functions !== undefined && Object.hasOwn(functions, call.name) ? functions[call.name] : undefined
+  if (typeof fn !== 'function') {
+    return { type: 'reply', id: call.id, ok: false, message: `unknown binding ${JSON.stringify(`${call.global}.${call.name}`)}` }
+  }
+  const args = decodeWorkerJson(call.args)
+  if (args === undefined) {
+    return { type: 'reply', id: call.id, ok: false, message: 'binding arguments must be lossless JSON' }
+  }
+  try {
+    const resolved = await fn(args)
+    let value: CodeJsonValue | undefined
+    try {
+      value = snapshotCodeJsonValue(resolved)
+    } catch {
+      value = undefined
+    }
+    if (value === undefined) {
+      return { type: 'reply', id: call.id, ok: false, message: 'binding resolution must be lossless JSON' }
+    }
+    return { type: 'reply', id: call.id, ok: true, value: encodeWorkerJson(value) }
+  } catch (error: unknown) {
+    return { type: 'reply', id: call.id, ok: false, message: runtimeErrorMessage(error) }
+  }
+}
+
+/** One run's combined outer-output ledger; binding values never enter it. */
+export class RuntimeOutputLedger {
+  private bytes = 2
+  private entries = 0
+
+  /** @param maxBytes - hard cap for logs plus completion or failure payload. */
+  constructor(private readonly maxBytes: number) {}
+
+  /**
+   * Admit one exact log entry.
+   * @param text - candidate log entry.
+   * @param sink - ordered retained log list.
+   * @returns false when the hard cap was crossed.
+   */
+  admit(text: string, sink: string[]): boolean {
+    const separatorBytes = this.entries > 0 ? 1 : 0
+    const stringBytes = jsonStringBytesUpTo(text, this.maxBytes - this.bytes - separatorBytes)
+    if (stringBytes === undefined) return false
+    this.bytes += stringBytes + separatorBytes
+    this.entries += 1
+    sink.push(text)
+    return true
+  }
+
+  /**
+   * Finalize a successful completion against the combined cap.
+   * @param logs - retained ordered logs.
+   * @param value - optional lossless-JSON completion.
+   * @returns the completion or output-limit result.
+   */
+  success(logs: string[], value?: CodeJsonValue): CodeRunResult {
+    if (value !== undefined && jsonValueBytesUpTo(value, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
+    return { logs, ...value !== undefined ? { value } : {} }
+  }
+
+  /**
+   * Finalize one failure diagnostic against the combined cap.
+   * @param logs - retained ordered logs.
+   * @param error - structured runtime failure.
+   * @returns the failure or output-limit result.
+   */
+  failure(logs: string[], error: CodeRunFailure): CodeRunResult {
+    if (jsonStringBytesUpTo(error.message, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
+    return { logs, error }
+  }
+
+  /**
+   * Build an explicit output-limit failure with a fitting log prefix.
+   * @param logs - ordered logs observed before the limit.
+   * @returns bounded output-limit result.
+   */
+  limit(logs: string[]): CodeRunResult {
+    const fullMessage = `outer output exceeded ${this.maxBytes} bytes`
+    const messageBytes = fullMessage.length + 2
+    const retained: string[] = []
+    let retainedBytes = 2
+    const logBudget = this.maxBytes - messageBytes
+    for (const text of logs) {
+      const separatorBytes = retained.length > 0 ? 1 : 0
+      const availableBytes = logBudget - retainedBytes - separatorBytes
+      const stringBytes = jsonStringBytesUpTo(text, availableBytes)
+      if (stringBytes !== undefined) {
+        retained.push(text)
+        retainedBytes += stringBytes + separatorBytes
+        continue
+      }
+      const prefix = truncateJsonStringBytes(text, availableBytes)
+      if (prefix.length > 0) {
+        const prefixBytes = jsonStringBytesUpTo(prefix, availableBytes)
+        /* v8 ignore next -- truncateJsonStringBytes guarantees the same bound. */
+        if (prefixBytes === undefined) throw new Error('output ledger produced an oversized log prefix')
+        retained.push(prefix)
+        retainedBytes += prefixBytes + separatorBytes
+      }
+      break
+    }
+    const message = truncateJsonStringBytes(fullMessage, this.maxBytes - retainedBytes)
+    return { logs: retained, error: { kind: 'output-limit', message } }
+  }
+}
+
+export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
+export type { WorkerJsonWire } from './worker-json.ts'
diff --git a/packages/code-runtime/code-runtime-worker/tsconfig.json b/packages/code-runtime/code-runtime-worker/tsconfig.json
index 555b3d161e..340e68e848 100644
--- a/packages/code-runtime/code-runtime-worker/tsconfig.json
+++ b/packages/code-runtime/code-runtime-worker/tsconfig.json
@@ -8,9 +8,6 @@
     "src"
   ],
   "references": [
-    {
-      "path": "../../core/session"
-    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/packages/code-runtime/code-runtime-worker/tsdown.config.ts b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
index 1c40637722..dac6f12a65 100644
--- a/packages/code-runtime/code-runtime-worker/tsdown.config.ts
+++ b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
@@ -1,9 +1,10 @@
 import { defineConfig } from 'tsdown'
 
 /**
- * Build the index and worker as separate single-entry bundles. The sibling `worker.cjs` is loaded
- * by file and must be CommonJS for pkg's VFS Worker hook. A multi-entry build emits an unlisted
- * shared chunk omitted by the package's exact `files` whitelist; separate builds inline it.
+ * Build the plugin, reusable runtime host, and worker as separate bundles. The
+ * sibling `worker.cjs` is loaded by file and must be CommonJS for pkg's VFS
+ * Worker hook. Separate builds inline shared implementation instead of
+ * emitting an unlisted chunk outside the exact `files` whitelist.
  */
 export default defineConfig([
   {
@@ -16,6 +17,16 @@ export default defineConfig([
     dts: false,
     clean: false,
   },
+  {
+    entry: ['lib/types/runtime-host.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
   {
     entry: ['lib/types/worker.js'],
     outDir: 'lib',
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index bb1c20d00a..7014bf517a 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -34,5 +34,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
 - **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)).
-- **Only the worker-thread backend ships** — `'process'`/`'container'` are declared well-known `isolation` values with no implementation; a hard security boundary awaits a container backend.
-- **Intermediate binding values have no byte cap** — implementations remain subject to structured-clone cost and process memory, while a provider or executor may already have imposed its own acquisition bound.
+- **No runtime claims a hard security boundary** — both shipped implementations use fresh worker threads; the filesystem/subprocess backend can place them inside a stronger execution world, but no runtime reports `'container'` today.
+- **Intermediate binding values are implementation-bounded** — the direct worker backend has no per-binding byte cap; the filesystem/subprocess backend bounds each bridge frame, but repeated or concurrent binding traffic remains subject to process memory.
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 0af12596cc..8620c38981 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -75,6 +75,14 @@ class RecordingFileSystem extends FileSystem {
     return { targetKey: FsTargetKey(absolute), displayPath: absolute }
   }
 
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+
+  override fileUrl(target: FsTarget): string { return `file://${target.targetKey}` }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
+
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     if (signal !== undefined) this.signals.push(signal)
     signal?.throwIfAborted()
@@ -109,6 +117,12 @@ class RecordingFileSystem extends FileSystem {
     return this.entries.get(target.targetKey)?.content ?? ''
   }
 
+  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
+    const text = await this.readText(target, signal)
+    if (Buffer.byteLength(text) > maxBytes) throw new Error('too large')
+    return text
+  }
+
   override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     if (signal !== undefined) this.signals.push(signal)
     signal?.throwIfAborted()
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index bf179462ee..c7b6df254e 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -312,6 +312,18 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>',
         jsDoc: '/**\n * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a\n * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence\n * async even though the local backend only normalizes + realpaths.\n *\n * @param path - the path to resolve; relative paths resolve against `opts.cwd`.\n * @param opts - optional cwd override and cancellation signal.\n * @returns the stable target; the same file yields the same `targetKey`.\n */',
       },
+      {
+        signature: 'abstract processPath(target: FsTarget): string',
+        jsDoc: '/**\n * Return the canonical absolute path a subprocess in this filesystem\'s\n * execution world can open. The path is deliberately separate from\n * {@link FsTarget.targetKey}: consumers may pass this value to another OS\n * capability, but must continue treating the target key as opaque.\n * @param target - the resolved target whose process path is required.\n * @returns an absolute path in the backend\'s execution world.\n */',
+      },
+      {
+        signature: 'abstract fileUrl(target: FsTarget): string',
+        jsDoc: '/**\n * Return the canonical `file:` URI for a target in this filesystem\'s\n * execution world. Backends own URI encoding because the host platform may\n * differ from the execution platform.\n * @param target - the resolved target to encode.\n * @returns the target\'s canonical file URI.\n */',
+      },
+      {
+        signature: 'abstract contains(parent: FsTarget, child: FsTarget): boolean',
+        jsDoc: '/**\n * Test canonical containment without exposing or parsing backend target\n * keys. Both targets must come from this provider.\n * @param parent - canonical directory target.\n * @param child - canonical candidate target.\n * @returns true when `child` is `parent` or a descendant of it.\n */',
+      },
       {
         signature: 'abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>',
         jsDoc: '/**\n * Return target metadata, or `undefined` when the target does not exist.\n * @param target - the resolved target to stat.\n * @param signal - aborts the metadata round-trip.\n * @returns metadata only, never content; undefined for an absent target.\n */',
@@ -324,6 +336,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>',
         jsDoc: '/**\n * Read the whole regular text file as a single decoded string.\n * @param target - the resolved target to read.\n * @param signal - aborts the read.\n * @returns the full decoded UTF-8 content.\n */',
       },
+      {
+        signature: 'abstract readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string>',
+        jsDoc: '/**\n * Read one regular UTF-8 text file through a backend-owned stable handle,\n * rejecting before more than `maxBytes` are retained. The size check and\n * bytes read are one operation: a caller must not emulate this with\n * {@link stat} followed by {@link readText}, which admits growth and path\n * replacement races between the two calls.\n * @param target - the resolved target to read.\n * @param maxBytes - positive safe-integer byte ceiling.\n * @param signal - aborts the open/read operation.\n * @returns the complete decoded text when it fits.\n */',
+      },
       {
         signature: 'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>',
         jsDoc: '/**\n * Stream the whole regular text file as decoded text chunks (same text\n * semantics as {@link readText}, for large files). The backend owns\n * cross-chunk UTF-8 decoding and binary rejection so the policy layer never\n * touches raw bytes.\n * @param target - the resolved target to read.\n * @param signal - aborts the stream, including between chunks.\n * @returns the chunk iterable, decoded and validated like {@link readText}.\n */',
@@ -974,10 +990,18 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     key: 'subprocess',
     summary: 'Abstract subprocess service.',
     methods: [
+      {
+        signature: 'abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>',
+        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
+      },
       {
         signature: 'abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle',
         jsDoc: '/**\n * Start one managed child process from a fully-specified spec; this seam\n * applies no defaults.\n * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.\n * @returns the live process handle (streams/readers, signalling, outcome promise).\n */',
       },
+      {
+        signature: 'abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>',
+        jsDoc: '/**\n * Allocate a real terminal and start one owned process session. This is the\n * only non-pipe process primitive: implementations own terminal byte I/O,\n * foreground groups, signals, and complete session-tree cleanup.\n * @param spec - fully specified argv, cwd, environment, dimensions, grace, and cancellation.\n * @returns the live terminal handle after allocation succeeds.\n */',
+      },
     ],
   },
   {
@@ -2879,6 +2903,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SubprocessStdio',
     declaration: 'export interface SubprocessStdio {\n    stdin: SubprocessStdinMode;\n    stdout: SubprocessOutputMode;\n    stderr: SubprocessOutputMode;\n}',
   },
+  {
+    name: 'SubprocessTerminalForeground',
+    declaration: 'export interface SubprocessTerminalForeground {\n    processGroupId: number;\n    inputWaiting: boolean;\n}',
+  },
+  {
+    name: 'SubprocessTerminalHandle',
+    declaration: 'export interface SubprocessTerminalHandle {\n    readonly pid: number;\n    readonly output: Readable;\n    readonly done: Promise<SubprocessOutcome>;\n    write(data: Uint8Array): Promise<void>;\n    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;\n    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;\n    terminate(): void;\n    waitForExit(signal?: AbortSignal): Promise<boolean>;\n}',
+  },
+  {
+    name: 'SubprocessTerminalSignal',
+    declaration: 'export type SubprocessTerminalSignal = \'SIGINT\' | \'SIGTERM\' | \'SIGKILL\' | \'SIGTSTP\' | \'SIGHUP\';',
+  },
+  {
+    name: 'SubprocessTerminalSpawnSpec',
+    declaration: 'export interface SubprocessTerminalSpawnSpec {\n    argv: readonly string[];\n    cwd: string;\n    env?: Record<string, string> | undefined;\n    rows: number;\n    cols: number;\n    graceMs: number;\n    signal?: AbortSignal | undefined;\n}',
+  },
   {
     name: 'SurfaceEvent',
     declaration: 'export type SurfaceEvent = SessionEvent<SurfaceEventType> & {\n    surfaceOp: SurfaceOp;\n};',
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index e435f166ad..c1a381cb81 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: 108d7d862a1dc6307268e2a93fa00789c952e440
-README.zh.md: 8b037cc3192bf6ceb0f0671d62911a8e035db24c
+README.md: b6adabd5744cb2b3dcee78b71815f8e95ba780f1
+README.zh.md: 0841f538932452921d2b0d7d9534f023672f241d
diff --git a/packages/fs/README.md b/packages/fs/README.md
index 108d7d862a..b6adabd574 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -2,16 +2,19 @@
 
 English | [中文](README.zh.md)
 
-The filesystem capability family: provider seam, interchangeable backends, policy, and model-facing tools. All **product** packages.
+The filesystem stack: a provider seam (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the bash-backed discovery tools. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`fs/`](fs/README.md) | Filesystem provider seam and policy-event vocabulary | `ctx.fs` |
-| [`fs-local/`](fs-local/README.md) | Local-filesystem backend | registers `ctx.fs` |
-| [`fs-sandbox/`](fs-sandbox/README.md) | Sandbox-enforcing backend | registers `ctx.fs` |
-| [`fs-policy/`](fs-policy/README.md) | Observed-state and mutation policy | `fs/*` listeners |
-| [`tool-fs/`](tool-fs/README.md) | Model-facing file tools | registers on `ctx.tools` |
-| [`tool-fs-search/`](tool-fs-search/README.md) | Process-backed discovery tools | registers on `ctx.tools` |
-| [`tool-str-replace-editor/`](tool-str-replace-editor/README.md) | Model-facing string-replacement editor | registers on `ctx.tools` |
+| `fs/` | Provider seam: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
+| `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
+| `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
+| `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
+| `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
+| `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-Backends replace one another behind `ctx.fs`; policy and tools consume the seam independently. Discovery remains process-backed instead of expanding the provider contract. Child READMEs own containment, mutation, schema, and timeout details.
+The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas — `fs-sandbox` is the first such replacement (an in-process path fence over the shared sandbox mode; see [the cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+
+## No timeouts on file IO
+
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 8b037cc319..0841f53893 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -1,17 +1,20 @@
-# fs/ - 文件系统能力家族
+# fs/：文件系统能力族
 
 [English](README.md) | 中文
 
-文件系统能力家族：提供方 seam、可互换后端、策略和面向模型工具。这些全是**产品**包。
+文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品** 包。
 
-| 包 | 职责 | ctx key |
+| 包 | 角色 | ctx 键 |
 |---|---|---|
-| [`fs/`](fs/README.md) | 文件系统提供方 seam 和策略事件词汇 | `ctx.fs` |
-| [`fs-local/`](fs-local/README.md) | 本地文件系统后端 | 注册 `ctx.fs` |
-| [`fs-sandbox/`](fs-sandbox/README.md) | 强制执行沙箱的后端 | 注册 `ctx.fs` |
-| [`fs-policy/`](fs-policy/README.md) | 已观察状态和修改策略 | `fs/*` 监听器 |
-| [`tool-fs/`](tool-fs/README.md) | 面向模型的文件工具 | 注册到 `ctx.tools` |
-| [`tool-fs-search/`](tool-fs-search/README.md) | 基于进程的发现工具 | 注册到 `ctx.tools` |
-| [`tool-str-replace-editor/`](tool-str-replace-editor/README.md) | 面向模型的字符串替换编辑器 | 注册到 `ctx.tools` |
+| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
+| `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
+| `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
+| `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
+| `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
+| `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-后端可在 `ctx.fs` 后互相替换；策略和工具独立消费该 seam。发现功能仍由进程提供，不扩展提供方契约。子 README 负责围堵、修改、schema 和超时细节。
+接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema；`fs-sandbox` 是第一个这样的替代实现（基于共享沙箱模式的进程内路径围栏；见[跨能力族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+
+## 文件 I/O 不设超时
+
+`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index cc14be584f..57d2a32f97 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-local/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/fs/fs-local/README.md
-README.md: 6d344fa3fef7f6bda6c0daa50184661156a925a7
-README.zh.md: 4c94de64561d805684f91f02d5b0dfc375f0d04f
+README.md: f5cf2441adcd62e55c6169ceb766f88382e314f5
+README.zh.md: 40f5a83626780bae8f335c80662721bae6cc0b0b
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index 6d344fa3fe..f5cf2441ad 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eight `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the twelve `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
@@ -15,8 +15,9 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 ## Behavior
 
 - **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. `opts.signal` is checked before and after local resolution, while a remote sibling backend may use it to abort its round-trip. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
+- **Execution-world coordinates** — `processPath` exposes the target's canonical host path, `fileUrl` encodes that path through Node's platform-aware URL conversion, and `contains` uses platform path semantics to test identity or descendant containment without consumers parsing `targetKey`.
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
-- **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing.
+- **`readText` / `readTextBounded` / `streamText`** — UTF-8 only. `readText` reads the whole file; `readTextBounded` opens one no-follow, nonblocking handle, verifies it is regular, and retains at most `maxBytes + 1` bytes so growth cannot bypass the cap; `streamText` decodes chunks so a huge file need not be held whole in memory. All reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing; protocol consumers such as the LSP host use the stable bounded operation.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
 - **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
@@ -35,7 +36,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`config.cwd` is not a sandbox** — it is a resolution default, not containment: absolute paths and `..` escape it. Enforce containment with a stricter `ctx.fs` backend or a permission plugin on the `tools/execute` waterfall ([capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences)).
 - **An overwrite reads the whole prior file into memory** — solely as the UI diff basis; bounding that pre-read above a size threshold is deferred (`TODO(overwrite-diff-bound)`).
-- **Version tokens are `mtimeMs:size`** — an external change that preserves both within the filesystem's timestamp granularity defeats the stale guard.
+- **Version tokens depend on filesystem metadata** — they combine device, inode, size, nanosecond mtime, and nanosecond ctime; a storage layer that cannot update any of those facts for a rewrite can still defeat the stale guard.
 - **`editText` holds the whole file (plus the edited copy) in memory** — streaming exists only on the read path.
 - **Binary detection is asymmetric** — reads NUL-sample only the first 8192 bytes while edits scan the whole buffer, so a file with a late NUL reads fine but rejects edits.
 - **The per-target mutation lock is in-process only** — a writer in another process is caught only by the optional version guard, never serialized.
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 4c94de6456..40f5a83626 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持八个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
+`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十二个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
@@ -15,27 +15,28 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 ## 行为
 
 - **`resolve(path, opts?)`**：相对 `path` 在调用方提供 `opts.cwd` 时以该值为基准解析（面向模型的工具会传入调用 agent（智能体）的会话 cwd；见[每会话 cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)），否则以 `config.cwd` 为基准（默认 `process.cwd()`）；绝对 `path` 会忽略两者。`opts.signal` 会在本地解析前后检查，远程同级后端则可以用它中止往返。`targetKey` 是文件的 `realpath`，因此经符号链接到达同一文件的两个输入路径会共享一个身份，写入/编辑落在链接目标上，同时保留链接。尚不存在的路径在父目录存在时使用 realpath 后的父目录加 basename；只有父目录无法解析时才回退到绝对路径。`displayPath` 是绝对但未经解析的路径。
-- **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此异步探测进行期间发生的中止会报告 `FS_ABORTED`，而非已失效的「不存在」结果。
-- **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片流式读取（跨分片解码），因此超大文件无需整体保存在内存中。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）按大小决定调用哪个方法，并负责行窗口逻辑。
+- **执行世界坐标**：`processPath` 公开目标的规范化宿主路径，`fileUrl` 通过 Node 的平台感知 URL 转换对该路径编码，`contains` 则使用平台路径语义检查身份相等或后代包含关系，消费方无需解析 `targetKey`。
+- **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此飞行中的中止会报告 `FS_ABORTED`，而非陈旧的不存在结果。
+- **`readText` / `readTextBounded` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`readTextBounded` 打开一个不跟随符号链接的非阻塞句柄，确认其为普通文件，并最多保留 `maxBytes + 1` 字节，使文件增长无法绕过上限；`streamText` 按分片解码，因此超大文件无需整体保存在内存中。三者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑；LSP 主机等协议消费方使用稳定的有界操作。
 - **`listDir`**：按稳定的 `name.localeCompare()` 顺序列出一层目录。每个条目携带子项 basename、类型、解析后的子目标（`displayPath` 位于所列目录下，`targetKey` 是 realpath 身份）和低成本 stat 元数据（`version`，普通文件另有 `size`）。它绝不会打开或解码文件内容。缺失目标报告 `FS_NOT_FOUND`，文件/特殊文件目标报告 `FS_NOT_DIRECTORY`，已中止调用报告 `FS_ABORTED`，权限失败报告 `FS_PERMISSION_DENIED`，其他列出或子项元数据 I/O 失败报告 `FS_IO_ERROR`。损坏/消失的子项以无元数据的 `other` 返回，但解析子项时出现权限/I/O 失败会让整个列表以结构化 `FsError` 失败。
-- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内。完成写入和 fsync 后，以 rename 覆盖目标。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问策略得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选（OPTIONAL）的：省略时无条件创建或覆盖；`createIfAbsent` 创建缺失目标并拒绝现有目标（`FS_NOT_OBSERVED`）；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
-- **`editText`**：在同一原语之上执行原子式的字面量读取-修改-写入，并通过变更锁按目标串行化。`expected` 防护是可选（OPTIONAL）的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
+- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内。完成写入和 fsync 后，以 rename 覆盖目标。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 创建缺失目标并拒绝现有目标（`FS_NOT_OBSERVED`）；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
+- **`editText`**：在同一原语之上依次执行原子的字面量读取、修改和写入，并通过变更锁按目标串行化。`expected` 防护是可选的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
 
-包根目录的 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
+包根 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
 
 ## 模型体验
 
-通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接产生影响；该消费方在有上限的保留结果中渲染本提供方带行窗口的 UTF-8 内容、变更确认和精确提供方消息，而版本、原子写入机制和目录元数据仍属内部实现。
+通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接产生影响；该消费方把本提供方带行窗口的 UTF-8 内容、变更确认和精确提供方消息渲染为有上限且保留的结果，而版本、原子写入机制和目录元数据保持内部可见。
 
 #### KV Cache 影响
 
 不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
 
 - **`config.cwd` 不是沙箱**：它是解析默认值，而非约束；绝对路径和 `..` 可以逃逸。请使用更严格的 `ctx.fs` 后端或 `tools/execute` waterfall（瀑布式事件）上的权限插件实施约束（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences)）。
 - **覆盖会把整个旧文件读入内存**：只用于 UI diff；在大小阈值之上限制这次预读取的工作延期处理（`TODO(overwrite-diff-bound)`）。
-- **版本 token 是 `mtimeMs:size`**：如果外部变更在文件系统时间戳粒度内保持两者不变，就能绕过陈旧防护。
+- **版本 token 依赖文件系统元数据**：它们组合设备、inode、大小、纳秒级 mtime 和纳秒级 ctime；如果存储层在重写时无法更新其中任何一项事实，仍可能绕过陈旧防护。
 - **`editText` 会把整个文件及编辑后的副本保存在内存中**：只有读取路径支持流式处理。
 - **二进制检测不对称**：读取只对前 8192 字节执行 NUL 采样，编辑则扫描整个 buffer，因此 NUL 出现在后部的文件可以读取，但编辑会被拒绝。
 - **每目标变更锁仅限进程内**：其他进程中的写入方只会被可选版本防护发现，绝不会被串行化。
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index c93e4ddaeb..e95cb14cca 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -6,7 +6,7 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { createReadStream } from 'node:fs'
+import { constants, createReadStream } from 'node:fs'
 import { chmod, lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
 import type { BigIntStats, Dirent, Stats } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
@@ -369,6 +369,77 @@ export async function readWholeText(target: LocalTarget, signal?: AbortSignal):
   return decodeUtf8(raw, 'read', target.displayPath)
 }
 
+/**
+ * Read one regular UTF-8 file through a single no-follow handle, retaining at
+ * most `maxBytes + 1` bytes so a concurrent grow cannot bypass the bound.
+ * @param target - the resolved file to read.
+ * @param maxBytes - positive safe-integer byte ceiling.
+ * @param signal - aborts between handle operations.
+ * @returns the complete decoded text when it fits.
+ */
+export async function readWholeTextBounded(
+  target: LocalTarget,
+  maxBytes: number,
+  signal?: AbortSignal,
+): Promise<string> {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new Error('bounded read maxBytes must be a positive safe integer')
+  }
+  throwIfAborted(signal, 'read')
+  let handle: Awaited<ReturnType<typeof open>>
+  try {
+    handle = await open(
+      target.targetKey,
+      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+    )
+  } catch (error: unknown) {
+    if (isENOENT(error)) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND', { cause: error })
+    if (isPermissionError(error)) throw new FsError(`cannot read "${target.displayPath}": permission denied`, 'FS_PERMISSION_DENIED', { cause: error })
+    throw new FsError(`cannot read "${target.displayPath}" safely: ${errorMessage(error)}`, 'FS_IO_ERROR', { cause: error })
+  }
+  try {
+    throwIfAborted(signal, 'read')
+    const info = await handle.stat()
+    if (!info.isFile()) {
+      throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+    }
+    if (info.size > maxBytes) {
+      throw new FsError(
+        `cannot read "${target.displayPath}": ${info.size} bytes exceeds the ${maxBytes}-byte limit`,
+        'FS_IO_ERROR',
+      )
+    }
+    const chunks: Buffer[] = []
+    let total = 0
+    for (;;) {
+      throwIfAborted(signal, 'read')
+      // Allocate in fixed internal chunks so a permissive deployment cap does
+      // not reserve that entire cap for a small file. Once exactly at the
+      // bound, one final byte detects concurrent growth without retaining it.
+      const remaining = total === maxBytes ? 1 : Math.min(64 * 1024, maxBytes - total)
+      const chunk = Buffer.allocUnsafe(remaining)
+      const { bytesRead } = await handle.read(chunk, 0, chunk.length, total)
+      if (bytesRead === 0) break
+      total += bytesRead
+      if (total > maxBytes) {
+        throw new FsError(
+          `cannot read "${target.displayPath}": file grew past the ${maxBytes}-byte limit while reading`,
+          'FS_IO_ERROR',
+        )
+      }
+      chunks.push(chunk.subarray(0, bytesRead))
+    }
+    throwIfAborted(signal, 'read')
+    const bytes = chunks.length === 1 ? chunks[0] as Buffer : Buffer.concat(chunks, total)
+    if (bytes.subarray(0, BINARY_SAMPLE_BYTES).includes(0)) {
+      throw new FsError(`cannot read "${target.displayPath}": binary file`, 'FS_NOT_TEXT')
+    }
+    return decodeUtf8(bytes, 'read', target.displayPath)
+  } finally {
+    await handle.close()
+  }
+}
+
 /**
  * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
  * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 18433f3f7c..1a266301db 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -5,7 +5,8 @@
  */
 
 import { Context } from 'cordis'
-import { resolve } from 'node:path'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import z from 'schemastery'
 import { FileSystem, FsError, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
@@ -27,6 +28,7 @@ import {
   readForEdit,
   readTextForDiff,
   readWholeText,
+  readWholeTextBounded,
   resolveLocalTarget,
   restoreLineEndings,
   streamWholeText,
@@ -90,6 +92,19 @@ export class LocalFileSystem extends FileSystem {
     return { targetKey: local.targetKey, displayPath: local.displayPath }
   }
 
+  override processPath(target: FsTarget): string {
+    return String(target.targetKey)
+  }
+
+  override fileUrl(target: FsTarget): string {
+    return pathToFileURL(this.processPath(target)).href
+  }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    const path = relative(this.processPath(parent), this.processPath(child))
+    return path === '' || (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path))
+  }
+
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     if (signal?.aborted) throw new FsError('stat aborted', 'FS_ABORTED')
     const info = await probe(target.targetKey)
@@ -111,6 +126,10 @@ export class LocalFileSystem extends FileSystem {
     return readWholeText({ displayPath: target.displayPath, targetKey: target.targetKey }, signal)
   }
 
+  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
+    return readWholeTextBounded({ displayPath: target.displayPath, targetKey: target.targetKey }, maxBytes, signal)
+  }
+
   override streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     return Promise.resolve(streamWholeText({ displayPath: target.displayPath, targetKey: target.targetKey }, signal))
   }
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index 61e2c0e999..02beab7323 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -10,6 +10,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { mkdir, mkdtemp, readFile, realpath, rm, stat, symlink, unlink, utimes, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { Context } from 'cordis'
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
 import { FsVersion } from '@deepseek-ai/dsh-fs'
@@ -85,6 +86,20 @@ describe('resolve', () => {
 
     await expect(pending).rejects.toMatchObject({ code: 'FS_ABORTED' })
   })
+
+  it('projects process paths, file URLs, and canonical containment', async () => {
+    await mkdir(join(dir, 'nested'))
+    await writeFile(join(dir, 'nested', 'file.txt'), 'text')
+    const root = await fs.resolve('.')
+    const child = await fs.resolve('nested/file.txt')
+    const outside = await fs.resolve('..')
+
+    expect(fs.processPath(child)).toBe(await realpath(join(dir, 'nested', 'file.txt')))
+    expect(fs.fileUrl(child)).toBe(pathToFileURL(await realpath(join(dir, 'nested', 'file.txt'))).href)
+    expect(fs.contains(root, root)).toBe(true)
+    expect(fs.contains(root, child)).toBe(true)
+    expect(fs.contains(root, outside)).toBe(false)
+  })
 })
 
 describe('stat', () => {
@@ -203,6 +218,15 @@ describe('readText / streamText', () => {
     expect(await fs.readText(await fs.resolve('a.txt'))).toBe('one\ntwo\nthree')
   })
 
+  it('reads complete text through the stable byte bound', async () => {
+    await writeFile(join(dir, 'bounded.txt'), '€abc')
+    const target = await fs.resolve('bounded.txt')
+    expect(await fs.readTextBounded(target, 6)).toBe('€abc')
+    await expect(fs.readTextBounded(target, 5)).rejects.toThrow('exceeds the 5-byte limit')
+    await expect(fs.readTextBounded(target, 0)).rejects.toThrow('positive safe integer')
+    await expect(fs.readTextBounded(target, 6, AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
+
   it('streams the same text', async () => {
     await writeFile(join(dir, 'a.txt'), 'one\ntwo\nthree')
     const target = await fs.resolve('a.txt')
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index 15588e40b9..2c5fd7a8f4 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -5,7 +5,7 @@
  * policy and lives in `dsh-fs-policy`, so it is not tested here.
  */
 
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { chmod, mkdtemp, readFile, rename, rm, stat, symlink, unlink, writeFile, mkdir, readdir, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -17,6 +17,7 @@ import {
   probeNoFollow,
   readForEdit,
   readWholeText,
+  readWholeTextBounded,
   resolveLocalTarget,
   restoreLineEndings,
   streamWholeText,
@@ -316,6 +317,66 @@ describe('readWholeText', () => {
   })
 })
 
+describe('readWholeTextBounded', () => {
+  it('rejects non-files, binary text, and initial oversize without a full read', async () => {
+    await expect(readWholeTextBounded(localTarget(dir), 10)).rejects.toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
+    await writeFile(join(dir, 'large'), '12345')
+    await expect(readWholeTextBounded(localTarget(join(dir, 'large')), 4)).rejects.toThrow('exceeds the 4-byte limit')
+    await writeFile(join(dir, 'binary'), Buffer.from([0x61, 0x00, 0x62]))
+    await expect(readWholeTextBounded(localTarget(join(dir, 'binary')), 3)).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+  })
+
+  it('detects growth past the bound on the same open handle', async () => {
+    const close = vi.fn(async () => {})
+    const read = vi.fn(async (buffer: Buffer, offset: number, length: number, position: number) => {
+      const bytes = position === 0 ? Buffer.from('abc') : Buffer.from('d')
+      bytes.copy(buffer, offset, 0, Math.min(length, bytes.length))
+      return { bytesRead: Math.min(length, bytes.length), buffer }
+    })
+    vi.resetModules()
+    vi.doMock('node:fs/promises', async (importOriginal) => {
+      const actual = await importOriginal<typeof import('node:fs/promises')>()
+      return {
+        ...actual,
+        open: async () => ({
+          stat: async () => ({ isFile: () => true, size: 3 }),
+          read,
+          close,
+        }),
+      }
+    })
+    try {
+      const isolated = await import('../src/fsio.ts')
+      await expect(isolated.readWholeTextBounded(localTarget('/virtual/growing'), 3))
+        .rejects.toThrow('grew past the 3-byte limit')
+      expect(close).toHaveBeenCalledOnce()
+    } finally {
+      vi.doUnmock('node:fs/promises')
+      vi.resetModules()
+    }
+  })
+
+  it('translates permission and generic open failures', async () => {
+    const failure: { current: Error & { code?: string } } = { current: Object.assign(new Error('denied'), { code: 'EACCES' }) }
+    vi.resetModules()
+    vi.doMock('node:fs/promises', async (importOriginal) => {
+      const actual = await importOriginal<typeof import('node:fs/promises')>()
+      return { ...actual, open: async () => { throw failure.current } }
+    })
+    try {
+      const isolated = await import('../src/fsio.ts')
+      await expect(isolated.readWholeTextBounded(localTarget('/virtual/denied'), 3))
+        .rejects.toMatchObject({ code: 'FS_PERMISSION_DENIED' })
+      failure.current = new Error('open broke')
+      await expect(isolated.readWholeTextBounded(localTarget('/virtual/broken'), 3))
+        .rejects.toMatchObject({ code: 'FS_IO_ERROR' })
+    } finally {
+      vi.doUnmock('node:fs/promises')
+      vi.resetModules()
+    }
+  })
+})
+
 describe('streamWholeText', () => {
   it('streams the whole file as decoded text', async () => {
     const file = join(dir, 'a.txt')
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index ddf57a98d0..4a0e675c0c 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: 6c80cc22f6f28e792c3458df3390b241b51d8202
-README.zh.md: 4772d799221efbfff9667cbc8b9e1df6af07dcff
+README.md: 67079f795c705ab4c9cfa476e0458be04a48c6c8
+README.zh.md: d812a94fab9f4b7e9d15ff78bd1fea3bcc00c0d9
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index 6c80cc22f6..67079f795c 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -2,20 +2,33 @@
 
 English | [中文](README.zh.md)
 
-The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives a backend provides — resolve a path, stat metadata, no-follow path metadata, read/stream text, list directories, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
+The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read bounded or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
-This package is the provider-seam layer of the [filesystem family](../README.md). The [tool](../tool-fs/README.md), [policy](../fs-policy/README.md), and [local](../fs-local/README.md) and [sandboxed](../fs-sandbox/README.md) backends remain separate consumers and implementations; the capability-seam decisions own the split ([foundation](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [filesystem seam](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [provider split](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), [event gate](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)).
+This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
+
+| Layer | Package | Role |
+|---|---|---|
+| tool / executor | `@deepseek-ai/dsh-tool-fs` | model-facing `read`/`write`/`edit` schemas + read windowing + text rendering; reads/writes/edits via `ctx.fs`, dispatches the `fs/*` events |
+| policy | `@deepseek-ai/dsh-fs-policy` | observed-state + read-before-edit + version-guarded write/edit, contributed through the `fs/*` event gate (no service) |
+| provider seam | `@deepseek-ai/dsh-fs` (this) | `ctx.fs`: execution-world paths, text IO, and atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
+| provider | `@deepseek-ai/dsh-fs-local` | the host-filesystem implementation |
+
+A future sandboxed, virtual, or remote backend implements this interface and the policy/tool layers don't change.
 
 ## Service API (`ctx.fs`)
 
-A backend subclasses `FileSystem` and implements eight primitives.
+A backend subclasses `FileSystem` and implements twelve primitives.
 
 | Member | Semantics |
 |---|---|
 | `resolve(path, opts?)` | Resolve a path into a stable `FsTarget` (opaque `targetKey`, `displayPath`). `opts.cwd` is the base a relative `path` resolves against (a caller supplies its session workspace; absolute paths ignore it; omitted ⇒ the backend default), while `opts.signal` aborts a backend round-trip. Async — a remote backend may need I/O. The same file via different paths must yield the same `targetKey`. |
+| `processPath(target)` | Return the canonical absolute path that a subprocess in this provider's execution world can open. This is intentionally distinct from opaque `targetKey`. |
+| `fileUrl(target)` | Return the canonical `file:` URI in the execution world's platform syntax. The backend, not the host process, owns encoding. |
+| `contains(parent, child)` | Test canonical identity/descendant containment without exposing or parsing target keys. Both targets come from this provider. |
 | `stat(target, signal?)` | Return `FsInfo` metadata (`version`, `type`, optional `size`), or `undefined` when the target is absent. Never content. |
 | `lstat(path, opts?, signal?)` | Return `FsPathInfo` metadata without following the final path component when it is a symlink. This is path-shaped so consumers can reject repository-owned symlinks before `resolve` follows them into a target. |
 | `readText(target, signal?)` | Read the whole regular text file as one decoded string. Owns regular-file checks, UTF-8 decoding, binary/NUL rejection (`FS_NOT_TEXT`). |
+| `readTextBounded(target, maxBytes, signal?)` | Read one complete regular UTF-8 file through a backend-owned stable operation, rejecting before retaining more than `maxBytes`. Consumers must not emulate this with `stat` then `readText`, which admits growth and replacement races. |
 | `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here). |
 | `listDir(target, signal?)` | List direct directory children in stable name order. Returns entry names, entry types, resolved child targets, and cheap metadata (`version`/file `size` when available); never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`. Broken/disappeared children may be returned as `other` without metadata; child permission/IO failures fail the whole listing with the same structured codes. |
 | `writeText(target, content, expected?, signal?)` | Atomic create/replace. `expected` is OPTIONAL: omit ⇒ unconditional create-or-overwrite; supply an `FsWriteIntent` (`createIfAbsent`/`replaceIfVersion`) to guard. |
@@ -37,10 +50,6 @@ This package declares three events (see the generated [events catalog](../../../
 
 `FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
 
-## No IO deadline
-
-Filesystem primitives accept an optional `AbortSignal` but arm no deadline. Local IO is only best-effort abortable: a timeout cannot force an in-progress `fsync` or `rename` to stop, so a fixed deadline would promise control the backend cannot provide. Process-backed discovery owns its separate timeout contract.
-
 ## Model Experience
 
 Indirectly, through `dsh-tool-fs`, which renders provider text and errors as bounded, retained filesystem tool results.
@@ -52,6 +61,6 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **Text-only by contract** — backends reject binary/non-UTF-8 content with `FS_NOT_TEXT`; binary-safe operations are a deliberate deferral of [the tool-schemas Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md).
-- **Eight primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
-- **No IO deadline** — cancellation is best-effort at primitive boundaries.
+- **Twelve primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
+- **No IO deadline** — the seam arms no timeout; cancellation is a best-effort optional `AbortSignal` per primitive (the deliberate [fs-family stance](../README.md)).
 - **Resolve-then-operate costs a remote backend two round-trips per tool call** — folding or caching resolution is left to such a backend.
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 4772d79922..d812a94fab 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -2,56 +2,65 @@
 
 [English](README.md) | 中文
 
-**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义后端提供的存储原语，包括路径解析、stat 元数据、不跟随链接的路径元数据、读取/流式读取文本、列出目录、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
+**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、有界或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
 
-本包是[文件系统家族](../README.md)中的提供方 seam 层。[工具](../tool-fs/README.md)、[策略](../fs-policy/README.md)、[本地](../fs-local/README.md)与[沙箱化](../fs-sandbox/README.md)后端分别作为消费方与实现保持独立；能力 seam 决策负责该拆分（[基础](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统 seam](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[提供方拆分](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)、[事件门禁](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）。
+本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
+
+| 层 | 包 | 角色 |
+|---|---|---|
+| 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 `read`/`write`/`edit` schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
+| 政策 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
+| 提供方 seam | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
+| 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
+
+未来的沙箱化、虚拟或远程后端只需实现该接口，政策层和工具层无需改变。
 
 ## 服务 API（`ctx.fs`）
 
-后端继承 `FileSystem` 并实现八个原语。
+后端继承 `FileSystem` 并实现十二个原语。
 
 | 成员 | 语义 |
 |---|---|
 | `resolve(path, opts?)` | 把路径解析为稳定的 `FsTarget`（不透明 `targetKey`、`displayPath`）。`opts.cwd` 是相对 `path` 解析所依据的基准（调用方提供其会话工作区；绝对路径忽略该值；省略时使用后端默认值），`opts.signal` 则中止后端往返。该方法是异步的，因为远程后端可能需要 I/O。经不同路径到达的同一文件必须产生相同 `targetKey`。 |
+| `processPath(target)` | 返回该提供方执行世界中的子进程可以打开的规范化绝对路径。该路径有意与不透明的 `targetKey` 分离。 |
+| `fileUrl(target)` | 返回采用执行世界平台语法的规范化 `file:` URI。编码由后端而非宿主进程负责。 |
+| `contains(parent, child)` | 在不公开或解析目标 key 的情况下，检查规范化身份相等或后代包含关系。两个目标都来自该提供方。 |
 | `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
-| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库自有的符号链接进入目标前拒绝它。 |
+| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
+| `readTextBounded(target, maxBytes, signal?)` | 通过后端自有的稳定操作读取一个完整的普通 UTF-8 文件，在保留超过 `maxBytes` 前拒绝。消费方不得以先 `stat` 再 `readText` 模拟此操作，因为那会容许文件增长与替换竞态。 |
 | `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）。 |
-| `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列出操作失败。 |
+| `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
 | `writeText(target, content, expected?, signal?)` | 原子创建/替换。`expected` 是可选的：省略 ⇒ 无条件创建或覆盖；提供 `FsWriteIntent`（`createIfAbsent`/`replaceIfVersion`）⇒ 添加防护。 |
 | `editText(target, edit, expected?, signal?)` | 字面量编辑。`expected` 是可选的：省略 ⇒ 无条件编辑当前内容；提供 `{ version }` ⇒ 添加防护，并在匹配之前校验。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。应用和写入以原子方式完成，使用同一个变更临界区。 |
 
 无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
 
-## `fs/*` 策略事件
+## `fs/*` 政策事件
 
-本包声明三个事件（见已生成的[事件目录](../../../docs/cordis-catalog/events.md)），使发出方（`@deepseek-ai/dsh-tool-fs`）和策略监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖策略插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（瀑布式事件）（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见已生成的[事件目录](../../../docs/cordis-catalog/events.md)），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
-## 提供方 seam，不是策略层
+## 提供方 seam，不是政策层
 
-`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察策略。
+`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使政策层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不** 负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的政策，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
 
-`editText` 留在该 seam 上，不由策略层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
+`editText` 留在该 seam 上，不由政策层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
 
 ## 词汇
 
 `FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整契约见 `src/types.ts`。
 
-## 无 I/O deadline
-
-文件系统原语接受可选 `AbortSignal`，但不会启动 deadline。本地 I/O 只能尽力取消：超时无法强制进行中的 `fsync` 或 `rename` 停止，因此固定 deadline 会承诺后端无法提供的控制能力。基于进程的发现功能拥有独立的超时契约。
-
 ## 模型体验
 
 通过 `dsh-tool-fs` 间接产生影响；该消费方把提供方文本和错误渲染为有界且保留的文件系统工具结果。
 
 #### KV Cache 影响
 
-不会直接使缓存失效；上述消费方负责请求前缀的任何变化。
+不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
 
 - **契约只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
-- **只有八个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
-- **没有 I/O deadline**：取消只能在原语边界尽力执行。
+- **只有十二个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
+- **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见有意采用的 [fs 能力族立场](../README.md)）。
 - **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。
diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts
index b43fa48c4b..8bb20ece18 100644
--- a/packages/fs/fs/src/index.ts
+++ b/packages/fs/fs/src/index.ts
@@ -1,8 +1,10 @@
 /**
- * Filesystem text-storage provider seam. Backends own stable target identity,
- * text decoding, binary rejection, and atomic mutations. Read windows and
- * observed-state policy stay in consumer and policy plugins; `editText` remains
- * here so version check, literal match, and rewrite share one critical section.
+ * Filesystem provider seam for one execution world. Backends own stable target
+ * identity, process paths and file URIs, containment, stable bounded text
+ * reads, decoding, binary rejection, and atomic mutations. Read windows and
+ * observed-state policy stay in consumer and policy plugins; `editText`
+ * remains here so version check, literal match, and rewrite share one critical
+ * section.
  * @module @deepseek-ai/dsh-fs
  */
 
@@ -83,7 +85,6 @@ export abstract class FileSystem extends Service {
     super(ctx, 'fs')
   }
 
-  /**
   /**
    * The sandbox mode this backend enforces on mutations BY DEFAULT, or
    * `undefined` when it does not confine at all — the capability fact the tool
@@ -111,6 +112,34 @@ export abstract class FileSystem extends Service {
    */
   abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
 
+  /**
+   * Return the canonical absolute path a subprocess in this filesystem's
+   * execution world can open. The path is deliberately separate from
+   * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+   * capability, but must continue treating the target key as opaque.
+   * @param target - the resolved target whose process path is required.
+   * @returns an absolute path in the backend's execution world.
+   */
+  abstract processPath(target: FsTarget): string
+
+  /**
+   * Return the canonical `file:` URI for a target in this filesystem's
+   * execution world. Backends own URI encoding because the host platform may
+   * differ from the execution platform.
+   * @param target - the resolved target to encode.
+   * @returns the target's canonical file URI.
+   */
+  abstract fileUrl(target: FsTarget): string
+
+  /**
+   * Test canonical containment without exposing or parsing backend target
+   * keys. Both targets must come from this provider.
+   * @param parent - canonical directory target.
+   * @param child - canonical candidate target.
+   * @returns true when `child` is `parent` or a descendant of it.
+   */
+  abstract contains(parent: FsTarget, child: FsTarget): boolean
+
   /**
    * Return target metadata, or `undefined` when the target does not exist.
    * @param target - the resolved target to stat.
@@ -143,6 +172,19 @@ export abstract class FileSystem extends Service {
    */
   abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
 
+  /**
+   * Read one regular UTF-8 text file through a backend-owned stable handle,
+   * rejecting before more than `maxBytes` are retained. The size check and
+   * bytes read are one operation: a caller must not emulate this with
+   * {@link stat} followed by {@link readText}, which admits growth and path
+   * replacement races between the two calls.
+   * @param target - the resolved target to read.
+   * @param maxBytes - positive safe-integer byte ceiling.
+   * @param signal - aborts the open/read operation.
+   * @returns the complete decoded text when it fits.
+   */
+  abstract readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string>
+
   /**
    * Stream the whole regular text file as decoded text chunks (same text
    * semantics as {@link readText}, for large files). The backend owns
diff --git a/packages/fs/fs/tests/service.spec.ts b/packages/fs/fs/tests/service.spec.ts
index 19ee033cce..92f1cfc37f 100644
--- a/packages/fs/fs/tests/service.spec.ts
+++ b/packages/fs/fs/tests/service.spec.ts
@@ -19,13 +19,18 @@ import type {
   FsWriteOutcome,
 } from '@deepseek-ai/dsh-fs'
 
-/** A minimal in-memory fake implementing the eight provider primitives. */
+/** A minimal in-memory fake implementing the provider primitives. */
 class FakeFileSystem extends FileSystem {
   files = new Map<string, string>()
 
   override async resolve(path: string): Promise<FsTarget> {
     return { targetKey: FsTargetKey(path), displayPath: path }
   }
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+  override fileUrl(target: FsTarget): string { return `file:///${encodeURIComponent(String(target.targetKey))}` }
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
   override async stat(target: FsTarget): Promise<FsInfo | undefined> {
     const content = this.files.get(target.targetKey)
     if (content === undefined) return undefined
@@ -41,6 +46,11 @@ class FakeFileSystem extends FileSystem {
     if (content === undefined) throw new FsError(`not found: ${target.displayPath}`, 'FS_NOT_FOUND')
     return content
   }
+  override async readTextBounded(target: FsTarget, maxBytes: number): Promise<string> {
+    const content = await this.readText(target)
+    if (Buffer.byteLength(content) > maxBytes) throw new FsError('too large', 'FS_IO_ERROR')
+    return content
+  }
   override async streamText(target: FsTarget): Promise<AsyncIterable<string>> {
     const content = await this.readText(target)
     return (async function* () { yield content })()
@@ -75,6 +85,7 @@ describe('FileSystem provider seam', () => {
     const ctx = new Context()
     await ctx.plugin(FakeFileSystem)
     const fs = ctx.fs as FakeFileSystem
+    expect(fs.sandboxMode).toBeUndefined()
     fs.files.set('a.txt', 'hi')
     const target = await fs.resolve('a.txt')
     expect((await fs.stat(target))?.type).toBe('file')
diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts
index ad01237c2b..f54701246a 100644
--- a/packages/fs/tool-fs/tests/tools.spec.ts
+++ b/packages/fs/tool-fs/tests/tools.spec.ts
@@ -48,6 +48,11 @@ class FakeFs extends FileSystem {
   override async resolve(path: string): Promise<FsTarget> {
     return { targetKey: FsTargetKey(`key:${path}`), displayPath: `/abs/${path}` }
   }
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+  override fileUrl(target: FsTarget): string { return `file://${target.targetKey}` }
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
   override async stat(target: FsTarget): Promise<FsInfo | undefined> {
     this.throwIfArmed()
     const content = this.files.get(target.targetKey)
@@ -62,6 +67,11 @@ class FakeFs extends FileSystem {
   override async readText(target: FsTarget): Promise<string> {
     return this.files.get(target.targetKey) ?? ''
   }
+  override async readTextBounded(target: FsTarget, maxBytes: number): Promise<string> {
+    const content = await this.readText(target)
+    if (Buffer.byteLength(content) > maxBytes) throw new Error('too large')
+    return content
+  }
   override async streamText(target: FsTarget): Promise<AsyncIterable<string>> {
     const content = this.files.get(target.targetKey) ?? ''
     return (async function* () { yield content })()
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index a41b05f148..9919cdaba5 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: 4964d78f1096d1a4bc78fa80c6b5febaf24a5661
-README.zh.md: 93b872002cf1f53cdbb96ff42402bfeb9557575f
+README.md: 7fbdf071735673fb0158f6fa66148be1c644a433
+README.zh.md: e059dbd80b7e38c0e447e54178162316dfd127c7
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index 4964d78f10..7fbdf07173 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -6,8 +6,10 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`lsp/`](lsp/README.md) | LSP provider seam and shared vocabulary | `ctx.lsp` |
-| [`lsp-local/`](lsp-local/README.md) | Local stdio language-server backend | registers providers on `ctx.lsp` |
-| [`tool-lsp/`](tool-lsp/README.md) | Model-facing semantic-navigation tool | registers on `ctx.tools` |
+| `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
+| `lsp-local/` | Generic multi-server stdio backend over `ctx.fs` and `ctx.subprocess` (JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
+| `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
-Providers register semantic capabilities; the tool owns the model-facing contract. The child READMEs document operation, protocol, and presentation details, while the [LSP capability-seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) owns the rationale.
+The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
+
+See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index 93b872002c..e059dbd80b 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -2,12 +2,14 @@
 
 [English](README.md) | 中文
 
-语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方和面向模型的 `lsp` 工具。这些全是**产品**包。
+语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品** 包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`lsp/`](lsp/README.md) | LSP 提供方 seam 和共享词汇 | `ctx.lsp` |
-| [`lsp-local/`](lsp-local/README.md) | 本地 stdio 语言服务器后端 | 在 `ctx.lsp` 上注册提供方 |
-| [`tool-lsp/`](tool-lsp/README.md) | 面向模型的语义导航工具 | 注册到 `ctx.tools` |
+| `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
+| `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
+| `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
-提供方注册语义能力；工具负责面向模型的契约。子 README 记录操作、协议和呈现细节，[LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)负责设计原理。
+接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
+
+设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index b786ec1a60..1504e6f726 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-local/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/lsp/lsp-local/README.md
-README.md: 37676a82fb5d45b40ca86507259aca9509d25a43
-README.zh.md: 9e8b7f4f4395985bdbc29c1d911520b3559d7e0c
+README.md: 2c5ab309f3557ad77696a881b41d164e65bd24fe
+README.zh.md: d4493832964a5ac0d804602c18774bb106ddcbd9
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index 37676a82fb..2c5ab309f3 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -2,18 +2,19 @@
 
 English | [中文](README.zh.md)
 
-A **generic local stdio language-server backend** for `ctx.lsp`. One plugin instance accepts a named server table and registers one isolated provider per entry. This is a generic host, not a language-server catalog or installer — deployments configure commands and mappings explicitly; presets belong in `cordis.yml` overlays.
+A **generic stdio language-server backend** for `ctx.lsp`. One plugin instance accepts a named server table and registers one isolated provider per entry. It reads through `ctx.fs` and launches through `ctx.subprocess`, so the server and source always inhabit the mounted execution world. This is a generic host, not a language-server catalog or installer — deployments configure commands and mappings explicitly; presets belong in `cordis.yml` overlays.
 
 Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export).
 
 ## What it does
 
 - Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes.
-- Lazily single-flights one server process per `(server id, canonical workspace realpath)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
-- Uses a compatibility-first **transient-open** sequence per query: canonicalize and read the source with Node APIs, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
+- Lazily single-flights one server process per `(server id, canonical workspace target)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
+- Uses a compatibility-first **transient-open** sequence per query: resolve and boundedly read the source through `ctx.fs`, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
 - Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel.
 - After protocol shutdown fails, terminates the server's descendant tree through the subprocess seam (POSIX process-group signaling; Windows `taskkill /T /F`). Tree-kill delivery is contained like every group signal — it races server exit — and quiescence is confirmed by the handle's tree-liveness wait rather than by the kill's own outcome.
-- Reads sources through Node filesystem APIs in the subprocess's host namespace — NOT `ctx.fs`, and emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
+- Resolves the server executable, cwd, process, and protocol streams through `ctx.subprocess`; `initialize.processId` is `null` because another machine or PID namespace must not monitor the harness process.
+- Uses `ctx.fs` canonical containment, file URIs, and stable bounded reads, but emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
 
 ## Configuration
 
@@ -23,7 +24,7 @@ The `servers` record key is the stable provider id reserved on `ctx.lsp`; each v
 |---|---|---|
 | `command` | (required) | Executable to spawn — absolute, or resolved on the child PATH at load. Launch uses no shell. |
 | `args` | `[]` | Arguments passed to the executable. |
-| `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`PASSWORD`/`SECRET`/`TOKEN` are not forwarded); an explicit `DSH_*` entry merges after the seam's scrub of ambient ones. |
+| `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`SECRET`/`TOKEN` are not forwarded); an explicit `DSH_*` entry merges after the seam's scrub of ambient ones. |
 | `extensionToLanguage` | (required) | Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). |
 | `initializationOptions` | `null` | Static `initialize` options forwarded to the server. |
 | `configuration` | `null` | Static answer to every `workspace/configuration` item. |
@@ -41,7 +42,7 @@ Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: {
 
 ## Security boundary
 
-The provider trusts its configured server and claims no sandbox confinement. It canonicalizes and reads source through Node APIs, rejecting a source that is missing, non-regular, non-UTF-8, oversized, or whose canonical path resolves outside the canonical workspace (symlink aliases share one instance). Result locations may be external, but an external path cannot become a query source. The first implementation therefore requires trusted host-local deployment; restricted, remote, or virtual workspaces require another provider.
+The provider trusts its configured server and claims no sandbox confinement. It delegates canonical identity, containment, no-follow/stable bounded reads, UTF-8 validation, and file-URI encoding to `ctx.fs`; it rejects missing, non-regular, non-UTF-8, oversized, or canonically out-of-workspace query sources before server startup. Result locations may be external, but an external path cannot become a query source. A deployment must mount filesystem and subprocess providers for the same execution world; split-world composition is invalid.
 
 ## Model Experience
 
@@ -53,6 +54,7 @@ No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **Trusted host-local only** — no sandbox confinement, no private cache/temp write contract; supporting untrusted binaries or restricted/remote/virtual workspaces requires a later process/filesystem contract and a different provider ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)). Containment resolves `realpath`, then opens the source through one handle with `O_NOFOLLOW | O_NONBLOCK` (final-component symlink guard plus nonblocking rejection of FIFOs) and a bounded read; a concurrent mutator that swaps an *ancestor* directory for a symlink between the resolve and the open is an accepted residual TOCTOU under this trusted-deployment model, not closed with non-portable `openat` segment walks.
-- **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; compatibility with one TypeScript server does not imply cross-language support.
+- **No confinement policy** — this package trusts the configured server and does not sandbox its process; a restricted deployment must supply appropriate process/filesystem providers or a same-world sandbox wrapper.
+- **Execution-world URI rendering** — the stdio host produces provider-owned `file:` URIs. The current model tool renders them with the harness host's path library, so a Windows harness paired with a POSIX remote execution world may show remote locations as URIs or non-native paths; protocol queries remain correct.
+- **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim.
 - **Per-server/workspace serialization latency** — parallel agents sharing one server and workspace queue behind one process; long-lived workspace processes consume memory until disposal.
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index 9e8b7f4f43..d449383296 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -2,18 +2,19 @@
 
 [English](README.md) | 中文
 
-`ctx.lsp` 的**通用本地 stdio 语言服务器后端**。一个插件实例接受一张命名服务器表，并逐配置项注册一个隔离的提供方。这是通用主机，而不是语言服务器目录或安装器：部署需要显式配置命令与映射，预设应放在 `cordis.yml` overlay 中。
+`ctx.lsp` 的**通用 stdio 语言服务器后端**。一个插件实例接受一张命名服务器表，并逐配置项注册一个隔离的提供方。它通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动，因此服务器与源文件始终位于所挂载的同一执行环境。这是通用主机，而不是语言服务器目录或安装器：部署需要显式配置命令与映射，preset 应放在 `cordis.yml` overlay 中。
 
 Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）。
 
 ## 功能
 
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
-- 每个 `(server id, canonical workspace realpath)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其 dispose（资源释放）完成，并在新进程上重试该查询一次。
-- 每次查询都使用兼容性优先的**临时打开**序列：通过 Node API 规范化并读取源文件、`textDocument/didOpen`（版本 1、完整文本）、所请求操作，然后执行 `textDocument/didClose`，该操作位于 `finally` 中。写入 `didOpen` 失败或取消时，会在池复用该实例前将其终止。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
+- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其释放，并在新进程上重试该查询一次。
+- 每次查询都使用兼容性优先的**临时打开** 序列：通过 `ctx.fs` 解析源文件并进行有界读取、`textDocument/didOpen`（版本 1、完整文本）、所请求操作，然后执行 `textDocument/didClose`，该操作位于 `finally` 中。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
 - 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。
-- 协议 shutdown 失败后，经由子进程 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
-- 通过子进程 host namespace 中的 Node 文件系统 API 读取源文件，绝不使用 `ctx.fs`，也不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
+- 协议 shutdown 失败后，经由进程管理器 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
+- 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程与协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID 命名空间不得监控 harness 进程。
+- 使用 `ctx.fs` 提供的规范 containment、文件 URI 与稳定有界读取，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
 
 ## 配置
 
@@ -23,13 +24,13 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 |---|---|---|
 | `command` | （必填） | 要 spawn 的可执行文件：绝对路径，或在加载时从子进程 PATH 解析。不使用 shell 启动。 |
 | `args` | `[]` | 传给可执行文件的参数。 |
-| `env` | `{}` | 合并到已清理 credential 的环境之上的额外 env（匹配 `KEY`／`PASSWORD`／`SECRET`／`TOKEN` 的变量不会转发）；显式 `DSH_*` 条目在 seam 清除环境中同名值之后合并。 |
+| `env` | `{}` | 合并到已清理 credential 的环境之上的额外 env（匹配 `KEY`／`SECRET`／`TOKEN` 的变量不会转发）；显式 `DSH_*` 条目在 seam 清除环境中同名值之后合并。 |
 | `extensionToLanguage` | （必填） | 小写、以点开头的扩展名 → LSP language id（例如 `{ '.ts': 'typescript' }`）。 |
 | `initializationOptions` | `null` | 转发给服务器的静态 `initialize` 选项。 |
 | `configuration` | `null` | 每个 `workspace/configuration` 配置项的静态答案。 |
 | `maxMessageBytes` | `16000000` | 从服务器接受的单条 framed 消息最大大小。 |
 | `maxStderrBytes` | `1000000` | 为诊断保留的 stderr 尾部最大大小。 |
-| `maxDocumentBytes` | `4000000` | 该主机可打开的源文件大小上限。 |
+| `maxDocumentBytes` | `4000000` | 该主机可打开的最大源文件。 |
 | `shutdownTimeoutMs` | `5000` | 升级前用于优雅 `shutdown`／`exit` 的预算。 |
 | `killGraceMs` | `2000` | 请求取消及 SIGTERM→SIGKILL 升级的宽限期。 |
 
@@ -37,11 +38,11 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 协议行为
 
-初始化会声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及定义与实现使用的 `linkSupport: true`，且不进行动态注册。服务器返回的能力具有最终决定权：不受支持的操作，或缺少临时打开／关闭的同步方式，会使查询失败。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值都属于协议错误。客户端通过静态配置回答 `workspace/configuration`，接受生命周期记账请求，并拒绝 `workspace/applyEdit`：它绝不应用编辑或运行命令。导航直接映射 `Location`，并从 `LocationLink` 的 `targetUri` + `targetSelectionRange` 映射；hover 规范化会取得有效的 `MarkupContent.value`，保留 string `MarkedString`，把带 language tag 的值渲染为围栏代码，并用一个空行连接数组。缺失结果、格式错误的范围或位置，以及格式错误的 hover 编码，都会以结构化 `LSP_MALFORMED_RESPONSE` 错误的形式失败。
+初始化会声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及定义与实现使用的 `linkSupport: true`，且不进行动态注册。服务器返回的能力具有最终决定权：不受支持的操作，或缺少临时打开／关闭的同步方式，会使查询失败。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值都属于协议错误。客户端通过静态配置回答 `workspace/configuration`，接受生命周期记账请求，并拒绝 `workspace/applyEdit`：它绝不应用编辑或运行命令。导航直接映射 `Location`，并从 `LocationLink` 的 `targetUri` + `targetSelectionRange` 映射；hover 规范化会取得有效的 `MarkupContent.value`，保留 string `MarkedString`，把带 language tag 的值渲染为围栏代码，并用一个空行连接数组。缺失结果、格式错误的范围或位置，以及格式错误的 hover 编码，都会作为结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
 
 ## 安全边界
 
-提供方信任其配置的服务器，不提供任何沙箱隔离。它通过 Node API 规范化并读取源文件，拒绝缺失、非普通文件、非 UTF-8、过大，或规范路径位于规范 Workspace 外部的源文件（符号链接别名共享一个实例）。结果位置可以在外部，但外部路径不能成为查询源。因此，第一版要求可信的主机本地部署；受限、远程或虚拟 Workspace 需要另一个提供方。
+提供方信任其配置的服务器，不声明任何沙箱限制。它把规范身份、containment、不跟随符号链接的稳定有界读取、UTF-8 校验与文件 URI 编码委托给 `ctx.fs`；服务器启动前，系统会拒绝缺失、非普通文件、非 UTF-8、过大或规范路径位于工作区外的查询源。结果位置可以在外部，但外部路径不能成为查询源。部署必须为同一执行环境挂载文件系统与子进程提供方；分裂执行环境的组合无效。
 
 ## 模型体验
 
@@ -53,6 +54,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 已知限制与暂缓事项
 
-- **仅限可信主机本地环境**：没有沙箱隔离，也没有私有 cache／temp 写入契约；支持不受信任 binary 或受限／远程／虚拟 Workspace，需要后续的进程／文件系统契约及不同提供方（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。限制逻辑先解析 `realpath`，再通过一个带 `O_NOFOLLOW | O_NONBLOCK` 的 handle 打开源文件（最终组件符号链接防护，并以非阻塞方式拒绝 FIFO），同时进行有界读取；并发修改方如果在解析与打开之间把*祖先*目录替换为符号链接，会造成残余 TOCTOU。在该可信部署模型下接受此风险，不使用不可移植的 `openat` 逐 segment 遍历来封闭。
-- **临时打开兼容性下限**：同步能力省略打开／关闭（或声明 `None`）的服务器不受支持，即使关闭文档查询能够工作；与一个 TypeScript 服务器兼容，并不表示支持其他语言。
-- **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent（智能体）会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到 dispose。
+- **不提供隔离策略**：这个包（package）信任配置的服务器，不会对其进程执行沙箱化；受限部署必须提供适当的进程／文件系统提供方，或包装同一执行环境的沙箱。
+- **执行环境 URI 渲染**：stdio 主机生成归提供方所有的 `file:` URI。当前面向模型的工具使用 harness 宿主的路径库渲染这些 URI，因此 Windows harness 与 POSIX 远程执行环境配对时，可能把远程位置显示为 URI 或非本机路径；协议查询仍然正确。
+- **临时打开兼容性下限**：同步能力省略打开／关闭（或声明 `None`）的服务器不受支持，即使关闭文档查询能够工作；固定的 TypeScript e2e 只建立一项兼容性下限，不代表跨语言承诺。
+- **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent 会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到释放。
diff --git a/packages/lsp/lsp-local/package.json b/packages/lsp/lsp-local/package.json
index b68745d617..a5411bab55 100644
--- a/packages/lsp/lsp-local/package.json
+++ b/packages/lsp/lsp-local/package.json
@@ -26,6 +26,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-fs": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-lsp": "^0.0.1",
@@ -38,6 +39,8 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-lsp": "workspace:^",
diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts
index e19718eed6..4be75cbd33 100644
--- a/packages/lsp/lsp-local/src/connection.ts
+++ b/packages/lsp/lsp-local/src/connection.ts
@@ -22,7 +22,7 @@ export interface ConnectionSpec {
   readonly args: readonly string[]
   /** The child's working directory (the canonical workspace). */
   readonly cwd: string
-  /** The child's environment (credential-scrubbed, with overrides applied). */
+  /** Explicit child environment overrides; the subprocess provider owns its ambient scrub. */
   readonly env: Record<string, string>
   /** Largest single framed message accepted from the server. */
   readonly maxMessageBytes: number
@@ -98,9 +98,8 @@ export class LspConnection {
         stderr: { maxBytes: spec.maxStderrBytes },
       },
       graceMs: spec.killGraceMs,
-      // spec.env mixes the scrubbed base with explicit config entries; the
-      // seam merges the whole map after its own ambient scrub, so a
-      // configured DSH_* fact reaches the child.
+      // The seam merges explicit config entries after its ambient scrub, so a
+      // configured credential or DSH_* fact reaches the child deliberately.
       env: spec.env,
     })
     /* v8 ignore start -- 'pipe' dispositions expose both streams by the seam contract; defensive. */
diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts
index 11996908ac..3a2b9fbd7b 100644
--- a/packages/lsp/lsp-local/src/host.ts
+++ b/packages/lsp/lsp-local/src/host.ts
@@ -1,154 +1,106 @@
-/**
- * Host-filesystem source access for the local provider, using Node APIs directly in the
- * subprocess's namespace (never `ctx.fs`): only the LSP result is model-visible, so a query does not
- * satisfy read-before-write policy and emits no `fs/observed`. Canonicalization derives target
- * identity from `realpath`, so symlink aliases share a workspace; a source is rejected before server
- * startup when it is missing, non-regular, non-UTF-8, oversized, or canonically outside the
- * workspace. External result locations are allowed, but an external path can never become a query
- * source.
- * @module @deepseek-ai/dsh-lsp-local/host
- */
+/** Filesystem-seam source access for the generic stdio LSP provider. */
 
-import { constants } from 'node:fs'
-import { open, realpath, stat } from 'node:fs/promises'
-import type { FileHandle } from 'node:fs/promises'
-import { isAbsolute, resolve as resolvePath, sep } from 'node:path'
+import type { FileSystem, FsTarget } from '@deepseek-ai/dsh-fs'
 import { throwIfAborted } from './abort.ts'
 
-/** A validated source: its canonical absolute path and current UTF-8 text. */
-export interface HostSource {
-  /** The canonical (realpath-resolved) absolute path, inside the canonical workspace. */
+/** A canonical workspace in the filesystem/subprocess execution world. */
+export interface HostWorkspace {
+  /** Stable filesystem identity used for provider pooling. */
+  readonly target: FsTarget
+  /** Canonical absolute path accepted as a subprocess cwd. */
   readonly canonicalPath: string
-  /** The file's current text, read as UTF-8. */
+  /** Canonical file URI sent during LSP initialization. */
+  readonly fileUrl: string
+}
+
+/** A validated source and the exact URI sent to the language server. */
+export interface HostSource {
+  /** Canonical file URI in the execution world's platform syntax. */
+  readonly fileUrl: string
+  /** Current complete UTF-8 text. */
   readonly text: string
 }
 
 /**
- * Canonicalize a workspace root: it must exist and be a directory. The returned realpath supplies
- * process cwd, `rootUri`, the sole `workspaceFolders` entry, and pool identity, so symlinked roots
- * collapse to one instance.
- * @param workspaceRoot - the caller's workspace root (absolute).
- * @param signal - optional cancellation observed around each filesystem operation.
- * @returns the canonical directory path.
- * @throws Error when the path is missing or not a directory.
+ * Resolve and validate one workspace through `ctx.fs`.
+ * @param fs - filesystem provider sharing the language server's execution world.
+ * @param workspaceRoot - caller-supplied workspace path.
+ * @param signal - optional cancellation around provider operations.
+ * @returns stable identity plus process path and file URI.
  */
-export async function canonicalizeWorkspace(workspaceRoot: string, signal?: AbortSignal): Promise<string> {
+export async function canonicalizeWorkspace(
+  fs: FileSystem,
+  workspaceRoot: string,
+  signal?: AbortSignal,
+): Promise<HostWorkspace> {
   throwIfAborted(signal)
-  let canonical: string
+  let target: FsTarget
   try {
-    canonical = await realpath(workspaceRoot)
-  } catch (error) {
-    throw new Error(`workspace root "${workspaceRoot}" cannot be resolved: ${messageOf(error)}`)
+    target = await fs.resolve(workspaceRoot, signal === undefined ? {} : { signal })
+  } catch (error: unknown) {
+    throwIfAborted(signal)
+    throw new Error(`workspace root "${workspaceRoot}" cannot be resolved: ${messageOf(error)}`, { cause: error })
   }
   throwIfAborted(signal)
-  const info = await stat(canonical)
+  const info = await fs.stat(target, signal)
   throwIfAborted(signal)
-  if (!info.isDirectory()) {
+  if (info?.type !== 'directory') {
     throw new Error(`workspace root "${workspaceRoot}" is not a directory`)
   }
-  return canonical
+  return {
+    target,
+    canonicalPath: fs.processPath(target),
+    fileUrl: fs.fileUrl(target),
+  }
 }
 
 /**
- * Resolve, canonicalize, validate, and read a query source in one pass. A relative `filePath`
- * resolves against `canonicalWorkspace`; an absolute one is taken directly. The canonical target
- * must be a regular UTF-8 file no larger than `maxDocumentBytes`, and must lie inside the canonical
- * workspace.
- * @param filePath - the model-supplied source path (relative or absolute).
- * @param canonicalWorkspace - the already-canonicalized workspace root.
- * @param maxDocumentBytes - the largest source this host will open.
- * @param signal - optional cancellation observed throughout resolution, validation, and reading.
- * @returns the canonical path and current UTF-8 text.
- * @throws Error when the source is missing, non-regular, oversized, non-UTF-8, or out of workspace.
+ * Resolve, contain, and atomically read one bounded query source through
+ * `ctx.fs`. The provider's bounded read owns stable-handle and no-follow
+ * mechanics; this layer owns only LSP-facing validation and messages.
+ * @param fs - filesystem provider sharing the server's execution world.
+ * @param filePath - absolute source path or path relative to `workspace`.
+ * @param workspace - already-canonical workspace.
+ * @param maxDocumentBytes - largest complete source accepted by this host.
+ * @param signal - optional cancellation.
+ * @returns canonical file URI and current text.
  */
 export async function readHostSource(
+  fs: FileSystem,
   filePath: string,
-  canonicalWorkspace: string,
+  workspace: HostWorkspace,
   maxDocumentBytes: number,
   signal?: AbortSignal,
 ): Promise<HostSource> {
   throwIfAborted(signal)
-  const requested = isAbsolute(filePath) ? filePath : resolvePath(canonicalWorkspace, filePath)
-  let canonicalPath: string
+  let target: FsTarget
   try {
-    canonicalPath = await realpath(requested)
-  } catch (error) {
-    throw new Error(`source "${filePath}" cannot be resolved: ${messageOf(error)}`)
+    target = await fs.resolve(filePath, {
+      cwd: workspace.canonicalPath,
+      ...signal === undefined ? {} : { signal },
+    })
+  } catch (error: unknown) {
+    throwIfAborted(signal)
+    throw new Error(`source "${filePath}" cannot be resolved: ${messageOf(error)}`, { cause: error })
   }
   throwIfAborted(signal)
-  if (!isInside(canonicalWorkspace, canonicalPath)) {
+  if (!fs.contains(workspace.target, target)) {
     throw new Error(`source "${filePath}" resolves outside the workspace`)
   }
-  // Open ONE handle after containment, then stat and read through it: a concurrent replace between
-  // realpath and read cannot swap the target, so the regular-file and size checks bind the bytes we
-  // actually read (no path-based TOCTOU). O_NOFOLLOW rejects the final component being swapped for a
-  // symlink between realpath and open (which would otherwise escape the workspace).
-  // O_NONBLOCK prevents a FIFO with no writer from hanging before fstat can reject it as nonregular.
-  const handle = await open(canonicalPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  let text: string
   try {
+    text = await fs.readTextBounded(target, maxDocumentBytes, signal)
+  } catch (error: unknown) {
     throwIfAborted(signal)
-    const info = await handle.stat()
-    throwIfAborted(signal)
-    if (!info.isFile()) {
-      throw new Error(`source "${filePath}" is not a regular file`)
-    }
-    if (info.size > maxDocumentBytes) {
-      throw new Error(`source "${filePath}" is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`)
-    }
-    // Bound the read to the cap even if the file grew after stat: read one extra byte and reject on
-    // overflow, so a concurrent grow cannot defeat the memory bound.
-    const buffer = await readCapped(handle, maxDocumentBytes, filePath, signal)
-    const text = decodeUtf8Strict(buffer, filePath)
-    throwIfAborted(signal)
-    return { canonicalPath, text }
-  } finally {
-    await handle.close()
+    throw new Error(`source "${filePath}" could not be opened safely: ${messageOf(error)}`, { cause: error })
+  }
+  throwIfAborted(signal)
+  return {
+    fileUrl: fs.fileUrl(target),
+    text,
   }
 }
 
-/** Read at most `maxBytes` from the handle, rejecting when the source overflows the cap. */
-async function readCapped(
-  handle: FileHandle,
-  maxBytes: number,
-  filePath: string,
-  signal?: AbortSignal,
-): Promise<Buffer> {
-  const limit = maxBytes + 1
-  const chunk = Buffer.allocUnsafe(limit)
-  let total = 0
-  for (;;) {
-    throwIfAborted(signal)
-    const { bytesRead } = await handle.read(chunk, total, limit - total, total)
-    throwIfAborted(signal)
-    if (bytesRead === 0) break
-    total += bytesRead
-    /* v8 ignore next 3 -- overflow requires the file to grow past the cap between stat and read (a concurrent mutation); defensive. */
-    if (total > maxBytes) {
-      throw new Error(`source "${filePath}" grew past the ${maxBytes}-byte limit while reading`)
-    }
-  }
-  return chunk.subarray(0, total)
-}
-
-/** Whether `child` is the workspace itself or a descendant of it (both already canonical). */
-function isInside(workspace: string, child: string): boolean {
-  if (child === workspace) return true
-  /* v8 ignore next -- a canonical non-root workspace never ends with a separator; the guard covers the filesystem root. */
-  const base = workspace.endsWith(sep) ? workspace : workspace + sep
-  return child.startsWith(base)
-}
-
-/** Decode strictly as UTF-8: a fatal decoder rejects only malformed bytes, keeping a legitimate U+FFFD. */
-function decodeUtf8Strict(buffer: Buffer, filePath: string): string {
-  try {
-    return new TextDecoder('utf-8', { fatal: true }).decode(buffer)
-  } catch {
-    throw new Error(`source "${filePath}" is not valid UTF-8 text`)
-  }
-}
-
-/** Extract a message from an unknown thrown value without leaking `any`. */
 function messageOf(error: unknown): string {
-  /* v8 ignore next -- Node fs rejections are always Error instances; the String() fallback is defensive. */
   return error instanceof Error ? error.message : String(error)
 }
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index d926ae9428..d12e8986fc 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -1,18 +1,16 @@
 /**
  * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table
  * of server commands and registers one isolated provider for each entry. Every provider lazily
- * single-flights one server process per canonical workspace realpath, serves transient-open queries
+ * single-flights one server process per canonical workspace target, serves transient-open queries
  * through it, and replaces a selected transport that fails before or during the next read-only
- * query. Providers read sources through Node APIs in the host namespace (not `ctx.fs`)
- * and trust their configured servers — no sandbox confinement.
+ * query. Providers read sources through `ctx.fs` and launch servers through
+ * `ctx.subprocess`, so both local and remote implementations share one host.
  *
  * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
  * unregisters from `ctx.lsp` and tears down every live server.
  * @module @deepseek-ai/dsh-lsp-local
  */
 
-import { accessSync, constants, statSync } from 'node:fs'
-import { delimiter, isAbsolute, join } from 'node:path'
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
@@ -24,9 +22,9 @@ import type {
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { abortable, abortError } from './abort.ts'
 import { canonicalizeWorkspace, readHostSource } from './host.ts'
+import type { HostWorkspace } from './host.ts'
 import { LspInstance } from './instance.ts'
 import type { ConnectionSpawner } from './connection.ts'
-import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import type { InstanceSpec } from './instance.ts'
 
 export { canonicalizeWorkspace, readHostSource } from './host.ts'
@@ -46,10 +44,7 @@ export { LspConnection } from './connection.ts'
 export const name = 'lsp-local'
 
 /** Services required by this plugin. */
-export const inject = ['lsp', 'subprocess']
-
-/** Credential-shaped ambient env vars are NOT forwarded to the child by default. */
-
+export const inject = ['fs', 'lsp', 'subprocess']
 
 const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
 const DEFAULT_MAX_STDERR_BYTES = 1_000_000
@@ -91,6 +86,7 @@ export interface Config {
 
 /** One server config after schemastery fills every default. */
 type ResolvedServerConfig = Required<LspLocalServerConfig>
+type WorkspaceKey = HostWorkspace['target']['targetKey']
 
 const LspLocalServerConfig: z<LspLocalServerConfig> = z.object({
   command: z.string().required(),
@@ -114,23 +110,28 @@ export const Config: z<Config> = z.object({
  * Register the configured stdio LSP providers. Resolves every executable at load (after credential
  * scrubbing) before publishing any provider; each process launches lazily on its first matching
  * query.
- * @param ctx - the plugin context (must inject `lsp`).
+ * @param ctx - the plugin context carrying `fs`, `lsp`, and `subprocess`.
  * @param config - the resolved plugin configuration (schemastery has filled every default).
  */
-export function apply(ctx: Context, config: Config): void {
+export async function apply(ctx: Context, config: Config): Promise<void> {
   const entries = Object.entries(config.servers)
   if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server')
 
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
-  const providers = entries.map(([providerId, rawConfig]) => {
+  const providers = await Promise.all(entries.map(async ([providerId, rawConfig]) => {
     if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
     const resolved = rawConfig as ResolvedServerConfig
     validateServerConfig(providerId, resolved)
-    const childEnv = buildChildEnv(resolved.env)
-    const executable = resolveExecutable(resolved.command, childEnv)
-    return new LocalLspProvider(providerId, resolved, childEnv, executable, spec => ctx.subprocess.spawn(spec))
-  })
+    const executable = await ctx.subprocess.resolveExecutable(resolved.command, resolved.env)
+    return new LocalLspProvider(
+      providerId,
+      ctx.fs,
+      resolved,
+      executable,
+      spec => ctx.subprocess.spawn(spec),
+    )
+  }))
 
   ctx.effect(() => {
     const disposers: Array<() => void> = []
@@ -180,16 +181,16 @@ function assertPositiveInteger(providerId: string, name: string, value: number):
 class LocalLspProvider implements LspProvider {
   readonly id: LspProviderId
   readonly extensionToLanguage: Readonly<Record<string, string>>
-  /** One live instance per canonical workspace realpath. */
-  private readonly instances = new Map<string, LspInstance>()
+  /** One live instance per stable canonical workspace identity. */
+  private readonly instances = new Map<WorkspaceKey, LspInstance>()
   /** One complete source-read→open→query→close serialization tail per canonical workspace. */
-  private readonly queues = new Map<string, Promise<void>>()
+  private readonly queues = new Map<WorkspaceKey, Promise<void>>()
   private disposed = false
 
   constructor(
     providerId: string,
+    private readonly fs: Context['fs'],
     private readonly config: ResolvedServerConfig,
-    private readonly childEnv: Record<string, string>,
     private readonly executable: string,
     private readonly spawner: ConnectionSpawner,
   ) {
@@ -211,19 +212,20 @@ class LocalLspProvider implements LspProvider {
   }
 
   async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
-    // Honor an already-aborted signal before host I/O so a canceled request never starts a server.
+    // Honor an already-aborted signal before provider I/O so a canceled request never starts a server.
     this.assertActive(signal)
-    const workspace = await canonicalizeWorkspace(request.workspaceRoot, signal)
+    const workspace = await canonicalizeWorkspace(this.fs, request.workspaceRoot, signal)
     this.assertActive(signal)
-    return this.enqueue(workspace, signal, async () => {
+    const workspaceKey = workspace.target.targetKey
+    return this.enqueue(workspaceKey, signal, async () => {
       this.assertActive(signal)
       // Read inside the workspace queue but before spawning: a queued query sees current bytes when
       // its turn starts, while an invalid source still cannot leave an idle process pooled.
-      const source = await readHostSource(request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, signal)
       // Disposal may have snapshotted the instance map while host I/O was pending. Re-check before a
       // synchronous get-or-create so every spawned process remains owned by teardown.
       this.assertActive(signal)
-      let instance = this.instanceFor(workspace)
+      let instance = this.instanceFor(workspaceKey, workspace)
       try {
         return await instance.query(request, source, signal)
       } catch (error) {
@@ -231,22 +233,22 @@ class LocalLspProvider implements LspProvider {
         // read-only, so replace that transport once and retry transparently.
         if (!instance.isTransportFailure(error)) throw error
         await instance.dispose()
-        this.evictIfCurrent(workspace, instance)
+        this.evictIfCurrent(workspaceKey, instance)
         this.assertActive(signal)
-        instance = this.instanceFor(workspace)
+        instance = this.instanceFor(workspaceKey, workspace)
         return await instance.query(request, source, signal)
       } finally {
         // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check.
         if (instance.dead) {
           await instance.dispose()
-          this.evictIfCurrent(workspace, instance)
+          this.evictIfCurrent(workspaceKey, instance)
         }
       }
     })
   }
 
   /** Serialize one complete query lifecycle for a canonical workspace. */
-  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
+  private enqueue<T>(workspace: WorkspaceKey, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
     const previous = this.queues.get(workspace) ?? Promise.resolve()
     const result = abortable(previous, signal).then(run)
     // The tail follows the actual prior work even when this caller aborts its wait. It never rejects,
@@ -260,27 +262,28 @@ class LocalLspProvider implements LspProvider {
   }
 
   /** Return or synchronously publish the one instance for a canonical workspace. */
-  private instanceFor(workspace: string): LspInstance {
+  private instanceFor(workspaceKey: WorkspaceKey, workspace: HostWorkspace): LspInstance {
     this.assertActive()
-    const existing = this.instances.get(workspace)
+    const existing = this.instances.get(workspaceKey)
     if (existing !== undefined) return existing
     const created = this.createInstance(workspace)
-    this.instances.set(workspace, created)
+    this.instances.set(workspaceKey, created)
     return created
   }
 
   /** Drop the slot iff it still contains this instance. */
-  private evictIfCurrent(workspace: string, instance: LspInstance): void {
+  private evictIfCurrent(workspace: WorkspaceKey, instance: LspInstance): void {
     /* v8 ignore next -- mismatch requires another query to replace the slot before this finally runs. */
     if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
   }
 
-  private createInstance(workspace: string): LspInstance {
+  private createInstance(workspace: HostWorkspace): LspInstance {
     const spec: InstanceSpec = {
       command: this.executable,
       args: this.config.args,
-      cwd: workspace,
-      env: this.childEnv,
+      cwd: workspace.canonicalPath,
+      workspaceUri: workspace.fileUrl,
+      env: this.config.env,
       configuration: this.config.configuration,
       initializationOptions: this.config.initializationOptions,
       maxMessageBytes: this.config.maxMessageBytes,
@@ -304,41 +307,3 @@ class LocalLspProvider implements LspProvider {
     this.queues.clear()
   }
 }
-
-/** The seam's scrubbed parent env (credential-shaped and DSH_* names dropped), plus the config's explicit env. */
-function buildChildEnv(extra: Record<string, string>): Record<string, string> {
-  return { ...scrubbedParentEnv(), ...extra }
-}
-
-/**
- * Resolve the server executable to an absolute path: an absolute command is verified directly; a
- * bare command is looked up on the child's PATH. Fails loudly when nothing is executable.
- */
-function resolveExecutable(command: string, childEnv: Record<string, string>): string {
-  if (isAbsolute(command)) {
-    // Verify an absolute command too, so an unavailable one fails at load, not on the first query.
-    if (!isExecutableFileSync(command)) {
-      throw new Error(`lsp-local: command "${command}" is not an executable file`)
-    }
-    return command
-  }
-  /* v8 ignore next -- buildChildEnv always sets PATH from the ambient env; the further fallbacks are defensive. */
-  const pathValue = childEnv.PATH ?? process.env.PATH ?? ''
-  for (const dir of pathValue.split(delimiter)) {
-    if (dir === '') continue
-    const candidate = join(dir, command)
-    if (isExecutableFileSync(candidate)) return candidate
-  }
-  throw new Error(`lsp-local: command "${command}" was not found on PATH`)
-}
-
-/** Synchronous regular-file and executable check used only at load-time resolution. */
-function isExecutableFileSync(path: string): boolean {
-  try {
-    if (!statSync(path).isFile()) return false
-    accessSync(path, constants.X_OK)
-    return true
-  } catch {
-    return false
-  }
-}
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index c1f78eaa38..8584f64f48 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -7,7 +7,6 @@
  * @module @deepseek-ai/dsh-lsp-local/instance
  */
 
-import { pathToFileURL } from 'node:url'
 import { LspError } from '@deepseek-ai/dsh-lsp'
 import type {
   LspOperation,
@@ -31,6 +30,8 @@ import {
 
 /** Everything an instance needs beyond the connection spec. */
 export interface InstanceSpec extends ConnectionSpec {
+  /** Canonical workspace file URI supplied by the filesystem provider. */
+  readonly workspaceUri: string
   /** Static `initialize` options forwarded to the server. */
   readonly initializationOptions: unknown
   /** Graceful `shutdown`/`exit` budget before escalation (ms). */
@@ -108,9 +109,11 @@ export class LspInstance {
 
   private async initialize(): Promise<void> {
     const initializeResult = await this.connection.request('initialize', {
-      processId: process.pid,
-      rootUri: pathToFileURL(this.spec.cwd).href,
-      workspaceFolders: [{ uri: pathToFileURL(this.spec.cwd).href, name: 'workspace' }],
+      // A subprocess provider may run in another PID namespace or machine;
+      // the host PID would let the server monitor an unrelated process.
+      processId: null,
+      rootUri: this.spec.workspaceUri,
+      workspaceFolders: [{ uri: this.spec.workspaceUri, name: 'workspace' }],
       capabilities: CLIENT_CAPABILITIES,
       initializationOptions: this.spec.initializationOptions,
     }) as WireInitializeResult
@@ -147,7 +150,7 @@ export class LspInstance {
       throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION')
     }
 
-    const uri = pathToFileURL(source.canonicalPath).href
+    const uri = source.fileUrl
     let opened = false
     try {
       /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */
diff --git a/packages/lsp/lsp-local/tests/built-lib.e2e.ts b/packages/lsp/lsp-local/tests/built-lib.e2e.ts
index bdd0ec1067..75f9f227c3 100644
--- a/packages/lsp/lsp-local/tests/built-lib.e2e.ts
+++ b/packages/lsp/lsp-local/tests/built-lib.e2e.ts
@@ -16,8 +16,9 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 
 const pkgDir = fileURLToPath(new URL('..', import.meta.url))
 const seamLib = join(pkgDir, '../lsp/lib/index.js')
+const fsLib = join(pkgDir, '../../fs/fs-local/lib/index.js')
 const subprocessLib = join(pkgDir, '../../subprocess/subprocess-local/lib/index.js')
-const built = existsSync(join(pkgDir, 'lib/index.js')) && existsSync(seamLib) && existsSync(subprocessLib)
+const built = existsSync(join(pkgDir, 'lib/index.js')) && existsSync(seamLib) && existsSync(fsLib) && existsSync(subprocessLib)
 
 const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url))
 
@@ -42,10 +43,12 @@ describe.skipIf(!built)('built lib real load path (plain node)', () => {
       const { Context } = await import('cordis')
       const { default: Lsp } = await import('@deepseek-ai/dsh-lsp')
       const LspLocal = await import('@deepseek-ai/dsh-lsp-local')
+      const { default: LocalFileSystem } = await import('@deepseek-ai/dsh-fs-local')
       const { default: LocalSubprocessService } = await import('@deepseek-ai/dsh-subprocess-local')
       const ctx = new Context()
       await ctx.plugin(Lsp)
       await ctx.plugin(LocalSubprocessService)
+      await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
       await ctx.plugin(LspLocal, {
         servers: {
           fake: {
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index 26aacdc1f4..cd7ed87e17 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -4,7 +4,10 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { realpath } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
 import { promisify } from 'node:util'
+import { Context } from 'cordis'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import { deadline } from '@deepseek-ai/dsh-timeout'
 import { canonicalizeWorkspace, readHostSource } from '@deepseek-ai/dsh-lsp-local'
 
@@ -12,84 +15,105 @@ const execFileAsync = promisify(execFile)
 
 let root: string
 let ws: string
+let ctx: Context
+let fs: LocalFileSystem
 
 beforeEach(async () => {
   root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-host-')))
   ws = join(root, 'ws')
   await mkdir(ws)
+  ctx = new Context()
+  await ctx.plugin(LocalFileSystem, { cwd: root })
+  fs = ctx.fs as LocalFileSystem
 })
 
 afterEach(async () => {
+  await ctx.fiber.dispose()
   await rm(root, { recursive: true, force: true })
 })
 
 const BIG = 1_000_000
 
+async function workspace() {
+  return await canonicalizeWorkspace(fs, ws)
+}
+
+async function readSource(filePath: string, maxBytes = BIG, signal?: AbortSignal) {
+  return await readHostSource(fs, filePath, await workspace(), maxBytes, signal)
+}
+
 describe('canonicalizeWorkspace', () => {
   it('returns the realpath of a directory', async () => {
-    expect(await canonicalizeWorkspace(ws)).toBe(ws)
+    expect((await workspace()).canonicalPath).toBe(ws)
   })
 
   it('resolves a symlinked workspace to its target so aliases share identity', async () => {
     const link = join(root, 'ws-link')
     await symlink(ws, link)
-    expect(await canonicalizeWorkspace(link)).toBe(ws)
+    expect((await canonicalizeWorkspace(fs, link)).canonicalPath).toBe(ws)
   })
 
   it('rejects a missing workspace', async () => {
-    await expect(canonicalizeWorkspace(join(root, 'nope'))).rejects.toThrow(/cannot be resolved/)
+    await expect(canonicalizeWorkspace(fs, join(root, 'nope'))).rejects.toThrow(/not a directory/)
   })
 
   it('rejects a non-directory workspace', async () => {
     const file = join(root, 'file.txt')
     await writeFile(file, 'x')
-    await expect(canonicalizeWorkspace(file)).rejects.toThrow(/not a directory/)
+    await expect(canonicalizeWorkspace(fs, file)).rejects.toThrow(/not a directory/)
   })
 })
 
 describe('readHostSource', () => {
   it('reads a relative path against the workspace', async () => {
     await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
-    const source = await readHostSource('a.ts', ws, BIG)
-    expect(source.canonicalPath).toBe(join(ws, 'a.ts'))
+    const source = await readSource('a.ts')
+    expect(source.fileUrl).toBe(pathToFileURL(join(ws, 'a.ts')).href)
     expect(source.text).toBe('const x = 1\n')
   })
 
   it('reads an absolute path inside the workspace', async () => {
     const abs = join(ws, 'b.ts')
     await writeFile(abs, 'b')
-    const source = await readHostSource(abs, ws, BIG)
-    expect(source.canonicalPath).toBe(abs)
+    const source = await readSource(abs)
+    expect(source.fileUrl).toBe(pathToFileURL(abs).href)
   })
 
   it('accepts a source reached through a symlink that stays inside the workspace', async () => {
     await mkdir(join(ws, 'real'))
     await writeFile(join(ws, 'real', 'c.ts'), 'c')
     await symlink(join(ws, 'real'), join(ws, 'linked'))
-    const source = await readHostSource('linked/c.ts', ws, BIG)
-    expect(source.canonicalPath).toBe(join(ws, 'real', 'c.ts'))
+    const source = await readSource('linked/c.ts')
+    expect(source.fileUrl).toBe(pathToFileURL(join(ws, 'real', 'c.ts')).href)
   })
 
   it('rejects a source whose canonical path escapes the workspace via symlink', async () => {
     const outside = join(root, 'outside.ts')
     await writeFile(outside, 'secret')
     await symlink(outside, join(ws, 'escape.ts'))
-    await expect(readHostSource('escape.ts', ws, BIG)).rejects.toThrow(/outside the workspace/)
+    await expect(readSource('escape.ts')).rejects.toThrow(/outside the workspace/)
   })
 
   it('rejects an absolute source outside the workspace', async () => {
     const outside = join(root, 'out.ts')
     await writeFile(outside, 'x')
-    await expect(readHostSource(outside, ws, BIG)).rejects.toThrow(/outside the workspace/)
+    await expect(readSource(outside)).rejects.toThrow(/outside the workspace/)
   })
 
   it('rejects a missing source', async () => {
-    await expect(readHostSource('nope.ts', ws, BIG)).rejects.toThrow(/cannot be resolved/)
+    await expect(readSource('nope.ts')).rejects.toThrow(/not found/)
+  })
+
+  it('wraps a provider failure while resolving the source', async () => {
+    const canonical = await workspace()
+    fs.resolve = async () => { throw 'raw resolve failure' }
+    await expect(readHostSource(fs, 'broken.ts', canonical, BIG))
+      .rejects.toThrow('source "broken.ts" cannot be resolved: raw resolve failure')
   })
 
   it('rejects a non-regular source (directory)', async () => {
     await mkdir(join(ws, 'dir'))
-    await expect(readHostSource('dir', ws, BIG)).rejects.toThrow(/not a regular file/)
+    await expect(readSource('dir')).rejects.toThrow(/not a regular file/)
   })
 
   // Windows has no filesystem FIFO; the directory case above pins non-regular rejection there.
@@ -97,36 +121,36 @@ describe('readHostSource', () => {
     const fifo = join(ws, 'pipe.ts')
     await execFileAsync('mkfifo', [fifo])
     using d = deadline(undefined, 1000, 'FIFO_READ_TIMEOUT')
-    await expect(readHostSource('pipe.ts', ws, BIG, d.signal)).rejects.toThrow(/not a regular file/)
+    await expect(readSource('pipe.ts', BIG, d.signal)).rejects.toThrow(/not a regular file/)
   })
 
   it('honors a pre-aborted source read before filesystem work', async () => {
     const controller = new AbortController()
     controller.abort(new Error('source read cancelled'))
-    await expect(readHostSource('missing.ts', ws, BIG, controller.signal)).rejects.toThrow(/source read cancelled/)
+    await expect(readSource('missing.ts', BIG, controller.signal)).rejects.toThrow(/source read cancelled/)
   })
 
   it('treats the workspace root itself as inside, then rejects it as non-regular', async () => {
-    // filePath '.' canonicalizes to the workspace dir: isInside's identity branch is taken, and the
-    // directory then fails the regular-file check.
-    await expect(readHostSource('.', ws, BIG)).rejects.toThrow(/not a regular file/)
+    // The filesystem containment primitive accepts the workspace itself; the
+    // bounded read then rejects the directory as non-regular.
+    await expect(readSource('.')).rejects.toThrow(/not a regular file/)
   })
 
   it('rejects an oversized source', async () => {
     await writeFile(join(ws, 'big.ts'), 'x'.repeat(100))
-    await expect(readHostSource('big.ts', ws, 10)).rejects.toThrow(/over the 10-byte limit/)
+    await expect(readSource('big.ts', 10)).rejects.toThrow(/10-byte limit/)
   })
 
   it('rejects a non-UTF-8 source', async () => {
     await writeFile(join(ws, 'bin.ts'), Buffer.from([0xff, 0xfe, 0x00]))
-    await expect(readHostSource('bin.ts', ws, BIG)).rejects.toThrow(/not valid UTF-8/)
+    await expect(readSource('bin.ts')).rejects.toThrow(/invalid UTF-8|binary file/)
   })
 
   it('keeps a valid U+FFFD replacement character in otherwise-valid UTF-8', async () => {
     // The literal replacement char is valid UTF-8; a fatal decoder must accept it (only malformed
     // byte sequences are rejected).
     await writeFile(join(ws, 'repl.ts'), 'const s = "�"\n')
-    const source = await readHostSource('repl.ts', ws, BIG)
+    const source = await readSource('repl.ts')
     expect(source.text).toBe('const s = "�"\n')
   })
 })
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 75b9e541fc..3027cbbd29 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -3,6 +3,8 @@ import { mkdtemp, mkdir, readFile, rm, writeFile, realpath } from 'node:fs/promi
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL, fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import { LspInstance, readHostSource } from '@deepseek-ai/dsh-lsp-local'
 import { encodeMessage } from '@deepseek-ai/dsh-lsp-local'
 import type { ConnectionWriter } from '@deepseek-ai/dsh-lsp-local/src/connection.ts'
@@ -15,6 +17,8 @@ const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.u
 
 let root: string
 let ws: string
+let ctx: Context
+let fs: LocalFileSystem
 let live: LspInstance[] = []
 
 beforeEach(async () => {
@@ -22,11 +26,15 @@ beforeEach(async () => {
   ws = join(root, 'ws')
   await mkdir(ws)
   await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
+  ctx = new Context()
+  await ctx.plugin(LocalFileSystem, { cwd: root })
+  fs = ctx.fs as LocalFileSystem
 })
 
 afterEach(async () => {
   for (const instance of live) await instance.dispose()
   live = []
+  await ctx.fiber.dispose()
   await rm(root, { recursive: true, force: true })
 })
 
@@ -39,6 +47,7 @@ function makeInstance(
     command: process.execPath,
     args: [fixtureServer],
     cwd: ws,
+    workspaceUri: pathToFileURL(ws).href,
     env: { ...scrubbedParentEnv(), ...env },
     configuration: { setting: 42 },
     initializationOptions: { init: true },
@@ -58,7 +67,12 @@ function query(operation: LspProviderQuery['operation'] = 'goToDefinition'): Lsp
 
 /** Run a query against an instance, reading the source first the way the provider does. */
 async function run(instance: LspInstance, operation: LspProviderQuery['operation'] = 'goToDefinition', signal?: AbortSignal): Promise<LspQueryResult> {
-  const source = await readHostSource('a.ts', ws, 4_000_000)
+  const workspace = {
+    target: await fs.resolve(ws),
+    canonicalPath: ws,
+    fileUrl: pathToFileURL(ws).href,
+  }
+  const source = await readHostSource(fs, 'a.ts', workspace, 4_000_000)
   return instance.query(query(operation), source, signal)
 }
 
@@ -68,6 +82,7 @@ function scriptInstance(script: string, overrides: Partial<InstanceSpec> = {}):
     command: process.execPath,
     args: ['-e', script],
     cwd: ws,
+    workspaceUri: pathToFileURL(ws).href,
     env: scrubbedParentEnv(),
     configuration: null,
     initializationOptions: null,
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index ccd85a1e14..a7a006c06e 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -8,6 +8,7 @@ import { Context } from 'cordis'
 import Lsp, { type LspProvider, type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
 import { deadline } from '@deepseek-ai/dsh-timeout'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
 import type { LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local'
 
@@ -47,6 +48,7 @@ async function mount(
   const ctx = new Context()
   await ctx.plugin(Lsp)
   await ctx.plugin(LocalSubprocessService)
+  await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
   const register = ctx.lsp.registerProvider.bind(ctx.lsp)
   const registrationSpy = captureProvider === undefined
     ? undefined
@@ -79,6 +81,7 @@ describe('lsp-local end to end over a fake server', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await ctx.plugin(LspLocal, {
       servers: {
         typescript: fakeServer({ LSP_FAKE_HOVER: JSON.stringify({ contents: 'ts' }) }),
@@ -322,6 +325,7 @@ describe('lsp-local end to end over a fake server', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, {
       servers: {
         missing: {
diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts
index 77fcbe7851..b0209e09b8 100644
--- a/packages/lsp/lsp-local/tests/provider.spec.ts
+++ b/packages/lsp/lsp-local/tests/provider.spec.ts
@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os'
 import { delimiter, join } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import Lsp, { type LspQueryRequest } from '@deepseek-ai/dsh-lsp'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
 import type { Config, LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local'
@@ -44,6 +45,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('onpath', {
       command: 'fake-lsp',
       args: [],
@@ -57,6 +59,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('nope', {
       command: 'fake-lsp',
       args: [],
@@ -71,6 +74,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     // Grab the provider instance by registering, then dispose the whole plugin fiber.
     const lsp = ctx.lsp
     const fiber = await ctx.plugin(LspLocal, config('disp', {
@@ -88,6 +92,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('bad-budget', {
       command: process.execPath,
       args: ['-e', ''],
@@ -101,6 +106,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('bad-cap', {
       command: process.execPath,
       args: ['-e', ''],
@@ -114,6 +120,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('bad-timer', {
       command: process.execPath,
       args: ['-e', ''],
@@ -130,6 +137,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('abs-bad', {
       command: notExe,
       args: [],
@@ -142,6 +150,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('abs-directory', {
       command: ws,
       args: [],
@@ -154,6 +163,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, { servers: {} })).rejects.toThrow(/servers must contain at least one server/)
     await ctx.fiber.dispose()
   })
@@ -162,6 +172,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('', {
       command: process.execPath,
       extensionToLanguage: { '.ts': 'typescript' },
@@ -173,6 +184,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, {
       servers: {
         valid: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } },
@@ -187,6 +199,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, {
       servers: {
         first: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } },
diff --git a/packages/lsp/lsp-local/tests/typescript-server.e2e.ts b/packages/lsp/lsp-local/tests/typescript-server.e2e.ts
index fe9230ce14..9bdb7d1fd4 100644
--- a/packages/lsp/lsp-local/tests/typescript-server.e2e.ts
+++ b/packages/lsp/lsp-local/tests/typescript-server.e2e.ts
@@ -11,6 +11,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import Lsp, { type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
 
@@ -54,6 +55,7 @@ beforeAll(async () => {
   ctx = new Context()
   await ctx.plugin(Lsp)
   await ctx.plugin(LocalSubprocessService)
+  await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
   await ctx.plugin(LspLocal, {
     servers: {
       typescript: {
diff --git a/packages/lsp/lsp-local/tsconfig.json b/packages/lsp/lsp-local/tsconfig.json
index 2b106ddc81..04fdeb9a84 100644
--- a/packages/lsp/lsp-local/tsconfig.json
+++ b/packages/lsp/lsp-local/tsconfig.json
@@ -26,6 +26,9 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../fs/fs"
+    },
     {
       "path": "../lsp"
     },
diff --git a/packages/lsp/tool-lsp/package.json b/packages/lsp/tool-lsp/package.json
index 28b5a34bdb..f757df35fd 100644
--- a/packages/lsp/tool-lsp/package.json
+++ b/packages/lsp/tool-lsp/package.json
@@ -38,11 +38,13 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-lsp": "workspace:^",
     "@deepseek-ai/dsh-lsp-local": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
     "@deepseek-ai/dsh-timeout-policy": "workspace:^",
diff --git a/packages/lsp/tool-lsp/tests/integration.spec.ts b/packages/lsp/tool-lsp/tests/integration.spec.ts
index 4d790cbd6b..8312a6e3ab 100644
--- a/packages/lsp/tool-lsp/tests/integration.spec.ts
+++ b/packages/lsp/tool-lsp/tests/integration.spec.ts
@@ -6,6 +6,7 @@ import { pathToFileURL } from 'node:url'
 import { Context } from 'cordis'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import Lsp from '@deepseek-ai/dsh-lsp'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
@@ -50,6 +51,7 @@ async function mount(hang: boolean, timeoutMs?: number): Promise<Context> {
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(Lsp)
+  await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
   await ctx.plugin(LocalSubprocessService)
   await ctx.plugin(LspLocal, {
     servers: {
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index 083a144b55..65d541a7c1 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
-README.md: 9c8206464d45b1be1d6ee3861c57c128e77686c5
-README.zh.md: 70d081e60a7db61443ed616b64586a93c119a640
+README.md: a4f743056b4a524be9623b0f700f37e0534b463f
+README.zh.md: c84ad3f1b59afcdbbd111f1b82c57c56aa24fdcf
diff --git a/packages/pty/README.md b/packages/pty/README.md
index 9c8206464d..a4f743056b 100644
--- a/packages/pty/README.md
+++ b/packages/pty/README.md
@@ -2,13 +2,12 @@
 
 English | [中文](README.zh.md)
 
-This family provides persistent, owner-scoped pseudo-terminal sessions for interactive or stateful terminal work. It complements one-shot bash execution.
+`PTY` stands for **Pseudo-Terminal**（伪终端）. This capability provides persistent, owner-scoped terminal sessions for workflows that require state across tool calls or interactive stdin. PTY complements the one-shot bash and filesystem tools; it does not replace their stronger per-operation contracts.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`pty/`](pty/README.md) | Defines the PTY service and session lifecycle | `ctx.pty` |
-| [`pty-local/`](pty-local/README.md) | Provides local persistent terminal sessions | registers on `ctx.pty` |
-| [`tool-pty/`](tool-pty/README.md) | Exposes PTY session operations to the model | registers on `ctx.tools` |
-| [`tool-bash-persistent/`](tool-bash-persistent/README.md) | Exposes a reusable PTY-backed bash tool | registers on `ctx.tools` |
+| [`pty`](pty/README.md) (`@deepseek-ai/dsh-pty`) | Backend registry, branded ids, exact-Agent ownership, session operations, and awaited cleanup | `ctx.pty` |
+| `pty-local` (`@deepseek-ai/dsh-pty-local`) | Shell backend over `ctx.subprocess.spawnTerminal`: readiness detection, bounded terminal state, sandbox policy, and session operations | registers on `ctx.pty` |
+| `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
-The [persistent PTY decision](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) records the family boundary.
+The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index 70d081e60a..c84ad3f1b5 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -2,13 +2,12 @@
 
 [English](README.md) | 中文
 
-本家族为交互式或有状态的终端工作提供持久且限定所有者范围的伪终端会话，是单次 bash 执行的补充。
+`PTY` 的全称是 **Pseudo-Terminal（伪终端）**。这项能力提供持久且限定所有者范围的终端会话，适用于需要跨工具调用保留状态或使用交互式 stdin 的工作流。PTY 是单次 bash 与文件系统工具的补充，不会取代后两者更严格的逐操作契约。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
-| [`pty/`](pty/README.md) | 定义 PTY 服务和会话生命周期 | `ctx.pty` |
-| [`pty-local/`](pty-local/README.md) | 提供本地持久终端会话 | 注册到 `ctx.pty` |
-| [`tool-pty/`](tool-pty/README.md) | 向模型公开 PTY 会话操作 | 注册到 `ctx.tools` |
-| [`tool-bash-persistent/`](tool-bash-persistent/README.md) | 公开可复用的 PTY 后端 bash 工具 | 注册到 `ctx.tools` |
+| [`pty`](pty/README.md)（`@deepseek-ai/dsh-pty`） | 后端注册表、品牌化 id、精确的 Agent 所有权、会话操作与等待完成的清理 | `ctx.pty` |
+| `pty-local`（`@deepseek-ai/dsh-pty-local`） | `ctx.subprocess.spawnTerminal` 之上的 shell 后端：就绪检测、有界终端状态、沙箱策略与会话操作 | 注册到 `ctx.pty` |
+| `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
-[持久 PTY 决策](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)记录了该家族的边界。
+设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 48ae675425..d8f5c2e2d0 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: ba05495318127b63b3d2a6a60ec743e1ff1c5821
-README.zh.md: 81987ea0685d761507b535b7ed6eefa0888fbd54
+README.md: 8a0a60139e27d98c4f506245a204723da997cd4a
+README.zh.md: 3df845931dac33abecbcd5030a1b204c68acc638
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index ba05495318..8a0a60139e 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -2,35 +2,35 @@
 
 English | [中文](README.zh.md)
 
-Local Linux/macOS `node-pty` backend for `ctx.pty`; loading it on another platform fails as unsupported. It starts an interactive shell under the shared `ctx.sandboxPolicy`, strips credential-shaped ambient environment variables, retains bounded line-oriented output, detects readiness, and tears down the captured process tree rooted at the `node-pty` child.
+Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It starts an interactive shell under the shared `ctx.sandboxPolicy`, retains bounded line-oriented output, and detects readiness while the subprocess provider owns PTY allocation, environment scrubbing, foreground process groups, signalling, and complete terminal-session cleanup. The same PTY backend therefore composes with local or remote execution-world providers.
 
 ## Plugin (`pty-local`)
 
-The plugin injects `pty`, `sandbox`, and `sandboxPolicy`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. At spawn, one `ctx.sandboxPolicy.resolve({ session })` call supplies both the effective mode and the session workspace root; the same root is the default shell cwd when the caller omits one. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a local-provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
+The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Linux readiness combines a foreground-verified private bash prompt marker, foreground-process-group syscall inspection, silence fallback, and absolute timeout. macOS uses the verified prompt marker plus silence/timeout because it has no `/proc` syscall surface. A marker is not ready until printable prompt text arrives, including when the OSC marker and `PS1` are split across data callbacks; when bash prints the marker before the kernel publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win; that grace must cover at least one `pollIntervalMs` and is rejected at load otherwise. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unrecognized or unreadable process state is never a positive exact-idle signal. A foreground group's stdin wait that already existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason even when its foreground process group is not observable yet; if that close fails, `PtyBackendCleanupError` separately preserves the cleanup failure for registry disposal. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until printable prompt text arrives, including when the OSC marker and `PS1` are split across data callbacks; when bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation resolves the current foreground process group and delivers a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close sends `SIGTERM` to descendants, waits, then sends `SIGKILL` to the union of captured survivors and newly scanned descendants so reparenting cannot hide a process from teardown. It verifies that every retained identity is gone or, on Linux, a non-executing zombie before stopping the shell; zombie entries are quiescent and are reaped as the shell exits. A survivor failure does not cache a permanently rejected close; a later close retries the teardown.
+Send cancellation asks the terminal handle to signal the current foreground process group with a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
-### Current file policy and indirect consumer
+### Indirect consumer
 
 #### What the model sees
 
-The policy owner contributes capability-neutral `sandbox:policy` context. Through `@deepseek-ai/dsh-tool-pty` or another PTY consumer, the model may also receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
+Nothing directly. Through `@deepseek-ai/dsh-tool-pty`, the model may receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
 
 #### Token effect
 
-The current-policy clause is present while this backend is mounted. Retained PTY scrollback is not placed in model history until a consumer returns bounded output.
+None until a consumer returns bounded backend output. Retained PTY scrollback is not placed in model history by this package.
 
 #### KV Cache effect
 
-A standing-policy change appends an owner-rendered superseding runtime-context snapshot after retained history; consumer results remain append-only.
+No direct invalidation; the consumer owns prompts, schemas, and appended results.
 
 ## Known Limitations and Deferred Work
 
 - Line-oriented output is normalized; full-screen alternate-buffer interaction is unsupported.
-- Linux exact probes support x64 and arm64 UAPI tables; other architectures use prompt-marker and silence/timeout readiness.
-- A descendant that daemonizes and reparents before teardown leaves the captured tree; cleanup never broadens to the launcher PID's POSIX session because that can include unrelated processes.
+- Exact stdin-wait detection depends on the mounted subprocess provider; providers that cannot prove it use prompt-marker and silence/timeout readiness.
+- Cleanup guarantees are those of `SubprocessTerminalHandle`; provider-specific gaps belong to that implementation's contract rather than this PTY consumer.
 - Sessions do not survive harness process exit.
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 81987ea068..3df845931d 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -2,35 +2,35 @@
 
 [English](README.md) | 中文
 
-这个本地 Linux／macOS `node-pty` 后端实现 `ctx.pty`；在其他平台加载时会以不支持为由失败。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，移除形似凭据的环境变量，保留有界的逐行输出，检测就绪状态，并清理以 `node-pty` 子进程为根的已捕获进程树。
+这是基于 `ctx.subprocess.spawnTerminal` 的 `ctx.pty` 持久 shell 后端。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，保留有界的逐行输出并检测就绪状态；进程管理提供方负责 PTY 分配、环境清理、前台进程组、信号发送和完整终端会话清理。因此，同一个 PTY 后端可以与本地或远程执行世界提供方组合。
 
 ## 插件（`pty-local`）
 
-该插件注入 `pty`、`sandbox` 和 `sandboxPolicy`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。Spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使本地提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
+该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-Linux 的就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、前台进程组 syscall 检查、静默回退和绝对超时。macOS 没有 `/proc` syscall 接口，因此使用经过验证的提示符标记以及静默／超时。当可打印的提示符文本尚未到达时，即使 OSC 标记和 `PS1` 被拆到多个数据回调中，系统也不会把标记视为就绪。如果 bash 在内核发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出；该宽限至少要覆盖一个 `pollIntervalMs`，否则加载时即被拒绝。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。无法识别或读取的进程状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝，即使当时还无法观察其前台进程组。如果关闭失败，`PtyBackendCleanupError` 会单独保留清理失败，供注册表 dispose（资源释放）时处理。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。可打印的提示符文本尚未到达时，即使 OSC 标记和 `PS1` 被拆到多个数据回调中，系统也不会把标记视为就绪。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送时，系统会解析当前前台进程组并发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作先向后代发送 `SIGTERM` 并等待，再向已捕获的存活进程与新扫描到的后代之并集发送 `SIGKILL`，防止进程通过重新设定父进程而逃避清理。在停止 shell 前，系统会确认每个保留的进程身份都已消失，或者在 Linux 上已成为不再执行的僵尸进程；僵尸进程条目视为完全停稳，并会随 shell 退出而回收。如果仍有进程存活，失败结果不会缓存成永久拒绝的关闭操作；后续关闭仍会重试清理。
+取消发送时，系统会请求终端句柄向当前前台进程组发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
-### 当前文件策略与间接消费方
+### 间接消费方
 
 #### 模型看到的内容
 
-策略归属方会贡献与具体能力无关的 `sandbox:policy` 上下文。模型通过 `@deepseek-ai/dsh-tool-pty` 或其他 PTY 消费方还可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因和清理错误。
+没有直接可见内容。模型通过 `@deepseek-ai/dsh-tool-pty` 可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因和清理错误。
 
 #### Token 影响
 
-装载该后端期间，当前策略子句会一直存在。消费方返回有界输出前，保留的 PTY scrollback 不会进入模型历史。
+消费方返回有界的后端输出前没有影响。此包不会把保留的 PTY scrollback 放入模型历史。
 
 #### KV Cache 影响
 
-常驻策略发生变化时，会在保留的历史之后追加一份由归属方渲染、取代先前状态的运行时上下文快照；消费方结果保持仅追加。
+不会直接失效；提示词、schema 与追加结果由消费方负责。
 
-## 已知限制与暂缓事项
+## 已知限制与暂缓工作
 
 - 输出按行规范化；不支持全屏备用缓冲区交互。
-- Linux 精确探针支持 x64 与 arm64 UAPI 表；其他架构使用提示符标记和静默／超时就绪机制。
-- 如果后代进程在清理前守护化并重新设定父进程，它会脱离已捕获的进程树；清理绝不会扩大到启动器 PID 所属的整个 POSIX 会话，因为其中可能包含无关进程。
-- harness 进程退出后，会话无法继续存在。
+- 精确 stdin 等待检测取决于挂载的进程管理提供方；无法证明该事实的提供方使用提示符标记和静默／超时就绪机制。
+- 清理保证遵循 `SubprocessTerminalHandle`；提供方特有缺口属于该实现的契约，而非此 PTY 消费方。
+- 会话无法跨 harness 进程退出保留。
diff --git a/packages/pty/pty-local/package.json b/packages/pty/pty-local/package.json
index a859f482fa..94f98c02d5 100644
--- a/packages/pty/pty-local/package.json
+++ b/packages/pty/pty-local/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-pty-local",
-  "description": "Local node-pty backend for persistent DeepSeek Harness PTY sessions",
+  "description": "Persistent shell PTY backend over the DeepSeek Harness subprocess terminal primitive",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -21,12 +21,8 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
-    "scripts/ensure-spawn-helper.mjs",
     "lib/types/**/*.d.ts"
   ],
-  "scripts": {
-    "postinstall": "node scripts/ensure-spawn-helper.mjs"
-  },
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
@@ -39,7 +35,6 @@
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
-    "node-pty": "^1.1.0",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
@@ -50,6 +45,7 @@
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index e59d53446a..0a54a0b804 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -1,22 +1,18 @@
 /**
- * Local persistent PTY backend using public `node-pty` APIs, shared sandbox
- * policy, bounded output, platform readiness probes, and process-session cleanup.
+ * Persistent shell PTY backend over the subprocess terminal primitive, shared
+ * sandbox policy, bounded output, and provider-owned session cleanup.
  * @module @deepseek-ai/dsh-pty-local
  */
 
 import { Context } from 'cordis'
-import * as nodePty from 'node-pty'
-import type { IPtyForkOptions } from 'node-pty'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { PtyBackendCleanupError } from '@deepseek-ai/dsh-pty'
-import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
-import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox'
+import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
 import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
-import { createProcessInspector } from './process-inspector.ts'
-import type { ProcessInspector } from './process-inspector.ts'
 import { LocalPtySession } from './session.ts'
 
 export { Config } from './config.ts'
@@ -24,8 +20,8 @@ export type { Config as PtyLocalConfig } from './config.ts'
 
 /** Cordis plugin name. */
 export const name = 'pty-local'
-/** Required services: PTY registry plus the one shared confinement policy. */
-export const inject = ['pty', 'sandbox', 'sandboxPolicy']
+/** Required services: PTY registry, shared confinement policy, and process substrate. */
+export const inject = ['pty', 'sandbox', 'sandboxPolicy', 'subprocess']
 
 interface SandboxModeFenceState {
   pty: Context['pty']
@@ -55,10 +51,10 @@ function ensureSandboxModeFence(ctx: Context, owner: Agent): void {
   }, { global: true })
 }
 
-function childEnvironment(spec: PtyBackendSpawnSpec): NodeJS.ProcessEnv {
-  // node-pty owns the spawn; the base env shares the subprocess seam's scrub.
+function childEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
+  // The subprocess provider supplies its own scrubbed ambient base; these are
+  // deliberate terminal-specific overrides layered after it.
   return {
-    ...scrubbedParentEnv(),
     TERM: 'dumb',
     PAGER: 'cat',
     GIT_PAGER: 'cat',
@@ -71,11 +67,14 @@ function childEnvironment(spec: PtyBackendSpawnSpec): NodeJS.ProcessEnv {
   }
 }
 
-function spawnArgv(ctx: Context, config: ResolvedConfig, policy: SandboxExecutionPolicy): string[] {
+function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSpec): string[] {
   const argv = [config.shellPath, ...config.shellArgs]
-  if (policy.mode === 'danger-full-access') return argv
-  // Re-state the discriminant because object spread does not preserve its narrowed type.
-  return ctx.sandbox.confine(argv, { ...policy, mode: policy.mode }).argv
+  const mode: SandboxMode = effectiveSandboxMode(spec.owner.session.events) ?? ctx.sandboxPolicy.defaultMode
+  if (mode === 'danger-full-access') return argv
+  return ctx.sandbox.confine(argv, {
+    mode: mode,
+    workspaceRoot: ctx.sandboxPolicy.workspaceRoot,
+  }).argv
 }
 
 /** Local shell backend registered under the configured type. */
@@ -85,13 +84,13 @@ export class LocalPtyBackend implements PtyBackend {
   constructor(
     private readonly ctx: Context,
     private readonly config: ResolvedConfig,
-    private readonly inspector: ProcessInspector,
-    private readonly spawnTerminal: typeof nodePty.spawn = nodePty.spawn,
+    private readonly spawnTerminal: (
+      spec: SubprocessTerminalSpawnSpec,
+    ) => Promise<SubprocessTerminalHandle> = spec => ctx.subprocess.spawnTerminal(spec),
     private readonly createSession: (
-      terminal: ReturnType<typeof nodePty.spawn>,
-      inspector: ProcessInspector,
+      terminal: SubprocessTerminalHandle,
       config: ResolvedConfig,
-    ) => LocalPtySession = (terminal, inspector, config) => new LocalPtySession(terminal, inspector, config),
+    ) => LocalPtySession = (terminal, config) => new LocalPtySession(terminal, config),
   ) {
     this.type = config.backendType
   }
@@ -99,19 +98,18 @@ export class LocalPtyBackend implements PtyBackend {
   async spawn(spec: PtyBackendSpawnSpec): Promise<LocalPtySession> {
     spec.signal?.throwIfAborted()
     ensureSandboxModeFence(this.ctx, spec.owner)
-    const policy = this.ctx.sandboxPolicy.resolve({ session: spec.owner.session })
-    const argv = spawnArgv(this.ctx, this.config, policy)
-    const file = argv[0]
-    if (file === undefined) throw new Error('pty-local: sandbox returned empty argv')
-    const options: IPtyForkOptions = {
-      name: 'dumb',
-      cols: this.config.cols,
-      rows: this.config.rows,
-      cwd: spec.cwd ?? policy.workspaceRoot,
+    const argv = spawnArgv(this.ctx, this.config, spec)
+    if (argv[0] === undefined) throw new Error('pty-local: sandbox returned empty argv')
+    const terminal = await this.spawnTerminal({
+      argv,
+      cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
       env: childEnvironment(spec),
-    }
-    const terminal = this.spawnTerminal(file, argv.slice(1), options)
-    const session = this.createSession(terminal, this.inspector, this.config)
+      rows: this.config.rows,
+      cols: this.config.cols,
+      graceMs: this.config.disposeGraceMs,
+      signal: spec.signal,
+    })
+    const session = this.createSession(terminal, this.config)
     try {
       await session.initialize(spec.signal)
       return session
@@ -129,6 +127,5 @@ export class LocalPtyBackend implements PtyBackend {
 /** Register the local PTY backend. */
 export function apply(ctx: Context, config: Config): void {
   validateConfig(config)
-  const inspector = createProcessInspector()
-  ctx.pty.registerBackend(new LocalPtyBackend(ctx, config, inspector))
+  ctx.pty.registerBackend(new LocalPtyBackend(ctx, config))
 }
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 46f3be2ca8..a6abaf7785 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -1,8 +1,11 @@
-/** Local `node-pty` session: bounded output, readiness, signals, and teardown. */
+/** Persistent PTY session over the subprocess seam's terminal primitive. */
 
-import { constants } from 'node:os'
 import { Buffer } from 'node:buffer'
-import type { IDisposable, IPty } from 'node-pty'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+} from '@deepseek-ai/dsh-subprocess'
 import type {
   PtyBackendSession,
   PtyReadRequest,
@@ -17,13 +20,8 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
 import { TerminalSanitizer } from './sanitize.ts'
 
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}
-
 function utf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
   if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
   const chars = Array.from(text)
@@ -80,17 +78,16 @@ class LocalSendOperation implements PtySendOperation {
   private readonly promise: PromiseWithResolvers<PtySendResult>
   private finished = false
   private initialForegroundLeftWait: boolean
+  private initialForegroundPgid: number | undefined
 
   constructor(
     maxBytes: number,
     readonly startedAt: number,
-    private readonly initialForegroundPgid: number | undefined,
-    initialForegroundWasWaiting: boolean,
     private readonly onCancel: () => void,
   ) {
     this.output = new BoundedTextBuffer(maxBytes)
     this.promise = Promise.withResolvers<PtySendResult>()
-    this.initialForegroundLeftWait = !initialForegroundWasWaiting
+    this.initialForegroundLeftWait = true
   }
 
   get done(): Promise<PtySendResult> {
@@ -123,6 +120,11 @@ class LocalSendOperation implements PtySendOperation {
     return this.output.consume()
   }
 
+  setInitialForeground(foreground: SubprocessTerminalForeground | undefined): void {
+    this.initialForegroundPgid = foreground?.processGroupId
+    this.initialForegroundLeftWait = foreground?.inputWaiting !== true
+  }
+
   acceptsStdinWait(pgid: number, waiting: boolean): boolean {
     // The same group may still expose the wait that existed before terminal.write.
     // Observe every poll so a departure before the exact-settlement threshold
@@ -139,27 +141,21 @@ class LocalSendOperation implements PtySendOperation {
   }
 }
 
-function signalName(number: number | undefined): NodeJS.Signals | null {
-  if (number === undefined || number === 0) return null
-  for (const [name, value] of Object.entries(constants.signals)) {
-    if (value === number) return name as NodeJS.Signals
-  }
-  return null
-}
-
-/** Backend session wrapping one `node-pty` process and its captured process tree. */
+/** Backend session wrapping one provider-owned terminal process. */
 export class LocalPtySession implements PtyBackendSession {
   motd = ''
   readonly pid: number
+  private readonly decoder = new TextDecoder('utf-8', { fatal: true })
   private readonly sanitizer: TerminalSanitizer
   private readonly scrollback: BoundedTextBuffer
-  private readonly exitPromise: PromiseWithResolvers<void> = Promise.withResolvers<void>()
-  private readonly dataDisposable: IDisposable
-  private readonly exitDisposable: IDisposable
+  private readonly outputEnded = Promise.withResolvers<void>()
+  private readonly completion: Promise<void>
   private statusValue: PtySessionStatus = { kind: 'running' }
   private active: LocalSendOperation | undefined
   private activeTimer: NodeJS.Timeout | undefined
+  private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
+  private polling = false
   private promptSeen = false
   private promptTextSeen = false
   private shellPgid: number | undefined
@@ -167,23 +163,22 @@ export class LocalPtySession implements PtyBackendSession {
   private lastOutputAt = Date.now()
   private closing = false
   private closePromise: Promise<void> | undefined
+  private transportFailure: Error | undefined
 
   constructor(
-    private readonly terminal: IPty,
-    private readonly inspector: ProcessInspector,
+    private readonly terminal: SubprocessTerminalHandle,
     private readonly config: ResolvedConfig,
   ) {
     this.pid = terminal.pid
     this.sanitizer = new TerminalSanitizer(config.maxReadBytes)
     this.scrollback = new BoundedTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
-    this.dataDisposable = terminal.onData((data) => { this.onData(data) })
-    this.exitDisposable = terminal.onExit(({ exitCode, signal }) => {
-      const tail = this.sanitizer.flush()
-      this.appendOutput(tail)
-      this.statusValue = { kind: 'exited', exitCode, signal: signalName(signal) }
-      this.settleActive('session_exit')
-      this.exitPromise.resolve()
-    })
+    terminal.output.on('data', this.onTerminalData)
+    terminal.output.once('end', this.onTerminalEnd)
+    terminal.output.once('error', this.onTerminalError)
+    this.completion = terminal.done.then(
+      outcome => this.onExit(outcome),
+      (error: unknown) => { this.onTransportFailure(error) },
+    )
   }
 
   /**
@@ -213,14 +208,9 @@ export class LocalPtySession implements PtyBackendSession {
     if (this.active !== undefined) throw new Error('PTY session already has an active send')
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
-    const initialForegroundPgid = this.inspector.foregroundPgid(this.pid)
-    const initialForegroundWasWaiting = initialForegroundPgid !== undefined
-      && this.inspector.isStdinWaiting(initialForegroundPgid)
     const operation = new LocalSendOperation(
       this.config.maxReadBytes,
       Date.now(),
-      initialForegroundPgid,
-      initialForegroundWasWaiting,
       () => { this.interrupt(operation) },
     )
     this.active = operation
@@ -233,20 +223,28 @@ export class LocalPtySession implements PtyBackendSession {
       request.signal.addEventListener('abort', onAbort, { once: true })
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
-
-    try {
-      if (request.text.length > 0) this.terminal.write(request.text)
-      if (request.submit) this.terminal.write('\r')
-    } catch (error: unknown) {
-      this.clearActive()
-      operation.fail(error)
-      return operation
-    }
-
-    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
+    this.activeDeadlineTimer = setTimeout(() => {
+      if (this.active === operation) this.settleActive('timeout')
+    }, this.config.timeoutMs)
+    void this.beginSend(operation, request)
     return operation
   }
 
+  private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
+    try {
+      const foreground = await this.terminal.inspectForeground()
+      if (this.active !== operation || this.closing) return
+      operation.setInitialForeground(foreground)
+      const input = `${request.text}${request.submit ? '\r' : ''}`
+      if (input.length > 0) await this.terminal.write(Buffer.from(input, 'utf8'))
+      // Closing can race the awaited provider write even though static analysis sees only local assignments.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (this.active === operation && !this.closing) this.schedulePoll(operation, 0)
+    } catch (error: unknown) {
+      if (this.active === operation) this.failActive(error)
+    }
+  }
+
   read(request: PtyReadRequest): PtyReadResult {
     const snapshot = this.scrollback.snapshot()
     const lines = snapshot.text.split('\n')
@@ -272,16 +270,9 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
-  signal(signal: PtySignal): Promise<PtySignalResult> {
-    return Promise.resolve().then(() => {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
-      if (signal === 'SIGKILL' && pgid === this.pid) {
-        throw new Error('refusing to SIGKILL the PTY shell; use terminal_close')
-      }
-      this.inspector.signalGroup(pgid, signal)
-      return { delivered: true, targetPgid: pgid }
-    })
+  async signal(signal: PtySignal): Promise<PtySignalResult> {
+    const targetPgid = await this.terminal.signalForeground(signal)
+    return { delivered: true, targetPgid }
   }
 
   status(): PtySessionStatus {
@@ -300,12 +291,35 @@ export class LocalPtySession implements PtyBackendSession {
     return closing
   }
 
+  private readonly onTerminalData = (chunk: Buffer | Uint8Array | string): void => {
+    try {
+      const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
+      this.onData(this.decoder.decode(bytes, { stream: true }))
+    } catch (error: unknown) {
+      this.onTransportFailure(new Error('PTY emitted invalid UTF-8', { cause: error }))
+    }
+  }
+
+  private readonly onTerminalEnd = (): void => {
+    try {
+      this.onData(this.decoder.decode())
+      this.appendOutput(this.sanitizer.flush())
+    } catch (error: unknown) {
+      this.onTransportFailure(new Error('PTY ended with invalid UTF-8', { cause: error }))
+    } finally {
+      this.outputEnded.resolve()
+    }
+  }
+
+  private readonly onTerminalError = (error: Error): void => {
+    this.onTransportFailure(error)
+    this.outputEnded.resolve()
+  }
+
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
     if (sanitized.prompt) {
-      const foregroundPgid = this.inspector.foregroundPgid(this.pid)
-      if (this.shellPgid === undefined) this.shellPgid = foregroundPgid
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
@@ -317,6 +331,21 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
+  private async onExit(outcome: SubprocessOutcome): Promise<void> {
+    await this.outputEnded.promise
+    if (this.transportFailure !== undefined) return
+    this.statusValue = { kind: 'exited', exitCode: outcome.exitCode, signal: outcome.signal }
+    this.settleActive('session_exit')
+  }
+
+  private onTransportFailure(error: unknown): void {
+    const failure = error instanceof Error ? error : new Error(String(error))
+    this.transportFailure ??= failure
+    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
+    this.failActive(failure)
+    this.terminal.terminate()
+  }
+
   private appendOutput(text: string): void {
     if (text.length === 0) return
     this.lastOutputAt = Date.now()
@@ -324,44 +353,56 @@ export class LocalPtySession implements PtyBackendSession {
     this.active?.append(text)
   }
 
-  private pollReadiness(operation: LocalSendOperation): void {
-    if (this.active !== operation) return
-    if (this.statusValue.kind === 'exited') {
-      this.settleActive('session_exit')
-      return
-    }
-    if (this.promptSeen && this.promptTextSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (this.shellPgid !== undefined && pgid === this.shellPgid) {
+  private schedulePoll(operation: LocalSendOperation, delayMs = this.config.pollIntervalMs): void {
+    if (this.active !== operation || this.polling) return
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
+    this.activeTimer = setTimeout(() => {
+      this.activeTimer = undefined
+      void this.pollReadiness(operation)
+    }, delayMs)
+  }
+
+  private async pollReadiness(operation: LocalSendOperation): Promise<void> {
+    if (this.active !== operation || this.polling) return
+    this.polling = true
+    try {
+      if (this.statusValue.kind === 'exited') {
+        this.settleActive('session_exit')
+        return
+      }
+      const foreground = await this.terminal.inspectForeground()
+      if (this.active !== operation) return
+      const idleFor = Date.now() - this.lastOutputAt
+      if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
+        this.shellPgid = foreground.processGroupId
+      }
+      if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs
+        && foreground?.processGroupId === this.shellPgid) {
         this.settleActive('stdin_read')
         return
       }
+      const elapsed = Date.now() - operation.startedAt
+      const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
+      const acceptsStdinWait = startupHasOutput && foreground !== undefined
+        && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting)
+      if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
+        this.settleActive('stdin_read')
+        return
+      }
+      // A prompt candidate can race bash's foreground handoff, but an interactive
+      // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
+      // on waiting for shell ownership instead of letting a child marker suppress
+      // readiness until the absolute timeout.
+      const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
+      if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
+        this.settleActive('inferred_idle')
+      }
+    } catch (error: unknown) {
+      if (this.active === operation) this.failActive(error)
+    } finally {
+      this.polling = false
+      if (this.active === operation) this.schedulePoll(operation)
     }
-    const elapsed = Date.now() - operation.startedAt
-    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
-    let acceptsStdinWait = false
-    if (startupHasOutput) {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      acceptsStdinWait = pgid !== undefined
-        && operation.acceptsStdinWait(pgid, this.inspector.isStdinWaiting(pgid))
-    }
-    if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
-      this.settleActive('stdin_read')
-      return
-    }
-    // A prompt candidate can race bash's foreground handoff, but an interactive
-    // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
-    // on waiting for shell ownership instead of letting a child marker suppress
-    // readiness until the absolute timeout. When a prompt marker was seen, the
-    // configured grace holds the fallback past the silence bound so polls in
-    // that window can observe the foreground handoff and settle as stdin_read.
-    const idleFor = Date.now() - this.lastOutputAt
-    const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
-    if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
-      this.settleActive('inferred_idle')
-      return
-    }
-    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
   }
 
   private settleActive(waitReason: PtyWaitReason): void {
@@ -373,8 +414,10 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private stopPolling(): void {
-    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = undefined
+    if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
+    this.activeDeadlineTimer = undefined
   }
 
   private clearActive(): void {
@@ -393,104 +436,30 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    try {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
-      this.inspector.signalGroup(pgid, 'SIGINT')
-    } catch (error: unknown) {
-      this.failActive(error)
-    }
-  }
-
-  private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
-    return members.filter(member => this.inspector.isAlive(member))
-  }
-
-  private descendants(): ProcessIdentity[] {
-    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
-  }
-
-  private async waitForExit(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
-    const deadline = Date.now() + this.config.disposeGraceMs
-    let survivors = this.survivors(members)
-    while (survivors.length > 0 && Date.now() < deadline) {
-      await delay(Math.min(25, Math.max(1, deadline - Date.now())))
-      survivors = this.survivors(members)
-    }
-    return survivors
-  }
-
-  private signalMembers(members: ProcessIdentity[], signal: 'SIGTERM' | 'SIGKILL'): void {
-    for (const member of members) {
-      try {
-        this.inspector.signalProcess(member, signal)
-      } catch (_alreadyExitedDuringSignal) {
-        // Identity is rechecked by the inspector; a same-tick exit is success.
-      }
-    }
-  }
-
-  private unionMembers(...groups: ProcessIdentity[][]): ProcessIdentity[] {
-    const members: ProcessIdentity[] = []
-    const seen = new Set<string>()
-    for (const group of groups) {
-      for (const member of group) {
-        const key = JSON.stringify([member.pid, member.started])
-        if (seen.has(key)) continue
-        seen.add(key)
-        members.push(member)
-      }
-    }
-    return members
-  }
-
-  private async stopDescendants(): Promise<ProcessIdentity[]> {
-    const captured = this.descendants()
-    this.signalMembers(captured, 'SIGTERM')
-    const capturedSurvivors = await this.waitForExit(captured)
-    // A TERM-handling descendant may have forked while winding down. Rescan
-    // while the shell can still reap every member, then kill both the fresh
-    // tree and captured survivors that were reparented out of that tree.
-    const members = this.unionMembers(capturedSurvivors, this.descendants())
-    this.signalMembers(members, 'SIGKILL')
-    const survivors = await this.waitForExit(members)
-    return this.survivors(this.unionMembers(survivors, this.descendants()))
-  }
-
-  private async stopShell(): Promise<void> {
-    try {
-      this.terminal.kill('SIGTERM')
-    } catch (_topLevelAlreadyExitedDuringTerm) {
-      // The exit notification remains authoritative.
-    }
-    if (this.statusValue.kind === 'running') {
-      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (this.statusValue.kind === 'running') {
-      try {
-        this.terminal.kill('SIGKILL')
-      } catch (_topLevelAlreadyExitedDuringKill) {
-        // The exit notification remains authoritative.
-      }
-      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (this.statusValue.kind === 'running') {
-      throw new Error(`PTY cleanup failed; surviving pids: ${this.pid}`)
-    }
+    void this.terminal.signalForeground('SIGINT').catch((error: unknown) => {
+      if (this.active === operation) this.failActive(error)
+    })
   }
 
   private async closeOnce(reason: string): Promise<void> {
-    this.dataDisposable.dispose()
     // Stop readiness polling but retain the active operation: teardown settles
     // it as session_exit below, so an in-flight send is never mis-settled as
     // stdin_read/inferred_idle/timeout during the grace period.
     this.stopPolling()
-    const survivors = await this.stopDescendants()
-    if (survivors.length > 0) {
-      throw new Error(`PTY cleanup failed (${reason}); surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
+    this.terminal.terminate()
+    const quiescent = await this.terminal.waitForExit()
+    if (!quiescent) {
+      throw new Error(`PTY cleanup failed (${reason}); terminal session did not reach quiescence`)
     }
-    await this.stopShell()
+    // Whole-session cleanup can fail before the top-level process exits. Wait
+    // for it first so that failure is reported instead of blocking forever on
+    // `done`; successful quiescence guarantees `done` can now settle status and
+    // drain the terminal output.
+    await this.completion
     this.settleActive('session_exit')
-    this.exitDisposable.dispose()
+    this.terminal.output.off('data', this.onTerminalData)
+    this.terminal.output.off('end', this.onTerminalEnd)
+    this.terminal.output.off('error', this.onTerminalError)
+    if (this.transportFailure !== undefined) throw this.transportFailure
   }
 }
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 1ad29d7d01..a8753deaf3 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -1,9 +1,9 @@
 import { describe, expect, it, vi } from 'vitest'
-import type { IPty, IPtyForkOptions } from 'node-pty'
+import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { Inbox, type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
@@ -11,12 +11,18 @@ import PtyService, { PtyBackendCleanupError, PtySessionId } from '@deepseek-ai/d
 import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
 import * as ptyLocal from '@deepseek-ai/dsh-pty-local'
 import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-local/src/config.ts'
-import type { ProcessInspector } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
 import type { LocalPtySession } from '@deepseek-ai/dsh-pty-local/src/session.ts'
+import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
+import type {
+  SubprocessHandle,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
 
 class EmptySandbox extends SandboxProvider {
   confine(_argv: readonly string[], _policy: SandboxPolicy): ConfinedArgv {
-    return { argv: [], enforcement: 'full', denialSignatures: [], runnerFailureRules: [] }
+    return { argv: [], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
   }
 }
 
@@ -25,7 +31,7 @@ class RecordingSandbox extends SandboxProvider {
 
   confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv {
     this.calls.push({ argv, policy })
-    return { argv: ['/sandbox', '--', ...argv], enforcement: 'full', denialSignatures: [], runnerFailureRules: [] }
+    return { argv: ['/sandbox', '--', ...argv], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
   }
 }
 
@@ -38,28 +44,37 @@ function config(): ResolvedConfig {
   }
 }
 
-function agent(ctx: Context, cwd?: string): Agent {
+function agent(ctx: Context): Agent {
   const id = SessionId('agent')
-  const session = Session.create(id, undefined, { version: 0, id, createdAt: 0, ...cwd === undefined ? {} : { cwd } })
   return {
-    id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
-    status: 'idle',
-    ctx,
-    send: () => {},
-    followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
-    runMaintenance: task => task(new AbortController().signal),
-    whenIdle: () => Promise.resolve(),
+    id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx,
+    followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
   }
 }
 
-const inspector = {
-  foregroundPgid: () => undefined,
-  isStdinWaiting: () => false,
-  processTree: () => [],
-  isAlive: () => false,
-  signalGroup() {},
-  signalProcess() {},
-} satisfies ProcessInspector
+function terminalHandle(): SubprocessTerminalHandle {
+  const output = new PassThrough()
+  return {
+    pid: 123,
+    output,
+    done: Promise.resolve({ exitCode: 0, signal: null }),
+    write: async () => {},
+    inspectForeground: async () => ({ processGroupId: 123, inputWaiting: true }),
+    signalForeground: async () => 123,
+    terminate: () => { output.end() },
+    waitForExit: async () => true,
+  }
+}
+
+class StubSubprocessService extends SubprocessService {
+  readonly cwd = '/tmp'
+  readonly runtimeRoot = '/tmp/dsh-runtime'
+  async resolveExecutable(command: string): Promise<string> { return command }
+  spawn(_spec: SubprocessSpawnSpec): SubprocessHandle { throw new Error('unused') }
+  async spawnTerminal(_spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    return terminalHandle()
+  }
+}
 
 function spec(owner: Agent, signal?: AbortSignal) {
   return {
@@ -81,12 +96,11 @@ function stubLocalSession(initialize: () => Promise<void> = () => Promise.resolv
 }
 
 function registerStubLocalBackend(ctx: Context, createSession: () => LocalPtySession) {
-  return ctx.inject(['pty', 'sandbox', 'sandboxPolicy'], (providerCtx) => {
+  return ctx.inject(['pty', 'sandbox', 'sandboxPolicy', 'subprocess'], (providerCtx) => {
     providerCtx.pty.registerBackend(new LocalPtyBackend(
       providerCtx,
       { ...config(), backendType: 'stub' },
-      inspector,
-      (() => ({})) as never,
+      async () => terminalHandle(),
       createSession,
     ))
   })
@@ -97,7 +111,7 @@ describe('LocalPtyBackend startup rollback', () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/tmp' })
-    const backend = new LocalPtyBackend(ctx, config(), inspector)
+    const backend = new LocalPtyBackend(ctx, config(), async () => terminalHandle())
     const controller = new AbortController()
     const abortReason = new Error('spawn aborted')
     controller.abort(abortReason)
@@ -109,11 +123,11 @@ describe('LocalPtyBackend startup rollback', () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
-    const spawnTerminal = (() => ({} as IPty)) as never
+    const spawnTerminal = async (): Promise<SubprocessTerminalHandle> => terminalHandle()
 
     const closed = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
     const failed = { initialize: () => Promise.reject(new Error('startup failed')), close: closed } as unknown as LocalPtySession
-    const backend = new LocalPtyBackend(ctx, config(), inspector, spawnTerminal, () => failed)
+    const backend = new LocalPtyBackend(ctx, config(), spawnTerminal, () => failed)
     await expect(backend.spawn(spec(agent(ctx)))).rejects.toThrow('startup failed')
     expect(closed).toHaveBeenCalledWith('PTY startup failed')
 
@@ -123,7 +137,7 @@ describe('LocalPtyBackend startup rollback', () => {
       initialize: () => Promise.reject(startupFailure),
       close: () => Promise.reject(cleanupFailure),
     } as unknown as LocalPtySession
-    const aggregate = new LocalPtyBackend(ctx, config(), inspector, spawnTerminal, () => doublyFailed)
+    const aggregate = new LocalPtyBackend(ctx, config(), spawnTerminal, () => doublyFailed)
     await expect(aggregate.spawn(spec(agent(ctx)))).rejects.toEqual(expect.objectContaining({
       name: 'PtyBackendCleanupError',
       spawnError: startupFailure,
@@ -131,79 +145,72 @@ describe('LocalPtyBackend startup rollback', () => {
     } satisfies Partial<PtyBackendCleanupError>))
   })
 
-  it('resolves session mode and root together before wrapping the shell', async () => {
+  it('wraps confined argv, scrubs the environment, and returns initialized sessions', async () => {
     const ctx = new Context()
     await ctx.plugin(RecordingSandbox)
-    await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/deployment-fallback' })
-    const terminal = {} as IPty
-    let spawned: { file: string; args: string[]; options: IPtyForkOptions } | undefined
-    const spawnTerminal = ((file: string, args: string[], options: IPtyForkOptions) => {
-      spawned = { file, args, options }
+    await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: '/workspace' })
+    const terminal = terminalHandle()
+    let spawned: SubprocessTerminalSpawnSpec | undefined
+    const spawnTerminal = async (spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> => {
+      spawned = spec
       return terminal
-    }) as never
+    }
     const initialized = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
     const session = { initialize: initialized } as unknown as LocalPtySession
     const backend = new LocalPtyBackend(
       ctx,
       { ...config(), shellArgs: ['-i'] },
-      inspector,
       spawnTerminal,
       () => session,
     )
     const previous = process.env.PTY_TEST_SECRET
     process.env.PTY_TEST_SECRET = 'must-not-leak'
-    const owner = agent(ctx, '/session-workspace')
-    setSandboxMode(owner.session, 'workspace-write')
     try {
-      expect(await backend.spawn(spec(owner))).toBe(session)
+      expect(await backend.spawn({ ...spec(agent(ctx)), cwd: '/work' })).toBe(session)
     } finally {
       if (previous === undefined) delete process.env.PTY_TEST_SECRET
       else process.env.PTY_TEST_SECRET = previous
     }
 
     expect(spawned).toMatchObject({
-      file: '/sandbox',
-      args: ['--', '/bin/bash', '-i'],
-      options: {
-        name: 'dumb', cols: 80, rows: 24, cwd: '/session-workspace',
-        env: {
-          TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ', BASH_SILENCE_DEPRECATION_WARNING: '1',
-          DSH_SHELL: '1', DSH_SESSION_ID: 'agent', DSH_PTY_SESSION_ID: 'pty-1',
-        },
+      argv: ['/sandbox', '--', '/bin/bash', '-i'],
+      cols: 80,
+      rows: 24,
+      cwd: '/work',
+      graceMs: 10,
+      env: {
+        TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ', BASH_SILENCE_DEPRECATION_WARNING: '1',
+        DSH_SHELL: '1', DSH_SESSION_ID: 'agent', DSH_PTY_SESSION_ID: 'pty-1',
       },
     })
-    expect(spawned?.options.env?.PTY_TEST_SECRET).toBeUndefined()
+    expect(spawned?.env?.PTY_TEST_SECRET).toBeUndefined()
     expect(initialized).toHaveBeenCalledWith(undefined)
-    expect((ctx.sandbox as RecordingSandbox).calls).toEqual([{
-      argv: ['/bin/bash', '-i'],
-      policy: { mode: 'workspace-write', workspaceRoot: '/session-workspace' },
-    }])
   })
 
   it('composes the default local session around a spawned terminal', async () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/workspace' })
-    let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
-    const terminal = {
-      pid: 123, cols: 80, rows: 24, process: 'bash', handleFlowControl: false,
-      onData(listener: (data: string) => void) {
-        queueMicrotask(() => { listener('\x1b]133;D;0\x07dsh> ') })
-        return { dispose() {} }
+    const output = new PassThrough()
+    const outcome = Promise.withResolvers<{ exitCode: number | null; signal: NodeJS.Signals | null }>()
+    const terminal: SubprocessTerminalHandle = {
+      pid: 123,
+      output,
+      done: outcome.promise,
+      write: async () => {},
+      inspectForeground: async () => ({ processGroupId: 123, inputWaiting: true }),
+      signalForeground: async () => 123,
+      terminate() {
+        output.end()
+        outcome.resolve({ exitCode: null, signal: 'SIGTERM' })
       },
-      onExit(listener: (event: { exitCode: number; signal?: number }) => void) {
-        exitListener = listener
-        return { dispose() {} }
-      },
-      write() {},
-      kill() { exitListener?.({ exitCode: 0, signal: 15 }) },
-      resize() {}, clear() {}, pause() {}, resume() {},
-    } as IPty
+      waitForExit: async () => true,
+    }
+    queueMicrotask(() => { output.write(Buffer.from('\x1b]133;D;0\x07dsh> ')) })
     const backend = new LocalPtyBackend(
       ctx,
       config(),
-      { ...inspector, foregroundPgid: () => terminal.pid },
-      () => terminal,
+      async () => terminal,
     )
     const session = await backend.spawn(spec(agent(ctx)))
     expect(session.motd).toBe('dsh> ')
@@ -217,7 +224,7 @@ describe('pty-local plugin shape', () => {
     const loader = Object.create(Loader.prototype) as Loader
     const unwrapped = loader.unwrapExports(ptyLocal) as Record<string, unknown>
     expect(unwrapped.name).toBe('pty-local')
-    expect(unwrapped.inject).toEqual(['pty', 'sandbox', 'sandboxPolicy'])
+    expect(unwrapped.inject).toEqual(['pty', 'sandbox', 'sandboxPolicy', 'subprocess'])
     expect(unwrapped.Config).toBeDefined()
   })
 
@@ -227,6 +234,7 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
     const fiber = await ctx.plugin(ptyLocal, config())
     expect(ctx.pty.listBackends()).toEqual(['shell'])
     await fiber.dispose()
@@ -240,11 +248,12 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
     await ctx.plugin(ptyLocal, config())
 
     const session = ctx.sessions.create(SessionId('unowned-mode'))
     expect(() => {
-      session.append('turn/start', { turn: 1 })
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     }).not.toThrow()
     expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow()
   })
@@ -256,17 +265,13 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(RecordingSandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
 
     const session = ctx.sessions.create(SessionId('mode-owner'))
     const ownerFiber = await ctx.plugin(() => {})
     const owner: Agent = {
-      id: session.id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
-      status: 'idle',
-      ctx: ownerFiber.ctx,
-      send: () => {},
-      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
-      runMaintenance: task => task(new AbortController().signal),
-      whenIdle: () => Promise.resolve(),
+      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx,
+      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
     }
     ctx.agents.register(owner)
     const providerFiber = await registerStubLocalBackend(ctx, () => stubLocalSession())
@@ -275,7 +280,7 @@ describe('pty-local plugin shape', () => {
     const unrelated = ctx.sessions.create(SessionId('unrelated-mode'))
     expect(() => { setSandboxMode(unrelated, 'read-only') }).not.toThrow()
     expect(() => {
-      session.append('turn/start', { turn: 1 })
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     }).not.toThrow()
 
     expect(() => { setSandboxMode(session, 'danger-full-access') }).not.toThrow()
@@ -304,17 +309,13 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(RecordingSandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
 
     const session = ctx.sessions.create(SessionId('pending-mode-owner'))
     const ownerFiber = await ctx.plugin(() => {})
     const owner: Agent = {
-      id: session.id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
-      status: 'idle',
-      ctx: ownerFiber.ctx,
-      send: () => {},
-      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
-      runMaintenance: task => task(new AbortController().signal),
-      whenIdle: () => Promise.resolve(),
+      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx,
+      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
     }
     ctx.agents.register(owner)
     const gate = Promise.withResolvers<undefined>()
diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts
index c57b0ebb8e..c02a9563ea 100644
--- a/packages/pty/pty-local/tests/local.spec.ts
+++ b/packages/pty/pty-local/tests/local.spec.ts
@@ -11,6 +11,7 @@ import type { PtySendOperation } from '@deepseek-ai/dsh-pty'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import * as ptyLocal from '@deepseek-ai/dsh-pty-local'
 
 const roots: string[] = []
@@ -57,6 +58,7 @@ async function harness(
   await ctx.plugin(PtyService)
   await ctx.plugin(PassthroughSandbox)
   await ctx.plugin(SandboxPolicyService, { mode, workspaceRoot: root })
+  await ctx.plugin(LocalSubprocessService)
   const fiber = await ctx.plugin(ptyLocal, {
     pollIntervalMs: 10,
     exactProbeAfterMs: 20,
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 53ce61eebc..7a775eb9a0 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -1,62 +1,17 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import type { IDisposable, IPty } from 'node-pty'
+import { PassThrough } from 'node:stream'
 import { LocalPtySession } from '@deepseek-ai/dsh-pty-local/src/session.ts'
 import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-local/src/config.ts'
-import type { ProcessIdentity, ProcessInspector } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
 import type { PtySendOperation, PtySessionStatus, PtySignal } from '@deepseek-ai/dsh-pty'
-
-class FakeTerminal {
-  pid = 123
-  cols = 80
-  rows = 24
-  process = 'bash'
-  handleFlowControl = false
-  writes: string[] = []
-  kills: string[] = []
-  throwWrite = false
-  throwKill = false
-  autoExitOnKill = true
-  private dataListeners = new Set<(data: string) => void>()
-  private exitListeners = new Set<(event: { exitCode: number; signal?: number }) => void>()
-
-  readonly onData = (listener: (data: string) => void): IDisposable => {
-    this.dataListeners.add(listener)
-    return { dispose: () => this.dataListeners.delete(listener) }
-  }
-
-  readonly onExit = (listener: (event: { exitCode: number; signal?: number }) => void): IDisposable => {
-    this.exitListeners.add(listener)
-    return { dispose: () => this.exitListeners.delete(listener) }
-  }
-
-  emitData(data: string): void {
-    for (const listener of this.dataListeners) listener(data)
-  }
-
-  emitExit(exitCode = 0, signal?: number): void {
-    for (const listener of this.exitListeners) listener({ exitCode, ...signal === undefined ? {} : { signal } })
-  }
-
-  write(data: string): void {
-    if (this.throwWrite) throw new Error('write failed')
-    this.writes.push(data)
-  }
-
-  kill(signal?: string): void {
-    if (this.throwKill) throw new Error('kill failed')
-    this.kills.push(signal ?? 'SIGHUP')
-    if (this.autoExitOnKill) this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
-  }
-
-  resize() {}
-  clear() {}
-  pause() {}
-  resume() {}
-
-  asPty(): IPty {
-    return this
-  }
-}
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSignal,
+} from '@deepseek-ai/dsh-subprocess'
+import type {
+  ProcessIdentity,
+  ProcessInspector,
+} from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
 
 class FakeInspector implements ProcessInspector {
   pgid: number | undefined = 456
@@ -84,6 +39,89 @@ class FakeInspector implements ProcessInspector {
   }
 }
 
+class FakeTerminal implements SubprocessTerminalHandle {
+  pid = 123
+  readonly output = new PassThrough()
+  readonly writes: string[] = []
+  readonly kills: string[] = []
+  readonly outcome = Promise.withResolvers<SubprocessOutcome>()
+  readonly done = this.outcome.promise
+  throwWrite = false
+  throwKill = false
+  autoExitOnKill = true
+  quiescent = true
+  waitError: Error | undefined
+
+  constructor(public inspector = new FakeInspector()) {}
+
+  emitData(data: string): void {
+    this.output.write(Buffer.from(data, 'utf8'))
+  }
+
+  emitBytes(data: Uint8Array): void {
+    this.output.write(data)
+  }
+
+  emitError(error: Error): void {
+    this.output.emit('error', error)
+  }
+
+  emitFailure(error: unknown): void {
+    this.output.end()
+    this.outcome.reject(error)
+  }
+
+  emitExit(exitCode = 0, signal?: number): void {
+    this.output.end()
+    this.outcome.resolve({
+      exitCode: signal === undefined || signal === 0 ? exitCode : null,
+      signal: signal === 9 ? 'SIGKILL' : signal === 15 ? 'SIGTERM' : null,
+    })
+  }
+
+  async write(data: Uint8Array): Promise<void> {
+    if (this.throwWrite) throw new Error('write failed')
+    this.writes.push(Buffer.from(data).toString('utf8'))
+  }
+
+  async inspectForeground() {
+    const processGroupId = this.inspector.foregroundPgid()
+    return processGroupId === undefined
+      ? undefined
+      : { processGroupId, inputWaiting: this.inspector.isStdinWaiting() }
+  }
+
+  async signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
+    const foreground = await this.inspectForeground()
+    if (foreground === undefined) throw new Error(`cannot resolve foreground process group for terminal ${this.pid}`)
+    if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
+      throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
+    }
+    this.inspector.signalGroup(foreground.processGroupId, signal)
+    return foreground.processGroupId
+  }
+
+  terminate(): void {
+    if (this.throwKill) throw new Error('kill failed')
+    this.kills.push('SIGTERM')
+    if (this.autoExitOnKill) this.emitExit(0, 15)
+  }
+
+  async waitForExit(): Promise<boolean> {
+    if (this.waitError !== undefined) throw this.waitError
+    return this.quiescent
+  }
+}
+
+function makeSession(
+  terminal: FakeTerminal,
+  inspector: FakeInspector,
+  resolved: ResolvedConfig,
+): LocalPtySession {
+  terminal.inspector = inspector
+  return new LocalPtySession(terminal, resolved)
+}
+
 function config(overrides: Partial<ResolvedConfig> = {}): ResolvedConfig {
   return {
     backendType: 'shell', shellPath: '/bin/bash', shellArgs: [], rows: 24, cols: 80,
@@ -108,13 +146,15 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
     expect(session.motd).toBe('dsh> ')
 
     inspector.waiting = true
     const operation = session.startSend({ text: 'python3', submit: true })
-    expect(terminal.writes).toEqual(['python3', '\r'])
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(terminal.writes).toEqual(['python3\r'])
     inspector.pgid = 789
     terminal.emitData('Python\r\n>>> ')
     await vi.advanceTimersByTimeAsync(20)
@@ -126,7 +166,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
 
     inspector.waiting = true
@@ -148,7 +188,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({
+    const session = makeSession(terminal, inspector, config({
       exactProbeAfterMs: 50,
       idleSilenceMs: 100,
       timeoutMs: 200,
@@ -173,7 +213,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
     inspector.pgid = undefined
 
@@ -193,7 +233,7 @@ describe('LocalPtySession readiness and output', () => {
 
     const exiting = session.startSend({ text: 'exit', submit: true })
     terminal.emitExit(7, 9)
-    expect(await exiting.done).toMatchObject({ waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: 7, signal: 'SIGKILL' } })
+    expect(await exiting.done).toMatchObject({ waitReason: 'session_exit', sessionStatus: { kind: 'exited', exitCode: null, signal: 'SIGKILL' } })
     expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
   })
 
@@ -201,13 +241,15 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
 
     const controller = new AbortController()
     const operation = session.startSend({ text: 'sleep', submit: true, signal: controller.signal })
     expect(() => session.startSend({ text: 'again', submit: true })).toThrow('active send')
     controller.abort()
+    await Promise.resolve()
+    await Promise.resolve()
     expect(inspector.groups).toContainEqual([456, 'SIGINT'])
     expect(terminal.writes).not.toContain('\x03')
     terminal.emitData('\x1b]133;D;130\x07dsh> ')
@@ -229,14 +271,14 @@ describe('LocalPtySession readiness and output', () => {
   it('handles startup exit, unknown exit signals, cancel-write failure, and stale polls', async () => {
     vi.useFakeTimers()
     const startupTerminal = new FakeTerminal()
-    const startup = new LocalPtySession(startupTerminal.asPty(), new FakeInspector(), config())
+    const startup = new LocalPtySession(startupTerminal, config())
     const initializing = startup.initialize(new AbortController().signal)
     startupTerminal.emitExit(1)
     await expect(initializing).rejects.toThrow('exited during startup')
     expect(startup.status()).toEqual({ kind: 'exited', exitCode: 1, signal: null })
 
     const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal.asPty(), new FakeInspector(), config())
+    const session = new LocalPtySession(terminal, config())
     await initialize(session, terminal)
     const operation = session.startSend({ text: '', submit: false })
     const operationInternal = operation as unknown as {
@@ -247,11 +289,17 @@ describe('LocalPtySession readiness and output', () => {
     const sessionInternal = session as unknown as {
       pollReadiness(operation: PtySendOperation): void
       interrupt(operation: PtySendOperation): void
+      schedulePoll(operation: PtySendOperation): void
+      polling: boolean
       statusValue: PtySessionStatus
       appendOutput(text: string): void
     }
     sessionInternal.appendOutput('')
     sessionInternal.pollReadiness({} as PtySendOperation)
+    sessionInternal.schedulePoll({} as PtySendOperation)
+    sessionInternal.polling = true
+    sessionInternal.schedulePoll(operation)
+    sessionInternal.polling = false
     sessionInternal.interrupt({} as PtySendOperation)
     sessionInternal.statusValue = { kind: 'exited', exitCode: 2, signal: null }
     sessionInternal.pollReadiness(operation)
@@ -259,13 +307,15 @@ describe('LocalPtySession readiness and output', () => {
     operationInternal.settle('timeout', { kind: 'running' }, false)
 
     const unknownTerminal = new FakeTerminal()
-    const unknown = new LocalPtySession(unknownTerminal.asPty(), new FakeInspector(), config())
+    const unknown = new LocalPtySession(unknownTerminal, config())
     unknownTerminal.emitExit(1, 999)
-    expect(unknown.status()).toEqual({ kind: 'exited', exitCode: 1, signal: null })
+    await vi.waitFor(() => {
+      expect(unknown.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+    })
 
     const cancelTerminal = new FakeTerminal()
     const cancelInspector = new FakeInspector()
-    const cancel = new LocalPtySession(cancelTerminal.asPty(), cancelInspector, config())
+    const cancel = makeSession(cancelTerminal, cancelInspector, config())
     await initialize(cancel, cancelTerminal)
     const cancellable = cancel.startSend({ text: '', submit: false })
     cancelInspector.throwGroup = true
@@ -275,7 +325,7 @@ describe('LocalPtySession readiness and output', () => {
 
     const missingGroupTerminal = new FakeTerminal()
     const missingGroupInspector = new FakeInspector()
-    const missingGroup = new LocalPtySession(missingGroupTerminal.asPty(), missingGroupInspector, config())
+    const missingGroup = makeSession(missingGroupTerminal, missingGroupInspector, config())
     await initialize(missingGroup, missingGroupTerminal)
     missingGroupInspector.pgid = undefined
     const unresolved = missingGroup.startSend({ text: '', submit: false })
@@ -286,7 +336,7 @@ describe('LocalPtySession readiness and output', () => {
   it('does not treat zero-output startup silence as readiness and fails on startup timeout', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal.asPty(), new FakeInspector(), config())
+    const session = new LocalPtySession(terminal, config())
     let settled = false
     const initializing = session.initialize().then(() => { settled = true })
     await vi.advanceTimersByTimeAsync(60)
@@ -296,7 +346,7 @@ describe('LocalPtySession readiness and output', () => {
     await initializing
 
     const timeoutTerminal = new FakeTerminal()
-    const timeout = new LocalPtySession(timeoutTerminal.asPty(), new FakeInspector(), config())
+    const timeout = new LocalPtySession(timeoutTerminal, config())
     const timedOut = expect(timeout.initialize()).rejects.toThrow('startup timeout')
     await vi.advanceTimersByTimeAsync(100)
     await timedOut
@@ -306,7 +356,7 @@ describe('LocalPtySession readiness and output', () => {
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
     inspector.pgid = undefined
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     const controller = new AbortController()
     const reason = new Error('startup cancelled')
 
@@ -320,7 +370,7 @@ describe('LocalPtySession readiness and output', () => {
   it('waits for printable prompt text when the startup marker is split from PS1', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal.asPty(), new FakeInspector(), config())
+    const session = new LocalPtySession(terminal, config())
     let settled = false
     const initializing = session.initialize().then(() => { settled = true })
 
@@ -338,7 +388,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
 
     const operation = session.startSend({ text: 'run', submit: true })
@@ -359,7 +409,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({ handoffGraceMs: 40 }))
+    const session = makeSession(terminal, inspector, config({ handoffGraceMs: 40 }))
     await initialize(session, terminal)
 
     const operation = session.startSend({ text: 'run', submit: true })
@@ -380,7 +430,7 @@ describe('LocalPtySession readiness and output', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     await initialize(session, terminal)
 
     const operation = session.startSend({ text: 'bash -i', submit: true })
@@ -390,6 +440,156 @@ describe('LocalPtySession readiness and output', () => {
 
     expect((await operation.done).waitReason).toBe('inferred_idle')
   })
+
+  it('contains terminal transport failures and preserves the first failure', async () => {
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    const operation = session.startSend({ text: '', submit: false })
+    terminal.output.emit('data', 'plain text')
+    terminal.emitError(new Error('output transport failed'))
+    ;(session as unknown as { onTransportFailure(error: unknown): void })
+      .onTransportFailure(new Error('later failure'))
+    await expect(operation.done).rejects.toThrow('output transport failed')
+    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+    await expect(session.close('transport')).rejects.toThrow('output transport failed')
+
+    const rejectedTerminal = new FakeTerminal()
+    const rejected = new LocalPtySession(rejectedTerminal, config())
+    const rejectedOperation = rejected.startSend({ text: '', submit: false })
+    rejectedTerminal.emitFailure('raw transport failure')
+    await expect(rejectedOperation.done).rejects.toThrow('raw transport failure')
+  })
+
+  it('rejects invalid UTF-8 in a data chunk and at stream end', async () => {
+    const chunkTerminal = new FakeTerminal()
+    const chunkSession = new LocalPtySession(chunkTerminal, config())
+    const chunkOperation = chunkSession.startSend({ text: '', submit: false })
+    chunkTerminal.emitBytes(Uint8Array.from([0xff]))
+    await expect(chunkOperation.done).rejects.toThrow('PTY emitted invalid UTF-8')
+
+    const endTerminal = new FakeTerminal()
+    const endSession = new LocalPtySession(endTerminal, config())
+    const endOperation = endSession.startSend({ text: '', submit: false })
+    endTerminal.emitBytes(Uint8Array.from([0xe2]))
+    endTerminal.emitExit()
+    await expect(endOperation.done).rejects.toThrow('PTY ended with invalid UTF-8')
+  })
+
+  it('contains readiness inspection failure and a stale inspection result', async () => {
+    vi.useFakeTimers()
+    const failedTerminal = new FakeTerminal()
+    const failedSession = new LocalPtySession(failedTerminal, config())
+    const failedOperation = failedSession.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    failedTerminal.inspectForeground = async () => { throw new Error('inspect failed') }
+    const failedInternal = failedSession as unknown as {
+      pollReadiness(operation: PtySendOperation): Promise<void>
+    }
+    await failedInternal.pollReadiness(failedOperation)
+    await expect(failedOperation.done).rejects.toThrow('inspect failed')
+
+    const staleTerminal = new FakeTerminal()
+    const staleSession = new LocalPtySession(staleTerminal, config())
+    const staleOperation = staleSession.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    const gate = Promise.withResolvers<ReturnType<FakeTerminal['inspectForeground']> extends Promise<infer T> ? T : never>()
+    staleTerminal.inspectForeground = async () => await gate.promise
+    const staleInternal = staleSession as unknown as {
+      active: PtySendOperation | undefined
+      pollReadiness(operation: PtySendOperation): Promise<void>
+    }
+    const polling = staleInternal.pollReadiness(staleOperation)
+    staleInternal.active = undefined
+    gate.resolve({ processGroupId: 456, inputWaiting: false })
+    await polling
+    ;(staleOperation as unknown as {
+      settle(reason: 'timeout', status: PtySessionStatus, inherited: boolean): void
+    }).settle('timeout', { kind: 'running' }, false)
+  })
+
+  it('contains stale timer, write, inspection, and interrupt continuations', async () => {
+    vi.useFakeTimers()
+    const settle = (operation: PtySendOperation): void => {
+      ;(operation as unknown as {
+        settle(reason: 'timeout', status: PtySessionStatus, inherited: boolean): void
+      }).settle('timeout', { kind: 'running' }, false)
+    }
+
+    const deadlineTerminal = new FakeTerminal()
+    const deadlineSession = new LocalPtySession(deadlineTerminal, config())
+    const deadlineOperation = deadlineSession.startSend({ text: '', submit: false })
+    ;(deadlineSession as unknown as { active: PtySendOperation | undefined }).active = undefined
+    await vi.advanceTimersByTimeAsync(100)
+    settle(deadlineOperation)
+
+    const writeTerminal = new FakeTerminal()
+    const writeGate = Promise.withResolvers<undefined>()
+    writeTerminal.write = async () => { await writeGate.promise }
+    const writeSession = new LocalPtySession(writeTerminal, config())
+    const writeOperation = writeSession.startSend({ text: 'x', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    ;(writeSession as unknown as { closing: boolean }).closing = true
+    writeGate.resolve(undefined)
+    await Promise.resolve()
+    await Promise.resolve()
+    settle(writeOperation)
+
+    const beginTerminal = new FakeTerminal()
+    const beginGate = Promise.withResolvers<never>()
+    beginTerminal.inspectForeground = async () => await beginGate.promise
+    const beginSession = new LocalPtySession(beginTerminal, config())
+    const beginOperation = beginSession.startSend({ text: '', submit: false })
+    ;(beginSession as unknown as { active: PtySendOperation | undefined }).active = undefined
+    beginGate.reject(new Error('stale begin failure'))
+    await Promise.resolve()
+    await Promise.resolve()
+    settle(beginOperation)
+
+    const scheduledTerminal = new FakeTerminal()
+    const scheduledSession = new LocalPtySession(scheduledTerminal, config())
+    const scheduledOperation = scheduledSession.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    const scheduledInternal = scheduledSession as unknown as {
+      schedulePoll(operation: PtySendOperation, delayMs?: number): void
+      settleActive(reason: 'timeout'): void
+    }
+    scheduledInternal.schedulePoll(scheduledOperation, 5)
+    scheduledInternal.settleActive('timeout')
+    await scheduledOperation.done
+
+    const pollTerminal = new FakeTerminal()
+    const pollSession = new LocalPtySession(pollTerminal, config())
+    const pollOperation = pollSession.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    const pollGate = Promise.withResolvers<never>()
+    pollTerminal.inspectForeground = async () => await pollGate.promise
+    const pollInternal = pollSession as unknown as {
+      active: PtySendOperation | undefined
+      pollReadiness(operation: PtySendOperation): Promise<void>
+    }
+    const stalePoll = pollInternal.pollReadiness(pollOperation)
+    pollInternal.active = undefined
+    pollGate.reject(new Error('stale poll failure'))
+    await stalePoll
+    settle(pollOperation)
+
+    const interruptTerminal = new FakeTerminal()
+    const interruptGate = Promise.withResolvers<never>()
+    interruptTerminal.signalForeground = async () => await interruptGate.promise
+    const interruptSession = new LocalPtySession(interruptTerminal, config())
+    const interruptOperation = interruptSession.startSend({ text: '', submit: false })
+    expect(interruptOperation.cancel()).toBe(true)
+    ;(interruptSession as unknown as { active: PtySendOperation | undefined }).active = undefined
+    interruptGate.reject(new Error('stale interrupt failure'))
+    await Promise.resolve()
+    await Promise.resolve()
+    settle(interruptOperation)
+  })
 })
 
 describe('LocalPtySession bounds, signals, and teardown', () => {
@@ -397,8 +597,7 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const session = new LocalPtySession(
-      terminal.asPty(),
-      new FakeInspector(),
+      terminal,
       config({ scrollbackLines: 3, scrollbackMaxBytes: 12, maxReadBytes: 6 }),
     )
     expect(session.read({})).toMatchObject({ text: '' })
@@ -415,7 +614,7 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     expect(() => session.read({ count: 0 })).toThrow('count')
 
     const tinyTerminal = new FakeTerminal()
-    const tiny = new LocalPtySession(tinyTerminal.asPty(), new FakeInspector(), config({ maxReadBytes: 1 }))
+    const tiny = new LocalPtySession(tinyTerminal, config({ maxReadBytes: 1 }))
     await initialize(tiny, tinyTerminal)
     const tinyOperation = tiny.startSend({ text: '', submit: false })
     tinyTerminal.emitData('一')
@@ -427,32 +626,38 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
   it('signals verified groups and refuses unresolved or shell-targeted hard kills', async () => {
     const terminal = new FakeTerminal()
     const inspector = new FakeInspector()
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
+    const session = makeSession(terminal, inspector, config())
     expect(await session.signal('SIGINT')).toEqual({ delivered: true, targetPgid: 456 })
     inspector.pgid = terminal.pid
-    await expect(session.signal('SIGKILL')).rejects.toThrow('use terminal_close')
+    await expect(session.signal('SIGKILL')).rejects.toThrow('terminate the terminal session')
     inspector.pgid = undefined
     await expect(session.signal('SIGTERM')).rejects.toThrow('cannot resolve')
   })
 
   it('closes idempotently, contains signal races, and reports survivors', async () => {
     const terminal = new FakeTerminal()
-    const inspector = new FakeInspector()
-    inspector.members = [{ pid: 123, started: 'a' }]
-    inspector.alive.add(123)
-    inspector.throwProcess = true
-    terminal.throwKill = true
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 1 }))
+    terminal.quiescent = false
+    const session = new LocalPtySession(terminal, config({ disposeGraceMs: 1 }))
     const closing = session.close('test')
     expect(session.close('other')).toBe(closing)
-    await expect(closing).rejects.toThrow('surviving pids: 123')
+    await expect(closing).rejects.toThrow('did not reach quiescence')
     expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
   })
 
+  it('reports cleanup failure without waiting for top-level exit', async () => {
+    const terminal = new FakeTerminal()
+    terminal.autoExitOnKill = false
+    terminal.waitError = new Error('terminal cleanup failed; surviving pids: 456')
+    const session = new LocalPtySession(terminal, config())
+
+    await expect(session.close('survivor')).rejects.toThrow('surviving pids: 456')
+    expect(terminal.kills).toEqual(['SIGTERM'])
+  })
+
   it('settles an active send as session_exit when closed mid-operation', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal.asPty(), new FakeInspector(), config({ disposeGraceMs: 50 }))
+    const session = new LocalPtySession(terminal, config({ disposeGraceMs: 50 }))
     await initialize(session, terminal)
     const operation = session.startSend({ text: 'run', submit: true })
     // The shell returns to its prompt while the send is active; a running
@@ -467,94 +672,4 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     await closing
   })
 
-  it('keeps the shell alive until SIGKILL recipients leave the process table', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const inspector = new FakeInspector()
-    inspector.members = [{ pid: 124, started: 'child' }]
-    inspector.alive.add(124)
-    inspector.removeOnSignal = false
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 20 }))
-
-    let settled = false
-    const closing = session.close('test').then(() => { settled = true })
-    await vi.advanceTimersByTimeAsync(20)
-    expect(inspector.processes).toContainEqual([124, 'SIGKILL'])
-    expect(terminal.kills).toEqual([])
-    expect(settled).toBe(false)
-
-    inspector.alive.delete(124)
-    await vi.advanceTimersByTimeAsync(20)
-    await closing
-    expect(terminal.kills).toEqual(['SIGTERM'])
-    expect(settled).toBe(true)
-  })
-
-  it('rescans for descendants forked during TERM before stopping the shell', async () => {
-    const terminal = new FakeTerminal()
-    const inspector = new FakeInspector()
-    let reads = 0
-    inspector.processTree = () => {
-      reads += 1
-      if (reads === 1) {
-        inspector.alive.add(124)
-        return [{ pid: 124, started: 'first' }]
-      }
-      if (reads === 2) {
-        inspector.alive.add(125)
-        return [{ pid: 125, started: 'late' }]
-      }
-      return []
-    }
-    const session = new LocalPtySession(terminal.asPty(), inspector, config())
-
-    await session.close('test')
-
-    expect(inspector.processes).toEqual([[124, 'SIGTERM'], [125, 'SIGKILL']])
-    expect(terminal.kills).toEqual(['SIGTERM'])
-  })
-
-  it('retains captured survivors that are reparented out of the teardown rescan', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const inspector = new FakeInspector()
-    const captured = { pid: 124, started: 'captured' }
-    let reads = 0
-    inspector.alive.add(captured.pid)
-    inspector.processTree = () => reads++ === 0 ? [captured] : []
-    inspector.signalProcess = (identity, signal) => {
-      inspector.processes.push([identity.pid, signal])
-      if (signal === 'SIGKILL') inspector.alive.delete(identity.pid)
-    }
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 20 }))
-
-    const closing = session.close('test')
-    await vi.advanceTimersByTimeAsync(25)
-    await closing
-
-    expect(inspector.processes).toEqual([[124, 'SIGTERM'], [124, 'SIGKILL']])
-    expect(terminal.kills).toEqual(['SIGTERM'])
-  })
-
-  it('allows teardown to retry after a descendant-survivor failure', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const inspector = new FakeInspector()
-    inspector.members = [{ pid: 124, started: 'child' }]
-    inspector.alive.add(124)
-    inspector.removeOnSignal = false
-    const session = new LocalPtySession(terminal.asPty(), inspector, config({ disposeGraceMs: 10 }))
-
-    const first = session.close('first')
-    const rejected = expect(first).rejects.toThrow('surviving pids: 124')
-    await vi.advanceTimersByTimeAsync(25)
-    await rejected
-    expect(terminal.kills).toEqual([])
-
-    inspector.alive.delete(124)
-    const second = session.close('retry')
-    expect(second).not.toBe(first)
-    await second
-    expect(terminal.kills).toEqual(['SIGTERM'])
-  })
 })
diff --git a/packages/pty/tool-pty/package.json b/packages/pty/tool-pty/package.json
index 5512daba92..9027169941 100644
--- a/packages/pty/tool-pty/package.json
+++ b/packages/pty/tool-pty/package.json
@@ -51,6 +51,7 @@
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "@deepseek-ai/dsh-tasks": "workspace:^",
     "@deepseek-ai/dsh-tasks-local": "workspace:^",
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
diff --git a/packages/pty/tool-pty/tests/loader-composition.spec.ts b/packages/pty/tool-pty/tests/loader-composition.spec.ts
index 835df86abc..35d0ea5d0a 100644
--- a/packages/pty/tool-pty/tests/loader-composition.spec.ts
+++ b/packages/pty/tool-pty/tests/loader-composition.spec.ts
@@ -16,6 +16,7 @@ import PtyService from '@deepseek-ai/dsh-pty'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import * as PtyLocal from '@deepseek-ai/dsh-pty-local'
 import * as ToolPty from '@deepseek-ai/dsh-tool-pty'
 
@@ -72,6 +73,7 @@ suite('terminal real Loader composition through cordis.yml', () => {
       '  config:',
       '    mode: danger-full-access',
       `    workspaceRoot: ${JSON.stringify(root)}`,
+      "- name: '@deepseek-ai/dsh-subprocess-local'",
       "- name: '@deepseek-ai/dsh-pty-local'",
       '  config:',
       '    pollIntervalMs: 10',
@@ -95,6 +97,7 @@ suite('terminal real Loader composition through cordis.yml', () => {
       ['@deepseek-ai/dsh-pty', PtyService],
       ['@deepseek-ai/dsh-test-sandbox', PassthroughSandbox],
       ['@deepseek-ai/dsh-sandbox-policy', SandboxPolicyService],
+      ['@deepseek-ai/dsh-subprocess-local', LocalSubprocessService],
       ['@deepseek-ai/dsh-pty-local', PtyLocal],
       ['@deepseek-ai/dsh-tool-pty', ToolPty],
     ])
diff --git a/packages/skill/skill-local/tests/skill-local.spec.ts b/packages/skill/skill-local/tests/skill-local.spec.ts
index 0f92cac1d6..9dc723fb58 100644
--- a/packages/skill/skill-local/tests/skill-local.spec.ts
+++ b/packages/skill/skill-local/tests/skill-local.spec.ts
@@ -42,6 +42,14 @@ class TestFileSystem extends FileSystem {
     return { targetKey: path as never, displayPath: path }
   }
 
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+
+  override fileUrl(target: FsTarget): string { return `file://${target.targetKey}` }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
+
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     this.statSignals.push(signal)
     if (this.failStatPaths.has(target.displayPath)) throw new FsError('stat failed', 'FS_NOT_FOUND')
@@ -84,6 +92,12 @@ class TestFileSystem extends FileSystem {
     return text
   }
 
+  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
+    const text = await this.readText(target, signal)
+    if (Buffer.byteLength(text) > maxBytes) throw new Error('too large')
+    return text
+  }
+
   override async streamText(_target: FsTarget): Promise<AsyncIterable<string>> {
     throw new Error('not needed in skill tests')
   }
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 9c0cb0c25d..256d4ad2d9 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: 187ea5b778a4bc1f9c3c9121adb18bda11cc7b58
-README.zh.md: dd3a975daec014131877d7b1523810bd932619d8
+README.md: c4bb1da1a172b05afa63834db4e5b1fa974baabb
+README.zh.md: f68bc1c720eeb5282bb9c94c951524a021e38b2f
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index 187ea5b778..c4bb1da1a1 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-This family runs host subprocesses behind an explicit process-lifecycle service.
+The shared process substrate for one execution world: canonical cwd/runtime storage, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and complete session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
-| Package | Role | ctx key |
+| Package | ctx key | Role |
 |---|---|---|
-| [`subprocess/`](subprocess/README.md) | Defines subprocess launch, stream, termination, and disposal contracts | `ctx.subprocess` |
-| [`subprocess-local/`](subprocess-local/README.md) | Implements local process-tree execution | registers on `ctx.subprocess` |
+| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: execution-world coordinates and executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
+| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, runtime storage, and terminate-and-join disposal |
 
-The service owns process lifetime; each consumer owns what the process does and which defaults apply.
+The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index dd3a975dae..f68bc1c720 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -1,12 +1,12 @@
-# subprocess/：子进程能力家族
+# subprocess/：进程管理能力家族
 
 [English](README.md) | 中文
 
-本家族通过显式的进程生命周期服务运行宿主子进程。
+同一执行世界中的共享进程基底：规范化 cwd／运行时存储、可执行文件查找、采用原始或收集式 stdio 的完全显式受管子进程树，以及一项负责 PTY 分配、前台进程组和完整会话清理的深层终端进程原语。命令默认值补全、shell 语义、deadline、协议分帧、就绪检测与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[基于进程管理的 Code Runtime](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[进程管理器 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
-| 包 | 职责 | ctx 键 |
+| 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess/`](subprocess/README.md) | 定义子进程启动、流、终止和 dispose（资源释放）契约 | `ctx.subprocess` |
-| [`subprocess-local/`](subprocess-local/README.md) | 实现本地进程树执行 | 注册到 `ctx.subprocess` |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：执行世界坐标与可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送、运行时存储，以及先终止再等待退出的资源释放 |
 
-服务负责进程生命周期；每个消费方负责进程执行的工作以及所应用的默认值。
+服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 28ebc2c110..d931d3574b 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: af9f92db714398dd52c9b5e7aeb64d5af71021da
-README.zh.md: da78cbcfbff174eb5fda5b8323fbdc84b50c9997
+README.md: 6bc1003ae5903bb5640728bc79c3f9042fddbe7a
+README.zh.md: 3c9ce73c7fcbeec9b17d73f212ecdcb6842ec133
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index af9f92db71..6bc1003ae5 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -2,14 +2,16 @@
 
 English | [中文](README.zh.md)
 
-Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam: `LocalSubprocessService` spawns each spec's argv as a detached process tree, wires the spec's per-stream stdio dispositions (raw pipes, inherit, bounded tail-keep collection with optional spill files), and signals tree-scoped with SIGTERM→SIGKILL escalation. It has no config: every disposition, limit, and directory arrives on the spawn spec, so the deployment-varying knobs stay with the calling seams' configs ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md)).
+Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` owns a private runtime directory, resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), [`dsh-pty-local`](../../pty/pty-local/README.md), and [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)).
 
 ## Behavior (and where it came from)
 
-- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F`. `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — the same caveat as the surveyed tools.
+- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F` (injectable for tests). `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — the same caveat as the surveyed tools.
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
-- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
+- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
+- **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
+- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and cleans descendants before the top-level shell. Linux `/proc`/syscall and macOS `ps` inspectors retain exact pid/start identity so pid reuse cannot redirect cleanup; the higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
 ## Model Experience
@@ -22,8 +24,10 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **Windows tree support is best-effort** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary.
-- **The credential scrub is a name heuristic** — `*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSPHRASE*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
+- **Windows tree support is best-effort and untested in CI** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary; the suites cover the routing through an injected runner only, and `packages/subprocess/*` is excluded from the Windows test matrix.
+- **Terminal process inspection is Linux/macOS only** — the terminal primitive fails when its inspector has no supported platform implementation; Linux exact probes cover x64 and arm64, while macOS uses `ps` snapshots.
+- **A daemonized terminal descendant can escape the captured tree** — a child that reparents before teardown is no longer discoverable from the `node-pty` root. The local provider accepts this gap rather than signal the root PID's POSIX session, which can include unrelated launcher processes.
+- **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
 - **Completed spill files are not deleted** — bounded full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them; oversize incomplete spills are discarded and deletion is attempted immediately, but a cleanup failure can leave a bounded file behind.
 
 The raw process handling lives in `src/spawn.ts`; `src/index.ts` is the service wiring.
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index da78cbcfbf..3c9ce73c7f 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -2,15 +2,17 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现：`LocalSubprocessService` 将每个 spec 的 argv spawn 为 detached 进程树，依照 spec 中按流划分的 stdio 处置方式（disposition）完成接线（原始管道、inherit、附带可选 spill 文件的有界尾部保留收集），并以进程树为范围发送信号，按 SIGTERM→SIGKILL 逐级升级。该实现没有任何配置：每项处置方式、限制与目录都随 spawn spec 传入，因此随部署变化的可调参数留在各调用方 seam 的配置里（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-subagent-acp`](../../subagent/subagent-acp/README.md)）。
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 拥有私有运行时目录，解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 与平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-pty-local`](../../pty/pty-local/README.md)和 [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)）。
 
 ## 行为（以及设计来源）
 
-- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活，这与所调研工具的局限相同。
-- **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
-- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
-- **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
+- **带平台正确信号发送的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树（可为测试注入）。`terminate()`（句柄唯一的终止动词）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；管道与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；脱离该组重新挂载的 daemon 仍可能存活，这与调研工具的局限相同。
+- **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留尾部，即诊断尾部的形状。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需延迟创建的 `0700` 每进程目录之下。
+- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+- **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
+- **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，在资源释放时删除；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并先于顶层 shell 清理后代。Linux 的 `/proc`／syscall 检查器与 macOS 的 `ps` 检查器会保留精确的 pid／启动身份，使 PID 复用无法把清理重定向到其他进程；上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
+- **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
 
@@ -18,12 +20,14 @@
 
 #### KV Cache 影响
 
-不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+不会直接失效；请求前缀变更由具名消费方负责。
 
 ## 已知限制与暂缓事项
 
-- **Windows 进程树支持仅为尽力而为**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界。
-- **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
+- **Windows 进程树支持仅为尽力而为，且未经 CI 测试**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界；测试套件只通过注入的运行器覆盖这条路由，且 `packages/subprocess/*` 被排除在 Windows 测试矩阵之外。
+- **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 使用 `ps` 快照。
+- **守护化的终端后代可能逃离已捕获进程树**：子进程若在拆卸前重新设定父进程，便无法再从 `node-pty` 根发现。本地提供方接受这个缺口，不向根 PID 的 POSIX 会话发送信号，因为其中可能包含无关的启动器进程。
+- **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSWORD*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
 - **不会删除已完成的 spill 文件**：有界的完整输出恢复文件（以及每个进程的私有 spill 目录）会在 OS tmpdir 下累积，直到外部机制进行清理；超大的不完整 spill 会被丢弃并立即尝试删除，但清理失败可能留下一个有界文件。
 
 原始进程处理位于 `src/spawn.ts`；`src/index.ts` 负责服务接线。
diff --git a/packages/subprocess/subprocess-local/package.json b/packages/subprocess/subprocess-local/package.json
index e1429bffd0..7a68a9b91b 100644
--- a/packages/subprocess/subprocess-local/package.json
+++ b/packages/subprocess/subprocess-local/package.json
@@ -21,8 +21,12 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "scripts/ensure-spawn-helper.mjs",
     "lib/types/**/*.d.ts"
   ],
+  "scripts": {
+    "postinstall": "node scripts/ensure-spawn-helper.mjs"
+  },
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
@@ -30,6 +34,9 @@
     "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "dependencies": {
+    "node-pty": "^1.1.0"
+  },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
diff --git a/packages/pty/pty-local/scripts/ensure-spawn-helper.mjs b/packages/subprocess/subprocess-local/scripts/ensure-spawn-helper.mjs
similarity index 100%
rename from packages/pty/pty-local/scripts/ensure-spawn-helper.mjs
rename to packages/subprocess/subprocess-local/scripts/ensure-spawn-helper.mjs
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index eea1f1e739..40d2f52552 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -7,11 +7,26 @@
  * @module @deepseek-ai/dsh-subprocess-local
  */
 
+import { constants } from 'node:fs'
+import { mkdtempSync } from 'node:fs'
+import { access, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { delimiter, extname, isAbsolute, join } from 'node:path'
 import { Context } from 'cordis'
+import * as nodePty from 'node-pty'
+import type { IPtyForkOptions } from 'node-pty'
 import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
-import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
-import { spawnSubprocess } from './spawn.ts'
+import type {
+  SubprocessHandle,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import { childEnv, spawnSubprocess } from './spawn.ts'
 import type { SpawnInternals } from './spawn.ts'
+import { createProcessInspector } from './process-inspector.ts'
+import type { ProcessInspector } from './process-inspector.ts'
+import { LocalTerminalHandle } from './terminal.ts'
 
 /**
  * Local subprocess service: detached process trees, Node-shaped stdio
@@ -20,10 +35,16 @@ import type { SpawnInternals } from './spawn.ts'
  * SIGTERM→grace→SIGKILL escalation.
  */
 export class LocalSubprocessService extends SubprocessService {
+  readonly cwd = process.cwd()
+  readonly runtimeRoot = mkdtempSync(join(tmpdir(), 'dsh-subprocess-runtime-'))
   /** Live handles retained only so disposal can terminate and join them. */
   private live = new Set<SubprocessHandle>()
+  /** Live terminal sessions retained through whole-session quiescence. */
+  private terminals = new Set<SubprocessTerminalHandle>()
   /** Test seam: spill and platform knobs forwarded to spawnSubprocess. */
   internals: SpawnInternals = {}
+  /** Test seam for platform process inspection; production resolves lazily on terminal spawn. */
+  terminalInspector: ProcessInspector | undefined
 
   constructor(ctx: Context) {
     super(ctx)
@@ -37,11 +58,58 @@ export class LocalSubprocessService extends SubprocessService {
         // Spawn-failure rejections already settled and left the live set.
         pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))
       }
+      for (const terminal of this.terminals) {
+        terminal.terminate()
+        // Cleanup may reject before the top-level process exits (for example,
+        // an identity-fenced descendant survives escalation). Await the cleanup
+        // transaction directly so disposal reports that failure rather than
+        // waiting forever on `done`.
+        pending.push(terminal.waitForExit())
+      }
       this.live.clear()
+      this.terminals.clear()
       await Promise.all(pending)
+      await rm(this.runtimeRoot, { recursive: true, force: true })
     }, 'local subprocess teardown')
   }
 
+  async resolveExecutable(
+    command: string,
+    env?: Readonly<Record<string, string>>,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    if (command.length === 0) throw new Error('subprocess-local: executable must be non-empty')
+    signal?.throwIfAborted()
+    const environment = childEnv(env)
+    const absolute = isAbsolute(command)
+    const candidates = absolute ? [command] : this.executableCandidates(command, environment)
+    for (const candidate of candidates) {
+      signal?.throwIfAborted()
+      try {
+        const info = await stat(candidate)
+        if (!info.isFile()) continue
+        await access(candidate, constants.X_OK)
+        signal?.throwIfAborted()
+        return candidate
+      } catch {
+        // Try the next PATH candidate; the final miss receives one stable error.
+      }
+    }
+    signal?.throwIfAborted()
+    throw new Error(absolute
+      ? `subprocess-local: command ${JSON.stringify(command)} is not an executable file`
+      : `subprocess-local: command ${JSON.stringify(command)} was not found on PATH`)
+  }
+
+  private executableCandidates(command: string, env: NodeJS.ProcessEnv): string[] {
+    const path = env.PATH ?? ''
+    const extensions = process.platform === 'win32' && extname(command) === ''
+      ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+      : ['']
+    return path.split(delimiter).flatMap(directory =>
+      directory === '' ? [] : extensions.map(extension => join(directory, command + extension)))
+  }
+
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
     const handle = spawnSubprocess(spec, this.internals)
     this.live.add(handle)
@@ -54,6 +122,38 @@ export class LocalSubprocessService extends SubprocessService {
     handle.done.then(release, release)
     return handle
   }
+
+  // Local PTY allocation is synchronous, but the provider seam permits remote asynchronous allocation.
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    const file = spec.argv[0]
+    if (file === undefined || file.length === 0) {
+      throw new Error('subprocess-local: terminal argv must contain a program')
+    }
+    for (const [name, value] of [['rows', spec.rows], ['cols', spec.cols], ['graceMs', spec.graceMs]] as const) {
+      if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`subprocess-local: terminal ${name} must be a positive safe integer`)
+      }
+    }
+    spec.signal?.throwIfAborted()
+    const options: IPtyForkOptions = {
+      name: 'dumb',
+      rows: spec.rows,
+      cols: spec.cols,
+      cwd: spec.cwd,
+      env: childEnv(spec.env),
+    }
+    const inspector = this.terminalInspector ?? createProcessInspector()
+    const terminal = nodePty.spawn(file, [...spec.argv.slice(1)], options)
+    const handle = new LocalTerminalHandle(terminal, inspector, spec.graceMs, spec.signal)
+    this.terminals.add(handle)
+    const release = async (): Promise<void> => {
+      await handle.waitForExit()
+      this.terminals.delete(handle)
+    }
+    void handle.done.then(release, release).catch(() => {})
+    return handle
+  }
 }
 
 export default LocalSubprocessService
diff --git a/packages/pty/pty-local/src/process-inspector.ts b/packages/subprocess/subprocess-local/src/process-inspector.ts
similarity index 96%
rename from packages/pty/pty-local/src/process-inspector.ts
rename to packages/subprocess/subprocess-local/src/process-inspector.ts
index 5be25a224a..f57184f289 100644
--- a/packages/pty/pty-local/src/process-inspector.ts
+++ b/packages/subprocess/subprocess-local/src/process-inspector.ts
@@ -1,8 +1,8 @@
-/** Platform process-table inspection used for readiness, signals, and teardown. */
+/** Platform process-table inspection for terminal readiness, signals, and teardown. */
 
 import { closeSync, openSync, readFileSync, readdirSync, readSync } from 'node:fs'
 import { execFileSync } from 'node:child_process'
-import type { PtySignal } from '@deepseek-ai/dsh-pty'
+import type { SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess'
 
 /** PID plus start identity, preventing teardown escalation after PID reuse. */
 export interface ProcessIdentity {
@@ -18,7 +18,7 @@ export interface ProcessInspector {
   processTree(rootPid: number): ProcessIdentity[]
   /** Return whether the exact identity remains a non-quiescent process. */
   isAlive(identity: ProcessIdentity): boolean
-  signalGroup(pgid: number, signal: PtySignal): void
+  signalGroup(pgid: number, signal: SubprocessTerminalSignal): void
   signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void
 }
 
@@ -203,7 +203,7 @@ abstract class PosixProcessInspector implements ProcessInspector {
   abstract processTree(rootPid: number): ProcessIdentity[]
   abstract isAlive(identity: ProcessIdentity): boolean
 
-  signalGroup(pgid: number, signal: PtySignal): void {
+  signalGroup(pgid: number, signal: SubprocessTerminalSignal): void {
     this.internals.kill(-pgid, signal)
   }
 
@@ -327,5 +327,5 @@ export function createProcessInspector(
 ): ProcessInspector {
   if (platform === 'linux') return new LinuxProcessInspector(arch, internals)
   if (platform === 'darwin') return new MacProcessInspector(internals)
-  throw new Error(`pty-local: unsupported platform ${platform}`)
+  throw new Error(`subprocess-local: terminal inspection is unsupported on platform ${platform}`)
 }
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
new file mode 100644
index 0000000000..d4b7bd26d1
--- /dev/null
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -0,0 +1,226 @@
+/** Local node-pty terminal-process implementation for the subprocess seam. */
+
+import { Buffer } from 'node:buffer'
+import { constants } from 'node:os'
+import { PassThrough } from 'node:stream'
+import type { IDisposable, IPty } from 'node-pty'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSignal,
+} from '@deepseek-ai/dsh-subprocess'
+import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function signalName(number: number | undefined): NodeJS.Signals | null {
+  if (number === undefined || number === 0) return null
+  for (const [name, value] of Object.entries(constants.signals)) {
+    if (value === number) return name as NodeJS.Signals
+  }
+  return null
+}
+
+/** A local terminal whose process-session ownership stays below the PTY backend. */
+export class LocalTerminalHandle implements SubprocessTerminalHandle {
+  readonly pid: number
+  readonly output = new PassThrough()
+  readonly done: Promise<SubprocessOutcome>
+
+  private readonly outcome = Promise.withResolvers<SubprocessOutcome>()
+  private readonly dataDisposable: IDisposable
+  private readonly exitDisposable: IDisposable
+  private exited = false
+  private termination: Promise<void> | undefined
+  private removeAbort: (() => void) | undefined
+
+  /**
+   * @param terminal - allocated node-pty process.
+   * @param inspector - platform process/session operations.
+   * @param graceMs - TERM-to-KILL and exit-wait grace.
+   * @param signal - optional lifetime cancellation.
+   */
+  constructor(
+    private readonly terminal: IPty,
+    private readonly inspector: ProcessInspector,
+    private readonly graceMs: number,
+    signal?: AbortSignal,
+  ) {
+    this.pid = terminal.pid
+    this.done = this.outcome.promise
+    this.dataDisposable = terminal.onData((data) => { this.output.write(Buffer.from(data, 'utf8')) })
+    this.exitDisposable = terminal.onExit(({ exitCode, signal: exitSignal }) => {
+      if (this.exited) return
+      this.exited = true
+      this.output.end()
+      this.outcome.resolve({
+        exitCode: exitSignal === undefined || exitSignal === 0 ? exitCode : null,
+        signal: signalName(exitSignal),
+      })
+      this.terminate()
+    })
+    if (signal !== undefined) {
+      const onAbort = (): void => { this.terminate() }
+      signal.addEventListener('abort', onAbort, { once: true })
+      this.removeAbort = () => { signal.removeEventListener('abort', onAbort) }
+      if (signal.aborted) this.terminate()
+    }
+  }
+
+  // node-pty writes synchronously; the seam returns a promise for remote transports.
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async write(data: Uint8Array): Promise<void> {
+    if (this.exited) throw new Error('terminal process has exited')
+    let text: string
+    try {
+      text = new TextDecoder('utf-8', { fatal: true }).decode(data)
+    } catch (error: unknown) {
+      throw new Error('terminal input must be valid UTF-8', { cause: error })
+    }
+    this.terminal.write(text)
+  }
+
+  // Local inspection is synchronous; the seam returns a promise for remote transports.
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+    const processGroupId = this.inspector.foregroundPgid(this.pid)
+    if (processGroupId === undefined) return undefined
+    return {
+      processGroupId,
+      inputWaiting: this.inspector.isStdinWaiting(processGroupId),
+    }
+  }
+
+  async signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
+    const foreground = await this.inspectForeground()
+    if (foreground === undefined) {
+      throw new Error(`cannot resolve foreground process group for terminal ${this.pid}`)
+    }
+    if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
+      throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
+    }
+    this.inspector.signalGroup(foreground.processGroupId, signal)
+    return foreground.processGroupId
+  }
+
+  terminate(): void {
+    this.termination ??= this.closeOnce().catch((error: unknown) => {
+      this.termination = undefined
+      throw error
+    })
+    void this.termination.catch(() => {})
+  }
+
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    // A caller may begin waiting before the top-level process exits. The exit
+    // callback starts descendant cleanup in the same turn, so resolve that
+    // eventual transaction after `done` instead of snapshotting only `done`.
+    const quiescence = this.termination ?? this.done.then(() => this.termination)
+    if (signal === undefined) {
+      await quiescence
+      return true
+    }
+    if (signal.aborted) return false
+    return await new Promise<boolean>((resolve, reject) => {
+      const onAbort = (): void => { cleanup(); resolve(false) }
+      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      void quiescence.then(
+        () => { cleanup(); resolve(true) },
+        (error: unknown) => {
+          cleanup()
+          // The owned cleanup transaction only throws Error diagnostics.
+          // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+          reject(error)
+        },
+      )
+    })
+  }
+
+  private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
+    return members.filter(member => this.inspector.isAlive(member))
+  }
+
+  private descendants(): ProcessIdentity[] {
+    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
+  }
+
+  private async waitForMembers(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
+    const until = Date.now() + this.graceMs
+    let survivors = this.survivors(members)
+    while (survivors.length > 0 && Date.now() < until) {
+      await delay(Math.min(25, Math.max(1, until - Date.now())))
+      survivors = this.survivors(members)
+    }
+    return survivors
+  }
+
+  private signalMembers(members: ProcessIdentity[], signal: 'SIGTERM' | 'SIGKILL'): void {
+    for (const member of members) {
+      try {
+        this.inspector.signalProcess(member, signal)
+      } catch (_alreadyExitedDuringSignal) {
+        // The exact process identity is rechecked; a same-tick exit is success.
+      }
+    }
+  }
+
+  private unionMembers(...groups: ProcessIdentity[][]): ProcessIdentity[] {
+    const members: ProcessIdentity[] = []
+    const seen = new Set<string>()
+    for (const group of groups) {
+      for (const member of group) {
+        const key = `${member.pid}:${member.started}`
+        if (seen.has(key)) continue
+        seen.add(key)
+        members.push(member)
+      }
+    }
+    return members
+  }
+
+  private async stopDescendants(): Promise<ProcessIdentity[]> {
+    const captured = this.descendants()
+    this.signalMembers(captured, 'SIGTERM')
+    const capturedSurvivors = await this.waitForMembers(captured)
+    const members = this.unionMembers(capturedSurvivors, this.descendants())
+    this.signalMembers(members, 'SIGKILL')
+    const survivors = await this.waitForMembers(members)
+    return this.survivors(this.unionMembers(survivors, this.descendants()))
+  }
+
+  private async stopShell(): Promise<void> {
+    if (!this.exited) {
+      try {
+        this.terminal.kill('SIGTERM')
+      } catch (_topLevelAlreadyExitedDuringTerm) {
+        // The exit callback is authoritative.
+      }
+      await Promise.race([this.done.then(() => undefined), delay(this.graceMs)])
+    }
+    if (!this.exited) {
+      try {
+        this.terminal.kill('SIGKILL')
+      } catch (_topLevelAlreadyExitedDuringKill) {
+        // The exit callback is authoritative.
+      }
+      await Promise.race([this.done.then(() => undefined), delay(this.graceMs)])
+    }
+    if (!this.exited) throw new Error(`terminal cleanup failed; surviving pid: ${this.pid}`)
+  }
+
+  private async closeOnce(): Promise<void> {
+    const survivors = await this.stopDescendants()
+    if (survivors.length > 0) {
+      throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
+    }
+    await this.stopShell()
+    this.removeAbort?.()
+    this.removeAbort = undefined
+    this.dataDisposable.dispose()
+    this.exitDisposable.dispose()
+  }
+}
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index ca723fdb87..bc77d24cfd 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,7 +1,10 @@
-import { describe, expect, it } from 'vitest'
+import { PassThrough } from 'node:stream'
+import { describe, expect, it, vi } from 'vitest'
+import { stat } from 'node:fs/promises'
+import { basename, delimiter, dirname } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
-import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import type { SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 
 function spec(command: string, overrides: Partial<SubprocessSpawnSpec> = {}): SubprocessSpawnSpec {
   return {
@@ -18,6 +21,133 @@ function spec(command: string, overrides: Partial<SubprocessSpawnSpec> = {}): Su
 }
 
 describe('LocalSubprocessService', () => {
+  it('publishes execution-world paths and removes its private runtime directory', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const root = ctx.subprocess.runtimeRoot
+    expect(ctx.subprocess.cwd).toBe(process.cwd())
+    expect((await stat(root)).isDirectory()).toBe(true)
+    await fiber.dispose()
+    await expect(stat(root)).rejects.toMatchObject({ code: 'ENOENT' })
+  })
+
+  it('resolves absolute and PATH executables and honors lookup cancellation', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    expect(await ctx.subprocess.resolveExecutable(process.execPath)).toBe(process.execPath)
+    expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), {
+      PATH: dirname(process.execPath),
+    })).toBe(process.execPath)
+    await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('must be non-empty')
+    await expect(ctx.subprocess.resolveExecutable('dsh-command-that-does-not-exist', { PATH: '' }))
+      .rejects.toThrow('was not found on PATH')
+    await expect(ctx.subprocess.resolveExecutable('/dsh-absolute-command-that-does-not-exist'))
+      .rejects.toThrow('is not an executable file')
+    await expect(ctx.subprocess.resolveExecutable(process.cwd()))
+      .rejects.toThrow('is not an executable file')
+    await expect(ctx.subprocess.resolveExecutable(process.execPath, {}, AbortSignal.abort('stop')))
+      .rejects.toBe('stop')
+    await fiber.dispose()
+  })
+
+  it('builds Windows executable candidates without empty PATH entries', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const service = ctx.subprocess as LocalSubprocessService
+    const candidates = (service as unknown as {
+      executableCandidates(command: string, env: NodeJS.ProcessEnv): string[]
+    }).executableCandidates.bind(service)
+    const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
+    try {
+      expect(candidates('tool', { PATH: `${delimiter}/bin`, PATHEXT: '.EXE;.CMD' }))
+        .toEqual(['/bin/tool.EXE', '/bin/tool.CMD'])
+      expect(candidates('tool.exe', {})).toEqual([])
+      expect(candidates('tool', { PATH: '/bin' })).toHaveLength(4)
+    } finally {
+      platform.mockRestore()
+      await fiber.dispose()
+    }
+  })
+
+  it('validates terminal spawn specs before allocating a PTY', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const base: SubprocessTerminalSpawnSpec = {
+      argv: ['bash'], cwd: process.cwd(), rows: 24, cols: 80, graceMs: 10,
+    }
+    await expect(ctx.subprocess.spawnTerminal({ ...base, argv: [] })).rejects.toThrow('must contain a program')
+    await expect(ctx.subprocess.spawnTerminal({ ...base, argv: [''] })).rejects.toThrow('must contain a program')
+    await expect(ctx.subprocess.spawnTerminal({ ...base, rows: 1.5 })).rejects.toThrow('rows')
+    await expect(ctx.subprocess.spawnTerminal({ ...base, cols: 0 })).rejects.toThrow('cols')
+    await expect(ctx.subprocess.spawnTerminal({ ...base, graceMs: 0 })).rejects.toThrow('graceMs')
+    await expect(ctx.subprocess.spawnTerminal({ ...base, signal: AbortSignal.abort('stop') })).rejects.toBe('stop')
+    await fiber.dispose()
+  })
+
+  it('terminates and joins an owned terminal during disposal', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const terminate = vi.fn()
+    const waitForExit = vi.fn(async () => true)
+    const terminal: SubprocessTerminalHandle = {
+      pid: 1,
+      output: new PassThrough(),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+      write: async () => {},
+      inspectForeground: async () => undefined,
+      signalForeground: async () => 1,
+      terminate,
+      waitForExit,
+    }
+    ;(ctx.subprocess as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals.add(terminal)
+    await fiber.dispose()
+    expect(terminate).toHaveBeenCalledOnce()
+    expect(waitForExit).toHaveBeenCalledOnce()
+  })
+
+  it('contains a terminal release failure after top-level exit', async () => {
+    let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
+    const terminal = {
+      pid: 123,
+      onData: () => ({ dispose: () => {} }),
+      onExit: (listener: (event: { exitCode: number; signal?: number }) => void) => {
+        exitListener = listener
+        return { dispose: () => {} }
+      },
+      write: () => {},
+      kill: () => {},
+    }
+    vi.resetModules()
+    vi.doMock('node-pty', () => ({ spawn: () => terminal }))
+    try {
+      const { default: IsolatedLocalSubprocessService } = await import('../src/index.ts')
+      const ctx = new Context()
+      const fiber = await ctx.plugin(IsolatedLocalSubprocessService)
+      const alive = new Set([124])
+      ;(ctx.subprocess as InstanceType<typeof IsolatedLocalSubprocessService>).terminalInspector = {
+        foregroundPgid: () => 123,
+        isStdinWaiting: () => false,
+        processTree: () => [{ pid: 124, started: 'child' }],
+        isAlive: identity => alive.has(identity.pid),
+        signalGroup: () => {},
+        signalProcess: () => {},
+      }
+      const handle = await ctx.subprocess.spawnTerminal({
+        argv: ['shell'], cwd: process.cwd(), rows: 24, cols: 80, graceMs: 1,
+      })
+      exitListener?.({ exitCode: 0 })
+      await handle.done
+      await new Promise(resolve => setTimeout(resolve, 10))
+      alive.clear()
+      handle.terminate()
+      await handle.waitForExit()
+      await fiber.dispose()
+    } finally {
+      vi.doUnmock('node-pty')
+      vi.resetModules()
+    }
+  })
+
   it('registers as ctx.subprocess and spawns managed handles', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
diff --git a/packages/pty/pty-local/tests/process-inspector.spec.ts b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
similarity index 98%
rename from packages/pty/pty-local/tests/process-inspector.spec.ts
rename to packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
index 218a3d77fe..e8ad2fd11e 100644
--- a/packages/pty/pty-local/tests/process-inspector.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { createProcessInspector, parseProcStat } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
-import type { ProcessInspectorInternals } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
+import { createProcessInspector, parseProcStat } from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
+import type { ProcessInspectorInternals } from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
 
 function stat(pid: number, pgrp: number, session: number, tpgid: number, started: string, parentPid = 1, state = 'S'): string {
   const rest = [state, String(parentPid), String(pgrp), String(session), '99', String(tpgid)]
@@ -216,6 +216,6 @@ describe('macOS process inspector', () => {
     expect(createProcessInspector('darwin', 'arm64', fake.internals).foregroundPgid(1)).toBeUndefined()
     fake.internals.exec = () => { throw new Error('gone') }
     expect(createProcessInspector('darwin', 'arm64', fake.internals).foregroundPgid(1)).toBeUndefined()
-    expect(() => createProcessInspector('win32', 'x64', fake.internals)).toThrow('unsupported platform win32')
+    expect(() => createProcessInspector('win32', 'x64', fake.internals)).toThrow('unsupported on platform win32')
   })
 })
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
new file mode 100644
index 0000000000..417fd62517
--- /dev/null
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -0,0 +1,275 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { IDisposable, IPty } from 'node-pty'
+import { LocalTerminalHandle } from '@deepseek-ai/dsh-subprocess-local/src/terminal.ts'
+import type {
+  ProcessIdentity,
+  ProcessInspector,
+} from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
+import type { SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess'
+
+class FakePty {
+  pid = 123
+  readonly writes: string[] = []
+  readonly kills: string[] = []
+  autoExitOnKill = true
+  throwKill = false
+  private readonly dataListeners = new Set<(data: string) => void>()
+  private readonly exitListeners = new Set<(event: { exitCode: number; signal?: number }) => void>()
+
+  readonly onData = (listener: (data: string) => void): IDisposable => {
+    this.dataListeners.add(listener)
+    return { dispose: () => { this.dataListeners.delete(listener) } }
+  }
+
+  readonly onExit = (listener: (event: { exitCode: number; signal?: number }) => void): IDisposable => {
+    this.exitListeners.add(listener)
+    return { dispose: () => { this.exitListeners.delete(listener) } }
+  }
+
+  emitData(data: string): void {
+    for (const listener of this.dataListeners) listener(data)
+  }
+
+  emitExit(exitCode = 0, signal?: number): void {
+    for (const listener of this.exitListeners) listener({ exitCode, ...signal === undefined ? {} : { signal } })
+  }
+
+  write(data: string): void { this.writes.push(data) }
+
+  kill(signal?: string): void {
+    if (this.throwKill) throw new Error('process raced')
+    this.kills.push(signal ?? 'SIGHUP')
+    if (this.autoExitOnKill) this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
+  }
+
+  asPty(): IPty {
+    return this as unknown as IPty
+  }
+}
+
+class FakeInspector implements ProcessInspector {
+  pgid: number | undefined = 456
+  waiting = false
+  members: ProcessIdentity[] = []
+  readonly alive = new Set<number>()
+  readonly groups: Array<[number, SubprocessTerminalSignal]> = []
+  readonly processes: Array<[number, 'SIGTERM' | 'SIGKILL']> = []
+  throwGroup = false
+  throwProcess = false
+  removeOnSignal = true
+
+  foregroundPgid() { return this.pgid }
+  isStdinWaiting() { return this.waiting }
+  processTree() { return this.members }
+  isAlive(identity: ProcessIdentity) { return this.alive.has(identity.pid) }
+  signalGroup(pgid: number, signal: SubprocessTerminalSignal) {
+    if (this.throwGroup) throw new Error('group failed')
+    this.groups.push([pgid, signal])
+  }
+  signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL') {
+    if (this.throwProcess) throw new Error('process raced')
+    this.processes.push([identity.pid, signal])
+    if (this.removeOnSignal) this.alive.delete(identity.pid)
+  }
+}
+
+afterEach(() => { vi.useRealTimers() })
+
+describe('LocalTerminalHandle', () => {
+  it('bridges terminal bytes, foreground control, and signalled exit facts', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    inspector.waiting = true
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+    const chunks: Buffer[] = []
+    handle.output.on('data', (chunk: Buffer) => { chunks.push(chunk) })
+
+    pty.emitData('hello €')
+    await handle.write(Buffer.from('input\r'))
+    expect(pty.writes).toEqual(['input\r'])
+    expect(await handle.inspectForeground()).toEqual({ processGroupId: 456, inputWaiting: true })
+    expect(await handle.signalForeground('SIGINT')).toBe(456)
+    expect(inspector.groups).toEqual([[456, 'SIGINT']])
+
+    pty.emitExit(7, 9)
+    pty.emitExit(0)
+    expect(await handle.done).toEqual({ exitCode: null, signal: 'SIGKILL' })
+    expect(await handle.waitForExit()).toBe(true)
+    expect(Buffer.concat(chunks).toString('utf8')).toBe('hello €')
+  })
+
+  it('rejects invalid input and unsafe foreground signals', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+    await expect(handle.write(Uint8Array.from([0xff]))).rejects.toThrow('valid UTF-8')
+
+    inspector.pgid = handle.pid
+    await expect(handle.signalForeground('SIGKILL')).rejects.toThrow('terminate the terminal session')
+    inspector.pgid = undefined
+    expect(await handle.inspectForeground()).toBeUndefined()
+    await expect(handle.signalForeground('SIGTERM')).rejects.toThrow('cannot resolve')
+
+    pty.emitExit(3)
+    expect(await handle.done).toEqual({ exitCode: 3, signal: null })
+    await handle.waitForExit()
+    await expect(handle.write(Buffer.from('late'))).rejects.toThrow('has exited')
+  })
+
+  it('keeps the shell alive until forced descendants leave', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 124, started: 'child' }]
+    inspector.alive.add(124)
+    inspector.removeOnSignal = false
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
+
+    handle.terminate()
+    const quiescent = handle.waitForExit()
+    await vi.advanceTimersByTimeAsync(20)
+    expect(inspector.processes).toContainEqual([124, 'SIGKILL'])
+    expect(pty.kills).toEqual([])
+
+    inspector.alive.delete(124)
+    await vi.advanceTimersByTimeAsync(20)
+    expect(await quiescent).toBe(true)
+    expect(pty.kills).toEqual(['SIGTERM'])
+  })
+
+  it('keeps an early exit wait pending through descendant cleanup', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 124, started: 'child' }]
+    inspector.alive.add(124)
+    inspector.removeOnSignal = false
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
+    const waiting = handle.waitForExit()
+    let settled = false
+    void waiting.then(() => { settled = true })
+
+    pty.emitExit()
+    await vi.advanceTimersByTimeAsync(10)
+    expect(settled).toBe(false)
+
+    inspector.alive.delete(124)
+    await vi.advanceTimersByTimeAsync(20)
+    expect(await waiting).toBe(true)
+  })
+
+  it('rescans for descendants forked during TERM', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    let reads = 0
+    inspector.processTree = () => {
+      reads += 1
+      if (reads === 1) {
+        inspector.alive.add(124)
+        return [{ pid: 124, started: 'first' }]
+      }
+      if (reads === 2) {
+        inspector.alive.add(125)
+        return [{ pid: 125, started: 'late' }]
+      }
+      return []
+    }
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+    handle.terminate()
+    await handle.waitForExit()
+    expect(inspector.processes).toEqual([[124, 'SIGTERM'], [125, 'SIGKILL']])
+    expect(pty.kills).toEqual(['SIGTERM'])
+  })
+
+  it('retains captured descendants after reparenting', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const captured = { pid: 124, started: 'captured' }
+    let reads = 0
+    inspector.alive.add(captured.pid)
+    inspector.processTree = () => reads++ === 0 ? [captured] : []
+    inspector.signalProcess = (identity, signal) => {
+      inspector.processes.push([identity.pid, signal])
+      if (signal === 'SIGKILL') inspector.alive.delete(identity.pid)
+    }
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
+    handle.terminate()
+    const quiescent = handle.waitForExit()
+    await vi.advanceTimersByTimeAsync(25)
+    expect(await quiescent).toBe(true)
+    expect(inspector.processes).toEqual([[124, 'SIGTERM'], [124, 'SIGKILL']])
+  })
+
+  it('allows cleanup to retry after a surviving descendant leaves', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 124, started: 'child' }]
+    inspector.alive.add(124)
+    inspector.removeOnSignal = false
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+
+    handle.terminate()
+    const first = expect(handle.waitForExit(new AbortController().signal)).rejects.toThrow('surviving pids: 124')
+    await vi.advanceTimersByTimeAsync(25)
+    await first
+
+    inspector.alive.delete(124)
+    handle.terminate()
+    expect(await handle.waitForExit()).toBe(true)
+    expect(pty.kills).toEqual(['SIGTERM'])
+  })
+
+  it('bounds waits and reports a top-level process that ignores escalation', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    pty.autoExitOnKill = false
+    const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10)
+    expect(await handle.waitForExit(AbortSignal.abort())).toBe(false)
+    const controller = new AbortController()
+    const bounded = handle.waitForExit(controller.signal)
+    controller.abort()
+    expect(await bounded).toBe(false)
+
+    handle.terminate()
+    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pid: 123')
+    await vi.advanceTimersByTimeAsync(25)
+    await failed
+    expect(pty.kills).toEqual(['SIGTERM', 'SIGKILL'])
+
+    pty.emitExit(0, 999)
+    expect(await handle.done).toEqual({ exitCode: null, signal: null })
+    handle.terminate()
+    expect(await handle.waitForExit()).toBe(true)
+  })
+
+  it('contains process races and reacts to lifetime cancellation', async () => {
+    const pty = new FakePty()
+    pty.throwKill = true
+    const inspector = new FakeInspector()
+    inspector.members = [{ pid: 124, started: 'child' }]
+    inspector.alive.add(124)
+    inspector.throwProcess = true
+    const controller = new AbortController()
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 1, controller.signal)
+    controller.abort()
+    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pids: 124')
+    await failed
+
+    inspector.alive.delete(124)
+    pty.throwKill = false
+    handle.terminate()
+    await handle.waitForExit()
+
+    const preAbortedPty = new FakePty()
+    const preAborted = new LocalTerminalHandle(
+      preAbortedPty.asPty(),
+      new FakeInspector(),
+      1,
+      AbortSignal.abort('stop'),
+    )
+    await preAborted.waitForExit()
+    expect(preAbortedPty.kills).toEqual(['SIGTERM'])
+  })
+})
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index b178daafb2..84d7d4a666 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: e59dd96df036826f36bd0286c977438d2d87d1cf
-README.zh.md: e8fb89dfd1f8c41a0caefc96469c13d9ae7d415d
+README.md: 84b4b0c11c74c96929fa97b58fb33156d44e6ef1
+README.zh.md: dbd80a1c975719884481501f5cc43798e464a4fb
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index e59dd96df0..84b4b0c11c 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -2,15 +2,17 @@
 
 English | [中文](README.zh.md)
 
-The subprocess seam (`ctx.subprocess`). The abstract `SubprocessService` exposes one method — `spawn(spec): SubprocessHandle` — plus the vocabulary shared by every consumer: the fully-explicit `SubprocessSpawnSpec`, `SubprocessHandle` with its non-consuming offset-based output readers, `SubprocessOutcome`, `CollectedOutput`, and the managed `DSH_*` environment namespace (`DSH_ENV_PREFIX`, `DshEnvironment`). The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
+The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessService` exposes its canonical `cwd`, private `runtimeRoot`, executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
 
 ## Contract
 
 - `spawn(spec)` returns immediately with a live handle; `done` resolves at process close with exit facts (`SubprocessOutcome` carries no output and no cause classification) and rejects only for spawn-level failures.
-- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). Grace must be positive, finite, and no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), so the implementation can represent it with one Node timer instead of accepting a value that Node collapses to one millisecond. `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
+- `cwd` and `runtimeRoot` are absolute paths in the provider's execution world. Consumers materialize private helpers below `runtimeRoot`, never in a host-only temp directory. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
+- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and the spec's explicit `env` merges after the scrub with no namespace validation — a string deliberately forwards or overrides a value, while an `undefined` tombstone removes an ordinary ambient entry. Spawners that cannot route through the service (node-pty backends, SDK-managed transports) import the scrub.
+- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, valid-UTF-8 byte I/O, foreground-process-group inspection/signalling, TERM-to-KILL whole-session cleanup, and a quiescence wait. The output stream ends after queued output when the top-level process exits; a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or prove and clean the complete terminal session; readiness, scrollback, and owner policy remain in the PTY consumer.
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
 See the [subprocess data-structure catalog](../../../docs/core-data-structures/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
@@ -25,5 +27,5 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **node-pty and SDK-managed spawns share only the scrub** — the PTY backend's terminal fork and the MCP SDK's own stdio transport cannot route their spawns through this seam (the library owns the fork/spawn call); they import `scrubbedParentEnv` so the environment policy stays single-sourced.
+- **SDK-managed spawns remain outside** — an SDK transport that owns its internal spawn cannot route that call through this service; it can still import `scrubbedParentEnv` so environment policy stays single-sourced.
 - **Teardown ladders are consumer-owned** — the seam ships signalling verbs and the tree-liveness wait, not a canned quiesce sequence; each out-of-process consumer encodes its child's cooperation shape itself (the ACP backend's stdin-EOF-first ladder is the in-repo template).
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index e8fb89dfd1..dbd80a1c97 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -2,28 +2,30 @@
 
 [English](README.md) | 中文
 
-子进程 seam（`ctx.subprocess`）。抽象的 `SubprocessService` 只暴露一个方法：`spawn(spec): SubprocessHandle`，外加所有消费方共享的词汇：完全显式的 `SubprocessSpawnSpec`、携带基于偏移量的非消费式输出读取器的 `SubprocessHandle`、`SubprocessOutcome`、`CollectedOutput`，以及受管的 `DSH_*` 环境命名空间（`DSH_ENV_PREFIX`、`DshEnvironment`）。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
+进程管理器 seam（`ctx.subprocess`）是同一执行世界中的进程侧。抽象的 `SubprocessService` 公开其规范化 `cwd`、私有 `runtimeRoot`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
 
 ## 契约
 
-- `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
-- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样实现便可用一个 Node 定时器表示它，而不会接受会被 Node 折叠为 1 毫秒的值。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
-- stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
+- `spawn(spec)` 立即返回一个实时句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
+- `cwd` 与 `runtimeRoot` 是提供方执行世界中的绝对路径。消费方在 `runtimeRoot` 下物化私有辅助程序，绝不使用仅宿主可见的临时目录。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
+- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的进程管理器默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
+- stdio 按流采用 Node 形状：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，spec 的显式 `env` 在清理后合并且不做命名空间校验——字符串会有意转发或覆盖某个值，而 `undefined` tombstone 则会删除普通的环境条目。无法把 spawn 路由到该服务的进程启动方（node-pty 后端、由 SDK 管理的传输层）会导入该环境清理定义。
+- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、有效 UTF-8 字节 I/O、前台进程组检查／信号发送、TERM→KILL 全会话清理，以及等待完全停稳。顶层进程退出后，输出流会在排完队列中的输出后结束；存活期间的传输故障会拒绝 `done`。这些操作仍属于一项基底原语，因为普通管道无法分配控制终端，也无法证明并清理完整的终端会话；就绪检测、scrollback 与所有者策略仍归 PTY 消费方所有。
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的凭据清除定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地普通 spawn 与终端 spawn 都应用这一定义；自行拥有 spawn 的 SDK 管理传输层可以直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
-参见[子进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与[seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+参见[进程管理器数据结构目录](../../../docs/core-data-structures/subprocess.md)与 [seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 ## 模型体验
 
-通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出和生命周期的全部面向模型渲染均由消费方负责。
+通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出与生命周期面向模型的全部渲染归消费方所有。
 
 #### KV Cache 影响
 
-不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+不会直接失效；请求前缀变更由具名消费方负责。
 
 ## 已知限制与暂缓事项
 
-- **node-pty 与由 SDK 管理的 spawn 只共享环境清理**：PTY 后端的终端 fork 与 MCP SDK 自己的 stdio 传输层无法把 spawn 路由到这道 seam（fork/spawn 调用归库所有）；它们改为导入 `scrubbedParentEnv`，使环境策略保持单一来源。
-- **拆卸阶梯归消费方所有**：该 seam 只提供信号动词与进程树存活等待，不提供现成的停稳序列；每个进程外消费方自行编码其子进程的配合方式（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。
+- **由 SDK 管理的 spawn 仍在服务之外**：自行拥有内部 spawn 的 SDK 传输层无法经该服务路由这次调用；它仍可导入 `scrubbedParentEnv`，使环境策略保持单一来源。
+- **拆卸阶梯归消费方所有**：该 seam 只提供信号动词与进程树存活等待，不提供现成的停稳序列；每个进程外消费方自行编码其子进程的配合形状（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index d484faa24d..3c58a07a9e 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -1,10 +1,9 @@
 /**
- * The subprocess seam (`ctx.subprocess`): spawn fully-specified commands into
- * managed process trees with Node-shaped stdio dispositions — raw pipes for
- * protocol streams, inherit for diagnostics, bounded spill-backed collection
- * for batch output — plus tree-scoped signalling. Command defaulting, shell
- * semantics, deadlines, teardown ladders, framing, and presentation belong to
- * consumers; the bash executor seam is the owning template. The local implementation lives in
+ * The subprocess seam (`ctx.subprocess`): execution-world process coordinates,
+ * executable lookup, fully specified managed process trees with raw or
+ * collected stdio, and one terminal-process primitive. Command defaulting,
+ * shell semantics, deadlines, protocol framing, terminal readiness, and
+ * presentation belong to consumers. The local implementation lives in
  * `@deepseek-ai/dsh-subprocess-local`.
  * @module @deepseek-ai/dsh-subprocess
  */
@@ -12,6 +11,7 @@
 import { Context, Service } from 'cordis'
 import { DSH_ENV_PREFIX } from './types.ts'
 import type { SubprocessHandle, SubprocessSpawnSpec } from './types.ts'
+import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from './types.ts'
 
 export { DSH_ENV_PREFIX } from './types.ts'
 export type {
@@ -28,6 +28,10 @@ export type {
   SubprocessSpawnSpec,
   SubprocessStdinMode,
   SubprocessStdio,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSignal,
+  SubprocessTerminalSpawnSpec,
 } from './types.ts'
 
 /**
@@ -74,6 +78,8 @@ declare module 'cordis' {
  * duplicate-service behavior).
  *
  * Implementations must honor these semantics:
+ * - {@link cwd}, {@link runtimeRoot}, and executable paths belong to one
+ *   execution world shared with the mounted filesystem provider.
  * - {@link spawn} returns immediately with a live handle; `done` resolves at
  *   process close with exit facts and rejects only for spawn-level failures.
  * - Collect-mode readers are offset-based and non-consuming, so independent
@@ -87,12 +93,37 @@ declare module 'cordis' {
  *   quiescence.
  * - Disposal of the service terminates all still-running managed processes
  *   and awaits their exit.
+ * - {@link spawnTerminal} owns terminal allocation, byte transport,
+ *   foreground groups, signalling, and whole-session quiescence; readiness
+ *   and persistent-shell policy stay in the PTY consumer. Its output stream
+ *   ends after queued terminal output when the top-level process exits.
  */
 export abstract class SubprocessService extends Service {
   constructor(ctx: Context) {
     super(ctx, 'subprocess')
   }
 
+  /** Canonical default cwd in this provider's execution world. */
+  abstract readonly cwd: string
+
+  /** Private directory for runtime artifacts in this provider's execution world. */
+  abstract readonly runtimeRoot: string
+
+  /**
+   * Resolve one configured executable in this provider's execution world.
+   * Absolute paths are verified; bare names use the provider's scrubbed PATH
+   * plus explicit environment overrides.
+   * @param command - absolute executable path or bare PATH name.
+   * @param env - explicit environment entries used for lookup.
+   * @param signal - aborts remote or local lookup.
+   * @returns a canonical executable path.
+   */
+  abstract resolveExecutable(
+    command: string,
+    env?: Readonly<Record<string, string>>,
+    signal?: AbortSignal,
+  ): Promise<string>
+
   /**
    * Start one managed child process from a fully-specified spec; this seam
    * applies no defaults.
@@ -100,6 +131,15 @@ export abstract class SubprocessService extends Service {
    * @returns the live process handle (streams/readers, signalling, outcome promise).
    */
   abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
+
+  /**
+   * Allocate a real terminal and start one owned process session. This is the
+   * only non-pipe process primitive: implementations own terminal byte I/O,
+   * foreground groups, signals, and complete session-tree cleanup.
+   * @param spec - fully specified argv, cwd, environment, dimensions, grace, and cancellation.
+   * @returns the live terminal handle after allocation succeeds.
+   */
+  abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
 }
 
 export default SubprocessService
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index 6084cc8c8e..206104ad5b 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -192,3 +192,71 @@ export interface SubprocessHandle {
    */
   waitForExit(signal?: AbortSignal): Promise<boolean>
 }
+
+/** Signals supported by the terminal-process primitive. */
+export type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP'
+
+/** A fully specified terminal-process spawn. */
+export interface SubprocessTerminalSpawnSpec {
+  /** Executable and arguments; `argv[0]` is the program. */
+  argv: readonly string[]
+  /** Working directory in this subprocess provider's execution world. */
+  cwd: string
+  /** Explicit environment layered after the provider's ambient scrub. */
+  env?: Record<string, string> | undefined
+  /** Initial terminal row count. */
+  rows: number
+  /** Initial terminal column count. */
+  cols: number
+  /** TERM-to-KILL cleanup grace for the complete terminal session. */
+  graceMs: number
+  /** Cancellation of setup or the live terminal session. */
+  signal?: AbortSignal | undefined
+}
+
+/** Current foreground process-group facts for one terminal. */
+export interface SubprocessTerminalForeground {
+  /** Foreground process-group id published by the terminal driver. */
+  processGroupId: number
+  /** Whether the provider can currently prove that group is waiting on terminal input. */
+  inputWaiting: boolean
+}
+
+/**
+ * One live terminal process and its owned OS session. Terminal allocation,
+ * foreground-group inspection/signalling, and session-tree cleanup are one
+ * deep subprocess primitive because none can be reconstructed from ordinary
+ * piped stdio without substrate-specific process control.
+ */
+export interface SubprocessTerminalHandle {
+  /** Top-level terminal process id. */
+  readonly pid: number
+  /** UTF-8 terminal output bytes in delivery order; ends after queued output when the terminal exits. */
+  readonly output: Readable
+  /** Resolves when the top-level process exits; rejects only for a live transport failure. */
+  readonly done: Promise<SubprocessOutcome>
+  /**
+   * Write bytes to the terminal input.
+   * @param data - valid UTF-8 bytes to deliver without implicit newline conversion.
+   */
+  write(data: Uint8Array): Promise<void>
+  /**
+   * Inspect the current foreground process group.
+   * @returns its id and input-wait fact, or undefined when no foreground group can be resolved.
+   */
+  inspectForeground(): Promise<SubprocessTerminalForeground | undefined>
+  /**
+   * Deliver a signal to the current foreground process group.
+   * @param signal - permitted terminal signal.
+   * @returns the exact group id that received it.
+   */
+  signalForeground(signal: SubprocessTerminalSignal): Promise<number>
+  /** Begin idempotent TERM-to-KILL cleanup of the complete terminal session. */
+  terminate(): void
+  /**
+   * Await whole-session quiescence, not only top-level process exit.
+   * @param signal - optional bound for this wait.
+   * @returns true after quiescence, false when `signal` aborts first.
+   */
+  waitForExit(signal?: AbortSignal): Promise<boolean>
+}
diff --git a/packages/subprocess/subprocess/tests/service.spec.ts b/packages/subprocess/subprocess/tests/service.spec.ts
index d0ef5c9fd6..853b333400 100644
--- a/packages/subprocess/subprocess/tests/service.spec.ts
+++ b/packages/subprocess/subprocess/tests/service.spec.ts
@@ -1,7 +1,14 @@
 import { describe, expect, it } from 'vitest'
+import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import { scrubbedParentEnv, SubprocessService } from '@deepseek-ai/dsh-subprocess'
-import type { SubprocessHandle, SubprocessOutputRead, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import type {
+  SubprocessHandle,
+  SubprocessOutputRead,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
 
 /**
  * Minimal concrete service: a hand-built handle. The seam is spawn-only —
@@ -9,6 +16,13 @@ import type { SubprocessHandle, SubprocessOutputRead, SubprocessSpawnSpec } from
  * is all an implementation owes the abstract class.
  */
 class StubSubprocessService extends SubprocessService {
+  readonly cwd = '/stub'
+  readonly runtimeRoot = '/stub/.runtime'
+
+  async resolveExecutable(command: string): Promise<string> {
+    return `/bin/${command}`
+  }
+
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
     const read: SubprocessOutputRead = { text: '', nextOffset: 0, lossy: false }
     const collected = spec.stdio.stdout !== 'pipe' && spec.stdio.stdout !== 'inherit'
@@ -25,6 +39,19 @@ class StubSubprocessService extends SubprocessService {
       waitForExit: () => Promise.resolve(true),
     }
   }
+
+  async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    return {
+      pid: spec.argv.length,
+      output: new PassThrough(),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+      write: async () => {},
+      inspectForeground: async () => ({ processGroupId: 1, inputWaiting: true }),
+      signalForeground: async () => 1,
+      terminate: () => {},
+      waitForExit: async () => true,
+    }
+  }
 }
 
 describe('SubprocessService seam', () => {
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 355b817e68..b20d5b5f3b 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -148,6 +148,7 @@ function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
     'lib/invariant.js',
     ...manifest.bin ? ['lib/bin.js'] : [],
     ...manifest.exports?.['./worker'] ? ['lib/worker.cjs'] : [],
+    ...exportDefault(manifest, './runtime-host') === './lib/runtime-host.js' ? ['lib/runtime-host.js'] : [],
     // UI plugin packages ship their browser bundle beside the node lib
     // (single-artifact ruling: dist/ retired, ./client resolves lib/client.js).
     // Keyed on the artifact path, not the subpath name: apiproxy's ./client is
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 6d9665236a..256ae90caa 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -73,6 +73,8 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   SubprocessOutputRead: 'subprocess.md',
   SubprocessOutputReader: 'subprocess.md',
   SubprocessSpawnSpec: 'subprocess.md',
+  SubprocessTerminalHandle: 'subprocess.md',
+  SubprocessTerminalSpawnSpec: 'subprocess.md',
   CodeRunRequest: 'code-runtime.md',
   CodeRunResult: 'code-runtime.md',
   CompactionResult: 'compaction.md',
@@ -242,6 +244,7 @@ export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
   'Partial',
   'Pick',
   'Promise',
+  'Record',
   'Readonly',
 ])
 
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 77432e7dbe..74a09a874e 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -623,11 +623,12 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
     'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
     'packages/api/remotes/tests/built-lib.e2e.ts',
-    // The worker-entry packages' built bundles: the only automated proof
-    // that lib/index.js resolves its sibling lib/worker.cjs under plain node
-    // (the e2e lane runs unbuilt, so these files self-skip there).
+    // Built execution consumers: the only automated proof that package-name
+    // imports reach their lib/ entrypoints under plain Node. The e2e lane runs
+    // unbuilt, so these files self-skip there.
     'packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts',
     'packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts',
+    'packages/lsp/lsp-local/tests/built-lib.e2e.ts',
   ], {
     label: 'built-bin smoke',
     needs,
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 3ca0317cf4..9a249ca844 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -47,6 +47,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/code-runtime/code-runtime-subprocess': { kind: 'indirect', reason: 'The subprocess backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 1a8ef6508a..6252733511 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -169,6 +169,7 @@
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
+    { "path": "./packages/code-runtime/code-runtime-subprocess" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
     { "path": "./packages/bash/bash-local" },

From 16cac3b5afb7e829a3f02d9445e5991a6c30a5d3 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 00:05:46 +0800
Subject: [PATCH 293/516] fix(runtime): close remote cleanup and readiness
 races

---
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |   4 +-
 ...8-portable-execution-world-consumers.zh.md |   4 +-
 packages/pty/pty-local/README.i18n.yaml       |   4 +-
 packages/pty/pty-local/README.md              |   2 +-
 packages/pty/pty-local/README.zh.md           |   2 +-
 packages/pty/pty-local/src/session.ts         |  48 ++++++--
 packages/pty/pty-local/tests/session.spec.ts  | 112 ++++++++++++++++++
 packages/typert/README.i18n.yaml              |   6 +-
 9 files changed, 166 insertions(+), 20 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 8b4288edb4..0eb1611fe1 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 000fa1b98964eb85550d0c607281937f8d7932c6
-2026-07-28-portable-execution-world-consumers.zh.md: 94e6bfcf94e450fafea2b33e152384da400e4b63
+2026-07-28-portable-execution-world-consumers.md: 5a15c2c0a4e552fadbdad9f7d09e00229afb033b
+2026-07-28-portable-execution-world-consumers.zh.md: 5ae7f3b96f4df4c3756d294ba12147a3b1b54d34
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 000fa1b989..5a15c2c0a4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,8 +22,8 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and sends provider-owned file URIs. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. A timed-out asynchronous write retains the send reservation until the provider settles it, and completion of a stale inspection resumes polling for the current send.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher reaps its controller before group termination becomes the fallback.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 94e6bfcf94..5ae7f3b96f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,8 +22,8 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并发送由提供方负责的文件 URI。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。异步写入超时后仍保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会先回收 controller，进程组终止才会成为后备手段。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index d8f5c2e2d0..828e767a60 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: 8a0a60139e27d98c4f506245a204723da997cd4a
-README.zh.md: 3df845931dac33abecbcd5030a1b204c68acc638
+README.md: 235599737d21289d291ccab8f06fbcca91c83223
+README.zh.md: ca01c9a10430644b0d6ea6c5cfa70472f0447b92
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 8a0a60139e..235599737d 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -10,7 +10,7 @@ The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then reg
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until printable prompt text arrives, including when the OSC marker and `PS1` are split across data callbacks; when bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation asks the terminal handle to signal the current foreground process group with a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation asks the terminal handle to signal the current foreground process group with a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write reports the timeout but retains the session's send slot until that write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 3df845931d..ca01c9a104 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -10,7 +10,7 @@
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。可打印的提示符文本尚未到达时，即使 OSC 标记和 `PS1` 被拆到多个数据回调中，系统也不会把标记视为就绪。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送时，系统会请求终端句柄向当前前台进程组发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送时，系统会请求终端句柄向当前前台进程组发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。在提供方异步写入期间超时的发送会报告超时，但会继续占用该会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index a6abaf7785..5ac4dbca73 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -94,6 +94,10 @@ class LocalSendOperation implements PtySendOperation {
     return this.promise.promise
   }
 
+  get settled(): boolean {
+    return this.finished
+  }
+
   append(text: string): void {
     if (!this.finished) this.output.append(text)
   }
@@ -155,6 +159,8 @@ export class LocalPtySession implements PtyBackendSession {
   private activeTimer: NodeJS.Timeout | undefined
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
+  private writing: LocalSendOperation | undefined
+  private pollingReady: LocalSendOperation | undefined
   private polling = false
   private promptSeen = false
   private promptTextSeen = false
@@ -224,7 +230,7 @@ export class LocalPtySession implements PtyBackendSession {
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
     this.activeDeadlineTimer = setTimeout(() => {
-      if (this.active === operation) this.settleActive('timeout')
+      if (this.active === operation) this.settleActive('timeout', this.writing === operation)
     }, this.config.timeoutMs)
     void this.beginSend(operation, request)
     return operation
@@ -236,12 +242,29 @@ export class LocalPtySession implements PtyBackendSession {
       if (this.active !== operation || this.closing) return
       operation.setInitialForeground(foreground)
       const input = `${request.text}${request.submit ? '\r' : ''}`
-      if (input.length > 0) await this.terminal.write(Buffer.from(input, 'utf8'))
+      if (input.length > 0) {
+        this.writing = operation
+        try {
+          await this.terminal.write(Buffer.from(input, 'utf8'))
+        } finally {
+          this.writing = undefined
+        }
+      }
+      if (this.active === operation && operation.settled) {
+        this.clearActive()
+        return
+      }
       // Closing can race the awaited provider write even though static analysis sees only local assignments.
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (this.active === operation && !this.closing) this.schedulePoll(operation, 0)
+      if (this.active === operation && !this.closing) {
+        this.pollingReady = operation
+        this.schedulePoll(operation, 0)
+      }
     } catch (error: unknown) {
-      if (this.active === operation) this.failActive(error)
+      if (this.active === operation) {
+        if (operation.settled) this.clearActive()
+        else this.failActive(error)
+      }
     }
   }
 
@@ -401,15 +424,24 @@ export class LocalPtySession implements PtyBackendSession {
       if (this.active === operation) this.failActive(error)
     } finally {
       this.polling = false
-      if (this.active === operation) this.schedulePoll(operation)
+      const active = this.active
+      // Awaited provider inspection can clear or replace the active send despite static analysis.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (active !== undefined && this.pollingReady === active) this.schedulePoll(active)
     }
   }
 
-  private settleActive(waitReason: PtyWaitReason): void {
+  private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
     const scrollbackTruncated = this.scrollback.snapshot().truncated
-    this.clearActive()
+    if (retainOwnership) {
+      this.stopPolling()
+      this.activeAbort?.()
+      this.activeAbort = undefined
+    } else {
+      this.clearActive()
+    }
     operation.settle(waitReason, this.statusValue, scrollbackTruncated)
   }
 
@@ -424,6 +456,8 @@ export class LocalPtySession implements PtyBackendSession {
     this.stopPolling()
     this.activeAbort?.()
     this.activeAbort = undefined
+    this.writing = undefined
+    this.pollingReady = undefined
     this.active = undefined
   }
 
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 7a775eb9a0..7e6b9407a0 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -268,6 +268,40 @@ describe('LocalPtySession readiness and output', () => {
     failedInternal.fail(new Error('ignored'))
   })
 
+  it('retains send ownership after timeout until an asynchronous provider write settles', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const writeGate = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await writeGate.promise }
+    const operation = session.startSend({ text: 'slow write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await vi.advanceTimersByTimeAsync(100)
+
+    expect((await operation.done).waitReason).toBe('timeout')
+    expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow('active send')
+
+    writeGate.resolve(undefined)
+    await Promise.resolve()
+    await Promise.resolve()
+    const rejectedWrite = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await rejectedWrite.promise }
+    const rejected = session.startSend({ text: 'late rejection', submit: true })
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await rejected.done).waitReason).toBe('timeout')
+    rejectedWrite.reject(new Error('write failed after timeout'))
+    await Promise.resolve()
+    await Promise.resolve()
+
+    const next = session.startSend({ text: '', submit: false })
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await next.done).waitReason).toBe('inferred_idle')
+  })
+
   it('handles startup exit, unknown exit signals, cancel-write failure, and stale polls', async () => {
     vi.useFakeTimers()
     const startupTerminal = new FakeTerminal()
@@ -509,6 +543,84 @@ describe('LocalPtySession readiness and output', () => {
     }).settle('timeout', { kind: 'running' }, false)
   })
 
+  it('reschedules readiness for a new send after a stale remote inspection releases the poll slot', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const old = session.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    let block = true
+    terminal.inspectForeground = async () => block
+      ? await inspection.promise
+      : { processGroupId: 456, inputWaiting: false }
+    const internals = session as unknown as {
+      pollReadiness(operation: PtySendOperation): Promise<void>
+      settleActive(reason: 'timeout'): void
+    }
+    const stalePoll = internals.pollReadiness(old)
+    internals.settleActive('timeout')
+    await old.done
+
+    block = false
+    const current = session.startSend({ text: '', submit: false })
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await Promise.resolve()
+    await Promise.resolve()
+    inspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await stalePoll
+    await vi.advanceTimersByTimeAsync(10)
+
+    expect((await current.done).waitReason).toBe('stdin_read')
+  })
+
+  it('does not poll a successor before its own pre-write inspection and write complete', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const old = session.startSend({ text: '', submit: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    const staleInspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    const successorInspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    let inspectCalls = 0
+    terminal.inspectForeground = async () => {
+      inspectCalls += 1
+      return inspectCalls === 1 ? await staleInspection.promise : await successorInspection.promise
+    }
+    const internals = session as unknown as {
+      pollReadiness(operation: PtySendOperation): Promise<void>
+      settleActive(reason: 'timeout'): void
+    }
+    const stalePoll = internals.pollReadiness(old)
+    internals.settleActive('timeout')
+    await old.done
+
+    const current = session.startSend({ text: 'successor', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    staleInspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await stalePoll
+    await vi.advanceTimersByTimeAsync(10)
+    expect(inspectCalls).toBe(2)
+    expect(terminal.writes).toEqual([])
+
+    successorInspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await Promise.resolve()
+    await Promise.resolve()
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(terminal.writes).toEqual(['successor\r'])
+    expect((await current.done).waitReason).toBe('stdin_read')
+  })
+
   it('contains stale timer, write, inspection, and interrupt continuations', async () => {
     vi.useFakeTimers()
     const settle = (operation: PtySendOperation): void => {
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index cf44d9aace..d075078b94 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/README.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 packages/typert/README.md
-README.md: ad9f843e48be0e3be85921ed8fd3ca4e2c327160
-README.zh.md: 0d4be016b766178b54f7e269583fa4200e3eb24b
+#   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-subprocess/README.md
+README.md: 9e0ea9065ea4e42696f6afcd243c385e514f7c2d
+README.zh.md: 6946248ec58054fcdd93a4c94affb55f90041301

From ac81165662eeee7fb9b4f77be358e78c8b0c6263 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 01:18:01 +0800
Subject: [PATCH 294/516] fix(runtime): close async cleanup and framing races

---
 .../feature/2026-06-15-code-mode.i18n.yaml    |  4 +-
 .../feature/2026-06-15-code-mode.md           |  4 +-
 .../feature/2026-06-15-code-mode.zh.md        |  4 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |  4 +-
 .../2026-07-16-persistent-pty-sessions.md     |  6 +--
 .../2026-07-16-persistent-pty-sessions.zh.md  |  6 +--
 packages/pty/pty-local/README.i18n.yaml       |  4 +-
 packages/pty/pty-local/README.md              |  4 +-
 packages/pty/pty-local/README.zh.md           |  4 +-
 packages/pty/pty-local/src/index.ts           |  3 +-
 packages/pty/pty-local/src/sanitize.ts        | 37 +++++++++-------
 packages/pty/pty-local/src/session.ts         | 22 +++++++---
 packages/pty/pty-local/tests/sanitize.spec.ts |  6 +--
 packages/pty/pty-local/tests/session.spec.ts  | 44 +++++++++++++++++++
 packages/typert/README.i18n.yaml              |  4 +-
 15 files changed, 109 insertions(+), 47 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index a878942993..42a11b8fb8 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 7e51b9fa726afe4c34b87457b562b4092ee6c93c
-2026-06-15-code-mode.zh.md: 4ba098d87d8c944e88c4cbe11ff78ac4383d3ac5
+2026-06-15-code-mode.md: b0778b2c9a8dfce8f786faccf6cc47f477c6b7c0
+2026-06-15-code-mode.zh.md: 437692eac3fc6740e0f1d4dd9001130fd6dd448a
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index 7e51b9fa72..b0778b2c9a 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -79,7 +79,7 @@ Requests contain every runtime input; implementations own validated timeout and
 5. **Enforce independent budgets.** `computeMs` meters worker busy time, allowing slow awaited tools without excusing a hot loop. `maxWallMs` bounds total elapsed time, including unresolved waits. `maxOutputBytes` bounds only the combined serialized outer logs, completion, or diagnostic; intermediate binding values have no byte cap. Expiry, cancellation, and completion terminate the worker, and heap exits or outer overflow are explicit failures.
 6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../../docs/defensive-patterns.md).
 
-`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded base64 JSON frames on raw pipes. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
+`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded base64 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
 
 ### Trust posture
 
@@ -95,7 +95,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Testing
 
-- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger boundaries, compute and wall budgets, hostile binding traffic, empty environment, and disposal to quiescence. Built-package tests run both the direct worker entry and the filesystem/subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
+- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger and per-hop frame boundaries, compute and wall budgets, hostile binding traffic, empty environment, descendant lifetime cleanup, and disposal to quiescence. Built-package tests run both the direct worker entry and the filesystem/subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
 - **Registry integration:** Tests cover code generation, all presentation modes, reserved-name and restriction rules, scoped visibility, authoritative assembly rewrites, `toolOrder`, runtime compatibility failures, full-pipeline sub-dispatch, parent-token correlation, serialization, cancellation and queue drain, JSON normalization, error propagation, log events, ordered context deferral across successful and failed programs, outer-block suppression, and HMR cleanup.
 - **With-key e2e:** A real model composes two bash calls in one program; another discovers nested workspace instructions through a Code Mode fs dispatch. The tests verify collapsed request headers, correlated dispatch events, resulting files, deferred context, and model behavior.
 - **Snapshot:** The `code-mode-turn`, `both-mode-turn`, and `code-mode-workspace-context` fixtures pin SDK text, header tool lists, dispatch events, deferred context, and result cards.
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index 4ba098d87d..437692eac3 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -79,7 +79,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
 6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
 
-`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界 base64 JSON 帧承载绑定通信。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
+`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界 base64 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
 
 ### 信任姿态
 
@@ -95,7 +95,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 ## 测试
 
-- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界、compute 和 wall 预算、恶意绑定流量、空环境以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与文件系统／子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
+- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界与逐跳帧边界、compute 和 wall 预算、恶意绑定流量、空环境、后代进程生命周期清理以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与文件系统／子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
 - **注册表集成：** 测试覆盖代码生成、所有呈现模式、保留名称和限制规则、scoped 可见性、权威组装重写、`toolOrder`、运行时兼容性失败、完整流水线子分发、parent-token 关联、序列化、取消和队列排空、JSON 规范化、错误传播、日志事件、成功与失败程序中的有序上下文延后、外层阻止抑制以及 HMR（热模块替换）清理。
 - **带密钥 e2e：** 真实模型在一个程序中组合两次 bash 调用；另一个模型通过 Code Mode fs 分发发现嵌套的工作区指令。测试验证折叠的请求头、关联的分发事件、结果文件、延后上下文和模型行为。
 - **快照：** `code-mode-turn`、`both-mode-turn` 和 `code-mode-workspace-context` fixture（测试前置数据）固定 SDK 文本、请求头工具列表、分发事件、延后上下文和结果卡片。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 6a801df865..8b33466ea7 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: 65d265b83ab5ad89c2b919364043eb28e75977c7
-2026-07-16-persistent-pty-sessions.zh.md: 6ea92da9a1b2870f3773d84e7f5629bec220dd1c
+2026-07-16-persistent-pty-sessions.md: ef87c2806a237e6e6d44c1e62942146af24b8c19
+2026-07-16-persistent-pty-sessions.zh.md: 5f1bde39de5eca7aa57897d87c95675ce0da5abd
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index 65d265b83a..ef87c2806a 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -60,7 +60,7 @@ The local subprocess terminal primitive uses only public `node-pty` capabilities
 
 The UI render contract is exact and location-free. `terminal_send` uses terminal call/result cards only for foreground sends; its background form is generic `execute`. `terminal_open`, `terminal_read`, `terminal_signal`, `terminal_close`, and `terminal_list` use generic `execute`, `read`, `execute`, `delete`, and `read` cards respectively. No PTY tool emits `locations`.
 
-`terminal_send({ sessionId, text, submit?, run_in_background? })` treats `text` as UTF-8 bytes and resolves `submit` to `true` in the tool implementation. When `submit` is true it writes the platform Enter sequence after the text; when false it writes only the text, allowing control characters and REPL fragments without hidden content heuristics. `enableRunInBackground` defaults to true; false removes `run_in_background` from the schema and rejects the same undeclared argument if a caller forces it through execution.
+`terminal_send({ sessionId, text, submit?, run_in_background? })` treats `text` as UTF-8 bytes and resolves `submit` to `true` in the tool implementation. When `submit` is true it writes the platform Enter sequence after the text; when false it writes only the text, allowing control characters and REPL fragments without hidden content heuristics. Cancellation marks queued input before signaling the real foreground group, so input cannot execute if an asynchronous pre-write inspection settles afterward. `enableRunInBackground` defaults to true; false removes `run_in_background` from the schema and rejects the same undeclared argument if a caller forces it through execution.
 
 Foreground sends return a bounded rendered delta and two independent facts: `waitReason` (`stdin_read | inferred_idle | timeout | session_exit`) and `sessionStatus` (`running` or `exited` with exit code or signal). `session_exit` refers to the PTY's top-level shell process, not an arbitrary foreground command whose status the shell consumes. A timeout never implies process exit. `dsh-tool-pty.maxResultBytes` defaults to 262144, rejects values below 64 so creation acknowledgements retain registry-issued ids, and caps each single-text UTF-8 result after normalized tool or pipeline errors, wait, session, pagination, truncation, generic task-status wrappers, policy denials or short-circuits, and post-execute replacements or blocks; the terminal definitions' last-mile `finalizeContent` callback leaves deliberately structured multi-block policy content unchanged. The renderer reserves suffix space and preserves code-point boundaries instead of treating the backend payload cap as the final model bound.
 
@@ -72,7 +72,7 @@ With `run_in_background: true`, `dsh-tool-pty` registers the in-flight send on `
 
 ### Local readiness detection
 
-The local backend first recognizes a private OSC prompt marker emitted by its controlled bash startup, then requires printable prompt text after that marker before declaring prompt readiness and runs three bounded fallback tiers. Carrying that state across data callbacks covers macOS delivery where the OSC marker and `PS1` arrive separately; the marker alone can no longer publish an empty MOTD. The marker is removed before output reaches the model and avoids a fixed silence delay for ordinary shell commands on both platforms. Unpublished startup does not accept zero-output silence as readiness; timeout rejects the spawn. If caller cancellation wins during startup, the backend closes the private session and propagates the exact `AbortSignal.reason`; a foreground PGID that is not observable yet cannot replace cancellation with a lookup error. All timings are validated config fields: `pollIntervalMs`, `exactProbeAfterMs`, `idleSilenceMs`, `handoffGraceMs`, and `timeoutMs`.
+The local backend first recognizes a private OSC prompt marker emitted by its controlled bash startup, then requires the printable tail after the latest marker to exactly equal the controlled `PS1` before declaring prompt readiness and runs three bounded fallback tiers. Carrying that tail across data callbacks covers delivery where the marker and prompt arrive separately; requiring the exact tail rejects a delayed earlier prompt once echoed input or output follows it, so it cannot settle the current send. The marker is removed before output reaches the model and avoids a fixed silence delay for ordinary shell commands on both platforms. Unpublished startup does not accept zero-output silence as readiness; timeout rejects the spawn. If caller cancellation wins during startup, the backend closes the private session and propagates the exact `AbortSignal.reason`; a foreground PGID that is not observable yet cannot replace cancellation with a lookup error. All timings are validated config fields: `pollIntervalMs`, `exactProbeAfterMs`, `idleSilenceMs`, `handoffGraceMs`, and `timeoutMs`.
 
 On Linux, the inspector reads the shell's terminal foreground PGID from `/proc/<shellPid>/stat`, enumerates every process and thread in that process group, and probes their current syscalls. A positive Tier 1 result requires an observed stdin wait: direct `read(0)`, a permitted read of a `select`/`pselect6` or `poll`/`ppoll` argument containing fd 0, or an epoll interest list containing fd 0. A wait already present before terminal input is not post-write readiness: the same PGID must be observed outside that wait before re-entering it, while a changed foreground PGID is new evidence. Unreadable process memory and unrecognized syscalls are misses, never positive guesses. Architecture tables contain only syscall numbers defined by the corresponding Linux UAPI; unsupported architectures skip Tier 1.
 
@@ -156,7 +156,7 @@ The package ships concise tool guidance explaining persistent state, owner isola
 
 ## Verification
 
-- Per-file coverage pins owner fencing, concurrent reservations, unpublished-spawn cancellation and awaited teardown, sandbox-mode change rejection, retriable lifecycle cleanup, readiness tiers, rejection of pre-write stdin waits, the configured handoff grace holding the idle fallback past one poll and its rejection below `pollIntervalMs`, sanitizer carry state, complete UTF-8 bounds, task integration, schemas, and exact render intents.
+- Per-file coverage pins owner fencing, concurrent reservations, cancellation during pre-write inspection, unpublished-spawn cancellation and awaited teardown, sandbox-mode change rejection, retriable lifecycle cleanup, readiness tiers, rejection of pre-write stdin waits and delayed earlier prompts, the configured handoff grace holding the idle fallback past one poll and its rejection below `pollIntervalMs`, sanitizer carry state, complete UTF-8 bounds, task integration, schemas, and exact render intents.
 - Subprocess process fixtures cover non-leader and non-main-thread stdin waits, zombie quiescence, unreadable process state, supported syscall tables, unsupported architectures, and false-positive rejection; macOS inspector logic is injected into the same unit suite.
 - Real `node-pty` and PTY-consumer tests jointly exercise shell state, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
 - A Loader-driven `cordis.yml` test mounts the real three-package composition. ACP and headless snapshots pin the six schemas, bounded results, and errors through opt-in overlays; TUI snapshots pin terminal and generic card presentation.
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 6ea92da9a1..5f1bde39de 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -60,7 +60,7 @@ agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出
 
 UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
 
-`terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。`enableRunInBackground` 默认为 true；设为 false 时，schema 中会移除 `run_in_background`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
+`terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。取消会在向真实前台进程组发送信号前将排队输入标记为已取消，因此即使异步的写入前检查随后才结算，该输入也无法执行。`enableRunInBackground` 默认为 true；设为 false 时，schema 中会移除 `run_in_background`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
 
 前台发送返回有界的渲染增量和两个独立事实：`waitReason`（`stdin_read | inferred_idle | timeout | session_exit`）与 `sessionStatus`（`running`，或携带退出码或信号的 `exited`）。`session_exit` 指 PTY 顶层 shell 进程退出，不指由 shell 消费状态的任意前台命令。timeout 从不意味着进程已经退出。`dsh-tool-pty.maxResultBytes` 默认为 262144；低于 64 的值会被拒绝，以确保创建确认保留 registry 签发的 id；每个单文本 UTF-8 结果在加入规范化的工具或流水线错误、等待、会话、分页、截断、通用 task 状态包装、策略拒绝或短路以及 post-execute 替换或阻断后，仍受该值限制；终端定义自有的末端 `finalizeContent` callback 会原样保留策略刻意返回的结构化多 block 内容。渲染器会为后缀预留空间并保持代码点边界，而不会把后端载荷上限当作面向模型结果的最终上限。
 
@@ -72,7 +72,7 @@ UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发
 
 ### 本地就绪检测
 
-本地后端先识别受控 bash 启动时发出的私有 OSC prompt marker，并且只有在该 marker 后出现可打印的 prompt 文本时才据此声明 prompt 就绪；除此之外，它还运行 3 个有界 fallback 层级。在 data callback 之间保留这项状态，可以适配 macOS 分开交付 OSC marker 与 `PS1` 的情况；单独的 marker 不会发布空 MOTD。marker 在输出到达模型前被移除，使两个平台上的普通 shell 命令都无需固定等待静默阈值。尚未发布的 startup 不会把零输出静默视为就绪；timeout 会拒绝 spawn。若调用方取消在 startup 期间胜出，后端会关闭私有会话并原样抛出 `AbortSignal.reason`；尚不可观察的前台 PGID 不会再用查找错误覆盖取消原因。所有时间参数都是经校验的配置字段：`pollIntervalMs`、`exactProbeAfterMs`、`idleSilenceMs`、`handoffGraceMs` 和 `timeoutMs`。
+本地后端先识别受控 bash 启动时发出的私有 OSC prompt marker，并且只有在最近一个 marker 后的可打印尾部与受控 `PS1` 完全相等时才声明 prompt 就绪；除此之外，它还运行 3 个有界 fallback 层级。在 data callback 之间保留该尾部，可以适配 marker 与 prompt 被分开交付的情况；如果回显的输入或输出跟在延迟到达的先前 prompt 之后，要求尾部完全相等会拒绝该 prompt，使其无法完成当前 send。marker 在输出到达模型前被移除，使两个平台上的普通 shell 命令都无需固定等待静默阈值。尚未发布的 startup 不会把零输出静默视为就绪；timeout 会拒绝 spawn。若调用方取消在 startup 期间胜出，后端会关闭私有会话并原样抛出 `AbortSignal.reason`；尚不可观察的前台 PGID 不会再用查找错误覆盖取消原因。所有时间参数都是经校验的配置字段：`pollIntervalMs`、`exactProbeAfterMs`、`idleSilenceMs`、`handoffGraceMs` 和 `timeoutMs`。
 
 在 Linux 上，检查器从 `/proc/<shellPid>/stat` 读取 shell 的终端前台 PGID，枚举该进程组中的每个进程与线程，并检查它们当前的 syscall。Tier 1 只有观察到 stdin 等待才返回正结果：直接 `read(0)`、获准读取且含 fd 0 的 `select`/`pselect6` 或 `poll`/`ppoll` 参数，或者含 fd 0 的 epoll interest list。终端输入前就已存在的等待并不代表写入后就绪：必须先观察到同一 PGID 脱离该等待，之后再次进入等待才能使该次 send 完成；前台 PGID 发生变化则构成新的证据。无法读取的进程内存和未识别的 syscall 都是 miss，绝不作为正向猜测。架构表只包含对应 Linux UAPI 定义的 syscall number；不支持的架构跳过 Tier 1。
 
@@ -156,7 +156,7 @@ plugins:
 
 ## 验证
 
-- 每文件覆盖率固定 owner 隔离、并发预留、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、对写入前 stdin 等待的拒绝、配置化交接宽限把 idle fallback 顶过一次轮询以及低于 `pollIntervalMs` 时的拒绝、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。
+- 每文件覆盖率固定 owner 隔离、并发预留、写入前检查期间的取消、未发布 spawn 的取消与等待式 teardown、沙箱模式变更拒绝、可重试的生命周期清理、就绪层级、对写入前 stdin 等待与延迟到达的先前 prompt 的拒绝、配置化交接宽限把 idle fallback 顶过一次轮询以及低于 `pollIntervalMs` 时的拒绝、sanitizer carry state、完整 UTF-8 结果上限、task 集成、schema 和精确 render intent。
 - 子进程 fixture 覆盖非 leader 与非主线程的 stdin 等待、僵尸进程完全停稳、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
 - 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合。ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 828e767a60..e29a581f57 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: 235599737d21289d291ccab8f06fbcca91c83223
-README.zh.md: ca01c9a10430644b0d6ea6c5cfa70472f0447b92
+README.md: 2c4ee44e8489cc6b53179769301e125dcca0ac8e
+README.zh.md: 947bab00b9d6aa5fb7b321fbee84f4b2e420133c
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 235599737d..2c4ee44e84 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,9 +8,9 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until printable prompt text arrives, including when the OSC marker and `PS1` are split across data callbacks; when bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation asks the terminal handle to signal the current foreground process group with a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write reports the timeout but retains the session's send slot until that write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write reports the timeout but retains the session's send slot until that write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index ca01c9a104..947bab00b9 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,9 +8,9 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。可打印的提示符文本尚未到达时，即使 OSC 标记和 `PS1` 被拆到多个数据回调中，系统也不会把标记视为就绪。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送时，系统会请求终端句柄向当前前台进程组发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。在提供方异步写入期间超时的发送会报告超时，但会继续占用该会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。在提供方异步写入期间超时的发送会报告超时，但会继续占用该会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index 0a54a0b804..a8d99cb243 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -14,6 +14,7 @@ import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
 import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
 import { LocalPtySession } from './session.ts'
+import { CONTROLLED_PROMPT } from './sanitize.ts'
 
 export { Config } from './config.ts'
 export type { Config as PtyLocalConfig } from './config.ts'
@@ -58,7 +59,7 @@ function childEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
     TERM: 'dumb',
     PAGER: 'cat',
     GIT_PAGER: 'cat',
-    PS1: 'dsh> ',
+    PS1: CONTROLLED_PROMPT,
     PROMPT_COMMAND: 'printf "\\033]133;D;%s\\007" "$?"',
     BASH_SILENCE_DEPRECATION_WARNING: '1',
     DSH_SHELL: '1',
diff --git a/packages/pty/pty-local/src/sanitize.ts b/packages/pty/pty-local/src/sanitize.ts
index cc22c29c01..1f28315fb1 100644
--- a/packages/pty/pty-local/src/sanitize.ts
+++ b/packages/pty/pty-local/src/sanitize.ts
@@ -5,12 +5,15 @@ import { Buffer } from 'node:buffer'
 /** OSC marker emitted by the controlled bash before each prompt. */
 export const PROMPT_MARKER_PREFIX = '133;D;'
 
+/** Exact printable prompt emitted after the private marker. */
+export const CONTROLLED_PROMPT = 'dsh> '
+
 /** One sanitized chunk plus whether it contained the owned prompt marker. */
 export interface SanitizedChunk {
   text: string
   prompt: boolean
-  /** Present when printable text followed the latest owned prompt marker. */
-  promptText?: true
+  /** Printable text after the latest owned marker in this chunk. */
+  promptTail?: string
 }
 
 /**
@@ -23,7 +26,7 @@ export class TerminalSanitizer {
   private discardMode: 'osc' | 'csi' | undefined
   private discardOscEscape = false
   private trailingCarriageReturn = false
-  private awaitingPromptText = false
+  private trackingPromptTail = false
 
   constructor(private readonly maxPendingBytes: number) {}
 
@@ -36,24 +39,21 @@ export class TerminalSanitizer {
     this.pending += this.discardPrefix(chunk)
     let text = ''
     let prompt = false
-    let promptText = false
+    let includePromptTail = this.trackingPromptTail
+    let promptTail = ''
     let index = 0
-    const appendText = (value: string): boolean => {
+    const appendText = (value: string): void => {
       text += value
-      if (this.awaitingPromptText && value.replace(/[\r\n\x07]/g, '').length > 0) {
-        this.awaitingPromptText = false
-        return true
-      }
-      return false
+      if (this.trackingPromptTail) promptTail += value
     }
     while (index < this.pending.length) {
       const escape = this.pending.indexOf('\x1b', index)
       if (escape < 0) {
-        promptText = appendText(this.pending.slice(index)) || promptText
+        appendText(this.pending.slice(index))
         index = this.pending.length
         break
       }
-      promptText = appendText(this.pending.slice(index, escape)) || promptText
+      appendText(this.pending.slice(index, escape))
       if (escape + 1 >= this.pending.length) {
         index = escape
         break
@@ -74,8 +74,9 @@ export class TerminalSanitizer {
         const content = this.pending.slice(escape + 2, end - terminatorBytes)
         if (content.startsWith(PROMPT_MARKER_PREFIX)) {
           prompt = true
-          promptText = false
-          this.awaitingPromptText = true
+          this.trackingPromptTail = true
+          includePromptTail = true
+          promptTail = ''
         }
         index = end
         continue
@@ -99,7 +100,11 @@ export class TerminalSanitizer {
     }
     this.pending = this.pending.slice(index)
     this.enforcePendingBound()
-    return { text: this.normalizeText(text), prompt, ...promptText ? { promptText: true } : {} }
+    return {
+      text: this.normalizeText(text),
+      prompt,
+      ...includePromptTail ? { promptTail } : {},
+    }
   }
 
   /**
@@ -111,7 +116,7 @@ export class TerminalSanitizer {
     this.pending = ''
     this.discardMode = undefined
     this.discardOscEscape = false
-    this.awaitingPromptText = false
+    this.trackingPromptTail = false
     const normalized = this.normalizeText(text)
     if (!this.trailingCarriageReturn) return normalized
     this.trailingCarriageReturn = false
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 5ac4dbca73..f984648f27 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -20,7 +20,7 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import { TerminalSanitizer } from './sanitize.ts'
+import { CONTROLLED_PROMPT, TerminalSanitizer } from './sanitize.ts'
 
 function utf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
   if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
@@ -77,6 +77,7 @@ class LocalSendOperation implements PtySendOperation {
   private readonly output: BoundedTextBuffer
   private readonly promise: PromiseWithResolvers<PtySendResult>
   private finished = false
+  private cancellationRequested = false
   private initialForegroundLeftWait: boolean
   private initialForegroundPgid: number | undefined
 
@@ -98,6 +99,10 @@ class LocalSendOperation implements PtySendOperation {
     return this.finished
   }
 
+  get cancelRequested(): boolean {
+    return this.cancellationRequested
+  }
+
   append(text: string): void {
     if (!this.finished) this.output.append(text)
   }
@@ -140,6 +145,7 @@ class LocalSendOperation implements PtySendOperation {
 
   cancel(): boolean {
     if (this.finished) return false
+    this.cancellationRequested = true
     this.onCancel()
     return true
   }
@@ -164,6 +170,7 @@ export class LocalPtySession implements PtyBackendSession {
   private polling = false
   private promptSeen = false
   private promptTextSeen = false
+  private promptTail = ''
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
@@ -223,6 +230,7 @@ export class LocalPtySession implements PtyBackendSession {
     this.lastOutputAt = Date.now()
     this.promptSeen = false
     this.promptTextSeen = false
+    this.promptTail = ''
 
     if (request.signal !== undefined) {
       const onAbort = (): void => { operation.cancel() }
@@ -242,7 +250,7 @@ export class LocalPtySession implements PtyBackendSession {
       if (this.active !== operation || this.closing) return
       operation.setInitialForeground(foreground)
       const input = `${request.text}${request.submit ? '\r' : ''}`
-      if (input.length > 0) {
+      if (input.length > 0 && !operation.cancelRequested) {
         this.writing = operation
         try {
           await this.terminal.write(Buffer.from(input, 'utf8'))
@@ -347,10 +355,14 @@ export class LocalPtySession implements PtyBackendSession {
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
       this.promptSeen = true
-      this.promptTextSeen = sanitized.promptText === true
+      this.promptTail = ''
       this.lastOutputAt = Date.now()
-    } else if (this.promptSeen && sanitized.promptText === true) {
-      this.promptTextSeen = true
+    }
+    if (this.promptSeen && sanitized.promptTail !== undefined) {
+      const remaining = Math.max(0, CONTROLLED_PROMPT.length + 1 - this.promptTail.length)
+      this.promptTail += sanitized.promptTail.slice(0, remaining)
+      if (sanitized.promptTail.length > remaining) this.promptTail = `${CONTROLLED_PROMPT}\0`
+      this.promptTextSeen = this.promptTail === CONTROLLED_PROMPT
     }
   }
 
diff --git a/packages/pty/pty-local/tests/sanitize.spec.ts b/packages/pty/pty-local/tests/sanitize.spec.ts
index 4da4ab0d73..f6649b3c6f 100644
--- a/packages/pty/pty-local/tests/sanitize.spec.ts
+++ b/packages/pty/pty-local/tests/sanitize.spec.ts
@@ -7,7 +7,7 @@ describe('TerminalSanitizer', () => {
     expect(sanitizer.push('red\x1b[3')).toEqual({ text: 'red', prompt: false })
     expect(sanitizer.push('1m text\x1b[0m\r\n')).toEqual({ text: ' text\n', prompt: false })
     expect(sanitizer.push('\x1b]133;')).toEqual({ text: '', prompt: false })
-    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptText: true })
+    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptTail: 'dsh> ' })
   })
 
   it('drops unrelated OSC, short escapes, BEL, and incomplete trailing escape', () => {
@@ -35,8 +35,8 @@ describe('TerminalSanitizer', () => {
 
   it('reports printable prompt text that follows a marker in a later chunk', () => {
     const sanitizer = new TerminalSanitizer(64)
-    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true })
-    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptText: true })
+    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true, promptTail: '' })
+    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptTail: 'dsh> ' })
   })
 
   it('bounds and discards unterminated control sequences through their terminators', () => {
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 7e6b9407a0..6346a6bba2 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -268,6 +268,29 @@ describe('LocalPtySession readiness and output', () => {
     failedInternal.fail(new Error('ignored'))
   })
 
+  it('does not write a send canceled during asynchronous foreground inspection', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await inspection.promise
+    const controller = new AbortController()
+    const operation = session.startSend({ text: 'must not execute', submit: true, signal: controller.signal })
+    controller.abort()
+    inspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(terminal.writes).toEqual([])
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    terminal.emitData('\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+  })
+
   it('retains send ownership after timeout until an asynchronous provider write settles', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -418,6 +441,27 @@ describe('LocalPtySession readiness and output', () => {
     expect(session.motd).toBe('dsh> ')
   })
 
+  it('does not attribute a delayed prior prompt to the current send', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config({ idleSilenceMs: 100, timeoutMs: 200 }))
+    await initialize(session, terminal)
+
+    const operation = session.startSend({ text: "printf 'PID=%s\\n' \"$!\"", submit: true })
+    let settled = false
+    void operation.done.then(() => { settled = true })
+    await Promise.resolve()
+    await Promise.resolve()
+
+    terminal.emitData('\x1b]133;D;0\x07dsh> printf \'PID=%s\\n\' "$!"\r\n')
+    await vi.advanceTimersByTimeAsync(20)
+    expect(settled).toBe(false)
+
+    terminal.emitData('PID=123\r\n\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(await operation.done).toMatchObject({ waitReason: 'stdin_read' })
+  })
+
   it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index d075078b94..d1678caf7e 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: 9e0ea9065ea4e42696f6afcd243c385e514f7c2d
-README.zh.md: 6946248ec58054fcdd93a4c94affb55f90041301
+README.md: 620728744fb2a63a730ee06ef3eb5c36505ae572
+README.zh.md: d3201d2e49e9dc89a9d274ca1075f450ad13c683

From e5f3a6736357c33d3d889ebda316646a409b3eb8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 01:15:35 +0800
Subject: [PATCH 295/516] fix(runtime): publish completion before pipe cleanup

---
 .../2026-07-28-portable-execution-world-consumers.i18n.yaml   | 4 ++--
 .../2026-07-28-portable-execution-world-consumers.md          | 2 +-
 .../2026-07-28-portable-execution-world-consumers.zh.md       | 2 +-
 packages/typert/README.i18n.yaml                              | 4 ++--
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 0eb1611fe1..f72f7c1d89 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 5a15c2c0a4e552fadbdad9f7d09e00229afb033b
-2026-07-28-portable-execution-world-consumers.zh.md: 5ae7f3b96f4df4c3756d294ba12147a3b1b54d34
+2026-07-28-portable-execution-world-consumers.md: 145b23317552a51f608404a3308011fb8540319f
+2026-07-28-portable-execution-world-consumers.zh.md: 50e27ccce19516a02e4e5024efb8303231a2236e
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 5a15c2c0a4..145b233175 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -23,7 +23,7 @@ Generic consumers use that execution world:
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and sends provider-owned file URIs. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. A timed-out asynchronous write retains the send reservation until the provider settles it, and completion of a stale inspection resumes polling for the current send.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher reaps its controller before group termination becomes the fallback.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 5ae7f3b96f..50e27ccce1 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -23,7 +23,7 @@ Status: implemented
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并发送由提供方负责的文件 URI。其 JSON-RPC、池化、同步、取消和规范化保持不变。
 - `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。异步写入超时后仍保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会先回收 controller，进程组终止才会成为后备手段。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index d1678caf7e..384c9cdb94 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: 620728744fb2a63a730ee06ef3eb5c36505ae572
-README.zh.md: d3201d2e49e9dc89a9d274ca1075f450ad13c683
+README.md: db4478fe799dce1bbdb7e3ae3d31947515aae151
+README.zh.md: 238f5f66db58edb99945cfa43299635b4f8f36a8

From c17727d43dcb118158bc28bfec6cebe60097fae3 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 01:15:50 +0800
Subject: [PATCH 296/516] test(subprocess): cover terminal release cleanup

---
 .../subprocess-local/tests/local.spec.ts      | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index bc77d24cfd..7ff10a7348 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -105,6 +105,53 @@ describe('LocalSubprocessService', () => {
     expect(waitForExit).toHaveBeenCalledOnce()
   })
 
+  it('releases a terminal after top-level exit reaches quiescence', async () => {
+    let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
+    const inspector = {
+      foregroundPgid: () => undefined,
+      isStdinWaiting: () => false,
+      processTree: () => [],
+      isAlive: () => false,
+      signalGroup: () => {},
+      signalProcess: () => {},
+    }
+    const terminal = {
+      pid: 123,
+      onData: () => ({ dispose: () => {} }),
+      onExit: (listener: (event: { exitCode: number; signal?: number }) => void) => {
+        exitListener = listener
+        return { dispose: () => {} }
+      },
+      write: () => {},
+      kill: () => {},
+    }
+    vi.resetModules()
+    vi.doMock('node-pty', () => ({ spawn: () => terminal }))
+    vi.doMock('../src/process-inspector.ts', async importOriginal => ({
+      ...await importOriginal<typeof import('../src/process-inspector.ts')>(),
+      createProcessInspector: () => inspector,
+    }))
+    try {
+      const { default: IsolatedLocalSubprocessService } = await import('../src/index.ts')
+      const ctx = new Context()
+      const fiber = await ctx.plugin(IsolatedLocalSubprocessService)
+      const service = ctx.subprocess as InstanceType<typeof IsolatedLocalSubprocessService>
+      const handle = await ctx.subprocess.spawnTerminal({
+        argv: ['shell'], cwd: process.cwd(), rows: 24, cols: 80, graceMs: 1,
+      })
+      expect((service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals.size).toBe(1)
+      exitListener?.({ exitCode: 0 })
+      await handle.done
+      await new Promise(resolve => setImmediate(resolve))
+      expect((service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals.size).toBe(0)
+      await fiber.dispose()
+    } finally {
+      vi.doUnmock('node-pty')
+      vi.doUnmock('../src/process-inspector.ts')
+      vi.resetModules()
+    }
+  })
+
   it('contains a terminal release failure after top-level exit', async () => {
     let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
     const terminal = {

From 32bce339da84917b696f1387d8e7e8417c73c27d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 02:40:02 +0800
Subject: [PATCH 297/516] fix(runtime): close lifecycle teardown races

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  6 +--
 ...8-portable-execution-world-consumers.zh.md |  6 +--
 packages/pty/pty-local/README.i18n.yaml       |  4 +-
 packages/pty/pty-local/README.md              |  4 +-
 packages/pty/pty-local/README.zh.md           |  4 +-
 packages/pty/pty-local/src/index.ts           | 33 ++++++++++----
 packages/pty/pty-local/src/session.ts         | 12 +++--
 packages/pty/pty-local/tests/index.spec.ts    | 45 +++++++++++++++++++
 packages/pty/pty-local/tests/local.spec.ts    | 43 +++++++++++++++++-
 packages/pty/pty-local/tests/session.spec.ts  | 27 +++++++++++
 .../subprocess-local/README.i18n.yaml         |  4 +-
 .../subprocess/subprocess-local/README.md     |  4 +-
 .../subprocess/subprocess-local/README.zh.md  |  4 +-
 .../subprocess-local/src/process-inspector.ts | 14 ++++++
 .../subprocess-local/src/terminal.ts          |  9 +++-
 .../subprocess-local/tests/local.spec.ts      |  2 +
 .../tests/process-inspector.spec.ts           |  8 ++++
 .../subprocess-local/tests/terminal.spec.ts   | 32 +++++++++++++
 packages/typert/README.i18n.yaml              |  4 +-
 20 files changed, 233 insertions(+), 36 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index f72f7c1d89..f97b09b940 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 145b23317552a51f608404a3308011fb8540319f
-2026-07-28-portable-execution-world-consumers.zh.md: 50e27ccce19516a02e4e5024efb8303231a2236e
+2026-07-28-portable-execution-world-consumers.md: 3d1928be882fb3fb621e733649146445c69e8a5b
+2026-07-28-portable-execution-world-consumers.zh.md: f385e502d5d737fe0d5ae6e28ac7a3a097d85a6b
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 145b233175..3d1928be88 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,8 +22,8 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and sends provider-owned file URIs. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. A timed-out asynchronous write retains the send reservation until the provider settles it, and completion of a stale inspection resumes polling for the current send.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. A timed-out asynchronous write, or a cancellation whose foreground signal fails during that write, retains the send reservation until the provider settles it; completion of a stale inspection resumes polling for the current send.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
@@ -45,4 +45,4 @@ A remote execution provider implements only its shared sandbox owner plus filesy
 
 The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers.
 
-The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal still waits for exact PID-identity-fenced descendants and the top-level terminal process to reach quiescence.
+The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal waits for exact PID-identity-fenced descendants retained during foreground inspection, Linux session members that survive top-level exit, and the top-level terminal process to reach quiescence. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 50e27ccce1..f385e502d5 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,8 +22,8 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并发送由提供方负责的文件 URI。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。异步写入超时后仍保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。异步写入超时，或在该写入期间取消时前台信号发送失败，都会保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
@@ -45,4 +45,4 @@ Status: implemented
 
 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
 
-本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）仍会等待受精确 PID 身份校验保护的后代进程和顶层终端进程完全停稳。
+本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程、在顶层进程退出后仍存活的 Linux 会话成员，以及顶层终端进程完全停稳。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index e29a581f57..05e9b904f9 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: 2c4ee44e8489cc6b53179769301e125dcca0ac8e
-README.zh.md: 947bab00b9d6aa5fb7b321fbee84f4b2e420133c
+README.md: 7d0cd2c26c6c58a64ae9d5fe5598c8aa6ff62915
+README.zh.md: 0b8216a9f599c224bd2888eb428213c9d725a338
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 2c4ee44e84..7d0cd2c26c 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,9 +8,9 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write reports the timeout but retains the session's send slot until that write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the session's send slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 947bab00b9..0b8216a9f5 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,9 +8,9 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。在提供方异步写入期间超时的发送会报告超时，但会继续占用该会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index a8d99cb243..62b5fdb71a 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -101,15 +101,30 @@ export class LocalPtyBackend implements PtyBackend {
     ensureSandboxModeFence(this.ctx, spec.owner)
     const argv = spawnArgv(this.ctx, this.config, spec)
     if (argv[0] === undefined) throw new Error('pty-local: sandbox returned empty argv')
-    const terminal = await this.spawnTerminal({
-      argv,
-      cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
-      env: childEnvironment(spec),
-      rows: this.config.rows,
-      cols: this.config.cols,
-      graceMs: this.config.disposeGraceMs,
-      signal: spec.signal,
-    })
+    let terminalSignal: AbortSignal | undefined
+    let detachSetupSignal: (() => void) | undefined
+    if (spec.signal !== undefined) {
+      const source = spec.signal
+      const controller = new AbortController()
+      const onAbort = (): void => { controller.abort(source.reason) }
+      source.addEventListener('abort', onAbort, { once: true })
+      detachSetupSignal = () => { source.removeEventListener('abort', onAbort) }
+      terminalSignal = controller.signal
+    }
+    let terminal: SubprocessTerminalHandle
+    try {
+      terminal = await this.spawnTerminal({
+        argv,
+        cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
+        env: childEnvironment(spec),
+        rows: this.config.rows,
+        cols: this.config.cols,
+        graceMs: this.config.disposeGraceMs,
+        signal: terminalSignal,
+      })
+    } finally {
+      detachSetupSignal?.()
+    }
     const session = this.createSession(terminal, this.config)
     try {
       await session.initialize(spec.signal)
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index f984648f27..9a0beed6ff 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -473,17 +473,23 @@ export class LocalPtySession implements PtyBackendSession {
     this.active = undefined
   }
 
-  private failActive(error: unknown): void {
+  private failActive(error: unknown, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
-    this.clearActive()
+    if (retainOwnership) {
+      this.stopPolling()
+      this.activeAbort?.()
+      this.activeAbort = undefined
+    } else {
+      this.clearActive()
+    }
     operation.fail(error)
   }
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
     void this.terminal.signalForeground('SIGINT').catch((error: unknown) => {
-      if (this.active === operation) this.failActive(error)
+      if (this.active === operation) this.failActive(error, this.writing === operation)
     })
   }
 
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index a8753deaf3..23e6f4bc89 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -187,6 +187,51 @@ describe('LocalPtyBackend startup rollback', () => {
     expect(initialized).toHaveBeenCalledWith(undefined)
   })
 
+  it('forwards setup cancellation only while terminal allocation is unpublished', async () => {
+    const ctx = new Context()
+    await ctx.plugin(EmptySandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+
+    const publishedController = new AbortController()
+    let publishedSignal: AbortSignal | undefined
+    const published = new LocalPtyBackend(
+      ctx,
+      config(),
+      async (spawnSpec) => {
+        publishedSignal = spawnSpec.signal
+        return terminalHandle()
+      },
+      () => stubLocalSession(),
+    )
+    await published.spawn(spec(agent(ctx), publishedController.signal))
+    expect(publishedSignal).toBeDefined()
+    expect(publishedSignal).not.toBe(publishedController.signal)
+    publishedController.abort(new Error('originating turn ended'))
+    expect(publishedSignal?.aborted).toBe(false)
+
+    const pendingController = new AbortController()
+    const seen = Promise.withResolvers<AbortSignal>()
+    const pending = new LocalPtyBackend(
+      ctx,
+      config(),
+      async spawnSpec => await new Promise<SubprocessTerminalHandle>((_resolve, reject) => {
+        const setupSignal = spawnSpec.signal as AbortSignal
+        seen.resolve(setupSignal)
+        const onAbort = (): void => {
+          reject(setupSignal.reason instanceof Error ? setupSignal.reason : new Error(String(setupSignal.reason)))
+        }
+        setupSignal.addEventListener('abort', onAbort, { once: true })
+      }),
+      () => stubLocalSession(),
+    )
+    const spawning = pending.spawn(spec(agent(ctx), pendingController.signal))
+    const pendingSignal = await seen.promise
+    const reason = new Error('cancel pending allocation')
+    pendingController.abort(reason)
+    await expect(spawning).rejects.toBe(reason)
+    expect(pendingSignal.aborted).toBe(true)
+  })
+
   it('composes the default local session around a spawned terminal', async () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts
index c02a9563ea..df05438864 100644
--- a/packages/pty/pty-local/tests/local.spec.ts
+++ b/packages/pty/pty-local/tests/local.spec.ts
@@ -1,4 +1,4 @@
-import { mkdtempSync, realpathSync, rmSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
@@ -156,6 +156,47 @@ describe('pty-local real shell', () => {
     expect(() => process.kill(pid, 0)).toThrow()
   }, 10_000)
 
+  it('reaps a disowned same-session descendant after the shell exits naturally', async () => {
+    const { ctx, root, agent } = await harness('danger-full-access')
+    const created = await ctx.pty.spawn(agent, { type: 'shell' })
+    const pidFile = join(root, 'disowned.pid')
+    let pid: number | undefined
+    try {
+      const background = ctx.pty.startSend(agent, created.sessionId, {
+        text: `sh -c 'trap "" TERM; printf "%s" "$$" > "$1"; sleep 60' dsh "${pidFile}" & disown`,
+        submit: true,
+      })
+      await background.done
+      const pidDeadline = Date.now() + 2_000
+      let childPid = 0
+      while (childPid === 0 && Date.now() < pidDeadline) {
+        if (existsSync(pidFile)) childPid = Number(readFileSync(pidFile, 'utf8'))
+        if (childPid > 0) break
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+      expect(existsSync(pidFile), ctx.pty.read(agent, created.sessionId, { offset: 0, count: 100 }).text).toBe(true)
+      expect(childPid).toBeGreaterThan(0)
+      pid = childPid
+      expect(() => process.kill(childPid, 0)).not.toThrow()
+      await ctx.pty.startSend(agent, created.sessionId, { text: 'exit', submit: true }).done
+      const deadline = Date.now() + 2_000
+      while (ctx.pty.list(agent)[0]?.status.kind !== 'exited' && Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+      expect(ctx.pty.list(agent)[0]?.status.kind).toBe('exited')
+      await ctx.pty.kill(agent, created.sessionId)
+      expect(() => process.kill(childPid, 0)).toThrow()
+    } finally {
+      if (pid !== undefined) {
+        try {
+          process.kill(pid, 'SIGKILL')
+        } catch (_alreadyReaped) {
+          // Product cleanup is the expected path; this only contains a failed regression.
+        }
+      }
+    }
+  }, 10_000)
+
   it('cancels a slow-starting raw-mode foreground process with a real SIGINT', async () => {
     const { ctx, agent } = await harness('danger-full-access', {
       idleSilenceMs: 10_000,
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 6346a6bba2..120b2881e1 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -27,6 +27,7 @@ class FakeInspector implements ProcessInspector {
   foregroundPgid() { return this.pgid }
   isStdinWaiting() { return this.waiting }
   processTree() { return this.members }
+  processSession() { return [] }
   isAlive(identity: ProcessIdentity) { return this.alive.has(identity.pid) }
   signalGroup(pgid: number, signal: PtySignal) {
     if (this.throwGroup) throw new Error('group failed')
@@ -325,6 +326,32 @@ describe('LocalPtySession readiness and output', () => {
     expect((await next.done).waitReason).toBe('inferred_idle')
   })
 
+  it('retains send ownership when cancellation signalling fails during an asynchronous write', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const writeGate = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await writeGate.promise }
+    terminal.signalForeground = async () => { throw new Error('interrupt failed') }
+    const operation = session.startSend({ text: 'slow write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    const rejected = expect(operation.done).rejects.toThrow('interrupt failed')
+    expect(operation.cancel()).toBe(true)
+    await rejected
+    expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow('active send')
+
+    writeGate.resolve(undefined)
+    await Promise.resolve()
+    await Promise.resolve()
+    const next = session.startSend({ text: '', submit: false })
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await next.done).waitReason).toBe('inferred_idle')
+  })
+
   it('handles startup exit, unknown exit signals, cancel-write failure, and stale polls', async () => {
     vi.useFakeTimers()
     const startupTerminal = new FakeTerminal()
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index d931d3574b..72f3c93da9 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: 6bc1003ae5903bb5640728bc79c3f9042fddbe7a
-README.zh.md: 3c9ce73c7fcbeec9b17d73f212ecdcb6842ec133
+README.md: 38b26c33f3854acdb4a2bb48612da73361d727ba
+README.zh.md: fc4a5d4961fb7618b9db84b21063f907361a26d8
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 6bc1003ae5..38b26c33f3 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -11,7 +11,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
 - **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
-- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and cleans descendants before the top-level shell. Linux `/proc`/syscall and macOS `ps` inspectors retain exact pid/start identity so pid reuse cannot redirect cleanup; the higher PTY backend owns prompt readiness, buffers, and model-facing operations.
+- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and cleans descendants before the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
 ## Model Experience
@@ -26,7 +26,7 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 - **Windows tree support is best-effort and untested in CI** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary; the suites cover the routing through an injected runner only, and `packages/subprocess/*` is excluded from the Windows test matrix.
 - **Terminal process inspection is Linux/macOS only** — the terminal primitive fails when its inspector has no supported platform implementation; Linux exact probes cover x64 and arm64, while macOS uses `ps` snapshots.
-- **A daemonized terminal descendant can escape the captured tree** — a child that reparents before teardown is no longer discoverable from the `node-pty` root. The local provider accepts this gap rather than signal the root PID's POSIX session, which can include unrelated launcher processes.
+- **A daemonized terminal descendant can still escape the observable boundary** — on macOS, a child that reparents before any foreground-inspection snapshot is no longer discoverable from the `node-pty` root; on Linux, a child that calls `setsid` leaves both the tree and owned terminal session. The local provider does not add a continuous process-table monitor.
 - **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
 - **Completed spill files are not deleted** — bounded full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them; oversize incomplete spills are discarded and deletion is attempted immediately, but a cleanup failure can leave a bounded file behind.
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 3c9ce73c7f..fc4a5d4961 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -11,7 +11,7 @@
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
 - **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，在资源释放时删除；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
-- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并先于顶层 shell 清理后代。Linux 的 `/proc`／syscall 检查器与 macOS 的 `ps` 检查器会保留精确的 pid／启动身份，使 PID 复用无法把清理重定向到其他进程；上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并先于顶层 shell 清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
 - **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
@@ -26,7 +26,7 @@
 
 - **Windows 进程树支持仅为尽力而为，且未经 CI 测试**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界；测试套件只通过注入的运行器覆盖这条路由，且 `packages/subprocess/*` 被排除在 Windows 测试矩阵之外。
 - **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 使用 `ps` 快照。
-- **守护化的终端后代可能逃离已捕获进程树**：子进程若在拆卸前重新设定父进程，便无法再从 `node-pty` 根发现。本地提供方接受这个缺口，不向根 PID 的 POSIX 会话发送信号，因为其中可能包含无关的启动器进程。
+- **守护化的终端后代仍可能逃出可观察边界**：在 macOS 上，子进程若在任何前台检查快照产生前重新设定父进程，便无法再从 `node-pty` 根发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与该提供方拥有的终端会话。本地提供方不会增加持续运行的进程表监视器。
 - **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSWORD*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
 - **不会删除已完成的 spill 文件**：有界的完整输出恢复文件（以及每个进程的私有 spill 目录）会在 OS tmpdir 下累积，直到外部机制进行清理；超大的不完整 spill 会被丢弃并立即尝试删除，但清理失败可能留下一个有界文件。
 
diff --git a/packages/subprocess/subprocess-local/src/process-inspector.ts b/packages/subprocess/subprocess-local/src/process-inspector.ts
index f57184f289..48b01e18e3 100644
--- a/packages/subprocess/subprocess-local/src/process-inspector.ts
+++ b/packages/subprocess/subprocess-local/src/process-inspector.ts
@@ -16,6 +16,8 @@ export interface ProcessInspector {
   isStdinWaiting(pgid: number): boolean
   /** Return the root and its current transitive descendants, children first. */
   processTree(rootPid: number): ProcessIdentity[]
+  /** Return current members of one POSIX process session when the platform exposes them. */
+  processSession(sessionId: number): ProcessIdentity[]
   /** Return whether the exact identity remains a non-quiescent process. */
   isAlive(identity: ProcessIdentity): boolean
   signalGroup(pgid: number, signal: SubprocessTerminalSignal): void
@@ -201,6 +203,7 @@ abstract class PosixProcessInspector implements ProcessInspector {
   abstract foregroundPgid(shellPid: number): number | undefined
   abstract isStdinWaiting(pgid: number): boolean
   abstract processTree(rootPid: number): ProcessIdentity[]
+  abstract processSession(sessionId: number): ProcessIdentity[]
   abstract isAlive(identity: ProcessIdentity): boolean
 
   signalGroup(pgid: number, signal: SubprocessTerminalSignal): void {
@@ -272,6 +275,13 @@ class LinuxProcessInspector extends PosixProcessInspector {
     return processTree(entries, rootPid)
   }
 
+  processSession(sessionId: number): ProcessIdentity[] {
+    return numericEntries(this.internals, '/proc').flatMap((pid) => {
+      const stat = readLinuxStat(this.internals, pid)
+      return stat?.session === sessionId ? [{ pid, started: stat.started }] : []
+    })
+  }
+
   isAlive(identity: ProcessIdentity): boolean {
     const stat = readLinuxStat(this.internals, identity.pid)
     return stat?.started === identity.started && !/^[ZXx]$/.test(stat.state)
@@ -307,6 +317,10 @@ class MacProcessInspector extends PosixProcessInspector {
     return processTree(macProcessTable(this.internals), rootPid)
   }
 
+  processSession(_sessionId: number): ProcessIdentity[] {
+    return []
+  }
+
   isAlive(identity: ProcessIdentity): boolean {
     return macProcessTable(this.internals).some(entry => entry.pid === identity.pid && entry.started === identity.started)
   }
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index d4b7bd26d1..8446f11b8f 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -36,6 +36,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   private exited = false
   private termination: Promise<void> | undefined
   private removeAbort: (() => void) | undefined
+  private trackedDescendants: ProcessIdentity[] = []
 
   /**
    * @param terminal - allocated node-pty process.
@@ -86,6 +87,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   // Local inspection is synchronous; the seam returns a promise for remote transports.
   // eslint-disable-next-line @typescript-eslint/require-await
   async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+    this.descendants()
     const processGroupId = this.inspector.foregroundPgid(this.pid)
     if (processGroupId === undefined) return undefined
     return {
@@ -145,7 +147,12 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private descendants(): ProcessIdentity[] {
-    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
+    this.trackedDescendants = this.survivors(this.unionMembers(
+      this.trackedDescendants,
+      this.inspector.processTree(this.pid),
+      this.inspector.processSession(this.pid),
+    ).filter(member => member.pid !== this.pid))
+    return this.trackedDescendants
   }
 
   private async waitForMembers(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 7ff10a7348..93be25acd0 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -111,6 +111,7 @@ describe('LocalSubprocessService', () => {
       foregroundPgid: () => undefined,
       isStdinWaiting: () => false,
       processTree: () => [],
+      processSession: () => [],
       isAlive: () => false,
       signalGroup: () => {},
       signalProcess: () => {},
@@ -175,6 +176,7 @@ describe('LocalSubprocessService', () => {
         foregroundPgid: () => 123,
         isStdinWaiting: () => false,
         processTree: () => [{ pid: 124, started: 'child' }],
+        processSession: () => [],
         isAlive: identity => alive.has(identity.pid),
         signalGroup: () => {},
         signalProcess: () => {},
diff --git a/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
index e8ad2fd11e..bcc3ddb091 100644
--- a/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
@@ -86,6 +86,13 @@ describe('Linux process inspector', () => {
       { pid: 10, started: '500' },
     ])
     expect(inspector.processTree(99)).toEqual([])
+    expect(inspector.processSession(30)).toEqual([
+      { pid: 10, started: '500' },
+      { pid: 11, started: '501' },
+      { pid: 12, started: '502' },
+      { pid: 13, started: '503' },
+    ])
+    expect(inspector.processSession(99)).toEqual([])
     expect(inspector.isAlive({ pid: 10, started: '500' })).toBe(true)
     expect(inspector.isAlive({ pid: 10, started: 'old' })).toBe(false)
     inspector.signalGroup(40, 'SIGINT')
@@ -197,6 +204,7 @@ describe('macOS process inspector', () => {
       { pid: 10, started: 'Mon Jul 21 10:00:00 2026' },
     ])
     expect(inspector.processTree(99)).toEqual([])
+    expect(inspector.processSession(10)).toEqual([])
     expect(inspector.isAlive({ pid: 11, started: 'Mon Jul 21 10:00:01 2026' })).toBe(true)
     inspector.signalGroup(55, 'SIGTSTP')
     inspector.signalProcess({ pid: 11, started: 'Mon Jul 21 10:00:01 2026' }, 'SIGKILL')
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
index 417fd62517..0202a3f33e 100644
--- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -51,6 +51,7 @@ class FakeInspector implements ProcessInspector {
   pgid: number | undefined = 456
   waiting = false
   members: ProcessIdentity[] = []
+  sessionMembers: ProcessIdentity[] = []
   readonly alive = new Set<number>()
   readonly groups: Array<[number, SubprocessTerminalSignal]> = []
   readonly processes: Array<[number, 'SIGTERM' | 'SIGKILL']> = []
@@ -61,6 +62,7 @@ class FakeInspector implements ProcessInspector {
   foregroundPgid() { return this.pgid }
   isStdinWaiting() { return this.waiting }
   processTree() { return this.members }
+  processSession() { return this.sessionMembers }
   isAlive(identity: ProcessIdentity) { return this.alive.has(identity.pid) }
   signalGroup(pgid: number, signal: SubprocessTerminalSignal) {
     if (this.throwGroup) throw new Error('group failed')
@@ -158,6 +160,36 @@ describe('LocalTerminalHandle', () => {
     expect(await waiting).toBe(true)
   })
 
+  it('cleans a same-session descendant after the top-level shell exits naturally', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const disowned = { pid: 124, started: 'disowned' }
+    inspector.processSession = () => inspector.alive.has(disowned.pid) ? [disowned] : []
+    inspector.alive.add(124)
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
+
+    pty.emitExit()
+
+    expect(await handle.waitForExit()).toBe(true)
+    expect(inspector.processes).toEqual([[124, 'SIGTERM']])
+  })
+
+  it('retains an inspected descendant after it reparents away from the shell', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const descendant = { pid: 124, started: 'observed' }
+    inspector.members = [descendant]
+    inspector.alive.add(descendant.pid)
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
+
+    await handle.inspectForeground()
+    inspector.members = []
+    pty.emitExit()
+
+    expect(await handle.waitForExit()).toBe(true)
+    expect(inspector.processes).toEqual([[124, 'SIGTERM']])
+  })
+
   it('rescans for descendants forked during TERM', async () => {
     const pty = new FakePty()
     const inspector = new FakeInspector()
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index 384c9cdb94..13b8df9f71 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: db4478fe799dce1bbdb7e3ae3d31947515aae151
-README.zh.md: 238f5f66db58edb99945cfa43299635b4f8f36a8
+README.md: fd8cfccdb333018e551459195564daad157d3867
+README.zh.md: b5b495e22bbf4328d82925cc793588ee45e5c6e4

From 65264f6c80f034b0c1c0bd448c5635506b98b792 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 03:17:40 +0800
Subject: [PATCH 298/516] refactor(subprocess): share terminal lifecycle

---
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |   2 +-
 ...8-portable-execution-world-consumers.zh.md |   2 +-
 .../subprocess-local/src/terminal.ts          |  47 ++-----
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.md      |   1 +
 packages/subprocess/subprocess/README.zh.md   |   1 +
 packages/subprocess/subprocess/src/index.ts   |   2 +
 .../subprocess/src/terminal-lifecycle.ts      | 104 +++++++++++++++
 .../tests/terminal-lifecycle.spec.ts          | 125 ++++++++++++++++++
 10 files changed, 248 insertions(+), 44 deletions(-)
 create mode 100644 packages/subprocess/subprocess/src/terminal-lifecycle.ts
 create mode 100644 packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index f97b09b940..231037f054 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 3d1928be882fb3fb621e733649146445c69e8a5b
-2026-07-28-portable-execution-world-consumers.zh.md: f385e502d5d737fe0d5ae6e28ac7a3a097d85a6b
+2026-07-28-portable-execution-world-consumers.md: a5df393f31a25b7d16e63af240882e1d94093e34
+2026-07-28-portable-execution-world-consumers.zh.md: 87f11fa53b5b7579969dcb15dc3aaad978018773
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 3d1928be88..a5df393f31 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -16,7 +16,7 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all
 
 The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, containment, and a bounded stable-handle text read. The existing text and mutation operations remain filesystem-owned.
 
-The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns byte I/O, foreground groups, signalling, TERM-to-KILL session cleanup, and a quiescence wait. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns byte I/O, foreground groups, signalling, TERM-to-KILL session cleanup, and a quiescence wait. The interface package also exports a provider-neutral lifecycle controller that joins top-level settlement, lifetime cancellation, retryable provider cleanup, and bounded quiescence observation; each implementation supplies only its session-cleanup transaction. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
 
 Generic consumers use that execution world:
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index f385e502d5..87f11fa53b 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI、包含关系，以及通过稳定句柄执行的有界文本读取。现有文本与变更操作仍归文件系统负责。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责字节 I/O、前台进程组管理、信号发送、TERM→KILL 会话清理以及等待完全停稳。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责字节 I/O、前台进程组管理、信号发送、TERM→KILL 会话清理以及等待完全停稳。接口包还导出一个提供方无关的生命周期控制器，用于组合顶层结算、生命周期取消、可重试的提供方清理与有界的完全停稳观测；每个实现只需提供自身的会话清理事务。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 8446f11b8f..2f1e4d4058 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -4,6 +4,7 @@ import { Buffer } from 'node:buffer'
 import { constants } from 'node:os'
 import { PassThrough } from 'node:stream'
 import type { IDisposable, IPty } from 'node-pty'
+import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessOutcome,
   SubprocessTerminalForeground,
@@ -33,9 +34,8 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   private readonly outcome = Promise.withResolvers<SubprocessOutcome>()
   private readonly dataDisposable: IDisposable
   private readonly exitDisposable: IDisposable
+  private readonly lifecycle: SubprocessTerminalLifecycle
   private exited = false
-  private termination: Promise<void> | undefined
-  private removeAbort: (() => void) | undefined
   private trackedDescendants: ProcessIdentity[] = []
 
   /**
@@ -63,12 +63,11 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
       })
       this.terminate()
     })
-    if (signal !== undefined) {
-      const onAbort = (): void => { this.terminate() }
-      signal.addEventListener('abort', onAbort, { once: true })
-      this.removeAbort = () => { signal.removeEventListener('abort', onAbort) }
-      if (signal.aborted) this.terminate()
-    }
+    this.lifecycle = new SubprocessTerminalLifecycle({
+      done: this.done,
+      cleanup: () => this.closeOnce(),
+      signal,
+    })
   }
 
   // node-pty writes synchronously; the seam returns a promise for remote transports.
@@ -109,37 +108,11 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   }
 
   terminate(): void {
-    this.termination ??= this.closeOnce().catch((error: unknown) => {
-      this.termination = undefined
-      throw error
-    })
-    void this.termination.catch(() => {})
+    this.lifecycle.terminate()
   }
 
   async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    // A caller may begin waiting before the top-level process exits. The exit
-    // callback starts descendant cleanup in the same turn, so resolve that
-    // eventual transaction after `done` instead of snapshotting only `done`.
-    const quiescence = this.termination ?? this.done.then(() => this.termination)
-    if (signal === undefined) {
-      await quiescence
-      return true
-    }
-    if (signal.aborted) return false
-    return await new Promise<boolean>((resolve, reject) => {
-      const onAbort = (): void => { cleanup(); resolve(false) }
-      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
-      signal.addEventListener('abort', onAbort, { once: true })
-      void quiescence.then(
-        () => { cleanup(); resolve(true) },
-        (error: unknown) => {
-          cleanup()
-          // The owned cleanup transaction only throws Error diagnostics.
-          // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
-          reject(error)
-        },
-      )
-    })
+    return await this.lifecycle.waitForExit(signal)
   }
 
   private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
@@ -225,8 +198,6 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
       throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
     }
     await this.stopShell()
-    this.removeAbort?.()
-    this.removeAbort = undefined
     this.dataDisposable.dispose()
     this.exitDisposable.dispose()
   }
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 84d7d4a666..8e6c6a88e4 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: 84b4b0c11c74c96929fa97b58fb33156d44e6ef1
-README.zh.md: dbd80a1c975719884481501f5cc43798e464a4fb
+README.md: d03824da33bb44b2525b1343a27557ed15823418
+README.zh.md: 34cc75c3cfc8148754343e92b0c204760b1fb543
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index 84b4b0c11c..d03824da33 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -12,6 +12,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
 - `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, valid-UTF-8 byte I/O, foreground-process-group inspection/signalling, TERM-to-KILL whole-session cleanup, and a quiescence wait. The output stream ends after queued output when the top-level process exits; a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or prove and clean the complete terminal session; readiness, scrollback, and owner policy remain in the PTY consumer.
+- `SubprocessTerminalLifecycle` composes a handle's top-level `done` promise with its provider-owned session cleanup. It binds lifetime cancellation, shares one active cleanup attempt, permits a failed attempt to retry, normalizes cleanup rejections, and bounds quiescence observation without knowing the provider's process mechanics.
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index dbd80a1c97..34cc75c3cf 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -12,6 +12,7 @@
 - stdio 按流采用 Node 形状：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
 - `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、有效 UTF-8 字节 I/O、前台进程组检查／信号发送、TERM→KILL 全会话清理，以及等待完全停稳。顶层进程退出后，输出流会在排完队列中的输出后结束；存活期间的传输故障会拒绝 `done`。这些操作仍属于一项基底原语，因为普通管道无法分配控制终端，也无法证明并清理完整的终端会话；就绪检测、scrollback 与所有者策略仍归 PTY 消费方所有。
+- `SubprocessTerminalLifecycle` 把句柄的顶层 `done` promise 与由提供方负责的会话清理组合起来。它绑定生命周期取消，共享同一个进行中的清理尝试，允许失败的尝试重试，规范化清理拒绝，并在不了解提供方进程机制的情况下对完全停稳观测施加上限。
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的凭据清除定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地普通 spawn 与终端 spawn 都应用这一定义；自行拥有 spawn 的 SDK 管理传输层可以直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index 3c58a07a9e..df79ee5f3e 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -14,6 +14,8 @@ import type { SubprocessHandle, SubprocessSpawnSpec } from './types.ts'
 import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from './types.ts'
 
 export { DSH_ENV_PREFIX } from './types.ts'
+export { SubprocessTerminalLifecycle } from './terminal-lifecycle.ts'
+export type { SubprocessTerminalLifecycleOptions } from './terminal-lifecycle.ts'
 export type {
   CollectedOutput,
   DshEnvironment,
diff --git a/packages/subprocess/subprocess/src/terminal-lifecycle.ts b/packages/subprocess/subprocess/src/terminal-lifecycle.ts
new file mode 100644
index 0000000000..76430fe7c6
--- /dev/null
+++ b/packages/subprocess/subprocess/src/terminal-lifecycle.ts
@@ -0,0 +1,104 @@
+/** Provider-neutral lifecycle transaction for terminal-process handles. */
+
+/** Inputs owned by one terminal-process lifecycle controller. */
+export interface SubprocessTerminalLifecycleOptions {
+  /** Settlement of the top-level terminal process or its live transport. */
+  readonly done: Promise<unknown>
+  /** Provider-owned cleanup that reaches whole-session quiescence. */
+  readonly cleanup: () => Promise<void>
+  /** Optional cancellation for the complete terminal lifetime. */
+  readonly signal?: AbortSignal | undefined
+}
+
+function normalizeCleanupError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+/**
+ * Coordinates terminal cleanup without knowing how a provider allocates or
+ * terminates its process session. One active cleanup attempt is shared by all
+ * callers; a rejected attempt may be retried, and successful cleanup removes
+ * the lifetime abort listener.
+ */
+export class SubprocessTerminalLifecycle {
+  private cleanupAttempt: Promise<void> | undefined
+  private removeLifetimeAbort: (() => void) | undefined
+
+  /**
+   * @param options - top-level settlement, provider cleanup, and lifetime cancellation.
+   */
+  constructor(private readonly options: SubprocessTerminalLifecycleOptions) {
+    const onDone = (): void => { this.terminate() }
+    void options.done.then(onDone, onDone)
+
+    if (options.signal !== undefined) {
+      const onAbort = (): void => { this.terminate() }
+      options.signal.addEventListener('abort', onAbort, { once: true })
+      this.removeLifetimeAbort = () => { options.signal?.removeEventListener('abort', onAbort) }
+      if (options.signal.aborted) this.terminate()
+    }
+  }
+
+  /** Begin an idempotent provider cleanup attempt. */
+  terminate(): void {
+    void this.startCleanup().catch(() => {})
+  }
+
+  /**
+   * Wait for top-level settlement and successful whole-session cleanup.
+   * @param signal - optional bound for this observation only.
+   * @returns true after quiescence, false when the observer signal aborts first.
+   */
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    const quiescence = this.cleanupAttempt ?? this.options.done.then(
+      () => this.startCleanup(),
+      () => this.startCleanup(),
+    )
+    if (signal === undefined) {
+      await quiescence
+      return true
+    }
+    if (signal.aborted) return false
+
+    return await new Promise<boolean>((resolve, reject) => {
+      let settled = false
+      const finish = (complete: () => void): void => {
+        if (settled) return
+        settled = true
+        signal.removeEventListener('abort', onAbort)
+        complete()
+      }
+      const onAbort = (): void => { finish(() => { resolve(false) }) }
+
+      signal.addEventListener('abort', onAbort, { once: true })
+      if (signal.aborted) onAbort()
+      void quiescence.then(
+        () => { finish(() => { resolve(true) }) },
+        (error: unknown) => { finish(() => { reject(normalizeCleanupError(error)) }) },
+      )
+    })
+  }
+
+  private startCleanup(): Promise<void> {
+    if (this.cleanupAttempt !== undefined) return this.cleanupAttempt
+
+    const outcome = Promise.withResolvers<void>()
+    this.cleanupAttempt = outcome.promise.catch((error: unknown) => {
+      this.cleanupAttempt = undefined
+      throw normalizeCleanupError(error)
+    })
+    void this.cleanupAttempt.then(
+      () => {
+        this.removeLifetimeAbort?.()
+        this.removeLifetimeAbort = undefined
+      },
+      () => {},
+    )
+    try {
+      void this.options.cleanup().then(outcome.resolve, outcome.reject)
+    } catch (error: unknown) {
+      outcome.reject(error)
+    }
+    return this.cleanupAttempt
+  }
+}
diff --git a/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts b/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts
new file mode 100644
index 0000000000..2dd688bbc0
--- /dev/null
+++ b/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it, vi } from 'vitest'
+import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
+
+describe('SubprocessTerminalLifecycle', () => {
+  it('waits for top-level settlement and the provider cleanup transaction', async () => {
+    const done = Promise.withResolvers<undefined>()
+    const cleanupGate = Promise.withResolvers<undefined>()
+    const cleanup = vi.fn(() => cleanupGate.promise)
+    const lifecycle = new SubprocessTerminalLifecycle({ done: done.promise, cleanup })
+
+    const waiting = lifecycle.waitForExit()
+    expect(cleanup).not.toHaveBeenCalled()
+    done.resolve(undefined)
+    await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() })
+
+    const observed = vi.fn()
+    void waiting.then(observed)
+    await Promise.resolve()
+    expect(observed).not.toHaveBeenCalled()
+
+    cleanupGate.resolve(undefined)
+    await expect(waiting).resolves.toBe(true)
+    lifecycle.terminate()
+    await expect(lifecycle.waitForExit()).resolves.toBe(true)
+    expect(cleanup).toHaveBeenCalledOnce()
+  })
+
+  it('normalizes cleanup failures, permits retries, and retains lifetime cancellation until success', async () => {
+    const done = Promise.withResolvers<undefined>()
+    const lifetime = new AbortController()
+    const removeListener = vi.spyOn(lifetime.signal, 'removeEventListener')
+    const synchronousFailure = new Error('first cleanup failed')
+    let attempt = 0
+    const cleanup = vi.fn((): Promise<void> => {
+      attempt += 1
+      if (attempt === 1) throw synchronousFailure
+      if (attempt === 2) {
+        return Promise.resolve().then(() => {
+          const nonErrorRejection: unknown = 'cleanup transport gone'
+          throw nonErrorRejection
+        })
+      }
+      return Promise.resolve()
+    })
+    const lifecycle = new SubprocessTerminalLifecycle({
+      done: done.promise,
+      cleanup,
+      signal: lifetime.signal,
+    })
+
+    lifecycle.terminate()
+    await expect(lifecycle.waitForExit()).rejects.toBe(synchronousFailure)
+    lifecycle.terminate()
+    await expect(lifecycle.waitForExit()).rejects.toThrow('cleanup transport gone')
+
+    lifetime.abort()
+    await expect(lifecycle.waitForExit()).resolves.toBe(true)
+    expect(cleanup).toHaveBeenCalledTimes(3)
+    expect(removeListener).toHaveBeenCalledWith('abort', expect.any(Function))
+
+    done.reject(new Error('top-level transport failed'))
+    await Promise.resolve()
+    expect(cleanup).toHaveBeenCalledTimes(3)
+  })
+
+  it('starts cleanup for a pre-aborted lifetime and bounds a wait that is already aborted', async () => {
+    const cleanupGate = Promise.withResolvers<undefined>()
+    const cleanup = vi.fn(() => cleanupGate.promise)
+    const lifecycle = new SubprocessTerminalLifecycle({
+      done: new Promise(() => {}),
+      cleanup,
+      signal: AbortSignal.abort(new Error('lifetime cancelled')),
+    })
+
+    expect(cleanup).toHaveBeenCalledOnce()
+    await expect(lifecycle.waitForExit(AbortSignal.abort())).resolves.toBe(false)
+    cleanupGate.resolve(undefined)
+    await expect(lifecycle.waitForExit()).resolves.toBe(true)
+  })
+
+  it('contains cleanup settlement after an observer aborts between signal checks', async () => {
+    const firstCleanup = Promise.withResolvers<undefined>()
+    const cleanup = vi.fn()
+      .mockImplementationOnce(() => firstCleanup.promise)
+      .mockResolvedValueOnce(undefined)
+    const lifecycle = new SubprocessTerminalLifecycle({ done: Promise.resolve(), cleanup })
+    const observer = new AbortController().signal
+    vi.spyOn(observer, 'aborted', 'get')
+      .mockReturnValueOnce(false)
+      .mockReturnValueOnce(true)
+
+    await expect(lifecycle.waitForExit(observer)).resolves.toBe(false)
+    firstCleanup.reject(new Error('late cleanup failure'))
+    await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() })
+    await Promise.resolve()
+
+    lifecycle.terminate()
+    await expect(lifecycle.waitForExit()).resolves.toBe(true)
+    expect(cleanup).toHaveBeenCalledTimes(2)
+  })
+
+  it('reports bounded cleanup success and failure', async () => {
+    const successful = new SubprocessTerminalLifecycle({
+      done: Promise.resolve(),
+      cleanup: async () => {},
+    })
+    await expect(successful.waitForExit(new AbortController().signal)).resolves.toBe(true)
+
+    const failure = new Error('quiescence failed')
+    const failed = new SubprocessTerminalLifecycle({
+      done: Promise.resolve(),
+      cleanup: () => Promise.reject(failure),
+    })
+    await expect(failed.waitForExit(new AbortController().signal)).rejects.toBe(failure)
+
+    const failedDone = Promise.withResolvers<undefined>()
+    const afterTransportFailure = new SubprocessTerminalLifecycle({
+      done: failedDone.promise,
+      cleanup: async () => {},
+    })
+    const waiting = afterTransportFailure.waitForExit()
+    failedDone.reject(new Error('transport failed'))
+    await expect(waiting).resolves.toBe(true)
+  })
+})

From a0200376a1aaa35e00c1e2583b47f5a39c5ba157 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 03:44:57 +0800
Subject: [PATCH 299/516] fix(pty): defer the first readiness poll

---
 packages/pty/pty-local/src/session.ts        |  2 +-
 packages/pty/pty-local/tests/session.spec.ts | 25 ++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 9a0beed6ff..03809aec9f 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -266,7 +266,7 @@ export class LocalPtySession implements PtyBackendSession {
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
       if (this.active === operation && !this.closing) {
         this.pollingReady = operation
-        this.schedulePoll(operation, 0)
+        this.schedulePoll(operation)
       }
     } catch (error: unknown) {
       if (this.active === operation) {
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 120b2881e1..5f0065d0ee 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -143,6 +143,31 @@ async function initialize(session: LocalPtySession, terminal: FakeTerminal): Pro
 }
 
 describe('LocalPtySession readiness and output', () => {
+  it('lets queued terminal output run before the first post-write readiness poll', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const inspect = terminal.inspectForeground.bind(terminal)
+    let inspections = 0
+    terminal.inspectForeground = async () => {
+      inspections += 1
+      return await inspect()
+    }
+    const operation = session.startSend({ text: 'true', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(inspections).toBe(1)
+
+    await vi.advanceTimersByTimeAsync(0)
+    expect(inspections).toBe(1)
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect((await operation.done).waitReason).toBe('stdin_read')
+  })
+
   it('captures prompt MOTD, writes submit explicitly, and settles exact stdin waits', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From 03f1c8eb437885469e3478a6982c525b4de6cb50 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 03:45:06 +0800
Subject: [PATCH 300/516] fix(subprocess): absolutize relative PATH lookups

---
 packages/subprocess/subprocess-local/src/index.ts        | 4 ++--
 packages/subprocess/subprocess-local/tests/local.spec.ts | 5 ++++-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 40d2f52552..03755cd9ea 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -11,7 +11,7 @@ import { constants } from 'node:fs'
 import { mkdtempSync } from 'node:fs'
 import { access, rm, stat } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { delimiter, extname, isAbsolute, join } from 'node:path'
+import { delimiter, extname, isAbsolute, join, resolve } from 'node:path'
 import { Context } from 'cordis'
 import * as nodePty from 'node-pty'
 import type { IPtyForkOptions } from 'node-pty'
@@ -107,7 +107,7 @@ export class LocalSubprocessService extends SubprocessService {
       ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
       : ['']
     return path.split(delimiter).flatMap(directory =>
-      directory === '' ? [] : extensions.map(extension => join(directory, command + extension)))
+      directory === '' ? [] : extensions.map(extension => resolve(this.cwd, directory, command + extension)))
   }
 
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 93be25acd0..6ce3d06b8e 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,7 +1,7 @@
 import { PassThrough } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
 import { stat } from 'node:fs/promises'
-import { basename, delimiter, dirname } from 'node:path'
+import { basename, delimiter, dirname, relative } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import type { SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
@@ -38,6 +38,9 @@ describe('LocalSubprocessService', () => {
     expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), {
       PATH: dirname(process.execPath),
     })).toBe(process.execPath)
+    expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), {
+      PATH: relative(process.cwd(), dirname(process.execPath)) || '.',
+    })).toBe(process.execPath)
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('must be non-empty')
     await expect(ctx.subprocess.resolveExecutable('dsh-command-that-does-not-exist', { PATH: '' }))
       .rejects.toThrow('was not found on PATH')

From 35376658061cc35aaf9316eca3100af6d0445357 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 04:19:04 +0800
Subject: [PATCH 301/516] fix(subprocess): honor Windows environment key casing

---
 packages/subprocess/subprocess-local/src/index.ts    | 12 ++++++++++--
 .../subprocess/subprocess-local/tests/local.spec.ts  |  4 +++-
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 03755cd9ea..4c5cad8018 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -102,9 +102,9 @@ export class LocalSubprocessService extends SubprocessService {
   }
 
   private executableCandidates(command: string, env: NodeJS.ProcessEnv): string[] {
-    const path = env.PATH ?? ''
+    const path = environmentValue(env, 'PATH') ?? ''
     const extensions = process.platform === 'win32' && extname(command) === ''
-      ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+      ? (environmentValue(env, 'PATHEXT') ?? '.COM;.EXE;.BAT;.CMD').split(';')
       : ['']
     return path.split(delimiter).flatMap(directory =>
       directory === '' ? [] : extensions.map(extension => resolve(this.cwd, directory, command + extension)))
@@ -156,4 +156,12 @@ export class LocalSubprocessService extends SubprocessService {
   }
 }
 
+/** Read a Windows environment key using the platform's case-insensitive semantics. */
+function environmentValue(env: NodeJS.ProcessEnv, name: 'PATH' | 'PATHEXT'): string | undefined {
+  const exact = env[name]
+  if (exact !== undefined || process.platform !== 'win32') return exact
+  const normalized = name.toUpperCase()
+  return Object.entries(env).find(([key]) => key.toUpperCase() === normalized)?.[1]
+}
+
 export default LocalSubprocessService
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 6ce3d06b8e..4662283aad 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -62,8 +62,10 @@ describe('LocalSubprocessService', () => {
     }).executableCandidates.bind(service)
     const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
     try {
-      expect(candidates('tool', { PATH: `${delimiter}/bin`, PATHEXT: '.EXE;.CMD' }))
+      expect(candidates('tool', { Path: `${delimiter}/bin`, PathExt: '.EXE;.CMD' }))
         .toEqual(['/bin/tool.EXE', '/bin/tool.CMD'])
+      expect(candidates('tool', { Path: '/ambient', PATH: '/explicit', PATHEXT: '.EXE' }))
+        .toEqual(['/explicit/tool.EXE'])
       expect(candidates('tool.exe', {})).toEqual([])
       expect(candidates('tool', { PATH: '/bin' })).toHaveLength(4)
     } finally {

From 4997fb219e38e26ef7e76d4c0531f029849bfc96 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 04:19:18 +0800
Subject: [PATCH 302/516] fix(lsp): preserve execution-world URI semantics

---
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |  4 +-
 .../2026-07-15-lsp-capability-seam.md         |  6 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |  6 +-
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 docs/core-data-structures/lsp.i18n.yaml       |  4 +-
 docs/core-data-structures/lsp.md              | 12 ++--
 docs/core-data-structures/lsp.zh.md           | 12 ++--
 packages/lsp/lsp-local/src/instance.ts        |  7 +-
 packages/lsp/lsp-local/tests/instance.spec.ts |  8 +--
 .../lsp/lsp-local/tests/lifecycle.spec.ts     |  8 +--
 packages/lsp/lsp/README.i18n.yaml             |  4 +-
 packages/lsp/lsp/README.md                    |  2 +-
 packages/lsp/lsp/README.zh.md                 | 14 ++--
 packages/lsp/lsp/src/types.ts                 | 10 +--
 packages/lsp/lsp/tests/lsp.spec.ts            |  8 +--
 packages/lsp/tool-lsp/README.i18n.yaml        |  4 +-
 packages/lsp/tool-lsp/README.md               |  2 +-
 packages/lsp/tool-lsp/README.zh.md            | 16 ++---
 packages/lsp/tool-lsp/src/index.ts            |  6 +-
 packages/lsp/tool-lsp/src/render.ts           | 72 ++++++++++++++-----
 packages/lsp/tool-lsp/tests/render.spec.ts    | 45 ++++++++----
 packages/lsp/tool-lsp/tests/tool-lsp.spec.ts  | 11 +--
 24 files changed, 162 insertions(+), 107 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index afb9251d33..bba045d606 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: a9dab45ebf034f6d5218b25a0868a7e86803719b
-2026-07-15-lsp-capability-seam.zh.md: b411a2456ea2a3838e56422f58954473da51ae23
+2026-07-15-lsp-capability-seam.md: 6e46fac0611c1b7282766cf57965a07e3ee6bb9b
+2026-07-15-lsp-capability-seam.zh.md: b535b60df70e8a6132bb1596581be3ab1daba932
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index a9dab45ebf..6e46fac061 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -62,7 +62,7 @@ interface LspProviderQuery extends LspQueryRequest {
 }
 
 type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: { readonly contents: string; readonly range?: LspRange } | null }
 
 interface LspProvider {
@@ -77,7 +77,7 @@ interface LspService {
 }
 ```
 
-Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `findReferences` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`; navigation results carry the provider's resolved workspace root so consumers relativize file URIs in the same canonical namespace. The seam exposes no protocol types, process or document controls, or generic request escape hatch.
+Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `findReferences` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`; navigation results carry the provider's canonical workspace URI so consumers relativize file URIs in the execution world's namespace. The seam exposes no protocol types, process or document controls, or generic request escape hatch.
 
 `dsh-lsp-local` owns server configuration, JSON-RPC, process and transient-document state, and protocol translation. It reads through `ctx.fs` and launches through `ctx.subprocess`, depending on their interface packages rather than concrete providers; the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) owns that pairing. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider.
 
@@ -98,7 +98,7 @@ interface LspToolInput {
 
 The tool requires `workspaceRoot` from session `header.cwd`, with no fallback; absence fails as `LSP_WORKSPACE_REQUIRED` before querying or startup. The local provider resolves relative paths against that root and accepts absolute paths directly; both forms are canonicalized and rejected before startup when the target is outside the canonical workspace.
 
-Locations render as stable, file-grouped `path:line:character` entries. A `file:` URI accepted by Node `fileURLToPath()` becomes a relative path inside the workspace or an absolute path outside it; other URIs remain verbatim. `maxLocations` defaults to `100` and reports omitted items; `maxResultChars` defaults to `16_000` and bounds every complete rendered result, including its truncation metadata. Empty locations and `null` hover are successful no-result responses; missing or malformed server payloads fail with structured `LSP_MALFORMED_RESPONSE` errors.
+Locations render as stable, file-grouped `path:line:character` entries without applying harness-host path rules. A valid `file:` URI becomes a relative path inside the provider's canonical workspace URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs remain verbatim. `maxLocations` defaults to `100` and reports omitted items; `maxResultChars` defaults to `16_000` and bounds every complete rendered result, including its truncation metadata. Empty locations and `null` hover are successful no-result responses; missing or malformed server payloads fail with structured `LSP_MALFORMED_RESPONSE` errors.
 
 The transport-neutral presenter uses `{ card: 'generic', kind: 'search', title, locations: [{ path: file_path, line }] }` with an args-derived operation/cursor `title`. Because `FileLocation` has no character, follow-along focuses the input line while the title preserves the cursor; presentation remains pure.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index b411a2456e..b535b60df7 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -62,7 +62,7 @@ interface LspProviderQuery extends LspQueryRequest {
 }
 
 type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: { readonly contents: string; readonly range?: LspRange } | null }
 
 interface LspProvider {
@@ -77,7 +77,7 @@ interface LspService {
 }
 ```
 
-映射键规范化为带前导点的小写扩展名，并按 `filePath` 的最后一个扩展名选择；语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`findReferences` 始终包含声明：提供方在内部执行该约束，本地映射设置 `context.includeDeclaration: true`，调用方不能配置。封闭结果联合将导航统一为位置，将 `hover` 统一为内容或 `null`；导航结果携带提供方解析后的工作区根目录，使消费方依据同一规范化根目录相对化文件 URI。服务边界不公开协议类型、进程或文档控制，也不提供通用请求逃生口。
+映射键规范化为带前导点的小写扩展名，并按 `filePath` 的最后一个扩展名选择；语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`findReferences` 始终包含声明：提供方在内部执行该约束，本地映射设置 `context.includeDeclaration: true`，调用方不能配置。封闭结果联合将导航统一为位置，将 `hover` 统一为内容或 `null`；导航结果携带提供方的规范工作区 URI，使消费方在执行世界的命名空间内相对化文件 URI。服务边界不公开协议类型、进程或文档控制，也不提供通用请求逃生口。
 
 `dsh-lsp-local` 负责服务器配置、JSON-RPC、进程与临时文档状态和协议转换。它通过 `ctx.fs` 读取，通过 `ctx.subprocess` 启动，只依赖二者的接口包而非具体提供方；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)负责定义这种配对。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
 
@@ -98,7 +98,7 @@ interface LspToolInput {
 
 工具必须从会话 `header.cwd` 取得 `workspaceRoot`，没有后备值；缺失时在查询或启动前以 `LSP_WORKSPACE_REQUIRED` 失败。本地提供方基于根目录解析相对路径并直接接受绝对路径；两种路径都会进行规范化，如果目标位于规范工作区外，则在启动前拒绝。
 
-位置按文件稳定分组并渲染为 `path:line:character`。Node `fileURLToPath()` 可接受的 `file:` URI 在工作区内转换为相对路径，在工作区外转换为绝对路径；其他 URI 保持原样。`maxLocations` 默认值为 `100`，并报告省略的条目；`maxResultChars` 默认值为 `16_000`，并限制每个完整渲染结果，其中包括截断元数据。空位置与 `null` hover 是成功的无结果响应；服务器载荷缺失或格式错误时，以结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
+位置在不应用 harness 宿主路径规则的情况下按文件稳定分组并渲染为 `path:line:character`。有效的 `file:` URI 落在提供方的规范工作区 URI 内时转换为相对路径，位于其外时转换为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。`maxLocations` 默认值为 `100`，并报告省略的条目；`maxResultChars` 默认值为 `16_000`，并限制每个完整渲染结果，其中包括截断元数据。空位置与 `null` hover 是成功的无结果响应；服务器载荷缺失或格式错误时，以结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
 
 与传输方式无关的展示器使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_path, line }] }`，`title` 由参数推导并标明操作与光标。由于 `FileLocation` 没有 character，跟随位置聚焦输入行，标题保留完整光标；展示保持纯函数。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 231037f054..1033fffcc6 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: a5df393f31a25b7d16e63af240882e1d94093e34
-2026-07-28-portable-execution-world-consumers.zh.md: 87f11fa53b5b7579969dcb15dc3aaad978018773
+2026-07-28-portable-execution-world-consumers.md: 6f75778398e8f204c85b64fe096838a3b62d398e
+2026-07-28-portable-execution-world-consumers.zh.md: 22edc591f7716a92fd2a68d74c84168189743fbd
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index a5df393f31..6f75778398 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -21,7 +21,7 @@ The subprocess interface owns the process coordinates and primitives: canonical
 Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
-- `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and sends provider-owned file URIs. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
+- `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. A timed-out asynchronous write, or a cancellation whose foreground signal fails during that write, retains the send reservation until the provider settles it; completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 87f11fa53b..22edc591f7 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
-- `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并发送由提供方负责的文件 URI。其 JSON-RPC、池化、同步、取消和规范化保持不变。
+- `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
 - `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。异步写入超时，或在该写入期间取消时前台信号发送失败，都会保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
diff --git a/docs/core-data-structures/lsp.i18n.yaml b/docs/core-data-structures/lsp.i18n.yaml
index 5bed4a1a23..329d5086e0 100644
--- a/docs/core-data-structures/lsp.i18n.yaml
+++ b/docs/core-data-structures/lsp.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 docs/core-data-structures/lsp.md
-lsp.md: 62b133cbfdf521e067c56355664d7514a613397f
-lsp.zh.md: 51a19a51a8ad92e744cb920a51f3214f68ae0036
+lsp.md: 03d0ce2dbe246aadb6f6c9a702fa50e3e792eb09
+lsp.zh.md: ef9623f01124bc459d3bbceba340c3870e678baa
diff --git a/docs/core-data-structures/lsp.md b/docs/core-data-structures/lsp.md
index 62b133cbfd..03d0ce2dbe 100644
--- a/docs/core-data-structures/lsp.md
+++ b/docs/core-data-structures/lsp.md
@@ -73,7 +73,7 @@ interface LspProviderQuery extends LspQueryRequest {
 
 ## Result
 
-A CLOSED discriminated union: navigation operations normalize to `locations`, `hover` to content or `null`. Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled. `findReferences` always includes declarations — the provider enforces this internally, so callers get no flag. The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the request's `workspaceRoot` and the root its `file:` URIs are relative to, so a caller relativizing display paths uses it rather than the possibly-symlinked request root.
+A CLOSED discriminated union: navigation operations normalize to `locations`, `hover` to content or `null`. Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled. `findReferences` always includes declarations — the provider enforces this internally, so callers get no flag. The `locations` variant carries `resolvedWorkspaceUri`, the provider's canonical workspace `file:` URI. A caller relativizing location URIs uses that coordinate rather than applying host-platform path rules to the possibly-symlinked request root.
 
 ```ts type-equiv
 /** One resolved location: a document URI and the range within it. */
@@ -101,13 +101,13 @@ interface LspHover {
  * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
  * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
  *
- * The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the
- * request's `workspaceRoot`, and the root its `file:` location URIs are relative to. A caller that
- * relativizes display paths MUST use this, not the request's (possibly symlinked) `workspaceRoot`;
- * otherwise a symlinked workspace misclassifies in-workspace results as external.
+ * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
+ * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
+ * request's possibly symlinked process path with host-platform rules; the execution platform may
+ * differ from the caller's.
  */
 type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: LspHover | null }
 ```
 
diff --git a/docs/core-data-structures/lsp.zh.md b/docs/core-data-structures/lsp.zh.md
index 51a19a51a8..d428f2b5f9 100644
--- a/docs/core-data-structures/lsp.zh.md
+++ b/docs/core-data-structures/lsp.zh.md
@@ -73,7 +73,7 @@ interface LspProviderQuery extends LspQueryRequest {
 
 ## 结果
 
-这是一个闭合的可辨识联合：导航操作规范化为 `locations`，`hover` 规范化为内容或 `null`。消费方使用 `switch` 对 `kind` 做穷尽处理，因此新增分支会使编译失败，直到完成处理。`findReferences` 始终包含声明；提供方在内部强制保证这一点，因此调用方没有对应 flag。`locations` 变体携带 `resolvedWorkspaceRoot`，即提供方对请求中 `workspaceRoot` 的规范形式，也是其 `file:` URI 所相对的根目录；调用方在相对化显示路径时应使用它，而不是可能经过符号链接的请求根目录。
+这是一个闭合的可辨识联合：导航操作规范化为 `locations`，`hover` 规范化为内容或 `null`。消费方使用 `switch` 对 `kind` 做穷尽处理，因此新增分支会使编译失败，直到完成处理。`findReferences` 始终包含声明；提供方在内部强制保证这一点，因此调用方没有对应 flag。`locations` 变体携带 `resolvedWorkspaceUri`，即提供方的规范工作区 `file:` URI。调用方相对化位置 URI 时应使用这一坐标，而不是对可能经过符号链接的请求根目录应用宿主平台路径规则。
 
 ```ts type-equiv
 /** One resolved location: a document URI and the range within it. */
@@ -101,13 +101,13 @@ interface LspHover {
  * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
  * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
  *
- * The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the
- * request's `workspaceRoot`, and the root its `file:` location URIs are relative to. A caller that
- * relativizes display paths MUST use this, not the request's (possibly symlinked) `workspaceRoot`;
- * otherwise a symlinked workspace misclassifies in-workspace results as external.
+ * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
+ * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
+ * request's possibly symlinked process path with host-platform rules; the execution platform may
+ * differ from the caller's.
  */
 type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: LspHover | null }
 ```
 
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index 8584f64f48..318704b9fc 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -244,10 +244,9 @@ export class LspInstance {
     if (operation === 'hover') {
       return { kind: 'hover', hover: normalizeHover(payload) }
     }
-    // `spec.cwd` is the canonical workspace realpath (the provider canonicalizes before spawning),
-    // and every `file:` location URI is relative to it — so it is the root a caller must relativize
-    // display paths against, not the request's possibly-symlinked workspaceRoot.
-    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceRoot: this.spec.cwd }
+    // The filesystem provider owns URI syntax for the execution platform, which may differ from the
+    // harness host. Preserve that coordinate through rendering instead of reparsing `spec.cwd` there.
+    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceUri: this.spec.workspaceUri }
   }
 
   private answerServerRequest(method: string, params: unknown): Promise<unknown> {
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 3027cbbd29..811f15c9fa 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -117,17 +117,17 @@ describe('LspInstance server-request handling', () => {
 
   it('accepts a lifecycle client/registerCapability request', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'lifecycle', LSP_FAKE_DEF: 'null' })
-    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
   })
 
   it('rejects a workspace/applyEdit request but keeps serving', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'applyEdit', LSP_FAKE_DEF: 'null' })
-    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
   })
 
   it('rejects an unknown server request but keeps serving', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'unknown', LSP_FAKE_DEF: 'null' })
-    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
   })
 })
 
@@ -263,7 +263,7 @@ describe('LspInstance query and abort', () => {
     await expect(run(instance, 'goToDefinition')).resolves.toEqual({
       kind: 'locations',
       locations: [],
-      resolvedWorkspaceRoot: ws,
+      resolvedWorkspaceUri: pathToFileURL(ws).href,
     })
     expect(instance.dead).toBe(true)
   })
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index a7a006c06e..ce92e2c8fb 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -102,7 +102,7 @@ describe('lsp-local end to end over a fake server', () => {
     expect(result).toEqual<LspQueryResult>({
       kind: 'locations',
       locations: [{ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } }],
-      resolvedWorkspaceRoot: ws,
+      resolvedWorkspaceUri: pathToFileURL(ws).href,
     })
     await ctx.fiber.dispose()
   })
@@ -133,7 +133,7 @@ describe('lsp-local end to end over a fake server', () => {
 
   it('returns an empty locations result for a null definition', async () => {
     const ctx = await mount({ LSP_FAKE_DEF: 'null' })
-    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
     await ctx.fiber.dispose()
   })
 
@@ -173,7 +173,7 @@ describe('lsp-local end to end over a fake server', () => {
 
   it('accepts openClose options sync', async () => {
     const ctx = await mount({ LSP_FAKE_SYNC: JSON.stringify({ openClose: true, change: 2 }), LSP_FAKE_DEF: 'null' })
-    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
     await ctx.fiber.dispose()
   })
 
@@ -297,7 +297,7 @@ describe('lsp-local end to end over a fake server', () => {
     controller.abort(new Error('mid-read cancel'))
     await expect(pending).rejects.toThrow(/mid-read cancel/)
     // A subsequent live query still works, proving no half-created instance poisoned the pool.
-    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
     await ctx.fiber.dispose()
   })
 
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index 3faf906868..02649a8d39 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/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/lsp/lsp/README.md
-README.md: f96fc67ec8cb95f423eff9b312b7b591ec9d3008
-README.zh.md: 9757147de692684747d9965efda6329b3bbe2638
+README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
+README.zh.md: cc412333e63b9469319240d67269bf0192ad3858
diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md
index f96fc67ec8..5c1044be50 100644
--- a/packages/lsp/lsp/README.md
+++ b/packages/lsp/lsp/README.md
@@ -27,7 +27,7 @@ Providers register **capabilities**, not tools. `dsh-tool-lsp` is the only owner
 
 ## Vocabulary
 
-`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `findReferences` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations; resolvedWorkspaceRoot }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. `resolvedWorkspaceRoot` is the provider's canonical form of the request's `workspaceRoot` and the root its `file:` URIs are relative to; a caller relativizing display paths uses it, not the (possibly symlinked) request root. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes, including `LSP_DISPOSED` and `LSP_MALFORMED_RESPONSE`.
+`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `findReferences` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations; resolvedWorkspaceUri }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. `resolvedWorkspaceUri` is the provider's canonical workspace `file:` URI; callers relativize location URIs against it instead of applying host-platform path rules to the possibly symlinked request root. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes, including `LSP_DISPOSED` and `LSP_MALFORMED_RESPONSE`.
 
 ## Model Experience
 
diff --git a/packages/lsp/lsp/README.zh.md b/packages/lsp/lsp/README.zh.md
index 9757147de6..cc412333e6 100644
--- a/packages/lsp/lsp/README.zh.md
+++ b/packages/lsp/lsp/README.zh.md
@@ -8,7 +8,7 @@
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以带品牌类型的 id 和扩展名映射为键的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
+| `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
 | `@deepseek-ai/dsh-lsp-local` | 通用本地后端，注册已配置的 stdio 语言服务器提供方 |
 | `@deepseek-ai/dsh-tool-lsp` | 面向模型的 `lsp` 工具，基于 `ctx.lsp` |
 
@@ -18,16 +18,16 @@
 
 | 成员 | 语义 |
 |---|---|
-| `registerProvider(provider)` | 注册后端，以原子方式保留其带品牌类型的 `id` 与每个规范化文件扩展名。任何无效输入或冲突都不会发布内容，并抛出 `LspError`（`LSP_INVALID_PROVIDER`／`LSP_CONFLICT`）。返回释放所有保留项的 disposer。随调用 fiber 一同 dispose（资源释放）。 |
+| `registerProvider(provider)` | 注册后端，以原子方式保留其品牌化 `id` 与每个规范化文件扩展名。任何无效输入或冲突都不会发布内容，并抛出 `LspError`（`LSP_INVALID_PROVIDER`／`LSP_CONFLICT`）。返回释放所有保留项的 disposer。随调用 fiber 释放。 |
 | `query(request, signal?)` | 按文件最终扩展名选择提供方，从该提供方的映射派生 `languageId`，并运行一次查询。没有匹配项时抛出 `LspError` `LSP_UNAVAILABLE`。 |
 
-选择逐查询进行且与顺序无关：一个提供方独占一组扩展名，因此注册和 HMR（热模块替换）顺序绝不会改变路由。扩展名 key 规范化为小写且以点开头；`languageId` 只用于同步临时文档，绝不参与选择。第一版没有 glob、language-id 或显式路由 selector。
+选择逐查询进行且与顺序无关：一个提供方独占一组扩展名，因此注册和 HMR 顺序绝不会改变路由。扩展名 key 规范化为小写且以点开头；`languageId` 只用于同步临时文档，绝不参与选择。第一版没有 glob、language-id 或显式路由 selector。
 
-提供方注册的是**能力**，而非工具。`dsh-tool-lsp` 是面向模型名称、描述、提示词指引、schema 和呈现的唯一 owner。
+提供方注册的是**能力** 而非工具。`dsh-tool-lsp` 是面向模型名称、描述、提示词指引、schema 和呈现的唯一 owner。
 
 ## 词汇
 
-`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具负责从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceRoot }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceRoot` 是提供方对请求 `workspaceRoot` 的规范形式，也是其 `file:` URI 所相对的根；调用方把显示路径相对化时使用该值，而非可能含符号链接的请求根。完整契约见 `src/types.ts`；`src/index.ts` 给出 `LspError` 代码，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
+`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具拥有从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceUri }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceUri` 是提供方的规范工作区 `file:` URI；调用方相对化位置 URI 时以它为基准，而不是对可能含符号链接的请求根应用宿主平台路径规则。完整契约见 `src/types.ts`；`src/index.ts` 给出 `LspError` code，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
 
 ## 模型体验
 
@@ -39,6 +39,6 @@
 
 ## 已知限制与暂缓事项
 
-- **同一运行时内扩展名归属互斥**：两个提供方不能同时声明 `.ts`，即使语言 ID 不同；重叠会使注册失败。预期扩展是在注册之上增加部署配置的 selector；它可以放宽互斥保留，而无需把提供方选择加入模型输入（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
+- **同一运行时内扩展名归属互斥**：两个提供方不能同时声明 `.ts`，即使 language id 不同；重叠会使注册失败。预期扩展是在注册之上增加部署配置的 selector；它可以放宽互斥保留，而无需把提供方选择加入模型输入（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
 - **仅四种操作**：symbol 与 call hierarchy 暂缓（它们需要不同 schema）；diagnostics 需要独立的新鲜度／累积规则；修改操作（rename、code action、formatting）需要独立工具，并集成预览、权限和写入策略。
-- **没有观测接口**：可用性只能通过运行 `query()` 并按抛出的 `LspError` 代码进行路由来观测；没有提供方变更事件或能力状态查询。
+- **没有观测表层**：可用性只能通过运行 `query()` 并按抛出的 `LspError` code 路由来观测；没有提供方变更事件或能力状态查询。
diff --git a/packages/lsp/lsp/src/types.ts b/packages/lsp/lsp/src/types.ts
index d0c84f606d..d1bebe2a58 100644
--- a/packages/lsp/lsp/src/types.ts
+++ b/packages/lsp/lsp/src/types.ts
@@ -77,13 +77,13 @@ export interface LspHover {
  * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
  * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
  *
- * The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the
- * request's `workspaceRoot`, and the root its `file:` location URIs are relative to. A caller that
- * relativizes display paths MUST use this, not the request's (possibly symlinked) `workspaceRoot`;
- * otherwise a symlinked workspace misclassifies in-workspace results as external.
+ * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
+ * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
+ * request's possibly symlinked process path with host-platform rules; the execution platform may
+ * differ from the caller's.
  */
 export type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: LspHover | null }
 
 /**
diff --git a/packages/lsp/lsp/tests/lsp.spec.ts b/packages/lsp/lsp/tests/lsp.spec.ts
index 77ea9687c7..86c9b0ac53 100644
--- a/packages/lsp/lsp/tests/lsp.spec.ts
+++ b/packages/lsp/lsp/tests/lsp.spec.ts
@@ -13,7 +13,7 @@ import Lsp, {
 function makeProvider(
   id: string,
   extensionToLanguage: Record<string, string>,
-  result: LspQueryResult = { kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' },
+  result: LspQueryResult = { kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' },
 ): LspProvider & { seen: LspProviderQuery[]; seenSignals: (AbortSignal | undefined)[] } {
   const seen: LspProviderQuery[] = []
   const seenSignals: (AbortSignal | undefined)[] = []
@@ -63,7 +63,7 @@ describe('Lsp registration', () => {
     const provider = makeProvider('ts', { '.ts': 'typescript' })
     const dispose = lsp.registerProvider(provider)
 
-    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' })
     expect(provider.seen[0]).toMatchObject({ filePath: 'a.ts', languageId: 'typescript' })
 
     dispose()
@@ -148,7 +148,7 @@ describe('Lsp registration', () => {
     const py = makeProvider('py', { '.py': 'python' })
     lsp.registerProvider(ts)
     lsp.registerProvider(py)
-    await expect(lsp.query(query('a.py'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await expect(lsp.query(query('a.py'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' })
     await expect(lsp.query(query('a.ts', 'hover'))).resolves.toEqual(hover)
   })
 
@@ -172,7 +172,7 @@ describe('Lsp registration', () => {
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
       inner.lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' }))
     }, { inject: ['lsp'] }))
-    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' })
     await fiber.dispose()
     await expect(lsp.query(query('a.ts'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
   })
diff --git a/packages/lsp/tool-lsp/README.i18n.yaml b/packages/lsp/tool-lsp/README.i18n.yaml
index e2e7c7517f..85a33f73af 100644
--- a/packages/lsp/tool-lsp/README.i18n.yaml
+++ b/packages/lsp/tool-lsp/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/lsp/tool-lsp/README.md
-README.md: 9b4130015ddf7e1cad6fa9a0e131be86f3bd4bcc
-README.zh.md: a3f59fb6e39bb6c19cc2ef06d0bc256633e75386
+README.md: 1e89abf22e853735c094d17047b2c946af210905
+README.zh.md: 396b4d22ada8761b17c01d0c40e4bb4cfe80ca67
diff --git a/packages/lsp/tool-lsp/README.md b/packages/lsp/tool-lsp/README.md
index 9b4130015d..1e89abf22e 100644
--- a/packages/lsp/tool-lsp/README.md
+++ b/packages/lsp/tool-lsp/README.md
@@ -10,7 +10,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). In
 
 `lsp` accepts `operation` (`goToDefinition` | `findReferences` | `goToImplementation` | `hover`), `file_path`, `line`, and `character`. `line` and `character` are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based positions and converts rendered locations back. `findReferences` includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable stay outside model input.
 
-The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized seam union: `{ kind: "locations", locations, resolvedWorkspaceRoot }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering then projects stable, file-grouped `path:line:character` entries relativized against the result's `resolvedWorkspaceRoot` (the provider's canonical root), not the session cwd — so a symlinked cwd still renders in-workspace results as workspace-relative paths; a `file:` URI becomes a workspace-relative path (inside) or absolute path (outside), and any other URI stays verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
+The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized seam union: `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering projects stable, file-grouped `path:line:character` entries against the provider's canonical workspace URI rather than applying host-platform path rules to the session cwd. A `file:` URI becomes a workspace-relative path inside that URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs stay verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
 
 ## Configuration
 
diff --git a/packages/lsp/tool-lsp/README.zh.md b/packages/lsp/tool-lsp/README.zh.md
index a3f59fb6e3..396b4d22ad 100644
--- a/packages/lsp/tool-lsp/README.zh.md
+++ b/packages/lsp/tool-lsp/README.zh.md
@@ -8,13 +8,13 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 工具
 
-`lsp` 接受 `operation`（`goToDefinition` | `findReferences` | `goToImplementation` | `hover`）、`file_path`、`line` 和 `character`。`line` 与 `character` 是正的、从 1 开始的 UTF-16 光标坐标；工具将其转换为 seam 从零开始的位置，并把渲染位置转换回来。`findReferences` 包含声明，因此影响分析不会遗漏定义位置。提供方、语言 ID、工作区根目录、限制、超时、初始化和可执行文件均不进入模型输入。
+`lsp` 接受 `operation`（`goToDefinition` | `findReferences` | `goToImplementation` | `hover`）、`file_path`、`line` 和 `character`。`line` 与 `character` 是正的、从 1 开始的 UTF-16 光标坐标；工具将其转换为 seam 从零开始的位置，并把渲染位置转换回来。`findReferences` 包含声明，因此影响分析不会遗漏定义位置。提供方、language id、Workspace 根、限制、超时、初始化和可执行文件均不进入模型输入。
 
-该工具要求从会话 `header.cwd` 取得工作区根目录，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 seam 联合：`{ kind: "locations", locations, resolvedWorkspaceRoot }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。Native 渲染随后投影出稳定的、按文件分组的 `path:line:character` 条目，并相对于结果的 `resolvedWorkspaceRoot`（提供方的规范根目录）而非会话 cwd；因此，即使 cwd 包含符号链接，工作区内的结果仍渲染为相对路径。`file:` URI 位于工作区内时成为工作区相对路径，位于工作区外时成为绝对路径，其他 URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
+该工具要求从会话 `header.cwd` 取得 Workspace 根，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 seam 联合：`{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。原生渲染以提供方的规范工作区 URI 为基准，投影按文件稳定分组的 `path:line:character` 条目，而不对会话 cwd 应用宿主平台路径规则。`file:` URI 落在该工作区 URI 内时成为工作区相对路径，位于其外时成为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
 
 ## 配置
 
-| 配置键 | 默认值 | 含义 |
+| Key | 默认值 | 含义 |
 |---|---|---|
 | `maxLocations` | `100` | 出现省略标记前可渲染位置的最大数量。 |
 | `maxResultChars` | `16000` | 完整渲染结果的最大长度，包括截断元数据。 |
@@ -40,7 +40,7 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 #### KV Cache 影响
 
-只要插件作用域与指引文本不变，前缀就保持稳定；激活或 dispose（资源释放）可能使从该区段起的复用失效。
+只要插件 scope 与指引文本不变，前缀就保持稳定；激活或释放可能使从该区段起的复用失效。
 
 ### 工具 schema
 
@@ -54,13 +54,13 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 #### KV Cache 影响
 
-只要可见工具定义与顺序不变，前缀就保持稳定；注册生命周期或作用域限制可能使从第一个变化的 schema token 起的复用失效。
+只要可见工具定义与顺序不变，前缀就保持稳定；注册生命周期或 scope 限制可能使从第一个变化的 schema token 起的复用失效。
 
 ### 结果
 
 #### 模型看到的内容
 
-按文件分组的 `path:line:character` 位置行或规范化 hover 文本，先由 `maxLocations` 限制，再由 `maxResultChars` 限制；省略与截断标记计入完整字符上限。这些上限只影响 Native／模型呈现，不影响规范值。空结果使用不同的 `No results.`／`No hover information.` 行。
+按文件分组的 `path:line:character` 位置行或规范化 hover 文本，先由 `maxLocations` 限制，再由 `maxResultChars` 限制；省略与截断标记计入完整字符上限。这些上限只影响原生／模型呈现，不影响规范值。空结果使用不同的 `No results.`／`No hover information.` 行。
 
 #### Token 影响
 
@@ -74,7 +74,7 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 #### 模型看到的内容
 
-无。客户端渲染通用搜索卡片：`{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }`；从 args 派生的标题携带操作与从 1 开始的光标，编辑器跟随定位会聚焦所查询的行，标题则保留列号。
+无。客户端渲染通用搜索卡片：`{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }`；从 args 派生的标题携带操作与从 1 开始的光标，跟随焦点对准查询行，标题则保留列号。
 
 #### Token 影响
 
@@ -86,5 +86,5 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 ## 已知限制与暂缓事项
 
-- **UTF-16 光标坐标**：列坐标与协议精确一致，但模型难以在非 BMP 字符周围计数；不在符号上的位置可能返回空结果，因此提示词解释了该约定，但不会鼓励宽泛使用 LSP（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
+- **UTF-16 光标坐标**：列坐标与协议精确一致，但模型难以在非 BMP 字符周围计数；非 symbol 位置可能返回空结果，因此提示词解释了该约定，但不会鼓励宽泛使用 LSP（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
 - **不承诺跨服务器完整性**：受支持的服务器仍可能根据索引就绪情况返回空或部分结果；该工具不承诺跨语言或服务器的完整性。
diff --git a/packages/lsp/tool-lsp/src/index.ts b/packages/lsp/tool-lsp/src/index.ts
index e47dbc87db..688b48b369 100644
--- a/packages/lsp/tool-lsp/src/index.ts
+++ b/packages/lsp/tool-lsp/src/index.ts
@@ -138,7 +138,7 @@ export function apply(ctx: Context, config: Config): void {
                   },
                 },
               },
-              resolvedWorkspaceRoot: { type: 'string', required: true },
+              resolvedWorkspaceUri: { type: 'string', required: true },
             },
           },
           {
@@ -167,7 +167,7 @@ export function apply(ctx: Context, config: Config): void {
       render: (_args, value) => {
         switch (value.kind) {
           case 'locations':
-            return [{ type: 'text', text: formatLocations(value.locations, value.resolvedWorkspaceRoot, resolved.maxLocations, resolved.maxResultChars) }]
+            return [{ type: 'text', text: formatLocations(value.locations, value.resolvedWorkspaceUri, resolved.maxLocations, resolved.maxResultChars) }]
           case 'hover':
             return [{ type: 'text', text: formatHover(value.hover, resolved.maxResultChars) }]
           /* v8 ignore next -- exhaustive over the output schema's closed union; unreachable. */
@@ -200,7 +200,7 @@ export function apply(ctx: Context, config: Config): void {
                 end: { line: location.range.end.line, character: location.range.end.character },
               },
             })),
-            resolvedWorkspaceRoot: result.resolvedWorkspaceRoot,
+            resolvedWorkspaceUri: result.resolvedWorkspaceUri,
           }
         case 'hover':
           return {
diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 215dfb60e6..3f49d1edfd 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -6,8 +6,6 @@
  * @module @deepseek-ai/dsh-tool-lsp/render
  */
 
-import { fileURLToPath } from 'node:url'
-import { isAbsolute, relative, sep } from 'node:path'
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
 import type { LspHover, LspLocation, LspOperation, LspPosition } from '@deepseek-ai/dsh-lsp'
 
@@ -74,17 +72,17 @@ function oneBased(value: number, name: string): number {
 /**
  * Render a locations result grouped by file, converting each zero-based location back to a one-based
  * `path:line:character` entry. A `file:` URI inside the workspace becomes a workspace-relative path;
- * outside it, an absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and
+ * outside it, a URI-derived absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and
  * appends an omission marker when it truncates by count, then applies the complete result cap.
  * @param locations - the seam's locations (possibly empty).
- * @param workspaceRoot - the canonical workspace root for relativizing `file:` paths.
+ * @param workspaceUri - the provider's canonical workspace `file:` URI.
  * @param maxLocations - the cap before truncation.
  * @param maxResultChars - the complete rendered-text cap, including truncation metadata.
  * @returns the rendered text; a distinct no-result line when there are none.
  */
 export function formatLocations(
   locations: readonly LspLocation[],
-  workspaceRoot: string,
+  workspaceUri: string,
   maxLocations: number,
   maxResultChars: number,
 ): string {
@@ -93,7 +91,7 @@ export function formatLocations(
   const omitted = locations.length - shown.length
   const grouped = new Map<string, string[]>()
   for (const location of shown) {
-    const path = renderUri(location.uri, workspaceRoot)
+    const path = renderUri(location.uri, workspaceUri)
     const line = location.range.start.line + 1
     const character = location.range.start.character + 1
     const entries = grouped.get(path) ?? []
@@ -128,27 +126,63 @@ function boundResult(text: string, maxChars: number, label: string): string {
 }
 
 /**
- * Resolve a location URI to a display path. A `file:` URI accepted by Node becomes workspace-relative
- * (inside) or absolute (outside); any other URI is returned verbatim.
+ * Resolve a location URI without applying the harness host's path rules. A valid `file:` URI becomes
+ * workspace-relative when it is under the provider's canonical workspace URI, or a URI-derived
+ * absolute path otherwise; malformed and non-`file:` URIs remain verbatim.
  * @param uri - the target URI from the seam.
- * @param workspaceRoot - the canonical workspace root.
+ * @param workspaceUri - the provider's canonical workspace `file:` URI.
  * @returns the display path or the verbatim URI.
  */
-export function renderUri(uri: string, workspaceRoot: string): string {
+export function renderUri(uri: string, workspaceUri: string): string {
   if (!uri.startsWith('file:')) return uri
-  let absolute: string
+  let target: URL
+  let workspace: URL
   try {
-    absolute = fileURLToPath(uri)
+    target = new URL(uri)
+    workspace = new URL(workspaceUri)
   } catch {
-    // A malformed file: URI is not a path we can resolve; show it verbatim.
     return uri
   }
-  const rel = relative(workspaceRoot, absolute)
-  if (rel === '') return '.'
-  // A leading `..` SEGMENT (or an absolute rel) means outside the workspace; guard against a false
-  // positive on an in-workspace path whose first component merely starts with dots (e.g. `..gen/x`).
-  const outside = rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)
-  return outside ? absolute : rel.split(sep).join('/')
+  if (workspace.protocol !== 'file:') return uri
+  const targetSegments = decodeFileSegments(target)
+  const workspaceSegments = decodeFileSegments(workspace)
+  if (targetSegments === undefined || workspaceSegments === undefined) return uri
+  const sameAuthority = target.hostname === workspace.hostname
+  const windowsWorld = /^[A-Za-z]:$/.test(workspaceSegments[0] ?? '')
+  const inside = sameAuthority
+    && targetSegments.length >= workspaceSegments.length
+    && workspaceSegments.every((segment, index) => samePathSegment(segment, targetSegments[index] as string, windowsWorld))
+  if (inside) {
+    const relative = targetSegments.slice(workspaceSegments.length)
+    return relative.length === 0 ? '.' : relative.join('/')
+  }
+  return absoluteUriPath(target, targetSegments, workspaceSegments)
+}
+
+/** Decode URI path segments while rejecting encoded separators that would change path structure. */
+function decodeFileSegments(url: URL): string[] | undefined {
+  try {
+    const decoded = url.pathname.split('/').map(segment => decodeURIComponent(segment))
+    if (decoded.some(segment => /[/\\\0]/u.test(segment))) return undefined
+    while (decoded.at(-1) === '') decoded.pop()
+    decoded.shift()
+    return decoded
+  } catch {
+    return undefined
+  }
+}
+
+/** Windows execution-world path segments are case-insensitive even on a non-Windows harness host. */
+function samePathSegment(left: string, right: string, windowsWorld: boolean): boolean {
+  return windowsWorld ? left.toUpperCase() === right.toUpperCase() : left === right
+}
+
+/** Render an external file URL according to the execution-world style implied by its workspace URI. */
+function absoluteUriPath(target: URL, segments: readonly string[], workspaceSegments: readonly string[]): string {
+  if (target.hostname.length > 0) return `//${target.hostname}/${segments.join('/')}`
+  const windowsWorld = /^[A-Za-z]:$/.test(workspaceSegments[0] ?? '')
+  if (windowsWorld && /^[A-Za-z]:$/.test(segments[0] ?? '')) return segments.join('/')
+  return `/${segments.join('/')}`
 }
 
 /**
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index 1fd0eeba51..9f87d663fb 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -14,6 +14,7 @@ import {
 import type { LspLocation } from '@deepseek-ai/dsh-lsp'
 
 const WS = resolve('/home/u/proj')
+const WS_URI = pathToFileURL(WS).href
 
 function loc(uri: string, line: number, character = 0): LspLocation {
   return { uri, range: { start: { line, character }, end: { line, character: character + 1 } } }
@@ -48,64 +49,84 @@ describe('parseLspArgs', () => {
 describe('renderUri', () => {
   it('relativizes a file: URI inside the workspace with forward slashes', () => {
     const uri = pathToFileURL(join(WS, 'src', 'a.ts')).href
-    expect(renderUri(uri, WS)).toBe('src/a.ts')
+    expect(renderUri(uri, WS_URI)).toBe('src/a.ts')
   })
 
   it('returns an absolute path for a file: URI outside the workspace', () => {
     const outside = resolve(WS, '..', 'other', 'lib', 'b.ts')
     const uri = pathToFileURL(outside).href
-    expect(renderUri(uri, WS)).toBe(outside)
+    expect(renderUri(uri, WS_URI)).toBe(outside)
   })
 
   it('renders the workspace root itself as "."', () => {
-    expect(renderUri(pathToFileURL(WS).href, WS)).toBe('.')
+    expect(renderUri(WS_URI, WS_URI)).toBe('.')
   })
 
   it('keeps an in-workspace path whose first segment starts with dots relative', () => {
     // `..generated` is a real in-workspace dir, not a parent escape; only a `..` segment is external.
     const uri = pathToFileURL(join(WS, '..generated', 'a.ts')).href
-    expect(renderUri(uri, WS)).toBe('..generated/a.ts')
+    expect(renderUri(uri, WS_URI)).toBe('..generated/a.ts')
+  })
+
+  it('relativizes Windows execution-world URIs on a non-Windows host', () => {
+    expect(renderUri('file:///C:/WORKSPACE/src/a.ts', 'file:///c:/workspace')).toBe('src/a.ts')
+    expect(renderUri('file:///D:/lib/b.ts', 'file:///C:/workspace')).toBe('D:/lib/b.ts')
+  })
+
+  it('renders remote file authorities without host path conversion', () => {
+    expect(renderUri('file://server/share/workspace/a.ts', 'file://server/share/workspace')).toBe('a.ts')
+    expect(renderUri('file://other/share/b.ts', 'file://server/share/workspace')).toBe('//other/share/b.ts')
+    expect(renderUri('file:///a.ts', 'file://server/')).toBe('/a.ts')
+  })
+
+  it('keeps malformed or mismatched URI coordinates verbatim', () => {
+    expect(renderUri('file://[', WS_URI)).toBe('file://[')
+    expect(renderUri('file:///a.ts', 'https://example.com/workspace')).toBe('file:///a.ts')
+    expect(renderUri('file:///a.ts', 'file:///bad%ZZ')).toBe('file:///a.ts')
+    expect(renderUri('file:///bad%5Cpath', WS_URI)).toBe('file:///bad%5Cpath')
+    expect(renderUri('file:///short', 'file:///short/deeper')).toBe('/short')
+    expect(renderUri('file:///', 'file:///C:/workspace')).toBe('/')
   })
 
   it('keeps a non-file URI verbatim', () => {
-    expect(renderUri('untitled:Untitled-1', WS)).toBe('untitled:Untitled-1')
-    expect(renderUri('jdt://contents/Foo.class', WS)).toBe('jdt://contents/Foo.class')
+    expect(renderUri('untitled:Untitled-1', WS_URI)).toBe('untitled:Untitled-1')
+    expect(renderUri('jdt://contents/Foo.class', WS_URI)).toBe('jdt://contents/Foo.class')
   })
 
   it('keeps a malformed file: URI verbatim when it cannot be parsed to a path', () => {
     // An encoded path separator is invalid on every platform and must remain verbatim.
-    expect(renderUri('file:///bad%2Fpath', WS)).toBe('file:///bad%2Fpath')
+    expect(renderUri('file:///bad%2Fpath', WS_URI)).toBe('file:///bad%2Fpath')
   })
 })
 
 describe('formatLocations', () => {
   it('renders a no-result line for an empty list', () => {
-    expect(formatLocations([], WS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)).toBe('No results.')
+    expect(formatLocations([], WS_URI, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)).toBe('No results.')
   })
 
   it('renders one-based path:line:character grouped by file', () => {
     const a = pathToFileURL(join(WS, 'a.ts')).href
-    const text = formatLocations([loc(a, 0, 0), loc(a, 4, 2)], WS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)
+    const text = formatLocations([loc(a, 0, 0), loc(a, 4, 2)], WS_URI, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)
     expect(text).toBe('a.ts:1:1\na.ts:5:3')
   })
 
   it('caps at maxLocations and marks the omission', () => {
     const a = pathToFileURL(join(WS, 'a.ts')).href
     const many = Array.from({ length: 5 }, (_, i) => loc(a, i))
-    const text = formatLocations(many, WS, 2, DEFAULT_MAX_RESULT_CHARS)
+    const text = formatLocations(many, WS_URI, 2, DEFAULT_MAX_RESULT_CHARS)
     expect(text).toContain('a.ts:1:1')
     expect(text).toContain('3 more locations omitted (limit 2).')
   })
 
   it('uses the singular omission marker for exactly one extra', () => {
     const a = pathToFileURL(join(WS, 'a.ts')).href
-    const text = formatLocations([loc(a, 0), loc(a, 1)], WS, 1, DEFAULT_MAX_RESULT_CHARS)
+    const text = formatLocations([loc(a, 0), loc(a, 1)], WS_URI, 1, DEFAULT_MAX_RESULT_CHARS)
     expect(text).toContain('1 more location omitted (limit 1).')
   })
 
   it('caps the complete location text even when one URI is enormous', () => {
     const maxResultChars = 80
-    const text = formatLocations([loc(`custom:${'x'.repeat(1_000_000)}`, 0)], WS, 1, maxResultChars)
+    const text = formatLocations([loc(`custom:${'x'.repeat(1_000_000)}`, 0)], WS_URI, 1, maxResultChars)
     expect(text).toHaveLength(maxResultChars)
     expect(text).toContain('locations truncated')
   })
diff --git a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
index de7a5319ef..846bd702ea 100644
--- a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
+++ b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts
@@ -44,6 +44,7 @@ let seq = 0
 const testToolSignal = new AbortController().signal
 const workspaceRoot = resolve('/virtual/workspace')
 const resolvedWorkspaceRoot = resolve('/virtual/real-workspace')
+const resolvedWorkspaceUri = pathToFileURL(resolvedWorkspaceRoot).href
 const workspaceAlias = resolve('/virtual/workspace-alias')
 /** `cwd: null` means "no agent" (tests LSP_WORKSPACE_REQUIRED); a string is the session cwd. */
 function call(ctx: Context, args: unknown, cwd: string | null = workspaceRoot) {
@@ -59,7 +60,7 @@ function call(ctx: Context, args: unknown, cwd: string | null = workspaceRoot) {
 const okLocations: LspQueryResult = {
   kind: 'locations',
   locations: [{ uri: pathToFileURL(join(workspaceRoot, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
-  resolvedWorkspaceRoot: workspaceRoot,
+  resolvedWorkspaceUri: pathToFileURL(workspaceRoot).href,
 }
 
 describe('tool-lsp registration', () => {
@@ -138,7 +139,7 @@ describe('tool-lsp execution', () => {
     const { ctx } = await mount(stubProvider(() => ({
       kind: 'locations',
       locations,
-      resolvedWorkspaceRoot: cappedWorkspaceRoot,
+      resolvedWorkspaceUri: pathToFileURL(cappedWorkspaceRoot).href,
     })), { maxLocations: 1 })
     const result = await call(ctx, { operation: 'findReferences', file_path: 'a.ts', line: 1, character: 1 }, cappedWorkspaceRoot)
     expect(result.content[0]).toEqual({
@@ -147,17 +148,17 @@ describe('tool-lsp execution', () => {
     })
     expect(result).toMatchObject({
       isError: false,
-      value: { kind: 'locations', locations, resolvedWorkspaceRoot: cappedWorkspaceRoot },
+      value: { kind: 'locations', locations, resolvedWorkspaceUri: pathToFileURL(cappedWorkspaceRoot).href },
     })
   })
 
-  it('relativizes against the provider resolvedWorkspaceRoot, not the session cwd', async () => {
+  it('relativizes against the provider resolvedWorkspaceUri, not the session cwd', async () => {
     // A symlinked session cwd resolves to the real path that contains the provider's location URIs.
     // Relativizing against the alias would misclassify the location as external.
     const provider = stubProvider(() => ({
       kind: 'locations',
       locations: [{ uri: pathToFileURL(join(resolvedWorkspaceRoot, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
-      resolvedWorkspaceRoot,
+      resolvedWorkspaceUri,
     }))
     const { ctx } = await mount(provider)
     const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, workspaceAlias)

From 587fff9fe79170905352ee8639996f623e929158 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 04:43:54 +0800
Subject: [PATCH 303/516] fix(runtime): honor platform quiescence semantics

---
 packages/pty/pty-local/tests/local.spec.ts    | 20 ++++-
 .../subprocess/subprocess-local/src/spawn.ts  | 84 ++++++-------------
 .../subprocess-local/tests/local.spec.ts      |  8 +-
 3 files changed, 48 insertions(+), 64 deletions(-)

diff --git a/packages/pty/pty-local/tests/local.spec.ts b/packages/pty/pty-local/tests/local.spec.ts
index df05438864..1c0de1660a 100644
--- a/packages/pty/pty-local/tests/local.spec.ts
+++ b/packages/pty/pty-local/tests/local.spec.ts
@@ -98,6 +98,22 @@ function expectReadyForNextSend(waitReason: string): void {
   expect(['stdin_read', 'inferred_idle']).toContain(waitReason)
 }
 
+function processIsRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+  } catch (_missingProcess) {
+    return false
+  }
+  if (process.platform !== 'linux') return true
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    const state = stat.slice(stat.lastIndexOf(')') + 2).split(/\s+/, 1)[0]
+    return !/^[ZXx]$/.test(state ?? '')
+  } catch (_unreadableProcEntry) {
+    return false
+  }
+}
+
 describe('pty-local real shell', () => {
   it('persists cwd and environment across sends, scrubs secrets, and closes', async () => {
     const previous = process.env.DSH_TEST_SECRET
@@ -156,7 +172,7 @@ describe('pty-local real shell', () => {
     expect(() => process.kill(pid, 0)).toThrow()
   }, 10_000)
 
-  it('reaps a disowned same-session descendant after the shell exits naturally', async () => {
+  it('quiesces a disowned same-session descendant after the shell exits naturally', async () => {
     const { ctx, root, agent } = await harness('danger-full-access')
     const created = await ctx.pty.spawn(agent, { type: 'shell' })
     const pidFile = join(root, 'disowned.pid')
@@ -185,7 +201,7 @@ describe('pty-local real shell', () => {
       }
       expect(ctx.pty.list(agent)[0]?.status.kind).toBe('exited')
       await ctx.pty.kill(agent, created.sessionId)
-      expect(() => process.kill(childPid, 0)).toThrow()
+      expect(processIsRunning(childPid)).toBe(false)
     } finally {
       if (pid !== undefined) {
         try {
diff --git a/packages/subprocess/subprocess-local/src/spawn.ts b/packages/subprocess/subprocess-local/src/spawn.ts
index 462da41382..feb0ed0767 100644
--- a/packages/subprocess/subprocess-local/src/spawn.ts
+++ b/packages/subprocess/subprocess-local/src/spawn.ts
@@ -15,7 +15,6 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { setTimeout as sleepMs } from 'node:timers/promises'
 import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type {
   CollectedOutput,
   SubprocessCollect,
@@ -26,14 +25,23 @@ import type {
 } from '@deepseek-ai/dsh-subprocess'
 
 /**
- * Build a child environment: explicit caller entries merge after the scrubbed
- * parent base. A string deliberately restores or overrides an entry; an
- * explicit `undefined` tombstone removes an ordinary ambient entry.
- * @param extra - explicit caller entries and tombstones, merged after the scrub.
+ * Build a child environment: explicit caller entries override the scrubbed
+ * parent base using the target platform's environment-key semantics, so a
+ * deliberately supplied credential or current `DSH_*` fact wins over the
+ * scrub that dropped its ambient namesake.
+ * @param extra - explicit caller entries merged after the scrubbed parent.
  * @returns the environment to hand to `spawn` for the child process.
  */
-export function childEnv(extra?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv {
-  return { ...scrubbedParentEnv(), ...extra }
+export function childEnv(extra?: Readonly<Record<string, string>>): NodeJS.ProcessEnv {
+  const env = scrubbedParentEnv()
+  if (process.platform !== 'win32') return { ...env, ...extra }
+  let entries = Object.entries(env)
+  for (const [key, value] of Object.entries(extra ?? {})) {
+    const normalized = key.toUpperCase()
+    entries = entries.filter(([inherited]) => inherited.toUpperCase() !== normalized)
+    entries.push([key, value])
+  }
+  return Object.fromEntries(entries)
 }
 
 /** Injectable knobs so tests can exercise spill and platform behavior deterministically. */
@@ -299,12 +307,8 @@ function signalTree(
  * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
  * @param internals - test-only spill-directory, platform, and taskkill overrides.
  * @returns live subprocess handle.
- * @throws when `graceMs` cannot be represented by one Node timer.
  */
 export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInternals = {}): SubprocessHandle {
-  if (!Number.isFinite(spec.graceMs) || spec.graceMs <= 0 || spec.graceMs > MAX_TIMER_DELAY_MS) {
-    throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
-  }
   const spillDir = internals.spillDir ?? privateSpillDir()
   const platform = internals.platform ?? process.platform
   const taskkill = internals.taskkill ?? taskkillProcessTree
@@ -346,9 +350,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   const stdoutCollector = collectStream(outMode, child.stdout, 'stdout')
   const stderrCollector = collectStream(errMode, child.stderr, 'stderr')
 
-  let graceTimer: ReturnType<typeof setTimeout> | undefined
-  let treeExitObserved = false
-  let treeExitObservation: Promise<void> | undefined
+  let graceTimer: NodeJS.Timeout | undefined
   let settled = false
 
   // Failed spawns use pid -1 so signalling remains a no-op.
@@ -356,9 +358,6 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
 
   /** Whether the detached tree's root (or POSIX group) is still alive. */
   const treeAlive = (): boolean => {
-    /* v8 ignore next -- only a timer callback already queued when the observer settles can enter here;
-       the guard is the final defense against probing an id after its tree was confirmed absent. */
-    if (treeExitObserved) return false
     if (pid <= 0) return false
     if (platform === 'win32') {
       // Windows has no group-liveness probe; the direct child's exit is the
@@ -381,40 +380,19 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
     }
   }
 
-  /**
-   * Start or reuse the handle's single whole-tree exit observer. The first
-   * confirmed absence is a permanent no-more-signals boundary: it cancels a
-   * pending escalation before this process-group id can be reused.
-   */
-  const observeTreeExit = (): Promise<void> => {
-    treeExitObservation ??= (async () => {
-      while (treeAlive()) await sleepTick()
-      treeExitObserved = true
-      if (graceTimer !== undefined) clearTimeout(graceTimer)
-      graceTimer = undefined
-    })()
-    return treeExitObservation
-  }
-
   // The escalation's tier primitive (not on the handle — terminate() is the
   // only consumer-facing termination verb). Guards on TREE liveness, not
   // outcome settlement: a TERM-trapping helper can outlive the settled direct
   // child and must stay signalable, while a fully-dead tree (possible pid
   // reuse) must not be re-signalled by a later tier.
   const kill = (sig: NodeJS.Signals): void => {
-    /* v8 ignore next -- the shared exit observer cancels the ordinary dead-tree timer;
-       this remains the timer/death race guard and cannot be staged deterministically. */
     if (!treeAlive()) return
     signalTree(platform, pid, sig, child, taskkill)
   }
 
   const terminate = (): void => {
-    if (treeExitObserved || graceTimer !== undefined) return
-    // Observe from the first termination tier onward, even when inherited
-    // pipes delay `done` and no consumer has begun its own teardown wait.
-    void observeTreeExit()
-    // oxlint-disable-next-line typescript/no-unnecessary-condition -- observer can record absence before its first await.
-    if (treeExitObserved) return
+    if (graceTimer !== undefined) return // escalation already in flight
+    if (!treeAlive()) return
     kill('SIGTERM')
     // The escalation must survive direct-child settlement — the leader dying
     // does not mean the tree died — so settle does not clear this timer, and
@@ -436,7 +414,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   }
 
   const done = new Promise<SubprocessOutcome>((resolve, reject) => {
-    let pipeDrainTimer: ReturnType<typeof setTimeout> | undefined
+    let pipeDrainTimer: NodeJS.Timeout | undefined
     const settle = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
       if (settled) return
       settled = true
@@ -459,9 +437,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
       // A surviving descendant that inherited a pipe must not hold the
       // outcome open indefinitely: after exit, the same bounded grace that
       // governs kills also bounds the close wait.
-      pipeDrainTimer = setTimeout(() => {
-        settle(exitCode, signal)
-      }, spec.graceMs)
+      pipeDrainTimer = setTimeout(() => { settle(exitCode, signal) }, spec.graceMs)
     })
     child.on('close', settle)
     function cleanup(): void {
@@ -473,23 +449,11 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   })
 
   const waitForExit = async (signal?: AbortSignal): Promise<boolean> => {
-    const observed = observeTreeExit()
-    if (treeExitObserved) return true
-    if (signal?.aborted) return false
-    if (signal === undefined) {
-      await observed
-      return true
-    }
-    const aborted = Promise.withResolvers<boolean>()
-    const onAbort = (): void => { aborted.resolve(false) }
-    signal.addEventListener('abort', onAbort, { once: true })
-    /* v8 ignore next -- closes the event-loop race between the preceding aborted check and listener registration. */
-    if (signal.aborted) onAbort()
-    try {
-      return await Promise.race([observed.then(() => true), aborted.promise])
-    } finally {
-      signal.removeEventListener('abort', onAbort)
+    while (treeAlive()) {
+      if (signal?.aborted) return false
+      await sleepTick()
     }
+    return true
   }
 
   return {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 4662283aad..b2ebfcfed0 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -5,6 +5,7 @@ import { basename, delimiter, dirname, relative } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import type { SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { childEnv } from '../src/spawn.ts'
 
 function spec(command: string, overrides: Partial<SubprocessSpawnSpec> = {}): SubprocessSpawnSpec {
   return {
@@ -62,8 +63,11 @@ describe('LocalSubprocessService', () => {
     }).executableCandidates.bind(service)
     const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
     try {
-      expect(candidates('tool', { Path: `${delimiter}/bin`, PathExt: '.EXE;.CMD' }))
-        .toEqual(['/bin/tool.EXE', '/bin/tool.CMD'])
+      expect(Object.keys(childEnv()).filter(key => key.toUpperCase() === 'PATH')).toHaveLength(1)
+      const explicit = childEnv({ Path: `${delimiter}/bin`, PathExt: '.EXE;.CMD' })
+      expect(Object.keys(explicit).filter(key => key.toUpperCase() === 'PATH')).toEqual(['Path'])
+      expect(Object.keys(explicit).filter(key => key.toUpperCase() === 'PATHEXT')).toEqual(['PathExt'])
+      expect(candidates('tool', explicit)).toEqual(['/bin/tool.EXE', '/bin/tool.CMD'])
       expect(candidates('tool', { Path: '/ambient', PATH: '/explicit', PATHEXT: '.EXE' }))
         .toEqual(['/explicit/tool.EXE'])
       expect(candidates('tool.exe', {})).toEqual([])

From f5f40c740377d37a7da1bb1e0c8143b9d3201ca7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 05:20:40 +0800
Subject: [PATCH 304/516] fix(pty): discard pre-write readiness evidence

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +--
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +--
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 13 ++++++---
 packages/pty/pty-local/tests/session.spec.ts  | 27 +++++++++++++++++++
 8 files changed, 44 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 1033fffcc6..30e672416a 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 6f75778398e8f204c85b64fe096838a3b62d398e
-2026-07-28-portable-execution-world-consumers.zh.md: 22edc591f7716a92fd2a68d74c84168189743fbd
+2026-07-28-portable-execution-world-consumers.md: ccb7a13a9677c106976efbe95629d0d2c027b982
+2026-07-28-portable-execution-world-consumers.zh.md: 0a7b840049a826a47f4dc0476e5991bfd0578970
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 6f75778398..ccb7a13a96 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. A timed-out asynchronous write, or a cancellation whose foreground signal fails during that write, retains the send reservation until the provider settles it; completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. A timed-out asynchronous write, or a cancellation whose foreground signal fails during that write, retains the send reservation until the provider settles it; completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 22edc591f7..0a7b840049 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。异步写入超时，或在该写入期间取消时前台信号发送失败，都会保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。异步写入超时，或在该写入期间取消时前台信号发送失败，都会保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 05e9b904f9..4c153eff47 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: 7d0cd2c26c6c58a64ae9d5fe5598c8aa6ff62915
-README.zh.md: 0b8216a9f599c224bd2888eb428213c9d725a338
+README.md: 74dfd7f59d45649f6daf0b42408285d9ede830a7
+README.zh.md: 2c7780f7e7db896c959e017dc39299e0e16f187d
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 7d0cd2c26c..74dfd7f59d 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,7 +8,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
 Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the session's send slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 0b8216a9f5..2c7780f7e7 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,7 +8,7 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
 取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 03809aec9f..d780719c54 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -227,10 +227,7 @@ export class LocalPtySession implements PtyBackendSession {
       () => { this.interrupt(operation) },
     )
     this.active = operation
-    this.lastOutputAt = Date.now()
-    this.promptSeen = false
-    this.promptTextSeen = false
-    this.promptTail = ''
+    this.resetReadinessEvidence()
 
     if (request.signal !== undefined) {
       const onAbort = (): void => { operation.cancel() }
@@ -251,6 +248,7 @@ export class LocalPtySession implements PtyBackendSession {
       operation.setInitialForeground(foreground)
       const input = `${request.text}${request.submit ? '\r' : ''}`
       if (input.length > 0 && !operation.cancelRequested) {
+        this.resetReadinessEvidence()
         this.writing = operation
         try {
           await this.terminal.write(Buffer.from(input, 'utf8'))
@@ -276,6 +274,13 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
+  private resetReadinessEvidence(): void {
+    this.lastOutputAt = Date.now()
+    this.promptSeen = false
+    this.promptTextSeen = false
+    this.promptTail = ''
+  }
+
   read(request: PtyReadRequest): PtyReadResult {
     const snapshot = this.scrollback.snapshot()
     const lines = snapshot.text.split('\n')
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 5f0065d0ee..40c60c570d 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -168,6 +168,29 @@ describe('LocalPtySession readiness and output', () => {
     expect((await operation.done).waitReason).toBe('stdin_read')
   })
 
+  it('discards prompt readiness observed during asynchronous pre-write inspection', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await inspection.promise
+    const operation = session.startSend({ text: 'long-running-command', submit: true })
+    let settled = false
+    void operation.done.then(() => { settled = true })
+
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    inspection.resolve({ processGroupId: 456, inputWaiting: true })
+    await vi.advanceTimersByTimeAsync(20)
+    expect(terminal.writes).toEqual(['long-running-command\r'])
+    expect(settled).toBe(false)
+
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect((await operation.done).waitReason).toBe('stdin_read')
+  })
+
   it('captures prompt MOTD, writes submit explicitly, and settles exact stdin waits', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -524,6 +547,8 @@ describe('LocalPtySession readiness and output', () => {
     const operation = session.startSend({ text: 'run', submit: true })
     let settled = false
     void operation.done.then(() => { settled = true })
+    await Promise.resolve()
+    await Promise.resolve()
     inspector.pgid = 789
     terminal.emitData('\x1b]133;D;0\x07dsh> ')
     await vi.advanceTimersByTimeAsync(50)
@@ -545,6 +570,8 @@ describe('LocalPtySession readiness and output', () => {
     const operation = session.startSend({ text: 'run', submit: true })
     let settled = false
     void operation.done.then(() => { settled = true })
+    await Promise.resolve()
+    await Promise.resolve()
     inspector.pgid = 789
     terminal.emitData('\x1b]133;D;0\x07dsh> ')
     // One poll past the silence bound would already have settled inferred_idle.

From ea75333c92e815a633664323dcd41565c83c4565 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 05:32:54 +0800
Subject: [PATCH 305/516] fix(lsp): compare UNC paths case-insensitively

---
 packages/lsp/tool-lsp/src/render.ts        | 7 ++++++-
 packages/lsp/tool-lsp/tests/render.spec.ts | 2 ++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 3f49d1edfd..4613312c87 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -148,7 +148,7 @@ export function renderUri(uri: string, workspaceUri: string): string {
   const workspaceSegments = decodeFileSegments(workspace)
   if (targetSegments === undefined || workspaceSegments === undefined) return uri
   const sameAuthority = target.hostname === workspace.hostname
-  const windowsWorld = /^[A-Za-z]:$/.test(workspaceSegments[0] ?? '')
+  const windowsWorld = isWindowsFileWorld(workspace, workspaceSegments)
   const inside = sameAuthority
     && targetSegments.length >= workspaceSegments.length
     && workspaceSegments.every((segment, index) => samePathSegment(segment, targetSegments[index] as string, windowsWorld))
@@ -159,6 +159,11 @@ export function renderUri(uri: string, workspaceUri: string): string {
   return absoluteUriPath(target, targetSegments, workspaceSegments)
 }
 
+/** Whether a canonical file URI names a drive path or UNC path in a Windows execution world. */
+function isWindowsFileWorld(url: URL, segments: readonly string[]): boolean {
+  return url.hostname.length > 0 || /^[A-Za-z]:$/.test(segments[0] ?? '')
+}
+
 /** Decode URI path segments while rejecting encoded separators that would change path structure. */
 function decodeFileSegments(url: URL): string[] | undefined {
   try {
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index 9f87d663fb..d76600ea6f 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -75,8 +75,10 @@ describe('renderUri', () => {
 
   it('renders remote file authorities without host path conversion', () => {
     expect(renderUri('file://server/share/workspace/a.ts', 'file://server/share/workspace')).toBe('a.ts')
+    expect(renderUri('file://SERVER/share/workspace/src/A.ts', 'file://server/Share/Workspace')).toBe('src/A.ts')
     expect(renderUri('file://other/share/b.ts', 'file://server/share/workspace')).toBe('//other/share/b.ts')
     expect(renderUri('file:///a.ts', 'file://server/')).toBe('/a.ts')
+    expect(renderUri('file:///a.ts', 'file:///')).toBe('a.ts')
   })
 
   it('keeps malformed or mismatched URI coordinates verbatim', () => {

From d29c73ddd6cbd4d5f4e8feab980f06961f5414f8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 06:04:36 +0800
Subject: [PATCH 306/516] fix(subprocess): treat zombie-only groups as
 quiescent

---
 .../subprocess-local/src/process-inspector.ts | 29 +++++++++++++++++++
 .../subprocess/subprocess-local/src/spawn.ts  |  9 ++++++
 .../tests/process-inspector.spec.ts           | 21 +++++++++++++-
 .../subprocess-local/tests/spawn.spec.ts      | 18 ++++++++++++
 4 files changed, 76 insertions(+), 1 deletion(-)

diff --git a/packages/subprocess/subprocess-local/src/process-inspector.ts b/packages/subprocess/subprocess-local/src/process-inspector.ts
index 48b01e18e3..f31de010de 100644
--- a/packages/subprocess/subprocess-local/src/process-inspector.ts
+++ b/packages/subprocess/subprocess-local/src/process-inspector.ts
@@ -87,6 +87,35 @@ function readLinuxStat(internals: ProcessInspectorInternals, pid: number): ProcS
   }
 }
 
+/**
+ * Report whether a Linux process group has an executing member. `false`
+ * means the group contains only zombie/dead entries; `undefined` means the
+ * process table could not prove either outcome.
+ * @param processGroupId - POSIX process-group id to inspect.
+ * @param internals - injectable process-table operations.
+ * @returns Live-member presence, or `undefined` when unavailable/absent.
+ */
+export function linuxProcessGroupHasLiveMembers(
+  processGroupId: number,
+  internals: ProcessInspectorInternals = DEFAULT_INTERNALS,
+): boolean | undefined {
+  let entries: string[]
+  try {
+    entries = internals.readDir('/proc')
+  } catch (_unreadableProcDirectory) {
+    return undefined
+  }
+  let matched = false
+  for (const entry of entries) {
+    if (!/^\d+$/.test(entry)) continue
+    const stat = readLinuxStat(internals, Number(entry))
+    if (stat?.pgrp !== processGroupId) continue
+    matched = true
+    if (!/^[ZXx]$/.test(stat.state)) return true
+  }
+  return matched ? false : undefined
+}
+
 function numericEntries(internals: ProcessInspectorInternals, path: string): number[] {
   try {
     return internals.readDir(path).filter(entry => /^\d+$/.test(entry)).map(Number)
diff --git a/packages/subprocess/subprocess-local/src/spawn.ts b/packages/subprocess/subprocess-local/src/spawn.ts
index feb0ed0767..9fa70250dc 100644
--- a/packages/subprocess/subprocess-local/src/spawn.ts
+++ b/packages/subprocess/subprocess-local/src/spawn.ts
@@ -23,6 +23,7 @@ import type {
   SubprocessOutputMode,
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
+import { linuxProcessGroupHasLiveMembers } from './process-inspector.ts'
 
 /**
  * Build a child environment: explicit caller entries override the scrubbed
@@ -52,6 +53,8 @@ export interface SpawnInternals {
   taskkill?: (pid: number) => void
   /** Host platform override for signalling decisions. */
   platform?: NodeJS.Platform
+  /** Linux process-group member probe (defaults to `/proc` inspection). */
+  linuxProcessGroupHasLiveMembers?: (processGroupId: number) => boolean | undefined
 }
 
 /**
@@ -312,6 +315,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   const spillDir = internals.spillDir ?? privateSpillDir()
   const platform = internals.platform ?? process.platform
   const taskkill = internals.taskkill ?? taskkillProcessTree
+  const linuxGroupHasLiveMembers = internals.linuxProcessGroupHasLiveMembers ?? linuxProcessGroupHasLiveMembers
 
   if (spec.signal?.aborted) {
     throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`)
@@ -366,6 +370,11 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
     }
     try {
       process.kill(-pid, 0)
+      // A group containing only unreaped zombies still answers kill(0), but
+      // it can execute no work and cannot be signalled into quiescence. Only
+      // inspect after direct-child settlement so live-process polls remain a
+      // syscall rather than repeated process-table scans.
+      if (settled && platform === 'linux' && linuxGroupHasLiveMembers(pid) === false) return false
       return true
     } catch (error) {
       const code = (error as NodeJS.ErrnoException).code
diff --git a/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
index bcc3ddb091..c90a7b3490 100644
--- a/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/process-inspector.spec.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest'
-import { createProcessInspector, parseProcStat } from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
+import {
+  createProcessInspector,
+  linuxProcessGroupHasLiveMembers,
+  parseProcStat,
+} from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
 import type { ProcessInspectorInternals } from '@deepseek-ai/dsh-subprocess-local/src/process-inspector.ts'
 
 function stat(pid: number, pgrp: number, session: number, tpgid: number, started: string, parentPid = 1, state = 'S'): string {
@@ -63,6 +67,21 @@ function fakeInternals() {
 }
 
 describe('Linux process inspector', () => {
+  it('treats zombie-only process groups as quiescent and fails closed when unobservable', () => {
+    const fake = fakeInternals()
+    expect(linuxProcessGroupHasLiveMembers(77, fake.internals)).toBeUndefined()
+
+    fake.dirs.set('/proc', ['self', '10', '11', '12'])
+    fake.files.set('/proc/10/stat', stat(10, 77, 10, -1, '500', 1, 'Z'))
+    fake.files.set('/proc/11/stat', stat(11, 77, 10, -1, '501', 1, 'X'))
+    fake.files.set('/proc/12/stat', stat(12, 88, 12, -1, '502'))
+    expect(linuxProcessGroupHasLiveMembers(77, fake.internals)).toBe(false)
+    expect(linuxProcessGroupHasLiveMembers(99, fake.internals)).toBeUndefined()
+
+    fake.files.set('/proc/11/stat', stat(11, 77, 10, -1, '501'))
+    expect(linuxProcessGroupHasLiveMembers(77, fake.internals)).toBe(true)
+  })
+
   it('parses stat safely, captures only the rooted process tree, and signals identities', () => {
     expect(parseProcStat('bad')).toBeUndefined()
     expect(parseProcStat('1 () ')).toBeUndefined()
diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index 08b6b1dbf8..7d92447794 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -268,6 +268,24 @@ describe('spawnSubprocess', () => {
     expect(result.signal).toBe('SIGTERM')
   })
 
+  it('does not wait for a Linux group that has only zombie members', async () => {
+    const pidFile = join(spillDir, `zombie-group-${Date.now()}.pid`)
+    let hasLiveMembers = false
+    const running = spawnSubprocess(spec(`sleep 60 & echo $! > ${pidFile}; echo leader-done`, { graceMs: 100 }), {
+      platform: 'linux',
+      linuxProcessGroupHasLiveMembers: () => hasLiveMembers,
+    })
+    const descendant = await waitForPidFile(pidFile)
+    try {
+      await running.done
+      await expect(running.waitForExit()).resolves.toBe(true)
+    } finally {
+      hasLiveMembers = true
+      running.terminate()
+      await waitGone(descendant)
+    }
+  })
+
   it('bounds inherited-pipe draining after the shell exits', async () => {
     const pidFile = join(spillDir, `pipe-holder-${Date.now()}.pid`)
     const started = Date.now()

From 3572c65d57214cd66819239616b5238e3482bb13 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 06:04:49 +0800
Subject: [PATCH 307/516] fix(pty): join asynchronous terminal operations

---
 packages/pty/pty-local/src/session.ts        | 19 ++++++--
 packages/pty/pty-local/tests/session.spec.ts | 47 ++++++++++++++++++++
 2 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index d780719c54..0fb9f4ab0b 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -165,6 +165,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeTimer: NodeJS.Timeout | undefined
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
+  private readonly terminalOperations = new Set<Promise<void>>()
   private writing: LocalSendOperation | undefined
   private pollingReady: LocalSendOperation | undefined
   private polling = false
@@ -237,10 +238,18 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeDeadlineTimer = setTimeout(() => {
       if (this.active === operation) this.settleActive('timeout', this.writing === operation)
     }, this.config.timeoutMs)
-    void this.beginSend(operation, request)
+    this.ownTerminalOperation(this.beginSend(operation, request))
     return operation
   }
 
+  /** Retain one contained provider operation until its asynchronous work finishes. */
+  private ownTerminalOperation(operation: Promise<void>): void {
+    const tracked = operation.finally(() => { this.terminalOperations.delete(tracked) })
+    this.terminalOperations.add(tracked)
+    // beginSend(), pollReadiness(), and interrupt() contain their own boundary errors.
+    void tracked
+  }
+
   private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
     try {
       const foreground = await this.terminal.inspectForeground()
@@ -398,7 +407,7 @@ export class LocalPtySession implements PtyBackendSession {
     if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = setTimeout(() => {
       this.activeTimer = undefined
-      void this.pollReadiness(operation)
+      this.ownTerminalOperation(this.pollReadiness(operation))
     }, delayMs)
   }
 
@@ -467,6 +476,7 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeTimer = undefined
     if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
     this.activeDeadlineTimer = undefined
+    this.pollingReady = undefined
   }
 
   private clearActive(): void {
@@ -493,9 +503,9 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    void this.terminal.signalForeground('SIGINT').catch((error: unknown) => {
+    this.ownTerminalOperation(this.terminal.signalForeground('SIGINT').then(() => {}, (error: unknown) => {
       if (this.active === operation) this.failActive(error, this.writing === operation)
-    })
+    }))
   }
 
   private async closeOnce(reason: string): Promise<void> {
@@ -508,6 +518,7 @@ export class LocalPtySession implements PtyBackendSession {
     if (!quiescent) {
       throw new Error(`PTY cleanup failed (${reason}); terminal session did not reach quiescence`)
     }
+    await Promise.all(this.terminalOperations)
     // Whole-session cleanup can fail before the top-level process exits. Wait
     // for it first so that failure is reported instead of blocking forever on
     // `done`; successful quiescence guarantees `done` can now settle status and
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 40c60c570d..c5fc354106 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -907,4 +907,51 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     await closing
   })
 
+  it('does not finish close while a pre-write terminal operation is pending', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await inspection.promise
+    const operation = session.startSend({ text: 'must not run', submit: true })
+    const closing = session.close('pending inspection')
+    let closed = false
+    void closing.then(() => { closed = true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(closed).toBe(false)
+
+    inspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await closing
+    expect(closed).toBe(true)
+    expect(terminal.writes).toEqual([])
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
+  it('does not finish close while a terminal write is pending', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+
+    const write = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await write.promise }
+    const operation = session.startSend({ text: 'pending write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    const closing = session.close('pending write')
+    let closed = false
+    void closing.then(() => { closed = true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(closed).toBe(false)
+
+    write.resolve(undefined)
+    await closing
+    expect(closed).toBe(true)
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
 })

From f2a3cc450e988bdb36083f57f2fb0303b96b7e89 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 06:04:59 +0800
Subject: [PATCH 308/516] fix(lsp): retain drive syntax in UNC worlds

---
 packages/lsp/tool-lsp/src/render.ts        | 5 ++---
 packages/lsp/tool-lsp/tests/render.spec.ts | 1 +
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 4613312c87..1e73e7ec6a 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -156,7 +156,7 @@ export function renderUri(uri: string, workspaceUri: string): string {
     const relative = targetSegments.slice(workspaceSegments.length)
     return relative.length === 0 ? '.' : relative.join('/')
   }
-  return absoluteUriPath(target, targetSegments, workspaceSegments)
+  return absoluteUriPath(target, targetSegments, windowsWorld)
 }
 
 /** Whether a canonical file URI names a drive path or UNC path in a Windows execution world. */
@@ -183,9 +183,8 @@ function samePathSegment(left: string, right: string, windowsWorld: boolean): bo
 }
 
 /** Render an external file URL according to the execution-world style implied by its workspace URI. */
-function absoluteUriPath(target: URL, segments: readonly string[], workspaceSegments: readonly string[]): string {
+function absoluteUriPath(target: URL, segments: readonly string[], windowsWorld: boolean): string {
   if (target.hostname.length > 0) return `//${target.hostname}/${segments.join('/')}`
-  const windowsWorld = /^[A-Za-z]:$/.test(workspaceSegments[0] ?? '')
   if (windowsWorld && /^[A-Za-z]:$/.test(segments[0] ?? '')) return segments.join('/')
   return `/${segments.join('/')}`
 }
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index d76600ea6f..953f7ef4c1 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -77,6 +77,7 @@ describe('renderUri', () => {
     expect(renderUri('file://server/share/workspace/a.ts', 'file://server/share/workspace')).toBe('a.ts')
     expect(renderUri('file://SERVER/share/workspace/src/A.ts', 'file://server/Share/Workspace')).toBe('src/A.ts')
     expect(renderUri('file://other/share/b.ts', 'file://server/share/workspace')).toBe('//other/share/b.ts')
+    expect(renderUri('file:///D:/lib/a.ts', 'file://server/share/workspace')).toBe('D:/lib/a.ts')
     expect(renderUri('file:///a.ts', 'file://server/')).toBe('/a.ts')
     expect(renderUri('file:///a.ts', 'file:///')).toBe('a.ts')
   })

From 4d96ff40affe56f7301930cb45c9ee990bfe567c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 06:23:30 +0800
Subject: [PATCH 309/516] docs(lsp): align canonical output field

---
 .../2026-07-20-canonical-tool-output-contract.i18n.yaml       | 4 ++--
 .../architecture/2026-07-20-canonical-tool-output-contract.md | 2 +-
 .../2026-07-20-canonical-tool-output-contract.zh.md           | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
index f8ce3ee5f5..b8db543510 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.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 .agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
-2026-07-20-canonical-tool-output-contract.md: b2de9480d2659153dfb8a76ee07438d12e5b07c3
-2026-07-20-canonical-tool-output-contract.zh.md: 1852ae849aec27ef3af28895e902d840af5de14d
+2026-07-20-canonical-tool-output-contract.md: 2429e1c141ad8c8ee932c6d654a6ba74bc4f7618
+2026-07-20-canonical-tool-output-contract.zh.md: fd1e55eab38e5929a2dc104073b49f9de7a493e2
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
index b2de9480d2..2429e1c141 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
@@ -46,7 +46,7 @@ The first-party tools preserve their existing Native text while returning domain
 | `glob` | `{ paths: string[] }` |
 | `grep` | `{ matches: [{ path, lineNumber, line }] }` |
 | `web_search` / `web_fetch` | The normalized `WebSearchResult` / `WebFetchResult` |
-| `lsp` | `{ kind: "locations", locations, resolvedWorkspaceRoot }` or `{ kind: "hover", hover }` |
+| `lsp` | `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }` |
 | `bash` | `{ kind: "background", taskId }` or `{ kind: "foreground" } & BashRunResult` |
 | `terminal_open` / `terminal_list` / `terminal_send` / `terminal_read` / `terminal_signal` / `terminal_close` | Public session snapshots, bounded read/send DTOs, signal/close outcomes, or a background task handle |
 | `task_output` / `task_list` / `task_kill` | Public task snapshots without owner or notification bookkeeping |
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
index 1852ae849a..26653ea769 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
@@ -46,7 +46,7 @@ type ToolExecutionResult =
 | `glob` | `{ paths: string[] }` |
 | `grep` | `{ matches: [{ path, lineNumber, line }] }` |
 | `web_search` ／ `web_fetch` | 归一化后的 `WebSearchResult` ／ `WebFetchResult` |
-| `lsp` | `{ kind: "locations", locations, resolvedWorkspaceRoot }` 或 `{ kind: "hover", hover }` |
+| `lsp` | `{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }` |
 | `bash` | `{ kind: "background", taskId }` 或 `{ kind: "foreground" } & BashRunResult` |
 | `terminal_open` ／ `terminal_list` ／ `terminal_send` ／ `terminal_read` ／ `terminal_signal` ／ `terminal_close` | 公开会话快照、有界的读取／发送 DTO、信号／关闭操作结果，或后台任务句柄 |
 | `task_output` ／ `task_list` ／ `task_kill` | 不含所有者或通知管理信息的公开任务快照 |

From 6e5d711099a1db4f14bf897a9416c705d9fd2d4f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 07:59:55 +0800
Subject: [PATCH 310/516] fix(lsp): cancel executable setup on disposal

---
 packages/lsp/lsp-local/src/index.ts           | 49 ++++++++++++++-----
 packages/lsp/lsp-local/tests/provider.spec.ts | 37 +++++++++++++-
 2 files changed, 72 insertions(+), 14 deletions(-)

diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index d12e8986fc..0d511588bd 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -117,21 +117,44 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   const entries = Object.entries(config.servers)
   if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server')
 
+  const setupAbort = new AbortController()
+  const stopSetupCancellation = ctx.on('internal/plugin', (fiber) => {
+    // An async plugin callback must observe its own disposal before Cordis can
+    // run effect cleanup, because unload otherwise waits for this callback.
+    if (fiber === ctx.fiber && fiber.uid === null) {
+      setupAbort.abort(new Error('lsp-local setup disposed'))
+    }
+  })
+
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
-  const providers = await Promise.all(entries.map(async ([providerId, rawConfig]) => {
-    if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
-    const resolved = rawConfig as ResolvedServerConfig
-    validateServerConfig(providerId, resolved)
-    const executable = await ctx.subprocess.resolveExecutable(resolved.command, resolved.env)
-    return new LocalLspProvider(
-      providerId,
-      ctx.fs,
-      resolved,
-      executable,
-      spec => ctx.subprocess.spawn(spec),
-    )
-  }))
+  const providers = await (async () => {
+    try {
+      return await Promise.all(entries.map(async ([providerId, rawConfig]) => {
+        if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
+        const resolved = rawConfig as ResolvedServerConfig
+        validateServerConfig(providerId, resolved)
+        const executable = await ctx.subprocess.resolveExecutable(
+          resolved.command,
+          resolved.env,
+          setupAbort.signal,
+        )
+        setupAbort.signal.throwIfAborted()
+        return new LocalLspProvider(
+          providerId,
+          ctx.fs,
+          resolved,
+          executable,
+          spec => ctx.subprocess.spawn(spec),
+        )
+      }))
+    } catch (error: unknown) {
+      setupAbort.abort(error)
+      throw error
+    } finally {
+      stopSetupCancellation()
+    }
+  })()
 
   ctx.effect(() => {
     const disposers: Array<() => void> = []
diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts
index b0209e09b8..8d8a7ad356 100644
--- a/packages/lsp/lsp-local/tests/provider.spec.ts
+++ b/packages/lsp/lsp-local/tests/provider.spec.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { chmod, mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { delimiter, join } from 'node:path'
@@ -195,6 +195,41 @@ describe('lsp-local provider resolution', () => {
     await ctx.fiber.dispose()
   })
 
+  it('aborts executable resolution when disposed during setup', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+    const subprocess = ctx.subprocess
+    const lookupStarted = Promise.withResolvers<AbortSignal>()
+    vi.spyOn(subprocess, 'resolveExecutable').mockImplementation(async (_command, _env, signal) => {
+      if (signal === undefined) throw new Error('missing setup signal')
+      lookupStarted.resolve(signal)
+      return await new Promise<string>((_resolve, reject) => {
+        const onAbort = (): void => {
+          reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+        }
+        signal.addEventListener('abort', onAbort, { once: true })
+        if (signal.aborted) onAbort()
+      })
+    })
+
+    const loading = ctx.plugin(LspLocal, config('pending', {
+      command: 'pending-lsp',
+      extensionToLanguage: { '.ts': 'typescript' },
+    }))
+    const signal = await lookupStarted.promise
+    const unrelated = await ctx.plugin(() => {})
+    await unrelated.dispose()
+    expect(signal.aborted).toBe(false)
+    const disposing = loading.dispose()
+
+    await expect(loading).rejects.toThrow('lsp-local setup disposed')
+    await expect(disposing).resolves.toBeUndefined()
+    expect(signal.aborted).toBe(true)
+    await ctx.fiber.dispose()
+  })
+
   it('rolls back earlier registrations when a later server conflicts', async () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)

From a95e01d8b02bc4882d840441b59d680b34d9ab39 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:00:08 +0800
Subject: [PATCH 311/516] fix(pty): detach cancellation before close drain

---
 packages/pty/pty-local/src/session.ts        |  5 ++++-
 packages/pty/pty-local/tests/session.spec.ts | 22 ++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 0fb9f4ab0b..267c7c17fc 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -518,13 +518,16 @@ export class LocalPtySession implements PtyBackendSession {
     if (!quiescent) {
       throw new Error(`PTY cleanup failed (${reason}); terminal session did not reach quiescence`)
     }
+    // Quiescence is the active send's terminal outcome. Detach its abort
+    // listener before snapshotting provider operations so no late interrupt
+    // can enter the owned set after the drain starts.
+    this.settleActive('session_exit')
     await Promise.all(this.terminalOperations)
     // Whole-session cleanup can fail before the top-level process exits. Wait
     // for it first so that failure is reported instead of blocking forever on
     // `done`; successful quiescence guarantees `done` can now settle status and
     // drain the terminal output.
     await this.completion
-    this.settleActive('session_exit')
     this.terminal.output.off('data', this.onTerminalData)
     this.terminal.output.off('end', this.onTerminalEnd)
     this.terminal.output.off('error', this.onTerminalError)
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index c5fc354106..cce384bf6b 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -954,4 +954,26 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     expect((await operation.done).waitReason).toBe('session_exit')
   })
 
+  it('detaches active cancellation before draining terminal operations', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await inspection.promise
+    const signalForeground = vi.spyOn(terminal, 'signalForeground')
+    const controller = new AbortController()
+    const operation = session.startSend({ text: 'pending inspection', submit: true, signal: controller.signal })
+    const closing = session.close('pending cancellation')
+    await Promise.resolve()
+    await Promise.resolve()
+
+    controller.abort('late cancellation')
+    expect(signalForeground).not.toHaveBeenCalled()
+    inspection.resolve({ processGroupId: 456, inputWaiting: false })
+    await closing
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
 })

From 06a922490418f6dea751328e8ee0970762036d6e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:00:21 +0800
Subject: [PATCH 312/516] fix(subprocess): retain failed terminal cleanup

---
 .../subprocess/subprocess-local/src/index.ts  |  3 +-
 .../subprocess-local/tests/local.spec.ts      | 30 +++++++++++++++++--
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 4c5cad8018..6d7684eeeb 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -64,10 +64,9 @@ export class LocalSubprocessService extends SubprocessService {
         // an identity-fenced descendant survives escalation). Await the cleanup
         // transaction directly so disposal reports that failure rather than
         // waiting forever on `done`.
-        pending.push(terminal.waitForExit())
+        pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
       }
       this.live.clear()
-      this.terminals.clear()
       await Promise.all(pending)
       await rm(this.runtimeRoot, { recursive: true, force: true })
     }, 'local subprocess teardown')
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index b2ebfcfed0..b772545f7f 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,6 +1,6 @@
 import { PassThrough } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
-import { stat } from 'node:fs/promises'
+import { rm, stat } from 'node:fs/promises'
 import { basename, delimiter, dirname, relative } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
@@ -108,10 +108,36 @@ describe('LocalSubprocessService', () => {
       terminate,
       waitForExit,
     }
-    ;(ctx.subprocess as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals.add(terminal)
+    const terminals = (ctx.subprocess as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
+    terminals.add(terminal)
     await fiber.dispose()
     expect(terminate).toHaveBeenCalledOnce()
     expect(waitForExit).toHaveBeenCalledOnce()
+    expect(terminals.size).toBe(0)
+  })
+
+  it('retains an owned terminal when disposal cleanup rejects', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const service = ctx.subprocess
+    const runtimeRoot = service.runtimeRoot
+    const terminal: SubprocessTerminalHandle = {
+      pid: 1,
+      output: new PassThrough(),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+      write: async () => {},
+      inspectForeground: async () => undefined,
+      signalForeground: async () => 1,
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw new Error('retryable cleanup failure') }),
+    }
+    const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
+    terminals.add(terminal)
+
+    await fiber.dispose()
+    expect(terminals).toEqual(new Set([terminal]))
+    expect((await stat(runtimeRoot)).isDirectory()).toBe(true)
+    await rm(runtimeRoot, { recursive: true, force: true })
   })
 
   it('releases a terminal after top-level exit reaches quiescence', async () => {

From ea047cc634bf1674f0d563a4f68d72a284e1b97e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:00:33 +0800
Subject: [PATCH 313/516] test(subprocess): accept zombie quiescence

---
 .../subprocess/subprocess-local/tests/spawn.spec.ts  | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index 7d92447794..b9f0bf0321 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -60,7 +60,7 @@ function spec(command: string, overrides: SpecOverrides = {}) {
   }
 }
 
-/** Poll until a pid no longer exists (kill(pid, 0) throws ESRCH). */
+/** Poll until a pid no longer exists, or is only a zombie on Linux. */
 async function waitGone(pid: number, timeoutMs = 5_000): Promise<void> {
   const deadline = Date.now() + timeoutMs
   while (Date.now() < deadline) {
@@ -69,6 +69,16 @@ async function waitGone(pid: number, timeoutMs = 5_000): Promise<void> {
     } catch {
       return
     }
+    if (process.platform === 'linux') {
+      try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+        const state = stat.slice(stat.lastIndexOf(')') + 2, stat.lastIndexOf(')') + 3)
+        if (state === 'Z' || state === 'X') return
+      } catch (error: unknown) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+        throw error
+      }
+    }
     await new Promise(resolve => setTimeout(resolve, 20))
   }
   throw new Error(`pid ${pid} still alive after ${timeoutMs}ms`)

From 562cd154a827ee2fc619f9d246a31f3f927e87d9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:00:44 +0800
Subject: [PATCH 314/516] docs(lsp): remove resolved URI limitation

---
 packages/lsp/lsp-local/README.i18n.yaml | 4 ++--
 packages/lsp/lsp-local/README.md        | 1 -
 packages/lsp/lsp-local/README.zh.md     | 1 -
 3 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index 1504e6f726..e2b67d46d9 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-local/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/lsp/lsp-local/README.md
-README.md: 2c5ab309f3557ad77696a881b41d164e65bd24fe
-README.zh.md: d4493832964a5ac0d804602c18774bb106ddcbd9
+README.md: 299a5282bbca0a6d517af9342c4101cbdae33d4c
+README.zh.md: edf706fdb424756aa43b303b018b11e3764c2559
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index 2c5ab309f3..299a5282bb 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -55,6 +55,5 @@ No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **No confinement policy** — this package trusts the configured server and does not sandbox its process; a restricted deployment must supply appropriate process/filesystem providers or a same-world sandbox wrapper.
-- **Execution-world URI rendering** — the stdio host produces provider-owned `file:` URIs. The current model tool renders them with the harness host's path library, so a Windows harness paired with a POSIX remote execution world may show remote locations as URIs or non-native paths; protocol queries remain correct.
 - **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim.
 - **Per-server/workspace serialization latency** — parallel agents sharing one server and workspace queue behind one process; long-lived workspace processes consume memory until disposal.
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index d449383296..edf706fdb4 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -55,6 +55,5 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 ## 已知限制与暂缓事项
 
 - **不提供隔离策略**：这个包（package）信任配置的服务器，不会对其进程执行沙箱化；受限部署必须提供适当的进程／文件系统提供方，或包装同一执行环境的沙箱。
-- **执行环境 URI 渲染**：stdio 主机生成归提供方所有的 `file:` URI。当前面向模型的工具使用 harness 宿主的路径库渲染这些 URI，因此 Windows harness 与 POSIX 远程执行环境配对时，可能把远程位置显示为 URI 或非本机路径；协议查询仍然正确。
 - **临时打开兼容性下限**：同步能力省略打开／关闭（或声明 `None`）的服务器不受支持，即使关闭文档查询能够工作；固定的 TypeScript e2e 只建立一项兼容性下限，不代表跨语言承诺。
 - **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent 会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到释放。

From f84f63ccd777aee8961f7631008a7f30a68faaa6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:26:21 +0800
Subject: [PATCH 315/516] test(runtime): finish zombie quiescence migration

---
 packages/lsp/lsp-local/tests/instance.spec.ts       | 13 +++++++++++--
 .../subprocess/subprocess-local/tests/spawn.spec.ts |  6 +++---
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 811f15c9fa..08bad67ae2 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
 import { mkdtemp, mkdir, readFile, rm, writeFile, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -346,14 +347,22 @@ describe('LspInstance disposal', () => {
 function processAlive(pid: number): boolean {
   try {
     process.kill(pid, 0)
-    return true
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false
     throw error
   }
+  if (process.platform !== 'linux') return true
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    const state = stat.slice(stat.lastIndexOf(')') + 2).split(/\s+/, 1)[0]
+    return !/^[ZXx]$/.test(state ?? '')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
 }
 
-/** Wait until a process id disappears so temporary-workspace cleanup cannot race handle release. */
+/** Wait until a process can no longer execute so temporary-workspace cleanup cannot race handle release. */
 async function waitForProcessExit(pid: number, timeoutMs = 3_000): Promise<void> {
   const started = Date.now()
   while (processAlive(pid)) {
diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index b9f0bf0321..f28f741992 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -665,7 +665,7 @@ describe('tree-survivor escalation (terminate and bounded waits reach helpers th
     clearTimeout(timer)
     running.terminate()
     await expect(running.waitForExit()).resolves.toBe(true)
-    expect(() => process.kill(helper, 0)).toThrow()
+    await expect(waitGone(helper)).resolves.toBeUndefined()
   })
 
   it('service teardown awaits tree survivors, not just handle settlement', async () => {
@@ -682,8 +682,8 @@ describe('tree-survivor escalation (terminate and bounded waits reach helpers th
     const helper = await waitForPidFile(pidFile)
     await running.done
     await fiber.dispose()
-    // Teardown itself waited for the survivor to die.
-    expect(() => process.kill(helper, 0)).toThrow()
+    // Teardown itself waited for the survivor to become quiescent.
+    await expect(waitGone(helper)).resolves.toBeUndefined()
   })
 })
 

From 71e0eeac40231c943490c328bd71be3fafdadc9b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 09:28:50 +0800
Subject: [PATCH 316/516] fix(code-runtime): contain hostile boundary failures

---
 .../code-runtime-worker/src/runtime-host.ts   |  6 +++++-
 .../code-runtime-worker/tests/runtime.spec.ts | 21 +++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
index 334bd82e38..474a058e9f 100644
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -49,7 +49,11 @@ export type RuntimeBindingReply =
  * @returns the caller-facing diagnostic text.
  */
 export function runtimeErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
+  try {
+    return error instanceof Error ? error.message : String(error)
+  } catch {
+    return 'binding rejected with an unrenderable value'
+  }
 }
 
 /**
diff --git a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
index 54f58eb414..db2c167354 100644
--- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
@@ -597,6 +597,27 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
     expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
   })
 
+  it('contains binding rejections whose thrown values cannot be rendered', async () => {
+    const { runtime } = await setup()
+    const result = await runtime.run({
+      program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
+      bindings: tools({
+        bad: async () => {
+          const hostile = new Error('hidden')
+          Object.defineProperty(hostile, 'message', {
+            get() { throw new Error('message getter failed') },
+          })
+          throw hostile
+        },
+      }),
+    })
+    expect(result.value).toEqual({
+      name: 'ToolCallError',
+      toolName: 'bad',
+      message: 'binding rejected with an unrenderable value',
+    })
+  })
+
   it('rejects lossy binding arguments in the worker before invoking the host binding', async () => {
     const { runtime } = await setup()
     let calls = 0

From f61a4943bdad0874a662f6fbfb8389cc140fd38f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 09:29:01 +0800
Subject: [PATCH 317/516] fix(lsp): preserve POSIX backslash paths

---
 packages/lsp/tool-lsp/src/render.ts        | 5 +++--
 packages/lsp/tool-lsp/tests/render.spec.ts | 6 +++++-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 1e73e7ec6a..2f376707db 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -149,6 +149,7 @@ export function renderUri(uri: string, workspaceUri: string): string {
   if (targetSegments === undefined || workspaceSegments === undefined) return uri
   const sameAuthority = target.hostname === workspace.hostname
   const windowsWorld = isWindowsFileWorld(workspace, workspaceSegments)
+  if (windowsWorld && [...targetSegments, ...workspaceSegments].some(segment => segment.includes('\\'))) return uri
   const inside = sameAuthority
     && targetSegments.length >= workspaceSegments.length
     && workspaceSegments.every((segment, index) => samePathSegment(segment, targetSegments[index] as string, windowsWorld))
@@ -164,11 +165,11 @@ function isWindowsFileWorld(url: URL, segments: readonly string[]): boolean {
   return url.hostname.length > 0 || /^[A-Za-z]:$/.test(segments[0] ?? '')
 }
 
-/** Decode URI path segments while rejecting encoded separators that would change path structure. */
+/** Decode URI path segments while rejecting encoded POSIX separators and NUL. */
 function decodeFileSegments(url: URL): string[] | undefined {
   try {
     const decoded = url.pathname.split('/').map(segment => decodeURIComponent(segment))
-    if (decoded.some(segment => /[/\\\0]/u.test(segment))) return undefined
+    if (decoded.some(segment => /[/\0]/u.test(segment))) return undefined
     while (decoded.at(-1) === '') decoded.pop()
     decoded.shift()
     return decoded
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index 953f7ef4c1..f09297d3d4 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -82,11 +82,15 @@ describe('renderUri', () => {
     expect(renderUri('file:///a.ts', 'file:///')).toBe('a.ts')
   })
 
+  it('preserves backslashes as ordinary POSIX filename characters', () => {
+    expect(renderUri('file:///home/u/proj/dir%5Cname/a.ts', WS_URI)).toBe('dir\\name/a.ts')
+  })
+
   it('keeps malformed or mismatched URI coordinates verbatim', () => {
     expect(renderUri('file://[', WS_URI)).toBe('file://[')
     expect(renderUri('file:///a.ts', 'https://example.com/workspace')).toBe('file:///a.ts')
     expect(renderUri('file:///a.ts', 'file:///bad%ZZ')).toBe('file:///a.ts')
-    expect(renderUri('file:///bad%5Cpath', WS_URI)).toBe('file:///bad%5Cpath')
+    expect(renderUri('file:///C:/workspace/bad%5Cpath', 'file:///C:/workspace')).toBe('file:///C:/workspace/bad%5Cpath')
     expect(renderUri('file:///short', 'file:///short/deeper')).toBe('/short')
     expect(renderUri('file:///', 'file:///C:/workspace')).toBe('/')
   })

From 098f826001cc407e785cc70d2f8a89a77cfa8002 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:02:17 +0800
Subject: [PATCH 318/516] fix(subprocess): honor teardown and PATH semantics

---
 .../subprocess/subprocess-local/src/index.ts  |  7 ++--
 .../subprocess-local/tests/local.spec.ts      | 36 ++++++++++++++-----
 2 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 6d7684eeeb..80d0b4c76b 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -67,7 +67,10 @@ export class LocalSubprocessService extends SubprocessService {
         pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
       }
       this.live.clear()
-      await Promise.all(pending)
+      const outcomes = await Promise.allSettled(pending)
+      for (const outcome of outcomes) {
+        if (outcome.status === 'rejected') throw outcome.reason
+      }
       await rm(this.runtimeRoot, { recursive: true, force: true })
     }, 'local subprocess teardown')
   }
@@ -106,7 +109,7 @@ export class LocalSubprocessService extends SubprocessService {
       ? (environmentValue(env, 'PATHEXT') ?? '.COM;.EXE;.BAT;.CMD').split(';')
       : ['']
     return path.split(delimiter).flatMap(directory =>
-      directory === '' ? [] : extensions.map(extension => resolve(this.cwd, directory, command + extension)))
+      extensions.map(extension => resolve(this.cwd, directory, command + extension)))
   }
 
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index b772545f7f..46f3b14bea 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,7 +1,7 @@
 import { PassThrough } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
 import { rm, stat } from 'node:fs/promises'
-import { basename, delimiter, dirname, relative } from 'node:path'
+import { basename, dirname, relative, resolve } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import type { SubprocessSpawnSpec, SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
@@ -42,6 +42,9 @@ describe('LocalSubprocessService', () => {
     expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), {
       PATH: relative(process.cwd(), dirname(process.execPath)) || '.',
     })).toBe(process.execPath)
+    Reflect.set(ctx.subprocess, 'cwd', dirname(process.execPath))
+    expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), { PATH: '' }))
+      .toBe(process.execPath)
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('must be non-empty')
     await expect(ctx.subprocess.resolveExecutable('dsh-command-that-does-not-exist', { PATH: '' }))
       .rejects.toThrow('was not found on PATH')
@@ -54,7 +57,7 @@ describe('LocalSubprocessService', () => {
     await fiber.dispose()
   })
 
-  it('builds Windows executable candidates without empty PATH entries', async () => {
+  it('builds Windows executable candidates with case-insensitive overrides', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess as LocalSubprocessService
@@ -64,13 +67,13 @@ describe('LocalSubprocessService', () => {
     const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
     try {
       expect(Object.keys(childEnv()).filter(key => key.toUpperCase() === 'PATH')).toHaveLength(1)
-      const explicit = childEnv({ Path: `${delimiter}/bin`, PathExt: '.EXE;.CMD' })
+      const explicit = childEnv({ Path: '/bin', PathExt: '.EXE;.CMD' })
       expect(Object.keys(explicit).filter(key => key.toUpperCase() === 'PATH')).toEqual(['Path'])
       expect(Object.keys(explicit).filter(key => key.toUpperCase() === 'PATHEXT')).toEqual(['PathExt'])
       expect(candidates('tool', explicit)).toEqual(['/bin/tool.EXE', '/bin/tool.CMD'])
       expect(candidates('tool', { Path: '/ambient', PATH: '/explicit', PATHEXT: '.EXE' }))
         .toEqual(['/explicit/tool.EXE'])
-      expect(candidates('tool.exe', {})).toEqual([])
+      expect(candidates('tool.exe', {})).toEqual([resolve(process.cwd(), 'tool.exe')])
       expect(candidates('tool', { PATH: '/bin' })).toHaveLength(4)
     } finally {
       platform.mockRestore()
@@ -116,12 +119,12 @@ describe('LocalSubprocessService', () => {
     expect(terminals.size).toBe(0)
   })
 
-  it('retains an owned terminal when disposal cleanup rejects', async () => {
+  it('waits for every terminal cleanup and retains rejections', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
     const runtimeRoot = service.runtimeRoot
-    const terminal: SubprocessTerminalHandle = {
+    const failedTerminal: SubprocessTerminalHandle = {
       pid: 1,
       output: new PassThrough(),
       done: Promise.resolve({ exitCode: 0, signal: null }),
@@ -131,11 +134,26 @@ describe('LocalSubprocessService', () => {
       terminate: vi.fn(),
       waitForExit: vi.fn(async () => { throw new Error('retryable cleanup failure') }),
     }
+    let finishCleanup!: () => void
+    const cleanup = new Promise<boolean>((resolve) => {
+      finishCleanup = () => { resolve(true) }
+    })
+    const drainingTerminal: SubprocessTerminalHandle = {
+      ...failedTerminal,
+      terminate: vi.fn(),
+      waitForExit: vi.fn(() => cleanup),
+    }
     const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
-    terminals.add(terminal)
+    terminals.add(failedTerminal)
+    terminals.add(drainingTerminal)
 
-    await fiber.dispose()
-    expect(terminals).toEqual(new Set([terminal]))
+    let disposed = false
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await new Promise(resolve => setImmediate(resolve))
+    expect(disposed).toBe(false)
+    finishCleanup()
+    await disposing
+    expect(terminals).toEqual(new Set([failedTerminal]))
     expect((await stat(runtimeRoot)).isDirectory()).toBe(true)
     await rm(runtimeRoot, { recursive: true, force: true })
   })

From 4d63552d009aad6e09c06f87c3a68e1b2a0e10ac Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:17:45 +0800
Subject: [PATCH 319/516] fix(lsp): preserve workspace cancellation reason

---
 packages/lsp/lsp-local/src/host.ts        |  5 ++++-
 packages/lsp/lsp-local/tests/host.spec.ts | 20 ++++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts
index 3a2b9fbd7b..55e13ed307 100644
--- a/packages/lsp/lsp-local/src/host.ts
+++ b/packages/lsp/lsp-local/src/host.ts
@@ -42,7 +42,10 @@ export async function canonicalizeWorkspace(
     throw new Error(`workspace root "${workspaceRoot}" cannot be resolved: ${messageOf(error)}`, { cause: error })
   }
   throwIfAborted(signal)
-  const info = await fs.stat(target, signal)
+  const info = await fs.stat(target, signal).catch((error: unknown) => {
+    throwIfAborted(signal)
+    throw error
+  })
   throwIfAborted(signal)
   if (info?.type !== 'directory') {
     throw new Error(`workspace root "${workspaceRoot}" is not a directory`)
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index cd7ed87e17..3db9deb50a 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -57,11 +57,31 @@ describe('canonicalizeWorkspace', () => {
     await expect(canonicalizeWorkspace(fs, join(root, 'nope'))).rejects.toThrow(/not a directory/)
   })
 
+  it('wraps a provider failure while resolving the workspace', async () => {
+    fs.resolve = async () => { throw 'raw workspace resolve failure' }
+    await expect(canonicalizeWorkspace(fs, ws))
+      .rejects.toThrow(`workspace root "${ws}" cannot be resolved: raw workspace resolve failure`)
+  })
+
   it('rejects a non-directory workspace', async () => {
     const file = join(root, 'file.txt')
     await writeFile(file, 'x')
     await expect(canonicalizeWorkspace(fs, file)).rejects.toThrow(/not a directory/)
   })
+
+  it('normalizes workspace metadata cancellation and preserves other provider failures', async () => {
+    const providerFailure = new Error('workspace metadata failed')
+    fs.stat = async () => { throw providerFailure }
+    await expect(canonicalizeWorkspace(fs, ws)).rejects.toBe(providerFailure)
+
+    const controller = new AbortController()
+    fs.stat = async () => {
+      controller.abort(new Error('workspace metadata cancelled'))
+      throw providerFailure
+    }
+    await expect(canonicalizeWorkspace(fs, ws, controller.signal))
+      .rejects.toThrow('workspace metadata cancelled')
+  })
 })
 
 describe('readHostSource', () => {

From 0fec058a483a1dae658250878c149b4fafa04f65 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:52:37 +0800
Subject: [PATCH 320/516] fix(pty): retain send ownership through cancellation

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |  4 +-
 .../2026-07-16-persistent-pty-sessions.md     |  2 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +-
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 24 +++++++--
 packages/pty/pty-local/tests/session.spec.ts  | 54 +++++++++++++++++++
 11 files changed, 87 insertions(+), 15 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 30e672416a..02545da311 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: ccb7a13a9677c106976efbe95629d0d2c027b982
-2026-07-28-portable-execution-world-consumers.zh.md: 0a7b840049a826a47f4dc0476e5991bfd0578970
+2026-07-28-portable-execution-world-consumers.md: 715529e5f24df0c2fe0afc40716737285afa223b
+2026-07-28-portable-execution-world-consumers.zh.md: a9d864b581bd546c12776152ad4515816ee6b83a
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index ccb7a13a96..715529e5f2 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. A timed-out asynchronous write, or a cancellation whose foreground signal fails during that write, retains the send reservation until the provider settles it; completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; a timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 0a7b840049..a9d864b581 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。异步写入超时，或在该写入期间取消时前台信号发送失败，都会保留发送预留，直至提供方将写入结算；陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 8b33466ea7..2694664183 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: ef87c2806a237e6e6d44c1e62942146af24b8c19
-2026-07-16-persistent-pty-sessions.zh.md: 5f1bde39de5eca7aa57897d87c95675ce0da5abd
+2026-07-16-persistent-pty-sessions.md: f94dd57622c555e195564cc2eee9b3228841d5cc
+2026-07-16-persistent-pty-sessions.zh.md: 6228571a6496e9d4cb031a2df958b80dee102fd3
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index ef87c2806a..f94dd57622 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -60,7 +60,7 @@ The local subprocess terminal primitive uses only public `node-pty` capabilities
 
 The UI render contract is exact and location-free. `terminal_send` uses terminal call/result cards only for foreground sends; its background form is generic `execute`. `terminal_open`, `terminal_read`, `terminal_signal`, `terminal_close`, and `terminal_list` use generic `execute`, `read`, `execute`, `delete`, and `read` cards respectively. No PTY tool emits `locations`.
 
-`terminal_send({ sessionId, text, submit?, run_in_background? })` treats `text` as UTF-8 bytes and resolves `submit` to `true` in the tool implementation. When `submit` is true it writes the platform Enter sequence after the text; when false it writes only the text, allowing control characters and REPL fragments without hidden content heuristics. Cancellation marks queued input before signaling the real foreground group, so input cannot execute if an asynchronous pre-write inspection settles afterward. `enableRunInBackground` defaults to true; false removes `run_in_background` from the schema and rejects the same undeclared argument if a caller forces it through execution.
+`terminal_send({ sessionId, text, submit?, run_in_background? })` treats `text` as UTF-8 bytes and resolves `submit` to `true` in the tool implementation. When `submit` is true it writes the platform Enter sequence after the text; when false it writes only the text, allowing control characters and REPL fragments without hidden content heuristics. Cancellation marks queued input before signaling the real foreground group, so input cannot execute if an asynchronous pre-write inspection settles afterward. The canceled send retains its reservation until asynchronous foreground signalling settles, so a successor cannot become that signal's target. `enableRunInBackground` defaults to true; false removes `run_in_background` from the schema and rejects the same undeclared argument if a caller forces it through execution.
 
 Foreground sends return a bounded rendered delta and two independent facts: `waitReason` (`stdin_read | inferred_idle | timeout | session_exit`) and `sessionStatus` (`running` or `exited` with exit code or signal). `session_exit` refers to the PTY's top-level shell process, not an arbitrary foreground command whose status the shell consumes. A timeout never implies process exit. `dsh-tool-pty.maxResultBytes` defaults to 262144, rejects values below 64 so creation acknowledgements retain registry-issued ids, and caps each single-text UTF-8 result after normalized tool or pipeline errors, wait, session, pagination, truncation, generic task-status wrappers, policy denials or short-circuits, and post-execute replacements or blocks; the terminal definitions' last-mile `finalizeContent` callback leaves deliberately structured multi-block policy content unchanged. The renderer reserves suffix space and preserves code-point boundaries instead of treating the backend payload cap as the final model bound.
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 5f1bde39de..6228571a64 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -60,7 +60,7 @@ agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出
 
 UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
 
-`terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。取消会在向真实前台进程组发送信号前将排队输入标记为已取消，因此即使异步的写入前检查随后才结算，该输入也无法执行。`enableRunInBackground` 默认为 true；设为 false 时，schema 中会移除 `run_in_background`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
+`terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。取消会在向真实前台进程组发送信号前将排队输入标记为已取消，因此即使异步的写入前检查随后才结算，该输入也无法执行。被取消的发送会保留其预留，直至异步前台信号发送结算，因此后续发送不会成为该信号的目标。`enableRunInBackground` 默认为 true；设为 false 时，schema 中会移除 `run_in_background`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
 
 前台发送返回有界的渲染增量和两个独立事实：`waitReason`（`stdin_read | inferred_idle | timeout | session_exit`）与 `sessionStatus`（`running`，或携带退出码或信号的 `exited`）。`session_exit` 指 PTY 顶层 shell 进程退出，不指由 shell 消费状态的任意前台命令。timeout 从不意味着进程已经退出。`dsh-tool-pty.maxResultBytes` 默认为 262144；低于 64 的值会被拒绝，以确保创建确认保留 registry 签发的 id；每个单文本 UTF-8 结果在加入规范化的工具或流水线错误、等待、会话、分页、截断、通用 task 状态包装、策略拒绝或短路以及 post-execute 替换或阻断后，仍受该值限制；终端定义自有的末端 `finalizeContent` callback 会原样保留策略刻意返回的结构化多 block 内容。渲染器会为后缀预留空间并保持代码点边界，而不会把后端载荷上限当作面向模型结果的最终上限。
 
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 4c153eff47..c89122066a 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: 74dfd7f59d45649f6daf0b42408285d9ede830a7
-README.zh.md: 2c7780f7e7db896c959e017dc39299e0e16f187d
+README.md: 7e31adfbc486a190252be867e2113948b17e7924
+README.zh.md: eb628aef9ad6b0fea14a5e833197b4fac7856785
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 74dfd7f59d..7e31adfbc4 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -10,7 +10,7 @@ The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then reg
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the session's send slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 2c7780f7e7..eb628aef9a 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -10,7 +10,7 @@
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用会话的发送槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 267c7c17fc..922db21152 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -166,6 +166,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private readonly terminalOperations = new Set<Promise<void>>()
+  private interrupting: LocalSendOperation | undefined
   private writing: LocalSendOperation | undefined
   private pollingReady: LocalSendOperation | undefined
   private polling = false
@@ -403,7 +404,7 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private schedulePoll(operation: LocalSendOperation, delayMs = this.config.pollIntervalMs): void {
-    if (this.active !== operation || this.polling) return
+    if (this.active !== operation || this.interrupting === operation || this.polling) return
     if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = setTimeout(() => {
       this.activeTimer = undefined
@@ -480,9 +481,11 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private clearActive(): void {
+    const operation = this.active
     this.stopPolling()
     this.activeAbort?.()
     this.activeAbort = undefined
+    if (this.interrupting === operation) this.interrupting = undefined
     this.writing = undefined
     this.pollingReady = undefined
     this.active = undefined
@@ -503,9 +506,24 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    this.ownTerminalOperation(this.terminal.signalForeground('SIGINT').then(() => {}, (error: unknown) => {
+    this.interrupting = operation
+    this.stopPolling()
+    this.ownTerminalOperation(this.interruptOnce(operation))
+  }
+
+  private async interruptOnce(operation: LocalSendOperation): Promise<void> {
+    try {
+      await this.terminal.signalForeground('SIGINT')
+    } catch (error: unknown) {
       if (this.active === operation) this.failActive(error, this.writing === operation)
-    }))
+      return
+    } finally {
+      if (this.interrupting === operation) this.interrupting = undefined
+    }
+    if (this.active === operation && !operation.settled && !this.closing && this.writing !== operation) {
+      this.pollingReady = operation
+      this.schedulePoll(operation, 0)
+    }
   }
 
   private async closeOnce(reason: string): Promise<void> {
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index cce384bf6b..513dcbbbb4 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -340,6 +340,60 @@ describe('LocalPtySession readiness and output', () => {
     await operation.done
   })
 
+  it('retains a canceled send until asynchronous foreground signalling settles', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const signalGate = Promise.withResolvers<undefined>()
+    terminal.signalForeground = async (signal) => {
+      await signalGate.promise
+      const foreground = await terminal.inspectForeground()
+      if (foreground === undefined) throw new Error('cannot resolve foreground')
+      inspector.signalGroup(foreground.processGroupId, signal)
+      return foreground.processGroupId
+    }
+    const operation = session.startSend({ text: 'first', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+
+    terminal.emitData('\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(() => session.startSend({ text: 'successor', submit: true })).toThrow('active send')
+    signalGate.resolve(undefined)
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    expect(inspector.groups).not.toContainEqual([789, 'SIGINT'])
+  })
+
+  it('does not resume cancellation polling after the terminal exits during signalling', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const signalGate = Promise.withResolvers<undefined>()
+    terminal.signalForeground = async () => {
+      await signalGate.promise
+      return 456
+    }
+    const operation = session.startSend({ text: 'first', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+    terminal.emitExit(0)
+    await expect(operation.done).resolves.toMatchObject({ waitReason: 'session_exit' })
+
+    signalGate.resolve(undefined)
+    await vi.advanceTimersByTimeAsync(10)
+    expect(session.status()).toEqual({ kind: 'exited', exitCode: 0, signal: null })
+  })
+
   it('retains send ownership after timeout until an asynchronous provider write settles', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From be3533fa19438cea98daad5727eb1a21e44a3f03 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:53:27 +0800
Subject: [PATCH 321/516] fix(subprocess): clean runtime state after teardown
 failure

---
 .../subprocess-local/README.i18n.yaml         |  4 +-
 .../subprocess/subprocess-local/README.md     |  2 +-
 .../subprocess/subprocess-local/README.zh.md  |  2 +-
 .../subprocess/subprocess-local/src/index.ts  | 14 +++--
 .../subprocess-local/tests/local.spec.ts      | 53 ++++++++++++++++---
 5 files changed, 60 insertions(+), 15 deletions(-)

diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 72f3c93da9..efbb1612bd 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: 38b26c33f3854acdb4a2bb48612da73361d727ba
-README.zh.md: fc4a5d4961fb7618b9db84b21063f907361a26d8
+README.md: 61ee8ff9e09d5177ff6d5b3805dd84fb74c59961
+README.zh.md: 06a8e4bdd225e212aa67817ebbf66581314ab2bf
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 38b26c33f3..61ee8ff9e0 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -10,7 +10,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
-- **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
+- **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal before any process-cleanup failure is reported, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and cleans descendants before the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index fc4a5d4961..06a8e4bdd2 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -10,7 +10,7 @@
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留尾部，即诊断尾部的形状。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需延迟创建的 `0700` 每进程目录之下。
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，在资源释放时删除；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
+- **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，会在资源释放时删除，并且删除发生在报告任何进程清理失败之前；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并先于顶层 shell 清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
 - **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 80d0b4c76b..0d71cb0e33 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -67,11 +67,15 @@ export class LocalSubprocessService extends SubprocessService {
         pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
       }
       this.live.clear()
-      const outcomes = await Promise.allSettled(pending)
-      for (const outcome of outcomes) {
-        if (outcome.status === 'rejected') throw outcome.reason
-      }
-      await rm(this.runtimeRoot, { recursive: true, force: true })
+      const outcomes = [
+        ...await Promise.allSettled(pending),
+        ...await Promise.allSettled([rm(this.runtimeRoot, { recursive: true, force: true })]),
+      ]
+      const failures = outcomes.flatMap<unknown>(outcome => outcome.status === 'rejected'
+        ? [outcome.reason as unknown]
+        : [])
+      if (failures.length === 1) throw failures[0]
+      if (failures.length > 1) throw new AggregateError(failures, 'local subprocess teardown failed')
     }, 'local subprocess teardown')
   }
 
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 46f3b14bea..e4dd4cfb44 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,6 +1,6 @@
 import { PassThrough } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
-import { rm, stat } from 'node:fs/promises'
+import { stat } from 'node:fs/promises'
 import { basename, dirname, relative, resolve } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
@@ -119,11 +119,15 @@ describe('LocalSubprocessService', () => {
     expect(terminals.size).toBe(0)
   })
 
-  it('waits for every terminal cleanup and retains rejections', async () => {
+  it('waits for every terminal cleanup, removes runtime state, and retains rejections', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
     const runtimeRoot = service.runtimeRoot
+    const firstFailure = new Error('first retryable cleanup failure')
+    const secondFailure = new Error('second retryable cleanup failure')
+    const disposalErrors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
     const failedTerminal: SubprocessTerminalHandle = {
       pid: 1,
       output: new PassThrough(),
@@ -132,7 +136,12 @@ describe('LocalSubprocessService', () => {
       inspectForeground: async () => undefined,
       signalForeground: async () => 1,
       terminate: vi.fn(),
-      waitForExit: vi.fn(async () => { throw new Error('retryable cleanup failure') }),
+      waitForExit: vi.fn(async () => { throw firstFailure }),
+    }
+    const secondFailedTerminal: SubprocessTerminalHandle = {
+      ...failedTerminal,
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw secondFailure }),
     }
     let finishCleanup!: () => void
     const cleanup = new Promise<boolean>((resolve) => {
@@ -145,6 +154,7 @@ describe('LocalSubprocessService', () => {
     }
     const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
     terminals.add(failedTerminal)
+    terminals.add(secondFailedTerminal)
     terminals.add(drainingTerminal)
 
     let disposed = false
@@ -153,9 +163,40 @@ describe('LocalSubprocessService', () => {
     expect(disposed).toBe(false)
     finishCleanup()
     await disposing
-    expect(terminals).toEqual(new Set([failedTerminal]))
-    expect((await stat(runtimeRoot)).isDirectory()).toBe(true)
-    await rm(runtimeRoot, { recursive: true, force: true })
+    expect(terminals).toEqual(new Set([failedTerminal, secondFailedTerminal]))
+    await expect(stat(runtimeRoot)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect(disposalErrors).toHaveLength(1)
+    expect(disposalErrors[0]).toMatchObject({
+      errors: [firstFailure, secondFailure],
+      message: 'local subprocess teardown failed',
+    })
+  })
+
+  it('reports one cleanup failure without wrapping it after removing runtime state', async () => {
+    const ctx = new Context()
+    const failure = new Error('single cleanup failure')
+    const disposalErrors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
+    const fiber = await ctx.plugin(LocalSubprocessService)
+    const service = ctx.subprocess
+    const runtimeRoot = service.runtimeRoot
+    const terminal: SubprocessTerminalHandle = {
+      pid: 1,
+      output: new PassThrough(),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+      write: async () => {},
+      inspectForeground: async () => undefined,
+      signalForeground: async () => 1,
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw failure }),
+    }
+    const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
+    terminals.add(terminal)
+
+    await fiber.dispose()
+
+    await expect(stat(runtimeRoot)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect(disposalErrors).toEqual([failure])
   })
 
   it('releases a terminal after top-level exit reaches quiescence', async () => {

From d6b3de6e0da064f5b95e29a4134e30da39ab2d1a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 11:57:12 +0800
Subject: [PATCH 322/516] fix(pty): fence delayed signal prompts

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +--
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +--
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 16 +++++++++-
 packages/pty/pty-local/tests/session.spec.ts  | 29 +++++++++++++++++++
 8 files changed, 52 insertions(+), 9 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 02545da311..803a2f83fe 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 715529e5f24df0c2fe0afc40716737285afa223b
-2026-07-28-portable-execution-world-consumers.zh.md: a9d864b581bd546c12776152ad4515816ee6b83a
+2026-07-28-portable-execution-world-consumers.md: 54b8ec19bc74e734f2cb940a475d2c7b4c9336fd
+2026-07-28-portable-execution-world-consumers.zh.md: f21be00fd35267fe93e2fbb62642809cc42c0742
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 715529e5f2..54b8ec19bc 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; a timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index a9d864b581..f21be00fd3 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index c89122066a..3f21fb2bd3 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: 7e31adfbc486a190252be867e2113948b17e7924
-README.zh.md: eb628aef9ad6b0fea14a5e833197b4fac7856785
+README.md: c7b7a363f22821363a0fed81982165fd35326d12
+README.zh.md: 859b94e4f29b82abb298468f028f9eba7cc067e6
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 7e31adfbc4..c7b7a363f2 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,7 +8,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. After a signaled send returns `inferred_idle` without a prompt marker, the next marker remains attributed to that prior send and cannot settle a successor even when it follows the successor's echoed input. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
 Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index eb628aef9a..859b94e4f2 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,7 +8,7 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。在一次经过信号处理的 send 未出现提示符标记却返回 `inferred_idle` 后，下一个标记仍归属于该先前 send；即使该标记出现在后续 send 的输入回显之后，也不能使后续 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
 取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 922db21152..65a10c36ea 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -166,6 +166,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private readonly terminalOperations = new Set<Promise<void>>()
+  private signaledOperation: LocalSendOperation | undefined
   private interrupting: LocalSendOperation | undefined
   private writing: LocalSendOperation | undefined
   private pollingReady: LocalSendOperation | undefined
@@ -173,6 +174,7 @@ export class LocalPtySession implements PtyBackendSession {
   private promptSeen = false
   private promptTextSeen = false
   private promptTail = ''
+  private delayedSignaledPrompt = false
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
@@ -317,6 +319,7 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   async signal(signal: PtySignal): Promise<PtySignalResult> {
+    if (this.active !== undefined) this.signaledOperation = this.active
     const targetPgid = await this.terminal.signalForeground(signal)
     return { delivered: true, targetPgid }
   }
@@ -365,7 +368,9 @@ export class LocalPtySession implements PtyBackendSession {
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
-    if (sanitized.prompt) {
+    if (sanitized.prompt && this.delayedSignaledPrompt) {
+      this.delayedSignaledPrompt = false
+    } else if (sanitized.prompt) {
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
@@ -461,6 +466,13 @@ export class LocalPtySession implements PtyBackendSession {
   private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
+    // A signaled command can return by silence before bash emits its prompt.
+    // Reserve that marker so it cannot become successor readiness after echo.
+    const signaled = this.signaledOperation === operation
+    if (signaled) this.signaledOperation = undefined
+    if (waitReason === 'inferred_idle' && !this.promptSeen && signaled) {
+      this.delayedSignaledPrompt = true
+    }
     const scrollbackTruncated = this.scrollback.snapshot().truncated
     if (retainOwnership) {
       this.stopPolling()
@@ -486,6 +498,7 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeAbort?.()
     this.activeAbort = undefined
     if (this.interrupting === operation) this.interrupting = undefined
+    if (this.signaledOperation === operation) this.signaledOperation = undefined
     this.writing = undefined
     this.pollingReady = undefined
     this.active = undefined
@@ -506,6 +519,7 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
+    this.signaledOperation = operation
     this.interrupting = operation
     this.stopPolling()
     this.ownTerminalOperation(this.interruptOnce(operation))
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 513dcbbbb4..28ad58f04d 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -591,6 +591,35 @@ describe('LocalPtySession readiness and output', () => {
     expect(await operation.done).toMatchObject({ waitReason: 'stdin_read' })
   })
 
+  it('does not attribute a post-echo prompt from an inferred prior send to its successor', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config({ idleSilenceMs: 50, timeoutMs: 200 }))
+    await initialize(session, terminal)
+
+    const interrupted = session.startSend({ text: 'sleep', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await session.signal('SIGINT')
+    await vi.advanceTimersByTimeAsync(50)
+    expect((await interrupted.done).waitReason).toBe('inferred_idle')
+
+    const successor = session.startSend({ text: "printf 'PID=%s\\n' \"$!\"", submit: true })
+    let settled = false
+    void successor.done.then(() => { settled = true })
+    await Promise.resolve()
+    await Promise.resolve()
+    terminal.emitData('printf \'PID=%s\\n\' "$!"\r\n\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(settled).toBe(false)
+
+    terminal.emitData('PID=123\r\n\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    const result = await successor.done
+    expect(result.waitReason).toBe('stdin_read')
+    expect(result.viewport).toContain('PID=123')
+  })
+
   it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From 277870dac275292ce12f1de060421ba9cfd24661 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 12:05:00 +0800
Subject: [PATCH 323/516] Revert "fix(pty): fence delayed signal prompts"

This reverts commit a78958eeeaf04a3acdf22ef8a26dec370661a51d.
---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +--
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +--
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 16 +---------
 packages/pty/pty-local/tests/session.spec.ts  | 29 -------------------
 8 files changed, 9 insertions(+), 52 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 803a2f83fe..02545da311 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 54b8ec19bc74e734f2cb940a475d2c7b4c9336fd
-2026-07-28-portable-execution-world-consumers.zh.md: f21be00fd35267fe93e2fbb62642809cc42c0742
+2026-07-28-portable-execution-world-consumers.md: 715529e5f24df0c2fe0afc40716737285afa223b
+2026-07-28-portable-execution-world-consumers.zh.md: a9d864b581bd546c12776152ad4515816ee6b83a
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 54b8ec19bc..715529e5f2 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; a timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index f21be00fd3..a9d864b581 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 3f21fb2bd3..c89122066a 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: c7b7a363f22821363a0fed81982165fd35326d12
-README.zh.md: 859b94e4f29b82abb298468f028f9eba7cc067e6
+README.md: 7e31adfbc486a190252be867e2113948b17e7924
+README.zh.md: eb628aef9ad6b0fea14a5e833197b4fac7856785
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index c7b7a363f2..7e31adfbc4 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,7 +8,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. After a signaled send returns `inferred_idle` without a prompt marker, the next marker remains attributed to that prior send and cannot settle a successor even when it follows the successor's echoed input. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
 Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 859b94e4f2..eb628aef9a 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,7 +8,7 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。在一次经过信号处理的 send 未出现提示符标记却返回 `inferred_idle` 后，下一个标记仍归属于该先前 send；即使该标记出现在后续 send 的输入回显之后，也不能使后续 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
 取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 65a10c36ea..922db21152 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -166,7 +166,6 @@ export class LocalPtySession implements PtyBackendSession {
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private readonly terminalOperations = new Set<Promise<void>>()
-  private signaledOperation: LocalSendOperation | undefined
   private interrupting: LocalSendOperation | undefined
   private writing: LocalSendOperation | undefined
   private pollingReady: LocalSendOperation | undefined
@@ -174,7 +173,6 @@ export class LocalPtySession implements PtyBackendSession {
   private promptSeen = false
   private promptTextSeen = false
   private promptTail = ''
-  private delayedSignaledPrompt = false
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
@@ -319,7 +317,6 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   async signal(signal: PtySignal): Promise<PtySignalResult> {
-    if (this.active !== undefined) this.signaledOperation = this.active
     const targetPgid = await this.terminal.signalForeground(signal)
     return { delivered: true, targetPgid }
   }
@@ -368,9 +365,7 @@ export class LocalPtySession implements PtyBackendSession {
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
-    if (sanitized.prompt && this.delayedSignaledPrompt) {
-      this.delayedSignaledPrompt = false
-    } else if (sanitized.prompt) {
+    if (sanitized.prompt) {
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
@@ -466,13 +461,6 @@ export class LocalPtySession implements PtyBackendSession {
   private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
-    // A signaled command can return by silence before bash emits its prompt.
-    // Reserve that marker so it cannot become successor readiness after echo.
-    const signaled = this.signaledOperation === operation
-    if (signaled) this.signaledOperation = undefined
-    if (waitReason === 'inferred_idle' && !this.promptSeen && signaled) {
-      this.delayedSignaledPrompt = true
-    }
     const scrollbackTruncated = this.scrollback.snapshot().truncated
     if (retainOwnership) {
       this.stopPolling()
@@ -498,7 +486,6 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeAbort?.()
     this.activeAbort = undefined
     if (this.interrupting === operation) this.interrupting = undefined
-    if (this.signaledOperation === operation) this.signaledOperation = undefined
     this.writing = undefined
     this.pollingReady = undefined
     this.active = undefined
@@ -519,7 +506,6 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    this.signaledOperation = operation
     this.interrupting = operation
     this.stopPolling()
     this.ownTerminalOperation(this.interruptOnce(operation))
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 28ad58f04d..513dcbbbb4 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -591,35 +591,6 @@ describe('LocalPtySession readiness and output', () => {
     expect(await operation.done).toMatchObject({ waitReason: 'stdin_read' })
   })
 
-  it('does not attribute a post-echo prompt from an inferred prior send to its successor', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal, config({ idleSilenceMs: 50, timeoutMs: 200 }))
-    await initialize(session, terminal)
-
-    const interrupted = session.startSend({ text: 'sleep', submit: true })
-    await Promise.resolve()
-    await Promise.resolve()
-    await session.signal('SIGINT')
-    await vi.advanceTimersByTimeAsync(50)
-    expect((await interrupted.done).waitReason).toBe('inferred_idle')
-
-    const successor = session.startSend({ text: "printf 'PID=%s\\n' \"$!\"", submit: true })
-    let settled = false
-    void successor.done.then(() => { settled = true })
-    await Promise.resolve()
-    await Promise.resolve()
-    terminal.emitData('printf \'PID=%s\\n\' "$!"\r\n\x1b]133;D;130\x07dsh> ')
-    await vi.advanceTimersByTimeAsync(10)
-    expect(settled).toBe(false)
-
-    terminal.emitData('PID=123\r\n\x1b]133;D;0\x07dsh> ')
-    await vi.advanceTimersByTimeAsync(10)
-    const result = await successor.done
-    expect(result.waitReason).toBe('stdin_read')
-    expect(result.viewport).toContain('PID=123')
-  })
-
   it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From 7eedfda961d4e30e10b3d4756650bab402542d0f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 11:57:12 +0800
Subject: [PATCH 324/516] fix(pty): fence delayed signal prompts

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +--
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +--
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 16 +++++++++-
 packages/pty/pty-local/tests/session.spec.ts  | 29 +++++++++++++++++++
 8 files changed, 52 insertions(+), 9 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 02545da311..803a2f83fe 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 715529e5f24df0c2fe0afc40716737285afa223b
-2026-07-28-portable-execution-world-consumers.zh.md: a9d864b581bd546c12776152ad4515816ee6b83a
+2026-07-28-portable-execution-world-consumers.md: 54b8ec19bc74e734f2cb940a475d2c7b4c9336fd
+2026-07-28-portable-execution-world-consumers.zh.md: f21be00fd35267fe93e2fbb62642809cc42c0742
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 715529e5f2..54b8ec19bc 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; a timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index a9d864b581..f21be00fd3 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index c89122066a..3f21fb2bd3 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: 7e31adfbc486a190252be867e2113948b17e7924
-README.zh.md: eb628aef9ad6b0fea14a5e833197b4fac7856785
+README.md: c7b7a363f22821363a0fed81982165fd35326d12
+README.zh.md: 859b94e4f29b82abb298468f028f9eba7cc067e6
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 7e31adfbc4..c7b7a363f2 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,7 +8,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. After a signaled send returns `inferred_idle` without a prompt marker, the next marker remains attributed to that prior send and cannot settle a successor even when it follows the successor's echoed input. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
 Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index eb628aef9a..859b94e4f2 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,7 +8,7 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。在一次经过信号处理的 send 未出现提示符标记却返回 `inferred_idle` 后，下一个标记仍归属于该先前 send；即使该标记出现在后续 send 的输入回显之后，也不能使后续 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
 取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 922db21152..65a10c36ea 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -166,6 +166,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private readonly terminalOperations = new Set<Promise<void>>()
+  private signaledOperation: LocalSendOperation | undefined
   private interrupting: LocalSendOperation | undefined
   private writing: LocalSendOperation | undefined
   private pollingReady: LocalSendOperation | undefined
@@ -173,6 +174,7 @@ export class LocalPtySession implements PtyBackendSession {
   private promptSeen = false
   private promptTextSeen = false
   private promptTail = ''
+  private delayedSignaledPrompt = false
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
@@ -317,6 +319,7 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   async signal(signal: PtySignal): Promise<PtySignalResult> {
+    if (this.active !== undefined) this.signaledOperation = this.active
     const targetPgid = await this.terminal.signalForeground(signal)
     return { delivered: true, targetPgid }
   }
@@ -365,7 +368,9 @@ export class LocalPtySession implements PtyBackendSession {
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
-    if (sanitized.prompt) {
+    if (sanitized.prompt && this.delayedSignaledPrompt) {
+      this.delayedSignaledPrompt = false
+    } else if (sanitized.prompt) {
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
@@ -461,6 +466,13 @@ export class LocalPtySession implements PtyBackendSession {
   private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
+    // A signaled command can return by silence before bash emits its prompt.
+    // Reserve that marker so it cannot become successor readiness after echo.
+    const signaled = this.signaledOperation === operation
+    if (signaled) this.signaledOperation = undefined
+    if (waitReason === 'inferred_idle' && !this.promptSeen && signaled) {
+      this.delayedSignaledPrompt = true
+    }
     const scrollbackTruncated = this.scrollback.snapshot().truncated
     if (retainOwnership) {
       this.stopPolling()
@@ -486,6 +498,7 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeAbort?.()
     this.activeAbort = undefined
     if (this.interrupting === operation) this.interrupting = undefined
+    if (this.signaledOperation === operation) this.signaledOperation = undefined
     this.writing = undefined
     this.pollingReady = undefined
     this.active = undefined
@@ -506,6 +519,7 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
+    this.signaledOperation = operation
     this.interrupting = operation
     this.stopPolling()
     this.ownTerminalOperation(this.interruptOnce(operation))
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 513dcbbbb4..28ad58f04d 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -591,6 +591,35 @@ describe('LocalPtySession readiness and output', () => {
     expect(await operation.done).toMatchObject({ waitReason: 'stdin_read' })
   })
 
+  it('does not attribute a post-echo prompt from an inferred prior send to its successor', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config({ idleSilenceMs: 50, timeoutMs: 200 }))
+    await initialize(session, terminal)
+
+    const interrupted = session.startSend({ text: 'sleep', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await session.signal('SIGINT')
+    await vi.advanceTimersByTimeAsync(50)
+    expect((await interrupted.done).waitReason).toBe('inferred_idle')
+
+    const successor = session.startSend({ text: "printf 'PID=%s\\n' \"$!\"", submit: true })
+    let settled = false
+    void successor.done.then(() => { settled = true })
+    await Promise.resolve()
+    await Promise.resolve()
+    terminal.emitData('printf \'PID=%s\\n\' "$!"\r\n\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(settled).toBe(false)
+
+    terminal.emitData('PID=123\r\n\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    const result = await successor.done
+    expect(result.waitReason).toBe('stdin_read')
+    expect(result.viewport).toContain('PID=123')
+  })
+
   it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From 727546ce6d8cb4a12294d63da5f9cb43ee19443f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 12:59:49 +0800
Subject: [PATCH 325/516] fix(code-runtime): bound every subprocess frame hop

---
 packages/code-runtime/code-runtime-worker/src/runtime-host.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
index 474a058e9f..d2bb1082b8 100644
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -223,4 +223,5 @@ export class RuntimeOutputLedger {
 }
 
 export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
+export { jsonValueBytesUpTo } from './output-json.ts'
 export type { WorkerJsonWire } from './worker-json.ts'

From 045e8462ee5ba25d14e399060a4ccb3c40f89c5d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 13:00:12 +0800
Subject: [PATCH 326/516] fix(pty): drain public signals during close

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 ++--
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 ++--
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/session.ts         | 12 +++++++----
 packages/pty/pty-local/tests/session.spec.ts  | 20 +++++++++++++++++++
 8 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 803a2f83fe..fecaacac05 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 54b8ec19bc74e734f2cb940a475d2c7b4c9336fd
-2026-07-28-portable-execution-world-consumers.zh.md: f21be00fd35267fe93e2fbb62642809cc42c0742
+2026-07-28-portable-execution-world-consumers.md: fe9d7bdd38199a031989b093fd3e9d931d62c80a
+2026-07-28-portable-execution-world-consumers.zh.md: 9f4f38e6e4c6c7dba74e8de4c260ec633dade910
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 54b8ec19bc..fe9d7bdd38 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals after shutdown begins and drains public signals already in flight before returning.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index f21be00fd3..9f4f38e6e4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作开始后会拒绝新的公开信号，并在返回前等待所有已在途的公开信号结算。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 3f21fb2bd3..2bd653983e 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: c7b7a363f22821363a0fed81982165fd35326d12
-README.zh.md: 859b94e4f29b82abb298468f028f9eba7cc067e6
+README.md: bccef05ca73ec8d826621f814f232206fa9fea4b
+README.zh.md: 27d4d1193047eb1bb3bf2289697be3c0cc0253aa
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index c7b7a363f2..bccef05ca7 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -10,7 +10,7 @@ The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then reg
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. After a signaled send returns `inferred_idle` without a prompt marker, the next marker remains attributed to that prior send and cannot settle a successor even when it follows the successor's echoed input. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close starts provider-owned TERM-to-KILL whole-session cleanup and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close rejects new public signals after shutdown begins, drains public signals already in flight, starts provider-owned TERM-to-KILL whole-session cleanup, and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 859b94e4f2..27d4d11930 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -10,7 +10,7 @@
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。在一次经过信号处理的 send 未出现提示符标记却返回 `inferred_idle` 后，下一个标记仍归属于该先前 send；即使该标记出现在后续 send 的输入回显之后，也不能使后续 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作会在关闭开始后拒绝新的公开信号请求，等待已经在途的公开信号请求全部结算，再启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 65a10c36ea..08b42466aa 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -165,7 +165,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeTimer: NodeJS.Timeout | undefined
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
-  private readonly terminalOperations = new Set<Promise<void>>()
+  private readonly terminalOperations = new Set<Promise<unknown>>()
   private signaledOperation: LocalSendOperation | undefined
   private interrupting: LocalSendOperation | undefined
   private writing: LocalSendOperation | undefined
@@ -247,10 +247,13 @@ export class LocalPtySession implements PtyBackendSession {
 
   /** Retain one contained provider operation until its asynchronous work finishes. */
   private ownTerminalOperation(operation: Promise<void>): void {
+    void this.trackTerminalOperation(operation)
+  }
+
+  private trackTerminalOperation<T>(operation: Promise<T>): Promise<T> {
     const tracked = operation.finally(() => { this.terminalOperations.delete(tracked) })
     this.terminalOperations.add(tracked)
-    // beginSend(), pollReadiness(), and interrupt() contain their own boundary errors.
-    void tracked
+    return tracked
   }
 
   private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
@@ -319,8 +322,9 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   async signal(signal: PtySignal): Promise<PtySignalResult> {
+    if (this.closing) throw new Error('PTY session is closing')
     if (this.active !== undefined) this.signaledOperation = this.active
-    const targetPgid = await this.terminal.signalForeground(signal)
+    const targetPgid = await this.trackTerminalOperation(this.terminal.signalForeground(signal))
     return { delivered: true, targetPgid }
   }
 
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 28ad58f04d..dc03da2a63 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -952,6 +952,26 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     await expect(session.signal('SIGTERM')).rejects.toThrow('cannot resolve')
   })
 
+  it('drains an in-flight public signal and rejects signals after close starts', async () => {
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    const signal = Promise.withResolvers<number>()
+    terminal.signalForeground = async () => await signal.promise
+
+    const signaling = session.signal('SIGINT')
+    const closing = session.close('public signal')
+    let closed = false
+    void closing.then(() => { closed = true })
+    await Promise.resolve()
+    expect(closed).toBe(false)
+    await expect(session.signal('SIGTERM')).rejects.toThrow('closing')
+
+    signal.resolve(456)
+    await expect(signaling).resolves.toEqual({ delivered: true, targetPgid: 456 })
+    await closing
+    expect(closed).toBe(true)
+  })
+
   it('closes idempotently, contains signal races, and reports survivors', async () => {
     const terminal = new FakeTerminal()
     terminal.quiescent = false

From 4fecc549981ebb572ad25bed32b78aa123d0dd78 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 13:51:55 +0800
Subject: [PATCH 327/516] fix(runtime): close teardown gaps and simplify
 framing

---
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |  4 +-
 .../2026-07-15-lsp-capability-seam.md         |  2 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |  2 +-
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  6 +-
 ...8-portable-execution-world-consumers.zh.md |  6 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |  4 +-
 .../feature/2026-06-15-code-mode.md           |  2 +-
 .../feature/2026-06-15-code-mode.zh.md        |  2 +-
 packages/lsp/lsp-local/README.i18n.yaml       |  4 +-
 packages/lsp/lsp-local/README.md              |  2 +-
 packages/lsp/lsp-local/README.zh.md           |  2 +-
 packages/lsp/lsp-local/src/index.ts           | 41 ++++++++++---
 .../lsp/lsp-local/tests/lifecycle.spec.ts     | 59 +++++++++++++++++++
 .../subprocess-local/README.i18n.yaml         |  4 +-
 .../subprocess/subprocess-local/README.md     |  2 +-
 .../subprocess/subprocess-local/README.zh.md  |  2 +-
 .../subprocess-local/src/terminal.ts          |  6 +-
 .../subprocess-local/tests/terminal.spec.ts   | 42 +++++++++++++
 packages/typert/README.i18n.yaml              |  4 +-
 20 files changed, 164 insertions(+), 36 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index bba045d606..c2ed39b07d 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: 6e46fac0611c1b7282766cf57965a07e3ee6bb9b
-2026-07-15-lsp-capability-seam.zh.md: b535b60df70e8a6132bb1596581be3ab1daba932
+2026-07-15-lsp-capability-seam.md: 233a7321e1b4fded955144ed84fbc34df49e8964
+2026-07-15-lsp-capability-seam.zh.md: 547249fc22844878954fe7120dd8b5c87aabfc1a
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index 6e46fac061..233a7321e1 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -112,7 +112,7 @@ Provider disposal occurs outside tool execution, so `dsh-lsp-local` keeps `shutd
 
 ## Workspace, filesystem, and document synchronization
 
-`dsh-lsp-local` canonicalizes and reads through `ctx.fs` in the language server's execution world. It requires the workspace target to be a directory, rejects out-of-workspace sources through provider-owned containment, and uses `readTextBounded` so regular-file validation, UTF-8 decoding, the byte ceiling, and path replacement/growth safety stay one filesystem operation. It observes caller cancellation around each provider operation. It does not emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
+`dsh-lsp-local` canonicalizes and reads through `ctx.fs` in the language server's execution world. It requires the workspace target to be a directory, rejects out-of-workspace sources through provider-owned containment, and uses `readTextBounded` so regular-file validation, UTF-8 decoding, the byte ceiling, and path replacement/growth safety stay one filesystem operation. It fuses caller cancellation with provider disposal across each filesystem operation, tracks workspace lookups before they enter a queue, and awaits those lookups during disposal. It does not emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
 
 The `read` tool is unsuitable source because its output is windowed, numbered, transcript-visible, and observed. Reading in `tool-lsp` would also assign provider-specific synchronization to the consumer and preclude non-local providers.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index b535b60df7..547249fc22 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -112,7 +112,7 @@ interface LspToolInput {
 
 ## 工作区、文件系统与文档同步
 
-`dsh-lsp-local` 在语言服务器的执行环境中通过 `ctx.fs` 规范化并读取文件。它要求工作区目标是目录，使用提供方自有的 containment 拒绝工作区外的源文件，并通过 `readTextBounded` 把普通文件校验、UTF-8 解码、字节上限和路径替换／增长安全性保留在同一项文件系统操作中。它在每项提供方操作前后检查调用方是否取消。它不发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
+`dsh-lsp-local` 在语言服务器的执行环境中通过 `ctx.fs` 规范化并读取文件。它要求工作区目标是目录，使用提供方自有的 containment 拒绝工作区外的源文件，并通过 `readTextBounded` 把普通文件校验、UTF-8 解码、字节上限和路径替换／增长安全性保留在同一项文件系统操作中。它会针对每项文件系统操作合并调用方取消与提供方资源释放，跟踪尚未进入队列的工作区查找，并在资源释放期间等待这些查找结算。它不发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
 
 `read` 工具的输出带窗口与行号，进入 transcript（文本记录）且已被观察，不适合作为源文件。在 `tool-lsp` 内读取还会把提供方专用同步职责交给消费方，并排除非本地提供方。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index fecaacac05..de79bd2d8d 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: fe9d7bdd38199a031989b093fd3e9d931d62c80a
-2026-07-28-portable-execution-world-consumers.zh.md: 9f4f38e6e4c6c7dba74e8de4c260ec633dade910
+2026-07-28-portable-execution-world-consumers.md: e943c54a3f3a4c93a95db999d4c60790457ba644
+2026-07-28-portable-execution-world-consumers.zh.md: 7755791d5763436866763e8d4ea9e0fab8203bb9
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index fe9d7bdd38..e943c54a3f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -21,9 +21,9 @@ The subprocess interface owns the process coordinates and primitives: canonical
 Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
-- `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. Its JSON-RPC, pooling, synchronization, cancellation, and normalization stay unchanged.
+- `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals after shutdown begins and drains public signals already in flight before returning.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and the launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
@@ -45,4 +45,4 @@ A remote execution provider implements only its shared sandbox owner plus filesy
 
 The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers.
 
-The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal waits for exact PID-identity-fenced descendants retained during foreground inspection, Linux session members that survive top-level exit, and the top-level terminal process to reach quiescence. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer.
+The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal sweeps descendants before and after terminating the top-level shell, waits for exact PID-identity-fenced descendants retained during foreground inspection, and retains Linux session members that survive top-level exit. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 9f4f38e6e4..7755791d57 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -21,9 +21,9 @@ Status: implemented
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
-- `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。其 JSON-RPC、池化、同步、取消和规范化保持不变。
+- `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
 - `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作开始后会拒绝新的公开信号，并在返回前等待所有已在途的公开信号结算。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
@@ -45,4 +45,4 @@ Status: implemented
 
 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
 
-本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程、在顶层进程退出后仍存活的 Linux 会话成员，以及顶层终端进程完全停稳。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。
+本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会在终止顶层 shell 前后清理后代进程，等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程，并继续追踪在顶层进程退出后仍存活的 Linux 会话成员。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 42a11b8fb8..112e4eed83 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: b0778b2c9a8dfce8f786faccf6cc47f477c6b7c0
-2026-06-15-code-mode.zh.md: 437692eac3fc6740e0f1d4dd9001130fd6dd448a
+2026-06-15-code-mode.md: 1be25f5b145e50d8fe391d22910b71d85181582e
+2026-06-15-code-mode.zh.md: a4e8fbbd339899937c4f39091b4befbbb78ec347
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index b0778b2c9a..1be25f5b14 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -79,7 +79,7 @@ Requests contain every runtime input; implementations own validated timeout and
 5. **Enforce independent budgets.** `computeMs` meters worker busy time, allowing slow awaited tools without excusing a hot loop. `maxWallMs` bounds total elapsed time, including unresolved waits. `maxOutputBytes` bounds only the combined serialized outer logs, completion, or diagnostic; intermediate binding values have no byte cap. Expiry, cancellation, and completion terminate the worker, and heap exits or outer overflow are explicit failures.
 6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../../docs/defensive-patterns.md).
 
-`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded base64 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
+`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded newline-delimited UTF-8 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
 
 ### Trust posture
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index 437692eac3..a4e8fbbd33 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -79,7 +79,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
 6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
 
-`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界 base64 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
+`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界的、以换行符分隔的 UTF-8 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
 
 ### 信任姿态
 
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index e2b67d46d9..5a1036a349 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-local/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/lsp/lsp-local/README.md
-README.md: 299a5282bbca0a6d517af9342c4101cbdae33d4c
-README.zh.md: edf706fdb424756aa43b303b018b11e3764c2559
+README.md: c96c4febc9d047b41789f2b7a73e3eaf4d35012b
+README.zh.md: 5bc2c3c8bb7a89afb673797f5a3b25bb9fc06748
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index 299a5282bb..c96c4febc9 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -11,7 +11,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export).
 - Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes.
 - Lazily single-flights one server process per `(server id, canonical workspace target)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
 - Uses a compatibility-first **transient-open** sequence per query: resolve and boundedly read the source through `ctx.fs`, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
-- Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel.
+- Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel. Provider disposal aborts filesystem and protocol work, awaits workspace lookups that have not entered a queue, then drains every queue and server.
 - After protocol shutdown fails, terminates the server's descendant tree through the subprocess seam (POSIX process-group signaling; Windows `taskkill /T /F`). Tree-kill delivery is contained like every group signal — it races server exit — and quiescence is confirmed by the handle's tree-liveness wait rather than by the kill's own outcome.
 - Resolves the server executable, cwd, process, and protocol streams through `ctx.subprocess`; `initialize.processId` is `null` because another machine or PID namespace must not monitor the harness process.
 - Uses `ctx.fs` canonical containment, file URIs, and stable bounded reads, but emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index edf706fdb4..5bc2c3c8bb 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -11,7 +11,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
 - 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其释放，并在新进程上重试该查询一次。
 - 每次查询都使用兼容性优先的**临时打开** 序列：通过 `ctx.fs` 解析源文件并进行有界读取、`textDocument/didOpen`（版本 1、完整文本）、所请求操作，然后执行 `textDocument/didClose`，该操作位于 `finally` 中。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
-- 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。
+- 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方资源释放会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找结算，再排空所有队列并等待所有服务器结算。
 - 协议 shutdown 失败后，经由进程管理器 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
 - 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程与协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID 命名空间不得监控 harness 进程。
 - 使用 `ctx.fs` 提供的规范 containment、文件 URI 与稳定有界读取，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index 0d511588bd..f3f45959e5 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -208,6 +208,9 @@ class LocalLspProvider implements LspProvider {
   private readonly instances = new Map<WorkspaceKey, LspInstance>()
   /** One complete source-read→open→query→close serialization tail per canonical workspace. */
   private readonly queues = new Map<WorkspaceKey, Promise<void>>()
+  /** Workspace canonicalizations that have not entered a provider-owned queue yet. */
+  private readonly workspaceLookups = new Set<Promise<void>>()
+  private readonly lifetime = new AbortController()
   private disposed = false
 
   constructor(
@@ -234,32 +237,48 @@ class LocalLspProvider implements LspProvider {
     if (signal?.aborted) throw abortError(signal)
   }
 
+  /** Fuse caller cancellation with provider disposal for every filesystem and protocol await. */
+  private querySignal(signal?: AbortSignal): AbortSignal {
+    return signal === undefined
+      ? this.lifetime.signal
+      : AbortSignal.any([signal, this.lifetime.signal])
+  }
+
   async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
     // Honor an already-aborted signal before provider I/O so a canceled request never starts a server.
     this.assertActive(signal)
-    const workspace = await canonicalizeWorkspace(this.fs, request.workspaceRoot, signal)
-    this.assertActive(signal)
+    const querySignal = this.querySignal(signal)
+    const workspaceResult = canonicalizeWorkspace(this.fs, request.workspaceRoot, querySignal)
+    const workspaceLookup = workspaceResult.then(() => undefined, () => undefined)
+    this.workspaceLookups.add(workspaceLookup)
+    let workspace: HostWorkspace
+    try {
+      workspace = await workspaceResult
+    } finally {
+      this.workspaceLookups.delete(workspaceLookup)
+    }
+    this.assertActive(querySignal)
     const workspaceKey = workspace.target.targetKey
-    return this.enqueue(workspaceKey, signal, async () => {
-      this.assertActive(signal)
+    return this.enqueue(workspaceKey, querySignal, async () => {
+      this.assertActive(querySignal)
       // Read inside the workspace queue but before spawning: a queued query sees current bytes when
       // its turn starts, while an invalid source still cannot leave an idle process pooled.
-      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, querySignal)
       // Disposal may have snapshotted the instance map while host I/O was pending. Re-check before a
       // synchronous get-or-create so every spawned process remains owned by teardown.
-      this.assertActive(signal)
+      this.assertActive(querySignal)
       let instance = this.instanceFor(workspaceKey, workspace)
       try {
-        return await instance.query(request, source, signal)
+        return await instance.query(request, source, querySignal)
       } catch (error) {
         // A selected child can have died while idle or fail during the next write. Queries are
         // read-only, so replace that transport once and retry transparently.
         if (!instance.isTransportFailure(error)) throw error
         await instance.dispose()
         this.evictIfCurrent(workspaceKey, instance)
-        this.assertActive(signal)
+        this.assertActive(querySignal)
         instance = this.instanceFor(workspaceKey, workspace)
-        return await instance.query(request, source, signal)
+        return await instance.query(request, source, querySignal)
       } finally {
         // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check.
         if (instance.dead) {
@@ -320,13 +339,17 @@ class LocalLspProvider implements LspProvider {
   /** Dispose every live instance and block further queries. */
   async disposeAll(): Promise<void> {
     this.disposed = true
+    this.lifetime.abort(new LspError('lsp-local provider is disposed', 'LSP_DISPOSED'))
     const live = [...this.instances.values()]
     const draining = [...this.queues.values()]
+    const resolving = [...this.workspaceLookups]
     this.instances.clear()
     await Promise.all([
       ...live.map(instance => instance.dispose()),
       ...draining,
+      ...resolving,
     ])
     this.queues.clear()
+    this.workspaceLookups.clear()
   }
 }
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index ce92e2c8fb..0337b0fec2 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -301,6 +301,52 @@ describe('lsp-local end to end over a fake server', () => {
     await ctx.fiber.dispose()
   })
 
+  it('aborts and awaits a workspace lookup when the provider is disposed', async () => {
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' })
+    const fs = ctx.fs
+    const resolve = fs.resolve.bind(fs)
+    const started = Promise.withResolvers<AbortSignal>()
+    const release = Promise.withResolvers<undefined>()
+    vi.spyOn(fs, 'resolve').mockImplementation(async (path, options) => {
+      if (path !== ws) return await resolve(path, options)
+      const signal = options?.signal
+      if (signal === undefined) throw new Error('workspace lookup missing provider lifetime signal')
+      started.resolve(signal)
+      return await rejectWhenAborted(signal, release.promise)
+    })
+
+    const pending = ctx.lsp.query(query('goToDefinition'))
+    const signal = await started.promise
+    let disposed = false
+    const disposing = ctx.fiber.dispose().then(() => { disposed = true })
+    await new Promise<void>(resolve => setImmediate(resolve))
+
+    expect(signal.aborted).toBe(true)
+    expect(disposed).toBe(false)
+    release.resolve(undefined)
+    await expect(pending).rejects.toThrow('provider is disposed')
+    await expect(disposing).resolves.toBeUndefined()
+  })
+
+  it('aborts a queued source read when the provider is disposed', async () => {
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' })
+    const fs = ctx.fs
+    const started = Promise.withResolvers<AbortSignal>()
+    vi.spyOn(fs, 'readTextBounded').mockImplementation(async (_target, _maxBytes, signal) => {
+      if (signal === undefined) throw new Error('source read missing provider lifetime signal')
+      started.resolve(signal)
+      return await rejectWhenAborted(signal)
+    })
+
+    const pending = ctx.lsp.query(query('goToDefinition'))
+    const signal = await started.promise
+    const disposing = ctx.fiber.dispose()
+
+    await expect(pending).rejects.toThrow('provider is disposed')
+    await expect(disposing).resolves.toBeUndefined()
+    expect(signal.aborted).toBe(true)
+  })
+
   it('runs distinct workspaces in parallel instances', async () => {
     const ws2 = join(root, 'ws2')
     await mkdir(ws2)
@@ -358,3 +404,16 @@ async function waitFor(condition: () => Promise<boolean>, timeoutMs = 3000): Pro
     await new Promise<void>(resolve => setTimeout(resolve, 10))
   }
 }
+
+/** Hold one fake provider operation until cancellation, optionally behind a cleanup gate. */
+function rejectWhenAborted<T>(signal: AbortSignal, release: Promise<unknown> = Promise.resolve()): Promise<T> {
+  return new Promise((_resolve, reject) => {
+    const onAbort = (): void => {
+      void release.then(() => {
+        reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+      })
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    if (signal.aborted) onAbort()
+  })
+}
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index efbb1612bd..ded1d12b30 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: 61ee8ff9e09d5177ff6d5b3805dd84fb74c59961
-README.zh.md: 06a8e4bdd225e212aa67817ebbf66581314ab2bf
+README.md: 9f30fa6dc676e7b82f87b75b78b7d3143f204c94
+README.zh.md: 0b6813ec7d754f42e8bf4c65a1dee33d77bf3787
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 61ee8ff9e0..9f30fa6dc6 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -11,7 +11,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
 - **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal before any process-cleanup failure is reported, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
-- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and cleans descendants before the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
+- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
 ## Model Experience
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 06a8e4bdd2..0b6813ec7d 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -11,7 +11,7 @@
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
 - **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，会在资源释放时删除，并且删除发生在报告任何进程清理失败之前；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
-- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并先于顶层 shell 清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并在终止顶层 shell 前后清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
 - **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 2f1e4d4058..30e38bd422 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -193,11 +193,15 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private async closeOnce(): Promise<void> {
-    const survivors = await this.stopDescendants()
+    let survivors = await this.stopDescendants()
     if (survivors.length > 0) {
       throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
     }
     await this.stopShell()
+    survivors = await this.stopDescendants()
+    if (survivors.length > 0) {
+      throw new Error(`terminal cleanup failed; surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
+    }
     this.dataDisposable.dispose()
     this.exitDisposable.dispose()
   }
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
index 0202a3f33e..456ce4ee8f 100644
--- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -13,6 +13,7 @@ class FakePty {
   readonly kills: string[] = []
   autoExitOnKill = true
   throwKill = false
+  onKill?: () => void
   private readonly dataListeners = new Set<(data: string) => void>()
   private readonly exitListeners = new Set<(event: { exitCode: number; signal?: number }) => void>()
 
@@ -39,6 +40,7 @@ class FakePty {
   kill(signal?: string): void {
     if (this.throwKill) throw new Error('process raced')
     this.kills.push(signal ?? 'SIGHUP')
+    this.onKill?.()
     if (this.autoExitOnKill) this.emitExit(0, signal === 'SIGKILL' ? 9 : 15)
   }
 
@@ -213,6 +215,46 @@ describe('LocalTerminalHandle', () => {
     expect(pty.kills).toEqual(['SIGTERM'])
   })
 
+  it('sweeps a same-session descendant forked while the shell handles TERM', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const late = { pid: 124, started: 'shell-term-trap' }
+    pty.onKill = () => {
+      inspector.sessionMembers = [late]
+      inspector.alive.add(late.pid)
+    }
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+
+    handle.terminate()
+    await handle.waitForExit()
+
+    expect(inspector.processes).toEqual([[late.pid, 'SIGTERM']])
+    expect(pty.kills).toEqual(['SIGTERM'])
+  })
+
+  it('keeps a failed post-shell sweep retryable until its survivor leaves', async () => {
+    vi.useFakeTimers()
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const late = { pid: 124, started: 'shell-term-survivor' }
+    inspector.removeOnSignal = false
+    pty.onKill = () => {
+      inspector.sessionMembers = [late]
+      inspector.alive.add(late.pid)
+    }
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+
+    handle.terminate()
+    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pids: 124')
+    await vi.advanceTimersByTimeAsync(25)
+    await failed
+
+    inspector.alive.delete(late.pid)
+    handle.terminate()
+    expect(await handle.waitForExit()).toBe(true)
+    expect(inspector.processes).toEqual([[late.pid, 'SIGTERM'], [late.pid, 'SIGKILL']])
+  })
+
   it('retains captured descendants after reparenting', async () => {
     vi.useFakeTimers()
     const pty = new FakePty()
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index 13b8df9f71..7a36ab0690 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: fd8cfccdb333018e551459195564daad157d3867
-README.zh.md: b5b495e22bbf4328d82925cc793588ee45e5c6e4
+README.md: 38ee201a1754c6f50b7fae60b77af7dae734c8f9
+README.zh.md: 6fec39de550b7e3f57cd613dbe23c9687cd840ac

From c1d550de5809abea2a5db920c02396d412a1f013 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 18:26:21 +0800
Subject: [PATCH 328/516] refactor(runtime): collapse speculative portability
 layers

Remove the one-consumer bounded-read primitive and shared terminal lifecycle controller, make terminal cleanup one awaited provider operation, and reuse one Code Runtime contract suite. Keep only reproduced cancellation and policy fixes; defer unproven replacement, prompt-attribution, and streaming-frame concerns to scoped markers.
---
 ...06-17-filesystem-capability-seam.i18n.yaml |   4 +-
 .../2026-06-17-filesystem-capability-seam.md  |   4 +-
 ...026-06-17-filesystem-capability-seam.zh.md |   4 +-
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |   4 +-
 .../2026-07-15-lsp-capability-seam.md         |   8 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |   8 +-
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |  12 +-
 ...8-portable-execution-world-consumers.zh.md |  12 +-
 docs/config-catalog.md                        |   2 +-
 .../core-data-structures/filesystem.i18n.yaml |   4 +-
 docs/core-data-structures/filesystem.md       |   4 +-
 docs/core-data-structures/filesystem.zh.md    |   4 +-
 .../core-data-structures/subprocess.i18n.yaml |   4 +-
 docs/core-data-structures/subprocess.md       |   4 +-
 docs/core-data-structures/subprocess.zh.md    |   4 +-
 .../code-runtime-worker/src/runtime-host.ts   |   1 -
 .../code-runtime/tests/contract.ts            | 838 ++++++++++++++++++
 .../tests/workspace-context.spec.ts           |   6 -
 .../cordis/tool-cordis/src/api-catalog.ts     |   8 +-
 packages/fs/fs-local/README.i18n.yaml         |   4 +-
 packages/fs/fs-local/README.md                |   2 +-
 packages/fs/fs-local/README.zh.md             |   2 +-
 packages/fs/fs-local/src/fsio.ts              |  65 +-
 packages/fs/fs-local/src/index.ts             |   5 -
 packages/fs/fs-local/tests/filesystem.spec.ts |   9 -
 packages/fs/fs-local/tests/fsio.spec.ts       |  63 +-
 packages/fs/fs/README.i18n.yaml               |   4 +-
 packages/fs/fs/README.md                      |   9 +-
 packages/fs/fs/README.zh.md                   |   9 +-
 packages/fs/fs/src/index.ts                   |  17 +-
 packages/fs/fs/tests/service.spec.ts          |   5 -
 packages/fs/tool-fs/tests/tools.spec.ts       |   5 -
 packages/lsp/lsp-local/README.i18n.yaml       |   4 +-
 packages/lsp/lsp-local/README.md              |   6 +-
 packages/lsp/lsp-local/README.zh.md           |   6 +-
 packages/lsp/lsp-local/src/host.ts            |  26 +-
 packages/lsp/lsp-local/tests/host.spec.ts     |   6 +
 .../lsp/lsp-local/tests/lifecycle.spec.ts     |   9 +-
 packages/lsp/tool-lsp/src/render.ts           |  57 +-
 packages/lsp/tool-lsp/tests/render.spec.ts    |   1 +
 packages/pty/pty-local/README.i18n.yaml       |   4 +-
 packages/pty/pty-local/README.md              |   4 +-
 packages/pty/pty-local/README.zh.md           |   4 +-
 packages/pty/pty-local/src/index.ts           |  33 +-
 packages/pty/pty-local/src/session.ts         | 130 ++-
 packages/pty/pty-local/tests/index.spec.ts    |  13 +-
 packages/pty/pty-local/tests/session.spec.ts  | 285 +++---
 .../skill-local/tests/skill-local.spec.ts     |   6 -
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |   2 +-
 .../subprocess/subprocess-local/README.zh.md  |   2 +-
 .../subprocess/subprocess-local/src/index.ts  |  16 +-
 .../subprocess-local/src/terminal.ts          |  34 +-
 .../subprocess-local/tests/local.spec.ts      |  39 +-
 .../subprocess-local/tests/terminal.spec.ts   | 108 +--
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.md      |   3 +-
 packages/subprocess/subprocess/README.zh.md   |   3 +-
 packages/subprocess/subprocess/src/index.ts   |  13 +-
 .../subprocess/src/terminal-lifecycle.ts      | 104 ---
 packages/subprocess/subprocess/src/types.ts   |  17 +-
 .../subprocess/tests/service.spec.ts          |   3 +-
 .../tests/terminal-lifecycle.spec.ts          | 125 ---
 packages/typert/README.i18n.yaml              |   4 +-
 65 files changed, 1265 insertions(+), 948 deletions(-)
 create mode 100644 packages/code-runtime/code-runtime/tests/contract.ts
 delete mode 100644 packages/subprocess/subprocess/src/terminal-lifecycle.ts
 delete mode 100644 packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index dc9b924f54..ddb215be9f 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.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 .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
-2026-06-17-filesystem-capability-seam.md: 2fb360e5ad3c972f4a8de50c602a79af158dfc22
-2026-06-17-filesystem-capability-seam.zh.md: 1f70113b1583d890047ee4a17161f76b6390d8e8
+2026-06-17-filesystem-capability-seam.md: 7436d2a9402c76f17c7d6571eb489a86e550ebfb
+2026-06-17-filesystem-capability-seam.zh.md: fdeafba387b562352b377321327c526a67669ef6
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
index 2fb360e5ad..7436d2a940 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
@@ -64,7 +64,7 @@ The interface covers these semantic operations:
 - Resolve a model/plugin-supplied path into a backend-defined target.
 - Convert a resolved target to the canonical process path or `file:` URI for the same execution world, and test containment without parsing its opaque key.
 - Stat target metadata without reading file contents.
-- Read complete or streamed UTF-8 text, including one stable-handle byte-bounded whole-file operation.
+- Read complete or streamed UTF-8 text; consumers apply their own view and retention limits.
 - Create or replace a UTF-8 text file.
 - Edit an existing UTF-8 text file by literal replacement.
 
@@ -88,7 +88,7 @@ Resolved targets must expose at least three concepts:
 
 Read and mutation results must include an opaque file `version`. The local backend derives its token from bigint stat metadata (`dev`, `ino`, `size`, `mtimeNs`, and `ctimeNs`) so same-size rewrites and inode replacement invalidate consumers reliably; a remote backend can use a revision id or hash-like token. The `dsh-fs-policy` plugin records versions for stale checks; consumers may display related metadata but must not interpret the version token.
 
-The provider hands back decoded text: `readText` returns a whole regular text file, `streamText` streams the same text semantics for large files, and `readTextBounded` holds one backend-owned stable handle while rejecting a complete file above its byte ceiling. Line windowing, numbered-line rendering, and total-line accounting live in the executor (`dsh-tool-fs`). The provider owns regular-file checks, UTF-8 decoding, binary/NUL rejection, and the bounded read's replacement/growth race; it does not know about line windows or views.
+The provider hands back decoded text: `readText` returns a whole regular text file and `streamText` streams the same text semantics for large files or consumer-owned retention limits. Line windowing, byte ceilings, numbered-line rendering, and total-line accounting live in consumers such as `dsh-tool-fs` and `dsh-lsp-local`. The provider owns regular-file checks, UTF-8 decoding, and binary/NUL rejection; it does not know about line windows, protocol limits, or views.
 
 Observed-state recording is not on `ctx.fs`: after a successful read the executor emits `fs/observed`, and the `dsh-fs-policy` plugin records `{ version }` for the deriving owner. There is no `full`/`partial` view — a read at any window records the version, and freshness (not view completeness) authorizes a later write/edit.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
index 1f70113b15..fdeafba387 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -64,7 +64,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 - 将模型/插件提供的路径解析为后端定义的目标。
 - 将解析后的目标转换为同一执行环境的规范进程路径或 `file:` URI，并在不解析其不透明键的情况下检查包含关系。
 - 获取目标元数据而不读取文件内容。
-- 读取完整或流式 UTF-8 文本，其中包括一项持有稳定句柄、以字节为上限的全文件读取操作。
+- 读取完整或流式 UTF-8 文本；消费方执行各自的视图与保留上限。
 - 创建或替换一个 UTF-8 文本文件。
 - 通过字面替换编辑一个已有的 UTF-8 文本文件。
 
@@ -88,7 +88,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 读取和变更结果必须包含不透明的文件 `version`。本地后端从 bigint stat 元数据（`dev`、`ino`、`size`、`mtimeNs` 和 `ctimeNs`）派生令牌，因此同大小重写和 inode 替换都会可靠地使消费方失效；远程后端可以使用 revision id 或类似 hash 的令牌。`dsh-fs-policy` 插件记录版本用于陈旧检查；消费方可以展示相关元数据但禁止解释版本令牌。
 
-提供方返回已解码的文本：`readText` 返回整个常规文本文件，`streamText` 为大文件流式传输相同的文本语义，`readTextBounded` 则持有一个归后端所有的稳定句柄，并在完整文件超过字节上限时拒绝。行窗口化、带行号渲染和总行数统计位于执行器（`dsh-tool-fs`）中。提供方负责普通文件检查、UTF-8 解码、二进制/NUL 拒绝，以及有界读取期间的路径替换／增长竞态；它不知道行窗口或视图。
+提供方返回已解码的文本：`readText` 返回整个普通文本文件，`streamText` 为大文件或消费方自有的保留上限流式传输相同的文本语义。行窗口化、字节上限、带行号渲染和总行数统计归 `dsh-tool-fs`、`dsh-lsp-local` 等消费方所有。提供方负责普通文件检查、UTF-8 解码和二进制／NUL 拒绝；它不知道行窗口、协议上限或视图。
 
 观测状态记录不在 `ctx.fs` 上：成功读取后，执行器发出 `fs/observed`，`dsh-fs-policy` 插件为推导出的 owner 记录 `{ version }`。没有 `full`/`partial` 视图——任何窗口的读取都记录版本，新鲜度（而非视图完整性）授权后续的写入/编辑。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index c2ed39b07d..aac1c86e11 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: 233a7321e1b4fded955144ed84fbc34df49e8964
-2026-07-15-lsp-capability-seam.zh.md: 547249fc22844878954fe7120dd8b5c87aabfc1a
+2026-07-15-lsp-capability-seam.md: 63cec0a4e349ffc5be27a84e955b15e9168f898b
+2026-07-15-lsp-capability-seam.zh.md: cdb1289f6956d8a4e46ed92847ddd8a58e588afa
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index 233a7321e1..63cec0a4e3 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -112,13 +112,13 @@ Provider disposal occurs outside tool execution, so `dsh-lsp-local` keeps `shutd
 
 ## Workspace, filesystem, and document synchronization
 
-`dsh-lsp-local` canonicalizes and reads through `ctx.fs` in the language server's execution world. It requires the workspace target to be a directory, rejects out-of-workspace sources through provider-owned containment, and uses `readTextBounded` so regular-file validation, UTF-8 decoding, the byte ceiling, and path replacement/growth safety stay one filesystem operation. It fuses caller cancellation with provider disposal across each filesystem operation, tracks workspace lookups before they enter a queue, and awaits those lookups during disposal. It does not emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
+`dsh-lsp-local` canonicalizes and reads through `ctx.fs` in the language server's execution world. It requires the workspace target to be a directory, rejects out-of-workspace sources through provider-owned containment, consumes `streamText`, and enforces `maxDocumentBytes` as chunks arrive; the provider retains regular-file validation and UTF-8 decoding while the protocol consumer owns its document limit. It fuses caller cancellation with provider disposal across each filesystem operation, tracks workspace lookups before they enter a queue, and awaits those lookups during disposal. It does not emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy.
 
 The `read` tool is unsuitable source because its output is windowed, numbered, transcript-visible, and observed. Reading in `tool-lsp` would also assign provider-specific synchronization to the consumer and preclude non-local providers.
 
 The local provider uses a compatibility-first transient-open sequence for every query. It accepts legacy `textDocumentSync` `Full` or `Incremental`, or options with `openClose: true`; omitted, `None`, or explicitly incompatible synchronization fails as unsupported before `didOpen`.
 
-1. Resolve and contain the source through `ctx.fs`, then read its current bounded text through the same provider.
+1. Resolve and contain the source through `ctx.fs`, then stream its current text through the same provider while enforcing the document byte limit.
 2. Send `textDocument/didOpen` with version `1`, full text, and the configured language id. Its write remains abortable; failure or cancellation invalidates the instance and awaits bounded process termination before the pool can reuse it.
 3. Send the requested `textDocument/definition`, `textDocument/references`, `textDocument/implementation`, or `textDocument/hover` request.
 4. If `didOpen` succeeded, attempt `textDocument/didClose` in `finally` after the request settles or aborts. A close-write failure does not replace the settled result or error, but invalidates the instance and awaits bounded process termination.
@@ -157,7 +157,7 @@ The provider trusts its configured server. Its filesystem visibility and process
 
 **Wrap the signal in a per-seam execution-context object.** Web passes a bare `AbortSignal`; wrapping this single field would add unexplained asymmetry. `query()` gains a context object only when another field requires it.
 
-**Read through the model-facing `read` tool.** Rejected because tool output is windowed, numbered, transcript-visible, and observed. The provider reads bounded full text directly through the same `ctx.fs` execution world used by its subprocess.
+**Read through the model-facing `read` tool.** Rejected because tool output is windowed, numbered, transcript-visible, and observed. The provider consumes streamed full text directly through the same `ctx.fs` execution world used by its subprocess.
 
 **Keep documents open.** Mirroring edits requires version ownership, all-path `didChange`, HMR recovery, eviction, and stale-state rules. Transient opens avoid that MVP state machine.
 
@@ -195,4 +195,4 @@ Extension ownership is exclusive within one runtime. Two providers cannot both c
 
 UTF-16 cursor columns are exact for the protocol but difficult for a model to count around non-BMP characters. Invalid or off-symbol positions may produce empty results, so error text and prompt examples must explain the coordinate convention without encouraging broad LSP use.
 
-The paired filesystem/subprocess providers align the query snapshot with the server index but do not make a trusted language server safe. Canonical containment rejects query sources outside the workspace; the server itself receives the execution world's configured authority and may read other paths or use caches.
+The paired filesystem/subprocess providers align the query snapshot with the server index but do not make a trusted language server safe. Canonical containment rejects query sources outside the workspace at resolution time, but stream opening does not add stable-handle identity across a concurrent path replacement; the server itself receives the execution world's configured authority and may read other paths or use caches.
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index 547249fc22..cdb1289f69 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -112,13 +112,13 @@ interface LspToolInput {
 
 ## 工作区、文件系统与文档同步
 
-`dsh-lsp-local` 在语言服务器的执行环境中通过 `ctx.fs` 规范化并读取文件。它要求工作区目标是目录，使用提供方自有的 containment 拒绝工作区外的源文件，并通过 `readTextBounded` 把普通文件校验、UTF-8 解码、字节上限和路径替换／增长安全性保留在同一项文件系统操作中。它会针对每项文件系统操作合并调用方取消与提供方资源释放，跟踪尚未进入队列的工作区查找，并在资源释放期间等待这些查找结算。它不发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
+`dsh-lsp-local` 在语言服务器的执行环境中通过 `ctx.fs` 规范化并读取文件。它要求工作区目标是目录，使用提供方自有的 containment 拒绝工作区外的源文件，消费 `streamText`，并在分片到达时执行 `maxDocumentBytes` 上限；普通文件校验和 UTF-8 解码仍由提供方负责，文档上限则由协议消费方负责。它会针对每项文件系统操作合并调用方取消与提供方资源释放，跟踪尚未进入队列的工作区查找，并在资源释放期间等待这些查找结算。它不发送 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足写前读取策略。
 
 `read` 工具的输出带窗口与行号，进入 transcript（文本记录）且已被观察，不适合作为源文件。在 `tool-lsp` 内读取还会把提供方专用同步职责交给消费方，并排除非本地提供方。
 
 本地提供方对每次查询都采用兼容优先的临时打开流程。它接受旧式 `textDocumentSync` 的 `Full` 或 `Incremental`，也接受设置了 `openClose: true` 的选项；同步能力缺失、为 `None` 或明确不兼容时，在 `didOpen` 前以不支持错误失败。
 
-1. 通过 `ctx.fs` 解析源文件并检查其位于工作区内，再通过同一提供方对当前文本进行有界读取。
+1. 通过 `ctx.fs` 解析源文件并检查其位于工作区内，再通过同一提供方流式读取当前文本，同时执行文档字节上限。
 2. 发送 `textDocument/didOpen`，其中包含版本 `1`、完整文本和配置的语言 id。该写入仍可取消；写入失败或遭取消会使实例失效，并等待有界进程终止完成，池才能复用它。
 3. 发送所请求的 `textDocument/definition`、`textDocument/references`、`textDocument/implementation` 或 `textDocument/hover` 请求。
 4. 如果 `didOpen` 成功，则在请求完成或取消后于 `finally` 中尝试发送 `textDocument/didClose`。关闭写入失败不会覆盖已经确定的结果或错误，但会使实例失效，并等待有界进程终止完成。
@@ -157,7 +157,7 @@ interface LspToolInput {
 
 **将信号包装为每服务边界的执行上下文对象。** Web 传递裸 `AbortSignal`；仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时，`query()` 才引入上下文对象。
 
-**通过面向模型的 `read` 工具读取。**拒绝，因为工具输出带窗口与行号，会进入 transcript 且已被观察。提供方直接通过子进程所用的同一 `ctx.fs` 执行环境读取有界的完整文本。
+**通过面向模型的 `read` 工具读取。**拒绝，因为工具输出带窗口与行号，会进入 transcript 且已被观察。提供方直接通过子进程所用的同一 `ctx.fs` 执行环境消费流式传输的完整文本。
 
 **保持文档打开。** 镜像编辑需要版本归属、覆盖所有路径的 `didChange`、HMR 恢复、淘汰和陈旧状态规则。临时打开避免在 MVP 引入这套状态机。
 
@@ -195,4 +195,4 @@ interface LspToolInput {
 
 UTF-16 光标列与协议完全一致，但模型难以在包含非 BMP 字符的文本中准确计数。无效位置或不在符号上的位置可能返回空结果，因此错误文本和提示词示例必须说明坐标约定，同时避免鼓励模型广泛使用 LSP。
 
-配对的文件系统／子进程提供方会对齐查询快照与服务器索引，但不会因此使受信任的语言服务器变得安全。规范 containment 会拒绝工作区外的查询源；服务器本身获得执行环境所配置的权限，仍可读取其他路径或使用缓存。
+配对的文件系统／子进程提供方会对齐查询快照与服务器索引，但不会因此使受信任的语言服务器变得安全。规范 containment 会在解析时拒绝工作区外的查询源，但打开流不会在路径并发替换期间额外保证稳定句柄身份；服务器本身获得执行环境所配置的权限，仍可读取其他路径或使用缓存。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index de79bd2d8d..7b6a74b7e8 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: e943c54a3f3a4c93a95db999d4c60790457ba644
-2026-07-28-portable-execution-world-consumers.zh.md: 7755791d5763436866763e8d4ea9e0fab8203bb9
+2026-07-28-portable-execution-world-consumers.md: d68fc92308079aa68a8f4e1accadde0addb0e5aa
+2026-07-28-portable-execution-world-consumers.zh.md: 5341cf1643cabb1043b977e18179dc857e37e121
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index e943c54a3f..d68fc92308 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -14,16 +14,16 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all
 
 `ctx.fs` and `ctx.subprocess` together define one execution world. Providers mounted together must describe the same path namespace, executables, processes, and terminal sessions; higher capabilities consume those two interfaces rather than name the provider.
 
-The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, containment, and a bounded stable-handle text read. The existing text and mutation operations remain filesystem-owned.
+The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, and containment. Existing whole and streaming text operations remain filesystem-owned; protocol consumers enforce their own retention limits while consuming the stream.
 
-The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns byte I/O, foreground groups, signalling, TERM-to-KILL session cleanup, and a quiescence wait. The interface package also exports a provider-neutral lifecycle controller that joins top-level settlement, lifetime cancellation, retryable provider cleanup, and bounded quiescence observation; each implementation supplies only its session-cleanup transaction. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches whole-session quiescence. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
 
 Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. The allocation signal is detached before publication, while readiness initialization retains setup cancellation. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation until asynchronous foreground signalling settles, so the signal cannot target a successor; if a signaled send returns `inferred_idle` before its prompt arrives, that marker remains attributed to the prior send instead of settling a successor after its echo. A timed-out asynchronous write, or a signal failure during that write, retains the reservation until the provider settles the write. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals after shutdown begins and drains public signals already in flight before returning.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before serialization, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals and delegates complete-session quiescence to the handle's awaited termination operation.
+- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. The fixed runner is adapter-owned infrastructure below `ctx.subprocess.runtimeRoot`, so its write carries an explicit `danger-full-access` policy instead of inheriting the model-facing filesystem mode. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
@@ -35,6 +35,10 @@ Generic consumers use that execution world:
 
 **Move PTY readiness and session policy into the subprocess service.** Rejected because those are persistent-terminal consumer semantics, not OS process mechanics. A subprocess provider owns what only its substrate can do; `dsh-pty-local` owns what a Harness terminal means.
 
+**Expose separate terminal termination and quiescence operations plus a shared lifecycle controller.** Rejected because every terminal consumer needs the same single cleanup outcome. Separate operations export provider bookkeeping, bounded-observer, and retry semantics without a production consumer; one awaited provider operation is a deeper interface.
+
+**Add a stable bounded-read primitive to the filesystem seam.** Rejected because only LSP needs a complete-document byte ceiling, which it can enforce while consuming the existing text stream. A second primitive forces every provider to implement stable-handle and no-follow mechanics, including a remote helper protocol, without an observed concurrent-replacement defect.
+
 **Delete the worker-thread Code Runtime.** Rejected because portability does not erase its current deployment need. The subprocess backend requires a Node executable and filesystem materialization; the worker backend has neither requirement and remains the supported single-process path.
 
 **Run the whole harness inside the remote environment.** Rejected as a different deployment model. Making execution capabilities portable does not move model calls, session state, plugin state, or the agent loop.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 7755791d57..5341cf1643 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -14,16 +14,16 @@ Status: implemented
 
 `ctx.fs` 与 `ctx.subprocess` 共同定义一个执行世界。共同挂载的提供方必须描述相同的路径命名空间、可执行文件、进程和终端会话；上层能力消费这两个接口，而不引用具体提供方。
 
-文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI、包含关系，以及通过稳定句柄执行的有界文本读取。现有文本与变更操作仍归文件系统负责。
+文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责字节 I/O、前台进程组管理、信号发送、TERM→KILL 会话清理以及等待完全停稳。接口包还导出一个提供方无关的生命周期控制器，用于组合顶层结算、生命周期取消、可重试的提供方清理与有界的完全停稳观测；每个实现只需提供自身的会话清理事务。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使整个会话完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。分配信号会在发布前解除关联，而就绪初始化仍保留设置阶段的取消。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会保留发送预留，直至异步前台信号发送结算，从而使该信号无法把后续发送作为目标；如果收到信号的 send 在其提示符到达前返回 `inferred_idle`，随后到达的标记仍归属于先前的 send，而不会在后续 send 回显后使其完成。异步写入超时，或该写入期间发生信号发送失败，都会保留预留，直至提供方将写入结算。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作开始后会拒绝新的公开信号，并在返回前等待所有已在途的公开信号结算。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在序列化前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
@@ -35,6 +35,10 @@ Status: implemented
 
 **把 PTY 就绪判断与会话策略移入进程管理服务。** 不予采纳，因为这些属于持久终端消费方的语义，而非 OS 进程机制。进程管理提供方负责只有其执行基底才能完成的操作；`dsh-pty-local` 负责 Harness 终端的语义。
 
+**分别公开终端终止与完全停稳操作，并提供共享生命周期控制器。** 不予采纳，因为每个终端消费方都需要相同的单一清理结果。拆分操作会把提供方簿记、有界观察者和重试语义暴露出来，却没有生产消费方；由提供方提供一个须等待的操作，接口更深。
+
+**在文件系统 seam 中新增稳定的有界读取原语。** 不予采纳，因为只有 LSP 需要完整文档字节上限，而它可以在消费现有文本流时执行该上限。第二项原语会迫使每个提供方实现稳定句柄和不跟随符号链接的机制，远程提供方甚至需要辅助协议，却没有已观察到的并发替换缺陷。
+
 **删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件和文件系统物化，而 worker 后端两者都不需要，并且仍是受支持的单进程路径。
 
 **在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop（智能体循环）。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index c07e81089c..b70f468960 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -447,7 +447,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/fs/fs-local/src/index.ts:40`](../packages/fs/fs-local/src/index.ts)
+Source: [`packages/fs/fs-local/src/index.ts:39`](../packages/fs/fs-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-fs-sandbox`
 
diff --git a/docs/core-data-structures/filesystem.i18n.yaml b/docs/core-data-structures/filesystem.i18n.yaml
index 129c5569b9..78386c54fd 100644
--- a/docs/core-data-structures/filesystem.i18n.yaml
+++ b/docs/core-data-structures/filesystem.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 docs/core-data-structures/filesystem.md
-filesystem.md: 50b936bdef7535769f19d6cc0a75eb11eea9a869
-filesystem.zh.md: 61a885203b0718b34b0fd936c318b03c65ce4770
+filesystem.md: addded9f673ed435e95109d4fb772967514c0b87
+filesystem.zh.md: 3ef16ede1e137d2a1310861941ac3244ca105650
diff --git a/docs/core-data-structures/filesystem.md b/docs/core-data-structures/filesystem.md
index 50b936bdef..addded9f67 100644
--- a/docs/core-data-structures/filesystem.md
+++ b/docs/core-data-structures/filesystem.md
@@ -52,7 +52,7 @@ type FsTargetKey = Branded<'FsTargetKey'>
 type FsVersion = Branded<'FsVersion'>
 ```
 
-`stat` returns metadata (never content), or `undefined` when the target is absent. `type` lets the tool reject directories/special files before reading, and `size` lets it choose `readText` vs `streamText` without probing by failure. Protocol consumers use `readTextBounded(target, maxBytes)` when size validation and the complete UTF-8 read must remain one backend-owned stable operation; composing `stat` with `readText` would admit growth and replacement races.
+`stat` returns metadata (never content), or `undefined` when the target is absent. `type` lets the tool reject directories/special files before reading, and `size` lets it choose `readText` vs `streamText` without probing by failure. A protocol consumer that needs a byte ceiling applies it while consuming `streamText`, so the filesystem seam needs no consumer-specific bounded-read primitive.
 
 ```ts type-equiv
 /**
@@ -258,4 +258,4 @@ type FsErrorCode =
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `readTextBounded`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
diff --git a/docs/core-data-structures/filesystem.zh.md b/docs/core-data-structures/filesystem.zh.md
index 6b7642b3f7..1e378928ed 100644
--- a/docs/core-data-structures/filesystem.zh.md
+++ b/docs/core-data-structures/filesystem.zh.md
@@ -52,7 +52,7 @@ type FsTargetKey = Branded<'FsTargetKey'>
 type FsVersion = Branded<'FsVersion'>
 ```
 
-`stat` 返回元数据（从不返回内容），目标不存在时返回 `undefined`。`type` 让工具在读取前拒绝目录或特殊文件；`size` 让工具无需通过失败探测即可选择 `readText` 还是 `streamText`。当大小校验与完整 UTF-8 读取必须保持为一个由后端负责的稳定操作时，协议消费方使用 `readTextBounded(target, maxBytes)`；组合 `stat` 与 `readText` 会容许文件增长与替换竞态。
+`stat` 返回元数据（从不返回内容），目标不存在时返回 `undefined`。`type` 让工具在读取前拒绝目录或特殊文件；`size` 让工具无需通过失败探测即可选择 `readText` 还是 `streamText`。需要字节上限的协议消费方在消费 `streamText` 时执行该上限，因此文件系统 seam 无需消费方专用的有界读取原语。
 
 ```ts type-equiv
 /**
@@ -258,4 +258,4 @@ type FsErrorCode =
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`readTextBounded`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。生成的 wiring 目录在 [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam) 中展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。生成的 wiring 目录在 [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam) 中展示确切的 `ctx.fs` 签名。
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index fca7947aae..7cba3857bb 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: eae497530ff54a7a259c23a2d0f665f3313488f5
-subprocess.zh.md: c3504ef7cd42448a15341f7f92d0f309a6216de1
+subprocess.md: 89c75aea3393a000612e3b8f87d263c7b4fa7c60
+subprocess.zh.md: 83fb44f4750ba31db1f4336c0c293eb9e236be22
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index c866276b8e..d6e0105c59 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -240,9 +240,9 @@ interface SubprocessOutcome {
 
 ## Terminal-process primitive
 
-`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns raw UTF-8 byte transport, foreground-process-group inspection and signalling, TERM-to-KILL cleanup, and whole-session quiescence. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
+`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches whole-session quiescence. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
 
-The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, `terminate`, and `waitForExit`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam).
+The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam).
 
 ## Service behavior
 
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index c3504ef7cd..83fb44f475 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -240,9 +240,9 @@ interface SubprocessOutcome {
 
 ## 终端进程原语
 
-`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责原始 UTF-8 字节传输、前台进程组检查与信号发送、TERM→KILL 清理，以及整个会话的完全停稳。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
+`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使整个会话完全停稳。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
 
-终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground`、`terminate` 和 `waitForExit`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam)中。
+终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam)中。
 
 ## 服务行为
 
diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
index d2bb1082b8..474a058e9f 100644
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -223,5 +223,4 @@ export class RuntimeOutputLedger {
 }
 
 export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
-export { jsonValueBytesUpTo } from './output-json.ts'
 export type { WorkerJsonWire } from './worker-json.ts'
diff --git a/packages/code-runtime/code-runtime/tests/contract.ts b/packages/code-runtime/code-runtime/tests/contract.ts
new file mode 100644
index 0000000000..f28545f8c1
--- /dev/null
+++ b/packages/code-runtime/code-runtime/tests/contract.ts
@@ -0,0 +1,838 @@
+import { describe, expect, it } from 'vitest'
+import type {
+  CodeBindingFunction,
+  CodeBindingNamespace,
+  CodeRunResult,
+  CodeRuntime,
+} from '@deepseek-ai/dsh-code-runtime'
+
+interface WorkerCodeRuntimeContractConfig {
+  computeMs?: number
+  maxWallMs?: number
+  maxOutputBytes?: number
+  maxOldGenerationSizeMb?: number
+}
+
+interface WorkerCodeRuntimeContractHarness {
+  runtime: CodeRuntime
+  dispose: () => Promise<void>
+}
+
+type WorkerCodeRuntimeContractSetup = (
+  config?: WorkerCodeRuntimeContractConfig,
+) => Promise<WorkerCodeRuntimeContractHarness>
+
+/** Convenience: one namespace `tools` with the given functions. */
+export function workerRuntimeTools(
+  functions: Record<string, (args: unknown) => Promise<unknown>>,
+): CodeBindingNamespace[] {
+  return [{
+    global: 'tools',
+    functions: functions as Record<string, CodeBindingFunction>,
+    errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
+  }]
+}
+
+/** Run behavior shared by the direct and subprocess-hosted worker runtimes. */
+export function runWorkerCodeRuntimeContract(
+  label: string,
+  setup: WorkerCodeRuntimeContractSetup,
+): void {
+  describe(`${label} — programs and bindings (real workers)`, () => {
+    it('registers with the seam descriptors', async () => {
+      const { runtime } = await setup()
+      expect(runtime.language).toBe('typescript')
+      expect(runtime.isolation).toBe('worker-thread')
+    })
+
+    it('runs TypeScript (erasable syntax), captures output in order, returns the value', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          interface Point { x: number; y: number }
+          const p: Point = { x: 1, y: 2 } as Point;
+          console.log('point', p);
+          process.stdout.write('raw-out\\n');
+          console.warn('careful');
+          return p.x + p.y;
+        `,
+        bindings: [],
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe(3)
+      expect(result.logs).toEqual(['point { x: 1, y: 2 }', 'raw-out\n', 'careful'])
+    })
+
+    it('bridges binding calls both ways and rejects the program-side call on a host rejection', async () => {
+      const { runtime } = await setup()
+      const calls: unknown[] = []
+      const result = await runtime.run({
+        program: `
+          const first = await tools.echo({ n: 1 });
+          let caught = {};
+          try { await tools.fail({}) } catch (error) { caught = { isTyped: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message } }
+          let caughtRaw = {};
+          try { await tools.failRaw({}) } catch (error) { caughtRaw = { name: error.name, toolName: error.toolName, message: error.message } }
+          return { first, caught, caughtRaw };
+        `,
+        bindings: workerRuntimeTools({
+          echo: async (args) => { calls.push(args); return { echoed: args } },
+          fail: async () => { throw new Error('nope') },
+          // A non-Error throw: the host renders it, the program still catches.
+          failRaw: async () => { throw 'raw-nope' },
+        }),
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toEqual({
+        first: { echoed: { n: 1 } },
+        caught: { isTyped: true, name: 'ToolCallError', toolName: 'fail', message: 'nope' },
+        caughtRaw: { name: 'ToolCallError', toolName: 'failRaw', message: 'raw-nope' },
+      })
+      expect(calls).toEqual([{ n: 1 }])
+    })
+
+    it('materializes a typed rejection from a generic namespace descriptor', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          try { await helpers.fail({}) } catch (error) {
+            return {
+              isTyped: error instanceof HelperCallError,
+              name: error.name,
+              helperName: error.helperName,
+              message: error.message,
+            };
+          }
+        `,
+        bindings: [{
+          global: 'helpers',
+          functions: { fail: async () => { throw new Error('nope') } },
+          errorClass: { name: 'HelperCallError', memberNameProperty: 'helperName' },
+        }],
+      })
+      expect(result.value).toEqual({
+        isTyped: true,
+        name: 'HelperCallError',
+        helperName: 'fail',
+        message: 'nope',
+      })
+    })
+
+    it('bridges a deeply nested lossless JSON argument, resolution, and completion', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          let value = 'leaf';
+          for (let depth = 0; depth < 3_000; depth++) value = [value];
+          return await tools.echo(value);
+        `,
+        bindings: workerRuntimeTools({ echo: async args => args }),
+      })
+
+      expect(result.error).toBeUndefined()
+      let cursor = result.value
+      for (let depth = 0; depth < 3_000; depth++) {
+        expect(Array.isArray(cursor)).toBe(true)
+        cursor = Array.isArray(cursor) ? cursor[0] : undefined
+      }
+      expect(cursor).toBe('leaf')
+    }, 15_000)
+
+    it('reports non-erasable syntax as an exception without spawning a worker', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'enum E { A }\nreturn 1', bindings: [] })
+      expect(result.error?.kind).toBe('exception')
+      expect(result.error?.message).toMatch(/enum|strip/i)
+    })
+
+    it('reports a runtime throw as an exception with the message', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'throw new Error("kaboom")', bindings: [] })
+      expect(result.error?.kind).toBe('exception')
+      expect(result.error?.message).toContain('kaboom')
+    })
+
+    it('gives the program an EMPTY environment', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'return JSON.stringify(process.env)', bindings: [] })
+      expect(result.value).toBe('{}')
+    })
+
+    it('rejects a non-lossless completion instead of replacing it with rendered text', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'return { f: () => 1 }', bindings: [] })
+      expect(result.value).toBeUndefined()
+      expect(result.error).toEqual({ kind: 'invalid-output', message: 'program completion must be lossless JSON' })
+    })
+
+    it('completes a program that returns nothing with no value at all', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'const x = 1', bindings: [] })
+      expect(result.error).toBeUndefined()
+      expect('value' in result).toBe(false)
+    })
+
+    it('keeps logs streamed before a failure', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: 'console.log("before"); throw new Error("after-log")',
+        bindings: [],
+      })
+      expect(result.error?.kind).toBe('exception')
+      expect(result.logs).toContain('before')
+    })
+  })
+
+  describe(`${label} — budgets and containment (real workers)`, () => {
+    it('ends a hot loop at the compute budget — including behind a pending decoy dispatch', async () => {
+      const { runtime } = await setup({ computeMs: 300, maxWallMs: 30_000 })
+      const result = await runtime.run({
+        // The decoy: fire a call at a never-resolving binding WITHOUT awaiting,
+        // then spin. Host-side pending-call bookkeeping would pause a naive
+        // budget here; measured busy time cannot be fooled.
+        program: 'void tools.slow({}); for (;;) {}',
+        bindings: workerRuntimeTools({ slow: () => new Promise(() => {}) }),
+      })
+      expect(result.error?.kind).toBe('timeout')
+      expect(result.error?.message).toContain('compute budget')
+    }, 15_000)
+
+    it('does not charge time spent awaiting a slow binding against the compute budget', async () => {
+      // Keep the binding delay above the compute allowance while leaving enough
+      // headroom for worker bootstrap on loaded CI hosts.
+      const { runtime } = await setup({ computeMs: 1_000, maxWallMs: 30_000 })
+      const result = await runtime.run({
+        program: 'return await tools.slow({})',
+        bindings: workerRuntimeTools({ slow: () => new Promise(resolve => setTimeout(() => { resolve('slow-done') }, 1_500)) }),
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('slow-done')
+    }, 15_000)
+
+    it('ends an idle-forever run at the wall-clock ceiling', async () => {
+      const { runtime } = await setup({ computeMs: 30_000, maxWallMs: 400 })
+      const result = await runtime.run({
+        program: 'await tools.never({}); return 1',
+        bindings: workerRuntimeTools({ never: () => new Promise(() => {}) }),
+      })
+      expect(result.error?.kind).toBe('timeout')
+      expect(result.error?.message).toContain('wall-clock ceiling')
+    }, 15_000)
+
+    it('reports an abort mid-run and stops the worker', async () => {
+      const { runtime } = await setup()
+      const controller = new AbortController()
+      setTimeout(() => { controller.abort('user-cancel') }, 150)
+      const result = await runtime.run({ program: 'for (;;) {}', bindings: [], signal: controller.signal })
+      expect(result.error).toEqual({ kind: 'abort', message: 'user-cancel' })
+    }, 15_000)
+
+    it('reports a pre-aborted signal without spawning', async () => {
+      const { runtime } = await setup()
+      const controller = new AbortController()
+      controller.abort('too-late')
+      const result = await runtime.run({ program: 'return 1', bindings: [], signal: controller.signal })
+      expect(result.error).toEqual({ kind: 'abort', message: 'too-late' })
+    })
+
+    it('applies the outer-output cap to failures before worker startup', async () => {
+      const capped = await setup({ maxOutputBytes: 64 })
+      const controller = new AbortController()
+      controller.abort('A'.repeat(1_000))
+      const aborted = await capped.runtime.run({ program: 'return 1', bindings: [], signal: controller.signal })
+      expect(aborted).toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' } })
+
+      const minimal = await setup({ maxOutputBytes: 4 })
+      const invalid = await minimal.runtime.run({ program: 'enum E { A }\nreturn 1', bindings: [] })
+      expect(invalid.error?.kind).toBe('output-limit')
+      expect(Buffer.byteLength(JSON.stringify(invalid.logs), 'utf8') + Buffer.byteLength(JSON.stringify(invalid.error?.message), 'utf8')).toBeLessThanOrEqual(4)
+    })
+
+    it('drops a binding resolution that lands after the run settled', async () => {
+      const { runtime } = await setup()
+      const controller = new AbortController()
+      let replyDelivered!: Promise<void>
+      const result = await runtime.run({
+        program: 'void tools.late({}); for (;;) {}',
+        bindings: workerRuntimeTools({
+          // Anchored on invocation: abort 100ms after the call reaches the
+          // host, resolve 400ms after — by then the run has settled, so the
+          // resolution's reply hits the post-settlement drop.
+          late: () => new Promise((resolve) => {
+            setTimeout(() => { controller.abort('cancel-now') }, 100)
+            replyDelivered = new Promise(done => setTimeout(() => { resolve('too-late'); done() }, 400))
+          }),
+        }),
+        signal: controller.signal,
+      })
+      expect(result.error).toEqual({ kind: 'abort', message: 'cancel-now' })
+      // Let the late resolution actually fire so its reply executes instead of
+      // being cancelled with the test.
+      await replyDelivered
+    }, 15_000)
+
+    it('contains an OOM under resourceLimits as worker-exit, host process healthy', async () => {
+      const { runtime } = await setup({ maxOldGenerationSizeMb: 32 })
+      const result = await runtime.run({
+        program: 'const hog = []; for (;;) hog.push(new Array(1e6).fill(1));',
+        bindings: [],
+      })
+      expect(result.error?.kind).toBe('worker-exit')
+      // And the host is fine: run something else.
+      const after = await runtime.run({ program: 'return "alive"', bindings: [] })
+      expect(after.value).toBe('alive')
+    }, 30_000)
+
+    it('reports a worker that exits before publishing a completion', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'process.exit(7)', bindings: [] })
+      expect(result).toEqual({
+        logs: [],
+        error: { kind: 'worker-exit', message: 'worker exited with code 7 before completing' },
+      })
+    })
+
+    it('fails runaway log output explicitly while retaining a bounded prefix', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 300 })
+      const result = await runtime.run({
+        program: 'for (let i = 0; i < 1000; i++) console.log("spam line", i); return 1',
+        bindings: [],
+      })
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 300 bytes' })
+      expect(result.value).toBeUndefined()
+      expect(result.logs.length).toBeGreaterThan(0)
+      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')).toBeLessThan(300)
+    })
+
+    it('retains a fitting prefix when one oversized log is the first output', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 96 })
+      const result = await runtime.run({
+        program: 'console.log(`start-${`😀"\\\\\\n`.repeat(100)}`); return null',
+        bindings: [],
+      })
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 96 bytes' })
+      expect(result.logs).toHaveLength(1)
+      expect(result.logs[0]?.startsWith('start-')).toBe(true)
+      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')
+        + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(96)
+    })
+
+    it('fails an oversized return value without substituting a string', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 64 })
+      const result = await runtime.run({ program: 'return "y".repeat(10_000)', bindings: [] })
+      expect(result.value).toBeUndefined()
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 64 bytes' })
+    })
+
+    it('uses UTF-8 serialized bytes at the exact completion boundary', async () => {
+      const exact = await setup({ maxOutputBytes: 7 })
+      const exactResult = await exact.runtime.run({ program: 'return "€"', bindings: [] })
+      // [] costs two bytes and JSON serialization of "€" costs five.
+      expect(exactResult).toEqual({ logs: [], value: '€' })
+
+      const over = await setup({ maxOutputBytes: 6 })
+      const overResult = await over.runtime.run({ program: 'return "€"', bindings: [] })
+      expect(overResult.error?.kind).toBe('output-limit')
+    })
+
+    it('accounts logs and completion in one exact combined ledger', async () => {
+      // JSON(["abc"]) is seven bytes and JSON("xy") is four.
+      const exact = await setup({ maxOutputBytes: 11 })
+      expect(await exact.runtime.run({ program: 'console.log("abc"); return "xy"', bindings: [] }))
+        .toEqual({ logs: ['abc'], value: 'xy' })
+
+      const over = await setup({ maxOutputBytes: 10 })
+      const result = await over.runtime.run({ program: 'console.log("abc"); return "xy"', bindings: [] })
+      expect(result.value).toBeUndefined()
+      expect(result.error?.kind).toBe('output-limit')
+      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8') + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(10)
+    })
+
+    it('accounts logs and exception diagnostics before the worker port boundary', async () => {
+      // JSON(["abc"]) is seven bytes and JSON("xy") is four.
+      const exact = await setup({ maxOutputBytes: 11 })
+      expect(await exact.runtime.run({ program: 'console.log("abc"); throw "xy"', bindings: [] }))
+        .toEqual({ logs: ['abc'], error: { kind: 'exception', message: 'xy' } })
+
+      const over = await setup({ maxOutputBytes: 10 })
+      const result = await over.runtime.run({ program: 'console.log("abc"); throw "xy"', bindings: [] })
+      expect(result.error?.kind).toBe('output-limit')
+      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')
+        + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(10)
+    })
+
+    it('does not send a giant Error stack across the worker port', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 64 })
+      const result = await runtime.run({
+        program: 'throw new Error("x".repeat(1_000_000))',
+        bindings: [],
+      })
+      expect(result).toEqual({
+        logs: [],
+        error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
+      })
+    })
+
+    it('completes a program that awaits its write callback, capturing the chunk', async () => {
+      // Node's write(chunk[, encoding][, callback]) contract: dropping the
+      // callback would leave this promise pending until the wall ceiling and
+      // misreport a completed program as a timeout.
+      const { runtime } = await setup({ maxWallMs: 2_000 })
+      const result = await runtime.run({
+        program: 'await new Promise(resolve => process.stdout.write("flushed", resolve)); return "done"',
+        bindings: [],
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('done')
+      expect(result.logs).toContain('flushed')
+    })
+
+    it('returns a large JSON container exactly when the outer cap permits it', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'return new Array(50_000).fill(7)', bindings: [] })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toEqual(new Array(50_000).fill(7))
+    })
+
+    it('returns an exact completion at the default 64 MiB combined boundary', async () => {
+      const { runtime } = await setup()
+      // [] costs two bytes and the JSON string contributes two quotes, leaving
+      // exactly this many payload bytes under the 67_108_864-byte default.
+      const result = await runtime.run({ program: 'return "x".repeat(67_108_860)', bindings: [] })
+      expect(result.error).toBeUndefined()
+      expect(result.logs).toEqual([])
+      expect(result.value).toHaveLength(67_108_860)
+    }, 60_000)
+
+    it('fails one byte over the default 64 MiB combined boundary', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({ program: 'return "x".repeat(67_108_861)', bindings: [] })
+      expect(result.value).toBeUndefined()
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 67108864 bytes' })
+    }, 60_000)
+
+    it('drains pipe output queued before terminal worker teardown completes', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 200_000 })
+      const payload = `late-pipe-${'x'.repeat(100_000)}`
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          const write = (text) => Object.getPrototypeOf(process.stdout).write.call(process.stdout, text);
+          write('late-pipe-' + 'x'.repeat(100_000));
+          parentPort.postMessage({ type: 'done', value: ['done'] });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('done')
+      expect(result.logs.join('') === payload).toBe(true)
+    }, 15_000)
+  })
+
+  describe(`${label} — hostile programs (real workers)`, () => {
+    it('survives forged port traffic: unknown binding names, duplicate ids, junk shapes', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'call', id: 7777, global: 'tools', name: 'missing', args: {} });
+          parentPort.postMessage({ type: 'call', id: 7777, global: 'tools', name: 'missing', args: {} });
+          parentPort.postMessage({ type: 'call', id: 7778, global: 'tools', name: 'constructor', args: {} });
+          parentPort.postMessage({ type: 'junk' });
+          return await tools.real({});
+        `,
+        bindings: workerRuntimeTools({ real: async () => 'still-works' }),
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('still-works')
+    })
+
+    it('survives arbitrary junk on the port: non-objects, junk types, malformed calls, logs, and dones', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          for (const junk of [
+            null, 42, 'junk', [],
+            { type: 'nope' },
+            { type: 'call' },
+            { type: 'call', id: 'x', global: 'tools', name: 'real', args: {} },
+            { type: 'call', id: 1e9, global: 7, name: 'real', args: {} },
+            { type: 'call', id: 1e9, global: 'tools', name: 7, args: {} },
+            { type: 'log' },
+            { type: 'log', text: null },
+            { type: 'log', text: 7 },
+            { type: 'log', text: {} },
+            { type: 'done', error: 5 },
+            { type: 'done', error: { kind: 'exception', message: 5 } },
+            { type: 'done', error: { kind: 'invented', message: 'bad kind' } },
+          ]) parentPort.postMessage(junk);
+          return await tools.real({});
+        `,
+        bindings: workerRuntimeTools({ real: async () => 'still-works' }),
+      })
+      expect(result.error).toBeUndefined()
+      expect(result.value).toBe('still-works')
+      expect(result.logs).toEqual([])
+    })
+
+    it('fails forged log floods and forged done values through the same outer cap', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 200 })
+      const result = await runtime.run({
+        // Forged messages bypass worker-side capture and completion checks;
+        // the outer ledger must still contain them.
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          for (let i = 0; i < 50; i++) parentPort.postMessage({ type: 'log', text: 'F'.repeat(100), forged: true });
+          parentPort.postMessage({ type: 'done', value: ['V'.repeat(100000)] });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result.value).toBeUndefined()
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 200 bytes' })
+      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')).toBeLessThan(200)
+    })
+
+    it('re-caps an oversized forged done value at the host boundary', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 64 })
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'done', value: ['V'.repeat(100_000)] });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result).toEqual({
+        logs: [],
+        error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
+      })
+    })
+
+    it('drops a malformed forged done carrying both value and error', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'done', value: 'lied', error: { kind: 'exception', message: 'fake failure' } });
+          return 'honest';
+        `,
+        bindings: [],
+      })
+      expect(result).toEqual({ logs: [], error: { kind: 'exception', message: 'fake failure' } })
+    })
+
+    it('contains a deeply nested forged completion without overflowing the host meter', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          const value = [];
+          for (let depth = 0; depth < 3_000; depth++) value.push({ kind: 'array', length: 1 });
+          value.push(null);
+          setTimeout(() => { parentPort.postMessage({ type: 'done', value }) }, 25);
+          // Prevent bootstrap's normal undefined completion from racing the forged terminal.
+          await new Promise(() => {});
+        `,
+        bindings: [],
+      })
+      expect(result.error).toBeUndefined()
+      let value = result.value
+      let depth = 0
+      while (Array.isArray(value)) {
+        expect(value).toHaveLength(1)
+        value = value[0]
+        depth += 1
+      }
+      expect(depth).toBe(3_000)
+      expect(value).toBeNull()
+    }, 15_000)
+
+    it('turns forged over-limit error text into output-limit at the host', async () => {
+      const { runtime } = await setup({ maxOutputBytes: 64 })
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'done', error: { kind: 'exception', message: '€'.repeat(1000) } });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 64 bytes' })
+    })
+
+    it('answers a binding whose resolution is not lossless JSON with a typed failure reply', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
+        bindings: workerRuntimeTools({ bad: async () => (() => 1) }),
+      })
+      expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
+    })
+
+    it('rejects lossy binding arguments in the worker before invoking the host binding', async () => {
+      const { runtime } = await setup()
+      let calls = 0
+      const result = await runtime.run({
+        program: `
+          const decorated = [1]; Object.defineProperty(decorated, 'extra', { value: true });
+          const values = [new Date(), decorated, () => 1];
+          const failures = [];
+          for (const value of values) {
+            try { await tools.never(value) } catch (error) {
+              failures.push({ typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message });
+            }
+          }
+          return failures;
+        `,
+        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
+      })
+      expect(calls).toBe(0)
+      expect(result.value).toEqual(new Array(3).fill({
+        typed: true,
+        name: 'ToolCallError',
+        toolName: 'never',
+        message: 'binding arguments must be lossless JSON',
+      }))
+    })
+
+    it('rejects intrinsic-looking exotic objects as arguments and completions', async () => {
+      const { runtime } = await setup()
+      let calls = 0
+      const forgeObject = `
+        const prototype = Object.create(null);
+        const SpoofedObject = function Object() {};
+        SpoofedObject.prototype = prototype;
+        Object.defineProperty(prototype, 'constructor', { value: SpoofedObject });
+        const forged = Object.assign(Object.create(prototype), { value: 1 });
+        Function.prototype.toString = () => 'function Object() { [native code] }';
+      `
+      const argument = await runtime.run({
+        program: `${forgeObject}
+          try { await tools.never(forged) } catch (error) {
+            return { typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message };
+          }
+        `,
+        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
+      })
+      expect(calls).toBe(0)
+      expect(argument.value).toEqual({
+        typed: true,
+        name: 'ToolCallError',
+        toolName: 'never',
+        message: 'binding arguments must be lossless JSON',
+      })
+
+      const completion = await runtime.run({ program: `${forgeObject}\nreturn forged`, bindings: [] })
+      expect(completion).toEqual({
+        logs: [],
+        error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' },
+      })
+    })
+
+    it('preserves binding and completion JSON after model code mutates boundary globals', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const arrayPrototype = Array.prototype;
+          const objectPrototype = Object.prototype;
+          const setPrototype = Set.prototype;
+          const stringPrototype = String.prototype;
+          Array.isArray = () => false;
+          arrayPrototype.at = arrayPrototype.includes = arrayPrototype.pop = arrayPrototype.push = () => { throw new Error('mutated array method') };
+          Object.defineProperty = Object.getOwnPropertyDescriptor = Object.getPrototypeOf = Object.keys = () => { throw new Error('mutated object method') };
+          Object.hasOwn = () => false;
+          Object.is = () => true;
+          objectPrototype.propertyIsEnumerable = () => false;
+          Number.isFinite = Number.isSafeInteger = () => false;
+          Reflect.apply = Reflect.ownKeys = () => { throw new Error('mutated reflect method') };
+          setPrototype.add = setPrototype.delete = setPrototype.has = () => { throw new Error('mutated set method') };
+          stringPrototype.charCodeAt = stringPrototype.codePointAt = stringPrototype.slice = () => { throw new Error('mutated string method') };
+          Buffer.byteLength = () => 0;
+          Function.prototype.toString = () => 'mutated';
+          objectPrototype.get = () => undefined;
+          objectPrototype.constructor = arrayPrototype.constructor = null;
+          globalThis.Array = globalThis.Buffer = globalThis.Error = globalThis.Function = globalThis.Number = globalThis.Object = globalThis.Reflect = globalThis.Set = globalThis.String = undefined;
+          const echoed = await tools.echo({ request: ['€', 1] });
+          let failure;
+          try { await tools.fail({}) } catch (error) {
+            failure = { typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message };
+          }
+          return { echoed, failure, completion: { ok: true, amount: 42 } };
+        `,
+        bindings: workerRuntimeTools({ echo: async args => args, fail: async () => { throw new Error('nope') } }),
+      })
+      expect(result).toEqual({
+        logs: [],
+        value: {
+          echoed: { request: ['€', 1] },
+          failure: { typed: true, name: 'ToolCallError', toolName: 'fail', message: 'nope' },
+          completion: { ok: true, amount: 42 },
+        },
+      })
+    })
+
+    it('rejects forged lossy binding arguments again at the host boundary', async () => {
+      const { runtime } = await setup()
+      let calls = 0
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          const forged = (id, args) => new Promise((resolve) => {
+            const receive = (message) => {
+              if (message?.type !== 'reply' || message.id !== id) return;
+              parentPort.off('message', receive);
+              resolve(message);
+            };
+            parentPort.on('message', receive);
+            parentPort.postMessage({ type: 'call', id, global: 'tools', name: 'never', args });
+          });
+          const sparse = []; sparse.length = 1;
+          const cycle = {}; cycle.self = cycle;
+          return await Promise.all([
+            forged(8001, new Date()),
+            forged(8002, -0),
+            forged(8003, sparse),
+            forged(8004, cycle),
+          ]);
+        `,
+        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
+      })
+      expect(calls).toBe(0)
+      expect(result.value).toEqual([8001, 8002, 8003, 8004].map(id => ({
+        type: 'reply',
+        id,
+        ok: false,
+        message: 'binding arguments must be lossless JSON',
+      })))
+    })
+
+    it('contains throwing getters while snapshotting binding resolutions', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
+        bindings: workerRuntimeTools({ bad: async () => Object.defineProperty({}, 'bad', { enumerable: true, get() { throw new Error('getter exploded') } }) }),
+      })
+      expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
+    })
+
+    it('revalidates a forged lossy completion at the host boundary', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'done', value: -0 });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result).toEqual({ logs: [], error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' } })
+    })
+
+    it('honors a forged worker-side output-limit signal', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          parentPort.postMessage({ type: 'output-limit' });
+          for (;;) {}
+        `,
+        bindings: [],
+      })
+      expect(result).toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 67108864 bytes' } })
+    })
+
+    it('exposes binding names that collide with Object.prototype as ordinary functions', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: 'return [await tools["__proto__"]({}), await tools["constructor"]({}), typeof tools["hasOwnProperty"]]',
+        // Computed keys: a literal `'__proto__': …` entry would SET the record's
+        // prototype instead of declaring a binding of that name.
+        bindings: workerRuntimeTools({ ['__proto__']: async () => 'proto-ok', ['constructor']: async () => 'ctor-ok' }),
+      })
+      expect(result.value).toEqual(['proto-ok', 'ctor-ok', 'undefined'])
+    })
+  })
+
+  describe(`${label} — seam misuse and lifecycle`, () => {
+    it('rejects invalid and duplicate binding globals loudly', async () => {
+      const { runtime } = await setup()
+      const cases: [string, RegExp][] = [
+        ['not valid!', /not a usable identifier/],
+        ['await', /not a usable identifier/],
+        ['console', /duplicate binding global/],
+      ]
+      for (const [global, message] of cases) {
+        await expect(runtime.run({ program: 'return 1', bindings: [{ global, functions: {} }] })).rejects.toThrow(message)
+      }
+      await expect(runtime.run({
+        program: 'return 1',
+        bindings: [{ global: 'tools', functions: {} }, { global: 'tools', functions: {} }],
+      })).rejects.toThrow(/duplicate binding global/)
+
+      await expect(runtime.run({
+        program: 'return typeof ToolCallError',
+        bindings: [{ global: 'ToolCallError', functions: {} }],
+      })).resolves.toMatchObject({ value: 'object' })
+    })
+
+    it('rejects malformed or colliding binding error-class declarations', async () => {
+      const { runtime } = await setup()
+      const run = async (bindings: CodeBindingNamespace[]) => await runtime.run({ program: 'return 1', bindings })
+      const namespace = (global: string, name: string, memberNameProperty = 'memberName'): CodeBindingNamespace => ({
+        global,
+        functions: {},
+        errorClass: { name, memberNameProperty },
+      })
+
+      await expect(run([namespace('tools', 'not valid!')])).rejects.toThrow(/error class.*not a usable identifier/)
+      await expect(run([namespace('tools', 'await')])).rejects.toThrow(/error class.*not a usable identifier/)
+      await expect(run([namespace('tools', 'console')])).rejects.toThrow(/duplicate injected global/)
+      await expect(run([namespace('tools', 'tools')])).rejects.toThrow(/duplicate injected global/)
+      await expect(run([
+        namespace('tools', 'CallError'),
+        namespace('helpers', 'CallError'),
+      ])).rejects.toThrow(/duplicate injected global/)
+      await expect(run([namespace('tools', 'CallError', '')])).rejects.toThrow(/member property.*not usable/)
+      await expect(run([namespace('tools', 'CallError', 'message')])).rejects.toThrow(/member property.*not usable/)
+    })
+
+    it('rejects config values that are not positive numbers', async () => {
+      await expect(setup({ computeMs: -1 })).rejects.toThrow(/positive number/)
+    })
+
+    it('rejects a maxWallMs above Node\'s maximum timer delay', async () => {
+      // setTimeout clamps a delay past 2^31-1 ms to 1 ms, so the positivity check
+      // alone would accept a 25-day ceiling that expires on the first tick.
+      await expect(setup({ maxWallMs: 2_147_483_648 }))
+        .rejects.toThrow(/maxWallMs must be at most 2147483647/)
+      // The boundary itself is usable.
+      await expect(setup({ maxWallMs: 2_147_483_647 })).resolves.toBeTruthy()
+    })
+
+    it('requires maxOutputBytes to fit the smallest counted outer payloads', async () => {
+      await expect(setup({ maxOutputBytes: 3 })).rejects.toThrow(/safe integer of at least 4/)
+      await expect(setup({ maxOutputBytes: 4.5 })).rejects.toThrow(/safe integer of at least 4/)
+    })
+
+    it('keeps runs isolated: no state survives from one run to the next', async () => {
+      const { runtime } = await setup()
+      await runtime.run({ program: 'globalThis.leak = "value"; return 1', bindings: [] })
+      const second = await runtime.run({ program: 'return typeof globalThis.leak', bindings: [] })
+      expect(second.value).toBe('undefined')
+    })
+
+    it('disposal aborts in-flight runs, awaits worker exit, and rejects later runs', async () => {
+      const { runtime, dispose } = await setup()
+      const inflight: Promise<CodeRunResult> = runtime.run({ program: 'for (;;) {}', bindings: [] })
+      // Give the worker a moment to actually start spinning.
+      await new Promise(resolve => setTimeout(resolve, 200))
+      await dispose()
+      const result = await inflight
+      expect(result.error).toEqual({ kind: 'abort', message: 'runtime disposed' })
+      await expect(runtime.run({ program: 'return 1', bindings: [] })).rejects.toThrow(/after disposal/)
+    }, 15_000)
+  })
+}
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 8620c38981..fcdcd7c422 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -117,12 +117,6 @@ class RecordingFileSystem extends FileSystem {
     return this.entries.get(target.targetKey)?.content ?? ''
   }
 
-  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
-    const text = await this.readText(target, signal)
-    if (Buffer.byteLength(text) > maxBytes) throw new Error('too large')
-    return text
-  }
-
   override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     if (signal !== undefined) this.signals.push(signal)
     signal?.throwIfAborted()
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index c7b6df254e..2eb410acc6 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -336,10 +336,6 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>',
         jsDoc: '/**\n * Read the whole regular text file as a single decoded string.\n * @param target - the resolved target to read.\n * @param signal - aborts the read.\n * @returns the full decoded UTF-8 content.\n */',
       },
-      {
-        signature: 'abstract readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string>',
-        jsDoc: '/**\n * Read one regular UTF-8 text file through a backend-owned stable handle,\n * rejecting before more than `maxBytes` are retained. The size check and\n * bytes read are one operation: a caller must not emulate this with\n * {@link stat} followed by {@link readText}, which admits growth and path\n * replacement races between the two calls.\n * @param target - the resolved target to read.\n * @param maxBytes - positive safe-integer byte ceiling.\n * @param signal - aborts the open/read operation.\n * @returns the complete decoded text when it fits.\n */',
-      },
       {
         signature: 'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>',
         jsDoc: '/**\n * Stream the whole regular text file as decoded text chunks (same text\n * semantics as {@link readText}, for large files). The backend owns\n * cross-chunk UTF-8 decoding and binary rejection so the policy layer never\n * touches raw bytes.\n * @param target - the resolved target to read.\n * @param signal - aborts the stream, including between chunks.\n * @returns the chunk iterable, decoded and validated like {@link readText}.\n */',
@@ -1000,7 +996,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>',
-        jsDoc: '/**\n * Allocate a real terminal and start one owned process session. This is the\n * only non-pipe process primitive: implementations own terminal byte I/O,\n * foreground groups, signals, and complete session-tree cleanup.\n * @param spec - fully specified argv, cwd, environment, dimensions, grace, and cancellation.\n * @returns the live terminal handle after allocation succeeds.\n */',
+        jsDoc: '/**\n * Allocate a real terminal and start one owned process session. This is the\n * only non-pipe process primitive: implementations own terminal byte I/O,\n * foreground groups, signals, and complete session-tree cleanup.\n * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.\n * @returns the live terminal handle after allocation succeeds.\n */',
       },
     ],
   },
@@ -2909,7 +2905,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SubprocessTerminalHandle',
-    declaration: 'export interface SubprocessTerminalHandle {\n    readonly pid: number;\n    readonly output: Readable;\n    readonly done: Promise<SubprocessOutcome>;\n    write(data: Uint8Array): Promise<void>;\n    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;\n    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;\n    terminate(): void;\n    waitForExit(signal?: AbortSignal): Promise<boolean>;\n}',
+    declaration: 'export interface SubprocessTerminalHandle {\n    readonly pid: number;\n    readonly output: Readable;\n    readonly done: Promise<SubprocessOutcome>;\n    write(data: string): Promise<void>;\n    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;\n    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;\n    terminate(): Promise<void>;\n}',
   },
   {
     name: 'SubprocessTerminalSignal',
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index 57d2a32f97..e1870cbf41 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-local/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/fs/fs-local/README.md
-README.md: f5cf2441adcd62e55c6169ceb766f88382e314f5
-README.zh.md: 40f5a83626780bae8f335c80662721bae6cc0b0b
+README.md: fe0e5e9dec07fad745d6bea28da9009e517c7d85
+README.zh.md: 195f3963328035e9c6c382dd924cd04ee9e8c642
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index f5cf2441ad..fe0e5e9dec 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -17,7 +17,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. `opts.signal` is checked before and after local resolution, while a remote sibling backend may use it to abort its round-trip. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
 - **Execution-world coordinates** — `processPath` exposes the target's canonical host path, `fileUrl` encodes that path through Node's platform-aware URL conversion, and `contains` uses platform path semantics to test identity or descendant containment without consumers parsing `targetKey`.
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
-- **`readText` / `readTextBounded` / `streamText`** — UTF-8 only. `readText` reads the whole file; `readTextBounded` opens one no-follow, nonblocking handle, verifies it is regular, and retains at most `maxBytes + 1` bytes so growth cannot bypass the cap; `streamText` decodes chunks so a huge file need not be held whole in memory. All reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing; protocol consumers such as the LSP host use the stable bounded operation.
+- **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` decodes chunks so a huge file need not be held whole in memory and consumers can enforce their own retention bounds. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
 - **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 40f5a83626..195f396332 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -17,7 +17,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`resolve(path, opts?)`**：相对 `path` 在调用方提供 `opts.cwd` 时以该值为基准解析（面向模型的工具会传入调用 agent（智能体）的会话 cwd；见[每会话 cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)），否则以 `config.cwd` 为基准（默认 `process.cwd()`）；绝对 `path` 会忽略两者。`opts.signal` 会在本地解析前后检查，远程同级后端则可以用它中止往返。`targetKey` 是文件的 `realpath`，因此经符号链接到达同一文件的两个输入路径会共享一个身份，写入/编辑落在链接目标上，同时保留链接。尚不存在的路径在父目录存在时使用 realpath 后的父目录加 basename；只有父目录无法解析时才回退到绝对路径。`displayPath` 是绝对但未经解析的路径。
 - **执行世界坐标**：`processPath` 公开目标的规范化宿主路径，`fileUrl` 通过 Node 的平台感知 URL 转换对该路径编码，`contains` 则使用平台路径语义检查身份相等或后代包含关系，消费方无需解析 `targetKey`。
 - **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此飞行中的中止会报告 `FS_ABORTED`，而非陈旧的不存在结果。
-- **`readText` / `readTextBounded` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`readTextBounded` 打开一个不跟随符号链接的非阻塞句柄，确认其为普通文件，并最多保留 `maxBytes + 1` 字节，使文件增长无法绕过上限；`streamText` 按分片解码，因此超大文件无需整体保存在内存中。三者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑；LSP 主机等协议消费方使用稳定的有界操作。
+- **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片解码，因此超大文件无需整体保存在内存中，消费方也可以执行各自的保留上限。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑。
 - **`listDir`**：按稳定的 `name.localeCompare()` 顺序列出一层目录。每个条目携带子项 basename、类型、解析后的子目标（`displayPath` 位于所列目录下，`targetKey` 是 realpath 身份）和低成本 stat 元数据（`version`，普通文件另有 `size`）。它绝不会打开或解码文件内容。缺失目标报告 `FS_NOT_FOUND`，文件/特殊文件目标报告 `FS_NOT_DIRECTORY`，已中止调用报告 `FS_ABORTED`，权限失败报告 `FS_PERMISSION_DENIED`，其他列出或子项元数据 I/O 失败报告 `FS_IO_ERROR`。损坏/消失的子项以无元数据的 `other` 返回，但解析子项时出现权限/I/O 失败会让整个列表以结构化 `FsError` 失败。
 - **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内。完成写入和 fsync 后，以 rename 覆盖目标。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 创建缺失目标并拒绝现有目标（`FS_NOT_OBSERVED`）；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
 - **`editText`**：在同一原语之上依次执行原子的字面量读取、修改和写入，并通过变更锁按目标串行化。`expected` 防护是可选的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index e95cb14cca..4925357e45 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -6,7 +6,7 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { constants, createReadStream } from 'node:fs'
+import { createReadStream } from 'node:fs'
 import { chmod, lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
 import type { BigIntStats, Dirent, Stats } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
@@ -377,69 +377,6 @@ export async function readWholeText(target: LocalTarget, signal?: AbortSignal):
  * @param signal - aborts between handle operations.
  * @returns the complete decoded text when it fits.
  */
-export async function readWholeTextBounded(
-  target: LocalTarget,
-  maxBytes: number,
-  signal?: AbortSignal,
-): Promise<string> {
-  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
-    throw new Error('bounded read maxBytes must be a positive safe integer')
-  }
-  throwIfAborted(signal, 'read')
-  let handle: Awaited<ReturnType<typeof open>>
-  try {
-    handle = await open(
-      target.targetKey,
-      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
-    )
-  } catch (error: unknown) {
-    if (isENOENT(error)) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND', { cause: error })
-    if (isPermissionError(error)) throw new FsError(`cannot read "${target.displayPath}": permission denied`, 'FS_PERMISSION_DENIED', { cause: error })
-    throw new FsError(`cannot read "${target.displayPath}" safely: ${errorMessage(error)}`, 'FS_IO_ERROR', { cause: error })
-  }
-  try {
-    throwIfAborted(signal, 'read')
-    const info = await handle.stat()
-    if (!info.isFile()) {
-      throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
-    }
-    if (info.size > maxBytes) {
-      throw new FsError(
-        `cannot read "${target.displayPath}": ${info.size} bytes exceeds the ${maxBytes}-byte limit`,
-        'FS_IO_ERROR',
-      )
-    }
-    const chunks: Buffer[] = []
-    let total = 0
-    for (;;) {
-      throwIfAborted(signal, 'read')
-      // Allocate in fixed internal chunks so a permissive deployment cap does
-      // not reserve that entire cap for a small file. Once exactly at the
-      // bound, one final byte detects concurrent growth without retaining it.
-      const remaining = total === maxBytes ? 1 : Math.min(64 * 1024, maxBytes - total)
-      const chunk = Buffer.allocUnsafe(remaining)
-      const { bytesRead } = await handle.read(chunk, 0, chunk.length, total)
-      if (bytesRead === 0) break
-      total += bytesRead
-      if (total > maxBytes) {
-        throw new FsError(
-          `cannot read "${target.displayPath}": file grew past the ${maxBytes}-byte limit while reading`,
-          'FS_IO_ERROR',
-        )
-      }
-      chunks.push(chunk.subarray(0, bytesRead))
-    }
-    throwIfAborted(signal, 'read')
-    const bytes = chunks.length === 1 ? chunks[0] as Buffer : Buffer.concat(chunks, total)
-    if (bytes.subarray(0, BINARY_SAMPLE_BYTES).includes(0)) {
-      throw new FsError(`cannot read "${target.displayPath}": binary file`, 'FS_NOT_TEXT')
-    }
-    return decodeUtf8(bytes, 'read', target.displayPath)
-  } finally {
-    await handle.close()
-  }
-}
-
 /**
  * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
  * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 1a266301db..f6049b1795 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -28,7 +28,6 @@ import {
   readForEdit,
   readTextForDiff,
   readWholeText,
-  readWholeTextBounded,
   resolveLocalTarget,
   restoreLineEndings,
   streamWholeText,
@@ -126,10 +125,6 @@ export class LocalFileSystem extends FileSystem {
     return readWholeText({ displayPath: target.displayPath, targetKey: target.targetKey }, signal)
   }
 
-  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
-    return readWholeTextBounded({ displayPath: target.displayPath, targetKey: target.targetKey }, maxBytes, signal)
-  }
-
   override streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     return Promise.resolve(streamWholeText({ displayPath: target.displayPath, targetKey: target.targetKey }, signal))
   }
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index 02beab7323..4906bb0adc 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -218,15 +218,6 @@ describe('readText / streamText', () => {
     expect(await fs.readText(await fs.resolve('a.txt'))).toBe('one\ntwo\nthree')
   })
 
-  it('reads complete text through the stable byte bound', async () => {
-    await writeFile(join(dir, 'bounded.txt'), '€abc')
-    const target = await fs.resolve('bounded.txt')
-    expect(await fs.readTextBounded(target, 6)).toBe('€abc')
-    await expect(fs.readTextBounded(target, 5)).rejects.toThrow('exceeds the 5-byte limit')
-    await expect(fs.readTextBounded(target, 0)).rejects.toThrow('positive safe integer')
-    await expect(fs.readTextBounded(target, 6, AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
-  })
-
   it('streams the same text', async () => {
     await writeFile(join(dir, 'a.txt'), 'one\ntwo\nthree')
     const target = await fs.resolve('a.txt')
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index 2c5fd7a8f4..15588e40b9 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -5,7 +5,7 @@
  * policy and lives in `dsh-fs-policy`, so it is not tested here.
  */
 
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { chmod, mkdtemp, readFile, rename, rm, stat, symlink, unlink, writeFile, mkdir, readdir, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -17,7 +17,6 @@ import {
   probeNoFollow,
   readForEdit,
   readWholeText,
-  readWholeTextBounded,
   resolveLocalTarget,
   restoreLineEndings,
   streamWholeText,
@@ -317,66 +316,6 @@ describe('readWholeText', () => {
   })
 })
 
-describe('readWholeTextBounded', () => {
-  it('rejects non-files, binary text, and initial oversize without a full read', async () => {
-    await expect(readWholeTextBounded(localTarget(dir), 10)).rejects.toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
-    await writeFile(join(dir, 'large'), '12345')
-    await expect(readWholeTextBounded(localTarget(join(dir, 'large')), 4)).rejects.toThrow('exceeds the 4-byte limit')
-    await writeFile(join(dir, 'binary'), Buffer.from([0x61, 0x00, 0x62]))
-    await expect(readWholeTextBounded(localTarget(join(dir, 'binary')), 3)).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
-  })
-
-  it('detects growth past the bound on the same open handle', async () => {
-    const close = vi.fn(async () => {})
-    const read = vi.fn(async (buffer: Buffer, offset: number, length: number, position: number) => {
-      const bytes = position === 0 ? Buffer.from('abc') : Buffer.from('d')
-      bytes.copy(buffer, offset, 0, Math.min(length, bytes.length))
-      return { bytesRead: Math.min(length, bytes.length), buffer }
-    })
-    vi.resetModules()
-    vi.doMock('node:fs/promises', async (importOriginal) => {
-      const actual = await importOriginal<typeof import('node:fs/promises')>()
-      return {
-        ...actual,
-        open: async () => ({
-          stat: async () => ({ isFile: () => true, size: 3 }),
-          read,
-          close,
-        }),
-      }
-    })
-    try {
-      const isolated = await import('../src/fsio.ts')
-      await expect(isolated.readWholeTextBounded(localTarget('/virtual/growing'), 3))
-        .rejects.toThrow('grew past the 3-byte limit')
-      expect(close).toHaveBeenCalledOnce()
-    } finally {
-      vi.doUnmock('node:fs/promises')
-      vi.resetModules()
-    }
-  })
-
-  it('translates permission and generic open failures', async () => {
-    const failure: { current: Error & { code?: string } } = { current: Object.assign(new Error('denied'), { code: 'EACCES' }) }
-    vi.resetModules()
-    vi.doMock('node:fs/promises', async (importOriginal) => {
-      const actual = await importOriginal<typeof import('node:fs/promises')>()
-      return { ...actual, open: async () => { throw failure.current } }
-    })
-    try {
-      const isolated = await import('../src/fsio.ts')
-      await expect(isolated.readWholeTextBounded(localTarget('/virtual/denied'), 3))
-        .rejects.toMatchObject({ code: 'FS_PERMISSION_DENIED' })
-      failure.current = new Error('open broke')
-      await expect(isolated.readWholeTextBounded(localTarget('/virtual/broken'), 3))
-        .rejects.toMatchObject({ code: 'FS_IO_ERROR' })
-    } finally {
-      vi.doUnmock('node:fs/promises')
-      vi.resetModules()
-    }
-  })
-})
-
 describe('streamWholeText', () => {
   it('streams the whole file as decoded text', async () => {
     const file = join(dir, 'a.txt')
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index 4a0e675c0c..d9b5f0ebc0 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: 67079f795c705ab4c9cfa476e0458be04a48c6c8
-README.zh.md: d812a94fab9f4b7e9d15ff78bd1fea3bcc00c0d9
+README.md: bf1dd1c1eb65146258cd64e450749845522e7057
+README.zh.md: f3fcc0c3794b972233dc418e93bdd80b1cc8570a
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index 67079f795c..bf1dd1c1eb 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read bounded or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
+The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read whole or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
 This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
 
@@ -17,7 +17,7 @@ A future sandboxed, virtual, or remote backend implements this interface and the
 
 ## Service API (`ctx.fs`)
 
-A backend subclasses `FileSystem` and implements twelve primitives.
+A backend subclasses `FileSystem` and implements eleven primitives.
 
 | Member | Semantics |
 |---|---|
@@ -28,8 +28,7 @@ A backend subclasses `FileSystem` and implements twelve primitives.
 | `stat(target, signal?)` | Return `FsInfo` metadata (`version`, `type`, optional `size`), or `undefined` when the target is absent. Never content. |
 | `lstat(path, opts?, signal?)` | Return `FsPathInfo` metadata without following the final path component when it is a symlink. This is path-shaped so consumers can reject repository-owned symlinks before `resolve` follows them into a target. |
 | `readText(target, signal?)` | Read the whole regular text file as one decoded string. Owns regular-file checks, UTF-8 decoding, binary/NUL rejection (`FS_NOT_TEXT`). |
-| `readTextBounded(target, maxBytes, signal?)` | Read one complete regular UTF-8 file through a backend-owned stable operation, rejecting before retaining more than `maxBytes`. Consumers must not emulate this with `stat` then `readText`, which admits growth and replacement races. |
-| `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here). |
+| `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here); consumers that need a byte ceiling enforce it while consuming the stream. |
 | `listDir(target, signal?)` | List direct directory children in stable name order. Returns entry names, entry types, resolved child targets, and cheap metadata (`version`/file `size` when available); never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`. Broken/disappeared children may be returned as `other` without metadata; child permission/IO failures fail the whole listing with the same structured codes. |
 | `writeText(target, content, expected?, signal?)` | Atomic create/replace. `expected` is OPTIONAL: omit ⇒ unconditional create-or-overwrite; supply an `FsWriteIntent` (`createIfAbsent`/`replaceIfVersion`) to guard. |
 | `editText(target, edit, expected?, signal?)` | Literal edit. `expected` is OPTIONAL: omit ⇒ unconditional edit of the current content; supply `{ version }` to guard (verified BEFORE matching). A missing target reports `FS_STALE_VERSION` either way. Applies and writes atomically — one mutation critical section. |
@@ -61,6 +60,6 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **Text-only by contract** — backends reject binary/non-UTF-8 content with `FS_NOT_TEXT`; binary-safe operations are a deliberate deferral of [the tool-schemas Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md).
-- **Twelve primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
+- **Eleven primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
 - **No IO deadline** — the seam arms no timeout; cancellation is a best-effort optional `AbortSignal` per primitive (the deliberate [fs-family stance](../README.md)).
 - **Resolve-then-operate costs a remote backend two round-trips per tool call** — folding or caching resolution is left to such a backend.
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index d812a94fab..f3fcc0c379 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、有界或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
+**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
 
 本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
 
@@ -17,7 +17,7 @@
 
 ## 服务 API（`ctx.fs`）
 
-后端继承 `FileSystem` 并实现十二个原语。
+后端继承 `FileSystem` 并实现十一个原语。
 
 | 成员 | 语义 |
 |---|---|
@@ -28,8 +28,7 @@
 | `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
 | `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
-| `readTextBounded(target, maxBytes, signal?)` | 通过后端自有的稳定操作读取一个完整的普通 UTF-8 文件，在保留超过 `maxBytes` 前拒绝。消费方不得以先 `stat` 再 `readText` 模拟此操作，因为那会容许文件增长与替换竞态。 |
-| `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）。 |
+| `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
 | `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
 | `writeText(target, content, expected?, signal?)` | 原子创建/替换。`expected` 是可选的：省略 ⇒ 无条件创建或覆盖；提供 `FsWriteIntent`（`createIfAbsent`/`replaceIfVersion`）⇒ 添加防护。 |
 | `editText(target, edit, expected?, signal?)` | 字面量编辑。`expected` 是可选的：省略 ⇒ 无条件编辑当前内容；提供 `{ version }` ⇒ 添加防护，并在匹配之前校验。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。应用和写入以原子方式完成，使用同一个变更临界区。 |
@@ -61,6 +60,6 @@
 ## 已知限制与延期工作
 
 - **契约只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
-- **只有十二个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
+- **只有十一个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
 - **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见有意采用的 [fs 能力族立场](../README.md)）。
 - **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。
diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts
index 8bb20ece18..2d46868a57 100644
--- a/packages/fs/fs/src/index.ts
+++ b/packages/fs/fs/src/index.ts
@@ -1,7 +1,7 @@
 /**
  * Filesystem provider seam for one execution world. Backends own stable target
- * identity, process paths and file URIs, containment, stable bounded text
- * reads, decoding, binary rejection, and atomic mutations. Read windows and
+ * identity, process paths and file URIs, containment, text reads, decoding,
+ * binary rejection, and atomic mutations. Read windows and
  * observed-state policy stay in consumer and policy plugins; `editText`
  * remains here so version check, literal match, and rewrite share one critical
  * section.
@@ -172,19 +172,6 @@ export abstract class FileSystem extends Service {
    */
   abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
 
-  /**
-   * Read one regular UTF-8 text file through a backend-owned stable handle,
-   * rejecting before more than `maxBytes` are retained. The size check and
-   * bytes read are one operation: a caller must not emulate this with
-   * {@link stat} followed by {@link readText}, which admits growth and path
-   * replacement races between the two calls.
-   * @param target - the resolved target to read.
-   * @param maxBytes - positive safe-integer byte ceiling.
-   * @param signal - aborts the open/read operation.
-   * @returns the complete decoded text when it fits.
-   */
-  abstract readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string>
-
   /**
    * Stream the whole regular text file as decoded text chunks (same text
    * semantics as {@link readText}, for large files). The backend owns
diff --git a/packages/fs/fs/tests/service.spec.ts b/packages/fs/fs/tests/service.spec.ts
index 92f1cfc37f..f225e51cc0 100644
--- a/packages/fs/fs/tests/service.spec.ts
+++ b/packages/fs/fs/tests/service.spec.ts
@@ -46,11 +46,6 @@ class FakeFileSystem extends FileSystem {
     if (content === undefined) throw new FsError(`not found: ${target.displayPath}`, 'FS_NOT_FOUND')
     return content
   }
-  override async readTextBounded(target: FsTarget, maxBytes: number): Promise<string> {
-    const content = await this.readText(target)
-    if (Buffer.byteLength(content) > maxBytes) throw new FsError('too large', 'FS_IO_ERROR')
-    return content
-  }
   override async streamText(target: FsTarget): Promise<AsyncIterable<string>> {
     const content = await this.readText(target)
     return (async function* () { yield content })()
diff --git a/packages/fs/tool-fs/tests/tools.spec.ts b/packages/fs/tool-fs/tests/tools.spec.ts
index f54701246a..b217260972 100644
--- a/packages/fs/tool-fs/tests/tools.spec.ts
+++ b/packages/fs/tool-fs/tests/tools.spec.ts
@@ -67,11 +67,6 @@ class FakeFs extends FileSystem {
   override async readText(target: FsTarget): Promise<string> {
     return this.files.get(target.targetKey) ?? ''
   }
-  override async readTextBounded(target: FsTarget, maxBytes: number): Promise<string> {
-    const content = await this.readText(target)
-    if (Buffer.byteLength(content) > maxBytes) throw new Error('too large')
-    return content
-  }
   override async streamText(target: FsTarget): Promise<AsyncIterable<string>> {
     const content = this.files.get(target.targetKey) ?? ''
     return (async function* () { yield content })()
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index 5a1036a349..55a9f97165 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-local/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/lsp/lsp-local/README.md
-README.md: c96c4febc9d047b41789f2b7a73e3eaf4d35012b
-README.zh.md: 5bc2c3c8bb7a89afb673797f5a3b25bb9fc06748
+README.md: ad8f4bc2318a58202f9596a18d402d2c6d45dae1
+README.zh.md: ff2686856a9e518a7fa846edf700da1b32e8a114
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index c96c4febc9..ad8f4bc231 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -10,11 +10,11 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export).
 
 - Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes.
 - Lazily single-flights one server process per `(server id, canonical workspace target)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
-- Uses a compatibility-first **transient-open** sequence per query: resolve and boundedly read the source through `ctx.fs`, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
+- Uses a compatibility-first **transient-open** sequence per query: resolve and byte-bound the source while streaming it through `ctx.fs`, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
 - Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel. Provider disposal aborts filesystem and protocol work, awaits workspace lookups that have not entered a queue, then drains every queue and server.
 - After protocol shutdown fails, terminates the server's descendant tree through the subprocess seam (POSIX process-group signaling; Windows `taskkill /T /F`). Tree-kill delivery is contained like every group signal — it races server exit — and quiescence is confirmed by the handle's tree-liveness wait rather than by the kill's own outcome.
 - Resolves the server executable, cwd, process, and protocol streams through `ctx.subprocess`; `initialize.processId` is `null` because another machine or PID namespace must not monitor the harness process.
-- Uses `ctx.fs` canonical containment, file URIs, and stable bounded reads, but emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
+- Uses `ctx.fs` canonical containment, file URIs, and streamed text validation, but emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
 
 ## Configuration
 
@@ -42,7 +42,7 @@ Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: {
 
 ## Security boundary
 
-The provider trusts its configured server and claims no sandbox confinement. It delegates canonical identity, containment, no-follow/stable bounded reads, UTF-8 validation, and file-URI encoding to `ctx.fs`; it rejects missing, non-regular, non-UTF-8, oversized, or canonically out-of-workspace query sources before server startup. Result locations may be external, but an external path cannot become a query source. A deployment must mount filesystem and subprocess providers for the same execution world; split-world composition is invalid.
+The provider trusts its configured server and claims no sandbox confinement. It delegates canonical identity, containment, regular-file streaming, UTF-8 validation, and file-URI encoding to `ctx.fs`; it rejects missing, non-regular, non-UTF-8, oversized, or canonically out-of-workspace query sources before server startup. Containment is evaluated before the stream opens and does not promise stable-handle identity across concurrent path replacement. Result locations may be external, but an external path cannot become a query source. A deployment must mount filesystem and subprocess providers for the same execution world; split-world composition is invalid.
 
 ## Model Experience
 
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index 5bc2c3c8bb..ff2686856a 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -10,11 +10,11 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
 - 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其释放，并在新进程上重试该查询一次。
-- 每次查询都使用兼容性优先的**临时打开** 序列：通过 `ctx.fs` 解析源文件并进行有界读取、`textDocument/didOpen`（版本 1、完整文本）、所请求操作，然后执行 `textDocument/didClose`，该操作位于 `finally` 中。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
+- 每次查询都使用兼容性优先的**临时打开** 序列：通过 `ctx.fs` 解析并流式读取源文件，同时执行字节上限；随后执行 `textDocument/didOpen`（版本 1、完整文本）、所请求操作，以及位于 `finally` 中的 `textDocument/didClose`。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
 - 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方资源释放会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找结算，再排空所有队列并等待所有服务器结算。
 - 协议 shutdown 失败后，经由进程管理器 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
 - 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程与协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID 命名空间不得监控 harness 进程。
-- 使用 `ctx.fs` 提供的规范 containment、文件 URI 与稳定有界读取，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
+- 使用 `ctx.fs` 提供的规范 containment、文件 URI 与流式文本校验，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
 
 ## 配置
 
@@ -42,7 +42,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 安全边界
 
-提供方信任其配置的服务器，不声明任何沙箱限制。它把规范身份、containment、不跟随符号链接的稳定有界读取、UTF-8 校验与文件 URI 编码委托给 `ctx.fs`；服务器启动前，系统会拒绝缺失、非普通文件、非 UTF-8、过大或规范路径位于工作区外的查询源。结果位置可以在外部，但外部路径不能成为查询源。部署必须为同一执行环境挂载文件系统与子进程提供方；分裂执行环境的组合无效。
+提供方信任其配置的服务器，不声明任何沙箱限制。它把规范身份、containment、普通文件流式读取、UTF-8 校验与文件 URI 编码委托给 `ctx.fs`；服务器启动前，系统会拒绝缺失、非普通文件、非 UTF-8、过大或规范路径位于工作区外的查询源。系统在打开流之前检查 containment，但不保证路径并发替换期间的稳定句柄身份。结果位置可以在外部，但外部路径不能成为查询源。部署必须为同一执行环境挂载文件系统与子进程提供方；分裂执行环境的组合无效。
 
 ## 模型体验
 
diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts
index 55e13ed307..b8939a2ae4 100644
--- a/packages/lsp/lsp-local/src/host.ts
+++ b/packages/lsp/lsp-local/src/host.ts
@@ -1,5 +1,6 @@
 /** Filesystem-seam source access for the generic stdio LSP provider. */
 
+import { Buffer } from 'node:buffer'
 import type { FileSystem, FsTarget } from '@deepseek-ai/dsh-fs'
 import { throwIfAborted } from './abort.ts'
 
@@ -58,9 +59,9 @@ export async function canonicalizeWorkspace(
 }
 
 /**
- * Resolve, contain, and atomically read one bounded query source through
- * `ctx.fs`. The provider's bounded read owns stable-handle and no-follow
- * mechanics; this layer owns only LSP-facing validation and messages.
+ * Resolve, contain, and read one byte-bounded query source through `ctx.fs`.
+ * This layer owns the LSP-specific complete-document cap while the filesystem
+ * provider owns streaming, regular-file checks, and UTF-8 validation.
  * @param fs - filesystem provider sharing the server's execution world.
  * @param filePath - absolute source path or path relative to `workspace`.
  * @param workspace - already-canonical workspace.
@@ -90,17 +91,28 @@ export async function readHostSource(
   if (!fs.contains(workspace.target, target)) {
     throw new Error(`source "${filePath}" resolves outside the workspace`)
   }
-  let text: string
+  const chunks: string[] = []
+  let bytes = 0
   try {
-    text = await fs.readTextBounded(target, maxDocumentBytes, signal)
+    // XXX(lsp-source-replacement): Revisit stable-handle identity only if a real query observes
+    // replacement between canonical containment and the provider opening this stream.
+    const stream = await fs.streamText(target, signal)
+    for await (const chunk of stream) {
+      throwIfAborted(signal)
+      bytes += Buffer.byteLength(chunk)
+      if (bytes > maxDocumentBytes) {
+        throw new Error(`source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit`)
+      }
+      chunks.push(chunk)
+    }
   } catch (error: unknown) {
     throwIfAborted(signal)
-    throw new Error(`source "${filePath}" could not be opened safely: ${messageOf(error)}`, { cause: error })
+    throw new Error(`source "${filePath}" could not be read: ${messageOf(error)}`, { cause: error })
   }
   throwIfAborted(signal)
   return {
     fileUrl: fs.fileUrl(target),
-    text,
+    text: chunks.join(''),
   }
 }
 
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index 3db9deb50a..eea3851414 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -161,6 +161,12 @@ describe('readHostSource', () => {
     await expect(readSource('big.ts', 10)).rejects.toThrow(/10-byte limit/)
   })
 
+  it('counts the complete UTF-8 byte length at the configured boundary', async () => {
+    await writeFile(join(ws, 'multibyte.ts'), '€abc')
+    await expect(readSource('multibyte.ts', 6)).resolves.toMatchObject({ text: '€abc' })
+    await expect(readSource('multibyte.ts', 5)).rejects.toThrow(/5-byte limit/)
+  })
+
   it('rejects a non-UTF-8 source', async () => {
     await writeFile(join(ws, 'bin.ts'), Buffer.from([0xff, 0xfe, 0x00]))
     await expect(readSource('bin.ts')).rejects.toThrow(/invalid UTF-8|binary file/)
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index 0337b0fec2..63aea8742c 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -328,14 +328,17 @@ describe('lsp-local end to end over a fake server', () => {
     await expect(disposing).resolves.toBeUndefined()
   })
 
-  it('aborts a queued source read when the provider is disposed', async () => {
+  it('aborts a queued source stream when the provider is disposed', async () => {
     const ctx = await mount({ LSP_FAKE_DEF: 'null' })
     const fs = ctx.fs
     const started = Promise.withResolvers<AbortSignal>()
-    vi.spyOn(fs, 'readTextBounded').mockImplementation(async (_target, _maxBytes, signal) => {
+    vi.spyOn(fs, 'streamText').mockImplementation(async (_target, signal) => {
       if (signal === undefined) throw new Error('source read missing provider lifetime signal')
       started.resolve(signal)
-      return await rejectWhenAborted(signal)
+      return (async function* () {
+        await rejectWhenAborted(signal)
+        yield ''
+      })()
     })
 
     const pending = ctx.lsp.query(query('goToDefinition'))
diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 2f376707db..761f5a7d34 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -8,6 +8,8 @@
 
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
 import type { LspHover, LspLocation, LspOperation, LspPosition } from '@deepseek-ai/dsh-lsp'
+import { posix, win32 } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 /** The four operations the tool exposes, as a runtime tuple for schema enum + validation. */
 export const LSP_OPERATIONS: readonly LspOperation[] = ['goToDefinition', 'findReferences', 'goToImplementation', 'hover']
@@ -144,52 +146,31 @@ export function renderUri(uri: string, workspaceUri: string): string {
     return uri
   }
   if (workspace.protocol !== 'file:') return uri
-  const targetSegments = decodeFileSegments(target)
-  const workspaceSegments = decodeFileSegments(workspace)
-  if (targetSegments === undefined || workspaceSegments === undefined) return uri
-  const sameAuthority = target.hostname === workspace.hostname
-  const windowsWorld = isWindowsFileWorld(workspace, workspaceSegments)
-  if (windowsWorld && [...targetSegments, ...workspaceSegments].some(segment => segment.includes('\\'))) return uri
-  const inside = sameAuthority
-    && targetSegments.length >= workspaceSegments.length
-    && workspaceSegments.every((segment, index) => samePathSegment(segment, targetSegments[index] as string, windowsWorld))
-  if (inside) {
-    const relative = targetSegments.slice(workspaceSegments.length)
-    return relative.length === 0 ? '.' : relative.join('/')
-  }
-  return absoluteUriPath(target, targetSegments, windowsWorld)
+  const drivePath = /^\/[a-z](?::|%3A)/iu
+  const windowsWorld = workspace.hostname.length > 0 || drivePath.test(workspace.pathname)
+  const targetWindowsWorld = windowsWorld && (target.hostname.length > 0 || drivePath.test(target.pathname))
+  const workspacePath = filePath(workspace, windowsWorld)
+  const targetPath = filePath(target, targetWindowsWorld)
+  if (workspacePath === undefined || targetPath === undefined) return uri
+  if (windowsWorld !== targetWindowsWorld) return targetPath
+  const path = windowsWorld ? win32 : posix
+  const relative = path.relative(workspacePath, targetPath)
+  const outside = relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)
+  const rendered = relative === '' ? '.' : outside ? targetPath : relative
+  return windowsWorld ? rendered.replaceAll('\\', '/') : rendered
 }
 
-/** Whether a canonical file URI names a drive path or UNC path in a Windows execution world. */
-function isWindowsFileWorld(url: URL, segments: readonly string[]): boolean {
-  return url.hostname.length > 0 || /^[A-Za-z]:$/.test(segments[0] ?? '')
-}
-
-/** Decode URI path segments while rejecting encoded POSIX separators and NUL. */
-function decodeFileSegments(url: URL): string[] | undefined {
+/** Decode a file URL for its execution world while containing malformed URL failures. */
+function filePath(url: URL, windows: boolean): string | undefined {
   try {
-    const decoded = url.pathname.split('/').map(segment => decodeURIComponent(segment))
-    if (decoded.some(segment => /[/\0]/u.test(segment))) return undefined
-    while (decoded.at(-1) === '') decoded.pop()
-    decoded.shift()
-    return decoded
+    const path = fileURLToPath(url, { windows })
+    return path.includes('\0') ? undefined : path
   } catch {
+    // `fileURLToPath` rejects malformed escapes, authorities, and encoded path separators.
     return undefined
   }
 }
 
-/** Windows execution-world path segments are case-insensitive even on a non-Windows harness host. */
-function samePathSegment(left: string, right: string, windowsWorld: boolean): boolean {
-  return windowsWorld ? left.toUpperCase() === right.toUpperCase() : left === right
-}
-
-/** Render an external file URL according to the execution-world style implied by its workspace URI. */
-function absoluteUriPath(target: URL, segments: readonly string[], windowsWorld: boolean): string {
-  if (target.hostname.length > 0) return `//${target.hostname}/${segments.join('/')}`
-  if (windowsWorld && /^[A-Za-z]:$/.test(segments[0] ?? '')) return segments.join('/')
-  return `/${segments.join('/')}`
-}
-
 /**
  * UI presentation for a pending `lsp` call. Uses a generic search card; the title carries the
  * operation and one-based cursor, and `locations` focuses the queried line. The shared location
diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts
index f09297d3d4..2d181f25b3 100644
--- a/packages/lsp/tool-lsp/tests/render.spec.ts
+++ b/packages/lsp/tool-lsp/tests/render.spec.ts
@@ -103,6 +103,7 @@ describe('renderUri', () => {
   it('keeps a malformed file: URI verbatim when it cannot be parsed to a path', () => {
     // An encoded path separator is invalid on every platform and must remain verbatim.
     expect(renderUri('file:///bad%2Fpath', WS_URI)).toBe('file:///bad%2Fpath')
+    expect(renderUri('file:///bad%00path', WS_URI)).toBe('file:///bad%00path')
   })
 })
 
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 2bd653983e..c2a0f9b647 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: bccef05ca73ec8d826621f814f232206fa9fea4b
-README.zh.md: 27d4d1193047eb1bb3bf2289697be3c0cc0253aa
+README.md: c4af7bc8293689d64c58eebab2606d4f9b52fd2f
+README.zh.md: 21075ccbf53d173a54220b58b384f01cfe50ced1
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index bccef05ca7..c4af7bc829 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -8,9 +8,9 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following a delayed earlier prompt therefore cannot settle the current send. After a signaled send returns `inferred_idle` without a prompt marker, the next marker remains attributed to that prior send and cannot settle a successor even when it follows the successor's echoed input. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The terminal-allocation signal is detached when allocation returns, while readiness initialization keeps the setup signal, so later cancellation cannot terminate a published persistent session. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. The canceled send retains its slot until foreground signalling settles, so a successor cannot become that signal's target. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. A send that times out during an asynchronous provider write, or whose cancellation signal fails while that write remains pending, reports its result but retains the slot until the write settles, so late bytes cannot interleave with a successor. Close rejects new public signals after shutdown begins, drains public signals already in flight, starts provider-owned TERM-to-KILL whole-session cleanup, and awaits quiescence after the terminal outcome. A cleanup failure does not cache a permanently rejected close; a later close retries the provider operation.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. If a provider write is already in flight, signalling waits for it to settle; a rejected write sends no signal. The canceled send retains its slot until the write and foreground signalling settle, so a successor cannot receive either late bytes or that signal. The absolute deadline remains armed while cancellation waits. A signal failure is a terminal transport failure and rejects the active send. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close rejects new public signals, stops readiness polling, and awaits the handle's provider-owned complete-session termination before settling the active send as `session_exit`.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 27d4d11930..21075ccbf5 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -8,9 +8,9 @@
 
 该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在延迟到达的先前提示符之后，该提示符无法使当前 send 完成。在一次经过信号处理的 send 未出现提示符标记却返回 `inferred_idle` 后，下一个标记仍归属于该先前 send；即使该标记出现在后续 send 的输入回显之后，也不能使后续 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。终端分配返回时，分配信号会解除关联；就绪初始化则保留设置阶段信号，因此后续取消无法终止已发布的持久会话。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方信号会转发给终端分配和就绪初始化；句柄一经发布，便负责自身生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。被取消的发送会保留其槽位，直至前台信号发送结算，因此后续发送不会成为该信号的目标。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。发送在提供方异步写入期间超时，或在该写入仍未完成时其取消信号发送失败，都会报告各自结果，但继续占用该槽位，直至写入结算，从而避免延迟到达的字节与后续发送交错。关闭操作会在关闭开始后拒绝新的公开信号请求，等待已经在途的公开信号请求全部结算，再启动由提供方负责的 TERM→KILL 全会话清理，并在终端结果之后等待完全停稳。清理失败不会缓存成永久拒绝的关闭操作；后续关闭会重试提供方操作。
+取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待写入结算；写入被拒绝时不会发送信号。被取消的发送会保留其槽位，直至写入和前台信号发送都结算，因此后续发送既不会收到延迟字节，也不会成为该信号的目标。取消等待期间，绝对截止时间仍保持启用。信号发送失败属于终结性传输失败，并会使当前发送被拒绝。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待句柄执行由提供方负责的完整会话终止，之后才将当前发送以 `session_exit` 结算。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index 62b5fdb71a..a8d99cb243 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -101,30 +101,15 @@ export class LocalPtyBackend implements PtyBackend {
     ensureSandboxModeFence(this.ctx, spec.owner)
     const argv = spawnArgv(this.ctx, this.config, spec)
     if (argv[0] === undefined) throw new Error('pty-local: sandbox returned empty argv')
-    let terminalSignal: AbortSignal | undefined
-    let detachSetupSignal: (() => void) | undefined
-    if (spec.signal !== undefined) {
-      const source = spec.signal
-      const controller = new AbortController()
-      const onAbort = (): void => { controller.abort(source.reason) }
-      source.addEventListener('abort', onAbort, { once: true })
-      detachSetupSignal = () => { source.removeEventListener('abort', onAbort) }
-      terminalSignal = controller.signal
-    }
-    let terminal: SubprocessTerminalHandle
-    try {
-      terminal = await this.spawnTerminal({
-        argv,
-        cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
-        env: childEnvironment(spec),
-        rows: this.config.rows,
-        cols: this.config.cols,
-        graceMs: this.config.disposeGraceMs,
-        signal: terminalSignal,
-      })
-    } finally {
-      detachSetupSignal?.()
-    }
+    const terminal = await this.spawnTerminal({
+      argv,
+      cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
+      env: childEnvironment(spec),
+      rows: this.config.rows,
+      cols: this.config.cols,
+      graceMs: this.config.disposeGraceMs,
+      signal: spec.signal,
+    })
     const session = this.createSession(terminal, this.config)
     try {
       await session.initialize(spec.signal)
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 08b42466aa..076f21e3b9 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -155,7 +155,7 @@ class LocalSendOperation implements PtySendOperation {
 export class LocalPtySession implements PtyBackendSession {
   motd = ''
   readonly pid: number
-  private readonly decoder = new TextDecoder('utf-8', { fatal: true })
+  private readonly decoder = new TextDecoder()
   private readonly sanitizer: TerminalSanitizer
   private readonly scrollback: BoundedTextBuffer
   private readonly outputEnded = Promise.withResolvers<void>()
@@ -165,16 +165,13 @@ export class LocalPtySession implements PtyBackendSession {
   private activeTimer: NodeJS.Timeout | undefined
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
-  private readonly terminalOperations = new Set<Promise<unknown>>()
-  private signaledOperation: LocalSendOperation | undefined
   private interrupting: LocalSendOperation | undefined
-  private writing: LocalSendOperation | undefined
+  private activeWrite: { operation: LocalSendOperation; settled: Promise<boolean> } | undefined
   private pollingReady: LocalSendOperation | undefined
   private polling = false
   private promptSeen = false
   private promptTextSeen = false
   private promptTail = ''
-  private delayedSignaledPrompt = false
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
@@ -239,23 +236,14 @@ export class LocalPtySession implements PtyBackendSession {
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
     this.activeDeadlineTimer = setTimeout(() => {
-      if (this.active === operation) this.settleActive('timeout', this.writing === operation)
+      if (this.active === operation) {
+        this.settleActive('timeout', this.activeWrite?.operation === operation)
+      }
     }, this.config.timeoutMs)
-    this.ownTerminalOperation(this.beginSend(operation, request))
+    void this.beginSend(operation, request)
     return operation
   }
 
-  /** Retain one contained provider operation until its asynchronous work finishes. */
-  private ownTerminalOperation(operation: Promise<void>): void {
-    void this.trackTerminalOperation(operation)
-  }
-
-  private trackTerminalOperation<T>(operation: Promise<T>): Promise<T> {
-    const tracked = operation.finally(() => { this.terminalOperations.delete(tracked) })
-    this.terminalOperations.add(tracked)
-    return tracked
-  }
-
   private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
     try {
       const foreground = await this.terminal.inspectForeground()
@@ -264,13 +252,20 @@ export class LocalPtySession implements PtyBackendSession {
       const input = `${request.text}${request.submit ? '\r' : ''}`
       if (input.length > 0 && !operation.cancelRequested) {
         this.resetReadinessEvidence()
-        this.writing = operation
+        const write = this.terminal.write(input)
+        const activeWrite = {
+          operation,
+          settled: write.then(() => true, () => false),
+        }
+        this.activeWrite = activeWrite
         try {
-          await this.terminal.write(Buffer.from(input, 'utf8'))
+          await write
         } finally {
-          this.writing = undefined
+          this.activeWrite = undefined
         }
       }
+      // Cancellation owns post-write signalling and reservation release.
+      if (operation.cancelRequested) return
       if (this.active === operation && operation.settled) {
         this.clearActive()
         return
@@ -282,7 +277,7 @@ export class LocalPtySession implements PtyBackendSession {
         this.schedulePoll(operation)
       }
     } catch (error: unknown) {
-      if (this.active === operation) {
+      if (this.active === operation && !this.closing) {
         if (operation.settled) this.clearActive()
         else this.failActive(error)
       }
@@ -323,8 +318,7 @@ export class LocalPtySession implements PtyBackendSession {
 
   async signal(signal: PtySignal): Promise<PtySignalResult> {
     if (this.closing) throw new Error('PTY session is closing')
-    if (this.active !== undefined) this.signaledOperation = this.active
-    const targetPgid = await this.trackTerminalOperation(this.terminal.signalForeground(signal))
+    const targetPgid = await this.terminal.signalForeground(signal)
     return { delivered: true, targetPgid }
   }
 
@@ -345,23 +339,14 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private readonly onTerminalData = (chunk: Buffer | Uint8Array | string): void => {
-    try {
-      const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
-      this.onData(this.decoder.decode(bytes, { stream: true }))
-    } catch (error: unknown) {
-      this.onTransportFailure(new Error('PTY emitted invalid UTF-8', { cause: error }))
-    }
+    const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
+    this.onData(this.decoder.decode(bytes, { stream: true }))
   }
 
   private readonly onTerminalEnd = (): void => {
-    try {
-      this.onData(this.decoder.decode())
-      this.appendOutput(this.sanitizer.flush())
-    } catch (error: unknown) {
-      this.onTransportFailure(new Error('PTY ended with invalid UTF-8', { cause: error }))
-    } finally {
-      this.outputEnded.resolve()
-    }
+    this.onData(this.decoder.decode())
+    this.appendOutput(this.sanitizer.flush())
+    this.outputEnded.resolve()
   }
 
   private readonly onTerminalError = (error: Error): void => {
@@ -372,9 +357,9 @@ export class LocalPtySession implements PtyBackendSession {
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
-    if (sanitized.prompt && this.delayedSignaledPrompt) {
-      this.delayedSignaledPrompt = false
-    } else if (sanitized.prompt) {
+    if (sanitized.prompt) {
+      // TODO(pty-delayed-signal-prompt): With a reproducer, define a marker-generation boundary
+      // before attributing a signal-delayed prompt to a later send.
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
@@ -402,7 +387,7 @@ export class LocalPtySession implements PtyBackendSession {
     this.transportFailure ??= failure
     this.statusValue = { kind: 'exited', exitCode: null, signal: null }
     this.failActive(failure)
-    this.terminal.terminate()
+    void this.terminal.terminate().catch(() => {})
   }
 
   private appendOutput(text: string): void {
@@ -417,7 +402,7 @@ export class LocalPtySession implements PtyBackendSession {
     if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = setTimeout(() => {
       this.activeTimer = undefined
-      this.ownTerminalOperation(this.pollReadiness(operation))
+      void this.pollReadiness(operation)
     }, delayMs)
   }
 
@@ -457,7 +442,7 @@ export class LocalPtySession implements PtyBackendSession {
         this.settleActive('inferred_idle')
       }
     } catch (error: unknown) {
-      if (this.active === operation) this.failActive(error)
+      if (this.active === operation && !this.closing) this.failActive(error)
     } finally {
       this.polling = false
       const active = this.active
@@ -470,13 +455,6 @@ export class LocalPtySession implements PtyBackendSession {
   private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
-    // A signaled command can return by silence before bash emits its prompt.
-    // Reserve that marker so it cannot become successor readiness after echo.
-    const signaled = this.signaledOperation === operation
-    if (signaled) this.signaledOperation = undefined
-    if (waitReason === 'inferred_idle' && !this.promptSeen && signaled) {
-      this.delayedSignaledPrompt = true
-    }
     const scrollbackTruncated = this.scrollback.snapshot().truncated
     if (retainOwnership) {
       this.stopPolling()
@@ -489,10 +467,14 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private stopPolling(): void {
-    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
-    this.activeTimer = undefined
+    this.stopReadinessPolling()
     if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
     this.activeDeadlineTimer = undefined
+  }
+
+  private stopReadinessPolling(): void {
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
+    this.activeTimer = undefined
     this.pollingReady = undefined
   }
 
@@ -502,43 +484,38 @@ export class LocalPtySession implements PtyBackendSession {
     this.activeAbort?.()
     this.activeAbort = undefined
     if (this.interrupting === operation) this.interrupting = undefined
-    if (this.signaledOperation === operation) this.signaledOperation = undefined
-    this.writing = undefined
     this.pollingReady = undefined
     this.active = undefined
   }
 
-  private failActive(error: unknown, retainOwnership = false): void {
+  private failActive(error: unknown): void {
     const operation = this.active
     if (operation === undefined) return
-    if (retainOwnership) {
-      this.stopPolling()
-      this.activeAbort?.()
-      this.activeAbort = undefined
-    } else {
-      this.clearActive()
-    }
+    this.clearActive()
     operation.fail(error)
   }
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    this.signaledOperation = operation
     this.interrupting = operation
-    this.stopPolling()
-    this.ownTerminalOperation(this.interruptOnce(operation))
+    this.stopReadinessPolling()
+    void this.interruptOnce(operation)
   }
 
   private async interruptOnce(operation: LocalSendOperation): Promise<void> {
     try {
+      const activeWrite = this.activeWrite
+      if (activeWrite?.operation === operation && !await activeWrite.settled) return
       await this.terminal.signalForeground('SIGINT')
     } catch (error: unknown) {
-      if (this.active === operation) this.failActive(error, this.writing === operation)
+      if (this.active === operation && !this.closing) this.onTransportFailure(error)
       return
     } finally {
       if (this.interrupting === operation) this.interrupting = undefined
     }
-    if (this.active === operation && !operation.settled && !this.closing && this.writing !== operation) {
+    if (this.active === operation && operation.settled) {
+      this.clearActive()
+    } else if (this.active === operation && !this.closing) {
       this.pollingReady = operation
       this.schedulePoll(operation, 0)
     }
@@ -549,20 +526,13 @@ export class LocalPtySession implements PtyBackendSession {
     // it as session_exit below, so an in-flight send is never mis-settled as
     // stdin_read/inferred_idle/timeout during the grace period.
     this.stopPolling()
-    this.terminal.terminate()
-    const quiescent = await this.terminal.waitForExit()
-    if (!quiescent) {
-      throw new Error(`PTY cleanup failed (${reason}); terminal session did not reach quiescence`)
+    try {
+      await this.terminal.terminate()
+    } catch (error: unknown) {
+      throw new Error(`PTY cleanup failed (${reason})`, { cause: error })
     }
-    // Quiescence is the active send's terminal outcome. Detach its abort
-    // listener before snapshotting provider operations so no late interrupt
-    // can enter the owned set after the drain starts.
+    // Quiescence is the active send's terminal outcome.
     this.settleActive('session_exit')
-    await Promise.all(this.terminalOperations)
-    // Whole-session cleanup can fail before the top-level process exits. Wait
-    // for it first so that failure is reported instead of blocking forever on
-    // `done`; successful quiescence guarantees `done` can now settle status and
-    // drain the terminal output.
     await this.completion
     this.terminal.output.off('data', this.onTerminalData)
     this.terminal.output.off('end', this.onTerminalEnd)
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 23e6f4bc89..48c8272106 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -61,8 +61,7 @@ function terminalHandle(): SubprocessTerminalHandle {
     write: async () => {},
     inspectForeground: async () => ({ processGroupId: 123, inputWaiting: true }),
     signalForeground: async () => 123,
-    terminate: () => { output.end() },
-    waitForExit: async () => true,
+    terminate: async () => { output.end() },
   }
 }
 
@@ -187,7 +186,7 @@ describe('LocalPtyBackend startup rollback', () => {
     expect(initialized).toHaveBeenCalledWith(undefined)
   })
 
-  it('forwards setup cancellation only while terminal allocation is unpublished', async () => {
+  it('forwards terminal allocation cancellation directly', async () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
@@ -204,10 +203,9 @@ describe('LocalPtyBackend startup rollback', () => {
       () => stubLocalSession(),
     )
     await published.spawn(spec(agent(ctx), publishedController.signal))
-    expect(publishedSignal).toBeDefined()
-    expect(publishedSignal).not.toBe(publishedController.signal)
+    expect(publishedSignal).toBe(publishedController.signal)
     publishedController.abort(new Error('originating turn ended'))
-    expect(publishedSignal?.aborted).toBe(false)
+    expect(publishedSignal?.aborted).toBe(true)
 
     const pendingController = new AbortController()
     const seen = Promise.withResolvers<AbortSignal>()
@@ -245,11 +243,10 @@ describe('LocalPtyBackend startup rollback', () => {
       write: async () => {},
       inspectForeground: async () => ({ processGroupId: 123, inputWaiting: true }),
       signalForeground: async () => 123,
-      terminate() {
+      async terminate() {
         output.end()
         outcome.resolve({ exitCode: null, signal: 'SIGTERM' })
       },
-      waitForExit: async () => true,
     }
     queueMicrotask(() => { output.write(Buffer.from('\x1b]133;D;0\x07dsh> ')) })
     const backend = new LocalPtyBackend(
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index dc03da2a63..22b07a0f8f 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -50,8 +50,8 @@ class FakeTerminal implements SubprocessTerminalHandle {
   throwWrite = false
   throwKill = false
   autoExitOnKill = true
-  quiescent = true
-  waitError: Error | undefined
+  terminateError: Error | undefined
+  private cleanup: Promise<void> | undefined
 
   constructor(public inspector = new FakeInspector()) {}
 
@@ -80,9 +80,9 @@ class FakeTerminal implements SubprocessTerminalHandle {
     })
   }
 
-  async write(data: Uint8Array): Promise<void> {
+  async write(data: string): Promise<void> {
     if (this.throwWrite) throw new Error('write failed')
-    this.writes.push(Buffer.from(data).toString('utf8'))
+    this.writes.push(data)
   }
 
   async inspectForeground() {
@@ -102,16 +102,20 @@ class FakeTerminal implements SubprocessTerminalHandle {
     return foreground.processGroupId
   }
 
-  terminate(): void {
+  terminate(): Promise<void> {
+    if (this.cleanup !== undefined) return this.cleanup
+    const cleanup = this.terminateOnce()
+    this.cleanup = cleanup
+    void cleanup.catch(() => { this.cleanup = undefined })
+    return cleanup
+  }
+
+  private async terminateOnce(): Promise<void> {
+    if (this.terminateError !== undefined) throw this.terminateError
     if (this.throwKill) throw new Error('kill failed')
     this.kills.push('SIGTERM')
     if (this.autoExitOnKill) this.emitExit(0, 15)
   }
-
-  async waitForExit(): Promise<boolean> {
-    if (this.waitError !== undefined) throw this.waitError
-    return this.quiescent
-  }
 }
 
 function makeSession(
@@ -370,6 +374,100 @@ describe('LocalPtySession readiness and output', () => {
     expect(inspector.groups).not.toContainEqual([789, 'SIGINT'])
   })
 
+  it('signals only after an in-flight provider write lands', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const writeGate = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await writeGate.promise }
+    const operation = session.startSend({ text: 'must be interrupted', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+    await vi.advanceTimersByTimeAsync(20)
+    expect(inspector.groups).toEqual([])
+
+    writeGate.resolve(undefined)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    terminal.emitData('\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+  })
+
+  it('does not signal when a cancelled provider write rejects', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const writeGate = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await writeGate.promise }
+    const operation = session.startSend({ text: 'rejected write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+
+    const rejected = expect(operation.done).rejects.toThrow('write failed after cancellation')
+    writeGate.reject(new Error('write failed after cancellation'))
+    await rejected
+    expect(inspector.groups).toEqual([])
+
+    const next = session.startSend({ text: '', submit: false })
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await next.done).waitReason).toBe('inferred_idle')
+  })
+
+  it('releases a timed-out cancellation after the provider write and signal settle', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const writeGate = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await writeGate.promise }
+    const operation = session.startSend({ text: 'slow cancelled write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+    await vi.advanceTimersByTimeAsync(100)
+
+    expect((await operation.done).waitReason).toBe('timeout')
+    expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow('active send')
+
+    writeGate.resolve(undefined)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+
+    const next = session.startSend({ text: '', submit: false })
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await next.done).waitReason).toBe('inferred_idle')
+  })
+
+  it('retains the absolute timeout after cancellation while output stays active', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const operation = session.startSend({ text: 'ignore-sigint-and-write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(operation.cancel()).toBe(true)
+    for (let elapsed = 20; elapsed <= 100; elapsed += 20) {
+      terminal.emitData('.')
+      await vi.advanceTimersByTimeAsync(20)
+    }
+
+    expect(await operation.done).toMatchObject({ waitReason: 'timeout' })
+  })
+
   it('does not resume cancellation polling after the terminal exits during signalling', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -437,21 +535,24 @@ describe('LocalPtySession readiness and output', () => {
 
     const writeGate = Promise.withResolvers<undefined>()
     terminal.write = async () => { await writeGate.promise }
-    terminal.signalForeground = async () => { throw new Error('interrupt failed') }
+    let signalCalls = 0
+    terminal.signalForeground = async () => {
+      signalCalls += 1
+      throw new Error('interrupt failed')
+    }
     const operation = session.startSend({ text: 'slow write', submit: true })
     await Promise.resolve()
     await Promise.resolve()
-    const rejected = expect(operation.done).rejects.toThrow('interrupt failed')
     expect(operation.cancel()).toBe(true)
-    await rejected
+    await vi.advanceTimersByTimeAsync(20)
+    expect(signalCalls).toBe(0)
     expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow('active send')
 
     writeGate.resolve(undefined)
-    await Promise.resolve()
-    await Promise.resolve()
-    const next = session.startSend({ text: '', submit: false })
-    await vi.advanceTimersByTimeAsync(100)
-    expect((await next.done).waitReason).toBe('inferred_idle')
+    await expect(operation.done).rejects.toThrow('interrupt failed')
+    expect(signalCalls).toBe(1)
+    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+    expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
   })
 
   it('handles startup exit, unknown exit signals, cancel-write failure, and stale polls', async () => {
@@ -591,35 +692,6 @@ describe('LocalPtySession readiness and output', () => {
     expect(await operation.done).toMatchObject({ waitReason: 'stdin_read' })
   })
 
-  it('does not attribute a post-echo prompt from an inferred prior send to its successor', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal, config({ idleSilenceMs: 50, timeoutMs: 200 }))
-    await initialize(session, terminal)
-
-    const interrupted = session.startSend({ text: 'sleep', submit: true })
-    await Promise.resolve()
-    await Promise.resolve()
-    await session.signal('SIGINT')
-    await vi.advanceTimersByTimeAsync(50)
-    expect((await interrupted.done).waitReason).toBe('inferred_idle')
-
-    const successor = session.startSend({ text: "printf 'PID=%s\\n' \"$!\"", submit: true })
-    let settled = false
-    void successor.done.then(() => { settled = true })
-    await Promise.resolve()
-    await Promise.resolve()
-    terminal.emitData('printf \'PID=%s\\n\' "$!"\r\n\x1b]133;D;130\x07dsh> ')
-    await vi.advanceTimersByTimeAsync(10)
-    expect(settled).toBe(false)
-
-    terminal.emitData('PID=123\r\n\x1b]133;D;0\x07dsh> ')
-    await vi.advanceTimersByTimeAsync(10)
-    const result = await successor.done
-    expect(result.waitReason).toBe('stdin_read')
-    expect(result.viewport).toContain('PID=123')
-  })
-
   it('retains a prompt marker until the startup shell regains the foreground group', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -683,6 +755,7 @@ describe('LocalPtySession readiness and output', () => {
 
   it('contains terminal transport failures and preserves the first failure', async () => {
     const terminal = new FakeTerminal()
+    terminal.terminateError = new Error('cleanup after transport failure')
     const session = new LocalPtySession(terminal, config())
     const operation = session.startSend({ text: '', submit: false })
     terminal.output.emit('data', 'plain text')
@@ -691,6 +764,7 @@ describe('LocalPtySession readiness and output', () => {
       .onTransportFailure(new Error('later failure'))
     await expect(operation.done).rejects.toThrow('output transport failed')
     expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+    terminal.terminateError = undefined
     await expect(session.close('transport')).rejects.toThrow('output transport failed')
 
     const rejectedTerminal = new FakeTerminal()
@@ -700,19 +774,21 @@ describe('LocalPtySession readiness and output', () => {
     await expect(rejectedOperation.done).rejects.toThrow('raw transport failure')
   })
 
-  it('rejects invalid UTF-8 in a data chunk and at stream end', async () => {
+  it('replaces invalid UTF-8 terminal output', async () => {
     const chunkTerminal = new FakeTerminal()
     const chunkSession = new LocalPtySession(chunkTerminal, config())
     const chunkOperation = chunkSession.startSend({ text: '', submit: false })
     chunkTerminal.emitBytes(Uint8Array.from([0xff]))
-    await expect(chunkOperation.done).rejects.toThrow('PTY emitted invalid UTF-8')
+    expect(chunkOperation.readOutput()).toEqual({ delta: '�', truncated: false })
+    chunkTerminal.emitExit()
+    await chunkOperation.done
 
     const endTerminal = new FakeTerminal()
     const endSession = new LocalPtySession(endTerminal, config())
     const endOperation = endSession.startSend({ text: '', submit: false })
     endTerminal.emitBytes(Uint8Array.from([0xe2]))
     endTerminal.emitExit()
-    await expect(endOperation.done).rejects.toThrow('PTY ended with invalid UTF-8')
+    expect((await endOperation.done).viewport).toBe('�')
   })
 
   it('contains readiness inspection failure and a stale inspection result', async () => {
@@ -952,43 +1028,32 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     await expect(session.signal('SIGTERM')).rejects.toThrow('cannot resolve')
   })
 
-  it('drains an in-flight public signal and rejects signals after close starts', async () => {
+  it('closes idempotently and rejects new signals', async () => {
     const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal, config())
-    const signal = Promise.withResolvers<number>()
-    terminal.signalForeground = async () => await signal.promise
-
-    const signaling = session.signal('SIGINT')
-    const closing = session.close('public signal')
-    let closed = false
-    void closing.then(() => { closed = true })
-    await Promise.resolve()
-    expect(closed).toBe(false)
-    await expect(session.signal('SIGTERM')).rejects.toThrow('closing')
-
-    signal.resolve(456)
-    await expect(signaling).resolves.toEqual({ delivered: true, targetPgid: 456 })
-    await closing
-    expect(closed).toBe(true)
-  })
-
-  it('closes idempotently, contains signal races, and reports survivors', async () => {
-    const terminal = new FakeTerminal()
-    terminal.quiescent = false
+    terminal.throwKill = true
     const session = new LocalPtySession(terminal, config({ disposeGraceMs: 1 }))
     const closing = session.close('test')
     expect(session.close('other')).toBe(closing)
-    await expect(closing).rejects.toThrow('did not reach quiescence')
+    await expect(closing).rejects.toThrow('PTY cleanup failed (test)')
     expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
+    await expect(session.signal('SIGTERM')).rejects.toThrow('closing')
   })
 
-  it('reports cleanup failure without waiting for top-level exit', async () => {
+  it('reports cleanup failure without waiting for top-level exit and permits retry', async () => {
     const terminal = new FakeTerminal()
     terminal.autoExitOnKill = false
-    terminal.waitError = new Error('terminal cleanup failed; surviving pids: 456')
+    terminal.terminateError = new Error('terminal cleanup failed; surviving pids: 456')
     const session = new LocalPtySession(terminal, config())
 
-    await expect(session.close('survivor')).rejects.toThrow('surviving pids: 456')
+    await expect(session.close('survivor')).rejects.toMatchObject({
+      message: 'PTY cleanup failed (survivor)',
+      cause: terminal.terminateError,
+    })
+    expect(terminal.kills).toEqual([])
+
+    terminal.terminateError = undefined
+    terminal.autoExitOnKill = true
+    await expect(session.close('retry')).resolves.toBeUndefined()
     expect(terminal.kills).toEqual(['SIGTERM'])
   })
 
@@ -1010,73 +1075,25 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     await closing
   })
 
-  it('does not finish close while a pre-write terminal operation is pending', async () => {
+  it('settles a closing send when provider termination cancels inspection', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const session = new LocalPtySession(terminal, config())
     await initialize(session, terminal)
-
     const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
     terminal.inspectForeground = async () => await inspection.promise
-    const operation = session.startSend({ text: 'must not run', submit: true })
-    const closing = session.close('pending inspection')
-    let closed = false
-    void closing.then(() => { closed = true })
+    const terminate = terminal.terminate.bind(terminal)
+    terminal.terminate = async () => {
+      inspection.reject(new Error('terminal terminated'))
+      await terminate()
+    }
+    const operation = session.startSend({ text: 'pending inspection', submit: true })
     await Promise.resolve()
-    await Promise.resolve()
-    expect(closed).toBe(false)
 
-    inspection.resolve({ processGroupId: 456, inputWaiting: false })
-    await closing
-    expect(closed).toBe(true)
+    await session.close('pending inspection')
+
+    expect((await operation.done).waitReason).toBe('session_exit')
     expect(terminal.writes).toEqual([])
-    expect((await operation.done).waitReason).toBe('session_exit')
-  })
-
-  it('does not finish close while a terminal write is pending', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal, config())
-    await initialize(session, terminal)
-
-    const write = Promise.withResolvers<undefined>()
-    terminal.write = async () => { await write.promise }
-    const operation = session.startSend({ text: 'pending write', submit: true })
-    await Promise.resolve()
-    await Promise.resolve()
-    const closing = session.close('pending write')
-    let closed = false
-    void closing.then(() => { closed = true })
-    await Promise.resolve()
-    await Promise.resolve()
-    expect(closed).toBe(false)
-
-    write.resolve(undefined)
-    await closing
-    expect(closed).toBe(true)
-    expect((await operation.done).waitReason).toBe('session_exit')
-  })
-
-  it('detaches active cancellation before draining terminal operations', async () => {
-    vi.useFakeTimers()
-    const terminal = new FakeTerminal()
-    const session = new LocalPtySession(terminal, config())
-    await initialize(session, terminal)
-
-    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
-    terminal.inspectForeground = async () => await inspection.promise
-    const signalForeground = vi.spyOn(terminal, 'signalForeground')
-    const controller = new AbortController()
-    const operation = session.startSend({ text: 'pending inspection', submit: true, signal: controller.signal })
-    const closing = session.close('pending cancellation')
-    await Promise.resolve()
-    await Promise.resolve()
-
-    controller.abort('late cancellation')
-    expect(signalForeground).not.toHaveBeenCalled()
-    inspection.resolve({ processGroupId: 456, inputWaiting: false })
-    await closing
-    expect((await operation.done).waitReason).toBe('session_exit')
   })
 
 })
diff --git a/packages/skill/skill-local/tests/skill-local.spec.ts b/packages/skill/skill-local/tests/skill-local.spec.ts
index 9dc723fb58..75f4a4ed65 100644
--- a/packages/skill/skill-local/tests/skill-local.spec.ts
+++ b/packages/skill/skill-local/tests/skill-local.spec.ts
@@ -92,12 +92,6 @@ class TestFileSystem extends FileSystem {
     return text
   }
 
-  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
-    const text = await this.readText(target, signal)
-    if (Buffer.byteLength(text) > maxBytes) throw new Error('too large')
-    return text
-  }
-
   override async streamText(_target: FsTarget): Promise<AsyncIterable<string>> {
     throw new Error('not needed in skill tests')
   }
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index ded1d12b30..d34e7475f9 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: 9f30fa6dc676e7b82f87b75b78b7d3143f204c94
-README.zh.md: 0b6813ec7d754f42e8bf4c65a1dee33d77bf3787
+README.md: 31c5539750c4af2b1c4169ac1dce4c91da587af7
+README.zh.md: 74aed52084c0db3ed9bfe4fcb991f781976fb7b5
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 9f30fa6dc6..31c5539750 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -11,7 +11,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
 - **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal before any process-cleanup failure is reported, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
-- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal bytes, inspects and signals the current foreground process group, and sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
+- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
 ## Model Experience
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 0b6813ec7d..74aed52084 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -11,7 +11,7 @@
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
 - **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，会在资源释放时删除，并且删除发生在报告任何进程清理失败之前；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
-- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端字节，检查当前前台进程组并向其发送信号，并在终止顶层 shell 前后清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，并公开一项须等待的终止操作，该操作会在终止顶层 shell 前后清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
 - **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 0d71cb0e33..0d02f0e387 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -59,12 +59,7 @@ export class LocalSubprocessService extends SubprocessService {
         pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))
       }
       for (const terminal of this.terminals) {
-        terminal.terminate()
-        // Cleanup may reject before the top-level process exits (for example,
-        // an identity-fenced descendant survives escalation). Await the cleanup
-        // transaction directly so disposal reports that failure rather than
-        // waiting forever on `done`.
-        pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
+        pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
       }
       this.live.clear()
       const outcomes = [
@@ -136,11 +131,6 @@ export class LocalSubprocessService extends SubprocessService {
     if (file === undefined || file.length === 0) {
       throw new Error('subprocess-local: terminal argv must contain a program')
     }
-    for (const [name, value] of [['rows', spec.rows], ['cols', spec.cols], ['graceMs', spec.graceMs]] as const) {
-      if (!Number.isSafeInteger(value) || value <= 0) {
-        throw new Error(`subprocess-local: terminal ${name} must be a positive safe integer`)
-      }
-    }
     spec.signal?.throwIfAborted()
     const options: IPtyForkOptions = {
       name: 'dumb',
@@ -151,10 +141,10 @@ export class LocalSubprocessService extends SubprocessService {
     }
     const inspector = this.terminalInspector ?? createProcessInspector()
     const terminal = nodePty.spawn(file, [...spec.argv.slice(1)], options)
-    const handle = new LocalTerminalHandle(terminal, inspector, spec.graceMs, spec.signal)
+    const handle = new LocalTerminalHandle(terminal, inspector, spec.graceMs)
     this.terminals.add(handle)
     const release = async (): Promise<void> => {
-      await handle.waitForExit()
+      await handle.terminate()
       this.terminals.delete(handle)
     }
     void handle.done.then(release, release).catch(() => {})
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 30e38bd422..93b7a8fc2e 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -4,7 +4,6 @@ import { Buffer } from 'node:buffer'
 import { constants } from 'node:os'
 import { PassThrough } from 'node:stream'
 import type { IDisposable, IPty } from 'node-pty'
-import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessOutcome,
   SubprocessTerminalForeground,
@@ -34,7 +33,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   private readonly outcome = Promise.withResolvers<SubprocessOutcome>()
   private readonly dataDisposable: IDisposable
   private readonly exitDisposable: IDisposable
-  private readonly lifecycle: SubprocessTerminalLifecycle
+  private cleanup: Promise<void> | undefined
   private exited = false
   private trackedDescendants: ProcessIdentity[] = []
 
@@ -42,13 +41,11 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
    * @param terminal - allocated node-pty process.
    * @param inspector - platform process/session operations.
    * @param graceMs - TERM-to-KILL and exit-wait grace.
-   * @param signal - optional lifetime cancellation.
    */
   constructor(
     private readonly terminal: IPty,
     private readonly inspector: ProcessInspector,
     private readonly graceMs: number,
-    signal?: AbortSignal,
   ) {
     this.pid = terminal.pid
     this.done = this.outcome.promise
@@ -61,26 +58,15 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
         exitCode: exitSignal === undefined || exitSignal === 0 ? exitCode : null,
         signal: signalName(exitSignal),
       })
-      this.terminate()
-    })
-    this.lifecycle = new SubprocessTerminalLifecycle({
-      done: this.done,
-      cleanup: () => this.closeOnce(),
-      signal,
+      void this.terminate().catch(() => {})
     })
   }
 
   // node-pty writes synchronously; the seam returns a promise for remote transports.
   // eslint-disable-next-line @typescript-eslint/require-await
-  async write(data: Uint8Array): Promise<void> {
+  async write(data: string): Promise<void> {
     if (this.exited) throw new Error('terminal process has exited')
-    let text: string
-    try {
-      text = new TextDecoder('utf-8', { fatal: true }).decode(data)
-    } catch (error: unknown) {
-      throw new Error('terminal input must be valid UTF-8', { cause: error })
-    }
-    this.terminal.write(text)
+    this.terminal.write(data)
   }
 
   // Local inspection is synchronous; the seam returns a promise for remote transports.
@@ -107,12 +93,12 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
     return foreground.processGroupId
   }
 
-  terminate(): void {
-    this.lifecycle.terminate()
-  }
-
-  async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    return await this.lifecycle.waitForExit(signal)
+  terminate(): Promise<void> {
+    if (this.cleanup !== undefined) return this.cleanup
+    const cleanup = this.closeOnce()
+    this.cleanup = cleanup
+    void cleanup.catch(() => { this.cleanup = undefined })
+    return cleanup
   }
 
   private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index e4dd4cfb44..e58c66f7fa 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -81,7 +81,7 @@ describe('LocalSubprocessService', () => {
     }
   })
 
-  it('validates terminal spawn specs before allocating a PTY', async () => {
+  it('validates terminal allocation inputs before allocating a PTY', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const base: SubprocessTerminalSpawnSpec = {
@@ -89,9 +89,6 @@ describe('LocalSubprocessService', () => {
     }
     await expect(ctx.subprocess.spawnTerminal({ ...base, argv: [] })).rejects.toThrow('must contain a program')
     await expect(ctx.subprocess.spawnTerminal({ ...base, argv: [''] })).rejects.toThrow('must contain a program')
-    await expect(ctx.subprocess.spawnTerminal({ ...base, rows: 1.5 })).rejects.toThrow('rows')
-    await expect(ctx.subprocess.spawnTerminal({ ...base, cols: 0 })).rejects.toThrow('cols')
-    await expect(ctx.subprocess.spawnTerminal({ ...base, graceMs: 0 })).rejects.toThrow('graceMs')
     await expect(ctx.subprocess.spawnTerminal({ ...base, signal: AbortSignal.abort('stop') })).rejects.toBe('stop')
     await fiber.dispose()
   })
@@ -99,8 +96,7 @@ describe('LocalSubprocessService', () => {
   it('terminates and joins an owned terminal during disposal', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
-    const terminate = vi.fn()
-    const waitForExit = vi.fn(async () => true)
+    const terminate = vi.fn(async () => {})
     const terminal: SubprocessTerminalHandle = {
       pid: 1,
       output: new PassThrough(),
@@ -109,13 +105,11 @@ describe('LocalSubprocessService', () => {
       inspectForeground: async () => undefined,
       signalForeground: async () => 1,
       terminate,
-      waitForExit,
     }
     const terminals = (ctx.subprocess as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
     terminals.add(terminal)
     await fiber.dispose()
     expect(terminate).toHaveBeenCalledOnce()
-    expect(waitForExit).toHaveBeenCalledOnce()
     expect(terminals.size).toBe(0)
   })
 
@@ -124,8 +118,8 @@ describe('LocalSubprocessService', () => {
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
     const runtimeRoot = service.runtimeRoot
-    const firstFailure = new Error('first retryable cleanup failure')
-    const secondFailure = new Error('second retryable cleanup failure')
+    const firstFailure = new Error('first cleanup failure')
+    const secondFailure = new Error('second cleanup failure')
     const disposalErrors: unknown[] = []
     ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
     const failedTerminal: SubprocessTerminalHandle = {
@@ -135,22 +129,19 @@ describe('LocalSubprocessService', () => {
       write: async () => {},
       inspectForeground: async () => undefined,
       signalForeground: async () => 1,
-      terminate: vi.fn(),
-      waitForExit: vi.fn(async () => { throw firstFailure }),
+      terminate: vi.fn(async () => { throw firstFailure }),
     }
     const secondFailedTerminal: SubprocessTerminalHandle = {
       ...failedTerminal,
-      terminate: vi.fn(),
-      waitForExit: vi.fn(async () => { throw secondFailure }),
+      terminate: vi.fn(async () => { throw secondFailure }),
     }
     let finishCleanup!: () => void
-    const cleanup = new Promise<boolean>((resolve) => {
-      finishCleanup = () => { resolve(true) }
+    const cleanup = new Promise<void>((resolve) => {
+      finishCleanup = resolve
     })
     const drainingTerminal: SubprocessTerminalHandle = {
       ...failedTerminal,
-      terminate: vi.fn(),
-      waitForExit: vi.fn(() => cleanup),
+      terminate: vi.fn(() => cleanup),
     }
     const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
     terminals.add(failedTerminal)
@@ -187,8 +178,7 @@ describe('LocalSubprocessService', () => {
       write: async () => {},
       inspectForeground: async () => undefined,
       signalForeground: async () => 1,
-      terminate: vi.fn(),
-      waitForExit: vi.fn(async () => { throw failure }),
+      terminate: vi.fn(async () => { throw failure }),
     }
     const terminals = (service as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals
     terminals.add(terminal)
@@ -247,7 +237,7 @@ describe('LocalSubprocessService', () => {
     }
   })
 
-  it('contains a terminal release failure after top-level exit', async () => {
+  it('retains a terminal whose automatic cleanup fails', async () => {
     let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
     const terminal = {
       pid: 123,
@@ -264,6 +254,8 @@ describe('LocalSubprocessService', () => {
     try {
       const { default: IsolatedLocalSubprocessService } = await import('../src/index.ts')
       const ctx = new Context()
+      const disposalErrors: unknown[] = []
+      ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
       const fiber = await ctx.plugin(IsolatedLocalSubprocessService)
       const alive = new Set([124])
       ;(ctx.subprocess as InstanceType<typeof IsolatedLocalSubprocessService>).terminalInspector = {
@@ -281,10 +273,9 @@ describe('LocalSubprocessService', () => {
       exitListener?.({ exitCode: 0 })
       await handle.done
       await new Promise(resolve => setTimeout(resolve, 10))
-      alive.clear()
-      handle.terminate()
-      await handle.waitForExit()
+      expect((ctx.subprocess as unknown as { terminals: Set<SubprocessTerminalHandle> }).terminals.size).toBe(1)
       await fiber.dispose()
+      expect(disposalErrors).toHaveLength(1)
     } finally {
       vi.doUnmock('node-pty')
       vi.resetModules()
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
index 456ce4ee8f..2eeb7c6a27 100644
--- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -89,7 +89,7 @@ describe('LocalTerminalHandle', () => {
     handle.output.on('data', (chunk: Buffer) => { chunks.push(chunk) })
 
     pty.emitData('hello €')
-    await handle.write(Buffer.from('input\r'))
+    await handle.write('input\r')
     expect(pty.writes).toEqual(['input\r'])
     expect(await handle.inspectForeground()).toEqual({ processGroupId: 456, inputWaiting: true })
     expect(await handle.signalForeground('SIGINT')).toBe(456)
@@ -98,16 +98,14 @@ describe('LocalTerminalHandle', () => {
     pty.emitExit(7, 9)
     pty.emitExit(0)
     expect(await handle.done).toEqual({ exitCode: null, signal: 'SIGKILL' })
-    expect(await handle.waitForExit()).toBe(true)
+    await handle.terminate()
     expect(Buffer.concat(chunks).toString('utf8')).toBe('hello €')
   })
 
-  it('rejects invalid input and unsafe foreground signals', async () => {
+  it('rejects unsafe foreground signals and writes after exit', async () => {
     const pty = new FakePty()
     const inspector = new FakeInspector()
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
-    await expect(handle.write(Uint8Array.from([0xff]))).rejects.toThrow('valid UTF-8')
-
     inspector.pgid = handle.pid
     await expect(handle.signalForeground('SIGKILL')).rejects.toThrow('terminate the terminal session')
     inspector.pgid = undefined
@@ -116,8 +114,8 @@ describe('LocalTerminalHandle', () => {
 
     pty.emitExit(3)
     expect(await handle.done).toEqual({ exitCode: 3, signal: null })
-    await handle.waitForExit()
-    await expect(handle.write(Buffer.from('late'))).rejects.toThrow('has exited')
+    await handle.terminate()
+    await expect(handle.write('late')).rejects.toThrow('has exited')
   })
 
   it('keeps the shell alive until forced descendants leave', async () => {
@@ -129,15 +127,14 @@ describe('LocalTerminalHandle', () => {
     inspector.removeOnSignal = false
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
 
-    handle.terminate()
-    const quiescent = handle.waitForExit()
+    const quiescent = handle.terminate()
     await vi.advanceTimersByTimeAsync(20)
     expect(inspector.processes).toContainEqual([124, 'SIGKILL'])
     expect(pty.kills).toEqual([])
 
     inspector.alive.delete(124)
     await vi.advanceTimersByTimeAsync(20)
-    expect(await quiescent).toBe(true)
+    await quiescent
     expect(pty.kills).toEqual(['SIGTERM'])
   })
 
@@ -149,17 +146,16 @@ describe('LocalTerminalHandle', () => {
     inspector.alive.add(124)
     inspector.removeOnSignal = false
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
-    const waiting = handle.waitForExit()
+    pty.emitExit()
+    const waiting = handle.terminate()
     let settled = false
     void waiting.then(() => { settled = true })
-
-    pty.emitExit()
     await vi.advanceTimersByTimeAsync(10)
     expect(settled).toBe(false)
 
     inspector.alive.delete(124)
     await vi.advanceTimersByTimeAsync(20)
-    expect(await waiting).toBe(true)
+    await waiting
   })
 
   it('cleans a same-session descendant after the top-level shell exits naturally', async () => {
@@ -172,7 +168,7 @@ describe('LocalTerminalHandle', () => {
 
     pty.emitExit()
 
-    expect(await handle.waitForExit()).toBe(true)
+    await handle.terminate()
     expect(inspector.processes).toEqual([[124, 'SIGTERM']])
   })
 
@@ -188,7 +184,7 @@ describe('LocalTerminalHandle', () => {
     inspector.members = []
     pty.emitExit()
 
-    expect(await handle.waitForExit()).toBe(true)
+    await handle.terminate()
     expect(inspector.processes).toEqual([[124, 'SIGTERM']])
   })
 
@@ -209,8 +205,7 @@ describe('LocalTerminalHandle', () => {
       return []
     }
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
-    handle.terminate()
-    await handle.waitForExit()
+    await handle.terminate()
     expect(inspector.processes).toEqual([[124, 'SIGTERM'], [125, 'SIGKILL']])
     expect(pty.kills).toEqual(['SIGTERM'])
   })
@@ -225,14 +220,13 @@ describe('LocalTerminalHandle', () => {
     }
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
 
-    handle.terminate()
-    await handle.waitForExit()
+    await handle.terminate()
 
     expect(inspector.processes).toEqual([[late.pid, 'SIGTERM']])
     expect(pty.kills).toEqual(['SIGTERM'])
   })
 
-  it('keeps a failed post-shell sweep retryable until its survivor leaves', async () => {
+  it('retries failed cleanup after a surviving descendant leaves', async () => {
     vi.useFakeTimers()
     const pty = new FakePty()
     const inspector = new FakeInspector()
@@ -244,14 +238,15 @@ describe('LocalTerminalHandle', () => {
     }
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
 
-    handle.terminate()
-    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pids: 124')
+    const first = handle.terminate()
+    const failed = expect(first).rejects.toThrow('surviving pids: 124')
     await vi.advanceTimersByTimeAsync(25)
     await failed
 
     inspector.alive.delete(late.pid)
-    handle.terminate()
-    expect(await handle.waitForExit()).toBe(true)
+    const retry = handle.terminate()
+    expect(retry).not.toBe(first)
+    await retry
     expect(inspector.processes).toEqual([[late.pid, 'SIGTERM'], [late.pid, 'SIGKILL']])
   })
 
@@ -268,82 +263,35 @@ describe('LocalTerminalHandle', () => {
       if (signal === 'SIGKILL') inspector.alive.delete(identity.pid)
     }
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
-    handle.terminate()
-    const quiescent = handle.waitForExit()
+    const quiescent = handle.terminate()
     await vi.advanceTimersByTimeAsync(25)
-    expect(await quiescent).toBe(true)
+    await quiescent
     expect(inspector.processes).toEqual([[124, 'SIGTERM'], [124, 'SIGKILL']])
   })
 
-  it('allows cleanup to retry after a surviving descendant leaves', async () => {
-    vi.useFakeTimers()
-    const pty = new FakePty()
-    const inspector = new FakeInspector()
-    inspector.members = [{ pid: 124, started: 'child' }]
-    inspector.alive.add(124)
-    inspector.removeOnSignal = false
-    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
-
-    handle.terminate()
-    const first = expect(handle.waitForExit(new AbortController().signal)).rejects.toThrow('surviving pids: 124')
-    await vi.advanceTimersByTimeAsync(25)
-    await first
-
-    inspector.alive.delete(124)
-    handle.terminate()
-    expect(await handle.waitForExit()).toBe(true)
-    expect(pty.kills).toEqual(['SIGTERM'])
-  })
-
-  it('bounds waits and reports a top-level process that ignores escalation', async () => {
+  it('reports a top-level process that ignores escalation', async () => {
     vi.useFakeTimers()
     const pty = new FakePty()
     pty.autoExitOnKill = false
     const handle = new LocalTerminalHandle(pty.asPty(), new FakeInspector(), 10)
-    expect(await handle.waitForExit(AbortSignal.abort())).toBe(false)
-    const controller = new AbortController()
-    const bounded = handle.waitForExit(controller.signal)
-    controller.abort()
-    expect(await bounded).toBe(false)
-
-    handle.terminate()
-    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pid: 123')
+    const failed = expect(handle.terminate()).rejects.toThrow('surviving pid: 123')
     await vi.advanceTimersByTimeAsync(25)
     await failed
     expect(pty.kills).toEqual(['SIGTERM', 'SIGKILL'])
 
     pty.emitExit(0, 999)
     expect(await handle.done).toEqual({ exitCode: null, signal: null })
-    handle.terminate()
-    expect(await handle.waitForExit()).toBe(true)
+    await handle.terminate()
   })
 
-  it('contains process races and reacts to lifetime cancellation', async () => {
+  it('contains process races while reporting surviving descendants', async () => {
     const pty = new FakePty()
     pty.throwKill = true
     const inspector = new FakeInspector()
     inspector.members = [{ pid: 124, started: 'child' }]
     inspector.alive.add(124)
     inspector.throwProcess = true
-    const controller = new AbortController()
-    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 1, controller.signal)
-    controller.abort()
-    const failed = expect(handle.waitForExit()).rejects.toThrow('surviving pids: 124')
-    await failed
-
-    inspector.alive.delete(124)
-    pty.throwKill = false
-    handle.terminate()
-    await handle.waitForExit()
-
-    const preAbortedPty = new FakePty()
-    const preAborted = new LocalTerminalHandle(
-      preAbortedPty.asPty(),
-      new FakeInspector(),
-      1,
-      AbortSignal.abort('stop'),
-    )
-    await preAborted.waitForExit()
-    expect(preAbortedPty.kills).toEqual(['SIGTERM'])
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 1)
+    await expect(handle.terminate()).rejects.toThrow('surviving pids: 124')
   })
 })
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 8e6c6a88e4..f8678464a9 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: d03824da33bb44b2525b1343a27557ed15823418
-README.zh.md: 34cc75c3cfc8148754343e92b0c204760b1fb543
+README.md: 2fca5cdd08f3cbd36d8ef492226c91681b5568d0
+README.zh.md: 5830d0fc394160bc557e24646cc76d4bcfead13c
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index d03824da33..2fca5cdd08 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -11,8 +11,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 - The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
-- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, valid-UTF-8 byte I/O, foreground-process-group inspection/signalling, TERM-to-KILL whole-session cleanup, and a quiescence wait. The output stream ends after queued output when the top-level process exits; a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or prove and clean the complete terminal session; readiness, scrollback, and owner policy remain in the PTY consumer.
-- `SubprocessTerminalLifecycle` composes a handle's top-level `done` promise with its provider-owned session cleanup. It binds lifetime cancellation, shares one active cleanup attempt, permits a failed attempt to retry, normalizes cleanup rejections, and bounds quiescence observation without knowing the provider's process mechanics.
+- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, UTF-8 text I/O, foreground-process-group inspection/signalling, and one awaited `terminate()` operation that reaches whole-session quiescence and settles in-flight handle calls. The spec signal cancels allocation only; the published handle owns its lifetime. The output stream ends after queued output when the top-level process exits, and a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or clean the complete terminal session; readiness, scrollback, and owner policy remain in the PTY consumer.
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 34cc75c3cf..5830d0fc39 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -11,8 +11,7 @@
 - spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的进程管理器默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 形状：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、有效 UTF-8 字节 I/O、前台进程组检查／信号发送、TERM→KILL 全会话清理，以及等待完全停稳。顶层进程退出后，输出流会在排完队列中的输出后结束；存活期间的传输故障会拒绝 `done`。这些操作仍属于一项基底原语，因为普通管道无法分配控制终端，也无法证明并清理完整的终端会话；就绪检测、scrollback 与所有者策略仍归 PTY 消费方所有。
-- `SubprocessTerminalLifecycle` 把句柄的顶层 `done` promise 与由提供方负责的会话清理组合起来。它绑定生命周期取消，共享同一个进行中的清理尝试，允许失败的尝试重试，规范化清理拒绝，并在不了解提供方进程机制的情况下对完全停稳观测施加上限。
+- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使整个会话完全停稳，并让所有在途句柄调用结算。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出后，输出流会在排完队列中的输出后结束；存活期间的传输故障会拒绝 `done`。这些操作仍属于一项基底原语，因为普通管道无法分配控制终端，也无法清理完整的终端会话；就绪检测、scrollback 与所有者策略仍归 PTY 消费方所有。
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的凭据清除定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地普通 spawn 与终端 spawn 都应用这一定义；自行拥有 spawn 的 SDK 管理传输层可以直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index df79ee5f3e..e1749203dd 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -14,8 +14,6 @@ import type { SubprocessHandle, SubprocessSpawnSpec } from './types.ts'
 import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from './types.ts'
 
 export { DSH_ENV_PREFIX } from './types.ts'
-export { SubprocessTerminalLifecycle } from './terminal-lifecycle.ts'
-export type { SubprocessTerminalLifecycleOptions } from './terminal-lifecycle.ts'
 export type {
   CollectedOutput,
   DshEnvironment,
@@ -95,10 +93,11 @@ declare module 'cordis' {
  *   quiescence.
  * - Disposal of the service terminates all still-running managed processes
  *   and awaits their exit.
- * - {@link spawnTerminal} owns terminal allocation, byte transport,
- *   foreground groups, signalling, and whole-session quiescence; readiness
- *   and persistent-shell policy stay in the PTY consumer. Its output stream
- *   ends after queued terminal output when the top-level process exits.
+ * - {@link spawnTerminal} owns terminal allocation, text transport,
+ *   foreground groups, signalling, and whole-session quiescence behind one
+ *   awaited termination method; readiness and persistent-shell policy stay
+ *   in the PTY consumer. Its output stream ends after queued terminal output
+ *   when the top-level process exits.
  */
 export abstract class SubprocessService extends Service {
   constructor(ctx: Context) {
@@ -138,7 +137,7 @@ export abstract class SubprocessService extends Service {
    * Allocate a real terminal and start one owned process session. This is the
    * only non-pipe process primitive: implementations own terminal byte I/O,
    * foreground groups, signals, and complete session-tree cleanup.
-   * @param spec - fully specified argv, cwd, environment, dimensions, grace, and cancellation.
+   * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
    * @returns the live terminal handle after allocation succeeds.
    */
   abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
diff --git a/packages/subprocess/subprocess/src/terminal-lifecycle.ts b/packages/subprocess/subprocess/src/terminal-lifecycle.ts
deleted file mode 100644
index 76430fe7c6..0000000000
--- a/packages/subprocess/subprocess/src/terminal-lifecycle.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-/** Provider-neutral lifecycle transaction for terminal-process handles. */
-
-/** Inputs owned by one terminal-process lifecycle controller. */
-export interface SubprocessTerminalLifecycleOptions {
-  /** Settlement of the top-level terminal process or its live transport. */
-  readonly done: Promise<unknown>
-  /** Provider-owned cleanup that reaches whole-session quiescence. */
-  readonly cleanup: () => Promise<void>
-  /** Optional cancellation for the complete terminal lifetime. */
-  readonly signal?: AbortSignal | undefined
-}
-
-function normalizeCleanupError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error))
-}
-
-/**
- * Coordinates terminal cleanup without knowing how a provider allocates or
- * terminates its process session. One active cleanup attempt is shared by all
- * callers; a rejected attempt may be retried, and successful cleanup removes
- * the lifetime abort listener.
- */
-export class SubprocessTerminalLifecycle {
-  private cleanupAttempt: Promise<void> | undefined
-  private removeLifetimeAbort: (() => void) | undefined
-
-  /**
-   * @param options - top-level settlement, provider cleanup, and lifetime cancellation.
-   */
-  constructor(private readonly options: SubprocessTerminalLifecycleOptions) {
-    const onDone = (): void => { this.terminate() }
-    void options.done.then(onDone, onDone)
-
-    if (options.signal !== undefined) {
-      const onAbort = (): void => { this.terminate() }
-      options.signal.addEventListener('abort', onAbort, { once: true })
-      this.removeLifetimeAbort = () => { options.signal?.removeEventListener('abort', onAbort) }
-      if (options.signal.aborted) this.terminate()
-    }
-  }
-
-  /** Begin an idempotent provider cleanup attempt. */
-  terminate(): void {
-    void this.startCleanup().catch(() => {})
-  }
-
-  /**
-   * Wait for top-level settlement and successful whole-session cleanup.
-   * @param signal - optional bound for this observation only.
-   * @returns true after quiescence, false when the observer signal aborts first.
-   */
-  async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    const quiescence = this.cleanupAttempt ?? this.options.done.then(
-      () => this.startCleanup(),
-      () => this.startCleanup(),
-    )
-    if (signal === undefined) {
-      await quiescence
-      return true
-    }
-    if (signal.aborted) return false
-
-    return await new Promise<boolean>((resolve, reject) => {
-      let settled = false
-      const finish = (complete: () => void): void => {
-        if (settled) return
-        settled = true
-        signal.removeEventListener('abort', onAbort)
-        complete()
-      }
-      const onAbort = (): void => { finish(() => { resolve(false) }) }
-
-      signal.addEventListener('abort', onAbort, { once: true })
-      if (signal.aborted) onAbort()
-      void quiescence.then(
-        () => { finish(() => { resolve(true) }) },
-        (error: unknown) => { finish(() => { reject(normalizeCleanupError(error)) }) },
-      )
-    })
-  }
-
-  private startCleanup(): Promise<void> {
-    if (this.cleanupAttempt !== undefined) return this.cleanupAttempt
-
-    const outcome = Promise.withResolvers<void>()
-    this.cleanupAttempt = outcome.promise.catch((error: unknown) => {
-      this.cleanupAttempt = undefined
-      throw normalizeCleanupError(error)
-    })
-    void this.cleanupAttempt.then(
-      () => {
-        this.removeLifetimeAbort?.()
-        this.removeLifetimeAbort = undefined
-      },
-      () => {},
-    )
-    try {
-      void this.options.cleanup().then(outcome.resolve, outcome.reject)
-    } catch (error: unknown) {
-      outcome.reject(error)
-    }
-    return this.cleanupAttempt
-  }
-}
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index 206104ad5b..6b606fd870 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -210,7 +210,7 @@ export interface SubprocessTerminalSpawnSpec {
   cols: number
   /** TERM-to-KILL cleanup grace for the complete terminal session. */
   graceMs: number
-  /** Cancellation of setup or the live terminal session. */
+  /** Cancellation of terminal allocation; a published handle owns its later lifetime. */
   signal?: AbortSignal | undefined
 }
 
@@ -236,10 +236,10 @@ export interface SubprocessTerminalHandle {
   /** Resolves when the top-level process exits; rejects only for a live transport failure. */
   readonly done: Promise<SubprocessOutcome>
   /**
-   * Write bytes to the terminal input.
-   * @param data - valid UTF-8 bytes to deliver without implicit newline conversion.
+   * Write text to the terminal input.
+   * @param data - text to deliver without implicit newline conversion.
    */
-  write(data: Uint8Array): Promise<void>
+  write(data: string): Promise<void>
   /**
    * Inspect the current foreground process group.
    * @returns its id and input-wait fact, or undefined when no foreground group can be resolved.
@@ -251,12 +251,9 @@ export interface SubprocessTerminalHandle {
    * @returns the exact group id that received it.
    */
   signalForeground(signal: SubprocessTerminalSignal): Promise<number>
-  /** Begin idempotent TERM-to-KILL cleanup of the complete terminal session. */
-  terminate(): void
   /**
-   * Await whole-session quiescence, not only top-level process exit.
-   * @param signal - optional bound for this wait.
-   * @returns true after quiescence, false when `signal` aborts first.
+   * Idempotently terminate the complete terminal session and await whole-session quiescence.
+   * After settlement, no write, inspection, or signal call remains in flight.
    */
-  waitForExit(signal?: AbortSignal): Promise<boolean>
+  terminate(): Promise<void>
 }
diff --git a/packages/subprocess/subprocess/tests/service.spec.ts b/packages/subprocess/subprocess/tests/service.spec.ts
index 853b333400..9f321caf54 100644
--- a/packages/subprocess/subprocess/tests/service.spec.ts
+++ b/packages/subprocess/subprocess/tests/service.spec.ts
@@ -48,8 +48,7 @@ class StubSubprocessService extends SubprocessService {
       write: async () => {},
       inspectForeground: async () => ({ processGroupId: 1, inputWaiting: true }),
       signalForeground: async () => 1,
-      terminate: () => {},
-      waitForExit: async () => true,
+      terminate: async () => {},
     }
   }
 }
diff --git a/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts b/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts
deleted file mode 100644
index 2dd688bbc0..0000000000
--- a/packages/subprocess/subprocess/tests/terminal-lifecycle.spec.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
-
-describe('SubprocessTerminalLifecycle', () => {
-  it('waits for top-level settlement and the provider cleanup transaction', async () => {
-    const done = Promise.withResolvers<undefined>()
-    const cleanupGate = Promise.withResolvers<undefined>()
-    const cleanup = vi.fn(() => cleanupGate.promise)
-    const lifecycle = new SubprocessTerminalLifecycle({ done: done.promise, cleanup })
-
-    const waiting = lifecycle.waitForExit()
-    expect(cleanup).not.toHaveBeenCalled()
-    done.resolve(undefined)
-    await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() })
-
-    const observed = vi.fn()
-    void waiting.then(observed)
-    await Promise.resolve()
-    expect(observed).not.toHaveBeenCalled()
-
-    cleanupGate.resolve(undefined)
-    await expect(waiting).resolves.toBe(true)
-    lifecycle.terminate()
-    await expect(lifecycle.waitForExit()).resolves.toBe(true)
-    expect(cleanup).toHaveBeenCalledOnce()
-  })
-
-  it('normalizes cleanup failures, permits retries, and retains lifetime cancellation until success', async () => {
-    const done = Promise.withResolvers<undefined>()
-    const lifetime = new AbortController()
-    const removeListener = vi.spyOn(lifetime.signal, 'removeEventListener')
-    const synchronousFailure = new Error('first cleanup failed')
-    let attempt = 0
-    const cleanup = vi.fn((): Promise<void> => {
-      attempt += 1
-      if (attempt === 1) throw synchronousFailure
-      if (attempt === 2) {
-        return Promise.resolve().then(() => {
-          const nonErrorRejection: unknown = 'cleanup transport gone'
-          throw nonErrorRejection
-        })
-      }
-      return Promise.resolve()
-    })
-    const lifecycle = new SubprocessTerminalLifecycle({
-      done: done.promise,
-      cleanup,
-      signal: lifetime.signal,
-    })
-
-    lifecycle.terminate()
-    await expect(lifecycle.waitForExit()).rejects.toBe(synchronousFailure)
-    lifecycle.terminate()
-    await expect(lifecycle.waitForExit()).rejects.toThrow('cleanup transport gone')
-
-    lifetime.abort()
-    await expect(lifecycle.waitForExit()).resolves.toBe(true)
-    expect(cleanup).toHaveBeenCalledTimes(3)
-    expect(removeListener).toHaveBeenCalledWith('abort', expect.any(Function))
-
-    done.reject(new Error('top-level transport failed'))
-    await Promise.resolve()
-    expect(cleanup).toHaveBeenCalledTimes(3)
-  })
-
-  it('starts cleanup for a pre-aborted lifetime and bounds a wait that is already aborted', async () => {
-    const cleanupGate = Promise.withResolvers<undefined>()
-    const cleanup = vi.fn(() => cleanupGate.promise)
-    const lifecycle = new SubprocessTerminalLifecycle({
-      done: new Promise(() => {}),
-      cleanup,
-      signal: AbortSignal.abort(new Error('lifetime cancelled')),
-    })
-
-    expect(cleanup).toHaveBeenCalledOnce()
-    await expect(lifecycle.waitForExit(AbortSignal.abort())).resolves.toBe(false)
-    cleanupGate.resolve(undefined)
-    await expect(lifecycle.waitForExit()).resolves.toBe(true)
-  })
-
-  it('contains cleanup settlement after an observer aborts between signal checks', async () => {
-    const firstCleanup = Promise.withResolvers<undefined>()
-    const cleanup = vi.fn()
-      .mockImplementationOnce(() => firstCleanup.promise)
-      .mockResolvedValueOnce(undefined)
-    const lifecycle = new SubprocessTerminalLifecycle({ done: Promise.resolve(), cleanup })
-    const observer = new AbortController().signal
-    vi.spyOn(observer, 'aborted', 'get')
-      .mockReturnValueOnce(false)
-      .mockReturnValueOnce(true)
-
-    await expect(lifecycle.waitForExit(observer)).resolves.toBe(false)
-    firstCleanup.reject(new Error('late cleanup failure'))
-    await vi.waitFor(() => { expect(cleanup).toHaveBeenCalledOnce() })
-    await Promise.resolve()
-
-    lifecycle.terminate()
-    await expect(lifecycle.waitForExit()).resolves.toBe(true)
-    expect(cleanup).toHaveBeenCalledTimes(2)
-  })
-
-  it('reports bounded cleanup success and failure', async () => {
-    const successful = new SubprocessTerminalLifecycle({
-      done: Promise.resolve(),
-      cleanup: async () => {},
-    })
-    await expect(successful.waitForExit(new AbortController().signal)).resolves.toBe(true)
-
-    const failure = new Error('quiescence failed')
-    const failed = new SubprocessTerminalLifecycle({
-      done: Promise.resolve(),
-      cleanup: () => Promise.reject(failure),
-    })
-    await expect(failed.waitForExit(new AbortController().signal)).rejects.toBe(failure)
-
-    const failedDone = Promise.withResolvers<undefined>()
-    const afterTransportFailure = new SubprocessTerminalLifecycle({
-      done: failedDone.promise,
-      cleanup: async () => {},
-    })
-    const waiting = afterTransportFailure.waitForExit()
-    failedDone.reject(new Error('transport failed'))
-    await expect(waiting).resolves.toBe(true)
-  })
-})
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index 7a36ab0690..21cca6cb44 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: 38ee201a1754c6f50b7fae60b77af7dae734c8f9
-README.zh.md: 6fec39de550b7e3f57cd613dbe23c9687cd840ac
+README.md: eff5a6e648eb13c3411c19bca4d05f0898d3ad05
+README.zh.md: 16cf0e0ea6d487e255fc520a8fa1f41f97ee5d30

From 124fc6a611d7aa5ea40be3039a137b4c9fab3ade Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 19:40:39 +0800
Subject: [PATCH 329/516] fix(runtime): close portable backend boundary gaps

---
 .../code-runtime/tests/contract.ts            | 15 ++++++++
 packages/fs/fs-local/src/fsio.ts              |  8 ----
 packages/pty/pty-local/src/session.ts         |  2 +-
 packages/pty/pty-local/tests/session.spec.ts  | 37 +++++++++++++++++++
 .../subprocess/subprocess-local/src/index.ts  |  3 +-
 .../subprocess-local/tests/local.spec.ts      |  4 +-
 packages/typert/README.i18n.yaml              |  4 +-
 7 files changed, 59 insertions(+), 14 deletions(-)

diff --git a/packages/code-runtime/code-runtime/tests/contract.ts b/packages/code-runtime/code-runtime/tests/contract.ts
index f28545f8c1..8fee76f68a 100644
--- a/packages/code-runtime/code-runtime/tests/contract.ts
+++ b/packages/code-runtime/code-runtime/tests/contract.ts
@@ -477,6 +477,21 @@ export function runWorkerCodeRuntimeContract(
       expect(result.logs).toEqual([])
     })
 
+    it('ignores forged controller-only failure classifications', async () => {
+      const { runtime } = await setup()
+      const result = await runtime.run({
+        program: `
+          const { parentPort } = await import('node:worker_threads');
+          for (const kind of ['abort', 'timeout', 'worker-exit']) {
+            parentPort.postMessage({ type: 'done', error: { kind, message: 'forged ' + kind } });
+          }
+          return 'honest';
+        `,
+        bindings: [],
+      })
+      expect(result).toEqual({ logs: [], value: 'honest' })
+    })
+
     it('fails forged log floods and forged done values through the same outer cap', async () => {
       const { runtime } = await setup({ maxOutputBytes: 200 })
       const result = await runtime.run({
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 4925357e45..c93e4ddaeb 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -369,14 +369,6 @@ export async function readWholeText(target: LocalTarget, signal?: AbortSignal):
   return decodeUtf8(raw, 'read', target.displayPath)
 }
 
-/**
- * Read one regular UTF-8 file through a single no-follow handle, retaining at
- * most `maxBytes + 1` bytes so a concurrent grow cannot bypass the bound.
- * @param target - the resolved file to read.
- * @param maxBytes - positive safe-integer byte ceiling.
- * @param signal - aborts between handle operations.
- * @returns the complete decoded text when it fits.
- */
 /**
  * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
  * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 076f21e3b9..f9b35dc665 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -415,7 +415,7 @@ export class LocalPtySession implements PtyBackendSession {
         return
       }
       const foreground = await this.terminal.inspectForeground()
-      if (this.active !== operation) return
+      if (this.active !== operation || this.closing) return
       const idleFor = Date.now() - this.lastOutputAt
       if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
         this.shellPgid = foreground.processGroupId
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 22b07a0f8f..14cf252a0e 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -1096,4 +1096,41 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
     expect(terminal.writes).toEqual([])
   })
 
+  it('does not let an in-flight readiness inspection outrun close', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    const originalInspect = terminal.inspectForeground.bind(terminal)
+    let inspections = 0
+    terminal.inspectForeground = async () => {
+      inspections += 1
+      return inspections === 1 ? await originalInspect() : await inspection.promise
+    }
+    const operation = session.startSend({ text: 'pending readiness', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    terminal.emitData('\x1b]133;D;0\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    expect(inspections).toBe(2)
+
+    const termination = Promise.withResolvers<undefined>()
+    terminal.terminate = async () => {
+      await termination.promise
+      terminal.emitExit(0, 15)
+    }
+    const closing = session.close('in-flight readiness')
+    let settled = false
+    void operation.done.then(() => { settled = true })
+    inspection.resolve({ processGroupId: 456, inputWaiting: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(settled).toBe(false)
+
+    termination.resolve(undefined)
+    await closing
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
 })
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 0d02f0e387..46d179a7b2 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -59,9 +59,10 @@ export class LocalSubprocessService extends SubprocessService {
         pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))
       }
       for (const terminal of this.terminals) {
-        pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
+        pending.push(terminal.terminate())
       }
       this.live.clear()
+      this.terminals.clear()
       const outcomes = [
         ...await Promise.allSettled(pending),
         ...await Promise.allSettled([rm(this.runtimeRoot, { recursive: true, force: true })]),
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index e58c66f7fa..ff83141fab 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -113,7 +113,7 @@ describe('LocalSubprocessService', () => {
     expect(terminals.size).toBe(0)
   })
 
-  it('waits for every terminal cleanup, removes runtime state, and retains rejections', async () => {
+  it('waits for every terminal cleanup and clears single-shot teardown ownership', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
@@ -154,7 +154,7 @@ describe('LocalSubprocessService', () => {
     expect(disposed).toBe(false)
     finishCleanup()
     await disposing
-    expect(terminals).toEqual(new Set([failedTerminal, secondFailedTerminal]))
+    expect(terminals.size).toBe(0)
     await expect(stat(runtimeRoot)).rejects.toMatchObject({ code: 'ENOENT' })
     expect(disposalErrors).toHaveLength(1)
     expect(disposalErrors[0]).toMatchObject({
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index 21cca6cb44..5e93edd997 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/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/code-runtime/code-runtime-subprocess/README.md
-README.md: eff5a6e648eb13c3411c19bca4d05f0898d3ad05
-README.zh.md: 16cf0e0ea6d487e255fc520a8fa1f41f97ee5d30
+README.md: 152921a1ed595676781aad170e3396f7ce613161
+README.zh.md: 3e8223c33c7ce85f342c9a36ab5a24c4d2a6cb94

From 674d23118bfa894e13142d8cc1746dd74c39fba0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 20:20:51 +0800
Subject: [PATCH 330/516] fix(runtime): close measured portability defects

---
 packages/lsp/lsp-local/src/host.ts            |  5 +--
 packages/lsp/lsp-local/src/index.ts           | 38 ++++++++--------
 packages/lsp/lsp-local/tests/host.spec.ts     |  4 +-
 packages/lsp/lsp-local/tests/provider.spec.ts | 44 +++++++++++++++++++
 packages/pty/pty-local/src/session.ts         |  2 +-
 packages/pty/pty-local/tests/session.spec.ts  |  6 +--
 6 files changed, 73 insertions(+), 26 deletions(-)

diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts
index b8939a2ae4..ffba6a1344 100644
--- a/packages/lsp/lsp-local/src/host.ts
+++ b/packages/lsp/lsp-local/src/host.ts
@@ -100,15 +100,14 @@ export async function readHostSource(
     for await (const chunk of stream) {
       throwIfAborted(signal)
       bytes += Buffer.byteLength(chunk)
-      if (bytes > maxDocumentBytes) {
-        throw new Error(`source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit`)
-      }
+      if (bytes > maxDocumentBytes) break
       chunks.push(chunk)
     }
   } catch (error: unknown) {
     throwIfAborted(signal)
     throw new Error(`source "${filePath}" could not be read: ${messageOf(error)}`, { cause: error })
   }
+  if (bytes > maxDocumentBytes) throw new Error(`source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit`)
   throwIfAborted(signal)
   return {
     fileUrl: fs.fileUrl(target),
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index f3f45959e5..0e9468cba9 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -129,27 +129,29 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
   const providers = await (async () => {
+    const lookups = entries.map(async ([providerId, rawConfig]) => {
+      if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
+      const resolved = rawConfig as ResolvedServerConfig
+      validateServerConfig(providerId, resolved)
+      const executable = await ctx.subprocess.resolveExecutable(
+        resolved.command,
+        resolved.env,
+        setupAbort.signal,
+      )
+      setupAbort.signal.throwIfAborted()
+      return new LocalLspProvider(
+        providerId,
+        ctx.fs,
+        resolved,
+        executable,
+        spec => ctx.subprocess.spawn(spec),
+      )
+    })
     try {
-      return await Promise.all(entries.map(async ([providerId, rawConfig]) => {
-        if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
-        const resolved = rawConfig as ResolvedServerConfig
-        validateServerConfig(providerId, resolved)
-        const executable = await ctx.subprocess.resolveExecutable(
-          resolved.command,
-          resolved.env,
-          setupAbort.signal,
-        )
-        setupAbort.signal.throwIfAborted()
-        return new LocalLspProvider(
-          providerId,
-          ctx.fs,
-          resolved,
-          executable,
-          spec => ctx.subprocess.spawn(spec),
-        )
-      }))
+      return await Promise.all(lookups)
     } catch (error: unknown) {
       setupAbort.abort(error)
+      await Promise.allSettled(lookups)
       throw error
     } finally {
       stopSetupCancellation()
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index eea3851414..c97defc086 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -158,7 +158,9 @@ describe('readHostSource', () => {
 
   it('rejects an oversized source', async () => {
     await writeFile(join(ws, 'big.ts'), 'x'.repeat(100))
-    await expect(readSource('big.ts', 10)).rejects.toThrow(/10-byte limit/)
+    await expect(readSource('big.ts', 10)).rejects.toMatchObject({
+      message: 'source "big.ts" exceeds the 10-byte limit',
+    })
   })
 
   it('counts the complete UTF-8 byte length at the configured boundary', async () => {
diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts
index 8d8a7ad356..88b2b0144f 100644
--- a/packages/lsp/lsp-local/tests/provider.spec.ts
+++ b/packages/lsp/lsp-local/tests/provider.spec.ts
@@ -195,6 +195,50 @@ describe('lsp-local provider resolution', () => {
     await ctx.fiber.dispose()
   })
 
+  it('waits for aborted sibling executable lookups before setup rejects', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+    const slowStarted = Promise.withResolvers<undefined>()
+    const slowAborted = Promise.withResolvers<undefined>()
+    const releaseCleanup = Promise.withResolvers<undefined>()
+    vi.spyOn(ctx.subprocess, 'resolveExecutable').mockImplementation(async (command, _env, signal) => {
+      if (signal === undefined) throw new Error('missing setup signal')
+      if (command === 'slow-lsp') {
+        return await new Promise<string>((_resolve, reject) => {
+          const onAbort = (): void => {
+            slowAborted.resolve(undefined)
+            void releaseCleanup.promise.then(() => {
+              reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+            })
+          }
+          signal.addEventListener('abort', onAbort, { once: true })
+          slowStarted.resolve(undefined)
+          if (signal.aborted) onAbort()
+        })
+      }
+      await slowStarted.promise
+      throw new Error('lookup failed')
+    })
+
+    const loading = ctx.plugin(LspLocal, {
+      servers: {
+        slow: { command: 'slow-lsp', extensionToLanguage: { '.ts': 'typescript' } },
+        failing: { command: 'failing-lsp', extensionToLanguage: { '.js': 'javascript' } },
+      },
+    })
+    await slowAborted.promise
+    let settled = false
+    void loading.then(() => { settled = true }, () => { settled = true })
+    await new Promise<void>((resolve) => { setImmediate(resolve) })
+    expect(settled).toBe(false)
+
+    releaseCleanup.resolve(undefined)
+    await expect(loading).rejects.toThrow('lookup failed')
+    await ctx.fiber.dispose()
+  })
+
   it('aborts executable resolution when disposed during setup', async () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index f9b35dc665..5517cd902d 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -237,7 +237,7 @@ export class LocalPtySession implements PtyBackendSession {
     }
     this.activeDeadlineTimer = setTimeout(() => {
       if (this.active === operation) {
-        this.settleActive('timeout', this.activeWrite?.operation === operation)
+        this.settleActive('timeout', this.activeWrite?.operation === operation || this.interrupting === operation)
       }
     }, this.config.timeoutMs)
     void this.beginSend(operation, request)
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 14cf252a0e..fbe0aa807b 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -365,11 +365,11 @@ describe('LocalPtySession readiness and output', () => {
     expect(operation.cancel()).toBe(true)
 
     terminal.emitData('\x1b]133;D;130\x07dsh> ')
-    await vi.advanceTimersByTimeAsync(10)
+    await vi.advanceTimersByTimeAsync(100)
+    expect((await operation.done).waitReason).toBe('timeout')
     expect(() => session.startSend({ text: 'successor', submit: true })).toThrow('active send')
     signalGate.resolve(undefined)
-    await vi.advanceTimersByTimeAsync(10)
-    await operation.done
+    await vi.advanceTimersByTimeAsync(0)
     expect(inspector.groups).toContainEqual([456, 'SIGINT'])
     expect(inspector.groups).not.toContainEqual([789, 'SIGINT'])
   })

From b71dbbe766edc0646a4f7c073d45867bb3248684 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 21:19:27 +0800
Subject: [PATCH 331/516] fix(runtime): close review lifecycle and bound gaps

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  2 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |  4 +-
 .../2026-07-16-persistent-pty-sessions.md     |  2 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  |  2 +-
 docs/config-catalog.md                        |  2 +-
 .../code-runtime-worker/src/runtime-host.ts   |  1 +
 packages/lsp/lsp-local/src/index.ts           | 16 ++++-
 .../lsp/lsp-local/tests/lifecycle.spec.ts     | 72 +++++++++++++++++++
 packages/pty/pty-local/README.i18n.yaml       |  4 +-
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           | 20 +++---
 packages/pty/pty-local/src/index.ts           |  8 ++-
 packages/pty/pty-local/tests/index.spec.ts    | 18 ++++-
 15 files changed, 130 insertions(+), 29 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 7b6a74b7e8..a7eaaa2e3a 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: d68fc92308079aa68a8f4e1accadde0addb0e5aa
-2026-07-28-portable-execution-world-consumers.zh.md: 5341cf1643cabb1043b977e18179dc857e37e121
+2026-07-28-portable-execution-world-consumers.md: 260f38981ea0cd034f506594057483c6ccfa9617
+2026-07-28-portable-execution-world-consumers.zh.md: 0bf7b4dd1a87378b76f6a71343a8cb78766b7b3a
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index d68fc92308..260f38981e 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -22,7 +22,7 @@ Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals and delegates complete-session quiescence to the handle's awaited termination operation.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals and delegates complete-session quiescence to the handle's awaited termination operation.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. The fixed runner is adapter-owned infrastructure below `ctx.subprocess.runtimeRoot`, so its write carries an explicit `danger-full-access` policy instead of inheriting the model-facing filesystem mode. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 5341cf1643..0bf7b4dd1a 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 2694664183..72944d7433 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: f94dd57622c555e195564cc2eee9b3228841d5cc
-2026-07-16-persistent-pty-sessions.zh.md: 6228571a6496e9d4cb031a2df958b80dee102fd3
+2026-07-16-persistent-pty-sessions.md: 88296a9318b2c398fead382153bd2c652dbd9e68
+2026-07-16-persistent-pty-sessions.zh.md: 40f26c67fe046ad292f05919501600bd2e146c62
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index f94dd57622..88296a9318 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -41,7 +41,7 @@ Agent-scope disposal closes registrations first, then awaits quiescent teardown
 A registered `shell` backend constrains how a terminal starts; it does not constrain commands typed after startup. `dsh-pty-local` therefore applies two protections before spawning:
 
 - It supplies only terminal-specific environment overrides; the mounted subprocess provider applies the shared credential-shaped-name scrub before merging them.
-- It requires `ctx.sandbox` and the shared `ctx.sandboxPolicy`. At spawn, the backend resolves the owner's effective session mode over the deployment default and wraps the shell argv once; that mode and workspace root remain the process boundary for the PTY lifetime. A write that would change the effective `sandbox/mode` is rejected before commit while the owner has any open PTY or unpublished spawn, with an instruction to wait for creation to settle and close those sessions first; same-effective-mode writes remain valid. The pending reservation spans backend setup through publication, so there is no race in which a wider terminal appears after a downgrade. `danger-full-access` is the existing explicit unconfined choice rather than a PTY-specific bypass.
+- It requires the shared `ctx.sandboxPolicy`. At spawn, the backend resolves the owner's effective session mode over the deployment default; `danger-full-access` starts the shell directly, while confined modes require a same-world `ctx.sandbox` provider and wrap the shell argv once. That mode and workspace root remain the process boundary for the PTY lifetime. A write that would change the effective `sandbox/mode` is rejected before commit while the owner has any open PTY or unpublished spawn, with an instruction to wait for creation to settle and close those sessions first; same-effective-mode writes remain valid. The pending reservation spans backend setup through publication, so there is no race in which a wider terminal appears after a downgrade. `danger-full-access` is the existing explicit unconfined choice rather than a PTY-specific bypass.
 
 Sandboxing confines local process effects but does not make arbitrary shell input safe: network calls and other external side effects remain governed by deployment policy. Tool descriptions state that PTY sessions are less auditable than one-shot tools and should be used only when persistence or interactive stdin is necessary.
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 6228571a64..40f26c67fe 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -41,7 +41,7 @@ agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出
 注册的 `shell` 后端只约束终端如何启动，不约束启动后输入的命令。因此 `dsh-pty-local` 在 spawn 前应用两层保护：
 
 - 它只提供终端专用的环境覆盖；挂载的子进程提供方先清除名称形似凭据的环境变量，再合并这些覆盖。
-- 它要求 `ctx.sandbox` 和共享的 `ctx.sandboxPolicy`。后端在 spawn 时，以部署默认值为底折叠 owner 的有效 session mode，并只包装一次 shell argv；该 mode 与 workspace root 在 PTY 的整个生命周期中充当进程边界。只要 owner 有任何已打开的 PTY 或尚未发布的 spawn，任何会改变生效 `sandbox/mode` 的写入都会在提交前被拒绝，并提示先等待创建操作结算，再关闭这些会话；不会改变生效模式的写入仍然有效。这项进行中的预留从后端 setup 持续到发布完成，因此不存在降级后又出现权限更宽的终端这一竞态。`danger-full-access` 是现有的显式无约束选择，不另设 PTY 私有 bypass。
+- 它要求共享的 `ctx.sandboxPolicy`。后端在 spawn 时，以部署默认值为底折叠 owner 的有效 session mode；`danger-full-access` 会直接启动 shell，受限模式则要求同一执行世界中存在 `ctx.sandbox` 提供方，并只包装一次 shell argv。该 mode 与 workspace root 在 PTY 的整个生命周期中充当进程边界。只要 owner 有任何已打开的 PTY 或尚未发布的 spawn，任何会改变生效 `sandbox/mode` 的写入都会在提交前被拒绝，并提示先等待创建操作结算，再关闭这些会话；不会改变生效模式的写入仍然有效。这项进行中的预留从后端 setup 持续到发布完成，因此不存在降级后又出现权限更宽的终端这一竞态。`danger-full-access` 是现有的显式无约束选择，不另设 PTY 私有 bypass。
 
 沙箱限制本地进程副作用，但不会让任意 shell 输入自动安全：网络调用和其他外部副作用仍由部署策略治理。工具描述会说明 PTY 会话比一次性工具更难审计，只应在确实需要持久状态或交互式 stdin 时使用。
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index b70f468960..0514cdd969 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1072,7 +1072,7 @@ Source: [`packages/plan/plan-mode/src/index.ts:69`](../packages/plan/plan-mode/s
 
 ## `@deepseek-ai/dsh-pty-local`
 
-Requires: `pty` · `sandbox` · `sandboxPolicy` · `subprocess`
+Requires: `pty` · `sandboxPolicy` · `subprocess`
 
 ```ts config-catalog
 /** Public plugin configuration. */
diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
index 474a058e9f..d2bb1082b8 100644
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -223,4 +223,5 @@ export class RuntimeOutputLedger {
 }
 
 export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
+export { jsonValueBytesUpTo } from './output-json.ts'
 export type { WorkerJsonWire } from './worker-json.ts'
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index 0e9468cba9..fc7e50787f 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -106,6 +106,16 @@ export const Config: z<Config> = z.object({
   servers: z.dict(LspLocalServerConfig).required(),
 })
 
+/** Propagate teardown failures only after every sibling has settled. */
+function throwTeardownFailures(results: readonly PromiseSettledResult<void>[], message: string): void {
+  const failures: unknown[] = []
+  for (const result of results) {
+    if (result.status === 'rejected') failures.push(result.reason)
+  }
+  if (failures.length === 1) throw failures[0]
+  if (failures.length > 1) throw new AggregateError(failures, message)
+}
+
 /**
  * Register the configured stdio LSP providers. Resolves every executable at load (after credential
  * scrubbing) before publishing any provider; each process launches lazily on its first matching
@@ -169,7 +179,8 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
     return async () => {
       // Remove every route before process teardown so no new query can enter a draining provider.
       for (const dispose of disposers.reverse()) dispose()
-      await Promise.all(providers.map(provider => provider.disposeAll()))
+      const results = await Promise.allSettled(providers.map(provider => provider.disposeAll()))
+      throwTeardownFailures(results, 'lsp-local provider teardown failed')
     }
   }, 'lsp-local.registerProviders')
 }
@@ -346,12 +357,13 @@ class LocalLspProvider implements LspProvider {
     const draining = [...this.queues.values()]
     const resolving = [...this.workspaceLookups]
     this.instances.clear()
-    await Promise.all([
+    const results = await Promise.allSettled([
       ...live.map(instance => instance.dispose()),
       ...draining,
       ...resolving,
     ])
     this.queues.clear()
     this.workspaceLookups.clear()
+    throwTeardownFailures(results, 'lsp-local instance teardown failed')
   }
 }
diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index 63aea8742c..7a30232e22 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -350,6 +350,78 @@ describe('lsp-local end to end over a fake server', () => {
     expect(signal.aborted).toBe(true)
   })
 
+  it('waits for every owned teardown before aggregating instance failures', async () => {
+    let provider: LspProvider | undefined
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' }, {}, (registered) => { provider = registered })
+    if (provider === undefined) throw new Error('expected lsp-local to register a provider')
+    const internals = provider as unknown as {
+      readonly instances: Map<string, { dispose(): Promise<void> }>
+      readonly queues: Map<string, Promise<void>>
+      readonly workspaceLookups: Set<Promise<void>>
+      disposeAll(): Promise<void>
+    }
+    const firstFailure = new Error('first instance cleanup failed')
+    const secondFailure = new Error('second instance cleanup failed')
+    const release = Promise.withResolvers<undefined>()
+    internals.instances.set('first', { dispose: async () => { throw firstFailure } })
+    internals.instances.set('second', { dispose: async () => { throw secondFailure } })
+    internals.queues.set('pending', release.promise)
+    internals.workspaceLookups.add(Promise.resolve())
+
+    let settled = false
+    const disposing = internals.disposeAll().finally(() => { settled = true })
+    await new Promise<void>(resolve => setImmediate(resolve))
+    expect(settled).toBe(false)
+    release.resolve(undefined)
+    await expect(disposing).rejects.toMatchObject({
+      errors: [firstFailure, secondFailure],
+      message: 'lsp-local instance teardown failed',
+    })
+    expect(internals.instances.size).toBe(0)
+    expect(internals.queues.size).toBe(0)
+    expect(internals.workspaceLookups.size).toBe(0)
+    await ctx.fiber.dispose()
+  })
+
+  it('waits for every provider before reporting plugin teardown failure', async () => {
+    const ctx = new Context()
+    const disposalErrors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
+    await ctx.plugin(Lsp)
+    await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+    const providers: LspProvider[] = []
+    const register = ctx.lsp.registerProvider.bind(ctx.lsp)
+    const registrationSpy = vi.spyOn(ctx.lsp, 'registerProvider').mockImplementation((provider) => {
+      providers.push(provider)
+      return register(provider)
+    })
+    const fiber = await ctx.plugin(LspLocal, {
+      servers: {
+        first: fakeServer(),
+        second: fakeServer({}, { extensionToLanguage: { '.js': 'javascript' } }),
+      },
+    })
+    registrationSpy.mockRestore()
+    expect(providers).toHaveLength(2)
+    const failure = new Error('provider cleanup failed')
+    const release = Promise.withResolvers<undefined>()
+    const first = providers[0] as LspProvider & { disposeAll(): Promise<void> }
+    const second = providers[1] as LspProvider & { disposeAll(): Promise<void> }
+    first.disposeAll = async () => { throw failure }
+    second.disposeAll = async () => { await release.promise }
+
+    let disposed = false
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await new Promise<void>(resolve => setImmediate(resolve))
+    expect(disposed).toBe(false)
+    expect(disposalErrors).toEqual([])
+    release.resolve(undefined)
+    await disposing
+    expect(disposalErrors).toEqual([failure])
+    await ctx.fiber.dispose()
+  })
+
   it('runs distinct workspaces in parallel instances', async () => {
     const ws2 = join(root, 'ws2')
     await mkdir(ws2)
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index c2a0f9b647..2689103443 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: c4af7bc8293689d64c58eebab2606d4f9b52fd2f
-README.zh.md: 21075ccbf53d173a54220b58b384f01cfe50ced1
+README.md: 92a3d7be68ada6f38ab3c4ca5bdd2622ebefc8ee
+README.zh.md: 016043f7842df8bb963cdc5eea015666c9ce6941
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index c4af7bc829..92a3d7be68 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -6,7 +6,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 ## Plugin (`pty-local`)
 
-The plugin injects `pty`, `sandbox`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
+The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly without requiring a sandbox provider; confined modes require a same-world `ctx.sandbox` and wrap the exact shell argv through it, failing before spawn when none is mounted. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 21075ccbf5..016043f784 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-这是基于 `ctx.subprocess.spawnTerminal` 的 `ctx.pty` 持久 shell 后端。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，保留有界的逐行输出并检测就绪状态；进程管理提供方负责 PTY 分配、环境清理、前台进程组、信号发送和完整终端会话清理。因此，同一个 PTY 后端可以与本地或远程执行世界提供方组合。
+这是一个基于 `ctx.subprocess.spawnTerminal`、为 `ctx.pty` 提供的持久 shell 后端。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，保留有界的逐行输出并检测就绪状态；进程管理提供方则负责 PTY 分配、环境清理、前台进程组、信号发送和完整终端会话清理。因此，同一个 PTY 后端可以与本地或远程执行世界提供方组合。
 
 ## 插件（`pty-local`）
 
-该插件注入 `pty`、`sandbox`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建结算并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
+该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最近一个自有标记之后的可打印尾部与受控 `PS1` 完全相等时，系统才会把标记视为就绪；即使 OSC 标记和提示符被拆到多个数据回调中也是如此。因此，如果回显的输入或输出跟在先前提示符之后，该提示符无法使当前 send 完成。系统会在写入边界丢弃提供方写入前收集的提示符与静默证据，包括写入前的前台检查尚未完成时收集的证据。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法持续压制推断空闲就绪，最多只能延续到绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方信号会转发给终端分配和就绪初始化；句柄一经发布，便负责自身生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送会先把排队输入标记为已取消，再请求终端句柄向当前前台进程组发送真正的 `SIGINT`；如果异步的写入前检查随后才结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待写入结算；写入被拒绝时不会发送信号。被取消的发送会保留其槽位，直至写入和前台信号发送都结算，因此后续发送既不会收到延迟字节，也不会成为该信号的目标。取消等待期间，绝对截止时间仍保持启用。信号发送失败属于终结性传输失败，并会使当前发送被拒绝。取消绝不会通过写入 `\x03` 模拟中断，因此原始模式程序仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待句柄执行由提供方负责的完整会话终止，之后才将当前发送以 `session_exit` 结算。
+取消发送时，系统会先把排队输入标记为已取消，再要求终端句柄向当前前台进程组发送真正的 `SIGINT`；异步写入前检查即使随后结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待其结算；写入被拒绝时不会发送信号。已取消的 send 会保留其位置，直到写入与前台信号发送都结算，因此后继 send 不会收到延迟字节或该信号。取消等待期间，绝对 deadline 仍保持启用。信号发送失败是终端传输失败，会拒绝活跃 send。取消绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待由句柄提供方负责的完整会话终止，然后才把活跃 send 结算为 `session_exit`。
 
 ## 模型体验
 
@@ -22,15 +22,15 @@
 
 #### Token 影响
 
-消费方返回有界的后端输出前没有影响。此包不会把保留的 PTY scrollback 放入模型历史。
+消费方返回有界的后端输出前没有影响。此包（package）不会把保留的 PTY scrollback 放入模型历史。
 
 #### KV Cache 影响
 
-不会直接失效；提示词、schema 与追加结果由消费方负责。
+不会直接使 KV Cache 失效；提示词、schema 与追加结果由消费方负责。
 
-## 已知限制与暂缓工作
+## 已知限制与暂缓事项
 
 - 输出按行规范化；不支持全屏备用缓冲区交互。
-- 精确 stdin 等待检测取决于挂载的进程管理提供方；无法证明该事实的提供方使用提示符标记和静默／超时就绪机制。
-- 清理保证遵循 `SubprocessTerminalHandle`；提供方特有缺口属于该实现的契约，而非此 PTY 消费方。
-- 会话无法跨 harness 进程退出保留。
+- 精确 stdin 等待检测取决于已挂载的进程管理提供方；无法证明该状态的提供方使用提示符标记和静默／超时就绪机制。
+- 清理保证以 `SubprocessTerminalHandle` 的保证为准；提供方特定的缺口属于该实现的契约，而非这个 PTY 消费方。
+- harness 进程退出后，会话无法继续存在。
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index a8d99cb243..1fa3357002 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -22,7 +22,7 @@ export type { Config as PtyLocalConfig } from './config.ts'
 /** Cordis plugin name. */
 export const name = 'pty-local'
 /** Required services: PTY registry, shared confinement policy, and process substrate. */
-export const inject = ['pty', 'sandbox', 'sandboxPolicy', 'subprocess']
+export const inject = ['pty', 'sandboxPolicy', 'subprocess']
 
 interface SandboxModeFenceState {
   pty: Context['pty']
@@ -72,7 +72,11 @@ function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSp
   const argv = [config.shellPath, ...config.shellArgs]
   const mode: SandboxMode = effectiveSandboxMode(spec.owner.session.events) ?? ctx.sandboxPolicy.defaultMode
   if (mode === 'danger-full-access') return argv
-  return ctx.sandbox.confine(argv, {
+  const sandbox = ctx.get('sandbox')
+  if (sandbox === undefined) {
+    throw new Error(`pty-local: sandbox mode "${mode}" requires a ctx.sandbox provider in the execution world`)
+  }
+  return sandbox.confine(argv, {
     mode: mode,
     workspaceRoot: ctx.sandboxPolicy.workspaceRoot,
   }).argv
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 48c8272106..9206dd89ef 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -120,7 +120,6 @@ describe('LocalPtyBackend startup rollback', () => {
 
   it('closes failed startup and aggregates cleanup failure', async () => {
     const ctx = new Context()
-    await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
     const spawnTerminal = async (): Promise<SubprocessTerminalHandle> => terminalHandle()
 
@@ -186,6 +185,20 @@ describe('LocalPtyBackend startup rollback', () => {
     expect(initialized).toHaveBeenCalledWith(undefined)
   })
 
+  it('rejects a confined spawn without a sandbox provider', async () => {
+    const confinedCtx = new Context()
+    await confinedCtx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: '/workspace' })
+    const confined = new LocalPtyBackend(
+      confinedCtx,
+      config(),
+      async () => { throw new Error('terminal spawn must not run') },
+      () => stubLocalSession(),
+    )
+    await expect(confined.spawn(spec(agent(confinedCtx)))).rejects.toThrow(
+      'sandbox mode "workspace-write" requires a ctx.sandbox provider in the execution world',
+    )
+  })
+
   it('forwards terminal allocation cancellation directly', async () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
@@ -266,7 +279,7 @@ describe('pty-local plugin shape', () => {
     const loader = Object.create(Loader.prototype) as Loader
     const unwrapped = loader.unwrapExports(ptyLocal) as Record<string, unknown>
     expect(unwrapped.name).toBe('pty-local')
-    expect(unwrapped.inject).toEqual(['pty', 'sandbox', 'sandboxPolicy', 'subprocess'])
+    expect(unwrapped.inject).toEqual(['pty', 'sandboxPolicy', 'subprocess'])
     expect(unwrapped.Config).toBeDefined()
   })
 
@@ -274,7 +287,6 @@ describe('pty-local plugin shape', () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(PtyService)
-    await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
     await ctx.plugin(StubSubprocessService)
     const fiber = await ctx.plugin(ptyLocal, config())

From ff86795b15576048529c7ccff4d00c38adbdb015 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 23:11:49 +0800
Subject: [PATCH 332/516] fix(pty): close provider cancellation races

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  4 +-
 ...8-portable-execution-world-consumers.zh.md |  4 +-
 .../core-data-structures/subprocess.i18n.yaml |  4 +-
 docs/core-data-structures/subprocess.md       |  2 +-
 docs/core-data-structures/subprocess.zh.md    |  2 +-
 packages/pty/pty-local/src/index.ts           | 18 ++++++-
 packages/pty/pty-local/src/session.ts         |  5 +-
 packages/pty/pty-local/tests/index.spec.ts    | 26 +++++++++
 packages/pty/pty-local/tests/session.spec.ts  | 53 ++++++++++++++++++-
 packages/subprocess/README.i18n.yaml          |  4 +-
 packages/subprocess/README.md                 |  2 +-
 packages/subprocess/README.zh.md              |  6 +--
 .../subprocess/subprocess/README.i18n.yaml    |  4 +-
 packages/subprocess/subprocess/README.md      |  2 +-
 packages/subprocess/subprocess/README.zh.md   | 24 ++++-----
 packages/subprocess/subprocess/src/types.ts   |  3 +-
 17 files changed, 131 insertions(+), 36 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index a7eaaa2e3a..683a095229 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 260f38981ea0cd034f506594057483c6ccfa9617
-2026-07-28-portable-execution-world-consumers.zh.md: 0bf7b4dd1a87378b76f6a71343a8cb78766b7b3a
+2026-07-28-portable-execution-world-consumers.md: 03b274688e15661845c326afdd105b342dd6a513
+2026-07-28-portable-execution-world-consumers.zh.md: 1e3d8ae8e46d26f4bea47293104c52dbf33098d4
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 260f38981e..03b274688e 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -16,13 +16,13 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all
 
 The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, and containment. Existing whole and streaming text operations remain filesystem-owned; protocol consumers enforce their own retention limits while consuming the stream.
 
-The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches whole-session quiescence. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
 
 Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
-- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Close rejects new public signals and delegates complete-session quiescence to the handle's awaited termination operation.
+- `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; an in-flight readiness poll cannot release that reservation, and a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Startup cancellation begins terminal rollback without waiting for a stalled readiness or signalling call. Close rejects new public signals and delegates provider-observable session quiescence to the handle's awaited termination operation.
 - `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. The fixed runner is adapter-owned infrastructure below `ctx.subprocess.runtimeRoot`, so its write carries an explicit `danger-full-access` policy instead of inheriting the model-facing filesystem mode. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 0bf7b4dd1a..1e3d8ae8e4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -16,13 +16,13 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使整个会话完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。
 - `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index 7cba3857bb..f3b308b0be 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: 89c75aea3393a000612e3b8f87d263c7b4fa7c60
-subprocess.zh.md: 83fb44f4750ba31db1f4336c0c293eb9e236be22
+subprocess.md: 95e9454a75112cf98e1ed583f970c50fe90aac37
+subprocess.zh.md: 58127d662fa599d19f632449d42b8aa3259886d6
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index d6e0105c59..935a7d60ac 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -240,7 +240,7 @@ interface SubprocessOutcome {
 
 ## Terminal-process primitive
 
-`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches whole-session quiescence. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
+`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches quiescence for every session member the provider can still observe; providers document substrate-specific observability limits. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
 
 The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam).
 
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 83fb44f475..58127d662f 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -240,7 +240,7 @@ interface SubprocessOutcome {
 
 ## 终端进程原语
 
-`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使整个会话完全停稳。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
+`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，提供方则会记录执行基底特有的可观察性限制。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
 
 终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam)中。
 
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index 1fa3357002..f91db5d386 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -82,6 +82,22 @@ function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSp
   }).argv
 }
 
+async function initializeSession(session: LocalPtySession, signal?: AbortSignal): Promise<void> {
+  if (signal === undefined) {
+    await session.initialize(signal)
+    return
+  }
+  const aborted = Promise.withResolvers<never>()
+  const onAbort = (): void => { aborted.reject(signal.reason) }
+  signal.addEventListener('abort', onAbort, { once: true })
+  try {
+    signal.throwIfAborted()
+    await Promise.race([session.initialize(signal), aborted.promise])
+  } finally {
+    signal.removeEventListener('abort', onAbort)
+  }
+}
+
 /** Local shell backend registered under the configured type. */
 export class LocalPtyBackend implements PtyBackend {
   readonly type: string
@@ -116,7 +132,7 @@ export class LocalPtyBackend implements PtyBackend {
     })
     const session = this.createSession(terminal, this.config)
     try {
-      await session.initialize(spec.signal)
+      await initializeSession(session, spec.signal)
       return session
     } catch (error) {
       try {
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 5517cd902d..ebd7e076cf 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -6,6 +6,7 @@ import type {
   SubprocessTerminalForeground,
   SubprocessTerminalHandle,
 } from '@deepseek-ai/dsh-subprocess'
+import { PtyError } from '@deepseek-ai/dsh-pty'
 import type {
   PtyBackendSession,
   PtyReadRequest,
@@ -219,7 +220,7 @@ export class LocalPtySession implements PtyBackendSession {
   startSend(request: PtySendRequest): PtySendOperation {
     if (this.closing) throw new Error('PTY session is closing')
     if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
-    if (this.active !== undefined) throw new Error('PTY session already has an active send')
+    if (this.active !== undefined) throw new PtyError('PTY session already has an active send or draining provider operation', 'SEND_ACTIVE')
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
     const operation = new LocalSendOperation(
@@ -247,7 +248,7 @@ export class LocalPtySession implements PtyBackendSession {
   private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
     try {
       const foreground = await this.terminal.inspectForeground()
-      if (this.active !== operation || this.closing) return
+      if (this.active !== operation || this.closing || this.interrupting === operation) return
       operation.setInitialForeground(foreground)
       const input = `${request.text}${request.submit ? '\r' : ''}`
       if (input.length > 0 && !operation.cancelRequested) {
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 9206dd89ef..f59cd3ab5a 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -143,6 +143,32 @@ describe('LocalPtyBackend startup rollback', () => {
     } satisfies Partial<PtyBackendCleanupError>))
   })
 
+  it('starts startup rollback when cancellation wins a stalled initialization', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    const initialization = Promise.withResolvers<undefined>()
+    const initializationStarted = Promise.withResolvers<undefined>()
+    const close = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
+    const session = {
+      initialize: () => {
+        initializationStarted.resolve(undefined)
+        return initialization.promise
+      },
+      close,
+    } as unknown as LocalPtySession
+    const backend = new LocalPtyBackend(ctx, config(), async () => terminalHandle(), () => session)
+    const controller = new AbortController()
+    const reason = new Error('cancel stalled startup')
+
+    const spawning = backend.spawn(spec(agent(ctx), controller.signal))
+    await initializationStarted.promise
+    controller.abort(reason)
+
+    await expect(spawning).rejects.toBe(reason)
+    expect(close).toHaveBeenCalledWith('PTY startup failed')
+    initialization.resolve(undefined)
+  })
+
   it('wraps confined argv, scrubs the environment, and returns initialized sessions', async () => {
     const ctx = new Context()
     await ctx.plugin(RecordingSandbox)
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index fbe0aa807b..8d11f8e6f4 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -8,6 +8,7 @@ import type {
   SubprocessTerminalHandle,
   SubprocessTerminalSignal,
 } from '@deepseek-ai/dsh-subprocess'
+import { PtyError } from '@deepseek-ai/dsh-pty'
 import type {
   ProcessIdentity,
   ProcessInspector,
@@ -374,6 +375,54 @@ describe('LocalPtySession readiness and output', () => {
     expect(inspector.groups).not.toContainEqual([789, 'SIGINT'])
   })
 
+  it('does not let an in-flight readiness inspection release a canceled send before signalling settles', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const readiness = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    let inspections = 0
+    terminal.inspectForeground = async () => {
+      inspections += 1
+      if (inspections === 1) return { processGroupId: 456, inputWaiting: false }
+      if (inspections === 2) return await readiness.promise
+      return { processGroupId: 456, inputWaiting: true }
+    }
+    const signalling = Promise.withResolvers<undefined>()
+    const signalled = Promise.withResolvers<number>()
+    terminal.signalForeground = async (signal) => {
+      await signalling.promise
+      const foreground = await terminal.inspectForeground()
+      if (foreground === undefined) throw new Error('cannot resolve foreground')
+      inspector.signalGroup(foreground.processGroupId, signal)
+      signalled.resolve(foreground.processGroupId)
+      return foreground.processGroupId
+    }
+
+    const operation = session.startSend({ text: 'first', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await vi.advanceTimersByTimeAsync(10)
+    expect(inspections).toBe(2)
+    expect(operation.cancel()).toBe(true)
+    let settled = false
+    void operation.done.then(() => { settled = true })
+
+    readiness.resolve({ processGroupId: 456, inputWaiting: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(settled).toBe(false)
+    expect(() => session.startSend({ text: 'successor', submit: true })).toThrow(PtyError)
+
+    signalling.resolve(undefined)
+    expect(await signalled.promise).toBe(456)
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    await session.close('test complete')
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
   it('signals only after an in-flight provider write lands', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -438,7 +487,9 @@ describe('LocalPtySession readiness and output', () => {
     await vi.advanceTimersByTimeAsync(100)
 
     expect((await operation.done).waitReason).toBe('timeout')
-    expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow('active send')
+    expect(() => session.startSend({ text: 'must wait', submit: true })).toThrow(expect.objectContaining({
+      code: 'SEND_ACTIVE',
+    }))
 
     writeGate.resolve(undefined)
     await vi.advanceTimersByTimeAsync(0)
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 256d4ad2d9..f6de20e259 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: c4bb1da1a172b05afa63834db4e5b1fa974baabb
-README.zh.md: f68bc1c720eeb5282bb9c94c951524a021e38b2f
+README.md: b4aaf78454a51af4d3f7ea9f1aef450fde8d729d
+README.zh.md: c5013ce19bacb582b6c8c93e0ea0a73ec776ee57
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index c4bb1da1a1..b4aaf78454 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The shared process substrate for one execution world: canonical cwd/runtime storage, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and complete session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+The shared process substrate for one execution world: canonical cwd/runtime storage, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 | Package | ctx key | Role |
 |---|---|---|
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index f68bc1c720..c5013ce19b 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -1,12 +1,12 @@
-# subprocess/：进程管理能力家族
+# subprocess/：子进程能力家族
 
 [English](README.md) | 中文
 
-同一执行世界中的共享进程基底：规范化 cwd／运行时存储、可执行文件查找、采用原始或收集式 stdio 的完全显式受管子进程树，以及一项负责 PTY 分配、前台进程组和完整会话清理的深层终端进程原语。命令默认值补全、shell 语义、deadline、协议分帧、就绪检测与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[基于进程管理的 Code Runtime](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[进程管理器 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+这里集中提供一个执行世界的共享进程基底：规范化 cwd／运行时存储、可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[子进程代码运行时](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
 | [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：执行世界坐标与可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
 | [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送、运行时存储，以及先终止再等待退出的资源释放 |
 
-服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
+即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index f8678464a9..92887cc247 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: 2fca5cdd08f3cbd36d8ef492226c91681b5568d0
-README.zh.md: 5830d0fc394160bc557e24646cc76d4bcfead13c
+README.md: 12a88a86c3cd7bcde2858bdbd874c99533100e09
+README.zh.md: f4c265a0f55c4e35e4557516593dd0da236164c5
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index 2fca5cdd08..12a88a86c3 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -11,7 +11,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 - The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
-- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, UTF-8 text I/O, foreground-process-group inspection/signalling, and one awaited `terminate()` operation that reaches whole-session quiescence and settles in-flight handle calls. The spec signal cancels allocation only; the published handle owns its lifetime. The output stream ends after queued output when the top-level process exits, and a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or clean the complete terminal session; readiness, scrollback, and owner policy remain in the PTY consumer.
+- `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, UTF-8 text I/O, foreground-process-group inspection/signalling, and one awaited `terminate()` operation that reaches quiescence for every session member the provider can still observe and settles in-flight handle calls; providers document substrate-specific observability limits. The spec signal cancels allocation only; the published handle owns its lifetime. The output stream ends after queued output when the top-level process exits, and a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members; readiness, scrollback, and owner policy remain in the PTY consumer.
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 5830d0fc39..f4c265a0f5 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -2,30 +2,30 @@
 
 [English](README.md) | 中文
 
-进程管理器 seam（`ctx.subprocess`）是同一执行世界中的进程侧。抽象的 `SubprocessService` 公开其规范化 `cwd`、私有 `runtimeRoot`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
+子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开其规范化 `cwd`、私有 `runtimeRoot`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
 
 ## 契约
 
-- `spawn(spec)` 立即返回一个实时句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
-- `cwd` 与 `runtimeRoot` 是提供方执行世界中的绝对路径。消费方在 `runtimeRoot` 下物化私有辅助程序，绝不使用仅宿主可见的临时目录。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
-- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的进程管理器默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
-- stdio 按流采用 Node 形状：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
+- `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
+- `cwd` 和 `runtimeRoot` 是提供方执行世界中的绝对路径。消费方在 `runtimeRoot` 之下物化私有辅助程序，绝不使用仅宿主可见的临时目录。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
+- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
+- stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使整个会话完全停稳，并让所有在途句柄调用结算。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出后，输出流会在排完队列中的输出后结束；存活期间的传输故障会拒绝 `done`。这些操作仍属于一项基底原语，因为普通管道无法分配控制终端，也无法清理完整的终端会话；就绪检测、scrollback 与所有者策略仍归 PTY 消费方所有。
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的凭据清除定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地普通 spawn 与终端 spawn 都应用这一定义；自行拥有 spawn 的 SDK 管理传输层可以直接导入它。
+- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，并结算在途句柄调用；提供方会记录执行基底特有的可观察性限制。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出时，输出流在已排队输出之后结束；存活传输失败会拒绝 `done`。这些操作保留为一项执行基底原语，因为普通管道无法分配控制终端或清理终端会话成员；就绪状态、scrollback 和所有者策略仍归 PTY 消费方所有。
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地的普通 spawn 与终端 spawn 都应用该定义；拥有自身 spawn 的 SDK 管理传输可直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
-参见[进程管理器数据结构目录](../../../docs/core-data-structures/subprocess.md)与 [seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+参见[子进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 ## 模型体验
 
-通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出与生命周期面向模型的全部渲染归消费方所有。
+通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出和生命周期的全部面向模型渲染均由消费方负责。
 
 #### KV Cache 影响
 
-不会直接失效；请求前缀变更由具名消费方负责。
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
 
 ## 已知限制与暂缓事项
 
-- **由 SDK 管理的 spawn 仍在服务之外**：自行拥有内部 spawn 的 SDK 传输层无法经该服务路由这次调用；它仍可导入 `scrubbedParentEnv`，使环境策略保持单一来源。
-- **拆卸阶梯归消费方所有**：该 seam 只提供信号动词与进程树存活等待，不提供现成的停稳序列；每个进程外消费方自行编码其子进程的配合形状（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。
+- **由 SDK 管理的 spawn 仍在服务之外**：拥有内部 spawn 的 SDK 传输无法把该调用路由到本服务；它仍可导入 `scrubbedParentEnv`，使环境策略保持单一来源。
+- **拆卸阶梯归消费方所有**：该 seam 只提供信号动词与进程树存活等待，不提供现成的停稳序列；每个进程外消费方自行编码其子进程的配合方式（ACP 后端以 stdin EOF 打头的阶梯是仓库内模板）。
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index 6b606fd870..9801bf2f49 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -252,8 +252,9 @@ export interface SubprocessTerminalHandle {
    */
   signalForeground(signal: SubprocessTerminalSignal): Promise<number>
   /**
-   * Idempotently terminate the complete terminal session and await whole-session quiescence.
+   * Idempotently terminate every terminal-session member the provider can still observe and await quiescence.
    * After settlement, no write, inspection, or signal call remains in flight.
+   * Providers document substrate-specific observability limits.
    */
   terminate(): Promise<void>
 }

From dde55d5afecb75e8cd3f07f04e8f79e8199b53ba Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 02:04:11 +0800
Subject: [PATCH 333/516] docs(agent-notes): consolidate subprocess decisions

---
 ...26-subprocess-consumer-migration.i18n.yaml |  6 ---
 ...026-07-26-subprocess-consumer-migration.md | 38 -------------------
 ...-07-26-subprocess-consumer-migration.zh.md | 38 -------------------
 .../2026-07-26-subprocess-seam.i18n.yaml      |  4 +-
 .../2026-07-26-subprocess-seam.md             | 16 +++++---
 .../2026-07-26-subprocess-seam.zh.md          | 16 +++++---
 6 files changed, 24 insertions(+), 94 deletions(-)
 delete mode 100644 .agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml
 delete mode 100644 .agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
 delete mode 100644 .agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml
deleted file mode 100644
index 469c3f9a24..0000000000
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/architecture/2026-07-26-subprocess-consumer-migration.md
-2026-07-26-subprocess-consumer-migration.md: abc7c8504595641b2b821df5ddbd4645c3a15336
-2026-07-26-subprocess-consumer-migration.zh.md: 500dcfe36f63315156b1a3cc48670eaf1c204b20
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
deleted file mode 100644
index abc7c85045..0000000000
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Agent Note: The subprocess seam goes Node-shaped and every eligible spawner rides it
-
-Status: implemented
-
-English | [中文](2026-07-26-subprocess-consumer-migration.zh.md)
-
-## Problem
-
-The [subprocess seam](2026-07-26-subprocess-seam.md) shipped shaped for exactly one consumer family: batch-collected stdout/stderr, batch stdin, a single escalating `kill()`. That was deliberate scope control, and its own note records "migrate the other spawn sites" as rejected-for-now. Review on the introducing PR reversed that deferral: the stacked follow-up should reshape the interface toward Node's API and move the remaining process-running places onto the service. The remaining spawners each carried a private copy of some slice of the same mechanics — lsp-local had its own detached-tree signalling (POSIX group + Windows taskkill + liveness polling), subagent-subprocess had the dispose ladder and its own scrub, mcp-client and pty-local and the SDK helper each had a third/fourth/fifth copy of the credential scrub — and none of it was swappable or centrally testable.
-
-## Decision
-
-The seam's vocabulary is now Node-shaped, and every spawner that can ride the service does:
-
-- **Per-stream stdio dispositions** on `SubprocessSpawnSpec`: `'pipe'` (the raw `Readable`/`Writable`, for consumer-owned protocol framing), `'inherit'` (diagnostics to the parent's stream), and collect mode `{ maxBytes, spill? }` — the original bounded tail-keep shape, with the spill file now optional so a diagnostic tail (a language server's stderr) buffers without touching disk. stdin is `'ignore'`, `'pipe'`, or `{ data }` (write-and-close batch).
-- **`SubprocessOutcome` carries exit facts only** (Node's close-event vocabulary); collected output stays readable through `handle.collected` after settlement (spill fds seal at the settle boundary), so batch and streaming callers share one access path and nothing is copied into the outcome.
-- **Tree-scoped termination behind one verb**: `terminate()` owns the SIGTERM→grace→SIGKILL escalation (serves the spec's abort signal too, and is a no-op once the tree is gone) — the handle exposes no single-signal `kill(signal?)`, so a consumer cannot skip the grace window; `waitForExit()` polls tree liveness (POSIX group probe; direct-child boundary on Windows); Windows tree termination (`taskkill /T`, injectable) moved in from lsp-local, so tree semantics are platform-correct for every consumer. (The stdin-EOF-first dispose ladder initially absorbed from `subagent-subprocess` later moved back out to its one consumer — see the [ladder-ownership Agent Note](2026-07-27-dispose-ladder-to-consumer.md).)
-- **One scrub definition**: `scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` live on the seam. Ordinary and terminal local spawns apply it inside `dsh-subprocess-local`; mcp-client still imports it because the MCP SDK owns that transport spawn, and the SDK helper's `scrubEnvironment()` defaults through it as well.
-
-Migrations landed with the reshape: **bash-local/bash-sandbox** (collect modes + batch stdin; the bash `kill()` maps to `terminate()` so `task_kill` keeps escalation semantics), **lsp-local** (piped protocol streams + a no-spill collected stderr tail; `LspConnection` takes the seam's spawn function; its private tree-op helpers deleted), **subagent-acp** (piped ndjson streams + inherited stderr; spawn failure surfaces through `done` rejection into the same startup race; disposal is the backend-owned `disposeAcpChild` ladder over the seam's verbs, with the plugin's configured graces), and **pty-local** through the later [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) (`node-pty` allocation and process inspection sit behind `spawnTerminal()`, while readiness and terminal policy remain in the consumer). **`dsh-subagent-subprocess` is deleted** — the dispose ladder and scrub are the seam's; the unused isolated-config-dir helper died with it (no consumer existed).
-
-Compositions mounting lsp-local or subagent-acp now load `dsh-subprocess-local` (the plugins inject `'subprocess'`); the acp/lsp test fixtures gained the row.
-
-## Alternatives considered
-
-**Keep the batch-only seam and let stream consumers stay bespoke.** The introducing note's position, rejected by review: it leaves three private copies of tree signalling and five of the scrub, and any future runner (containerized executor, remote process host) would have to pick which private copy to fork. The Node-shaped dispositions cover all three observed stream shapes without widening the outcome type or buffering piped streams.
-
-**A single `stdio: 'pipe' | 'inherit' | 'collect'` mode for all three streams at once.** Rejected: real consumers mix modes per stream (lsp: pipe/pipe/collect; acp: pipe/pipe/inherit; bash: data/collect/collect). Per-stream dispositions are exactly Node's shape and avoid a second spawn call for the mixed cases.
-
-**Keep pty-local and mcp-client spawns outside the service.** The MCP SDK still owns its transport spawn. PTY allocation is different: the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) moves `node-pty` behind one deep terminal primitive, resolving the ownership objection without pretending an ordinary piped spawn can provide terminal semantics.
-
-**Migrate the test-support launchers (acp-snapshot, loader-smoke) and the SDK package-manager runner.** Rejected: the support packages are deliberately dependency-light test infrastructure that must not depend on product seams, and the SDK wizard's `stdio: 'inherit'`-with-redirect semantics plus its out-of-composition lifecycle (no cordis context at all) make the service a poor fit; it shares the scrub instead.
-
-## Consequences
-
-Bought: one implementation of tree signalling, escalation, bounded collection, terminal process mechanics, and the scrub, tested once in `dsh-subprocess-local`'s suites (including injected-platform Windows coverage that lsp-local's private copy never had); lsp-local, pty-local, and subagent-acp shed provider-specific process plumbing and their children die with composition teardown like bash's; a whole package (`dsh-subagent-subprocess`) is gone. The seam README's "one consumer family" limitation is retired.
-
-Cost: the seam is wider — execution-world coordinates, executable lookup, three stdio modes, process-tree lifecycle, and one terminal primitive — so a future backend implements more surface; the compositions for lsp-local, pty-local, and subagent-acp each carry the subprocess row; and `SubprocessOutcome` no longer carries output, a breaking shape change inside the still-unreleased stack. MCP/SDK/test-support spawns remain outside the service by ownership, with the scrub as the shared floor.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md
deleted file mode 100644
index 500dcfe36f..0000000000
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-consumer-migration.zh.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Agent Note: 进程 seam 转向 Node 形状，所有具备条件的 spawn 调用点一并迁入
-
-Status: implemented
-
-[English](2026-07-26-subprocess-consumer-migration.md) | 中文
-
-## 问题
-
-[进程 seam](2026-07-26-subprocess-seam.md) 交付时恰好只为一个消费方家族塑形：批量收集的 stdout/stderr、批量 stdin、单一的升级式 `kill()`。那是有意的范围控制，其自身的 Agent Note 也把「迁移其余 spawn 调用点」记为暂缓否决项。引入该 seam 的 PR（Pull Request）上的评审推翻了这一暂缓决定：堆叠其上的后续变更应当把接口向 Node 的 API 方向重塑，并把其余运行进程之处迁到该服务上。其余各 spawn 调用点此前各自持有同一套机制中某个切片的私有副本——lsp-local 自带 detached 进程树信号发送（POSIX 进程组 + Windows taskkill + 存活轮询），subagent-subprocess 自带 dispose（资源释放）阶梯和自己的凭据清除，mcp-client、pty-local 与 SDK helper 则各自持有凭据清除的第三、第四、第五份副本——而这一切既不可替换，也无法集中测试。
-
-## 决策
-
-这道 seam 的词汇如今已是 Node 形状，凡能接入该服务的 spawn 调用点均已迁入：
-
-- **按流划分的 stdio 处置方式（disposition）**，位于 `SubprocessSpawnSpec` 上：`'pipe'`（原始的 `Readable`/`Writable`，供消费方自有的协议分帧使用）、`'inherit'`（诊断输出直通父进程的流），以及收集模式（collect）`{ maxBytes, spill? }`——即最初的有界尾部保留形状，只是 spill 文件改为可选，使诊断尾部（例如语言服务器的 stderr）无需落盘即可缓冲。stdin 则为 `'ignore'`、`'pipe'` 或 `{ data }`（写完即关闭的批量形式）。
-- **`SubprocessOutcome` 只承载退出事实**（Node close 事件的词汇）；收集到的输出在结算后仍可经 `handle.collected` 读取（spill 文件描述符在结算边界封存），因此批量与流式调用方共用一条访问路径，也没有任何内容被复制进这份结果。
-- **以进程树为范围的终止，集中在一个动词后面**：`terminate()` 拥有 SIGTERM→宽限期→SIGKILL 升级（也承接 spec 的 abort 信号，进程树消亡后为空操作）——句柄不暴露单信号的 `kill(signal?)`，因此消费方无法跳过宽限窗口；`waitForExit()` 轮询进程树存活状态（POSIX 进程组探测；Windows 上以直接子进程为界）。Windows 进程树终止（`taskkill /T`，可注入）自 lsp-local 迁入，因此每个消费方拿到的进程树语义在各平台上都正确。（最初从 `subagent-subprocess` 吸收的以 stdin EOF 打头的 dispose 阶梯，后来又移回其唯一消费方——见[阶梯归属 Agent Note](2026-07-27-dispose-ladder-to-consumer.md)。）
-- **凭据清除只有一份定义**：`scrubbedParentEnv()`/`SENSITIVE_ENV_PATTERN` 定义在 seam 上。普通本地 spawn 与终端本地 spawn 都在 `dsh-subprocess-local` 内部应用该定义；mcp-client 仍需导入它，因为 MCP SDK 拥有该传输层 spawn，SDK helper 的 `scrubEnvironment()` 默认同样委托给它。
-
-各项迁移随这次重塑一并落地：**bash-local/bash-sandbox**（收集模式 + 批量 stdin；bash 的 `kill()` 映射到 `terminate()`，因此 `task_kill` 保有升级语义），**lsp-local**（管道化的协议流 + 无 spill 的 stderr 收集尾部；`LspConnection` 改为接收 seam 的 spawn 函数；其私有的进程树操作辅助函数已删除），**subagent-acp**（管道化的 ndjson 流 + inherit 的 stderr；spawn 失败经 `done` 的 reject 汇入同一个启动竞态；dispose 是后端自有的 `disposeAcpChild` 阶梯，经由 seam 的动词运行，携带插件所配置的宽限期），以及后来通过[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)迁移的 **pty-local**（`node-pty` 分配与进程检查位于 `spawnTerminal()` 之后，就绪状态和终端策略仍归消费方所有）。**`dsh-subagent-subprocess` 已删除**——dispose 阶梯与凭据清除归 seam 所有；无人使用的隔离配置目录辅助函数随之消亡（其消费方本就不存在）。
-
-挂载 lsp-local 或 subagent-acp 的组合如今都加载 `dsh-subprocess-local`（这两个插件注入 `'subprocess'`）；acp/lsp 测试 fixture（测试前置数据）补上了这一行组合配置。
-
-## 曾考虑的替代方案
-
-**保持只支持批量的 seam，让流式消费方继续各自为政。**这正是引入该 seam 的 Agent Note 当初的立场，评审将其否决：这样会留下三份进程树信号发送的私有副本和五份凭据清除的私有副本，而未来任何运行器（容器化执行器、远程进程宿主）都得挑选去 fork 哪一份私有副本。Node 形状的处置方式覆盖已观察到的全部三种流形状，既不拓宽结果类型，也不缓冲管道化的流。
-
-**用单个 `stdio: 'pipe' | 'inherit' | 'collect'` 模式一次性统辖全部三条流。**否决：真实消费方按流混用模式（lsp：pipe/pipe/collect；acp：pipe/pipe/inherit；bash：data/collect/collect）。按流划分的处置方式恰好就是 Node 的形状，也免去了混用场景的第二个 spawn 调用。
-
-**让 pty-local 与 mcp-client 的 spawn 留在服务之外。**MCP SDK 仍拥有其传输层 spawn。PTY 分配则不同：[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)把 `node-pty` 放到一个深层终端原语之后，既解决所有权异议，也不假装普通管道化 spawn 能够提供终端语义。
-
-**迁移 test-support 启动器（acp-snapshot、loader-smoke）与 SDK package-manager 运行器。**否决：support 各包（package）是刻意保持轻依赖的测试基础设施，不得依赖产品 seam；而 SDK 向导那套附带重定向的 `stdio: 'inherit'` 语义，加上其完全脱离组合的生命周期（根本没有 cordis 上下文），使该服务并不合用；它改为共享凭据清除。
-
-## 后果
-
-换来的是：进程树信号发送、升级、有界收集、终端进程机制与凭据清除各自只剩一份实现，且只在 `dsh-subprocess-local` 的测试套件中测试一次（其中包括 lsp-local 的私有副本从未有过的、以注入平台方式实现的 Windows 覆盖）；lsp-local、pty-local 与 subagent-acp 卸下了提供方专用的进程管道，其子进程如今像 bash 的一样随组合拆除而终止；一个完整的包（`dsh-subagent-subprocess`）就此消失。seam README 中「只有一个消费方家族」的限制说明也随之退役。
-
-代价是：这道 seam 变宽了，涵盖执行环境坐标、可执行文件查找、三种 stdio 模式、进程树生命周期和一个终端原语，未来的后端因此要实现更宽的表面；lsp-local、pty-local 与 subagent-acp 的各组合如今都多出 subprocess 这一行组合配置；`SubprocessOutcome` 也不再承载输出，这是仍未发布的堆叠变更内部的一次破坏性形状变更。MCP／SDK／test-support 的 spawn 因所有权归属留在该服务之外，以凭据清除作为共享底线。
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index 94711572d6..0b62184128 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: d5dee7361e48f18f3147444b2db74da3dd1c1161
-2026-07-26-subprocess-seam.zh.md: 884c572dc65c0fbf240f7e4e3b0387038e21f5ad
+2026-07-26-subprocess-seam.md: 359977ac6a50394405163bc060f3a39eb68891fb
+2026-07-26-subprocess-seam.zh.md: 551fcc8f4df82d0c893d8e6f5423f172dfd5d9c5
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index d5dee7361e..359977ac6a 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -12,8 +12,8 @@ English | [中文](2026-07-26-subprocess-seam.zh.md)
 
 A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it:
 
-- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd and runtime storage, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Its vocabulary includes per-stream stdio dispositions, process and terminal handles, exit facts with deliberately no timeout/cancel classification, and the shared scrub plus `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` types. `argv` is never shell-interpreted.
-- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, private runtime storage, foreground/session inspection, credential scrub with explicit env merged after it, tree cleanup, and disposal that terminates and joins every managed process. It has no config; every limit arrives on the spec. Bash and PTY presentation environment overrides stay in their consumers.
+- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd and runtime storage, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
+- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, private runtime storage, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the seam's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The implementation has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their consumers.
 - **`dsh-bash-local` (consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
 - **`dsh-bash` (seam)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
 
@@ -21,11 +21,17 @@ Every composition that loads a bash executor now also loads `@deepseek-ai/dsh-su
 
 Background-process lifetime moved from the executor to the subprocess service: the executor no longer retains a live-process set, so an executor reload leaves background work running and readable, and composition teardown (the service's disposal) remains the kill-and-join boundary. One behavioral seam shifted with it: a background spawn failure can no longer be buffered as fake stderr inside the plumbing (the service rejects `done` and buffers nothing for a process that never ran), so the executor injects the `spawn failed: …` note into exactly one `readOutput()` delta.
 
+Observed stream and lifecycle needs then moved the eligible process consumers onto the seam: LSP uses piped protocol streams plus a collected stderr tail; the ACP backend uses piped ndjson, inherited stderr, and a consumer-owned stdin-EOF disposal ladder; PTY uses `spawnTerminal()` while keeping readiness and terminal policy; Code Runtime uses ordinary raw pipes. `dsh-subagent-subprocess` and the private LSP tree helpers were deleted. MCP transport spawning, the SDK package-manager runner, synchronous TUI Git probing, and dependency-light test-support launchers remain outside by ownership or execution shape; their production callers share the scrub where applicable.
+
 ## Alternatives considered
 
 **Leave the process plumbing inside `dsh-bash-local` (status quo).** Rejected for the same reason the [task registry split](2026-07-26-task-registry-seam.md) landed: the boundary is stable and already documented in-code (`run.ts`'s module doc said "this layer reacts to an abort signal; the executor owns deadlines and classifies causes"), and keeping it private makes every future non-shell runner either fork the mechanics or depend on a bash-named package for non-bash work. The user-visible driver for this stack was exactly this split.
 
-**Migrate the repo's other spawn sites in the introducing change.** Rejected as scope creep with real design risk at that scale. The later [consumer-migration](2026-07-26-subprocess-consumer-migration.md) and [portable execution-world](2026-07-28-portable-execution-world-consumers.md) decisions reshape the interface around the observed LSP, subagent, PTY, and Code Runtime consumers; SDK and test-support launchers remain outside by ownership.
+**Keep the original batch-only interface and leave stream consumers bespoke.** Rejected after the observed LSP, ACP, PTY, and Code Runtime shapes showed that private process-tree signalling and environment scrubs would otherwise remain duplicated. The Node-shaped dispositions cover those consumers without buffering piped streams.
+
+**Use one `stdio: 'pipe' | 'inherit' | 'collect'` mode for all streams.** Rejected because real consumers mix modes per stream: LSP uses pipe/pipe/collect, ACP uses pipe/pipe/inherit, and Bash uses data/collect/collect.
+
+**Route every process launch through `ctx.subprocess`.** Rejected because the MCP SDK owns its transport spawn, the SDK wizard has no Cordis context and needs inherited redirection, the TUI probe is synchronous, and support launchers deliberately stay independent of product seams. PTY allocation did move behind `spawnTerminal()` because the provider, not the consumer, owns that substrate-specific primitive.
 
 **Put `run_in_background`/task semantics into the process seam instead.** Rejected: that boundary already exists — `ctx.tasks` owns ids, ownership, and notices, and the bash tool adapts a `BashProcess` into task hooks. The process seam sits *below* the bash executor, not beside the task registry.
 
@@ -33,6 +39,6 @@ Background-process lifetime moved from the executor to the subprocess service: t
 
 ## Consequences
 
-Bought: "run and manage a process" is a swappable capability used by Bash, LSP, PTY, Code Runtime, and ACP consumers; a containerized or remote process backend slots in without changing their domain semantics; the shared `DSH_*`/output vocabulary has a non-shell home; and background processes survive executor reloads, matching the task registry's lifetime model. Process and terminal plumbing is tested through `dsh-subprocess-local`; consumer suites pin only their owned behavior against the real service.
+Bought: "run and manage a process" is a swappable capability used by Bash, LSP, PTY, Code Runtime, and ACP consumers; a containerized or remote process backend slots in without changing their domain semantics; tree signalling, escalation, bounded collection, terminal mechanics, and credential scrubbing each have one implementation; and background processes survive executor reloads, matching the task registry's lifetime model. Process and terminal plumbing is tested through `dsh-subprocess-local`; consumer suites pin only their owned behavior against the real service.
 
-Cost: one more package pair and one more composition row everywhere a bash executor loads — a boot that loads an executor without the subprocess service leaves `ctx.bash` pending on `ctx.subprocess` (standard missing-service behavior). The moved-vocabulary re-exports keep `dsh-bash` imports working but mean two packages now name the same types; the subprocess seam is the owner and the bash seam documents the re-export. The spawn-failure note became single-delivery through the read path where the old plumbing retained it in the stderr buffer for repeated `readFrom(0)` reads — acceptable because the bash background read path was already a consuming cursor, and the note reaches the one reader that exists.
+Cost: one more package pair and one more composition row wherever a consumer loads; a missing subprocess provider leaves the consumer pending by standard service-injection behavior. Every backend implements execution-world coordinates, executable lookup, three stdio modes, tree lifecycle, and one terminal primitive. The moved-vocabulary re-exports keep `dsh-bash` imports working but mean two packages name the same types; the subprocess seam is the owner. The spawn-failure note became single-delivery through Bash's consuming read cursor instead of repeatable stderr-buffer content.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 884c572dc6..551fcc8f4d 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -12,8 +12,8 @@ Status: implemented
 
 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方：
 
-- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd 与运行时存储、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。其词汇包括按流划分的 stdio 处置方式（disposition）、进程与终端句柄、刻意不含超时／取消分类的退出事实，以及共享的凭据清除与 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput` 类型。`argv` 绝不经过 shell 解释。
-- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、私有运行时存储、前台／会话检查、清除之后合并显式 env 的凭据清除、进程树清理，以及终止每个受管进程并等待其退出的 dispose。该实现没有任何配置；每项限制都随 spec 到达。Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
+- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd 与运行时存储、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
+- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、私有运行时存储、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 seam 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该实现没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
 - **`dsh-bash-local`（消费方）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
 - **`dsh-bash`（seam）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash 消费方需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
 
@@ -21,11 +21,17 @@ Status: implemented
 
 后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为 seam 随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
 
+基于已观察到的流与生命周期需求，具备条件的进程消费方随后迁到该 seam：LSP 使用管道化协议流加收集式 stderr 尾部；ACP（Agent Client Protocol）后端使用管道化 ndjson、继承式 stderr 和消费方拥有的 stdin-EOF dispose 阶梯；PTY 使用 `spawnTerminal()`，同时保留就绪与终端策略；Code Runtime 使用普通原始管道。`dsh-subagent-subprocess` 与 LSP 私有进程树辅助函数均被删除。MCP 传输 spawn、SDK 包管理器运行器、同步 TUI Git 探测和刻意保持轻依赖的 test-support 启动器因所有权或执行形状仍留在外部；适用的生产调用方共享凭据清除。
+
 ## 曾考虑的替代方案
 
 **把进程管道留在 `dsh-bash-local` 里（维持现状）。**否决的理由与[任务注册表拆分](2026-07-26-task-registry-seam.md)得以落地的理由相同：这条边界既稳定，也早已记录在代码里（`run.ts` 的模块文档曾写明「this layer reacts to an abort signal; the executor owns deadlines and classifies causes」），而若继续将它保持私有，未来每个非 shell 运行器就只能要么 fork 这套机制，要么为非 bash 工作去依赖一个以 bash 命名的包。这组堆叠变更对用户可见的动因正是这一拆分。
 
-**在引入 seam 的同一变更中迁移仓库其余 spawn 调用点。**否决，因为在当时的规模下属于带有真实设计风险的范围蔓延。后续的[消费方迁移](2026-07-26-subprocess-consumer-migration.md)与[可移植执行环境](2026-07-28-portable-execution-world-consumers.md)决策围绕已观察到的 LSP、subagent、PTY 与 Code Runtime 消费方重塑接口；SDK 与 test-support 启动器因所有权归属仍留在服务之外。
+**保留最初只支持批量的接口，让流式消费方继续各自实现。**否决：已观察到的 LSP、ACP、PTY 与 Code Runtime 形状表明，这会继续保留重复的私有进程树信号与环境清除。Node 形状的处置方式覆盖这些消费方，又不缓冲管道化流。
+
+**用单个 `stdio: 'pipe' | 'inherit' | 'collect'` 模式统一全部流。**否决：真实消费方按流混用模式——LSP 使用 pipe/pipe/collect，ACP 使用 pipe/pipe/inherit，Bash 使用 data/collect/collect。
+
+**把每一次进程启动都路由到 `ctx.subprocess`。**否决：MCP SDK 拥有其传输 spawn，SDK 向导没有 Cordis 上下文且需要继承式重定向，TUI 探测是同步的，support 启动器则刻意独立于产品 seam。PTY 分配迁到 `spawnTerminal()`，因为这项底层专用原语归提供方而非消费方所有。
 
 **改把 `run_in_background`/任务语义放进进程 seam。**否决：那条边界已经存在。`ctx.tasks` 拥有 id、所有权与通知，bash 工具则把 `BashProcess` 适配成任务钩子。进程 seam 位于 bash 执行器*之下*，而不是与任务注册表并列。
 
@@ -33,6 +39,6 @@ Status: implemented
 
 ## 后果
 
-换来的是：「运行并管理一个进程」成为 Bash、LSP、PTY、Code Runtime 与 ACP（Agent Client Protocol）消费方共用的可替换能力；容器化或远程进程后端可以直接接入，而无需改变各领域语义；共享的 `DSH_*`/输出词汇有了一个不带 shell 含义的归属；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。进程与终端管道通过 `dsh-subprocess-local` 测试；消费方测试套件只需针对真实服务固定各自拥有的行为。
+换来的是：「运行并管理一个进程」成为 Bash、LSP、PTY、Code Runtime 与 ACP 消费方共用的可替换能力；容器化或远程进程后端可以直接接入，而无需改变各领域语义；进程树信号、升级终止、有界收集、终端机制与凭据清除各自只剩一份实现；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。进程与终端管道通过 `dsh-subprocess-local` 测试；消费方测试套件只需针对真实服务固定各自拥有的行为。
 
-代价是：多出一对包，而且凡加载 bash 执行器之处都多一行组合配置。若某次启动加载了执行器却没有加载管理器，`ctx.bash` 会因等待 `ctx.subprocess` 而保持挂起（标准的服务缺失行为）。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包如今命名同一批类型；进程 seam 是所有者，bash seam 则记录这层重导出。spawn 失败提示经由读取路径变为单次交付，而旧管道曾把它保留在 stderr 缓冲区里，供重复的 `readFrom(0)` 读取；这一点可以接受，因为 bash 的后台读取路径本就是消费游标，该提示能到达唯一存在的那个读取方。
+代价是：多出一对包，而且凡加载消费方之处都多一行组合配置；缺少 subprocess 提供方时，消费方会按标准服务注入行为保持挂起。每个后端都要实现执行环境坐标、可执行文件查找、三种 stdio 模式、进程树生命周期和一个终端原语。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包命名同一批类型；进程 seam 是所有者。spawn 失败提示经由 Bash 的消费式读取游标变为单次交付，不再是可重复读取的 stderr 缓冲内容。

From 68ccf50a77f34288de50d5008eb636851cd48e18 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 02:04:21 +0800
Subject: [PATCH 334/516] refactor(code-runtime): generate shared subprocess
 runner

---
 package.json                                  |   2 +
 .../code-runtime-worker/src/bootstrap.ts      |  19 +-
 .../code-runtime-worker/src/runtime-host.ts   |  26 +-
 .../tests/bootstrap.spec.ts                   |  27 ++
 .../src/runner-source.generated.ts            |   6 +
 packages/util/atomic-write/src/runner.ts      | 390 ++++++++++++++++++
 scripts/gen-code-runtime-runner.ts            |  70 ++++
 scripts/run-gates.ts                          |   1 +
 vitest.config.ts                              |  96 +----
 9 files changed, 555 insertions(+), 82 deletions(-)
 create mode 100644 packages/util/atomic-write/src/runner-source.generated.ts
 create mode 100644 packages/util/atomic-write/src/runner.ts
 create mode 100644 scripts/gen-code-runtime-runner.ts

diff --git a/package.json b/package.json
index 423cbf813c..2b4971a6b7 100644
--- a/package.json
+++ b/package.json
@@ -112,6 +112,8 @@
     "gen-module-graph": "tsx scripts/gen-module-graph.ts",
     "gen-scoped-events": "tsx scripts/gen-scoped-events.ts",
     "verify-scoped-events": "tsx scripts/gen-scoped-events.ts --check",
+    "gen-code-runtime-runner": "tsx scripts/gen-code-runtime-runner.ts",
+    "verify-code-runtime-runner": "tsx scripts/gen-code-runtime-runner.ts --check",
     "verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
     "constraints": "tsx scripts/check-workspace-constraints.ts",
     "doc-sync": "tsx scripts/run-gates.ts doc-sync",
diff --git a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
index cbe0d0ac55..2207389c97 100644
--- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
+++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
@@ -6,6 +6,7 @@
  */
 
 import { inspect } from 'node:util'
+import type { CodeJsonValue } from '@deepseek-ai/dsh-code-runtime'
 import type { DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'
 import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
 import { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
@@ -310,6 +311,7 @@ export function wireReplies(port: BootstrapPort, pending: Map<number, PendingCal
  * @param pending - the id-keyed map each posted call parks its handles in.
  * @param nextId - the shared mutable id counter (worker-issued correlation ids).
  * @param errorClasses - per-namespace constructors shared with program globals.
+ * @param maxFrameBytes - optional serialized transport cap checked before posting.
  * @returns one namespace object per declaration, in declaration order.
  */
 export function makeNamespaces(
@@ -318,6 +320,7 @@ export function makeNamespaces(
   pending: Map<number, PendingCall>,
   nextId: { value: number },
   errorClasses: Map<string, BindingErrorConstructor> = makeBindingErrorClasses(data),
+  maxFrameBytes?: number,
 ): Record<string, unknown>[] {
   return data.namespaces.map(({ global, names }) => {
     const errorClass = errorClasses.get(global)
@@ -335,6 +338,11 @@ export function makeNamespaces(
           if (detached === undefined) {
             return Promise.reject(bindingFailure(errorClass, name, 'binding arguments must be lossless JSON'))
           }
+          const call = { type: 'call' as const, id: nextId.value, global, name, args: encodeWorkerJson(detached) }
+          if (maxFrameBytes !== undefined
+            && jsonValueBytesUpTo(call as unknown as CodeJsonValue, maxFrameBytes) === undefined) {
+            return Promise.reject(bindingFailure(errorClass, name, 'binding arguments exceed maxFrameBytes'))
+          }
           return new Promise((resolve, reject) => {
             const id = nextId.value++
             pending.set(id, {
@@ -344,7 +352,7 @@ export function makeNamespaces(
               },
             })
             try {
-              port.postMessage({ type: 'call', id, global, name, args: encodeWorkerJson(detached) })
+              port.postMessage(call)
             } catch (error: unknown) {
               pending.delete(id)
               const message = `binding arguments must be structured-cloneable: ${error instanceof CapturedError ? error.message : String(error)}`
@@ -364,12 +372,14 @@ export function makeNamespaces(
  * @param port - host message port or test double.
  * @param data - the boot payload the host sent.
  * @param streams - stdout/stderr objects captured as program logs.
+ * @param maxFrameBytes - optional serialized transport cap checked before posting.
  * @returns after posting the done message.
  */
 export async function runWorkerMain(
   port: BootstrapPort,
   data: WorkerBootData,
   streams: { stdout: PatchableStream; stderr: PatchableStream },
+  maxFrameBytes?: number,
 ): Promise<void> {
   const logs = new LogBuffer(
     data.maxOutputBytes,
@@ -384,7 +394,7 @@ export async function runWorkerMain(
 
   const nextId = { value: 1 }
   const errorClasses = makeBindingErrorClasses(data)
-  const namespaces = makeNamespaces(data, port, pending, nextId, errorClasses)
+  const namespaces = makeNamespaces(data, port, pending, nextId, errorClasses, maxFrameBytes)
   const errorClassParameters: string[] = []
   const errorClassValues: BindingErrorConstructor[] = []
   for (const namespace of data.namespaces) {
@@ -420,5 +430,8 @@ export async function runWorkerMain(
       ...prepareException(error, logs.remainingOutputBytes(), data.maxOutputBytes),
     }
   }
-  port.postMessage(done)
+  port.postMessage(maxFrameBytes !== undefined
+    && jsonValueBytesUpTo(done as unknown as CodeJsonValue, maxFrameBytes) === undefined
+    ? { type: 'output-limit' }
+    : done)
 }
diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
index d2bb1082b8..47bfacfe91 100644
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
@@ -1,6 +1,7 @@
 /** Shared host mechanics for local and subprocess-hosted TypeScript worker runtimes. */
 
 import { stripTypeScriptTypes } from 'node:module'
+import type { Readable } from 'node:stream'
 import type {
   CodeBindingNamespace,
   CodeJsonValue,
@@ -15,6 +16,28 @@ import type { WorkerJsonWire } from './worker-json.ts'
 /** Smallest cap that can represent an empty log array and failure message. */
 export const MIN_RUNTIME_OUTPUT_BYTES = 4
 
+/**
+ * Resolve after a worker pipe emits queued data or closes during termination.
+ * @param stream - captured worker or child-process pipe.
+ * @returns after no more queued bytes can arrive.
+ */
+export function waitForRuntimePipeDrain(stream: Readable): Promise<void> {
+  if (stream.readableEnded || stream.destroyed) return Promise.resolve()
+  return new Promise((resolve) => {
+    const done = (): void => {
+      stream.off('end', done)
+      stream.off('close', done)
+      stream.off('error', done)
+      resolve()
+    }
+    stream.once('end', done)
+    stream.once('close', done)
+    stream.once('error', done)
+    /* v8 ignore next -- termination can win the adjacent listener-registration race. */
+    if (stream.readableEnded || stream.destroyed) done()
+  })
+}
+
 const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 const RESERVED_WORDS = new Set([
   'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
@@ -223,5 +246,6 @@ export class RuntimeOutputLedger {
 }
 
 export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
-export { jsonValueBytesUpTo } from './output-json.ts'
+export { jsonStringBytesUpTo, jsonValueBytesUpTo } from './output-json.ts'
+export { runWorkerMain } from './bootstrap.ts'
 export type { WorkerJsonWire } from './worker-json.ts'
diff --git a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
index a2aac6d9c2..247501df29 100644
--- a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
@@ -286,6 +286,23 @@ describe('makeNamespaces', () => {
     expect(nextId.value).toBe(1)
   })
 
+  it('rejects an oversized transport frame before posting or allocating a call id', async () => {
+    const port = new FakePort()
+    const pending = new Map<number, PendingCall>()
+    const nextId = { value: 1 }
+    const data = { namespaces: [toolNamespace(['x'])] }
+    const [tools] = makeNamespaces(
+      data, port, pending, nextId, makeBindingErrorClasses(data), 64,
+    ) as [Record<string, (args: unknown) => Promise<unknown>>]
+
+    await expect(tools.x?.({ text: 'x'.repeat(64) })).rejects.toMatchObject({
+      name: 'ToolCallError', toolName: 'x', message: 'binding arguments exceed maxFrameBytes',
+    })
+    expect(port.sent).toEqual([])
+    expect(pending.size).toBe(0)
+    expect(nextId.value).toBe(1)
+  })
+
   it('uses ordinary Error for non-tools namespace failures', async () => {
     const deniedPort = new FakePort()
     deniedPort.respond = message => message.type === 'call'
@@ -343,6 +360,16 @@ describe('runWorkerMain', () => {
     })
   })
 
+  it('reports output-limit before posting a completion that expands past the transport cap', async () => {
+    const port = new FakePort()
+    await runWorkerMain(port, {
+      maxOutputBytes: 1_000,
+      code: 'return Array.from({ length: 100 }, () => [])',
+      namespaces: [],
+    }, fakeStreams(), 100)
+    expect(port.sent.at(-1)).toEqual({ type: 'output-limit' })
+  })
+
   it('reports a thrown program error on the done message', async () => {
     const port = new FakePort()
     await runWorkerMain(port, { ...BOOT, code: 'throw new Error("boom")', namespaces: [] }, fakeStreams())
diff --git a/packages/util/atomic-write/src/runner-source.generated.ts b/packages/util/atomic-write/src/runner-source.generated.ts
new file mode 100644
index 0000000000..d40c77783c
--- /dev/null
+++ b/packages/util/atomic-write/src/runner-source.generated.ts
@@ -0,0 +1,6 @@
+/**
+ * Generated dependency-free execution-world runner.
+ * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.
+ */
+
+export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{fork as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{fileURLToPath as i}from\"node:url\";import{Worker as a,isMainThread as o,parentPort as s,workerData as c}from\"node:worker_threads\";const l=Reflect.apply,u=Array.isArray,d=Buffer,f=Reflect.get(Buffer,`byteLength`),ee=Object.create,p=Object.defineProperty,te=Object.keys,ne=String,re=Reflect.get(String.prototype,`charCodeAt`),ie=Reflect.get(String.prototype,`codePointAt`),m=Reflect.get(String.prototype,`slice`);function h(e){let t=ee(null);return t.value=e,t}function ae(e,t,n){let r=h(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function g(e){return l(f,d,[e,`utf8`])}function _(e,t){ae(e,e.length,t)}function oe(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,h(t)),n}function se(e,t){return l(m,e,[t,t+(l(ie,e,[t])>65535?2:1)])}function ce(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=l(re,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:g(e)}function v(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=se(e,r);if(n+=ce(i),n>t)return;r+=i.length}return n}function y(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=oe(i);e!==void 0;e=oe(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=v(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(g(ne(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(u(a)){if(!r(2))return;a.length>0&&_(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=te(a);e.length>0&&_(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=v(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:s})}return n}function le(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=se(e,i),o=ce(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:l(m,e,[0,r])}const ue=Reflect.get(Function.prototype,`toString`),b=Reflect.get(Reflect,`apply`),x=Error,S=Set,C=Array.isArray,de=Array.prototype,w=Number.isFinite,fe=Number.isSafeInteger,pe=Object.create,me=Object.defineProperty,he=Object.getOwnPropertyDescriptor,T=Object.getPrototypeOf,ge=Object.hasOwn,E=Object.is,_e=Object.keys,D=Object.prototype,ve=Reflect.get(D,`propertyIsEnumerable`),O=Reflect.ownKeys,ye=Reflect.get(Set.prototype,`add`),be=Reflect.get(Set.prototype,`delete`),xe=Reflect.get(Set.prototype,`has`);function k(e){let t=pe(null);return t.value=e,t}function A(e,t,n){let r=k(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,me(e,t,r)}function j(e,t){A(e,e.length,t)}function M(e){if(e.length===0)return;let t=e.length-1,n=e[t];return me(e,`length`,k(t)),n}function N(e,t){return b(xe,e,[t])}function P(e,t){b(ye,e,[t])}function Se(e,t){b(be,e,[t])}function F(e,t){let n=he(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&b(ue,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function I(e){return T(e)===null&&F(e,`Object`)}function L(e){let t=T(e);if(t===de)return!0;if(!C(t)||!F(t,`Array`))return!1;let n=T(t);return typeof n==`object`&&!!n&&I(n)}function R(e){let t=T(e);return t===null||t===D||typeof t==`object`&&I(t)}function z(e){let t=O(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!b(ve,e,[r]))return}return t}function B(e){let t=new S,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?A(e.target,e.index,t):A(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=M(i);e!==void 0;e=M(i)){if(e.kind===`leave`){Se(t,e.source);continue}if(e.kind===`array-item`){if(!ge(e.source,e.index))return;j(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){j(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!w(n)||E(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||N(t,n))return;if(C(n)){if(!L(n))return;let a=n.length;if(O(n).length!==a+1)return;let o=[];r(e.destination,o),P(t,n),j(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)j(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!R(n))return;let a=z(n);if(a===void 0)return;let o={};r(e.destination,o),P(t,n),j(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;j(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function V(e){let t=[],n=[e];for(let e=M(n);e!==void 0;e=M(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){j(t,e);continue}if(C(e)){j(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new x(`cannot encode a sparse JSON array`);j(n,r)}continue}let r=_e(e);j(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new x(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new x(`cannot encode an undefined JSON object property`);j(n,a)}}return t}function H(e){if(!L(e)||O(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!ge(e,t))return!1;return!0}function U(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function Ce(e){if(C(e)||!R(e))return;let t=z(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!U(t,`kind`)||!U(t,`length`))return;let e=n.length;return typeof e==`number`&&fe(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!U(t,`kind`)||!U(t,`keys`))return;let e=n.keys;if(!C(e)||!H(e))return;let r=new S,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||N(r,t))return;P(r,t),j(i,t)}return{kind:`object`,keys:i}}}function W(e){try{if(!C(e)||!H(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)j(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;A(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!w(r)||E(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=Ce(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&j(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;M(n)}}return n.length===0?r:void 0}catch{return}}const G=Error,we=Object.create,Te=Object.defineProperty;function K(e,t,n){let r=we(null);r.enumerable=!0,r.value=n,Te(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=v(e,n);if(r===void 0){this.truncated=!0;let r=le(e,n);if(r.length>0){let e=v(r,n);if(e===void 0)throw new G(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=B(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):y(r,t)===void 0?Me(n):{value:V(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return v(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof G?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends G{constructor(t,n){super(n),K(this,`name`,e.name),K(this,e.memberNameProperty,t)}}}function q(e,t,n){return e?new e(t,n):new G(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=W(e.value);t===void 0?n.reject(new G(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new G(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=B(o)}catch{c=void 0}if(c===void 0)return Promise.reject(q(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:V(c)};return a!==void 0&&y(l,a)===void 0?Promise.reject(q(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(q(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(q(s,i,`binding arguments must be structured-cloneable: ${e instanceof G?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new G(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&y(f,r)===void 0?{type:`output-limit`}:f)}function J(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let Y=0;function X(e){return typeof e==`object`&&e?e:void 0}function Z(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function Ve(e){process.stdout.write(e),process.stdout.write(`\n`)}function He(e){let t=Z(e,Y);return t===void 0?!1:(Ve(t),!0)}function Ue(e){let t=X(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function We(e){return Ue(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ge(e){let t=X(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function Ke(e){let t=X(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=W(e);return t===void 0?null:V(t)}function qe(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Je(){let e=n({input:process.stdin,crlfDelay:1/0}),r,a=0,o=2,s=0,c=!1,l=t=>{if(c)return;let n=Z(t,Y)??Z($(),Y);c=!0,n!==void 0&&Ve(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(i.stdout),t=J(i.stderr),n=qe(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},u=e=>{if(c)return;let t=+(s>0),n=v(e,a-o-t);if(n===void 0){l({type:`output-limit`});return}o+=n+t,s+=1,He({type:`log`,text:e})||l($())},d=e=>{a=e.maxOutputBytes,Y=e.maxFrameBytes,r=t(i(import.meta.url),[],{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,execArgv:[],stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{u(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{u(e.toString(`utf8`))}),n.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){u(t.text);return}c||(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`?He({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||l($()):t.type===`output-limit`?l({type:`output-limit`}):t.type===`done`&&(t.error===void 0?l({type:`done`,...t.value===void 0?{}:{value:Q(t.value)}}):Ue(t.error)&&l({type:`done`,error:t.error})))}}),n.on(`error`,e=>{l({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{c||l({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Ge(t);if(e===void 0){l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}d(e);return}let n=Ke(t);n!==void 0&&r.send(n,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!c&&l({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Ye(){let e,t=!1,n,i=0,o=e=>process.send===void 0||i>0&&Z(e,i)===void 0?!1:(process.send(e),!0),s=r=>{if(t)return;t=!0,clearInterval(n);let a=i>0&&Z(r,i)===void 0?$():r,s=e;e=void 0,(s===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(s.stdout),t=J(s.stderr);await Promise.all([s.terminate(),e,t])})).catch(e=>{o({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(a,()=>{process.connected&&process.disconnect()})})};process.on(`message`,c=>{if(e===void 0){let l=Ge(c);if(l===void 0){s({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}i=l.maxFrameBytes,e=new a(new URL(import.meta.url),{workerData:l,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:l.maxOldGenerationSizeMb}});let u=e;u.stdout.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.stderr.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.on(`message`,e=>{let t=X(e);t!==void 0&&(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`?o({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||s($()):t.type===`log`&&typeof t.text==`string`?o({type:`log`,text:t.text})||s($()):t.type===`output-limit`?s({type:`output-limit`}):t.type===`done`&&(t.error===void 0?s({type:`done`,...t.value===void 0?{}:{value:Q(t.value)}}):We(t.error)&&s({type:`done`,error:t.error})))}),u.on(`error`,e=>{s({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),u.on(`exit`,e=>{t||s({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),n=setInterval(()=>{e!==void 0&&e.performance.eventLoopUtilization().active>l.computeMs&&s({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${l.computeMs}ms busy)`}})},25);return}let l=Ke(c);l!==void 0&&e.postMessage(l)}),process.on(`disconnect`,()=>{e!==void 0&&!t&&e.terminate()})}if(o)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Ye():Je();else{if(s===null)throw Error(`remote worker requires parentPort`);let e=c;ze(s,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
diff --git a/packages/util/atomic-write/src/runner.ts b/packages/util/atomic-write/src/runner.ts
new file mode 100644
index 0000000000..7a0b3eb678
--- /dev/null
+++ b/packages/util/atomic-write/src/runner.ts
@@ -0,0 +1,390 @@
+/** Typed source for the dependency-free execution-world runner bundle. */
+
+import { Buffer } from 'node:buffer'
+import { fork } from 'node:child_process'
+import type { ChildProcess } from 'node:child_process'
+import { createInterface } from 'node:readline'
+import type { Readable } from 'node:stream'
+import { inspect } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
+import {
+  decodeWorkerJson,
+  encodeWorkerJson,
+  jsonStringBytesUpTo,
+  runWorkerMain,
+  waitForRuntimePipeDrain,
+} from '@deepseek-ai/dsh-code-runtime-worker/runtime-host'
+import type { WorkerJsonWire } from '@deepseek-ai/dsh-code-runtime-worker/runtime-host'
+
+type WorkerBootData = Parameters<typeof runWorkerMain>[1]
+type Controller = ChildProcess & { stdout: Readable; stderr: Readable }
+type FailureKind = 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'
+
+interface RuntimeBootData extends WorkerBootData {
+  type: 'boot'
+  maxFrameBytes: number
+  maxOldGenerationSizeMb: number
+  computeMs: number
+}
+
+interface RuntimeFailure {
+  kind: FailureKind
+  message: string
+}
+
+interface RuntimeCall {
+  type: 'call'
+  id: number
+  global: string
+  name: string
+  args: WorkerJsonWire | null
+}
+
+type RuntimeReply =
+  | { type: 'reply'; id: number; ok: true; value: unknown }
+  | { type: 'reply'; id: number; ok: false; message: string }
+
+type RuntimeMessage = RuntimeCall
+  | { type: 'log'; text: string }
+  | { type: 'output-limit' }
+  | { type: 'done'; value?: WorkerJsonWire | null; error?: RuntimeFailure }
+
+const failureKinds = new Set<FailureKind>([
+  'exception', 'timeout', 'abort', 'worker-exit', 'invalid-output', 'output-limit',
+])
+
+let maxFrameBytes = 0
+
+function recordOf(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : undefined
+}
+
+function encodeJsonBounded(value: unknown, maxBytes: number): string | undefined {
+  try {
+    const json: unknown = JSON.stringify(value)
+    return typeof json === 'string' && Buffer.byteLength(json) <= maxBytes ? json : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function emitJson(json: string): void {
+  process.stdout.write(json)
+  process.stdout.write('\n')
+}
+
+function emitFrame(message: RuntimeMessage): boolean {
+  const json = encodeJsonBounded(message, maxFrameBytes)
+  if (json === undefined) return false
+  emitJson(json)
+  return true
+}
+
+function validFailure(value: unknown): value is RuntimeFailure {
+  const record = recordOf(value)
+  return record !== undefined
+    && typeof record.kind === 'string'
+    && failureKinds.has(record.kind as FailureKind)
+    && typeof record.message === 'string'
+}
+
+function validWorkerFailure(value: unknown): value is RuntimeFailure {
+  return validFailure(value)
+    && (value.kind === 'exception' || value.kind === 'invalid-output' || value.kind === 'output-limit')
+}
+
+function runtimeBoot(value: unknown): RuntimeBootData | undefined {
+  const record = recordOf(value)
+  if (record === undefined
+    || record.type !== 'boot'
+    || typeof record.code !== 'string'
+    || !Array.isArray(record.namespaces)
+    || !Number.isSafeInteger(record.maxOutputBytes)
+    || (record.maxOutputBytes as number) < 4
+    || !Number.isSafeInteger(record.maxFrameBytes)
+    || (record.maxFrameBytes as number) < (record.maxOutputBytes as number)
+    || typeof record.computeMs !== 'number'
+    || !Number.isFinite(record.computeMs)
+    || (record.computeMs) <= 0
+    || typeof record.maxOldGenerationSizeMb !== 'number'
+    || !Number.isFinite(record.maxOldGenerationSizeMb)
+    || (record.maxOldGenerationSizeMb) <= 0) return undefined
+  return record as unknown as RuntimeBootData
+}
+
+function runtimeReply(value: unknown): RuntimeReply | undefined {
+  const record = recordOf(value)
+  if (record === undefined || record.type !== 'reply' || typeof record.id !== 'number' || typeof record.ok !== 'boolean') return undefined
+  return record.ok
+    ? { type: 'reply', id: record.id, ok: true, value: record.value }
+    : { type: 'reply', id: record.id, ok: false, message: String(record.message) }
+}
+
+function transportWireOrNull(input: unknown): WorkerJsonWire | null {
+  const value = decodeWorkerJson(input)
+  return value === undefined ? null : encodeWorkerJson(value)
+}
+
+function waitForChildExit(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
+  return new Promise((resolve) => { child.once('exit', () => { resolve() }) })
+}
+
+function frameLimitFailure(): RuntimeMessage {
+  return {
+    type: 'done',
+    error: { kind: 'worker-exit', message: 'code runtime bridge frame exceeded maxFrameBytes' },
+  }
+}
+
+function runLauncher(): void {
+  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
+  let controller: Controller | undefined
+  let maxOutputBytes = 0
+  let logBytes = 2
+  let logEntries = 0
+  let settling = false
+
+  const finish = (message: RuntimeMessage): void => {
+    if (settling) return
+    const encoded = encodeJsonBounded(message, maxFrameBytes)
+      ?? encodeJsonBounded(frameLimitFailure(), maxFrameBytes)
+    settling = true
+    if (encoded !== undefined) emitJson(encoded)
+    const current = controller
+    controller = undefined
+    const drain = current === undefined
+      ? Promise.resolve()
+      : new Promise<void>((resolve) => { setImmediate(resolve) }).then(async () => {
+        const stdoutDrained = waitForRuntimePipeDrain(current.stdout)
+        const stderrDrained = waitForRuntimePipeDrain(current.stderr)
+        const exited = waitForChildExit(current)
+        current.kill('SIGKILL')
+        await Promise.all([exited, stdoutDrained, stderrDrained])
+      })
+    void drain.catch((error: unknown) => {
+      process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(error)}\n`)
+    }).then(() => {
+      input.close()
+      process.stdin.destroy()
+    })
+  }
+
+  const forwardLog = (text: string): void => {
+    if (settling) return
+    const separator = logEntries > 0 ? 1 : 0
+    const cost = jsonStringBytesUpTo(text, maxOutputBytes - logBytes - separator)
+    if (cost === undefined) {
+      finish({ type: 'output-limit' })
+      return
+    }
+    logBytes += cost + separator
+    logEntries += 1
+    if (!emitFrame({ type: 'log', text })) finish(frameLimitFailure())
+  }
+
+  const startController = (boot: RuntimeBootData): void => {
+    maxOutputBytes = boot.maxOutputBytes
+    maxFrameBytes = boot.maxFrameBytes
+    controller = fork(fileURLToPath(import.meta.url), [], {
+      env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
+      detached: false,
+      execArgv: [],
+      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+    }) as Controller
+    const current = controller
+    current.stdout.on('data', (data: Buffer) => { forwardLog(data.toString('utf8')) })
+    current.stderr.on('data', (data: Buffer) => { forwardLog(data.toString('utf8')) })
+    current.on('message', (raw: unknown) => {
+      const message = recordOf(raw)
+      if (message === undefined) return
+      if (message.type === 'log' && typeof message.text === 'string') {
+        forwardLog(message.text)
+        return
+      }
+      if (settling) return
+      if (message.type === 'call'
+        && typeof message.id === 'number'
+        && typeof message.global === 'string'
+        && typeof message.name === 'string') {
+        if (!emitFrame({
+          type: 'call', id: message.id, global: message.global, name: message.name, args: transportWireOrNull(message.args),
+        })) finish(frameLimitFailure())
+      } else if (message.type === 'output-limit') {
+        finish({ type: 'output-limit' })
+      } else if (message.type === 'done') {
+        if (message.error !== undefined) {
+          if (validFailure(message.error)) finish({ type: 'done', error: message.error })
+        } else {
+          finish({ type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } })
+        }
+      }
+    })
+    current.on('error', (error: Error) => {
+      finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller error: ${error.message}` } })
+    })
+    current.on('exit', (code: number | null) => {
+      if (!settling) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller exited with code ${code} before completing` } })
+      }
+    })
+    current.send(boot, (error: Error | null) => {
+      if (error !== null) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller boot failed: ${error.message}` } })
+      }
+    })
+  }
+
+  input.on('line', (line: string) => {
+    let raw: unknown
+    try {
+      raw = JSON.parse(line) as unknown
+    } catch (error: unknown) {
+      process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(error)}\n`)
+      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received a malformed frame' } })
+      return
+    }
+    if (controller === undefined) {
+      const boot = runtimeBoot(raw)
+      if (boot === undefined) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
+        return
+      }
+      startController(boot)
+      return
+    }
+    const reply = runtimeReply(raw)
+    if (reply !== undefined) {
+      controller.send(reply, (error: Error | null) => {
+        if (error !== null) {
+          finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller reply failed: ${error.message}` } })
+        }
+      })
+    }
+  })
+  input.on('close', () => {
+    if (controller !== undefined && !settling) {
+      finish({ type: 'done', error: { kind: 'abort', message: 'remote runner input closed' } })
+    }
+  })
+}
+
+function runController(): void {
+  let worker: Worker | undefined
+  let finished = false
+  let computeTimer: NodeJS.Timeout | undefined
+  let controllerMaxFrameBytes = 0
+
+  const send = (message: RuntimeMessage): boolean => {
+    if (process.send === undefined) return false
+    if (controllerMaxFrameBytes > 0 && encodeJsonBounded(message, controllerMaxFrameBytes) === undefined) return false
+    process.send(message)
+    return true
+  }
+
+  const finish = (message: RuntimeMessage): void => {
+    if (finished) return
+    finished = true
+    clearInterval(computeTimer)
+    const bounded = controllerMaxFrameBytes > 0 && encodeJsonBounded(message, controllerMaxFrameBytes) === undefined
+      ? frameLimitFailure()
+      : message
+    const current = worker
+    worker = undefined
+    const drain = current === undefined
+      ? Promise.resolve()
+      : new Promise<void>((resolve) => { setImmediate(resolve) }).then(async () => {
+        const stdoutDrained = waitForRuntimePipeDrain(current.stdout)
+        const stderrDrained = waitForRuntimePipeDrain(current.stderr)
+        await Promise.all([current.terminate(), stdoutDrained, stderrDrained])
+      })
+    void drain.catch((error: unknown) => {
+      send({ type: 'log', text: `dsh-code-runtime-subprocess worker cleanup error: ${String(error)}\n` })
+    }).then(() => {
+      if (process.send === undefined) {
+        process.exitCode = 1
+        return
+      }
+      process.send(bounded, () => { if (process.connected) process.disconnect() })
+    })
+  }
+
+  process.on('message', (raw: unknown) => {
+    if (worker === undefined) {
+      const boot = runtimeBoot(raw)
+      if (boot === undefined) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller received an invalid boot frame' } })
+        return
+      }
+      controllerMaxFrameBytes = boot.maxFrameBytes
+      worker = new Worker(new URL(import.meta.url), {
+        workerData: boot,
+        env: {},
+        execArgv: [],
+        stdout: true,
+        stderr: true,
+        resourceLimits: { maxOldGenerationSizeMb: boot.maxOldGenerationSizeMb },
+      })
+      const current = worker
+      current.stdout.on('data', (data: Buffer) => {
+        if (!send({ type: 'log', text: data.toString('utf8') })) finish(frameLimitFailure())
+      })
+      current.stderr.on('data', (data: Buffer) => {
+        if (!send({ type: 'log', text: data.toString('utf8') })) finish(frameLimitFailure())
+      })
+      current.on('message', (messageRaw: unknown) => {
+        const message = recordOf(messageRaw)
+        if (message === undefined) return
+        if (message.type === 'call'
+          && typeof message.id === 'number'
+          && typeof message.global === 'string'
+          && typeof message.name === 'string') {
+          if (!send({
+            type: 'call', id: message.id, global: message.global, name: message.name, args: transportWireOrNull(message.args),
+          })) finish(frameLimitFailure())
+        } else if (message.type === 'log' && typeof message.text === 'string') {
+          if (!send({ type: 'log', text: message.text })) finish(frameLimitFailure())
+        } else if (message.type === 'output-limit') {
+          finish({ type: 'output-limit' })
+        } else if (message.type === 'done') {
+          if (message.error !== undefined) {
+            if (validWorkerFailure(message.error)) finish({ type: 'done', error: message.error })
+          } else {
+            finish({ type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } })
+          }
+        }
+      })
+      current.on('error', (error: Error) => {
+        finish({
+          type: 'done',
+          error: { kind: 'worker-exit', message: `worker error: ${error.stack || error.message || inspect(error)}` },
+        })
+      })
+      current.on('exit', (code: number) => {
+        if (!finished) {
+          finish({ type: 'done', error: { kind: 'worker-exit', message: `worker exited with code ${code} before completing` } })
+        }
+      })
+      computeTimer = setInterval(() => {
+        if (worker !== undefined && worker.performance.eventLoopUtilization().active > boot.computeMs) {
+          finish({ type: 'done', error: { kind: 'timeout', message: `compute budget exhausted (${boot.computeMs}ms busy)` } })
+        }
+      }, 25)
+      return
+    }
+    const reply = runtimeReply(raw)
+    if (reply !== undefined) worker.postMessage(reply)
+  })
+  process.on('disconnect', () => { if (worker !== undefined && !finished) void worker.terminate() })
+}
+
+if (!isMainThread) {
+  if (parentPort === null) throw new Error('remote worker requires parentPort')
+  const boot = workerData as RuntimeBootData
+  void runWorkerMain(parentPort, boot, { stdout: process.stdout, stderr: process.stderr }, boot.maxFrameBytes)
+} else if (process.env.DSH_CODE_RUNTIME_CONTROLLER === '1') {
+  runController()
+} else {
+  runLauncher()
+}
diff --git a/scripts/gen-code-runtime-runner.ts b/scripts/gen-code-runtime-runner.ts
new file mode 100644
index 0000000000..7e856e7651
--- /dev/null
+++ b/scripts/gen-code-runtime-runner.ts
@@ -0,0 +1,70 @@
+/** Generate the subprocess Code Runtime's dependency-free runner bundle. */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { build } from 'tsdown'
+
+const root = resolve(import.meta.dirname, '..')
+const ENTRY = 'packages/code-runtime/code-runtime-subprocess/src/runner.ts'
+const OUT = 'packages/code-runtime/code-runtime-subprocess/src/runner-source.generated.ts'
+
+/**
+ * Bundle the typed runner and shared worker implementation into one source literal.
+ * @returns generated TypeScript module consumed by the subprocess backend.
+ */
+export async function renderCodeRuntimeRunner(): Promise<string> {
+  const bundles = await build({
+    config: false,
+    entry: [resolve(root, ENTRY)],
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    write: false,
+    dts: false,
+    clean: false,
+    minify: true,
+    logLevel: 'silent',
+    report: false,
+    deps: { alwaysBundle: ['@deepseek-ai/dsh-code-runtime-worker'] },
+  })
+  try {
+    const chunks = bundles.flatMap(bundle => bundle.chunks).filter(chunk => chunk.type === 'chunk')
+    if (chunks.length !== 1) throw new Error(`gen-code-runtime-runner: expected one chunk, received ${chunks.length}`)
+    const chunk = chunks[0]
+    if (chunk === undefined) throw new Error('gen-code-runtime-runner: runner chunk is missing')
+    const external = chunk.imports.filter(specifier => !specifier.startsWith('node:'))
+    if (external.length > 0) {
+      throw new Error(`gen-code-runtime-runner: runner retained external imports: ${external.join(', ')}`)
+    }
+    return [
+      '/**',
+      ' * Generated dependency-free execution-world runner.',
+      ' * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.',
+      ' */',
+      '',
+      `export const CODE_RUNNER_SOURCE = ${JSON.stringify(chunk.code)}`,
+      '',
+    ].join('\n')
+  } finally {
+    await Promise.all(bundles.map(async (bundle) => { await bundle[Symbol.asyncDispose]() }))
+  }
+}
+
+async function main(): Promise<void> {
+  const content = await renderCodeRuntimeRunner()
+  const output = resolve(root, OUT)
+  if (process.argv.includes('--check')) {
+    const committed = existsSync(output) ? readFileSync(output, 'utf8') : null
+    if (committed === content) {
+      console.log(`gen-code-runtime-runner: ${OUT} is up to date.`)
+      return
+    }
+    console.error(`gen-code-runtime-runner: ${OUT} is stale. Run \`pnpm run gen-code-runtime-runner\` and commit it.`)
+    process.exitCode = 1
+    return
+  }
+  writeFileSync(output, content)
+  console.log(`gen-code-runtime-runner: wrote ${OUT}.`)
+}
+
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) await main()
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 74a09a874e..6f59b64826 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -585,6 +585,7 @@ function docSyncLeafGates(options: {
     pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }),
     pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }),
     pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }),
+    pnpmScript('code-runtime-runner', 'verify-code-runtime-runner', { label: 'code-runtime runner' }),
     pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }),
     pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
     pnpmScript('public-repository-links', 'verify-public-repository-links', { label: 'public repository links' }),
diff --git a/vitest.config.ts b/vitest.config.ts
index 6eb1bda354..996f2456c7 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,16 +1,5 @@
-import { spawnSync } from 'node:child_process'
-import { fileURLToPath } from 'node:url'
 import tsconfigPaths from 'vite-tsconfig-paths'
-import { resolvePwshPath } from './packages/bash/pwsh-local/src/resolve.ts'
 import { defineConfig } from 'vitest/config'
-import { standardDecoratorPlugin, vitestExecArgv } from './vitest.shared.ts'
-import { COVERAGE_EXEMPT_ENV, coverageExemptHeavySuites } from './scripts/coverage-exempt.ts'
-
-// Prints exact `path:line:col` records for every uncovered statement, branch
-// path, and function when a file misses the per-file 100% gate — the built-in
-// threshold ERRORs name only the file. Absolute path because istanbul-reports
-// require()s custom reporters (which is also why the reporter is CJS).
-const uncoveredLocationsReporter = fileURLToPath(new URL('./scripts/coverage-uncovered-locations.cjs', import.meta.url))
 
 // Resolution facade shared by every plugin instance below: tsconfig.base.json
 // has no include, which vite-tsconfig-paths treats as match-all, so its paths
@@ -20,14 +9,7 @@ const pathsPlugin = (): ReturnType<typeof tsconfigPaths> => tsconfigPaths({ proj
 
 const windowsUnsupportedPackages = process.platform === 'win32'
   ? [
-      // Bash-requiring suites (a real POSIX shell is unavailable on Windows).
-      // The pwsh-requiring suites (pwsh-local, tool-pwsh) deliberately stay
-      // INCLUDED: PowerShell ships with Windows, so they run natively here.
-      // Replacing the old 'packages/bash/*' glob with this explicit list also
-      // newly INCLUDES packages/bash/bash (the pure seam package) on Windows.
-      'packages/bash/bash-local',
-      'packages/bash/bash-sandbox',
-      'packages/bash/tool-bash',
+      'packages/bash/*',
       'packages/hooks/*',
       'packages/subprocess/*',
       'packages/pty/pty-local',
@@ -44,20 +26,10 @@ const windowsCoverageExclusions = process.platform === 'win32'
       'packages/lsp/lsp-local/src/connection.ts',
       'packages/lsp/lsp-local/src/index.ts',
       'packages/lsp/lsp-local/src/instance.ts',
+      'packages/ui/tui/src/index.ts',
     ]
   : []
 
-// Mirrors windowsCoverageExclusions: pwsh-local's run/start/lifecycle suites
-// self-skip without a real pwsh (executor.spec.ts hasPwsh), leaving this file
-// far below per-file 100% on pwsh-less hosts; the exemption keeps those hosts
-// green while CI runners ship pwsh and still enforce the full bar. The probe
-// runs the suites' own resolution (the dependency-free resolve.ts module),
-// so the exemption is active exactly when the suites skip — a mismatched
-// narrower probe could exempt the file on hosts whose suites actually run.
-const pwshCoverageExclusions = spawnSync(resolvePwshPath(), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '$true'], { encoding: 'utf8' }).status === 0
-  ? []
-  : ['packages/bash/pwsh-local/src/index.ts']
-
 const testIncludes = [
   'packages/*/*/tests/**/*.spec.{ts,tsx}',
   'apps/*/tests/**/*.spec.ts',
@@ -65,17 +37,6 @@ const testIncludes = [
   'scripts/**/*.spec.ts',
 ]
 
-// The instrumented coverage gate sets this env; the exempt heavy suites then
-// run beside it uninstrumented (membership contract in scripts/coverage-exempt.ts).
-// A set-but-not-'1' value is a misconfiguration, not a silent no-op.
-const coverageExemptRaw = process.env[COVERAGE_EXEMPT_ENV]
-if (coverageExemptRaw !== undefined && coverageExemptRaw !== '' && coverageExemptRaw !== '1') {
-  throw new Error(`vitest config: ${COVERAGE_EXEMPT_ENV} must be '1' or unset, got ${JSON.stringify(coverageExemptRaw)}.`)
-}
-const coverageExemptExcludes = coverageExemptRaw === '1'
-  ? coverageExemptHeavySuites.map(suite => suite.exclude)
-  : []
-
 // These suites exercise process-global state, process APIs, or timing-sensitive process I/O
 // that worker threads cannot isolate reliably under aggregate gate contention.
 // Keep the narrow exception in forks while the rest of the inventory avoids per-file processes.
@@ -88,48 +49,39 @@ const processBoundTests = [
 ]
 
 export default defineConfig({
-  plugins: [pathsPlugin(), standardDecoratorPlugin()],
+  plugins: [pathsPlugin()],
   test: {
     setupFiles: ['./scripts/test-invariants.ts'],
     // .tsx: client component specs (jsdom via per-file @vitest-environment pragma).
     include: testIncludes,
     exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
-    // One coverage invocation aggregates both projects. Regular suites fork on
-    // POSIX for Node stability and use threads on Windows; process-bound suites
-    // always fork.
+    // One coverage invocation aggregates both projects. Most suites use threads
+    // for lower startup/IPC overhead; only explicit process-bound suites fork.
     projects: [
       {
-        plugins: [pathsPlugin(), standardDecoratorPlugin()],
+        plugins: [pathsPlugin()],
         test: {
           name: 'thread-safe',
-          execArgv: vitestExecArgv,
-          // Node 24 has aborted in its CJS lexer (v8::ToLocalChecked Empty
-          // MaybeLocal in cjs_lexer::Parse) from worker threads on macOS
-          // arm64 and later on Linux. A fork contains that external runtime
-          // failure to the test process; Windows keeps the thread pool, where
-          // the abort has not reproduced and process spawn is costlier.
-          pool: process.platform === 'win32' ? 'threads' : 'forks',
+          // Node 24 has aborted in its CJS lexer from a macOS arm64 worker
+          // thread. A fork contains that external runtime failure to the test
+          // process; other hosts retain the lower-overhead thread pool.
+          pool: process.platform === 'darwin' ? 'forks' : 'threads',
           setupFiles: ['./scripts/test-invariants.ts'],
           include: testIncludes,
           exclude: [
             ...windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
             ...processBoundTests,
-            ...coverageExemptExcludes,
           ],
         },
       },
       {
-        plugins: [pathsPlugin(), standardDecoratorPlugin()],
+        plugins: [pathsPlugin()],
         test: {
           name: 'process-bound',
-          execArgv: vitestExecArgv,
           pool: 'forks',
           setupFiles: ['./scripts/test-invariants.ts'],
           include: processBoundTests,
-          exclude: [
-            ...windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
-            ...coverageExemptExcludes,
-          ],
+          exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
         },
       },
     ],
@@ -146,8 +98,7 @@ export default defineConfig({
         'packages/*/*/src/types.ts',
         'packages/*/*/src/bin.ts',
         'packages/*/*/src/worker.ts',
-        // A killed executable lint-contract test can leave a non-product source probe behind.
-        'packages/*/*/src/oxlint-contract-*.ts',
+        'packages/code-runtime/code-runtime-subprocess/src/runner.ts',
         // GUI step-1 skeleton (PR #500): client/web UI files whose remaining
         // branches need a browser-grade harness the jsdom lane doesn't cover
         // yet. TODO(gui): cover and remove as the client test lane matures.
@@ -156,7 +107,6 @@ export default defineConfig({
         'packages/client/ui-primitives/src/markdown/plain-text.ts',
         'packages/client/ui-question/src/client/QuestionComposer.tsx',
         'packages/client/ui-primitives/src/Menu.tsx',
-        'packages/client/ui-primitives/src/RiskConfirmation.tsx',
         'packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx',
         'packages/client/ui-workspace/src/client/WorkspacePicker.tsx',
         'packages/client/web-react/src/*',
@@ -181,10 +131,6 @@ export default defineConfig({
         'packages/client/hmr/src/invariant.ts',
         'packages/client/connection/src/index.ts',
         'packages/client/connection/src/http-bridge.ts',
-        // This assembly imports generated Host-for-Client code that exists
-        // only in lib; the post-build built-bin smoke executes both entries.
-        'packages/api/remotes/src/index.ts',
-        'packages/api/remotes/src/client/index.ts',
         // Slash/command/input round: per-file gaps deferred with the same
         // client-lane debt. TODO(gui): cover and remove with the lane above.
         'packages/client/connection/src/client/fixture.ts',
@@ -209,13 +155,9 @@ export default defineConfig({
         'packages/client/ui-sidebar/src/client/index.ts',
         'packages/client/ui-skill/src/client/index.ts',
         'packages/client/ui-workspace/src/client/index.ts',
-        'packages/client/test-runtime/src/translate.ts',
-        'packages/client/ui-primitives/src/JsonTree.tsx',
-        // Typert generator: correctness is pinned by its fixture suites and
-        // the byte-for-byte catalog reproduction test; per-file coverage
-        // would put whole-workspace compiler analysis under v8
-        // instrumentation — the coverage lane's longest tail.
-        'packages/typert/generator/src/*.ts',
+        'packages/typert/generator/src/analyzer.ts',
+        'packages/typert/generator/src/renderer.ts',
+        'packages/typert/generator/src/cordis-catalog.ts',
         'packages/host/apiproxy/src/index.ts',
         'packages/host/apiproxy/src/invariant.ts',
         'packages/host/apiproxy/src/api-proxy.ts',
@@ -225,9 +167,9 @@ export default defineConfig({
         'packages/ui/commands/src/index.ts',
         'packages/ui/commands/src/invariant.ts',
         'packages/session-projection/session-projection/src/index.ts',
+        'packages/ui/tui/src/index.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
         ...windowsCoverageExclusions,
-        ...pwshCoverageExclusions,
       ],
       // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome).
       // Per-file so a well-covered big file can't subsidize a bare one.
@@ -240,9 +182,7 @@ export default defineConfig({
         functions: 100,
         lines: 100,
       },
-      reporter: process.env.CI
-        ? ['text', uncoveredLocationsReporter]
-        : ['text', 'html', uncoveredLocationsReporter],
+      reporter: process.env.CI ? ['text'] : ['text', 'html'],
     },
   },
 })

From e8409cf928a3f848f8c2e6a8ab85c32ecbd52de6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 02:27:12 +0800
Subject: [PATCH 335/516] fix(code-runtime): track generated runner source

---
 knip.json                                     |  1 +
 .../src/runner-source.generated.ts            |  2 +-
 packages/util/atomic-write/src/runner.ts      | 24 +++++++++++--------
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/knip.json b/knip.json
index 20bcb5ff2d..413b740578 100644
--- a/knip.json
+++ b/knip.json
@@ -385,6 +385,7 @@
     },
     "packages/code-runtime/code-runtime-subprocess": {
       "entry": [
+        "src/runner.ts",
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
       ],
diff --git a/packages/util/atomic-write/src/runner-source.generated.ts b/packages/util/atomic-write/src/runner-source.generated.ts
index d40c77783c..8592fa2399 100644
--- a/packages/util/atomic-write/src/runner-source.generated.ts
+++ b/packages/util/atomic-write/src/runner-source.generated.ts
@@ -3,4 +3,4 @@
  * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.
  */
 
-export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{fork as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{fileURLToPath as i}from\"node:url\";import{Worker as a,isMainThread as o,parentPort as s,workerData as c}from\"node:worker_threads\";const l=Reflect.apply,u=Array.isArray,d=Buffer,f=Reflect.get(Buffer,`byteLength`),ee=Object.create,p=Object.defineProperty,te=Object.keys,ne=String,re=Reflect.get(String.prototype,`charCodeAt`),ie=Reflect.get(String.prototype,`codePointAt`),m=Reflect.get(String.prototype,`slice`);function h(e){let t=ee(null);return t.value=e,t}function ae(e,t,n){let r=h(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function g(e){return l(f,d,[e,`utf8`])}function _(e,t){ae(e,e.length,t)}function oe(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,h(t)),n}function se(e,t){return l(m,e,[t,t+(l(ie,e,[t])>65535?2:1)])}function ce(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=l(re,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:g(e)}function v(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=se(e,r);if(n+=ce(i),n>t)return;r+=i.length}return n}function y(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=oe(i);e!==void 0;e=oe(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=v(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(g(ne(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(u(a)){if(!r(2))return;a.length>0&&_(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=te(a);e.length>0&&_(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=v(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:s})}return n}function le(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=se(e,i),o=ce(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:l(m,e,[0,r])}const ue=Reflect.get(Function.prototype,`toString`),b=Reflect.get(Reflect,`apply`),x=Error,S=Set,C=Array.isArray,de=Array.prototype,w=Number.isFinite,fe=Number.isSafeInteger,pe=Object.create,me=Object.defineProperty,he=Object.getOwnPropertyDescriptor,T=Object.getPrototypeOf,ge=Object.hasOwn,E=Object.is,_e=Object.keys,D=Object.prototype,ve=Reflect.get(D,`propertyIsEnumerable`),O=Reflect.ownKeys,ye=Reflect.get(Set.prototype,`add`),be=Reflect.get(Set.prototype,`delete`),xe=Reflect.get(Set.prototype,`has`);function k(e){let t=pe(null);return t.value=e,t}function A(e,t,n){let r=k(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,me(e,t,r)}function j(e,t){A(e,e.length,t)}function M(e){if(e.length===0)return;let t=e.length-1,n=e[t];return me(e,`length`,k(t)),n}function N(e,t){return b(xe,e,[t])}function P(e,t){b(ye,e,[t])}function Se(e,t){b(be,e,[t])}function F(e,t){let n=he(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&b(ue,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function I(e){return T(e)===null&&F(e,`Object`)}function L(e){let t=T(e);if(t===de)return!0;if(!C(t)||!F(t,`Array`))return!1;let n=T(t);return typeof n==`object`&&!!n&&I(n)}function R(e){let t=T(e);return t===null||t===D||typeof t==`object`&&I(t)}function z(e){let t=O(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!b(ve,e,[r]))return}return t}function B(e){let t=new S,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?A(e.target,e.index,t):A(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=M(i);e!==void 0;e=M(i)){if(e.kind===`leave`){Se(t,e.source);continue}if(e.kind===`array-item`){if(!ge(e.source,e.index))return;j(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){j(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!w(n)||E(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||N(t,n))return;if(C(n)){if(!L(n))return;let a=n.length;if(O(n).length!==a+1)return;let o=[];r(e.destination,o),P(t,n),j(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)j(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!R(n))return;let a=z(n);if(a===void 0)return;let o={};r(e.destination,o),P(t,n),j(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;j(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function V(e){let t=[],n=[e];for(let e=M(n);e!==void 0;e=M(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){j(t,e);continue}if(C(e)){j(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new x(`cannot encode a sparse JSON array`);j(n,r)}continue}let r=_e(e);j(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new x(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new x(`cannot encode an undefined JSON object property`);j(n,a)}}return t}function H(e){if(!L(e)||O(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!ge(e,t))return!1;return!0}function U(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function Ce(e){if(C(e)||!R(e))return;let t=z(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!U(t,`kind`)||!U(t,`length`))return;let e=n.length;return typeof e==`number`&&fe(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!U(t,`kind`)||!U(t,`keys`))return;let e=n.keys;if(!C(e)||!H(e))return;let r=new S,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||N(r,t))return;P(r,t),j(i,t)}return{kind:`object`,keys:i}}}function W(e){try{if(!C(e)||!H(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)j(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;A(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!w(r)||E(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=Ce(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&j(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;M(n)}}return n.length===0?r:void 0}catch{return}}const G=Error,we=Object.create,Te=Object.defineProperty;function K(e,t,n){let r=we(null);r.enumerable=!0,r.value=n,Te(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=v(e,n);if(r===void 0){this.truncated=!0;let r=le(e,n);if(r.length>0){let e=v(r,n);if(e===void 0)throw new G(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=B(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):y(r,t)===void 0?Me(n):{value:V(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return v(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof G?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends G{constructor(t,n){super(n),K(this,`name`,e.name),K(this,e.memberNameProperty,t)}}}function q(e,t,n){return e?new e(t,n):new G(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=W(e.value);t===void 0?n.reject(new G(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new G(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=B(o)}catch{c=void 0}if(c===void 0)return Promise.reject(q(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:V(c)};return a!==void 0&&y(l,a)===void 0?Promise.reject(q(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(q(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(q(s,i,`binding arguments must be structured-cloneable: ${e instanceof G?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new G(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&y(f,r)===void 0?{type:`output-limit`}:f)}function J(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let Y=0;function X(e){return typeof e==`object`&&e?e:void 0}function Z(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function Ve(e){process.stdout.write(e),process.stdout.write(`\n`)}function He(e){let t=Z(e,Y);return t===void 0?!1:(Ve(t),!0)}function Ue(e){let t=X(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function We(e){return Ue(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ge(e){let t=X(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function Ke(e){let t=X(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=W(e);return t===void 0?null:V(t)}function qe(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Je(){let e=n({input:process.stdin,crlfDelay:1/0}),r,a=0,o=2,s=0,c=!1,l=t=>{if(c)return;let n=Z(t,Y)??Z($(),Y);c=!0,n!==void 0&&Ve(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(i.stdout),t=J(i.stderr),n=qe(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},u=e=>{if(c)return;let t=+(s>0),n=v(e,a-o-t);if(n===void 0){l({type:`output-limit`});return}o+=n+t,s+=1,He({type:`log`,text:e})||l($())},d=e=>{a=e.maxOutputBytes,Y=e.maxFrameBytes,r=t(i(import.meta.url),[],{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,execArgv:[],stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{u(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{u(e.toString(`utf8`))}),n.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){u(t.text);return}c||(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`?He({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||l($()):t.type===`output-limit`?l({type:`output-limit`}):t.type===`done`&&(t.error===void 0?l({type:`done`,...t.value===void 0?{}:{value:Q(t.value)}}):Ue(t.error)&&l({type:`done`,error:t.error})))}}),n.on(`error`,e=>{l({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{c||l({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Ge(t);if(e===void 0){l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}d(e);return}let n=Ke(t);n!==void 0&&r.send(n,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!c&&l({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Ye(){let e,t=!1,n,i=0,o=e=>process.send===void 0||i>0&&Z(e,i)===void 0?!1:(process.send(e),!0),s=r=>{if(t)return;t=!0,clearInterval(n);let a=i>0&&Z(r,i)===void 0?$():r,s=e;e=void 0,(s===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(s.stdout),t=J(s.stderr);await Promise.all([s.terminate(),e,t])})).catch(e=>{o({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(a,()=>{process.connected&&process.disconnect()})})};process.on(`message`,c=>{if(e===void 0){let l=Ge(c);if(l===void 0){s({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}i=l.maxFrameBytes,e=new a(new URL(import.meta.url),{workerData:l,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:l.maxOldGenerationSizeMb}});let u=e;u.stdout.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.stderr.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.on(`message`,e=>{let t=X(e);t!==void 0&&(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`?o({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||s($()):t.type===`log`&&typeof t.text==`string`?o({type:`log`,text:t.text})||s($()):t.type===`output-limit`?s({type:`output-limit`}):t.type===`done`&&(t.error===void 0?s({type:`done`,...t.value===void 0?{}:{value:Q(t.value)}}):We(t.error)&&s({type:`done`,error:t.error})))}),u.on(`error`,e=>{s({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),u.on(`exit`,e=>{t||s({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),n=setInterval(()=>{e!==void 0&&e.performance.eventLoopUtilization().active>l.computeMs&&s({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${l.computeMs}ms busy)`}})},25);return}let l=Ke(c);l!==void 0&&e.postMessage(l)}),process.on(`disconnect`,()=>{e!==void 0&&!t&&e.terminate()})}if(o)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Ye():Je();else{if(s===null)throw Error(`remote worker requires parentPort`);let e=c;ze(s,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
+export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{fork as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{fileURLToPath as i}from\"node:url\";import{Worker as a,isMainThread as o,parentPort as s,workerData as c}from\"node:worker_threads\";const l=Reflect.apply,u=Array.isArray,d=Buffer,f=Reflect.get(Buffer,`byteLength`),ee=Object.create,p=Object.defineProperty,te=Object.keys,ne=String,re=Reflect.get(String.prototype,`charCodeAt`),ie=Reflect.get(String.prototype,`codePointAt`),m=Reflect.get(String.prototype,`slice`);function h(e){let t=ee(null);return t.value=e,t}function ae(e,t,n){let r=h(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function g(e){return l(f,d,[e,`utf8`])}function _(e,t){ae(e,e.length,t)}function oe(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,h(t)),n}function se(e,t){return l(m,e,[t,t+(l(ie,e,[t])>65535?2:1)])}function ce(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=l(re,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:g(e)}function v(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=se(e,r);if(n+=ce(i),n>t)return;r+=i.length}return n}function y(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=oe(i);e!==void 0;e=oe(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=v(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(g(ne(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(u(a)){if(!r(2))return;a.length>0&&_(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=te(a);e.length>0&&_(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=v(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:s})}return n}function le(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=se(e,i),o=ce(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:l(m,e,[0,r])}const ue=Reflect.get(Function.prototype,`toString`),b=Reflect.get(Reflect,`apply`),x=Error,S=Set,C=Array.isArray,de=Array.prototype,w=Number.isFinite,fe=Number.isSafeInteger,pe=Object.create,T=Object.defineProperty,me=Object.getOwnPropertyDescriptor,E=Object.getPrototypeOf,D=Object.hasOwn,O=Object.is,he=Object.keys,k=Object.prototype,ge=Reflect.get(k,`propertyIsEnumerable`),A=Reflect.ownKeys,_e=Reflect.get(Set.prototype,`add`),ve=Reflect.get(Set.prototype,`delete`),ye=Reflect.get(Set.prototype,`has`);function j(e){let t=pe(null);return t.value=e,t}function M(e,t,n){let r=j(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,T(e,t,r)}function N(e,t){M(e,e.length,t)}function P(e){if(e.length===0)return;let t=e.length-1,n=e[t];return T(e,`length`,j(t)),n}function F(e,t){return b(ye,e,[t])}function I(e,t){b(_e,e,[t])}function be(e,t){b(ve,e,[t])}function L(e,t){let n=me(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&b(ue,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function R(e){return E(e)===null&&L(e,`Object`)}function z(e){let t=E(e);if(t===de)return!0;if(!C(t)||!L(t,`Array`))return!1;let n=E(t);return typeof n==`object`&&!!n&&R(n)}function B(e){let t=E(e);return t===null||t===k||typeof t==`object`&&R(t)}function V(e){let t=A(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!b(ge,e,[r]))return}return t}function H(e){let t=new S,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?M(e.target,e.index,t):M(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=P(i);e!==void 0;e=P(i)){if(e.kind===`leave`){be(t,e.source);continue}if(e.kind===`array-item`){if(!D(e.source,e.index))return;N(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){N(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!w(n)||O(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||F(t,n))return;if(C(n)){if(!z(n))return;let a=n.length;if(A(n).length!==a+1)return;let o=[];r(e.destination,o),I(t,n),N(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)N(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!B(n))return;let a=V(n);if(a===void 0)return;let o={};r(e.destination,o),I(t,n),N(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;N(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function U(e){let t=[],n=[e];for(let e=P(n);e!==void 0;e=P(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){N(t,e);continue}if(C(e)){N(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new x(`cannot encode a sparse JSON array`);N(n,r)}continue}let r=he(e);N(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new x(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new x(`cannot encode an undefined JSON object property`);N(n,a)}}return t}function xe(e){if(!z(e)||A(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!D(e,t))return!1;return!0}function W(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function Se(e){if(C(e)||!B(e))return;let t=V(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!W(t,`kind`)||!W(t,`length`))return;let e=n.length;return typeof e==`number`&&fe(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!W(t,`kind`)||!W(t,`keys`))return;let e=n.keys;if(!C(e)||!xe(e))return;let r=new S,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||F(r,t))return;I(r,t),N(i,t)}return{kind:`object`,keys:i}}}function G(e){try{if(!C(e)||!xe(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)N(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;M(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!w(r)||O(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=Se(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&N(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;P(n)}}return n.length===0?r:void 0}catch{return}}const K=Error,Ce=Object.create,we=Object.defineProperty;function Te(e,t,n){let r=Ce(null);r.enumerable=!0,r.value=n,we(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=v(e,n);if(r===void 0){this.truncated=!0;let r=le(e,n);if(r.length>0){let e=v(r,n);if(e===void 0)throw new K(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=H(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):y(r,t)===void 0?Me(n):{value:U(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return v(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof K?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends K{constructor(t,n){super(n),Te(this,`name`,e.name),Te(this,e.memberNameProperty,t)}}}function q(e,t,n){return e?new e(t,n):new K(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=G(e.value);t===void 0?n.reject(new K(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new K(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=H(o)}catch{c=void 0}if(c===void 0)return Promise.reject(q(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:U(c)};return a!==void 0&&y(l,a)===void 0?Promise.reject(q(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(q(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(q(s,i,`binding arguments must be structured-cloneable: ${e instanceof K?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new K(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&y(f,r)===void 0?{type:`output-limit`}:f)}function J(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let Y=0;function X(e){return typeof e==`object`&&e?e:void 0}function Z(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function Ve(e){process.stdout.write(e),process.stdout.write(`\n`)}function He(e){let t=Z(e,Y);return t===void 0?!1:(Ve(t),!0)}function Ue(e){let t=X(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function We(e){return Ue(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ge(e,t){return e.error===void 0?{type:`done`,...e.value===void 0?{}:{value:Q(e.value)}}:t(e.error)?{type:`done`,error:e.error}:void 0}function Ke(e){let t=X(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function qe(e){let t=X(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=G(e);return t===void 0?null:U(t)}function Je(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Ye(){let e=n({input:process.stdin,crlfDelay:1/0}),r,a=0,o=2,s=0,c=!1,l=t=>{if(c)return;let n=Z(t,Y)??Z($(),Y);c=!0,n!==void 0&&Ve(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(i.stdout),t=J(i.stderr),n=Je(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},u=e=>{if(c)return;let t=+(s>0),n=v(e,a-o-t);if(n===void 0){l({type:`output-limit`});return}o+=n+t,s+=1,He({type:`log`,text:e})||l($())},d=e=>{a=e.maxOutputBytes,Y=e.maxFrameBytes,r=t(i(import.meta.url),[],{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,execArgv:[],stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{u(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{u(e.toString(`utf8`))}),n.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){u(t.text);return}if(!c){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)He({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||l($());else if(t.type===`output-limit`)l({type:`output-limit`});else if(t.type===`done`){let e=Ge(t,Ue);e!==void 0&&l(e)}}}}),n.on(`error`,e=>{l({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{c||l({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Ke(t);if(e===void 0){l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}d(e);return}let n=qe(t);n!==void 0&&r.send(n,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!c&&l({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Xe(){let e,t=!1,n,i=0,o=e=>process.send===void 0||i>0&&Z(e,i)===void 0?!1:(process.send(e),!0),s=r=>{if(t)return;t=!0,clearInterval(n);let a=i>0&&Z(r,i)===void 0?$():r,s=e;e=void 0,(s===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(s.stdout),t=J(s.stderr);await Promise.all([s.terminate(),e,t])})).catch(e=>{o({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(a,()=>{process.connected&&process.disconnect()})})};process.on(`message`,c=>{if(e===void 0){let l=Ke(c);if(l===void 0){s({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}i=l.maxFrameBytes,e=new a(new URL(import.meta.url),{workerData:l,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:l.maxOldGenerationSizeMb}});let u=e;u.stdout.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.stderr.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)o({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||s($());else if(t.type===`log`&&typeof t.text==`string`)o({type:`log`,text:t.text})||s($());else if(t.type===`output-limit`)s({type:`output-limit`});else if(t.type===`done`){let e=Ge(t,We);e!==void 0&&s(e)}}}),u.on(`error`,e=>{s({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),u.on(`exit`,e=>{t||s({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),n=setInterval(()=>{e!==void 0&&e.performance.eventLoopUtilization().active>l.computeMs&&s({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${l.computeMs}ms busy)`}})},25);return}let l=qe(c);l!==void 0&&e.postMessage(l)}),process.on(`disconnect`,()=>{e!==void 0&&!t&&e.terminate()})}if(o)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Xe():Ye();else{if(s===null)throw Error(`remote worker requires parentPort`);let e=c;ze(s,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
diff --git a/packages/util/atomic-write/src/runner.ts b/packages/util/atomic-write/src/runner.ts
index 7a0b3eb678..92fad6db2e 100644
--- a/packages/util/atomic-write/src/runner.ts
+++ b/packages/util/atomic-write/src/runner.ts
@@ -94,6 +94,16 @@ function validWorkerFailure(value: unknown): value is RuntimeFailure {
     && (value.kind === 'exception' || value.kind === 'invalid-output' || value.kind === 'output-limit')
 }
 
+function doneMessage(
+  message: Record<string, unknown>,
+  acceptsFailure: (value: unknown) => value is RuntimeFailure,
+): RuntimeMessage | undefined {
+  if (message.error !== undefined) {
+    return acceptsFailure(message.error) ? { type: 'done', error: message.error } : undefined
+  }
+  return { type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } }
+}
+
 function runtimeBoot(value: unknown): RuntimeBootData | undefined {
   const record = recordOf(value)
   if (record === undefined
@@ -214,11 +224,8 @@ function runLauncher(): void {
       } else if (message.type === 'output-limit') {
         finish({ type: 'output-limit' })
       } else if (message.type === 'done') {
-        if (message.error !== undefined) {
-          if (validFailure(message.error)) finish({ type: 'done', error: message.error })
-        } else {
-          finish({ type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } })
-        }
+        const done = doneMessage(message, validFailure)
+        if (done !== undefined) finish(done)
       }
     })
     current.on('error', (error: Error) => {
@@ -348,11 +355,8 @@ function runController(): void {
         } else if (message.type === 'output-limit') {
           finish({ type: 'output-limit' })
         } else if (message.type === 'done') {
-          if (message.error !== undefined) {
-            if (validWorkerFailure(message.error)) finish({ type: 'done', error: message.error })
-          } else {
-            finish({ type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } })
-          }
+          const done = doneMessage(message, validWorkerFailure)
+          if (done !== undefined) finish(done)
         }
       })
       current.on('error', (error: Error) => {

From 22fc228b9757626fbc0c3c9ab920ec9472b258ea Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 04:23:20 +0800
Subject: [PATCH 336/516] refactor(runtime): collapse unused setup layers

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 ++--
 ...7-28-portable-execution-world-consumers.md |  4 ++--
 ...8-portable-execution-world-consumers.zh.md |  4 ++--
 .../feature/2026-06-15-code-mode.i18n.yaml    |  4 ++--
 .../feature/2026-06-15-code-mode.md           |  6 ++---
 .../feature/2026-06-15-code-mode.zh.md        |  6 ++---
 docs/config-catalog.md                        |  4 ++--
 .../core-data-structures/subprocess.i18n.yaml |  4 ++--
 docs/core-data-structures/subprocess.md       |  2 +-
 docs/core-data-structures/subprocess.zh.md    |  2 +-
 packages/README.i18n.yaml                     |  4 ++--
 packages/README.md                            |  2 +-
 packages/README.zh.md                         |  2 +-
 packages/bash/pwsh-local/tsconfig.json        | 10 ++++----
 packages/code-runtime/code-runtime/README.md  |  4 ++--
 packages/pty/pty-local/tests/index.spec.ts    |  1 -
 .../subprocess-local/README.i18n.yaml         |  4 ++--
 .../subprocess/subprocess-local/README.md     |  4 ++--
 .../subprocess/subprocess-local/README.zh.md  | 24 +++++++++----------
 .../subprocess/subprocess-local/src/index.ts  | 14 ++++-------
 .../subprocess-local/tests/local.spec.ts      | 19 ++-------------
 .../subprocess/subprocess/README.i18n.yaml    |  4 ++--
 packages/subprocess/subprocess/README.md      |  4 ++--
 packages/subprocess/subprocess/README.zh.md   |  4 ++--
 packages/subprocess/subprocess/src/index.ts   |  7 ++----
 .../subprocess/tests/service.spec.ts          |  1 -
 packages/ui/app-boot/tsdown.config.ts         |  8 +------
 packages/util/atomic-write/README.i18n.yaml   |  6 ++---
 .../src/runner-source.generated.ts            |  2 +-
 packages/util/atomic-write/src/runner.ts      | 17 +++++++++----
 30 files changed, 78 insertions(+), 103 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 683a095229..3fce989f78 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 03b274688e15661845c326afdd105b342dd6a513
-2026-07-28-portable-execution-world-consumers.zh.md: 1e3d8ae8e46d26f4bea47293104c52dbf33098d4
+2026-07-28-portable-execution-world-consumers.md: 74fa2687782a2cf59be8dddf98fa4a08a953d565
+2026-07-28-portable-execution-world-consumers.zh.md: 35d4f3640a44564894fecfaa22c7255d7452dec9
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 03b274688e..74fa268778 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -23,7 +23,7 @@ Generic consumers use that execution world:
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; an in-flight readiness poll cannot release that reservation, and a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Startup cancellation begins terminal rollback without waiting for a stalled readiness or signalling call. Close rejects new public signals and delegates provider-observable session quiescence to the handle's awaited termination operation.
-- `dsh-code-runtime-subprocess` materializes a dependency-free runner through `ctx.fs` and launches it through `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote worlds. The fixed runner is adapter-owned infrastructure below `ctx.subprocess.runtimeRoot`, so its write carries an explicit `danger-full-access` policy instead of inheriting the model-facing filesystem mode. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. Preparation carries one lifecycle signal through filesystem resolution, materialization, and executable lookup so disposal can abort a stalled provider. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
+- `dsh-code-runtime-subprocess` passes a bundled dependency-free eval runner directly to `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote process worlds without a filesystem dependency or provider-specific package. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
 
 `dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
@@ -39,7 +39,7 @@ Generic consumers use that execution world:
 
 **Add a stable bounded-read primitive to the filesystem seam.** Rejected because only LSP needs a complete-document byte ceiling, which it can enforce while consuming the existing text stream. A second primitive forces every provider to implement stable-handle and no-follow mechanics, including a remote helper protocol, without an observed concurrent-replacement defect.
 
-**Delete the worker-thread Code Runtime.** Rejected because portability does not erase its current deployment need. The subprocess backend requires a Node executable and filesystem materialization; the worker backend has neither requirement and remains the supported single-process path.
+**Delete the worker-thread Code Runtime.** Rejected because portability does not erase its current deployment need. The subprocess backend requires a Node executable; the worker backend does not and remains the supported single-process path.
 
 **Run the whole harness inside the remote environment.** Rejected as a different deployment model. Making execution capabilities portable does not move model calls, session state, plugin state, or the agent loop.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 1e3d8ae8e4..35d4f3640a 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -23,7 +23,7 @@ Status: implemented
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
 - `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
+- `dsh-code-runtime-subprocess` 将一个内置的无依赖 eval runner 直接传给 `ctx.subprocess`，从而在本地或远程进程执行环境中保留代码运行时的绑定与输出契约，且不依赖文件系统或提供方专用包。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
 
 `dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
 
@@ -39,7 +39,7 @@ Status: implemented
 
 **在文件系统 seam 中新增稳定的有界读取原语。** 不予采纳，因为只有 LSP 需要完整文档字节上限，而它可以在消费现有文本流时执行该上限。第二项原语会迫使每个提供方实现稳定句柄和不跟随符号链接的机制，远程提供方甚至需要辅助协议，却没有已观察到的并发替换缺陷。
 
-**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件和文件系统物化，而 worker 后端两者都不需要，并且仍是受支持的单进程路径。
+**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件，而 worker 后端不需要，并且仍是受支持的单进程路径。
 
 **在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop（智能体循环）。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 112e4eed83..d2655b6d02 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 1be25f5b145e50d8fe391d22910b71d85181582e
-2026-06-15-code-mode.zh.md: a4e8fbbd339899937c4f39091b4befbbb78ec347
+2026-06-15-code-mode.md: a075ea66c150afb1b48f98c600b72eec57869962
+2026-06-15-code-mode.zh.md: c269c0a8709087e7b1e27051cbda3924f8dd9109
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index 1be25f5b14..a075ea66c1 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -20,7 +20,7 @@ Three decisions, each elaborated in its own section below:
 
 1. **Code Mode is a first-class presentation mode of `ToolRegistry`** (`dsh-tools`), selected by a validated `mode` config: `'native'` (the default, contributing the visible capability schemas), `'code'` (the registry contributes only its reserved `run_code` transport plus a generated SDK `.d.ts` in the system prompt), or `'both'` (native schemas and the transport + SDK). The registry shapes its canonical contribution at the source; the cooperative prompt-assembly result remains authoritative, and the logged request header records exactly that returned presentation.
 2. **Code execution is a capability seam** — `packages/code-runtime/` contains the interface package `@deepseek-ai/dsh-code-runtime`, which owns `ctx.codeRuntime` ([capability seams](../architecture/2026-06-13-capability-seams.md); consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is another implementation package, not a redesign.
-3. **Two implementations preserve one fresh-worker contract**: `@deepseek-ai/dsh-code-runtime-worker` runs the worker in the harness process, while `@deepseek-ai/dsh-code-runtime-subprocess` materializes a runner through `ctx.fs` and launches it through `ctx.subprocess` for another execution world. Both execute host-stripped TypeScript in a fresh Node worker with an empty environment, bridged bindings, configurable heap/output/time caps, and hard termination. Their trust posture is bash-equivalent by design; stronger isolation comes from the mounted execution world.
+3. **Two implementations preserve one fresh-worker contract**: `@deepseek-ai/dsh-code-runtime-worker` runs the worker in the harness process, while `@deepseek-ai/dsh-code-runtime-subprocess` passes a bundled eval runner to `ctx.subprocess` for another execution world. Both execute host-stripped TypeScript in a fresh Node worker with an empty environment, bridged bindings, configurable heap/output/time caps, and hard termination. Their trust posture is bash-equivalent by design; stronger isolation comes from the mounted execution world.
 
 This note owns Code Mode's presentation, composition, isolation, and settlement foundation. The later [typed tool-return Agent Note](2026-07-20-code-mode-typed-tool-returns.md) owns the generated output map, canonical binding values, `ToolCallError`, and the lossless outer-output boundary.
 
@@ -79,7 +79,7 @@ Requests contain every runtime input; implementations own validated timeout and
 5. **Enforce independent budgets.** `computeMs` meters worker busy time, allowing slow awaited tools without excusing a hot loop. `maxWallMs` bounds total elapsed time, including unresolved waits. `maxOutputBytes` bounds only the combined serialized outer logs, completion, or diagnostic; intermediate binding values have no byte cap. Expiry, cancellation, and completion terminate the worker, and heap exits or outer overflow are explicit failures.
 6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../../docs/defensive-patterns.md).
 
-`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across a filesystem/subprocess execution world. It writes a dependency-free runner below `ctx.subprocess.runtimeRoot`, resolves Node through the provider, and carries binding traffic over bounded newline-delimited UTF-8 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
+`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across another process world. It passes a dependency-free eval runner directly through the subprocess provider and carries binding traffic over bounded newline-delimited UTF-8 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
 
 ### Trust posture
 
@@ -95,7 +95,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Testing
 
-- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger and per-hop frame boundaries, compute and wall budgets, hostile binding traffic, empty environment, descendant lifetime cleanup, and disposal to quiescence. Built-package tests run both the direct worker entry and the filesystem/subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
+- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger and per-hop frame boundaries, compute and wall budgets, hostile binding traffic, empty environment, descendant lifetime cleanup, and disposal to quiescence. Built-package tests run both the direct worker entry and the subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
 - **Registry integration:** Tests cover code generation, all presentation modes, reserved-name and restriction rules, scoped visibility, authoritative assembly rewrites, `toolOrder`, runtime compatibility failures, full-pipeline sub-dispatch, parent-token correlation, serialization, cancellation and queue drain, JSON normalization, error propagation, log events, ordered context deferral across successful and failed programs, outer-block suppression, and HMR cleanup.
 - **With-key e2e:** A real model composes two bash calls in one program; another discovers nested workspace instructions through a Code Mode fs dispatch. The tests verify collapsed request headers, correlated dispatch events, resulting files, deferred context, and model behavior.
 - **Snapshot:** The `code-mode-turn`, `both-mode-turn`, and `code-mode-workspace-context` fixtures pin SDK text, header tool lists, dispatch events, deferred context, and result cards.
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index a4e8fbbd33..c269c0a870 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -20,7 +20,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
 2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
-3. **两种实现保持同一份全新 worker 契约**：`@deepseek-ai/dsh-code-runtime-worker` 在 harness 进程内运行 worker，`@deepseek-ai/dsh-code-runtime-subprocess` 则通过 `ctx.fs` 物化 runner，再通过 `ctx.subprocess` 在另一执行环境中启动。二者都在具有空环境的全新 Node worker 内执行由宿主剥离类型的 TypeScript，并提供桥接绑定、可配置的堆／输出／时间上限和硬终止。其信任姿态在设计上等同于 bash；更强的隔离来自挂载的执行环境。
+3. **两种实现保持同一份全新 worker 契约**：`@deepseek-ai/dsh-code-runtime-worker` 在 harness 进程内运行 worker，`@deepseek-ai/dsh-code-runtime-subprocess` 则将一个内置的 eval runner 传给 `ctx.subprocess`，用于另一执行环境。二者都在具有空环境的全新 Node worker 内执行由宿主剥离类型的 TypeScript，并提供桥接绑定、可配置的堆／输出／时间上限和硬终止。其信任姿态在设计上等同于 bash；更强的隔离来自挂载的执行环境。
 
 本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
 
@@ -79,7 +79,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
 6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
 
-`@deepseek-ai/dsh-code-runtime-subprocess` 在文件系统／子进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它在 `ctx.subprocess.runtimeRoot` 下写入一个无依赖 runner，通过提供方解析 Node，并在原始管道上使用有界的、以换行符分隔的 UTF-8 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
+`@deepseek-ai/dsh-code-runtime-subprocess` 在另一进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它通过子进程提供方直接传递一个无依赖的 eval runner，并在原始管道上使用有界的、以换行符分隔的 UTF-8 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
 
 ### 信任姿态
 
@@ -95,7 +95,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 ## 测试
 
-- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界与逐跳帧边界、compute 和 wall 预算、恶意绑定流量、空环境、后代进程生命周期清理以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与文件系统／子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
+- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界与逐跳帧边界、compute 和 wall 预算、恶意绑定流量、空环境、后代进程生命周期清理以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
 - **注册表集成：** 测试覆盖代码生成、所有呈现模式、保留名称和限制规则、scoped 可见性、权威组装重写、`toolOrder`、运行时兼容性失败、完整流水线子分发、parent-token 关联、序列化、取消和队列排空、JSON 规范化、错误传播、日志事件、成功与失败程序中的有序上下文延后、外层阻止抑制以及 HMR（热模块替换）清理。
 - **带密钥 e2e：** 真实模型在一个程序中组合两次 bash 调用；另一个模型通过 Code Mode fs 分发发现嵌套的工作区指令。测试验证折叠的请求头、关联的分发事件、结果文件、延后上下文和模型行为。
 - **快照：** `code-mode-turn`、`both-mode-turn` 和 `code-mode-workspace-context` fixture（测试前置数据）固定 SDK 文本、请求头工具列表、分发事件、延后上下文和结果卡片。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 0514cdd969..a875c190fe 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -286,7 +286,7 @@ Source: [`packages/client/hmr/src/index.ts:29`](../packages/client/hmr/src/index
 
 ## `@deepseek-ai/dsh-code-runtime-subprocess`
 
-Requires: `fs` · `subprocess`
+Requires: `subprocess`
 
 ```ts config-catalog
 /** Runtime configuration; every execution and bridge bound is deployment-tunable. */
@@ -306,7 +306,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/code-runtime/code-runtime-subprocess/src/index.ts:28`](../packages/code-runtime/code-runtime-subprocess/src/index.ts)
+Source: [`packages/code-runtime/code-runtime-subprocess/src/index.ts:27`](../packages/code-runtime/code-runtime-subprocess/src/index.ts)
 
 ## `@deepseek-ai/dsh-code-runtime-worker`
 
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index f3b308b0be..f6c61bd691 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: 95e9454a75112cf98e1ed583f970c50fe90aac37
-subprocess.zh.md: 58127d662fa599d19f632449d42b8aa3259886d6
+subprocess.md: f0fe691219df3afba2b836da8f1594fd5fe5a87b
+subprocess.zh.md: f59e787820ba2727fdc0c4b62c4aec7b8d2d6b7a
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index 935a7d60ac..89f30095bc 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -8,7 +8,7 @@ Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subproces
 
 ## Execution-world coordinates
 
-One provider's `cwd`, `runtimeRoot`, executable paths, ordinary processes, and terminal sessions inhabit the same path and process namespace as the mounted filesystem provider. `resolveExecutable(command, env?, signal?)` verifies absolute executable paths or resolves bare names through the provider's scrubbed `PATH` plus deliberate overrides. Consumers use `runtimeRoot` for private materialized helpers and never assume a host path exists in that world.
+One provider's `cwd`, executable paths, ordinary processes, and terminal sessions inhabit the same path and process namespace as the mounted filesystem provider. `resolveExecutable(command, env?, signal?)` verifies absolute executable paths or resolves bare names through the provider's scrubbed `PATH` plus deliberate overrides.
 
 ## Managed environment namespace and captured output
 
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 58127d662f..f59e787820 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -8,7 +8,7 @@
 
 ## 执行世界坐标
 
-一个提供方的 `cwd`、`runtimeRoot`、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。消费方使用 `runtimeRoot` 存放私有物化辅助程序，绝不假设该执行世界中存在某条宿主路径。
+一个提供方的 `cwd`、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。
 
 ## 受管环境命名空间与捕获的输出
 
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index c5be7e67d6..eaa48fac05 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 7fcd98bd19ca3291f0472af57841f2f763bb346f
-README.zh.md: 7c4aed9b343ec57001883e094ea3dd0d73e2a920
+README.md: b498c146202f1a69d89805fa3e8966c4d0735d6c
+README.zh.md: 2eefc73ed0ea22aae5fde93284c25c5d03fe86c4
diff --git a/packages/README.md b/packages/README.md
index a711e4d303..7d591605ef 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -19,7 +19,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: runtime seam plus local worker and filesystem/subprocess backends | Product — stable surface |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: runtime seam plus local worker and subprocess backends | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
 | [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 41380317f8..a9201d08a9 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -19,7 +19,7 @@
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：运行时 seam、本地 worker 后端及文件系统／进程管理后端 | 产品：稳定表面 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：运行时 seam、本地 worker 后端及进程管理后端 | 产品：稳定表面 |
 | [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
 | [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
 | [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |
diff --git a/packages/bash/pwsh-local/tsconfig.json b/packages/bash/pwsh-local/tsconfig.json
index 53ccc94926..7381575674 100644
--- a/packages/bash/pwsh-local/tsconfig.json
+++ b/packages/bash/pwsh-local/tsconfig.json
@@ -18,19 +18,19 @@
       "path": "../../../vendor/schemastery"
     },
     {
-      "path": "../../util/brand"
+      "path": "../code-runtime"
     },
     {
-      "path": "../../util/timeout"
-    },
-    {
-      "path": "../../bash/bash"
+      "path": "../code-runtime-worker"
     },
     {
       "path": "../../subprocess/subprocess"
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../util/timeout"
     }
   ]
 }
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index 7014bf517a..d58508cd08 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -34,5 +34,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
 - **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)).
-- **No runtime claims a hard security boundary** — both shipped implementations use fresh worker threads; the filesystem/subprocess backend can place them inside a stronger execution world, but no runtime reports `'container'` today.
-- **Intermediate binding values are implementation-bounded** — the direct worker backend has no per-binding byte cap; the filesystem/subprocess backend bounds each bridge frame, but repeated or concurrent binding traffic remains subject to process memory.
+- **No runtime claims a hard security boundary** — both shipped implementations use fresh worker threads; the subprocess backend can place them inside a stronger execution world, but no runtime reports `'container'` today.
+- **Intermediate binding values are implementation-bounded** — the direct worker backend has no per-binding byte cap; the subprocess backend bounds each bridge frame, but repeated or concurrent binding traffic remains subject to process memory.
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index f59cd3ab5a..15e73ddc1c 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -67,7 +67,6 @@ function terminalHandle(): SubprocessTerminalHandle {
 
 class StubSubprocessService extends SubprocessService {
   readonly cwd = '/tmp'
-  readonly runtimeRoot = '/tmp/dsh-runtime'
   async resolveExecutable(command: string): Promise<string> { return command }
   spawn(_spec: SubprocessSpawnSpec): SubprocessHandle { throw new Error('unused') }
   async spawnTerminal(_spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index d34e7475f9..8b668b43f6 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: 31c5539750c4af2b1c4169ac1dce4c91da587af7
-README.zh.md: 74aed52084c0db3ed9bfe4fcb991f781976fb7b5
+README.md: 4892ad49e571662b833b1dd6d64dc966f343ae3c
+README.zh.md: ca0df5ff18e9feb992cc3f6d0db90dc06cb275d8
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 31c5539750..13b51ec6d1 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` owns a private runtime directory, resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), [`dsh-pty-local`](../../pty/pty-local/README.md), and [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)).
+Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), [`dsh-pty-local`](../../pty/pty-local/README.md), and [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)).
 
 ## Behavior (and where it came from)
 
@@ -10,7 +10,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
-- **Execution-world coordinates** — `cwd` is the host process cwd, `runtimeRoot` is an owner-private temporary directory removed on disposal before any process-cleanup failure is reported, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
+- **Execution-world coordinates** — `cwd` is the host process cwd, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 74aed52084..ca0df5ff18 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -2,17 +2,17 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 拥有私有运行时目录，解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 与平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-pty-local`](../../pty/pty-local/README.md)和 [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)）。
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-pty-local`](../../pty/pty-local/README.md) 和 [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)）。
 
 ## 行为（以及设计来源）
 
-- **带平台正确信号发送的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树（可为测试注入）。`terminate()`（句柄唯一的终止动词）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；管道与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；脱离该组重新挂载的 daemon 仍可能存活，这与调研工具的局限相同。
-- **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留尾部，即诊断尾部的形状。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需延迟创建的 `0700` 每进程目录之下。
-- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
-- **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **执行世界坐标**：`cwd` 是宿主进程 cwd，`runtimeRoot` 是所有者私有的临时目录，会在资源释放时删除，并且删除发生在报告任何进程清理失败之前；`resolveExecutable` 检查绝对文件，或使用平台感知的可执行扩展名在清理后的有效 PATH 中查找。
-- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，并公开一项须等待的终止操作，该操作会在终止顶层 shell 前后清理后代。每次前台检查都会保留有根进程树中的精确身份；Linux 还会在会话 leader 退出后枚举该 POSIX 会话。因此，先前观察到的 macOS 后代以及任何同会话 Linux 成员在重新设定父进程后仍受身份围栏保护，而 pid／启动身份可防止清理因 PID 复用而跟随到其他进程。上层 PTY 后端负责提示符就绪检测、缓冲和面向模型的操作。
-- **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
+- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树（可为测试注入）。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活，这与所调研工具的局限相同。
+- **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
+- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+- **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
+- **执行世界坐标**：`cwd` 是宿主进程 cwd，`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索。
+- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
+- **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
 
@@ -20,14 +20,14 @@
 
 #### KV Cache 影响
 
-不会直接失效；请求前缀变更由具名消费方负责。
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
 
 ## 已知限制与暂缓事项
 
 - **Windows 进程树支持仅为尽力而为，且未经 CI 测试**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界；测试套件只通过注入的运行器覆盖这条路由，且 `packages/subprocess/*` 被排除在 Windows 测试矩阵之外。
-- **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 使用 `ps` 快照。
-- **守护化的终端后代仍可能逃出可观察边界**：在 macOS 上，子进程若在任何前台检查快照产生前重新设定父进程，便无法再从 `node-pty` 根发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与该提供方拥有的终端会话。本地提供方不会增加持续运行的进程表监视器。
-- **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSWORD*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
+- **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 则使用 `ps` 快照。
+- **守护化的终端后代仍可能逃出可观察边界**：在 macOS 上，子进程如果在任何前台检查快照之前重新设定父进程，将无法再从 `node-pty` 根进程发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与自有终端会话。本地提供方不会新增持续进程表监视器。
+- **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
 - **不会删除已完成的 spill 文件**：有界的完整输出恢复文件（以及每个进程的私有 spill 目录）会在 OS tmpdir 下累积，直到外部机制进行清理；超大的不完整 spill 会被丢弃并立即尝试删除，但清理失败可能留下一个有界文件。
 
 原始进程处理位于 `src/spawn.ts`；`src/index.ts` 负责服务接线。
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 46d179a7b2..262a2567b8 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -8,10 +8,8 @@
  */
 
 import { constants } from 'node:fs'
-import { mkdtempSync } from 'node:fs'
-import { access, rm, stat } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { delimiter, extname, isAbsolute, join, resolve } from 'node:path'
+import { access, stat } from 'node:fs/promises'
+import { delimiter, extname, isAbsolute, resolve } from 'node:path'
 import { Context } from 'cordis'
 import * as nodePty from 'node-pty'
 import type { IPtyForkOptions } from 'node-pty'
@@ -36,7 +34,6 @@ import { LocalTerminalHandle } from './terminal.ts'
  */
 export class LocalSubprocessService extends SubprocessService {
   readonly cwd = process.cwd()
-  readonly runtimeRoot = mkdtempSync(join(tmpdir(), 'dsh-subprocess-runtime-'))
   /** Live handles retained only so disposal can terminate and join them. */
   private live = new Set<SubprocessHandle>()
   /** Live terminal sessions retained through whole-session quiescence. */
@@ -63,10 +60,7 @@ export class LocalSubprocessService extends SubprocessService {
       }
       this.live.clear()
       this.terminals.clear()
-      const outcomes = [
-        ...await Promise.allSettled(pending),
-        ...await Promise.allSettled([rm(this.runtimeRoot, { recursive: true, force: true })]),
-      ]
+      const outcomes = await Promise.allSettled(pending)
       const failures = outcomes.flatMap<unknown>(outcome => outcome.status === 'rejected'
         ? [outcome.reason as unknown]
         : [])
@@ -126,7 +120,7 @@ export class LocalSubprocessService extends SubprocessService {
   }
 
   // Local PTY allocation is synchronous, but the provider seam permits remote asynchronous allocation.
-  // eslint-disable-next-line @typescript-eslint/require-await
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
   async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
     const file = spec.argv[0]
     if (file === undefined || file.length === 0) {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index ff83141fab..e74927448d 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -1,6 +1,5 @@
 import { PassThrough } from 'node:stream'
 import { describe, expect, it, vi } from 'vitest'
-import { stat } from 'node:fs/promises'
 import { basename, dirname, relative, resolve } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
@@ -22,16 +21,6 @@ function spec(command: string, overrides: Partial<SubprocessSpawnSpec> = {}): Su
 }
 
 describe('LocalSubprocessService', () => {
-  it('publishes execution-world paths and removes its private runtime directory', async () => {
-    const ctx = new Context()
-    const fiber = await ctx.plugin(LocalSubprocessService)
-    const root = ctx.subprocess.runtimeRoot
-    expect(ctx.subprocess.cwd).toBe(process.cwd())
-    expect((await stat(root)).isDirectory()).toBe(true)
-    await fiber.dispose()
-    await expect(stat(root)).rejects.toMatchObject({ code: 'ENOENT' })
-  })
-
   it('resolves absolute and PATH executables and honors lookup cancellation', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
@@ -113,11 +102,10 @@ describe('LocalSubprocessService', () => {
     expect(terminals.size).toBe(0)
   })
 
-  it('waits for every terminal cleanup and clears single-shot teardown ownership', async () => {
+  it('waits for every terminal cleanup and aggregates teardown failures', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
-    const runtimeRoot = service.runtimeRoot
     const firstFailure = new Error('first cleanup failure')
     const secondFailure = new Error('second cleanup failure')
     const disposalErrors: unknown[] = []
@@ -155,7 +143,6 @@ describe('LocalSubprocessService', () => {
     finishCleanup()
     await disposing
     expect(terminals.size).toBe(0)
-    await expect(stat(runtimeRoot)).rejects.toMatchObject({ code: 'ENOENT' })
     expect(disposalErrors).toHaveLength(1)
     expect(disposalErrors[0]).toMatchObject({
       errors: [firstFailure, secondFailure],
@@ -163,14 +150,13 @@ describe('LocalSubprocessService', () => {
     })
   })
 
-  it('reports one cleanup failure without wrapping it after removing runtime state', async () => {
+  it('reports one cleanup failure without wrapping it', async () => {
     const ctx = new Context()
     const failure = new Error('single cleanup failure')
     const disposalErrors: unknown[] = []
     ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
     const fiber = await ctx.plugin(LocalSubprocessService)
     const service = ctx.subprocess
-    const runtimeRoot = service.runtimeRoot
     const terminal: SubprocessTerminalHandle = {
       pid: 1,
       output: new PassThrough(),
@@ -185,7 +171,6 @@ describe('LocalSubprocessService', () => {
 
     await fiber.dispose()
 
-    await expect(stat(runtimeRoot)).rejects.toMatchObject({ code: 'ENOENT' })
     expect(disposalErrors).toEqual([failure])
   })
 
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 92887cc247..d12516f11f 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: 12a88a86c3cd7bcde2858bdbd874c99533100e09
-README.zh.md: f4c265a0f55c4e35e4557516593dd0da236164c5
+README.md: 08fb03d6f145c1026180d92de2421b647cb3ebbe
+README.zh.md: 592fc83223092b3406e9070e11de2b20a63232a6
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index 12a88a86c3..08fb03d6f1 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -2,12 +2,12 @@
 
 English | [中文](README.zh.md)
 
-The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessService` exposes its canonical `cwd`, private `runtimeRoot`, executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
+The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessService` exposes its canonical `cwd`, executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
 
 ## Contract
 
 - `spawn(spec)` returns immediately with a live handle; `done` resolves at process close with exit facts (`SubprocessOutcome` carries no output and no cause classification) and rejects only for spawn-level failures.
-- `cwd` and `runtimeRoot` are absolute paths in the provider's execution world. Consumers materialize private helpers below `runtimeRoot`, never in a host-only temp directory. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
+- `cwd` and executable paths belong to the provider's execution world. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
 - The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index f4c265a0f5..592fc83223 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -2,12 +2,12 @@
 
 [English](README.md) | 中文
 
-子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开其规范化 `cwd`、私有 `runtimeRoot`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
+子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开其规范化 `cwd`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
 
 ## 契约
 
 - `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
-- `cwd` 和 `runtimeRoot` 是提供方执行世界中的绝对路径。消费方在 `runtimeRoot` 之下物化私有辅助程序，绝不使用仅宿主可见的临时目录。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
+- `cwd` 和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
 - spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index e1749203dd..df3186c9b0 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -78,8 +78,8 @@ declare module 'cordis' {
  * duplicate-service behavior).
  *
  * Implementations must honor these semantics:
- * - {@link cwd}, {@link runtimeRoot}, and executable paths belong to one
- *   execution world shared with the mounted filesystem provider.
+ * - {@link cwd} and executable paths belong to one execution world shared
+ *   with the mounted filesystem provider.
  * - {@link spawn} returns immediately with a live handle; `done` resolves at
  *   process close with exit facts and rejects only for spawn-level failures.
  * - Collect-mode readers are offset-based and non-consuming, so independent
@@ -107,9 +107,6 @@ export abstract class SubprocessService extends Service {
   /** Canonical default cwd in this provider's execution world. */
   abstract readonly cwd: string
 
-  /** Private directory for runtime artifacts in this provider's execution world. */
-  abstract readonly runtimeRoot: string
-
   /**
    * Resolve one configured executable in this provider's execution world.
    * Absolute paths are verified; bare names use the provider's scrubbed PATH
diff --git a/packages/subprocess/subprocess/tests/service.spec.ts b/packages/subprocess/subprocess/tests/service.spec.ts
index 9f321caf54..2084310da9 100644
--- a/packages/subprocess/subprocess/tests/service.spec.ts
+++ b/packages/subprocess/subprocess/tests/service.spec.ts
@@ -17,7 +17,6 @@ import type {
  */
 class StubSubprocessService extends SubprocessService {
   readonly cwd = '/stub'
-  readonly runtimeRoot = '/stub/.runtime'
 
   async resolveExecutable(command: string): Promise<string> {
     return `/bin/${command}`
diff --git a/packages/ui/app-boot/tsdown.config.ts b/packages/ui/app-boot/tsdown.config.ts
index 88492d7c26..33db6be1b8 100644
--- a/packages/ui/app-boot/tsdown.config.ts
+++ b/packages/ui/app-boot/tsdown.config.ts
@@ -1,9 +1,6 @@
 import { defineConfig } from 'tsdown'
 
-/**
- * Embed Include while keeping Loader external so the built include tree and
- * app host bind to one Loader peer.
- */
+/** Bundle the host plugin and its dependency-free eval runner. */
 export default defineConfig({
   entry: ['lib/types/index.js', 'lib/types/invariant.js'],
   outDir: 'lib',
@@ -13,7 +10,4 @@ export default defineConfig({
   fixedExtension: false,
   dts: false,
   clean: false,
-  deps: {
-    alwaysBundle: ['@cordisjs/plugin-include'],
-  },
 })
diff --git a/packages/util/atomic-write/README.i18n.yaml b/packages/util/atomic-write/README.i18n.yaml
index 33e1f6014b..efcd06f845 100644
--- a/packages/util/atomic-write/README.i18n.yaml
+++ b/packages/util/atomic-write/README.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 packages/util/atomic-write/README.md
-README.md: 2ff4abb6ac10d8b592ccd2056b4f1f92cc8518b0
-README.zh.md: 4284d06422564268bb9e31d1a1ed06ab5271e562
+#   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-subprocess/README.md
+README.md: 897112a32fa3e776df756d4caaba97b617c6af9e
+README.zh.md: d9ab3713640fe955d2b36a8f0674f77686e4791b
diff --git a/packages/util/atomic-write/src/runner-source.generated.ts b/packages/util/atomic-write/src/runner-source.generated.ts
index 8592fa2399..95da563dbb 100644
--- a/packages/util/atomic-write/src/runner-source.generated.ts
+++ b/packages/util/atomic-write/src/runner-source.generated.ts
@@ -3,4 +3,4 @@
  * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.
  */
 
-export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{fork as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{fileURLToPath as i}from\"node:url\";import{Worker as a,isMainThread as o,parentPort as s,workerData as c}from\"node:worker_threads\";const l=Reflect.apply,u=Array.isArray,d=Buffer,f=Reflect.get(Buffer,`byteLength`),ee=Object.create,p=Object.defineProperty,te=Object.keys,ne=String,re=Reflect.get(String.prototype,`charCodeAt`),ie=Reflect.get(String.prototype,`codePointAt`),m=Reflect.get(String.prototype,`slice`);function h(e){let t=ee(null);return t.value=e,t}function ae(e,t,n){let r=h(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function g(e){return l(f,d,[e,`utf8`])}function _(e,t){ae(e,e.length,t)}function oe(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,h(t)),n}function se(e,t){return l(m,e,[t,t+(l(ie,e,[t])>65535?2:1)])}function ce(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=l(re,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:g(e)}function v(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=se(e,r);if(n+=ce(i),n>t)return;r+=i.length}return n}function y(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=oe(i);e!==void 0;e=oe(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=v(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(g(ne(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(u(a)){if(!r(2))return;a.length>0&&_(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=te(a);e.length>0&&_(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=v(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&_(i,{...e,index:e.index+1}),_(i,{kind:`value`,value:s})}return n}function le(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=se(e,i),o=ce(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:l(m,e,[0,r])}const ue=Reflect.get(Function.prototype,`toString`),b=Reflect.get(Reflect,`apply`),x=Error,S=Set,C=Array.isArray,de=Array.prototype,w=Number.isFinite,fe=Number.isSafeInteger,pe=Object.create,T=Object.defineProperty,me=Object.getOwnPropertyDescriptor,E=Object.getPrototypeOf,D=Object.hasOwn,O=Object.is,he=Object.keys,k=Object.prototype,ge=Reflect.get(k,`propertyIsEnumerable`),A=Reflect.ownKeys,_e=Reflect.get(Set.prototype,`add`),ve=Reflect.get(Set.prototype,`delete`),ye=Reflect.get(Set.prototype,`has`);function j(e){let t=pe(null);return t.value=e,t}function M(e,t,n){let r=j(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,T(e,t,r)}function N(e,t){M(e,e.length,t)}function P(e){if(e.length===0)return;let t=e.length-1,n=e[t];return T(e,`length`,j(t)),n}function F(e,t){return b(ye,e,[t])}function I(e,t){b(_e,e,[t])}function be(e,t){b(ve,e,[t])}function L(e,t){let n=me(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&b(ue,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function R(e){return E(e)===null&&L(e,`Object`)}function z(e){let t=E(e);if(t===de)return!0;if(!C(t)||!L(t,`Array`))return!1;let n=E(t);return typeof n==`object`&&!!n&&R(n)}function B(e){let t=E(e);return t===null||t===k||typeof t==`object`&&R(t)}function V(e){let t=A(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!b(ge,e,[r]))return}return t}function H(e){let t=new S,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?M(e.target,e.index,t):M(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=P(i);e!==void 0;e=P(i)){if(e.kind===`leave`){be(t,e.source);continue}if(e.kind===`array-item`){if(!D(e.source,e.index))return;N(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){N(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!w(n)||O(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||F(t,n))return;if(C(n)){if(!z(n))return;let a=n.length;if(A(n).length!==a+1)return;let o=[];r(e.destination,o),I(t,n),N(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)N(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!B(n))return;let a=V(n);if(a===void 0)return;let o={};r(e.destination,o),I(t,n),N(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;N(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function U(e){let t=[],n=[e];for(let e=P(n);e!==void 0;e=P(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){N(t,e);continue}if(C(e)){N(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new x(`cannot encode a sparse JSON array`);N(n,r)}continue}let r=he(e);N(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new x(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new x(`cannot encode an undefined JSON object property`);N(n,a)}}return t}function xe(e){if(!z(e)||A(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!D(e,t))return!1;return!0}function W(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function Se(e){if(C(e)||!B(e))return;let t=V(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!W(t,`kind`)||!W(t,`length`))return;let e=n.length;return typeof e==`number`&&fe(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!W(t,`kind`)||!W(t,`keys`))return;let e=n.keys;if(!C(e)||!xe(e))return;let r=new S,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||F(r,t))return;I(r,t),N(i,t)}return{kind:`object`,keys:i}}}function G(e){try{if(!C(e)||!xe(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)N(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;M(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!w(r)||O(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=Se(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&N(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;P(n)}}return n.length===0?r:void 0}catch{return}}const K=Error,Ce=Object.create,we=Object.defineProperty;function Te(e,t,n){let r=Ce(null);r.enumerable=!0,r.value=n,we(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=v(e,n);if(r===void 0){this.truncated=!0;let r=le(e,n);if(r.length>0){let e=v(r,n);if(e===void 0)throw new K(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=H(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):y(r,t)===void 0?Me(n):{value:U(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return v(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof K?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends K{constructor(t,n){super(n),Te(this,`name`,e.name),Te(this,e.memberNameProperty,t)}}}function q(e,t,n){return e?new e(t,n):new K(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=G(e.value);t===void 0?n.reject(new K(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new K(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=H(o)}catch{c=void 0}if(c===void 0)return Promise.reject(q(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:U(c)};return a!==void 0&&y(l,a)===void 0?Promise.reject(q(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(q(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(q(s,i,`binding arguments must be structured-cloneable: ${e instanceof K?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new K(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&y(f,r)===void 0?{type:`output-limit`}:f)}function J(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let Y=0;function X(e){return typeof e==`object`&&e?e:void 0}function Z(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function Ve(e){process.stdout.write(e),process.stdout.write(`\n`)}function He(e){let t=Z(e,Y);return t===void 0?!1:(Ve(t),!0)}function Ue(e){let t=X(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function We(e){return Ue(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ge(e,t){return e.error===void 0?{type:`done`,...e.value===void 0?{}:{value:Q(e.value)}}:t(e.error)?{type:`done`,error:e.error}:void 0}function Ke(e){let t=X(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function qe(e){let t=X(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=G(e);return t===void 0?null:U(t)}function Je(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Ye(){let e=n({input:process.stdin,crlfDelay:1/0}),r,a=0,o=2,s=0,c=!1,l=t=>{if(c)return;let n=Z(t,Y)??Z($(),Y);c=!0,n!==void 0&&Ve(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(i.stdout),t=J(i.stderr),n=Je(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},u=e=>{if(c)return;let t=+(s>0),n=v(e,a-o-t);if(n===void 0){l({type:`output-limit`});return}o+=n+t,s+=1,He({type:`log`,text:e})||l($())},d=e=>{a=e.maxOutputBytes,Y=e.maxFrameBytes,r=t(i(import.meta.url),[],{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,execArgv:[],stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{u(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{u(e.toString(`utf8`))}),n.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){u(t.text);return}if(!c){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)He({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||l($());else if(t.type===`output-limit`)l({type:`output-limit`});else if(t.type===`done`){let e=Ge(t,Ue);e!==void 0&&l(e)}}}}),n.on(`error`,e=>{l({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{c||l({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Ke(t);if(e===void 0){l({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}d(e);return}let n=qe(t);n!==void 0&&r.send(n,e=>{e!==null&&l({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!c&&l({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Xe(){let e,t=!1,n,i=0,o=e=>process.send===void 0||i>0&&Z(e,i)===void 0?!1:(process.send(e),!0),s=r=>{if(t)return;t=!0,clearInterval(n);let a=i>0&&Z(r,i)===void 0?$():r,s=e;e=void 0,(s===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=J(s.stdout),t=J(s.stderr);await Promise.all([s.terminate(),e,t])})).catch(e=>{o({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(a,()=>{process.connected&&process.disconnect()})})};process.on(`message`,c=>{if(e===void 0){let l=Ke(c);if(l===void 0){s({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}i=l.maxFrameBytes,e=new a(new URL(import.meta.url),{workerData:l,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:l.maxOldGenerationSizeMb}});let u=e;u.stdout.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.stderr.on(`data`,e=>{o({type:`log`,text:e.toString(`utf8`)})||s($())}),u.on(`message`,e=>{let t=X(e);if(t!==void 0){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)o({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||s($());else if(t.type===`log`&&typeof t.text==`string`)o({type:`log`,text:t.text})||s($());else if(t.type===`output-limit`)s({type:`output-limit`});else if(t.type===`done`){let e=Ge(t,We);e!==void 0&&s(e)}}}),u.on(`error`,e=>{s({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),u.on(`exit`,e=>{t||s({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),n=setInterval(()=>{e!==void 0&&e.performance.eventLoopUtilization().active>l.computeMs&&s({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${l.computeMs}ms busy)`}})},25);return}let l=qe(c);l!==void 0&&e.postMessage(l)}),process.on(`disconnect`,()=>{e!==void 0&&!t&&e.terminate()})}if(o)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Xe():Ye();else{if(s===null)throw Error(`remote worker requires parentPort`);let e=c;ze(s,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
+export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{spawn as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{Worker as i,isMainThread as a,parentPort as o,workerData as s}from\"node:worker_threads\";const c=Reflect.apply,l=Array.isArray,u=Buffer,d=Reflect.get(Buffer,`byteLength`),f=Object.create,p=Object.defineProperty,ee=Object.keys,te=String,ne=Reflect.get(String.prototype,`charCodeAt`),re=Reflect.get(String.prototype,`codePointAt`),ie=Reflect.get(String.prototype,`slice`);function m(e){let t=f(null);return t.value=e,t}function ae(e,t,n){let r=m(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function h(e){return c(d,u,[e,`utf8`])}function g(e,t){ae(e,e.length,t)}function _(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,m(t)),n}function v(e,t){return c(ie,e,[t,t+(c(re,e,[t])>65535?2:1)])}function y(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=c(ne,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:h(e)}function b(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=v(e,r);if(n+=y(i),n>t)return;r+=i.length}return n}function x(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=_(i);e!==void 0;e=_(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=b(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(h(te(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(l(a)){if(!r(2))return;a.length>0&&g(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=ee(a);e.length>0&&g(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&g(i,{...e,index:e.index+1}),g(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=b(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&g(i,{...e,index:e.index+1}),g(i,{kind:`value`,value:s})}return n}function oe(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=v(e,i),o=y(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:c(ie,e,[0,r])}const se=Reflect.get(Function.prototype,`toString`),S=Reflect.get(Reflect,`apply`),C=Error,ce=Set,w=Array.isArray,le=Array.prototype,T=Number.isFinite,ue=Number.isSafeInteger,de=Object.create,E=Object.defineProperty,fe=Object.getOwnPropertyDescriptor,D=Object.getPrototypeOf,O=Object.hasOwn,k=Object.is,pe=Object.keys,A=Object.prototype,me=Reflect.get(A,`propertyIsEnumerable`),j=Reflect.ownKeys,he=Reflect.get(Set.prototype,`add`),ge=Reflect.get(Set.prototype,`delete`),_e=Reflect.get(Set.prototype,`has`);function M(e){let t=de(null);return t.value=e,t}function N(e,t,n){let r=M(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,E(e,t,r)}function P(e,t){N(e,e.length,t)}function F(e){if(e.length===0)return;let t=e.length-1,n=e[t];return E(e,`length`,M(t)),n}function I(e,t){return S(_e,e,[t])}function L(e,t){S(he,e,[t])}function ve(e,t){S(ge,e,[t])}function R(e,t){let n=fe(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&S(se,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function z(e){return D(e)===null&&R(e,`Object`)}function B(e){let t=D(e);if(t===le)return!0;if(!w(t)||!R(t,`Array`))return!1;let n=D(t);return typeof n==`object`&&!!n&&z(n)}function V(e){let t=D(e);return t===null||t===A||typeof t==`object`&&z(t)}function ye(e){let t=j(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!S(me,e,[r]))return}return t}function H(e){let t=new ce,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?N(e.target,e.index,t):N(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=F(i);e!==void 0;e=F(i)){if(e.kind===`leave`){ve(t,e.source);continue}if(e.kind===`array-item`){if(!O(e.source,e.index))return;P(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){P(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!T(n)||k(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||I(t,n))return;if(w(n)){if(!B(n))return;let a=n.length;if(j(n).length!==a+1)return;let o=[];r(e.destination,o),L(t,n),P(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)P(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!V(n))return;let a=ye(n);if(a===void 0)return;let o={};r(e.destination,o),L(t,n),P(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;P(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function U(e){let t=[],n=[e];for(let e=F(n);e!==void 0;e=F(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){P(t,e);continue}if(w(e)){P(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new C(`cannot encode a sparse JSON array`);P(n,r)}continue}let r=pe(e);P(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new C(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new C(`cannot encode an undefined JSON object property`);P(n,a)}}return t}function be(e){if(!B(e)||j(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!O(e,t))return!1;return!0}function W(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function xe(e){if(w(e)||!V(e))return;let t=ye(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!W(t,`kind`)||!W(t,`length`))return;let e=n.length;return typeof e==`number`&&ue(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!W(t,`kind`)||!W(t,`keys`))return;let e=n.keys;if(!w(e)||!be(e))return;let r=new ce,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||I(r,t))return;L(r,t),P(i,t)}return{kind:`object`,keys:i}}}function Se(e){try{if(!w(e)||!be(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)P(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;N(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!T(r)||k(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=xe(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&P(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;F(n)}}return n.length===0?r:void 0}catch{return}}const G=Error,Ce=Object.create,we=Object.defineProperty;function Te(e,t,n){let r=Ce(null);r.enumerable=!0,r.value=n,we(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=b(e,n);if(r===void 0){this.truncated=!0;let r=oe(e,n);if(r.length>0){let e=b(r,n);if(e===void 0)throw new G(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=H(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):x(r,t)===void 0?Me(n):{value:U(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return b(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof G?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends G{constructor(t,n){super(n),Te(this,`name`,e.name),Te(this,e.memberNameProperty,t)}}}function K(e,t,n){return e?new e(t,n):new G(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=Se(e.value);t===void 0?n.reject(new G(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new G(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=H(o)}catch{c=void 0}if(c===void 0)return Promise.reject(K(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:U(c)};return a!==void 0&&x(l,a)===void 0?Promise.reject(K(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(K(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(K(s,i,`binding arguments must be structured-cloneable: ${e instanceof G?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new G(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&x(f,r)===void 0?{type:`output-limit`}:f)}function q(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let J=0;function Ve(){let e=process.execArgv.indexOf(`--eval`);if(e<0)throw Error(`code runtime runner requires its eval source`);let t=process.execArgv[e+1];if(t===void 0)throw Error(`code runtime runner requires its eval source`);return t}function Y(e){return typeof e==`object`&&e?e:void 0}function X(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function He(e){process.stdout.write(e),process.stdout.write(`\n`)}function Ue(e){let t=X(e,J);return t===void 0?!1:(He(t),!0)}function We(e){let t=Y(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function Ge(e){return We(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ke(e,t){return e.error===void 0?{type:`done`,...e.value===void 0?{}:{value:Q(e.value)}}:t(e.error)?{type:`done`,error:e.error}:void 0}function Z(e){let t=Y(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function qe(e){let t=Y(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=Se(e);return t===void 0?null:U(t)}function Je(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Ye(){let e=n({input:process.stdin,crlfDelay:1/0}),r,i=0,a=2,o=0,s=!1,c=t=>{if(s)return;let n=X(t,J)??X($(),J);s=!0,n!==void 0&&He(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=q(i.stdout),t=q(i.stderr),n=Je(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},l=e=>{if(s)return;let t=+(o>0),n=b(e,i-a-t);if(n===void 0){c({type:`output-limit`});return}a+=n+t,o+=1,Ue({type:`log`,text:e})||c($())},u=e=>{i=e.maxOutputBytes,J=e.maxFrameBytes,r=t(process.execPath,process.execArgv,{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{l(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{l(e.toString(`utf8`))}),n.on(`message`,e=>{let t=Y(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){l(t.text);return}if(!s){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)Ue({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||c($());else if(t.type===`output-limit`)c({type:`output-limit`});else if(t.type===`done`){let e=Ke(t,We);e!==void 0&&c(e)}}}}),n.on(`error`,e=>{c({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{s||c({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&c({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),c({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Z(t);if(e===void 0){c({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}u(e);return}let n=qe(t);n!==void 0&&r.send(n,e=>{e!==null&&c({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!s&&c({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Xe(){let t,n=!1,a,o=0,s=e=>process.send===void 0||o>0&&X(e,o)===void 0?!1:(process.send(e),!0),c=e=>{if(n)return;n=!0,clearInterval(a);let r=o>0&&X(e,o)===void 0?$():e,i=t;t=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=q(i.stdout),t=q(i.stderr);await Promise.all([i.terminate(),e,t])})).catch(e=>{s({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(r,()=>{process.connected&&process.disconnect()})})};process.on(`message`,l=>{if(t===void 0){let u=Z(l);if(u===void 0){c({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}o=u.maxFrameBytes,t=new i(new URL(`data:text/javascript;base64,${e.from(Ve()).toString(`base64`)}`),{workerData:u,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:u.maxOldGenerationSizeMb}});let d=t;d.stdout.on(`data`,e=>{s({type:`log`,text:e.toString(`utf8`)})||c($())}),d.stderr.on(`data`,e=>{s({type:`log`,text:e.toString(`utf8`)})||c($())}),d.on(`message`,e=>{let t=Y(e);if(t!==void 0){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)s({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||c($());else if(t.type===`log`&&typeof t.text==`string`)s({type:`log`,text:t.text})||c($());else if(t.type===`output-limit`)c({type:`output-limit`});else if(t.type===`done`){let e=Ke(t,Ge);e!==void 0&&c(e)}}}),d.on(`error`,e=>{c({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),d.on(`exit`,e=>{n||c({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),a=setInterval(()=>{t!==void 0&&t.performance.eventLoopUtilization().active>u.computeMs&&c({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${u.computeMs}ms busy)`}})},25);return}let u=qe(l);u!==void 0&&t.postMessage(u)}),process.on(`disconnect`,()=>{t!==void 0&&!n&&t.terminate()})}if(a)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Xe():Ye();else{if(o===null)throw Error(`remote worker requires parentPort`);let e=s;ze(o,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
diff --git a/packages/util/atomic-write/src/runner.ts b/packages/util/atomic-write/src/runner.ts
index 92fad6db2e..2655d22026 100644
--- a/packages/util/atomic-write/src/runner.ts
+++ b/packages/util/atomic-write/src/runner.ts
@@ -1,12 +1,11 @@
 /** Typed source for the dependency-free execution-world runner bundle. */
 
 import { Buffer } from 'node:buffer'
-import { fork } from 'node:child_process'
+import { spawn } from 'node:child_process'
 import type { ChildProcess } from 'node:child_process'
 import { createInterface } from 'node:readline'
 import type { Readable } from 'node:stream'
 import { inspect } from 'node:util'
-import { fileURLToPath } from 'node:url'
 import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
 import {
   decodeWorkerJson,
@@ -56,6 +55,14 @@ const failureKinds = new Set<FailureKind>([
 
 let maxFrameBytes = 0
 
+function runnerSource(): string {
+  const evalIndex = process.execArgv.indexOf('--eval')
+  if (evalIndex < 0) throw new Error('code runtime runner requires its eval source')
+  const source = process.execArgv[evalIndex + 1]
+  if (source === undefined) throw new Error('code runtime runner requires its eval source')
+  return source
+}
+
 function recordOf(value: unknown): Record<string, unknown> | undefined {
   return typeof value === 'object' && value !== null ? value as Record<string, unknown> : undefined
 }
@@ -197,10 +204,9 @@ function runLauncher(): void {
   const startController = (boot: RuntimeBootData): void => {
     maxOutputBytes = boot.maxOutputBytes
     maxFrameBytes = boot.maxFrameBytes
-    controller = fork(fileURLToPath(import.meta.url), [], {
+    controller = spawn(process.execPath, process.execArgv, {
       env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
       detached: false,
-      execArgv: [],
       stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
     }) as Controller
     const current = controller
@@ -325,7 +331,8 @@ function runController(): void {
         return
       }
       controllerMaxFrameBytes = boot.maxFrameBytes
-      worker = new Worker(new URL(import.meta.url), {
+      const sourceUrl = new URL(`data:text/javascript;base64,${Buffer.from(runnerSource()).toString('base64')}`)
+      worker = new Worker(sourceUrl, {
         workerData: boot,
         env: {},
         execArgv: [],

From 87b2c5d93f44bd52bfd52b536251e98ae7c274d2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 05:04:01 +0800
Subject: [PATCH 337/516] docs(runtime): remove stale runtime storage claims

---
 .../architecture/2026-07-26-subprocess-seam.i18n.yaml         | 4 ++--
 .../implemented/architecture/2026-07-26-subprocess-seam.md    | 4 ++--
 .../implemented/architecture/2026-07-26-subprocess-seam.zh.md | 4 ++--
 .../2026-07-28-portable-execution-world-consumers.i18n.yaml   | 4 ++--
 .../2026-07-28-portable-execution-world-consumers.md          | 2 +-
 .../2026-07-28-portable-execution-world-consumers.zh.md       | 2 +-
 docs/core-data-structures/subprocess.i18n.yaml                | 4 ++--
 docs/core-data-structures/subprocess.md                       | 2 +-
 docs/core-data-structures/subprocess.zh.md                    | 2 +-
 packages/subprocess/README.i18n.yaml                          | 4 ++--
 packages/subprocess/README.md                                 | 4 ++--
 packages/subprocess/README.zh.md                              | 4 ++--
 12 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index 0b62184128..fde94ee5cf 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: 359977ac6a50394405163bc060f3a39eb68891fb
-2026-07-26-subprocess-seam.zh.md: 551fcc8f4df82d0c893d8e6f5423f172dfd5d9c5
+2026-07-26-subprocess-seam.md: 214a46959c48862176e3c790d541def3444e31ad
+2026-07-26-subprocess-seam.zh.md: 13ba397458a041ec358828bab53e75516fd3e76d
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index 359977ac6a..214a46959c 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -12,8 +12,8 @@ English | [中文](2026-07-26-subprocess-seam.zh.md)
 
 A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it:
 
-- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd and runtime storage, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
-- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, private runtime storage, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the seam's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The implementation has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their consumers.
+- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
+- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the seam's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The implementation has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their consumers.
 - **`dsh-bash-local` (consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
 - **`dsh-bash` (seam)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 551fcc8f4d..13ba397458 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -12,8 +12,8 @@ Status: implemented
 
 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方：
 
-- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd 与运行时存储、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
-- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、私有运行时存储、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 seam 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该实现没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
+- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
+- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 seam 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该实现没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
 - **`dsh-bash-local`（消费方）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
 - **`dsh-bash`（seam）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash 消费方需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 3fce989f78..62592b5be0 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 74fa2687782a2cf59be8dddf98fa4a08a953d565
-2026-07-28-portable-execution-world-consumers.zh.md: 35d4f3640a44564894fecfaa22c7255d7452dec9
+2026-07-28-portable-execution-world-consumers.md: 97c8bcfc7bf84db4b6a2862fcc9d991ee7f4a7f6
+2026-07-28-portable-execution-world-consumers.zh.md: 025393f9e5ae99feba41fa8badeef8276151ba6f
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 74fa268778..97c8bcfc7b 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -16,7 +16,7 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all
 
 The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, and containment. Existing whole and streaming text operations remain filesystem-owned; protocol consumers enforce their own retention limits while consuming the stream.
 
-The subprocess interface owns the process coordinates and primitives: canonical cwd, private runtime storage, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+The subprocess interface owns the process coordinates and primitives: canonical cwd, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
 
 Generic consumers use that execution world:
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 35d4f3640a..025393f9e5 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责进程运行坐标与原语：规范化 cwd、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index f6c61bd691..cfa3762222 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: f0fe691219df3afba2b836da8f1594fd5fe5a87b
-subprocess.zh.md: f59e787820ba2727fdc0c4b62c4aec7b8d2d6b7a
+subprocess.md: c68a2f77059f62b273c536987b321017f2a71bbb
+subprocess.zh.md: 061c681430ba1f011b4ed9e5c4d9fc8595fe6738
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index 89f30095bc..a258ff4767 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -246,4 +246,4 @@ The terminal spec fully specifies argv, cwd, environment overrides, dimensions,
 
 ## Service behavior
 
-The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) implements them with temporary runtime storage, detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the interface contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
+The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) implements them with detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the interface contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index f59e787820..061c681430 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -246,4 +246,4 @@ interface SubprocessOutcome {
 
 ## 服务行为
 
-抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以临时运行时存储、detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index f6de20e259..af424b8809 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: b4aaf78454a51af4d3f7ea9f1aef450fde8d729d
-README.zh.md: c5013ce19bacb582b6c8c93e0ea0a73ec776ee57
+README.md: 5ea1ae3681f9340cfba798e659f454d6d05fdbfe
+README.zh.md: 4e1cb9472d6e90062ecde61db4200a79a56b16f1
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index b4aaf78454..5ea1ae3681 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-The shared process substrate for one execution world: canonical cwd/runtime storage, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+The shared process substrate for one execution world: canonical cwd, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 | Package | ctx key | Role |
 |---|---|---|
 | [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: execution-world coordinates and executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
-| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, runtime storage, and terminate-and-join disposal |
+| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index c5013ce19b..4e1cb9472d 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-这里集中提供一个执行世界的共享进程基底：规范化 cwd／运行时存储、可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[子进程代码运行时](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+这里集中提供一个执行世界的共享进程基底：规范化 cwd、可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[子进程代码运行时](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
 | [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：执行世界坐标与可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
-| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送、运行时存储，以及先终止再等待退出的资源释放 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
 
 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。

From c1d08edd8324092c4981baee3bd030fbc2cd740b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 05:19:53 +0800
Subject: [PATCH 338/516] refactor(runtime): remove duplicate terminal
 ownership state

---
 packages/pty/pty-local/src/session.ts            | 16 ++++++----------
 .../subprocess/subprocess-local/src/terminal.ts  |  5 ++---
 .../subprocess-local/tests/terminal.spec.ts      |  1 +
 3 files changed, 9 insertions(+), 13 deletions(-)

diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index ebd7e076cf..faea1ef84d 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -167,7 +167,7 @@ export class LocalPtySession implements PtyBackendSession {
   private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
   private interrupting: LocalSendOperation | undefined
-  private activeWrite: { operation: LocalSendOperation; settled: Promise<boolean> } | undefined
+  private activeWrite: Promise<boolean> | undefined
   private pollingReady: LocalSendOperation | undefined
   private polling = false
   private promptSeen = false
@@ -238,7 +238,7 @@ export class LocalPtySession implements PtyBackendSession {
     }
     this.activeDeadlineTimer = setTimeout(() => {
       if (this.active === operation) {
-        this.settleActive('timeout', this.activeWrite?.operation === operation || this.interrupting === operation)
+        this.settleActive('timeout', this.activeWrite !== undefined || this.interrupting === operation)
       }
     }, this.config.timeoutMs)
     void this.beginSend(operation, request)
@@ -254,11 +254,7 @@ export class LocalPtySession implements PtyBackendSession {
       if (input.length > 0 && !operation.cancelRequested) {
         this.resetReadinessEvidence()
         const write = this.terminal.write(input)
-        const activeWrite = {
-          operation,
-          settled: write.then(() => true, () => false),
-        }
-        this.activeWrite = activeWrite
+        this.activeWrite = write.then(() => true, () => false)
         try {
           await write
         } finally {
@@ -272,7 +268,7 @@ export class LocalPtySession implements PtyBackendSession {
         return
       }
       // Closing can race the awaited provider write even though static analysis sees only local assignments.
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited provider writes can close the session.
       if (this.active === operation && !this.closing) {
         this.pollingReady = operation
         this.schedulePoll(operation)
@@ -448,7 +444,7 @@ export class LocalPtySession implements PtyBackendSession {
       this.polling = false
       const active = this.active
       // Awaited provider inspection can clear or replace the active send despite static analysis.
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited inspection can replace the active send.
       if (active !== undefined && this.pollingReady === active) this.schedulePoll(active)
     }
   }
@@ -506,7 +502,7 @@ export class LocalPtySession implements PtyBackendSession {
   private async interruptOnce(operation: LocalSendOperation): Promise<void> {
     try {
       const activeWrite = this.activeWrite
-      if (activeWrite?.operation === operation && !await activeWrite.settled) return
+      if (activeWrite !== undefined && !await activeWrite) return
       await this.terminal.signalForeground('SIGINT')
     } catch (error: unknown) {
       if (this.active === operation && !this.closing) this.onTransportFailure(error)
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 93b7a8fc2e..53c531675f 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -58,19 +58,18 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
         exitCode: exitSignal === undefined || exitSignal === 0 ? exitCode : null,
         signal: signalName(exitSignal),
       })
-      void this.terminate().catch(() => {})
     })
   }
 
   // node-pty writes synchronously; the seam returns a promise for remote transports.
-  // eslint-disable-next-line @typescript-eslint/require-await
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
   async write(data: string): Promise<void> {
     if (this.exited) throw new Error('terminal process has exited')
     this.terminal.write(data)
   }
 
   // Local inspection is synchronous; the seam returns a promise for remote transports.
-  // eslint-disable-next-line @typescript-eslint/require-await
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
   async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
     this.descendants()
     const processGroupId = this.inspector.foregroundPgid(this.pid)
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
index 2eeb7c6a27..8a6270883f 100644
--- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -128,6 +128,7 @@ describe('LocalTerminalHandle', () => {
     const handle = new LocalTerminalHandle(pty.asPty(), inspector, 20)
 
     const quiescent = handle.terminate()
+    expect(handle.terminate()).toBe(quiescent)
     await vi.advanceTimersByTimeAsync(20)
     expect(inspector.processes).toContainEqual([124, 'SIGKILL'])
     expect(pty.kills).toEqual([])

From 4d5345794d73e51d09620cce859303d642a76bf1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 14:24:47 +0800
Subject: [PATCH 339/516] refactor(code-runtime): remove subprocess backend

---
 .../2026-07-26-subprocess-seam.i18n.yaml      |   4 +-
 .../2026-07-26-subprocess-seam.md             |  10 +-
 .../2026-07-26-subprocess-seam.zh.md          |  10 +-
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |  13 +-
 ...8-portable-execution-world-consumers.zh.md |  14 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |   4 +-
 .../feature/2026-06-15-code-mode.md           |  14 +-
 .../feature/2026-06-15-code-mode.zh.md        |  14 +-
 docs/capability-seams.md                      |  79 +-
 docs/config-catalog.md                        |  26 +-
 .../core-data-structures/subprocess.i18n.yaml |   4 +-
 docs/core-data-structures/subprocess.md       |   6 +-
 docs/core-data-structures/subprocess.zh.md    |   6 +-
 knip.json                                     |  11 -
 package.json                                  |   2 -
 packages/README.i18n.yaml                     |   4 +-
 packages/README.md                            |   2 +-
 packages/README.zh.md                         |   2 +-
 .../code-runtime-worker/src/bootstrap.ts      |  19 +-
 .../code-runtime-worker/src/runtime-host.ts   | 251 ------
 .../tests/bootstrap.spec.ts                   |  27 -
 .../code-runtime-worker/tsconfig.json         |   3 +
 .../code-runtime-worker/tsdown.config.ts      |  17 +-
 packages/code-runtime/code-runtime/README.md  |   4 +-
 .../code-runtime/tests/contract.ts            | 853 ------------------
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.md                 |   4 +-
 packages/subprocess/README.zh.md              |   4 +-
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |   4 +-
 .../subprocess/subprocess-local/README.zh.md  |   4 +-
 .../subprocess/subprocess-local/src/index.ts  |   3 +-
 .../subprocess-local/tests/local.spec.ts      |   3 -
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.md      |   4 +-
 packages/subprocess/subprocess/README.zh.md   |   4 +-
 packages/subprocess/subprocess/src/index.ts   |  11 +-
 scripts/check-workspace-constraints.ts        |   1 -
 scripts/gen-code-runtime-runner.ts            |  70 --
 scripts/gen-doc-graphs.ts                     | 276 ++----
 scripts/run-gates.ts                          |   1 -
 .../verify-package-readme-model-experience.ts |   1 -
 tsconfig.host.json                            |   1 -
 44 files changed, 192 insertions(+), 1614 deletions(-)
 delete mode 100644 packages/code-runtime/code-runtime-worker/src/runtime-host.ts
 delete mode 100644 packages/code-runtime/code-runtime/tests/contract.ts
 delete mode 100644 scripts/gen-code-runtime-runner.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index fde94ee5cf..f805e7cde3 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: 214a46959c48862176e3c790d541def3444e31ad
-2026-07-26-subprocess-seam.zh.md: 13ba397458a041ec358828bab53e75516fd3e76d
+2026-07-26-subprocess-seam.md: 8797102c65ebab663bcf72fced5791364fe2c6ae
+2026-07-26-subprocess-seam.zh.md: 8a7ff14079374d6d74a1ec729dd02c8961fa23e6
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index 214a46959c..8797102c65 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -12,7 +12,7 @@ English | [中文](2026-07-26-subprocess-seam.zh.md)
 
 A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it:
 
-- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: execution-world cwd, executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
+- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
 - **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the seam's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The implementation has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their consumers.
 - **`dsh-bash-local` (consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
 - **`dsh-bash` (seam)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
@@ -21,13 +21,13 @@ Every composition that loads a bash executor now also loads `@deepseek-ai/dsh-su
 
 Background-process lifetime moved from the executor to the subprocess service: the executor no longer retains a live-process set, so an executor reload leaves background work running and readable, and composition teardown (the service's disposal) remains the kill-and-join boundary. One behavioral seam shifted with it: a background spawn failure can no longer be buffered as fake stderr inside the plumbing (the service rejects `done` and buffers nothing for a process that never ran), so the executor injects the `spawn failed: …` note into exactly one `readOutput()` delta.
 
-Observed stream and lifecycle needs then moved the eligible process consumers onto the seam: LSP uses piped protocol streams plus a collected stderr tail; the ACP backend uses piped ndjson, inherited stderr, and a consumer-owned stdin-EOF disposal ladder; PTY uses `spawnTerminal()` while keeping readiness and terminal policy; Code Runtime uses ordinary raw pipes. `dsh-subagent-subprocess` and the private LSP tree helpers were deleted. MCP transport spawning, the SDK package-manager runner, synchronous TUI Git probing, and dependency-light test-support launchers remain outside by ownership or execution shape; their production callers share the scrub where applicable.
+Observed stream and lifecycle needs then moved the eligible process consumers onto the seam: LSP uses piped protocol streams plus a collected stderr tail; the ACP backend uses piped ndjson, inherited stderr, and a consumer-owned stdin-EOF disposal ladder; PTY uses `spawnTerminal()` while keeping readiness and terminal policy. `dsh-subagent-subprocess` and the private LSP tree helpers were deleted. MCP transport spawning, the SDK package-manager runner, synchronous TUI Git probing, and dependency-light test-support launchers remain outside by ownership or execution shape; their production callers share the scrub where applicable.
 
 ## Alternatives considered
 
 **Leave the process plumbing inside `dsh-bash-local` (status quo).** Rejected for the same reason the [task registry split](2026-07-26-task-registry-seam.md) landed: the boundary is stable and already documented in-code (`run.ts`'s module doc said "this layer reacts to an abort signal; the executor owns deadlines and classifies causes"), and keeping it private makes every future non-shell runner either fork the mechanics or depend on a bash-named package for non-bash work. The user-visible driver for this stack was exactly this split.
 
-**Keep the original batch-only interface and leave stream consumers bespoke.** Rejected after the observed LSP, ACP, PTY, and Code Runtime shapes showed that private process-tree signalling and environment scrubs would otherwise remain duplicated. The Node-shaped dispositions cover those consumers without buffering piped streams.
+**Keep the original batch-only interface and leave stream consumers bespoke.** Rejected after the observed LSP, ACP, and PTY shapes showed that private process-tree signalling and environment scrubs would otherwise remain duplicated. The Node-shaped dispositions cover those consumers without buffering piped streams.
 
 **Use one `stdio: 'pipe' | 'inherit' | 'collect'` mode for all streams.** Rejected because real consumers mix modes per stream: LSP uses pipe/pipe/collect, ACP uses pipe/pipe/inherit, and Bash uses data/collect/collect.
 
@@ -39,6 +39,6 @@ Observed stream and lifecycle needs then moved the eligible process consumers on
 
 ## Consequences
 
-Bought: "run and manage a process" is a swappable capability used by Bash, LSP, PTY, Code Runtime, and ACP consumers; a containerized or remote process backend slots in without changing their domain semantics; tree signalling, escalation, bounded collection, terminal mechanics, and credential scrubbing each have one implementation; and background processes survive executor reloads, matching the task registry's lifetime model. Process and terminal plumbing is tested through `dsh-subprocess-local`; consumer suites pin only their owned behavior against the real service.
+Bought: "run and manage a process" is a swappable capability used by Bash, LSP, PTY, and ACP consumers; a containerized or remote process backend slots in without changing their domain semantics; tree signalling, escalation, bounded collection, terminal mechanics, and credential scrubbing each have one implementation; and background processes survive executor reloads, matching the task registry's lifetime model. Process and terminal plumbing is tested through `dsh-subprocess-local`; consumer suites pin only their owned behavior against the real service.
 
-Cost: one more package pair and one more composition row wherever a consumer loads; a missing subprocess provider leaves the consumer pending by standard service-injection behavior. Every backend implements execution-world coordinates, executable lookup, three stdio modes, tree lifecycle, and one terminal primitive. The moved-vocabulary re-exports keep `dsh-bash` imports working but mean two packages name the same types; the subprocess seam is the owner. The spawn-failure note became single-delivery through Bash's consuming read cursor instead of repeatable stderr-buffer content.
+Cost: one more package pair and one more composition row wherever a consumer loads; a missing subprocess provider leaves the consumer pending by standard service-injection behavior. Every backend implements executable lookup, three stdio modes, tree lifecycle, and one terminal primitive. The moved-vocabulary re-exports keep `dsh-bash` imports working but mean two packages name the same types; the subprocess seam is the owner. The spawn-failure note became single-delivery through Bash's consuming read cursor instead of repeatable stderr-buffer content.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 13ba397458..8a7ff14079 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方：
 
-- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：执行环境 cwd、可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
+- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
 - **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 seam 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该实现没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
 - **`dsh-bash-local`（消费方）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
 - **`dsh-bash`（seam）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash 消费方需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
@@ -21,13 +21,13 @@ Status: implemented
 
 后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为 seam 随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
 
-基于已观察到的流与生命周期需求，具备条件的进程消费方随后迁到该 seam：LSP 使用管道化协议流加收集式 stderr 尾部；ACP（Agent Client Protocol）后端使用管道化 ndjson、继承式 stderr 和消费方拥有的 stdin-EOF dispose 阶梯；PTY 使用 `spawnTerminal()`，同时保留就绪与终端策略；Code Runtime 使用普通原始管道。`dsh-subagent-subprocess` 与 LSP 私有进程树辅助函数均被删除。MCP 传输 spawn、SDK 包管理器运行器、同步 TUI Git 探测和刻意保持轻依赖的 test-support 启动器因所有权或执行形状仍留在外部；适用的生产调用方共享凭据清除。
+基于已观察到的流与生命周期需求，具备条件的进程消费方随后迁到该 seam：LSP 使用管道化协议流加收集式 stderr 尾部；ACP（Agent Client Protocol）后端使用管道化 ndjson、继承式 stderr 和消费方拥有的 stdin-EOF dispose 阶梯；PTY 使用 `spawnTerminal()`，同时保留就绪与终端策略。`dsh-subagent-subprocess` 与 LSP 私有进程树辅助函数均被删除。MCP 传输 spawn、SDK 包管理器运行器、同步 TUI Git 探测和刻意保持轻依赖的 test-support 启动器因所有权或执行形状仍留在外部；适用的生产调用方共享凭据清除。
 
 ## 曾考虑的替代方案
 
 **把进程管道留在 `dsh-bash-local` 里（维持现状）。**否决的理由与[任务注册表拆分](2026-07-26-task-registry-seam.md)得以落地的理由相同：这条边界既稳定，也早已记录在代码里（`run.ts` 的模块文档曾写明「this layer reacts to an abort signal; the executor owns deadlines and classifies causes」），而若继续将它保持私有，未来每个非 shell 运行器就只能要么 fork 这套机制，要么为非 bash 工作去依赖一个以 bash 命名的包。这组堆叠变更对用户可见的动因正是这一拆分。
 
-**保留最初只支持批量的接口，让流式消费方继续各自实现。**否决：已观察到的 LSP、ACP、PTY 与 Code Runtime 形状表明，这会继续保留重复的私有进程树信号与环境清除。Node 形状的处置方式覆盖这些消费方，又不缓冲管道化流。
+**保留最初只支持批量的接口，让流式消费方继续各自实现。**否决：已观察到的 LSP、ACP 与 PTY 形状表明，这会继续保留重复的私有进程树信号与环境清除。Node 形状的处置方式覆盖这些消费方，又不缓冲管道化流。
 
 **用单个 `stdio: 'pipe' | 'inherit' | 'collect'` 模式统一全部流。**否决：真实消费方按流混用模式——LSP 使用 pipe/pipe/collect，ACP 使用 pipe/pipe/inherit，Bash 使用 data/collect/collect。
 
@@ -39,6 +39,6 @@ Status: implemented
 
 ## 后果
 
-换来的是：「运行并管理一个进程」成为 Bash、LSP、PTY、Code Runtime 与 ACP 消费方共用的可替换能力；容器化或远程进程后端可以直接接入，而无需改变各领域语义；进程树信号、升级终止、有界收集、终端机制与凭据清除各自只剩一份实现；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。进程与终端管道通过 `dsh-subprocess-local` 测试；消费方测试套件只需针对真实服务固定各自拥有的行为。
+换来的是：「运行并管理一个进程」成为 Bash、LSP、PTY 与 ACP 消费方共用的可替换能力；容器化或远程进程后端可以直接接入，而无需改变各领域语义；进程树信号、升级终止、有界收集、终端机制与凭据清除各自只剩一份实现；后台进程也能在执行器重载后存活，与任务注册表的存续期模型一致。进程与终端管道通过 `dsh-subprocess-local` 测试；消费方测试套件只需针对真实服务固定各自拥有的行为。
 
-代价是：多出一对包，而且凡加载消费方之处都多一行组合配置；缺少 subprocess 提供方时，消费方会按标准服务注入行为保持挂起。每个后端都要实现执行环境坐标、可执行文件查找、三种 stdio 模式、进程树生命周期和一个终端原语。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包命名同一批类型；进程 seam 是所有者。spawn 失败提示经由 Bash 的消费式读取游标变为单次交付，不再是可重复读取的 stderr 缓冲内容。
+代价是：多出一对包，而且凡加载消费方之处都多一行组合配置；缺少 subprocess 提供方时，消费方会按标准服务注入行为保持挂起。每个后端都要实现可执行文件查找、三种 stdio 模式、进程树生命周期和一个终端原语。迁移词汇的重导出让 `dsh-bash` 的导入继续可用，但也意味着两个包命名同一批类型；进程 seam 是所有者。spawn 失败提示经由 Bash 的消费式读取游标变为单次交付，不再是可重复读取的 stderr 缓冲内容。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 62592b5be0..06fd47f329 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 97c8bcfc7bf84db4b6a2862fcc9d991ee7f4a7f6
-2026-07-28-portable-execution-world-consumers.zh.md: 025393f9e5ae99feba41fa8badeef8276151ba6f
+2026-07-28-portable-execution-world-consumers.md: 402aa580255a5bd6aa0d046e3bcc16f712da520d
+2026-07-28-portable-execution-world-consumers.zh.md: 26d493a79f8adb9e729ff69b0673f2f2775868b0
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 97c8bcfc7b..402aa58025 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-28-portable-execution-world-consumers.zh.md)
 
 ## Problem
 
-The filesystem and subprocess seams made file and ordinary process access replaceable, but several higher capabilities still reached host Node APIs directly. A remote execution provider therefore appeared to need separate PTY, LSP, and Code Runtime packages even though their domain behavior did not change. Those packages would be shallow adapters: each would duplicate an existing consumer merely to replace its file and process operations.
+The filesystem and subprocess seams made file and ordinary process access replaceable, but PTY and LSP still reached host Node APIs directly. A remote execution provider therefore appeared to need separate PTY and LSP packages even though their domain behavior did not change. Those packages would be shallow adapters: each would duplicate an existing consumer merely to replace its file and process operations.
 
 Ordinary pipes do not cover one requirement. A persistent terminal needs PTY allocation, foreground-process-group inspection and signalling, and cleanup of the complete terminal session. Pretending those operations can be rebuilt in `dsh-pty-local` from an ordinary `spawn()` handle would either leak provider internals or weaken its lifecycle contract.
 
@@ -16,20 +16,17 @@ Ordinary pipes do not cover one requirement. A persistent terminal needs PTY all
 
 The filesystem interface owns the path facts that another capability needs without exposing its opaque target identity: a canonical process path, canonical `file:` URI, and containment. Existing whole and streaming text operations remain filesystem-owned; protocol consumers enforce their own retention limits while consuming the stream.
 
-The subprocess interface owns the process coordinates and primitives: canonical cwd, executable lookup, ordinary raw or collected process spawning, and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
+The subprocess interface owns executable lookup and process primitives: ordinary raw or collected process spawning and `spawnTerminal()`. The terminal operation is one deep primitive whose handle owns text I/O, foreground groups, signalling, and one awaited TERM-to-KILL operation that settles in-flight handle calls and reaches quiescence for every session member the provider can still observe. Its signal cancels allocation only; the published handle owns its lifetime. Prompt detection, idle inference, scrollback, sandbox policy, and owner lifecycle remain in the PTY consumer.
 
 Generic consumers use that execution world:
 
 - `dsh-bash-local` continues to map Bash semantics onto ordinary `ctx.subprocess.spawn()`.
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; an in-flight readiness poll cannot release that reservation, and a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Startup cancellation begins terminal rollback without waiting for a stalled readiness or signalling call. Close rejects new public signals and delegates provider-observable session quiescence to the handle's awaited termination operation.
-- `dsh-code-runtime-subprocess` passes a bundled dependency-free eval runner directly to `ctx.subprocess`, preserving the Code Runtime binding and output contract across local or remote process worlds without a filesystem dependency or provider-specific package. It shares host-side worker mechanics through the non-plugin `dsh-code-runtime-worker/runtime-host` subpath instead of copying them. The heap-bounded worker rejects oversized binding frames before transfer, each outer hop enforces the same bound before forwarding, and raw subprocess pipes carry newline-delimited UTF-8 JSON without a redundant base64 representation. The launcher publishes an accepted terminal frame before reaping its controller so a descendant that inherits controller pipes cannot suppress completion; the host still awaits process-group quiescence.
-
-`dsh-code-runtime-worker` remains a separate implementation. It is the smaller in-process backend and works in single-file distributions that cannot assume an installed Node executable. Remote filesystem/process compositions select `dsh-code-runtime-subprocess`; they do not need a provider-specific Code Runtime package.
 
 ## Alternatives considered
 
-**Keep one PTY, LSP, and Code Runtime package per remote provider.** Rejected because provider mechanics would be repeated above the existing seams. The deletion test exposes the problem: deleting those adapters should not scatter domain behavior into the remote provider; the generic consumers already own it.
+**Keep one PTY and LSP package per remote provider.** Rejected because provider mechanics would be repeated above the existing seams. The deletion test exposes the problem: deleting those adapters should not scatter domain behavior into the remote provider; the generic consumers already own it.
 
 **Model a terminal as an ordinary piped subprocess.** Rejected because pipes cannot allocate a controlling terminal, resolve the current foreground process group, or prove complete terminal-session cleanup. One terminal primitive is smaller and more honest than exposing substrate-specific escape hatches.
 
@@ -39,13 +36,11 @@ Generic consumers use that execution world:
 
 **Add a stable bounded-read primitive to the filesystem seam.** Rejected because only LSP needs a complete-document byte ceiling, which it can enforce while consuming the existing text stream. A second primitive forces every provider to implement stable-handle and no-follow mechanics, including a remote helper protocol, without an observed concurrent-replacement defect.
 
-**Delete the worker-thread Code Runtime.** Rejected because portability does not erase its current deployment need. The subprocess backend requires a Node executable; the worker backend does not and remains the supported single-process path.
-
 **Run the whole harness inside the remote environment.** Rejected as a different deployment model. Making execution capabilities portable does not move model calls, session state, plugin state, or the agent loop.
 
 ## Consequences
 
-A remote execution provider implements only its shared sandbox owner plus filesystem and subprocess adapters. Bash, PTY, LSP, and subprocess Code Runtime compose above them, so fixes to those capabilities remain provider-neutral.
+A remote execution provider implements only its shared sandbox owner plus filesystem and subprocess adapters. Bash, PTY, and LSP compose above them, so fixes to those capabilities remain provider-neutral.
 
 The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 025393f9e5..26d493a79f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但若干上层能力仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY、LSP 与代码运行时包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
+文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但 PTY 和 LSP 仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY 与 LSP 包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
 
 普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期契约。
 
@@ -16,20 +16,16 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责可执行文件查找与进程原语：以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
 - `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。
-- `dsh-code-runtime-subprocess` 将一个内置的无依赖 eval runner 直接传给 `ctx.subprocess`，从而在本地或远程进程执行环境中保留代码运行时的绑定与输出契约，且不依赖文件系统或提供方专用包。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
-
-`dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
-
 ## 考虑过的替代方案
 
-**为每个远程提供方分别保留 PTY、LSP 和代码运行时包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
+**为每个远程提供方分别保留 PTY 与 LSP 包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
 
 **把终端建模为普通的管道子进程。** 不予采纳，因为管道无法分配控制终端、确定当前前台进程组或证明完整终端会话已清理。一项终端原语比公开特定于执行基底的逃生口更小，也更能如实表达契约。
 
@@ -39,13 +35,11 @@ Status: implemented
 
 **在文件系统 seam 中新增稳定的有界读取原语。** 不予采纳，因为只有 LSP 需要完整文档字节上限，而它可以在消费现有文本流时执行该上限。第二项原语会迫使每个提供方实现稳定句柄和不跟随符号链接的机制，远程提供方甚至需要辅助协议，却没有已观察到的并发替换缺陷。
 
-**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件，而 worker 后端不需要，并且仍是受支持的单进程路径。
-
 **在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop（智能体循环）。
 
 ## 后果
 
-远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY、LSP 和基于进程管理的代码运行时组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
+远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY 与 LSP 组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
 
 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index d2655b6d02..8773a797e9 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: a075ea66c150afb1b48f98c600b72eec57869962
-2026-06-15-code-mode.zh.md: c269c0a8709087e7b1e27051cbda3924f8dd9109
+2026-06-15-code-mode.md: b6a24ecd9700e32912b8112b59cbd8b6ab131eb5
+2026-06-15-code-mode.zh.md: 4d0a4cf8fa31cf9d9954e5bd95f823dfc0668444
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index a075ea66c1..b6a24ecd97 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -20,7 +20,7 @@ Three decisions, each elaborated in its own section below:
 
 1. **Code Mode is a first-class presentation mode of `ToolRegistry`** (`dsh-tools`), selected by a validated `mode` config: `'native'` (the default, contributing the visible capability schemas), `'code'` (the registry contributes only its reserved `run_code` transport plus a generated SDK `.d.ts` in the system prompt), or `'both'` (native schemas and the transport + SDK). The registry shapes its canonical contribution at the source; the cooperative prompt-assembly result remains authoritative, and the logged request header records exactly that returned presentation.
 2. **Code execution is a capability seam** — `packages/code-runtime/` contains the interface package `@deepseek-ai/dsh-code-runtime`, which owns `ctx.codeRuntime` ([capability seams](../architecture/2026-06-13-capability-seams.md); consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is another implementation package, not a redesign.
-3. **Two implementations preserve one fresh-worker contract**: `@deepseek-ai/dsh-code-runtime-worker` runs the worker in the harness process, while `@deepseek-ai/dsh-code-runtime-subprocess` passes a bundled eval runner to `ctx.subprocess` for another execution world. Both execute host-stripped TypeScript in a fresh Node worker with an empty environment, bridged bindings, configurable heap/output/time caps, and hard termination. Their trust posture is bash-equivalent by design; stronger isolation comes from the mounted execution world.
+3. **The shipped implementation is `@deepseek-ai/dsh-code-runtime-worker`**: one fresh Node worker thread per run, executing the model's TypeScript after type-strip, with bindings bridged over the message port, an empty environment, configurable heap/output/time caps, and hard termination. Its trust posture is bash-equivalent by design — no unsafe-acknowledgement flags — because the harness already ships `dsh-bash-local`, which executes arbitrary model-written shell commands with strictly *more* ambient authority.
 
 This note owns Code Mode's presentation, composition, isolation, and settlement foundation. The later [typed tool-return Agent Note](2026-07-20-code-mode-typed-tool-returns.md) owns the generated output map, canonical binding values, `ToolCallError`, and the lossless outer-output boundary.
 
@@ -64,7 +64,7 @@ Each sub-dispatch appends a log-only `tool/code-dispatch-start` event at pool en
 - `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }` — the runtime exposes each namespace as a global object of async functions inside the program; the optional descriptor asks the runtime to inject a real program-visible rejection class without teaching the seam consumer-specific names. `CodeJsonValue` is this dependency-light seam's structural lossless-JSON type, so binding arguments and resolutions cross the implementation's serialization boundary whole.
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }` — program execution outcomes resolve as the `error` field. `run()` may reject only for caller/seam misuse (for example a duplicate binding namespace); consumers still contain a non-conforming backend rejection at their own error boundary.
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }` — orthogonal outcomes reported independently per [defensive patterns](../../../../docs/defensive-patterns.md); a timed-out run is not an exception, an abort is not a timeout, a lossy completion is not an overflow, and a substrate exit is none of them.
-- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for both shipped backends; a Python backend would pair with its own SDK generator) and `isolation` (`'worker-thread'` for both shipped backends; the subprocess provider may add a container boundary). `dsh-tools` requires `language === 'typescript'` in the MVP — its codegen emits TS — and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
+- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for the shipped backend; a Python backend would say so, and pair with its own SDK generator on the presentation side) and `isolation` (`'worker-thread'` for the shipped backend; `'process'`, `'container'`, … for future ones). `dsh-tools` requires `language === 'typescript'` in the MVP — its codegen emits TS — and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
 
 Requests contain every runtime input; implementations own validated timeout and cap defaults. The registry looks up the optional runtime only when Code Mode is assembled, so native mode does not depend on one. Missing or language-incompatible runtimes fail loudly. Alternate substrates or languages can replace the implementation behind the same seam, paired with the appropriate SDK generator.
 
@@ -79,11 +79,9 @@ Requests contain every runtime input; implementations own validated timeout and
 5. **Enforce independent budgets.** `computeMs` meters worker busy time, allowing slow awaited tools without excusing a hot loop. `maxWallMs` bounds total elapsed time, including unresolved waits. `maxOutputBytes` bounds only the combined serialized outer logs, completion, or diagnostic; intermediate binding values have no byte cap. Expiry, cancellation, and completion terminate the worker, and heap exits or outer overflow are explicit failures.
 6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../../docs/defensive-patterns.md).
 
-`@deepseek-ai/dsh-code-runtime-subprocess` preserves those program, binding, output, and worker-budget semantics across another process world. It passes a dependency-free eval runner directly through the subprocess provider and carries binding traffic over bounded newline-delimited UTF-8 JSON frames on raw pipes. The heap-bounded worker rejects expanded completion wires before MessagePort transfer; terminal settlement asks the launcher to reap its controller and keeps process-group escalation armed until `waitForExit()` confirms whole-tree quiescence. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns why this generic backend replaces provider-specific Code Runtime packages; `dsh-code-runtime-worker` remains the single-process and single-file-distribution path.
-
 ### Trust posture
 
-The runtimes provide containment, not an independent security boundary: model code can reach Node APIs and has the authority of its mounted execution world. Code Mode uses the same `tools/pre-execute` policy gate as bash and adds an empty worker environment, heap limits, a separate isolate, and hard termination of the program itself. Deployments that need a hard multi-tenant boundary mount container-class filesystem/subprocess providers for both code and bash.
+The worker runtime provides containment, not a security boundary: model code can reach Node APIs and has authority comparable to the bash tool. `worker.terminate()` stops the thread but not OS processes it spawned. Code Mode uses the same `tools/pre-execute` policy gate as bash and adds an empty environment, heap limits, a separate isolate, and hard termination of the program itself. Deployments that need a hard multi-tenant boundary need a container-class backend for both code and bash; the runtime's isolation descriptor lets them distinguish that backend.
 
 ### What the model sees
 
@@ -95,7 +93,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Testing
 
-- **Runtime implementations:** Real-worker suites cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger and per-hop frame boundaries, compute and wall budgets, hostile binding traffic, empty environment, descendant lifetime cleanup, and disposal to quiescence. Built-package tests run both the direct worker entry and the subprocess composition under plain Node; the latter also has a Loader-driven `cordis.yml` test.
+- **Worker runtime:** Real-worker tests cover typed binding values and failures, every lossless JSON completion root, invalid and over-limit output, exact combined ledger boundaries, compute and wall budgets, hostile binding traffic, empty environment, and disposal to quiescence. A built-package test runs the worker entry under plain Node.
 - **Registry integration:** Tests cover code generation, all presentation modes, reserved-name and restriction rules, scoped visibility, authoritative assembly rewrites, `toolOrder`, runtime compatibility failures, full-pipeline sub-dispatch, parent-token correlation, serialization, cancellation and queue drain, JSON normalization, error propagation, log events, ordered context deferral across successful and failed programs, outer-block suppression, and HMR cleanup.
 - **With-key e2e:** A real model composes two bash calls in one program; another discovers nested workspace instructions through a Code Mode fs dispatch. The tests verify collapsed request headers, correlated dispatch events, resulting files, deferred context, and model behavior.
 - **Snapshot:** The `code-mode-turn`, `both-mode-turn`, and `code-mode-workspace-context` fixtures pin SDK text, header tool lists, dispatch events, deferred context, and result cards.
@@ -120,7 +118,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Risks
 
-**A worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool and gating uses the same seams. The subprocess implementation can run inside a container-class execution world, but its worker descriptor does not itself claim that boundary.
+**The worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool, containment exceeds it, gating uses the same seams. Deployments needing more need a future `isolation: 'container'` backend — tracked as the seam's designed extension, not a TODO on this design.
 
 **`stripTypeScriptTypes` is marked experimental.** It is the same engine (amaro/swc) behind Node's own native `.ts` execution, exposed as an API across this repo's whole engines range. Mitigations: the runtime's unit suite pins the behaviors relied on (position preservation, erasable-only rejection message shape loosely), the call sits behind one private function, and `amaro`/`sucrase` are drop-in replacements if the API shifts. The erasable-only subset is a model-facing contract line, and the error path is a working feedback loop, not a dead end.
 
@@ -128,7 +126,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Registry scope growth.** `dsh-tools` absorbs codegen, a tool, a bridge, and an event. Contained by module boundaries inside the package (`ts-types.ts`, `code-mode.ts` beside `schema.ts`/`json-schema.ts`/`presentation.ts`) and by the seam: everything substrate-shaped lives behind `ctx.codeRuntime`.
 
-**Large lossless JSON values can exhaust memory.** Tool bindings snapshot lossless JSON before dispatch and return canonical JSON resolutions whole. The direct worker runtime applies no per-binding byte cap; the subprocess runtime bounds each transport frame with `maxFrameBytes`, but repeated or concurrent calls can still consume process or worker memory. The combined outer-output ledger for logs, the completion value, and a failure diagnostic is separately bounded by `maxOutputBytes`.
+**Large lossless JSON values can exhaust memory.** Tool bindings snapshot lossless JSON before dispatch and return canonical JSON resolutions whole. The runtime validates both sides of the worker port and applies no per-binding byte cap; structured-clone cost and process or worker memory are the practical bounds. The combined outer-output ledger for logs, the completion value, and a failure diagnostic is the only byte-capped boundary.
 
 **Serialized-only sub-dispatch.** `Promise.all` gains no wall-clock parallelism yet, only fewer round-trips; models may over-expect. The instructions state it; lifting it is tied to the same concurrency-safety metadata the native parallel-dispatch TODO needs.
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index c269c0a870..4d0a4cf8fa 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -20,7 +20,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
 2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
-3. **两种实现保持同一份全新 worker 契约**：`@deepseek-ai/dsh-code-runtime-worker` 在 harness 进程内运行 worker，`@deepseek-ai/dsh-code-runtime-subprocess` 则将一个内置的 eval runner 传给 `ctx.subprocess`，用于另一执行环境。二者都在具有空环境的全新 Node worker 内执行由宿主剥离类型的 TypeScript，并提供桥接绑定、可配置的堆／输出／时间上限和硬终止。其信任姿态在设计上等同于 bash；更强的隔离来自挂载的执行环境。
+3. **交付的实现是 `@deepseek-ai/dsh-code-runtime-worker`**：每次运行 spawn 一个全新的 Node worker 线程，对模型的 TypeScript 进行 type-strip 后执行，绑定通过消息端口桥接，环境为空，堆/输出/时间上限可配置，并支持硬终止。其信任姿态在设计上等同于 bash——无需 unsafe-acknowledgement flag——因为 harness 已经交付了 `dsh-bash-local`，后者以严格*更高*的环境权限执行模型编写的任意 shell 命令。
 
 本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
 
@@ -64,7 +64,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 - `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }`——运行时将每个命名空间作为程序内部的全局异步函数对象暴露；可选描述符要求运行时注入真正的、程序可见的 reject 类，而无需让 seam 获知消费方专用名称。`CodeJsonValue` 是这个低依赖 seam 的结构化无损 JSON 类型，因此绑定参数与解析值可以完整跨越实现的序列化边界。
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }`——程序执行失败时，执行 promise 仍会 fulfill，并通过 `error` 字段返回失败结果。只有调用方/seam 误用（例如重复的绑定命名空间）时，`run()` 才会 reject；消费方仍在自己的错误边界处理不合规后端的拒绝。
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }`——按[防御性模式](../../../../docs/defensive-patterns.md)独立报告的正交结果；超时的 run 不是异常，abort 不是超时，有损完成值不是溢出，基底退出也与上述情况相互独立。
-- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——两种已交付后端均为 `'typescript'`；Python 后端会配对自己的 SDK 生成器）和 `isolation`（两种已交付后端均为 `'worker-thread'`；子进程提供方可以增加容器边界）。`dsh-tools` 在 MVP 中要求 `language === 'typescript'`——其代码生成输出 TS——否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
+- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——交付的后端为 `'typescript'`；Python 后端会声明自己，并在呈现侧配对自己的 SDK 生成器）和 `isolation`（交付的后端为 `'worker-thread'`；未来可为 `'process'`、`'container'` 等）。`dsh-tools` 在 MVP 中要求 `language === 'typescript'`——其代码生成输出 TS——否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
 
 请求包含所有运行时输入；实现方拥有经校验的超时和上限默认值。注册表仅在组装 Code Mode 时查找可选的运行时，因此 native 模式不依赖它。缺失或语言不兼容的运行时会大声失败。替代基底或语言可以在同一 seam 背后替换实现，配对相应的 SDK 生成器。
 
@@ -79,11 +79,9 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
 6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
 
-`@deepseek-ai/dsh-code-runtime-subprocess` 在另一进程执行环境中保持相同的程序、绑定、输出与 worker 预算语义。它通过子进程提供方直接传递一个无依赖的 eval runner，并在原始管道上使用有界的、以换行符分隔的 UTF-8 JSON 帧承载绑定通信。受堆上限约束的 worker 会在通过 MessagePort 传输前拒绝展开后的完成值 wire；终态结算会请求 launcher 回收其 controller，并让进程组升级终止机制保持待命，直至 `waitForExit()` 确认整棵进程树完全停稳。[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)说明为何这个通用后端会取代提供方专用的 Code Runtime 包；`dsh-code-runtime-worker` 仍用于单进程和单文件发行版。
-
 ### 信任姿态
 
-这些运行时提供的是隔离，而非独立安全边界：模型代码可以访问 Node API，并拥有挂载的执行环境所授予的权限。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空 worker 环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署应当为代码和 bash 都挂载容器级文件系统／子进程提供方。
+worker 运行时提供的是隔离，而非安全边界：模型代码可以访问 Node API，权限与 bash 工具相当。`worker.terminate()` 停止线程但不停止它 spawn 的 OS 进程。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署需要为代码和 bash 都使用容器级后端；运行时的 isolation 描述符让它们能区分该后端。
 
 ### 模型看到的内容
 
@@ -95,7 +93,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 ## 测试
 
-- **运行时实现：** 真实 worker 测试套件覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界与逐跳帧边界、compute 和 wall 预算、恶意绑定流量、空环境、后代进程生命周期清理以及 dispose 至完全停稳。构建后包测试会在纯 Node 下分别运行直接 worker 入口与子进程组合；后者另有一个由 Loader 驱动的 `cordis.yml` 测试。
+- **Worker 运行时：** 真实 worker 测试覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界、compute 和 wall 预算、恶意绑定流量、空环境以及 dispose 至完全停稳。一个构建后包测试在纯 Node 下运行 worker 入口。
 - **注册表集成：** 测试覆盖代码生成、所有呈现模式、保留名称和限制规则、scoped 可见性、权威组装重写、`toolOrder`、运行时兼容性失败、完整流水线子分发、parent-token 关联、序列化、取消和队列排空、JSON 规范化、错误传播、日志事件、成功与失败程序中的有序上下文延后、外层阻止抑制以及 HMR（热模块替换）清理。
 - **带密钥 e2e：** 真实模型在一个程序中组合两次 bash 调用；另一个模型通过 Code Mode fs 分发发现嵌套的工作区指令。测试验证折叠的请求头、关联的分发事件、结果文件、延后上下文和模型行为。
 - **快照：** `code-mode-turn`、`both-mode-turn` 和 `code-mode-workspace-context` fixture（测试前置数据）固定 SDK 文本、请求头工具列表、分发事件、延后上下文和结果卡片。
@@ -120,7 +118,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 ## 风险
 
-**worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，门禁使用相同的 seam。子进程实现可以在容器级执行环境中运行，但其 worker 描述符本身不声称具备该边界。
+**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，隔离程度超过它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
 
 **`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的契约线，错误路径是一个可工作的反馈循环，而非死胡同。
 
@@ -128,7 +126,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 **注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。通过包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 约束：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
 
-**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 解析值。直接 worker 运行时不对单次绑定设置字节数上限；子进程运行时使用 `maxFrameBytes` 限制每个传输帧，但重复或并发调用仍可能消耗进程或 worker 内存。包含日志、完成值和失败诊断的组合外层输出账本另由 `maxOutputBytes` 限制。
+**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 解析值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
 
 **仅序列化的子分发。** `Promise.all` 尚未获得挂钟并行性，仅减少往返次数；模型可能过度期望。说明中已声明；解除此限制与原生并行分发 TODO 所需的并发安全元数据绑定。
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 1aee225b5d..c5ec654d0f 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -21,6 +21,7 @@ flowchart LR
   pkg_session["session"]
   svc_sessions["ctx.sessions<br/>In-memory session store"]
   pkg_agent["agent"]
+  pkg_cli_demo["cli-demo"]
   pkg_session_persistence["session-persistence"]
   pkg_session_query["session-query"]
   pkg_session_query_sqlite["session-query-sqlite"]
@@ -39,13 +40,6 @@ flowchart LR
   pkg_tool_bash["tool-bash"]
   pkg_hooks_claude["hooks-claude"]
   pkg_hooks_codex["hooks-codex"]
-  pkg_settings["settings"]
-  svc_settings["ctx.settings<br/>User-settings seam"]
-  pkg_settings_local["settings-local"]
-  pkg_apiproxy["apiproxy"]
-  pkg_credentials["credentials"]
-  svc_credentials["ctx.credentials<br/>Credential seam"]
-  pkg_credentials_local["credentials-local"]
   pkg_session_telemetry["session-telemetry"]
   svc_telemetry["ctx.telemetry<br/>Session telemetry seam"]
   pkg_session_telemetry_otel["session-telemetry-otel"]
@@ -57,10 +51,12 @@ flowchart LR
   svc_storageDomain["ctx.storageDomain<br/>Domain data facility"]
   pkg_workspace["workspace"]
   svc_workspace["ctx.workspace<br/>Workspace entity registry"]
+  pkg_apiproxy["apiproxy"]
   svc_sessionQuery["ctx.sessionQuery<br/>Session reads, traces, filters, and search"]
   pkg_session_reference["session-reference"]
   pkg_tool_session_query["tool-session-query"]
   svc_sessionReferences["ctx.sessionReferences<br/>Cross-session snapshot preparation"]
+  pkg_tui["tui"]
   pkg_session_title["session-title"]
   svc_sessionTitle["ctx.sessionTitle<br/>Log-backed session titles"]
   pkg_session_title_first_message_llm["session-title-first-message-llm"]
@@ -88,12 +84,13 @@ flowchart LR
   pkg_host_apiproxy["host-apiproxy"]
   pkg_session_projection_cache["session-projection-cache"]
   svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"]
+  svc_tui["ctx.tui<br/>Mounted-terminal interaction service"]
   pkg_skill["skill"]
   svc_skills["ctx.skills<br/>Skill provider registry"]
-  pkg_skill_badge["skill-badge"]
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
+  pkg_tui_demo["tui-demo"]
   svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_goal["goal"]
@@ -103,19 +100,14 @@ flowchart LR
   pkg_subprocess_local["subprocess-local"]
   pkg_bash_local["bash-local"]
   pkg_bash_sandbox["bash-sandbox"]
+  pkg_pty_local["pty-local"]
   pkg_lsp_local["lsp-local"]
   pkg_subagent_acp["subagent-acp"]
-  pkg_subagent_codex["subagent-codex"]
-  pkg_subagent_claude_code["subagent-claude-code"]
   pkg_bash["bash"]
   svc_bash["ctx.bash<br/>Bash executor seam"]
-  pkg_pwsh_local["pwsh-local"]
-  pkg_tool_pwsh["tool-pwsh"]
-  pkg_bash_env["bash-env"]
   svc_bashEnv["ctx.bashEnv<br/>Managed bash environment registry"]
   pkg_pty["pty"]
   svc_pty["ctx.pty<br/>Persistent PTY session registry"]
-  pkg_pty_local["pty-local"]
   pkg_sandbox["sandbox"]
   svc_sandbox["ctx.sandbox<br/>Process-sandbox seam"]
   pkg_sandbox_local["sandbox-local"]
@@ -136,11 +128,9 @@ flowchart LR
   pkg_compact["compact"]
   svc_compact["ctx.compact<br/>Compaction seam"]
   pkg_subagent["subagent"]
-  svc_subagents["ctx.subagents<br/>Subagent provider and continuation service"]
+  svc_subagents["ctx.subagents<br/>Subagent provider registry"]
   pkg_subagent_spawn["subagent-spawn"]
   pkg_subagent_fork["subagent-fork"]
-  pkg_subagent_dsh_sdk["subagent-dsh-sdk"]
-  pkg_tool_subagent_control["tool-subagent-control"]
   pkg_tool_ralph["tool-ralph"]
   pkg_tasks["tasks"]
   svc_tasks["ctx.tasks<br/>Background task registry"]
@@ -176,7 +166,6 @@ flowchart LR
   pkg_api_gateway --> svc_typertGateway
   pkg_approval --> svc_approval
   pkg_bash --> svc_bash
-  pkg_bash_env --> svc_bashEnv
   pkg_bash_local --> svc_bash
   pkg_bash_sandbox --> svc_bash
   pkg_code_runtime --> svc_codeRuntime
@@ -185,8 +174,6 @@ flowchart LR
   pkg_compact --> svc_compact
   pkg_compact_basic --> svc_compact
   pkg_compact_tool_result_prune --> svc_toolResultPrune
-  pkg_credentials --> svc_credentials
-  pkg_credentials_local --> svc_credentials
   pkg_directory_picker --> svc_directoryPicker
   pkg_directory_picker_browse --> svc_directoryPicker
   pkg_directory_picker_native --> svc_directoryPicker
@@ -204,7 +191,6 @@ flowchart LR
   pkg_plan_mode --> svc_planMode
   pkg_pty --> svc_pty
   pkg_pty_local --> svc_pty
-  pkg_pwsh_local --> svc_bash
   pkg_sandbox --> svc_sandbox
   pkg_sandbox_local --> svc_sandbox
   pkg_sandbox_policy --> svc_sandboxPolicy
@@ -222,10 +208,7 @@ flowchart LR
   pkg_session_title --> svc_sessionTitle
   pkg_session_title_all_messages_llm --> svc_sessionTitle
   pkg_session_title_first_message_llm --> svc_sessionTitle
-  pkg_settings --> svc_settings
-  pkg_settings_local --> svc_settings
   pkg_skill --> svc_skills
-  pkg_skill_badge --> svc_skills
   pkg_skill_local --> svc_skills
   pkg_spill --> svc_spillStore
   pkg_spill_local --> svc_spillStore
@@ -235,9 +218,6 @@ flowchart LR
   pkg_storage_sqlite --> svc_storage
   pkg_subagent --> svc_subagents
   pkg_subagent_acp --> svc_subagents
-  pkg_subagent_claude_code --> svc_subagents
-  pkg_subagent_codex --> svc_subagents
-  pkg_subagent_dsh_sdk --> svc_subagents
   pkg_subagent_fork --> svc_subagents
   pkg_subagent_spawn --> svc_subagents
   pkg_subprocess --> svc_subprocess
@@ -246,7 +226,10 @@ flowchart LR
   pkg_tasks --> svc_tasks
   pkg_tasks_local --> svc_tasks
   pkg_token_meter --> svc_tokenMeter
+  pkg_tool_bash --> svc_bashEnv
   pkg_tools --> svc_tools
+  pkg_tui --> svc_tui
+  pkg_tui --> svc_userInteraction
   pkg_typert_registry --> svc_typert
   pkg_user_interaction --> svc_userInteraction
   pkg_web --> svc_web
@@ -261,21 +244,18 @@ flowchart LR
   svc_agentLoop --> pkg_agent_spine_demo
   svc_agents --> pkg_acp
   svc_agents --> pkg_agent_loop
+  svc_agents --> pkg_cli_demo
   svc_agents --> pkg_subagent_inprocess
+  svc_agents --> pkg_tui_demo
   svc_approval --> pkg_tool_bash
   svc_approval --> pkg_tools
   svc_bash --> pkg_hooks_claude
   svc_bash --> pkg_hooks_codex
   svc_bash --> pkg_tool_bash
-  svc_bash --> pkg_tool_pwsh
-  svc_bashEnv --> pkg_tool_bash
-  svc_bashEnv --> pkg_tool_pwsh
   svc_clientModuleHost --> pkg_hmr
   svc_codeRuntime --> pkg_tools
+  svc_commands --> pkg_tui
   svc_compact --> pkg_compact_basic
-  svc_credentials --> pkg_apiproxy
-  svc_credentials --> pkg_llm_deepseek
-  svc_credentials --> pkg_llm_pi_ai
   svc_directoryPicker --> pkg_apiproxy
   svc_fs --> pkg_tool_fs
   svc_httpServer --> pkg_connection
@@ -305,29 +285,26 @@ flowchart LR
   svc_sessionProjections --> pkg_tool_todo
   svc_sessionQuery --> pkg_session_reference
   svc_sessionQuery --> pkg_tool_session_query
+  svc_sessionReferences --> pkg_tui
   svc_sessions --> pkg_agent
   svc_sessions --> pkg_agent_loop
+  svc_sessions --> pkg_cli_demo
   svc_sessions --> pkg_invariants
   svc_sessions --> pkg_session_persistence
   svc_sessions --> pkg_session_query
   svc_sessions --> pkg_session_query_sqlite
   svc_sessions --> pkg_subagent_inprocess
-  svc_settings --> pkg_apiproxy
-  svc_settings --> pkg_llm_deepseek
-  svc_settings --> pkg_llm_pi_ai
   svc_skills --> pkg_tool_skill
   svc_spillStore --> pkg_spill_policy
   svc_storage --> pkg_storage_domain
   svc_storageDomain --> pkg_workspace
   svc_subagents --> pkg_tool_ralph
   svc_subagents --> pkg_tool_subagent
-  svc_subagents --> pkg_tool_subagent_control
   svc_subprocess --> pkg_bash_local
   svc_subprocess --> pkg_bash_sandbox
   svc_subprocess --> pkg_lsp_local
+  svc_subprocess --> pkg_pty_local
   svc_subprocess --> pkg_subagent_acp
-  svc_subprocess --> pkg_subagent_claude_code
-  svc_subprocess --> pkg_subagent_codex
   svc_systemPrompt --> pkg_agent_loop
   svc_systemPrompt --> pkg_tool_fs
   svc_systemPrompt --> pkg_tool_pty
@@ -352,6 +329,7 @@ flowchart LR
   svc_typert --> pkg_api_gateway
   svc_typert --> pkg_typert_loader
   svc_userInteraction --> pkg_tool_ask_user
+  svc_userInteraction --> pkg_tui
   svc_web --> pkg_tool_web
   svc_workflows --> pkg_tool_ralph
   svc_workflows --> pkg_tool_workflow
@@ -364,34 +342,33 @@ flowchart LR
 | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compact-basic`](../packages/compact/compact-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. |
 | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements. |
 | `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
-| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
 | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
 | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
-| `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer. |
-| `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage. |
 | `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/telemetry/session-telemetry) | [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
 | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. |
 | `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. |
 | `ctx.workspace` | `core` | [`workspace`](../packages/workspace/workspace) | - | `apiproxy` | - | Owns WorkspaceId-branded records over the domain facility; stable sessionIds accounts drive Host RPC and GUI projections. |
 | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference), [`tool-session-query`](../packages/session-query/tool-session-query) | - | The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations, while the model consumer owns workspace authority and cursor-free rendering. |
-| `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
+| `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | [`tui`](../packages/ui/tui) | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
 | `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session-title/session-title) | [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session-title/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
 | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
-| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | - | [`tool-ask-user`](../packages/ui/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
+| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`tui`](../packages/ui/tui) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`tui`](../packages/ui/tui) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
-| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
+| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | [`tui`](../packages/ui/tui) | - | Plugins register direct human commands; TUI consumes the effective per-agent catalog without sending invocations to the model. |
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
-| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
-| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.tui` | `bundle` | [`tui`](../packages/ui/tui) | - | - | - | One TUI front door provides a FIFO overlay host; injected plugins receive caller-fiber ownership without access to pi-tui or terminal lifecycle state. |
+| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tui-demo`](../packages/examples/tui-demo) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
-| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation. |
-| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pwsh-local`](../packages/bash/pwsh-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them. |
-| `ctx.bashEnv` | `core` | [`bash-env`](../packages/bash/bash-env) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh) | - | Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace. |
+| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp) | - | The bash executors, PTY shell backend, LSP host, and ACP subagent backend spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
+| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them. |
+| `ctx.bashEnv` | `core` | [`tool-bash`](../packages/bash/tool-bash) | - | - | - | Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace. |
 | `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface. |
 | `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local) | - | Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement. |
 | `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/bash/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`pty-local`](../packages/pty/pty-local) | - | The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots. |
@@ -400,7 +377,7 @@ flowchart LR
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
-| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
+| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route. |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
 | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a875c190fe..b8a49a7ba2 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -284,30 +284,6 @@ export interface Config {
 
 Source: [`packages/client/hmr/src/index.ts:29`](../packages/client/hmr/src/index.ts)
 
-## `@deepseek-ai/dsh-code-runtime-subprocess`
-
-Requires: `subprocess`
-
-```ts config-catalog
-/** Runtime configuration; every execution and bridge bound is deployment-tunable. */
-export interface Config {
-  /** Worker measured event-loop busy-time budget. */
-  computeMs?: number
-  /** Host-observed wall-clock ceiling. */
-  maxWallMs?: number
-  /** Combined serialized outer logs/value/diagnostic cap. */
-  maxOutputBytes?: number
-  /** Worker old-generation heap cap in MiB. */
-  maxOldGenerationSizeMb?: number
-  /** Largest decoded bridge frame, including binding traffic. */
-  maxFrameBytes?: number
-  /** Process-tree TERM-to-KILL grace. */
-  killGraceMs?: number
-}
-```
-
-Source: [`packages/code-runtime/code-runtime-subprocess/src/index.ts:27`](../packages/code-runtime/code-runtime-subprocess/src/index.ts)
-
 ## `@deepseek-ai/dsh-code-runtime-worker`
 
 ```ts config-catalog
@@ -341,7 +317,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:30`](../packages/code-runtime/code-runtime-worker/src/index.ts)
+Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:25`](../packages/code-runtime/code-runtime-worker/src/index.ts)
 
 ## `@deepseek-ai/dsh-compact-basic`
 
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index cfa3762222..50e219a2c6 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: c68a2f77059f62b273c536987b321017f2a71bbb
-subprocess.zh.md: 061c681430ba1f011b4ed9e5c4d9fc8595fe6738
+subprocess.md: 895bfe3d763853a86648e8aaab8b091a26006255
+subprocess.zh.md: 044e924674ecf5dd8f8a1c71fe39653e7525dfb0
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index a258ff4767..023b122218 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -2,13 +2,13 @@
 
 English | [中文](subprocess.zh.md)
 
-The subprocess seam is split across interface ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and implementation ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its consumers are other capability seams and out-of-process backends: the [bash executor family](bash.md) uses collected batch output, the LSP and Code Runtime hosts use raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
+The subprocess seam is split across interface ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and implementation ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its consumers are other capability seams and out-of-process backends: the [bash executor family](bash.md) uses collected batch output, LSP uses raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
 
 Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) and [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
 
-## Execution-world coordinates
+## Executable lookup
 
-One provider's `cwd`, executable paths, ordinary processes, and terminal sessions inhabit the same path and process namespace as the mounted filesystem provider. `resolveExecutable(command, env?, signal?)` verifies absolute executable paths or resolves bare names through the provider's scrubbed `PATH` plus deliberate overrides.
+One provider's spawn working directories, executable paths, ordinary processes, and terminal sessions inhabit the same path and process namespace as the mounted filesystem provider. `resolveExecutable(command, env?, signal?)` verifies absolute executable paths or resolves bare names through the provider's scrubbed `PATH` plus deliberate overrides.
 
 ## Managed environment namespace and captured output
 
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 061c681430..044e924674 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -2,13 +2,13 @@
 
 [English](subprocess.md) | 中文
 
-进程管理器 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式的批量输出，LSP 与 Code Runtime 主机使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用管道化 ndjson 加 inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
+进程管理器 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式的批量输出，LSP 使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用管道化 ndjson 加 inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
 
 源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) 与 [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
 
-## 执行世界坐标
+## 可执行文件查找
 
-一个提供方的 `cwd`、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。
+一个提供方的 spawn 工作目录、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。
 
 ## 受管环境命名空间与捕获的输出
 
diff --git a/knip.json b/knip.json
index 413b740578..ede8b2c738 100644
--- a/knip.json
+++ b/knip.json
@@ -383,17 +383,6 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/code-runtime/code-runtime-subprocess": {
-      "entry": [
-        "src/runner.ts",
-        "tests/**/*.spec.ts",
-        "tests/**/*.e2e.ts"
-      ],
-      "project": [
-        "src/**/*.ts",
-        "tests/**/*.ts"
-      ]
-    },
     "packages/llm/llm-deepseek": {
       "entry": [
         "tests/**/*.spec.ts",
diff --git a/package.json b/package.json
index 2b4971a6b7..423cbf813c 100644
--- a/package.json
+++ b/package.json
@@ -112,8 +112,6 @@
     "gen-module-graph": "tsx scripts/gen-module-graph.ts",
     "gen-scoped-events": "tsx scripts/gen-scoped-events.ts",
     "verify-scoped-events": "tsx scripts/gen-scoped-events.ts --check",
-    "gen-code-runtime-runner": "tsx scripts/gen-code-runtime-runner.ts",
-    "verify-code-runtime-runner": "tsx scripts/gen-code-runtime-runner.ts --check",
     "verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
     "constraints": "tsx scripts/check-workspace-constraints.ts",
     "doc-sync": "tsx scripts/run-gates.ts doc-sync",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index eaa48fac05..1484411cca 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: b498c146202f1a69d89805fa3e8966c4d0735d6c
-README.zh.md: 2eefc73ed0ea22aae5fde93284c25c5d03fe86c4
+README.md: 3f467641bbc9eae14a94aa2d3bff0402116a9d3f
+README.zh.md: faa879f3b5b62527c1d76ab3aff6a737f876ce4d
diff --git a/packages/README.md b/packages/README.md
index 7d591605ef..229feae568 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -19,7 +19,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: runtime seam plus local worker and subprocess backends | Product — stable surface |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
 | [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index a9201d08a9..bed31b657c 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -19,7 +19,7 @@
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：运行时 seam、本地 worker 后端及进程管理后端 | 产品：稳定表面 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：用于模型编写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
 | [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
 | [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
 | [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |
diff --git a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
index 2207389c97..cbe0d0ac55 100644
--- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
+++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
@@ -6,7 +6,6 @@
  */
 
 import { inspect } from 'node:util'
-import type { CodeJsonValue } from '@deepseek-ai/dsh-code-runtime'
 import type { DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'
 import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
 import { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
@@ -311,7 +310,6 @@ export function wireReplies(port: BootstrapPort, pending: Map<number, PendingCal
  * @param pending - the id-keyed map each posted call parks its handles in.
  * @param nextId - the shared mutable id counter (worker-issued correlation ids).
  * @param errorClasses - per-namespace constructors shared with program globals.
- * @param maxFrameBytes - optional serialized transport cap checked before posting.
  * @returns one namespace object per declaration, in declaration order.
  */
 export function makeNamespaces(
@@ -320,7 +318,6 @@ export function makeNamespaces(
   pending: Map<number, PendingCall>,
   nextId: { value: number },
   errorClasses: Map<string, BindingErrorConstructor> = makeBindingErrorClasses(data),
-  maxFrameBytes?: number,
 ): Record<string, unknown>[] {
   return data.namespaces.map(({ global, names }) => {
     const errorClass = errorClasses.get(global)
@@ -338,11 +335,6 @@ export function makeNamespaces(
           if (detached === undefined) {
             return Promise.reject(bindingFailure(errorClass, name, 'binding arguments must be lossless JSON'))
           }
-          const call = { type: 'call' as const, id: nextId.value, global, name, args: encodeWorkerJson(detached) }
-          if (maxFrameBytes !== undefined
-            && jsonValueBytesUpTo(call as unknown as CodeJsonValue, maxFrameBytes) === undefined) {
-            return Promise.reject(bindingFailure(errorClass, name, 'binding arguments exceed maxFrameBytes'))
-          }
           return new Promise((resolve, reject) => {
             const id = nextId.value++
             pending.set(id, {
@@ -352,7 +344,7 @@ export function makeNamespaces(
               },
             })
             try {
-              port.postMessage(call)
+              port.postMessage({ type: 'call', id, global, name, args: encodeWorkerJson(detached) })
             } catch (error: unknown) {
               pending.delete(id)
               const message = `binding arguments must be structured-cloneable: ${error instanceof CapturedError ? error.message : String(error)}`
@@ -372,14 +364,12 @@ export function makeNamespaces(
  * @param port - host message port or test double.
  * @param data - the boot payload the host sent.
  * @param streams - stdout/stderr objects captured as program logs.
- * @param maxFrameBytes - optional serialized transport cap checked before posting.
  * @returns after posting the done message.
  */
 export async function runWorkerMain(
   port: BootstrapPort,
   data: WorkerBootData,
   streams: { stdout: PatchableStream; stderr: PatchableStream },
-  maxFrameBytes?: number,
 ): Promise<void> {
   const logs = new LogBuffer(
     data.maxOutputBytes,
@@ -394,7 +384,7 @@ export async function runWorkerMain(
 
   const nextId = { value: 1 }
   const errorClasses = makeBindingErrorClasses(data)
-  const namespaces = makeNamespaces(data, port, pending, nextId, errorClasses, maxFrameBytes)
+  const namespaces = makeNamespaces(data, port, pending, nextId, errorClasses)
   const errorClassParameters: string[] = []
   const errorClassValues: BindingErrorConstructor[] = []
   for (const namespace of data.namespaces) {
@@ -430,8 +420,5 @@ export async function runWorkerMain(
       ...prepareException(error, logs.remainingOutputBytes(), data.maxOutputBytes),
     }
   }
-  port.postMessage(maxFrameBytes !== undefined
-    && jsonValueBytesUpTo(done as unknown as CodeJsonValue, maxFrameBytes) === undefined
-    ? { type: 'output-limit' }
-    : done)
+  port.postMessage(done)
 }
diff --git a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts b/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
deleted file mode 100644
index 47bfacfe91..0000000000
--- a/packages/code-runtime/code-runtime-worker/src/runtime-host.ts
+++ /dev/null
@@ -1,251 +0,0 @@
-/** Shared host mechanics for local and subprocess-hosted TypeScript worker runtimes. */
-
-import { stripTypeScriptTypes } from 'node:module'
-import type { Readable } from 'node:stream'
-import type {
-  CodeBindingNamespace,
-  CodeJsonValue,
-  CodeRunFailure,
-  CodeRunRequest,
-  CodeRunResult,
-} from '@deepseek-ai/dsh-code-runtime'
-import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
-import { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
-import type { WorkerJsonWire } from './worker-json.ts'
-
-/** Smallest cap that can represent an empty log array and failure message. */
-export const MIN_RUNTIME_OUTPUT_BYTES = 4
-
-/**
- * Resolve after a worker pipe emits queued data or closes during termination.
- * @param stream - captured worker or child-process pipe.
- * @returns after no more queued bytes can arrive.
- */
-export function waitForRuntimePipeDrain(stream: Readable): Promise<void> {
-  if (stream.readableEnded || stream.destroyed) return Promise.resolve()
-  return new Promise((resolve) => {
-    const done = (): void => {
-      stream.off('end', done)
-      stream.off('close', done)
-      stream.off('error', done)
-      resolve()
-    }
-    stream.once('end', done)
-    stream.once('close', done)
-    stream.once('error', done)
-    /* v8 ignore next -- termination can win the adjacent listener-registration race. */
-    if (stream.readableEnded || stream.destroyed) done()
-  })
-}
-
-const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
-const RESERVED_WORDS = new Set([
-  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
-  'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in',
-  'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
-  'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface', 'package',
-  'private', 'protected', 'public', 'arguments', 'eval',
-])
-const RESERVED_ERROR_PROPERTIES = new Set(['name', 'message', 'stack'])
-const STRIP_WRAP = { prefix: 'async function __dsh_program__() {\n', suffix: '\n}' } as const
-
-/** One validated binding call received from an isolated worker. */
-export interface RuntimeBindingCall {
-  /** Correlation id supplied by the isolated worker. */
-  readonly id: number
-  /** Injected namespace global. */
-  readonly global: string
-  /** Declared namespace function. */
-  readonly name: string
-  /** Untrusted lossless-JSON wire payload. */
-  readonly args: unknown
-}
-
-/** One host reply to an isolated worker binding call. */
-export type RuntimeBindingReply =
-  | { readonly type: 'reply'; readonly id: number; readonly ok: true; readonly value: WorkerJsonWire }
-  | { readonly type: 'reply'; readonly id: number; readonly ok: false; readonly message: string }
-
-/**
- * Render an unknown thrown value without assuming it is an Error.
- * @param error - thrown or rejected value.
- * @returns the caller-facing diagnostic text.
- */
-export function runtimeErrorMessage(error: unknown): string {
-  try {
-    return error instanceof Error ? error.message : String(error)
-  } catch {
-    return 'binding rejected with an unrenderable value'
-  }
-}
-
-/**
- * Strip erasable TypeScript while preserving the program's body coordinates.
- * @param program - model-written async-function body.
- * @returns JavaScript source with the wrapper removed.
- */
-export function stripRuntimeProgram(program: string): string {
-  const stripped = stripTypeScriptTypes(STRIP_WRAP.prefix + program + STRIP_WRAP.suffix)
-  return stripped.slice(STRIP_WRAP.prefix.length, stripped.length - STRIP_WRAP.suffix.length)
-}
-
-/**
- * Validate binding globals and typed-error declarations shared by worker runtimes.
- * @param request - code-runtime request carrying the namespaces.
- * @param implementationName - package name used in seam-misuse diagnostics.
- * @returns namespaces indexed by their injected global.
- */
-export function validateRuntimeBindings(
-  request: CodeRunRequest,
-  implementationName: string,
-): Map<string, CodeBindingNamespace> {
-  const bindings = new Map<string, CodeBindingNamespace>()
-  for (const namespace of request.bindings) {
-    if (!IDENTIFIER.test(namespace.global) || RESERVED_WORDS.has(namespace.global)) {
-      throw new Error(`${implementationName}: binding global ${JSON.stringify(namespace.global)} is not a usable identifier`)
-    }
-    if (namespace.global === 'console' || bindings.has(namespace.global)) {
-      throw new Error(`${implementationName}: duplicate binding global ${JSON.stringify(namespace.global)}`)
-    }
-    bindings.set(namespace.global, namespace)
-  }
-
-  const errorClassNames = new Set<string>()
-  for (const namespace of request.bindings) {
-    const descriptor = namespace.errorClass
-    if (descriptor === undefined) continue
-    if (!IDENTIFIER.test(descriptor.name) || RESERVED_WORDS.has(descriptor.name)) {
-      throw new Error(`${implementationName}: binding error class ${JSON.stringify(descriptor.name)} is not a usable identifier`)
-    }
-    if (descriptor.name === 'console' || bindings.has(descriptor.name) || errorClassNames.has(descriptor.name)) {
-      throw new Error(`${implementationName}: duplicate injected global ${JSON.stringify(descriptor.name)}`)
-    }
-    if (descriptor.memberNameProperty.length === 0 || RESERVED_ERROR_PROPERTIES.has(descriptor.memberNameProperty)) {
-      throw new Error(`${implementationName}: binding error member property ${JSON.stringify(descriptor.memberNameProperty)} is not usable`)
-    }
-    errorClassNames.add(descriptor.name)
-  }
-  return bindings
-}
-
-/**
- * Resolve one untrusted worker call through a declared host binding.
- * @param call - parsed call envelope from the isolated worker.
- * @param bindings - namespaces returned by {@link validateRuntimeBindings}.
- * @returns a lossless-JSON success or stable rejection reply.
- */
-export async function invokeRuntimeBinding(
-  call: RuntimeBindingCall,
-  bindings: ReadonlyMap<string, CodeBindingNamespace>,
-): Promise<RuntimeBindingReply> {
-  const functions = bindings.get(call.global)?.functions
-  const fn = functions !== undefined && Object.hasOwn(functions, call.name) ? functions[call.name] : undefined
-  if (typeof fn !== 'function') {
-    return { type: 'reply', id: call.id, ok: false, message: `unknown binding ${JSON.stringify(`${call.global}.${call.name}`)}` }
-  }
-  const args = decodeWorkerJson(call.args)
-  if (args === undefined) {
-    return { type: 'reply', id: call.id, ok: false, message: 'binding arguments must be lossless JSON' }
-  }
-  try {
-    const resolved = await fn(args)
-    let value: CodeJsonValue | undefined
-    try {
-      value = snapshotCodeJsonValue(resolved)
-    } catch {
-      value = undefined
-    }
-    if (value === undefined) {
-      return { type: 'reply', id: call.id, ok: false, message: 'binding resolution must be lossless JSON' }
-    }
-    return { type: 'reply', id: call.id, ok: true, value: encodeWorkerJson(value) }
-  } catch (error: unknown) {
-    return { type: 'reply', id: call.id, ok: false, message: runtimeErrorMessage(error) }
-  }
-}
-
-/** One run's combined outer-output ledger; binding values never enter it. */
-export class RuntimeOutputLedger {
-  private bytes = 2
-  private entries = 0
-
-  /** @param maxBytes - hard cap for logs plus completion or failure payload. */
-  constructor(private readonly maxBytes: number) {}
-
-  /**
-   * Admit one exact log entry.
-   * @param text - candidate log entry.
-   * @param sink - ordered retained log list.
-   * @returns false when the hard cap was crossed.
-   */
-  admit(text: string, sink: string[]): boolean {
-    const separatorBytes = this.entries > 0 ? 1 : 0
-    const stringBytes = jsonStringBytesUpTo(text, this.maxBytes - this.bytes - separatorBytes)
-    if (stringBytes === undefined) return false
-    this.bytes += stringBytes + separatorBytes
-    this.entries += 1
-    sink.push(text)
-    return true
-  }
-
-  /**
-   * Finalize a successful completion against the combined cap.
-   * @param logs - retained ordered logs.
-   * @param value - optional lossless-JSON completion.
-   * @returns the completion or output-limit result.
-   */
-  success(logs: string[], value?: CodeJsonValue): CodeRunResult {
-    if (value !== undefined && jsonValueBytesUpTo(value, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
-    return { logs, ...value !== undefined ? { value } : {} }
-  }
-
-  /**
-   * Finalize one failure diagnostic against the combined cap.
-   * @param logs - retained ordered logs.
-   * @param error - structured runtime failure.
-   * @returns the failure or output-limit result.
-   */
-  failure(logs: string[], error: CodeRunFailure): CodeRunResult {
-    if (jsonStringBytesUpTo(error.message, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
-    return { logs, error }
-  }
-
-  /**
-   * Build an explicit output-limit failure with a fitting log prefix.
-   * @param logs - ordered logs observed before the limit.
-   * @returns bounded output-limit result.
-   */
-  limit(logs: string[]): CodeRunResult {
-    const fullMessage = `outer output exceeded ${this.maxBytes} bytes`
-    const messageBytes = fullMessage.length + 2
-    const retained: string[] = []
-    let retainedBytes = 2
-    const logBudget = this.maxBytes - messageBytes
-    for (const text of logs) {
-      const separatorBytes = retained.length > 0 ? 1 : 0
-      const availableBytes = logBudget - retainedBytes - separatorBytes
-      const stringBytes = jsonStringBytesUpTo(text, availableBytes)
-      if (stringBytes !== undefined) {
-        retained.push(text)
-        retainedBytes += stringBytes + separatorBytes
-        continue
-      }
-      const prefix = truncateJsonStringBytes(text, availableBytes)
-      if (prefix.length > 0) {
-        const prefixBytes = jsonStringBytesUpTo(prefix, availableBytes)
-        /* v8 ignore next -- truncateJsonStringBytes guarantees the same bound. */
-        if (prefixBytes === undefined) throw new Error('output ledger produced an oversized log prefix')
-        retained.push(prefix)
-        retainedBytes += prefixBytes + separatorBytes
-      }
-      break
-    }
-    const message = truncateJsonStringBytes(fullMessage, this.maxBytes - retainedBytes)
-    return { logs: retained, error: { kind: 'output-limit', message } }
-  }
-}
-
-export { decodeWorkerJson, encodeWorkerJson, snapshotCodeJsonValue } from './worker-json.ts'
-export { jsonStringBytesUpTo, jsonValueBytesUpTo } from './output-json.ts'
-export { runWorkerMain } from './bootstrap.ts'
-export type { WorkerJsonWire } from './worker-json.ts'
diff --git a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
index 247501df29..a2aac6d9c2 100644
--- a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
@@ -286,23 +286,6 @@ describe('makeNamespaces', () => {
     expect(nextId.value).toBe(1)
   })
 
-  it('rejects an oversized transport frame before posting or allocating a call id', async () => {
-    const port = new FakePort()
-    const pending = new Map<number, PendingCall>()
-    const nextId = { value: 1 }
-    const data = { namespaces: [toolNamespace(['x'])] }
-    const [tools] = makeNamespaces(
-      data, port, pending, nextId, makeBindingErrorClasses(data), 64,
-    ) as [Record<string, (args: unknown) => Promise<unknown>>]
-
-    await expect(tools.x?.({ text: 'x'.repeat(64) })).rejects.toMatchObject({
-      name: 'ToolCallError', toolName: 'x', message: 'binding arguments exceed maxFrameBytes',
-    })
-    expect(port.sent).toEqual([])
-    expect(pending.size).toBe(0)
-    expect(nextId.value).toBe(1)
-  })
-
   it('uses ordinary Error for non-tools namespace failures', async () => {
     const deniedPort = new FakePort()
     deniedPort.respond = message => message.type === 'call'
@@ -360,16 +343,6 @@ describe('runWorkerMain', () => {
     })
   })
 
-  it('reports output-limit before posting a completion that expands past the transport cap', async () => {
-    const port = new FakePort()
-    await runWorkerMain(port, {
-      maxOutputBytes: 1_000,
-      code: 'return Array.from({ length: 100 }, () => [])',
-      namespaces: [],
-    }, fakeStreams(), 100)
-    expect(port.sent.at(-1)).toEqual({ type: 'output-limit' })
-  })
-
   it('reports a thrown program error on the done message', async () => {
     const port = new FakePort()
     await runWorkerMain(port, { ...BOOT, code: 'throw new Error("boom")', namespaces: [] }, fakeStreams())
diff --git a/packages/code-runtime/code-runtime-worker/tsconfig.json b/packages/code-runtime/code-runtime-worker/tsconfig.json
index 340e68e848..555b3d161e 100644
--- a/packages/code-runtime/code-runtime-worker/tsconfig.json
+++ b/packages/code-runtime/code-runtime-worker/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../core/session"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/packages/code-runtime/code-runtime-worker/tsdown.config.ts b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
index dac6f12a65..1c40637722 100644
--- a/packages/code-runtime/code-runtime-worker/tsdown.config.ts
+++ b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
@@ -1,10 +1,9 @@
 import { defineConfig } from 'tsdown'
 
 /**
- * Build the plugin, reusable runtime host, and worker as separate bundles. The
- * sibling `worker.cjs` is loaded by file and must be CommonJS for pkg's VFS
- * Worker hook. Separate builds inline shared implementation instead of
- * emitting an unlisted chunk outside the exact `files` whitelist.
+ * Build the index and worker as separate single-entry bundles. The sibling `worker.cjs` is loaded
+ * by file and must be CommonJS for pkg's VFS Worker hook. A multi-entry build emits an unlisted
+ * shared chunk omitted by the package's exact `files` whitelist; separate builds inline it.
  */
 export default defineConfig([
   {
@@ -17,16 +16,6 @@ export default defineConfig([
     dts: false,
     clean: false,
   },
-  {
-    entry: ['lib/types/runtime-host.js'],
-    outDir: 'lib',
-    format: ['esm'],
-    platform: 'node',
-    target: 'es2024',
-    fixedExtension: false,
-    dts: false,
-    clean: false,
-  },
   {
     entry: ['lib/types/worker.js'],
     outDir: 'lib',
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index d58508cd08..bb1c20d00a 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -34,5 +34,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
 - **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)).
-- **No runtime claims a hard security boundary** — both shipped implementations use fresh worker threads; the subprocess backend can place them inside a stronger execution world, but no runtime reports `'container'` today.
-- **Intermediate binding values are implementation-bounded** — the direct worker backend has no per-binding byte cap; the subprocess backend bounds each bridge frame, but repeated or concurrent binding traffic remains subject to process memory.
+- **Only the worker-thread backend ships** — `'process'`/`'container'` are declared well-known `isolation` values with no implementation; a hard security boundary awaits a container backend.
+- **Intermediate binding values have no byte cap** — implementations remain subject to structured-clone cost and process memory, while a provider or executor may already have imposed its own acquisition bound.
diff --git a/packages/code-runtime/code-runtime/tests/contract.ts b/packages/code-runtime/code-runtime/tests/contract.ts
deleted file mode 100644
index 8fee76f68a..0000000000
--- a/packages/code-runtime/code-runtime/tests/contract.ts
+++ /dev/null
@@ -1,853 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import type {
-  CodeBindingFunction,
-  CodeBindingNamespace,
-  CodeRunResult,
-  CodeRuntime,
-} from '@deepseek-ai/dsh-code-runtime'
-
-interface WorkerCodeRuntimeContractConfig {
-  computeMs?: number
-  maxWallMs?: number
-  maxOutputBytes?: number
-  maxOldGenerationSizeMb?: number
-}
-
-interface WorkerCodeRuntimeContractHarness {
-  runtime: CodeRuntime
-  dispose: () => Promise<void>
-}
-
-type WorkerCodeRuntimeContractSetup = (
-  config?: WorkerCodeRuntimeContractConfig,
-) => Promise<WorkerCodeRuntimeContractHarness>
-
-/** Convenience: one namespace `tools` with the given functions. */
-export function workerRuntimeTools(
-  functions: Record<string, (args: unknown) => Promise<unknown>>,
-): CodeBindingNamespace[] {
-  return [{
-    global: 'tools',
-    functions: functions as Record<string, CodeBindingFunction>,
-    errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
-  }]
-}
-
-/** Run behavior shared by the direct and subprocess-hosted worker runtimes. */
-export function runWorkerCodeRuntimeContract(
-  label: string,
-  setup: WorkerCodeRuntimeContractSetup,
-): void {
-  describe(`${label} — programs and bindings (real workers)`, () => {
-    it('registers with the seam descriptors', async () => {
-      const { runtime } = await setup()
-      expect(runtime.language).toBe('typescript')
-      expect(runtime.isolation).toBe('worker-thread')
-    })
-
-    it('runs TypeScript (erasable syntax), captures output in order, returns the value', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          interface Point { x: number; y: number }
-          const p: Point = { x: 1, y: 2 } as Point;
-          console.log('point', p);
-          process.stdout.write('raw-out\\n');
-          console.warn('careful');
-          return p.x + p.y;
-        `,
-        bindings: [],
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe(3)
-      expect(result.logs).toEqual(['point { x: 1, y: 2 }', 'raw-out\n', 'careful'])
-    })
-
-    it('bridges binding calls both ways and rejects the program-side call on a host rejection', async () => {
-      const { runtime } = await setup()
-      const calls: unknown[] = []
-      const result = await runtime.run({
-        program: `
-          const first = await tools.echo({ n: 1 });
-          let caught = {};
-          try { await tools.fail({}) } catch (error) { caught = { isTyped: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message } }
-          let caughtRaw = {};
-          try { await tools.failRaw({}) } catch (error) { caughtRaw = { name: error.name, toolName: error.toolName, message: error.message } }
-          return { first, caught, caughtRaw };
-        `,
-        bindings: workerRuntimeTools({
-          echo: async (args) => { calls.push(args); return { echoed: args } },
-          fail: async () => { throw new Error('nope') },
-          // A non-Error throw: the host renders it, the program still catches.
-          failRaw: async () => { throw 'raw-nope' },
-        }),
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toEqual({
-        first: { echoed: { n: 1 } },
-        caught: { isTyped: true, name: 'ToolCallError', toolName: 'fail', message: 'nope' },
-        caughtRaw: { name: 'ToolCallError', toolName: 'failRaw', message: 'raw-nope' },
-      })
-      expect(calls).toEqual([{ n: 1 }])
-    })
-
-    it('materializes a typed rejection from a generic namespace descriptor', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          try { await helpers.fail({}) } catch (error) {
-            return {
-              isTyped: error instanceof HelperCallError,
-              name: error.name,
-              helperName: error.helperName,
-              message: error.message,
-            };
-          }
-        `,
-        bindings: [{
-          global: 'helpers',
-          functions: { fail: async () => { throw new Error('nope') } },
-          errorClass: { name: 'HelperCallError', memberNameProperty: 'helperName' },
-        }],
-      })
-      expect(result.value).toEqual({
-        isTyped: true,
-        name: 'HelperCallError',
-        helperName: 'fail',
-        message: 'nope',
-      })
-    })
-
-    it('bridges a deeply nested lossless JSON argument, resolution, and completion', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          let value = 'leaf';
-          for (let depth = 0; depth < 3_000; depth++) value = [value];
-          return await tools.echo(value);
-        `,
-        bindings: workerRuntimeTools({ echo: async args => args }),
-      })
-
-      expect(result.error).toBeUndefined()
-      let cursor = result.value
-      for (let depth = 0; depth < 3_000; depth++) {
-        expect(Array.isArray(cursor)).toBe(true)
-        cursor = Array.isArray(cursor) ? cursor[0] : undefined
-      }
-      expect(cursor).toBe('leaf')
-    }, 15_000)
-
-    it('reports non-erasable syntax as an exception without spawning a worker', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'enum E { A }\nreturn 1', bindings: [] })
-      expect(result.error?.kind).toBe('exception')
-      expect(result.error?.message).toMatch(/enum|strip/i)
-    })
-
-    it('reports a runtime throw as an exception with the message', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'throw new Error("kaboom")', bindings: [] })
-      expect(result.error?.kind).toBe('exception')
-      expect(result.error?.message).toContain('kaboom')
-    })
-
-    it('gives the program an EMPTY environment', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'return JSON.stringify(process.env)', bindings: [] })
-      expect(result.value).toBe('{}')
-    })
-
-    it('rejects a non-lossless completion instead of replacing it with rendered text', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'return { f: () => 1 }', bindings: [] })
-      expect(result.value).toBeUndefined()
-      expect(result.error).toEqual({ kind: 'invalid-output', message: 'program completion must be lossless JSON' })
-    })
-
-    it('completes a program that returns nothing with no value at all', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'const x = 1', bindings: [] })
-      expect(result.error).toBeUndefined()
-      expect('value' in result).toBe(false)
-    })
-
-    it('keeps logs streamed before a failure', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: 'console.log("before"); throw new Error("after-log")',
-        bindings: [],
-      })
-      expect(result.error?.kind).toBe('exception')
-      expect(result.logs).toContain('before')
-    })
-  })
-
-  describe(`${label} — budgets and containment (real workers)`, () => {
-    it('ends a hot loop at the compute budget — including behind a pending decoy dispatch', async () => {
-      const { runtime } = await setup({ computeMs: 300, maxWallMs: 30_000 })
-      const result = await runtime.run({
-        // The decoy: fire a call at a never-resolving binding WITHOUT awaiting,
-        // then spin. Host-side pending-call bookkeeping would pause a naive
-        // budget here; measured busy time cannot be fooled.
-        program: 'void tools.slow({}); for (;;) {}',
-        bindings: workerRuntimeTools({ slow: () => new Promise(() => {}) }),
-      })
-      expect(result.error?.kind).toBe('timeout')
-      expect(result.error?.message).toContain('compute budget')
-    }, 15_000)
-
-    it('does not charge time spent awaiting a slow binding against the compute budget', async () => {
-      // Keep the binding delay above the compute allowance while leaving enough
-      // headroom for worker bootstrap on loaded CI hosts.
-      const { runtime } = await setup({ computeMs: 1_000, maxWallMs: 30_000 })
-      const result = await runtime.run({
-        program: 'return await tools.slow({})',
-        bindings: workerRuntimeTools({ slow: () => new Promise(resolve => setTimeout(() => { resolve('slow-done') }, 1_500)) }),
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe('slow-done')
-    }, 15_000)
-
-    it('ends an idle-forever run at the wall-clock ceiling', async () => {
-      const { runtime } = await setup({ computeMs: 30_000, maxWallMs: 400 })
-      const result = await runtime.run({
-        program: 'await tools.never({}); return 1',
-        bindings: workerRuntimeTools({ never: () => new Promise(() => {}) }),
-      })
-      expect(result.error?.kind).toBe('timeout')
-      expect(result.error?.message).toContain('wall-clock ceiling')
-    }, 15_000)
-
-    it('reports an abort mid-run and stops the worker', async () => {
-      const { runtime } = await setup()
-      const controller = new AbortController()
-      setTimeout(() => { controller.abort('user-cancel') }, 150)
-      const result = await runtime.run({ program: 'for (;;) {}', bindings: [], signal: controller.signal })
-      expect(result.error).toEqual({ kind: 'abort', message: 'user-cancel' })
-    }, 15_000)
-
-    it('reports a pre-aborted signal without spawning', async () => {
-      const { runtime } = await setup()
-      const controller = new AbortController()
-      controller.abort('too-late')
-      const result = await runtime.run({ program: 'return 1', bindings: [], signal: controller.signal })
-      expect(result.error).toEqual({ kind: 'abort', message: 'too-late' })
-    })
-
-    it('applies the outer-output cap to failures before worker startup', async () => {
-      const capped = await setup({ maxOutputBytes: 64 })
-      const controller = new AbortController()
-      controller.abort('A'.repeat(1_000))
-      const aborted = await capped.runtime.run({ program: 'return 1', bindings: [], signal: controller.signal })
-      expect(aborted).toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' } })
-
-      const minimal = await setup({ maxOutputBytes: 4 })
-      const invalid = await minimal.runtime.run({ program: 'enum E { A }\nreturn 1', bindings: [] })
-      expect(invalid.error?.kind).toBe('output-limit')
-      expect(Buffer.byteLength(JSON.stringify(invalid.logs), 'utf8') + Buffer.byteLength(JSON.stringify(invalid.error?.message), 'utf8')).toBeLessThanOrEqual(4)
-    })
-
-    it('drops a binding resolution that lands after the run settled', async () => {
-      const { runtime } = await setup()
-      const controller = new AbortController()
-      let replyDelivered!: Promise<void>
-      const result = await runtime.run({
-        program: 'void tools.late({}); for (;;) {}',
-        bindings: workerRuntimeTools({
-          // Anchored on invocation: abort 100ms after the call reaches the
-          // host, resolve 400ms after — by then the run has settled, so the
-          // resolution's reply hits the post-settlement drop.
-          late: () => new Promise((resolve) => {
-            setTimeout(() => { controller.abort('cancel-now') }, 100)
-            replyDelivered = new Promise(done => setTimeout(() => { resolve('too-late'); done() }, 400))
-          }),
-        }),
-        signal: controller.signal,
-      })
-      expect(result.error).toEqual({ kind: 'abort', message: 'cancel-now' })
-      // Let the late resolution actually fire so its reply executes instead of
-      // being cancelled with the test.
-      await replyDelivered
-    }, 15_000)
-
-    it('contains an OOM under resourceLimits as worker-exit, host process healthy', async () => {
-      const { runtime } = await setup({ maxOldGenerationSizeMb: 32 })
-      const result = await runtime.run({
-        program: 'const hog = []; for (;;) hog.push(new Array(1e6).fill(1));',
-        bindings: [],
-      })
-      expect(result.error?.kind).toBe('worker-exit')
-      // And the host is fine: run something else.
-      const after = await runtime.run({ program: 'return "alive"', bindings: [] })
-      expect(after.value).toBe('alive')
-    }, 30_000)
-
-    it('reports a worker that exits before publishing a completion', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'process.exit(7)', bindings: [] })
-      expect(result).toEqual({
-        logs: [],
-        error: { kind: 'worker-exit', message: 'worker exited with code 7 before completing' },
-      })
-    })
-
-    it('fails runaway log output explicitly while retaining a bounded prefix', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 300 })
-      const result = await runtime.run({
-        program: 'for (let i = 0; i < 1000; i++) console.log("spam line", i); return 1',
-        bindings: [],
-      })
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 300 bytes' })
-      expect(result.value).toBeUndefined()
-      expect(result.logs.length).toBeGreaterThan(0)
-      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')).toBeLessThan(300)
-    })
-
-    it('retains a fitting prefix when one oversized log is the first output', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 96 })
-      const result = await runtime.run({
-        program: 'console.log(`start-${`😀"\\\\\\n`.repeat(100)}`); return null',
-        bindings: [],
-      })
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 96 bytes' })
-      expect(result.logs).toHaveLength(1)
-      expect(result.logs[0]?.startsWith('start-')).toBe(true)
-      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')
-        + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(96)
-    })
-
-    it('fails an oversized return value without substituting a string', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 64 })
-      const result = await runtime.run({ program: 'return "y".repeat(10_000)', bindings: [] })
-      expect(result.value).toBeUndefined()
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 64 bytes' })
-    })
-
-    it('uses UTF-8 serialized bytes at the exact completion boundary', async () => {
-      const exact = await setup({ maxOutputBytes: 7 })
-      const exactResult = await exact.runtime.run({ program: 'return "€"', bindings: [] })
-      // [] costs two bytes and JSON serialization of "€" costs five.
-      expect(exactResult).toEqual({ logs: [], value: '€' })
-
-      const over = await setup({ maxOutputBytes: 6 })
-      const overResult = await over.runtime.run({ program: 'return "€"', bindings: [] })
-      expect(overResult.error?.kind).toBe('output-limit')
-    })
-
-    it('accounts logs and completion in one exact combined ledger', async () => {
-      // JSON(["abc"]) is seven bytes and JSON("xy") is four.
-      const exact = await setup({ maxOutputBytes: 11 })
-      expect(await exact.runtime.run({ program: 'console.log("abc"); return "xy"', bindings: [] }))
-        .toEqual({ logs: ['abc'], value: 'xy' })
-
-      const over = await setup({ maxOutputBytes: 10 })
-      const result = await over.runtime.run({ program: 'console.log("abc"); return "xy"', bindings: [] })
-      expect(result.value).toBeUndefined()
-      expect(result.error?.kind).toBe('output-limit')
-      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8') + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(10)
-    })
-
-    it('accounts logs and exception diagnostics before the worker port boundary', async () => {
-      // JSON(["abc"]) is seven bytes and JSON("xy") is four.
-      const exact = await setup({ maxOutputBytes: 11 })
-      expect(await exact.runtime.run({ program: 'console.log("abc"); throw "xy"', bindings: [] }))
-        .toEqual({ logs: ['abc'], error: { kind: 'exception', message: 'xy' } })
-
-      const over = await setup({ maxOutputBytes: 10 })
-      const result = await over.runtime.run({ program: 'console.log("abc"); throw "xy"', bindings: [] })
-      expect(result.error?.kind).toBe('output-limit')
-      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')
-        + Buffer.byteLength(JSON.stringify(result.error?.message), 'utf8')).toBeLessThanOrEqual(10)
-    })
-
-    it('does not send a giant Error stack across the worker port', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 64 })
-      const result = await runtime.run({
-        program: 'throw new Error("x".repeat(1_000_000))',
-        bindings: [],
-      })
-      expect(result).toEqual({
-        logs: [],
-        error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
-      })
-    })
-
-    it('completes a program that awaits its write callback, capturing the chunk', async () => {
-      // Node's write(chunk[, encoding][, callback]) contract: dropping the
-      // callback would leave this promise pending until the wall ceiling and
-      // misreport a completed program as a timeout.
-      const { runtime } = await setup({ maxWallMs: 2_000 })
-      const result = await runtime.run({
-        program: 'await new Promise(resolve => process.stdout.write("flushed", resolve)); return "done"',
-        bindings: [],
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe('done')
-      expect(result.logs).toContain('flushed')
-    })
-
-    it('returns a large JSON container exactly when the outer cap permits it', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'return new Array(50_000).fill(7)', bindings: [] })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toEqual(new Array(50_000).fill(7))
-    })
-
-    it('returns an exact completion at the default 64 MiB combined boundary', async () => {
-      const { runtime } = await setup()
-      // [] costs two bytes and the JSON string contributes two quotes, leaving
-      // exactly this many payload bytes under the 67_108_864-byte default.
-      const result = await runtime.run({ program: 'return "x".repeat(67_108_860)', bindings: [] })
-      expect(result.error).toBeUndefined()
-      expect(result.logs).toEqual([])
-      expect(result.value).toHaveLength(67_108_860)
-    }, 60_000)
-
-    it('fails one byte over the default 64 MiB combined boundary', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({ program: 'return "x".repeat(67_108_861)', bindings: [] })
-      expect(result.value).toBeUndefined()
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 67108864 bytes' })
-    }, 60_000)
-
-    it('drains pipe output queued before terminal worker teardown completes', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 200_000 })
-      const payload = `late-pipe-${'x'.repeat(100_000)}`
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          const write = (text) => Object.getPrototypeOf(process.stdout).write.call(process.stdout, text);
-          write('late-pipe-' + 'x'.repeat(100_000));
-          parentPort.postMessage({ type: 'done', value: ['done'] });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe('done')
-      expect(result.logs.join('') === payload).toBe(true)
-    }, 15_000)
-  })
-
-  describe(`${label} — hostile programs (real workers)`, () => {
-    it('survives forged port traffic: unknown binding names, duplicate ids, junk shapes', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'call', id: 7777, global: 'tools', name: 'missing', args: {} });
-          parentPort.postMessage({ type: 'call', id: 7777, global: 'tools', name: 'missing', args: {} });
-          parentPort.postMessage({ type: 'call', id: 7778, global: 'tools', name: 'constructor', args: {} });
-          parentPort.postMessage({ type: 'junk' });
-          return await tools.real({});
-        `,
-        bindings: workerRuntimeTools({ real: async () => 'still-works' }),
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe('still-works')
-    })
-
-    it('survives arbitrary junk on the port: non-objects, junk types, malformed calls, logs, and dones', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          for (const junk of [
-            null, 42, 'junk', [],
-            { type: 'nope' },
-            { type: 'call' },
-            { type: 'call', id: 'x', global: 'tools', name: 'real', args: {} },
-            { type: 'call', id: 1e9, global: 7, name: 'real', args: {} },
-            { type: 'call', id: 1e9, global: 'tools', name: 7, args: {} },
-            { type: 'log' },
-            { type: 'log', text: null },
-            { type: 'log', text: 7 },
-            { type: 'log', text: {} },
-            { type: 'done', error: 5 },
-            { type: 'done', error: { kind: 'exception', message: 5 } },
-            { type: 'done', error: { kind: 'invented', message: 'bad kind' } },
-          ]) parentPort.postMessage(junk);
-          return await tools.real({});
-        `,
-        bindings: workerRuntimeTools({ real: async () => 'still-works' }),
-      })
-      expect(result.error).toBeUndefined()
-      expect(result.value).toBe('still-works')
-      expect(result.logs).toEqual([])
-    })
-
-    it('ignores forged controller-only failure classifications', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          for (const kind of ['abort', 'timeout', 'worker-exit']) {
-            parentPort.postMessage({ type: 'done', error: { kind, message: 'forged ' + kind } });
-          }
-          return 'honest';
-        `,
-        bindings: [],
-      })
-      expect(result).toEqual({ logs: [], value: 'honest' })
-    })
-
-    it('fails forged log floods and forged done values through the same outer cap', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 200 })
-      const result = await runtime.run({
-        // Forged messages bypass worker-side capture and completion checks;
-        // the outer ledger must still contain them.
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          for (let i = 0; i < 50; i++) parentPort.postMessage({ type: 'log', text: 'F'.repeat(100), forged: true });
-          parentPort.postMessage({ type: 'done', value: ['V'.repeat(100000)] });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result.value).toBeUndefined()
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 200 bytes' })
-      expect(Buffer.byteLength(JSON.stringify(result.logs), 'utf8')).toBeLessThan(200)
-    })
-
-    it('re-caps an oversized forged done value at the host boundary', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 64 })
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'done', value: ['V'.repeat(100_000)] });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result).toEqual({
-        logs: [],
-        error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' },
-      })
-    })
-
-    it('drops a malformed forged done carrying both value and error', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'done', value: 'lied', error: { kind: 'exception', message: 'fake failure' } });
-          return 'honest';
-        `,
-        bindings: [],
-      })
-      expect(result).toEqual({ logs: [], error: { kind: 'exception', message: 'fake failure' } })
-    })
-
-    it('contains a deeply nested forged completion without overflowing the host meter', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          const value = [];
-          for (let depth = 0; depth < 3_000; depth++) value.push({ kind: 'array', length: 1 });
-          value.push(null);
-          setTimeout(() => { parentPort.postMessage({ type: 'done', value }) }, 25);
-          // Prevent bootstrap's normal undefined completion from racing the forged terminal.
-          await new Promise(() => {});
-        `,
-        bindings: [],
-      })
-      expect(result.error).toBeUndefined()
-      let value = result.value
-      let depth = 0
-      while (Array.isArray(value)) {
-        expect(value).toHaveLength(1)
-        value = value[0]
-        depth += 1
-      }
-      expect(depth).toBe(3_000)
-      expect(value).toBeNull()
-    }, 15_000)
-
-    it('turns forged over-limit error text into output-limit at the host', async () => {
-      const { runtime } = await setup({ maxOutputBytes: 64 })
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'done', error: { kind: 'exception', message: '€'.repeat(1000) } });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result.error).toEqual({ kind: 'output-limit', message: 'outer output exceeded 64 bytes' })
-    })
-
-    it('answers a binding whose resolution is not lossless JSON with a typed failure reply', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
-        bindings: workerRuntimeTools({ bad: async () => (() => 1) }),
-      })
-      expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
-    })
-
-    it('rejects lossy binding arguments in the worker before invoking the host binding', async () => {
-      const { runtime } = await setup()
-      let calls = 0
-      const result = await runtime.run({
-        program: `
-          const decorated = [1]; Object.defineProperty(decorated, 'extra', { value: true });
-          const values = [new Date(), decorated, () => 1];
-          const failures = [];
-          for (const value of values) {
-            try { await tools.never(value) } catch (error) {
-              failures.push({ typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message });
-            }
-          }
-          return failures;
-        `,
-        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
-      })
-      expect(calls).toBe(0)
-      expect(result.value).toEqual(new Array(3).fill({
-        typed: true,
-        name: 'ToolCallError',
-        toolName: 'never',
-        message: 'binding arguments must be lossless JSON',
-      }))
-    })
-
-    it('rejects intrinsic-looking exotic objects as arguments and completions', async () => {
-      const { runtime } = await setup()
-      let calls = 0
-      const forgeObject = `
-        const prototype = Object.create(null);
-        const SpoofedObject = function Object() {};
-        SpoofedObject.prototype = prototype;
-        Object.defineProperty(prototype, 'constructor', { value: SpoofedObject });
-        const forged = Object.assign(Object.create(prototype), { value: 1 });
-        Function.prototype.toString = () => 'function Object() { [native code] }';
-      `
-      const argument = await runtime.run({
-        program: `${forgeObject}
-          try { await tools.never(forged) } catch (error) {
-            return { typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message };
-          }
-        `,
-        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
-      })
-      expect(calls).toBe(0)
-      expect(argument.value).toEqual({
-        typed: true,
-        name: 'ToolCallError',
-        toolName: 'never',
-        message: 'binding arguments must be lossless JSON',
-      })
-
-      const completion = await runtime.run({ program: `${forgeObject}\nreturn forged`, bindings: [] })
-      expect(completion).toEqual({
-        logs: [],
-        error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' },
-      })
-    })
-
-    it('preserves binding and completion JSON after model code mutates boundary globals', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const arrayPrototype = Array.prototype;
-          const objectPrototype = Object.prototype;
-          const setPrototype = Set.prototype;
-          const stringPrototype = String.prototype;
-          Array.isArray = () => false;
-          arrayPrototype.at = arrayPrototype.includes = arrayPrototype.pop = arrayPrototype.push = () => { throw new Error('mutated array method') };
-          Object.defineProperty = Object.getOwnPropertyDescriptor = Object.getPrototypeOf = Object.keys = () => { throw new Error('mutated object method') };
-          Object.hasOwn = () => false;
-          Object.is = () => true;
-          objectPrototype.propertyIsEnumerable = () => false;
-          Number.isFinite = Number.isSafeInteger = () => false;
-          Reflect.apply = Reflect.ownKeys = () => { throw new Error('mutated reflect method') };
-          setPrototype.add = setPrototype.delete = setPrototype.has = () => { throw new Error('mutated set method') };
-          stringPrototype.charCodeAt = stringPrototype.codePointAt = stringPrototype.slice = () => { throw new Error('mutated string method') };
-          Buffer.byteLength = () => 0;
-          Function.prototype.toString = () => 'mutated';
-          objectPrototype.get = () => undefined;
-          objectPrototype.constructor = arrayPrototype.constructor = null;
-          globalThis.Array = globalThis.Buffer = globalThis.Error = globalThis.Function = globalThis.Number = globalThis.Object = globalThis.Reflect = globalThis.Set = globalThis.String = undefined;
-          const echoed = await tools.echo({ request: ['€', 1] });
-          let failure;
-          try { await tools.fail({}) } catch (error) {
-            failure = { typed: error instanceof ToolCallError, name: error.name, toolName: error.toolName, message: error.message };
-          }
-          return { echoed, failure, completion: { ok: true, amount: 42 } };
-        `,
-        bindings: workerRuntimeTools({ echo: async args => args, fail: async () => { throw new Error('nope') } }),
-      })
-      expect(result).toEqual({
-        logs: [],
-        value: {
-          echoed: { request: ['€', 1] },
-          failure: { typed: true, name: 'ToolCallError', toolName: 'fail', message: 'nope' },
-          completion: { ok: true, amount: 42 },
-        },
-      })
-    })
-
-    it('rejects forged lossy binding arguments again at the host boundary', async () => {
-      const { runtime } = await setup()
-      let calls = 0
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          const forged = (id, args) => new Promise((resolve) => {
-            const receive = (message) => {
-              if (message?.type !== 'reply' || message.id !== id) return;
-              parentPort.off('message', receive);
-              resolve(message);
-            };
-            parentPort.on('message', receive);
-            parentPort.postMessage({ type: 'call', id, global: 'tools', name: 'never', args });
-          });
-          const sparse = []; sparse.length = 1;
-          const cycle = {}; cycle.self = cycle;
-          return await Promise.all([
-            forged(8001, new Date()),
-            forged(8002, -0),
-            forged(8003, sparse),
-            forged(8004, cycle),
-          ]);
-        `,
-        bindings: workerRuntimeTools({ never: async () => { calls += 1; return null } }),
-      })
-      expect(calls).toBe(0)
-      expect(result.value).toEqual([8001, 8002, 8003, 8004].map(id => ({
-        type: 'reply',
-        id,
-        ok: false,
-        message: 'binding arguments must be lossless JSON',
-      })))
-    })
-
-    it('contains throwing getters while snapshotting binding resolutions', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
-        bindings: workerRuntimeTools({ bad: async () => Object.defineProperty({}, 'bad', { enumerable: true, get() { throw new Error('getter exploded') } }) }),
-      })
-      expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
-    })
-
-    it('revalidates a forged lossy completion at the host boundary', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'done', value: -0 });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result).toEqual({ logs: [], error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' } })
-    })
-
-    it('honors a forged worker-side output-limit signal', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: `
-          const { parentPort } = await import('node:worker_threads');
-          parentPort.postMessage({ type: 'output-limit' });
-          for (;;) {}
-        `,
-        bindings: [],
-      })
-      expect(result).toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 67108864 bytes' } })
-    })
-
-    it('exposes binding names that collide with Object.prototype as ordinary functions', async () => {
-      const { runtime } = await setup()
-      const result = await runtime.run({
-        program: 'return [await tools["__proto__"]({}), await tools["constructor"]({}), typeof tools["hasOwnProperty"]]',
-        // Computed keys: a literal `'__proto__': …` entry would SET the record's
-        // prototype instead of declaring a binding of that name.
-        bindings: workerRuntimeTools({ ['__proto__']: async () => 'proto-ok', ['constructor']: async () => 'ctor-ok' }),
-      })
-      expect(result.value).toEqual(['proto-ok', 'ctor-ok', 'undefined'])
-    })
-  })
-
-  describe(`${label} — seam misuse and lifecycle`, () => {
-    it('rejects invalid and duplicate binding globals loudly', async () => {
-      const { runtime } = await setup()
-      const cases: [string, RegExp][] = [
-        ['not valid!', /not a usable identifier/],
-        ['await', /not a usable identifier/],
-        ['console', /duplicate binding global/],
-      ]
-      for (const [global, message] of cases) {
-        await expect(runtime.run({ program: 'return 1', bindings: [{ global, functions: {} }] })).rejects.toThrow(message)
-      }
-      await expect(runtime.run({
-        program: 'return 1',
-        bindings: [{ global: 'tools', functions: {} }, { global: 'tools', functions: {} }],
-      })).rejects.toThrow(/duplicate binding global/)
-
-      await expect(runtime.run({
-        program: 'return typeof ToolCallError',
-        bindings: [{ global: 'ToolCallError', functions: {} }],
-      })).resolves.toMatchObject({ value: 'object' })
-    })
-
-    it('rejects malformed or colliding binding error-class declarations', async () => {
-      const { runtime } = await setup()
-      const run = async (bindings: CodeBindingNamespace[]) => await runtime.run({ program: 'return 1', bindings })
-      const namespace = (global: string, name: string, memberNameProperty = 'memberName'): CodeBindingNamespace => ({
-        global,
-        functions: {},
-        errorClass: { name, memberNameProperty },
-      })
-
-      await expect(run([namespace('tools', 'not valid!')])).rejects.toThrow(/error class.*not a usable identifier/)
-      await expect(run([namespace('tools', 'await')])).rejects.toThrow(/error class.*not a usable identifier/)
-      await expect(run([namespace('tools', 'console')])).rejects.toThrow(/duplicate injected global/)
-      await expect(run([namespace('tools', 'tools')])).rejects.toThrow(/duplicate injected global/)
-      await expect(run([
-        namespace('tools', 'CallError'),
-        namespace('helpers', 'CallError'),
-      ])).rejects.toThrow(/duplicate injected global/)
-      await expect(run([namespace('tools', 'CallError', '')])).rejects.toThrow(/member property.*not usable/)
-      await expect(run([namespace('tools', 'CallError', 'message')])).rejects.toThrow(/member property.*not usable/)
-    })
-
-    it('rejects config values that are not positive numbers', async () => {
-      await expect(setup({ computeMs: -1 })).rejects.toThrow(/positive number/)
-    })
-
-    it('rejects a maxWallMs above Node\'s maximum timer delay', async () => {
-      // setTimeout clamps a delay past 2^31-1 ms to 1 ms, so the positivity check
-      // alone would accept a 25-day ceiling that expires on the first tick.
-      await expect(setup({ maxWallMs: 2_147_483_648 }))
-        .rejects.toThrow(/maxWallMs must be at most 2147483647/)
-      // The boundary itself is usable.
-      await expect(setup({ maxWallMs: 2_147_483_647 })).resolves.toBeTruthy()
-    })
-
-    it('requires maxOutputBytes to fit the smallest counted outer payloads', async () => {
-      await expect(setup({ maxOutputBytes: 3 })).rejects.toThrow(/safe integer of at least 4/)
-      await expect(setup({ maxOutputBytes: 4.5 })).rejects.toThrow(/safe integer of at least 4/)
-    })
-
-    it('keeps runs isolated: no state survives from one run to the next', async () => {
-      const { runtime } = await setup()
-      await runtime.run({ program: 'globalThis.leak = "value"; return 1', bindings: [] })
-      const second = await runtime.run({ program: 'return typeof globalThis.leak', bindings: [] })
-      expect(second.value).toBe('undefined')
-    })
-
-    it('disposal aborts in-flight runs, awaits worker exit, and rejects later runs', async () => {
-      const { runtime, dispose } = await setup()
-      const inflight: Promise<CodeRunResult> = runtime.run({ program: 'for (;;) {}', bindings: [] })
-      // Give the worker a moment to actually start spinning.
-      await new Promise(resolve => setTimeout(resolve, 200))
-      await dispose()
-      const result = await inflight
-      expect(result.error).toEqual({ kind: 'abort', message: 'runtime disposed' })
-      await expect(runtime.run({ program: 'return 1', bindings: [] })).rejects.toThrow(/after disposal/)
-    }, 15_000)
-  })
-}
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index af424b8809..0ebb5bd4af 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: 5ea1ae3681f9340cfba798e659f454d6d05fdbfe
-README.zh.md: 4e1cb9472d6e90062ecde61db4200a79a56b16f1
+README.md: f2b19436da40feb14d067e2cfc706222625680b5
+README.zh.md: 938312448dd5c0a691ed07ddc9843cf2c4445637
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index 5ea1ae3681..f2b19436da 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-The shared process substrate for one execution world: canonical cwd, executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), [subprocess code runtime](../code-runtime/code-runtime-subprocess/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+The shared process substrate for one execution world: executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 | Package | ctx key | Role |
 |---|---|---|
-| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: execution-world coordinates and executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
+| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
 | [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index 4e1cb9472d..938312448d 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-这里集中提供一个执行世界的共享进程基底：规范化 cwd、可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)、[子进程代码运行时](../code-runtime/code-runtime-subprocess/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+这里集中提供一个执行世界的共享进程基底：可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：执行世界坐标与可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
 | [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
 
 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 8b668b43f6..ee90e9e607 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: 4892ad49e571662b833b1dd6d64dc966f343ae3c
-README.zh.md: ca0df5ff18e9feb992cc3f6d0db90dc06cb275d8
+README.md: 85103c2634bd35b188acd71c7f037e3678a2542e
+README.zh.md: 505eac4f2650e6723e042cdb1122f9ef504ad7df
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 13b51ec6d1..c211ca26f1 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), [`dsh-pty-local`](../../pty/pty-local/README.md), and [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)).
+Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), and [`dsh-pty-local`](../../pty/pty-local/README.md)).
 
 ## Behavior (and where it came from)
 
@@ -10,7 +10,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
-- **Execution-world coordinates** — `cwd` is the host process cwd, and `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions.
+- **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative PATH entries resolve from the host process cwd.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index ca0df5ff18..505eac4f26 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-pty-local`](../../pty/pty-local/README.md) 和 [`dsh-code-runtime-subprocess`](../../code-runtime/code-runtime-subprocess/README.md)）。
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md) 和 [`dsh-pty-local`](../../pty/pty-local/README.md)）。
 
 ## 行为（以及设计来源）
 
@@ -10,7 +10,7 @@
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **执行世界坐标**：`cwd` 是宿主进程 cwd，`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索。
+- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；相对 PATH 条目从宿主进程 cwd 解析。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
 - **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 262a2567b8..4a740a1e3b 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -33,7 +33,6 @@ import { LocalTerminalHandle } from './terminal.ts'
  * SIGTERM→grace→SIGKILL escalation.
  */
 export class LocalSubprocessService extends SubprocessService {
-  readonly cwd = process.cwd()
   /** Live handles retained only so disposal can terminate and join them. */
   private live = new Set<SubprocessHandle>()
   /** Live terminal sessions retained through whole-session quiescence. */
@@ -103,7 +102,7 @@ export class LocalSubprocessService extends SubprocessService {
       ? (environmentValue(env, 'PATHEXT') ?? '.COM;.EXE;.BAT;.CMD').split(';')
       : ['']
     return path.split(delimiter).flatMap(directory =>
-      extensions.map(extension => resolve(this.cwd, directory, command + extension)))
+      extensions.map(extension => resolve(process.cwd(), directory, command + extension)))
   }
 
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index e74927448d..a0455edef0 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -31,9 +31,6 @@ describe('LocalSubprocessService', () => {
     expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), {
       PATH: relative(process.cwd(), dirname(process.execPath)) || '.',
     })).toBe(process.execPath)
-    Reflect.set(ctx.subprocess, 'cwd', dirname(process.execPath))
-    expect(await ctx.subprocess.resolveExecutable(basename(process.execPath), { PATH: '' }))
-      .toBe(process.execPath)
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('must be non-empty')
     await expect(ctx.subprocess.resolveExecutable('dsh-command-that-does-not-exist', { PATH: '' }))
       .rejects.toThrow('was not found on PATH')
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index d12516f11f..e67bf1a87f 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: 08fb03d6f145c1026180d92de2421b647cb3ebbe
-README.zh.md: 592fc83223092b3406e9070e11de2b20a63232a6
+README.md: ec4a4e3328a5a600441d2e7983b3844f4ccc5e91
+README.zh.md: 3da79995fad9a2c8f2a6020ae18152a0e4459c71
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index 08fb03d6f1..ec4a4e3328 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -2,12 +2,12 @@
 
 English | [中文](README.zh.md)
 
-The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessService` exposes its canonical `cwd`, executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
+The subprocess seam (`ctx.subprocess`) is the process half of one execution world. The abstract `SubprocessService` exposes executable lookup, ordinary managed `spawn`, and one terminal-process primitive; its vocabulary covers raw/collected stdio, process and terminal handles, exit facts, tree/session cleanup, and the managed `DSH_*` environment namespace. The local implementation lives in [`dsh-subprocess-local`](../subprocess-local/README.md).
 
 ## Contract
 
 - `spawn(spec)` returns immediately with a live handle; `done` resolves at process close with exit facts (`SubprocessOutcome` carries no output and no cause classification) and rejects only for spawn-level failures.
-- `cwd` and executable paths belong to the provider's execution world. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
+- Spawn working directories and executable paths belong to the provider's execution world. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
 - The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 592fc83223..3da79995fa 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -2,12 +2,12 @@
 
 [English](README.md) | 中文
 
-子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开其规范化 `cwd`、可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
+子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
 
 ## 契约
 
 - `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
-- `cwd` 和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
+- spawn 工作目录和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
 - spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index df3186c9b0..14866c9784 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -1,6 +1,6 @@
 /**
- * The subprocess seam (`ctx.subprocess`): execution-world process coordinates,
- * executable lookup, fully specified managed process trees with raw or
+ * The subprocess seam (`ctx.subprocess`): execution-world executable lookup,
+ * fully specified managed process trees with raw or
  * collected stdio, and one terminal-process primitive. Command defaulting,
  * shell semantics, deadlines, protocol framing, terminal readiness, and
  * presentation belong to consumers. The local implementation lives in
@@ -78,8 +78,8 @@ declare module 'cordis' {
  * duplicate-service behavior).
  *
  * Implementations must honor these semantics:
- * - {@link cwd} and executable paths belong to one execution world shared
- *   with the mounted filesystem provider.
+ * - Executable paths belong to one execution world shared with the mounted
+ *   filesystem provider.
  * - {@link spawn} returns immediately with a live handle; `done` resolves at
  *   process close with exit facts and rejects only for spawn-level failures.
  * - Collect-mode readers are offset-based and non-consuming, so independent
@@ -104,9 +104,6 @@ export abstract class SubprocessService extends Service {
     super(ctx, 'subprocess')
   }
 
-  /** Canonical default cwd in this provider's execution world. */
-  abstract readonly cwd: string
-
   /**
    * Resolve one configured executable in this provider's execution world.
    * Absolute paths are verified; bare names use the provider's scrubbed PATH
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index b20d5b5f3b..355b817e68 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -148,7 +148,6 @@ function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
     'lib/invariant.js',
     ...manifest.bin ? ['lib/bin.js'] : [],
     ...manifest.exports?.['./worker'] ? ['lib/worker.cjs'] : [],
-    ...exportDefault(manifest, './runtime-host') === './lib/runtime-host.js' ? ['lib/runtime-host.js'] : [],
     // UI plugin packages ship their browser bundle beside the node lib
     // (single-artifact ruling: dist/ retired, ./client resolves lib/client.js).
     // Keyed on the artifact path, not the subpath name: apiproxy's ./client is
diff --git a/scripts/gen-code-runtime-runner.ts b/scripts/gen-code-runtime-runner.ts
deleted file mode 100644
index 7e856e7651..0000000000
--- a/scripts/gen-code-runtime-runner.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-/** Generate the subprocess Code Runtime's dependency-free runner bundle. */
-
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { build } from 'tsdown'
-
-const root = resolve(import.meta.dirname, '..')
-const ENTRY = 'packages/code-runtime/code-runtime-subprocess/src/runner.ts'
-const OUT = 'packages/code-runtime/code-runtime-subprocess/src/runner-source.generated.ts'
-
-/**
- * Bundle the typed runner and shared worker implementation into one source literal.
- * @returns generated TypeScript module consumed by the subprocess backend.
- */
-export async function renderCodeRuntimeRunner(): Promise<string> {
-  const bundles = await build({
-    config: false,
-    entry: [resolve(root, ENTRY)],
-    format: ['esm'],
-    platform: 'node',
-    target: 'es2024',
-    write: false,
-    dts: false,
-    clean: false,
-    minify: true,
-    logLevel: 'silent',
-    report: false,
-    deps: { alwaysBundle: ['@deepseek-ai/dsh-code-runtime-worker'] },
-  })
-  try {
-    const chunks = bundles.flatMap(bundle => bundle.chunks).filter(chunk => chunk.type === 'chunk')
-    if (chunks.length !== 1) throw new Error(`gen-code-runtime-runner: expected one chunk, received ${chunks.length}`)
-    const chunk = chunks[0]
-    if (chunk === undefined) throw new Error('gen-code-runtime-runner: runner chunk is missing')
-    const external = chunk.imports.filter(specifier => !specifier.startsWith('node:'))
-    if (external.length > 0) {
-      throw new Error(`gen-code-runtime-runner: runner retained external imports: ${external.join(', ')}`)
-    }
-    return [
-      '/**',
-      ' * Generated dependency-free execution-world runner.',
-      ' * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.',
-      ' */',
-      '',
-      `export const CODE_RUNNER_SOURCE = ${JSON.stringify(chunk.code)}`,
-      '',
-    ].join('\n')
-  } finally {
-    await Promise.all(bundles.map(async (bundle) => { await bundle[Symbol.asyncDispose]() }))
-  }
-}
-
-async function main(): Promise<void> {
-  const content = await renderCodeRuntimeRunner()
-  const output = resolve(root, OUT)
-  if (process.argv.includes('--check')) {
-    const committed = existsSync(output) ? readFileSync(output, 'utf8') : null
-    if (committed === content) {
-      console.log(`gen-code-runtime-runner: ${OUT} is up to date.`)
-      return
-    }
-    console.error(`gen-code-runtime-runner: ${OUT} is stale. Run \`pnpm run gen-code-runtime-runner\` and commit it.`)
-    process.exitCode = 1
-    return
-  }
-  writeFileSync(output, content)
-  console.log(`gen-code-runtime-runner: wrote ${OUT}.`)
-}
-
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) await main()
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 7be0e1fa58..00520bdbe7 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -48,13 +48,9 @@ interface EventRelation {
   listeners: Set<string>
 }
 
-/** One scanned package source file and its owning package short name. */
-export interface PackageSource {
-  /** Repository-relative path. */
+interface PackageSource {
   rel: string
-  /** Package short name from the `packages/<group>/<pkg>/src` path. */
   pkg: string
-  /** The bound program source file. */
   sourceFile: ts.SourceFile
 }
 
@@ -124,7 +120,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session',
     title: 'In-memory session store',
     mode: 'core',
-    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
+    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
     note: 'Owns append-only Session instances and emits the durable session event feed.',
   },
   {
@@ -159,24 +155,6 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'session-query', 'session-query-sqlite'],
     note: 'Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time.',
   },
-  {
-    key: 'settings',
-    pkg: 'settings',
-    title: 'User-settings seam',
-    mode: 'seam',
-    implementations: ['settings-local'],
-    consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
-    note: 'Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer.',
-  },
-  {
-    key: 'credentials',
-    pkg: 'credentials',
-    title: 'Credential seam',
-    mode: 'seam',
-    implementations: ['credentials-local'],
-    consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
-    note: 'Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage.',
-  },
   {
     key: 'telemetry',
     pkg: 'session-telemetry',
@@ -225,6 +203,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session-reference',
     title: 'Cross-session snapshot preparation',
     mode: 'core',
+    consumers: ['tui'],
     note: 'Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax.',
   },
   {
@@ -256,7 +235,8 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'user-interaction',
     title: 'Human question/answer seam',
     mode: 'seam',
-    consumers: ['tool-ask-user'],
+    implementations: ['tui'],
+    consumers: ['tool-ask-user', 'tui'],
     note: 'UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.',
   },
   {
@@ -271,7 +251,8 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'commands',
     title: 'Human command registry',
     mode: 'core',
-    note: 'Plugins register direct human commands without sending invocations to the model.',
+    consumers: ['tui'],
+    note: 'Plugins register direct human commands; TUI consumes the effective per-agent catalog without sending invocations to the model.',
   },
   {
     key: 'sessionProjections',
@@ -289,12 +270,19 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['host-apiproxy'],
     note: 'Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs.',
   },
+  {
+    key: 'tui',
+    pkg: 'tui',
+    title: 'Mounted-terminal interaction service',
+    mode: 'bundle',
+    note: 'One TUI front door provides a FIFO overlay host; injected plugins receive caller-fiber ownership without access to pi-tui or terminal lifecycle state.',
+  },
   {
     key: 'skills',
     pkg: 'skill',
     title: 'Skill provider registry',
     mode: 'seam',
-    implementations: ['skill-badge', 'skill-local'],
+    implementations: ['skill-local'],
     consumers: ['tool-skill'],
     note: 'Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies.',
   },
@@ -303,7 +291,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'agent',
     title: 'Agent service',
     mode: 'core',
-    consumers: ['agent-loop', 'acp', 'subagent-inprocess'],
+    consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'tui-demo'],
     note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
   },
   {
@@ -327,25 +315,24 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Subprocess seam',
     mode: 'seam',
     implementations: ['subprocess-local'],
-    consumers: ['bash-local', 'bash-sandbox', 'lsp-local', 'subagent-acp', 'subagent-codex', 'subagent-claude-code'],
-    note: 'The bash executors, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation.',
+    consumers: ['bash-local', 'bash-sandbox', 'pty-local', 'lsp-local', 'subagent-acp'],
+    note: 'The bash executors, PTY shell backend, LSP host, and ACP subagent backend spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation.',
   },
   {
     key: 'bash',
     pkg: 'bash',
     title: 'Bash executor seam',
     mode: 'seam',
-    implementations: ['bash-local', 'bash-sandbox', 'pwsh-local'],
-    consumers: ['tool-bash', 'tool-pwsh', 'hooks-claude', 'hooks-codex'],
-    note: 'The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them.',
+    implementations: ['bash-local', 'bash-sandbox'],
+    consumers: ['tool-bash', 'hooks-claude', 'hooks-codex'],
+    note: 'The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them.',
   },
   {
     key: 'bashEnv',
-    pkg: 'bash-env',
+    pkg: 'tool-bash',
     title: 'Managed bash environment registry',
     mode: 'core',
-    consumers: ['tool-bash', 'tool-pwsh'],
-    note: 'Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace.',
+    note: 'Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace.',
   },
   {
     key: 'pty',
@@ -422,11 +409,11 @@ const SERVICE_ROLES: ServiceRole[] = [
   {
     key: 'subagents',
     pkg: 'subagent',
-    title: 'Subagent provider and continuation service',
+    title: 'Subagent provider registry',
     mode: 'seam',
-    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp', 'subagent-codex', 'subagent-claude-code', 'subagent-dsh-sdk'],
-    consumers: ['tool-subagent', 'tool-subagent-control', 'tool-ralph'],
-    note: 'Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route.',
+    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
+    consumers: ['tool-subagent', 'tool-ralph'],
+    note: 'Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route.',
   },
   {
     key: 'tasks',
@@ -605,8 +592,7 @@ function parseExampleCordis(rel: string): ExamplePlugin[] {
     if (current?.name) plugins.push({ id: current.id, name: current.name })
   }
   for (const line of text.split('\n')) {
-    // Top-level rows (`- id:`) and bundle-patch insert rows (`    - id:`).
-    const id = /^\s*-\s+id:\s+(.+?)\s*$/.exec(line)
+    const id = /^-\s+id:\s+(.+?)\s*$/.exec(line)
     if (id?.[1] !== undefined) {
       flush()
       current = { id: stripYamlScalar(id[1]) }
@@ -625,20 +611,28 @@ function stripYamlScalar(value: string): string {
 
 const APP_EXAMPLES = [
   {
-    id: 'dsh_base',
-    rel: 'apps/cli/composition.md',
-    title: 'DSH Base Composition',
-    label: 'packages/bundle/base/cordis.patch.yml',
-    config: 'packages/bundle/base/cordis.patch.yml',
-    summary: 'The dsh-base bundle patch every profile applies first; mode bundles (dsh-web-app, dsh-headless) and the user\'s profile layer patch over it.',
+    id: 'tui',
+    rel: 'examples/tui-agent/composition.md',
+    title: 'TUI Agent App Composition',
+    label: 'examples/tui-agent',
+    config: 'examples/tui-agent/cordis.yml',
+    summary: 'The TUI agent combines the real DeepSeek adapter, coding tools, compaction, subagents, and workflows with the full-screen terminal app package.',
   },
   {
     id: 'headless',
     rel: 'examples/headless-agent/composition.md',
-    title: 'Headless Agent Snapshot Composition',
+    title: 'Headless Agent App Composition',
     label: 'examples/headless-agent',
     config: 'examples/headless-agent/cordis.yml',
-    summary: 'The headless snapshot composition combines the real DeepSeek adapter and coding capabilities with one explicitly configured persisted top-level agent; its JSONL driver is test-only.',
+    summary: 'The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.',
+  },
+  {
+    id: 'cordis',
+    rel: 'examples/cordis-agent/composition.md',
+    title: 'Cordis Agent App Composition',
+    label: 'examples/cordis-agent',
+    config: 'examples/cordis-agent/cordis.yml',
+    summary: 'The self-referential demo puts @deepseek-ai/dsh-tool-cordis on the coding spine, letting the agent inspect its current-process runtime and mount or unmount in-memory temporary Plugins.',
   },
   {
     id: 'acp',
@@ -657,7 +651,11 @@ function renderAppExpansion(lines: string[], appNode: string, pluginName: string
   const jsonl = nodeId('bundle', 'jsonl')
   lines.push(`  ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`)
   lines.push(`  ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
-  if (pluginName === '@deepseek-ai/dsh-acp-demo') {
+  if (pluginName === '@deepseek-ai/dsh-tui-demo') {
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'tui')}["@deepseek-ai/dsh-tui<br/>pre-created main agent"]`)
+  } else if (pluginName === '@deepseek-ai/dsh-cli-demo') {
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'cli')}["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]`)
+  } else if (pluginName === '@deepseek-ai/dsh-acp-demo') {
     lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>automation-only JSON-RPC stdio<br/>fresh sessions created by client"]`)
   }
   lines.push(
@@ -683,7 +681,7 @@ function renderAppComposition(example: AppExample): string {
     const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
     lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
     lines.push(`  cfg --> ${pluginNode}`)
-    if (plugin.name === '@deepseek-ai/dsh-acp-demo') {
+    if (plugin.name === '@deepseek-ai/dsh-tui-demo' || plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
       renderAppExpansion(lines, pluginNode, plugin.name)
     }
   }
@@ -700,26 +698,13 @@ function renderAppComposition(example: AppExample): string {
   return lines.join('\n')
 }
 
-type CallSiteIndex = Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>
-
-/**
- * The only method names visitSource classifies; receiver typing runs on these
- * alone. Obligation: every method name matched by a branch inside visitSource
- * must appear here — the prefilter drops non-members before any branch runs,
- * so a branch for an unlisted name is silently dead.
- */
-const EVENT_API_METHODS = new Set(['on', 'once', 'emit', 'parallel', 'serial', 'waterfall', 'dispatch'])
-
 /** Collect event dispatch/listener relations from real cross-file receiver types. */
-export class EventRelationCollector {
+class EventRelationCollector {
   private readonly relations = new Map<string, EventRelation>()
-  private readonly fileCallSites = new Map<ts.SourceFile, CallSiteIndex>()
-  private readonly localCalleeProofs = new Map<ts.FunctionDeclaration, boolean>()
-  private globalCallSites: CallSiteIndex | null = null
+  private readonly callSites = new Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>()
   private readonly contextType: ts.Type
   private readonly agentDispatchType: ts.Type
   private readonly eventsServiceType: ts.Type
-  private readonly packageSourceFiles: ReadonlySet<ts.SourceFile>
 
   constructor(
     private readonly project: TypeScriptProject,
@@ -728,7 +713,7 @@ export class EventRelationCollector {
     this.contextType = this.declaredType('vendor/cordis/src/context.ts', 'Context')
     this.agentDispatchType = this.declaredType('packages/core/agent/src/dispatch.ts', 'AgentEventDispatch')
     this.eventsServiceType = this.declaredType('vendor/cordis/src/events.ts', 'EventsService')
-    this.packageSourceFiles = new Set(sources.map(source => source.sourceFile))
+    this.indexCallSites()
   }
 
   /** Return all event relations discovered from the Program. */
@@ -748,88 +733,20 @@ export class EventRelationCollector {
     return this.project.checker.getDeclaredTypeOfSymbol(symbol)
   }
 
-  /** Index resolved function calls in the given files for narrow argument-flow recovery. */
-  private buildCallSiteIndex(files: Iterable<ts.SourceFile>): CallSiteIndex {
-    const index: CallSiteIndex = new Map()
+  /** Index resolved local function calls for narrow argument-flow recovery. */
+  private indexCallSites(): void {
     const visit = (node: ts.Node): void => {
       if (ts.isCallExpression(node)) {
         const declaration = this.project.checker.getResolvedSignature(node)?.declaration
         if (declaration) {
-          const calls = index.get(declaration) ?? []
+          const calls = this.callSites.get(declaration) ?? []
           calls.push(node)
-          index.set(declaration, calls)
+          this.callSites.set(declaration, calls)
         }
       }
       ts.forEachChild(node, visit)
     }
-    for (const file of files) visit(file)
-    return index
-  }
-
-  /**
-   * Return every indexed call resolving to one local helper declaration.
-   * Fast path: when every same-file reference to the non-exported helper is
-   * provably a direct callee, module scoping confines all of its calls to that
-   * file, so only that file is indexed. Any other reference shape may alias
-   * the function value outward, so the original full package-source index
-   * decides instead.
-   */
-  private callSitesFor(owner: ts.FunctionDeclaration): ts.CallExpression[] {
-    if (!this.globalCallSites && !this.provenLocalCallee(owner)) {
-      this.globalCallSites = this.buildCallSiteIndex(this.packageSourceFiles)
-    }
-    if (this.globalCallSites) return this.globalCallSites.get(owner) ?? []
-    const file = owner.getSourceFile()
-    let index = this.fileCallSites.get(file)
-    if (!index) {
-      index = this.buildCallSiteIndex([file])
-      this.fileCallSites.set(file, index)
-    }
-    return index.get(owner) ?? []
-  }
-
-  /**
-   * Prove every same-file reference to one helper is a direct callee. The
-   * proof owns its premises: an exported helper or a helper in a global
-   * script file (no import/export means program-wide scope, callable from
-   * another file with no same-file reference at all) fails immediately.
-   * Alias escapes (re-export statements, default exports, value reads)
-   * resolve back to the owner symbol at a non-callee position and fail the
-   * proof, as does anything the scan cannot positively classify.
-   */
-  private provenLocalCallee(owner: ts.FunctionDeclaration): boolean {
-    const cached = this.localCalleeProofs.get(owner)
-    if (cached !== undefined) return cached
-    if (hasExportModifier(owner) || !ts.isExternalModule(owner.getSourceFile())) {
-      this.localCalleeProofs.set(owner, false)
-      return false
-    }
-    const name = owner.name
-    const ownerSymbol = name && this.project.checker.getSymbolAtLocation(name)
-    let proven = !!ownerSymbol
-    const refersToOwner = (identifier: ts.Identifier): boolean => {
-      // Shorthand properties resolve to the property symbol; ask for the value side.
-      const local = ts.isShorthandPropertyAssignment(identifier.parent)
-        ? this.project.checker.getShorthandAssignmentValueSymbol(identifier.parent)
-        : this.project.checker.getSymbolAtLocation(identifier)
-      if (!local) return false
-      const symbol = local.flags & ts.SymbolFlags.Alias
-        ? this.project.checker.getAliasedSymbol(local)
-        : local
-      return symbol === ownerSymbol
-    }
-    const visit = (node: ts.Node): void => {
-      if (!proven) return
-      if (ts.isIdentifier(node) && node !== name && node.text === name?.text
-        && !isDirectCallee(node) && refersToOwner(node)) {
-        proven = false
-        return
-      }
-      ts.forEachChild(node, visit)
-    }
-    visit(owner.getSourceFile())
-    this.localCalleeProofs.set(owner, proven)
-    return proven
+    for (const source of this.sources) visit(source.sourceFile)
   }
 
   /** Walk one package source file and classify event API calls by receiver type. */
@@ -843,7 +760,7 @@ export class EventRelationCollector {
               this.addDispatcher(name, source.pkg, 'emitAgentEvent')
             }
           }
-        } else if (ts.isPropertyAccessExpression(node.expression) && EVENT_API_METHODS.has(node.expression.name.text)) {
+        } else if (ts.isPropertyAccessExpression(node.expression)) {
           const receiverKind = this.receiverKind(node.expression.expression)
           const method = node.expression.name.text
           if (receiverKind === 'events-service' && method === 'dispatch') {
@@ -946,7 +863,7 @@ export class EventRelationCollector {
     const index = owner.parameters.indexOf(parameter)
     if (index < 0) return new Set()
     const events = new Set<string>()
-    for (const call of this.callSitesFor(owner)) {
+    for (const call of this.callSites.get(owner) ?? []) {
       const argument = call.arguments[index]
       if (argument) addAll(events, this.eventNamesFromArgumentList(argument, new Set(seen)))
     }
@@ -993,21 +910,6 @@ export class EventRelationCollector {
   }
 }
 
-/** Return whether an identifier is the callee of a call, seen through value-preserving wrappers. */
-function isDirectCallee(identifier: ts.Identifier): boolean {
-  let current: ts.Node = identifier
-  while (
-    ts.isParenthesizedExpression(current.parent)
-    || ts.isAsExpression(current.parent)
-    || ts.isTypeAssertionExpression(current.parent)
-    || ts.isNonNullExpression(current.parent)
-    || ts.isSatisfiesExpression(current.parent)
-  ) {
-    current = current.parent
-  }
-  return ts.isCallExpression(current.parent) && current.parent.expression === current
-}
-
 /** Peel syntax-only wrappers that do not change an expression's runtime value. */
 function unwrapExpression(expression: ts.Expression): ts.Expression {
   let current = expression
@@ -1063,22 +965,14 @@ function unionSets<T>(left: ReadonlySet<T>, right: ReadonlySet<T>): Set<T> {
   return out
 }
 
-/**
- * Select the package source files of one project in deterministic order.
- * @param project - the loaded repository TypeScript project.
- * @returns `packages/<group>/<pkg>/src` files tagged with their package name.
- */
-export function collectPackageSources(project: TypeScriptProject): PackageSource[] {
-  return project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
+function collectEventRelations(): Map<string, EventRelation> {
+  const project = new TypeScriptProject(root)
+  const sources = project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
     const rel = project.relativePath(sourceFile)
     const match = /^packages\/[^/]+\/([^/]+)\/src\/.+\.ts$/.exec(rel)
     return match?.[1] ? [{ rel, pkg: match[1], sourceFile }] : []
   }).sort((left, right) => left.rel.localeCompare(right.rel))
-}
-
-function collectEventRelations(): Map<string, EventRelation> {
-  const project = new TypeScriptProject(root)
-  return new EventRelationCollector(project, collectPackageSources(project)).collect()
+  return new EventRelationCollector(project, sources).collect()
 }
 
 function relationPackages(map: Map<string, Set<string>>, pkgsByShort: Map<string, Pkg>): string {
@@ -1159,22 +1053,20 @@ function renderLifecycle(): string {
     '  participant Session',
     '  participant SDK as UI or SDK listener',
     '  User->>Agent: followup(content)',
-    `  Agent-->>SDK: ${mermaidCode('agent/inbox/spliced')}`,
-    `  Agent-->>SDK: ${mermaidCode('agent/inbox/inserted')} { message }`,
+    `  Agent-->>SDK: ${mermaidCode('agent/inbox/enqueue')}`,
     '  Agent->>Driver: queued work wakes driver',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
-    '  Note over Agent,Driver: claim pending next-step input plus one queued prompt',
-    `  Driver-->>SDK: ${mermaidCode('agent/inbox/spliced')} pure deletion`,
-    `  Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
-    `  Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
-    '  Hooks-->>Driver: authoritative reject or enter(messages)',
-    '  alt proposed step rejected or pre-step failed',
-    '    Driver-->>Driver: claimed batch stays removed, no turn opens',
-    '  else enter proposed step',
+    '  Note over Agent,Driver: next-step acceptance window opens',
+    `  Driver->>Hooks: ${mermaidCode('agent/prompt-submit')} waterfall`,
+    '  Hooks-->>Driver: authoritative allow, block, or add context',
+    '  alt prompt blocked or admission failed',
+    '    Driver-->>Driver: append context-only batch or keep steering boundary pending',
+    '  else prompt allowed',
     `  Driver->>Session: ${mermaidCode('turn/start')}`,
-    `  Driver->>Session: ${mermaidCode('step/start')}`,
-    `  Driver->>Session: ${mermaidCode('user/message')} per entered message`,
+    `  Driver->>Session: ${mermaidCode('user/message')}`,
     `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
+    `  Driver-->>Driver: ${mermaidCode('agent/step')} serial checkpoint`,
+    `  Driver->>Session: ${mermaidCode('step/start')}`,
     `  Driver->>LLM: ${mermaidCode('agent/request')} waterfall, then ${mermaidCode('llm/stream')} waterfall`,
     '  LLM-->>Driver: StreamChunk*',
     `  Driver->>Session: ${mermaidCode('assistant/chunk')}*`,
@@ -1197,17 +1089,11 @@ function renderLifecycle(): string {
     `      Driver->>Session: ${mermaidCode('tool/result')}`,
     '    end',
     '  end',
+    '  Driver->>Session: post-tool context and steering (no prompt-submit)',
     `  Driver->>Session: ${mermaidCode('step/end')}`,
-    '  opt natural stop and next-step inbox empty',
-    `    Driver->>Hooks: ${mermaidCode('agent/turn-stopping')} serial terminal checkpoint`,
-    '  end',
-    '  opt next-step input is pending',
-    '    Driver-->>Driver: claim pending next-step input',
-    `    Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
-    `    Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
-    '    Hooks-->>Driver: authoritative reject or enter(messages)',
-    '  end',
+    `  Driver->>Hooks: ${mermaidCode('agent/turn-stopping')} serial terminal checkpoint`,
     '  end',
+    '  Note over Agent,Driver: next-step acceptance window closes',
     `  Driver->>Session: ${mermaidCode('turn/end')}`,
     '  end',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
@@ -1215,9 +1101,9 @@ function renderLifecycle(): string {
     '',
     'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
     '',
-    '`dsh-compact-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
+    '`dsh-compact-basic` uses `agent/step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
     '',
-    'The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages unless replacement is intentional. Steering and injected context pass through the same waterfall after a later boundary claims their next-step batch.',
+    'The returned `agent/prompt-submit` allow is authoritative; listeners wrapping `next()` preserve downstream content and additional contexts unless replacement is intentional. Steering bypasses that waterfall and joins at its durable checkpoint.',
     '',
     'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
     '',
@@ -1306,8 +1192,8 @@ function renderDocs(): GraphDoc[] {
 function renderIndex(docs: GraphDoc[]): string {
   const labels: Record<string, string> = {
     'docs/capability-seams.md': 'capability seams and core services',
-    'apps/cli/composition.md': 'dsh shared base composition',
     'examples/headless-agent/composition.md': 'headless-agent app composition',
+    'examples/tui-agent/composition.md': 'tui-agent app composition',
     'examples/cordis-agent/composition.md': 'cordis-agent app composition',
     'examples/acp-agent/composition.md': 'acp-agent app composition',
     'docs/event-producer-consumer.md': 'event producer/consumer matrix',
@@ -1316,8 +1202,8 @@ function renderIndex(docs: GraphDoc[]): string {
   }
   const modes: Record<string, string> = {
     'docs/capability-seams.md': 'hybrid generated',
-    'apps/cli/composition.md': 'hybrid generated',
     'examples/headless-agent/composition.md': 'hybrid generated',
+    'examples/tui-agent/composition.md': 'hybrid generated',
     'examples/cordis-agent/composition.md': 'hybrid generated',
     'examples/acp-agent/composition.md': 'hybrid generated',
     'docs/event-producer-consumer.md': 'hybrid generated',
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 6f59b64826..74a09a874e 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -585,7 +585,6 @@ function docSyncLeafGates(options: {
     pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }),
     pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }),
     pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }),
-    pnpmScript('code-runtime-runner', 'verify-code-runtime-runner', { label: 'code-runtime runner' }),
     pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }),
     pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
     pnpmScript('public-repository-links', 'verify-public-repository-links', { label: 'public repository links' }),
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 9a249ca844..3ca0317cf4 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -47,7 +47,6 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
-  'packages/code-runtime/code-runtime-subprocess': { kind: 'indirect', reason: 'The subprocess backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 6252733511..1a8ef6508a 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -169,7 +169,6 @@
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
-    { "path": "./packages/code-runtime/code-runtime-subprocess" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
     { "path": "./packages/bash/bash-local" },

From e67a824604c3c098f01cb3e24fa189f56d4c8fc0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 14:38:03 +0800
Subject: [PATCH 340/516] docs(code-runtime): restore worker-only package
 summary

---
 packages/README.i18n.yaml | 2 +-
 packages/README.zh.md     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 1484411cca..458da3b713 100644
--- a/packages/README.i18n.yaml
+++ b/packages/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/README.md
 README.md: 3f467641bbc9eae14a94aa2d3bff0402116a9d3f
-README.zh.md: faa879f3b5b62527c1d76ab3aff6a737f876ce4d
+README.zh.md: c9d11bbf6239b4239a4e037dac63b05d3a9a58f7
diff --git a/packages/README.zh.md b/packages/README.zh.md
index bed31b657c..b84aef020a 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -19,7 +19,7 @@
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：用于模型编写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
 | [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
 | [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
 | [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |

From 921f4ff7a32d3c8189e4983071281cdbc1525800 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 14:53:28 +0800
Subject: [PATCH 341/516] fix(pty): retain sends through cancellation polling

---
 packages/pty/pty-local/src/session.ts        |  4 +-
 packages/pty/pty-local/tests/session.spec.ts | 49 ++++++++++++++++++++
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index faea1ef84d..7116f44611 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -412,7 +412,7 @@ export class LocalPtySession implements PtyBackendSession {
         return
       }
       const foreground = await this.terminal.inspectForeground()
-      if (this.active !== operation || this.closing) return
+      if (this.active !== operation || this.closing || this.interrupting === operation) return
       const idleFor = Date.now() - this.lastOutputAt
       if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
         this.shellPgid = foreground.processGroupId
@@ -439,7 +439,7 @@ export class LocalPtySession implements PtyBackendSession {
         this.settleActive('inferred_idle')
       }
     } catch (error: unknown) {
-      if (this.active === operation && !this.closing) this.failActive(error)
+      if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error)
     } finally {
       this.polling = false
       const active = this.active
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 8d11f8e6f4..27abfcf74e 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -406,6 +406,7 @@ describe('LocalPtySession readiness and output', () => {
     await Promise.resolve()
     await vi.advanceTimersByTimeAsync(10)
     expect(inspections).toBe(2)
+    await vi.advanceTimersByTimeAsync(50)
     expect(operation.cancel()).toBe(true)
     let settled = false
     void operation.done.then(() => { settled = true })
@@ -423,6 +424,54 @@ describe('LocalPtySession readiness and output', () => {
     expect((await operation.done).waitReason).toBe('session_exit')
   })
 
+  it('does not let an in-flight readiness failure release a canceled send before signalling settles', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const readiness = Promise.withResolvers<never>()
+    let inspections = 0
+    terminal.inspectForeground = async () => {
+      inspections += 1
+      if (inspections === 1) return { processGroupId: 456, inputWaiting: false }
+      if (inspections === 2) return await readiness.promise
+      return { processGroupId: 456, inputWaiting: true }
+    }
+    const signalling = Promise.withResolvers<undefined>()
+    const signalled = Promise.withResolvers<number>()
+    terminal.signalForeground = async (signal) => {
+      await signalling.promise
+      const foreground = await terminal.inspectForeground()
+      if (foreground === undefined) throw new Error('cannot resolve foreground')
+      inspector.signalGroup(foreground.processGroupId, signal)
+      signalled.resolve(foreground.processGroupId)
+      return foreground.processGroupId
+    }
+
+    const operation = session.startSend({ text: 'first', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await vi.advanceTimersByTimeAsync(10)
+    expect(inspections).toBe(2)
+    expect(operation.cancel()).toBe(true)
+    let settled = false
+    void operation.done.then(() => { settled = true })
+
+    readiness.reject(new Error('inspection failed during cancellation'))
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(settled).toBe(false)
+    expect(() => session.startSend({ text: 'successor', submit: true })).toThrow(PtyError)
+
+    signalling.resolve(undefined)
+    expect(await signalled.promise).toBe(456)
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+    await session.close('test complete')
+    expect((await operation.done).waitReason).toBe('session_exit')
+  })
+
   it('signals only after an in-flight provider write lands', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()

From 6e4bdbf0df411caca431986f39f8221ba6b64664 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 16:01:38 +0800
Subject: [PATCH 342/516] fix(pty): wire persistent Bash through subprocess

---
 examples/jsonrpc-agent/persistent-tools.cordis.yml             | 3 +++
 packages/pty/tool-bash-persistent/package.json                 | 1 +
 .../pty/tool-bash-persistent/tests/loader-composition.spec.ts  | 3 +++
 pnpm-lock.yaml                                                 | 3 +++
 4 files changed, 10 insertions(+)

diff --git a/examples/jsonrpc-agent/persistent-tools.cordis.yml b/examples/jsonrpc-agent/persistent-tools.cordis.yml
index 6f42441ca7..ebe0a00e61 100644
--- a/examples/jsonrpc-agent/persistent-tools.cordis.yml
+++ b/examples/jsonrpc-agent/persistent-tools.cordis.yml
@@ -18,6 +18,9 @@
     mode: danger-full-access
     workspaceRoot: !!js process.env.DSH_CWD ?? process.cwd()
 
+- id: subprocess
+  name: '@deepseek-ai/dsh-subprocess-local'
+
 - id: pty
   name: '@deepseek-ai/dsh-pty'
 
diff --git a/packages/pty/tool-bash-persistent/package.json b/packages/pty/tool-bash-persistent/package.json
index b5cede3920..23aad9f32e 100644
--- a/packages/pty/tool-bash-persistent/package.json
+++ b/packages/pty/tool-bash-persistent/package.json
@@ -45,6 +45,7 @@
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
diff --git a/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts b/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts
index 16c4a7fea5..a69048e8d6 100644
--- a/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts
+++ b/packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts
@@ -15,6 +15,7 @@ import * as PtyLocal from '@deepseek-ai/dsh-pty-local'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import * as ToolBashPersistent from '@deepseek-ai/dsh-tool-bash-persistent'
@@ -78,6 +79,7 @@ suite('persistent Bash through a real cordis.yml Loader composition', () => {
       '  config:',
       '    mode: danger-full-access',
       `    workspaceRoot: ${JSON.stringify(root)}`,
+      "- name: '@deepseek-ai/dsh-subprocess-local'",
       "- name: '@deepseek-ai/dsh-pty-local'",
       '  config:',
       '    pollIntervalMs: 10',
@@ -104,6 +106,7 @@ suite('persistent Bash through a real cordis.yml Loader composition', () => {
       ['@deepseek-ai/dsh-pty', PtyService],
       ['@deepseek-ai/dsh-test-sandbox', PassthroughSandbox],
       ['@deepseek-ai/dsh-sandbox-policy', SandboxPolicyService],
+      ['@deepseek-ai/dsh-subprocess-local', LocalSubprocessService],
       ['@deepseek-ai/dsh-pty-local', PtyLocal],
       ['@deepseek-ai/dsh-tool-bash-persistent', ToolBashPersistent],
     ])
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ccbc67c764..666d01c1c1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4508,6 +4508,9 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess-local
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt

From d689907c121ea1f012cb18ecee835b4f567ece2e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 17:25:44 +0800
Subject: [PATCH 343/516] test(subprocess): drop obsolete cwd stubs

---
 packages/pty/pty-local/tests/index.spec.ts           | 1 -
 packages/subprocess/subprocess/tests/service.spec.ts | 2 --
 2 files changed, 3 deletions(-)

diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 15e73ddc1c..e6c4fde452 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -66,7 +66,6 @@ function terminalHandle(): SubprocessTerminalHandle {
 }
 
 class StubSubprocessService extends SubprocessService {
-  readonly cwd = '/tmp'
   async resolveExecutable(command: string): Promise<string> { return command }
   spawn(_spec: SubprocessSpawnSpec): SubprocessHandle { throw new Error('unused') }
   async spawnTerminal(_spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
diff --git a/packages/subprocess/subprocess/tests/service.spec.ts b/packages/subprocess/subprocess/tests/service.spec.ts
index 2084310da9..e4f770a9a3 100644
--- a/packages/subprocess/subprocess/tests/service.spec.ts
+++ b/packages/subprocess/subprocess/tests/service.spec.ts
@@ -16,8 +16,6 @@ import type {
  * is all an implementation owes the abstract class.
  */
 class StubSubprocessService extends SubprocessService {
-  readonly cwd = '/stub'
-
   async resolveExecutable(command: string): Promise<string> {
     return `/bin/${command}`
   }

From a662af94df3e628645bca2ca223b90e5f88bc2a6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 19:08:07 +0800
Subject: [PATCH 344/516] test(lsp): accept eager dead-slot eviction

---
 packages/lsp/lsp-local/tests/lifecycle.spec.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
index 7a30232e22..20c4bc7bf0 100644
--- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts
+++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts
@@ -282,8 +282,9 @@ describe('lsp-local end to end over a fake server', () => {
       readonly instances: ReadonlyMap<string, { readonly dead: boolean }>
     }).instances
     const instance = [...instances.values()][0]
-    if (instance === undefined) throw new Error('expected one pooled LSP instance')
-    await waitFor(async () => instance.dead)
+    // The query's finally may already have observed the exit and evicted the dead slot. When the
+    // slot remains, synchronize with its close before proving the next query replaces it.
+    if (instance !== undefined) await waitFor(async () => instance.dead)
     expect(await ctx.lsp.query(query('goToDefinition'))).toMatchObject({ kind: 'locations' })
     await ctx.fiber.dispose()
   })

From e385c11e8e7b5d5d787c457760184b42fbd23767 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 14:11:57 +0800
Subject: [PATCH 345/516] fix(pty,subprocess,lsp): address review round on
 cancellation, lookup, and contracts

- pty-local: a pre-write inspection rejection no longer releases a canceled
  send while its foreground SIGINT is in flight; the interrupt path retains
  the slot and its post-signal tail resumes polling. Regression pins the
  failure-shaped cancellation and a close-during-write release.
- pty-local: SEND_ACTIVE names which provider operation is draining; README
  states the never-settling-provider outcome (slot retained, close recovers).
- subprocess-local: resolveExecutable rejects relative paths containing
  separators instead of expanding them per PATH entry with a misleading
  not-found error; seam JSDoc pins the rule for every provider.
- subprocess-local: LocalTerminalHandle documents why the seam's
  in-flight-join promise holds without operation tracking.
- lsp-local: the oversized-source diagnostic reports the observed byte lower
  bound; README documents that processId: null trades away server-side
  orphan cleanup after a hard-killed harness.
- pty/subprocess seams: cross-reference the twin five-member signal unions.
- pty-local: TODO markers for send-state consolidation and initialize-race
  relocation.
---
 .../cordis/tool-cordis/src/api-catalog.ts     |  2 +-
 packages/lsp/lsp-local/README.i18n.yaml       |  4 +-
 packages/lsp/lsp-local/README.md              |  1 +
 packages/lsp/lsp-local/README.zh.md           | 27 +++++----
 packages/lsp/lsp-local/src/host.ts            |  6 +-
 packages/lsp/lsp-local/tests/host.spec.ts     |  4 +-
 packages/pty/pty-local/README.i18n.yaml       |  4 +-
 packages/pty/pty-local/README.md              |  2 +-
 packages/pty/pty-local/README.zh.md           |  2 +-
 packages/pty/pty-local/src/index.ts           |  3 +
 packages/pty/pty-local/src/session.ts         | 30 +++++++++-
 packages/pty/pty-local/tests/session.spec.ts  | 59 +++++++++++++++++++
 packages/pty/pty/src/types.ts                 |  6 +-
 .../subprocess-local/README.i18n.yaml         |  4 +-
 .../subprocess/subprocess-local/README.md     |  2 +-
 .../subprocess/subprocess-local/README.zh.md  |  2 +-
 .../subprocess/subprocess-local/src/index.ts  |  5 ++
 .../subprocess-local/src/terminal.ts          |  9 ++-
 .../subprocess-local/tests/local.spec.ts      |  6 ++
 packages/subprocess/subprocess/src/index.ts   |  4 +-
 packages/subprocess/subprocess/src/types.ts   |  6 +-
 21 files changed, 155 insertions(+), 33 deletions(-)

diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 2eb410acc6..21848e55e2 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -988,7 +988,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>',
-        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
+        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides. Relative paths containing separators\n * are rejected: no current consumer defines which directory they would\n * resolve against, so providers fail loud instead of guessing.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
       },
       {
         signature: 'abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle',
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index 55a9f97165..03487d5719 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-local/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/lsp/lsp-local/README.md
-README.md: ad8f4bc2318a58202f9596a18d402d2c6d45dae1
-README.zh.md: ff2686856a9e518a7fa846edf700da1b32e8a114
+README.md: 661c27d3326adfc3408b33550a63fe3ebe183a39
+README.zh.md: 83f0eaa1fb4caccc381a1623b791355b2f5c5b65
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index ad8f4bc231..93d123fac7 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -57,3 +57,4 @@ No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
 - **No confinement policy** — this package trusts the configured server and does not sandbox its process; a restricted deployment must supply appropriate process/filesystem providers or a same-world sandbox wrapper.
 - **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim.
 - **Per-server/workspace serialization latency** — parallel agents sharing one server and workspace queue behind one process; long-lived workspace processes consume memory until disposal.
+- **A hard-killed harness orphans language servers** — `initialize.processId: null` removes server-side client-PID monitoring, so servers are cleaned only by graceful service disposal; a SIGKILL'd harness leaves them running until they exit on their own.
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index ff2686856a..83f0eaa1fb 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -2,19 +2,19 @@
 
 [English](README.md) | 中文
 
-`ctx.lsp` 的**通用 stdio 语言服务器后端**。一个插件实例接受一张命名服务器表，并逐配置项注册一个隔离的提供方。它通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动，因此服务器与源文件始终位于所挂载的同一执行环境。这是通用主机，而不是语言服务器目录或安装器：部署需要显式配置命令与映射，preset 应放在 `cordis.yml` overlay 中。
+`ctx.lsp` 的**通用 stdio 语言服务器后端**。一个插件实例接受一张命名服务器表，并逐配置项注册一个隔离的提供方。它通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动，因此服务器与源文件始终位于已挂载的执行世界中。这是通用主机，而不是语言服务器目录或安装器：部署需要显式配置命令与映射，预设应放在 `cordis.yml` overlay 中。
 
 Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）。
 
 ## 功能
 
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
-- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其释放，并在新进程上重试该查询一次。
-- 每次查询都使用兼容性优先的**临时打开** 序列：通过 `ctx.fs` 解析并流式读取源文件，同时执行字节上限；随后执行 `textDocument/didOpen`（版本 1、完整文本）、所请求操作，以及位于 `finally` 中的 `textDocument/didClose`。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
-- 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方资源释放会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找结算，再排空所有队列并等待所有服务器结算。
-- 协议 shutdown 失败后，经由进程管理器 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
-- 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程与协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID 命名空间不得监控 harness 进程。
-- 使用 `ctx.fs` 提供的规范 containment、文件 URI 与流式文本校验，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
+- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其 dispose（资源释放）完成，并在新进程上重试该查询一次。
+- 每次查询都使用兼容性优先的**临时打开**序列：通过 `ctx.fs` 流式读取源文件，同时解析并限制其字节数；随后执行 `textDocument/didOpen`（版本 1、完整文本）、所请求操作，再执行位于 `finally` 中的 `textDocument/didClose`。写入 `didOpen` 失败或取消时，会在池复用该实例前将其终止。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
+- 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方 dispose 会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找完成，随后排空每条队列与每个服务器。
+- 协议 shutdown 失败后，经由子进程 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
+- 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程和协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID namespace 不得监视 harness 进程。
+- 使用 `ctx.fs` 提供的规范化包含关系、文件 URI 与流式文本验证，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
 
 ## 配置
 
@@ -24,13 +24,13 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 |---|---|---|
 | `command` | （必填） | 要 spawn 的可执行文件：绝对路径，或在加载时从子进程 PATH 解析。不使用 shell 启动。 |
 | `args` | `[]` | 传给可执行文件的参数。 |
-| `env` | `{}` | 合并到已清理 credential 的环境之上的额外 env（匹配 `KEY`／`SECRET`／`TOKEN` 的变量不会转发）；显式 `DSH_*` 条目在 seam 清除环境中同名值之后合并。 |
+| `env` | `{}` | 合并到已清理 credential 的环境之上的额外 env（匹配 `KEY`／`PASSWORD`／`SECRET`／`TOKEN` 的变量不会转发）；显式 `DSH_*` 条目在 seam 清除环境中同名值之后合并。 |
 | `extensionToLanguage` | （必填） | 小写、以点开头的扩展名 → LSP language id（例如 `{ '.ts': 'typescript' }`）。 |
 | `initializationOptions` | `null` | 转发给服务器的静态 `initialize` 选项。 |
 | `configuration` | `null` | 每个 `workspace/configuration` 配置项的静态答案。 |
 | `maxMessageBytes` | `16000000` | 从服务器接受的单条 framed 消息最大大小。 |
 | `maxStderrBytes` | `1000000` | 为诊断保留的 stderr 尾部最大大小。 |
-| `maxDocumentBytes` | `4000000` | 该主机可打开的最大源文件。 |
+| `maxDocumentBytes` | `4000000` | 该主机可打开的源文件大小上限。 |
 | `shutdownTimeoutMs` | `5000` | 升级前用于优雅 `shutdown`／`exit` 的预算。 |
 | `killGraceMs` | `2000` | 请求取消及 SIGTERM→SIGKILL 升级的宽限期。 |
 
@@ -38,11 +38,11 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 协议行为
 
-初始化会声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及定义与实现使用的 `linkSupport: true`，且不进行动态注册。服务器返回的能力具有最终决定权：不受支持的操作，或缺少临时打开／关闭的同步方式，会使查询失败。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值都属于协议错误。客户端通过静态配置回答 `workspace/configuration`，接受生命周期记账请求，并拒绝 `workspace/applyEdit`：它绝不应用编辑或运行命令。导航直接映射 `Location`，并从 `LocationLink` 的 `targetUri` + `targetSelectionRange` 映射；hover 规范化会取得有效的 `MarkupContent.value`，保留 string `MarkedString`，把带 language tag 的值渲染为围栏代码，并用一个空行连接数组。缺失结果、格式错误的范围或位置，以及格式错误的 hover 编码，都会作为结构化 `LSP_MALFORMED_RESPONSE` 错误失败。
+初始化会声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`，以及定义与实现使用的 `linkSupport: true`，且不进行动态注册。服务器返回的能力具有最终决定权：不受支持的操作，或缺少临时打开／关闭的同步方式，会使查询失败。服务器省略 `positionEncoding` 时默认为 `utf-16`；其他值都属于协议错误。客户端通过静态配置回答 `workspace/configuration`，接受生命周期记账请求，并拒绝 `workspace/applyEdit`：它绝不应用编辑或运行命令。导航直接映射 `Location`，并从 `LocationLink` 的 `targetUri` + `targetSelectionRange` 映射；hover 规范化会取得有效的 `MarkupContent.value`，保留 string `MarkedString`，把带 language tag 的值渲染为围栏代码，并用一个空行连接数组。缺失结果、格式错误的范围或位置，以及格式错误的 hover 编码，都会以结构化 `LSP_MALFORMED_RESPONSE` 错误的形式失败。
 
 ## 安全边界
 
-提供方信任其配置的服务器，不声明任何沙箱限制。它把规范身份、containment、普通文件流式读取、UTF-8 校验与文件 URI 编码委托给 `ctx.fs`；服务器启动前，系统会拒绝缺失、非普通文件、非 UTF-8、过大或规范路径位于工作区外的查询源。系统在打开流之前检查 containment，但不保证路径并发替换期间的稳定句柄身份。结果位置可以在外部，但外部路径不能成为查询源。部署必须为同一执行环境挂载文件系统与子进程提供方；分裂执行环境的组合无效。
+提供方信任其配置的服务器，不提供任何沙箱隔离。它把规范化身份、包含关系、普通文件流式读取、UTF-8 验证和文件 URI 编码委托给 `ctx.fs`；并在服务器启动前拒绝缺失、非普通文件、非 UTF-8、过大，或规范化后位于 Workspace 外部的查询源。包含关系在打开流之前评估，不承诺在并发路径替换期间保持稳定句柄身份。结果位置可以在外部，但外部路径不能成为查询源。部署必须挂载描述同一执行世界的文件系统与进程管理提供方；分裂世界组合无效。
 
 ## 模型体验
 
@@ -54,6 +54,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 已知限制与暂缓事项
 
-- **不提供隔离策略**：这个包（package）信任配置的服务器，不会对其进程执行沙箱化；受限部署必须提供适当的进程／文件系统提供方，或包装同一执行环境的沙箱。
+- **不提供隔离策略**：本包（package）信任所配置的服务器，不对其进程实施沙箱；受限部署必须提供适当的进程／文件系统提供方，或使用同一执行世界的沙箱包装层。
 - **临时打开兼容性下限**：同步能力省略打开／关闭（或声明 `None`）的服务器不受支持，即使关闭文档查询能够工作；固定的 TypeScript e2e 只建立一项兼容性下限，不代表跨语言承诺。
-- **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent 会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到释放。
+- **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent（智能体）会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到 dispose。
+- **被强制杀死的 harness 会遗留语言服务器**：`initialize.processId: null` 取消了服务器侧的客户端 PID 监视，因此服务器只能由服务的优雅 dispose 清理；被 SIGKILL 的 harness 会让它们继续运行，直到自行退出。
diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts
index ffba6a1344..ef4b56809d 100644
--- a/packages/lsp/lsp-local/src/host.ts
+++ b/packages/lsp/lsp-local/src/host.ts
@@ -107,7 +107,11 @@ export async function readHostSource(
     throwIfAborted(signal)
     throw new Error(`source "${filePath}" could not be read: ${messageOf(error)}`, { cause: error })
   }
-  if (bytes > maxDocumentBytes) throw new Error(`source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit`)
+  if (bytes > maxDocumentBytes) {
+    throw new Error(
+      `source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit; reading stopped after ${bytes} bytes`,
+    )
+  }
   throwIfAborted(signal)
   return {
     fileUrl: fs.fileUrl(target),
diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts
index c97defc086..c06b6d9df8 100644
--- a/packages/lsp/lsp-local/tests/host.spec.ts
+++ b/packages/lsp/lsp-local/tests/host.spec.ts
@@ -156,10 +156,10 @@ describe('readHostSource', () => {
     await expect(readSource('.')).rejects.toThrow(/not a regular file/)
   })
 
-  it('rejects an oversized source', async () => {
+  it('rejects an oversized source and reports the observed lower bound', async () => {
     await writeFile(join(ws, 'big.ts'), 'x'.repeat(100))
     await expect(readSource('big.ts', 10)).rejects.toMatchObject({
-      message: 'source "big.ts" exceeds the 10-byte limit',
+      message: 'source "big.ts" exceeds the 10-byte limit; reading stopped after 100 bytes',
     })
   })
 
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index 2689103443..bd835a091d 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/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/pty/pty-local/README.md
-README.md: 92a3d7be68ada6f38ab3c4ca5bdd2622ebefc8ee
-README.zh.md: 016043f7842df8bb963cdc5eea015666c9ce6941
+README.md: 5acc92853e6e8fcb8938c48e391559bf4a28fb75
+README.zh.md: 353c2a4bdac7e8402fc63071dfb6fb85dcff66d5
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 92a3d7be68..3b1112b025 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -10,7 +10,7 @@ The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. If a provider write is already in flight, signalling waits for it to settle; a rejected write sends no signal. The canceled send retains its slot until the write and foreground signalling settle, so a successor cannot receive either late bytes or that signal. The absolute deadline remains armed while cancellation waits. A signal failure is a terminal transport failure and rejects the active send. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close rejects new public signals, stops readiness polling, and awaits the handle's provider-owned complete-session termination before settling the active send as `session_exit`.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. If a provider write is already in flight, signalling waits for it to settle; a rejected write sends no signal. The canceled send retains its slot until the write and foreground signalling settle, so a successor cannot receive either late bytes or that signal. A provider write or signal that never settles therefore retains the slot indefinitely; closing the session (`terminal_close`) is the recovery. The absolute deadline remains armed while cancellation waits. A signal failure is a terminal transport failure and rejects the active send. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close rejects new public signals, stops readiness polling, and awaits the handle's provider-owned complete-session termination before settling the active send as `session_exit`.
 
 ## Model Experience
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 016043f784..a23a2f3338 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -10,7 +10,7 @@
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送时，系统会先把排队输入标记为已取消，再要求终端句柄向当前前台进程组发送真正的 `SIGINT`；异步写入前检查即使随后结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待其结算；写入被拒绝时不会发送信号。已取消的 send 会保留其位置，直到写入与前台信号发送都结算，因此后继 send 不会收到延迟字节或该信号。取消等待期间，绝对 deadline 仍保持启用。信号发送失败是终端传输失败，会拒绝活跃 send。取消绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待由句柄提供方负责的完整会话终止，然后才把活跃 send 结算为 `session_exit`。
+取消发送时，系统会先把排队输入标记为已取消，再要求终端句柄向当前前台进程组发送真正的 `SIGINT`；异步写入前检查即使随后结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待其结算；写入被拒绝时不会发送信号。已取消的 send 会保留其位置，直到写入与前台信号发送都结算，因此后继 send 不会收到延迟字节或该信号。因此，永不结算的提供方写入或信号会无限期保留该位置；恢复手段是关闭会话（`terminal_close`）。取消等待期间，绝对 deadline 仍保持启用。信号发送失败是终端传输失败，会拒绝活跃 send。取消绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待由句柄提供方负责的完整会话终止，然后才把活跃 send 结算为 `session_exit`。
 
 ## 模型体验
 
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index f91db5d386..b1e0e6edbd 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -82,6 +82,9 @@ function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSp
   }).argv
 }
 
+// TODO(pty-initialize-race-home): Fold this outer abort race into
+// LocalPtySession.initialize when the send-state consolidation lands; the
+// session already owns the send lifecycle the race protects.
 async function initializeSession(session: LocalPtySession, signal?: AbortSignal): Promise<void> {
   if (signal === undefined) {
     await session.initialize(signal)
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 7116f44611..25ed8fe586 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -162,6 +162,11 @@ export class LocalPtySession implements PtyBackendSession {
   private readonly outputEnded = Promise.withResolvers<void>()
   private readonly completion: Promise<void>
   private statusValue: PtySessionStatus = { kind: 'running' }
+  // TODO(pty-send-state-consolidation): Fold the per-send fields below
+  // (active/activeTimer/activeDeadlineTimer/activeAbort/interrupting/
+  // activeWrite/pollingReady/polling) into one send-lifecycle owner; the
+  // cancellation/readiness interplay now has enough pinned tests to carry
+  // that refactor safely.
   private active: LocalSendOperation | undefined
   private activeTimer: NodeJS.Timeout | undefined
   private activeDeadlineTimer: NodeJS.Timeout | undefined
@@ -220,7 +225,14 @@ export class LocalPtySession implements PtyBackendSession {
   startSend(request: PtySendRequest): PtySendOperation {
     if (this.closing) throw new Error('PTY session is closing')
     if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
-    if (this.active !== undefined) throw new PtyError('PTY session already has an active send or draining provider operation', 'SEND_ACTIVE')
+    if (this.active !== undefined) {
+      const draining = this.activeWrite !== undefined
+        ? ' or draining provider write'
+        : this.interrupting !== undefined
+          ? ' or draining foreground interrupt'
+          : ''
+      throw new PtyError(`PTY session already has an active send${draining}`, 'SEND_ACTIVE')
+    }
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
     const operation = new LocalSendOperation(
@@ -246,8 +258,22 @@ export class LocalPtySession implements PtyBackendSession {
   }
 
   private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
+    let foreground: SubprocessTerminalForeground | undefined
+    try {
+      foreground = await this.terminal.inspectForeground()
+    } catch (error: unknown) {
+      // A pre-write inspection failure while cancellation owns the slot must not
+      // release it: interruptOnce's in-flight foreground signal could land on a
+      // successor's foreground group. The interrupt path's post-signal tail
+      // resumes polling, whose guarded catch propagates a persistent failure.
+      // A retained settled operation implies that same in-flight interrupt, so
+      // this guard admits only an unsettled active send.
+      if (this.active === operation && !this.closing && this.interrupting !== operation) {
+        this.failActive(error)
+      }
+      return
+    }
     try {
-      const foreground = await this.terminal.inspectForeground()
       if (this.active !== operation || this.closing || this.interrupting === operation) return
       operation.setInitialForeground(foreground)
       const input = `${request.text}${request.submit ? '\r' : ''}`
diff --git a/packages/pty/pty-local/tests/session.spec.ts b/packages/pty/pty-local/tests/session.spec.ts
index 27abfcf74e..0ca1835e53 100644
--- a/packages/pty/pty-local/tests/session.spec.ts
+++ b/packages/pty/pty-local/tests/session.spec.ts
@@ -345,6 +345,47 @@ describe('LocalPtySession readiness and output', () => {
     await operation.done
   })
 
+  it('retains a canceled send when the pre-write inspection rejects while its signal is in flight', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const inspector = new FakeInspector()
+    const session = makeSession(terminal, inspector, config())
+    await initialize(session, terminal)
+
+    const failed = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await failed.promise
+    const uncanceled = session.startSend({ text: 'plain failure', submit: true })
+    failed.reject(new Error('inspect failed before write'))
+    await expect(uncanceled.done).rejects.toThrow('inspect failed before write')
+
+    terminal.inspectForeground = FakeTerminal.prototype.inspectForeground.bind(terminal)
+    const inspection = Promise.withResolvers<{ processGroupId: number; inputWaiting: boolean }>()
+    terminal.inspectForeground = async () => await inspection.promise
+    const signalGate = Promise.withResolvers<undefined>()
+    terminal.signalForeground = async (signal) => {
+      await signalGate.promise
+      inspector.signalGroup(456, signal)
+      return 456
+    }
+    const controller = new AbortController()
+    const operation = session.startSend({ text: 'must stay owned', submit: true, signal: controller.signal })
+    controller.abort()
+    inspection.reject(new Error('transient inspection failure'))
+    await Promise.resolve()
+    await Promise.resolve()
+
+    // The slot stays reserved while the cancellation's foreground signal is in flight.
+    expect(() => session.startSend({ text: 'successor', submit: true })).toThrow('active send')
+    terminal.inspectForeground = async () => ({ processGroupId: 456, inputWaiting: false })
+    signalGate.resolve(undefined)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(inspector.groups).toContainEqual([456, 'SIGINT'])
+
+    terminal.emitData('\x1b]133;D;130\x07dsh> ')
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+  })
+
   it('retains a canceled send until asynchronous foreground signalling settles', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
@@ -1176,6 +1217,24 @@ describe('LocalPtySession bounds, signals, and teardown', () => {
   })
 
   it('settles a closing send when provider termination cancels inspection', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    await initialize(session, terminal)
+    const write = Promise.withResolvers<undefined>()
+    terminal.write = async () => { await write.promise }
+    const writeOperation = session.startSend({ text: 'pending write', submit: true })
+    await Promise.resolve()
+    await Promise.resolve()
+    await session.close('pending write')
+    expect((await writeOperation.done).waitReason).toBe('session_exit')
+    // The rejection lands after close released the send; it must stay contained.
+    write.reject(new Error('write rejected during close'))
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+
+  it('settles a closing send when provider termination cancels a pending inspection', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
     const session = new LocalPtySession(terminal, config())
diff --git a/packages/pty/pty/src/types.ts b/packages/pty/pty/src/types.ts
index a4985ead93..0317bb9d43 100644
--- a/packages/pty/pty/src/types.ts
+++ b/packages/pty/pty/src/types.ts
@@ -28,7 +28,11 @@ export class PtyBackendCleanupError extends AggregateError {
 /** Why one interactive send returned control to its caller. */
 export type PtyWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
 
-/** Signals the model-facing PTY surface permits for foreground process groups. */
+/**
+ * Signals the model-facing PTY surface permits for foreground process groups.
+ * Kept member-identical to `SubprocessTerminalSignal` in
+ * `@deepseek-ai/dsh-subprocess` without a cross-seam dependency; change both together.
+ */
 export type PtySignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP'
 
 /** Top-level PTY process status, independent of a send's wait reason. */
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index ee90e9e607..87a95c3170 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: 85103c2634bd35b188acd71c7f037e3678a2542e
-README.zh.md: 505eac4f2650e6723e042cdb1122f9ef504ad7df
+README.md: b901a69d6cfd45a084711ba0d32e555c481fd626
+README.zh.md: 5723dc99ff955c5f4b07ea96e7d2134100d9fd6a
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index c211ca26f1..9e3e8f7f2d 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -10,7 +10,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
-- **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative PATH entries resolve from the host process cwd.
+- **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative paths containing separators are rejected at the seam, and relative PATH entries resolve from the host process cwd.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
 - **Terminate-and-join disposal** — the service retains live handles only so its own disposal can escalate every running tree and await its exit; settled and spawn-failed handles leave the live set on settlement.
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 505eac4f26..5723dc99ff 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -10,7 +10,7 @@
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；相对 PATH 条目从宿主进程 cwd 解析。
+- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在接缝处被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
 - **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index 4a740a1e3b..e441944225 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -77,6 +77,11 @@ export class LocalSubprocessService extends SubprocessService {
     signal?.throwIfAborted()
     const environment = childEnv(env)
     const absolute = isAbsolute(command)
+    if (!absolute && (command.includes('/') || (process.platform === 'win32' && command.includes('\\')))) {
+      throw new Error(
+        `subprocess-local: command ${JSON.stringify(command)} is a relative path; use an absolute path or a bare PATH name`,
+      )
+    }
     const candidates = absolute ? [command] : this.executableCandidates(command, environment)
     for (const candidate of candidates) {
       signal?.throwIfAborted()
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 53c531675f..2d3d0bb78e 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -24,7 +24,14 @@ function signalName(number: number | undefined): NodeJS.Signals | null {
   return null
 }
 
-/** A local terminal whose process-session ownership stays below the PTY backend. */
+/**
+ * A local terminal whose process-session ownership stays below the PTY backend.
+ * The seam's terminate() promise — no write, inspection, or signal in flight
+ * after settlement — holds here without operation tracking only because every
+ * handle call completes synchronously under the hood (node-pty write, ps-based
+ * inspection). A first genuinely asynchronous step in any handle call must add
+ * the tracking a remote provider needs.
+ */
 export class LocalTerminalHandle implements SubprocessTerminalHandle {
   readonly pid: number
   readonly output = new PassThrough()
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index a0455edef0..347b9c9330 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -32,6 +32,10 @@ describe('LocalSubprocessService', () => {
       PATH: relative(process.cwd(), dirname(process.execPath)) || '.',
     })).toBe(process.execPath)
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('must be non-empty')
+    await expect(ctx.subprocess.resolveExecutable('./bin/tsserver'))
+      .rejects.toThrow('is a relative path')
+    await expect(ctx.subprocess.resolveExecutable('node_modules/.bin/server'))
+      .rejects.toThrow('is a relative path')
     await expect(ctx.subprocess.resolveExecutable('dsh-command-that-does-not-exist', { PATH: '' }))
       .rejects.toThrow('was not found on PATH')
     await expect(ctx.subprocess.resolveExecutable('/dsh-absolute-command-that-does-not-exist'))
@@ -61,6 +65,8 @@ describe('LocalSubprocessService', () => {
         .toEqual(['/explicit/tool.EXE'])
       expect(candidates('tool.exe', {})).toEqual([resolve(process.cwd(), 'tool.exe')])
       expect(candidates('tool', { PATH: '/bin' })).toHaveLength(4)
+      await expect(ctx.subprocess.resolveExecutable(String.raw`bin\server.exe`))
+        .rejects.toThrow('is a relative path')
     } finally {
       platform.mockRestore()
       await fiber.dispose()
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index 14866c9784..6b9904078f 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -107,7 +107,9 @@ export abstract class SubprocessService extends Service {
   /**
    * Resolve one configured executable in this provider's execution world.
    * Absolute paths are verified; bare names use the provider's scrubbed PATH
-   * plus explicit environment overrides.
+   * plus explicit environment overrides. Relative paths containing separators
+   * are rejected: no current consumer defines which directory they would
+   * resolve against, so providers fail loud instead of guessing.
    * @param command - absolute executable path or bare PATH name.
    * @param env - explicit environment entries used for lookup.
    * @param signal - aborts remote or local lookup.
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index 9801bf2f49..2aa2de0c91 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -193,7 +193,11 @@ export interface SubprocessHandle {
   waitForExit(signal?: AbortSignal): Promise<boolean>
 }
 
-/** Signals supported by the terminal-process primitive. */
+/**
+ * Signals supported by the terminal-process primitive. Kept member-identical
+ * to `PtySignal` in `@deepseek-ai/dsh-pty` without a cross-seam dependency;
+ * change both together.
+ */
 export type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP'
 
 /** A fully specified terminal-process spawn. */

From 18ab9f6db201468d6cc68de3a7f4a6176e97b93c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 20:34:31 +0800
Subject: [PATCH 346/516] fix(rebase): migrate the replayed stack onto current
 master APIs

The linear replay carried each commit's own lineage, so this checkpoint
restores the master-owned surfaces the conflicted regions clobbered and
migrates branch-owned code to master's post-rebase APIs:

- rebuild subprocess-local spawn.ts on master's tree-exit-observer
  machinery, keeping the branch's win32 childEnv key semantics and the
  Linux zombie-quiescence probe; the zombie test reaps its survivor
  directly since a confirmed-absent verdict is a permanent
  no-more-signals boundary
- migrate pty-local test stubs to the Inbox-model Agent interface,
  Session.create, runnerFailureRules, and the new turn/start payload
- implement the seam's resolveExecutable/spawnTerminal abstracts in the
  new pwsh-local and tool-fs-search test fakes
- restore code-runtime, atomic-write, pwsh-local, and app-boot to
  master's exact content (the net-zero code-runtime churn is pruned
  from this history) and drop rename-detection graft debris
- re-apply the PR's architecture rows and execution-world paragraph,
  re-record bilingual pairings, regenerate catalogs, and reconcile the
  lockfile
---
 ...0-canonical-tool-output-contract.i18n.yaml |   2 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |   4 +-
 .../feature/2026-06-15-code-mode.md           |  16 +-
 .../feature/2026-06-15-code-mode.zh.md        |  42 +-
 docs/architecture.md                          |   6 +-
 docs/architecture.zh.md                       |   6 +-
 docs/capability-seams.md                      |  67 ++-
 docs/cordis-catalog/services.md               |  58 ++-
 .../core-data-structures/filesystem.i18n.yaml |   2 +-
 docs/core-data-structures/lsp.i18n.yaml       |   2 +-
 .../core-data-structures/subprocess.i18n.yaml |   4 +-
 docs/core-data-structures/subprocess.zh.md    |  30 +-
 packages/README.i18n.yaml                     |   4 +-
 .../bash/pwsh-local/tests/executor.spec.ts    |   2 +
 packages/bash/pwsh-local/tsconfig.json        |  10 +-
 .../code-runtime-worker/README.md             |   2 +-
 .../code-runtime-worker/tests/runtime.spec.ts |  21 -
 .../fs/tool-fs-search/tests/tools.spec.ts     |   2 +
 packages/lsp/lsp-local/README.md              |   2 +-
 packages/pty/pty-local/README.md              |  10 +-
 packages/pty/pty-local/README.zh.md           |  10 +-
 packages/pty/pty-local/tests/index.spec.ts    |  38 +-
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |   8 +-
 .../subprocess/subprocess-local/README.zh.md  |   6 +-
 .../subprocess/subprocess-local/src/spawn.ts  |  75 +++-
 .../subprocess-local/tests/spawn.spec.ts      |   8 +-
 packages/typert/README.i18n.yaml              |   6 +-
 packages/ui/app-boot/tsdown.config.ts         |   8 +-
 packages/util/atomic-write/README.i18n.yaml   |   6 +-
 .../src/runner-source.generated.ts            |   6 -
 packages/util/atomic-write/src/runner.ts      | 401 ------------------
 pnpm-lock.yaml                                |  25 +-
 scripts/gen-doc-graphs.ts                     | 276 ++++++++----
 vitest.config.ts                              |  86 +++-
 35 files changed, 582 insertions(+), 673 deletions(-)
 delete mode 100644 packages/util/atomic-write/src/runner-source.generated.ts
 delete mode 100644 packages/util/atomic-write/src/runner.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
index b8db543510..680d2dd94a 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
 2026-07-20-canonical-tool-output-contract.md: 2429e1c141ad8c8ee932c6d654a6ba74bc4f7618
-2026-07-20-canonical-tool-output-contract.zh.md: fd1e55eab38e5929a2dc104073b49f9de7a493e2
+2026-07-20-canonical-tool-output-contract.zh.md: 26653ea769b8a642b70c4d3dd2f5ab907a70bd85
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 8773a797e9..bc05e497c5 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: b6a24ecd9700e32912b8112b59cbd8b6ab131eb5
-2026-06-15-code-mode.zh.md: 4d0a4cf8fa31cf9d9954e5bd95f823dfc0668444
+2026-06-15-code-mode.md: 99bbed3edab32512f88ece9694d6519a1f89c2dd
+2026-06-15-code-mode.zh.md: ca1bbe9ed3e412186763d1ed4fca9ed06669d4c3
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index b6a24ecd97..99bbed3eda 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-15-code-mode.zh.md)
 
 ## Problem
 
-In the registry's native presentation, the agent loop advertises every visible capability as a JSON-schema function definition. `ToolRegistry` contributes its schemas to the system-prompt assembly, the assembly's `tools` land on the wire (and in the logged request header), the model invokes one `tool-call` block per step, and the loop dispatches each call through `ctx.tools.execute()` **sequentially** (parallel tool execution is an explicit open TODO in `dsh-tools` and [docs/architecture.md](../../../../docs/architecture.md)), with **every** intermediate `tool-result` re-entering the model's context on the next request.
+In the registry's native presentation, the agent loop advertises every visible capability as a JSON-schema function definition. `ToolRegistry` contributes its schemas to the system-prompt assembly, the assembly's `tools` land on the wire (and in the logged request header), the model invokes one `tool-call` block per step, and at the time of this note the loop dispatched each call through `ctx.tools.execute()` **sequentially** (parallel tool execution was an open TODO then; bounded parallel dispatch has since shipped — the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md), the rolling pool in [docs/architecture.md](../../../../docs/architecture.md)) — with **every** intermediate `tool-result` re-entering the model's context on the next request.
 
 For multi-step tool work this is token-heavy and serial. The model cannot compose tools — loop over a result set, branch on an intermediate value, fan out, post-process — without a full model round-trip per call, and each round-trip drags the entire intermediate result back into context whether the model needs it or not.
 
@@ -32,7 +32,7 @@ This note owns Code Mode's presentation, composition, isolation, and settlement
 
 **Interaction with `toolOrder`, stated up front:** a configured `systemPrompt.toolOrder` naming native capabilities rejects every assembly under `mode: 'code'`, because those names are outside that mode's wire-validation universe. This is correct behavior, not a bug: a deployment using Code Mode updates its order config or drops it.
 
-**SDK prompt section.** In `'code'` and `'both'`, the lazy `tools:sdk` section in the tool-guidance order band renders TypeScript declarations plus fixed usage instructions for the scope's visible capabilities. It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
+**SDK prompt section.** In `'code'` and `'both'`, the lazy `tools:sdk` section in the tool-guidance order band renders the loaded runtime's language declarations plus fixed usage instructions for the scope's visible capabilities (TypeScript by default; the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md) added Python and the `ctx.codeRuntime.language` renderer table). It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
 
 **Assembly ownership.** `run_code` and `tools:sdk` enter the trusted `system-prompt/assemble` waterfall as normal assembly inputs. A scoped `tools:sdk` section may shadow the global default before dispatch, and a listener may remove or replace either contribution. The waterfall's returned assembly is final, so whoever changes these inputs owns preserving a viable Code Mode protocol when the deployment expects Code Mode to remain usable; no restoration pass overrides deliberate composition.
 
@@ -48,7 +48,7 @@ Under `'code'` and `'both'` the registry owns `run_code` as a reserved presentat
 
 **Sub-call contexts are deferred through the parent.** Injecting inside `run_code` would break parent call/result adjacency, so `ToolRunContext.deferContext()` collects every sub-result `additionalContexts` entry in dispatch order. The registry carries that array even when the program later throws, and the loop appends each entry only after the outer result and every sibling result in the step. An outer post-execute block discards tool-deferred entries and exposes only contexts explicitly attached by the blocking decision.
 
-**Concurrency is serialized.** Each run owns a dispatch queue, so even `Promise.all` executes tool calls in submission order. Settlement abandons queued calls that have not started. Parallelism requires per-tool concurrency-safety metadata.
+**Concurrency is bounded, not serialized.** Each run owns a dispatch queue that starts calls strictly in submission order and classifies each one through `registry.executionMode`, the same fail-closed `isConcurrencySafe` contract the native loop uses. Consecutive parallel-classified calls overlap up to `maxParallelSubCalls` (default 10; `1` restores serial dispatch); an exclusive call drains the pool and runs alone. Settlement abandons queued calls that have not started. This note shipped the serialized placeholder; the [live-parallel Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) owns the scheduler that replaced it.
 
 **Presentation.** `run_code`'s render intent is decided here per the [render-intent Agent Note](../architecture/2026-07-02-tool-render-intent-union.md): `presentCall` creates a `generic` card with `kind: 'execute'`, the program text as its title, and the same program text as `rawInput`; `run_code` intentionally declares no `presentResult`, so the TUI and host/client runtime (Web) complete that card through their generic raw-content fallback using the final durable `tool/result.content`, including captured logs plus the returned value, failure, or post-policy spill preview. This is not a `terminal` card: that card's semantics are "a shell command in a working directory", which a program is not. See the [result-card completeness note](../../archived/bug-fix/2026-07-20-code-mode-result-card-completeness.md).
 
@@ -64,7 +64,7 @@ Each sub-dispatch appends a log-only `tool/code-dispatch-start` event at pool en
 - `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }` — the runtime exposes each namespace as a global object of async functions inside the program; the optional descriptor asks the runtime to inject a real program-visible rejection class without teaching the seam consumer-specific names. `CodeJsonValue` is this dependency-light seam's structural lossless-JSON type, so binding arguments and resolutions cross the implementation's serialization boundary whole.
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }` — program execution outcomes resolve as the `error` field. `run()` may reject only for caller/seam misuse (for example a duplicate binding namespace); consumers still contain a non-conforming backend rejection at their own error boundary.
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }` — orthogonal outcomes reported independently per [defensive patterns](../../../../docs/defensive-patterns.md); a timed-out run is not an exception, an abort is not a timeout, a lossy completion is not an overflow, and a substrate exit is none of them.
-- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for the shipped backend; a Python backend would say so, and pair with its own SDK generator on the presentation side) and `isolation` (`'worker-thread'` for the shipped backend; `'process'`, `'container'`, … for future ones). `dsh-tools` requires `language === 'typescript'` in the MVP — its codegen emits TS — and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
+- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for the first backend; a Python backend says `'python'` and pairs with its own SDK generator on the presentation side) and `isolation` (`'worker-thread'` for the shipped backend; `'process'`, `'container'`, … for future ones). `dsh-tools` accepts any `language` with a registered SDK renderer and `run_code` flavor (TypeScript and Python ship; see the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md)) and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
 
 Requests contain every runtime input; implementations own validated timeout and cap defaults. The registry looks up the optional runtime only when Code Mode is assembled, so native mode does not depend on one. Missing or language-incompatible runtimes fail loudly. Alternate substrates or languages can replace the implementation behind the same seam, paired with the appropriate SDK generator.
 
@@ -85,11 +85,11 @@ The worker runtime provides containment, not a security boundary: model code can
 
 ### What the model sees
 
-The SDK instructs the model to write an async erasable-TypeScript body, call tools through `await tools.name(args)`, catch rejected tool calls when needed, and return or log only the output that should re-enter context. Calls remain sequential even under `Promise.all`. The declaration prefix can be as large as native schemas, especially in `'both'`, but remains stable for provider caching.
+The SDK instructs the model to write an async body in the loaded runtime's language (an erasable-TypeScript body by default; a Python `async` body under a Python runtime — see the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md)), call tools through `await tools.name(args)`, catch rejected tool calls when needed, and return or log only the output that should re-enter context. Both flavors state the same contract in their own primitive: independent read-only calls MAY overlap under `Promise.all` (TypeScript) or `asyncio.gather` (Python), mutating calls run alone in submission order, and dependent work sequences with `await`. The declaration prefix can be as large as native schemas, especially in `'both'`, but remains stable for provider caching.
 
 ## Consequences
 
-Deployments switching to `'code'` must update any native-only `toolOrder`. Assembly listeners own the integrity of any rewritten protocol surface. Sub-dispatch remains serialized, while per-call contexts retain their source, envelope, and metadata through the outer result.
+Deployments switching to `'code'` must update any native-only `toolOrder`. Assembly listeners own the integrity of any rewritten protocol surface. Sub-dispatch starts in submission order under a bounded overlap pool, while per-call contexts retain their source, envelope, and metadata through the outer result.
 
 ## Testing
 
@@ -106,7 +106,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Result elision / summarization over native tool-calling.** Addresses only the context-bloat half of the problem: trimming old `tool-result`s is cheap to add as a logged surface replacement under reconstructable requests, but still pays one model round-trip per call and cannot express loops, branches, or joins. Complementary, not competing; it can layer under Code Mode for residual native calls.
 
-**Parallel native dispatch in the loop.** The other answer to round-trip cost; still valid future work (the open TODO), still blocked on concurrency-safety metadata, and still no composition — it parallelizes calls the model already decided on in one step. Code Mode's serialized-queue decision keeps the two compatible: when the metadata lands, both native parallel dispatch and per-tool binding parallelism unlock together.
+**Parallel native dispatch in the loop.** The other answer to round-trip cost at decision time; it was blocked on concurrency-safety metadata and offers no composition either way — it parallelizes calls the model already decided on in one step. Code Mode's queue decision kept the two compatible, and that is how it played out: the metadata landed as `isConcurrencySafe` (the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md)), and native rolling-pool dispatch and per-tool binding parallelism unlocked on the same classifier.
 
 **Always-exclusive (Cloudflare-faithful, no mode).** Rejected for this SDK's primary consumer: a coding agent's bread-and-butter single calls (`bash`, `read`, `edit`) are already ideal as native calls, and forcing every edit through a program taxes the common case. The mode config keeps the faithful form (`'code'`) one line away without imposing it.
 
@@ -128,6 +128,6 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Large lossless JSON values can exhaust memory.** Tool bindings snapshot lossless JSON before dispatch and return canonical JSON resolutions whole. The runtime validates both sides of the worker port and applies no per-binding byte cap; structured-clone cost and process or worker memory are the practical bounds. The combined outer-output ledger for logs, the completion value, and a failure diagnostic is the only byte-capped boundary.
 
-**Serialized-only sub-dispatch.** `Promise.all` gains no wall-clock parallelism yet, only fewer round-trips; models may over-expect. The instructions state it; lifting it is tied to the same concurrency-safety metadata the native parallel-dispatch TODO needs.
+**Sub-dispatch overlap is bounded by tool safety claims, not by the caller.** A program's `Promise.all` or `asyncio.gather` buys wall-clock parallelism only across calls the tool itself classifies concurrency-safe; a run of exclusive calls still costs its round-trips in sequence, and models may over-expect. Both flavors' SDK instructions state the real contract. This note shipped the serialized placeholder that made the risk absolute; the [live-parallel Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) owns the scheduler and its overlap cap.
 
 **Budget metering reads the event loop, not a flag.** Busy-time polling (`eventLoopUtilization()`) is coarser than an exact CPU meter — a budget expires up to one poll interval late — and its correctness claim ("a pending dispatch cannot pause it") is load-bearing against a hostile program. Both sides are unit-tested (hot loop with a pending decoy dispatch dies at `computeMs`; idle-on-slow-binding survives to `maxWallMs`), and the poll interval is an internal constant, not config — nothing a deployment could mis-tune into a bypass. `maxWallMs` is config, and it reaches `setTimeout`, which clamps a delay above `MAX_TIMER_DELAY_MS` (2^31-1 ms) to 1 ms; a positivity check alone therefore accepts a 25-day ceiling that expires on the first tick and times out every run. The worker runtime range-checks the field at load for that reason. `computeMs` needs no upper bound because it is compared against measured utilization instead of being handed to a timer.
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index 4d0a4cf8fa..ca1bbe9ed3 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-在注册表的原生呈现方式下，agent loop（智能体循环）将每个可见能力以 JSON Schema 函数定义的形式通告给模型。`ToolRegistry` 将其 schema 贡献给系统提示词组装，组装结果中的 `tools` 落到协议格式（wire format）上（也记录在请求头日志中），模型每步调用一个 `tool-call` 块，循环通过 `ctx.tools.execute()` **逐个**分发每次调用（并行工具执行是 `dsh-tools` 和 [docs/architecture.md](../../../../docs/architecture.md) 中明确标注的 open TODO），且**每一个**中间 `tool-result` 都会在下一次请求时重新进入模型上下文。
+在注册表的原生呈现方式下，agent loop（智能体循环）将每个可见能力以 JSON Schema 函数定义的形式通告给模型。`ToolRegistry` 将其 schema 贡献给系统提示词组装，组装结果中的 `tools` 落到协议格式（wire format）上（也记录在请求头日志中），模型每步调用一个 `tool-call` 块，而在本 note 写作时，循环通过 `ctx.tools.execute()` **逐个**分发每次调用（并行工具执行当时还是 open TODO；此后有界的并行分发已经交付——见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)，以及 [docs/architecture.md](../../../../docs/architecture.md) 中的 rolling pool）——且**每一个**中间 `tool-result` 都会在下一次请求时重新进入模型上下文。
 
 对于多步工具操作，这种方式 token 开销大且串行。模型无法组合工具——遍历结果集、根据中间值分支、扇出、后处理——每次调用都需要一次完整的模型往返，而每次往返都会把完整的中间结果拖回上下文，不管模型是否需要。
 
@@ -19,7 +19,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 三项决策，各自在下方独立小节中展开：
 
 1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
-2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
+2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包`@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
 3. **交付的实现是 `@deepseek-ai/dsh-code-runtime-worker`**：每次运行 spawn 一个全新的 Node worker 线程，对模型的 TypeScript 进行 type-strip 后执行，绑定通过消息端口桥接，环境为空，堆/输出/时间上限可配置，并支持硬终止。其信任姿态在设计上等同于 bash——无需 unsafe-acknowledgement flag——因为 harness 已经交付了 `dsh-bash-local`，后者以严格*更高*的环境权限执行模型编写的任意 shell 命令。
 
 本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
@@ -32,7 +32,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **与 `toolOrder` 的交互，预先说明：** 如果配置的 `systemPrompt.toolOrder` 引用了原生能力名称，在 `mode: 'code'` 下会拒绝所有组装，因为那些名称不在该模式的协议校验范围内。这是正确行为而非 bug：使用 Code Mode 的部署需要更新其 order 配置或移除它。
 
-**SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染 TypeScript 声明加固定的使用说明。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
+**SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染所加载运行时语言的声明加固定的使用说明（默认 TypeScript；[语言分发 note](2026-07-31-code-mode-language-dispatch.md) 加入了 Python 与按 `ctx.codeRuntime.language` 选择的渲染器表）。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
 
 **组装所有权。** `run_code` 和 `tools:sdk` 作为正常的组装输入进入受信任的 `system-prompt/assemble` waterfall。一个 scoped 的 `tools:sdk` 段可以在分发前遮蔽全局默认值，监听器也可以移除或替换任一贡献。waterfall 返回的组装结果是最终的，因此修改这些输入的人有责任在部署期望 Code Mode 可用时保持协议面的完整性；没有恢复 pass 会覆盖有意的组合。
 
@@ -40,7 +40,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 ### run_code 工具与分发桥
 
-在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
+在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调性守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
 
 1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，进入原生契约的分发池（调度设计由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责），以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `tool/code-dispatch-start`/`tool/code-dispatch` 事件对，其中结算侧携带完整渲染后的结果内容。成功时返回工具最终的规范 JSON 值；失败则变为程序可见的 `ToolCallError`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。
 2. **运行程序**：`ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`。运行时接收的是 run 级别的 signal 而非仅调用方的外层 signal，因此外层 run 以任何方式结算都会同时 abort 运行时内部的工作。
@@ -48,7 +48,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **子调用上下文通过父调用延后。** 在 `run_code` 内部注入会破坏父调用/结果的相邻性，因此 `ToolRunContext.deferContext()` 按分发顺序收集每个子结果的 `additionalContexts` 条目。即使程序后来抛出异常，注册表仍携带该数组；循环只在外层结果与步骤中所有兄弟结果之后追加每个条目。外层 post-execute 阻止会丢弃工具延后的条目，只暴露阻止 decision 显式附加的上下文。
 
-**并发被序列化。** 每次 run 拥有一个分发队列，因此即使 `Promise.all` 也按提交顺序执行工具调用。结算时放弃尚未开始的排队调用。并行化需要每个工具的并发安全元数据。
+**并发是有界的，而非被序列化。** 每次 run 拥有一个分发队列，严格按提交顺序启动调用，并通过 `registry.executionMode` 对每个调用分类——与原生循环所用的 fail-closed `isConcurrencySafe` 契约相同。连续的 parallel 类调用最多重叠 `maxParallelSubCalls` 个（默认 10；设为 `1` 恢复串行分发）；exclusive 类调用会排空池并单独运行。结算时放弃尚未开始的排队调用。本 note 交付的是被序列化的占位实现；取代它的调度器由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
 
 **呈现。** `run_code` 的 render intent 按[呈现意图 Agent Note](../architecture/2026-07-02-tool-render-intent-union.md)在此决定：`presentCall` 创建一个 `generic` 卡片，`kind: 'execute'`，以程序文本作为标题，并将同一程序文本作为 `rawInput`；`run_code` 有意不声明 `presentResult`，因此 TUI 和宿主/客户端运行时（Web）会通过通用原始内容回退机制，使用最终持久化的 `tool/result.content` 补全该卡片，其中包括捕获的日志，以及返回值、失败信息或 post-policy 输出落盘预览。这不是 `terminal` 卡片：该卡片的语义是「工作目录中的 shell 命令」，程序不是。参见[结果卡片完整性说明](../../archived/bug-fix/2026-07-20-code-mode-result-card-completeness.md)。
 
@@ -61,35 +61,35 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 `packages/code-runtime/code-runtime/`——`@deepseek-ai/dsh-code-runtime`，仅依赖 `cordis`。一个抽象的 `CodeRuntime extends Service`（`super(ctx, 'codeRuntime')`）加上词汇：
 
 - `CodeRunRequest = { program: string; bindings: CodeBindingNamespace[]; signal?: AbortSignal }`
-- `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }`——运行时将每个命名空间作为程序内部的全局异步函数对象暴露；可选描述符要求运行时注入真正的、程序可见的 reject 类，而无需让 seam 获知消费方专用名称。`CodeJsonValue` 是这个低依赖 seam 的结构化无损 JSON 类型，因此绑定参数与解析值可以完整跨越实现的序列化边界。
+- `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<CodeJsonValue>>; errorClass?: { name: string; memberNameProperty: string } }`——运行时将每个命名空间作为程序内部的全局异步函数对象暴露；可选描述符要求运行时注入真正的、程序可见的 reject 类，而无需让 seam 获知消费方专用名称。`CodeJsonValue` 是这个低依赖 seam 的结构化无损 JSON 类型，因此绑定参数与返回值可以完整跨越实现的序列化边界。
 - `CodeRunResult = { value?: CodeJsonValue; logs: string[]; error?: CodeRunFailure }`——程序执行失败时，执行 promise 仍会 fulfill，并通过 `error` 字段返回失败结果。只有调用方/seam 误用（例如重复的绑定命名空间）时，`run()` 才会 reject；消费方仍在自己的错误边界处理不合规后端的拒绝。
 - `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'; message: string }`——按[防御性模式](../../../../docs/defensive-patterns.md)独立报告的正交结果；超时的 run 不是异常，abort 不是超时，有损完成值不是溢出，基底退出也与上述情况相互独立。
-- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——交付的后端为 `'typescript'`；Python 后端会声明自己，并在呈现侧配对自己的 SDK 生成器）和 `isolation`（交付的后端为 `'worker-thread'`；未来可为 `'process'`、`'container'` 等）。`dsh-tools` 在 MVP 中要求 `language === 'typescript'`——其代码生成输出 TS——否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
+- 两个只读的后端描述符，仅供信息参考而非门禁判定：`language`（程序必须使用的语言——首个后端为 `'typescript'`；Python 后端声明 `'python'`，并在呈现侧配对自己的 SDK 生成器）和 `isolation`（交付的后端为 `'worker-thread'`；未来可为 `'process'`、`'container'` 等）。`dsh-tools` 接受任何注册了 SDK 渲染器与 `run_code` flavor 的 `language`（TypeScript 与 Python 已交付；见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），否则组装会大声失败，与 `toolOrder` 违规时的配置错误惯用法相同（如 `mode` 为非 native 但根本没有加载 `ctx.codeRuntime`）。
 
 请求包含所有运行时输入；实现方拥有经校验的超时和上限默认值。注册表仅在组装 Code Mode 时查找可选的运行时，因此 native 模式不依赖它。缺失或语言不兼容的运行时会大声失败。替代基底或语言可以在同一 seam 背后替换实现，配对相应的 SDK 生成器。
 
 ### worker-thread 运行时
 
-`@deepseek-ai/dsh-code-runtime-worker`，`packages/code-runtime/` 组的第二个包（package）。每次 `run()`：
+`@deepseek-ai/dsh-code-runtime-worker`，`packages/code-runtime/` 组的第二个包。每次 `run()`：
 
-1. **宿主侧 type-strip**，使用 Node 内置的 `stripTypeScriptTypes`（`node:module`；在本仓库的整个引擎范围 `^22.19.0 || >=24.0.0` 内可用，且保持位置不变，因此运行时错误行号与模型源码一致）。仅剥离模式拒绝不可擦除的语法（`enum`、namespaces）——该拒绝以 `error.kind: 'exception'` 加 Node 的消息返回，SDK 说明写明「仅限可擦除 TypeScript」，模型像处理其他程序错误一样自我修正。语法级失败不会 spawn worker。
+1. **宿主侧 type-strip**，使用 Node 内置的 `stripTypeScriptTypes`（`node:module`；在本仓库的整个引擎范围 `^22.19.0 || >=24.0.0` 内可用，且会保留源码位置，因此运行时错误行号与模型源码一致）。仅剥离模式拒绝不可擦除的语法（`enum`、namespaces）——该拒绝以 `error.kind: 'exception'` 加 Node 的消息返回，SDK 说明写明「仅限可擦除 TypeScript」，模型像处理其他程序错误一样自我修正。语法级失败不会 spawn worker。
 2. **每次 run spawn 一个全新 `Worker`**，来自包自身的 bootstrap 模块：`env: {}`（真正为空——比 spawn 命令的 scrubbed-env 规则更严格），`resourceLimits` 来自配置，`stdout`/`stderr` 捕获到 `logs` 而非继承。不做池化，不跨 run 保留状态：程序的世界随 worker 消亡，这使得 run 仅从日志即可重建，状态泄漏不可表达。
 3. **在 bootstrap 中执行**：剥离后的程序成为一个 `AsyncFunction` 的函数体，其参数是绑定全局变量、消费方声明的 reject 类和一个捕获式 `console` shim，因此顶层 `await` 和 `return` 可用。Code Mode 声明 `ToolCallError`，成员属性为 `toolName`；运行时无需硬编码工具即可实体化真正的构造函数。无损 JSON 完成值会精确跨越边界；`undefined` 仍表示缺席，有损值产生 `invalid-output`，过大的外层结果产生 `output-limit`，而不会退化为检查格式化后的字符串替代品。
 4. **通过消息端口桥接绑定**：worker 中的每个绑定函数发送 `{ id, global, name, args }` 并等待回复；宿主根据请求的绑定校验名称、调用、并回复 `{ id, ok, value }` 或 `{ id, ok: false, message }`（宿主侧绑定拒绝变为程序侧 rejection）。worker 侧的命名空间对象通过 `defineProperty` 构建为 null-prototype，因此名为 `__proto__`、`constructor` 或 `toString` 的绑定是普通自有属性，而非原型链碰撞。未知名称、重复 id 和结算后消息被拒绝或忽略——端口协议假设对端是恶意的，因为对端运行的是模型代码。
 5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
-6. **dispose 至完全停稳**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
+6. **dispose（资源释放）至完全停稳**：服务自身的 dispose 终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
 
 ### 信任姿态
 
-worker 运行时提供的是隔离，而非安全边界：模型代码可以访问 Node API，权限与 bash 工具相当。`worker.terminate()` 停止线程但不停止它 spawn 的 OS 进程。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署需要为代码和 bash 都使用容器级后端；运行时的 isolation 描述符让它们能区分该后端。
+worker 运行时只能约束程序的运行，而不构成安全边界：模型代码可以访问 Node API，权限与 bash 工具相当。`worker.terminate()` 停止线程但不停止它 spawn 的 OS 进程。Code Mode 使用与 bash 相同的 `tools/pre-execute` 策略门禁，并额外提供空环境、堆限制、独立 isolate 和对程序本身的硬终止。需要硬多租户边界的部署需要为代码和 bash 都使用容器级后端；运行时的 isolation 描述符让它们能区分该后端。
 
 ### 模型看到的内容
 
-SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。即使在 `Promise.all` 下调用仍保持顺序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
+SDK 指示模型编写一个所加载运行时语言的异步函数体（默认可擦除 TypeScript；Python 运行时下为 Python `async` 函数体——见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。两种 flavor 用各自的原语陈述同一契约：相互独立的只读调用可以在 `Promise.all`（TypeScript）或 `asyncio.gather`（Python）下重叠，有副作用的调用按提交顺序单独运行，有依赖的工作用 `await` 排序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
 
 ## 后果
 
-切换到 `'code'` 的部署必须更新任何仅限 native 的 `toolOrder`。组装监听器有责任维护任何被重写的协议面的完整性。子分发保持序列化，而每次调用的上下文会通过外层结果保留其 source、信封与元数据。
+切换到 `'code'` 的部署必须更新任何仅限 native 的 `toolOrder`。组装监听器有责任维护任何被重写的协议面的完整性。子分发在有界的重叠池下按提交顺序启动，而每次调用的上下文会通过外层结果保留其 source、信封与元数据。
 
 ## 测试
 
@@ -104,9 +104,9 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 **`node:vm` 作为参考运行时，加固推迟。** 否决：`node:vm` 不是隔离（原型链逃逸可达宿主 realm）且无法中断热循环。worker 线程提供独立 isolate、空环境、`resourceLimits` 和可靠的 `terminate()`，信任等级等同于 bash，因此参考实现和生产实现是同一个包，无需 unsafe-acknowledgement 仪式。
 
-**在原生工具调用上做结果省略/摘要。** 仅解决问题的上下文膨胀一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
+**在原生工具调用上做结果省略/摘要。** 仅解决问题中上下文膨胀这一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
 
-**循环中的并行原生分发。** 往返成本的另一个答案；仍是有效的未来工作（open TODO），仍被并发安全元数据阻塞，且仍无组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的序列化队列决策保持两者兼容：当元数据就绪时，原生并行分发和每工具绑定并行化一起解锁。
+**循环中的并行原生分发。** 决策当时对往返成本的另一个答案；它被并发安全元数据阻塞，且无论如何都不提供组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的队列决策保持了两者兼容，后续也正是这样落地的：元数据以 `isConcurrencySafe` 的形式就绪（见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)），原生 rolling-pool 分发与每工具绑定并行化基于同一个分类器一起解锁。
 
 **始终排他（忠于 Cloudflare，无模式）。** 否决，因为本 SDK 的主要消费方是编码 agent：其日常的单次调用（`bash`、`read`、`edit`）作为原生调用已经是最优的，强制每次编辑都通过程序会给常见场景增加负担。mode 配置让忠实形式（`'code'`）只需一行配置即可启用，而不强加于人。
 
@@ -114,20 +114,20 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
 
 **SDK 中的清洁化标识符别名**（`my-tool` → `my_tool`，Cloudflare 的做法）。否决：`declare const` 上的带引号键使每个名称可达，零别名碰撞逻辑；模型能正常处理 `tools["my-tool"](…)`。
 
-**REPL 风格的持久内核**（状态跨 `run_code` 调用存活）。在 MVP 中否决：跨调用状态对会话日志不可见，破坏了「每个请求是日志的纯函数」这一可重建性保证；每次 run 全新保持了这一点。内核风格的后端在未来仍可通过同一 seam 表达，配合自己的日志方案。
+**REPL 风格的持久内核**（状态跨 `run_code` 调用存活）。在 MVP 中否决：跨调用状态对会话日志不可见，破坏了「每个请求是日志的纯函数」这一可重建性保证；每次 run 均使用全新实例则维持了这一保证。内核风格的后端在未来仍可通过同一 seam 表达，配合自己的日志方案。
 
 ## 风险
 
-**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，隔离程度超过它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
+**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，约束能力强于它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
 
 **`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的契约线，错误路径是一个可工作的反馈循环，而非死胡同。
 
 **SDK 的提示词成本，尤其在 `'both'` 下。** `.d.ts` 可能与它补充的原生 schema 体量相当；`'both'` 携带两种表示。前缀稳定性 + 提供方缓存摊销了每会话成本；mode 是每部署的；本 Agent Note 不做无条件节省的声明。何时优先使用哪种模式的量化指导明确属于上线后学习。
 
-**注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。通过包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 约束：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
+**注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 共同约束了这一增长：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
 
-**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 解析值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
+**大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 返回值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
 
-**仅序列化的子分发。** `Promise.all` 尚未获得挂钟并行性，仅减少往返次数；模型可能过度期望。说明中已声明；解除此限制与原生并行分发 TODO 所需的并发安全元数据绑定。
+**子分发的重叠由工具自身的安全声明限定，而非由调用方决定。** 程序里的 `Promise.all` 或 `asyncio.gather` 只在工具自己分类为并发安全的调用之间换来挂钟并行性；一串 exclusive 调用仍要按顺序付出各自的往返开销，模型可能过度期望。两种 flavor 的 SDK 说明都陈述了真实契约。本 note 交付的是使该风险绝对化的序列化占位实现；调度器及其重叠上限由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
 
-**预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）对恶意程序是承重的。两侧都有单元测试（带 pending 诱饵分发的热循环在 `computeMs` 处死亡；在慢绑定上空闲的程序存活到 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。`maxWallMs` 是配置项，且会传入 `setTimeout`，后者会把超过 `MAX_TIMER_DELAY_MS`（2^31-1 ms）的延迟夹到 1 ms；因此仅有正数校验会放行一个 25 天的上限，它在第一个 tick 就到期，使每次运行都超时。worker 运行时正因如此在加载时对该字段做范围校验。`computeMs` 不需要上界，因为它对照的是实测占用率，而不是交给定时器。
+**预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）是抵御恶意程序的关键。两种情况均有单元测试（带 pending 诱饵分发的热循环会在耗尽 `computeMs` 预算时终止；等待慢速绑定的空闲程序则会持续运行至 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。`maxWallMs` 是配置项，且会传入 `setTimeout`，后者会把超过 `MAX_TIMER_DELAY_MS`（2^31-1 ms）的延迟夹到 1 ms；因此仅有正数校验会放行一个 25 天的上限，它在第一个 tick 就到期，使每次运行都超时。worker 运行时正因如此在加载时对该字段做范围校验。`computeMs` 不需要上界，因为它对照的是实测占用率，而不是交给定时器。
diff --git a/docs/architecture.md b/docs/architecture.md
index ea78faa627..e88bdac118 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -26,12 +26,12 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | adapter registry, streaming model calls |
 | `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | replay-aware request and surface pressure |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | foreground/background command execution |
-| `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | managed child-process trees for bash, LSP, and ACP subagent backends |
+| `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | executable lookup, managed trees, terminals |
 | `ctx.pty` | [`pty/`](../packages/pty/README.md) | owner-scoped persistent terminal sessions |
 | `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | same-world process confinement through argv wrapping and per-call policy |
 | `ctx.sandboxPolicy` | [`sandbox/`](../packages/sandbox/README.md) | shared sandbox policy home |
 | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | model-written program execution |
-| `ctx.fs` | [`fs/`](../packages/fs/README.md) | filesystem provider primitives and policy events |
+| `ctx.fs` | [`fs/`](../packages/fs/README.md) | execution-world paths, bounded IO, and policy events |
 | `ctx.lsp` | [`lsp/`](../packages/lsp/README.md) | semantic navigation registry |
 | `ctx.skills` | [`skill/`](../packages/skill/README.md) | skill provider registry, progressive disclosure |
 | `ctx.web` | [`web/`](../packages/web/README.md) | search/fetch provider registries |
@@ -155,7 +155,7 @@ Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is on
 
 ### Capability Pattern
 
-A swappable capability usually has **interface / implementation / consumer** layers: service/events, backend, and model-facing tools/prompts. Bash is the reference; the [capability graph](capability-seams.md) maps each family.
+Capabilities separate **interface / implementation / consumer** layers. Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks. See the [capability graph](capability-seams.md).
 
 Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](core-data-structures/subagent.md)).
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 5a46dfaf84..9314a3fbfc 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -26,12 +26,12 @@
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | 适配器注册表和模型流式调用 |
 | `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的单实例请求压力与表面压力 |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | 前台和后台命令执行 |
-| `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | 供 bash、LSP 与 ACP subagent 后端使用的受管子进程树 |
+| `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | 可执行文件查找、受管进程树、终端 |
 | `ctx.pty` | [`pty/`](../packages/pty/README.md) | 按 owner 隔离的持久化终端会话 |
 | `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | 通过 argv 包装和逐调用策略限制同一执行环境内的进程 |
 | `ctx.sandboxPolicy` | [`sandbox/`](../packages/sandbox/README.md) | 共享沙箱策略归属点 |
 | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | 执行模型编写的程序 |
-| `ctx.fs` | [`fs/`](../packages/fs/README.md) | 文件系统提供方原语和策略事件 |
+| `ctx.fs` | [`fs/`](../packages/fs/README.md) | 执行世界路径、有界 I/O 和策略事件 |
 | `ctx.lsp` | [`lsp/`](../packages/lsp/README.md) | 语义导航注册表 |
 | `ctx.skills` | [`skill/`](../packages/skill/README.md) | skill（技能）提供方注册表和渐进式披露 |
 | `ctx.web` | [`web/`](../packages/web/README.md) | 搜索与抓取提供方注册表 |
@@ -155,7 +155,7 @@ idle inject:
 
 ### 功能模式
 
-可替换功能通常具有**接口／实现／消费方**三层：服务和事件、后端、面向模型的工具和提示词。Bash 是参考实现；[功能图](capability-seams.md)映射了每个包族。
+能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[功能图](capability-seams.md)。
 
 例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](core-data-structures/subagent.md)）。
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index c5ec654d0f..ae90e4a9bf 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -40,6 +40,13 @@ flowchart LR
   pkg_tool_bash["tool-bash"]
   pkg_hooks_claude["hooks-claude"]
   pkg_hooks_codex["hooks-codex"]
+  pkg_settings["settings"]
+  svc_settings["ctx.settings<br/>User-settings seam"]
+  pkg_settings_local["settings-local"]
+  pkg_apiproxy["apiproxy"]
+  pkg_credentials["credentials"]
+  svc_credentials["ctx.credentials<br/>Credential seam"]
+  pkg_credentials_local["credentials-local"]
   pkg_session_telemetry["session-telemetry"]
   svc_telemetry["ctx.telemetry<br/>Session telemetry seam"]
   pkg_session_telemetry_otel["session-telemetry-otel"]
@@ -51,12 +58,10 @@ flowchart LR
   svc_storageDomain["ctx.storageDomain<br/>Domain data facility"]
   pkg_workspace["workspace"]
   svc_workspace["ctx.workspace<br/>Workspace entity registry"]
-  pkg_apiproxy["apiproxy"]
   svc_sessionQuery["ctx.sessionQuery<br/>Session reads, traces, filters, and search"]
   pkg_session_reference["session-reference"]
   pkg_tool_session_query["tool-session-query"]
   svc_sessionReferences["ctx.sessionReferences<br/>Cross-session snapshot preparation"]
-  pkg_tui["tui"]
   pkg_session_title["session-title"]
   svc_sessionTitle["ctx.sessionTitle<br/>Log-backed session titles"]
   pkg_session_title_first_message_llm["session-title-first-message-llm"]
@@ -84,13 +89,11 @@ flowchart LR
   pkg_host_apiproxy["host-apiproxy"]
   pkg_session_projection_cache["session-projection-cache"]
   svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"]
-  svc_tui["ctx.tui<br/>Mounted-terminal interaction service"]
   pkg_skill["skill"]
   svc_skills["ctx.skills<br/>Skill provider registry"]
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
-  pkg_tui_demo["tui-demo"]
   svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_goal["goal"]
@@ -103,8 +106,13 @@ flowchart LR
   pkg_pty_local["pty-local"]
   pkg_lsp_local["lsp-local"]
   pkg_subagent_acp["subagent-acp"]
+  pkg_subagent_codex["subagent-codex"]
+  pkg_subagent_claude_code["subagent-claude-code"]
   pkg_bash["bash"]
   svc_bash["ctx.bash<br/>Bash executor seam"]
+  pkg_pwsh_local["pwsh-local"]
+  pkg_tool_pwsh["tool-pwsh"]
+  pkg_bash_env["bash-env"]
   svc_bashEnv["ctx.bashEnv<br/>Managed bash environment registry"]
   pkg_pty["pty"]
   svc_pty["ctx.pty<br/>Persistent PTY session registry"]
@@ -128,9 +136,11 @@ flowchart LR
   pkg_compact["compact"]
   svc_compact["ctx.compact<br/>Compaction seam"]
   pkg_subagent["subagent"]
-  svc_subagents["ctx.subagents<br/>Subagent provider registry"]
+  svc_subagents["ctx.subagents<br/>Subagent provider and continuation service"]
   pkg_subagent_spawn["subagent-spawn"]
   pkg_subagent_fork["subagent-fork"]
+  pkg_subagent_dsh_sdk["subagent-dsh-sdk"]
+  pkg_tool_subagent_control["tool-subagent-control"]
   pkg_tool_ralph["tool-ralph"]
   pkg_tasks["tasks"]
   svc_tasks["ctx.tasks<br/>Background task registry"]
@@ -166,6 +176,7 @@ flowchart LR
   pkg_api_gateway --> svc_typertGateway
   pkg_approval --> svc_approval
   pkg_bash --> svc_bash
+  pkg_bash_env --> svc_bashEnv
   pkg_bash_local --> svc_bash
   pkg_bash_sandbox --> svc_bash
   pkg_code_runtime --> svc_codeRuntime
@@ -174,6 +185,8 @@ flowchart LR
   pkg_compact --> svc_compact
   pkg_compact_basic --> svc_compact
   pkg_compact_tool_result_prune --> svc_toolResultPrune
+  pkg_credentials --> svc_credentials
+  pkg_credentials_local --> svc_credentials
   pkg_directory_picker --> svc_directoryPicker
   pkg_directory_picker_browse --> svc_directoryPicker
   pkg_directory_picker_native --> svc_directoryPicker
@@ -191,6 +204,7 @@ flowchart LR
   pkg_plan_mode --> svc_planMode
   pkg_pty --> svc_pty
   pkg_pty_local --> svc_pty
+  pkg_pwsh_local --> svc_bash
   pkg_sandbox --> svc_sandbox
   pkg_sandbox_local --> svc_sandbox
   pkg_sandbox_policy --> svc_sandboxPolicy
@@ -208,6 +222,8 @@ flowchart LR
   pkg_session_title --> svc_sessionTitle
   pkg_session_title_all_messages_llm --> svc_sessionTitle
   pkg_session_title_first_message_llm --> svc_sessionTitle
+  pkg_settings --> svc_settings
+  pkg_settings_local --> svc_settings
   pkg_skill --> svc_skills
   pkg_skill_local --> svc_skills
   pkg_spill --> svc_spillStore
@@ -218,6 +234,9 @@ flowchart LR
   pkg_storage_sqlite --> svc_storage
   pkg_subagent --> svc_subagents
   pkg_subagent_acp --> svc_subagents
+  pkg_subagent_claude_code --> svc_subagents
+  pkg_subagent_codex --> svc_subagents
+  pkg_subagent_dsh_sdk --> svc_subagents
   pkg_subagent_fork --> svc_subagents
   pkg_subagent_spawn --> svc_subagents
   pkg_subprocess --> svc_subprocess
@@ -226,10 +245,7 @@ flowchart LR
   pkg_tasks --> svc_tasks
   pkg_tasks_local --> svc_tasks
   pkg_token_meter --> svc_tokenMeter
-  pkg_tool_bash --> svc_bashEnv
   pkg_tools --> svc_tools
-  pkg_tui --> svc_tui
-  pkg_tui --> svc_userInteraction
   pkg_typert_registry --> svc_typert
   pkg_user_interaction --> svc_userInteraction
   pkg_web --> svc_web
@@ -246,16 +262,20 @@ flowchart LR
   svc_agents --> pkg_agent_loop
   svc_agents --> pkg_cli_demo
   svc_agents --> pkg_subagent_inprocess
-  svc_agents --> pkg_tui_demo
   svc_approval --> pkg_tool_bash
   svc_approval --> pkg_tools
   svc_bash --> pkg_hooks_claude
   svc_bash --> pkg_hooks_codex
   svc_bash --> pkg_tool_bash
+  svc_bash --> pkg_tool_pwsh
+  svc_bashEnv --> pkg_tool_bash
+  svc_bashEnv --> pkg_tool_pwsh
   svc_clientModuleHost --> pkg_hmr
   svc_codeRuntime --> pkg_tools
-  svc_commands --> pkg_tui
   svc_compact --> pkg_compact_basic
+  svc_credentials --> pkg_apiproxy
+  svc_credentials --> pkg_llm_deepseek
+  svc_credentials --> pkg_llm_pi_ai
   svc_directoryPicker --> pkg_apiproxy
   svc_fs --> pkg_tool_fs
   svc_httpServer --> pkg_connection
@@ -285,7 +305,6 @@ flowchart LR
   svc_sessionProjections --> pkg_tool_todo
   svc_sessionQuery --> pkg_session_reference
   svc_sessionQuery --> pkg_tool_session_query
-  svc_sessionReferences --> pkg_tui
   svc_sessions --> pkg_agent
   svc_sessions --> pkg_agent_loop
   svc_sessions --> pkg_cli_demo
@@ -294,17 +313,23 @@ flowchart LR
   svc_sessions --> pkg_session_query
   svc_sessions --> pkg_session_query_sqlite
   svc_sessions --> pkg_subagent_inprocess
+  svc_settings --> pkg_apiproxy
+  svc_settings --> pkg_llm_deepseek
+  svc_settings --> pkg_llm_pi_ai
   svc_skills --> pkg_tool_skill
   svc_spillStore --> pkg_spill_policy
   svc_storage --> pkg_storage_domain
   svc_storageDomain --> pkg_workspace
   svc_subagents --> pkg_tool_ralph
   svc_subagents --> pkg_tool_subagent
+  svc_subagents --> pkg_tool_subagent_control
   svc_subprocess --> pkg_bash_local
   svc_subprocess --> pkg_bash_sandbox
   svc_subprocess --> pkg_lsp_local
   svc_subprocess --> pkg_pty_local
   svc_subprocess --> pkg_subagent_acp
+  svc_subprocess --> pkg_subagent_claude_code
+  svc_subprocess --> pkg_subagent_codex
   svc_systemPrompt --> pkg_agent_loop
   svc_systemPrompt --> pkg_tool_fs
   svc_systemPrompt --> pkg_tool_pty
@@ -329,7 +354,6 @@ flowchart LR
   svc_typert --> pkg_api_gateway
   svc_typert --> pkg_typert_loader
   svc_userInteraction --> pkg_tool_ask_user
-  svc_userInteraction --> pkg_tui
   svc_web --> pkg_tool_web
   svc_workflows --> pkg_tool_ralph
   svc_workflows --> pkg_tool_workflow
@@ -347,28 +371,29 @@ flowchart LR
 | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
 | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
+| `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer. |
+| `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage. |
 | `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/telemetry/session-telemetry) | [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
 | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. |
 | `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. |
 | `ctx.workspace` | `core` | [`workspace`](../packages/workspace/workspace) | - | `apiproxy` | - | Owns WorkspaceId-branded records over the domain facility; stable sessionIds accounts drive Host RPC and GUI projections. |
 | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference), [`tool-session-query`](../packages/session-query/tool-session-query) | - | The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations, while the model consumer owns workspace authority and cursor-free rendering. |
-| `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | [`tui`](../packages/ui/tui) | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
+| `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
 | `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session-title/session-title) | [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session-title/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
 | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
-| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`tui`](../packages/ui/tui) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`tui`](../packages/ui/tui) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
+| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | - | [`tool-ask-user`](../packages/ui/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
-| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | [`tui`](../packages/ui/tui) | - | Plugins register direct human commands; TUI consumes the effective per-agent catalog without sending invocations to the model. |
+| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
-| `ctx.tui` | `bundle` | [`tui`](../packages/ui/tui) | - | - | - | One TUI front door provides a FIFO overlay host; injected plugins receive caller-fiber ownership without access to pi-tui or terminal lifecycle state. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
-| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tui-demo`](../packages/examples/tui-demo) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
-| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp) | - | The bash executors, PTY shell backend, LSP host, and ACP subagent backend spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
-| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them. |
-| `ctx.bashEnv` | `core` | [`tool-bash`](../packages/bash/tool-bash) | - | - | - | Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace. |
+| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
+| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pwsh-local`](../packages/bash/pwsh-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them. |
+| `ctx.bashEnv` | `core` | [`bash-env`](../packages/bash/bash-env) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh) | - | Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace. |
 | `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface. |
 | `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local) | - | Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement. |
 | `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/bash/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`pty-local`](../packages/pty/pty-local) | - | The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots. |
@@ -377,7 +402,7 @@ flowchart LR
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
-| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route. |
+| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
 | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. |
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index a9077ae139..7e125cd02c 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -594,6 +594,34 @@ Abstract filesystem provider. Targets must preserve identity across aliases; rea
  */
 abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
 
+/**
+ * Return the canonical absolute path a subprocess in this filesystem's
+ * execution world can open. The path is deliberately separate from
+ * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+ * capability, but must continue treating the target key as opaque.
+ * @param target - the resolved target whose process path is required.
+ * @returns an absolute path in the backend's execution world.
+ */
+abstract processPath(target: FsTarget): string
+
+/**
+ * Return the canonical `file:` URI for a target in this filesystem's
+ * execution world. Backends own URI encoding because the host platform may
+ * differ from the execution platform.
+ * @param target - the resolved target to encode.
+ * @returns the target's canonical file URI.
+ */
+abstract fileUrl(target: FsTarget): string
+
+/**
+ * Test canonical containment without exposing or parsing backend target
+ * keys. Both targets must come from this provider.
+ * @param parent - canonical directory target.
+ * @param child - canonical candidate target.
+ * @returns true when `child` is `parent` or a descendant of it.
+ */
+abstract contains(parent: FsTarget, child: FsTarget): boolean
+
 /**
  * Return target metadata, or `undefined` when the target does not exist.
  * @param target - the resolved target to stat.
@@ -678,7 +706,7 @@ abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version:
 
 Types: [FsDirEntry](../core-data-structures/filesystem.md) · [FsEditOutcome](../core-data-structures/filesystem.md) · [FsEditRequest](../core-data-structures/filesystem.md) · [FsInfo](../core-data-structures/filesystem.md) · [FsPathInfo](../core-data-structures/filesystem.md) · [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md) · [FsWriteOutcome](../core-data-structures/filesystem.md) · [SandboxExecutionPolicy](../core-data-structures/sandbox.md)
 
-Source: [`packages/fs/fs/src/index.ts:81`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
 
 ## `ctx.goals` — `GoalService`
 
@@ -2215,12 +2243,27 @@ Abstract subprocess service. Subclass, implement spawn, and load the subclass as
 
 Implementations must honor these semantics:
 
+- Executable paths belong to one execution world shared with the mounted filesystem provider.
 - spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures.
 - Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.
 - SubprocessHandle.terminate (and the spec's abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
+- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.
 
 ```ts cordis-catalog
+/**
+ * Resolve one configured executable in this provider's execution world.
+ * Absolute paths are verified; bare names use the provider's scrubbed PATH
+ * plus explicit environment overrides. Relative paths containing separators
+ * are rejected: no current consumer defines which directory they would
+ * resolve against, so providers fail loud instead of guessing.
+ * @param command - absolute executable path or bare PATH name.
+ * @param env - explicit environment entries used for lookup.
+ * @param signal - aborts remote or local lookup.
+ * @returns a canonical executable path.
+ */
+abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
+
 /**
  * Start one managed child process from a fully-specified spec; this seam
  * applies no defaults.
@@ -2228,11 +2271,20 @@ Implementations must honor these semantics:
  * @returns the live process handle (streams/readers, signalling, outcome promise).
  */
 abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
+
+/**
+ * Allocate a real terminal and start one owned process session. This is the
+ * only non-pipe process primitive: implementations own terminal byte I/O,
+ * foreground groups, signals, and complete session-tree cleanup.
+ * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
+ * @returns the live terminal handle after allocation succeeds.
+ */
+abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
 ```
 
-Types: [SubprocessHandle](../core-data-structures/subprocess.md) · [SubprocessSpawnSpec](../core-data-structures/subprocess.md)
+Types: [SubprocessHandle](../core-data-structures/subprocess.md) · [SubprocessSpawnSpec](../core-data-structures/subprocess.md) · [SubprocessTerminalHandle](../core-data-structures/subprocess.md) · [SubprocessTerminalSpawnSpec](../core-data-structures/subprocess.md)
 
-Source: [`packages/subprocess/subprocess/src/index.ts:91`](../../packages/subprocess/subprocess/src/index.ts)
+Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts)
 
 ## `ctx.systemPrompt` — `SystemPrompt`
 
diff --git a/docs/core-data-structures/filesystem.i18n.yaml b/docs/core-data-structures/filesystem.i18n.yaml
index 78386c54fd..2f9478a7ba 100644
--- a/docs/core-data-structures/filesystem.i18n.yaml
+++ b/docs/core-data-structures/filesystem.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/core-data-structures/filesystem.md
 filesystem.md: addded9f673ed435e95109d4fb772967514c0b87
-filesystem.zh.md: 3ef16ede1e137d2a1310861941ac3244ca105650
+filesystem.zh.md: 1e378928ed570b97dbec73b836a7e6ff18726ff8
diff --git a/docs/core-data-structures/lsp.i18n.yaml b/docs/core-data-structures/lsp.i18n.yaml
index 329d5086e0..25b54df775 100644
--- a/docs/core-data-structures/lsp.i18n.yaml
+++ b/docs/core-data-structures/lsp.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/core-data-structures/lsp.md
 lsp.md: 03d0ce2dbe246aadb6f6c9a702fa50e3e792eb09
-lsp.zh.md: ef9623f01124bc459d3bbceba340c3870e678baa
+lsp.zh.md: d428f2b5f9568b231b0b50a13bd4a41f7ea81346
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index 50e219a2c6..b2d38854b2 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: 895bfe3d763853a86648e8aaab8b091a26006255
-subprocess.zh.md: 044e924674ecf5dd8f8a1c71fe39653e7525dfb0
+subprocess.md: 023b122218ad1caa2b8e16c26b0bc8b0d4183c28
+subprocess.zh.md: 5ee9c782c0ce73ca9a2e694450ed38b8d548dc09
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 044e924674..5ee9c782c0 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -1,4 +1,4 @@
-# 进程管理器
+# 子进程
 
 [English](subprocess.md) | 中文
 
@@ -12,7 +12,7 @@
 
 ## 受管环境命名空间与捕获的输出
 
-`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的条目形式到达，每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
+`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的字符串条目形式到达，而显式的 `undefined` tombstone 会删除普通环境中已有的值。每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
 
 ```ts type-equiv
 /** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
@@ -36,7 +36,7 @@ interface CollectedOutput {
 }
 ```
 
-## Node 形状的 stdio 处置方式（disposition）
+## Node 风格的 stdio 处置方式（disposition）
 
 每条流的处置方式都显式给出，由各消费方自行选择：原始管道用于协议分帧（LSP JSON-RPC、ACP ndjson），inherit 用于直通的诊断输出，收集模式用于有界的批量输出；其中 spill 文件是可选的，因此诊断尾部（语言服务器的 stderr）可以只在内存中缓冲，不留下任何文件。
 
@@ -88,7 +88,7 @@ interface SubprocessStdio {
 
 ## 完全显式的 spawn spec
 
-该 seam 不应用任何默认值：每项处置方式、限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的进程管理器默认值决定。`argv` 绝不经过 shell 解释。
+该 seam 不应用任何默认值：每项处置方式、限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的子进程服务默认值决定。`argv` 绝不经过 shell 解释。
 
 ```ts type-equiv
 /**
@@ -105,10 +105,11 @@ interface SubprocessSpawnSpec {
   /** Per-stream stdio dispositions. */
   stdio: SubprocessStdio
   /**
-   * Grace period in milliseconds for the {@link SubprocessHandle.terminate}
-   * escalation and for draining still-open collected pipes after the process
-   * exits (an inherited descriptor held by a surviving descendant cannot hold
-   * the outcome open indefinitely).
+   * Positive finite grace period in milliseconds, no greater than
+   * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation
+   * and for draining still-open collected pipes after the process exits (an
+   * inherited descriptor held by a surviving descendant cannot hold the
+   * outcome open indefinitely).
    */
   graceMs: number
   /**
@@ -119,19 +120,18 @@ interface SubprocessSpawnSpec {
   signal?: AbortSignal | undefined
   /**
    * Explicit environment entries merged onto the implementation's scrubbed
-   * parent base (see `scrubbedParentEnv`), with no namespace validation:
-   * every entry is a deliberate caller opt-in, so a forwarded
-   * credential-shaped entry or a current `DSH_*` fact survives precisely
-   * because this layer merges after the scrub that drops its ambient
-   * namesake.
+   * parent base (see `scrubbedParentEnv`), with no namespace validation. A
+   * string is a deliberate caller opt-in, so a forwarded credential-shaped
+   * entry or current `DSH_*` fact survives the scrub; `undefined` is a
+   * tombstone that removes an ordinary ambient entry from the child.
    */
-  env?: Record<string, string> | undefined
+  env?: NodeJS.ProcessEnv | undefined
 }
 ```
 
 ## 句柄：流、读取器与以进程树为范围的终止
 
-spawn 会立即返回一个实时句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树——这足以让消费方构建自己的拆卸阶梯（ACP 后端以 stdin EOF 打头的 `disposeAcpChild` 即是模板）。
+spawn 会立即返回一个活动句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树。这足以让消费方构建自己的拆卸阶梯；ACP 后端的 `disposeAcpChild` 以 stdin EOF 开始，即为仓库内模板。
 
 ```ts type-equiv
 /**
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 458da3b713..d10f476f79 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 3f467641bbc9eae14a94aa2d3bff0402116a9d3f
-README.zh.md: c9d11bbf6239b4239a4e037dac63b05d3a9a58f7
+README.md: 8fbb6069a784a5bd45423a4e1ae11834a597750d
+README.zh.md: 42a8d691344c716021188df6fd870a841d543f36
diff --git a/packages/bash/pwsh-local/tests/executor.spec.ts b/packages/bash/pwsh-local/tests/executor.spec.ts
index c7da16c44c..350ea4de89 100644
--- a/packages/bash/pwsh-local/tests/executor.spec.ts
+++ b/packages/bash/pwsh-local/tests/executor.spec.ts
@@ -119,6 +119,8 @@ describe('spawn construction (pure, every platform)', () => {
   /** A subprocess service that records spawn specs and settles instantly. */
   class CapturingSubprocessService extends SubprocessService {
     specs: SubprocessSpawnSpec[] = []
+    override async resolveExecutable(command: string): Promise<string> { return command }
+    override spawnTerminal(): Promise<never> { throw new Error('pwsh spawns pipes, never terminals') }
     private readonly reader: SubprocessOutputReader = {
       readFrom: () => ({ text: '', lossy: false, nextOffset: 0 }),
     }
diff --git a/packages/bash/pwsh-local/tsconfig.json b/packages/bash/pwsh-local/tsconfig.json
index 7381575674..53ccc94926 100644
--- a/packages/bash/pwsh-local/tsconfig.json
+++ b/packages/bash/pwsh-local/tsconfig.json
@@ -18,19 +18,19 @@
       "path": "../../../vendor/schemastery"
     },
     {
-      "path": "../code-runtime"
+      "path": "../../util/brand"
     },
     {
-      "path": "../code-runtime-worker"
+      "path": "../../util/timeout"
+    },
+    {
+      "path": "../../bash/bash"
     },
     {
       "path": "../../subprocess/subprocess"
     },
     {
       "path": "../../support/invariants"
-    },
-    {
-      "path": "../../util/timeout"
     }
   ]
 }
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index 3de3bc622e..590b79dcd1 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -34,7 +34,7 @@ Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at
 
 Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local and session-owned JSON boundaries both flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. The repository-wide requirement to exercise this published entry path belongs to the [testing policy](../../../docs/testing.md).
 
-The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The `./runtime-host` subpath shares type stripping, binding validation/dispatch, lossless JSON transport, and output accounting with sibling worker-based implementations; it is implementation support, not a plugin. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers remain source-private.
+The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
 
 ## Model Experience
 
diff --git a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
index db2c167354..54f58eb414 100644
--- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
@@ -597,27 +597,6 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
     expect(result.value).toEqual({ name: 'ToolCallError', toolName: 'bad', message: 'binding resolution must be lossless JSON' })
   })
 
-  it('contains binding rejections whose thrown values cannot be rendered', async () => {
-    const { runtime } = await setup()
-    const result = await runtime.run({
-      program: 'try { await tools.bad({}) } catch (error) { return { name: error.name, toolName: error.toolName, message: error.message } }',
-      bindings: tools({
-        bad: async () => {
-          const hostile = new Error('hidden')
-          Object.defineProperty(hostile, 'message', {
-            get() { throw new Error('message getter failed') },
-          })
-          throw hostile
-        },
-      }),
-    })
-    expect(result.value).toEqual({
-      name: 'ToolCallError',
-      toolName: 'bad',
-      message: 'binding rejected with an unrenderable value',
-    })
-  })
-
   it('rejects lossy binding arguments in the worker before invoking the host binding', async () => {
     const { runtime } = await setup()
     let calls = 0
diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts
index e9ae5588ee..c02e4f93db 100644
--- a/packages/fs/tool-fs-search/tests/tools.spec.ts
+++ b/packages/fs/tool-fs-search/tests/tools.spec.ts
@@ -148,6 +148,8 @@ class FakeHandle implements SubprocessHandle {
  */
 class FakeSubprocess extends SubprocessService {
   spawns: SubprocessSpawnSpec[] = []
+  override async resolveExecutable(command: string): Promise<string> { return command }
+  override spawnTerminal(): Promise<never> { throw new Error('search tools spawn pipes, never terminals') }
   handles: FakeHandle[] = []
   /** Arms the per-spawn script; a `{ reject }` return scripts a spawn-level failure. */
   handler: (spec: SubprocessSpawnSpec) => ScriptedRun | { reject: Error } = () => runResult('')
diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md
index 93d123fac7..661c27d332 100644
--- a/packages/lsp/lsp-local/README.md
+++ b/packages/lsp/lsp-local/README.md
@@ -24,7 +24,7 @@ The `servers` record key is the stable provider id reserved on `ctx.lsp`; each v
 |---|---|---|
 | `command` | (required) | Executable to spawn — absolute, or resolved on the child PATH at load. Launch uses no shell. |
 | `args` | `[]` | Arguments passed to the executable. |
-| `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`SECRET`/`TOKEN` are not forwarded); an explicit `DSH_*` entry merges after the seam's scrub of ambient ones. |
+| `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`PASSWORD`/`SECRET`/`TOKEN` are not forwarded); an explicit `DSH_*` entry merges after the seam's scrub of ambient ones. |
 | `extensionToLanguage` | (required) | Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). |
 | `initializationOptions` | `null` | Static `initialize` options forwarded to the server. |
 | `configuration` | `null` | Static answer to every `workspace/configuration` item. |
diff --git a/packages/pty/pty-local/README.md b/packages/pty/pty-local/README.md
index 3b1112b025..5acc92853e 100644
--- a/packages/pty/pty-local/README.md
+++ b/packages/pty/pty-local/README.md
@@ -6,7 +6,7 @@ Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It s
 
 ## Plugin (`pty-local`)
 
-The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly without requiring a sandbox provider; confined modes require a same-world `ctx.sandbox` and wrap the exact shell argv through it, failing before spawn when none is mounted. The effective session mode is resolved at spawn. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
+The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly without requiring a sandbox provider; confined modes require a same-world `ctx.sandbox` and wrap the exact shell argv through it, failing before spawn when none is mounted. At spawn, one `ctx.sandboxPolicy.resolve({ session })` call supplies both the effective mode and the session workspace root; the same root is the default shell cwd when the caller omits one. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
 Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
@@ -14,19 +14,19 @@ Send cancellation marks queued input as canceled before asking the terminal hand
 
 ## Model Experience
 
-### Indirect consumer
+### Current file policy and indirect consumer
 
 #### What the model sees
 
-Nothing directly. Through `@deepseek-ai/dsh-tool-pty`, the model may receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
+The policy owner contributes capability-neutral `sandbox:policy` context. Through `@deepseek-ai/dsh-tool-pty` or another PTY consumer, the model may also receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
 
 #### Token effect
 
-None until a consumer returns bounded backend output. Retained PTY scrollback is not placed in model history by this package.
+The current-policy clause is present while this backend is mounted. Retained PTY scrollback is not placed in model history until a consumer returns bounded output.
 
 #### KV Cache effect
 
-No direct invalidation; the consumer owns prompts, schemas, and appended results.
+A standing-policy change appends an owner-rendered superseding runtime-context snapshot after retained history; consumer results remain append-only.
 
 ## Known Limitations and Deferred Work
 
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index a23a2f3338..353c2a4bda 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 插件（`pty-local`）
 
-该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。系统在 spawn 时解析会话的实际模式。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
+该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。Spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
@@ -14,19 +14,19 @@
 
 ## 模型体验
 
-### 间接消费方
+### 当前文件策略与间接消费方
 
 #### 模型看到的内容
 
-没有直接可见内容。模型通过 `@deepseek-ai/dsh-tool-pty` 可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因和清理错误。
+策略归属方会贡献与具体能力无关的 `sandbox:policy` 上下文。模型通过 `@deepseek-ai/dsh-tool-pty` 或其他 PTY 消费方还可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因和清理错误。
 
 #### Token 影响
 
-消费方返回有界的后端输出前没有影响。此包（package）不会把保留的 PTY scrollback 放入模型历史。
+装载该后端期间，当前策略子句会一直存在。消费方返回有界输出前，保留的 PTY scrollback 不会进入模型历史。
 
 #### KV Cache 影响
 
-不会直接使 KV Cache 失效；提示词、schema 与追加结果由消费方负责。
+常驻策略发生变化时，会在保留的历史之后追加一份由归属方渲染、取代先前状态的运行时上下文快照；消费方结果保持仅追加。
 
 ## 已知限制与暂缓事项
 
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index e6c4fde452..9f10a2cde8 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -3,7 +3,7 @@ import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { Inbox, type Agent } from '@deepseek-ai/dsh-agent'
 import SandboxProvider from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import SandboxPolicyService, { setSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
@@ -22,7 +22,7 @@ import type {
 
 class EmptySandbox extends SandboxProvider {
   confine(_argv: readonly string[], _policy: SandboxPolicy): ConfinedArgv {
-    return { argv: [], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
+    return { argv: [], enforcement: 'full', denialSignatures: [], runnerFailureRules: [] }
   }
 }
 
@@ -31,7 +31,7 @@ class RecordingSandbox extends SandboxProvider {
 
   confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv {
     this.calls.push({ argv, policy })
-    return { argv: ['/sandbox', '--', ...argv], enforcement: 'full', denialSignatures: [], runnerFailureSignatures: [] }
+    return { argv: ['/sandbox', '--', ...argv], enforcement: 'full', denialSignatures: [], runnerFailureRules: [] }
   }
 }
 
@@ -46,9 +46,15 @@ function config(): ResolvedConfig {
 
 function agent(ctx: Context): Agent {
   const id = SessionId('agent')
+  const session = Session.create(id, undefined, { version: 0, id, createdAt: 0 })
   return {
-    id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx,
-    followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+    id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+    status: 'idle',
+    ctx,
+    send: () => {},
+    followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
+    runMaintenance: task => task(new AbortController().signal),
+    whenIdle: () => Promise.resolve(),
   }
 }
 
@@ -331,7 +337,7 @@ describe('pty-local plugin shape', () => {
 
     const session = ctx.sessions.create(SessionId('unowned-mode'))
     expect(() => {
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      session.append('turn/start', { turn: 1 })
     }).not.toThrow()
     expect(() => { setSandboxMode(session, 'read-only') }).not.toThrow()
   })
@@ -348,8 +354,13 @@ describe('pty-local plugin shape', () => {
     const session = ctx.sessions.create(SessionId('mode-owner'))
     const ownerFiber = await ctx.plugin(() => {})
     const owner: Agent = {
-      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      id: session.id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+      status: 'idle',
+      ctx: ownerFiber.ctx,
+      send: () => {},
+      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
+      runMaintenance: task => task(new AbortController().signal),
+      whenIdle: () => Promise.resolve(),
     }
     ctx.agents.register(owner)
     const providerFiber = await registerStubLocalBackend(ctx, () => stubLocalSession())
@@ -358,7 +369,7 @@ describe('pty-local plugin shape', () => {
     const unrelated = ctx.sessions.create(SessionId('unrelated-mode'))
     expect(() => { setSandboxMode(unrelated, 'read-only') }).not.toThrow()
     expect(() => {
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      session.append('turn/start', { turn: 1 })
     }).not.toThrow()
 
     expect(() => { setSandboxMode(session, 'danger-full-access') }).not.toThrow()
@@ -392,8 +403,13 @@ describe('pty-local plugin shape', () => {
     const session = ctx.sessions.create(SessionId('pending-mode-owner'))
     const ownerFiber = await ctx.plugin(() => {})
     const owner: Agent = {
-      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx: ownerFiber.ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      id: session.id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+      status: 'idle',
+      ctx: ownerFiber.ctx,
+      send: () => {},
+      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {},
+      runMaintenance: task => task(new AbortController().signal),
+      whenIdle: () => Promise.resolve(),
     }
     ctx.agents.register(owner)
     const gate = Promise.withResolvers<undefined>()
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 87a95c3170..22d971b251 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: b901a69d6cfd45a084711ba0d32e555c481fd626
-README.zh.md: 5723dc99ff955c5f4b07ea96e7d2134100d9fd6a
+README.md: 087ca24a3207cb8cb1568769a462fbbb010aaa35
+README.zh.md: 4d400906f71b653ce2be95a22751fd9893f447bd
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 9e3e8f7f2d..087ca24a32 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -6,9 +6,9 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 
 ## Behavior (and where it came from)
 
-- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F` (injectable for tests). `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — the same caveat as the surveyed tools.
+- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F`. `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — the same caveat as the surveyed tools.
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
-- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
+- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
 - **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative paths containing separators are rejected at the seam, and relative PATH entries resolve from the host process cwd.
 - **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
@@ -24,10 +24,10 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **Windows tree support is best-effort and untested in CI** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary; the suites cover the routing through an injected runner only, and `packages/subprocess/*` is excluded from the Windows test matrix.
+- **Windows tree support is best-effort** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary.
 - **Terminal process inspection is Linux/macOS only** — the terminal primitive fails when its inspector has no supported platform implementation; Linux exact probes cover x64 and arm64, while macOS uses `ps` snapshots.
 - **A daemonized terminal descendant can still escape the observable boundary** — on macOS, a child that reparents before any foreground-inspection snapshot is no longer discoverable from the `node-pty` root; on Linux, a child that calls `setsid` leaves both the tree and owned terminal session. The local provider does not add a continuous process-table monitor.
-- **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
+- **The credential scrub is a name heuristic** — `*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSPHRASE*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
 - **Completed spill files are not deleted** — bounded full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them; oversize incomplete spills are discarded and deletion is attempted immediately, but a cleanup failure can leave a bounded file behind.
 
 The raw process handling lives in `src/spawn.ts`; `src/index.ts` is the service wiring.
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 5723dc99ff..4d400906f7 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -6,9 +6,9 @@
 
 ## 行为（以及设计来源）
 
-- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树（可为测试注入）。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活，这与所调研工具的局限相同。
+- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活，这与所调研工具的局限相同。
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
-- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
 - **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在接缝处被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
@@ -24,7 +24,7 @@
 
 ## 已知限制与暂缓事项
 
-- **Windows 进程树支持仅为尽力而为，且未经 CI 测试**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界；测试套件只通过注入的运行器覆盖这条路由，且 `packages/subprocess/*` 被排除在 Windows 测试矩阵之外。
+- **Windows 进程树支持仅为尽力而为**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界。
 - **终端进程检查仅支持 Linux／macOS**：检查器没有受支持的平台实现时，终端原语会失败；Linux 精确探针覆盖 x64 与 arm64，macOS 则使用 `ps` 快照。
 - **守护化的终端后代仍可能逃出可观察边界**：在 macOS 上，子进程如果在任何前台检查快照之前重新设定父进程，将无法再从 `node-pty` 根进程发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与自有终端会话。本地提供方不会新增持续进程表监视器。
 - **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
diff --git a/packages/subprocess/subprocess-local/src/spawn.ts b/packages/subprocess/subprocess-local/src/spawn.ts
index 9fa70250dc..5b977cacc1 100644
--- a/packages/subprocess/subprocess-local/src/spawn.ts
+++ b/packages/subprocess/subprocess-local/src/spawn.ts
@@ -15,6 +15,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { setTimeout as sleepMs } from 'node:timers/promises'
 import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type {
   CollectedOutput,
   SubprocessCollect,
@@ -27,16 +28,16 @@ import { linuxProcessGroupHasLiveMembers } from './process-inspector.ts'
 
 /**
  * Build a child environment: explicit caller entries override the scrubbed
- * parent base using the target platform's environment-key semantics, so a
- * deliberately supplied credential or current `DSH_*` fact wins over the
- * scrub that dropped its ambient namesake.
- * @param extra - explicit caller entries merged after the scrubbed parent.
+ * parent base using the target platform's environment-key semantics. A string
+ * deliberately restores or overrides an entry; an explicit `undefined`
+ * tombstone removes an ordinary ambient entry.
+ * @param extra - explicit caller entries and tombstones, merged after the scrub.
  * @returns the environment to hand to `spawn` for the child process.
  */
-export function childEnv(extra?: Readonly<Record<string, string>>): NodeJS.ProcessEnv {
+export function childEnv(extra?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv {
   const env = scrubbedParentEnv()
   if (process.platform !== 'win32') return { ...env, ...extra }
-  let entries = Object.entries(env)
+  let entries: [string, string | undefined][] = Object.entries(env)
   for (const [key, value] of Object.entries(extra ?? {})) {
     const normalized = key.toUpperCase()
     entries = entries.filter(([inherited]) => inherited.toUpperCase() !== normalized)
@@ -310,8 +311,12 @@ function signalTree(
  * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
  * @param internals - test-only spill-directory, platform, and taskkill overrides.
  * @returns live subprocess handle.
+ * @throws when `graceMs` cannot be represented by one Node timer.
  */
 export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInternals = {}): SubprocessHandle {
+  if (!Number.isFinite(spec.graceMs) || spec.graceMs <= 0 || spec.graceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
   const spillDir = internals.spillDir ?? privateSpillDir()
   const platform = internals.platform ?? process.platform
   const taskkill = internals.taskkill ?? taskkillProcessTree
@@ -354,7 +359,9 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   const stdoutCollector = collectStream(outMode, child.stdout, 'stdout')
   const stderrCollector = collectStream(errMode, child.stderr, 'stderr')
 
-  let graceTimer: NodeJS.Timeout | undefined
+  let graceTimer: ReturnType<typeof setTimeout> | undefined
+  let treeExitObserved = false
+  let treeExitObservation: Promise<void> | undefined
   let settled = false
 
   // Failed spawns use pid -1 so signalling remains a no-op.
@@ -362,6 +369,9 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
 
   /** Whether the detached tree's root (or POSIX group) is still alive. */
   const treeAlive = (): boolean => {
+    /* v8 ignore next -- only a timer callback already queued when the observer settles can enter here;
+       the guard is the final defense against probing an id after its tree was confirmed absent. */
+    if (treeExitObserved) return false
     if (pid <= 0) return false
     if (platform === 'win32') {
       // Windows has no group-liveness probe; the direct child's exit is the
@@ -389,19 +399,40 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
     }
   }
 
+  /**
+   * Start or reuse the handle's single whole-tree exit observer. The first
+   * confirmed absence is a permanent no-more-signals boundary: it cancels a
+   * pending escalation before this process-group id can be reused.
+   */
+  const observeTreeExit = (): Promise<void> => {
+    treeExitObservation ??= (async () => {
+      while (treeAlive()) await sleepTick()
+      treeExitObserved = true
+      if (graceTimer !== undefined) clearTimeout(graceTimer)
+      graceTimer = undefined
+    })()
+    return treeExitObservation
+  }
+
   // The escalation's tier primitive (not on the handle — terminate() is the
   // only consumer-facing termination verb). Guards on TREE liveness, not
   // outcome settlement: a TERM-trapping helper can outlive the settled direct
   // child and must stay signalable, while a fully-dead tree (possible pid
   // reuse) must not be re-signalled by a later tier.
   const kill = (sig: NodeJS.Signals): void => {
+    /* v8 ignore next -- the shared exit observer cancels the ordinary dead-tree timer;
+       this remains the timer/death race guard and cannot be staged deterministically. */
     if (!treeAlive()) return
     signalTree(platform, pid, sig, child, taskkill)
   }
 
   const terminate = (): void => {
-    if (graceTimer !== undefined) return // escalation already in flight
-    if (!treeAlive()) return
+    if (treeExitObserved || graceTimer !== undefined) return
+    // Observe from the first termination tier onward, even when inherited
+    // pipes delay `done` and no consumer has begun its own teardown wait.
+    void observeTreeExit()
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- observer can record absence before its first await.
+    if (treeExitObserved) return
     kill('SIGTERM')
     // The escalation must survive direct-child settlement — the leader dying
     // does not mean the tree died — so settle does not clear this timer, and
@@ -423,7 +454,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   }
 
   const done = new Promise<SubprocessOutcome>((resolve, reject) => {
-    let pipeDrainTimer: NodeJS.Timeout | undefined
+    let pipeDrainTimer: ReturnType<typeof setTimeout> | undefined
     const settle = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
       if (settled) return
       settled = true
@@ -446,7 +477,9 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
       // A surviving descendant that inherited a pipe must not hold the
       // outcome open indefinitely: after exit, the same bounded grace that
       // governs kills also bounds the close wait.
-      pipeDrainTimer = setTimeout(() => { settle(exitCode, signal) }, spec.graceMs)
+      pipeDrainTimer = setTimeout(() => {
+        settle(exitCode, signal)
+      }, spec.graceMs)
     })
     child.on('close', settle)
     function cleanup(): void {
@@ -458,11 +491,23 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   })
 
   const waitForExit = async (signal?: AbortSignal): Promise<boolean> => {
-    while (treeAlive()) {
-      if (signal?.aborted) return false
-      await sleepTick()
+    const observed = observeTreeExit()
+    if (treeExitObserved) return true
+    if (signal?.aborted) return false
+    if (signal === undefined) {
+      await observed
+      return true
+    }
+    const aborted = Promise.withResolvers<boolean>()
+    const onAbort = (): void => { aborted.resolve(false) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    /* v8 ignore next -- closes the event-loop race between the preceding aborted check and listener registration. */
+    if (signal.aborted) onAbort()
+    try {
+      return await Promise.race([observed.then(() => true), aborted.promise])
+    } finally {
+      signal.removeEventListener('abort', onAbort)
     }
-    return true
   }
 
   return {
diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index f28f741992..6bac46ac16 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -280,18 +280,18 @@ describe('spawnSubprocess', () => {
 
   it('does not wait for a Linux group that has only zombie members', async () => {
     const pidFile = join(spillDir, `zombie-group-${Date.now()}.pid`)
-    let hasLiveMembers = false
     const running = spawnSubprocess(spec(`sleep 60 & echo $! > ${pidFile}; echo leader-done`, { graceMs: 100 }), {
       platform: 'linux',
-      linuxProcessGroupHasLiveMembers: () => hasLiveMembers,
+      linuxProcessGroupHasLiveMembers: () => false,
     })
     const descendant = await waitForPidFile(pidFile)
     try {
       await running.done
       await expect(running.waitForExit()).resolves.toBe(true)
     } finally {
-      hasLiveMembers = true
-      running.terminate()
+      // The confirmed-absent verdict is a permanent no-more-signals boundary,
+      // so terminate() must stay inert here; reap the live survivor directly.
+      process.kill(descendant, 'SIGKILL')
       await waitGone(descendant)
     }
   })
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index 5e93edd997..cf44d9aace 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/README.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 packages/code-runtime/code-runtime-subprocess/README.md
-README.md: 152921a1ed595676781aad170e3396f7ce613161
-README.zh.md: 3e8223c33c7ce85f342c9a36ab5a24c4d2a6cb94
+#   pnpm run verify-translation-pairing --write packages/typert/README.md
+README.md: ad9f843e48be0e3be85921ed8fd3ca4e2c327160
+README.zh.md: 0d4be016b766178b54f7e269583fa4200e3eb24b
diff --git a/packages/ui/app-boot/tsdown.config.ts b/packages/ui/app-boot/tsdown.config.ts
index 33db6be1b8..88492d7c26 100644
--- a/packages/ui/app-boot/tsdown.config.ts
+++ b/packages/ui/app-boot/tsdown.config.ts
@@ -1,6 +1,9 @@
 import { defineConfig } from 'tsdown'
 
-/** Bundle the host plugin and its dependency-free eval runner. */
+/**
+ * Embed Include while keeping Loader external so the built include tree and
+ * app host bind to one Loader peer.
+ */
 export default defineConfig({
   entry: ['lib/types/index.js', 'lib/types/invariant.js'],
   outDir: 'lib',
@@ -10,4 +13,7 @@ export default defineConfig({
   fixedExtension: false,
   dts: false,
   clean: false,
+  deps: {
+    alwaysBundle: ['@cordisjs/plugin-include'],
+  },
 })
diff --git a/packages/util/atomic-write/README.i18n.yaml b/packages/util/atomic-write/README.i18n.yaml
index efcd06f845..33e1f6014b 100644
--- a/packages/util/atomic-write/README.i18n.yaml
+++ b/packages/util/atomic-write/README.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 packages/code-runtime/code-runtime-subprocess/README.md
-README.md: 897112a32fa3e776df756d4caaba97b617c6af9e
-README.zh.md: d9ab3713640fe955d2b36a8f0674f77686e4791b
+#   pnpm run verify-translation-pairing --write packages/util/atomic-write/README.md
+README.md: 2ff4abb6ac10d8b592ccd2056b4f1f92cc8518b0
+README.zh.md: 4284d06422564268bb9e31d1a1ed06ab5271e562
diff --git a/packages/util/atomic-write/src/runner-source.generated.ts b/packages/util/atomic-write/src/runner-source.generated.ts
deleted file mode 100644
index 95da563dbb..0000000000
--- a/packages/util/atomic-write/src/runner-source.generated.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-/**
- * Generated dependency-free execution-world runner.
- * Do not edit by hand; run `pnpm run gen-code-runtime-runner`.
- */
-
-export const CODE_RUNNER_SOURCE = "import{Buffer as e}from\"node:buffer\";import{spawn as t}from\"node:child_process\";import{createInterface as n}from\"node:readline\";import{inspect as r}from\"node:util\";import{Worker as i,isMainThread as a,parentPort as o,workerData as s}from\"node:worker_threads\";const c=Reflect.apply,l=Array.isArray,u=Buffer,d=Reflect.get(Buffer,`byteLength`),f=Object.create,p=Object.defineProperty,ee=Object.keys,te=String,ne=Reflect.get(String.prototype,`charCodeAt`),re=Reflect.get(String.prototype,`codePointAt`),ie=Reflect.get(String.prototype,`slice`);function m(e){let t=f(null);return t.value=e,t}function ae(e,t,n){let r=m(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,p(e,t,r)}function h(e){return c(d,u,[e,`utf8`])}function g(e,t){ae(e,e.length,t)}function _(e){if(e.length===0)return;let t=e.length-1,n=e[t];return p(e,`length`,m(t)),n}function v(e,t){return c(ie,e,[t,t+(c(re,e,[t])>65535?2:1)])}function y(e){if(e.length===2)return 4;if(e===`\"`||e===`\\\\`)return 2;let t=c(ne,e,[0]);return t>=55296&&t<=57343?6:t<32?t===8||t===9||t===10||t===12||t===13?2:6:h(e)}function b(e,t){if(t<2)return;let n=2;for(let r=0;r<e.length;){let i=v(e,r);if(n+=y(i),n>t)return;r+=i.length}return n}function x(e,t){let n=0,r=e=>(n+=e,n<=t),i=[{kind:`value`,value:e}];for(let e=_(i);e!==void 0;e=_(i)){if(e.kind===`value`){let a=e.value;if(a===null){if(!r(4))return}else if(typeof a==`string`){let e=b(a,t-n);if(e===void 0)return;n+=e}else if(typeof a==`number`){if(!r(h(te(a))))return}else if(typeof a==`boolean`){if(!r(a?4:5))return}else if(l(a)){if(!r(2))return;a.length>0&&g(i,{kind:`array`,value:a,index:0})}else{if(!r(2))return;let e=ee(a);e.length>0&&g(i,{kind:`object`,value:a,keys:e,index:0})}continue}if(e.index>0&&!r(1))return;if(e.kind===`array`){let t=e.value[e.index];if(t===void 0)return;e.index+1<e.value.length&&g(i,{...e,index:e.index+1}),g(i,{kind:`value`,value:t});continue}let a=e.keys[e.index];if(a===void 0)return;let o=b(a,t-n);if(o===void 0||!r(o+1))return;let s=e.value[a];if(s===void 0)return;e.index+1<e.keys.length&&g(i,{...e,index:e.index+1}),g(i,{kind:`value`,value:s})}return n}function oe(e,t){if(t<2)return``;let n=2,r=0;for(let i=0;i<e.length;){let a=v(e,i),o=y(a);if(n+o>t)break;n+=o,r+=a.length,i+=a.length}return r===e.length?e:c(ie,e,[0,r])}const se=Reflect.get(Function.prototype,`toString`),S=Reflect.get(Reflect,`apply`),C=Error,ce=Set,w=Array.isArray,le=Array.prototype,T=Number.isFinite,ue=Number.isSafeInteger,de=Object.create,E=Object.defineProperty,fe=Object.getOwnPropertyDescriptor,D=Object.getPrototypeOf,O=Object.hasOwn,k=Object.is,pe=Object.keys,A=Object.prototype,me=Reflect.get(A,`propertyIsEnumerable`),j=Reflect.ownKeys,he=Reflect.get(Set.prototype,`add`),ge=Reflect.get(Set.prototype,`delete`),_e=Reflect.get(Set.prototype,`has`);function M(e){let t=de(null);return t.value=e,t}function N(e,t,n){let r=M(n);r.enumerable=!0,r.configurable=!0,r.writable=!0,E(e,t,r)}function P(e,t){N(e,e.length,t)}function F(e){if(e.length===0)return;let t=e.length-1,n=e[t];return E(e,`length`,M(t)),n}function I(e,t){return S(_e,e,[t])}function L(e,t){S(he,e,[t])}function ve(e,t){S(ge,e,[t])}function R(e,t){let n=fe(e,`constructor`)?.value;if(typeof n!=`function`)return!1;try{return n.name===t&&n.prototype===e&&S(se,n,[])===`function ${t}() { [native code] }`}catch{return!1}}function z(e){return D(e)===null&&R(e,`Object`)}function B(e){let t=D(e);if(t===le)return!0;if(!w(t)||!R(t,`Array`))return!1;let n=D(t);return typeof n==`object`&&!!n&&z(n)}function V(e){let t=D(e);return t===null||t===A||typeof t==`object`&&z(t)}function ye(e){let t=j(e);for(let n=0;n<t.length;n++){let r=t[n];if(typeof r!=`string`||!S(me,e,[r]))return}return t}function H(e){let t=new ce,n,r=(e,t)=>{e.kind===`root`?n=t:e.kind===`array`?N(e.target,e.index,t):N(e.target,e.key,t)},i=[{kind:`visit`,value:e,destination:{kind:`root`}}];for(let e=F(i);e!==void 0;e=F(i)){if(e.kind===`leave`){ve(t,e.source);continue}if(e.kind===`array-item`){if(!O(e.source,e.index))return;P(i,{kind:`visit`,value:e.source[e.index],destination:{kind:`array`,target:e.target,index:e.index}});continue}if(e.kind===`object-property`){P(i,{kind:`visit`,value:e.source[e.key],destination:{kind:`object`,target:e.target,key:e.key}});continue}let n=e.value;if(n===null){r(e.destination,null);continue}if(typeof n==`boolean`||typeof n==`string`){r(e.destination,n);continue}if(typeof n==`number`){if(!T(n)||k(n,-0))return;r(e.destination,n);continue}if(typeof n!=`object`||I(t,n))return;if(w(n)){if(!B(n))return;let a=n.length;if(j(n).length!==a+1)return;let o=[];r(e.destination,o),L(t,n),P(i,{kind:`leave`,source:n});for(let e=a-1;e>=0;e--)P(i,{kind:`array-item`,source:n,index:e,target:o});continue}if(!V(n))return;let a=ye(n);if(a===void 0)return;let o={};r(e.destination,o),L(t,n),P(i,{kind:`leave`,source:n});for(let e=a.length-1;e>=0;e--){let t=a[e];if(t===void 0)return;P(i,{kind:`object-property`,source:n,key:t,target:o})}}return n}function U(e){let t=[],n=[e];for(let e=F(n);e!==void 0;e=F(n)){if(e===null||typeof e==`boolean`||typeof e==`number`||typeof e==`string`){P(t,e);continue}if(w(e)){P(t,{kind:`array`,length:e.length});for(let t=e.length-1;t>=0;t--){let r=e[t];if(r===void 0)throw new C(`cannot encode a sparse JSON array`);P(n,r)}continue}let r=pe(e);P(t,{kind:`object`,keys:r});for(let t=r.length-1;t>=0;t--){let i=r[t];if(i===void 0)throw new C(`cannot encode a missing JSON object key`);let a=e[i];if(a===void 0)throw new C(`cannot encode an undefined JSON object property`);P(n,a)}}return t}function be(e){if(!B(e)||j(e).length!==e.length+1)return!1;for(let t=0;t<e.length;t++)if(!O(e,t))return!1;return!0}function W(e,t){for(let n=0;n<e.length;n++)if(e[n]===t)return!0;return!1}function xe(e){if(w(e)||!V(e))return;let t=ye(e);if(t===void 0)return;let n=e;if(n.kind===`array`){if(t.length!==2||!W(t,`kind`)||!W(t,`length`))return;let e=n.length;return typeof e==`number`&&ue(e)&&e>=0?{kind:`array`,length:e}:void 0}if(n.kind===`object`){if(t.length!==2||!W(t,`kind`)||!W(t,`keys`))return;let e=n.keys;if(!w(e)||!be(e))return;let r=new ce,i=[],a=e;for(let e=0;e<a.length;e++){let t=a[e];if(typeof t!=`string`||I(r,t))return;L(r,t),P(i,t)}return{kind:`object`,keys:i}}}function Se(e){try{if(!w(e)||!be(e)||e.length===0)return;let t=e,n=[],r,i=!1,a=e=>{let t=n[n.length-1];if(!t)return i?!1:(r=e,i=!0,!0);if(t.index>=(t.kind===`array`?t.length:t.keys.length))return!1;if(t.kind===`array`)P(t.target,e);else{let n=t.keys[t.index];if(n===void 0)return!1;N(t.target,n,e)}return t.index+=1,!0};for(let e=0;e<t.length;e++){let r=t[e],i,o;if(r===null||typeof r==`boolean`||typeof r==`string`)i=r;else if(typeof r==`number`){if(!T(r)||k(r,-0))return;i=r}else{if(typeof r!=`object`)return;let n=xe(r);if(!n)return;let a=t.length-e-1;if(n.kind===`array`){if(n.length>a)return;let e=[];i=e,n.length>0&&(o={kind:`array`,target:e,length:n.length,index:0})}else{if(n.keys.length>a)return;let e={};i=e,n.keys.length>0&&(o={kind:`object`,target:e,keys:n.keys,index:0})}}if(!a(i))return;for(o&&P(n,o);n.length>0;){let e=n[n.length-1];if(e===void 0||e.index<(e.kind===`array`?e.length:e.keys.length))break;F(n)}}return n.length===0?r:void 0}catch{return}}const G=Error,Ce=Object.create,we=Object.defineProperty;function Te(e,t,n){let r=Ce(null);r.enumerable=!0,r.value=n,we(e,t,r)}var Ee=class{bytes=2;entries=0;truncated=!1;sink;onLimit;maxBytes;constructor(e,t,n=()=>{}){this.maxBytes=e,this.sink=t,this.onLimit=n}push(e){if(this.truncated)return;let t=+(this.entries>0),n=this.maxBytes-this.bytes-t,r=b(e,n);if(r===void 0){this.truncated=!0;let r=oe(e,n);if(r.length>0){let e=b(r,n);if(e===void 0)throw new G(`worker output ledger produced an oversized log prefix`);this.bytes+=e+t,this.entries+=1,this.sink(r)}this.onLimit();return}this.bytes+=r+t,this.entries+=1,this.sink(e)}remainingOutputBytes(){return this.maxBytes-this.bytes}};const De=[`log`,`info`,`warn`,`error`,`debug`];function Oe(e){let t=e=>e.map(e=>typeof e==`string`?e:r(e,Ae)).join(` `),n=Object.create(null);for(let r of De)n[r]=(...n)=>{e.push(t(n))};return n}function ke(e,t){let n=t.write;return t.write=(t,...n)=>{e.push(typeof t==`string`?t:String(t));let r=[n[0],n[1]].find(e=>typeof e==`function`);return r&&queueMicrotask(()=>{r(null)}),!0},()=>{t.write=n}}const Ae={depth:4,maxArrayLength:100,maxStringLength:1e4};function je(e,t,n=t){if(e===void 0)return{};let r;try{r=H(e)}catch{r=void 0}return r===void 0?Ne(`invalid-output`,`program completion must be lossless JSON`,t,n):x(r,t)===void 0?Me(n):{value:U(r)}}function Me(e){return{error:{kind:`output-limit`,message:`outer output exceeded ${e} bytes`}}}function Ne(e,t,n,r){return b(t,n)===void 0?Me(r):{error:{kind:e,message:t}}}function Pe(e,t,n=t){let r;try{let t=e instanceof G?e.stack??e.message:e;r=typeof t==`string`?t:String(t)}catch{r=`program threw an unrenderable value`}return Ne(`exception`,r,t,n)}function Fe(e){return class extends G{constructor(t,n){super(n),Te(this,`name`,e.name),Te(this,e.memberNameProperty,t)}}}function K(e,t,n){return e?new e(t,n):new G(n)}function Ie(e){let t=new Map;for(let n of e.namespaces)n.errorClass&&t.set(n.global,Fe(n.errorClass));return t}function Le(e,t){e.on(`message`,e=>{let n=t.get(e.id);if(n)if(t.delete(e.id),e.ok){let t=Se(e.value);t===void 0?n.reject(new G(`binding resolution must be lossless JSON`)):n.resolve(t)}else n.reject(new G(e.message))})}function Re(e,t,n,r,i=Ie(e),a){return e.namespaces.map(({global:e,names:o})=>{let s=i.get(e),c=Object.create(null);for(let i of o)Object.defineProperty(c,i,{enumerable:!0,value:o=>{let c;try{c=H(o)}catch{c=void 0}if(c===void 0)return Promise.reject(K(s,i,`binding arguments must be lossless JSON`));let l={type:`call`,id:r.value,global:e,name:i,args:U(c)};return a!==void 0&&x(l,a)===void 0?Promise.reject(K(s,i,`binding arguments exceed maxFrameBytes`)):new Promise((e,a)=>{let o=r.value++;n.set(o,{resolve:e,reject:e=>{a(K(s,i,e.message))}});try{t.postMessage(l)}catch(e){n.delete(o),a(K(s,i,`binding arguments must be structured-cloneable: ${e instanceof G?e.message:String(e)}`))}})}});return c})}async function ze(e,t,n,r){let i=new Ee(t.maxOutputBytes,t=>{e.postMessage({type:`log`,text:t})},()=>{e.postMessage({type:`output-limit`})});ke(i,n.stdout),ke(i,n.stderr);let a=new Map;Le(e,a);let o={value:1},s=Ie(t),c=Re(t,e,a,o,s,r),l=[],u=[];for(let e of t.namespaces){if(!e.errorClass)continue;l.push(e.errorClass.name);let t=s.get(e.global);if(!t)throw new G(`missing binding error class for ${e.global}`);u.push(t)}let d=Oe(i),f;try{let e=(async()=>{}).constructor;f={type:`done`,...je(await new e(...t.namespaces.map(e=>e.global),...l,`console`,`'use strict';\\n${t.code}`)(...c,...u,d),i.remainingOutputBytes(),t.maxOutputBytes)}}catch(e){f={type:`done`,...Pe(e,i.remainingOutputBytes(),t.maxOutputBytes)}}e.postMessage(r!==void 0&&x(f,r)===void 0?{type:`output-limit`}:f)}function q(e){return e.readableEnded||e.destroyed?Promise.resolve():new Promise(t=>{let n=()=>{e.off(`end`,n),e.off(`close`,n),e.off(`error`,n),t()};e.once(`end`,n),e.once(`close`,n),e.once(`error`,n),(e.readableEnded||e.destroyed)&&n()})}const Be=new Set([`exception`,`timeout`,`abort`,`worker-exit`,`invalid-output`,`output-limit`]);let J=0;function Ve(){let e=process.execArgv.indexOf(`--eval`);if(e<0)throw Error(`code runtime runner requires its eval source`);let t=process.execArgv[e+1];if(t===void 0)throw Error(`code runtime runner requires its eval source`);return t}function Y(e){return typeof e==`object`&&e?e:void 0}function X(t,n){try{let r=JSON.stringify(t);return typeof r==`string`&&e.byteLength(r)<=n?r:void 0}catch{return}}function He(e){process.stdout.write(e),process.stdout.write(`\n`)}function Ue(e){let t=X(e,J);return t===void 0?!1:(He(t),!0)}function We(e){let t=Y(e);return t!==void 0&&typeof t.kind==`string`&&Be.has(t.kind)&&typeof t.message==`string`}function Ge(e){return We(e)&&(e.kind===`exception`||e.kind===`invalid-output`||e.kind===`output-limit`)}function Ke(e,t){return e.error===void 0?{type:`done`,...e.value===void 0?{}:{value:Q(e.value)}}:t(e.error)?{type:`done`,error:e.error}:void 0}function Z(e){let t=Y(e);if(!(t===void 0||t.type!==`boot`||typeof t.code!=`string`||!Array.isArray(t.namespaces)||!Number.isSafeInteger(t.maxOutputBytes)||t.maxOutputBytes<4||!Number.isSafeInteger(t.maxFrameBytes)||t.maxFrameBytes<t.maxOutputBytes||typeof t.computeMs!=`number`||!Number.isFinite(t.computeMs)||t.computeMs<=0||typeof t.maxOldGenerationSizeMb!=`number`||!Number.isFinite(t.maxOldGenerationSizeMb)||t.maxOldGenerationSizeMb<=0))return t}function qe(e){let t=Y(e);if(!(t===void 0||t.type!==`reply`||typeof t.id!=`number`||typeof t.ok!=`boolean`))return t.ok?{type:`reply`,id:t.id,ok:!0,value:t.value}:{type:`reply`,id:t.id,ok:!1,message:String(t.message)}}function Q(e){let t=Se(e);return t===void 0?null:U(t)}function Je(e){return e.exitCode!==null||e.signalCode!==null?Promise.resolve():new Promise(t=>{e.once(`exit`,()=>{t()})})}function $(){return{type:`done`,error:{kind:`worker-exit`,message:`code runtime bridge frame exceeded maxFrameBytes`}}}function Ye(){let e=n({input:process.stdin,crlfDelay:1/0}),r,i=0,a=2,o=0,s=!1,c=t=>{if(s)return;let n=X(t,J)??X($(),J);s=!0,n!==void 0&&He(n);let i=r;r=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=q(i.stdout),t=q(i.stderr),n=Je(i);i.kill(`SIGKILL`),await Promise.all([n,e,t])})).catch(e=>{process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(e)}\\n`)}).then(()=>{e.close(),process.stdin.destroy()})},l=e=>{if(s)return;let t=+(o>0),n=b(e,i-a-t);if(n===void 0){c({type:`output-limit`});return}a+=n+t,o+=1,Ue({type:`log`,text:e})||c($())},u=e=>{i=e.maxOutputBytes,J=e.maxFrameBytes,r=t(process.execPath,process.execArgv,{env:{DSH_CODE_RUNTIME_CONTROLLER:`1`},detached:!1,stdio:[`ignore`,`pipe`,`pipe`,`ipc`]});let n=r;n.stdout.on(`data`,e=>{l(e.toString(`utf8`))}),n.stderr.on(`data`,e=>{l(e.toString(`utf8`))}),n.on(`message`,e=>{let t=Y(e);if(t!==void 0){if(t.type===`log`&&typeof t.text==`string`){l(t.text);return}if(!s){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)Ue({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||c($());else if(t.type===`output-limit`)c({type:`output-limit`});else if(t.type===`done`){let e=Ke(t,We);e!==void 0&&c(e)}}}}),n.on(`error`,e=>{c({type:`done`,error:{kind:`worker-exit`,message:`remote controller error: ${e.message}`}})}),n.on(`exit`,e=>{s||c({type:`done`,error:{kind:`worker-exit`,message:`remote controller exited with code ${e} before completing`}})}),n.send(e,e=>{e!==null&&c({type:`done`,error:{kind:`worker-exit`,message:`remote controller boot failed: ${e.message}`}})})};e.on(`line`,e=>{let t;try{t=JSON.parse(e)}catch(e){process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(e)}\\n`),c({type:`done`,error:{kind:`worker-exit`,message:`remote runner received a malformed frame`}});return}if(r===void 0){let e=Z(t);if(e===void 0){c({type:`done`,error:{kind:`worker-exit`,message:`remote runner received an invalid boot frame`}});return}u(e);return}let n=qe(t);n!==void 0&&r.send(n,e=>{e!==null&&c({type:`done`,error:{kind:`worker-exit`,message:`remote controller reply failed: ${e.message}`}})})}),e.on(`close`,()=>{r!==void 0&&!s&&c({type:`done`,error:{kind:`abort`,message:`remote runner input closed`}})})}function Xe(){let t,n=!1,a,o=0,s=e=>process.send===void 0||o>0&&X(e,o)===void 0?!1:(process.send(e),!0),c=e=>{if(n)return;n=!0,clearInterval(a);let r=o>0&&X(e,o)===void 0?$():e,i=t;t=void 0,(i===void 0?Promise.resolve():new Promise(e=>{setImmediate(e)}).then(async()=>{let e=q(i.stdout),t=q(i.stderr);await Promise.all([i.terminate(),e,t])})).catch(e=>{s({type:`log`,text:`dsh-code-runtime-subprocess worker cleanup error: ${String(e)}\\n`})}).then(()=>{if(process.send===void 0){process.exitCode=1;return}process.send(r,()=>{process.connected&&process.disconnect()})})};process.on(`message`,l=>{if(t===void 0){let u=Z(l);if(u===void 0){c({type:`done`,error:{kind:`worker-exit`,message:`remote controller received an invalid boot frame`}});return}o=u.maxFrameBytes,t=new i(new URL(`data:text/javascript;base64,${e.from(Ve()).toString(`base64`)}`),{workerData:u,env:{},execArgv:[],stdout:!0,stderr:!0,resourceLimits:{maxOldGenerationSizeMb:u.maxOldGenerationSizeMb}});let d=t;d.stdout.on(`data`,e=>{s({type:`log`,text:e.toString(`utf8`)})||c($())}),d.stderr.on(`data`,e=>{s({type:`log`,text:e.toString(`utf8`)})||c($())}),d.on(`message`,e=>{let t=Y(e);if(t!==void 0){if(t.type===`call`&&typeof t.id==`number`&&typeof t.global==`string`&&typeof t.name==`string`)s({type:`call`,id:t.id,global:t.global,name:t.name,args:Q(t.args)})||c($());else if(t.type===`log`&&typeof t.text==`string`)s({type:`log`,text:t.text})||c($());else if(t.type===`output-limit`)c({type:`output-limit`});else if(t.type===`done`){let e=Ke(t,Ge);e!==void 0&&c(e)}}}),d.on(`error`,e=>{c({type:`done`,error:{kind:`worker-exit`,message:`worker error: ${e.stack||e.message||r(e)}`}})}),d.on(`exit`,e=>{n||c({type:`done`,error:{kind:`worker-exit`,message:`worker exited with code ${e} before completing`}})}),a=setInterval(()=>{t!==void 0&&t.performance.eventLoopUtilization().active>u.computeMs&&c({type:`done`,error:{kind:`timeout`,message:`compute budget exhausted (${u.computeMs}ms busy)`}})},25);return}let u=qe(l);u!==void 0&&t.postMessage(u)}),process.on(`disconnect`,()=>{t!==void 0&&!n&&t.terminate()})}if(a)process.env.DSH_CODE_RUNTIME_CONTROLLER===`1`?Xe():Ye();else{if(o===null)throw Error(`remote worker requires parentPort`);let e=s;ze(o,e,{stdout:process.stdout,stderr:process.stderr},e.maxFrameBytes)}export{};"
diff --git a/packages/util/atomic-write/src/runner.ts b/packages/util/atomic-write/src/runner.ts
deleted file mode 100644
index 2655d22026..0000000000
--- a/packages/util/atomic-write/src/runner.ts
+++ /dev/null
@@ -1,401 +0,0 @@
-/** Typed source for the dependency-free execution-world runner bundle. */
-
-import { Buffer } from 'node:buffer'
-import { spawn } from 'node:child_process'
-import type { ChildProcess } from 'node:child_process'
-import { createInterface } from 'node:readline'
-import type { Readable } from 'node:stream'
-import { inspect } from 'node:util'
-import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
-import {
-  decodeWorkerJson,
-  encodeWorkerJson,
-  jsonStringBytesUpTo,
-  runWorkerMain,
-  waitForRuntimePipeDrain,
-} from '@deepseek-ai/dsh-code-runtime-worker/runtime-host'
-import type { WorkerJsonWire } from '@deepseek-ai/dsh-code-runtime-worker/runtime-host'
-
-type WorkerBootData = Parameters<typeof runWorkerMain>[1]
-type Controller = ChildProcess & { stdout: Readable; stderr: Readable }
-type FailureKind = 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'
-
-interface RuntimeBootData extends WorkerBootData {
-  type: 'boot'
-  maxFrameBytes: number
-  maxOldGenerationSizeMb: number
-  computeMs: number
-}
-
-interface RuntimeFailure {
-  kind: FailureKind
-  message: string
-}
-
-interface RuntimeCall {
-  type: 'call'
-  id: number
-  global: string
-  name: string
-  args: WorkerJsonWire | null
-}
-
-type RuntimeReply =
-  | { type: 'reply'; id: number; ok: true; value: unknown }
-  | { type: 'reply'; id: number; ok: false; message: string }
-
-type RuntimeMessage = RuntimeCall
-  | { type: 'log'; text: string }
-  | { type: 'output-limit' }
-  | { type: 'done'; value?: WorkerJsonWire | null; error?: RuntimeFailure }
-
-const failureKinds = new Set<FailureKind>([
-  'exception', 'timeout', 'abort', 'worker-exit', 'invalid-output', 'output-limit',
-])
-
-let maxFrameBytes = 0
-
-function runnerSource(): string {
-  const evalIndex = process.execArgv.indexOf('--eval')
-  if (evalIndex < 0) throw new Error('code runtime runner requires its eval source')
-  const source = process.execArgv[evalIndex + 1]
-  if (source === undefined) throw new Error('code runtime runner requires its eval source')
-  return source
-}
-
-function recordOf(value: unknown): Record<string, unknown> | undefined {
-  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : undefined
-}
-
-function encodeJsonBounded(value: unknown, maxBytes: number): string | undefined {
-  try {
-    const json: unknown = JSON.stringify(value)
-    return typeof json === 'string' && Buffer.byteLength(json) <= maxBytes ? json : undefined
-  } catch {
-    return undefined
-  }
-}
-
-function emitJson(json: string): void {
-  process.stdout.write(json)
-  process.stdout.write('\n')
-}
-
-function emitFrame(message: RuntimeMessage): boolean {
-  const json = encodeJsonBounded(message, maxFrameBytes)
-  if (json === undefined) return false
-  emitJson(json)
-  return true
-}
-
-function validFailure(value: unknown): value is RuntimeFailure {
-  const record = recordOf(value)
-  return record !== undefined
-    && typeof record.kind === 'string'
-    && failureKinds.has(record.kind as FailureKind)
-    && typeof record.message === 'string'
-}
-
-function validWorkerFailure(value: unknown): value is RuntimeFailure {
-  return validFailure(value)
-    && (value.kind === 'exception' || value.kind === 'invalid-output' || value.kind === 'output-limit')
-}
-
-function doneMessage(
-  message: Record<string, unknown>,
-  acceptsFailure: (value: unknown) => value is RuntimeFailure,
-): RuntimeMessage | undefined {
-  if (message.error !== undefined) {
-    return acceptsFailure(message.error) ? { type: 'done', error: message.error } : undefined
-  }
-  return { type: 'done', ...message.value === undefined ? {} : { value: transportWireOrNull(message.value) } }
-}
-
-function runtimeBoot(value: unknown): RuntimeBootData | undefined {
-  const record = recordOf(value)
-  if (record === undefined
-    || record.type !== 'boot'
-    || typeof record.code !== 'string'
-    || !Array.isArray(record.namespaces)
-    || !Number.isSafeInteger(record.maxOutputBytes)
-    || (record.maxOutputBytes as number) < 4
-    || !Number.isSafeInteger(record.maxFrameBytes)
-    || (record.maxFrameBytes as number) < (record.maxOutputBytes as number)
-    || typeof record.computeMs !== 'number'
-    || !Number.isFinite(record.computeMs)
-    || (record.computeMs) <= 0
-    || typeof record.maxOldGenerationSizeMb !== 'number'
-    || !Number.isFinite(record.maxOldGenerationSizeMb)
-    || (record.maxOldGenerationSizeMb) <= 0) return undefined
-  return record as unknown as RuntimeBootData
-}
-
-function runtimeReply(value: unknown): RuntimeReply | undefined {
-  const record = recordOf(value)
-  if (record === undefined || record.type !== 'reply' || typeof record.id !== 'number' || typeof record.ok !== 'boolean') return undefined
-  return record.ok
-    ? { type: 'reply', id: record.id, ok: true, value: record.value }
-    : { type: 'reply', id: record.id, ok: false, message: String(record.message) }
-}
-
-function transportWireOrNull(input: unknown): WorkerJsonWire | null {
-  const value = decodeWorkerJson(input)
-  return value === undefined ? null : encodeWorkerJson(value)
-}
-
-function waitForChildExit(child: ChildProcess): Promise<void> {
-  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
-  return new Promise((resolve) => { child.once('exit', () => { resolve() }) })
-}
-
-function frameLimitFailure(): RuntimeMessage {
-  return {
-    type: 'done',
-    error: { kind: 'worker-exit', message: 'code runtime bridge frame exceeded maxFrameBytes' },
-  }
-}
-
-function runLauncher(): void {
-  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
-  let controller: Controller | undefined
-  let maxOutputBytes = 0
-  let logBytes = 2
-  let logEntries = 0
-  let settling = false
-
-  const finish = (message: RuntimeMessage): void => {
-    if (settling) return
-    const encoded = encodeJsonBounded(message, maxFrameBytes)
-      ?? encodeJsonBounded(frameLimitFailure(), maxFrameBytes)
-    settling = true
-    if (encoded !== undefined) emitJson(encoded)
-    const current = controller
-    controller = undefined
-    const drain = current === undefined
-      ? Promise.resolve()
-      : new Promise<void>((resolve) => { setImmediate(resolve) }).then(async () => {
-        const stdoutDrained = waitForRuntimePipeDrain(current.stdout)
-        const stderrDrained = waitForRuntimePipeDrain(current.stderr)
-        const exited = waitForChildExit(current)
-        current.kill('SIGKILL')
-        await Promise.all([exited, stdoutDrained, stderrDrained])
-      })
-    void drain.catch((error: unknown) => {
-      process.stderr.write(`dsh-code-runtime-subprocess controller cleanup error: ${String(error)}\n`)
-    }).then(() => {
-      input.close()
-      process.stdin.destroy()
-    })
-  }
-
-  const forwardLog = (text: string): void => {
-    if (settling) return
-    const separator = logEntries > 0 ? 1 : 0
-    const cost = jsonStringBytesUpTo(text, maxOutputBytes - logBytes - separator)
-    if (cost === undefined) {
-      finish({ type: 'output-limit' })
-      return
-    }
-    logBytes += cost + separator
-    logEntries += 1
-    if (!emitFrame({ type: 'log', text })) finish(frameLimitFailure())
-  }
-
-  const startController = (boot: RuntimeBootData): void => {
-    maxOutputBytes = boot.maxOutputBytes
-    maxFrameBytes = boot.maxFrameBytes
-    controller = spawn(process.execPath, process.execArgv, {
-      env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
-      detached: false,
-      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
-    }) as Controller
-    const current = controller
-    current.stdout.on('data', (data: Buffer) => { forwardLog(data.toString('utf8')) })
-    current.stderr.on('data', (data: Buffer) => { forwardLog(data.toString('utf8')) })
-    current.on('message', (raw: unknown) => {
-      const message = recordOf(raw)
-      if (message === undefined) return
-      if (message.type === 'log' && typeof message.text === 'string') {
-        forwardLog(message.text)
-        return
-      }
-      if (settling) return
-      if (message.type === 'call'
-        && typeof message.id === 'number'
-        && typeof message.global === 'string'
-        && typeof message.name === 'string') {
-        if (!emitFrame({
-          type: 'call', id: message.id, global: message.global, name: message.name, args: transportWireOrNull(message.args),
-        })) finish(frameLimitFailure())
-      } else if (message.type === 'output-limit') {
-        finish({ type: 'output-limit' })
-      } else if (message.type === 'done') {
-        const done = doneMessage(message, validFailure)
-        if (done !== undefined) finish(done)
-      }
-    })
-    current.on('error', (error: Error) => {
-      finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller error: ${error.message}` } })
-    })
-    current.on('exit', (code: number | null) => {
-      if (!settling) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller exited with code ${code} before completing` } })
-      }
-    })
-    current.send(boot, (error: Error | null) => {
-      if (error !== null) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller boot failed: ${error.message}` } })
-      }
-    })
-  }
-
-  input.on('line', (line: string) => {
-    let raw: unknown
-    try {
-      raw = JSON.parse(line) as unknown
-    } catch (error: unknown) {
-      process.stderr.write(`dsh-code-runtime-subprocess frame error: ${String(error)}\n`)
-      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received a malformed frame' } })
-      return
-    }
-    if (controller === undefined) {
-      const boot = runtimeBoot(raw)
-      if (boot === undefined) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
-        return
-      }
-      startController(boot)
-      return
-    }
-    const reply = runtimeReply(raw)
-    if (reply !== undefined) {
-      controller.send(reply, (error: Error | null) => {
-        if (error !== null) {
-          finish({ type: 'done', error: { kind: 'worker-exit', message: `remote controller reply failed: ${error.message}` } })
-        }
-      })
-    }
-  })
-  input.on('close', () => {
-    if (controller !== undefined && !settling) {
-      finish({ type: 'done', error: { kind: 'abort', message: 'remote runner input closed' } })
-    }
-  })
-}
-
-function runController(): void {
-  let worker: Worker | undefined
-  let finished = false
-  let computeTimer: NodeJS.Timeout | undefined
-  let controllerMaxFrameBytes = 0
-
-  const send = (message: RuntimeMessage): boolean => {
-    if (process.send === undefined) return false
-    if (controllerMaxFrameBytes > 0 && encodeJsonBounded(message, controllerMaxFrameBytes) === undefined) return false
-    process.send(message)
-    return true
-  }
-
-  const finish = (message: RuntimeMessage): void => {
-    if (finished) return
-    finished = true
-    clearInterval(computeTimer)
-    const bounded = controllerMaxFrameBytes > 0 && encodeJsonBounded(message, controllerMaxFrameBytes) === undefined
-      ? frameLimitFailure()
-      : message
-    const current = worker
-    worker = undefined
-    const drain = current === undefined
-      ? Promise.resolve()
-      : new Promise<void>((resolve) => { setImmediate(resolve) }).then(async () => {
-        const stdoutDrained = waitForRuntimePipeDrain(current.stdout)
-        const stderrDrained = waitForRuntimePipeDrain(current.stderr)
-        await Promise.all([current.terminate(), stdoutDrained, stderrDrained])
-      })
-    void drain.catch((error: unknown) => {
-      send({ type: 'log', text: `dsh-code-runtime-subprocess worker cleanup error: ${String(error)}\n` })
-    }).then(() => {
-      if (process.send === undefined) {
-        process.exitCode = 1
-        return
-      }
-      process.send(bounded, () => { if (process.connected) process.disconnect() })
-    })
-  }
-
-  process.on('message', (raw: unknown) => {
-    if (worker === undefined) {
-      const boot = runtimeBoot(raw)
-      if (boot === undefined) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller received an invalid boot frame' } })
-        return
-      }
-      controllerMaxFrameBytes = boot.maxFrameBytes
-      const sourceUrl = new URL(`data:text/javascript;base64,${Buffer.from(runnerSource()).toString('base64')}`)
-      worker = new Worker(sourceUrl, {
-        workerData: boot,
-        env: {},
-        execArgv: [],
-        stdout: true,
-        stderr: true,
-        resourceLimits: { maxOldGenerationSizeMb: boot.maxOldGenerationSizeMb },
-      })
-      const current = worker
-      current.stdout.on('data', (data: Buffer) => {
-        if (!send({ type: 'log', text: data.toString('utf8') })) finish(frameLimitFailure())
-      })
-      current.stderr.on('data', (data: Buffer) => {
-        if (!send({ type: 'log', text: data.toString('utf8') })) finish(frameLimitFailure())
-      })
-      current.on('message', (messageRaw: unknown) => {
-        const message = recordOf(messageRaw)
-        if (message === undefined) return
-        if (message.type === 'call'
-          && typeof message.id === 'number'
-          && typeof message.global === 'string'
-          && typeof message.name === 'string') {
-          if (!send({
-            type: 'call', id: message.id, global: message.global, name: message.name, args: transportWireOrNull(message.args),
-          })) finish(frameLimitFailure())
-        } else if (message.type === 'log' && typeof message.text === 'string') {
-          if (!send({ type: 'log', text: message.text })) finish(frameLimitFailure())
-        } else if (message.type === 'output-limit') {
-          finish({ type: 'output-limit' })
-        } else if (message.type === 'done') {
-          const done = doneMessage(message, validWorkerFailure)
-          if (done !== undefined) finish(done)
-        }
-      })
-      current.on('error', (error: Error) => {
-        finish({
-          type: 'done',
-          error: { kind: 'worker-exit', message: `worker error: ${error.stack || error.message || inspect(error)}` },
-        })
-      })
-      current.on('exit', (code: number) => {
-        if (!finished) {
-          finish({ type: 'done', error: { kind: 'worker-exit', message: `worker exited with code ${code} before completing` } })
-        }
-      })
-      computeTimer = setInterval(() => {
-        if (worker !== undefined && worker.performance.eventLoopUtilization().active > boot.computeMs) {
-          finish({ type: 'done', error: { kind: 'timeout', message: `compute budget exhausted (${boot.computeMs}ms busy)` } })
-        }
-      }, 25)
-      return
-    }
-    const reply = runtimeReply(raw)
-    if (reply !== undefined) worker.postMessage(reply)
-  })
-  process.on('disconnect', () => { if (worker !== undefined && !finished) void worker.terminate() })
-}
-
-if (!isMainThread) {
-  if (parentPort === null) throw new Error('remote worker requires parentPort')
-  const boot = workerData as RuntimeBootData
-  void runWorkerMain(parentPort, boot, { stdout: process.stdout, stderr: process.stderr }, boot.maxFrameBytes)
-} else if (process.env.DSH_CODE_RUNTIME_CONTROLLER === '1') {
-  runController()
-} else {
-  runLauncher()
-}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 666d01c1c1..87648e01e1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4275,6 +4275,12 @@ importers:
       '@deepseek-ai/dsh-brand':
         specifier: workspace:^
         version: link:../../util/brand
+      '@deepseek-ai/dsh-fs':
+        specifier: workspace:^
+        version: link:../../fs/fs
+      '@deepseek-ai/dsh-fs-local':
+        specifier: workspace:^
+        version: link:../../fs/fs-local
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -4312,6 +4318,9 @@ importers:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
+      '@deepseek-ai/dsh-fs-local':
+        specifier: workspace:^
+        version: link:../../fs/fs-local
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -4327,6 +4336,9 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess-local
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -4440,9 +4452,6 @@ importers:
 
   packages/pty/pty-local:
     dependencies:
-      node-pty:
-        specifier: ^1.1.0
-        version: 1.1.0(patch_hash=7a0c04f1f49d798a9ffe2f7f414c01064a44ca2489772d0c3e1235ab336755e6)
       schemastery:
         specifier: ^3.18.0
         version: link:../../../vendor/schemastery
@@ -4468,6 +4477,9 @@ importers:
       '@deepseek-ai/dsh-subprocess':
         specifier: workspace:^
         version: link:../../subprocess/subprocess
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess-local
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -4563,6 +4575,9 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess-local
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -5940,6 +5955,10 @@ importers:
         version: link:../../../vendor/cordis
 
   packages/subprocess/subprocess-local:
+    dependencies:
+      node-pty:
+        specifier: ^1.1.0
+        version: 1.1.0(patch_hash=7a0c04f1f49d798a9ffe2f7f414c01064a44ca2489772d0c3e1235ab336755e6)
     devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 00520bdbe7..e254696491 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -48,9 +48,13 @@ interface EventRelation {
   listeners: Set<string>
 }
 
-interface PackageSource {
+/** One scanned package source file and its owning package short name. */
+export interface PackageSource {
+  /** Repository-relative path. */
   rel: string
+  /** Package short name from the `packages/<group>/<pkg>/src` path. */
   pkg: string
+  /** The bound program source file. */
   sourceFile: ts.SourceFile
 }
 
@@ -120,7 +124,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session',
     title: 'In-memory session store',
     mode: 'core',
-    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
+    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
     note: 'Owns append-only Session instances and emits the durable session event feed.',
   },
   {
@@ -155,6 +159,24 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'session-query', 'session-query-sqlite'],
     note: 'Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time.',
   },
+  {
+    key: 'settings',
+    pkg: 'settings',
+    title: 'User-settings seam',
+    mode: 'seam',
+    implementations: ['settings-local'],
+    consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
+    note: 'Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer.',
+  },
+  {
+    key: 'credentials',
+    pkg: 'credentials',
+    title: 'Credential seam',
+    mode: 'seam',
+    implementations: ['credentials-local'],
+    consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
+    note: 'Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage.',
+  },
   {
     key: 'telemetry',
     pkg: 'session-telemetry',
@@ -203,7 +225,6 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session-reference',
     title: 'Cross-session snapshot preparation',
     mode: 'core',
-    consumers: ['tui'],
     note: 'Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax.',
   },
   {
@@ -235,8 +256,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'user-interaction',
     title: 'Human question/answer seam',
     mode: 'seam',
-    implementations: ['tui'],
-    consumers: ['tool-ask-user', 'tui'],
+    consumers: ['tool-ask-user'],
     note: 'UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.',
   },
   {
@@ -251,8 +271,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'commands',
     title: 'Human command registry',
     mode: 'core',
-    consumers: ['tui'],
-    note: 'Plugins register direct human commands; TUI consumes the effective per-agent catalog without sending invocations to the model.',
+    note: 'Plugins register direct human commands without sending invocations to the model.',
   },
   {
     key: 'sessionProjections',
@@ -270,19 +289,12 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['host-apiproxy'],
     note: 'Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs.',
   },
-  {
-    key: 'tui',
-    pkg: 'tui',
-    title: 'Mounted-terminal interaction service',
-    mode: 'bundle',
-    note: 'One TUI front door provides a FIFO overlay host; injected plugins receive caller-fiber ownership without access to pi-tui or terminal lifecycle state.',
-  },
   {
     key: 'skills',
     pkg: 'skill',
     title: 'Skill provider registry',
     mode: 'seam',
-    implementations: ['skill-local'],
+    implementations: ['skill-badge', 'skill-local'],
     consumers: ['tool-skill'],
     note: 'Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies.',
   },
@@ -291,7 +303,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'agent',
     title: 'Agent service',
     mode: 'core',
-    consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'tui-demo'],
+    consumers: ['agent-loop', 'acp', 'subagent-inprocess'],
     note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
   },
   {
@@ -315,24 +327,25 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Subprocess seam',
     mode: 'seam',
     implementations: ['subprocess-local'],
-    consumers: ['bash-local', 'bash-sandbox', 'pty-local', 'lsp-local', 'subagent-acp'],
-    note: 'The bash executors, PTY shell backend, LSP host, and ACP subagent backend spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation.',
+    consumers: ['bash-local', 'bash-sandbox', 'pty-local', 'lsp-local', 'subagent-acp', 'subagent-codex', 'subagent-claude-code'],
+    note: 'The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation.',
   },
   {
     key: 'bash',
     pkg: 'bash',
     title: 'Bash executor seam',
     mode: 'seam',
-    implementations: ['bash-local', 'bash-sandbox'],
-    consumers: ['tool-bash', 'hooks-claude', 'hooks-codex'],
-    note: 'The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them.',
+    implementations: ['bash-local', 'bash-sandbox', 'pwsh-local'],
+    consumers: ['tool-bash', 'tool-pwsh', 'hooks-claude', 'hooks-codex'],
+    note: 'The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them.',
   },
   {
     key: 'bashEnv',
-    pkg: 'tool-bash',
+    pkg: 'bash-env',
     title: 'Managed bash environment registry',
     mode: 'core',
-    note: 'Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace.',
+    consumers: ['tool-bash', 'tool-pwsh'],
+    note: 'Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace.',
   },
   {
     key: 'pty',
@@ -409,11 +422,11 @@ const SERVICE_ROLES: ServiceRole[] = [
   {
     key: 'subagents',
     pkg: 'subagent',
-    title: 'Subagent provider registry',
+    title: 'Subagent provider and continuation service',
     mode: 'seam',
-    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
-    consumers: ['tool-subagent', 'tool-ralph'],
-    note: 'Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route.',
+    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp', 'subagent-codex', 'subagent-claude-code', 'subagent-dsh-sdk'],
+    consumers: ['tool-subagent', 'tool-subagent-control', 'tool-ralph'],
+    note: 'Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route.',
   },
   {
     key: 'tasks',
@@ -592,7 +605,8 @@ function parseExampleCordis(rel: string): ExamplePlugin[] {
     if (current?.name) plugins.push({ id: current.id, name: current.name })
   }
   for (const line of text.split('\n')) {
-    const id = /^-\s+id:\s+(.+?)\s*$/.exec(line)
+    // Top-level rows (`- id:`) and bundle-patch insert rows (`    - id:`).
+    const id = /^\s*-\s+id:\s+(.+?)\s*$/.exec(line)
     if (id?.[1] !== undefined) {
       flush()
       current = { id: stripYamlScalar(id[1]) }
@@ -611,28 +625,20 @@ function stripYamlScalar(value: string): string {
 
 const APP_EXAMPLES = [
   {
-    id: 'tui',
-    rel: 'examples/tui-agent/composition.md',
-    title: 'TUI Agent App Composition',
-    label: 'examples/tui-agent',
-    config: 'examples/tui-agent/cordis.yml',
-    summary: 'The TUI agent combines the real DeepSeek adapter, coding tools, compaction, subagents, and workflows with the full-screen terminal app package.',
+    id: 'dsh_base',
+    rel: 'apps/cli/composition.md',
+    title: 'DSH Base Composition',
+    label: 'packages/bundle/base/cordis.patch.yml',
+    config: 'packages/bundle/base/cordis.patch.yml',
+    summary: 'The dsh-base bundle patch every profile applies first; mode bundles (dsh-web-app, dsh-headless) and the user\'s profile layer patch over it.',
   },
   {
     id: 'headless',
     rel: 'examples/headless-agent/composition.md',
-    title: 'Headless Agent App Composition',
+    title: 'Headless Agent Snapshot Composition',
     label: 'examples/headless-agent',
     config: 'examples/headless-agent/cordis.yml',
-    summary: 'The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.',
-  },
-  {
-    id: 'cordis',
-    rel: 'examples/cordis-agent/composition.md',
-    title: 'Cordis Agent App Composition',
-    label: 'examples/cordis-agent',
-    config: 'examples/cordis-agent/cordis.yml',
-    summary: 'The self-referential demo puts @deepseek-ai/dsh-tool-cordis on the coding spine, letting the agent inspect its current-process runtime and mount or unmount in-memory temporary Plugins.',
+    summary: 'The headless snapshot composition combines the real DeepSeek adapter and coding capabilities with one explicitly configured persisted top-level agent; its JSONL driver is test-only.',
   },
   {
     id: 'acp',
@@ -651,11 +657,7 @@ function renderAppExpansion(lines: string[], appNode: string, pluginName: string
   const jsonl = nodeId('bundle', 'jsonl')
   lines.push(`  ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`)
   lines.push(`  ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
-  if (pluginName === '@deepseek-ai/dsh-tui-demo') {
-    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'tui')}["@deepseek-ai/dsh-tui<br/>pre-created main agent"]`)
-  } else if (pluginName === '@deepseek-ai/dsh-cli-demo') {
-    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'cli')}["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]`)
-  } else if (pluginName === '@deepseek-ai/dsh-acp-demo') {
+  if (pluginName === '@deepseek-ai/dsh-acp-demo') {
     lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>automation-only JSON-RPC stdio<br/>fresh sessions created by client"]`)
   }
   lines.push(
@@ -681,7 +683,7 @@ function renderAppComposition(example: AppExample): string {
     const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
     lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
     lines.push(`  cfg --> ${pluginNode}`)
-    if (plugin.name === '@deepseek-ai/dsh-tui-demo' || plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
+    if (plugin.name === '@deepseek-ai/dsh-acp-demo') {
       renderAppExpansion(lines, pluginNode, plugin.name)
     }
   }
@@ -698,13 +700,26 @@ function renderAppComposition(example: AppExample): string {
   return lines.join('\n')
 }
 
+type CallSiteIndex = Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>
+
+/**
+ * The only method names visitSource classifies; receiver typing runs on these
+ * alone. Obligation: every method name matched by a branch inside visitSource
+ * must appear here — the prefilter drops non-members before any branch runs,
+ * so a branch for an unlisted name is silently dead.
+ */
+const EVENT_API_METHODS = new Set(['on', 'once', 'emit', 'parallel', 'serial', 'waterfall', 'dispatch'])
+
 /** Collect event dispatch/listener relations from real cross-file receiver types. */
-class EventRelationCollector {
+export class EventRelationCollector {
   private readonly relations = new Map<string, EventRelation>()
-  private readonly callSites = new Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>()
+  private readonly fileCallSites = new Map<ts.SourceFile, CallSiteIndex>()
+  private readonly localCalleeProofs = new Map<ts.FunctionDeclaration, boolean>()
+  private globalCallSites: CallSiteIndex | null = null
   private readonly contextType: ts.Type
   private readonly agentDispatchType: ts.Type
   private readonly eventsServiceType: ts.Type
+  private readonly packageSourceFiles: ReadonlySet<ts.SourceFile>
 
   constructor(
     private readonly project: TypeScriptProject,
@@ -713,7 +728,7 @@ class EventRelationCollector {
     this.contextType = this.declaredType('vendor/cordis/src/context.ts', 'Context')
     this.agentDispatchType = this.declaredType('packages/core/agent/src/dispatch.ts', 'AgentEventDispatch')
     this.eventsServiceType = this.declaredType('vendor/cordis/src/events.ts', 'EventsService')
-    this.indexCallSites()
+    this.packageSourceFiles = new Set(sources.map(source => source.sourceFile))
   }
 
   /** Return all event relations discovered from the Program. */
@@ -733,20 +748,88 @@ class EventRelationCollector {
     return this.project.checker.getDeclaredTypeOfSymbol(symbol)
   }
 
-  /** Index resolved local function calls for narrow argument-flow recovery. */
-  private indexCallSites(): void {
+  /** Index resolved function calls in the given files for narrow argument-flow recovery. */
+  private buildCallSiteIndex(files: Iterable<ts.SourceFile>): CallSiteIndex {
+    const index: CallSiteIndex = new Map()
     const visit = (node: ts.Node): void => {
       if (ts.isCallExpression(node)) {
         const declaration = this.project.checker.getResolvedSignature(node)?.declaration
         if (declaration) {
-          const calls = this.callSites.get(declaration) ?? []
+          const calls = index.get(declaration) ?? []
           calls.push(node)
-          this.callSites.set(declaration, calls)
+          index.set(declaration, calls)
         }
       }
       ts.forEachChild(node, visit)
     }
-    for (const source of this.sources) visit(source.sourceFile)
+    for (const file of files) visit(file)
+    return index
+  }
+
+  /**
+   * Return every indexed call resolving to one local helper declaration.
+   * Fast path: when every same-file reference to the non-exported helper is
+   * provably a direct callee, module scoping confines all of its calls to that
+   * file, so only that file is indexed. Any other reference shape may alias
+   * the function value outward, so the original full package-source index
+   * decides instead.
+   */
+  private callSitesFor(owner: ts.FunctionDeclaration): ts.CallExpression[] {
+    if (!this.globalCallSites && !this.provenLocalCallee(owner)) {
+      this.globalCallSites = this.buildCallSiteIndex(this.packageSourceFiles)
+    }
+    if (this.globalCallSites) return this.globalCallSites.get(owner) ?? []
+    const file = owner.getSourceFile()
+    let index = this.fileCallSites.get(file)
+    if (!index) {
+      index = this.buildCallSiteIndex([file])
+      this.fileCallSites.set(file, index)
+    }
+    return index.get(owner) ?? []
+  }
+
+  /**
+   * Prove every same-file reference to one helper is a direct callee. The
+   * proof owns its premises: an exported helper or a helper in a global
+   * script file (no import/export means program-wide scope, callable from
+   * another file with no same-file reference at all) fails immediately.
+   * Alias escapes (re-export statements, default exports, value reads)
+   * resolve back to the owner symbol at a non-callee position and fail the
+   * proof, as does anything the scan cannot positively classify.
+   */
+  private provenLocalCallee(owner: ts.FunctionDeclaration): boolean {
+    const cached = this.localCalleeProofs.get(owner)
+    if (cached !== undefined) return cached
+    if (hasExportModifier(owner) || !ts.isExternalModule(owner.getSourceFile())) {
+      this.localCalleeProofs.set(owner, false)
+      return false
+    }
+    const name = owner.name
+    const ownerSymbol = name && this.project.checker.getSymbolAtLocation(name)
+    let proven = !!ownerSymbol
+    const refersToOwner = (identifier: ts.Identifier): boolean => {
+      // Shorthand properties resolve to the property symbol; ask for the value side.
+      const local = ts.isShorthandPropertyAssignment(identifier.parent)
+        ? this.project.checker.getShorthandAssignmentValueSymbol(identifier.parent)
+        : this.project.checker.getSymbolAtLocation(identifier)
+      if (!local) return false
+      const symbol = local.flags & ts.SymbolFlags.Alias
+        ? this.project.checker.getAliasedSymbol(local)
+        : local
+      return symbol === ownerSymbol
+    }
+    const visit = (node: ts.Node): void => {
+      if (!proven) return
+      if (ts.isIdentifier(node) && node !== name && node.text === name?.text
+        && !isDirectCallee(node) && refersToOwner(node)) {
+        proven = false
+        return
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(owner.getSourceFile())
+    this.localCalleeProofs.set(owner, proven)
+    return proven
   }
 
   /** Walk one package source file and classify event API calls by receiver type. */
@@ -760,7 +843,7 @@ class EventRelationCollector {
               this.addDispatcher(name, source.pkg, 'emitAgentEvent')
             }
           }
-        } else if (ts.isPropertyAccessExpression(node.expression)) {
+        } else if (ts.isPropertyAccessExpression(node.expression) && EVENT_API_METHODS.has(node.expression.name.text)) {
           const receiverKind = this.receiverKind(node.expression.expression)
           const method = node.expression.name.text
           if (receiverKind === 'events-service' && method === 'dispatch') {
@@ -863,7 +946,7 @@ class EventRelationCollector {
     const index = owner.parameters.indexOf(parameter)
     if (index < 0) return new Set()
     const events = new Set<string>()
-    for (const call of this.callSites.get(owner) ?? []) {
+    for (const call of this.callSitesFor(owner)) {
       const argument = call.arguments[index]
       if (argument) addAll(events, this.eventNamesFromArgumentList(argument, new Set(seen)))
     }
@@ -910,6 +993,21 @@ class EventRelationCollector {
   }
 }
 
+/** Return whether an identifier is the callee of a call, seen through value-preserving wrappers. */
+function isDirectCallee(identifier: ts.Identifier): boolean {
+  let current: ts.Node = identifier
+  while (
+    ts.isParenthesizedExpression(current.parent)
+    || ts.isAsExpression(current.parent)
+    || ts.isTypeAssertionExpression(current.parent)
+    || ts.isNonNullExpression(current.parent)
+    || ts.isSatisfiesExpression(current.parent)
+  ) {
+    current = current.parent
+  }
+  return ts.isCallExpression(current.parent) && current.parent.expression === current
+}
+
 /** Peel syntax-only wrappers that do not change an expression's runtime value. */
 function unwrapExpression(expression: ts.Expression): ts.Expression {
   let current = expression
@@ -965,14 +1063,22 @@ function unionSets<T>(left: ReadonlySet<T>, right: ReadonlySet<T>): Set<T> {
   return out
 }
 
-function collectEventRelations(): Map<string, EventRelation> {
-  const project = new TypeScriptProject(root)
-  const sources = project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
+/**
+ * Select the package source files of one project in deterministic order.
+ * @param project - the loaded repository TypeScript project.
+ * @returns `packages/<group>/<pkg>/src` files tagged with their package name.
+ */
+export function collectPackageSources(project: TypeScriptProject): PackageSource[] {
+  return project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
     const rel = project.relativePath(sourceFile)
     const match = /^packages\/[^/]+\/([^/]+)\/src\/.+\.ts$/.exec(rel)
     return match?.[1] ? [{ rel, pkg: match[1], sourceFile }] : []
   }).sort((left, right) => left.rel.localeCompare(right.rel))
-  return new EventRelationCollector(project, sources).collect()
+}
+
+function collectEventRelations(): Map<string, EventRelation> {
+  const project = new TypeScriptProject(root)
+  return new EventRelationCollector(project, collectPackageSources(project)).collect()
 }
 
 function relationPackages(map: Map<string, Set<string>>, pkgsByShort: Map<string, Pkg>): string {
@@ -1053,20 +1159,22 @@ function renderLifecycle(): string {
     '  participant Session',
     '  participant SDK as UI or SDK listener',
     '  User->>Agent: followup(content)',
-    `  Agent-->>SDK: ${mermaidCode('agent/inbox/enqueue')}`,
+    `  Agent-->>SDK: ${mermaidCode('agent/inbox/spliced')}`,
+    `  Agent-->>SDK: ${mermaidCode('agent/inbox/inserted')} { message }`,
     '  Agent->>Driver: queued work wakes driver',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
-    '  Note over Agent,Driver: next-step acceptance window opens',
-    `  Driver->>Hooks: ${mermaidCode('agent/prompt-submit')} waterfall`,
-    '  Hooks-->>Driver: authoritative allow, block, or add context',
-    '  alt prompt blocked or admission failed',
-    '    Driver-->>Driver: append context-only batch or keep steering boundary pending',
-    '  else prompt allowed',
+    '  Note over Agent,Driver: claim pending next-step input plus one queued prompt',
+    `  Driver-->>SDK: ${mermaidCode('agent/inbox/spliced')} pure deletion`,
+    `  Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
+    `  Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
+    '  Hooks-->>Driver: authoritative reject or enter(messages)',
+    '  alt proposed step rejected or pre-step failed',
+    '    Driver-->>Driver: claimed batch stays removed, no turn opens',
+    '  else enter proposed step',
     `  Driver->>Session: ${mermaidCode('turn/start')}`,
-    `  Driver->>Session: ${mermaidCode('user/message')}`,
-    `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
-    `  Driver-->>Driver: ${mermaidCode('agent/step')} serial checkpoint`,
     `  Driver->>Session: ${mermaidCode('step/start')}`,
+    `  Driver->>Session: ${mermaidCode('user/message')} per entered message`,
+    `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
     `  Driver->>LLM: ${mermaidCode('agent/request')} waterfall, then ${mermaidCode('llm/stream')} waterfall`,
     '  LLM-->>Driver: StreamChunk*',
     `  Driver->>Session: ${mermaidCode('assistant/chunk')}*`,
@@ -1089,11 +1197,17 @@ function renderLifecycle(): string {
     `      Driver->>Session: ${mermaidCode('tool/result')}`,
     '    end',
     '  end',
-    '  Driver->>Session: post-tool context and steering (no prompt-submit)',
     `  Driver->>Session: ${mermaidCode('step/end')}`,
-    `  Driver->>Hooks: ${mermaidCode('agent/turn-stopping')} serial terminal checkpoint`,
+    '  opt natural stop and next-step inbox empty',
+    `    Driver->>Hooks: ${mermaidCode('agent/turn-stopping')} serial terminal checkpoint`,
+    '  end',
+    '  opt next-step input is pending',
+    '    Driver-->>Driver: claim pending next-step input',
+    `    Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
+    `    Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
+    '    Hooks-->>Driver: authoritative reject or enter(messages)',
+    '  end',
     '  end',
-    '  Note over Agent,Driver: next-step acceptance window closes',
     `  Driver->>Session: ${mermaidCode('turn/end')}`,
     '  end',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
@@ -1101,9 +1215,9 @@ function renderLifecycle(): string {
     '',
     'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
     '',
-    '`dsh-compact-basic` uses `agent/step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
+    '`dsh-compact-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
     '',
-    'The returned `agent/prompt-submit` allow is authoritative; listeners wrapping `next()` preserve downstream content and additional contexts unless replacement is intentional. Steering bypasses that waterfall and joins at its durable checkpoint.',
+    'The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages unless replacement is intentional. Steering and injected context pass through the same waterfall after a later boundary claims their next-step batch.',
     '',
     'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
     '',
@@ -1192,8 +1306,8 @@ function renderDocs(): GraphDoc[] {
 function renderIndex(docs: GraphDoc[]): string {
   const labels: Record<string, string> = {
     'docs/capability-seams.md': 'capability seams and core services',
+    'apps/cli/composition.md': 'dsh shared base composition',
     'examples/headless-agent/composition.md': 'headless-agent app composition',
-    'examples/tui-agent/composition.md': 'tui-agent app composition',
     'examples/cordis-agent/composition.md': 'cordis-agent app composition',
     'examples/acp-agent/composition.md': 'acp-agent app composition',
     'docs/event-producer-consumer.md': 'event producer/consumer matrix',
@@ -1202,8 +1316,8 @@ function renderIndex(docs: GraphDoc[]): string {
   }
   const modes: Record<string, string> = {
     'docs/capability-seams.md': 'hybrid generated',
+    'apps/cli/composition.md': 'hybrid generated',
     'examples/headless-agent/composition.md': 'hybrid generated',
-    'examples/tui-agent/composition.md': 'hybrid generated',
     'examples/cordis-agent/composition.md': 'hybrid generated',
     'examples/acp-agent/composition.md': 'hybrid generated',
     'docs/event-producer-consumer.md': 'hybrid generated',
diff --git a/vitest.config.ts b/vitest.config.ts
index 996f2456c7..5e6ac400ef 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,5 +1,16 @@
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
 import tsconfigPaths from 'vite-tsconfig-paths'
+import { resolvePwshPath } from './packages/bash/pwsh-local/src/resolve.ts'
 import { defineConfig } from 'vitest/config'
+import { vitestExecArgv } from './vitest.shared.ts'
+import { COVERAGE_EXEMPT_ENV, coverageExemptHeavySuites } from './scripts/coverage-exempt.ts'
+
+// Prints exact `path:line:col` records for every uncovered statement, branch
+// path, and function when a file misses the per-file 100% gate — the built-in
+// threshold ERRORs name only the file. Absolute path because istanbul-reports
+// require()s custom reporters (which is also why the reporter is CJS).
+const uncoveredLocationsReporter = fileURLToPath(new URL('./scripts/coverage-uncovered-locations.cjs', import.meta.url))
 
 // Resolution facade shared by every plugin instance below: tsconfig.base.json
 // has no include, which vite-tsconfig-paths treats as match-all, so its paths
@@ -9,7 +20,14 @@ const pathsPlugin = (): ReturnType<typeof tsconfigPaths> => tsconfigPaths({ proj
 
 const windowsUnsupportedPackages = process.platform === 'win32'
   ? [
-      'packages/bash/*',
+      // Bash-requiring suites (a real POSIX shell is unavailable on Windows).
+      // The pwsh-requiring suites (pwsh-local, tool-pwsh) deliberately stay
+      // INCLUDED: PowerShell ships with Windows, so they run natively here.
+      // Replacing the old 'packages/bash/*' glob with this explicit list also
+      // newly INCLUDES packages/bash/bash (the pure seam package) on Windows.
+      'packages/bash/bash-local',
+      'packages/bash/bash-sandbox',
+      'packages/bash/tool-bash',
       'packages/hooks/*',
       'packages/subprocess/*',
       'packages/pty/pty-local',
@@ -26,10 +44,20 @@ const windowsCoverageExclusions = process.platform === 'win32'
       'packages/lsp/lsp-local/src/connection.ts',
       'packages/lsp/lsp-local/src/index.ts',
       'packages/lsp/lsp-local/src/instance.ts',
-      'packages/ui/tui/src/index.ts',
     ]
   : []
 
+// Mirrors windowsCoverageExclusions: pwsh-local's run/start/lifecycle suites
+// self-skip without a real pwsh (executor.spec.ts hasPwsh), leaving this file
+// far below per-file 100% on pwsh-less hosts; the exemption keeps those hosts
+// green while CI runners ship pwsh and still enforce the full bar. The probe
+// runs the suites' own resolution (the dependency-free resolve.ts module),
+// so the exemption is active exactly when the suites skip — a mismatched
+// narrower probe could exempt the file on hosts whose suites actually run.
+const pwshCoverageExclusions = spawnSync(resolvePwshPath(), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '$true'], { encoding: 'utf8' }).status === 0
+  ? []
+  : ['packages/bash/pwsh-local/src/index.ts']
+
 const testIncludes = [
   'packages/*/*/tests/**/*.spec.{ts,tsx}',
   'apps/*/tests/**/*.spec.ts',
@@ -37,6 +65,17 @@ const testIncludes = [
   'scripts/**/*.spec.ts',
 ]
 
+// The instrumented coverage gate sets this env; the exempt heavy suites then
+// run beside it uninstrumented (membership contract in scripts/coverage-exempt.ts).
+// A set-but-not-'1' value is a misconfiguration, not a silent no-op.
+const coverageExemptRaw = process.env[COVERAGE_EXEMPT_ENV]
+if (coverageExemptRaw !== undefined && coverageExemptRaw !== '' && coverageExemptRaw !== '1') {
+  throw new Error(`vitest config: ${COVERAGE_EXEMPT_ENV} must be '1' or unset, got ${JSON.stringify(coverageExemptRaw)}.`)
+}
+const coverageExemptExcludes = coverageExemptRaw === '1'
+  ? coverageExemptHeavySuites.map(suite => suite.exclude)
+  : []
+
 // These suites exercise process-global state, process APIs, or timing-sensitive process I/O
 // that worker threads cannot isolate reliably under aggregate gate contention.
 // Keep the narrow exception in forks while the rest of the inventory avoids per-file processes.
@@ -55,22 +94,27 @@ export default defineConfig({
     // .tsx: client component specs (jsdom via per-file @vitest-environment pragma).
     include: testIncludes,
     exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
-    // One coverage invocation aggregates both projects. Most suites use threads
-    // for lower startup/IPC overhead; only explicit process-bound suites fork.
+    // One coverage invocation aggregates both projects. Regular suites fork on
+    // POSIX for Node stability and use threads on Windows; process-bound suites
+    // always fork.
     projects: [
       {
         plugins: [pathsPlugin()],
         test: {
           name: 'thread-safe',
-          // Node 24 has aborted in its CJS lexer from a macOS arm64 worker
-          // thread. A fork contains that external runtime failure to the test
-          // process; other hosts retain the lower-overhead thread pool.
-          pool: process.platform === 'darwin' ? 'forks' : 'threads',
+          execArgv: vitestExecArgv,
+          // Node 24 has aborted in its CJS lexer (v8::ToLocalChecked Empty
+          // MaybeLocal in cjs_lexer::Parse) from worker threads on macOS
+          // arm64 and later on Linux. A fork contains that external runtime
+          // failure to the test process; Windows keeps the thread pool, where
+          // the abort has not reproduced and process spawn is costlier.
+          pool: process.platform === 'win32' ? 'threads' : 'forks',
           setupFiles: ['./scripts/test-invariants.ts'],
           include: testIncludes,
           exclude: [
             ...windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
             ...processBoundTests,
+            ...coverageExemptExcludes,
           ],
         },
       },
@@ -78,10 +122,14 @@ export default defineConfig({
         plugins: [pathsPlugin()],
         test: {
           name: 'process-bound',
+          execArgv: vitestExecArgv,
           pool: 'forks',
           setupFiles: ['./scripts/test-invariants.ts'],
           include: processBoundTests,
-          exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
+          exclude: [
+            ...windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`),
+            ...coverageExemptExcludes,
+          ],
         },
       },
     ],
@@ -98,7 +146,8 @@ export default defineConfig({
         'packages/*/*/src/types.ts',
         'packages/*/*/src/bin.ts',
         'packages/*/*/src/worker.ts',
-        'packages/code-runtime/code-runtime-subprocess/src/runner.ts',
+        // A killed executable lint-contract test can leave a non-product source probe behind.
+        'packages/*/*/src/oxlint-contract-*.ts',
         // GUI step-1 skeleton (PR #500): client/web UI files whose remaining
         // branches need a browser-grade harness the jsdom lane doesn't cover
         // yet. TODO(gui): cover and remove as the client test lane matures.
@@ -107,6 +156,7 @@ export default defineConfig({
         'packages/client/ui-primitives/src/markdown/plain-text.ts',
         'packages/client/ui-question/src/client/QuestionComposer.tsx',
         'packages/client/ui-primitives/src/Menu.tsx',
+        'packages/client/ui-primitives/src/RiskConfirmation.tsx',
         'packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx',
         'packages/client/ui-workspace/src/client/WorkspacePicker.tsx',
         'packages/client/web-react/src/*',
@@ -155,9 +205,13 @@ export default defineConfig({
         'packages/client/ui-sidebar/src/client/index.ts',
         'packages/client/ui-skill/src/client/index.ts',
         'packages/client/ui-workspace/src/client/index.ts',
-        'packages/typert/generator/src/analyzer.ts',
-        'packages/typert/generator/src/renderer.ts',
-        'packages/typert/generator/src/cordis-catalog.ts',
+        'packages/client/test-runtime/src/translate.ts',
+        'packages/client/ui-primitives/src/JsonTree.tsx',
+        // Typert generator: correctness is pinned by its fixture suites and
+        // the byte-for-byte catalog reproduction test; per-file coverage
+        // would put whole-workspace compiler analysis under v8
+        // instrumentation — the coverage lane's longest tail.
+        'packages/typert/generator/src/*.ts',
         'packages/host/apiproxy/src/index.ts',
         'packages/host/apiproxy/src/invariant.ts',
         'packages/host/apiproxy/src/api-proxy.ts',
@@ -167,9 +221,9 @@ export default defineConfig({
         'packages/ui/commands/src/index.ts',
         'packages/ui/commands/src/invariant.ts',
         'packages/session-projection/session-projection/src/index.ts',
-        'packages/ui/tui/src/index.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
         ...windowsCoverageExclusions,
+        ...pwshCoverageExclusions,
       ],
       // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome).
       // Per-file so a well-covered big file can't subsidize a bare one.
@@ -182,7 +236,9 @@ export default defineConfig({
         functions: 100,
         lines: 100,
       },
-      reporter: process.env.CI ? ['text'] : ['text', 'html'],
+      reporter: process.env.CI
+        ? ['text', uncoveredLocationsReporter]
+        : ['text', 'html', uncoveredLocationsReporter],
     },
   },
 })

From d0701296223994d82323b7c249aa20ce9a325b35 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:09:51 +0800
Subject: [PATCH 347/516] fix(constraints): follow the spawn-helper relocation
 to subprocess-local

The workspace-constraints allowlist pinned scripts/ensure-spawn-helper.mjs
to dsh-pty-local; this branch relocates the helper (with node-pty
ownership) into dsh-subprocess-local, so the published-files expectation
moves with it.
---
 scripts/check-workspace-constraints.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 355b817e68..1c7bedc696 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -125,8 +125,8 @@ const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
   '@deepseek-ai/dsh-headless': ['cordis.patch.yml'],
   '@deepseek-ai/dsh-client-ui-theme': ['lib/styles'],
   '@deepseek-ai/dsh-helper': ['lib/assets'],
-  '@deepseek-ai/dsh-pty-local': ['scripts/ensure-spawn-helper.mjs'],
   '@deepseek-ai/dsh-skill-badge': ['assets'],
+  '@deepseek-ai/dsh-subprocess-local': ['scripts/ensure-spawn-helper.mjs'],
   '@deepseek-ai/dsh-scripts': [
     'lib/dev/tsdown-config.js',
     'lib/local-plugin-loader-hooks.js',

From fbceb8dcd55535e84f5b2ced570cbc613a00891a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 23:40:45 +0800
Subject: [PATCH 348/516] fix(pty-local): restore the session-resolved
 workspace policy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The linear replay resurrected the July spawn path: mode folded inline
and both confinement and the default cwd fenced to the deployment
workspaceRoot. Master (and the pre-rebase merge result) resolve the
policy once per spawn — resolve({ session }) — so session.header.cwd
is both the workspace-write boundary and the default shell cwd, as the
README already states. Restores the single resolve, threads the policy
through spawnArgv and the cwd fallback, re-expresses master's
session-root test on the terminal spec, and pins the recorded confine
policy in the explicit-cwd test.

Also from the same review round: the Python SDK exe build stages
pty.node from subprocess-local (node-pty's home since the relocation),
and fs-local's README counts the seam's eleven primitives.
---
 packages/fs/fs-local/README.i18n.yaml      |  4 +--
 packages/fs/fs-local/README.md             |  2 +-
 packages/fs/fs-local/README.zh.md          |  2 +-
 packages/pty/pty-local/src/index.ts        | 20 +++++------
 packages/pty/pty-local/tests/index.spec.ts | 40 ++++++++++++++++++++--
 scripts/build-exe-for-python-sdk.ts        |  2 +-
 6 files changed, 52 insertions(+), 18 deletions(-)

diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index e1870cbf41..250b94dacf 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-local/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/fs/fs-local/README.md
-README.md: fe0e5e9dec07fad745d6bea28da9009e517c7d85
-README.zh.md: 195f3963328035e9c6c382dd924cd04ee9e8c642
+README.md: 2e934298ceff75440357b0742770010c8b1c3904
+README.zh.md: 14f4867ce0f9eaae2a1dea98dbd7d401c98d4535
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index fe0e5e9dec..2e934298ce 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the twelve `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eleven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 195f396332..14f4867ce0 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十二个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
+`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十一个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts
index b1e0e6edbd..fa2237c959 100644
--- a/packages/pty/pty-local/src/index.ts
+++ b/packages/pty/pty-local/src/index.ts
@@ -10,7 +10,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { PtyBackendCleanupError } from '@deepseek-ai/dsh-pty'
 import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
 import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
-import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox'
 import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
 import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
 import { LocalPtySession } from './session.ts'
@@ -68,18 +68,15 @@ function childEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
   }
 }
 
-function spawnArgv(ctx: Context, config: ResolvedConfig, spec: PtyBackendSpawnSpec): string[] {
+function spawnArgv(ctx: Context, config: ResolvedConfig, policy: SandboxExecutionPolicy): string[] {
   const argv = [config.shellPath, ...config.shellArgs]
-  const mode: SandboxMode = effectiveSandboxMode(spec.owner.session.events) ?? ctx.sandboxPolicy.defaultMode
-  if (mode === 'danger-full-access') return argv
+  if (policy.mode === 'danger-full-access') return argv
   const sandbox = ctx.get('sandbox')
   if (sandbox === undefined) {
-    throw new Error(`pty-local: sandbox mode "${mode}" requires a ctx.sandbox provider in the execution world`)
+    throw new Error(`pty-local: sandbox mode "${policy.mode}" requires a ctx.sandbox provider in the execution world`)
   }
-  return sandbox.confine(argv, {
-    mode: mode,
-    workspaceRoot: ctx.sandboxPolicy.workspaceRoot,
-  }).argv
+  // Re-state the discriminant because object spread does not preserve its narrowed type.
+  return sandbox.confine(argv, { ...policy, mode: policy.mode }).argv
 }
 
 // TODO(pty-initialize-race-home): Fold this outer abort race into
@@ -122,11 +119,12 @@ export class LocalPtyBackend implements PtyBackend {
   async spawn(spec: PtyBackendSpawnSpec): Promise<LocalPtySession> {
     spec.signal?.throwIfAborted()
     ensureSandboxModeFence(this.ctx, spec.owner)
-    const argv = spawnArgv(this.ctx, this.config, spec)
+    const policy = this.ctx.sandboxPolicy.resolve({ session: spec.owner.session })
+    const argv = spawnArgv(this.ctx, this.config, policy)
     if (argv[0] === undefined) throw new Error('pty-local: sandbox returned empty argv')
     const terminal = await this.spawnTerminal({
       argv,
-      cwd: spec.cwd ?? this.ctx.sandboxPolicy.workspaceRoot,
+      cwd: spec.cwd ?? policy.workspaceRoot,
       env: childEnvironment(spec),
       rows: this.config.rows,
       cols: this.config.cols,
diff --git a/packages/pty/pty-local/tests/index.spec.ts b/packages/pty/pty-local/tests/index.spec.ts
index 9f10a2cde8..d61eb58da5 100644
--- a/packages/pty/pty-local/tests/index.spec.ts
+++ b/packages/pty/pty-local/tests/index.spec.ts
@@ -44,9 +44,9 @@ function config(): ResolvedConfig {
   }
 }
 
-function agent(ctx: Context): Agent {
+function agent(ctx: Context, cwd?: string): Agent {
   const id = SessionId('agent')
-  const session = Session.create(id, undefined, { version: 0, id, createdAt: 0 })
+  const session = Session.create(id, undefined, { version: 0, id, createdAt: 0, ...cwd === undefined ? {} : { cwd } })
   return {
     id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
     status: 'idle',
@@ -213,6 +213,42 @@ describe('LocalPtyBackend startup rollback', () => {
     })
     expect(spawned?.env?.PTY_TEST_SECRET).toBeUndefined()
     expect(initialized).toHaveBeenCalledWith(undefined)
+    expect((ctx.sandbox as RecordingSandbox).calls).toEqual([{
+      argv: ['/bin/bash', '-i'],
+      policy: { mode: 'workspace-write', workspaceRoot: '/workspace' },
+    }])
+  })
+
+  it('resolves session mode and root together before wrapping the shell', async () => {
+    const ctx = new Context()
+    await ctx.plugin(RecordingSandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/deployment-fallback' })
+    const terminal = terminalHandle()
+    let spawned: SubprocessTerminalSpawnSpec | undefined
+    const spawnTerminal = async (spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> => {
+      spawned = spec
+      return terminal
+    }
+    const initialized = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
+    const session = { initialize: initialized } as unknown as LocalPtySession
+    const backend = new LocalPtyBackend(
+      ctx,
+      { ...config(), shellArgs: ['-i'] },
+      spawnTerminal,
+      () => session,
+    )
+    const owner = agent(ctx, '/session-workspace')
+    setSandboxMode(owner.session, 'workspace-write')
+    expect(await backend.spawn(spec(owner))).toBe(session)
+
+    expect(spawned).toMatchObject({
+      argv: ['/sandbox', '--', '/bin/bash', '-i'],
+      cwd: '/session-workspace',
+    })
+    expect((ctx.sandbox as RecordingSandbox).calls).toEqual([{
+      argv: ['/bin/bash', '-i'],
+      policy: { mode: 'workspace-write', workspaceRoot: '/session-workspace' },
+    }])
   })
 
   it('rejects a confined spawn without a sandbox provider', async () => {
diff --git a/scripts/build-exe-for-python-sdk.ts b/scripts/build-exe-for-python-sdk.ts
index db72f4c52e..536342dc89 100644
--- a/scripts/build-exe-for-python-sdk.ts
+++ b/scripts/build-exe-for-python-sdk.ts
@@ -326,7 +326,7 @@ class SingleExeBuild {
     if (this.cli.dryRun) console.log(`build-exe-for-python-sdk: [dry-run] rm -rf ${stagedBuild}`)
     else await rm(stagedBuild, { recursive: true, force: true })
     if (target.platform !== 'linux') return
-    const source = join(root, 'packages', 'pty', 'pty-local', 'node_modules', 'node-pty', 'build', 'Release', 'pty.node')
+    const source = join(root, 'packages', 'subprocess', 'subprocess-local', 'node_modules', 'node-pty', 'build', 'Release', 'pty.node')
     const destination = join(stagedBuild, 'Release', 'pty.node')
     if (this.cli.dryRun) {
       console.log(`build-exe-for-python-sdk: [dry-run] cp ${source} ${destination}`)

From d47df8ff9dc9d2eaabac8ae09449e325212c5bbf Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 00:10:29 +0800
Subject: [PATCH 349/516] chore(rebase): refresh generated docs after the
 round-two replay

Restores master's vitest config and packages-README pairing record (the
replay had carried old-lineage copies; this branch claims neither), and
regenerates the doc graphs, catalogs, and architecture pairing the
replay's ours-side resolutions had flattened to master's content.
---
 docs/architecture.i18n.yaml     |  4 ++--
 docs/capability-seams.md        | 11 +++++------
 docs/event-producer-consumer.md |  8 ++++----
 docs/module-graph.md            | 15 ++++++++-------
 packages/README.i18n.yaml       |  4 ++--
 vitest.config.ts                | 12 ++++++++----
 6 files changed, 29 insertions(+), 25 deletions(-)

diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index de15631197..e0ddc02423 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: ea78faa62773a6b8ac98e5baab6e181ad6a3b7f0
-architecture.zh.md: 5a46dfaf84276de5f4dc0352a529bdd4e5d8c267
+architecture.md: e88bdac118e382d91c41c471d03182952d8a4508
+architecture.zh.md: 9314a3fbfc87d467a0f902fa1dae9e8f07e2eb28
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index ae90e4a9bf..50ebe88d4f 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -21,7 +21,6 @@ flowchart LR
   pkg_session["session"]
   svc_sessions["ctx.sessions<br/>In-memory session store"]
   pkg_agent["agent"]
-  pkg_cli_demo["cli-demo"]
   pkg_session_persistence["session-persistence"]
   pkg_session_query["session-query"]
   pkg_session_query_sqlite["session-query-sqlite"]
@@ -91,6 +90,7 @@ flowchart LR
   svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"]
   pkg_skill["skill"]
   svc_skills["ctx.skills<br/>Skill provider registry"]
+  pkg_skill_badge["skill-badge"]
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
@@ -225,6 +225,7 @@ flowchart LR
   pkg_settings --> svc_settings
   pkg_settings_local --> svc_settings
   pkg_skill --> svc_skills
+  pkg_skill_badge --> svc_skills
   pkg_skill_local --> svc_skills
   pkg_spill --> svc_spillStore
   pkg_spill_local --> svc_spillStore
@@ -260,7 +261,6 @@ flowchart LR
   svc_agentLoop --> pkg_agent_spine_demo
   svc_agents --> pkg_acp
   svc_agents --> pkg_agent_loop
-  svc_agents --> pkg_cli_demo
   svc_agents --> pkg_subagent_inprocess
   svc_approval --> pkg_tool_bash
   svc_approval --> pkg_tools
@@ -307,7 +307,6 @@ flowchart LR
   svc_sessionQuery --> pkg_tool_session_query
   svc_sessions --> pkg_agent
   svc_sessions --> pkg_agent_loop
-  svc_sessions --> pkg_cli_demo
   svc_sessions --> pkg_invariants
   svc_sessions --> pkg_session_persistence
   svc_sessions --> pkg_session_query
@@ -366,7 +365,7 @@ flowchart LR
 | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compact-basic`](../packages/compact/compact-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. |
 | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements. |
 | `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
-| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
 | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
 | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
@@ -387,8 +386,8 @@ flowchart LR
 | `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
-| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
-| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
 | `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index acd2bc5e91..9699870ecc 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -24,9 +24,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:172`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
-| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:62`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
-| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
-| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:64`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:73`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
+| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:56`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
@@ -65,7 +65,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-permission`, `ui-settings-general` |
 | `credentials/changed` | `runtime` (`emit`) | `ui-models` |
 | `internal/dispatch` | - | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
-| `internal/plugin` | - | `hmr`, `loader`, `modules`, `webserver` |
+| `internal/plugin` | - | `hmr`, `loader`, [`lsp-local`](../packages/lsp/lsp-local), `modules`, `webserver` |
 | `internal/service` | - | `gateway` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
 | `locale/change` | `locale` (`emit`) | `locale` |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 22af77f9c5..38a85a508a 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -491,12 +491,6 @@ flowchart TD
   pkg_code_runtime_worker --> pkg_invariants
   pkg_code_runtime_worker --> pkg_session
   pkg_code_runtime_worker --> pkg_timeout
-  pkg_lsp_local --> pkg_brand
-  pkg_lsp_local --> pkg_invariants
-  pkg_lsp_local --> pkg_llm
-  pkg_lsp_local --> pkg_lsp
-  pkg_lsp_local --> pkg_subprocess
-  pkg_lsp_local --> pkg_timeout
   pkg_sandbox_local --> pkg_invariants
   pkg_sandbox_local --> pkg_llm
   pkg_sandbox_local --> pkg_sandbox
@@ -607,6 +601,13 @@ flowchart TD
   pkg_host_directory_picker_native --> pkg_client_ui_slots
   pkg_host_directory_picker_native --> pkg_client_ui_workspace
   pkg_host_directory_picker_native --> pkg_invariants
+  pkg_lsp_local --> pkg_brand
+  pkg_lsp_local --> pkg_fs
+  pkg_lsp_local --> pkg_invariants
+  pkg_lsp_local --> pkg_llm
+  pkg_lsp_local --> pkg_lsp
+  pkg_lsp_local --> pkg_subprocess
+  pkg_lsp_local --> pkg_timeout
   pkg_pty --> pkg_agent
   pkg_pty --> pkg_brand
   pkg_pty --> pkg_invariants
@@ -1238,7 +1239,6 @@ flowchart TD
 | [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`session-projection`](../packages/session-projection/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
@@ -1266,6 +1266,7 @@ flowchart TD
 | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants) |
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index d10f476f79..8aa9b92b91 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 8fbb6069a784a5bd45423a4e1ae11834a597750d
-README.zh.md: 42a8d691344c716021188df6fd870a841d543f36
+README.md: 229feae568ba6e40a9c633696097eff46fd5bc95
+README.zh.md: b84aef020a7e3edf305df709d399fbc7b093b6a3
diff --git a/vitest.config.ts b/vitest.config.ts
index 5e6ac400ef..6eb1bda354 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import tsconfigPaths from 'vite-tsconfig-paths'
 import { resolvePwshPath } from './packages/bash/pwsh-local/src/resolve.ts'
 import { defineConfig } from 'vitest/config'
-import { vitestExecArgv } from './vitest.shared.ts'
+import { standardDecoratorPlugin, vitestExecArgv } from './vitest.shared.ts'
 import { COVERAGE_EXEMPT_ENV, coverageExemptHeavySuites } from './scripts/coverage-exempt.ts'
 
 // Prints exact `path:line:col` records for every uncovered statement, branch
@@ -88,7 +88,7 @@ const processBoundTests = [
 ]
 
 export default defineConfig({
-  plugins: [pathsPlugin()],
+  plugins: [pathsPlugin(), standardDecoratorPlugin()],
   test: {
     setupFiles: ['./scripts/test-invariants.ts'],
     // .tsx: client component specs (jsdom via per-file @vitest-environment pragma).
@@ -99,7 +99,7 @@ export default defineConfig({
     // always fork.
     projects: [
       {
-        plugins: [pathsPlugin()],
+        plugins: [pathsPlugin(), standardDecoratorPlugin()],
         test: {
           name: 'thread-safe',
           execArgv: vitestExecArgv,
@@ -119,7 +119,7 @@ export default defineConfig({
         },
       },
       {
-        plugins: [pathsPlugin()],
+        plugins: [pathsPlugin(), standardDecoratorPlugin()],
         test: {
           name: 'process-bound',
           execArgv: vitestExecArgv,
@@ -181,6 +181,10 @@ export default defineConfig({
         'packages/client/hmr/src/invariant.ts',
         'packages/client/connection/src/index.ts',
         'packages/client/connection/src/http-bridge.ts',
+        // This assembly imports generated Host-for-Client code that exists
+        // only in lib; the post-build built-bin smoke executes both entries.
+        'packages/api/remotes/src/index.ts',
+        'packages/api/remotes/src/client/index.ts',
         // Slash/command/input round: per-file gaps deferred with the same
         // client-lane debt. TODO(gui): cover and remove with the lane above.
         'packages/client/connection/src/client/fixture.ts',

From 9a4b70cf3be777a913cd79fc4aeeeadc8e71d3b8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:49:23 +0800
Subject: [PATCH 350/516] fix(i18n): harden stopped-merge recovery

---
 ...matic-translation-pairing-merges.i18n.yaml |   4 +-
 ...08-automatic-translation-pairing-merges.md |   6 +-
 ...automatic-translation-pairing-merges.zh.md |   6 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +-
 docs/development.zh.md                        |   2 +-
 docs/i18n/README.i18n.yaml                    |   4 +-
 docs/i18n/README.md                           |   2 +-
 docs/i18n/README.zh.md                        |   2 +-
 scripts/merge-translation-pairing.ts          |   5 +
 .../request-response.expected.json            |   8 +-
 scripts/translation-pairing-git.ts            |  17 ++-
 scripts/translation-pairing-merge.spec.ts     | 103 ++++++++++++++
 scripts/translation-pairing-merge.ts          | 131 +++++++++++++-----
 14 files changed, 237 insertions(+), 59 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
index bbd7870d69..7631476fb8 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.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 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
-2026-08-08-automatic-translation-pairing-merges.md: a1b92c97240e2019b188b606dc079b2211a89238
-2026-08-08-automatic-translation-pairing-merges.zh.md: 5c7249dc436d24aa955d9c042c8d1bdc84655868
+2026-08-08-automatic-translation-pairing-merges.md: e70864f1227fe11d7895dd85b0a99d166753a685
+2026-08-08-automatic-translation-pairing-merges.zh.md: 08da67d78e5cca23e3c5c698644c667813697812
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
index a1b92c9724..e70864f122 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
@@ -14,15 +14,15 @@ A bilingual consistency record contains the two owner files' exact blob hashes.
 
 The driver parses the ancestor, current, and other records and loads the six owner blobs named by their hashes. It independently runs Git's default three-way text merge for the English and Chinese triplets, requires both merges to be clean, verifies language switchers and the pairing structural signature, stores the two merged blobs, and writes their hashes as the canonical record. This composes confirmations already present in both parents; it never records an ordinary one-sided documentation edit.
 
-The driver fails with an ordinary unresolved sidecar when a record is malformed, an object is missing, an owner uses another merge strategy, either owner has content conflicts, or the merged pair violates structural checks. Add/delete and rename shapes remain manual because their path ownership is not the same three-record operation.
+The driver fails with an ordinary unresolved sidecar when a record is malformed, an object is missing, an owner uses another merge strategy (including a non-text `merge.default` inherited by an otherwise unspecified path), either owner has content conflicts, or the merged pair violates structural checks. Add/delete and rename shapes remain manual because their path ownership is not the same three-record operation.
 
-`pnpm run resolve-translation-pairing-conflicts` applies the same algorithm after a merge has already stopped. Before writing any sidecar, it proves that the staged owner blob IDs and working-tree bytes equal its independent merges; then it writes and stages every safe record as one batch while leaving unrelated conflicts untouched.
+`pnpm run resolve-translation-pairing-conflicts` applies the same algorithm after a merge has already stopped. Before writing any sidecar, it proves that the sidecar still contains Git's untouched conflict result and that the staged owner blob IDs and working-tree bytes equal its independent merges. It writes and stages every safe record as one batch even when another pair still needs manual work, then reports the remaining pairing conflicts and exits unsuccessfully so callers cannot mistake a partial resolution for a completed merge.
 
 `pre-merge-commit` and `pre-commit` verify staged `.i18n.yaml` files against the exact index bytes of their owners. They validate driver output but do not regenerate records, so bypassing a hook cannot silently bless translation drift; the corpus-wide `doc-sync` check remains authoritative in CI.
 
 ## Verification
 
-Script tests exercise clean composition through a real custom-driver Git merge, explicit recovery from an unresolved index, owner-content conflicts, record parsing, and worktree-local installation. The existing corpus verifier continues to prove that a committed record matches its two owners.
+Script tests exercise clean composition through a real custom-driver Git merge, explicit recovery from an unresolved index, mixed safe and owner-conflicted pairs, edited sidecars, non-text default merge configuration, record parsing, and worktree-local installation. The existing corpus verifier continues to prove that a committed record matches its two owners.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
index 5c7249dc43..08da67d78e 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
@@ -14,15 +14,15 @@ Status: implemented
 
 驱动会解析祖先、当前和另一侧的记录，并加载其中 hash 指向的六个 Markdown blob。它分别对英文文档的三个 blob 与中文文档的三个 blob 运行 Git 默认的三方文本合并，要求两次合并都干净完成，校验语言切换行与配对结构签名，存储两个合并后的 blob，再将其 hash 写入规范记录。这一过程组合两个父提交中已经存在的确认；它绝不会为普通的单侧文档编辑写入记录。
 
-记录格式错误、对象缺失、配对文档采用其他合并策略、任一配对文档存在内容冲突，或合并后的配对违反结构检查时，驱动会让伴随文件保持为普通的未解决冲突。新增、删除及重命名情形仍需手工处理，因为它们的路径归属关系无法由上述基于三份记录的操作处理。
+记录格式错误、对象缺失、配对文档采用其他合并策略（包括原本未单独指定策略的路径继承了非文本 `merge.default`）、任一配对文档存在内容冲突，或合并后的配对违反结构检查时，驱动会让伴随文件保持为普通的未解决冲突。新增、删除及重命名情形仍需手工处理，因为它们的路径归属关系无法由上述基于三份记录的操作处理。
 
-`pnpm run resolve-translation-pairing-conflicts` 会在合并已经停止后应用同一算法。写入任何伴随文件之前，它会先验证暂存区中配对文档的 blob ID 以及工作树中的文件字节，都与工具独立完成的合并结果一致；随后它会将所有可安全生成的记录作为一个批次写入并暂存，同时不改动无关冲突。
+`pnpm run resolve-translation-pairing-conflicts` 会在合并已经停止后应用同一算法。写入任何伴随文件之前，它会验证伴随文件仍保留 Git 生成且未经改动的冲突结果，并验证暂存区中配对文档的 blob ID 以及工作树中的文件字节都与工具独立完成的合并结果一致。即使其他配对仍需手工处理，它也会将所有可安全生成的记录作为一个批次写入并暂存；随后报告剩余的配对冲突并以非零状态退出，确保调用方不会把仅部分解决误认为合并已经完成。
 
 `pre-merge-commit` 与 `pre-commit` 通过限定范围的配对检查，对照两侧文档在索引中的精确字节校验暂存的 `.i18n.yaml` 文件。这些钩子会验证驱动输出，但不会重新生成记录，因此绕过钩子也无法默默确认发生漂移的译文；CI 中全语料的 `doc-sync`（文档同步门禁）仍是权威检查。
 
 ## 验证
 
-脚本测试通过一次使用真实自定义驱动的 Git 合并来覆盖无冲突组合，并覆盖从含未解决条目的索引中显式恢复、配对文档内容冲突、记录解析和 worktree 本地安装。既有的全语料校验器继续证明已提交的记录与两侧配对文档相符。
+脚本测试通过一次使用真实自定义驱动的 Git 合并来覆盖无冲突组合，并覆盖从含未解决条目的索引中显式恢复、可安全解决的配对与配对文档冲突的配对并存、被编辑过的伴随文件、非文本默认合并配置、记录解析和 worktree 本地安装。既有的全语料校验器继续证明已提交的记录与两侧配对文档相符。
 
 ## 考虑过的替代方案
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 3c57bb057c..6397e9d97e 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: 1b0a412cd55224740a074a88734bc5663a14effc
-development.zh.md: 3c01f680dd8107fe6b3369415a979cea69cd19a0
+development.md: ad0447a0e121eaa31fb6e98502c6a55a9456d768
+development.zh.md: aef8b25d2115d00d5cfdb76b342a57662030feee
diff --git a/docs/development.md b/docs/development.md
index 1b0a412cd5..ad0447a0e1 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -100,7 +100,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 ### Git integrations
 
-The pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files merge cleanly. It fails closed on owner conflicts or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.
+The pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.
 
 lefthook is configured in `lefthook.yml` as a fast local checkpoint:
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 3c01f680dd..aef8b25d21 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -100,7 +100,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 ### Git 集成
 
-当两种语言的文件都能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
+当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
 
 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index 48d27cbb41..c62de565e7 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/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 docs/i18n/README.md
-README.md: 2f9d7d1112492545e4e82d8d99c3d11df383e42d
-README.zh.md: 65ac3552aa4b66cbd43e6b55b98f0e1d9491feea
+README.md: 30f56eeebf15a3edec559e3080247dab9ab14178
+README.zh.md: 91d5b35a00994beea70f2bbd674cfb557d6f834d
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index 2f9d7d1112..30f56eeebf 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -17,7 +17,7 @@ This repo's documentation is read by people and agents both inside and outside t
 
   Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).
 
-  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.
+  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.
 - **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.
 - **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
 
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index 65ac3552aa..91d5b35a00 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -17,7 +17,7 @@
 
   用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。
 
-  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。
+  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。
 - **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
 - **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
 
diff --git a/scripts/merge-translation-pairing.ts b/scripts/merge-translation-pairing.ts
index 8d193ab9f9..30313d045a 100644
--- a/scripts/merge-translation-pairing.ts
+++ b/scripts/merge-translation-pairing.ts
@@ -38,5 +38,10 @@ try {
   }
 } catch (error) {
   console.error(`merge-translation-pairing: ${error instanceof Error ? error.message : String(error)}`)
+  console.error(
+    'merge-translation-pairing: resolve owner conflicts, then confirm the pair with '
+    + '`pnpm run verify-translation-pairing --write <pair>`; rerun '
+    + '`pnpm run resolve-translation-pairing-conflicts` for other safe records',
+  )
   process.exitCode = 1
 }
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index b45ffe01e0..311b0ecc80 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,19 +16,19 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files merge cleanly. It fails closed on owner conflicts or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
-        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
+        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
       },
       {
         "role": "user",
diff --git a/scripts/translation-pairing-git.ts b/scripts/translation-pairing-git.ts
index b18b2d5778..cda27426c6 100644
--- a/scripts/translation-pairing-git.ts
+++ b/scripts/translation-pairing-git.ts
@@ -5,6 +5,9 @@ import { createHash } from 'node:crypto'
 
 const SNAPSHOT_REF_PREFIX = 'refs/dsh/translation-pairing/snapshots'
 
+/** Maximum buffered stdout or stderr for repository-owned Git subprocesses. */
+export const GIT_COMMAND_MAX_BUFFER = 1 << 26
+
 /** Full SHA-1 Git blob hash (the 40-hex format used by pairing records). */
 export function gitBlobHash(content: Buffer): string {
   const hash = createHash('sha1')
@@ -13,10 +16,20 @@ export function gitBlobHash(content: Buffer): string {
   return hash.digest('hex')
 }
 
-function runGit(root: string, args: string[], operation: string, input?: Buffer): Buffer {
+/**
+ * Run one Git subprocess and return its exact stdout bytes.
+ *
+ * @param root - Repository root used as Git's working directory.
+ * @param args - Arguments following the `git` executable.
+ * @param operation - Human-readable operation for failure diagnostics.
+ * @param input - Optional stdin bytes.
+ * @returns Exact stdout bytes.
+ * @throws Error when Git cannot start or exits unsuccessfully.
+ */
+export function runGit(root: string, args: string[], operation: string, input?: Buffer): Buffer {
   const result = spawnSync('git', ['-C', root, ...args], {
     input,
-    maxBuffer: 1 << 26,
+    maxBuffer: GIT_COMMAND_MAX_BUFFER,
   })
   if (result.error) {
     throw new Error(`${operation} failed: ${result.error.message}`, { cause: result.error })
diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
index bd6d2a632b..6ddce4b30b 100644
--- a/scripts/translation-pairing-merge.spec.ts
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -85,6 +85,12 @@ const otherSource = baseSource.replace('Beta base.', 'Beta other.')
 const otherZh = baseZh.replace('乙基础。', '乙对侧。')
 const mergedSource = currentSource.replace('Beta base.', 'Beta other.')
 const mergedZh = currentZh.replace('乙基础。', '乙对侧。')
+const manualBaseSource = baseSource.replace('guide.zh.md', 'manual.zh.md')
+const manualBaseZh = baseZh.replace('guide.md', 'manual.md')
+const manualCurrentSource = manualBaseSource.replace('Alpha base.', 'Alpha current.')
+const manualCurrentZh = manualBaseZh.replace('甲基础。', '甲当前。')
+const manualOtherSource = manualBaseSource.replace('Alpha base.', 'Alpha other.')
+const manualOtherZh = manualBaseZh.replace('甲基础。', '甲对侧。')
 
 function commitPair(fixture: Fixture, source: string, zh: string, message: string): string {
   const sidecar = record(fixture.root, 'docs/guide.md', source, zh)
@@ -113,6 +119,47 @@ function startStoppedPairingMerge(fixture: Fixture): void {
   expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
 }
 
+function commitMixedPairs(
+  fixture: Fixture,
+  guide: { source: string; zh: string },
+  manual: { source: string; zh: string },
+  message: string,
+): void {
+  record(fixture.root, 'docs/guide.md', guide.source, guide.zh)
+  record(fixture.root, 'docs/manual.md', manual.source, manual.zh)
+  git(fixture, ['add', '.'])
+  git(fixture, ['commit', '-m', message])
+}
+
+function startMixedPairingMerge(fixture: Fixture): void {
+  commitMixedPairs(
+    fixture,
+    { source: baseSource, zh: baseZh },
+    { source: manualBaseSource, zh: manualBaseZh },
+    'base',
+  )
+  git(fixture, ['switch', '-c', 'current'])
+  commitMixedPairs(
+    fixture,
+    { source: currentSource, zh: currentZh },
+    { source: manualCurrentSource, zh: manualCurrentZh },
+    'current',
+  )
+  git(fixture, ['switch', 'master'])
+  commitMixedPairs(
+    fixture,
+    { source: otherSource, zh: otherZh },
+    { source: manualOtherSource, zh: manualOtherZh },
+    'other',
+  )
+  git(fixture, ['switch', 'current'])
+  const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+    encoding: 'utf8',
+    env: fixture.env,
+  })
+  expect(merge.status).toBe(1)
+}
+
 function expectMergedPair(fixture: Fixture): void {
   expect(readFileSync(join(fixture.root, 'docs/guide.md'), 'utf8')).toBe(mergedSource)
   expect(readFileSync(join(fixture.root, 'docs/guide.zh.md'), 'utf8')).toBe(mergedZh)
@@ -139,6 +186,7 @@ describe('translation pairing merge composition', () => {
 
   it('merges the owner blobs named by three valid records', () => {
     const fixture = createFixture(false)
+    git(fixture, ['config', 'merge.default', 'text'])
     const records = createDivergedPair(fixture)
 
     const result = mergeTranslationPairingRecords(
@@ -214,6 +262,20 @@ describe('translation pairing merge composition', () => {
     )).toThrow('docs/guide.md uses merge=custom-owner')
   })
 
+  it('refuses unspecified owners affected by merge.default', () => {
+    const fixture = createFixture(false)
+    git(fixture, ['config', 'merge.default', 'custom-owner'])
+    const records = createDivergedPair(fixture)
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      records.ancestor,
+      records.current,
+      records.other,
+    )).toThrow('merge.default=custom-owner')
+  })
+
   it('runs as Git\'s custom driver and commits a clean composed record', () => {
     const fixture = createFixture()
     createDivergedPair(fixture)
@@ -231,6 +293,19 @@ describe('translation pairing merge composition', () => {
     expectMergedPair(fixture)
   })
 
+  it('prints the recovery path when driver input is not composable', () => {
+    const fixture = createFixture(false)
+    const result = spawnSync(process.execPath, ['--import', tsxLoader, driver], {
+      cwd: fixture.root,
+      encoding: 'utf8',
+      env: fixture.env,
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('pnpm run verify-translation-pairing --write <pair>')
+    expect(result.stderr).toContain('pnpm run resolve-translation-pairing-conflicts')
+  })
+
   it('resolves an already-stopped generated-only conflict from index stages', () => {
     const fixture = createFixture(false)
     startStoppedPairingMerge(fixture)
@@ -251,4 +326,32 @@ describe('translation pairing merge composition', () => {
     )
     expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
   })
+
+  it('refuses to overwrite an edited sidecar after a stopped merge', () => {
+    const fixture = createFixture(false)
+    startStoppedPairingMerge(fixture)
+    write(fixture.root, 'docs/guide.i18n.yaml', 'manually resolved\n')
+
+    expect(() => resolveTranslationPairingConflicts(fixture.root)).toThrow(
+      'docs/guide.i18n.yaml has edited conflict content',
+    )
+    expect(readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')).toBe('manually resolved\n')
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+  })
+
+  it('resolves safe records while leaving an owner-conflicted pair untouched', () => {
+    const fixture = createFixture(false)
+    startMixedPairingMerge(fixture)
+
+    expect(() => resolveTranslationPairingConflicts(fixture.root)).toThrow(
+      'docs/manual.i18n.yaml: docs/manual.md has content conflicts',
+    )
+
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U']).split('\n')).toEqual([
+      'docs/manual.i18n.yaml',
+      'docs/manual.md',
+      'docs/manual.zh.md',
+    ])
+    expectMergedPair(fixture)
+  })
 })
diff --git a/scripts/translation-pairing-merge.ts b/scripts/translation-pairing-merge.ts
index 3297e30ea2..58b1be3fee 100644
--- a/scripts/translation-pairing-merge.ts
+++ b/scripts/translation-pairing-merge.ts
@@ -4,7 +4,13 @@ import { spawnSync } from 'node:child_process'
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path'
-import { gitBlobHash, readGitIndexBlob, storeGitBlob } from './translation-pairing-git.ts'
+import {
+  GIT_COMMAND_MAX_BUFFER,
+  gitBlobHash,
+  readGitIndexBlob,
+  runGit,
+  storeGitBlob,
+} from './translation-pairing-git.ts'
 import {
   linksTo,
   isTranslationScopeFile,
@@ -20,7 +26,6 @@ import {
   type TranslationPairingRecord,
 } from './translation-pairing-record.ts'
 
-const MAX_GIT_OUTPUT = 1 << 26
 const UNMERGED_ENTRY = /^(\d+) ([0-9a-f]+) ([123])\t([\s\S]+)$/
 
 /** A mechanically composed record and the exact merged owner contents it names. */
@@ -39,18 +44,6 @@ interface UnmergedStages {
   other?: string
 }
 
-function runGit(root: string, args: string[], operation: string, input?: Buffer): Buffer {
-  const result = spawnSync('git', ['-C', root, ...args], {
-    input,
-    maxBuffer: MAX_GIT_OUTPUT,
-  })
-  if (result.error) throw new Error(`${operation} failed: ${result.error.message}`, { cause: result.error })
-  if (result.status !== 0) {
-    throw new Error(`${operation} failed with status ${String(result.status)}: ${result.stderr.toString('utf8').trim()}`)
-  }
-  return result.stdout
-}
-
 function readGitBlob(root: string, objectId: string, owner: string): Buffer {
   const content = runGit(root, ['cat-file', 'blob', objectId], `reading ${owner} blob ${objectId}`)
   if (gitBlobHash(content) !== objectId) {
@@ -59,6 +52,22 @@ function readGitBlob(root: string, objectId: string, owner: string): Buffer {
   return content
 }
 
+function readMergeDefault(root: string): string | undefined {
+  const result = spawnSync('git', ['-C', root, 'config', '--get', 'merge.default'], {
+    maxBuffer: GIT_COMMAND_MAX_BUFFER,
+  })
+  if (result.error) {
+    throw new Error(`reading merge.default failed: ${result.error.message}`, { cause: result.error })
+  }
+  if (result.status === 1) return undefined
+  if (result.status !== 0) {
+    throw new Error(
+      `reading merge.default failed with status ${String(result.status)}: ${result.stderr.toString('utf8').trim()}`,
+    )
+  }
+  return result.stdout.toString('utf8').trim()
+}
+
 function assertDefaultTextMerge(root: string, paths: TranslationPairPaths): void {
   const output = runGit(
     root,
@@ -67,6 +76,7 @@ function assertDefaultTextMerge(root: string, paths: TranslationPairPaths): void
   ).toString('utf8')
   const fields = output.split('\0')
   fields.pop()
+  let mergeDefault: string | undefined
   for (let index = 0; index < fields.length; index += 3) {
     const path = fields[index]
     const value = fields[index + 2]
@@ -76,6 +86,14 @@ function assertDefaultTextMerge(root: string, paths: TranslationPairPaths): void
     if (!['unspecified', 'set', 'text'].includes(value)) {
       throw new Error(`${path} uses merge=${value}; the pairing driver only composes Git's default text merge`)
     }
+    if (value === 'unspecified') {
+      mergeDefault ??= readMergeDefault(root)
+      if (mergeDefault !== undefined && mergeDefault !== 'text') {
+        throw new Error(
+          `${path} inherits merge.default=${mergeDefault}; the pairing driver only composes Git's default text merge`,
+        )
+      }
+    }
   }
 }
 
@@ -101,7 +119,7 @@ function mergeBlobTriplet(
       '-L', `${owner}:ancestor`,
       '-L', `${owner}:other`,
       currentPath, ancestorPath, otherPath,
-    ], { maxBuffer: MAX_GIT_OUTPUT })
+    ], { maxBuffer: GIT_COMMAND_MAX_BUFFER })
     if (result.error) {
       throw new Error(`merging ${owner} failed: ${result.error.message}`, { cause: result.error })
     }
@@ -222,46 +240,85 @@ function unmergedSidecars(root: string): Map<string, UnmergedStages> {
   return records
 }
 
+function assertUneditedSidecar(
+  root: string,
+  metaPath: string,
+  currentRecord: string,
+  otherRecord: string,
+): void {
+  const worktreeRecord = readFileSync(join(root, metaPath), 'utf8')
+  if (worktreeRecord === currentRecord || worktreeRecord === otherRecord) return
+  const stageDataLines = [currentRecord, otherRecord]
+    .flatMap(record => record.split(/\r?\n/))
+    .filter(line => line !== '' && !line.startsWith('#'))
+  const hasUneditedConflict = worktreeRecord.includes('<<<<<<<')
+    && worktreeRecord.includes('=======')
+    && worktreeRecord.includes('>>>>>>>')
+    && stageDataLines.every(line => worktreeRecord.includes(line))
+  if (!hasUneditedConflict) {
+    throw new Error(`${metaPath} has edited conflict content; refusing to overwrite manual work`)
+  }
+}
+
 /**
  * Resolve every mechanically composable `.i18n.yaml` conflict in the index.
  *
  * The command first proves that Git's already-staged owner merges match the
  * independently composed contents, then writes and stages all sidecars as one
- * batch. Other conflicts remain untouched.
+ * batch. Other conflicts remain untouched; after staging the safe records, an
+ * aggregate error reports any pairing conflicts that still need manual work.
  *
  * @param root - Repository root with an in-progress merge-like operation.
  * @returns Repository-relative sidecar paths resolved and staged.
  */
 export function resolveTranslationPairingConflicts(root: string): string[] {
   const resolutions: { path: string; record: string }[] = []
+  const failures: { path: string; reason: string }[] = []
   for (const [metaPath, stages] of [...unmergedSidecars(root)].sort(([left], [right]) => left.localeCompare(right))) {
-    if (stages.ancestor === undefined || stages.current === undefined || stages.other === undefined) {
-      throw new Error(`${metaPath} is an add/delete or incomplete-stage conflict and requires manual resolution`)
-    }
-    const result = mergeTranslationPairingRecords(
-      root,
-      metaPath,
-      readGitBlob(root, stages.ancestor, `ancestor ${metaPath}`).toString('utf8'),
-      readGitBlob(root, stages.current, `current ${metaPath}`).toString('utf8'),
-      readGitBlob(root, stages.other, `other ${metaPath}`).toString('utf8'),
-    )
-    const paths = translationPairPathsFromMeta(metaPath)
-    if (readGitIndexBlob(root, paths.source)?.objectId !== result.sourceHash) {
-      throw new Error(`${paths.source} staged merge does not match the pairing driver's clean merge`)
-    }
-    if (readGitIndexBlob(root, paths.zh)?.objectId !== result.zhHash) {
-      throw new Error(`${paths.zh} staged merge does not match the pairing driver's clean merge`)
-    }
-    for (const [path, expected] of [[paths.source, result.sourceHash], [paths.zh, result.zhHash]] as const) {
-      if (gitBlobHash(readFileSync(join(root, path))) !== expected) {
-        throw new Error(`${path} has unstaged content; refusing to confirm bytes outside the merge result`)
+    try {
+      if (stages.ancestor === undefined || stages.current === undefined || stages.other === undefined) {
+        throw new Error('is an add/delete or incomplete-stage conflict and requires manual resolution')
       }
+      const ancestorRecord = readGitBlob(root, stages.ancestor, `ancestor ${metaPath}`).toString('utf8')
+      const currentRecord = readGitBlob(root, stages.current, `current ${metaPath}`).toString('utf8')
+      const otherRecord = readGitBlob(root, stages.other, `other ${metaPath}`).toString('utf8')
+      assertUneditedSidecar(root, metaPath, currentRecord, otherRecord)
+      const result = mergeTranslationPairingRecords(
+        root,
+        metaPath,
+        ancestorRecord,
+        currentRecord,
+        otherRecord,
+      )
+      const paths = translationPairPathsFromMeta(metaPath)
+      if (readGitIndexBlob(root, paths.source)?.objectId !== result.sourceHash) {
+        throw new Error(`${paths.source} staged merge does not match the pairing driver's clean merge`)
+      }
+      if (readGitIndexBlob(root, paths.zh)?.objectId !== result.zhHash) {
+        throw new Error(`${paths.zh} staged merge does not match the pairing driver's clean merge`)
+      }
+      for (const [path, expected] of [[paths.source, result.sourceHash], [paths.zh, result.zhHash]] as const) {
+        if (gitBlobHash(readFileSync(join(root, path))) !== expected) {
+          throw new Error(`${path} has unstaged content; refusing to confirm bytes outside the merge result`)
+        }
+      }
+      resolutions.push({ path: metaPath, record: result.record })
+    } catch (error) {
+      failures.push({ path: metaPath, reason: error instanceof Error ? error.message : String(error) })
     }
-    resolutions.push({ path: metaPath, record: result.record })
   }
   for (const resolution of resolutions) writeFileSync(join(root, resolution.path), resolution.record)
   if (resolutions.length > 0) {
     runGit(root, ['add', '--', ...resolutions.map(resolution => resolution.path)], 'staging resolved pairing records')
   }
+  if (failures.length > 0) {
+    const resolved = resolutions.length === 0
+      ? ''
+      : `resolved and staged ${resolutions.map(resolution => resolution.path).join(', ')}; `
+    throw new Error(
+      `${resolved}left ${String(failures.length)} pairing conflict(s) unresolved:\n`
+      + failures.map(failure => `- ${failure.path}: ${failure.reason}`).join('\n'),
+    )
+  }
   return resolutions.map(resolution => resolution.path)
 }

From b9b25f81cb5659b7b73ab6ec049a53a36e26407a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 22:17:54 +0800
Subject: [PATCH 351/516] fix(subprocess-local): fence descendant adoption on
 the shell's start identity

A recycled shell pid could donate an unrelated process's children to the
terminal session's cleanup signalling: post-exit rescans queried
processTree/processSession by numeric pid alone. The handle now captures
the spawned shell's start identity at construction and adopts newly
scanned members only while the root pid still carries it; already-adopted
members keep their own identities, which every signal already rechecks.
Regressions cover a recycled root donating an imposter child and a shell
whose identity was never observable; the terminal fakes now model the
root row the real /proc and ps scans include.

Also from the review round: tool-pty's dependency list is re-sorted, and
the LSP renderer documents the deliberate drive-letter reading of
ambiguous file: URIs (display-only blast radius).
---
 packages/lsp/tool-lsp/src/render.ts           |  3 ++
 packages/pty/tool-pty/package.json            |  2 +-
 .../subprocess-local/src/terminal.ts          | 16 ++++++-
 .../subprocess-local/tests/local.spec.ts      |  2 +-
 .../subprocess-local/tests/terminal.spec.ts   | 48 ++++++++++++++++---
 5 files changed, 60 insertions(+), 11 deletions(-)

diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts
index 761f5a7d34..ad77b2a6e2 100644
--- a/packages/lsp/tool-lsp/src/render.ts
+++ b/packages/lsp/tool-lsp/src/render.ts
@@ -146,6 +146,9 @@ export function renderUri(uri: string, workspaceUri: string): string {
     return uri
   }
   if (workspace.protocol !== 'file:') return uri
+  // A `file:` URI does not carry its world's OS, so a leading `/X:` segment is
+  // read as a Windows drive. A POSIX workspace literally rooted at `/c:/...`
+  // would mis-render (display only; edits and reads use the exact URI).
   const drivePath = /^\/[a-z](?::|%3A)/iu
   const windowsWorld = workspace.hostname.length > 0 || drivePath.test(workspace.pathname)
   const targetWindowsWorld = windowsWorld && (target.hostname.length > 0 || drivePath.test(target.pathname))
diff --git a/packages/pty/tool-pty/package.json b/packages/pty/tool-pty/package.json
index 9027169941..f443bbbdf4 100644
--- a/packages/pty/tool-pty/package.json
+++ b/packages/pty/tool-pty/package.json
@@ -50,8 +50,8 @@
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tasks": "workspace:^",
     "@deepseek-ai/dsh-tasks-local": "workspace:^",
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 2d3d0bb78e..2a763948bb 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -43,6 +43,8 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   private cleanup: Promise<void> | undefined
   private exited = false
   private trackedDescendants: ProcessIdentity[] = []
+  /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
+  private readonly rootIdentity: ProcessIdentity | undefined
 
   /**
    * @param terminal - allocated node-pty process.
@@ -55,6 +57,7 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
     private readonly graceMs: number,
   ) {
     this.pid = terminal.pid
+    this.rootIdentity = inspector.processTree(this.pid).find(member => member.pid === this.pid)
     this.done = this.outcome.promise
     this.dataDisposable = terminal.onData((data) => { this.output.write(Buffer.from(data, 'utf8')) })
     this.exitDisposable = terminal.onExit(({ exitCode, signal: exitSignal }) => {
@@ -112,10 +115,19 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private descendants(): ProcessIdentity[] {
+    // Adopt newly scanned members only while the numeric root pid provably
+    // still carries the spawned shell's start identity: after the shell dies,
+    // a recycled pid's tree and session must not donate an unrelated
+    // process's children to this session's signalling. Already-adopted
+    // members keep their own start identities, which every signal rechecks.
+    const tree = this.inspector.processTree(this.pid)
+    const root = tree.find(member => member.pid === this.pid)
+    const rootVerified = this.rootIdentity !== undefined
+      && root !== undefined
+      && root.started === this.rootIdentity.started
     this.trackedDescendants = this.survivors(this.unionMembers(
       this.trackedDescendants,
-      this.inspector.processTree(this.pid),
-      this.inspector.processSession(this.pid),
+      ...rootVerified ? [tree, this.inspector.processSession(this.pid)] : [],
     ).filter(member => member.pid !== this.pid))
     return this.trackedDescendants
   }
diff --git a/packages/subprocess/subprocess-local/tests/local.spec.ts b/packages/subprocess/subprocess-local/tests/local.spec.ts
index 347b9c9330..c4e3f91522 100644
--- a/packages/subprocess/subprocess-local/tests/local.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/local.spec.ts
@@ -249,7 +249,7 @@ describe('LocalSubprocessService', () => {
       ;(ctx.subprocess as InstanceType<typeof IsolatedLocalSubprocessService>).terminalInspector = {
         foregroundPgid: () => 123,
         isStdinWaiting: () => false,
-        processTree: () => [{ pid: 124, started: 'child' }],
+        processTree: () => [{ pid: 123, started: 'shell' }, { pid: 124, started: 'child' }],
         processSession: () => [],
         isAlive: identity => alive.has(identity.pid),
         signalGroup: () => {},
diff --git a/packages/subprocess/subprocess-local/tests/terminal.spec.ts b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
index 8a6270883f..79501c7dc4 100644
--- a/packages/subprocess/subprocess-local/tests/terminal.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/terminal.spec.ts
@@ -52,6 +52,8 @@ class FakePty {
 class FakeInspector implements ProcessInspector {
   pgid: number | undefined = 456
   waiting = false
+  /** The shell's own row, present like the real /proc- and ps-backed scans; tests recycle or drop it. */
+  root: ProcessIdentity | undefined = { pid: 123, started: 'shell' }
   members: ProcessIdentity[] = []
   sessionMembers: ProcessIdentity[] = []
   readonly alive = new Set<number>()
@@ -63,7 +65,7 @@ class FakeInspector implements ProcessInspector {
 
   foregroundPgid() { return this.pgid }
   isStdinWaiting() { return this.waiting }
-  processTree() { return this.members }
+  processTree() { return this.root === undefined ? this.members : [this.root, ...this.members] }
   processSession() { return this.sessionMembers }
   isAlive(identity: ProcessIdentity) { return this.alive.has(identity.pid) }
   signalGroup(pgid: number, signal: SubprocessTerminalSignal) {
@@ -189,19 +191,50 @@ describe('LocalTerminalHandle', () => {
     expect(inspector.processes).toEqual([[124, 'SIGTERM']])
   })
 
+  it('does not adopt the children of a recycled shell pid', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+
+    pty.emitExit()
+    const imposterChild = { pid: 999, started: 'imposter-child' }
+    inspector.root = { pid: 123, started: 'imposter' }
+    inspector.members = [imposterChild]
+    inspector.alive.add(imposterChild.pid)
+
+    await handle.terminate()
+    expect(inspector.processes).toEqual([])
+  })
+
+  it('adopts nothing when the shell identity was never observable', async () => {
+    const pty = new FakePty()
+    const inspector = new FakeInspector()
+    inspector.root = undefined
+    const orphan = { pid: 321, started: 'unverifiable' }
+    inspector.members = [orphan]
+    inspector.alive.add(orphan.pid)
+    const handle = new LocalTerminalHandle(pty.asPty(), inspector, 10)
+
+    await handle.terminate()
+    expect(inspector.processes).toEqual([])
+    expect(pty.kills).toEqual(['SIGTERM'])
+  })
+
   it('rescans for descendants forked during TERM', async () => {
     const pty = new FakePty()
     const inspector = new FakeInspector()
+    const root = { pid: 123, started: 'shell' }
     let reads = 0
     inspector.processTree = () => {
       reads += 1
-      if (reads === 1) {
-        inspector.alive.add(124)
-        return [{ pid: 124, started: 'first' }]
-      }
+      if (reads === 1) return [root]
       if (reads === 2) {
+        inspector.alive.add(124)
+        return [root, { pid: 124, started: 'first' }]
+      }
+      if (reads === 3) {
         inspector.alive.add(125)
-        return [{ pid: 125, started: 'late' }]
+        return [root, { pid: 125, started: 'late' }]
       }
       return []
     }
@@ -256,9 +289,10 @@ describe('LocalTerminalHandle', () => {
     const pty = new FakePty()
     const inspector = new FakeInspector()
     const captured = { pid: 124, started: 'captured' }
+    const root = { pid: 123, started: 'shell' }
     let reads = 0
     inspector.alive.add(captured.pid)
-    inspector.processTree = () => reads++ === 0 ? [captured] : []
+    inspector.processTree = () => { reads += 1; return reads === 1 ? [root] : reads === 2 ? [root, captured] : [] }
     inspector.signalProcess = (identity, signal) => {
       inspector.processes.push([identity.pid, signal])
       if (signal === 'SIGKILL') inspector.alive.delete(identity.pid)

From e7b682f1f65fa9de386edffd94bd4c46c232a786 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 10:05:30 +0800
Subject: [PATCH 352/516] feat(e2b): add remote runtime providers

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   6 +
 .../2026-07-27-e2b-remote-runtime-poc.md      |  46 ++
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |  46 ++
 docs/architecture.zh.md                       |   1 +
 docs/cordis-catalog/services.md               |  15 +
 examples/headless-agent/README.i18n.yaml      |   4 +-
 examples/headless-agent/README.md             |  26 +-
 examples/headless-agent/README.zh.md          |  26 +-
 examples/headless-agent/e2b.cordis.yml        |  30 +
 .../tests/fixtures/e2b/e2b/bin.ts             |  32 +
 .../tests/fixtures/e2b/e2b/cordis.yml         |  19 +
 examples/package.json                         |   3 +
 knip.json                                     |  11 +
 packages/README.i18n.yaml                     |   4 +-
 packages/README.md                            |   1 +
 packages/README.zh.md                         |   1 +
 packages/e2b/README.i18n.yaml                 |   6 +
 packages/e2b/README.md                        |  13 +
 packages/e2b/README.zh.md                     |  13 +
 packages/e2b/e2b/README.i18n.yaml             |   6 +
 packages/e2b/e2b/README.md                    |  50 ++
 packages/e2b/e2b/README.zh.md                 |  50 ++
 packages/e2b/e2b/package.json                 |  44 ++
 packages/e2b/e2b/src/index.ts                 | 240 ++++++
 packages/e2b/e2b/src/invariant.ts             |  30 +
 packages/e2b/e2b/tests/composition.e2e.ts     |  39 +
 packages/e2b/e2b/tests/e2b.spec.ts            | 218 ++++++
 packages/e2b/e2b/tsconfig.json                |  25 +
 packages/fs/README.i18n.yaml                  |   4 +-
 packages/fs/README.md                         |   3 +-
 packages/fs/README.zh.md                      |   3 +-
 packages/fs/fs-e2b/README.i18n.yaml           |   6 +
 packages/fs/fs-e2b/README.md                  |  29 +
 packages/fs/fs-e2b/README.zh.md               |  29 +
 packages/fs/fs-e2b/package.json               |  41 +
 packages/fs/fs-e2b/src/index.ts               | 423 ++++++++++
 packages/fs/fs-e2b/src/invariant.ts           |  27 +
 packages/fs/fs-e2b/tests/filesystem.spec.ts   | 537 +++++++++++++
 packages/fs/fs-e2b/tsconfig.json              |  25 +
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.md                 |   7 +-
 packages/subprocess/README.zh.md              |  11 +-
 .../subprocess-e2b/README.i18n.yaml           |   6 +
 packages/subprocess/subprocess-e2b/README.md  |  32 +
 .../subprocess/subprocess-e2b/README.zh.md    |  32 +
 .../subprocess/subprocess-e2b/package.json    |  41 +
 .../subprocess/subprocess-e2b/src/index.ts    |  58 ++
 .../subprocess-e2b/src/invariant.ts           |  27 +
 .../subprocess/subprocess-e2b/src/output.ts   |  70 ++
 .../subprocess/subprocess-e2b/src/process.ts  | 417 ++++++++++
 .../subprocess-e2b/tests/subprocess.spec.ts   | 725 ++++++++++++++++++
 .../subprocess/subprocess-e2b/tsconfig.json   |  25 +
 scripts/gen-cordis-catalog.ts                 |   1 +
 .../verify-package-readme-model-experience.ts |   3 +
 tsconfig.base.json                            |   1 +
 tsconfig.host.json                            |   3 +
 56 files changed, 3565 insertions(+), 30 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
 create mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
 create mode 100644 examples/headless-agent/e2b.cordis.yml
 create mode 100644 examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
 create mode 100644 examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
 create mode 100644 packages/e2b/README.i18n.yaml
 create mode 100644 packages/e2b/README.md
 create mode 100644 packages/e2b/README.zh.md
 create mode 100644 packages/e2b/e2b/README.i18n.yaml
 create mode 100644 packages/e2b/e2b/README.md
 create mode 100644 packages/e2b/e2b/README.zh.md
 create mode 100644 packages/e2b/e2b/package.json
 create mode 100644 packages/e2b/e2b/src/index.ts
 create mode 100644 packages/e2b/e2b/src/invariant.ts
 create mode 100644 packages/e2b/e2b/tests/composition.e2e.ts
 create mode 100644 packages/e2b/e2b/tests/e2b.spec.ts
 create mode 100644 packages/e2b/e2b/tsconfig.json
 create mode 100644 packages/fs/fs-e2b/README.i18n.yaml
 create mode 100644 packages/fs/fs-e2b/README.md
 create mode 100644 packages/fs/fs-e2b/README.zh.md
 create mode 100644 packages/fs/fs-e2b/package.json
 create mode 100644 packages/fs/fs-e2b/src/index.ts
 create mode 100644 packages/fs/fs-e2b/src/invariant.ts
 create mode 100644 packages/fs/fs-e2b/tests/filesystem.spec.ts
 create mode 100644 packages/fs/fs-e2b/tsconfig.json
 create mode 100644 packages/subprocess/subprocess-e2b/README.i18n.yaml
 create mode 100644 packages/subprocess/subprocess-e2b/README.md
 create mode 100644 packages/subprocess/subprocess-e2b/README.zh.md
 create mode 100644 packages/subprocess/subprocess-e2b/package.json
 create mode 100644 packages/subprocess/subprocess-e2b/src/index.ts
 create mode 100644 packages/subprocess/subprocess-e2b/src/invariant.ts
 create mode 100644 packages/subprocess/subprocess-e2b/src/output.ts
 create mode 100644 packages/subprocess/subprocess-e2b/src/process.ts
 create mode 100644 packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts
 create mode 100644 packages/subprocess/subprocess-e2b/tsconfig.json

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
new file mode 100644
index 0000000000..13d081c28f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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-e2b-remote-runtime-poc.md
+2026-07-27-e2b-remote-runtime-poc.md: 307a08d6ca77c83bf836bc8d50b071fbf33ac49a
+2026-07-27-e2b-remote-runtime-poc.zh.md: bb4e657d999760f000949d509228bbb65f22773a
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
new file mode 100644
index 0000000000..307a08d6ca
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -0,0 +1,46 @@
+# Agent Note: Shared E2B remote runtime POC
+
+Status: implemented
+
+English | [中文](2026-07-27-e2b-remote-runtime-poc.zh.md)
+
+## Problem
+
+A remote coding-agent backend is useful only when file operations and commands observe one coherent world. Attaching E2B independently at individual tools would allow a Bash command and a filesystem edit to address different sandboxes, while moving the complete harness into a remote VM would couple provider experimentation to agent, session, model, persistence, and deployment changes.
+
+## Decision
+
+The E2B integration is a provider-composition POC with one shared lifecycle owner and two capability implementations:
+
+- `@deepseek-ai/dsh-e2b` creates or reconnects one secure E2B sandbox, creates its working and private runtime directories, and owns kill/pause/leave disposal.
+- `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
+- `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands and remote Linux process groups.
+- The existing `@deepseek-ai/dsh-bash-local` remains the Bash implementation because it delegates all process mechanics to `ctx.subprocess`.
+
+The owner is the sole source of sandbox identity. Providers inject it and never create private sandboxes. The composition therefore gives filesystem tools and Bash one remote cwd, process namespace, and spill/state directory while preserving the existing capability interfaces and model-facing tools.
+
+## POC boundary
+
+Only filesystem state, command processes during the provider lifetime, and adapter-owned remote files move into E2B. The host retains Cordis and plugin objects, the agent loop, agent/session state, session logs and persistence, model requests, skills, subagent orchestration, and E2B SDK buffers. The overlay does not upload or mount the host workspace; identical cwd strings name independent host and remote directories. Managed process groups still terminate and join when the subprocess service disposes, including before a retained-sandbox pause or leave disposition.
+
+The POC has no PTY adapter, LSP-specific integration, session-persistence backend, code-runtime backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, or workspace synchronization. Retained sandbox reconnect proves lifecycle continuity only; it does not reconstruct host process handles, output cursors, or locks.
+
+## Verification
+
+Package tests pin lifecycle cleanup, filesystem seam semantics, subprocess group/stdio/abort behavior, and the package-owned invariant registrations. A credential-gated real Loader composition creates one sandbox, proves FS-write→Bash-read and Bash-write→FS-read in the same remote cwd, proves neither file appears in the host cwd, disposes the composition, and confirms the sandbox id is gone.
+
+## Alternatives considered
+
+**A separate E2B sandbox per capability or tool** — rejected because file and command operations would not share identity or state, defeating the coding-agent use case and multiplying lifecycle ownership.
+
+**Run the entire harness process inside E2B** — rejected because it changes deployment, credential flow, model transport, session durability, plugin loading, and supervision at once. Those questions are independent of proving the provider seams.
+
+**Add E2B-specific Bash, PTY, LSP, persistence, and synchronization packages together** — rejected because Bash already has the required subprocess seam and the other capabilities need separate consumer evidence and lifecycle designs. Their absence is an explicit fidelity boundary, not an incomplete hidden plan.
+
+**Implement filesystem operations through shell commands only** — rejected because that bypasses `ctx.fs` identity, structured errors, version guards, streaming reads, and atomic mutation semantics already consumed by the file tools.
+
+## Consequences
+
+The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual state retention for experiments, while kill remains the demo's cleanup policy.
+
+The provider is not interchangeable with the local subprocess backend for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, callback output is not byte-faithful, signal attribution is inferred, and reconnect cannot restore handles. Remote process/spill artifacts accumulate in a retained sandbox. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
new file mode 100644
index 0000000000..bb4e657d99
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -0,0 +1,46 @@
+# Agent Note: 共享 E2B 远程运行时 POC
+
+Status: implemented
+
+[English](2026-07-27-e2b-remote-runtime-poc.md) | 中文
+
+## 问题
+
+远程 coding agent（智能体）后端只有在文件操作与命令观察到同一个一致环境时才有用。若在各工具上分别接入 E2B，Bash 命令和文件系统编辑可能访问不同的沙箱；若把完整 harness 迁入远程 VM，则会把提供方实验与 agent、会话、模型、持久化及部署变更耦合在一起。
+
+## 决策
+
+E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和两个功能实现组成：
+
+- `@deepseek-ai/dsh-e2b` 创建或重新连接一个安全的 E2B 沙箱，创建其工作目录与私有运行时目录，并拥有 kill/pause/leave 资源释放操作。
+- `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
+- `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands 和远程 Linux 进程组之上实现 `ctx.subprocess`。
+- 现有的 `@deepseek-ai/dsh-bash-local` 继续作为 Bash 实现，因为它把所有进程机制委托给 `ctx.subprocess`。
+
+该所有者是沙箱身份的唯一真源。提供方会注入该所有者，绝不创建私有沙箱。因此，该组合让文件系统工具与 Bash 共享一个远程 cwd、进程命名空间和 spill／状态目录，同时保留现有功能接口与面向模型的工具。
+
+## POC 边界
+
+只有文件系统状态、提供方存续期内的命令进程，以及适配器拥有的远程文件会迁入 E2B。宿主仍保留 Cordis 和插件对象、agent loop（智能体循环）、agent／会话状态、会话日志及其持久化、模型请求、skill（技能）、subagent 编排和 E2B SDK 缓冲。该 overlay 不会上传或挂载宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。受管进程组仍会在进程管理服务 dispose（资源释放）时终止并等待退出，包括保留沙箱采用 `pause` 或 `leave` 处置方式之前。
+
+本 POC 没有 PTY 适配器、LSP 专用集成、会话持久化后端、代码运行时后端、模板构建器、卷、快照、网络策略层、沙箱目录或工作区同步。保留沙箱后重新连接只能证明生命周期连续性；它不会重建宿主进程句柄、输出游标或锁。
+
+## 验证
+
+包测试固定生命周期清理、文件系统 seam 语义、进程管理的进程组／stdio／中止行为，以及包自有不变式注册。凭据门控的真实 Loader 组合会创建一个沙箱，证明同一远程 cwd 中 FS-write→Bash-read 和 Bash-write→FS-read 双向可见，证明两个文件均未出现在宿主 cwd 中，释放组合，并确认该沙箱 id 已不存在。
+
+## 曾考虑的替代方案
+
+**每项功能或每个工具使用独立的 E2B 沙箱。** 不予采纳，因为文件操作和命令操作将无法共享身份或状态，既违背 coding agent 用例，也会增加生命周期所有者的数量。
+
+**在 E2B 内运行完整 harness 进程。** 不予采纳，因为这会同时改变部署、凭据流、模型传输、会话持久性、插件加载和监管方式。要证明提供方 seam，并不需要同时回答这些彼此独立的问题。
+
+**同时添加 E2B 专用 Bash、PTY、LSP、持久化和同步包。** 不予采纳，因为 Bash 已经具备所需的进程管理 seam，其他功能则需要各自的消费方证据和生命周期设计。缺少它们是显式保真边界，而不是尚未公开的不完整计划。
+
+**仅通过 shell 命令实现文件系统操作。** 不予采纳，因为这会绕过文件工具已经使用的 `ctx.fs` 身份、结构化错误、版本防护、流式读取和原子变更语义。
+
+## 后果
+
+这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留状态，演示仍以 `kill` 作为清理策略。
+
+该提供方并不能对所有消费方与本地进程管理后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，回调输出并非字节保真，信号归因依靠推断，重新连接也无法恢复句柄。保留沙箱后会累积远程进程／spill 产物。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 9314a3fbfc..2d1a0b43d5 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -25,6 +25,7 @@
 |---|---|---|
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | 适配器注册表和模型流式调用 |
 | `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的单实例请求压力与表面压力 |
+| `ctx.e2b` | [`e2b/`](../packages/e2b/README.md) | 共享 E2B 沙箱 |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | 前台和后台命令执行 |
 | `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | 可执行文件查找、受管进程树、终端 |
 | `ctx.pty` | [`pty/`](../packages/pty/README.md) | 按 owner 隔离的持久化终端会话 |
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 7e125cd02c..7ce45c6817 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -578,6 +578,21 @@ abstract capability(): DirectoryPickerCapability
 
 Source: [`packages/host/directory-picker/src/index.ts:131`](../../packages/host/directory-picker/src/index.ts)
 
+## `ctx.e2b` — `E2BSandboxService`
+
+Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decision. The connection begins at plugin construction; adapters await getSandbox before their first operation.
+
+```ts cordis-catalog
+/**
+ * Return the shared live SDK handle.
+ * @returns the created or reconnected sandbox after the configured cwd exists.
+ * @throws when E2B rejects creation/reconnection or the service is disposing.
+ */
+async getSandbox(): Promise<Sandbox>
+```
+
+Source: [`packages/e2b/e2b/src/index.ts:97`](../../packages/e2b/e2b/src/index.ts)
+
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
diff --git a/examples/headless-agent/README.i18n.yaml b/examples/headless-agent/README.i18n.yaml
index 7b6139f28b..56c02d3e0a 100644
--- a/examples/headless-agent/README.i18n.yaml
+++ b/examples/headless-agent/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 examples/headless-agent/README.md
-README.md: e00f3d2d4fd21a860239f3d3a3e5eb2d7520f14a
-README.zh.md: 6cd845783b1c112ba73676474b176ec28a4d0b78
+README.md: 16c45d304eb0f06a2b062518b053db683cd402c0
+README.zh.md: 72d2813d174e74a3bf93c363b268499a44f1cd4f
diff --git a/examples/headless-agent/README.md b/examples/headless-agent/README.md
index e00f3d2d4f..16c45d304e 100644
--- a/examples/headless-agent/README.md
+++ b/examples/headless-agent/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-This directory owns the replay and real-model test composition for a headless coding agent: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + JSONL persistence. It explicitly mounts the shared agent spine, one root agent, persistence, and checkpoint policy; it is not a second product front door.
+Headless one-shot agent wiring: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + JSONL persistence, with [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) as the app front door.
 
 ## Run it
 
@@ -10,13 +10,27 @@ This directory owns the replay and real-model test composition for a headless co
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run dsh run "fix the failing test in this workspace"
+pnpm run demo:headless "fix the failing test in this workspace"
+pnpm run demo:headless --output-format json -- "summarize the implementation"
+pnpm run demo:headless --output-format stream-json -- "run the focused tests"
 ```
 
-The product command is [`dsh run`](../../apps/cli/README.md): it accepts one nonblank task, creates and persists a fresh session, prints the final assistant text, and exits. The root `demo:headless` script is only an alias of that command.
+Exactly one nonblank positional task is required; quote tasks containing spaces. There is no `-p` flag. `text` prints the last text-bearing assistant message, `json` prints one DSH-native result record, and `stream-json` emits the top-level session's canonical task-turn events before that record. Child sessions surface only through parent tool events and results.
 
-Snapshot suites run this directory's configuration through [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts), an unexported test-only process that emits canonical session events as JSONL before its result record. That stream is test infrastructure, not a supported CLI output format. Child sessions surface only through parent tool events and results.
+Each invocation creates and persists a fresh session, runs all model and tool steps in one turn, flushes, disposes, and exits. This is non-interactive automation: there is no prompt, approval, resume, second turn, or stdin context. The configured tools can mutate the launch workspace, run commands, spawn child agents, and consume provider tokens.
 
-## Advanced configuration
+## E2B POC overlay
 
-[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the test composition.
+[`e2b.cordis.yml`](e2b.cordis.yml) replaces the local filesystem and subprocess providers with one shared E2B sandbox while retaining `dsh-bash-local` and the same model-facing tools. Put `E2B_API_KEY` beside `DEEPSEEK_API_KEY` in the gitignored root `.env`, then run:
+
+```sh
+pnpm run demo:e2b "create hello.txt, read it back, and run pwd"
+```
+
+The overlay creates the same absolute cwd inside the sandbox, but it does not upload or mount the host workspace. File and Bash mutations exist only in E2B; Cordis, model calls, agent/session state, session logs, skills, and SDK buffers remain on the host. The demo kills its sandbox on timeout and disposal. It is a provider-composition POC, not a whole-harness migration or a workspace-sync feature.
+
+## Advanced and snapshot wiring
+
+[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the shipped leaf. [`advanced.cordis.snapshot.yml`](advanced.cordis.snapshot.yml) replaces only the live LLM with replay. The tests under [`tests/`](tests/) own the keyless real-Loader smoke, key-gated world-verified smoke, and the `stream-json` replay snapshot with its parent and child session fixtures.
+
+The package-level [CLI contract](../../packages/examples/cli-demo/README.md) documents output records, exit status, cancellation, persistence, and model/token effects.
diff --git a/examples/headless-agent/README.zh.md b/examples/headless-agent/README.zh.md
index 6cd845783b..72d2813d17 100644
--- a/examples/headless-agent/README.zh.md
+++ b/examples/headless-agent/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本目录负责 headless coding agent（智能体）的回放和真实模型测试组装：DeepSeek V4 + 本地 bash 与文件系统工具 + subagent 委托 + 工作流与全新 agent Ralph 迭代 + `todo_write` + JSONL 持久化。本目录显式挂载共享 agent 主干、一个根 agent、持久化和检查点策略；它不是第二个产品入口。
+无头单次 agent（智能体）接线：DeepSeek V4 + 本地 bash 与文件系统工具 + subagent 委托 + 工作流与新 agent Ralph 迭代 + `todo_write` + JSONL 持久化，并以 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) 作为应用入口。
 
 ## 运行
 
@@ -10,13 +10,27 @@
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run dsh run "fix the failing test in this workspace"
+pnpm run demo:headless "fix the failing test in this workspace"
+pnpm run demo:headless --output-format json -- "summarize the implementation"
+pnpm run demo:headless --output-format stream-json -- "run the focused tests"
 ```
 
-产品命令是 [`dsh run`](../../apps/cli/README.md)：它接受一项非空任务，创建并持久化新会话，打印最终 assistant 文本，然后退出。根目录的 `demo:headless` 脚本只是该命令的别名。
+必须提供且只能提供一个非空位置任务；含空格的任务需要加引号。没有 `-p` 标志。`text` 打印最后一条包含文本的 assistant 消息，`json` 打印一条 DSH 原生结果记录，`stream-json` 则在该记录之前发出顶层会话的规范任务轮次事件。子会话只通过父工具事件和结果对外显示。
 
-快照套件通过 [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts) 运行本目录的配置。这个未导出且仅供测试使用的进程会在结果记录之前，以 JSONL 发出规范会话事件。该事件流属于测试基础设施，不是受支持的 CLI（命令行界面）输出格式。子会话只通过父会话的工具事件和结果对外显示。
+每次调用都会创建并持久化新会话，在一个轮次中运行所有模型和工具步骤，然后刷新、释放并退出。这是非交互式自动化：没有提示符、批准、恢复、第二轮次或 stdin 上下文。已配置工具可以修改启动 workspace、运行命令、spawn 子 agent，并消耗提供方 token。
 
-## 高级配置
+## E2B POC overlay
 
-[`advanced.cordis.yml`](advanced.cordis.yml) 在测试组装中添加 Code Mode 和 Cordis 工具。
+[`e2b.cordis.yml`](e2b.cordis.yml) 使用一个共享 E2B 沙箱替换本地文件系统与进程管理提供方，同时保留 `dsh-bash-local` 和相同的面向模型工具。请在 git 忽略的根目录 `.env` 中，将 `E2B_API_KEY` 与 `DEEPSEEK_API_KEY` 放在一起，然后运行：
+
+```sh
+pnpm run demo:e2b "create hello.txt, read it back, and run pwd"
+```
+
+该 overlay 会在沙箱中创建拼写相同的绝对 cwd，但不会上传或挂载宿主工作区。文件与 Bash 变更只存在于 E2B；Cordis、模型调用、agent／会话状态、会话日志、skill（技能）和 SDK 缓冲仍在宿主上。演示会在超时和资源释放时终止其沙箱。它是提供方组合 POC，而不是完整 harness 迁移或工作区同步功能。
+
+## 高级与快照接线
+
+[`advanced.cordis.yml`](advanced.cordis.yml) 在已交付叶节点上添加 Code Mode 和 Cordis 工具。[`advanced.cordis.snapshot.yml`](advanced.cordis.snapshot.yml) 只将实时 LLM（大语言模型）替换为回放。[`tests/`](tests/) 下的测试拥有无密钥真实 Loader 冒烟测试、密钥门控的外部状态验证冒烟测试，以及带父子会话 fixture（测试前置数据）的 `stream-json` 回放快照。
+
+包级 [CLI 契约](../../packages/examples/cli-demo/README.md)记录输出记录、退出状态、取消、持久化以及模型／token 影响。
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
new file mode 100644
index 0000000000..4f961100b4
--- /dev/null
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -0,0 +1,30 @@
+# POC overlay: keep the headless agent and model-facing tools, but place its
+# filesystem and managed Bash process world in one short-lived E2B sandbox.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: subprocess
+        name: '@deepseek-ai/dsh-subprocess-local'
+        disabled: true
+      - id: fs-local
+        name: '@deepseek-ai/dsh-fs-local'
+        disabled: true
+      - id: bash
+        name: '@deepseek-ai/dsh-bash-local'
+        config:
+          cwd: !!js process.cwd()
+          timeoutMs: 60000
+      - insert:
+          - id: e2b
+            name: '@deepseek-ai/dsh-e2b'
+            config:
+              cwd: !!js process.cwd()
+              timeoutMs: 300000
+              onTimeout: kill
+              onDispose: kill
+          - id: subprocess-e2b
+            name: '@deepseek-ai/dsh-subprocess-e2b'
+          - id: fs-e2b
+            name: '@deepseek-ai/dsh-fs-e2b'
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
new file mode 100644
index 0000000000..3b2cef609b
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -0,0 +1,32 @@
+import { resolve } from 'node:path'
+import { boot } from '@deepseek-ai/dsh-app-boot'
+import type {} from '@deepseek-ai/dsh-e2b'
+import type {} from '@deepseek-ai/dsh-fs-e2b'
+import type {} from '@deepseek-ai/dsh-bash-local'
+
+const configPath = process.argv[2]
+if (configPath === undefined) throw new Error('usage: bin.ts <cordis.yml>')
+
+const ctx = await boot('e2b-composition', resolve(configPath))
+try {
+  const fromFs = await ctx.fs.resolve('from-fs.txt')
+  await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
+  const bashRead = await ctx.bash.run(ctx.bash.resolve({ command: 'cat from-fs.txt' }))
+  if (bashRead.exitCode !== 0 || bashRead.stdout.text !== 'written-by-fs\n') {
+    throw new Error(`E2B Bash could not read the FS write: ${JSON.stringify(bashRead)}`)
+  }
+
+  const bashWrite = await ctx.bash.run(ctx.bash.resolve({ command: "printf 'written-by-bash\\n' > from-bash.txt" }))
+  if (bashWrite.exitCode !== 0) {
+    throw new Error(`E2B Bash could not write the shared filesystem: ${JSON.stringify(bashWrite)}`)
+  }
+  const fromBash = await ctx.fs.resolve('from-bash.txt')
+  const fsRead = await ctx.fs.readText(fromBash)
+  process.stdout.write(`${JSON.stringify({
+    sandboxId: await ctx.e2b.sandboxId,
+    bashRead: bashRead.stdout.text,
+    fsRead,
+  })}\n`)
+} finally {
+  await ctx.fiber.dispose()
+}
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
new file mode 100644
index 0000000000..08a7e7225c
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -0,0 +1,19 @@
+- id: e2b
+  name: '@deepseek-ai/dsh-e2b'
+  config:
+    cwd: !!js process.cwd()
+    timeoutMs: 60000
+    onTimeout: kill
+    onDispose: kill
+
+- id: subprocess-e2b
+  name: '@deepseek-ai/dsh-subprocess-e2b'
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    cwd: !!js process.cwd()
+    timeoutMs: 30000
+
+- id: fs-e2b
+  name: '@deepseek-ai/dsh-fs-e2b'
diff --git a/examples/package.json b/examples/package.json
index 1f6e99d240..48ac39f5ca 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -26,7 +26,9 @@
     "@deepseek-ai/dsh-compact-basic": "workspace:*",
     "@deepseek-ai/dsh-compact-tool-result-prune": "workspace:*",
     "@deepseek-ai/dsh-credentials-local": "workspace:*",
+    "@deepseek-ai/dsh-e2b": "workspace:*",
     "@deepseek-ai/dsh-fs-local": "workspace:*",
+    "@deepseek-ai/dsh-fs-e2b": "workspace:*",
     "@deepseek-ai/dsh-fs-policy": "workspace:*",
     "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:*",
@@ -76,6 +78,7 @@
     "@deepseek-ai/dsh-subagent-fork": "workspace:*",
     "@deepseek-ai/dsh-subagent-spawn": "workspace:*",
     "@deepseek-ai/dsh-subprocess-local": "workspace:*",
+    "@deepseek-ai/dsh-subprocess-e2b": "workspace:*",
     "@deepseek-ai/dsh-system-prompt": "workspace:*",
     "@deepseek-ai/dsh-tasks-local": "workspace:*",
     "@deepseek-ai/dsh-time-context": "workspace:*",
diff --git a/knip.json b/knip.json
index ede8b2c738..d154cd646b 100644
--- a/knip.json
+++ b/knip.json
@@ -45,6 +45,7 @@
         "headless-agent/tests/fixtures/time-context-mock-llm.ts",
         "headless-agent/tests/fixtures/telemetry-otel-driver.ts",
         "headless-agent/tests/fixtures/telemetry-redact-rule.ts",
+        "headless-agent/tests/fixtures/e2b/e2b/bin.ts",
         "acp-agent/tests/snapshots/lsp-definition/workspace/subject.ts",
         "acp-agent/tests/fixtures/child-question-tripwire.ts",
         "acp-agent/tests/fixtures/partial-landlock-sandbox.ts",
@@ -229,6 +230,16 @@
         "tests/**/*.ts"
       ]
     },
+    "packages/e2b/e2b": {
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
+    },
     "packages/context/time-context": {
       "entry": [
         "tests/**/*.spec.ts",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 8aa9b92b91..3eee08f35b 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 229feae568ba6e40a9c633696097eff46fd5bc95
-README.zh.md: b84aef020a7e3edf305df709d399fbc7b093b6a3
+README.md: 1b2a1737bcac33829a65fa937668ca9496035330
+README.zh.md: 2ef61e9c38750f4420ce99abc9943af1f3308b56
diff --git a/packages/README.md b/packages/README.md
index 229feae568..54a5779016 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -16,6 +16,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
+| [`e2b/`](e2b/README.md) | E2B remote filesystem/process providers | POC |
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index b84aef020a..46b112ec8f 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -16,6 +16,7 @@
 | [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
+| [`e2b/`](e2b/README.md) | E2B 远程文件系统／进程管理提供方 | POC |
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
new file mode 100644
index 0000000000..1bc9761930
--- /dev/null
+++ b/packages/e2b/README.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 packages/e2b/README.md
+README.md: 4b28ec7c0452189a579a6d7e0cd22a0b8561784d
+README.zh.md: ab254eecad82c05cd6a6021e7f8bc4eda6cf3076
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
new file mode 100644
index 0000000000..4b28ec7c04
--- /dev/null
+++ b/packages/e2b/README.md
@@ -0,0 +1,13 @@
+# e2b/ — E2B remote runtime family
+
+English | [中文](README.zh.md)
+
+An experimental provider-composition POC that places the filesystem and managed subprocess world in one E2B Linux sandbox. The shared owner is separate from the capability adapters so every remote provider awaits the same sandbox identity and lifecycle.
+
+| Package | ctx key | Role |
+|---|---|---|
+| [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create or reconnect one sandbox, create its working/runtime directories, expose the shared SDK handle, and apply the configured kill/pause/leave disposition |
+| [`fs-e2b`](../fs/fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
+| [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement managed process groups, stdio projection, and remote spill files over E2B Commands |
+
+The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it already delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world as `ctx.fs`. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, or E2B SDK buffers. The [decision record](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary and rejected expansion.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
new file mode 100644
index 0000000000..ab254eecad
--- /dev/null
+++ b/packages/e2b/README.zh.md
@@ -0,0 +1,13 @@
+# e2b/ — E2B 远程运行时家族
+
+[English](README.md) | 中文
+
+这是一个实验性提供方组合 POC，把文件系统和受管子进程环境放进同一个 E2B Linux 沙箱。共享所有者与功能适配器彼此分离，使每个远程提供方都等待同一个沙箱身份和生命周期。
+
+| 包（package） | ctx 键 | 职责 |
+|---|---|---|
+| [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建或重新连接一个沙箱，创建其工作目录与运行时目录，公开共享 SDK 句柄，并应用配置的 kill/pause/leave 处置方式 |
+| [`fs-e2b`](../fs/fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
+| [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 实现受管进程组、stdio 投影与远程 spill 文件 |
+
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它已经把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 与 `ctx.fs` 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）或 E2B SDK 缓冲。[决策记录](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)负责说明 POC 边界及未采纳的扩展方案。
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
new file mode 100644
index 0000000000..9255c21577
--- /dev/null
+++ b/packages/e2b/e2b/README.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 packages/e2b/e2b/README.md
+README.md: bf62cb7d4811ca92f263bd3d337fff9fe41ce223
+README.zh.md: 8c7603aa501a2481aba6dab1f22750056e43ad26
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
new file mode 100644
index 0000000000..bf62cb7d48
--- /dev/null
+++ b/packages/e2b/e2b/README.md
@@ -0,0 +1,50 @@
+# @deepseek-ai/dsh-e2b
+
+English | [中文](README.zh.md)
+
+Shared lifecycle owner for one E2B sandbox. Filesystem and subprocess adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`.
+
+## Configuration
+
+```yaml
+- id: e2b
+  name: '@deepseek-ai/dsh-e2b'
+  config:
+    cwd: /home/user/workspace
+    timeoutMs: 300000
+    onTimeout: pause
+    onDispose: kill
+
+- id: subprocess-e2b
+  name: '@deepseek-ai/dsh-subprocess-e2b'
+
+- id: fs-e2b
+  name: '@deepseek-ai/dsh-fs-e2b'
+```
+
+`apiKey` is optional and otherwise reads `E2B_API_KEY`; the key configures the host SDK connection and is never installed in the sandbox. `cwd` defaults to `/home/user/workspace` and must be an absolute POSIX path. `timeoutMs` defaults to five minutes. `onTimeout` is `pause` by default and accepts `pause | kill`; it applies only when this service creates a sandbox. Pause-on-timeout enables E2B auto-resume so the shared SDK handle wakes on its next operation. `onDispose` defaults to `kill` and accepts `kill | pause | leave`.
+
+Set `sandboxId` to reconnect a running or paused sandbox instead of creating one. E2B resumes a paused sandbox during connect; `template` is creation-only and cannot accompany `sandboxId`. Omitting `template` uses E2B's default base template.
+
+## Lifecycle and ownership
+
+Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, then sets that directory to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
+
+Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A newly created sandbox is killed when initial directory setup fails; a reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
+
+`pause` and `leave` retain remote filesystem and adapter artifacts for a later `sandboxId` connection, but a later harness process receives only a new SDK handle. The subprocess service still fulfills its seam contract by terminating managed groups before owner disposal; neither disposition recovers prior process objects, output cursors, or in-memory adapter locks.
+
+## Model Experience
+
+None, as this shared runtime owner registers no model-visible context; provider adapters and their consumers own any rendered effects.
+
+#### KV Cache effect
+
+No direct invalidation; this package does not contribute request tokens.
+
+## Known Limitations and Deferred Work
+
+- **This is not a whole-harness runtime** — Cordis services, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
+- **Retained sandboxes do not restore host handles** — reconnect preserves remote files and adapter artifacts, but cannot reconstruct subprocess handles, stream cursors, or mutation locks; managed subprocesses terminate when their service disposes.
+- **No deployment platform is configured** — templates, volumes, snapshots, network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
+- **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access also retains the template's policy.
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
new file mode 100644
index 0000000000..8c7603aa50
--- /dev/null
+++ b/packages/e2b/e2b/README.zh.md
@@ -0,0 +1,50 @@
+# @deepseek-ai/dsh-e2b
+
+[English](README.md) | 中文
+
+一个 E2B 沙箱的共享生命周期所有者。文件系统与进程管理适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`。
+
+## 配置
+
+```yaml
+- id: e2b
+  name: '@deepseek-ai/dsh-e2b'
+  config:
+    cwd: /home/user/workspace
+    timeoutMs: 300000
+    onTimeout: pause
+    onDispose: kill
+
+- id: subprocess-e2b
+  name: '@deepseek-ai/dsh-subprocess-e2b'
+
+- id: fs-e2b
+  name: '@deepseek-ai/dsh-fs-e2b'
+```
+
+`apiKey` 可省略；省略时读取 `E2B_API_KEY`。该密钥只配置宿主 SDK 连接，绝不会安装进沙箱。`cwd` 默认为 `/home/user/workspace`，并且必须是绝对 POSIX 路径。`timeoutMs` 默认为 5 分钟。`onTimeout` 默认为 `pause`，接受 `pause | kill`；它只在本服务创建沙箱时生效。超时时 pause 会启用 E2B 自动恢复，使共享 SDK 句柄在下一次操作时唤醒。`onDispose` 默认为 `kill`，接受 `kill | pause | leave`。
+
+设置 `sandboxId` 可重新连接正在运行或已经暂停的沙箱，而不是创建新沙箱。连接时，E2B 会恢复已经暂停的沙箱；`template` 仅用于创建，不能与 `sandboxId` 同时使用。省略 `template` 时使用 E2B 的默认基础模板。
+
+## 生命周期与所有权
+
+构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
+
+资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。新建沙箱的初始目录设置失败时，服务会终止该沙箱；重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+
+`pause` 和 `leave` 会保留远程文件系统及适配器产物，供稍后的 `sandboxId` 连接使用，但后续 harness 进程只会获得新的 SDK 句柄。进程管理服务仍会履行其 seam 契约，在所有者释放前终止受管进程组；这两种处置方式都不会恢复先前的进程对象、输出游标或内存中的适配器锁。
+
+## 模型体验
+
+无。本共享运行时所有者不注册模型可见上下文；提供方适配器及其消费方拥有所有渲染效果。
+
+#### KV Cache 影响
+
+不会直接失效；本包不会贡献请求 token。
+
+## 已知限制与延后工作
+
+- **这不是完整的 harness 运行时**：Cordis 服务、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
+- **保留的沙箱不会恢复宿主句柄**：重新连接会保留远程文件和适配器产物，但无法重建进程管理句柄、流游标或变更锁；进程管理服务 dispose 时会终止受管子进程。
+- **没有配置部署平台**：模板、卷、快照、网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
+- **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用模板的策略。
diff --git a/packages/e2b/e2b/package.json b/packages/e2b/e2b/package.json
new file mode 100644
index 0000000000..7ecc5fabed
--- /dev/null
+++ b/packages/e2b/e2b/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@deepseek-ai/dsh-e2b",
+  "description": "Shared E2B sandbox lifecycle for DeepSeek Harness provider adapters",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "e2b": "2.29.1",
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
new file mode 100644
index 0000000000..29cbf1dc53
--- /dev/null
+++ b/packages/e2b/e2b/src/index.ts
@@ -0,0 +1,240 @@
+/**
+ * Shared ownership of one E2B sandbox. Capability adapters await the same SDK
+ * handle, so filesystem and process operations inhabit one remote Linux world.
+ * @module @deepseek-ai/dsh-e2b
+ */
+
+import { posix } from 'node:path'
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import { Sandbox } from 'e2b'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+export {
+  CommandExitError,
+  FileNotFoundError,
+  FileType,
+  Sandbox,
+  SandboxError,
+  SandboxNotFoundError,
+  TimeoutError,
+} from 'e2b'
+export type { CommandHandle, CommandResult, EntryInfo } from 'e2b'
+
+/** Opaque E2B sandbox identity used for reconnecting a later harness process. */
+export type E2BSandboxId = Branded<'E2BSandboxId'>
+
+/**
+ * Brand an SDK sandbox id after E2B has created or resolved it.
+ * @param value - E2B's opaque sandbox id.
+ * @returns the same string with the harness brand.
+ */
+export function E2BSandboxId(value: string): E2BSandboxId {
+  return value as E2BSandboxId
+}
+
+/**
+ * Quote one opaque argument for the SDK's unavoidable `/bin/bash -l -c` layer.
+ * @param value - Exact argument value to preserve.
+ * @returns A single shell word with no interpolation.
+ */
+export function quoteE2BShellArg(value: string): string {
+  return `'${value.replaceAll('\'', "'\"'\"'")}'`
+}
+
+/** Action taken on the owned sandbox when the Cordis service is disposed. */
+export type E2BDisposeMode = 'kill' | 'pause' | 'leave'
+
+/** Action E2B takes when a newly created sandbox reaches its lifetime. */
+export type E2BTimeoutMode = 'kill' | 'pause'
+
+/** Configuration for the shared E2B sandbox owner. */
+export interface Config {
+  /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */
+  apiKey?: string
+  /** Existing sandbox to reconnect instead of creating a new one. */
+  sandboxId?: string
+  /** Template name or id for a newly created sandbox. */
+  template?: string
+  /** Shared remote working directory, created before adapters receive the sandbox. */
+  cwd?: string
+  /** E2B sandbox lifetime in milliseconds. */
+  timeoutMs?: number
+  /** E2B action when a newly created sandbox reaches `timeoutMs`. */
+  onTimeout?: E2BTimeoutMode
+  /** Disposal policy; `pause` and `leave` retain remote state for reconnect. */
+  onDispose?: E2BDisposeMode
+}
+
+interface ResolvedConfig {
+  apiKey: string
+  cwd: string
+  timeoutMs: number
+  onTimeout: E2BTimeoutMode
+  onDispose: E2BDisposeMode
+  sandboxId?: string
+  template?: string
+}
+
+interface SchemaResolvedConfig extends Config {
+  cwd: string
+  timeoutMs: number
+  onTimeout: E2BTimeoutMode
+  onDispose: E2BDisposeMode
+}
+
+declare module 'cordis' {
+  interface Context {
+    e2b: E2BSandboxService
+  }
+}
+
+/**
+ * Owns one lazily consumable E2B SDK handle and its final kill/pause/leave
+ * decision. The connection begins at plugin construction; adapters await
+ * {@link getSandbox} before their first operation.
+ */
+export class E2BSandboxService extends Service {
+  static Config: z<Config> = z.object({
+    apiKey: z.string(),
+    sandboxId: z.string(),
+    template: z.string(),
+    cwd: z.string().default('/home/user/workspace'),
+    timeoutMs: z.number().default(300_000),
+    onTimeout: z.union(['kill', 'pause'] as const).default('pause'),
+    onDispose: z.union(['kill', 'pause', 'leave'] as const).default('kill'),
+  })
+
+  /** Validated remote working directory shared by provider adapters. */
+  readonly cwd: string
+  /** Remote directory reserved for adapter-owned process and terminal state. */
+  readonly runtimeRoot: string
+  /** Whether this service creates a sandbox rather than reconnecting one. */
+  readonly created: boolean
+  /** Configured action when a newly created sandbox reaches its lifetime. */
+  readonly timeoutMode: E2BTimeoutMode
+  /** Configured final sandbox disposition. */
+  readonly disposeMode: E2BDisposeMode
+  /** Sandbox id once E2B has created or resolved the remote runtime. */
+  readonly sandboxId: Promise<E2BSandboxId>
+
+  private readonly config: ResolvedConfig
+  private readonly ready: Promise<Sandbox>
+  private disposed = false
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'e2b')
+    // Schemastery fills these fields before construction; the type does not encode that step.
+    const resolved = config as SchemaResolvedConfig
+    const apiKey = config.apiKey ?? process.env.E2B_API_KEY
+    this.config = {
+      apiKey: apiKey ?? '',
+      cwd: resolved.cwd,
+      timeoutMs: resolved.timeoutMs,
+      onTimeout: resolved.onTimeout,
+      onDispose: resolved.onDispose,
+      ...(config.sandboxId !== undefined ? { sandboxId: config.sandboxId } : {}),
+      ...(config.template !== undefined ? { template: config.template } : {}),
+    }
+    this.validate()
+    this.cwd = this.config.cwd
+    this.runtimeRoot = posix.join(this.cwd, '.dsh-e2b')
+    this.created = this.config.sandboxId === undefined
+    this.timeoutMode = this.config.onTimeout
+    this.disposeMode = this.config.onDispose
+    this.ready = this.open()
+    // A deployment may load the owner before any adapter uses it. Keep a
+    // failed eager connection observed; getSandbox() still returns the error.
+    void this.ready.catch(() => {})
+    this.sandboxId = this.ready.then(sandbox => E2BSandboxId(sandbox.sandboxId))
+    void this.sandboxId.catch(() => {})
+
+    ctx.effect(() => async () => {
+      this.disposed = true
+      let sandbox: Sandbox
+      try {
+        sandbox = await this.ready
+      } catch {
+        // Connection creation already failed and is exposed by getSandbox();
+        // there is no remote resource for teardown to own.
+        return
+      }
+      switch (this.config.onDispose) {
+        case 'kill':
+          await sandbox.kill()
+          return
+        case 'pause': {
+          await sandbox.pause()
+          return
+        }
+        case 'leave':
+          return
+      }
+    }, 'e2b sandbox teardown')
+  }
+
+  /**
+   * Return the shared live SDK handle.
+   * @returns the created or reconnected sandbox after the configured cwd exists.
+   * @throws when E2B rejects creation/reconnection or the service is disposing.
+   */
+  async getSandbox(): Promise<Sandbox> {
+    if (this.disposed) throw new Error('E2B sandbox service is disposing')
+    return await this.ready
+  }
+
+  private validate(): void {
+    if (this.config.apiKey.length === 0) {
+      throw new Error('dsh-e2b: configure apiKey or set E2B_API_KEY')
+    }
+    if (!posix.isAbsolute(this.config.cwd)) {
+      throw new Error(`dsh-e2b: cwd must be an absolute Linux path: ${this.config.cwd}`)
+    }
+    if (!Number.isFinite(this.config.timeoutMs) || this.config.timeoutMs <= 0) {
+      throw new Error('dsh-e2b: timeoutMs must be a positive finite number')
+    }
+    if (this.config.sandboxId !== undefined && this.config.sandboxId.length === 0) {
+      throw new Error('dsh-e2b: sandboxId must be non-empty when provided')
+    }
+    if (this.config.sandboxId !== undefined && this.config.template !== undefined) {
+      throw new Error('dsh-e2b: template applies only when creating; omit it when sandboxId reconnects')
+    }
+  }
+
+  private async open(): Promise<Sandbox> {
+    const connection = {
+      apiKey: this.config.apiKey,
+      timeoutMs: this.config.timeoutMs,
+    }
+    const sandbox = this.config.sandboxId === undefined
+      ? this.config.template === undefined
+        ? await Sandbox.create({
+          ...connection,
+          secure: true,
+          lifecycle: { onTimeout: this.config.onTimeout, autoResume: this.config.onTimeout === 'pause' },
+        })
+        : await Sandbox.create(this.config.template, {
+          ...connection,
+          secure: true,
+          lifecycle: { onTimeout: this.config.onTimeout, autoResume: this.config.onTimeout === 'pause' },
+        })
+      : await Sandbox.connect(this.config.sandboxId, connection)
+    try {
+      await sandbox.files.makeDir(this.cwd)
+      await sandbox.files.makeDir(this.runtimeRoot)
+      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.runtimeRoot)}`)
+      return sandbox
+    } catch (error: unknown) {
+      if (this.created) {
+        try {
+          await sandbox.kill()
+        } catch (_cleanupFailure) {
+          // The setup failure remains authoritative; E2B will still apply the configured lifetime.
+        }
+      }
+      throw error
+    }
+  }
+}
+
+export default E2BSandboxService
diff --git a/packages/e2b/e2b/src/invariant.ts b/packages/e2b/e2b/src/invariant.ts
new file mode 100644
index 0000000000..891cabb2db
--- /dev/null
+++ b/packages/e2b/e2b/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-e2b`.
+ * @module @deepseek-ai/dsh-e2b/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'e2b-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: sandbox creation and teardown have one SDK promise and
+ * no independent event or mutable-data relationship to cross-check.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
new file mode 100644
index 0000000000..8c01fae7b4
--- /dev/null
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -0,0 +1,39 @@
+import { access } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+import { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+
+const fixtureRoot = fileURLToPath(new URL('../../../../examples/headless-agent/tests/fixtures/e2b/e2b/', import.meta.url))
+const binScript = join(fixtureRoot, 'bin.ts')
+const configPath = join(fixtureRoot, 'cordis.yml')
+const tsconfigPath = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+
+describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
+  it('shares remote state across FS and Bash without creating host workspace files', async () => {
+    const { stdout, stderr } = await runLoaderSmoke({
+      label: 'E2B composition',
+      tempDirPrefix: 'dsh-e2b-composition-',
+      binScript,
+      libBinScript: binScript,
+      configPath,
+      tsconfigPath,
+      processTimeoutMs: 90_000,
+      inspect: async (cwd) => {
+        await expect(access(join(cwd, 'from-fs.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
+        await expect(access(join(cwd, 'from-bash.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
+      },
+    })
+
+    expect(stderr).toBe('')
+    const output = JSON.parse(stdout) as Record<string, unknown>
+    expect(output).toMatchObject({
+      bashRead: 'written-by-fs\n',
+      fsRead: 'written-by-bash\n',
+    })
+    const apiKey = process.env.E2B_API_KEY
+    if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
+    await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
+  }, 105_000)
+})
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
new file mode 100644
index 0000000000..c842731f5c
--- /dev/null
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -0,0 +1,218 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import type { Sandbox as SandboxType } from 'e2b'
+import E2BSandboxService, {
+  E2BSandboxId,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import * as E2BInvariant from '../src/invariant.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+const sdk = vi.hoisted(() => ({
+  create: vi.fn(),
+  connect: vi.fn(),
+}))
+
+vi.mock('e2b', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('e2b')>()
+  // The mock replaces only the SDK's static factory surface and is never constructed.
+  // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+  class FakeSandbox {
+    static create(...args: unknown[]): unknown {
+      return sdk.create(...args)
+    }
+
+    static connect(...args: unknown[]): unknown {
+      return sdk.connect(...args)
+    }
+  }
+  return { ...actual, Sandbox: FakeSandbox }
+})
+
+interface SandboxFixture {
+  sandbox: SandboxType
+  makeDir: ReturnType<typeof vi.fn>
+  run: ReturnType<typeof vi.fn>
+  kill: ReturnType<typeof vi.fn>
+  pause: ReturnType<typeof vi.fn>
+}
+
+function fakeSandbox(id = 'sandbox-1'): SandboxFixture {
+  const makeDir = vi.fn().mockResolvedValue(true)
+  const run = vi.fn().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
+  const kill = vi.fn().mockResolvedValue(undefined)
+  const pause = vi.fn().mockResolvedValue(true)
+  const sandbox = {
+    sandboxId: id,
+    files: { makeDir },
+    commands: { run },
+    kill,
+    pause,
+  } as unknown as SandboxType
+  return { sandbox, makeDir, run, kill, pause }
+}
+
+beforeEach(() => {
+  sdk.create.mockReset()
+  sdk.connect.mockReset()
+  vi.unstubAllEnvs()
+})
+
+describe('E2BSandboxService', () => {
+  it('creates one protected shared sandbox and kills it on default disposal', async () => {
+    const fixture = fakeSandbox()
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    const service = ctx.e2b
+    await expect(service.getSandbox()).resolves.toBe(fixture.sandbox)
+    await expect(service.sandboxId).resolves.toBe(E2BSandboxId('sandbox-1'))
+    expect(service.cwd).toBe('/home/user/workspace')
+    expect(service.runtimeRoot).toBe('/home/user/workspace/.dsh-e2b')
+    expect(service.created).toBe(true)
+    expect(service.timeoutMode).toBe('pause')
+    expect(service.disposeMode).toBe('kill')
+    expect(sdk.create).toHaveBeenCalledWith({
+      apiKey: 'test-key',
+      timeoutMs: 300_000,
+      secure: true,
+      lifecycle: { onTimeout: 'pause', autoResume: true },
+    })
+    expect(fixture.makeDir).toHaveBeenNthCalledWith(1, '/home/user/workspace')
+    expect(fixture.makeDir).toHaveBeenNthCalledWith(2, '/home/user/workspace/.dsh-e2b')
+    expect(fixture.run).toHaveBeenCalledWith("chmod 700 -- '/home/user/workspace/.dsh-e2b'")
+
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+    await expect(service.getSandbox()).rejects.toThrow(/disposing/)
+  })
+
+  it('creates from a template, honors timeout and pause policies, and reads the key from the environment', async () => {
+    vi.stubEnv('E2B_API_KEY', 'environment-key')
+    const fixture = fakeSandbox('template-sandbox')
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, {
+      template: 'agent-template',
+      cwd: '/workspace/project',
+      timeoutMs: 60_000,
+      onTimeout: 'kill',
+      onDispose: 'pause',
+    })
+    await ctx.e2b.getSandbox()
+
+    expect(sdk.create).toHaveBeenCalledWith('agent-template', {
+      apiKey: 'environment-key',
+      timeoutMs: 60_000,
+      secure: true,
+      lifecycle: { onTimeout: 'kill', autoResume: false },
+    })
+    await fiber.dispose()
+    expect(fixture.pause).toHaveBeenCalledOnce()
+    expect(fixture.kill).not.toHaveBeenCalled()
+  })
+
+  it('accepts an already-paused result during configured pause disposal', async () => {
+    const fixture = fakeSandbox()
+    fixture.pause.mockResolvedValue(false)
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', onDispose: 'pause' })
+    await ctx.e2b.getSandbox()
+    await fiber.dispose()
+    expect(fixture.pause).toHaveBeenCalledOnce()
+  })
+
+  it('reconnects without applying creation lifecycle options and can leave state running', async () => {
+    const fixture = fakeSandbox('existing')
+    sdk.connect.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, {
+      apiKey: 'test-key',
+      sandboxId: 'existing',
+      timeoutMs: 90_000,
+      onDispose: 'leave',
+    })
+    await ctx.e2b.getSandbox()
+
+    expect(ctx.e2b.created).toBe(false)
+    expect(sdk.connect).toHaveBeenCalledWith('existing', { apiKey: 'test-key', timeoutMs: 90_000 })
+    expect(sdk.create).not.toHaveBeenCalled()
+    await fiber.dispose()
+    expect(fixture.kill).not.toHaveBeenCalled()
+    expect(fixture.pause).not.toHaveBeenCalled()
+  })
+
+  it('kills a newly created sandbox when remote directory setup fails', async () => {
+    const fixture = fakeSandbox()
+    fixture.makeDir.mockRejectedValueOnce(new Error('setup failed'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('setup failed')
+    await expect(ctx.e2b.sandboxId).rejects.toThrow('setup failed')
+    expect(fixture.kill).toHaveBeenCalledOnce()
+    await fiber.dispose()
+  })
+
+  it('preserves the setup failure even when cleanup also fails', async () => {
+    const fixture = fakeSandbox()
+    fixture.run.mockRejectedValueOnce(new Error('chmod failed'))
+    fixture.kill.mockRejectedValueOnce(new Error('cleanup failed'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('chmod failed')
+  })
+
+  it('does not kill a reconnected sandbox when setup fails', async () => {
+    const fixture = fakeSandbox()
+    fixture.makeDir.mockRejectedValueOnce(new Error('setup failed'))
+    sdk.connect.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', sandboxId: 'existing' })
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('setup failed')
+    expect(fixture.kill).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    [{ apiKey: '' }, /configure apiKey/],
+    [{ apiKey: 'x', cwd: 'relative' }, /absolute Linux path/],
+    [{ apiKey: 'x', timeoutMs: 0 }, /positive finite/],
+    [{ apiKey: 'x', sandboxId: '' }, /sandboxId must be non-empty/],
+    [{ apiKey: 'x', sandboxId: 'one', template: 'two' }, /template applies only/],
+  ] as const)('fails self-contained configuration before opening E2B: %j', async (config, message) => {
+    vi.stubEnv('E2B_API_KEY', '')
+    const ctx = new Context()
+    await expect(ctx.plugin(E2BSandboxService, config)).rejects.toThrow(message)
+    expect(sdk.create).not.toHaveBeenCalled()
+    expect(sdk.connect).not.toHaveBeenCalled()
+  })
+
+  it('requires a key when both config and the environment omit it', async () => {
+    const original = process.env.E2B_API_KEY
+    delete process.env.E2B_API_KEY
+    try {
+      const ctx = new Context()
+      await expect(ctx.plugin(E2BSandboxService, {})).rejects.toThrow(/configure apiKey/)
+    } finally {
+      if (original === undefined) delete process.env.E2B_API_KEY
+      else process.env.E2B_API_KEY = original
+    }
+  })
+})
+
+describe('E2B helpers and invariant companion', () => {
+  it('quotes opaque shell arguments without interpolation', () => {
+    expect(quoteE2BShellArg("a'b $HOME")).toBe("'a'\"'\"'b $HOME'")
+  })
+
+  it('registers the package-owned empty invariant installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/e2b/e2b/tsconfig.json b/packages/e2b/e2b/tsconfig.json
new file mode 100644
index 0000000000..5890a41d66
--- /dev/null
+++ b/packages/e2b/e2b/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index c1a381cb81..eabb6a602e 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: b6adabd5744cb2b3dcee78b71815f8e95ba780f1
-README.zh.md: 0841f538932452921d2b0d7d9534f023672f241d
+README.md: 8ac8807cc9ca4b5cc31b686cef9796a8e42b7f81
+README.zh.md: 49705790cc0cdf1f7199251e09af0af01f704efb
diff --git a/packages/fs/README.md b/packages/fs/README.md
index b6adabd574..460af7c53b 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -8,12 +8,13 @@ The filesystem stack: a provider seam (execution-world paths, bounded text IO, a
 |---|---|---|
 | `fs/` | Provider seam: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
 | `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
+| `fs-e2b/` | E2B-backed `FileSystem` implementation sharing the remote runtime owned by `ctx.e2b` | (registers `ctx.fs`) |
 | `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
 | `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
 | `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas — `fs-sandbox` is the first such replacement (an in-process path fence over the shared sandbox mode; see [the cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote runtime shared with the E2B subprocess provider ([POC decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
 
 ## No timeouts on file IO
 
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 0841f53893..5f70e3cb50 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -8,12 +8,13 @@
 |---|---|---|
 | `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
 | `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
+| `fs-e2b/` | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
 | `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
 | `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
 | `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema；`fs-sandbox` 是第一个这样的替代实现（基于共享沙箱模式的进程内路径围栏；见[跨能力族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程运行时中（[POC 决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
 
 ## 文件 I/O 不设超时
 
diff --git a/packages/fs/fs-e2b/README.i18n.yaml b/packages/fs/fs-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..d3ea2786b2
--- /dev/null
+++ b/packages/fs/fs-e2b/README.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 packages/fs/fs-e2b/README.md
+README.md: 2b23884e345e7c39b0559465afa0bc588699b70a
+README.zh.md: 1a9a174ac90c59b68b02887303f58ee2a99dc72e
diff --git a/packages/fs/fs-e2b/README.md b/packages/fs/fs-e2b/README.md
new file mode 100644
index 0000000000..2b23884e34
--- /dev/null
+++ b/packages/fs/fs-e2b/README.md
@@ -0,0 +1,29 @@
+# @deepseek-ai/dsh-fs-e2b
+
+English | [中文](README.zh.md)
+
+E2B implementation of the [`@deepseek-ai/dsh-fs`](../fs/README.md) provider seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
+
+## Behavior
+
+- **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; `realpath -m` supplies canonical target identity without requiring the final file to exist. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
+- **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
+- **Atomic mutations** — writes upload a mode-`0600` temporary sibling, preserve an existing file's POSIX mode, and publish through same-directory Linux `mv -f`. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
+- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at SDK request boundaries; a successful rename is the commit point.
+
+The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
+
+## Model Experience
+
+Indirectly, through [`dsh-tool-fs`](../tool-fs/README.md), which renders remote UTF-8 content, directory results, mutation acknowledgements, and provider errors while E2B identity and transport remain internal.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **No host synchronization** — an empty E2B cwd stays empty until a tool, command, template, or external process populates it; local files are neither uploaded nor reflected back.
+- **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
+- **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
+- **Custom templates must support the used Linux and envd features** — `realpath`, `chmod`, `mv`, same-filesystem POSIX rename, streaming reads, and file metadata extended attributes are required; unsupported templates fail rather than degrade silently.
diff --git a/packages/fs/fs-e2b/README.zh.md b/packages/fs/fs-e2b/README.zh.md
new file mode 100644
index 0000000000..1a9a174ac9
--- /dev/null
+++ b/packages/fs/fs-e2b/README.zh.md
@@ -0,0 +1,29 @@
+# @deepseek-ai/dsh-fs-e2b
+
+[English](README.md) | 中文
+
+[`@deepseek-ai/dsh-fs`](../fs/README.md) 提供方 seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
+
+## 行为
+
+- **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；`realpath -m` 提供规范化目标身份，且不要求最终文件存在。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
+- **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
+- **原子变更**：写入会上传 mode 为 `0600` 的同级临时文件，保留现有文件的 POSIX mode，并通过同目录 Linux `mv -f` 发布。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
+- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。
+
+该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
+
+## 模型体验
+
+通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接影响模型；该工具会渲染远程 UTF-8 内容、目录结果、变更确认和提供方错误，而 E2B 身份及传输保持内部实现。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由具名消费方负责。
+
+## 已知限制与延后工作
+
+- **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令、模板或外部进程填充它；本地文件既不会上传，也不会同步回本地。
+- **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
+- **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
+- **自定义模板必须支持所用的 Linux 与 envd 功能**：必须支持 `realpath`、`chmod`、`mv`、同一文件系统内的 POSIX rename、流式读取和文件元数据扩展属性；不支持的模板会失败，而不会静默降级。
diff --git a/packages/fs/fs-e2b/package.json b/packages/fs/fs-e2b/package.json
new file mode 100644
index 0000000000..cc96cba6c9
--- /dev/null
+++ b/packages/fs/fs-e2b/package.json
@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-fs-e2b",
+  "description": "E2B filesystem implementation for DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-fs": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/fs/fs-e2b/src/index.ts b/packages/fs/fs-e2b/src/index.ts
new file mode 100644
index 0000000000..020b0f4857
--- /dev/null
+++ b/packages/fs/fs-e2b/src/index.ts
@@ -0,0 +1,423 @@
+/**
+ * E2B implementation of the filesystem provider seam. Paths, contents, and
+ * atomic staging files remain inside the shared remote sandbox.
+ * @module @deepseek-ai/dsh-fs-e2b
+ */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { posix } from 'node:path'
+import { FileSystem, FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
+import type {
+  FsDirEntry,
+  FsEditOutcome,
+  FsEditRequest,
+  FsInfo,
+  FsPathInfo,
+  FsTarget,
+  FsWriteIntent,
+  FsWriteOutcome,
+} from '@deepseek-ai/dsh-fs'
+import {
+  CommandExitError,
+  FileNotFoundError,
+  FileType,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import type { EntryInfo, Sandbox } from '@deepseek-ai/dsh-e2b'
+
+const VERSION_METADATA_KEY = 'dsh-version'
+const BINARY_SAMPLE_BYTES = 8192
+
+function assertNotAborted(signal: AbortSignal | undefined, operation: string): void {
+  if (signal?.aborted === true) throw new FsError(`${operation} aborted`, 'FS_ABORTED')
+}
+
+function normalizeLineEndings(value: string): string {
+  return value.replaceAll('\r\n', '\n')
+}
+
+function detectsCrlf(value: string): boolean {
+  const sample = value.slice(0, 4096)
+  const crlf = sample.split('\r\n').length - 1
+  const lf = sample.split('\n').length - 1 - crlf
+  return crlf > lf
+}
+
+function restoreLineEndings(value: string, crlf: boolean): string {
+  return crlf ? normalizeLineEndings(value).replaceAll('\n', '\r\n') : value
+}
+
+function decodeText(bytes: Uint8Array, displayPath: string, binarySampleBytes: number): string {
+  if (bytes.subarray(0, binarySampleBytes).includes(0)) {
+    throw new FsError(`cannot read "${displayPath}": binary file`, 'FS_NOT_TEXT')
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  } catch (error: unknown) {
+    throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
+  }
+}
+
+function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
+
+function entryType(entry: EntryInfo): FsInfo['type'] {
+  switch (entry.type) {
+    case FileType.FILE:
+      return 'file'
+    case FileType.DIR:
+      return 'directory'
+    default:
+      return 'other'
+  }
+}
+
+function entryVersion(entry: EntryInfo): ReturnType<typeof FsVersion> {
+  const facts = JSON.stringify([
+    entry.metadata?.[VERSION_METADATA_KEY],
+    entry.path,
+    entry.type,
+    entry.size,
+    entry.mode,
+    entry.modifiedTime?.toISOString(),
+    entry.symlinkTarget,
+  ])
+  return FsVersion(`e2b:${createHash('sha256').update(facts).digest('hex')}`)
+}
+
+function mapError(error: unknown, operation: string, displayPath: string, signal?: AbortSignal): FsError {
+  if (error instanceof FsError) return error
+  if (signal?.aborted === true || (error instanceof DOMException && error.name === 'AbortError')) {
+    return new FsError(`${operation} aborted`, 'FS_ABORTED', { cause: error })
+  }
+  if (error instanceof FileNotFoundError) {
+    return new FsError(`cannot ${operation} "${displayPath}": not found`, 'FS_NOT_FOUND', { cause: error })
+  }
+  if (/permission denied|operation not permitted/i.test(String(error))) {
+    return new FsError(`cannot ${operation} "${displayPath}": permission denied`, 'FS_PERMISSION_DENIED', { cause: error })
+  }
+  return new FsError(`cannot ${operation} "${displayPath}": ${String(error)}`, 'FS_IO_ERROR', { cause: error })
+}
+
+function literalEdit(content: string, request: FsEditRequest, displayPath: string): string {
+  const oldString = normalizeLineEndings(request.oldString)
+  const newString = normalizeLineEndings(request.newString)
+  if (oldString.length === 0) {
+    throw new FsError(`cannot edit "${displayPath}": old_string must be non-empty`, 'FS_EDIT_NOT_FOUND')
+  }
+  let matches = 0
+  let offset = 0
+  while (true) {
+    const found = content.indexOf(oldString, offset)
+    if (found < 0) break
+    matches += 1
+    offset = found + oldString.length
+  }
+  if (matches === 0) throw new FsError(`cannot edit "${displayPath}": old_string was not found`, 'FS_EDIT_NOT_FOUND')
+  if (!request.replaceAll && matches !== 1) {
+    throw new FsError(`cannot edit "${displayPath}": old_string matched ${matches} times`, 'FS_AMBIGUOUS_EDIT')
+  }
+  return request.replaceAll ? content.split(oldString).join(newString) : content.replace(oldString, newString)
+}
+
+/** Remote filesystem backend sharing the sandbox owned by `ctx.e2b`. */
+export class E2BFileSystem extends FileSystem {
+  static inject = ['e2b']
+
+  private readonly locks = new Map<string, Promise<unknown>>()
+
+  override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget> {
+    assertNotAborted(opts?.signal, 'resolve')
+    if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')
+    const displayPath = posix.resolve(opts?.cwd ?? this.ctx.e2b.cwd, path)
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const targetKey = await this.canonicalPath(sandbox, displayPath, opts?.signal)
+      assertNotAborted(opts?.signal, 'resolve')
+      return { targetKey: FsTargetKey(targetKey), displayPath }
+    } catch (error: unknown) {
+      throw mapError(error, 'resolve', displayPath, opts?.signal)
+    }
+  }
+
+  override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
+    assertNotAborted(signal, 'stat')
+    const entry = await this.probe(String(target.targetKey), target.displayPath, signal)
+    if (entry === undefined) return undefined
+    return {
+      version: entryVersion(entry),
+      type: entryType(entry),
+      ...(entry.type === FileType.FILE ? { size: entry.size } : {}),
+    }
+  }
+
+  override async lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined> {
+    assertNotAborted(signal, 'lstat')
+    if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')
+    const displayPath = posix.resolve(opts?.cwd ?? this.ctx.e2b.cwd, path)
+    const entry = await this.probe(displayPath, displayPath, signal)
+    if (entry === undefined) return undefined
+    const type = entry.symlinkTarget !== undefined
+      ? 'symlink' as const
+      : entry.type === FileType.FILE
+        ? 'file' as const
+        : entry.type === FileType.DIR
+          ? 'directory' as const
+          : 'other' as const
+    return {
+      version: entryVersion(entry),
+      type,
+      ...(entry.type === FileType.FILE ? { size: entry.size } : {}),
+    }
+  }
+
+  override async readText(target: FsTarget, signal?: AbortSignal): Promise<string> {
+    const sandbox = await this.ctx.e2b.getSandbox()
+    await this.requireRegular(target, signal)
+    try {
+      const bytes = await sandbox.files.read(String(target.targetKey), { format: 'bytes', ...signalOpts(signal) })
+      assertNotAborted(signal, 'read')
+      return decodeText(bytes, target.displayPath, BINARY_SAMPLE_BYTES)
+    } catch (error: unknown) {
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+  }
+
+  override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
+    const sandbox = await this.ctx.e2b.getSandbox()
+    await this.requireRegular(target, signal)
+    let stream: ReadableStream<Uint8Array>
+    try {
+      stream = await sandbox.files.read(String(target.targetKey), { format: 'stream', ...signalOpts(signal) })
+    } catch (error: unknown) {
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+    const displayPath = target.displayPath
+    return {
+      async *[Symbol.asyncIterator](): AsyncGenerator<string> {
+        const reader = stream.getReader()
+        const decoder = new TextDecoder('utf-8', { fatal: true })
+        let sampledBytes = 0
+        try {
+          while (true) {
+            assertNotAborted(signal, 'read')
+            const next = await reader.read()
+            if (next.done) break
+            if (sampledBytes < BINARY_SAMPLE_BYTES) {
+              const sample = next.value.subarray(0, BINARY_SAMPLE_BYTES - sampledBytes)
+              if (sample.includes(0)) throw new FsError(`cannot read "${displayPath}": binary file`, 'FS_NOT_TEXT')
+              sampledBytes += sample.length
+            }
+            let text: string
+            try {
+              text = decoder.decode(next.value, { stream: true })
+            } catch (error: unknown) {
+              throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
+            }
+            if (text.length > 0) yield text
+          }
+          try {
+            decoder.decode()
+          } catch (error: unknown) {
+            throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
+          }
+        } catch (error: unknown) {
+          throw mapError(error, 'read', displayPath, signal)
+        } finally {
+          reader.releaseLock()
+        }
+      },
+    }
+  }
+
+  override async listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]> {
+    const info = await this.stat(target, signal)
+    if (info === undefined) throw new FsError(`cannot list "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+    if (info.type !== 'directory') throw new FsError(`cannot list "${target.displayPath}": not a directory`, 'FS_NOT_DIRECTORY')
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const listed = await sandbox.files.list(String(target.targetKey), { depth: 1, ...signalOpts(signal) })
+      const entries = await Promise.all(listed.map(async (entry): Promise<FsDirEntry> => {
+        const displayPath = posix.join(target.displayPath, entry.name)
+        const canonical = await this.canonicalPath(sandbox, entry.path, signal)
+        const resolved = await this.probe(canonical, displayPath, signal)
+        return {
+          name: entry.name,
+          type: resolved === undefined ? 'other' : entryType(resolved),
+          target: { targetKey: FsTargetKey(canonical), displayPath },
+          ...(resolved !== undefined ? { version: entryVersion(resolved) } : {}),
+          ...(resolved?.type === FileType.FILE ? { size: resolved.size } : {}),
+        }
+      }))
+      return entries.sort((left, right) => left.name.localeCompare(right.name))
+    } catch (error: unknown) {
+      throw mapError(error, 'list', target.displayPath, signal)
+    }
+  }
+
+  override async writeText(
+    target: FsTarget,
+    content: string,
+    expected?: FsWriteIntent,
+    signal?: AbortSignal,
+  ): Promise<FsWriteOutcome> {
+    return this.withLock(String(target.targetKey), async () => {
+      const existing = await this.probe(String(target.targetKey), target.displayPath, signal)
+      if (existing !== undefined && entryType(existing) !== 'file') {
+        throw new FsError(`cannot write "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+      }
+      this.checkWriteIntent(existing, expected, target)
+      const before = existing === undefined ? null : await this.readForDiff(target, signal)
+      const version = await this.writeAtomic(target, content, existing, signal)
+      return {
+        operation: existing === undefined ? 'create' : 'update',
+        version,
+        before,
+        after: normalizeLineEndings(content),
+      }
+    })
+  }
+
+  override async editText(
+    target: FsTarget,
+    edit: FsEditRequest,
+    expected?: { version: ReturnType<typeof FsVersion> },
+    signal?: AbortSignal,
+  ): Promise<FsEditOutcome> {
+    return this.withLock(String(target.targetKey), async () => {
+      const existing = await this.probe(String(target.targetKey), target.displayPath, signal)
+      if (existing === undefined) {
+        throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
+      }
+      if (entryType(existing) !== 'file') {
+        throw new FsError(`cannot edit "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+      }
+      if (expected !== undefined && entryVersion(existing) !== expected.version) {
+        throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
+      }
+      const raw = await this.readForEdit(target, signal)
+      const before = normalizeLineEndings(raw)
+      const after = literalEdit(before, edit, target.displayPath)
+      const storage = restoreLineEndings(after, detectsCrlf(raw))
+      const version = await this.writeAtomic(target, storage, existing, signal)
+      return { version, before, after }
+    })
+  }
+
+  private async withLock<T>(targetKey: string, operation: () => Promise<T>): Promise<T> {
+    const prior = this.locks.get(targetKey) ?? Promise.resolve()
+    const run = prior.then(operation, operation)
+    const tail = run.then(() => undefined, () => undefined)
+    this.locks.set(targetKey, tail)
+    try {
+      return await run
+    } finally {
+      if (this.locks.get(targetKey) === tail) this.locks.delete(targetKey)
+    }
+  }
+
+  private async canonicalPath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
+    try {
+      const result = await sandbox.commands.run(`realpath -m -- ${quoteE2BShellArg(path)}`, signalOpts(signal))
+      return result.stdout.replace(/\n$/, '')
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError) throw new Error(error.stderr || error.message, { cause: error })
+      throw error
+    }
+  }
+
+  private async probe(path: string, displayPath: string, signal?: AbortSignal): Promise<EntryInfo | undefined> {
+    assertNotAborted(signal, 'stat')
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const entry = await sandbox.files.getInfo(path, signalOpts(signal))
+      assertNotAborted(signal, 'stat')
+      return entry
+    } catch (error: unknown) {
+      if (error instanceof FileNotFoundError) return undefined
+      throw mapError(error, 'stat', displayPath, signal)
+    }
+  }
+
+  private async requireRegular(target: FsTarget, signal?: AbortSignal): Promise<void> {
+    const info = await this.stat(target, signal)
+    if (info === undefined) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+    if (info.type !== 'file') throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+  }
+
+  private checkWriteIntent(existing: EntryInfo | undefined, expected: FsWriteIntent | undefined, target: FsTarget): void {
+    if (expected?.kind === 'createIfAbsent' && existing !== undefined) {
+      throw new FsError(`cannot overwrite existing "${target.displayPath}" without reading it first`, 'FS_NOT_OBSERVED')
+    }
+    if (expected?.kind === 'replaceIfVersion') {
+      if (existing === undefined || entryVersion(existing) !== expected.version) {
+        throw new FsError(`cannot write "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
+      }
+    }
+  }
+
+  private async readForDiff(target: FsTarget, signal?: AbortSignal): Promise<string | null> {
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const bytes = await sandbox.files.read(String(target.targetKey), { format: 'bytes', ...signalOpts(signal) })
+      assertNotAborted(signal, 'read')
+      return normalizeLineEndings(decodeText(bytes, target.displayPath, bytes.length))
+    } catch (error: unknown) {
+      if (error instanceof FsError && error.code === 'FS_NOT_TEXT') return null
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+  }
+
+  private async readForEdit(target: FsTarget, signal?: AbortSignal): Promise<string> {
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const bytes = await sandbox.files.read(String(target.targetKey), { format: 'bytes', ...signalOpts(signal) })
+      assertNotAborted(signal, 'edit')
+      return decodeText(bytes, target.displayPath, bytes.length)
+    } catch (error: unknown) {
+      throw mapError(error, 'edit', target.displayPath, signal)
+    }
+  }
+
+  private async writeAtomic(
+    target: FsTarget,
+    content: string,
+    existing: EntryInfo | undefined,
+    signal?: AbortSignal,
+  ): Promise<ReturnType<typeof FsVersion>> {
+    assertNotAborted(signal, 'write')
+    const sandbox = await this.ctx.e2b.getSandbox()
+    const targetPath = String(target.targetKey)
+    const versionId = randomUUID()
+    const temporary = posix.join(posix.dirname(targetPath), `.${posix.basename(targetPath)}.dsh-${randomUUID()}.tmp`)
+    try {
+      await sandbox.files.write(temporary, content, {
+        metadata: { [VERSION_METADATA_KEY]: versionId },
+        ...signalOpts(signal),
+      })
+      assertNotAborted(signal, 'write')
+      const mode = existing === undefined ? 0o600 : existing.mode & 0o777
+      await sandbox.commands.run(
+        `chmod ${mode.toString(8)} -- ${quoteE2BShellArg(temporary)}`,
+        signalOpts(signal),
+      )
+      assertNotAborted(signal, 'write')
+      await sandbox.commands.run(
+        `mv -f -- ${quoteE2BShellArg(temporary)} ${quoteE2BShellArg(targetPath)}`,
+        signalOpts(signal),
+      )
+      const committed = await sandbox.files.getInfo(targetPath)
+      return entryVersion(committed)
+    } catch (error: unknown) {
+      try {
+        await sandbox.files.remove(temporary)
+      } catch (_temporaryAlreadyAbsent) {
+        // Only the private staging path is swallowed; the original failure owns the operation.
+      }
+      throw mapError(error, 'write', target.displayPath, signal)
+    }
+  }
+}
+
+export default E2BFileSystem
diff --git a/packages/fs/fs-e2b/src/invariant.ts b/packages/fs/fs-e2b/src/invariant.ts
new file mode 100644
index 0000000000..6294d66ace
--- /dev/null
+++ b/packages/fs/fs-e2b/src/invariant.ts
@@ -0,0 +1,27 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-fs-e2b`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-fs-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'fs-e2b-invariant'
+/** Service required before reserving package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: each operation returns the E2B controller's committed
+ * result directly, with no independent event or cache to cross-check.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/fs/fs-e2b/tests/filesystem.spec.ts b/packages/fs/fs-e2b/tests/filesystem.spec.ts
new file mode 100644
index 0000000000..b8eb5447d6
--- /dev/null
+++ b/packages/fs/fs-e2b/tests/filesystem.spec.ts
@@ -0,0 +1,537 @@
+import { dirname, posix } from 'node:path'
+import { Context } from 'cordis'
+import {
+  CommandExitError,
+  FileNotFoundError,
+  FileType,
+  type EntryInfo,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import { FsVersion } from '@deepseek-ai/dsh-fs'
+import E2BFileSystem from '@deepseek-ai/dsh-fs-e2b'
+import * as E2BFsInvariant from '../src/invariant.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import { describe, expect, it } from 'vitest'
+
+interface RemoteNode {
+  type: FileType
+  data: Uint8Array
+  mode: number
+  modified: number
+  metadata?: Record<string, string>
+  symlinkTarget?: string
+}
+
+function bytes(value: string | readonly number[]): Uint8Array {
+  return typeof value === 'string' ? new TextEncoder().encode(value) : Uint8Array.from(value)
+}
+
+function commandError(exitCode: number, stderr = ''): CommandExitError {
+  return new CommandExitError({ exitCode, stdout: '', stderr, error: stderr })
+}
+
+class FakeRemote {
+  readonly nodes = new Map<string, RemoteNode>()
+  readonly writes: Array<{ path: string; data: string; metadata?: Record<string, string> }> = []
+  readonly renames: Array<{ from: string; to: string }> = []
+  readonly removals: string[] = []
+  readonly commands: string[] = []
+  streamChunks: Uint8Array[] | undefined
+  nextCommandError: unknown
+  nextInfoError: unknown
+  nextListError: unknown
+  nextReadError: unknown
+  nextRenameError: unknown
+  nextRemoveError: unknown
+  abortAfterRename: AbortController | undefined
+  disappearOnInfo = new Set<string>()
+  private clock = 1
+
+  constructor() {
+    this.dir('/')
+    this.dir('/workspace')
+  }
+
+  dir(path: string): void {
+    this.nodes.set(path, { type: FileType.DIR, data: bytes(''), mode: 0o755, modified: this.clock++ })
+  }
+
+  file(path: string, data: string | readonly number[], mode = 0o644): void {
+    this.nodes.set(path, { type: FileType.FILE, data: bytes(data), mode, modified: this.clock++ })
+  }
+
+  other(path: string): void {
+    this.nodes.set(path, { type: 'other' as FileType, data: bytes(''), mode: 0o600, modified: this.clock++ })
+  }
+
+  symlink(path: string, target: string): void {
+    this.nodes.set(path, {
+      type: FileType.FILE,
+      data: bytes(''),
+      mode: 0o777,
+      modified: this.clock++,
+      symlinkTarget: target,
+    })
+  }
+
+  mutate(path: string, data: string): void {
+    const node = this.required(path)
+    node.data = bytes(data)
+    node.modified = this.clock++
+  }
+
+  private required(path: string): RemoteNode {
+    const node = this.nodes.get(path)
+    if (node === undefined) throw new FileNotFoundError(`missing: ${path}`)
+    return node
+  }
+
+  private followed(path: string): { path: string; node: RemoteNode; link?: RemoteNode } {
+    const node = this.required(path)
+    if (node.symlinkTarget === undefined) return { path, node }
+    return { path: node.symlinkTarget, node: this.required(node.symlinkTarget), link: node }
+  }
+
+  private info(path: string): EntryInfo {
+    if (this.disappearOnInfo.delete(path)) throw new FileNotFoundError(`missing: ${path}`)
+    return this.rawInfo(path)
+  }
+
+  private rawInfo(path: string): EntryInfo {
+    const followed = this.followed(path)
+    const node = followed.node
+    return {
+      name: posix.basename(path),
+      path,
+      type: node.type,
+      size: node.data.byteLength,
+      mode: node.mode,
+      permissions: 'rw-------',
+      owner: 'user',
+      group: 'user',
+      modifiedTime: new Date(node.modified),
+      ...(node.metadata !== undefined ? { metadata: { ...node.metadata } } : {}),
+      ...(followed.link?.symlinkTarget !== undefined ? { symlinkTarget: followed.link.symlinkTarget } : {}),
+    }
+  }
+
+  private checkAbort(options: { signal?: AbortSignal } | undefined): void {
+    if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
+  }
+
+  readonly sandbox = {
+    sandboxId: 'fake',
+    files: {
+      makeDir: async (path: string): Promise<boolean> => {
+        if (this.nodes.has(path)) return false
+        this.dir(path)
+        return true
+      },
+      getInfo: async (path: string, options?: { signal?: AbortSignal }): Promise<EntryInfo> => {
+        this.checkAbort(options)
+        if (this.nextInfoError !== undefined) {
+          const error = this.nextInfoError
+          this.nextInfoError = undefined
+          throw error
+        }
+        return this.info(path)
+      },
+      read: async (path: string, options: { format: 'bytes' | 'stream'; signal?: AbortSignal }): Promise<Uint8Array | ReadableStream<Uint8Array>> => {
+        this.checkAbort(options)
+        if (this.nextReadError !== undefined) {
+          const error = this.nextReadError
+          this.nextReadError = undefined
+          throw error
+        }
+        const data = this.followed(path).node.data
+        if (options.format === 'bytes') return data.slice()
+        const chunks = this.streamChunks ?? [data.slice()]
+        return new ReadableStream<Uint8Array>({
+          start(controller) {
+            for (const chunk of chunks) controller.enqueue(chunk)
+            controller.close()
+          },
+        })
+      },
+      list: async (path: string, options?: { depth?: number; signal?: AbortSignal }): Promise<EntryInfo[]> => {
+        this.checkAbort(options)
+        if (this.nextListError !== undefined) {
+          const error = this.nextListError
+          this.nextListError = undefined
+          throw error
+        }
+        this.required(path)
+        return [...this.nodes.keys()]
+          .filter(candidate => candidate !== path && dirname(candidate) === path)
+          .map(candidate => this.rawInfo(candidate))
+      },
+      write: async (path: string, data: string, options?: { metadata?: Record<string, string>; signal?: AbortSignal }): Promise<object> => {
+        this.checkAbort(options)
+        const parent = dirname(path)
+        if (!this.nodes.has(parent)) this.dir(parent)
+        this.nodes.set(path, {
+          type: FileType.FILE,
+          data: bytes(data),
+          mode: 0o644,
+          modified: this.clock++,
+          ...(options?.metadata !== undefined ? { metadata: { ...options.metadata } } : {}),
+        })
+        this.writes.push({ path, data, ...(options?.metadata !== undefined ? { metadata: options.metadata } : {}) })
+        return {}
+      },
+      rename: async (from: string, to: string, options?: { signal?: AbortSignal }): Promise<EntryInfo> => {
+        this.checkAbort(options)
+        if (this.nextRenameError !== undefined) {
+          const error = this.nextRenameError
+          this.nextRenameError = undefined
+          throw error
+        }
+        const node = this.required(from)
+        this.nodes.delete(from)
+        this.nodes.set(to, node)
+        this.renames.push({ from, to })
+        this.abortAfterRename?.abort('after commit')
+        return this.info(to)
+      },
+      remove: async (path: string): Promise<void> => {
+        this.removals.push(path)
+        if (this.nextRemoveError !== undefined) {
+          const error = this.nextRemoveError
+          this.nextRemoveError = undefined
+          throw error
+        }
+        this.nodes.delete(path)
+      },
+    },
+    commands: {
+      run: async (command: string, options?: { signal?: AbortSignal }): Promise<{ exitCode: number; stdout: string; stderr: string }> => {
+        this.checkAbort(options)
+        this.commands.push(command)
+        if (this.nextCommandError !== undefined) {
+          const error = this.nextCommandError
+          this.nextCommandError = undefined
+          throw error
+        }
+        if (command.startsWith('realpath -m -- ')) {
+          const input = command.slice('realpath -m -- '.length).slice(1, -1)
+          const node = this.nodes.get(input)
+          return { exitCode: 0, stdout: `${node?.symlinkTarget ?? input}\n`, stderr: '' }
+        }
+        const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
+        if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
+        const move = /^mv -f -- '([^']+)' '([^']+)'$/.exec(command)
+        if (move !== null) {
+          if (this.nextRenameError !== undefined) {
+            const error = this.nextRenameError
+            this.nextRenameError = undefined
+            throw error
+          }
+          const node = this.required(move[1]!)
+          this.nodes.delete(move[1]!)
+          this.nodes.set(move[2]!, node)
+          this.renames.push({ from: move[1]!, to: move[2]! })
+          this.abortAfterRename?.abort('after commit')
+        }
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+  } as unknown as Sandbox
+}
+
+async function setup(remote = new FakeRemote()): Promise<{ ctx: Context; fs: E2BFileSystem; remote: FakeRemote }> {
+  const ctx = new Context()
+  const runtime = {
+    cwd: '/workspace',
+    runtimeRoot: '/workspace/.dsh-e2b',
+    disposeMode: 'kill',
+    getSandbox: async () => remote.sandbox,
+  } as unknown as E2BSandboxService
+  ctx.provide('e2b', runtime)
+  await ctx.plugin(E2BFileSystem)
+  return { ctx, fs: ctx.fs as E2BFileSystem, remote }
+}
+
+async function expectCode(promise: Promise<unknown>, code: string): Promise<void> {
+  await expect(promise).rejects.toMatchObject({ code })
+}
+
+describe('E2BFileSystem identity, metadata, and reads', () => {
+  it('resolves remote paths, reports symlinks, and lists direct children in stable order', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/z.txt', 'z')
+    remote.file('/workspace/a.txt', 'a')
+    remote.dir('/workspace/dir')
+    remote.other('/workspace/special')
+    remote.file('/workspace/dir/nested.txt', 'nested')
+    remote.symlink('/workspace/link.txt', '/workspace/a.txt')
+    const { fs } = await setup(remote)
+
+    const link = await fs.resolve('link.txt')
+    expect(link).toEqual({ targetKey: '/workspace/a.txt', displayPath: '/workspace/link.txt' })
+    await expect(fs.lstat('link.txt')).resolves.toMatchObject({ type: 'symlink', size: 1 })
+    await expect(fs.lstat('a.txt')).resolves.toMatchObject({ type: 'file', size: 1 })
+    await expect(fs.lstat('dir')).resolves.toEqual(expect.objectContaining({ type: 'directory' }))
+    await expect(fs.lstat('special')).resolves.toEqual(expect.objectContaining({ type: 'other' }))
+    await expect(fs.lstat('missing')).resolves.toBeUndefined()
+    await expect(fs.stat(link)).resolves.toMatchObject({ type: 'file', size: 1 })
+    const directory = await fs.resolve('.')
+    const listed = await fs.listDir(directory)
+    expect(listed.map(entry => entry.name)).toEqual(['a.txt', 'dir', 'link.txt', 'special', 'z.txt'])
+    expect(listed.find(entry => entry.name === 'dir')).toMatchObject({ type: 'directory' })
+    expect(listed.find(entry => entry.name === 'link.txt')).toMatchObject({
+      type: 'file',
+      target: { targetKey: '/workspace/a.txt', displayPath: '/workspace/link.txt' },
+    })
+    expect(listed.some(entry => entry.name === 'nested.txt')).toBe(false)
+  })
+
+  it('reads whole and streamed UTF-8 across chunk boundaries', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/text.txt', 'A€B')
+    remote.streamChunks = [bytes([65, 0xe2]), bytes([0x82, 0xac, 66])]
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('text.txt')
+    await expect(fs.readText(target)).resolves.toBe('A€B')
+    let streamed = ''
+    for await (const chunk of await fs.streamText(target)) streamed += chunk
+    expect(streamed).toBe('A€B')
+
+    remote.streamChunks = [bytes([0xe2]), bytes([0x82, 0xac])]
+    let initiallyBuffered = ''
+    for await (const chunk of await fs.streamText(target)) initiallyBuffered += chunk
+    expect(initiallyBuffered).toBe('€')
+  })
+
+  it('matches local binary sampling while edits still reject any NUL byte', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/late-nul.txt', `${'a'.repeat(8192)}\0tail`)
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('late-nul.txt')
+    await expect(fs.readText(target)).resolves.toContain('\0tail')
+    remote.streamChunks = [bytes('a'.repeat(8192)), bytes([0, 116])]
+    let streamed = ''
+    for await (const chunk of await fs.streamText(target)) streamed += chunk
+    expect(streamed).toBe(`${'a'.repeat(8192)}\0t`)
+    await expectCode(fs.editText(target, { oldString: 'tail', newString: 'end', replaceAll: false }), 'FS_NOT_TEXT')
+  })
+
+  it('maps binary, invalid UTF-8, missing, and non-regular read failures', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/binary', [0, 1])
+    remote.file('/workspace/invalid', [0xff])
+    remote.dir('/workspace/directory')
+    const { fs } = await setup(remote)
+    await expectCode(fs.readText(await fs.resolve('binary')), 'FS_NOT_TEXT')
+    await expectCode(fs.readText(await fs.resolve('invalid')), 'FS_NOT_TEXT')
+    await expectCode(fs.readText(await fs.resolve('missing')), 'FS_NOT_FOUND')
+    await expectCode(fs.readText(await fs.resolve('directory')), 'FS_NOT_REGULAR_FILE')
+
+    remote.streamChunks = [bytes([0xff])]
+    const invalid = await fs.streamText(await fs.resolve('invalid'))
+    await expect((async () => { for await (const _chunk of invalid) void _chunk })()).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+    remote.streamChunks = [bytes([0])]
+    const binary = await fs.streamText(await fs.resolve('binary'))
+    await expect((async () => { for await (const _chunk of binary) void _chunk })()).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+
+    remote.streamChunks = [bytes([0xe2])]
+    const incomplete = await fs.streamText(await fs.resolve('invalid'))
+    await expect((async () => { for await (const _chunk of incomplete) void _chunk })()).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+
+    const raced = await fs.resolve('invalid')
+    remote.nextReadError = new FileNotFoundError('gone after stat')
+    await expectCode(fs.streamText(raced), 'FS_NOT_FOUND')
+  })
+
+  it('honors aborts before and during remote reads', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'a')
+    const { fs } = await setup(remote)
+    await expectCode(fs.resolve('a', { signal: AbortSignal.abort() }), 'FS_ABORTED')
+    await expectCode(fs.lstat('a', undefined, AbortSignal.abort()), 'FS_ABORTED')
+    await expectCode(fs.stat(await fs.resolve('a'), AbortSignal.abort()), 'FS_ABORTED')
+    remote.nextReadError = new DOMException('aborted', 'AbortError')
+    await expectCode(fs.readText(await fs.resolve('a')), 'FS_ABORTED')
+  })
+
+  it('rejects empty paths and directory-listing type errors', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file', 'x')
+    const { fs } = await setup(remote)
+    await expectCode(fs.resolve('   '), 'FS_NOT_FOUND')
+    await expectCode(fs.lstat(''), 'FS_NOT_FOUND')
+    await expectCode(fs.listDir(await fs.resolve('missing')), 'FS_NOT_FOUND')
+    await expectCode(fs.listDir(await fs.resolve('/workspace/file')), 'FS_NOT_DIRECTORY')
+    remote.nextListError = new Error('listing transport failed')
+    await expectCode(fs.listDir(await fs.resolve('/workspace')), 'FS_IO_ERROR')
+  })
+})
+
+describe('E2BFileSystem atomic writes and edits', () => {
+  it('creates owner-only files and returns metadata after the committed move', async () => {
+    const { fs, remote } = await setup()
+    const target = await fs.resolve('new.txt')
+    const outcome = await fs.writeText(target, 'one\r\ntwo\rthree', { kind: 'createIfAbsent' })
+    expect(outcome).toMatchObject({ operation: 'create', before: null, after: 'one\ntwo\rthree' })
+    expect(remote.nodes.get('/workspace/new.txt')?.mode).toBe(0o600)
+    expect(remote.nodes.get('/workspace/new.txt')?.metadata?.['dsh-version']).toBeDefined()
+    await expect(fs.stat(target)).resolves.toMatchObject({ version: outcome.version, size: 14 })
+  })
+
+  it('preserves replacement mode, normalizes only CRLF for diffs, and changes version on external writes', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'old\r\nline\rlone', 0o640)
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const before = (await fs.stat(target))!.version
+    const outcome = await fs.writeText(target, 'new', { kind: 'replaceIfVersion', version: before })
+    expect(outcome).toMatchObject({ operation: 'update', before: 'old\nline\rlone', after: 'new' })
+    expect(remote.nodes.get('/workspace/file.txt')?.mode).toBe(0o640)
+    const committed = outcome.version
+    remote.mutate('/workspace/file.txt', 'external')
+    expect((await fs.stat(target))!.version).not.toBe(committed)
+  })
+
+  it('returns null as the overwrite diff basis for binary or invalid prior content', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', [0xff])
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    await expect(fs.writeText(target, 'valid')).resolves.toMatchObject({ before: null, after: 'valid' })
+  })
+
+  it('fails an overwrite when reading its text diff basis fails for another reason', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'prior')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    remote.nextReadError = new Error('read transport failed')
+    await expectCode(fs.writeText(target, 'replacement'), 'FS_IO_ERROR')
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/file.txt')?.data)).toBe('prior')
+  })
+
+  it('enforces create and version intents before publication', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'v1')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const version = (await fs.stat(target))!.version
+    await expectCode(fs.writeText(target, 'blind', { kind: 'createIfAbsent' }), 'FS_NOT_OBSERVED')
+    remote.mutate('/workspace/file.txt', 'v2')
+    await expectCode(fs.writeText(target, 'stale', { kind: 'replaceIfVersion', version }), 'FS_STALE_VERSION')
+    await expectCode(fs.writeText(await fs.resolve('missing'), 'stale', { kind: 'replaceIfVersion', version }), 'FS_STALE_VERSION')
+    remote.dir('/workspace/dir')
+    await expectCode(fs.writeText(await fs.resolve('dir'), 'x'), 'FS_NOT_REGULAR_FILE')
+  })
+
+  it('does not turn an abort observed after a successful move into a failed write', async () => {
+    const remote = new FakeRemote()
+    const controller = new AbortController()
+    remote.abortAfterRename = controller
+    const { fs } = await setup(remote)
+    await expect(fs.writeText(await fs.resolve('committed'), 'yes', undefined, controller.signal))
+      .resolves.toMatchObject({ operation: 'create' })
+    expect(controller.signal.aborted).toBe(true)
+  })
+
+  it('cleans staging files and maps command, permission, and abort failures', async () => {
+    const remote = new FakeRemote()
+    const { fs } = await setup(remote)
+    const commandTarget = await fs.resolve('command')
+    remote.nextCommandError = commandError(1, 'chmod failed')
+    await expectCode(fs.writeText(commandTarget, 'x'), 'FS_IO_ERROR')
+    expect(remote.removals).toHaveLength(1)
+
+    remote.nextRenameError = new Error('permission denied')
+    await expectCode(fs.writeText(await fs.resolve('permission'), 'x'), 'FS_PERMISSION_DENIED')
+    remote.nextRemoveError = new Error('cleanup also failed')
+    remote.nextRenameError = new DOMException('aborted', 'AbortError')
+    await expectCode(fs.writeText(await fs.resolve('abort'), 'x'), 'FS_ABORTED')
+  })
+
+  it('applies literal edits atomically and restores the detected CRLF style', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'one\r\ntwo\r\nthree\n')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const version = (await fs.stat(target))!.version
+    const outcome = await fs.editText(
+      target,
+      { oldString: 'two\r\n', newString: 'TWO\r\n', replaceAll: false },
+      { version },
+    )
+    expect(outcome).toMatchObject({ before: 'one\ntwo\nthree\n', after: 'one\nTWO\nthree\n' })
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/file.txt')?.data)).toBe('one\r\nTWO\r\nthree\r\n')
+  })
+
+  it('reports stale and literal-match failures with stable codes', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'a a')
+    remote.dir('/workspace/dir')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    await expectCode(fs.editText(target, { oldString: '', newString: 'x', replaceAll: false }), 'FS_EDIT_NOT_FOUND')
+    await expectCode(fs.editText(target, { oldString: 'z', newString: 'x', replaceAll: false }), 'FS_EDIT_NOT_FOUND')
+    await expectCode(fs.editText(target, { oldString: 'a', newString: 'x', replaceAll: false }), 'FS_AMBIGUOUS_EDIT')
+    await expect(fs.editText(target, { oldString: 'a', newString: 'x', replaceAll: true }))
+      .resolves.toMatchObject({ after: 'x x' })
+    await expectCode(fs.editText(target, { oldString: 'x', newString: 'y', replaceAll: false }, { version: FsVersion('stale') }), 'FS_STALE_VERSION')
+    await expectCode(fs.editText(await fs.resolve('missing'), { oldString: 'x', newString: 'y', replaceAll: false }), 'FS_STALE_VERSION')
+    await expectCode(fs.editText(await fs.resolve('dir'), { oldString: 'x', newString: 'y', replaceAll: false }), 'FS_NOT_REGULAR_FILE')
+  })
+
+  it('serializes guarded mutations so only one stale version can win', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'base')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const version = (await fs.stat(target))!.version
+    const results = await Promise.allSettled([
+      fs.writeText(target, 'one', { kind: 'replaceIfVersion', version }),
+      fs.editText(target, { oldString: 'base', newString: 'two', replaceAll: false }, { version }),
+    ])
+    expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(1)
+    expect(results.filter(result => result.status === 'rejected')).toHaveLength(1)
+  })
+})
+
+describe('E2B filesystem adapter integration edges', () => {
+  it('maps canonicalization, permission, and generic provider failures', async () => {
+    const remote = new FakeRemote()
+    const { fs } = await setup(remote)
+    remote.nextCommandError = commandError(1, 'not a directory')
+    await expectCode(fs.resolve('bad'), 'FS_IO_ERROR')
+    remote.nextCommandError = commandError(1)
+    await expectCode(fs.resolve('bad-again'), 'FS_IO_ERROR')
+    remote.nextCommandError = new Error('canonical transport failed')
+    await expectCode(fs.resolve('bad-transport'), 'FS_IO_ERROR')
+    remote.file('/workspace/a', 'a')
+    const target = await fs.resolve('a')
+    remote.nextInfoError = new Error('metadata transport failed')
+    await expectCode(fs.stat(target), 'FS_IO_ERROR')
+    remote.nextReadError = new Error('operation not permitted')
+    await expectCode(fs.readText(target), 'FS_PERMISSION_DENIED')
+    remote.nextReadError = 'transport vanished'
+    await expectCode(fs.readText(target), 'FS_IO_ERROR')
+  })
+
+  it('keeps a listed child whose metadata disappears as an other entry', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'a')
+    remote.disappearOnInfo.add('/workspace/a')
+    const { fs } = await setup(remote)
+    const listed = await fs.listDir(await fs.resolve('/workspace'))
+    expect(listed).toEqual([{
+      name: 'a',
+      type: 'other',
+      target: { targetKey: '/workspace/a', displayPath: '/workspace/a' },
+    }])
+  })
+
+  it('registers the package-owned empty invariant installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BFsInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/fs/fs-e2b/tsconfig.json b/packages/fs/fs-e2b/tsconfig.json
new file mode 100644
index 0000000000..c424efd2e5
--- /dev/null
+++ b/packages/fs/fs-e2b/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../e2b/e2b"
+    },
+    {
+      "path": "../fs"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 0ebb5bd4af..0efaf7838e 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: f2b19436da40feb14d067e2cfc706222625680b5
-README.zh.md: 938312448dd5c0a691ed07ddc9843cf2c4445637
+README.md: ae18c55205edd6085a0ed8de1bb7f875c411c79f
+README.zh.md: e27fd240e4c1e96d8b859b326574e441241e8508
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index f2b19436da..ae18c55205 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,11 +2,12 @@
 
 English | [中文](README.zh.md)
 
-The shared process substrate for one execution world: executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+The shared home for spawning managed child-process trees: fully-specified spawn specs with Node-shaped per-stream stdio dispositions (raw pipes, inherit, bounded tail-keep collection with spill files), the one credential scrub every harness spawner uses, offset-based incremental reads, tree-scoped signalling with SIGTERM→grace→SIGKILL escalation, and the cooperative dispose ladder. Command defaulting, shell semantics, deadlines, protocol framing, and presentation stay with consumers — the [bash executors](../bash/README.md), the [LSP host](../lsp/README.md), and the [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 | Package | ctx key | Role |
 |---|---|---|
-| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
-| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
+| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: abstract `SubprocessService.spawn(spec)`, the fully-explicit `SubprocessSpawnSpec` with per-stream stdio dispositions, `SubprocessHandle` (streams, offset-based readers, terminate/waitForExit/dispose), and the shared scrub + `DSH_*`/`CollectedOutput` vocabulary |
+| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, per-disposition stream wiring, tail-keep truncation with bounded private spill files, the `DSH_*` merge order, tree signalling with escalation, the dispose ladder, and terminate-and-join disposal |
+| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | — | Experimental E2B implementation: remote Linux process groups and spill state in the shared `ctx.e2b` sandbox, with asynchronous PID acquisition and SDK buffering limitations |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index 938312448d..e27fd240e4 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -1,12 +1,13 @@
-# subprocess/：子进程能力家族
+# subprocess/：进程管理能力家族
 
 [English](README.md) | 中文
 
-这里集中提供一个执行世界的共享进程基底：可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+spawn 受管子进程树的共用归属位置：完全显式的 spawn spec，其 stdio 处置方式（disposition）为 Node 形状、按流划分（原始管道、inherit、附带 spill 文件的有界尾部保留收集）；harness 中所有 spawn 调用方共用的那一份凭据清除；基于偏移量的增量读取；以进程树为范围、带 SIGTERM→宽限期→SIGKILL 升级的信号发送；以及协作式 dispose（资源释放）阶梯。命令默认值补全、shell 语义、deadline、协议分帧与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[进程管理器 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
-| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：抽象的 `SubprocessService.spawn(spec)`、完全显式且带按流划分 stdio 处置方式的 `SubprocessSpawnSpec`、`SubprocessHandle`（流、基于偏移量的读取器、terminate/waitForExit/dispose），以及共享的凭据清除 + `DSH_*`/`CollectedOutput` 词汇 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、按处置方式接线的流、附带有界私有 spill 文件的尾部保留截断、`DSH_*` 合并次序、带升级的进程树信号发送、dispose 阶梯，以及先终止再等待退出的 dispose |
+| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | 无 | 实验性 E2B 实现：远程 Linux 进程组和共享 `ctx.e2b` 沙箱中的 spill 状态，但 PID 异步获取，且受 SDK 缓冲限制 |
 
-即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
+服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
diff --git a/packages/subprocess/subprocess-e2b/README.i18n.yaml b/packages/subprocess/subprocess-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..dfbe97e8b9
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/README.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 packages/subprocess/subprocess-e2b/README.md
+README.md: 9ec1518103413f33a52023c17722bf5a5fe275ce
+README.zh.md: f50ff2f3d85a5ddd9bd352e95d0eb0a23e756404
diff --git a/packages/subprocess/subprocess-e2b/README.md b/packages/subprocess/subprocess-e2b/README.md
new file mode 100644
index 0000000000..9ec1518103
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/README.md
@@ -0,0 +1,32 @@
+# @deepseek-ai/dsh-subprocess-e2b
+
+English | [中文](README.zh.md)
+
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing consumers such as [`dsh-bash-local`](../../bash/bash-local/README.md) then execute in the shared remote sandbox without an E2B-specific Bash adapter.
+
+## Behavior
+
+- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the SDK returns the command PID; `done`, stdin, termination, and `waitForExit()` wait for readiness internally.
+- **Linux process groups** — a quoted wrapper starts each argv under `setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of assuming the SDK command PID is the group id. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
+- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
+- **Stdio projection** — pipe mode forwards E2B callbacks into host Node streams; inherit mode forwards them to the harness process streams; collect mode retains a bounded host tail with offset reads. Optional complete spill files are written remotely and advertised only while within their cap. Batch and streaming stdin use the SDK handle.
+
+The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `tr`, `env`, `chmod`, `tee`, and `kill`. A custom template must retain compatible commands.
+
+## Model Experience
+
+Indirectly, through consumer seams such as the Bash executor behind `dsh-tool-bash`, which render remote output, exit facts, background deltas, and spill paths.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumers own any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate even when this adapter exposes bounded tails, so the subprocess seam's normal host-memory bound is not achieved.
+- **Pipe output is not byte-faithful** — E2B delivers separately decoded strings rather than raw bytes, so split multibyte sequences and arbitrary binary protocols can be corrupted; LSP and other framed byte-stream consumers are unsupported.
+- **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
+- **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
+- **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
+- **Signal attribution is inferred** — when termination was requested and E2B reports a nonzero exit code, the adapter reports the last requested signal because the SDK result does not identify the terminating signal.
+- **Linux utility and E2B transport semantics are assumed** — there is no PTY, Windows, arbitrary-template, or network-partition fidelity layer.
diff --git a/packages/subprocess/subprocess-e2b/README.zh.md b/packages/subprocess/subprocess-e2b/README.zh.md
new file mode 100644
index 0000000000..f50ff2f3d8
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/README.zh.md
@@ -0,0 +1,32 @@
+# @deepseek-ai/dsh-subprocess-e2b
+
+[English](README.md) | 中文
+
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。随后，[`dsh-bash-local`](../../bash/bash-local/README.md) 等现有消费方会在共享远程沙箱中执行，无需 E2B 专用 Bash 适配器。
+
+## 行为
+
+- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。SDK 返回命令 PID 之前，`pid` 为 `-1`；`done`、stdin、终止和 `waitForExit()` 会在内部等待就绪。
+- **Linux 进程组**：带引号保护的包装层会在 `setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会假设 SDK 命令 PID 就是进程组 ID。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
+- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
+- **stdio 投影**：pipe 模式把 E2B 回调转发到宿主 Node 流；inherit 模式把回调转发到 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。可选的完整 spill 文件写在远程，并且只有未超过其上限时才会对外公布。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+
+基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`tr`、`env`、`chmod`、`tee` 和 `kill`。自定义模板必须保留兼容的命令。
+
+## 模型体验
+
+通过消费方 seam 间接影响模型，例如 `dsh-tool-bash` 背后的 Bash 执行器；这些消费方会渲染远程输出、退出事实、后台增量和 spill 路径。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由具名消费方负责。
+
+## 已知限制与延后工作
+
+- **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会持续累积，因此无法达到进程管理 seam 通常提供的宿主内存边界。
+- **Pipe 输出并非字节保真**：E2B 交付的是分别解码后的字符串，而不是原始字节，因此拆分的多字节序列和任意二进制协议可能损坏；不支持 LSP 及其他带帧字节流消费方。
+- **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
+- **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
+- **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
+- **信号归因依靠推断**：如果已经请求终止，而 E2B 报告非零退出码，适配器会报告最后请求的信号，因为 SDK 结果不标识终止信号。
+- **依赖 Linux 工具与 E2B 传输语义**：没有 PTY、Windows、任意模板或网络分区的保真层。
diff --git a/packages/subprocess/subprocess-e2b/package.json b/packages/subprocess/subprocess-e2b/package.json
new file mode 100644
index 0000000000..d73607d1f3
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/package.json
@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-subprocess-e2b",
+  "description": "E2B subprocess implementation for DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/subprocess/subprocess-e2b/src/index.ts b/packages/subprocess/subprocess-e2b/src/index.ts
new file mode 100644
index 0000000000..2856df67bd
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/src/index.ts
@@ -0,0 +1,58 @@
+/**
+ * E2B implementation of the subprocess seam. Each handle starts through the
+ * shared sandbox and retains command output/status paths in that remote world.
+ * @module @deepseek-ai/dsh-subprocess-e2b
+ */
+
+import { randomUUID } from 'node:crypto'
+import { posix } from 'node:path'
+import { Context } from 'cordis'
+import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { E2BSubprocessHandle } from './process.ts'
+
+/** E2B command manager registered as `ctx.subprocess`. */
+export class E2BSubprocessService extends SubprocessService {
+  static inject = ['e2b']
+
+  private readonly live = new Set<E2BSubprocessHandle>()
+
+  /** Create the E2B subprocess service and bind its disposal policy. */
+  constructor(ctx: Context) {
+    super(ctx)
+    ctx.effect(() => async () => {
+      const handles = [...this.live]
+      for (const handle of handles) handle.terminate()
+      await Promise.all(handles.map(async (handle) => {
+        await handle.done.catch(() => {})
+        await handle.waitForExit()
+      }))
+      this.live.clear()
+    }, 'e2b subprocess teardown')
+  }
+
+  /** @inheritdoc */
+  spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
+    const program = spec.argv[0]
+    if (program === undefined || program.length === 0) {
+      throw new Error('invalid argv: expected a non-empty program name at argv[0]')
+    }
+    if (!Number.isFinite(spec.graceMs) || spec.graceMs <= 0) {
+      throw new Error('subprocess-e2b: graceMs must be a positive finite number')
+    }
+    if (spec.signal?.aborted === true) {
+      throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`)
+    }
+    const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'processes', randomUUID())
+    const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir)
+    this.live.add(handle)
+    const release = async (): Promise<void> => {
+      await handle.waitForExit()
+      this.live.delete(handle)
+    }
+    void handle.done.then(release, release).catch(() => {})
+    return handle
+  }
+}
+
+export default E2BSubprocessService
diff --git a/packages/subprocess/subprocess-e2b/src/invariant.ts b/packages/subprocess/subprocess-e2b/src/invariant.ts
new file mode 100644
index 0000000000..4416175b1b
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/src/invariant.ts
@@ -0,0 +1,27 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-subprocess-e2b`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subprocess-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'subprocess-e2b-invariant'
+/** Service required before reserving package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: live remote handles are private teardown ownership,
+ * and the E2B command event stream is the sole outcome authority.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/subprocess/subprocess-e2b/src/output.ts b/packages/subprocess/subprocess-e2b/src/output.ts
new file mode 100644
index 0000000000..b6551983a0
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/src/output.ts
@@ -0,0 +1,70 @@
+/** Bounded host-side projection of a complete output file retained in E2B. */
+
+import { Buffer } from 'node:buffer'
+import type { SubprocessOutputRead, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess'
+
+/** Offset reader used for one collect-mode E2B stream. */
+export class E2BOutputReader implements SubprocessOutputReader {
+  private chunks: Buffer[] = []
+  private retainedBytes = 0
+  private totalBytes = 0
+
+  /**
+   * Create a bounded reader over one remote spill path.
+   * @param maxBytes - In-memory tail cap.
+   * @param maxSpillBytes - Maximum complete remote file size the caller accepts.
+   * @param spillPath - Remote full-output path.
+   */
+  constructor(
+    private readonly maxBytes: number,
+    private readonly maxSpillBytes: number | undefined,
+    private readonly spillPath: string,
+  ) {}
+
+  /** Total bytes observed from the SDK stream. */
+  get size(): number {
+    return this.totalBytes
+  }
+
+  /**
+   * Append one decoded SDK output event.
+   * @param text - Event text delivered by E2B.
+   */
+  push(text: string): void {
+    if (text.length === 0) return
+    const chunk = Buffer.from(text)
+    this.totalBytes += chunk.length
+    this.chunks.push(chunk)
+    this.retainedBytes += chunk.length
+    while (this.retainedBytes > this.maxBytes) {
+      const head = this.chunks[0] as Buffer
+      const excess = this.retainedBytes - this.maxBytes
+      if (head.length <= excess) {
+        this.chunks.shift()
+        this.retainedBytes -= head.length
+      } else {
+        this.chunks[0] = head.subarray(excess)
+        this.retainedBytes -= excess
+      }
+    }
+  }
+
+  /** @inheritdoc */
+  readFrom(fromByte: number): SubprocessOutputRead {
+    if (!Number.isSafeInteger(fromByte) || fromByte < 0) {
+      throw new Error('subprocess output offset must be a non-negative safe integer')
+    }
+    const retained = Buffer.concat(this.chunks, this.retainedBytes)
+    const firstRetained = this.totalBytes - this.retainedBytes
+    const lossy = fromByte < firstRetained
+    const start = lossy ? 0 : Math.min(retained.length, Math.max(0, fromByte - firstRetained))
+    return {
+      text: retained.subarray(start).toString('utf8'),
+      nextOffset: this.totalBytes,
+      lossy,
+      ...(lossy && this.maxSpillBytes !== undefined && this.totalBytes <= this.maxSpillBytes
+        ? { spillPath: this.spillPath }
+        : {}),
+    }
+  }
+}
diff --git a/packages/subprocess/subprocess-e2b/src/process.ts b/packages/subprocess/subprocess-e2b/src/process.ts
new file mode 100644
index 0000000000..507ea700c4
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/src/process.ts
@@ -0,0 +1,417 @@
+/** One asynchronously-started E2B command projected onto the subprocess seam. */
+
+import { Buffer } from 'node:buffer'
+import { PassThrough, Writable } from 'node:stream'
+import { posix } from 'node:path'
+import {
+  CommandExitError,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
+import type {
+  SubprocessCollect,
+  SubprocessHandle,
+  SubprocessOutcome,
+  SubprocessOutputMode,
+  SubprocessSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import { E2BOutputReader } from './output.ts'
+
+const GROUP_POLL_MS = 20
+
+function isCollect(mode: SubprocessOutputMode): mode is SubprocessCollect {
+  return mode !== 'pipe' && mode !== 'inherit'
+}
+
+function hasSpill(mode: SubprocessOutputMode): mode is SubprocessCollect & { spill: { maxBytes: number } } {
+  return isCollect(mode) && mode.spill !== undefined
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+class DeferredStdin extends Writable {
+  constructor(private readonly ready: Promise<CommandHandle>) {
+    super({ decodeStrings: false })
+  }
+
+  override _write(chunk: string | Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    void this.ready.then(handle => handle.sendStdin(chunk)).then(
+      () => { callback() },
+      (error: unknown) => { callback(asError(error)) },
+    )
+  }
+
+  override _final(callback: (error?: Error | null) => void): void {
+    void this.ready.then(handle => handle.closeStdin()).then(
+      () => { callback() },
+      (error: unknown) => { callback(asError(error)) },
+    )
+  }
+}
+
+interface RemotePaths {
+  pid: string
+  status: string
+  stdout: string
+  stderr: string
+}
+
+function explicitEnvironmentNames(env: Readonly<Record<string, string>> | undefined): string {
+  return Object.keys(env ?? {})
+    .map(quoteE2BShellArg)
+    .join(' ')
+}
+
+function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
+  const stdoutRedirect = hasSpill(spec.stdio.stdout)
+    ? `> >(tee -a -- ${quoteE2BShellArg(paths.stdout)})`
+    : ''
+  const stderrRedirect = hasSpill(spec.stdio.stderr)
+    ? `2> >(tee -a -- ${quoteE2BShellArg(paths.stderr)} >&2)`
+    : ''
+  const environmentNames = explicitEnvironmentNames(spec.env)
+  const inner = [
+    'set +e',
+    'umask 077',
+    'dsh_e2b_pgid="$(ps -o pgid= -p "$$" | tr -d " ")"',
+    `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
+    'dsh_e2b_env=()',
+    `dsh_e2b_explicit=(${environmentNames})`,
+    'while IFS= read -r dsh_e2b_name; do',
+    '  case "${dsh_e2b_name^^}" in DSH_*|*KEY*|*SECRET*|*TOKEN*) continue ;; esac',
+    '  dsh_e2b_env+=("$dsh_e2b_name=${!dsh_e2b_name}")',
+    'done < <(compgen -e)',
+    'for dsh_e2b_name in "${dsh_e2b_explicit[@]}"; do dsh_e2b_env+=("$dsh_e2b_name=${!dsh_e2b_name}"); done',
+    `env -i "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
+    'dsh_e2b_status=$?',
+    'wait',
+    `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
+    'exit "$dsh_e2b_status"',
+  ].join('\n')
+  const argv = spec.argv.map(quoteE2BShellArg).join(' ')
+  return `exec setsid --wait -- bash -c ${quoteE2BShellArg(inner)} dsh-e2b ${argv}`
+}
+
+function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
+
+function isAborted(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true
+}
+
+function waitTick(signal?: AbortSignal): Promise<boolean> {
+  if (signal?.aborted === true) return Promise.resolve(false)
+  return new Promise<boolean>((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve(true)
+    }, GROUP_POLL_MS)
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      resolve(false)
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/** E2B-backed subprocess handle with deferred remote PID acquisition. */
+export class E2BSubprocessHandle implements SubprocessHandle {
+  readonly stdin: Writable | undefined
+  readonly stdout: PassThrough | undefined
+  readonly stderr: PassThrough | undefined
+  readonly collected: SubprocessHandle['collected']
+  readonly done: Promise<SubprocessOutcome>
+
+  private readonly readyState = Promise.withResolvers<CommandHandle>()
+  private readonly stdoutReader: E2BOutputReader | undefined
+  private readonly stderrReader: E2BOutputReader | undefined
+  private readonly paths: RemotePaths
+  private remotePid = -1
+  private settled = false
+  private terminationRequested = false
+  private terminationSignal: NodeJS.Signals | null = null
+  private termination: Promise<void> | undefined
+
+  /**
+   * Begin an E2B command without blocking the synchronous subprocess spawn seam.
+   * @param runtime - Shared E2B sandbox owner.
+   * @param spec - Fully resolved subprocess request.
+   * @param stateDir - Remote directory retaining process identity, status, and valid spills.
+   */
+  constructor(
+    private readonly runtime: E2BSandboxService,
+    private readonly spec: SubprocessSpawnSpec,
+    readonly stateDir: string,
+  ) {
+    this.paths = {
+      pid: posix.join(stateDir, 'pid'),
+      status: posix.join(stateDir, 'exit-code'),
+      stdout: posix.join(stateDir, 'stdout.log'),
+      stderr: posix.join(stateDir, 'stderr.log'),
+    }
+    const outMode = spec.stdio.stdout
+    const errMode = spec.stdio.stderr
+    this.stdout = outMode === 'pipe' ? new PassThrough() : undefined
+    this.stderr = errMode === 'pipe' ? new PassThrough() : undefined
+    this.stdoutReader = isCollect(outMode)
+      ? new E2BOutputReader(outMode.maxBytes, outMode.spill?.maxBytes, this.paths.stdout)
+      : undefined
+    this.stderrReader = isCollect(errMode)
+      ? new E2BOutputReader(errMode.maxBytes, errMode.spill?.maxBytes, this.paths.stderr)
+      : undefined
+    this.collected = {
+      ...(this.stdoutReader !== undefined ? { stdout: this.stdoutReader } : {}),
+      ...(this.stderrReader !== undefined ? { stderr: this.stderrReader } : {}),
+    }
+    this.stdin = spec.stdio.stdin === 'pipe' ? new DeferredStdin(this.readyState.promise) : undefined
+    void this.readyState.promise.catch(() => {})
+    spec.signal?.addEventListener('abort', this.onAbort, { once: true })
+    this.done = this.run()
+    void this.done.catch(() => {})
+    if (spec.signal?.aborted === true) this.terminate()
+  }
+
+  /** Remote process id after start; `-1` while E2B startup is pending or after it fails. */
+  get pid(): number {
+    return this.remotePid
+  }
+
+  /** @inheritdoc */
+  terminate(): void {
+    if (this.terminationRequested || this.settled) return
+    this.terminationRequested = true
+    this.termination = this.terminateRemote()
+    void this.termination.catch(() => {})
+  }
+
+  /** @inheritdoc */
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    let handle: CommandHandle | undefined
+    try {
+      handle = await this.readyForWait(signal)
+    } catch {
+      return true
+    }
+    if (handle === undefined) return false
+    let sandbox: Sandbox
+    try {
+      sandbox = await this.runtime.getSandbox()
+    } catch (error: unknown) {
+      if (isAborted(signal)) return false
+      throw error
+    }
+    while (await this.groupAlive(sandbox, this.remotePid, signal)) {
+      if (!await waitTick(signal)) return false
+    }
+    return !isAborted(signal)
+  }
+
+  private readyForWait(signal: AbortSignal | undefined): Promise<CommandHandle | undefined> {
+    if (signal === undefined) return this.readyState.promise
+    return new Promise<CommandHandle | undefined>((resolve, reject) => {
+      const onAbort = (): void => { cleanup(); resolve(undefined) }
+      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      if (signal.aborted) {
+        onAbort()
+        return
+      }
+      void this.readyState.promise.then(
+        (handle) => { cleanup(); resolve(handle) },
+        (error: unknown) => { cleanup(); reject(asError(error)) },
+      )
+    })
+  }
+
+  private readonly onAbort = (): void => { this.terminate() }
+
+  private async run(): Promise<SubprocessOutcome> {
+    try {
+      const sandbox = await this.runtime.getSandbox()
+      await this.prepareState(sandbox)
+      const handle = await sandbox.commands.run(
+        commandText(this.spec, this.paths),
+        {
+          background: true,
+          cwd: this.spec.cwd,
+          stdin: this.spec.stdio.stdin !== 'ignore',
+          timeoutMs: 0,
+          ...(this.spec.env !== undefined ? { envs: this.spec.env } : {}),
+          onStdout: async (data) => { await this.dispatchOutput('stdout', data) },
+          onStderr: async (data) => { await this.dispatchOutput('stderr', data) },
+        },
+      )
+      if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
+        throw new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
+      }
+      const completion = handle.wait()
+      void completion.catch(() => {})
+      this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
+      this.readyState.resolve(handle)
+      await this.writeBatchStdin(handle)
+      const outcome = await this.waitForCommand(completion)
+      await this.finalizeSpills(sandbox)
+      return outcome
+    } catch (error: unknown) {
+      this.readyState.reject(error)
+      throw error
+    } finally {
+      this.settled = true
+      this.spec.signal?.removeEventListener('abort', this.onAbort)
+      this.stdout?.end()
+      this.stderr?.end()
+    }
+  }
+
+  private async prepareState(sandbox: Sandbox): Promise<void> {
+    await sandbox.files.makeDir(this.stateDir)
+    const files = [
+      { path: this.paths.pid, data: '' },
+      { path: this.paths.status, data: '' },
+      ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
+      ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
+    ]
+    await sandbox.files.write(files)
+    await sandbox.commands.run([
+      `chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`,
+      `chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`,
+    ].join('\n'))
+  }
+
+  private async writeBatchStdin(handle: CommandHandle): Promise<void> {
+    if (typeof this.spec.stdio.stdin !== 'object') return
+    try {
+      await handle.sendStdin(this.spec.stdio.stdin.data)
+      await handle.closeStdin()
+    } catch (_processClosedItsInput) {
+      // Like the local adapter, batch stdin is best-effort; exit and output remain authoritative.
+    }
+  }
+
+  private async dispatchOutput(stream: 'stdout' | 'stderr', data: string): Promise<void> {
+    try {
+      if (stream === 'stdout') {
+        this.stdoutReader?.push(data)
+        await this.writeOutput(this.stdout, this.spec.stdio.stdout === 'inherit' ? process.stdout : undefined, data)
+        return
+      }
+      this.stderrReader?.push(data)
+      await this.writeOutput(this.stderr, this.spec.stdio.stderr === 'inherit' ? process.stderr : undefined, data)
+    } catch (error: unknown) {
+      const target = stream === 'stdout' ? this.stdout : this.stderr
+      target?.destroy(asError(error))
+    }
+  }
+
+  private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: string): Promise<void> {
+    const target = pipe ?? inherited
+    if (target === undefined || data.length === 0) return
+    if (target.destroyed) throw new Error('subprocess output stream is closed')
+    if (target.write(Buffer.from(data))) return
+    await new Promise<void>((resolve, reject) => {
+      const onDrain = (): void => { cleanup(); resolve() }
+      const onError = (error: Error): void => { cleanup(); reject(error) }
+      const cleanup = (): void => {
+        target.removeListener('drain', onDrain)
+        target.removeListener('error', onError)
+      }
+      target.once('drain', onDrain)
+      target.once('error', onError)
+    })
+  }
+
+  private async waitForProcessGroupId(sandbox: Sandbox, completion: Promise<CommandResult>): Promise<number> {
+    const commandSettled = completion.then(
+      () => true,
+      () => true,
+    )
+    while (true) {
+      const raw = await sandbox.files.read(this.paths.pid)
+      const value = raw.trim()
+      if (value.length > 0) {
+        const pid = Number(value)
+        if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(pid)) {
+          throw new Error(`subprocess-e2b: remote wrapper published invalid process-group id ${JSON.stringify(value)}`)
+        }
+        return pid
+      }
+      const settled = await Promise.race([commandSettled, waitTick().then(() => false)])
+      if (settled) throw new Error('subprocess-e2b: remote command exited before publishing its process-group id')
+    }
+  }
+
+  private async waitForCommand(completion: Promise<CommandResult>): Promise<SubprocessOutcome> {
+    try {
+      const result = await completion
+      return { exitCode: result.exitCode, signal: null }
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError) {
+        return this.terminationSignal === null
+          ? { exitCode: error.exitCode, signal: null }
+          : { exitCode: null, signal: this.terminationSignal }
+      }
+      throw error
+    }
+  }
+
+  private async terminateRemote(): Promise<void> {
+    let handle: CommandHandle
+    try {
+      handle = await this.readyState.promise
+    } catch {
+      return
+    }
+    const sandbox = await this.runtime.getSandbox()
+    this.terminationSignal = 'SIGTERM'
+    await this.signalGroup(sandbox, this.remotePid, 'TERM')
+    const deadline = Date.now() + this.spec.graceMs
+    while (Date.now() < deadline && await this.groupAlive(sandbox, this.remotePid)) {
+      await waitTick()
+    }
+    if (!await this.groupAlive(sandbox, this.remotePid)) return
+    this.terminationSignal = 'SIGKILL'
+    try {
+      await this.signalGroup(sandbox, this.remotePid, 'KILL')
+    } finally {
+      await handle.kill().catch(() => false)
+    }
+  }
+
+  private async signalGroup(sandbox: Sandbox, pid: number, signal: 'TERM' | 'KILL'): Promise<void> {
+    try {
+      await sandbox.commands.run(`kill -${signal} -- -${pid}`)
+    } catch (error: unknown) {
+      if (!(error instanceof CommandExitError)) throw error
+    }
+  }
+
+  private async groupAlive(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<boolean> {
+    try {
+      await sandbox.commands.run(`kill -0 -- -${pid}`, signalOpts(signal))
+      return true
+    } catch (error: unknown) {
+      if (signal?.aborted === true) return false
+      if (error instanceof CommandExitError) return false
+      throw error
+    }
+  }
+
+  private async finalizeSpills(sandbox: Sandbox): Promise<void> {
+    const removals: Promise<void>[] = []
+    const collect = (mode: SubprocessOutputMode, reader: E2BOutputReader | undefined, path: string): void => {
+      if (!hasSpill(mode)) return
+      // A spill mode is a collect mode, so construction always created its reader.
+      const size = (reader as E2BOutputReader).size
+      if (size <= mode.maxBytes || size > mode.spill.maxBytes) {
+        removals.push(sandbox.files.remove(path).catch(() => {}))
+      }
+    }
+    collect(this.spec.stdio.stdout, this.stdoutReader, this.paths.stdout)
+    collect(this.spec.stdio.stderr, this.stderrReader, this.paths.stderr)
+    await Promise.all(removals)
+  }
+}
diff --git a/packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts b/packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts
new file mode 100644
index 0000000000..ff9d48073c
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts
@@ -0,0 +1,725 @@
+import { once } from 'node:events'
+import { Context } from 'cordis'
+import {
+  CommandExitError,
+  type CommandHandle,
+  type CommandResult,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import * as E2BSubprocessInvariant from '../src/invariant.ts'
+import { E2BOutputReader } from '../src/output.ts'
+import { E2BSubprocessHandle } from '../src/process.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import { describe, expect, it, vi } from 'vitest'
+
+function commandError(exitCode: number): CommandExitError {
+  return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
+}
+
+interface StartOptions {
+  background: true
+  cwd: string
+  stdin: boolean
+  timeoutMs: number
+  signal?: AbortSignal
+  envs?: Record<string, string>
+  onStdout?: (data: string) => void | Promise<void>
+  onStderr?: (data: string) => void | Promise<void>
+}
+
+class FakeCommandHandle {
+  pid = 4242
+  readonly sent: Array<string | Uint8Array> = []
+  closes = 0
+  kills = 0
+  killError: unknown
+  private readonly result = Promise.withResolvers<CommandResult>()
+  private settled = false
+
+  wait(): Promise<CommandResult> {
+    return this.result.promise
+  }
+
+  async sendStdin(data: string | Uint8Array): Promise<void> {
+    this.sent.push(data)
+  }
+
+  async closeStdin(): Promise<void> {
+    this.closes += 1
+  }
+
+  async kill(): Promise<boolean> {
+    this.kills += 1
+    if (this.killError !== undefined) throw this.killError
+    return true
+  }
+
+  succeed(exitCode = 0): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.resolve({ exitCode, stdout: '', stderr: '' })
+  }
+
+  fail(exitCode: number): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(commandError(exitCode))
+  }
+
+  crash(error: unknown): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(error)
+  }
+}
+
+class FakeSandbox {
+  readonly handle = new FakeCommandHandle()
+  readonly commandsSeen: string[] = []
+  readonly writtenFiles: string[][] = []
+  readonly removed: string[] = []
+  readonly directories: string[] = []
+  startOptions: StartOptions | undefined
+  backgroundError: unknown
+  nextRemoveError: unknown
+  probeError: unknown
+  signalError: unknown
+  trapsTerm = false
+  alive = true
+  processGroupId = '4242\n'
+  readonly processGroupReads: string[] = []
+  beforeProbe: (() => void) | undefined
+  afterProbe: (() => void) | undefined
+  private startGate: Promise<void> | undefined
+  private openStart: (() => void) | undefined
+
+  deferStart(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.startGate = gate.promise
+    this.openStart = () => { gate.resolve(undefined) }
+  }
+
+  releaseStart(): void {
+    this.openStart?.()
+  }
+
+  finish(exitCode = 0): void {
+    this.alive = false
+    if (exitCode === 0) this.handle.succeed(0)
+    else this.handle.fail(exitCode)
+  }
+
+  async stdout(data: string): Promise<void> {
+    await this.startOptions?.onStdout?.(data)
+  }
+
+  async stderr(data: string): Promise<void> {
+    await this.startOptions?.onStderr?.(data)
+  }
+
+  readonly sandbox = {
+    sandboxId: 'fake',
+    files: {
+      makeDir: async (path: string): Promise<boolean> => {
+        this.directories.push(path)
+        return true
+      },
+      write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
+        this.writtenFiles.push(files.map(file => file.path))
+        return files.map(() => ({}))
+      },
+      read: async (): Promise<string> => this.processGroupReads.shift() ?? this.processGroupId,
+      remove: async (path: string): Promise<void> => {
+        this.removed.push(path)
+        if (this.nextRemoveError !== undefined) {
+          const error = this.nextRemoveError
+          this.nextRemoveError = undefined
+          throw error
+        }
+      },
+    },
+    commands: {
+      run: async (command: string, options?: StartOptions | { signal?: AbortSignal }): Promise<CommandHandle | CommandResult> => {
+        this.commandsSeen.push(command)
+        if (command.startsWith('kill -0 ')) {
+          this.beforeProbe?.()
+          if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
+          if (this.probeError !== undefined) {
+            const error = this.probeError
+            this.probeError = undefined
+            throw error
+          }
+          if (!this.alive) throw commandError(1)
+          this.afterProbe?.()
+          return { exitCode: 0, stdout: '', stderr: '' }
+        }
+        if (command.startsWith('kill -TERM ')) {
+          if (this.signalError !== undefined) {
+            const error = this.signalError
+            this.signalError = undefined
+            throw error
+          }
+          if (!this.trapsTerm) {
+            this.alive = false
+            this.handle.fail(143)
+          }
+          return { exitCode: 0, stdout: '', stderr: '' }
+        }
+        if (command.startsWith('kill -KILL ')) {
+          if (this.signalError !== undefined) {
+            const error = this.signalError
+            this.signalError = undefined
+            throw error
+          }
+          this.alive = false
+          this.handle.fail(137)
+          return { exitCode: 0, stdout: '', stderr: '' }
+        }
+        if ((options as StartOptions | undefined)?.background === true) {
+          this.startOptions = options as StartOptions
+          await this.startGate
+          if (this.backgroundError !== undefined) throw this.backgroundError
+          return this.handle as unknown as CommandHandle
+        }
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+  } as unknown as Sandbox
+}
+
+function spec(overrides: Partial<SubprocessSpawnSpec> = {}): SubprocessSpawnSpec {
+  return {
+    argv: ['bash', '-c', 'printf ok'],
+    cwd: '/workspace',
+    stdio: {
+      stdin: 'ignore',
+      stdout: { maxBytes: 4, spill: { maxBytes: 16 } },
+      stderr: { maxBytes: 4 },
+    },
+    graceMs: 5,
+    ...overrides,
+  }
+}
+
+function runtime(fake: FakeSandbox, getSandbox: () => Promise<Sandbox> = async () => fake.sandbox): E2BSandboxService {
+  return {
+    cwd: '/workspace',
+    runtimeRoot: '/workspace/.dsh-e2b',
+    disposeMode: 'kill',
+    getSandbox,
+  } as unknown as E2BSandboxService
+}
+
+async function flush(): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, 0))
+}
+
+describe('E2BOutputReader', () => {
+  it('keeps a byte-exact tail with independent whole-stream cursors', () => {
+    const reader = new E2BOutputReader(4, 10, '/remote/spill')
+    reader.push('')
+    reader.push('ab')
+    reader.push('cdef')
+    expect(reader.size).toBe(6)
+    expect(reader.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true, spillPath: '/remote/spill' })
+    expect(reader.readFrom(2)).toEqual({ text: 'cdef', nextOffset: 6, lossy: false })
+    expect(reader.readFrom(5)).toEqual({ text: 'f', nextOffset: 6, lossy: false })
+    expect(reader.readFrom(99)).toEqual({ text: '', nextOffset: 6, lossy: false })
+  })
+
+  it('drops whole head chunks and withholds absent or over-cap spills', () => {
+    const withoutSpill = new E2BOutputReader(2, undefined, '/unused')
+    withoutSpill.push('ab')
+    withoutSpill.push('cd')
+    expect(withoutSpill.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
+    const overCap = new E2BOutputReader(2, 3, '/too-small')
+    overCap.push('abcd')
+    expect(overCap.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
+    expect(() => overCap.readFrom(-1)).toThrow(/non-negative safe integer/)
+    expect(() => overCap.readFrom(1.5)).toThrow(/non-negative safe integer/)
+  })
+})
+
+describe('E2BSubprocessHandle', () => {
+  it('starts asynchronously, keeps secrets out of the command, and supports deferred piped stdin/output', async () => {
+    const fake = new FakeSandbox()
+    fake.processGroupId = '4343\n'
+    fake.deferStart()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      argv: ['tool', 'argument with spaces'],
+      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 8, spill: { maxBytes: 32 } } },
+      env: { PATH: '/bin', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' },
+    }), '/workspace/.dsh-e2b/processes/one')
+    expect(handle.pid).toBe(-1)
+    handle.stdin!.write('hello')
+    handle.stdin!.end()
+    fake.releaseStart()
+    await flush()
+    expect(handle.pid).toBe(4343)
+    expect(fake.handle.sent.map(value => String(value))).toEqual(['hello'])
+    expect(fake.handle.closes).toBe(1)
+    expect(fake.startOptions?.envs).toEqual({ PATH: '/bin', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' })
+    const command = fake.commandsSeen.find(value => value.startsWith('exec setsid'))!
+    expect(command).toContain('exec setsid --wait -- bash -c')
+    expect(command).toContain('DEEPSEEK_API_KEY')
+    expect(command).toContain('DSH_MODE')
+    expect(command).not.toContain('explicit-secret')
+    expect(fake.writtenFiles[0]).toEqual([
+      '/workspace/.dsh-e2b/processes/one/pid',
+      '/workspace/.dsh-e2b/processes/one/exit-code',
+      '/workspace/.dsh-e2b/processes/one/stderr.log',
+    ])
+
+    let piped = ''
+    handle.stdout!.on('data', (chunk) => { piped += String(chunk) })
+    await fake.stdout('pipe-data')
+    await fake.stderr('err')
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(piped).toBe('pipe-data')
+    expect(handle.collected.stderr!.readFrom(0)).toMatchObject({ text: 'err', lossy: false })
+    expect(fake.removed).toContain('/workspace/.dsh-e2b/processes/one/stderr.log')
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
+  it('surfaces deferred piped-stdin write and close failures as stream errors', async () => {
+    const writeFake = new FakeSandbox()
+    writeFake.deferStart()
+    vi.spyOn(writeFake.handle, 'sendStdin').mockRejectedValueOnce('stdin rejected')
+    const writeHandle = new E2BSubprocessHandle(runtime(writeFake), spec({
+      stdio: { stdin: 'pipe', stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
+    }), '/runtime/stdin-write-error')
+    const writeError = once(writeHandle.stdin!, 'error')
+    writeHandle.stdin!.write('input')
+    writeFake.releaseStart()
+    await expect(writeError).resolves.toMatchObject([{ message: 'stdin rejected' }])
+    writeFake.finish()
+    await writeHandle.done
+
+    const closeFake = new FakeSandbox()
+    vi.spyOn(closeFake.handle, 'closeStdin').mockRejectedValueOnce(new Error('close rejected'))
+    const closeHandle = new E2BSubprocessHandle(runtime(closeFake), spec({
+      stdio: { stdin: 'pipe', stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
+    }), '/runtime/stdin-close-error')
+    await flush()
+    const closeError = once(closeHandle.stdin!, 'error')
+    closeHandle.stdin!.end()
+    await expect(closeError).resolves.toMatchObject([{ message: 'close rejected' }])
+    closeFake.finish()
+    await closeHandle.done
+  })
+
+  it('collects bounded tails, retains valid spills, and maps natural nonzero exits', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: {
+        stdin: { data: 'batch' },
+        stdout: { maxBytes: 4, spill: { maxBytes: 16 } },
+        stderr: { maxBytes: 3 },
+      },
+    }), '/runtime/two')
+    await flush()
+    await fake.stdout('abcdef')
+    await fake.stderr('12345')
+    fake.finish(7)
+    await expect(handle.done).resolves.toEqual({ exitCode: 7, signal: null })
+    expect(fake.handle.sent).toEqual(['batch'])
+    expect(fake.handle.closes).toBe(1)
+    expect(handle.collected.stdout!.readFrom(0)).toEqual({
+      text: 'cdef',
+      nextOffset: 6,
+      lossy: true,
+      spillPath: '/runtime/two/stdout.log',
+    })
+    expect(handle.collected.stderr!.readFrom(0)).toEqual({ text: '345', nextOffset: 5, lossy: true })
+    expect(fake.removed).not.toContain('/runtime/two/stdout.log')
+  })
+
+  it('removes a spill once the complete stream exceeds its cap', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: { maxBytes: 2, spill: { maxBytes: 3 } }, stderr: 'inherit' },
+    }), '/runtime/oversize')
+    await flush()
+    await fake.stdout('abcd')
+    await fake.stderr('')
+    fake.finish()
+    await handle.done
+    expect(handle.collected.stdout!.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
+    expect(fake.removed).toContain('/runtime/oversize/stdout.log')
+  })
+
+  it('contains remote spill-removal failures and routes empty inherited output', async () => {
+    const fake = new FakeSandbox()
+    fake.nextRemoveError = new Error('already removed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'inherit', stderr: { maxBytes: 4, spill: { maxBytes: 8 } } },
+    }), '/runtime/remove-error')
+    await flush()
+    await fake.stdout('')
+    await fake.stderr('')
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(fake.removed).toContain('/runtime/remove-error/stderr.log')
+  })
+
+  it('terminates a process group with TERM and reports the signal outcome', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/term')
+    await flush()
+    handle.terminate()
+    handle.terminate()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
+    expect(fake.commandsSeen).not.toContain('kill -KILL -- -4242')
+  })
+
+  it('escalates a TERM-trapping process group to KILL and uses the SDK kill as fallback', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    fake.handle.killError = new Error('already gone')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/kill')
+    await flush()
+    handle.terminate()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(fake.commandsSeen).toContain('kill -KILL -- -4242')
+    expect(fake.handle.kills).toBe(1)
+  })
+
+  it('honors termination requested before asynchronous startup finishes', async () => {
+    const fake = new FakeSandbox()
+    fake.deferStart()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/deferred-kill')
+    handle.terminate()
+    fake.releaseStart()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+  })
+
+  it('honors an already-aborted signal when constructing the asynchronous handle directly', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ signal: AbortSignal.abort('stop') }), '/runtime/pre-aborted')
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+  })
+
+  it('reacts to a signal that aborts after the remote command has started', async () => {
+    const fake = new FakeSandbox()
+    const controller = new AbortController()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ signal: controller.signal }), '/runtime/live-abort')
+    await flush()
+    controller.abort('stop')
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+  })
+
+  it('bounds waitForExit while startup or a live group is pending', async () => {
+    const fake = new FakeSandbox()
+    fake.deferStart()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/wait')
+    const beforeStart = new AbortController()
+    const pending = handle.waitForExit(beforeStart.signal)
+    beforeStart.abort()
+    await expect(pending).resolves.toBe(false)
+    await expect(handle.waitForExit(AbortSignal.abort())).resolves.toBe(false)
+    fake.releaseStart()
+    await flush()
+    const live = new AbortController()
+    const liveWait = handle.waitForExit(live.signal)
+    live.abort()
+    await expect(liveWait).resolves.toBe(false)
+    fake.finish()
+    await handle.done
+  })
+
+  it('bounds both sides of the liveness-poll abort race', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/poll-abort')
+    await flush()
+
+    const beforeTick = new AbortController()
+    fake.afterProbe = () => { beforeTick.abort(); fake.afterProbe = undefined }
+    await expect(handle.waitForExit(beforeTick.signal)).resolves.toBe(false)
+
+    const duringTick = new AbortController()
+    fake.afterProbe = () => {
+      fake.afterProbe = undefined
+      setTimeout(() => { duringTick.abort() }, 0)
+    }
+    await expect(handle.waitForExit(duringTick.signal)).resolves.toBe(false)
+
+    const duringProbe = new AbortController()
+    fake.beforeProbe = () => { duringProbe.abort(); fake.beforeProbe = undefined }
+    await expect(handle.waitForExit(duringProbe.signal)).resolves.toBe(false)
+    fake.finish()
+    await handle.done
+  })
+
+  it('observes a live group across one successful bounded poll', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/poll-success')
+    await flush()
+    setTimeout(() => { fake.finish() }, 1)
+    await expect(handle.waitForExit(new AbortController().signal)).resolves.toBe(true)
+    await handle.done
+  })
+
+  it('treats startup failure as no live tree and contains readiness rejection', async () => {
+    const fake = new FakeSandbox()
+    fake.backgroundError = new Error('start failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/fail')
+    await expect(handle.done).rejects.toThrow('start failed')
+    expect(handle.pid).toBe(-1)
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    handle.terminate()
+  })
+
+  it('bounds a readiness rejection with a still-live caller signal', async () => {
+    const fake = new FakeSandbox()
+    fake.deferStart()
+    fake.backgroundError = new Error('start failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/fail-with-signal')
+    const waiting = handle.waitForExit(new AbortController().signal)
+    fake.releaseStart()
+    await expect(handle.done).rejects.toThrow('start failed')
+    await expect(waiting).resolves.toBe(true)
+  })
+
+  it('propagates an unavailable sandbox unless the caller aborts the wait', async () => {
+    const fake = new FakeSandbox()
+    let calls = 0
+    const unavailable = runtime(fake, async () => {
+      calls += 1
+      if (calls === 1) return fake.sandbox
+      throw new Error('connection unavailable')
+    })
+    const handle = new E2BSubprocessHandle(unavailable, spec(), '/runtime/unavailable')
+    await flush()
+    await expect(handle.waitForExit()).rejects.toThrow('connection unavailable')
+    fake.finish()
+    await handle.done
+  })
+
+  it('returns false when the caller aborts while reconnecting for liveness', async () => {
+    const fake = new FakeSandbox()
+    const reconnect = Promise.withResolvers<Sandbox>()
+    let calls = 0
+    const unavailable = runtime(fake, async () => {
+      calls += 1
+      return calls === 1 ? fake.sandbox : await reconnect.promise
+    })
+    const handle = new E2BSubprocessHandle(unavailable, spec(), '/runtime/reconnect-abort')
+    await flush()
+    const controller = new AbortController()
+    const waiting = handle.waitForExit(controller.signal)
+    await flush()
+    controller.abort()
+    reconnect.reject(new Error('connection unavailable'))
+    await expect(waiting).resolves.toBe(false)
+    fake.finish()
+    await handle.done
+  })
+
+  it('returns false when a liveness request itself is aborted and surfaces other probe failures', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/probe')
+    await flush()
+    const controller = new AbortController()
+    controller.abort()
+    await expect(handle.waitForExit(controller.signal)).resolves.toBe(false)
+    fake.probeError = new Error('probe failed')
+    await expect(handle.waitForExit()).rejects.toThrow('probe failed')
+    fake.finish()
+    await handle.done
+  })
+
+  it('makes batch stdin close failures best-effort', async () => {
+    const fake = new FakeSandbox()
+    vi.spyOn(fake.handle, 'sendStdin').mockRejectedValueOnce(new Error('closed'))
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: { data: 'ignored' }, stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
+    }), '/runtime/stdin-closed')
+    await flush()
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
+  it('rejects malformed SDK process ids and non-command settlement failures', async () => {
+    const invalidPid = new FakeSandbox()
+    invalidPid.handle.pid = 0
+    const invalid = new E2BSubprocessHandle(runtime(invalidPid), spec(), '/runtime/invalid-pid')
+    await expect(invalid.done).rejects.toThrow(/invalid command pid 0/)
+    await expect(invalid.waitForExit()).resolves.toBe(true)
+
+    const crashedFake = new FakeSandbox()
+    const crashed = new E2BSubprocessHandle(runtime(crashedFake), spec(), '/runtime/crashed')
+    await flush()
+    crashedFake.alive = false
+    crashedFake.handle.crash(new Error('command transport failed'))
+    await expect(crashed.done).rejects.toThrow('command transport failed')
+  })
+
+  it('rejects invalid or absent process-group publication', async () => {
+    const invalidGroup = new FakeSandbox()
+    invalidGroup.processGroupId = 'not-a-pid\n'
+    const invalid = new E2BSubprocessHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
+    await expect(invalid.done).rejects.toThrow(/invalid process-group id/)
+
+    const absentGroup = new FakeSandbox()
+    absentGroup.processGroupId = ''
+    const absent = new E2BSubprocessHandle(runtime(absentGroup), spec(), '/runtime/absent-group')
+    await flush()
+    absentGroup.finish()
+    await expect(absent.done).rejects.toThrow(/exited before publishing/)
+  })
+
+  it('waits for delayed process-group publication', async () => {
+    const fake = new FakeSandbox()
+    fake.processGroupReads.push('', '4242\n')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/delayed-group')
+    await vi.waitFor(() => { expect(handle.pid).toBe(4242) })
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
+  it('handles output backpressure and contains a stderr sink failure', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
+    }), '/runtime/backpressure')
+    await flush()
+
+    handle.stdout!.on('error', () => {})
+    const stdoutWrite = vi.spyOn(handle.stdout!, 'write').mockReturnValueOnce(false)
+    const stdoutPending = fake.stdout('blocked')
+    queueMicrotask(() => { handle.stdout!.emit('drain') })
+    await stdoutPending
+    stdoutWrite.mockRestore()
+
+    handle.stderr!.on('error', () => {})
+    const stderrWrite = vi.spyOn(handle.stderr!, 'write').mockReturnValueOnce(false)
+    const stderrPending = fake.stderr('broken')
+    queueMicrotask(() => { handle.stderr!.emit('error', new Error('sink failed')) })
+    await stderrPending
+    stderrWrite.mockRestore()
+
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
+  it('contains a pipe callback failure instead of rejecting command settlement', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/pipe-error')
+    await flush()
+    const emitted = once(handle.stdout!, 'error')
+    handle.stdout!.destroy(new Error('consumer failed'))
+    await emitted
+    await fake.stdout('late output')
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
+  it('contains an already-gone group signal and observes non-command signal failures', async () => {
+    const gone = new FakeSandbox()
+    gone.trapsTerm = true
+    gone.signalError = commandError(1)
+    const goneHandle = new E2BSubprocessHandle(runtime(gone), spec({ graceMs: 1 }), '/runtime/gone-signal')
+    await flush()
+    goneHandle.terminate()
+    await expect(goneHandle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+
+    const failed = new FakeSandbox()
+    failed.signalError = new Error('signal transport failed')
+    const failedHandle = new E2BSubprocessHandle(runtime(failed), spec(), '/runtime/failed-signal')
+    await flush()
+    failedHandle.terminate()
+    await flush()
+    failed.finish()
+    await expect(failedHandle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+})
+
+describe('E2BSubprocessService', () => {
+  async function service(
+    fake = new FakeSandbox(),
+    providedRuntime: E2BSandboxService = runtime(fake),
+  ): Promise<{ ctx: Context; fiber: Awaited<ReturnType<Context['plugin']>> }> {
+    const ctx = new Context()
+    ctx.provide('e2b', providedRuntime)
+    const fiber = await ctx.plugin(E2BSubprocessService)
+    return { ctx, fiber }
+  }
+
+  it('registers handles and disposal terminates and joins live remote groups regardless of sandbox policy', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    const { ctx, fiber } = await service(fake)
+    const handle = ctx.subprocess.spawn(spec({ graceMs: 1 }))
+    await flush()
+    await fiber.dispose()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    expect(fake.alive).toBe(false)
+  })
+
+  it('releases naturally settled handles before later service disposal', async () => {
+    const fake = new FakeSandbox()
+    const { ctx, fiber } = await service(fake)
+    const handle = ctx.subprocess.spawn(spec())
+    await flush()
+    fake.finish()
+    await handle.done
+    await flush()
+    const signalsBefore = fake.commandsSeen.filter(command => command.startsWith('kill -')).length
+    await fiber.dispose()
+    expect(fake.commandsSeen.filter(command => command.startsWith('kill -')).length).toBe(signalsBefore)
+  })
+
+  it('contains a release liveness failure and retries quiescence during disposal', async () => {
+    const fake = new FakeSandbox()
+    let calls = 0
+    const reconnecting = runtime(fake, async () => {
+      calls += 1
+      if (calls === 2) throw new Error('transient liveness failure')
+      return fake.sandbox
+    })
+    const { ctx, fiber } = await service(fake, reconnecting)
+    const handle = ctx.subprocess.spawn(spec())
+    await flush()
+    fake.finish()
+    await handle.done
+    await flush()
+    await fiber.dispose()
+    expect(calls).toBeGreaterThanOrEqual(3)
+  })
+
+  it('contains spawn rejection while disposal is joining the pending handle', async () => {
+    const fake = new FakeSandbox()
+    fake.deferStart()
+    fake.backgroundError = new Error('start failed during disposal')
+    const { ctx, fiber } = await service(fake)
+    const handle = ctx.subprocess.spawn(spec())
+    const disposing = fiber.dispose()
+    fake.releaseStart()
+    await expect(disposing).resolves.toBeUndefined()
+    await expect(handle.done).rejects.toThrow('start failed during disposal')
+  })
+
+  it('validates synchronous spawn preconditions', async () => {
+    const { ctx } = await service()
+    expect(() => ctx.subprocess.spawn(spec({ argv: [] }))).toThrow(/non-empty program/)
+    expect(() => ctx.subprocess.spawn(spec({ graceMs: 0 }))).toThrow(/positive finite/)
+    expect(() => ctx.subprocess.spawn(spec({ signal: AbortSignal.abort('stop') }))).toThrow(/aborted before spawn/)
+    expect(() => ctx.subprocess.spawn(spec({ signal: { aborted: true, reason: undefined } as AbortSignal }))).toThrow(/aborted$/)
+  })
+
+  it('registers the package-owned empty invariant installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BSubprocessInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/subprocess/subprocess-e2b/tsconfig.json b/packages/subprocess/subprocess-e2b/tsconfig.json
new file mode 100644
index 0000000000..f3bb8c2a26
--- /dev/null
+++ b/packages/subprocess/subprocess-e2b/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../e2b/e2b"
+    },
+    {
+      "path": "../subprocess"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 256ae90caa..b17cc5b4f8 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -301,6 +301,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   PermissionSelect: 'permissions projection payload is owned by packages/ui/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
   ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
+  Sandbox: 'external E2B SDK handle is owned by packages/e2b/e2b/README.md',
   SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
   SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
   SubagentRunInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 3ca0317cf4..90aa22e322 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -50,6 +50,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
+  'packages/e2b/e2b': { kind: 'none', reason: 'The shared remote-runtime owner registers no model context; provider adapters and consumers own rendered effects.' },
   'packages/client/hmr': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/modules': { kind: 'none', reason: 'Browser-side module-loading kernel machinery; registers no model surface.' },
   'packages/client/test-runtime': { kind: 'none', reason: 'Browser-side test infrastructure (jsdom bench); registers no model surface.' },
@@ -82,6 +83,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/web': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/examples/agent-spine-demo': { kind: 'indirect', reason: 'The bundle only mounts model-facing child plugins.' },
   'packages/fs/fs': { kind: 'indirect', reason: 'The service interface delegates model rendering to dsh-tool-fs.' },
+  'packages/fs/fs-e2b': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/fs/fs-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
   'packages/host/apiproxy': { kind: 'none', reason: 'The wire contract and fetch carriers move already-composed messages and register no model surface.' },
@@ -98,6 +100,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
   'packages/lsp/lsp-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/subprocess/subprocess': { kind: 'indirect', reason: 'The seam delegates all model rendering to consumer seams such as the bash executor family.' },
+  'packages/subprocess/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/subprocess/subprocess-local': { kind: 'indirect', reason: 'The spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
   'packages/sdk/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index de9b63459c..8380182e83 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -188,6 +188,7 @@
         "./packages/bash/*/src",
         "./packages/pty/*/src",
         "./packages/subprocess/*/src",
+        "./packages/e2b/*/src",
         "./packages/code-runtime/*/src",
         "./packages/fs/*/src",
         "./packages/lsp/*/src",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 1a8ef6508a..03b1bcd2dd 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -162,6 +162,8 @@
     { "path": "./packages/examples/agent-spine-demo" },
     { "path": "./packages/subprocess/subprocess" },
     { "path": "./packages/subprocess/subprocess-local" },
+    { "path": "./packages/e2b/e2b" },
+    { "path": "./packages/subprocess/subprocess-e2b" },
     { "path": "./packages/bash/bash" },
     { "path": "./packages/pty/pty" },
     { "path": "./packages/pty/pty-local" },
@@ -183,6 +185,7 @@
     { "path": "./packages/bash/tool-bash" },
     { "path": "./packages/fs/fs" },
     { "path": "./packages/fs/fs-local" },
+    { "path": "./packages/fs/fs-e2b" },
     { "path": "./packages/fs/fs-policy" },
     { "path": "./packages/fs/fs-sandbox" },
     { "path": "./packages/fs/tool-fs" },

From 6667102890ce0cf50f6122ecb676a4deccd60499 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 13:59:47 +0800
Subject: [PATCH 353/516] Add E2B PTY, LSP, and code runtime providers

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |  11 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |  11 +-
 ...active-semantic-code-runtime-poc.i18n.yaml |   6 +
 ...b-interactive-semantic-code-runtime-poc.md |  57 ++
 ...nteractive-semantic-code-runtime-poc.zh.md |  57 ++
 docs/cordis-catalog/services.md               |   4 +-
 examples/headless-agent/e2b.cordis.yml        |  34 +-
 .../tests/fixtures/e2b/e2b/bin.ts             | 143 +++++
 .../tests/fixtures/e2b/e2b/cordis.yml         |  40 ++
 .../tests/fixtures/e2b/e2b/fixture-lsp.mjs    |  85 +++
 examples/package.json                         |   5 +
 packages/code-runtime/README.i18n.yaml        |   4 +-
 packages/code-runtime/README.md               |   9 +-
 packages/code-runtime/README.zh.md            |  13 +-
 .../code-runtime-e2b/README.i18n.yaml         |   6 +
 .../code-runtime/code-runtime-e2b/README.md   |  44 ++
 .../code-runtime-e2b/README.zh.md             |  44 ++
 .../code-runtime-e2b/package.json             |  52 ++
 .../code-runtime-e2b/src/index.ts             | 441 +++++++++++++++
 .../code-runtime-e2b/src/invariant.ts         |  20 +
 .../code-runtime-e2b/src/runner-source.ts     | 460 ++++++++++++++++
 .../code-runtime-e2b/tests/runtime.spec.ts    | 460 ++++++++++++++++
 .../code-runtime-e2b/tsconfig.json            |  20 +
 .../code-runtime-worker/README.i18n.yaml      |   4 +-
 .../code-runtime-worker/README.md             |   6 +-
 .../code-runtime-worker/README.zh.md          |  26 +-
 .../code-runtime-worker/src/index.ts          |  35 +-
 .../code-runtime/README.i18n.yaml             |   4 +-
 packages/code-runtime/code-runtime/README.md  |   2 +-
 .../code-runtime/code-runtime/README.zh.md    |  20 +-
 packages/e2b/README.i18n.yaml                 |   4 +-
 packages/e2b/README.md                        |   7 +-
 packages/e2b/README.zh.md                     |   7 +-
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/frame.ts                 |  75 +++
 packages/e2b/e2b/src/index.ts                 |  24 +-
 packages/e2b/e2b/tests/composition.e2e.ts     |  42 +-
 packages/e2b/e2b/tests/e2b.spec.ts            |  46 ++
 packages/lsp/README.i18n.yaml                 |   4 +-
 packages/lsp/README.md                        |   5 +-
 packages/lsp/README.zh.md                     |   5 +-
 packages/lsp/lsp-e2b/README.i18n.yaml         |   6 +
 packages/lsp/lsp-e2b/README.md                |  47 ++
 packages/lsp/lsp-e2b/README.zh.md             |  47 ++
 packages/lsp/lsp-e2b/package.json             |  52 ++
 packages/lsp/lsp-e2b/src/index.ts             | 358 ++++++++++++
 packages/lsp/lsp-e2b/src/invariant.ts         |  20 +
 packages/lsp/lsp-e2b/src/proxy-source.ts      |  55 ++
 packages/lsp/lsp-e2b/src/transport.ts         | 183 +++++++
 packages/lsp/lsp-e2b/tests/provider.spec.ts   | 397 ++++++++++++++
 packages/lsp/lsp-e2b/tests/transport.spec.ts  | 181 +++++++
 packages/lsp/lsp-e2b/tsconfig.json            |  20 +
 packages/lsp/lsp-local/src/instance.ts        |  22 +-
 .../lsp/lsp-local/tests/fixture-server.ts     |   6 +
 packages/lsp/lsp-local/tests/instance.spec.ts |   5 +
 packages/lsp/lsp/README.i18n.yaml             |   4 +-
 packages/lsp/lsp/README.md                    |   1 +
 packages/lsp/lsp/README.zh.md                 |   1 +
 packages/pty/README.i18n.yaml                 |   4 +-
 packages/pty/README.md                        |   5 +-
 packages/pty/README.zh.md                     |   5 +-
 packages/pty/pty-e2b/README.i18n.yaml         |   6 +
 packages/pty/pty-e2b/README.md                |  54 ++
 packages/pty/pty-e2b/README.zh.md             |  54 ++
 packages/pty/pty-e2b/package.json             |  46 ++
 packages/pty/pty-e2b/src/config.ts            |  64 +++
 packages/pty/pty-e2b/src/index.ts             |  93 ++++
 packages/pty/pty-e2b/src/invariant.ts         |  20 +
 packages/pty/pty-e2b/src/session.ts           | 367 +++++++++++++
 packages/pty/pty-e2b/tests/index.spec.ts      | 195 +++++++
 packages/pty/pty-e2b/tests/session.spec.ts    | 398 ++++++++++++++
 packages/pty/pty-e2b/tsconfig.json            |  16 +
 packages/pty/pty-local/src/sanitize.ts        | 188 -------
 packages/pty/pty-local/src/session.ts         | 511 ++++++------------
 packages/pty/pty-local/tests/sanitize.spec.ts |  34 +-
 packages/pty/pty/src/index.ts                 |   9 +
 packages/pty/pty/src/terminal.ts              | 273 ++++++++++
 .../verify-package-readme-model-experience.ts |   2 +
 tsconfig.host.json                            |   3 +
 82 files changed, 5462 insertions(+), 644 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
 create mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
 create mode 100644 examples/headless-agent/tests/fixtures/e2b/e2b/fixture-lsp.mjs
 create mode 100644 packages/code-runtime/code-runtime-e2b/README.i18n.yaml
 create mode 100644 packages/code-runtime/code-runtime-e2b/README.md
 create mode 100644 packages/code-runtime/code-runtime-e2b/README.zh.md
 create mode 100644 packages/code-runtime/code-runtime-e2b/package.json
 create mode 100644 packages/code-runtime/code-runtime-e2b/src/index.ts
 create mode 100644 packages/code-runtime/code-runtime-e2b/src/invariant.ts
 create mode 100644 packages/code-runtime/code-runtime-e2b/src/runner-source.ts
 create mode 100644 packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts
 create mode 100644 packages/code-runtime/code-runtime-e2b/tsconfig.json
 create mode 100644 packages/e2b/e2b/src/frame.ts
 create mode 100644 packages/lsp/lsp-e2b/README.i18n.yaml
 create mode 100644 packages/lsp/lsp-e2b/README.md
 create mode 100644 packages/lsp/lsp-e2b/README.zh.md
 create mode 100644 packages/lsp/lsp-e2b/package.json
 create mode 100644 packages/lsp/lsp-e2b/src/index.ts
 create mode 100644 packages/lsp/lsp-e2b/src/invariant.ts
 create mode 100644 packages/lsp/lsp-e2b/src/proxy-source.ts
 create mode 100644 packages/lsp/lsp-e2b/src/transport.ts
 create mode 100644 packages/lsp/lsp-e2b/tests/provider.spec.ts
 create mode 100644 packages/lsp/lsp-e2b/tests/transport.spec.ts
 create mode 100644 packages/lsp/lsp-e2b/tsconfig.json
 create mode 100644 packages/pty/pty-e2b/README.i18n.yaml
 create mode 100644 packages/pty/pty-e2b/README.md
 create mode 100644 packages/pty/pty-e2b/README.zh.md
 create mode 100644 packages/pty/pty-e2b/package.json
 create mode 100644 packages/pty/pty-e2b/src/config.ts
 create mode 100644 packages/pty/pty-e2b/src/index.ts
 create mode 100644 packages/pty/pty-e2b/src/invariant.ts
 create mode 100644 packages/pty/pty-e2b/src/session.ts
 create mode 100644 packages/pty/pty-e2b/tests/index.spec.ts
 create mode 100644 packages/pty/pty-e2b/tests/session.spec.ts
 create mode 100644 packages/pty/pty-e2b/tsconfig.json
 delete mode 100644 packages/pty/pty-local/src/sanitize.ts
 create mode 100644 packages/pty/pty/src/terminal.ts

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 13d081c28f..46f1849b07 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 307a08d6ca77c83bf836bc8d50b071fbf33ac49a
-2026-07-27-e2b-remote-runtime-poc.zh.md: bb4e657d999760f000949d509228bbb65f22773a
+2026-07-27-e2b-remote-runtime-poc.md: 730e6f0e1958ccab43a5a6a11931f9407b38ef16
+2026-07-27-e2b-remote-runtime-poc.zh.md: 5f1ae07b985787a7dc1bd61f2a5b7ff0512d85c1
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index 307a08d6ca..730e6f0e19 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -16,18 +16,19 @@ The E2B integration is a provider-composition POC with one shared lifecycle owne
 - `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
 - `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands and remote Linux process groups.
 - The existing `@deepseek-ai/dsh-bash-local` remains the Bash implementation because it delegates all process mechanics to `ctx.subprocess`.
+- PTY, LSP, and Code Runtime remain separate capability providers over the same owner, with their runtime split recorded in the [extension decision](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
 
 The owner is the sole source of sandbox identity. Providers inject it and never create private sandboxes. The composition therefore gives filesystem tools and Bash one remote cwd, process namespace, and spill/state directory while preserving the existing capability interfaces and model-facing tools.
 
 ## POC boundary
 
-Only filesystem state, command processes during the provider lifetime, and adapter-owned remote files move into E2B. The host retains Cordis and plugin objects, the agent loop, agent/session state, session logs and persistence, model requests, skills, subagent orchestration, and E2B SDK buffers. The overlay does not upload or mount the host workspace; identical cwd strings name independent host and remote directories. Managed process groups still terminate and join when the subprocess service disposes, including before a retained-sandbox pause or leave disposition.
+Filesystem state, managed commands, interactive shells, language servers, code workers, and adapter-owned files move into E2B. The host retains Cordis and plugin objects, the agent loop, agent/session state, session logs and persistence, model requests, skills, subagent orchestration, capability protocol state, and E2B SDK buffers. The overlay does not upload or mount the host workspace; identical cwd strings name independent host and remote directories. Managed process groups still terminate and join when their provider disposes, including before a retained-sandbox pause or leave disposition.
 
-The POC has no PTY adapter, LSP-specific integration, session-persistence backend, code-runtime backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, or workspace synchronization. Retained sandbox reconnect proves lifecycle continuity only; it does not reconstruct host process handles, output cursors, or locks.
+The POC has no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, or workspace synchronization. Retained sandbox reconnect proves lifecycle continuity only; it does not reconstruct host PTY/LSP/code-runtime state, process handles, output cursors, pending calls, or locks.
 
 ## Verification
 
-Package tests pin lifecycle cleanup, filesystem seam semantics, subprocess group/stdio/abort behavior, and the package-owned invariant registrations. A credential-gated real Loader composition creates one sandbox, proves FS-write→Bash-read and Bash-write→FS-read in the same remote cwd, proves neither file appears in the host cwd, disposes the composition, and confirms the sandbox id is gone.
+Package tests pin lifecycle cleanup, filesystem semantics, subprocess groups, byte framing, PTY readiness/signals, LSP transport and containment, Code Runtime binding/output behavior, and package-owned invariant registrations. A credential-gated real Loader composition creates one sandbox, exercises filesystem, Bash/subprocess, PTY, LSP, and Code Runtime through source and built package paths, proves host-workspace isolation, disposes the composition, and confirms the sandbox id is gone.
 
 ## Alternatives considered
 
@@ -35,7 +36,7 @@ Package tests pin lifecycle cleanup, filesystem seam semantics, subprocess group
 
 **Run the entire harness process inside E2B** — rejected because it changes deployment, credential flow, model transport, session durability, plugin loading, and supervision at once. Those questions are independent of proving the provider seams.
 
-**Add E2B-specific Bash, PTY, LSP, persistence, and synchronization packages together** — rejected because Bash already has the required subprocess seam and the other capabilities need separate consumer evidence and lifecycle designs. Their absence is an explicit fidelity boundary, not an incomplete hidden plan.
+**Put every E2B capability in the shared owner package** — rejected because lifecycle identity is the owner's only concern. Filesystem, subprocess, PTY, LSP, and Code Runtime retain separate provider contracts, configuration, tests, and consumers; Bash continues to reuse its subprocess seam.
 
 **Implement filesystem operations through shell commands only** — rejected because that bypasses `ctx.fs` identity, structured errors, version guards, streaming reads, and atomic mutation semantics already consumed by the file tools.
 
@@ -43,4 +44,4 @@ Package tests pin lifecycle cleanup, filesystem seam semantics, subprocess group
 
 The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual state retention for experiments, while kill remains the demo's cleanup policy.
 
-The provider is not interchangeable with the local subprocess backend for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, callback output is not byte-faithful, signal attribution is inferred, and reconnect cannot restore handles. Remote process/spill artifacts accumulate in a retained sandbox. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
+The provider is not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index bb4e657d99..5f1ae07b98 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -16,18 +16,19 @@ E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和
 - `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
 - `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands 和远程 Linux 进程组之上实现 `ctx.subprocess`。
 - 现有的 `@deepseek-ai/dsh-bash-local` 继续作为 Bash 实现，因为它把所有进程机制委托给 `ctx.subprocess`。
+- PTY、LSP 与 Code Runtime 仍是基于同一所有者的独立功能提供方；其运行时划分见[扩展决策](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)。
 
 该所有者是沙箱身份的唯一真源。提供方会注入该所有者，绝不创建私有沙箱。因此，该组合让文件系统工具与 Bash 共享一个远程 cwd、进程命名空间和 spill／状态目录，同时保留现有功能接口与面向模型的工具。
 
 ## POC 边界
 
-只有文件系统状态、提供方存续期内的命令进程，以及适配器拥有的远程文件会迁入 E2B。宿主仍保留 Cordis 和插件对象、agent loop（智能体循环）、agent／会话状态、会话日志及其持久化、模型请求、skill（技能）、subagent 编排和 E2B SDK 缓冲。该 overlay 不会上传或挂载宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。受管进程组仍会在进程管理服务 dispose（资源释放）时终止并等待退出，包括保留沙箱采用 `pause` 或 `leave` 处置方式之前。
+文件系统状态、受管命令、交互式 shell、语言服务器、代码 worker 和适配器拥有的文件会迁入 E2B。宿主仍保留 Cordis 和插件对象、agent loop（智能体循环）、agent／会话状态、会话日志及其持久化、模型请求、skill（技能）、subagent 编排、功能协议状态和 E2B SDK 缓冲。该 overlay 不会上传或挂载宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。受管进程组仍会在所属提供方 dispose（资源释放）时终止并等待退出，包括保留沙箱采用 `pause` 或 `leave` 处置方式之前。
 
-本 POC 没有 PTY 适配器、LSP 专用集成、会话持久化后端、代码运行时后端、模板构建器、卷、快照、网络策略层、沙箱目录或工作区同步。保留沙箱后重新连接只能证明生命周期连续性；它不会重建宿主进程句柄、输出游标或锁。
+本 POC 没有会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录或工作区同步。保留沙箱后重新连接只能证明生命周期连续性；它不会重建宿主 PTY／LSP／Code Runtime 状态、进程句柄、输出游标、待处理调用或锁。
 
 ## 验证
 
-包测试固定生命周期清理、文件系统 seam 语义、进程管理的进程组／stdio／中止行为，以及包自有不变式注册。凭据门控的真实 Loader 组合会创建一个沙箱，证明同一远程 cwd 中 FS-write→Bash-read 和 Bash-write→FS-read 双向可见，证明两个文件均未出现在宿主 cwd 中，释放组合，并确认该沙箱 id 已不存在。
+包测试固定生命周期清理、文件系统语义、进程管理的进程组、字节分帧、PTY 就绪状态／信号、LSP 传输与源码路径约束、Code Runtime 绑定／输出行为，以及包自有不变式注册。凭据门控的真实 Loader 组合会创建一个沙箱，通过源代码与已构建包路径演练文件系统、Bash／进程管理、PTY、LSP 和 Code Runtime，证明宿主工作区隔离，释放组合，并确认该沙箱 id 已不存在。
 
 ## 曾考虑的替代方案
 
@@ -35,7 +36,7 @@ E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和
 
 **在 E2B 内运行完整 harness 进程。** 不予采纳，因为这会同时改变部署、凭据流、模型传输、会话持久性、插件加载和监管方式。要证明提供方 seam，并不需要同时回答这些彼此独立的问题。
 
-**同时添加 E2B 专用 Bash、PTY、LSP、持久化和同步包。** 不予采纳，因为 Bash 已经具备所需的进程管理 seam，其他功能则需要各自的消费方证据和生命周期设计。缺少它们是显式保真边界，而不是尚未公开的不完整计划。
+**把所有 E2B 功能放入共享所有者包。** 不予采纳，因为生命周期身份是该所有者唯一负责的事项。文件系统、进程管理、PTY、LSP 与 Code Runtime 各自保留独立的提供方契约、配置、测试和消费方；Bash 继续复用其进程管理 seam。
 
 **仅通过 shell 命令实现文件系统操作。** 不予采纳，因为这会绕过文件工具已经使用的 `ctx.fs` 身份、结构化错误、版本防护、流式读取和原子变更语义。
 
@@ -43,4 +44,4 @@ E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和
 
 这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留状态，演示仍以 `kill` 作为清理策略。
 
-该提供方并不能对所有消费方与本地进程管理后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，回调输出并非字节保真，信号归因依靠推断，重新连接也无法恢复句柄。保留沙箱后会累积远程进程／spill 产物。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
+该提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml
new file mode 100644
index 0000000000..e34f939a7f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.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-28-e2b-interactive-semantic-code-runtime-poc.md
+2026-07-28-e2b-interactive-semantic-code-runtime-poc.md: befaa47dd56b7f425e72978ae040bd0815cc9f92
+2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md: 677c3a09f6846320d3e000e9607becb3dee865cf
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
new file mode 100644
index 0000000000..befaa47dd5
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
@@ -0,0 +1,57 @@
+# Agent Note: E2B interactive, semantic, and code-runtime POC
+
+Status: implemented
+
+English | [中文](2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md)
+
+## Problem
+
+The [shared E2B runtime](2026-07-27-e2b-remote-runtime-poc.md) proves that filesystem operations and one-shot commands can inhabit one remote coding world, but an assembled coding agent also uses persistent terminals, language servers, and model-written Code Mode programs. Falling back to host implementations for those capabilities splits observable state: a Bash edit exists in E2B while a host PTY, LSP process, or code worker addresses a different filesystem and process namespace.
+
+Moving the complete harness process into E2B would unify that state but also changes plugin loading, credentials, model transport, session durability, supervision, and deployment. The POC needs to test the existing capability boundaries without taking on those independent concerns.
+
+## Decision
+
+Three opt-in providers extend the existing shared sandbox:
+
+- `@deepseek-ai/dsh-pty-e2b` registers an E2B byte-PTY backend on `ctx.pty` and keeps exact-Agent ownership in the existing registry.
+- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through E2B Filesystem APIs, and runs servers through `dsh-subprocess-e2b`.
+- `@deepseek-ai/dsh-code-runtime-e2b` registers `ctx.codeRuntime`, runs each model program in a fresh remote worker, and dispatches binding functions in the host process.
+
+All three inject `ctx.e2b`; none creates another sandbox. The opt-in overlay composes them with `dsh-fs-e2b`, `dsh-subprocess-e2b`, and the existing `dsh-bash-local`, so files, foreground commands, interactive shell processes, language servers, and code workers observe one remote cwd.
+
+The providers reuse the PTY, LSP, Code Runtime, and subprocess seams without changing their model-facing consumers or the agent loop. Backend-neutral PTY text handling moves into `dsh-pty`; the LSP protocol engine accepts `processId: null` for a server in another process namespace; Code Runtime exports its output-ledger and lossless-JSON helpers for backend parity.
+
+## Runtime boundary
+
+E2B owns the mutable filesystem, command and Bash processes, PTY shell and foreground process groups, language-server processes and source reads, the Code Runtime runner and worker, and adapter-private files under `.dsh-e2b`.
+
+The host owns Cordis and plugin objects, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The host workspace is not mounted or synchronized merely because its absolute cwd string is reused remotely.
+
+Byte-sensitive protocols use the narrowest adapter needed for E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP and Code Runtime install dependency-free remote helpers that encode raw payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
+
+Retaining a sandbox preserves remote files and any unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups are terminated and awaited when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
+
+## Verification
+
+Focused unit suites pin configuration, publication rollback, byte framing, multibyte boundaries, readiness, signals, timeout/abort ordering, output limits, hostile Code Runtime traffic, and disposal to quiescence. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
+
+A credential-gated Loader composition creates one real E2B sandbox and exercises FS-to-Bash and Bash-to-FS visibility, multibyte PTY output and `SIGINT`, multibyte LSP hover and definition results, Code Runtime host bindings and typed rejection under mutation of adapter-captured intrinsics, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same scenario runs through source imports and built package exports.
+
+## Alternatives considered
+
+**Run the complete harness inside E2B** — rejected because it couples this provider experiment to credentials, LLM transport, plugin deployment, session persistence, supervision, and remote package installation. None is necessary to prove the capability seams.
+
+**Use the host PTY, LSP, and worker backends unchanged** — rejected because they use host process and filesystem APIs; sharing an absolute cwd string does not share state across machines.
+
+**Expose E2B Commands as one generic transport and bypass capability providers** — rejected because PTY needs byte callbacks and foreground signaling, LSP needs byte-faithful stdio plus remote source containment, and Code Runtime needs bidirectional host binding calls and hostile-peer validation. Bypassing their registries would also fork model-facing behavior.
+
+**Add a generic distributed-runtime abstraction first** — rejected because the three existing capability seams already carry the required contracts. A new cross-cutting interface would speculate about persistence, synchronization, and reconnect semantics beyond the POC.
+
+**Restore live capability handles after `sandboxId` reconnect** — rejected because remote identity alone cannot reconstruct host callbacks, pending promises, authority, protocol state, or output cursors. Claiming continuity would make stale remote processes appear managed when they are not.
+
+## Consequences
+
+The assembled POC keeps the coding world remote without moving the agent runtime or changing model-visible tool contracts. It demonstrates that PTY, LSP, and Code Runtime can share E2B state through existing plugins, while making the remaining host state explicit.
+
+This is not a deployment platform. Language-server installation, templates, volumes, snapshots, network policy, workspace synchronization, durable remote handles, and whole-harness execution remain outside scope. E2B SDK buffering and host protocol state remain memory costs. Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a captured remote process group is not made reconnectable or owned by this composition.
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
new file mode 100644
index 0000000000..677c3a09f6
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
@@ -0,0 +1,57 @@
+# Agent Note: E2B 交互式、语义与代码运行时 POC
+
+Status: implemented
+
+[English](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) | 中文
+
+## 问题
+
+[共享 E2B 运行时](2026-07-27-e2b-remote-runtime-poc.md)证明，文件系统操作与一次性命令可以共处一个远程 coding 环境，但组装完成的 coding agent（智能体）还会使用持久终端、语言服务器，以及模型编写的 Code Mode 程序。若这些功能回退到宿主实现，可观测状态就会分裂：Bash 修改存在于 E2B 中，而宿主 PTY、LSP 进程或代码 worker 面向的却是另一个文件系统与进程命名空间。
+
+把完整 harness 进程迁入 E2B 可以统一这些状态，但也会改变插件加载、凭据、模型传输、会话持久性、监管和部署。这个 POC 只需测试现有功能边界，不应把这些彼此独立的问题纳入范围。
+
+## 决策
+
+三个可选提供方扩展现有共享沙箱：
+
+- `@deepseek-ai/dsh-pty-e2b` 在 `ctx.pty` 上注册 E2B 字节 PTY 后端，并把精确的 Agent 所有权保留在现有注册表中。
+- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B Filesystem API 读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
+- `@deepseek-ai/dsh-code-runtime-e2b` 注册 `ctx.codeRuntime`，在全新的远程 worker 中运行每个模型程序，并在宿主进程中分发绑定函数。
+
+三个提供方均注入 `ctx.e2b`，无一创建其他沙箱。可选叠加配置将它们与 `dsh-fs-e2b`、`dsh-subprocess-e2b` 和现有的 `dsh-bash-local` 组合，使文件、前台命令、交互式 shell 进程、语言服务器和代码 worker 观察到同一个远程 cwd。
+
+这些提供方复用 PTY、LSP、Code Runtime 与进程管理 seam，不更改面向模型的消费方或 agent loop（智能体循环）。后端无关的 PTY 文本处理移入 `dsh-pty`；LSP 协议引擎允许位于另一个进程命名空间的服务器使用 `processId: null`；Code Runtime 导出输出账本与无损 JSON 辅助函数，以保持各后端一致。
+
+## 运行时边界
+
+E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程组、语言服务器进程及源码读取、Code Runtime 运行器和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
+
+宿主拥有 Cordis 与插件对象、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。宿主工作区不会仅因远程复用了其绝对 cwd 字符串就被挂载或同步。
+
+对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 与 Code Runtime 会安装无依赖的远程辅助程序，把原始载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
+
+保留沙箱只会保存远程文件与任何未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
+
+## 验证
+
+聚焦单元测试固定配置、发布回滚、字节分帧、多字节边界、就绪状态、信号、超时／中止顺序、输出上限、恶意 Code Runtime 通信，以及等待完全停稳的资源释放。相邻本地后端测试固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
+
+凭据门控的 Loader 组合会创建一个真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、多字节 PTY 输出和 `SIGINT`、多字节 LSP 悬停与定义结果、Code Runtime 宿主绑定，以及适配器已捕获 intrinsic 被修改时的类型化 reject、墙钟超时、中止、运行器清理、宿主工作区隔离，以及最终删除沙箱。同一场景分别通过源代码导入与已构建包导出运行。
+
+## 曾考虑的替代方案
+
+**在 E2B 内运行完整 harness。** 不予采纳，因为这会把这项提供方实验与凭据、LLM 传输、插件部署、会话持久化、监管和远程包安装耦合。要证明功能 seam，无需引入任何一项。
+
+**原样使用宿主 PTY、LSP 与 worker 后端。** 不予采纳，因为它们使用宿主的进程与文件系统 API；在不同机器上复用同一个绝对 cwd 字符串并不会共享状态。
+
+**把 E2B Commands 公开为通用传输并绕过功能提供方。** 不予采纳，因为 PTY 需要字节回调和前台信号，LSP 需要字节保真的 stdio 与远程源码路径约束，Code Runtime 则需要双向宿主绑定调用与不可信对等方验证。绕过其注册表还会使面向模型的行为产生分叉。
+
+**先添加通用分布式运行时抽象。** 不予采纳，因为现有三个功能 seam 已承载所需契约。新的跨领域接口会预先假定 POC 范围之外的持久化、同步与重连语义。
+
+**在 `sandboxId` 重连后恢复活动功能句柄。** 不予采纳，因为只有远程身份，无法重建宿主回调、待处理 promise、权限、协议状态或输出游标。若声称保持连续性，就会让陈旧的远程进程看似仍受管理，实际并非如此。
+
+## 后果
+
+组装后的 POC 在不迁移 agent 运行时、不改变模型可见工具契约的前提下，把 coding 环境保留在远程。它证明 PTY、LSP 与 Code Runtime 可以通过现有插件共享 E2B 状态，同时明确列出仍留在宿主的状态。
+
+这不是部署平台。语言服务器安装、模板、卷、快照、网络策略、工作区同步、持久远程句柄和完整 harness 执行仍不在范围内。E2B SDK 缓冲与宿主协议状态仍会占用内存。模型程序与 Node worker 内部机制共享一个 JavaScript realm；有意逃离已捕获远程进程组的进程，也不会因此变得可重新连接或由该组合管理。
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 7ce45c6817..33f357d2bf 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -591,7 +591,7 @@ Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decisio
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:97`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:119`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
@@ -1180,7 +1180,7 @@ list(owner: Agent): PtySessionSnapshot[]
 
 Types: [Agent](../core-data-structures/core.md) · [PtyBackend](../core-data-structures/pty.md) · [PtyReadRequest](../core-data-structures/pty.md) · [PtyReadResult](../core-data-structures/pty.md) · [PtySendOperation](../core-data-structures/pty.md) · [PtySendRequest](../core-data-structures/pty.md) · [PtySessionId](../core-data-structures/pty.md) · [PtySessionSnapshot](../core-data-structures/pty.md) · [PtySignal](../core-data-structures/pty.md) · [PtySignalResult](../core-data-structures/pty.md) · [PtySpawnRequest](../core-data-structures/pty.md) · [PtySpawnResult](../core-data-structures/pty.md)
 
-Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
+Source: [`packages/pty/pty/src/index.ts:114`](../../packages/pty/pty/src/index.ts)
 
 ## `ctx.sandbox` — `SandboxProvider` (abstract seam)
 
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index 4f961100b4..877172c343 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -1,9 +1,10 @@
-# POC overlay: keep the headless agent and model-facing tools, but place its
-# filesystem and managed Bash process world in one short-lived E2B sandbox.
+# POC overlay: keep the advanced headless agent and model-facing tools, but
+# place its filesystem, processes, terminals, language servers, and Code Mode
+# execution in one short-lived E2B sandbox.
 - id: base
   name: '@cordisjs/plugin-include'
   config:
-    path: ./cordis.yml
+    path: ./advanced.cordis.yml
     patches:
       - id: subprocess
         name: '@deepseek-ai/dsh-subprocess-local'
@@ -11,6 +12,9 @@
       - id: fs-local
         name: '@deepseek-ai/dsh-fs-local'
         disabled: true
+      - id: code-runtime
+        name: '@deepseek-ai/dsh-code-runtime-worker'
+        disabled: true
       - id: bash
         name: '@deepseek-ai/dsh-bash-local'
         config:
@@ -28,3 +32,27 @@
             name: '@deepseek-ai/dsh-subprocess-e2b'
           - id: fs-e2b
             name: '@deepseek-ai/dsh-fs-e2b'
+          - id: code-runtime-e2b
+            name: '@deepseek-ai/dsh-code-runtime-e2b'
+          - id: pty
+            name: '@deepseek-ai/dsh-pty'
+          - id: pty-e2b
+            name: '@deepseek-ai/dsh-pty-e2b'
+          - id: tool-pty
+            name: '@deepseek-ai/dsh-tool-pty'
+          - id: lsp
+            name: '@deepseek-ai/dsh-lsp'
+          - id: lsp-e2b
+            name: '@deepseek-ai/dsh-lsp-e2b'
+            config:
+              servers:
+                typescript:
+                  command: npx
+                  args: [--yes, typescript-language-server@5.0.0, --stdio]
+                  extensionToLanguage:
+                    .ts: typescript
+                    .tsx: typescriptreact
+                    .js: javascript
+                    .jsx: javascriptreact
+          - id: tool-lsp
+            name: '@deepseek-ai/dsh-tool-lsp'
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 3b2cef609b..33e9530708 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -1,13 +1,38 @@
+import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
+import { AgentMessageId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-code-runtime-e2b'
 import type {} from '@deepseek-ai/dsh-e2b'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
 import type {} from '@deepseek-ai/dsh-bash-local'
+import type {} from '@deepseek-ai/dsh-lsp-e2b'
+import type {} from '@deepseek-ai/dsh-pty-e2b'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('usage: bin.ts <cordis.yml>')
 
 const ctx = await boot('e2b-composition', resolve(configPath))
+const ownerFiber = ctx.plugin(() => {})
+const ownerId = SessionId('e2b-live-owner')
+const owner: Agent = {
+  id: ownerId,
+  options: {},
+  session: new Session(ownerId),
+  status: 'idle',
+  acceptsNextStep: false,
+  ctx: ownerFiber.ctx,
+  followup: () => AgentMessageId('unused'),
+  steer: () => AgentMessageId('unused'),
+  inject: () => AgentMessageId('unused'),
+  send: () => AgentMessageId('unused'),
+  cancel() {},
+  whenIdle: () => Promise.resolve(),
+}
+const unregisterOwner = ctx.agents.register(owner)
+let terminalId: Awaited<ReturnType<typeof ctx.pty.spawn>>['sessionId'] | undefined
 try {
   const fromFs = await ctx.fs.resolve('from-fs.txt')
   await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
@@ -22,11 +47,129 @@ try {
   }
   const fromBash = await ctx.fs.resolve('from-bash.txt')
   const fsRead = await ctx.fs.readText(fromBash)
+
+  const lspFixture = await readFile(new URL('./fixture-lsp.mjs', import.meta.url), 'utf8')
+  const remoteLspFixture = await ctx.fs.resolve('fixture-lsp.mjs')
+  await ctx.fs.writeText(remoteLspFixture, lspFixture, { kind: 'createIfAbsent' })
+  const remoteSource = await ctx.fs.resolve('multibyte.ts')
+  await ctx.fs.writeText(remoteSource, 'const café = "你好"\nconsole.log(café)\n', { kind: 'createIfAbsent' })
+  const hover = await ctx.lsp.query({
+    operation: 'hover',
+    filePath: 'multibyte.ts',
+    position: { line: 0, character: 7 },
+    workspaceRoot: process.cwd(),
+  })
+  const definition = await ctx.lsp.query({
+    operation: 'goToDefinition',
+    filePath: 'multibyte.ts',
+    position: { line: 0, character: 7 },
+    workspaceRoot: process.cwd(),
+  })
+
+  const terminal = await ctx.pty.spawn(owner, { type: 'shell' })
+  terminalId = terminal.sessionId
+  const terminalEcho = await ctx.pty.startSend(owner, terminal.sessionId, {
+    text: "printf 'PTY-你好\\n'",
+    submit: true,
+  }).done
+  const sleeping = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 30', submit: true })
+  await new Promise(resolveDelay => setTimeout(resolveDelay, 150))
+  const terminalSignal = await ctx.pty.signal(owner, terminal.sessionId, 'SIGINT')
+  const interrupted = await sleeping.done
+  const terminalScrollback = ctx.pty.read(owner, terminal.sessionId, { count: 50 })
+  await ctx.pty.kill(owner, terminal.sessionId, 'live E2B composition complete')
+  terminalId = undefined
+
+  const code = await ctx.codeRuntime.run({
+    program: `
+      console.log('remote-log 你好', 42)
+      const arrayPrototype = Array.prototype
+      const objectPrototype = Object.prototype
+      const setPrototype = Set.prototype
+      const stringPrototype = String.prototype
+      Array.isArray = () => false
+      Object.defineProperty = Object.getPrototypeOf = Object.keys = () => { throw new Error('mutated object method') }
+      Object.hasOwn = () => false
+      Object.is = () => true
+      objectPrototype.propertyIsEnumerable = () => false
+      Number.isFinite = Number.isSafeInteger = () => false
+      Reflect.apply = Reflect.ownKeys = () => { throw new Error('mutated reflect method') }
+      setPrototype.add = setPrototype.delete = setPrototype.has = () => { throw new Error('mutated set method') }
+      stringPrototype.charCodeAt = stringPrototype.codePointAt = stringPrototype.slice = () => { throw new Error('mutated string method') }
+      Buffer.byteLength = () => 0
+      Function.prototype.toString = () => 'mutated'
+      objectPrototype.constructor = arrayPrototype.constructor = null
+      globalThis.Array = globalThis.Buffer = globalThis.Function = globalThis.Number = globalThis.Object = globalThis.Promise = globalThis.Reflect = globalThis.Set = globalThis.String = undefined
+      process.stdout.write('post-mutation', () => {})
+      const doubled: number = await bridge.double({ value: 21 })
+      let typed = false
+      try {
+        await bridge.fail({ reason: 'expected' })
+      } catch (error) {
+        typed = error instanceof BridgeError && (error as { member: string }).member === 'fail'
+      }
+      return { doubled, typed }
+    `,
+    bindings: [{
+      global: 'bridge',
+      errorClass: { name: 'BridgeError', memberNameProperty: 'member' },
+      functions: {
+        double: async (args) => {
+          const value = (args as { value: number }).value
+          return value * 2
+        },
+        fail: async () => { throw new Error('binding rejected') },
+      },
+    }],
+  })
+  const hostileOutput = await ctx.codeRuntime.run({
+    program: `
+      const payload = '🙂'.repeat(4096)
+      String.prototype[Symbol.iterator] = () => { throw new Error('mutated string iterator') }
+      console.log(payload)
+      return true
+    `,
+    bindings: [],
+  })
+  const timedOut = await ctx.codeRuntime.run({
+    program: 'await new Promise(() => {})',
+    bindings: [],
+  })
+  const abortController = new AbortController()
+  const aborting = ctx.codeRuntime.run({
+    program: 'await new Promise(() => {})',
+    bindings: [],
+    signal: abortController.signal,
+  })
+  setTimeout(() => { abortController.abort('live abort') }, 50)
+  const aborted = await aborting
+  const remoteProcesses = await (await ctx.e2b.getSandbox()).commands.list()
+  const lingeringCodeRunners = remoteProcesses.filter(processInfo =>
+    JSON.stringify([processInfo.cmd, processInfo.args]).includes('code-runtime-runner.mjs'),
+  )
+
   process.stdout.write(`${JSON.stringify({
     sandboxId: await ctx.e2b.sandboxId,
     bashRead: bashRead.stdout.text,
     fsRead,
+    hover,
+    definition,
+    terminal: {
+      motd: terminal.motd,
+      echo: terminalEcho,
+      signal: terminalSignal,
+      interrupted,
+      scrollback: terminalScrollback.text,
+    },
+    code,
+    hostileOutput,
+    timedOut,
+    aborted,
+    lingeringCodeRunners: lingeringCodeRunners.length,
   })}\n`)
 } finally {
+  if (terminalId !== undefined) await ctx.pty.kill(owner, terminalId, 'fixture cleanup').catch(() => false)
+  unregisterOwner()
+  await ownerFiber.dispose()
   await ctx.fiber.dispose()
 }
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 08a7e7225c..f5cf403c4b 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -17,3 +17,43 @@
 
 - id: fs-e2b
   name: '@deepseek-ai/dsh-fs-e2b'
+
+- id: agents
+  name: '@deepseek-ai/dsh-agent'
+
+- id: pty
+  name: '@deepseek-ai/dsh-pty'
+
+- id: pty-e2b
+  name: '@deepseek-ai/dsh-pty-e2b'
+  config:
+    pollIntervalMs: 25
+    idleSilenceMs: 2000
+    timeoutMs: 5000
+    disposeGraceMs: 1000
+
+- id: lsp
+  name: '@deepseek-ai/dsh-lsp'
+
+- id: lsp-e2b
+  name: '@deepseek-ai/dsh-lsp-e2b'
+  config:
+    servers:
+      fixture:
+        command: node
+        args:
+          - !!js process.cwd() + '/fixture-lsp.mjs'
+        extensionToLanguage:
+          .ts: typescript
+        shutdownTimeoutMs: 1000
+        killGraceMs: 500
+
+- id: code-runtime-e2b
+  name: '@deepseek-ai/dsh-code-runtime-e2b'
+  config:
+    computeMs: 500
+    maxWallMs: 5000
+    maxOutputBytes: 4096
+    maxOldGenerationSizeMb: 128
+    maxFrameBytes: 4194304
+    killGraceMs: 500
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/fixture-lsp.mjs b/examples/headless-agent/tests/fixtures/e2b/e2b/fixture-lsp.mjs
new file mode 100644
index 0000000000..dc4f7bb219
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/fixture-lsp.mjs
@@ -0,0 +1,85 @@
+import { Buffer } from 'node:buffer'
+
+let pending = Buffer.alloc(0)
+let source = ''
+let sourceUri = ''
+
+function send(message) {
+  const body = Buffer.from(JSON.stringify(message))
+  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`)
+  process.stdout.write(body)
+}
+
+function respond(id, result) {
+  send({ jsonrpc: '2.0', id, result })
+}
+
+function dispatch(message) {
+  switch (message.method) {
+    case 'initialize':
+      respond(message.id, {
+        capabilities: {
+          positionEncoding: 'utf-16',
+          textDocumentSync: { openClose: true, change: 1 },
+          definitionProvider: true,
+          referencesProvider: true,
+          implementationProvider: true,
+          hoverProvider: true,
+        },
+      })
+      return
+    case 'textDocument/didOpen':
+      source = message.params.textDocument.text
+      sourceUri = message.params.textDocument.uri
+      return
+    case 'textDocument/didClose':
+      source = ''
+      sourceUri = ''
+      return
+    case 'textDocument/hover':
+      if (!source.includes('const café = "你好"')) {
+        send({ jsonrpc: '2.0', id: message.id, error: { code: -32000, message: 'multibyte source was corrupted' } })
+        return
+      }
+      respond(message.id, {
+        contents: { kind: 'markdown', value: '**remote hover** 你好 café' },
+        range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } },
+      })
+      return
+    case 'textDocument/definition':
+    case 'textDocument/references':
+    case 'textDocument/implementation':
+      respond(message.id, [{
+        uri: sourceUri,
+        range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } },
+      }])
+      return
+    case 'shutdown':
+      respond(message.id, null)
+      return
+    case 'exit':
+      process.exit(0)
+      return
+  }
+}
+
+function drain() {
+  for (;;) {
+    const headerEnd = pending.indexOf('\r\n\r\n')
+    if (headerEnd < 0) return
+    const header = pending.subarray(0, headerEnd).toString('ascii')
+    const match = /(?:^|\r\n)Content-Length: ([0-9]+)(?:\r\n|$)/i.exec(header)
+    if (!match) throw new Error('missing Content-Length')
+    const length = Number(match[1])
+    const bodyStart = headerEnd + 4
+    if (pending.length < bodyStart + length) return
+    const body = pending.subarray(bodyStart, bodyStart + length)
+    pending = pending.subarray(bodyStart + length)
+    dispatch(JSON.parse(body.toString('utf8')))
+  }
+}
+
+process.stdin.on('data', chunk => {
+  pending = Buffer.concat([pending, chunk])
+  drain()
+})
diff --git a/examples/package.json b/examples/package.json
index 48ac39f5ca..8dd631e760 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -43,10 +43,12 @@
     "@deepseek-ai/dsh-llm-replay": "workspace:*",
     "@deepseek-ai/dsh-loader-smoke": "workspace:*",
     "@deepseek-ai/dsh-lsp": "workspace:*",
+    "@deepseek-ai/dsh-lsp-e2b": "workspace:*",
     "@deepseek-ai/dsh-lsp-local": "workspace:*",
     "@deepseek-ai/dsh-permission": "workspace:*",
     "@deepseek-ai/dsh-plan-mode": "workspace:*",
     "@deepseek-ai/dsh-pty": "workspace:*",
+    "@deepseek-ai/dsh-pty-e2b": "workspace:*",
     "@deepseek-ai/dsh-pty-local": "workspace:*",
     "@deepseek-ai/dsh-pwsh-local": "workspace:*",
     "@deepseek-ai/dsh-repeat-tool-guard": "workspace:*",
@@ -54,7 +56,10 @@
     "@deepseek-ai/dsh-sandbox": "workspace:*",
     "@deepseek-ai/dsh-sandbox-local": "workspace:*",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
+<<<<<<< HEAD
     "@deepseek-ai/dsh-scope": "workspace:*",
+=======
+>>>>>>> 3f6c905d5e (Add E2B PTY, LSP, and code runtime providers)
     "@deepseek-ai/dsh-session": "workspace:*",
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:*",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:*",
diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml
index 3eb462d513..f9160b4f8e 100644
--- a/packages/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/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/code-runtime/README.md
-README.md: f20a287419b94b1a9dc1d8da7303fc4d3032cfd3
-README.zh.md: f5cd4c9949f2bd7a7d6d7cd078144910712a3819
+README.md: f59fc3b15331b4799cbc7a3fbe27ce8cd9a12e51
+README.zh.md: 02ade97887fab8a8a0c22efcf73bb2dd1f2cf33c
diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md
index f20a287419..f59fc3b153 100644
--- a/packages/code-runtime/README.md
+++ b/packages/code-runtime/README.md
@@ -2,11 +2,12 @@
 
 English | [中文](README.zh.md)
 
-The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the SDK generated in the loaded runtime's `language`); design in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
+The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the generated TypeScript SDK); design in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`code-runtime/`](code-runtime/README.md) | Code-execution seam and shared vocabulary | `ctx.codeRuntime` |
-| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend | registers `ctx.codeRuntime` |
+| `code-runtime/` | Abstract code-execution seam (interface + vocabulary) | `ctx.codeRuntime` |
+| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend: fresh worker per run, TypeScript via host-side type-strip (annotations advisory, never type-checked), port-bridged bindings, budget/heap containment | registers `ctx.codeRuntime` |
+| [`code-runtime-e2b/`](code-runtime-e2b/README.md) | E2B backend: host type-strip and bindings, fresh remote runner/worker, framed bridge, remote process-group cleanup | registers `ctx.codeRuntime` |
 
-Backends register the seam without changing its consumer. The child READMEs own language, isolation, and execution-budget details.
+Backends differ by execution substrate and source language—both readonly descriptors on the service—and register `ctx.codeRuntime` without touching the interface or its consumer. The E2B ownership split is recorded in the [remote extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md
index f5cd4c9949..02ade97887 100644
--- a/packages/code-runtime/README.zh.md
+++ b/packages/code-runtime/README.zh.md
@@ -1,12 +1,13 @@
-# code-runtime/ — 代码执行能力家族
+# code-runtime/：代码执行能力家族
 
 [English](README.md) | 中文
 
-代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：一个抽象运行时接口，用于对宿主提供的异步绑定执行模型编写的程序，并捕获它打印和返回的内容。消费方是工具注册表的 [Code Mode](../core/tools/README.md)（`tools: { mode: code }`，即 `run_code` 工具和按所加载运行时 `language` 生成的 SDK）；设计见 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)。这些全是**产品**包。
+代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：一个抽象运行时接口，用于针对宿主提供的异步绑定执行一段模型编写的程序，并捕获程序打印和返回的内容。消费方是工具注册表的 [Code Mode](../core/tools/README.md)（`tools: { mode: code }`，即 `run_code` 工具与生成的 TypeScript SDK）；设计记录在 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 中。这些都是**产品** 包。
 
-| 包 | 职责 | ctx key |
+| 包 | 职责 | ctx 键 |
 |---|---|---|
-| [`code-runtime/`](code-runtime/README.md) | 代码执行 seam 与共享词汇 | `ctx.codeRuntime` |
-| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker 线程后端 | 注册 `ctx.codeRuntime` |
+| `code-runtime/` | 抽象代码执行 seam（接口 + 词汇） | `ctx.codeRuntime` |
+| [`code-runtime-worker/`](code-runtime-worker/README.md) | worker 线程后端：每次运行使用全新 worker，由宿主侧剥离 TypeScript 类型（类型注解仅供参考，绝不执行类型检查）、端口桥接绑定、预算／堆隔离 | 注册 `ctx.codeRuntime` |
+| [`code-runtime-e2b/`](code-runtime-e2b/README.md) | E2B 后端：宿主侧类型剥离与绑定、全新远程 runner／worker、分帧桥、远程进程组清理 | 注册 `ctx.codeRuntime` |
 
-后端在不改变消费方的情况下注册该 seam。子 README 负责语言、隔离和执行预算细节。
+不同后端的执行基底和源语言各异，二者都是服务上的只读描述符；后端注册 `ctx.codeRuntime`，无需修改接口或消费方。E2B 所有权拆分记录在[远程扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) 中。
diff --git a/packages/code-runtime/code-runtime-e2b/README.i18n.yaml b/packages/code-runtime/code-runtime-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..c00b40f4a2
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/README.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 packages/code-runtime/code-runtime-e2b/README.md
+README.md: bf26174c59c1df18f63278acb7923fd409860b44
+README.zh.md: c87945da30a6f8d77eb3722879510bb6159b3ee8
diff --git a/packages/code-runtime/code-runtime-e2b/README.md b/packages/code-runtime/code-runtime-e2b/README.md
new file mode 100644
index 0000000000..bf26174c59
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/README.md
@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-code-runtime-e2b
+
+English | [中文](README.zh.md)
+
+E2B implementation of [`ctx.codeRuntime`](../code-runtime/README.md). Each run executes one model-written TypeScript program in a fresh remote Node worker while binding functions, type stripping, output accounting, and lifecycle orchestration remain on the host.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `computeMs` | `60000` | Remote worker event-loop busy-time budget. |
+| `maxWallMs` | `600000` | Host-observed wall-clock ceiling. |
+| `maxOutputBytes` | `67108864` | Combined serialized outer logs/value/diagnostic cap. |
+| `maxOldGenerationSizeMb` | `512` | Remote worker old-generation heap cap in MiB. |
+| `maxFrameBytes` | `268435456` | Largest decoded bridge frame, including binding traffic. |
+| `killGraceMs` | `2000` | Remote process-group TERM-to-KILL grace. |
+
+Every value is a positive safe integer. `maxOutputBytes` is at least four bytes, `maxWallMs` cannot exceed Node's maximum timer delay, and `maxFrameBytes` cannot be smaller than `maxOutputBytes`. The service requires the concrete `dsh-subprocess-e2b` backend so run cleanup has remote process-group semantics.
+
+## Execution and bridge contract
+
+Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner creates a fresh worker thread with an empty environment and heap limit, measures active event-loop time, and destroys that worker after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in that group stop with the run.
+
+The bridge uses validated newline-delimited base64 JSON frames because E2B subprocess callbacks expose decoded text. Binding arguments and resolutions use the worker runtime's iterative lossless-JSON wire shape; binding functions execute on the host and typed rejection classes are materialized inside the remote worker. The worker captures the JavaScript intrinsics that its adapter boundary invokes before model code runs, hardening binding transport, output accounting, and completion validation against mutation of those references. The host repeats message validation, call-id deduplication, lossless-JSON checks, and the outer-output ledger.
+
+Program failures resolve as `CodeRunResult.error`; only seam misuse rejects. `isolation` is reported as `container`, which is a deployment descriptor rather than a security claim.
+
+## Model Experience
+
+Indirectly, through Code Mode in `dsh-tools`, which returns program logs, values, or typed failures through the existing `run_code` result contract.
+
+#### KV Cache effect
+
+No direct invalidation; Code Mode owns request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Not a whole-agent runtime** — Cordis, sessions, LLM calls, binding dispatch, TypeScript stripping, output ledgers, and E2B SDK state remain on the host.
+- **No reconnectable runs** — retaining a sandbox preserves files but not worker/subprocess handles, binding calls, timers, or output cursors.
+- **Node worker internals share the model realm** — mutating realm-wide globals or prototypes that Node itself uses can terminate the worker; captured adapter intrinsics are not a separate JavaScript realm or a security boundary.
+- **Deliberate process-group escape is not captured** — model code can create a new POSIX session; that unmanaged process is outside this backend's cleanup identity.
+- **Intermediate binding traffic is memory-bounded only per frame** — it does not enter model context or the outer-output ledger, but aggregate host/remote process memory remains the limit.
+- **Experimental type stripping** — the backend shares the worker implementation's reliance on Node's experimental erasable-syntax API.
+- **Sandbox policy is template-owned** — this package adds no network, volume, snapshot, or workspace-synchronization policy.
diff --git a/packages/code-runtime/code-runtime-e2b/README.zh.md b/packages/code-runtime/code-runtime-e2b/README.zh.md
new file mode 100644
index 0000000000..c87945da30
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/README.zh.md
@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-code-runtime-e2b
+
+[English](README.md) | 中文
+
+[`ctx.codeRuntime`](../code-runtime/README.md) 的 E2B 实现。每次运行都会在全新的远程 Node worker 中执行一段模型编写的 TypeScript 程序；绑定函数、类型剥离、输出记账和生命周期编排仍保留在宿主侧。
+
+## 配置
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `computeMs` | `60000` | 远程 worker 的事件循环忙碌时间预算。 |
+| `maxWallMs` | `600000` | 宿主观测到的墙钟时间上限。 |
+| `maxOutputBytes` | `67108864` | 外层日志、值和诊断合计的序列化上限。 |
+| `maxOldGenerationSizeMb` | `512` | 远程 worker 的老生代堆上限（MiB）。 |
+| `maxFrameBytes` | `268435456` | 已解码桥接帧的最大大小，包括绑定流量。 |
+| `killGraceMs` | `2000` | 远程进程组 TERM 到 KILL 的宽限期。 |
+
+每个值都必须是正的安全整数。`maxOutputBytes` 必须至少为 4 字节，`maxWallMs` 不得超过 Node 的最大定时器延迟，且 `maxFrameBytes` 不得小于 `maxOutputBytes`。本服务要求使用具体的 `dsh-subprocess-e2b` 后端，使运行清理具备远程进程组语义。
+
+## 执行与桥接契约
+
+设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会创建一个具有空环境与堆上限的全新 worker 线程，测量事件循环活跃时间，并在一次运行结算后销毁该 worker。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此组内的普通子进程会随本次运行一同停止。
+
+由于 E2B 进程管理回调公开的是已解码文本，桥接层使用经过验证、以换行分隔的 base64 JSON 帧。绑定参数与 resolve 值使用 worker 运行时的迭代式无损 JSON wire 形状；绑定函数在宿主执行，类型化的 reject 类则在远程 worker 内物化。worker 会在模型代码运行前捕获其适配器边界调用的 JavaScript intrinsic，从而增强绑定传输、输出记账与完成值验证对这些引用修改的抵御能力。宿主会再次执行消息验证、调用 id 去重和无损 JSON 检查，并用外层输出账本再次计量。
+
+程序失败会 resolve 为 `CodeRunResult.error`；只有 seam 误用才会 reject。`isolation` 报告为 `container`；这是部署描述符，不构成安全声明。
+
+## 模型体验
+
+通过 `dsh-tools` 中的 Code Mode 间接影响模型；它会通过现有 `run_code` 结果契约返回程序日志、值或类型化失败。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由 Code Mode 负责。
+
+## 已知限制与暂缓工作
+
+- **并非完整的 agent（智能体）运行时**：Cordis、会话、LLM（大语言模型）调用、绑定分发、TypeScript 类型剥离、输出账本和 E2B SDK 状态仍保留在宿主侧。
+- **运行不可重连**：保留沙箱会保留文件，但不会保留 worker／进程管理句柄、绑定调用、定时器或输出游标。
+- **Node worker 内部机制与模型共享同一 realm**：修改 Node 自身使用、影响整个 realm 的全局对象或原型可能会终止 worker；已捕获的适配器 intrinsic 并不构成独立的 JavaScript realm 或安全边界。
+- **不会捕获有意逃逸进程组的行为**：模型代码可以创建新的 POSIX 会话；该非受管进程不属于此后端的清理身份范围。
+- **中间绑定流量的内存边界仅适用于单帧**：它不会进入模型上下文或外层输出账本，但其总量仍只受宿主／远程进程内存限制。
+- **实验性类型剥离**：该后端与 worker 实现一样，依赖 Node 的实验性可擦除语法 API。
+- **沙箱策略归模板负责**：本包不会额外增加网络、卷、快照或工作区同步策略。
diff --git a/packages/code-runtime/code-runtime-e2b/package.json b/packages/code-runtime/code-runtime-e2b/package.json
new file mode 100644
index 0000000000..222ae71bef
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/package.json
@@ -0,0 +1,52 @@
+{
+  "name": "@deepseek-ai/dsh-code-runtime-e2b",
+  "description": "E2B code-runtime implementation for DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-code-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-code-runtime-worker": "^0.0.1",
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-code-runtime": "workspace:^",
+    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-e2b": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/code-runtime/code-runtime-e2b/src/index.ts b/packages/code-runtime/code-runtime-e2b/src/index.ts
new file mode 100644
index 0000000000..fbfbdea91f
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/src/index.ts
@@ -0,0 +1,441 @@
+/** E2B process/worker implementation of the harness code-runtime seam. */
+
+import { posix } from 'node:path'
+import { stripTypeScriptTypes } from 'node:module'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
+import type {
+  CodeBindingNamespace,
+  CodeJsonValue,
+  CodeRunFailure,
+  CodeRunRequest,
+  CodeRunResult,
+} from '@deepseek-ai/dsh-code-runtime'
+import {
+  E2BFrameDecoder,
+  encodeE2BFrame,
+  quoteE2BShellArg,
+  resolveE2BExecutable,
+} from '@deepseek-ai/dsh-e2b'
+import {
+  decodeWorkerJson,
+  encodeWorkerJson,
+  OutputLedger,
+} from '@deepseek-ai/dsh-code-runtime-worker'
+import type { WorkerJsonWire } from '@deepseek-ai/dsh-code-runtime-worker'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import { CODE_RUNNER_SOURCE } from './runner-source.ts'
+
+/** Runtime configuration; every execution and bridge bound is deployment-tunable. */
+export interface Config {
+  /** Remote worker measured event-loop busy-time budget. */
+  computeMs?: number
+  /** Host-observed wall-clock ceiling. */
+  maxWallMs?: number
+  /** Combined serialized outer logs/value/diagnostic cap. */
+  maxOutputBytes?: number
+  /** Remote worker old-generation heap cap in MiB. */
+  maxOldGenerationSizeMb?: number
+  /** Largest decoded bridge frame, including binding traffic. */
+  maxFrameBytes?: number
+  /** Remote process-group TERM-to-KILL grace. */
+  killGraceMs?: number
+}
+
+type ResolvedConfig = Required<Config>
+
+interface LiveRun {
+  settle(failure: CodeRunFailure): void
+  finished: Promise<void>
+}
+
+interface CallMessage {
+  type: 'call'
+  id: number
+  global: string
+  name: string
+  args: WorkerJsonWire
+}
+
+interface LogMessage {
+  type: 'log'
+  text: string
+}
+
+interface DoneMessage {
+  type: 'done'
+  value?: WorkerJsonWire
+  error?: CodeRunFailure
+}
+
+type RunnerMessage = CallMessage | LogMessage | DoneMessage | { type: 'output-limit' }
+
+const STRIP_WRAP = { prefix: 'async function __dsh_program__() {\n', suffix: '\n}' } as const
+const MIN_OUTPUT_BYTES = 4
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+/* jscpd:ignore-start -- Backends enforce the same injected-global vocabulary without coupling lifecycle implementations. */
+const RESERVED_WORDS = new Set([
+  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
+  'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in',
+  'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
+  'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface', 'package',
+  'private', 'protected', 'public', 'arguments', 'eval',
+])
+const RESERVED_ERROR_PROPERTIES = new Set(['name', 'message', 'stack'])
+/* jscpd:ignore-end */
+const FAILURE_KINDS = new Set<CodeRunFailure['kind']>([
+  'exception', 'timeout', 'abort', 'worker-exit', 'invalid-output', 'output-limit',
+])
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function parseRunnerMessage(raw: unknown): RunnerMessage | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const record = raw as Record<string, unknown>
+  if (record.type === 'output-limit') return { type: 'output-limit' }
+  if (record.type === 'log') return typeof record.text === 'string' ? { type: 'log', text: record.text } : undefined
+  if (record.type === 'call') {
+    if (!Number.isSafeInteger(record.id) || (record.id as number) < 1 || typeof record.global !== 'string' || typeof record.name !== 'string' || !Array.isArray(record.args)) return undefined
+    return { type: 'call', id: record.id as number, global: record.global, name: record.name, args: record.args as WorkerJsonWire }
+  }
+  if (record.type !== 'done') return undefined
+  if (record.error === undefined) {
+    return { type: 'done', ...record.value === undefined ? {} : { value: record.value as WorkerJsonWire } }
+  }
+  if (typeof record.error !== 'object' || record.error === null) return undefined
+  const error = record.error as Record<string, unknown>
+  if (typeof error.kind !== 'string' || !FAILURE_KINDS.has(error.kind as CodeRunFailure['kind']) || typeof error.message !== 'string') return undefined
+  return { type: 'done', error: { kind: error.kind as CodeRunFailure['kind'], message: error.message } }
+}
+
+/** E2B-backed runtime: host-side type stripping, remote worker execution, host binding dispatch. */
+export class E2BCodeRuntime extends CodeRuntime {
+  static inject = ['e2b', 'subprocess']
+
+  static Config: z<Config> = z.object({
+    computeMs: z.number().default(60_000),
+    maxWallMs: z.number().default(600_000),
+    maxOutputBytes: z.number().default(67_108_864),
+    maxOldGenerationSizeMb: z.number().default(512),
+    maxFrameBytes: z.number().default(268_435_456),
+    killGraceMs: z.number().default(2_000),
+  })
+
+  readonly language = 'typescript'
+  readonly isolation = 'container'
+
+  private readonly config: ResolvedConfig
+  private readonly ready: Promise<{ node: string; runner: string }>
+  private readonly live = new Set<LiveRun>()
+  private readonly subprocess: E2BSubprocessService
+  private disposed = false
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx)
+    if (!(ctx.subprocess instanceof E2BSubprocessService)) {
+      throw new Error('code-runtime-e2b requires @deepseek-ai/dsh-subprocess-e2b as ctx.subprocess')
+    }
+    this.subprocess = ctx.subprocess
+    this.config = config as ResolvedConfig
+    for (const [key, value] of Object.entries(this.config)) {
+      if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`code-runtime-e2b: config.${key} must be a positive safe integer`)
+      }
+    }
+    if (this.config.maxOutputBytes < MIN_OUTPUT_BYTES) {
+      throw new Error(`code-runtime-e2b: config.maxOutputBytes must be at least ${MIN_OUTPUT_BYTES}`)
+    }
+    if (this.config.maxWallMs > MAX_TIMER_DELAY_MS) {
+      throw new Error(`code-runtime-e2b: config.maxWallMs must be at most ${MAX_TIMER_DELAY_MS}`)
+    }
+    if (this.config.maxFrameBytes < this.config.maxOutputBytes) {
+      throw new Error('code-runtime-e2b: config.maxFrameBytes must be at least maxOutputBytes')
+    }
+    this.ready = this.prepare()
+    void this.ready.catch(() => {})
+    ctx.effect(() => () => this.teardown(), 'E2B code-runtime teardown')
+  }
+
+  /* jscpd:ignore-start -- Seam-level abort and type-strip results remain identical across execution substrates. */
+  /** Execute one type-stripped program in a fresh E2B worker process. */
+  async run(request: CodeRunRequest): Promise<CodeRunResult> {
+    if (this.disposed) throw new Error('code-runtime-e2b: run() after disposal')
+    const bindings = this.validateBindings(request)
+    if (request.signal?.aborted === true) {
+      return this.failure({ kind: 'abort', message: String(request.signal.reason) })
+    }
+    let code: string
+    try {
+      const stripped = stripTypeScriptTypes(STRIP_WRAP.prefix + request.program + STRIP_WRAP.suffix)
+      code = stripped.slice(STRIP_WRAP.prefix.length, stripped.length - STRIP_WRAP.suffix.length)
+    } catch (error: unknown) {
+      return this.failure({ kind: 'exception', message: messageOf(error) })
+    }
+    let runtime: Awaited<typeof this.ready>
+    try {
+      runtime = await this.ready
+    } catch (error: unknown) {
+      return this.failure({ kind: 'worker-exit', message: `E2B runtime setup failed: ${messageOf(error)}` })
+    }
+    // Disposal can race the awaited remote setup after the pre-await check.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
+    return await this.execute(request, code, bindings, runtime)
+  }
+  /* jscpd:ignore-end */
+
+  private async prepare(): Promise<{ node: string; runner: string }> {
+    const sandbox = await this.ctx.e2b.getSandbox()
+    const runner = posix.join(this.ctx.e2b.runtimeRoot, 'code-runtime-runner.mjs')
+    await sandbox.files.write([{ path: runner, data: CODE_RUNNER_SOURCE }])
+    await sandbox.commands.run(`chmod 600 -- ${quoteE2BShellArg(runner)}`)
+    const node = await resolveE2BExecutable(sandbox, 'node')
+    return { node, runner }
+  }
+
+  private failure(error: CodeRunFailure): CodeRunResult {
+    return new OutputLedger(this.config.maxOutputBytes).failure([], error)
+  }
+
+  /* jscpd:ignore-start -- Binding names have one seam contract while dispatch and teardown remain backend-owned. */
+  private validateBindings(request: CodeRunRequest): Map<string, CodeBindingNamespace> {
+    const bindings = new Map<string, CodeBindingNamespace>()
+    for (const namespace of request.bindings) {
+      if (!IDENTIFIER.test(namespace.global) || RESERVED_WORDS.has(namespace.global)) {
+        throw new Error(`code-runtime-e2b: binding global ${JSON.stringify(namespace.global)} is not a usable identifier`)
+      }
+      if (namespace.global === 'console' || bindings.has(namespace.global)) {
+        throw new Error(`code-runtime-e2b: duplicate binding global ${JSON.stringify(namespace.global)}`)
+      }
+      bindings.set(namespace.global, namespace)
+    }
+    const errorClassNames = new Set<string>()
+    for (const namespace of request.bindings) {
+      const descriptor = namespace.errorClass
+      if (descriptor === undefined) continue
+      if (!IDENTIFIER.test(descriptor.name) || RESERVED_WORDS.has(descriptor.name)) {
+        throw new Error(`code-runtime-e2b: binding error class ${JSON.stringify(descriptor.name)} is not a usable identifier`)
+      }
+      if (descriptor.name === 'console' || bindings.has(descriptor.name) || errorClassNames.has(descriptor.name)) {
+        throw new Error(`code-runtime-e2b: duplicate injected global ${JSON.stringify(descriptor.name)}`)
+      }
+      if (descriptor.memberNameProperty.length === 0 || RESERVED_ERROR_PROPERTIES.has(descriptor.memberNameProperty)) {
+        throw new Error(`code-runtime-e2b: binding error member property ${JSON.stringify(descriptor.memberNameProperty)} is not usable`)
+      }
+      errorClassNames.add(descriptor.name)
+    }
+    return bindings
+  }
+  /* jscpd:ignore-end */
+
+  private async execute(
+    request: CodeRunRequest,
+    code: string,
+    bindings: Map<string, CodeBindingNamespace>,
+    runtime: { node: string; runner: string },
+  ): Promise<CodeRunResult> {
+    const handle = this.subprocess.spawn({
+      argv: [runtime.node, runtime.runner],
+      cwd: this.ctx.e2b.cwd,
+      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: this.config.maxOutputBytes } },
+      graceMs: this.config.killGraceMs,
+      ...request.signal === undefined ? {} : { signal: request.signal },
+      env: {},
+    })
+    if (handle.stdin === undefined || handle.stdout === undefined) {
+      handle.terminate()
+      await Promise.allSettled([handle.done])
+      try {
+        await handle.waitForExit()
+      } catch (error: unknown) {
+        return this.failure({ kind: 'worker-exit', message: `E2B runtime cleanup failed: ${messageOf(error)}` })
+      }
+      return this.failure({ kind: 'worker-exit', message: 'E2B subprocess dropped a piped runtime stream' })
+    }
+    const stdin = handle.stdin
+    const stdout = handle.stdout
+
+    return new Promise<CodeRunResult>((resolve) => {
+      const output = new OutputLedger(this.config.maxOutputBytes)
+      const logs: string[] = []
+      const answered = new Set<number>()
+      const decoder = new E2BFrameDecoder(this.config.maxFrameBytes)
+      let settled = false
+      let finishResolve!: () => void
+      const finished = new Promise<void>((done) => { finishResolve = done })
+      const wallTimer: { current: NodeJS.Timeout | undefined } = { current: undefined }
+      const live: LiveRun = {
+        finished,
+        settle: (failure) => { finish(() => output.failure(logs, failure)) },
+      }
+
+      const finish = (result: CodeRunResult | (() => CodeRunResult)): void => {
+        if (settled) return
+        settled = true
+        clearTimeout(wallTimer.current)
+        request.signal?.removeEventListener('abort', onAbort)
+        this.live.delete(live)
+        void new Promise<void>((resume) => { setImmediate(resume) }).then(async () => {
+          handle.terminate()
+          await handle.done.catch(() => {})
+          let cleanupError: unknown
+          try {
+            await handle.waitForExit()
+          } catch (error: unknown) {
+            cleanupError = error
+          }
+          try {
+            decoder.finish()
+          } catch (error: unknown) {
+            result = output.failure(logs, { kind: 'worker-exit', message: messageOf(error) })
+          }
+          if (cleanupError !== undefined) {
+            result = output.failure(logs, { kind: 'worker-exit', message: `E2B runtime cleanup failed: ${messageOf(cleanupError)}` })
+          }
+          const final = typeof result === 'function' ? result() : result
+          finishResolve()
+          resolve(final)
+        })
+      }
+
+      const sendReply = (message: unknown): void => {
+        if (settled) return
+        stdin.write(encodeE2BFrame(message), (error?: Error | null) => {
+          if (error !== undefined && error !== null) {
+            finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge write failed: ${error.message}` }))
+          }
+        })
+      }
+
+      /* jscpd:ignore-start -- Host binding resolution mirrors worker semantics over a different transport. */
+      const onCall = (message: CallMessage): void => {
+        if (answered.has(message.id)) return
+        answered.add(message.id)
+        const functions = bindings.get(message.global)?.functions
+        const fn = functions !== undefined && Object.hasOwn(functions, message.name) ? functions[message.name] : undefined
+        if (typeof fn !== 'function') {
+          sendReply({ type: 'reply', id: message.id, ok: false, message: `unknown binding ${JSON.stringify(`${message.global}.${message.name}`)}` })
+          return
+        }
+        const args = decodeWorkerJson(message.args)
+        if (args === undefined) {
+          sendReply({ type: 'reply', id: message.id, ok: false, message: 'binding arguments must be lossless JSON' })
+          return
+        }
+        void (async () => {
+          try {
+            const resolved = await fn(args)
+            let value: CodeJsonValue | undefined
+            try {
+              value = snapshotJsonValue(resolved)
+            } catch {
+              value = undefined
+            }
+            if (value === undefined) {
+              sendReply({ type: 'reply', id: message.id, ok: false, message: 'binding resolution must be lossless JSON' })
+            } else {
+              sendReply({ type: 'reply', id: message.id, ok: true, value: encodeWorkerJson(value) })
+            }
+          } catch (error: unknown) {
+            sendReply({ type: 'reply', id: message.id, ok: false, message: messageOf(error) })
+          }
+        })()
+      }
+      /* jscpd:ignore-end */
+
+      const onMessage = (raw: unknown): void => {
+        if (settled) return
+        const message = parseRunnerMessage(raw)
+        if (message === undefined) return
+        if (message.type === 'log') {
+          if (!output.admit(message.text, logs)) finish(output.limit([...logs, message.text]))
+          return
+        }
+        if (message.type === 'output-limit') {
+          finish(output.limit(logs))
+          return
+        }
+        if (message.type === 'call') {
+          onCall(message)
+          return
+        }
+        if (message.error !== undefined) {
+          finish(() => output.failure(logs, message.error as CodeRunFailure))
+        } else if (message.value === undefined) {
+          finish(() => output.success(logs))
+        } else {
+          const value = decodeWorkerJson(message.value)
+          if (value === undefined) finish(() => output.failure(logs, { kind: 'invalid-output', message: 'program completion must be lossless JSON' }))
+          else finish(() => output.success(logs, value))
+        }
+      }
+
+      stdout.on('data', (chunk: Buffer) => {
+        if (settled) return
+        try {
+          for (const frame of decoder.push(chunk.toString('utf8'))) onMessage(frame)
+        } catch (error: unknown) {
+          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge failed: ${messageOf(error)}` }))
+        }
+      })
+      stdout.on('error', (error: Error) => {
+        finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime stdout failed: ${error.message}` }))
+      })
+      stdin.on('error', (error: Error) => {
+        finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime stdin failed: ${error.message}` }))
+      })
+      void handle.done.then(
+        () => {
+          if (!settled) {
+            const stderr = handle.collected.stderr?.readFrom(0).text.trim()
+            finish(() => output.failure(logs, { kind: 'worker-exit', message: stderr === undefined || stderr === '' ? 'E2B runtime exited before completing' : `E2B runtime exited before completing: ${stderr}` }))
+          }
+        },
+        (error: unknown) => {
+          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime spawn failed: ${messageOf(error)}` }))
+        },
+      )
+
+      const onAbort = (): void => {
+        finish(() => output.failure(logs, { kind: 'abort', message: String(request.signal?.reason) }))
+      }
+      request.signal?.addEventListener('abort', onAbort, { once: true })
+      wallTimer.current = setTimeout(() => {
+        finish(() => output.failure(logs, { kind: 'timeout', message: `wall-clock ceiling reached (${this.config.maxWallMs}ms)` }))
+      }, this.config.maxWallMs)
+      this.live.add(live)
+      if (request.signal?.aborted === true) {
+        onAbort()
+        return
+      }
+      sendReply({
+        type: 'boot',
+        code,
+        namespaces: [...bindings].map(([global, namespace]) => ({
+          global,
+          names: Object.keys(namespace.functions),
+          ...namespace.errorClass === undefined ? {} : { errorClass: namespace.errorClass },
+        })),
+        computeMs: this.config.computeMs,
+        maxOutputBytes: this.config.maxOutputBytes,
+        maxOldGenerationSizeMb: this.config.maxOldGenerationSizeMb,
+      })
+    })
+  }
+
+  /* jscpd:ignore-start -- Code-runtime backends share the service lifecycle but own different child identities. */
+  private async teardown(): Promise<void> {
+    this.disposed = true
+    const runs = [...this.live]
+    for (const run of runs) run.settle({ kind: 'abort', message: 'runtime disposed' })
+    await Promise.all(runs.map(run => run.finished))
+  }
+  /* jscpd:ignore-end */
+}
+
+export default E2BCodeRuntime
diff --git a/packages/code-runtime/code-runtime-e2b/src/invariant.ts b/packages/code-runtime/code-runtime-e2b/src/invariant.ts
new file mode 100644
index 0000000000..4112cdc76b
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/src/invariant.ts
@@ -0,0 +1,20 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-code-runtime-e2b`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-code-runtime-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'code-runtime-e2b-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: the service owns every one-shot remote run. */
+const install: InvariantInstaller = () => {}
+
+/** Register this package's invariant companion. */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/code-runtime/code-runtime-e2b/src/runner-source.ts b/packages/code-runtime/code-runtime-e2b/src/runner-source.ts
new file mode 100644
index 0000000000..b0355f20ce
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/src/runner-source.ts
@@ -0,0 +1,460 @@
+/** Dependency-free remote code runner installed inside the E2B sandbox. */
+
+/** Node program that runs one model program in a fresh remote worker thread. */
+export const CODE_RUNNER_SOURCE = String.raw`import { Buffer } from 'node:buffer'
+import { inspect } from 'node:util'
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
+import { createInterface } from 'node:readline'
+
+const emitFrame = message => {
+  process.stdout.write(Buffer.from(JSON.stringify(message)).toString('base64') + '\n')
+}
+
+const parseFrame = line => JSON.parse(Buffer.from(line, 'base64').toString('utf8'))
+
+if (isMainThread) {
+  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
+  let worker
+  let finished = false
+  let computeTimer
+  const finish = message => {
+    if (finished) return
+    finished = true
+    clearInterval(computeTimer)
+    emitFrame(message)
+    const current = worker
+    worker = undefined
+    Promise.resolve(current ? current.terminate() : undefined).finally(() => {
+      input.close()
+      process.stdin.destroy()
+    })
+  }
+  input.on('line', line => {
+    let message
+    try {
+      message = parseFrame(line)
+    } catch (error) {
+      process.stderr.write('code-runtime-e2b frame error: ' + String(error) + '\n')
+      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received a malformed frame' } })
+      return
+    }
+    if (!worker) {
+      if (!message || message.type !== 'boot' || typeof message.code !== 'string' || !Array.isArray(message.namespaces)) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
+        return
+      }
+      worker = new Worker(new URL(import.meta.url), {
+        workerData: message,
+        env: {},
+        stdout: true,
+        stderr: true,
+        resourceLimits: { maxOldGenerationSizeMb: message.maxOldGenerationSizeMb },
+      })
+      worker.stdout.on('data', data => { emitFrame({ type: 'log', text: data.toString('utf8') }) })
+      worker.stderr.on('data', data => { emitFrame({ type: 'log', text: data.toString('utf8') }) })
+      worker.on('message', raw => {
+        if (!raw || typeof raw !== 'object') return
+        if (raw.type === 'call' && typeof raw.id === 'number' && typeof raw.global === 'string' && typeof raw.name === 'string' && Array.isArray(raw.args)) {
+          emitFrame({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
+        } else if (raw.type === 'log' && typeof raw.text === 'string') {
+          emitFrame({ type: 'log', text: raw.text })
+        } else if (raw.type === 'output-limit') {
+          finish({ type: 'output-limit' })
+        } else if (raw.type === 'done') {
+          if (raw.error && typeof raw.error === 'object' && typeof raw.error.kind === 'string' && typeof raw.error.message === 'string') {
+            finish({ type: 'done', error: { kind: raw.error.kind, message: raw.error.message } })
+          } else if (raw.value === undefined || Array.isArray(raw.value)) {
+            finish({ type: 'done', ...(raw.value === undefined ? {} : { value: raw.value }) })
+          }
+        }
+      })
+      worker.on('error', error => {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote worker error: ' + error.message } })
+      })
+      worker.on('exit', code => {
+        if (!finished) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote worker exited with code ' + code + ' before completing' } })
+      })
+      computeTimer = setInterval(() => {
+        if (!worker) return
+        if (worker.performance.eventLoopUtilization().active > message.computeMs) {
+          finish({ type: 'done', error: { kind: 'timeout', message: 'compute budget exhausted (' + message.computeMs + 'ms busy)' } })
+        }
+      }, 25)
+      return
+    }
+    if (message && message.type === 'reply' && typeof message.id === 'number' && typeof message.ok === 'boolean') {
+      worker.postMessage(message.ok
+        ? { type: 'reply', id: message.id, ok: true, value: message.value }
+        : { type: 'reply', id: message.id, ok: false, message: String(message.message) })
+    }
+  })
+  input.on('close', () => { if (worker && !finished) void worker.terminate() })
+} else {
+  const port = parentPort
+  if (!port) throw new Error('remote worker requires parentPort')
+
+  const CapturedError = Error
+  const ArrayIsArray = Array.isArray
+  const ArrayPrototype = Array.prototype
+  const ObjectPrototype = Object.prototype
+  const ObjectCreate = Object.create
+  const ObjectDefineProperty = Object.defineProperty
+  const ObjectGetPrototypeOf = Object.getPrototypeOf
+  const ObjectHasOwn = Object.hasOwn
+  const ObjectKeys = Object.keys
+  const ObjectIs = Object.is
+  const ObjectPropertyIsEnumerable = Object.prototype.propertyIsEnumerable
+  const ReflectOwnKeys = Reflect.ownKeys
+  const ReflectApply = Reflect.apply
+  const NumberIsFinite = Number.isFinite
+  const NumberIsSafeInteger = Number.isSafeInteger
+  const PromiseCtor = Promise
+  const PromiseReject = Promise.reject
+  const QueueMicrotask = queueMicrotask
+  const BufferByteLength = Buffer.byteLength
+  const SetCtor = Set
+  const SetAdd = Set.prototype.add
+  const SetDelete = Set.prototype.delete
+  const SetHas = Set.prototype.has
+  const MapDelete = Map.prototype.delete
+  const MapGet = Map.prototype.get
+  const MapSet = Map.prototype.set
+  const ArrayJoin = Array.prototype.join
+  const ArrayPop = Array.prototype.pop
+  const StringCharCodeAt = String.prototype.charCodeAt
+  const StringSlice = String.prototype.slice
+  const JSONStringify = JSON.stringify
+  const StringValue = String
+
+  const define = (target, key, value) => {
+    const descriptor = ObjectCreate(null)
+    descriptor.value = value
+    descriptor.enumerable = true
+    descriptor.configurable = true
+    descriptor.writable = true
+    ObjectDefineProperty(target, key, descriptor)
+  }
+  const append = (target, value) => { define(target, target.length, value) }
+  const pop = target => ReflectApply(ArrayPop, target, [])
+  const setAdd = (target, value) => { ReflectApply(SetAdd, target, [value]) }
+  const setDelete = (target, value) => { ReflectApply(SetDelete, target, [value]) }
+  const setHas = (target, value) => ReflectApply(SetHas, target, [value])
+  const mapDelete = (target, key) => { ReflectApply(MapDelete, target, [key]) }
+  const mapGet = (target, key) => ReflectApply(MapGet, target, [key])
+  const mapSet = (target, key, value) => { ReflectApply(MapSet, target, [key, value]) }
+  const plainObject = value => {
+    const prototype = ObjectGetPrototypeOf(value)
+    return prototype === null || prototype === ObjectPrototype
+  }
+  const ownEnumerableStringKeys = value => {
+    const keys = ReflectOwnKeys(value)
+    for (let index = 0; index < keys.length; index++) {
+      const key = keys[index]
+      if (typeof key !== 'string' || !ReflectApply(ObjectPropertyIsEnumerable, value, [key])) return undefined
+    }
+    return keys
+  }
+  const assign = (destination, value) => {
+    if (destination.kind === 'root') destination.holder.value = value
+    else define(destination.target, destination.key, value)
+  }
+  const snapshot = input => {
+    const active = new SetCtor()
+    const holder = ObjectCreate(null)
+    const tasks = [{ kind: 'visit', value: input, destination: { kind: 'root', holder } }]
+    while (tasks.length) {
+      const task = pop(tasks)
+      if (task.kind === 'leave') { setDelete(active, task.source); continue }
+      const candidate = task.value
+      if (candidate === null || typeof candidate === 'boolean' || typeof candidate === 'string') {
+        assign(task.destination, candidate); continue
+      }
+      if (typeof candidate === 'number') {
+        if (!NumberIsFinite(candidate) || ObjectIs(candidate, -0)) return undefined
+        assign(task.destination, candidate); continue
+      }
+      if (typeof candidate !== 'object' || setHas(active, candidate)) return undefined
+      if (ArrayIsArray(candidate)) {
+        if (ObjectGetPrototypeOf(candidate) !== ArrayPrototype || ReflectOwnKeys(candidate).length !== candidate.length + 1) return undefined
+        const target = []
+        assign(task.destination, target)
+        setAdd(active, candidate)
+        append(tasks, { kind: 'leave', source: candidate })
+        for (let index = candidate.length - 1; index >= 0; index--) {
+          if (!ObjectHasOwn(candidate, index)) return undefined
+          append(tasks, { kind: 'visit', value: candidate[index], destination: { kind: 'slot', target, key: index } })
+        }
+        continue
+      }
+      if (!plainObject(candidate)) return undefined
+      const keys = ownEnumerableStringKeys(candidate)
+      if (!keys) return undefined
+      const target = {}
+      assign(task.destination, target)
+      setAdd(active, candidate)
+      append(tasks, { kind: 'leave', source: candidate })
+      for (let index = keys.length - 1; index >= 0; index--) {
+        const key = keys[index]
+        append(tasks, { kind: 'visit', value: candidate[key], destination: { kind: 'slot', target, key } })
+      }
+    }
+    return holder.value
+  }
+  const encodeWire = value => {
+    const wire = []
+    const pending = [value]
+    while (pending.length) {
+      const current = pop(pending)
+      if (current === null || typeof current === 'boolean' || typeof current === 'number' || typeof current === 'string') {
+        append(wire, current); continue
+      }
+      if (ArrayIsArray(current)) {
+        append(wire, { kind: 'array', length: current.length })
+        for (let index = current.length - 1; index >= 0; index--) append(pending, current[index])
+      } else {
+        const keys = ObjectKeys(current)
+        append(wire, { kind: 'object', keys })
+        for (let index = keys.length - 1; index >= 0; index--) append(pending, current[keys[index]])
+      }
+    }
+    return wire
+  }
+  const decodeWire = wire => {
+    if (!ArrayIsArray(wire) || wire.length === 0) return undefined
+    const frames = []
+    let root
+    let assigned = false
+    const attach = value => {
+      const parent = frames[frames.length - 1]
+      if (!parent) {
+        if (assigned) return false
+        root = value; assigned = true; return true
+      }
+      if (parent.kind === 'array') append(parent.target, value)
+      else define(parent.target, parent.keys[parent.index], value)
+      parent.index += 1
+      return true
+    }
+    for (let tokenIndex = 0; tokenIndex < wire.length; tokenIndex++) {
+      const token = wire[tokenIndex]
+      let value
+      let frame
+      if (token === null || typeof token === 'boolean' || typeof token === 'string') value = token
+      else if (typeof token === 'number') {
+        if (!NumberIsFinite(token) || ObjectIs(token, -0)) return undefined
+        value = token
+      } else {
+        if (!plainObject(token)) return undefined
+        const keys = ownEnumerableStringKeys(token)
+        if (!keys || keys.length !== 2 || keys[0] !== 'kind') return undefined
+        if (token.kind === 'array' && keys[1] === 'length' && NumberIsSafeInteger(token.length) && token.length >= 0) {
+          value = []
+          if (token.length > wire.length - tokenIndex - 1) return undefined
+          if (token.length) frame = { kind: 'array', target: value, length: token.length, index: 0 }
+        } else if (token.kind === 'object' && keys[1] === 'keys' && ArrayIsArray(token.keys)) {
+          const unique = new SetCtor()
+          const objectKeys = []
+          for (const key of token.keys) {
+            if (typeof key !== 'string' || setHas(unique, key)) return undefined
+            setAdd(unique, key); append(objectKeys, key)
+          }
+          if (objectKeys.length > wire.length - tokenIndex - 1) return undefined
+          value = {}
+          if (objectKeys.length) frame = { kind: 'object', target: value, keys: objectKeys, index: 0 }
+        } else return undefined
+      }
+      if (!attach(value)) return undefined
+      if (frame) append(frames, frame)
+      while (frames.length) {
+        const current = frames[frames.length - 1]
+        const length = current.kind === 'array' ? current.length : current.keys.length
+        if (current.index < length) break
+        pop(frames)
+      }
+    }
+    return frames.length === 0 ? root : undefined
+  }
+  const byteLength = text => ReflectApply(BufferByteLength, Buffer, [text])
+  const jsonStringBytes = text => byteLength(JSONStringify(text))
+  const jsonValueBytes = value => {
+    let bytes = 0
+    const tasks = [{ kind: 'value', value }]
+    while (tasks.length) {
+      const task = pop(tasks)
+      if (task.kind === 'separator') { bytes += 1; continue }
+      if (task.kind === 'key') { bytes += jsonStringBytes(task.value) + 1; continue }
+      const current = task.value
+      if (current === null) bytes += 4
+      else if (typeof current === 'string') bytes += jsonStringBytes(current)
+      else if (typeof current === 'number' || typeof current === 'boolean') bytes += byteLength(StringValue(current))
+      else if (ArrayIsArray(current)) {
+        bytes += 2
+        for (let index = current.length - 1; index >= 0; index--) {
+          append(tasks, { kind: 'value', value: current[index] })
+          if (index > 0) append(tasks, { kind: 'separator' })
+        }
+      } else {
+        bytes += 2
+        const keys = ObjectKeys(current)
+        for (let index = keys.length - 1; index >= 0; index--) {
+          const key = keys[index]
+          append(tasks, { kind: 'value', value: current[key] })
+          append(tasks, { kind: 'key', value: key })
+          if (index > 0) append(tasks, { kind: 'separator' })
+        }
+      }
+    }
+    return bytes
+  }
+  const truncate = (text, available) => {
+    if (available < 2) return ''
+    let result = ''
+    let bytes = 2
+    let index = 0
+    while (index < text.length) {
+      const first = ReflectApply(StringCharCodeAt, text, [index])
+      let end = index + 1
+      if (first >= 0xd800 && first <= 0xdbff && end < text.length) {
+        const second = ReflectApply(StringCharCodeAt, text, [end])
+        if (second >= 0xdc00 && second <= 0xdfff) end += 1
+      }
+      const character = ReflectApply(StringSlice, text, [index, end])
+      const cost = jsonStringBytes(character) - 2
+      if (bytes + cost > available) break
+      bytes += cost
+      result += character
+      index = end
+    }
+    return result
+  }
+  let logBytes = 2
+  let logEntries = 0
+  let limited = false
+  const pushLog = text => {
+    if (limited) return
+    const separator = logEntries > 0 ? 1 : 0
+    const available = workerData.maxOutputBytes - logBytes - separator
+    const cost = jsonStringBytes(text)
+    if (cost > available) {
+      const prefix = truncate(text, available)
+      if (prefix) {
+        logBytes += jsonStringBytes(prefix) + separator
+        logEntries += 1
+        port.postMessage({ type: 'log', text: prefix })
+      }
+      limited = true
+      port.postMessage({ type: 'output-limit' })
+      return
+    }
+    logBytes += cost + separator
+    logEntries += 1
+    port.postMessage({ type: 'log', text })
+  }
+  const originalStdout = process.stdout.write
+  const originalStderr = process.stderr.write
+  process.stdout.write = (chunk, ...rest) => {
+    pushLog(typeof chunk === 'string' ? chunk : StringValue(chunk))
+    let callback
+    for (let index = 0; index < rest.length; index++) {
+      if (typeof rest[index] === 'function') { callback = rest[index]; break }
+    }
+    if (callback) QueueMicrotask(() => { callback(null) })
+    return true
+  }
+  process.stderr.write = process.stdout.write
+  const consoleShim = ObjectCreate(null)
+  for (const level of ['log', 'info', 'warn', 'error', 'debug']) {
+    define(consoleShim, level, (...args) => {
+      const rendered = []
+      for (let index = 0; index < args.length; index++) {
+        const value = args[index]
+        append(rendered, typeof value === 'string' ? value : inspect(value, { depth: 4, maxArrayLength: 100, maxStringLength: 10000 }))
+      }
+      pushLog(ReflectApply(ArrayJoin, rendered, [' ']))
+    })
+  }
+  const pending = new Map()
+  let nextId = 1
+  const errorClasses = new Map()
+  for (const namespace of workerData.namespaces) {
+    if (!namespace.errorClass) continue
+    const descriptor = namespace.errorClass
+    mapSet(errorClasses, namespace.global, class BindingCallError extends CapturedError {
+      constructor(memberName, message) {
+        super(message)
+        ObjectDefineProperty(this, 'name', { value: descriptor.name, enumerable: true })
+        ObjectDefineProperty(this, descriptor.memberNameProperty, { value: memberName, enumerable: true })
+      }
+    })
+  }
+  port.on('message', message => {
+    if (!message || message.type !== 'reply' || typeof message.id !== 'number') return
+    const entry = mapGet(pending, message.id)
+    if (!entry) return
+    mapDelete(pending, message.id)
+    if (!message.ok) { entry.reject(new CapturedError(StringValue(message.message))); return }
+    const value = decodeWire(message.value)
+    if (value === undefined) entry.reject(new CapturedError('binding resolution must be lossless JSON'))
+    else entry.resolve(value)
+  })
+  const namespaces = workerData.namespaces.map(namespace => {
+    const target = ObjectCreate(null)
+    const ErrorClass = mapGet(errorClasses, namespace.global)
+    for (const name of namespace.names) {
+      define(target, name, args => {
+        const detached = snapshot(args)
+        if (detached === undefined) {
+          return ReflectApply(PromiseReject, PromiseCtor, [ErrorClass ? new ErrorClass(name, 'binding arguments must be lossless JSON') : new CapturedError('binding arguments must be lossless JSON')])
+        }
+        return new PromiseCtor((resolve, reject) => {
+          const id = nextId++
+          mapSet(pending, id, {
+            resolve,
+            reject: error => { reject(ErrorClass ? new ErrorClass(name, error.message) : error) },
+          })
+          port.postMessage({ type: 'call', id, global: namespace.global, name, args: encodeWire(detached) })
+        })
+      })
+    }
+    return target
+  })
+  const errorClassNames = []
+  const errorClassValues = []
+  for (const namespace of workerData.namespaces) {
+    if (!namespace.errorClass) continue
+    append(errorClassNames, namespace.errorClass.name)
+    append(errorClassValues, mapGet(errorClasses, namespace.global))
+  }
+  const AsyncFunction = ObjectGetPrototypeOf(async function () {}).constructor
+  try {
+    const fn = new AsyncFunction(...workerData.namespaces.map(value => value.global), ...errorClassNames, 'console', '"use strict";\n' + workerData.code)
+    const value = await fn(...namespaces, ...errorClassValues, consoleShim)
+    if (!limited) {
+      if (value === undefined) port.postMessage({ type: 'done' })
+      else {
+        const detached = snapshot(value)
+        if (detached === undefined) {
+          const message = 'program completion must be lossless JSON'
+          if (jsonStringBytes(message) > workerData.maxOutputBytes - logBytes) port.postMessage({ type: 'output-limit' })
+          else port.postMessage({ type: 'done', error: { kind: 'invalid-output', message } })
+        } else if (jsonValueBytes(detached) > workerData.maxOutputBytes - logBytes) {
+          port.postMessage({ type: 'output-limit' })
+        } else {
+          port.postMessage({ type: 'done', value: encodeWire(detached) })
+        }
+      }
+    }
+  } catch (error) {
+    if (!limited) {
+      let message
+      try { message = error instanceof CapturedError ? error.stack || error.message : StringValue(error) }
+      catch { message = 'program threw an unrenderable value' }
+      if (jsonStringBytes(message) > workerData.maxOutputBytes - logBytes) port.postMessage({ type: 'output-limit' })
+      else port.postMessage({ type: 'done', error: { kind: 'exception', message } })
+    }
+  } finally {
+    process.stdout.write = originalStdout
+    process.stderr.write = originalStderr
+  }
+}
+`
diff --git a/packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts b/packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts
new file mode 100644
index 0000000000..ff1c5dd84a
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts
@@ -0,0 +1,460 @@
+import { PassThrough, Writable } from 'node:stream'
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import type { Sandbox } from '@deepseek-ai/dsh-e2b'
+import {
+  E2BFrameDecoder,
+  encodeE2BFrame,
+} from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import type {
+  SubprocessHandle,
+  SubprocessOutcome,
+  SubprocessSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import {
+  encodeWorkerJson,
+} from '@deepseek-ai/dsh-code-runtime-worker'
+import E2BCodeRuntime from '@deepseek-ai/dsh-code-runtime-e2b'
+import * as E2BCodeRuntimeInvariant from '../src/invariant.ts'
+import { CODE_RUNNER_SOURCE } from '../src/runner-source.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+class FakeHandle implements SubprocessHandle {
+  readonly pid = 123
+  readonly stdin: Writable | undefined
+  readonly stdout: PassThrough | undefined
+  readonly stderr = undefined
+  readonly collected: SubprocessHandle['collected']
+  readonly done: Promise<SubprocessOutcome>
+  readonly writes: unknown[] = []
+  readonly result = Promise.withResolvers<SubprocessOutcome>()
+  terminated = 0
+  waitCalls = 0
+  private readonly decoder = new E2BFrameDecoder(10_000_000)
+  private readonly waitError: Error | undefined
+  private settled = false
+
+  constructor(
+    private readonly onMessage: (message: unknown, handle: FakeHandle) => void = () => {},
+    options: { stdin?: boolean; stdout?: boolean; stderr?: string; writeError?: Error; waitError?: Error } = {},
+  ) {
+    this.waitError = options.waitError
+    this.stdin = options.stdin === false
+      ? undefined
+      : options.writeError === undefined
+        ? new PassThrough()
+        : new Writable({ write: (_chunk, _encoding, callback) => { callback(options.writeError) } })
+    this.stdout = options.stdout === false ? undefined : new PassThrough()
+    this.collected = options.stderr === undefined
+      ? {}
+      : { stderr: { readFrom: () => ({ text: options.stderr as string, nextOffset: 0, lossy: false }) } }
+    this.done = this.result.promise
+    this.stdin?.on('data', (chunk: Buffer) => {
+      for (const message of this.decoder.push(chunk.toString('ascii'))) {
+        this.writes.push(message)
+        this.onMessage(message, this)
+      }
+    })
+  }
+
+  emit(message: unknown): void {
+    this.stdout?.write(encodeE2BFrame(message))
+  }
+
+  emitRaw(text: string): void {
+    this.stdout?.write(text)
+  }
+
+  exit(outcome: SubprocessOutcome = { exitCode: 0, signal: null }): void {
+    if (this.settled) return
+    this.settled = true
+    this.stdout?.end()
+    this.result.resolve(outcome)
+  }
+
+  crash(error: unknown): void {
+    if (this.settled) return
+    this.settled = true
+    this.stdout?.end()
+    this.result.reject(error)
+  }
+
+  terminate(): void {
+    this.terminated += 1
+    this.exit({ exitCode: null, signal: 'SIGTERM' })
+  }
+
+  async waitForExit(): Promise<boolean> {
+    this.waitCalls += 1
+    if (this.waitError !== undefined) throw this.waitError
+    return true
+  }
+}
+
+interface RuntimeFixture {
+  ctx: Context
+  fiber: Awaited<ReturnType<Context['plugin']>>
+  runtime: E2BCodeRuntime
+  sandbox: Sandbox
+  spawn: ReturnType<typeof vi.fn<(spec: SubprocessSpawnSpec) => SubprocessHandle>>
+  write: ReturnType<typeof vi.fn>
+  run: ReturnType<typeof vi.fn>
+}
+
+async function setup(
+  handles: FakeHandle[] = [],
+  config: Record<string, number> = {},
+  sandboxOverrides: Partial<Sandbox> = {},
+  getSandbox?: () => Promise<Sandbox>,
+): Promise<RuntimeFixture> {
+  const write = vi.fn().mockResolvedValue([])
+  const run = vi.fn().mockImplementation(async (command: string) => ({
+    exitCode: 0,
+    stdout: command.startsWith('command -v') ? '/usr/bin/node\n' : '',
+    stderr: '',
+  }))
+  const sandbox = {
+    files: { write },
+    commands: { run },
+    ...sandboxOverrides,
+  } as unknown as Sandbox
+  const e2b = {
+    cwd: '/workspace',
+    runtimeRoot: '/workspace/.dsh-e2b',
+    getSandbox: getSandbox ?? (async () => sandbox),
+  } as unknown as E2BSandboxService
+  const spawn = vi.fn<(spec: SubprocessSpawnSpec) => SubprocessHandle>(() => {
+    const handle = handles.shift()
+    if (handle === undefined) throw new Error('no fake handle queued')
+    return handle
+  })
+  const subprocess = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
+  Object.defineProperty(subprocess, 'spawn', { value: spawn })
+  const ctx = new Context()
+  ctx.provide('e2b', e2b)
+  ctx.provide('subprocess', subprocess)
+  const fiber = await ctx.plugin(E2BCodeRuntime, config)
+  return { ctx, fiber, runtime: ctx.codeRuntime as E2BCodeRuntime, sandbox, spawn, write, run }
+}
+
+function request(program = 'return 1') {
+  return { program, bindings: [] }
+}
+
+describe('E2BCodeRuntime', () => {
+  it('prepares the remote runner and returns logs and a lossless completion', async () => {
+    const handle = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type !== 'boot') return
+      current.emit({ type: 'log', text: 'remote 你好' })
+      current.emitRaw(
+        encodeE2BFrame({ type: 'done', value: encodeWorkerJson({ answer: 42 }) })
+        + encodeE2BFrame({ type: 'log', text: 'ignored after done' }),
+      )
+      current.emit({ type: 'log', text: 'also ignored after done' })
+    })
+    const fixture = await setup([handle])
+
+    await expect(fixture.runtime.run(request('const answer: number = 42; return { answer }')))
+      .resolves.toEqual({ logs: ['remote 你好'], value: { answer: 42 } })
+    expect(fixture.runtime.language).toBe('typescript')
+    expect(fixture.runtime.isolation).toBe('container')
+    expect(fixture.write).toHaveBeenCalledWith([{ path: '/workspace/.dsh-e2b/code-runtime-runner.mjs', data: CODE_RUNNER_SOURCE }])
+    expect(fixture.run).toHaveBeenCalledWith("chmod 600 -- '/workspace/.dsh-e2b/code-runtime-runner.mjs'")
+    expect(fixture.spawn).toHaveBeenCalledWith(expect.objectContaining({
+      argv: ['/usr/bin/node', '/workspace/.dsh-e2b/code-runtime-runner.mjs'],
+      cwd: '/workspace',
+      env: {},
+    }))
+    expect(handle.terminated).toBe(1)
+    expect(handle.waitCalls).toBe(1)
+    await fixture.fiber.dispose()
+  })
+
+  it('bridges binding success, host rejection, unknown members, and invalid values', async () => {
+    const replies: unknown[] = []
+    const handle = new FakeHandle((message, current) => {
+      const record = message as { type?: string; id?: number; ok?: boolean }
+      if (record.type === 'boot') {
+        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'double', args: encodeWorkerJson({ value: 4 }) })
+        current.emit({ type: 'call', id: 2, global: 'bridge', name: 'fail', args: encodeWorkerJson(null) })
+        current.emit({ type: 'call', id: 3, global: 'bridge', name: 'missing', args: encodeWorkerJson(null) })
+        current.emit({ type: 'call', id: 4, global: 'bridge', name: 'double', args: [] })
+        current.emit({ type: 'call', id: 5, global: 'bridge', name: 'invalid', args: encodeWorkerJson(null) })
+        current.emit({ type: 'call', id: 6, global: 'bridge', name: 'throwing', args: encodeWorkerJson(null) })
+        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'double', args: encodeWorkerJson({ value: 99 }) })
+        return
+      }
+      if (record.type === 'reply') {
+        replies.push(message)
+        if (replies.length === 6) current.emit({ type: 'done', value: encodeWorkerJson('done') })
+      }
+    })
+    const fixture = await setup([handle])
+    const result = await fixture.runtime.run({
+      program: 'return await bridge.double({ value: 4 })',
+      bindings: [
+        {
+          global: 'bridge',
+          errorClass: { name: 'BridgeError', memberNameProperty: 'member' },
+          functions: {
+            double: async args => (args as { value: number }).value * 2,
+            fail: async () => { throw 'nope' },
+            invalid: (async () => undefined) as never,
+            throwing: async () => Object.defineProperty({}, 'value', {
+              enumerable: true,
+              get: () => { throw new Error('getter failed') },
+            }),
+          },
+        },
+        { global: 'plain', functions: {} },
+      ],
+    })
+
+    expect(result).toEqual({ logs: [], value: 'done' })
+    expect(replies.sort((left, right) => (left as { id: number }).id - (right as { id: number }).id)).toEqual([
+      { type: 'reply', id: 1, ok: true, value: encodeWorkerJson(8) },
+      { type: 'reply', id: 2, ok: false, message: 'nope' },
+      { type: 'reply', id: 3, ok: false, message: 'unknown binding "bridge.missing"' },
+      { type: 'reply', id: 4, ok: false, message: 'binding arguments must be lossless JSON' },
+      { type: 'reply', id: 5, ok: false, message: 'binding resolution must be lossless JSON' },
+      { type: 'reply', id: 6, ok: false, message: 'binding resolution must be lossless JSON' },
+    ])
+    await fixture.fiber.dispose()
+  })
+
+  it('ignores malformed runner traffic and classifies terminal runner messages', async () => {
+    const ignored = [
+      null, 1, {}, { type: 'log' }, { type: 'call' },
+      { type: 'call', id: 0, global: 'x', name: 'y', args: [] },
+      { type: 'call', id: 1, global: 1, name: 'y', args: [] },
+      { type: 'call', id: 1, global: 'x', name: 1, args: [] },
+      { type: 'call', id: 1, global: 'x', name: 'y', args: {} },
+      { type: 'done', error: null },
+      { type: 'done', error: { kind: 'invented', message: 'x' } },
+      { type: 'done', error: { kind: 'exception', message: 1 } },
+    ]
+    const handles = [
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type !== 'boot') return
+        for (const item of ignored) current.emit(item)
+        current.emit({ type: 'done' })
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done', error: { kind: 'exception', message: 'boom' } })
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done', value: [] })
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'output-limit' })
+      }),
+    ]
+    const fixture = await setup(handles, { maxOutputBytes: 64, maxFrameBytes: 128 })
+
+    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [] })
+    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'exception', message: 'boom' } })
+    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' } })
+    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' } })
+    await fixture.fiber.dispose()
+  })
+
+  it('enforces the host output ledger and catches malformed bridge output', async () => {
+    const handles = [
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'log', text: 'x'.repeat(1_000) })
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emitRaw('not-base64\n')
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.emitRaw('é')
+      }),
+      new FakeHandle((message, current) => {
+        if ((message as { type?: string }).type === 'boot') current.stdout?.emit('error', new Error('stdout broke'))
+      }),
+    ]
+    const fixture = await setup(handles, { maxOutputBytes: 128, maxFrameBytes: 4_096 })
+
+    expect((await fixture.runtime.run(request())).error?.kind).toBe('output-limit')
+    const malformed = (await fixture.runtime.run(request())).error
+    expect(malformed?.kind).toBe('worker-exit')
+    expect(malformed?.message).toContain('bridge failed')
+    expect((await fixture.runtime.run(request())).error?.message).toContain('non-ASCII')
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime stdout failed: stdout broke' })
+    await fixture.fiber.dispose()
+  })
+
+  it('contains stdin errors, process exits, spawn failures, and missing pipes', async () => {
+    const writeError = new FakeHandle(() => {}, { writeError: new Error('write callback broke') })
+    const stdinError = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') current.stdin?.emit('error', new Error('stdin broke'))
+    })
+    const earlyExit = new FakeHandle(() => {}, { stderr: 'remote diagnostic' })
+    const quietExit = new FakeHandle()
+    const emptyStderrExit = new FakeHandle(() => {}, { stderr: '' })
+    const spawnFailure = new FakeHandle()
+    const missingStdin = new FakeHandle(() => {}, { stdin: false })
+    const missingStdout = new FakeHandle(() => {}, { stdout: false, waitError: new Error('missing-stream process query failed') })
+    const truncated = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') {
+        current.emitRaw('YQ==')
+        setImmediate(() => { current.exit() })
+      }
+    })
+    const cleanupFailure = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done' })
+    }, { waitError: new Error('process query failed') })
+    const fixture = await setup([
+      writeError, stdinError, earlyExit, quietExit, emptyStderrExit,
+      spawnFailure, missingStdin, missingStdout, truncated, cleanupFailure,
+    ])
+
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime bridge write failed: write callback broke' })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime stdin failed: stdin broke' })
+    setImmediate(() => { earlyExit.exit() })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing: remote diagnostic' })
+    setImmediate(() => { quietExit.exit() })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing' })
+    setImmediate(() => { emptyStderrExit.exit() })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing' })
+    setImmediate(() => { spawnFailure.crash('spawn rejected') })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime spawn failed: spawn rejected' })
+    expect((await fixture.runtime.run(request())).error?.message).toContain('dropped a piped runtime stream')
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime cleanup failed: missing-stream process query failed' })
+    expect(missingStdin.terminated).toBe(1)
+    expect(missingStdin.waitCalls).toBe(1)
+    expect(missingStdout.terminated).toBe(1)
+    expect(missingStdout.waitCalls).toBe(1)
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B frame stream ended mid-frame' })
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime cleanup failed: process query failed' })
+    await fixture.fiber.dispose()
+  })
+
+  it('reports wall timeout, abort, pre-abort, type-strip failure, and disposal', async () => {
+    const timeout = new FakeHandle()
+    const abort = new FakeHandle()
+    const disposing = new FakeHandle()
+    const fixture = await setup([timeout, abort, disposing], { maxWallMs: 20 })
+
+    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'timeout', message: 'wall-clock ceiling reached (20ms)' })
+    const controller = new AbortController()
+    const aborting = fixture.runtime.run({ ...request(), signal: controller.signal })
+    controller.abort('stop')
+    expect((await aborting).error).toEqual({ kind: 'abort', message: 'stop' })
+    expect((await fixture.runtime.run({ ...request(), signal: AbortSignal.abort('already') })).error)
+      .toEqual({ kind: 'abort', message: 'already' })
+    expect((await fixture.runtime.run(request('enum E { A }'))).error?.kind).toBe('exception')
+
+    const live = fixture.runtime.run(request())
+    await new Promise(resolve => setImmediate(resolve))
+    await fixture.fiber.dispose()
+    expect((await live).error).toEqual({ kind: 'abort', message: 'runtime disposed' })
+    await expect(fixture.runtime.run(request())).rejects.toThrow('after disposal')
+  })
+
+  it('drops binding replies that settle after abort', async () => {
+    const controller = new AbortController()
+    const resolution = Promise.withResolvers<string>()
+    const invoked = Promise.withResolvers<undefined>()
+    const handle = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') {
+        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'late', args: encodeWorkerJson(null) })
+      }
+    })
+    const fixture = await setup([handle])
+    const running = fixture.runtime.run({
+      program: 'return await bridge.late(null)',
+      bindings: [{
+        global: 'bridge',
+        functions: {
+          late: async () => {
+            invoked.resolve(undefined)
+            return await resolution.promise
+          },
+        },
+      }],
+      signal: controller.signal,
+    })
+    await invoked.promise
+    controller.abort('stop')
+    expect((await running).error).toEqual({ kind: 'abort', message: 'stop' })
+    resolution.resolve('late')
+    await new Promise(resolve => setImmediate(resolve))
+    expect(handle.writes).toHaveLength(1)
+    await fixture.fiber.dispose()
+  })
+
+  it('validates binding and runtime configuration before remote execution', async () => {
+    const fixture = await setup([])
+    const invalidRequests = [
+      { global: 'not-valid!', functions: {} },
+      { global: 'await', functions: {} },
+      { global: 'console', functions: {} },
+      { global: 'same', functions: {} },
+      { global: 'same', functions: {} },
+      { global: 'ok', functions: {}, errorClass: { name: 'not-valid!', memberNameProperty: 'member' } },
+      { global: 'ok', functions: {}, errorClass: { name: 'await', memberNameProperty: 'member' } },
+      { global: 'Clash', functions: {}, errorClass: { name: 'Clash', memberNameProperty: 'member' } },
+      { global: 'one', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'member' } },
+      { global: 'two', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'member' } },
+      { global: 'ok', functions: {}, errorClass: { name: 'Err', memberNameProperty: '' } },
+      { global: 'ok', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'message' } },
+    ]
+    for (const bindings of [
+      [invalidRequests[0]], [invalidRequests[1]], [invalidRequests[2]],
+      invalidRequests.slice(3, 5), [invalidRequests[5]], [invalidRequests[6]],
+      [invalidRequests[7]], invalidRequests.slice(8, 10), [invalidRequests[10]], [invalidRequests[11]],
+    ]) {
+      await expect(fixture.runtime.run({ program: 'return 1', bindings: bindings as never })).rejects.toThrow()
+    }
+    await fixture.fiber.dispose()
+
+    for (const config of [
+      { computeMs: 0 }, { computeMs: 1.5 }, { maxOutputBytes: 3 },
+      { maxWallMs: 2_147_483_648 }, { maxFrameBytes: 10, maxOutputBytes: 20 },
+    ]) {
+      const ctx = new Context()
+      const subprocess = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
+      ctx.provide('e2b', { getSandbox: async () => ({}) } as never)
+      ctx.provide('subprocess', subprocess)
+      await expect(ctx.plugin(E2BCodeRuntime, config)).rejects.toThrow()
+    }
+
+    const wrong = new Context()
+    wrong.provide('e2b', { getSandbox: async () => ({}) } as never)
+    wrong.provide('subprocess', {} as never)
+    await expect(wrong.plugin(E2BCodeRuntime, {})).rejects.toThrow('dsh-subprocess-e2b')
+  })
+
+  it('turns asynchronous runtime preparation failure into a run result', async () => {
+    const sandbox = {
+      files: { write: vi.fn().mockRejectedValue(new Error('upload failed')) },
+      commands: { run: vi.fn() },
+    } as unknown as Sandbox
+    const fixture = await setup([], {}, sandbox)
+    expect((await fixture.runtime.run(request())).error).toEqual({
+      kind: 'worker-exit',
+      message: 'E2B runtime setup failed: upload failed',
+    })
+    await fixture.fiber.dispose()
+  })
+
+  it('returns disposal when remote preparation completes after teardown', async () => {
+    const gate = Promise.withResolvers<Sandbox>()
+    const fixture = await setup([], {}, {}, () => gate.promise)
+    const running = fixture.runtime.run(request())
+    await (fixture.runtime as unknown as { teardown(): Promise<void> }).teardown()
+    gate.resolve(fixture.sandbox)
+    expect((await running).error).toEqual({ kind: 'abort', message: 'runtime disposed' })
+    await fixture.fiber.dispose()
+  })
+
+  it('registers the package-owned invariant companion', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BCodeRuntimeInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/code-runtime/code-runtime-e2b/tsconfig.json b/packages/code-runtime/code-runtime-e2b/tsconfig.json
new file mode 100644
index 0000000000..4ddc3b5ffe
--- /dev/null
+++ b/packages/code-runtime/code-runtime-e2b/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../code-runtime" },
+    { "path": "../code-runtime-worker" },
+    { "path": "../../e2b/e2b" },
+    { "path": "../../core/session" },
+    { "path": "../../subprocess/subprocess-e2b" },
+    { "path": "../../util/timeout" },
+    { "path": "../../support/invariants" }
+  ]
+}
diff --git a/packages/code-runtime/code-runtime-worker/README.i18n.yaml b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
index 8d3568e82e..d3472a697e 100644
--- a/packages/code-runtime/code-runtime-worker/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-worker/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/code-runtime/code-runtime-worker/README.md
-README.md: 590b79dcd1bc322350060b55767b09c6305edacc
-README.zh.md: 12c25f892bd20892cb47e593f16b6aadd9ffa84c
+README.md: 4b14c6fad5d1e491faeb54c9cb0e4403c8e2d8dd
+README.zh.md: c522917835b562cf7648d8bc78f0315b7c52d2d2
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index 590b79dcd1..4b14c6fad5 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -32,7 +32,7 @@ Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at
 
 ## The worker entry, unbuilt and built
 
-Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local and session-owned JSON boundaries both flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. The repository-wide requirement to exercise this published entry path belongs to the [testing policy](../../../docs/testing.md).
+Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local JSON snapshotter is parity-tested against the session-owned canonical boundary; both sides flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. `tests/built-lib.e2e.ts` pins the real load path required by [docs/testing.md](../../../docs/testing.md).
 
 The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
 
@@ -46,8 +46,8 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only, weaker than bash-local's process-group kill; orphan cleanup is a deployment concern until a container backend exists.
-- **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — amaro or sucrase are the named drop-in replacements if the relied-on behavior shifts.
+- **OS processes a program spawns survive this backend's termination** — `worker.terminate()` ends only the thread; deployments needing remote process-group cleanup can select the E2B backend, whose separate limitations still apply.
+- **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — the relied-on behavior is pinned by unit tests, with amaro/sucrase as named drop-in replacements if it shifts.
 - **`computeMs` expiry can overshoot by up to one poll interval** — busy time is sampled every 25 ms (an internal constant, deliberately not config).
 - **Programs get a five-method `console` shim** (`log`/`info`/`warn`/`error`/`debug`) — deliberately not Node's full console surface.
 - **Intermediate binding values have no byte cap** — a program can exhaust process or worker memory with a value that never becomes outer output.
diff --git a/packages/code-runtime/code-runtime-worker/README.zh.md b/packages/code-runtime/code-runtime-worker/README.zh.md
index 12c25f892b..c522917835 100644
--- a/packages/code-runtime/code-runtime-worker/README.zh.md
+++ b/packages/code-runtime/code-runtime-worker/README.zh.md
@@ -23,18 +23,18 @@
 - **每次运行使用一个全新 worker，不设池化**：程序所在的世界会随 worker 一同终止，不会留下需要记录的跨运行状态，也无法发生状态泄漏；仅凭会话日志即可重建运行。
 - **在执行上下文中，由宿主侧剥离类型**：程序会包裹在异步函数外壳中，通过 `node:module` 的 `stripTypeScriptTypes` 剥离类型（只支持可擦除语法；`enum`／namespace 会作为程序 `exception` 被拒绝，且不会启动 worker），再按字节位置切回原内容。之后程序作为 `AsyncFunction` 的函数体执行，因此顶层 `await`／`return` 可用。
 - **端口把对端视为不可信**：模型代码能够访问 `parentPort` 并伪造通信，因此任何代码读取入站消息前，系统都会验证其形状并重新构建（`null`、原始值、无效类型和格式错误的载荷会被静默丢弃；伪造的额外字段绝不会被带入）；宿主对每个调用 id 最多响应一次，只将绑定名称解析为自有属性（伪造的 `constructor` 无法沿原型链访问），丢弃结算后的回复，并验证每个绑定 resolve 值与完成值是否为无损 JSON。伪造的 `log`／`done` 消息无法绕过外层上限：宿主会再次验证，并统计每条获准日志以及完成值或诊断。worker 侧命名空间使用 null-prototype 和 `defineProperty`，因此形似 `__proto__` 的绑定名称只是普通键。
-- **绑定调用被拒绝时使用的异常类属于请求数据**：可选命名空间描述符会指定构造器全局变量，以及用于接收调用失败的成员名称的自有属性。worker 会创建并注入该真实类，使 `instanceof` 生效，同时无需硬编码 `tools` 或 `ToolCallError`；全局变量无效或冲突的声明会在启动 worker 前失败。失败路径使用模块捕获的错误 intrinsic 与属性定义 intrinsic，以及 null-prototype 描述符，因此模型之后的修改无法把被拒绝的绑定变成 worker 崩溃。
-- **两个独立预算，因为对端不可信**：`computeMs` 统计 worker 实际测得的忙碌时间（轮询 `worker.performance.eventLoopUtilization()`）；热循环无法借助待完成的诱饵 dispatch 隐藏，程序等待慢工具时则不累计。`maxWallMs` 为忙碌时间无法观测的情况兜底（例如等待永远不会 resolve 的 promise）。二者最终都会调用 `worker.terminate()`，连同步热循环也能终止；堆溢出会表现为 worker 的 OOM 退出（`kind: 'worker-exit'`）。`maxWallMs` 在加载时会对照 `MAX_TIMER_DELAY_MS` 做范围校验：`setTimeout` 会把更长的延迟限制为 1 ms，仅有正数校验会放行一个在第一个 tick 就到期的上限。`computeMs` 不需要这道上界，因为它对照的是实测占用率，而不是喂给定时器。
-- **中间绑定值是完整 JSON**：绑定参数与 resolve 值会接受迭代式无损 JSON 验证。程序执行前，worker 会捕获自己 realm 中的普通容器原型身份，以及只用于外部 realm 的原生函数源码检查，因此构造器槽修改和用户编写的仿冒对象都无法改变容器分类。它还会捕获该 JSON 边界使用的每一个结构与计量 intrinsic，以无原型对象创建属性描述符，并绕过可变集合原型管理私有遍历状态；因此，模型对全局对象、原型方法或 `Object.prototype` 上形似描述符字段的修改，都无法改变验证、wire 传输或字节计量。值会展平为自身嵌套深度有界的前序 wire 值，供 structured clone 使用，并在另一侧迭代式重建。它们没有字节、JavaScript 调用栈或嵌套 structured-clone 深度上限，绝不会进入外层输出账本或模型上下文；上限仍来自提供方／执行器获取限制与进程／worker 内存。
-- **日志主动流入一个外层账本**：console／stdout／stderr 文本按产生顺序经端口传输，因此超时或被终止的程序仍会显示已经打印的内容。worker 会精确统计 JSON 字符串的字节数，并在发送完成值和异常诊断前，根据组合预算的剩余量预检；因此，抛出的百万字节 stack 会在 worker 边界变成固定的 `output-limit` 诊断。绕过补丁 stream 槽的原生写入会到达独立于完成端口的 pipe，因此宿主会针对这些字节和不可信伪造通信再次执行账本统计；在物化结果前，结算过程会持续进行有界 pipe 捕获，直到 worker 完成终止。`maxOutputBytes` 统计外层 `logs` 数组加完成值或失败消息载荷的 JSON 序列化；固定的 `CodeRunResult` 字段名、花括号、有界错误 kind 标签，以及后续呈现空白不计入这份可变载荷账本。未超过上限时会返回精确值；有损完成值属于 `invalid-output`，组合溢出属于 `output-limit`，不会用 inspected string 代替。失败会保留能容纳的已捕获前缀，之后按普通外层 `run_code` 落盘策略处理。
-- **空环境**：worker 使用 `env: {}` 和 `execArgv: []`，既不会获得环境变量中的凭据（比 spawn 命令的清理环境规则更严格），也不会继承 loader 标志。
-- **dispose（资源释放）时等待完全停稳**：清理会使进行中的运行以 `abort` 失败，并会等待每个 worker 退出后再完成。
+- **绑定 reject 类属于请求数据**：可选命名空间描述符会指定构造器全局变量，以及用于接收失败成员名称的自有属性。worker 会创建并注入该真实类，使 `instanceof` 生效，同时无需硬编码 `tools` 或 `ToolCallError`；全局变量无效或冲突的声明会在启动 worker 前失败。失败路径使用模块捕获的错误与属性定义 intrinsic，以及 null-prototype 描述符，因此模型之后的修改无法把被拒绝的绑定变成 worker 崩溃。
+- **两个独立预算，因为对端不可信**：`computeMs` 统计 worker 实际测得的忙碌时间（轮询 `worker.performance.eventLoopUtilization()`）；热循环无法借助待完成的诱饵 dispatch 隐藏，程序等待慢工具时则不累计。`maxWallMs` 为忙碌时间无法观测的情况兜底（例如等待永远不会 resolve 的 promise）。二者最终都会调用 `worker.terminate()`，连同步热循环也能终止；堆溢出会表现为 worker 的 OOM 退出（`kind: 'worker-exit'`）。`maxWallMs` 在加载时会对照 `MAX_TIMER_DELAY_MS` 做范围校验：`setTimeout` 会把更长的延迟夹到 1 ms，仅有正数校验会放行一个在第一个 tick 就到期的上限。`computeMs` 不需要这道上界，因为它对照的是实测占用率，而不是喂给定时器。
+- **中间绑定值是完整 JSON**：绑定参数与 resolve 值会接受迭代式无损 JSON 验证。程序执行前，worker 会捕获自己 realm 中的普通容器原型身份，以及只用于外部 realm 的原生函数源码检查，因此构造器槽修改和用户编写的仿冒对象都无法改变容器分类。它还会捕获该 JSON 边界使用的每一个结构与计量 intrinsic，以无原型对象创建属性描述符，并绕过可变集合原型管理私有遍历状态；因此，模型对全局对象、原型方法或 `Object.prototype` 上形似描述符字段的修改，都无法改变验证、wire 传输或字节计量。值会展平为有深度上限的前序 wire 值，供 structured clone 使用，并在另一侧迭代式重建。它们没有字节、JavaScript 调用栈或嵌套 structured-clone 深度上限，绝不会进入外层输出账本或模型上下文；上限仍来自提供方／执行器获取限制与进程／worker 内存。
+- **日志主动流入一个外层账本**：console／stdout／stderr 文本按发送顺序穿过端口，因此超时或被终止的程序仍会显示已经打印的内容。worker 会按 JSON 字符串精确计费，并在发送完成值和异常诊断前，根据组合预算的剩余量预检；因此，抛出的百万字节 stack 会在 worker 边界变成固定的 `output-limit` 诊断。绕过补丁 stream 槽的原生写入会到达独立于完成端口的 pipe，因此宿主会针对这些字节和不可信伪造通信再次执行账本统计；在物化结果前，结算过程会持续进行有界 pipe 捕获，直到 worker 完成终止。`maxOutputBytes` 统计外层 `logs` 数组加完成值或失败消息载荷的 JSON 序列化；固定的 `CodeRunResult` 字段名、花括号、有界错误 kind 标签，以及后续呈现空白不计入这份可变载荷账本。未超过上限时会返回精确值；有损完成值属于 `invalid-output`，组合溢出属于 `output-limit`，不会用 inspected string 代替。失败会保留能容纳的已捕获前缀，之后按普通外层 `run_code` 落盘策略处理。
+- **空环境**：worker 使用 `env: {}` 和 `execArgv: []`，既没有环境凭据（比 spawn 命令的清理环境规则更严格），也不会继承 loader 标志。
+- **释放资源时等待完全停稳**：清理会把进行中的运行标记为 `abort`，并在 resolve 前等待每个 worker 退出。
 
 ## 未构建与已构建的 worker 入口
 
-源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地和会话自有的 JSON 边界都会在消息端口周围展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的虚拟文件系统（VFS）Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。演练这个已发布入口路径的仓库级要求由[测试策略](../../../docs/testing.md)规定。
+源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地 JSON 快照器会与会话自有的规范边界执行一致性测试；消息端口两侧都会展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的 VFS Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。`tests/built-lib.e2e.ts` 固定了 [docs/testing.md](../../../docs/testing.md) 要求的真实加载路径。
 
-SDK 对外提供默认及具名导出的 `WorkerCodeRuntime` 类，以及 `Config`。运行所用的 `./worker` 子路径仅作为打包后的 spawn 入口存在；wire 协议与启动辅助模块是源代码私有的实现细节。
+SDK 接口是默认／具名 `WorkerCodeRuntime` 类与 `Config`。可操作的 `./worker` 子路径仅作为打包后的 spawn 入口存在；wire 协议与启动辅助模块是源代码私有的实现细节。
 
 ## 模型体验
 
@@ -42,13 +42,13 @@ SDK 对外提供默认及具名导出的 `WorkerCodeRuntime` 类，以及 `Confi
 
 #### KV Cache 影响
 
-不会直接失效；由上述消费方负责请求前缀变更。
+不会直接失效；由具名消费方负责请求前缀变更。
 
-## 已知限制与暂缓事项
+## 已知限制与暂缓工作
 
-- **程序派生的 OS 进程在程序终止后仍会存活**：`worker.terminate()` 只结束线程，比 bash-local 的进程组终止更弱；在容器后端出现前，孤儿进程清理属于部署职责。
-- **类型剥离依赖 Node 的实验性 `stripTypeScriptTypes` API**：如依赖的行为发生变化，amaro 或 sucrase 是已经点名的直接替代品。
+- **程序 spawn 的 OS 进程在该后端终止后仍会存活**：`worker.terminate()` 只结束线程；需要清理远程进程组的部署可以选择 E2B 后端，但该后端自身的限制仍然适用。
+- **类型剥离依赖 Node 的实验性 `stripTypeScriptTypes` API**：依赖的行为由单元测试固定；如其发生变化，amaro／sucrase 是已经点名的直接替代品。
 - **`computeMs` 到期最多可能超过一个轮询间隔**：系统每 25 ms 采样一次忙碌时间（内部常量，有意不做成配置）。
-- **程序获得一个含 5 个方法的 `console` shim**（`log`／`info`／`warn`／`error`／`debug`）：有意不提供 Node 的完整 console 接口。
+- **程序获得一个含 5 种方法的 `console` shim**（`log`／`info`／`warn`／`error`／`debug`）：有意不提供 Node 的完整 console 接口。
 - **中间绑定值没有字节上限**：程序可以用永远不会成为外层输出的值耗尽进程或 worker 内存。
 - **默认 64 MiB 是拒绝边界，不是可恢复存储**：外层落盘只能保存发生 `output-limit` 后返回的有界日志和诊断；在运行时上限之外被拒绝的字节永远不会到达落盘层。
diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts
index 43801899a2..2ece0b5c39 100644
--- a/packages/code-runtime/code-runtime-worker/src/index.ts
+++ b/packages/code-runtime/code-runtime-worker/src/index.ts
@@ -21,6 +21,10 @@ import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from
 import { decodeWorkerJson, encodeWorkerJson } from './worker-json.ts'
 import type { WorkerJsonWire } from './worker-json.ts'
 
+export { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
+export { decodeWorkerJson, encodeWorkerJson } from './worker-json.ts'
+export type { WorkerJsonWire } from './worker-json.ts'
+
 /** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */
 export interface Config {
   /**
@@ -165,14 +169,19 @@ function parseWorkerMessage(raw: unknown): WorkerToHost | undefined {
 }
 
 
-/** One run's combined outer-output ledger; binding values never enter it. */
-class OutputLedger {
+/** Shared outer-output accounting for one isolated run; binding values never enter it. */
+export class OutputLedger {
   private bytes = 2 // JSON serialization of the empty logs array: []
   private entries = 0
 
   constructor(private readonly maxBytes: number) {}
 
-  /** Admit one exact log entry, or report that the hard cap was crossed. */
+  /**
+   * Admit one exact log entry, or report that the hard cap was crossed.
+   * @param text - Candidate log entry.
+   * @param sink - Accepted log entries for the current run.
+   * @returns Whether the complete entry fits the remaining outer-output budget.
+   */
   admit(text: string, sink: string[]): boolean {
     const separatorBytes = this.entries > 0 ? 1 : 0
     const stringBytes = jsonStringBytesUpTo(text, this.maxBytes - this.bytes - separatorBytes)
@@ -183,19 +192,33 @@ class OutputLedger {
     return true
   }
 
-  /** Finalize a successful absent-or-JSON completion against the combined cap. */
+  /**
+   * Finalize a successful absent-or-JSON completion against the combined cap.
+   * @param logs - Already accepted log entries.
+   * @param value - Optional lossless-JSON completion value.
+   * @returns A success result or an output-limit failure.
+   */
   success(logs: string[], value?: CodeJsonValue): CodeRunResult {
     if (value !== undefined && jsonValueBytesUpTo(value, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
     return { logs, ...value !== undefined ? { value } : {} }
   }
 
-  /** Finalize a failure diagnostic, with output-limit taking precedence when combined bytes exceed the cap. */
+  /**
+   * Finalize a failure diagnostic, with output-limit taking precedence when combined bytes exceed the cap.
+   * @param logs - Already accepted log entries.
+   * @param error - Candidate failure diagnostic.
+   * @returns The diagnostic result or an output-limit failure.
+   */
   failure(logs: string[], error: CodeRunFailure): CodeRunResult {
     if (jsonStringBytesUpTo(error.message, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
     return { logs, error }
   }
 
-  /** Build the explicit output-limit failure while retaining a fitting prefix of the final log. */
+  /**
+   * Build the explicit output-limit failure while retaining a fitting prefix of the final log.
+   * @param logs - Candidate log entries in original order.
+   * @returns A capped output-limit result.
+   */
   limit(logs: string[]): CodeRunResult {
     const fullMessage = `outer output exceeded ${this.maxBytes} bytes`
     // The fixed diagnostic is ASCII, so every character is one byte plus the quotes.
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index a6bd209c7b..51c1466872 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/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/code-runtime/code-runtime/README.md
-README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
-README.zh.md: 15fbcecf77b2318acf3b09101802cd032ae426d2
+README.md: c7690412d0f1bc8556fc758da4e94c6ce5a08d8f
+README.zh.md: ecfa48a97c46113c52f13c7a6edfc5d6fbbc2285
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index bb1c20d00a..4018cdf508 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -34,5 +34,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
 - **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)).
-- **Only the worker-thread backend ships** — `'process'`/`'container'` are declared well-known `isolation` values with no implementation; a hard security boundary awaits a container backend.
+- **Isolation is backend-specific** — the worker backend is process-local, while the E2B backend reports `container` and keeps orchestration and bindings on the host; the descriptor remains informational rather than a security claim.
 - **Intermediate binding values have no byte cap** — implementations remain subject to structured-clone cost and process memory, while a provider or executor may already have imposed its own acquisition bound.
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index 15fbcecf77..ecfa48a97c 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -4,23 +4,21 @@
 
 这是**代码执行 seam**：抽象的 `CodeRuntime` 服务（`ctx.codeRuntime`）只定义代码运行时做什么，即针对宿主提供的一组异步绑定运行一段模型编写的程序，并报告 `{ value, logs, error? }`，而不规定如何实现。
 
-此包承担该能力三个组成部分中的接口职责（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。这两项职责均由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有与工具有关的内容都留在消费方。
+此包是该能力的接口层（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。两者都由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有工具形状的内容都留在消费方。
 
 ## 服务 API（`ctx.codeRuntime`）
 
 | 成员 | 语义 |
 |---|---|
-| `run(request)` | 针对请求的绑定执行一段程序。**所有程序失败结果都通过 resolve 结果中的 error 字段报告**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底终止（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 seam 本身时才 reject（例如 dispose（资源释放）后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
-| `language` | 只读描述符：`run` 期望的源语言。已知值为 `'typescript'` 与 `'python'`——`dsh-tools` 能呈现的那些；其中只有 `'typescript'` 有已发布的后端。仅供参考，不作门禁；生成语言专用呈现的消费方会根据该值选择分支，遇到无法呈现的语言时明确失败。 |
+| `run(request)` | 针对请求的绑定执行一段程序。**每一种程序结果都通过 error 字段完成 resolve**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底死亡（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 seam 本身时才 reject（例如资源释放后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
+| `language` | 只读描述符：`run` 期望的源语言（已知值为 `'typescript'`）。仅供参考，不作门禁；生成语言专用呈现的消费方会对该值执行分支，遇到无法呈现的语言时明确失败。 |
 | `isolation` | 只读描述符：执行基底（`'worker-thread'`、`'process'`、`'container'`）。供部署与诊断使用，**不构成安全声明**。 |
 
-每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为敌对对等方（任意绑定名称都会成为自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；dispose 会终止进行中的运行，并且在完成前等待其退出。
+每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为不可信对等方（任意绑定名称都是自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；资源释放会终止进行中的运行，并且在完成前等待其退出。
 
 ## 词汇
 
-`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
-
-binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的契约——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
+`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收 reject 成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
 
 ## 模型体验
 
@@ -28,11 +26,11 @@ binding-global 与 error-class 名称是**语言可移植**的：必须匹配标
 
 #### KV Cache 影响
 
-不会直接失效；由上述消费方负责请求前缀变更。
+不会直接失效；由具名消费方负责请求前缀变更。
 
-## 已知限制与暂缓事项
+## 已知限制与暂缓工作
 
-- **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供正在运行的程序所产生输出的流式日志或进度接口。
+- **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供活跃程序输出的流式日志或进度接口。
 - **持久 REPL 风格内核已记录为未来工作**：在持久内核后端带来自己的日志方案前，运行之间不保留状态的契约继续有效（参见 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)）。
-- **目前只提供 worker 线程后端**：`'process'`／`'container'` 是已经声明但没有实现的已知 `isolation` 值；强安全边界需要等待容器后端。
+- **隔离方式由后端决定**：worker 后端位于宿主进程内，而 E2B 后端报告 `container`，并把编排与绑定留在宿主；该描述符仍只提供信息，不构成安全声明。
 - **中间绑定值没有字节上限**：实现仍受 structured-clone 成本与进程内存约束，而提供方或执行器可能已经应用自己的获取上限。
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 1bc9761930..444145fbb8 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: 4b28ec7c0452189a579a6d7e0cd22a0b8561784d
-README.zh.md: ab254eecad82c05cd6a6021e7f8bc4eda6cf3076
+README.md: 9e7f1a98ada9f56f3d1e3f74d2a906f8a1c7bc15
+README.zh.md: 53fdf30eaf405ab5313274a7fadde0b044b7fba1
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index 4b28ec7c04..9e7f1a98ad 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -2,12 +2,15 @@
 
 English | [中文](README.zh.md)
 
-An experimental provider-composition POC that places the filesystem and managed subprocess world in one E2B Linux sandbox. The shared owner is separate from the capability adapters so every remote provider awaits the same sandbox identity and lifecycle.
+An experimental provider-composition POC that places the mutable coding world in one E2B Linux sandbox. The shared owner is separate from capability adapters so every remote provider awaits the same sandbox identity and lifecycle.
 
 | Package | ctx key | Role |
 |---|---|---|
 | [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create or reconnect one sandbox, create its working/runtime directories, expose the shared SDK handle, and apply the configured kill/pause/leave disposition |
 | [`fs-e2b`](../fs/fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
 | [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement managed process groups, stdio projection, and remote spill files over E2B Commands |
+| [`pty-e2b`](../pty/pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | `ctx.pty` backend | Run persistent interactive shells through E2B's byte PTY API |
+| [`lsp-e2b`](../lsp/lsp-e2b/README.md) (`@deepseek-ai/dsh-lsp-e2b`) | `ctx.lsp` provider | Run configured language servers and read query sources inside E2B |
+| [`code-runtime-e2b`](../code-runtime/code-runtime-e2b/README.md) (`@deepseek-ai/dsh-code-runtime-e2b`) | `ctx.codeRuntime` | Run model-written programs remotely while bridging bindings to the host |
 
-The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it already delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world as `ctx.fs`. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, or E2B SDK buffers. The [decision record](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary and rejected expansion.
+The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, protocol state, or E2B SDK buffers. The [base decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) and [runtime-extension decision](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) own the POC boundary.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index ab254eecad..53fdf30eaf 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -2,12 +2,15 @@
 
 [English](README.md) | 中文
 
-这是一个实验性提供方组合 POC，把文件系统和受管子进程环境放进同一个 E2B Linux 沙箱。共享所有者与功能适配器彼此分离，使每个远程提供方都等待同一个沙箱身份和生命周期。
+这是一个实验性提供方组合 POC，把可变的编码环境放进同一个 E2B Linux 沙箱。共享所有者与功能适配器分离，使每个远程提供方都等待同一个沙箱身份和生命周期。
 
 | 包（package） | ctx 键 | 职责 |
 |---|---|---|
 | [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建或重新连接一个沙箱，创建其工作目录与运行时目录，公开共享 SDK 句柄，并应用配置的 kill/pause/leave 处置方式 |
 | [`fs-e2b`](../fs/fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
 | [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 实现受管进程组、stdio 投影与远程 spill 文件 |
+| [`pty-e2b`](../pty/pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | `ctx.pty` 后端 | 通过 E2B 的字节 PTY API 运行持久交互式 shell |
+| [`lsp-e2b`](../lsp/lsp-e2b/README.md)（`@deepseek-ai/dsh-lsp-e2b`） | `ctx.lsp` 提供方 | 在 E2B 内运行已配置的语言服务器并读取查询源代码 |
+| [`code-runtime-e2b`](../code-runtime/code-runtime-e2b/README.md)（`@deepseek-ai/dsh-code-runtime-e2b`） | `ctx.codeRuntime` | 远程运行模型编写的程序，同时把绑定桥接到宿主 |
 
-现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它已经把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 与 `ctx.fs` 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）或 E2B SDK 缓冲。[决策记录](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)负责说明 POC 边界及未采纳的扩展方案。
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、协议状态或 E2B SDK 缓冲。[基础决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)与[运行时扩展决策](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)共同界定 POC 边界。
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 9255c21577..164bb47784 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: bf62cb7d4811ca92f263bd3d337fff9fe41ce223
-README.zh.md: 8c7603aa501a2481aba6dab1f22750056e43ad26
+README.md: 5f89a4bcffdfd11fef8929d2a2ceecb41af319e2
+README.zh.md: b4956033bae131bb8aa236276323ecba30f00115
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index bf62cb7d48..5f89a4bcff 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shared lifecycle owner for one E2B sandbox. Filesystem and subprocess adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`.
+Shared lifecycle owner for one E2B sandbox. Capability adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`; the [family map](../README.md) lists the opt-in adapters.
 
 ## Configuration
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 8c7603aa50..b4956033ba 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个 E2B 沙箱的共享生命周期所有者。文件系统与进程管理适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`。
+一个 E2B 沙箱的共享生命周期所有者。功能适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`；可选适配器见[包族索引](../README.md)。
 
 ## 配置
 
diff --git a/packages/e2b/e2b/src/frame.ts b/packages/e2b/e2b/src/frame.ts
new file mode 100644
index 0000000000..39800b4428
--- /dev/null
+++ b/packages/e2b/e2b/src/frame.ts
@@ -0,0 +1,75 @@
+/** ASCII/base64 JSON framing for byte-faithful protocols over E2B text callbacks. */
+
+import { Buffer } from 'node:buffer'
+
+const BASE64_LINE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+/**
+ * Encode one JSON-compatible value as a newline-delimited ASCII frame.
+ * @param value - Value accepted by `JSON.stringify`.
+ * @returns Base64-encoded UTF-8 JSON followed by one newline.
+ */
+export function encodeE2BFrame(value: unknown): string {
+  const json: unknown = JSON.stringify(value)
+  if (typeof json !== 'string') throw new Error('E2B frame value is not JSON-serializable')
+  return `${Buffer.from(json).toString('base64')}\n`
+}
+
+/** Incremental decoder for newline-delimited base64 JSON frames. */
+export class E2BFrameDecoder {
+  private pending = ''
+  private readonly maxEncodedChars: number
+
+  /** @param maxFrameBytes - Maximum decoded UTF-8 JSON bytes in one frame. */
+  constructor(private readonly maxFrameBytes: number) {
+    if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
+      throw new Error('E2B frame maxFrameBytes must be a positive safe integer')
+    }
+    this.maxEncodedChars = Math.ceil(maxFrameBytes / 3) * 4
+  }
+
+  /**
+   * Consume one E2B callback chunk.
+   * @param chunk - ASCII text received from the remote helper.
+   * @returns Every complete decoded JSON value, in order.
+   */
+  push(chunk: string): unknown[] {
+    if (/[^\x0a\x20-\x7e]/.test(chunk)) throw new Error('E2B frame stream contained non-ASCII data')
+    this.pending += chunk
+    const values: unknown[] = []
+    for (;;) {
+      const newline = this.pending.indexOf('\n')
+      if (newline < 0) {
+        if (this.pending.length > this.maxEncodedChars) throw new Error('E2B frame exceeded its byte limit')
+        return values
+      }
+      const line = this.pending.slice(0, newline)
+      this.pending = this.pending.slice(newline + 1)
+      values.push(this.decode(line))
+    }
+  }
+
+  /** Reject a truncated final frame. */
+  finish(): void {
+    if (this.pending.length !== 0) throw new Error('E2B frame stream ended mid-frame')
+  }
+
+  private decode(line: string): unknown {
+    if (line.length === 0 || line.length > this.maxEncodedChars || !BASE64_LINE.test(line)) {
+      throw new Error('E2B frame contained invalid base64 or exceeded its byte limit')
+    }
+    const bytes = Buffer.from(line, 'base64')
+    if (bytes.length > this.maxFrameBytes) throw new Error('E2B frame exceeded its byte limit')
+    let json: string
+    try {
+      json = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+    } catch (error: unknown) {
+      throw new Error('E2B frame contained invalid UTF-8', { cause: error })
+    }
+    try {
+      return JSON.parse(json) as unknown
+    } catch (error: unknown) {
+      throw new Error('E2B frame contained invalid JSON', { cause: error })
+    }
+  }
+}
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 29cbf1dc53..4c4597f6ef 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -10,6 +10,8 @@ import z from 'schemastery'
 import { Sandbox } from 'e2b'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
+export { E2BFrameDecoder, encodeE2BFrame } from './frame.ts'
+
 export {
   CommandExitError,
   FileNotFoundError,
@@ -19,7 +21,7 @@ export {
   SandboxNotFoundError,
   TimeoutError,
 } from 'e2b'
-export type { CommandHandle, CommandResult, EntryInfo } from 'e2b'
+export type { CommandHandle, CommandResult, EntryInfo, ProcessInfo, PtyOutput } from 'e2b'
 
 /** Opaque E2B sandbox identity used for reconnecting a later harness process. */
 export type E2BSandboxId = Branded<'E2BSandboxId'>
@@ -42,6 +44,26 @@ export function quoteE2BShellArg(value: string): string {
   return `'${value.replaceAll('\'', "'\"'\"'")}'`
 }
 
+/**
+ * Resolve one executable inside an E2B sandbox and require an absolute result.
+ * @param sandbox - Sandbox whose PATH and filesystem own the executable.
+ * @param command - Absolute path or bare executable name.
+ * @returns Verified absolute remote executable path.
+ */
+export async function resolveE2BExecutable(sandbox: Sandbox, command: string): Promise<string> {
+  if (command.length === 0) throw new Error('E2B executable name must be non-empty')
+  if (posix.isAbsolute(command)) {
+    await sandbox.commands.run(`test -f ${quoteE2BShellArg(command)} -a -x ${quoteE2BShellArg(command)}`)
+    return command
+  }
+  const result = await sandbox.commands.run(`command -v -- ${quoteE2BShellArg(command)}`)
+  const executable = result.stdout.trim()
+  if (!posix.isAbsolute(executable) || executable.includes('\n')) {
+    throw new Error(`E2B executable ${JSON.stringify(command)} did not resolve to one absolute path`)
+  }
+  return executable
+}
+
 /** Action taken on the owned sandbox when the Cordis service is disposed. */
 export type E2BDisposeMode = 'kill' | 'pause' | 'leave'
 
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 8c01fae7b4..d056d4b851 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -11,7 +11,7 @@ const configPath = join(fixtureRoot, 'cordis.yml')
 const tsconfigPath = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 
 describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
-  it('shares remote state across FS and Bash without creating host workspace files', async () => {
+  it('runs FS, Bash, PTY, LSP, and Code Runtime in one sandbox and deletes it', async () => {
     const { stdout, stderr } = await runLoaderSmoke({
       label: 'E2B composition',
       tempDirPrefix: 'dsh-e2b-composition-',
@@ -19,10 +19,14 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       libBinScript: binScript,
       configPath,
       tsconfigPath,
-      processTimeoutMs: 90_000,
+      env: {
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      processTimeoutMs: 120_000,
       inspect: async (cwd) => {
-        await expect(access(join(cwd, 'from-fs.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
-        await expect(access(join(cwd, 'from-bash.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
+        for (const name of ['from-fs.txt', 'from-bash.txt', 'multibyte.ts', 'fixture-lsp.mjs']) {
+          await expect(access(join(cwd, name))).rejects.toMatchObject({ code: 'ENOENT' })
+        }
       },
     })
 
@@ -31,9 +35,37 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     expect(output).toMatchObject({
       bashRead: 'written-by-fs\n',
       fsRead: 'written-by-bash\n',
+      hover: {
+        kind: 'hover',
+        hover: { contents: '**remote hover** 你好 café' },
+      },
+      definition: {
+        kind: 'locations',
+        locations: [{ range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } } }],
+      },
+      terminal: {
+        echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
+        signal: { delivered: true },
+        interrupted: { sessionStatus: { kind: 'running' } },
+      },
+      hostileOutput: { error: { kind: 'output-limit' } },
+      timedOut: { error: { kind: 'timeout' } },
+      aborted: { error: { kind: 'abort', message: 'live abort' } },
+      lingeringCodeRunners: 0,
+    })
+    expect((output.terminal as { motd: string }).motd.length).toBeGreaterThan(0)
+    expect((output.terminal as { echo: { viewport: string } }).echo.viewport).toContain('PTY-你好')
+    expect((output.terminal as { scrollback: string }).scrollback).toContain('PTY-你好')
+    expect((output.terminal as { signal: { targetPgid: number } }).signal.targetPgid).toBeGreaterThan(0)
+    expect(['stdin_read', 'inferred_idle']).toContain(
+      (output.terminal as { interrupted: { waitReason: string } }).interrupted.waitReason,
+    )
+    expect(output.code).toEqual({
+      value: { doubled: 42, typed: true },
+      logs: ['remote-log 你好 42', 'post-mutation'],
     })
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
     await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
-  }, 105_000)
+  }, 135_000)
 })
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index c842731f5c..541e69df9c 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -2,8 +2,11 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
+  E2BFrameDecoder,
   E2BSandboxId,
+  encodeE2BFrame,
   quoteE2BShellArg,
+  resolveE2BExecutable,
 } from '@deepseek-ai/dsh-e2b'
 import * as E2BInvariant from '../src/invariant.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -209,6 +212,49 @@ describe('E2B helpers and invariant companion', () => {
     expect(quoteE2BShellArg("a'b $HOME")).toBe("'a'\"'\"'b $HOME'")
   })
 
+  it('resolves absolute and PATH executables inside the sandbox', async () => {
+    const run = vi.fn()
+      .mockResolvedValueOnce({ exitCode: 0, stdout: '', stderr: '' })
+      .mockResolvedValueOnce({ exitCode: 0, stdout: '/usr/bin/node\n', stderr: '' })
+    const sandbox = { commands: { run } } as unknown as SandboxType
+    await expect(resolveE2BExecutable(sandbox, '/bin/bash')).resolves.toBe('/bin/bash')
+    await expect(resolveE2BExecutable(sandbox, 'node')).resolves.toBe('/usr/bin/node')
+    expect(run).toHaveBeenNthCalledWith(1, "test -f '/bin/bash' -a -x '/bin/bash'")
+    expect(run).toHaveBeenNthCalledWith(2, "command -v -- 'node'")
+  })
+
+  it('rejects empty or non-absolute executable resolutions', async () => {
+    const sandbox = {
+      commands: { run: vi.fn().mockResolvedValue({ exitCode: 0, stdout: 'relative\npath\n', stderr: '' }) },
+    } as unknown as SandboxType
+    await expect(resolveE2BExecutable(sandbox, '')).rejects.toThrow('non-empty')
+    await expect(resolveE2BExecutable(sandbox, 'tool')).rejects.toThrow('did not resolve')
+  })
+
+  it('round-trips split and adjacent ASCII/base64 JSON frames', () => {
+    const decoder = new E2BFrameDecoder(128)
+    const encoded = encodeE2BFrame({ text: '你好' }) + encodeE2BFrame([1, true])
+    expect(decoder.push(encoded.slice(0, 5))).toEqual([])
+    expect(decoder.push(encoded.slice(5))).toEqual([{ text: '你好' }, [1, true]])
+    expect(() => { decoder.finish() }).not.toThrow()
+    expect(() => encodeE2BFrame(undefined)).toThrow('not JSON-serializable')
+  })
+
+  it('rejects malformed, oversized, and truncated frame streams', () => {
+    expect(() => new E2BFrameDecoder(0)).toThrow('positive safe integer')
+    expect(() => new E2BFrameDecoder(1.5)).toThrow('positive safe integer')
+    expect(() => new E2BFrameDecoder(4).push('é')).toThrow('non-ASCII')
+    expect(() => new E2BFrameDecoder(3).push('AAAAA')).toThrow('byte limit')
+    expect(() => new E2BFrameDecoder(8).push('\n')).toThrow('invalid base64')
+    expect(() => new E2BFrameDecoder(8).push('abc!\n')).toThrow('invalid base64')
+    expect(() => new E2BFrameDecoder(2).push(`${Buffer.from('abc').toString('base64')}\n`)).toThrow('byte limit')
+    expect(() => new E2BFrameDecoder(8).push('/w==\n')).toThrow('invalid UTF-8')
+    expect(() => new E2BFrameDecoder(16).push(`${Buffer.from('not-json').toString('base64')}\n`)).toThrow('invalid JSON')
+    const truncated = new E2BFrameDecoder(8)
+    truncated.push('YQ==')
+    expect(() => { truncated.finish() }).toThrow('mid-frame')
+  })
+
   it('registers the package-owned empty invariant installer', async () => {
     const ctx = new Context()
     await ctx.plugin(InvariantService, { enabled: true })
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index 9919cdaba5..c28c0282c2 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: 7fbdf071735673fb0158f6fa66148be1c644a433
-README.zh.md: e059dbd80b7e38c0e447e54178162316dfd127c7
+README.md: 74ed729d97013de3d7f502f728e3abe62348846f
+README.zh.md: 5a08d54ca6c54d8355454fc3021a0da48772000b
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index 7fbdf07173..74ed729d97 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -7,9 +7,10 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 | Package | Role | ctx key |
 |---|---|---|
 | `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
-| `lsp-local/` | Generic multi-server stdio backend over `ctx.fs` and `ctx.subprocess` (JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
+| [`lsp-local/`](lsp-local/README.md) | Generic multi-server local backend (spawn, JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
+| [`lsp-e2b/`](lsp-e2b/README.md) | Remote E2B backend (remote source reads and servers, byte-framed stdio bridge) | (registers providers on `ctx.lsp`) |
 | `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
 The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
 
-See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
+See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the protocol design and the [E2B extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) for the remote process/filesystem boundary.
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index e059dbd80b..5a08d54ca6 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -7,9 +7,10 @@
 | 包 | 职责 | ctx key |
 |---|---|---|
 | `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
-| `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
+| [`lsp-local/`](lsp-local/README.md) | 通用多服务器本地后端（spawn、JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
+| [`lsp-e2b/`](lsp-e2b/README.md) | 远程 E2B 后端（在远程读取源文件并运行服务器、采用字节分帧的 stdio 桥） | （在 `ctx.lsp` 上注册提供方） |
 | `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
 接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
-设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
+协议设计见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，远程进程／文件系统边界见 [E2B 扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)。
diff --git a/packages/lsp/lsp-e2b/README.i18n.yaml b/packages/lsp/lsp-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..fa159820a9
--- /dev/null
+++ b/packages/lsp/lsp-e2b/README.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 packages/lsp/lsp-e2b/README.md
+README.md: 968487b7c5f63b2165cf66797a4182642507a8e9
+README.zh.md: 2b937f01156c3194f64ed9fb54478fec5c77305b
diff --git a/packages/lsp/lsp-e2b/README.md b/packages/lsp/lsp-e2b/README.md
new file mode 100644
index 0000000000..968487b7c5
--- /dev/null
+++ b/packages/lsp/lsp-e2b/README.md
@@ -0,0 +1,47 @@
+# @deepseek-ai/dsh-lsp-e2b
+
+English | [中文](README.zh.md)
+
+Generic E2B language-server backend for [`ctx.lsp`](../lsp/README.md). It runs configured stdio servers and reads their source documents inside the shared `ctx.e2b` sandbox; the provider registry, normalized query results, queues, and protocol connection state remain on the host.
+
+## Plugin and configuration
+
+The `lsp-e2b` plugin injects `e2b`, `lsp`, and the concrete `dsh-subprocess-e2b` service. `servers` is a non-empty provider-id table:
+
+| Server key | Default | Meaning |
+|---|---|---|
+| `command` | required | Remote executable, absolute or resolved on the sandbox PATH at load. |
+| `args` | `[]` | Remote server arguments. |
+| `env` | `{}` | Explicit environment entries passed through the subprocess adapter. |
+| `extensionToLanguage` | required | Lowercase leading-dot extension to LSP language id. |
+| `initializationOptions` / `configuration` | `null` / `null` | Static initialize options and `workspace/configuration` answer. |
+| `maxMessageBytes` | `16000000` | Largest LSP message accepted from the server. |
+| `maxStderrBytes` | `1000000` | Retained raw server stderr tail. |
+| `maxDocumentBytes` | `4000000` | Largest remote source opened for one query. |
+| `shutdownTimeoutMs` | `5000` | Graceful protocol-shutdown budget. |
+| `killGraceMs` | `2000` | Request-cancel and TERM-to-KILL grace. |
+
+Provider ids and commands are non-empty; numeric bounds are positive safe integers, and timer values cannot exceed Node's maximum timer delay. Setup uploads one owner-private proxy under `ctx.e2b.runtimeRoot`, resolves Node and every configured server executable remotely, then registers all providers atomically.
+
+## Remote protocol and filesystem
+
+E2B command callbacks are text, while LSP is byte-framed. The installed proxy therefore base64-frames raw server stdout, stderr, and stdin as newline-delimited ASCII JSON; the host validates and decodes every frame before handing bytes to the shared `LspInstance` protocol engine. `initialize.processId` is `null` because host and server do not share a process namespace.
+
+One language-server process is pooled per provider and canonical remote workspace. Queries serialize per workspace but different workspaces run concurrently. Each query canonicalizes the remote workspace and source with `realpath`, rejects paths outside that workspace, requires a regular file, enforces the size bound before and after reading, decodes strict UTF-8, and uses the ordinary transient `didOpen` / request / `didClose` lifecycle. A transport failure disposes the instance and retries the read-only query once on a fresh remote process.
+
+The subprocess adapter owns process groups and escalation, so cancellation and disposal await remote server quiescence. The host owns LSP request ids, pending requests, provider queues, and normalized results.
+
+## Model Experience
+
+Indirectly, through `@deepseek-ai/dsh-tool-lsp`, which exposes normalized semantic navigation and hover results without changing its model-facing schema.
+
+#### KV Cache effect
+
+No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Configured servers only** — this package does not install language servers, select presets, or synchronize a host workspace into E2B.
+- **Host protocol state is not reconnectable** — retaining a sandbox does not restore provider queues, JSON-RPC requests, subprocess handles, or document lifecycle state.
+- **SDK output retention remains** — ASCII framing preserves protocol bytes, but E2B and the subprocess adapter still retain callback output in host memory.
+- **Sandbox policy is template-owned** — this provider adds no volume, snapshot, credential, or network-policy layer.
diff --git a/packages/lsp/lsp-e2b/README.zh.md b/packages/lsp/lsp-e2b/README.zh.md
new file mode 100644
index 0000000000..2b937f0115
--- /dev/null
+++ b/packages/lsp/lsp-e2b/README.zh.md
@@ -0,0 +1,47 @@
+# @deepseek-ai/dsh-lsp-e2b
+
+[English](README.md) | 中文
+
+用于 [`ctx.lsp`](../lsp/README.md) 的通用 E2B 语言服务器后端。它在共享的 `ctx.e2b` 沙箱内运行已配置的 stdio 服务器并读取其源文档；提供方注册表、规范化查询结果、队列和协议连接状态仍保留在宿主侧。
+
+## 插件与配置
+
+`lsp-e2b` 插件注入 `e2b`、`lsp` 和具体的 `dsh-subprocess-e2b` 服务。`servers` 是一张非空的提供方 id 表：
+
+| 服务器键 | 默认值 | 含义 |
+|---|---|---|
+| `command` | 必填 | 远程可执行文件：绝对路径，或在加载时通过沙箱 PATH 解析。 |
+| `args` | `[]` | 远程服务器参数。 |
+| `env` | `{}` | 经由进程管理适配器传入的显式环境条目。 |
+| `extensionToLanguage` | 必填 | 小写、以点开头的扩展名到 LSP language id 的映射。 |
+| `initializationOptions` / `configuration` | `null` / `null` | 静态初始化选项和 `workspace/configuration` 应答。 |
+| `maxMessageBytes` | `16000000` | 从服务器接受的 LSP 消息大小上限。 |
+| `maxStderrBytes` | `1000000` | 保留的服务器原始 stderr 尾部上限。 |
+| `maxDocumentBytes` | `4000000` | 单次查询可打开的最大远程源文件。 |
+| `shutdownTimeoutMs` | `5000` | 协议优雅关闭预算。 |
+| `killGraceMs` | `2000` | 请求取消与 TERM 到 KILL 升级的宽限期。 |
+
+提供方 id 与命令必须非空；数值上限必须是正的安全整数，定时器取值不得超过 Node 的最大定时器延迟。设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个仅供所有者使用的私有代理，在远程解析 Node 和每个已配置服务器的可执行文件，再以原子方式注册所有提供方。
+
+## 远程协议与文件系统
+
+E2B 命令回调交付的是文本，而 LSP 按字节分帧。因此，已安装的代理会把服务器 stdout、stderr 和 stdin 的原始字节进行 base64 编码，封装为以换行分隔的 ASCII JSON 帧；宿主会验证并解码每一帧，再把字节交给共享的 `LspInstance` 协议引擎。`initialize.processId` 为 `null`，因为宿主与服务器不共享进程命名空间。
+
+每个提供方与规范化远程工作区的组合共享一个池化语言服务器进程。同一工作区的查询串行执行，不同工作区的查询并发运行。每项查询都会使用 `realpath` 规范化远程工作区与源文件，拒绝工作区外的路径，要求源文件为普通文件，在读取前后都检查大小上限，使用严格的 UTF-8 解码，并采用常规的临时 `didOpen`／请求／`didClose` 生命周期。传输失败会 dispose（资源释放）该实例，并在全新的远程进程上重试一次只读查询。
+
+进程管理适配器负责进程组和终止升级，因此取消与资源释放都会等待远程服务器完全停稳。宿主负责 LSP 请求 id、待完成请求、提供方队列和规范化结果。
+
+## 模型体验
+
+通过 `@deepseek-ai/dsh-tool-lsp` 间接影响模型；该包会公开规范化的语义导航与悬停结果，而不改变其面向模型的 schema。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由 `dsh-tool-lsp` 负责。
+
+## 已知限制与暂缓工作
+
+- **仅支持已配置的服务器**：本包不会安装语言服务器、选择 preset，或把宿主工作区同步到 E2B。
+- **宿主协议状态不可重连**：保留沙箱并不会恢复提供方队列、JSON-RPC 请求、进程管理句柄或文档生命周期状态。
+- **SDK 仍会保留输出**：ASCII 分帧能保留协议字节，但 E2B 和进程管理适配器仍会在宿主内存中保留回调输出。
+- **沙箱策略归模板负责**：本提供方不会额外增加卷、快照、凭据或网络策略层。
diff --git a/packages/lsp/lsp-e2b/package.json b/packages/lsp/lsp-e2b/package.json
new file mode 100644
index 0000000000..0671341f3c
--- /dev/null
+++ b/packages/lsp/lsp-e2b/package.json
@@ -0,0 +1,52 @@
+{
+  "name": "@deepseek-ai/dsh-lsp-e2b",
+  "description": "E2B language-server provider for DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-lsp": "^0.0.1",
+    "@deepseek-ai/dsh-lsp-local": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-lsp": "workspace:^",
+    "@deepseek-ai/dsh-lsp-local": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-e2b": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/lsp/lsp-e2b/src/index.ts b/packages/lsp/lsp-e2b/src/index.ts
new file mode 100644
index 0000000000..eb9596db5f
--- /dev/null
+++ b/packages/lsp/lsp-e2b/src/index.ts
@@ -0,0 +1,358 @@
+/** E2B filesystem and process backend for the harness LSP capability seam. */
+
+import { Buffer } from 'node:buffer'
+import { posix } from 'node:path'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import {
+  FileType,
+  quoteE2BShellArg,
+  resolveE2BExecutable,
+} from '@deepseek-ai/dsh-e2b'
+import type { Sandbox } from '@deepseek-ai/dsh-e2b'
+import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
+import type { LspProvider, LspProviderQuery, LspQueryResult } from '@deepseek-ai/dsh-lsp'
+import { LspInstance } from '@deepseek-ai/dsh-lsp-local'
+import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import { LSP_PROXY_SOURCE } from './proxy-source.ts'
+import { E2BLspTransport } from './transport.ts'
+
+export { E2BLspTransport } from './transport.ts'
+
+/** Cordis plugin name. */
+export const name = 'lsp-e2b'
+/** Services required by the remote provider. */
+export const inject = ['e2b', 'lsp', 'subprocess']
+
+const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
+const DEFAULT_MAX_STDERR_BYTES = 1_000_000
+const DEFAULT_MAX_DOCUMENT_BYTES = 4_000_000
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000
+const DEFAULT_KILL_GRACE_MS = 2_000
+
+/* jscpd:ignore-start -- Loader requires each backend to expose its own statically walkable server schema. */
+/** One configured language server inside the shared E2B sandbox. */
+export interface LspE2BServerConfig {
+  /** Remote executable, absolute or resolved on the sandbox PATH. */
+  command: string
+  /** Lowercase leading-dot extension to LSP language id. */
+  extensionToLanguage: Record<string, string>
+  /** Remote executable arguments. */
+  args?: string[]
+  /** Explicit remote environment overrides. */
+  env?: Record<string, string>
+  /** Static `initialize` options. */
+  initializationOptions?: unknown
+  /** Static answer to every `workspace/configuration` item. */
+  configuration?: unknown
+  /** Largest LSP message accepted from the server. */
+  maxMessageBytes?: number
+  /** Largest remote stderr tail retained for diagnostics. */
+  maxStderrBytes?: number
+  /** Largest remote source opened for one query. */
+  maxDocumentBytes?: number
+  /** Graceful LSP shutdown budget. */
+  shutdownTimeoutMs?: number
+  /** Request-cancel and TERM-to-KILL grace. */
+  killGraceMs?: number
+}
+
+/** Plugin configuration. */
+export interface Config {
+  /** Non-empty provider-id to remote-server table. */
+  servers: Record<string, LspE2BServerConfig>
+}
+
+type ResolvedServerConfig = Required<LspE2BServerConfig>
+
+const ServerConfig: z<LspE2BServerConfig> = z.object({
+  command: z.string().required(),
+  args: z.array(String).default([]),
+  env: z.dict(String).default({}),
+  extensionToLanguage: z.dict(String).required(),
+  initializationOptions: z.any().default(null),
+  configuration: z.any().default(null),
+  maxMessageBytes: z.number().default(DEFAULT_MAX_MESSAGE_BYTES),
+  maxStderrBytes: z.number().default(DEFAULT_MAX_STDERR_BYTES),
+  maxDocumentBytes: z.number().default(DEFAULT_MAX_DOCUMENT_BYTES),
+  shutdownTimeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_SHUTDOWN_TIMEOUT_MS),
+  killGraceMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_KILL_GRACE_MS),
+})
+
+/** Schemastery plugin configuration. */
+export const Config: z<Config> = z.object({
+  servers: z.dict(ServerConfig).required(),
+})
+/* jscpd:ignore-end */
+
+interface RemoteSource {
+  canonicalPath: string
+  text: string
+}
+
+function abortReason(signal: AbortSignal): unknown {
+  try {
+    signal.throwIfAborted()
+  } catch (error: unknown) {
+    return error
+  }
+  return new DOMException('The operation was aborted', 'AbortError')
+}
+
+function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (signal === undefined) return promise
+  // AbortSignal permits opaque reasons, and callers observe the exact reason.
+  // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+  if (signal.aborted) return Promise.reject(abortReason(signal))
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => {
+      cleanup()
+      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- Preserve the signal's exact opaque reason.
+      reject(abortReason(signal))
+    }
+    const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    void promise.then(
+      (value) => { cleanup(); resolve(value) },
+      (error: unknown) => { cleanup(); reject(error instanceof Error ? error : new Error(String(error))) },
+    )
+  })
+}
+
+function validateServerConfig(providerId: string, config: ResolvedServerConfig): void {
+  if (config.command.length === 0) throw new Error(`lsp-e2b: servers.${providerId}.command must be non-empty`)
+  for (const name of ['maxMessageBytes', 'maxStderrBytes', 'maxDocumentBytes', 'shutdownTimeoutMs', 'killGraceMs'] as const) {
+    const value = config[name]
+    if (!Number.isSafeInteger(value) || value <= 0 || (name.endsWith('Ms') && value > MAX_TIMER_DELAY_MS)) {
+      throw new Error(`lsp-e2b: servers.${providerId}.${name} must be a positive safe integer${name.endsWith('Ms') ? ` no greater than ${MAX_TIMER_DELAY_MS}` : ''}`)
+    }
+  }
+}
+
+async function canonicalRemotePath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
+  signal?.throwIfAborted()
+  const result = await sandbox.commands.run(`realpath -e -- ${quoteE2BShellArg(path)}`, signal === undefined ? {} : { signal })
+  signal?.throwIfAborted()
+  const canonical = result.stdout.trim()
+  if (!posix.isAbsolute(canonical) || canonical.includes('\n')) throw new Error(`remote path ${JSON.stringify(path)} did not resolve canonically`)
+  return canonical
+}
+
+/**
+ * Canonicalize and validate one workspace inside E2B.
+ * @param sandbox - Shared sandbox that owns the workspace.
+ * @param workspaceRoot - Remote workspace path supplied by the query.
+ * @param signal - Optional query cancellation signal.
+ * @returns The canonical remote directory path.
+ */
+export async function canonicalizeE2BWorkspace(
+  sandbox: Sandbox,
+  workspaceRoot: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const canonical = await canonicalRemotePath(sandbox, workspaceRoot, signal)
+  const info = await sandbox.files.getInfo(canonical, signal === undefined ? {} : { signal })
+  signal?.throwIfAborted()
+  if (info.type !== FileType.DIR) throw new Error(`workspace root ${JSON.stringify(workspaceRoot)} is not a directory`)
+  return canonical
+}
+
+/**
+ * Resolve, contain, and read one UTF-8 query source inside E2B.
+ * @param sandbox - Shared sandbox that owns the source.
+ * @param filePath - Absolute path or path relative to the canonical workspace.
+ * @param workspace - Canonical remote workspace directory.
+ * @param maxDocumentBytes - Maximum source size before and after reading.
+ * @param signal - Optional query cancellation signal.
+ * @returns The canonical source path and decoded text.
+ */
+export async function readE2BSource(
+  sandbox: Sandbox,
+  filePath: string,
+  workspace: string,
+  maxDocumentBytes: number,
+  signal?: AbortSignal,
+): Promise<RemoteSource> {
+  const requested = posix.isAbsolute(filePath) ? filePath : posix.resolve(workspace, filePath)
+  const canonicalPath = await canonicalRemotePath(sandbox, requested, signal)
+  const relative = posix.relative(workspace, canonicalPath)
+  if (relative === '..' || relative.startsWith('../') || posix.isAbsolute(relative)) {
+    throw new Error(`source ${JSON.stringify(filePath)} resolves outside the workspace`)
+  }
+  const info = await sandbox.files.getInfo(canonicalPath, signal === undefined ? {} : { signal })
+  if (info.type !== FileType.FILE) throw new Error(`source ${JSON.stringify(filePath)} is not a regular file`)
+  if (info.size > maxDocumentBytes) {
+    throw new Error(`source ${JSON.stringify(filePath)} is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`)
+  }
+  const bytes = await sandbox.files.read(canonicalPath, { format: 'bytes', ...signal === undefined ? {} : { signal } })
+  signal?.throwIfAborted()
+  if (bytes.length > maxDocumentBytes) {
+    throw new Error(`source ${JSON.stringify(filePath)} grew past the ${maxDocumentBytes}-byte limit while reading`)
+  }
+  let text: string
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  } catch (error: unknown) {
+    throw new Error(`source ${JSON.stringify(filePath)} is not valid UTF-8 text`, { cause: error })
+  }
+  return { canonicalPath, text }
+}
+
+/* jscpd:ignore-start -- Provider identity mirrors the seam while remote source and process ownership stay local. */
+/** One pooled remote provider with an isolated server per canonical workspace. */
+export class E2BLspProvider implements LspProvider {
+  readonly id: LspProviderId
+  readonly extensionToLanguage: Readonly<Record<string, string>>
+  private readonly instances = new Map<string, LspInstance>()
+  private readonly queues = new Map<string, Promise<void>>()
+  private disposed = false
+
+  constructor(
+    providerId: string,
+    private readonly sandbox: Sandbox,
+    private readonly subprocess: E2BSubprocessService,
+    private readonly config: ResolvedServerConfig,
+    private readonly executable: string,
+    private readonly nodeExecutable: string,
+    private readonly proxyPath: string,
+  ) {
+    this.id = LspProviderId(providerId)
+    this.extensionToLanguage = config.extensionToLanguage
+  }
+  /* jscpd:ignore-end */
+
+  async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
+    this.assertActive(signal)
+    const workspace = await canonicalizeE2BWorkspace(this.sandbox, request.workspaceRoot, signal)
+    this.assertActive(signal)
+    return this.enqueue(workspace, signal, async () => {
+      this.assertActive(signal)
+      const source = await readE2BSource(this.sandbox, request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      this.assertActive(signal)
+      let instance = this.instanceFor(workspace)
+      try {
+        return await instance.query(request, source, signal)
+      } catch (error: unknown) {
+        if (!instance.isTransportFailure(error)) throw error
+        await instance.dispose()
+        this.evict(workspace, instance)
+        this.assertActive(signal)
+        instance = this.instanceFor(workspace)
+        return await instance.query(request, source, signal)
+      } finally {
+        if (instance.dead) {
+          await instance.dispose()
+          this.evict(workspace, instance)
+        }
+      }
+    })
+  }
+
+  /* jscpd:ignore-start -- Queue and pooling semantics are shared; transport failure and disposal identities differ. */
+  /** Stop accepting work and await every remote server and queued query. */
+  async disposeAll(): Promise<void> {
+    this.disposed = true
+    const instances = [...this.instances.values()]
+    const queues = [...this.queues.values()]
+    this.instances.clear()
+    await Promise.all([...instances.map(instance => instance.dispose()), ...queues])
+    this.queues.clear()
+  }
+
+  private assertActive(signal?: AbortSignal): void {
+    if (this.disposed) throw new LspError('lsp-e2b provider is disposed', 'LSP_DISPOSED')
+    signal?.throwIfAborted()
+  }
+
+  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
+    const previous = this.queues.get(workspace) ?? Promise.resolve()
+    const result = abortable(previous, signal).then(run)
+    const tail = previous.then(() => result).then(() => undefined, () => undefined)
+    this.queues.set(workspace, tail)
+    void tail.then(() => { if (this.queues.get(workspace) === tail) this.queues.delete(workspace) })
+    return result
+  }
+
+  private instanceFor(workspace: string): LspInstance {
+    this.assertActive()
+    const existing = this.instances.get(workspace)
+    if (existing !== undefined) return existing
+    const created = this.createInstance(workspace)
+    this.instances.set(workspace, created)
+    return created
+  }
+  /* jscpd:ignore-end */
+
+  private createInstance(workspace: string): LspInstance {
+    return new LspInstance({
+      command: this.executable,
+      args: this.config.args,
+      cwd: workspace,
+      env: this.config.env,
+      configuration: this.config.configuration,
+      initializationOptions: this.config.initializationOptions,
+      maxMessageBytes: this.config.maxMessageBytes,
+      maxStderrBytes: this.config.maxStderrBytes,
+      shutdownTimeoutMs: this.config.shutdownTimeoutMs,
+      killGraceMs: this.config.killGraceMs,
+      clientProcessId: null,
+    }, (spec: SubprocessSpawnSpec) => {
+      const originalArgv = Buffer.from(JSON.stringify(spec.argv)).toString('base64')
+      const inner = this.subprocess.spawn({
+        ...spec,
+        argv: [this.nodeExecutable, this.proxyPath, originalArgv],
+        stdio: {
+          stdin: 'pipe',
+          stdout: 'pipe',
+          stderr: { maxBytes: this.config.maxStderrBytes },
+        },
+      })
+      const rawBound = Math.max(this.config.maxMessageBytes, this.config.maxStderrBytes)
+      return new E2BLspTransport(inner, rawBound * 2 + 1024, this.config.maxStderrBytes)
+    })
+  }
+
+  private evict(workspace: string, instance: LspInstance): void {
+    if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
+  }
+}
+
+/** Install the proxy, resolve remote commands, and atomically register providers. */
+export async function apply(ctx: Context, config: Config): Promise<void> {
+  if (!(ctx.subprocess instanceof E2BSubprocessService)) {
+    throw new Error('lsp-e2b requires @deepseek-ai/dsh-subprocess-e2b as ctx.subprocess')
+  }
+  const subprocess = ctx.subprocess
+  const entries = Object.entries(config.servers)
+  if (entries.length === 0) throw new Error('lsp-e2b: servers must contain at least one server')
+  const sandbox = await ctx.e2b.getSandbox()
+  const proxyPath = posix.join(ctx.e2b.runtimeRoot, 'lsp-stdio-proxy.mjs')
+  await sandbox.files.write([{ path: proxyPath, data: LSP_PROXY_SOURCE }])
+  await sandbox.commands.run(`chmod 600 -- ${quoteE2BShellArg(proxyPath)}`)
+  const nodeExecutable = await resolveE2BExecutable(sandbox, 'node')
+  const providers = await Promise.all(entries.map(async ([providerId, raw]) => {
+    if (providerId.trim() === '') throw new Error('lsp-e2b: server ids must be non-empty strings')
+    const resolved = raw as ResolvedServerConfig
+    validateServerConfig(providerId, resolved)
+    const executable = await resolveE2BExecutable(sandbox, resolved.command)
+    return new E2BLspProvider(providerId, sandbox, subprocess, resolved, executable, nodeExecutable, proxyPath)
+  }))
+
+  /* jscpd:ignore-start -- Every provider table publishes atomically through the same registry contract. */
+  ctx.effect(() => {
+    const disposers: Array<() => void> = []
+    try {
+      for (const provider of providers) disposers.push(ctx.lsp.registerProvider(provider))
+    } catch (error: unknown) {
+      for (const dispose of disposers.reverse()) dispose()
+      throw error
+    }
+    return async () => {
+      for (const dispose of disposers.reverse()) dispose()
+      await Promise.all(providers.map(provider => provider.disposeAll()))
+    }
+  }, 'lsp-e2b.registerProviders')
+  /* jscpd:ignore-end */
+}
diff --git a/packages/lsp/lsp-e2b/src/invariant.ts b/packages/lsp/lsp-e2b/src/invariant.ts
new file mode 100644
index 0000000000..129cf0a6d4
--- /dev/null
+++ b/packages/lsp/lsp-e2b/src/invariant.ts
@@ -0,0 +1,20 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-lsp-e2b`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-lsp-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'lsp-e2b-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: the LSP registry owns provider publication. */
+const install: InvariantInstaller = () => {}
+
+/** Register this package's invariant companion. */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/lsp/lsp-e2b/src/proxy-source.ts b/packages/lsp/lsp-e2b/src/proxy-source.ts
new file mode 100644
index 0000000000..5b6fe42d07
--- /dev/null
+++ b/packages/lsp/lsp-e2b/src/proxy-source.ts
@@ -0,0 +1,55 @@
+/** Dependency-free remote stdio proxy installed inside the E2B sandbox. */
+
+/**
+ * Node program that base64-frames raw child stdio so E2B's text callbacks
+ * never decode the language server's byte stream.
+ */
+export const LSP_PROXY_SOURCE = String.raw`import { Buffer } from 'node:buffer'
+import { spawn } from 'node:child_process'
+import { createInterface } from 'node:readline'
+
+const emit = (message) => {
+  process.stdout.write(Buffer.from(JSON.stringify(message)).toString('base64') + '\n')
+}
+
+let argv
+try {
+  argv = JSON.parse(Buffer.from(process.argv[2], 'base64').toString('utf8'))
+  if (!Array.isArray(argv) || argv.length === 0 || argv.some(value => typeof value !== 'string')) throw new Error('invalid argv')
+} catch (error) {
+  process.stderr.write('lsp-e2b proxy argv error: ' + String(error) + '\n')
+  process.exitCode = 125
+  process.stdin.destroy()
+}
+
+if (argv) {
+  const child = spawn(argv[0], argv.slice(1), { stdio: ['pipe', 'pipe', 'pipe'], env: process.env })
+  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
+  child.stdout.on('data', data => { emit({ type: 'stdout', data: data.toString('base64') }) })
+  child.stderr.on('data', data => { emit({ type: 'stderr', data: data.toString('base64') }) })
+  child.on('error', error => {
+    emit({ type: 'stderr', data: Buffer.from('language server spawn failed: ' + error.message).toString('base64') })
+  })
+  child.on('close', (code, signal) => {
+    emit({ type: 'exit', code, signal })
+    input.close()
+    process.stdin.destroy()
+    process.exitCode = code === null ? 1 : code
+  })
+  input.on('line', line => {
+    input.pause()
+    try {
+      const message = JSON.parse(Buffer.from(line, 'base64').toString('utf8'))
+      if (!message || message.type !== 'stdin' || typeof message.data !== 'string') throw new Error('invalid stdin frame')
+      const data = Buffer.from(message.data, 'base64')
+      if (data.toString('base64') !== message.data) throw new Error('invalid stdin base64')
+      if (child.stdin.write(data)) input.resume()
+      else child.stdin.once('drain', () => { input.resume() })
+    } catch (error) {
+      process.stderr.write('lsp-e2b proxy stdin error: ' + String(error) + '\n')
+      child.kill('SIGTERM')
+    }
+  })
+  input.on('close', () => { child.stdin.end() })
+}
+`
diff --git a/packages/lsp/lsp-e2b/src/transport.ts b/packages/lsp/lsp-e2b/src/transport.ts
new file mode 100644
index 0000000000..ddd3445db8
--- /dev/null
+++ b/packages/lsp/lsp-e2b/src/transport.ts
@@ -0,0 +1,183 @@
+/** Byte-faithful stdio transport over an E2B subprocess and ASCII/base64 frames. */
+
+import { Buffer } from 'node:buffer'
+import { PassThrough, Writable } from 'node:stream'
+import { E2BFrameDecoder, encodeE2BFrame } from '@deepseek-ai/dsh-e2b'
+import type {
+  SubprocessHandle,
+  SubprocessOutcome,
+  SubprocessOutputRead,
+  SubprocessOutputReader,
+} from '@deepseek-ai/dsh-subprocess'
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+class ByteTailReader implements SubprocessOutputReader {
+  private chunks: Buffer[] = []
+  private totalBytes = 0
+  private retainedBytes = 0
+  private dropped = false
+
+  constructor(private readonly maxBytes: number) {}
+
+  append(data: Buffer): void {
+    if (data.length === 0) return
+    this.chunks.push(data)
+    this.totalBytes += data.length
+    this.retainedBytes += data.length
+    while (this.retainedBytes > this.maxBytes && this.chunks.length > 0) {
+      const first = this.chunks[0] as Buffer
+      const excess = this.retainedBytes - this.maxBytes
+      if (first.length <= excess) {
+        this.chunks.shift()
+        this.retainedBytes -= first.length
+      } else {
+        this.chunks[0] = first.subarray(excess)
+        this.retainedBytes -= excess
+      }
+      this.dropped = true
+    }
+  }
+
+  readFrom(fromByte: number): SubprocessOutputRead {
+    if (!Number.isSafeInteger(fromByte) || fromByte < 0) {
+      throw new Error('subprocess output offset must be a non-negative safe integer')
+    }
+    const retainedStart = this.totalBytes - this.retainedBytes
+    const lossy = fromByte < retainedStart
+    const start = lossy ? 0 : Math.min(this.retainedBytes, fromByte - retainedStart)
+    const bytes = Buffer.concat(this.chunks).subarray(start)
+    return { text: bytes.toString('utf8'), nextOffset: this.totalBytes, lossy: lossy || this.dropped && fromByte === 0 }
+  }
+}
+
+class FramedInput extends Writable {
+  constructor(private readonly target: Writable) {
+    super()
+    target.on('error', (error: Error) => { this.destroy(error) })
+  }
+
+  override _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    this.target.write(encodeE2BFrame({ type: 'stdin', data: chunk.toString('base64') }), callback)
+  }
+
+  override _final(callback: (error?: Error | null) => void): void {
+    this.target.end(callback)
+  }
+}
+
+/** Subprocess handle that decodes a remote proxy's stdout/stderr byte frames. */
+export class E2BLspTransport implements SubprocessHandle {
+  readonly stdin: Writable
+  readonly stdout = new PassThrough()
+  readonly stderr = undefined
+  readonly collected: SubprocessHandle['collected']
+  readonly done: Promise<SubprocessOutcome>
+  private readonly stderrTail: ByteTailReader
+  private readonly decoder: E2BFrameDecoder
+  private failed: Error | undefined
+
+  /**
+   * @param inner - E2B subprocess running the installed proxy.
+   * @param maxFrameBytes - Maximum decoded proxy frame size.
+   * @param maxStderrBytes - Retained raw language-server stderr tail.
+   */
+  constructor(
+    private readonly inner: SubprocessHandle,
+    maxFrameBytes: number,
+    maxStderrBytes: number,
+  ) {
+    if (inner.stdin === undefined || inner.stdout === undefined) {
+      inner.terminate()
+      throw new Error('lsp-e2b: proxy subprocess dropped a piped stream')
+    }
+    this.stdin = new FramedInput(inner.stdin)
+    this.stderrTail = new ByteTailReader(maxStderrBytes)
+    this.collected = { stderr: this.stderrTail }
+    this.decoder = new E2BFrameDecoder(maxFrameBytes)
+    inner.stdout.on('data', (chunk: Buffer) => { this.onProxyData(chunk) })
+    inner.stdout.on('error', (error: Error) => { this.fail(error) })
+    this.done = inner.done.then(
+      (outcome) => {
+        this.finishFrames()
+        this.captureProxyStderr()
+        this.stdout.end()
+        if (this.failed !== undefined) throw this.failed
+        return outcome
+      },
+      (error: unknown) => {
+        this.captureProxyStderr()
+        this.stdout.end()
+        throw error
+      },
+    )
+    void this.done.catch(() => {})
+  }
+
+  get pid(): number {
+    return this.inner.pid
+  }
+
+  terminate(): void {
+    this.inner.terminate()
+  }
+
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    return await this.inner.waitForExit(signal)
+  }
+
+  private onProxyData(chunk: Buffer): void {
+    if (this.failed !== undefined) return
+    let frames: unknown[]
+    try {
+      frames = this.decoder.push(chunk.toString('utf8'))
+    } catch (error: unknown) {
+      this.fail(asError(error))
+      return
+    }
+    for (const frame of frames) this.dispatch(frame)
+  }
+
+  private dispatch(frame: unknown): void {
+    if (typeof frame !== 'object' || frame === null) {
+      this.fail(new Error('lsp-e2b: proxy emitted a malformed frame'))
+      return
+    }
+    const record = frame as Record<string, unknown>
+    if (record.type === 'exit' && (record.code === null || typeof record.code === 'number') && (record.signal === null || typeof record.signal === 'string')) return
+    if ((record.type !== 'stdout' && record.type !== 'stderr') || typeof record.data !== 'string') {
+      this.fail(new Error('lsp-e2b: proxy emitted a malformed frame'))
+      return
+    }
+    const data = Buffer.from(record.data, 'base64')
+    if (data.toString('base64') !== record.data) {
+      this.fail(new Error('lsp-e2b: proxy emitted invalid base64'))
+      return
+    }
+    if (record.type === 'stdout') this.stdout.write(data)
+    else this.stderrTail.append(data)
+  }
+
+  private finishFrames(): void {
+    if (this.failed !== undefined) return
+    try {
+      this.decoder.finish()
+    } catch (error: unknown) {
+      this.fail(asError(error))
+    }
+  }
+
+  private captureProxyStderr(): void {
+    const diagnostic = this.inner.collected.stderr?.readFrom(0).text
+    if (diagnostic !== undefined && diagnostic.length > 0) this.stderrTail.append(Buffer.from(diagnostic))
+  }
+
+  private fail(error: Error): void {
+    if (this.failed !== undefined) return
+    this.failed = error
+    this.inner.terminate()
+    this.stdout.end()
+  }
+}
diff --git a/packages/lsp/lsp-e2b/tests/provider.spec.ts b/packages/lsp/lsp-e2b/tests/provider.spec.ts
new file mode 100644
index 0000000000..0b41be12a3
--- /dev/null
+++ b/packages/lsp/lsp-e2b/tests/provider.spec.ts
@@ -0,0 +1,397 @@
+import { PassThrough } from 'node:stream'
+import { Context } from 'cordis'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  FileType,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+
+const mockedLsp = vi.hoisted(() => {
+  interface Plan {
+    query?: (...args: unknown[]) => unknown
+    transportFailure?: unknown
+    dead?: boolean
+    deadAfterQuery?: boolean
+    disposeError?: unknown
+  }
+
+  class FakeLspInstance {
+    static readonly instances: FakeLspInstance[] = []
+    static readonly plans: Plan[] = []
+    readonly plan: Plan
+    readonly transport: unknown
+    readonly queries: unknown[][] = []
+    dead: boolean
+    disposals = 0
+
+    constructor(
+      readonly spec: Record<string, unknown>,
+      spawner: (spec: SubprocessSpawnSpec) => unknown,
+    ) {
+      this.plan = FakeLspInstance.plans.shift() ?? {}
+      this.dead = this.plan.dead === true
+      this.transport = spawner({
+        argv: [String(spec.command), ...(spec.args as string[])],
+        cwd: String(spec.cwd),
+        env: spec.env as Record<string, string>,
+        graceMs: Number(spec.killGraceMs),
+        stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: Number(spec.maxStderrBytes) } },
+      })
+      FakeLspInstance.instances.push(this)
+    }
+
+    async query(...args: unknown[]): Promise<unknown> {
+      this.queries.push(args)
+      const result = await Promise.resolve(this.plan.query?.(...args) ?? { kind: 'hover', hover: null })
+      if (this.plan.deadAfterQuery === true) this.dead = true
+      return result
+    }
+
+    isTransportFailure(error: unknown): boolean {
+      return error === this.plan.transportFailure
+    }
+
+    async dispose(): Promise<void> {
+      this.disposals += 1
+      this.dead = true
+      if (this.plan.disposeError !== undefined) throw this.plan.disposeError
+    }
+  }
+
+  return { FakeLspInstance }
+})
+
+vi.mock('@deepseek-ai/dsh-lsp-local', () => ({ LspInstance: mockedLsp.FakeLspInstance }))
+
+import {
+  E2BLspProvider,
+  apply,
+  canonicalizeE2BWorkspace,
+  readE2BSource,
+} from '@deepseek-ai/dsh-lsp-e2b'
+import type { LspE2BServerConfig } from '@deepseek-ai/dsh-lsp-e2b'
+import * as E2BLspInvariant from '../src/invariant.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+class FakeInnerHandle implements SubprocessHandle {
+  readonly pid = 777
+  readonly stdin = new PassThrough()
+  readonly stdout = new PassThrough()
+  readonly stderr = undefined
+  readonly collected = { stderr: { readFrom: () => ({ text: '', nextOffset: 0, lossy: false }) } }
+  readonly done = Promise.resolve({ exitCode: 0, signal: null })
+  terminate(): void {}
+  async waitForExit(): Promise<boolean> { return true }
+}
+
+class FakeRemote {
+  readonly writes: Array<Array<{ path: string; data: string }>> = []
+  readonly commands: string[] = []
+  readonly infos = new Map<string, { type: FileType; size: number }>()
+  readonly contents = new Map<string, Uint8Array>()
+  readonly realpaths = new Map<string, string>()
+  forcedRealpath: string | undefined
+
+  constructor() {
+    this.infos.set('/workspace', { type: FileType.DIR, size: 0 })
+    this.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 12 })
+    this.contents.set('/workspace/file.ts', Buffer.from('const x = 1'))
+  }
+
+  readonly sandbox = {
+    commands: {
+      run: async (command: string) => {
+        this.commands.push(command)
+        if (command.startsWith('realpath ')) {
+          const match = /'([^']*)'$/.exec(command)
+          const requested = match?.[1] ?? ''
+          return { exitCode: 0, stdout: `${this.forcedRealpath ?? this.realpaths.get(requested) ?? requested}\n`, stderr: '' }
+        }
+        if (command.startsWith('command -v')) return { exitCode: 0, stdout: '/usr/bin/node\n', stderr: '' }
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+    files: {
+      write: async (files: Array<{ path: string; data: string }>) => {
+        this.writes.push(files)
+        return files.map(() => ({}))
+      },
+      getInfo: async (path: string) => {
+        const info = this.infos.get(path)
+        if (info === undefined) throw new Error(`missing info for ${path}`)
+        return info
+      },
+      read: async (path: string) => this.contents.get(path) ?? new Uint8Array(),
+    },
+  } as unknown as Sandbox
+}
+
+function subprocess(spawn = vi.fn((_spec: SubprocessSpawnSpec) => new FakeInnerHandle())): E2BSubprocessService {
+  const service = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
+  Object.defineProperty(service, 'spawn', { value: spawn })
+  return service
+}
+
+function server(overrides: Partial<LspE2BServerConfig> = {}): Required<LspE2BServerConfig> {
+  return {
+    command: '/usr/bin/server', args: ['--stdio'], env: {},
+    extensionToLanguage: { '.ts': 'typescript' },
+    initializationOptions: null, configuration: null,
+    maxMessageBytes: 1_024, maxStderrBytes: 128, maxDocumentBytes: 1_024,
+    shutdownTimeoutMs: 100, killGraceMs: 50,
+    ...overrides,
+  }
+}
+
+function provider(remote = new FakeRemote(), service = subprocess()): E2BLspProvider {
+  return new E2BLspProvider(
+    'fixture', remote.sandbox, service, server(),
+    '/usr/bin/server', '/usr/bin/node', '/workspace/.dsh-e2b/lsp-proxy.mjs',
+  )
+}
+
+function query(workspaceRoot = '/workspace') {
+  return {
+    operation: 'hover' as const,
+    filePath: 'file.ts',
+    position: { line: 0, character: 1 },
+    workspaceRoot,
+    languageId: 'typescript',
+  }
+}
+
+beforeEach(() => {
+  mockedLsp.FakeLspInstance.instances.length = 0
+  mockedLsp.FakeLspInstance.plans.length = 0
+})
+
+describe('E2B LSP filesystem boundary', () => {
+  it('canonicalizes a directory and reads a contained UTF-8 source', async () => {
+    const remote = new FakeRemote()
+    await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace')).resolves.toBe('/workspace')
+    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024)).resolves.toEqual({
+      canonicalPath: '/workspace/file.ts',
+      text: 'const x = 1',
+    })
+    await expect(readE2BSource(remote.sandbox, '/workspace/file.ts', '/workspace', 1_024)).resolves.toMatchObject({
+      canonicalPath: '/workspace/file.ts',
+    })
+    const signal = new AbortController().signal
+    await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace', signal)).resolves.toBe('/workspace')
+    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, signal)).resolves.toMatchObject({
+      canonicalPath: '/workspace/file.ts',
+    })
+  })
+
+  it('rejects malformed workspaces and source containment/type/size/encoding failures', async () => {
+    const malformed = new FakeRemote()
+    malformed.forcedRealpath = 'relative'
+    await expect(canonicalizeE2BWorkspace(malformed.sandbox, '/workspace')).rejects.toThrow('did not resolve canonically')
+    malformed.forcedRealpath = '/workspace\nother'
+    await expect(canonicalizeE2BWorkspace(malformed.sandbox, '/workspace')).rejects.toThrow('did not resolve canonically')
+
+    const notDirectory = new FakeRemote()
+    notDirectory.infos.set('/workspace', { type: FileType.FILE, size: 0 })
+    await expect(canonicalizeE2BWorkspace(notDirectory.sandbox, '/workspace')).rejects.toThrow('not a directory')
+
+    const outside = new FakeRemote()
+    outside.realpaths.set('/workspace/file.ts', '/outside/file.ts')
+    await expect(readE2BSource(outside.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('outside the workspace')
+
+    const notFile = new FakeRemote()
+    notFile.infos.set('/workspace/file.ts', { type: FileType.DIR, size: 0 })
+    await expect(readE2BSource(notFile.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('not a regular file')
+
+    const tooLarge = new FakeRemote()
+    tooLarge.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 21 })
+    await expect(readE2BSource(tooLarge.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('over the 20-byte limit')
+
+    const grew = new FakeRemote()
+    grew.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 1 })
+    grew.contents.set('/workspace/file.ts', Buffer.alloc(21))
+    await expect(readE2BSource(grew.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('grew past')
+
+    const invalid = new FakeRemote()
+    invalid.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 1 })
+    invalid.contents.set('/workspace/file.ts', Uint8Array.from([0xff]))
+    await expect(readE2BSource(invalid.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('not valid UTF-8')
+
+    await expect(canonicalizeE2BWorkspace(new FakeRemote().sandbox, '/workspace', AbortSignal.abort('stop')))
+      .rejects.toBe('stop')
+  })
+})
+
+describe('E2BLspProvider pooling and lifecycle', () => {
+  it('reuses one canonical-workspace instance and constructs the remote proxy transport', async () => {
+    const spawn = vi.fn((_spec: SubprocessSpawnSpec) => new FakeInnerHandle())
+    const remote = new FakeRemote()
+    mockedLsp.FakeLspInstance.plans.push({ query: async () => ({ kind: 'hover', hover: { contents: 'ok' } }) })
+    const current = provider(remote, subprocess(spawn))
+
+    await expect(current.query(query())).resolves.toEqual({ kind: 'hover', hover: { contents: 'ok' } })
+    await expect(current.query(query())).resolves.toEqual({ kind: 'hover', hover: { contents: 'ok' } })
+    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(1)
+    expect(mockedLsp.FakeLspInstance.instances[0]?.spec).toMatchObject({ clientProcessId: null, cwd: '/workspace' })
+    expect(spawn).toHaveBeenCalledWith(expect.objectContaining({
+      argv: ['/usr/bin/node', '/workspace/.dsh-e2b/lsp-proxy.mjs', expect.any(String)],
+      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 128 } },
+    }))
+    expect(current.id).toBe('fixture')
+    expect(current.extensionToLanguage).toEqual({ '.ts': 'typescript' })
+    await current.disposeAll()
+    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
+  })
+
+  it('replaces one transport failure, but preserves ordinary query errors', async () => {
+    const transportFailure = new Error('transport failed')
+    mockedLsp.FakeLspInstance.plans.push(
+      { transportFailure, query: async () => { throw transportFailure } },
+      { query: async () => ({ kind: 'hover', hover: { contents: 'retried' } }) },
+    )
+    const retried = provider()
+    await expect(retried.query(query())).resolves.toMatchObject({ hover: { contents: 'retried' } })
+    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
+    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(2)
+
+    const ordinary = new Error('ordinary failure')
+    mockedLsp.FakeLspInstance.plans.push(
+      { query: async () => { throw ordinary }, dead: true },
+      { query: async () => ({ kind: 'hover', hover: null }) },
+    )
+    const failed = provider()
+    await expect(failed.query(query())).rejects.toBe(ordinary)
+    await expect(failed.query(query())).resolves.toMatchObject({ kind: 'hover' })
+  })
+
+  it('evicts a server that dies after a successful query', async () => {
+    mockedLsp.FakeLspInstance.plans.push(
+      { deadAfterQuery: true, query: async () => ({ kind: 'hover', hover: null }) },
+      { query: async () => ({ kind: 'hover', hover: null }) },
+    )
+    const current = provider()
+    await current.query(query())
+    await current.query(query())
+    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(2)
+    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
+  })
+
+  it('serializes a workspace queue, observes queued abort, and awaits work on disposal', async () => {
+    const first = Promise.withResolvers<unknown>()
+    mockedLsp.FakeLspInstance.plans.push({ query: () => first.promise })
+    const current = provider()
+    const running = current.query(query())
+    const controller = new AbortController()
+    const queued = current.query(query(), controller.signal)
+    await new Promise(resolve => setImmediate(resolve))
+    controller.abort('queued stop')
+    await expect(queued).rejects.toBe('queued stop')
+
+    const disposing = current.disposeAll()
+    first.resolve({ kind: 'hover', hover: null })
+    await expect(running).resolves.toMatchObject({ kind: 'hover' })
+    await disposing
+    await expect(current.query(query())).rejects.toMatchObject({ code: 'LSP_DISPOSED' })
+  })
+
+  it('covers pre-abort, synthetic abort, resolve, and rejection in the queue race', async () => {
+    const current = provider()
+    const internal = current as unknown as {
+      queues: Map<string, Promise<void>>
+      enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T>
+    }
+    await expect(internal.enqueue('pre', AbortSignal.abort('pre-stop'), async () => 'unused')).rejects.toBe('pre-stop')
+
+    const signal = new AbortController().signal
+    await expect(internal.enqueue('resolve', signal, async () => 'ok')).resolves.toBe('ok')
+
+    const failure = new Error('queue failed')
+    const rejected = Promise.reject<undefined>(failure)
+    void rejected.catch(() => {})
+    internal.queues.set('reject', rejected)
+    await expect(internal.enqueue('reject', signal, async () => 'unused')).rejects.toBe(failure)
+
+    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- Exercise normalization at the promise boundary.
+    const opaque = Promise.reject<undefined>('opaque queue failure')
+    void opaque.catch(() => {})
+    internal.queues.set('opaque', opaque)
+    await expect(internal.enqueue('opaque', signal, async () => 'unused')).rejects.toEqual(new Error('opaque queue failure'))
+
+    const synthetic = {
+      aborted: false,
+      reason: undefined,
+      throwIfAborted() {},
+      addEventListener(_type: string, listener: () => void) { listener() },
+      removeEventListener() {},
+    } as unknown as AbortSignal
+    await expect(internal.enqueue('synthetic', synthetic, async () => 'unused')).rejects.toMatchObject({ name: 'AbortError' })
+    await current.disposeAll()
+  })
+})
+
+describe('lsp-e2b plugin composition', () => {
+  function pluginContext(
+    remote: FakeRemote,
+    service: E2BSubprocessService,
+    registerProvider = vi.fn(() => vi.fn()),
+  ) {
+    const effects: Array<() => void | Promise<void>> = []
+    const ctx = {
+      subprocess: service,
+      e2b: {
+        runtimeRoot: '/workspace/.dsh-e2b',
+        getSandbox: async () => remote.sandbox,
+      },
+      lsp: { registerProvider },
+      effect: (callback: () => (() => void | Promise<void>)) => { effects.push(callback()) },
+    } as unknown as Context
+    return { ctx, effects, registerProvider }
+  }
+
+  it('installs one proxy, resolves commands, registers providers, and disposes them', async () => {
+    const remote = new FakeRemote()
+    const fixture = pluginContext(remote, subprocess())
+    await apply(fixture.ctx, { servers: { one: server(), two: server({ command: 'server-two' }) } })
+    expect(remote.writes).toHaveLength(1)
+    expect(remote.writes[0]?.[0]?.path).toBe('/workspace/.dsh-e2b/lsp-stdio-proxy.mjs')
+    expect(remote.commands).toContain("chmod 600 -- '/workspace/.dsh-e2b/lsp-stdio-proxy.mjs'")
+    expect(fixture.registerProvider).toHaveBeenCalledTimes(2)
+    await fixture.effects[0]?.()
+  })
+
+  it('rolls back partial registration and rejects invalid composition/configuration', async () => {
+    const remote = new FakeRemote()
+    const firstDispose = vi.fn()
+    const register = vi.fn()
+      .mockReturnValueOnce(firstDispose)
+      .mockImplementationOnce(() => { throw new Error('duplicate provider') })
+    const rollback = pluginContext(remote, subprocess(), register)
+    await expect(apply(rollback.ctx, { servers: { one: server(), two: server() } })).rejects.toThrow('duplicate provider')
+    expect(firstDispose).toHaveBeenCalledOnce()
+
+    const wrong = pluginContext(remote, {} as E2BSubprocessService)
+    await expect(apply(wrong.ctx, { servers: { one: server() } })).rejects.toThrow('dsh-subprocess-e2b')
+
+    const empty = pluginContext(remote, subprocess())
+    await expect(apply(empty.ctx, { servers: {} })).rejects.toThrow('at least one server')
+
+    for (const [id, config] of [
+      ['', server()],
+      ['one', server({ command: '' })],
+      ['one', server({ maxMessageBytes: 0 })],
+      ['one', server({ maxStderrBytes: 1.5 })],
+      ['one', server({ shutdownTimeoutMs: 2_147_483_648 })],
+    ] as const) {
+      const fixture = pluginContext(new FakeRemote(), subprocess())
+      await expect(apply(fixture.ctx, { servers: { [id]: config } })).rejects.toThrow()
+    }
+  })
+
+  it('registers the package-owned invariant companion', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BLspInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/lsp/lsp-e2b/tests/transport.spec.ts b/packages/lsp/lsp-e2b/tests/transport.spec.ts
new file mode 100644
index 0000000000..ae5106bc09
--- /dev/null
+++ b/packages/lsp/lsp-e2b/tests/transport.spec.ts
@@ -0,0 +1,181 @@
+import { once } from 'node:events'
+import { PassThrough } from 'node:stream'
+import { describe, expect, it } from 'vitest'
+import { encodeE2BFrame } from '@deepseek-ai/dsh-e2b'
+import type { SubprocessHandle, SubprocessOutcome } from '@deepseek-ai/dsh-subprocess'
+import { E2BLspTransport } from '@deepseek-ai/dsh-lsp-e2b'
+
+class FakeHandle implements SubprocessHandle {
+  readonly pid = 321
+  readonly stdin: PassThrough | undefined
+  readonly stdout: PassThrough | undefined
+  readonly stderr = undefined
+  readonly collected: SubprocessHandle['collected']
+  readonly result = Promise.withResolvers<SubprocessOutcome>()
+  readonly done = this.result.promise
+  terminated = 0
+  waitResult = true
+
+  constructor(options: { stdin?: boolean; stdout?: boolean; diagnostic?: string } = {}) {
+    this.stdin = options.stdin === false ? undefined : new PassThrough()
+    this.stdout = options.stdout === false ? undefined : new PassThrough()
+    this.collected = options.diagnostic === undefined
+      ? {}
+      : { stderr: { readFrom: () => ({ text: options.diagnostic as string, nextOffset: 0, lossy: false }) } }
+  }
+
+  terminate(): void {
+    this.terminated += 1
+  }
+
+  async waitForExit(): Promise<boolean> {
+    return this.waitResult
+  }
+
+  resolve(outcome: SubprocessOutcome = { exitCode: 0, signal: null }): void {
+    this.stdout?.end()
+    this.result.resolve(outcome)
+  }
+
+  reject(error: unknown): void {
+    this.stdout?.end()
+    this.result.reject(error)
+  }
+}
+
+function proxyFrame(type: 'stdout' | 'stderr', data: string | Buffer): string {
+  return encodeE2BFrame({ type, data: Buffer.from(data).toString('base64') })
+}
+
+describe('E2BLspTransport', () => {
+  it('frames stdin, decodes split byte output, and exposes handle lifecycle', async () => {
+    const inner = new FakeHandle({ diagnostic: 'proxy diagnostic' })
+    const transport = new E2BLspTransport(inner, 1_024, 64)
+    let stdin = ''
+    inner.stdin?.on('data', (chunk) => { stdin += String(chunk) })
+    let stdout = Buffer.alloc(0)
+    transport.stdout.on('data', (chunk) => { stdout = Buffer.concat([stdout, chunk]) })
+
+    transport.stdin.write(Buffer.from([0, 0xff]))
+    await new Promise(resolve => setImmediate(resolve))
+    const encodedInput = stdin.trim()
+    const input = JSON.parse(Buffer.from(encodedInput, 'base64').toString('utf8')) as Record<string, string>
+    expect(input).toEqual({ type: 'stdin', data: 'AP8=' })
+
+    const frames = proxyFrame('stdout', Buffer.from([0, 0xff]))
+      + proxyFrame('stderr', 'server diagnostic')
+      + encodeE2BFrame({ type: 'exit', code: 0, signal: null })
+    inner.stdout?.write(frames.slice(0, 7))
+    inner.stdout?.write(frames.slice(7))
+    inner.stdout?.write(proxyFrame('stderr', ''))
+    inner.stdout?.write(encodeE2BFrame({ type: 'exit', code: null, signal: 'SIGTERM' }))
+    inner.resolve()
+
+    await expect(transport.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(stdout).toEqual(Buffer.from([0, 0xff]))
+    expect(transport.collected.stderr?.readFrom(0).text).toBe('server diagnosticproxy diagnostic')
+    expect(transport.pid).toBe(321)
+    inner.waitResult = false
+    await expect(transport.waitForExit()).resolves.toBe(false)
+    transport.terminate()
+    expect(inner.terminated).toBe(1)
+  })
+
+  it('ends the inner stdin and retains a bounded byte tail with independent offsets', async () => {
+    const inner = new FakeHandle()
+    const transport = new E2BLspTransport(inner, 1_024, 4)
+    const finished = once(inner.stdin!, 'finish')
+    transport.stdin.end()
+    await finished
+
+    inner.stdout?.write(proxyFrame('stderr', 'ab'))
+    inner.stdout?.write(proxyFrame('stderr', 'cdef'))
+    const reader = transport.collected.stderr!
+    expect(reader.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true })
+    expect(reader.readFrom(2)).toEqual({ text: 'cdef', nextOffset: 6, lossy: false })
+    expect(reader.readFrom(5)).toEqual({ text: 'f', nextOffset: 6, lossy: false })
+    expect(reader.readFrom(99)).toEqual({ text: '', nextOffset: 6, lossy: false })
+    expect(() => reader.readFrom(-1)).toThrow('non-negative safe integer')
+    expect(() => reader.readFrom(1.5)).toThrow('non-negative safe integer')
+    inner.resolve()
+    await transport.done
+
+    const partialInner = new FakeHandle()
+    const partial = new E2BLspTransport(partialInner, 1_024, 4)
+    partialInner.stdout?.write(proxyFrame('stderr', 'abcdef'))
+    expect(partial.collected.stderr?.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true })
+    partialInner.resolve()
+    await partial.done
+  })
+
+  it.each([
+    ['non-object', encodeE2BFrame(null), 'malformed frame'],
+    ['wrong type', encodeE2BFrame({ type: 'other', data: '' }), 'malformed frame'],
+    ['invalid exit', encodeE2BFrame({ type: 'exit', code: 'zero', signal: null }), 'malformed frame'],
+    ['missing data', encodeE2BFrame({ type: 'stdout' }), 'malformed frame'],
+    ['invalid base64', encodeE2BFrame({ type: 'stdout', data: 'abc' }), 'invalid base64'],
+    ['invalid outer frame', 'not-base64\n', 'invalid base64'],
+    ['non-ASCII outer frame', 'é', 'non-ASCII'],
+  ])('fails %s proxy traffic and terminates the group', async (_name, frame, message) => {
+    const inner = new FakeHandle()
+    const transport = new E2BLspTransport(inner, 1_024, 32)
+    inner.stdout?.write(frame)
+    inner.stdout?.write(proxyFrame('stdout', 'ignored'))
+    inner.stdout?.emit('error', new Error('second failure'))
+    inner.resolve()
+    await expect(transport.done).rejects.toThrow(message)
+    expect(inner.terminated).toBe(1)
+  })
+
+  it('fails truncated frames and preserves inner spawn rejection', async () => {
+    const truncatedInner = new FakeHandle()
+    const truncated = new E2BLspTransport(truncatedInner, 1_024, 32)
+    truncatedInner.stdout?.write('YQ==')
+    truncatedInner.resolve()
+    await expect(truncated.done).rejects.toThrow('mid-frame')
+
+    const rejectedInner = new FakeHandle({ diagnostic: 'tail' })
+    const rejected = new E2BLspTransport(rejectedInner, 1_024, 32)
+    rejectedInner.reject(new Error('spawn failed'))
+    await expect(rejected.done).rejects.toThrow('spawn failed')
+    expect(rejected.collected.stderr?.readFrom(0).text).toBe('tail')
+  })
+
+  it('forwards output and input stream errors without an unhandled inner error', async () => {
+    const outputInner = new FakeHandle()
+    const output = new E2BLspTransport(outputInner, 1_024, 32)
+    outputInner.stdout?.emit('error', new Error('proxy stdout failed'))
+    outputInner.resolve()
+    await expect(output.done).rejects.toThrow('proxy stdout failed')
+
+    const inputInner = new FakeHandle()
+    const input = new E2BLspTransport(inputInner, 1_024, 32)
+    const outerError = once(input.stdin, 'error')
+    inputInner.stdin?.emit('error', new Error('proxy stdin failed'))
+    await expect(outerError).resolves.toMatchObject([{ message: 'proxy stdin failed' }])
+    inputInner.resolve()
+    await input.done
+  })
+
+  it('normalizes a non-Error decoder throw', async () => {
+    const inner = new FakeHandle()
+    const transport = new E2BLspTransport(inner, 1_024, 32)
+    const internal = transport as unknown as {
+      decoder: { push(chunk: string): unknown[] }
+      onProxyData(chunk: Buffer): void
+    }
+    internal.decoder = { push: () => { throw 'raw decoder failure' } }
+    internal.onProxyData(Buffer.from('x'))
+    inner.resolve()
+    await expect(transport.done).rejects.toThrow('raw decoder failure')
+  })
+
+  it('rejects a subprocess that drops either required pipe', () => {
+    const missingStdin = new FakeHandle({ stdin: false })
+    const missingStdout = new FakeHandle({ stdout: false })
+    expect(() => new E2BLspTransport(missingStdin, 10, 10)).toThrow('dropped a piped stream')
+    expect(() => new E2BLspTransport(missingStdout, 10, 10)).toThrow('dropped a piped stream')
+    expect(missingStdin.terminated).toBe(1)
+    expect(missingStdout.terminated).toBe(1)
+  })
+})
diff --git a/packages/lsp/lsp-e2b/tsconfig.json b/packages/lsp/lsp-e2b/tsconfig.json
new file mode 100644
index 0000000000..4679845db8
--- /dev/null
+++ b/packages/lsp/lsp-e2b/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../e2b/e2b" },
+    { "path": "../lsp" },
+    { "path": "../lsp-local" },
+    { "path": "../../subprocess/subprocess" },
+    { "path": "../../subprocess/subprocess-e2b" },
+    { "path": "../../util/timeout" },
+    { "path": "../../support/invariants" }
+  ]
+}
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index 318704b9fc..d643db1528 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -7,6 +7,7 @@
  * @module @deepseek-ai/dsh-lsp-local/instance
  */
 
+import { pathToFileURL } from 'node:url'
 import { LspError } from '@deepseek-ai/dsh-lsp'
 import type {
   LspOperation,
@@ -30,12 +31,12 @@ import {
 
 /** Everything an instance needs beyond the connection spec. */
 export interface InstanceSpec extends ConnectionSpec {
-  /** Canonical workspace file URI supplied by the filesystem provider. */
-  readonly workspaceUri: string
   /** Static `initialize` options forwarded to the server. */
   readonly initializationOptions: unknown
   /** Graceful `shutdown`/`exit` budget before escalation (ms). */
   readonly shutdownTimeoutMs: number
+  /** PID advertised to the server; `null` when client and server do not share a process namespace. */
+  readonly clientProcessId?: number | null
 }
 
 /**
@@ -109,11 +110,9 @@ export class LspInstance {
 
   private async initialize(): Promise<void> {
     const initializeResult = await this.connection.request('initialize', {
-      // A subprocess provider may run in another PID namespace or machine;
-      // the host PID would let the server monitor an unrelated process.
-      processId: null,
-      rootUri: this.spec.workspaceUri,
-      workspaceFolders: [{ uri: this.spec.workspaceUri, name: 'workspace' }],
+      processId: this.spec.clientProcessId === undefined ? process.pid : this.spec.clientProcessId,
+      rootUri: pathToFileURL(this.spec.cwd).href,
+      workspaceFolders: [{ uri: pathToFileURL(this.spec.cwd).href, name: 'workspace' }],
       capabilities: CLIENT_CAPABILITIES,
       initializationOptions: this.spec.initializationOptions,
     }) as WireInitializeResult
@@ -150,7 +149,7 @@ export class LspInstance {
       throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION')
     }
 
-    const uri = source.fileUrl
+    const uri = pathToFileURL(source.canonicalPath).href
     let opened = false
     try {
       /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */
@@ -244,9 +243,10 @@ export class LspInstance {
     if (operation === 'hover') {
       return { kind: 'hover', hover: normalizeHover(payload) }
     }
-    // The filesystem provider owns URI syntax for the execution platform, which may differ from the
-    // harness host. Preserve that coordinate through rendering instead of reparsing `spec.cwd` there.
-    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceUri: this.spec.workspaceUri }
+    // `spec.cwd` is the canonical workspace realpath (the provider canonicalizes before spawning),
+    // and every `file:` location URI is relative to it — so it is the root a caller must relativize
+    // display paths against, not the request's possibly-symlinked workspaceRoot.
+    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceRoot: this.spec.cwd }
   }
 
   private answerServerRequest(method: string, params: unknown): Promise<unknown> {
diff --git a/packages/lsp/lsp-local/tests/fixture-server.ts b/packages/lsp/lsp-local/tests/fixture-server.ts
index 9399b5a1a7..89053894ee 100644
--- a/packages/lsp/lsp-local/tests/fixture-server.ts
+++ b/packages/lsp/lsp-local/tests/fixture-server.ts
@@ -15,6 +15,7 @@
  * - LSP_FAKE_REPLY_DELAY_MS: delays each textDocument/* response by this many milliseconds.
  * - LSP_FAKE_OPEN_MARKER: appends each didOpen document text as one JSON line to this path.
  * - LSP_FAKE_INITIALIZED_MARKER: records when the initialized notification is received.
+ * - LSP_FAKE_EXPECT_PROCESS_ID: expected JSON `initialize.processId`; mismatch exits nonzero.
  * - LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED: "1" stops consuming stdin after initialized.
  * - LSP_FAKE_EXIT_DELAY_MS / LSP_FAKE_EXIT_MARKER: delay protocol exit and record exit/termination.
  * - LSP_FAKE_NO_SHUTDOWN: "1" ignores the shutdown request (forces kill escalation).
@@ -37,6 +38,7 @@ const exitAfterReply = process.env.LSP_FAKE_EXIT_AFTER_REPLY === '1'
 const replyDelayMs = Number(process.env.LSP_FAKE_REPLY_DELAY_MS ?? 0)
 const openMarker = process.env.LSP_FAKE_OPEN_MARKER
 const initializedMarker = process.env.LSP_FAKE_INITIALIZED_MARKER
+const expectedProcessId = process.env.LSP_FAKE_EXPECT_PROCESS_ID
 const pauseStdinAfterInitialized = process.env.LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED === '1'
 const exitDelayMs = Number(process.env.LSP_FAKE_EXIT_DELAY_MS ?? 0)
 const exitMarker = process.env.LSP_FAKE_EXIT_MARKER
@@ -102,6 +104,10 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul
     return
   }
   if (method === 'initialize') {
+    if (expectedProcessId !== undefined) {
+      const params = message.params as { processId?: unknown } | undefined
+      if (JSON.stringify(params?.processId) !== expectedProcessId) process.exit(2)
+    }
     if (garbage) process.stdout.write('this is not a framed message\r\n')
     send({
       id,
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 08bad67ae2..939b58f0b1 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -109,6 +109,11 @@ const RESPONDING_SERVER =
 const locJson = () => JSON.stringify({ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } })
 
 describe('LspInstance server-request handling', () => {
+  it('advertises a null process id across process namespaces', async () => {
+    const instance = makeInstance({ LSP_FAKE_EXPECT_PROCESS_ID: 'null', LSP_FAKE_DEF: 'null' }, { clientProcessId: null })
+    await expect(run(instance, 'goToDefinition')).resolves.toMatchObject({ kind: 'locations' })
+  })
+
   it('answers workspace/configuration with the static config per item', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'configuration', LSP_FAKE_DEF: locJson() })
     // The query drives didOpen, which makes the fake emit workspace/configuration; a healthy answer
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index 02649a8d39..b672a405de 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/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/lsp/lsp/README.md
-README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
-README.zh.md: cc412333e63b9469319240d67269bf0192ad3858
+README.md: bcffd460f192b0e6ac214ad0bc0d43da4c81d68c
+README.zh.md: e9df352e999834235a66ef7a500e300dadc2029c
diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md
index 5c1044be50..4dc0436bbb 100644
--- a/packages/lsp/lsp/README.md
+++ b/packages/lsp/lsp/README.md
@@ -10,6 +10,7 @@ This package is the interface third of the LSP capability:
 |---|---|
 | `@deepseek-ai/dsh-lsp` (this) | the interface: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
 | `@deepseek-ai/dsh-lsp-local` | a generic local backend that registers configured stdio language-server providers |
+| `@deepseek-ai/dsh-lsp-e2b` | a generic E2B backend that registers configured remote stdio providers |
 | `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool over `ctx.lsp` |
 
 The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`.
diff --git a/packages/lsp/lsp/README.zh.md b/packages/lsp/lsp/README.zh.md
index cc412333e6..fdaedc9a96 100644
--- a/packages/lsp/lsp/README.zh.md
+++ b/packages/lsp/lsp/README.zh.md
@@ -10,6 +10,7 @@
 |---|---|
 | `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
 | `@deepseek-ai/dsh-lsp-local` | 通用本地后端，注册已配置的 stdio 语言服务器提供方 |
+| `@deepseek-ai/dsh-lsp-e2b` | 通用 E2B 后端，注册已配置的远程 stdio 提供方 |
 | `@deepseek-ai/dsh-tool-lsp` | 面向模型的 `lsp` 工具，基于 `ctx.lsp` |
 
 该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且没有通用 JSON-RPC 逃生口，因此任何协议载荷或未经评审的命令／修改都无法通过 `ctx.lsp` 到达提供方。
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index 65d541a7c1..c0fa873642 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
-README.md: a4f743056b4a524be9623b0f700f37e0534b463f
-README.zh.md: c84ad3f1b59afcdbbd111f1b82c57c56aa24fdcf
+README.md: 239c751f30f8e5c543e6737e65a67f9bb22f79ad
+README.zh.md: edaae7f948d957e2fce2b3f331cc2af61cfabd36
diff --git a/packages/pty/README.md b/packages/pty/README.md
index a4f743056b..239c751f30 100644
--- a/packages/pty/README.md
+++ b/packages/pty/README.md
@@ -7,7 +7,8 @@ English | [中文](README.zh.md)
 | Package | Role | ctx key |
 |---|---|---|
 | [`pty`](pty/README.md) (`@deepseek-ai/dsh-pty`) | Backend registry, branded ids, exact-Agent ownership, session operations, and awaited cleanup | `ctx.pty` |
-| `pty-local` (`@deepseek-ai/dsh-pty-local`) | Shell backend over `ctx.subprocess.spawnTerminal`: readiness detection, bounded terminal state, sandbox policy, and session operations | registers on `ctx.pty` |
+| [`pty-local`](pty-local/README.md) (`@deepseek-ai/dsh-pty-local`) | Local `node-pty` backend, readiness detection, bounded terminal state, sandboxing, and process-session supervision | registers on `ctx.pty` |
+| [`pty-e2b`](pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | E2B byte-PTY backend, remote foreground signaling, bounded terminal state, and awaited remote cleanup | registers on `ctx.pty` |
 | `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
-The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
+The core design lives in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md); the remote ownership boundary lives in the [E2B extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index c84ad3f1b5..edaae7f948 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -7,7 +7,8 @@
 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | [`pty`](pty/README.md)（`@deepseek-ai/dsh-pty`） | 后端注册表、品牌化 id、精确的 Agent 所有权、会话操作与等待完成的清理 | `ctx.pty` |
-| `pty-local`（`@deepseek-ai/dsh-pty-local`） | `ctx.subprocess.spawnTerminal` 之上的 shell 后端：就绪检测、有界终端状态、沙箱策略与会话操作 | 注册到 `ctx.pty` |
+| [`pty-local`](pty-local/README.md)（`@deepseek-ai/dsh-pty-local`） | 本地 `node-pty` 后端、就绪检测、有界终端状态、沙箱与进程会话监管 | 注册到 `ctx.pty` |
+| [`pty-e2b`](pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | E2B 字节 PTY 后端、远程前台信号传递、有界终端状态与等待完成的远程清理 | 注册到 `ctx.pty` |
 | `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
-设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
+核心设计记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中；远程所有权边界记录在 [E2B 扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) 中。
diff --git a/packages/pty/pty-e2b/README.i18n.yaml b/packages/pty/pty-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..bfd7795349
--- /dev/null
+++ b/packages/pty/pty-e2b/README.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 packages/pty/pty-e2b/README.md
+README.md: 7a8ddc9e08f4d28d69b97825232b00e2d8f394b7
+README.zh.md: 2151ca1f2d91b01a7b0106153f708ace2c3d2726
diff --git a/packages/pty/pty-e2b/README.md b/packages/pty/pty-e2b/README.md
new file mode 100644
index 0000000000..7a8ddc9e08
--- /dev/null
+++ b/packages/pty/pty-e2b/README.md
@@ -0,0 +1,54 @@
+# @deepseek-ai/dsh-pty-e2b
+
+English | [中文](README.zh.md)
+
+E2B byte-PTY backend for [`ctx.pty`](../pty/README.md). It creates persistent interactive shells inside the shared `ctx.e2b` sandbox while the PTY registry keeps session identity, exact-Agent ownership, and cleanup policy on the host.
+
+## Plugin and configuration
+
+The `pty-e2b` plugin injects `e2b` and `pty`, then registers one backend under `backendType`.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `backendType` | `shell` | Registry type selected by `terminal_open`. |
+| `rows` / `cols` | `40` / `160` | Initial remote PTY size. |
+| `scrollbackLines` | `10000` | Maximum retained logical lines. |
+| `scrollbackMaxBytes` | `4194304` | Maximum retained UTF-8 scrollback bytes. |
+| `maxReadBytes` | `262144` | Maximum bytes returned by one read or settled send. |
+| `pollIntervalMs` | `50` | Host readiness-poll interval. |
+| `idleSilenceMs` | `3000` | Output silence that yields `inferred_idle`. |
+| `timeoutMs` | `30000` | Absolute startup and send wait bound. |
+| `disposeGraceMs` | `3000` | TERM-to-KILL cleanup grace. |
+
+Numeric values are positive safe integers, `backendType` is non-empty, and `maxReadBytes` cannot exceed `scrollbackMaxBytes`. A relative spawn cwd resolves against `ctx.e2b.cwd`; an absolute remote path remains absolute.
+
+## Runtime contract
+
+The backend uses E2B's byte-oriented PTY callback with a streaming fatal UTF-8 decoder, then the backend-neutral line sanitizer and bounded buffers from `dsh-pty`. It installs a controlled Bash prompt marker and waits for printable prompt text; when that marker is unavailable, observed output plus the configured silence bound yields `inferred_idle`. Startup with no output reaches the absolute timeout and fails instead of publishing an empty session.
+
+Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; `SIGKILL` refuses to target the shell itself. Close sends `SIGTERM` to the PTY process group, waits, escalates through E2B's PTY kill, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
+
+The remote PTY process and its child processes live in E2B. Prompt/readiness state, scrollback, operation handles, owner authority, and SDK event delivery remain in host memory.
+
+## Model Experience
+
+### Indirect consumer
+
+#### What the model sees
+
+Nothing directly. Through `@deepseek-ai/dsh-tool-pty`, the model may receive bounded MOTD, send deltas, scrollback pages, readiness reasons, signal results, and cleanup failures.
+
+#### Token effect
+
+None until a consumer returns bounded backend output. Retained host PTY scrollback is not placed in model history by this package.
+
+#### KV Cache effect
+
+No direct invalidation; the consumer owns prompts, schemas, and appended results.
+
+## Known Limitations and Deferred Work
+
+- **Line-oriented terminal model** — CSI/OSC control sequences are removed; alternate-screen and full terminal emulation remain unsupported.
+- **Readiness is marker-or-silence based** — E2B exposes foreground process groups but not the local backend's Linux syscall inspection, so `inferred_idle` is deliberately possible.
+- **UTF-8 only** — invalid byte sequences fail the session instead of returning lossy text.
+- **No reconnectable terminal handles** — retaining an E2B sandbox preserves remote files, not host ownership, buffers, callbacks, or live PTY sessions.
diff --git a/packages/pty/pty-e2b/README.zh.md b/packages/pty/pty-e2b/README.zh.md
new file mode 100644
index 0000000000..2151ca1f2d
--- /dev/null
+++ b/packages/pty/pty-e2b/README.zh.md
@@ -0,0 +1,54 @@
+# @deepseek-ai/dsh-pty-e2b
+
+[English](README.md) | 中文
+
+用于 [`ctx.pty`](../pty/README.md) 的 E2B 字节 PTY 后端。它在共享的 `ctx.e2b` 沙箱内创建持久交互式 shell；PTY 注册表则在宿主侧维护会话身份、精确的 Agent 所有权和清理策略。
+
+## 插件与配置
+
+`pty-e2b` 插件注入 `e2b` 和 `pty`，然后以 `backendType` 注册一个后端。
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `backendType` | `shell` | `terminal_open` 选择的注册表类型。 |
+| `rows` / `cols` | `40` / `160` | 远程 PTY 的初始尺寸。 |
+| `scrollbackLines` | `10000` | 保留的逻辑行数上限。 |
+| `scrollbackMaxBytes` | `4194304` | 保留的 UTF-8 scrollback 字节数上限。 |
+| `maxReadBytes` | `262144` | 单次读取或发送结算时返回的字节数上限。 |
+| `pollIntervalMs` | `50` | 宿主就绪轮询间隔。 |
+| `idleSilenceMs` | `3000` | 触发 `inferred_idle` 的输出静默时长。 |
+| `timeoutMs` | `30000` | 启动与发送等待的绝对上限。 |
+| `disposeGraceMs` | `3000` | TERM 到 KILL 的清理宽限期。 |
+
+数值必须是正的安全整数，`backendType` 必须非空，且 `maxReadBytes` 不得超过 `scrollbackMaxBytes`。相对的 spawn cwd 以 `ctx.e2b.cwd` 为基准解析；绝对远程路径保持不变。
+
+## 运行时契约
+
+该后端为 E2B 面向字节的 PTY 回调配备流式、遇到无效序列即失败的 UTF-8 解码器，随后使用 `dsh-pty` 提供的后端无关行清理器与有界缓冲区。它会安装受控的 Bash 提示符标记，并等待可打印的提示符文本；若该标记不可用，系统会在已经观察到输出且达到已配置的静默上限时得出 `inferred_idle`。零输出的启动过程会达到绝对超时并失败，不会发布空会话。
+
+每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；发送 `SIGKILL` 时拒绝以 shell 本身为目标。关闭操作向 PTY 进程组发送 `SIGTERM`，等待后通过 E2B 的 PTY kill 操作升级，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
+
+远程 PTY 进程及其子进程位于 E2B。提示符／就绪状态、scrollback、操作句柄、所有者权限和 SDK 事件交付仍保留在宿主内存中。
+
+## 模型体验
+
+### 间接消费方
+
+#### 模型看到的内容
+
+没有直接可见内容。模型通过 `@deepseek-ai/dsh-tool-pty` 可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因、信号结果和清理失败。
+
+#### Token 影响
+
+消费方返回有界的后端输出前没有影响。本包不会把宿主保留的 PTY scrollback 放入模型历史。
+
+#### KV Cache 影响
+
+不会直接失效；提示词、schema 和追加结果由消费方负责。
+
+## 已知限制与暂缓工作
+
+- **面向行的终端模型**：CSI／OSC 控制序列会被移除；备用屏幕与完整终端仿真仍不受支持。
+- **就绪判断基于标记或静默**：E2B 会公开前台进程组，但不提供本地后端使用的 Linux syscall 检查，因此系统有意保留返回 `inferred_idle` 的可能性。
+- **仅支持 UTF-8**：无效字节序列会使会话失败，而不是返回有损文本。
+- **没有可重连的终端句柄**：保留 E2B 沙箱会保留远程文件，但不会保留宿主所有权、缓冲区、回调或实时 PTY 会话。
diff --git a/packages/pty/pty-e2b/package.json b/packages/pty/pty-e2b/package.json
new file mode 100644
index 0000000000..cc31699ab1
--- /dev/null
+++ b/packages/pty/pty-e2b/package.json
@@ -0,0 +1,46 @@
+{
+  "name": "@deepseek-ai/dsh-pty-e2b",
+  "description": "E2B PTY provider for DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-pty": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-pty": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/pty/pty-e2b/src/config.ts b/packages/pty/pty-e2b/src/config.ts
new file mode 100644
index 0000000000..e6849bf54d
--- /dev/null
+++ b/packages/pty/pty-e2b/src/config.ts
@@ -0,0 +1,64 @@
+/** Validated configuration for the E2B PTY backend. */
+
+import z from 'schemastery'
+
+/** Public plugin configuration. */
+export interface Config {
+  /** Backend registry type. */
+  backendType?: string
+  /** Initial terminal rows. */
+  rows?: number
+  /** Initial terminal columns. */
+  cols?: number
+  /** Maximum retained logical lines. */
+  scrollbackLines?: number
+  /** Maximum retained UTF-8 bytes. */
+  scrollbackMaxBytes?: number
+  /** Maximum bytes returned by one read or settled viewport. */
+  maxReadBytes?: number
+  /** Readiness polling interval. */
+  pollIntervalMs?: number
+  /** Output silence duration that yields `inferred_idle`. */
+  idleSilenceMs?: number
+  /** Absolute send and startup wait bound. */
+  timeoutMs?: number
+  /** Grace before PTY teardown escalates from TERM to KILL. */
+  disposeGraceMs?: number
+}
+
+/** Configuration after Schemastery defaults. */
+export type ResolvedConfig = Required<Config>
+
+/* jscpd:ignore-start -- Loader requires a backend-local schema and load-time diagnostics. */
+/** Schemastery config exposed by the plugin. */
+export const Config: z<Config> = z.object({
+  backendType: z.string().default('shell'),
+  rows: z.number().default(40),
+  cols: z.number().default(160),
+  scrollbackLines: z.number().default(10_000),
+  scrollbackMaxBytes: z.number().default(4 * 1024 * 1024),
+  maxReadBytes: z.number().default(256 * 1024),
+  pollIntervalMs: z.number().default(50),
+  idleSilenceMs: z.number().default(3_000),
+  timeoutMs: z.number().default(30_000),
+  disposeGraceMs: z.number().default(3_000),
+})
+
+/**
+ * Validate the resolved configuration before publishing the backend.
+ * @param config - Schemastery-resolved plugin configuration.
+ * @returns Nothing; success narrows every optional field to its resolved value.
+ */
+export function validateConfig(config: Config): asserts config is ResolvedConfig {
+  const resolved = config as ResolvedConfig
+  if (resolved.backendType.length === 0) throw new Error('pty-e2b: backendType must be non-empty')
+  for (const [name, value] of Object.entries(resolved)) {
+    if (typeof value === 'number' && (!Number.isSafeInteger(value) || value <= 0)) {
+      throw new Error(`pty-e2b: ${name} must be a positive safe integer`)
+    }
+  }
+  if (resolved.maxReadBytes > resolved.scrollbackMaxBytes) {
+    throw new Error('pty-e2b: maxReadBytes must not exceed scrollbackMaxBytes')
+  }
+}
+/* jscpd:ignore-end */
diff --git a/packages/pty/pty-e2b/src/index.ts b/packages/pty/pty-e2b/src/index.ts
new file mode 100644
index 0000000000..fca16cf5c7
--- /dev/null
+++ b/packages/pty/pty-e2b/src/index.ts
@@ -0,0 +1,93 @@
+/** E2B byte-PTY backend for persistent interactive terminal sessions. */
+
+import { posix } from 'node:path'
+import type { Context } from 'cordis'
+import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
+import { PtyBackendCleanupError } from '@deepseek-ai/dsh-pty'
+import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
+import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
+import { E2BPtySession } from './session.ts'
+
+export { Config } from './config.ts'
+export type { Config as PtyE2BConfig } from './config.ts'
+export { E2BPtySession } from './session.ts'
+
+/** Cordis plugin name. */
+export const name = 'pty-e2b'
+/** Required shared sandbox owner and PTY registry. */
+export const inject = ['e2b', 'pty']
+
+function terminalEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
+  return {
+    TERM: 'dumb',
+    PAGER: 'cat',
+    GIT_PAGER: 'cat',
+    PS1: 'dsh> ',
+    PROMPT_COMMAND: 'printf "\\033]133;D;%s\\007" "$?"',
+    BASH_SILENCE_DEPRECATION_WARNING: '1',
+    DSH_SHELL: '1',
+    DSH_SESSION_ID: spec.owner.id,
+    DSH_PTY_SESSION_ID: spec.sessionId,
+  }
+}
+
+/** E2B backend registered under the configured terminal type. */
+export class E2BPtyBackend implements PtyBackend {
+  readonly type: string
+
+  constructor(
+    private readonly ctx: Context,
+    private readonly config: ResolvedConfig,
+    private readonly createPty: (
+      sandbox: Sandbox,
+      options: Parameters<Sandbox['pty']['create']>[0],
+    ) => Promise<CommandHandle> = (sandbox, options) => sandbox.pty.create(options),
+  ) {
+    this.type = config.backendType
+  }
+
+  /** Create, initialize, and publish one remote PTY session. */
+  async spawn(spec: PtyBackendSpawnSpec): Promise<E2BPtySession> {
+    spec.signal?.throwIfAborted()
+    const sandbox = await this.ctx.e2b.getSandbox()
+    spec.signal?.throwIfAborted()
+    const pending: Uint8Array[] = []
+    const created: { session?: E2BPtySession } = {}
+    const handle = await this.createPty(sandbox, {
+      rows: this.config.rows,
+      cols: this.config.cols,
+      cwd: posix.resolve(this.ctx.e2b.cwd, spec.cwd ?? this.ctx.e2b.cwd),
+      envs: terminalEnvironment(spec),
+      timeoutMs: 0,
+      ...spec.signal === undefined ? {} : { signal: spec.signal },
+      onData: (data) => {
+        if (created.session === undefined) pending.push(Uint8Array.from(data))
+        else created.session.onData(data)
+      },
+    })
+    if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
+      await handle.kill().catch(() => false)
+      throw new Error(`pty-e2b: E2B returned invalid PTY pid ${handle.pid}`)
+    }
+    const session = new E2BPtySession(sandbox, handle, this.config)
+    created.session = session
+    for (const data of pending) session.onData(data)
+    try {
+      await session.initialize(spec.signal)
+      return session
+    } catch (error: unknown) {
+      try {
+        await session.close('E2B PTY startup failed')
+      } catch (cleanupError: unknown) {
+        throw new PtyBackendCleanupError(error, cleanupError)
+      }
+      throw error
+    }
+  }
+}
+
+/** Register the E2B PTY backend. */
+export function apply(ctx: Context, config: Config): void {
+  validateConfig(config)
+  ctx.pty.registerBackend(new E2BPtyBackend(ctx, config))
+}
diff --git a/packages/pty/pty-e2b/src/invariant.ts b/packages/pty/pty-e2b/src/invariant.ts
new file mode 100644
index 0000000000..b86fdffc5d
--- /dev/null
+++ b/packages/pty/pty-e2b/src/invariant.ts
@@ -0,0 +1,20 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-pty-e2b`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-pty-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'pty-e2b-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: the PTY registry owns publication and cleanup. */
+const install: InvariantInstaller = () => {}
+
+/** Register this package's invariant companion. */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/pty/pty-e2b/src/session.ts b/packages/pty/pty-e2b/src/session.ts
new file mode 100644
index 0000000000..e5dfc05efe
--- /dev/null
+++ b/packages/pty/pty-e2b/src/session.ts
@@ -0,0 +1,367 @@
+/** One byte-oriented E2B PTY session projected onto the harness PTY seam. */
+
+import { Buffer } from 'node:buffer'
+import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
+import { CommandExitError } from '@deepseek-ai/dsh-e2b'
+import {
+  PtyTerminalSanitizer,
+  PtyTextBuffer,
+  ptySignalName,
+  ptyUtf8Tail,
+} from '@deepseek-ai/dsh-pty'
+import type {
+  PtyBackendSession,
+  PtyReadRequest,
+  PtyReadResult,
+  PtySendOperation,
+  PtySendRead,
+  PtySendRequest,
+  PtySendResult,
+  PtySessionStatus,
+  PtySignal,
+  PtySignalResult,
+  PtyWaitReason,
+} from '@deepseek-ai/dsh-pty'
+import type { ResolvedConfig } from './config.ts'
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/* jscpd:ignore-start -- Operation state stays backend-local because process readiness and cleanup identities diverge. */
+class E2BSendOperation implements PtySendOperation {
+  private readonly output: PtyTextBuffer
+  private readonly result = Promise.withResolvers<PtySendResult>()
+  private finished = false
+
+  constructor(
+    maxBytes: number,
+    readonly startedAt: number,
+    private readonly onCancel: () => void,
+  ) {
+    this.output = new PtyTextBuffer(maxBytes)
+  }
+
+  get done(): Promise<PtySendResult> {
+    return this.result.promise
+  }
+
+  append(text: string): void {
+    if (!this.finished) this.output.append(text)
+  }
+
+  settle(waitReason: PtyWaitReason, sessionStatus: PtySessionStatus, inheritedTruncation: boolean): void {
+    if (this.finished) return
+    this.finished = true
+    const read = this.output.snapshot()
+    this.result.resolve({
+      viewport: read.text,
+      waitReason,
+      sessionStatus,
+      truncated: read.truncated || inheritedTruncation,
+    })
+  }
+
+  fail(error: unknown): void {
+    if (this.finished) return
+    this.finished = true
+    this.result.reject(error)
+  }
+
+  readOutput(): PtySendRead {
+    return this.output.consume()
+  }
+
+  cancel(): boolean {
+    if (this.finished) return false
+    this.onCancel()
+    return true
+  }
+}
+/* jscpd:ignore-end */
+
+/** Live session around one E2B SDK PTY handle. */
+export class E2BPtySession implements PtyBackendSession {
+  motd = ''
+  readonly pid: number
+  private readonly decoder = new TextDecoder('utf-8', { fatal: true })
+  private readonly sanitizer: PtyTerminalSanitizer
+  private readonly scrollback: PtyTextBuffer
+  private readonly exited = Promise.withResolvers<void>()
+  private statusValue: PtySessionStatus = { kind: 'running' }
+  private active: E2BSendOperation | undefined
+  private activeTimer: NodeJS.Timeout | undefined
+  private activeAbort: (() => void) | undefined
+  private promptSeen = false
+  private promptTextSeen = false
+  private initializing = false
+  private lastOutputAt = Date.now()
+  private closing = false
+  private closePromise: Promise<void> | undefined
+  private closeSignal: NodeJS.Signals | null = null
+  private transportFailure: Error | undefined
+  private remoteExited = false
+
+  constructor(
+    private readonly sandbox: Sandbox,
+    private readonly handle: CommandHandle,
+    private readonly config: ResolvedConfig,
+  ) {
+    this.pid = handle.pid
+    this.sanitizer = new PtyTerminalSanitizer(config.maxReadBytes)
+    this.scrollback = new PtyTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
+    const completion = handle.wait()
+    void completion.then(
+      (result) => { this.onExit(result.exitCode) },
+      (error: unknown) => {
+        if (error instanceof CommandExitError) this.onExit(error.exitCode)
+        else this.onTransportFailure(error)
+      },
+    )
+  }
+
+  /**
+   * Consume bytes received by the SDK's PTY callback.
+   * @param data - Exact callback bytes in delivery order.
+   */
+  onData(data: Uint8Array): void {
+    let decoded: string
+    try {
+      decoded = this.decoder.decode(data, { stream: true })
+    } catch (error: unknown) {
+      this.onTransportFailure(new Error('pty-e2b: PTY emitted invalid UTF-8', { cause: error }))
+      return
+    }
+    const sanitized = this.sanitizer.push(decoded)
+    this.appendOutput(sanitized.text)
+    if (sanitized.prompt) {
+      this.promptSeen = true
+      this.promptTextSeen = sanitized.promptText === true
+      this.lastOutputAt = Date.now()
+    } else if (this.promptSeen && sanitized.promptText === true) {
+      this.promptTextSeen = true
+    }
+  }
+
+  /**
+   * Await the first prompt or bounded startup fallback.
+   * @param signal - Optional startup cancellation signal.
+   */
+  async initialize(signal?: AbortSignal): Promise<void> {
+    this.initializing = true
+    try {
+      const operation = this.startSend({ text: '', submit: false, ...signal === undefined ? {} : { signal } })
+      const result = await operation.done
+      if (result.waitReason === 'session_exit') throw new Error('E2B PTY shell exited during startup')
+      if (result.waitReason === 'timeout') throw new Error('E2B PTY shell did not reach readiness before startup timeout')
+      this.motd = result.viewport
+    } catch (error: unknown) {
+      signal?.throwIfAborted()
+      throw error
+    } finally {
+      this.initializing = false
+    }
+  }
+
+  /* jscpd:ignore-start -- PTY backends share request admission while owning distinct input and readiness transports. */
+  startSend(request: PtySendRequest): PtySendOperation {
+    if (this.closing) throw new Error('E2B PTY session is closing')
+    if (this.statusValue.kind === 'exited') throw new Error('E2B PTY session has exited')
+    if (this.active !== undefined) throw new Error('E2B PTY session already has an active send')
+    if (request.signal?.aborted === true) throw new Error('E2B PTY send aborted before write')
+
+    const operation = new E2BSendOperation(
+      this.config.maxReadBytes,
+      Date.now(),
+      () => { this.interrupt(operation) },
+    )
+    this.active = operation
+    this.lastOutputAt = Date.now()
+    this.promptSeen = false
+    this.promptTextSeen = false
+    if (request.signal !== undefined) {
+      const onAbort = (): void => { operation.cancel() }
+      request.signal.addEventListener('abort', onAbort, { once: true })
+      this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
+    }
+
+    const input = `${request.text}${request.submit ? '\r' : ''}`
+    if (input.length > 0) {
+      void this.sandbox.pty.sendInput(this.pid, Buffer.from(input)).catch((error: unknown) => {
+        if (this.active === operation) this.failActive(error)
+      })
+    }
+    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
+    return operation
+  }
+  /* jscpd:ignore-end */
+
+  /* jscpd:ignore-start -- The seam requires identical bounded-read coordinates across backend buffers. */
+  read(request: PtyReadRequest): PtyReadResult {
+    const snapshot = this.scrollback.snapshot()
+    const lines = snapshot.text.split('\n')
+    const totalLines = snapshot.text.length === 0 ? 0 : lines.length
+    const offset = request.offset ?? 0
+    const count = request.count ?? 500
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('PTY read offset must be a non-negative safe integer')
+    if (!Number.isSafeInteger(count) || count <= 0) throw new Error('PTY read count must be a positive safe integer')
+    if (offset >= totalLines) {
+      return { text: '', totalLines, lineBegin: offset, lineEnd: offset, truncated: snapshot.truncated }
+    }
+    const end = totalLines - offset
+    const start = Math.max(0, end - count)
+    const bounded = ptyUtf8Tail(lines.slice(start, end).join('\n'), this.config.maxReadBytes)
+    const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split('\n').length
+    return {
+      text: bounded.text,
+      totalLines,
+      lineBegin: offset,
+      lineEnd: offset + returnedLines,
+      truncated: snapshot.truncated || bounded.truncated,
+    }
+  }
+  /* jscpd:ignore-end */
+
+  /* jscpd:ignore-start -- Signal, status, and close methods preserve the seam shape around remote identities. */
+  async signal(signal: PtySignal): Promise<PtySignalResult> {
+    const pgid = await this.foregroundPgid()
+    if (signal === 'SIGKILL' && pgid === this.pid) {
+      throw new Error('refusing to SIGKILL the E2B PTY shell; use terminal_close')
+    }
+    await this.sandbox.commands.run(`kill -${signal.slice(3)} -- -${pgid}`)
+    return { delivered: true, targetPgid: pgid }
+  }
+
+  status(): PtySessionStatus {
+    return this.statusValue
+  }
+
+  close(reason: string): Promise<void> {
+    this.closing = true
+    if (this.closePromise !== undefined) return this.closePromise
+    const closing = this.closeOnce(reason).catch((error: unknown) => {
+      this.closePromise = undefined
+      this.failActive(error)
+      throw error
+    })
+    this.closePromise = closing
+    return closing
+  }
+  /* jscpd:ignore-end */
+
+  private appendOutput(text: string): void {
+    if (text.length === 0) return
+    this.lastOutputAt = Date.now()
+    this.scrollback.append(text)
+    this.active?.append(text)
+  }
+
+  private pollReadiness(operation: E2BSendOperation): void {
+    if (this.active !== operation) return
+    if (this.statusValue.kind === 'exited') {
+      this.settleActive('session_exit')
+      return
+    }
+    const elapsed = Date.now() - operation.startedAt
+    const idleFor = Date.now() - this.lastOutputAt
+    if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs) {
+      this.settleActive('stdin_read')
+      return
+    }
+    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
+    if (startupHasOutput && idleFor >= this.config.idleSilenceMs) {
+      this.settleActive('inferred_idle')
+      return
+    }
+    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
+  }
+
+  private settleActive(waitReason: PtyWaitReason): void {
+    const operation = this.active
+    if (operation === undefined) return
+    const inherited = this.scrollback.snapshot().truncated
+    this.clearActive()
+    operation.settle(waitReason, this.statusValue, inherited)
+  }
+
+  private clearActive(): void {
+    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
+    this.activeTimer = undefined
+    this.activeAbort?.()
+    this.activeAbort = undefined
+    this.active = undefined
+  }
+
+  private failActive(error: unknown): void {
+    const operation = this.active
+    if (operation === undefined) return
+    this.clearActive()
+    operation.fail(error)
+  }
+
+  private interrupt(operation: E2BSendOperation): void {
+    if (this.active !== operation) return
+    void this.signal('SIGINT').catch((error: unknown) => { this.failActive(error) })
+  }
+
+  private async foregroundPgid(): Promise<number> {
+    const result = await this.sandbox.commands.run(`ps -o tpgid= -p ${this.pid}`)
+    const raw = result.stdout.trim()
+    const pgid = Number(raw)
+    if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(pgid)) {
+      throw new Error(`cannot resolve foreground process group for E2B PTY ${this.pid}`)
+    }
+    return pgid
+  }
+
+  private onExit(exitCode: number): void {
+    this.remoteExited = true
+    let tail = ''
+    try {
+      tail = this.decoder.decode()
+    } catch (error: unknown) {
+      this.transportFailure ??= new Error('pty-e2b: PTY ended with invalid UTF-8', { cause: error })
+    }
+    this.appendOutput(this.sanitizer.push(tail).text)
+    this.appendOutput(this.sanitizer.flush())
+    const inferredSignal = this.closeSignal ?? (exitCode > 128 ? ptySignalName(exitCode - 128) : null)
+    this.statusValue = {
+      kind: 'exited',
+      exitCode: inferredSignal === null ? exitCode : null,
+      signal: inferredSignal,
+    }
+    if (this.transportFailure === undefined) this.settleActive('session_exit')
+    else this.failActive(this.transportFailure)
+    this.exited.resolve()
+  }
+
+  private onTransportFailure(error: unknown): void {
+    const failure = error instanceof Error ? error : new Error(String(error))
+    this.transportFailure ??= failure
+    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
+    this.failActive(failure)
+  }
+
+  private async closeOnce(reason: string): Promise<void> {
+    if (!this.remoteExited) {
+      this.closeSignal = 'SIGTERM'
+      try {
+        await this.sandbox.commands.run(`kill -TERM -- -${this.pid}`)
+      } catch (error: unknown) {
+        if (!(error instanceof CommandExitError)) throw error
+      }
+      await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (!this.remoteExited) {
+      this.closeSignal = 'SIGKILL'
+      await this.sandbox.pty.kill(this.pid)
+      await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (!this.remoteExited) {
+      throw new Error(`E2B PTY cleanup failed (${reason}); surviving pid: ${this.pid}`)
+    }
+    this.settleActive('session_exit')
+    await this.handle.disconnect().catch(() => {})
+    if (this.transportFailure !== undefined) throw this.transportFailure
+  }
+}
diff --git a/packages/pty/pty-e2b/tests/index.spec.ts b/packages/pty/pty-e2b/tests/index.spec.ts
new file mode 100644
index 0000000000..567b3b9215
--- /dev/null
+++ b/packages/pty/pty-e2b/tests/index.spec.ts
@@ -0,0 +1,195 @@
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import PtyService, { PtyBackendCleanupError, PtySessionId } from '@deepseek-ai/dsh-pty'
+import { E2BPtyBackend, apply } from '@deepseek-ai/dsh-pty-e2b'
+import { validateConfig } from '@deepseek-ai/dsh-pty-e2b/src/config.ts'
+import * as E2BPtyInvariant from '../src/invariant.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import { AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+
+function config() {
+  return {
+    backendType: 'shell', rows: 24, cols: 80,
+    scrollbackLines: 10, scrollbackMaxBytes: 128, maxReadBytes: 64,
+    pollIntervalMs: 1, idleSilenceMs: 2, timeoutMs: 5, disposeGraceMs: 1,
+  }
+}
+
+function owner(ctx: Context): Agent {
+  const id = SessionId('owner')
+  return {
+    id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx,
+    followup: () => AgentMessageId('unused'), steer: () => AgentMessageId('unused'),
+    inject: () => AgentMessageId('unused'), send: () => AgentMessageId('unused'),
+    cancel() {}, whenIdle: () => Promise.resolve(),
+  }
+}
+
+function handle(pid = 123, kill = vi.fn().mockResolvedValue(true)): CommandHandle {
+  const result = Promise.withResolvers<{ exitCode: number; stdout: string; stderr: string }>()
+  return {
+    pid,
+    wait: () => result.promise,
+    kill,
+    disconnect: vi.fn().mockResolvedValue(undefined),
+  } as unknown as CommandHandle
+}
+
+describe('E2BPtyBackend and plugin', () => {
+  it('creates a remote PTY with isolated environment and initializes the session', async () => {
+    vi.useFakeTimers()
+    const ctx = new Context()
+    const sandbox = {} as Sandbox
+    ctx.provide('e2b', {
+      cwd: '/workspace',
+      getSandbox: async () => sandbox,
+    } as E2BSandboxService)
+    const created = handle()
+    let options: Parameters<Sandbox['pty']['create']>[0] | undefined
+    const backend = new E2BPtyBackend(ctx, config(), async (_sandbox, received) => {
+      options = received
+      void received.onData(Buffer.from('banner\n'))
+      setTimeout(() => { void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> ')) }, 0)
+      return created
+    })
+    const pending = backend.spawn({
+      sessionId: PtySessionId('pty-1'), owner: owner(ctx), type: 'shell', cwd: 'project',
+      signal: new AbortController().signal,
+    })
+    await vi.advanceTimersByTimeAsync(2)
+    const session = await pending
+
+    expect(session.motd).toBe('dsh> ')
+    expect(options).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace/project', timeoutMs: 0 })
+    expect(options?.envs).toMatchObject({
+      TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ',
+      DSH_SHELL: '1', DSH_SESSION_ID: 'owner', DSH_PTY_SESSION_ID: 'pty-1',
+    })
+    vi.useRealTimers()
+  })
+
+  it('uses the SDK PTY create method and the shared cwd by default', async () => {
+    vi.useFakeTimers()
+    const ctx = new Context()
+    const created = handle()
+    const create = vi.fn(async (received: Parameters<Sandbox['pty']['create']>[0]) => {
+      setTimeout(() => { void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> ')) }, 0)
+      return created
+    })
+    const sandbox = { pty: { create } } as unknown as Sandbox
+    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as unknown as E2BSandboxService)
+    const backend = new E2BPtyBackend(ctx, config())
+    const pending = backend.spawn({ sessionId: PtySessionId('default'), owner: owner(ctx), type: 'shell' })
+    await vi.advanceTimersByTimeAsync(2)
+    await pending
+    expect(create).toHaveBeenCalledWith(expect.objectContaining({ cwd: '/workspace' }))
+    vi.useRealTimers()
+  })
+
+  it('rejects aborts and invalid pids, killing a malformed SDK handle', async () => {
+    const ctx = new Context()
+    const sandbox = {} as Sandbox
+    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
+    const create = vi.fn().mockResolvedValue(handle(0))
+    const backend = new E2BPtyBackend(ctx, config(), create)
+    const aborted = AbortSignal.abort(new Error('stop'))
+    await expect(backend.spawn({ sessionId: PtySessionId('one'), owner: owner(ctx), type: 'shell', signal: aborted })).rejects.toThrow('stop')
+    expect(create).not.toHaveBeenCalled()
+
+    const malformedKill = vi.fn().mockResolvedValue(true)
+    const malformed = handle(0, malformedKill)
+    const invalid = new E2BPtyBackend(ctx, config(), async () => malformed)
+    await expect(invalid.spawn({ sessionId: PtySessionId('two'), owner: owner(ctx), type: 'shell' })).rejects.toThrow('invalid PTY pid')
+    expect(malformedKill).toHaveBeenCalledOnce()
+
+    const killFailureKill = vi.fn().mockRejectedValue(new Error('already gone'))
+    const killFailure = handle(0, killFailureKill)
+    const raced = new E2BPtyBackend(ctx, config(), async () => killFailure)
+    await expect(raced.spawn({ sessionId: PtySessionId('three'), owner: owner(ctx), type: 'shell' })).rejects.toThrow('invalid PTY pid')
+  })
+
+  it('cleans failed startup and aggregates a cleanup failure', async () => {
+    vi.useFakeTimers()
+    const ctx = new Context()
+    const sandbox = {
+      commands: { run: vi.fn().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }) },
+      pty: { kill: vi.fn().mockRejectedValue(new Error('cleanup failed')) },
+    } as unknown as Sandbox
+    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
+    const failedHandle = handle()
+    const backend = new E2BPtyBackend(ctx, config(), async () => failedHandle)
+    const pending = backend.spawn({ sessionId: PtySessionId('failed'), owner: owner(ctx), type: 'shell' })
+    const rejected = expect(pending).rejects.toMatchObject({
+      name: 'PtyBackendCleanupError',
+      cleanupError: expect.objectContaining({ message: 'cleanup failed' }),
+    } satisfies Partial<PtyBackendCleanupError>)
+    await vi.advanceTimersByTimeAsync(6)
+    await vi.advanceTimersByTimeAsync(2)
+    await rejected
+    vi.useRealTimers()
+  })
+
+  it('preserves startup failure when cleanup succeeds', async () => {
+    vi.useFakeTimers()
+    const ctx = new Context()
+    const completion = Promise.withResolvers<{ exitCode: number; stdout: string; stderr: string }>()
+    const created = {
+      pid: 123,
+      wait: () => completion.promise,
+      disconnect: vi.fn().mockResolvedValue(undefined),
+    } as unknown as CommandHandle
+    const sandbox = {
+      commands: {
+        run: vi.fn(async (command: string) => {
+          if (command.startsWith('kill -TERM')) completion.resolve({ exitCode: 143, stdout: '', stderr: '' })
+          return { exitCode: 0, stdout: '', stderr: '' }
+        }),
+      },
+      pty: { kill: vi.fn().mockResolvedValue(true) },
+    } as unknown as Sandbox
+    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as unknown as E2BSandboxService)
+    const backend = new E2BPtyBackend(ctx, config(), async () => created)
+    const rejected = expect(backend.spawn({ sessionId: PtySessionId('failed-clean'), owner: owner(ctx), type: 'shell' }))
+      .rejects.toThrow('startup timeout')
+    await vi.advanceTimersByTimeAsync(6)
+    await rejected
+    vi.useRealTimers()
+  })
+
+  it('validates configuration and registers the selected backend type', async () => {
+    const valid = config()
+    expect(() => { validateConfig(valid) }).not.toThrow()
+    for (const invalid of [
+      { ...valid, backendType: '' },
+      { ...valid, rows: 0 },
+      { ...valid, rows: 1.5 },
+      { ...valid, maxReadBytes: 129 },
+    ]) {
+      expect(() => { validateConfig(invalid) }).toThrow()
+    }
+
+    const registerBackend = vi.fn()
+    apply({ pty: { registerBackend } } as unknown as Context, valid)
+    expect(registerBackend).toHaveBeenCalledWith(expect.objectContaining({ type: 'shell' }))
+
+    const ctx = new Context()
+    await ctx.plugin(PtyService)
+    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => ({}) } as never)
+    const fiber = await ctx.plugin({
+      inject: ['pty', 'e2b'],
+      apply: (pluginCtx: Context) => { apply(pluginCtx, valid) },
+    })
+    expect(ctx.pty.listBackends()).toEqual(['shell'])
+    await fiber.dispose()
+  })
+
+  it('registers the package-owned invariant companion', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BPtyInvariant).await()
+    await fiber.dispose()
+  })
+})
diff --git a/packages/pty/pty-e2b/tests/session.spec.ts b/packages/pty/pty-e2b/tests/session.spec.ts
new file mode 100644
index 0000000000..6dced22ed2
--- /dev/null
+++ b/packages/pty/pty-e2b/tests/session.spec.ts
@@ -0,0 +1,398 @@
+import { Buffer } from 'node:buffer'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  CommandExitError,
+  type CommandHandle,
+  type CommandResult,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type { PtySendOperation, PtySessionStatus } from '@deepseek-ai/dsh-pty'
+import { E2BPtySession } from '@deepseek-ai/dsh-pty-e2b'
+import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-e2b/src/config.ts'
+
+function commandError(exitCode: number): CommandExitError {
+  return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
+}
+
+class FakePtyHandle {
+  pid = 123
+  readonly result = Promise.withResolvers<CommandResult>()
+  disconnects = 0
+  kills = 0
+  disconnectError: unknown
+  private settled = false
+
+  wait(): Promise<CommandResult> {
+    return this.result.promise
+  }
+
+  async disconnect(): Promise<void> {
+    this.disconnects += 1
+    if (this.disconnectError !== undefined) throw this.disconnectError
+  }
+
+  async kill(): Promise<boolean> {
+    this.kills += 1
+    return true
+  }
+
+  exit(exitCode = 0): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.resolve({ exitCode, stdout: '', stderr: '' })
+  }
+
+  failExit(exitCode: number): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(commandError(exitCode))
+  }
+
+  crash(error: unknown): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(error)
+  }
+
+  asHandle(): CommandHandle {
+    return this as unknown as CommandHandle
+  }
+}
+
+class FakeSandbox {
+  readonly sent: Array<{ pid: number; data: Buffer }> = []
+  readonly commands: string[] = []
+  readonly killed: number[] = []
+  pgid = '456\n'
+  sendError: unknown
+  commandError: unknown
+  killError: unknown
+  onTerm: (() => void) | undefined
+  onKill: (() => void) | undefined
+
+  readonly sandbox = {
+    pty: {
+      sendInput: async (pid: number, data: Uint8Array): Promise<void> => {
+        this.sent.push({ pid, data: Buffer.from(data) })
+        if (this.sendError !== undefined) throw this.sendError
+      },
+      kill: async (pid: number): Promise<boolean> => {
+        this.killed.push(pid)
+        if (this.killError !== undefined) throw this.killError
+        this.onKill?.()
+        return true
+      },
+    },
+    commands: {
+      run: async (command: string): Promise<CommandResult> => {
+        this.commands.push(command)
+        if (this.commandError !== undefined) {
+          const error = this.commandError
+          this.commandError = undefined
+          throw error
+        }
+        if (command.startsWith('ps ')) return { exitCode: 0, stdout: this.pgid, stderr: '' }
+        if (command.startsWith('kill -TERM')) this.onTerm?.()
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+  } as unknown as Sandbox
+}
+
+function config(overrides: Partial<ResolvedConfig> = {}): ResolvedConfig {
+  return {
+    backendType: 'shell', rows: 24, cols: 80,
+    scrollbackLines: 10, scrollbackMaxBytes: 128, maxReadBytes: 64,
+    pollIntervalMs: 10, idleSilenceMs: 40, timeoutMs: 100, disposeGraceMs: 20,
+    ...overrides,
+  }
+}
+
+async function initialize(session: E2BPtySession): Promise<void> {
+  const pending = session.initialize()
+  session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+  await vi.advanceTimersByTimeAsync(10)
+  await pending
+}
+
+afterEach(() => { vi.useRealTimers() })
+
+describe('E2BPtySession readiness, output, and signals', () => {
+  it('initializes, sends UTF-8 input, settles at a prompt, and reads bounded scrollback', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config({ maxReadBytes: 12 }))
+    expect(session.read({})).toMatchObject({ text: '', totalLines: 0 })
+    await initialize(session)
+    expect(session.motd).toBe('dsh> ')
+
+    const operation = session.startSend({ text: 'printf 你好', submit: true })
+    expect(fake.sent).toEqual([{ pid: 123, data: Buffer.from('printf 你好\r') }])
+    session.onData(Buffer.from('一\n二\n三\x1b]133;D;0\x07dsh> '))
+    const bounded = operation.readOutput()
+    expect(bounded.delta).toContain('三')
+    expect(bounded.truncated).toBe(true)
+    await vi.advanceTimersByTimeAsync(10)
+    expect(await operation.done).toMatchObject({ waitReason: 'stdin_read', sessionStatus: { kind: 'running' } })
+    expect(operation.cancel()).toBe(false)
+    expect(session.read({ count: 2 }).text).toContain('dsh>')
+    expect(session.read({ offset: 99 })).toMatchObject({ text: '', lineBegin: 99, lineEnd: 99 })
+    expect(() => session.read({ offset: -1 })).toThrow('non-negative safe integer')
+    expect(() => session.read({ offset: 1.5 })).toThrow('non-negative safe integer')
+    expect(() => session.read({ count: 0 })).toThrow('positive safe integer')
+    expect(() => session.read({ count: 1.5 })).toThrow('positive safe integer')
+
+    await expect(session.signal('SIGTERM')).resolves.toEqual({ delivered: true, targetPgid: 456 })
+    expect(fake.commands).toContain('kill -TERM -- -456')
+    expect(session.status()).toEqual({ kind: 'running' })
+  })
+
+  it('distinguishes inferred idle, timeout, session exit, and no-output startup timeout', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    await initialize(session)
+
+    const inferred = session.startSend({ text: '', submit: false })
+    await vi.advanceTimersByTimeAsync(40)
+    expect((await inferred.done).waitReason).toBe('inferred_idle')
+
+    const timeout = session.startSend({ text: '', submit: false })
+    for (let index = 0; index < 3; index += 1) {
+      await vi.advanceTimersByTimeAsync(30)
+      session.onData(Buffer.from('.'))
+    }
+    await vi.advanceTimersByTimeAsync(10)
+    expect((await timeout.done).waitReason).toBe('timeout')
+
+    const exiting = session.startSend({ text: '', submit: false })
+    handle.failExit(143)
+    expect(await exiting.done).toMatchObject({
+      waitReason: 'session_exit',
+      sessionStatus: { kind: 'exited', exitCode: null, signal: 'SIGTERM' },
+    })
+    expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
+
+    const startupHandle = new FakePtyHandle()
+    const startup = new E2BPtySession(fake.sandbox, startupHandle.asHandle(), config())
+    const timedOut = expect(startup.initialize()).rejects.toThrow('startup timeout')
+    await vi.advanceTimersByTimeAsync(100)
+    await timedOut
+  })
+
+  it('handles split prompt text, stale operations, and explicit cancellation', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const initializing = session.initialize()
+    session.onData(Buffer.from('\x1b]133;D;0\x07'))
+    await vi.advanceTimersByTimeAsync(20)
+    session.onData(Buffer.from('dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await initializing
+
+    const operation = session.startSend({ text: 'sleep', submit: true })
+    const internal = session as unknown as {
+      pollReadiness(operation: PtySendOperation): void
+      interrupt(operation: PtySendOperation): void
+      settleActive(reason: 'timeout'): void
+      failActive(error: unknown): void
+      appendOutput(text: string): void
+      statusValue: PtySessionStatus
+    }
+    internal.pollReadiness({} as PtySendOperation)
+    internal.interrupt({} as PtySendOperation)
+    internal.appendOutput('')
+    fake.pgid = '789\n'
+    expect(operation.cancel()).toBe(true)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(fake.commands).toContain('kill -INT -- -789')
+    session.onData(Buffer.from('\x1b]133;D;130\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await operation.done
+
+    internal.settleActive('timeout')
+    internal.failActive(new Error('ignored'))
+    const operationInternal = operation as unknown as {
+      append(text: string): void
+      settle(reason: 'timeout', status: PtySessionStatus, inherited: boolean): void
+      fail(error: unknown): void
+    }
+    operationInternal.append('ignored')
+    operationInternal.settle('timeout', { kind: 'running' }, false)
+    operationInternal.fail(new Error('ignored'))
+  })
+
+  it('observes AbortSignal and contains send or foreground lookup failures', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    await initialize(session)
+
+    const controller = new AbortController()
+    const aborting = session.startSend({ text: '', submit: false, signal: controller.signal })
+    expect(() => session.startSend({ text: '', submit: false })).toThrow('active send')
+    fake.pgid = 'not-a-pgid\n'
+    controller.abort()
+    await expect(aborting.done).rejects.toThrow('cannot resolve foreground process group')
+
+    const already = new AbortController()
+    already.abort()
+    expect(() => session.startSend({ text: '', submit: false, signal: already.signal })).toThrow('aborted before write')
+
+    fake.sendError = new Error('send failed')
+    const failed = session.startSend({ text: 'x', submit: false })
+    await expect(failed.done).rejects.toThrow('send failed')
+
+    fake.pgid = '123\n'
+    await expect(session.signal('SIGKILL')).rejects.toThrow('refusing to SIGKILL')
+    fake.pgid = '0\n'
+    await expect(session.signal('SIGINT')).rejects.toThrow('cannot resolve')
+
+    const deferred = Promise.withResolvers<undefined>()
+    fake.sendError = undefined
+    const sendInput = vi.spyOn(fake.sandbox.pty, 'sendInput').mockReturnValueOnce(deferred.promise)
+    const late = session.startSend({ text: 'late', submit: false })
+    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await late.done
+    deferred.reject(new Error('late failure'))
+    await vi.advanceTimersByTimeAsync(0)
+    expect(sendInput).toHaveBeenCalled()
+  })
+
+  it('preserves startup abort reasons and classifies invalid UTF-8 transport failures', async () => {
+    const fake = new FakeSandbox()
+    const abortHandle = new FakePtyHandle()
+    const abortSession = new E2BPtySession(fake.sandbox, abortHandle.asHandle(), config())
+    const controller = new AbortController()
+    const reason = new Error('startup cancelled')
+    const initializing = abortSession.initialize(controller.signal)
+    const rejected = expect(initializing).rejects.toBe(reason)
+    controller.abort(reason)
+    await rejected
+
+    const invalidHandle = new FakePtyHandle()
+    const invalid = new E2BPtySession(fake.sandbox, invalidHandle.asHandle(), config())
+    const pending = invalid.startSend({ text: '', submit: false })
+    invalid.onData(Uint8Array.from([0xff]))
+    await expect(pending.done).rejects.toThrow('invalid UTF-8')
+    expect(invalid.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+
+    const crashHandle = new FakePtyHandle()
+    const crashed = new E2BPtySession(fake.sandbox, crashHandle.asHandle(), config())
+    const active = crashed.startSend({ text: '', submit: false })
+    crashHandle.crash('transport gone')
+    await expect(active.done).rejects.toEqual(new Error('transport gone'))
+
+    const startupExitHandle = new FakePtyHandle()
+    const startupExit = new E2BPtySession(fake.sandbox, startupExitHandle.asHandle(), config())
+    const exitedDuringStartup = expect(startupExit.initialize()).rejects.toThrow('exited during startup')
+    startupExitHandle.exit(7)
+    await exitedDuringStartup
+  })
+
+  it('covers empty bounded reads and polling an exited active session', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const tinyHandle = new FakePtyHandle()
+    const tiny = new E2BPtySession(fake.sandbox, tinyHandle.asHandle(), config({ maxReadBytes: 1 }))
+    tiny.onData(Buffer.from('你'))
+    expect(tiny.read({ count: 1 })).toMatchObject({ text: '', lineEnd: 0 })
+
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const operation = session.startSend({ text: '', submit: false })
+    const internal = session as unknown as {
+      pollReadiness(operation: PtySendOperation): void
+      clearActive(): void
+      statusValue: PtySessionStatus
+    }
+    internal.statusValue = { kind: 'exited', exitCode: 7, signal: null }
+    internal.pollReadiness(operation)
+    expect((await operation.done).waitReason).toBe('session_exit')
+    internal.clearActive()
+  })
+})
+
+describe('E2BPtySession teardown', () => {
+  it('terminates the process group once, awaits exit, and disconnects', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    fake.onTerm = () => { handle.failExit(143) }
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const first = session.close('done')
+    expect(session.close('again')).toBe(first)
+    await first
+    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: 'SIGTERM' })
+    expect(handle.disconnects).toBe(1)
+    expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
+  })
+
+  it('contains an already-gone TERM, escalates to KILL, and reports a survivor', async () => {
+    vi.useFakeTimers()
+    const gone = new FakeSandbox()
+    const goneHandle = new FakePtyHandle()
+    gone.commandError = commandError(1)
+    gone.onKill = () => { goneHandle.failExit(137) }
+    const goneSession = new E2BPtySession(gone.sandbox, goneHandle.asHandle(), config())
+    const closingGone = goneSession.close('gone')
+    await vi.advanceTimersByTimeAsync(20)
+    await closingGone
+    expect(gone.killed).toEqual([123])
+    expect(goneSession.status()).toEqual({ kind: 'exited', exitCode: null, signal: 'SIGKILL' })
+
+    const survivor = new FakeSandbox()
+    const survivorHandle = new FakePtyHandle()
+    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), config())
+    const failed = expect(survivorSession.close('still alive')).rejects.toThrow('surviving pid: 123')
+    await vi.advanceTimersByTimeAsync(40)
+    await failed
+    survivorHandle.exit()
+    await expect(survivorSession.close('retry')).resolves.toBeUndefined()
+  })
+
+  it('propagates cleanup transport failures and lets close retry', async () => {
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    fake.commandError = new Error('TERM transport failed')
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    await expect(session.close('failure')).rejects.toThrow('TERM transport failed')
+    handle.exit()
+    await expect(session.close('retry')).resolves.toBeUndefined()
+
+    const invalidTailHandle = new FakePtyHandle()
+    const invalidTail = new E2BPtySession(fake.sandbox, invalidTailHandle.asHandle(), config())
+    invalidTail.onData(Uint8Array.from([0xe2]))
+    invalidTailHandle.exit()
+    await expect(invalidTail.close('invalid tail')).rejects.toThrow('invalid UTF-8')
+
+    const normalHandle = new FakePtyHandle()
+    normalHandle.disconnectError = new Error('disconnect raced')
+    const normal = new E2BPtySession(fake.sandbox, normalHandle.asHandle(), config())
+    normalHandle.exit(7)
+    await Promise.resolve()
+    expect(normal.status()).toEqual({ kind: 'exited', exitCode: 7, signal: null })
+    await expect(normal.close('already exited')).resolves.toBeUndefined()
+  })
+
+  it('kills a remotely live PTY after its host transport fails', async () => {
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const active = session.startSend({ text: '', submit: false })
+    session.onData(Uint8Array.from([0xff]))
+    await expect(active.done).rejects.toThrow('invalid UTF-8')
+    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
+
+    fake.onTerm = () => { handle.failExit(143) }
+    await expect(session.close('transport failed')).rejects.toThrow('invalid UTF-8')
+    expect(fake.commands).toContain('kill -TERM -- -123')
+    expect(handle.disconnects).toBe(1)
+  })
+})
diff --git a/packages/pty/pty-e2b/tsconfig.json b/packages/pty/pty-e2b/tsconfig.json
new file mode 100644
index 0000000000..0a7647aa80
--- /dev/null
+++ b/packages/pty/pty-e2b/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../e2b/e2b" },
+    { "path": "../pty" },
+    { "path": "../../support/invariants" }
+  ]
+}
diff --git a/packages/pty/pty-local/src/sanitize.ts b/packages/pty/pty-local/src/sanitize.ts
deleted file mode 100644
index 1f28315fb1..0000000000
--- a/packages/pty/pty-local/src/sanitize.ts
+++ /dev/null
@@ -1,188 +0,0 @@
-/** Streaming terminal-control sanitizer for the line-oriented first release. */
-
-import { Buffer } from 'node:buffer'
-
-/** OSC marker emitted by the controlled bash before each prompt. */
-export const PROMPT_MARKER_PREFIX = '133;D;'
-
-/** Exact printable prompt emitted after the private marker. */
-export const CONTROLLED_PROMPT = 'dsh> '
-
-/** One sanitized chunk plus whether it contained the owned prompt marker. */
-export interface SanitizedChunk {
-  text: string
-  prompt: boolean
-  /** Printable text after the latest owned marker in this chunk. */
-  promptTail?: string
-}
-
-/**
- * Remove CSI/OSC/short escape sequences while preserving split-sequence carry.
- * Full terminal emulation is deliberately deferred; ordinary line output and
- * the private prompt marker are the supported contract.
- */
-export class TerminalSanitizer {
-  private pending = ''
-  private discardMode: 'osc' | 'csi' | undefined
-  private discardOscEscape = false
-  private trailingCarriageReturn = false
-  private trackingPromptTail = false
-
-  constructor(private readonly maxPendingBytes: number) {}
-
-  /**
-   * Consume one decoded `node-pty` data chunk.
-   * @param chunk - decoded terminal data.
-   * @returns Printable text and whether the private prompt marker completed.
-   */
-  push(chunk: string): SanitizedChunk {
-    this.pending += this.discardPrefix(chunk)
-    let text = ''
-    let prompt = false
-    let includePromptTail = this.trackingPromptTail
-    let promptTail = ''
-    let index = 0
-    const appendText = (value: string): void => {
-      text += value
-      if (this.trackingPromptTail) promptTail += value
-    }
-    while (index < this.pending.length) {
-      const escape = this.pending.indexOf('\x1b', index)
-      if (escape < 0) {
-        appendText(this.pending.slice(index))
-        index = this.pending.length
-        break
-      }
-      appendText(this.pending.slice(index, escape))
-      if (escape + 1 >= this.pending.length) {
-        index = escape
-        break
-      }
-      const kind = this.pending[escape + 1]
-      if (kind === ']') {
-        const bel = this.pending.indexOf('\x07', escape + 2)
-        const stringTerminator = this.pending.indexOf('\x1b\\', escape + 2)
-        let end = -1
-        if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2)
-        else if (bel >= 0) end = bel + 1
-        else if (stringTerminator >= 0) end = stringTerminator + 2
-        if (end < 0) {
-          index = escape
-          break
-        }
-        const terminatorBytes = this.pending[end - 1] === '\x07' ? 1 : 2
-        const content = this.pending.slice(escape + 2, end - terminatorBytes)
-        if (content.startsWith(PROMPT_MARKER_PREFIX)) {
-          prompt = true
-          this.trackingPromptTail = true
-          includePromptTail = true
-          promptTail = ''
-        }
-        index = end
-        continue
-      }
-      if (kind === '[') {
-        let end = escape + 2
-        while (end < this.pending.length) {
-          const code = this.pending.charCodeAt(end)
-          if (code >= 0x40 && code <= 0x7e) break
-          end += 1
-        }
-        if (end >= this.pending.length) {
-          index = escape
-          break
-        }
-        index = end + 1
-        continue
-      }
-      // Two-byte escape family (save/restore cursor and similar).
-      index = escape + 2
-    }
-    this.pending = this.pending.slice(index)
-    this.enforcePendingBound()
-    return {
-      text: this.normalizeText(text),
-      prompt,
-      ...includePromptTail ? { promptTail } : {},
-    }
-  }
-
-  /**
-   * Flush a trailing printable fragment when the PTY exits.
-   * @returns Remaining printable text; incomplete escapes are discarded.
-   */
-  flush(): string {
-    const text = this.pending.startsWith('\x1b') ? '' : this.pending
-    this.pending = ''
-    this.discardMode = undefined
-    this.discardOscEscape = false
-    this.trackingPromptTail = false
-    const normalized = this.normalizeText(text)
-    if (!this.trailingCarriageReturn) return normalized
-    this.trailingCarriageReturn = false
-    return `${normalized}\n`
-  }
-
-  private normalizeText(text: string): string {
-    let complete = this.trailingCarriageReturn ? `\r${text}` : text
-    this.trailingCarriageReturn = false
-    if (complete.endsWith('\r')) {
-      complete = complete.slice(0, -1)
-      this.trailingCarriageReturn = true
-    }
-    return normalizeTerminalText(complete)
-  }
-
-  private enforcePendingBound(): void {
-    if (Buffer.byteLength(this.pending) <= this.maxPendingBytes) return
-    this.discardMode = this.pending[1] === ']' ? 'osc' : 'csi'
-    this.pending = ''
-  }
-
-  private discardPrefix(chunk: string): string {
-    if (this.discardMode === undefined) return chunk
-    if (this.discardMode === 'csi') {
-      for (let index = 0; index < chunk.length; index += 1) {
-        const code = chunk.charCodeAt(index)
-        if (code >= 0x40 && code <= 0x7e) {
-          this.discardMode = undefined
-          return chunk.slice(index + 1)
-        }
-      }
-      return ''
-    }
-
-    let index = 0
-    if (this.discardOscEscape) {
-      this.discardOscEscape = false
-      if (chunk.startsWith('\\')) {
-        this.discardMode = undefined
-        return chunk.slice(1)
-      }
-    }
-    while (index < chunk.length) {
-      if (chunk[index] === '\x07') {
-        this.discardMode = undefined
-        return chunk.slice(index + 1)
-      }
-      if (chunk[index] === '\x1b') {
-        if (chunk[index + 1] === '\\') {
-          this.discardMode = undefined
-          return chunk.slice(index + 2)
-        }
-        if (index + 1 === chunk.length) this.discardOscEscape = true
-      }
-      index += 1
-    }
-    return ''
-  }
-}
-
-/**
- * Normalize CRLF and standalone carriage returns for line-oriented rendering.
- * @param text - sanitized terminal text.
- * @returns Line-normalized text with BEL removed.
- */
-export function normalizeTerminalText(text: string): string {
-  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n').replaceAll('\x07', '')
-}
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index 25ed8fe586..ebf6b559d1 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -1,12 +1,7 @@
-/** Persistent PTY session over the subprocess seam's terminal primitive. */
+/** Local `node-pty` session: bounded output, readiness, signals, and teardown. */
 
-import { Buffer } from 'node:buffer'
-import type {
-  SubprocessOutcome,
-  SubprocessTerminalForeground,
-  SubprocessTerminalHandle,
-} from '@deepseek-ai/dsh-subprocess'
-import { PtyError } from '@deepseek-ai/dsh-pty'
+import type { IDisposable, IPty } from 'node-pty'
+import { PtyTerminalSanitizer, PtyTextBuffer, ptySignalName, ptyUtf8Tail } from '@deepseek-ai/dsh-pty'
 import type {
   PtyBackendSession,
   PtyReadRequest,
@@ -21,89 +16,30 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import { CONTROLLED_PROMPT, TerminalSanitizer } from './sanitize.ts'
+import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
 
-function utf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
-  if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
-  const chars = Array.from(text)
-  let bytes = 0
-  let start = chars.length
-  while (start > 0) {
-    const next = Buffer.byteLength(chars[start - 1] as string)
-    if (bytes + next > maxBytes) break
-    bytes += next
-    start -= 1
-  }
-  return { text: chars.slice(start).join(''), truncated: true }
-}
-
-class BoundedTextBuffer {
-  private value = ''
-  private dropped = false
-
-  constructor(
-    private readonly maxBytes: number,
-    private readonly maxLines?: number,
-  ) {}
-
-  append(text: string): void {
-    if (text.length === 0) return
-    this.value += text
-    if (this.maxLines !== undefined) {
-      const lines = this.value.split('\n')
-      if (lines.length > this.maxLines) {
-        this.value = lines.slice(lines.length - this.maxLines).join('\n')
-        this.dropped = true
-      }
-    }
-    const tail = utf8Tail(this.value, this.maxBytes)
-    this.value = tail.text
-    this.dropped ||= tail.truncated
-  }
-
-  consume(): PtySendRead {
-    const delta = this.value
-    const truncated = this.dropped
-    this.value = ''
-    this.dropped = false
-    return { delta, truncated }
-  }
-
-  snapshot(): { text: string; truncated: boolean } {
-    return { text: this.value, truncated: this.dropped }
-  }
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
 }
 
 class LocalSendOperation implements PtySendOperation {
-  private readonly output: BoundedTextBuffer
+  private readonly output: PtyTextBuffer
   private readonly promise: PromiseWithResolvers<PtySendResult>
   private finished = false
-  private cancellationRequested = false
-  private initialForegroundLeftWait: boolean
-  private initialForegroundPgid: number | undefined
 
   constructor(
     maxBytes: number,
     readonly startedAt: number,
     private readonly onCancel: () => void,
   ) {
-    this.output = new BoundedTextBuffer(maxBytes)
+    this.output = new PtyTextBuffer(maxBytes)
     this.promise = Promise.withResolvers<PtySendResult>()
-    this.initialForegroundLeftWait = true
   }
 
   get done(): Promise<PtySendResult> {
     return this.promise.promise
   }
 
-  get settled(): boolean {
-    return this.finished
-  }
-
-  get cancelRequested(): boolean {
-    return this.cancellationRequested
-  }
-
   append(text: string): void {
     if (!this.finished) this.output.append(text)
   }
@@ -130,75 +66,50 @@ class LocalSendOperation implements PtySendOperation {
     return this.output.consume()
   }
 
-  setInitialForeground(foreground: SubprocessTerminalForeground | undefined): void {
-    this.initialForegroundPgid = foreground?.processGroupId
-    this.initialForegroundLeftWait = foreground?.inputWaiting !== true
-  }
-
-  acceptsStdinWait(pgid: number, waiting: boolean): boolean {
-    // The same group may still expose the wait that existed before terminal.write.
-    // Observe every poll so a departure before the exact-settlement threshold
-    // still makes a later return to that wait post-write evidence.
-    if (pgid !== this.initialForegroundPgid) return waiting
-    if (!waiting) this.initialForegroundLeftWait = true
-    return waiting && this.initialForegroundLeftWait
-  }
-
   cancel(): boolean {
     if (this.finished) return false
-    this.cancellationRequested = true
     this.onCancel()
     return true
   }
 }
 
-/** Backend session wrapping one provider-owned terminal process. */
+/** Backend session wrapping one `node-pty` process and its captured process tree. */
 export class LocalPtySession implements PtyBackendSession {
   motd = ''
   readonly pid: number
-  private readonly decoder = new TextDecoder()
-  private readonly sanitizer: TerminalSanitizer
-  private readonly scrollback: BoundedTextBuffer
-  private readonly outputEnded = Promise.withResolvers<void>()
-  private readonly completion: Promise<void>
+  private readonly sanitizer: PtyTerminalSanitizer
+  private readonly scrollback: PtyTextBuffer
+  private readonly exitPromise: PromiseWithResolvers<void> = Promise.withResolvers<void>()
+  private readonly dataDisposable: IDisposable
+  private readonly exitDisposable: IDisposable
   private statusValue: PtySessionStatus = { kind: 'running' }
-  // TODO(pty-send-state-consolidation): Fold the per-send fields below
-  // (active/activeTimer/activeDeadlineTimer/activeAbort/interrupting/
-  // activeWrite/pollingReady/polling) into one send-lifecycle owner; the
-  // cancellation/readiness interplay now has enough pinned tests to carry
-  // that refactor safely.
   private active: LocalSendOperation | undefined
   private activeTimer: NodeJS.Timeout | undefined
-  private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
-  private interrupting: LocalSendOperation | undefined
-  private activeWrite: Promise<boolean> | undefined
-  private pollingReady: LocalSendOperation | undefined
-  private polling = false
   private promptSeen = false
   private promptTextSeen = false
-  private promptTail = ''
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
   private closing = false
   private closePromise: Promise<void> | undefined
-  private transportFailure: Error | undefined
 
   constructor(
-    private readonly terminal: SubprocessTerminalHandle,
+    private readonly terminal: IPty,
+    private readonly inspector: ProcessInspector,
     private readonly config: ResolvedConfig,
   ) {
     this.pid = terminal.pid
-    this.sanitizer = new TerminalSanitizer(config.maxReadBytes)
-    this.scrollback = new BoundedTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
-    terminal.output.on('data', this.onTerminalData)
-    terminal.output.once('end', this.onTerminalEnd)
-    terminal.output.once('error', this.onTerminalError)
-    this.completion = terminal.done.then(
-      outcome => this.onExit(outcome),
-      (error: unknown) => { this.onTransportFailure(error) },
-    )
+    this.sanitizer = new PtyTerminalSanitizer(config.maxReadBytes)
+    this.scrollback = new PtyTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
+    this.dataDisposable = terminal.onData((data) => { this.onData(data) })
+    this.exitDisposable = terminal.onExit(({ exitCode, signal }) => {
+      const tail = this.sanitizer.flush()
+      this.appendOutput(tail)
+      this.statusValue = { kind: 'exited', exitCode, signal: ptySignalName(signal) }
+      this.settleActive('session_exit')
+      this.exitPromise.resolve()
+    })
   }
 
   /**
@@ -225,14 +136,7 @@ export class LocalPtySession implements PtyBackendSession {
   startSend(request: PtySendRequest): PtySendOperation {
     if (this.closing) throw new Error('PTY session is closing')
     if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
-    if (this.active !== undefined) {
-      const draining = this.activeWrite !== undefined
-        ? ' or draining provider write'
-        : this.interrupting !== undefined
-          ? ' or draining foreground interrupt'
-          : ''
-      throw new PtyError(`PTY session already has an active send${draining}`, 'SEND_ACTIVE')
-    }
+    if (this.active !== undefined) throw new Error('PTY session already has an active send')
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
     const operation = new LocalSendOperation(
@@ -241,79 +145,29 @@ export class LocalPtySession implements PtyBackendSession {
       () => { this.interrupt(operation) },
     )
     this.active = operation
-    this.resetReadinessEvidence()
+    this.lastOutputAt = Date.now()
+    this.promptSeen = false
+    this.promptTextSeen = false
 
     if (request.signal !== undefined) {
       const onAbort = (): void => { operation.cancel() }
       request.signal.addEventListener('abort', onAbort, { once: true })
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
-    this.activeDeadlineTimer = setTimeout(() => {
-      if (this.active === operation) {
-        this.settleActive('timeout', this.activeWrite !== undefined || this.interrupting === operation)
-      }
-    }, this.config.timeoutMs)
-    void this.beginSend(operation, request)
+
+    try {
+      if (request.text.length > 0) this.terminal.write(request.text)
+      if (request.submit) this.terminal.write('\r')
+    } catch (error: unknown) {
+      this.clearActive()
+      operation.fail(error)
+      return operation
+    }
+
+    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
     return operation
   }
 
-  private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
-    let foreground: SubprocessTerminalForeground | undefined
-    try {
-      foreground = await this.terminal.inspectForeground()
-    } catch (error: unknown) {
-      // A pre-write inspection failure while cancellation owns the slot must not
-      // release it: interruptOnce's in-flight foreground signal could land on a
-      // successor's foreground group. The interrupt path's post-signal tail
-      // resumes polling, whose guarded catch propagates a persistent failure.
-      // A retained settled operation implies that same in-flight interrupt, so
-      // this guard admits only an unsettled active send.
-      if (this.active === operation && !this.closing && this.interrupting !== operation) {
-        this.failActive(error)
-      }
-      return
-    }
-    try {
-      if (this.active !== operation || this.closing || this.interrupting === operation) return
-      operation.setInitialForeground(foreground)
-      const input = `${request.text}${request.submit ? '\r' : ''}`
-      if (input.length > 0 && !operation.cancelRequested) {
-        this.resetReadinessEvidence()
-        const write = this.terminal.write(input)
-        this.activeWrite = write.then(() => true, () => false)
-        try {
-          await write
-        } finally {
-          this.activeWrite = undefined
-        }
-      }
-      // Cancellation owns post-write signalling and reservation release.
-      if (operation.cancelRequested) return
-      if (this.active === operation && operation.settled) {
-        this.clearActive()
-        return
-      }
-      // Closing can race the awaited provider write even though static analysis sees only local assignments.
-      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited provider writes can close the session.
-      if (this.active === operation && !this.closing) {
-        this.pollingReady = operation
-        this.schedulePoll(operation)
-      }
-    } catch (error: unknown) {
-      if (this.active === operation && !this.closing) {
-        if (operation.settled) this.clearActive()
-        else this.failActive(error)
-      }
-    }
-  }
-
-  private resetReadinessEvidence(): void {
-    this.lastOutputAt = Date.now()
-    this.promptSeen = false
-    this.promptTextSeen = false
-    this.promptTail = ''
-  }
-
   read(request: PtyReadRequest): PtyReadResult {
     const snapshot = this.scrollback.snapshot()
     const lines = snapshot.text.split('\n')
@@ -328,7 +182,7 @@ export class LocalPtySession implements PtyBackendSession {
     const end = totalLines - offset
     const start = Math.max(0, end - count)
     const requested = lines.slice(start, end).join('\n')
-    const bounded = utf8Tail(requested, this.config.maxReadBytes)
+    const bounded = ptyUtf8Tail(requested, this.config.maxReadBytes)
     const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split('\n').length
     return {
       text: bounded.text,
@@ -339,10 +193,16 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
-  async signal(signal: PtySignal): Promise<PtySignalResult> {
-    if (this.closing) throw new Error('PTY session is closing')
-    const targetPgid = await this.terminal.signalForeground(signal)
-    return { delivered: true, targetPgid }
+  signal(signal: PtySignal): Promise<PtySignalResult> {
+    return Promise.resolve().then(() => {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
+      if (signal === 'SIGKILL' && pgid === this.pid) {
+        throw new Error('refusing to SIGKILL the PTY shell; use terminal_close')
+      }
+      this.inspector.signalGroup(pgid, signal)
+      return { delivered: true, targetPgid: pgid }
+    })
   }
 
   status(): PtySessionStatus {
@@ -361,56 +221,21 @@ export class LocalPtySession implements PtyBackendSession {
     return closing
   }
 
-  private readonly onTerminalData = (chunk: Buffer | Uint8Array | string): void => {
-    const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
-    this.onData(this.decoder.decode(bytes, { stream: true }))
-  }
-
-  private readonly onTerminalEnd = (): void => {
-    this.onData(this.decoder.decode())
-    this.appendOutput(this.sanitizer.flush())
-    this.outputEnded.resolve()
-  }
-
-  private readonly onTerminalError = (error: Error): void => {
-    this.onTransportFailure(error)
-    this.outputEnded.resolve()
-  }
-
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
     if (sanitized.prompt) {
-      // TODO(pty-delayed-signal-prompt): With a reproducer, define a marker-generation boundary
-      // before attributing a signal-delayed prompt to a later send.
+      const foregroundPgid = this.inspector.foregroundPgid(this.pid)
+      if (this.shellPgid === undefined) this.shellPgid = foregroundPgid
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
       this.promptSeen = true
-      this.promptTail = ''
+      this.promptTextSeen = sanitized.promptText === true
       this.lastOutputAt = Date.now()
+    } else if (this.promptSeen && sanitized.promptText === true) {
+      this.promptTextSeen = true
     }
-    if (this.promptSeen && sanitized.promptTail !== undefined) {
-      const remaining = Math.max(0, CONTROLLED_PROMPT.length + 1 - this.promptTail.length)
-      this.promptTail += sanitized.promptTail.slice(0, remaining)
-      if (sanitized.promptTail.length > remaining) this.promptTail = `${CONTROLLED_PROMPT}\0`
-      this.promptTextSeen = this.promptTail === CONTROLLED_PROMPT
-    }
-  }
-
-  private async onExit(outcome: SubprocessOutcome): Promise<void> {
-    await this.outputEnded.promise
-    if (this.transportFailure !== undefined) return
-    this.statusValue = { kind: 'exited', exitCode: outcome.exitCode, signal: outcome.signal }
-    this.settleActive('session_exit')
-  }
-
-  private onTransportFailure(error: unknown): void {
-    const failure = error instanceof Error ? error : new Error(String(error))
-    this.transportFailure ??= failure
-    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
-    this.failActive(failure)
-    void this.terminal.terminate().catch(() => {})
   }
 
   private appendOutput(text: string): void {
@@ -420,94 +245,60 @@ export class LocalPtySession implements PtyBackendSession {
     this.active?.append(text)
   }
 
-  private schedulePoll(operation: LocalSendOperation, delayMs = this.config.pollIntervalMs): void {
-    if (this.active !== operation || this.interrupting === operation || this.polling) return
-    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
-    this.activeTimer = setTimeout(() => {
-      this.activeTimer = undefined
-      void this.pollReadiness(operation)
-    }, delayMs)
-  }
-
-  private async pollReadiness(operation: LocalSendOperation): Promise<void> {
-    if (this.active !== operation || this.polling) return
-    this.polling = true
-    try {
-      if (this.statusValue.kind === 'exited') {
-        this.settleActive('session_exit')
-        return
-      }
-      const foreground = await this.terminal.inspectForeground()
-      if (this.active !== operation || this.closing || this.interrupting === operation) return
-      const idleFor = Date.now() - this.lastOutputAt
-      if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
-        this.shellPgid = foreground.processGroupId
-      }
-      if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs
-        && foreground?.processGroupId === this.shellPgid) {
-        this.settleActive('stdin_read')
-        return
-      }
-      const elapsed = Date.now() - operation.startedAt
-      const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
-      const acceptsStdinWait = startupHasOutput && foreground !== undefined
-        && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting)
-      if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
-        this.settleActive('stdin_read')
-        return
-      }
-      // A prompt candidate can race bash's foreground handoff, but an interactive
-      // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
-      // on waiting for shell ownership instead of letting a child marker suppress
-      // readiness until the absolute timeout.
-      const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
-      if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
-        this.settleActive('inferred_idle')
-      }
-    } catch (error: unknown) {
-      if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error)
-    } finally {
-      this.polling = false
-      const active = this.active
-      // Awaited provider inspection can clear or replace the active send despite static analysis.
-      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited inspection can replace the active send.
-      if (active !== undefined && this.pollingReady === active) this.schedulePoll(active)
+  private pollReadiness(operation: LocalSendOperation): void {
+    if (this.active !== operation) return
+    if (this.statusValue.kind === 'exited') {
+      this.settleActive('session_exit')
+      return
     }
+    if (this.promptSeen && this.promptTextSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (this.shellPgid !== undefined && pgid === this.shellPgid) {
+        this.settleActive('stdin_read')
+        return
+      }
+    }
+    const elapsed = Date.now() - operation.startedAt
+    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
+    if (startupHasOutput && elapsed >= this.config.exactProbeAfterMs) {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (pgid !== undefined && this.inspector.isStdinWaiting(pgid)) {
+        this.settleActive('stdin_read')
+        return
+      }
+    }
+    // A prompt candidate can race bash's foreground handoff, but an interactive
+    // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
+    // on waiting for shell ownership instead of letting a child marker suppress
+    // readiness until the absolute timeout. When a prompt marker was seen, the
+    // configured grace holds the fallback past the silence bound so polls in
+    // that window can observe the foreground handoff and settle as stdin_read.
+    const idleFor = Date.now() - this.lastOutputAt
+    const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
+    if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
+      this.settleActive('inferred_idle')
+      return
+    }
+    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
   }
 
-  private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
+  private settleActive(waitReason: PtyWaitReason): void {
     const operation = this.active
     if (operation === undefined) return
     const scrollbackTruncated = this.scrollback.snapshot().truncated
-    if (retainOwnership) {
-      this.stopPolling()
-      this.activeAbort?.()
-      this.activeAbort = undefined
-    } else {
-      this.clearActive()
-    }
+    this.clearActive()
     operation.settle(waitReason, this.statusValue, scrollbackTruncated)
   }
 
   private stopPolling(): void {
-    this.stopReadinessPolling()
-    if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
-    this.activeDeadlineTimer = undefined
-  }
-
-  private stopReadinessPolling(): void {
-    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
+    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
     this.activeTimer = undefined
-    this.pollingReady = undefined
   }
 
   private clearActive(): void {
-    const operation = this.active
     this.stopPolling()
     this.activeAbort?.()
     this.activeAbort = undefined
-    if (this.interrupting === operation) this.interrupting = undefined
-    this.pollingReady = undefined
     this.active = undefined
   }
 
@@ -520,46 +311,104 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
-    this.interrupting = operation
-    this.stopReadinessPolling()
-    void this.interruptOnce(operation)
+    try {
+      const pgid = this.inspector.foregroundPgid(this.pid)
+      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
+      this.inspector.signalGroup(pgid, 'SIGINT')
+    } catch (error: unknown) {
+      this.failActive(error)
+    }
   }
 
-  private async interruptOnce(operation: LocalSendOperation): Promise<void> {
-    try {
-      const activeWrite = this.activeWrite
-      if (activeWrite !== undefined && !await activeWrite) return
-      await this.terminal.signalForeground('SIGINT')
-    } catch (error: unknown) {
-      if (this.active === operation && !this.closing) this.onTransportFailure(error)
-      return
-    } finally {
-      if (this.interrupting === operation) this.interrupting = undefined
+  private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
+    return members.filter(member => this.inspector.isAlive(member))
+  }
+
+  private descendants(): ProcessIdentity[] {
+    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
+  }
+
+  private async waitForExit(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
+    const deadline = Date.now() + this.config.disposeGraceMs
+    let survivors = this.survivors(members)
+    while (survivors.length > 0 && Date.now() < deadline) {
+      await delay(Math.min(25, Math.max(1, deadline - Date.now())))
+      survivors = this.survivors(members)
     }
-    if (this.active === operation && operation.settled) {
-      this.clearActive()
-    } else if (this.active === operation && !this.closing) {
-      this.pollingReady = operation
-      this.schedulePoll(operation, 0)
+    return survivors
+  }
+
+  private signalMembers(members: ProcessIdentity[], signal: 'SIGTERM' | 'SIGKILL'): void {
+    for (const member of members) {
+      try {
+        this.inspector.signalProcess(member, signal)
+      } catch (_alreadyExitedDuringSignal) {
+        // Identity is rechecked by the inspector; a same-tick exit is success.
+      }
+    }
+  }
+
+  private unionMembers(...groups: ProcessIdentity[][]): ProcessIdentity[] {
+    const members: ProcessIdentity[] = []
+    const seen = new Set<string>()
+    for (const group of groups) {
+      for (const member of group) {
+        const key = JSON.stringify([member.pid, member.started])
+        if (seen.has(key)) continue
+        seen.add(key)
+        members.push(member)
+      }
+    }
+    return members
+  }
+
+  private async stopDescendants(): Promise<ProcessIdentity[]> {
+    const captured = this.descendants()
+    this.signalMembers(captured, 'SIGTERM')
+    const capturedSurvivors = await this.waitForExit(captured)
+    // A TERM-handling descendant may have forked while winding down. Rescan
+    // while the shell can still reap every member, then kill both the fresh
+    // tree and captured survivors that were reparented out of that tree.
+    const members = this.unionMembers(capturedSurvivors, this.descendants())
+    this.signalMembers(members, 'SIGKILL')
+    const survivors = await this.waitForExit(members)
+    return this.survivors(this.unionMembers(survivors, this.descendants()))
+  }
+
+  private async stopShell(): Promise<void> {
+    try {
+      this.terminal.kill('SIGTERM')
+    } catch (_topLevelAlreadyExitedDuringTerm) {
+      // The exit notification remains authoritative.
+    }
+    if (this.statusValue.kind === 'running') {
+      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (this.statusValue.kind === 'running') {
+      try {
+        this.terminal.kill('SIGKILL')
+      } catch (_topLevelAlreadyExitedDuringKill) {
+        // The exit notification remains authoritative.
+      }
+      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (this.statusValue.kind === 'running') {
+      throw new Error(`PTY cleanup failed; surviving pids: ${this.pid}`)
     }
   }
 
   private async closeOnce(reason: string): Promise<void> {
+    this.dataDisposable.dispose()
     // Stop readiness polling but retain the active operation: teardown settles
     // it as session_exit below, so an in-flight send is never mis-settled as
     // stdin_read/inferred_idle/timeout during the grace period.
     this.stopPolling()
-    try {
-      await this.terminal.terminate()
-    } catch (error: unknown) {
-      throw new Error(`PTY cleanup failed (${reason})`, { cause: error })
+    const survivors = await this.stopDescendants()
+    if (survivors.length > 0) {
+      throw new Error(`PTY cleanup failed (${reason}); surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
     }
-    // Quiescence is the active send's terminal outcome.
+    await this.stopShell()
     this.settleActive('session_exit')
-    await this.completion
-    this.terminal.output.off('data', this.onTerminalData)
-    this.terminal.output.off('end', this.onTerminalEnd)
-    this.terminal.output.off('error', this.onTerminalError)
-    if (this.transportFailure !== undefined) throw this.transportFailure
+    this.exitDisposable.dispose()
   }
 }
diff --git a/packages/pty/pty-local/tests/sanitize.spec.ts b/packages/pty/pty-local/tests/sanitize.spec.ts
index f6649b3c6f..06ec076358 100644
--- a/packages/pty/pty-local/tests/sanitize.spec.ts
+++ b/packages/pty/pty-local/tests/sanitize.spec.ts
@@ -1,17 +1,17 @@
 import { describe, expect, it } from 'vitest'
-import { normalizeTerminalText, TerminalSanitizer } from '@deepseek-ai/dsh-pty-local/src/sanitize.ts'
+import { normalizePtyTerminalText, PtyTerminalSanitizer } from '@deepseek-ai/dsh-pty'
 
-describe('TerminalSanitizer', () => {
+describe('PtyTerminalSanitizer', () => {
   it('removes split CSI and owned OSC prompt markers', () => {
-    const sanitizer = new TerminalSanitizer(64)
+    const sanitizer = new PtyTerminalSanitizer(64)
     expect(sanitizer.push('red\x1b[3')).toEqual({ text: 'red', prompt: false })
     expect(sanitizer.push('1m text\x1b[0m\r\n')).toEqual({ text: ' text\n', prompt: false })
     expect(sanitizer.push('\x1b]133;')).toEqual({ text: '', prompt: false })
-    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptTail: 'dsh> ' })
+    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptText: true })
   })
 
   it('drops unrelated OSC, short escapes, BEL, and incomplete trailing escape', () => {
-    const sanitizer = new TerminalSanitizer(64)
+    const sanitizer = new PtyTerminalSanitizer(64)
     expect(sanitizer.push('a\x1b]0;title\x1b\\b\x1b7c\x07')).toEqual({ text: 'abc', prompt: false })
     expect(sanitizer.push('tail\x1b')).toEqual({ text: 'tail', prompt: false })
     expect(sanitizer.flush()).toBe('')
@@ -22,11 +22,11 @@ describe('TerminalSanitizer', () => {
   })
 
   it('normalizes CRLF and standalone carriage returns', () => {
-    expect(normalizeTerminalText('a\r\nb\rc\x07')).toBe('a\nb\nc')
+    expect(normalizePtyTerminalText('a\r\nb\rc\x07')).toBe('a\nb\nc')
   })
 
   it('carries a trailing carriage return across data chunks and flushes standalone CR', () => {
-    const sanitizer = new TerminalSanitizer(64)
+    const sanitizer = new PtyTerminalSanitizer(64)
     expect(sanitizer.push('a\r')).toEqual({ text: 'a', prompt: false })
     expect(sanitizer.push('\nb')).toEqual({ text: '\nb', prompt: false })
     expect(sanitizer.push('\r')).toEqual({ text: '', prompt: false })
@@ -34,41 +34,41 @@ describe('TerminalSanitizer', () => {
   })
 
   it('reports printable prompt text that follows a marker in a later chunk', () => {
-    const sanitizer = new TerminalSanitizer(64)
-    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true, promptTail: '' })
-    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptTail: 'dsh> ' })
+    const sanitizer = new PtyTerminalSanitizer(64)
+    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true })
+    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptText: true })
   })
 
   it('bounds and discards unterminated control sequences through their terminators', () => {
-    const oscBel = new TerminalSanitizer(8)
+    const oscBel = new PtyTerminalSanitizer(8)
     expect(oscBel.push(`\x1b]0;${'x'.repeat(16)}`)).toEqual({ text: '', prompt: false })
     expect(oscBel.push('more\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscSt = new TerminalSanitizer(8)
+    const oscSt = new PtyTerminalSanitizer(8)
     oscSt.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscSt.push('more\x1b')).toEqual({ text: '', prompt: false })
     expect(oscSt.push('\\tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscDirectSt = new TerminalSanitizer(8)
+    const oscDirectSt = new PtyTerminalSanitizer(8)
     oscDirectSt.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscDirectSt.push('more\x1b\\tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscFalseSt = new TerminalSanitizer(8)
+    const oscFalseSt = new PtyTerminalSanitizer(8)
     oscFalseSt.push(`\x1b]0;${'x'.repeat(16)}`)
     oscFalseSt.push('\x1b')
     expect(oscFalseSt.push('more')).toEqual({ text: '', prompt: false })
     expect(oscFalseSt.push('\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscNonTerminatingEscape = new TerminalSanitizer(8)
+    const oscNonTerminatingEscape = new PtyTerminalSanitizer(8)
     oscNonTerminatingEscape.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscNonTerminatingEscape.push('more\x1bxmore\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const csi = new TerminalSanitizer(8)
+    const csi = new PtyTerminalSanitizer(8)
     expect(csi.push(`\x1b[${'1'.repeat(16)}`)).toEqual({ text: '', prompt: false })
     expect(csi.push('123')).toEqual({ text: '', prompt: false })
     expect(csi.push('mtext')).toEqual({ text: 'text', prompt: false })
 
-    const flushed = new TerminalSanitizer(8)
+    const flushed = new PtyTerminalSanitizer(8)
     flushed.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(flushed.flush()).toBe('')
     expect(flushed.push('text')).toEqual({ text: 'text', prompt: false })
diff --git a/packages/pty/pty/src/index.ts b/packages/pty/pty/src/index.ts
index 8ff4168e1a..5cb375fbca 100644
--- a/packages/pty/pty/src/index.ts
+++ b/packages/pty/pty/src/index.ts
@@ -41,6 +41,15 @@ export type {
   PtyWaitReason,
 } from './types.ts'
 export { PtyBackendCleanupError } from './types.ts'
+export {
+  normalizePtyTerminalText,
+  PTY_PROMPT_MARKER_PREFIX,
+  PtyTerminalSanitizer,
+  PtyTextBuffer,
+  ptySignalName,
+  ptyUtf8Tail,
+} from './terminal.ts'
+export type { PtySanitizedChunk } from './terminal.ts'
 
 /** Opaque identity minted by {@link PtyService} for one live PTY session. */
 export type PtySessionId = PtySessionIdValue
diff --git a/packages/pty/pty/src/terminal.ts b/packages/pty/pty/src/terminal.ts
new file mode 100644
index 0000000000..ed005dda41
--- /dev/null
+++ b/packages/pty/pty/src/terminal.ts
@@ -0,0 +1,273 @@
+/** Backend-neutral line-oriented terminal buffering and control-sequence sanitization. */
+
+import { Buffer } from 'node:buffer'
+import { constants } from 'node:os'
+import type { PtySendRead } from './types.ts'
+
+/** OSC marker emitted by a controlled bash before each prompt. */
+export const PTY_PROMPT_MARKER_PREFIX = '133;D;'
+
+/** One sanitized chunk plus whether it contained the controlled prompt marker. */
+export interface PtySanitizedChunk {
+  /** Printable, line-normalized terminal text. */
+  text: string
+  /** Whether the chunk completed the controlled prompt marker. */
+  prompt: boolean
+  /** Present when printable text followed the latest controlled prompt marker. */
+  promptText?: true
+}
+
+/**
+ * Return the largest code-point-aligned UTF-8 tail within a byte cap.
+ * @param text - Candidate terminal text.
+ * @param maxBytes - Maximum retained UTF-8 bytes.
+ * @returns The retained tail and whether its head was dropped.
+ */
+export function ptyUtf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
+  if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
+  const chars = Array.from(text)
+  let bytes = 0
+  let start = chars.length
+  while (start > 0) {
+    const next = Buffer.byteLength(chars[start - 1] as string)
+    if (bytes + next > maxBytes) break
+    bytes += next
+    start -= 1
+  }
+  return { text: chars.slice(start).join(''), truncated: true }
+}
+
+/** UTF-8 and optionally line-bounded terminal text buffer. */
+export class PtyTextBuffer {
+  private value = ''
+  private dropped = false
+
+  /**
+   * @param maxBytes - Maximum retained UTF-8 bytes.
+   * @param maxLines - Optional maximum retained logical lines.
+   */
+  constructor(
+    private readonly maxBytes: number,
+    private readonly maxLines?: number,
+  ) {}
+
+  /**
+   * Append terminal text and drop the oldest excess.
+   * @param text - Decoded and sanitized terminal text.
+   */
+  append(text: string): void {
+    if (text.length === 0) return
+    this.value += text
+    if (this.maxLines !== undefined) {
+      const lines = this.value.split('\n')
+      if (lines.length > this.maxLines) {
+        this.value = lines.slice(lines.length - this.maxLines).join('\n')
+        this.dropped = true
+      }
+    }
+    const tail = ptyUtf8Tail(this.value, this.maxBytes)
+    this.value = tail.text
+    this.dropped ||= tail.truncated
+  }
+
+  /**
+   * Consume all currently retained operation text.
+   * @returns The delta and whether older text was dropped.
+   */
+  consume(): PtySendRead {
+    const delta = this.value
+    const truncated = this.dropped
+    this.value = ''
+    this.dropped = false
+    return { delta, truncated }
+  }
+
+  /**
+   * Return the retained text without consuming it.
+   * @returns The retained text and whether its head was dropped.
+   */
+  snapshot(): { text: string; truncated: boolean } {
+    return { text: this.value, truncated: this.dropped }
+  }
+}
+
+/**
+ * Streaming terminal-control sanitizer for line-oriented PTY backends.
+ * Full terminal emulation is deliberately outside the PTY seam.
+ */
+export class PtyTerminalSanitizer {
+  private pending = ''
+  private discardMode: 'osc' | 'csi' | undefined
+  private discardOscEscape = false
+  private trailingCarriageReturn = false
+  private awaitingPromptText = false
+
+  /** @param maxPendingBytes - Bound for an incomplete terminal-control sequence. */
+  constructor(private readonly maxPendingBytes: number) {}
+
+  /**
+   * Consume one decoded PTY data chunk.
+   * @param chunk - Decoded terminal data.
+   * @returns Printable text and prompt-marker facts.
+   */
+  push(chunk: string): PtySanitizedChunk {
+    this.pending += this.discardPrefix(chunk)
+    let text = ''
+    let prompt = false
+    let promptText = false
+    let index = 0
+    const appendText = (value: string): boolean => {
+      text += value
+      if (this.awaitingPromptText && value.replace(/[\r\n\x07]/g, '').length > 0) {
+        this.awaitingPromptText = false
+        return true
+      }
+      return false
+    }
+    while (index < this.pending.length) {
+      const escape = this.pending.indexOf('\x1b', index)
+      if (escape < 0) {
+        promptText = appendText(this.pending.slice(index)) || promptText
+        index = this.pending.length
+        break
+      }
+      promptText = appendText(this.pending.slice(index, escape)) || promptText
+      if (escape + 1 >= this.pending.length) {
+        index = escape
+        break
+      }
+      const kind = this.pending[escape + 1]
+      if (kind === ']') {
+        const bel = this.pending.indexOf('\x07', escape + 2)
+        const stringTerminator = this.pending.indexOf('\x1b\\', escape + 2)
+        let end = -1
+        if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2)
+        else if (bel >= 0) end = bel + 1
+        else if (stringTerminator >= 0) end = stringTerminator + 2
+        if (end < 0) {
+          index = escape
+          break
+        }
+        const terminatorBytes = this.pending[end - 1] === '\x07' ? 1 : 2
+        const content = this.pending.slice(escape + 2, end - terminatorBytes)
+        if (content.startsWith(PTY_PROMPT_MARKER_PREFIX)) {
+          prompt = true
+          promptText = false
+          this.awaitingPromptText = true
+        }
+        index = end
+        continue
+      }
+      if (kind === '[') {
+        let end = escape + 2
+        while (end < this.pending.length) {
+          const code = this.pending.charCodeAt(end)
+          if (code >= 0x40 && code <= 0x7e) break
+          end += 1
+        }
+        if (end >= this.pending.length) {
+          index = escape
+          break
+        }
+        index = end + 1
+        continue
+      }
+      index = escape + 2
+    }
+    this.pending = this.pending.slice(index)
+    this.enforcePendingBound()
+    return { text: this.normalizeText(text), prompt, ...promptText ? { promptText: true } : {} }
+  }
+
+  /**
+   * Flush printable trailing data and discard incomplete controls.
+   * @returns Remaining normalized printable text.
+   */
+  flush(): string {
+    const text = this.pending.startsWith('\x1b') ? '' : this.pending
+    this.pending = ''
+    this.discardMode = undefined
+    this.discardOscEscape = false
+    this.awaitingPromptText = false
+    const normalized = this.normalizeText(text)
+    if (!this.trailingCarriageReturn) return normalized
+    this.trailingCarriageReturn = false
+    return `${normalized}\n`
+  }
+
+  private normalizeText(text: string): string {
+    let complete = this.trailingCarriageReturn ? `\r${text}` : text
+    this.trailingCarriageReturn = false
+    if (complete.endsWith('\r')) {
+      complete = complete.slice(0, -1)
+      this.trailingCarriageReturn = true
+    }
+    return normalizePtyTerminalText(complete)
+  }
+
+  private enforcePendingBound(): void {
+    if (Buffer.byteLength(this.pending) <= this.maxPendingBytes) return
+    this.discardMode = this.pending[1] === ']' ? 'osc' : 'csi'
+    this.pending = ''
+  }
+
+  private discardPrefix(chunk: string): string {
+    if (this.discardMode === undefined) return chunk
+    if (this.discardMode === 'csi') {
+      for (let index = 0; index < chunk.length; index += 1) {
+        const code = chunk.charCodeAt(index)
+        if (code >= 0x40 && code <= 0x7e) {
+          this.discardMode = undefined
+          return chunk.slice(index + 1)
+        }
+      }
+      return ''
+    }
+
+    let index = 0
+    if (this.discardOscEscape) {
+      this.discardOscEscape = false
+      if (chunk.startsWith('\\')) {
+        this.discardMode = undefined
+        return chunk.slice(1)
+      }
+    }
+    while (index < chunk.length) {
+      if (chunk[index] === '\x07') {
+        this.discardMode = undefined
+        return chunk.slice(index + 1)
+      }
+      if (chunk[index] === '\x1b') {
+        if (chunk[index + 1] === '\\') {
+          this.discardMode = undefined
+          return chunk.slice(index + 2)
+        }
+        if (index + 1 === chunk.length) this.discardOscEscape = true
+      }
+      index += 1
+    }
+    return ''
+  }
+}
+
+/**
+ * Normalize CRLF and standalone carriage returns for line-oriented rendering.
+ * @param text - Sanitized terminal text.
+ * @returns Line-normalized text with BEL removed.
+ */
+export function normalizePtyTerminalText(text: string): string {
+  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n').replaceAll('\x07', '')
+}
+
+/**
+ * Convert a platform signal number into the seam's signal-name vocabulary.
+ * @param number - Platform signal number, zero, or an absent signal.
+ * @returns The matching Node signal name, or `null` when unknown or absent.
+ */
+export function ptySignalName(number: number | undefined): NodeJS.Signals | null {
+  if (number === undefined || number === 0) return null
+  for (const [name, value] of Object.entries(constants.signals)) {
+    if (value === number) return name as NodeJS.Signals
+  }
+  return null
+}
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 90aa22e322..5ab5dc2e4e 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -47,6 +47,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/code-runtime/code-runtime-e2b': { kind: 'indirect', reason: 'The E2B backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
@@ -98,6 +99,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
+  'packages/lsp/lsp-e2b': { kind: 'indirect', reason: 'The E2B provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/lsp/lsp-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/subprocess/subprocess': { kind: 'indirect', reason: 'The seam delegates all model rendering to consumer seams such as the bash executor family.' },
   'packages/subprocess/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 03b1bcd2dd..1f70e79a4f 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -166,10 +166,12 @@
     { "path": "./packages/subprocess/subprocess-e2b" },
     { "path": "./packages/bash/bash" },
     { "path": "./packages/pty/pty" },
+    { "path": "./packages/pty/pty-e2b" },
     { "path": "./packages/pty/pty-local" },
     { "path": "./packages/pty/tool-bash-persistent" },
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
+    { "path": "./packages/code-runtime/code-runtime-e2b" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
@@ -266,6 +268,7 @@
     { "path": "./packages/sdk/create-sdk" },
     { "path": "./packages/sdk/telemetry" },
     { "path": "./packages/lsp/lsp" },
+    { "path": "./packages/lsp/lsp-e2b" },
     { "path": "./packages/lsp/lsp-local" },
     { "path": "./packages/lsp/tool-lsp" },
     { "path": "./apps/cli" }

From e64d40837c04bc6b39ea958ce8afc26cba97b2ed Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 14:52:37 +0800
Subject: [PATCH 354/516] refactor(e2b): group remote providers

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |  4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      | 40 ++++++++++---
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   | 40 ++++++++++---
 ...active-semantic-code-runtime-poc.i18n.yaml |  6 --
 ...b-interactive-semantic-code-runtime-poc.md | 57 -------------------
 ...nteractive-semantic-code-runtime-poc.zh.md | 57 -------------------
 AGENTS.md                                     | 21 +++----
 packages/README.i18n.yaml                     |  4 +-
 packages/README.md                            |  2 +-
 packages/README.zh.md                         |  2 +-
 packages/code-runtime/README.i18n.yaml        |  4 +-
 packages/code-runtime/README.md               |  4 +-
 packages/code-runtime/README.zh.md            |  4 +-
 .../code-runtime-e2b/README.i18n.yaml         |  6 --
 packages/e2b/README.i18n.yaml                 |  4 +-
 packages/e2b/README.md                        | 12 ++--
 packages/e2b/README.zh.md                     | 12 ++--
 .../code-runtime-e2b}/README.i18n.yaml        |  6 +-
 .../code-runtime-e2b/README.md                |  2 +-
 .../code-runtime-e2b/README.zh.md             |  2 +-
 .../code-runtime-e2b/package.json             |  0
 .../code-runtime-e2b/src/index.ts             |  0
 .../code-runtime-e2b/src/invariant.ts         |  0
 .../code-runtime-e2b/src/runner-source.ts     |  0
 .../code-runtime-e2b/tests/runtime.spec.ts    |  0
 .../code-runtime-e2b/tsconfig.json            |  8 +--
 packages/{fs => e2b}/fs-e2b/README.i18n.yaml  |  6 +-
 packages/{fs => e2b}/fs-e2b/README.md         |  4 +-
 packages/{fs => e2b}/fs-e2b/README.zh.md      |  4 +-
 packages/{fs => e2b}/fs-e2b/package.json      |  0
 packages/{fs => e2b}/fs-e2b/src/index.ts      |  0
 packages/{fs => e2b}/fs-e2b/src/invariant.ts  |  0
 .../fs-e2b/tests/filesystem.spec.ts           |  0
 packages/{fs => e2b}/fs-e2b/tsconfig.json     |  4 +-
 .../pty-e2b => e2b/lsp-e2b}/README.i18n.yaml  |  6 +-
 packages/{lsp => e2b}/lsp-e2b/README.md       |  2 +-
 packages/{lsp => e2b}/lsp-e2b/README.zh.md    |  2 +-
 packages/{lsp => e2b}/lsp-e2b/package.json    |  0
 packages/{lsp => e2b}/lsp-e2b/src/index.ts    |  0
 .../{lsp => e2b}/lsp-e2b/src/invariant.ts     |  0
 .../{lsp => e2b}/lsp-e2b/src/proxy-source.ts  |  0
 .../{lsp => e2b}/lsp-e2b/src/transport.ts     |  0
 .../lsp-e2b/tests/provider.spec.ts            |  0
 .../lsp-e2b/tests/transport.spec.ts           |  0
 packages/{lsp => e2b}/lsp-e2b/tsconfig.json   |  8 +--
 .../lsp-e2b => e2b/pty-e2b}/README.i18n.yaml  |  6 +-
 packages/{pty => e2b}/pty-e2b/README.md       |  2 +-
 packages/{pty => e2b}/pty-e2b/README.zh.md    |  2 +-
 packages/{pty => e2b}/pty-e2b/package.json    |  0
 packages/{pty => e2b}/pty-e2b/src/config.ts   |  0
 packages/{pty => e2b}/pty-e2b/src/index.ts    |  0
 .../{pty => e2b}/pty-e2b/src/invariant.ts     |  0
 packages/{pty => e2b}/pty-e2b/src/session.ts  |  0
 .../{pty => e2b}/pty-e2b/tests/index.spec.ts  |  0
 .../pty-e2b/tests/session.spec.ts             |  0
 packages/{pty => e2b}/pty-e2b/tsconfig.json   |  4 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  6 ++
 .../subprocess-e2b/README.md                  |  2 +-
 .../subprocess-e2b/README.zh.md               |  2 +-
 .../subprocess-e2b/package.json               |  0
 .../subprocess-e2b/src/index.ts               |  0
 .../subprocess-e2b/src/invariant.ts           |  0
 .../subprocess-e2b/src/output.ts              |  0
 .../subprocess-e2b/src/process.ts             |  0
 .../subprocess-e2b/tests/subprocess.spec.ts   |  0
 .../subprocess-e2b/tsconfig.json              |  4 +-
 packages/fs/README.i18n.yaml                  |  4 +-
 packages/fs/README.md                         |  2 +-
 packages/fs/README.zh.md                      |  2 +-
 packages/lsp/README.i18n.yaml                 |  4 +-
 packages/lsp/README.md                        |  4 +-
 packages/lsp/README.zh.md                     |  4 +-
 packages/pty/README.i18n.yaml                 |  4 +-
 packages/pty/README.md                        |  4 +-
 packages/pty/README.zh.md                     |  4 +-
 packages/subprocess/README.i18n.yaml          |  4 +-
 packages/subprocess/README.md                 |  2 +-
 packages/subprocess/README.zh.md              |  2 +-
 .../verify-package-readme-model-experience.ts |  8 +--
 tsconfig.base.json                            |  1 +
 tsconfig.host.json                            | 10 ++--
 81 files changed, 171 insertions(+), 249 deletions(-)
 delete mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
 delete mode 100644 .agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
 delete mode 100644 packages/code-runtime/code-runtime-e2b/README.i18n.yaml
 rename packages/{subprocess/subprocess-e2b => e2b/code-runtime-e2b}/README.i18n.yaml (54%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/README.md (93%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/README.zh.md (93%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/package.json (100%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/src/index.ts (100%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/src/invariant.ts (100%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/src/runner-source.ts (100%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/tests/runtime.spec.ts (100%)
 rename packages/{code-runtime => e2b}/code-runtime-e2b/tsconfig.json (70%)
 rename packages/{fs => e2b}/fs-e2b/README.i18n.yaml (56%)
 rename packages/{fs => e2b}/fs-e2b/README.md (81%)
 rename packages/{fs => e2b}/fs-e2b/README.zh.md (81%)
 rename packages/{fs => e2b}/fs-e2b/package.json (100%)
 rename packages/{fs => e2b}/fs-e2b/src/index.ts (100%)
 rename packages/{fs => e2b}/fs-e2b/src/invariant.ts (100%)
 rename packages/{fs => e2b}/fs-e2b/tests/filesystem.spec.ts (100%)
 rename packages/{fs => e2b}/fs-e2b/tsconfig.json (87%)
 rename packages/{pty/pty-e2b => e2b/lsp-e2b}/README.i18n.yaml (60%)
 rename packages/{lsp => e2b}/lsp-e2b/README.md (92%)
 rename packages/{lsp => e2b}/lsp-e2b/README.zh.md (92%)
 rename packages/{lsp => e2b}/lsp-e2b/package.json (100%)
 rename packages/{lsp => e2b}/lsp-e2b/src/index.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/src/invariant.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/src/proxy-source.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/src/transport.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/tests/provider.spec.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/tests/transport.spec.ts (100%)
 rename packages/{lsp => e2b}/lsp-e2b/tsconfig.json (75%)
 rename packages/{lsp/lsp-e2b => e2b/pty-e2b}/README.i18n.yaml (60%)
 rename packages/{pty => e2b}/pty-e2b/README.md (93%)
 rename packages/{pty => e2b}/pty-e2b/README.zh.md (93%)
 rename packages/{pty => e2b}/pty-e2b/package.json (100%)
 rename packages/{pty => e2b}/pty-e2b/src/config.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/src/index.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/src/invariant.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/src/session.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/tests/index.spec.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/tests/session.spec.ts (100%)
 rename packages/{pty => e2b}/pty-e2b/tsconfig.json (85%)
 create mode 100644 packages/e2b/subprocess-e2b/README.i18n.yaml
 rename packages/{subprocess => e2b}/subprocess-e2b/README.md (89%)
 rename packages/{subprocess => e2b}/subprocess-e2b/README.zh.md (89%)
 rename packages/{subprocess => e2b}/subprocess-e2b/package.json (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/src/index.ts (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/src/invariant.ts (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/src/output.ts (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/src/process.ts (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/tests/subprocess.spec.ts (100%)
 rename packages/{subprocess => e2b}/subprocess-e2b/tsconfig.json (84%)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 46f1849b07..5ed4e445b8 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 730e6f0e1958ccab43a5a6a11931f9407b38ef16
-2026-07-27-e2b-remote-runtime-poc.zh.md: 5f1ae07b985787a7dc1bd61f2a5b7ff0512d85c1
+2026-07-27-e2b-remote-runtime-poc.md: a713cca3fd9e7ee11a2c487bf6ed2c3a205dc502
+2026-07-27-e2b-remote-runtime-poc.zh.md: 7afd54f72622d51a3d71719b3b4975ccd7f83e3a
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index 730e6f0e19..a713cca3fd 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -6,29 +6,43 @@ English | [中文](2026-07-27-e2b-remote-runtime-poc.zh.md)
 
 ## Problem
 
-A remote coding-agent backend is useful only when file operations and commands observe one coherent world. Attaching E2B independently at individual tools would allow a Bash command and a filesystem edit to address different sandboxes, while moving the complete harness into a remote VM would couple provider experimentation to agent, session, model, persistence, and deployment changes.
+A remote coding-agent backend is useful only when filesystem operations, one-shot commands, persistent terminals, language servers, and model-written programs observe one coherent world. Attaching E2B independently at individual tools would let those capabilities address different sandboxes, while retaining host PTY, LSP, or worker backends would split state across machines even when the cwd strings match.
+
+Moving the complete harness into a remote VM would unify that state but also couple provider experimentation to plugin loading, credentials, model transport, agent/session durability, supervision, and deployment. The POC needs to test the existing capability boundaries without taking on those independent concerns.
 
 ## Decision
 
-The E2B integration is a provider-composition POC with one shared lifecycle owner and two capability implementations:
+The E2B integration is an opt-in provider-composition POC. Its six E2B-specific packages live under `packages/e2b/` while retaining seam-specific npm names:
 
 - `@deepseek-ai/dsh-e2b` creates or reconnects one secure E2B sandbox, creates its working and private runtime directories, and owns kill/pause/leave disposal.
 - `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
 - `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands and remote Linux process groups.
+- `@deepseek-ai/dsh-pty-e2b` registers an E2B byte-PTY backend on `ctx.pty` while the existing registry retains exact-Agent ownership.
+- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through E2B Filesystem APIs, and runs servers through `dsh-subprocess-e2b`.
+- `@deepseek-ai/dsh-code-runtime-e2b` registers `ctx.codeRuntime`, runs each model program in a fresh remote worker, and dispatches binding functions in the host process.
 - The existing `@deepseek-ai/dsh-bash-local` remains the Bash implementation because it delegates all process mechanics to `ctx.subprocess`.
-- PTY, LSP, and Code Runtime remain separate capability providers over the same owner, with their runtime split recorded in the [extension decision](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
 
-The owner is the sole source of sandbox identity. Providers inject it and never create private sandboxes. The composition therefore gives filesystem tools and Bash one remote cwd, process namespace, and spill/state directory while preserving the existing capability interfaces and model-facing tools.
+The owner is the sole source of sandbox identity. Providers inject it and never create private sandboxes, so filesystem tools, Bash, interactive shells, language servers, and code workers share one remote cwd, process namespace, and adapter-private directory while preserving the existing capability interfaces and model-facing tools.
+
+The providers reuse the PTY, LSP, Code Runtime, and subprocess seams without changing their model-facing consumers or the agent loop. Backend-neutral PTY text handling lives in `dsh-pty`; the LSP protocol engine accepts `processId: null` for a server in another process namespace; Code Runtime exports its output-ledger and lossless-JSON helpers for backend parity.
 
 ## POC boundary
 
-Filesystem state, managed commands, interactive shells, language servers, code workers, and adapter-owned files move into E2B. The host retains Cordis and plugin objects, the agent loop, agent/session state, session logs and persistence, model requests, skills, subagent orchestration, capability protocol state, and E2B SDK buffers. The overlay does not upload or mount the host workspace; identical cwd strings name independent host and remote directories. Managed process groups still terminate and join when their provider disposes, including before a retained-sandbox pause or leave disposition.
+E2B owns the mutable filesystem, command and Bash processes, PTY shell and foreground process groups, language-server processes and source reads, the Code Runtime runner and worker, and adapter-private files under `.dsh-e2b`.
 
-The POC has no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, or workspace synchronization. Retained sandbox reconnect proves lifecycle continuity only; it does not reconstruct host PTY/LSP/code-runtime state, process handles, output cursors, pending calls, or locks.
+The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
+
+Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP and Code Runtime install dependency-free remote helpers that encode raw payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
+
+Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
+
+The POC has no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, workspace synchronization, durable remote handles, or whole-harness execution.
 
 ## Verification
 
-Package tests pin lifecycle cleanup, filesystem semantics, subprocess groups, byte framing, PTY readiness/signals, LSP transport and containment, Code Runtime binding/output behavior, and package-owned invariant registrations. A credential-gated real Loader composition creates one sandbox, exercises filesystem, Bash/subprocess, PTY, LSP, and Code Runtime through source and built package paths, proves host-workspace isolation, disposes the composition, and confirms the sandbox id is gone.
+Focused package suites pin owner lifecycle cleanup, filesystem semantics, subprocess process groups, configuration and publication rollback, byte framing and multibyte boundaries, PTY readiness/signals, LSP transport and source containment, Code Runtime bindings, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
+
+A credential-gated Loader composition creates one real E2B sandbox and exercises FS-to-Bash and Bash-to-FS visibility, multibyte PTY output and `SIGINT`, multibyte LSP hover and definition results, Code Runtime host bindings and typed rejection under mutation of adapter-captured intrinsics, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same scenario runs through source imports and built package exports.
 
 ## Alternatives considered
 
@@ -40,8 +54,16 @@ Package tests pin lifecycle cleanup, filesystem semantics, subprocess groups, by
 
 **Implement filesystem operations through shell commands only** — rejected because that bypasses `ctx.fs` identity, structured errors, version guards, streaming reads, and atomic mutation semantics already consumed by the file tools.
 
+**Use the host PTY, LSP, and worker backends unchanged** — rejected because they use host process and filesystem APIs; sharing an absolute cwd string does not share state across machines.
+
+**Expose E2B Commands as one generic transport and bypass capability providers** — rejected because PTY needs byte callbacks and foreground signaling, LSP needs byte-faithful stdio plus remote source containment, and Code Runtime needs bidirectional host binding calls and hostile-peer validation. Bypassing their registries would also fork model-facing behavior.
+
+**Add a generic distributed-runtime abstraction first** — rejected because the existing capability seams already carry the required contracts. A new cross-cutting interface would speculate about persistence, synchronization, and reconnect semantics beyond the POC.
+
+**Restore live capability handles after `sandboxId` reconnect** — rejected because remote identity alone cannot reconstruct host callbacks, pending promises, authority, protocol state, or output cursors. Claiming continuity would make stale remote processes appear managed when they are not.
+
 ## Consequences
 
-The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual state retention for experiments, while kill remains the demo's cleanup policy.
+The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
 
-The provider is not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
+The providers are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a captured remote process group does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 5f1ae07b98..7afd54f726 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -6,29 +6,43 @@ Status: implemented
 
 ## 问题
 
-远程 coding agent（智能体）后端只有在文件操作与命令观察到同一个一致环境时才有用。若在各工具上分别接入 E2B，Bash 命令和文件系统编辑可能访问不同的沙箱；若把完整 harness 迁入远程 VM，则会把提供方实验与 agent、会话、模型、持久化及部署变更耦合在一起。
+远程 coding agent（智能体）后端只有在文件系统操作、一次性命令、持久终端、语言服务器和模型编写的程序观察到同一个一致环境时才有用。若在各工具上分别接入 E2B，这些功能可能访问不同的沙箱；即使 cwd 字符串相同，保留宿主 PTY、LSP 或 worker 后端也会让状态分散在不同机器上。
+
+把完整 harness 迁入远程 VM 可以统一这些状态，但也会把提供方实验与插件加载、凭据、模型传输、agent／会话持久性、监管和部署耦合在一起。这个 POC 只需测试现有功能边界，不应把这些彼此独立的问题纳入范围。
 
 ## 决策
 
-E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和两个功能实现组成：
+E2B 集成是一个选择性启用的提供方组合 POC。它的 6 个 E2B 专用包（package）位于 `packages/e2b/` 下，同时保留按 seam 区分的 npm 名称：
 
 - `@deepseek-ai/dsh-e2b` 创建或重新连接一个安全的 E2B 沙箱，创建其工作目录与私有运行时目录，并拥有 kill/pause/leave 资源释放操作。
 - `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
 - `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands 和远程 Linux 进程组之上实现 `ctx.subprocess`。
+- `@deepseek-ai/dsh-pty-e2b` 在 `ctx.pty` 上注册 E2B 字节 PTY 后端，并把精确的 Agent 所有权保留在现有注册表中。
+- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B Filesystem API 读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
+- `@deepseek-ai/dsh-code-runtime-e2b` 注册 `ctx.codeRuntime`，在全新的远程 worker 中运行每个模型程序，并在宿主进程中分发绑定函数。
 - 现有的 `@deepseek-ai/dsh-bash-local` 继续作为 Bash 实现，因为它把所有进程机制委托给 `ctx.subprocess`。
-- PTY、LSP 与 Code Runtime 仍是基于同一所有者的独立功能提供方；其运行时划分见[扩展决策](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)。
 
-该所有者是沙箱身份的唯一真源。提供方会注入该所有者，绝不创建私有沙箱。因此，该组合让文件系统工具与 Bash 共享一个远程 cwd、进程命名空间和 spill／状态目录，同时保留现有功能接口与面向模型的工具。
+该所有者是沙箱身份的唯一真源。提供方会注入该所有者，绝不创建私有沙箱，因此文件系统工具、Bash、交互式 shell、语言服务器和代码 worker 会共享一个远程 cwd、进程命名空间和适配器私有目录，同时保留现有功能接口与面向模型的工具。
+
+这些提供方复用 PTY、LSP、Code Runtime 与进程管理 seam，不更改面向模型的消费方或 agent loop（智能体循环）。后端无关的 PTY 文本处理位于 `dsh-pty`；LSP 协议引擎允许位于另一个进程命名空间的服务器使用 `processId: null`；Code Runtime 导出输出账本与无损 JSON 辅助函数，以保持各后端一致。
 
 ## POC 边界
 
-文件系统状态、受管命令、交互式 shell、语言服务器、代码 worker 和适配器拥有的文件会迁入 E2B。宿主仍保留 Cordis 和插件对象、agent loop（智能体循环）、agent／会话状态、会话日志及其持久化、模型请求、skill（技能）、subagent 编排、功能协议状态和 E2B SDK 缓冲。该 overlay 不会上传或挂载宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。受管进程组仍会在所属提供方 dispose（资源释放）时终止并等待退出，包括保留沙箱采用 `pause` 或 `leave` 处置方式之前。
+E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程组、语言服务器进程及源码读取、Code Runtime 运行器和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
 
-本 POC 没有会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录或工作区同步。保留沙箱后重新连接只能证明生命周期连续性；它不会重建宿主 PTY／LSP／Code Runtime 状态、进程句柄、输出游标、待处理调用或锁。
+宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
+
+对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 与 Code Runtime 会安装无依赖的远程辅助程序，把原始载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
+
+保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
+
+本 POC 没有会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录、工作区同步、持久远程句柄或完整 harness 执行。
 
 ## 验证
 
-包测试固定生命周期清理、文件系统语义、进程管理的进程组、字节分帧、PTY 就绪状态／信号、LSP 传输与源码路径约束、Code Runtime 绑定／输出行为，以及包自有不变式注册。凭据门控的真实 Loader 组合会创建一个沙箱，通过源代码与已构建包路径演练文件系统、Bash／进程管理、PTY、LSP 和 Code Runtime，证明宿主工作区隔离，释放组合，并确认该沙箱 id 已不存在。
+聚焦包测试套件固定所有者生命周期清理、文件系统语义、进程管理的进程组、配置与发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号、LSP 传输与源码路径约束、Code Runtime 绑定、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
+
+凭据门控的 Loader 组合会创建一个真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、多字节 PTY 输出和 `SIGINT`、多字节 LSP 悬停与定义结果、Code Runtime 宿主绑定，以及适配器已捕获 intrinsic 被修改时的类型化 reject、墙钟超时、中止、运行器清理、宿主工作区隔离，以及最终删除沙箱。同一场景分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
@@ -40,8 +54,16 @@ E2B 集成是一个提供方组合 POC，由一个共享生命周期所有者和
 
 **仅通过 shell 命令实现文件系统操作。** 不予采纳，因为这会绕过文件工具已经使用的 `ctx.fs` 身份、结构化错误、版本防护、流式读取和原子变更语义。
 
+**原样使用宿主 PTY、LSP 与 worker 后端。** 不予采纳，因为它们使用宿主的进程与文件系统 API；在不同机器上复用同一个绝对 cwd 字符串并不会共享状态。
+
+**把 E2B Commands 公开为通用传输并绕过功能提供方。** 不予采纳，因为 PTY 需要字节回调和前台信号，LSP 需要字节保真的 stdio 与远程源码路径约束，Code Runtime 则需要双向宿主绑定调用与不可信对等方验证。绕过其注册表还会使面向模型的行为产生分叉。
+
+**先添加通用分布式运行时抽象。** 不予采纳，因为现有功能 seam 已承载所需契约。新的跨领域接口会预先假定 POC 范围之外的持久化、同步与重连语义。
+
+**在 `sandboxId` 重连后恢复活动功能句柄。** 不予采纳，因为只有远程身份，无法重建宿主回调、待处理 promise、权限、协议状态或输出游标。若声称保持连续性，就会让陈旧的远程进程看似仍受管理，实际并非如此。
+
 ## 后果
 
-这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留状态，演示仍以 `kill` 作为清理策略。
+这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
 
-该提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
+这些提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离已捕获远程进程组的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml
deleted file mode 100644
index e34f939a7f..0000000000
--- a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-28-e2b-interactive-semantic-code-runtime-poc.md
-2026-07-28-e2b-interactive-semantic-code-runtime-poc.md: befaa47dd56b7f425e72978ae040bd0815cc9f92
-2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md: 677c3a09f6846320d3e000e9607becb3dee865cf
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
deleted file mode 100644
index befaa47dd5..0000000000
--- a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Agent Note: E2B interactive, semantic, and code-runtime POC
-
-Status: implemented
-
-English | [中文](2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md)
-
-## Problem
-
-The [shared E2B runtime](2026-07-27-e2b-remote-runtime-poc.md) proves that filesystem operations and one-shot commands can inhabit one remote coding world, but an assembled coding agent also uses persistent terminals, language servers, and model-written Code Mode programs. Falling back to host implementations for those capabilities splits observable state: a Bash edit exists in E2B while a host PTY, LSP process, or code worker addresses a different filesystem and process namespace.
-
-Moving the complete harness process into E2B would unify that state but also changes plugin loading, credentials, model transport, session durability, supervision, and deployment. The POC needs to test the existing capability boundaries without taking on those independent concerns.
-
-## Decision
-
-Three opt-in providers extend the existing shared sandbox:
-
-- `@deepseek-ai/dsh-pty-e2b` registers an E2B byte-PTY backend on `ctx.pty` and keeps exact-Agent ownership in the existing registry.
-- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through E2B Filesystem APIs, and runs servers through `dsh-subprocess-e2b`.
-- `@deepseek-ai/dsh-code-runtime-e2b` registers `ctx.codeRuntime`, runs each model program in a fresh remote worker, and dispatches binding functions in the host process.
-
-All three inject `ctx.e2b`; none creates another sandbox. The opt-in overlay composes them with `dsh-fs-e2b`, `dsh-subprocess-e2b`, and the existing `dsh-bash-local`, so files, foreground commands, interactive shell processes, language servers, and code workers observe one remote cwd.
-
-The providers reuse the PTY, LSP, Code Runtime, and subprocess seams without changing their model-facing consumers or the agent loop. Backend-neutral PTY text handling moves into `dsh-pty`; the LSP protocol engine accepts `processId: null` for a server in another process namespace; Code Runtime exports its output-ledger and lossless-JSON helpers for backend parity.
-
-## Runtime boundary
-
-E2B owns the mutable filesystem, command and Bash processes, PTY shell and foreground process groups, language-server processes and source reads, the Code Runtime runner and worker, and adapter-private files under `.dsh-e2b`.
-
-The host owns Cordis and plugin objects, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The host workspace is not mounted or synchronized merely because its absolute cwd string is reused remotely.
-
-Byte-sensitive protocols use the narrowest adapter needed for E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP and Code Runtime install dependency-free remote helpers that encode raw payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
-
-Retaining a sandbox preserves remote files and any unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups are terminated and awaited when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
-
-## Verification
-
-Focused unit suites pin configuration, publication rollback, byte framing, multibyte boundaries, readiness, signals, timeout/abort ordering, output limits, hostile Code Runtime traffic, and disposal to quiescence. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
-
-A credential-gated Loader composition creates one real E2B sandbox and exercises FS-to-Bash and Bash-to-FS visibility, multibyte PTY output and `SIGINT`, multibyte LSP hover and definition results, Code Runtime host bindings and typed rejection under mutation of adapter-captured intrinsics, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same scenario runs through source imports and built package exports.
-
-## Alternatives considered
-
-**Run the complete harness inside E2B** — rejected because it couples this provider experiment to credentials, LLM transport, plugin deployment, session persistence, supervision, and remote package installation. None is necessary to prove the capability seams.
-
-**Use the host PTY, LSP, and worker backends unchanged** — rejected because they use host process and filesystem APIs; sharing an absolute cwd string does not share state across machines.
-
-**Expose E2B Commands as one generic transport and bypass capability providers** — rejected because PTY needs byte callbacks and foreground signaling, LSP needs byte-faithful stdio plus remote source containment, and Code Runtime needs bidirectional host binding calls and hostile-peer validation. Bypassing their registries would also fork model-facing behavior.
-
-**Add a generic distributed-runtime abstraction first** — rejected because the three existing capability seams already carry the required contracts. A new cross-cutting interface would speculate about persistence, synchronization, and reconnect semantics beyond the POC.
-
-**Restore live capability handles after `sandboxId` reconnect** — rejected because remote identity alone cannot reconstruct host callbacks, pending promises, authority, protocol state, or output cursors. Claiming continuity would make stale remote processes appear managed when they are not.
-
-## Consequences
-
-The assembled POC keeps the coding world remote without moving the agent runtime or changing model-visible tool contracts. It demonstrates that PTY, LSP, and Code Runtime can share E2B state through existing plugins, while making the remaining host state explicit.
-
-This is not a deployment platform. Language-server installation, templates, volumes, snapshots, network policy, workspace synchronization, durable remote handles, and whole-harness execution remain outside scope. E2B SDK buffering and host protocol state remain memory costs. Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a captured remote process group is not made reconnectable or owned by this composition.
diff --git a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
deleted file mode 100644
index 677c3a09f6..0000000000
--- a/.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.zh.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Agent Note: E2B 交互式、语义与代码运行时 POC
-
-Status: implemented
-
-[English](2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) | 中文
-
-## 问题
-
-[共享 E2B 运行时](2026-07-27-e2b-remote-runtime-poc.md)证明，文件系统操作与一次性命令可以共处一个远程 coding 环境，但组装完成的 coding agent（智能体）还会使用持久终端、语言服务器，以及模型编写的 Code Mode 程序。若这些功能回退到宿主实现，可观测状态就会分裂：Bash 修改存在于 E2B 中，而宿主 PTY、LSP 进程或代码 worker 面向的却是另一个文件系统与进程命名空间。
-
-把完整 harness 进程迁入 E2B 可以统一这些状态，但也会改变插件加载、凭据、模型传输、会话持久性、监管和部署。这个 POC 只需测试现有功能边界，不应把这些彼此独立的问题纳入范围。
-
-## 决策
-
-三个可选提供方扩展现有共享沙箱：
-
-- `@deepseek-ai/dsh-pty-e2b` 在 `ctx.pty` 上注册 E2B 字节 PTY 后端，并把精确的 Agent 所有权保留在现有注册表中。
-- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B Filesystem API 读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
-- `@deepseek-ai/dsh-code-runtime-e2b` 注册 `ctx.codeRuntime`，在全新的远程 worker 中运行每个模型程序，并在宿主进程中分发绑定函数。
-
-三个提供方均注入 `ctx.e2b`，无一创建其他沙箱。可选叠加配置将它们与 `dsh-fs-e2b`、`dsh-subprocess-e2b` 和现有的 `dsh-bash-local` 组合，使文件、前台命令、交互式 shell 进程、语言服务器和代码 worker 观察到同一个远程 cwd。
-
-这些提供方复用 PTY、LSP、Code Runtime 与进程管理 seam，不更改面向模型的消费方或 agent loop（智能体循环）。后端无关的 PTY 文本处理移入 `dsh-pty`；LSP 协议引擎允许位于另一个进程命名空间的服务器使用 `processId: null`；Code Runtime 导出输出账本与无损 JSON 辅助函数，以保持各后端一致。
-
-## 运行时边界
-
-E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程组、语言服务器进程及源码读取、Code Runtime 运行器和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
-
-宿主拥有 Cordis 与插件对象、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。宿主工作区不会仅因远程复用了其绝对 cwd 字符串就被挂载或同步。
-
-对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 与 Code Runtime 会安装无依赖的远程辅助程序，把原始载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
-
-保留沙箱只会保存远程文件与任何未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
-
-## 验证
-
-聚焦单元测试固定配置、发布回滚、字节分帧、多字节边界、就绪状态、信号、超时／中止顺序、输出上限、恶意 Code Runtime 通信，以及等待完全停稳的资源释放。相邻本地后端测试固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
-
-凭据门控的 Loader 组合会创建一个真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、多字节 PTY 输出和 `SIGINT`、多字节 LSP 悬停与定义结果、Code Runtime 宿主绑定，以及适配器已捕获 intrinsic 被修改时的类型化 reject、墙钟超时、中止、运行器清理、宿主工作区隔离，以及最终删除沙箱。同一场景分别通过源代码导入与已构建包导出运行。
-
-## 曾考虑的替代方案
-
-**在 E2B 内运行完整 harness。** 不予采纳，因为这会把这项提供方实验与凭据、LLM 传输、插件部署、会话持久化、监管和远程包安装耦合。要证明功能 seam，无需引入任何一项。
-
-**原样使用宿主 PTY、LSP 与 worker 后端。** 不予采纳，因为它们使用宿主的进程与文件系统 API；在不同机器上复用同一个绝对 cwd 字符串并不会共享状态。
-
-**把 E2B Commands 公开为通用传输并绕过功能提供方。** 不予采纳，因为 PTY 需要字节回调和前台信号，LSP 需要字节保真的 stdio 与远程源码路径约束，Code Runtime 则需要双向宿主绑定调用与不可信对等方验证。绕过其注册表还会使面向模型的行为产生分叉。
-
-**先添加通用分布式运行时抽象。** 不予采纳，因为现有三个功能 seam 已承载所需契约。新的跨领域接口会预先假定 POC 范围之外的持久化、同步与重连语义。
-
-**在 `sandboxId` 重连后恢复活动功能句柄。** 不予采纳，因为只有远程身份，无法重建宿主回调、待处理 promise、权限、协议状态或输出游标。若声称保持连续性，就会让陈旧的远程进程看似仍受管理，实际并非如此。
-
-## 后果
-
-组装后的 POC 在不迁移 agent 运行时、不改变模型可见工具契约的前提下，把 coding 环境保留在远程。它证明 PTY、LSP 与 Code Runtime 可以通过现有插件共享 E2B 状态，同时明确列出仍留在宿主的状态。
-
-这不是部署平台。语言服务器安装、模板、卷、快照、网络策略、工作区同步、持久远程句柄和完整 harness 执行仍不在范围内。E2B SDK 缓冲与宿主协议状态仍会占用内存。模型程序与 Node worker 内部机制共享一个 JavaScript realm；有意逃离已捕获远程进程组的进程，也不会因此变得可重新连接或由该组合管理。
diff --git a/AGENTS.md b/AGENTS.md
index 64f2e944a8..c663a5e099 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,10 +12,9 @@ DeepSeek Harness SDK is a plugin-based agent harness on vendored Cordis: **every
 vendor/      Vendored Cordis source — manifest + sync procedure in vendor/README.md
 packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
-  api/         Remote BFF assembly and TypeRT RPC gateway
-  typert/      type graph generator, loader, and runtime registry
   llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
-  bash/        bash executor seam + local/pwsh impls + model-facing shell tools
+  e2b/         remote-runtime POC
+  bash/        bash executor seam + local impl + model-facing bash tools
   subprocess/  subprocess seam + local process-tree impl
   pty/         persistent PTY seam/backend/tools
   fs/          filesystem seam + local impl + policy gate + read/write/edit tools
@@ -25,7 +24,6 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   compact/     compaction seam + basic backend
   context/     request-context plugins
   subagent/    subagent seam + spawn/fork/ACP backends + delegation tool
-  bundle/      profile plugin bundles: installable patch layers for dsh --profile
   workflow/    workflow seam + worker-thread engine + workflow tool
   todo/        todo_write tool
   plan/        plan mode as logged per-agent collaboration state
@@ -33,11 +31,9 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   cordis/      self-referential toolset: the agent inspects/mounts plugins in its own runtime
   hooks/       Claude Code/Codex hook bridges + shared wire-protocol library
   session-persistence/  persistence seam + JSONL/SQLite backends
-  settings/    user-settings seam + file-backed provider
-  credentials/ credential-reference seam + env-over-.env provider
   acp/         automation-only Agent Client Protocol server
-  ui/          JSON-RPC bridge; boot, approval, interaction plugins
-  examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load
+  ui/          TUI/JSON-RPC bridges; boot, approval, interaction plugins
+  examples/    demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load
   support/     dev/test infrastructure
   util/        zero-dependency utilities
 python/      Python SDK and bundled runtime (see python/README.md)
@@ -59,7 +55,7 @@ pnpm run clean           # remove build outputs and safe residue from deleted pa
 pnpm run test           # vitest unit tests
 pnpm run test:coverage  # CI coverage gate: per-file 100% on packages/*/*/src
 pnpm run test:e2e       # real-API tests; self-skip without DEEPSEEK_API_KEY
-pnpm run test:snapshot  # keyless ACP/headless replay vs expected outputs; filter: -t <name>
+pnpm run test:snapshot  # keyless ACP/headless/TUI replay vs expected outputs; filter: -t <name>
 pnpm run test:snapshot:record  # re-record expected outputs (needs key)
 pnpm run typecheck
 pnpm run lint
@@ -70,6 +66,7 @@ pnpm run hygiene        # knip + publint + workspace constraints + NodeNext cons
 pnpm run doc-sync       # all documentation gates; leaf list in scripts/run-gates.ts
 pnpm run website:build  # VitePress build (doubles as dead-link check)
 pnpm run demo:headless "task" # one-shot agent (needs DEEPSEEK_API_KEY)
+pnpm run demo:tui       # full-screen TUI coding agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:cordis    # the agent modifies its own runtime (needs key)
 pnpm run demo:acp       # ACP automation server (needs DEEPSEEK_API_KEY)
 ```
@@ -80,7 +77,7 @@ When required `gh`, `pnpm`, build, test, or generator commands fail because the
 
 ### Run relevant checks locally
 
-Run checks before pushes via [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md); report only commands run. After `gh stack sync`, validate immediately; do not merge before checks pass.
+Agents MUST run relevant tests and checks before pushing; select them with [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md) and report only commands run.
 
 - Match evidence to the surface: focused tests for behavior, snapshots for model or user output, `doc-sync` for docs, build/hygiene and built smokes for published paths, and real-API e2e for provider behavior.
 - Never default to the full suite or repeat a passing check for commit or push. CI owns exhaustive coverage and the platform matrix; rehearse all locally only by explicit request, for CI diagnosis, or for an irreducibly repository-wide change.
@@ -93,7 +90,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 ## Conventions
 
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
-- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only shapes) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
+- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. CI subprocesses that boot examples or Cordis configs run built `lib/` under plain Node; only explicit source-path regressions use tsx ([testing policy](docs/testing.md#test-subprocess-launch-modes)).
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
 - **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. If a package has no plausible relationship, an explained empty companion is correct ([package contract](packages/AGENTS.md)).
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns.
@@ -117,7 +114,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
-- **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
+- **Use incremental merge commits.** Split independent changes; never squash, rebase, or rewrite pushed history. Fix the introducing PR before merging down-stack. If the base advances mid-merge, never restart: finish the checkpoint, push when authorized, then merge the newer tip separately ([rationale](.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)).
 - **Label PRs:** one kind (`feature`/`bug-fix`/`doc`/`testing`/`cleanup`), each matching area; the [taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md) is extensible.
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 3eee08f35b..b8320d8c19 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 1b2a1737bcac33829a65fa937668ca9496035330
-README.zh.md: 2ef61e9c38750f4420ce99abc9943af1f3308b56
+README.md: c46a08f76f9f38f9620c03f05f28e7698487afc8
+README.zh.md: 65a5c6c88b9b37b3f948b11c6db778e42965643d
diff --git a/packages/README.md b/packages/README.md
index 54a5779016..b2a870f516 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -16,7 +16,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
-| [`e2b/`](e2b/README.md) | E2B remote filesystem/process providers | POC |
+| [`e2b/`](e2b/README.md) | E2B remote-runtime provider family | POC |
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 46b112ec8f..c8079c3d03 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -16,7 +16,7 @@
 | [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
-| [`e2b/`](e2b/README.md) | E2B 远程文件系统／进程管理提供方 | POC |
+| [`e2b/`](e2b/README.md) | E2B 远程运行时提供方系列 | POC |
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml
index f9160b4f8e..30c5ca2572 100644
--- a/packages/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/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/code-runtime/README.md
-README.md: f59fc3b15331b4799cbc7a3fbe27ce8cd9a12e51
-README.zh.md: 02ade97887fab8a8a0c22efcf73bb2dd1f2cf33c
+README.md: 34eecc4874afc5a576ed129e72eeeb944b95f67f
+README.zh.md: 85d7a95a37cd1f4090062f3036a6634fde5011ee
diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md
index f59fc3b153..34eecc4874 100644
--- a/packages/code-runtime/README.md
+++ b/packages/code-runtime/README.md
@@ -8,6 +8,6 @@ The code-execution capability seam (see [capability seams](../../.agents/notes/i
 |---|---|---|
 | `code-runtime/` | Abstract code-execution seam (interface + vocabulary) | `ctx.codeRuntime` |
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend: fresh worker per run, TypeScript via host-side type-strip (annotations advisory, never type-checked), port-bridged bindings, budget/heap containment | registers `ctx.codeRuntime` |
-| [`code-runtime-e2b/`](code-runtime-e2b/README.md) | E2B backend: host type-strip and bindings, fresh remote runner/worker, framed bridge, remote process-group cleanup | registers `ctx.codeRuntime` |
+| [`e2b/code-runtime-e2b`](../e2b/code-runtime-e2b/README.md) | E2B backend: host type-strip and bindings, fresh remote runner/worker, framed bridge, remote process-group cleanup | registers `ctx.codeRuntime` |
 
-Backends differ by execution substrate and source language—both readonly descriptors on the service—and register `ctx.codeRuntime` without touching the interface or its consumer. The E2B ownership split is recorded in the [remote extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
+Backends differ by execution substrate and source language—both readonly descriptors on the service—and register `ctx.codeRuntime` without touching the interface or its consumer. The E2B ownership split is recorded in the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md).
diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md
index 02ade97887..85d7a95a37 100644
--- a/packages/code-runtime/README.zh.md
+++ b/packages/code-runtime/README.zh.md
@@ -8,6 +8,6 @@
 |---|---|---|
 | `code-runtime/` | 抽象代码执行 seam（接口 + 词汇） | `ctx.codeRuntime` |
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | worker 线程后端：每次运行使用全新 worker，由宿主侧剥离 TypeScript 类型（类型注解仅供参考，绝不执行类型检查）、端口桥接绑定、预算／堆隔离 | 注册 `ctx.codeRuntime` |
-| [`code-runtime-e2b/`](code-runtime-e2b/README.md) | E2B 后端：宿主侧类型剥离与绑定、全新远程 runner／worker、分帧桥、远程进程组清理 | 注册 `ctx.codeRuntime` |
+| [`e2b/code-runtime-e2b`](../e2b/code-runtime-e2b/README.md) | E2B 后端：宿主侧类型剥离与绑定、全新远程 runner／worker、分帧桥、远程进程组清理 | 注册 `ctx.codeRuntime` |
 
-不同后端的执行基底和源语言各异，二者都是服务上的只读描述符；后端注册 `ctx.codeRuntime`，无需修改接口或消费方。E2B 所有权拆分记录在[远程扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) 中。
+不同后端的执行基底和源语言各异，二者都是服务上的只读描述符；后端注册 `ctx.codeRuntime`，无需修改接口或消费方。E2B 所有权拆分记录在[共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) 中。
diff --git a/packages/code-runtime/code-runtime-e2b/README.i18n.yaml b/packages/code-runtime/code-runtime-e2b/README.i18n.yaml
deleted file mode 100644
index c00b40f4a2..0000000000
--- a/packages/code-runtime/code-runtime-e2b/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/code-runtime/code-runtime-e2b/README.md
-README.md: bf26174c59c1df18f63278acb7923fd409860b44
-README.zh.md: c87945da30a6f8d77eb3722879510bb6159b3ee8
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 444145fbb8..1ded2a1d34 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: 9e7f1a98ada9f56f3d1e3f74d2a906f8a1c7bc15
-README.zh.md: 53fdf30eaf405ab5313274a7fadde0b044b7fba1
+README.md: b25f00fb5f32643008127f0cee4f3d758018404a
+README.zh.md: fc3d6901f3cdf6c645cfde49dc46108759959aca
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index 9e7f1a98ad..b25f00fb5f 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -7,10 +7,10 @@ An experimental provider-composition POC that places the mutable coding world in
 | Package | ctx key | Role |
 |---|---|---|
 | [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create or reconnect one sandbox, create its working/runtime directories, expose the shared SDK handle, and apply the configured kill/pause/leave disposition |
-| [`fs-e2b`](../fs/fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
-| [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement managed process groups, stdio projection, and remote spill files over E2B Commands |
-| [`pty-e2b`](../pty/pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | `ctx.pty` backend | Run persistent interactive shells through E2B's byte PTY API |
-| [`lsp-e2b`](../lsp/lsp-e2b/README.md) (`@deepseek-ai/dsh-lsp-e2b`) | `ctx.lsp` provider | Run configured language servers and read query sources inside E2B |
-| [`code-runtime-e2b`](../code-runtime/code-runtime-e2b/README.md) (`@deepseek-ai/dsh-code-runtime-e2b`) | `ctx.codeRuntime` | Run model-written programs remotely while bridging bindings to the host |
+| [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
+| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement managed process groups, stdio projection, and remote spill files over E2B Commands |
+| [`pty-e2b`](pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | `ctx.pty` backend | Run persistent interactive shells through E2B's byte PTY API |
+| [`lsp-e2b`](lsp-e2b/README.md) (`@deepseek-ai/dsh-lsp-e2b`) | `ctx.lsp` provider | Run configured language servers and read query sources inside E2B |
+| [`code-runtime-e2b`](code-runtime-e2b/README.md) (`@deepseek-ai/dsh-code-runtime-e2b`) | `ctx.codeRuntime` | Run model-written programs remotely while bridging bindings to the host |
 
-The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, protocol state, or E2B SDK buffers. The [base decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) and [runtime-extension decision](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) own the POC boundary.
+The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, protocol state, or E2B SDK buffers. The [shared-runtime decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index 53fdf30eaf..fc3d6901f3 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -7,10 +7,10 @@
 | 包（package） | ctx 键 | 职责 |
 |---|---|---|
 | [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建或重新连接一个沙箱，创建其工作目录与运行时目录，公开共享 SDK 句柄，并应用配置的 kill/pause/leave 处置方式 |
-| [`fs-e2b`](../fs/fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
-| [`subprocess-e2b`](../subprocess/subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 实现受管进程组、stdio 投影与远程 spill 文件 |
-| [`pty-e2b`](../pty/pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | `ctx.pty` 后端 | 通过 E2B 的字节 PTY API 运行持久交互式 shell |
-| [`lsp-e2b`](../lsp/lsp-e2b/README.md)（`@deepseek-ai/dsh-lsp-e2b`） | `ctx.lsp` 提供方 | 在 E2B 内运行已配置的语言服务器并读取查询源代码 |
-| [`code-runtime-e2b`](../code-runtime/code-runtime-e2b/README.md)（`@deepseek-ai/dsh-code-runtime-e2b`） | `ctx.codeRuntime` | 远程运行模型编写的程序，同时把绑定桥接到宿主 |
+| [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
+| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 实现受管进程组、stdio 投影与远程 spill 文件 |
+| [`pty-e2b`](pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | `ctx.pty` 后端 | 通过 E2B 的字节 PTY API 运行持久交互式 shell |
+| [`lsp-e2b`](lsp-e2b/README.md)（`@deepseek-ai/dsh-lsp-e2b`） | `ctx.lsp` 提供方 | 在 E2B 内运行已配置的语言服务器并读取查询源代码 |
+| [`code-runtime-e2b`](code-runtime-e2b/README.md)（`@deepseek-ai/dsh-code-runtime-e2b`） | `ctx.codeRuntime` | 远程运行模型编写的程序，同时把绑定桥接到宿主 |
 
-现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、协议状态或 E2B SDK 缓冲。[基础决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)与[运行时扩展决策](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)共同界定 POC 边界。
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、协议状态或 E2B SDK 缓冲。[共享运行时决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)界定 POC 边界。
diff --git a/packages/subprocess/subprocess-e2b/README.i18n.yaml b/packages/e2b/code-runtime-e2b/README.i18n.yaml
similarity index 54%
rename from packages/subprocess/subprocess-e2b/README.i18n.yaml
rename to packages/e2b/code-runtime-e2b/README.i18n.yaml
index dfbe97e8b9..9eb2633b86 100644
--- a/packages/subprocess/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/code-runtime-e2b/README.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 packages/subprocess/subprocess-e2b/README.md
-README.md: 9ec1518103413f33a52023c17722bf5a5fe275ce
-README.zh.md: f50ff2f3d85a5ddd9bd352e95d0eb0a23e756404
+#   pnpm run verify-translation-pairing --write packages/e2b/code-runtime-e2b/README.md
+README.md: 1007800c59725d116197a52f6d087ea5e2860686
+README.zh.md: a56026bce760879079627dd63a80dfe95c4d2049
diff --git a/packages/code-runtime/code-runtime-e2b/README.md b/packages/e2b/code-runtime-e2b/README.md
similarity index 93%
rename from packages/code-runtime/code-runtime-e2b/README.md
rename to packages/e2b/code-runtime-e2b/README.md
index bf26174c59..1007800c59 100644
--- a/packages/code-runtime/code-runtime-e2b/README.md
+++ b/packages/e2b/code-runtime-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of [`ctx.codeRuntime`](../code-runtime/README.md). Each run executes one model-written TypeScript program in a fresh remote Node worker while binding functions, type stripping, output accounting, and lifecycle orchestration remain on the host.
+E2B implementation of [`ctx.codeRuntime`](../../code-runtime/code-runtime/README.md). Each run executes one model-written TypeScript program in a fresh remote Node worker while binding functions, type stripping, output accounting, and lifecycle orchestration remain on the host.
 
 ## Configuration
 
diff --git a/packages/code-runtime/code-runtime-e2b/README.zh.md b/packages/e2b/code-runtime-e2b/README.zh.md
similarity index 93%
rename from packages/code-runtime/code-runtime-e2b/README.zh.md
rename to packages/e2b/code-runtime-e2b/README.zh.md
index c87945da30..a56026bce7 100644
--- a/packages/code-runtime/code-runtime-e2b/README.zh.md
+++ b/packages/e2b/code-runtime-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`ctx.codeRuntime`](../code-runtime/README.md) 的 E2B 实现。每次运行都会在全新的远程 Node worker 中执行一段模型编写的 TypeScript 程序；绑定函数、类型剥离、输出记账和生命周期编排仍保留在宿主侧。
+[`ctx.codeRuntime`](../../code-runtime/code-runtime/README.md) 的 E2B 实现。每次运行都会在全新的远程 Node worker 中执行一段模型编写的 TypeScript 程序；绑定函数、类型剥离、输出记账和生命周期编排仍保留在宿主侧。
 
 ## 配置
 
diff --git a/packages/code-runtime/code-runtime-e2b/package.json b/packages/e2b/code-runtime-e2b/package.json
similarity index 100%
rename from packages/code-runtime/code-runtime-e2b/package.json
rename to packages/e2b/code-runtime-e2b/package.json
diff --git a/packages/code-runtime/code-runtime-e2b/src/index.ts b/packages/e2b/code-runtime-e2b/src/index.ts
similarity index 100%
rename from packages/code-runtime/code-runtime-e2b/src/index.ts
rename to packages/e2b/code-runtime-e2b/src/index.ts
diff --git a/packages/code-runtime/code-runtime-e2b/src/invariant.ts b/packages/e2b/code-runtime-e2b/src/invariant.ts
similarity index 100%
rename from packages/code-runtime/code-runtime-e2b/src/invariant.ts
rename to packages/e2b/code-runtime-e2b/src/invariant.ts
diff --git a/packages/code-runtime/code-runtime-e2b/src/runner-source.ts b/packages/e2b/code-runtime-e2b/src/runner-source.ts
similarity index 100%
rename from packages/code-runtime/code-runtime-e2b/src/runner-source.ts
rename to packages/e2b/code-runtime-e2b/src/runner-source.ts
diff --git a/packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
similarity index 100%
rename from packages/code-runtime/code-runtime-e2b/tests/runtime.spec.ts
rename to packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
diff --git a/packages/code-runtime/code-runtime-e2b/tsconfig.json b/packages/e2b/code-runtime-e2b/tsconfig.json
similarity index 70%
rename from packages/code-runtime/code-runtime-e2b/tsconfig.json
rename to packages/e2b/code-runtime-e2b/tsconfig.json
index 4ddc3b5ffe..3bc2e21873 100644
--- a/packages/code-runtime/code-runtime-e2b/tsconfig.json
+++ b/packages/e2b/code-runtime-e2b/tsconfig.json
@@ -9,11 +9,11 @@
     { "path": "../../../vendor/cosmokit" },
     { "path": "../../../vendor/cordis" },
     { "path": "../../../vendor/schemastery" },
-    { "path": "../code-runtime" },
-    { "path": "../code-runtime-worker" },
-    { "path": "../../e2b/e2b" },
+    { "path": "../../code-runtime/code-runtime" },
+    { "path": "../../code-runtime/code-runtime-worker" },
+    { "path": "../e2b" },
     { "path": "../../core/session" },
-    { "path": "../../subprocess/subprocess-e2b" },
+    { "path": "../subprocess-e2b" },
     { "path": "../../util/timeout" },
     { "path": "../../support/invariants" }
   ]
diff --git a/packages/fs/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
similarity index 56%
rename from packages/fs/fs-e2b/README.i18n.yaml
rename to packages/e2b/fs-e2b/README.i18n.yaml
index d3ea2786b2..b416105166 100644
--- a/packages/fs/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/README.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 packages/fs/fs-e2b/README.md
-README.md: 2b23884e345e7c39b0559465afa0bc588699b70a
-README.zh.md: 1a9a174ac90c59b68b02887303f58ee2a99dc72e
+#   pnpm run verify-translation-pairing --write packages/e2b/fs-e2b/README.md
+README.md: d8f3915fa281e8b9c062e3412c92bc6358616284
+README.zh.md: 93d27bcdd514ccbf87e07d0eff5958edf3c726c1
diff --git a/packages/fs/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
similarity index 81%
rename from packages/fs/fs-e2b/README.md
rename to packages/e2b/fs-e2b/README.md
index 2b23884e34..d8f3915fa2 100644
--- a/packages/fs/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-fs`](../fs/README.md) provider seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
+E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provider seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
 
 ## Behavior
 
@@ -15,7 +15,7 @@ The provider does not copy, mount, or reconcile the host workspace. Giving it a
 
 ## Model Experience
 
-Indirectly, through [`dsh-tool-fs`](../tool-fs/README.md), which renders remote UTF-8 content, directory results, mutation acknowledgements, and provider errors while E2B identity and transport remain internal.
+Indirectly, through [`dsh-tool-fs`](../../fs/tool-fs/README.md), which renders remote UTF-8 content, directory results, mutation acknowledgements, and provider errors while E2B identity and transport remain internal.
 
 #### KV Cache effect
 
diff --git a/packages/fs/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
similarity index 81%
rename from packages/fs/fs-e2b/README.zh.md
rename to packages/e2b/fs-e2b/README.zh.md
index 1a9a174ac9..93d27bcdd5 100644
--- a/packages/fs/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-fs`](../fs/README.md) 提供方 seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
+[`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) 提供方 seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
 
 ## 行为
 
@@ -15,7 +15,7 @@
 
 ## 模型体验
 
-通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接影响模型；该工具会渲染远程 UTF-8 内容、目录结果、变更确认和提供方错误，而 E2B 身份及传输保持内部实现。
+通过 [`dsh-tool-fs`](../../fs/tool-fs/README.md) 间接影响模型；该工具会渲染远程 UTF-8 内容、目录结果、变更确认和提供方错误，而 E2B 身份及传输保持内部实现。
 
 #### KV Cache 影响
 
diff --git a/packages/fs/fs-e2b/package.json b/packages/e2b/fs-e2b/package.json
similarity index 100%
rename from packages/fs/fs-e2b/package.json
rename to packages/e2b/fs-e2b/package.json
diff --git a/packages/fs/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
similarity index 100%
rename from packages/fs/fs-e2b/src/index.ts
rename to packages/e2b/fs-e2b/src/index.ts
diff --git a/packages/fs/fs-e2b/src/invariant.ts b/packages/e2b/fs-e2b/src/invariant.ts
similarity index 100%
rename from packages/fs/fs-e2b/src/invariant.ts
rename to packages/e2b/fs-e2b/src/invariant.ts
diff --git a/packages/fs/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
similarity index 100%
rename from packages/fs/fs-e2b/tests/filesystem.spec.ts
rename to packages/e2b/fs-e2b/tests/filesystem.spec.ts
diff --git a/packages/fs/fs-e2b/tsconfig.json b/packages/e2b/fs-e2b/tsconfig.json
similarity index 87%
rename from packages/fs/fs-e2b/tsconfig.json
rename to packages/e2b/fs-e2b/tsconfig.json
index c424efd2e5..bcb54a88d9 100644
--- a/packages/fs/fs-e2b/tsconfig.json
+++ b/packages/e2b/fs-e2b/tsconfig.json
@@ -13,10 +13,10 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../e2b/e2b"
+      "path": "../e2b"
     },
     {
-      "path": "../fs"
+      "path": "../../fs/fs"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/pty/pty-e2b/README.i18n.yaml b/packages/e2b/lsp-e2b/README.i18n.yaml
similarity index 60%
rename from packages/pty/pty-e2b/README.i18n.yaml
rename to packages/e2b/lsp-e2b/README.i18n.yaml
index bfd7795349..5f126d7e56 100644
--- a/packages/pty/pty-e2b/README.i18n.yaml
+++ b/packages/e2b/lsp-e2b/README.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 packages/pty/pty-e2b/README.md
-README.md: 7a8ddc9e08f4d28d69b97825232b00e2d8f394b7
-README.zh.md: 2151ca1f2d91b01a7b0106153f708ace2c3d2726
+#   pnpm run verify-translation-pairing --write packages/e2b/lsp-e2b/README.md
+README.md: ded928ec073e6c0943d574d86359eeec586bb862
+README.zh.md: 91eb7cecb49adcf73f4be948e9a5da400981e6f1
diff --git a/packages/lsp/lsp-e2b/README.md b/packages/e2b/lsp-e2b/README.md
similarity index 92%
rename from packages/lsp/lsp-e2b/README.md
rename to packages/e2b/lsp-e2b/README.md
index 968487b7c5..ded928ec07 100644
--- a/packages/lsp/lsp-e2b/README.md
+++ b/packages/e2b/lsp-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Generic E2B language-server backend for [`ctx.lsp`](../lsp/README.md). It runs configured stdio servers and reads their source documents inside the shared `ctx.e2b` sandbox; the provider registry, normalized query results, queues, and protocol connection state remain on the host.
+Generic E2B language-server backend for [`ctx.lsp`](../../lsp/lsp/README.md). It runs configured stdio servers and reads their source documents inside the shared `ctx.e2b` sandbox; the provider registry, normalized query results, queues, and protocol connection state remain on the host.
 
 ## Plugin and configuration
 
diff --git a/packages/lsp/lsp-e2b/README.zh.md b/packages/e2b/lsp-e2b/README.zh.md
similarity index 92%
rename from packages/lsp/lsp-e2b/README.zh.md
rename to packages/e2b/lsp-e2b/README.zh.md
index 2b937f0115..91eb7cecb4 100644
--- a/packages/lsp/lsp-e2b/README.zh.md
+++ b/packages/e2b/lsp-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-用于 [`ctx.lsp`](../lsp/README.md) 的通用 E2B 语言服务器后端。它在共享的 `ctx.e2b` 沙箱内运行已配置的 stdio 服务器并读取其源文档；提供方注册表、规范化查询结果、队列和协议连接状态仍保留在宿主侧。
+用于 [`ctx.lsp`](../../lsp/lsp/README.md) 的通用 E2B 语言服务器后端。它在共享的 `ctx.e2b` 沙箱内运行已配置的 stdio 服务器并读取其源文档；提供方注册表、规范化查询结果、队列和协议连接状态仍保留在宿主侧。
 
 ## 插件与配置
 
diff --git a/packages/lsp/lsp-e2b/package.json b/packages/e2b/lsp-e2b/package.json
similarity index 100%
rename from packages/lsp/lsp-e2b/package.json
rename to packages/e2b/lsp-e2b/package.json
diff --git a/packages/lsp/lsp-e2b/src/index.ts b/packages/e2b/lsp-e2b/src/index.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/src/index.ts
rename to packages/e2b/lsp-e2b/src/index.ts
diff --git a/packages/lsp/lsp-e2b/src/invariant.ts b/packages/e2b/lsp-e2b/src/invariant.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/src/invariant.ts
rename to packages/e2b/lsp-e2b/src/invariant.ts
diff --git a/packages/lsp/lsp-e2b/src/proxy-source.ts b/packages/e2b/lsp-e2b/src/proxy-source.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/src/proxy-source.ts
rename to packages/e2b/lsp-e2b/src/proxy-source.ts
diff --git a/packages/lsp/lsp-e2b/src/transport.ts b/packages/e2b/lsp-e2b/src/transport.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/src/transport.ts
rename to packages/e2b/lsp-e2b/src/transport.ts
diff --git a/packages/lsp/lsp-e2b/tests/provider.spec.ts b/packages/e2b/lsp-e2b/tests/provider.spec.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/tests/provider.spec.ts
rename to packages/e2b/lsp-e2b/tests/provider.spec.ts
diff --git a/packages/lsp/lsp-e2b/tests/transport.spec.ts b/packages/e2b/lsp-e2b/tests/transport.spec.ts
similarity index 100%
rename from packages/lsp/lsp-e2b/tests/transport.spec.ts
rename to packages/e2b/lsp-e2b/tests/transport.spec.ts
diff --git a/packages/lsp/lsp-e2b/tsconfig.json b/packages/e2b/lsp-e2b/tsconfig.json
similarity index 75%
rename from packages/lsp/lsp-e2b/tsconfig.json
rename to packages/e2b/lsp-e2b/tsconfig.json
index 4679845db8..a6c0fd8ece 100644
--- a/packages/lsp/lsp-e2b/tsconfig.json
+++ b/packages/e2b/lsp-e2b/tsconfig.json
@@ -9,11 +9,11 @@
     { "path": "../../../vendor/cosmokit" },
     { "path": "../../../vendor/cordis" },
     { "path": "../../../vendor/schemastery" },
-    { "path": "../../e2b/e2b" },
-    { "path": "../lsp" },
-    { "path": "../lsp-local" },
+    { "path": "../e2b" },
+    { "path": "../../lsp/lsp" },
+    { "path": "../../lsp/lsp-local" },
     { "path": "../../subprocess/subprocess" },
-    { "path": "../../subprocess/subprocess-e2b" },
+    { "path": "../subprocess-e2b" },
     { "path": "../../util/timeout" },
     { "path": "../../support/invariants" }
   ]
diff --git a/packages/lsp/lsp-e2b/README.i18n.yaml b/packages/e2b/pty-e2b/README.i18n.yaml
similarity index 60%
rename from packages/lsp/lsp-e2b/README.i18n.yaml
rename to packages/e2b/pty-e2b/README.i18n.yaml
index fa159820a9..1bd8485e8f 100644
--- a/packages/lsp/lsp-e2b/README.i18n.yaml
+++ b/packages/e2b/pty-e2b/README.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 packages/lsp/lsp-e2b/README.md
-README.md: 968487b7c5f63b2165cf66797a4182642507a8e9
-README.zh.md: 2b937f01156c3194f64ed9fb54478fec5c77305b
+#   pnpm run verify-translation-pairing --write packages/e2b/pty-e2b/README.md
+README.md: 3d363309f6bd1c4def5fbff668735958ca2de52d
+README.zh.md: 78d61cc654bf6eb46a3bec7124b3cc06cc7e34e9
diff --git a/packages/pty/pty-e2b/README.md b/packages/e2b/pty-e2b/README.md
similarity index 93%
rename from packages/pty/pty-e2b/README.md
rename to packages/e2b/pty-e2b/README.md
index 7a8ddc9e08..3d363309f6 100644
--- a/packages/pty/pty-e2b/README.md
+++ b/packages/e2b/pty-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-E2B byte-PTY backend for [`ctx.pty`](../pty/README.md). It creates persistent interactive shells inside the shared `ctx.e2b` sandbox while the PTY registry keeps session identity, exact-Agent ownership, and cleanup policy on the host.
+E2B byte-PTY backend for [`ctx.pty`](../../pty/pty/README.md). It creates persistent interactive shells inside the shared `ctx.e2b` sandbox while the PTY registry keeps session identity, exact-Agent ownership, and cleanup policy on the host.
 
 ## Plugin and configuration
 
diff --git a/packages/pty/pty-e2b/README.zh.md b/packages/e2b/pty-e2b/README.zh.md
similarity index 93%
rename from packages/pty/pty-e2b/README.zh.md
rename to packages/e2b/pty-e2b/README.zh.md
index 2151ca1f2d..78d61cc654 100644
--- a/packages/pty/pty-e2b/README.zh.md
+++ b/packages/e2b/pty-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-用于 [`ctx.pty`](../pty/README.md) 的 E2B 字节 PTY 后端。它在共享的 `ctx.e2b` 沙箱内创建持久交互式 shell；PTY 注册表则在宿主侧维护会话身份、精确的 Agent 所有权和清理策略。
+用于 [`ctx.pty`](../../pty/pty/README.md) 的 E2B 字节 PTY 后端。它在共享的 `ctx.e2b` 沙箱内创建持久交互式 shell；PTY 注册表则在宿主侧维护会话身份、精确的 Agent 所有权和清理策略。
 
 ## 插件与配置
 
diff --git a/packages/pty/pty-e2b/package.json b/packages/e2b/pty-e2b/package.json
similarity index 100%
rename from packages/pty/pty-e2b/package.json
rename to packages/e2b/pty-e2b/package.json
diff --git a/packages/pty/pty-e2b/src/config.ts b/packages/e2b/pty-e2b/src/config.ts
similarity index 100%
rename from packages/pty/pty-e2b/src/config.ts
rename to packages/e2b/pty-e2b/src/config.ts
diff --git a/packages/pty/pty-e2b/src/index.ts b/packages/e2b/pty-e2b/src/index.ts
similarity index 100%
rename from packages/pty/pty-e2b/src/index.ts
rename to packages/e2b/pty-e2b/src/index.ts
diff --git a/packages/pty/pty-e2b/src/invariant.ts b/packages/e2b/pty-e2b/src/invariant.ts
similarity index 100%
rename from packages/pty/pty-e2b/src/invariant.ts
rename to packages/e2b/pty-e2b/src/invariant.ts
diff --git a/packages/pty/pty-e2b/src/session.ts b/packages/e2b/pty-e2b/src/session.ts
similarity index 100%
rename from packages/pty/pty-e2b/src/session.ts
rename to packages/e2b/pty-e2b/src/session.ts
diff --git a/packages/pty/pty-e2b/tests/index.spec.ts b/packages/e2b/pty-e2b/tests/index.spec.ts
similarity index 100%
rename from packages/pty/pty-e2b/tests/index.spec.ts
rename to packages/e2b/pty-e2b/tests/index.spec.ts
diff --git a/packages/pty/pty-e2b/tests/session.spec.ts b/packages/e2b/pty-e2b/tests/session.spec.ts
similarity index 100%
rename from packages/pty/pty-e2b/tests/session.spec.ts
rename to packages/e2b/pty-e2b/tests/session.spec.ts
diff --git a/packages/pty/pty-e2b/tsconfig.json b/packages/e2b/pty-e2b/tsconfig.json
similarity index 85%
rename from packages/pty/pty-e2b/tsconfig.json
rename to packages/e2b/pty-e2b/tsconfig.json
index 0a7647aa80..06bf0cd589 100644
--- a/packages/pty/pty-e2b/tsconfig.json
+++ b/packages/e2b/pty-e2b/tsconfig.json
@@ -9,8 +9,8 @@
     { "path": "../../../vendor/cosmokit" },
     { "path": "../../../vendor/cordis" },
     { "path": "../../../vendor/schemastery" },
-    { "path": "../../e2b/e2b" },
-    { "path": "../pty" },
+    { "path": "../e2b" },
+    { "path": "../../pty/pty" },
     { "path": "../../support/invariants" }
   ]
 }
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
new file mode 100644
index 0000000000..26bc8f0b51
--- /dev/null
+++ b/packages/e2b/subprocess-e2b/README.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 packages/e2b/subprocess-e2b/README.md
+README.md: ce61de1100791be6e5c4db74c73ff43566281ed9
+README.zh.md: a4c619f0c002cc1d36310c5a9b4a3f7ae655ad1f
diff --git a/packages/subprocess/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
similarity index 89%
rename from packages/subprocess/subprocess-e2b/README.md
rename to packages/e2b/subprocess-e2b/README.md
index 9ec1518103..ce61de1100 100644
--- a/packages/subprocess/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing consumers such as [`dsh-bash-local`](../../bash/bash-local/README.md) then execute in the shared remote sandbox without an E2B-specific Bash adapter.
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing consumers such as [`dsh-bash-local`](../../bash/bash-local/README.md) then execute in the shared remote sandbox without an E2B-specific Bash adapter.
 
 ## Behavior
 
diff --git a/packages/subprocess/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
similarity index 89%
rename from packages/subprocess/subprocess-e2b/README.zh.md
rename to packages/e2b/subprocess-e2b/README.zh.md
index f50ff2f3d8..a4c619f0c0 100644
--- a/packages/subprocess/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../../e2b/e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。随后，[`dsh-bash-local`](../../bash/bash-local/README.md) 等现有消费方会在共享远程沙箱中执行，无需 E2B 专用 Bash 适配器。
+[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。随后，[`dsh-bash-local`](../../bash/bash-local/README.md) 等现有消费方会在共享远程沙箱中执行，无需 E2B 专用 Bash 适配器。
 
 ## 行为
 
diff --git a/packages/subprocess/subprocess-e2b/package.json b/packages/e2b/subprocess-e2b/package.json
similarity index 100%
rename from packages/subprocess/subprocess-e2b/package.json
rename to packages/e2b/subprocess-e2b/package.json
diff --git a/packages/subprocess/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
similarity index 100%
rename from packages/subprocess/subprocess-e2b/src/index.ts
rename to packages/e2b/subprocess-e2b/src/index.ts
diff --git a/packages/subprocess/subprocess-e2b/src/invariant.ts b/packages/e2b/subprocess-e2b/src/invariant.ts
similarity index 100%
rename from packages/subprocess/subprocess-e2b/src/invariant.ts
rename to packages/e2b/subprocess-e2b/src/invariant.ts
diff --git a/packages/subprocess/subprocess-e2b/src/output.ts b/packages/e2b/subprocess-e2b/src/output.ts
similarity index 100%
rename from packages/subprocess/subprocess-e2b/src/output.ts
rename to packages/e2b/subprocess-e2b/src/output.ts
diff --git a/packages/subprocess/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
similarity index 100%
rename from packages/subprocess/subprocess-e2b/src/process.ts
rename to packages/e2b/subprocess-e2b/src/process.ts
diff --git a/packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
similarity index 100%
rename from packages/subprocess/subprocess-e2b/tests/subprocess.spec.ts
rename to packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
diff --git a/packages/subprocess/subprocess-e2b/tsconfig.json b/packages/e2b/subprocess-e2b/tsconfig.json
similarity index 84%
rename from packages/subprocess/subprocess-e2b/tsconfig.json
rename to packages/e2b/subprocess-e2b/tsconfig.json
index f3bb8c2a26..fda7cfc667 100644
--- a/packages/subprocess/subprocess-e2b/tsconfig.json
+++ b/packages/e2b/subprocess-e2b/tsconfig.json
@@ -13,10 +13,10 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../e2b/e2b"
+      "path": "../e2b"
     },
     {
-      "path": "../subprocess"
+      "path": "../../subprocess/subprocess"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index eabb6a602e..6b5a5d8b76 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: 8ac8807cc9ca4b5cc31b686cef9796a8e42b7f81
-README.zh.md: 49705790cc0cdf1f7199251e09af0af01f704efb
+README.md: 0b9a244d0c42542909460edf7109dfb9cee34503
+README.zh.md: 77da9b73f866fd88fcb81b28cbb622b0389bf5f0
diff --git a/packages/fs/README.md b/packages/fs/README.md
index 460af7c53b..96bbe6c95b 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -8,7 +8,7 @@ The filesystem stack: a provider seam (execution-world paths, bounded text IO, a
 |---|---|---|
 | `fs/` | Provider seam: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
 | `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
-| `fs-e2b/` | E2B-backed `FileSystem` implementation sharing the remote runtime owned by `ctx.e2b` | (registers `ctx.fs`) |
+| [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | E2B-backed `FileSystem` implementation sharing the remote runtime owned by `ctx.e2b` | (registers `ctx.fs`) |
 | `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
 | `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 5f70e3cb50..7f091b4f09 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -8,7 +8,7 @@
 |---|---|---|
 | `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
 | `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
-| `fs-e2b/` | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
+| [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
 | `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
 | `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index c28c0282c2..be241ada6e 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: 74ed729d97013de3d7f502f728e3abe62348846f
-README.zh.md: 5a08d54ca6c54d8355454fc3021a0da48772000b
+README.md: d8bc6047e7eadeb2993f1114564b41913b2970dc
+README.zh.md: d838af346626bb96299a3b702df0dabb6231c15a
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index 74ed729d97..d8bc6047e7 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -8,9 +8,9 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 |---|---|---|
 | `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
 | [`lsp-local/`](lsp-local/README.md) | Generic multi-server local backend (spawn, JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
-| [`lsp-e2b/`](lsp-e2b/README.md) | Remote E2B backend (remote source reads and servers, byte-framed stdio bridge) | (registers providers on `ctx.lsp`) |
+| [`e2b/lsp-e2b`](../e2b/lsp-e2b/README.md) | Remote E2B backend (remote source reads and servers, byte-framed stdio bridge) | (registers providers on `ctx.lsp`) |
 | `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
 The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
 
-See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the protocol design and the [E2B extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) for the remote process/filesystem boundary.
+See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the protocol design and the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) for the remote process/filesystem boundary.
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index 5a08d54ca6..d838af3466 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -8,9 +8,9 @@
 |---|---|---|
 | `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
 | [`lsp-local/`](lsp-local/README.md) | 通用多服务器本地后端（spawn、JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
-| [`lsp-e2b/`](lsp-e2b/README.md) | 远程 E2B 后端（在远程读取源文件并运行服务器、采用字节分帧的 stdio 桥） | （在 `ctx.lsp` 上注册提供方） |
+| [`e2b/lsp-e2b`](../e2b/lsp-e2b/README.md) | 远程 E2B 后端（在远程读取源文件并运行服务器、采用字节分帧的 stdio 桥） | （在 `ctx.lsp` 上注册提供方） |
 | `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
 接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
-协议设计见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，远程进程／文件系统边界见 [E2B 扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md)。
+协议设计见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，远程进程／文件系统边界见 [共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)。
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index c0fa873642..2dff12e3da 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
-README.md: 239c751f30f8e5c543e6737e65a67f9bb22f79ad
-README.zh.md: edaae7f948d957e2fce2b3f331cc2af61cfabd36
+README.md: a6706ed653bc60909a23b3598c41bb10ef499cbe
+README.zh.md: 01fecf8d57d933168e91331c4d3c3e4666c13cdc
diff --git a/packages/pty/README.md b/packages/pty/README.md
index 239c751f30..a6706ed653 100644
--- a/packages/pty/README.md
+++ b/packages/pty/README.md
@@ -8,7 +8,7 @@ English | [中文](README.zh.md)
 |---|---|---|
 | [`pty`](pty/README.md) (`@deepseek-ai/dsh-pty`) | Backend registry, branded ids, exact-Agent ownership, session operations, and awaited cleanup | `ctx.pty` |
 | [`pty-local`](pty-local/README.md) (`@deepseek-ai/dsh-pty-local`) | Local `node-pty` backend, readiness detection, bounded terminal state, sandboxing, and process-session supervision | registers on `ctx.pty` |
-| [`pty-e2b`](pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | E2B byte-PTY backend, remote foreground signaling, bounded terminal state, and awaited remote cleanup | registers on `ctx.pty` |
+| [`e2b/pty-e2b`](../e2b/pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | E2B byte-PTY backend, remote foreground signaling, bounded terminal state, and awaited remote cleanup | registers on `ctx.pty` |
 | `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
-The core design lives in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md); the remote ownership boundary lives in the [E2B extension note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md).
+The core design lives in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md); the remote ownership boundary lives in the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md).
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index edaae7f948..01fecf8d57 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -8,7 +8,7 @@
 |---|---|---|
 | [`pty`](pty/README.md)（`@deepseek-ai/dsh-pty`） | 后端注册表、品牌化 id、精确的 Agent 所有权、会话操作与等待完成的清理 | `ctx.pty` |
 | [`pty-local`](pty-local/README.md)（`@deepseek-ai/dsh-pty-local`） | 本地 `node-pty` 后端、就绪检测、有界终端状态、沙箱与进程会话监管 | 注册到 `ctx.pty` |
-| [`pty-e2b`](pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | E2B 字节 PTY 后端、远程前台信号传递、有界终端状态与等待完成的远程清理 | 注册到 `ctx.pty` |
+| [`e2b/pty-e2b`](../e2b/pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | E2B 字节 PTY 后端、远程前台信号传递、有界终端状态与等待完成的远程清理 | 注册到 `ctx.pty` |
 | `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
-核心设计记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中；远程所有权边界记录在 [E2B 扩展 Agent Note](../../.agents/notes/implemented/feature/2026-07-28-e2b-interactive-semantic-code-runtime-poc.md) 中。
+核心设计记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中；远程所有权边界记录在 [共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) 中。
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 0efaf7838e..4097420382 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: ae18c55205edd6085a0ed8de1bb7f875c411c79f
-README.zh.md: e27fd240e4c1e96d8b859b326574e441241e8508
+README.md: cdea3803e903b31e895658745bc6dbf5a3c04c71
+README.zh.md: 95b02b6491077750f23ff12ffd14c1aa174609be
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index ae18c55205..cdea3803e9 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -8,6 +8,6 @@ The shared home for spawning managed child-process trees: fully-specified spawn
 |---|---|---|
 | [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: abstract `SubprocessService.spawn(spec)`, the fully-explicit `SubprocessSpawnSpec` with per-stream stdio dispositions, `SubprocessHandle` (streams, offset-based readers, terminate/waitForExit/dispose), and the shared scrub + `DSH_*`/`CollectedOutput` vocabulary |
 | [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, per-disposition stream wiring, tail-keep truncation with bounded private spill files, the `DSH_*` merge order, tree signalling with escalation, the dispose ladder, and terminate-and-join disposal |
-| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | — | Experimental E2B implementation: remote Linux process groups and spill state in the shared `ctx.e2b` sandbox, with asynchronous PID acquisition and SDK buffering limitations |
+| [`e2b/subprocess-e2b`](../e2b/subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | — | Experimental E2B implementation: remote Linux process groups and spill state in the shared `ctx.e2b` sandbox, with asynchronous PID acquisition and SDK buffering limitations |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index e27fd240e4..95b02b6491 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -8,6 +8,6 @@ spawn 受管子进程树的共用归属位置：完全显式的 spawn spec，其
 |---|---|---|
 | [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：抽象的 `SubprocessService.spawn(spec)`、完全显式且带按流划分 stdio 处置方式的 `SubprocessSpawnSpec`、`SubprocessHandle`（流、基于偏移量的读取器、terminate/waitForExit/dispose），以及共享的凭据清除 + `DSH_*`/`CollectedOutput` 词汇 |
 | [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、按处置方式接线的流、附带有界私有 spill 文件的尾部保留截断、`DSH_*` 合并次序、带升级的进程树信号发送、dispose 阶梯，以及先终止再等待退出的 dispose |
-| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | 无 | 实验性 E2B 实现：远程 Linux 进程组和共享 `ctx.e2b` 沙箱中的 spill 状态，但 PID 异步获取，且受 SDK 缓冲限制 |
+| [`e2b/subprocess-e2b`](../e2b/subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | 无 | 实验性 E2B 实现：远程 Linux 进程组和共享 `ctx.e2b` 沙箱中的 spill 状态，但 PID 异步获取，且受 SDK 缓冲限制 |
 
 服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 5ab5dc2e4e..5ad70c0e68 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -47,7 +47,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
-  'packages/code-runtime/code-runtime-e2b': { kind: 'indirect', reason: 'The E2B backend delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/e2b/code-runtime-e2b': { kind: 'indirect', reason: 'The E2B backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
@@ -84,7 +84,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/web': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/examples/agent-spine-demo': { kind: 'indirect', reason: 'The bundle only mounts model-facing child plugins.' },
   'packages/fs/fs': { kind: 'indirect', reason: 'The service interface delegates model rendering to dsh-tool-fs.' },
-  'packages/fs/fs-e2b': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
+  'packages/e2b/fs-e2b': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/fs/fs-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
   'packages/host/apiproxy': { kind: 'none', reason: 'The wire contract and fetch carriers move already-composed messages and register no model surface.' },
@@ -99,10 +99,10 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
-  'packages/lsp/lsp-e2b': { kind: 'indirect', reason: 'The E2B provider backend delegates model rendering to dsh-tool-lsp.' },
+  'packages/e2b/lsp-e2b': { kind: 'indirect', reason: 'The E2B provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/lsp/lsp-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/subprocess/subprocess': { kind: 'indirect', reason: 'The seam delegates all model rendering to consumer seams such as the bash executor family.' },
-  'packages/subprocess/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
+  'packages/e2b/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/subprocess/subprocess-local': { kind: 'indirect', reason: 'The spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
   'packages/sdk/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 8380182e83..0673c35b90 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -85,6 +85,7 @@
         "./packages/llm/*/src/invariant.ts",
         "./packages/bash/*/src/invariant.ts",
         "./packages/subprocess/*/src/invariant.ts",
+        "./packages/e2b/*/src/invariant.ts",
         "./packages/code-runtime/*/src/invariant.ts",
         "./packages/fs/*/src/invariant.ts",
         "./packages/skill/*/src/invariant.ts",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 1f70e79a4f..526d4ef4b8 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -163,15 +163,15 @@
     { "path": "./packages/subprocess/subprocess" },
     { "path": "./packages/subprocess/subprocess-local" },
     { "path": "./packages/e2b/e2b" },
-    { "path": "./packages/subprocess/subprocess-e2b" },
+    { "path": "./packages/e2b/subprocess-e2b" },
     { "path": "./packages/bash/bash" },
     { "path": "./packages/pty/pty" },
-    { "path": "./packages/pty/pty-e2b" },
+    { "path": "./packages/e2b/pty-e2b" },
     { "path": "./packages/pty/pty-local" },
     { "path": "./packages/pty/tool-bash-persistent" },
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
-    { "path": "./packages/code-runtime/code-runtime-e2b" },
+    { "path": "./packages/e2b/code-runtime-e2b" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
@@ -187,7 +187,7 @@
     { "path": "./packages/bash/tool-bash" },
     { "path": "./packages/fs/fs" },
     { "path": "./packages/fs/fs-local" },
-    { "path": "./packages/fs/fs-e2b" },
+    { "path": "./packages/e2b/fs-e2b" },
     { "path": "./packages/fs/fs-policy" },
     { "path": "./packages/fs/fs-sandbox" },
     { "path": "./packages/fs/tool-fs" },
@@ -268,7 +268,7 @@
     { "path": "./packages/sdk/create-sdk" },
     { "path": "./packages/sdk/telemetry" },
     { "path": "./packages/lsp/lsp" },
-    { "path": "./packages/lsp/lsp-e2b" },
+    { "path": "./packages/e2b/lsp-e2b" },
     { "path": "./packages/lsp/lsp-local" },
     { "path": "./packages/lsp/tool-lsp" },
     { "path": "./apps/cli" }

From 3dea36f1ce43d72413fb2b6e8fc3144b7e358d86 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 16:26:20 +0800
Subject: [PATCH 355/516] fix(e2b): close remote lifecycle gaps

---
 .../tests/fixtures/e2b/e2b/bin.ts             |  71 ++++++-
 .../tests/fixtures/e2b/e2b/cordis.yml         |   4 +-
 packages/e2b/code-runtime-e2b/src/index.ts    |  91 ++++++--
 .../code-runtime-e2b/tests/runtime.spec.ts    | 142 ++++++++++++-
 packages/e2b/e2b/src/frame.ts                 |  23 +-
 packages/e2b/e2b/src/index.ts                 |   8 +-
 packages/e2b/e2b/tests/composition.e2e.ts     |  10 +-
 packages/e2b/e2b/tests/e2b.spec.ts            |  25 +++
 packages/e2b/fs-e2b/src/index.ts              |   9 +
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |  25 ++-
 packages/e2b/lsp-e2b/src/index.ts             |  11 +
 packages/e2b/lsp-e2b/tests/provider.spec.ts   |   5 +
 packages/e2b/pty-e2b/src/index.ts             |   5 +-
 packages/e2b/pty-e2b/tests/index.spec.ts      |   4 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   2 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   2 +-
 packages/e2b/subprocess-e2b/src/process.ts    |  47 +++--
 .../subprocess-e2b/tests/subprocess.spec.ts   |  47 ++++-
 packages/lsp/lsp-local/src/index.ts           | 199 ++++++++----------
 packages/lsp/lsp-local/src/instance.ts        |  13 +-
 packages/lsp/lsp-local/tests/instance.spec.ts |   2 +
 22 files changed, 568 insertions(+), 181 deletions(-)

diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 33e9530708..89b09a6818 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { posix, resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
 import { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -48,20 +48,68 @@ try {
   const fromBash = await ctx.fs.resolve('from-bash.txt')
   const fsRead = await ctx.fs.readText(fromBash)
 
+  const environmentHandle = ctx.subprocess.spawn({
+    argv: ['env'],
+    cwd: process.cwd(),
+    stdio: { stdin: 'ignore', stdout: { maxBytes: 65_536 }, stderr: { maxBytes: 4_096 } },
+    graceMs: 500,
+    env: {
+      'FOO-BAR': 'hyphen-value',
+      DSH_EXPLICIT: 'managed-value',
+      TOKEN_EXPLICIT: 'credential-value',
+    },
+  })
+  const environmentOutcome = await environmentHandle.done
+  const environmentText = environmentHandle.collected.stdout?.readFrom(0).text
+  if (environmentOutcome.exitCode !== 0 || environmentText === undefined) {
+    throw new Error(`E2B subprocess environment probe failed: ${JSON.stringify(environmentOutcome)}`)
+  }
+  const environmentLines = new Set(environmentText.trimEnd().split('\n'))
+  const explicitEnvironment = [
+    'FOO-BAR=hyphen-value',
+    'DSH_EXPLICIT=managed-value',
+    'TOKEN_EXPLICIT=credential-value',
+  ].every(entry => environmentLines.has(entry))
+  if (!explicitEnvironment) throw new Error(`E2B subprocess dropped an explicit environment entry: ${environmentText}`)
+
+  const spillHandle = ctx.subprocess.spawn({
+    argv: ['bash', '-c', "printf '0123456789'; sleep 30"],
+    cwd: process.cwd(),
+    stdio: { stdin: 'ignore', stdout: { maxBytes: 4, spill: { maxBytes: 6 } }, stderr: { maxBytes: 4_096 } },
+    graceMs: 500,
+    env: {},
+  })
+  const spillReader = spillHandle.collected.stdout
+  if (spillReader === undefined) throw new Error('E2B subprocess omitted its configured stdout collector')
+  const spillDeadline = Date.now() + 5_000
+  while (spillReader.readFrom(0).nextOffset < 10) {
+    if (Date.now() >= spillDeadline) throw new Error('E2B subprocess did not stream the spill probe output')
+    await new Promise(resolveDelay => setTimeout(resolveDelay, 20))
+  }
+  const spillPath = posix.join((spillHandle as unknown as { stateDir: string }).stateDir, 'stdout.log')
+  const liveSpillBytes = (await (await ctx.e2b.getSandbox()).files.getInfo(spillPath)).size
+  spillHandle.terminate()
+  const spillOutcome = await spillHandle.done
+  const spillExited = await spillHandle.waitForExit(AbortSignal.timeout(5_000))
+  const spillRead = spillReader.readFrom(0)
+  if (liveSpillBytes !== 6 || !spillExited || spillRead.spillPath !== undefined) {
+    throw new Error(`E2B subprocess spill bound failed: ${JSON.stringify({ liveSpillBytes, spillExited, spillRead })}`)
+  }
+
   const lspFixture = await readFile(new URL('./fixture-lsp.mjs', import.meta.url), 'utf8')
   const remoteLspFixture = await ctx.fs.resolve('fixture-lsp.mjs')
   await ctx.fs.writeText(remoteLspFixture, lspFixture, { kind: 'createIfAbsent' })
-  const remoteSource = await ctx.fs.resolve('multibyte.ts')
+  const remoteSource = await ctx.fs.resolve('multibyte # file.ts')
   await ctx.fs.writeText(remoteSource, 'const café = "你好"\nconsole.log(café)\n', { kind: 'createIfAbsent' })
   const hover = await ctx.lsp.query({
     operation: 'hover',
-    filePath: 'multibyte.ts',
+    filePath: 'multibyte # file.ts',
     position: { line: 0, character: 7 },
     workspaceRoot: process.cwd(),
   })
   const definition = await ctx.lsp.query({
     operation: 'goToDefinition',
-    filePath: 'multibyte.ts',
+    filePath: 'multibyte # file.ts',
     position: { line: 0, character: 7 },
     workspaceRoot: process.cwd(),
   })
@@ -143,6 +191,17 @@ try {
   })
   setTimeout(() => { abortController.abort('live abort') }, 50)
   const aborted = await aborting
+  const oversizedBoot = await ctx.codeRuntime.run({
+    program: `return ${JSON.stringify('x'.repeat(40_000))}`,
+    bindings: [],
+  })
+  const oversizedReply = await ctx.codeRuntime.run({
+    program: 'return await bridge.large(null)',
+    bindings: [{
+      global: 'bridge',
+      functions: { large: async () => 'x'.repeat(40_000) },
+    }],
+  })
   const remoteProcesses = await (await ctx.e2b.getSandbox()).commands.list()
   const lingeringCodeRunners = remoteProcesses.filter(processInfo =>
     JSON.stringify([processInfo.cmd, processInfo.args]).includes('code-runtime-runner.mjs'),
@@ -152,6 +211,8 @@ try {
     sandboxId: await ctx.e2b.sandboxId,
     bashRead: bashRead.stdout.text,
     fsRead,
+    explicitEnvironment,
+    spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
     definition,
     terminal: {
@@ -165,6 +226,8 @@ try {
     hostileOutput,
     timedOut,
     aborted,
+    oversizedBoot,
+    oversizedReply,
     lingeringCodeRunners: lingeringCodeRunners.length,
   })}\n`)
 } finally {
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index f5cf403c4b..6b3350e49c 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -2,7 +2,7 @@
   name: '@deepseek-ai/dsh-e2b'
   config:
     cwd: !!js process.cwd()
-    timeoutMs: 60000
+    timeoutMs: 120000
     onTimeout: kill
     onDispose: kill
 
@@ -55,5 +55,5 @@
     maxWallMs: 5000
     maxOutputBytes: 4096
     maxOldGenerationSizeMb: 128
-    maxFrameBytes: 4194304
+    maxFrameBytes: 32768
     killGraceMs: 500
diff --git a/packages/e2b/code-runtime-e2b/src/index.ts b/packages/e2b/code-runtime-e2b/src/index.ts
index fbfbdea91f..a567a2bb6d 100644
--- a/packages/e2b/code-runtime-e2b/src/index.ts
+++ b/packages/e2b/code-runtime-e2b/src/index.ts
@@ -14,7 +14,7 @@ import type {
 } from '@deepseek-ai/dsh-code-runtime'
 import {
   E2BFrameDecoder,
-  encodeE2BFrame,
+  encodeBoundedE2BFrame,
   quoteE2BShellArg,
   resolveE2BExecutable,
 } from '@deepseek-ai/dsh-e2b'
@@ -25,6 +25,7 @@ import {
 } from '@deepseek-ai/dsh-code-runtime-worker'
 import type { WorkerJsonWire } from '@deepseek-ai/dsh-code-runtime-worker'
 import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
+import type { SubprocessHandle } from '@deepseek-ai/dsh-subprocess'
 import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { CODE_RUNNER_SOURCE } from './runner-source.ts'
@@ -46,6 +47,7 @@ export interface Config {
 }
 
 type ResolvedConfig = Required<Config>
+type PreparedRuntime = { node: string; runner: string }
 
 interface LiveRun {
   settle(failure: CodeRunFailure): void
@@ -130,7 +132,7 @@ export class E2BCodeRuntime extends CodeRuntime {
   readonly isolation = 'container'
 
   private readonly config: ResolvedConfig
-  private readonly ready: Promise<{ node: string; runner: string }>
+  private readonly ready: Promise<PreparedRuntime>
   private readonly live = new Set<LiveRun>()
   private readonly subprocess: E2BSubprocessService
   private disposed = false
@@ -176,25 +178,61 @@ export class E2BCodeRuntime extends CodeRuntime {
     } catch (error: unknown) {
       return this.failure({ kind: 'exception', message: messageOf(error) })
     }
-    let runtime: Awaited<typeof this.ready>
+    let runtime: PreparedRuntime | undefined
     try {
-      runtime = await this.ready
+      runtime = await this.awaitPreparation(request.signal)
     } catch (error: unknown) {
+      // Disposal can race the awaited setup despite the synchronous precheck.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
       return this.failure({ kind: 'worker-exit', message: `E2B runtime setup failed: ${messageOf(error)}` })
     }
+    if (runtime === undefined) {
+      return this.failure({ kind: 'abort', message: String(request.signal?.reason) })
+    }
     // Disposal can race the awaited remote setup after the pre-await check.
+    /* v8 ignore start -- requires disposal between promise resolution and its awaiting continuation. */
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
+    /* v8 ignore stop */
     return await this.execute(request, code, bindings, runtime)
   }
   /* jscpd:ignore-end */
 
-  private async prepare(): Promise<{ node: string; runner: string }> {
+  private awaitPreparation(signal: AbortSignal | undefined): Promise<PreparedRuntime | undefined> {
+    if (signal === undefined) return this.ready
+    return new Promise<PreparedRuntime | undefined>((resolve, reject) => {
+      const onAbort = (): void => { cleanup(); resolve(undefined) }
+      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      if (signal.aborted) {
+        onAbort()
+        return
+      }
+      void this.ready.then(
+        (runtime) => { cleanup(); resolve(runtime) },
+        (error: unknown) => {
+          cleanup()
+          reject(error instanceof Error ? error : new Error(String(error)))
+        },
+      )
+    })
+  }
+
+  private assertPreparationActive(): void {
+    if (this.disposed) throw new Error('code-runtime-e2b: runtime disposed during setup')
+  }
+
+  private async prepare(): Promise<PreparedRuntime> {
     const sandbox = await this.ctx.e2b.getSandbox()
+    this.assertPreparationActive()
     const runner = posix.join(this.ctx.e2b.runtimeRoot, 'code-runtime-runner.mjs')
     await sandbox.files.write([{ path: runner, data: CODE_RUNNER_SOURCE }])
+    this.assertPreparationActive()
     await sandbox.commands.run(`chmod 600 -- ${quoteE2BShellArg(runner)}`)
+    this.assertPreparationActive()
     const node = await resolveE2BExecutable(sandbox, 'node')
+    this.assertPreparationActive()
     return { node, runner }
   }
 
@@ -237,16 +275,25 @@ export class E2BCodeRuntime extends CodeRuntime {
     request: CodeRunRequest,
     code: string,
     bindings: Map<string, CodeBindingNamespace>,
-    runtime: { node: string; runner: string },
+    runtime: PreparedRuntime,
   ): Promise<CodeRunResult> {
-    const handle = this.subprocess.spawn({
-      argv: [runtime.node, runtime.runner],
-      cwd: this.ctx.e2b.cwd,
-      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: this.config.maxOutputBytes } },
-      graceMs: this.config.killGraceMs,
-      ...request.signal === undefined ? {} : { signal: request.signal },
-      env: {},
-    })
+    let handle: SubprocessHandle
+    try {
+      handle = this.subprocess.spawn({
+        argv: [runtime.node, runtime.runner],
+        cwd: this.ctx.e2b.cwd,
+        stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: this.config.maxOutputBytes } },
+        graceMs: this.config.killGraceMs,
+        ...request.signal === undefined ? {} : { signal: request.signal },
+        env: {},
+      })
+    } catch (error: unknown) {
+      if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
+      if (request.signal?.aborted === true) {
+        return this.failure({ kind: 'abort', message: String(request.signal.reason) })
+      }
+      return this.failure({ kind: 'worker-exit', message: `E2B runtime spawn failed: ${messageOf(error)}` })
+    }
     if (handle.stdin === undefined || handle.stdout === undefined) {
       handle.terminate()
       await Promise.allSettled([handle.done])
@@ -279,7 +326,6 @@ export class E2BCodeRuntime extends CodeRuntime {
         settled = true
         clearTimeout(wallTimer.current)
         request.signal?.removeEventListener('abort', onAbort)
-        this.live.delete(live)
         void new Promise<void>((resume) => { setImmediate(resume) }).then(async () => {
           handle.terminate()
           await handle.done.catch(() => {})
@@ -298,6 +344,7 @@ export class E2BCodeRuntime extends CodeRuntime {
             result = output.failure(logs, { kind: 'worker-exit', message: `E2B runtime cleanup failed: ${messageOf(cleanupError)}` })
           }
           const final = typeof result === 'function' ? result() : result
+          this.live.delete(live)
           finishResolve()
           resolve(final)
         })
@@ -305,7 +352,14 @@ export class E2BCodeRuntime extends CodeRuntime {
 
       const sendReply = (message: unknown): void => {
         if (settled) return
-        stdin.write(encodeE2BFrame(message), (error?: Error | null) => {
+        let frame: string
+        try {
+          frame = encodeBoundedE2BFrame(message, this.config.maxFrameBytes)
+        } catch (error: unknown) {
+          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge failed: ${messageOf(error)}` }))
+          return
+        }
+        stdin.write(frame, (error?: Error | null) => {
           if (error !== undefined && error !== null) {
             finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge write failed: ${error.message}` }))
           }
@@ -433,7 +487,10 @@ export class E2BCodeRuntime extends CodeRuntime {
     this.disposed = true
     const runs = [...this.live]
     for (const run of runs) run.settle({ kind: 'abort', message: 'runtime disposed' })
-    await Promise.all(runs.map(run => run.finished))
+    await Promise.all([
+      this.ready.then(() => {}, () => {}),
+      ...runs.map(run => run.finished),
+    ])
   }
   /* jscpd:ignore-end */
 }
diff --git a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
index ff1c5dd84a..9824fb2cf0 100644
--- a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
+++ b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
@@ -34,13 +34,22 @@ class FakeHandle implements SubprocessHandle {
   waitCalls = 0
   private readonly decoder = new E2BFrameDecoder(10_000_000)
   private readonly waitError: Error | undefined
+  private readonly waitResult: Promise<boolean> | undefined
   private settled = false
 
   constructor(
     private readonly onMessage: (message: unknown, handle: FakeHandle) => void = () => {},
-    options: { stdin?: boolean; stdout?: boolean; stderr?: string; writeError?: Error; waitError?: Error } = {},
+    options: {
+      stdin?: boolean
+      stdout?: boolean
+      stderr?: string
+      writeError?: Error
+      waitError?: Error
+      waitResult?: Promise<boolean>
+    } = {},
   ) {
     this.waitError = options.waitError
+    this.waitResult = options.waitResult
     this.stdin = options.stdin === false
       ? undefined
       : options.writeError === undefined
@@ -89,6 +98,7 @@ class FakeHandle implements SubprocessHandle {
   async waitForExit(): Promise<boolean> {
     this.waitCalls += 1
     if (this.waitError !== undefined) throw this.waitError
+    if (this.waitResult !== undefined) return await this.waitResult
     return true
   }
 }
@@ -286,6 +296,30 @@ describe('E2BCodeRuntime', () => {
     await fixture.fiber.dispose()
   })
 
+  it('enforces the outbound frame bound on boot and binding replies', async () => {
+    const oversizedBoot = new FakeHandle()
+    const oversizedReply = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') {
+        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'large', args: encodeWorkerJson(null) })
+      }
+    })
+    const fixture = await setup([oversizedBoot, oversizedReply], { maxOutputBytes: 128, maxFrameBytes: 512 })
+
+    const bootResult = await fixture.runtime.run(request(`return ${JSON.stringify('x'.repeat(1_000))}`))
+    expect(bootResult.error).toMatchObject({ kind: 'worker-exit' })
+    expect(bootResult.error?.message).toContain('frame exceeded its byte limit')
+    expect(oversizedBoot.writes).toHaveLength(0)
+
+    const replyResult = await fixture.runtime.run({
+      program: 'return await bridge.large(null)',
+      bindings: [{ global: 'bridge', functions: { large: async () => 'x'.repeat(1_000) } }],
+    })
+    expect(replyResult.error).toMatchObject({ kind: 'worker-exit' })
+    expect(replyResult.error?.message).toContain('frame exceeded its byte limit')
+    expect(oversizedReply.writes).toHaveLength(1)
+    await fixture.fiber.dispose()
+  })
+
   it('contains stdin errors, process exits, spawn failures, and missing pipes', async () => {
     const writeError = new FakeHandle(() => {}, { writeError: new Error('write callback broke') })
     const stdinError = new FakeHandle((message, current) => {
@@ -445,12 +479,116 @@ describe('E2BCodeRuntime', () => {
     const gate = Promise.withResolvers<Sandbox>()
     const fixture = await setup([], {}, {}, () => gate.promise)
     const running = fixture.runtime.run(request())
-    await (fixture.runtime as unknown as { teardown(): Promise<void> }).teardown()
+    const disposing = fixture.fiber.dispose()
+    let disposed = false
+    void disposing.then(() => { disposed = true })
+    await new Promise(resolve => setImmediate(resolve))
+    const disposedBeforeSetup = disposed
     gate.resolve(fixture.sandbox)
+    await disposing
+    expect(disposedBeforeSetup).toBe(false)
     expect((await running).error).toEqual({ kind: 'abort', message: 'runtime disposed' })
+    expect(fixture.write).not.toHaveBeenCalled()
+  })
+
+  it('observes abort while runtime preparation is pending', async () => {
+    const gate = Promise.withResolvers<Sandbox>()
+    const fixture = await setup([], {}, {}, () => gate.promise)
+    const controller = new AbortController()
+    const running = fixture.runtime.run({ ...request(), signal: controller.signal })
+
+    controller.abort('stop during setup')
+    const early = await Promise.race([
+      running.then(result => ({ kind: 'result' as const, result })),
+      new Promise<{ kind: 'pending' }>((resolve) => { setImmediate(() => { resolve({ kind: 'pending' }) }) }),
+    ])
+    expect(fixture.spawn).not.toHaveBeenCalled()
+
+    gate.resolve(fixture.sandbox)
+    expect(early).toMatchObject({ kind: 'result', result: { error: { kind: 'abort', message: 'stop during setup' } } })
+    await running
     await fixture.fiber.dispose()
   })
 
+  it('classifies an abort that races synchronous subprocess spawn', async () => {
+    const fixture = await setup()
+    const controller = new AbortController()
+    fixture.spawn.mockImplementationOnce(() => {
+      controller.abort('stop at spawn')
+      throw new Error('aborted before spawn')
+    })
+
+    expect((await fixture.runtime.run({ ...request(), signal: controller.signal })).error)
+      .toEqual({ kind: 'abort', message: 'stop at spawn' })
+
+    fixture.spawn.mockImplementationOnce(() => { throw new Error('synchronous spawn failure') })
+    expect((await fixture.runtime.run(request())).error).toEqual({
+      kind: 'worker-exit',
+      message: 'E2B runtime spawn failed: synchronous spawn failure',
+    })
+    await fixture.fiber.dispose()
+
+    const disposingFixture = await setup()
+    disposingFixture.spawn.mockImplementationOnce(() => {
+      void (disposingFixture.runtime as unknown as { teardown(): Promise<void> }).teardown()
+      throw new Error('spawn raced disposal')
+    })
+    expect((await disposingFixture.runtime.run(request())).error)
+      .toEqual({ kind: 'abort', message: 'runtime disposed' })
+    await disposingFixture.fiber.dispose()
+  })
+
+  it('closes both abort races around runtime readiness and live-run publication', async () => {
+    let preparationAborted = false
+    const preparationSignal = {
+      get aborted() { return preparationAborted },
+      reason: 'preparation race',
+      addEventListener() { preparationAborted = true },
+      removeEventListener() {},
+    } as unknown as AbortSignal
+    const liveHandle = new FakeHandle()
+    const fixture = await setup([liveHandle])
+    expect((await fixture.runtime.run({ ...request(), signal: preparationSignal })).error)
+      .toEqual({ kind: 'abort', message: 'preparation race' })
+    expect(fixture.spawn).not.toHaveBeenCalled()
+
+    let liveAborted = false
+    let registrations = 0
+    const liveSignal = {
+      get aborted() { return liveAborted },
+      reason: 'live publication race',
+      addEventListener() {
+        registrations += 1
+        if (registrations === 2) liveAborted = true
+      },
+      removeEventListener() {},
+    } as unknown as AbortSignal
+    expect((await fixture.runtime.run({ ...request(), signal: liveSignal })).error)
+      .toEqual({ kind: 'abort', message: 'live publication race' })
+    await fixture.fiber.dispose()
+  })
+
+  it('retains a live run until remote cleanup reaches quiescence', async () => {
+    const cleanup = Promise.withResolvers<boolean>()
+    const handle = new FakeHandle((message, current) => {
+      if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done' })
+    }, { waitResult: cleanup.promise })
+    const fixture = await setup([handle])
+    const running = fixture.runtime.run(request())
+    await vi.waitFor(() => { expect(handle.waitCalls).toBe(1) })
+
+    const disposing = fixture.fiber.dispose()
+    let disposed = false
+    void disposing.then(() => { disposed = true })
+    await new Promise(resolve => setImmediate(resolve))
+    const disposedBeforeCleanup = disposed
+
+    cleanup.resolve(true)
+    await expect(running).resolves.toEqual({ logs: [] })
+    await expect(disposing).resolves.toBeUndefined()
+    expect(disposedBeforeCleanup).toBe(false)
+  })
+
   it('registers the package-owned invariant companion', async () => {
     const ctx = new Context()
     await ctx.plugin(InvariantService, { enabled: true })
diff --git a/packages/e2b/e2b/src/frame.ts b/packages/e2b/e2b/src/frame.ts
index 39800b4428..5b6fe536c0 100644
--- a/packages/e2b/e2b/src/frame.ts
+++ b/packages/e2b/e2b/src/frame.ts
@@ -10,9 +10,30 @@ const BASE64_LINE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3
  * @returns Base64-encoded UTF-8 JSON followed by one newline.
  */
 export function encodeE2BFrame(value: unknown): string {
+  return encodeFrame(value)
+}
+
+/**
+ * Encode one JSON-compatible value while enforcing the decoded frame bound.
+ * @param value - Value accepted by `JSON.stringify`.
+ * @param maxFrameBytes - Maximum UTF-8 JSON bytes in the encoded frame.
+ * @returns Base64-encoded UTF-8 JSON followed by one newline.
+ */
+export function encodeBoundedE2BFrame(value: unknown, maxFrameBytes: number): string {
+  if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
+    throw new Error('E2B frame maxFrameBytes must be a positive safe integer')
+  }
+  return encodeFrame(value, maxFrameBytes)
+}
+
+function encodeFrame(value: unknown, maxFrameBytes?: number): string {
   const json: unknown = JSON.stringify(value)
   if (typeof json !== 'string') throw new Error('E2B frame value is not JSON-serializable')
-  return `${Buffer.from(json).toString('base64')}\n`
+  const bytes = Buffer.from(json)
+  if (maxFrameBytes !== undefined && bytes.length > maxFrameBytes) {
+    throw new Error('E2B frame exceeded its byte limit')
+  }
+  return `${bytes.toString('base64')}\n`
 }
 
 /** Incremental decoder for newline-delimited base64 JSON frames. */
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 4c4597f6ef..11625b3b21 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -10,7 +10,7 @@ import z from 'schemastery'
 import { Sandbox } from 'e2b'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
-export { E2BFrameDecoder, encodeE2BFrame } from './frame.ts'
+export { E2BFrameDecoder, encodeBoundedE2BFrame, encodeE2BFrame } from './frame.ts'
 
 export {
   CommandExitError,
@@ -202,7 +202,11 @@ export class E2BSandboxService extends Service {
    */
   async getSandbox(): Promise<Sandbox> {
     if (this.disposed) throw new Error('E2B sandbox service is disposing')
-    return await this.ready
+    const sandbox = await this.ready
+    // Disposal can race the awaited sandbox readiness despite the synchronous precheck.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (this.disposed) throw new Error('E2B sandbox service is disposing')
+    return sandbox
   }
 
   private validate(): void {
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index d056d4b851..5c9bd56fc9 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -24,7 +24,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       },
       processTimeoutMs: 120_000,
       inspect: async (cwd) => {
-        for (const name of ['from-fs.txt', 'from-bash.txt', 'multibyte.ts', 'fixture-lsp.mjs']) {
+        for (const name of ['from-fs.txt', 'from-bash.txt', 'multibyte # file.ts', 'fixture-lsp.mjs']) {
           await expect(access(join(cwd, name))).rejects.toMatchObject({ code: 'ENOENT' })
         }
       },
@@ -35,6 +35,12 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     expect(output).toMatchObject({
       bashRead: 'written-by-fs\n',
       fsRead: 'written-by-bash\n',
+      explicitEnvironment: true,
+      spill: {
+        liveBytes: 6,
+        outcome: { exitCode: null, signal: 'SIGTERM' },
+        read: { text: '6789', nextOffset: 10, lossy: true },
+      },
       hover: {
         kind: 'hover',
         hover: { contents: '**remote hover** 你好 café' },
@@ -51,6 +57,8 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       hostileOutput: { error: { kind: 'output-limit' } },
       timedOut: { error: { kind: 'timeout' } },
       aborted: { error: { kind: 'abort', message: 'live abort' } },
+      oversizedBoot: { error: { kind: 'worker-exit' } },
+      oversizedReply: { error: { kind: 'worker-exit' } },
       lingeringCodeRunners: 0,
     })
     expect((output.terminal as { motd: string }).motd.length).toBeGreaterThan(0)
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index 541e69df9c..58d2ffbd7a 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -4,6 +4,7 @@ import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
   E2BFrameDecoder,
   E2BSandboxId,
+  encodeBoundedE2BFrame,
   encodeE2BFrame,
   quoteE2BShellArg,
   resolveE2BExecutable,
@@ -91,6 +92,22 @@ describe('E2BSandboxService', () => {
     await expect(service.getSandbox()).rejects.toThrow(/disposing/)
   })
 
+  it('rejects handle acquisition when disposal starts during setup', async () => {
+    const fixture = fakeSandbox()
+    const opening = Promise.withResolvers<SandboxType>()
+    sdk.create.mockReturnValue(opening.promise)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    const acquisition = ctx.e2b.getSandbox()
+    const disposing = fiber.dispose()
+    opening.resolve(fixture.sandbox)
+
+    await expect(acquisition).rejects.toThrow(/disposing/)
+    await expect(disposing).resolves.toBeUndefined()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+  })
+
   it('creates from a template, honors timeout and pause policies, and reads the key from the environment', async () => {
     vi.stubEnv('E2B_API_KEY', 'environment-key')
     const fixture = fakeSandbox('template-sandbox')
@@ -240,6 +257,14 @@ describe('E2B helpers and invariant companion', () => {
     expect(() => encodeE2BFrame(undefined)).toThrow('not JSON-serializable')
   })
 
+  it('bounds outbound frames by decoded UTF-8 bytes', () => {
+    const exact = encodeBoundedE2BFrame({ text: '你' }, 14)
+    expect(new E2BFrameDecoder(14).push(exact)).toEqual([{ text: '你' }])
+    expect(() => encodeBoundedE2BFrame({ text: '你' }, 13)).toThrow('byte limit')
+    expect(() => encodeBoundedE2BFrame(null, 0)).toThrow('positive safe integer')
+    expect(() => encodeBoundedE2BFrame(null, 1.5)).toThrow('positive safe integer')
+  })
+
   it('rejects malformed, oversized, and truncated frame streams', () => {
     expect(() => new E2BFrameDecoder(0)).toThrow('positive safe integer')
     expect(() => new E2BFrameDecoder(1.5)).toThrow('positive safe integer')
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 020b0f4857..4f733f1fba 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -199,6 +199,7 @@ export class E2BFileSystem extends FileSystem {
         const reader = stream.getReader()
         const decoder = new TextDecoder('utf-8', { fatal: true })
         let sampledBytes = 0
+        let completed = false
         try {
           while (true) {
             assertNotAborted(signal, 'read')
@@ -222,9 +223,17 @@ export class E2BFileSystem extends FileSystem {
           } catch (error: unknown) {
             throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
           }
+          completed = true
         } catch (error: unknown) {
           throw mapError(error, 'read', displayPath, signal)
         } finally {
+          if (!completed) {
+            try {
+              await reader.cancel()
+            } catch (_streamCancellationFailure) {
+              // The primary read outcome owns the result; cancellation is best-effort after early stop.
+            }
+          }
           reader.releaseLock()
         }
       },
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index b8eb5447d6..177bb9e59c 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -12,7 +12,7 @@ import { FsVersion } from '@deepseek-ai/dsh-fs'
 import E2BFileSystem from '@deepseek-ai/dsh-fs-e2b'
 import * as E2BFsInvariant from '../src/invariant.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 
 interface RemoteNode {
   type: FileType
@@ -38,6 +38,8 @@ class FakeRemote {
   readonly removals: string[] = []
   readonly commands: string[] = []
   streamChunks: Uint8Array[] | undefined
+  streamKeepOpen = false
+  readonly streamCancel = vi.fn()
   nextCommandError: unknown
   nextInfoError: unknown
   nextListError: unknown
@@ -148,10 +150,11 @@ class FakeRemote {
         if (options.format === 'bytes') return data.slice()
         const chunks = this.streamChunks ?? [data.slice()]
         return new ReadableStream<Uint8Array>({
-          start(controller) {
+          start: (controller) => {
             for (const chunk of chunks) controller.enqueue(chunk)
-            controller.close()
+            if (!this.streamKeepOpen) controller.close()
           },
+          cancel: () => { this.streamCancel() },
         })
       },
       list: async (path: string, options?: { depth?: number; signal?: AbortSignal }): Promise<EntryInfo[]> => {
@@ -303,6 +306,22 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     expect(initiallyBuffered).toBe('€')
   })
 
+  it('cancels a remote stream when its consumer stops early', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/text.txt', 'ab')
+    remote.streamChunks = [bytes('a'), bytes('b')]
+    remote.streamKeepOpen = true
+    const { fs } = await setup(remote)
+    const stream = await fs.streamText(await fs.resolve('text.txt'))
+
+    for await (const chunk of stream) {
+      expect(chunk).toBe('a')
+      break
+    }
+
+    expect(remote.streamCancel).toHaveBeenCalledOnce()
+  })
+
   it('matches local binary sampling while edits still reject any NUL byte', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/late-nul.txt', `${'a'.repeat(8192)}\0tail`)
diff --git a/packages/e2b/lsp-e2b/src/index.ts b/packages/e2b/lsp-e2b/src/index.ts
index eb9596db5f..b378ebfc9a 100644
--- a/packages/e2b/lsp-e2b/src/index.ts
+++ b/packages/e2b/lsp-e2b/src/index.ts
@@ -200,6 +200,16 @@ export async function readE2BSource(
   return { canonicalPath, text }
 }
 
+/**
+ * Encode one absolute remote Linux path as a host-independent file URI.
+ * @param path - Canonical POSIX path inside E2B.
+ * @returns The equivalent percent-encoded file URI.
+ */
+export function e2bFileUri(path: string): string {
+  if (!posix.isAbsolute(path)) throw new Error(`lsp-e2b: expected an absolute remote path, received ${JSON.stringify(path)}`)
+  return `file://${path.split('/').map(segment => encodeURIComponent(segment)).join('/')}`
+}
+
 /* jscpd:ignore-start -- Provider identity mirrors the seam while remote source and process ownership stay local. */
 /** One pooled remote provider with an isolated server per canonical workspace. */
 export class E2BLspProvider implements LspProvider {
@@ -298,6 +308,7 @@ export class E2BLspProvider implements LspProvider {
       shutdownTimeoutMs: this.config.shutdownTimeoutMs,
       killGraceMs: this.config.killGraceMs,
       clientProcessId: null,
+      pathToFileUri: e2bFileUri,
     }, (spec: SubprocessSpawnSpec) => {
       const originalArgv = Buffer.from(JSON.stringify(spec.argv)).toString('base64')
       const inner = this.subprocess.spawn({
diff --git a/packages/e2b/lsp-e2b/tests/provider.spec.ts b/packages/e2b/lsp-e2b/tests/provider.spec.ts
index 0b41be12a3..d746abe7f7 100644
--- a/packages/e2b/lsp-e2b/tests/provider.spec.ts
+++ b/packages/e2b/lsp-e2b/tests/provider.spec.ts
@@ -69,6 +69,7 @@ import {
   E2BLspProvider,
   apply,
   canonicalizeE2BWorkspace,
+  e2bFileUri,
   readE2BSource,
 } from '@deepseek-ai/dsh-lsp-e2b'
 import type { LspE2BServerConfig } from '@deepseek-ai/dsh-lsp-e2b'
@@ -234,6 +235,10 @@ describe('E2BLspProvider pooling and lifecycle', () => {
     await expect(current.query(query())).resolves.toEqual({ kind: 'hover', hover: { contents: 'ok' } })
     expect(mockedLsp.FakeLspInstance.instances).toHaveLength(1)
     expect(mockedLsp.FakeLspInstance.instances[0]?.spec).toMatchObject({ clientProcessId: null, cwd: '/workspace' })
+    expect(e2bFileUri('/workspace/a b#c.ts')).toBe('file:///workspace/a%20b%23c.ts')
+    expect(() => e2bFileUri('relative.ts')).toThrow('absolute remote path')
+    const pathToFileUri = mockedLsp.FakeLspInstance.instances[0]?.spec.pathToFileUri as (path: string) => string
+    expect(pathToFileUri('/workspace/a b#c.ts')).toBe('file:///workspace/a%20b%23c.ts')
     expect(spawn).toHaveBeenCalledWith(expect.objectContaining({
       argv: ['/usr/bin/node', '/workspace/.dsh-e2b/lsp-proxy.mjs', expect.any(String)],
       stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 128 } },
diff --git a/packages/e2b/pty-e2b/src/index.ts b/packages/e2b/pty-e2b/src/index.ts
index fca16cf5c7..8fd7a519a0 100644
--- a/packages/e2b/pty-e2b/src/index.ts
+++ b/packages/e2b/pty-e2b/src/index.ts
@@ -71,9 +71,10 @@ export class E2BPtyBackend implements PtyBackend {
     }
     const session = new E2BPtySession(sandbox, handle, this.config)
     created.session = session
-    for (const data of pending) session.onData(data)
     try {
-      await session.initialize(spec.signal)
+      const initializing = session.initialize(spec.signal)
+      for (const data of pending) session.onData(data)
+      await initializing
       return session
     } catch (error: unknown) {
       try {
diff --git a/packages/e2b/pty-e2b/tests/index.spec.ts b/packages/e2b/pty-e2b/tests/index.spec.ts
index 567b3b9215..e306d8b86b 100644
--- a/packages/e2b/pty-e2b/tests/index.spec.ts
+++ b/packages/e2b/pty-e2b/tests/index.spec.ts
@@ -52,7 +52,7 @@ describe('E2BPtyBackend and plugin', () => {
     const backend = new E2BPtyBackend(ctx, config(), async (_sandbox, received) => {
       options = received
       void received.onData(Buffer.from('banner\n'))
-      setTimeout(() => { void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> ')) }, 0)
+      void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
       return created
     })
     const pending = backend.spawn({
@@ -62,7 +62,7 @@ describe('E2BPtyBackend and plugin', () => {
     await vi.advanceTimersByTimeAsync(2)
     const session = await pending
 
-    expect(session.motd).toBe('dsh> ')
+    expect(session.motd).toBe('banner\ndsh> ')
     expect(options).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace/project', timeoutMs: 0 })
     expect(options?.envs).toMatchObject({
       TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ',
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 26bc8f0b51..8b8a70838c 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: ce61de1100791be6e5c4db74c73ff43566281ed9
-README.zh.md: a4c619f0c002cc1d36310c5a9b4a3f7ae655ad1f
+README.md: 3b3bfa88e7e6483decfcdec11355942ae4ff7403
+README.zh.md: 3ff9a51c60636dea5789f9dd11b04aa902b91d0c
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index ce61de1100..3b3bfa88e7 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -11,7 +11,7 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
 - **Stdio projection** — pipe mode forwards E2B callbacks into host Node streams; inherit mode forwards them to the harness process streams; collect mode retains a bounded host tail with offset reads. Optional complete spill files are written remotely and advertised only while within their cap. Batch and streaming stdin use the SDK handle.
 
-The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `tr`, `env`, `chmod`, `tee`, and `kill`. A custom template must retain compatible commands.
+The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands.
 
 ## Model Experience
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index a4c619f0c0..3ff9a51c60 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -11,7 +11,7 @@
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
 - **stdio 投影**：pipe 模式把 E2B 回调转发到宿主 Node 流；inherit 模式把回调转发到 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。可选的完整 spill 文件写在远程，并且只有未超过其上限时才会对外公布。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 
-基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`tr`、`env`、`chmod`、`tee` 和 `kill`。自定义模板必须保留兼容的命令。
+基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令。
 
 ## 模型体验
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 507ea700c4..86bdade589 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -55,37 +55,38 @@ class DeferredStdin extends Writable {
 interface RemotePaths {
   pid: string
   status: string
+  environment: string
   stdout: string
   stderr: string
 }
 
-function explicitEnvironmentNames(env: Readonly<Record<string, string>> | undefined): string {
-  return Object.keys(env ?? {})
-    .map(quoteE2BShellArg)
-    .join(' ')
+function explicitEnvironment(env: Readonly<Record<string, string>> | undefined): string {
+  return Object.entries(env ?? {})
+    .map(([name, value]) => `${name}=${value}\0`)
+    .join('')
 }
 
 function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
   const stdoutRedirect = hasSpill(spec.stdio.stdout)
-    ? `> >(tee -a -- ${quoteE2BShellArg(paths.stdout)})`
+    ? `> >(tee --output-error=warn-nopipe >(head -c ${spec.stdio.stdout.spill.maxBytes} > ${quoteE2BShellArg(paths.stdout)}))`
     : ''
   const stderrRedirect = hasSpill(spec.stdio.stderr)
-    ? `2> >(tee -a -- ${quoteE2BShellArg(paths.stderr)} >&2)`
+    ? `2> >(tee --output-error=warn-nopipe >(head -c ${spec.stdio.stderr.spill.maxBytes} > ${quoteE2BShellArg(paths.stderr)}) >&2)`
     : ''
-  const environmentNames = explicitEnvironmentNames(spec.env)
   const inner = [
     'set +e',
     'umask 077',
     'dsh_e2b_pgid="$(ps -o pgid= -p "$$" | tr -d " ")"',
     `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
+    `mapfile -d '' -t dsh_e2b_explicit < ${quoteE2BShellArg(paths.environment)}`,
+    `: > ${quoteE2BShellArg(paths.environment)}`,
     'dsh_e2b_env=()',
-    `dsh_e2b_explicit=(${environmentNames})`,
-    'while IFS= read -r dsh_e2b_name; do',
+    "while IFS= read -r -d '' dsh_e2b_entry; do",
+    '  dsh_e2b_name="${dsh_e2b_entry%%=*}"',
     '  case "${dsh_e2b_name^^}" in DSH_*|*KEY*|*SECRET*|*TOKEN*) continue ;; esac',
-    '  dsh_e2b_env+=("$dsh_e2b_name=${!dsh_e2b_name}")',
-    'done < <(compgen -e)',
-    'for dsh_e2b_name in "${dsh_e2b_explicit[@]}"; do dsh_e2b_env+=("$dsh_e2b_name=${!dsh_e2b_name}"); done',
-    `env -i "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
+    '  dsh_e2b_env+=("$dsh_e2b_entry")',
+    'done < <(env -0)',
+    `env -i "\${dsh_e2b_env[@]}" "\${dsh_e2b_explicit[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
     'dsh_e2b_status=$?',
     'wait',
     `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
@@ -131,7 +132,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
   private remotePid = -1
-  private settled = false
   private terminationRequested = false
   private terminationSignal: NodeJS.Signals | null = null
   private termination: Promise<void> | undefined
@@ -150,6 +150,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     this.paths = {
       pid: posix.join(stateDir, 'pid'),
       status: posix.join(stateDir, 'exit-code'),
+      environment: posix.join(stateDir, 'environment'),
       stdout: posix.join(stateDir, 'stdout.log'),
       stderr: posix.join(stateDir, 'stderr.log'),
     }
@@ -182,7 +183,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    if (this.terminationRequested || this.settled) return
+    if (this.terminationRequested) return
     this.terminationRequested = true
     this.termination = this.terminateRemote()
     void this.termination.catch(() => {})
@@ -240,7 +241,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           cwd: this.spec.cwd,
           stdin: this.spec.stdio.stdin !== 'ignore',
           timeoutMs: 0,
-          ...(this.spec.env !== undefined ? { envs: this.spec.env } : {}),
           onStdout: async (data) => { await this.dispatchOutput('stdout', data) },
           onStderr: async (data) => { await this.dispatchOutput('stderr', data) },
         },
@@ -250,7 +250,12 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       }
       const completion = handle.wait()
       void completion.catch(() => {})
-      this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
+      try {
+        this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
+      } catch (error: unknown) {
+        await Promise.allSettled([handle.kill()])
+        throw error
+      }
       this.readyState.resolve(handle)
       await this.writeBatchStdin(handle)
       const outcome = await this.waitForCommand(completion)
@@ -260,7 +265,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       this.readyState.reject(error)
       throw error
     } finally {
-      this.settled = true
       this.spec.signal?.removeEventListener('abort', this.onAbort)
       this.stdout?.end()
       this.stderr?.end()
@@ -269,17 +273,16 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async prepareState(sandbox: Sandbox): Promise<void> {
     await sandbox.files.makeDir(this.stateDir)
+    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`)
     const files = [
       { path: this.paths.pid, data: '' },
       { path: this.paths.status, data: '' },
+      { path: this.paths.environment, data: explicitEnvironment(this.spec.env) },
       ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
       ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
     ]
     await sandbox.files.write(files)
-    await sandbox.commands.run([
-      `chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`,
-      `chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`,
-    ].join('\n'))
+    await sandbox.commands.run(`chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`)
   }
 
   private async writeBatchStdin(handle: CommandHandle): Promise<void> {
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index ff9d48073c..6be645a713 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -80,6 +80,7 @@ class FakeSandbox {
   readonly handle = new FakeCommandHandle()
   readonly commandsSeen: string[] = []
   readonly writtenFiles: string[][] = []
+  readonly writtenFileData = new Map<string, string>()
   readonly removed: string[] = []
   readonly directories: string[] = []
   startOptions: StartOptions | undefined
@@ -129,6 +130,7 @@ class FakeSandbox {
       },
       write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
         this.writtenFiles.push(files.map(file => file.path))
+        for (const file of files) this.writtenFileData.set(file.path, file.data)
         return files.map(() => ({}))
       },
       read: async (): Promise<string> => this.processGroupReads.shift() ?? this.processGroupId,
@@ -251,7 +253,7 @@ describe('E2BSubprocessHandle', () => {
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
       argv: ['tool', 'argument with spaces'],
       stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 8, spill: { maxBytes: 32 } } },
-      env: { PATH: '/bin', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' },
+      env: { PATH: '/bin', 'FOO-BAR': 'hyphen-value', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' },
     }), '/workspace/.dsh-e2b/processes/one')
     expect(handle.pid).toBe(-1)
     handle.stdin!.write('hello')
@@ -261,17 +263,26 @@ describe('E2BSubprocessHandle', () => {
     expect(handle.pid).toBe(4343)
     expect(fake.handle.sent.map(value => String(value))).toEqual(['hello'])
     expect(fake.handle.closes).toBe(1)
-    expect(fake.startOptions?.envs).toEqual({ PATH: '/bin', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' })
+    expect(fake.startOptions?.envs).toBeUndefined()
     const command = fake.commandsSeen.find(value => value.startsWith('exec setsid'))!
     expect(command).toContain('exec setsid --wait -- bash -c')
-    expect(command).toContain('DEEPSEEK_API_KEY')
-    expect(command).toContain('DSH_MODE')
+    expect(command).not.toContain('DEEPSEEK_API_KEY')
+    expect(command).not.toContain('DSH_MODE')
+    expect(command).not.toContain('FOO-BAR')
     expect(command).not.toContain('explicit-secret')
+    expect(command).not.toContain('hyphen-value')
+    expect(command).not.toContain('${!dsh_e2b_name}')
+    expect(command).toContain('env -0')
+    expect(command).toContain('mapfile -d')
     expect(fake.writtenFiles[0]).toEqual([
       '/workspace/.dsh-e2b/processes/one/pid',
       '/workspace/.dsh-e2b/processes/one/exit-code',
+      '/workspace/.dsh-e2b/processes/one/environment',
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
+    expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
+      'PATH=/bin\0FOO-BAR=hyphen-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+    )
 
     let piped = ''
     handle.stdout!.on('data', (chunk) => { piped += String(chunk) })
@@ -350,6 +361,11 @@ describe('E2BSubprocessHandle', () => {
     await handle.done
     expect(handle.collected.stdout!.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
     expect(fake.removed).toContain('/runtime/oversize/stdout.log')
+    const command = fake.commandsSeen.find(value => value.startsWith('exec setsid'))!
+    expect(command).toContain('head -c 3')
+    expect(command).toContain('/runtime/oversize/stdout.log')
+    expect(command).toContain('tee --output-error=warn-nopipe')
+    expect(command).not.toContain('tee -a')
   })
 
   it('contains remote spill-removal failures and routes empty inherited output', async () => {
@@ -415,6 +431,22 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
+  it('can terminate a surviving process group after the command leader settles', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/surviving-group')
+    await flush()
+    fake.handle.succeed(0)
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(fake.alive).toBe(true)
+
+    handle.terminate()
+    await flush()
+    const signaled = fake.commandsSeen.includes('kill -TERM -- -4242')
+    if (!signaled) fake.finish()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(signaled).toBe(true)
+  })
+
   it('bounds waitForExit while startup or a live group is pending', async () => {
     const fake = new FakeSandbox()
     fake.deferStart()
@@ -564,8 +596,14 @@ describe('E2BSubprocessHandle', () => {
   it('rejects invalid or absent process-group publication', async () => {
     const invalidGroup = new FakeSandbox()
     invalidGroup.processGroupId = 'not-a-pid\n'
+    vi.spyOn(invalidGroup.handle, 'kill').mockImplementation(async () => {
+      invalidGroup.handle.kills += 1
+      invalidGroup.finish()
+      return true
+    })
     const invalid = new E2BSubprocessHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
     await expect(invalid.done).rejects.toThrow(/invalid process-group id/)
+    expect(invalidGroup.handle.kills).toBe(1)
 
     const absentGroup = new FakeSandbox()
     absentGroup.processGroupId = ''
@@ -573,6 +611,7 @@ describe('E2BSubprocessHandle', () => {
     await flush()
     absentGroup.finish()
     await expect(absent.done).rejects.toThrow(/exited before publishing/)
+    expect(absentGroup.handle.kills).toBe(1)
   })
 
   it('waits for delayed process-group publication', async () => {
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index fc7e50787f..3a2baa0c55 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -1,16 +1,19 @@
 /**
  * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table
  * of server commands and registers one isolated provider for each entry. Every provider lazily
- * single-flights one server process per canonical workspace target, serves transient-open queries
+ * single-flights one server process per canonical workspace realpath, serves transient-open queries
  * through it, and replaces a selected transport that fails before or during the next read-only
- * query. Providers read sources through `ctx.fs` and launch servers through
- * `ctx.subprocess`, so both local and remote implementations share one host.
+ * query. Providers read sources through Node APIs in the host namespace (not `ctx.fs`)
+ * and trust their configured servers — no sandbox confinement.
  *
  * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
  * unregisters from `ctx.lsp` and tears down every live server.
  * @module @deepseek-ai/dsh-lsp-local
  */
 
+import { accessSync, constants, statSync } from 'node:fs'
+import { delimiter, isAbsolute, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
@@ -22,9 +25,9 @@ import type {
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { abortable, abortError } from './abort.ts'
 import { canonicalizeWorkspace, readHostSource } from './host.ts'
-import type { HostWorkspace } from './host.ts'
 import { LspInstance } from './instance.ts'
 import type { ConnectionSpawner } from './connection.ts'
+import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import type { InstanceSpec } from './instance.ts'
 
 export { canonicalizeWorkspace, readHostSource } from './host.ts'
@@ -44,7 +47,10 @@ export { LspConnection } from './connection.ts'
 export const name = 'lsp-local'
 
 /** Services required by this plugin. */
-export const inject = ['fs', 'lsp', 'subprocess']
+export const inject = ['lsp', 'subprocess']
+
+/** Credential-shaped ambient env vars are NOT forwarded to the child by default. */
+
 
 const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
 const DEFAULT_MAX_STDERR_BYTES = 1_000_000
@@ -86,7 +92,6 @@ export interface Config {
 
 /** One server config after schemastery fills every default. */
 type ResolvedServerConfig = Required<LspLocalServerConfig>
-type WorkspaceKey = HostWorkspace['target']['targetKey']
 
 const LspLocalServerConfig: z<LspLocalServerConfig> = z.object({
   command: z.string().required(),
@@ -106,67 +111,27 @@ export const Config: z<Config> = z.object({
   servers: z.dict(LspLocalServerConfig).required(),
 })
 
-/** Propagate teardown failures only after every sibling has settled. */
-function throwTeardownFailures(results: readonly PromiseSettledResult<void>[], message: string): void {
-  const failures: unknown[] = []
-  for (const result of results) {
-    if (result.status === 'rejected') failures.push(result.reason)
-  }
-  if (failures.length === 1) throw failures[0]
-  if (failures.length > 1) throw new AggregateError(failures, message)
-}
-
 /**
  * Register the configured stdio LSP providers. Resolves every executable at load (after credential
  * scrubbing) before publishing any provider; each process launches lazily on its first matching
  * query.
- * @param ctx - the plugin context carrying `fs`, `lsp`, and `subprocess`.
+ * @param ctx - the plugin context (must inject `lsp`).
  * @param config - the resolved plugin configuration (schemastery has filled every default).
  */
-export async function apply(ctx: Context, config: Config): Promise<void> {
+export function apply(ctx: Context, config: Config): void {
   const entries = Object.entries(config.servers)
   if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server')
 
-  const setupAbort = new AbortController()
-  const stopSetupCancellation = ctx.on('internal/plugin', (fiber) => {
-    // An async plugin callback must observe its own disposal before Cordis can
-    // run effect cleanup, because unload otherwise waits for this callback.
-    if (fiber === ctx.fiber && fiber.uid === null) {
-      setupAbort.abort(new Error('lsp-local setup disposed'))
-    }
-  })
-
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
-  const providers = await (async () => {
-    const lookups = entries.map(async ([providerId, rawConfig]) => {
-      if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
-      const resolved = rawConfig as ResolvedServerConfig
-      validateServerConfig(providerId, resolved)
-      const executable = await ctx.subprocess.resolveExecutable(
-        resolved.command,
-        resolved.env,
-        setupAbort.signal,
-      )
-      setupAbort.signal.throwIfAborted()
-      return new LocalLspProvider(
-        providerId,
-        ctx.fs,
-        resolved,
-        executable,
-        spec => ctx.subprocess.spawn(spec),
-      )
-    })
-    try {
-      return await Promise.all(lookups)
-    } catch (error: unknown) {
-      setupAbort.abort(error)
-      await Promise.allSettled(lookups)
-      throw error
-    } finally {
-      stopSetupCancellation()
-    }
-  })()
+  const providers = entries.map(([providerId, rawConfig]) => {
+    if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
+    const resolved = rawConfig as ResolvedServerConfig
+    validateServerConfig(providerId, resolved)
+    const childEnv = buildChildEnv(resolved.env)
+    const executable = resolveExecutable(resolved.command, childEnv)
+    return new LocalLspProvider(providerId, resolved, childEnv, executable, spec => ctx.subprocess.spawn(spec))
+  })
 
   ctx.effect(() => {
     const disposers: Array<() => void> = []
@@ -179,8 +144,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
     return async () => {
       // Remove every route before process teardown so no new query can enter a draining provider.
       for (const dispose of disposers.reverse()) dispose()
-      const results = await Promise.allSettled(providers.map(provider => provider.disposeAll()))
-      throwTeardownFailures(results, 'lsp-local provider teardown failed')
+      await Promise.all(providers.map(provider => provider.disposeAll()))
     }
   }, 'lsp-local.registerProviders')
 }
@@ -217,19 +181,16 @@ function assertPositiveInteger(providerId: string, name: string, value: number):
 class LocalLspProvider implements LspProvider {
   readonly id: LspProviderId
   readonly extensionToLanguage: Readonly<Record<string, string>>
-  /** One live instance per stable canonical workspace identity. */
-  private readonly instances = new Map<WorkspaceKey, LspInstance>()
+  /** One live instance per canonical workspace realpath. */
+  private readonly instances = new Map<string, LspInstance>()
   /** One complete source-read→open→query→close serialization tail per canonical workspace. */
-  private readonly queues = new Map<WorkspaceKey, Promise<void>>()
-  /** Workspace canonicalizations that have not entered a provider-owned queue yet. */
-  private readonly workspaceLookups = new Set<Promise<void>>()
-  private readonly lifetime = new AbortController()
+  private readonly queues = new Map<string, Promise<void>>()
   private disposed = false
 
   constructor(
     providerId: string,
-    private readonly fs: Context['fs'],
     private readonly config: ResolvedServerConfig,
+    private readonly childEnv: Record<string, string>,
     private readonly executable: string,
     private readonly spawner: ConnectionSpawner,
   ) {
@@ -250,60 +211,43 @@ class LocalLspProvider implements LspProvider {
     if (signal?.aborted) throw abortError(signal)
   }
 
-  /** Fuse caller cancellation with provider disposal for every filesystem and protocol await. */
-  private querySignal(signal?: AbortSignal): AbortSignal {
-    return signal === undefined
-      ? this.lifetime.signal
-      : AbortSignal.any([signal, this.lifetime.signal])
-  }
-
   async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
-    // Honor an already-aborted signal before provider I/O so a canceled request never starts a server.
+    // Honor an already-aborted signal before host I/O so a canceled request never starts a server.
     this.assertActive(signal)
-    const querySignal = this.querySignal(signal)
-    const workspaceResult = canonicalizeWorkspace(this.fs, request.workspaceRoot, querySignal)
-    const workspaceLookup = workspaceResult.then(() => undefined, () => undefined)
-    this.workspaceLookups.add(workspaceLookup)
-    let workspace: HostWorkspace
-    try {
-      workspace = await workspaceResult
-    } finally {
-      this.workspaceLookups.delete(workspaceLookup)
-    }
-    this.assertActive(querySignal)
-    const workspaceKey = workspace.target.targetKey
-    return this.enqueue(workspaceKey, querySignal, async () => {
-      this.assertActive(querySignal)
+    const workspace = await canonicalizeWorkspace(request.workspaceRoot, signal)
+    this.assertActive(signal)
+    return this.enqueue(workspace, signal, async () => {
+      this.assertActive(signal)
       // Read inside the workspace queue but before spawning: a queued query sees current bytes when
       // its turn starts, while an invalid source still cannot leave an idle process pooled.
-      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, querySignal)
+      const source = await readHostSource(request.filePath, workspace, this.config.maxDocumentBytes, signal)
       // Disposal may have snapshotted the instance map while host I/O was pending. Re-check before a
       // synchronous get-or-create so every spawned process remains owned by teardown.
-      this.assertActive(querySignal)
-      let instance = this.instanceFor(workspaceKey, workspace)
+      this.assertActive(signal)
+      let instance = this.instanceFor(workspace)
       try {
-        return await instance.query(request, source, querySignal)
+        return await instance.query(request, source, signal)
       } catch (error) {
         // A selected child can have died while idle or fail during the next write. Queries are
         // read-only, so replace that transport once and retry transparently.
         if (!instance.isTransportFailure(error)) throw error
         await instance.dispose()
-        this.evictIfCurrent(workspaceKey, instance)
-        this.assertActive(querySignal)
-        instance = this.instanceFor(workspaceKey, workspace)
-        return await instance.query(request, source, querySignal)
+        this.evictIfCurrent(workspace, instance)
+        this.assertActive(signal)
+        instance = this.instanceFor(workspace)
+        return await instance.query(request, source, signal)
       } finally {
         // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check.
         if (instance.dead) {
           await instance.dispose()
-          this.evictIfCurrent(workspaceKey, instance)
+          this.evictIfCurrent(workspace, instance)
         }
       }
     })
   }
 
   /** Serialize one complete query lifecycle for a canonical workspace. */
-  private enqueue<T>(workspace: WorkspaceKey, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
+  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
     const previous = this.queues.get(workspace) ?? Promise.resolve()
     const result = abortable(previous, signal).then(run)
     // The tail follows the actual prior work even when this caller aborts its wait. It never rejects,
@@ -317,34 +261,34 @@ class LocalLspProvider implements LspProvider {
   }
 
   /** Return or synchronously publish the one instance for a canonical workspace. */
-  private instanceFor(workspaceKey: WorkspaceKey, workspace: HostWorkspace): LspInstance {
+  private instanceFor(workspace: string): LspInstance {
     this.assertActive()
-    const existing = this.instances.get(workspaceKey)
+    const existing = this.instances.get(workspace)
     if (existing !== undefined) return existing
     const created = this.createInstance(workspace)
-    this.instances.set(workspaceKey, created)
+    this.instances.set(workspace, created)
     return created
   }
 
   /** Drop the slot iff it still contains this instance. */
-  private evictIfCurrent(workspace: WorkspaceKey, instance: LspInstance): void {
+  private evictIfCurrent(workspace: string, instance: LspInstance): void {
     /* v8 ignore next -- mismatch requires another query to replace the slot before this finally runs. */
     if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
   }
 
-  private createInstance(workspace: HostWorkspace): LspInstance {
+  private createInstance(workspace: string): LspInstance {
     const spec: InstanceSpec = {
       command: this.executable,
       args: this.config.args,
-      cwd: workspace.canonicalPath,
-      workspaceUri: workspace.fileUrl,
-      env: this.config.env,
+      cwd: workspace,
+      env: this.childEnv,
       configuration: this.config.configuration,
       initializationOptions: this.config.initializationOptions,
       maxMessageBytes: this.config.maxMessageBytes,
       maxStderrBytes: this.config.maxStderrBytes,
       shutdownTimeoutMs: this.config.shutdownTimeoutMs,
       killGraceMs: this.config.killGraceMs,
+      pathToFileUri: path => pathToFileURL(path).href,
     }
     return new LspInstance(spec, this.spawner)
   }
@@ -352,18 +296,51 @@ class LocalLspProvider implements LspProvider {
   /** Dispose every live instance and block further queries. */
   async disposeAll(): Promise<void> {
     this.disposed = true
-    this.lifetime.abort(new LspError('lsp-local provider is disposed', 'LSP_DISPOSED'))
     const live = [...this.instances.values()]
     const draining = [...this.queues.values()]
-    const resolving = [...this.workspaceLookups]
     this.instances.clear()
-    const results = await Promise.allSettled([
+    await Promise.all([
       ...live.map(instance => instance.dispose()),
       ...draining,
-      ...resolving,
     ])
     this.queues.clear()
-    this.workspaceLookups.clear()
-    throwTeardownFailures(results, 'lsp-local instance teardown failed')
+  }
+}
+
+/** The seam's scrubbed parent env (credential-shaped and DSH_* names dropped), plus the config's explicit env. */
+function buildChildEnv(extra: Record<string, string>): Record<string, string> {
+  return { ...scrubbedParentEnv(), ...extra }
+}
+
+/**
+ * Resolve the server executable to an absolute path: an absolute command is verified directly; a
+ * bare command is looked up on the child's PATH. Fails loudly when nothing is executable.
+ */
+function resolveExecutable(command: string, childEnv: Record<string, string>): string {
+  if (isAbsolute(command)) {
+    // Verify an absolute command too, so an unavailable one fails at load, not on the first query.
+    if (!isExecutableFileSync(command)) {
+      throw new Error(`lsp-local: command "${command}" is not an executable file`)
+    }
+    return command
+  }
+  /* v8 ignore next -- buildChildEnv always sets PATH from the ambient env; the further fallbacks are defensive. */
+  const pathValue = childEnv.PATH ?? process.env.PATH ?? ''
+  for (const dir of pathValue.split(delimiter)) {
+    if (dir === '') continue
+    const candidate = join(dir, command)
+    if (isExecutableFileSync(candidate)) return candidate
+  }
+  throw new Error(`lsp-local: command "${command}" was not found on PATH`)
+}
+
+/** Synchronous regular-file and executable check used only at load-time resolution. */
+function isExecutableFileSync(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) return false
+    accessSync(path, constants.X_OK)
+    return true
+  } catch {
+    return false
   }
 }
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index d643db1528..5a12192c62 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -7,7 +7,6 @@
  * @module @deepseek-ai/dsh-lsp-local/instance
  */
 
-import { pathToFileURL } from 'node:url'
 import { LspError } from '@deepseek-ai/dsh-lsp'
 import type {
   LspOperation,
@@ -37,6 +36,12 @@ export interface InstanceSpec extends ConnectionSpec {
   readonly shutdownTimeoutMs: number
   /** PID advertised to the server; `null` when client and server do not share a process namespace. */
   readonly clientProcessId?: number | null
+  /**
+   * Encode one implementation-native absolute path as a file URI.
+   * @param path - Canonical workspace or source path.
+   * @returns A file URI interpreted in the server's filesystem namespace.
+   */
+  readonly pathToFileUri: (path: string) => string
 }
 
 /**
@@ -111,8 +116,8 @@ export class LspInstance {
   private async initialize(): Promise<void> {
     const initializeResult = await this.connection.request('initialize', {
       processId: this.spec.clientProcessId === undefined ? process.pid : this.spec.clientProcessId,
-      rootUri: pathToFileURL(this.spec.cwd).href,
-      workspaceFolders: [{ uri: pathToFileURL(this.spec.cwd).href, name: 'workspace' }],
+      rootUri: this.spec.pathToFileUri(this.spec.cwd),
+      workspaceFolders: [{ uri: this.spec.pathToFileUri(this.spec.cwd), name: 'workspace' }],
       capabilities: CLIENT_CAPABILITIES,
       initializationOptions: this.spec.initializationOptions,
     }) as WireInitializeResult
@@ -149,7 +154,7 @@ export class LspInstance {
       throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION')
     }
 
-    const uri = pathToFileURL(source.canonicalPath).href
+    const uri = this.spec.pathToFileUri(source.canonicalPath)
     let opened = false
     try {
       /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 939b58f0b1..fc1d05843c 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -56,6 +56,7 @@ function makeInstance(
     maxStderrBytes: 100_000,
     shutdownTimeoutMs: 200,
     killGraceMs: 200,
+    pathToFileUri: path => pathToFileURL(path).href,
     ...overrides,
   }, spawnSubprocess, writer)
   live.push(instance)
@@ -91,6 +92,7 @@ function scriptInstance(script: string, overrides: Partial<InstanceSpec> = {}):
     maxStderrBytes: 100_000,
     shutdownTimeoutMs: 150,
     killGraceMs: 150,
+    pathToFileUri: path => pathToFileURL(path).href,
     ...overrides,
   }, spawnSubprocess)
   live.push(instance)

From bccad1bb31d21a0290cdcbab23584c86feba80b1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 16:30:28 +0800
Subject: [PATCH 356/516] fix(e2b): normalize setup rejection reasons

---
 packages/e2b/code-runtime-e2b/src/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/e2b/code-runtime-e2b/src/index.ts b/packages/e2b/code-runtime-e2b/src/index.ts
index a567a2bb6d..b6245244ba 100644
--- a/packages/e2b/code-runtime-e2b/src/index.ts
+++ b/packages/e2b/code-runtime-e2b/src/index.ts
@@ -213,7 +213,7 @@ export class E2BCodeRuntime extends CodeRuntime {
         (runtime) => { cleanup(); resolve(runtime) },
         (error: unknown) => {
           cleanup()
-          reject(error instanceof Error ? error : new Error(String(error)))
+          reject(new Error(messageOf(error), { cause: error }))
         },
       )
     })

From dc44f93c39d284d378bc687769a0616758a13f82 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 16:54:29 +0800
Subject: [PATCH 357/516] fix(e2b): simplify setup abort wait

---
 packages/e2b/code-runtime-e2b/src/index.ts | 32 ++++++++++------------
 1 file changed, 14 insertions(+), 18 deletions(-)

diff --git a/packages/e2b/code-runtime-e2b/src/index.ts b/packages/e2b/code-runtime-e2b/src/index.ts
index b6245244ba..c37cb3cc64 100644
--- a/packages/e2b/code-runtime-e2b/src/index.ts
+++ b/packages/e2b/code-runtime-e2b/src/index.ts
@@ -199,24 +199,20 @@ export class E2BCodeRuntime extends CodeRuntime {
   }
   /* jscpd:ignore-end */
 
-  private awaitPreparation(signal: AbortSignal | undefined): Promise<PreparedRuntime | undefined> {
-    if (signal === undefined) return this.ready
-    return new Promise<PreparedRuntime | undefined>((resolve, reject) => {
-      const onAbort = (): void => { cleanup(); resolve(undefined) }
-      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
-      signal.addEventListener('abort', onAbort, { once: true })
-      if (signal.aborted) {
-        onAbort()
-        return
-      }
-      void this.ready.then(
-        (runtime) => { cleanup(); resolve(runtime) },
-        (error: unknown) => {
-          cleanup()
-          reject(new Error(messageOf(error), { cause: error }))
-        },
-      )
-    })
+  private async awaitPreparation(signal: AbortSignal | undefined): Promise<PreparedRuntime | undefined> {
+    if (signal === undefined) return await this.ready
+    const aborted = Promise.withResolvers<undefined>()
+    const onAbort = (): void => { aborted.resolve(undefined) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    if (signal.aborted) {
+      signal.removeEventListener('abort', onAbort)
+      return undefined
+    }
+    try {
+      return await Promise.race([this.ready, aborted.promise])
+    } finally {
+      signal.removeEventListener('abort', onAbort)
+    }
   }
 
   private assertPreparationActive(): void {

From 3e343b44778633350f02420c11cc45ea0168e91e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 18:31:37 +0800
Subject: [PATCH 358/516] fix(e2b): harden remote adapter boundaries

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |  12 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |  12 +-
 .../tests/fixtures/e2b/e2b/bin.ts             | 128 ++++++++++-
 .../tests/fixtures/e2b/e2b/cordis.yml         |   2 +-
 .../e2b/code-runtime-e2b/README.i18n.yaml     |   4 +-
 packages/e2b/code-runtime-e2b/README.md       |   2 +-
 packages/e2b/code-runtime-e2b/README.zh.md    |   2 +-
 .../e2b/code-runtime-e2b/src/runner-source.ts | 212 ++++++++++++++++--
 .../code-runtime-e2b/tests/runtime.spec.ts    | 117 ++++++++++
 packages/e2b/e2b/tests/composition.e2e.ts     |  64 +++++-
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   2 +-
 packages/e2b/fs-e2b/README.zh.md              |   2 +-
 packages/e2b/fs-e2b/src/index.ts              |   6 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |  11 +
 packages/e2b/lsp-e2b/README.i18n.yaml         |   4 +-
 packages/e2b/lsp-e2b/README.md                |   2 +-
 packages/e2b/lsp-e2b/README.zh.md             |   2 +-
 packages/e2b/lsp-e2b/src/index.ts             |  90 +++++++-
 packages/e2b/lsp-e2b/tests/provider.spec.ts   |  44 ++--
 packages/e2b/pty-e2b/README.i18n.yaml         |   4 +-
 packages/e2b/pty-e2b/README.md                |   5 +-
 packages/e2b/pty-e2b/README.zh.md             |   5 +-
 packages/e2b/pty-e2b/src/index.ts             |  42 +++-
 packages/e2b/pty-e2b/src/session.ts           |  56 ++++-
 packages/e2b/pty-e2b/tests/index.spec.ts      |  63 +++++-
 packages/e2b/pty-e2b/tests/session.spec.ts    | 109 ++++++---
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   4 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   4 +-
 packages/e2b/subprocess-e2b/src/process.ts    |  22 +-
 .../subprocess-e2b/tests/subprocess.spec.ts   |  41 +++-
 33 files changed, 939 insertions(+), 146 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 5ed4e445b8..beb49fba76 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: a713cca3fd9e7ee11a2c487bf6ed2c3a205dc502
-2026-07-27-e2b-remote-runtime-poc.zh.md: 7afd54f72622d51a3d71719b3b4975ccd7f83e3a
+2026-07-27-e2b-remote-runtime-poc.md: efb91fc166f36dc8fb047d686e8cd82d93b9af6a
+2026-07-27-e2b-remote-runtime-poc.zh.md: eb14cccc284d38cdc5cc704512b6899621a9a840
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index a713cca3fd..efb91fc166 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -18,7 +18,7 @@ The E2B integration is an opt-in provider-composition POC. Its six E2B-specific
 - `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
 - `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands and remote Linux process groups.
 - `@deepseek-ai/dsh-pty-e2b` registers an E2B byte-PTY backend on `ctx.pty` while the existing registry retains exact-Agent ownership.
-- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through E2B Filesystem APIs, and runs servers through `dsh-subprocess-e2b`.
+- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through a bounded no-follow helper in E2B, and runs servers through `dsh-subprocess-e2b`.
 - `@deepseek-ai/dsh-code-runtime-e2b` registers `ctx.codeRuntime`, runs each model program in a fresh remote worker, and dispatches binding functions in the host process.
 - The existing `@deepseek-ai/dsh-bash-local` remains the Bash implementation because it delegates all process mechanics to `ctx.subprocess`.
 
@@ -28,11 +28,11 @@ The providers reuse the PTY, LSP, Code Runtime, and subprocess seams without cha
 
 ## POC boundary
 
-E2B owns the mutable filesystem, command and Bash processes, PTY shell and foreground process groups, language-server processes and source reads, the Code Runtime runner and worker, and adapter-private files under `.dsh-e2b`.
+E2B owns the mutable filesystem, command and Bash processes, PTY shell and terminal-session process groups, language-server processes and source reads, the Code Runtime launcher, controller, and worker, and adapter-private files under `.dsh-e2b`.
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP and Code Runtime install dependency-free remote helpers that encode raw payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
+Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP installs a bounded remote source reader, while Code Runtime keeps framed stdout in a launcher process isolated from the controller and worker descriptors. Their dependency-free helpers encode protocol payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
@@ -40,9 +40,9 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 ## Verification
 
-Focused package suites pin owner lifecycle cleanup, filesystem semantics, subprocess process groups, configuration and publication rollback, byte framing and multibyte boundaries, PTY readiness/signals, LSP transport and source containment, Code Runtime bindings, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
+Focused package suites pin owner lifecycle cleanup, filesystem semantics and commit metadata, subprocess process groups, configuration and verified publication rollback, byte framing and multibyte boundaries, PTY readiness/signals/default-environment scrubbing/terminal-session cleanup, stable bounded LSP source reads, Code Runtime binding and descriptor isolation, worker-pipe draining, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
 
-A credential-gated Loader composition creates one real E2B sandbox and exercises FS-to-Bash and Bash-to-FS visibility, multibyte PTY output and `SIGINT`, multibyte LSP hover and definition results, Code Runtime host bindings and typed rejection under mutation of adapter-captured intrinsics, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same scenario runs through source imports and built package exports.
+A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, bounded spill output, PTY default-secret scrubbing and process-tree cleanup, stable bounded LSP source reads, Code Runtime host bindings and descriptor-isolated output accounting, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
 ## Alternatives considered
 
@@ -66,4 +66,4 @@ A credential-gated Loader composition creates one real E2B sandbox and exercises
 
 The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
 
-The providers are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a captured remote process group does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
+The providers are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or PTY session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 7afd54f726..eb14cccc28 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -18,7 +18,7 @@ E2B 集成是一个选择性启用的提供方组合 POC。它的 6 个 E2B 专
 - `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
 - `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands 和远程 Linux 进程组之上实现 `ctx.subprocess`。
 - `@deepseek-ai/dsh-pty-e2b` 在 `ctx.pty` 上注册 E2B 字节 PTY 后端，并把精确的 Agent 所有权保留在现有注册表中。
-- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B Filesystem API 读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
+- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B 内有界且不跟随链接的辅助程序读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
 - `@deepseek-ai/dsh-code-runtime-e2b` 注册 `ctx.codeRuntime`，在全新的远程 worker 中运行每个模型程序，并在宿主进程中分发绑定函数。
 - 现有的 `@deepseek-ai/dsh-bash-local` 继续作为 Bash 实现，因为它把所有进程机制委托给 `ctx.subprocess`。
 
@@ -28,11 +28,11 @@ E2B 集成是一个选择性启用的提供方组合 POC。它的 6 个 E2B 专
 
 ## POC 边界
 
-E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程组、语言服务器进程及源码读取、Code Runtime 运行器和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
+E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话进程组、语言服务器进程及源码读取、Code Runtime launcher、controller 和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 与 Code Runtime 会安装无依赖的远程辅助程序，把原始载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
+对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 会安装一个有界的远程源码读取器；Code Runtime 则把分帧 stdout 保留在与 controller 和 worker 描述符隔离的 launcher 进程内。它们的无依赖辅助程序会把协议载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
@@ -40,9 +40,9 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程
 
 ## 验证
 
-聚焦包测试套件固定所有者生命周期清理、文件系统语义、进程管理的进程组、配置与发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号、LSP 传输与源码路径约束、Code Runtime 绑定、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
+聚焦包测试套件固定所有者生命周期清理、文件系统语义与提交元数据、进程管理的进程组、配置与经过验证的发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号／默认环境清理／终端会话清理、稳定且有界的 LSP 源码读取、Code Runtime 绑定与描述符隔离、worker 管道排空、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
 
-凭据门控的 Loader 组合会创建一个真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、多字节 PTY 输出和 `SIGINT`、多字节 LSP 悬停与定义结果、Code Runtime 宿主绑定，以及适配器已捕获 intrinsic 被修改时的类型化 reject、墙钟超时、中止、运行器清理、宿主工作区隔离，以及最终删除沙箱。同一场景分别通过源代码导入与已构建包导出运行。
+凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、有界 spill 输出、PTY 默认秘密清理与进程树清理、稳定且有界的 LSP 源码读取、Code Runtime 宿主绑定与描述符隔离的输出记账、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
@@ -66,4 +66,4 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与前台进程
 
 这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
 
-这些提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离已捕获远程进程组的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
+这些提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或 PTY 会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 89b09a6818..4f2401d2c7 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -5,7 +5,7 @@ import { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-code-runtime-e2b'
-import type {} from '@deepseek-ai/dsh-e2b'
+import { quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
 import type {} from '@deepseek-ai/dsh-bash-local'
 import type {} from '@deepseek-ai/dsh-lsp-e2b'
@@ -34,6 +34,7 @@ const owner: Agent = {
 const unregisterOwner = ctx.agents.register(owner)
 let terminalId: Awaited<ReturnType<typeof ctx.pty.spawn>>['sessionId'] | undefined
 try {
+  const sandbox = await ctx.e2b.getSandbox()
   const fromFs = await ctx.fs.resolve('from-fs.txt')
   await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
   const bashRead = await ctx.bash.run(ctx.bash.resolve({ command: 'cat from-fs.txt' }))
@@ -72,6 +73,38 @@ try {
   ].every(entry => environmentLines.has(entry))
   if (!explicitEnvironment) throw new Error(`E2B subprocess dropped an explicit environment entry: ${environmentText}`)
 
+  const remoteFiles = sandbox.files as unknown as {
+    read(path: string, options?: unknown): Promise<unknown>
+  }
+  const readRemoteFile = remoteFiles.read.bind(sandbox.files)
+  let publicationFaultInjected = false
+  remoteFiles.read = async (path, options) => {
+    if (!publicationFaultInjected && path.includes('/processes/') && path.endsWith('/pid')) {
+      publicationFaultInjected = true
+      throw new Error('injected process-group publication read failure')
+    }
+    return await readRemoteFile(path, options)
+  }
+  let publicationRollback = false
+  try {
+    const unpublished = ctx.subprocess.spawn({
+      argv: ['bash', '-c', 'exec -a dsh-publication-survivor sleep 30 & wait'],
+      cwd: process.cwd(),
+      stdio: { stdin: 'ignore', stdout: { maxBytes: 4_096 }, stderr: { maxBytes: 4_096 } },
+      graceMs: 500,
+      env: {},
+    })
+    await unpublished.done
+    throw new Error('E2B subprocess unexpectedly survived an injected publication failure')
+  } catch (error: unknown) {
+    if (!String(error).includes('injected process-group publication read failure')) throw error
+    const processes = await sandbox.commands.run('ps -eo args=')
+    publicationRollback = publicationFaultInjected && !processes.stdout.includes('dsh-publication-survivor')
+    if (!publicationRollback) throw new Error('E2B subprocess publication rollback left its remote process group alive')
+  } finally {
+    remoteFiles.read = readRemoteFile
+  }
+
   const spillHandle = ctx.subprocess.spawn({
     argv: ['bash', '-c', "printf '0123456789'; sleep 30"],
     cwd: process.cwd(),
@@ -81,7 +114,7 @@ try {
   })
   const spillReader = spillHandle.collected.stdout
   if (spillReader === undefined) throw new Error('E2B subprocess omitted its configured stdout collector')
-  const spillDeadline = Date.now() + 5_000
+  const spillDeadline = Date.now() + 15_000
   while (spillReader.readFrom(0).nextOffset < 10) {
     if (Date.now() >= spillDeadline) throw new Error('E2B subprocess did not stream the spill probe output')
     await new Promise(resolveDelay => setTimeout(resolveDelay, 20))
@@ -114,6 +147,53 @@ try {
     workspaceRoot: process.cwd(),
   })
 
+  const swappedSource = await ctx.fs.resolve('swapped-source.ts')
+  const swappedSourcePath = posix.join(process.cwd(), 'swapped-source.ts')
+  await ctx.fs.writeText(swappedSource, 'const safe = true\n', { kind: 'createIfAbsent' })
+  const remoteCommands = sandbox.commands as unknown as {
+    run(command: string, options?: unknown): Promise<{ exitCode: number; stdout: string; stderr: string }>
+  }
+  const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
+  let containmentFaultInjected = false
+  remoteCommands.run = async (command, options) => {
+    if (!containmentFaultInjected && command.includes('dsh-e2b-source-reader') && command.includes('swapped-source.ts')) {
+      containmentFaultInjected = true
+      await runRemoteCommand(`rm -f -- ${quoteE2BShellArg(swappedSourcePath)} && ln -s -- /etc/hosts ${quoteE2BShellArg(swappedSourcePath)}`)
+    }
+    return await runRemoteCommand(command, options)
+  }
+  let lspContainment = false
+  try {
+    await ctx.lsp.query({
+      operation: 'hover',
+      filePath: 'swapped-source.ts',
+      position: { line: 0, character: 1 },
+      workspaceRoot: process.cwd(),
+    })
+  } catch (error: unknown) {
+    lspContainment = containmentFaultInjected && String(error).includes('opened safely')
+    if (!lspContainment) throw error
+  } finally {
+    remoteCommands.run = runRemoteCommand
+  }
+  if (!lspContainment) throw new Error('E2B LSP source swap was not rejected')
+
+  const oversizedSourcePath = posix.join(process.cwd(), 'oversized-source.ts')
+  await sandbox.commands.run(`head -c 4000001 /dev/zero > ${quoteE2BShellArg(oversizedSourcePath)}`)
+  let lspDocumentBound = false
+  try {
+    await ctx.lsp.query({
+      operation: 'hover',
+      filePath: 'oversized-source.ts',
+      position: { line: 0, character: 0 },
+      workspaceRoot: process.cwd(),
+    })
+  } catch (error: unknown) {
+    lspDocumentBound = String(error).includes('over the 4000000-byte limit')
+    if (!lspDocumentBound) throw error
+  }
+  if (!lspDocumentBound) throw new Error('E2B LSP accepted an oversized remote source')
+
   const terminal = await ctx.pty.spawn(owner, { type: 'shell' })
   terminalId = terminal.sessionId
   const terminalEcho = await ctx.pty.startSend(owner, terminal.sessionId, {
@@ -124,9 +204,19 @@ try {
   await new Promise(resolveDelay => setTimeout(resolveDelay, 150))
   const terminalSignal = await ctx.pty.signal(owner, terminal.sessionId, 'SIGINT')
   const interrupted = await sleeping.done
+  const stubborn = await ctx.pty.startSend(owner, terminal.sessionId, {
+    text: "bash -c 'trap \"\" TERM; exec sleep 30' & printf 'DSH_STUBBORN_PID=%s\\n' \"$!\"",
+    submit: true,
+  }).done
+  const stubbornMatch = /DSH_STUBBORN_PID=([1-9][0-9]*)/.exec(stubborn.viewport)
+  if (stubbornMatch?.[1] === undefined) throw new Error(`E2B PTY did not report its stubborn child: ${stubborn.viewport}`)
+  const stubbornPid = Number(stubbornMatch[1])
   const terminalScrollback = ctx.pty.read(owner, terminal.sessionId, { count: 50 })
   await ctx.pty.kill(owner, terminal.sessionId, 'live E2B composition complete')
   terminalId = undefined
+  const stubbornProbe = await sandbox.commands.run(`if kill -0 ${stubbornPid} 2>/dev/null; then printf alive; else printf gone; fi`)
+  const terminalTreeCleanup = stubbornProbe.stdout === 'gone'
+  if (!terminalTreeCleanup) throw new Error(`E2B PTY left process ${stubbornPid} alive after close`)
 
   const code = await ctx.codeRuntime.run({
     program: `
@@ -179,6 +269,33 @@ try {
     `,
     bindings: [],
   })
+  const nativeOutput = await ctx.codeRuntime.run({
+    program: `
+      let stdoutPrototype = Object.getPrototypeOf(process.stdout)
+      while (stdoutPrototype && !Object.hasOwn(stdoutPrototype, 'write')) stdoutPrototype = Object.getPrototypeOf(stdoutPrototype)
+      Reflect.apply(stdoutPrototype.write, process.stdout, ['x'.repeat(8192)])
+      return true
+    `,
+    bindings: [],
+  })
+  const descriptorOutput = await ctx.codeRuntime.run({
+    program: `
+      const fs = await import('node:fs')
+      const forged = Buffer.from(JSON.stringify({ type: 'done' })).toString('base64') + '\\n'
+      fs.writeSync(1, forged)
+      fs.writeSync(1, 'x'.repeat(8192))
+      return true
+    `,
+    bindings: [],
+  })
+  const inheritedOutput = await ctx.codeRuntime.run({
+    program: `
+      const childProcess = await import('node:child_process')
+      childProcess.spawnSync(process.execPath, ['-e', 'process.stdout.write("x".repeat(8192))'], { stdio: 'inherit' })
+      return true
+    `,
+    bindings: [],
+  })
   const timedOut = await ctx.codeRuntime.run({
     program: 'await new Promise(() => {})',
     bindings: [],
@@ -212,18 +329,25 @@ try {
     bashRead: bashRead.stdout.text,
     fsRead,
     explicitEnvironment,
+    publicationRollback,
     spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
     definition,
+    lspContainment,
+    lspDocumentBound,
     terminal: {
       motd: terminal.motd,
       echo: terminalEcho,
       signal: terminalSignal,
       interrupted,
+      treeCleanup: terminalTreeCleanup,
       scrollback: terminalScrollback.text,
     },
     code,
     hostileOutput,
+    nativeOutput,
+    descriptorOutput,
+    inheritedOutput,
     timedOut,
     aborted,
     oversizedBoot,
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 6b3350e49c..65bd3d5246 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -2,7 +2,7 @@
   name: '@deepseek-ai/dsh-e2b'
   config:
     cwd: !!js process.cwd()
-    timeoutMs: 120000
+    timeoutMs: 180000
     onTimeout: kill
     onDispose: kill
 
diff --git a/packages/e2b/code-runtime-e2b/README.i18n.yaml b/packages/e2b/code-runtime-e2b/README.i18n.yaml
index 9eb2633b86..ba43d787b8 100644
--- a/packages/e2b/code-runtime-e2b/README.i18n.yaml
+++ b/packages/e2b/code-runtime-e2b/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/e2b/code-runtime-e2b/README.md
-README.md: 1007800c59725d116197a52f6d087ea5e2860686
-README.zh.md: a56026bce760879079627dd63a80dfe95c4d2049
+README.md: 171e63a8c1ca70deb63e9860f5088b83401a37d0
+README.zh.md: b70984e765d32985436c15dd543263cc06a25715
diff --git a/packages/e2b/code-runtime-e2b/README.md b/packages/e2b/code-runtime-e2b/README.md
index 1007800c59..171e63a8c1 100644
--- a/packages/e2b/code-runtime-e2b/README.md
+++ b/packages/e2b/code-runtime-e2b/README.md
@@ -19,7 +19,7 @@ Every value is a positive safe integer. `maxOutputBytes` is at least four bytes,
 
 ## Execution and bridge contract
 
-Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner creates a fresh worker thread with an empty environment and heap limit, measures active event-loop time, and destroys that worker after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in that group stop with the run.
+Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner keeps the framed host protocol in a launcher process, forks a controller whose stdout and stderr are bounded data pipes, and creates a fresh worker thread with an empty environment and heap limit. Model writes to native descriptors and inherited child output therefore cannot enter the frame stream; worker and controller pipes drain before the terminal frame. The worker measures active event-loop time and is destroyed after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in that group stop with the run.
 
 The bridge uses validated newline-delimited base64 JSON frames because E2B subprocess callbacks expose decoded text. Binding arguments and resolutions use the worker runtime's iterative lossless-JSON wire shape; binding functions execute on the host and typed rejection classes are materialized inside the remote worker. The worker captures the JavaScript intrinsics that its adapter boundary invokes before model code runs, hardening binding transport, output accounting, and completion validation against mutation of those references. The host repeats message validation, call-id deduplication, lossless-JSON checks, and the outer-output ledger.
 
diff --git a/packages/e2b/code-runtime-e2b/README.zh.md b/packages/e2b/code-runtime-e2b/README.zh.md
index a56026bce7..b70984e765 100644
--- a/packages/e2b/code-runtime-e2b/README.zh.md
+++ b/packages/e2b/code-runtime-e2b/README.zh.md
@@ -19,7 +19,7 @@
 
 ## 执行与桥接契约
 
-设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会创建一个具有空环境与堆上限的全新 worker 线程，测量事件循环活跃时间，并在一次运行结算后销毁该 worker。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此组内的普通子进程会随本次运行一同停止。
+设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会把面向宿主的分帧协议保留在 launcher 进程内，派生一个以 stdout 和 stderr 作为有界数据管道的 controller，再创建一个具有空环境与堆上限的全新 worker 线程。因此，模型对原生描述符的写入和继承的子进程输出无法进入分帧流；worker 与 controller 管道会在发出终结帧前排空。worker 会测量事件循环活跃时间，并在一次运行结算后销毁。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此组内的普通子进程会随本次运行一同停止。
 
 由于 E2B 进程管理回调公开的是已解码文本，桥接层使用经过验证、以换行分隔的 base64 JSON 帧。绑定参数与 resolve 值使用 worker 运行时的迭代式无损 JSON wire 形状；绑定函数在宿主执行，类型化的 reject 类则在远程 worker 内物化。worker 会在模型代码运行前捕获其适配器边界调用的 JavaScript intrinsic，从而增强绑定传输、输出记账与完成值验证对这些引用修改的抵御能力。宿主会再次执行消息验证、调用 id 去重和无损 JSON 检查，并用外层输出账本再次计量。
 
diff --git a/packages/e2b/code-runtime-e2b/src/runner-source.ts b/packages/e2b/code-runtime-e2b/src/runner-source.ts
index b0355f20ce..e5cf6ebefa 100644
--- a/packages/e2b/code-runtime-e2b/src/runner-source.ts
+++ b/packages/e2b/code-runtime-e2b/src/runner-source.ts
@@ -2,9 +2,11 @@
 
 /** Node program that runs one model program in a fresh remote worker thread. */
 export const CODE_RUNNER_SOURCE = String.raw`import { Buffer } from 'node:buffer'
+import { fork } from 'node:child_process'
 import { inspect } from 'node:util'
 import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
 import { createInterface } from 'node:readline'
+import { fileURLToPath } from 'node:url'
 
 const emitFrame = message => {
   process.stdout.write(Buffer.from(JSON.stringify(message)).toString('base64') + '\n')
@@ -12,23 +14,140 @@ const emitFrame = message => {
 
 const parseFrame = line => JSON.parse(Buffer.from(line, 'base64').toString('utf8'))
 
-if (isMainThread) {
+const waitForPipeDrain = stream => {
+  if (stream.readableEnded || stream.destroyed) return Promise.resolve()
+  return new Promise(resolve => {
+    const done = () => {
+      stream.off('end', done)
+      stream.off('close', done)
+      stream.off('error', done)
+      resolve()
+    }
+    stream.once('end', done)
+    stream.once('close', done)
+    stream.once('error', done)
+    if (stream.readableEnded || stream.destroyed) done()
+  })
+}
+
+const waitForChildExit = child => {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
+  return new Promise(resolve => { child.once('exit', resolve) })
+}
+
+const jsonStringBytes = text => Buffer.byteLength(JSON.stringify(text))
+
+const truncateLog = (text, available) => {
+  if (available < 2) return ''
+  let result = ''
+  let bytes = 2
+  for (const character of text) {
+    const cost = jsonStringBytes(character) - 2
+    if (bytes + cost > available) break
+    bytes += cost
+    result += character
+  }
+  return result
+}
+
+const runLauncher = () => {
   const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
-  let worker
-  let finished = false
-  let computeTimer
+  let controller
+  let maxOutputBytes = 0
+  let logBytes = 2
+  let logEntries = 0
+  let settling = false
+  let closed = false
+  let terminal
+
   const finish = message => {
-    if (finished) return
-    finished = true
-    clearInterval(computeTimer)
-    emitFrame(message)
-    const current = worker
-    worker = undefined
-    Promise.resolve(current ? current.terminate() : undefined).finally(() => {
+    if (settling) {
+      if (message.type === 'output-limit') terminal = message
+      return
+    }
+    settling = true
+    terminal = message
+    const current = controller
+    controller = undefined
+    const drain = current
+      ? new Promise(resolve => { setImmediate(resolve) }).then(async () => {
+          const stdoutDrained = waitForPipeDrain(current.stdout)
+          const stderrDrained = waitForPipeDrain(current.stderr)
+          const exited = waitForChildExit(current)
+          current.kill('SIGKILL')
+          await Promise.all([exited, stdoutDrained, stderrDrained])
+        })
+      : Promise.resolve()
+    void drain.catch(error => {
+      process.stderr.write('code-runtime-e2b controller cleanup error: ' + String(error) + '\n')
+    }).then(() => {
+      closed = true
+      emitFrame(terminal)
       input.close()
       process.stdin.destroy()
     })
   }
+
+  const forwardLog = text => {
+    if (closed || terminal?.type === 'output-limit') return
+    const separator = logEntries > 0 ? 1 : 0
+    const available = maxOutputBytes - logBytes - separator
+    const cost = jsonStringBytes(text)
+    if (cost > available) {
+      const prefix = truncateLog(text, available)
+      if (prefix) {
+        logBytes += jsonStringBytes(prefix) + separator
+        logEntries += 1
+        emitFrame({ type: 'log', text: prefix })
+      }
+      finish({ type: 'output-limit' })
+      return
+    }
+    logBytes += cost + separator
+    logEntries += 1
+    emitFrame({ type: 'log', text })
+  }
+
+  const startController = message => {
+    maxOutputBytes = message.maxOutputBytes
+    controller = fork(fileURLToPath(import.meta.url), [], {
+      env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
+      execArgv: [],
+      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+    })
+    const current = controller
+    current.stdout.on('data', data => { forwardLog(data.toString('utf8')) })
+    current.stderr.on('data', data => { forwardLog(data.toString('utf8')) })
+    current.on('message', raw => {
+      if (!raw || typeof raw !== 'object') return
+      if (raw.type === 'log' && typeof raw.text === 'string') {
+        forwardLog(raw.text)
+        return
+      }
+      if (settling) return
+      if (raw.type === 'call' && typeof raw.id === 'number' && typeof raw.global === 'string' && typeof raw.name === 'string' && Array.isArray(raw.args)) {
+        emitFrame({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
+      } else if (raw.type === 'output-limit') {
+        finish({ type: 'output-limit' })
+      } else if (raw.type === 'done') {
+        if (raw.error && typeof raw.error === 'object' && typeof raw.error.kind === 'string' && typeof raw.error.message === 'string') {
+          finish({ type: 'done', error: { kind: raw.error.kind, message: raw.error.message } })
+        } else if (raw.value === undefined || Array.isArray(raw.value)) {
+          finish({ type: 'done', ...(raw.value === undefined ? {} : { value: raw.value }) })
+        }
+      }
+    })
+    current.on('error', error => {
+      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller error: ' + error.message } })
+    })
+    current.on('exit', code => {
+      if (!settling) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller exited with code ' + code + ' before completing' } })
+    })
+    current.send(message, error => {
+      if (error) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller boot failed: ' + error.message } })
+    })
+  }
+
   input.on('line', line => {
     let message
     try {
@@ -38,26 +157,77 @@ if (isMainThread) {
       finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received a malformed frame' } })
       return
     }
+    if (!controller) {
+      if (!message || message.type !== 'boot' || typeof message.code !== 'string' || !Array.isArray(message.namespaces) || !Number.isSafeInteger(message.maxOutputBytes) || message.maxOutputBytes < 4) {
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
+        return
+      }
+      startController(message)
+      return
+    }
+    if (message && message.type === 'reply' && typeof message.id === 'number' && typeof message.ok === 'boolean') {
+      controller.send(message.ok
+        ? { type: 'reply', id: message.id, ok: true, value: message.value }
+        : { type: 'reply', id: message.id, ok: false, message: String(message.message) }, error => {
+          if (error) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller reply failed: ' + error.message } })
+        })
+    }
+  })
+  input.on('close', () => { if (controller && !settling) controller.kill('SIGKILL') })
+}
+
+const runController = () => {
+  let worker
+  let finished = false
+  let computeTimer
+  const send = message => {
+    if (process.send) process.send(message)
+  }
+  const finish = message => {
+    if (finished) return
+    finished = true
+    clearInterval(computeTimer)
+    const current = worker
+    worker = undefined
+    const drain = current
+      ? new Promise(resolve => { setImmediate(resolve) }).then(async () => {
+          const stdoutDrained = waitForPipeDrain(current.stdout)
+          const stderrDrained = waitForPipeDrain(current.stderr)
+          await Promise.all([current.terminate(), stdoutDrained, stderrDrained])
+        })
+      : Promise.resolve()
+    void drain.catch(error => {
+      send({ type: 'log', text: 'code-runtime-e2b worker cleanup error: ' + String(error) + '\n' })
+    }).then(() => {
+      if (!process.send) {
+        process.exitCode = 1
+        return
+      }
+      process.send(message, () => { if (process.connected) process.disconnect() })
+    })
+  }
+  process.on('message', message => {
     if (!worker) {
       if (!message || message.type !== 'boot' || typeof message.code !== 'string' || !Array.isArray(message.namespaces)) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
+        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller received an invalid boot frame' } })
         return
       }
       worker = new Worker(new URL(import.meta.url), {
         workerData: message,
         env: {},
+        execArgv: [],
         stdout: true,
         stderr: true,
         resourceLimits: { maxOldGenerationSizeMb: message.maxOldGenerationSizeMb },
       })
-      worker.stdout.on('data', data => { emitFrame({ type: 'log', text: data.toString('utf8') }) })
-      worker.stderr.on('data', data => { emitFrame({ type: 'log', text: data.toString('utf8') }) })
+      worker.stdout.on('data', data => { send({ type: 'log', text: data.toString('utf8') }) })
+      worker.stderr.on('data', data => { send({ type: 'log', text: data.toString('utf8') }) })
       worker.on('message', raw => {
         if (!raw || typeof raw !== 'object') return
         if (raw.type === 'call' && typeof raw.id === 'number' && typeof raw.global === 'string' && typeof raw.name === 'string' && Array.isArray(raw.args)) {
-          emitFrame({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
+          send({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
         } else if (raw.type === 'log' && typeof raw.text === 'string') {
-          emitFrame({ type: 'log', text: raw.text })
+          send({ type: 'log', text: raw.text })
         } else if (raw.type === 'output-limit') {
           finish({ type: 'output-limit' })
         } else if (raw.type === 'done') {
@@ -88,8 +258,10 @@ if (isMainThread) {
         : { type: 'reply', id: message.id, ok: false, message: String(message.message) })
     }
   })
-  input.on('close', () => { if (worker && !finished) void worker.terminate() })
-} else {
+  process.on('disconnect', () => { if (worker && !finished) void worker.terminate() })
+}
+
+if (!isMainThread) {
   const port = parentPort
   if (!port) throw new Error('remote worker requires parentPort')
 
@@ -456,5 +628,9 @@ if (isMainThread) {
     process.stdout.write = originalStdout
     process.stderr.write = originalStderr
   }
+} else if (process.env.DSH_CODE_RUNTIME_CONTROLLER === '1') {
+  runController()
+} else {
+  runLauncher()
 }
 `
diff --git a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
index 9824fb2cf0..9743c361c5 100644
--- a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
+++ b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
@@ -1,3 +1,7 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { PassThrough, Writable } from 'node:stream'
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
@@ -153,7 +157,120 @@ function request(program = 'return 1') {
   return { program, bindings: [] }
 }
 
+async function runInstalledRunner(
+  code: string,
+  maxOutputBytes = 2_000_000,
+): Promise<{ messages: unknown[]; stderr: string }> {
+  const directory = await mkdtemp(join(tmpdir(), 'dsh-e2b-code-runner-'))
+  const runner = join(directory, 'runner.mjs')
+  await writeFile(runner, CODE_RUNNER_SOURCE)
+  const child = spawn(process.execPath, [runner], { stdio: ['pipe', 'pipe', 'pipe'] })
+  const decoder = new E2BFrameDecoder(4_000_000)
+  const messages: unknown[] = []
+  let stderr = ''
+  let outputError: unknown
+  child.stdout.setEncoding('ascii')
+  child.stdout.on('data', (chunk: string) => {
+    try {
+      messages.push(...decoder.push(chunk))
+    } catch (error: unknown) {
+      outputError = error
+      child.kill('SIGKILL')
+    }
+  })
+  child.stderr.setEncoding('utf8')
+  child.stderr.on('data', (chunk: string) => { stderr += chunk })
+
+  try {
+    child.stdin.write(encodeE2BFrame({
+      type: 'boot',
+      code,
+      namespaces: [],
+      computeMs: 1_000,
+      maxOutputBytes,
+      maxOldGenerationSizeMb: 128,
+    }))
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        child.kill('SIGKILL')
+        reject(new Error('installed E2B code runner did not exit'))
+      }, 5_000)
+      child.once('error', (error) => {
+        clearTimeout(timeout)
+        reject(error)
+      })
+      child.once('exit', () => {
+        clearTimeout(timeout)
+        resolve()
+      })
+    })
+    if (outputError !== undefined) throw outputError
+    decoder.finish()
+    return { messages, stderr }
+  } finally {
+    child.kill('SIGKILL')
+    await rm(directory, { recursive: true, force: true })
+  }
+}
+
 describe('E2BCodeRuntime', () => {
+  it('keeps model-owned descriptors outside the host framing process', async () => {
+    const forged = Buffer.from(JSON.stringify({ type: 'done' })).toString('base64') + '\\n'
+    const { messages, stderr } = await runInstalledRunner(
+      `
+        const fs = await import('node:fs')
+        const childProcess = await import('node:child_process')
+        fs.writeSync(1, ${JSON.stringify(forged)})
+        childProcess.spawnSync(process.execPath, ['-e', 'process.stdout.write("child-native")'], { stdio: 'inherit' })
+        return true
+      `,
+    )
+    const records = messages as Array<{ type?: string; text?: string; value?: unknown }>
+    const terminal = records.filter(message => message.type === 'done')
+
+    expect(stderr).toBe('')
+    expect(terminal).toEqual([{ type: 'done', value: [true] }])
+    expect(records.at(-1)).toEqual(terminal[0])
+    expect(records.filter(message => message.type === 'log').map(message => message.text).join(''))
+      .toContain(forged + 'child-native')
+  })
+
+  it('bounds native descriptor output before it reaches the host protocol', async () => {
+    const { messages, stderr } = await runInstalledRunner(
+      "(await import('node:fs')).writeSync(1, 'x'.repeat(4096)); return true",
+      64,
+    )
+    const records = messages as Array<{ type?: string; text?: string }>
+
+    expect(stderr).toBe('')
+    expect(records.at(-1)).toEqual({ type: 'output-limit' })
+    expect(Buffer.byteLength(records.filter(message => message.type === 'log').map(message => message.text).join('')))
+      .toBeLessThanOrEqual(62)
+  })
+
+  it('drains native worker pipes before emitting the terminal frame', async () => {
+    const expectedBytes = 1_048_576
+    const { messages, stderr } = await runInstalledRunner(
+      `
+        let stdoutPrototype = Object.getPrototypeOf(process.stdout)
+        while (stdoutPrototype && !Object.hasOwn(stdoutPrototype, 'write')) stdoutPrototype = Object.getPrototypeOf(stdoutPrototype)
+        Reflect.apply(stdoutPrototype.write, process.stdout, ['x'.repeat(${expectedBytes})])
+        return true
+      `,
+    )
+    const records = messages as Array<{ type?: string; text?: string }>
+    const terminalIndex = records.findIndex(message => message.type === 'done')
+    const nativeOutput = records
+      .slice(0, terminalIndex)
+      .filter(message => message.type === 'log')
+      .map(message => message.text ?? '')
+      .join('')
+
+    expect(stderr).toBe('')
+    expect(terminalIndex).toBe(records.length - 1)
+    expect(Buffer.byteLength(nativeOutput)).toBe(expectedBytes)
+  })
+
   it('prepares the remote runner and returns logs and a lossless completion', async () => {
     const handle = new FakeHandle((message, current) => {
       if ((message as { type?: string }).type !== 'boot') return
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 5c9bd56fc9..4f4ea19eb9 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -1,9 +1,15 @@
 import { access } from 'node:fs/promises'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
+import { AgentMessageId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+import { E2BPtyBackend } from '@deepseek-ai/dsh-pty-e2b'
+import { PtySessionId } from '@deepseek-ai/dsh-pty'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
 
 const fixtureRoot = fileURLToPath(new URL('../../../../examples/headless-agent/tests/fixtures/e2b/e2b/', import.meta.url))
 const binScript = join(fixtureRoot, 'bin.ts')
@@ -11,6 +17,53 @@ const configPath = join(fixtureRoot, 'cordis.yml')
 const tsconfigPath = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 
 describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
+  it('scrubs sandbox-default credentials from an actual E2B PTY', async () => {
+    const apiKey = process.env.E2B_API_KEY
+    if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared before the PTY environment test')
+    const sandbox = await Sandbox.create({
+      apiKey,
+      envs: { NPM_TOKEN: 'sentinel-secret', DSH_STALE: 'sentinel-stale', KEEP: 'visible' },
+      timeoutMs: 60_000,
+      secure: true,
+      lifecycle: { onTimeout: 'kill' },
+    })
+    try {
+      const ctx = new Context()
+      ctx.provide('e2b', { cwd: '/home/user', getSandbox: async () => sandbox } as never)
+      const ownerId = SessionId('e2b-pty-env-owner')
+      const owner: Agent = {
+        id: ownerId,
+        options: {},
+        session: new Session(ownerId),
+        status: 'idle',
+        acceptsNextStep: false,
+        ctx,
+        followup: () => AgentMessageId('unused'),
+        steer: () => AgentMessageId('unused'),
+        inject: () => AgentMessageId('unused'),
+        send: () => AgentMessageId('unused'),
+        cancel() {},
+        whenIdle: () => Promise.resolve(),
+      }
+      const backend = new E2BPtyBackend(ctx, {
+        backendType: 'shell', rows: 24, cols: 80,
+        scrollbackLines: 100, scrollbackMaxBytes: 65_536, maxReadBytes: 16_384,
+        pollIntervalMs: 25, idleSilenceMs: 1_000, timeoutMs: 5_000, disposeGraceMs: 1_000,
+      })
+      const session = await backend.spawn({ sessionId: PtySessionId('env'), owner, type: 'shell' })
+      const result = await session.startSend({
+        text: "printf 'NPM=<%s> DSH=<%s> KEEP=<%s>\\n' \"$NPM_TOKEN\" \"$DSH_STALE\" \"$KEEP\"",
+        submit: true,
+      }).done
+      expect(result.viewport).toContain('NPM=<> DSH=<> KEEP=<visible>')
+      expect(result.viewport).not.toContain('sentinel-secret')
+      expect(result.viewport).not.toContain('sentinel-stale')
+      await session.close('environment test complete')
+    } finally {
+      await sandbox.kill().catch(() => false)
+    }
+  }, 70_000)
+
   it('runs FS, Bash, PTY, LSP, and Code Runtime in one sandbox and deletes it', async () => {
     const { stdout, stderr } = await runLoaderSmoke({
       label: 'E2B composition',
@@ -22,7 +75,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       env: {
         NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
       },
-      processTimeoutMs: 120_000,
+      processTimeoutMs: 180_000,
       inspect: async (cwd) => {
         for (const name of ['from-fs.txt', 'from-bash.txt', 'multibyte # file.ts', 'fixture-lsp.mjs']) {
           await expect(access(join(cwd, name))).rejects.toMatchObject({ code: 'ENOENT' })
@@ -36,6 +89,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       bashRead: 'written-by-fs\n',
       fsRead: 'written-by-bash\n',
       explicitEnvironment: true,
+      publicationRollback: true,
       spill: {
         liveBytes: 6,
         outcome: { exitCode: null, signal: 'SIGTERM' },
@@ -49,12 +103,18 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         kind: 'locations',
         locations: [{ range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } } }],
       },
+      lspContainment: true,
+      lspDocumentBound: true,
       terminal: {
         echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
         signal: { delivered: true },
         interrupted: { sessionStatus: { kind: 'running' } },
+        treeCleanup: true,
       },
       hostileOutput: { error: { kind: 'output-limit' } },
+      nativeOutput: { error: { kind: 'output-limit' } },
+      descriptorOutput: { error: { kind: 'output-limit' } },
+      inheritedOutput: { error: { kind: 'output-limit' } },
       timedOut: { error: { kind: 'timeout' } },
       aborted: { error: { kind: 'abort', message: 'live abort' } },
       oversizedBoot: { error: { kind: 'worker-exit' } },
@@ -75,5 +135,5 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
     await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
-  }, 135_000)
+  }, 195_000)
 })
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index b416105166..95a3a9eea6 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: d8f3915fa281e8b9c062e3412c92bc6358616284
-README.zh.md: 93d27bcdd514ccbf87e07d0eff5958edf3c726c1
+README.md: a505703fc764f8441fa54d2b1d922762eb3fafdf
+README.zh.md: 626fdb52979d29f12d1bc1b67b0ea13730003af7
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index d8f3915fa2..a505703fc7 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -8,7 +8,7 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 
 - **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; `realpath -m` supplies canonical target identity without requiring the final file to exist. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
-- **Atomic mutations** — writes upload a mode-`0600` temporary sibling, preserve an existing file's POSIX mode, and publish through same-directory Linux `mv -f`. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
+- **Atomic mutations** — writes upload a mode-`0600` temporary sibling, preserve an existing file's POSIX mode, and publish through E2B's same-directory atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at SDK request boundaries; a successful rename is the commit point.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 93d27bcdd5..626fdb5297 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -8,7 +8,7 @@
 
 - **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；`realpath -m` 提供规范化目标身份，且不要求最终文件存在。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
-- **原子变更**：写入会上传 mode 为 `0600` 的同级临时文件，保留现有文件的 POSIX mode，并通过同目录 Linux `mv -f` 发布。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
+- **原子变更**：写入会上传 mode 为 `0600` 的同级临时文件，保留现有文件的 POSIX mode，并通过 E2B 的同目录原子重命名发布。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 4f733f1fba..2a7fd1275f 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -412,11 +412,7 @@ export class E2BFileSystem extends FileSystem {
         signalOpts(signal),
       )
       assertNotAborted(signal, 'write')
-      await sandbox.commands.run(
-        `mv -f -- ${quoteE2BShellArg(temporary)} ${quoteE2BShellArg(targetPath)}`,
-        signalOpts(signal),
-      )
-      const committed = await sandbox.files.getInfo(targetPath)
+      const committed = await sandbox.files.rename(temporary, targetPath, signalOpts(signal))
       return entryVersion(committed)
     } catch (error: unknown) {
       try {
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 177bb9e59c..13d94e70c7 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -453,6 +453,17 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(controller.signal.aborted).toBe(true)
   })
 
+  it('returns committed rename metadata without a fallible post-commit lookup', async () => {
+    const remote = new FakeRemote()
+    const getInfo = vi.spyOn(remote.sandbox.files, 'getInfo')
+    const { fs } = await setup(remote)
+
+    await expect(fs.writeText(await fs.resolve('committed'), 'yes'))
+      .resolves.toMatchObject({ operation: 'create' })
+    expect(getInfo).toHaveBeenCalledTimes(1)
+    expect(remote.renames).toHaveLength(1)
+  })
+
   it('cleans staging files and maps command, permission, and abort failures', async () => {
     const remote = new FakeRemote()
     const { fs } = await setup(remote)
diff --git a/packages/e2b/lsp-e2b/README.i18n.yaml b/packages/e2b/lsp-e2b/README.i18n.yaml
index 5f126d7e56..066820d9fd 100644
--- a/packages/e2b/lsp-e2b/README.i18n.yaml
+++ b/packages/e2b/lsp-e2b/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/e2b/lsp-e2b/README.md
-README.md: ded928ec073e6c0943d574d86359eeec586bb862
-README.zh.md: 91eb7cecb49adcf73f4be948e9a5da400981e6f1
+README.md: 6cc118767adc5d2df855b009f48faab596928fb7
+README.zh.md: b384e9efd0e5c62b0ee6e69f73755e1bbe0192df
diff --git a/packages/e2b/lsp-e2b/README.md b/packages/e2b/lsp-e2b/README.md
index ded928ec07..6cc118767a 100644
--- a/packages/e2b/lsp-e2b/README.md
+++ b/packages/e2b/lsp-e2b/README.md
@@ -27,7 +27,7 @@ Provider ids and commands are non-empty; numeric bounds are positive safe intege
 
 E2B command callbacks are text, while LSP is byte-framed. The installed proxy therefore base64-frames raw server stdout, stderr, and stdin as newline-delimited ASCII JSON; the host validates and decodes every frame before handing bytes to the shared `LspInstance` protocol engine. `initialize.processId` is `null` because host and server do not share a process namespace.
 
-One language-server process is pooled per provider and canonical remote workspace. Queries serialize per workspace but different workspaces run concurrently. Each query canonicalizes the remote workspace and source with `realpath`, rejects paths outside that workspace, requires a regular file, enforces the size bound before and after reading, decodes strict UTF-8, and uses the ordinary transient `didOpen` / request / `didClose` lifecycle. A transport failure disposes the instance and retries the read-only query once on a fresh remote process.
+One language-server process is pooled per provider and canonical remote workspace. Queries serialize per workspace but different workspaces run concurrently. Each query canonicalizes the remote workspace and source with `realpath`, rejects paths outside that workspace, then uses a remote helper to open the canonical source without following the final symlink and to verify and read one stable descriptor. The helper requires a regular file and reads at most `maxDocumentBytes + 1` bytes before strict UTF-8 decoding. Queries use the ordinary transient `didOpen` / request / `didClose` lifecycle. A transport failure disposes the instance and retries the read-only query once on a fresh remote process.
 
 The subprocess adapter owns process groups and escalation, so cancellation and disposal await remote server quiescence. The host owns LSP request ids, pending requests, provider queues, and normalized results.
 
diff --git a/packages/e2b/lsp-e2b/README.zh.md b/packages/e2b/lsp-e2b/README.zh.md
index 91eb7cecb4..b384e9efd0 100644
--- a/packages/e2b/lsp-e2b/README.zh.md
+++ b/packages/e2b/lsp-e2b/README.zh.md
@@ -27,7 +27,7 @@
 
 E2B 命令回调交付的是文本，而 LSP 按字节分帧。因此，已安装的代理会把服务器 stdout、stderr 和 stdin 的原始字节进行 base64 编码，封装为以换行分隔的 ASCII JSON 帧；宿主会验证并解码每一帧，再把字节交给共享的 `LspInstance` 协议引擎。`initialize.processId` 为 `null`，因为宿主与服务器不共享进程命名空间。
 
-每个提供方与规范化远程工作区的组合共享一个池化语言服务器进程。同一工作区的查询串行执行，不同工作区的查询并发运行。每项查询都会使用 `realpath` 规范化远程工作区与源文件，拒绝工作区外的路径，要求源文件为普通文件，在读取前后都检查大小上限，使用严格的 UTF-8 解码，并采用常规的临时 `didOpen`／请求／`didClose` 生命周期。传输失败会 dispose（资源释放）该实例，并在全新的远程进程上重试一次只读查询。
+每个提供方与规范化远程工作区的组合共享一个池化语言服务器进程。同一工作区的查询串行执行，不同工作区的查询并发运行。每项查询都会使用 `realpath` 规范化远程工作区与源文件，拒绝工作区外的路径，再由远程 helper 以不跟随最终符号链接的方式打开规范化源文件，并在同一个稳定描述符上完成验证与读取。该 helper 要求目标为普通文件，最多读取 `maxDocumentBytes + 1` 字节，随后执行严格的 UTF-8 解码。查询采用常规的临时 `didOpen`／请求／`didClose` 生命周期。传输失败会 dispose（资源释放）该实例，并在全新的远程进程上重试一次只读查询。
 
 进程管理适配器负责进程组和终止升级，因此取消与资源释放都会等待远程服务器完全停稳。宿主负责 LSP 请求 id、待完成请求、提供方队列和规范化结果。
 
diff --git a/packages/e2b/lsp-e2b/src/index.ts b/packages/e2b/lsp-e2b/src/index.ts
index b378ebfc9a..fa6b3729da 100644
--- a/packages/e2b/lsp-e2b/src/index.ts
+++ b/packages/e2b/lsp-e2b/src/index.ts
@@ -92,6 +92,46 @@ interface RemoteSource {
   text: string
 }
 
+interface RemoteSourceReadResponse {
+  kind: 'ok' | 'not-file' | 'oversize' | 'grew' | 'open-error'
+  data?: string
+  size?: number
+  message?: string
+}
+
+const SOURCE_READER_SOURCE = String.raw`
+/* dsh-e2b-source-reader */
+const fs = require('node:fs')
+const path = process.argv[1]
+const maxBytes = Number(process.argv[2])
+let descriptor
+let response
+try {
+  descriptor = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK)
+  const info = fs.fstatSync(descriptor)
+  if (!info.isFile()) response = { kind: 'not-file' }
+  else if (info.size > maxBytes) response = { kind: 'oversize', size: info.size }
+  else {
+    const chunks = []
+    let total = 0
+    while (total <= maxBytes) {
+      const chunk = Buffer.allocUnsafe(Math.min(65536, maxBytes - total + 1))
+      const bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)
+      if (bytesRead === 0) break
+      chunks.push(chunk.subarray(0, bytesRead))
+      total += bytesRead
+    }
+    response = total > maxBytes
+      ? { kind: 'grew' }
+      : { kind: 'ok', data: Buffer.concat(chunks, total).toString('base64') }
+  }
+} catch (error) {
+  response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
+}
+if (descriptor !== undefined) fs.closeSync(descriptor)
+process.stdout.write(JSON.stringify(response))
+`
+
 function abortReason(signal: AbortSignal): unknown {
   try {
     signal.throwIfAborted()
@@ -164,7 +204,8 @@ export async function canonicalizeE2BWorkspace(
  * @param sandbox - Shared sandbox that owns the source.
  * @param filePath - Absolute path or path relative to the canonical workspace.
  * @param workspace - Canonical remote workspace directory.
- * @param maxDocumentBytes - Maximum source size before and after reading.
+ * @param maxDocumentBytes - Maximum bytes read through the stable remote handle.
+ * @param nodeExecutable - Resolved remote Node executable used by the bounded reader.
  * @param signal - Optional query cancellation signal.
  * @returns The canonical source path and decoded text.
  */
@@ -173,6 +214,7 @@ export async function readE2BSource(
   filePath: string,
   workspace: string,
   maxDocumentBytes: number,
+  nodeExecutable: string,
   signal?: AbortSignal,
 ): Promise<RemoteSource> {
   const requested = posix.isAbsolute(filePath) ? filePath : posix.resolve(workspace, filePath)
@@ -181,16 +223,39 @@ export async function readE2BSource(
   if (relative === '..' || relative.startsWith('../') || posix.isAbsolute(relative)) {
     throw new Error(`source ${JSON.stringify(filePath)} resolves outside the workspace`)
   }
-  const info = await sandbox.files.getInfo(canonicalPath, signal === undefined ? {} : { signal })
-  if (info.type !== FileType.FILE) throw new Error(`source ${JSON.stringify(filePath)} is not a regular file`)
-  if (info.size > maxDocumentBytes) {
-    throw new Error(`source ${JSON.stringify(filePath)} is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`)
-  }
-  const bytes = await sandbox.files.read(canonicalPath, { format: 'bytes', ...signal === undefined ? {} : { signal } })
+  const command = [
+    quoteE2BShellArg(nodeExecutable),
+    '--input-type=commonjs',
+    '-e',
+    quoteE2BShellArg(SOURCE_READER_SOURCE),
+    quoteE2BShellArg(canonicalPath),
+    String(maxDocumentBytes),
+  ].join(' ')
+  const result = await sandbox.commands.run(command, signal === undefined ? {} : { signal })
   signal?.throwIfAborted()
-  if (bytes.length > maxDocumentBytes) {
+  let response: RemoteSourceReadResponse
+  try {
+    response = JSON.parse(result.stdout) as RemoteSourceReadResponse
+  } catch (error: unknown) {
+    throw new Error(`source ${JSON.stringify(filePath)} reader returned an invalid response`, { cause: error })
+  }
+  if (response.kind === 'not-file') throw new Error(`source ${JSON.stringify(filePath)} is not a regular file`)
+  if (response.kind === 'oversize' && Number.isSafeInteger(response.size)) {
+    throw new Error(`source ${JSON.stringify(filePath)} is ${response.size} bytes, over the ${maxDocumentBytes}-byte limit`)
+  }
+  if (response.kind === 'grew') {
     throw new Error(`source ${JSON.stringify(filePath)} grew past the ${maxDocumentBytes}-byte limit while reading`)
   }
+  if (response.kind === 'open-error' && typeof response.message === 'string') {
+    throw new Error(`source ${JSON.stringify(filePath)} could not be opened safely: ${response.message}`)
+  }
+  if (response.kind !== 'ok' || typeof response.data !== 'string') {
+    throw new Error(`source ${JSON.stringify(filePath)} reader returned an invalid response`)
+  }
+  const bytes = Buffer.from(response.data, 'base64')
+  if (bytes.toString('base64') !== response.data || bytes.length > maxDocumentBytes) {
+    throw new Error(`source ${JSON.stringify(filePath)} reader returned invalid bounded bytes`)
+  }
   let text: string
   try {
     text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
@@ -239,7 +304,14 @@ export class E2BLspProvider implements LspProvider {
     this.assertActive(signal)
     return this.enqueue(workspace, signal, async () => {
       this.assertActive(signal)
-      const source = await readE2BSource(this.sandbox, request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      const source = await readE2BSource(
+        this.sandbox,
+        request.filePath,
+        workspace,
+        this.config.maxDocumentBytes,
+        this.nodeExecutable,
+        signal,
+      )
       this.assertActive(signal)
       let instance = this.instanceFor(workspace)
       try {
diff --git a/packages/e2b/lsp-e2b/tests/provider.spec.ts b/packages/e2b/lsp-e2b/tests/provider.spec.ts
index d746abe7f7..dc92053e4a 100644
--- a/packages/e2b/lsp-e2b/tests/provider.spec.ts
+++ b/packages/e2b/lsp-e2b/tests/provider.spec.ts
@@ -94,11 +94,14 @@ class FakeRemote {
   readonly contents = new Map<string, Uint8Array>()
   readonly realpaths = new Map<string, string>()
   forcedRealpath: string | undefined
+  readerResponse: unknown
+  readerOutput: string | undefined
 
   constructor() {
     this.infos.set('/workspace', { type: FileType.DIR, size: 0 })
     this.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 12 })
     this.contents.set('/workspace/file.ts', Buffer.from('const x = 1'))
+    this.readerResponse = { kind: 'ok', data: Buffer.from('const x = 1').toString('base64') }
   }
 
   readonly sandbox = {
@@ -110,6 +113,9 @@ class FakeRemote {
           const requested = match?.[1] ?? ''
           return { exitCode: 0, stdout: `${this.forcedRealpath ?? this.realpaths.get(requested) ?? requested}\n`, stderr: '' }
         }
+        if (command.includes('dsh-e2b-source-reader')) {
+          return { exitCode: 0, stdout: this.readerOutput ?? JSON.stringify(this.readerResponse), stderr: '' }
+        }
         if (command.startsWith('command -v')) return { exitCode: 0, stdout: '/usr/bin/node\n', stderr: '' }
         return { exitCode: 0, stdout: '', stderr: '' }
       },
@@ -172,16 +178,16 @@ describe('E2B LSP filesystem boundary', () => {
   it('canonicalizes a directory and reads a contained UTF-8 source', async () => {
     const remote = new FakeRemote()
     await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace')).resolves.toBe('/workspace')
-    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024)).resolves.toEqual({
+    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, '/usr/bin/node')).resolves.toEqual({
       canonicalPath: '/workspace/file.ts',
       text: 'const x = 1',
     })
-    await expect(readE2BSource(remote.sandbox, '/workspace/file.ts', '/workspace', 1_024)).resolves.toMatchObject({
+    await expect(readE2BSource(remote.sandbox, '/workspace/file.ts', '/workspace', 1_024, '/usr/bin/node')).resolves.toMatchObject({
       canonicalPath: '/workspace/file.ts',
     })
     const signal = new AbortController().signal
     await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace', signal)).resolves.toBe('/workspace')
-    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, signal)).resolves.toMatchObject({
+    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, '/usr/bin/node', signal)).resolves.toMatchObject({
       canonicalPath: '/workspace/file.ts',
     })
   })
@@ -199,25 +205,35 @@ describe('E2B LSP filesystem boundary', () => {
 
     const outside = new FakeRemote()
     outside.realpaths.set('/workspace/file.ts', '/outside/file.ts')
-    await expect(readE2BSource(outside.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('outside the workspace')
+    await expect(readE2BSource(outside.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('outside the workspace')
 
     const notFile = new FakeRemote()
-    notFile.infos.set('/workspace/file.ts', { type: FileType.DIR, size: 0 })
-    await expect(readE2BSource(notFile.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('not a regular file')
+    notFile.readerResponse = { kind: 'not-file' }
+    await expect(readE2BSource(notFile.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('not a regular file')
 
     const tooLarge = new FakeRemote()
-    tooLarge.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 21 })
-    await expect(readE2BSource(tooLarge.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('over the 20-byte limit')
+    tooLarge.readerResponse = { kind: 'oversize', size: 21 }
+    await expect(readE2BSource(tooLarge.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('over the 20-byte limit')
 
     const grew = new FakeRemote()
-    grew.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 1 })
-    grew.contents.set('/workspace/file.ts', Buffer.alloc(21))
-    await expect(readE2BSource(grew.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('grew past')
+    grew.readerResponse = { kind: 'grew' }
+    await expect(readE2BSource(grew.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('grew past')
 
     const invalid = new FakeRemote()
-    invalid.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 1 })
-    invalid.contents.set('/workspace/file.ts', Uint8Array.from([0xff]))
-    await expect(readE2BSource(invalid.sandbox, 'file.ts', '/workspace', 20)).rejects.toThrow('not valid UTF-8')
+    invalid.readerResponse = { kind: 'ok', data: Buffer.from([0xff]).toString('base64') }
+    await expect(readE2BSource(invalid.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('not valid UTF-8')
+
+    const swapped = new FakeRemote()
+    swapped.readerResponse = { kind: 'open-error', message: 'ELOOP: symbolic link encountered' }
+    await expect(readE2BSource(swapped.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('opened safely')
+
+    const malformedReader = new FakeRemote()
+    malformedReader.readerResponse = { kind: 'ok', data: '*' }
+    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid bounded bytes')
+    malformedReader.readerResponse = { kind: 'oversize', size: 'large' }
+    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid response')
+    malformedReader.readerOutput = '{'
+    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid response')
 
     await expect(canonicalizeE2BWorkspace(new FakeRemote().sandbox, '/workspace', AbortSignal.abort('stop')))
       .rejects.toBe('stop')
diff --git a/packages/e2b/pty-e2b/README.i18n.yaml b/packages/e2b/pty-e2b/README.i18n.yaml
index 1bd8485e8f..ddae4c21db 100644
--- a/packages/e2b/pty-e2b/README.i18n.yaml
+++ b/packages/e2b/pty-e2b/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/e2b/pty-e2b/README.md
-README.md: 3d363309f6bd1c4def5fbff668735958ca2de52d
-README.zh.md: 78d61cc654bf6eb46a3bec7124b3cc06cc7e34e9
+README.md: d6d8e05f13701b85cee9a9646bfdd82ac07769da
+README.zh.md: 265257c72e7bcbd2dfd805b343db5bab7173ab51
diff --git a/packages/e2b/pty-e2b/README.md b/packages/e2b/pty-e2b/README.md
index 3d363309f6..d6d8e05f13 100644
--- a/packages/e2b/pty-e2b/README.md
+++ b/packages/e2b/pty-e2b/README.md
@@ -20,13 +20,13 @@ The `pty-e2b` plugin injects `e2b` and `pty`, then registers one backend under `
 | `timeoutMs` | `30000` | Absolute startup and send wait bound. |
 | `disposeGraceMs` | `3000` | TERM-to-KILL cleanup grace. |
 
-Numeric values are positive safe integers, `backendType` is non-empty, and `maxReadBytes` cannot exceed `scrollbackMaxBytes`. A relative spawn cwd resolves against `ctx.e2b.cwd`; an absolute remote path remains absolute.
+Numeric values are positive safe integers, `backendType` is non-empty, and `maxReadBytes` cannot exceed `scrollbackMaxBytes`. A relative spawn cwd resolves against `ctx.e2b.cwd`; an absolute remote path remains absolute. Before launch, the backend enumerates sandbox-default environment names, blanks `DSH_*` and credential-shaped names, then overlays its controlled terminal values and explicit `spec.env` entries.
 
 ## Runtime contract
 
 The backend uses E2B's byte-oriented PTY callback with a streaming fatal UTF-8 decoder, then the backend-neutral line sanitizer and bounded buffers from `dsh-pty`. It installs a controlled Bash prompt marker and waits for printable prompt text; when that marker is unavailable, observed output plus the configured silence bound yields `inferred_idle`. Startup with no output reaches the absolute timeout and fails instead of publishing an empty session.
 
-Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; `SIGKILL` refuses to target the shell itself. Close sends `SIGTERM` to the PTY process group, waits, escalates through E2B's PTY kill, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
+Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; `SIGKILL` refuses to target the shell itself. The backend records the terminal's POSIX session id at startup. Close sends `SIGTERM` to every process group still in that session, escalates survivors to `SIGKILL`, verifies that the session is empty, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
 
 The remote PTY process and its child processes live in E2B. Prompt/readiness state, scrollback, operation handles, owner authority, and SDK event delivery remain in host memory.
 
@@ -51,4 +51,5 @@ No direct invalidation; the consumer owns prompts, schemas, and appended results
 - **Line-oriented terminal model** — CSI/OSC control sequences are removed; alternate-screen and full terminal emulation remain unsupported.
 - **Readiness is marker-or-silence based** — E2B exposes foreground process groups but not the local backend's Linux syscall inspection, so `inferred_idle` is deliberately possible.
 - **UTF-8 only** — invalid byte sequences fail the session instead of returning lossy text.
+- **Deliberate session escape is unmanaged** — a process that calls `setsid` leaves the terminal session and is outside this backend's cleanup identity.
 - **No reconnectable terminal handles** — retaining an E2B sandbox preserves remote files, not host ownership, buffers, callbacks, or live PTY sessions.
diff --git a/packages/e2b/pty-e2b/README.zh.md b/packages/e2b/pty-e2b/README.zh.md
index 78d61cc654..265257c72e 100644
--- a/packages/e2b/pty-e2b/README.zh.md
+++ b/packages/e2b/pty-e2b/README.zh.md
@@ -20,13 +20,13 @@
 | `timeoutMs` | `30000` | 启动与发送等待的绝对上限。 |
 | `disposeGraceMs` | `3000` | TERM 到 KILL 的清理宽限期。 |
 
-数值必须是正的安全整数，`backendType` 必须非空，且 `maxReadBytes` 不得超过 `scrollbackMaxBytes`。相对的 spawn cwd 以 `ctx.e2b.cwd` 为基准解析；绝对远程路径保持不变。
+数值必须是正的安全整数，`backendType` 必须非空，且 `maxReadBytes` 不得超过 `scrollbackMaxBytes`。相对的 spawn cwd 以 `ctx.e2b.cwd` 为基准解析；绝对远程路径保持不变。启动前，后端会枚举沙箱默认环境变量名，清空 `DSH_*` 和形似凭据的名称，再覆盖其受控终端值与显式 `spec.env` 条目。
 
 ## 运行时契约
 
 该后端为 E2B 面向字节的 PTY 回调配备流式、遇到无效序列即失败的 UTF-8 解码器，随后使用 `dsh-pty` 提供的后端无关行清理器与有界缓冲区。它会安装受控的 Bash 提示符标记，并等待可打印的提示符文本；若该标记不可用，系统会在已经观察到输出且达到已配置的静默上限时得出 `inferred_idle`。零输出的启动过程会达到绝对超时并失败，不会发布空会话。
 
-每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；发送 `SIGKILL` 时拒绝以 shell 本身为目标。关闭操作向 PTY 进程组发送 `SIGTERM`，等待后通过 E2B 的 PTY kill 操作升级，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
+每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；发送 `SIGKILL` 时拒绝以 shell 本身为目标。后端会在启动时记录终端的 POSIX 会话 id。关闭操作会向该会话内仍存在的每个进程组发送 `SIGTERM`，对存活者升级为 `SIGKILL`，验证会话已经清空，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
 
 远程 PTY 进程及其子进程位于 E2B。提示符／就绪状态、scrollback、操作句柄、所有者权限和 SDK 事件交付仍保留在宿主内存中。
 
@@ -51,4 +51,5 @@
 - **面向行的终端模型**：CSI／OSC 控制序列会被移除；备用屏幕与完整终端仿真仍不受支持。
 - **就绪判断基于标记或静默**：E2B 会公开前台进程组，但不提供本地后端使用的 Linux syscall 检查，因此系统有意保留返回 `inferred_idle` 的可能性。
 - **仅支持 UTF-8**：无效字节序列会使会话失败，而不是返回有损文本。
+- **主动逃离会话的进程不受管理**：调用 `setsid` 的进程会离开终端会话，因而不属于本后端的清理身份。
 - **没有可重连的终端句柄**：保留 E2B 沙箱会保留远程文件，但不会保留宿主所有权、缓冲区、回调或实时 PTY 会话。
diff --git a/packages/e2b/pty-e2b/src/index.ts b/packages/e2b/pty-e2b/src/index.ts
index 8fd7a519a0..d665a734b7 100644
--- a/packages/e2b/pty-e2b/src/index.ts
+++ b/packages/e2b/pty-e2b/src/index.ts
@@ -17,8 +17,22 @@ export const name = 'pty-e2b'
 /** Required shared sandbox owner and PTY registry. */
 export const inject = ['e2b', 'pty']
 
-function terminalEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
+const SENSITIVE_ENV_NAME = /KEY|SECRET|TOKEN/i
+
+async function terminalEnvironment(
+  sandbox: Sandbox,
+  spec: PtyBackendSpawnSpec,
+): Promise<Record<string, string>> {
+  const discovered = await sandbox.commands.run(
+    'env -0 | cut -z -d= -f1',
+    spec.signal === undefined ? {} : { signal: spec.signal },
+  )
+  spec.signal?.throwIfAborted()
+  const scrubbed = Object.fromEntries(discovered.stdout.split('\0')
+    .filter(name => name.startsWith('DSH_') || SENSITIVE_ENV_NAME.test(name))
+    .map(name => [name, '']))
   return {
+    ...scrubbed,
     TERM: 'dumb',
     PAGER: 'cat',
     GIT_PAGER: 'cat',
@@ -31,6 +45,20 @@ function terminalEnvironment(spec: PtyBackendSpawnSpec): Record<string, string>
   }
 }
 
+async function resolveTerminalSessionId(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<number> {
+  const result = await sandbox.commands.run(
+    `ps -o sid= -p ${pid}`,
+    signal === undefined ? {} : { signal },
+  )
+  signal?.throwIfAborted()
+  const raw = result.stdout.trim()
+  const sessionId = Number(raw)
+  if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(sessionId)) {
+    throw new Error(`pty-e2b: cannot resolve process session for E2B PTY ${pid}`)
+  }
+  return sessionId
+}
+
 /** E2B backend registered under the configured terminal type. */
 export class E2BPtyBackend implements PtyBackend {
   readonly type: string
@@ -57,7 +85,7 @@ export class E2BPtyBackend implements PtyBackend {
       rows: this.config.rows,
       cols: this.config.cols,
       cwd: posix.resolve(this.ctx.e2b.cwd, spec.cwd ?? this.ctx.e2b.cwd),
-      envs: terminalEnvironment(spec),
+      envs: await terminalEnvironment(sandbox, spec),
       timeoutMs: 0,
       ...spec.signal === undefined ? {} : { signal: spec.signal },
       onData: (data) => {
@@ -69,7 +97,15 @@ export class E2BPtyBackend implements PtyBackend {
       await handle.kill().catch(() => false)
       throw new Error(`pty-e2b: E2B returned invalid PTY pid ${handle.pid}`)
     }
-    const session = new E2BPtySession(sandbox, handle, this.config)
+    let terminalSessionId: number
+    try {
+      terminalSessionId = await resolveTerminalSessionId(sandbox, handle.pid, spec.signal)
+    } catch (error: unknown) {
+      await handle.kill().catch(() => false)
+      await Promise.allSettled([handle.wait()])
+      throw error
+    }
+    const session = new E2BPtySession(sandbox, handle, terminalSessionId, this.config)
     created.session = session
     try {
       const initializing = session.initialize(spec.signal)
diff --git a/packages/e2b/pty-e2b/src/session.ts b/packages/e2b/pty-e2b/src/session.ts
index e5dfc05efe..bf8780103d 100644
--- a/packages/e2b/pty-e2b/src/session.ts
+++ b/packages/e2b/pty-e2b/src/session.ts
@@ -105,6 +105,7 @@ export class E2BPtySession implements PtyBackendSession {
   constructor(
     private readonly sandbox: Sandbox,
     private readonly handle: CommandHandle,
+    private readonly terminalSessionId: number,
     private readonly config: ResolvedConfig,
   ) {
     this.pid = handle.pid
@@ -314,6 +315,40 @@ export class E2BPtySession implements PtyBackendSession {
     return pgid
   }
 
+  private async sessionProcessGroups(): Promise<number[]> {
+    const result = await this.sandbox.commands.run(
+      `ps -eo sid=,pgid= | awk '$1 == ${this.terminalSessionId} { print $2 }'`,
+    )
+    const groups = new Set<number>()
+    for (const raw of result.stdout.trim().split(/\s+/)) {
+      if (raw.length === 0) continue
+      const pgid = Number(raw)
+      if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(pgid) || pgid <= 1) {
+        throw new Error(`pty-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${this.terminalSessionId}`)
+      }
+      groups.add(pgid)
+    }
+    return [...groups]
+  }
+
+  private async signalProcessGroups(groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
+    try {
+      await this.sandbox.commands.run(`kill -${signal} -- ${groups.map(pgid => `-${pgid}`).join(' ')}`)
+    } catch (error: unknown) {
+      if (!(error instanceof CommandExitError)) throw error
+    }
+  }
+
+  private async awaitSessionEmpty(timeoutMs: number, signal?: 'KILL'): Promise<number[]> {
+    const deadline = Date.now() + timeoutMs
+    for (;;) {
+      const groups = await this.sessionProcessGroups()
+      if (groups.length === 0 || Date.now() >= deadline) return groups
+      if (signal !== undefined) await this.signalProcessGroups(groups, signal)
+      await delay(Math.min(this.config.pollIntervalMs, deadline - Date.now()))
+    }
+  }
+
   private onExit(exitCode: number): void {
     this.remoteExited = true
     let tail = ''
@@ -343,19 +378,20 @@ export class E2BPtySession implements PtyBackendSession {
   }
 
   private async closeOnce(reason: string): Promise<void> {
-    if (!this.remoteExited) {
+    let survivingGroups = await this.sessionProcessGroups()
+    if (survivingGroups.length > 0) {
       this.closeSignal = 'SIGTERM'
-      try {
-        await this.sandbox.commands.run(`kill -TERM -- -${this.pid}`)
-      } catch (error: unknown) {
-        if (!(error instanceof CommandExitError)) throw error
-      }
-      await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
+      await this.signalProcessGroups(survivingGroups, 'TERM')
+      survivingGroups = await this.awaitSessionEmpty(this.config.disposeGraceMs)
     }
-    if (!this.remoteExited) {
+    if (survivingGroups.length > 0 || !this.remoteExited) {
       this.closeSignal = 'SIGKILL'
-      await this.sandbox.pty.kill(this.pid)
-      await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
+      if (!this.remoteExited) await this.sandbox.pty.kill(this.pid)
+      survivingGroups = await this.awaitSessionEmpty(this.config.disposeGraceMs, 'KILL')
+      if (!this.remoteExited) await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
+    }
+    if (survivingGroups.length > 0) {
+      throw new Error(`E2B PTY cleanup failed (${reason}); surviving process groups: ${survivingGroups.join(', ')}`)
     }
     if (!this.remoteExited) {
       throw new Error(`E2B PTY cleanup failed (${reason}); surviving pid: ${this.pid}`)
diff --git a/packages/e2b/pty-e2b/tests/index.spec.ts b/packages/e2b/pty-e2b/tests/index.spec.ts
index e306d8b86b..476ddc38df 100644
--- a/packages/e2b/pty-e2b/tests/index.spec.ts
+++ b/packages/e2b/pty-e2b/tests/index.spec.ts
@@ -42,7 +42,10 @@ describe('E2BPtyBackend and plugin', () => {
   it('creates a remote PTY with isolated environment and initializes the session', async () => {
     vi.useFakeTimers()
     const ctx = new Context()
-    const sandbox = {} as Sandbox
+    const run = vi.fn(async (command: string) => command.startsWith('env -0')
+      ? { exitCode: 0, stdout: 'NPM_TOKEN\0DSH_STALE\0KEEP\0', stderr: '' }
+      : { exitCode: 0, stdout: '123\n', stderr: '' })
+    const sandbox = { commands: { run } } as unknown as Sandbox
     ctx.provide('e2b', {
       cwd: '/workspace',
       getSandbox: async () => sandbox,
@@ -65,9 +68,11 @@ describe('E2BPtyBackend and plugin', () => {
     expect(session.motd).toBe('banner\ndsh> ')
     expect(options).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace/project', timeoutMs: 0 })
     expect(options?.envs).toMatchObject({
+      NPM_TOKEN: '', DSH_STALE: '',
       TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ',
       DSH_SHELL: '1', DSH_SESSION_ID: 'owner', DSH_PTY_SESSION_ID: 'pty-1',
     })
+    expect(options?.envs).not.toHaveProperty('KEEP')
     vi.useRealTimers()
   })
 
@@ -79,7 +84,10 @@ describe('E2BPtyBackend and plugin', () => {
       setTimeout(() => { void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> ')) }, 0)
       return created
     })
-    const sandbox = { pty: { create } } as unknown as Sandbox
+    const sandbox = {
+      commands: { run: async (command: string) => ({ exitCode: 0, stdout: command.startsWith('env -0') ? '' : '123\n', stderr: '' }) },
+      pty: { create },
+    } as unknown as Sandbox
     ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as unknown as E2BSandboxService)
     const backend = new E2BPtyBackend(ctx, config())
     const pending = backend.spawn({ sessionId: PtySessionId('default'), owner: owner(ctx), type: 'shell' })
@@ -91,7 +99,9 @@ describe('E2BPtyBackend and plugin', () => {
 
   it('rejects aborts and invalid pids, killing a malformed SDK handle', async () => {
     const ctx = new Context()
-    const sandbox = {} as Sandbox
+    const sandbox = {
+      commands: { run: async () => ({ exitCode: 0, stdout: '', stderr: '' }) },
+    } as unknown as Sandbox
     ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
     const create = vi.fn().mockResolvedValue(handle(0))
     const backend = new E2BPtyBackend(ctx, config(), create)
@@ -109,13 +119,47 @@ describe('E2BPtyBackend and plugin', () => {
     const killFailure = handle(0, killFailureKill)
     const raced = new E2BPtyBackend(ctx, config(), async () => killFailure)
     await expect(raced.spawn({ sessionId: PtySessionId('three'), owner: owner(ctx), type: 'shell' })).rejects.toThrow('invalid PTY pid')
+
+    const invalidSessionKill = vi.fn().mockRejectedValue(new Error('kill raced'))
+    const invalidSessionHandle = {
+      pid: 123,
+      wait: vi.fn().mockRejectedValue(new Error('already exited')),
+      kill: invalidSessionKill,
+      disconnect: vi.fn(),
+    } as unknown as CommandHandle
+    const invalidSessionSandbox = {
+      commands: {
+        run: async (command: string) => ({
+          exitCode: 0,
+          stdout: command.startsWith('env -0') ? '' : '9007199254740992\n',
+          stderr: '',
+        }),
+      },
+    } as unknown as Sandbox
+    const invalidSessionContext = new Context()
+    invalidSessionContext.provide('e2b', {
+      cwd: '/workspace',
+      getSandbox: async () => invalidSessionSandbox,
+    } as E2BSandboxService)
+    const invalidSession = new E2BPtyBackend(invalidSessionContext, config(), async () => invalidSessionHandle)
+    await expect(invalidSession.spawn({
+      sessionId: PtySessionId('four'), owner: owner(invalidSessionContext), type: 'shell',
+    }))
+      .rejects.toThrow('cannot resolve process session')
+    expect(invalidSessionKill).toHaveBeenCalledOnce()
   })
 
   it('cleans failed startup and aggregates a cleanup failure', async () => {
     vi.useFakeTimers()
     const ctx = new Context()
     const sandbox = {
-      commands: { run: vi.fn().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }) },
+      commands: {
+        run: vi.fn(async (command: string) => ({
+          exitCode: 0,
+          stdout: command.startsWith('ps -o sid=') || command.startsWith('ps -eo sid=') ? '123\n' : '',
+          stderr: '',
+        })),
+      },
       pty: { kill: vi.fn().mockRejectedValue(new Error('cleanup failed')) },
     } as unknown as Sandbox
     ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
@@ -141,10 +185,19 @@ describe('E2BPtyBackend and plugin', () => {
       wait: () => completion.promise,
       disconnect: vi.fn().mockResolvedValue(undefined),
     } as unknown as CommandHandle
+    let sessionRunning = true
     const sandbox = {
       commands: {
         run: vi.fn(async (command: string) => {
-          if (command.startsWith('kill -TERM')) completion.resolve({ exitCode: 143, stdout: '', stderr: '' })
+          if (command.startsWith('env -0')) return { exitCode: 0, stdout: '', stderr: '' }
+          if (command.startsWith('ps -o sid=')) return { exitCode: 0, stdout: '123\n', stderr: '' }
+          if (command.startsWith('ps -eo sid=')) {
+            return { exitCode: 0, stdout: sessionRunning ? '123\n' : '', stderr: '' }
+          }
+          if (command.startsWith('kill -TERM')) {
+            sessionRunning = false
+            completion.resolve({ exitCode: 143, stdout: '', stderr: '' })
+          }
           return { exitCode: 0, stdout: '', stderr: '' }
         }),
       },
diff --git a/packages/e2b/pty-e2b/tests/session.spec.ts b/packages/e2b/pty-e2b/tests/session.spec.ts
index 6dced22ed2..554a4a3590 100644
--- a/packages/e2b/pty-e2b/tests/session.spec.ts
+++ b/packages/e2b/pty-e2b/tests/session.spec.ts
@@ -64,10 +64,12 @@ class FakeSandbox {
   readonly commands: string[] = []
   readonly killed: number[] = []
   pgid = '456\n'
+  sessionGroups = [123]
   sendError: unknown
-  commandError: unknown
+  signalError: unknown
   killError: unknown
   onTerm: (() => void) | undefined
+  onGroupKill: (() => void) | undefined
   onKill: (() => void) | undefined
 
   readonly sandbox = {
@@ -86,13 +88,19 @@ class FakeSandbox {
     commands: {
       run: async (command: string): Promise<CommandResult> => {
         this.commands.push(command)
-        if (this.commandError !== undefined) {
-          const error = this.commandError
-          this.commandError = undefined
-          throw error
+        if (command.startsWith('ps -o tpgid')) return { exitCode: 0, stdout: this.pgid, stderr: '' }
+        if (command.startsWith('ps -eo sid=')) {
+          return { exitCode: 0, stdout: this.sessionGroups.map(value => `${value}\n`).join(''), stderr: '' }
+        }
+        if (command.startsWith('kill -')) {
+          if (this.signalError !== undefined) {
+            const error = this.signalError
+            this.signalError = undefined
+            throw error
+          }
+          if (command.startsWith('kill -TERM')) this.onTerm?.()
+          if (command.startsWith('kill -KILL')) this.onGroupKill?.()
         }
-        if (command.startsWith('ps ')) return { exitCode: 0, stdout: this.pgid, stderr: '' }
-        if (command.startsWith('kill -TERM')) this.onTerm?.()
         return { exitCode: 0, stdout: '', stderr: '' }
       },
     },
@@ -122,7 +130,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config({ maxReadBytes: 12 }))
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config({ maxReadBytes: 12 }))
     expect(session.read({})).toMatchObject({ text: '', totalLines: 0 })
     await initialize(session)
     expect(session.motd).toBe('dsh> ')
@@ -152,7 +160,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     await initialize(session)
 
     const inferred = session.startSend({ text: '', submit: false })
@@ -176,7 +184,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
     expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
 
     const startupHandle = new FakePtyHandle()
-    const startup = new E2BPtySession(fake.sandbox, startupHandle.asHandle(), config())
+    const startup = new E2BPtySession(fake.sandbox, startupHandle.asHandle(), 123, config())
     const timedOut = expect(startup.initialize()).rejects.toThrow('startup timeout')
     await vi.advanceTimersByTimeAsync(100)
     await timedOut
@@ -186,7 +194,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     const initializing = session.initialize()
     session.onData(Buffer.from('\x1b]133;D;0\x07'))
     await vi.advanceTimersByTimeAsync(20)
@@ -230,7 +238,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     await initialize(session)
 
     const controller = new AbortController()
@@ -268,7 +276,7 @@ describe('E2BPtySession readiness, output, and signals', () => {
   it('preserves startup abort reasons and classifies invalid UTF-8 transport failures', async () => {
     const fake = new FakeSandbox()
     const abortHandle = new FakePtyHandle()
-    const abortSession = new E2BPtySession(fake.sandbox, abortHandle.asHandle(), config())
+    const abortSession = new E2BPtySession(fake.sandbox, abortHandle.asHandle(), 123, config())
     const controller = new AbortController()
     const reason = new Error('startup cancelled')
     const initializing = abortSession.initialize(controller.signal)
@@ -277,20 +285,20 @@ describe('E2BPtySession readiness, output, and signals', () => {
     await rejected
 
     const invalidHandle = new FakePtyHandle()
-    const invalid = new E2BPtySession(fake.sandbox, invalidHandle.asHandle(), config())
+    const invalid = new E2BPtySession(fake.sandbox, invalidHandle.asHandle(), 123, config())
     const pending = invalid.startSend({ text: '', submit: false })
     invalid.onData(Uint8Array.from([0xff]))
     await expect(pending.done).rejects.toThrow('invalid UTF-8')
     expect(invalid.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
 
     const crashHandle = new FakePtyHandle()
-    const crashed = new E2BPtySession(fake.sandbox, crashHandle.asHandle(), config())
+    const crashed = new E2BPtySession(fake.sandbox, crashHandle.asHandle(), 123, config())
     const active = crashed.startSend({ text: '', submit: false })
     crashHandle.crash('transport gone')
     await expect(active.done).rejects.toEqual(new Error('transport gone'))
 
     const startupExitHandle = new FakePtyHandle()
-    const startupExit = new E2BPtySession(fake.sandbox, startupExitHandle.asHandle(), config())
+    const startupExit = new E2BPtySession(fake.sandbox, startupExitHandle.asHandle(), 123, config())
     const exitedDuringStartup = expect(startupExit.initialize()).rejects.toThrow('exited during startup')
     startupExitHandle.exit(7)
     await exitedDuringStartup
@@ -300,12 +308,12 @@ describe('E2BPtySession readiness, output, and signals', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const tinyHandle = new FakePtyHandle()
-    const tiny = new E2BPtySession(fake.sandbox, tinyHandle.asHandle(), config({ maxReadBytes: 1 }))
+    const tiny = new E2BPtySession(fake.sandbox, tinyHandle.asHandle(), 123, config({ maxReadBytes: 1 }))
     tiny.onData(Buffer.from('你'))
     expect(tiny.read({ count: 1 })).toMatchObject({ text: '', lineEnd: 0 })
 
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     const operation = session.startSend({ text: '', submit: false })
     const internal = session as unknown as {
       pollReadiness(operation: PtySendOperation): void
@@ -324,8 +332,8 @@ describe('E2BPtySession teardown', () => {
     vi.useFakeTimers()
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    fake.onTerm = () => { handle.failExit(143) }
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    fake.onTerm = () => { fake.sessionGroups = []; handle.failExit(143) }
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     const first = session.close('done')
     expect(session.close('again')).toBe(first)
     await first
@@ -334,63 +342,100 @@ describe('E2BPtySession teardown', () => {
     expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
   })
 
+  it('escalates every job-control group that survives shell exit', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    fake.sessionGroups = [123, 456]
+    const handle = new FakePtyHandle()
+    fake.onTerm = () => { fake.sessionGroups = [456]; handle.failExit(143) }
+    fake.onGroupKill = () => { fake.sessionGroups = [] }
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
+
+    const closing = session.close('tree cleanup')
+    await vi.advanceTimersByTimeAsync(100)
+    await closing
+
+    expect(fake.commands).toContain('kill -TERM -- -123 -456')
+    expect(fake.commands).toContain('kill -KILL -- -456')
+  })
+
   it('contains an already-gone TERM, escalates to KILL, and reports a survivor', async () => {
     vi.useFakeTimers()
     const gone = new FakeSandbox()
     const goneHandle = new FakePtyHandle()
-    gone.commandError = commandError(1)
+    gone.signalError = commandError(1)
+    gone.onGroupKill = () => { gone.sessionGroups = [] }
     gone.onKill = () => { goneHandle.failExit(137) }
-    const goneSession = new E2BPtySession(gone.sandbox, goneHandle.asHandle(), config())
+    const goneSession = new E2BPtySession(gone.sandbox, goneHandle.asHandle(), 123, config())
     const closingGone = goneSession.close('gone')
-    await vi.advanceTimersByTimeAsync(20)
+    await vi.advanceTimersByTimeAsync(100)
     await closingGone
     expect(gone.killed).toEqual([123])
     expect(goneSession.status()).toEqual({ kind: 'exited', exitCode: null, signal: 'SIGKILL' })
 
     const survivor = new FakeSandbox()
     const survivorHandle = new FakePtyHandle()
-    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), config())
-    const failed = expect(survivorSession.close('still alive')).rejects.toThrow('surviving pid: 123')
-    await vi.advanceTimersByTimeAsync(40)
+    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), 123, config())
+    const failed = expect(survivorSession.close('still alive')).rejects.toThrow('surviving process groups: 123')
+    await vi.advanceTimersByTimeAsync(100)
     await failed
     survivorHandle.exit()
+    survivor.sessionGroups = []
     await expect(survivorSession.close('retry')).resolves.toBeUndefined()
   })
 
   it('propagates cleanup transport failures and lets close retry', async () => {
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    fake.commandError = new Error('TERM transport failed')
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    fake.signalError = new Error('TERM transport failed')
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     await expect(session.close('failure')).rejects.toThrow('TERM transport failed')
     handle.exit()
+    fake.sessionGroups = []
     await expect(session.close('retry')).resolves.toBeUndefined()
 
     const invalidTailHandle = new FakePtyHandle()
-    const invalidTail = new E2BPtySession(fake.sandbox, invalidTailHandle.asHandle(), config())
+    const invalidTail = new E2BPtySession(fake.sandbox, invalidTailHandle.asHandle(), 123, config())
     invalidTail.onData(Uint8Array.from([0xe2]))
     invalidTailHandle.exit()
     await expect(invalidTail.close('invalid tail')).rejects.toThrow('invalid UTF-8')
 
     const normalHandle = new FakePtyHandle()
     normalHandle.disconnectError = new Error('disconnect raced')
-    const normal = new E2BPtySession(fake.sandbox, normalHandle.asHandle(), config())
+    const normal = new E2BPtySession(fake.sandbox, normalHandle.asHandle(), 123, config())
     normalHandle.exit(7)
     await Promise.resolve()
     expect(normal.status()).toEqual({ kind: 'exited', exitCode: 7, signal: null })
     await expect(normal.close('already exited')).resolves.toBeUndefined()
   })
 
+  it('rejects invalid session groups and a shell handle that survives SDK kill', async () => {
+    const invalid = new FakeSandbox()
+    invalid.sessionGroups = [1]
+    const invalidSession = new E2BPtySession(invalid.sandbox, new FakePtyHandle().asHandle(), 123, config())
+    await expect(invalidSession.close('invalid group')).rejects.toThrow('invalid process group')
+
+    vi.useFakeTimers()
+    const survivor = new FakeSandbox()
+    survivor.sessionGroups = []
+    const survivorHandle = new FakePtyHandle()
+    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), 123, config())
+    const failed = expect(survivorSession.close('shell survived')).rejects.toThrow('surviving pid: 123')
+    await vi.advanceTimersByTimeAsync(100)
+    await failed
+    expect(survivor.killed).toEqual([123])
+  })
+
   it('kills a remotely live PTY after its host transport fails', async () => {
     const fake = new FakeSandbox()
     const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), config())
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
     const active = session.startSend({ text: '', submit: false })
     session.onData(Uint8Array.from([0xff]))
     await expect(active.done).rejects.toThrow('invalid UTF-8')
     expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
 
-    fake.onTerm = () => { handle.failExit(143) }
+    fake.onTerm = () => { fake.sessionGroups = []; handle.failExit(143) }
     await expect(session.close('transport failed')).rejects.toThrow('invalid UTF-8')
     expect(fake.commands).toContain('kill -TERM -- -123')
     expect(handle.disconnects).toBe(1)
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 8b8a70838c..f05191a45b 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 3b3bfa88e7e6483decfcdec11355942ae4ff7403
-README.zh.md: 3ff9a51c60636dea5789f9dd11b04aa902b91d0c
+README.md: 066d35a099f560fe40fe629ede632c37535129f7
+README.zh.md: d3af14e8cc58c7d86331156358f78a0abbb24c39
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 3b3bfa88e7..066d35a099 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -6,8 +6,8 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 ## Behavior
 
-- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the SDK returns the command PID; `done`, stdin, termination, and `waitForExit()` wait for readiness internally.
-- **Linux process groups** — a quoted wrapper starts each argv under `setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of assuming the SDK command PID is the group id. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
+- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; `done`, stdin, termination, and `waitForExit()` wait for readiness internally.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. If publication fails, the SDK PID remains the provisional `exec setsid` group id; rollback kills and verifies that group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
 - **Stdio projection** — pipe mode forwards E2B callbacks into host Node streams; inherit mode forwards them to the harness process streams; collect mode retains a bounded host tail with offset reads. Optional complete spill files are written remotely and advertised only while within their cap. Batch and streaming stdin use the SDK handle.
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index 3ff9a51c60..d3af14e8cc 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -6,8 +6,8 @@
 
 ## 行为
 
-- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。SDK 返回命令 PID 之前，`pid` 为 `-1`；`done`、stdin、终止和 `waitForExit()` 会在内部等待就绪。
-- **Linux 进程组**：带引号保护的包装层会在 `setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会假设 SDK 命令 PID 就是进程组 ID。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
+- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；`done`、stdin、终止和 `waitForExit()` 会在内部等待就绪。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。如果发布失败，SDK PID 仍为临时的 `exec setsid` 进程组 ID；回滚会终止并验证该进程组，随后启动操作才会以拒绝结束。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
 - **stdio 投影**：pipe 模式把 E2B 回调转发到宿主 Node 流；inherit 模式把回调转发到 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。可选的完整 spill 文件写在远程，并且只有未超过其上限时才会对外公布。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 86bdade589..3b9594a752 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -253,7 +253,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       try {
         this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
       } catch (error: unknown) {
-        await Promise.allSettled([handle.kill()])
+        try {
+          await this.rollbackUnpublishedGroup(sandbox, handle)
+        } catch (cleanupError: unknown) {
+          throw new AggregateError(
+            [error, cleanupError],
+            'subprocess-e2b: process-group publication failed and rollback did not reach quiescence',
+          )
+        }
         throw error
       }
       this.readyState.resolve(handle)
@@ -361,6 +368,19 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     }
   }
 
+  private async rollbackUnpublishedGroup(sandbox: Sandbox, handle: CommandHandle): Promise<void> {
+    // The background command begins with `exec setsid`, so E2B's command PID is
+    // the provisional group id even before the private publication file can be
+    // trusted. Kill that group before the SDK-PID fallback, then prove no group
+    // member survived before rejecting startup.
+    try {
+      await this.signalGroup(sandbox, handle.pid, 'KILL')
+    } finally {
+      await handle.kill().catch(() => false)
+    }
+    while (await this.groupAlive(sandbox, handle.pid)) await waitTick()
+  }
+
   private async terminateRemote(): Promise<void> {
     let handle: CommandHandle
     try {
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 6be645a713..fd4cc97a83 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -89,6 +89,7 @@ class FakeSandbox {
   probeError: unknown
   signalError: unknown
   trapsTerm = false
+  delaysKill = false
   alive = true
   processGroupId = '4242\n'
   readonly processGroupReads: string[] = []
@@ -176,7 +177,7 @@ class FakeSandbox {
             this.signalError = undefined
             throw error
           }
-          this.alive = false
+          if (!this.delaysKill) this.alive = false
           this.handle.fail(137)
           return { exitCode: 0, stdout: '', stderr: '' }
         }
@@ -596,14 +597,13 @@ describe('E2BSubprocessHandle', () => {
   it('rejects invalid or absent process-group publication', async () => {
     const invalidGroup = new FakeSandbox()
     invalidGroup.processGroupId = 'not-a-pid\n'
-    vi.spyOn(invalidGroup.handle, 'kill').mockImplementation(async () => {
-      invalidGroup.handle.kills += 1
-      invalidGroup.finish()
-      return true
-    })
+    invalidGroup.delaysKill = true
+    invalidGroup.afterProbe = () => { invalidGroup.alive = false }
     const invalid = new E2BSubprocessHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
     await expect(invalid.done).rejects.toThrow(/invalid process-group id/)
     expect(invalidGroup.handle.kills).toBe(1)
+    expect(invalidGroup.commandsSeen).toContain('kill -KILL -- -4242')
+    await expect(invalid.waitForExit()).resolves.toBe(true)
 
     const absentGroup = new FakeSandbox()
     absentGroup.processGroupId = ''
@@ -612,6 +612,35 @@ describe('E2BSubprocessHandle', () => {
     absentGroup.finish()
     await expect(absent.done).rejects.toThrow(/exited before publishing/)
     expect(absentGroup.handle.kills).toBe(1)
+    expect(absentGroup.commandsSeen).toContain('kill -KILL -- -4242')
+    await expect(absent.waitForExit()).resolves.toBe(true)
+  })
+
+  it('preserves publication and rollback failures when cleanup cannot be verified', async () => {
+    const fake = new FakeSandbox()
+    fake.processGroupId = 'not-a-pid\n'
+    fake.signalError = new Error('rollback signal failed')
+    fake.handle.killError = new Error('SDK kill failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/failed-rollback')
+
+    let failure: unknown
+    try {
+      await handle.done
+    } catch (error: unknown) {
+      failure = error
+    }
+    expect(failure).toBeInstanceOf(AggregateError)
+    if (!(failure instanceof AggregateError)) throw new Error('expected AggregateError')
+    expect(failure.message).toBe('subprocess-e2b: process-group publication failed and rollback did not reach quiescence')
+    const failures = Array.from(failure.errors as Iterable<unknown>)
+    expect(failures).toHaveLength(2)
+    expect(failures[0]).toBeInstanceOf(Error)
+    expect(failures[1]).toBeInstanceOf(Error)
+    if (!(failures[0] instanceof Error) || !(failures[1] instanceof Error)) throw new Error('expected nested errors')
+    expect(failures[0].message).toContain('invalid process-group id')
+    expect(failures[1].message).toBe('rollback signal failed')
+    expect(fake.handle.kills).toBe(1)
+    fake.finish()
   })
 
   it('waits for delayed process-group publication', async () => {

From 64b4669a742b975e717e1544316efee427925bad Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 18:38:45 +0800
Subject: [PATCH 359/516] docs(packages): fit merged group map budget

---
 packages/README.i18n.yaml | 4 ++--
 packages/README.md        | 4 ++--
 packages/README.zh.md     | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index b8320d8c19..a0827779db 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: c46a08f76f9f38f9620c03f05f28e7698487afc8
-README.zh.md: 65a5c6c88b9b37b3f948b11c6db778e42965643d
+README.md: 7dc52943e488a14e0c055ac72be0b2ad6f752455
+README.zh.md: bc3dbf0b4533d1d6adf6d49b0376a3dcdd6bfdb5
diff --git a/packages/README.md b/packages/README.md
index b2a870f516..125b466d72 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -6,7 +6,7 @@ Packages use the `@deepseek-ai/dsh-*` scope. Cordis `Service` subclasses and fun
 
 ## Hierarchy
 
-Packages live at `packages/<group>/<pkg>/`; groups are containers, while names remain `@deepseek-ai/dsh-<pkg>`. **Each group README is the canonical package/ctx-key map.**
+Groups contain packages at `packages/<group>/<pkg>/`; names remain `@deepseek-ai/dsh-<pkg>`. **Group READMEs own package/ctx-key maps.**
 
 | Group | Role | Release expectation |
 |---|---|---|
@@ -16,7 +16,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
-| [`e2b/`](e2b/README.md) | E2B remote-runtime provider family | POC |
+| [`e2b/`](e2b/README.md) | E2B providers | POC |
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index c8079c3d03..1667c88273 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 层级结构
 
-包位于 `packages/<group>/<pkg>/`；组是容器，包名仍为 `@deepseek-ai/dsh-<pkg>`。**每个组 README 是规范的包／ctx 键映射。**
+组在 `packages/<group>/<pkg>/` 容纳包；包名仍为 `@deepseek-ai/dsh-<pkg>`。**组 README 是规范的包／ctx 键映射。**
 
 | 组 | 职责 | 发布预期 |
 |---|---|---|
@@ -16,7 +16,7 @@
 | [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
-| [`e2b/`](e2b/README.md) | E2B 远程运行时提供方系列 | POC |
+| [`e2b/`](e2b/README.md) | E2B 提供方 | POC |
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |

From 97496c3d00b4165dfb64d57b55d00e3462bedab4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 19:21:39 +0800
Subject: [PATCH 360/516] fix(e2b): close remaining remote lifecycle races

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |   6 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |   6 +-
 .../tests/fixtures/e2b/e2b/bin.ts             |  59 ++-
 .../e2b/code-runtime-e2b/README.i18n.yaml     |   4 +-
 packages/e2b/code-runtime-e2b/README.md       |   2 +-
 packages/e2b/code-runtime-e2b/README.zh.md    |   2 +-
 .../e2b/code-runtime-e2b/src/runner-source.ts |  17 +-
 .../code-runtime-e2b/tests/runtime.spec.ts    |  52 ++-
 packages/e2b/e2b/tests/composition.e2e.ts     |   3 +
 packages/e2b/lsp-e2b/README.i18n.yaml         |   6 -
 packages/e2b/lsp-e2b/README.md                |  47 --
 packages/e2b/lsp-e2b/README.zh.md             |  47 --
 packages/e2b/lsp-e2b/package.json             |  52 ---
 packages/e2b/lsp-e2b/src/index.ts             | 441 ------------------
 packages/e2b/lsp-e2b/src/invariant.ts         |  20 -
 packages/e2b/lsp-e2b/src/proxy-source.ts      |  55 ---
 packages/e2b/lsp-e2b/src/transport.ts         | 183 --------
 packages/e2b/lsp-e2b/tests/provider.spec.ts   | 418 -----------------
 packages/e2b/lsp-e2b/tests/transport.spec.ts  | 181 -------
 packages/e2b/lsp-e2b/tsconfig.json            |  20 -
 packages/e2b/pty-e2b/README.i18n.yaml         |   4 +-
 packages/e2b/pty-e2b/README.md                |   2 +-
 packages/e2b/pty-e2b/README.zh.md             |   2 +-
 packages/e2b/pty-e2b/src/session.ts           |  14 +-
 packages/e2b/pty-e2b/tests/session.spec.ts    |  44 +-
 26 files changed, 193 insertions(+), 1498 deletions(-)
 delete mode 100644 packages/e2b/lsp-e2b/README.i18n.yaml
 delete mode 100644 packages/e2b/lsp-e2b/README.md
 delete mode 100644 packages/e2b/lsp-e2b/README.zh.md
 delete mode 100644 packages/e2b/lsp-e2b/package.json
 delete mode 100644 packages/e2b/lsp-e2b/src/index.ts
 delete mode 100644 packages/e2b/lsp-e2b/src/invariant.ts
 delete mode 100644 packages/e2b/lsp-e2b/src/proxy-source.ts
 delete mode 100644 packages/e2b/lsp-e2b/src/transport.ts
 delete mode 100644 packages/e2b/lsp-e2b/tests/provider.spec.ts
 delete mode 100644 packages/e2b/lsp-e2b/tests/transport.spec.ts
 delete mode 100644 packages/e2b/lsp-e2b/tsconfig.json

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index beb49fba76..04ebe420ac 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: efb91fc166f36dc8fb047d686e8cd82d93b9af6a
-2026-07-27-e2b-remote-runtime-poc.zh.md: eb14cccc284d38cdc5cc704512b6899621a9a840
+2026-07-27-e2b-remote-runtime-poc.md: 4e6414b7d919d765712ac9314ce73a69c5c6344e
+2026-07-27-e2b-remote-runtime-poc.zh.md: 4d39ed7eb07cdd17c5bfa9155bc7efabaa798117
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index efb91fc166..4e6414b7d9 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -32,7 +32,7 @@ E2B owns the mutable filesystem, command and Bash processes, PTY shell and termi
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly. LSP installs a bounded remote source reader, while Code Runtime keeps framed stdout in a launcher process isolated from the controller and worker descriptors. Their dependency-free helpers encode protocol payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
+Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly and carries send identity across asynchronous foreground-group lookup. LSP installs a bounded remote source reader that walks no-follow directory descriptors beneath the canonical workspace. Code Runtime keeps framed stdout in a launcher process isolated from the controller and worker descriptors, and gives each controller a process group that is killed before its inherited pipes drain. Their dependency-free helpers encode protocol payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
@@ -40,9 +40,9 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 ## Verification
 
-Focused package suites pin owner lifecycle cleanup, filesystem semantics and commit metadata, subprocess process groups, configuration and verified publication rollback, byte framing and multibyte boundaries, PTY readiness/signals/default-environment scrubbing/terminal-session cleanup, stable bounded LSP source reads, Code Runtime binding and descriptor isolation, worker-pipe draining, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
+Focused package suites pin owner lifecycle cleanup, filesystem semantics and commit metadata, subprocess process groups, configuration and verified publication rollback, byte framing and multibyte boundaries, PTY readiness/signal identity/default-environment scrubbing/terminal-session cleanup, descriptor-walked bounded LSP source reads, Code Runtime binding and descriptor isolation, worker and descendant-held pipe draining, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
 
-A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, bounded spill output, PTY default-secret scrubbing and process-tree cleanup, stable bounded LSP source reads, Code Runtime host bindings and descriptor-isolated output accounting, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
+A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, bounded spill output, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index eb14cccc28..4d39ed7eb0 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -32,7 +32,7 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调。LSP 会安装一个有界的远程源码读取器；Code Runtime 则把分帧 stdout 保留在与 controller 和 worker 描述符隔离的 launcher 进程内。它们的无依赖辅助程序会把协议载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
+对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调，并在异步查找前台进程组的过程中保留发送操作身份。LSP 会安装一个有界的远程源码读取器，通过不跟随符号链接打开的目录描述符在规范化工作区下逐级遍历。Code Runtime 则把分帧 stdout 保留在与 controller 和 worker 描述符隔离的 launcher 进程内，并为每个 controller 分配一个进程组，在 controller 继承的管道排空前终止该组。它们的无依赖辅助程序会把协议载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
@@ -40,9 +40,9 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话
 
 ## 验证
 
-聚焦包测试套件固定所有者生命周期清理、文件系统语义与提交元数据、进程管理的进程组、配置与经过验证的发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号／默认环境清理／终端会话清理、稳定且有界的 LSP 源码读取、Code Runtime 绑定与描述符隔离、worker 管道排空、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
+聚焦包测试套件固定所有者生命周期清理、文件系统语义与提交元数据、进程管理的进程组、配置与经过验证的发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号身份／默认环境清理／终端会话清理、基于描述符逐级遍历的有界 LSP 源码读取、Code Runtime 绑定与描述符隔离、worker 管道及后代进程所持管道的排空、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
 
-凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、有界 spill 输出、PTY 默认秘密清理与进程树清理、稳定且有界的 LSP 源码读取、Code Runtime 宿主绑定与描述符隔离的输出记账、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
+凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、有界 spill 输出、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 4f2401d2c7..a997752711 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -147,18 +147,23 @@ try {
     workspaceRoot: process.cwd(),
   })
 
-  const swappedSource = await ctx.fs.resolve('swapped-source.ts')
-  const swappedSourcePath = posix.join(process.cwd(), 'swapped-source.ts')
-  await ctx.fs.writeText(swappedSource, 'const safe = true\n', { kind: 'createIfAbsent' })
+  const swappedParentPath = posix.join(process.cwd(), 'swapped-parent')
+  const swappedSourcePath = posix.join(swappedParentPath, 'source.ts')
+  const swappedOutsidePath = '/tmp/dsh-e2b-lsp-outside'
+  await sandbox.commands.run(
+    `mkdir -p -- ${quoteE2BShellArg(swappedParentPath)} ${quoteE2BShellArg(swappedOutsidePath)} && printf 'const safe = true\\n' > ${quoteE2BShellArg(swappedSourcePath)} && printf 'const outside = true\\n' > ${quoteE2BShellArg(posix.join(swappedOutsidePath, 'source.ts'))}`,
+  )
   const remoteCommands = sandbox.commands as unknown as {
     run(command: string, options?: unknown): Promise<{ exitCode: number; stdout: string; stderr: string }>
   }
   const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
   let containmentFaultInjected = false
   remoteCommands.run = async (command, options) => {
-    if (!containmentFaultInjected && command.includes('dsh-e2b-source-reader') && command.includes('swapped-source.ts')) {
+    if (!containmentFaultInjected && command.includes('dsh-e2b-source-reader') && command.includes('swapped-parent/source.ts')) {
       containmentFaultInjected = true
-      await runRemoteCommand(`rm -f -- ${quoteE2BShellArg(swappedSourcePath)} && ln -s -- /etc/hosts ${quoteE2BShellArg(swappedSourcePath)}`)
+      await runRemoteCommand(
+        `rm -rf -- ${quoteE2BShellArg(swappedParentPath)} && ln -s -- ${quoteE2BShellArg(swappedOutsidePath)} ${quoteE2BShellArg(swappedParentPath)}`,
+      )
     }
     return await runRemoteCommand(command, options)
   }
@@ -166,7 +171,7 @@ try {
   try {
     await ctx.lsp.query({
       operation: 'hover',
-      filePath: 'swapped-source.ts',
+      filePath: 'swapped-parent/source.ts',
       position: { line: 0, character: 1 },
       workspaceRoot: process.cwd(),
     })
@@ -200,8 +205,28 @@ try {
     text: "printf 'PTY-你好\\n'",
     submit: true,
   }).done
+  const foregroundLookup = Promise.withResolvers<undefined>()
+  let delayedForegroundLookup = false
+  remoteCommands.run = async (command, options) => {
+    if (!delayedForegroundLookup && command.startsWith('ps -o tpgid=')) {
+      delayedForegroundLookup = true
+      await foregroundLookup.promise
+    }
+    return await runRemoteCommand(command, options)
+  }
+  const staleInterrupt = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 0.2', submit: true })
+  if (!staleInterrupt.cancel()) throw new Error('E2B PTY refused the stale-interrupt probe cancellation')
+  await staleInterrupt.done
   const sleeping = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 30', submit: true })
-  await new Promise(resolveDelay => setTimeout(resolveDelay, 150))
+  foregroundLookup.resolve(undefined)
+  const interruptIdentitySafe = await Promise.race([
+    sleeping.done.then(() => false),
+    new Promise<true>(resolveDelay => setTimeout(() => { resolveDelay(true) }, 300)),
+  ])
+  remoteCommands.run = runRemoteCommand
+  if (!delayedForegroundLookup || !interruptIdentitySafe) {
+    throw new Error('E2B PTY stale interrupt affected its successor send')
+  }
   const terminalSignal = await ctx.pty.signal(owner, terminal.sessionId, 'SIGINT')
   const interrupted = await sleeping.done
   const stubborn = await ctx.pty.startSend(owner, terminal.sessionId, {
@@ -296,6 +321,23 @@ try {
     `,
     bindings: [],
   })
+  const descendantPipe = await ctx.codeRuntime.run({
+    program: `
+      const childProcess = await import('node:child_process')
+      const child = childProcess.spawn(
+        process.execPath,
+        ['-e', 'setInterval(() => {}, 1000)', 'dsh-code-runtime-descendant'],
+        { stdio: ['ignore', 'inherit', 'inherit'] },
+      )
+      return child.pid > 0
+    `,
+    bindings: [],
+  })
+  const descendantProcesses = await sandbox.commands.list()
+  const descendantCleanup = !descendantProcesses.some(processInfo =>
+    JSON.stringify([processInfo.cmd, processInfo.args]).includes('dsh-code-runtime-descendant'),
+  )
+  if (!descendantCleanup) throw new Error('E2B Code Runtime left a pipe-holding descendant alive')
   const timedOut = await ctx.codeRuntime.run({
     program: 'await new Promise(() => {})',
     bindings: [],
@@ -340,6 +382,7 @@ try {
       echo: terminalEcho,
       signal: terminalSignal,
       interrupted,
+      interruptIdentitySafe,
       treeCleanup: terminalTreeCleanup,
       scrollback: terminalScrollback.text,
     },
@@ -348,6 +391,8 @@ try {
     nativeOutput,
     descriptorOutput,
     inheritedOutput,
+    descendantPipe,
+    descendantCleanup,
     timedOut,
     aborted,
     oversizedBoot,
diff --git a/packages/e2b/code-runtime-e2b/README.i18n.yaml b/packages/e2b/code-runtime-e2b/README.i18n.yaml
index ba43d787b8..eb4e75f297 100644
--- a/packages/e2b/code-runtime-e2b/README.i18n.yaml
+++ b/packages/e2b/code-runtime-e2b/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/e2b/code-runtime-e2b/README.md
-README.md: 171e63a8c1ca70deb63e9860f5088b83401a37d0
-README.zh.md: b70984e765d32985436c15dd543263cc06a25715
+README.md: a8623f95d16b54b29e53bb9cf2c528b36f121283
+README.zh.md: 2b4a37864e3c6755a74f0d2ef6ce38aa39aae24b
diff --git a/packages/e2b/code-runtime-e2b/README.md b/packages/e2b/code-runtime-e2b/README.md
index 171e63a8c1..a8623f95d1 100644
--- a/packages/e2b/code-runtime-e2b/README.md
+++ b/packages/e2b/code-runtime-e2b/README.md
@@ -19,7 +19,7 @@ Every value is a positive safe integer. `maxOutputBytes` is at least four bytes,
 
 ## Execution and bridge contract
 
-Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner keeps the framed host protocol in a launcher process, forks a controller whose stdout and stderr are bounded data pipes, and creates a fresh worker thread with an empty environment and heap limit. Model writes to native descriptors and inherited child output therefore cannot enter the frame stream; worker and controller pipes drain before the terminal frame. The worker measures active event-loop time and is destroyed after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in that group stop with the run.
+Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner keeps the framed host protocol in a launcher process, forks a controller process group whose stdout and stderr are bounded data pipes, and creates a fresh worker thread with an empty environment and heap limit. Model writes to native descriptors and inherited child output therefore cannot enter the frame stream; completion kills the controller group before draining its pipes and emitting the terminal frame. The worker measures active event-loop time and is destroyed after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in either managed group stop with the run.
 
 The bridge uses validated newline-delimited base64 JSON frames because E2B subprocess callbacks expose decoded text. Binding arguments and resolutions use the worker runtime's iterative lossless-JSON wire shape; binding functions execute on the host and typed rejection classes are materialized inside the remote worker. The worker captures the JavaScript intrinsics that its adapter boundary invokes before model code runs, hardening binding transport, output accounting, and completion validation against mutation of those references. The host repeats message validation, call-id deduplication, lossless-JSON checks, and the outer-output ledger.
 
diff --git a/packages/e2b/code-runtime-e2b/README.zh.md b/packages/e2b/code-runtime-e2b/README.zh.md
index b70984e765..2b4a37864e 100644
--- a/packages/e2b/code-runtime-e2b/README.zh.md
+++ b/packages/e2b/code-runtime-e2b/README.zh.md
@@ -19,7 +19,7 @@
 
 ## 执行与桥接契约
 
-设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会把面向宿主的分帧协议保留在 launcher 进程内，派生一个以 stdout 和 stderr 作为有界数据管道的 controller，再创建一个具有空环境与堆上限的全新 worker 线程。因此，模型对原生描述符的写入和继承的子进程输出无法进入分帧流；worker 与 controller 管道会在发出终结帧前排空。worker 会测量事件循环活跃时间，并在一次运行结算后销毁。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此组内的普通子进程会随本次运行一同停止。
+设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会把面向宿主的分帧协议保留在 launcher 进程内，派生一个以 stdout 和 stderr 作为有界数据管道的 controller 进程组，再创建一个具有空环境与堆上限的全新 worker 线程。因此，模型对原生描述符的写入和继承的子进程输出无法进入分帧流；运行结算会先终止 controller 进程组，再排空其管道并发出终结帧。worker 会测量事件循环活跃时间，并在一次运行结算后销毁。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此任一受管组内的普通子进程会随本次运行一同停止。
 
 由于 E2B 进程管理回调公开的是已解码文本，桥接层使用经过验证、以换行分隔的 base64 JSON 帧。绑定参数与 resolve 值使用 worker 运行时的迭代式无损 JSON wire 形状；绑定函数在宿主执行，类型化的 reject 类则在远程 worker 内物化。worker 会在模型代码运行前捕获其适配器边界调用的 JavaScript intrinsic，从而增强绑定传输、输出记账与完成值验证对这些引用修改的抵御能力。宿主会再次执行消息验证、调用 id 去重和无损 JSON 检查，并用外层输出账本再次计量。
 
diff --git a/packages/e2b/code-runtime-e2b/src/runner-source.ts b/packages/e2b/code-runtime-e2b/src/runner-source.ts
index e5cf6ebefa..527f21114e 100644
--- a/packages/e2b/code-runtime-e2b/src/runner-source.ts
+++ b/packages/e2b/code-runtime-e2b/src/runner-source.ts
@@ -35,6 +35,18 @@ const waitForChildExit = child => {
   return new Promise(resolve => { child.once('exit', resolve) })
 }
 
+const killControllerGroup = child => {
+  if (process.platform !== 'win32' && Number.isSafeInteger(child.pid)) {
+    try {
+      process.kill(-child.pid, 'SIGKILL')
+    } catch (error) {
+      if (!error || typeof error !== 'object' || error.code !== 'ESRCH') throw error
+    }
+    return
+  }
+  child.kill('SIGKILL')
+}
+
 const jsonStringBytes = text => Buffer.byteLength(JSON.stringify(text))
 
 const truncateLog = (text, available) => {
@@ -74,7 +86,7 @@ const runLauncher = () => {
           const stdoutDrained = waitForPipeDrain(current.stdout)
           const stderrDrained = waitForPipeDrain(current.stderr)
           const exited = waitForChildExit(current)
-          current.kill('SIGKILL')
+          killControllerGroup(current)
           await Promise.all([exited, stdoutDrained, stderrDrained])
         })
       : Promise.resolve()
@@ -112,6 +124,7 @@ const runLauncher = () => {
     maxOutputBytes = message.maxOutputBytes
     controller = fork(fileURLToPath(import.meta.url), [], {
       env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
+      detached: process.platform !== 'win32',
       execArgv: [],
       stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
     })
@@ -173,7 +186,7 @@ const runLauncher = () => {
         })
     }
   })
-  input.on('close', () => { if (controller && !settling) controller.kill('SIGKILL') })
+  input.on('close', () => { if (controller && !settling) killControllerGroup(controller) })
 }
 
 const runController = () => {
diff --git a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
index 9743c361c5..f99485a929 100644
--- a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
+++ b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
@@ -1,8 +1,9 @@
 import { spawn } from 'node:child_process'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { access, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PassThrough, Writable } from 'node:stream'
+import { setTimeout as delay } from 'node:timers/promises'
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import type { Sandbox } from '@deepseek-ai/dsh-e2b'
@@ -271,6 +272,55 @@ describe('E2BCodeRuntime', () => {
     expect(Buffer.byteLength(nativeOutput)).toBe(expectedBytes)
   })
 
+  it.skipIf(process.platform === 'win32')('reaps descendant-held controller pipes before completion', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'dsh-e2b-code-descendant-'))
+    const marker = join(directory, 'started')
+    const release = join(directory, 'release')
+    const childSource = `
+      const fs = require('node:fs')
+      fs.writeFileSync(${JSON.stringify(marker)}, 'started')
+      const timer = setInterval(() => {
+        if (fs.existsSync(${JSON.stringify(release)})) clearInterval(timer)
+      }, 10)
+    `
+    let running: ReturnType<typeof runInstalledRunner> | undefined
+    try {
+      running = runInstalledRunner(`
+        const fs = await import('node:fs')
+        const childProcess = await import('node:child_process')
+        childProcess.spawn(process.execPath, ['-e', ${JSON.stringify(childSource)}], {
+          stdio: ['ignore', 'inherit', 'inherit'],
+        })
+        while (!fs.existsSync(${JSON.stringify(marker)})) await new Promise(resolve => setTimeout(resolve, 5))
+        return true
+      `)
+      const deadline = Date.now() + 2_000
+      for (;;) {
+        try {
+          await access(marker)
+          break
+        } catch (error: unknown) {
+          if (Date.now() >= deadline) throw error
+          await delay(10)
+        }
+      }
+      const completed = await Promise.race([
+        running.then(() => true),
+        delay(500).then(() => false),
+      ])
+      await writeFile(release, '')
+      const { messages, stderr } = await running
+
+      expect(completed).toBe(true)
+      expect(stderr).toBe('')
+      expect(messages.at(-1)).toEqual({ type: 'done', value: [true] })
+    } finally {
+      await writeFile(release, '').catch(() => undefined)
+      await running?.catch(() => undefined)
+      await rm(directory, { recursive: true, force: true })
+    }
+  })
+
   it('prepares the remote runner and returns logs and a lossless completion', async () => {
     const handle = new FakeHandle((message, current) => {
       if ((message as { type?: string }).type !== 'boot') return
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 4f4ea19eb9..1bfbab1e8e 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -109,12 +109,15 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
         signal: { delivered: true },
         interrupted: { sessionStatus: { kind: 'running' } },
+        interruptIdentitySafe: true,
         treeCleanup: true,
       },
       hostileOutput: { error: { kind: 'output-limit' } },
       nativeOutput: { error: { kind: 'output-limit' } },
       descriptorOutput: { error: { kind: 'output-limit' } },
       inheritedOutput: { error: { kind: 'output-limit' } },
+      descendantPipe: { value: true, logs: [] },
+      descendantCleanup: true,
       timedOut: { error: { kind: 'timeout' } },
       aborted: { error: { kind: 'abort', message: 'live abort' } },
       oversizedBoot: { error: { kind: 'worker-exit' } },
diff --git a/packages/e2b/lsp-e2b/README.i18n.yaml b/packages/e2b/lsp-e2b/README.i18n.yaml
deleted file mode 100644
index 066820d9fd..0000000000
--- a/packages/e2b/lsp-e2b/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/e2b/lsp-e2b/README.md
-README.md: 6cc118767adc5d2df855b009f48faab596928fb7
-README.zh.md: b384e9efd0e5c62b0ee6e69f73755e1bbe0192df
diff --git a/packages/e2b/lsp-e2b/README.md b/packages/e2b/lsp-e2b/README.md
deleted file mode 100644
index 6cc118767a..0000000000
--- a/packages/e2b/lsp-e2b/README.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# @deepseek-ai/dsh-lsp-e2b
-
-English | [中文](README.zh.md)
-
-Generic E2B language-server backend for [`ctx.lsp`](../../lsp/lsp/README.md). It runs configured stdio servers and reads their source documents inside the shared `ctx.e2b` sandbox; the provider registry, normalized query results, queues, and protocol connection state remain on the host.
-
-## Plugin and configuration
-
-The `lsp-e2b` plugin injects `e2b`, `lsp`, and the concrete `dsh-subprocess-e2b` service. `servers` is a non-empty provider-id table:
-
-| Server key | Default | Meaning |
-|---|---|---|
-| `command` | required | Remote executable, absolute or resolved on the sandbox PATH at load. |
-| `args` | `[]` | Remote server arguments. |
-| `env` | `{}` | Explicit environment entries passed through the subprocess adapter. |
-| `extensionToLanguage` | required | Lowercase leading-dot extension to LSP language id. |
-| `initializationOptions` / `configuration` | `null` / `null` | Static initialize options and `workspace/configuration` answer. |
-| `maxMessageBytes` | `16000000` | Largest LSP message accepted from the server. |
-| `maxStderrBytes` | `1000000` | Retained raw server stderr tail. |
-| `maxDocumentBytes` | `4000000` | Largest remote source opened for one query. |
-| `shutdownTimeoutMs` | `5000` | Graceful protocol-shutdown budget. |
-| `killGraceMs` | `2000` | Request-cancel and TERM-to-KILL grace. |
-
-Provider ids and commands are non-empty; numeric bounds are positive safe integers, and timer values cannot exceed Node's maximum timer delay. Setup uploads one owner-private proxy under `ctx.e2b.runtimeRoot`, resolves Node and every configured server executable remotely, then registers all providers atomically.
-
-## Remote protocol and filesystem
-
-E2B command callbacks are text, while LSP is byte-framed. The installed proxy therefore base64-frames raw server stdout, stderr, and stdin as newline-delimited ASCII JSON; the host validates and decodes every frame before handing bytes to the shared `LspInstance` protocol engine. `initialize.processId` is `null` because host and server do not share a process namespace.
-
-One language-server process is pooled per provider and canonical remote workspace. Queries serialize per workspace but different workspaces run concurrently. Each query canonicalizes the remote workspace and source with `realpath`, rejects paths outside that workspace, then uses a remote helper to open the canonical source without following the final symlink and to verify and read one stable descriptor. The helper requires a regular file and reads at most `maxDocumentBytes + 1` bytes before strict UTF-8 decoding. Queries use the ordinary transient `didOpen` / request / `didClose` lifecycle. A transport failure disposes the instance and retries the read-only query once on a fresh remote process.
-
-The subprocess adapter owns process groups and escalation, so cancellation and disposal await remote server quiescence. The host owns LSP request ids, pending requests, provider queues, and normalized results.
-
-## Model Experience
-
-Indirectly, through `@deepseek-ai/dsh-tool-lsp`, which exposes normalized semantic navigation and hover results without changing its model-facing schema.
-
-#### KV Cache effect
-
-No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
-
-## Known Limitations and Deferred Work
-
-- **Configured servers only** — this package does not install language servers, select presets, or synchronize a host workspace into E2B.
-- **Host protocol state is not reconnectable** — retaining a sandbox does not restore provider queues, JSON-RPC requests, subprocess handles, or document lifecycle state.
-- **SDK output retention remains** — ASCII framing preserves protocol bytes, but E2B and the subprocess adapter still retain callback output in host memory.
-- **Sandbox policy is template-owned** — this provider adds no volume, snapshot, credential, or network-policy layer.
diff --git a/packages/e2b/lsp-e2b/README.zh.md b/packages/e2b/lsp-e2b/README.zh.md
deleted file mode 100644
index b384e9efd0..0000000000
--- a/packages/e2b/lsp-e2b/README.zh.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# @deepseek-ai/dsh-lsp-e2b
-
-[English](README.md) | 中文
-
-用于 [`ctx.lsp`](../../lsp/lsp/README.md) 的通用 E2B 语言服务器后端。它在共享的 `ctx.e2b` 沙箱内运行已配置的 stdio 服务器并读取其源文档；提供方注册表、规范化查询结果、队列和协议连接状态仍保留在宿主侧。
-
-## 插件与配置
-
-`lsp-e2b` 插件注入 `e2b`、`lsp` 和具体的 `dsh-subprocess-e2b` 服务。`servers` 是一张非空的提供方 id 表：
-
-| 服务器键 | 默认值 | 含义 |
-|---|---|---|
-| `command` | 必填 | 远程可执行文件：绝对路径，或在加载时通过沙箱 PATH 解析。 |
-| `args` | `[]` | 远程服务器参数。 |
-| `env` | `{}` | 经由进程管理适配器传入的显式环境条目。 |
-| `extensionToLanguage` | 必填 | 小写、以点开头的扩展名到 LSP language id 的映射。 |
-| `initializationOptions` / `configuration` | `null` / `null` | 静态初始化选项和 `workspace/configuration` 应答。 |
-| `maxMessageBytes` | `16000000` | 从服务器接受的 LSP 消息大小上限。 |
-| `maxStderrBytes` | `1000000` | 保留的服务器原始 stderr 尾部上限。 |
-| `maxDocumentBytes` | `4000000` | 单次查询可打开的最大远程源文件。 |
-| `shutdownTimeoutMs` | `5000` | 协议优雅关闭预算。 |
-| `killGraceMs` | `2000` | 请求取消与 TERM 到 KILL 升级的宽限期。 |
-
-提供方 id 与命令必须非空；数值上限必须是正的安全整数，定时器取值不得超过 Node 的最大定时器延迟。设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个仅供所有者使用的私有代理，在远程解析 Node 和每个已配置服务器的可执行文件，再以原子方式注册所有提供方。
-
-## 远程协议与文件系统
-
-E2B 命令回调交付的是文本，而 LSP 按字节分帧。因此，已安装的代理会把服务器 stdout、stderr 和 stdin 的原始字节进行 base64 编码，封装为以换行分隔的 ASCII JSON 帧；宿主会验证并解码每一帧，再把字节交给共享的 `LspInstance` 协议引擎。`initialize.processId` 为 `null`，因为宿主与服务器不共享进程命名空间。
-
-每个提供方与规范化远程工作区的组合共享一个池化语言服务器进程。同一工作区的查询串行执行，不同工作区的查询并发运行。每项查询都会使用 `realpath` 规范化远程工作区与源文件，拒绝工作区外的路径，再由远程 helper 以不跟随最终符号链接的方式打开规范化源文件，并在同一个稳定描述符上完成验证与读取。该 helper 要求目标为普通文件，最多读取 `maxDocumentBytes + 1` 字节，随后执行严格的 UTF-8 解码。查询采用常规的临时 `didOpen`／请求／`didClose` 生命周期。传输失败会 dispose（资源释放）该实例，并在全新的远程进程上重试一次只读查询。
-
-进程管理适配器负责进程组和终止升级，因此取消与资源释放都会等待远程服务器完全停稳。宿主负责 LSP 请求 id、待完成请求、提供方队列和规范化结果。
-
-## 模型体验
-
-通过 `@deepseek-ai/dsh-tool-lsp` 间接影响模型；该包会公开规范化的语义导航与悬停结果，而不改变其面向模型的 schema。
-
-#### KV Cache 影响
-
-不会直接失效；请求前缀变更由 `dsh-tool-lsp` 负责。
-
-## 已知限制与暂缓工作
-
-- **仅支持已配置的服务器**：本包不会安装语言服务器、选择 preset，或把宿主工作区同步到 E2B。
-- **宿主协议状态不可重连**：保留沙箱并不会恢复提供方队列、JSON-RPC 请求、进程管理句柄或文档生命周期状态。
-- **SDK 仍会保留输出**：ASCII 分帧能保留协议字节，但 E2B 和进程管理适配器仍会在宿主内存中保留回调输出。
-- **沙箱策略归模板负责**：本提供方不会额外增加卷、快照、凭据或网络策略层。
diff --git a/packages/e2b/lsp-e2b/package.json b/packages/e2b/lsp-e2b/package.json
deleted file mode 100644
index 0671341f3c..0000000000
--- a/packages/e2b/lsp-e2b/package.json
+++ /dev/null
@@ -1,52 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-lsp-e2b",
-  "description": "E2B language-server provider for DeepSeek Harness",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
-  ],
-  "license": "BSD-3-Clause",
-  "peerDependencies": {
-    "@deepseek-ai/dsh-e2b": "^0.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-lsp": "^0.0.1",
-    "@deepseek-ai/dsh-lsp-local": "^0.0.1",
-    "@deepseek-ai/dsh-subprocess": "^0.0.1",
-    "@deepseek-ai/dsh-subprocess-e2b": "^0.0.1",
-    "@deepseek-ai/dsh-timeout": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
-  },
-  "dependencies": {
-    "schemastery": "^3.18.0"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-e2b": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-lsp": "workspace:^",
-    "@deepseek-ai/dsh-lsp-local": "workspace:^",
-    "@deepseek-ai/dsh-subprocess": "workspace:^",
-    "@deepseek-ai/dsh-subprocess-e2b": "workspace:^",
-    "@deepseek-ai/dsh-timeout": "workspace:^",
-    "cordis": "^4.0.0-rc.7"
-  }
-}
diff --git a/packages/e2b/lsp-e2b/src/index.ts b/packages/e2b/lsp-e2b/src/index.ts
deleted file mode 100644
index fa6b3729da..0000000000
--- a/packages/e2b/lsp-e2b/src/index.ts
+++ /dev/null
@@ -1,441 +0,0 @@
-/** E2B filesystem and process backend for the harness LSP capability seam. */
-
-import { Buffer } from 'node:buffer'
-import { posix } from 'node:path'
-import type { Context } from 'cordis'
-import z from 'schemastery'
-import {
-  FileType,
-  quoteE2BShellArg,
-  resolveE2BExecutable,
-} from '@deepseek-ai/dsh-e2b'
-import type { Sandbox } from '@deepseek-ai/dsh-e2b'
-import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
-import type { LspProvider, LspProviderQuery, LspQueryResult } from '@deepseek-ai/dsh-lsp'
-import { LspInstance } from '@deepseek-ai/dsh-lsp-local'
-import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
-import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
-import { LSP_PROXY_SOURCE } from './proxy-source.ts'
-import { E2BLspTransport } from './transport.ts'
-
-export { E2BLspTransport } from './transport.ts'
-
-/** Cordis plugin name. */
-export const name = 'lsp-e2b'
-/** Services required by the remote provider. */
-export const inject = ['e2b', 'lsp', 'subprocess']
-
-const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
-const DEFAULT_MAX_STDERR_BYTES = 1_000_000
-const DEFAULT_MAX_DOCUMENT_BYTES = 4_000_000
-const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000
-const DEFAULT_KILL_GRACE_MS = 2_000
-
-/* jscpd:ignore-start -- Loader requires each backend to expose its own statically walkable server schema. */
-/** One configured language server inside the shared E2B sandbox. */
-export interface LspE2BServerConfig {
-  /** Remote executable, absolute or resolved on the sandbox PATH. */
-  command: string
-  /** Lowercase leading-dot extension to LSP language id. */
-  extensionToLanguage: Record<string, string>
-  /** Remote executable arguments. */
-  args?: string[]
-  /** Explicit remote environment overrides. */
-  env?: Record<string, string>
-  /** Static `initialize` options. */
-  initializationOptions?: unknown
-  /** Static answer to every `workspace/configuration` item. */
-  configuration?: unknown
-  /** Largest LSP message accepted from the server. */
-  maxMessageBytes?: number
-  /** Largest remote stderr tail retained for diagnostics. */
-  maxStderrBytes?: number
-  /** Largest remote source opened for one query. */
-  maxDocumentBytes?: number
-  /** Graceful LSP shutdown budget. */
-  shutdownTimeoutMs?: number
-  /** Request-cancel and TERM-to-KILL grace. */
-  killGraceMs?: number
-}
-
-/** Plugin configuration. */
-export interface Config {
-  /** Non-empty provider-id to remote-server table. */
-  servers: Record<string, LspE2BServerConfig>
-}
-
-type ResolvedServerConfig = Required<LspE2BServerConfig>
-
-const ServerConfig: z<LspE2BServerConfig> = z.object({
-  command: z.string().required(),
-  args: z.array(String).default([]),
-  env: z.dict(String).default({}),
-  extensionToLanguage: z.dict(String).required(),
-  initializationOptions: z.any().default(null),
-  configuration: z.any().default(null),
-  maxMessageBytes: z.number().default(DEFAULT_MAX_MESSAGE_BYTES),
-  maxStderrBytes: z.number().default(DEFAULT_MAX_STDERR_BYTES),
-  maxDocumentBytes: z.number().default(DEFAULT_MAX_DOCUMENT_BYTES),
-  shutdownTimeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_SHUTDOWN_TIMEOUT_MS),
-  killGraceMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_KILL_GRACE_MS),
-})
-
-/** Schemastery plugin configuration. */
-export const Config: z<Config> = z.object({
-  servers: z.dict(ServerConfig).required(),
-})
-/* jscpd:ignore-end */
-
-interface RemoteSource {
-  canonicalPath: string
-  text: string
-}
-
-interface RemoteSourceReadResponse {
-  kind: 'ok' | 'not-file' | 'oversize' | 'grew' | 'open-error'
-  data?: string
-  size?: number
-  message?: string
-}
-
-const SOURCE_READER_SOURCE = String.raw`
-/* dsh-e2b-source-reader */
-const fs = require('node:fs')
-const path = process.argv[1]
-const maxBytes = Number(process.argv[2])
-let descriptor
-let response
-try {
-  descriptor = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK)
-  const info = fs.fstatSync(descriptor)
-  if (!info.isFile()) response = { kind: 'not-file' }
-  else if (info.size > maxBytes) response = { kind: 'oversize', size: info.size }
-  else {
-    const chunks = []
-    let total = 0
-    while (total <= maxBytes) {
-      const chunk = Buffer.allocUnsafe(Math.min(65536, maxBytes - total + 1))
-      const bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)
-      if (bytesRead === 0) break
-      chunks.push(chunk.subarray(0, bytesRead))
-      total += bytesRead
-    }
-    response = total > maxBytes
-      ? { kind: 'grew' }
-      : { kind: 'ok', data: Buffer.concat(chunks, total).toString('base64') }
-  }
-} catch (error) {
-  response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
-}
-if (descriptor !== undefined) fs.closeSync(descriptor)
-process.stdout.write(JSON.stringify(response))
-`
-
-function abortReason(signal: AbortSignal): unknown {
-  try {
-    signal.throwIfAborted()
-  } catch (error: unknown) {
-    return error
-  }
-  return new DOMException('The operation was aborted', 'AbortError')
-}
-
-function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
-  if (signal === undefined) return promise
-  // AbortSignal permits opaque reasons, and callers observe the exact reason.
-  // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
-  if (signal.aborted) return Promise.reject(abortReason(signal))
-  return new Promise<T>((resolve, reject) => {
-    const onAbort = (): void => {
-      cleanup()
-      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- Preserve the signal's exact opaque reason.
-      reject(abortReason(signal))
-    }
-    const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
-    signal.addEventListener('abort', onAbort, { once: true })
-    void promise.then(
-      (value) => { cleanup(); resolve(value) },
-      (error: unknown) => { cleanup(); reject(error instanceof Error ? error : new Error(String(error))) },
-    )
-  })
-}
-
-function validateServerConfig(providerId: string, config: ResolvedServerConfig): void {
-  if (config.command.length === 0) throw new Error(`lsp-e2b: servers.${providerId}.command must be non-empty`)
-  for (const name of ['maxMessageBytes', 'maxStderrBytes', 'maxDocumentBytes', 'shutdownTimeoutMs', 'killGraceMs'] as const) {
-    const value = config[name]
-    if (!Number.isSafeInteger(value) || value <= 0 || (name.endsWith('Ms') && value > MAX_TIMER_DELAY_MS)) {
-      throw new Error(`lsp-e2b: servers.${providerId}.${name} must be a positive safe integer${name.endsWith('Ms') ? ` no greater than ${MAX_TIMER_DELAY_MS}` : ''}`)
-    }
-  }
-}
-
-async function canonicalRemotePath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
-  signal?.throwIfAborted()
-  const result = await sandbox.commands.run(`realpath -e -- ${quoteE2BShellArg(path)}`, signal === undefined ? {} : { signal })
-  signal?.throwIfAborted()
-  const canonical = result.stdout.trim()
-  if (!posix.isAbsolute(canonical) || canonical.includes('\n')) throw new Error(`remote path ${JSON.stringify(path)} did not resolve canonically`)
-  return canonical
-}
-
-/**
- * Canonicalize and validate one workspace inside E2B.
- * @param sandbox - Shared sandbox that owns the workspace.
- * @param workspaceRoot - Remote workspace path supplied by the query.
- * @param signal - Optional query cancellation signal.
- * @returns The canonical remote directory path.
- */
-export async function canonicalizeE2BWorkspace(
-  sandbox: Sandbox,
-  workspaceRoot: string,
-  signal?: AbortSignal,
-): Promise<string> {
-  const canonical = await canonicalRemotePath(sandbox, workspaceRoot, signal)
-  const info = await sandbox.files.getInfo(canonical, signal === undefined ? {} : { signal })
-  signal?.throwIfAborted()
-  if (info.type !== FileType.DIR) throw new Error(`workspace root ${JSON.stringify(workspaceRoot)} is not a directory`)
-  return canonical
-}
-
-/**
- * Resolve, contain, and read one UTF-8 query source inside E2B.
- * @param sandbox - Shared sandbox that owns the source.
- * @param filePath - Absolute path or path relative to the canonical workspace.
- * @param workspace - Canonical remote workspace directory.
- * @param maxDocumentBytes - Maximum bytes read through the stable remote handle.
- * @param nodeExecutable - Resolved remote Node executable used by the bounded reader.
- * @param signal - Optional query cancellation signal.
- * @returns The canonical source path and decoded text.
- */
-export async function readE2BSource(
-  sandbox: Sandbox,
-  filePath: string,
-  workspace: string,
-  maxDocumentBytes: number,
-  nodeExecutable: string,
-  signal?: AbortSignal,
-): Promise<RemoteSource> {
-  const requested = posix.isAbsolute(filePath) ? filePath : posix.resolve(workspace, filePath)
-  const canonicalPath = await canonicalRemotePath(sandbox, requested, signal)
-  const relative = posix.relative(workspace, canonicalPath)
-  if (relative === '..' || relative.startsWith('../') || posix.isAbsolute(relative)) {
-    throw new Error(`source ${JSON.stringify(filePath)} resolves outside the workspace`)
-  }
-  const command = [
-    quoteE2BShellArg(nodeExecutable),
-    '--input-type=commonjs',
-    '-e',
-    quoteE2BShellArg(SOURCE_READER_SOURCE),
-    quoteE2BShellArg(canonicalPath),
-    String(maxDocumentBytes),
-  ].join(' ')
-  const result = await sandbox.commands.run(command, signal === undefined ? {} : { signal })
-  signal?.throwIfAborted()
-  let response: RemoteSourceReadResponse
-  try {
-    response = JSON.parse(result.stdout) as RemoteSourceReadResponse
-  } catch (error: unknown) {
-    throw new Error(`source ${JSON.stringify(filePath)} reader returned an invalid response`, { cause: error })
-  }
-  if (response.kind === 'not-file') throw new Error(`source ${JSON.stringify(filePath)} is not a regular file`)
-  if (response.kind === 'oversize' && Number.isSafeInteger(response.size)) {
-    throw new Error(`source ${JSON.stringify(filePath)} is ${response.size} bytes, over the ${maxDocumentBytes}-byte limit`)
-  }
-  if (response.kind === 'grew') {
-    throw new Error(`source ${JSON.stringify(filePath)} grew past the ${maxDocumentBytes}-byte limit while reading`)
-  }
-  if (response.kind === 'open-error' && typeof response.message === 'string') {
-    throw new Error(`source ${JSON.stringify(filePath)} could not be opened safely: ${response.message}`)
-  }
-  if (response.kind !== 'ok' || typeof response.data !== 'string') {
-    throw new Error(`source ${JSON.stringify(filePath)} reader returned an invalid response`)
-  }
-  const bytes = Buffer.from(response.data, 'base64')
-  if (bytes.toString('base64') !== response.data || bytes.length > maxDocumentBytes) {
-    throw new Error(`source ${JSON.stringify(filePath)} reader returned invalid bounded bytes`)
-  }
-  let text: string
-  try {
-    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
-  } catch (error: unknown) {
-    throw new Error(`source ${JSON.stringify(filePath)} is not valid UTF-8 text`, { cause: error })
-  }
-  return { canonicalPath, text }
-}
-
-/**
- * Encode one absolute remote Linux path as a host-independent file URI.
- * @param path - Canonical POSIX path inside E2B.
- * @returns The equivalent percent-encoded file URI.
- */
-export function e2bFileUri(path: string): string {
-  if (!posix.isAbsolute(path)) throw new Error(`lsp-e2b: expected an absolute remote path, received ${JSON.stringify(path)}`)
-  return `file://${path.split('/').map(segment => encodeURIComponent(segment)).join('/')}`
-}
-
-/* jscpd:ignore-start -- Provider identity mirrors the seam while remote source and process ownership stay local. */
-/** One pooled remote provider with an isolated server per canonical workspace. */
-export class E2BLspProvider implements LspProvider {
-  readonly id: LspProviderId
-  readonly extensionToLanguage: Readonly<Record<string, string>>
-  private readonly instances = new Map<string, LspInstance>()
-  private readonly queues = new Map<string, Promise<void>>()
-  private disposed = false
-
-  constructor(
-    providerId: string,
-    private readonly sandbox: Sandbox,
-    private readonly subprocess: E2BSubprocessService,
-    private readonly config: ResolvedServerConfig,
-    private readonly executable: string,
-    private readonly nodeExecutable: string,
-    private readonly proxyPath: string,
-  ) {
-    this.id = LspProviderId(providerId)
-    this.extensionToLanguage = config.extensionToLanguage
-  }
-  /* jscpd:ignore-end */
-
-  async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
-    this.assertActive(signal)
-    const workspace = await canonicalizeE2BWorkspace(this.sandbox, request.workspaceRoot, signal)
-    this.assertActive(signal)
-    return this.enqueue(workspace, signal, async () => {
-      this.assertActive(signal)
-      const source = await readE2BSource(
-        this.sandbox,
-        request.filePath,
-        workspace,
-        this.config.maxDocumentBytes,
-        this.nodeExecutable,
-        signal,
-      )
-      this.assertActive(signal)
-      let instance = this.instanceFor(workspace)
-      try {
-        return await instance.query(request, source, signal)
-      } catch (error: unknown) {
-        if (!instance.isTransportFailure(error)) throw error
-        await instance.dispose()
-        this.evict(workspace, instance)
-        this.assertActive(signal)
-        instance = this.instanceFor(workspace)
-        return await instance.query(request, source, signal)
-      } finally {
-        if (instance.dead) {
-          await instance.dispose()
-          this.evict(workspace, instance)
-        }
-      }
-    })
-  }
-
-  /* jscpd:ignore-start -- Queue and pooling semantics are shared; transport failure and disposal identities differ. */
-  /** Stop accepting work and await every remote server and queued query. */
-  async disposeAll(): Promise<void> {
-    this.disposed = true
-    const instances = [...this.instances.values()]
-    const queues = [...this.queues.values()]
-    this.instances.clear()
-    await Promise.all([...instances.map(instance => instance.dispose()), ...queues])
-    this.queues.clear()
-  }
-
-  private assertActive(signal?: AbortSignal): void {
-    if (this.disposed) throw new LspError('lsp-e2b provider is disposed', 'LSP_DISPOSED')
-    signal?.throwIfAborted()
-  }
-
-  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
-    const previous = this.queues.get(workspace) ?? Promise.resolve()
-    const result = abortable(previous, signal).then(run)
-    const tail = previous.then(() => result).then(() => undefined, () => undefined)
-    this.queues.set(workspace, tail)
-    void tail.then(() => { if (this.queues.get(workspace) === tail) this.queues.delete(workspace) })
-    return result
-  }
-
-  private instanceFor(workspace: string): LspInstance {
-    this.assertActive()
-    const existing = this.instances.get(workspace)
-    if (existing !== undefined) return existing
-    const created = this.createInstance(workspace)
-    this.instances.set(workspace, created)
-    return created
-  }
-  /* jscpd:ignore-end */
-
-  private createInstance(workspace: string): LspInstance {
-    return new LspInstance({
-      command: this.executable,
-      args: this.config.args,
-      cwd: workspace,
-      env: this.config.env,
-      configuration: this.config.configuration,
-      initializationOptions: this.config.initializationOptions,
-      maxMessageBytes: this.config.maxMessageBytes,
-      maxStderrBytes: this.config.maxStderrBytes,
-      shutdownTimeoutMs: this.config.shutdownTimeoutMs,
-      killGraceMs: this.config.killGraceMs,
-      clientProcessId: null,
-      pathToFileUri: e2bFileUri,
-    }, (spec: SubprocessSpawnSpec) => {
-      const originalArgv = Buffer.from(JSON.stringify(spec.argv)).toString('base64')
-      const inner = this.subprocess.spawn({
-        ...spec,
-        argv: [this.nodeExecutable, this.proxyPath, originalArgv],
-        stdio: {
-          stdin: 'pipe',
-          stdout: 'pipe',
-          stderr: { maxBytes: this.config.maxStderrBytes },
-        },
-      })
-      const rawBound = Math.max(this.config.maxMessageBytes, this.config.maxStderrBytes)
-      return new E2BLspTransport(inner, rawBound * 2 + 1024, this.config.maxStderrBytes)
-    })
-  }
-
-  private evict(workspace: string, instance: LspInstance): void {
-    if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
-  }
-}
-
-/** Install the proxy, resolve remote commands, and atomically register providers. */
-export async function apply(ctx: Context, config: Config): Promise<void> {
-  if (!(ctx.subprocess instanceof E2BSubprocessService)) {
-    throw new Error('lsp-e2b requires @deepseek-ai/dsh-subprocess-e2b as ctx.subprocess')
-  }
-  const subprocess = ctx.subprocess
-  const entries = Object.entries(config.servers)
-  if (entries.length === 0) throw new Error('lsp-e2b: servers must contain at least one server')
-  const sandbox = await ctx.e2b.getSandbox()
-  const proxyPath = posix.join(ctx.e2b.runtimeRoot, 'lsp-stdio-proxy.mjs')
-  await sandbox.files.write([{ path: proxyPath, data: LSP_PROXY_SOURCE }])
-  await sandbox.commands.run(`chmod 600 -- ${quoteE2BShellArg(proxyPath)}`)
-  const nodeExecutable = await resolveE2BExecutable(sandbox, 'node')
-  const providers = await Promise.all(entries.map(async ([providerId, raw]) => {
-    if (providerId.trim() === '') throw new Error('lsp-e2b: server ids must be non-empty strings')
-    const resolved = raw as ResolvedServerConfig
-    validateServerConfig(providerId, resolved)
-    const executable = await resolveE2BExecutable(sandbox, resolved.command)
-    return new E2BLspProvider(providerId, sandbox, subprocess, resolved, executable, nodeExecutable, proxyPath)
-  }))
-
-  /* jscpd:ignore-start -- Every provider table publishes atomically through the same registry contract. */
-  ctx.effect(() => {
-    const disposers: Array<() => void> = []
-    try {
-      for (const provider of providers) disposers.push(ctx.lsp.registerProvider(provider))
-    } catch (error: unknown) {
-      for (const dispose of disposers.reverse()) dispose()
-      throw error
-    }
-    return async () => {
-      for (const dispose of disposers.reverse()) dispose()
-      await Promise.all(providers.map(provider => provider.disposeAll()))
-    }
-  }, 'lsp-e2b.registerProviders')
-  /* jscpd:ignore-end */
-}
diff --git a/packages/e2b/lsp-e2b/src/invariant.ts b/packages/e2b/lsp-e2b/src/invariant.ts
deleted file mode 100644
index 129cf0a6d4..0000000000
--- a/packages/e2b/lsp-e2b/src/invariant.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-lsp-e2b`. */
-
-/* jscpd:ignore-start */
-import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-lsp-e2b'
-
-/** Cordis companion plugin name. */
-export const name = 'lsp-e2b-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/** No runtime invariant: the LSP registry owns provider publication. */
-const install: InvariantInstaller = () => {}
-
-/** Register this package's invariant companion. */
-export const apply = (ctx: Context): Promise<() => void> =>
-  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-/* jscpd:ignore-end */
diff --git a/packages/e2b/lsp-e2b/src/proxy-source.ts b/packages/e2b/lsp-e2b/src/proxy-source.ts
deleted file mode 100644
index 5b6fe42d07..0000000000
--- a/packages/e2b/lsp-e2b/src/proxy-source.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-/** Dependency-free remote stdio proxy installed inside the E2B sandbox. */
-
-/**
- * Node program that base64-frames raw child stdio so E2B's text callbacks
- * never decode the language server's byte stream.
- */
-export const LSP_PROXY_SOURCE = String.raw`import { Buffer } from 'node:buffer'
-import { spawn } from 'node:child_process'
-import { createInterface } from 'node:readline'
-
-const emit = (message) => {
-  process.stdout.write(Buffer.from(JSON.stringify(message)).toString('base64') + '\n')
-}
-
-let argv
-try {
-  argv = JSON.parse(Buffer.from(process.argv[2], 'base64').toString('utf8'))
-  if (!Array.isArray(argv) || argv.length === 0 || argv.some(value => typeof value !== 'string')) throw new Error('invalid argv')
-} catch (error) {
-  process.stderr.write('lsp-e2b proxy argv error: ' + String(error) + '\n')
-  process.exitCode = 125
-  process.stdin.destroy()
-}
-
-if (argv) {
-  const child = spawn(argv[0], argv.slice(1), { stdio: ['pipe', 'pipe', 'pipe'], env: process.env })
-  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
-  child.stdout.on('data', data => { emit({ type: 'stdout', data: data.toString('base64') }) })
-  child.stderr.on('data', data => { emit({ type: 'stderr', data: data.toString('base64') }) })
-  child.on('error', error => {
-    emit({ type: 'stderr', data: Buffer.from('language server spawn failed: ' + error.message).toString('base64') })
-  })
-  child.on('close', (code, signal) => {
-    emit({ type: 'exit', code, signal })
-    input.close()
-    process.stdin.destroy()
-    process.exitCode = code === null ? 1 : code
-  })
-  input.on('line', line => {
-    input.pause()
-    try {
-      const message = JSON.parse(Buffer.from(line, 'base64').toString('utf8'))
-      if (!message || message.type !== 'stdin' || typeof message.data !== 'string') throw new Error('invalid stdin frame')
-      const data = Buffer.from(message.data, 'base64')
-      if (data.toString('base64') !== message.data) throw new Error('invalid stdin base64')
-      if (child.stdin.write(data)) input.resume()
-      else child.stdin.once('drain', () => { input.resume() })
-    } catch (error) {
-      process.stderr.write('lsp-e2b proxy stdin error: ' + String(error) + '\n')
-      child.kill('SIGTERM')
-    }
-  })
-  input.on('close', () => { child.stdin.end() })
-}
-`
diff --git a/packages/e2b/lsp-e2b/src/transport.ts b/packages/e2b/lsp-e2b/src/transport.ts
deleted file mode 100644
index ddd3445db8..0000000000
--- a/packages/e2b/lsp-e2b/src/transport.ts
+++ /dev/null
@@ -1,183 +0,0 @@
-/** Byte-faithful stdio transport over an E2B subprocess and ASCII/base64 frames. */
-
-import { Buffer } from 'node:buffer'
-import { PassThrough, Writable } from 'node:stream'
-import { E2BFrameDecoder, encodeE2BFrame } from '@deepseek-ai/dsh-e2b'
-import type {
-  SubprocessHandle,
-  SubprocessOutcome,
-  SubprocessOutputRead,
-  SubprocessOutputReader,
-} from '@deepseek-ai/dsh-subprocess'
-
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error))
-}
-
-class ByteTailReader implements SubprocessOutputReader {
-  private chunks: Buffer[] = []
-  private totalBytes = 0
-  private retainedBytes = 0
-  private dropped = false
-
-  constructor(private readonly maxBytes: number) {}
-
-  append(data: Buffer): void {
-    if (data.length === 0) return
-    this.chunks.push(data)
-    this.totalBytes += data.length
-    this.retainedBytes += data.length
-    while (this.retainedBytes > this.maxBytes && this.chunks.length > 0) {
-      const first = this.chunks[0] as Buffer
-      const excess = this.retainedBytes - this.maxBytes
-      if (first.length <= excess) {
-        this.chunks.shift()
-        this.retainedBytes -= first.length
-      } else {
-        this.chunks[0] = first.subarray(excess)
-        this.retainedBytes -= excess
-      }
-      this.dropped = true
-    }
-  }
-
-  readFrom(fromByte: number): SubprocessOutputRead {
-    if (!Number.isSafeInteger(fromByte) || fromByte < 0) {
-      throw new Error('subprocess output offset must be a non-negative safe integer')
-    }
-    const retainedStart = this.totalBytes - this.retainedBytes
-    const lossy = fromByte < retainedStart
-    const start = lossy ? 0 : Math.min(this.retainedBytes, fromByte - retainedStart)
-    const bytes = Buffer.concat(this.chunks).subarray(start)
-    return { text: bytes.toString('utf8'), nextOffset: this.totalBytes, lossy: lossy || this.dropped && fromByte === 0 }
-  }
-}
-
-class FramedInput extends Writable {
-  constructor(private readonly target: Writable) {
-    super()
-    target.on('error', (error: Error) => { this.destroy(error) })
-  }
-
-  override _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
-    this.target.write(encodeE2BFrame({ type: 'stdin', data: chunk.toString('base64') }), callback)
-  }
-
-  override _final(callback: (error?: Error | null) => void): void {
-    this.target.end(callback)
-  }
-}
-
-/** Subprocess handle that decodes a remote proxy's stdout/stderr byte frames. */
-export class E2BLspTransport implements SubprocessHandle {
-  readonly stdin: Writable
-  readonly stdout = new PassThrough()
-  readonly stderr = undefined
-  readonly collected: SubprocessHandle['collected']
-  readonly done: Promise<SubprocessOutcome>
-  private readonly stderrTail: ByteTailReader
-  private readonly decoder: E2BFrameDecoder
-  private failed: Error | undefined
-
-  /**
-   * @param inner - E2B subprocess running the installed proxy.
-   * @param maxFrameBytes - Maximum decoded proxy frame size.
-   * @param maxStderrBytes - Retained raw language-server stderr tail.
-   */
-  constructor(
-    private readonly inner: SubprocessHandle,
-    maxFrameBytes: number,
-    maxStderrBytes: number,
-  ) {
-    if (inner.stdin === undefined || inner.stdout === undefined) {
-      inner.terminate()
-      throw new Error('lsp-e2b: proxy subprocess dropped a piped stream')
-    }
-    this.stdin = new FramedInput(inner.stdin)
-    this.stderrTail = new ByteTailReader(maxStderrBytes)
-    this.collected = { stderr: this.stderrTail }
-    this.decoder = new E2BFrameDecoder(maxFrameBytes)
-    inner.stdout.on('data', (chunk: Buffer) => { this.onProxyData(chunk) })
-    inner.stdout.on('error', (error: Error) => { this.fail(error) })
-    this.done = inner.done.then(
-      (outcome) => {
-        this.finishFrames()
-        this.captureProxyStderr()
-        this.stdout.end()
-        if (this.failed !== undefined) throw this.failed
-        return outcome
-      },
-      (error: unknown) => {
-        this.captureProxyStderr()
-        this.stdout.end()
-        throw error
-      },
-    )
-    void this.done.catch(() => {})
-  }
-
-  get pid(): number {
-    return this.inner.pid
-  }
-
-  terminate(): void {
-    this.inner.terminate()
-  }
-
-  async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    return await this.inner.waitForExit(signal)
-  }
-
-  private onProxyData(chunk: Buffer): void {
-    if (this.failed !== undefined) return
-    let frames: unknown[]
-    try {
-      frames = this.decoder.push(chunk.toString('utf8'))
-    } catch (error: unknown) {
-      this.fail(asError(error))
-      return
-    }
-    for (const frame of frames) this.dispatch(frame)
-  }
-
-  private dispatch(frame: unknown): void {
-    if (typeof frame !== 'object' || frame === null) {
-      this.fail(new Error('lsp-e2b: proxy emitted a malformed frame'))
-      return
-    }
-    const record = frame as Record<string, unknown>
-    if (record.type === 'exit' && (record.code === null || typeof record.code === 'number') && (record.signal === null || typeof record.signal === 'string')) return
-    if ((record.type !== 'stdout' && record.type !== 'stderr') || typeof record.data !== 'string') {
-      this.fail(new Error('lsp-e2b: proxy emitted a malformed frame'))
-      return
-    }
-    const data = Buffer.from(record.data, 'base64')
-    if (data.toString('base64') !== record.data) {
-      this.fail(new Error('lsp-e2b: proxy emitted invalid base64'))
-      return
-    }
-    if (record.type === 'stdout') this.stdout.write(data)
-    else this.stderrTail.append(data)
-  }
-
-  private finishFrames(): void {
-    if (this.failed !== undefined) return
-    try {
-      this.decoder.finish()
-    } catch (error: unknown) {
-      this.fail(asError(error))
-    }
-  }
-
-  private captureProxyStderr(): void {
-    const diagnostic = this.inner.collected.stderr?.readFrom(0).text
-    if (diagnostic !== undefined && diagnostic.length > 0) this.stderrTail.append(Buffer.from(diagnostic))
-  }
-
-  private fail(error: Error): void {
-    if (this.failed !== undefined) return
-    this.failed = error
-    this.inner.terminate()
-    this.stdout.end()
-  }
-}
diff --git a/packages/e2b/lsp-e2b/tests/provider.spec.ts b/packages/e2b/lsp-e2b/tests/provider.spec.ts
deleted file mode 100644
index dc92053e4a..0000000000
--- a/packages/e2b/lsp-e2b/tests/provider.spec.ts
+++ /dev/null
@@ -1,418 +0,0 @@
-import { PassThrough } from 'node:stream'
-import { Context } from 'cordis'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import {
-  FileType,
-  type Sandbox,
-} from '@deepseek-ai/dsh-e2b'
-import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
-import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-
-const mockedLsp = vi.hoisted(() => {
-  interface Plan {
-    query?: (...args: unknown[]) => unknown
-    transportFailure?: unknown
-    dead?: boolean
-    deadAfterQuery?: boolean
-    disposeError?: unknown
-  }
-
-  class FakeLspInstance {
-    static readonly instances: FakeLspInstance[] = []
-    static readonly plans: Plan[] = []
-    readonly plan: Plan
-    readonly transport: unknown
-    readonly queries: unknown[][] = []
-    dead: boolean
-    disposals = 0
-
-    constructor(
-      readonly spec: Record<string, unknown>,
-      spawner: (spec: SubprocessSpawnSpec) => unknown,
-    ) {
-      this.plan = FakeLspInstance.plans.shift() ?? {}
-      this.dead = this.plan.dead === true
-      this.transport = spawner({
-        argv: [String(spec.command), ...(spec.args as string[])],
-        cwd: String(spec.cwd),
-        env: spec.env as Record<string, string>,
-        graceMs: Number(spec.killGraceMs),
-        stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: Number(spec.maxStderrBytes) } },
-      })
-      FakeLspInstance.instances.push(this)
-    }
-
-    async query(...args: unknown[]): Promise<unknown> {
-      this.queries.push(args)
-      const result = await Promise.resolve(this.plan.query?.(...args) ?? { kind: 'hover', hover: null })
-      if (this.plan.deadAfterQuery === true) this.dead = true
-      return result
-    }
-
-    isTransportFailure(error: unknown): boolean {
-      return error === this.plan.transportFailure
-    }
-
-    async dispose(): Promise<void> {
-      this.disposals += 1
-      this.dead = true
-      if (this.plan.disposeError !== undefined) throw this.plan.disposeError
-    }
-  }
-
-  return { FakeLspInstance }
-})
-
-vi.mock('@deepseek-ai/dsh-lsp-local', () => ({ LspInstance: mockedLsp.FakeLspInstance }))
-
-import {
-  E2BLspProvider,
-  apply,
-  canonicalizeE2BWorkspace,
-  e2bFileUri,
-  readE2BSource,
-} from '@deepseek-ai/dsh-lsp-e2b'
-import type { LspE2BServerConfig } from '@deepseek-ai/dsh-lsp-e2b'
-import * as E2BLspInvariant from '../src/invariant.ts'
-import InvariantService from '@deepseek-ai/dsh-invariants'
-
-class FakeInnerHandle implements SubprocessHandle {
-  readonly pid = 777
-  readonly stdin = new PassThrough()
-  readonly stdout = new PassThrough()
-  readonly stderr = undefined
-  readonly collected = { stderr: { readFrom: () => ({ text: '', nextOffset: 0, lossy: false }) } }
-  readonly done = Promise.resolve({ exitCode: 0, signal: null })
-  terminate(): void {}
-  async waitForExit(): Promise<boolean> { return true }
-}
-
-class FakeRemote {
-  readonly writes: Array<Array<{ path: string; data: string }>> = []
-  readonly commands: string[] = []
-  readonly infos = new Map<string, { type: FileType; size: number }>()
-  readonly contents = new Map<string, Uint8Array>()
-  readonly realpaths = new Map<string, string>()
-  forcedRealpath: string | undefined
-  readerResponse: unknown
-  readerOutput: string | undefined
-
-  constructor() {
-    this.infos.set('/workspace', { type: FileType.DIR, size: 0 })
-    this.infos.set('/workspace/file.ts', { type: FileType.FILE, size: 12 })
-    this.contents.set('/workspace/file.ts', Buffer.from('const x = 1'))
-    this.readerResponse = { kind: 'ok', data: Buffer.from('const x = 1').toString('base64') }
-  }
-
-  readonly sandbox = {
-    commands: {
-      run: async (command: string) => {
-        this.commands.push(command)
-        if (command.startsWith('realpath ')) {
-          const match = /'([^']*)'$/.exec(command)
-          const requested = match?.[1] ?? ''
-          return { exitCode: 0, stdout: `${this.forcedRealpath ?? this.realpaths.get(requested) ?? requested}\n`, stderr: '' }
-        }
-        if (command.includes('dsh-e2b-source-reader')) {
-          return { exitCode: 0, stdout: this.readerOutput ?? JSON.stringify(this.readerResponse), stderr: '' }
-        }
-        if (command.startsWith('command -v')) return { exitCode: 0, stdout: '/usr/bin/node\n', stderr: '' }
-        return { exitCode: 0, stdout: '', stderr: '' }
-      },
-    },
-    files: {
-      write: async (files: Array<{ path: string; data: string }>) => {
-        this.writes.push(files)
-        return files.map(() => ({}))
-      },
-      getInfo: async (path: string) => {
-        const info = this.infos.get(path)
-        if (info === undefined) throw new Error(`missing info for ${path}`)
-        return info
-      },
-      read: async (path: string) => this.contents.get(path) ?? new Uint8Array(),
-    },
-  } as unknown as Sandbox
-}
-
-function subprocess(spawn = vi.fn((_spec: SubprocessSpawnSpec) => new FakeInnerHandle())): E2BSubprocessService {
-  const service = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
-  Object.defineProperty(service, 'spawn', { value: spawn })
-  return service
-}
-
-function server(overrides: Partial<LspE2BServerConfig> = {}): Required<LspE2BServerConfig> {
-  return {
-    command: '/usr/bin/server', args: ['--stdio'], env: {},
-    extensionToLanguage: { '.ts': 'typescript' },
-    initializationOptions: null, configuration: null,
-    maxMessageBytes: 1_024, maxStderrBytes: 128, maxDocumentBytes: 1_024,
-    shutdownTimeoutMs: 100, killGraceMs: 50,
-    ...overrides,
-  }
-}
-
-function provider(remote = new FakeRemote(), service = subprocess()): E2BLspProvider {
-  return new E2BLspProvider(
-    'fixture', remote.sandbox, service, server(),
-    '/usr/bin/server', '/usr/bin/node', '/workspace/.dsh-e2b/lsp-proxy.mjs',
-  )
-}
-
-function query(workspaceRoot = '/workspace') {
-  return {
-    operation: 'hover' as const,
-    filePath: 'file.ts',
-    position: { line: 0, character: 1 },
-    workspaceRoot,
-    languageId: 'typescript',
-  }
-}
-
-beforeEach(() => {
-  mockedLsp.FakeLspInstance.instances.length = 0
-  mockedLsp.FakeLspInstance.plans.length = 0
-})
-
-describe('E2B LSP filesystem boundary', () => {
-  it('canonicalizes a directory and reads a contained UTF-8 source', async () => {
-    const remote = new FakeRemote()
-    await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace')).resolves.toBe('/workspace')
-    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, '/usr/bin/node')).resolves.toEqual({
-      canonicalPath: '/workspace/file.ts',
-      text: 'const x = 1',
-    })
-    await expect(readE2BSource(remote.sandbox, '/workspace/file.ts', '/workspace', 1_024, '/usr/bin/node')).resolves.toMatchObject({
-      canonicalPath: '/workspace/file.ts',
-    })
-    const signal = new AbortController().signal
-    await expect(canonicalizeE2BWorkspace(remote.sandbox, '/workspace', signal)).resolves.toBe('/workspace')
-    await expect(readE2BSource(remote.sandbox, 'file.ts', '/workspace', 1_024, '/usr/bin/node', signal)).resolves.toMatchObject({
-      canonicalPath: '/workspace/file.ts',
-    })
-  })
-
-  it('rejects malformed workspaces and source containment/type/size/encoding failures', async () => {
-    const malformed = new FakeRemote()
-    malformed.forcedRealpath = 'relative'
-    await expect(canonicalizeE2BWorkspace(malformed.sandbox, '/workspace')).rejects.toThrow('did not resolve canonically')
-    malformed.forcedRealpath = '/workspace\nother'
-    await expect(canonicalizeE2BWorkspace(malformed.sandbox, '/workspace')).rejects.toThrow('did not resolve canonically')
-
-    const notDirectory = new FakeRemote()
-    notDirectory.infos.set('/workspace', { type: FileType.FILE, size: 0 })
-    await expect(canonicalizeE2BWorkspace(notDirectory.sandbox, '/workspace')).rejects.toThrow('not a directory')
-
-    const outside = new FakeRemote()
-    outside.realpaths.set('/workspace/file.ts', '/outside/file.ts')
-    await expect(readE2BSource(outside.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('outside the workspace')
-
-    const notFile = new FakeRemote()
-    notFile.readerResponse = { kind: 'not-file' }
-    await expect(readE2BSource(notFile.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('not a regular file')
-
-    const tooLarge = new FakeRemote()
-    tooLarge.readerResponse = { kind: 'oversize', size: 21 }
-    await expect(readE2BSource(tooLarge.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('over the 20-byte limit')
-
-    const grew = new FakeRemote()
-    grew.readerResponse = { kind: 'grew' }
-    await expect(readE2BSource(grew.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('grew past')
-
-    const invalid = new FakeRemote()
-    invalid.readerResponse = { kind: 'ok', data: Buffer.from([0xff]).toString('base64') }
-    await expect(readE2BSource(invalid.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('not valid UTF-8')
-
-    const swapped = new FakeRemote()
-    swapped.readerResponse = { kind: 'open-error', message: 'ELOOP: symbolic link encountered' }
-    await expect(readE2BSource(swapped.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('opened safely')
-
-    const malformedReader = new FakeRemote()
-    malformedReader.readerResponse = { kind: 'ok', data: '*' }
-    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid bounded bytes')
-    malformedReader.readerResponse = { kind: 'oversize', size: 'large' }
-    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid response')
-    malformedReader.readerOutput = '{'
-    await expect(readE2BSource(malformedReader.sandbox, 'file.ts', '/workspace', 20, '/usr/bin/node')).rejects.toThrow('invalid response')
-
-    await expect(canonicalizeE2BWorkspace(new FakeRemote().sandbox, '/workspace', AbortSignal.abort('stop')))
-      .rejects.toBe('stop')
-  })
-})
-
-describe('E2BLspProvider pooling and lifecycle', () => {
-  it('reuses one canonical-workspace instance and constructs the remote proxy transport', async () => {
-    const spawn = vi.fn((_spec: SubprocessSpawnSpec) => new FakeInnerHandle())
-    const remote = new FakeRemote()
-    mockedLsp.FakeLspInstance.plans.push({ query: async () => ({ kind: 'hover', hover: { contents: 'ok' } }) })
-    const current = provider(remote, subprocess(spawn))
-
-    await expect(current.query(query())).resolves.toEqual({ kind: 'hover', hover: { contents: 'ok' } })
-    await expect(current.query(query())).resolves.toEqual({ kind: 'hover', hover: { contents: 'ok' } })
-    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(1)
-    expect(mockedLsp.FakeLspInstance.instances[0]?.spec).toMatchObject({ clientProcessId: null, cwd: '/workspace' })
-    expect(e2bFileUri('/workspace/a b#c.ts')).toBe('file:///workspace/a%20b%23c.ts')
-    expect(() => e2bFileUri('relative.ts')).toThrow('absolute remote path')
-    const pathToFileUri = mockedLsp.FakeLspInstance.instances[0]?.spec.pathToFileUri as (path: string) => string
-    expect(pathToFileUri('/workspace/a b#c.ts')).toBe('file:///workspace/a%20b%23c.ts')
-    expect(spawn).toHaveBeenCalledWith(expect.objectContaining({
-      argv: ['/usr/bin/node', '/workspace/.dsh-e2b/lsp-proxy.mjs', expect.any(String)],
-      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 128 } },
-    }))
-    expect(current.id).toBe('fixture')
-    expect(current.extensionToLanguage).toEqual({ '.ts': 'typescript' })
-    await current.disposeAll()
-    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
-  })
-
-  it('replaces one transport failure, but preserves ordinary query errors', async () => {
-    const transportFailure = new Error('transport failed')
-    mockedLsp.FakeLspInstance.plans.push(
-      { transportFailure, query: async () => { throw transportFailure } },
-      { query: async () => ({ kind: 'hover', hover: { contents: 'retried' } }) },
-    )
-    const retried = provider()
-    await expect(retried.query(query())).resolves.toMatchObject({ hover: { contents: 'retried' } })
-    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
-    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(2)
-
-    const ordinary = new Error('ordinary failure')
-    mockedLsp.FakeLspInstance.plans.push(
-      { query: async () => { throw ordinary }, dead: true },
-      { query: async () => ({ kind: 'hover', hover: null }) },
-    )
-    const failed = provider()
-    await expect(failed.query(query())).rejects.toBe(ordinary)
-    await expect(failed.query(query())).resolves.toMatchObject({ kind: 'hover' })
-  })
-
-  it('evicts a server that dies after a successful query', async () => {
-    mockedLsp.FakeLspInstance.plans.push(
-      { deadAfterQuery: true, query: async () => ({ kind: 'hover', hover: null }) },
-      { query: async () => ({ kind: 'hover', hover: null }) },
-    )
-    const current = provider()
-    await current.query(query())
-    await current.query(query())
-    expect(mockedLsp.FakeLspInstance.instances).toHaveLength(2)
-    expect(mockedLsp.FakeLspInstance.instances[0]?.disposals).toBe(1)
-  })
-
-  it('serializes a workspace queue, observes queued abort, and awaits work on disposal', async () => {
-    const first = Promise.withResolvers<unknown>()
-    mockedLsp.FakeLspInstance.plans.push({ query: () => first.promise })
-    const current = provider()
-    const running = current.query(query())
-    const controller = new AbortController()
-    const queued = current.query(query(), controller.signal)
-    await new Promise(resolve => setImmediate(resolve))
-    controller.abort('queued stop')
-    await expect(queued).rejects.toBe('queued stop')
-
-    const disposing = current.disposeAll()
-    first.resolve({ kind: 'hover', hover: null })
-    await expect(running).resolves.toMatchObject({ kind: 'hover' })
-    await disposing
-    await expect(current.query(query())).rejects.toMatchObject({ code: 'LSP_DISPOSED' })
-  })
-
-  it('covers pre-abort, synthetic abort, resolve, and rejection in the queue race', async () => {
-    const current = provider()
-    const internal = current as unknown as {
-      queues: Map<string, Promise<void>>
-      enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T>
-    }
-    await expect(internal.enqueue('pre', AbortSignal.abort('pre-stop'), async () => 'unused')).rejects.toBe('pre-stop')
-
-    const signal = new AbortController().signal
-    await expect(internal.enqueue('resolve', signal, async () => 'ok')).resolves.toBe('ok')
-
-    const failure = new Error('queue failed')
-    const rejected = Promise.reject<undefined>(failure)
-    void rejected.catch(() => {})
-    internal.queues.set('reject', rejected)
-    await expect(internal.enqueue('reject', signal, async () => 'unused')).rejects.toBe(failure)
-
-    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- Exercise normalization at the promise boundary.
-    const opaque = Promise.reject<undefined>('opaque queue failure')
-    void opaque.catch(() => {})
-    internal.queues.set('opaque', opaque)
-    await expect(internal.enqueue('opaque', signal, async () => 'unused')).rejects.toEqual(new Error('opaque queue failure'))
-
-    const synthetic = {
-      aborted: false,
-      reason: undefined,
-      throwIfAborted() {},
-      addEventListener(_type: string, listener: () => void) { listener() },
-      removeEventListener() {},
-    } as unknown as AbortSignal
-    await expect(internal.enqueue('synthetic', synthetic, async () => 'unused')).rejects.toMatchObject({ name: 'AbortError' })
-    await current.disposeAll()
-  })
-})
-
-describe('lsp-e2b plugin composition', () => {
-  function pluginContext(
-    remote: FakeRemote,
-    service: E2BSubprocessService,
-    registerProvider = vi.fn(() => vi.fn()),
-  ) {
-    const effects: Array<() => void | Promise<void>> = []
-    const ctx = {
-      subprocess: service,
-      e2b: {
-        runtimeRoot: '/workspace/.dsh-e2b',
-        getSandbox: async () => remote.sandbox,
-      },
-      lsp: { registerProvider },
-      effect: (callback: () => (() => void | Promise<void>)) => { effects.push(callback()) },
-    } as unknown as Context
-    return { ctx, effects, registerProvider }
-  }
-
-  it('installs one proxy, resolves commands, registers providers, and disposes them', async () => {
-    const remote = new FakeRemote()
-    const fixture = pluginContext(remote, subprocess())
-    await apply(fixture.ctx, { servers: { one: server(), two: server({ command: 'server-two' }) } })
-    expect(remote.writes).toHaveLength(1)
-    expect(remote.writes[0]?.[0]?.path).toBe('/workspace/.dsh-e2b/lsp-stdio-proxy.mjs')
-    expect(remote.commands).toContain("chmod 600 -- '/workspace/.dsh-e2b/lsp-stdio-proxy.mjs'")
-    expect(fixture.registerProvider).toHaveBeenCalledTimes(2)
-    await fixture.effects[0]?.()
-  })
-
-  it('rolls back partial registration and rejects invalid composition/configuration', async () => {
-    const remote = new FakeRemote()
-    const firstDispose = vi.fn()
-    const register = vi.fn()
-      .mockReturnValueOnce(firstDispose)
-      .mockImplementationOnce(() => { throw new Error('duplicate provider') })
-    const rollback = pluginContext(remote, subprocess(), register)
-    await expect(apply(rollback.ctx, { servers: { one: server(), two: server() } })).rejects.toThrow('duplicate provider')
-    expect(firstDispose).toHaveBeenCalledOnce()
-
-    const wrong = pluginContext(remote, {} as E2BSubprocessService)
-    await expect(apply(wrong.ctx, { servers: { one: server() } })).rejects.toThrow('dsh-subprocess-e2b')
-
-    const empty = pluginContext(remote, subprocess())
-    await expect(apply(empty.ctx, { servers: {} })).rejects.toThrow('at least one server')
-
-    for (const [id, config] of [
-      ['', server()],
-      ['one', server({ command: '' })],
-      ['one', server({ maxMessageBytes: 0 })],
-      ['one', server({ maxStderrBytes: 1.5 })],
-      ['one', server({ shutdownTimeoutMs: 2_147_483_648 })],
-    ] as const) {
-      const fixture = pluginContext(new FakeRemote(), subprocess())
-      await expect(apply(fixture.ctx, { servers: { [id]: config } })).rejects.toThrow()
-    }
-  })
-
-  it('registers the package-owned invariant companion', async () => {
-    const ctx = new Context()
-    await ctx.plugin(InvariantService, { enabled: true })
-    const fiber = await ctx.plugin(E2BLspInvariant).await()
-    await fiber.dispose()
-  })
-})
diff --git a/packages/e2b/lsp-e2b/tests/transport.spec.ts b/packages/e2b/lsp-e2b/tests/transport.spec.ts
deleted file mode 100644
index ae5106bc09..0000000000
--- a/packages/e2b/lsp-e2b/tests/transport.spec.ts
+++ /dev/null
@@ -1,181 +0,0 @@
-import { once } from 'node:events'
-import { PassThrough } from 'node:stream'
-import { describe, expect, it } from 'vitest'
-import { encodeE2BFrame } from '@deepseek-ai/dsh-e2b'
-import type { SubprocessHandle, SubprocessOutcome } from '@deepseek-ai/dsh-subprocess'
-import { E2BLspTransport } from '@deepseek-ai/dsh-lsp-e2b'
-
-class FakeHandle implements SubprocessHandle {
-  readonly pid = 321
-  readonly stdin: PassThrough | undefined
-  readonly stdout: PassThrough | undefined
-  readonly stderr = undefined
-  readonly collected: SubprocessHandle['collected']
-  readonly result = Promise.withResolvers<SubprocessOutcome>()
-  readonly done = this.result.promise
-  terminated = 0
-  waitResult = true
-
-  constructor(options: { stdin?: boolean; stdout?: boolean; diagnostic?: string } = {}) {
-    this.stdin = options.stdin === false ? undefined : new PassThrough()
-    this.stdout = options.stdout === false ? undefined : new PassThrough()
-    this.collected = options.diagnostic === undefined
-      ? {}
-      : { stderr: { readFrom: () => ({ text: options.diagnostic as string, nextOffset: 0, lossy: false }) } }
-  }
-
-  terminate(): void {
-    this.terminated += 1
-  }
-
-  async waitForExit(): Promise<boolean> {
-    return this.waitResult
-  }
-
-  resolve(outcome: SubprocessOutcome = { exitCode: 0, signal: null }): void {
-    this.stdout?.end()
-    this.result.resolve(outcome)
-  }
-
-  reject(error: unknown): void {
-    this.stdout?.end()
-    this.result.reject(error)
-  }
-}
-
-function proxyFrame(type: 'stdout' | 'stderr', data: string | Buffer): string {
-  return encodeE2BFrame({ type, data: Buffer.from(data).toString('base64') })
-}
-
-describe('E2BLspTransport', () => {
-  it('frames stdin, decodes split byte output, and exposes handle lifecycle', async () => {
-    const inner = new FakeHandle({ diagnostic: 'proxy diagnostic' })
-    const transport = new E2BLspTransport(inner, 1_024, 64)
-    let stdin = ''
-    inner.stdin?.on('data', (chunk) => { stdin += String(chunk) })
-    let stdout = Buffer.alloc(0)
-    transport.stdout.on('data', (chunk) => { stdout = Buffer.concat([stdout, chunk]) })
-
-    transport.stdin.write(Buffer.from([0, 0xff]))
-    await new Promise(resolve => setImmediate(resolve))
-    const encodedInput = stdin.trim()
-    const input = JSON.parse(Buffer.from(encodedInput, 'base64').toString('utf8')) as Record<string, string>
-    expect(input).toEqual({ type: 'stdin', data: 'AP8=' })
-
-    const frames = proxyFrame('stdout', Buffer.from([0, 0xff]))
-      + proxyFrame('stderr', 'server diagnostic')
-      + encodeE2BFrame({ type: 'exit', code: 0, signal: null })
-    inner.stdout?.write(frames.slice(0, 7))
-    inner.stdout?.write(frames.slice(7))
-    inner.stdout?.write(proxyFrame('stderr', ''))
-    inner.stdout?.write(encodeE2BFrame({ type: 'exit', code: null, signal: 'SIGTERM' }))
-    inner.resolve()
-
-    await expect(transport.done).resolves.toEqual({ exitCode: 0, signal: null })
-    expect(stdout).toEqual(Buffer.from([0, 0xff]))
-    expect(transport.collected.stderr?.readFrom(0).text).toBe('server diagnosticproxy diagnostic')
-    expect(transport.pid).toBe(321)
-    inner.waitResult = false
-    await expect(transport.waitForExit()).resolves.toBe(false)
-    transport.terminate()
-    expect(inner.terminated).toBe(1)
-  })
-
-  it('ends the inner stdin and retains a bounded byte tail with independent offsets', async () => {
-    const inner = new FakeHandle()
-    const transport = new E2BLspTransport(inner, 1_024, 4)
-    const finished = once(inner.stdin!, 'finish')
-    transport.stdin.end()
-    await finished
-
-    inner.stdout?.write(proxyFrame('stderr', 'ab'))
-    inner.stdout?.write(proxyFrame('stderr', 'cdef'))
-    const reader = transport.collected.stderr!
-    expect(reader.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true })
-    expect(reader.readFrom(2)).toEqual({ text: 'cdef', nextOffset: 6, lossy: false })
-    expect(reader.readFrom(5)).toEqual({ text: 'f', nextOffset: 6, lossy: false })
-    expect(reader.readFrom(99)).toEqual({ text: '', nextOffset: 6, lossy: false })
-    expect(() => reader.readFrom(-1)).toThrow('non-negative safe integer')
-    expect(() => reader.readFrom(1.5)).toThrow('non-negative safe integer')
-    inner.resolve()
-    await transport.done
-
-    const partialInner = new FakeHandle()
-    const partial = new E2BLspTransport(partialInner, 1_024, 4)
-    partialInner.stdout?.write(proxyFrame('stderr', 'abcdef'))
-    expect(partial.collected.stderr?.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true })
-    partialInner.resolve()
-    await partial.done
-  })
-
-  it.each([
-    ['non-object', encodeE2BFrame(null), 'malformed frame'],
-    ['wrong type', encodeE2BFrame({ type: 'other', data: '' }), 'malformed frame'],
-    ['invalid exit', encodeE2BFrame({ type: 'exit', code: 'zero', signal: null }), 'malformed frame'],
-    ['missing data', encodeE2BFrame({ type: 'stdout' }), 'malformed frame'],
-    ['invalid base64', encodeE2BFrame({ type: 'stdout', data: 'abc' }), 'invalid base64'],
-    ['invalid outer frame', 'not-base64\n', 'invalid base64'],
-    ['non-ASCII outer frame', 'é', 'non-ASCII'],
-  ])('fails %s proxy traffic and terminates the group', async (_name, frame, message) => {
-    const inner = new FakeHandle()
-    const transport = new E2BLspTransport(inner, 1_024, 32)
-    inner.stdout?.write(frame)
-    inner.stdout?.write(proxyFrame('stdout', 'ignored'))
-    inner.stdout?.emit('error', new Error('second failure'))
-    inner.resolve()
-    await expect(transport.done).rejects.toThrow(message)
-    expect(inner.terminated).toBe(1)
-  })
-
-  it('fails truncated frames and preserves inner spawn rejection', async () => {
-    const truncatedInner = new FakeHandle()
-    const truncated = new E2BLspTransport(truncatedInner, 1_024, 32)
-    truncatedInner.stdout?.write('YQ==')
-    truncatedInner.resolve()
-    await expect(truncated.done).rejects.toThrow('mid-frame')
-
-    const rejectedInner = new FakeHandle({ diagnostic: 'tail' })
-    const rejected = new E2BLspTransport(rejectedInner, 1_024, 32)
-    rejectedInner.reject(new Error('spawn failed'))
-    await expect(rejected.done).rejects.toThrow('spawn failed')
-    expect(rejected.collected.stderr?.readFrom(0).text).toBe('tail')
-  })
-
-  it('forwards output and input stream errors without an unhandled inner error', async () => {
-    const outputInner = new FakeHandle()
-    const output = new E2BLspTransport(outputInner, 1_024, 32)
-    outputInner.stdout?.emit('error', new Error('proxy stdout failed'))
-    outputInner.resolve()
-    await expect(output.done).rejects.toThrow('proxy stdout failed')
-
-    const inputInner = new FakeHandle()
-    const input = new E2BLspTransport(inputInner, 1_024, 32)
-    const outerError = once(input.stdin, 'error')
-    inputInner.stdin?.emit('error', new Error('proxy stdin failed'))
-    await expect(outerError).resolves.toMatchObject([{ message: 'proxy stdin failed' }])
-    inputInner.resolve()
-    await input.done
-  })
-
-  it('normalizes a non-Error decoder throw', async () => {
-    const inner = new FakeHandle()
-    const transport = new E2BLspTransport(inner, 1_024, 32)
-    const internal = transport as unknown as {
-      decoder: { push(chunk: string): unknown[] }
-      onProxyData(chunk: Buffer): void
-    }
-    internal.decoder = { push: () => { throw 'raw decoder failure' } }
-    internal.onProxyData(Buffer.from('x'))
-    inner.resolve()
-    await expect(transport.done).rejects.toThrow('raw decoder failure')
-  })
-
-  it('rejects a subprocess that drops either required pipe', () => {
-    const missingStdin = new FakeHandle({ stdin: false })
-    const missingStdout = new FakeHandle({ stdout: false })
-    expect(() => new E2BLspTransport(missingStdin, 10, 10)).toThrow('dropped a piped stream')
-    expect(() => new E2BLspTransport(missingStdout, 10, 10)).toThrow('dropped a piped stream')
-    expect(missingStdin.terminated).toBe(1)
-    expect(missingStdout.terminated).toBe(1)
-  })
-})
diff --git a/packages/e2b/lsp-e2b/tsconfig.json b/packages/e2b/lsp-e2b/tsconfig.json
deleted file mode 100644
index a6c0fd8ece..0000000000
--- a/packages/e2b/lsp-e2b/tsconfig.json
+++ /dev/null
@@ -1,20 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src"],
-  "references": [
-    { "path": "../../../vendor/cosmokit" },
-    { "path": "../../../vendor/cordis" },
-    { "path": "../../../vendor/schemastery" },
-    { "path": "../e2b" },
-    { "path": "../../lsp/lsp" },
-    { "path": "../../lsp/lsp-local" },
-    { "path": "../../subprocess/subprocess" },
-    { "path": "../subprocess-e2b" },
-    { "path": "../../util/timeout" },
-    { "path": "../../support/invariants" }
-  ]
-}
diff --git a/packages/e2b/pty-e2b/README.i18n.yaml b/packages/e2b/pty-e2b/README.i18n.yaml
index ddae4c21db..580f874e62 100644
--- a/packages/e2b/pty-e2b/README.i18n.yaml
+++ b/packages/e2b/pty-e2b/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/e2b/pty-e2b/README.md
-README.md: d6d8e05f13701b85cee9a9646bfdd82ac07769da
-README.zh.md: 265257c72e7bcbd2dfd805b343db5bab7173ab51
+README.md: d1b1731cd7b65577a18814a90363acdc66d7d262
+README.zh.md: 4aa2cc8d661e61e80ef61693422a7b6f73c2cb67
diff --git a/packages/e2b/pty-e2b/README.md b/packages/e2b/pty-e2b/README.md
index d6d8e05f13..d1b1731cd7 100644
--- a/packages/e2b/pty-e2b/README.md
+++ b/packages/e2b/pty-e2b/README.md
@@ -26,7 +26,7 @@ Numeric values are positive safe integers, `backendType` is non-empty, and `maxR
 
 The backend uses E2B's byte-oriented PTY callback with a streaming fatal UTF-8 decoder, then the backend-neutral line sanitizer and bounded buffers from `dsh-pty`. It installs a controlled Bash prompt marker and waits for printable prompt text; when that marker is unavailable, observed output plus the configured silence bound yields `inferred_idle`. Startup with no output reaches the absolute timeout and fails instead of publishing an empty session.
 
-Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; `SIGKILL` refuses to target the shell itself. The backend records the terminal's POSIX session id at startup. Close sends `SIGTERM` to every process group still in that session, escalates survivors to `SIGKILL`, verifies that the session is empty, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
+Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; cancellation rechecks the originating send after lookup so a settled operation cannot signal or fail its successor, and `SIGKILL` refuses to target the shell itself. The backend records the terminal's POSIX session id at startup. Close sends `SIGTERM` to every process group still in that session, escalates survivors to `SIGKILL`, verifies that the session is empty, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
 
 The remote PTY process and its child processes live in E2B. Prompt/readiness state, scrollback, operation handles, owner authority, and SDK event delivery remain in host memory.
 
diff --git a/packages/e2b/pty-e2b/README.zh.md b/packages/e2b/pty-e2b/README.zh.md
index 265257c72e..4aa2cc8d66 100644
--- a/packages/e2b/pty-e2b/README.zh.md
+++ b/packages/e2b/pty-e2b/README.zh.md
@@ -26,7 +26,7 @@
 
 该后端为 E2B 面向字节的 PTY 回调配备流式、遇到无效序列即失败的 UTF-8 解码器，随后使用 `dsh-pty` 提供的后端无关行清理器与有界缓冲区。它会安装受控的 Bash 提示符标记，并等待可打印的提示符文本；若该标记不可用，系统会在已经观察到输出且达到已配置的静默上限时得出 `inferred_idle`。零输出的启动过程会达到绝对超时并失败，不会发布空会话。
 
-每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；发送 `SIGKILL` 时拒绝以 shell 本身为目标。后端会在启动时记录终端的 POSIX 会话 id。关闭操作会向该会话内仍存在的每个进程组发送 `SIGTERM`，对存活者升级为 `SIGKILL`，验证会话已经清空，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
+每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；取消处理会在查找后重新检查原发送操作是否仍为当前操作，以免已结算的操作向后继操作发送信号或令其失败；发送 `SIGKILL` 时拒绝以 shell 本身为目标。后端会在启动时记录终端的 POSIX 会话 id。关闭操作会向该会话内仍存在的每个进程组发送 `SIGTERM`，对存活者升级为 `SIGKILL`，验证会话已经清空，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
 
 远程 PTY 进程及其子进程位于 E2B。提示符／就绪状态、scrollback、操作句柄、所有者权限和 SDK 事件交付仍保留在宿主内存中。
 
diff --git a/packages/e2b/pty-e2b/src/session.ts b/packages/e2b/pty-e2b/src/session.ts
index bf8780103d..7742cd44f0 100644
--- a/packages/e2b/pty-e2b/src/session.ts
+++ b/packages/e2b/pty-e2b/src/session.ts
@@ -226,6 +226,10 @@ export class E2BPtySession implements PtyBackendSession {
   /* jscpd:ignore-start -- Signal, status, and close methods preserve the seam shape around remote identities. */
   async signal(signal: PtySignal): Promise<PtySignalResult> {
     const pgid = await this.foregroundPgid()
+    return await this.deliverSignal(signal, pgid)
+  }
+
+  private async deliverSignal(signal: PtySignal, pgid: number): Promise<PtySignalResult> {
     if (signal === 'SIGKILL' && pgid === this.pid) {
       throw new Error('refusing to SIGKILL the E2B PTY shell; use terminal_close')
     }
@@ -302,7 +306,15 @@ export class E2BPtySession implements PtyBackendSession {
 
   private interrupt(operation: E2BSendOperation): void {
     if (this.active !== operation) return
-    void this.signal('SIGINT').catch((error: unknown) => { this.failActive(error) })
+    void this.interruptActive(operation).catch((error: unknown) => {
+      if (this.active === operation) this.failActive(error)
+    })
+  }
+
+  private async interruptActive(operation: E2BSendOperation): Promise<void> {
+    const pgid = await this.foregroundPgid()
+    if (this.active !== operation) return
+    await this.deliverSignal('SIGINT', pgid)
   }
 
   private async foregroundPgid(): Promise<number> {
diff --git a/packages/e2b/pty-e2b/tests/session.spec.ts b/packages/e2b/pty-e2b/tests/session.spec.ts
index 554a4a3590..1fedf6bbac 100644
--- a/packages/e2b/pty-e2b/tests/session.spec.ts
+++ b/packages/e2b/pty-e2b/tests/session.spec.ts
@@ -68,6 +68,7 @@ class FakeSandbox {
   sendError: unknown
   signalError: unknown
   killError: unknown
+  foregroundLookup: Promise<CommandResult> | undefined
   onTerm: (() => void) | undefined
   onGroupKill: (() => void) | undefined
   onKill: (() => void) | undefined
@@ -88,7 +89,9 @@ class FakeSandbox {
     commands: {
       run: async (command: string): Promise<CommandResult> => {
         this.commands.push(command)
-        if (command.startsWith('ps -o tpgid')) return { exitCode: 0, stdout: this.pgid, stderr: '' }
+        if (command.startsWith('ps -o tpgid')) {
+          return await (this.foregroundLookup ?? Promise.resolve({ exitCode: 0, stdout: this.pgid, stderr: '' }))
+        }
         if (command.startsWith('ps -eo sid=')) {
           return { exitCode: 0, stdout: this.sessionGroups.map(value => `${value}\n`).join(''), stderr: '' }
         }
@@ -273,6 +276,45 @@ describe('E2BPtySession readiness, output, and signals', () => {
     expect(sendInput).toHaveBeenCalled()
   })
 
+  it('does not let a stale interrupt signal or fail a successor send', async () => {
+    vi.useFakeTimers()
+    const fake = new FakeSandbox()
+    const handle = new FakePtyHandle()
+    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
+    await initialize(session)
+
+    const lookup = Promise.withResolvers<CommandResult>()
+    fake.foregroundLookup = lookup.promise
+    const stale = session.startSend({ text: 'old', submit: true })
+    expect(stale.cancel()).toBe(true)
+    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await stale.done
+
+    const successor = session.startSend({ text: 'new', submit: true })
+    fake.signalError = new Error('late interrupt failure')
+    lookup.resolve({ exitCode: 0, stdout: '789\n', stderr: '' })
+    await vi.advanceTimersByTimeAsync(0)
+    expect(fake.commands).not.toContain('kill -INT -- -789')
+    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await expect(successor.done).resolves.toMatchObject({ waitReason: 'stdin_read' })
+
+    const failedLookup = Promise.withResolvers<CommandResult>()
+    fake.foregroundLookup = failedLookup.promise
+    const staleFailure = session.startSend({ text: 'old failure', submit: true })
+    expect(staleFailure.cancel()).toBe(true)
+    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await staleFailure.done
+    const finalSuccessor = session.startSend({ text: 'new after failure', submit: true })
+    failedLookup.reject(new Error('late lookup failure'))
+    await vi.advanceTimersByTimeAsync(0)
+    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
+    await vi.advanceTimersByTimeAsync(10)
+    await expect(finalSuccessor.done).resolves.toMatchObject({ waitReason: 'stdin_read' })
+  })
+
   it('preserves startup abort reasons and classifies invalid UTF-8 transport failures', async () => {
     const fake = new FakeSandbox()
     const abortHandle = new FakePtyHandle()

From 2abc9823e761e5abce520799504d264581719930 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 02:51:44 +0800
Subject: [PATCH 361/516] refactor(e2b): compose portable runtime consumers

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |  28 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |  28 +-
 examples/headless-agent/e2b.cordis.yml        |  23 +-
 .../tests/fixtures/e2b/e2b/bin.ts             |  19 +-
 .../tests/fixtures/e2b/e2b/cordis.yml         |  23 +-
 examples/package.json                         |   2 -
 packages/README.i18n.yaml                     |   4 +-
 packages/README.zh.md                         |   2 +-
 .../code-runtime-worker/README.i18n.yaml      |   4 +-
 .../code-runtime-worker/README.md             |   2 +-
 .../code-runtime-worker/README.zh.md          |   2 +-
 packages/e2b/README.i18n.yaml                 |   4 +-
 packages/e2b/README.md                        |  11 +-
 packages/e2b/README.zh.md                     |  11 +-
 .../e2b/code-runtime-e2b/README.i18n.yaml     |   6 -
 packages/e2b/code-runtime-e2b/README.md       |  44 -
 packages/e2b/code-runtime-e2b/README.zh.md    |  44 -
 packages/e2b/code-runtime-e2b/package.json    |  52 --
 packages/e2b/code-runtime-e2b/src/index.ts    | 494 -----------
 .../e2b/code-runtime-e2b/src/invariant.ts     |  20 -
 .../e2b/code-runtime-e2b/src/runner-source.ts | 649 ---------------
 .../code-runtime-e2b/tests/runtime.spec.ts    | 765 ------------------
 packages/e2b/code-runtime-e2b/tsconfig.json   |  20 -
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/frame.ts                 |  96 ---
 packages/e2b/e2b/src/index.ts                 |  22 -
 packages/e2b/e2b/tests/composition.e2e.ts     |  36 +-
 packages/e2b/e2b/tests/e2b.spec.ts            |  55 --
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   4 +-
 packages/e2b/fs-e2b/README.zh.md              |   4 +-
 packages/e2b/fs-e2b/src/index.ts              |  99 +++
 packages/e2b/fs-e2b/src/source-reader.ts      |  63 ++
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  | 107 ++-
 packages/e2b/pty-e2b/README.i18n.yaml         |   6 -
 packages/e2b/pty-e2b/README.md                |  55 --
 packages/e2b/pty-e2b/README.zh.md             |  55 --
 packages/e2b/pty-e2b/package.json             |  46 --
 packages/e2b/pty-e2b/src/config.ts            |  64 --
 packages/e2b/pty-e2b/src/index.ts             | 130 ---
 packages/e2b/pty-e2b/src/invariant.ts         |  20 -
 packages/e2b/pty-e2b/src/session.ts           | 415 ----------
 packages/e2b/pty-e2b/tests/index.spec.ts      | 248 ------
 packages/e2b/pty-e2b/tests/session.spec.ts    | 485 -----------
 packages/e2b/pty-e2b/tsconfig.json            |  16 -
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |  11 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  11 +-
 packages/e2b/subprocess-e2b/src/index.ts      |  93 ++-
 packages/e2b/subprocess-e2b/src/terminal.ts   | 386 +++++++++
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 541 +++++++++++++
 packages/fs/README.i18n.yaml                  |   4 +-
 .../lsp/lsp-local/tests/fixture-server.ts     |   6 -
 packages/lsp/lsp-local/tests/instance.spec.ts |   5 -
 packages/lsp/lsp/README.i18n.yaml             |   6 +-
 packages/lsp/lsp/README.md                    |   1 -
 packages/lsp/lsp/README.zh.md                 |   1 -
 packages/pty/pty/src/index.ts                 |   9 -
 packages/pty/pty/src/terminal.ts              | 273 -------
 .../verify-package-readme-model-experience.ts |   2 -
 tsconfig.host.json                            |   3 -
 64 files changed, 1426 insertions(+), 4229 deletions(-)
 delete mode 100644 packages/e2b/code-runtime-e2b/README.i18n.yaml
 delete mode 100644 packages/e2b/code-runtime-e2b/README.md
 delete mode 100644 packages/e2b/code-runtime-e2b/README.zh.md
 delete mode 100644 packages/e2b/code-runtime-e2b/package.json
 delete mode 100644 packages/e2b/code-runtime-e2b/src/index.ts
 delete mode 100644 packages/e2b/code-runtime-e2b/src/invariant.ts
 delete mode 100644 packages/e2b/code-runtime-e2b/src/runner-source.ts
 delete mode 100644 packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
 delete mode 100644 packages/e2b/code-runtime-e2b/tsconfig.json
 delete mode 100644 packages/e2b/e2b/src/frame.ts
 create mode 100644 packages/e2b/fs-e2b/src/source-reader.ts
 delete mode 100644 packages/e2b/pty-e2b/README.i18n.yaml
 delete mode 100644 packages/e2b/pty-e2b/README.md
 delete mode 100644 packages/e2b/pty-e2b/README.zh.md
 delete mode 100644 packages/e2b/pty-e2b/package.json
 delete mode 100644 packages/e2b/pty-e2b/src/config.ts
 delete mode 100644 packages/e2b/pty-e2b/src/index.ts
 delete mode 100644 packages/e2b/pty-e2b/src/invariant.ts
 delete mode 100644 packages/e2b/pty-e2b/src/session.ts
 delete mode 100644 packages/e2b/pty-e2b/tests/index.spec.ts
 delete mode 100644 packages/e2b/pty-e2b/tests/session.spec.ts
 delete mode 100644 packages/e2b/pty-e2b/tsconfig.json
 create mode 100644 packages/e2b/subprocess-e2b/src/terminal.ts
 create mode 100644 packages/e2b/subprocess-e2b/tests/terminal.spec.ts
 delete mode 100644 packages/pty/pty/src/terminal.ts

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 04ebe420ac..fc187ec47b 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 4e6414b7d919d765712ac9314ce73a69c5c6344e
-2026-07-27-e2b-remote-runtime-poc.zh.md: 4d39ed7eb07cdd17c5bfa9155bc7efabaa798117
+2026-07-27-e2b-remote-runtime-poc.md: df0d6be97c502a9afe1a7aff3656a7567d302704
+2026-07-27-e2b-remote-runtime-poc.zh.md: 111d7aa63f8f7e51a82cfa0e42c489901f2b88e4
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index 4e6414b7d9..df0d6be97c 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -12,27 +12,23 @@ Moving the complete harness into a remote VM would unify that state but also cou
 
 ## Decision
 
-The E2B integration is an opt-in provider-composition POC. Its six E2B-specific packages live under `packages/e2b/` while retaining seam-specific npm names:
+The E2B integration is an opt-in provider-composition POC. Its three E2B-specific packages live together under `packages/e2b/`:
 
 - `@deepseek-ai/dsh-e2b` creates or reconnects one secure E2B sandbox, creates its working and private runtime directories, and owns kill/pause/leave disposal.
 - `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
-- `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands and remote Linux process groups.
-- `@deepseek-ai/dsh-pty-e2b` registers an E2B byte-PTY backend on `ctx.pty` while the existing registry retains exact-Agent ownership.
-- `@deepseek-ai/dsh-lsp-e2b` registers configured remote language servers on `ctx.lsp`, reads source through a bounded no-follow helper in E2B, and runs servers through `dsh-subprocess-e2b`.
-- `@deepseek-ai/dsh-code-runtime-e2b` registers `ctx.codeRuntime`, runs each model program in a fresh remote worker, and dispatches binding functions in the host process.
-- The existing `@deepseek-ai/dsh-bash-local` remains the Bash implementation because it delegates all process mechanics to `ctx.subprocess`.
+- `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, byte PTYs, and remote Linux process groups.
 
-The owner is the sole source of sandbox identity. Providers inject it and never create private sandboxes, so filesystem tools, Bash, interactive shells, language servers, and code workers share one remote cwd, process namespace, and adapter-private directory while preserving the existing capability interfaces and model-facing tools.
+The higher capabilities use provider-neutral implementations. `dsh-bash-local` delegates command mechanics to `ctx.subprocess`; `dsh-pty-local` delegates terminal allocation and signalling to `ctx.subprocess.spawnTerminal()`; `dsh-lsp-local` reads through `ctx.fs` and launches through `ctx.subprocess`; `dsh-code-runtime-subprocess` materializes its runner through `ctx.fs` and starts it through `ctx.subprocess`. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns those generic interfaces and consumers.
 
-The providers reuse the PTY, LSP, Code Runtime, and subprocess seams without changing their model-facing consumers or the agent loop. Backend-neutral PTY text handling lives in `dsh-pty`; the LSP protocol engine accepts `processId: null` for a server in another process namespace; Code Runtime exports its output-ledger and lossless-JSON helpers for backend parity.
+The E2B owner is the sole source of sandbox identity. Its two adapters never create private sandboxes, so filesystem tools, Bash, interactive shells, language servers, and code workers share one remote cwd, process namespace, and adapter-private directory while preserving the existing capability interfaces, generic implementations, model-facing tools, and agent loop.
 
 ## POC boundary
 
-E2B owns the mutable filesystem, command and Bash processes, PTY shell and terminal-session process groups, language-server processes and source reads, the Code Runtime launcher, controller, and worker, and adapter-private files under `.dsh-e2b`.
+E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session process groups, language-server processes and source reads, the Code Runtime launcher, controller, and worker, and adapter-private files under `.dsh-e2b`.
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-Byte-sensitive protocols use the narrowest adapter required by E2B's callback shapes. PTY consumes the SDK's byte callback directly and carries send identity across asynchronous foreground-group lookup. LSP installs a bounded remote source reader that walks no-follow directory descriptors beneath the canonical workspace. Code Runtime keeps framed stdout in a launcher process isolated from the controller and worker descriptors, and gives each controller a process group that is killed before its inherited pipes drain. Their dependency-free helpers encode protocol payloads as validated newline-delimited base64 JSON, keeping E2B's decoded command callbacks on an ASCII transport.
+The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses UTF-8 JSON over command pipes; E2B's decoded callback transport is not an arbitrary binary channel.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
@@ -40,7 +36,7 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 ## Verification
 
-Focused package suites pin owner lifecycle cleanup, filesystem semantics and commit metadata, subprocess process groups, configuration and verified publication rollback, byte framing and multibyte boundaries, PTY readiness/signal identity/default-environment scrubbing/terminal-session cleanup, descriptor-walked bounded LSP source reads, Code Runtime binding and descriptor isolation, worker and descendant-held pipe draining, hostile traffic, output limits, timeout/abort ordering, disposal to quiescence, and package-owned invariant registrations. Adjacent local-backend suites pin the shared PTY utilities and the LSP cross-namespace `processId` behavior.
+Focused package suites pin owner lifecycle cleanup, filesystem paths/containment/bounded descriptor reads and commit metadata, subprocess executable lookup/process groups/publication rollback, terminal byte I/O/signal identity/default-environment scrubbing/session cleanup, output limits, abort ordering, disposal to quiescence, and package-owned invariant registrations. The generic PTY, LSP, and subprocess Code Runtime suites pin their provider-neutral readiness, cross-namespace `processId`, binding bridge, descriptor isolation, hostile traffic, and worker/descendant cleanup behavior.
 
 A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, bounded spill output, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
@@ -50,13 +46,13 @@ A credential-gated Loader composition creates real E2B sandboxes and exercises F
 
 **Run the entire harness process inside E2B** — rejected because it changes deployment, credential flow, model transport, session durability, plugin loading, and supervision at once. Those questions are independent of proving the provider seams.
 
-**Put every E2B capability in the shared owner package** — rejected because lifecycle identity is the owner's only concern. Filesystem, subprocess, PTY, LSP, and Code Runtime retain separate provider contracts, configuration, tests, and consumers; Bash continues to reuse its subprocess seam.
+**Put every E2B operation in the shared owner package** — rejected because lifecycle identity is the owner's only concern. Filesystem and subprocess retain separate provider contracts, tests, and consumers; the owner exposes one shared SDK handle without becoming a capability grab bag.
 
 **Implement filesystem operations through shell commands only** — rejected because that bypasses `ctx.fs` identity, structured errors, version guards, streaming reads, and atomic mutation semantics already consumed by the file tools.
 
-**Use the host PTY, LSP, and worker backends unchanged** — rejected because they use host process and filesystem APIs; sharing an absolute cwd string does not share state across machines.
+**Keep E2B-specific PTY, LSP, and Code Runtime packages** — rejected because their domain behavior does not vary with E2B. They were shallow adapters that duplicated existing consumers to replace filesystem and process operations; moving those operations behind the fundamental seams gives every provider one implementation of readiness, protocol, binding, and presentation behavior.
 
-**Expose E2B Commands as one generic transport and bypass capability providers** — rejected because PTY needs byte callbacks and foreground signaling, LSP needs byte-faithful stdio plus remote source containment, and Code Runtime needs bidirectional host binding calls and hostile-peer validation. Bypassing their registries would also fork model-facing behavior.
+**Call E2B Filesystem, Commands, or PTY APIs directly from higher capabilities** — rejected because it bypasses the `ctx.fs` and `ctx.subprocess` contracts, duplicates execution-world policy in each consumer, and forks model-facing behavior. The subprocess seam includes the irreducible terminal primitive because ordinary pipes cannot supply foreground groups or whole-session cleanup.
 
 **Add a generic distributed-runtime abstraction first** — rejected because the existing capability seams already carry the required contracts. A new cross-cutting interface would speculate about persistence, synchronization, and reconnect semantics beyond the POC.
 
@@ -64,6 +60,6 @@ A credential-gated Loader composition creates real E2B sandboxes and exercises F
 
 ## Consequences
 
-The small composition demonstrates that existing capability seams can move an agent's mutable coding world off-host without changing the loop or model-facing tool packages. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
+The three-package composition demonstrates that filesystem and subprocess are the sufficient provider seams for moving an agent's mutable coding world off-host without changing the loop, higher capability implementations, or model-facing tool packages. Fixes to Bash, PTY, LSP, and Code Runtime remain provider-neutral. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
 
-The providers are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, ordinary command callbacks are not byte-faithful, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; LSP and Code Runtime add validated ASCII framing where protocol bytes matter. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or PTY session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
+The adapters are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, command callbacks are text-decoded rather than arbitrary binary streams, exact terminal stdin-wait inspection is unavailable, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; Code Runtime uses validated ASCII/base64 framing; the exercised LSP path carries valid UTF-8 JSON. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or terminal session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 4d39ed7eb0..111d7aa63f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -12,27 +12,23 @@ Status: implemented
 
 ## 决策
 
-E2B 集成是一个选择性启用的提供方组合 POC。它的 6 个 E2B 专用包（package）位于 `packages/e2b/` 下，同时保留按 seam 区分的 npm 名称：
+E2B 集成是一个选择性启用的提供方组合 POC。它的 3 个 E2B 专用包（package）集中位于 `packages/e2b/` 下：
 
 - `@deepseek-ai/dsh-e2b` 创建或重新连接一个安全的 E2B 沙箱，创建其工作目录与私有运行时目录，并拥有 kill/pause/leave 资源释放操作。
 - `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
-- `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands 和远程 Linux 进程组之上实现 `ctx.subprocess`。
-- `@deepseek-ai/dsh-pty-e2b` 在 `ctx.pty` 上注册 E2B 字节 PTY 后端，并把精确的 Agent 所有权保留在现有注册表中。
-- `@deepseek-ai/dsh-lsp-e2b` 在 `ctx.lsp` 上注册已配置的远程语言服务器，通过 E2B 内有界且不跟随链接的辅助程序读取源代码，并通过 `dsh-subprocess-e2b` 运行服务器。
-- `@deepseek-ai/dsh-code-runtime-e2b` 注册 `ctx.codeRuntime`，在全新的远程 worker 中运行每个模型程序，并在宿主进程中分发绑定函数。
-- 现有的 `@deepseek-ai/dsh-bash-local` 继续作为 Bash 实现，因为它把所有进程机制委托给 `ctx.subprocess`。
+- `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands、字节 PTY 和远程 Linux 进程组之上实现 `ctx.subprocess`。
 
-该所有者是沙箱身份的唯一真源。提供方会注入该所有者，绝不创建私有沙箱，因此文件系统工具、Bash、交互式 shell、语言服务器和代码 worker 会共享一个远程 cwd、进程命名空间和适配器私有目录，同时保留现有功能接口与面向模型的工具。
+上层功能使用提供方无关的实现。`dsh-bash-local` 把命令机制委托给 `ctx.subprocess`；`dsh-pty-local` 把终端分配与信号发送委托给 `ctx.subprocess.spawnTerminal()`；`dsh-lsp-local` 通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动；`dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化 runner，再通过 `ctx.subprocess` 启动它。这些通用接口与消费方由[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)负责定义。
 
-这些提供方复用 PTY、LSP、Code Runtime 与进程管理 seam，不更改面向模型的消费方或 agent loop（智能体循环）。后端无关的 PTY 文本处理位于 `dsh-pty`；LSP 协议引擎允许位于另一个进程命名空间的服务器使用 `processId: null`；Code Runtime 导出输出账本与无损 JSON 辅助函数，以保持各后端一致。
+E2B 所有者是沙箱身份的唯一真源。其两个适配器绝不创建私有沙箱，因此文件系统工具、Bash、交互式 shell、语言服务器和代码 worker 会共享一个远程 cwd、进程命名空间和适配器私有目录，同时保留现有功能接口、通用实现、面向模型的工具与 agent loop（智能体循环）。
 
 ## POC 边界
 
-E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话进程组、语言服务器进程及源码读取、Code Runtime launcher、controller 和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
+E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终端会话进程组、语言服务器进程及源码读取、Code Runtime launcher、controller 和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-对字节敏感的协议只使用适配 E2B 回调形状所需的最窄适配器。PTY 直接消费 SDK 的字节回调，并在异步查找前台进程组的过程中保留发送操作身份。LSP 会安装一个有界的远程源码读取器，通过不跟随符号链接打开的目录描述符在规范化工作区下逐级遍历。Code Runtime 则把分帧 stdout 保留在与 controller 和 worker 描述符隔离的 launcher 进程内，并为每个 controller 分配一个进程组，在 controller 继承的管道排空前终止该组。它们的无依赖辅助程序会把协议载荷编码为经过验证、以换行分隔的 base64 JSON，并通过 ASCII 传输承载 E2B 已解码的命令回调。
+基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用 UTF-8 JSON；E2B 的已解码回调传输并非任意二进制通道。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
@@ -40,7 +36,7 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话
 
 ## 验证
 
-聚焦包测试套件固定所有者生命周期清理、文件系统语义与提交元数据、进程管理的进程组、配置与经过验证的发布回滚、字节分帧与多字节边界、PTY 就绪状态／信号身份／默认环境清理／终端会话清理、基于描述符逐级遍历的有界 LSP 源码读取、Code Runtime 绑定与描述符隔离、worker 管道及后代进程所持管道的排空、恶意通信、输出上限、超时／中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。相邻本地后端测试套件固定共享 PTY 工具函数，以及 LSP 跨命名空间 `processId` 行为。
+聚焦包测试套件固定所有者生命周期清理、文件系统路径／containment／有界描述符读取与提交元数据、子进程可执行文件查找／进程组／发布回滚、终端字节 I/O／信号身份／默认环境清理／会话清理、输出上限、中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。通用 PTY、LSP 与子进程 Code Runtime 测试套件固定其提供方无关的就绪判定、跨命名空间 `processId`、绑定桥接、描述符隔离、恶意通信，以及 worker／后代进程清理行为。
 
 凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、有界 spill 输出、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
@@ -50,13 +46,13 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话
 
 **在 E2B 内运行完整 harness 进程。** 不予采纳，因为这会同时改变部署、凭据流、模型传输、会话持久性、插件加载和监管方式。要证明提供方 seam，并不需要同时回答这些彼此独立的问题。
 
-**把所有 E2B 功能放入共享所有者包。** 不予采纳，因为生命周期身份是该所有者唯一负责的事项。文件系统、进程管理、PTY、LSP 与 Code Runtime 各自保留独立的提供方契约、配置、测试和消费方；Bash 继续复用其进程管理 seam。
+**把所有 E2B 操作放入共享所有者包。** 不予采纳，因为生命周期身份是该所有者唯一负责的事项。文件系统与进程管理各自保留独立的提供方契约、测试和消费方；所有者只公开一个共享 SDK 句柄，不会因此包揽各类功能。
 
 **仅通过 shell 命令实现文件系统操作。** 不予采纳，因为这会绕过文件工具已经使用的 `ctx.fs` 身份、结构化错误、版本防护、流式读取和原子变更语义。
 
-**原样使用宿主 PTY、LSP 与 worker 后端。** 不予采纳，因为它们使用宿主的进程与文件系统 API；在不同机器上复用同一个绝对 cwd 字符串并不会共享状态。
+**保留 E2B 专用的 PTY、LSP 与 Code Runtime 包。** 不予采纳，因为它们的领域行为不会随 E2B 改变。这些浅层适配器为了替换文件系统与进程操作而重复现有消费方；把这些操作移到基础 seam 之后，可让所有提供方共享同一套就绪判定、协议、绑定与呈现行为实现。
 
-**把 E2B Commands 公开为通用传输并绕过功能提供方。** 不予采纳，因为 PTY 需要字节回调和前台信号，LSP 需要字节保真的 stdio 与远程源码路径约束，Code Runtime 则需要双向宿主绑定调用与不可信对等方验证。绕过其注册表还会使面向模型的行为产生分叉。
+**从上层功能直接调用 E2B Filesystem、Commands 或 PTY API。** 不予采纳，因为这会绕过 `ctx.fs` 与 `ctx.subprocess` 契约，在每个消费方中重复执行环境策略，并使面向模型的行为产生分叉。进程管理 seam 纳入不可约简的终端原语，因为普通管道无法提供前台进程组或全会话清理。
 
 **先添加通用分布式运行时抽象。** 不予采纳，因为现有功能 seam 已承载所需契约。新的跨领域接口会预先假定 POC 范围之外的持久化、同步与重连语义。
 
@@ -64,6 +60,6 @@ E2B 拥有可变文件系统、命令和 Bash 进程、PTY shell 与终端会话
 
 ## 后果
 
-这个小型组合证明，现有功能 seam 可以把 agent 的可变 coding 环境移出宿主，而无需改变循环或面向模型的工具包。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
+这个由 3 个包组成的组合证明，文件系统与进程管理这两个提供方 seam 足以把 agent 的可变 coding 环境移出宿主，而无需改变循环、上层功能实现或面向模型的工具包。Bash、PTY、LSP 与 Code Runtime 的修复仍与提供方无关。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
 
-这些提供方并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，普通命令回调并非字节保真，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；LSP 与 Code Runtime 则在必须保真处理协议字节之处增加经过验证的 ASCII 分帧。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或 PTY 会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
+这些适配器并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，命令回调传递的是已解码文本而非任意二进制流，无法精确检查终端 stdin 等待状态，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；Code Runtime 使用经过验证的 ASCII/base64 分帧；已演练的 LSP 路径承载有效的 UTF-8 JSON。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或终端会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index 877172c343..32d7049c5d 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -1,6 +1,6 @@
 # POC overlay: keep the advanced headless agent and model-facing tools, but
-# place its filesystem, processes, terminals, language servers, and Code Mode
-# execution in one short-lived E2B sandbox.
+# place its filesystem and process substrate in one short-lived E2B sandbox;
+# the generic Bash, PTY, LSP, and Code Runtime consumers compose above them.
 - id: base
   name: '@cordisjs/plugin-include'
   config:
@@ -32,18 +32,25 @@
             name: '@deepseek-ai/dsh-subprocess-e2b'
           - id: fs-e2b
             name: '@deepseek-ai/dsh-fs-e2b'
-          - id: code-runtime-e2b
-            name: '@deepseek-ai/dsh-code-runtime-e2b'
+          - id: code-runtime-subprocess
+            name: '@deepseek-ai/dsh-code-runtime-subprocess'
+          - id: sandbox
+            name: '@deepseek-ai/dsh-sandbox-local'
+          - id: sandbox-policy
+            name: '@deepseek-ai/dsh-sandbox-policy'
+            config:
+              mode: danger-full-access
+              workspaceRoot: !!js process.cwd()
           - id: pty
             name: '@deepseek-ai/dsh-pty'
-          - id: pty-e2b
-            name: '@deepseek-ai/dsh-pty-e2b'
+          - id: pty-local
+            name: '@deepseek-ai/dsh-pty-local'
           - id: tool-pty
             name: '@deepseek-ai/dsh-tool-pty'
           - id: lsp
             name: '@deepseek-ai/dsh-lsp'
-          - id: lsp-e2b
-            name: '@deepseek-ai/dsh-lsp-e2b'
+          - id: lsp-local
+            name: '@deepseek-ai/dsh-lsp-local'
             config:
               servers:
                 typescript:
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index a997752711..aeb447b0e8 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -1,15 +1,14 @@
 import { readFile } from 'node:fs/promises'
 import { posix, resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
-import { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-code-runtime-e2b'
+import type {} from '@deepseek-ai/dsh-code-runtime-subprocess'
 import { quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
 import type {} from '@deepseek-ai/dsh-bash-local'
-import type {} from '@deepseek-ai/dsh-lsp-e2b'
-import type {} from '@deepseek-ai/dsh-pty-e2b'
+import type {} from '@deepseek-ai/dsh-lsp-local'
+import type {} from '@deepseek-ai/dsh-pty-local'
 
 const configPath = process.argv[2]
 if (configPath === undefined) throw new Error('usage: bin.ts <cordis.yml>')
@@ -24,10 +23,10 @@ const owner: Agent = {
   status: 'idle',
   acceptsNextStep: false,
   ctx: ownerFiber.ctx,
-  followup: () => AgentMessageId('unused'),
-  steer: () => AgentMessageId('unused'),
-  inject: () => AgentMessageId('unused'),
-  send: () => AgentMessageId('unused'),
+  followup() {},
+  steer() {},
+  inject() {},
+  send() {},
   cancel() {},
   whenIdle: () => Promise.resolve(),
 }
@@ -159,7 +158,7 @@ try {
   const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
   let containmentFaultInjected = false
   remoteCommands.run = async (command, options) => {
-    if (!containmentFaultInjected && command.includes('dsh-e2b-source-reader') && command.includes('swapped-parent/source.ts')) {
+    if (!containmentFaultInjected && command.includes('dsh-e2b-bounded-reader') && command.includes('swapped-parent/source.ts')) {
       containmentFaultInjected = true
       await runRemoteCommand(
         `rm -rf -- ${quoteE2BShellArg(swappedParentPath)} && ln -s -- ${quoteE2BShellArg(swappedOutsidePath)} ${quoteE2BShellArg(swappedParentPath)}`,
@@ -194,7 +193,7 @@ try {
       workspaceRoot: process.cwd(),
     })
   } catch (error: unknown) {
-    lspDocumentBound = String(error).includes('over the 4000000-byte limit')
+    lspDocumentBound = String(error).includes('exceeds the 4000000-byte limit')
     if (!lspDocumentBound) throw error
   }
   if (!lspDocumentBound) throw new Error('E2B LSP accepted an oversized remote source')
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 65bd3d5246..93bb6b65e5 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -21,22 +21,33 @@
 - id: agents
   name: '@deepseek-ai/dsh-agent'
 
+- id: sandbox
+  name: '@deepseek-ai/dsh-sandbox-local'
+
+- id: sandbox-policy
+  name: '@deepseek-ai/dsh-sandbox-policy'
+  config:
+    mode: danger-full-access
+    workspaceRoot: !!js process.cwd()
+
 - id: pty
   name: '@deepseek-ai/dsh-pty'
 
-- id: pty-e2b
-  name: '@deepseek-ai/dsh-pty-e2b'
+- id: pty-local
+  name: '@deepseek-ai/dsh-pty-local'
   config:
     pollIntervalMs: 25
+    exactProbeAfterMs: 150
     idleSilenceMs: 2000
+    handoffGraceMs: 500
     timeoutMs: 5000
     disposeGraceMs: 1000
 
 - id: lsp
   name: '@deepseek-ai/dsh-lsp'
 
-- id: lsp-e2b
-  name: '@deepseek-ai/dsh-lsp-e2b'
+- id: lsp-local
+  name: '@deepseek-ai/dsh-lsp-local'
   config:
     servers:
       fixture:
@@ -48,8 +59,8 @@
         shutdownTimeoutMs: 1000
         killGraceMs: 500
 
-- id: code-runtime-e2b
-  name: '@deepseek-ai/dsh-code-runtime-e2b'
+- id: code-runtime-subprocess
+  name: '@deepseek-ai/dsh-code-runtime-subprocess'
   config:
     computeMs: 500
     maxWallMs: 5000
diff --git a/examples/package.json b/examples/package.json
index 8dd631e760..e4251c9475 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -43,12 +43,10 @@
     "@deepseek-ai/dsh-llm-replay": "workspace:*",
     "@deepseek-ai/dsh-loader-smoke": "workspace:*",
     "@deepseek-ai/dsh-lsp": "workspace:*",
-    "@deepseek-ai/dsh-lsp-e2b": "workspace:*",
     "@deepseek-ai/dsh-lsp-local": "workspace:*",
     "@deepseek-ai/dsh-permission": "workspace:*",
     "@deepseek-ai/dsh-plan-mode": "workspace:*",
     "@deepseek-ai/dsh-pty": "workspace:*",
-    "@deepseek-ai/dsh-pty-e2b": "workspace:*",
     "@deepseek-ai/dsh-pty-local": "workspace:*",
     "@deepseek-ai/dsh-pwsh-local": "workspace:*",
     "@deepseek-ai/dsh-repeat-tool-guard": "workspace:*",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index a0827779db..f101375bc6 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 7dc52943e488a14e0c055ac72be0b2ad6f752455
-README.zh.md: bc3dbf0b4533d1d6adf6d49b0376a3dcdd6bfdb5
+README.md: 1fd0c9c2385f3169791a28f3ef50bb42792760af
+README.zh.md: f9f7d5ae8839ea7033a349ac7a0083a97780a21c
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 1667c88273..86a316dca7 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 层级结构
 
-组在 `packages/<group>/<pkg>/` 容纳包；包名仍为 `@deepseek-ai/dsh-<pkg>`。**组 README 是规范的包／ctx 键映射。**
+包按组置于 `packages/<group>/<pkg>/`；包名仍为 `@deepseek-ai/dsh-<pkg>`。**组 README 负责包／ctx 键映射。**
 
 | 组 | 职责 | 发布预期 |
 |---|---|---|
diff --git a/packages/code-runtime/code-runtime-worker/README.i18n.yaml b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
index d3472a697e..10c721446f 100644
--- a/packages/code-runtime/code-runtime-worker/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-worker/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/code-runtime/code-runtime-worker/README.md
-README.md: 4b14c6fad5d1e491faeb54c9cb0e4403c8e2d8dd
-README.zh.md: c522917835b562cf7648d8bc78f0315b7c52d2d2
+README.md: 35196a0b4fba5cd0388246a70354308ece08b39f
+README.zh.md: 49871c38c540addd06f5d24793ae00b45e2f8bb0
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index 4b14c6fad5..fbe387e4ea 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -46,7 +46,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **OS processes a program spawns survive this backend's termination** — `worker.terminate()` ends only the thread; deployments needing remote process-group cleanup can select the E2B backend, whose separate limitations still apply.
+- **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only; deployments requiring process-tree cleanup select `dsh-code-runtime-subprocess`, whose mounted subprocess provider owns that cleanup.
 - **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — the relied-on behavior is pinned by unit tests, with amaro/sucrase as named drop-in replacements if it shifts.
 - **`computeMs` expiry can overshoot by up to one poll interval** — busy time is sampled every 25 ms (an internal constant, deliberately not config).
 - **Programs get a five-method `console` shim** (`log`/`info`/`warn`/`error`/`debug`) — deliberately not Node's full console surface.
diff --git a/packages/code-runtime/code-runtime-worker/README.zh.md b/packages/code-runtime/code-runtime-worker/README.zh.md
index c522917835..57f2a1145a 100644
--- a/packages/code-runtime/code-runtime-worker/README.zh.md
+++ b/packages/code-runtime/code-runtime-worker/README.zh.md
@@ -46,7 +46,7 @@ SDK 接口是默认／具名 `WorkerCodeRuntime` 类与 `Config`。可操作的
 
 ## 已知限制与暂缓工作
 
-- **程序 spawn 的 OS 进程在该后端终止后仍会存活**：`worker.terminate()` 只结束线程；需要清理远程进程组的部署可以选择 E2B 后端，但该后端自身的限制仍然适用。
+- **程序 spawn 的 OS 进程在终止后仍会存活**：`worker.terminate()` 只结束线程；需要清理进程树的部署应选择 `dsh-code-runtime-subprocess`，由其挂载的子进程提供方负责该清理。
 - **类型剥离依赖 Node 的实验性 `stripTypeScriptTypes` API**：依赖的行为由单元测试固定；如其发生变化，amaro／sucrase 是已经点名的直接替代品。
 - **`computeMs` 到期最多可能超过一个轮询间隔**：系统每 25 ms 采样一次忙碌时间（内部常量，有意不做成配置）。
 - **程序获得一个含 5 种方法的 `console` shim**（`log`／`info`／`warn`／`error`／`debug`）：有意不提供 Node 的完整 console 接口。
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 1ded2a1d34..9b56a3ef55 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: b25f00fb5f32643008127f0cee4f3d758018404a
-README.zh.md: fc3d6901f3cdf6c645cfde49dc46108759959aca
+README.md: ef2e5ef49056e6688630e785a61c01fa53febbb1
+README.zh.md: d76b05f9b60bc471c1793decd1def1d15615c852
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index b25f00fb5f..ef2e5ef490 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -2,15 +2,14 @@
 
 English | [中文](README.zh.md)
 
-An experimental provider-composition POC that places the mutable coding world in one E2B Linux sandbox. The shared owner is separate from capability adapters so every remote provider awaits the same sandbox identity and lifecycle.
+An experimental provider-composition POC that places one filesystem/process execution world in an E2B Linux sandbox. E2B supplies only sandbox lifecycle and the two fundamental OS adapters; provider-neutral consumers build higher capabilities above them.
 
 | Package | ctx key | Role |
 |---|---|---|
 | [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create or reconnect one sandbox, create its working/runtime directories, expose the shared SDK handle, and apply the configured kill/pause/leave disposition |
 | [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
-| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement managed process groups, stdio projection, and remote spill files over E2B Commands |
-| [`pty-e2b`](pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | `ctx.pty` backend | Run persistent interactive shells through E2B's byte PTY API |
-| [`lsp-e2b`](lsp-e2b/README.md) (`@deepseek-ai/dsh-lsp-e2b`) | `ctx.lsp` provider | Run configured language servers and read query sources inside E2B |
-| [`code-runtime-e2b`](code-runtime-e2b/README.md) (`@deepseek-ai/dsh-code-runtime-e2b`) | `ctx.codeRuntime` | Run model-written programs remotely while bridging bindings to the host |
+| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement executable lookup, managed process groups and stdio, remote spill files, and terminal sessions over E2B Commands and PTY APIs |
 
-The existing [`dsh-bash-local`](../bash/bash-local/README.md) needs no E2B-specific fork: it delegates process mechanics to `ctx.subprocess`, so replacing that provider places Bash in the same remote world. This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, protocol state, or E2B SDK buffers. The [shared-runtime decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary.
+The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), [`dsh-lsp-local`](../lsp/lsp-local/README.md), and [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox.
+
+This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [shared-runtime decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary; the [portable-consumer decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns the generic composition.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index fc3d6901f3..d76b05f9b6 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -2,15 +2,14 @@
 
 [English](README.md) | 中文
 
-这是一个实验性提供方组合 POC，把可变的编码环境放进同一个 E2B Linux 沙箱。共享所有者与功能适配器分离，使每个远程提供方都等待同一个沙箱身份和生命周期。
+这是一个实验性提供方组合 POC，把一个文件系统／进程执行环境放进 E2B Linux 沙箱。E2B 只提供沙箱生命周期与两个基础 OS 适配器；提供方无关的消费方在其上构建更高层能力。
 
 | 包（package） | ctx 键 | 职责 |
 |---|---|---|
 | [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建或重新连接一个沙箱，创建其工作目录与运行时目录，公开共享 SDK 句柄，并应用配置的 kill/pause/leave 处置方式 |
 | [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
-| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 实现受管进程组、stdio 投影与远程 spill 文件 |
-| [`pty-e2b`](pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | `ctx.pty` 后端 | 通过 E2B 的字节 PTY API 运行持久交互式 shell |
-| [`lsp-e2b`](lsp-e2b/README.md)（`@deepseek-ai/dsh-lsp-e2b`） | `ctx.lsp` 提供方 | 在 E2B 内运行已配置的语言服务器并读取查询源代码 |
-| [`code-runtime-e2b`](code-runtime-e2b/README.md)（`@deepseek-ai/dsh-code-runtime-e2b`） | `ctx.codeRuntime` | 远程运行模型编写的程序，同时把绑定桥接到宿主 |
+| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 与 PTY API 实现可执行文件查找、受管进程组与 stdio、远程 spill 文件及终端会话 |
 
-现有的 [`dsh-bash-local`](../bash/bash-local/README.md) 无需 E2B 专用 fork：它把进程机制委托给 `ctx.subprocess`，因此替换该提供方即可让 Bash 进入同一个远程环境。该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、协议状态或 E2B SDK 缓冲。[共享运行时决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)界定 POC 边界。
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md)、[`dsh-lsp-local`](../lsp/lsp-local/README.md) 及 [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。
+
+该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[共享运行时决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)界定 POC 边界；[可移植消费方决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)界定通用组合。
diff --git a/packages/e2b/code-runtime-e2b/README.i18n.yaml b/packages/e2b/code-runtime-e2b/README.i18n.yaml
deleted file mode 100644
index eb4e75f297..0000000000
--- a/packages/e2b/code-runtime-e2b/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/e2b/code-runtime-e2b/README.md
-README.md: a8623f95d16b54b29e53bb9cf2c528b36f121283
-README.zh.md: 2b4a37864e3c6755a74f0d2ef6ce38aa39aae24b
diff --git a/packages/e2b/code-runtime-e2b/README.md b/packages/e2b/code-runtime-e2b/README.md
deleted file mode 100644
index a8623f95d1..0000000000
--- a/packages/e2b/code-runtime-e2b/README.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# @deepseek-ai/dsh-code-runtime-e2b
-
-English | [中文](README.zh.md)
-
-E2B implementation of [`ctx.codeRuntime`](../../code-runtime/code-runtime/README.md). Each run executes one model-written TypeScript program in a fresh remote Node worker while binding functions, type stripping, output accounting, and lifecycle orchestration remain on the host.
-
-## Configuration
-
-| Key | Default | Meaning |
-|---|---|---|
-| `computeMs` | `60000` | Remote worker event-loop busy-time budget. |
-| `maxWallMs` | `600000` | Host-observed wall-clock ceiling. |
-| `maxOutputBytes` | `67108864` | Combined serialized outer logs/value/diagnostic cap. |
-| `maxOldGenerationSizeMb` | `512` | Remote worker old-generation heap cap in MiB. |
-| `maxFrameBytes` | `268435456` | Largest decoded bridge frame, including binding traffic. |
-| `killGraceMs` | `2000` | Remote process-group TERM-to-KILL grace. |
-
-Every value is a positive safe integer. `maxOutputBytes` is at least four bytes, `maxWallMs` cannot exceed Node's maximum timer delay, and `maxFrameBytes` cannot be smaller than `maxOutputBytes`. The service requires the concrete `dsh-subprocess-e2b` backend so run cleanup has remote process-group semantics.
-
-## Execution and bridge contract
-
-Setup uploads one dependency-free runner under `ctx.e2b.runtimeRoot` and resolves remote Node. For each run, the host wraps and type-strips erasable TypeScript with Node's `stripTypeScriptTypes`, then starts the runner in `ctx.e2b.cwd`. The runner keeps the framed host protocol in a launcher process, forks a controller process group whose stdout and stderr are bounded data pipes, and creates a fresh worker thread with an empty environment and heap limit. Model writes to native descriptors and inherited child output therefore cannot enter the frame stream; completion kills the controller group before draining its pipes and emitting the terminal frame. The worker measures active event-loop time and is destroyed after one completion. The enclosing E2B subprocess group is terminated and awaited after every result, timeout, abort, or disposal, so ordinary child processes in either managed group stop with the run.
-
-The bridge uses validated newline-delimited base64 JSON frames because E2B subprocess callbacks expose decoded text. Binding arguments and resolutions use the worker runtime's iterative lossless-JSON wire shape; binding functions execute on the host and typed rejection classes are materialized inside the remote worker. The worker captures the JavaScript intrinsics that its adapter boundary invokes before model code runs, hardening binding transport, output accounting, and completion validation against mutation of those references. The host repeats message validation, call-id deduplication, lossless-JSON checks, and the outer-output ledger.
-
-Program failures resolve as `CodeRunResult.error`; only seam misuse rejects. `isolation` is reported as `container`, which is a deployment descriptor rather than a security claim.
-
-## Model Experience
-
-Indirectly, through Code Mode in `dsh-tools`, which returns program logs, values, or typed failures through the existing `run_code` result contract.
-
-#### KV Cache effect
-
-No direct invalidation; Code Mode owns request-prefix changes.
-
-## Known Limitations and Deferred Work
-
-- **Not a whole-agent runtime** — Cordis, sessions, LLM calls, binding dispatch, TypeScript stripping, output ledgers, and E2B SDK state remain on the host.
-- **No reconnectable runs** — retaining a sandbox preserves files but not worker/subprocess handles, binding calls, timers, or output cursors.
-- **Node worker internals share the model realm** — mutating realm-wide globals or prototypes that Node itself uses can terminate the worker; captured adapter intrinsics are not a separate JavaScript realm or a security boundary.
-- **Deliberate process-group escape is not captured** — model code can create a new POSIX session; that unmanaged process is outside this backend's cleanup identity.
-- **Intermediate binding traffic is memory-bounded only per frame** — it does not enter model context or the outer-output ledger, but aggregate host/remote process memory remains the limit.
-- **Experimental type stripping** — the backend shares the worker implementation's reliance on Node's experimental erasable-syntax API.
-- **Sandbox policy is template-owned** — this package adds no network, volume, snapshot, or workspace-synchronization policy.
diff --git a/packages/e2b/code-runtime-e2b/README.zh.md b/packages/e2b/code-runtime-e2b/README.zh.md
deleted file mode 100644
index 2b4a37864e..0000000000
--- a/packages/e2b/code-runtime-e2b/README.zh.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# @deepseek-ai/dsh-code-runtime-e2b
-
-[English](README.md) | 中文
-
-[`ctx.codeRuntime`](../../code-runtime/code-runtime/README.md) 的 E2B 实现。每次运行都会在全新的远程 Node worker 中执行一段模型编写的 TypeScript 程序；绑定函数、类型剥离、输出记账和生命周期编排仍保留在宿主侧。
-
-## 配置
-
-| 配置键 | 默认值 | 含义 |
-|---|---|---|
-| `computeMs` | `60000` | 远程 worker 的事件循环忙碌时间预算。 |
-| `maxWallMs` | `600000` | 宿主观测到的墙钟时间上限。 |
-| `maxOutputBytes` | `67108864` | 外层日志、值和诊断合计的序列化上限。 |
-| `maxOldGenerationSizeMb` | `512` | 远程 worker 的老生代堆上限（MiB）。 |
-| `maxFrameBytes` | `268435456` | 已解码桥接帧的最大大小，包括绑定流量。 |
-| `killGraceMs` | `2000` | 远程进程组 TERM 到 KILL 的宽限期。 |
-
-每个值都必须是正的安全整数。`maxOutputBytes` 必须至少为 4 字节，`maxWallMs` 不得超过 Node 的最大定时器延迟，且 `maxFrameBytes` 不得小于 `maxOutputBytes`。本服务要求使用具体的 `dsh-subprocess-e2b` 后端，使运行清理具备远程进程组语义。
-
-## 执行与桥接契约
-
-设置阶段会在 `ctx.e2b.runtimeRoot` 下上传一个无依赖的 runner，并解析远程 Node。每次运行时，宿主会包装仅使用可擦除语法的 TypeScript，再用 Node 的 `stripTypeScriptTypes` 剥离类型，然后在 `ctx.e2b.cwd` 中启动 runner。runner 会把面向宿主的分帧协议保留在 launcher 进程内，派生一个以 stdout 和 stderr 作为有界数据管道的 controller 进程组，再创建一个具有空环境与堆上限的全新 worker 线程。因此，模型对原生描述符的写入和继承的子进程输出无法进入分帧流；运行结算会先终止 controller 进程组，再排空其管道并发出终结帧。worker 会测量事件循环活跃时间，并在一次运行结算后销毁。每当运行返回结果、超时、中止或因资源释放终止时，系统都会终止外围的 E2B 进程组并等待其退出，因此任一受管组内的普通子进程会随本次运行一同停止。
-
-由于 E2B 进程管理回调公开的是已解码文本，桥接层使用经过验证、以换行分隔的 base64 JSON 帧。绑定参数与 resolve 值使用 worker 运行时的迭代式无损 JSON wire 形状；绑定函数在宿主执行，类型化的 reject 类则在远程 worker 内物化。worker 会在模型代码运行前捕获其适配器边界调用的 JavaScript intrinsic，从而增强绑定传输、输出记账与完成值验证对这些引用修改的抵御能力。宿主会再次执行消息验证、调用 id 去重和无损 JSON 检查，并用外层输出账本再次计量。
-
-程序失败会 resolve 为 `CodeRunResult.error`；只有 seam 误用才会 reject。`isolation` 报告为 `container`；这是部署描述符，不构成安全声明。
-
-## 模型体验
-
-通过 `dsh-tools` 中的 Code Mode 间接影响模型；它会通过现有 `run_code` 结果契约返回程序日志、值或类型化失败。
-
-#### KV Cache 影响
-
-不会直接失效；请求前缀变更由 Code Mode 负责。
-
-## 已知限制与暂缓工作
-
-- **并非完整的 agent（智能体）运行时**：Cordis、会话、LLM（大语言模型）调用、绑定分发、TypeScript 类型剥离、输出账本和 E2B SDK 状态仍保留在宿主侧。
-- **运行不可重连**：保留沙箱会保留文件，但不会保留 worker／进程管理句柄、绑定调用、定时器或输出游标。
-- **Node worker 内部机制与模型共享同一 realm**：修改 Node 自身使用、影响整个 realm 的全局对象或原型可能会终止 worker；已捕获的适配器 intrinsic 并不构成独立的 JavaScript realm 或安全边界。
-- **不会捕获有意逃逸进程组的行为**：模型代码可以创建新的 POSIX 会话；该非受管进程不属于此后端的清理身份范围。
-- **中间绑定流量的内存边界仅适用于单帧**：它不会进入模型上下文或外层输出账本，但其总量仍只受宿主／远程进程内存限制。
-- **实验性类型剥离**：该后端与 worker 实现一样，依赖 Node 的实验性可擦除语法 API。
-- **沙箱策略归模板负责**：本包不会额外增加网络、卷、快照或工作区同步策略。
diff --git a/packages/e2b/code-runtime-e2b/package.json b/packages/e2b/code-runtime-e2b/package.json
deleted file mode 100644
index 222ae71bef..0000000000
--- a/packages/e2b/code-runtime-e2b/package.json
+++ /dev/null
@@ -1,52 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-code-runtime-e2b",
-  "description": "E2B code-runtime implementation for DeepSeek Harness",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
-  ],
-  "license": "BSD-3-Clause",
-  "peerDependencies": {
-    "@deepseek-ai/dsh-code-runtime": "^0.0.1",
-    "@deepseek-ai/dsh-code-runtime-worker": "^0.0.1",
-    "@deepseek-ai/dsh-e2b": "^0.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-session": "^0.0.1",
-    "@deepseek-ai/dsh-subprocess-e2b": "^0.0.1",
-    "@deepseek-ai/dsh-timeout": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
-  },
-  "dependencies": {
-    "schemastery": "^3.18.0"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-code-runtime": "workspace:^",
-    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
-    "@deepseek-ai/dsh-e2b": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-subprocess-e2b": "workspace:^",
-    "@deepseek-ai/dsh-timeout": "workspace:^",
-    "cordis": "^4.0.0-rc.7"
-  }
-}
diff --git a/packages/e2b/code-runtime-e2b/src/index.ts b/packages/e2b/code-runtime-e2b/src/index.ts
deleted file mode 100644
index c37cb3cc64..0000000000
--- a/packages/e2b/code-runtime-e2b/src/index.ts
+++ /dev/null
@@ -1,494 +0,0 @@
-/** E2B process/worker implementation of the harness code-runtime seam. */
-
-import { posix } from 'node:path'
-import { stripTypeScriptTypes } from 'node:module'
-import type { Context } from 'cordis'
-import z from 'schemastery'
-import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
-import type {
-  CodeBindingNamespace,
-  CodeJsonValue,
-  CodeRunFailure,
-  CodeRunRequest,
-  CodeRunResult,
-} from '@deepseek-ai/dsh-code-runtime'
-import {
-  E2BFrameDecoder,
-  encodeBoundedE2BFrame,
-  quoteE2BShellArg,
-  resolveE2BExecutable,
-} from '@deepseek-ai/dsh-e2b'
-import {
-  decodeWorkerJson,
-  encodeWorkerJson,
-  OutputLedger,
-} from '@deepseek-ai/dsh-code-runtime-worker'
-import type { WorkerJsonWire } from '@deepseek-ai/dsh-code-runtime-worker'
-import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
-import type { SubprocessHandle } from '@deepseek-ai/dsh-subprocess'
-import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
-import { CODE_RUNNER_SOURCE } from './runner-source.ts'
-
-/** Runtime configuration; every execution and bridge bound is deployment-tunable. */
-export interface Config {
-  /** Remote worker measured event-loop busy-time budget. */
-  computeMs?: number
-  /** Host-observed wall-clock ceiling. */
-  maxWallMs?: number
-  /** Combined serialized outer logs/value/diagnostic cap. */
-  maxOutputBytes?: number
-  /** Remote worker old-generation heap cap in MiB. */
-  maxOldGenerationSizeMb?: number
-  /** Largest decoded bridge frame, including binding traffic. */
-  maxFrameBytes?: number
-  /** Remote process-group TERM-to-KILL grace. */
-  killGraceMs?: number
-}
-
-type ResolvedConfig = Required<Config>
-type PreparedRuntime = { node: string; runner: string }
-
-interface LiveRun {
-  settle(failure: CodeRunFailure): void
-  finished: Promise<void>
-}
-
-interface CallMessage {
-  type: 'call'
-  id: number
-  global: string
-  name: string
-  args: WorkerJsonWire
-}
-
-interface LogMessage {
-  type: 'log'
-  text: string
-}
-
-interface DoneMessage {
-  type: 'done'
-  value?: WorkerJsonWire
-  error?: CodeRunFailure
-}
-
-type RunnerMessage = CallMessage | LogMessage | DoneMessage | { type: 'output-limit' }
-
-const STRIP_WRAP = { prefix: 'async function __dsh_program__() {\n', suffix: '\n}' } as const
-const MIN_OUTPUT_BYTES = 4
-const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
-/* jscpd:ignore-start -- Backends enforce the same injected-global vocabulary without coupling lifecycle implementations. */
-const RESERVED_WORDS = new Set([
-  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
-  'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in',
-  'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
-  'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface', 'package',
-  'private', 'protected', 'public', 'arguments', 'eval',
-])
-const RESERVED_ERROR_PROPERTIES = new Set(['name', 'message', 'stack'])
-/* jscpd:ignore-end */
-const FAILURE_KINDS = new Set<CodeRunFailure['kind']>([
-  'exception', 'timeout', 'abort', 'worker-exit', 'invalid-output', 'output-limit',
-])
-
-function messageOf(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
-}
-
-function parseRunnerMessage(raw: unknown): RunnerMessage | undefined {
-  if (typeof raw !== 'object' || raw === null) return undefined
-  const record = raw as Record<string, unknown>
-  if (record.type === 'output-limit') return { type: 'output-limit' }
-  if (record.type === 'log') return typeof record.text === 'string' ? { type: 'log', text: record.text } : undefined
-  if (record.type === 'call') {
-    if (!Number.isSafeInteger(record.id) || (record.id as number) < 1 || typeof record.global !== 'string' || typeof record.name !== 'string' || !Array.isArray(record.args)) return undefined
-    return { type: 'call', id: record.id as number, global: record.global, name: record.name, args: record.args as WorkerJsonWire }
-  }
-  if (record.type !== 'done') return undefined
-  if (record.error === undefined) {
-    return { type: 'done', ...record.value === undefined ? {} : { value: record.value as WorkerJsonWire } }
-  }
-  if (typeof record.error !== 'object' || record.error === null) return undefined
-  const error = record.error as Record<string, unknown>
-  if (typeof error.kind !== 'string' || !FAILURE_KINDS.has(error.kind as CodeRunFailure['kind']) || typeof error.message !== 'string') return undefined
-  return { type: 'done', error: { kind: error.kind as CodeRunFailure['kind'], message: error.message } }
-}
-
-/** E2B-backed runtime: host-side type stripping, remote worker execution, host binding dispatch. */
-export class E2BCodeRuntime extends CodeRuntime {
-  static inject = ['e2b', 'subprocess']
-
-  static Config: z<Config> = z.object({
-    computeMs: z.number().default(60_000),
-    maxWallMs: z.number().default(600_000),
-    maxOutputBytes: z.number().default(67_108_864),
-    maxOldGenerationSizeMb: z.number().default(512),
-    maxFrameBytes: z.number().default(268_435_456),
-    killGraceMs: z.number().default(2_000),
-  })
-
-  readonly language = 'typescript'
-  readonly isolation = 'container'
-
-  private readonly config: ResolvedConfig
-  private readonly ready: Promise<PreparedRuntime>
-  private readonly live = new Set<LiveRun>()
-  private readonly subprocess: E2BSubprocessService
-  private disposed = false
-
-  constructor(ctx: Context, config: Config) {
-    super(ctx)
-    if (!(ctx.subprocess instanceof E2BSubprocessService)) {
-      throw new Error('code-runtime-e2b requires @deepseek-ai/dsh-subprocess-e2b as ctx.subprocess')
-    }
-    this.subprocess = ctx.subprocess
-    this.config = config as ResolvedConfig
-    for (const [key, value] of Object.entries(this.config)) {
-      if (!Number.isSafeInteger(value) || value <= 0) {
-        throw new Error(`code-runtime-e2b: config.${key} must be a positive safe integer`)
-      }
-    }
-    if (this.config.maxOutputBytes < MIN_OUTPUT_BYTES) {
-      throw new Error(`code-runtime-e2b: config.maxOutputBytes must be at least ${MIN_OUTPUT_BYTES}`)
-    }
-    if (this.config.maxWallMs > MAX_TIMER_DELAY_MS) {
-      throw new Error(`code-runtime-e2b: config.maxWallMs must be at most ${MAX_TIMER_DELAY_MS}`)
-    }
-    if (this.config.maxFrameBytes < this.config.maxOutputBytes) {
-      throw new Error('code-runtime-e2b: config.maxFrameBytes must be at least maxOutputBytes')
-    }
-    this.ready = this.prepare()
-    void this.ready.catch(() => {})
-    ctx.effect(() => () => this.teardown(), 'E2B code-runtime teardown')
-  }
-
-  /* jscpd:ignore-start -- Seam-level abort and type-strip results remain identical across execution substrates. */
-  /** Execute one type-stripped program in a fresh E2B worker process. */
-  async run(request: CodeRunRequest): Promise<CodeRunResult> {
-    if (this.disposed) throw new Error('code-runtime-e2b: run() after disposal')
-    const bindings = this.validateBindings(request)
-    if (request.signal?.aborted === true) {
-      return this.failure({ kind: 'abort', message: String(request.signal.reason) })
-    }
-    let code: string
-    try {
-      const stripped = stripTypeScriptTypes(STRIP_WRAP.prefix + request.program + STRIP_WRAP.suffix)
-      code = stripped.slice(STRIP_WRAP.prefix.length, stripped.length - STRIP_WRAP.suffix.length)
-    } catch (error: unknown) {
-      return this.failure({ kind: 'exception', message: messageOf(error) })
-    }
-    let runtime: PreparedRuntime | undefined
-    try {
-      runtime = await this.awaitPreparation(request.signal)
-    } catch (error: unknown) {
-      // Disposal can race the awaited setup despite the synchronous precheck.
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
-      return this.failure({ kind: 'worker-exit', message: `E2B runtime setup failed: ${messageOf(error)}` })
-    }
-    if (runtime === undefined) {
-      return this.failure({ kind: 'abort', message: String(request.signal?.reason) })
-    }
-    // Disposal can race the awaited remote setup after the pre-await check.
-    /* v8 ignore start -- requires disposal between promise resolution and its awaiting continuation. */
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
-    /* v8 ignore stop */
-    return await this.execute(request, code, bindings, runtime)
-  }
-  /* jscpd:ignore-end */
-
-  private async awaitPreparation(signal: AbortSignal | undefined): Promise<PreparedRuntime | undefined> {
-    if (signal === undefined) return await this.ready
-    const aborted = Promise.withResolvers<undefined>()
-    const onAbort = (): void => { aborted.resolve(undefined) }
-    signal.addEventListener('abort', onAbort, { once: true })
-    if (signal.aborted) {
-      signal.removeEventListener('abort', onAbort)
-      return undefined
-    }
-    try {
-      return await Promise.race([this.ready, aborted.promise])
-    } finally {
-      signal.removeEventListener('abort', onAbort)
-    }
-  }
-
-  private assertPreparationActive(): void {
-    if (this.disposed) throw new Error('code-runtime-e2b: runtime disposed during setup')
-  }
-
-  private async prepare(): Promise<PreparedRuntime> {
-    const sandbox = await this.ctx.e2b.getSandbox()
-    this.assertPreparationActive()
-    const runner = posix.join(this.ctx.e2b.runtimeRoot, 'code-runtime-runner.mjs')
-    await sandbox.files.write([{ path: runner, data: CODE_RUNNER_SOURCE }])
-    this.assertPreparationActive()
-    await sandbox.commands.run(`chmod 600 -- ${quoteE2BShellArg(runner)}`)
-    this.assertPreparationActive()
-    const node = await resolveE2BExecutable(sandbox, 'node')
-    this.assertPreparationActive()
-    return { node, runner }
-  }
-
-  private failure(error: CodeRunFailure): CodeRunResult {
-    return new OutputLedger(this.config.maxOutputBytes).failure([], error)
-  }
-
-  /* jscpd:ignore-start -- Binding names have one seam contract while dispatch and teardown remain backend-owned. */
-  private validateBindings(request: CodeRunRequest): Map<string, CodeBindingNamespace> {
-    const bindings = new Map<string, CodeBindingNamespace>()
-    for (const namespace of request.bindings) {
-      if (!IDENTIFIER.test(namespace.global) || RESERVED_WORDS.has(namespace.global)) {
-        throw new Error(`code-runtime-e2b: binding global ${JSON.stringify(namespace.global)} is not a usable identifier`)
-      }
-      if (namespace.global === 'console' || bindings.has(namespace.global)) {
-        throw new Error(`code-runtime-e2b: duplicate binding global ${JSON.stringify(namespace.global)}`)
-      }
-      bindings.set(namespace.global, namespace)
-    }
-    const errorClassNames = new Set<string>()
-    for (const namespace of request.bindings) {
-      const descriptor = namespace.errorClass
-      if (descriptor === undefined) continue
-      if (!IDENTIFIER.test(descriptor.name) || RESERVED_WORDS.has(descriptor.name)) {
-        throw new Error(`code-runtime-e2b: binding error class ${JSON.stringify(descriptor.name)} is not a usable identifier`)
-      }
-      if (descriptor.name === 'console' || bindings.has(descriptor.name) || errorClassNames.has(descriptor.name)) {
-        throw new Error(`code-runtime-e2b: duplicate injected global ${JSON.stringify(descriptor.name)}`)
-      }
-      if (descriptor.memberNameProperty.length === 0 || RESERVED_ERROR_PROPERTIES.has(descriptor.memberNameProperty)) {
-        throw new Error(`code-runtime-e2b: binding error member property ${JSON.stringify(descriptor.memberNameProperty)} is not usable`)
-      }
-      errorClassNames.add(descriptor.name)
-    }
-    return bindings
-  }
-  /* jscpd:ignore-end */
-
-  private async execute(
-    request: CodeRunRequest,
-    code: string,
-    bindings: Map<string, CodeBindingNamespace>,
-    runtime: PreparedRuntime,
-  ): Promise<CodeRunResult> {
-    let handle: SubprocessHandle
-    try {
-      handle = this.subprocess.spawn({
-        argv: [runtime.node, runtime.runner],
-        cwd: this.ctx.e2b.cwd,
-        stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: this.config.maxOutputBytes } },
-        graceMs: this.config.killGraceMs,
-        ...request.signal === undefined ? {} : { signal: request.signal },
-        env: {},
-      })
-    } catch (error: unknown) {
-      if (this.disposed) return this.failure({ kind: 'abort', message: 'runtime disposed' })
-      if (request.signal?.aborted === true) {
-        return this.failure({ kind: 'abort', message: String(request.signal.reason) })
-      }
-      return this.failure({ kind: 'worker-exit', message: `E2B runtime spawn failed: ${messageOf(error)}` })
-    }
-    if (handle.stdin === undefined || handle.stdout === undefined) {
-      handle.terminate()
-      await Promise.allSettled([handle.done])
-      try {
-        await handle.waitForExit()
-      } catch (error: unknown) {
-        return this.failure({ kind: 'worker-exit', message: `E2B runtime cleanup failed: ${messageOf(error)}` })
-      }
-      return this.failure({ kind: 'worker-exit', message: 'E2B subprocess dropped a piped runtime stream' })
-    }
-    const stdin = handle.stdin
-    const stdout = handle.stdout
-
-    return new Promise<CodeRunResult>((resolve) => {
-      const output = new OutputLedger(this.config.maxOutputBytes)
-      const logs: string[] = []
-      const answered = new Set<number>()
-      const decoder = new E2BFrameDecoder(this.config.maxFrameBytes)
-      let settled = false
-      let finishResolve!: () => void
-      const finished = new Promise<void>((done) => { finishResolve = done })
-      const wallTimer: { current: NodeJS.Timeout | undefined } = { current: undefined }
-      const live: LiveRun = {
-        finished,
-        settle: (failure) => { finish(() => output.failure(logs, failure)) },
-      }
-
-      const finish = (result: CodeRunResult | (() => CodeRunResult)): void => {
-        if (settled) return
-        settled = true
-        clearTimeout(wallTimer.current)
-        request.signal?.removeEventListener('abort', onAbort)
-        void new Promise<void>((resume) => { setImmediate(resume) }).then(async () => {
-          handle.terminate()
-          await handle.done.catch(() => {})
-          let cleanupError: unknown
-          try {
-            await handle.waitForExit()
-          } catch (error: unknown) {
-            cleanupError = error
-          }
-          try {
-            decoder.finish()
-          } catch (error: unknown) {
-            result = output.failure(logs, { kind: 'worker-exit', message: messageOf(error) })
-          }
-          if (cleanupError !== undefined) {
-            result = output.failure(logs, { kind: 'worker-exit', message: `E2B runtime cleanup failed: ${messageOf(cleanupError)}` })
-          }
-          const final = typeof result === 'function' ? result() : result
-          this.live.delete(live)
-          finishResolve()
-          resolve(final)
-        })
-      }
-
-      const sendReply = (message: unknown): void => {
-        if (settled) return
-        let frame: string
-        try {
-          frame = encodeBoundedE2BFrame(message, this.config.maxFrameBytes)
-        } catch (error: unknown) {
-          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge failed: ${messageOf(error)}` }))
-          return
-        }
-        stdin.write(frame, (error?: Error | null) => {
-          if (error !== undefined && error !== null) {
-            finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge write failed: ${error.message}` }))
-          }
-        })
-      }
-
-      /* jscpd:ignore-start -- Host binding resolution mirrors worker semantics over a different transport. */
-      const onCall = (message: CallMessage): void => {
-        if (answered.has(message.id)) return
-        answered.add(message.id)
-        const functions = bindings.get(message.global)?.functions
-        const fn = functions !== undefined && Object.hasOwn(functions, message.name) ? functions[message.name] : undefined
-        if (typeof fn !== 'function') {
-          sendReply({ type: 'reply', id: message.id, ok: false, message: `unknown binding ${JSON.stringify(`${message.global}.${message.name}`)}` })
-          return
-        }
-        const args = decodeWorkerJson(message.args)
-        if (args === undefined) {
-          sendReply({ type: 'reply', id: message.id, ok: false, message: 'binding arguments must be lossless JSON' })
-          return
-        }
-        void (async () => {
-          try {
-            const resolved = await fn(args)
-            let value: CodeJsonValue | undefined
-            try {
-              value = snapshotJsonValue(resolved)
-            } catch {
-              value = undefined
-            }
-            if (value === undefined) {
-              sendReply({ type: 'reply', id: message.id, ok: false, message: 'binding resolution must be lossless JSON' })
-            } else {
-              sendReply({ type: 'reply', id: message.id, ok: true, value: encodeWorkerJson(value) })
-            }
-          } catch (error: unknown) {
-            sendReply({ type: 'reply', id: message.id, ok: false, message: messageOf(error) })
-          }
-        })()
-      }
-      /* jscpd:ignore-end */
-
-      const onMessage = (raw: unknown): void => {
-        if (settled) return
-        const message = parseRunnerMessage(raw)
-        if (message === undefined) return
-        if (message.type === 'log') {
-          if (!output.admit(message.text, logs)) finish(output.limit([...logs, message.text]))
-          return
-        }
-        if (message.type === 'output-limit') {
-          finish(output.limit(logs))
-          return
-        }
-        if (message.type === 'call') {
-          onCall(message)
-          return
-        }
-        if (message.error !== undefined) {
-          finish(() => output.failure(logs, message.error as CodeRunFailure))
-        } else if (message.value === undefined) {
-          finish(() => output.success(logs))
-        } else {
-          const value = decodeWorkerJson(message.value)
-          if (value === undefined) finish(() => output.failure(logs, { kind: 'invalid-output', message: 'program completion must be lossless JSON' }))
-          else finish(() => output.success(logs, value))
-        }
-      }
-
-      stdout.on('data', (chunk: Buffer) => {
-        if (settled) return
-        try {
-          for (const frame of decoder.push(chunk.toString('utf8'))) onMessage(frame)
-        } catch (error: unknown) {
-          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime bridge failed: ${messageOf(error)}` }))
-        }
-      })
-      stdout.on('error', (error: Error) => {
-        finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime stdout failed: ${error.message}` }))
-      })
-      stdin.on('error', (error: Error) => {
-        finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime stdin failed: ${error.message}` }))
-      })
-      void handle.done.then(
-        () => {
-          if (!settled) {
-            const stderr = handle.collected.stderr?.readFrom(0).text.trim()
-            finish(() => output.failure(logs, { kind: 'worker-exit', message: stderr === undefined || stderr === '' ? 'E2B runtime exited before completing' : `E2B runtime exited before completing: ${stderr}` }))
-          }
-        },
-        (error: unknown) => {
-          finish(() => output.failure(logs, { kind: 'worker-exit', message: `E2B runtime spawn failed: ${messageOf(error)}` }))
-        },
-      )
-
-      const onAbort = (): void => {
-        finish(() => output.failure(logs, { kind: 'abort', message: String(request.signal?.reason) }))
-      }
-      request.signal?.addEventListener('abort', onAbort, { once: true })
-      wallTimer.current = setTimeout(() => {
-        finish(() => output.failure(logs, { kind: 'timeout', message: `wall-clock ceiling reached (${this.config.maxWallMs}ms)` }))
-      }, this.config.maxWallMs)
-      this.live.add(live)
-      if (request.signal?.aborted === true) {
-        onAbort()
-        return
-      }
-      sendReply({
-        type: 'boot',
-        code,
-        namespaces: [...bindings].map(([global, namespace]) => ({
-          global,
-          names: Object.keys(namespace.functions),
-          ...namespace.errorClass === undefined ? {} : { errorClass: namespace.errorClass },
-        })),
-        computeMs: this.config.computeMs,
-        maxOutputBytes: this.config.maxOutputBytes,
-        maxOldGenerationSizeMb: this.config.maxOldGenerationSizeMb,
-      })
-    })
-  }
-
-  /* jscpd:ignore-start -- Code-runtime backends share the service lifecycle but own different child identities. */
-  private async teardown(): Promise<void> {
-    this.disposed = true
-    const runs = [...this.live]
-    for (const run of runs) run.settle({ kind: 'abort', message: 'runtime disposed' })
-    await Promise.all([
-      this.ready.then(() => {}, () => {}),
-      ...runs.map(run => run.finished),
-    ])
-  }
-  /* jscpd:ignore-end */
-}
-
-export default E2BCodeRuntime
diff --git a/packages/e2b/code-runtime-e2b/src/invariant.ts b/packages/e2b/code-runtime-e2b/src/invariant.ts
deleted file mode 100644
index 4112cdc76b..0000000000
--- a/packages/e2b/code-runtime-e2b/src/invariant.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-code-runtime-e2b`. */
-
-/* jscpd:ignore-start */
-import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-code-runtime-e2b'
-
-/** Cordis companion plugin name. */
-export const name = 'code-runtime-e2b-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/** No runtime invariant: the service owns every one-shot remote run. */
-const install: InvariantInstaller = () => {}
-
-/** Register this package's invariant companion. */
-export const apply = (ctx: Context): Promise<() => void> =>
-  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-/* jscpd:ignore-end */
diff --git a/packages/e2b/code-runtime-e2b/src/runner-source.ts b/packages/e2b/code-runtime-e2b/src/runner-source.ts
deleted file mode 100644
index 527f21114e..0000000000
--- a/packages/e2b/code-runtime-e2b/src/runner-source.ts
+++ /dev/null
@@ -1,649 +0,0 @@
-/** Dependency-free remote code runner installed inside the E2B sandbox. */
-
-/** Node program that runs one model program in a fresh remote worker thread. */
-export const CODE_RUNNER_SOURCE = String.raw`import { Buffer } from 'node:buffer'
-import { fork } from 'node:child_process'
-import { inspect } from 'node:util'
-import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads'
-import { createInterface } from 'node:readline'
-import { fileURLToPath } from 'node:url'
-
-const emitFrame = message => {
-  process.stdout.write(Buffer.from(JSON.stringify(message)).toString('base64') + '\n')
-}
-
-const parseFrame = line => JSON.parse(Buffer.from(line, 'base64').toString('utf8'))
-
-const waitForPipeDrain = stream => {
-  if (stream.readableEnded || stream.destroyed) return Promise.resolve()
-  return new Promise(resolve => {
-    const done = () => {
-      stream.off('end', done)
-      stream.off('close', done)
-      stream.off('error', done)
-      resolve()
-    }
-    stream.once('end', done)
-    stream.once('close', done)
-    stream.once('error', done)
-    if (stream.readableEnded || stream.destroyed) done()
-  })
-}
-
-const waitForChildExit = child => {
-  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
-  return new Promise(resolve => { child.once('exit', resolve) })
-}
-
-const killControllerGroup = child => {
-  if (process.platform !== 'win32' && Number.isSafeInteger(child.pid)) {
-    try {
-      process.kill(-child.pid, 'SIGKILL')
-    } catch (error) {
-      if (!error || typeof error !== 'object' || error.code !== 'ESRCH') throw error
-    }
-    return
-  }
-  child.kill('SIGKILL')
-}
-
-const jsonStringBytes = text => Buffer.byteLength(JSON.stringify(text))
-
-const truncateLog = (text, available) => {
-  if (available < 2) return ''
-  let result = ''
-  let bytes = 2
-  for (const character of text) {
-    const cost = jsonStringBytes(character) - 2
-    if (bytes + cost > available) break
-    bytes += cost
-    result += character
-  }
-  return result
-}
-
-const runLauncher = () => {
-  const input = createInterface({ input: process.stdin, crlfDelay: Infinity })
-  let controller
-  let maxOutputBytes = 0
-  let logBytes = 2
-  let logEntries = 0
-  let settling = false
-  let closed = false
-  let terminal
-
-  const finish = message => {
-    if (settling) {
-      if (message.type === 'output-limit') terminal = message
-      return
-    }
-    settling = true
-    terminal = message
-    const current = controller
-    controller = undefined
-    const drain = current
-      ? new Promise(resolve => { setImmediate(resolve) }).then(async () => {
-          const stdoutDrained = waitForPipeDrain(current.stdout)
-          const stderrDrained = waitForPipeDrain(current.stderr)
-          const exited = waitForChildExit(current)
-          killControllerGroup(current)
-          await Promise.all([exited, stdoutDrained, stderrDrained])
-        })
-      : Promise.resolve()
-    void drain.catch(error => {
-      process.stderr.write('code-runtime-e2b controller cleanup error: ' + String(error) + '\n')
-    }).then(() => {
-      closed = true
-      emitFrame(terminal)
-      input.close()
-      process.stdin.destroy()
-    })
-  }
-
-  const forwardLog = text => {
-    if (closed || terminal?.type === 'output-limit') return
-    const separator = logEntries > 0 ? 1 : 0
-    const available = maxOutputBytes - logBytes - separator
-    const cost = jsonStringBytes(text)
-    if (cost > available) {
-      const prefix = truncateLog(text, available)
-      if (prefix) {
-        logBytes += jsonStringBytes(prefix) + separator
-        logEntries += 1
-        emitFrame({ type: 'log', text: prefix })
-      }
-      finish({ type: 'output-limit' })
-      return
-    }
-    logBytes += cost + separator
-    logEntries += 1
-    emitFrame({ type: 'log', text })
-  }
-
-  const startController = message => {
-    maxOutputBytes = message.maxOutputBytes
-    controller = fork(fileURLToPath(import.meta.url), [], {
-      env: { DSH_CODE_RUNTIME_CONTROLLER: '1' },
-      detached: process.platform !== 'win32',
-      execArgv: [],
-      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
-    })
-    const current = controller
-    current.stdout.on('data', data => { forwardLog(data.toString('utf8')) })
-    current.stderr.on('data', data => { forwardLog(data.toString('utf8')) })
-    current.on('message', raw => {
-      if (!raw || typeof raw !== 'object') return
-      if (raw.type === 'log' && typeof raw.text === 'string') {
-        forwardLog(raw.text)
-        return
-      }
-      if (settling) return
-      if (raw.type === 'call' && typeof raw.id === 'number' && typeof raw.global === 'string' && typeof raw.name === 'string' && Array.isArray(raw.args)) {
-        emitFrame({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
-      } else if (raw.type === 'output-limit') {
-        finish({ type: 'output-limit' })
-      } else if (raw.type === 'done') {
-        if (raw.error && typeof raw.error === 'object' && typeof raw.error.kind === 'string' && typeof raw.error.message === 'string') {
-          finish({ type: 'done', error: { kind: raw.error.kind, message: raw.error.message } })
-        } else if (raw.value === undefined || Array.isArray(raw.value)) {
-          finish({ type: 'done', ...(raw.value === undefined ? {} : { value: raw.value }) })
-        }
-      }
-    })
-    current.on('error', error => {
-      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller error: ' + error.message } })
-    })
-    current.on('exit', code => {
-      if (!settling) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller exited with code ' + code + ' before completing' } })
-    })
-    current.send(message, error => {
-      if (error) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller boot failed: ' + error.message } })
-    })
-  }
-
-  input.on('line', line => {
-    let message
-    try {
-      message = parseFrame(line)
-    } catch (error) {
-      process.stderr.write('code-runtime-e2b frame error: ' + String(error) + '\n')
-      finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received a malformed frame' } })
-      return
-    }
-    if (!controller) {
-      if (!message || message.type !== 'boot' || typeof message.code !== 'string' || !Array.isArray(message.namespaces) || !Number.isSafeInteger(message.maxOutputBytes) || message.maxOutputBytes < 4) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote runner received an invalid boot frame' } })
-        return
-      }
-      startController(message)
-      return
-    }
-    if (message && message.type === 'reply' && typeof message.id === 'number' && typeof message.ok === 'boolean') {
-      controller.send(message.ok
-        ? { type: 'reply', id: message.id, ok: true, value: message.value }
-        : { type: 'reply', id: message.id, ok: false, message: String(message.message) }, error => {
-          if (error) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller reply failed: ' + error.message } })
-        })
-    }
-  })
-  input.on('close', () => { if (controller && !settling) killControllerGroup(controller) })
-}
-
-const runController = () => {
-  let worker
-  let finished = false
-  let computeTimer
-  const send = message => {
-    if (process.send) process.send(message)
-  }
-  const finish = message => {
-    if (finished) return
-    finished = true
-    clearInterval(computeTimer)
-    const current = worker
-    worker = undefined
-    const drain = current
-      ? new Promise(resolve => { setImmediate(resolve) }).then(async () => {
-          const stdoutDrained = waitForPipeDrain(current.stdout)
-          const stderrDrained = waitForPipeDrain(current.stderr)
-          await Promise.all([current.terminate(), stdoutDrained, stderrDrained])
-        })
-      : Promise.resolve()
-    void drain.catch(error => {
-      send({ type: 'log', text: 'code-runtime-e2b worker cleanup error: ' + String(error) + '\n' })
-    }).then(() => {
-      if (!process.send) {
-        process.exitCode = 1
-        return
-      }
-      process.send(message, () => { if (process.connected) process.disconnect() })
-    })
-  }
-  process.on('message', message => {
-    if (!worker) {
-      if (!message || message.type !== 'boot' || typeof message.code !== 'string' || !Array.isArray(message.namespaces)) {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote controller received an invalid boot frame' } })
-        return
-      }
-      worker = new Worker(new URL(import.meta.url), {
-        workerData: message,
-        env: {},
-        execArgv: [],
-        stdout: true,
-        stderr: true,
-        resourceLimits: { maxOldGenerationSizeMb: message.maxOldGenerationSizeMb },
-      })
-      worker.stdout.on('data', data => { send({ type: 'log', text: data.toString('utf8') }) })
-      worker.stderr.on('data', data => { send({ type: 'log', text: data.toString('utf8') }) })
-      worker.on('message', raw => {
-        if (!raw || typeof raw !== 'object') return
-        if (raw.type === 'call' && typeof raw.id === 'number' && typeof raw.global === 'string' && typeof raw.name === 'string' && Array.isArray(raw.args)) {
-          send({ type: 'call', id: raw.id, global: raw.global, name: raw.name, args: raw.args })
-        } else if (raw.type === 'log' && typeof raw.text === 'string') {
-          send({ type: 'log', text: raw.text })
-        } else if (raw.type === 'output-limit') {
-          finish({ type: 'output-limit' })
-        } else if (raw.type === 'done') {
-          if (raw.error && typeof raw.error === 'object' && typeof raw.error.kind === 'string' && typeof raw.error.message === 'string') {
-            finish({ type: 'done', error: { kind: raw.error.kind, message: raw.error.message } })
-          } else if (raw.value === undefined || Array.isArray(raw.value)) {
-            finish({ type: 'done', ...(raw.value === undefined ? {} : { value: raw.value }) })
-          }
-        }
-      })
-      worker.on('error', error => {
-        finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote worker error: ' + error.message } })
-      })
-      worker.on('exit', code => {
-        if (!finished) finish({ type: 'done', error: { kind: 'worker-exit', message: 'remote worker exited with code ' + code + ' before completing' } })
-      })
-      computeTimer = setInterval(() => {
-        if (!worker) return
-        if (worker.performance.eventLoopUtilization().active > message.computeMs) {
-          finish({ type: 'done', error: { kind: 'timeout', message: 'compute budget exhausted (' + message.computeMs + 'ms busy)' } })
-        }
-      }, 25)
-      return
-    }
-    if (message && message.type === 'reply' && typeof message.id === 'number' && typeof message.ok === 'boolean') {
-      worker.postMessage(message.ok
-        ? { type: 'reply', id: message.id, ok: true, value: message.value }
-        : { type: 'reply', id: message.id, ok: false, message: String(message.message) })
-    }
-  })
-  process.on('disconnect', () => { if (worker && !finished) void worker.terminate() })
-}
-
-if (!isMainThread) {
-  const port = parentPort
-  if (!port) throw new Error('remote worker requires parentPort')
-
-  const CapturedError = Error
-  const ArrayIsArray = Array.isArray
-  const ArrayPrototype = Array.prototype
-  const ObjectPrototype = Object.prototype
-  const ObjectCreate = Object.create
-  const ObjectDefineProperty = Object.defineProperty
-  const ObjectGetPrototypeOf = Object.getPrototypeOf
-  const ObjectHasOwn = Object.hasOwn
-  const ObjectKeys = Object.keys
-  const ObjectIs = Object.is
-  const ObjectPropertyIsEnumerable = Object.prototype.propertyIsEnumerable
-  const ReflectOwnKeys = Reflect.ownKeys
-  const ReflectApply = Reflect.apply
-  const NumberIsFinite = Number.isFinite
-  const NumberIsSafeInteger = Number.isSafeInteger
-  const PromiseCtor = Promise
-  const PromiseReject = Promise.reject
-  const QueueMicrotask = queueMicrotask
-  const BufferByteLength = Buffer.byteLength
-  const SetCtor = Set
-  const SetAdd = Set.prototype.add
-  const SetDelete = Set.prototype.delete
-  const SetHas = Set.prototype.has
-  const MapDelete = Map.prototype.delete
-  const MapGet = Map.prototype.get
-  const MapSet = Map.prototype.set
-  const ArrayJoin = Array.prototype.join
-  const ArrayPop = Array.prototype.pop
-  const StringCharCodeAt = String.prototype.charCodeAt
-  const StringSlice = String.prototype.slice
-  const JSONStringify = JSON.stringify
-  const StringValue = String
-
-  const define = (target, key, value) => {
-    const descriptor = ObjectCreate(null)
-    descriptor.value = value
-    descriptor.enumerable = true
-    descriptor.configurable = true
-    descriptor.writable = true
-    ObjectDefineProperty(target, key, descriptor)
-  }
-  const append = (target, value) => { define(target, target.length, value) }
-  const pop = target => ReflectApply(ArrayPop, target, [])
-  const setAdd = (target, value) => { ReflectApply(SetAdd, target, [value]) }
-  const setDelete = (target, value) => { ReflectApply(SetDelete, target, [value]) }
-  const setHas = (target, value) => ReflectApply(SetHas, target, [value])
-  const mapDelete = (target, key) => { ReflectApply(MapDelete, target, [key]) }
-  const mapGet = (target, key) => ReflectApply(MapGet, target, [key])
-  const mapSet = (target, key, value) => { ReflectApply(MapSet, target, [key, value]) }
-  const plainObject = value => {
-    const prototype = ObjectGetPrototypeOf(value)
-    return prototype === null || prototype === ObjectPrototype
-  }
-  const ownEnumerableStringKeys = value => {
-    const keys = ReflectOwnKeys(value)
-    for (let index = 0; index < keys.length; index++) {
-      const key = keys[index]
-      if (typeof key !== 'string' || !ReflectApply(ObjectPropertyIsEnumerable, value, [key])) return undefined
-    }
-    return keys
-  }
-  const assign = (destination, value) => {
-    if (destination.kind === 'root') destination.holder.value = value
-    else define(destination.target, destination.key, value)
-  }
-  const snapshot = input => {
-    const active = new SetCtor()
-    const holder = ObjectCreate(null)
-    const tasks = [{ kind: 'visit', value: input, destination: { kind: 'root', holder } }]
-    while (tasks.length) {
-      const task = pop(tasks)
-      if (task.kind === 'leave') { setDelete(active, task.source); continue }
-      const candidate = task.value
-      if (candidate === null || typeof candidate === 'boolean' || typeof candidate === 'string') {
-        assign(task.destination, candidate); continue
-      }
-      if (typeof candidate === 'number') {
-        if (!NumberIsFinite(candidate) || ObjectIs(candidate, -0)) return undefined
-        assign(task.destination, candidate); continue
-      }
-      if (typeof candidate !== 'object' || setHas(active, candidate)) return undefined
-      if (ArrayIsArray(candidate)) {
-        if (ObjectGetPrototypeOf(candidate) !== ArrayPrototype || ReflectOwnKeys(candidate).length !== candidate.length + 1) return undefined
-        const target = []
-        assign(task.destination, target)
-        setAdd(active, candidate)
-        append(tasks, { kind: 'leave', source: candidate })
-        for (let index = candidate.length - 1; index >= 0; index--) {
-          if (!ObjectHasOwn(candidate, index)) return undefined
-          append(tasks, { kind: 'visit', value: candidate[index], destination: { kind: 'slot', target, key: index } })
-        }
-        continue
-      }
-      if (!plainObject(candidate)) return undefined
-      const keys = ownEnumerableStringKeys(candidate)
-      if (!keys) return undefined
-      const target = {}
-      assign(task.destination, target)
-      setAdd(active, candidate)
-      append(tasks, { kind: 'leave', source: candidate })
-      for (let index = keys.length - 1; index >= 0; index--) {
-        const key = keys[index]
-        append(tasks, { kind: 'visit', value: candidate[key], destination: { kind: 'slot', target, key } })
-      }
-    }
-    return holder.value
-  }
-  const encodeWire = value => {
-    const wire = []
-    const pending = [value]
-    while (pending.length) {
-      const current = pop(pending)
-      if (current === null || typeof current === 'boolean' || typeof current === 'number' || typeof current === 'string') {
-        append(wire, current); continue
-      }
-      if (ArrayIsArray(current)) {
-        append(wire, { kind: 'array', length: current.length })
-        for (let index = current.length - 1; index >= 0; index--) append(pending, current[index])
-      } else {
-        const keys = ObjectKeys(current)
-        append(wire, { kind: 'object', keys })
-        for (let index = keys.length - 1; index >= 0; index--) append(pending, current[keys[index]])
-      }
-    }
-    return wire
-  }
-  const decodeWire = wire => {
-    if (!ArrayIsArray(wire) || wire.length === 0) return undefined
-    const frames = []
-    let root
-    let assigned = false
-    const attach = value => {
-      const parent = frames[frames.length - 1]
-      if (!parent) {
-        if (assigned) return false
-        root = value; assigned = true; return true
-      }
-      if (parent.kind === 'array') append(parent.target, value)
-      else define(parent.target, parent.keys[parent.index], value)
-      parent.index += 1
-      return true
-    }
-    for (let tokenIndex = 0; tokenIndex < wire.length; tokenIndex++) {
-      const token = wire[tokenIndex]
-      let value
-      let frame
-      if (token === null || typeof token === 'boolean' || typeof token === 'string') value = token
-      else if (typeof token === 'number') {
-        if (!NumberIsFinite(token) || ObjectIs(token, -0)) return undefined
-        value = token
-      } else {
-        if (!plainObject(token)) return undefined
-        const keys = ownEnumerableStringKeys(token)
-        if (!keys || keys.length !== 2 || keys[0] !== 'kind') return undefined
-        if (token.kind === 'array' && keys[1] === 'length' && NumberIsSafeInteger(token.length) && token.length >= 0) {
-          value = []
-          if (token.length > wire.length - tokenIndex - 1) return undefined
-          if (token.length) frame = { kind: 'array', target: value, length: token.length, index: 0 }
-        } else if (token.kind === 'object' && keys[1] === 'keys' && ArrayIsArray(token.keys)) {
-          const unique = new SetCtor()
-          const objectKeys = []
-          for (const key of token.keys) {
-            if (typeof key !== 'string' || setHas(unique, key)) return undefined
-            setAdd(unique, key); append(objectKeys, key)
-          }
-          if (objectKeys.length > wire.length - tokenIndex - 1) return undefined
-          value = {}
-          if (objectKeys.length) frame = { kind: 'object', target: value, keys: objectKeys, index: 0 }
-        } else return undefined
-      }
-      if (!attach(value)) return undefined
-      if (frame) append(frames, frame)
-      while (frames.length) {
-        const current = frames[frames.length - 1]
-        const length = current.kind === 'array' ? current.length : current.keys.length
-        if (current.index < length) break
-        pop(frames)
-      }
-    }
-    return frames.length === 0 ? root : undefined
-  }
-  const byteLength = text => ReflectApply(BufferByteLength, Buffer, [text])
-  const jsonStringBytes = text => byteLength(JSONStringify(text))
-  const jsonValueBytes = value => {
-    let bytes = 0
-    const tasks = [{ kind: 'value', value }]
-    while (tasks.length) {
-      const task = pop(tasks)
-      if (task.kind === 'separator') { bytes += 1; continue }
-      if (task.kind === 'key') { bytes += jsonStringBytes(task.value) + 1; continue }
-      const current = task.value
-      if (current === null) bytes += 4
-      else if (typeof current === 'string') bytes += jsonStringBytes(current)
-      else if (typeof current === 'number' || typeof current === 'boolean') bytes += byteLength(StringValue(current))
-      else if (ArrayIsArray(current)) {
-        bytes += 2
-        for (let index = current.length - 1; index >= 0; index--) {
-          append(tasks, { kind: 'value', value: current[index] })
-          if (index > 0) append(tasks, { kind: 'separator' })
-        }
-      } else {
-        bytes += 2
-        const keys = ObjectKeys(current)
-        for (let index = keys.length - 1; index >= 0; index--) {
-          const key = keys[index]
-          append(tasks, { kind: 'value', value: current[key] })
-          append(tasks, { kind: 'key', value: key })
-          if (index > 0) append(tasks, { kind: 'separator' })
-        }
-      }
-    }
-    return bytes
-  }
-  const truncate = (text, available) => {
-    if (available < 2) return ''
-    let result = ''
-    let bytes = 2
-    let index = 0
-    while (index < text.length) {
-      const first = ReflectApply(StringCharCodeAt, text, [index])
-      let end = index + 1
-      if (first >= 0xd800 && first <= 0xdbff && end < text.length) {
-        const second = ReflectApply(StringCharCodeAt, text, [end])
-        if (second >= 0xdc00 && second <= 0xdfff) end += 1
-      }
-      const character = ReflectApply(StringSlice, text, [index, end])
-      const cost = jsonStringBytes(character) - 2
-      if (bytes + cost > available) break
-      bytes += cost
-      result += character
-      index = end
-    }
-    return result
-  }
-  let logBytes = 2
-  let logEntries = 0
-  let limited = false
-  const pushLog = text => {
-    if (limited) return
-    const separator = logEntries > 0 ? 1 : 0
-    const available = workerData.maxOutputBytes - logBytes - separator
-    const cost = jsonStringBytes(text)
-    if (cost > available) {
-      const prefix = truncate(text, available)
-      if (prefix) {
-        logBytes += jsonStringBytes(prefix) + separator
-        logEntries += 1
-        port.postMessage({ type: 'log', text: prefix })
-      }
-      limited = true
-      port.postMessage({ type: 'output-limit' })
-      return
-    }
-    logBytes += cost + separator
-    logEntries += 1
-    port.postMessage({ type: 'log', text })
-  }
-  const originalStdout = process.stdout.write
-  const originalStderr = process.stderr.write
-  process.stdout.write = (chunk, ...rest) => {
-    pushLog(typeof chunk === 'string' ? chunk : StringValue(chunk))
-    let callback
-    for (let index = 0; index < rest.length; index++) {
-      if (typeof rest[index] === 'function') { callback = rest[index]; break }
-    }
-    if (callback) QueueMicrotask(() => { callback(null) })
-    return true
-  }
-  process.stderr.write = process.stdout.write
-  const consoleShim = ObjectCreate(null)
-  for (const level of ['log', 'info', 'warn', 'error', 'debug']) {
-    define(consoleShim, level, (...args) => {
-      const rendered = []
-      for (let index = 0; index < args.length; index++) {
-        const value = args[index]
-        append(rendered, typeof value === 'string' ? value : inspect(value, { depth: 4, maxArrayLength: 100, maxStringLength: 10000 }))
-      }
-      pushLog(ReflectApply(ArrayJoin, rendered, [' ']))
-    })
-  }
-  const pending = new Map()
-  let nextId = 1
-  const errorClasses = new Map()
-  for (const namespace of workerData.namespaces) {
-    if (!namespace.errorClass) continue
-    const descriptor = namespace.errorClass
-    mapSet(errorClasses, namespace.global, class BindingCallError extends CapturedError {
-      constructor(memberName, message) {
-        super(message)
-        ObjectDefineProperty(this, 'name', { value: descriptor.name, enumerable: true })
-        ObjectDefineProperty(this, descriptor.memberNameProperty, { value: memberName, enumerable: true })
-      }
-    })
-  }
-  port.on('message', message => {
-    if (!message || message.type !== 'reply' || typeof message.id !== 'number') return
-    const entry = mapGet(pending, message.id)
-    if (!entry) return
-    mapDelete(pending, message.id)
-    if (!message.ok) { entry.reject(new CapturedError(StringValue(message.message))); return }
-    const value = decodeWire(message.value)
-    if (value === undefined) entry.reject(new CapturedError('binding resolution must be lossless JSON'))
-    else entry.resolve(value)
-  })
-  const namespaces = workerData.namespaces.map(namespace => {
-    const target = ObjectCreate(null)
-    const ErrorClass = mapGet(errorClasses, namespace.global)
-    for (const name of namespace.names) {
-      define(target, name, args => {
-        const detached = snapshot(args)
-        if (detached === undefined) {
-          return ReflectApply(PromiseReject, PromiseCtor, [ErrorClass ? new ErrorClass(name, 'binding arguments must be lossless JSON') : new CapturedError('binding arguments must be lossless JSON')])
-        }
-        return new PromiseCtor((resolve, reject) => {
-          const id = nextId++
-          mapSet(pending, id, {
-            resolve,
-            reject: error => { reject(ErrorClass ? new ErrorClass(name, error.message) : error) },
-          })
-          port.postMessage({ type: 'call', id, global: namespace.global, name, args: encodeWire(detached) })
-        })
-      })
-    }
-    return target
-  })
-  const errorClassNames = []
-  const errorClassValues = []
-  for (const namespace of workerData.namespaces) {
-    if (!namespace.errorClass) continue
-    append(errorClassNames, namespace.errorClass.name)
-    append(errorClassValues, mapGet(errorClasses, namespace.global))
-  }
-  const AsyncFunction = ObjectGetPrototypeOf(async function () {}).constructor
-  try {
-    const fn = new AsyncFunction(...workerData.namespaces.map(value => value.global), ...errorClassNames, 'console', '"use strict";\n' + workerData.code)
-    const value = await fn(...namespaces, ...errorClassValues, consoleShim)
-    if (!limited) {
-      if (value === undefined) port.postMessage({ type: 'done' })
-      else {
-        const detached = snapshot(value)
-        if (detached === undefined) {
-          const message = 'program completion must be lossless JSON'
-          if (jsonStringBytes(message) > workerData.maxOutputBytes - logBytes) port.postMessage({ type: 'output-limit' })
-          else port.postMessage({ type: 'done', error: { kind: 'invalid-output', message } })
-        } else if (jsonValueBytes(detached) > workerData.maxOutputBytes - logBytes) {
-          port.postMessage({ type: 'output-limit' })
-        } else {
-          port.postMessage({ type: 'done', value: encodeWire(detached) })
-        }
-      }
-    }
-  } catch (error) {
-    if (!limited) {
-      let message
-      try { message = error instanceof CapturedError ? error.stack || error.message : StringValue(error) }
-      catch { message = 'program threw an unrenderable value' }
-      if (jsonStringBytes(message) > workerData.maxOutputBytes - logBytes) port.postMessage({ type: 'output-limit' })
-      else port.postMessage({ type: 'done', error: { kind: 'exception', message } })
-    }
-  } finally {
-    process.stdout.write = originalStdout
-    process.stderr.write = originalStderr
-  }
-} else if (process.env.DSH_CODE_RUNTIME_CONTROLLER === '1') {
-  runController()
-} else {
-  runLauncher()
-}
-`
diff --git a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts b/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
deleted file mode 100644
index f99485a929..0000000000
--- a/packages/e2b/code-runtime-e2b/tests/runtime.spec.ts
+++ /dev/null
@@ -1,765 +0,0 @@
-import { spawn } from 'node:child_process'
-import { access, mkdtemp, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { PassThrough, Writable } from 'node:stream'
-import { setTimeout as delay } from 'node:timers/promises'
-import { Context } from 'cordis'
-import { describe, expect, it, vi } from 'vitest'
-import type { Sandbox } from '@deepseek-ai/dsh-e2b'
-import {
-  E2BFrameDecoder,
-  encodeE2BFrame,
-} from '@deepseek-ai/dsh-e2b'
-import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import type {
-  SubprocessHandle,
-  SubprocessOutcome,
-  SubprocessSpawnSpec,
-} from '@deepseek-ai/dsh-subprocess'
-import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-import {
-  encodeWorkerJson,
-} from '@deepseek-ai/dsh-code-runtime-worker'
-import E2BCodeRuntime from '@deepseek-ai/dsh-code-runtime-e2b'
-import * as E2BCodeRuntimeInvariant from '../src/invariant.ts'
-import { CODE_RUNNER_SOURCE } from '../src/runner-source.ts'
-import InvariantService from '@deepseek-ai/dsh-invariants'
-
-class FakeHandle implements SubprocessHandle {
-  readonly pid = 123
-  readonly stdin: Writable | undefined
-  readonly stdout: PassThrough | undefined
-  readonly stderr = undefined
-  readonly collected: SubprocessHandle['collected']
-  readonly done: Promise<SubprocessOutcome>
-  readonly writes: unknown[] = []
-  readonly result = Promise.withResolvers<SubprocessOutcome>()
-  terminated = 0
-  waitCalls = 0
-  private readonly decoder = new E2BFrameDecoder(10_000_000)
-  private readonly waitError: Error | undefined
-  private readonly waitResult: Promise<boolean> | undefined
-  private settled = false
-
-  constructor(
-    private readonly onMessage: (message: unknown, handle: FakeHandle) => void = () => {},
-    options: {
-      stdin?: boolean
-      stdout?: boolean
-      stderr?: string
-      writeError?: Error
-      waitError?: Error
-      waitResult?: Promise<boolean>
-    } = {},
-  ) {
-    this.waitError = options.waitError
-    this.waitResult = options.waitResult
-    this.stdin = options.stdin === false
-      ? undefined
-      : options.writeError === undefined
-        ? new PassThrough()
-        : new Writable({ write: (_chunk, _encoding, callback) => { callback(options.writeError) } })
-    this.stdout = options.stdout === false ? undefined : new PassThrough()
-    this.collected = options.stderr === undefined
-      ? {}
-      : { stderr: { readFrom: () => ({ text: options.stderr as string, nextOffset: 0, lossy: false }) } }
-    this.done = this.result.promise
-    this.stdin?.on('data', (chunk: Buffer) => {
-      for (const message of this.decoder.push(chunk.toString('ascii'))) {
-        this.writes.push(message)
-        this.onMessage(message, this)
-      }
-    })
-  }
-
-  emit(message: unknown): void {
-    this.stdout?.write(encodeE2BFrame(message))
-  }
-
-  emitRaw(text: string): void {
-    this.stdout?.write(text)
-  }
-
-  exit(outcome: SubprocessOutcome = { exitCode: 0, signal: null }): void {
-    if (this.settled) return
-    this.settled = true
-    this.stdout?.end()
-    this.result.resolve(outcome)
-  }
-
-  crash(error: unknown): void {
-    if (this.settled) return
-    this.settled = true
-    this.stdout?.end()
-    this.result.reject(error)
-  }
-
-  terminate(): void {
-    this.terminated += 1
-    this.exit({ exitCode: null, signal: 'SIGTERM' })
-  }
-
-  async waitForExit(): Promise<boolean> {
-    this.waitCalls += 1
-    if (this.waitError !== undefined) throw this.waitError
-    if (this.waitResult !== undefined) return await this.waitResult
-    return true
-  }
-}
-
-interface RuntimeFixture {
-  ctx: Context
-  fiber: Awaited<ReturnType<Context['plugin']>>
-  runtime: E2BCodeRuntime
-  sandbox: Sandbox
-  spawn: ReturnType<typeof vi.fn<(spec: SubprocessSpawnSpec) => SubprocessHandle>>
-  write: ReturnType<typeof vi.fn>
-  run: ReturnType<typeof vi.fn>
-}
-
-async function setup(
-  handles: FakeHandle[] = [],
-  config: Record<string, number> = {},
-  sandboxOverrides: Partial<Sandbox> = {},
-  getSandbox?: () => Promise<Sandbox>,
-): Promise<RuntimeFixture> {
-  const write = vi.fn().mockResolvedValue([])
-  const run = vi.fn().mockImplementation(async (command: string) => ({
-    exitCode: 0,
-    stdout: command.startsWith('command -v') ? '/usr/bin/node\n' : '',
-    stderr: '',
-  }))
-  const sandbox = {
-    files: { write },
-    commands: { run },
-    ...sandboxOverrides,
-  } as unknown as Sandbox
-  const e2b = {
-    cwd: '/workspace',
-    runtimeRoot: '/workspace/.dsh-e2b',
-    getSandbox: getSandbox ?? (async () => sandbox),
-  } as unknown as E2BSandboxService
-  const spawn = vi.fn<(spec: SubprocessSpawnSpec) => SubprocessHandle>(() => {
-    const handle = handles.shift()
-    if (handle === undefined) throw new Error('no fake handle queued')
-    return handle
-  })
-  const subprocess = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
-  Object.defineProperty(subprocess, 'spawn', { value: spawn })
-  const ctx = new Context()
-  ctx.provide('e2b', e2b)
-  ctx.provide('subprocess', subprocess)
-  const fiber = await ctx.plugin(E2BCodeRuntime, config)
-  return { ctx, fiber, runtime: ctx.codeRuntime as E2BCodeRuntime, sandbox, spawn, write, run }
-}
-
-function request(program = 'return 1') {
-  return { program, bindings: [] }
-}
-
-async function runInstalledRunner(
-  code: string,
-  maxOutputBytes = 2_000_000,
-): Promise<{ messages: unknown[]; stderr: string }> {
-  const directory = await mkdtemp(join(tmpdir(), 'dsh-e2b-code-runner-'))
-  const runner = join(directory, 'runner.mjs')
-  await writeFile(runner, CODE_RUNNER_SOURCE)
-  const child = spawn(process.execPath, [runner], { stdio: ['pipe', 'pipe', 'pipe'] })
-  const decoder = new E2BFrameDecoder(4_000_000)
-  const messages: unknown[] = []
-  let stderr = ''
-  let outputError: unknown
-  child.stdout.setEncoding('ascii')
-  child.stdout.on('data', (chunk: string) => {
-    try {
-      messages.push(...decoder.push(chunk))
-    } catch (error: unknown) {
-      outputError = error
-      child.kill('SIGKILL')
-    }
-  })
-  child.stderr.setEncoding('utf8')
-  child.stderr.on('data', (chunk: string) => { stderr += chunk })
-
-  try {
-    child.stdin.write(encodeE2BFrame({
-      type: 'boot',
-      code,
-      namespaces: [],
-      computeMs: 1_000,
-      maxOutputBytes,
-      maxOldGenerationSizeMb: 128,
-    }))
-    await new Promise<void>((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        child.kill('SIGKILL')
-        reject(new Error('installed E2B code runner did not exit'))
-      }, 5_000)
-      child.once('error', (error) => {
-        clearTimeout(timeout)
-        reject(error)
-      })
-      child.once('exit', () => {
-        clearTimeout(timeout)
-        resolve()
-      })
-    })
-    if (outputError !== undefined) throw outputError
-    decoder.finish()
-    return { messages, stderr }
-  } finally {
-    child.kill('SIGKILL')
-    await rm(directory, { recursive: true, force: true })
-  }
-}
-
-describe('E2BCodeRuntime', () => {
-  it('keeps model-owned descriptors outside the host framing process', async () => {
-    const forged = Buffer.from(JSON.stringify({ type: 'done' })).toString('base64') + '\\n'
-    const { messages, stderr } = await runInstalledRunner(
-      `
-        const fs = await import('node:fs')
-        const childProcess = await import('node:child_process')
-        fs.writeSync(1, ${JSON.stringify(forged)})
-        childProcess.spawnSync(process.execPath, ['-e', 'process.stdout.write("child-native")'], { stdio: 'inherit' })
-        return true
-      `,
-    )
-    const records = messages as Array<{ type?: string; text?: string; value?: unknown }>
-    const terminal = records.filter(message => message.type === 'done')
-
-    expect(stderr).toBe('')
-    expect(terminal).toEqual([{ type: 'done', value: [true] }])
-    expect(records.at(-1)).toEqual(terminal[0])
-    expect(records.filter(message => message.type === 'log').map(message => message.text).join(''))
-      .toContain(forged + 'child-native')
-  })
-
-  it('bounds native descriptor output before it reaches the host protocol', async () => {
-    const { messages, stderr } = await runInstalledRunner(
-      "(await import('node:fs')).writeSync(1, 'x'.repeat(4096)); return true",
-      64,
-    )
-    const records = messages as Array<{ type?: string; text?: string }>
-
-    expect(stderr).toBe('')
-    expect(records.at(-1)).toEqual({ type: 'output-limit' })
-    expect(Buffer.byteLength(records.filter(message => message.type === 'log').map(message => message.text).join('')))
-      .toBeLessThanOrEqual(62)
-  })
-
-  it('drains native worker pipes before emitting the terminal frame', async () => {
-    const expectedBytes = 1_048_576
-    const { messages, stderr } = await runInstalledRunner(
-      `
-        let stdoutPrototype = Object.getPrototypeOf(process.stdout)
-        while (stdoutPrototype && !Object.hasOwn(stdoutPrototype, 'write')) stdoutPrototype = Object.getPrototypeOf(stdoutPrototype)
-        Reflect.apply(stdoutPrototype.write, process.stdout, ['x'.repeat(${expectedBytes})])
-        return true
-      `,
-    )
-    const records = messages as Array<{ type?: string; text?: string }>
-    const terminalIndex = records.findIndex(message => message.type === 'done')
-    const nativeOutput = records
-      .slice(0, terminalIndex)
-      .filter(message => message.type === 'log')
-      .map(message => message.text ?? '')
-      .join('')
-
-    expect(stderr).toBe('')
-    expect(terminalIndex).toBe(records.length - 1)
-    expect(Buffer.byteLength(nativeOutput)).toBe(expectedBytes)
-  })
-
-  it.skipIf(process.platform === 'win32')('reaps descendant-held controller pipes before completion', async () => {
-    const directory = await mkdtemp(join(tmpdir(), 'dsh-e2b-code-descendant-'))
-    const marker = join(directory, 'started')
-    const release = join(directory, 'release')
-    const childSource = `
-      const fs = require('node:fs')
-      fs.writeFileSync(${JSON.stringify(marker)}, 'started')
-      const timer = setInterval(() => {
-        if (fs.existsSync(${JSON.stringify(release)})) clearInterval(timer)
-      }, 10)
-    `
-    let running: ReturnType<typeof runInstalledRunner> | undefined
-    try {
-      running = runInstalledRunner(`
-        const fs = await import('node:fs')
-        const childProcess = await import('node:child_process')
-        childProcess.spawn(process.execPath, ['-e', ${JSON.stringify(childSource)}], {
-          stdio: ['ignore', 'inherit', 'inherit'],
-        })
-        while (!fs.existsSync(${JSON.stringify(marker)})) await new Promise(resolve => setTimeout(resolve, 5))
-        return true
-      `)
-      const deadline = Date.now() + 2_000
-      for (;;) {
-        try {
-          await access(marker)
-          break
-        } catch (error: unknown) {
-          if (Date.now() >= deadline) throw error
-          await delay(10)
-        }
-      }
-      const completed = await Promise.race([
-        running.then(() => true),
-        delay(500).then(() => false),
-      ])
-      await writeFile(release, '')
-      const { messages, stderr } = await running
-
-      expect(completed).toBe(true)
-      expect(stderr).toBe('')
-      expect(messages.at(-1)).toEqual({ type: 'done', value: [true] })
-    } finally {
-      await writeFile(release, '').catch(() => undefined)
-      await running?.catch(() => undefined)
-      await rm(directory, { recursive: true, force: true })
-    }
-  })
-
-  it('prepares the remote runner and returns logs and a lossless completion', async () => {
-    const handle = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type !== 'boot') return
-      current.emit({ type: 'log', text: 'remote 你好' })
-      current.emitRaw(
-        encodeE2BFrame({ type: 'done', value: encodeWorkerJson({ answer: 42 }) })
-        + encodeE2BFrame({ type: 'log', text: 'ignored after done' }),
-      )
-      current.emit({ type: 'log', text: 'also ignored after done' })
-    })
-    const fixture = await setup([handle])
-
-    await expect(fixture.runtime.run(request('const answer: number = 42; return { answer }')))
-      .resolves.toEqual({ logs: ['remote 你好'], value: { answer: 42 } })
-    expect(fixture.runtime.language).toBe('typescript')
-    expect(fixture.runtime.isolation).toBe('container')
-    expect(fixture.write).toHaveBeenCalledWith([{ path: '/workspace/.dsh-e2b/code-runtime-runner.mjs', data: CODE_RUNNER_SOURCE }])
-    expect(fixture.run).toHaveBeenCalledWith("chmod 600 -- '/workspace/.dsh-e2b/code-runtime-runner.mjs'")
-    expect(fixture.spawn).toHaveBeenCalledWith(expect.objectContaining({
-      argv: ['/usr/bin/node', '/workspace/.dsh-e2b/code-runtime-runner.mjs'],
-      cwd: '/workspace',
-      env: {},
-    }))
-    expect(handle.terminated).toBe(1)
-    expect(handle.waitCalls).toBe(1)
-    await fixture.fiber.dispose()
-  })
-
-  it('bridges binding success, host rejection, unknown members, and invalid values', async () => {
-    const replies: unknown[] = []
-    const handle = new FakeHandle((message, current) => {
-      const record = message as { type?: string; id?: number; ok?: boolean }
-      if (record.type === 'boot') {
-        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'double', args: encodeWorkerJson({ value: 4 }) })
-        current.emit({ type: 'call', id: 2, global: 'bridge', name: 'fail', args: encodeWorkerJson(null) })
-        current.emit({ type: 'call', id: 3, global: 'bridge', name: 'missing', args: encodeWorkerJson(null) })
-        current.emit({ type: 'call', id: 4, global: 'bridge', name: 'double', args: [] })
-        current.emit({ type: 'call', id: 5, global: 'bridge', name: 'invalid', args: encodeWorkerJson(null) })
-        current.emit({ type: 'call', id: 6, global: 'bridge', name: 'throwing', args: encodeWorkerJson(null) })
-        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'double', args: encodeWorkerJson({ value: 99 }) })
-        return
-      }
-      if (record.type === 'reply') {
-        replies.push(message)
-        if (replies.length === 6) current.emit({ type: 'done', value: encodeWorkerJson('done') })
-      }
-    })
-    const fixture = await setup([handle])
-    const result = await fixture.runtime.run({
-      program: 'return await bridge.double({ value: 4 })',
-      bindings: [
-        {
-          global: 'bridge',
-          errorClass: { name: 'BridgeError', memberNameProperty: 'member' },
-          functions: {
-            double: async args => (args as { value: number }).value * 2,
-            fail: async () => { throw 'nope' },
-            invalid: (async () => undefined) as never,
-            throwing: async () => Object.defineProperty({}, 'value', {
-              enumerable: true,
-              get: () => { throw new Error('getter failed') },
-            }),
-          },
-        },
-        { global: 'plain', functions: {} },
-      ],
-    })
-
-    expect(result).toEqual({ logs: [], value: 'done' })
-    expect(replies.sort((left, right) => (left as { id: number }).id - (right as { id: number }).id)).toEqual([
-      { type: 'reply', id: 1, ok: true, value: encodeWorkerJson(8) },
-      { type: 'reply', id: 2, ok: false, message: 'nope' },
-      { type: 'reply', id: 3, ok: false, message: 'unknown binding "bridge.missing"' },
-      { type: 'reply', id: 4, ok: false, message: 'binding arguments must be lossless JSON' },
-      { type: 'reply', id: 5, ok: false, message: 'binding resolution must be lossless JSON' },
-      { type: 'reply', id: 6, ok: false, message: 'binding resolution must be lossless JSON' },
-    ])
-    await fixture.fiber.dispose()
-  })
-
-  it('ignores malformed runner traffic and classifies terminal runner messages', async () => {
-    const ignored = [
-      null, 1, {}, { type: 'log' }, { type: 'call' },
-      { type: 'call', id: 0, global: 'x', name: 'y', args: [] },
-      { type: 'call', id: 1, global: 1, name: 'y', args: [] },
-      { type: 'call', id: 1, global: 'x', name: 1, args: [] },
-      { type: 'call', id: 1, global: 'x', name: 'y', args: {} },
-      { type: 'done', error: null },
-      { type: 'done', error: { kind: 'invented', message: 'x' } },
-      { type: 'done', error: { kind: 'exception', message: 1 } },
-    ]
-    const handles = [
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type !== 'boot') return
-        for (const item of ignored) current.emit(item)
-        current.emit({ type: 'done' })
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done', error: { kind: 'exception', message: 'boom' } })
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done', value: [] })
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'output-limit' })
-      }),
-    ]
-    const fixture = await setup(handles, { maxOutputBytes: 64, maxFrameBytes: 128 })
-
-    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [] })
-    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'exception', message: 'boom' } })
-    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'invalid-output', message: 'program completion must be lossless JSON' } })
-    await expect(fixture.runtime.run(request())).resolves.toEqual({ logs: [], error: { kind: 'output-limit', message: 'outer output exceeded 64 bytes' } })
-    await fixture.fiber.dispose()
-  })
-
-  it('enforces the host output ledger and catches malformed bridge output', async () => {
-    const handles = [
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emit({ type: 'log', text: 'x'.repeat(1_000) })
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emitRaw('not-base64\n')
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.emitRaw('é')
-      }),
-      new FakeHandle((message, current) => {
-        if ((message as { type?: string }).type === 'boot') current.stdout?.emit('error', new Error('stdout broke'))
-      }),
-    ]
-    const fixture = await setup(handles, { maxOutputBytes: 128, maxFrameBytes: 4_096 })
-
-    expect((await fixture.runtime.run(request())).error?.kind).toBe('output-limit')
-    const malformed = (await fixture.runtime.run(request())).error
-    expect(malformed?.kind).toBe('worker-exit')
-    expect(malformed?.message).toContain('bridge failed')
-    expect((await fixture.runtime.run(request())).error?.message).toContain('non-ASCII')
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime stdout failed: stdout broke' })
-    await fixture.fiber.dispose()
-  })
-
-  it('enforces the outbound frame bound on boot and binding replies', async () => {
-    const oversizedBoot = new FakeHandle()
-    const oversizedReply = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') {
-        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'large', args: encodeWorkerJson(null) })
-      }
-    })
-    const fixture = await setup([oversizedBoot, oversizedReply], { maxOutputBytes: 128, maxFrameBytes: 512 })
-
-    const bootResult = await fixture.runtime.run(request(`return ${JSON.stringify('x'.repeat(1_000))}`))
-    expect(bootResult.error).toMatchObject({ kind: 'worker-exit' })
-    expect(bootResult.error?.message).toContain('frame exceeded its byte limit')
-    expect(oversizedBoot.writes).toHaveLength(0)
-
-    const replyResult = await fixture.runtime.run({
-      program: 'return await bridge.large(null)',
-      bindings: [{ global: 'bridge', functions: { large: async () => 'x'.repeat(1_000) } }],
-    })
-    expect(replyResult.error).toMatchObject({ kind: 'worker-exit' })
-    expect(replyResult.error?.message).toContain('frame exceeded its byte limit')
-    expect(oversizedReply.writes).toHaveLength(1)
-    await fixture.fiber.dispose()
-  })
-
-  it('contains stdin errors, process exits, spawn failures, and missing pipes', async () => {
-    const writeError = new FakeHandle(() => {}, { writeError: new Error('write callback broke') })
-    const stdinError = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') current.stdin?.emit('error', new Error('stdin broke'))
-    })
-    const earlyExit = new FakeHandle(() => {}, { stderr: 'remote diagnostic' })
-    const quietExit = new FakeHandle()
-    const emptyStderrExit = new FakeHandle(() => {}, { stderr: '' })
-    const spawnFailure = new FakeHandle()
-    const missingStdin = new FakeHandle(() => {}, { stdin: false })
-    const missingStdout = new FakeHandle(() => {}, { stdout: false, waitError: new Error('missing-stream process query failed') })
-    const truncated = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') {
-        current.emitRaw('YQ==')
-        setImmediate(() => { current.exit() })
-      }
-    })
-    const cleanupFailure = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done' })
-    }, { waitError: new Error('process query failed') })
-    const fixture = await setup([
-      writeError, stdinError, earlyExit, quietExit, emptyStderrExit,
-      spawnFailure, missingStdin, missingStdout, truncated, cleanupFailure,
-    ])
-
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime bridge write failed: write callback broke' })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime stdin failed: stdin broke' })
-    setImmediate(() => { earlyExit.exit() })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing: remote diagnostic' })
-    setImmediate(() => { quietExit.exit() })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing' })
-    setImmediate(() => { emptyStderrExit.exit() })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime exited before completing' })
-    setImmediate(() => { spawnFailure.crash('spawn rejected') })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime spawn failed: spawn rejected' })
-    expect((await fixture.runtime.run(request())).error?.message).toContain('dropped a piped runtime stream')
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime cleanup failed: missing-stream process query failed' })
-    expect(missingStdin.terminated).toBe(1)
-    expect(missingStdin.waitCalls).toBe(1)
-    expect(missingStdout.terminated).toBe(1)
-    expect(missingStdout.waitCalls).toBe(1)
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B frame stream ended mid-frame' })
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'worker-exit', message: 'E2B runtime cleanup failed: process query failed' })
-    await fixture.fiber.dispose()
-  })
-
-  it('reports wall timeout, abort, pre-abort, type-strip failure, and disposal', async () => {
-    const timeout = new FakeHandle()
-    const abort = new FakeHandle()
-    const disposing = new FakeHandle()
-    const fixture = await setup([timeout, abort, disposing], { maxWallMs: 20 })
-
-    expect((await fixture.runtime.run(request())).error).toEqual({ kind: 'timeout', message: 'wall-clock ceiling reached (20ms)' })
-    const controller = new AbortController()
-    const aborting = fixture.runtime.run({ ...request(), signal: controller.signal })
-    controller.abort('stop')
-    expect((await aborting).error).toEqual({ kind: 'abort', message: 'stop' })
-    expect((await fixture.runtime.run({ ...request(), signal: AbortSignal.abort('already') })).error)
-      .toEqual({ kind: 'abort', message: 'already' })
-    expect((await fixture.runtime.run(request('enum E { A }'))).error?.kind).toBe('exception')
-
-    const live = fixture.runtime.run(request())
-    await new Promise(resolve => setImmediate(resolve))
-    await fixture.fiber.dispose()
-    expect((await live).error).toEqual({ kind: 'abort', message: 'runtime disposed' })
-    await expect(fixture.runtime.run(request())).rejects.toThrow('after disposal')
-  })
-
-  it('drops binding replies that settle after abort', async () => {
-    const controller = new AbortController()
-    const resolution = Promise.withResolvers<string>()
-    const invoked = Promise.withResolvers<undefined>()
-    const handle = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') {
-        current.emit({ type: 'call', id: 1, global: 'bridge', name: 'late', args: encodeWorkerJson(null) })
-      }
-    })
-    const fixture = await setup([handle])
-    const running = fixture.runtime.run({
-      program: 'return await bridge.late(null)',
-      bindings: [{
-        global: 'bridge',
-        functions: {
-          late: async () => {
-            invoked.resolve(undefined)
-            return await resolution.promise
-          },
-        },
-      }],
-      signal: controller.signal,
-    })
-    await invoked.promise
-    controller.abort('stop')
-    expect((await running).error).toEqual({ kind: 'abort', message: 'stop' })
-    resolution.resolve('late')
-    await new Promise(resolve => setImmediate(resolve))
-    expect(handle.writes).toHaveLength(1)
-    await fixture.fiber.dispose()
-  })
-
-  it('validates binding and runtime configuration before remote execution', async () => {
-    const fixture = await setup([])
-    const invalidRequests = [
-      { global: 'not-valid!', functions: {} },
-      { global: 'await', functions: {} },
-      { global: 'console', functions: {} },
-      { global: 'same', functions: {} },
-      { global: 'same', functions: {} },
-      { global: 'ok', functions: {}, errorClass: { name: 'not-valid!', memberNameProperty: 'member' } },
-      { global: 'ok', functions: {}, errorClass: { name: 'await', memberNameProperty: 'member' } },
-      { global: 'Clash', functions: {}, errorClass: { name: 'Clash', memberNameProperty: 'member' } },
-      { global: 'one', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'member' } },
-      { global: 'two', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'member' } },
-      { global: 'ok', functions: {}, errorClass: { name: 'Err', memberNameProperty: '' } },
-      { global: 'ok', functions: {}, errorClass: { name: 'Err', memberNameProperty: 'message' } },
-    ]
-    for (const bindings of [
-      [invalidRequests[0]], [invalidRequests[1]], [invalidRequests[2]],
-      invalidRequests.slice(3, 5), [invalidRequests[5]], [invalidRequests[6]],
-      [invalidRequests[7]], invalidRequests.slice(8, 10), [invalidRequests[10]], [invalidRequests[11]],
-    ]) {
-      await expect(fixture.runtime.run({ program: 'return 1', bindings: bindings as never })).rejects.toThrow()
-    }
-    await fixture.fiber.dispose()
-
-    for (const config of [
-      { computeMs: 0 }, { computeMs: 1.5 }, { maxOutputBytes: 3 },
-      { maxWallMs: 2_147_483_648 }, { maxFrameBytes: 10, maxOutputBytes: 20 },
-    ]) {
-      const ctx = new Context()
-      const subprocess = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
-      ctx.provide('e2b', { getSandbox: async () => ({}) } as never)
-      ctx.provide('subprocess', subprocess)
-      await expect(ctx.plugin(E2BCodeRuntime, config)).rejects.toThrow()
-    }
-
-    const wrong = new Context()
-    wrong.provide('e2b', { getSandbox: async () => ({}) } as never)
-    wrong.provide('subprocess', {} as never)
-    await expect(wrong.plugin(E2BCodeRuntime, {})).rejects.toThrow('dsh-subprocess-e2b')
-  })
-
-  it('turns asynchronous runtime preparation failure into a run result', async () => {
-    const sandbox = {
-      files: { write: vi.fn().mockRejectedValue(new Error('upload failed')) },
-      commands: { run: vi.fn() },
-    } as unknown as Sandbox
-    const fixture = await setup([], {}, sandbox)
-    expect((await fixture.runtime.run(request())).error).toEqual({
-      kind: 'worker-exit',
-      message: 'E2B runtime setup failed: upload failed',
-    })
-    await fixture.fiber.dispose()
-  })
-
-  it('returns disposal when remote preparation completes after teardown', async () => {
-    const gate = Promise.withResolvers<Sandbox>()
-    const fixture = await setup([], {}, {}, () => gate.promise)
-    const running = fixture.runtime.run(request())
-    const disposing = fixture.fiber.dispose()
-    let disposed = false
-    void disposing.then(() => { disposed = true })
-    await new Promise(resolve => setImmediate(resolve))
-    const disposedBeforeSetup = disposed
-    gate.resolve(fixture.sandbox)
-    await disposing
-    expect(disposedBeforeSetup).toBe(false)
-    expect((await running).error).toEqual({ kind: 'abort', message: 'runtime disposed' })
-    expect(fixture.write).not.toHaveBeenCalled()
-  })
-
-  it('observes abort while runtime preparation is pending', async () => {
-    const gate = Promise.withResolvers<Sandbox>()
-    const fixture = await setup([], {}, {}, () => gate.promise)
-    const controller = new AbortController()
-    const running = fixture.runtime.run({ ...request(), signal: controller.signal })
-
-    controller.abort('stop during setup')
-    const early = await Promise.race([
-      running.then(result => ({ kind: 'result' as const, result })),
-      new Promise<{ kind: 'pending' }>((resolve) => { setImmediate(() => { resolve({ kind: 'pending' }) }) }),
-    ])
-    expect(fixture.spawn).not.toHaveBeenCalled()
-
-    gate.resolve(fixture.sandbox)
-    expect(early).toMatchObject({ kind: 'result', result: { error: { kind: 'abort', message: 'stop during setup' } } })
-    await running
-    await fixture.fiber.dispose()
-  })
-
-  it('classifies an abort that races synchronous subprocess spawn', async () => {
-    const fixture = await setup()
-    const controller = new AbortController()
-    fixture.spawn.mockImplementationOnce(() => {
-      controller.abort('stop at spawn')
-      throw new Error('aborted before spawn')
-    })
-
-    expect((await fixture.runtime.run({ ...request(), signal: controller.signal })).error)
-      .toEqual({ kind: 'abort', message: 'stop at spawn' })
-
-    fixture.spawn.mockImplementationOnce(() => { throw new Error('synchronous spawn failure') })
-    expect((await fixture.runtime.run(request())).error).toEqual({
-      kind: 'worker-exit',
-      message: 'E2B runtime spawn failed: synchronous spawn failure',
-    })
-    await fixture.fiber.dispose()
-
-    const disposingFixture = await setup()
-    disposingFixture.spawn.mockImplementationOnce(() => {
-      void (disposingFixture.runtime as unknown as { teardown(): Promise<void> }).teardown()
-      throw new Error('spawn raced disposal')
-    })
-    expect((await disposingFixture.runtime.run(request())).error)
-      .toEqual({ kind: 'abort', message: 'runtime disposed' })
-    await disposingFixture.fiber.dispose()
-  })
-
-  it('closes both abort races around runtime readiness and live-run publication', async () => {
-    let preparationAborted = false
-    const preparationSignal = {
-      get aborted() { return preparationAborted },
-      reason: 'preparation race',
-      addEventListener() { preparationAborted = true },
-      removeEventListener() {},
-    } as unknown as AbortSignal
-    const liveHandle = new FakeHandle()
-    const fixture = await setup([liveHandle])
-    expect((await fixture.runtime.run({ ...request(), signal: preparationSignal })).error)
-      .toEqual({ kind: 'abort', message: 'preparation race' })
-    expect(fixture.spawn).not.toHaveBeenCalled()
-
-    let liveAborted = false
-    let registrations = 0
-    const liveSignal = {
-      get aborted() { return liveAborted },
-      reason: 'live publication race',
-      addEventListener() {
-        registrations += 1
-        if (registrations === 2) liveAborted = true
-      },
-      removeEventListener() {},
-    } as unknown as AbortSignal
-    expect((await fixture.runtime.run({ ...request(), signal: liveSignal })).error)
-      .toEqual({ kind: 'abort', message: 'live publication race' })
-    await fixture.fiber.dispose()
-  })
-
-  it('retains a live run until remote cleanup reaches quiescence', async () => {
-    const cleanup = Promise.withResolvers<boolean>()
-    const handle = new FakeHandle((message, current) => {
-      if ((message as { type?: string }).type === 'boot') current.emit({ type: 'done' })
-    }, { waitResult: cleanup.promise })
-    const fixture = await setup([handle])
-    const running = fixture.runtime.run(request())
-    await vi.waitFor(() => { expect(handle.waitCalls).toBe(1) })
-
-    const disposing = fixture.fiber.dispose()
-    let disposed = false
-    void disposing.then(() => { disposed = true })
-    await new Promise(resolve => setImmediate(resolve))
-    const disposedBeforeCleanup = disposed
-
-    cleanup.resolve(true)
-    await expect(running).resolves.toEqual({ logs: [] })
-    await expect(disposing).resolves.toBeUndefined()
-    expect(disposedBeforeCleanup).toBe(false)
-  })
-
-  it('registers the package-owned invariant companion', async () => {
-    const ctx = new Context()
-    await ctx.plugin(InvariantService, { enabled: true })
-    const fiber = await ctx.plugin(E2BCodeRuntimeInvariant).await()
-    await fiber.dispose()
-  })
-})
diff --git a/packages/e2b/code-runtime-e2b/tsconfig.json b/packages/e2b/code-runtime-e2b/tsconfig.json
deleted file mode 100644
index 3bc2e21873..0000000000
--- a/packages/e2b/code-runtime-e2b/tsconfig.json
+++ /dev/null
@@ -1,20 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src"],
-  "references": [
-    { "path": "../../../vendor/cosmokit" },
-    { "path": "../../../vendor/cordis" },
-    { "path": "../../../vendor/schemastery" },
-    { "path": "../../code-runtime/code-runtime" },
-    { "path": "../../code-runtime/code-runtime-worker" },
-    { "path": "../e2b" },
-    { "path": "../../core/session" },
-    { "path": "../subprocess-e2b" },
-    { "path": "../../util/timeout" },
-    { "path": "../../support/invariants" }
-  ]
-}
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 164bb47784..8ffb6e981f 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 5f89a4bcffdfd11fef8929d2a2ceecb41af319e2
-README.zh.md: b4956033bae131bb8aa236276323ecba30f00115
+README.md: 00264b8f0b03e4af8512025322fe3e457e7b6b9b
+README.zh.md: 93fad661ded446e78e3addc0c8b2b8fdc39bd994
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 5f89a4bcff..00264b8f0b 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shared lifecycle owner for one E2B sandbox. Capability adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`; the [family map](../README.md) lists the opt-in adapters.
+Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`; the [family map](../README.md) lists the opt-in composition.
 
 ## Configuration
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index b4956033ba..93fad661de 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个 E2B 沙箱的共享生命周期所有者。功能适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`；可选适配器见[包族索引](../README.md)。
+一个 E2B 沙箱的共享生命周期所有者。文件系统与进程管理适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`；可选组合见[包族索引](../README.md)。
 
 ## 配置
 
diff --git a/packages/e2b/e2b/src/frame.ts b/packages/e2b/e2b/src/frame.ts
deleted file mode 100644
index 5b6fe536c0..0000000000
--- a/packages/e2b/e2b/src/frame.ts
+++ /dev/null
@@ -1,96 +0,0 @@
-/** ASCII/base64 JSON framing for byte-faithful protocols over E2B text callbacks. */
-
-import { Buffer } from 'node:buffer'
-
-const BASE64_LINE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
-
-/**
- * Encode one JSON-compatible value as a newline-delimited ASCII frame.
- * @param value - Value accepted by `JSON.stringify`.
- * @returns Base64-encoded UTF-8 JSON followed by one newline.
- */
-export function encodeE2BFrame(value: unknown): string {
-  return encodeFrame(value)
-}
-
-/**
- * Encode one JSON-compatible value while enforcing the decoded frame bound.
- * @param value - Value accepted by `JSON.stringify`.
- * @param maxFrameBytes - Maximum UTF-8 JSON bytes in the encoded frame.
- * @returns Base64-encoded UTF-8 JSON followed by one newline.
- */
-export function encodeBoundedE2BFrame(value: unknown, maxFrameBytes: number): string {
-  if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
-    throw new Error('E2B frame maxFrameBytes must be a positive safe integer')
-  }
-  return encodeFrame(value, maxFrameBytes)
-}
-
-function encodeFrame(value: unknown, maxFrameBytes?: number): string {
-  const json: unknown = JSON.stringify(value)
-  if (typeof json !== 'string') throw new Error('E2B frame value is not JSON-serializable')
-  const bytes = Buffer.from(json)
-  if (maxFrameBytes !== undefined && bytes.length > maxFrameBytes) {
-    throw new Error('E2B frame exceeded its byte limit')
-  }
-  return `${bytes.toString('base64')}\n`
-}
-
-/** Incremental decoder for newline-delimited base64 JSON frames. */
-export class E2BFrameDecoder {
-  private pending = ''
-  private readonly maxEncodedChars: number
-
-  /** @param maxFrameBytes - Maximum decoded UTF-8 JSON bytes in one frame. */
-  constructor(private readonly maxFrameBytes: number) {
-    if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
-      throw new Error('E2B frame maxFrameBytes must be a positive safe integer')
-    }
-    this.maxEncodedChars = Math.ceil(maxFrameBytes / 3) * 4
-  }
-
-  /**
-   * Consume one E2B callback chunk.
-   * @param chunk - ASCII text received from the remote helper.
-   * @returns Every complete decoded JSON value, in order.
-   */
-  push(chunk: string): unknown[] {
-    if (/[^\x0a\x20-\x7e]/.test(chunk)) throw new Error('E2B frame stream contained non-ASCII data')
-    this.pending += chunk
-    const values: unknown[] = []
-    for (;;) {
-      const newline = this.pending.indexOf('\n')
-      if (newline < 0) {
-        if (this.pending.length > this.maxEncodedChars) throw new Error('E2B frame exceeded its byte limit')
-        return values
-      }
-      const line = this.pending.slice(0, newline)
-      this.pending = this.pending.slice(newline + 1)
-      values.push(this.decode(line))
-    }
-  }
-
-  /** Reject a truncated final frame. */
-  finish(): void {
-    if (this.pending.length !== 0) throw new Error('E2B frame stream ended mid-frame')
-  }
-
-  private decode(line: string): unknown {
-    if (line.length === 0 || line.length > this.maxEncodedChars || !BASE64_LINE.test(line)) {
-      throw new Error('E2B frame contained invalid base64 or exceeded its byte limit')
-    }
-    const bytes = Buffer.from(line, 'base64')
-    if (bytes.length > this.maxFrameBytes) throw new Error('E2B frame exceeded its byte limit')
-    let json: string
-    try {
-      json = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
-    } catch (error: unknown) {
-      throw new Error('E2B frame contained invalid UTF-8', { cause: error })
-    }
-    try {
-      return JSON.parse(json) as unknown
-    } catch (error: unknown) {
-      throw new Error('E2B frame contained invalid JSON', { cause: error })
-    }
-  }
-}
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 11625b3b21..184c49f811 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -10,8 +10,6 @@ import z from 'schemastery'
 import { Sandbox } from 'e2b'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
-export { E2BFrameDecoder, encodeBoundedE2BFrame, encodeE2BFrame } from './frame.ts'
-
 export {
   CommandExitError,
   FileNotFoundError,
@@ -44,26 +42,6 @@ export function quoteE2BShellArg(value: string): string {
   return `'${value.replaceAll('\'', "'\"'\"'")}'`
 }
 
-/**
- * Resolve one executable inside an E2B sandbox and require an absolute result.
- * @param sandbox - Sandbox whose PATH and filesystem own the executable.
- * @param command - Absolute path or bare executable name.
- * @returns Verified absolute remote executable path.
- */
-export async function resolveE2BExecutable(sandbox: Sandbox, command: string): Promise<string> {
-  if (command.length === 0) throw new Error('E2B executable name must be non-empty')
-  if (posix.isAbsolute(command)) {
-    await sandbox.commands.run(`test -f ${quoteE2BShellArg(command)} -a -x ${quoteE2BShellArg(command)}`)
-    return command
-  }
-  const result = await sandbox.commands.run(`command -v -- ${quoteE2BShellArg(command)}`)
-  const executable = result.stdout.trim()
-  if (!posix.isAbsolute(executable) || executable.includes('\n')) {
-    throw new Error(`E2B executable ${JSON.stringify(command)} did not resolve to one absolute path`)
-  }
-  return executable
-}
-
 /** Action taken on the owned sandbox when the Cordis service is disposed. */
 export type E2BDisposeMode = 'kill' | 'pause' | 'leave'
 
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 1bfbab1e8e..98fcdeae7f 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -3,13 +3,13 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
-import { AgentMessageId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
-import { E2BPtyBackend } from '@deepseek-ai/dsh-pty-e2b'
-import { PtySessionId } from '@deepseek-ai/dsh-pty'
+import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
+import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
 
 const fixtureRoot = fileURLToPath(new URL('../../../../examples/headless-agent/tests/fixtures/e2b/e2b/', import.meta.url))
 const binScript = join(fixtureRoot, 'bin.ts')
@@ -29,7 +29,17 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     })
     try {
       const ctx = new Context()
-      ctx.provide('e2b', { cwd: '/home/user', getSandbox: async () => sandbox } as never)
+      ctx.provide('e2b', {
+        cwd: '/home/user',
+        runtimeRoot: '/home/user/.dsh-e2b',
+        getSandbox: async () => sandbox,
+      } as never)
+      ctx.provide('sandboxPolicy', {
+        defaultMode: 'danger-full-access',
+        workspaceRoot: '/home/user',
+      } as never)
+      const ptyFiber = await ctx.plugin(PtyService)
+      const subprocessFiber = await ctx.plugin(E2BSubprocessService)
       const ownerId = SessionId('e2b-pty-env-owner')
       const owner: Agent = {
         id: ownerId,
@@ -38,17 +48,19 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         status: 'idle',
         acceptsNextStep: false,
         ctx,
-        followup: () => AgentMessageId('unused'),
-        steer: () => AgentMessageId('unused'),
-        inject: () => AgentMessageId('unused'),
-        send: () => AgentMessageId('unused'),
+        followup() {},
+        steer() {},
+        inject() {},
+        send() {},
         cancel() {},
         whenIdle: () => Promise.resolve(),
       }
-      const backend = new E2BPtyBackend(ctx, {
-        backendType: 'shell', rows: 24, cols: 80,
+      const backend = new LocalPtyBackend(ctx, {
+        backendType: 'shell', shellPath: '/bin/bash', shellArgs: ['--noprofile', '--norc', '-i'],
+        rows: 24, cols: 80,
         scrollbackLines: 100, scrollbackMaxBytes: 65_536, maxReadBytes: 16_384,
-        pollIntervalMs: 25, idleSilenceMs: 1_000, timeoutMs: 5_000, disposeGraceMs: 1_000,
+        pollIntervalMs: 25, exactProbeAfterMs: 150, idleSilenceMs: 1_000,
+        handoffGraceMs: 500, timeoutMs: 5_000, disposeGraceMs: 1_000,
       })
       const session = await backend.spawn({ sessionId: PtySessionId('env'), owner, type: 'shell' })
       const result = await session.startSend({
@@ -59,6 +71,8 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       expect(result.viewport).not.toContain('sentinel-secret')
       expect(result.viewport).not.toContain('sentinel-stale')
       await session.close('environment test complete')
+      await subprocessFiber.dispose()
+      await ptyFiber.dispose()
     } finally {
       await sandbox.kill().catch(() => false)
     }
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index 58d2ffbd7a..c0770f5917 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -2,12 +2,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
-  E2BFrameDecoder,
   E2BSandboxId,
-  encodeBoundedE2BFrame,
-  encodeE2BFrame,
   quoteE2BShellArg,
-  resolveE2BExecutable,
 } from '@deepseek-ai/dsh-e2b'
 import * as E2BInvariant from '../src/invariant.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -229,57 +225,6 @@ describe('E2B helpers and invariant companion', () => {
     expect(quoteE2BShellArg("a'b $HOME")).toBe("'a'\"'\"'b $HOME'")
   })
 
-  it('resolves absolute and PATH executables inside the sandbox', async () => {
-    const run = vi.fn()
-      .mockResolvedValueOnce({ exitCode: 0, stdout: '', stderr: '' })
-      .mockResolvedValueOnce({ exitCode: 0, stdout: '/usr/bin/node\n', stderr: '' })
-    const sandbox = { commands: { run } } as unknown as SandboxType
-    await expect(resolveE2BExecutable(sandbox, '/bin/bash')).resolves.toBe('/bin/bash')
-    await expect(resolveE2BExecutable(sandbox, 'node')).resolves.toBe('/usr/bin/node')
-    expect(run).toHaveBeenNthCalledWith(1, "test -f '/bin/bash' -a -x '/bin/bash'")
-    expect(run).toHaveBeenNthCalledWith(2, "command -v -- 'node'")
-  })
-
-  it('rejects empty or non-absolute executable resolutions', async () => {
-    const sandbox = {
-      commands: { run: vi.fn().mockResolvedValue({ exitCode: 0, stdout: 'relative\npath\n', stderr: '' }) },
-    } as unknown as SandboxType
-    await expect(resolveE2BExecutable(sandbox, '')).rejects.toThrow('non-empty')
-    await expect(resolveE2BExecutable(sandbox, 'tool')).rejects.toThrow('did not resolve')
-  })
-
-  it('round-trips split and adjacent ASCII/base64 JSON frames', () => {
-    const decoder = new E2BFrameDecoder(128)
-    const encoded = encodeE2BFrame({ text: '你好' }) + encodeE2BFrame([1, true])
-    expect(decoder.push(encoded.slice(0, 5))).toEqual([])
-    expect(decoder.push(encoded.slice(5))).toEqual([{ text: '你好' }, [1, true]])
-    expect(() => { decoder.finish() }).not.toThrow()
-    expect(() => encodeE2BFrame(undefined)).toThrow('not JSON-serializable')
-  })
-
-  it('bounds outbound frames by decoded UTF-8 bytes', () => {
-    const exact = encodeBoundedE2BFrame({ text: '你' }, 14)
-    expect(new E2BFrameDecoder(14).push(exact)).toEqual([{ text: '你' }])
-    expect(() => encodeBoundedE2BFrame({ text: '你' }, 13)).toThrow('byte limit')
-    expect(() => encodeBoundedE2BFrame(null, 0)).toThrow('positive safe integer')
-    expect(() => encodeBoundedE2BFrame(null, 1.5)).toThrow('positive safe integer')
-  })
-
-  it('rejects malformed, oversized, and truncated frame streams', () => {
-    expect(() => new E2BFrameDecoder(0)).toThrow('positive safe integer')
-    expect(() => new E2BFrameDecoder(1.5)).toThrow('positive safe integer')
-    expect(() => new E2BFrameDecoder(4).push('é')).toThrow('non-ASCII')
-    expect(() => new E2BFrameDecoder(3).push('AAAAA')).toThrow('byte limit')
-    expect(() => new E2BFrameDecoder(8).push('\n')).toThrow('invalid base64')
-    expect(() => new E2BFrameDecoder(8).push('abc!\n')).toThrow('invalid base64')
-    expect(() => new E2BFrameDecoder(2).push(`${Buffer.from('abc').toString('base64')}\n`)).toThrow('byte limit')
-    expect(() => new E2BFrameDecoder(8).push('/w==\n')).toThrow('invalid UTF-8')
-    expect(() => new E2BFrameDecoder(16).push(`${Buffer.from('not-json').toString('base64')}\n`)).toThrow('invalid JSON')
-    const truncated = new E2BFrameDecoder(8)
-    truncated.push('YQ==')
-    expect(() => { truncated.finish() }).toThrow('mid-frame')
-  })
-
   it('registers the package-owned empty invariant installer', async () => {
     const ctx = new Context()
     await ctx.plugin(InvariantService, { enabled: true })
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 95a3a9eea6..6e45ccaaf6 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: a505703fc764f8441fa54d2b1d922762eb3fafdf
-README.zh.md: 626fdb52979d29f12d1bc1b67b0ea13730003af7
+README.md: 86ad8720d3e4c7ce70ee0ac8c41713af03ed297a
+README.zh.md: 90dff57a5b9fe786aea3315633125536277ecc20
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index a505703fc7..86ad8720d3 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -7,7 +7,9 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 ## Behavior
 
 - **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; `realpath -m` supplies canonical target identity without requiring the final file to exist. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
+- **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
+- **Stable bounded reads** — a dependency-free Node helper walks directory descriptors with no-follow opens and reads one held regular-file descriptor through the byte cap. Generic LSP queries therefore reject parent swaps, non-files, invalid UTF-8, and growth past the configured document limit before server startup.
 - **Atomic mutations** — writes upload a mode-`0600` temporary sibling, preserve an existing file's POSIX mode, and publish through E2B's same-directory atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at SDK request boundaries; a successful rename is the commit point.
 
@@ -26,4 +28,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **No host synchronization** — an empty E2B cwd stays empty until a tool, command, template, or external process populates it; local files are neither uploaded nor reflected back.
 - **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
 - **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
-- **Custom templates must support the used Linux and envd features** — `realpath`, `chmod`, `mv`, same-filesystem POSIX rename, streaming reads, and file metadata extended attributes are required; unsupported templates fail rather than degrade silently.
+- **Custom templates must support the used Linux, Node, procfs, and envd features** — `realpath`, `chmod`, `mv`, same-filesystem POSIX rename, streaming reads, file metadata extended attributes, `/proc/self/fd`, and no-follow descriptor opens are required; unsupported templates fail rather than degrade silently.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 626fdb5297..90dff57a5b 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -7,7 +7,9 @@
 ## 行为
 
 - **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；`realpath -m` 提供规范化目标身份，且不要求最终文件存在。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
+- **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
+- **稳定的有界读取**：一个零依赖 Node 辅助程序会以不跟随链接的方式逐级打开目录描述符，并通过一个持续持有的常规文件描述符读取至字节上限。因此，通用 LSP 查询会在服务器启动前拒绝父目录交换、非文件、无效 UTF-8，以及增长后超出所配置文档上限的文件。
 - **原子变更**：写入会上传 mode 为 `0600` 的同级临时文件，保留现有文件的 POSIX mode，并通过 E2B 的同目录原子重命名发布。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。
 
@@ -26,4 +28,4 @@
 - **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令、模板或外部进程填充它；本地文件既不会上传，也不会同步回本地。
 - **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
 - **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
-- **自定义模板必须支持所用的 Linux 与 envd 功能**：必须支持 `realpath`、`chmod`、`mv`、同一文件系统内的 POSIX rename、流式读取和文件元数据扩展属性；不支持的模板会失败，而不会静默降级。
+- **自定义模板必须支持所用的 Linux、Node、procfs 与 envd 功能**：必须支持 `realpath`、`chmod`、`mv`、同一文件系统内的 POSIX rename、流式读取、文件元数据扩展属性、`/proc/self/fd` 和不跟随链接的描述符打开操作；不支持的模板会失败，而不会静默降级。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 2a7fd1275f..2452e856ca 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -5,6 +5,7 @@
  */
 
 import { createHash, randomUUID } from 'node:crypto'
+import { Buffer } from 'node:buffer'
 import { posix } from 'node:path'
 import { FileSystem, FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
@@ -24,10 +25,18 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { EntryInfo, Sandbox } from '@deepseek-ai/dsh-e2b'
+import { BOUNDED_READER_SOURCE } from './source-reader.ts'
 
 const VERSION_METADATA_KEY = 'dsh-version'
 const BINARY_SAMPLE_BYTES = 8192
 
+type BoundedReadResponse =
+  | { kind: 'ok'; data: string }
+  | { kind: 'not-file' }
+  | { kind: 'oversize'; size: number }
+  | { kind: 'grew' }
+  | { kind: 'open-error'; message: string }
+
 function assertNotAborted(signal: AbortSignal | undefined, operation: string): void {
   if (signal?.aborted === true) throw new FsError(`${operation} aborted`, 'FS_ABORTED')
 }
@@ -141,6 +150,21 @@ export class E2BFileSystem extends FileSystem {
     }
   }
 
+  override processPath(target: FsTarget): string {
+    return String(target.targetKey)
+  }
+
+  override fileUrl(target: FsTarget): string {
+    const path = this.processPath(target)
+    if (!posix.isAbsolute(path)) throw new Error(`fs-e2b: expected an absolute process path: ${JSON.stringify(path)}`)
+    return `file://${path.split('/').map(segment => encodeURIComponent(segment)).join('/')}`
+  }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    const relative = posix.relative(this.processPath(parent), this.processPath(child))
+    return relative === '' || (relative !== '..' && !relative.startsWith('../') && !posix.isAbsolute(relative))
+  }
+
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     assertNotAborted(signal, 'stat')
     const entry = await this.probe(String(target.targetKey), target.displayPath, signal)
@@ -184,6 +208,69 @@ export class E2BFileSystem extends FileSystem {
     }
   }
 
+  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+      throw new Error('bounded read maxBytes must be a positive safe integer')
+    }
+    assertNotAborted(signal, 'read')
+    const sandbox = await this.ctx.e2b.getSandbox()
+    try {
+      const node = await sandbox.commands.run('command -v -- node', signalOpts(signal))
+      const executable = node.stdout.trim()
+      if (!posix.isAbsolute(executable) || executable.includes('\n')) {
+        throw new Error('fs-e2b: bounded reader requires one absolute Node executable')
+      }
+      const command = [
+        quoteE2BShellArg(executable),
+        '--input-type=commonjs',
+        '-e',
+        quoteE2BShellArg(BOUNDED_READER_SOURCE),
+        quoteE2BShellArg(this.processPath(target)),
+        String(maxBytes),
+      ].join(' ')
+      const result = await sandbox.commands.run(command, signalOpts(signal))
+      assertNotAborted(signal, 'read')
+      const response = this.parseBoundedRead(result.stdout, target)
+      if (response.kind === 'not-file') {
+        throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+      }
+      if (response.kind === 'oversize' && Number.isSafeInteger(response.size)) {
+        throw new FsError(
+          `cannot read "${target.displayPath}": ${response.size} bytes exceeds the ${maxBytes}-byte limit`,
+          'FS_IO_ERROR',
+        )
+      }
+      if (response.kind === 'grew') {
+        throw new FsError(
+          `cannot read "${target.displayPath}": file grew past the ${maxBytes}-byte limit while reading`,
+          'FS_IO_ERROR',
+        )
+      }
+      if (response.kind === 'open-error' && typeof response.message === 'string') {
+        if (/ENOENT|no such file/i.test(response.message)) {
+          throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+        }
+        if (/EACCES|EPERM|permission denied|operation not permitted/i.test(response.message)) {
+          throw new FsError(`cannot read "${target.displayPath}": permission denied`, 'FS_PERMISSION_DENIED')
+        }
+        throw new FsError(
+          `cannot read "${target.displayPath}" safely: ${response.message}`,
+          'FS_IO_ERROR',
+        )
+      }
+      if (response.kind !== 'ok' || typeof response.data !== 'string') {
+        throw new FsError(`cannot read "${target.displayPath}": bounded reader returned an invalid response`, 'FS_IO_ERROR')
+      }
+      const bytes = Buffer.from(response.data, 'base64')
+      if (bytes.toString('base64') !== response.data || bytes.length > maxBytes) {
+        throw new FsError(`cannot read "${target.displayPath}": bounded reader returned invalid bytes`, 'FS_IO_ERROR')
+      }
+      return decodeText(bytes, target.displayPath, BINARY_SAMPLE_BYTES)
+    } catch (error: unknown) {
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+  }
+
   override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     const sandbox = await this.ctx.e2b.getSandbox()
     await this.requireRegular(target, signal)
@@ -336,6 +423,18 @@ export class E2BFileSystem extends FileSystem {
     }
   }
 
+  private parseBoundedRead(stdout: string, target: FsTarget): BoundedReadResponse {
+    try {
+      return JSON.parse(stdout) as BoundedReadResponse
+    } catch (error: unknown) {
+      throw new FsError(
+        `cannot read "${target.displayPath}": bounded reader returned invalid JSON`,
+        'FS_IO_ERROR',
+        { cause: error },
+      )
+    }
+  }
+
   private async probe(path: string, displayPath: string, signal?: AbortSignal): Promise<EntryInfo | undefined> {
     assertNotAborted(signal, 'stat')
     try {
diff --git a/packages/e2b/fs-e2b/src/source-reader.ts b/packages/e2b/fs-e2b/src/source-reader.ts
new file mode 100644
index 0000000000..9cb522ecbb
--- /dev/null
+++ b/packages/e2b/fs-e2b/src/source-reader.ts
@@ -0,0 +1,63 @@
+/** Dependency-free stable-handle bounded reader installed inside E2B. */
+export const BOUNDED_READER_SOURCE = String.raw`
+/* dsh-e2b-bounded-reader */
+const fs = require('node:fs')
+const target = process.argv[1]
+const maxBytes = Number(process.argv[2])
+const directoryFlags = fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK
+const fileFlags = fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK
+let directory
+let descriptor
+let response
+
+const openChild = (parent, component, flags) => fs.openSync('/proc/self/fd/' + parent + '/' + component, flags)
+const invalidComponent = component => component === '' || component === '.' || component === '..'
+
+try {
+  if (typeof target !== 'string' || !target.startsWith('/') || !Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new Error('bounded reader requires an absolute target and positive byte limit')
+  }
+  const components = target === '/' ? [] : target.slice(1).split('/')
+  if (components.length === 0 || components.some(invalidComponent)) {
+    throw new Error('bounded reader received a non-canonical file path')
+  }
+
+  directory = fs.openSync('/', directoryFlags)
+  for (const component of components.slice(0, -1)) {
+    const child = openChild(directory, component, directoryFlags)
+    fs.closeSync(directory)
+    directory = child
+  }
+  descriptor = openChild(directory, components.at(-1), fileFlags)
+
+  const info = fs.fstatSync(descriptor)
+  if (!info.isFile()) response = { kind: 'not-file' }
+  else if (info.size > maxBytes) response = { kind: 'oversize', size: info.size }
+  else {
+    const chunks = []
+    let total = 0
+    while (total <= maxBytes) {
+      const chunk = Buffer.allocUnsafe(Math.min(65536, maxBytes - total + 1))
+      const bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)
+      if (bytesRead === 0) break
+      chunks.push(chunk.subarray(0, bytesRead))
+      total += bytesRead
+    }
+    response = total > maxBytes
+      ? { kind: 'grew' }
+      : { kind: 'ok', data: Buffer.concat(chunks, total).toString('base64') }
+  }
+} catch (error) {
+  response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
+} finally {
+  for (const openDescriptor of [descriptor, directory]) {
+    if (openDescriptor === undefined) continue
+    try {
+      fs.closeSync(openDescriptor)
+    } catch (error) {
+      response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
+    }
+  }
+}
+process.stdout.write(JSON.stringify(response))
+`
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 13d94e70c7..648631c7ee 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -1,3 +1,4 @@
+import { Buffer } from 'node:buffer'
 import { dirname, posix } from 'node:path'
 import { Context } from 'cordis'
 import {
@@ -8,7 +9,7 @@ import {
   type Sandbox,
 } from '@deepseek-ai/dsh-e2b'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { FsVersion } from '@deepseek-ai/dsh-fs'
+import { FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
 import E2BFileSystem from '@deepseek-ai/dsh-fs-e2b'
 import * as E2BFsInvariant from '../src/invariant.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -46,6 +47,10 @@ class FakeRemote {
   nextReadError: unknown
   nextRenameError: unknown
   nextRemoveError: unknown
+  boundedOutput: string | undefined
+  boundedError: unknown
+  nodeExecutable = '/usr/bin/node\n'
+  abortAfterBoundedCommand: AbortController | undefined
   abortAfterRename: AbortController | undefined
   disappearOnInfo = new Set<string>()
   private clock = 1
@@ -221,6 +226,14 @@ class FakeRemote {
           const node = this.nodes.get(input)
           return { exitCode: 0, stdout: `${node?.symlinkTarget ?? input}\n`, stderr: '' }
         }
+        if (command === 'command -v -- node') {
+          return { exitCode: 0, stdout: this.nodeExecutable, stderr: '' }
+        }
+        if (command.includes('dsh-e2b-bounded-reader')) {
+          if (this.boundedError !== undefined) throw this.boundedError
+          this.abortAfterBoundedCommand?.abort('after bounded read')
+          return { exitCode: 0, stdout: this.boundedOutput ?? '{"kind":"ok","data":""}', stderr: '' }
+        }
         const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
         if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
         const move = /^mv -f -- '([^']+)' '([^']+)'$/.exec(command)
@@ -289,6 +302,26 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     expect(listed.some(entry => entry.name === 'nested.txt')).toBe(false)
   })
 
+  it('projects canonical process paths, file URLs, and containment', async () => {
+    const remote = new FakeRemote()
+    remote.dir('/workspace/nested')
+    remote.file('/workspace/nested/multibyte # file.ts', 'text')
+    remote.file('/outside.ts', 'outside')
+    const { fs } = await setup(remote)
+    const workspace = await fs.resolve('/workspace')
+    const nested = await fs.resolve('/workspace/nested/multibyte # file.ts')
+    const outside = await fs.resolve('/outside.ts')
+
+    expect(fs.processPath(nested)).toBe('/workspace/nested/multibyte # file.ts')
+    expect(fs.fileUrl(nested)).toBe('file:///workspace/nested/multibyte%20%23%20file.ts')
+    expect(fs.contains(workspace, workspace)).toBe(true)
+    expect(fs.contains(workspace, nested)).toBe(true)
+    expect(fs.contains(nested, workspace)).toBe(false)
+    expect(fs.contains(workspace, outside)).toBe(false)
+    expect(() => fs.fileUrl({ targetKey: FsTargetKey('relative'), displayPath: 'relative' }))
+      .toThrow('expected an absolute process path')
+  })
+
   it('reads whole and streamed UTF-8 across chunk boundaries', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/text.txt', 'A€B')
@@ -373,6 +406,78 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     await expectCode(fs.readText(await fs.resolve('a')), 'FS_ABORTED')
   })
 
+  it('performs stable bounded reads through the remote no-follow reader', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'unused')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('a')
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('hello 你好').toString('base64') })
+    await expect(fs.readTextBounded(target, 64)).resolves.toBe('hello 你好')
+    expect(remote.commands.some(command => command.includes('dsh-e2b-bounded-reader'))).toBe(true)
+
+    await expect(fs.readTextBounded(target, 0)).rejects.toThrow('positive safe integer')
+    await expect(fs.readTextBounded(target, 1.5)).rejects.toThrow('positive safe integer')
+    await expect(fs.readTextBounded(target, 64, AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
+
+  it('maps bounded-reader file, size, and open failures', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'unused')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('a')
+    const cases: Array<[unknown, string]> = [
+      [{ kind: 'not-file' }, 'FS_NOT_REGULAR_FILE'],
+      [{ kind: 'oversize', size: 65 }, 'FS_IO_ERROR'],
+      [{ kind: 'grew' }, 'FS_IO_ERROR'],
+      [{ kind: 'open-error', message: 'ENOENT: no such file' }, 'FS_NOT_FOUND'],
+      [{ kind: 'open-error', message: 'EACCES: permission denied' }, 'FS_PERMISSION_DENIED'],
+      [{ kind: 'open-error', message: 'ELOOP: symbolic link' }, 'FS_IO_ERROR'],
+      [{ kind: 'oversize', size: 'large' }, 'FS_IO_ERROR'],
+      [{ kind: 'open-error', message: 7 }, 'FS_IO_ERROR'],
+      [{ kind: 'unknown' }, 'FS_IO_ERROR'],
+    ]
+    for (const [response, code] of cases) {
+      remote.boundedOutput = JSON.stringify(response)
+      await expectCode(fs.readTextBounded(target, 64), code)
+    }
+  })
+
+  it('rejects malformed bounded-reader transports and bytes', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'unused')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('a')
+
+    remote.boundedOutput = 'not-json'
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: '!!!!' })
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('12345').toString('base64') })
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from([0]).toString('base64') })
+    await expectCode(fs.readTextBounded(target, 4), 'FS_NOT_TEXT')
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from([0xff]).toString('base64') })
+    await expectCode(fs.readTextBounded(target, 4), 'FS_NOT_TEXT')
+
+    remote.nodeExecutable = 'node\n'
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+    remote.nodeExecutable = '/usr/bin/node\n/other\n'
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+    remote.nodeExecutable = '/usr/bin/node\n'
+    remote.boundedError = new Error('reader transport failed')
+    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
+  })
+
+  it('does not turn a post-read abort into successful source text', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'unused')
+    const controller = new AbortController()
+    remote.abortAfterBoundedCommand = controller
+    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('text').toString('base64') })
+    const { fs } = await setup(remote)
+    await expectCode(fs.readTextBounded(await fs.resolve('a'), 4, controller.signal), 'FS_ABORTED')
+  })
+
   it('rejects empty paths and directory-listing type errors', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/file', 'x')
diff --git a/packages/e2b/pty-e2b/README.i18n.yaml b/packages/e2b/pty-e2b/README.i18n.yaml
deleted file mode 100644
index 580f874e62..0000000000
--- a/packages/e2b/pty-e2b/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/e2b/pty-e2b/README.md
-README.md: d1b1731cd7b65577a18814a90363acdc66d7d262
-README.zh.md: 4aa2cc8d661e61e80ef61693422a7b6f73c2cb67
diff --git a/packages/e2b/pty-e2b/README.md b/packages/e2b/pty-e2b/README.md
deleted file mode 100644
index d1b1731cd7..0000000000
--- a/packages/e2b/pty-e2b/README.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# @deepseek-ai/dsh-pty-e2b
-
-English | [中文](README.zh.md)
-
-E2B byte-PTY backend for [`ctx.pty`](../../pty/pty/README.md). It creates persistent interactive shells inside the shared `ctx.e2b` sandbox while the PTY registry keeps session identity, exact-Agent ownership, and cleanup policy on the host.
-
-## Plugin and configuration
-
-The `pty-e2b` plugin injects `e2b` and `pty`, then registers one backend under `backendType`.
-
-| Key | Default | Meaning |
-|---|---|---|
-| `backendType` | `shell` | Registry type selected by `terminal_open`. |
-| `rows` / `cols` | `40` / `160` | Initial remote PTY size. |
-| `scrollbackLines` | `10000` | Maximum retained logical lines. |
-| `scrollbackMaxBytes` | `4194304` | Maximum retained UTF-8 scrollback bytes. |
-| `maxReadBytes` | `262144` | Maximum bytes returned by one read or settled send. |
-| `pollIntervalMs` | `50` | Host readiness-poll interval. |
-| `idleSilenceMs` | `3000` | Output silence that yields `inferred_idle`. |
-| `timeoutMs` | `30000` | Absolute startup and send wait bound. |
-| `disposeGraceMs` | `3000` | TERM-to-KILL cleanup grace. |
-
-Numeric values are positive safe integers, `backendType` is non-empty, and `maxReadBytes` cannot exceed `scrollbackMaxBytes`. A relative spawn cwd resolves against `ctx.e2b.cwd`; an absolute remote path remains absolute. Before launch, the backend enumerates sandbox-default environment names, blanks `DSH_*` and credential-shaped names, then overlays its controlled terminal values and explicit `spec.env` entries.
-
-## Runtime contract
-
-The backend uses E2B's byte-oriented PTY callback with a streaming fatal UTF-8 decoder, then the backend-neutral line sanitizer and bounded buffers from `dsh-pty`. It installs a controlled Bash prompt marker and waits for printable prompt text; when that marker is unavailable, observed output plus the configured silence bound yields `inferred_idle`. Startup with no output reaches the absolute timeout and fails instead of publishing an empty session.
-
-Each send writes UTF-8 bytes and an optional carriage-return submit sequence. Cancellation and explicit signals resolve the remote terminal's foreground process group through `ps`, then signal that group; cancellation rechecks the originating send after lookup so a settled operation cannot signal or fail its successor, and `SIGKILL` refuses to target the shell itself. The backend records the terminal's POSIX session id at startup. Close sends `SIGTERM` to every process group still in that session, escalates survivors to `SIGKILL`, verifies that the session is empty, and does not resolve until the SDK handle reports exit. A startup failure closes the unpublished PTY, and `PtyBackendCleanupError` preserves a concurrent cleanup failure.
-
-The remote PTY process and its child processes live in E2B. Prompt/readiness state, scrollback, operation handles, owner authority, and SDK event delivery remain in host memory.
-
-## Model Experience
-
-### Indirect consumer
-
-#### What the model sees
-
-Nothing directly. Through `@deepseek-ai/dsh-tool-pty`, the model may receive bounded MOTD, send deltas, scrollback pages, readiness reasons, signal results, and cleanup failures.
-
-#### Token effect
-
-None until a consumer returns bounded backend output. Retained host PTY scrollback is not placed in model history by this package.
-
-#### KV Cache effect
-
-No direct invalidation; the consumer owns prompts, schemas, and appended results.
-
-## Known Limitations and Deferred Work
-
-- **Line-oriented terminal model** — CSI/OSC control sequences are removed; alternate-screen and full terminal emulation remain unsupported.
-- **Readiness is marker-or-silence based** — E2B exposes foreground process groups but not the local backend's Linux syscall inspection, so `inferred_idle` is deliberately possible.
-- **UTF-8 only** — invalid byte sequences fail the session instead of returning lossy text.
-- **Deliberate session escape is unmanaged** — a process that calls `setsid` leaves the terminal session and is outside this backend's cleanup identity.
-- **No reconnectable terminal handles** — retaining an E2B sandbox preserves remote files, not host ownership, buffers, callbacks, or live PTY sessions.
diff --git a/packages/e2b/pty-e2b/README.zh.md b/packages/e2b/pty-e2b/README.zh.md
deleted file mode 100644
index 4aa2cc8d66..0000000000
--- a/packages/e2b/pty-e2b/README.zh.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# @deepseek-ai/dsh-pty-e2b
-
-[English](README.md) | 中文
-
-用于 [`ctx.pty`](../../pty/pty/README.md) 的 E2B 字节 PTY 后端。它在共享的 `ctx.e2b` 沙箱内创建持久交互式 shell；PTY 注册表则在宿主侧维护会话身份、精确的 Agent 所有权和清理策略。
-
-## 插件与配置
-
-`pty-e2b` 插件注入 `e2b` 和 `pty`，然后以 `backendType` 注册一个后端。
-
-| 配置键 | 默认值 | 含义 |
-|---|---|---|
-| `backendType` | `shell` | `terminal_open` 选择的注册表类型。 |
-| `rows` / `cols` | `40` / `160` | 远程 PTY 的初始尺寸。 |
-| `scrollbackLines` | `10000` | 保留的逻辑行数上限。 |
-| `scrollbackMaxBytes` | `4194304` | 保留的 UTF-8 scrollback 字节数上限。 |
-| `maxReadBytes` | `262144` | 单次读取或发送结算时返回的字节数上限。 |
-| `pollIntervalMs` | `50` | 宿主就绪轮询间隔。 |
-| `idleSilenceMs` | `3000` | 触发 `inferred_idle` 的输出静默时长。 |
-| `timeoutMs` | `30000` | 启动与发送等待的绝对上限。 |
-| `disposeGraceMs` | `3000` | TERM 到 KILL 的清理宽限期。 |
-
-数值必须是正的安全整数，`backendType` 必须非空，且 `maxReadBytes` 不得超过 `scrollbackMaxBytes`。相对的 spawn cwd 以 `ctx.e2b.cwd` 为基准解析；绝对远程路径保持不变。启动前，后端会枚举沙箱默认环境变量名，清空 `DSH_*` 和形似凭据的名称，再覆盖其受控终端值与显式 `spec.env` 条目。
-
-## 运行时契约
-
-该后端为 E2B 面向字节的 PTY 回调配备流式、遇到无效序列即失败的 UTF-8 解码器，随后使用 `dsh-pty` 提供的后端无关行清理器与有界缓冲区。它会安装受控的 Bash 提示符标记，并等待可打印的提示符文本；若该标记不可用，系统会在已经观察到输出且达到已配置的静默上限时得出 `inferred_idle`。零输出的启动过程会达到绝对超时并失败，不会发布空会话。
-
-每次发送都会写入 UTF-8 字节，并可选写入回车提交序列。取消与显式信号会通过 `ps` 确定远程终端的前台进程组，再向该组发送信号；取消处理会在查找后重新检查原发送操作是否仍为当前操作，以免已结算的操作向后继操作发送信号或令其失败；发送 `SIGKILL` 时拒绝以 shell 本身为目标。后端会在启动时记录终端的 POSIX 会话 id。关闭操作会向该会话内仍存在的每个进程组发送 `SIGTERM`，对存活者升级为 `SIGKILL`，验证会话已经清空，并且直到 SDK 句柄报告退出才结算。如果启动失败，系统会关闭尚未发布的 PTY；若清理同时失败，`PtyBackendCleanupError` 会保留这项失败。
-
-远程 PTY 进程及其子进程位于 E2B。提示符／就绪状态、scrollback、操作句柄、所有者权限和 SDK 事件交付仍保留在宿主内存中。
-
-## 模型体验
-
-### 间接消费方
-
-#### 模型看到的内容
-
-没有直接可见内容。模型通过 `@deepseek-ai/dsh-tool-pty` 可能收到有界的 MOTD、发送增量、scrollback 页、就绪原因、信号结果和清理失败。
-
-#### Token 影响
-
-消费方返回有界的后端输出前没有影响。本包不会把宿主保留的 PTY scrollback 放入模型历史。
-
-#### KV Cache 影响
-
-不会直接失效；提示词、schema 和追加结果由消费方负责。
-
-## 已知限制与暂缓工作
-
-- **面向行的终端模型**：CSI／OSC 控制序列会被移除；备用屏幕与完整终端仿真仍不受支持。
-- **就绪判断基于标记或静默**：E2B 会公开前台进程组，但不提供本地后端使用的 Linux syscall 检查，因此系统有意保留返回 `inferred_idle` 的可能性。
-- **仅支持 UTF-8**：无效字节序列会使会话失败，而不是返回有损文本。
-- **主动逃离会话的进程不受管理**：调用 `setsid` 的进程会离开终端会话，因而不属于本后端的清理身份。
-- **没有可重连的终端句柄**：保留 E2B 沙箱会保留远程文件，但不会保留宿主所有权、缓冲区、回调或实时 PTY 会话。
diff --git a/packages/e2b/pty-e2b/package.json b/packages/e2b/pty-e2b/package.json
deleted file mode 100644
index cc31699ab1..0000000000
--- a/packages/e2b/pty-e2b/package.json
+++ /dev/null
@@ -1,46 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-pty-e2b",
-  "description": "E2B PTY provider for DeepSeek Harness",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
-  ],
-  "license": "BSD-3-Clause",
-  "peerDependencies": {
-    "@deepseek-ai/dsh-e2b": "^0.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-pty": "^0.0.1",
-    "cordis": "^4.0.0-rc.7"
-  },
-  "dependencies": {
-    "schemastery": "^3.18.0"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-e2b": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-pty": "workspace:^",
-    "@deepseek-ai/dsh-session": "workspace:^",
-    "cordis": "^4.0.0-rc.7"
-  }
-}
diff --git a/packages/e2b/pty-e2b/src/config.ts b/packages/e2b/pty-e2b/src/config.ts
deleted file mode 100644
index e6849bf54d..0000000000
--- a/packages/e2b/pty-e2b/src/config.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-/** Validated configuration for the E2B PTY backend. */
-
-import z from 'schemastery'
-
-/** Public plugin configuration. */
-export interface Config {
-  /** Backend registry type. */
-  backendType?: string
-  /** Initial terminal rows. */
-  rows?: number
-  /** Initial terminal columns. */
-  cols?: number
-  /** Maximum retained logical lines. */
-  scrollbackLines?: number
-  /** Maximum retained UTF-8 bytes. */
-  scrollbackMaxBytes?: number
-  /** Maximum bytes returned by one read or settled viewport. */
-  maxReadBytes?: number
-  /** Readiness polling interval. */
-  pollIntervalMs?: number
-  /** Output silence duration that yields `inferred_idle`. */
-  idleSilenceMs?: number
-  /** Absolute send and startup wait bound. */
-  timeoutMs?: number
-  /** Grace before PTY teardown escalates from TERM to KILL. */
-  disposeGraceMs?: number
-}
-
-/** Configuration after Schemastery defaults. */
-export type ResolvedConfig = Required<Config>
-
-/* jscpd:ignore-start -- Loader requires a backend-local schema and load-time diagnostics. */
-/** Schemastery config exposed by the plugin. */
-export const Config: z<Config> = z.object({
-  backendType: z.string().default('shell'),
-  rows: z.number().default(40),
-  cols: z.number().default(160),
-  scrollbackLines: z.number().default(10_000),
-  scrollbackMaxBytes: z.number().default(4 * 1024 * 1024),
-  maxReadBytes: z.number().default(256 * 1024),
-  pollIntervalMs: z.number().default(50),
-  idleSilenceMs: z.number().default(3_000),
-  timeoutMs: z.number().default(30_000),
-  disposeGraceMs: z.number().default(3_000),
-})
-
-/**
- * Validate the resolved configuration before publishing the backend.
- * @param config - Schemastery-resolved plugin configuration.
- * @returns Nothing; success narrows every optional field to its resolved value.
- */
-export function validateConfig(config: Config): asserts config is ResolvedConfig {
-  const resolved = config as ResolvedConfig
-  if (resolved.backendType.length === 0) throw new Error('pty-e2b: backendType must be non-empty')
-  for (const [name, value] of Object.entries(resolved)) {
-    if (typeof value === 'number' && (!Number.isSafeInteger(value) || value <= 0)) {
-      throw new Error(`pty-e2b: ${name} must be a positive safe integer`)
-    }
-  }
-  if (resolved.maxReadBytes > resolved.scrollbackMaxBytes) {
-    throw new Error('pty-e2b: maxReadBytes must not exceed scrollbackMaxBytes')
-  }
-}
-/* jscpd:ignore-end */
diff --git a/packages/e2b/pty-e2b/src/index.ts b/packages/e2b/pty-e2b/src/index.ts
deleted file mode 100644
index d665a734b7..0000000000
--- a/packages/e2b/pty-e2b/src/index.ts
+++ /dev/null
@@ -1,130 +0,0 @@
-/** E2B byte-PTY backend for persistent interactive terminal sessions. */
-
-import { posix } from 'node:path'
-import type { Context } from 'cordis'
-import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { PtyBackendCleanupError } from '@deepseek-ai/dsh-pty'
-import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
-import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
-import { E2BPtySession } from './session.ts'
-
-export { Config } from './config.ts'
-export type { Config as PtyE2BConfig } from './config.ts'
-export { E2BPtySession } from './session.ts'
-
-/** Cordis plugin name. */
-export const name = 'pty-e2b'
-/** Required shared sandbox owner and PTY registry. */
-export const inject = ['e2b', 'pty']
-
-const SENSITIVE_ENV_NAME = /KEY|SECRET|TOKEN/i
-
-async function terminalEnvironment(
-  sandbox: Sandbox,
-  spec: PtyBackendSpawnSpec,
-): Promise<Record<string, string>> {
-  const discovered = await sandbox.commands.run(
-    'env -0 | cut -z -d= -f1',
-    spec.signal === undefined ? {} : { signal: spec.signal },
-  )
-  spec.signal?.throwIfAborted()
-  const scrubbed = Object.fromEntries(discovered.stdout.split('\0')
-    .filter(name => name.startsWith('DSH_') || SENSITIVE_ENV_NAME.test(name))
-    .map(name => [name, '']))
-  return {
-    ...scrubbed,
-    TERM: 'dumb',
-    PAGER: 'cat',
-    GIT_PAGER: 'cat',
-    PS1: 'dsh> ',
-    PROMPT_COMMAND: 'printf "\\033]133;D;%s\\007" "$?"',
-    BASH_SILENCE_DEPRECATION_WARNING: '1',
-    DSH_SHELL: '1',
-    DSH_SESSION_ID: spec.owner.id,
-    DSH_PTY_SESSION_ID: spec.sessionId,
-  }
-}
-
-async function resolveTerminalSessionId(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<number> {
-  const result = await sandbox.commands.run(
-    `ps -o sid= -p ${pid}`,
-    signal === undefined ? {} : { signal },
-  )
-  signal?.throwIfAborted()
-  const raw = result.stdout.trim()
-  const sessionId = Number(raw)
-  if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(sessionId)) {
-    throw new Error(`pty-e2b: cannot resolve process session for E2B PTY ${pid}`)
-  }
-  return sessionId
-}
-
-/** E2B backend registered under the configured terminal type. */
-export class E2BPtyBackend implements PtyBackend {
-  readonly type: string
-
-  constructor(
-    private readonly ctx: Context,
-    private readonly config: ResolvedConfig,
-    private readonly createPty: (
-      sandbox: Sandbox,
-      options: Parameters<Sandbox['pty']['create']>[0],
-    ) => Promise<CommandHandle> = (sandbox, options) => sandbox.pty.create(options),
-  ) {
-    this.type = config.backendType
-  }
-
-  /** Create, initialize, and publish one remote PTY session. */
-  async spawn(spec: PtyBackendSpawnSpec): Promise<E2BPtySession> {
-    spec.signal?.throwIfAborted()
-    const sandbox = await this.ctx.e2b.getSandbox()
-    spec.signal?.throwIfAborted()
-    const pending: Uint8Array[] = []
-    const created: { session?: E2BPtySession } = {}
-    const handle = await this.createPty(sandbox, {
-      rows: this.config.rows,
-      cols: this.config.cols,
-      cwd: posix.resolve(this.ctx.e2b.cwd, spec.cwd ?? this.ctx.e2b.cwd),
-      envs: await terminalEnvironment(sandbox, spec),
-      timeoutMs: 0,
-      ...spec.signal === undefined ? {} : { signal: spec.signal },
-      onData: (data) => {
-        if (created.session === undefined) pending.push(Uint8Array.from(data))
-        else created.session.onData(data)
-      },
-    })
-    if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
-      await handle.kill().catch(() => false)
-      throw new Error(`pty-e2b: E2B returned invalid PTY pid ${handle.pid}`)
-    }
-    let terminalSessionId: number
-    try {
-      terminalSessionId = await resolveTerminalSessionId(sandbox, handle.pid, spec.signal)
-    } catch (error: unknown) {
-      await handle.kill().catch(() => false)
-      await Promise.allSettled([handle.wait()])
-      throw error
-    }
-    const session = new E2BPtySession(sandbox, handle, terminalSessionId, this.config)
-    created.session = session
-    try {
-      const initializing = session.initialize(spec.signal)
-      for (const data of pending) session.onData(data)
-      await initializing
-      return session
-    } catch (error: unknown) {
-      try {
-        await session.close('E2B PTY startup failed')
-      } catch (cleanupError: unknown) {
-        throw new PtyBackendCleanupError(error, cleanupError)
-      }
-      throw error
-    }
-  }
-}
-
-/** Register the E2B PTY backend. */
-export function apply(ctx: Context, config: Config): void {
-  validateConfig(config)
-  ctx.pty.registerBackend(new E2BPtyBackend(ctx, config))
-}
diff --git a/packages/e2b/pty-e2b/src/invariant.ts b/packages/e2b/pty-e2b/src/invariant.ts
deleted file mode 100644
index b86fdffc5d..0000000000
--- a/packages/e2b/pty-e2b/src/invariant.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-pty-e2b`. */
-
-/* jscpd:ignore-start */
-import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-pty-e2b'
-
-/** Cordis companion plugin name. */
-export const name = 'pty-e2b-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/** No runtime invariant: the PTY registry owns publication and cleanup. */
-const install: InvariantInstaller = () => {}
-
-/** Register this package's invariant companion. */
-export const apply = (ctx: Context): Promise<() => void> =>
-  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-/* jscpd:ignore-end */
diff --git a/packages/e2b/pty-e2b/src/session.ts b/packages/e2b/pty-e2b/src/session.ts
deleted file mode 100644
index 7742cd44f0..0000000000
--- a/packages/e2b/pty-e2b/src/session.ts
+++ /dev/null
@@ -1,415 +0,0 @@
-/** One byte-oriented E2B PTY session projected onto the harness PTY seam. */
-
-import { Buffer } from 'node:buffer'
-import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { CommandExitError } from '@deepseek-ai/dsh-e2b'
-import {
-  PtyTerminalSanitizer,
-  PtyTextBuffer,
-  ptySignalName,
-  ptyUtf8Tail,
-} from '@deepseek-ai/dsh-pty'
-import type {
-  PtyBackendSession,
-  PtyReadRequest,
-  PtyReadResult,
-  PtySendOperation,
-  PtySendRead,
-  PtySendRequest,
-  PtySendResult,
-  PtySessionStatus,
-  PtySignal,
-  PtySignalResult,
-  PtyWaitReason,
-} from '@deepseek-ai/dsh-pty'
-import type { ResolvedConfig } from './config.ts'
-
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}
-
-/* jscpd:ignore-start -- Operation state stays backend-local because process readiness and cleanup identities diverge. */
-class E2BSendOperation implements PtySendOperation {
-  private readonly output: PtyTextBuffer
-  private readonly result = Promise.withResolvers<PtySendResult>()
-  private finished = false
-
-  constructor(
-    maxBytes: number,
-    readonly startedAt: number,
-    private readonly onCancel: () => void,
-  ) {
-    this.output = new PtyTextBuffer(maxBytes)
-  }
-
-  get done(): Promise<PtySendResult> {
-    return this.result.promise
-  }
-
-  append(text: string): void {
-    if (!this.finished) this.output.append(text)
-  }
-
-  settle(waitReason: PtyWaitReason, sessionStatus: PtySessionStatus, inheritedTruncation: boolean): void {
-    if (this.finished) return
-    this.finished = true
-    const read = this.output.snapshot()
-    this.result.resolve({
-      viewport: read.text,
-      waitReason,
-      sessionStatus,
-      truncated: read.truncated || inheritedTruncation,
-    })
-  }
-
-  fail(error: unknown): void {
-    if (this.finished) return
-    this.finished = true
-    this.result.reject(error)
-  }
-
-  readOutput(): PtySendRead {
-    return this.output.consume()
-  }
-
-  cancel(): boolean {
-    if (this.finished) return false
-    this.onCancel()
-    return true
-  }
-}
-/* jscpd:ignore-end */
-
-/** Live session around one E2B SDK PTY handle. */
-export class E2BPtySession implements PtyBackendSession {
-  motd = ''
-  readonly pid: number
-  private readonly decoder = new TextDecoder('utf-8', { fatal: true })
-  private readonly sanitizer: PtyTerminalSanitizer
-  private readonly scrollback: PtyTextBuffer
-  private readonly exited = Promise.withResolvers<void>()
-  private statusValue: PtySessionStatus = { kind: 'running' }
-  private active: E2BSendOperation | undefined
-  private activeTimer: NodeJS.Timeout | undefined
-  private activeAbort: (() => void) | undefined
-  private promptSeen = false
-  private promptTextSeen = false
-  private initializing = false
-  private lastOutputAt = Date.now()
-  private closing = false
-  private closePromise: Promise<void> | undefined
-  private closeSignal: NodeJS.Signals | null = null
-  private transportFailure: Error | undefined
-  private remoteExited = false
-
-  constructor(
-    private readonly sandbox: Sandbox,
-    private readonly handle: CommandHandle,
-    private readonly terminalSessionId: number,
-    private readonly config: ResolvedConfig,
-  ) {
-    this.pid = handle.pid
-    this.sanitizer = new PtyTerminalSanitizer(config.maxReadBytes)
-    this.scrollback = new PtyTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
-    const completion = handle.wait()
-    void completion.then(
-      (result) => { this.onExit(result.exitCode) },
-      (error: unknown) => {
-        if (error instanceof CommandExitError) this.onExit(error.exitCode)
-        else this.onTransportFailure(error)
-      },
-    )
-  }
-
-  /**
-   * Consume bytes received by the SDK's PTY callback.
-   * @param data - Exact callback bytes in delivery order.
-   */
-  onData(data: Uint8Array): void {
-    let decoded: string
-    try {
-      decoded = this.decoder.decode(data, { stream: true })
-    } catch (error: unknown) {
-      this.onTransportFailure(new Error('pty-e2b: PTY emitted invalid UTF-8', { cause: error }))
-      return
-    }
-    const sanitized = this.sanitizer.push(decoded)
-    this.appendOutput(sanitized.text)
-    if (sanitized.prompt) {
-      this.promptSeen = true
-      this.promptTextSeen = sanitized.promptText === true
-      this.lastOutputAt = Date.now()
-    } else if (this.promptSeen && sanitized.promptText === true) {
-      this.promptTextSeen = true
-    }
-  }
-
-  /**
-   * Await the first prompt or bounded startup fallback.
-   * @param signal - Optional startup cancellation signal.
-   */
-  async initialize(signal?: AbortSignal): Promise<void> {
-    this.initializing = true
-    try {
-      const operation = this.startSend({ text: '', submit: false, ...signal === undefined ? {} : { signal } })
-      const result = await operation.done
-      if (result.waitReason === 'session_exit') throw new Error('E2B PTY shell exited during startup')
-      if (result.waitReason === 'timeout') throw new Error('E2B PTY shell did not reach readiness before startup timeout')
-      this.motd = result.viewport
-    } catch (error: unknown) {
-      signal?.throwIfAborted()
-      throw error
-    } finally {
-      this.initializing = false
-    }
-  }
-
-  /* jscpd:ignore-start -- PTY backends share request admission while owning distinct input and readiness transports. */
-  startSend(request: PtySendRequest): PtySendOperation {
-    if (this.closing) throw new Error('E2B PTY session is closing')
-    if (this.statusValue.kind === 'exited') throw new Error('E2B PTY session has exited')
-    if (this.active !== undefined) throw new Error('E2B PTY session already has an active send')
-    if (request.signal?.aborted === true) throw new Error('E2B PTY send aborted before write')
-
-    const operation = new E2BSendOperation(
-      this.config.maxReadBytes,
-      Date.now(),
-      () => { this.interrupt(operation) },
-    )
-    this.active = operation
-    this.lastOutputAt = Date.now()
-    this.promptSeen = false
-    this.promptTextSeen = false
-    if (request.signal !== undefined) {
-      const onAbort = (): void => { operation.cancel() }
-      request.signal.addEventListener('abort', onAbort, { once: true })
-      this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
-    }
-
-    const input = `${request.text}${request.submit ? '\r' : ''}`
-    if (input.length > 0) {
-      void this.sandbox.pty.sendInput(this.pid, Buffer.from(input)).catch((error: unknown) => {
-        if (this.active === operation) this.failActive(error)
-      })
-    }
-    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
-    return operation
-  }
-  /* jscpd:ignore-end */
-
-  /* jscpd:ignore-start -- The seam requires identical bounded-read coordinates across backend buffers. */
-  read(request: PtyReadRequest): PtyReadResult {
-    const snapshot = this.scrollback.snapshot()
-    const lines = snapshot.text.split('\n')
-    const totalLines = snapshot.text.length === 0 ? 0 : lines.length
-    const offset = request.offset ?? 0
-    const count = request.count ?? 500
-    if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('PTY read offset must be a non-negative safe integer')
-    if (!Number.isSafeInteger(count) || count <= 0) throw new Error('PTY read count must be a positive safe integer')
-    if (offset >= totalLines) {
-      return { text: '', totalLines, lineBegin: offset, lineEnd: offset, truncated: snapshot.truncated }
-    }
-    const end = totalLines - offset
-    const start = Math.max(0, end - count)
-    const bounded = ptyUtf8Tail(lines.slice(start, end).join('\n'), this.config.maxReadBytes)
-    const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split('\n').length
-    return {
-      text: bounded.text,
-      totalLines,
-      lineBegin: offset,
-      lineEnd: offset + returnedLines,
-      truncated: snapshot.truncated || bounded.truncated,
-    }
-  }
-  /* jscpd:ignore-end */
-
-  /* jscpd:ignore-start -- Signal, status, and close methods preserve the seam shape around remote identities. */
-  async signal(signal: PtySignal): Promise<PtySignalResult> {
-    const pgid = await this.foregroundPgid()
-    return await this.deliverSignal(signal, pgid)
-  }
-
-  private async deliverSignal(signal: PtySignal, pgid: number): Promise<PtySignalResult> {
-    if (signal === 'SIGKILL' && pgid === this.pid) {
-      throw new Error('refusing to SIGKILL the E2B PTY shell; use terminal_close')
-    }
-    await this.sandbox.commands.run(`kill -${signal.slice(3)} -- -${pgid}`)
-    return { delivered: true, targetPgid: pgid }
-  }
-
-  status(): PtySessionStatus {
-    return this.statusValue
-  }
-
-  close(reason: string): Promise<void> {
-    this.closing = true
-    if (this.closePromise !== undefined) return this.closePromise
-    const closing = this.closeOnce(reason).catch((error: unknown) => {
-      this.closePromise = undefined
-      this.failActive(error)
-      throw error
-    })
-    this.closePromise = closing
-    return closing
-  }
-  /* jscpd:ignore-end */
-
-  private appendOutput(text: string): void {
-    if (text.length === 0) return
-    this.lastOutputAt = Date.now()
-    this.scrollback.append(text)
-    this.active?.append(text)
-  }
-
-  private pollReadiness(operation: E2BSendOperation): void {
-    if (this.active !== operation) return
-    if (this.statusValue.kind === 'exited') {
-      this.settleActive('session_exit')
-      return
-    }
-    const elapsed = Date.now() - operation.startedAt
-    const idleFor = Date.now() - this.lastOutputAt
-    if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs) {
-      this.settleActive('stdin_read')
-      return
-    }
-    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
-    if (startupHasOutput && idleFor >= this.config.idleSilenceMs) {
-      this.settleActive('inferred_idle')
-      return
-    }
-    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
-  }
-
-  private settleActive(waitReason: PtyWaitReason): void {
-    const operation = this.active
-    if (operation === undefined) return
-    const inherited = this.scrollback.snapshot().truncated
-    this.clearActive()
-    operation.settle(waitReason, this.statusValue, inherited)
-  }
-
-  private clearActive(): void {
-    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
-    this.activeTimer = undefined
-    this.activeAbort?.()
-    this.activeAbort = undefined
-    this.active = undefined
-  }
-
-  private failActive(error: unknown): void {
-    const operation = this.active
-    if (operation === undefined) return
-    this.clearActive()
-    operation.fail(error)
-  }
-
-  private interrupt(operation: E2BSendOperation): void {
-    if (this.active !== operation) return
-    void this.interruptActive(operation).catch((error: unknown) => {
-      if (this.active === operation) this.failActive(error)
-    })
-  }
-
-  private async interruptActive(operation: E2BSendOperation): Promise<void> {
-    const pgid = await this.foregroundPgid()
-    if (this.active !== operation) return
-    await this.deliverSignal('SIGINT', pgid)
-  }
-
-  private async foregroundPgid(): Promise<number> {
-    const result = await this.sandbox.commands.run(`ps -o tpgid= -p ${this.pid}`)
-    const raw = result.stdout.trim()
-    const pgid = Number(raw)
-    if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(pgid)) {
-      throw new Error(`cannot resolve foreground process group for E2B PTY ${this.pid}`)
-    }
-    return pgid
-  }
-
-  private async sessionProcessGroups(): Promise<number[]> {
-    const result = await this.sandbox.commands.run(
-      `ps -eo sid=,pgid= | awk '$1 == ${this.terminalSessionId} { print $2 }'`,
-    )
-    const groups = new Set<number>()
-    for (const raw of result.stdout.trim().split(/\s+/)) {
-      if (raw.length === 0) continue
-      const pgid = Number(raw)
-      if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(pgid) || pgid <= 1) {
-        throw new Error(`pty-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${this.terminalSessionId}`)
-      }
-      groups.add(pgid)
-    }
-    return [...groups]
-  }
-
-  private async signalProcessGroups(groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
-    try {
-      await this.sandbox.commands.run(`kill -${signal} -- ${groups.map(pgid => `-${pgid}`).join(' ')}`)
-    } catch (error: unknown) {
-      if (!(error instanceof CommandExitError)) throw error
-    }
-  }
-
-  private async awaitSessionEmpty(timeoutMs: number, signal?: 'KILL'): Promise<number[]> {
-    const deadline = Date.now() + timeoutMs
-    for (;;) {
-      const groups = await this.sessionProcessGroups()
-      if (groups.length === 0 || Date.now() >= deadline) return groups
-      if (signal !== undefined) await this.signalProcessGroups(groups, signal)
-      await delay(Math.min(this.config.pollIntervalMs, deadline - Date.now()))
-    }
-  }
-
-  private onExit(exitCode: number): void {
-    this.remoteExited = true
-    let tail = ''
-    try {
-      tail = this.decoder.decode()
-    } catch (error: unknown) {
-      this.transportFailure ??= new Error('pty-e2b: PTY ended with invalid UTF-8', { cause: error })
-    }
-    this.appendOutput(this.sanitizer.push(tail).text)
-    this.appendOutput(this.sanitizer.flush())
-    const inferredSignal = this.closeSignal ?? (exitCode > 128 ? ptySignalName(exitCode - 128) : null)
-    this.statusValue = {
-      kind: 'exited',
-      exitCode: inferredSignal === null ? exitCode : null,
-      signal: inferredSignal,
-    }
-    if (this.transportFailure === undefined) this.settleActive('session_exit')
-    else this.failActive(this.transportFailure)
-    this.exited.resolve()
-  }
-
-  private onTransportFailure(error: unknown): void {
-    const failure = error instanceof Error ? error : new Error(String(error))
-    this.transportFailure ??= failure
-    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
-    this.failActive(failure)
-  }
-
-  private async closeOnce(reason: string): Promise<void> {
-    let survivingGroups = await this.sessionProcessGroups()
-    if (survivingGroups.length > 0) {
-      this.closeSignal = 'SIGTERM'
-      await this.signalProcessGroups(survivingGroups, 'TERM')
-      survivingGroups = await this.awaitSessionEmpty(this.config.disposeGraceMs)
-    }
-    if (survivingGroups.length > 0 || !this.remoteExited) {
-      this.closeSignal = 'SIGKILL'
-      if (!this.remoteExited) await this.sandbox.pty.kill(this.pid)
-      survivingGroups = await this.awaitSessionEmpty(this.config.disposeGraceMs, 'KILL')
-      if (!this.remoteExited) await Promise.race([this.exited.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (survivingGroups.length > 0) {
-      throw new Error(`E2B PTY cleanup failed (${reason}); surviving process groups: ${survivingGroups.join(', ')}`)
-    }
-    if (!this.remoteExited) {
-      throw new Error(`E2B PTY cleanup failed (${reason}); surviving pid: ${this.pid}`)
-    }
-    this.settleActive('session_exit')
-    await this.handle.disconnect().catch(() => {})
-    if (this.transportFailure !== undefined) throw this.transportFailure
-  }
-}
diff --git a/packages/e2b/pty-e2b/tests/index.spec.ts b/packages/e2b/pty-e2b/tests/index.spec.ts
deleted file mode 100644
index 476ddc38df..0000000000
--- a/packages/e2b/pty-e2b/tests/index.spec.ts
+++ /dev/null
@@ -1,248 +0,0 @@
-import { Context } from 'cordis'
-import { describe, expect, it, vi } from 'vitest'
-import type { CommandHandle, Sandbox } from '@deepseek-ai/dsh-e2b'
-import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import PtyService, { PtyBackendCleanupError, PtySessionId } from '@deepseek-ai/dsh-pty'
-import { E2BPtyBackend, apply } from '@deepseek-ai/dsh-pty-e2b'
-import { validateConfig } from '@deepseek-ai/dsh-pty-e2b/src/config.ts'
-import * as E2BPtyInvariant from '../src/invariant.ts'
-import InvariantService from '@deepseek-ai/dsh-invariants'
-import { AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
-
-function config() {
-  return {
-    backendType: 'shell', rows: 24, cols: 80,
-    scrollbackLines: 10, scrollbackMaxBytes: 128, maxReadBytes: 64,
-    pollIntervalMs: 1, idleSilenceMs: 2, timeoutMs: 5, disposeGraceMs: 1,
-  }
-}
-
-function owner(ctx: Context): Agent {
-  const id = SessionId('owner')
-  return {
-    id, options: {}, session: new Session(id), status: 'idle', acceptsNextStep: false, ctx,
-    followup: () => AgentMessageId('unused'), steer: () => AgentMessageId('unused'),
-    inject: () => AgentMessageId('unused'), send: () => AgentMessageId('unused'),
-    cancel() {}, whenIdle: () => Promise.resolve(),
-  }
-}
-
-function handle(pid = 123, kill = vi.fn().mockResolvedValue(true)): CommandHandle {
-  const result = Promise.withResolvers<{ exitCode: number; stdout: string; stderr: string }>()
-  return {
-    pid,
-    wait: () => result.promise,
-    kill,
-    disconnect: vi.fn().mockResolvedValue(undefined),
-  } as unknown as CommandHandle
-}
-
-describe('E2BPtyBackend and plugin', () => {
-  it('creates a remote PTY with isolated environment and initializes the session', async () => {
-    vi.useFakeTimers()
-    const ctx = new Context()
-    const run = vi.fn(async (command: string) => command.startsWith('env -0')
-      ? { exitCode: 0, stdout: 'NPM_TOKEN\0DSH_STALE\0KEEP\0', stderr: '' }
-      : { exitCode: 0, stdout: '123\n', stderr: '' })
-    const sandbox = { commands: { run } } as unknown as Sandbox
-    ctx.provide('e2b', {
-      cwd: '/workspace',
-      getSandbox: async () => sandbox,
-    } as E2BSandboxService)
-    const created = handle()
-    let options: Parameters<Sandbox['pty']['create']>[0] | undefined
-    const backend = new E2BPtyBackend(ctx, config(), async (_sandbox, received) => {
-      options = received
-      void received.onData(Buffer.from('banner\n'))
-      void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-      return created
-    })
-    const pending = backend.spawn({
-      sessionId: PtySessionId('pty-1'), owner: owner(ctx), type: 'shell', cwd: 'project',
-      signal: new AbortController().signal,
-    })
-    await vi.advanceTimersByTimeAsync(2)
-    const session = await pending
-
-    expect(session.motd).toBe('banner\ndsh> ')
-    expect(options).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace/project', timeoutMs: 0 })
-    expect(options?.envs).toMatchObject({
-      NPM_TOKEN: '', DSH_STALE: '',
-      TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ',
-      DSH_SHELL: '1', DSH_SESSION_ID: 'owner', DSH_PTY_SESSION_ID: 'pty-1',
-    })
-    expect(options?.envs).not.toHaveProperty('KEEP')
-    vi.useRealTimers()
-  })
-
-  it('uses the SDK PTY create method and the shared cwd by default', async () => {
-    vi.useFakeTimers()
-    const ctx = new Context()
-    const created = handle()
-    const create = vi.fn(async (received: Parameters<Sandbox['pty']['create']>[0]) => {
-      setTimeout(() => { void received.onData(Buffer.from('\x1b]133;D;0\x07dsh> ')) }, 0)
-      return created
-    })
-    const sandbox = {
-      commands: { run: async (command: string) => ({ exitCode: 0, stdout: command.startsWith('env -0') ? '' : '123\n', stderr: '' }) },
-      pty: { create },
-    } as unknown as Sandbox
-    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as unknown as E2BSandboxService)
-    const backend = new E2BPtyBackend(ctx, config())
-    const pending = backend.spawn({ sessionId: PtySessionId('default'), owner: owner(ctx), type: 'shell' })
-    await vi.advanceTimersByTimeAsync(2)
-    await pending
-    expect(create).toHaveBeenCalledWith(expect.objectContaining({ cwd: '/workspace' }))
-    vi.useRealTimers()
-  })
-
-  it('rejects aborts and invalid pids, killing a malformed SDK handle', async () => {
-    const ctx = new Context()
-    const sandbox = {
-      commands: { run: async () => ({ exitCode: 0, stdout: '', stderr: '' }) },
-    } as unknown as Sandbox
-    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
-    const create = vi.fn().mockResolvedValue(handle(0))
-    const backend = new E2BPtyBackend(ctx, config(), create)
-    const aborted = AbortSignal.abort(new Error('stop'))
-    await expect(backend.spawn({ sessionId: PtySessionId('one'), owner: owner(ctx), type: 'shell', signal: aborted })).rejects.toThrow('stop')
-    expect(create).not.toHaveBeenCalled()
-
-    const malformedKill = vi.fn().mockResolvedValue(true)
-    const malformed = handle(0, malformedKill)
-    const invalid = new E2BPtyBackend(ctx, config(), async () => malformed)
-    await expect(invalid.spawn({ sessionId: PtySessionId('two'), owner: owner(ctx), type: 'shell' })).rejects.toThrow('invalid PTY pid')
-    expect(malformedKill).toHaveBeenCalledOnce()
-
-    const killFailureKill = vi.fn().mockRejectedValue(new Error('already gone'))
-    const killFailure = handle(0, killFailureKill)
-    const raced = new E2BPtyBackend(ctx, config(), async () => killFailure)
-    await expect(raced.spawn({ sessionId: PtySessionId('three'), owner: owner(ctx), type: 'shell' })).rejects.toThrow('invalid PTY pid')
-
-    const invalidSessionKill = vi.fn().mockRejectedValue(new Error('kill raced'))
-    const invalidSessionHandle = {
-      pid: 123,
-      wait: vi.fn().mockRejectedValue(new Error('already exited')),
-      kill: invalidSessionKill,
-      disconnect: vi.fn(),
-    } as unknown as CommandHandle
-    const invalidSessionSandbox = {
-      commands: {
-        run: async (command: string) => ({
-          exitCode: 0,
-          stdout: command.startsWith('env -0') ? '' : '9007199254740992\n',
-          stderr: '',
-        }),
-      },
-    } as unknown as Sandbox
-    const invalidSessionContext = new Context()
-    invalidSessionContext.provide('e2b', {
-      cwd: '/workspace',
-      getSandbox: async () => invalidSessionSandbox,
-    } as E2BSandboxService)
-    const invalidSession = new E2BPtyBackend(invalidSessionContext, config(), async () => invalidSessionHandle)
-    await expect(invalidSession.spawn({
-      sessionId: PtySessionId('four'), owner: owner(invalidSessionContext), type: 'shell',
-    }))
-      .rejects.toThrow('cannot resolve process session')
-    expect(invalidSessionKill).toHaveBeenCalledOnce()
-  })
-
-  it('cleans failed startup and aggregates a cleanup failure', async () => {
-    vi.useFakeTimers()
-    const ctx = new Context()
-    const sandbox = {
-      commands: {
-        run: vi.fn(async (command: string) => ({
-          exitCode: 0,
-          stdout: command.startsWith('ps -o sid=') || command.startsWith('ps -eo sid=') ? '123\n' : '',
-          stderr: '',
-        })),
-      },
-      pty: { kill: vi.fn().mockRejectedValue(new Error('cleanup failed')) },
-    } as unknown as Sandbox
-    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as E2BSandboxService)
-    const failedHandle = handle()
-    const backend = new E2BPtyBackend(ctx, config(), async () => failedHandle)
-    const pending = backend.spawn({ sessionId: PtySessionId('failed'), owner: owner(ctx), type: 'shell' })
-    const rejected = expect(pending).rejects.toMatchObject({
-      name: 'PtyBackendCleanupError',
-      cleanupError: expect.objectContaining({ message: 'cleanup failed' }),
-    } satisfies Partial<PtyBackendCleanupError>)
-    await vi.advanceTimersByTimeAsync(6)
-    await vi.advanceTimersByTimeAsync(2)
-    await rejected
-    vi.useRealTimers()
-  })
-
-  it('preserves startup failure when cleanup succeeds', async () => {
-    vi.useFakeTimers()
-    const ctx = new Context()
-    const completion = Promise.withResolvers<{ exitCode: number; stdout: string; stderr: string }>()
-    const created = {
-      pid: 123,
-      wait: () => completion.promise,
-      disconnect: vi.fn().mockResolvedValue(undefined),
-    } as unknown as CommandHandle
-    let sessionRunning = true
-    const sandbox = {
-      commands: {
-        run: vi.fn(async (command: string) => {
-          if (command.startsWith('env -0')) return { exitCode: 0, stdout: '', stderr: '' }
-          if (command.startsWith('ps -o sid=')) return { exitCode: 0, stdout: '123\n', stderr: '' }
-          if (command.startsWith('ps -eo sid=')) {
-            return { exitCode: 0, stdout: sessionRunning ? '123\n' : '', stderr: '' }
-          }
-          if (command.startsWith('kill -TERM')) {
-            sessionRunning = false
-            completion.resolve({ exitCode: 143, stdout: '', stderr: '' })
-          }
-          return { exitCode: 0, stdout: '', stderr: '' }
-        }),
-      },
-      pty: { kill: vi.fn().mockResolvedValue(true) },
-    } as unknown as Sandbox
-    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => sandbox } as unknown as E2BSandboxService)
-    const backend = new E2BPtyBackend(ctx, config(), async () => created)
-    const rejected = expect(backend.spawn({ sessionId: PtySessionId('failed-clean'), owner: owner(ctx), type: 'shell' }))
-      .rejects.toThrow('startup timeout')
-    await vi.advanceTimersByTimeAsync(6)
-    await rejected
-    vi.useRealTimers()
-  })
-
-  it('validates configuration and registers the selected backend type', async () => {
-    const valid = config()
-    expect(() => { validateConfig(valid) }).not.toThrow()
-    for (const invalid of [
-      { ...valid, backendType: '' },
-      { ...valid, rows: 0 },
-      { ...valid, rows: 1.5 },
-      { ...valid, maxReadBytes: 129 },
-    ]) {
-      expect(() => { validateConfig(invalid) }).toThrow()
-    }
-
-    const registerBackend = vi.fn()
-    apply({ pty: { registerBackend } } as unknown as Context, valid)
-    expect(registerBackend).toHaveBeenCalledWith(expect.objectContaining({ type: 'shell' }))
-
-    const ctx = new Context()
-    await ctx.plugin(PtyService)
-    ctx.provide('e2b', { cwd: '/workspace', getSandbox: async () => ({}) } as never)
-    const fiber = await ctx.plugin({
-      inject: ['pty', 'e2b'],
-      apply: (pluginCtx: Context) => { apply(pluginCtx, valid) },
-    })
-    expect(ctx.pty.listBackends()).toEqual(['shell'])
-    await fiber.dispose()
-  })
-
-  it('registers the package-owned invariant companion', async () => {
-    const ctx = new Context()
-    await ctx.plugin(InvariantService, { enabled: true })
-    const fiber = await ctx.plugin(E2BPtyInvariant).await()
-    await fiber.dispose()
-  })
-})
diff --git a/packages/e2b/pty-e2b/tests/session.spec.ts b/packages/e2b/pty-e2b/tests/session.spec.ts
deleted file mode 100644
index 1fedf6bbac..0000000000
--- a/packages/e2b/pty-e2b/tests/session.spec.ts
+++ /dev/null
@@ -1,485 +0,0 @@
-import { Buffer } from 'node:buffer'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import {
-  CommandExitError,
-  type CommandHandle,
-  type CommandResult,
-  type Sandbox,
-} from '@deepseek-ai/dsh-e2b'
-import type { PtySendOperation, PtySessionStatus } from '@deepseek-ai/dsh-pty'
-import { E2BPtySession } from '@deepseek-ai/dsh-pty-e2b'
-import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-e2b/src/config.ts'
-
-function commandError(exitCode: number): CommandExitError {
-  return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
-}
-
-class FakePtyHandle {
-  pid = 123
-  readonly result = Promise.withResolvers<CommandResult>()
-  disconnects = 0
-  kills = 0
-  disconnectError: unknown
-  private settled = false
-
-  wait(): Promise<CommandResult> {
-    return this.result.promise
-  }
-
-  async disconnect(): Promise<void> {
-    this.disconnects += 1
-    if (this.disconnectError !== undefined) throw this.disconnectError
-  }
-
-  async kill(): Promise<boolean> {
-    this.kills += 1
-    return true
-  }
-
-  exit(exitCode = 0): void {
-    if (this.settled) return
-    this.settled = true
-    this.result.resolve({ exitCode, stdout: '', stderr: '' })
-  }
-
-  failExit(exitCode: number): void {
-    if (this.settled) return
-    this.settled = true
-    this.result.reject(commandError(exitCode))
-  }
-
-  crash(error: unknown): void {
-    if (this.settled) return
-    this.settled = true
-    this.result.reject(error)
-  }
-
-  asHandle(): CommandHandle {
-    return this as unknown as CommandHandle
-  }
-}
-
-class FakeSandbox {
-  readonly sent: Array<{ pid: number; data: Buffer }> = []
-  readonly commands: string[] = []
-  readonly killed: number[] = []
-  pgid = '456\n'
-  sessionGroups = [123]
-  sendError: unknown
-  signalError: unknown
-  killError: unknown
-  foregroundLookup: Promise<CommandResult> | undefined
-  onTerm: (() => void) | undefined
-  onGroupKill: (() => void) | undefined
-  onKill: (() => void) | undefined
-
-  readonly sandbox = {
-    pty: {
-      sendInput: async (pid: number, data: Uint8Array): Promise<void> => {
-        this.sent.push({ pid, data: Buffer.from(data) })
-        if (this.sendError !== undefined) throw this.sendError
-      },
-      kill: async (pid: number): Promise<boolean> => {
-        this.killed.push(pid)
-        if (this.killError !== undefined) throw this.killError
-        this.onKill?.()
-        return true
-      },
-    },
-    commands: {
-      run: async (command: string): Promise<CommandResult> => {
-        this.commands.push(command)
-        if (command.startsWith('ps -o tpgid')) {
-          return await (this.foregroundLookup ?? Promise.resolve({ exitCode: 0, stdout: this.pgid, stderr: '' }))
-        }
-        if (command.startsWith('ps -eo sid=')) {
-          return { exitCode: 0, stdout: this.sessionGroups.map(value => `${value}\n`).join(''), stderr: '' }
-        }
-        if (command.startsWith('kill -')) {
-          if (this.signalError !== undefined) {
-            const error = this.signalError
-            this.signalError = undefined
-            throw error
-          }
-          if (command.startsWith('kill -TERM')) this.onTerm?.()
-          if (command.startsWith('kill -KILL')) this.onGroupKill?.()
-        }
-        return { exitCode: 0, stdout: '', stderr: '' }
-      },
-    },
-  } as unknown as Sandbox
-}
-
-function config(overrides: Partial<ResolvedConfig> = {}): ResolvedConfig {
-  return {
-    backendType: 'shell', rows: 24, cols: 80,
-    scrollbackLines: 10, scrollbackMaxBytes: 128, maxReadBytes: 64,
-    pollIntervalMs: 10, idleSilenceMs: 40, timeoutMs: 100, disposeGraceMs: 20,
-    ...overrides,
-  }
-}
-
-async function initialize(session: E2BPtySession): Promise<void> {
-  const pending = session.initialize()
-  session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-  await vi.advanceTimersByTimeAsync(10)
-  await pending
-}
-
-afterEach(() => { vi.useRealTimers() })
-
-describe('E2BPtySession readiness, output, and signals', () => {
-  it('initializes, sends UTF-8 input, settles at a prompt, and reads bounded scrollback', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config({ maxReadBytes: 12 }))
-    expect(session.read({})).toMatchObject({ text: '', totalLines: 0 })
-    await initialize(session)
-    expect(session.motd).toBe('dsh> ')
-
-    const operation = session.startSend({ text: 'printf 你好', submit: true })
-    expect(fake.sent).toEqual([{ pid: 123, data: Buffer.from('printf 你好\r') }])
-    session.onData(Buffer.from('一\n二\n三\x1b]133;D;0\x07dsh> '))
-    const bounded = operation.readOutput()
-    expect(bounded.delta).toContain('三')
-    expect(bounded.truncated).toBe(true)
-    await vi.advanceTimersByTimeAsync(10)
-    expect(await operation.done).toMatchObject({ waitReason: 'stdin_read', sessionStatus: { kind: 'running' } })
-    expect(operation.cancel()).toBe(false)
-    expect(session.read({ count: 2 }).text).toContain('dsh>')
-    expect(session.read({ offset: 99 })).toMatchObject({ text: '', lineBegin: 99, lineEnd: 99 })
-    expect(() => session.read({ offset: -1 })).toThrow('non-negative safe integer')
-    expect(() => session.read({ offset: 1.5 })).toThrow('non-negative safe integer')
-    expect(() => session.read({ count: 0 })).toThrow('positive safe integer')
-    expect(() => session.read({ count: 1.5 })).toThrow('positive safe integer')
-
-    await expect(session.signal('SIGTERM')).resolves.toEqual({ delivered: true, targetPgid: 456 })
-    expect(fake.commands).toContain('kill -TERM -- -456')
-    expect(session.status()).toEqual({ kind: 'running' })
-  })
-
-  it('distinguishes inferred idle, timeout, session exit, and no-output startup timeout', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    await initialize(session)
-
-    const inferred = session.startSend({ text: '', submit: false })
-    await vi.advanceTimersByTimeAsync(40)
-    expect((await inferred.done).waitReason).toBe('inferred_idle')
-
-    const timeout = session.startSend({ text: '', submit: false })
-    for (let index = 0; index < 3; index += 1) {
-      await vi.advanceTimersByTimeAsync(30)
-      session.onData(Buffer.from('.'))
-    }
-    await vi.advanceTimersByTimeAsync(10)
-    expect((await timeout.done).waitReason).toBe('timeout')
-
-    const exiting = session.startSend({ text: '', submit: false })
-    handle.failExit(143)
-    expect(await exiting.done).toMatchObject({
-      waitReason: 'session_exit',
-      sessionStatus: { kind: 'exited', exitCode: null, signal: 'SIGTERM' },
-    })
-    expect(() => session.startSend({ text: '', submit: false })).toThrow('has exited')
-
-    const startupHandle = new FakePtyHandle()
-    const startup = new E2BPtySession(fake.sandbox, startupHandle.asHandle(), 123, config())
-    const timedOut = expect(startup.initialize()).rejects.toThrow('startup timeout')
-    await vi.advanceTimersByTimeAsync(100)
-    await timedOut
-  })
-
-  it('handles split prompt text, stale operations, and explicit cancellation', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    const initializing = session.initialize()
-    session.onData(Buffer.from('\x1b]133;D;0\x07'))
-    await vi.advanceTimersByTimeAsync(20)
-    session.onData(Buffer.from('dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await initializing
-
-    const operation = session.startSend({ text: 'sleep', submit: true })
-    const internal = session as unknown as {
-      pollReadiness(operation: PtySendOperation): void
-      interrupt(operation: PtySendOperation): void
-      settleActive(reason: 'timeout'): void
-      failActive(error: unknown): void
-      appendOutput(text: string): void
-      statusValue: PtySessionStatus
-    }
-    internal.pollReadiness({} as PtySendOperation)
-    internal.interrupt({} as PtySendOperation)
-    internal.appendOutput('')
-    fake.pgid = '789\n'
-    expect(operation.cancel()).toBe(true)
-    await vi.advanceTimersByTimeAsync(0)
-    expect(fake.commands).toContain('kill -INT -- -789')
-    session.onData(Buffer.from('\x1b]133;D;130\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await operation.done
-
-    internal.settleActive('timeout')
-    internal.failActive(new Error('ignored'))
-    const operationInternal = operation as unknown as {
-      append(text: string): void
-      settle(reason: 'timeout', status: PtySessionStatus, inherited: boolean): void
-      fail(error: unknown): void
-    }
-    operationInternal.append('ignored')
-    operationInternal.settle('timeout', { kind: 'running' }, false)
-    operationInternal.fail(new Error('ignored'))
-  })
-
-  it('observes AbortSignal and contains send or foreground lookup failures', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    await initialize(session)
-
-    const controller = new AbortController()
-    const aborting = session.startSend({ text: '', submit: false, signal: controller.signal })
-    expect(() => session.startSend({ text: '', submit: false })).toThrow('active send')
-    fake.pgid = 'not-a-pgid\n'
-    controller.abort()
-    await expect(aborting.done).rejects.toThrow('cannot resolve foreground process group')
-
-    const already = new AbortController()
-    already.abort()
-    expect(() => session.startSend({ text: '', submit: false, signal: already.signal })).toThrow('aborted before write')
-
-    fake.sendError = new Error('send failed')
-    const failed = session.startSend({ text: 'x', submit: false })
-    await expect(failed.done).rejects.toThrow('send failed')
-
-    fake.pgid = '123\n'
-    await expect(session.signal('SIGKILL')).rejects.toThrow('refusing to SIGKILL')
-    fake.pgid = '0\n'
-    await expect(session.signal('SIGINT')).rejects.toThrow('cannot resolve')
-
-    const deferred = Promise.withResolvers<undefined>()
-    fake.sendError = undefined
-    const sendInput = vi.spyOn(fake.sandbox.pty, 'sendInput').mockReturnValueOnce(deferred.promise)
-    const late = session.startSend({ text: 'late', submit: false })
-    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await late.done
-    deferred.reject(new Error('late failure'))
-    await vi.advanceTimersByTimeAsync(0)
-    expect(sendInput).toHaveBeenCalled()
-  })
-
-  it('does not let a stale interrupt signal or fail a successor send', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    await initialize(session)
-
-    const lookup = Promise.withResolvers<CommandResult>()
-    fake.foregroundLookup = lookup.promise
-    const stale = session.startSend({ text: 'old', submit: true })
-    expect(stale.cancel()).toBe(true)
-    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await stale.done
-
-    const successor = session.startSend({ text: 'new', submit: true })
-    fake.signalError = new Error('late interrupt failure')
-    lookup.resolve({ exitCode: 0, stdout: '789\n', stderr: '' })
-    await vi.advanceTimersByTimeAsync(0)
-    expect(fake.commands).not.toContain('kill -INT -- -789')
-    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await expect(successor.done).resolves.toMatchObject({ waitReason: 'stdin_read' })
-
-    const failedLookup = Promise.withResolvers<CommandResult>()
-    fake.foregroundLookup = failedLookup.promise
-    const staleFailure = session.startSend({ text: 'old failure', submit: true })
-    expect(staleFailure.cancel()).toBe(true)
-    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await staleFailure.done
-    const finalSuccessor = session.startSend({ text: 'new after failure', submit: true })
-    failedLookup.reject(new Error('late lookup failure'))
-    await vi.advanceTimersByTimeAsync(0)
-    session.onData(Buffer.from('\x1b]133;D;0\x07dsh> '))
-    await vi.advanceTimersByTimeAsync(10)
-    await expect(finalSuccessor.done).resolves.toMatchObject({ waitReason: 'stdin_read' })
-  })
-
-  it('preserves startup abort reasons and classifies invalid UTF-8 transport failures', async () => {
-    const fake = new FakeSandbox()
-    const abortHandle = new FakePtyHandle()
-    const abortSession = new E2BPtySession(fake.sandbox, abortHandle.asHandle(), 123, config())
-    const controller = new AbortController()
-    const reason = new Error('startup cancelled')
-    const initializing = abortSession.initialize(controller.signal)
-    const rejected = expect(initializing).rejects.toBe(reason)
-    controller.abort(reason)
-    await rejected
-
-    const invalidHandle = new FakePtyHandle()
-    const invalid = new E2BPtySession(fake.sandbox, invalidHandle.asHandle(), 123, config())
-    const pending = invalid.startSend({ text: '', submit: false })
-    invalid.onData(Uint8Array.from([0xff]))
-    await expect(pending.done).rejects.toThrow('invalid UTF-8')
-    expect(invalid.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
-
-    const crashHandle = new FakePtyHandle()
-    const crashed = new E2BPtySession(fake.sandbox, crashHandle.asHandle(), 123, config())
-    const active = crashed.startSend({ text: '', submit: false })
-    crashHandle.crash('transport gone')
-    await expect(active.done).rejects.toEqual(new Error('transport gone'))
-
-    const startupExitHandle = new FakePtyHandle()
-    const startupExit = new E2BPtySession(fake.sandbox, startupExitHandle.asHandle(), 123, config())
-    const exitedDuringStartup = expect(startupExit.initialize()).rejects.toThrow('exited during startup')
-    startupExitHandle.exit(7)
-    await exitedDuringStartup
-  })
-
-  it('covers empty bounded reads and polling an exited active session', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const tinyHandle = new FakePtyHandle()
-    const tiny = new E2BPtySession(fake.sandbox, tinyHandle.asHandle(), 123, config({ maxReadBytes: 1 }))
-    tiny.onData(Buffer.from('你'))
-    expect(tiny.read({ count: 1 })).toMatchObject({ text: '', lineEnd: 0 })
-
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    const operation = session.startSend({ text: '', submit: false })
-    const internal = session as unknown as {
-      pollReadiness(operation: PtySendOperation): void
-      clearActive(): void
-      statusValue: PtySessionStatus
-    }
-    internal.statusValue = { kind: 'exited', exitCode: 7, signal: null }
-    internal.pollReadiness(operation)
-    expect((await operation.done).waitReason).toBe('session_exit')
-    internal.clearActive()
-  })
-})
-
-describe('E2BPtySession teardown', () => {
-  it('terminates the process group once, awaits exit, and disconnects', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    fake.onTerm = () => { fake.sessionGroups = []; handle.failExit(143) }
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    const first = session.close('done')
-    expect(session.close('again')).toBe(first)
-    await first
-    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: 'SIGTERM' })
-    expect(handle.disconnects).toBe(1)
-    expect(() => session.startSend({ text: '', submit: false })).toThrow('closing')
-  })
-
-  it('escalates every job-control group that survives shell exit', async () => {
-    vi.useFakeTimers()
-    const fake = new FakeSandbox()
-    fake.sessionGroups = [123, 456]
-    const handle = new FakePtyHandle()
-    fake.onTerm = () => { fake.sessionGroups = [456]; handle.failExit(143) }
-    fake.onGroupKill = () => { fake.sessionGroups = [] }
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-
-    const closing = session.close('tree cleanup')
-    await vi.advanceTimersByTimeAsync(100)
-    await closing
-
-    expect(fake.commands).toContain('kill -TERM -- -123 -456')
-    expect(fake.commands).toContain('kill -KILL -- -456')
-  })
-
-  it('contains an already-gone TERM, escalates to KILL, and reports a survivor', async () => {
-    vi.useFakeTimers()
-    const gone = new FakeSandbox()
-    const goneHandle = new FakePtyHandle()
-    gone.signalError = commandError(1)
-    gone.onGroupKill = () => { gone.sessionGroups = [] }
-    gone.onKill = () => { goneHandle.failExit(137) }
-    const goneSession = new E2BPtySession(gone.sandbox, goneHandle.asHandle(), 123, config())
-    const closingGone = goneSession.close('gone')
-    await vi.advanceTimersByTimeAsync(100)
-    await closingGone
-    expect(gone.killed).toEqual([123])
-    expect(goneSession.status()).toEqual({ kind: 'exited', exitCode: null, signal: 'SIGKILL' })
-
-    const survivor = new FakeSandbox()
-    const survivorHandle = new FakePtyHandle()
-    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), 123, config())
-    const failed = expect(survivorSession.close('still alive')).rejects.toThrow('surviving process groups: 123')
-    await vi.advanceTimersByTimeAsync(100)
-    await failed
-    survivorHandle.exit()
-    survivor.sessionGroups = []
-    await expect(survivorSession.close('retry')).resolves.toBeUndefined()
-  })
-
-  it('propagates cleanup transport failures and lets close retry', async () => {
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    fake.signalError = new Error('TERM transport failed')
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    await expect(session.close('failure')).rejects.toThrow('TERM transport failed')
-    handle.exit()
-    fake.sessionGroups = []
-    await expect(session.close('retry')).resolves.toBeUndefined()
-
-    const invalidTailHandle = new FakePtyHandle()
-    const invalidTail = new E2BPtySession(fake.sandbox, invalidTailHandle.asHandle(), 123, config())
-    invalidTail.onData(Uint8Array.from([0xe2]))
-    invalidTailHandle.exit()
-    await expect(invalidTail.close('invalid tail')).rejects.toThrow('invalid UTF-8')
-
-    const normalHandle = new FakePtyHandle()
-    normalHandle.disconnectError = new Error('disconnect raced')
-    const normal = new E2BPtySession(fake.sandbox, normalHandle.asHandle(), 123, config())
-    normalHandle.exit(7)
-    await Promise.resolve()
-    expect(normal.status()).toEqual({ kind: 'exited', exitCode: 7, signal: null })
-    await expect(normal.close('already exited')).resolves.toBeUndefined()
-  })
-
-  it('rejects invalid session groups and a shell handle that survives SDK kill', async () => {
-    const invalid = new FakeSandbox()
-    invalid.sessionGroups = [1]
-    const invalidSession = new E2BPtySession(invalid.sandbox, new FakePtyHandle().asHandle(), 123, config())
-    await expect(invalidSession.close('invalid group')).rejects.toThrow('invalid process group')
-
-    vi.useFakeTimers()
-    const survivor = new FakeSandbox()
-    survivor.sessionGroups = []
-    const survivorHandle = new FakePtyHandle()
-    const survivorSession = new E2BPtySession(survivor.sandbox, survivorHandle.asHandle(), 123, config())
-    const failed = expect(survivorSession.close('shell survived')).rejects.toThrow('surviving pid: 123')
-    await vi.advanceTimersByTimeAsync(100)
-    await failed
-    expect(survivor.killed).toEqual([123])
-  })
-
-  it('kills a remotely live PTY after its host transport fails', async () => {
-    const fake = new FakeSandbox()
-    const handle = new FakePtyHandle()
-    const session = new E2BPtySession(fake.sandbox, handle.asHandle(), 123, config())
-    const active = session.startSend({ text: '', submit: false })
-    session.onData(Uint8Array.from([0xff]))
-    await expect(active.done).rejects.toThrow('invalid UTF-8')
-    expect(session.status()).toEqual({ kind: 'exited', exitCode: null, signal: null })
-
-    fake.onTerm = () => { fake.sessionGroups = []; handle.failExit(143) }
-    await expect(session.close('transport failed')).rejects.toThrow('invalid UTF-8')
-    expect(fake.commands).toContain('kill -TERM -- -123')
-    expect(handle.disconnects).toBe(1)
-  })
-})
diff --git a/packages/e2b/pty-e2b/tsconfig.json b/packages/e2b/pty-e2b/tsconfig.json
deleted file mode 100644
index 06bf0cd589..0000000000
--- a/packages/e2b/pty-e2b/tsconfig.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src"],
-  "references": [
-    { "path": "../../../vendor/cosmokit" },
-    { "path": "../../../vendor/cordis" },
-    { "path": "../../../vendor/schemastery" },
-    { "path": "../e2b" },
-    { "path": "../../pty/pty" },
-    { "path": "../../support/invariants" }
-  ]
-}
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index f05191a45b..dca7b016c2 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 066d35a099f560fe40fe629ede632c37535129f7
-README.zh.md: d3af14e8cc58c7d86331156358f78a0abbb24c39
+README.md: e0805345e708c67c6de721d95641e2366a7f990e
+README.zh.md: f83969c794e50f0658aa86218a0f5f3c89d53b56
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 066d35a099..e0805345e7 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -2,16 +2,18 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing consumers such as [`dsh-bash-local`](../../bash/bash-local/README.md) then execute in the shared remote sandbox without an E2B-specific Bash adapter.
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, LSP, and subprocess Code Runtime consumers then execute in the shared remote sandbox without E2B-specific capability packages.
 
 ## Behavior
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; `done`, stdin, termination, and `waitForExit()` wait for readiness internally.
+- **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. If publication fails, the SDK PID remains the provisional `exec setsid` group id; rollback kills and verifies that group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
 - **Stdio projection** — pipe mode forwards E2B callbacks into host Node streams; inherit mode forwards them to the harness process streams; collect mode retains a bounded host tail with offset reads. Optional complete spill files are written remotely and advertised only while within their cap. Batch and streaming stdin use the SDK handle.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
-The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands.
+The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
 ## Model Experience
 
@@ -24,9 +26,10 @@ No direct invalidation; the named consumers own any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate even when this adapter exposes bounded tails, so the subprocess seam's normal host-memory bound is not achieved.
-- **Pipe output is not byte-faithful** — E2B delivers separately decoded strings rather than raw bytes, so split multibyte sequences and arbitrary binary protocols can be corrupted; LSP and other framed byte-stream consumers are unsupported.
+- **Command-pipe output is text-decoded by the SDK** — valid UTF-8 protocol traffic, including the exercised LSP composition and Code Runtime's ASCII/base64 frames, is supported; arbitrary binary protocols and invalid UTF-8 are not byte-faithful.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
 - **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
 - **Signal attribution is inferred** — when termination was requested and E2B reports a nonzero exit code, the adapter reports the last requested signal because the SDK result does not identify the terminating signal.
-- **Linux utility and E2B transport semantics are assumed** — there is no PTY, Windows, arbitrary-template, or network-partition fidelity layer.
+- **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
+- **Linux utility and E2B transport semantics are assumed** — there is no Windows, arbitrary-template, escaped-session recovery, or network-partition fidelity layer.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index d3af14e8cc..f83969c794 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -2,16 +2,18 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。随后，[`dsh-bash-local`](../../bash/bash-local/README.md) 等现有消费方会在共享远程沙箱中执行，无需 E2B 专用 Bash 适配器。
+[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY、LSP 以及使用 subprocess 的 Code Runtime 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
 
 ## 行为
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；`done`、stdin、终止和 `waitForExit()` 会在内部等待就绪。
+- **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。如果发布失败，SDK PID 仍为临时的 `exec setsid` 进程组 ID；回滚会终止并验证该进程组，随后启动操作才会以拒绝结束。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
 - **stdio 投影**：pipe 模式把 E2B 回调转发到宿主 Node 流；inherit 模式把回调转发到 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。可选的完整 spill 文件写在远程，并且只有未超过其上限时才会对外公布。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
-基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令。
+基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
 ## 模型体验
 
@@ -24,9 +26,10 @@
 ## 已知限制与延后工作
 
 - **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会持续累积，因此无法达到进程管理 seam 通常提供的宿主内存边界。
-- **Pipe 输出并非字节保真**：E2B 交付的是分别解码后的字符串，而不是原始字节，因此拆分的多字节序列和任意二进制协议可能损坏；不支持 LSP 及其他带帧字节流消费方。
+- **命令管道输出由 SDK 解码为文本**：支持有效的 UTF-8 协议流量，包括已经过测试的 LSP 组合与 Code Runtime 的 ASCII/base64 帧；任意二进制协议和无效 UTF-8 不具备字节保真。
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
 - **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
 - **信号归因依靠推断**：如果已经请求终止，而 E2B 报告非零退出码，适配器会报告最后请求的信号，因为 SDK 结果不标识终止信号。
-- **依赖 Linux 工具与 E2B 传输语义**：没有 PTY、Windows、任意模板或网络分区的保真层。
+- **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
+- **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、任意模板、逃逸会话恢复或网络分区的保真层。
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 2856df67bd..1547e1b46e 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -8,29 +8,87 @@ import { randomUUID } from 'node:crypto'
 import { posix } from 'node:path'
 import { Context } from 'cordis'
 import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
-import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import type {
+  SubprocessHandle,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import { quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import { E2BSubprocessHandle } from './process.ts'
+import { spawnE2BTerminal } from './terminal.ts'
+
+function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
 
 /** E2B command manager registered as `ctx.subprocess`. */
 export class E2BSubprocessService extends SubprocessService {
   static inject = ['e2b']
 
   private readonly live = new Set<E2BSubprocessHandle>()
+  private readonly terminals = new Set<SubprocessTerminalHandle>()
+
+  /** @inheritdoc */
+  readonly cwd: string
+
+  /** @inheritdoc */
+  readonly runtimeRoot: string
 
   /** Create the E2B subprocess service and bind its disposal policy. */
   constructor(ctx: Context) {
     super(ctx)
+    this.cwd = ctx.e2b.cwd
+    this.runtimeRoot = ctx.e2b.runtimeRoot
     ctx.effect(() => async () => {
       const handles = [...this.live]
-      for (const handle of handles) handle.terminate()
-      await Promise.all(handles.map(async (handle) => {
-        await handle.done.catch(() => {})
-        await handle.waitForExit()
-      }))
+      const terminals = [...this.terminals]
+      const pending: Promise<unknown>[] = []
+      for (const handle of handles) {
+        handle.terminate()
+        pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))
+      }
+      for (const terminal of terminals) {
+        terminal.terminate()
+        pending.push(terminal.waitForExit())
+      }
       this.live.clear()
+      this.terminals.clear()
+      await Promise.all(pending)
     }, 'e2b subprocess teardown')
   }
 
+  /** @inheritdoc */
+  async resolveExecutable(
+    command: string,
+    env?: Readonly<Record<string, string>>,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    if (command.length === 0) throw new Error('subprocess-e2b: executable name must be non-empty')
+    signal?.throwIfAborted()
+    const sandbox = await this.ctx.e2b.getSandbox()
+    if (posix.isAbsolute(command)) {
+      await sandbox.commands.run(
+        `test -f ${quoteE2BShellArg(command)} -a -x ${quoteE2BShellArg(command)}`,
+        signalOpts(signal),
+      )
+      signal?.throwIfAborted()
+      return command
+    }
+    const path = env?.PATH
+    const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
+    const result = await sandbox.commands.run(
+      `${prefix}command -v -- ${quoteE2BShellArg(command)}`,
+      signalOpts(signal),
+    )
+    signal?.throwIfAborted()
+    const executable = result.stdout.trim()
+    if (!posix.isAbsolute(executable) || executable.includes('\n')) {
+      throw new Error(`subprocess-e2b: executable ${JSON.stringify(command)} did not resolve to one absolute path`)
+    }
+    return executable
+  }
+
   /** @inheritdoc */
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
     const program = spec.argv[0]
@@ -53,6 +111,29 @@ export class E2BSubprocessService extends SubprocessService {
     void handle.done.then(release, release).catch(() => {})
     return handle
   }
+
+  /** @inheritdoc */
+  async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    const program = spec.argv[0]
+    if (program === undefined || program.length === 0) {
+      throw new Error('subprocess-e2b: terminal argv must contain a program')
+    }
+    for (const [name, value] of [['rows', spec.rows], ['cols', spec.cols], ['graceMs', spec.graceMs]] as const) {
+      if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`subprocess-e2b: terminal ${name} must be a positive safe integer`)
+      }
+    }
+    spec.signal?.throwIfAborted()
+    const stateDir = posix.join(this.runtimeRoot, 'terminals', randomUUID())
+    const terminal = await spawnE2BTerminal(this.ctx.e2b, spec, stateDir)
+    this.terminals.add(terminal)
+    const release = async (): Promise<void> => {
+      await terminal.waitForExit()
+      this.terminals.delete(terminal)
+    }
+    void terminal.done.then(release, release).catch(() => {})
+    return terminal
+  }
 }
 
 export default E2BSubprocessService
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
new file mode 100644
index 0000000000..88bea44fde
--- /dev/null
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -0,0 +1,386 @@
+/** E2B PTY allocation and process-session ownership for the subprocess seam. */
+
+import { Buffer } from 'node:buffer'
+import { constants } from 'node:os'
+import { PassThrough } from 'node:stream'
+import { posix } from 'node:path'
+import {
+  CommandExitError,
+  FileNotFoundError,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
+import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSignal,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+
+const POLL_MS = 20
+
+const TERMINAL_RUNNER_SOURCE = [
+  '#!/bin/bash',
+  'set -euo pipefail',
+  'dsh_state=$1',
+  'mapfile -d \'\' -t dsh_env < "$dsh_state/environment"',
+  'mapfile -d \'\' -t dsh_argv < "$dsh_state/argv"',
+  'rm -f -- "$dsh_state/environment" "$dsh_state/argv" "$dsh_state/runner.bash"',
+  'if (( ${#dsh_argv[@]} == 0 )); then',
+  "  printf 'terminal runner received empty argv\\n' >&2",
+  '  exit 125',
+  'fi',
+  "printf 'ready\\n' > \"$dsh_state/ready\"",
+  'exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"',
+  '',
+].join('\n')
+
+interface TerminalPaths {
+  runner: string
+  environment: string
+  argv: string
+  ready: string
+}
+
+function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function commandSignal(exitCode: number): NodeJS.Signals | null {
+  const number = exitCode - 128
+  if (number <= 0) return null
+  for (const [name, value] of Object.entries(constants.signals)) {
+    if (value === number) return name as NodeJS.Signals
+  }
+  return null
+}
+
+function parsePositiveId(value: string, message: string): number {
+  const raw = value.trim()
+  const id = Number(raw)
+  if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(id)) throw new Error(message)
+  return id
+}
+
+function serializeValues(values: readonly string[], kind: string): string {
+  for (const value of values) {
+    if (value.includes('\0')) throw new Error(`subprocess-e2b: terminal ${kind} must not contain NUL bytes`)
+  }
+  return values.map(value => `${value}\0`).join('')
+}
+
+function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
+  const environment = new Map<string, string>()
+  for (const entry of raw.split('\0')) {
+    if (entry.length === 0) continue
+    const separator = entry.indexOf('=')
+    if (separator <= 0) continue
+    const name = entry.slice(0, separator)
+    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
+    environment.set(name, entry.slice(separator + 1))
+  }
+  for (const [name, value] of Object.entries(explicit ?? {})) {
+    if (name.length === 0 || name.includes('=') || name.includes('\0') || value.includes('\0')) {
+      throw new Error('subprocess-e2b: terminal environment entries require non-empty NUL-free names without = and NUL-free values')
+    }
+    environment.set(name, value)
+  }
+  return serializeValues([...environment].map(([name, value]) => `${name}=${value}`), 'environment')
+}
+
+async function terminalSessionId(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<number> {
+  const result = await sandbox.commands.run(`ps -o sid= -p ${pid}`, signalOpts(signal))
+  signal?.throwIfAborted()
+  return parsePositiveId(result.stdout, `subprocess-e2b: cannot resolve process session for terminal ${pid}`)
+}
+
+async function waitUntilReady(
+  sandbox: Sandbox,
+  paths: TerminalPaths,
+  completion: Promise<CommandResult>,
+  signal?: AbortSignal,
+): Promise<void> {
+  const settled = completion.then(() => true, () => true)
+  for (;;) {
+    signal?.throwIfAborted()
+    try {
+      if ((await sandbox.files.read(paths.ready, signalOpts(signal))).trim() === 'ready') return
+    } catch (error: unknown) {
+      if (!(error instanceof FileNotFoundError)) throw error
+    }
+    if (await Promise.race([settled, delay(POLL_MS).then(() => false)])) {
+      throw new Error('subprocess-e2b: terminal exited before publishing readiness')
+    }
+  }
+}
+
+/** One E2B PTY and all process groups in its remote process session. */
+export class E2BTerminalHandle implements SubprocessTerminalHandle {
+  readonly pid: number
+  readonly done: Promise<SubprocessOutcome>
+
+  private topLevelExited = false
+  private termination: Promise<void> | undefined
+  private terminationSignal: NodeJS.Signals | null = null
+  private removeAbort: (() => void) | undefined
+
+  constructor(
+    private readonly sandbox: Sandbox,
+    private readonly handle: CommandHandle,
+    readonly output: PassThrough,
+    private readonly completion: Promise<CommandResult>,
+    private readonly sessionId: number,
+    private readonly stateDir: string,
+    private readonly graceMs: number,
+    signal?: AbortSignal,
+  ) {
+    this.pid = handle.pid
+    this.done = this.waitForCommand()
+    void this.done.then(() => { this.terminate() }, () => { this.terminate() })
+    if (signal !== undefined) {
+      const onAbort = (): void => { this.terminate() }
+      signal.addEventListener('abort', onAbort, { once: true })
+      this.removeAbort = () => { signal.removeEventListener('abort', onAbort) }
+      if (signal.aborted) this.terminate()
+    }
+  }
+
+  /** @inheritdoc */
+  async write(data: Uint8Array): Promise<void> {
+    if (this.topLevelExited) throw new Error('terminal process has exited')
+    await this.sandbox.pty.sendInput(this.pid, data)
+  }
+
+  /** @inheritdoc */
+  async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+    try {
+      const result = await this.sandbox.commands.run(`ps -o tpgid= -p ${this.pid}`)
+      return {
+        processGroupId: parsePositiveId(
+          result.stdout,
+          `subprocess-e2b: cannot resolve foreground process group for terminal ${this.pid}`,
+        ),
+        // E2B exposes process-table commands but not the /proc memory access
+        // needed to prove a specific syscall is waiting on fd 0.
+        inputWaiting: false,
+      }
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError && this.topLevelExited) return undefined
+      throw error
+    }
+  }
+
+  /** @inheritdoc */
+  async signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
+    const foreground = await this.inspectForeground()
+    if (foreground === undefined) {
+      throw new Error(`subprocess-e2b: cannot resolve foreground process group for terminal ${this.pid}`)
+    }
+    if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
+      throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
+    }
+    await this.sandbox.commands.run(`kill -${signal.slice(3)} -- -${foreground.processGroupId}`)
+    return foreground.processGroupId
+  }
+
+  /** @inheritdoc */
+  terminate(): void {
+    this.termination ??= this.closeOnce().catch((error: unknown) => {
+      this.termination = undefined
+      throw error
+    })
+    void this.termination.catch(() => {})
+  }
+
+  /** @inheritdoc */
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    const quiescence = this.termination ?? this.done.then(
+      () => { this.terminate(); return this.termination },
+      () => { this.terminate(); return this.termination },
+    )
+    if (signal === undefined) {
+      await quiescence
+      return true
+    }
+    if (signal.aborted) return false
+    return await new Promise<boolean>((resolve, reject) => {
+      const onAbort = (): void => { cleanup(); resolve(false) }
+      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      void quiescence.then(
+        () => { cleanup(); resolve(true) },
+        (error: unknown) => {
+          cleanup()
+          reject(error instanceof Error ? error : new Error(String(error)))
+        },
+      )
+    })
+  }
+
+  private async waitForCommand(): Promise<SubprocessOutcome> {
+    try {
+      const result = await this.completion
+      return { exitCode: result.exitCode, signal: null }
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError) {
+        const signal = this.terminationSignal ?? commandSignal(error.exitCode)
+        return signal === null ? { exitCode: error.exitCode, signal: null } : { exitCode: null, signal }
+      }
+      this.output.destroy(error instanceof Error ? error : new Error(String(error)))
+      throw error
+    } finally {
+      this.topLevelExited = true
+      if (!this.output.destroyed) this.output.end()
+    }
+  }
+
+  private async sessionProcessGroups(): Promise<number[]> {
+    const result = await this.sandbox.commands.run(
+      `ps -eo sid=,pgid= | awk '$1 == ${this.sessionId} { print $2 }'`,
+    )
+    const groups = new Set<number>()
+    for (const raw of result.stdout.trim().split(/\s+/)) {
+      if (raw.length === 0) continue
+      const group = parsePositiveId(
+        raw,
+        `subprocess-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${this.sessionId}`,
+      )
+      if (group <= 1) {
+        throw new Error(`subprocess-e2b: unsafe process group ${group} in terminal session ${this.sessionId}`)
+      }
+      groups.add(group)
+    }
+    return [...groups]
+  }
+
+  private async signalGroups(groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
+    if (groups.length === 0) return
+    try {
+      await this.sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
+    } catch (error: unknown) {
+      if (!(error instanceof CommandExitError)) throw error
+    }
+  }
+
+  private async awaitSessionEmpty(kill = false): Promise<number[]> {
+    const deadline = Date.now() + this.graceMs
+    for (;;) {
+      const groups = await this.sessionProcessGroups()
+      if (groups.length === 0 || Date.now() >= deadline) return groups
+      if (kill) await this.signalGroups(groups, 'KILL')
+      await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
+    }
+  }
+
+  private async closeOnce(): Promise<void> {
+    let groups = await this.sessionProcessGroups()
+    if (groups.length > 0) {
+      this.terminationSignal = 'SIGTERM'
+      await this.signalGroups(groups, 'TERM')
+      groups = await this.awaitSessionEmpty()
+    }
+    if (groups.length === 0 && !this.topLevelExited) {
+      await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
+    }
+    if (groups.length > 0 || !this.topLevelExited) {
+      this.terminationSignal = 'SIGKILL'
+      if (!this.topLevelExited) await this.sandbox.pty.kill(this.pid)
+      groups = await this.awaitSessionEmpty(true)
+      if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
+    }
+    if (groups.length > 0) {
+      throw new Error(`subprocess-e2b: terminal cleanup failed; surviving process groups: ${groups.join(', ')}`)
+    }
+    if (!this.topLevelExited) {
+      throw new Error(`subprocess-e2b: terminal cleanup failed; surviving pid: ${this.pid}`)
+    }
+    this.removeAbort?.()
+    this.removeAbort = undefined
+    await this.handle.disconnect()
+    await this.sandbox.files.remove(this.stateDir).catch(() => {})
+  }
+}
+
+/**
+ * Allocate an E2B PTY, replace its bootstrap shell with the requested argv,
+ * and return only after the private runner has published readiness.
+ * @param runtime - Shared E2B sandbox owner.
+ * @param spec - Fully specified terminal-process request.
+ * @param stateDir - Private remote directory for one startup transaction.
+ * @returns The live subprocess terminal handle.
+ */
+export async function spawnE2BTerminal(
+  runtime: E2BSandboxService,
+  spec: SubprocessTerminalSpawnSpec,
+  stateDir: string,
+): Promise<E2BTerminalHandle> {
+  const sandbox = await runtime.getSandbox()
+  spec.signal?.throwIfAborted()
+  const paths: TerminalPaths = {
+    runner: posix.join(stateDir, 'runner.bash'),
+    environment: posix.join(stateDir, 'environment'),
+    argv: posix.join(stateDir, 'argv'),
+    ready: posix.join(stateDir, 'ready'),
+  }
+  const ambient = await sandbox.commands.run('env -0', signalOpts(spec.signal))
+  const environment = remoteEnvironment(ambient.stdout, spec.env)
+  const argv = serializeValues(spec.argv, 'argv')
+  await sandbox.files.makeDir(stateDir)
+  await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stateDir)}`, signalOpts(spec.signal))
+  await sandbox.files.write([
+    { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
+    { path: paths.environment, data: environment },
+    { path: paths.argv, data: argv },
+  ], signalOpts(spec.signal))
+  await sandbox.commands.run(
+    `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)}`,
+    signalOpts(spec.signal),
+  )
+
+  const output = new PassThrough()
+  let handle: CommandHandle | undefined
+  let completion: Promise<CommandResult> | undefined
+  try {
+    handle = await sandbox.pty.create({
+      rows: spec.rows,
+      cols: spec.cols,
+      cwd: spec.cwd,
+      envs: { TERM: 'dumb' },
+      timeoutMs: 0,
+      ...signalOpts(spec.signal),
+      onData: (data) => { if (!output.destroyed) output.write(Buffer.from(data)) },
+    })
+    completion = handle.wait()
+    void completion.catch(() => {})
+    if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
+      throw new Error(`subprocess-e2b: E2B returned invalid terminal pid ${handle.pid}`)
+    }
+    const command = `exec /bin/bash ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(stateDir)}\r`
+    await sandbox.pty.sendInput(handle.pid, Buffer.from(command), signalOpts(spec.signal))
+    await waitUntilReady(sandbox, paths, completion, spec.signal)
+    const sessionId = await terminalSessionId(sandbox, handle.pid, spec.signal)
+    return new E2BTerminalHandle(
+      sandbox,
+      handle,
+      output,
+      completion,
+      sessionId,
+      stateDir,
+      spec.graceMs,
+      spec.signal,
+    )
+  } catch (error: unknown) {
+    output.destroy()
+    if (handle !== undefined) await handle.kill().catch(() => false)
+    if (completion !== undefined) await completion.catch(() => {})
+    await sandbox.files.remove(stateDir).catch(() => {})
+    throw error
+  }
+}
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
new file mode 100644
index 0000000000..9022e3d213
--- /dev/null
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -0,0 +1,541 @@
+import { Buffer } from 'node:buffer'
+import { once } from 'node:events'
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import {
+  CommandExitError,
+  FileNotFoundError,
+  type CommandHandle,
+  type CommandResult,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import type { SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import { spawnE2BTerminal } from '../src/terminal.ts'
+
+function commandError(exitCode: number): CommandExitError {
+  return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
+}
+
+class FakeTerminalCommandHandle {
+  pid = 123
+  disconnects = 0
+  sdkKills = 0
+  disconnectError: unknown
+  sdkKillError: unknown
+  private readonly result = Promise.withResolvers<CommandResult>()
+  private settled = false
+
+  wait(): Promise<CommandResult> {
+    return this.result.promise
+  }
+
+  async disconnect(): Promise<void> {
+    this.disconnects += 1
+    if (this.disconnectError !== undefined) throw this.disconnectError
+  }
+
+  async kill(): Promise<boolean> {
+    this.sdkKills += 1
+    if (this.sdkKillError !== undefined) {
+      const error = this.sdkKillError
+      this.fail(137)
+      throw error
+    }
+    this.fail(137)
+    return true
+  }
+
+  succeed(exitCode = 0): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.resolve({ exitCode, stdout: '', stderr: '' })
+  }
+
+  fail(exitCode: number): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(commandError(exitCode))
+  }
+
+  crash(error: unknown): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(error)
+  }
+
+  asHandle(): CommandHandle {
+    return this as unknown as CommandHandle
+  }
+}
+
+class FakeTerminalSandbox {
+  readonly handle = new FakeTerminalCommandHandle()
+  readonly commands: string[] = []
+  readonly inputs: Array<{ pid: number; data: Buffer }> = []
+  readonly removed: string[] = []
+  readonly directories: string[] = []
+  readonly writes = new Map<string, string>()
+  createOptions: Parameters<Sandbox['pty']['create']>[0] | undefined
+  ambient = 'KEEP=visible\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  ready: string | Error = 'ready\n'
+  sessionId = '123\n'
+  foreground = '456\n'
+  groups = [123]
+  createError: unknown
+  sendError: unknown
+  commandFailure: unknown
+  foregroundFailure: unknown
+  termFailure: unknown
+  removeError: unknown
+  clearOnTerm = true
+  clearOnKill = true
+  settleOnPtyKill = true
+  ptyKills = 0
+  resolvedExecutable = '/usr/bin/node\n'
+
+  readonly sandbox = {
+    files: {
+      makeDir: async (path: string): Promise<boolean> => {
+        this.directories.push(path)
+        return true
+      },
+      write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
+        for (const file of files) this.writes.set(file.path, file.data)
+        return files.map(() => ({}))
+      },
+      read: async (): Promise<string> => {
+        if (this.ready instanceof Error) throw this.ready
+        return this.ready
+      },
+      remove: async (path: string): Promise<void> => {
+        this.removed.push(path)
+        if (this.removeError !== undefined) throw this.removeError
+      },
+    },
+    commands: {
+      run: async (command: string, options?: { signal?: AbortSignal }): Promise<CommandResult> => {
+        this.commands.push(command)
+        options?.signal?.throwIfAborted()
+        if (this.commandFailure !== undefined) {
+          const error = this.commandFailure
+          this.commandFailure = undefined
+          throw error
+        }
+        if (command === 'env -0') return { exitCode: 0, stdout: this.ambient, stderr: '' }
+        if (command.includes('command -v -- ')) {
+          return { exitCode: 0, stdout: this.resolvedExecutable, stderr: '' }
+        }
+        if (command.startsWith('ps -o sid=')) return { exitCode: 0, stdout: this.sessionId, stderr: '' }
+        if (command.startsWith('ps -o tpgid=')) {
+          if (this.foregroundFailure !== undefined) throw this.foregroundFailure
+          return { exitCode: 0, stdout: this.foreground, stderr: '' }
+        }
+        if (command.startsWith('ps -eo sid=')) {
+          return { exitCode: 0, stdout: this.groups.map(group => `${group}\n`).join(''), stderr: '' }
+        }
+        if (command.startsWith('kill -TERM -- ')) {
+          if (this.termFailure !== undefined) throw this.termFailure
+          if (this.clearOnTerm) {
+            this.groups = []
+            this.handle.fail(143)
+          }
+        }
+        if (command.startsWith('kill -KILL -- ') && this.clearOnKill) this.groups = []
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+    pty: {
+      create: async (options: Parameters<Sandbox['pty']['create']>[0]): Promise<CommandHandle> => {
+        this.createOptions = options
+        if (this.createError !== undefined) throw this.createError
+        await options.onData(Buffer.from('buffered banner\n'))
+        return this.handle.asHandle()
+      },
+      sendInput: async (pid: number, data: Uint8Array, options?: { signal?: AbortSignal }): Promise<void> => {
+        options?.signal?.throwIfAborted()
+        this.inputs.push({ pid, data: Buffer.from(data) })
+        if (this.sendError !== undefined) throw this.sendError
+      },
+      kill: async (pid: number): Promise<boolean> => {
+        this.ptyKills += 1
+        if (this.settleOnPtyKill) this.handle.fail(137)
+        return pid === this.handle.pid
+      },
+    },
+  } as unknown as Sandbox
+}
+
+function runtime(fake: FakeTerminalSandbox): E2BSandboxService {
+  return {
+    cwd: '/workspace',
+    runtimeRoot: '/workspace/.dsh-e2b',
+    disposeMode: 'kill',
+    getSandbox: async () => fake.sandbox,
+  } as unknown as E2BSandboxService
+}
+
+function spec(overrides: Partial<SubprocessTerminalSpawnSpec> = {}): SubprocessTerminalSpawnSpec {
+  return {
+    argv: ['/bin/bash', '--noprofile', '--norc'],
+    cwd: '/workspace',
+    rows: 24,
+    cols: 80,
+    graceMs: 5,
+    env: { TERM: 'dumb', DSH_SESSION_ID: 'owner', TOKEN_EXPLICIT: 'kept' },
+    ...overrides,
+  }
+}
+
+describe('E2B terminal allocation', () => {
+  it('boots the requested argv through a private runner and preserves buffered bytes', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/terminal-one')
+    let output = ''
+    terminal.output.on('data', (chunk) => { output += String(chunk) })
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(output).toBe('buffered banner\n')
+    expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0, envs: { TERM: 'dumb' } })
+    expect(fake.inputs[0]?.data.toString()).toContain("exec /bin/bash '/runtime/terminal-one/runner.bash'")
+    expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('KEEP=visible\0')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('TOKEN_EXPLICIT=kept\0')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('secret')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('DSH_STALE')
+    expect(fake.writes.get('/runtime/terminal-one/argv')).toBe('/bin/bash\0--noprofile\0--norc\0')
+    const runner = fake.writes.get('/runtime/terminal-one/runner.bash') ?? ''
+    expect(runner).toContain('if (( ${#dsh_argv[@]} == 0 )); then')
+    expect(runner).toContain('exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"')
+    expect(runner).not.toContain('\u007f')
+
+    await terminal.write(Buffer.from('echo ok\r'))
+    expect(fake.inputs.at(-1)?.data.toString()).toBe('echo ok\r')
+    await expect(terminal.inspectForeground()).resolves.toEqual({ processGroupId: 456, inputWaiting: false })
+    await expect(terminal.signalForeground('SIGINT')).resolves.toBe(456)
+    expect(fake.commands).toContain('kill -INT -- -456')
+
+    terminal.terminate()
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+    expect(fake.handle.disconnects).toBe(1)
+    expect(fake.removed).toContain('/runtime/terminal-one')
+  })
+
+  it('inherits only safe ambient values and binds live abort to terminal cleanup', async () => {
+    const fake = new FakeTerminalSandbox()
+    const controller = new AbortController()
+    const terminal = await spawnE2BTerminal(
+      runtime(fake),
+      spec({ env: undefined, signal: controller.signal }),
+      '/runtime/abort-live',
+    )
+    const environment = fake.writes.get('/runtime/abort-live/environment') ?? ''
+    expect(environment).toContain('KEEP=visible\0')
+    expect(environment).not.toContain('secret')
+    expect(environment).not.toContain('DSH_STALE')
+
+    controller.abort(new Error('stop'))
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await expect(terminal.waitForExit(controller.signal)).resolves.toBe(false)
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('rejects malformed environment and argv values before PTY allocation', async () => {
+    const invalidName = new FakeTerminalSandbox()
+    await expect(spawnE2BTerminal(runtime(invalidName), spec({ env: { 'BAD=NAME': 'x' } }), '/runtime/name'))
+      .rejects.toThrow('environment entries')
+    expect(invalidName.createOptions).toBeUndefined()
+
+    const invalidValue = new FakeTerminalSandbox()
+    await expect(spawnE2BTerminal(runtime(invalidValue), spec({ env: { BAD: 'x\0y' } }), '/runtime/value'))
+      .rejects.toThrow('environment entries')
+
+    const invalidArg = new FakeTerminalSandbox()
+    await expect(spawnE2BTerminal(runtime(invalidArg), spec({ argv: ['/bin/bash', 'x\0y'] }), '/runtime/argv'))
+      .rejects.toThrow('argv must not contain NUL')
+  })
+
+  it('cleans malformed handles, bootstrap failures, and readiness failures', async () => {
+    const invalidPid = new FakeTerminalSandbox()
+    invalidPid.handle.pid = 0
+    await expect(spawnE2BTerminal(runtime(invalidPid), spec(), '/runtime/invalid-pid'))
+      .rejects.toThrow('invalid terminal pid 0')
+    expect(invalidPid.handle.sdkKills).toBe(1)
+    expect(invalidPid.removed).toContain('/runtime/invalid-pid')
+
+    const failedInput = new FakeTerminalSandbox()
+    failedInput.sendError = new Error('bootstrap failed')
+    await expect(spawnE2BTerminal(runtime(failedInput), spec(), '/runtime/input'))
+      .rejects.toThrow('bootstrap failed')
+    expect(failedInput.handle.sdkKills).toBe(1)
+
+    const exited = new FakeTerminalSandbox()
+    exited.ready = new FileNotFoundError('not ready')
+    queueMicrotask(() => { exited.handle.succeed(0) })
+    await expect(spawnE2BTerminal(runtime(exited), spec(), '/runtime/exited'))
+      .rejects.toThrow('exited before publishing readiness')
+
+    const invalidSession = new FakeTerminalSandbox()
+    invalidSession.sessionId = 'not-a-session\n'
+    await expect(spawnE2BTerminal(runtime(invalidSession), spec(), '/runtime/session'))
+      .rejects.toThrow('cannot resolve process session')
+    expect(invalidSession.handle.sdkKills).toBe(1)
+
+    const cleanupFailed = new FakeTerminalSandbox()
+    cleanupFailed.handle.pid = 0
+    cleanupFailed.handle.sdkKillError = new Error('kill transport failed')
+    cleanupFailed.removeError = new Error('remove transport failed')
+    await expect(spawnE2BTerminal(runtime(cleanupFailed), spec(), '/runtime/cleanup-failed'))
+      .rejects.toThrow('invalid terminal pid 0')
+  })
+
+  it('propagates setup cancellation and provider failures', async () => {
+    const aborted = new FakeTerminalSandbox()
+    await expect(spawnE2BTerminal(runtime(aborted), spec({ signal: AbortSignal.abort(new Error('stop')) }), '/runtime/abort'))
+      .rejects.toThrow('stop')
+
+    const createFailed = new FakeTerminalSandbox()
+    createFailed.createError = new Error('create failed')
+    await expect(spawnE2BTerminal(runtime(createFailed), spec(), '/runtime/create'))
+      .rejects.toThrow('create failed')
+
+    const readFailed = new FakeTerminalSandbox()
+    readFailed.ready = new Error('ready transport failed')
+    await expect(spawnE2BTerminal(runtime(readFailed), spec(), '/runtime/read'))
+      .rejects.toThrow('ready transport failed')
+  })
+})
+
+describe('E2B terminal lifecycle', () => {
+  it('maps ordinary exits, closes output, and reports an absent foreground after exit', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/natural')
+    terminal.output.resume()
+    const ended = once(terminal.output, 'end')
+    fake.handle.succeed(7)
+    await expect(terminal.done).resolves.toEqual({ exitCode: 7, signal: null })
+    await ended
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await expect(terminal.write(Buffer.from('late'))).rejects.toThrow('exited')
+    fake.foregroundFailure = commandError(1)
+    await expect(terminal.inspectForeground()).resolves.toBeUndefined()
+  })
+
+  it.each([
+    [7, { exitCode: 7, signal: null }],
+    [143, { exitCode: null, signal: 'SIGTERM' }],
+    [255, { exitCode: 255, signal: null }],
+  ] as const)('classifies an unrequested command exit %i', async (exitCode, expected) => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), `/runtime/exit-${exitCode}`)
+    fake.handle.fail(exitCode)
+    await expect(terminal.done).resolves.toEqual(expected)
+    await expect(terminal.waitForExit(new AbortController().signal)).resolves.toBe(true)
+  })
+
+  it('lets an early quiescence observer follow a transport rejection', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/early-observer')
+    terminal.output.on('error', () => {})
+    const quiescence = terminal.waitForExit()
+    fake.handle.crash(new Error('transport failed'))
+    await expect(terminal.done).rejects.toThrow('transport failed')
+    await expect(quiescence).resolves.toBe(true)
+  })
+
+  it('rejects killing the terminal shell and propagates live foreground failures', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.foreground = '123\n'
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/signal')
+    await expect(terminal.signalForeground('SIGKILL')).rejects.toThrow('refusing to SIGKILL')
+    fake.foreground = 'invalid\n'
+    await expect(terminal.inspectForeground()).rejects.toThrow('cannot resolve foreground')
+    fake.foregroundFailure = commandError(1)
+    await expect(terminal.inspectForeground()).rejects.toBeInstanceOf(CommandExitError)
+    fake.clearOnTerm = true
+    terminal.terminate()
+    await terminal.waitForExit()
+  })
+
+  it('escalates surviving process groups and bounds an observing wait', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = [123, 456]
+    fake.clearOnTerm = false
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/escalate')
+    const controller = new AbortController()
+    const observing = terminal.waitForExit(controller.signal)
+    controller.abort()
+    await expect(observing).resolves.toBe(false)
+
+    terminal.terminate()
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+    expect(fake.commands).toContain('kill -TERM -- -123 -456')
+    expect(fake.commands).toContain('kill -KILL -- -123 -456')
+  })
+
+  it('surfaces cleanup failures and allows a later retry', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = [1]
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry')
+    terminal.terminate()
+    await expect(terminal.waitForExit(new AbortController().signal)).rejects.toThrow('unsafe process group 1')
+
+    fake.groups = []
+    fake.handle.succeed(0)
+    await terminal.done
+    terminal.terminate()
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('propagates a process-group signalling transport failure before retry', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.termFailure = new Error('signal transport failed')
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/signal-failure')
+    terminal.terminate()
+    await expect(terminal.waitForExit()).rejects.toThrow('signal transport failed')
+
+    fake.groups = []
+    fake.handle.succeed(0)
+    await terminal.done
+    terminal.terminate()
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('keeps command rejection authoritative while cleanup is already waiting', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.removeError = new Error('private state already gone')
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/reject-during-cleanup')
+    terminal.output.on('error', () => {})
+    terminal.terminate()
+    await Promise.resolve()
+    fake.handle.crash(new Error('command transport failed'))
+    await expect(terminal.done).rejects.toThrow('command transport failed')
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('keeps a late command rejection authoritative after PTY kill', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.settleOnPtyKill = false
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
+    terminal.output.on('error', () => {})
+    terminal.terminate()
+    while (fake.ptyKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
+    await Promise.resolve()
+    fake.handle.crash(new Error('late command transport failed'))
+    await expect(terminal.done).rejects.toThrow('late command transport failed')
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('reports surviving groups, a surviving top-level pid, and transport failure', async () => {
+    const survivor = new FakeTerminalSandbox()
+    survivor.clearOnTerm = false
+    survivor.clearOnKill = false
+    const terminal = await spawnE2BTerminal(runtime(survivor), spec({ graceMs: 1 }), '/runtime/survivor')
+    terminal.terminate()
+    await expect(terminal.waitForExit()).rejects.toThrow('surviving process groups: 123')
+
+    const livePid = new FakeTerminalSandbox()
+    livePid.groups = []
+    livePid.settleOnPtyKill = false
+    const live = await spawnE2BTerminal(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
+    live.terminate()
+    await expect(live.waitForExit()).rejects.toThrow('surviving pid: 123')
+    livePid.handle.succeed(0)
+    await live.done
+
+    const crashed = new FakeTerminalSandbox()
+    crashed.groups = []
+    const failed = await spawnE2BTerminal(runtime(crashed), spec(), '/runtime/crashed')
+    const outputError = once(failed.output, 'error')
+    crashed.handle.crash('transport gone')
+    await expect(failed.done).rejects.toEqual('transport gone')
+    await expect(outputError).resolves.toMatchObject([{ message: 'transport gone' }])
+    await expect(failed.waitForExit()).resolves.toBe(true)
+  })
+})
+
+describe('E2B subprocess terminal service', () => {
+  async function service(fake = new FakeTerminalSandbox()): Promise<{
+    ctx: Context
+    fiber: Awaited<ReturnType<Context['plugin']>>
+    fake: FakeTerminalSandbox
+  }> {
+    const ctx = new Context()
+    ctx.provide('e2b', runtime(fake))
+    const fiber = await ctx.plugin(E2BSubprocessService)
+    return { ctx, fiber, fake }
+  }
+
+  it('publishes execution-world coordinates and resolves remote executables', async () => {
+    const { ctx } = await service()
+    expect(ctx.subprocess.cwd).toBe('/workspace')
+    expect(ctx.subprocess.runtimeRoot).toBe('/workspace/.dsh-e2b')
+    await expect(ctx.subprocess.resolveExecutable('/bin/bash')).resolves.toBe('/bin/bash')
+    await expect(ctx.subprocess.resolveExecutable('node', { PATH: '/custom/bin' }, new AbortController().signal))
+      .resolves.toBe('/usr/bin/node')
+    expect((ctx.e2b)).toBeDefined()
+  })
+
+  it('rejects invalid executable lookup inputs and results', async () => {
+    const { ctx, fake } = await service()
+    await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('non-empty')
+    await expect(ctx.subprocess.resolveExecutable('node', undefined, AbortSignal.abort(new Error('stop'))))
+      .rejects.toThrow('stop')
+    fake.resolvedExecutable = 'relative/node\n'
+    await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')
+    fake.resolvedExecutable = '/one\n/two\n'
+    await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')
+  })
+
+  it('owns live terminals through service disposal', async () => {
+    const { ctx, fiber, fake } = await service()
+    const terminal = await ctx.subprocess.spawnTerminal(spec())
+    await fiber.dispose()
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
+  it('releases naturally settled terminals and validates terminal requests', async () => {
+    const { ctx, fiber, fake } = await service()
+    for (const request of [
+      spec({ argv: [] }),
+      spec({ rows: 0 }),
+      spec({ cols: 1.5 }),
+      spec({ graceMs: 0 }),
+      spec({ signal: AbortSignal.abort(new Error('cancelled')) }),
+    ]) {
+      await expect(ctx.subprocess.spawnTerminal(request)).rejects.toThrow()
+    }
+
+    fake.groups = []
+    const terminal = await ctx.subprocess.spawnTerminal(spec())
+    fake.handle.succeed(0)
+    await terminal.done
+    await terminal.waitForExit()
+    const signals = fake.commands.filter(command => command.startsWith('kill -')).length
+    await fiber.dispose()
+    expect(fake.commands.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
+  })
+
+  it('contains a failed automatic terminal release until service disposal retries it', async () => {
+    const { fiber, fake } = await service()
+    fake.clearOnTerm = false
+    fake.clearOnKill = false
+    const terminal = await (fiber.ctx).subprocess.spawnTerminal(spec({ graceMs: 1 }))
+    fake.handle.succeed(0)
+    await terminal.done
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(fake.commands).toContain('kill -KILL -- -123')
+
+    fake.groups = []
+    await fiber.dispose()
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+})
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index 6b5a5d8b76..ae44721735 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: 0b9a244d0c42542909460edf7109dfb9cee34503
-README.zh.md: 77da9b73f866fd88fcb81b28cbb622b0389bf5f0
+README.md: 96bbe6c95bd2aca7e66cf2d57abb3f056cd19390
+README.zh.md: 7f091b4f0955b847d21b8b3423dab421e610cda3
diff --git a/packages/lsp/lsp-local/tests/fixture-server.ts b/packages/lsp/lsp-local/tests/fixture-server.ts
index 89053894ee..9399b5a1a7 100644
--- a/packages/lsp/lsp-local/tests/fixture-server.ts
+++ b/packages/lsp/lsp-local/tests/fixture-server.ts
@@ -15,7 +15,6 @@
  * - LSP_FAKE_REPLY_DELAY_MS: delays each textDocument/* response by this many milliseconds.
  * - LSP_FAKE_OPEN_MARKER: appends each didOpen document text as one JSON line to this path.
  * - LSP_FAKE_INITIALIZED_MARKER: records when the initialized notification is received.
- * - LSP_FAKE_EXPECT_PROCESS_ID: expected JSON `initialize.processId`; mismatch exits nonzero.
  * - LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED: "1" stops consuming stdin after initialized.
  * - LSP_FAKE_EXIT_DELAY_MS / LSP_FAKE_EXIT_MARKER: delay protocol exit and record exit/termination.
  * - LSP_FAKE_NO_SHUTDOWN: "1" ignores the shutdown request (forces kill escalation).
@@ -38,7 +37,6 @@ const exitAfterReply = process.env.LSP_FAKE_EXIT_AFTER_REPLY === '1'
 const replyDelayMs = Number(process.env.LSP_FAKE_REPLY_DELAY_MS ?? 0)
 const openMarker = process.env.LSP_FAKE_OPEN_MARKER
 const initializedMarker = process.env.LSP_FAKE_INITIALIZED_MARKER
-const expectedProcessId = process.env.LSP_FAKE_EXPECT_PROCESS_ID
 const pauseStdinAfterInitialized = process.env.LSP_FAKE_PAUSE_STDIN_AFTER_INITIALIZED === '1'
 const exitDelayMs = Number(process.env.LSP_FAKE_EXIT_DELAY_MS ?? 0)
 const exitMarker = process.env.LSP_FAKE_EXIT_MARKER
@@ -104,10 +102,6 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul
     return
   }
   if (method === 'initialize') {
-    if (expectedProcessId !== undefined) {
-      const params = message.params as { processId?: unknown } | undefined
-      if (JSON.stringify(params?.processId) !== expectedProcessId) process.exit(2)
-    }
     if (garbage) process.stdout.write('this is not a framed message\r\n')
     send({
       id,
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index fc1d05843c..22877a94c8 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -111,11 +111,6 @@ const RESPONDING_SERVER =
 const locJson = () => JSON.stringify({ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } })
 
 describe('LspInstance server-request handling', () => {
-  it('advertises a null process id across process namespaces', async () => {
-    const instance = makeInstance({ LSP_FAKE_EXPECT_PROCESS_ID: 'null', LSP_FAKE_DEF: 'null' }, { clientProcessId: null })
-    await expect(run(instance, 'goToDefinition')).resolves.toMatchObject({ kind: 'locations' })
-  })
-
   it('answers workspace/configuration with the static config per item', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'configuration', LSP_FAKE_DEF: locJson() })
     // The query drives didOpen, which makes the fake emit workspace/configuration; a healthy answer
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index b672a405de..e63252c7f8 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/README.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 packages/lsp/lsp/README.md
-README.md: bcffd460f192b0e6ac214ad0bc0d43da4c81d68c
-README.zh.md: e9df352e999834235a66ef7a500e300dadc2029c
+#   pnpm run verify-translation-pairing --write
+README.md: f96fc67ec8cb95f423eff9b312b7b591ec9d3008
+README.zh.md: 13ae9700e284ff238147538a571622066efc5747
diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md
index 4dc0436bbb..5c1044be50 100644
--- a/packages/lsp/lsp/README.md
+++ b/packages/lsp/lsp/README.md
@@ -10,7 +10,6 @@ This package is the interface third of the LSP capability:
 |---|---|
 | `@deepseek-ai/dsh-lsp` (this) | the interface: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
 | `@deepseek-ai/dsh-lsp-local` | a generic local backend that registers configured stdio language-server providers |
-| `@deepseek-ai/dsh-lsp-e2b` | a generic E2B backend that registers configured remote stdio providers |
 | `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool over `ctx.lsp` |
 
 The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`.
diff --git a/packages/lsp/lsp/README.zh.md b/packages/lsp/lsp/README.zh.md
index fdaedc9a96..cc412333e6 100644
--- a/packages/lsp/lsp/README.zh.md
+++ b/packages/lsp/lsp/README.zh.md
@@ -10,7 +10,6 @@
 |---|---|
 | `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
 | `@deepseek-ai/dsh-lsp-local` | 通用本地后端，注册已配置的 stdio 语言服务器提供方 |
-| `@deepseek-ai/dsh-lsp-e2b` | 通用 E2B 后端，注册已配置的远程 stdio 提供方 |
 | `@deepseek-ai/dsh-tool-lsp` | 面向模型的 `lsp` 工具，基于 `ctx.lsp` |
 
 该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且没有通用 JSON-RPC 逃生口，因此任何协议载荷或未经评审的命令／修改都无法通过 `ctx.lsp` 到达提供方。
diff --git a/packages/pty/pty/src/index.ts b/packages/pty/pty/src/index.ts
index 5cb375fbca..8ff4168e1a 100644
--- a/packages/pty/pty/src/index.ts
+++ b/packages/pty/pty/src/index.ts
@@ -41,15 +41,6 @@ export type {
   PtyWaitReason,
 } from './types.ts'
 export { PtyBackendCleanupError } from './types.ts'
-export {
-  normalizePtyTerminalText,
-  PTY_PROMPT_MARKER_PREFIX,
-  PtyTerminalSanitizer,
-  PtyTextBuffer,
-  ptySignalName,
-  ptyUtf8Tail,
-} from './terminal.ts'
-export type { PtySanitizedChunk } from './terminal.ts'
 
 /** Opaque identity minted by {@link PtyService} for one live PTY session. */
 export type PtySessionId = PtySessionIdValue
diff --git a/packages/pty/pty/src/terminal.ts b/packages/pty/pty/src/terminal.ts
deleted file mode 100644
index ed005dda41..0000000000
--- a/packages/pty/pty/src/terminal.ts
+++ /dev/null
@@ -1,273 +0,0 @@
-/** Backend-neutral line-oriented terminal buffering and control-sequence sanitization. */
-
-import { Buffer } from 'node:buffer'
-import { constants } from 'node:os'
-import type { PtySendRead } from './types.ts'
-
-/** OSC marker emitted by a controlled bash before each prompt. */
-export const PTY_PROMPT_MARKER_PREFIX = '133;D;'
-
-/** One sanitized chunk plus whether it contained the controlled prompt marker. */
-export interface PtySanitizedChunk {
-  /** Printable, line-normalized terminal text. */
-  text: string
-  /** Whether the chunk completed the controlled prompt marker. */
-  prompt: boolean
-  /** Present when printable text followed the latest controlled prompt marker. */
-  promptText?: true
-}
-
-/**
- * Return the largest code-point-aligned UTF-8 tail within a byte cap.
- * @param text - Candidate terminal text.
- * @param maxBytes - Maximum retained UTF-8 bytes.
- * @returns The retained tail and whether its head was dropped.
- */
-export function ptyUtf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
-  if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
-  const chars = Array.from(text)
-  let bytes = 0
-  let start = chars.length
-  while (start > 0) {
-    const next = Buffer.byteLength(chars[start - 1] as string)
-    if (bytes + next > maxBytes) break
-    bytes += next
-    start -= 1
-  }
-  return { text: chars.slice(start).join(''), truncated: true }
-}
-
-/** UTF-8 and optionally line-bounded terminal text buffer. */
-export class PtyTextBuffer {
-  private value = ''
-  private dropped = false
-
-  /**
-   * @param maxBytes - Maximum retained UTF-8 bytes.
-   * @param maxLines - Optional maximum retained logical lines.
-   */
-  constructor(
-    private readonly maxBytes: number,
-    private readonly maxLines?: number,
-  ) {}
-
-  /**
-   * Append terminal text and drop the oldest excess.
-   * @param text - Decoded and sanitized terminal text.
-   */
-  append(text: string): void {
-    if (text.length === 0) return
-    this.value += text
-    if (this.maxLines !== undefined) {
-      const lines = this.value.split('\n')
-      if (lines.length > this.maxLines) {
-        this.value = lines.slice(lines.length - this.maxLines).join('\n')
-        this.dropped = true
-      }
-    }
-    const tail = ptyUtf8Tail(this.value, this.maxBytes)
-    this.value = tail.text
-    this.dropped ||= tail.truncated
-  }
-
-  /**
-   * Consume all currently retained operation text.
-   * @returns The delta and whether older text was dropped.
-   */
-  consume(): PtySendRead {
-    const delta = this.value
-    const truncated = this.dropped
-    this.value = ''
-    this.dropped = false
-    return { delta, truncated }
-  }
-
-  /**
-   * Return the retained text without consuming it.
-   * @returns The retained text and whether its head was dropped.
-   */
-  snapshot(): { text: string; truncated: boolean } {
-    return { text: this.value, truncated: this.dropped }
-  }
-}
-
-/**
- * Streaming terminal-control sanitizer for line-oriented PTY backends.
- * Full terminal emulation is deliberately outside the PTY seam.
- */
-export class PtyTerminalSanitizer {
-  private pending = ''
-  private discardMode: 'osc' | 'csi' | undefined
-  private discardOscEscape = false
-  private trailingCarriageReturn = false
-  private awaitingPromptText = false
-
-  /** @param maxPendingBytes - Bound for an incomplete terminal-control sequence. */
-  constructor(private readonly maxPendingBytes: number) {}
-
-  /**
-   * Consume one decoded PTY data chunk.
-   * @param chunk - Decoded terminal data.
-   * @returns Printable text and prompt-marker facts.
-   */
-  push(chunk: string): PtySanitizedChunk {
-    this.pending += this.discardPrefix(chunk)
-    let text = ''
-    let prompt = false
-    let promptText = false
-    let index = 0
-    const appendText = (value: string): boolean => {
-      text += value
-      if (this.awaitingPromptText && value.replace(/[\r\n\x07]/g, '').length > 0) {
-        this.awaitingPromptText = false
-        return true
-      }
-      return false
-    }
-    while (index < this.pending.length) {
-      const escape = this.pending.indexOf('\x1b', index)
-      if (escape < 0) {
-        promptText = appendText(this.pending.slice(index)) || promptText
-        index = this.pending.length
-        break
-      }
-      promptText = appendText(this.pending.slice(index, escape)) || promptText
-      if (escape + 1 >= this.pending.length) {
-        index = escape
-        break
-      }
-      const kind = this.pending[escape + 1]
-      if (kind === ']') {
-        const bel = this.pending.indexOf('\x07', escape + 2)
-        const stringTerminator = this.pending.indexOf('\x1b\\', escape + 2)
-        let end = -1
-        if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2)
-        else if (bel >= 0) end = bel + 1
-        else if (stringTerminator >= 0) end = stringTerminator + 2
-        if (end < 0) {
-          index = escape
-          break
-        }
-        const terminatorBytes = this.pending[end - 1] === '\x07' ? 1 : 2
-        const content = this.pending.slice(escape + 2, end - terminatorBytes)
-        if (content.startsWith(PTY_PROMPT_MARKER_PREFIX)) {
-          prompt = true
-          promptText = false
-          this.awaitingPromptText = true
-        }
-        index = end
-        continue
-      }
-      if (kind === '[') {
-        let end = escape + 2
-        while (end < this.pending.length) {
-          const code = this.pending.charCodeAt(end)
-          if (code >= 0x40 && code <= 0x7e) break
-          end += 1
-        }
-        if (end >= this.pending.length) {
-          index = escape
-          break
-        }
-        index = end + 1
-        continue
-      }
-      index = escape + 2
-    }
-    this.pending = this.pending.slice(index)
-    this.enforcePendingBound()
-    return { text: this.normalizeText(text), prompt, ...promptText ? { promptText: true } : {} }
-  }
-
-  /**
-   * Flush printable trailing data and discard incomplete controls.
-   * @returns Remaining normalized printable text.
-   */
-  flush(): string {
-    const text = this.pending.startsWith('\x1b') ? '' : this.pending
-    this.pending = ''
-    this.discardMode = undefined
-    this.discardOscEscape = false
-    this.awaitingPromptText = false
-    const normalized = this.normalizeText(text)
-    if (!this.trailingCarriageReturn) return normalized
-    this.trailingCarriageReturn = false
-    return `${normalized}\n`
-  }
-
-  private normalizeText(text: string): string {
-    let complete = this.trailingCarriageReturn ? `\r${text}` : text
-    this.trailingCarriageReturn = false
-    if (complete.endsWith('\r')) {
-      complete = complete.slice(0, -1)
-      this.trailingCarriageReturn = true
-    }
-    return normalizePtyTerminalText(complete)
-  }
-
-  private enforcePendingBound(): void {
-    if (Buffer.byteLength(this.pending) <= this.maxPendingBytes) return
-    this.discardMode = this.pending[1] === ']' ? 'osc' : 'csi'
-    this.pending = ''
-  }
-
-  private discardPrefix(chunk: string): string {
-    if (this.discardMode === undefined) return chunk
-    if (this.discardMode === 'csi') {
-      for (let index = 0; index < chunk.length; index += 1) {
-        const code = chunk.charCodeAt(index)
-        if (code >= 0x40 && code <= 0x7e) {
-          this.discardMode = undefined
-          return chunk.slice(index + 1)
-        }
-      }
-      return ''
-    }
-
-    let index = 0
-    if (this.discardOscEscape) {
-      this.discardOscEscape = false
-      if (chunk.startsWith('\\')) {
-        this.discardMode = undefined
-        return chunk.slice(1)
-      }
-    }
-    while (index < chunk.length) {
-      if (chunk[index] === '\x07') {
-        this.discardMode = undefined
-        return chunk.slice(index + 1)
-      }
-      if (chunk[index] === '\x1b') {
-        if (chunk[index + 1] === '\\') {
-          this.discardMode = undefined
-          return chunk.slice(index + 2)
-        }
-        if (index + 1 === chunk.length) this.discardOscEscape = true
-      }
-      index += 1
-    }
-    return ''
-  }
-}
-
-/**
- * Normalize CRLF and standalone carriage returns for line-oriented rendering.
- * @param text - Sanitized terminal text.
- * @returns Line-normalized text with BEL removed.
- */
-export function normalizePtyTerminalText(text: string): string {
-  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n').replaceAll('\x07', '')
-}
-
-/**
- * Convert a platform signal number into the seam's signal-name vocabulary.
- * @param number - Platform signal number, zero, or an absent signal.
- * @returns The matching Node signal name, or `null` when unknown or absent.
- */
-export function ptySignalName(number: number | undefined): NodeJS.Signals | null {
-  if (number === undefined || number === 0) return null
-  for (const [name, value] of Object.entries(constants.signals)) {
-    if (value === number) return name as NodeJS.Signals
-  }
-  return null
-}
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 5ad70c0e68..6fda3901b6 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -47,7 +47,6 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
-  'packages/e2b/code-runtime-e2b': { kind: 'indirect', reason: 'The E2B backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
@@ -99,7 +98,6 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
-  'packages/e2b/lsp-e2b': { kind: 'indirect', reason: 'The E2B provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/lsp/lsp-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-lsp.' },
   'packages/subprocess/subprocess': { kind: 'indirect', reason: 'The seam delegates all model rendering to consumer seams such as the bash executor family.' },
   'packages/e2b/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 526d4ef4b8..101c810c91 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -166,12 +166,10 @@
     { "path": "./packages/e2b/subprocess-e2b" },
     { "path": "./packages/bash/bash" },
     { "path": "./packages/pty/pty" },
-    { "path": "./packages/e2b/pty-e2b" },
     { "path": "./packages/pty/pty-local" },
     { "path": "./packages/pty/tool-bash-persistent" },
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
-    { "path": "./packages/e2b/code-runtime-e2b" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
@@ -268,7 +266,6 @@
     { "path": "./packages/sdk/create-sdk" },
     { "path": "./packages/sdk/telemetry" },
     { "path": "./packages/lsp/lsp" },
-    { "path": "./packages/e2b/lsp-e2b" },
     { "path": "./packages/lsp/lsp-local" },
     { "path": "./packages/lsp/tool-lsp" },
     { "path": "./apps/cli" }

From 2188cb908c5f9e71efd7ad1333f3f46b8d4b44ae Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 03:32:29 +0800
Subject: [PATCH 362/516] refactor(e2b): delegate terminal lifecycle

---
 docs/cordis-catalog/services.md               |  4 +-
 packages/e2b/subprocess-e2b/src/terminal.ts   | 48 ++++-------------
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 53 ++++++++++++++++++-
 3 files changed, 63 insertions(+), 42 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 33f357d2bf..7ce45c6817 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -591,7 +591,7 @@ Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decisio
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:119`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:97`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
@@ -1180,7 +1180,7 @@ list(owner: Agent): PtySessionSnapshot[]
 
 Types: [Agent](../core-data-structures/core.md) · [PtyBackend](../core-data-structures/pty.md) · [PtyReadRequest](../core-data-structures/pty.md) · [PtyReadResult](../core-data-structures/pty.md) · [PtySendOperation](../core-data-structures/pty.md) · [PtySendRequest](../core-data-structures/pty.md) · [PtySessionId](../core-data-structures/pty.md) · [PtySessionSnapshot](../core-data-structures/pty.md) · [PtySignal](../core-data-structures/pty.md) · [PtySignalResult](../core-data-structures/pty.md) · [PtySpawnRequest](../core-data-structures/pty.md) · [PtySpawnResult](../core-data-structures/pty.md)
 
-Source: [`packages/pty/pty/src/index.ts:114`](../../packages/pty/pty/src/index.ts)
+Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
 
 ## `ctx.sandbox` — `SandboxProvider` (abstract seam)
 
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 88bea44fde..1a916c0fd5 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -10,7 +10,7 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
+import { SENSITIVE_ENV_PATTERN, SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessOutcome,
   SubprocessTerminalForeground,
@@ -127,9 +127,8 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   readonly done: Promise<SubprocessOutcome>
 
   private topLevelExited = false
-  private termination: Promise<void> | undefined
+  private readonly lifecycle: SubprocessTerminalLifecycle
   private terminationSignal: NodeJS.Signals | null = null
-  private removeAbort: (() => void) | undefined
 
   constructor(
     private readonly sandbox: Sandbox,
@@ -143,13 +142,11 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   ) {
     this.pid = handle.pid
     this.done = this.waitForCommand()
-    void this.done.then(() => { this.terminate() }, () => { this.terminate() })
-    if (signal !== undefined) {
-      const onAbort = (): void => { this.terminate() }
-      signal.addEventListener('abort', onAbort, { once: true })
-      this.removeAbort = () => { signal.removeEventListener('abort', onAbort) }
-      if (signal.aborted) this.terminate()
-    }
+    this.lifecycle = new SubprocessTerminalLifecycle({
+      done: this.done,
+      cleanup: () => this.closeOnce(),
+      signal,
+    })
   }
 
   /** @inheritdoc */
@@ -192,36 +189,12 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    this.termination ??= this.closeOnce().catch((error: unknown) => {
-      this.termination = undefined
-      throw error
-    })
-    void this.termination.catch(() => {})
+    this.lifecycle.terminate()
   }
 
   /** @inheritdoc */
   async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    const quiescence = this.termination ?? this.done.then(
-      () => { this.terminate(); return this.termination },
-      () => { this.terminate(); return this.termination },
-    )
-    if (signal === undefined) {
-      await quiescence
-      return true
-    }
-    if (signal.aborted) return false
-    return await new Promise<boolean>((resolve, reject) => {
-      const onAbort = (): void => { cleanup(); resolve(false) }
-      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
-      signal.addEventListener('abort', onAbort, { once: true })
-      void quiescence.then(
-        () => { cleanup(); resolve(true) },
-        (error: unknown) => {
-          cleanup()
-          reject(error instanceof Error ? error : new Error(String(error)))
-        },
-      )
-    })
+    return await this.lifecycle.waitForExit(signal)
   }
 
   private async waitForCommand(): Promise<SubprocessOutcome> {
@@ -261,7 +234,6 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private async signalGroups(groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
-    if (groups.length === 0) return
     try {
       await this.sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
     } catch (error: unknown) {
@@ -301,8 +273,6 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     if (!this.topLevelExited) {
       throw new Error(`subprocess-e2b: terminal cleanup failed; surviving pid: ${this.pid}`)
     }
-    this.removeAbort?.()
-    this.removeAbort = undefined
     await this.handle.disconnect()
     await this.sandbox.files.remove(this.stateDir).catch(() => {})
   }
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 9022e3d213..43cb88ea87 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -1,5 +1,6 @@
 import { Buffer } from 'node:buffer'
 import { once } from 'node:events'
+import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import {
@@ -12,7 +13,7 @@ import {
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
 import type { SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-import { spawnE2BTerminal } from '../src/terminal.ts'
+import { E2BTerminalHandle, spawnE2BTerminal } from '../src/terminal.ts'
 
 function commandError(exitCode: number): CommandExitError {
   return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
@@ -80,6 +81,7 @@ class FakeTerminalSandbox {
   createOptions: Parameters<Sandbox['pty']['create']>[0] | undefined
   ambient = 'KEEP=visible\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   ready: string | Error = 'ready\n'
+  readyMisses = 0
   sessionId = '123\n'
   foreground = '456\n'
   groups = [123]
@@ -106,6 +108,10 @@ class FakeTerminalSandbox {
         return files.map(() => ({}))
       },
       read: async (): Promise<string> => {
+        if (this.readyMisses > 0) {
+          this.readyMisses -= 1
+          throw new FileNotFoundError('not ready')
+        }
         if (this.ready instanceof Error) throw this.ready
         return this.ready
       },
@@ -191,6 +197,7 @@ function spec(overrides: Partial<SubprocessTerminalSpawnSpec> = {}): SubprocessT
 describe('E2B terminal allocation', () => {
   it('boots the requested argv through a private runner and preserves buffered bytes', async () => {
     const fake = new FakeTerminalSandbox()
+    fake.readyMisses = 1
     const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/terminal-one')
     let output = ''
     terminal.output.on('data', (chunk) => { output += String(chunk) })
@@ -281,6 +288,9 @@ describe('E2B terminal allocation', () => {
     await expect(spawnE2BTerminal(runtime(invalidSession), spec(), '/runtime/session'))
       .rejects.toThrow('cannot resolve process session')
     expect(invalidSession.handle.sdkKills).toBe(1)
+    const lateData = invalidSession.createOptions?.onData
+    if (lateData === undefined) throw new Error('missing captured terminal callback')
+    expect(lateData(Buffer.from('late bytes'))).toBeUndefined()
 
     const cleanupFailed = new FakeTerminalSandbox()
     cleanupFailed.handle.pid = 0
@@ -321,6 +331,26 @@ describe('E2B terminal lifecycle', () => {
     await expect(terminal.write(Buffer.from('late'))).rejects.toThrow('exited')
     fake.foregroundFailure = commandError(1)
     await expect(terminal.inspectForeground()).resolves.toBeUndefined()
+    await expect(terminal.signalForeground('SIGINT')).rejects.toThrow('cannot resolve foreground process group')
+  })
+
+  it('starts cleanup when the lifetime signal is already aborted at handle publication', async () => {
+    const fake = new FakeTerminalSandbox()
+    const controller = new AbortController()
+    controller.abort(new Error('publication cancelled'))
+    const terminal = new E2BTerminalHandle(
+      fake.sandbox,
+      fake.handle.asHandle(),
+      new PassThrough(),
+      fake.handle.wait(),
+      123,
+      '/runtime/pre-aborted',
+      1,
+      controller.signal,
+    )
+
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await expect(terminal.waitForExit()).resolves.toBe(true)
   })
 
   it.each([
@@ -404,6 +434,27 @@ describe('E2B terminal lifecycle', () => {
     await terminal.done
     terminal.terminate()
     await expect(terminal.waitForExit()).resolves.toBe(true)
+
+    const alreadyExited = new FakeTerminalSandbox()
+    alreadyExited.termFailure = commandError(1)
+    const tolerant = await spawnE2BTerminal(runtime(alreadyExited), spec({ graceMs: 1 }), '/runtime/group-exited')
+    tolerant.terminate()
+    await expect(tolerant.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    await expect(tolerant.waitForExit()).resolves.toBe(true)
+  })
+
+  it('normalizes a non-Error cleanup rejection for an observing wait', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/non-error-cleanup')
+    fake.commandFailure = 'cleanup transport gone'
+    terminal.terminate()
+    await expect(terminal.waitForExit(new AbortController().signal)).rejects.toThrow('cleanup transport gone')
+
+    fake.groups = []
+    fake.handle.succeed(0)
+    await terminal.done
+    terminal.terminate()
+    await expect(terminal.waitForExit()).resolves.toBe(true)
   })
 
   it('keeps command rejection authoritative while cleanup is already waiting', async () => {

From 8877f5d58239806d28173410275e50f9ea477384 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 03:55:03 +0800
Subject: [PATCH 363/516] fix(e2b): normalize relative executable paths

---
 packages/e2b/e2b/tests/composition.e2e.ts       |  5 ++++-
 packages/e2b/subprocess-e2b/src/index.ts        |  6 +++---
 .../e2b/subprocess-e2b/tests/terminal.spec.ts   | 17 ++++++++++++++---
 3 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 98fcdeae7f..e87627af8e 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -1,5 +1,5 @@
 import { access } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, posix } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
@@ -40,6 +40,9 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       } as never)
       const ptyFiber = await ctx.plugin(PtyService)
       const subprocessFiber = await ctx.plugin(E2BSubprocessService)
+      const node = await ctx.subprocess.resolveExecutable('node')
+      const relativeNodePath = posix.relative(ctx.subprocess.cwd, posix.dirname(node)) || '.'
+      await expect(ctx.subprocess.resolveExecutable('node', { PATH: relativeNodePath })).resolves.toBe(node)
       const ownerId = SessionId('e2b-pty-env-owner')
       const owner: Agent = {
         id: ownerId,
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 1547e1b46e..86ca5ceada 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -79,14 +79,14 @@ export class E2BSubprocessService extends SubprocessService {
     const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
     const result = await sandbox.commands.run(
       `${prefix}command -v -- ${quoteE2BShellArg(command)}`,
-      signalOpts(signal),
+      { cwd: this.cwd, ...signalOpts(signal) },
     )
     signal?.throwIfAborted()
     const executable = result.stdout.trim()
-    if (!posix.isAbsolute(executable) || executable.includes('\n')) {
+    if (executable.includes('\n') || (!posix.isAbsolute(executable) && !executable.includes('/'))) {
       throw new Error(`subprocess-e2b: executable ${JSON.stringify(command)} did not resolve to one absolute path`)
     }
-    return executable
+    return posix.resolve(this.cwd, executable)
   }
 
   /** @inheritdoc */
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 43cb88ea87..81716c3d52 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -19,6 +19,11 @@ function commandError(exitCode: number): CommandExitError {
   return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
 }
 
+interface CommandOptions {
+  signal?: AbortSignal
+  cwd?: string
+}
+
 class FakeTerminalCommandHandle {
   pid = 123
   disconnects = 0
@@ -74,6 +79,7 @@ class FakeTerminalCommandHandle {
 class FakeTerminalSandbox {
   readonly handle = new FakeTerminalCommandHandle()
   readonly commands: string[] = []
+  readonly commandOptions: CommandOptions[] = []
   readonly inputs: Array<{ pid: number; data: Buffer }> = []
   readonly removed: string[] = []
   readonly directories: string[] = []
@@ -121,8 +127,9 @@ class FakeTerminalSandbox {
       },
     },
     commands: {
-      run: async (command: string, options?: { signal?: AbortSignal }): Promise<CommandResult> => {
+      run: async (command: string, options?: CommandOptions): Promise<CommandResult> => {
         this.commands.push(command)
+        if (options !== undefined) this.commandOptions.push(options)
         options?.signal?.throwIfAborted()
         if (this.commandFailure !== undefined) {
           const error = this.commandFailure
@@ -525,12 +532,16 @@ describe('E2B subprocess terminal service', () => {
   }
 
   it('publishes execution-world coordinates and resolves remote executables', async () => {
-    const { ctx } = await service()
+    const { ctx, fake } = await service()
     expect(ctx.subprocess.cwd).toBe('/workspace')
     expect(ctx.subprocess.runtimeRoot).toBe('/workspace/.dsh-e2b')
     await expect(ctx.subprocess.resolveExecutable('/bin/bash')).resolves.toBe('/bin/bash')
     await expect(ctx.subprocess.resolveExecutable('node', { PATH: '/custom/bin' }, new AbortController().signal))
       .resolves.toBe('/usr/bin/node')
+    fake.resolvedExecutable = 'tools/bin/node\n'
+    await expect(ctx.subprocess.resolveExecutable('node', { PATH: 'tools/bin' }))
+      .resolves.toBe('/workspace/tools/bin/node')
+    expect(fake.commandOptions.at(-1)).toMatchObject({ cwd: '/workspace' })
     expect((ctx.e2b)).toBeDefined()
   })
 
@@ -539,7 +550,7 @@ describe('E2B subprocess terminal service', () => {
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('non-empty')
     await expect(ctx.subprocess.resolveExecutable('node', undefined, AbortSignal.abort(new Error('stop'))))
       .rejects.toThrow('stop')
-    fake.resolvedExecutable = 'relative/node\n'
+    fake.resolvedExecutable = 'node\n'
     await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')
     fake.resolvedExecutable = '/one\n/two\n'
     await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')

From fd78d9bc58cc324c38fe1ac8b882558da152edd9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 05:31:22 +0800
Subject: [PATCH 364/516] fix(e2b): harden remote process lifecycle

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |   6 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |   6 +-
 .../tests/fixtures/e2b/e2b/bin.ts             |  14 ++
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/index.ts                 |  26 ++-
 packages/e2b/e2b/tests/composition.e2e.ts     |  17 ++
 packages/e2b/e2b/tests/e2b.spec.ts            |  27 +++
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   9 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   9 +-
 packages/e2b/subprocess-e2b/src/output.ts     |  68 +++++-
 packages/e2b/subprocess-e2b/src/process.ts    | 137 ++++++++----
 packages/e2b/subprocess-e2b/src/terminal.ts   | 201 +++++++++++++-----
 .../subprocess-e2b/tests/subprocess.spec.ts   | 136 ++++++++++--
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  67 +++++-
 18 files changed, 586 insertions(+), 153 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index fc187ec47b..b5e8e6e47c 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: df0d6be97c502a9afe1a7aff3656a7567d302704
-2026-07-27-e2b-remote-runtime-poc.zh.md: 111d7aa63f8f7e51a82cfa0e42c489901f2b88e4
+2026-07-27-e2b-remote-runtime-poc.md: 029950cb2dae47bcf1ce819156135e58d46a4bb6
+2026-07-27-e2b-remote-runtime-poc.zh.md: 4029cc85d206e0dd0b7dbd91ec03674062df8531
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index df0d6be97c..029950cb2d 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -28,7 +28,7 @@ E2B owns the mutable filesystem, managed command and Bash processes, terminal al
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses UTF-8 JSON over command pipes; E2B's decoded callback transport is not an arbitrary binary channel.
+The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. For ordinary command pipes, its remote wrapper branches raw spill bytes before framing each live chunk as newline-delimited base64 ASCII; the host restores raw bytes across arbitrary decoded SDK callback boundaries. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
@@ -38,7 +38,7 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 Focused package suites pin owner lifecycle cleanup, filesystem paths/containment/bounded descriptor reads and commit metadata, subprocess executable lookup/process groups/publication rollback, terminal byte I/O/signal identity/default-environment scrubbing/session cleanup, output limits, abort ordering, disposal to quiescence, and package-owned invariant registrations. The generic PTY, LSP, and subprocess Code Runtime suites pin their provider-neutral readiness, cross-namespace `processId`, binding bridge, descriptor isolation, hostile traffic, and worker/descendant cleanup behavior.
 
-A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, bounded spill output, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
+A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, byte-split UTF-8 command output, bounded raw spill output, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
 ## Alternatives considered
 
@@ -62,4 +62,4 @@ A credential-gated Loader composition creates real E2B sandboxes and exercises F
 
 The three-package composition demonstrates that filesystem and subprocess are the sufficient provider seams for moving an agent's mutable coding world off-host without changing the loop, higher capability implementations, or model-facing tool packages. Fixes to Bash, PTY, LSP, and Code Runtime remain provider-neutral. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
 
-The adapters are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains complete command output in SDK memory, command callbacks are text-decoded rather than arbitrary binary streams, exact terminal stdin-wait inspection is unavailable, signal attribution is partly inferred, and reconnect cannot restore handles or protocol state. PTY uses E2B's byte API; Code Runtime uses validated ASCII/base64 framing; the exercised LSP path carries valid UTF-8 JSON. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or terminal session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
+The adapters are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains the complete base64 command transport in SDK memory, exact terminal stdin-wait inspection is unavailable, E2B supplies no independent signal fact, and reconnect cannot restore handles or protocol state. The adapter reports only its own requested TERM/KILL as signals and preserves every unrequested SDK exit as an exit code. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or terminal session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 111d7aa63f..4029cc85d2 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -28,7 +28,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用 UTF-8 JSON；E2B 的已解码回调传输并非任意二进制通道。
+基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。对于普通命令管道，其远程包装层会先分流原始 spill 字节，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意已解码 SDK 回调边界恢复原始字节。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
@@ -38,7 +38,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 聚焦包测试套件固定所有者生命周期清理、文件系统路径／containment／有界描述符读取与提交元数据、子进程可执行文件查找／进程组／发布回滚、终端字节 I/O／信号身份／默认环境清理／会话清理、输出上限、中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。通用 PTY、LSP 与子进程 Code Runtime 测试套件固定其提供方无关的就绪判定、跨命名空间 `processId`、绑定桥接、描述符隔离、恶意通信，以及 worker／后代进程清理行为。
 
-凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、有界 spill 输出、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
+凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 输出、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
@@ -62,4 +62,4 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 这个由 3 个包组成的组合证明，文件系统与进程管理这两个提供方 seam 足以把 agent 的可变 coding 环境移出宿主，而无需改变循环、上层功能实现或面向模型的工具包。Bash、PTY、LSP 与 Code Runtime 的修复仍与提供方无关。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
 
-这些适配器并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整命令输出，命令回调传递的是已解码文本而非任意二进制流，无法精确检查终端 stdin 等待状态，信号归因部分依靠推断，重新连接也无法恢复句柄或协议状态。PTY 使用 E2B 的字节 API；Code Runtime 使用经过验证的 ASCII/base64 分帧；已演练的 LSP 路径承载有效的 UTF-8 JSON。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或终端会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
+这些适配器并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整的 base64 命令传输，无法精确检查终端 stdin 等待状态，E2B 不提供独立的信号事实，重新连接也无法恢复句柄或协议状态。适配器只会把自己请求的 TERM/KILL 报告为信号，其他未请求的 SDK 退出都保留为退出码。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或终端会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index aeb447b0e8..7c5fce5535 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -72,6 +72,19 @@ try {
   ].every(entry => environmentLines.has(entry))
   if (!explicitEnvironment) throw new Error(`E2B subprocess dropped an explicit environment entry: ${environmentText}`)
 
+  const splitUtf8Handle = ctx.subprocess.spawn({
+    argv: ['bash', '-c', "printf '\\344'; sleep 0.05; printf '\\275'; sleep 0.05; printf '\\240'; sleep 0.05; printf '\\345'; sleep 0.05; printf '\\245'; sleep 0.05; printf '\\275'"],
+    cwd: process.cwd(),
+    stdio: { stdin: 'ignore', stdout: { maxBytes: 32 }, stderr: { maxBytes: 4_096 } },
+    graceMs: 500,
+    env: {},
+  })
+  const splitUtf8Outcome = await splitUtf8Handle.done
+  const splitUtf8Output = splitUtf8Handle.collected.stdout?.readFrom(0).text
+  if (splitUtf8Outcome.exitCode !== 0 || splitUtf8Output !== '你好') {
+    throw new Error(`E2B subprocess corrupted split UTF-8 output: ${JSON.stringify({ splitUtf8Outcome, splitUtf8Output })}`)
+  }
+
   const remoteFiles = sandbox.files as unknown as {
     read(path: string, options?: unknown): Promise<unknown>
   }
@@ -370,6 +383,7 @@ try {
     bashRead: bashRead.stdout.text,
     fsRead,
     explicitEnvironment,
+    splitUtf8Output,
     publicationRollback,
     spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 8ffb6e981f..229a9e9343 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 00264b8f0b03e4af8512025322fe3e457e7b6b9b
-README.zh.md: 93fad661ded446e78e3addc0c8b2b8fdc39bd994
+README.md: 56606a22c36e65bcc53f2b8cce27f0739da1b8e2
+README.zh.md: 2e3213e431f15f1b22d2b8a429b27ab8a6a78671
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 00264b8f0b..56606a22c3 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -30,7 +30,7 @@ Set `sandboxId` to reconnect a running or paused sandbox instead of creating one
 
 Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, then sets that directory to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
 
-Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A newly created sandbox is killed when initial directory setup fails; a reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
+Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` means a kill-on-timeout sandbox is already quiescent; every other disposition failure rejects teardown. A newly created sandbox is killed when initial directory setup fails; a reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
 
 `pause` and `leave` retain remote filesystem and adapter artifacts for a later `sandboxId` connection, but a later harness process receives only a new SDK handle. The subprocess service still fulfills its seam contract by terminating managed groups before owner disposal; neither disposition recovers prior process objects, output cursors, or in-memory adapter locks.
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 93fad661de..2e3213e431 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -30,7 +30,7 @@
 
 构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
 
-资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。新建沙箱的初始目录设置失败时，服务会终止该沙箱；重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 表示因超时终止的沙箱已经完全停稳；其他处置失败都会使 teardown 拒绝。新建沙箱的初始目录设置失败时，服务会终止该沙箱；重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
 `pause` 和 `leave` 会保留远程文件系统及适配器产物，供稍后的 `sandboxId` 连接使用，但后续 harness 进程只会获得新的 SDK 句柄。进程管理服务仍会履行其 seam 契约，在所有者释放前终止受管进程组；这两种处置方式都不会恢复先前的进程对象、输出游标或内存中的适配器锁。
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 184c49f811..96da912033 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -7,7 +7,7 @@
 import { posix } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import { Sandbox } from 'e2b'
+import { Sandbox, SandboxNotFoundError } from 'e2b'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
 export {
@@ -159,16 +159,22 @@ export class E2BSandboxService extends Service {
         // there is no remote resource for teardown to own.
         return
       }
-      switch (this.config.onDispose) {
-        case 'kill':
-          await sandbox.kill()
-          return
-        case 'pause': {
-          await sandbox.pause()
-          return
+      try {
+        switch (this.config.onDispose) {
+          case 'kill':
+            await sandbox.kill()
+            return
+          case 'pause': {
+            await sandbox.pause()
+            return
+          }
+          case 'leave':
+            return
         }
-        case 'leave':
-          return
+      } catch (error: unknown) {
+        // A kill-on-timeout sandbox is already quiescent; every other disposal
+        // failure still reports that the configured final disposition is unknown.
+        if (!(error instanceof SandboxNotFoundError)) throw error
       }
     }, 'e2b sandbox teardown')
   }
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index e87627af8e..4e7be57c45 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -43,6 +43,22 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       const node = await ctx.subprocess.resolveExecutable('node')
       const relativeNodePath = posix.relative(ctx.subprocess.cwd, posix.dirname(node)) || '.'
       await expect(ctx.subprocess.resolveExecutable('node', { PATH: relativeNodePath })).resolves.toBe(node)
+      const environmentProbe = ctx.subprocess.spawn({
+        argv: ['/bin/bash', '-c', [
+          'dsh_leak=0',
+          'for dsh_pid in "$PPID" $(ps -o pid= --ppid "$PPID"); do',
+          '  [[ "$dsh_pid" == "$$" ]] && continue',
+          '  if tr "\\0" "\\n" < "/proc/$dsh_pid/environ" 2>/dev/null | grep -Fqx "NPM_TOKEN=sentinel-secret"; then dsh_leak=1; fi',
+          'done',
+          'printf "DIRECT=<%s> LEAK=<%s>\\n" "${NPM_TOKEN-}" "$dsh_leak"',
+        ].join('\n')],
+        cwd: '/home/user',
+        stdio: { stdin: 'ignore', stdout: { maxBytes: 1_024 }, stderr: { maxBytes: 1_024 } },
+        graceMs: 500,
+        env: {},
+      })
+      await expect(environmentProbe.done).resolves.toEqual({ exitCode: 0, signal: null })
+      expect(environmentProbe.collected.stdout?.readFrom(0).text).toBe('DIRECT=<> LEAK=<0>\n')
       const ownerId = SessionId('e2b-pty-env-owner')
       const owner: Agent = {
         id: ownerId,
@@ -106,6 +122,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       bashRead: 'written-by-fs\n',
       fsRead: 'written-by-bash\n',
       explicitEnvironment: true,
+      splitUtf8Output: '你好',
       publicationRollback: true,
       spill: {
         liveBytes: 6,
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index c0770f5917..bb96ca806a 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -3,6 +3,7 @@ import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
   E2BSandboxId,
+  SandboxNotFoundError,
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import * as E2BInvariant from '../src/invariant.ts'
@@ -140,6 +141,32 @@ describe('E2BSandboxService', () => {
     expect(fixture.pause).toHaveBeenCalledOnce()
   })
 
+  it('treats a timeout-killed sandbox as already quiescent during disposal', async () => {
+    const fixture = fakeSandbox()
+    fixture.pause.mockRejectedValue(new SandboxNotFoundError('sandbox expired'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, {
+      apiKey: 'test-key',
+      onTimeout: 'kill',
+      onDispose: 'pause',
+    })
+    await ctx.e2b.getSandbox()
+    await expect(fiber.dispose()).resolves.toBeUndefined()
+    expect(fixture.pause).toHaveBeenCalledOnce()
+  })
+
+  it('does not classify other disposal failures as an already-gone sandbox', async () => {
+    const fixture = fakeSandbox()
+    fixture.kill.mockRejectedValue(new Error('disposition unknown'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    await ctx.e2b.getSandbox()
+    await expect(fiber.dispose()).resolves.toBeUndefined()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+  })
+
   it('reconnects without applying creation lifecycle options and can leave state running', async () => {
     const fixture = fakeSandbox('existing')
     sdk.connect.mockResolvedValue(fixture.sandbox)
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index dca7b016c2..33a36141d0 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: e0805345e708c67c6de721d95641e2366a7f990e
-README.zh.md: f83969c794e50f0658aa86218a0f5f3c89d53b56
+README.md: 58f13b264324d2168d4bc264b60100cdafa0a366
+README.zh.md: d547e4e8d66f629edcef753651180fe1806ad9bf
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index e0805345e7..58f13b2643 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -10,10 +10,10 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. If publication fails, the SDK PID remains the provisional `exec setsid` group id; rollback kills and verifies that group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
-- **Stdio projection** — pipe mode forwards E2B callbacks into host Node streams; inherit mode forwards them to the harness process streams; collect mode retains a bounded host tail with offset reads. Optional complete spill files are written remotely and advertised only while within their cap. Batch and streaming stdin use the SDK handle.
+- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. Batch and streaming stdin use the SDK handle.
 - **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
-The base E2B image supplies the Bash/GNU utilities this adapter invokes: `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
+The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
 ## Model Experience
 
@@ -25,11 +25,10 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate even when this adapter exposes bounded tails, so the subprocess seam's normal host-memory bound is not achieved.
-- **Command-pipe output is text-decoded by the SDK** — valid UTF-8 protocol traffic, including the exercised LSP composition and Code Runtime's ASCII/base64 frames, is supported; arbitrary binary protocols and invalid UTF-8 are not byte-faithful.
+- **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate the base64 transport even when this adapter exposes bounded raw-byte tails, so the subprocess seam's normal host-memory bound is not achieved and transport retention is larger than the source stream.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
 - **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
-- **Signal attribution is inferred** — when termination was requested and E2B reports a nonzero exit code, the adapter reports the last requested signal because the SDK result does not identify the terminating signal.
+- **E2B exposes no signal fact** — only an adapter-requested `SIGTERM` or `SIGKILL` is reported as a signal; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
 - **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
 - **Linux utility and E2B transport semantics are assumed** — there is no Windows, arbitrary-template, escaped-session recovery, or network-partition fidelity layer.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index f83969c794..d547e4e8d6 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -10,10 +10,10 @@
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。如果发布失败，SDK PID 仍为临时的 `exec setsid` 进程组 ID；回滚会终止并验证该进程组，随后启动操作才会以拒绝结束。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
-- **stdio 投影**：pipe 模式把 E2B 回调转发到宿主 Node 流；inherit 模式把回调转发到 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。可选的完整 spill 文件写在远程，并且只有未超过其上限时才会对外公布。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 - **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
-基础 E2B 镜像提供该适配器调用的 Bash/GNU 工具：`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
+基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
 ## 模型体验
 
@@ -25,11 +25,10 @@
 
 ## 已知限制与延后工作
 
-- **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会持续累积，因此无法达到进程管理 seam 通常提供的宿主内存边界。
-- **命令管道输出由 SDK 解码为文本**：支持有效的 UTF-8 协议流量，包括已经过测试的 LSP 组合与 Code Runtime 的 ASCII/base64 帧；任意二进制协议和无效 UTF-8 不具备字节保真。
+- **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界原始字节尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会累积 base64 传输内容，因此无法达到进程管理 seam 通常提供的宿主内存边界，而且传输保留量大于源数据流。
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
 - **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
-- **信号归因依靠推断**：如果已经请求终止，而 E2B 报告非零退出码，适配器会报告最后请求的信号，因为 SDK 结果不标识终止信号。
+- **E2B 不公开信号事实**：只有适配器请求的 `SIGTERM` 或 `SIGKILL` 会报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
 - **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
 - **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、任意模板、逃逸会话恢复或网络分区的保真层。
diff --git a/packages/e2b/subprocess-e2b/src/output.ts b/packages/e2b/subprocess-e2b/src/output.ts
index b6551983a0..6cb61e4f09 100644
--- a/packages/e2b/subprocess-e2b/src/output.ts
+++ b/packages/e2b/subprocess-e2b/src/output.ts
@@ -3,6 +3,64 @@
 import { Buffer } from 'node:buffer'
 import type { SubprocessOutputRead, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess'
 
+const BASE64_TEXT = /^[A-Za-z0-9+/]+={0,2}$/u
+
+/** Reserved non-base64 frame proving that one remote encoder reached clean EOF. */
+export const E2B_OUTPUT_COMPLETE_FRAME = '!dsh-e2b-output-complete!'
+
+/** Incrementally decode newline-delimited base64 frames emitted by one remote encoder. */
+export class E2BBase64Decoder {
+  private pending = ''
+  private complete = false
+
+  /**
+   * Decode every complete newline-delimited frame in one arbitrarily split SDK callback.
+   * @param text - ASCII base64 frames from E2B's decoded callback.
+   * @returns the complete raw bytes made available by this callback.
+   */
+  push(text: string): Buffer {
+    if (text.length === 0) return Buffer.alloc(0)
+    this.pending += text
+    const decoded: Buffer[] = []
+    for (;;) {
+      const boundary = this.pending.indexOf('\n')
+      if (boundary < 0) break
+      const frame = this.pending.slice(0, boundary)
+      this.pending = this.pending.slice(boundary + 1)
+      if (frame === E2B_OUTPUT_COMPLETE_FRAME) {
+        if (this.complete) throw new Error('subprocess-e2b: duplicate output transport completion')
+        this.complete = true
+        continue
+      }
+      if (this.complete) throw new Error('subprocess-e2b: output transport continued after completion')
+      if (!BASE64_TEXT.test(frame)) {
+        throw new Error('subprocess-e2b: invalid base64 output transport')
+      }
+      const bytes = Buffer.from(frame, 'base64')
+      if (bytes.toString('base64') !== frame) {
+        throw new Error('subprocess-e2b: invalid base64 output transport')
+      }
+      decoded.push(bytes)
+    }
+    return Buffer.concat(decoded)
+  }
+
+  /**
+   * Validate clean encoder completion, or discard an interrupted trailing frame after requested termination.
+   * @param requireComplete - Whether natural completion requires the reserved EOF frame.
+   */
+  finish(requireComplete = true): void {
+    if (!requireComplete) {
+      this.pending = ''
+      return
+    }
+    if (this.pending.length > 0) {
+      throw new Error('subprocess-e2b: truncated base64 output transport')
+    }
+    if (!this.complete) throw new Error('subprocess-e2b: incomplete output transport')
+  }
+}
+
 /** Offset reader used for one collect-mode E2B stream. */
 export class E2BOutputReader implements SubprocessOutputReader {
   private chunks: Buffer[] = []
@@ -27,12 +85,12 @@ export class E2BOutputReader implements SubprocessOutputReader {
   }
 
   /**
-   * Append one decoded SDK output event.
-   * @param text - Event text delivered by E2B.
+   * Append one byte-faithful decoded transport event.
+   * @param bytes - Raw command bytes recovered from the ASCII SDK transport.
    */
-  push(text: string): void {
-    if (text.length === 0) return
-    const chunk = Buffer.from(text)
+  push(bytes: Uint8Array): void {
+    if (bytes.length === 0) return
+    const chunk = Buffer.from(bytes)
     this.totalBytes += chunk.length
     this.chunks.push(chunk)
     this.retainedBytes += chunk.length
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 3b9594a752..9eeee5d877 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -8,6 +8,7 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
+import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessCollect,
   SubprocessHandle,
@@ -16,9 +17,21 @@ import type {
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { E2BOutputReader } from './output.ts'
+import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
 
 const GROUP_POLL_MS = 20
+const OUTPUT_ENCODER_SOURCE = [
+  '(async () => {',
+  '  for await (const chunk of process.stdin) {',
+  "    if (!process.stdout.write(chunk.toString('base64') + '\\n')) {",
+  "      await new Promise(resolve => process.stdout.once('drain', resolve))",
+  '    }',
+  '  }',
+  `  if (!process.stdout.write(${JSON.stringify(E2B_OUTPUT_COMPLETE_FRAME)} + '\\n')) {`,
+  "    await new Promise(resolve => process.stdout.once('drain', resolve))",
+  '  }',
+  '})().catch(() => { process.exitCode = 1 })',
+].join('\n')
 
 function isCollect(mode: SubprocessOutputMode): mode is SubprocessCollect {
   return mode !== 'pipe' && mode !== 'inherit'
@@ -60,40 +73,65 @@ interface RemotePaths {
   stderr: string
 }
 
-function explicitEnvironment(env: Readonly<Record<string, string>> | undefined): string {
-  return Object.entries(env ?? {})
-    .map(([name, value]) => `${name}=${value}\0`)
-    .join('')
+function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
+  const environment = new Map<string, string>()
+  for (const entry of raw.split('\0')) {
+    if (entry.length === 0) continue
+    const separator = entry.indexOf('=')
+    if (separator <= 0) continue
+    const name = entry.slice(0, separator)
+    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
+    environment.set(name, entry.slice(separator + 1))
+  }
+  for (const [name, value] of Object.entries(explicit ?? {})) environment.set(name, value)
+  return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
 }
 
 function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
+  const encoder = `"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e ${quoteE2BShellArg(OUTPUT_ENCODER_SOURCE)}`
   const stdoutRedirect = hasSpill(spec.stdio.stdout)
-    ? `> >(tee --output-error=warn-nopipe >(head -c ${spec.stdio.stdout.spill.maxBytes} > ${quoteE2BShellArg(paths.stdout)}))`
-    : ''
+    ? `> >("$dsh_e2b_tee" --output-error=warn-nopipe >("$dsh_e2b_head" -c ${spec.stdio.stdout.spill.maxBytes} > ${quoteE2BShellArg(paths.stdout)}) | ${encoder} 2>/dev/null)`
+    : `> >(${encoder} 2>/dev/null)`
   const stderrRedirect = hasSpill(spec.stdio.stderr)
-    ? `2> >(tee --output-error=warn-nopipe >(head -c ${spec.stdio.stderr.spill.maxBytes} > ${quoteE2BShellArg(paths.stderr)}) >&2)`
-    : ''
+    ? `2> >("$dsh_e2b_tee" --output-error=warn-nopipe >("$dsh_e2b_head" -c ${spec.stdio.stderr.spill.maxBytes} > ${quoteE2BShellArg(paths.stderr)}) | ${encoder} >&2 2>/dev/null)`
+    : `2> >(${encoder} >&2 2>/dev/null)`
   const inner = [
     'set +e',
     'umask 077',
-    'dsh_e2b_pgid="$(ps -o pgid= -p "$$" | tr -d " ")"',
+    'dsh_e2b_env_bin=$1',
+    'dsh_e2b_node=$2',
+    'dsh_e2b_ps=$3',
+    'dsh_e2b_tr=$4',
+    'dsh_e2b_tee=$5',
+    'dsh_e2b_head=$6',
+    'shift 6',
+    'dsh_e2b_pgid="$("$dsh_e2b_ps" -o pgid= -p "$$" | "$dsh_e2b_tr" -d " ")"',
     `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
-    `mapfile -d '' -t dsh_e2b_explicit < ${quoteE2BShellArg(paths.environment)}`,
+    `mapfile -d '' -t dsh_e2b_env < ${quoteE2BShellArg(paths.environment)}`,
     `: > ${quoteE2BShellArg(paths.environment)}`,
-    'dsh_e2b_env=()',
-    "while IFS= read -r -d '' dsh_e2b_entry; do",
-    '  dsh_e2b_name="${dsh_e2b_entry%%=*}"',
-    '  case "${dsh_e2b_name^^}" in DSH_*|*KEY*|*SECRET*|*TOKEN*) continue ;; esac',
-    '  dsh_e2b_env+=("$dsh_e2b_entry")',
-    'done < <(env -0)',
-    `env -i "\${dsh_e2b_env[@]}" "\${dsh_e2b_explicit[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
+    `"$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
     'dsh_e2b_status=$?',
     'wait',
     `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
     'exit "$dsh_e2b_status"',
   ].join('\n')
   const argv = spec.argv.map(quoteE2BShellArg).join(' ')
-  return `exec setsid --wait -- bash -c ${quoteE2BShellArg(inner)} dsh-e2b ${argv}`
+  const bootstrap = [
+    `mapfile -d '' -t dsh_e2b_env < ${quoteE2BShellArg(paths.environment)}`,
+    'dsh_e2b_env_bin="$(command -v env)"',
+    'dsh_e2b_setsid="$(command -v setsid)"',
+    'dsh_e2b_bash="$(command -v bash)"',
+    'dsh_e2b_node="$(command -v node)"',
+    'dsh_e2b_ps="$(command -v ps)"',
+    'dsh_e2b_tr="$(command -v tr)"',
+    'dsh_e2b_tee="$(command -v tee)"',
+    'dsh_e2b_head="$(command -v head)"',
+    'for dsh_e2b_tool in "$dsh_e2b_env_bin" "$dsh_e2b_setsid" "$dsh_e2b_bash" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head"; do',
+    '  [[ "$dsh_e2b_tool" == /* && -x "$dsh_e2b_tool" ]] || exit 125',
+    'done',
+    `exec "$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" ${argv}`,
+  ].join('\n')
+  return bootstrap
 }
 
 function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
@@ -128,10 +166,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   readonly done: Promise<SubprocessOutcome>
 
   private readonly readyState = Promise.withResolvers<CommandHandle>()
+  private readonly stdoutDecoder = new E2BBase64Decoder()
+  private readonly stderrDecoder = new E2BBase64Decoder()
   private readonly stdoutReader: E2BOutputReader | undefined
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
   private remotePid = -1
+  private commandHandle: CommandHandle | undefined
+  private outputTransportError: Error | undefined
   private terminationRequested = false
   private terminationSignal: NodeJS.Signals | null = null
   private termination: Promise<void> | undefined
@@ -195,7 +237,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     try {
       handle = await this.readyForWait(signal)
     } catch {
-      return true
+      handle = this.commandHandle
+      if (handle === undefined) return true
     }
     if (handle === undefined) return false
     let sandbox: Sandbox
@@ -205,7 +248,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (isAborted(signal)) return false
       throw error
     }
-    while (await this.groupAlive(sandbox, this.remotePid, signal)) {
+    const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
+    while (await this.groupAlive(sandbox, processGroupId, signal)) {
       if (!await waitTick(signal)) return false
     }
     return !isAborted(signal)
@@ -248,6 +292,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
         throw new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
       }
+      this.commandHandle = handle
       const completion = handle.wait()
       void completion.catch(() => {})
       try {
@@ -266,6 +311,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       this.readyState.resolve(handle)
       await this.writeBatchStdin(handle)
       const outcome = await this.waitForCommand(completion)
+      if (this.outputTransportError !== undefined) throw this.outputTransportError
+      const requireCompleteOutput = this.terminationSignal === null
+      this.stdoutDecoder.finish(requireCompleteOutput)
+      this.stderrDecoder.finish(requireCompleteOutput)
       await this.finalizeSpills(sandbox)
       return outcome
     } catch (error: unknown) {
@@ -279,12 +328,13 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async prepareState(sandbox: Sandbox): Promise<void> {
+    const ambient = await sandbox.commands.run('env -0')
     await sandbox.files.makeDir(this.stateDir)
     await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`)
     const files = [
       { path: this.paths.pid, data: '' },
       { path: this.paths.status, data: '' },
-      { path: this.paths.environment, data: explicitEnvironment(this.spec.env) },
+      { path: this.paths.environment, data: remoteEnvironment(ambient.stdout, this.spec.env) },
       ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
       ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
     ]
@@ -303,25 +353,34 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async dispatchOutput(stream: 'stdout' | 'stderr', data: string): Promise<void> {
+    let bytes: Buffer
+    try {
+      bytes = stream === 'stdout' ? this.stdoutDecoder.push(data) : this.stderrDecoder.push(data)
+    } catch (error: unknown) {
+      this.outputTransportError ??= asError(error)
+      const target = stream === 'stdout' ? this.stdout : this.stderr
+      target?.destroy(this.outputTransportError)
+      return
+    }
     try {
       if (stream === 'stdout') {
-        this.stdoutReader?.push(data)
-        await this.writeOutput(this.stdout, this.spec.stdio.stdout === 'inherit' ? process.stdout : undefined, data)
+        this.stdoutReader?.push(bytes)
+        await this.writeOutput(this.stdout, this.spec.stdio.stdout === 'inherit' ? process.stdout : undefined, bytes)
         return
       }
-      this.stderrReader?.push(data)
-      await this.writeOutput(this.stderr, this.spec.stdio.stderr === 'inherit' ? process.stderr : undefined, data)
+      this.stderrReader?.push(bytes)
+      await this.writeOutput(this.stderr, this.spec.stdio.stderr === 'inherit' ? process.stderr : undefined, bytes)
     } catch (error: unknown) {
       const target = stream === 'stdout' ? this.stdout : this.stderr
       target?.destroy(asError(error))
     }
   }
 
-  private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: string): Promise<void> {
+  private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: Uint8Array): Promise<void> {
     const target = pipe ?? inherited
     if (target === undefined || data.length === 0) return
     if (target.destroyed) throw new Error('subprocess output stream is closed')
-    if (target.write(Buffer.from(data))) return
+    if (target.write(data)) return
     await new Promise<void>((resolve, reject) => {
       const onDrain = (): void => { cleanup(); resolve() }
       const onError = (error: Error): void => { cleanup(); reject(error) }
@@ -369,10 +428,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async rollbackUnpublishedGroup(sandbox: Sandbox, handle: CommandHandle): Promise<void> {
-    // The background command begins with `exec setsid`, so E2B's command PID is
-    // the provisional group id even before the private publication file can be
-    // trusted. Kill that group before the SDK-PID fallback, then prove no group
-    // member survived before rejecting startup.
+    // The bootstrap ends in an exec chain through the scrubbed environment and
+    // `setsid`, so E2B's command PID is the provisional group id even before the
+    // private publication file can be trusted. Kill that group before the SDK-PID
+    // fallback, then prove no group member survived before rejecting startup.
     try {
       await this.signalGroup(sandbox, handle.pid, 'KILL')
     } finally {
@@ -382,23 +441,25 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async terminateRemote(): Promise<void> {
-    let handle: CommandHandle
+    let handle: CommandHandle | undefined
     try {
       handle = await this.readyState.promise
     } catch {
-      return
+      handle = this.commandHandle
     }
+    if (handle === undefined) return
     const sandbox = await this.runtime.getSandbox()
+    const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
     this.terminationSignal = 'SIGTERM'
-    await this.signalGroup(sandbox, this.remotePid, 'TERM')
+    await this.signalGroup(sandbox, processGroupId, 'TERM')
     const deadline = Date.now() + this.spec.graceMs
-    while (Date.now() < deadline && await this.groupAlive(sandbox, this.remotePid)) {
+    while (Date.now() < deadline && await this.groupAlive(sandbox, processGroupId)) {
       await waitTick()
     }
-    if (!await this.groupAlive(sandbox, this.remotePid)) return
+    if (!await this.groupAlive(sandbox, processGroupId)) return
     this.terminationSignal = 'SIGKILL'
     try {
-      await this.signalGroup(sandbox, this.remotePid, 'KILL')
+      await this.signalGroup(sandbox, processGroupId, 'KILL')
     } finally {
       await handle.kill().catch(() => false)
     }
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 1a916c0fd5..565e406b97 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -1,7 +1,6 @@
 /** E2B PTY allocation and process-session ownership for the subprocess seam. */
 
 import { Buffer } from 'node:buffer'
-import { constants } from 'node:os'
 import { PassThrough } from 'node:stream'
 import { posix } from 'node:path'
 import {
@@ -53,13 +52,8 @@ function delay(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms))
 }
 
-function commandSignal(exitCode: number): NodeJS.Signals | null {
-  const number = exitCode - 128
-  if (number <= 0) return null
-  for (const [name, value] of Object.entries(constants.signals)) {
-    if (value === number) return name as NodeJS.Signals
-  }
-  return null
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
 }
 
 function parsePositiveId(value: string, message: string): number {
@@ -121,6 +115,132 @@ async function waitUntilReady(
   }
 }
 
+async function sessionProcessGroups(sandbox: Sandbox, sessionId: number): Promise<number[]> {
+  const result = await sandbox.commands.run(
+    `ps -eo sid=,pgid= | awk '$1 == ${sessionId} { print $2 }'`,
+  )
+  const groups = new Set<number>()
+  for (const raw of result.stdout.trim().split(/\s+/)) {
+    if (raw.length === 0) continue
+    const group = parsePositiveId(
+      raw,
+      `subprocess-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${sessionId}`,
+    )
+    if (group <= 1) {
+      throw new Error(`subprocess-e2b: unsafe process group ${group} in terminal session ${sessionId}`)
+    }
+    groups.add(group)
+  }
+  return [...groups]
+}
+
+async function signalGroups(sandbox: Sandbox, groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
+  try {
+    await sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
+  } catch (error: unknown) {
+    if (!(error instanceof CommandExitError)) throw error
+  }
+}
+
+async function awaitSessionEmpty(
+  sandbox: Sandbox,
+  sessionId: number,
+  graceMs: number,
+  kill = false,
+): Promise<number[]> {
+  const deadline = Date.now() + graceMs
+  for (;;) {
+    const groups = await sessionProcessGroups(sandbox, sessionId)
+    if (groups.length === 0 || Date.now() >= deadline) return groups
+    if (kill) await signalGroups(sandbox, groups, 'KILL')
+    await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
+  }
+}
+
+async function rollbackUnpublishedTerminal(
+  sandbox: Sandbox,
+  handle: CommandHandle,
+  completion: Promise<CommandResult>,
+  graceMs: number,
+): Promise<void> {
+  let topLevelExited = false
+  void completion.then(
+    () => { topLevelExited = true },
+    () => { topLevelExited = true },
+  )
+  const validPid = Number.isSafeInteger(handle.pid) && handle.pid > 1
+  const attemptFailures: Error[] = []
+  let sessionId: number | undefined
+  if (validPid) {
+    sessionId = handle.pid
+    try {
+      sessionId = await terminalSessionId(sandbox, handle.pid)
+    } catch (_sessionLookupFailure) {
+      // E2B's PTY leader is also the provisional POSIX session leader, so its
+      // PID remains usable after the setup lookup itself fails or is canceled.
+    }
+    try {
+      let groups = await sessionProcessGroups(sandbox, sessionId)
+      if (groups.length > 0) {
+        await signalGroups(sandbox, groups, 'TERM')
+        groups = await awaitSessionEmpty(sandbox, sessionId, graceMs)
+      }
+      if (groups.length > 0) {
+        await signalGroups(sandbox, groups, 'KILL')
+        await awaitSessionEmpty(sandbox, sessionId, graceMs, true)
+      }
+    } catch (error: unknown) {
+      attemptFailures.push(asError(error))
+    }
+  }
+  // Completion can settle while any awaited provider cleanup above is running.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!topLevelExited) {
+    if (validPid) {
+      try {
+        await sandbox.pty.kill(handle.pid)
+      } catch (error: unknown) {
+        attemptFailures.push(asError(error))
+      }
+    }
+    // The awaited PTY fallback can settle completion before the SDK fallback.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!topLevelExited) {
+      try {
+        await handle.kill()
+      } catch (error: unknown) {
+        attemptFailures.push(asError(error))
+      }
+    }
+    await Promise.race([completion.catch(() => undefined), delay(graceMs)])
+  }
+  const proofFailures: Error[] = []
+  if (sessionId !== undefined) {
+    try {
+      const groups = await awaitSessionEmpty(sandbox, sessionId, graceMs, true)
+      if (groups.length > 0) {
+        proofFailures.push(new Error(
+          `subprocess-e2b: terminal setup rollback failed; surviving process groups: ${groups.join(', ')}`,
+        ))
+      }
+    } catch (error: unknown) {
+      proofFailures.push(asError(error))
+    }
+  }
+  // The bounded completion race above updates this callback-owned state.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!topLevelExited) {
+    proofFailures.push(new Error(`subprocess-e2b: terminal setup rollback failed; surviving pid: ${handle.pid}`))
+  }
+  if (proofFailures.length > 0) {
+    throw new AggregateError(
+      [...attemptFailures, ...proofFailures],
+      'subprocess-e2b: terminal setup rollback did not reach quiescence',
+    )
+  }
+  await handle.disconnect()
+}
+
 /** One E2B PTY and all process groups in its remote process session. */
 export class E2BTerminalHandle implements SubprocessTerminalHandle {
   readonly pid: number
@@ -203,8 +323,9 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
       return { exitCode: result.exitCode, signal: null }
     } catch (error: unknown) {
       if (error instanceof CommandExitError) {
-        const signal = this.terminationSignal ?? commandSignal(error.exitCode)
-        return signal === null ? { exitCode: error.exitCode, signal: null } : { exitCode: null, signal }
+        return this.terminationSignal === null
+          ? { exitCode: error.exitCode, signal: null }
+          : { exitCode: null, signal: this.terminationSignal }
       }
       this.output.destroy(error instanceof Error ? error : new Error(String(error)))
       throw error
@@ -214,49 +335,12 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     }
   }
 
-  private async sessionProcessGroups(): Promise<number[]> {
-    const result = await this.sandbox.commands.run(
-      `ps -eo sid=,pgid= | awk '$1 == ${this.sessionId} { print $2 }'`,
-    )
-    const groups = new Set<number>()
-    for (const raw of result.stdout.trim().split(/\s+/)) {
-      if (raw.length === 0) continue
-      const group = parsePositiveId(
-        raw,
-        `subprocess-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${this.sessionId}`,
-      )
-      if (group <= 1) {
-        throw new Error(`subprocess-e2b: unsafe process group ${group} in terminal session ${this.sessionId}`)
-      }
-      groups.add(group)
-    }
-    return [...groups]
-  }
-
-  private async signalGroups(groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
-    try {
-      await this.sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
-    } catch (error: unknown) {
-      if (!(error instanceof CommandExitError)) throw error
-    }
-  }
-
-  private async awaitSessionEmpty(kill = false): Promise<number[]> {
-    const deadline = Date.now() + this.graceMs
-    for (;;) {
-      const groups = await this.sessionProcessGroups()
-      if (groups.length === 0 || Date.now() >= deadline) return groups
-      if (kill) await this.signalGroups(groups, 'KILL')
-      await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
-    }
-  }
-
   private async closeOnce(): Promise<void> {
-    let groups = await this.sessionProcessGroups()
+    let groups = await sessionProcessGroups(this.sandbox, this.sessionId)
     if (groups.length > 0) {
       this.terminationSignal = 'SIGTERM'
-      await this.signalGroups(groups, 'TERM')
-      groups = await this.awaitSessionEmpty()
+      await signalGroups(this.sandbox, groups, 'TERM')
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.graceMs)
     }
     if (groups.length === 0 && !this.topLevelExited) {
       await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
@@ -264,7 +348,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     if (groups.length > 0 || !this.topLevelExited) {
       this.terminationSignal = 'SIGKILL'
       if (!this.topLevelExited) await this.sandbox.pty.kill(this.pid)
-      groups = await this.awaitSessionEmpty(true)
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.graceMs, true)
       if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
     }
     if (groups.length > 0) {
@@ -348,9 +432,20 @@ export async function spawnE2BTerminal(
     )
   } catch (error: unknown) {
     output.destroy()
-    if (handle !== undefined) await handle.kill().catch(() => false)
-    if (completion !== undefined) await completion.catch(() => {})
+    let cleanupError: Error | undefined
+    if (handle !== undefined && completion !== undefined) {
+      try {
+        await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
+      } catch (rollbackError: unknown) {
+        cleanupError = asError(rollbackError)
+      }
+    } else if (handle !== undefined) {
+      await handle.kill().catch(() => false)
+    }
     await sandbox.files.remove(stateDir).catch(() => {})
+    if (cleanupError !== undefined) {
+      throw new AggregateError([asError(error), cleanupError], asError(error).message)
+    }
     throw error
   }
 }
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index fd4cc97a83..32adf872b3 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -10,7 +10,7 @@ import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
 import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
 import * as E2BSubprocessInvariant from '../src/invariant.ts'
-import { E2BOutputReader } from '../src/output.ts'
+import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from '../src/output.ts'
 import { E2BSubprocessHandle } from '../src/process.ts'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import { describe, expect, it, vi } from 'vitest'
@@ -91,6 +91,7 @@ class FakeSandbox {
   trapsTerm = false
   delaysKill = false
   alive = true
+  ambient = 'PATH=/ambient/bin\0KEEP=safe\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   processGroupId = '4242\n'
   readonly processGroupReads: string[] = []
   beforeProbe: (() => void) | undefined
@@ -110,15 +111,35 @@ class FakeSandbox {
 
   finish(exitCode = 0): void {
     this.alive = false
-    if (exitCode === 0) this.handle.succeed(0)
-    else this.handle.fail(exitCode)
+    void this.completeOutput().then(
+      () => {
+        if (exitCode === 0) this.handle.succeed(0)
+        else this.handle.fail(exitCode)
+      },
+      (error: unknown) => { this.handle.crash(error) },
+    )
+  }
+
+  async completeOutput(): Promise<void> {
+    await Promise.all([
+      this.stdoutWire(`${E2B_OUTPUT_COMPLETE_FRAME}\n`),
+      this.stderrWire(`${E2B_OUTPUT_COMPLETE_FRAME}\n`),
+    ])
   }
 
   async stdout(data: string): Promise<void> {
-    await this.startOptions?.onStdout?.(data)
+    await this.stdoutWire(data.length === 0 ? '' : `${Buffer.from(data).toString('base64')}\n`)
   }
 
   async stderr(data: string): Promise<void> {
+    await this.stderrWire(data.length === 0 ? '' : `${Buffer.from(data).toString('base64')}\n`)
+  }
+
+  async stdoutWire(data: string): Promise<void> {
+    await this.startOptions?.onStdout?.(data)
+  }
+
+  async stderrWire(data: string): Promise<void> {
     await this.startOptions?.onStderr?.(data)
   }
 
@@ -147,6 +168,7 @@ class FakeSandbox {
     commands: {
       run: async (command: string, options?: StartOptions | { signal?: AbortSignal }): Promise<CommandHandle | CommandResult> => {
         this.commandsSeen.push(command)
+        if (command === 'env -0') return { exitCode: 0, stdout: this.ambient, stderr: '' }
         if (command.startsWith('kill -0 ')) {
           this.beforeProbe?.()
           if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
@@ -221,11 +243,35 @@ async function flush(): Promise<void> {
 }
 
 describe('E2BOutputReader', () => {
+  it('decodes base64 across arbitrary callback boundaries and rejects malformed framing', () => {
+    const decoder = new E2BBase64Decoder()
+    expect(decoder.push('')).toEqual(Buffer.alloc(0))
+    expect(decoder.push('5')).toEqual(Buffer.alloc(0))
+    expect(decoder.push('L2')).toEqual(Buffer.alloc(0))
+    expect(decoder.push('g\n').toString()).toBe('你')
+    expect(decoder.push('YQ==\nYg==\n').toString()).toBe('ab')
+    expect(decoder.push(`${Buffer.from([0, 255]).toString('base64')}\n`)).toEqual(Buffer.from([0, 255]))
+    expect(decoder.push(`${E2B_OUTPUT_COMPLETE_FRAME}\n`)).toEqual(Buffer.alloc(0))
+    decoder.finish()
+
+    expect(() => new E2BBase64Decoder().push('%\n')).toThrow('invalid base64')
+    expect(() => new E2BBase64Decoder().push('AB==\n')).toThrow('invalid base64')
+    expect(() => decoder.push(`${E2B_OUTPUT_COMPLETE_FRAME}\n`)).toThrow('duplicate output transport completion')
+    expect(() => decoder.push('YQ==\n')).toThrow('continued after completion')
+    const truncated = new E2BBase64Decoder()
+    truncated.push('YQ')
+    expect(() => { truncated.finish() }).toThrow('truncated base64')
+    expect(() => { new E2BBase64Decoder().finish() }).toThrow('incomplete output transport')
+    const interrupted = new E2BBase64Decoder()
+    interrupted.push('YQ')
+    expect(() => { interrupted.finish(false) }).not.toThrow()
+  })
+
   it('keeps a byte-exact tail with independent whole-stream cursors', () => {
     const reader = new E2BOutputReader(4, 10, '/remote/spill')
-    reader.push('')
-    reader.push('ab')
-    reader.push('cdef')
+    reader.push(Buffer.alloc(0))
+    reader.push(Buffer.from('ab'))
+    reader.push(Buffer.from('cdef'))
     expect(reader.size).toBe(6)
     expect(reader.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true, spillPath: '/remote/spill' })
     expect(reader.readFrom(2)).toEqual({ text: 'cdef', nextOffset: 6, lossy: false })
@@ -235,11 +281,11 @@ describe('E2BOutputReader', () => {
 
   it('drops whole head chunks and withholds absent or over-cap spills', () => {
     const withoutSpill = new E2BOutputReader(2, undefined, '/unused')
-    withoutSpill.push('ab')
-    withoutSpill.push('cd')
+    withoutSpill.push(Buffer.from('ab'))
+    withoutSpill.push(Buffer.from('cd'))
     expect(withoutSpill.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
     const overCap = new E2BOutputReader(2, 3, '/too-small')
-    overCap.push('abcd')
+    overCap.push(Buffer.from('abcd'))
     expect(overCap.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
     expect(() => overCap.readFrom(-1)).toThrow(/non-negative safe integer/)
     expect(() => overCap.readFrom(1.5)).toThrow(/non-negative safe integer/)
@@ -265,16 +311,22 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.handle.sent.map(value => String(value))).toEqual(['hello'])
     expect(fake.handle.closes).toBe(1)
     expect(fake.startOptions?.envs).toBeUndefined()
-    const command = fake.commandsSeen.find(value => value.startsWith('exec setsid'))!
-    expect(command).toContain('exec setsid --wait -- bash -c')
+    const command = fake.commandsSeen.find(value => value.includes('exec "$dsh_e2b_env_bin" -i'))!
+    expect(command).toContain('"$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c')
     expect(command).not.toContain('DEEPSEEK_API_KEY')
     expect(command).not.toContain('DSH_MODE')
     expect(command).not.toContain('FOO-BAR')
     expect(command).not.toContain('explicit-secret')
     expect(command).not.toContain('hyphen-value')
     expect(command).not.toContain('${!dsh_e2b_name}')
-    expect(command).toContain('env -0')
+    expect(fake.commandsSeen).toContain('env -0')
     expect(command).toContain('mapfile -d')
+    expect(command).toContain('dsh_e2b_node="$(command -v node)"')
+    expect(command).toContain('"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e')
+    expect(command).toContain('exec "$dsh_e2b_env_bin" -i "${dsh_e2b_env[@]}"')
+    expect(command).toContain('>&2 2>/dev/null')
+    expect(command).not.toContain('2>/dev/null >&2')
+    expect(command).toContain('base64')
     expect(fake.writtenFiles[0]).toEqual([
       '/workspace/.dsh-e2b/processes/one/pid',
       '/workspace/.dsh-e2b/processes/one/exit-code',
@@ -282,7 +334,7 @@ describe('E2BSubprocessHandle', () => {
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
     expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
-      'PATH=/bin\0FOO-BAR=hyphen-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+      'PATH=/bin\0KEEP=safe\0FOO-BAR=hyphen-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
     )
 
     let piped = ''
@@ -297,6 +349,47 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('preserves UTF-8 bytes when the ASCII transport is split across callbacks', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/split-utf8')
+    await flush()
+    const chunks: Buffer[] = []
+    handle.stdout!.on('data', (chunk: Buffer) => { chunks.push(chunk) })
+    for (const character of `${Buffer.from('A你好B').toString('base64')}\n`) {
+      await fake.stdoutWire(character)
+    }
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(Buffer.concat(chunks).toString('utf8')).toBe('A你好B')
+  })
+
+  it('rejects malformed output transport without confusing it with a consumer sink failure', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/malformed-output')
+    await flush()
+    await fake.stdoutWire('%\n')
+    fake.finish()
+    await expect(handle.done).rejects.toThrow('invalid base64 output transport')
+
+    const stderrFake = new FakeSandbox()
+    const stderrHandle = new E2BSubprocessHandle(runtime(stderrFake), spec(), '/runtime/malformed-stderr')
+    await flush()
+    await stderrFake.stderrWire('%\n')
+    stderrFake.finish()
+    await expect(stderrHandle.done).rejects.toThrow('invalid base64 output transport')
+  })
+
+  it('rejects a naturally completed command whose encoder omits its completion frame', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/incomplete-output')
+    await flush()
+    fake.alive = false
+    fake.handle.succeed(0)
+    await expect(handle.done).rejects.toThrow('incomplete output transport')
+  })
+
   it('surfaces deferred piped-stdin write and close failures as stream errors', async () => {
     const writeFake = new FakeSandbox()
     writeFake.deferStart()
@@ -362,10 +455,10 @@ describe('E2BSubprocessHandle', () => {
     await handle.done
     expect(handle.collected.stdout!.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
     expect(fake.removed).toContain('/runtime/oversize/stdout.log')
-    const command = fake.commandsSeen.find(value => value.startsWith('exec setsid'))!
-    expect(command).toContain('head -c 3')
+    const command = fake.commandsSeen.find(value => value.includes('dsh_e2b_tee='))!
+    expect(command).toContain('"$dsh_e2b_head" -c 3')
     expect(command).toContain('/runtime/oversize/stdout.log')
-    expect(command).toContain('tee --output-error=warn-nopipe')
+    expect(command).toContain('"$dsh_e2b_tee" --output-error=warn-nopipe')
     expect(command).not.toContain('tee -a')
   })
 
@@ -436,6 +529,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/surviving-group')
     await flush()
+    await fake.completeOutput()
     fake.handle.succeed(0)
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
     expect(fake.alive).toBe(true)
@@ -640,7 +734,13 @@ describe('E2BSubprocessHandle', () => {
     expect(failures[0].message).toContain('invalid process-group id')
     expect(failures[1].message).toBe('rollback signal failed')
     expect(fake.handle.kills).toBe(1)
-    fake.finish()
+    const bounded = new AbortController()
+    const waiting = handle.waitForExit(bounded.signal)
+    bounded.abort()
+    await expect(waiting).resolves.toBe(false)
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
   })
 
   it('waits for delayed process-group publication', async () => {
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 81716c3d52..cefa432acd 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -30,10 +30,13 @@ class FakeTerminalCommandHandle {
   sdkKills = 0
   disconnectError: unknown
   sdkKillError: unknown
+  waitError: unknown
+  settleOnSdkKill = true
   private readonly result = Promise.withResolvers<CommandResult>()
   private settled = false
 
   wait(): Promise<CommandResult> {
+    if (this.waitError !== undefined) throw this.waitError
     return this.result.promise
   }
 
@@ -46,10 +49,10 @@ class FakeTerminalCommandHandle {
     this.sdkKills += 1
     if (this.sdkKillError !== undefined) {
       const error = this.sdkKillError
-      this.fail(137)
+      if (this.settleOnSdkKill) this.fail(137)
       throw error
     }
-    this.fail(137)
+    if (this.settleOnSdkKill) this.fail(137)
     return true
   }
 
@@ -94,8 +97,10 @@ class FakeTerminalSandbox {
   createError: unknown
   sendError: unknown
   commandFailure: unknown
+  sessionGroupsFailure: unknown
   foregroundFailure: unknown
   termFailure: unknown
+  ptyKillError: unknown
   removeError: unknown
   clearOnTerm = true
   clearOnKill = true
@@ -146,6 +151,7 @@ class FakeTerminalSandbox {
           return { exitCode: 0, stdout: this.foreground, stderr: '' }
         }
         if (command.startsWith('ps -eo sid=')) {
+          if (this.sessionGroupsFailure !== undefined) throw this.sessionGroupsFailure
           return { exitCode: 0, stdout: this.groups.map(group => `${group}\n`).join(''), stderr: '' }
         }
         if (command.startsWith('kill -TERM -- ')) {
@@ -173,6 +179,7 @@ class FakeTerminalSandbox {
       },
       kill: async (pid: number): Promise<boolean> => {
         this.ptyKills += 1
+        if (this.ptyKillError !== undefined) throw this.ptyKillError
         if (this.settleOnPtyKill) this.handle.fail(137)
         return pid === this.handle.pid
       },
@@ -282,7 +289,8 @@ describe('E2B terminal allocation', () => {
     failedInput.sendError = new Error('bootstrap failed')
     await expect(spawnE2BTerminal(runtime(failedInput), spec(), '/runtime/input'))
       .rejects.toThrow('bootstrap failed')
-    expect(failedInput.handle.sdkKills).toBe(1)
+    expect(failedInput.commands).toContain('kill -TERM -- -123')
+    expect(failedInput.groups).toEqual([])
 
     const exited = new FakeTerminalSandbox()
     exited.ready = new FileNotFoundError('not ready')
@@ -292,13 +300,62 @@ describe('E2B terminal allocation', () => {
 
     const invalidSession = new FakeTerminalSandbox()
     invalidSession.sessionId = 'not-a-session\n'
+    invalidSession.clearOnTerm = false
     await expect(spawnE2BTerminal(runtime(invalidSession), spec(), '/runtime/session'))
       .rejects.toThrow('cannot resolve process session')
-    expect(invalidSession.handle.sdkKills).toBe(1)
+    expect(invalidSession.commands).toContain('kill -TERM -- -123')
+    expect(invalidSession.commands).toContain('kill -KILL -- -123')
+    expect(invalidSession.groups).toEqual([])
+    expect(invalidSession.ptyKills).toBe(1)
     const lateData = invalidSession.createOptions?.onData
     if (lateData === undefined) throw new Error('missing captured terminal callback')
     expect(lateData(Buffer.from('late bytes'))).toBeUndefined()
 
+    const termFailed = new FakeTerminalSandbox()
+    termFailed.sendError = new Error('bootstrap failed')
+    termFailed.termFailure = new Error('TERM transport failed')
+    await expect(spawnE2BTerminal(runtime(termFailed), spec(), '/runtime/term-failed'))
+      .rejects.toThrow('bootstrap failed')
+    expect(termFailed.commands).toContain('kill -KILL -- -123')
+    expect(termFailed.ptyKills).toBe(1)
+
+    const uninspectable = new FakeTerminalSandbox()
+    uninspectable.sendError = new Error('bootstrap failed')
+    uninspectable.sessionGroupsFailure = 'session enumeration failed'
+    uninspectable.ptyKillError = new Error('PTY kill failed')
+    let uninspectableFailure: unknown
+    try {
+      await spawnE2BTerminal(runtime(uninspectable), spec(), '/runtime/uninspectable')
+    } catch (error: unknown) {
+      uninspectableFailure = error
+    }
+    expect(uninspectableFailure).toBeInstanceOf(AggregateError)
+    expect(uninspectable.ptyKills).toBe(1)
+    expect(uninspectable.handle.sdkKills).toBe(1)
+
+    const survivingGroups = new FakeTerminalSandbox()
+    survivingGroups.sendError = new Error('bootstrap failed')
+    survivingGroups.clearOnTerm = false
+    survivingGroups.clearOnKill = false
+    await expect(spawnE2BTerminal(runtime(survivingGroups), spec({ graceMs: 1 }), '/runtime/surviving-groups'))
+      .rejects.toThrow('bootstrap failed')
+
+    const survivingPid = new FakeTerminalSandbox()
+    survivingPid.sendError = new Error('bootstrap failed')
+    survivingPid.groups = []
+    survivingPid.settleOnPtyKill = false
+    survivingPid.handle.settleOnSdkKill = false
+    await expect(spawnE2BTerminal(runtime(survivingPid), spec({ graceMs: 1 }), '/runtime/surviving-pid'))
+      .rejects.toThrow('bootstrap failed')
+
+    const waitFailed = new FakeTerminalSandbox()
+    waitFailed.handle.waitError = new Error('wait failed')
+    waitFailed.handle.settleOnSdkKill = false
+    waitFailed.handle.sdkKillError = new Error('kill failed')
+    await expect(spawnE2BTerminal(runtime(waitFailed), spec(), '/runtime/wait-failed'))
+      .rejects.toThrow('wait failed')
+    expect(waitFailed.handle.sdkKills).toBe(1)
+
     const cleanupFailed = new FakeTerminalSandbox()
     cleanupFailed.handle.pid = 0
     cleanupFailed.handle.sdkKillError = new Error('kill transport failed')
@@ -362,7 +419,7 @@ describe('E2B terminal lifecycle', () => {
 
   it.each([
     [7, { exitCode: 7, signal: null }],
-    [143, { exitCode: null, signal: 'SIGTERM' }],
+    [143, { exitCode: 143, signal: null }],
     [255, { exitCode: 255, signal: null }],
   ] as const)('classifies an unrequested command exit %i', async (exitCode, expected) => {
     const fake = new FakeTerminalSandbox()

From 62df6d0c0977a71c689e91abb4b27c6f4c9a3262 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 05:45:55 +0800
Subject: [PATCH 365/516] refactor(e2b): share environment scrubbing

---
 .../e2b/subprocess-e2b/src/environment.ts     | 21 +++++++++++++++++++
 packages/e2b/subprocess-e2b/src/process.ts    | 12 ++---------
 packages/e2b/subprocess-e2b/src/terminal.ts   | 13 +++---------
 3 files changed, 26 insertions(+), 20 deletions(-)
 create mode 100644 packages/e2b/subprocess-e2b/src/environment.ts

diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
new file mode 100644
index 0000000000..cc9b41296a
--- /dev/null
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -0,0 +1,21 @@
+/** Shared remote-environment scrubbing for E2B process and terminal launchers. */
+
+import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
+
+/**
+ * Parse an E2B NUL-delimited environment while removing harness-private and credential-shaped names.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @returns Mutable retained entries for the caller to overlay and serialize.
+ */
+export function scrubRemoteEnvironment(raw: string): Map<string, string> {
+  const environment = new Map<string, string>()
+  for (const entry of raw.split('\0')) {
+    if (entry.length === 0) continue
+    const separator = entry.indexOf('=')
+    if (separator <= 0) continue
+    const name = entry.slice(0, separator)
+    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
+    environment.set(name, entry.slice(separator + 1))
+  }
+  return environment
+}
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 9eeee5d877..5f8a107cf6 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -8,7 +8,6 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessCollect,
   SubprocessHandle,
@@ -17,6 +16,7 @@ import type {
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import { scrubRemoteEnvironment } from './environment.ts'
 import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
 
 const GROUP_POLL_MS = 20
@@ -74,15 +74,7 @@ interface RemotePaths {
 }
 
 function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
-  const environment = new Map<string, string>()
-  for (const entry of raw.split('\0')) {
-    if (entry.length === 0) continue
-    const separator = entry.indexOf('=')
-    if (separator <= 0) continue
-    const name = entry.slice(0, separator)
-    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
-    environment.set(name, entry.slice(separator + 1))
-  }
+  const environment = scrubRemoteEnvironment(raw)
   for (const [name, value] of Object.entries(explicit ?? {})) environment.set(name, value)
   return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
 }
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 565e406b97..7185899f79 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -9,7 +9,7 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { SENSITIVE_ENV_PATTERN, SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
+import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessOutcome,
   SubprocessTerminalForeground,
@@ -18,6 +18,7 @@ import type {
   SubprocessTerminalSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import { scrubRemoteEnvironment } from './environment.ts'
 
 const POLL_MS = 20
 
@@ -71,15 +72,7 @@ function serializeValues(values: readonly string[], kind: string): string {
 }
 
 function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
-  const environment = new Map<string, string>()
-  for (const entry of raw.split('\0')) {
-    if (entry.length === 0) continue
-    const separator = entry.indexOf('=')
-    if (separator <= 0) continue
-    const name = entry.slice(0, separator)
-    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
-    environment.set(name, entry.slice(separator + 1))
-  }
+  const environment = scrubRemoteEnvironment(raw)
   for (const [name, value] of Object.entries(explicit ?? {})) {
     if (name.length === 0 || name.includes('=') || name.includes('\0') || value.includes('\0')) {
       throw new Error('subprocess-e2b: terminal environment entries require non-empty NUL-free names without = and NUL-free values')

From ec0310ca1b5eca56424c617af7360d40b329ce59 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 07:03:04 +0800
Subject: [PATCH 366/516] fix(e2b): harden remote teardown transactions

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |   2 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |   2 +-
 .../tests/fixtures/e2b/e2b/bin.ts             |  25 ++
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/index.ts                 |   6 +-
 packages/e2b/e2b/tests/composition.e2e.ts     |  29 +-
 packages/e2b/e2b/tests/e2b.spec.ts            |  23 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |  12 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  12 +-
 packages/e2b/subprocess-e2b/src/index.ts      |   6 +-
 packages/e2b/subprocess-e2b/src/output.ts     |   8 +-
 packages/e2b/subprocess-e2b/src/process.ts    | 332 ++++++++++++++----
 packages/e2b/subprocess-e2b/src/terminal.ts   |  47 +--
 .../subprocess-e2b/tests/subprocess.spec.ts   | 311 +++++++++++++++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  16 +
 19 files changed, 712 insertions(+), 135 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index b5e8e6e47c..079924ac74 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 029950cb2dae47bcf1ce819156135e58d46a4bb6
-2026-07-27-e2b-remote-runtime-poc.zh.md: 4029cc85d206e0dd0b7dbd91ec03674062df8531
+2026-07-27-e2b-remote-runtime-poc.md: 02de8df021094fa326431a996cd183d13b9c0c8c
+2026-07-27-e2b-remote-runtime-poc.zh.md: 3b7ddf761b2cbf950898a0083cf9da653d20e723
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index 029950cb2d..02de8df021 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -38,7 +38,7 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 Focused package suites pin owner lifecycle cleanup, filesystem paths/containment/bounded descriptor reads and commit metadata, subprocess executable lookup/process groups/publication rollback, terminal byte I/O/signal identity/default-environment scrubbing/session cleanup, output limits, abort ordering, disposal to quiescence, and package-owned invariant registrations. The generic PTY, LSP, and subprocess Code Runtime suites pin their provider-neutral readiness, cross-namespace `processId`, binding bridge, descriptor isolation, hostile traffic, and worker/descendant cleanup behavior.
 
-A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, process-publication rollback, byte-split UTF-8 command output, bounded raw spill output, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
+A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, real-directory runtime-state setup, process-publication rollback, byte-split UTF-8 command output, bounded raw spill and inherited-output draining, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 4029cc85d2..3b7ddf761b 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -38,7 +38,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 聚焦包测试套件固定所有者生命周期清理、文件系统路径／containment／有界描述符读取与提交元数据、子进程可执行文件查找／进程组／发布回滚、终端字节 I/O／信号身份／默认环境清理／会话清理、输出上限、中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。通用 PTY、LSP 与子进程 Code Runtime 测试套件固定其提供方无关的就绪判定、跨命名空间 `processId`、绑定桥接、描述符隔离、恶意通信，以及 worker／后代进程清理行为。
 
-凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 输出、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
+凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、真实目录形式的运行时状态设置、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 与继承输出排空、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 7c5fce5535..6fa95c24b6 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -85,6 +85,30 @@ try {
     throw new Error(`E2B subprocess corrupted split UTF-8 output: ${JSON.stringify({ splitUtf8Outcome, splitUtf8Output })}`)
   }
 
+  const outputDrainStarted = Date.now()
+  const outputDrainHandle = ctx.subprocess.spawn({
+    argv: ['bash', '-c', "bash -c 'exec -a dsh-output-drain-descendant sleep 30' & printf 'leader-done\\n'"],
+    cwd: process.cwd(),
+    stdio: { stdin: 'ignore', stdout: { maxBytes: 64 }, stderr: { maxBytes: 4_096 } },
+    graceMs: 250,
+    env: {},
+  })
+  const outputDrainOutcome = await outputDrainHandle.done
+  const outputDrainText = outputDrainHandle.collected.stdout?.readFrom(0).text
+  const outputDrainElapsedMs = Date.now() - outputDrainStarted
+  outputDrainHandle.terminate()
+  const outputDrainExited = await outputDrainHandle.waitForExit(AbortSignal.timeout(5_000))
+  const outputDrainProcesses = await sandbox.commands.list()
+  const outputDrainClean = !outputDrainProcesses.some(processInfo =>
+    JSON.stringify([processInfo.cmd, processInfo.args]).includes('dsh-output-drain-descendant'),
+  )
+  if (outputDrainOutcome.exitCode !== 0 || outputDrainText !== 'leader-done\n'
+    || outputDrainElapsedMs >= 10_000 || !outputDrainExited || !outputDrainClean) {
+    throw new Error(`E2B subprocess output drain was not bounded: ${JSON.stringify({
+      outputDrainOutcome, outputDrainText, outputDrainElapsedMs, outputDrainExited, outputDrainClean,
+    })}`)
+  }
+
   const remoteFiles = sandbox.files as unknown as {
     read(path: string, options?: unknown): Promise<unknown>
   }
@@ -384,6 +408,7 @@ try {
     fsRead,
     explicitEnvironment,
     splitUtf8Output,
+    outputDrain: { outcome: outputDrainOutcome, text: outputDrainText, exited: outputDrainExited, clean: outputDrainClean },
     publicationRollback,
     spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 229a9e9343..d8f1dcdc3f 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 56606a22c36e65bcc53f2b8cce27f0739da1b8e2
-README.zh.md: 2e3213e431f15f1b22d2b8a429b27ab8a6a78671
+README.md: 01c7ade2f5f31e34091ad0ae910287e659f15549
+README.zh.md: fb95a12cbbbd431ccb3283a14bb63b324f9bdea6
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 56606a22c3..01c7ade2f5 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -28,7 +28,7 @@ Set `sandboxId` to reconnect a running or paused sandbox instead of creating one
 
 ## Lifecycle and ownership
 
-Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, then sets that directory to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
+Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
 
 Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` means a kill-on-timeout sandbox is already quiescent; every other disposition failure rejects teardown. A newly created sandbox is killed when initial directory setup fails; a reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 2e3213e431..fb95a12cbb 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -28,7 +28,7 @@
 
 ## 生命周期与所有权
 
-构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
+构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
 
 资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 表示因超时终止的沙箱已经完全停稳；其他处置失败都会使 teardown 拒绝。新建沙箱的初始目录设置失败时，服务会终止该沙箱；重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 96da912033..2c0b3c635c 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -7,7 +7,7 @@
 import { posix } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import { Sandbox, SandboxNotFoundError } from 'e2b'
+import { FileType, Sandbox, SandboxNotFoundError } from 'e2b'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 
 export {
@@ -232,6 +232,10 @@ export class E2BSandboxService extends Service {
     try {
       await sandbox.files.makeDir(this.cwd)
       await sandbox.files.makeDir(this.runtimeRoot)
+      const runtimeRoot = await sandbox.files.getInfo(this.runtimeRoot)
+      if (runtimeRoot.type !== FileType.DIR || runtimeRoot.symlinkTarget !== undefined) {
+        throw new Error(`dsh-e2b: runtime root must be a real directory: ${this.runtimeRoot}`)
+      }
       await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.runtimeRoot)}`)
       return sandbox
     } catch (error: unknown) {
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 4e7be57c45..1ece44bb6a 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -5,7 +5,7 @@ import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
-import { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+import E2BSandboxService, { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
 import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
 import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
@@ -92,6 +92,27 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       await session.close('environment test complete')
       await subprocessFiber.dispose()
       await ptyFiber.dispose()
+
+      await sandbox.commands.run([
+        'rm -rf -- /home/user/.dsh-e2b /home/user/dsh-e2b-runtime-target',
+        'mkdir -p -- /home/user/dsh-e2b-runtime-target',
+        'chmod 755 -- /home/user/dsh-e2b-runtime-target',
+        'ln -s -- /home/user/dsh-e2b-runtime-target /home/user/.dsh-e2b',
+      ].join('\n'))
+      const linkedCtx = new Context()
+      const linkedFiber = await linkedCtx.plugin(E2BSandboxService, {
+        apiKey,
+        sandboxId: sandbox.sandboxId,
+        cwd: '/home/user',
+        onDispose: 'leave',
+      })
+      try {
+        await expect(linkedCtx.e2b.getSandbox()).rejects.toThrow('runtime root must be a real directory')
+        const target = await sandbox.files.getInfo('/home/user/dsh-e2b-runtime-target')
+        expect(target.mode & 0o777).toBe(0o755)
+      } finally {
+        await linkedFiber.dispose()
+      }
     } finally {
       await sandbox.kill().catch(() => false)
     }
@@ -123,6 +144,12 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       fsRead: 'written-by-bash\n',
       explicitEnvironment: true,
       splitUtf8Output: '你好',
+      outputDrain: {
+        outcome: { exitCode: 0, signal: null },
+        text: 'leader-done\n',
+        exited: true,
+        clean: true,
+      },
       publicationRollback: true,
       spill: {
         liveBytes: 6,
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index bb96ca806a..ff90c37b3a 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -3,6 +3,7 @@ import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
   E2BSandboxId,
+  FileType,
   SandboxNotFoundError,
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
@@ -33,6 +34,7 @@ vi.mock('e2b', async (importOriginal) => {
 interface SandboxFixture {
   sandbox: SandboxType
   makeDir: ReturnType<typeof vi.fn>
+  getInfo: ReturnType<typeof vi.fn>
   run: ReturnType<typeof vi.fn>
   kill: ReturnType<typeof vi.fn>
   pause: ReturnType<typeof vi.fn>
@@ -40,17 +42,18 @@ interface SandboxFixture {
 
 function fakeSandbox(id = 'sandbox-1'): SandboxFixture {
   const makeDir = vi.fn().mockResolvedValue(true)
+  const getInfo = vi.fn().mockResolvedValue({ type: FileType.DIR })
   const run = vi.fn().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
   const kill = vi.fn().mockResolvedValue(undefined)
   const pause = vi.fn().mockResolvedValue(true)
   const sandbox = {
     sandboxId: id,
-    files: { makeDir },
+    files: { makeDir, getInfo },
     commands: { run },
     kill,
     pause,
   } as unknown as SandboxType
-  return { sandbox, makeDir, run, kill, pause }
+  return { sandbox, makeDir, getInfo, run, kill, pause }
 }
 
 beforeEach(() => {
@@ -82,6 +85,7 @@ describe('E2BSandboxService', () => {
     })
     expect(fixture.makeDir).toHaveBeenNthCalledWith(1, '/home/user/workspace')
     expect(fixture.makeDir).toHaveBeenNthCalledWith(2, '/home/user/workspace/.dsh-e2b')
+    expect(fixture.getInfo).toHaveBeenCalledWith('/home/user/workspace/.dsh-e2b')
     expect(fixture.run).toHaveBeenCalledWith("chmod 700 -- '/home/user/workspace/.dsh-e2b'")
 
     await fiber.dispose()
@@ -220,6 +224,21 @@ describe('E2BSandboxService', () => {
     expect(fixture.kill).not.toHaveBeenCalled()
   })
 
+  it.each([
+    ['symbolic link', { type: FileType.DIR, symlinkTarget: '/tmp/redirected' }],
+    ['regular file', { type: FileType.FILE }],
+  ])('rejects a reserved runtime root that is a %s', async (_label, info) => {
+    const fixture = fakeSandbox()
+    fixture.getInfo.mockResolvedValueOnce(info)
+    sdk.connect.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', sandboxId: 'existing' })
+
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('runtime root must be a real directory')
+    expect(fixture.run).not.toHaveBeenCalled()
+    expect(fixture.kill).not.toHaveBeenCalled()
+  })
+
   it.each([
     [{ apiKey: '' }, /configure apiKey/],
     [{ apiKey: 'x', cwd: 'relative' }, /absolute Linux path/],
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 33a36141d0..091a6972cf 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 58f13b264324d2168d4bc264b60100cdafa0a366
-README.zh.md: d547e4e8d66f629edcef753651180fe1806ad9bf
+README.md: b1aa480305fef9ca485340b6bdae50f9fcffd88f
+README.zh.md: b4824c90e7fb908d9c12e77c19d2b952055dcb40
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 58f13b2643..b1aa480305 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -6,14 +6,14 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 ## Behavior
 
-- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; `done`, stdin, termination, and `waitForExit()` wait for readiness internally.
+- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication, while cancellation can stop the provisional SDK handle first.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback. If publication fails, the SDK PID remains the provisional `exec setsid` group id; rollback kills and verifies that group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
-- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly.
-- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
+- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers; after `graceMs`, the adapter disconnects an incomplete SDK stream, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Batch and streaming stdin use the SDK handle.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. Setup and teardown own the private state transaction, including failure cleanup. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
-The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
+The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
 ## Model Experience
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index d547e4e8d6..b4824c90e7 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -6,14 +6,14 @@
 
 ## 行为
 
-- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；`done`、stdin、终止和 `waitForExit()` 会在内部等待就绪。
+- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布，而取消操作可以先停止临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退。如果发布失败，SDK PID 仍为临时的 `exec setsid` 进程组 ID；回滚会终止并验证该进程组，随后启动操作才会以拒绝结束。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
-- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。
-- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
+- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态；超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。setup 与 teardown 负责私有状态事务，包括失败清理。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
-基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
+基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
 ## 模型体验
 
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 86ca5ceada..27efb216da 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -46,14 +46,12 @@ export class E2BSubprocessService extends SubprocessService {
       const pending: Promise<unknown>[] = []
       for (const handle of handles) {
         handle.terminate()
-        pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))
+        pending.push(handle.waitForExit().then(() => { this.live.delete(handle) }))
       }
       for (const terminal of terminals) {
         terminal.terminate()
-        pending.push(terminal.waitForExit())
+        pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
       }
-      this.live.clear()
-      this.terminals.clear()
       await Promise.all(pending)
     }, 'e2b subprocess teardown')
   }
diff --git a/packages/e2b/subprocess-e2b/src/output.ts b/packages/e2b/subprocess-e2b/src/output.ts
index 6cb61e4f09..8afcd138dc 100644
--- a/packages/e2b/subprocess-e2b/src/output.ts
+++ b/packages/e2b/subprocess-e2b/src/output.ts
@@ -66,6 +66,7 @@ export class E2BOutputReader implements SubprocessOutputReader {
   private chunks: Buffer[] = []
   private retainedBytes = 0
   private totalBytes = 0
+  private spillValid = true
 
   /**
    * Create a bounded reader over one remote spill path.
@@ -84,6 +85,11 @@ export class E2BOutputReader implements SubprocessOutputReader {
     return this.totalBytes
   }
 
+  /** Stop advertising a remote spill whose writer did not reach clean EOF. */
+  invalidateSpill(): void {
+    this.spillValid = false
+  }
+
   /**
    * Append one byte-faithful decoded transport event.
    * @param bytes - Raw command bytes recovered from the ASCII SDK transport.
@@ -120,7 +126,7 @@ export class E2BOutputReader implements SubprocessOutputReader {
       text: retained.subarray(start).toString('utf8'),
       nextOffset: this.totalBytes,
       lossy,
-      ...(lossy && this.maxSpillBytes !== undefined && this.totalBytes <= this.maxSpillBytes
+      ...(lossy && this.spillValid && this.maxSpillBytes !== undefined && this.totalBytes <= this.maxSpillBytes
         ? { spillPath: this.spillPath }
         : {}),
     }
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 5f8a107cf6..3a8047eb54 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -5,6 +5,7 @@ import { PassThrough, Writable } from 'node:stream'
 import { posix } from 'node:path'
 import {
   CommandExitError,
+  FileNotFoundError,
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
@@ -41,6 +42,10 @@ function hasSpill(mode: SubprocessOutputMode): mode is SubprocessCollect & { spi
   return isCollect(mode) && mode.spill !== undefined
 }
 
+function isValidProcessId(value: number): boolean {
+  return Number.isSafeInteger(value) && value > 0
+}
+
 function asError(error: unknown): Error {
   return error instanceof Error ? error : new Error(String(error))
 }
@@ -73,6 +78,20 @@ interface RemotePaths {
   stderr: string
 }
 
+type CommandSettlement =
+  | { kind: 'result'; result: CommandResult }
+  | { kind: 'error'; error: unknown }
+
+function withinMs<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined> {
+  return new Promise<T | undefined>((resolve) => {
+    const timer = setTimeout(() => { resolve(undefined) }, timeoutMs)
+    void promise.then((value) => {
+      clearTimeout(timer)
+      resolve(value)
+    })
+  })
+}
+
 function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
   const environment = scrubRemoteEnvironment(raw)
   for (const [name, value] of Object.entries(explicit ?? {})) environment.set(name, value)
@@ -96,15 +115,16 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
     'dsh_e2b_tr=$4',
     'dsh_e2b_tee=$5',
     'dsh_e2b_head=$6',
-    'shift 6',
+    'dsh_e2b_rm=$7',
+    'shift 7',
     'dsh_e2b_pgid="$("$dsh_e2b_ps" -o pgid= -p "$$" | "$dsh_e2b_tr" -d " ")"',
     `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
     `mapfile -d '' -t dsh_e2b_env < ${quoteE2BShellArg(paths.environment)}`,
-    `: > ${quoteE2BShellArg(paths.environment)}`,
+    `"$dsh_e2b_rm" -f -- ${quoteE2BShellArg(paths.environment)}`,
     `"$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
     'dsh_e2b_status=$?',
-    'wait',
     `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
+    'wait',
     'exit "$dsh_e2b_status"',
   ].join('\n')
   const argv = spec.argv.map(quoteE2BShellArg).join(' ')
@@ -118,10 +138,11 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
     'dsh_e2b_tr="$(command -v tr)"',
     'dsh_e2b_tee="$(command -v tee)"',
     'dsh_e2b_head="$(command -v head)"',
-    'for dsh_e2b_tool in "$dsh_e2b_env_bin" "$dsh_e2b_setsid" "$dsh_e2b_bash" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head"; do',
+    'dsh_e2b_rm="$(command -v rm)"',
+    'for dsh_e2b_tool in "$dsh_e2b_env_bin" "$dsh_e2b_setsid" "$dsh_e2b_bash" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm"; do',
     '  [[ "$dsh_e2b_tool" == /* && -x "$dsh_e2b_tool" ]] || exit 125',
     'done',
-    `exec "$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" ${argv}`,
+    `exec "$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm" ${argv}`,
   ].join('\n')
   return bootstrap
 }
@@ -149,6 +170,26 @@ function waitTick(signal?: AbortSignal): Promise<boolean> {
   })
 }
 
+const WAIT_ABORTED = Symbol('wait aborted')
+
+function waitWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | typeof WAIT_ABORTED> {
+  if (signal === undefined) return promise
+  if (signal.aborted) return Promise.resolve(WAIT_ABORTED)
+  return new Promise<T | typeof WAIT_ABORTED>((resolve, reject) => {
+    const onAbort = (): void => { cleanup(); resolve(WAIT_ABORTED) }
+    const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    if (signal.aborted) {
+      onAbort()
+      return
+    }
+    void promise.then(
+      (value) => { cleanup(); resolve(value) },
+      (error: unknown) => { cleanup(); reject(asError(error)) },
+    )
+  })
+}
+
 /** E2B-backed subprocess handle with deferred remote PID acquisition. */
 export class E2BSubprocessHandle implements SubprocessHandle {
   readonly stdin: Writable | undefined
@@ -157,6 +198,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   readonly collected: SubprocessHandle['collected']
   readonly done: Promise<SubprocessOutcome>
 
+  private readonly commandState = Promise.withResolvers<CommandHandle | undefined>()
   private readonly readyState = Promise.withResolvers<CommandHandle>()
   private readonly stdoutDecoder = new E2BBase64Decoder()
   private readonly stderrDecoder = new E2BBase64Decoder()
@@ -166,9 +208,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private remotePid = -1
   private commandHandle: CommandHandle | undefined
   private outputTransportError: Error | undefined
-  private terminationRequested = false
+  private outputDrainExpired = false
+  private stateDirectoryCreated = false
+  private invalidHandleQuiescent = false
+  private provisionalHandleQuiescent = false
+  private terminationStarted = false
+  private terminationAttempt: Promise<void> | undefined
+  private terminationFailure: Error | undefined
   private terminationSignal: NodeJS.Signals | null = null
-  private termination: Promise<void> | undefined
 
   /**
    * Begin an E2B command without blocking the synchronous subprocess spawn seam.
@@ -217,22 +264,47 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    if (this.terminationRequested) return
-    this.terminationRequested = true
-    this.termination = this.terminateRemote()
-    void this.termination.catch(() => {})
+    if (this.terminationAttempt !== undefined) return
+    this.terminationStarted = true
+    this.terminationFailure = undefined
+    const attempt = this.terminateRemote()
+    this.terminationAttempt = attempt
+    void attempt.then(
+      () => {
+        this.terminationAttempt = undefined
+      },
+      (error: unknown) => {
+        this.terminationFailure = asError(error)
+        this.terminationAttempt = undefined
+      },
+    )
   }
 
   /** @inheritdoc */
   async waitForExit(signal?: AbortSignal): Promise<boolean> {
     let handle: CommandHandle | undefined
-    try {
-      handle = await this.readyForWait(signal)
-    } catch {
-      handle = this.commandHandle
+    if (this.terminationStarted) {
+      const observed = await waitWithSignal(this.commandState.promise, signal)
+      if (observed === WAIT_ABORTED) return false
+      handle = observed
       if (handle === undefined) return true
+      if (this.remotePid <= 0) {
+        const attempt = this.terminationAttempt
+        if (attempt !== undefined && await waitWithSignal(attempt, signal) === WAIT_ABORTED) return false
+        this.throwTerminationFailure()
+        if (this.invalidHandleQuiescent || this.provisionalHandleQuiescent) return true
+      }
+    } else {
+      try {
+        const observed = await waitWithSignal(this.readyState.promise, signal)
+        if (observed === WAIT_ABORTED) return false
+        handle = observed
+      } catch {
+        handle = this.commandHandle
+        if (handle === undefined) return true
+      }
     }
-    if (handle === undefined) return false
+    this.throwTerminationFailure()
     let sandbox: Sandbox
     try {
       sandbox = await this.runtime.getSandbox()
@@ -242,33 +314,19 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     }
     const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
     while (await this.groupAlive(sandbox, processGroupId, signal)) {
+      this.throwTerminationFailure()
       if (!await waitTick(signal)) return false
     }
+    this.throwTerminationFailure()
     return !isAborted(signal)
   }
 
-  private readyForWait(signal: AbortSignal | undefined): Promise<CommandHandle | undefined> {
-    if (signal === undefined) return this.readyState.promise
-    return new Promise<CommandHandle | undefined>((resolve, reject) => {
-      const onAbort = (): void => { cleanup(); resolve(undefined) }
-      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
-      signal.addEventListener('abort', onAbort, { once: true })
-      if (signal.aborted) {
-        onAbort()
-        return
-      }
-      void this.readyState.promise.then(
-        (handle) => { cleanup(); resolve(handle) },
-        (error: unknown) => { cleanup(); reject(asError(error)) },
-      )
-    })
-  }
-
   private readonly onAbort = (): void => { this.terminate() }
 
   private async run(): Promise<SubprocessOutcome> {
+    let sandbox: Sandbox | undefined
     try {
-      const sandbox = await this.runtime.getSandbox()
+      sandbox = await this.runtime.getSandbox()
       await this.prepareState(sandbox)
       const handle = await sandbox.commands.run(
         commandText(this.spec, this.paths),
@@ -281,12 +339,26 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           onStderr: async (data) => { await this.dispatchOutput('stderr', data) },
         },
       )
-      if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
-        throw new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
-      }
       this.commandHandle = handle
       const completion = handle.wait()
       void completion.catch(() => {})
+      if (!isValidProcessId(handle.pid)) {
+        const invalidPid = new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
+        try {
+          await handle.kill()
+          this.invalidHandleQuiescent = true
+          this.commandHandle = undefined
+        } catch (cleanupError: unknown) {
+          this.terminationFailure = asError(cleanupError)
+          this.commandState.resolve(handle)
+          throw new AggregateError(
+            [invalidPid, cleanupError],
+            'subprocess-e2b: invalid command pid rollback did not reach quiescence',
+          )
+        }
+        throw invalidPid
+      }
+      this.commandState.resolve(handle)
       try {
         this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
       } catch (error: unknown) {
@@ -302,16 +374,28 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       }
       this.readyState.resolve(handle)
       await this.writeBatchStdin(handle)
-      const outcome = await this.waitForCommand(completion)
+      const outcome = await this.waitForCommand(sandbox, handle, completion)
       if (this.outputTransportError !== undefined) throw this.outputTransportError
-      const requireCompleteOutput = this.terminationSignal === null
+      const requireCompleteOutput = this.terminationSignal === null && !this.outputDrainExpired
       this.stdoutDecoder.finish(requireCompleteOutput)
       this.stderrDecoder.finish(requireCompleteOutput)
       await this.finalizeSpills(sandbox)
       return outcome
     } catch (error: unknown) {
-      this.readyState.reject(error)
-      throw error
+      this.commandState.resolve(undefined)
+      let failure = error
+      if (sandbox !== undefined && this.stateDirectoryCreated) {
+        try {
+          await this.removeFailedState(sandbox)
+        } catch (cleanupError: unknown) {
+          failure = new AggregateError(
+            [error, cleanupError],
+            'subprocess-e2b: command failed and private state cleanup failed',
+          )
+        }
+      }
+      this.readyState.reject(failure)
+      throw failure
     } finally {
       this.spec.signal?.removeEventListener('abort', this.onAbort)
       this.stdout?.end()
@@ -322,6 +406,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private async prepareState(sandbox: Sandbox): Promise<void> {
     const ambient = await sandbox.commands.run('env -0')
     await sandbox.files.makeDir(this.stateDir)
+    this.stateDirectoryCreated = true
     await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`)
     const files = [
       { path: this.paths.pid, data: '' },
@@ -405,20 +490,45 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     }
   }
 
-  private async waitForCommand(completion: Promise<CommandResult>): Promise<SubprocessOutcome> {
-    try {
-      const result = await completion
-      return { exitCode: result.exitCode, signal: null }
-    } catch (error: unknown) {
-      if (error instanceof CommandExitError) {
-        return this.terminationSignal === null
-          ? { exitCode: error.exitCode, signal: null }
-          : { exitCode: null, signal: this.terminationSignal }
+  private async waitForCommand(
+    sandbox: Sandbox,
+    handle: CommandHandle,
+    completion: Promise<CommandResult>,
+  ): Promise<SubprocessOutcome> {
+    const settlement = completion.then<CommandSettlement, CommandSettlement>(
+      result => ({ kind: 'result', result }),
+      (error: unknown) => ({ kind: 'error', error }),
+    )
+    while (true) {
+      const rawStatus = (await sandbox.files.read(this.paths.status)).trim()
+      if (rawStatus.length > 0) {
+        const exitCode = Number(rawStatus)
+        if (!/^(?:0|[1-9][0-9]*)$/.test(rawStatus) || !Number.isSafeInteger(exitCode) || exitCode > 255) {
+          throw new Error(`subprocess-e2b: remote wrapper published invalid exit code ${JSON.stringify(rawStatus)}`)
+        }
+        const completed = await withinMs(settlement, this.spec.graceMs)
+        if (completed !== undefined) return this.commandOutcome(completed)
+        this.outputDrainExpired = true
+        this.stdoutReader?.invalidateSpill()
+        this.stderrReader?.invalidateSpill()
+        await handle.disconnect()
+        return { exitCode, signal: null }
       }
-      throw error
+      const completed = await Promise.race([settlement, waitTick().then(() => undefined)])
+      if (completed !== undefined) return this.commandOutcome(completed)
     }
   }
 
+  private commandOutcome(settlement: CommandSettlement): SubprocessOutcome {
+    if (settlement.kind === 'result') return { exitCode: settlement.result.exitCode, signal: null }
+    if (settlement.error instanceof CommandExitError) {
+      return this.terminationSignal === null
+        ? { exitCode: settlement.error.exitCode, signal: null }
+        : { exitCode: null, signal: this.terminationSignal }
+    }
+    throw settlement.error
+  }
+
   private async rollbackUnpublishedGroup(sandbox: Sandbox, handle: CommandHandle): Promise<void> {
     // The bootstrap ends in an exec chain through the scrubbed environment and
     // `setsid`, so E2B's command PID is the provisional group id even before the
@@ -433,35 +543,99 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async terminateRemote(): Promise<void> {
-    let handle: CommandHandle | undefined
-    try {
-      handle = await this.readyState.promise
-    } catch {
-      handle = this.commandHandle
-    }
+    const handle = await this.commandState.promise
     if (handle === undefined) return
-    const sandbox = await this.runtime.getSandbox()
-    const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
-    this.terminationSignal = 'SIGTERM'
-    await this.signalGroup(sandbox, processGroupId, 'TERM')
-    const deadline = Date.now() + this.spec.graceMs
-    while (Date.now() < deadline && await this.groupAlive(sandbox, processGroupId)) {
-      await waitTick()
+    if (!isValidProcessId(handle.pid) && this.remotePid <= 0) {
+      await handle.kill()
+      this.invalidHandleQuiescent = true
+      this.commandHandle = undefined
+      return
     }
-    if (!await this.groupAlive(sandbox, processGroupId)) return
-    this.terminationSignal = 'SIGKILL'
+    if (this.remotePid <= 0) {
+      const sandbox = await this.runtime.getSandbox()
+      this.terminationSignal = 'SIGTERM'
+      try {
+        const delivered = await this.signalGroup(sandbox, handle.pid, 'TERM')
+        if (delivered) {
+          const deadline = Date.now() + this.spec.graceMs
+          while (Date.now() < deadline && await this.groupAlive(sandbox, handle.pid)) await waitTick()
+          if (!await this.groupAlive(sandbox, handle.pid)) {
+            this.provisionalHandleQuiescent = true
+            return
+          }
+        }
+      } catch (_gracefulTerminationFailure) {
+        // A missing or unobservable provisional group still has the SDK handle fallback.
+      }
+      this.terminationSignal = 'SIGKILL'
+      let groupDelivered = false
+      let groupFailure: unknown
+      try {
+        groupDelivered = await this.signalGroup(sandbox, handle.pid, 'KILL')
+      } catch (error: unknown) {
+        groupFailure = error
+      }
+      let handleFailure: unknown
+      try {
+        await handle.kill()
+        this.provisionalHandleQuiescent = true
+      } catch (error: unknown) {
+        handleFailure = error
+      }
+      if (!groupDelivered && handleFailure !== undefined) {
+        throw new AggregateError(
+          [...(groupFailure === undefined ? [] : [groupFailure]), handleFailure],
+          'subprocess-e2b: force termination failed through both process-group and SDK transports',
+        )
+      }
+      return
+    }
+    const sandbox = await this.runtime.getSandbox()
+    const processGroupId = this.remotePid
+    this.terminationSignal = 'SIGTERM'
     try {
-      await this.signalGroup(sandbox, processGroupId, 'KILL')
-    } finally {
-      await handle.kill().catch(() => false)
+      await this.signalGroup(sandbox, processGroupId, 'TERM')
+      const deadline = Date.now() + this.spec.graceMs
+      while (Date.now() < deadline && await this.groupAlive(sandbox, processGroupId)) {
+        await waitTick()
+      }
+      if (!await this.groupAlive(sandbox, processGroupId)) return
+    } catch (_gracefulTerminationFailure) {
+      // Failed TERM delivery or observation cannot prove exit; force cleanup still owns the group.
+    }
+    this.terminationSignal = 'SIGKILL'
+    let groupFailure: unknown
+    let groupDelivered = false
+    try {
+      groupDelivered = await this.signalGroup(sandbox, processGroupId, 'KILL')
+    } catch (error: unknown) {
+      groupFailure = error
+    }
+    let handleFailure: unknown
+    try {
+      await handle.kill()
+    } catch (error: unknown) {
+      handleFailure = error
+    }
+    if (!groupDelivered && handleFailure !== undefined && await this.groupAlive(sandbox, processGroupId)) {
+      throw new AggregateError(
+        [...(groupFailure === undefined ? [] : [groupFailure]), handleFailure],
+        'subprocess-e2b: force termination failed through both process-group and SDK transports',
+      )
     }
   }
 
-  private async signalGroup(sandbox: Sandbox, pid: number, signal: 'TERM' | 'KILL'): Promise<void> {
+  private throwTerminationFailure(): void {
+    if (this.terminationFailure !== undefined) throw this.terminationFailure
+  }
+
+  private async signalGroup(sandbox: Sandbox, pid: number, signal: 'TERM' | 'KILL'): Promise<boolean> {
     try {
       await sandbox.commands.run(`kill -${signal} -- -${pid}`)
+      return true
     } catch (error: unknown) {
-      if (!(error instanceof CommandExitError)) throw error
+      if (error instanceof CommandExitError) return false
+      throw error
     }
   }
 
@@ -482,7 +656,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (!hasSpill(mode)) return
       // A spill mode is a collect mode, so construction always created its reader.
       const size = (reader as E2BOutputReader).size
-      if (size <= mode.maxBytes || size > mode.spill.maxBytes) {
+      if (this.outputDrainExpired || size <= mode.maxBytes || size > mode.spill.maxBytes) {
         removals.push(sandbox.files.remove(path).catch(() => {}))
       }
     }
@@ -490,4 +664,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     collect(this.spec.stdio.stderr, this.stderrReader, this.paths.stderr)
     await Promise.all(removals)
   }
+
+  private async removeFailedState(sandbox: Sandbox): Promise<void> {
+    const failures: Error[] = []
+    for (const path of [this.paths.environment, this.stateDir]) {
+      try {
+        await sandbox.files.remove(path)
+      } catch (error: unknown) {
+        if (!(error instanceof FileNotFoundError)) failures.push(asError(error))
+      }
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, 'subprocess-e2b: failed to remove private command state')
+    }
+  }
 }
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 7185899f79..fb8dac6f49 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -376,25 +376,26 @@ export async function spawnE2BTerminal(
     argv: posix.join(stateDir, 'argv'),
     ready: posix.join(stateDir, 'ready'),
   }
-  const ambient = await sandbox.commands.run('env -0', signalOpts(spec.signal))
-  const environment = remoteEnvironment(ambient.stdout, spec.env)
-  const argv = serializeValues(spec.argv, 'argv')
-  await sandbox.files.makeDir(stateDir)
-  await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stateDir)}`, signalOpts(spec.signal))
-  await sandbox.files.write([
-    { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
-    { path: paths.environment, data: environment },
-    { path: paths.argv, data: argv },
-  ], signalOpts(spec.signal))
-  await sandbox.commands.run(
-    `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)}`,
-    signalOpts(spec.signal),
-  )
-
   const output = new PassThrough()
   let handle: CommandHandle | undefined
   let completion: Promise<CommandResult> | undefined
+  let stateDirectoryCreated = false
   try {
+    const ambient = await sandbox.commands.run('env -0', signalOpts(spec.signal))
+    const environment = remoteEnvironment(ambient.stdout, spec.env)
+    const argv = serializeValues(spec.argv, 'argv')
+    await sandbox.files.makeDir(stateDir)
+    stateDirectoryCreated = true
+    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stateDir)}`, signalOpts(spec.signal))
+    await sandbox.files.write([
+      { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
+      { path: paths.environment, data: environment },
+      { path: paths.argv, data: argv },
+    ], signalOpts(spec.signal))
+    await sandbox.commands.run(
+      `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)}`,
+      signalOpts(spec.signal),
+    )
     handle = await sandbox.pty.create({
       rows: spec.rows,
       cols: spec.cols,
@@ -425,19 +426,25 @@ export async function spawnE2BTerminal(
     )
   } catch (error: unknown) {
     output.destroy()
-    let cleanupError: Error | undefined
+    const cleanupErrors: Error[] = []
     if (handle !== undefined && completion !== undefined) {
       try {
         await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
       } catch (rollbackError: unknown) {
-        cleanupError = asError(rollbackError)
+        cleanupErrors.push(asError(rollbackError))
       }
     } else if (handle !== undefined) {
       await handle.kill().catch(() => false)
     }
-    await sandbox.files.remove(stateDir).catch(() => {})
-    if (cleanupError !== undefined) {
-      throw new AggregateError([asError(error), cleanupError], asError(error).message)
+    if (stateDirectoryCreated) {
+      try {
+        await sandbox.files.remove(stateDir)
+      } catch (stateError: unknown) {
+        if (!(stateError instanceof FileNotFoundError)) cleanupErrors.push(asError(stateError))
+      }
+    }
+    if (cleanupErrors.length > 0) {
+      throw new AggregateError([asError(error), ...cleanupErrors], asError(error).message)
     }
     throw error
   }
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 32adf872b3..d81b49a600 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -2,6 +2,7 @@ import { once } from 'node:events'
 import { Context } from 'cordis'
 import {
   CommandExitError,
+  FileNotFoundError,
   type CommandHandle,
   type CommandResult,
   type Sandbox,
@@ -35,10 +36,14 @@ class FakeCommandHandle {
   readonly sent: Array<string | Uint8Array> = []
   closes = 0
   kills = 0
+  disconnects = 0
   killError: unknown
+  disconnectError: unknown
   private readonly result = Promise.withResolvers<CommandResult>()
   private settled = false
 
+  constructor(private readonly onKill: () => void = () => {}) {}
+
   wait(): Promise<CommandResult> {
     return this.result.promise
   }
@@ -54,9 +59,15 @@ class FakeCommandHandle {
   async kill(): Promise<boolean> {
     this.kills += 1
     if (this.killError !== undefined) throw this.killError
+    this.onKill()
     return true
   }
 
+  async disconnect(): Promise<void> {
+    this.disconnects += 1
+    if (this.disconnectError !== undefined) throw this.disconnectError
+  }
+
   succeed(exitCode = 0): void {
     if (this.settled) return
     this.settled = true
@@ -77,7 +88,7 @@ class FakeCommandHandle {
 }
 
 class FakeSandbox {
-  readonly handle = new FakeCommandHandle()
+  readonly handle: FakeCommandHandle
   readonly commandsSeen: string[] = []
   readonly writtenFiles: string[][] = []
   readonly writtenFileData = new Map<string, string>()
@@ -85,19 +96,35 @@ class FakeSandbox {
   readonly directories: string[] = []
   startOptions: StartOptions | undefined
   backgroundError: unknown
+  envError: unknown
   nextRemoveError: unknown
   probeError: unknown
   signalError: unknown
+  readonly signalErrors: unknown[] = []
   trapsTerm = false
   delaysKill = false
+  sdkKillStops = true
   alive = true
   ambient = 'PATH=/ambient/bin\0KEEP=safe\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   processGroupId = '4242\n'
+  exitStatus = ''
   readonly processGroupReads: string[] = []
+  afterStatusRead: (() => void) | undefined
   beforeProbe: (() => void) | undefined
   afterProbe: (() => void) | undefined
   private startGate: Promise<void> | undefined
   private openStart: (() => void) | undefined
+  private processGroupReadGate: Promise<void> | undefined
+  private openProcessGroupRead: (() => void) | undefined
+
+  constructor() {
+    this.handle = new FakeCommandHandle(() => {
+      if (this.sdkKillStops) {
+        this.alive = false
+        this.handle.fail(137)
+      }
+    })
+  }
 
   deferStart(): void {
     const gate = Promise.withResolvers<undefined>()
@@ -109,6 +136,16 @@ class FakeSandbox {
     this.openStart?.()
   }
 
+  deferProcessGroupRead(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.processGroupReadGate = gate.promise
+    this.openProcessGroupRead = () => { gate.resolve(undefined) }
+  }
+
+  releaseProcessGroupRead(): void {
+    this.openProcessGroupRead?.()
+  }
+
   finish(exitCode = 0): void {
     this.alive = false
     void this.completeOutput().then(
@@ -155,7 +192,14 @@ class FakeSandbox {
         for (const file of files) this.writtenFileData.set(file.path, file.data)
         return files.map(() => ({}))
       },
-      read: async (): Promise<string> => this.processGroupReads.shift() ?? this.processGroupId,
+      read: async (path: string): Promise<string> => {
+        if (!path.endsWith('/exit-code')) {
+          await this.processGroupReadGate
+          return this.processGroupReads.shift() ?? this.processGroupId
+        }
+        this.afterStatusRead?.()
+        return this.exitStatus
+      },
       remove: async (path: string): Promise<void> => {
         this.removed.push(path)
         if (this.nextRemoveError !== undefined) {
@@ -168,7 +212,10 @@ class FakeSandbox {
     commands: {
       run: async (command: string, options?: StartOptions | { signal?: AbortSignal }): Promise<CommandHandle | CommandResult> => {
         this.commandsSeen.push(command)
-        if (command === 'env -0') return { exitCode: 0, stdout: this.ambient, stderr: '' }
+        if (command === 'env -0') {
+          if (this.envError !== undefined) throw this.envError
+          return { exitCode: 0, stdout: this.ambient, stderr: '' }
+        }
         if (command.startsWith('kill -0 ')) {
           this.beforeProbe?.()
           if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
@@ -182,9 +229,9 @@ class FakeSandbox {
           return { exitCode: 0, stdout: '', stderr: '' }
         }
         if (command.startsWith('kill -TERM ')) {
-          if (this.signalError !== undefined) {
-            const error = this.signalError
-            this.signalError = undefined
+          const error = this.signalErrors.shift() ?? this.signalError
+          if (error !== undefined) {
+            if (this.signalErrors.length === 0) this.signalError = undefined
             throw error
           }
           if (!this.trapsTerm) {
@@ -194,9 +241,9 @@ class FakeSandbox {
           return { exitCode: 0, stdout: '', stderr: '' }
         }
         if (command.startsWith('kill -KILL ')) {
-          if (this.signalError !== undefined) {
-            const error = this.signalError
-            this.signalError = undefined
+          const error = this.signalErrors.shift() ?? this.signalError
+          if (error !== undefined) {
+            if (this.signalErrors.length === 0) this.signalError = undefined
             throw error
           }
           if (!this.delaysKill) this.alive = false
@@ -277,6 +324,8 @@ describe('E2BOutputReader', () => {
     expect(reader.readFrom(2)).toEqual({ text: 'cdef', nextOffset: 6, lossy: false })
     expect(reader.readFrom(5)).toEqual({ text: 'f', nextOffset: 6, lossy: false })
     expect(reader.readFrom(99)).toEqual({ text: '', nextOffset: 6, lossy: false })
+    reader.invalidateSpill()
+    expect(reader.readFrom(0)).toEqual({ text: 'cdef', nextOffset: 6, lossy: true })
   })
 
   it('drops whole head chunks and withholds absent or over-cap spills', () => {
@@ -390,6 +439,50 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).rejects.toThrow('incomplete output transport')
   })
 
+  it('bounds descendant-held output draining and withholds the incomplete spill', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-bound')
+    await flush()
+    await fake.stdout('leader-output')
+    fake.exitStatus = '0\n'
+
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(fake.handle.disconnects).toBe(1)
+    expect(handle.collected.stdout?.readFrom(0)).toEqual({
+      text: 'tput',
+      nextOffset: 13,
+      lossy: true,
+    })
+    expect(fake.removed).toContain('/runtime/drain-bound/stdout.log')
+
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
+  it('accepts clean encoder completion inside the output-drain grace', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-complete')
+    await flush()
+    fake.exitStatus = '0\n'
+    fake.afterStatusRead = () => {
+      fake.afterStatusRead = undefined
+      setTimeout(() => { fake.finish() }, 0)
+    }
+
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(fake.handle.disconnects).toBe(0)
+  })
+
+  it('rejects an invalid direct-command exit status', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/invalid-status')
+    await flush()
+    fake.exitStatus = '999\n'
+    await expect(handle.done).rejects.toThrow('invalid exit code')
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
   it('surfaces deferred piped-stdin write and close failures as stream errors', async () => {
     const writeFake = new FakeSandbox()
     writeFake.deferStart()
@@ -510,6 +603,97 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
+  it('kills through the provisional SDK handle before process-group publication', async () => {
+    const fake = new FakeSandbox()
+    fake.deferProcessGroupRead()
+    fake.signalErrors.push(commandError(1), commandError(1))
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/pre-publication-kill')
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
+
+    handle.terminate()
+    await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
+    expect(fake.alive).toBe(false)
+    await expect(handle.waitForExit()).resolves.toBe(true)
+
+    fake.releaseProcessGroupRead()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+  })
+
+  it('bounds a quiescence observer while provisional termination is awaiting the controller', async () => {
+    const fake = new FakeSandbox()
+    fake.deferProcessGroupRead()
+    const reconnect = Promise.withResolvers<Sandbox>()
+    let calls = 0
+    const delayedRuntime = runtime(fake, async () => {
+      calls += 1
+      return calls === 1 ? fake.sandbox : await reconnect.promise
+    })
+    const handle = new E2BSubprocessHandle(delayedRuntime, spec(), '/runtime/pre-publication-observer')
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
+    handle.terminate()
+
+    const controller = new AbortController()
+    const waiting = handle.waitForExit(controller.signal)
+    await flush()
+    controller.abort()
+    await expect(waiting).resolves.toBe(false)
+
+    reconnect.resolve(fake.sandbox)
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    fake.releaseProcessGroupRead()
+    await handle.done
+  })
+
+  it('proves a provisional group exit when the SDK kill fallback fails', async () => {
+    const fake = new FakeSandbox()
+    fake.deferProcessGroupRead()
+    fake.trapsTerm = true
+    fake.handle.killError = new Error('SDK kill unavailable')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-group-kill')
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
+
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    fake.releaseProcessGroupRead()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+  })
+
+  it('reports failed provisional group and SDK force transports', async () => {
+    const fake = new FakeSandbox()
+    fake.deferProcessGroupRead()
+    fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    fake.handle.killError = new Error('SDK kill failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-failure')
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
+
+    handle.terminate()
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+
+    fake.handle.killError = undefined
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    fake.releaseProcessGroupRead()
+    await handle.done
+
+    const absentGroup = new FakeSandbox()
+    absentGroup.deferProcessGroupRead()
+    absentGroup.signalErrors.push(commandError(1), commandError(1))
+    absentGroup.handle.killError = new Error('SDK kill failed without a provisional group')
+    const absentHandle = new E2BSubprocessHandle(
+      runtime(absentGroup),
+      spec({ graceMs: 1 }),
+      '/runtime/pre-publication-absent-group',
+    )
+    await vi.waitFor(() => { expect(absentGroup.startOptions).toBeDefined() })
+    absentHandle.terminate()
+    await expect(absentHandle.waitForExit()).rejects.toThrow('force termination failed through both')
+    absentGroup.handle.killError = undefined
+    absentHandle.terminate()
+    await expect(absentHandle.waitForExit()).resolves.toBe(true)
+    absentGroup.releaseProcessGroupRead()
+    await absentHandle.done
+  })
+
   it('honors an already-aborted signal when constructing the asynchronous handle directly', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({ signal: AbortSignal.abort('stop') }), '/runtime/pre-aborted')
@@ -559,6 +743,17 @@ describe('E2BSubprocessHandle', () => {
     await expect(liveWait).resolves.toBe(false)
     fake.finish()
     await handle.done
+
+    const terminatingFake = new FakeSandbox()
+    terminatingFake.deferStart()
+    const terminating = new E2BSubprocessHandle(runtime(terminatingFake), spec(), '/runtime/wait-termination-start')
+    terminating.terminate()
+    const beforeHandle = new AbortController()
+    const handlePending = terminating.waitForExit(beforeHandle.signal)
+    beforeHandle.abort()
+    await expect(handlePending).resolves.toBe(false)
+    terminatingFake.releaseStart()
+    await terminating.done
   })
 
   it('bounds both sides of the liveness-poll abort race', async () => {
@@ -580,6 +775,14 @@ describe('E2BSubprocessHandle', () => {
     const duringProbe = new AbortController()
     fake.beforeProbe = () => { duringProbe.abort(); fake.beforeProbe = undefined }
     await expect(handle.waitForExit(duringProbe.signal)).resolves.toBe(false)
+
+    let racedAbort = false
+    const raceSignal = {
+      get aborted() { return racedAbort },
+      addEventListener: () => { racedAbort = true },
+      removeEventListener: () => {},
+    } as unknown as AbortSignal
+    await expect(handle.waitForExit(raceSignal)).resolves.toBe(false)
     fake.finish()
     await handle.done
   })
@@ -599,8 +802,36 @@ describe('E2BSubprocessHandle', () => {
     const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/fail')
     await expect(handle.done).rejects.toThrow('start failed')
     expect(handle.pid).toBe(-1)
+    expect(fake.removed).toContain('/runtime/fail/environment')
+    expect(fake.removed).toContain('/runtime/fail')
     await expect(handle.waitForExit()).resolves.toBe(true)
     handle.terminate()
+
+    const unavailableHandle = new E2BSubprocessHandle(
+      runtime(new FakeSandbox(), async () => { throw new Error('sandbox unavailable') }),
+      spec(),
+      '/runtime/unavailable-start',
+    )
+    await expect(unavailableHandle.done).rejects.toThrow('sandbox unavailable')
+    await expect(unavailableHandle.waitForExit()).resolves.toBe(true)
+
+    const envFailure = new FakeSandbox()
+    envFailure.envError = new Error('ambient lookup failed')
+    const envHandle = new E2BSubprocessHandle(runtime(envFailure), spec(), '/runtime/env-failure')
+    await expect(envHandle.done).rejects.toThrow('ambient lookup failed')
+    expect(envFailure.removed).toEqual([])
+
+    const cleanupFailure = new FakeSandbox()
+    cleanupFailure.backgroundError = new Error('start failed before credential consumption')
+    cleanupFailure.nextRemoveError = new Error('credential cleanup failed')
+    const cleanupHandle = new E2BSubprocessHandle(runtime(cleanupFailure), spec(), '/runtime/cleanup-failure')
+    await expect(cleanupHandle.done).rejects.toThrow('command failed and private state cleanup failed')
+
+    const absentState = new FakeSandbox()
+    absentState.backgroundError = new Error('start failed after external cleanup')
+    absentState.nextRemoveError = new FileNotFoundError('already removed')
+    const absentHandle = new E2BSubprocessHandle(runtime(absentState), spec(), '/runtime/absent-state')
+    await expect(absentHandle.done).rejects.toThrow('start failed after external cleanup')
   })
 
   it('bounds a readiness rejection with a still-live caller signal', async () => {
@@ -678,8 +909,20 @@ describe('E2BSubprocessHandle', () => {
     invalidPid.handle.pid = 0
     const invalid = new E2BSubprocessHandle(runtime(invalidPid), spec(), '/runtime/invalid-pid')
     await expect(invalid.done).rejects.toThrow(/invalid command pid 0/)
+    expect(invalidPid.handle.kills).toBe(1)
+    expect(invalidPid.removed).toContain('/runtime/invalid-pid/environment')
     await expect(invalid.waitForExit()).resolves.toBe(true)
 
+    const failedRollback = new FakeSandbox()
+    failedRollback.handle.pid = 0
+    failedRollback.handle.killError = new Error('invalid handle kill failed')
+    const retained = new E2BSubprocessHandle(runtime(failedRollback), spec(), '/runtime/invalid-pid-retained')
+    await expect(retained.done).rejects.toThrow('invalid command pid rollback did not reach quiescence')
+    await expect(retained.waitForExit()).rejects.toThrow('invalid handle kill failed')
+    failedRollback.handle.killError = undefined
+    retained.terminate()
+    await expect(retained.waitForExit()).resolves.toBe(true)
+
     const crashedFake = new FakeSandbox()
     const crashed = new E2BSubprocessHandle(runtime(crashedFake), spec(), '/runtime/crashed')
     await flush()
@@ -692,6 +935,7 @@ describe('E2BSubprocessHandle', () => {
     const invalidGroup = new FakeSandbox()
     invalidGroup.processGroupId = 'not-a-pid\n'
     invalidGroup.delaysKill = true
+    invalidGroup.sdkKillStops = false
     invalidGroup.afterProbe = () => { invalidGroup.alive = false }
     const invalid = new E2BSubprocessHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
     await expect(invalid.done).rejects.toThrow(/invalid process-group id/)
@@ -791,7 +1035,7 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
   })
 
-  it('contains an already-gone group signal and observes non-command signal failures', async () => {
+  it('contains an already-gone group signal and escalates after a TERM transport failure', async () => {
     const gone = new FakeSandbox()
     gone.trapsTerm = true
     gone.signalError = commandError(1)
@@ -805,9 +1049,35 @@ describe('E2BSubprocessHandle', () => {
     const failedHandle = new E2BSubprocessHandle(runtime(failed), spec(), '/runtime/failed-signal')
     await flush()
     failedHandle.terminate()
+    await expect(failedHandle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    expect(failed.commandsSeen).toContain('kill -KILL -- -4242')
+  })
+
+  it('allows termination retry after both force transports fail', async () => {
+    const fake = new FakeSandbox()
+    fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    fake.handle.killError = new Error('SDK kill failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry-signal')
     await flush()
-    failed.finish()
-    await expect(failedHandle.done).resolves.toEqual({ exitCode: 0, signal: null })
+
+    handle.terminate()
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    fake.handle.killError = undefined
+    handle.terminate()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    expect(fake.commandsSeen.filter(command => command.startsWith('kill -TERM '))).toHaveLength(2)
+
+    const missingGroup = new FakeSandbox()
+    missingGroup.trapsTerm = true
+    missingGroup.signalErrors.push(undefined, commandError(1))
+    missingGroup.handle.killError = new Error('SDK kill failed after group exit race')
+    const raced = new E2BSubprocessHandle(runtime(missingGroup), spec({ graceMs: 1 }), '/runtime/group-exit-race')
+    await flush()
+    raced.terminate()
+    await expect(raced.waitForExit()).rejects.toThrow('force termination failed through both')
+    missingGroup.handle.killError = undefined
+    raced.terminate()
+    await expect(raced.waitForExit()).resolves.toBe(true)
   })
 })
 
@@ -833,6 +1103,23 @@ describe('E2BSubprocessService', () => {
     expect(fake.alive).toBe(false)
   })
 
+  it('reports a failed termination transaction from disposal instead of waiting on done', async () => {
+    const fake = new FakeSandbox()
+    fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    fake.handle.killError = new Error('SDK kill failed')
+    const { ctx, fiber } = await service(fake)
+    const handle = ctx.subprocess.spawn(spec({ graceMs: 1 }))
+    await flush()
+
+    await expect(fiber.dispose()).resolves.toBeUndefined()
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+
+    fake.handle.killError = undefined
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+  })
+
   it('releases naturally settled handles before later service disposal', async () => {
     const fake = new FakeSandbox()
     const { ctx, fiber } = await service(fake)
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index cefa432acd..bda01a5a61 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -95,6 +95,7 @@ class FakeTerminalSandbox {
   foreground = '456\n'
   groups = [123]
   createError: unknown
+  writeError: unknown
   sendError: unknown
   commandFailure: unknown
   sessionGroupsFailure: unknown
@@ -116,6 +117,7 @@ class FakeTerminalSandbox {
       },
       write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
         for (const file of files) this.writes.set(file.path, file.data)
+        if (this.writeError !== undefined) throw this.writeError
         return files.map(() => ({}))
       },
       read: async (): Promise<string> => {
@@ -278,6 +280,20 @@ describe('E2B terminal allocation', () => {
   })
 
   it('cleans malformed handles, bootstrap failures, and readiness failures', async () => {
+    const failedState = new FakeTerminalSandbox()
+    failedState.writeError = new Error('state write failed')
+    await expect(spawnE2BTerminal(runtime(failedState), spec(), '/runtime/state-write'))
+      .rejects.toThrow('state write failed')
+    expect(failedState.writes.get('/runtime/state-write/environment')).toContain('KEEP=visible\0')
+    expect(failedState.removed).toContain('/runtime/state-write')
+    expect(failedState.createOptions).toBeUndefined()
+
+    const stateAlreadyGone = new FakeTerminalSandbox()
+    stateAlreadyGone.writeError = new Error('state write failed after external cleanup')
+    stateAlreadyGone.removeError = new FileNotFoundError('state already gone')
+    await expect(spawnE2BTerminal(runtime(stateAlreadyGone), spec(), '/runtime/state-gone'))
+      .rejects.toThrow('state write failed after external cleanup')
+
     const invalidPid = new FakeTerminalSandbox()
     invalidPid.handle.pid = 0
     await expect(spawnE2BTerminal(runtime(invalidPid), spec(), '/runtime/invalid-pid'))

From e9bef2967dcd6c399637482f8cb1739cf90bf6e0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 07:07:31 +0800
Subject: [PATCH 367/516] fix(e2b): preserve signals after output drain

---
 packages/e2b/subprocess-e2b/src/process.ts    |  4 +++-
 .../subprocess-e2b/tests/subprocess.spec.ts   | 22 ++++++++++++++++++-
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 3a8047eb54..473c1a0af4 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -512,7 +512,9 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         this.stdoutReader?.invalidateSpill()
         this.stderrReader?.invalidateSpill()
         await handle.disconnect()
-        return { exitCode, signal: null }
+        return this.terminationSignal === null
+          ? { exitCode, signal: null }
+          : { exitCode: null, signal: this.terminationSignal }
       }
       const completed = await Promise.race([settlement, waitTick().then(() => undefined)])
       if (completed !== undefined) return this.commandOutcome(completed)
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index d81b49a600..457e68f24d 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -103,6 +103,7 @@ class FakeSandbox {
   readonly signalErrors: unknown[] = []
   trapsTerm = false
   delaysKill = false
+  delaysKillCompletion = false
   sdkKillStops = true
   alive = true
   ambient = 'PATH=/ambient/bin\0KEEP=safe\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
@@ -247,7 +248,7 @@ class FakeSandbox {
             throw error
           }
           if (!this.delaysKill) this.alive = false
-          this.handle.fail(137)
+          if (!this.delaysKillCompletion) this.handle.fail(137)
           return { exitCode: 0, stdout: '', stderr: '' }
         }
         if ((options as StartOptions | undefined)?.background === true) {
@@ -473,6 +474,25 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.handle.disconnects).toBe(0)
   })
 
+  it('preserves a requested signal when output draining expires', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    fake.delaysKill = true
+    fake.delaysKillCompletion = true
+    fake.sdkKillStops = false
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-signal')
+    await flush()
+
+    handle.terminate()
+    await vi.waitFor(() => { expect(fake.commandsSeen).toContain('kill -KILL -- -4242') })
+    fake.exitStatus = '143\n'
+
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    expect(fake.handle.disconnects).toBe(1)
+    fake.alive = false
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
   it('rejects an invalid direct-command exit status', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/invalid-status')

From 022841027fb05a18c5567095d6fed88aebb9ad00 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 07:42:25 +0800
Subject: [PATCH 368/516] fix(e2b): fence teardown and terminal publication

---
 packages/e2b/e2b/tests/composition.e2e.ts     |  5 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         |  4 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  4 +-
 packages/e2b/subprocess-e2b/src/index.ts      | 42 +++++++--
 packages/e2b/subprocess-e2b/src/process.ts    |  4 +-
 packages/e2b/subprocess-e2b/src/terminal.ts   | 82 ++++++++++++++++-
 .../subprocess-e2b/tests/subprocess.spec.ts   | 25 ++++++
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 89 ++++++++++++++++++-
 9 files changed, 237 insertions(+), 22 deletions(-)

diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 1ece44bb6a..34875d5153 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -185,7 +185,10 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       oversizedReply: { error: { kind: 'worker-exit' } },
       lingeringCodeRunners: 0,
     })
-    expect((output.terminal as { motd: string }).motd.length).toBeGreaterThan(0)
+    const terminalMotd = (output.terminal as { motd: string }).motd
+    expect(terminalMotd.length).toBeGreaterThan(0)
+    expect(terminalMotd).not.toContain('exec /bin/bash')
+    expect(terminalMotd).not.toContain('.dsh-e2b/terminals/')
     expect((output.terminal as { echo: { viewport: string } }).echo.viewport).toContain('PTY-你好')
     expect((output.terminal as { scrollback: string }).scrollback).toContain('PTY-你好')
     expect((output.terminal as { signal: { targetPgid: number } }).signal.targetPgid).toBeGreaterThan(0)
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 091a6972cf..2d20e4ad4c 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: b1aa480305fef9ca485340b6bdae50f9fcffd88f
-README.zh.md: b4824c90e7fb908d9c12e77c19d2b952055dcb40
+README.md: 03146e02cc76b78fbb93faec7d36d1865418b670
+README.zh.md: 6ed49a355586c6df2a594f83b687e6a565d07cf0
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index b1aa480305..fb3d79433f 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -8,10 +8,10 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication, while cancellation can stop the provisional SDK handle first.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. Service disposal terminates and joins every retained handle before the sandbox owner disposes.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried, while successful termination remains a permanent no-op. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers; after `graceMs`, the adapter disconnects an incomplete SDK stream, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. Setup and teardown own the private state transaction, including failure cleanup. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, fence publication during service disposal, and include failure cleanup. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
 The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index b4824c90e7..ec012b6a05 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -8,10 +8,10 @@
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布，而取消操作可以先停止临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。服务 dispose（资源释放）会在沙箱所有者释放前终止并等待每个保留句柄退出。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试；成功终止后，重复终止将永久为空操作。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态；超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。setup 与 teardown 负责私有状态事务，包括失败清理。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间阻止发布，并包括失败清理。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
 基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 27efb216da..fcf2c6f0a4 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -28,6 +28,8 @@ export class E2BSubprocessService extends SubprocessService {
 
   private readonly live = new Set<E2BSubprocessHandle>()
   private readonly terminals = new Set<SubprocessTerminalHandle>()
+  private readonly terminalSetups = new Set<Promise<void>>()
+  private disposing = false
 
   /** @inheritdoc */
   readonly cwd: string
@@ -41,12 +43,17 @@ export class E2BSubprocessService extends SubprocessService {
     this.cwd = ctx.e2b.cwd
     this.runtimeRoot = ctx.e2b.runtimeRoot
     ctx.effect(() => async () => {
+      this.disposing = true
+      await Promise.all([...this.terminalSetups])
       const handles = [...this.live]
       const terminals = [...this.terminals]
       const pending: Promise<unknown>[] = []
       for (const handle of handles) {
         handle.terminate()
-        pending.push(handle.waitForExit().then(() => { this.live.delete(handle) }))
+        pending.push(handle.waitForExit().then(async () => {
+          await handle.done.catch(() => undefined)
+          this.live.delete(handle)
+        }))
       }
       for (const terminal of terminals) {
         terminal.terminate()
@@ -89,6 +96,7 @@ export class E2BSubprocessService extends SubprocessService {
 
   /** @inheritdoc */
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
+    if (this.isDisposing()) throw new Error('subprocess-e2b: service is disposing')
     const program = spec.argv[0]
     if (program === undefined || program.length === 0) {
       throw new Error('invalid argv: expected a non-empty program name at argv[0]')
@@ -112,6 +120,7 @@ export class E2BSubprocessService extends SubprocessService {
 
   /** @inheritdoc */
   async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    if (this.isDisposing()) throw new Error('subprocess-e2b: service is disposing')
     const program = spec.argv[0]
     if (program === undefined || program.length === 0) {
       throw new Error('subprocess-e2b: terminal argv must contain a program')
@@ -123,14 +132,31 @@ export class E2BSubprocessService extends SubprocessService {
     }
     spec.signal?.throwIfAborted()
     const stateDir = posix.join(this.runtimeRoot, 'terminals', randomUUID())
-    const terminal = await spawnE2BTerminal(this.ctx.e2b, spec, stateDir)
-    this.terminals.add(terminal)
-    const release = async (): Promise<void> => {
-      await terminal.waitForExit()
-      this.terminals.delete(terminal)
+    const setup = Promise.withResolvers<void>()
+    this.terminalSetups.add(setup.promise)
+    try {
+      const terminal = await spawnE2BTerminal(this.ctx.e2b, spec, stateDir)
+      this.terminals.add(terminal)
+      if (this.isDisposing()) {
+        terminal.terminate()
+        await terminal.waitForExit()
+        this.terminals.delete(terminal)
+        throw new Error('subprocess-e2b: service disposed during terminal setup')
+      }
+      const release = async (): Promise<void> => {
+        await terminal.waitForExit()
+        this.terminals.delete(terminal)
+      }
+      void terminal.done.then(release, release).catch(() => {})
+      return terminal
+    } finally {
+      this.terminalSetups.delete(setup.promise)
+      setup.resolve()
     }
-    void terminal.done.then(release, release).catch(() => {})
-    return terminal
+  }
+
+  private isDisposing(): boolean {
+    return this.disposing
   }
 }
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 473c1a0af4..3038f312dc 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -213,6 +213,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private invalidHandleQuiescent = false
   private provisionalHandleQuiescent = false
   private terminationStarted = false
+  private terminationSucceeded = false
   private terminationAttempt: Promise<void> | undefined
   private terminationFailure: Error | undefined
   private terminationSignal: NodeJS.Signals | null = null
@@ -264,13 +265,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    if (this.terminationAttempt !== undefined) return
+    if (this.terminationSucceeded || this.terminationAttempt !== undefined) return
     this.terminationStarted = true
     this.terminationFailure = undefined
     const attempt = this.terminateRemote()
     this.terminationAttempt = attempt
     void attempt.then(
       () => {
+        this.terminationSucceeded = true
         this.terminationAttempt = undefined
       },
       (error: unknown) => {
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index fb8dac6f49..78668490d7 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -1,6 +1,7 @@
 /** E2B PTY allocation and process-session ownership for the subprocess seam. */
 
 import { Buffer } from 'node:buffer'
+import { randomUUID } from 'node:crypto'
 import { PassThrough } from 'node:stream'
 import { posix } from 'node:path'
 import {
@@ -28,11 +29,13 @@ const TERMINAL_RUNNER_SOURCE = [
   'dsh_state=$1',
   'mapfile -d \'\' -t dsh_env < "$dsh_state/environment"',
   'mapfile -d \'\' -t dsh_argv < "$dsh_state/argv"',
-  'rm -f -- "$dsh_state/environment" "$dsh_state/argv" "$dsh_state/runner.bash"',
+  'dsh_output_marker=$(<"$dsh_state/output-marker")',
+  'rm -f -- "$dsh_state/environment" "$dsh_state/argv" "$dsh_state/output-marker" "$dsh_state/runner.bash"',
   'if (( ${#dsh_argv[@]} == 0 )); then',
   "  printf 'terminal runner received empty argv\\n' >&2",
   '  exit 125',
   'fi',
+  'printf \'%s\' "$dsh_output_marker"',
   "printf 'ready\\n' > \"$dsh_state/ready\"",
   'exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"',
   '',
@@ -42,6 +45,7 @@ interface TerminalPaths {
   runner: string
   environment: string
   argv: string
+  outputMarker: string
   ready: string
 }
 
@@ -53,6 +57,73 @@ function delay(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms))
 }
 
+class BootstrapOutputFilter {
+  readonly ready: Promise<void>
+
+  private readonly readyState = Promise.withResolvers<void>()
+  private pending = Buffer.alloc(0)
+  private published = false
+
+  constructor(
+    private readonly marker: Buffer,
+    private readonly output: PassThrough,
+  ) {
+    this.ready = this.readyState.promise
+  }
+
+  push(data: Uint8Array): void {
+    if (this.published) {
+      this.write(data)
+      return
+    }
+    const combined = Buffer.concat([this.pending, Buffer.from(data)])
+    const markerOffset = combined.indexOf(this.marker)
+    if (markerOffset < 0) {
+      const retained = Math.min(combined.length, this.marker.length - 1)
+      this.pending = Buffer.from(combined.subarray(combined.length - retained))
+      return
+    }
+    this.published = true
+    this.pending = Buffer.alloc(0)
+    this.readyState.resolve()
+    this.write(combined.subarray(markerOffset + this.marker.length))
+  }
+
+  private write(data: Uint8Array): void {
+    if (data.length > 0 && !this.output.destroyed) this.output.write(data)
+  }
+}
+
+async function waitForBootstrapOutput(
+  ready: Promise<void>,
+  completion: Promise<CommandResult>,
+  signal?: AbortSignal,
+): Promise<void> {
+  signal?.throwIfAborted()
+  await new Promise<void>((resolve, reject) => {
+    let settled = false
+    let removeAbort: (() => void) | undefined
+    const finish = (complete: () => void): void => {
+      if (settled) return
+      settled = true
+      removeAbort?.()
+      complete()
+    }
+    const onExit = (): void => {
+      finish(() => { reject(new Error('subprocess-e2b: terminal exited before publishing its output boundary')) })
+    }
+    if (signal !== undefined) {
+      const onAbort = (): void => {
+        finish(() => { reject(asError(signal.reason)) })
+      }
+      signal.addEventListener('abort', onAbort, { once: true })
+      removeAbort = () => { signal.removeEventListener('abort', onAbort) }
+    }
+    void ready.then(() => { finish(resolve) })
+    void completion.then(onExit, onExit)
+  })
+}
+
 function asError(error: unknown): Error {
   return error instanceof Error ? error : new Error(String(error))
 }
@@ -374,9 +445,12 @@ export async function spawnE2BTerminal(
     runner: posix.join(stateDir, 'runner.bash'),
     environment: posix.join(stateDir, 'environment'),
     argv: posix.join(stateDir, 'argv'),
+    outputMarker: posix.join(stateDir, 'output-marker'),
     ready: posix.join(stateDir, 'ready'),
   }
+  const outputMarker = Buffer.from(`dsh-e2b-bootstrap:${randomUUID()}`)
   const output = new PassThrough()
+  const outputFilter = new BootstrapOutputFilter(outputMarker, output)
   let handle: CommandHandle | undefined
   let completion: Promise<CommandResult> | undefined
   let stateDirectoryCreated = false
@@ -391,9 +465,10 @@ export async function spawnE2BTerminal(
       { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
       { path: paths.environment, data: environment },
       { path: paths.argv, data: argv },
+      { path: paths.outputMarker, data: outputMarker.toString('utf8') },
     ], signalOpts(spec.signal))
     await sandbox.commands.run(
-      `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)}`,
+      `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)} ${quoteE2BShellArg(paths.outputMarker)}`,
       signalOpts(spec.signal),
     )
     handle = await sandbox.pty.create({
@@ -403,7 +478,7 @@ export async function spawnE2BTerminal(
       envs: { TERM: 'dumb' },
       timeoutMs: 0,
       ...signalOpts(spec.signal),
-      onData: (data) => { if (!output.destroyed) output.write(Buffer.from(data)) },
+      onData: (data) => { outputFilter.push(data) },
     })
     completion = handle.wait()
     void completion.catch(() => {})
@@ -413,6 +488,7 @@ export async function spawnE2BTerminal(
     const command = `exec /bin/bash ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(stateDir)}\r`
     await sandbox.pty.sendInput(handle.pid, Buffer.from(command), signalOpts(spec.signal))
     await waitUntilReady(sandbox, paths, completion, spec.signal)
+    await waitForBootstrapOutput(outputFilter.ready, completion, spec.signal)
     const sessionId = await terminalSessionId(sandbox, handle.pid, spec.signal)
     return new E2BTerminalHandle(
       sandbox,
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 457e68f24d..be8850d905 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -599,6 +599,12 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
     expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
     expect(fake.commandsSeen).not.toContain('kill -KILL -- -4242')
+    const signals = fake.commandsSeen.filter(command => command.startsWith('kill -')).length
+    fake.alive = true
+    handle.terminate()
+    await flush()
+    expect(fake.alive).toBe(true)
+    expect(fake.commandsSeen.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
   })
 
   it('escalates a TERM-trapping process group to KILL and uses the SDK kill as fallback', async () => {
@@ -1123,6 +1129,24 @@ describe('E2BSubprocessService', () => {
     expect(fake.alive).toBe(false)
   })
 
+  it('awaits SDK settlement after the remote process group becomes quiescent', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    const { ctx, fiber } = await service(fake)
+    const handle = ctx.subprocess.spawn(spec())
+    await flush()
+    fake.alive = false
+
+    let disposed = false
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await flush()
+    expect(disposed).toBe(false)
+
+    fake.finish()
+    await disposing
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
   it('reports a failed termination transaction from disposal instead of waiting on done', async () => {
     const fake = new FakeSandbox()
     fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
@@ -1178,6 +1202,7 @@ describe('E2BSubprocessService', () => {
     const { ctx, fiber } = await service(fake)
     const handle = ctx.subprocess.spawn(spec())
     const disposing = fiber.dispose()
+    expect(() => ctx.subprocess.spawn(spec())).toThrow('service is disposing')
     fake.releaseStart()
     await expect(disposing).resolves.toBeUndefined()
     await expect(handle.done).rejects.toThrow('start failed during disposal')
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index bda01a5a61..1eac9a5780 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -2,7 +2,7 @@ import { Buffer } from 'node:buffer'
 import { once } from 'node:events'
 import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import {
   CommandExitError,
   FileNotFoundError,
@@ -91,6 +91,7 @@ class FakeTerminalSandbox {
   ambient = 'KEEP=visible\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   ready: string | Error = 'ready\n'
   readyMisses = 0
+  readyReads = 0
   sessionId = '123\n'
   foreground = '456\n'
   groups = [123]
@@ -108,6 +109,20 @@ class FakeTerminalSandbox {
   settleOnPtyKill = true
   ptyKills = 0
   resolvedExecutable = '/usr/bin/node\n'
+  requestedOutput = 'requested-shell$ '
+  emitOutputMarker = true
+  private createGate: Promise<void> | undefined
+  private releaseCreateGate: (() => void) | undefined
+
+  deferCreate(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.createGate = gate.promise
+    this.releaseCreateGate = () => { gate.resolve(undefined) }
+  }
+
+  releaseCreate(): void {
+    this.releaseCreateGate?.()
+  }
 
   readonly sandbox = {
     files: {
@@ -121,6 +136,7 @@ class FakeTerminalSandbox {
         return files.map(() => ({}))
       },
       read: async (): Promise<string> => {
+        this.readyReads += 1
         if (this.readyMisses > 0) {
           this.readyMisses -= 1
           throw new FileNotFoundError('not ready')
@@ -170,6 +186,7 @@ class FakeTerminalSandbox {
     pty: {
       create: async (options: Parameters<Sandbox['pty']['create']>[0]): Promise<CommandHandle> => {
         this.createOptions = options
+        await this.createGate
         if (this.createError !== undefined) throw this.createError
         await options.onData(Buffer.from('buffered banner\n'))
         return this.handle.asHandle()
@@ -178,6 +195,17 @@ class FakeTerminalSandbox {
         options?.signal?.throwIfAborted()
         this.inputs.push({ pid, data: Buffer.from(data) })
         if (this.sendError !== undefined) throw this.sendError
+        if (this.emitOutputMarker && Buffer.from(data).includes(Buffer.from('runner.bash'))) {
+          const marker = [...this.writes].find(([path]) => path.endsWith('/output-marker'))?.[1]
+          const onData = this.createOptions?.onData
+          if (marker !== undefined && onData !== undefined) {
+            await onData(Buffer.from(Buffer.from(data).toString().replace(/\r$/, '\r\n')))
+            const split = Math.floor(marker.length / 2)
+            await onData(Buffer.from(marker.slice(0, split)))
+            await onData(Buffer.from(marker.slice(split)))
+            await onData(Buffer.from(this.requestedOutput))
+          }
+        }
       },
       kill: async (pid: number): Promise<boolean> => {
         this.ptyKills += 1
@@ -211,7 +239,7 @@ function spec(overrides: Partial<SubprocessTerminalSpawnSpec> = {}): SubprocessT
 }
 
 describe('E2B terminal allocation', () => {
-  it('boots the requested argv through a private runner and preserves buffered bytes', async () => {
+  it('hides bootstrap-shell bytes and preserves requested-shell bytes across the output boundary', async () => {
     const fake = new FakeTerminalSandbox()
     fake.readyMisses = 1
     const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/terminal-one')
@@ -219,7 +247,9 @@ describe('E2B terminal allocation', () => {
     terminal.output.on('data', (chunk) => { output += String(chunk) })
     await new Promise(resolve => setTimeout(resolve, 0))
 
-    expect(output).toBe('buffered banner\n')
+    expect(output).toBe('requested-shell$ ')
+    expect(output).not.toContain('buffered banner')
+    expect(output).not.toContain('runner.bash')
     expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0, envs: { TERM: 'dumb' } })
     expect(fake.inputs[0]?.data.toString()).toContain("exec /bin/bash '/runtime/terminal-one/runner.bash'")
     expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('KEEP=visible\0')
@@ -227,10 +257,17 @@ describe('E2B terminal allocation', () => {
     expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('secret')
     expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('DSH_STALE')
     expect(fake.writes.get('/runtime/terminal-one/argv')).toBe('/bin/bash\0--noprofile\0--norc\0')
+    const marker = fake.writes.get('/runtime/terminal-one/output-marker') ?? ''
+    expect(marker).toMatch(/^dsh-e2b-bootstrap:/)
+    expect(fake.inputs[0]?.data.toString()).not.toContain(marker)
     const runner = fake.writes.get('/runtime/terminal-one/runner.bash') ?? ''
     expect(runner).toContain('if (( ${#dsh_argv[@]} == 0 )); then')
+    expect(runner).toContain('printf \'%s\' "$dsh_output_marker"')
     expect(runner).toContain('exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"')
     expect(runner).not.toContain('\u007f')
+    terminal.output.destroy()
+    await fake.createOptions?.onData(Buffer.from('late bootstrap callback'))
+    expect(output).toBe('requested-shell$ ')
 
     await terminal.write(Buffer.from('echo ok\r'))
     expect(fake.inputs.at(-1)?.data.toString()).toBe('echo ok\r')
@@ -395,6 +432,29 @@ describe('E2B terminal allocation', () => {
     await expect(spawnE2BTerminal(runtime(readFailed), spec(), '/runtime/read'))
       .rejects.toThrow('ready transport failed')
   })
+
+  it('bounds a missing bootstrap-output boundary by process exit or cancellation', async () => {
+    const exited = new FakeTerminalSandbox()
+    exited.emitOutputMarker = false
+    const exiting = spawnE2BTerminal(runtime(exited), spec(), '/runtime/missing-output-boundary')
+    await vi.waitFor(() => { expect(exited.inputs).toHaveLength(1) })
+    exited.handle.succeed(0)
+    await expect(exiting).rejects.toThrow('terminal exited before publishing its output boundary')
+
+    const cancelled = new FakeTerminalSandbox()
+    cancelled.emitOutputMarker = false
+    const controller = new AbortController()
+    const cancelling = spawnE2BTerminal(
+      runtime(cancelled),
+      spec({ signal: controller.signal }),
+      '/runtime/cancel-output-boundary',
+    )
+    await vi.waitFor(() => { expect(cancelled.inputs).toHaveLength(1) })
+    await vi.waitFor(() => { expect(cancelled.readyReads).toBeGreaterThan(0) })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    controller.abort(new Error('cancel output boundary'))
+    await expect(cancelling).rejects.toThrow('cancel output boundary')
+  })
 })
 
 describe('E2B terminal lifecycle', () => {
@@ -637,6 +697,29 @@ describe('E2B subprocess terminal service', () => {
     expect(fake.handle.disconnects).toBe(1)
   })
 
+  it('joins and rejects terminal setup that completes during service disposal', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.deferCreate()
+    const { ctx, fiber } = await service(fake)
+    const spawning = ctx.subprocess.spawnTerminal(spec())
+    const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
+    await vi.waitFor(() => { expect(fake.createOptions).toBeDefined() })
+
+    let disposed = false
+    const subprocess = ctx.subprocess
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(disposed).toBe(false)
+    await expect(subprocess.spawnTerminal(spec())).rejects.toThrow('service is disposing')
+    fake.releaseCreate()
+
+    await rejected
+    await disposing
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+    expect(fake.removed.some(path => path.includes('/terminals/'))).toBe(true)
+  })
+
   it('releases naturally settled terminals and validates terminal requests', async () => {
     const { ctx, fiber, fake } = await service()
     for (const request of [

From ed5d21277faa85ad97cf4fbe17ee62e3ca1bfdb8 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:05:37 +0800
Subject: [PATCH 369/516] test(e2b): observe disposal before spawn fence

---
 packages/e2b/subprocess-e2b/tests/subprocess.spec.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index be8850d905..8e6e420bcc 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -1200,9 +1200,11 @@ describe('E2BSubprocessService', () => {
     fake.deferStart()
     fake.backgroundError = new Error('start failed during disposal')
     const { ctx, fiber } = await service(fake)
-    const handle = ctx.subprocess.spawn(spec())
+    const subprocess = ctx.subprocess
+    const handle = subprocess.spawn(spec())
     const disposing = fiber.dispose()
-    expect(() => ctx.subprocess.spawn(spec())).toThrow('service is disposing')
+    await flush()
+    expect(() => subprocess.spawn(spec())).toThrow('service is disposing')
     fake.releaseStart()
     await expect(disposing).resolves.toBeUndefined()
     await expect(handle.done).rejects.toThrow('start failed during disposal')

From f5306f6e898c797900c66d1441ce0f7729007732 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:06:02 +0800
Subject: [PATCH 370/516] docs(e2b): record subprocess teardown contract

---
 packages/e2b/subprocess-e2b/README.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 2d20e4ad4c..3a577227f8 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 03146e02cc76b78fbb93faec7d36d1865418b670
-README.zh.md: 6ed49a355586c6df2a594f83b687e6a565d07cf0
+README.md: fb3d79433fba8bb86097cffb09a257ad5756cc2b
+README.zh.md: ec012b6a05c1a5f911d5ede9730f0f7207d5a645

From 219999cd2f3e0abf3878d354de3bf42cfc2e6134 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 09:19:46 +0800
Subject: [PATCH 371/516] fix(e2b): close adapter lifecycle review gaps

---
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   2 +-
 packages/e2b/fs-e2b/README.zh.md              |   2 +-
 packages/e2b/fs-e2b/src/index.ts              |  24 ++-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |  33 +++-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |  10 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  10 +-
 .../e2b/subprocess-e2b/src/environment.ts     |  20 +++
 packages/e2b/subprocess-e2b/src/index.ts      |  25 ++-
 packages/e2b/subprocess-e2b/src/process.ts    |  67 +++++---
 packages/e2b/subprocess-e2b/src/terminal.ts   |  61 ++++----
 .../subprocess-e2b/tests/subprocess.spec.ts   | 146 +++++++++++++++++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  70 ++++++---
 14 files changed, 375 insertions(+), 103 deletions(-)

diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 6e45ccaaf6..3c2b30ad15 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: 86ad8720d3e4c7ce70ee0ac8c41713af03ed297a
-README.zh.md: 90dff57a5b9fe786aea3315633125536277ecc20
+README.md: 8abf130ce16e2b79cda5fc858182159442f9e3c3
+README.zh.md: 943d9603046ad9b2a65f41d5801cac882040a0ff
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index 86ad8720d3..8abf130ce1 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -10,7 +10,7 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 - **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
 - **Stable bounded reads** — a dependency-free Node helper walks directory descriptors with no-follow opens and reads one held regular-file descriptor through the byte cap. Generic LSP queries therefore reject parent swaps, non-files, invalid UTF-8, and growth past the configured document limit before server startup.
-- **Atomic mutations** — writes upload a mode-`0600` temporary sibling, preserve an existing file's POSIX mode, and publish through E2B's same-directory atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
+- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at SDK request boundaries; a successful rename is the commit point.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 90dff57a5b..943d960304 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -10,7 +10,7 @@
 - **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
 - **稳定的有界读取**：一个零依赖 Node 辅助程序会以不跟随链接的方式逐级打开目录描述符，并通过一个持续持有的常规文件描述符读取至字节上限。因此，通用 LSP 查询会在服务器启动前拒绝父目录交换、非文件、无效 UTF-8，以及增长后超出所配置文档上限的文件。
-- **原子变更**：写入会上传 mode 为 `0600` 的同级临时文件，保留现有文件的 POSIX mode，并通过 E2B 的同目录原子重命名发布。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
+- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 2452e856ca..0824c3f87c 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -498,8 +498,15 @@ export class E2BFileSystem extends FileSystem {
     const sandbox = await this.ctx.e2b.getSandbox()
     const targetPath = String(target.targetKey)
     const versionId = randomUUID()
-    const temporary = posix.join(posix.dirname(targetPath), `.${posix.basename(targetPath)}.dsh-${randomUUID()}.tmp`)
+    const stagingDirectory = posix.join(posix.dirname(targetPath), `.dsh-${randomUUID()}.tmp`)
+    const temporary = posix.join(stagingDirectory, 'content')
+    let stagingDirectoryCreated = false
     try {
+      const created = await sandbox.files.makeDir(stagingDirectory, signalOpts(signal))
+      if (!created) throw new Error('private staging directory already exists')
+      stagingDirectoryCreated = true
+      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stagingDirectory)}`, signalOpts(signal))
+      assertNotAborted(signal, 'write')
       await sandbox.files.write(temporary, content, {
         metadata: { [VERSION_METADATA_KEY]: versionId },
         ...signalOpts(signal),
@@ -512,12 +519,19 @@ export class E2BFileSystem extends FileSystem {
       )
       assertNotAborted(signal, 'write')
       const committed = await sandbox.files.rename(temporary, targetPath, signalOpts(signal))
+      try {
+        await sandbox.files.remove(stagingDirectory)
+      } catch (_committedStagingCleanupFailure) {
+        // The target is already committed; an empty private directory cannot turn that write into a failure.
+      }
       return entryVersion(committed)
     } catch (error: unknown) {
-      try {
-        await sandbox.files.remove(temporary)
-      } catch (_temporaryAlreadyAbsent) {
-        // Only the private staging path is swallowed; the original failure owns the operation.
+      if (stagingDirectoryCreated) {
+        try {
+          await sandbox.files.remove(stagingDirectory)
+        } catch (_stagingDirectoryAlreadyAbsentOrCleanupFailed) {
+          // Only the private staging directory is swallowed; the original failure owns the operation.
+        }
       }
       throw mapError(error, 'write', target.displayPath, signal)
     }
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 648631c7ee..303f99c1e8 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -35,6 +35,7 @@ function commandError(exitCode: number, stderr = ''): CommandExitError {
 class FakeRemote {
   readonly nodes = new Map<string, RemoteNode>()
   readonly writes: Array<{ path: string; data: string; metadata?: Record<string, string> }> = []
+  readonly writeParentModes: number[] = []
   readonly renames: Array<{ from: string; to: string }> = []
   readonly removals: string[] = []
   readonly commands: string[] = []
@@ -42,6 +43,7 @@ class FakeRemote {
   streamKeepOpen = false
   readonly streamCancel = vi.fn()
   nextCommandError: unknown
+  nextMakeDirResult: boolean | undefined
   nextInfoError: unknown
   nextListError: unknown
   nextReadError: unknown
@@ -130,7 +132,13 @@ class FakeRemote {
   readonly sandbox = {
     sandboxId: 'fake',
     files: {
-      makeDir: async (path: string): Promise<boolean> => {
+      makeDir: async (path: string, options?: { signal?: AbortSignal }): Promise<boolean> => {
+        this.checkAbort(options)
+        if (this.nextMakeDirResult !== undefined) {
+          const result = this.nextMakeDirResult
+          this.nextMakeDirResult = undefined
+          return result
+        }
         if (this.nodes.has(path)) return false
         this.dir(path)
         return true
@@ -178,6 +186,7 @@ class FakeRemote {
         this.checkAbort(options)
         const parent = dirname(path)
         if (!this.nodes.has(parent)) this.dir(parent)
+        this.writeParentModes.push(this.required(parent).mode)
         this.nodes.set(path, {
           type: FileType.FILE,
           data: bytes(data),
@@ -209,7 +218,9 @@ class FakeRemote {
           this.nextRemoveError = undefined
           throw error
         }
-        this.nodes.delete(path)
+        for (const candidate of this.nodes.keys()) {
+          if (candidate === path || candidate.startsWith(`${path}/`)) this.nodes.delete(candidate)
+        }
       },
     },
     commands: {
@@ -499,6 +510,10 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(outcome).toMatchObject({ operation: 'create', before: null, after: 'one\ntwo\rthree' })
     expect(remote.nodes.get('/workspace/new.txt')?.mode).toBe(0o600)
     expect(remote.nodes.get('/workspace/new.txt')?.metadata?.['dsh-version']).toBeDefined()
+    expect(remote.writeParentModes).toEqual([0o700])
+    const stagingDirectory = posix.dirname(remote.writes[0]!.path)
+    expect(posix.dirname(stagingDirectory)).toBe('/workspace')
+    expect(remote.removals).toContain(stagingDirectory)
     await expect(fs.stat(target)).resolves.toMatchObject({ version: outcome.version, size: 14 })
   })
 
@@ -558,6 +573,15 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(controller.signal.aborted).toBe(true)
   })
 
+  it('does not turn post-commit staging cleanup failure into a failed write', async () => {
+    const remote = new FakeRemote()
+    remote.nextRemoveError = new Error('empty staging cleanup failed')
+    const { fs } = await setup(remote)
+    await expect(fs.writeText(await fs.resolve('committed'), 'yes'))
+      .resolves.toMatchObject({ operation: 'create' })
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/committed')?.data)).toBe('yes')
+  })
+
   it('returns committed rename metadata without a fallible post-commit lookup', async () => {
     const remote = new FakeRemote()
     const getInfo = vi.spyOn(remote.sandbox.files, 'getInfo')
@@ -582,6 +606,11 @@ describe('E2BFileSystem atomic writes and edits', () => {
     remote.nextRemoveError = new Error('cleanup also failed')
     remote.nextRenameError = new DOMException('aborted', 'AbortError')
     await expectCode(fs.writeText(await fs.resolve('abort'), 'x'), 'FS_ABORTED')
+
+    const removalsBeforeCollision = remote.removals.length
+    remote.nextMakeDirResult = false
+    await expectCode(fs.writeText(await fs.resolve('collision'), 'x'), 'FS_IO_ERROR')
+    expect(remote.removals).toHaveLength(removalsBeforeCollision)
   })
 
   it('applies literal edits atomically and restores the detected CRLF style', async () => {
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 3a577227f8..41d964a58a 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: fb3d79433fba8bb86097cffb09a257ad5756cc2b
-README.zh.md: ec012b6a05c1a5f911d5ede9730f0f7207d5a645
+README.md: 42cd4951edb101dc75980e114e704c4aab50ae25
+README.zh.md: c4b318184cb7616a378e3336f4f4a7c366a98807
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index fb3d79433f..42cd4951ed 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -8,10 +8,10 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication, while cancellation can stop the provisional SDK handle first.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried, while successful termination remains a permanent no-op. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every `spec.env` entry as an explicit caller opt-in. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
-- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers; after `graceMs`, the adapter disconnects an incomplete SDK stream, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, fence publication during service disposal, and include failure cleanup. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
+- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination; raw pipes instead await lossless transport completion and preserve backpressure. Batch and streaming stdin use the SDK handle.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
 The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
@@ -29,6 +29,6 @@ No direct invalidation; the named consumers own any request-prefix changes.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
 - **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
-- **E2B exposes no signal fact** — only an adapter-requested `SIGTERM` or `SIGKILL` is reported as a signal; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
+- **E2B exposes no signal fact** — an adapter-requested `SIGTERM` or `SIGKILL` is reported only when no wrapper-published direct exit code wins; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
 - **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
 - **Linux utility and E2B transport semantics are assumed** — there is no Windows, arbitrary-template, escaped-session recovery, or network-partition fidelity layer.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index ec012b6a05..c4b318184c 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -8,10 +8,10 @@
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布，而取消操作可以先停止临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试；成功终止后，重复终止将永久为空操作。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个 `spec.env` 条目恢复为调用方显式选择。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
-- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态；超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间阻止发布，并包括失败清理。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
+- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个有效的 `spec.env` 条目恢复为调用方显式选择；空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用；原始 pipe 则会等待无损传输完成并保留背压。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
 基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
@@ -29,6 +29,6 @@
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
 - **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
-- **E2B 不公开信号事实**：只有适配器请求的 `SIGTERM` 或 `SIGKILL` 会报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
+- **E2B 不公开信号事实**：适配器请求的 `SIGTERM` 或 `SIGKILL` 只有在包装层发布的直接退出码没有胜出时才报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
 - **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
 - **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、任意模板、逃逸会话恢复或网络分区的保真层。
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index cc9b41296a..f9c30d378f 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -19,3 +19,23 @@ export function scrubRemoteEnvironment(raw: string): Map<string, string> {
   }
   return environment
 }
+
+/**
+ * Overlay explicit entries and serialize one validated E2B environment.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @param explicit - Deliberate caller overrides applied after ambient scrubbing.
+ * @returns NUL-delimited `name=value` entries accepted by `env -i`.
+ */
+export function serializeRemoteEnvironment(
+  raw: string,
+  explicit: Readonly<Record<string, string>> | undefined,
+): string {
+  const environment = scrubRemoteEnvironment(raw)
+  for (const [name, value] of Object.entries(explicit ?? {})) {
+    if (name.length === 0 || name.includes('=') || name.includes('\0') || value.includes('\0')) {
+      throw new Error('subprocess-e2b: environment entries require non-empty NUL-free names without = and NUL-free values')
+    }
+    environment.set(name, value)
+  }
+  return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
+}
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index fcf2c6f0a4..bf7edc41a1 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -28,7 +28,8 @@ export class E2BSubprocessService extends SubprocessService {
 
   private readonly live = new Set<E2BSubprocessHandle>()
   private readonly terminals = new Set<SubprocessTerminalHandle>()
-  private readonly terminalSetups = new Set<Promise<void>>()
+  private readonly terminalSetups = new Map<Promise<void>, AbortController>()
+  private readonly failedTerminalSetupCleanups = new Set<() => Promise<void>>()
   private disposing = false
 
   /** @inheritdoc */
@@ -44,9 +45,13 @@ export class E2BSubprocessService extends SubprocessService {
     this.runtimeRoot = ctx.e2b.runtimeRoot
     ctx.effect(() => async () => {
       this.disposing = true
-      await Promise.all([...this.terminalSetups])
+      for (const controller of this.terminalSetups.values()) {
+        controller.abort(new Error('subprocess-e2b: service disposed during terminal setup'))
+      }
+      await Promise.all([...this.terminalSetups.keys()])
       const handles = [...this.live]
       const terminals = [...this.terminals]
+      const failedTerminalSetupCleanups = [...this.failedTerminalSetupCleanups]
       const pending: Promise<unknown>[] = []
       for (const handle of handles) {
         handle.terminate()
@@ -59,6 +64,9 @@ export class E2BSubprocessService extends SubprocessService {
         terminal.terminate()
         pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
       }
+      for (const cleanup of failedTerminalSetupCleanups) {
+        pending.push(cleanup().then(() => { this.failedTerminalSetupCleanups.delete(cleanup) }))
+      }
       await Promise.all(pending)
     }, 'e2b subprocess teardown')
   }
@@ -133,9 +141,18 @@ export class E2BSubprocessService extends SubprocessService {
     spec.signal?.throwIfAborted()
     const stateDir = posix.join(this.runtimeRoot, 'terminals', randomUUID())
     const setup = Promise.withResolvers<void>()
-    this.terminalSetups.add(setup.promise)
+    const setupController = new AbortController()
+    const setupSignal = spec.signal === undefined
+      ? setupController.signal
+      : AbortSignal.any([spec.signal, setupController.signal])
+    this.terminalSetups.set(setup.promise, setupController)
     try {
-      const terminal = await spawnE2BTerminal(this.ctx.e2b, spec, stateDir)
+      const terminal = await spawnE2BTerminal(
+        this.ctx.e2b,
+        { ...spec, signal: setupSignal },
+        stateDir,
+        (cleanup) => { this.failedTerminalSetupCleanups.add(cleanup) },
+      )
       this.terminals.add(terminal)
       if (this.isDisposing()) {
         terminal.terminate()
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 3038f312dc..4855b27b81 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -17,7 +17,7 @@ import type {
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { scrubRemoteEnvironment } from './environment.ts'
+import { serializeRemoteEnvironment } from './environment.ts'
 import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
 
 const GROUP_POLL_MS = 20
@@ -92,12 +92,6 @@ function withinMs<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefi
   })
 }
 
-function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
-  const environment = scrubRemoteEnvironment(raw)
-  for (const [name, value] of Object.entries(explicit ?? {})) environment.set(name, value)
-  return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
-}
-
 function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
   const encoder = `"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e ${quoteE2BShellArg(OUTPUT_ENCODER_SOURCE)}`
   const stdoutRedirect = hasSpill(spec.stdio.stdout)
@@ -213,7 +207,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private invalidHandleQuiescent = false
   private provisionalHandleQuiescent = false
   private terminationStarted = false
-  private terminationSucceeded = false
+  private terminationFenced = false
+  private quiescenceProven = false
   private terminationAttempt: Promise<void> | undefined
   private terminationFailure: Error | undefined
   private terminationSignal: NodeJS.Signals | null = null
@@ -265,18 +260,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    if (this.terminationSucceeded || this.terminationAttempt !== undefined) return
+    if (this.terminationFenced || this.quiescenceProven || this.terminationAttempt !== undefined) return
     this.terminationStarted = true
     this.terminationFailure = undefined
     const attempt = this.terminateRemote()
     this.terminationAttempt = attempt
     void attempt.then(
       () => {
-        this.terminationSucceeded = true
+        this.terminationFenced = true
         this.terminationAttempt = undefined
       },
       (error: unknown) => {
-        this.terminationFailure = asError(error)
+        if (!this.quiescenceProven) this.terminationFailure = asError(error)
         this.terminationAttempt = undefined
       },
     )
@@ -284,17 +279,24 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    if (this.quiescenceProven) return true
     let handle: CommandHandle | undefined
     if (this.terminationStarted) {
       const observed = await waitWithSignal(this.commandState.promise, signal)
       if (observed === WAIT_ABORTED) return false
       handle = observed
-      if (handle === undefined) return true
+      if (handle === undefined) {
+        this.markQuiescent()
+        return true
+      }
       if (this.remotePid <= 0) {
         const attempt = this.terminationAttempt
         if (attempt !== undefined && await waitWithSignal(attempt, signal) === WAIT_ABORTED) return false
         this.throwTerminationFailure()
-        if (this.invalidHandleQuiescent || this.provisionalHandleQuiescent) return true
+        if (this.invalidHandleQuiescent || this.provisionalHandleQuiescent) {
+          this.markQuiescent()
+          return true
+        }
       }
     } else {
       try {
@@ -303,7 +305,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         handle = observed
       } catch {
         handle = this.commandHandle
-        if (handle === undefined) return true
+        if (handle === undefined) {
+          this.markQuiescent()
+          return true
+        }
       }
     }
     this.throwTerminationFailure()
@@ -320,11 +325,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (!await waitTick(signal)) return false
     }
     this.throwTerminationFailure()
-    return !isAborted(signal)
+    if (isAborted(signal)) return false
+    this.markQuiescent()
+    return true
   }
 
   private readonly onAbort = (): void => { this.terminate() }
 
+  private markQuiescent(): void {
+    this.quiescenceProven = true
+    this.terminationFailure = undefined
+  }
+
   private async run(): Promise<SubprocessOutcome> {
     let sandbox: Sandbox | undefined
     try {
@@ -385,7 +397,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       return outcome
     } catch (error: unknown) {
       this.commandState.resolve(undefined)
-      let failure = error
+      let failure = await this.rollbackPublishedFailure(error)
       if (sandbox !== undefined && this.stateDirectoryCreated) {
         try {
           await this.removeFailedState(sandbox)
@@ -413,7 +425,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     const files = [
       { path: this.paths.pid, data: '' },
       { path: this.paths.status, data: '' },
-      { path: this.paths.environment, data: remoteEnvironment(ambient.stdout, this.spec.env) },
+      { path: this.paths.environment, data: serializeRemoteEnvironment(ambient.stdout, this.spec.env) },
       ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
       ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
     ]
@@ -508,15 +520,16 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         if (!/^(?:0|[1-9][0-9]*)$/.test(rawStatus) || !Number.isSafeInteger(exitCode) || exitCode > 255) {
           throw new Error(`subprocess-e2b: remote wrapper published invalid exit code ${JSON.stringify(rawStatus)}`)
         }
+        if (this.spec.stdio.stdout === 'pipe' || this.spec.stdio.stderr === 'pipe') {
+          return this.commandOutcome(await settlement)
+        }
         const completed = await withinMs(settlement, this.spec.graceMs)
         if (completed !== undefined) return this.commandOutcome(completed)
         this.outputDrainExpired = true
         this.stdoutReader?.invalidateSpill()
         this.stderrReader?.invalidateSpill()
         await handle.disconnect()
-        return this.terminationSignal === null
-          ? { exitCode, signal: null }
-          : { exitCode: null, signal: this.terminationSignal }
+        return { exitCode, signal: null }
       }
       const completed = await Promise.race([settlement, waitTick().then(() => undefined)])
       if (completed !== undefined) return this.commandOutcome(completed)
@@ -533,6 +546,20 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     throw settlement.error
   }
 
+  private async rollbackPublishedFailure(error: unknown): Promise<unknown> {
+    if (this.remotePid <= 0 || this.commandHandle === undefined || this.quiescenceProven) return error
+    this.terminate()
+    try {
+      await this.waitForExit()
+      return error
+    } catch (cleanupError: unknown) {
+      return new AggregateError(
+        [asError(error), asError(cleanupError)],
+        'subprocess-e2b: command monitoring failed and process-group rollback did not reach quiescence',
+      )
+    }
+  }
+
   private async rollbackUnpublishedGroup(sandbox: Sandbox, handle: CommandHandle): Promise<void> {
     // The bootstrap ends in an exec chain through the scrubbed environment and
     // `setsid`, so E2B's command PID is the provisional group id even before the
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 78668490d7..0f5809fa44 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -19,7 +19,7 @@ import type {
   SubprocessTerminalSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { scrubRemoteEnvironment } from './environment.ts'
+import { serializeRemoteEnvironment } from './environment.ts'
 
 const POLL_MS = 20
 
@@ -142,17 +142,6 @@ function serializeValues(values: readonly string[], kind: string): string {
   return values.map(value => `${value}\0`).join('')
 }
 
-function remoteEnvironment(raw: string, explicit: Readonly<Record<string, string>> | undefined): string {
-  const environment = scrubRemoteEnvironment(raw)
-  for (const [name, value] of Object.entries(explicit ?? {})) {
-    if (name.length === 0 || name.includes('=') || name.includes('\0') || value.includes('\0')) {
-      throw new Error('subprocess-e2b: terminal environment entries require non-empty NUL-free names without = and NUL-free values')
-    }
-    environment.set(name, value)
-  }
-  return serializeValues([...environment].map(([name, value]) => `${name}=${value}`), 'environment')
-}
-
 async function terminalSessionId(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<number> {
   const result = await sandbox.commands.run(`ps -o sid= -p ${pid}`, signalOpts(signal))
   signal?.throwIfAborted()
@@ -432,12 +421,14 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
  * @param runtime - Shared E2B sandbox owner.
  * @param spec - Fully specified terminal-process request.
  * @param stateDir - Private remote directory for one startup transaction.
+ * @param retainFailedCleanup - Optional owner for retrying a cleanup transaction that could not prove quiescence.
  * @returns The live subprocess terminal handle.
  */
 export async function spawnE2BTerminal(
   runtime: E2BSandboxService,
   spec: SubprocessTerminalSpawnSpec,
   stateDir: string,
+  retainFailedCleanup?: (cleanup: () => Promise<void>) => void,
 ): Promise<E2BTerminalHandle> {
   const sandbox = await runtime.getSandbox()
   spec.signal?.throwIfAborted()
@@ -456,7 +447,7 @@ export async function spawnE2BTerminal(
   let stateDirectoryCreated = false
   try {
     const ambient = await sandbox.commands.run('env -0', signalOpts(spec.signal))
-    const environment = remoteEnvironment(ambient.stdout, spec.env)
+    const environment = serializeRemoteEnvironment(ambient.stdout, spec.env)
     const argv = serializeValues(spec.argv, 'argv')
     await sandbox.files.makeDir(stateDir)
     stateDirectoryCreated = true
@@ -502,25 +493,37 @@ export async function spawnE2BTerminal(
     )
   } catch (error: unknown) {
     output.destroy()
-    const cleanupErrors: Error[] = []
-    if (handle !== undefined && completion !== undefined) {
-      try {
-        await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
-      } catch (rollbackError: unknown) {
-        cleanupErrors.push(asError(rollbackError))
+    let terminalQuiescent = handle === undefined
+    let stateRemoved = !stateDirectoryCreated
+    const retryCleanup = async (): Promise<void> => {
+      const failures: Error[] = []
+      if (!terminalQuiescent && handle !== undefined) {
+        try {
+          if (completion === undefined) await handle.kill()
+          else await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
+          terminalQuiescent = true
+        } catch (cleanupError: unknown) {
+          failures.push(asError(cleanupError))
+        }
       }
-    } else if (handle !== undefined) {
-      await handle.kill().catch(() => false)
-    }
-    if (stateDirectoryCreated) {
-      try {
-        await sandbox.files.remove(stateDir)
-      } catch (stateError: unknown) {
-        if (!(stateError instanceof FileNotFoundError)) cleanupErrors.push(asError(stateError))
+      if (!stateRemoved) {
+        try {
+          await sandbox.files.remove(stateDir)
+          stateRemoved = true
+        } catch (stateError: unknown) {
+          if (stateError instanceof FileNotFoundError) stateRemoved = true
+          else failures.push(asError(stateError))
+        }
+      }
+      if (failures.length > 0) {
+        throw new AggregateError(failures, 'subprocess-e2b: terminal setup cleanup did not complete')
       }
     }
-    if (cleanupErrors.length > 0) {
-      throw new AggregateError([asError(error), ...cleanupErrors], asError(error).message)
+    try {
+      await retryCleanup()
+    } catch (cleanupError: unknown) {
+      retainFailedCleanup?.(retryCleanup)
+      throw new AggregateError([asError(error), asError(cleanupError)], asError(error).message)
     }
     throw error
   }
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 8e6e420bcc..462e943a1b 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -97,6 +97,7 @@ class FakeSandbox {
   startOptions: StartOptions | undefined
   backgroundError: unknown
   envError: unknown
+  statusError: unknown
   nextRemoveError: unknown
   probeError: unknown
   signalError: unknown
@@ -117,6 +118,8 @@ class FakeSandbox {
   private openStart: (() => void) | undefined
   private processGroupReadGate: Promise<void> | undefined
   private openProcessGroupRead: (() => void) | undefined
+  private signalGate: Promise<void> | undefined
+  private openSignal: (() => void) | undefined
 
   constructor() {
     this.handle = new FakeCommandHandle(() => {
@@ -147,6 +150,16 @@ class FakeSandbox {
     this.openProcessGroupRead?.()
   }
 
+  deferSignals(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.signalGate = gate.promise
+    this.openSignal = () => { gate.resolve(undefined) }
+  }
+
+  releaseSignals(): void {
+    this.openSignal?.()
+  }
+
   finish(exitCode = 0): void {
     this.alive = false
     void this.completeOutput().then(
@@ -198,6 +211,11 @@ class FakeSandbox {
           await this.processGroupReadGate
           return this.processGroupReads.shift() ?? this.processGroupId
         }
+        if (this.statusError !== undefined) {
+          const error = this.statusError
+          this.statusError = undefined
+          throw error
+        }
         this.afterStatusRead?.()
         return this.exitStatus
       },
@@ -230,6 +248,7 @@ class FakeSandbox {
           return { exitCode: 0, stdout: '', stderr: '' }
         }
         if (command.startsWith('kill -TERM ')) {
+          await this.signalGate
           const error = this.signalErrors.shift() ?? this.signalError
           if (error !== undefined) {
             if (this.signalErrors.length === 0) this.signalError = undefined
@@ -242,6 +261,7 @@ class FakeSandbox {
           return { exitCode: 0, stdout: '', stderr: '' }
         }
         if (command.startsWith('kill -KILL ')) {
+          await this.signalGate
           const error = this.signalErrors.shift() ?? this.signalError
           if (error !== undefined) {
             if (this.signalErrors.length === 0) this.signalError = undefined
@@ -399,6 +419,16 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('rejects malformed environment entries before command start', async () => {
+    for (const env of [{ 'BAD=NAME': 'x' }, { BAD: 'x\0INJECTED=1' }]) {
+      const fake = new FakeSandbox()
+      const handle = new E2BSubprocessHandle(runtime(fake), spec({ env }), '/runtime/invalid-environment')
+      await expect(handle.done).rejects.toThrow('environment entries')
+      expect(fake.startOptions).toBeUndefined()
+      expect(fake.removed).toContain('/runtime/invalid-environment')
+    }
+  })
+
   it('preserves UTF-8 bytes when the ASCII transport is split across callbacks', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
@@ -460,6 +490,29 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('waits for lossless raw-pipe output after the direct status is published', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      graceMs: 1,
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/pipe-drain')
+    let output = ''
+    handle.stdout!.on('data', (chunk) => { output += String(chunk) })
+    await flush()
+    fake.exitStatus = '0\n'
+
+    let settled = false
+    void handle.done.then(() => { settled = true })
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(settled).toBe(false)
+    expect(fake.handle.disconnects).toBe(0)
+
+    await fake.stdout('complete protocol frame')
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    expect(output).toBe('complete protocol frame')
+  })
+
   it('accepts clean encoder completion inside the output-drain grace', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-complete')
@@ -474,7 +527,7 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.handle.disconnects).toBe(0)
   })
 
-  it('preserves a requested signal when output draining expires', async () => {
+  it('preserves a published exit code when requested termination outlives output draining', async () => {
     const fake = new FakeSandbox()
     fake.trapsTerm = true
     fake.delaysKill = true
@@ -485,9 +538,9 @@ describe('E2BSubprocessHandle', () => {
 
     handle.terminate()
     await vi.waitFor(() => { expect(fake.commandsSeen).toContain('kill -KILL -- -4242') })
-    fake.exitStatus = '143\n'
+    fake.exitStatus = '0\n'
 
-    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
     expect(fake.handle.disconnects).toBe(1)
     fake.alive = false
     await expect(handle.waitForExit()).resolves.toBe(true)
@@ -503,6 +556,31 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('rolls back a published process group before rejecting a monitoring failure', async () => {
+    const fake = new FakeSandbox()
+    fake.statusError = new Error('status transport failed')
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/status-failure')
+
+    await expect(handle.done).rejects.toThrow('status transport failed')
+    expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
+    expect(fake.alive).toBe(false)
+    await expect(handle.waitForExit()).resolves.toBe(true)
+
+    const failed = new FakeSandbox()
+    failed.statusError = new Error('status transport failed')
+    failed.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    failed.handle.killError = new Error('SDK kill failed')
+    const retained = new E2BSubprocessHandle(runtime(failed), spec({ graceMs: 1 }), '/runtime/status-cleanup-failure')
+
+    await expect(retained.done).rejects.toThrow(
+      'command monitoring failed and process-group rollback did not reach quiescence',
+    )
+    expect(failed.alive).toBe(true)
+    failed.handle.killError = undefined
+    retained.terminate()
+    await expect(retained.waitForExit()).resolves.toBe(true)
+  })
+
   it('surfaces deferred piped-stdin write and close failures as stream errors', async () => {
     const writeFake = new FakeSandbox()
     writeFake.deferStart()
@@ -607,6 +685,46 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.commandsSeen.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
   })
 
+  it('makes termination a permanent no-op after natural quiescence is observed', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/natural-quiescence')
+    await flush()
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    await expect(handle.waitForExit()).resolves.toBe(true)
+
+    const signals = fake.commandsSeen.filter(command => command.startsWith('kill -')).length
+    fake.alive = true
+    handle.terminate()
+    await flush()
+    expect(fake.alive).toBe(true)
+    expect(fake.commandsSeen.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
+  })
+
+  it('keeps proven quiescence after a concurrent termination transport fails', async () => {
+    const fake = new FakeSandbox()
+    fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    fake.handle.killError = new Error('SDK kill failed')
+    fake.deferSignals()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/quiescent-race')
+    await flush()
+
+    handle.terminate()
+    await vi.waitFor(() => { expect(fake.commandsSeen).toContain('kill -TERM -- -4242') })
+    fake.alive = false
+    await expect(handle.waitForExit()).resolves.toBe(true)
+
+    fake.probeError = new Error('post-quiescence probe failed')
+    fake.releaseSignals()
+    await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+    const signals = fake.commandsSeen.filter(command => command.startsWith('kill -')).length
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(fake.commandsSeen.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
+  })
+
   it('escalates a TERM-trapping process group to KILL and uses the SDK kill as fallback', async () => {
     const fake = new FakeSandbox()
     fake.trapsTerm = true
@@ -620,6 +738,28 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.handle.kills).toBe(1)
   })
 
+  it('does not treat successful termination transport as observed quiescence', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    fake.delaysKill = true
+    fake.delaysKillCompletion = true
+    fake.sdkKillStops = false
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/termination-fence')
+    await flush()
+    handle.terminate()
+    await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
+
+    let quiescent = false
+    const waiting = handle.waitForExit().then((value) => { quiescent = value })
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(quiescent).toBe(false)
+
+    fake.alive = false
+    fake.finish()
+    await waiting
+    expect(quiescent).toBe(true)
+  })
+
   it('honors termination requested before asynchronous startup finishes', async () => {
     const fake = new FakeSandbox()
     fake.deferStart()
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 1eac9a5780..e77646e586 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -111,18 +111,7 @@ class FakeTerminalSandbox {
   resolvedExecutable = '/usr/bin/node\n'
   requestedOutput = 'requested-shell$ '
   emitOutputMarker = true
-  private createGate: Promise<void> | undefined
-  private releaseCreateGate: (() => void) | undefined
-
-  deferCreate(): void {
-    const gate = Promise.withResolvers<undefined>()
-    this.createGate = gate.promise
-    this.releaseCreateGate = () => { gate.resolve(undefined) }
-  }
-
-  releaseCreate(): void {
-    this.releaseCreateGate?.()
-  }
+  afterSessionLookup: (() => void) | undefined
 
   readonly sandbox = {
     files: {
@@ -163,7 +152,10 @@ class FakeTerminalSandbox {
         if (command.includes('command -v -- ')) {
           return { exitCode: 0, stdout: this.resolvedExecutable, stderr: '' }
         }
-        if (command.startsWith('ps -o sid=')) return { exitCode: 0, stdout: this.sessionId, stderr: '' }
+        if (command.startsWith('ps -o sid=')) {
+          this.afterSessionLookup?.()
+          return { exitCode: 0, stdout: this.sessionId, stderr: '' }
+        }
         if (command.startsWith('ps -o tpgid=')) {
           if (this.foregroundFailure !== undefined) throw this.foregroundFailure
           return { exitCode: 0, stdout: this.foreground, stderr: '' }
@@ -186,7 +178,6 @@ class FakeTerminalSandbox {
     pty: {
       create: async (options: Parameters<Sandbox['pty']['create']>[0]): Promise<CommandHandle> => {
         this.createOptions = options
-        await this.createGate
         if (this.createError !== undefined) throw this.createError
         await options.onData(Buffer.from('buffered banner\n'))
         return this.handle.asHandle()
@@ -691,7 +682,7 @@ describe('E2B subprocess terminal service', () => {
 
   it('owns live terminals through service disposal', async () => {
     const { ctx, fiber, fake } = await service()
-    const terminal = await ctx.subprocess.spawnTerminal(spec())
+    const terminal = await ctx.subprocess.spawnTerminal(spec({ signal: new AbortController().signal }))
     await fiber.dispose()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
     expect(fake.handle.disconnects).toBe(1)
@@ -699,19 +690,19 @@ describe('E2B subprocess terminal service', () => {
 
   it('joins and rejects terminal setup that completes during service disposal', async () => {
     const fake = new FakeTerminalSandbox()
-    fake.deferCreate()
     const { ctx, fiber } = await service(fake)
+    let disposing: Promise<void> | undefined
+    fake.afterSessionLookup = () => {
+      fake.afterSessionLookup = undefined
+      queueMicrotask(() => {
+        queueMicrotask(() => { disposing = fiber.dispose() })
+      })
+    }
+    const subprocess = ctx.subprocess
     const spawning = ctx.subprocess.spawnTerminal(spec())
     const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
-    await vi.waitFor(() => { expect(fake.createOptions).toBeDefined() })
-
-    let disposed = false
-    const subprocess = ctx.subprocess
-    const disposing = fiber.dispose().then(() => { disposed = true })
-    await new Promise(resolve => setTimeout(resolve, 0))
-    expect(disposed).toBe(false)
+    await vi.waitFor(() => { expect(disposing).toBeDefined() })
     await expect(subprocess.spawnTerminal(spec())).rejects.toThrow('service is disposing')
-    fake.releaseCreate()
 
     await rejected
     await disposing
@@ -720,6 +711,37 @@ describe('E2B subprocess terminal service', () => {
     expect(fake.removed.some(path => path.includes('/terminals/'))).toBe(true)
   })
 
+  it('aborts and rolls back terminal setup that cannot publish readiness during disposal', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.ready = new FileNotFoundError('not ready')
+    const { ctx, fiber } = await service(fake)
+    const spawning = ctx.subprocess.spawnTerminal(spec())
+    const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
+    await vi.waitFor(() => { expect(fake.readyReads).toBeGreaterThan(0) })
+
+    await fiber.dispose()
+    await rejected
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
+  it('retains failed terminal setup cleanup for disposal retry', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.sendError = new Error('bootstrap failed')
+    fake.clearOnTerm = false
+    fake.clearOnKill = false
+    const { ctx, fiber } = await service(fake)
+
+    await expect(ctx.subprocess.spawnTerminal(spec({ graceMs: 1 }))).rejects.toThrow('bootstrap failed')
+    expect(fake.groups).toEqual([123])
+    expect(fake.handle.disconnects).toBe(0)
+
+    fake.clearOnKill = true
+    await fiber.dispose()
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
   it('releases naturally settled terminals and validates terminal requests', async () => {
     const { ctx, fiber, fake } = await service()
     for (const request of [

From d0648446c97e426c53deefe7d41cc25b1016bbaa Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 09:54:14 +0800
Subject: [PATCH 372/516] fix(e2b): close final lifecycle gaps

---
 packages/e2b/e2b/README.i18n.yaml             |  4 +-
 packages/e2b/e2b/README.md                    |  2 +-
 packages/e2b/e2b/README.zh.md                 |  2 +-
 packages/e2b/e2b/src/index.ts                 | 17 +++++++--
 packages/e2b/e2b/tests/e2b.spec.ts            | 22 ++++++++++-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         |  4 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  4 +-
 packages/e2b/subprocess-e2b/src/process.ts    | 17 +++++----
 packages/e2b/subprocess-e2b/src/terminal.ts   |  2 +-
 .../subprocess-e2b/tests/subprocess.spec.ts   | 38 +++++++++++++++++--
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 22 ++++++++++-
 12 files changed, 111 insertions(+), 27 deletions(-)

diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index d8f1dcdc3f..46ff37b222 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 01c7ade2f5f31e34091ad0ae910287e659f15549
-README.zh.md: fb95a12cbbbd431ccb3283a14bb63b324f9bdea6
+README.md: ccafa9df480e3812d3d3b6d25b513e7b5d2afc9f
+README.zh.md: 60eefd46a0a9a017f4db57e4dc5313d533eeba04
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 01c7ade2f5..ccafa9df48 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -30,7 +30,7 @@ Set `sandboxId` to reconnect a running or paused sandbox instead of creating one
 
 Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
 
-Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` means a kill-on-timeout sandbox is already quiescent; every other disposition failure rejects teardown. A newly created sandbox is killed when initial directory setup fails; a reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
+Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` means a kill-on-timeout sandbox is already quiescent; every other disposition failure rejects teardown. A newly created sandbox is killed when initial directory setup fails; if that rollback fails, disposal retries it before releasing ownership. A reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
 
 `pause` and `leave` retain remote filesystem and adapter artifacts for a later `sandboxId` connection, but a later harness process receives only a new SDK handle. The subprocess service still fulfills its seam contract by terminating managed groups before owner disposal; neither disposition recovers prior process objects, output cursors, or in-memory adapter locks.
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index fb95a12cbb..60eefd46a0 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -30,7 +30,7 @@
 
 构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
 
-资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 表示因超时终止的沙箱已经完全停稳；其他处置失败都会使 teardown 拒绝。新建沙箱的初始目录设置失败时，服务会终止该沙箱；重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 表示因超时终止的沙箱已经完全停稳；其他处置失败都会使 teardown 拒绝。新建沙箱的初始目录设置失败时，服务会终止该沙箱；如果该回滚失败，资源释放会在解除所有权前重试。重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
 `pause` 和 `leave` 会保留远程文件系统及适配器产物，供稍后的 `sandboxId` 连接使用，但后续 harness 进程只会获得新的 SDK 句柄。进程管理服务仍会履行其 seam 契约，在所有者释放前终止受管进程组；这两种处置方式都不会恢复先前的进程对象、输出游标或内存中的适配器锁。
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 2c0b3c635c..31e4f911a2 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -120,6 +120,7 @@ export class E2BSandboxService extends Service {
 
   private readonly config: ResolvedConfig
   private readonly ready: Promise<Sandbox>
+  private failedSetupSandbox: Sandbox | undefined
   private disposed = false
 
   constructor(ctx: Context, config: Config) {
@@ -155,8 +156,16 @@ export class E2BSandboxService extends Service {
       try {
         sandbox = await this.ready
       } catch {
-        // Connection creation already failed and is exposed by getSandbox();
-        // there is no remote resource for teardown to own.
+        const failedSetupSandbox = this.failedSetupSandbox
+        if (failedSetupSandbox === undefined) return
+        sandbox = failedSetupSandbox
+        try {
+          await sandbox.kill()
+          this.failedSetupSandbox = undefined
+        } catch (error: unknown) {
+          if (!(error instanceof SandboxNotFoundError)) throw error
+          this.failedSetupSandbox = undefined
+        }
         return
       }
       try {
@@ -243,7 +252,9 @@ export class E2BSandboxService extends Service {
         try {
           await sandbox.kill()
         } catch (_cleanupFailure) {
-          // The setup failure remains authoritative; E2B will still apply the configured lifetime.
+          // Preserve the setup failure as the public error while retaining the
+          // created handle for the service disposer to retry this rollback.
+          this.failedSetupSandbox = sandbox
         }
       }
       throw error
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index ff90c37b3a..fea24fa1cd 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -210,8 +210,28 @@ describe('E2BSandboxService', () => {
     fixture.kill.mockRejectedValueOnce(new Error('cleanup failed'))
     sdk.create.mockResolvedValue(fixture.sandbox)
     const ctx = new Context()
-    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
     await expect(ctx.e2b.getSandbox()).rejects.toThrow('chmod failed')
+    expect(fixture.kill).toHaveBeenCalledOnce()
+
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledTimes(2)
+  })
+
+  it.each([
+    ['retries a still-failing rollback', new Error('retry failed')],
+    ['accepts a setup sandbox that expired before retry', new SandboxNotFoundError('sandbox expired')],
+  ])('%s during disposal', async (_label, retryError) => {
+    const fixture = fakeSandbox()
+    fixture.run.mockRejectedValueOnce(new Error('chmod failed'))
+    fixture.kill.mockRejectedValueOnce(new Error('cleanup failed')).mockRejectedValueOnce(retryError)
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('chmod failed')
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledTimes(2)
   })
 
   it('does not kill a reconnected sandbox when setup fails', async () => {
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 41d964a58a..0a9baf6d27 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 42cd4951edb101dc75980e114e704c4aab50ae25
-README.zh.md: c4b318184cb7616a378e3336f4f4a7c366a98807
+README.md: 1c05509308e4f8b8b07cffd85e289b3ebee70318
+README.zh.md: b536d4e9d083076eccef4ca238dda1b2a503bee1
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 42cd4951ed..1c05509308 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -8,10 +8,10 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication, while cancellation can stop the provisional SDK handle first.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination; raw pipes instead await lossless transport completion and preserve backpressure. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every group in the remote terminal session before settlement. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 
 The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index c4b318184c..b536d4e9d0 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -8,10 +8,10 @@
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布，而取消操作可以先停止临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个有效的 `spec.env` 条目恢复为调用方显式选择；空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用；原始 pipe 则会等待无损传输完成并保留背压。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中的每个进程组。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 
 基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 4855b27b81..5387966578 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -474,12 +474,15 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     if (target.write(data)) return
     await new Promise<void>((resolve, reject) => {
       const onDrain = (): void => { cleanup(); resolve() }
+      const onClose = (): void => { cleanup(); resolve() }
       const onError = (error: Error): void => { cleanup(); reject(error) }
       const cleanup = (): void => {
         target.removeListener('drain', onDrain)
+        target.removeListener('close', onClose)
         target.removeListener('error', onError)
       }
       target.once('drain', onDrain)
+      target.once('close', onClose)
       target.once('error', onError)
     })
   }
@@ -671,14 +674,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async groupAlive(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<boolean> {
-    try {
-      await sandbox.commands.run(`kill -0 -- -${pid}`, signalOpts(signal))
-      return true
-    } catch (error: unknown) {
-      if (signal?.aborted === true) return false
-      if (error instanceof CommandExitError) return false
+    const result = await sandbox.commands.run(
+      `set -o pipefail; ps -eo pgid=,stat= | awk '$1 == ${pid} && $2 !~ /^[ZXx]/ { live=1 } END { if (live) print "live" }'`,
+      signalOpts(signal),
+    ).catch((error: unknown) => {
+      if (signal?.aborted === true) return undefined
       throw error
-    }
+    })
+    return result?.stdout.trim() === 'live'
   }
 
   private async finalizeSpills(sandbox: Sandbox): Promise<void> {
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 0f5809fa44..be79199b58 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -170,7 +170,7 @@ async function waitUntilReady(
 
 async function sessionProcessGroups(sandbox: Sandbox, sessionId: number): Promise<number[]> {
   const result = await sandbox.commands.run(
-    `ps -eo sid=,pgid= | awk '$1 == ${sessionId} { print $2 }'`,
+    `set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == ${sessionId} && $3 !~ /^[ZXx]/ { print $2 }'`,
   )
   const groups = new Set<number>()
   for (const raw of result.stdout.trim().split(/\s+/)) {
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 462e943a1b..b7d1642bd6 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -107,6 +107,7 @@ class FakeSandbox {
   delaysKillCompletion = false
   sdkKillStops = true
   alive = true
+  zombieOnly = false
   ambient = 'PATH=/ambient/bin\0KEEP=safe\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   processGroupId = '4242\n'
   exitStatus = ''
@@ -235,7 +236,7 @@ class FakeSandbox {
           if (this.envError !== undefined) throw this.envError
           return { exitCode: 0, stdout: this.ambient, stderr: '' }
         }
-        if (command.startsWith('kill -0 ')) {
+        if (command.startsWith('set -o pipefail; ps -eo pgid=,stat=')) {
           this.beforeProbe?.()
           if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
           if (this.probeError !== undefined) {
@@ -243,9 +244,9 @@ class FakeSandbox {
             this.probeError = undefined
             throw error
           }
-          if (!this.alive) throw commandError(1)
+          const stdout = this.alive && !this.zombieOnly ? 'live\n' : ''
           this.afterProbe?.()
-          return { exitCode: 0, stdout: '', stderr: '' }
+          return { exitCode: 0, stdout, stderr: '' }
         }
         if (command.startsWith('kill -TERM ')) {
           await this.signalGate
@@ -701,6 +702,20 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.commandsSeen.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
   })
 
+  it('treats a zombie-only process group as quiescent', async () => {
+    const fake = new FakeSandbox()
+    fake.zombieOnly = true
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/zombie-quiescence')
+    await flush()
+
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(fake.commandsSeen).toContain(
+      'set -o pipefail; ps -eo pgid=,stat= | awk \'$1 == 4242 && $2 !~ /^[ZXx]/ { live=1 } END { if (live) print "live" }\'',
+    )
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
   it('keeps proven quiescence after a concurrent termination transport fails', async () => {
     const fake = new FakeSandbox()
     fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
@@ -1187,6 +1202,23 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
   })
 
+  it('settles output backpressure when the consumer closes the pipe', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/backpressure-close')
+    await flush()
+
+    const stdoutWrite = vi.spyOn(handle.stdout!, 'write').mockReturnValueOnce(false)
+    const pending = fake.stdout('discarded')
+    queueMicrotask(() => { handle.stdout!.destroy() })
+    await pending
+    stdoutWrite.mockRestore()
+
+    fake.finish()
+    await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+  })
+
   it('contains a pipe callback failure instead of rejecting command settlement', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index e77646e586..b47cb8ffb1 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -95,6 +95,7 @@ class FakeTerminalSandbox {
   sessionId = '123\n'
   foreground = '456\n'
   groups = [123]
+  zombieGroups: number[] = []
   createError: unknown
   writeError: unknown
   sendError: unknown
@@ -160,9 +161,12 @@ class FakeTerminalSandbox {
           if (this.foregroundFailure !== undefined) throw this.foregroundFailure
           return { exitCode: 0, stdout: this.foreground, stderr: '' }
         }
-        if (command.startsWith('ps -eo sid=')) {
+        if (command.startsWith('set -o pipefail; ps -eo sid=')) {
           if (this.sessionGroupsFailure !== undefined) throw this.sessionGroupsFailure
-          return { exitCode: 0, stdout: this.groups.map(group => `${group}\n`).join(''), stderr: '' }
+          const groups = command.includes('stat=') && command.includes('$3 !~ /^[ZXx]/')
+            ? this.groups
+            : [...this.groups, ...this.zombieGroups]
+          return { exitCode: 0, stdout: groups.map(group => `${group}\n`).join(''), stderr: '' }
         }
         if (command.startsWith('kill -TERM -- ')) {
           if (this.termFailure !== undefined) throw this.termFailure
@@ -508,6 +512,20 @@ describe('E2B terminal lifecycle', () => {
     await expect(quiescence).resolves.toBe(true)
   })
 
+  it('treats a terminal session containing only zombies as quiescent', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.zombieGroups = [123]
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/zombie-session')
+
+    fake.handle.succeed(0)
+    await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+    expect(fake.commands).toContain(
+      "set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == 123 && $3 !~ /^[ZXx]/ { print $2 }'",
+    )
+  })
+
   it('rejects killing the terminal shell and propagates live foreground failures', async () => {
     const fake = new FakeTerminalSandbox()
     fake.foreground = '123\n'

From 896bcd64a10d74f75a674e278bd816738a31062e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:14:06 +0800
Subject: [PATCH 373/516] fix(e2b): await teardown and honor published status

---
 packages/e2b/subprocess-e2b/src/index.ts      |  5 ++-
 packages/e2b/subprocess-e2b/src/process.ts    | 11 +++--
 .../subprocess-e2b/tests/subprocess.spec.ts   | 43 +++++++++++++++++++
 3 files changed, 54 insertions(+), 5 deletions(-)

diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index bf7edc41a1..4516bffa84 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -67,7 +67,10 @@ export class E2BSubprocessService extends SubprocessService {
       for (const cleanup of failedTerminalSetupCleanups) {
         pending.push(cleanup().then(() => { this.failedTerminalSetupCleanups.delete(cleanup) }))
       }
-      await Promise.all(pending)
+      const outcomes = await Promise.allSettled(pending)
+      for (const outcome of outcomes) {
+        if (outcome.status === 'rejected') throw outcome.reason
+      }
     }, 'e2b subprocess teardown')
   }
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 5387966578..478dc96c30 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -524,10 +524,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           throw new Error(`subprocess-e2b: remote wrapper published invalid exit code ${JSON.stringify(rawStatus)}`)
         }
         if (this.spec.stdio.stdout === 'pipe' || this.spec.stdio.stderr === 'pipe') {
-          return this.commandOutcome(await settlement)
+          return this.commandOutcome(await settlement, exitCode)
         }
         const completed = await withinMs(settlement, this.spec.graceMs)
-        if (completed !== undefined) return this.commandOutcome(completed)
+        if (completed !== undefined) return this.commandOutcome(completed, exitCode)
         this.outputDrainExpired = true
         this.stdoutReader?.invalidateSpill()
         this.stderrReader?.invalidateSpill()
@@ -539,9 +539,12 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     }
   }
 
-  private commandOutcome(settlement: CommandSettlement): SubprocessOutcome {
-    if (settlement.kind === 'result') return { exitCode: settlement.result.exitCode, signal: null }
+  private commandOutcome(settlement: CommandSettlement, publishedExitCode?: number): SubprocessOutcome {
+    if (settlement.kind === 'result') {
+      return { exitCode: publishedExitCode ?? settlement.result.exitCode, signal: null }
+    }
     if (settlement.error instanceof CommandExitError) {
+      if (publishedExitCode !== undefined) return { exitCode: publishedExitCode, signal: null }
       return this.terminationSignal === null
         ? { exitCode: settlement.error.exitCode, signal: null }
         : { exitCode: null, signal: this.terminationSignal }
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index b7d1642bd6..6d20abd3c1 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -547,6 +547,20 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('preserves a published nonzero exit code when termination settles the SDK inside the drain grace', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-signal-settled')
+    await flush()
+    fake.exitStatus = '7\n'
+    fake.afterStatusRead = () => {
+      fake.afterStatusRead = undefined
+      handle.terminate()
+    }
+
+    await expect(handle.done).resolves.toEqual({ exitCode: 7, signal: null })
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
   it('rejects an invalid direct-command exit status', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/invalid-status')
@@ -1336,6 +1350,35 @@ describe('E2BSubprocessService', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
+  it('waits for every owned cleanup before reporting a disposal failure', async () => {
+    const { ctx, fiber } = await service()
+    const failed = {
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw new Error('cleanup failed') }),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+    } as unknown as E2BSubprocessHandle
+    let finishCleanup!: () => void
+    const cleanup = new Promise<boolean>((resolve) => {
+      finishCleanup = () => { resolve(true) }
+    })
+    const draining = {
+      terminate: vi.fn(),
+      waitForExit: vi.fn(() => cleanup),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+    } as unknown as E2BSubprocessHandle
+    const live = (ctx.subprocess as unknown as { live: Set<E2BSubprocessHandle> }).live
+    live.add(failed)
+    live.add(draining)
+
+    let disposed = false
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await flush()
+    expect(disposed).toBe(false)
+    finishCleanup()
+    await disposing
+    expect(live).toEqual(new Set([failed]))
+  })
+
   it('releases naturally settled handles before later service disposal', async () => {
     const fake = new FakeSandbox()
     const { ctx, fiber } = await service(fake)

From cf4b721a8d7a3df38a1152295e098ce0ed3e20f4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 10:27:56 +0800
Subject: [PATCH 374/516] test(e2b): snapshot provider-neutral overlay surface

---
 .../headless-agent/e2b.cordis.snapshot.yml    | 58 +++++++++++++++++++
 .../headless-agent/tests/headless.snapshot.ts | 56 ++++++++++++++++++
 .../tests/snapshots/e2b-overlay/input.json    |  8 +++
 .../e2b-overlay/replay.override.json          | 12 ++++
 .../e2b-overlay/stream-json.expected.jsonl    | 14 +++++
 5 files changed, 148 insertions(+)
 create mode 100644 examples/headless-agent/e2b.cordis.snapshot.yml
 create mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/input.json
 create mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
 create mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl

diff --git a/examples/headless-agent/e2b.cordis.snapshot.yml b/examples/headless-agent/e2b.cordis.snapshot.yml
new file mode 100644
index 0000000000..3f39f0ffe4
--- /dev/null
+++ b/examples/headless-agent/e2b.cordis.snapshot.yml
@@ -0,0 +1,58 @@
+# Keyless counterpart to e2b.cordis.yml. It keeps the same generic PTY, LSP,
+# and subprocess Code Runtime consumers, but supplies their fundamental
+# filesystem/process world locally and replaces the live model with replay.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: llm-deepseek
+        name: '@deepseek-ai/dsh-llm-deepseek'
+        disabled: true
+      - id: cli-agent
+        name: '@deepseek-ai/dsh-cli-demo'
+        config:
+          provider: deepseek
+          model: deepseek-v4-pro
+          persistenceRoot: './.sessions'
+          persistenceCompression: none
+          workspaceContext:
+            maxBytes: 65536
+          tools:
+            mode: both
+          persona: |
+            You are headless-agent, a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}.
+
+            Verify your work by running the code or tests. Keep answers brief and factual.
+      - insert:
+          - id: code-runtime-subprocess
+            name: '@deepseek-ai/dsh-code-runtime-subprocess'
+          - id: tool-cordis
+            name: '@deepseek-ai/dsh-tool-cordis'
+          - id: sandbox
+            name: '@deepseek-ai/dsh-sandbox-local'
+          - id: sandbox-policy
+            name: '@deepseek-ai/dsh-sandbox-policy'
+            config:
+              mode: danger-full-access
+              workspaceRoot: !!js process.cwd()
+          - id: pty
+            name: '@deepseek-ai/dsh-pty'
+          - id: pty-local
+            name: '@deepseek-ai/dsh-pty-local'
+          - id: tool-pty
+            name: '@deepseek-ai/dsh-tool-pty'
+          - id: lsp
+            name: '@deepseek-ai/dsh-lsp'
+          - id: lsp-local
+            name: '@deepseek-ai/dsh-lsp-local'
+            config:
+              servers:
+                typescript:
+                  command: node
+                  extensionToLanguage:
+                    .ts: typescript
+          - id: tool-lsp
+            name: '@deepseek-ai/dsh-tool-lsp'
+          - id: llm-replay
+            name: '@deepseek-ai/dsh-llm-replay'
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 87261439da..ca8e93724c 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -25,6 +25,8 @@ const advancedScenarioDir = join(snapshotsDir, 'advanced-toolchain')
 const advancedSessionFixture = join(advancedScenarioDir, 'session.jsonl')
 const advancedStreamExpected = join(advancedScenarioDir, 'stream-json.expected.jsonl')
 const advancedConfigPath = fileURLToPath(new URL('../advanced.cordis.snapshot.yml', import.meta.url))
+const e2bScenarioDir = join(snapshotsDir, 'e2b-overlay')
+const e2bConfigPath = fileURLToPath(new URL('../e2b.cordis.snapshot.yml', import.meta.url))
 const ptyScenarioDir = join(snapshotsDir, 'pty-tools')
 const ptySessionFixture = join(ptyScenarioDir, 'session.jsonl')
 const ptyStreamExpected = join(ptyScenarioDir, 'stream-json.expected.jsonl')
@@ -608,6 +610,60 @@ describe('headless stream-json snapshots', () => {
     expect(normalized).toBe(await readFile(advancedStreamExpected, 'utf8'))
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
+  it('pins the E2B overlay provider-neutral tool surface', async () => {
+    const prompt = await scenarioPrompt(e2bScenarioDir, 'e2b-overlay')
+    const streamExpected = join(e2bScenarioDir, 'stream-json.expected.jsonl')
+    let runCwd = ''
+    const result = await runLoaderSmoke({
+      label: 'E2B overlay headless stream-json snapshot',
+      tempDirPrefix: 'headless-snapshot-e2b-overlay-',
+      binScript,
+      configPath: e2bConfigPath,
+      binArgs: ['--config', e2bConfigPath, '--output-format', 'stream-json', prompt],
+      tsconfigPath,
+      env: {
+        DSH_SNAPSHOT: 'replay',
+        DSH_SNAPSHOT_FILE: join(e2bScenarioDir, 'session.jsonl'),
+        DSH_SNAPSHOT_OVERRIDE: join(e2bScenarioDir, 'replay.override.json'),
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      prepare: (cwd) => { runCwd = cwd },
+      inspect: async (cwd) => {
+        const logs = await persistedLogs(cwd)
+        expect(logs).toHaveLength(1)
+        const headers = parseJsonl(logs[0]?.content ?? '').filter(record => record.type === 'request/header')
+        expect(headers).toHaveLength(1)
+        const data = headers[0]?.data as JsonObject | undefined
+        const header = data?.header as JsonObject | undefined
+        if (!Array.isArray(header?.tools)) throw new Error('E2B overlay snapshot request has no tool schemas')
+        const toolNames = header.tools.map((tool, index) => {
+          if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) {
+            throw new Error(`E2B overlay snapshot tool schema ${index} is not an object`)
+          }
+          const name = (tool as JsonObject).name
+          if (typeof name !== 'string') throw new Error(`E2B overlay snapshot tool schema ${index} has no name`)
+          return name
+        })
+        expect(toolNames.filter(name => name === 'lsp' || name === 'run_code' || name.startsWith('terminal_')).sort())
+          .toEqual([
+            'lsp',
+            'run_code',
+            'terminal_close',
+            'terminal_list',
+            'terminal_open',
+            'terminal_read',
+            'terminal_send',
+            'terminal_signal',
+          ])
+      },
+    })
+
+    expect(result.stderr).toBe('')
+    const normalized = normalizeHeadlessStream(result.stdout, runCwd)
+    if (refreshing) await writeFile(streamExpected, normalized)
+    expect(normalized).toBe(await readFile(streamExpected, 'utf8'))
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
   it('replays persisted goal tools through the one-shot app', async () => {
     const prompt = await scenarioPrompt(goalScenarioDir, 'goal-tools')
     const streamExpected = join(goalScenarioDir, 'stream-json.expected.jsonl')
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/input.json b/examples/headless-agent/tests/snapshots/e2b-overlay/input.json
new file mode 100644
index 0000000000..00fd27ce2e
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/e2b-overlay/input.json
@@ -0,0 +1,8 @@
+{
+  "steps": [
+    {
+      "op": "prompt",
+      "text": "Report the assembled E2B overlay tool surface."
+    }
+  ]
+}
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json b/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
new file mode 100644
index 0000000000..d1a71ce58c
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
@@ -0,0 +1,12 @@
+[
+  {
+    "kind": "chunks",
+    "chunks": [
+      { "type": "block-start", "index": 0, "blockType": "text" },
+      { "type": "text-delta", "index": 0, "text": "E2B_SURFACE_OK" },
+      { "type": "block-end", "index": 0, "block": { "type": "text", "text": "E2B_SURFACE_OK" } },
+      { "type": "usage", "usage": { "inputTokens": 8, "outputTokens": 3 } },
+      { "type": "finish", "reason": { "kind": "stop" } }
+    ]
+  }
+]
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl
new file mode 100644
index 0000000000..2fb74415cb
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl
@@ -0,0 +1,14 @@
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Report the assembled E2B overlay tool surface."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"session/title","seq":2,"time":0,"data":{"title":"Report the assembled E2B overlay","messageSeqs":[1],"source":{"kind":"fallback"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-pro"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"E2B_SURFACE_OK"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"E2B_SURFACE_OK"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":8,"outputTokens":3}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":10,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"E2B_SURFACE_OK"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-pro"},"id":"{{sessionId}}"},"usage":{"inputTokens":8,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":11,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":12,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
+{"type":"result","success":true,"sessionId":"{{sessionId}}","turn":1,"result":"E2B_SURFACE_OK","reason":{"kind":"completed"},"usage":{"inputTokens":8,"outputTokens":3}}

From c122d984c4905d2d5d404fbe7686deded7737b07 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 11:23:01 +0800
Subject: [PATCH 375/516] fix(e2b): harden cancellation and teardown boundaries

---
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/index.ts                 |   8 +-
 packages/e2b/e2b/tests/e2b.spec.ts            |  48 ++++++-
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   2 +-
 packages/e2b/fs-e2b/README.zh.md              |   2 +-
 packages/e2b/fs-e2b/src/index.ts              |   2 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |   1 +
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   5 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   5 +-
 packages/e2b/subprocess-e2b/src/process.ts    |  34 ++++-
 packages/e2b/subprocess-e2b/src/terminal.ts   |  47 +++++--
 .../subprocess-e2b/tests/subprocess.spec.ts   |  98 +++++++++++++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 121 +++++++++++++++++-
 17 files changed, 351 insertions(+), 38 deletions(-)

diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 46ff37b222..2fc8d403d1 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: ccafa9df480e3812d3d3b6d25b513e7b5d2afc9f
-README.zh.md: 60eefd46a0a9a017f4db57e4dc5313d533eeba04
+README.md: 6eb7d69dd6355de870db6bf05540f2629f464bc8
+README.zh.md: b2e2616cf779bce659fdef58840aa51f095a73cf
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index ccafa9df48..6eb7d69dd6 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -30,7 +30,7 @@ Set `sandboxId` to reconnect a running or paused sandbox instead of creating one
 
 Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
 
-Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` means a kill-on-timeout sandbox is already quiescent; every other disposition failure rejects teardown. A newly created sandbox is killed when initial directory setup fails; if that rollback fails, disposal retries it before releasing ownership. A reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
+Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` is accepted when disposal requests `kill`, or when this service created a sandbox with `onTimeout: kill`; otherwise, a not-found error from a requested `pause` rejects teardown because retention was not proved. A newly created sandbox is killed when initial directory setup fails; if that rollback fails, disposal retries it before releasing ownership. A reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
 
 `pause` and `leave` retain remote filesystem and adapter artifacts for a later `sandboxId` connection, but a later harness process receives only a new SDK handle. The subprocess service still fulfills its seam contract by terminating managed groups before owner disposal; neither disposition recovers prior process objects, output cursors, or in-memory adapter locks.
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 60eefd46a0..b2e2616cf7 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -30,7 +30,7 @@
 
 构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
 
-资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 表示因超时终止的沙箱已经完全停稳；其他处置失败都会使 teardown 拒绝。新建沙箱的初始目录设置失败时，服务会终止该沙箱；如果该回滚失败，资源释放会在解除所有权前重试。重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 仅在资源释放请求 `kill`，或本服务创建了配置为 `onTimeout: kill` 的沙箱时才可接受；否则，`pause` 请求返回的未找到错误会导致 teardown 拒绝，因为无法证明保留成功。新建沙箱的初始目录设置失败时，服务会终止该沙箱；如果该回滚失败，资源释放会在解除所有权前重试。重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
 `pause` 和 `leave` 会保留远程文件系统及适配器产物，供稍后的 `sandboxId` 连接使用，但后续 harness 进程只会获得新的 SDK 句柄。进程管理服务仍会履行其 seam 契约，在所有者释放前终止受管进程组；这两种处置方式都不会恢复先前的进程对象、输出游标或内存中的适配器锁。
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 31e4f911a2..150961a897 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -181,9 +181,13 @@ export class E2BSandboxService extends Service {
             return
         }
       } catch (error: unknown) {
-        // A kill-on-timeout sandbox is already quiescent; every other disposal
-        // failure still reports that the configured final disposition is unknown.
         if (!(error instanceof SandboxNotFoundError)) throw error
+        // Missing proves the requested disposition only when this owner asked
+        // for deletion or created the sandbox with timeout deletion. A
+        // reconnected sandbox's creation lifecycle is unknown.
+        if (this.config.onDispose === 'kill') return
+        if (this.created && this.config.onTimeout === 'kill') return
+        throw error
       }
     }, 'e2b sandbox teardown')
   }
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index fea24fa1cd..a4eba5ebc9 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -160,15 +160,59 @@ describe('E2BSandboxService', () => {
     expect(fixture.pause).toHaveBeenCalledOnce()
   })
 
-  it('does not classify other disposal failures as an already-gone sandbox', async () => {
+  it('accepts a missing sandbox when disposal itself requests deletion', async () => {
     const fixture = fakeSandbox()
-    fixture.kill.mockRejectedValue(new Error('disposition unknown'))
+    fixture.kill.mockRejectedValue(new SandboxNotFoundError('already deleted'))
     sdk.create.mockResolvedValue(fixture.sandbox)
     const ctx = new Context()
+    const errors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    await ctx.e2b.getSandbox()
+
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+    expect(errors).toEqual([])
+  })
+
+  it('does not classify other disposal failures as an already-gone sandbox', async () => {
+    const fixture = fakeSandbox()
+    const failure = new Error('disposition unknown')
+    fixture.kill.mockRejectedValue(failure)
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const errors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
     const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
     await ctx.e2b.getSandbox()
     await expect(fiber.dispose()).resolves.toBeUndefined()
     expect(fixture.kill).toHaveBeenCalledOnce()
+    expect(errors).toContain(failure)
+  })
+
+  it.each([
+    ['a created pause-on-timeout sandbox', false],
+    ['a reconnected sandbox with unknown creation policy', true],
+  ] as const)('reports missing during pause disposal for %s', async (_label, reconnect) => {
+    const fixture = fakeSandbox()
+    const failure = new SandboxNotFoundError('sandbox unexpectedly missing')
+    fixture.pause.mockRejectedValue(failure)
+    if (reconnect) sdk.connect.mockResolvedValue(fixture.sandbox)
+    else sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const errors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
+    const fiber = await ctx.plugin(E2BSandboxService, {
+      apiKey: 'test-key',
+      onTimeout: reconnect ? 'kill' : 'pause',
+      onDispose: 'pause',
+      ...(reconnect ? { sandboxId: 'existing' } : {}),
+    })
+    await ctx.e2b.getSandbox()
+
+    await expect(fiber.dispose()).resolves.toBeUndefined()
+    expect(fixture.pause).toHaveBeenCalledOnce()
+    expect(errors).toContain(failure)
   })
 
   it('reconnects without applying creation lifecycle options and can leave state running', async () => {
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 3c2b30ad15..87f1c7c69b 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: 8abf130ce16e2b79cda5fc858182159442f9e3c3
-README.zh.md: 943d9603046ad9b2a65f41d5801cac882040a0ff
+README.md: bb92b5785383e9703a382fddefcd1cff9b2644cb
+README.zh.md: 57ebfdbb92799660e74078fcd0affcc8d5bc120a
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index 8abf130ce1..bb92b57853 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -11,7 +11,7 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
 - **Stable bounded reads** — a dependency-free Node helper walks directory descriptors with no-follow opens and reads one held regular-file descriptor through the byte cap. Generic LSP queries therefore reject parent swaps, non-files, invalid UTF-8, and growth past the configured document limit before server startup.
 - **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
-- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at SDK request boundaries; a successful rename is the commit point.
+- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before rename. The signal is not forwarded into the rename RPC, so cancellation cannot interrupt the atomic commit; a successful rename is the commit point.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
 
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 943d960304..57ebfdbb92 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -11,7 +11,7 @@
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
 - **稳定的有界读取**：一个零依赖 Node 辅助程序会以不跟随链接的方式逐级打开目录描述符，并通过一个持续持有的常规文件描述符读取至字节上限。因此，通用 LSP 查询会在服务器启动前拒绝父目录交换、非文件、无效 UTF-8，以及增长后超出所配置文档上限的文件。
 - **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
-- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。
+- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在 rename 前立即检查。信号不会传入 rename RPC，因此取消无法中断原子提交；成功 rename 是提交点。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
 
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 0824c3f87c..d41c2e3d32 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -518,7 +518,7 @@ export class E2BFileSystem extends FileSystem {
         signalOpts(signal),
       )
       assertNotAborted(signal, 'write')
-      const committed = await sandbox.files.rename(temporary, targetPath, signalOpts(signal))
+      const committed = await sandbox.files.rename(temporary, targetPath)
       try {
         await sandbox.files.remove(stagingDirectory)
       } catch (_committedStagingCleanupFailure) {
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 303f99c1e8..1689fb4023 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -209,6 +209,7 @@ class FakeRemote {
         this.nodes.set(to, node)
         this.renames.push({ from, to })
         this.abortAfterRename?.abort('after commit')
+        this.checkAbort(options)
         return this.info(to)
       },
       remove: async (path: string): Promise<void> => {
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 0a9baf6d27..8378cfa114 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 1c05509308e4f8b8b07cffd85e289b3ebee70318
-README.zh.md: b536d4e9d083076eccef4ca238dda1b2a503bee1
+README.md: 66481fb1c5edd4c124c2c58aaa5c86a1683e5a3b
+README.zh.md: 5e4b8bbe401cf4a565ccd53270df9fb6b5de9315
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 1c05509308..66481fb1c5 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -10,8 +10,9 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
 - **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
-- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination; raw pipes instead await lossless transport completion and preserve backpressure. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
 The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index b536d4e9d0..5e4b8bbe40 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -10,8 +10,9 @@
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
 - **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个有效的 `spec.env` 条目恢复为调用方显式选择；空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
-- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用；原始 pipe 则会等待无损传输完成并保留背压。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
 基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 478dc96c30..c7d19e0ab8 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -6,6 +6,7 @@ import { posix } from 'node:path'
 import {
   CommandExitError,
   FileNotFoundError,
+  SandboxNotFoundError,
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
@@ -115,7 +116,7 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
     `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
     `mapfile -d '' -t dsh_e2b_env < ${quoteE2BShellArg(paths.environment)}`,
     `"$dsh_e2b_rm" -f -- ${quoteE2BShellArg(paths.environment)}`,
-    `"$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
+    `"$dsh_e2b_env_bin" -i -- "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
     'dsh_e2b_status=$?',
     `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
     'wait',
@@ -136,7 +137,7 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
     'for dsh_e2b_tool in "$dsh_e2b_env_bin" "$dsh_e2b_setsid" "$dsh_e2b_bash" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm"; do',
     '  [[ "$dsh_e2b_tool" == /* && -x "$dsh_e2b_tool" ]] || exit 125',
     'done',
-    `exec "$dsh_e2b_env_bin" -i "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm" ${argv}`,
+    `exec "$dsh_e2b_env_bin" -i -- "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm" ${argv}`,
   ].join('\n')
   return bootstrap
 }
@@ -196,6 +197,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly readyState = Promise.withResolvers<CommandHandle>()
   private readonly stdoutDecoder = new E2BBase64Decoder()
   private readonly stderrDecoder = new E2BBase64Decoder()
+  private readonly outputTermination = new AbortController()
   private readonly stdoutReader: E2BOutputReader | undefined
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
@@ -262,6 +264,9 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   terminate(): void {
     if (this.terminationFenced || this.quiescenceProven || this.terminationAttempt !== undefined) return
     this.terminationStarted = true
+    this.outputTermination.abort()
+    this.stdout?.destroy()
+    this.stderr?.destroy()
     this.terminationFailure = undefined
     const attempt = this.terminateRemote()
     this.terminationAttempt = attempt
@@ -317,6 +322,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       sandbox = await this.runtime.getSandbox()
     } catch (error: unknown) {
       if (isAborted(signal)) return false
+      if (error instanceof SandboxNotFoundError) {
+        this.markQuiescent()
+        return true
+      }
       throw error
     }
     const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
@@ -469,21 +478,25 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: Uint8Array): Promise<void> {
     const target = pipe ?? inherited
-    if (target === undefined || data.length === 0) return
+    if (target === undefined || data.length === 0 || this.outputTermination.signal.aborted) return
     if (target.destroyed) throw new Error('subprocess output stream is closed')
     if (target.write(data)) return
     await new Promise<void>((resolve, reject) => {
       const onDrain = (): void => { cleanup(); resolve() }
       const onClose = (): void => { cleanup(); resolve() }
+      const onTermination = (): void => { cleanup(); resolve() }
       const onError = (error: Error): void => { cleanup(); reject(error) }
       const cleanup = (): void => {
         target.removeListener('drain', onDrain)
         target.removeListener('close', onClose)
         target.removeListener('error', onError)
+        this.outputTermination.signal.removeEventListener('abort', onTermination)
       }
       target.once('drain', onDrain)
       target.once('close', onClose)
       target.once('error', onError)
+      this.outputTermination.signal.addEventListener('abort', onTermination, { once: true })
+      if (this.outputTermination.signal.aborted) onTermination()
     })
   }
 
@@ -580,6 +593,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async terminateRemote(): Promise<void> {
+    try {
+      await this.terminateRemoteInSandbox()
+    } catch (error: unknown) {
+      if (error instanceof SandboxNotFoundError) {
+        this.markQuiescent()
+        return
+      }
+      throw error
+    }
+  }
+
+  private async terminateRemoteInSandbox(): Promise<void> {
     const handle = await this.commandState.promise
     if (handle === undefined) return
     if (!isValidProcessId(handle.pid) && this.remotePid <= 0) {
@@ -671,7 +696,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       await sandbox.commands.run(`kill -${signal} -- -${pid}`)
       return true
     } catch (error: unknown) {
-      if (error instanceof CommandExitError) return false
+      if (error instanceof CommandExitError || error instanceof SandboxNotFoundError) return false
       throw error
     }
   }
@@ -682,6 +707,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       signalOpts(signal),
     ).catch((error: unknown) => {
       if (signal?.aborted === true) return undefined
+      if (error instanceof SandboxNotFoundError) return { exitCode: 0, stdout: '', stderr: '' }
       throw error
     })
     return result?.stdout.trim() === 'live'
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index be79199b58..f918f802ba 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -7,6 +7,7 @@ import { posix } from 'node:path'
 import {
   CommandExitError,
   FileNotFoundError,
+  SandboxNotFoundError,
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
@@ -37,7 +38,7 @@ const TERMINAL_RUNNER_SOURCE = [
   'fi',
   'printf \'%s\' "$dsh_output_marker"',
   "printf 'ready\\n' > \"$dsh_state/ready\"",
-  'exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"',
+  'exec env -i -- "${dsh_env[@]}" "${dsh_argv[@]}"',
   '',
 ].join('\n')
 
@@ -169,9 +170,15 @@ async function waitUntilReady(
 }
 
 async function sessionProcessGroups(sandbox: Sandbox, sessionId: number): Promise<number[]> {
-  const result = await sandbox.commands.run(
-    `set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == ${sessionId} && $3 !~ /^[ZXx]/ { print $2 }'`,
-  )
+  let result: CommandResult
+  try {
+    result = await sandbox.commands.run(
+      `set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == ${sessionId} && $3 !~ /^[ZXx]/ { print $2 }'`,
+    )
+  } catch (error: unknown) {
+    if (error instanceof SandboxNotFoundError) return []
+    throw error
+  }
   const groups = new Set<number>()
   for (const raw of result.stdout.trim().split(/\s+/)) {
     if (raw.length === 0) continue
@@ -191,7 +198,7 @@ async function signalGroups(sandbox: Sandbox, groups: number[], signal: 'TERM' |
   try {
     await sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
   } catch (error: unknown) {
-    if (!(error instanceof CommandExitError)) throw error
+    if (!(error instanceof CommandExitError) && !(error instanceof SandboxNotFoundError)) throw error
   }
 }
 
@@ -253,6 +260,7 @@ async function rollbackUnpublishedTerminal(
       try {
         await sandbox.pty.kill(handle.pid)
       } catch (error: unknown) {
+        if (error instanceof SandboxNotFoundError) return
         attemptFailures.push(asError(error))
       }
     }
@@ -262,6 +270,7 @@ async function rollbackUnpublishedTerminal(
       try {
         await handle.kill()
       } catch (error: unknown) {
+        if (error instanceof SandboxNotFoundError) return
         attemptFailures.push(asError(error))
       }
     }
@@ -291,7 +300,11 @@ async function rollbackUnpublishedTerminal(
       'subprocess-e2b: terminal setup rollback did not reach quiescence',
     )
   }
-  await handle.disconnect()
+  try {
+    await handle.disconnect()
+  } catch (error: unknown) {
+    if (!(error instanceof SandboxNotFoundError)) throw error
+  }
 }
 
 /** One E2B PTY and all process groups in its remote process session. */
@@ -400,7 +413,14 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     }
     if (groups.length > 0 || !this.topLevelExited) {
       this.terminationSignal = 'SIGKILL'
-      if (!this.topLevelExited) await this.sandbox.pty.kill(this.pid)
+      if (!this.topLevelExited) {
+        try {
+          await this.sandbox.pty.kill(this.pid)
+        } catch (error: unknown) {
+          if (error instanceof SandboxNotFoundError) return
+          throw error
+        }
+      }
       groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.graceMs, true)
       if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
     }
@@ -410,7 +430,11 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     if (!this.topLevelExited) {
       throw new Error(`subprocess-e2b: terminal cleanup failed; surviving pid: ${this.pid}`)
     }
-    await this.handle.disconnect()
+    try {
+      await this.handle.disconnect()
+    } catch (error: unknown) {
+      if (!(error instanceof SandboxNotFoundError)) throw error
+    }
     await this.sandbox.files.remove(this.stateDir).catch(() => {})
   }
 }
@@ -468,11 +492,11 @@ export async function spawnE2BTerminal(
       cwd: spec.cwd,
       envs: { TERM: 'dumb' },
       timeoutMs: 0,
-      ...signalOpts(spec.signal),
       onData: (data) => { outputFilter.push(data) },
     })
     completion = handle.wait()
     void completion.catch(() => {})
+    spec.signal?.throwIfAborted()
     if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
       throw new Error(`subprocess-e2b: E2B returned invalid terminal pid ${handle.pid}`)
     }
@@ -503,7 +527,8 @@ export async function spawnE2BTerminal(
           else await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
           terminalQuiescent = true
         } catch (cleanupError: unknown) {
-          failures.push(asError(cleanupError))
+          if (cleanupError instanceof SandboxNotFoundError) terminalQuiescent = true
+          else failures.push(asError(cleanupError))
         }
       }
       if (!stateRemoved) {
@@ -511,7 +536,7 @@ export async function spawnE2BTerminal(
           await sandbox.files.remove(stateDir)
           stateRemoved = true
         } catch (stateError: unknown) {
-          if (stateError instanceof FileNotFoundError) stateRemoved = true
+          if (stateError instanceof FileNotFoundError || stateError instanceof SandboxNotFoundError) stateRemoved = true
           else failures.push(asError(stateError))
         }
       }
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 6d20abd3c1..680d309bbb 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -3,6 +3,7 @@ import { Context } from 'cordis'
 import {
   CommandExitError,
   FileNotFoundError,
+  SandboxNotFoundError,
   type CommandHandle,
   type CommandResult,
   type Sandbox,
@@ -371,7 +372,13 @@ describe('E2BSubprocessHandle', () => {
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
       argv: ['tool', 'argument with spaces'],
       stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 8, spill: { maxBytes: 32 } } },
-      env: { PATH: '/bin', 'FOO-BAR': 'hyphen-value', DEEPSEEK_API_KEY: 'explicit-secret', DSH_MODE: 'test' },
+      env: {
+        PATH: '/bin',
+        'FOO-BAR': 'hyphen-value',
+        '--split-string': 'literal-value',
+        DEEPSEEK_API_KEY: 'explicit-secret',
+        DSH_MODE: 'test',
+      },
     }), '/workspace/.dsh-e2b/processes/one')
     expect(handle.pid).toBe(-1)
     handle.stdin!.write('hello')
@@ -394,7 +401,8 @@ describe('E2BSubprocessHandle', () => {
     expect(command).toContain('mapfile -d')
     expect(command).toContain('dsh_e2b_node="$(command -v node)"')
     expect(command).toContain('"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e')
-    expect(command).toContain('exec "$dsh_e2b_env_bin" -i "${dsh_e2b_env[@]}"')
+    expect(command).toContain('"$dsh_e2b_env_bin" -i -- "${dsh_e2b_env[@]}" "$@"')
+    expect(command).toContain('exec "$dsh_e2b_env_bin" -i -- "${dsh_e2b_env[@]}"')
     expect(command).toContain('>&2 2>/dev/null')
     expect(command).not.toContain('2>/dev/null >&2')
     expect(command).toContain('base64')
@@ -405,7 +413,7 @@ describe('E2BSubprocessHandle', () => {
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
     expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
-      'PATH=/bin\0KEEP=safe\0FOO-BAR=hyphen-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+      'PATH=/bin\0KEEP=safe\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
     )
 
     let piped = ''
@@ -1088,6 +1096,52 @@ describe('E2BSubprocessHandle', () => {
     await handle.done
   })
 
+  it('treats a timeout-killed sandbox as quiescent during liveness probing', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/expired-sandbox')
+    await flush()
+    fake.finish()
+    await handle.done
+    fake.probeError = new SandboxNotFoundError('sandbox expired')
+
+    await expect(handle.waitForExit()).resolves.toBe(true)
+  })
+
+  it('treats a missing sandbox handle as quiescent during liveness acquisition', async () => {
+    const fake = new FakeSandbox()
+    let calls = 0
+    const handle = new E2BSubprocessHandle(runtime(fake, async () => {
+      calls += 1
+      if (calls === 1) return fake.sandbox
+      throw new SandboxNotFoundError('sandbox expired')
+    }), spec(), '/runtime/expired-acquisition')
+    await flush()
+
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    await fake.completeOutput()
+    fake.alive = false
+    fake.handle.succeed(0)
+    await handle.done
+  })
+
+  it('treats sandbox loss during termination as quiescent', async () => {
+    const fake = new FakeSandbox()
+    let calls = 0
+    const handle = new E2BSubprocessHandle(runtime(fake, async () => {
+      calls += 1
+      if (calls === 1) return fake.sandbox
+      throw new SandboxNotFoundError('sandbox expired')
+    }), spec(), '/runtime/expired-termination')
+    await flush()
+    await fake.completeOutput()
+
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    fake.alive = false
+    fake.handle.succeed(0)
+    await handle.done
+  })
+
   it('makes batch stdin close failures best-effort', async () => {
     const fake = new FakeSandbox()
     vi.spyOn(fake.handle, 'sendStdin').mockRejectedValueOnce(new Error('closed'))
@@ -1233,6 +1287,44 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
   })
 
+  it('breaks output backpressure when termination owns the command', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/backpressure-termination')
+    await flush()
+
+    const stdoutWrite = vi.spyOn(handle.stdout!, 'write').mockReturnValueOnce(false)
+    let released = false
+    const pending = fake.stdout('blocked').then(() => { released = true })
+    await Promise.resolve()
+    handle.terminate()
+    await flush()
+    const releasedByTermination = released
+    if (!released) handle.stdout!.emit('drain')
+    await pending
+    stdoutWrite.mockRestore()
+    await handle.done
+
+    expect(releasedByTermination).toBe(true)
+  })
+
+  it('settles backpressure when a synchronous pipe write starts termination', async () => {
+    const fake = new FakeSandbox()
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
+    }), '/runtime/backpressure-synchronous-termination')
+    await flush()
+
+    const stdoutWrite = vi.spyOn(handle.stdout!, 'write').mockImplementationOnce(() => {
+      handle.terminate()
+      return false
+    })
+    await expect(fake.stdout('blocked')).resolves.toBeUndefined()
+    stdoutWrite.mockRestore()
+    await handle.done
+  })
+
   it('contains a pipe callback failure instead of rejecting command settlement', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index b47cb8ffb1..c6ec5bfaad 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -6,6 +6,7 @@ import { describe, expect, it, vi } from 'vitest'
 import {
   CommandExitError,
   FileNotFoundError,
+  SandboxNotFoundError,
   type CommandHandle,
   type CommandResult,
   type Sandbox,
@@ -113,6 +114,18 @@ class FakeTerminalSandbox {
   requestedOutput = 'requested-shell$ '
   emitOutputMarker = true
   afterSessionLookup: (() => void) | undefined
+  private createGate: Promise<undefined> | undefined
+  private releaseCreateGate: (() => void) | undefined
+
+  deferCreate(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.createGate = gate.promise
+    this.releaseCreateGate = () => { gate.resolve(undefined) }
+  }
+
+  releaseCreate(): void {
+    this.releaseCreateGate?.()
+  }
 
   readonly sandbox = {
     files: {
@@ -183,6 +196,8 @@ class FakeTerminalSandbox {
       create: async (options: Parameters<Sandbox['pty']['create']>[0]): Promise<CommandHandle> => {
         this.createOptions = options
         if (this.createError !== undefined) throw this.createError
+        await this.createGate
+        options.signal?.throwIfAborted()
         await options.onData(Buffer.from('buffered banner\n'))
         return this.handle.asHandle()
       },
@@ -258,7 +273,7 @@ describe('E2B terminal allocation', () => {
     const runner = fake.writes.get('/runtime/terminal-one/runner.bash') ?? ''
     expect(runner).toContain('if (( ${#dsh_argv[@]} == 0 )); then')
     expect(runner).toContain('printf \'%s\' "$dsh_output_marker"')
-    expect(runner).toContain('exec env -i "${dsh_env[@]}" "${dsh_argv[@]}"')
+    expect(runner).toContain('exec env -i -- "${dsh_env[@]}" "${dsh_argv[@]}"')
     expect(runner).not.toContain('\u007f')
     terminal.output.destroy()
     await fake.createOptions?.onData(Buffer.from('late bootstrap callback'))
@@ -296,6 +311,25 @@ describe('E2B terminal allocation', () => {
     await expect(terminal.waitForExit()).resolves.toBe(true)
   })
 
+  it('publishes the PTY handle before honoring allocation cancellation', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.deferCreate()
+    const controller = new AbortController()
+    const spawning = spawnE2BTerminal(
+      runtime(fake),
+      spec({ signal: controller.signal }),
+      '/runtime/allocation-cancel',
+    )
+    await vi.waitFor(() => { expect(fake.createOptions).toBeDefined() })
+
+    controller.abort(new Error('allocation cancelled'))
+    fake.releaseCreate()
+    await expect(spawning).rejects.toThrow('allocation cancelled')
+    expect(fake.createOptions?.signal).toBeUndefined()
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
   it('rejects malformed environment and argv values before PTY allocation', async () => {
     const invalidName = new FakeTerminalSandbox()
     await expect(spawnE2BTerminal(runtime(invalidName), spec({ env: { 'BAD=NAME': 'x' } }), '/runtime/name'))
@@ -410,6 +444,44 @@ describe('E2B terminal allocation', () => {
     cleanupFailed.removeError = new Error('remove transport failed')
     await expect(spawnE2BTerminal(runtime(cleanupFailed), spec(), '/runtime/cleanup-failed'))
       .rejects.toThrow('invalid terminal pid 0')
+
+    const expiredDuringRollback = new FakeTerminalSandbox()
+    expiredDuringRollback.sendError = new Error('bootstrap failed before timeout')
+    expiredDuringRollback.groups = []
+    expiredDuringRollback.settleOnPtyKill = false
+    expiredDuringRollback.ptyKillError = new SandboxNotFoundError('sandbox expired')
+    expiredDuringRollback.removeError = new SandboxNotFoundError('sandbox expired')
+    await expect(spawnE2BTerminal(runtime(expiredDuringRollback), spec(), '/runtime/expired-rollback'))
+      .rejects.toThrow('bootstrap failed before timeout')
+    expect(expiredDuringRollback.ptyKills).toBe(1)
+
+    const expiredBeforeSdkRollback = new FakeTerminalSandbox()
+    expiredBeforeSdkRollback.handle.waitError = new Error('wait failed after timeout')
+    expiredBeforeSdkRollback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
+    expiredBeforeSdkRollback.handle.settleOnSdkKill = false
+    await expect(spawnE2BTerminal(runtime(expiredBeforeSdkRollback), spec(), '/runtime/expired-sdk-rollback'))
+      .rejects.toThrow('wait failed after timeout')
+
+    const expiredDuringSdkFallback = new FakeTerminalSandbox()
+    expiredDuringSdkFallback.sendError = new Error('bootstrap failed before SDK fallback')
+    expiredDuringSdkFallback.groups = []
+    expiredDuringSdkFallback.settleOnPtyKill = false
+    expiredDuringSdkFallback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
+    expiredDuringSdkFallback.handle.settleOnSdkKill = false
+    await expect(spawnE2BTerminal(runtime(expiredDuringSdkFallback), spec(), '/runtime/expired-sdk-fallback'))
+      .rejects.toThrow('bootstrap failed before SDK fallback')
+
+    const missingDuringDisconnect = new FakeTerminalSandbox()
+    missingDuringDisconnect.sendError = new Error('bootstrap failed before disconnect')
+    missingDuringDisconnect.handle.disconnectError = new SandboxNotFoundError('sandbox expired')
+    await expect(spawnE2BTerminal(runtime(missingDuringDisconnect), spec(), '/runtime/missing-disconnect'))
+      .rejects.toThrow('bootstrap failed before disconnect')
+
+    const failedDisconnect = new FakeTerminalSandbox()
+    failedDisconnect.sendError = new Error('bootstrap failed with disconnect failure')
+    failedDisconnect.handle.disconnectError = new Error('disconnect transport failed')
+    await expect(spawnE2BTerminal(runtime(failedDisconnect), spec(), '/runtime/failed-disconnect'))
+      .rejects.toThrow('bootstrap failed with disconnect failure')
   })
 
   it('propagates setup cancellation and provider failures', async () => {
@@ -526,6 +598,53 @@ describe('E2B terminal lifecycle', () => {
     )
   })
 
+  it('treats a timeout-killed sandbox as quiescent during terminal cleanup', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/expired-sandbox')
+    fake.sessionGroupsFailure = new SandboxNotFoundError('sandbox expired')
+    fake.handle.succeed(0)
+
+    await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+  })
+
+  it('treats sandbox disappearance during PTY kill as quiescent', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.settleOnPtyKill = false
+    fake.ptyKillError = new SandboxNotFoundError('sandbox expired')
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
+
+    terminal.terminate()
+    await expect(terminal.waitForExit()).resolves.toBe(true)
+    expect(fake.ptyKills).toBe(1)
+  })
+
+  it('propagates a non-missing PTY kill failure', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.settleOnPtyKill = false
+    fake.ptyKillError = new Error('PTY kill transport failed')
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
+
+    terminal.terminate()
+    await expect(terminal.waitForExit()).rejects.toThrow('PTY kill transport failed')
+  })
+
+  it.each([
+    ['accepts sandbox loss', new SandboxNotFoundError('sandbox expired'), true],
+    ['propagates another failure', new Error('disconnect failed'), false],
+  ] as const)('%s while disconnecting a settled terminal', async (_label, failure, accepted) => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), `/runtime/disconnect-${accepted}`)
+    fake.handle.disconnectError = failure
+    fake.groups = []
+    fake.handle.succeed(0)
+
+    if (accepted) await expect(terminal.waitForExit()).resolves.toBe(true)
+    else await expect(terminal.waitForExit()).rejects.toThrow('disconnect failed')
+  })
+
   it('rejects killing the terminal shell and propagates live foreground failures', async () => {
     const fake = new FakeTerminalSandbox()
     fake.foreground = '123\n'

From ca79f4364c63c3f0d7a9ace8c127fc2f696e5fdf Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 12:15:18 +0800
Subject: [PATCH 376/516] test(e2b): prove stale interrupt isolation

---
 .../tests/fixtures/e2b/e2b/bin.ts             | 30 +++++++++++++++++--
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 6fa95c24b6..b4acfd1e5a 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -252,14 +252,38 @@ try {
   }
   const staleInterrupt = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 0.2', submit: true })
   if (!staleInterrupt.cancel()) throw new Error('E2B PTY refused the stale-interrupt probe cancellation')
-  await staleInterrupt.done
-  const sleeping = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 30', submit: true })
+  let canceledSendRetained = false
+  try {
+    ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 30', submit: true })
+  } catch (error: unknown) {
+    canceledSendRetained = String(error).includes('active send')
+  }
   foregroundLookup.resolve(undefined)
+  await staleInterrupt.done
+  remoteCommands.run = runRemoteCommand
+  if (!canceledSendRetained) throw new Error('E2B PTY released a canceled send before foreground signalling settled')
+  const sleeping = ctx.pty.startSend(owner, terminal.sessionId, {
+    text: "printf 'DSH_SLEEP_%s\\n' READY; sleep 30",
+    submit: true,
+  })
+  let sleepReadyOutput = ''
+  const sleepReadyDeadline = Date.now() + 5_000
+  while (!sleepReadyOutput.includes('DSH_SLEEP_READY\n')) {
+    sleepReadyOutput += sleeping.readOutput().delta
+    if (sleepReadyOutput.includes('DSH_SLEEP_READY\n')) break
+    const settled = await Promise.race([
+      sleeping.done.then(result => ({ result })),
+      new Promise<undefined>(resolveDelay => setTimeout(() => { resolveDelay(undefined) }, 25)),
+    ])
+    if (settled !== undefined) {
+      throw new Error(`E2B PTY successor settled before executing: ${JSON.stringify(settled.result)}`)
+    }
+    if (Date.now() >= sleepReadyDeadline) throw new Error(`E2B PTY successor did not execute: ${sleepReadyOutput}`)
+  }
   const interruptIdentitySafe = await Promise.race([
     sleeping.done.then(() => false),
     new Promise<true>(resolveDelay => setTimeout(() => { resolveDelay(true) }, 300)),
   ])
-  remoteCommands.run = runRemoteCommand
   if (!delayedForegroundLookup || !interruptIdentitySafe) {
     throw new Error('E2B PTY stale interrupt affected its successor send')
   }

From 091af03a81319ccadde487a981933558de3c7c60 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 13:01:37 +0800
Subject: [PATCH 377/516] fix(e2b): harden remote startup and teardown

---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |   2 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |   2 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   8 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   8 +-
 .../e2b/subprocess-e2b/src/environment.ts     |  24 ++++
 packages/e2b/subprocess-e2b/src/process.ts    |  42 +++++--
 packages/e2b/subprocess-e2b/src/terminal.ts   |   8 +-
 .../subprocess-e2b/tests/subprocess.spec.ts   | 109 +++++++++++++++++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |   9 +-
 11 files changed, 182 insertions(+), 38 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 079924ac74..1343d33032 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 02de8df021094fa326431a996cd183d13b9c0c8c
-2026-07-27-e2b-remote-runtime-poc.zh.md: 3b7ddf761b2cbf950898a0083cf9da653d20e723
+2026-07-27-e2b-remote-runtime-poc.md: cccee91998e832cc9cf53e554e104ccc5caada38
+2026-07-27-e2b-remote-runtime-poc.zh.md: b1a30c92e313b1395006ebd4fd17eacda2546ad5
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index 02de8df021..cccee91998 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -28,7 +28,7 @@ E2B owns the mutable filesystem, managed command and Bash processes, terminal al
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. For ordinary command pipes, its remote wrapper branches raw spill bytes before framing each live chunk as newline-delimited base64 ASCII; the host restores raw bytes across arbitrary decoded SDK callback boundaries. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
+The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. Ambient environments and ordinary command pipes cross decoded SDK callback boundaries as ASCII/base64 before strict UTF-8 or raw-byte restoration; startup preparation carries the handle's owned cancellation signal, and provisional termination proves the remote group empty after SDK fallback. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index 3b7ddf761b..b1a30c92e3 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -28,7 +28,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。对于普通命令管道，其远程包装层会先分流原始 spill 字节，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意已解码 SDK 回调边界恢复原始字节。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
+基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。环境快照与普通命令管道会先以 ASCII/base64 跨越已解码的 SDK 回调边界，再执行严格 UTF-8 解码或恢复原始字节；启动准备会携带句柄自有的取消信号，临时终止则会在 SDK 回退后证明远程进程组为空。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 8378cfa114..3f64c67b7e 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 66481fb1c5edd4c124c2c58aaa5c86a1683e5a3b
-README.zh.md: 5e4b8bbe401cf4a565ccd53270df9fb6b5de9315
+README.md: aaac559e60162c3051cc6f06cbcfac011f5eb59a
+README.zh.md: 904e4fd1d9a13082ddfc8183c0e42abc25bd1caf
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 66481fb1c5..aaac559e60 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -6,15 +6,15 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 ## Behavior
 
-- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication, while cancellation can stop the provisional SDK handle first.
+- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses the provisional SDK handle; if publication fails, rollback kills and verifies the provisional group before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — the wrapper starts from the sandbox command environment, removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names, then restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses both the provisional group and SDK handle and proves the group empty before reporting quiescence; if publication fails, rollback applies the same proof before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
+- **Environment boundary** — the sandbox command environment crosses the SDK callback boundary as base64 ASCII before one strict UTF-8 decode, then the wrapper removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
 - **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
-The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
+The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
 
 ## Model Experience
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index 5e4b8bbe40..904e4fd1d9 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -6,15 +6,15 @@
 
 ## 行为
 
-- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布，而取消操作可以先停止临时 SDK 句柄。
+- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作使用临时 SDK 句柄；如果发布失败，回滚会终止并验证临时进程组，随后启动操作才会拒绝。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：包装层从沙箱命令环境开始，移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），再把每个有效的 `spec.env` 条目恢复为调用方显式选择；空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作会同时使用临时进程组与 SDK 句柄，并在报告完全停稳前证明进程组为空；如果发布失败，回滚会在启动拒绝前执行相同证明。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
+- **环境边界**：沙箱命令环境会先以 base64 ASCII 跨越 SDK 回调边界，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 - **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
-基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
+基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
 ## 模型体验
 
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index f9c30d378f..2b2516a706 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -1,7 +1,31 @@
 /** Shared remote-environment scrubbing for E2B process and terminal launchers. */
 
+import { Buffer } from 'node:buffer'
+import type { Sandbox } from '@deepseek-ai/dsh-e2b'
 import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
 
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+/**
+ * Read the remote environment through ASCII base64 so SDK callback chunking cannot corrupt UTF-8.
+ * @param sandbox - shared E2B execution world.
+ * @param signal - optional cancellation for the control-plane request.
+ * @returns the complete NUL-delimited UTF-8 environment.
+ */
+export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSignal): Promise<string> {
+  const result = await sandbox.commands.run(
+    'set -o pipefail; env -0 | base64 -w 0',
+    signal === undefined ? {} : { signal },
+  )
+  const encoded = result.stdout.trim()
+  if (!BASE64.test(encoded)) throw new Error('subprocess-e2b: remote environment transport returned invalid base64')
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.from(encoded, 'base64'))
+  } catch (error: unknown) {
+    throw new Error('subprocess-e2b: remote environment is not valid UTF-8', { cause: error })
+  }
+}
+
 /**
  * Parse an E2B NUL-delimited environment while removing harness-private and credential-shaped names.
  * @param raw - The complete NUL-delimited remote environment.
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index c7d19e0ab8..8c83c4b84b 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -18,7 +18,7 @@ import type {
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { serializeRemoteEnvironment } from './environment.ts'
+import { readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
 import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
 
 const GROUP_POLL_MS = 20
@@ -198,6 +198,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly stdoutDecoder = new E2BBase64Decoder()
   private readonly stderrDecoder = new E2BBase64Decoder()
   private readonly outputTermination = new AbortController()
+  private readonly startupController = new AbortController()
   private readonly stdoutReader: E2BOutputReader | undefined
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
@@ -206,6 +207,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private outputTransportError: Error | undefined
   private outputDrainExpired = false
   private stateDirectoryCreated = false
+  private preparing = true
   private invalidHandleQuiescent = false
   private provisionalHandleQuiescent = false
   private terminationStarted = false
@@ -264,6 +266,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   terminate(): void {
     if (this.terminationFenced || this.quiescenceProven || this.terminationAttempt !== undefined) return
     this.terminationStarted = true
+    if (this.preparing) this.startupController.abort(new Error('subprocess-e2b: command terminated during startup'))
     this.outputTermination.abort()
     this.stdout?.destroy()
     this.stderr?.destroy()
@@ -298,6 +301,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         const attempt = this.terminationAttempt
         if (attempt !== undefined && await waitWithSignal(attempt, signal) === WAIT_ABORTED) return false
         this.throwTerminationFailure()
+        /* v8 ignore else -- successful provisional cleanup always records one proof; failures throw above. */
         if (this.invalidHandleQuiescent || this.provisionalHandleQuiescent) {
           this.markQuiescent()
           return true
@@ -351,6 +355,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     try {
       sandbox = await this.runtime.getSandbox()
       await this.prepareState(sandbox)
+      this.preparing = false
       const handle = await sandbox.commands.run(
         commandText(this.spec, this.paths),
         {
@@ -405,7 +410,9 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       await this.finalizeSpills(sandbox)
       return outcome
     } catch (error: unknown) {
-      this.commandState.resolve(undefined)
+      const canceledPreparation = this.preparing
+        && this.terminationStarted
+        && this.startupController.signal.aborted
       let failure = await this.rollbackPublishedFailure(error)
       if (sandbox !== undefined && this.stateDirectoryCreated) {
         try {
@@ -417,9 +424,12 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           )
         }
       }
+      this.commandState.resolve(undefined)
       this.readyState.reject(failure)
+      if (canceledPreparation && failure === error) return { exitCode: null, signal: 'SIGTERM' }
       throw failure
     } finally {
+      this.preparing = false
       this.spec.signal?.removeEventListener('abort', this.onAbort)
       this.stdout?.end()
       this.stderr?.end()
@@ -427,19 +437,21 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async prepareState(sandbox: Sandbox): Promise<void> {
-    const ambient = await sandbox.commands.run('env -0')
-    await sandbox.files.makeDir(this.stateDir)
+    const signal = this.startupController.signal
+    const ambient = await readRemoteEnvironment(sandbox, signal)
+    await sandbox.files.makeDir(this.stateDir, { signal })
     this.stateDirectoryCreated = true
-    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`)
+    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`, { signal })
     const files = [
       { path: this.paths.pid, data: '' },
       { path: this.paths.status, data: '' },
-      { path: this.paths.environment, data: serializeRemoteEnvironment(ambient.stdout, this.spec.env) },
+      { path: this.paths.environment, data: serializeRemoteEnvironment(ambient, this.spec.env) },
       ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
       ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
     ]
-    await sandbox.files.write(files)
-    await sandbox.commands.run(`chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`)
+    await sandbox.files.write(files, { signal })
+    await sandbox.commands.run(`chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`, { signal })
+    signal.throwIfAborted()
   }
 
   private async writeBatchStdin(handle: CommandHandle): Promise<void> {
@@ -639,17 +651,23 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       }
       let handleFailure: unknown
       try {
-        await handle.kill()
-        this.provisionalHandleQuiescent = true
+        if (!await handle.kill()) handleFailure = new Error('E2B SDK kill did not report command termination')
       } catch (error: unknown) {
         handleFailure = error
       }
-      if (!groupDelivered && handleFailure !== undefined) {
+      if (!groupDelivered && await this.groupAlive(sandbox, handle.pid)) {
         throw new AggregateError(
-          [...(groupFailure === undefined ? [] : [groupFailure]), handleFailure],
+          [
+            ...(groupFailure === undefined ? [] : [groupFailure]),
+            ...(handleFailure === undefined
+              ? [new Error('E2B SDK kill did not quiesce the provisional process group')]
+              : [handleFailure]),
+          ],
           'subprocess-e2b: force termination failed through both process-group and SDK transports',
         )
       }
+      while (await this.groupAlive(sandbox, handle.pid)) await waitTick()
+      this.provisionalHandleQuiescent = true
       return
     }
     const sandbox = await this.runtime.getSandbox()
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index f918f802ba..9e0258c10d 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -20,7 +20,7 @@ import type {
   SubprocessTerminalSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { serializeRemoteEnvironment } from './environment.ts'
+import { readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
 
 const POLL_MS = 20
 
@@ -355,7 +355,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
         inputWaiting: false,
       }
     } catch (error: unknown) {
-      if (error instanceof CommandExitError && this.topLevelExited) return undefined
+      if (error instanceof CommandExitError && (error.exitCode === 1 || this.topLevelExited)) return undefined
       throw error
     }
   }
@@ -470,8 +470,8 @@ export async function spawnE2BTerminal(
   let completion: Promise<CommandResult> | undefined
   let stateDirectoryCreated = false
   try {
-    const ambient = await sandbox.commands.run('env -0', signalOpts(spec.signal))
-    const environment = serializeRemoteEnvironment(ambient.stdout, spec.env)
+    const ambient = await readRemoteEnvironment(sandbox, spec.signal)
+    const environment = serializeRemoteEnvironment(ambient, spec.env)
     const argv = serializeValues(spec.argv, 'argv')
     await sandbox.files.makeDir(stateDir)
     stateDirectoryCreated = true
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 680d309bbb..d3c96cf2fc 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -39,6 +39,7 @@ class FakeCommandHandle {
   kills = 0
   disconnects = 0
   killError: unknown
+  killResult = true
   disconnectError: unknown
   private readonly result = Promise.withResolvers<CommandResult>()
   private settled = false
@@ -61,7 +62,7 @@ class FakeCommandHandle {
     this.kills += 1
     if (this.killError !== undefined) throw this.killError
     this.onKill()
-    return true
+    return this.killResult
   }
 
   async disconnect(): Promise<void> {
@@ -109,7 +110,9 @@ class FakeSandbox {
   sdkKillStops = true
   alive = true
   zombieOnly = false
-  ambient = 'PATH=/ambient/bin\0KEEP=safe\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  ambient = 'PATH=/ambient/bin\0KEEP=safe\0UNICODE=你好\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  environmentWire: string | undefined
+  environmentRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
   processGroupId = '4242\n'
   exitStatus = ''
   readonly processGroupReads: string[] = []
@@ -233,9 +236,14 @@ class FakeSandbox {
     commands: {
       run: async (command: string, options?: StartOptions | { signal?: AbortSignal }): Promise<CommandHandle | CommandResult> => {
         this.commandsSeen.push(command)
-        if (command === 'env -0') {
+        if (command.includes('env -0 | base64')) {
+          await this.environmentRequest?.(options?.signal)
           if (this.envError !== undefined) throw this.envError
-          return { exitCode: 0, stdout: this.ambient, stderr: '' }
+          return {
+            exitCode: 0,
+            stdout: this.environmentWire ?? Buffer.from(this.ambient).toString('base64'),
+            stderr: '',
+          }
         }
         if (command.startsWith('set -o pipefail; ps -eo pgid=,stat=')) {
           this.beforeProbe?.()
@@ -397,7 +405,7 @@ describe('E2BSubprocessHandle', () => {
     expect(command).not.toContain('explicit-secret')
     expect(command).not.toContain('hyphen-value')
     expect(command).not.toContain('${!dsh_e2b_name}')
-    expect(fake.commandsSeen).toContain('env -0')
+    expect(fake.commandsSeen).toContain('set -o pipefail; env -0 | base64 -w 0')
     expect(command).toContain('mapfile -d')
     expect(command).toContain('dsh_e2b_node="$(command -v node)"')
     expect(command).toContain('"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e')
@@ -413,7 +421,7 @@ describe('E2BSubprocessHandle', () => {
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
     expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
-      'PATH=/bin\0KEEP=safe\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+      'PATH=/bin\0KEEP=safe\0UNICODE=你好\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
     )
 
     let piped = ''
@@ -806,6 +814,33 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
+  it('aborts a stalled preparation request before reporting startup quiescence', async () => {
+    const fake = new FakeSandbox()
+    let preparationSignal: AbortSignal | undefined
+    fake.environmentRequest = async (signal) => {
+      preparationSignal = signal
+      await new Promise<never>((_resolve, reject) => {
+        const rejectAbort = (): void => {
+          const reason: unknown = signal?.reason
+          reject(reason instanceof Error ? reason : new Error(String(reason)))
+        }
+        if (signal?.aborted === true) {
+          rejectAbort()
+          return
+        }
+        signal?.addEventListener('abort', rejectAbort, { once: true })
+      })
+    }
+    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/stalled-preparation')
+    await vi.waitFor(() => { expect(preparationSignal).toBeDefined() })
+
+    handle.terminate()
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    expect(preparationSignal?.aborted).toBe(true)
+    expect(fake.startOptions).toBeUndefined()
+  })
+
   it('kills through the provisional SDK handle before process-group publication', async () => {
     const fake = new FakeSandbox()
     fake.deferProcessGroupRead()
@@ -822,6 +857,32 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
   })
 
+  it('does not treat an unsuccessful SDK fallback as provisional group quiescence', async () => {
+    const fake = new FakeSandbox()
+    fake.deferProcessGroupRead()
+    fake.trapsTerm = true
+    fake.delaysKill = true
+    fake.delaysKillCompletion = true
+    fake.sdkKillStops = false
+    fake.handle.killResult = false
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/provisional-sdk-false')
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
+
+    handle.terminate()
+    await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
+    let quiescent = false
+    const waiting = handle.waitForExit().then((value) => { quiescent = value })
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(quiescent).toBe(false)
+
+    fake.alive = false
+    await waiting
+    expect(quiescent).toBe(true)
+    fake.releaseProcessGroupRead()
+    fake.finish()
+    await handle.done
+  })
+
   it('bounds a quiescence observer while provisional termination is awaiting the controller', async () => {
     const fake = new FakeSandbox()
     fake.deferProcessGroupRead()
@@ -895,6 +956,23 @@ describe('E2BSubprocessHandle', () => {
     await expect(absentHandle.waitForExit()).resolves.toBe(true)
     absentGroup.releaseProcessGroupRead()
     await absentHandle.done
+
+    const optimisticSdk = new FakeSandbox()
+    optimisticSdk.deferProcessGroupRead()
+    optimisticSdk.signalErrors.push(commandError(1), commandError(1))
+    optimisticSdk.sdkKillStops = false
+    const optimisticHandle = new E2BSubprocessHandle(
+      runtime(optimisticSdk),
+      spec({ graceMs: 1 }),
+      '/runtime/pre-publication-optimistic-sdk',
+    )
+    await vi.waitFor(() => { expect(optimisticSdk.startOptions).toBeDefined() })
+    optimisticHandle.terminate()
+    await expect(optimisticHandle.waitForExit()).rejects.toThrow('force termination failed through both')
+    optimisticHandle.terminate()
+    await expect(optimisticHandle.waitForExit()).resolves.toBe(true)
+    optimisticSdk.releaseProcessGroupRead()
+    await optimisticHandle.done
   })
 
   it('honors an already-aborted signal when constructing the asynchronous handle directly', async () => {
@@ -1024,6 +1102,24 @@ describe('E2BSubprocessHandle', () => {
     await expect(envHandle.done).rejects.toThrow('ambient lookup failed')
     expect(envFailure.removed).toEqual([])
 
+    const malformedEnvironment = new FakeSandbox()
+    malformedEnvironment.environmentWire = '%'
+    const malformedEnvironmentHandle = new E2BSubprocessHandle(
+      runtime(malformedEnvironment),
+      spec(),
+      '/runtime/malformed-environment',
+    )
+    await expect(malformedEnvironmentHandle.done).rejects.toThrow('invalid base64')
+
+    const invalidUtf8Environment = new FakeSandbox()
+    invalidUtf8Environment.environmentWire = Buffer.from([0xff]).toString('base64')
+    const invalidUtf8EnvironmentHandle = new E2BSubprocessHandle(
+      runtime(invalidUtf8Environment),
+      spec(),
+      '/runtime/invalid-utf8-environment',
+    )
+    await expect(invalidUtf8EnvironmentHandle.done).rejects.toThrow('not valid UTF-8')
+
     const cleanupFailure = new FakeSandbox()
     cleanupFailure.backgroundError = new Error('start failed before credential consumption')
     cleanupFailure.nextRemoveError = new Error('credential cleanup failed')
@@ -1509,6 +1605,7 @@ describe('E2BSubprocessService', () => {
     const { ctx, fiber } = await service(fake)
     const subprocess = ctx.subprocess
     const handle = subprocess.spawn(spec())
+    await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
     const disposing = fiber.dispose()
     await flush()
     expect(() => subprocess.spawn(spec())).toThrow('service is disposing')
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index c6ec5bfaad..00b9fc41fc 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -89,7 +89,7 @@ class FakeTerminalSandbox {
   readonly directories: string[] = []
   readonly writes = new Map<string, string>()
   createOptions: Parameters<Sandbox['pty']['create']>[0] | undefined
-  ambient = 'KEEP=visible\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  ambient = 'KEEP=visible\0UNICODE=你好\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
   ready: string | Error = 'ready\n'
   readyMisses = 0
   readyReads = 0
@@ -162,7 +162,9 @@ class FakeTerminalSandbox {
           this.commandFailure = undefined
           throw error
         }
-        if (command === 'env -0') return { exitCode: 0, stdout: this.ambient, stderr: '' }
+        if (command.includes('env -0 | base64')) {
+          return { exitCode: 0, stdout: Buffer.from(this.ambient).toString('base64'), stderr: '' }
+        }
         if (command.includes('command -v -- ')) {
           return { exitCode: 0, stdout: this.resolvedExecutable, stderr: '' }
         }
@@ -263,6 +265,7 @@ describe('E2B terminal allocation', () => {
     expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0, envs: { TERM: 'dumb' } })
     expect(fake.inputs[0]?.data.toString()).toContain("exec /bin/bash '/runtime/terminal-one/runner.bash'")
     expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('KEEP=visible\0')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('UNICODE=你好\0')
     expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('TOKEN_EXPLICIT=kept\0')
     expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('secret')
     expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('DSH_STALE')
@@ -653,6 +656,8 @@ describe('E2B terminal lifecycle', () => {
     fake.foreground = 'invalid\n'
     await expect(terminal.inspectForeground()).rejects.toThrow('cannot resolve foreground')
     fake.foregroundFailure = commandError(1)
+    await expect(terminal.inspectForeground()).resolves.toBeUndefined()
+    fake.foregroundFailure = commandError(2)
     await expect(terminal.inspectForeground()).rejects.toBeInstanceOf(CommandExitError)
     fake.clearOnTerm = true
     terminal.terminate()

From 81e2e1f647b07b20ec7974176770fdd9a7764c64 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 15:30:32 +0800
Subject: [PATCH 378/516] fix(e2b): harden SDK shell and cleanup boundaries

E2B starts command and PTY requests through login shells, so isolate each control shell behind a fresh randomized HOME and blank sandbox credential names before mutable profiles can run. Preserve the real remote HOME only for the requested argv.

Collapse duplicate termination state, keep failed force cleanup retryable until quiescence is observed, and make terminal state allocation cancellable. Leave numeric PGID reuse as an explicit provider-level TODO because a userspace precheck would remain TOCTOU.
---
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.md      |   4 +-
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |   4 +-
 docs/cordis-catalog/services.md               |   2 +-
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |   2 +-
 packages/e2b/e2b/README.zh.md                 |   2 +-
 packages/e2b/e2b/src/index.ts                 |  17 +-
 packages/e2b/e2b/tests/composition.e2e.ts     |  26 ++-
 packages/e2b/e2b/tests/e2b.spec.ts            |  27 ++-
 packages/e2b/fs-e2b/src/index.ts              |  15 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |   8 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   4 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   4 +-
 .../e2b/subprocess-e2b/src/environment.ts     |  57 ++++--
 packages/e2b/subprocess-e2b/src/index.ts      |   6 +-
 packages/e2b/subprocess-e2b/src/process.ts    | 182 ++++++++----------
 packages/e2b/subprocess-e2b/src/terminal.ts   |  99 +++++++---
 .../subprocess-e2b/tests/subprocess.spec.ts   | 127 ++++++++----
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  51 ++++-
 21 files changed, 438 insertions(+), 211 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
index 1343d33032..2c3db3fad4 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.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 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: cccee91998e832cc9cf53e554e104ccc5caada38
-2026-07-27-e2b-remote-runtime-poc.zh.md: b1a30c92e313b1395006ebd4fd17eacda2546ad5
+2026-07-27-e2b-remote-runtime-poc.md: 79c5bfe2dfa11cd695c7134e6ceffb639b449688
+2026-07-27-e2b-remote-runtime-poc.zh.md: 729a10ec7efa4dd55f041dc804d2252102b13c01
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
index cccee91998..79c5bfe2df 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
@@ -28,7 +28,7 @@ E2B owns the mutable filesystem, managed command and Bash processes, terminal al
 
 The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
 
-The fundamental adapters carry the substrate-specific mechanics. `dsh-subprocess-e2b` consumes E2B's byte PTY callback directly, retains terminal send identity across asynchronous foreground-group lookup, and owns whole-session cleanup. Ambient environments and ordinary command pipes cross decoded SDK callback boundaries as ASCII/base64 before strict UTF-8 or raw-byte restoration; startup preparation carries the handle's owned cancellation signal, and provisional termination proves the remote group empty after SDK fallback. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated ASCII/base64 frames and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
+The fundamental adapters carry the substrate-specific mechanics. Adapter-internal E2B command and PTY login shells use a fresh randomized root-level `HOME`; `dsh-subprocess-e2b` also gives them empty overrides for scrubbed credential names before user profiles run. The subprocess adapter consumes E2B's byte PTY callback, transports environment snapshots and command bytes as ASCII/base64 across decoded SDK callbacks, and uses one cancellation controller plus one retryable group-cleanup transaction that reports success only after proving quiescence. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated newline-delimited UTF-8 JSON and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
 
 Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
 
@@ -38,7 +38,7 @@ The POC has no session-persistence backend, template builder, volume, snapshot,
 
 Focused package suites pin owner lifecycle cleanup, filesystem paths/containment/bounded descriptor reads and commit metadata, subprocess executable lookup/process groups/publication rollback, terminal byte I/O/signal identity/default-environment scrubbing/session cleanup, output limits, abort ordering, disposal to quiescence, and package-owned invariant registrations. The generic PTY, LSP, and subprocess Code Runtime suites pin their provider-neutral readiness, cross-namespace `processId`, binding bridge, descriptor isolation, hostile traffic, and worker/descendant cleanup behavior.
 
-A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, real-directory runtime-state setup, process-publication rollback, byte-split UTF-8 command output, bounded raw spill and inherited-output draining, PTY default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
+A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, real-directory runtime-state setup, process-publication rollback, byte-split UTF-8 command output, bounded raw spill and inherited-output draining, hostile command and PTY login-profile isolation, default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
index b1a30c92e3..729a10ec7e 100644
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
@@ -28,7 +28,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
 
-基础适配器承载基底专用机制。`dsh-subprocess-e2b` 直接消费 E2B 的字节 PTY 回调，在异步查找前台进程组的过程中保留终端发送身份，并负责全会话清理。环境快照与普通命令管道会先以 ASCII/base64 跨越已解码的 SDK 回调边界，再执行严格 UTF-8 解码或恢复原始字节；启动准备会携带句柄自有的取消信号，临时终止则会在 SDK 回退后证明远程进程组为空。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 通过经过验证的 ASCII/base64 帧承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
+基础适配器承载基底专用机制。适配器内部的 E2B 命令与 PTY 登录 shell 使用位于根目录下、全新随机生成的 `HOME`；在用户 profile 脚本运行前，`dsh-subprocess-e2b` 还会为它们设置已清理凭据名称的空值覆盖。该子进程适配器消费 E2B 的字节 PTY 回调，以 ASCII/base64 跨越已解码的 SDK 回调传输环境快照与命令字节，并使用一个取消控制器与一个可重试的进程组清理事务，后者只有在证明完全停稳后才报告成功。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 以经过验证、由换行符分隔的 UTF-8 JSON 承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
 
 保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
 
@@ -38,7 +38,7 @@ E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 聚焦包测试套件固定所有者生命周期清理、文件系统路径／containment／有界描述符读取与提交元数据、子进程可执行文件查找／进程组／发布回滚、终端字节 I/O／信号身份／默认环境清理／会话清理、输出上限、中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。通用 PTY、LSP 与子进程 Code Runtime 测试套件固定其提供方无关的就绪判定、跨命名空间 `processId`、绑定桥接、描述符隔离、恶意通信，以及 worker／后代进程清理行为。
 
-凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、真实目录形式的运行时状态设置、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 与继承输出排空、PTY 默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
+凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、真实目录形式的运行时状态设置、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 与继承输出排空、恶意命令与 PTY 登录 profile 隔离、默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
 
 ## 曾考虑的替代方案
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 7ce45c6817..cdd2d87435 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -591,7 +591,7 @@ Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decisio
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:97`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:109`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 2fc8d403d1..fb645c2e36 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 6eb7d69dd6355de870db6bf05540f2629f464bc8
-README.zh.md: b2e2616cf779bce659fdef58840aa51f095a73cf
+README.md: 402903184934903eceb36a04d670e4490879ac65
+README.zh.md: 1fec6ab66858f04a47c8a2a7cb5f6a8907ab6cac
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 6eb7d69dd6..4029031849 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -28,7 +28,7 @@ Set `sandboxId` to reconnect a running or paused sandbox instead of creating one
 
 ## Lifecycle and ownership
 
-Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
+Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. Each adapter-internal E2B command shell receives a fresh randomized root-level `HOME`, so the SDK's fixed login shell does not resolve profile files from the mutable user home before the control command. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
 
 Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` is accepted when disposal requests `kill`, or when this service created a sandbox with `onTimeout: kill`; otherwise, a not-found error from a requested `pause` rejects teardown because retention was not proved. A newly created sandbox is killed when initial directory setup fails; if that rollback fails, disposal retries it before releasing ownership. A reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index b2e2616cf7..1fec6ab668 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -28,7 +28,7 @@
 
 ## 生命周期与所有权
 
-构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
+构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。每个适配器内部的 E2B 命令 shell 都会获得一个位于根目录下、全新随机生成的 `HOME`，因此 SDK 固定使用的登录 shell 不会在控制命令之前解析可变用户主目录中的配置文件。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
 
 资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 仅在资源释放请求 `kill`，或本服务创建了配置为 `onTimeout: kill` 的沙箱时才可接受；否则，`pause` 请求返回的未找到错误会导致 teardown 拒绝，因为无法证明保留成功。新建沙箱的初始目录设置失败时，服务会终止该沙箱；如果该回滚失败，资源释放会在解除所有权前重试。重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 150961a897..9e8960a685 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -4,6 +4,7 @@
  * @module @deepseek-ai/dsh-e2b
  */
 
+import { randomUUID } from 'node:crypto'
 import { posix } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
@@ -42,6 +43,17 @@ export function quoteE2BShellArg(value: string): string {
   return `'${value.replaceAll('\'', "'\"'\"'")}'`
 }
 
+/**
+ * Isolate E2B's hard-coded login shell behind a fresh randomized home path.
+ * @param overrides - Additional environment entries for the internal command.
+ * @returns A fresh mutable map that the E2B SDK may extend.
+ */
+export function e2bControlEnvs(
+  overrides: Readonly<Record<string, string>> = {},
+): Record<string, string> {
+  return { ...overrides, HOME: `/.dsh-e2b-control-${randomUUID()}` }
+}
+
 /** Action taken on the owned sandbox when the Cordis service is disposed. */
 export type E2BDisposeMode = 'kill' | 'pause' | 'leave'
 
@@ -249,7 +261,10 @@ export class E2BSandboxService extends Service {
       if (runtimeRoot.type !== FileType.DIR || runtimeRoot.symlinkTarget !== undefined) {
         throw new Error(`dsh-e2b: runtime root must be a real directory: ${this.runtimeRoot}`)
       }
-      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.runtimeRoot)}`)
+      await sandbox.commands.run(
+        `chmod 700 -- ${quoteE2BShellArg(this.runtimeRoot)}`,
+        { envs: e2bControlEnvs() },
+      )
       return sandbox
     } catch (error: unknown) {
       if (this.created) {
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 34875d5153..f9fcbfae8a 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -5,7 +5,12 @@ import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
-import E2BSandboxService, { Sandbox, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+import E2BSandboxService, {
+  e2bControlEnvs,
+  FileNotFoundError,
+  Sandbox,
+  SandboxNotFoundError,
+} from '@deepseek-ai/dsh-e2b'
 import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
 import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
@@ -17,7 +22,7 @@ const configPath = join(fixtureRoot, 'cordis.yml')
 const tsconfigPath = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 
 describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
-  it('scrubs sandbox-default credentials from an actual E2B PTY', async () => {
+  it('scrubs credentials before actual E2B command and PTY login shells', async () => {
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared before the PTY environment test')
     const sandbox = await Sandbox.create({
@@ -28,6 +33,18 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       lifecycle: { onTimeout: 'kill' },
     })
     try {
+      const profileLeakPath = '/home/user/dsh-e2b-bootstrap-profile-leak'
+      const hostileProfile = [
+        'if [[ "${NPM_TOKEN-}" == "sentinel-secret" ]]; then',
+        `  printf leaked > ${profileLeakPath}`,
+        'fi',
+        '',
+      ].join('\n')
+      await sandbox.files.write([
+        { path: '/home/user/.bash_profile', data: hostileProfile },
+        { path: '/home/user/.profile', data: hostileProfile },
+        { path: '/home/user/.bashrc', data: hostileProfile },
+      ])
       const ctx = new Context()
       ctx.provide('e2b', {
         cwd: '/home/user',
@@ -43,6 +60,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       const node = await ctx.subprocess.resolveExecutable('node')
       const relativeNodePath = posix.relative(ctx.subprocess.cwd, posix.dirname(node)) || '.'
       await expect(ctx.subprocess.resolveExecutable('node', { PATH: relativeNodePath })).resolves.toBe(node)
+      await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
       const environmentProbe = ctx.subprocess.spawn({
         argv: ['/bin/bash', '-c', [
           'dsh_leak=0',
@@ -59,6 +77,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       })
       await expect(environmentProbe.done).resolves.toEqual({ exitCode: 0, signal: null })
       expect(environmentProbe.collected.stdout?.readFrom(0).text).toBe('DIRECT=<> LEAK=<0>\n')
+      await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
       const ownerId = SessionId('e2b-pty-env-owner')
       const owner: Agent = {
         id: ownerId,
@@ -89,6 +108,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       expect(result.viewport).toContain('NPM=<> DSH=<> KEEP=<visible>')
       expect(result.viewport).not.toContain('sentinel-secret')
       expect(result.viewport).not.toContain('sentinel-stale')
+      await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
       await session.close('environment test complete')
       await subprocessFiber.dispose()
       await ptyFiber.dispose()
@@ -98,7 +118,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         'mkdir -p -- /home/user/dsh-e2b-runtime-target',
         'chmod 755 -- /home/user/dsh-e2b-runtime-target',
         'ln -s -- /home/user/dsh-e2b-runtime-target /home/user/.dsh-e2b',
-      ].join('\n'))
+      ].join('\n'), { envs: e2bControlEnvs({ NPM_TOKEN: '' }) })
       const linkedCtx = new Context()
       const linkedFiber = await linkedCtx.plugin(E2BSandboxService, {
         apiKey,
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index a4eba5ebc9..46ba452210 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -1,7 +1,9 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Mock } from 'vitest'
 import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
+  e2bControlEnvs,
   E2BSandboxId,
   FileType,
   SandboxNotFoundError,
@@ -35,15 +37,20 @@ interface SandboxFixture {
   sandbox: SandboxType
   makeDir: ReturnType<typeof vi.fn>
   getInfo: ReturnType<typeof vi.fn>
-  run: ReturnType<typeof vi.fn>
+  run: Mock<RunCommand>
   kill: ReturnType<typeof vi.fn>
   pause: ReturnType<typeof vi.fn>
 }
 
+type RunCommand = (
+  command: string,
+  options?: { envs?: Record<string, string> },
+) => Promise<{ exitCode: number; stdout: string; stderr: string }>
+
 function fakeSandbox(id = 'sandbox-1'): SandboxFixture {
   const makeDir = vi.fn().mockResolvedValue(true)
   const getInfo = vi.fn().mockResolvedValue({ type: FileType.DIR })
-  const run = vi.fn().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
+  const run = vi.fn<RunCommand>().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
   const kill = vi.fn().mockResolvedValue(undefined)
   const pause = vi.fn().mockResolvedValue(true)
   const sandbox = {
@@ -63,6 +70,15 @@ beforeEach(() => {
 })
 
 describe('E2BSandboxService', () => {
+  it('gives each SDK login shell a fresh non-overridable control home', () => {
+    const first = e2bControlEnvs({ HOME: '/hostile', NPM_TOKEN: '' })
+    const second = e2bControlEnvs()
+
+    expect(first.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(first).toEqual({ HOME: first.HOME, NPM_TOKEN: '' })
+    expect(first.HOME).not.toBe(second.HOME)
+  })
+
   it('creates one protected shared sandbox and kills it on default disposal', async () => {
     const fixture = fakeSandbox()
     sdk.create.mockResolvedValue(fixture.sandbox)
@@ -86,7 +102,12 @@ describe('E2BSandboxService', () => {
     expect(fixture.makeDir).toHaveBeenNthCalledWith(1, '/home/user/workspace')
     expect(fixture.makeDir).toHaveBeenNthCalledWith(2, '/home/user/workspace/.dsh-e2b')
     expect(fixture.getInfo).toHaveBeenCalledWith('/home/user/workspace/.dsh-e2b')
-    expect(fixture.run).toHaveBeenCalledWith("chmod 700 -- '/home/user/workspace/.dsh-e2b'")
+    const runOptions = fixture.run.mock.calls[0]?.[1]
+    expect(runOptions?.envs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(fixture.run).toHaveBeenCalledWith(
+      "chmod 700 -- '/home/user/workspace/.dsh-e2b'",
+      { envs: { HOME: runOptions?.envs?.HOME } },
+    )
 
     await fiber.dispose()
     expect(fixture.kill).toHaveBeenCalledOnce()
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index d41c2e3d32..7c81791d55 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -20,6 +20,7 @@ import type {
 } from '@deepseek-ai/dsh-fs'
 import {
   CommandExitError,
+  e2bControlEnvs,
   FileNotFoundError,
   FileType,
   quoteE2BShellArg,
@@ -71,6 +72,10 @@ function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
   return signal === undefined ? {} : { signal }
 }
 
+function commandOpts(signal: AbortSignal | undefined): { envs: Record<string, string>; signal?: AbortSignal } {
+  return { envs: e2bControlEnvs(), ...signalOpts(signal) }
+}
+
 function entryType(entry: EntryInfo): FsInfo['type'] {
   switch (entry.type) {
     case FileType.FILE:
@@ -215,7 +220,7 @@ export class E2BFileSystem extends FileSystem {
     assertNotAborted(signal, 'read')
     const sandbox = await this.ctx.e2b.getSandbox()
     try {
-      const node = await sandbox.commands.run('command -v -- node', signalOpts(signal))
+      const node = await sandbox.commands.run('command -v -- node', commandOpts(signal))
       const executable = node.stdout.trim()
       if (!posix.isAbsolute(executable) || executable.includes('\n')) {
         throw new Error('fs-e2b: bounded reader requires one absolute Node executable')
@@ -228,7 +233,7 @@ export class E2BFileSystem extends FileSystem {
         quoteE2BShellArg(this.processPath(target)),
         String(maxBytes),
       ].join(' ')
-      const result = await sandbox.commands.run(command, signalOpts(signal))
+      const result = await sandbox.commands.run(command, commandOpts(signal))
       assertNotAborted(signal, 'read')
       const response = this.parseBoundedRead(result.stdout, target)
       if (response.kind === 'not-file') {
@@ -415,7 +420,7 @@ export class E2BFileSystem extends FileSystem {
 
   private async canonicalPath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
     try {
-      const result = await sandbox.commands.run(`realpath -m -- ${quoteE2BShellArg(path)}`, signalOpts(signal))
+      const result = await sandbox.commands.run(`realpath -m -- ${quoteE2BShellArg(path)}`, commandOpts(signal))
       return result.stdout.replace(/\n$/, '')
     } catch (error: unknown) {
       if (error instanceof CommandExitError) throw new Error(error.stderr || error.message, { cause: error })
@@ -505,7 +510,7 @@ export class E2BFileSystem extends FileSystem {
       const created = await sandbox.files.makeDir(stagingDirectory, signalOpts(signal))
       if (!created) throw new Error('private staging directory already exists')
       stagingDirectoryCreated = true
-      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stagingDirectory)}`, signalOpts(signal))
+      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stagingDirectory)}`, commandOpts(signal))
       assertNotAborted(signal, 'write')
       await sandbox.files.write(temporary, content, {
         metadata: { [VERSION_METADATA_KEY]: versionId },
@@ -515,7 +520,7 @@ export class E2BFileSystem extends FileSystem {
       const mode = existing === undefined ? 0o600 : existing.mode & 0o777
       await sandbox.commands.run(
         `chmod ${mode.toString(8)} -- ${quoteE2BShellArg(temporary)}`,
-        signalOpts(signal),
+        commandOpts(signal),
       )
       assertNotAborted(signal, 'write')
       const committed = await sandbox.files.rename(temporary, targetPath)
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 1689fb4023..23835e9967 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -225,8 +225,14 @@ class FakeRemote {
       },
     },
     commands: {
-      run: async (command: string, options?: { signal?: AbortSignal }): Promise<{ exitCode: number; stdout: string; stderr: string }> => {
+      run: async (
+        command: string,
+        options?: { envs?: Record<string, string>; signal?: AbortSignal },
+      ): Promise<{ exitCode: number; stdout: string; stderr: string }> => {
         this.checkAbort(options)
+        const home = options?.envs?.HOME
+        expect(home).toMatch(/^\/\.dsh-e2b-control-/)
+        expect(options?.envs).toEqual({ HOME: home })
         this.commands.push(command)
         if (this.nextCommandError !== undefined) {
           const error = this.nextCommandError
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 3f64c67b7e..ac7b8d42a5 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: aaac559e60162c3051cc6f06cbcfac011f5eb59a
-README.zh.md: 904e4fd1d9a13082ddfc8183c0e42abc25bd1caf
+README.md: 9b86af428533ebcc2c0da56339e6ea2a28170fd3
+README.zh.md: e3e8368534266e35ec04dcf5a2d6718829b4a016
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index aaac559e60..9b86af4285 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -8,8 +8,8 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
-- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. A failed transaction is observable through `waitForExit()` and may be retried, while any proven quiescence permanently fences later termination against PID reuse. Before publication, cancellation uses both the provisional group and SDK handle and proves the group empty before reporting quiescence; if publication fails, rollback applies the same proof before startup rejects. After publication, a monitoring failure also rolls back the group before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — the sandbox command environment crosses the SDK callback boundary as base64 ASCII before one strict UTF-8 decode, then the wrapper removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
+- **Environment boundary** — the sandbox command environment crosses the SDK callback boundary as base64 ASCII before one strict UTF-8 decode, then the wrapper removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. E2B's fixed command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
 - **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index 904e4fd1d9..e3e8368534 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -8,8 +8,8 @@
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
-- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。失败的事务可通过 `waitForExit()` 观察，并可重试；任何已证明的完全停稳都会永久防止后续终止操作命中复用的 PID。发布前，取消操作会同时使用临时进程组与 SDK 句柄，并在报告完全停稳前证明进程组为空；如果发布失败，回滚会在启动拒绝前执行相同证明。发布后，监控失败也会在拒绝前回滚进程组。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：沙箱命令环境会先以 base64 ASCII 跨越 SDK 回调边界，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
+- **环境边界**：沙箱命令环境会先以 base64 ASCII 跨越 SDK 回调边界，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，E2B 固定的命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 才会接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 - **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index 2b2516a706..5322491261 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -1,11 +1,24 @@
 /** Shared remote-environment scrubbing for E2B process and terminal launchers. */
 
 import { Buffer } from 'node:buffer'
+import { posix } from 'node:path'
+import { e2bControlEnvs } from '@deepseek-ai/dsh-e2b'
 import type { Sandbox } from '@deepseek-ai/dsh-e2b'
 import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
 
 const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
 
+function remoteEnvironmentEntries(raw: string): Array<readonly [string, string]> {
+  const entries: Array<readonly [string, string]> = []
+  for (const entry of raw.split('\0')) {
+    if (entry.length === 0) continue
+    const separator = entry.indexOf('=')
+    if (separator <= 0) continue
+    entries.push([entry.slice(0, separator), entry.slice(separator + 1)])
+  }
+  return entries
+}
+
 /**
  * Read the remote environment through ASCII base64 so SDK callback chunking cannot corrupt UTF-8.
  * @param sandbox - shared E2B execution world.
@@ -14,16 +27,29 @@ const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
  */
 export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSignal): Promise<string> {
   const result = await sandbox.commands.run(
-    'set -o pipefail; env -0 | base64 -w 0',
-    signal === undefined ? {} : { signal },
+    'set -o pipefail; printf \'%s\' "$PWD" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
+    { envs: e2bControlEnvs(), ...(signal === undefined ? {} : { signal }) },
   )
-  const encoded = result.stdout.trim()
-  if (!BASE64.test(encoded)) throw new Error('subprocess-e2b: remote environment transport returned invalid base64')
+  const lines = result.stdout.trim().split('\n')
+  if (lines.length !== 2 || !lines.every(line => BASE64.test(line))) {
+    throw new Error('subprocess-e2b: remote environment transport returned invalid base64')
+  }
+  const [encodedHome, encodedEnvironment] = lines as [string, string]
+  let home: string
+  let raw: string
   try {
-    return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.from(encoded, 'base64'))
+    const decoder = new TextDecoder('utf-8', { fatal: true })
+    home = decoder.decode(Buffer.from(encodedHome, 'base64'))
+    raw = decoder.decode(Buffer.from(encodedEnvironment, 'base64'))
   } catch (error: unknown) {
     throw new Error('subprocess-e2b: remote environment is not valid UTF-8', { cause: error })
   }
+  if (!posix.isAbsolute(home) || home.includes('\0')) {
+    throw new Error(`subprocess-e2b: remote login home is invalid: ${JSON.stringify(home)}`)
+  }
+  const environment = new Map(remoteEnvironmentEntries(raw))
+  environment.set('HOME', home)
+  return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
 }
 
 /**
@@ -33,13 +59,22 @@ export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSign
  */
 export function scrubRemoteEnvironment(raw: string): Map<string, string> {
   const environment = new Map<string, string>()
-  for (const entry of raw.split('\0')) {
-    if (entry.length === 0) continue
-    const separator = entry.indexOf('=')
-    if (separator <= 0) continue
-    const name = entry.slice(0, separator)
+  for (const [name, value] of remoteEnvironmentEntries(raw)) {
     if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
-    environment.set(name, entry.slice(separator + 1))
+    environment.set(name, value)
+  }
+  return environment
+}
+
+/**
+ * Isolate E2B's fixed login-shell bootstrap from user profiles and ambient credentials.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @returns Explicit E2B command or PTY overrides for bootstrap-shell startup.
+ */
+export function bootstrapEnvironment(raw: string): Record<string, string> {
+  const environment: Record<string, string> = { TERM: 'dumb' }
+  for (const [name] of remoteEnvironmentEntries(raw)) {
+    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) environment[name] = ''
   }
   return environment
 }
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 4516bffa84..7318dfde95 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -14,7 +14,7 @@ import type {
   SubprocessTerminalHandle,
   SubprocessTerminalSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
-import { quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
+import { e2bControlEnvs, quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import { E2BSubprocessHandle } from './process.ts'
 import { spawnE2BTerminal } from './terminal.ts'
 
@@ -86,7 +86,7 @@ export class E2BSubprocessService extends SubprocessService {
     if (posix.isAbsolute(command)) {
       await sandbox.commands.run(
         `test -f ${quoteE2BShellArg(command)} -a -x ${quoteE2BShellArg(command)}`,
-        signalOpts(signal),
+        { envs: e2bControlEnvs(), ...signalOpts(signal) },
       )
       signal?.throwIfAborted()
       return command
@@ -95,7 +95,7 @@ export class E2BSubprocessService extends SubprocessService {
     const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
     const result = await sandbox.commands.run(
       `${prefix}command -v -- ${quoteE2BShellArg(command)}`,
-      { cwd: this.cwd, ...signalOpts(signal) },
+      { cwd: this.cwd, envs: e2bControlEnvs(), ...signalOpts(signal) },
     )
     signal?.throwIfAborted()
     const executable = result.stdout.trim()
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 8c83c4b84b..6b17f3b682 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -5,6 +5,7 @@ import { PassThrough, Writable } from 'node:stream'
 import { posix } from 'node:path'
 import {
   CommandExitError,
+  e2bControlEnvs,
   FileNotFoundError,
   SandboxNotFoundError,
   quoteE2BShellArg,
@@ -18,7 +19,7 @@ import type {
   SubprocessSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
+import { bootstrapEnvironment, readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
 import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
 
 const GROUP_POLL_MS = 20
@@ -142,8 +143,11 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
   return bootstrap
 }
 
-function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
-  return signal === undefined ? {} : { signal }
+function commandOpts(
+  envs: Record<string, string>,
+  signal: AbortSignal | undefined,
+): { envs: Record<string, string>; signal?: AbortSignal } {
+  return { envs: e2bControlEnvs(envs), ...(signal === undefined ? {} : { signal }) }
 }
 
 function isAborted(signal: AbortSignal | undefined): boolean {
@@ -197,21 +201,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly readyState = Promise.withResolvers<CommandHandle>()
   private readonly stdoutDecoder = new E2BBase64Decoder()
   private readonly stderrDecoder = new E2BBase64Decoder()
-  private readonly outputTermination = new AbortController()
-  private readonly startupController = new AbortController()
+  private readonly terminationController = new AbortController()
   private readonly stdoutReader: E2BOutputReader | undefined
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
+  private controlEnvs: Record<string, string> = {}
   private remotePid = -1
   private commandHandle: CommandHandle | undefined
   private outputTransportError: Error | undefined
   private outputDrainExpired = false
   private stateDirectoryCreated = false
   private preparing = true
-  private invalidHandleQuiescent = false
-  private provisionalHandleQuiescent = false
   private terminationStarted = false
-  private terminationFenced = false
   private quiescenceProven = false
   private terminationAttempt: Promise<void> | undefined
   private terminationFailure: Error | undefined
@@ -264,20 +265,16 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   /** @inheritdoc */
   terminate(): void {
-    if (this.terminationFenced || this.quiescenceProven || this.terminationAttempt !== undefined) return
+    if (this.quiescenceProven || this.terminationAttempt !== undefined) return
     this.terminationStarted = true
-    if (this.preparing) this.startupController.abort(new Error('subprocess-e2b: command terminated during startup'))
-    this.outputTermination.abort()
+    this.terminationController.abort(new Error('subprocess-e2b: command terminated'))
     this.stdout?.destroy()
     this.stderr?.destroy()
     this.terminationFailure = undefined
     const attempt = this.terminateRemote()
     this.terminationAttempt = attempt
     void attempt.then(
-      () => {
-        this.terminationFenced = true
-        this.terminationAttempt = undefined
-      },
+      () => { this.terminationAttempt = undefined },
       (error: unknown) => {
         if (!this.quiescenceProven) this.terminationFailure = asError(error)
         this.terminationAttempt = undefined
@@ -301,11 +298,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         const attempt = this.terminationAttempt
         if (attempt !== undefined && await waitWithSignal(attempt, signal) === WAIT_ABORTED) return false
         this.throwTerminationFailure()
-        /* v8 ignore else -- successful provisional cleanup always records one proof; failures throw above. */
-        if (this.invalidHandleQuiescent || this.provisionalHandleQuiescent) {
-          this.markQuiescent()
-          return true
-        }
+        // Successful pre-publication termination records quiescence; its only other outcome is the failure above.
+        return true
       }
     } else {
       try {
@@ -361,6 +355,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         {
           background: true,
           cwd: this.spec.cwd,
+          envs: e2bControlEnvs(this.controlEnvs),
           stdin: this.spec.stdio.stdin !== 'ignore',
           timeoutMs: 0,
           onStdout: async (data) => { await this.dispatchOutput('stdout', data) },
@@ -374,7 +369,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         const invalidPid = new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
         try {
           await handle.kill()
-          this.invalidHandleQuiescent = true
+          this.markQuiescent()
           this.commandHandle = undefined
         } catch (cleanupError: unknown) {
           this.terminationFailure = asError(cleanupError)
@@ -412,7 +407,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     } catch (error: unknown) {
       const canceledPreparation = this.preparing
         && this.terminationStarted
-        && this.startupController.signal.aborted
+        && this.terminationController.signal.aborted
       let failure = await this.rollbackPublishedFailure(error)
       if (sandbox !== undefined && this.stateDirectoryCreated) {
         try {
@@ -437,11 +432,15 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async prepareState(sandbox: Sandbox): Promise<void> {
-    const signal = this.startupController.signal
+    const signal = this.terminationController.signal
     const ambient = await readRemoteEnvironment(sandbox, signal)
+    this.controlEnvs = bootstrapEnvironment(ambient)
     await sandbox.files.makeDir(this.stateDir, { signal })
     this.stateDirectoryCreated = true
-    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`, { signal })
+    await sandbox.commands.run(
+      `chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`,
+      commandOpts(this.controlEnvs, signal),
+    )
     const files = [
       { path: this.paths.pid, data: '' },
       { path: this.paths.status, data: '' },
@@ -450,7 +449,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
     ]
     await sandbox.files.write(files, { signal })
-    await sandbox.commands.run(`chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`, { signal })
+    await sandbox.commands.run(
+      `chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`,
+      commandOpts(this.controlEnvs, signal),
+    )
     signal.throwIfAborted()
   }
 
@@ -490,7 +492,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: Uint8Array): Promise<void> {
     const target = pipe ?? inherited
-    if (target === undefined || data.length === 0 || this.outputTermination.signal.aborted) return
+    if (target === undefined || data.length === 0 || this.terminationController.signal.aborted) return
     if (target.destroyed) throw new Error('subprocess output stream is closed')
     if (target.write(data)) return
     await new Promise<void>((resolve, reject) => {
@@ -502,13 +504,13 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         target.removeListener('drain', onDrain)
         target.removeListener('close', onClose)
         target.removeListener('error', onError)
-        this.outputTermination.signal.removeEventListener('abort', onTermination)
+        this.terminationController.signal.removeEventListener('abort', onTermination)
       }
       target.once('drain', onDrain)
       target.once('close', onClose)
       target.once('error', onError)
-      this.outputTermination.signal.addEventListener('abort', onTermination, { once: true })
-      if (this.outputTermination.signal.aborted) onTermination()
+      this.terminationController.signal.addEventListener('abort', onTermination, { once: true })
+      if (this.terminationController.signal.aborted) onTermination()
     })
   }
 
@@ -596,12 +598,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     // `setsid`, so E2B's command PID is the provisional group id even before the
     // private publication file can be trusted. Kill that group before the SDK-PID
     // fallback, then prove no group member survived before rejecting startup.
-    try {
-      await this.signalGroup(sandbox, handle.pid, 'KILL')
-    } finally {
-      await handle.kill().catch(() => false)
-    }
-    while (await this.groupAlive(sandbox, handle.pid)) await waitTick()
+    await this.forceKillGroup(sandbox, handle, handle.pid)
+    this.markQuiescent()
   }
 
   private async terminateRemote(): Promise<void> {
@@ -618,91 +616,76 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async terminateRemoteInSandbox(): Promise<void> {
     const handle = await this.commandState.promise
-    if (handle === undefined) return
+    if (handle === undefined) {
+      this.markQuiescent()
+      return
+    }
     if (!isValidProcessId(handle.pid) && this.remotePid <= 0) {
       await handle.kill()
-      this.invalidHandleQuiescent = true
+      this.markQuiescent()
       this.commandHandle = undefined
       return
     }
-    if (this.remotePid <= 0) {
-      const sandbox = await this.runtime.getSandbox()
-      this.terminationSignal = 'SIGTERM'
-      try {
-        const delivered = await this.signalGroup(sandbox, handle.pid, 'TERM')
-        if (delivered) {
-          const deadline = Date.now() + this.spec.graceMs
-          while (Date.now() < deadline && await this.groupAlive(sandbox, handle.pid)) await waitTick()
-          if (!await this.groupAlive(sandbox, handle.pid)) {
-            this.provisionalHandleQuiescent = true
-            return
-          }
-        }
-      } catch (_gracefulTerminationFailure) {
-        // A missing or unobservable provisional group still has the SDK handle fallback.
-      }
-      this.terminationSignal = 'SIGKILL'
-      let groupDelivered = false
-      let groupFailure: unknown
-      try {
-        groupDelivered = await this.signalGroup(sandbox, handle.pid, 'KILL')
-      } catch (error: unknown) {
-        groupFailure = error
-      }
-      let handleFailure: unknown
-      try {
-        if (!await handle.kill()) handleFailure = new Error('E2B SDK kill did not report command termination')
-      } catch (error: unknown) {
-        handleFailure = error
-      }
-      if (!groupDelivered && await this.groupAlive(sandbox, handle.pid)) {
-        throw new AggregateError(
-          [
-            ...(groupFailure === undefined ? [] : [groupFailure]),
-            ...(handleFailure === undefined
-              ? [new Error('E2B SDK kill did not quiesce the provisional process group')]
-              : [handleFailure]),
-          ],
-          'subprocess-e2b: force termination failed through both process-group and SDK transports',
-        )
-      }
-      while (await this.groupAlive(sandbox, handle.pid)) await waitTick()
-      this.provisionalHandleQuiescent = true
-      return
-    }
     const sandbox = await this.runtime.getSandbox()
-    const processGroupId = this.remotePid
+    const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
+    await this.terminateGroup(sandbox, handle, processGroupId)
+  }
+
+  private async terminateGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
     this.terminationSignal = 'SIGTERM'
     try {
       await this.signalGroup(sandbox, processGroupId, 'TERM')
-      const deadline = Date.now() + this.spec.graceMs
-      while (Date.now() < deadline && await this.groupAlive(sandbox, processGroupId)) {
-        await waitTick()
+      if (await this.waitForGroupExit(sandbox, processGroupId)) {
+        this.markQuiescent()
+        return
       }
-      if (!await this.groupAlive(sandbox, processGroupId)) return
     } catch (_gracefulTerminationFailure) {
       // Failed TERM delivery or observation cannot prove exit; force cleanup still owns the group.
     }
     this.terminationSignal = 'SIGKILL'
+    await this.forceKillGroup(sandbox, handle, processGroupId)
+    this.markQuiescent()
+  }
+
+  private async forceKillGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
     let groupFailure: unknown
-    let groupDelivered = false
     try {
-      groupDelivered = await this.signalGroup(sandbox, processGroupId, 'KILL')
+      if (!await this.signalGroup(sandbox, processGroupId, 'KILL')) {
+        groupFailure = new Error('process-group KILL did not report delivery')
+      }
     } catch (error: unknown) {
       groupFailure = error
     }
     let handleFailure: unknown
     try {
-      await handle.kill()
+      if (!await handle.kill()) handleFailure = new Error('E2B SDK kill did not report command termination')
     } catch (error: unknown) {
       handleFailure = error
     }
-    if (!groupDelivered && handleFailure !== undefined && await this.groupAlive(sandbox, processGroupId)) {
-      throw new AggregateError(
-        [...(groupFailure === undefined ? [] : [groupFailure]), handleFailure],
-        'subprocess-e2b: force termination failed through both process-group and SDK transports',
-      )
+    let proofFailure: unknown
+    try {
+      if (await this.waitForGroupExit(sandbox, processGroupId)) return
+      proofFailure = new Error(`remote process group ${processGroupId} remained live after force termination`)
+    } catch (error: unknown) {
+      proofFailure = error
     }
+    throw new AggregateError(
+      [
+        ...(groupFailure === undefined ? [] : [groupFailure]),
+        ...(handleFailure === undefined ? [] : [handleFailure]),
+        proofFailure,
+      ],
+      'subprocess-e2b: force termination failed through both process-group and SDK transports',
+    )
+  }
+
+  private async waitForGroupExit(sandbox: Sandbox, processGroupId: number): Promise<boolean> {
+    const deadline = Date.now() + this.spec.graceMs
+    while (await this.groupAlive(sandbox, processGroupId)) {
+      if (Date.now() >= deadline) return false
+      await waitTick()
+    }
+    return true
   }
 
   private throwTerminationFailure(): void {
@@ -710,8 +693,13 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async signalGroup(sandbox: Sandbox, pid: number, signal: 'TERM' | 'KILL'): Promise<boolean> {
+    // TODO(e2b-pgid-identity): Prefer an atomic identity-bound group signal if E2B adds one;
+    // a userspace identity precheck cannot close the numeric-PGID reuse race.
     try {
-      await sandbox.commands.run(`kill -${signal} -- -${pid}`)
+      await sandbox.commands.run(
+        `kill -${signal} -- -${pid}`,
+        commandOpts(this.controlEnvs, undefined),
+      )
       return true
     } catch (error: unknown) {
       if (error instanceof CommandExitError || error instanceof SandboxNotFoundError) return false
@@ -722,7 +710,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private async groupAlive(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<boolean> {
     const result = await sandbox.commands.run(
       `set -o pipefail; ps -eo pgid=,stat= | awk '$1 == ${pid} && $2 !~ /^[ZXx]/ { live=1 } END { if (live) print "live" }'`,
-      signalOpts(signal),
+      commandOpts(this.controlEnvs, signal),
     ).catch((error: unknown) => {
       if (signal?.aborted === true) return undefined
       if (error instanceof SandboxNotFoundError) return { exitCode: 0, stdout: '', stderr: '' }
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 9e0258c10d..ff8af60da9 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -6,6 +6,7 @@ import { PassThrough } from 'node:stream'
 import { posix } from 'node:path'
 import {
   CommandExitError,
+  e2bControlEnvs,
   FileNotFoundError,
   SandboxNotFoundError,
   quoteE2BShellArg,
@@ -20,7 +21,11 @@ import type {
   SubprocessTerminalSpawnSpec,
 } from '@deepseek-ai/dsh-subprocess'
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
-import { readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
+import {
+  bootstrapEnvironment,
+  readRemoteEnvironment,
+  serializeRemoteEnvironment,
+} from './environment.ts'
 
 const POLL_MS = 20
 
@@ -54,6 +59,13 @@ function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
   return signal === undefined ? {} : { signal }
 }
 
+function commandOpts(
+  envs: Record<string, string>,
+  signal?: AbortSignal,
+): { envs: Record<string, string>; signal?: AbortSignal } {
+  return { envs: e2bControlEnvs(envs), ...signalOpts(signal) }
+}
+
 function delay(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms))
 }
@@ -143,8 +155,13 @@ function serializeValues(values: readonly string[], kind: string): string {
   return values.map(value => `${value}\0`).join('')
 }
 
-async function terminalSessionId(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<number> {
-  const result = await sandbox.commands.run(`ps -o sid= -p ${pid}`, signalOpts(signal))
+async function terminalSessionId(
+  sandbox: Sandbox,
+  pid: number,
+  envs: Record<string, string>,
+  signal?: AbortSignal,
+): Promise<number> {
+  const result = await sandbox.commands.run(`ps -o sid= -p ${pid}`, commandOpts(envs, signal))
   signal?.throwIfAborted()
   return parsePositiveId(result.stdout, `subprocess-e2b: cannot resolve process session for terminal ${pid}`)
 }
@@ -169,11 +186,16 @@ async function waitUntilReady(
   }
 }
 
-async function sessionProcessGroups(sandbox: Sandbox, sessionId: number): Promise<number[]> {
+async function sessionProcessGroups(
+  sandbox: Sandbox,
+  sessionId: number,
+  envs: Record<string, string>,
+): Promise<number[]> {
   let result: CommandResult
   try {
     result = await sandbox.commands.run(
       `set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == ${sessionId} && $3 !~ /^[ZXx]/ { print $2 }'`,
+      commandOpts(envs),
     )
   } catch (error: unknown) {
     if (error instanceof SandboxNotFoundError) return []
@@ -194,9 +216,17 @@ async function sessionProcessGroups(sandbox: Sandbox, sessionId: number): Promis
   return [...groups]
 }
 
-async function signalGroups(sandbox: Sandbox, groups: number[], signal: 'TERM' | 'KILL'): Promise<void> {
+async function signalGroups(
+  sandbox: Sandbox,
+  groups: number[],
+  signal: 'TERM' | 'KILL',
+  envs: Record<string, string>,
+): Promise<void> {
   try {
-    await sandbox.commands.run(`kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`)
+    await sandbox.commands.run(
+      `kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`,
+      commandOpts(envs),
+    )
   } catch (error: unknown) {
     if (!(error instanceof CommandExitError) && !(error instanceof SandboxNotFoundError)) throw error
   }
@@ -205,14 +235,15 @@ async function signalGroups(sandbox: Sandbox, groups: number[], signal: 'TERM' |
 async function awaitSessionEmpty(
   sandbox: Sandbox,
   sessionId: number,
+  envs: Record<string, string>,
   graceMs: number,
   kill = false,
 ): Promise<number[]> {
   const deadline = Date.now() + graceMs
   for (;;) {
-    const groups = await sessionProcessGroups(sandbox, sessionId)
+    const groups = await sessionProcessGroups(sandbox, sessionId, envs)
     if (groups.length === 0 || Date.now() >= deadline) return groups
-    if (kill) await signalGroups(sandbox, groups, 'KILL')
+    if (kill) await signalGroups(sandbox, groups, 'KILL', envs)
     await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
   }
 }
@@ -221,6 +252,7 @@ async function rollbackUnpublishedTerminal(
   sandbox: Sandbox,
   handle: CommandHandle,
   completion: Promise<CommandResult>,
+  envs: Record<string, string>,
   graceMs: number,
 ): Promise<void> {
   let topLevelExited = false
@@ -234,20 +266,20 @@ async function rollbackUnpublishedTerminal(
   if (validPid) {
     sessionId = handle.pid
     try {
-      sessionId = await terminalSessionId(sandbox, handle.pid)
+      sessionId = await terminalSessionId(sandbox, handle.pid, envs)
     } catch (_sessionLookupFailure) {
       // E2B's PTY leader is also the provisional POSIX session leader, so its
       // PID remains usable after the setup lookup itself fails or is canceled.
     }
     try {
-      let groups = await sessionProcessGroups(sandbox, sessionId)
+      let groups = await sessionProcessGroups(sandbox, sessionId, envs)
       if (groups.length > 0) {
-        await signalGroups(sandbox, groups, 'TERM')
-        groups = await awaitSessionEmpty(sandbox, sessionId, graceMs)
+        await signalGroups(sandbox, groups, 'TERM', envs)
+        groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs)
       }
       if (groups.length > 0) {
-        await signalGroups(sandbox, groups, 'KILL')
-        await awaitSessionEmpty(sandbox, sessionId, graceMs, true)
+        await signalGroups(sandbox, groups, 'KILL', envs)
+        await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, true)
       }
     } catch (error: unknown) {
       attemptFailures.push(asError(error))
@@ -279,7 +311,7 @@ async function rollbackUnpublishedTerminal(
   const proofFailures: Error[] = []
   if (sessionId !== undefined) {
     try {
-      const groups = await awaitSessionEmpty(sandbox, sessionId, graceMs, true)
+      const groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, true)
       if (groups.length > 0) {
         proofFailures.push(new Error(
           `subprocess-e2b: terminal setup rollback failed; surviving process groups: ${groups.join(', ')}`,
@@ -322,6 +354,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     readonly output: PassThrough,
     private readonly completion: Promise<CommandResult>,
     private readonly sessionId: number,
+    private readonly controlEnvs: Record<string, string>,
     private readonly stateDir: string,
     private readonly graceMs: number,
     signal?: AbortSignal,
@@ -344,7 +377,10 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   /** @inheritdoc */
   async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
     try {
-      const result = await this.sandbox.commands.run(`ps -o tpgid= -p ${this.pid}`)
+      const result = await this.sandbox.commands.run(
+        `ps -o tpgid= -p ${this.pid}`,
+        commandOpts(this.controlEnvs),
+      )
       return {
         processGroupId: parsePositiveId(
           result.stdout,
@@ -369,7 +405,10 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
       throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
     }
-    await this.sandbox.commands.run(`kill -${signal.slice(3)} -- -${foreground.processGroupId}`)
+    await this.sandbox.commands.run(
+      `kill -${signal.slice(3)} -- -${foreground.processGroupId}`,
+      commandOpts(this.controlEnvs),
+    )
     return foreground.processGroupId
   }
 
@@ -402,11 +441,11 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private async closeOnce(): Promise<void> {
-    let groups = await sessionProcessGroups(this.sandbox, this.sessionId)
+    let groups = await sessionProcessGroups(this.sandbox, this.sessionId, this.controlEnvs)
     if (groups.length > 0) {
       this.terminationSignal = 'SIGTERM'
-      await signalGroups(this.sandbox, groups, 'TERM')
-      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.graceMs)
+      await signalGroups(this.sandbox, groups, 'TERM', this.controlEnvs)
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs)
     }
     if (groups.length === 0 && !this.topLevelExited) {
       await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
@@ -421,7 +460,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
           throw error
         }
       }
-      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.graceMs, true)
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs, true)
       if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
     }
     if (groups.length > 0) {
@@ -469,13 +508,18 @@ export async function spawnE2BTerminal(
   let handle: CommandHandle | undefined
   let completion: Promise<CommandResult> | undefined
   let stateDirectoryCreated = false
+  let controlEnvs: Record<string, string> = {}
   try {
     const ambient = await readRemoteEnvironment(sandbox, spec.signal)
+    controlEnvs = bootstrapEnvironment(ambient)
     const environment = serializeRemoteEnvironment(ambient, spec.env)
     const argv = serializeValues(spec.argv, 'argv')
-    await sandbox.files.makeDir(stateDir)
     stateDirectoryCreated = true
-    await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stateDir)}`, signalOpts(spec.signal))
+    await sandbox.files.makeDir(stateDir, signalOpts(spec.signal))
+    await sandbox.commands.run(
+      `chmod 700 -- ${quoteE2BShellArg(stateDir)}`,
+      commandOpts(controlEnvs, spec.signal),
+    )
     await sandbox.files.write([
       { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
       { path: paths.environment, data: environment },
@@ -484,13 +528,13 @@ export async function spawnE2BTerminal(
     ], signalOpts(spec.signal))
     await sandbox.commands.run(
       `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)} ${quoteE2BShellArg(paths.outputMarker)}`,
-      signalOpts(spec.signal),
+      commandOpts(controlEnvs, spec.signal),
     )
     handle = await sandbox.pty.create({
       rows: spec.rows,
       cols: spec.cols,
       cwd: spec.cwd,
-      envs: { TERM: 'dumb' },
+      envs: e2bControlEnvs(controlEnvs),
       timeoutMs: 0,
       onData: (data) => { outputFilter.push(data) },
     })
@@ -504,13 +548,14 @@ export async function spawnE2BTerminal(
     await sandbox.pty.sendInput(handle.pid, Buffer.from(command), signalOpts(spec.signal))
     await waitUntilReady(sandbox, paths, completion, spec.signal)
     await waitForBootstrapOutput(outputFilter.ready, completion, spec.signal)
-    const sessionId = await terminalSessionId(sandbox, handle.pid, spec.signal)
+    const sessionId = await terminalSessionId(sandbox, handle.pid, controlEnvs, spec.signal)
     return new E2BTerminalHandle(
       sandbox,
       handle,
       output,
       completion,
       sessionId,
+      controlEnvs,
       stateDir,
       spec.graceMs,
       spec.signal,
@@ -524,7 +569,7 @@ export async function spawnE2BTerminal(
       if (!terminalQuiescent && handle !== undefined) {
         try {
           if (completion === undefined) await handle.kill()
-          else await rollbackUnpublishedTerminal(sandbox, handle, completion, spec.graceMs)
+          else await rollbackUnpublishedTerminal(sandbox, handle, completion, controlEnvs, spec.graceMs)
           terminalQuiescent = true
         } catch (cleanupError: unknown) {
           if (cleanupError instanceof SandboxNotFoundError) terminalQuiescent = true
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index d3c96cf2fc..0e906b1cfb 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -111,6 +111,7 @@ class FakeSandbox {
   alive = true
   zombieOnly = false
   ambient = 'PATH=/ambient/bin\0KEEP=safe\0UNICODE=你好\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  environmentHome = '/home/user'
   environmentWire: string | undefined
   environmentRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
   processGroupId = '4242\n'
@@ -241,7 +242,9 @@ class FakeSandbox {
           if (this.envError !== undefined) throw this.envError
           return {
             exitCode: 0,
-            stdout: this.environmentWire ?? Buffer.from(this.ambient).toString('base64'),
+            stdout: this.environmentWire ?? [this.environmentHome, this.ambient]
+              .map(value => Buffer.from(value).toString('base64'))
+              .join('\n'),
             stderr: '',
           }
         }
@@ -396,7 +399,14 @@ describe('E2BSubprocessHandle', () => {
     expect(handle.pid).toBe(4343)
     expect(fake.handle.sent.map(value => String(value))).toEqual(['hello'])
     expect(fake.handle.closes).toBe(1)
-    expect(fake.startOptions?.envs).toBeUndefined()
+    const controlEnvs = fake.startOptions?.envs
+    expect(controlEnvs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(controlEnvs).toEqual({
+      TERM: 'dumb',
+      NPM_TOKEN: '',
+      DSH_STALE: '',
+      HOME: controlEnvs?.HOME,
+    })
     const command = fake.commandsSeen.find(value => value.includes('exec "$dsh_e2b_env_bin" -i'))!
     expect(command).toContain('"$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c')
     expect(command).not.toContain('DEEPSEEK_API_KEY')
@@ -405,7 +415,9 @@ describe('E2BSubprocessHandle', () => {
     expect(command).not.toContain('explicit-secret')
     expect(command).not.toContain('hyphen-value')
     expect(command).not.toContain('${!dsh_e2b_name}')
-    expect(fake.commandsSeen).toContain('set -o pipefail; env -0 | base64 -w 0')
+    expect(fake.commandsSeen).toContain(
+      'set -o pipefail; printf \'%s\' "$PWD" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
+    )
     expect(command).toContain('mapfile -d')
     expect(command).toContain('dsh_e2b_node="$(command -v node)"')
     expect(command).toContain('"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e')
@@ -421,7 +433,7 @@ describe('E2BSubprocessHandle', () => {
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
     expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
-      'PATH=/bin\0KEEP=safe\0UNICODE=你好\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+      'PATH=/bin\0KEEP=safe\0UNICODE=你好\0HOME=/home/user\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
     )
 
     let piped = ''
@@ -560,6 +572,7 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
     expect(fake.handle.disconnects).toBe(1)
     fake.alive = false
+    handle.terminate()
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
@@ -783,7 +796,7 @@ describe('E2BSubprocessHandle', () => {
     expect(fake.handle.kills).toBe(1)
   })
 
-  it('does not treat successful termination transport as observed quiescence', async () => {
+  it('keeps force cleanup retryable until quiescence is proven', async () => {
     const fake = new FakeSandbox()
     fake.trapsTerm = true
     fake.delaysKill = true
@@ -793,16 +806,15 @@ describe('E2BSubprocessHandle', () => {
     await flush()
     handle.terminate()
     await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    expect(fake.alive).toBe(true)
 
-    let quiescent = false
-    const waiting = handle.waitForExit().then((value) => { quiescent = value })
-    await new Promise(resolve => setTimeout(resolve, 10))
-    expect(quiescent).toBe(false)
-
-    fake.alive = false
-    fake.finish()
-    await waiting
-    expect(quiescent).toBe(true)
+    fake.delaysKill = false
+    fake.delaysKillCompletion = false
+    fake.sdkKillStops = true
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
   })
 
   it('honors termination requested before asynchronous startup finishes', async () => {
@@ -870,14 +882,10 @@ describe('E2BSubprocessHandle', () => {
 
     handle.terminate()
     await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
-    let quiescent = false
-    const waiting = handle.waitForExit().then((value) => { quiescent = value })
-    await new Promise(resolve => setTimeout(resolve, 10))
-    expect(quiescent).toBe(false)
-
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
     fake.alive = false
-    await waiting
-    expect(quiescent).toBe(true)
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
     fake.releaseProcessGroupRead()
     fake.finish()
     await handle.done
@@ -1102,23 +1110,36 @@ describe('E2BSubprocessHandle', () => {
     await expect(envHandle.done).rejects.toThrow('ambient lookup failed')
     expect(envFailure.removed).toEqual([])
 
-    const malformedEnvironment = new FakeSandbox()
-    malformedEnvironment.environmentWire = '%'
-    const malformedEnvironmentHandle = new E2BSubprocessHandle(
-      runtime(malformedEnvironment),
-      spec(),
-      '/runtime/malformed-environment',
+    const expectEnvironmentFailure = async (name: string, wire: string, message: string): Promise<void> => {
+      const fake = new FakeSandbox()
+      fake.environmentWire = wire
+      const failed = new E2BSubprocessHandle(runtime(fake), spec(), `/runtime/${name}`)
+      await expect(failed.done).rejects.toThrow(message)
+    }
+    const encodedEnvironment = Buffer.from('PATH=/bin\0').toString('base64')
+    const encodedHome = Buffer.from('/home/user').toString('base64')
+    await expectEnvironmentFailure('malformed-frame', '%', 'invalid base64')
+    await expectEnvironmentFailure('malformed-base64', `${encodedHome}\n%`, 'invalid base64')
+    await expectEnvironmentFailure(
+      'invalid-utf8-home',
+      `${Buffer.from([0xff]).toString('base64')}\n${encodedEnvironment}`,
+      'not valid UTF-8',
     )
-    await expect(malformedEnvironmentHandle.done).rejects.toThrow('invalid base64')
-
-    const invalidUtf8Environment = new FakeSandbox()
-    invalidUtf8Environment.environmentWire = Buffer.from([0xff]).toString('base64')
-    const invalidUtf8EnvironmentHandle = new E2BSubprocessHandle(
-      runtime(invalidUtf8Environment),
-      spec(),
-      '/runtime/invalid-utf8-environment',
+    await expectEnvironmentFailure(
+      'invalid-utf8-environment',
+      `${encodedHome}\n${Buffer.from([0xff]).toString('base64')}`,
+      'not valid UTF-8',
+    )
+    await expectEnvironmentFailure(
+      'relative-home',
+      `${Buffer.from('home/user').toString('base64')}\n${encodedEnvironment}`,
+      'remote login home is invalid',
+    )
+    await expectEnvironmentFailure(
+      'nul-home',
+      `${Buffer.from('/home/user\0tail').toString('base64')}\n${encodedEnvironment}`,
+      'remote login home is invalid',
     )
-    await expect(invalidUtf8EnvironmentHandle.done).rejects.toThrow('not valid UTF-8')
 
     const cleanupFailure = new FakeSandbox()
     cleanupFailure.backgroundError = new Error('start failed before credential consumption')
@@ -1318,10 +1339,11 @@ describe('E2BSubprocessHandle', () => {
     const failures = Array.from(failure.errors as Iterable<unknown>)
     expect(failures).toHaveLength(2)
     expect(failures[0]).toBeInstanceOf(Error)
-    expect(failures[1]).toBeInstanceOf(Error)
-    if (!(failures[0] instanceof Error) || !(failures[1] instanceof Error)) throw new Error('expected nested errors')
+    expect(failures[1]).toBeInstanceOf(AggregateError)
+    if (!(failures[0] instanceof Error) || !(failures[1] instanceof AggregateError)) throw new Error('expected nested errors')
     expect(failures[0].message).toContain('invalid process-group id')
-    expect(failures[1].message).toBe('rollback signal failed')
+    expect(failures[1].message).toBe('subprocess-e2b: force termination failed through both process-group and SDK transports')
+    expect(Array.from(failures[1].errors as Iterable<unknown>)).toContainEqual(new Error('rollback signal failed'))
     expect(fake.handle.kills).toBe(1)
     const bounded = new AbortController()
     const waiting = handle.waitForExit(bounded.signal)
@@ -1330,6 +1352,15 @@ describe('E2BSubprocessHandle', () => {
     handle.terminate()
     await expect(handle.waitForExit()).resolves.toBe(true)
     expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
+
+    const naturallyGone = new FakeSandbox()
+    naturallyGone.processGroupId = 'not-a-pid\n'
+    naturallyGone.signalError = new Error('rollback signal failed')
+    naturallyGone.handle.killError = new Error('SDK kill failed')
+    const observed = new E2BSubprocessHandle(runtime(naturallyGone), spec(), '/runtime/failed-rollback-observed')
+    await expect(observed.done).rejects.toThrow('process-group publication failed')
+    naturallyGone.alive = false
+    await expect(observed.waitForExit()).resolves.toBe(true)
   })
 
   it('waits for delayed process-group publication', async () => {
@@ -1479,6 +1510,24 @@ describe('E2BSubprocessHandle', () => {
     raced.terminate()
     await expect(raced.waitForExit()).resolves.toBe(true)
   })
+
+  it('rejects an optimistic SDK kill while descendants survive a failed group KILL', async () => {
+    const fake = new FakeSandbox()
+    fake.trapsTerm = true
+    fake.sdkKillStops = false
+    fake.signalErrors.push(undefined, new Error('KILL transport failed'))
+    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/optimistic-sdk-kill')
+    await flush()
+
+    handle.terminate()
+    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    expect(fake.alive).toBe(true)
+
+    fake.sdkKillStops = true
+    handle.terminate()
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+  })
 })
 
 describe('E2BSubprocessService', () => {
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 00b9fc41fc..8ad0eb1dde 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -23,6 +23,7 @@ function commandError(exitCode: number): CommandExitError {
 interface CommandOptions {
   signal?: AbortSignal
   cwd?: string
+  envs?: Record<string, string>
 }
 
 class FakeTerminalCommandHandle {
@@ -101,6 +102,7 @@ class FakeTerminalSandbox {
   writeError: unknown
   sendError: unknown
   commandFailure: unknown
+  makeDirRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
   sessionGroupsFailure: unknown
   foregroundFailure: unknown
   termFailure: unknown
@@ -129,8 +131,10 @@ class FakeTerminalSandbox {
 
   readonly sandbox = {
     files: {
-      makeDir: async (path: string): Promise<boolean> => {
+      makeDir: async (path: string, options?: CommandOptions): Promise<boolean> => {
         this.directories.push(path)
+        await this.makeDirRequest?.(options?.signal)
+        options?.signal?.throwIfAborted()
         return true
       },
       write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
@@ -163,7 +167,11 @@ class FakeTerminalSandbox {
           throw error
         }
         if (command.includes('env -0 | base64')) {
-          return { exitCode: 0, stdout: Buffer.from(this.ambient).toString('base64'), stderr: '' }
+          return {
+            exitCode: 0,
+            stdout: ['/home/user', this.ambient].map(value => Buffer.from(value).toString('base64')).join('\n'),
+            stderr: '',
+          }
         }
         if (command.includes('command -v -- ')) {
           return { exitCode: 0, stdout: this.resolvedExecutable, stderr: '' }
@@ -262,7 +270,15 @@ describe('E2B terminal allocation', () => {
     expect(output).toBe('requested-shell$ ')
     expect(output).not.toContain('buffered banner')
     expect(output).not.toContain('runner.bash')
-    expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0, envs: { TERM: 'dumb' } })
+    expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0 })
+    const controlEnvs = fake.createOptions?.envs
+    expect(controlEnvs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(controlEnvs).toEqual({
+      TERM: 'dumb',
+      NPM_TOKEN: '',
+      DSH_STALE: '',
+      HOME: controlEnvs?.HOME,
+    })
     expect(fake.inputs[0]?.data.toString()).toContain("exec /bin/bash '/runtime/terminal-one/runner.bash'")
     expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('KEEP=visible\0')
     expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('UNICODE=你好\0')
@@ -554,6 +570,7 @@ describe('E2B terminal lifecycle', () => {
       new PassThrough(),
       fake.handle.wait(),
       123,
+      { TERM: 'dumb' },
       '/runtime/pre-aborted',
       1,
       controller.signal,
@@ -807,7 +824,10 @@ describe('E2B subprocess terminal service', () => {
     fake.resolvedExecutable = 'tools/bin/node\n'
     await expect(ctx.subprocess.resolveExecutable('node', { PATH: 'tools/bin' }))
       .resolves.toBe('/workspace/tools/bin/node')
-    expect(fake.commandOptions.at(-1)).toMatchObject({ cwd: '/workspace' })
+    const commandOptions = fake.commandOptions.at(-1)
+    expect(commandOptions).toMatchObject({ cwd: '/workspace' })
+    expect(commandOptions?.envs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(commandOptions?.envs).toEqual({ HOME: commandOptions?.envs?.HOME })
     expect((ctx.e2b)).toBeDefined()
   })
 
@@ -867,6 +887,29 @@ describe('E2B subprocess terminal service', () => {
     expect(fake.handle.disconnects).toBe(1)
   })
 
+  it('owns and cancels terminal state-directory creation during disposal', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.makeDirRequest = async (signal) => {
+      await new Promise<never>((_resolve, reject) => {
+        const onAbort = (): void => {
+          const reason: unknown = signal?.reason
+          reject(reason instanceof Error ? reason : new Error(String(reason)))
+        }
+        signal?.addEventListener('abort', onAbort, { once: true })
+        if (signal?.aborted === true) onAbort()
+      })
+    }
+    const { ctx, fiber } = await service(fake)
+    const spawning = ctx.subprocess.spawnTerminal(spec())
+    const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
+    await vi.waitFor(() => { expect(fake.directories.some(path => path.includes('/terminals/'))).toBe(true) })
+
+    await fiber.dispose()
+    await rejected
+    expect(fake.removed.some(path => path.includes('/terminals/'))).toBe(true)
+    expect(fake.createOptions).toBeUndefined()
+  })
+
   it('retains failed terminal setup cleanup for disposal retry', async () => {
     const fake = new FakeTerminalSandbox()
     fake.sendError = new Error('bootstrap failed')

From 65b345c96a77a40628ad6bbdee9c065894d03957 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 16:17:56 +0800
Subject: [PATCH 379/516] test(e2b): tolerate real-provider runtime latency

---
 examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 93bb6b65e5..d2b73c1077 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -63,7 +63,7 @@
   name: '@deepseek-ai/dsh-code-runtime-subprocess'
   config:
     computeMs: 500
-    maxWallMs: 5000
+    maxWallMs: 15000
     maxOutputBytes: 4096
     maxOldGenerationSizeMb: 128
     maxFrameBytes: 32768

From 917a7493f7ba0e6e2ab59a458d08566aa14669cc Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 19:07:11 +0800
Subject: [PATCH 380/516] refactor(e2b): keep provider layer substrate-only

---
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |  26 +++
 ...8-portable-execution-world-consumers.zh.md |  44 ++++-
 ...026-07-27-e2b-remote-runtime-poc.i18n.yaml |   6 -
 .../2026-07-27-e2b-remote-runtime-poc.md      |  65 --------
 .../2026-07-27-e2b-remote-runtime-poc.zh.md   |  65 --------
 .../tests/fixtures/e2b/e2b/bin.ts             |  58 +++----
 packages/e2b/README.i18n.yaml                 |   4 +-
 packages/e2b/README.md                        |   2 +-
 packages/e2b/README.zh.md                     |   2 +-
 packages/e2b/e2b/tests/composition.e2e.ts     |   4 +-
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   6 +-
 packages/e2b/fs-e2b/README.zh.md              |   6 +-
 packages/e2b/fs-e2b/src/index.ts              | 129 +++++----------
 packages/e2b/fs-e2b/src/source-reader.ts      |  63 --------
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  | 152 +++++++-----------
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |   6 +-
 packages/e2b/subprocess-e2b/README.zh.md      |   6 +-
 .../e2b/subprocess-e2b/src/environment.ts     |   2 +
 packages/e2b/subprocess-e2b/src/index.ts      |  16 +-
 packages/e2b/subprocess-e2b/src/process.ts    |   4 +-
 packages/e2b/subprocess-e2b/src/terminal.ts   |  37 +++--
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 135 +++++-----------
 packages/fs/README.i18n.yaml                  |   4 +-
 packages/fs/README.md                         |   2 +-
 packages/fs/README.zh.md                      |   2 +-
 28 files changed, 280 insertions(+), 578 deletions(-)
 delete mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
 delete mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
 delete mode 100644 .agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
 delete mode 100644 packages/e2b/fs-e2b/src/source-reader.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 06fd47f329..fc3b5b012f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 402aa580255a5bd6aa0d046e3bcc16f712da520d
-2026-07-28-portable-execution-world-consumers.zh.md: 26d493a79f8adb9e729ff69b0673f2f2775868b0
+2026-07-28-portable-execution-world-consumers.md: 250445cfed6a4fe2dd188562813d586df29992c1
+2026-07-28-portable-execution-world-consumers.zh.md: 361c4de4e813aa7f57a7eb5acc75087b2630db43
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 402aa58025..4c593604f4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -8,6 +8,8 @@ English | [中文](2026-07-28-portable-execution-world-consumers.zh.md)
 
 The filesystem and subprocess seams made file and ordinary process access replaceable, but PTY and LSP still reached host Node APIs directly. A remote execution provider therefore appeared to need separate PTY and LSP packages even though their domain behavior did not change. Those packages would be shallow adapters: each would duplicate an existing consumer merely to replace its file and process operations.
 
+A remote coding world is useful only when file operations, commands, terminals, language servers, and model-written programs share one sandbox identity. Moving the complete harness into that sandbox would also entangle provider experimentation with plugin loading, credentials, model transport, session durability, supervision, and deployment.
+
 Ordinary pipes do not cover one requirement. A persistent terminal needs PTY allocation, foreground-process-group inspection and signalling, and cleanup of the complete terminal session. Pretending those operations can be rebuilt in `dsh-pty-local` from an ordinary `spawn()` handle would either leak provider internals or weaken its lifecycle contract.
 
 ## Decision
@@ -24,10 +26,26 @@ Generic consumers use that execution world:
 - `dsh-lsp-local` reads and contains source through `ctx.fs`, resolves and launches language servers through `ctx.subprocess`, and carries provider-owned file URIs through initialization and result rendering. One provider-lifetime signal aborts filesystem and protocol work during disposal, including workspace lookup before queue ownership; its JSON-RPC, pooling, synchronization, and normalization stay unchanged.
 - `dsh-pty-local` maps persistent-shell semantics onto `ctx.subprocess.spawnTerminal()`. The local `node-pty` and process-inspection implementation moves into `dsh-subprocess-local`; another subprocess provider supplies the same primitive. `danger-full-access` needs no `ctx.sandbox`; a confined mode requires a same-world sandbox provider and fails before spawn when none is mounted. Prompt and silence evidence collected during asynchronous pre-write inspection is discarded when the provider write begins. Cancellation retains the send reservation while an in-flight write settles and then signals the foreground group, so late bytes or the signal cannot target a successor; an in-flight readiness poll cannot release that reservation, and a rejected write sends no signal. The absolute deadline remains armed throughout cancellation. A signal failure becomes terminal transport failure. Completion of a stale inspection resumes polling for the current send. Startup cancellation begins terminal rollback without waiting for a stalled readiness or signalling call. Close rejects new public signals and delegates provider-observable session quiescence to the handle's awaited termination operation.
 
+## E2B POC boundary
+
+The opt-in E2B realization has exactly three provider-specific packages under `packages/e2b/`: `dsh-e2b` creates or reconnects one sandbox and owns kill/pause/leave disposal, `dsh-fs-e2b` implements `ctx.fs`, and `dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, PTYs, and remote Linux process groups. The two adapters obtain the sole sandbox identity from the owner and never create private sandboxes.
+
+E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, subprocess Code Runtime processes, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, Code Runtime program/binding/output policy, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
+
+The adapters retain only substrate mechanics. Filesystem canonicalization crosses the SDK's decoded command transport as strict base64-encoded NUL framing; streamed reads leave byte ceilings with consumers. Subprocess command output and environment snapshots use ASCII/base64 where SDK chunk decoding would otherwise lose bytes, while private control shells isolate profiles and later launches blank discovered credential-shaped names. Process and terminal cleanup uses remote groups and proves quiescence before settlement.
+
+Retaining a sandbox preserves remote files and unmanaged state only. Reconnect does not reconstruct host process or terminal handles, protocol connections, pending calls, output cursors, timers, or locks. The POC adds no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, workspace synchronization, durable remote handles, or whole-harness execution.
+
+## Verification
+
+Focused package suites pin sandbox lifecycle, canonical path framing, filesystem metadata and atomic versions, subprocess publication/rollback, terminal text I/O and session cleanup, output limits, cancellation, disposal, and invariant registration. A credential-gated Loader composition exercises the same three-package provider through source imports and built exports, including FS/Bash visibility, post-rename version reread plus guarded edit, hostile login profiles, byte-split UTF-8 output, process and terminal cleanup, LSP document bounds, Code Runtime bindings/limits/cleanup, host-workspace isolation, and final sandbox deletion.
+
 ## Alternatives considered
 
 **Keep one PTY and LSP package per remote provider.** Rejected because provider mechanics would be repeated above the existing seams. The deletion test exposes the problem: deleting those adapters should not scatter domain behavior into the remote provider; the generic consumers already own it.
 
+**Create a separate sandbox per capability or tool.** Rejected because file and process operations would not share identity or state, defeating the coding use case and multiplying lifecycle owners.
+
 **Model a terminal as an ordinary piped subprocess.** Rejected because pipes cannot allocate a controlling terminal, resolve the current foreground process group, or prove complete terminal-session cleanup. One terminal primitive is smaller and more honest than exposing substrate-specific escape hatches.
 
 **Move PTY readiness and session policy into the subprocess service.** Rejected because those are persistent-terminal consumer semantics, not OS process mechanics. A subprocess provider owns what only its substrate can do; `dsh-pty-local` owns what a Harness terminal means.
@@ -38,6 +56,12 @@ Generic consumers use that execution world:
 
 **Run the whole harness inside the remote environment.** Rejected as a different deployment model. Making execution capabilities portable does not move model calls, session state, plugin state, or the agent loop.
 
+**Put every provider operation in one shared owner package.** Rejected because sandbox identity and lifecycle are the owner's only concerns. Filesystem and subprocess retain distinct contracts, tests, and consumers without turning the owner into a capability grab bag.
+
+**Implement remote filesystem operations only through shell commands.** Rejected because that discards structured filesystem identity, errors, streaming, version guards, and atomic mutation semantics already consumed by the file tools.
+
+**Add a generic distributed-runtime abstraction or reconnect live handles.** Rejected because the existing capability seams carry the demonstrated contracts, while remote identity alone cannot reconstruct callbacks, pending promises, authority, protocol state, or output cursors. A new layer would speculate about persistence and synchronization beyond the POC.
+
 ## Consequences
 
 A remote execution provider implements only its shared sandbox owner plus filesystem and subprocess adapters. Bash, PTY, and LSP compose above them, so fixes to those capabilities remain provider-neutral.
@@ -45,3 +69,5 @@ A remote execution provider implements only its shared sandbox owner plus filesy
 The fundamental interfaces are wider, and a filesystem/subprocess pair must agree on one execution world. The added operations are limited to facts and lifecycle mechanics that current generic consumers require; model schemas, protocol framing, readiness policy, and presentation do not leak into the providers.
 
 The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal sweeps descendants before and after terminating the top-level shell, waits for exact PID-identity-fenced descendants retained during foreground inspection, and retains Linux session members that survive top-level exit. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer.
+
+The E2B composition demonstrates that a shared sandbox owner plus filesystem and subprocess adapters are sufficient to move the mutable coding world off-host while leaving higher capabilities provider-neutral. Its POC limits remain explicit: the SDK retains complete command transport in host memory, remote startup cannot publish a PID synchronously, exact terminal stdin-wait and independent signal facts are unavailable, numeric PID/PGID operations are not identity-fenced, the initial environment probe cannot hide unknown sandbox-default secrets from already-running same-UID processes, retained artifacts accumulate, and escaped processes or reconnect state are not recovered. These are provider constraints, not justification for compatibility shims or more E2B packages.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 26d493a79f..361c4de4e8 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -6,7 +6,9 @@ Status: implemented
 
 ## 问题
 
-文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但 PTY 和 LSP 仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY 与 LSP 包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
+文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但若干上层能力仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY、LSP 与代码运行时包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
+
+只有文件操作、命令、终端、语言服务器和模型编写的程序共享同一个沙箱身份时，远程编码世界才有用。若把完整 harness 移入该沙箱，还会把提供方实验与插件加载、凭据、模型传输、会话持久性、监督和部署纠缠在一起。
 
 普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期契约。
 
@@ -16,16 +18,36 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责可执行文件查找与进程原语：以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使整个会话完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
+- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
+
+`dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
+
+## E2B POC 边界
+
+可选启用的 E2B 实现在 `packages/e2b/` 下恰好只有三个提供方专用包：`dsh-e2b` 创建或重新连接一个沙箱，并负责 kill、pause 或 leave 资源释放；`dsh-fs-e2b` 实现 `ctx.fs`；`dsh-subprocess-e2b` 基于 E2B Commands、PTY 和远程 Linux 进程组实现 `ctx.subprocess`。两个适配器都从所有者取得唯一的沙箱身份，绝不创建私有沙箱。
+
+E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取、子进程代码运行时进程，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态、代码运行时程序／绑定／输出策略，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
+
+适配器只保留执行基底机制。文件系统规范化以严格的 base64 加 NUL 分帧穿过 SDK 已解码的命令传输；流式读取把字节上限留给消费方执行。进程管理命令输出与环境快照采用 ASCII/base64，避免 SDK 分片解码丢失字节；私有控制 shell 隔离 profile，后续启动会把已发现且名称呈凭据特征的环境变量置空。进程与终端清理使用远程进程组，并在结算前证明完全停稳。
+
+保留沙箱只会保留远程文件与非托管状态。重新连接不会重建宿主进程或终端句柄、协议连接、待处理调用、输出游标、计时器或锁。该 POC 不会新增会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录、工作区同步、持久远程句柄，也不会在其中运行整个 harness。
+
+## 验证
+
+聚焦的包测试套件锁定了沙箱生命周期、规范化路径分帧、文件系统元数据与原子版本、进程管理发布／回滚、终端文本 I/O 与会话清理、输出上限、取消、资源释放和不变式注册。一项受凭据门控的 Loader 组合通过源代码导入与构建后导出运行同一套三包提供方组合，其中包括 FS/Bash 可见性、重命名后的版本重读与带保护编辑、恶意登录 profile、跨字节边界拆分的 UTF-8 输出、进程与终端清理、LSP 文档上限、代码运行时绑定／上限／清理、宿主工作区隔离，以及最终沙箱删除。
+
 ## 考虑过的替代方案
 
-**为每个远程提供方分别保留 PTY 与 LSP 包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
+**为每个远程提供方分别保留 PTY、LSP 和代码运行时包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
+
+**为每项能力或工具创建独立沙箱。** 不予采纳，因为文件与进程操作将无法共享身份或状态，从而破坏编码用例，并增加生命周期所有者的数量。
 
 **把终端建模为普通的管道子进程。** 不予采纳，因为管道无法分配控制终端、确定当前前台进程组或证明完整终端会话已清理。一项终端原语比公开特定于执行基底的逃生口更小，也更能如实表达契约。
 
@@ -35,12 +57,22 @@ Status: implemented
 
 **在文件系统 seam 中新增稳定的有界读取原语。** 不予采纳，因为只有 LSP 需要完整文档字节上限，而它可以在消费现有文本流时执行该上限。第二项原语会迫使每个提供方实现稳定句柄和不跟随符号链接的机制，远程提供方甚至需要辅助协议，却没有已观察到的并发替换缺陷。
 
-**在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop（智能体循环）。
+**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件和文件系统物化，而 worker 后端两者都不需要，并且仍是受支持的单进程路径。
+
+**在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop。
+
+**把所有提供方操作都放进一个共享所有者包。** 不予采纳，因为沙箱身份与生命周期是所有者唯一的关注点。文件系统与进程管理保留各自独立的契约、测试和消费方，同时避免把所有者变成无边界的能力集合。
+
+**只通过 shell 命令实现远程文件系统操作。** 不予采纳，因为这会丢弃现有文件工具已消费的结构化文件系统身份、错误、流式输出、版本保护和原子变更语义。
+
+**新增通用分布式运行时抽象，或重新连接活跃句柄。** 不予采纳，因为现有能力 seam 已承载经证实的契约，而仅凭远程身份无法重建回调、待处理 promise、权限、协议状态或输出游标。新增一层只会推测 POC 边界之外的持久化与同步问题。
 
 ## 后果
 
-远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY 与 LSP 组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
+远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY、LSP 和基于进程管理的代码运行时组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
 
 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
 
 本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会在终止顶层 shell 前后清理后代进程，等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程，并继续追踪在顶层进程退出后仍存活的 Linux 会话成员。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。
+
+E2B 组合证明，共享沙箱所有者加上文件系统与进程管理适配器，就足以在保持上层能力与提供方无关的同时，把可变编码世界移出宿主。其 POC 限制仍明确在案：SDK 会把完整命令传输内容保留在宿主内存中；远程启动无法同步发布 PID；无法获得精确的终端 stdin 等待状态与独立信号事实；基于数值 PID/PGID 的操作没有身份围栏；初始环境探测无法向已在运行的同 UID 进程隐藏未知的沙箱默认 secret；保留的产物会累积；也不会恢复逃逸进程或重连状态。这些是提供方限制，不是引入兼容性 shim 或更多 E2B 包的理由。
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
deleted file mode 100644
index 2c3db3fad4..0000000000
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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-e2b-remote-runtime-poc.md
-2026-07-27-e2b-remote-runtime-poc.md: 79c5bfe2dfa11cd695c7134e6ceffb639b449688
-2026-07-27-e2b-remote-runtime-poc.zh.md: 729a10ec7efa4dd55f041dc804d2252102b13c01
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
deleted file mode 100644
index 79c5bfe2df..0000000000
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# Agent Note: Shared E2B remote runtime POC
-
-Status: implemented
-
-English | [中文](2026-07-27-e2b-remote-runtime-poc.zh.md)
-
-## Problem
-
-A remote coding-agent backend is useful only when filesystem operations, one-shot commands, persistent terminals, language servers, and model-written programs observe one coherent world. Attaching E2B independently at individual tools would let those capabilities address different sandboxes, while retaining host PTY, LSP, or worker backends would split state across machines even when the cwd strings match.
-
-Moving the complete harness into a remote VM would unify that state but also couple provider experimentation to plugin loading, credentials, model transport, agent/session durability, supervision, and deployment. The POC needs to test the existing capability boundaries without taking on those independent concerns.
-
-## Decision
-
-The E2B integration is an opt-in provider-composition POC. Its three E2B-specific packages live together under `packages/e2b/`:
-
-- `@deepseek-ai/dsh-e2b` creates or reconnects one secure E2B sandbox, creates its working and private runtime directories, and owns kill/pause/leave disposal.
-- `@deepseek-ai/dsh-fs-e2b` implements `ctx.fs` over that sandbox's Filesystem API.
-- `@deepseek-ai/dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, byte PTYs, and remote Linux process groups.
-
-The higher capabilities use provider-neutral implementations. `dsh-bash-local` delegates command mechanics to `ctx.subprocess`; `dsh-pty-local` delegates terminal allocation and signalling to `ctx.subprocess.spawnTerminal()`; `dsh-lsp-local` reads through `ctx.fs` and launches through `ctx.subprocess`; `dsh-code-runtime-subprocess` materializes its runner through `ctx.fs` and starts it through `ctx.subprocess`. The [portable execution-world decision](../architecture/2026-07-28-portable-execution-world-consumers.md) owns those generic interfaces and consumers.
-
-The E2B owner is the sole source of sandbox identity. Its two adapters never create private sandboxes, so filesystem tools, Bash, interactive shells, language servers, and code workers share one remote cwd, process namespace, and adapter-private directory while preserving the existing capability interfaces, generic implementations, model-facing tools, and agent loop.
-
-## POC boundary
-
-E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session process groups, language-server processes and source reads, the Code Runtime launcher, controller, and worker, and adapter-private files under `.dsh-e2b`.
-
-The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority decisions, skills, subagent orchestration, PTY buffers and readiness state, LSP JSON-RPC ids/queues/protocol state, Code Runtime type stripping/output accounting/binding dispatch, and E2B SDK/network orchestration. The overlay does not upload, mount, or synchronize the host workspace; identical cwd strings name independent host and remote directories.
-
-The fundamental adapters carry the substrate-specific mechanics. Adapter-internal E2B command and PTY login shells use a fresh randomized root-level `HOME`; `dsh-subprocess-e2b` also gives them empty overrides for scrubbed credential names before user profiles run. The subprocess adapter consumes E2B's byte PTY callback, transports environment snapshots and command bytes as ASCII/base64 across decoded SDK callbacks, and uses one cancellation controller plus one retryable group-cleanup transaction that reports success only after proving quiescence. `dsh-fs-e2b` performs bounded source reads through a dependency-free helper that walks no-follow directory descriptors beneath the canonical target. Generic Code Runtime keeps its controller/worker protocol on validated newline-delimited UTF-8 JSON and kills the provider-owned process group before inherited pipes drain. Generic LSP uses byte-faithful UTF-8 JSON over command pipes.
-
-Retaining a sandbox preserves remote files and unmanaged remote state only. Reconnect does not reconstruct host PTY sessions, buffers, process handles, LSP connections or requests, code workers, binding calls, timers, output cursors, or locks. Managed groups terminate and join when their provider disposes before the shared owner pauses, leaves, or kills the sandbox.
-
-The POC has no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, workspace synchronization, durable remote handles, or whole-harness execution.
-
-## Verification
-
-Focused package suites pin owner lifecycle cleanup, filesystem paths/containment/bounded descriptor reads and commit metadata, subprocess executable lookup/process groups/publication rollback, terminal byte I/O/signal identity/default-environment scrubbing/session cleanup, output limits, abort ordering, disposal to quiescence, and package-owned invariant registrations. The generic PTY, LSP, and subprocess Code Runtime suites pin their provider-neutral readiness, cross-namespace `processId`, binding bridge, descriptor isolation, hostile traffic, and worker/descendant cleanup behavior.
-
-A credential-gated Loader composition creates real E2B sandboxes and exercises FS-to-Bash and Bash-to-FS visibility, real-directory runtime-state setup, process-publication rollback, byte-split UTF-8 command output, bounded raw spill and inherited-output draining, hostile command and PTY login-profile isolation, default-secret scrubbing, stale-interrupt identity, and process-tree cleanup, parent-swap-safe bounded LSP source reads, Code Runtime host bindings, descriptor-isolated output accounting, descendant-held pipe cleanup, wall timeout, abort, runner cleanup, host-workspace isolation, and final sandbox deletion. The same composition runs through source imports and built package exports.
-
-## Alternatives considered
-
-**A separate E2B sandbox per capability or tool** — rejected because file and command operations would not share identity or state, defeating the coding-agent use case and multiplying lifecycle ownership.
-
-**Run the entire harness process inside E2B** — rejected because it changes deployment, credential flow, model transport, session durability, plugin loading, and supervision at once. Those questions are independent of proving the provider seams.
-
-**Put every E2B operation in the shared owner package** — rejected because lifecycle identity is the owner's only concern. Filesystem and subprocess retain separate provider contracts, tests, and consumers; the owner exposes one shared SDK handle without becoming a capability grab bag.
-
-**Implement filesystem operations through shell commands only** — rejected because that bypasses `ctx.fs` identity, structured errors, version guards, streaming reads, and atomic mutation semantics already consumed by the file tools.
-
-**Keep E2B-specific PTY, LSP, and Code Runtime packages** — rejected because their domain behavior does not vary with E2B. They were shallow adapters that duplicated existing consumers to replace filesystem and process operations; moving those operations behind the fundamental seams gives every provider one implementation of readiness, protocol, binding, and presentation behavior.
-
-**Call E2B Filesystem, Commands, or PTY APIs directly from higher capabilities** — rejected because it bypasses the `ctx.fs` and `ctx.subprocess` contracts, duplicates execution-world policy in each consumer, and forks model-facing behavior. The subprocess seam includes the irreducible terminal primitive because ordinary pipes cannot supply foreground groups or whole-session cleanup.
-
-**Add a generic distributed-runtime abstraction first** — rejected because the existing capability seams already carry the required contracts. A new cross-cutting interface would speculate about persistence, synchronization, and reconnect semantics beyond the POC.
-
-**Restore live capability handles after `sandboxId` reconnect** — rejected because remote identity alone cannot reconstruct host callbacks, pending promises, authority, protocol state, or output cursors. Claiming continuity would make stale remote processes appear managed when they are not.
-
-## Consequences
-
-The three-package composition demonstrates that filesystem and subprocess are the sufficient provider seams for moving an agent's mutable coding world off-host without changing the loop, higher capability implementations, or model-facing tool packages. Fixes to Bash, PTY, LSP, and Code Runtime remain provider-neutral. `sandboxId` plus pause/leave permits manual remote-file retention for experiments, while kill remains the demo's cleanup policy.
-
-The adapters are not interchangeable with local backends for every consumer: remote startup cannot synchronously expose a PID, E2B retains the complete base64 command transport in SDK memory, exact terminal stdin-wait inspection is unavailable, E2B supplies no independent signal fact, and reconnect cannot restore handles or protocol state. The adapter reports only its own requested TERM/KILL as signals and preserves every unrequested SDK exit as an exit code. Remote process/spill artifacts accumulate in a retained sandbox, Code programs share a JavaScript realm with Node worker internals, and a process that deliberately escapes a managed process group or terminal session does not become reconnectable or owned. These gaps remain documented POC constraints rather than compatibility shims or new cross-cutting abstractions.
diff --git a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md b/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
deleted file mode 100644
index 729a10ec7e..0000000000
--- a/.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.zh.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# Agent Note: 共享 E2B 远程运行时 POC
-
-Status: implemented
-
-[English](2026-07-27-e2b-remote-runtime-poc.md) | 中文
-
-## 问题
-
-远程 coding agent（智能体）后端只有在文件系统操作、一次性命令、持久终端、语言服务器和模型编写的程序观察到同一个一致环境时才有用。若在各工具上分别接入 E2B，这些功能可能访问不同的沙箱；即使 cwd 字符串相同，保留宿主 PTY、LSP 或 worker 后端也会让状态分散在不同机器上。
-
-把完整 harness 迁入远程 VM 可以统一这些状态，但也会把提供方实验与插件加载、凭据、模型传输、agent／会话持久性、监管和部署耦合在一起。这个 POC 只需测试现有功能边界，不应把这些彼此独立的问题纳入范围。
-
-## 决策
-
-E2B 集成是一个选择性启用的提供方组合 POC。它的 3 个 E2B 专用包（package）集中位于 `packages/e2b/` 下：
-
-- `@deepseek-ai/dsh-e2b` 创建或重新连接一个安全的 E2B 沙箱，创建其工作目录与私有运行时目录，并拥有 kill/pause/leave 资源释放操作。
-- `@deepseek-ai/dsh-fs-e2b` 在该沙箱的 Filesystem API 之上实现 `ctx.fs`。
-- `@deepseek-ai/dsh-subprocess-e2b` 在 E2B Commands、字节 PTY 和远程 Linux 进程组之上实现 `ctx.subprocess`。
-
-上层功能使用提供方无关的实现。`dsh-bash-local` 把命令机制委托给 `ctx.subprocess`；`dsh-pty-local` 把终端分配与信号发送委托给 `ctx.subprocess.spawnTerminal()`；`dsh-lsp-local` 通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动；`dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化 runner，再通过 `ctx.subprocess` 启动它。这些通用接口与消费方由[可移植执行环境决策](../architecture/2026-07-28-portable-execution-world-consumers.md)负责定义。
-
-E2B 所有者是沙箱身份的唯一真源。其两个适配器绝不创建私有沙箱，因此文件系统工具、Bash、交互式 shell、语言服务器和代码 worker 会共享一个远程 cwd、进程命名空间和适配器私有目录，同时保留现有功能接口、通用实现、面向模型的工具与 agent loop（智能体循环）。
-
-## POC 边界
-
-E2B 拥有可变文件系统、受管命令与 Bash 进程、终端分配与终端会话进程组、语言服务器进程及源码读取、Code Runtime launcher、controller 和 worker，以及 `.dsh-e2b` 下的适配器私有文件。
-
-宿主拥有 Cordis 与插件对象、agent loop、agent／会话／goal 状态、会话日志及持久化、LLM（大语言模型）调用、提示词与工具、权限决策、skill（技能）、subagent 编排、PTY 缓冲与就绪状态、LSP JSON-RPC id／队列／协议状态、Code Runtime 类型剥离／输出计量／绑定分发，以及 E2B SDK／网络编排。该 overlay 不会上传、挂载或同步宿主工作区；拼写相同的 cwd 字符串分别指向彼此独立的宿主与远程目录。
-
-基础适配器承载基底专用机制。适配器内部的 E2B 命令与 PTY 登录 shell 使用位于根目录下、全新随机生成的 `HOME`；在用户 profile 脚本运行前，`dsh-subprocess-e2b` 还会为它们设置已清理凭据名称的空值覆盖。该子进程适配器消费 E2B 的字节 PTY 回调，以 ASCII/base64 跨越已解码的 SDK 回调传输环境快照与命令字节，并使用一个取消控制器与一个可重试的进程组清理事务，后者只有在证明完全停稳后才报告成功。`dsh-fs-e2b` 通过无依赖辅助程序执行有界源码读取，该程序会在规范化目标下逐级遍历不跟随符号链接的目录描述符。通用 Code Runtime 以经过验证、由换行符分隔的 UTF-8 JSON 承载 controller/worker 协议，并在继承的管道排空前终止提供方拥有的进程组。通用 LSP 通过命令管道使用字节保真的 UTF-8 JSON。
-
-保留沙箱只会保存远程文件与未受管的远程状态。重新连接不会重建宿主 PTY 会话、缓冲、进程句柄、LSP 连接或请求、代码 worker、绑定调用、定时器、输出游标或锁。受管进程组会在所属提供方 dispose（资源释放）时终止并等待退出，之后共享所有者才会暂停、脱离或终止沙箱。
-
-本 POC 没有会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录、工作区同步、持久远程句柄或完整 harness 执行。
-
-## 验证
-
-聚焦包测试套件固定所有者生命周期清理、文件系统路径／containment／有界描述符读取与提交元数据、子进程可执行文件查找／进程组／发布回滚、终端字节 I/O／信号身份／默认环境清理／会话清理、输出上限、中止顺序、等待完全停稳的资源释放，以及包自有不变式注册。通用 PTY、LSP 与子进程 Code Runtime 测试套件固定其提供方无关的就绪判定、跨命名空间 `processId`、绑定桥接、描述符隔离、恶意通信，以及 worker／后代进程清理行为。
-
-凭据门控的 Loader 组合会创建真实 E2B 沙箱，并演练 FS-to-Bash 与 Bash-to-FS 可见性、真实目录形式的运行时状态设置、进程发布回滚、按字节切分的 UTF-8 命令输出、有界原始 spill 与继承输出排空、恶意命令与 PTY 登录 profile 隔离、默认秘密清理、陈旧中断身份与进程树清理、可抵御父目录替换的有界 LSP 源码读取、Code Runtime 宿主绑定、描述符隔离的输出记账、后代进程所持管道的清理、墙钟超时、中止、runner 清理、宿主工作区隔离，以及最终删除沙箱。同一组合分别通过源代码导入与已构建包导出运行。
-
-## 曾考虑的替代方案
-
-**每项功能或每个工具使用独立的 E2B 沙箱。** 不予采纳，因为文件操作和命令操作将无法共享身份或状态，既违背 coding agent 用例，也会增加生命周期所有者的数量。
-
-**在 E2B 内运行完整 harness 进程。** 不予采纳，因为这会同时改变部署、凭据流、模型传输、会话持久性、插件加载和监管方式。要证明提供方 seam，并不需要同时回答这些彼此独立的问题。
-
-**把所有 E2B 操作放入共享所有者包。** 不予采纳，因为生命周期身份是该所有者唯一负责的事项。文件系统与进程管理各自保留独立的提供方契约、测试和消费方；所有者只公开一个共享 SDK 句柄，不会因此包揽各类功能。
-
-**仅通过 shell 命令实现文件系统操作。** 不予采纳，因为这会绕过文件工具已经使用的 `ctx.fs` 身份、结构化错误、版本防护、流式读取和原子变更语义。
-
-**保留 E2B 专用的 PTY、LSP 与 Code Runtime 包。** 不予采纳，因为它们的领域行为不会随 E2B 改变。这些浅层适配器为了替换文件系统与进程操作而重复现有消费方；把这些操作移到基础 seam 之后，可让所有提供方共享同一套就绪判定、协议、绑定与呈现行为实现。
-
-**从上层功能直接调用 E2B Filesystem、Commands 或 PTY API。** 不予采纳，因为这会绕过 `ctx.fs` 与 `ctx.subprocess` 契约，在每个消费方中重复执行环境策略，并使面向模型的行为产生分叉。进程管理 seam 纳入不可约简的终端原语，因为普通管道无法提供前台进程组或全会话清理。
-
-**先添加通用分布式运行时抽象。** 不予采纳，因为现有功能 seam 已承载所需契约。新的跨领域接口会预先假定 POC 范围之外的持久化、同步与重连语义。
-
-**在 `sandboxId` 重连后恢复活动功能句柄。** 不予采纳，因为只有远程身份，无法重建宿主回调、待处理 promise、权限、协议状态或输出游标。若声称保持连续性，就会让陈旧的远程进程看似仍受管理，实际并非如此。
-
-## 后果
-
-这个由 3 个包组成的组合证明，文件系统与进程管理这两个提供方 seam 足以把 agent 的可变 coding 环境移出宿主，而无需改变循环、上层功能实现或面向模型的工具包。Bash、PTY、LSP 与 Code Runtime 的修复仍与提供方无关。`sandboxId` 与 `pause`／`leave` 允许实验手动保留远程文件，演示仍以 `kill` 作为清理策略。
-
-这些适配器并不能对所有消费方与本地后端互换：远程启动无法同步公开 PID，E2B 会在 SDK 内存中保留完整的 base64 命令传输，无法精确检查终端 stdin 等待状态，E2B 不提供独立的信号事实，重新连接也无法恢复句柄或协议状态。适配器只会把自己请求的 TERM/KILL 报告为信号，其他未请求的 SDK 退出都保留为退出码。保留沙箱后会累积远程进程／spill 产物，模型程序与 Node worker 内部机制共享一个 JavaScript realm，有意逃离受管理进程组或终端会话的进程也不会因此变得可重新连接或由该组合管理。这些缺口作为 POC 约束明确记录，而不会引入兼容垫片或新的跨领域抽象。
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index b4acfd1e5a..856a26ed78 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -35,9 +35,19 @@ let terminalId: Awaited<ReturnType<typeof ctx.pty.spawn>>['sessionId'] | undefin
 try {
   const sandbox = await ctx.e2b.getSandbox()
   const fromFs = await ctx.fs.resolve('from-fs.txt')
-  await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
+  const written = await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
+  const reread = await ctx.fs.stat(fromFs)
+  if (reread?.version !== written.version) {
+    throw new Error(`E2B rename did not preserve version metadata: ${JSON.stringify({ written, reread })}`)
+  }
+  await ctx.fs.editText(
+    fromFs,
+    { oldString: 'written-by-fs', newString: 'written-by-fs-versioned', replaceAll: false },
+    { version: reread.version },
+  )
+  const fsVersionGuard = true
   const bashRead = await ctx.bash.run(ctx.bash.resolve({ command: 'cat from-fs.txt' }))
-  if (bashRead.exitCode !== 0 || bashRead.stdout.text !== 'written-by-fs\n') {
+  if (bashRead.exitCode !== 0 || bashRead.stdout.text !== 'written-by-fs-versioned\n') {
     throw new Error(`E2B Bash could not read the FS write: ${JSON.stringify(bashRead)}`)
   }
 
@@ -183,44 +193,8 @@ try {
     workspaceRoot: process.cwd(),
   })
 
-  const swappedParentPath = posix.join(process.cwd(), 'swapped-parent')
-  const swappedSourcePath = posix.join(swappedParentPath, 'source.ts')
-  const swappedOutsidePath = '/tmp/dsh-e2b-lsp-outside'
-  await sandbox.commands.run(
-    `mkdir -p -- ${quoteE2BShellArg(swappedParentPath)} ${quoteE2BShellArg(swappedOutsidePath)} && printf 'const safe = true\\n' > ${quoteE2BShellArg(swappedSourcePath)} && printf 'const outside = true\\n' > ${quoteE2BShellArg(posix.join(swappedOutsidePath, 'source.ts'))}`,
-  )
-  const remoteCommands = sandbox.commands as unknown as {
-    run(command: string, options?: unknown): Promise<{ exitCode: number; stdout: string; stderr: string }>
-  }
-  const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
-  let containmentFaultInjected = false
-  remoteCommands.run = async (command, options) => {
-    if (!containmentFaultInjected && command.includes('dsh-e2b-bounded-reader') && command.includes('swapped-parent/source.ts')) {
-      containmentFaultInjected = true
-      await runRemoteCommand(
-        `rm -rf -- ${quoteE2BShellArg(swappedParentPath)} && ln -s -- ${quoteE2BShellArg(swappedOutsidePath)} ${quoteE2BShellArg(swappedParentPath)}`,
-      )
-    }
-    return await runRemoteCommand(command, options)
-  }
-  let lspContainment = false
-  try {
-    await ctx.lsp.query({
-      operation: 'hover',
-      filePath: 'swapped-parent/source.ts',
-      position: { line: 0, character: 1 },
-      workspaceRoot: process.cwd(),
-    })
-  } catch (error: unknown) {
-    lspContainment = containmentFaultInjected && String(error).includes('opened safely')
-    if (!lspContainment) throw error
-  } finally {
-    remoteCommands.run = runRemoteCommand
-  }
-  if (!lspContainment) throw new Error('E2B LSP source swap was not rejected')
-
   const oversizedSourcePath = posix.join(process.cwd(), 'oversized-source.ts')
-  await sandbox.commands.run(`head -c 4000001 /dev/zero > ${quoteE2BShellArg(oversizedSourcePath)}`)
+  await sandbox.commands.run(`head -c 4000001 /dev/zero | tr '\\0' x > ${quoteE2BShellArg(oversizedSourcePath)}`)
   let lspDocumentBound = false
   try {
     await ctx.lsp.query({
@@ -235,6 +209,10 @@ try {
   }
   if (!lspDocumentBound) throw new Error('E2B LSP accepted an oversized remote source')
 
+  const remoteCommands = sandbox.commands as unknown as {
+    run(command: string, options?: unknown): Promise<{ exitCode: number; stdout: string; stderr: string }>
+  }
+  const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
   const terminal = await ctx.pty.spawn(owner, { type: 'shell' })
   terminalId = terminal.sessionId
   const terminalEcho = await ctx.pty.startSend(owner, terminal.sessionId, {
@@ -429,6 +407,7 @@ try {
   process.stdout.write(`${JSON.stringify({
     sandboxId: await ctx.e2b.sandboxId,
     bashRead: bashRead.stdout.text,
+    fsVersionGuard,
     fsRead,
     explicitEnvironment,
     splitUtf8Output,
@@ -437,7 +416,6 @@ try {
     spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
     definition,
-    lspContainment,
     lspDocumentBound,
     terminal: {
       motd: terminal.motd,
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 9b56a3ef55..2b6a8efb69 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: ef2e5ef49056e6688630e785a61c01fa53febbb1
-README.zh.md: d76b05f9b60bc471c1793decd1def1d15615c852
+README.md: cb733ba00d21070773ff9b381e4a72d9d3b9a8df
+README.zh.md: 29f8e58a0cdc59098cf8d74120cb360d11cfbcb3
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index ef2e5ef490..cb733ba00d 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -12,4 +12,4 @@ An experimental provider-composition POC that places one filesystem/process exec
 
 The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), [`dsh-lsp-local`](../lsp/lsp-local/README.md), and [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox.
 
-This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [shared-runtime decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) owns the POC boundary; the [portable-consumer decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns the generic composition.
+This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [portable execution-world decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns both the generic composition and this POC boundary.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index d76b05f9b6..29f8e58a0c 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -12,4 +12,4 @@
 
 现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md)、[`dsh-lsp-local`](../lsp/lsp-local/README.md) 及 [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。
 
-该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[共享运行时决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)界定 POC 边界；[可移植消费方决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)界定通用组合。
+该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[可移植执行世界决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)同时界定通用组合和此 POC 边界。
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index f9fcbfae8a..6600f1046d 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -160,7 +160,8 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     expect(stderr).toBe('')
     const output = JSON.parse(stdout) as Record<string, unknown>
     expect(output).toMatchObject({
-      bashRead: 'written-by-fs\n',
+      bashRead: 'written-by-fs-versioned\n',
+      fsVersionGuard: true,
       fsRead: 'written-by-bash\n',
       explicitEnvironment: true,
       splitUtf8Output: '你好',
@@ -184,7 +185,6 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         kind: 'locations',
         locations: [{ range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } } }],
       },
-      lspContainment: true,
       lspDocumentBound: true,
       terminal: {
         echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 87f1c7c69b..3f756bf2f9 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: bb92b5785383e9703a382fddefcd1cff9b2644cb
-README.zh.md: 57ebfdbb92799660e74078fcd0affcc8d5bc120a
+README.md: 6827e16e9c45532590ee1aa986c18a353d175fdc
+README.zh.md: 21b067829ea95c4581d7e89f3d225f9c90e630ef
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index bb92b57853..6827e16e9c 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -6,10 +6,9 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 
 ## Behavior
 
-- **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; `realpath -m` supplies canonical target identity without requiring the final file to exist. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
+- **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; GNU `realpath -mz` supplies canonical target identity without requiring the final file to exist, and ASCII/base64 plus strict NUL framing preserves newline and multibyte paths across the decoded SDK transport. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam; listings reuse returned metadata and resolve symbolic-link entries sequentially. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
 - **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
-- **Stable bounded reads** — a dependency-free Node helper walks directory descriptors with no-follow opens and reads one held regular-file descriptor through the byte cap. Generic LSP queries therefore reject parent swaps, non-files, invalid UTF-8, and growth past the configured document limit before server startup.
 - **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before rename. The signal is not forwarded into the rename RPC, so cancellation cannot interrupt the atomic commit; a successful rename is the commit point.
 
@@ -27,5 +26,6 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **No host synchronization** — an empty E2B cwd stays empty until a tool, command, template, or external process populates it; local files are neither uploaded nor reflected back.
 - **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
+- **Reads reopen canonical targets by path** — a concurrent remote path replacement between resolution and stream opening is not fenced by a stable file handle; no observed product defect justifies a provider-specific bounded-read protocol in this POC.
 - **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
-- **Custom templates must support the used Linux, Node, procfs, and envd features** — `realpath`, `chmod`, `mv`, same-filesystem POSIX rename, streaming reads, file metadata extended attributes, `/proc/self/fd`, and no-follow descriptor opens are required; unsupported templates fail rather than degrade silently.
+- **Custom templates must support the used Linux/GNU and E2B filesystem features** — `realpath -mz`, `base64 -w0`, `chmod`, same-filesystem rename, streaming reads, and file metadata extended attributes are required; unsupported templates fail rather than degrade silently.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 57ebfdbb92..21b067829e 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -6,10 +6,9 @@
 
 ## 行为
 
-- **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；`realpath -m` 提供规范化目标身份，且不要求最终文件存在。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
+- **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；GNU `realpath -mz` 提供规范化目标身份，且不要求最终文件存在；ASCII/base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam；目录列表会复用已返回的元数据，并依次解析符号链接条目。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
 - **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
-- **稳定的有界读取**：一个零依赖 Node 辅助程序会以不跟随链接的方式逐级打开目录描述符，并通过一个持续持有的常规文件描述符读取至字节上限。因此，通用 LSP 查询会在服务器启动前拒绝父目录交换、非文件、无效 UTF-8，以及增长后超出所配置文档上限的文件。
 - **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在 rename 前立即检查。信号不会传入 rename RPC，因此取消无法中断原子提交；成功 rename 是提交点。
 
@@ -27,5 +26,6 @@
 
 - **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令、模板或外部进程填充它；本地文件既不会上传，也不会同步回本地。
 - **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
+- **读取会按路径重新打开规范化目标**：在解析与打开流之间若并发替换远程路径，该操作没有稳定文件句柄提供围栏；在该 POC 中，没有已观察到的产品缺陷能够证明提供方专用的有界读取协议值得引入。
 - **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
-- **自定义模板必须支持所用的 Linux、Node、procfs 与 envd 功能**：必须支持 `realpath`、`chmod`、`mv`、同一文件系统内的 POSIX rename、流式读取、文件元数据扩展属性、`/proc/self/fd` 和不跟随链接的描述符打开操作；不支持的模板会失败，而不会静默降级。
+- **自定义模板必须支持所用的 Linux/GNU 与 E2B 文件系统功能**：必须支持 `realpath -mz`、`base64 -w0`、`chmod`、同一文件系统内的 rename、流式读取和文件元数据扩展属性；不支持的模板会失败，而不会静默降级。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 7c81791d55..3b0c835d8c 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -26,17 +26,10 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { EntryInfo, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { BOUNDED_READER_SOURCE } from './source-reader.ts'
 
 const VERSION_METADATA_KEY = 'dsh-version'
 const BINARY_SAMPLE_BYTES = 8192
-
-type BoundedReadResponse =
-  | { kind: 'ok'; data: string }
-  | { kind: 'not-file' }
-  | { kind: 'oversize'; size: number }
-  | { kind: 'grew' }
-  | { kind: 'open-error'; message: string }
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
 
 function assertNotAborted(signal: AbortSignal | undefined, operation: string): void {
   if (signal?.aborted === true) throw new FsError(`${operation} aborted`, 'FS_ABORTED')
@@ -68,6 +61,27 @@ function decodeText(bytes: Uint8Array, displayPath: string, binarySampleBytes: n
   }
 }
 
+function decodeCanonicalPath(encoded: string): string {
+  if (encoded.length === 0 || !BASE64.test(encoded)) {
+    throw new Error('fs-e2b: canonical path transport returned invalid base64')
+  }
+  const framed = Buffer.from(encoded, 'base64')
+  if (framed.toString('base64') !== encoded
+    || framed.length < 2
+    || framed.at(-1) !== 0
+    || framed.subarray(0, -1).includes(0)) {
+    throw new Error('fs-e2b: canonical path transport returned invalid NUL framing')
+  }
+  let path: string
+  try {
+    path = new TextDecoder('utf-8', { fatal: true }).decode(framed.subarray(0, -1))
+  } catch (error: unknown) {
+    throw new Error('fs-e2b: canonical path is not valid UTF-8', { cause: error })
+  }
+  if (!posix.isAbsolute(path)) throw new Error('fs-e2b: canonical path is not absolute')
+  return path
+}
+
 function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
   return signal === undefined ? {} : { signal }
 }
@@ -213,69 +227,6 @@ export class E2BFileSystem extends FileSystem {
     }
   }
 
-  override async readTextBounded(target: FsTarget, maxBytes: number, signal?: AbortSignal): Promise<string> {
-    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
-      throw new Error('bounded read maxBytes must be a positive safe integer')
-    }
-    assertNotAborted(signal, 'read')
-    const sandbox = await this.ctx.e2b.getSandbox()
-    try {
-      const node = await sandbox.commands.run('command -v -- node', commandOpts(signal))
-      const executable = node.stdout.trim()
-      if (!posix.isAbsolute(executable) || executable.includes('\n')) {
-        throw new Error('fs-e2b: bounded reader requires one absolute Node executable')
-      }
-      const command = [
-        quoteE2BShellArg(executable),
-        '--input-type=commonjs',
-        '-e',
-        quoteE2BShellArg(BOUNDED_READER_SOURCE),
-        quoteE2BShellArg(this.processPath(target)),
-        String(maxBytes),
-      ].join(' ')
-      const result = await sandbox.commands.run(command, commandOpts(signal))
-      assertNotAborted(signal, 'read')
-      const response = this.parseBoundedRead(result.stdout, target)
-      if (response.kind === 'not-file') {
-        throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
-      }
-      if (response.kind === 'oversize' && Number.isSafeInteger(response.size)) {
-        throw new FsError(
-          `cannot read "${target.displayPath}": ${response.size} bytes exceeds the ${maxBytes}-byte limit`,
-          'FS_IO_ERROR',
-        )
-      }
-      if (response.kind === 'grew') {
-        throw new FsError(
-          `cannot read "${target.displayPath}": file grew past the ${maxBytes}-byte limit while reading`,
-          'FS_IO_ERROR',
-        )
-      }
-      if (response.kind === 'open-error' && typeof response.message === 'string') {
-        if (/ENOENT|no such file/i.test(response.message)) {
-          throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
-        }
-        if (/EACCES|EPERM|permission denied|operation not permitted/i.test(response.message)) {
-          throw new FsError(`cannot read "${target.displayPath}": permission denied`, 'FS_PERMISSION_DENIED')
-        }
-        throw new FsError(
-          `cannot read "${target.displayPath}" safely: ${response.message}`,
-          'FS_IO_ERROR',
-        )
-      }
-      if (response.kind !== 'ok' || typeof response.data !== 'string') {
-        throw new FsError(`cannot read "${target.displayPath}": bounded reader returned an invalid response`, 'FS_IO_ERROR')
-      }
-      const bytes = Buffer.from(response.data, 'base64')
-      if (bytes.toString('base64') !== response.data || bytes.length > maxBytes) {
-        throw new FsError(`cannot read "${target.displayPath}": bounded reader returned invalid bytes`, 'FS_IO_ERROR')
-      }
-      return decodeText(bytes, target.displayPath, BINARY_SAMPLE_BYTES)
-    } catch (error: unknown) {
-      throw mapError(error, 'read', target.displayPath, signal)
-    }
-  }
-
   override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
     const sandbox = await this.ctx.e2b.getSandbox()
     await this.requireRegular(target, signal)
@@ -339,18 +290,23 @@ export class E2BFileSystem extends FileSystem {
     try {
       const sandbox = await this.ctx.e2b.getSandbox()
       const listed = await sandbox.files.list(String(target.targetKey), { depth: 1, ...signalOpts(signal) })
-      const entries = await Promise.all(listed.map(async (entry): Promise<FsDirEntry> => {
+      const entries: FsDirEntry[] = []
+      for (const entry of listed) {
         const displayPath = posix.join(target.displayPath, entry.name)
-        const canonical = await this.canonicalPath(sandbox, entry.path, signal)
-        const resolved = await this.probe(canonical, displayPath, signal)
-        return {
+        const canonical = entry.symlinkTarget === undefined
+          ? entry.path
+          : await this.canonicalPath(sandbox, entry.path, signal)
+        const resolved = entry.symlinkTarget === undefined
+          ? entry
+          : await this.probe(canonical, displayPath, signal)
+        entries.push({
           name: entry.name,
           type: resolved === undefined ? 'other' : entryType(resolved),
           target: { targetKey: FsTargetKey(canonical), displayPath },
           ...(resolved !== undefined ? { version: entryVersion(resolved) } : {}),
           ...(resolved?.type === FileType.FILE ? { size: resolved.size } : {}),
-        }
-      }))
+        })
+      }
       return entries.sort((left, right) => left.name.localeCompare(right.name))
     } catch (error: unknown) {
       throw mapError(error, 'list', target.displayPath, signal)
@@ -420,26 +376,17 @@ export class E2BFileSystem extends FileSystem {
 
   private async canonicalPath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
     try {
-      const result = await sandbox.commands.run(`realpath -m -- ${quoteE2BShellArg(path)}`, commandOpts(signal))
-      return result.stdout.replace(/\n$/, '')
+      const result = await sandbox.commands.run(
+        `set -o pipefail; realpath -mz -- ${quoteE2BShellArg(path)} | base64 -w0`,
+        commandOpts(signal),
+      )
+      return decodeCanonicalPath(result.stdout)
     } catch (error: unknown) {
       if (error instanceof CommandExitError) throw new Error(error.stderr || error.message, { cause: error })
       throw error
     }
   }
 
-  private parseBoundedRead(stdout: string, target: FsTarget): BoundedReadResponse {
-    try {
-      return JSON.parse(stdout) as BoundedReadResponse
-    } catch (error: unknown) {
-      throw new FsError(
-        `cannot read "${target.displayPath}": bounded reader returned invalid JSON`,
-        'FS_IO_ERROR',
-        { cause: error },
-      )
-    }
-  }
-
   private async probe(path: string, displayPath: string, signal?: AbortSignal): Promise<EntryInfo | undefined> {
     assertNotAborted(signal, 'stat')
     try {
diff --git a/packages/e2b/fs-e2b/src/source-reader.ts b/packages/e2b/fs-e2b/src/source-reader.ts
deleted file mode 100644
index 9cb522ecbb..0000000000
--- a/packages/e2b/fs-e2b/src/source-reader.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-/** Dependency-free stable-handle bounded reader installed inside E2B. */
-export const BOUNDED_READER_SOURCE = String.raw`
-/* dsh-e2b-bounded-reader */
-const fs = require('node:fs')
-const target = process.argv[1]
-const maxBytes = Number(process.argv[2])
-const directoryFlags = fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK
-const fileFlags = fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK
-let directory
-let descriptor
-let response
-
-const openChild = (parent, component, flags) => fs.openSync('/proc/self/fd/' + parent + '/' + component, flags)
-const invalidComponent = component => component === '' || component === '.' || component === '..'
-
-try {
-  if (typeof target !== 'string' || !target.startsWith('/') || !Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
-    throw new Error('bounded reader requires an absolute target and positive byte limit')
-  }
-  const components = target === '/' ? [] : target.slice(1).split('/')
-  if (components.length === 0 || components.some(invalidComponent)) {
-    throw new Error('bounded reader received a non-canonical file path')
-  }
-
-  directory = fs.openSync('/', directoryFlags)
-  for (const component of components.slice(0, -1)) {
-    const child = openChild(directory, component, directoryFlags)
-    fs.closeSync(directory)
-    directory = child
-  }
-  descriptor = openChild(directory, components.at(-1), fileFlags)
-
-  const info = fs.fstatSync(descriptor)
-  if (!info.isFile()) response = { kind: 'not-file' }
-  else if (info.size > maxBytes) response = { kind: 'oversize', size: info.size }
-  else {
-    const chunks = []
-    let total = 0
-    while (total <= maxBytes) {
-      const chunk = Buffer.allocUnsafe(Math.min(65536, maxBytes - total + 1))
-      const bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)
-      if (bytesRead === 0) break
-      chunks.push(chunk.subarray(0, bytesRead))
-      total += bytesRead
-    }
-    response = total > maxBytes
-      ? { kind: 'grew' }
-      : { kind: 'ok', data: Buffer.concat(chunks, total).toString('base64') }
-  }
-} catch (error) {
-  response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
-} finally {
-  for (const openDescriptor of [descriptor, directory]) {
-    if (openDescriptor === undefined) continue
-    try {
-      fs.closeSync(openDescriptor)
-    } catch (error) {
-      response = { kind: 'open-error', message: error instanceof Error ? error.message : String(error) }
-    }
-  }
-}
-process.stdout.write(JSON.stringify(response))
-`
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 23835e9967..91f9a278fd 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -49,10 +49,7 @@ class FakeRemote {
   nextReadError: unknown
   nextRenameError: unknown
   nextRemoveError: unknown
-  boundedOutput: string | undefined
-  boundedError: unknown
-  nodeExecutable = '/usr/bin/node\n'
-  abortAfterBoundedCommand: AbortController | undefined
+  canonicalOutput: string | undefined
   abortAfterRename: AbortController | undefined
   disappearOnInfo = new Set<string>()
   private clock = 1
@@ -239,18 +236,18 @@ class FakeRemote {
           this.nextCommandError = undefined
           throw error
         }
-        if (command.startsWith('realpath -m -- ')) {
-          const input = command.slice('realpath -m -- '.length).slice(1, -1)
+        const realpathPrefix = 'set -o pipefail; realpath -mz -- '
+        const realpathSuffix = ' | base64 -w0'
+        if (command.startsWith(realpathPrefix) && command.endsWith(realpathSuffix)) {
+          const quoted = command.slice(realpathPrefix.length, -realpathSuffix.length)
+          const input = quoted.slice(1, -1).replaceAll(String.raw`'"'"'`, '\'')
           const node = this.nodes.get(input)
-          return { exitCode: 0, stdout: `${node?.symlinkTarget ?? input}\n`, stderr: '' }
-        }
-        if (command === 'command -v -- node') {
-          return { exitCode: 0, stdout: this.nodeExecutable, stderr: '' }
-        }
-        if (command.includes('dsh-e2b-bounded-reader')) {
-          if (this.boundedError !== undefined) throw this.boundedError
-          this.abortAfterBoundedCommand?.abort('after bounded read')
-          return { exitCode: 0, stdout: this.boundedOutput ?? '{"kind":"ok","data":""}', stderr: '' }
+          const canonical = `${node?.symlinkTarget ?? input}\0`
+          return {
+            exitCode: 0,
+            stdout: this.canonicalOutput ?? Buffer.from(canonical).toString('base64'),
+            stderr: '',
+          }
         }
         const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
         if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
@@ -340,6 +337,28 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
       .toThrow('expected an absolute process path')
   })
 
+  it('preserves newline and multibyte canonical paths through strict ASCII framing', async () => {
+    const remote = new FakeRemote()
+    const path = '/workspace/你好\nfile.ts'
+    remote.file(path, 'text')
+    const { fs } = await setup(remote)
+
+    await expect(fs.resolve(path)).resolves.toEqual({ targetKey: path, displayPath: path })
+  })
+
+  it.each([
+    ['invalid base64', '!!!!'],
+    ['missing terminator', Buffer.from('/workspace/file').toString('base64')],
+    ['multiple records', Buffer.from('/workspace/file\0/other\0').toString('base64')],
+    ['invalid UTF-8', Buffer.from([47, 0xff, 0]).toString('base64')],
+    ['relative path', Buffer.from('workspace/file\0').toString('base64')],
+  ])('rejects %s from canonical path transport', async (_label, output) => {
+    const remote = new FakeRemote()
+    remote.canonicalOutput = output
+    const { fs } = await setup(remote)
+    await expectCode(fs.resolve('file'), 'FS_IO_ERROR')
+  })
+
   it('reads whole and streamed UTF-8 across chunk boundaries', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/text.txt', 'A€B')
@@ -424,78 +443,6 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     await expectCode(fs.readText(await fs.resolve('a')), 'FS_ABORTED')
   })
 
-  it('performs stable bounded reads through the remote no-follow reader', async () => {
-    const remote = new FakeRemote()
-    remote.file('/workspace/a', 'unused')
-    const { fs } = await setup(remote)
-    const target = await fs.resolve('a')
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('hello 你好').toString('base64') })
-    await expect(fs.readTextBounded(target, 64)).resolves.toBe('hello 你好')
-    expect(remote.commands.some(command => command.includes('dsh-e2b-bounded-reader'))).toBe(true)
-
-    await expect(fs.readTextBounded(target, 0)).rejects.toThrow('positive safe integer')
-    await expect(fs.readTextBounded(target, 1.5)).rejects.toThrow('positive safe integer')
-    await expect(fs.readTextBounded(target, 64, AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
-  })
-
-  it('maps bounded-reader file, size, and open failures', async () => {
-    const remote = new FakeRemote()
-    remote.file('/workspace/a', 'unused')
-    const { fs } = await setup(remote)
-    const target = await fs.resolve('a')
-    const cases: Array<[unknown, string]> = [
-      [{ kind: 'not-file' }, 'FS_NOT_REGULAR_FILE'],
-      [{ kind: 'oversize', size: 65 }, 'FS_IO_ERROR'],
-      [{ kind: 'grew' }, 'FS_IO_ERROR'],
-      [{ kind: 'open-error', message: 'ENOENT: no such file' }, 'FS_NOT_FOUND'],
-      [{ kind: 'open-error', message: 'EACCES: permission denied' }, 'FS_PERMISSION_DENIED'],
-      [{ kind: 'open-error', message: 'ELOOP: symbolic link' }, 'FS_IO_ERROR'],
-      [{ kind: 'oversize', size: 'large' }, 'FS_IO_ERROR'],
-      [{ kind: 'open-error', message: 7 }, 'FS_IO_ERROR'],
-      [{ kind: 'unknown' }, 'FS_IO_ERROR'],
-    ]
-    for (const [response, code] of cases) {
-      remote.boundedOutput = JSON.stringify(response)
-      await expectCode(fs.readTextBounded(target, 64), code)
-    }
-  })
-
-  it('rejects malformed bounded-reader transports and bytes', async () => {
-    const remote = new FakeRemote()
-    remote.file('/workspace/a', 'unused')
-    const { fs } = await setup(remote)
-    const target = await fs.resolve('a')
-
-    remote.boundedOutput = 'not-json'
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: '!!!!' })
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('12345').toString('base64') })
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from([0]).toString('base64') })
-    await expectCode(fs.readTextBounded(target, 4), 'FS_NOT_TEXT')
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from([0xff]).toString('base64') })
-    await expectCode(fs.readTextBounded(target, 4), 'FS_NOT_TEXT')
-
-    remote.nodeExecutable = 'node\n'
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-    remote.nodeExecutable = '/usr/bin/node\n/other\n'
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-    remote.nodeExecutable = '/usr/bin/node\n'
-    remote.boundedError = new Error('reader transport failed')
-    await expectCode(fs.readTextBounded(target, 4), 'FS_IO_ERROR')
-  })
-
-  it('does not turn a post-read abort into successful source text', async () => {
-    const remote = new FakeRemote()
-    remote.file('/workspace/a', 'unused')
-    const controller = new AbortController()
-    remote.abortAfterBoundedCommand = controller
-    remote.boundedOutput = JSON.stringify({ kind: 'ok', data: Buffer.from('text').toString('base64') })
-    const { fs } = await setup(remote)
-    await expectCode(fs.readTextBounded(await fs.resolve('a'), 4, controller.signal), 'FS_ABORTED')
-  })
-
   it('rejects empty paths and directory-listing type errors', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/file', 'x')
@@ -686,17 +633,34 @@ describe('E2B filesystem adapter integration edges', () => {
     await expectCode(fs.readText(target), 'FS_IO_ERROR')
   })
 
-  it('keeps a listed child whose metadata disappears as an other entry', async () => {
+  it('uses listing metadata directly and canonicalizes only symbolic links', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/a', 'a')
-    remote.disappearOnInfo.add('/workspace/a')
+    remote.file('/workspace/target', 'target')
+    remote.file('/workspace/gone', 'gone')
+    remote.symlink('/workspace/link', '/workspace/target')
+    remote.symlink('/workspace/vanished-link', '/workspace/gone')
+    remote.disappearOnInfo.add('/workspace/gone')
     const { fs } = await setup(remote)
-    const listed = await fs.listDir(await fs.resolve('/workspace'))
-    expect(listed).toEqual([{
-      name: 'a',
+    const directory = await fs.resolve('/workspace')
+    const commandsBefore = remote.commands.length
+    const getInfo = vi.spyOn(remote.sandbox.files, 'getInfo')
+
+    const listed = await fs.listDir(directory)
+
+    expect(listed.find(entry => entry.name === 'a')).toMatchObject({
+      type: 'file', target: { targetKey: '/workspace/a' }, size: 1,
+    })
+    expect(listed.find(entry => entry.name === 'link')).toMatchObject({
+      type: 'file', target: { targetKey: '/workspace/target' }, size: 6,
+    })
+    expect(listed.find(entry => entry.name === 'vanished-link')).toEqual({
+      name: 'vanished-link',
       type: 'other',
-      target: { targetKey: '/workspace/a', displayPath: '/workspace/a' },
-    }])
+      target: { targetKey: '/workspace/gone', displayPath: '/workspace/vanished-link' },
+    })
+    expect(remote.commands.slice(commandsBefore)).toHaveLength(2)
+    expect(getInfo).toHaveBeenCalledTimes(3)
   })
 
   it('registers the package-owned empty invariant installer', async () => {
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index ac7b8d42a5..20ba9b597e 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 9b86af428533ebcc2c0da56339e6ea2a28170fd3
-README.zh.md: e3e8368534266e35ec04dcf5a2d6718829b4a016
+README.md: 9e044c13b673461a876e016ec560db4897a27c66
+README.zh.md: b9180c0c0679915fae7a1db22353613708392a8c
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 9b86af4285..9e044c13b6 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -9,9 +9,9 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — the sandbox command environment crosses the SDK callback boundary as base64 ASCII before one strict UTF-8 decode, then the wrapper removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in; empty names, `=`, and NUL framing violations reject before launch. E2B's fixed command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Environment boundary** — one trusted control-shell probe transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session before settlement; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
 The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
@@ -30,6 +30,8 @@ No direct invalidation; the named consumers own any request-prefix changes.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
 - **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
+- **Numeric process identities are not reuse-fenced** — E2B exposes numeric PID/PGID PTY input, signalling, and cleanup operations but no atomic identity-bound alternative. The adapter minimizes host round trips and live coverage exercises the reproducible stale-interrupt overlap; replacement is deferred until E2B adds an identity primitive or a failure demonstrates a narrower protocol.
+- **The initial environment probe inherits sandbox defaults** — E2B merges command overrides with default environment entries, so the probe cannot blank unknown credential-shaped names before enumerating them. In a reconnected sandbox, a same-UID untrusted process could inspect that short-lived control shell; this POC therefore does not support secrets in sandbox-default environment variables and requires an E2B replacement-environment primitive or a hardened template to close the gap.
 - **E2B exposes no signal fact** — an adapter-requested `SIGTERM` or `SIGKILL` is reported only when no wrapper-published direct exit code wins; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
 - **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
 - **Linux utility and E2B transport semantics are assumed** — there is no Windows, arbitrary-template, escaped-session recovery, or network-partition fidelity layer.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index e3e8368534..b9180c0c06 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -9,9 +9,9 @@
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：沙箱命令环境会先以 base64 ASCII 跨越 SDK 回调边界，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，E2B 固定的命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 才会接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **环境边界**：一次受信任的控制 shell 探测会以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 才会接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并在结算前清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
 基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
@@ -30,6 +30,8 @@
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
 - **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
+- **数值进程身份没有复用围栏**：E2B 公开基于数值 PID/PGID 的 PTY 输入、信号发送和清理操作，却没有与身份原子绑定的替代方案。适配器会尽量减少宿主往返，真实环境测试会覆盖可复现的陈旧中断重叠；在 E2B 新增身份原语，或实际故障证明需要更窄的协议之前，替代方案会继续延后。
+- **初始环境探测会继承沙箱默认值**：E2B 会把命令覆盖与默认环境条目合并，因此探测无法在枚举未知且形似凭据的名称之前将它们置空。在重新连接的沙箱中，一个同 UID 的不可信进程可以检查该短时存在的控制 shell；因此，该 POC 不支持把 secret 放入沙箱默认环境变量，需要 E2B 的替换环境原语或经加固的模板才能弥合该缺口。
 - **E2B 不公开信号事实**：适配器请求的 `SIGTERM` 或 `SIGKILL` 只有在包装层发布的直接退出码没有胜出时才报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
 - **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
 - **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、任意模板、逃逸会话恢复或网络分区的保真层。
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index 5322491261..907810a1d7 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -26,6 +26,8 @@ function remoteEnvironmentEntries(raw: string): Array<readonly [string, string]>
  * @returns the complete NUL-delimited UTF-8 environment.
  */
 export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSignal): Promise<string> {
+  // TODO(e2b-replace-environment): Remove this ambient probe when E2B can start
+  // a command with a replacement environment instead of merged overrides.
   const result = await sandbox.commands.run(
     'set -o pipefail; printf \'%s\' "$PWD" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
     { envs: e2bControlEnvs(), ...(signal === undefined ? {} : { signal }) },
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 7318dfde95..990ab20a62 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -61,8 +61,7 @@ export class E2BSubprocessService extends SubprocessService {
         }))
       }
       for (const terminal of terminals) {
-        terminal.terminate()
-        pending.push(terminal.waitForExit().then(() => { this.terminals.delete(terminal) }))
+        pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
       }
       for (const cleanup of failedTerminalSetupCleanups) {
         pending.push(cleanup().then(() => { this.failedTerminalSetupCleanups.delete(cleanup) }))
@@ -125,7 +124,9 @@ export class E2BSubprocessService extends SubprocessService {
       await handle.waitForExit()
       this.live.delete(handle)
     }
-    void handle.done.then(release, release).catch(() => {})
+    void handle.done.then(release, release).catch((_automaticReleaseFailure: unknown) => {
+      // Retain the handle so service disposal can retry its cleanup transaction.
+    })
     return handle
   }
 
@@ -158,16 +159,17 @@ export class E2BSubprocessService extends SubprocessService {
       )
       this.terminals.add(terminal)
       if (this.isDisposing()) {
-        terminal.terminate()
-        await terminal.waitForExit()
+        await terminal.terminate()
         this.terminals.delete(terminal)
         throw new Error('subprocess-e2b: service disposed during terminal setup')
       }
       const release = async (): Promise<void> => {
-        await terminal.waitForExit()
+        await terminal.terminate()
         this.terminals.delete(terminal)
       }
-      void terminal.done.then(release, release).catch(() => {})
+      void terminal.done.then(release, release).catch((_automaticReleaseFailure: unknown) => {
+        // Retain the terminal so service disposal can retry its cleanup transaction.
+      })
       return terminal
     } finally {
       this.terminalSetups.delete(setup.promise)
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 6b17f3b682..02e1583e56 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -726,7 +726,9 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       // A spill mode is a collect mode, so construction always created its reader.
       const size = (reader as E2BOutputReader).size
       if (this.outputDrainExpired || size <= mode.maxBytes || size > mode.spill.maxBytes) {
-        removals.push(sandbox.files.remove(path).catch(() => {}))
+        removals.push(sandbox.files.remove(path).catch((_adapterPrivateSpillRemovalFailure: unknown) => {
+          // The command outcome is authoritative; a retained sandbox tolerates private residue.
+        }))
       }
     }
     collect(this.spec.stdio.stdout, this.stdoutReader, this.paths.stdout)
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index ff8af60da9..6c4b23d1c1 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -12,7 +12,6 @@ import {
   quoteE2BShellArg,
 } from '@deepseek-ai/dsh-e2b'
 import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
-import { SubprocessTerminalLifecycle } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessOutcome,
   SubprocessTerminalForeground,
@@ -345,7 +344,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   readonly done: Promise<SubprocessOutcome>
 
   private topLevelExited = false
-  private readonly lifecycle: SubprocessTerminalLifecycle
+  private cleanup: Promise<void> | undefined
   private terminationSignal: NodeJS.Signals | null = null
 
   constructor(
@@ -357,21 +356,17 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     private readonly controlEnvs: Record<string, string>,
     private readonly stateDir: string,
     private readonly graceMs: number,
-    signal?: AbortSignal,
   ) {
     this.pid = handle.pid
     this.done = this.waitForCommand()
-    this.lifecycle = new SubprocessTerminalLifecycle({
-      done: this.done,
-      cleanup: () => this.closeOnce(),
-      signal,
-    })
   }
 
+  // TODO(e2b-pgid-identity): Replace retained numeric PTY/session ids when E2B
+  // exposes identity-bound input, foreground-signal, and cleanup operations.
   /** @inheritdoc */
-  async write(data: Uint8Array): Promise<void> {
+  async write(data: string): Promise<void> {
     if (this.topLevelExited) throw new Error('terminal process has exited')
-    await this.sandbox.pty.sendInput(this.pid, data)
+    await this.sandbox.pty.sendInput(this.pid, Buffer.from(data, 'utf8'))
   }
 
   /** @inheritdoc */
@@ -413,13 +408,14 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   }
 
   /** @inheritdoc */
-  terminate(): void {
-    this.lifecycle.terminate()
-  }
-
-  /** @inheritdoc */
-  async waitForExit(signal?: AbortSignal): Promise<boolean> {
-    return await this.lifecycle.waitForExit(signal)
+  terminate(): Promise<void> {
+    if (this.cleanup !== undefined) return this.cleanup
+    const cleanup = this.closeOnce()
+    this.cleanup = cleanup
+    void cleanup.catch((_cleanupFailure: unknown) => {
+      this.cleanup = undefined
+    })
+    return cleanup
   }
 
   private async waitForCommand(): Promise<SubprocessOutcome> {
@@ -474,7 +470,11 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     } catch (error: unknown) {
       if (!(error instanceof SandboxNotFoundError)) throw error
     }
-    await this.sandbox.files.remove(this.stateDir).catch(() => {})
+    try {
+      await this.sandbox.files.remove(this.stateDir)
+    } catch (_adapterPrivateStateRemovalFailure) {
+      // The terminal is quiescent; a retained sandbox tolerates private residue.
+    }
   }
 }
 
@@ -558,7 +558,6 @@ export async function spawnE2BTerminal(
       controlEnvs,
       stateDir,
       spec.graceMs,
-      spec.signal,
     )
   } catch (error: unknown) {
     output.destroy()
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 8ad0eb1dde..6c3ef477af 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -1,6 +1,5 @@
 import { Buffer } from 'node:buffer'
 import { once } from 'node:events'
-import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import {
@@ -14,7 +13,7 @@ import {
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
 import type { SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
-import { E2BTerminalHandle, spawnE2BTerminal } from '../src/terminal.ts'
+import { spawnE2BTerminal } from '../src/terminal.ts'
 
 function commandError(exitCode: number): CommandExitError {
   return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
@@ -298,20 +297,20 @@ describe('E2B terminal allocation', () => {
     await fake.createOptions?.onData(Buffer.from('late bootstrap callback'))
     expect(output).toBe('requested-shell$ ')
 
-    await terminal.write(Buffer.from('echo ok\r'))
+    await terminal.write('echo ok\r')
     expect(fake.inputs.at(-1)?.data.toString()).toBe('echo ok\r')
     await expect(terminal.inspectForeground()).resolves.toEqual({ processGroupId: 456, inputWaiting: false })
     await expect(terminal.signalForeground('SIGINT')).resolves.toBe(456)
     expect(fake.commands).toContain('kill -INT -- -456')
 
-    terminal.terminate()
+    const terminated = terminal.terminate()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminated
     expect(fake.handle.disconnects).toBe(1)
     expect(fake.removed).toContain('/runtime/terminal-one')
   })
 
-  it('inherits only safe ambient values and binds live abort to terminal cleanup', async () => {
+  it('inherits only safe ambient values and limits the allocation signal to setup', async () => {
     const fake = new FakeTerminalSandbox()
     const controller = new AbortController()
     const terminal = await spawnE2BTerminal(
@@ -325,9 +324,10 @@ describe('E2B terminal allocation', () => {
     expect(environment).not.toContain('DSH_STALE')
 
     controller.abort(new Error('stop'))
+    await terminal.write('still live\r')
+    expect(fake.inputs.at(-1)?.data.toString()).toBe('still live\r')
+    await terminal.terminate()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
-    await expect(terminal.waitForExit(controller.signal)).resolves.toBe(false)
-    await expect(terminal.waitForExit()).resolves.toBe(true)
   })
 
   it('publishes the PTY handle before honoring allocation cancellation', async () => {
@@ -553,31 +553,11 @@ describe('E2B terminal lifecycle', () => {
     fake.handle.succeed(7)
     await expect(terminal.done).resolves.toEqual({ exitCode: 7, signal: null })
     await ended
-    await expect(terminal.waitForExit()).resolves.toBe(true)
-    await expect(terminal.write(Buffer.from('late'))).rejects.toThrow('exited')
+    await expect(terminal.write('late')).rejects.toThrow('exited')
     fake.foregroundFailure = commandError(1)
     await expect(terminal.inspectForeground()).resolves.toBeUndefined()
     await expect(terminal.signalForeground('SIGINT')).rejects.toThrow('cannot resolve foreground process group')
-  })
-
-  it('starts cleanup when the lifetime signal is already aborted at handle publication', async () => {
-    const fake = new FakeTerminalSandbox()
-    const controller = new AbortController()
-    controller.abort(new Error('publication cancelled'))
-    const terminal = new E2BTerminalHandle(
-      fake.sandbox,
-      fake.handle.asHandle(),
-      new PassThrough(),
-      fake.handle.wait(),
-      123,
-      { TERM: 'dumb' },
-      '/runtime/pre-aborted',
-      1,
-      controller.signal,
-    )
-
-    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
   })
 
   it.each([
@@ -590,18 +570,7 @@ describe('E2B terminal lifecycle', () => {
     const terminal = await spawnE2BTerminal(runtime(fake), spec(), `/runtime/exit-${exitCode}`)
     fake.handle.fail(exitCode)
     await expect(terminal.done).resolves.toEqual(expected)
-    await expect(terminal.waitForExit(new AbortController().signal)).resolves.toBe(true)
-  })
-
-  it('lets an early quiescence observer follow a transport rejection', async () => {
-    const fake = new FakeTerminalSandbox()
-    fake.groups = []
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/early-observer')
-    terminal.output.on('error', () => {})
-    const quiescence = terminal.waitForExit()
-    fake.handle.crash(new Error('transport failed'))
-    await expect(terminal.done).rejects.toThrow('transport failed')
-    await expect(quiescence).resolves.toBe(true)
+    await terminal.terminate()
   })
 
   it('treats a terminal session containing only zombies as quiescent', async () => {
@@ -612,7 +581,7 @@ describe('E2B terminal lifecycle', () => {
 
     fake.handle.succeed(0)
     await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
     expect(fake.commands).toContain(
       "set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == 123 && $3 !~ /^[ZXx]/ { print $2 }'",
     )
@@ -625,7 +594,7 @@ describe('E2B terminal lifecycle', () => {
     fake.handle.succeed(0)
 
     await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
   })
 
   it('treats sandbox disappearance during PTY kill as quiescent', async () => {
@@ -635,8 +604,7 @@ describe('E2B terminal lifecycle', () => {
     fake.ptyKillError = new SandboxNotFoundError('sandbox expired')
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
 
-    terminal.terminate()
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
     expect(fake.ptyKills).toBe(1)
   })
 
@@ -647,8 +615,11 @@ describe('E2B terminal lifecycle', () => {
     fake.ptyKillError = new Error('PTY kill transport failed')
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
 
-    terminal.terminate()
-    await expect(terminal.waitForExit()).rejects.toThrow('PTY kill transport failed')
+    await expect(terminal.terminate()).rejects.toThrow('PTY kill transport failed')
+    fake.ptyKillError = undefined
+    fake.handle.succeed(0)
+    await terminal.done
+    await terminal.terminate()
   })
 
   it.each([
@@ -661,8 +632,8 @@ describe('E2B terminal lifecycle', () => {
     fake.groups = []
     fake.handle.succeed(0)
 
-    if (accepted) await expect(terminal.waitForExit()).resolves.toBe(true)
-    else await expect(terminal.waitForExit()).rejects.toThrow('disconnect failed')
+    if (accepted) await expect(terminal.terminate()).resolves.toBeUndefined()
+    else await expect(terminal.terminate()).rejects.toThrow('disconnect failed')
   })
 
   it('rejects killing the terminal shell and propagates live foreground failures', async () => {
@@ -677,23 +648,17 @@ describe('E2B terminal lifecycle', () => {
     fake.foregroundFailure = commandError(2)
     await expect(terminal.inspectForeground()).rejects.toBeInstanceOf(CommandExitError)
     fake.clearOnTerm = true
-    terminal.terminate()
-    await terminal.waitForExit()
+    await terminal.terminate()
   })
 
-  it('escalates surviving process groups and bounds an observing wait', async () => {
+  it('escalates surviving process groups', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = [123, 456]
     fake.clearOnTerm = false
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/escalate')
-    const controller = new AbortController()
-    const observing = terminal.waitForExit(controller.signal)
-    controller.abort()
-    await expect(observing).resolves.toBe(false)
-
-    terminal.terminate()
+    const terminating = terminal.terminate()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminating
     expect(fake.commands).toContain('kill -TERM -- -123 -456')
     expect(fake.commands).toContain('kill -KILL -- -123 -456')
   })
@@ -702,49 +667,31 @@ describe('E2B terminal lifecycle', () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = [1]
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry')
-    terminal.terminate()
-    await expect(terminal.waitForExit(new AbortController().signal)).rejects.toThrow('unsafe process group 1')
+    await expect(terminal.terminate()).rejects.toThrow('unsafe process group 1')
 
     fake.groups = []
     fake.handle.succeed(0)
     await terminal.done
-    terminal.terminate()
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
   })
 
   it('propagates a process-group signalling transport failure before retry', async () => {
     const fake = new FakeTerminalSandbox()
     fake.termFailure = new Error('signal transport failed')
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/signal-failure')
-    terminal.terminate()
-    await expect(terminal.waitForExit()).rejects.toThrow('signal transport failed')
+    await expect(terminal.terminate()).rejects.toThrow('signal transport failed')
 
     fake.groups = []
     fake.handle.succeed(0)
     await terminal.done
-    terminal.terminate()
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await terminal.terminate()
 
     const alreadyExited = new FakeTerminalSandbox()
     alreadyExited.termFailure = commandError(1)
     const tolerant = await spawnE2BTerminal(runtime(alreadyExited), spec({ graceMs: 1 }), '/runtime/group-exited')
-    tolerant.terminate()
+    const tolerantTermination = tolerant.terminate()
     await expect(tolerant.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
-    await expect(tolerant.waitForExit()).resolves.toBe(true)
-  })
-
-  it('normalizes a non-Error cleanup rejection for an observing wait', async () => {
-    const fake = new FakeTerminalSandbox()
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/non-error-cleanup')
-    fake.commandFailure = 'cleanup transport gone'
-    terminal.terminate()
-    await expect(terminal.waitForExit(new AbortController().signal)).rejects.toThrow('cleanup transport gone')
-
-    fake.groups = []
-    fake.handle.succeed(0)
-    await terminal.done
-    terminal.terminate()
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await tolerantTermination
   })
 
   it('keeps command rejection authoritative while cleanup is already waiting', async () => {
@@ -753,11 +700,11 @@ describe('E2B terminal lifecycle', () => {
     fake.removeError = new Error('private state already gone')
     const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/reject-during-cleanup')
     terminal.output.on('error', () => {})
-    terminal.terminate()
+    const cleanup = terminal.terminate()
     await Promise.resolve()
     fake.handle.crash(new Error('command transport failed'))
     await expect(terminal.done).rejects.toThrow('command transport failed')
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await cleanup
   })
 
   it('keeps a late command rejection authoritative after PTY kill', async () => {
@@ -766,12 +713,12 @@ describe('E2B terminal lifecycle', () => {
     fake.settleOnPtyKill = false
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
     terminal.output.on('error', () => {})
-    terminal.terminate()
+    const cleanup = terminal.terminate()
     while (fake.ptyKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
     await Promise.resolve()
     fake.handle.crash(new Error('late command transport failed'))
     await expect(terminal.done).rejects.toThrow('late command transport failed')
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await cleanup
   })
 
   it('reports surviving groups, a surviving top-level pid, and transport failure', async () => {
@@ -779,15 +726,13 @@ describe('E2B terminal lifecycle', () => {
     survivor.clearOnTerm = false
     survivor.clearOnKill = false
     const terminal = await spawnE2BTerminal(runtime(survivor), spec({ graceMs: 1 }), '/runtime/survivor')
-    terminal.terminate()
-    await expect(terminal.waitForExit()).rejects.toThrow('surviving process groups: 123')
+    await expect(terminal.terminate()).rejects.toThrow('surviving process groups: 123')
 
     const livePid = new FakeTerminalSandbox()
     livePid.groups = []
     livePid.settleOnPtyKill = false
     const live = await spawnE2BTerminal(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
-    live.terminate()
-    await expect(live.waitForExit()).rejects.toThrow('surviving pid: 123')
+    await expect(live.terminate()).rejects.toThrow('surviving pid: 123')
     livePid.handle.succeed(0)
     await live.done
 
@@ -798,7 +743,7 @@ describe('E2B terminal lifecycle', () => {
     crashed.handle.crash('transport gone')
     await expect(failed.done).rejects.toEqual('transport gone')
     await expect(outputError).resolves.toMatchObject([{ message: 'transport gone' }])
-    await expect(failed.waitForExit()).resolves.toBe(true)
+    await failed.terminate()
   })
 })
 
@@ -943,7 +888,7 @@ describe('E2B subprocess terminal service', () => {
     const terminal = await ctx.subprocess.spawnTerminal(spec())
     fake.handle.succeed(0)
     await terminal.done
-    await terminal.waitForExit()
+    await terminal.terminate()
     const signals = fake.commands.filter(command => command.startsWith('kill -')).length
     await fiber.dispose()
     expect(fake.commands.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
@@ -961,6 +906,6 @@ describe('E2B subprocess terminal service', () => {
 
     fake.groups = []
     await fiber.dispose()
-    await expect(terminal.waitForExit()).resolves.toBe(true)
+    await expect(terminal.terminate()).resolves.toBeUndefined()
   })
 })
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index ae44721735..f4719447aa 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: 96bbe6c95bd2aca7e66cf2d57abb3f056cd19390
-README.zh.md: 7f091b4f0955b847d21b8b3423dab421e610cda3
+README.md: b15012e882b60847e1ad22edf08d1202ba64fe5b
+README.zh.md: 628f6c74894bc67559d49f7cf5d1378d0ece2382
diff --git a/packages/fs/README.md b/packages/fs/README.md
index 96bbe6c95b..b15012e882 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -14,7 +14,7 @@ The filesystem stack: a provider seam (execution-world paths, bounded text IO, a
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
 | `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote runtime shared with the E2B subprocess provider ([POC decision](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
 
 ## No timeouts on file IO
 
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 7f091b4f09..628f6c7489 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -14,7 +14,7 @@
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
 | `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程运行时中（[POC 决策](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
 
 ## 文件 I/O 不设超时
 

From 677541d1230a78fe7af64fd28f0afdaba00225ab Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 22:04:55 +0800
Subject: [PATCH 381/516] fix(e2b): close proven provider boundary gaps

---
 docs/cordis-catalog/services.md               |  2 +-
 packages/e2b/e2b/README.i18n.yaml             |  4 +-
 packages/e2b/e2b/README.md                    |  2 +-
 packages/e2b/e2b/README.zh.md                 |  2 +-
 packages/e2b/e2b/src/index.ts                 | 21 ++---
 packages/e2b/e2b/tests/e2b.spec.ts            |  6 +-
 packages/e2b/fs-e2b/src/invariant.ts          |  5 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         |  6 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  6 +-
 .../e2b/subprocess-e2b/src/environment.ts     |  2 +-
 packages/e2b/subprocess-e2b/src/invariant.ts  |  5 +-
 packages/e2b/subprocess-e2b/src/process.ts    | 15 ++--
 packages/e2b/subprocess-e2b/src/terminal.ts   | 85 +++++++++++++------
 .../subprocess-e2b/tests/subprocess.spec.ts   | 11 ++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 61 +++++++++++++
 16 files changed, 167 insertions(+), 70 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index cdd2d87435..3942c0696d 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -591,7 +591,7 @@ Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decisio
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:109`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:108`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index fb645c2e36..7d6b503ef4 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 402903184934903eceb36a04d670e4490879ac65
-README.zh.md: 1fec6ab66858f04a47c8a2a7cb5f6a8907ab6cac
+README.md: 6881556dc18497956966aff74adc085d8e8620d3
+README.zh.md: aea13f341f903e6c47b7484f477bf54cebf101c6
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 4029031849..6881556dc1 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -24,7 +24,7 @@ Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapte
 
 `apiKey` is optional and otherwise reads `E2B_API_KEY`; the key configures the host SDK connection and is never installed in the sandbox. `cwd` defaults to `/home/user/workspace` and must be an absolute POSIX path. `timeoutMs` defaults to five minutes. `onTimeout` is `pause` by default and accepts `pause | kill`; it applies only when this service creates a sandbox. Pause-on-timeout enables E2B auto-resume so the shared SDK handle wakes on its next operation. `onDispose` defaults to `kill` and accepts `kill | pause | leave`.
 
-Set `sandboxId` to reconnect a running or paused sandbox instead of creating one. E2B resumes a paused sandbox during connect; `template` is creation-only and cannot accompany `sandboxId`. Omitting `template` uses E2B's default base template.
+Set `sandboxId` to reconnect a running or paused sandbox instead of creating one. E2B resumes a paused sandbox during connect; `template` and `onTimeout` are creation-only and cannot accompany `sandboxId`. Omitting `template` uses E2B's default base template.
 
 ## Lifecycle and ownership
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 1fec6ab668..aea13f341f 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -24,7 +24,7 @@
 
 `apiKey` 可省略；省略时读取 `E2B_API_KEY`。该密钥只配置宿主 SDK 连接，绝不会安装进沙箱。`cwd` 默认为 `/home/user/workspace`，并且必须是绝对 POSIX 路径。`timeoutMs` 默认为 5 分钟。`onTimeout` 默认为 `pause`，接受 `pause | kill`；它只在本服务创建沙箱时生效。超时时 pause 会启用 E2B 自动恢复，使共享 SDK 句柄在下一次操作时唤醒。`onDispose` 默认为 `kill`，接受 `kill | pause | leave`。
 
-设置 `sandboxId` 可重新连接正在运行或已经暂停的沙箱，而不是创建新沙箱。连接时，E2B 会恢复已经暂停的沙箱；`template` 仅用于创建，不能与 `sandboxId` 同时使用。省略 `template` 时使用 E2B 的默认基础模板。
+设置 `sandboxId` 可重新连接正在运行或已经暂停的沙箱，而不是创建新沙箱。连接时，E2B 会恢复已经暂停的沙箱；`template` 和 `onTimeout` 仅用于创建，不能与 `sandboxId` 同时使用。省略 `template` 时使用 E2B 的默认基础模板。
 
 ## 生命周期与所有权
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 9e8960a685..3285d82395 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -91,7 +91,6 @@ interface ResolvedConfig {
 interface SchemaResolvedConfig extends Config {
   cwd: string
   timeoutMs: number
-  onTimeout: E2BTimeoutMode
   onDispose: E2BDisposeMode
 }
 
@@ -113,7 +112,7 @@ export class E2BSandboxService extends Service {
     template: z.string(),
     cwd: z.string().default('/home/user/workspace'),
     timeoutMs: z.number().default(300_000),
-    onTimeout: z.union(['kill', 'pause'] as const).default('pause'),
+    onTimeout: z.union(['kill', 'pause'] as const),
     onDispose: z.union(['kill', 'pause', 'leave'] as const).default('kill'),
   })
 
@@ -121,17 +120,12 @@ export class E2BSandboxService extends Service {
   readonly cwd: string
   /** Remote directory reserved for adapter-owned process and terminal state. */
   readonly runtimeRoot: string
-  /** Whether this service creates a sandbox rather than reconnecting one. */
-  readonly created: boolean
-  /** Configured action when a newly created sandbox reaches its lifetime. */
-  readonly timeoutMode: E2BTimeoutMode
-  /** Configured final sandbox disposition. */
-  readonly disposeMode: E2BDisposeMode
   /** Sandbox id once E2B has created or resolved the remote runtime. */
   readonly sandboxId: Promise<E2BSandboxId>
 
   private readonly config: ResolvedConfig
   private readonly ready: Promise<Sandbox>
+  private readonly created: boolean
   private failedSetupSandbox: Sandbox | undefined
   private disposed = false
 
@@ -144,17 +138,15 @@ export class E2BSandboxService extends Service {
       apiKey: apiKey ?? '',
       cwd: resolved.cwd,
       timeoutMs: resolved.timeoutMs,
-      onTimeout: resolved.onTimeout,
+      onTimeout: config.onTimeout ?? 'pause',
       onDispose: resolved.onDispose,
       ...(config.sandboxId !== undefined ? { sandboxId: config.sandboxId } : {}),
       ...(config.template !== undefined ? { template: config.template } : {}),
     }
-    this.validate()
+    this.validate(config)
     this.cwd = this.config.cwd
     this.runtimeRoot = posix.join(this.cwd, '.dsh-e2b')
     this.created = this.config.sandboxId === undefined
-    this.timeoutMode = this.config.onTimeout
-    this.disposeMode = this.config.onDispose
     this.ready = this.open()
     // A deployment may load the owner before any adapter uses it. Keep a
     // failed eager connection observed; getSandbox() still returns the error.
@@ -218,7 +210,7 @@ export class E2BSandboxService extends Service {
     return sandbox
   }
 
-  private validate(): void {
+  private validate(input: Config): void {
     if (this.config.apiKey.length === 0) {
       throw new Error('dsh-e2b: configure apiKey or set E2B_API_KEY')
     }
@@ -234,6 +226,9 @@ export class E2BSandboxService extends Service {
     if (this.config.sandboxId !== undefined && this.config.template !== undefined) {
       throw new Error('dsh-e2b: template applies only when creating; omit it when sandboxId reconnects')
     }
+    if (this.config.sandboxId !== undefined && input.onTimeout !== undefined) {
+      throw new Error('dsh-e2b: onTimeout applies only when creating; omit it when sandboxId reconnects')
+    }
   }
 
   private async open(): Promise<Sandbox> {
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index 46ba452210..af55a2419a 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -90,9 +90,6 @@ describe('E2BSandboxService', () => {
     await expect(service.sandboxId).resolves.toBe(E2BSandboxId('sandbox-1'))
     expect(service.cwd).toBe('/home/user/workspace')
     expect(service.runtimeRoot).toBe('/home/user/workspace/.dsh-e2b')
-    expect(service.created).toBe(true)
-    expect(service.timeoutMode).toBe('pause')
-    expect(service.disposeMode).toBe('kill')
     expect(sdk.create).toHaveBeenCalledWith({
       apiKey: 'test-key',
       timeoutMs: 300_000,
@@ -225,7 +222,6 @@ describe('E2BSandboxService', () => {
     ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
     const fiber = await ctx.plugin(E2BSandboxService, {
       apiKey: 'test-key',
-      onTimeout: reconnect ? 'kill' : 'pause',
       onDispose: 'pause',
       ...(reconnect ? { sandboxId: 'existing' } : {}),
     })
@@ -248,7 +244,6 @@ describe('E2BSandboxService', () => {
     })
     await ctx.e2b.getSandbox()
 
-    expect(ctx.e2b.created).toBe(false)
     expect(sdk.connect).toHaveBeenCalledWith('existing', { apiKey: 'test-key', timeoutMs: 90_000 })
     expect(sdk.create).not.toHaveBeenCalled()
     await fiber.dispose()
@@ -330,6 +325,7 @@ describe('E2BSandboxService', () => {
     [{ apiKey: 'x', timeoutMs: 0 }, /positive finite/],
     [{ apiKey: 'x', sandboxId: '' }, /sandboxId must be non-empty/],
     [{ apiKey: 'x', sandboxId: 'one', template: 'two' }, /template applies only/],
+    [{ apiKey: 'x', sandboxId: 'one', onTimeout: 'kill' }, /onTimeout applies only/],
   ] as const)('fails self-contained configuration before opening E2B: %j', async (config, message) => {
     vi.stubEnv('E2B_API_KEY', '')
     const ctx = new Context()
diff --git a/packages/e2b/fs-e2b/src/invariant.ts b/packages/e2b/fs-e2b/src/invariant.ts
index 6294d66ace..9f14bb37a6 100644
--- a/packages/e2b/fs-e2b/src/invariant.ts
+++ b/packages/e2b/fs-e2b/src/invariant.ts
@@ -1,4 +1,7 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-fs-e2b`. */
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-fs-e2b`.
+ * @module @deepseek-ai/dsh-fs-e2b/invariant
+ */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 20ba9b597e..9ac46f1bcb 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 9e044c13b673461a876e016ec560db4897a27c66
-README.zh.md: b9180c0c0679915fae7a1db22353613708392a8c
+README.md: 9d563c91c149d28718159af1b1f8ddbd6652dc44
+README.zh.md: be189f41818c66aeff2bed7b1851b82ca08f08f4
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 9e044c13b6..9d563c91c1 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -9,12 +9,12 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — one trusted control-shell probe transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the template's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; zombie-only groups are already quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
-The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, and `kill`. A custom template must retain compatible commands and E2B PTY support.
+The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`. A custom template must retain compatible commands and E2B PTY support.
 
 ## Model Experience
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index b9180c0c06..be189f4181 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -9,12 +9,12 @@
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：一次受信任的控制 shell 探测会以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 才会接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变模板 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；仅含僵尸进程的进程组已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
-基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm` 和 `kill`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
+基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
 
 ## 模型体验
 
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index 907810a1d7..8daae9ccfd 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -29,7 +29,7 @@ export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSign
   // TODO(e2b-replace-environment): Remove this ambient probe when E2B can start
   // a command with a replacement environment instead of merged overrides.
   const result = await sandbox.commands.run(
-    'set -o pipefail; printf \'%s\' "$PWD" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
+    'set -o pipefail; dsh_e2b_passwd="$(getent passwd "$(id -u)")"; IFS=: read -r _ _ _ _ _ dsh_e2b_home _ <<<"$dsh_e2b_passwd"; test -n "$dsh_e2b_home" -a -d "$dsh_e2b_home"; printf \'%s\' "$dsh_e2b_home" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
     { envs: e2bControlEnvs(), ...(signal === undefined ? {} : { signal }) },
   )
   const lines = result.stdout.trim().split('\n')
diff --git a/packages/e2b/subprocess-e2b/src/invariant.ts b/packages/e2b/subprocess-e2b/src/invariant.ts
index 4416175b1b..9f8b8fb739 100644
--- a/packages/e2b/subprocess-e2b/src/invariant.ts
+++ b/packages/e2b/subprocess-e2b/src/invariant.ts
@@ -1,4 +1,7 @@
-/** Package-owned invariant companion for `@deepseek-ai/dsh-subprocess-e2b`. */
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subprocess-e2b`.
+ * @module @deepseek-ai/dsh-subprocess-e2b/invariant
+ */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 02e1583e56..83dedd4e97 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -104,7 +104,6 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
     : `2> >(${encoder} >&2 2>/dev/null)`
   const inner = [
     'set +e',
-    'umask 077',
     'dsh_e2b_env_bin=$1',
     'dsh_e2b_node=$2',
     'dsh_e2b_ps=$3',
@@ -520,6 +519,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       () => true,
     )
     while (true) {
+      // TODO(e2b-publication-cancel): Join cancellation to the existing
+      // termination transaction before aborting an in-flight SDK file read.
       const raw = await sandbox.files.read(this.paths.pid)
       const value = raw.trim()
       if (value.length > 0) {
@@ -543,6 +544,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       result => ({ kind: 'result', result }),
       (error: unknown) => ({ kind: 'error', error }),
     )
+    const hasPipeOutput = this.spec.stdio.stdout === 'pipe' || this.spec.stdio.stderr === 'pipe'
+    let completed = hasPipeOutput ? await settlement : undefined
     while (true) {
       const rawStatus = (await sandbox.files.read(this.paths.status)).trim()
       if (rawStatus.length > 0) {
@@ -550,19 +553,19 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         if (!/^(?:0|[1-9][0-9]*)$/.test(rawStatus) || !Number.isSafeInteger(exitCode) || exitCode > 255) {
           throw new Error(`subprocess-e2b: remote wrapper published invalid exit code ${JSON.stringify(rawStatus)}`)
         }
-        if (this.spec.stdio.stdout === 'pipe' || this.spec.stdio.stderr === 'pipe') {
-          return this.commandOutcome(await settlement, exitCode)
-        }
-        const completed = await withinMs(settlement, this.spec.graceMs)
         if (completed !== undefined) return this.commandOutcome(completed, exitCode)
+        const drained = await withinMs(settlement, this.spec.graceMs)
+        if (drained !== undefined) return this.commandOutcome(drained, exitCode)
         this.outputDrainExpired = true
         this.stdoutReader?.invalidateSpill()
         this.stderrReader?.invalidateSpill()
         await handle.disconnect()
         return { exitCode, signal: null }
       }
-      const completed = await Promise.race([settlement, waitTick().then(() => undefined)])
       if (completed !== undefined) return this.commandOutcome(completed)
+      // TODO(e2b-status-watch): Replace collect/inherit polling when E2B can
+      // observe direct-command exit independently of descendant-held output.
+      completed = await Promise.race([settlement, waitTick().then(() => undefined)])
     }
   }
 
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 6c4b23d1c1..8d003dfc35 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -345,6 +345,9 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
 
   private topLevelExited = false
   private cleanup: Promise<void> | undefined
+  private readonly operationController = new AbortController()
+  private readonly operations = new Set<Promise<unknown>>()
+  private terminating = false
   private terminationSignal: NodeJS.Signals | null = null
 
   constructor(
@@ -364,17 +367,56 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   // TODO(e2b-pgid-identity): Replace retained numeric PTY/session ids when E2B
   // exposes identity-bound input, foreground-signal, and cleanup operations.
   /** @inheritdoc */
-  async write(data: string): Promise<void> {
-    if (this.topLevelExited) throw new Error('terminal process has exited')
-    await this.sandbox.pty.sendInput(this.pid, Buffer.from(data, 'utf8'))
+  write(data: string): Promise<void> {
+    return this.trackOperation(async (signal) => {
+      if (this.topLevelExited) throw new Error('terminal process has exited')
+      await this.sandbox.pty.sendInput(this.pid, Buffer.from(data, 'utf8'), { signal })
+    })
   }
 
   /** @inheritdoc */
-  async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+  inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+    return this.trackOperation(signal => this.inspectForegroundOnce(signal))
+  }
+
+  /** @inheritdoc */
+  signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
+    return this.trackOperation(async (operationSignal) => {
+      const foreground = await this.inspectForegroundOnce(operationSignal)
+      if (foreground === undefined) {
+        throw new Error(`subprocess-e2b: cannot resolve foreground process group for terminal ${this.pid}`)
+      }
+      if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
+        throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
+      }
+      await this.sandbox.commands.run(
+        `kill -${signal.slice(3)} -- -${foreground.processGroupId}`,
+        commandOpts(this.controlEnvs, operationSignal),
+      )
+      return foreground.processGroupId
+    })
+  }
+
+  /** @inheritdoc */
+  terminate(): Promise<void> {
+    if (this.cleanup !== undefined) return this.cleanup
+    this.terminating = true
+    this.operationController.abort(new Error('subprocess-e2b: terminal is terminating'))
+    const cleanup = this.closeAfterOperations()
+    this.cleanup = cleanup
+    void cleanup.catch((_cleanupFailure: unknown) => {
+      this.cleanup = undefined
+    })
+    return cleanup
+  }
+
+  private async inspectForegroundOnce(
+    signal: AbortSignal,
+  ): Promise<SubprocessTerminalForeground | undefined> {
     try {
       const result = await this.sandbox.commands.run(
         `ps -o tpgid= -p ${this.pid}`,
-        commandOpts(this.controlEnvs),
+        commandOpts(this.controlEnvs, signal),
       )
       return {
         processGroupId: parsePositiveId(
@@ -391,31 +433,20 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     }
   }
 
-  /** @inheritdoc */
-  async signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
-    const foreground = await this.inspectForeground()
-    if (foreground === undefined) {
-      throw new Error(`subprocess-e2b: cannot resolve foreground process group for terminal ${this.pid}`)
-    }
-    if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
-      throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
-    }
-    await this.sandbox.commands.run(
-      `kill -${signal.slice(3)} -- -${foreground.processGroupId}`,
-      commandOpts(this.controlEnvs),
+  private trackOperation<T>(operation: (signal: AbortSignal) => Promise<T>): Promise<T> {
+    if (this.terminating) return Promise.reject(new Error('subprocess-e2b: terminal is terminating'))
+    const pending = operation(this.operationController.signal)
+    this.operations.add(pending)
+    void pending.then(
+      () => { this.operations.delete(pending) },
+      () => { this.operations.delete(pending) },
     )
-    return foreground.processGroupId
+    return pending
   }
 
-  /** @inheritdoc */
-  terminate(): Promise<void> {
-    if (this.cleanup !== undefined) return this.cleanup
-    const cleanup = this.closeOnce()
-    this.cleanup = cleanup
-    void cleanup.catch((_cleanupFailure: unknown) => {
-      this.cleanup = undefined
-    })
-    return cleanup
+  private async closeAfterOperations(): Promise<void> {
+    if (this.operations.size > 0) await Promise.allSettled(this.operations)
+    await this.closeOnce()
   }
 
   private async waitForCommand(): Promise<SubprocessOutcome> {
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 0e906b1cfb..83e86892d4 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -116,6 +116,7 @@ class FakeSandbox {
   environmentRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
   processGroupId = '4242\n'
   exitStatus = ''
+  statusReads = 0
   readonly processGroupReads: string[] = []
   afterStatusRead: (() => void) | undefined
   beforeProbe: (() => void) | undefined
@@ -222,6 +223,7 @@ class FakeSandbox {
           this.statusError = undefined
           throw error
         }
+        this.statusReads += 1
         this.afterStatusRead?.()
         return this.exitStatus
       },
@@ -415,9 +417,10 @@ describe('E2BSubprocessHandle', () => {
     expect(command).not.toContain('explicit-secret')
     expect(command).not.toContain('hyphen-value')
     expect(command).not.toContain('${!dsh_e2b_name}')
-    expect(fake.commandsSeen).toContain(
-      'set -o pipefail; printf \'%s\' "$PWD" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
-    )
+    const environmentProbe = fake.commandsSeen.find(value => value.includes('env -0 | base64'))
+    expect(environmentProbe).toContain('getent passwd "$(id -u)"')
+    expect(environmentProbe).toContain('test -n "$dsh_e2b_home" -a -d "$dsh_e2b_home"')
+    expect(environmentProbe).not.toContain('"$PWD"')
     expect(command).toContain('mapfile -d')
     expect(command).toContain('dsh_e2b_node="$(command -v node)"')
     expect(command).toContain('"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e')
@@ -535,11 +538,13 @@ describe('E2BSubprocessHandle', () => {
     await new Promise(resolve => setTimeout(resolve, 50))
     expect(settled).toBe(false)
     expect(fake.handle.disconnects).toBe(0)
+    expect(fake.statusReads).toBe(0)
 
     await fake.stdout('complete protocol frame')
     fake.finish()
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
     expect(output).toBe('complete protocol frame')
+    expect(fake.statusReads).toBe(1)
   })
 
   it('accepts clean encoder completion inside the output-drain grace', async () => {
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 6c3ef477af..a4f4008a56 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -102,6 +102,9 @@ class FakeTerminalSandbox {
   sendError: unknown
   commandFailure: unknown
   makeDirRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
+  sendInputRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
+  foregroundRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
+  signalRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
   sessionGroupsFailure: unknown
   foregroundFailure: unknown
   termFailure: unknown
@@ -180,6 +183,8 @@ class FakeTerminalSandbox {
           return { exitCode: 0, stdout: this.sessionId, stderr: '' }
         }
         if (command.startsWith('ps -o tpgid=')) {
+          await this.foregroundRequest?.(options?.signal)
+          options?.signal?.throwIfAborted()
           if (this.foregroundFailure !== undefined) throw this.foregroundFailure
           return { exitCode: 0, stdout: this.foreground, stderr: '' }
         }
@@ -197,6 +202,10 @@ class FakeTerminalSandbox {
             this.handle.fail(143)
           }
         }
+        if (command.startsWith('kill -INT -- ')) {
+          await this.signalRequest?.(options?.signal)
+          options?.signal?.throwIfAborted()
+        }
         if (command.startsWith('kill -KILL -- ') && this.clearOnKill) this.groups = []
         return { exitCode: 0, stdout: '', stderr: '' }
       },
@@ -211,6 +220,8 @@ class FakeTerminalSandbox {
         return this.handle.asHandle()
       },
       sendInput: async (pid: number, data: Uint8Array, options?: { signal?: AbortSignal }): Promise<void> => {
+        options?.signal?.throwIfAborted()
+        await this.sendInputRequest?.(options?.signal)
         options?.signal?.throwIfAborted()
         this.inputs.push({ pid, data: Buffer.from(data) })
         if (this.sendError !== undefined) throw this.sendError
@@ -257,6 +268,19 @@ function spec(overrides: Partial<SubprocessTerminalSpawnSpec> = {}): SubprocessT
   }
 }
 
+function holdRequestUntilAbort(started: PromiseWithResolvers<AbortSignal>) {
+  return async (signal: AbortSignal | undefined): Promise<void> => {
+    if (signal === undefined) throw new Error('expected an operation signal')
+    signal.throwIfAborted()
+    started.resolve(signal)
+    await new Promise<void>((_resolve, reject) => {
+      signal.addEventListener('abort', () => {
+        reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+      }, { once: true })
+    })
+  }
+}
+
 describe('E2B terminal allocation', () => {
   it('hides bootstrap-shell bytes and preserves requested-shell bytes across the output boundary', async () => {
     const fake = new FakeTerminalSandbox()
@@ -544,6 +568,43 @@ describe('E2B terminal allocation', () => {
 })
 
 describe('E2B terminal lifecycle', () => {
+  it('aborts and joins in-flight terminal operations before cleanup', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/in-flight-operations')
+    const writeStarted = Promise.withResolvers<AbortSignal>()
+    const inspectStarted = Promise.withResolvers<AbortSignal>()
+    const signalStarted = Promise.withResolvers<AbortSignal>()
+    fake.sendInputRequest = holdRequestUntilAbort(writeStarted)
+    let foregroundRequests = 0
+    fake.foregroundRequest = async (signal) => {
+      foregroundRequests += 1
+      if (foregroundRequests === 1) await holdRequestUntilAbort(inspectStarted)(signal)
+    }
+    let signalCompleted = false
+    fake.signalRequest = async (operationSignal) => {
+      await holdRequestUntilAbort(signalStarted)(operationSignal)
+      signalCompleted = true
+    }
+    const write = terminal.write('late input')
+    const inspect = terminal.inspectForeground()
+    await Promise.all([writeStarted.promise, inspectStarted.promise])
+    const signal = terminal.signalForeground('SIGINT')
+    await signalStarted.promise
+
+    const terminating = terminal.terminate()
+    await expect(write).rejects.toThrow('terminal is terminating')
+    await expect(inspect).rejects.toThrow('terminal is terminating')
+    await expect(signal).rejects.toThrow('terminal is terminating')
+    await terminating
+    expect(signalCompleted).toBe(false)
+    expect(fake.inputs).toHaveLength(1)
+    const commandCount = fake.commands.length
+    await expect(terminal.write('after termination')).rejects.toThrow('terminal is terminating')
+    await expect(terminal.inspectForeground()).rejects.toThrow('terminal is terminating')
+    await expect(terminal.signalForeground('SIGINT')).rejects.toThrow('terminal is terminating')
+    expect(fake.commands).toHaveLength(commandCount)
+  })
+
   it('maps ordinary exits, closes output, and reports an absent foreground after exit', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []

From e8d55999456164af0a9842d0f103c2a9b77916ec Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 23:53:20 +0800
Subject: [PATCH 382/516] refactor(e2b): narrow settlement polling helper

---
 packages/e2b/subprocess-e2b/src/process.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 83dedd4e97..5e383a50e2 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -84,10 +84,10 @@ type CommandSettlement =
   | { kind: 'result'; result: CommandResult }
   | { kind: 'error'; error: unknown }
 
-function withinMs<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined> {
-  return new Promise<T | undefined>((resolve) => {
+function withinMs(settlement: Promise<CommandSettlement>, timeoutMs: number): Promise<CommandSettlement | undefined> {
+  return new Promise<CommandSettlement | undefined>((resolve) => {
     const timer = setTimeout(() => { resolve(undefined) }, timeoutMs)
-    void promise.then((value) => {
+    void settlement.then((value) => {
       clearTimeout(timer)
       resolve(value)
     })
@@ -563,8 +563,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         return { exitCode, signal: null }
       }
       if (completed !== undefined) return this.commandOutcome(completed)
-      // TODO(e2b-status-watch): Replace collect/inherit polling when E2B can
-      // observe direct-command exit independently of descendant-held output.
+      // TODO(e2b-status-watch): Replace collect/inherit control-plane polling
+      // when E2B can observe direct-command exit independently of descendant-held output.
       completed = await Promise.race([settlement, waitTick().then(() => undefined)])
     }
   }

From bb0be75d8549473996bbea3761897465e5a92141 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 29 Jul 2026 23:56:02 +0800
Subject: [PATCH 383/516] refactor(e2b): drop obsolete host sandbox overlay

---
 examples/headless-agent/e2b.cordis.snapshot.yml           | 2 --
 examples/headless-agent/e2b.cordis.yml                    | 2 --
 examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml | 3 ---
 3 files changed, 7 deletions(-)

diff --git a/examples/headless-agent/e2b.cordis.snapshot.yml b/examples/headless-agent/e2b.cordis.snapshot.yml
index 3f39f0ffe4..936aab290d 100644
--- a/examples/headless-agent/e2b.cordis.snapshot.yml
+++ b/examples/headless-agent/e2b.cordis.snapshot.yml
@@ -29,8 +29,6 @@
             name: '@deepseek-ai/dsh-code-runtime-subprocess'
           - id: tool-cordis
             name: '@deepseek-ai/dsh-tool-cordis'
-          - id: sandbox
-            name: '@deepseek-ai/dsh-sandbox-local'
           - id: sandbox-policy
             name: '@deepseek-ai/dsh-sandbox-policy'
             config:
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index 32d7049c5d..683bb7a0d4 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -34,8 +34,6 @@
             name: '@deepseek-ai/dsh-fs-e2b'
           - id: code-runtime-subprocess
             name: '@deepseek-ai/dsh-code-runtime-subprocess'
-          - id: sandbox
-            name: '@deepseek-ai/dsh-sandbox-local'
           - id: sandbox-policy
             name: '@deepseek-ai/dsh-sandbox-policy'
             config:
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index d2b73c1077..4132f4d1d6 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -21,9 +21,6 @@
 - id: agents
   name: '@deepseek-ai/dsh-agent'
 
-- id: sandbox
-  name: '@deepseek-ai/dsh-sandbox-local'
-
 - id: sandbox-policy
   name: '@deepseek-ai/dsh-sandbox-policy'
   config:

From de77310c6f68bafc6593dd37f134fd282bcbdd7b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 04:25:47 +0800
Subject: [PATCH 384/516] refactor(e2b): narrow the sandbox POC

---
 ...rtable-execution-world-consumers.i18n.yaml |   4 +-
 ...7-28-portable-execution-world-consumers.md |   8 +-
 ...8-portable-execution-world-consumers.zh.md |   8 +-
 AGENTS.md                                     |   7 +-
 docs/cordis-catalog/services.md               |   8 +-
 .../headless-agent/e2b.cordis.snapshot.yml    |  56 -----
 examples/headless-agent/e2b.cordis.yml        |   7 -
 .../tests/fixtures/e2b/e2b/bin.ts             | 215 +-----------------
 .../tests/fixtures/e2b/e2b/cordis.yml         |   4 -
 .../headless-agent/tests/headless.snapshot.ts |  56 -----
 .../tests/snapshots/e2b-overlay/input.json    |   8 -
 .../e2b-overlay/replay.override.json          |  12 -
 .../e2b-overlay/stream-json.expected.jsonl    |  14 --
 packages/e2b/README.i18n.yaml                 |   4 +-
 packages/e2b/README.md                        |   2 +-
 packages/e2b/README.zh.md                     |   2 +-
 packages/e2b/e2b/README.i18n.yaml             |   4 +-
 packages/e2b/e2b/README.md                    |  18 +-
 packages/e2b/e2b/README.zh.md                 |  18 +-
 packages/e2b/e2b/package.json                 |   2 -
 packages/e2b/e2b/src/index.ts                 | 146 +++---------
 packages/e2b/e2b/tests/composition.e2e.ts     |  51 +----
 packages/e2b/e2b/tests/e2b.spec.ts            | 122 +---------
 packages/e2b/fs-e2b/README.i18n.yaml          |   4 +-
 packages/e2b/fs-e2b/README.md                 |   4 +-
 packages/e2b/fs-e2b/README.zh.md              |   4 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  |   1 -
 packages/e2b/subprocess-e2b/README.i18n.yaml  |   4 +-
 packages/e2b/subprocess-e2b/README.md         |  11 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  11 +-
 packages/e2b/subprocess-e2b/src/index.ts      |  13 +-
 packages/e2b/subprocess-e2b/src/output.ts     |   3 -
 packages/e2b/subprocess-e2b/src/process.ts    |  59 ++---
 packages/e2b/subprocess-e2b/src/terminal.ts   |  72 ++----
 .../subprocess-e2b/tests/subprocess.spec.ts   |   4 -
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  85 ++-----
 pnpm-lock.yaml                                |   6 +-
 37 files changed, 176 insertions(+), 881 deletions(-)
 delete mode 100644 examples/headless-agent/e2b.cordis.snapshot.yml
 delete mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/input.json
 delete mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
 delete mode 100644 examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index fc3b5b012f..c7ce82595d 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 250445cfed6a4fe2dd188562813d586df29992c1
-2026-07-28-portable-execution-world-consumers.zh.md: 361c4de4e813aa7f57a7eb5acc75087b2630db43
+2026-07-28-portable-execution-world-consumers.md: 57c3a8a8b211279593359b02def865644052f549
+2026-07-28-portable-execution-world-consumers.zh.md: 8231913c26f75361add7a28bc40f7723c9b18728
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 4c593604f4..6f296bfa74 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -28,17 +28,17 @@ Generic consumers use that execution world:
 
 ## E2B POC boundary
 
-The opt-in E2B realization has exactly three provider-specific packages under `packages/e2b/`: `dsh-e2b` creates or reconnects one sandbox and owns kill/pause/leave disposal, `dsh-fs-e2b` implements `ctx.fs`, and `dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, PTYs, and remote Linux process groups. The two adapters obtain the sole sandbox identity from the owner and never create private sandboxes.
+The opt-in E2B realization has exactly three provider-specific packages under `packages/e2b/`: `dsh-e2b` creates one sandbox and deletes it on timeout or disposal, `dsh-fs-e2b` implements `ctx.fs`, and `dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, PTYs, and remote Linux process groups. The two adapters obtain the sole SDK handle from the owner and never create private sandboxes.
 
 E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, subprocess Code Runtime processes, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, Code Runtime program/binding/output policy, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
 
 The adapters retain only substrate mechanics. Filesystem canonicalization crosses the SDK's decoded command transport as strict base64-encoded NUL framing; streamed reads leave byte ceilings with consumers. Subprocess command output and environment snapshots use ASCII/base64 where SDK chunk decoding would otherwise lose bytes, while private control shells isolate profiles and later launches blank discovered credential-shaped names. Process and terminal cleanup uses remote groups and proves quiescence before settlement.
 
-Retaining a sandbox preserves remote files and unmanaged state only. Reconnect does not reconstruct host process or terminal handles, protocol connections, pending calls, output cursors, timers, or locks. The POC adds no session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, workspace synchronization, durable remote handles, or whole-harness execution.
+Sandbox state is deliberately ephemeral: timeout and disposal delete the remote files and unmanaged state. The POC adds no reconnect or pause/leave retention, session-persistence backend, template builder, volume, snapshot, network-policy layer, sandbox catalog, workspace synchronization, durable remote handles, or whole-harness execution.
 
 ## Verification
 
-Focused package suites pin sandbox lifecycle, canonical path framing, filesystem metadata and atomic versions, subprocess publication/rollback, terminal text I/O and session cleanup, output limits, cancellation, disposal, and invariant registration. A credential-gated Loader composition exercises the same three-package provider through source imports and built exports, including FS/Bash visibility, post-rename version reread plus guarded edit, hostile login profiles, byte-split UTF-8 output, process and terminal cleanup, LSP document bounds, Code Runtime bindings/limits/cleanup, host-workspace isolation, and final sandbox deletion.
+Focused package suites pin sandbox lifecycle, canonical path framing, filesystem metadata and atomic versions, subprocess publication/rollback, terminal text I/O and session cleanup, output limits, cancellation, disposal, and invariant registration. A credential-gated Loader composition exercises the same three-package provider through source imports and built exports, including FS/Bash visibility, hostile login profiles, byte-split UTF-8 output, process and terminal cleanup, LSP queries, Code Runtime bindings and cleanup, host-workspace isolation, and final sandbox deletion.
 
 ## Alternatives considered
 
@@ -70,4 +70,4 @@ The fundamental interfaces are wider, and a filesystem/subprocess pair must agre
 
 The local implementation absorbs `node-pty` and platform process inspection because it owns local terminal mechanics. This moves code without weakening terminal teardown: disposal sweeps descendants before and after terminating the top-level shell, waits for exact PID-identity-fenced descendants retained during foreground inspection, and retains Linux session members that survive top-level exit. macOS cannot enumerate a POSIX session after its leader exits, so a child that reparents between inspection snapshots remains an explicit local-provider limitation rather than a reason to move process mechanics back into the PTY consumer.
 
-The E2B composition demonstrates that a shared sandbox owner plus filesystem and subprocess adapters are sufficient to move the mutable coding world off-host while leaving higher capabilities provider-neutral. Its POC limits remain explicit: the SDK retains complete command transport in host memory, remote startup cannot publish a PID synchronously, exact terminal stdin-wait and independent signal facts are unavailable, numeric PID/PGID operations are not identity-fenced, the initial environment probe cannot hide unknown sandbox-default secrets from already-running same-UID processes, retained artifacts accumulate, and escaped processes or reconnect state are not recovered. These are provider constraints, not justification for compatibility shims or more E2B packages.
+The E2B composition demonstrates that a shared sandbox owner plus filesystem and subprocess adapters are sufficient to move the mutable coding world off-host while leaving higher capabilities provider-neutral. Its POC limits remain explicit: the SDK retains complete command transport in host memory, remote startup cannot publish a PID synchronously, exact terminal stdin-wait and independent signal facts are unavailable, numeric PID/PGID operations are not identity-fenced, the initial environment probe cannot hide unknown sandbox-default secrets from already-running same-UID processes, and adapter artifacts remain until sandbox deletion. These are provider constraints, not justification for compatibility shims or more E2B packages.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 361c4de4e8..471753573d 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -31,17 +31,17 @@ Status: implemented
 
 ## E2B POC 边界
 
-可选启用的 E2B 实现在 `packages/e2b/` 下恰好只有三个提供方专用包：`dsh-e2b` 创建或重新连接一个沙箱，并负责 kill、pause 或 leave 资源释放；`dsh-fs-e2b` 实现 `ctx.fs`；`dsh-subprocess-e2b` 基于 E2B Commands、PTY 和远程 Linux 进程组实现 `ctx.subprocess`。两个适配器都从所有者取得唯一的沙箱身份，绝不创建私有沙箱。
+可选启用的 E2B 实现在 `packages/e2b/` 下恰好只有三个提供方专用包：`dsh-e2b` 创建一个沙箱，并在超时或资源释放时将其删除；`dsh-fs-e2b` 实现 `ctx.fs`；`dsh-subprocess-e2b` 基于 E2B Commands、PTY 和远程 Linux 进程组实现 `ctx.subprocess`。两个适配器都从所有者取得唯一的 SDK 句柄，绝不创建私有沙箱。
 
 E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取、子进程代码运行时进程，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态、代码运行时程序／绑定／输出策略，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
 
 适配器只保留执行基底机制。文件系统规范化以严格的 base64 加 NUL 分帧穿过 SDK 已解码的命令传输；流式读取把字节上限留给消费方执行。进程管理命令输出与环境快照采用 ASCII/base64，避免 SDK 分片解码丢失字节；私有控制 shell 隔离 profile，后续启动会把已发现且名称呈凭据特征的环境变量置空。进程与终端清理使用远程进程组，并在结算前证明完全停稳。
 
-保留沙箱只会保留远程文件与非托管状态。重新连接不会重建宿主进程或终端句柄、协议连接、待处理调用、输出游标、计时器或锁。该 POC 不会新增会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录、工作区同步、持久远程句柄，也不会在其中运行整个 harness。
+沙箱状态有意保持短暂：超时与资源释放会删除远程文件和非托管状态。该 POC 不提供重新连接、pause/leave 保留、会话持久化后端、模板构建器、卷、快照、网络策略层、沙箱目录、工作区同步、持久远程句柄，也不会在其中运行整个 harness。
 
 ## 验证
 
-聚焦的包测试套件锁定了沙箱生命周期、规范化路径分帧、文件系统元数据与原子版本、进程管理发布／回滚、终端文本 I/O 与会话清理、输出上限、取消、资源释放和不变式注册。一项受凭据门控的 Loader 组合通过源代码导入与构建后导出运行同一套三包提供方组合，其中包括 FS/Bash 可见性、重命名后的版本重读与带保护编辑、恶意登录 profile、跨字节边界拆分的 UTF-8 输出、进程与终端清理、LSP 文档上限、代码运行时绑定／上限／清理、宿主工作区隔离，以及最终沙箱删除。
+聚焦的包测试套件锁定了沙箱生命周期、规范化路径分帧、文件系统元数据与原子版本、进程管理发布／回滚、终端文本 I/O 与会话清理、输出上限、取消、资源释放和不变式注册。一项受凭据门控的 Loader 组合通过源代码导入与构建后导出运行同一套三包提供方组合，其中包括 FS/Bash 可见性、恶意登录 profile、跨字节边界拆分的 UTF-8 输出、进程与终端清理、LSP 查询、代码运行时绑定与清理、宿主工作区隔离，以及最终沙箱删除。
 
 ## 考虑过的替代方案
 
@@ -75,4 +75,4 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 本地实现承接 `node-pty` 和平台进程检查，因为它负责本地终端机制。这种代码迁移不会削弱终端拆卸：dispose（资源释放）会在终止顶层 shell 前后清理后代进程，等待前台检查期间保留下来且受精确 PID 身份围栏保护的后代进程，并继续追踪在顶层进程退出后仍存活的 Linux 会话成员。macOS 无法在 POSIX 会话 leader 退出后枚举该会话，因此在两次检查快照之间重新设定父进程的子进程仍是明确的本地提供方限制，而不是把进程机制移回 PTY 消费方的理由。
 
-E2B 组合证明，共享沙箱所有者加上文件系统与进程管理适配器，就足以在保持上层能力与提供方无关的同时，把可变编码世界移出宿主。其 POC 限制仍明确在案：SDK 会把完整命令传输内容保留在宿主内存中；远程启动无法同步发布 PID；无法获得精确的终端 stdin 等待状态与独立信号事实；基于数值 PID/PGID 的操作没有身份围栏；初始环境探测无法向已在运行的同 UID 进程隐藏未知的沙箱默认 secret；保留的产物会累积；也不会恢复逃逸进程或重连状态。这些是提供方限制，不是引入兼容性 shim 或更多 E2B 包的理由。
+E2B 组合证明，共享沙箱所有者加上文件系统与进程管理适配器，就足以在保持上层能力与提供方无关的同时，把可变编码世界移出宿主。其 POC 限制仍明确在案：SDK 会把完整命令传输内容保留在宿主内存中；远程启动无法同步发布 PID；无法获得精确的终端 stdin 等待状态与独立信号事实；基于数值 PID/PGID 的操作没有身份围栏；初始环境探测无法向已在运行的同 UID 进程隐藏未知的沙箱默认 secret；适配器产物会一直保留到沙箱删除。这些是提供方限制，不是引入兼容性 shim 或更多 E2B 包的理由。
diff --git a/AGENTS.md b/AGENTS.md
index c663a5e099..1d2a6d977c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,8 +12,9 @@ DeepSeek Harness SDK is a plugin-based agent harness on vendored Cordis: **every
 vendor/      Vendored Cordis source — manifest + sync procedure in vendor/README.md
 packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
+  typert/      type graph generator, loader, and runtime registry
   llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
-  e2b/         remote-runtime POC
+  e2b/         E2B POC: sandbox owner + FS/subprocess adapters
   bash/        bash executor seam + local impl + model-facing bash tools
   subprocess/  subprocess seam + local process-tree impl
   pty/         persistent PTY seam/backend/tools
@@ -90,7 +91,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 ## Conventions
 
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
-- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. CI subprocesses that boot examples or Cordis configs run built `lib/` under plain Node; only explicit source-path regressions use tsx ([testing policy](docs/testing.md#test-subprocess-launch-modes)).
+- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only shapes) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). TUI/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
 - **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. If a package has no plausible relationship, an explained empty companion is correct ([package contract](packages/AGENTS.md)).
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns.
@@ -114,7 +115,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
-- **Use incremental merge commits.** Split independent changes; never squash, rebase, or rewrite pushed history. Fix the introducing PR before merging down-stack. If the base advances mid-merge, never restart: finish the checkpoint, push when authorized, then merge the newer tip separately ([rationale](.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)).
+- **Use incremental merge commits.** Split independent changes. Pushed history may be rewritten before review; afterward prefer new commits. Fix the introducing PR before merging down-stack. If the base advances mid-merge, finish the checkpoint, push when authorized, then merge the newer tip separately ([rationale](.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)).
 - **Label PRs:** one kind (`feature`/`bug-fix`/`doc`/`testing`/`cleanup`), each matching area; the [taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md) is extensible.
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 3942c0696d..db66ca5799 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -580,18 +580,18 @@ Source: [`packages/host/directory-picker/src/index.ts:131`](../../packages/host/
 
 ## `ctx.e2b` — `E2BSandboxService`
 
-Owns one lazily consumable E2B SDK handle and its final kill/pause/leave decision. The connection begins at plugin construction; adapters await getSandbox before their first operation.
+Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal. Creation begins at plugin construction; adapters await getSandbox before their first operation.
 
 ```ts cordis-catalog
 /**
  * Return the shared live SDK handle.
- * @returns the created or reconnected sandbox after the configured cwd exists.
- * @throws when E2B rejects creation/reconnection or the service is disposing.
+ * @returns the created sandbox after the configured cwd exists.
+ * @throws when E2B rejects creation or the service is disposing.
  */
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:108`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:76`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
diff --git a/examples/headless-agent/e2b.cordis.snapshot.yml b/examples/headless-agent/e2b.cordis.snapshot.yml
deleted file mode 100644
index 936aab290d..0000000000
--- a/examples/headless-agent/e2b.cordis.snapshot.yml
+++ /dev/null
@@ -1,56 +0,0 @@
-# Keyless counterpart to e2b.cordis.yml. It keeps the same generic PTY, LSP,
-# and subprocess Code Runtime consumers, but supplies their fundamental
-# filesystem/process world locally and replaces the live model with replay.
-- id: base
-  name: '@cordisjs/plugin-include'
-  config:
-    path: ./cordis.yml
-    patches:
-      - id: llm-deepseek
-        name: '@deepseek-ai/dsh-llm-deepseek'
-        disabled: true
-      - id: cli-agent
-        name: '@deepseek-ai/dsh-cli-demo'
-        config:
-          provider: deepseek
-          model: deepseek-v4-pro
-          persistenceRoot: './.sessions'
-          persistenceCompression: none
-          workspaceContext:
-            maxBytes: 65536
-          tools:
-            mode: both
-          persona: |
-            You are headless-agent, a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}.
-
-            Verify your work by running the code or tests. Keep answers brief and factual.
-      - insert:
-          - id: code-runtime-subprocess
-            name: '@deepseek-ai/dsh-code-runtime-subprocess'
-          - id: tool-cordis
-            name: '@deepseek-ai/dsh-tool-cordis'
-          - id: sandbox-policy
-            name: '@deepseek-ai/dsh-sandbox-policy'
-            config:
-              mode: danger-full-access
-              workspaceRoot: !!js process.cwd()
-          - id: pty
-            name: '@deepseek-ai/dsh-pty'
-          - id: pty-local
-            name: '@deepseek-ai/dsh-pty-local'
-          - id: tool-pty
-            name: '@deepseek-ai/dsh-tool-pty'
-          - id: lsp
-            name: '@deepseek-ai/dsh-lsp'
-          - id: lsp-local
-            name: '@deepseek-ai/dsh-lsp-local'
-            config:
-              servers:
-                typescript:
-                  command: node
-                  extensionToLanguage:
-                    .ts: typescript
-          - id: tool-lsp
-            name: '@deepseek-ai/dsh-tool-lsp'
-          - id: llm-replay
-            name: '@deepseek-ai/dsh-llm-replay'
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index 683bb7a0d4..724f30240d 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -15,19 +15,12 @@
       - id: code-runtime
         name: '@deepseek-ai/dsh-code-runtime-worker'
         disabled: true
-      - id: bash
-        name: '@deepseek-ai/dsh-bash-local'
-        config:
-          cwd: !!js process.cwd()
-          timeoutMs: 60000
       - insert:
           - id: e2b
             name: '@deepseek-ai/dsh-e2b'
             config:
               cwd: !!js process.cwd()
               timeoutMs: 300000
-              onTimeout: kill
-              onDispose: kill
           - id: subprocess-e2b
             name: '@deepseek-ai/dsh-subprocess-e2b'
           - id: fs-e2b
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 856a26ed78..570a244e88 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -1,10 +1,9 @@
 import { readFile } from 'node:fs/promises'
-import { posix, resolve } from 'node:path'
+import { resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-code-runtime-subprocess'
-import { quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
 import type {} from '@deepseek-ai/dsh-bash-local'
 import type {} from '@deepseek-ai/dsh-lsp-local'
@@ -36,18 +35,17 @@ try {
   const sandbox = await ctx.e2b.getSandbox()
   const fromFs = await ctx.fs.resolve('from-fs.txt')
   const written = await ctx.fs.writeText(fromFs, 'written-by-fs\n', { kind: 'createIfAbsent' })
-  const reread = await ctx.fs.stat(fromFs)
-  if (reread?.version !== written.version) {
-    throw new Error(`E2B rename did not preserve version metadata: ${JSON.stringify({ written, reread })}`)
+  const observed = await ctx.fs.stat(fromFs)
+  if (observed?.version !== written.version) {
+    throw new Error(`E2B rename did not preserve version metadata: ${JSON.stringify({ written, observed })}`)
   }
   await ctx.fs.editText(
     fromFs,
-    { oldString: 'written-by-fs', newString: 'written-by-fs-versioned', replaceAll: false },
-    { version: reread.version },
+    { oldString: 'written-by-fs', newString: 'versioned-by-fs', replaceAll: false },
+    { version: observed.version },
   )
-  const fsVersionGuard = true
   const bashRead = await ctx.bash.run(ctx.bash.resolve({ command: 'cat from-fs.txt' }))
-  if (bashRead.exitCode !== 0 || bashRead.stdout.text !== 'written-by-fs-versioned\n') {
+  if (bashRead.exitCode !== 0 || bashRead.stdout.text !== 'versioned-by-fs\n') {
     throw new Error(`E2B Bash could not read the FS write: ${JSON.stringify(bashRead)}`)
   }
 
@@ -114,67 +112,11 @@ try {
   )
   if (outputDrainOutcome.exitCode !== 0 || outputDrainText !== 'leader-done\n'
     || outputDrainElapsedMs >= 10_000 || !outputDrainExited || !outputDrainClean) {
-    throw new Error(`E2B subprocess output drain was not bounded: ${JSON.stringify({
+    throw new Error(`E2B subprocess did not bound descendant-held output: ${JSON.stringify({
       outputDrainOutcome, outputDrainText, outputDrainElapsedMs, outputDrainExited, outputDrainClean,
     })}`)
   }
 
-  const remoteFiles = sandbox.files as unknown as {
-    read(path: string, options?: unknown): Promise<unknown>
-  }
-  const readRemoteFile = remoteFiles.read.bind(sandbox.files)
-  let publicationFaultInjected = false
-  remoteFiles.read = async (path, options) => {
-    if (!publicationFaultInjected && path.includes('/processes/') && path.endsWith('/pid')) {
-      publicationFaultInjected = true
-      throw new Error('injected process-group publication read failure')
-    }
-    return await readRemoteFile(path, options)
-  }
-  let publicationRollback = false
-  try {
-    const unpublished = ctx.subprocess.spawn({
-      argv: ['bash', '-c', 'exec -a dsh-publication-survivor sleep 30 & wait'],
-      cwd: process.cwd(),
-      stdio: { stdin: 'ignore', stdout: { maxBytes: 4_096 }, stderr: { maxBytes: 4_096 } },
-      graceMs: 500,
-      env: {},
-    })
-    await unpublished.done
-    throw new Error('E2B subprocess unexpectedly survived an injected publication failure')
-  } catch (error: unknown) {
-    if (!String(error).includes('injected process-group publication read failure')) throw error
-    const processes = await sandbox.commands.run('ps -eo args=')
-    publicationRollback = publicationFaultInjected && !processes.stdout.includes('dsh-publication-survivor')
-    if (!publicationRollback) throw new Error('E2B subprocess publication rollback left its remote process group alive')
-  } finally {
-    remoteFiles.read = readRemoteFile
-  }
-
-  const spillHandle = ctx.subprocess.spawn({
-    argv: ['bash', '-c', "printf '0123456789'; sleep 30"],
-    cwd: process.cwd(),
-    stdio: { stdin: 'ignore', stdout: { maxBytes: 4, spill: { maxBytes: 6 } }, stderr: { maxBytes: 4_096 } },
-    graceMs: 500,
-    env: {},
-  })
-  const spillReader = spillHandle.collected.stdout
-  if (spillReader === undefined) throw new Error('E2B subprocess omitted its configured stdout collector')
-  const spillDeadline = Date.now() + 15_000
-  while (spillReader.readFrom(0).nextOffset < 10) {
-    if (Date.now() >= spillDeadline) throw new Error('E2B subprocess did not stream the spill probe output')
-    await new Promise(resolveDelay => setTimeout(resolveDelay, 20))
-  }
-  const spillPath = posix.join((spillHandle as unknown as { stateDir: string }).stateDir, 'stdout.log')
-  const liveSpillBytes = (await (await ctx.e2b.getSandbox()).files.getInfo(spillPath)).size
-  spillHandle.terminate()
-  const spillOutcome = await spillHandle.done
-  const spillExited = await spillHandle.waitForExit(AbortSignal.timeout(5_000))
-  const spillRead = spillReader.readFrom(0)
-  if (liveSpillBytes !== 6 || !spillExited || spillRead.spillPath !== undefined) {
-    throw new Error(`E2B subprocess spill bound failed: ${JSON.stringify({ liveSpillBytes, spillExited, spillRead })}`)
-  }
-
   const lspFixture = await readFile(new URL('./fixture-lsp.mjs', import.meta.url), 'utf8')
   const remoteLspFixture = await ctx.fs.resolve('fixture-lsp.mjs')
   await ctx.fs.writeText(remoteLspFixture, lspFixture, { kind: 'createIfAbsent' })
@@ -193,53 +135,12 @@ try {
     workspaceRoot: process.cwd(),
   })
 
-  const oversizedSourcePath = posix.join(process.cwd(), 'oversized-source.ts')
-  await sandbox.commands.run(`head -c 4000001 /dev/zero | tr '\\0' x > ${quoteE2BShellArg(oversizedSourcePath)}`)
-  let lspDocumentBound = false
-  try {
-    await ctx.lsp.query({
-      operation: 'hover',
-      filePath: 'oversized-source.ts',
-      position: { line: 0, character: 0 },
-      workspaceRoot: process.cwd(),
-    })
-  } catch (error: unknown) {
-    lspDocumentBound = String(error).includes('exceeds the 4000000-byte limit')
-    if (!lspDocumentBound) throw error
-  }
-  if (!lspDocumentBound) throw new Error('E2B LSP accepted an oversized remote source')
-
-  const remoteCommands = sandbox.commands as unknown as {
-    run(command: string, options?: unknown): Promise<{ exitCode: number; stdout: string; stderr: string }>
-  }
-  const runRemoteCommand = remoteCommands.run.bind(sandbox.commands)
   const terminal = await ctx.pty.spawn(owner, { type: 'shell' })
   terminalId = terminal.sessionId
   const terminalEcho = await ctx.pty.startSend(owner, terminal.sessionId, {
     text: "printf 'PTY-你好\\n'",
     submit: true,
   }).done
-  const foregroundLookup = Promise.withResolvers<undefined>()
-  let delayedForegroundLookup = false
-  remoteCommands.run = async (command, options) => {
-    if (!delayedForegroundLookup && command.startsWith('ps -o tpgid=')) {
-      delayedForegroundLookup = true
-      await foregroundLookup.promise
-    }
-    return await runRemoteCommand(command, options)
-  }
-  const staleInterrupt = ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 0.2', submit: true })
-  if (!staleInterrupt.cancel()) throw new Error('E2B PTY refused the stale-interrupt probe cancellation')
-  let canceledSendRetained = false
-  try {
-    ctx.pty.startSend(owner, terminal.sessionId, { text: 'sleep 30', submit: true })
-  } catch (error: unknown) {
-    canceledSendRetained = String(error).includes('active send')
-  }
-  foregroundLookup.resolve(undefined)
-  await staleInterrupt.done
-  remoteCommands.run = runRemoteCommand
-  if (!canceledSendRetained) throw new Error('E2B PTY released a canceled send before foreground signalling settled')
   const sleeping = ctx.pty.startSend(owner, terminal.sessionId, {
     text: "printf 'DSH_SLEEP_%s\\n' READY; sleep 30",
     submit: true,
@@ -258,13 +159,6 @@ try {
     }
     if (Date.now() >= sleepReadyDeadline) throw new Error(`E2B PTY successor did not execute: ${sleepReadyOutput}`)
   }
-  const interruptIdentitySafe = await Promise.race([
-    sleeping.done.then(() => false),
-    new Promise<true>(resolveDelay => setTimeout(() => { resolveDelay(true) }, 300)),
-  ])
-  if (!delayedForegroundLookup || !interruptIdentitySafe) {
-    throw new Error('E2B PTY stale interrupt affected its successor send')
-  }
   const terminalSignal = await ctx.pty.signal(owner, terminal.sessionId, 'SIGINT')
   const interrupted = await sleeping.done
   const stubborn = await ctx.pty.startSend(owner, terminal.sessionId, {
@@ -284,24 +178,6 @@ try {
   const code = await ctx.codeRuntime.run({
     program: `
       console.log('remote-log 你好', 42)
-      const arrayPrototype = Array.prototype
-      const objectPrototype = Object.prototype
-      const setPrototype = Set.prototype
-      const stringPrototype = String.prototype
-      Array.isArray = () => false
-      Object.defineProperty = Object.getPrototypeOf = Object.keys = () => { throw new Error('mutated object method') }
-      Object.hasOwn = () => false
-      Object.is = () => true
-      objectPrototype.propertyIsEnumerable = () => false
-      Number.isFinite = Number.isSafeInteger = () => false
-      Reflect.apply = Reflect.ownKeys = () => { throw new Error('mutated reflect method') }
-      setPrototype.add = setPrototype.delete = setPrototype.has = () => { throw new Error('mutated set method') }
-      stringPrototype.charCodeAt = stringPrototype.codePointAt = stringPrototype.slice = () => { throw new Error('mutated string method') }
-      Buffer.byteLength = () => 0
-      Function.prototype.toString = () => 'mutated'
-      objectPrototype.constructor = arrayPrototype.constructor = null
-      globalThis.Array = globalThis.Buffer = globalThis.Function = globalThis.Number = globalThis.Object = globalThis.Promise = globalThis.Reflect = globalThis.Set = globalThis.String = undefined
-      process.stdout.write('post-mutation', () => {})
       const doubled: number = await bridge.double({ value: 21 })
       let typed = false
       try {
@@ -323,42 +199,6 @@ try {
       },
     }],
   })
-  const hostileOutput = await ctx.codeRuntime.run({
-    program: `
-      const payload = '🙂'.repeat(4096)
-      String.prototype[Symbol.iterator] = () => { throw new Error('mutated string iterator') }
-      console.log(payload)
-      return true
-    `,
-    bindings: [],
-  })
-  const nativeOutput = await ctx.codeRuntime.run({
-    program: `
-      let stdoutPrototype = Object.getPrototypeOf(process.stdout)
-      while (stdoutPrototype && !Object.hasOwn(stdoutPrototype, 'write')) stdoutPrototype = Object.getPrototypeOf(stdoutPrototype)
-      Reflect.apply(stdoutPrototype.write, process.stdout, ['x'.repeat(8192)])
-      return true
-    `,
-    bindings: [],
-  })
-  const descriptorOutput = await ctx.codeRuntime.run({
-    program: `
-      const fs = await import('node:fs')
-      const forged = Buffer.from(JSON.stringify({ type: 'done' })).toString('base64') + '\\n'
-      fs.writeSync(1, forged)
-      fs.writeSync(1, 'x'.repeat(8192))
-      return true
-    `,
-    bindings: [],
-  })
-  const inheritedOutput = await ctx.codeRuntime.run({
-    program: `
-      const childProcess = await import('node:child_process')
-      childProcess.spawnSync(process.execPath, ['-e', 'process.stdout.write("x".repeat(8192))'], { stdio: 'inherit' })
-      return true
-    `,
-    bindings: [],
-  })
   const descendantPipe = await ctx.codeRuntime.run({
     program: `
       const childProcess = await import('node:child_process')
@@ -376,67 +216,30 @@ try {
     JSON.stringify([processInfo.cmd, processInfo.args]).includes('dsh-code-runtime-descendant'),
   )
   if (!descendantCleanup) throw new Error('E2B Code Runtime left a pipe-holding descendant alive')
-  const timedOut = await ctx.codeRuntime.run({
-    program: 'await new Promise(() => {})',
-    bindings: [],
-  })
-  const abortController = new AbortController()
-  const aborting = ctx.codeRuntime.run({
-    program: 'await new Promise(() => {})',
-    bindings: [],
-    signal: abortController.signal,
-  })
-  setTimeout(() => { abortController.abort('live abort') }, 50)
-  const aborted = await aborting
-  const oversizedBoot = await ctx.codeRuntime.run({
-    program: `return ${JSON.stringify('x'.repeat(40_000))}`,
-    bindings: [],
-  })
-  const oversizedReply = await ctx.codeRuntime.run({
-    program: 'return await bridge.large(null)',
-    bindings: [{
-      global: 'bridge',
-      functions: { large: async () => 'x'.repeat(40_000) },
-    }],
-  })
   const remoteProcesses = await (await ctx.e2b.getSandbox()).commands.list()
   const lingeringCodeRunners = remoteProcesses.filter(processInfo =>
     JSON.stringify([processInfo.cmd, processInfo.args]).includes('code-runtime-runner.mjs'),
   )
 
   process.stdout.write(`${JSON.stringify({
-    sandboxId: await ctx.e2b.sandboxId,
+    sandboxId: (await ctx.e2b.getSandbox()).sandboxId,
     bashRead: bashRead.stdout.text,
-    fsVersionGuard,
     fsRead,
     explicitEnvironment,
     splitUtf8Output,
-    outputDrain: { outcome: outputDrainOutcome, text: outputDrainText, exited: outputDrainExited, clean: outputDrainClean },
-    publicationRollback,
-    spill: { liveBytes: liveSpillBytes, outcome: spillOutcome, read: spillRead },
     hover,
     definition,
-    lspDocumentBound,
     terminal: {
       motd: terminal.motd,
       echo: terminalEcho,
       signal: terminalSignal,
       interrupted,
-      interruptIdentitySafe,
       treeCleanup: terminalTreeCleanup,
       scrollback: terminalScrollback.text,
     },
     code,
-    hostileOutput,
-    nativeOutput,
-    descriptorOutput,
-    inheritedOutput,
     descendantPipe,
     descendantCleanup,
-    timedOut,
-    aborted,
-    oversizedBoot,
-    oversizedReply,
     lingeringCodeRunners: lingeringCodeRunners.length,
   })}\n`)
 } finally {
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 4132f4d1d6..043362aaa1 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -3,8 +3,6 @@
   config:
     cwd: !!js process.cwd()
     timeoutMs: 180000
-    onTimeout: kill
-    onDispose: kill
 
 - id: subprocess-e2b
   name: '@deepseek-ai/dsh-subprocess-e2b'
@@ -12,7 +10,6 @@
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:
-    cwd: !!js process.cwd()
     timeoutMs: 30000
 
 - id: fs-e2b
@@ -63,5 +60,4 @@
     maxWallMs: 15000
     maxOutputBytes: 4096
     maxOldGenerationSizeMb: 128
-    maxFrameBytes: 32768
     killGraceMs: 500
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index ca8e93724c..87261439da 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -25,8 +25,6 @@ const advancedScenarioDir = join(snapshotsDir, 'advanced-toolchain')
 const advancedSessionFixture = join(advancedScenarioDir, 'session.jsonl')
 const advancedStreamExpected = join(advancedScenarioDir, 'stream-json.expected.jsonl')
 const advancedConfigPath = fileURLToPath(new URL('../advanced.cordis.snapshot.yml', import.meta.url))
-const e2bScenarioDir = join(snapshotsDir, 'e2b-overlay')
-const e2bConfigPath = fileURLToPath(new URL('../e2b.cordis.snapshot.yml', import.meta.url))
 const ptyScenarioDir = join(snapshotsDir, 'pty-tools')
 const ptySessionFixture = join(ptyScenarioDir, 'session.jsonl')
 const ptyStreamExpected = join(ptyScenarioDir, 'stream-json.expected.jsonl')
@@ -610,60 +608,6 @@ describe('headless stream-json snapshots', () => {
     expect(normalized).toBe(await readFile(advancedStreamExpected, 'utf8'))
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
-  it('pins the E2B overlay provider-neutral tool surface', async () => {
-    const prompt = await scenarioPrompt(e2bScenarioDir, 'e2b-overlay')
-    const streamExpected = join(e2bScenarioDir, 'stream-json.expected.jsonl')
-    let runCwd = ''
-    const result = await runLoaderSmoke({
-      label: 'E2B overlay headless stream-json snapshot',
-      tempDirPrefix: 'headless-snapshot-e2b-overlay-',
-      binScript,
-      configPath: e2bConfigPath,
-      binArgs: ['--config', e2bConfigPath, '--output-format', 'stream-json', prompt],
-      tsconfigPath,
-      env: {
-        DSH_SNAPSHOT: 'replay',
-        DSH_SNAPSHOT_FILE: join(e2bScenarioDir, 'session.jsonl'),
-        DSH_SNAPSHOT_OVERRIDE: join(e2bScenarioDir, 'replay.override.json'),
-        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
-      },
-      prepare: (cwd) => { runCwd = cwd },
-      inspect: async (cwd) => {
-        const logs = await persistedLogs(cwd)
-        expect(logs).toHaveLength(1)
-        const headers = parseJsonl(logs[0]?.content ?? '').filter(record => record.type === 'request/header')
-        expect(headers).toHaveLength(1)
-        const data = headers[0]?.data as JsonObject | undefined
-        const header = data?.header as JsonObject | undefined
-        if (!Array.isArray(header?.tools)) throw new Error('E2B overlay snapshot request has no tool schemas')
-        const toolNames = header.tools.map((tool, index) => {
-          if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) {
-            throw new Error(`E2B overlay snapshot tool schema ${index} is not an object`)
-          }
-          const name = (tool as JsonObject).name
-          if (typeof name !== 'string') throw new Error(`E2B overlay snapshot tool schema ${index} has no name`)
-          return name
-        })
-        expect(toolNames.filter(name => name === 'lsp' || name === 'run_code' || name.startsWith('terminal_')).sort())
-          .toEqual([
-            'lsp',
-            'run_code',
-            'terminal_close',
-            'terminal_list',
-            'terminal_open',
-            'terminal_read',
-            'terminal_send',
-            'terminal_signal',
-          ])
-      },
-    })
-
-    expect(result.stderr).toBe('')
-    const normalized = normalizeHeadlessStream(result.stdout, runCwd)
-    if (refreshing) await writeFile(streamExpected, normalized)
-    expect(normalized).toBe(await readFile(streamExpected, 'utf8'))
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
-
   it('replays persisted goal tools through the one-shot app', async () => {
     const prompt = await scenarioPrompt(goalScenarioDir, 'goal-tools')
     const streamExpected = join(goalScenarioDir, 'stream-json.expected.jsonl')
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/input.json b/examples/headless-agent/tests/snapshots/e2b-overlay/input.json
deleted file mode 100644
index 00fd27ce2e..0000000000
--- a/examples/headless-agent/tests/snapshots/e2b-overlay/input.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
-  "steps": [
-    {
-      "op": "prompt",
-      "text": "Report the assembled E2B overlay tool surface."
-    }
-  ]
-}
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json b/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
deleted file mode 100644
index d1a71ce58c..0000000000
--- a/examples/headless-agent/tests/snapshots/e2b-overlay/replay.override.json
+++ /dev/null
@@ -1,12 +0,0 @@
-[
-  {
-    "kind": "chunks",
-    "chunks": [
-      { "type": "block-start", "index": 0, "blockType": "text" },
-      { "type": "text-delta", "index": 0, "text": "E2B_SURFACE_OK" },
-      { "type": "block-end", "index": 0, "block": { "type": "text", "text": "E2B_SURFACE_OK" } },
-      { "type": "usage", "usage": { "inputTokens": 8, "outputTokens": 3 } },
-      { "type": "finish", "reason": { "kind": "stop" } }
-    ]
-  }
-]
diff --git a/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl
deleted file mode 100644
index 2fb74415cb..0000000000
--- a/examples/headless-agent/tests/snapshots/e2b-overlay/stream-json.expected.jsonl
+++ /dev/null
@@ -1,14 +0,0 @@
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Report the assembled E2B overlay tool surface."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"session/title","seq":2,"time":0,"data":{"title":"Report the assembled E2B overlay","messageSeqs":[1],"source":{"kind":"fallback"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-pro"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"E2B_SURFACE_OK"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"E2B_SURFACE_OK"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":8,"outputTokens":3}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":10,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"E2B_SURFACE_OK"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-pro"},"id":"{{sessionId}}"},"usage":{"inputTokens":8,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":11,"time":0,"data":{"turn":1,"step":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":12,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
-{"type":"result","success":true,"sessionId":"{{sessionId}}","turn":1,"result":"E2B_SURFACE_OK","reason":{"kind":"completed"},"usage":{"inputTokens":8,"outputTokens":3}}
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 2b6a8efb69..6b1dc7506b 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: cb733ba00d21070773ff9b381e4a72d9d3b9a8df
-README.zh.md: 29f8e58a0cdc59098cf8d74120cb360d11cfbcb3
+README.md: 3c85b2790d3414af73625e65732df58ff9fec566
+README.zh.md: a759539fc054dd68e75f3c7660ccc3b762985af5
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index cb733ba00d..3c85b2790d 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -6,7 +6,7 @@ An experimental provider-composition POC that places one filesystem/process exec
 
 | Package | ctx key | Role |
 |---|---|---|
-| [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create or reconnect one sandbox, create its working/runtime directories, expose the shared SDK handle, and apply the configured kill/pause/leave disposition |
+| [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create one sandbox, prepare its working/runtime directories, expose the shared SDK handle, and delete it on timeout or disposal |
 | [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
 | [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement executable lookup, managed process groups and stdio, remote spill files, and terminal sessions over E2B Commands and PTY APIs |
 
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index 29f8e58a0c..a759539fc0 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -6,7 +6,7 @@
 
 | 包（package） | ctx 键 | 职责 |
 |---|---|---|
-| [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建或重新连接一个沙箱，创建其工作目录与运行时目录，公开共享 SDK 句柄，并应用配置的 kill/pause/leave 处置方式 |
+| [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建一个沙箱，准备其工作目录与运行时目录，公开共享 SDK 句柄，并在超时或资源释放时将其删除 |
 | [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
 | [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 与 PTY API 实现可执行文件查找、受管进程组与 stdio、远程 spill 文件及终端会话 |
 
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 7d6b503ef4..c338fb0263 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 6881556dc18497956966aff74adc085d8e8620d3
-README.zh.md: aea13f341f903e6c47b7484f477bf54cebf101c6
+README.md: 6045b313a91edafc25361eba3f3c4dacf56b4eb0
+README.zh.md: dc157d9b5167488530c7d63b59aed793ab6aa4c7
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 6881556dc1..6045b313a9 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -12,8 +12,6 @@ Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapte
   config:
     cwd: /home/user/workspace
     timeoutMs: 300000
-    onTimeout: pause
-    onDispose: kill
 
 - id: subprocess-e2b
   name: '@deepseek-ai/dsh-subprocess-e2b'
@@ -22,17 +20,13 @@ Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapte
   name: '@deepseek-ai/dsh-fs-e2b'
 ```
 
-`apiKey` is optional and otherwise reads `E2B_API_KEY`; the key configures the host SDK connection and is never installed in the sandbox. `cwd` defaults to `/home/user/workspace` and must be an absolute POSIX path. `timeoutMs` defaults to five minutes. `onTimeout` is `pause` by default and accepts `pause | kill`; it applies only when this service creates a sandbox. Pause-on-timeout enables E2B auto-resume so the shared SDK handle wakes on its next operation. `onDispose` defaults to `kill` and accepts `kill | pause | leave`.
-
-Set `sandboxId` to reconnect a running or paused sandbox instead of creating one. E2B resumes a paused sandbox during connect; `template` and `onTimeout` are creation-only and cannot accompany `sandboxId`. Omitting `template` uses E2B's default base template.
+`apiKey` is optional and otherwise reads `E2B_API_KEY`; the key configures the host SDK connection and is never installed in the sandbox. `cwd` defaults to `/home/user/workspace` and must be an absolute POSIX path. `timeoutMs` defaults to five minutes and controls the sandbox lifetime; expiry deletes the sandbox.
 
 ## Lifecycle and ownership
 
-Construction starts one create/connect operation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. Each adapter-internal E2B command shell receives a fresh randomized root-level `HOME`, so the SDK's fixed login shell does not resolve profile files from the mutable user home before the control command. `sandboxId` resolves to a branded `E2BSandboxId` after setup.
+Construction starts one sandbox creation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. Each adapter-internal E2B command shell receives a fresh randomized root-level `HOME`, so the SDK's fixed login shell does not resolve profile files from the mutable user home before the control command.
 
-Disposal first prevents new handle acquisition, then awaits setup and applies exactly one configured disposition. A `SandboxNotFoundError` is accepted when disposal requests `kill`, or when this service created a sandbox with `onTimeout: kill`; otherwise, a not-found error from a requested `pause` rejects teardown because retention was not proved. A newly created sandbox is killed when initial directory setup fails; if that rollback fails, disposal retries it before releasing ownership. A reconnected sandbox is not killed on setup failure because the service did not create it. Provider plugins must load after this owner and dispose before it.
-
-`pause` and `leave` retain remote filesystem and adapter artifacts for a later `sandboxId` connection, but a later harness process receives only a new SDK handle. The subprocess service still fulfills its seam contract by terminating managed groups before owner disposal; neither disposition recovers prior process objects, output cursors, or in-memory adapter locks.
+Disposal first prevents new handle acquisition, then awaits setup and deletes the sandbox. A `SandboxNotFoundError` means expiry or another owner already deleted it and is accepted as quiescence. Initial directory setup failure also deletes the newly created sandbox; if that rollback fails, disposal retries it before releasing ownership. Provider plugins must load after this owner and dispose before it.
 
 ## Model Experience
 
@@ -45,6 +39,6 @@ No direct invalidation; this package does not contribute request tokens.
 ## Known Limitations and Deferred Work
 
 - **This is not a whole-harness runtime** — Cordis services, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
-- **Retained sandboxes do not restore host handles** — reconnect preserves remote files and adapter artifacts, but cannot reconstruct subprocess handles, stream cursors, or mutation locks; managed subprocesses terminate when their service disposes.
-- **No deployment platform is configured** — templates, volumes, snapshots, network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
-- **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access also retains the template's policy.
+- **Sandbox state is ephemeral** — disposal and timeout delete the sandbox; reconnect, pause/leave retention, templates, volumes, and snapshots are outside this POC.
+- **No deployment platform is configured** — network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
+- **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access retains the base image's policy.
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index aea13f341f..dc157d9b51 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -12,8 +12,6 @@
   config:
     cwd: /home/user/workspace
     timeoutMs: 300000
-    onTimeout: pause
-    onDispose: kill
 
 - id: subprocess-e2b
   name: '@deepseek-ai/dsh-subprocess-e2b'
@@ -22,17 +20,13 @@
   name: '@deepseek-ai/dsh-fs-e2b'
 ```
 
-`apiKey` 可省略；省略时读取 `E2B_API_KEY`。该密钥只配置宿主 SDK 连接，绝不会安装进沙箱。`cwd` 默认为 `/home/user/workspace`，并且必须是绝对 POSIX 路径。`timeoutMs` 默认为 5 分钟。`onTimeout` 默认为 `pause`，接受 `pause | kill`；它只在本服务创建沙箱时生效。超时时 pause 会启用 E2B 自动恢复，使共享 SDK 句柄在下一次操作时唤醒。`onDispose` 默认为 `kill`，接受 `kill | pause | leave`。
-
-设置 `sandboxId` 可重新连接正在运行或已经暂停的沙箱，而不是创建新沙箱。连接时，E2B 会恢复已经暂停的沙箱；`template` 和 `onTimeout` 仅用于创建，不能与 `sandboxId` 同时使用。省略 `template` 时使用 E2B 的默认基础模板。
+`apiKey` 可省略；省略时读取 `E2B_API_KEY`。该密钥只配置宿主 SDK 连接，绝不会安装进沙箱。`cwd` 默认为 `/home/user/workspace`，并且必须是绝对 POSIX 路径。`timeoutMs` 默认为 5 分钟并控制沙箱生命周期；超时会删除沙箱。
 
 ## 生命周期与所有权
 
-构造阶段会启动一次 create/connect 操作。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。每个适配器内部的 E2B 命令 shell 都会获得一个位于根目录下、全新随机生成的 `HOME`，因此 SDK 固定使用的登录 shell 不会在控制命令之前解析可变用户主目录中的配置文件。初始化完成后，`sandboxId` 会结算为品牌类型 `E2BSandboxId`。
+构造阶段会启动一次沙箱创建。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。每个适配器内部的 E2B 命令 shell 都会获得一个位于根目录下、全新随机生成的 `HOME`，因此 SDK 固定使用的登录 shell 不会在控制命令之前解析可变用户主目录中的配置文件。
 
-资源释放会先阻止继续获取新句柄，再等待初始化完成，并且只应用一种已配置的处置方式。`SandboxNotFoundError` 仅在资源释放请求 `kill`，或本服务创建了配置为 `onTimeout: kill` 的沙箱时才可接受；否则，`pause` 请求返回的未找到错误会导致 teardown 拒绝，因为无法证明保留成功。新建沙箱的初始目录设置失败时，服务会终止该沙箱；如果该回滚失败，资源释放会在解除所有权前重试。重新连接的沙箱设置失败时不会被终止，因为它不是由本服务创建的。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
-
-`pause` 和 `leave` 会保留远程文件系统及适配器产物，供稍后的 `sandboxId` 连接使用，但后续 harness 进程只会获得新的 SDK 句柄。进程管理服务仍会履行其 seam 契约，在所有者释放前终止受管进程组；这两种处置方式都不会恢复先前的进程对象、输出游标或内存中的适配器锁。
+资源释放会先阻止继续获取新句柄，再等待初始化完成，然后删除沙箱。`SandboxNotFoundError` 表示沙箱已因超时或被另一个所有者删除，因此可视为完全停稳。初始目录设置失败时也会删除新建沙箱；如果该回滚失败，资源释放会在解除所有权前重试。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
 ## 模型体验
 
@@ -45,6 +39,6 @@
 ## 已知限制与延后工作
 
 - **这不是完整的 harness 运行时**：Cordis 服务、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
-- **保留的沙箱不会恢复宿主句柄**：重新连接会保留远程文件和适配器产物，但无法重建进程管理句柄、流游标或变更锁；进程管理服务 dispose 时会终止受管子进程。
-- **没有配置部署平台**：模板、卷、快照、网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
-- **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用模板的策略。
+- **沙箱状态是短暂的**：资源释放和超时都会删除沙箱；重新连接、pause/leave 保留、模板、卷和快照均不在本 POC 范围内。
+- **没有配置部署平台**：网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
+- **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用基础镜像的策略。
diff --git a/packages/e2b/e2b/package.json b/packages/e2b/e2b/package.json
index 7ecc5fabed..82fda6b303 100644
--- a/packages/e2b/e2b/package.json
+++ b/packages/e2b/e2b/package.json
@@ -27,7 +27,6 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
@@ -36,7 +35,6 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-loader-smoke": "workspace:^",
     "cordis": "^4.0.0-rc.7"
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index 3285d82395..d6797b9147 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -9,30 +9,15 @@ import { posix } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import { FileType, Sandbox, SandboxNotFoundError } from 'e2b'
-import type { Branded } from '@deepseek-ai/dsh-brand'
 
 export {
   CommandExitError,
   FileNotFoundError,
   FileType,
   Sandbox,
-  SandboxError,
   SandboxNotFoundError,
-  TimeoutError,
 } from 'e2b'
-export type { CommandHandle, CommandResult, EntryInfo, ProcessInfo, PtyOutput } from 'e2b'
-
-/** Opaque E2B sandbox identity used for reconnecting a later harness process. */
-export type E2BSandboxId = Branded<'E2BSandboxId'>
-
-/**
- * Brand an SDK sandbox id after E2B has created or resolved it.
- * @param value - E2B's opaque sandbox id.
- * @returns the same string with the harness brand.
- */
-export function E2BSandboxId(value: string): E2BSandboxId {
-  return value as E2BSandboxId
-}
+export type { CommandHandle, CommandResult, EntryInfo } from 'e2b'
 
 /**
  * Quote one opaque argument for the SDK's unavoidable `/bin/bash -l -c` layer.
@@ -54,44 +39,25 @@ export function e2bControlEnvs(
   return { ...overrides, HOME: `/.dsh-e2b-control-${randomUUID()}` }
 }
 
-/** Action taken on the owned sandbox when the Cordis service is disposed. */
-export type E2BDisposeMode = 'kill' | 'pause' | 'leave'
-
-/** Action E2B takes when a newly created sandbox reaches its lifetime. */
-export type E2BTimeoutMode = 'kill' | 'pause'
-
 /** Configuration for the shared E2B sandbox owner. */
 export interface Config {
   /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */
   apiKey?: string
-  /** Existing sandbox to reconnect instead of creating a new one. */
-  sandboxId?: string
-  /** Template name or id for a newly created sandbox. */
-  template?: string
   /** Shared remote working directory, created before adapters receive the sandbox. */
   cwd?: string
-  /** E2B sandbox lifetime in milliseconds. */
+  /** E2B sandbox lifetime in milliseconds; expiry always deletes the sandbox. */
   timeoutMs?: number
-  /** E2B action when a newly created sandbox reaches `timeoutMs`. */
-  onTimeout?: E2BTimeoutMode
-  /** Disposal policy; `pause` and `leave` retain remote state for reconnect. */
-  onDispose?: E2BDisposeMode
 }
 
 interface ResolvedConfig {
   apiKey: string
   cwd: string
   timeoutMs: number
-  onTimeout: E2BTimeoutMode
-  onDispose: E2BDisposeMode
-  sandboxId?: string
-  template?: string
 }
 
 interface SchemaResolvedConfig extends Config {
   cwd: string
   timeoutMs: number
-  onDispose: E2BDisposeMode
 }
 
 declare module 'cordis' {
@@ -101,31 +67,24 @@ declare module 'cordis' {
 }
 
 /**
- * Owns one lazily consumable E2B SDK handle and its final kill/pause/leave
- * decision. The connection begins at plugin construction; adapters await
+ * Creates one lazily consumable E2B SDK handle and deletes the sandbox at
+ * timeout or disposal. Creation begins at plugin construction; adapters await
  * {@link getSandbox} before their first operation.
  */
 export class E2BSandboxService extends Service {
   static Config: z<Config> = z.object({
     apiKey: z.string(),
-    sandboxId: z.string(),
-    template: z.string(),
     cwd: z.string().default('/home/user/workspace'),
     timeoutMs: z.number().default(300_000),
-    onTimeout: z.union(['kill', 'pause'] as const),
-    onDispose: z.union(['kill', 'pause', 'leave'] as const).default('kill'),
   })
 
   /** Validated remote working directory shared by provider adapters. */
   readonly cwd: string
   /** Remote directory reserved for adapter-owned process and terminal state. */
   readonly runtimeRoot: string
-  /** Sandbox id once E2B has created or resolved the remote runtime. */
-  readonly sandboxId: Promise<E2BSandboxId>
 
   private readonly config: ResolvedConfig
   private readonly ready: Promise<Sandbox>
-  private readonly created: boolean
   private failedSetupSandbox: Sandbox | undefined
   private disposed = false
 
@@ -138,79 +97,50 @@ export class E2BSandboxService extends Service {
       apiKey: apiKey ?? '',
       cwd: resolved.cwd,
       timeoutMs: resolved.timeoutMs,
-      onTimeout: config.onTimeout ?? 'pause',
-      onDispose: resolved.onDispose,
-      ...(config.sandboxId !== undefined ? { sandboxId: config.sandboxId } : {}),
-      ...(config.template !== undefined ? { template: config.template } : {}),
     }
-    this.validate(config)
+    this.validate()
     this.cwd = this.config.cwd
     this.runtimeRoot = posix.join(this.cwd, '.dsh-e2b')
-    this.created = this.config.sandboxId === undefined
     this.ready = this.open()
     // A deployment may load the owner before any adapter uses it. Keep a
     // failed eager connection observed; getSandbox() still returns the error.
     void this.ready.catch(() => {})
-    this.sandboxId = this.ready.then(sandbox => E2BSandboxId(sandbox.sandboxId))
-    void this.sandboxId.catch(() => {})
 
     ctx.effect(() => async () => {
       this.disposed = true
-      let sandbox: Sandbox
-      try {
-        sandbox = await this.ready
-      } catch {
-        const failedSetupSandbox = this.failedSetupSandbox
-        if (failedSetupSandbox === undefined) return
-        sandbox = failedSetupSandbox
+      let sandbox = this.failedSetupSandbox
+      if (sandbox === undefined) {
         try {
-          await sandbox.kill()
-          this.failedSetupSandbox = undefined
-        } catch (error: unknown) {
-          if (!(error instanceof SandboxNotFoundError)) throw error
-          this.failedSetupSandbox = undefined
+          sandbox = await this.ready
+        } catch {
+          sandbox = this.failedSetupSandbox
         }
-        return
       }
+      if (sandbox === undefined) return
       try {
-        switch (this.config.onDispose) {
-          case 'kill':
-            await sandbox.kill()
-            return
-          case 'pause': {
-            await sandbox.pause()
-            return
-          }
-          case 'leave':
-            return
-        }
+        await sandbox.kill()
       } catch (error: unknown) {
         if (!(error instanceof SandboxNotFoundError)) throw error
-        // Missing proves the requested disposition only when this owner asked
-        // for deletion or created the sandbox with timeout deletion. A
-        // reconnected sandbox's creation lifecycle is unknown.
-        if (this.config.onDispose === 'kill') return
-        if (this.created && this.config.onTimeout === 'kill') return
-        throw error
       }
+      this.failedSetupSandbox = undefined
     }, 'e2b sandbox teardown')
   }
 
   /**
    * Return the shared live SDK handle.
-   * @returns the created or reconnected sandbox after the configured cwd exists.
-   * @throws when E2B rejects creation/reconnection or the service is disposing.
+   * @returns the created sandbox after the configured cwd exists.
+   * @throws when E2B rejects creation or the service is disposing.
    */
   async getSandbox(): Promise<Sandbox> {
     if (this.disposed) throw new Error('E2B sandbox service is disposing')
     const sandbox = await this.ready
     // Disposal can race the awaited sandbox readiness despite the synchronous precheck.
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- Awaiting readiness yields to disposal.
     if (this.disposed) throw new Error('E2B sandbox service is disposing')
     return sandbox
   }
 
-  private validate(input: Config): void {
+  private validate(): void {
     if (this.config.apiKey.length === 0) {
       throw new Error('dsh-e2b: configure apiKey or set E2B_API_KEY')
     }
@@ -220,35 +150,15 @@ export class E2BSandboxService extends Service {
     if (!Number.isFinite(this.config.timeoutMs) || this.config.timeoutMs <= 0) {
       throw new Error('dsh-e2b: timeoutMs must be a positive finite number')
     }
-    if (this.config.sandboxId !== undefined && this.config.sandboxId.length === 0) {
-      throw new Error('dsh-e2b: sandboxId must be non-empty when provided')
-    }
-    if (this.config.sandboxId !== undefined && this.config.template !== undefined) {
-      throw new Error('dsh-e2b: template applies only when creating; omit it when sandboxId reconnects')
-    }
-    if (this.config.sandboxId !== undefined && input.onTimeout !== undefined) {
-      throw new Error('dsh-e2b: onTimeout applies only when creating; omit it when sandboxId reconnects')
-    }
   }
 
   private async open(): Promise<Sandbox> {
-    const connection = {
+    const sandbox = await Sandbox.create({
       apiKey: this.config.apiKey,
       timeoutMs: this.config.timeoutMs,
-    }
-    const sandbox = this.config.sandboxId === undefined
-      ? this.config.template === undefined
-        ? await Sandbox.create({
-          ...connection,
-          secure: true,
-          lifecycle: { onTimeout: this.config.onTimeout, autoResume: this.config.onTimeout === 'pause' },
-        })
-        : await Sandbox.create(this.config.template, {
-          ...connection,
-          secure: true,
-          lifecycle: { onTimeout: this.config.onTimeout, autoResume: this.config.onTimeout === 'pause' },
-        })
-      : await Sandbox.connect(this.config.sandboxId, connection)
+      secure: true,
+      lifecycle: { onTimeout: 'kill' },
+    })
     try {
       await sandbox.files.makeDir(this.cwd)
       await sandbox.files.makeDir(this.runtimeRoot)
@@ -262,14 +172,12 @@ export class E2BSandboxService extends Service {
       )
       return sandbox
     } catch (error: unknown) {
-      if (this.created) {
-        try {
-          await sandbox.kill()
-        } catch (_cleanupFailure) {
-          // Preserve the setup failure as the public error while retaining the
-          // created handle for the service disposer to retry this rollback.
-          this.failedSetupSandbox = sandbox
-        }
+      try {
+        await sandbox.kill()
+      } catch (_cleanupFailure) {
+        // Preserve the setup failure as the public error while retaining the
+        // created handle for the service disposer to retry this rollback.
+        this.failedSetupSandbox = sandbox
       }
       throw error
     }
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 6600f1046d..2eca4f1f63 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -5,8 +5,7 @@ import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
-import E2BSandboxService, {
-  e2bControlEnvs,
+import {
   FileNotFoundError,
   Sandbox,
   SandboxNotFoundError,
@@ -113,26 +112,6 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       await subprocessFiber.dispose()
       await ptyFiber.dispose()
 
-      await sandbox.commands.run([
-        'rm -rf -- /home/user/.dsh-e2b /home/user/dsh-e2b-runtime-target',
-        'mkdir -p -- /home/user/dsh-e2b-runtime-target',
-        'chmod 755 -- /home/user/dsh-e2b-runtime-target',
-        'ln -s -- /home/user/dsh-e2b-runtime-target /home/user/.dsh-e2b',
-      ].join('\n'), { envs: e2bControlEnvs({ NPM_TOKEN: '' }) })
-      const linkedCtx = new Context()
-      const linkedFiber = await linkedCtx.plugin(E2BSandboxService, {
-        apiKey,
-        sandboxId: sandbox.sandboxId,
-        cwd: '/home/user',
-        onDispose: 'leave',
-      })
-      try {
-        await expect(linkedCtx.e2b.getSandbox()).rejects.toThrow('runtime root must be a real directory')
-        const target = await sandbox.files.getInfo('/home/user/dsh-e2b-runtime-target')
-        expect(target.mode & 0o777).toBe(0o755)
-      } finally {
-        await linkedFiber.dispose()
-      }
     } finally {
       await sandbox.kill().catch(() => false)
     }
@@ -160,23 +139,10 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     expect(stderr).toBe('')
     const output = JSON.parse(stdout) as Record<string, unknown>
     expect(output).toMatchObject({
-      bashRead: 'written-by-fs-versioned\n',
-      fsVersionGuard: true,
+      bashRead: 'versioned-by-fs\n',
       fsRead: 'written-by-bash\n',
       explicitEnvironment: true,
       splitUtf8Output: '你好',
-      outputDrain: {
-        outcome: { exitCode: 0, signal: null },
-        text: 'leader-done\n',
-        exited: true,
-        clean: true,
-      },
-      publicationRollback: true,
-      spill: {
-        liveBytes: 6,
-        outcome: { exitCode: null, signal: 'SIGTERM' },
-        read: { text: '6789', nextOffset: 10, lossy: true },
-      },
       hover: {
         kind: 'hover',
         hover: { contents: '**remote hover** 你好 café' },
@@ -185,24 +151,14 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         kind: 'locations',
         locations: [{ range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } } }],
       },
-      lspDocumentBound: true,
       terminal: {
         echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
         signal: { delivered: true },
         interrupted: { sessionStatus: { kind: 'running' } },
-        interruptIdentitySafe: true,
         treeCleanup: true,
       },
-      hostileOutput: { error: { kind: 'output-limit' } },
-      nativeOutput: { error: { kind: 'output-limit' } },
-      descriptorOutput: { error: { kind: 'output-limit' } },
-      inheritedOutput: { error: { kind: 'output-limit' } },
       descendantPipe: { value: true, logs: [] },
       descendantCleanup: true,
-      timedOut: { error: { kind: 'timeout' } },
-      aborted: { error: { kind: 'abort', message: 'live abort' } },
-      oversizedBoot: { error: { kind: 'worker-exit' } },
-      oversizedReply: { error: { kind: 'worker-exit' } },
       lingeringCodeRunners: 0,
     })
     const terminalMotd = (output.terminal as { motd: string }).motd
@@ -217,10 +173,11 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     )
     expect(output.code).toEqual({
       value: { doubled: 42, typed: true },
-      logs: ['remote-log 你好 42', 'post-mutation'],
+      logs: ['remote-log 你好 42'],
     })
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
     await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
+    await expect(Sandbox.list({ apiKey }).nextItems()).resolves.toEqual([])
   }, 195_000)
 })
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index af55a2419a..e3a6c09039 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -4,7 +4,6 @@ import { Context } from 'cordis'
 import type { Sandbox as SandboxType } from 'e2b'
 import E2BSandboxService, {
   e2bControlEnvs,
-  E2BSandboxId,
   FileType,
   SandboxNotFoundError,
   quoteE2BShellArg,
@@ -14,21 +13,16 @@ import InvariantService from '@deepseek-ai/dsh-invariants'
 
 const sdk = vi.hoisted(() => ({
   create: vi.fn(),
-  connect: vi.fn(),
 }))
 
 vi.mock('e2b', async (importOriginal) => {
   const actual = await importOriginal<typeof import('e2b')>()
   // The mock replaces only the SDK's static factory surface and is never constructed.
-  // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+  // oxlint-disable-next-line typescript/no-extraneous-class -- The SDK contract is a class with a static factory.
   class FakeSandbox {
     static create(...args: unknown[]): unknown {
       return sdk.create(...args)
     }
-
-    static connect(...args: unknown[]): unknown {
-      return sdk.connect(...args)
-    }
   }
   return { ...actual, Sandbox: FakeSandbox }
 })
@@ -39,7 +33,6 @@ interface SandboxFixture {
   getInfo: ReturnType<typeof vi.fn>
   run: Mock<RunCommand>
   kill: ReturnType<typeof vi.fn>
-  pause: ReturnType<typeof vi.fn>
 }
 
 type RunCommand = (
@@ -52,20 +45,17 @@ function fakeSandbox(id = 'sandbox-1'): SandboxFixture {
   const getInfo = vi.fn().mockResolvedValue({ type: FileType.DIR })
   const run = vi.fn<RunCommand>().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
   const kill = vi.fn().mockResolvedValue(undefined)
-  const pause = vi.fn().mockResolvedValue(true)
   const sandbox = {
     sandboxId: id,
     files: { makeDir, getInfo },
     commands: { run },
     kill,
-    pause,
   } as unknown as SandboxType
-  return { sandbox, makeDir, getInfo, run, kill, pause }
+  return { sandbox, makeDir, getInfo, run, kill }
 }
 
 beforeEach(() => {
   sdk.create.mockReset()
-  sdk.connect.mockReset()
   vi.unstubAllEnvs()
 })
 
@@ -87,14 +77,13 @@ describe('E2BSandboxService', () => {
 
     const service = ctx.e2b
     await expect(service.getSandbox()).resolves.toBe(fixture.sandbox)
-    await expect(service.sandboxId).resolves.toBe(E2BSandboxId('sandbox-1'))
     expect(service.cwd).toBe('/home/user/workspace')
     expect(service.runtimeRoot).toBe('/home/user/workspace/.dsh-e2b')
     expect(sdk.create).toHaveBeenCalledWith({
       apiKey: 'test-key',
       timeoutMs: 300_000,
       secure: true,
-      lifecycle: { onTimeout: 'pause', autoResume: true },
+      lifecycle: { onTimeout: 'kill' },
     })
     expect(fixture.makeDir).toHaveBeenNthCalledWith(1, '/home/user/workspace')
     expect(fixture.makeDir).toHaveBeenNthCalledWith(2, '/home/user/workspace/.dsh-e2b')
@@ -127,55 +116,26 @@ describe('E2BSandboxService', () => {
     expect(fixture.kill).toHaveBeenCalledOnce()
   })
 
-  it('creates from a template, honors timeout and pause policies, and reads the key from the environment', async () => {
+  it('reads the key from the environment and honors the configured cwd and lifetime', async () => {
     vi.stubEnv('E2B_API_KEY', 'environment-key')
-    const fixture = fakeSandbox('template-sandbox')
+    const fixture = fakeSandbox('configured-sandbox')
     sdk.create.mockResolvedValue(fixture.sandbox)
     const ctx = new Context()
     const fiber = await ctx.plugin(E2BSandboxService, {
-      template: 'agent-template',
       cwd: '/workspace/project',
       timeoutMs: 60_000,
-      onTimeout: 'kill',
-      onDispose: 'pause',
     })
     await ctx.e2b.getSandbox()
 
-    expect(sdk.create).toHaveBeenCalledWith('agent-template', {
+    expect(sdk.create).toHaveBeenCalledWith({
       apiKey: 'environment-key',
       timeoutMs: 60_000,
       secure: true,
-      lifecycle: { onTimeout: 'kill', autoResume: false },
+      lifecycle: { onTimeout: 'kill' },
     })
+    expect(ctx.e2b.cwd).toBe('/workspace/project')
     await fiber.dispose()
-    expect(fixture.pause).toHaveBeenCalledOnce()
-    expect(fixture.kill).not.toHaveBeenCalled()
-  })
-
-  it('accepts an already-paused result during configured pause disposal', async () => {
-    const fixture = fakeSandbox()
-    fixture.pause.mockResolvedValue(false)
-    sdk.create.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', onDispose: 'pause' })
-    await ctx.e2b.getSandbox()
-    await fiber.dispose()
-    expect(fixture.pause).toHaveBeenCalledOnce()
-  })
-
-  it('treats a timeout-killed sandbox as already quiescent during disposal', async () => {
-    const fixture = fakeSandbox()
-    fixture.pause.mockRejectedValue(new SandboxNotFoundError('sandbox expired'))
-    sdk.create.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    const fiber = await ctx.plugin(E2BSandboxService, {
-      apiKey: 'test-key',
-      onTimeout: 'kill',
-      onDispose: 'pause',
-    })
-    await ctx.e2b.getSandbox()
-    await expect(fiber.dispose()).resolves.toBeUndefined()
-    expect(fixture.pause).toHaveBeenCalledOnce()
+    expect(fixture.kill).toHaveBeenCalledOnce()
   })
 
   it('accepts a missing sandbox when disposal itself requests deletion', async () => {
@@ -208,49 +168,6 @@ describe('E2BSandboxService', () => {
     expect(errors).toContain(failure)
   })
 
-  it.each([
-    ['a created pause-on-timeout sandbox', false],
-    ['a reconnected sandbox with unknown creation policy', true],
-  ] as const)('reports missing during pause disposal for %s', async (_label, reconnect) => {
-    const fixture = fakeSandbox()
-    const failure = new SandboxNotFoundError('sandbox unexpectedly missing')
-    fixture.pause.mockRejectedValue(failure)
-    if (reconnect) sdk.connect.mockResolvedValue(fixture.sandbox)
-    else sdk.create.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    const errors: unknown[] = []
-    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
-    const fiber = await ctx.plugin(E2BSandboxService, {
-      apiKey: 'test-key',
-      onDispose: 'pause',
-      ...(reconnect ? { sandboxId: 'existing' } : {}),
-    })
-    await ctx.e2b.getSandbox()
-
-    await expect(fiber.dispose()).resolves.toBeUndefined()
-    expect(fixture.pause).toHaveBeenCalledOnce()
-    expect(errors).toContain(failure)
-  })
-
-  it('reconnects without applying creation lifecycle options and can leave state running', async () => {
-    const fixture = fakeSandbox('existing')
-    sdk.connect.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    const fiber = await ctx.plugin(E2BSandboxService, {
-      apiKey: 'test-key',
-      sandboxId: 'existing',
-      timeoutMs: 90_000,
-      onDispose: 'leave',
-    })
-    await ctx.e2b.getSandbox()
-
-    expect(sdk.connect).toHaveBeenCalledWith('existing', { apiKey: 'test-key', timeoutMs: 90_000 })
-    expect(sdk.create).not.toHaveBeenCalled()
-    await fiber.dispose()
-    expect(fixture.kill).not.toHaveBeenCalled()
-    expect(fixture.pause).not.toHaveBeenCalled()
-  })
-
   it('kills a newly created sandbox when remote directory setup fails', async () => {
     const fixture = fakeSandbox()
     fixture.makeDir.mockRejectedValueOnce(new Error('setup failed'))
@@ -259,7 +176,6 @@ describe('E2BSandboxService', () => {
     const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
 
     await expect(ctx.e2b.getSandbox()).rejects.toThrow('setup failed')
-    await expect(ctx.e2b.sandboxId).rejects.toThrow('setup failed')
     expect(fixture.kill).toHaveBeenCalledOnce()
     await fiber.dispose()
   })
@@ -294,44 +210,30 @@ describe('E2BSandboxService', () => {
     expect(fixture.kill).toHaveBeenCalledTimes(2)
   })
 
-  it('does not kill a reconnected sandbox when setup fails', async () => {
-    const fixture = fakeSandbox()
-    fixture.makeDir.mockRejectedValueOnce(new Error('setup failed'))
-    sdk.connect.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', sandboxId: 'existing' })
-    await expect(ctx.e2b.getSandbox()).rejects.toThrow('setup failed')
-    expect(fixture.kill).not.toHaveBeenCalled()
-  })
-
   it.each([
     ['symbolic link', { type: FileType.DIR, symlinkTarget: '/tmp/redirected' }],
     ['regular file', { type: FileType.FILE }],
   ])('rejects a reserved runtime root that is a %s', async (_label, info) => {
     const fixture = fakeSandbox()
     fixture.getInfo.mockResolvedValueOnce(info)
-    sdk.connect.mockResolvedValue(fixture.sandbox)
+    sdk.create.mockResolvedValue(fixture.sandbox)
     const ctx = new Context()
-    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key', sandboxId: 'existing' })
+    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
 
     await expect(ctx.e2b.getSandbox()).rejects.toThrow('runtime root must be a real directory')
     expect(fixture.run).not.toHaveBeenCalled()
-    expect(fixture.kill).not.toHaveBeenCalled()
+    expect(fixture.kill).toHaveBeenCalledOnce()
   })
 
   it.each([
     [{ apiKey: '' }, /configure apiKey/],
     [{ apiKey: 'x', cwd: 'relative' }, /absolute Linux path/],
     [{ apiKey: 'x', timeoutMs: 0 }, /positive finite/],
-    [{ apiKey: 'x', sandboxId: '' }, /sandboxId must be non-empty/],
-    [{ apiKey: 'x', sandboxId: 'one', template: 'two' }, /template applies only/],
-    [{ apiKey: 'x', sandboxId: 'one', onTimeout: 'kill' }, /onTimeout applies only/],
   ] as const)('fails self-contained configuration before opening E2B: %j', async (config, message) => {
     vi.stubEnv('E2B_API_KEY', '')
     const ctx = new Context()
     await expect(ctx.plugin(E2BSandboxService, config)).rejects.toThrow(message)
     expect(sdk.create).not.toHaveBeenCalled()
-    expect(sdk.connect).not.toHaveBeenCalled()
   })
 
   it('requires a key when both config and the environment omit it', async () => {
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 3f756bf2f9..a8edcb34ab 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: 6827e16e9c45532590ee1aa986c18a353d175fdc
-README.zh.md: 21b067829ea95c4581d7e89f3d225f9c90e630ef
+README.md: cd170bcbe2831b0856b51791a2045382d93c1148
+README.zh.md: f97790cf1d4ef90f042df8ed564723e186327f00
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index 6827e16e9c..cd170bcbe2 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -24,8 +24,8 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **No host synchronization** — an empty E2B cwd stays empty until a tool, command, template, or external process populates it; local files are neither uploaded nor reflected back.
+- **No host synchronization** — an empty E2B cwd stays empty until a tool, command, or external process populates it; local files are neither uploaded nor reflected back.
 - **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
 - **Reads reopen canonical targets by path** — a concurrent remote path replacement between resolution and stream opening is not fenced by a stable file handle; no observed product defect justifies a provider-specific bounded-read protocol in this POC.
 - **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
-- **Custom templates must support the used Linux/GNU and E2B filesystem features** — `realpath -mz`, `base64 -w0`, `chmod`, same-filesystem rename, streaming reads, and file metadata extended attributes are required; unsupported templates fail rather than degrade silently.
+- **The POC targets E2B's default Linux image** — it relies on GNU `realpath`/`base64`/`chmod`, same-filesystem rename, streaming reads, and metadata extended attributes; custom templates are outside this POC.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index 21b067829e..f97790cf1d 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -24,8 +24,8 @@
 
 ## 已知限制与延后工作
 
-- **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令、模板或外部进程填充它；本地文件既不会上传，也不会同步回本地。
+- **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令或外部进程填充它；本地文件既不会上传，也不会同步回本地。
 - **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
 - **读取会按路径重新打开规范化目标**：在解析与打开流之间若并发替换远程路径，该操作没有稳定文件句柄提供围栏；在该 POC 中，没有已观察到的产品缺陷能够证明提供方专用的有界读取协议值得引入。
 - **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
-- **自定义模板必须支持所用的 Linux/GNU 与 E2B 文件系统功能**：必须支持 `realpath -mz`、`base64 -w0`、`chmod`、同一文件系统内的 rename、流式读取和文件元数据扩展属性；不支持的模板会失败，而不会静默降级。
+- **该 POC 面向 E2B 默认 Linux 镜像**：它依赖 GNU `realpath`／`base64`／`chmod`、同一文件系统内的 rename、流式读取和元数据扩展属性；自定义模板不在该 POC 范围内。
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 91f9a278fd..618472a6b8 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -275,7 +275,6 @@ async function setup(remote = new FakeRemote()): Promise<{ ctx: Context; fs: E2B
   const runtime = {
     cwd: '/workspace',
     runtimeRoot: '/workspace/.dsh-e2b',
-    disposeMode: 'kill',
     getSandbox: async () => remote.sandbox,
   } as unknown as E2BSandboxService
   ctx.provide('e2b', runtime)
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 9ac46f1bcb..96fb24e21b 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 9d563c91c149d28718159af1b1f8ddbd6652dc44
-README.zh.md: be189f41818c66aeff2bed7b1851b82ca08f08f4
+README.md: 4e47566d55cf9400459993185f03482761c92096
+README.zh.md: 21ef231af700f72c2c5ec1fc651297ebdd17d49b
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 9d563c91c1..4e47566d55 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -9,12 +9,12 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
 - **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
-- **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the template's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the sandbox user's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
 - **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
-The base E2B image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`. A custom template must retain compatible commands and E2B PTY support.
+The default E2B base image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`.
 
 ## Model Experience
 
@@ -28,10 +28,9 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 - **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate the base64 transport even when this adapter exposes bounded raw-byte tails, so the subprocess seam's normal host-memory bound is not achieved and transport retention is larger than the source stream.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
-- **Reconnect does not reconstruct handles** — remote PID/status/spill files survive a retained sandbox, but a new harness process does not rebuild live `SubprocessHandle` objects or output cursors from them.
-- **Remote state accumulates when retained** — process directories and valid spill files remain under `.dsh-e2b`; this POC supplies no retention sweep.
+- **Private state lives for the sandbox lifetime** — process directories and valid spill files remain under `.dsh-e2b` until the owner deletes the sandbox; this POC supplies no in-sandbox sweep.
 - **Numeric process identities are not reuse-fenced** — E2B exposes numeric PID/PGID PTY input, signalling, and cleanup operations but no atomic identity-bound alternative. The adapter minimizes host round trips and live coverage exercises the reproducible stale-interrupt overlap; replacement is deferred until E2B adds an identity primitive or a failure demonstrates a narrower protocol.
-- **The initial environment probe inherits sandbox defaults** — E2B merges command overrides with default environment entries, so the probe cannot blank unknown credential-shaped names before enumerating them. In a reconnected sandbox, a same-UID untrusted process could inspect that short-lived control shell; this POC therefore does not support secrets in sandbox-default environment variables and requires an E2B replacement-environment primitive or a hardened template to close the gap.
+- **The initial environment probe inherits sandbox defaults** — E2B merges command overrides with default environment entries, so the probe cannot blank unknown credential-shaped names before enumerating them. A same-UID untrusted process already in the sandbox could inspect that short-lived control shell; this POC therefore does not support secrets in sandbox-default environment variables and requires an E2B replacement-environment primitive to close the gap.
 - **E2B exposes no signal fact** — an adapter-requested `SIGTERM` or `SIGKILL` is reported only when no wrapper-published direct exit code wins; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
 - **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
-- **Linux utility and E2B transport semantics are assumed** — there is no Windows, arbitrary-template, escaped-session recovery, or network-partition fidelity layer.
+- **Linux utility and E2B transport semantics are assumed** — there is no Windows, escaped-session recovery, or network-partition fidelity layer.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index be189f4181..21ef231af7 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -9,12 +9,12 @@
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
 - **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
-- **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变模板 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变沙箱用户 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
 - **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
-基础 E2B 镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。自定义模板必须保留兼容的命令和 E2B PTY 支持。
+E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。
 
 ## 模型体验
 
@@ -28,10 +28,9 @@
 
 - **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界原始字节尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会累积 base64 传输内容，因此无法达到进程管理 seam 通常提供的宿主内存边界，而且传输保留量大于源数据流。
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
-- **重新连接不会重建句柄**：保留沙箱后，远程 PID／状态／spill 文件仍然存在，但新的 harness 进程不会据此重建实时 `SubprocessHandle` 对象或输出游标。
-- **保留沙箱时会累积远程状态**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下；本 POC 不提供保留清理。
+- **私有状态随沙箱生命周期存在**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下，直到所有者删除沙箱；本 POC 不提供沙箱内清理。
 - **数值进程身份没有复用围栏**：E2B 公开基于数值 PID/PGID 的 PTY 输入、信号发送和清理操作，却没有与身份原子绑定的替代方案。适配器会尽量减少宿主往返，真实环境测试会覆盖可复现的陈旧中断重叠；在 E2B 新增身份原语，或实际故障证明需要更窄的协议之前，替代方案会继续延后。
-- **初始环境探测会继承沙箱默认值**：E2B 会把命令覆盖与默认环境条目合并，因此探测无法在枚举未知且形似凭据的名称之前将它们置空。在重新连接的沙箱中，一个同 UID 的不可信进程可以检查该短时存在的控制 shell；因此，该 POC 不支持把 secret 放入沙箱默认环境变量，需要 E2B 的替换环境原语或经加固的模板才能弥合该缺口。
+- **初始环境探测会继承沙箱默认值**：E2B 会把命令覆盖与默认环境条目合并，因此探测无法在枚举未知且形似凭据的名称之前将它们置空。一个已在沙箱内运行的同 UID 不可信进程可以检查该短时存在的控制 shell；因此，该 POC 不支持把 secret 放入沙箱默认环境变量，需要 E2B 的替换环境原语才能弥合该缺口。
 - **E2B 不公开信号事实**：适配器请求的 `SIGTERM` 或 `SIGKILL` 只有在包装层发布的直接退出码没有胜出时才报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
 - **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
-- **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、任意模板、逃逸会话恢复或网络分区的保真层。
+- **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、逃逸会话恢复或网络分区的保真层。
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 990ab20a62..63cafcbfe0 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -106,7 +106,7 @@ export class E2BSubprocessService extends SubprocessService {
 
   /** @inheritdoc */
   spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
-    if (this.isDisposing()) throw new Error('subprocess-e2b: service is disposing')
+    if (this.disposing) throw new Error('subprocess-e2b: service is disposing')
     const program = spec.argv[0]
     if (program === undefined || program.length === 0) {
       throw new Error('invalid argv: expected a non-empty program name at argv[0]')
@@ -115,7 +115,7 @@ export class E2BSubprocessService extends SubprocessService {
       throw new Error('subprocess-e2b: graceMs must be a positive finite number')
     }
     if (spec.signal?.aborted === true) {
-      throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`)
+      throw new Error(`aborted before spawn: ${String(spec.signal.reason)}`)
     }
     const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'processes', randomUUID())
     const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir)
@@ -132,7 +132,7 @@ export class E2BSubprocessService extends SubprocessService {
 
   /** @inheritdoc */
   async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
-    if (this.isDisposing()) throw new Error('subprocess-e2b: service is disposing')
+    if (this.disposing) throw new Error('subprocess-e2b: service is disposing')
     const program = spec.argv[0]
     if (program === undefined || program.length === 0) {
       throw new Error('subprocess-e2b: terminal argv must contain a program')
@@ -158,7 +158,8 @@ export class E2BSubprocessService extends SubprocessService {
         (cleanup) => { this.failedTerminalSetupCleanups.add(cleanup) },
       )
       this.terminals.add(terminal)
-      if (this.isDisposing()) {
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- Remote allocation yields to disposal.
+      if (this.disposing) {
         await terminal.terminate()
         this.terminals.delete(terminal)
         throw new Error('subprocess-e2b: service disposed during terminal setup')
@@ -176,10 +177,6 @@ export class E2BSubprocessService extends SubprocessService {
       setup.resolve()
     }
   }
-
-  private isDisposing(): boolean {
-    return this.disposing
-  }
 }
 
 export default E2BSubprocessService
diff --git a/packages/e2b/subprocess-e2b/src/output.ts b/packages/e2b/subprocess-e2b/src/output.ts
index 8afcd138dc..ba1dc1a716 100644
--- a/packages/e2b/subprocess-e2b/src/output.ts
+++ b/packages/e2b/subprocess-e2b/src/output.ts
@@ -115,9 +115,6 @@ export class E2BOutputReader implements SubprocessOutputReader {
 
   /** @inheritdoc */
   readFrom(fromByte: number): SubprocessOutputRead {
-    if (!Number.isSafeInteger(fromByte) || fromByte < 0) {
-      throw new Error('subprocess output offset must be a non-negative safe integer')
-    }
     const retained = Buffer.concat(this.chunks, this.retainedBytes)
     const firstRetained = this.totalBytes - this.retainedBytes
     const lossy = fromByte < firstRetained
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index 5e383a50e2..fe964a7395 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -149,10 +149,6 @@ function commandOpts(
   return { envs: e2bControlEnvs(envs), ...(signal === undefined ? {} : { signal }) }
 }
 
-function isAborted(signal: AbortSignal | undefined): boolean {
-  return signal?.aborted === true
-}
-
 function waitTick(signal?: AbortSignal): Promise<boolean> {
   if (signal?.aborted === true) return Promise.resolve(false)
   return new Promise<boolean>((resolve) => {
@@ -173,7 +169,7 @@ const WAIT_ABORTED = Symbol('wait aborted')
 function waitWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | typeof WAIT_ABORTED> {
   if (signal === undefined) return promise
   if (signal.aborted) return Promise.resolve(WAIT_ABORTED)
-  return new Promise<T | typeof WAIT_ABORTED>((resolve, reject) => {
+  return new Promise<T | typeof WAIT_ABORTED>((resolve) => {
     const onAbort = (): void => { cleanup(); resolve(WAIT_ABORTED) }
     const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
     signal.addEventListener('abort', onAbort, { once: true })
@@ -181,10 +177,7 @@ function waitWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined)
       onAbort()
       return
     }
-    void promise.then(
-      (value) => { cleanup(); resolve(value) },
-      (error: unknown) => { cleanup(); reject(asError(error)) },
-    )
+    void promise.then((value) => { cleanup(); resolve(value) })
   })
 }
 
@@ -206,12 +199,9 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly paths: RemotePaths
   private controlEnvs: Record<string, string> = {}
   private remotePid = -1
-  private commandHandle: CommandHandle | undefined
   private outputTransportError: Error | undefined
   private outputDrainExpired = false
   private stateDirectoryCreated = false
-  private preparing = true
-  private terminationStarted = false
   private quiescenceProven = false
   private terminationAttempt: Promise<void> | undefined
   private terminationFailure: Error | undefined
@@ -265,7 +255,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   /** @inheritdoc */
   terminate(): void {
     if (this.quiescenceProven || this.terminationAttempt !== undefined) return
-    this.terminationStarted = true
     this.terminationController.abort(new Error('subprocess-e2b: command terminated'))
     this.stdout?.destroy()
     this.stderr?.destroy()
@@ -285,7 +274,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   async waitForExit(signal?: AbortSignal): Promise<boolean> {
     if (this.quiescenceProven) return true
     let handle: CommandHandle | undefined
-    if (this.terminationStarted) {
+    if (this.terminationController.signal.aborted) {
       const observed = await waitWithSignal(this.commandState.promise, signal)
       if (observed === WAIT_ABORTED) return false
       handle = observed
@@ -295,22 +284,23 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       }
       if (this.remotePid <= 0) {
         const attempt = this.terminationAttempt
-        if (attempt !== undefined && await waitWithSignal(attempt, signal) === WAIT_ABORTED) return false
+        if (attempt !== undefined && await waitWithSignal(attempt.catch(() => undefined), signal) === WAIT_ABORTED) {
+          return false
+        }
         this.throwTerminationFailure()
         // Successful pre-publication termination records quiescence; its only other outcome is the failure above.
         return true
       }
     } else {
-      try {
-        const observed = await waitWithSignal(this.readyState.promise, signal)
-        if (observed === WAIT_ABORTED) return false
-        handle = observed
-      } catch {
-        handle = this.commandHandle
-        if (handle === undefined) {
-          this.markQuiescent()
-          return true
-        }
+      const observed = await waitWithSignal(
+        this.readyState.promise.catch(() => this.commandState.promise),
+        signal,
+      )
+      if (observed === WAIT_ABORTED) return false
+      handle = observed
+      if (handle === undefined) {
+        this.markQuiescent()
+        return true
       }
     }
     this.throwTerminationFailure()
@@ -318,7 +308,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     try {
       sandbox = await this.runtime.getSandbox()
     } catch (error: unknown) {
-      if (isAborted(signal)) return false
+      if (signal?.aborted === true) return false
       if (error instanceof SandboxNotFoundError) {
         this.markQuiescent()
         return true
@@ -331,7 +321,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (!await waitTick(signal)) return false
     }
     this.throwTerminationFailure()
-    if (isAborted(signal)) return false
+    if (signal?.aborted === true) return false
     this.markQuiescent()
     return true
   }
@@ -345,10 +335,11 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async run(): Promise<SubprocessOutcome> {
     let sandbox: Sandbox | undefined
+    let preparing = true
     try {
       sandbox = await this.runtime.getSandbox()
       await this.prepareState(sandbox)
-      this.preparing = false
+      preparing = false
       const handle = await sandbox.commands.run(
         commandText(this.spec, this.paths),
         {
@@ -361,7 +352,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           onStderr: async (data) => { await this.dispatchOutput('stderr', data) },
         },
       )
-      this.commandHandle = handle
       const completion = handle.wait()
       void completion.catch(() => {})
       if (!isValidProcessId(handle.pid)) {
@@ -369,7 +359,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         try {
           await handle.kill()
           this.markQuiescent()
-          this.commandHandle = undefined
         } catch (cleanupError: unknown) {
           this.terminationFailure = asError(cleanupError)
           this.commandState.resolve(handle)
@@ -404,9 +393,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       await this.finalizeSpills(sandbox)
       return outcome
     } catch (error: unknown) {
-      const canceledPreparation = this.preparing
-        && this.terminationStarted
-        && this.terminationController.signal.aborted
+      const canceledPreparation = preparing && this.terminationController.signal.aborted
       let failure = await this.rollbackPublishedFailure(error)
       if (sandbox !== undefined && this.stateDirectoryCreated) {
         try {
@@ -423,7 +410,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       if (canceledPreparation && failure === error) return { exitCode: null, signal: 'SIGTERM' }
       throw failure
     } finally {
-      this.preparing = false
       this.spec.signal?.removeEventListener('abort', this.onAbort)
       this.stdout?.end()
       this.stderr?.end()
@@ -583,7 +569,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async rollbackPublishedFailure(error: unknown): Promise<unknown> {
-    if (this.remotePid <= 0 || this.commandHandle === undefined || this.quiescenceProven) return error
+    if (this.remotePid <= 0 || this.quiescenceProven) return error
     this.terminate()
     try {
       await this.waitForExit()
@@ -626,7 +612,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     if (!isValidProcessId(handle.pid) && this.remotePid <= 0) {
       await handle.kill()
       this.markQuiescent()
-      this.commandHandle = undefined
       return
     }
     const sandbox = await this.runtime.getSandbox()
@@ -730,7 +715,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
       const size = (reader as E2BOutputReader).size
       if (this.outputDrainExpired || size <= mode.maxBytes || size > mode.spill.maxBytes) {
         removals.push(sandbox.files.remove(path).catch((_adapterPrivateSpillRemovalFailure: unknown) => {
-          // The command outcome is authoritative; a retained sandbox tolerates private residue.
+          // The command outcome is authoritative; owner teardown bounds private residue.
         }))
       }
     }
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 8d003dfc35..3876191759 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -41,7 +41,6 @@ const TERMINAL_RUNNER_SOURCE = [
   '  exit 125',
   'fi',
   'printf \'%s\' "$dsh_output_marker"',
-  "printf 'ready\\n' > \"$dsh_state/ready\"",
   'exec env -i -- "${dsh_env[@]}" "${dsh_argv[@]}"',
   '',
 ].join('\n')
@@ -51,7 +50,6 @@ interface TerminalPaths {
   environment: string
   argv: string
   outputMarker: string
-  ready: string
 }
 
 function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
@@ -165,26 +163,6 @@ async function terminalSessionId(
   return parsePositiveId(result.stdout, `subprocess-e2b: cannot resolve process session for terminal ${pid}`)
 }
 
-async function waitUntilReady(
-  sandbox: Sandbox,
-  paths: TerminalPaths,
-  completion: Promise<CommandResult>,
-  signal?: AbortSignal,
-): Promise<void> {
-  const settled = completion.then(() => true, () => true)
-  for (;;) {
-    signal?.throwIfAborted()
-    try {
-      if ((await sandbox.files.read(paths.ready, signalOpts(signal))).trim() === 'ready') return
-    } catch (error: unknown) {
-      if (!(error instanceof FileNotFoundError)) throw error
-    }
-    if (await Promise.race([settled, delay(POLL_MS).then(() => false)])) {
-      throw new Error('subprocess-e2b: terminal exited before publishing readiness')
-    }
-  }
-}
-
 async function sessionProcessGroups(
   sandbox: Sandbox,
   sessionId: number,
@@ -241,8 +219,13 @@ async function awaitSessionEmpty(
   const deadline = Date.now() + graceMs
   for (;;) {
     const groups = await sessionProcessGroups(sandbox, sessionId, envs)
-    if (groups.length === 0 || Date.now() >= deadline) return groups
-    if (kill) await signalGroups(sandbox, groups, 'KILL', envs)
+    if (groups.length === 0) return groups
+    if (kill) {
+      await signalGroups(sandbox, groups, 'KILL', envs)
+      if (Date.now() >= deadline) return await sessionProcessGroups(sandbox, sessionId, envs)
+    } else if (Date.now() >= deadline) {
+      return groups
+    }
     await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
   }
 }
@@ -277,7 +260,6 @@ async function rollbackUnpublishedTerminal(
         groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs)
       }
       if (groups.length > 0) {
-        await signalGroups(sandbox, groups, 'KILL', envs)
         await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, true)
       }
     } catch (error: unknown) {
@@ -285,25 +267,13 @@ async function rollbackUnpublishedTerminal(
     }
   }
   // Completion can settle while any awaited provider cleanup above is running.
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  // oxlint-disable-next-line typescript/no-unnecessary-condition -- Provider cleanup yields to completion.
   if (!topLevelExited) {
-    if (validPid) {
-      try {
-        await sandbox.pty.kill(handle.pid)
-      } catch (error: unknown) {
-        if (error instanceof SandboxNotFoundError) return
-        attemptFailures.push(asError(error))
-      }
-    }
-    // The awaited PTY fallback can settle completion before the SDK fallback.
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (!topLevelExited) {
-      try {
-        await handle.kill()
-      } catch (error: unknown) {
-        if (error instanceof SandboxNotFoundError) return
-        attemptFailures.push(asError(error))
-      }
+    try {
+      await handle.kill()
+    } catch (error: unknown) {
+      if (error instanceof SandboxNotFoundError) return
+      attemptFailures.push(asError(error))
     }
     await Promise.race([completion.catch(() => undefined), delay(graceMs)])
   }
@@ -321,7 +291,7 @@ async function rollbackUnpublishedTerminal(
     }
   }
   // The bounded completion race above updates this callback-owned state.
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  // oxlint-disable-next-line typescript/no-unnecessary-condition -- The callback mutates this after a race.
   if (!topLevelExited) {
     proofFailures.push(new Error(`subprocess-e2b: terminal setup rollback failed; surviving pid: ${handle.pid}`))
   }
@@ -347,7 +317,6 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   private cleanup: Promise<void> | undefined
   private readonly operationController = new AbortController()
   private readonly operations = new Set<Promise<unknown>>()
-  private terminating = false
   private terminationSignal: NodeJS.Signals | null = null
 
   constructor(
@@ -400,7 +369,6 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   /** @inheritdoc */
   terminate(): Promise<void> {
     if (this.cleanup !== undefined) return this.cleanup
-    this.terminating = true
     this.operationController.abort(new Error('subprocess-e2b: terminal is terminating'))
     const cleanup = this.closeAfterOperations()
     this.cleanup = cleanup
@@ -434,7 +402,9 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private trackOperation<T>(operation: (signal: AbortSignal) => Promise<T>): Promise<T> {
-    if (this.terminating) return Promise.reject(new Error('subprocess-e2b: terminal is terminating'))
+    if (this.operationController.signal.aborted) {
+      return Promise.reject(new Error('subprocess-e2b: terminal is terminating'))
+    }
     const pending = operation(this.operationController.signal)
     this.operations.add(pending)
     void pending.then(
@@ -445,7 +415,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
   }
 
   private async closeAfterOperations(): Promise<void> {
-    if (this.operations.size > 0) await Promise.allSettled(this.operations)
+    await Promise.allSettled(this.operations)
     await this.closeOnce()
   }
 
@@ -481,7 +451,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
       this.terminationSignal = 'SIGKILL'
       if (!this.topLevelExited) {
         try {
-          await this.sandbox.pty.kill(this.pid)
+          await this.handle.kill()
         } catch (error: unknown) {
           if (error instanceof SandboxNotFoundError) return
           throw error
@@ -504,7 +474,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     try {
       await this.sandbox.files.remove(this.stateDir)
     } catch (_adapterPrivateStateRemovalFailure) {
-      // The terminal is quiescent; a retained sandbox tolerates private residue.
+      // The terminal is quiescent; owner teardown bounds private residue.
     }
   }
 }
@@ -531,7 +501,6 @@ export async function spawnE2BTerminal(
     environment: posix.join(stateDir, 'environment'),
     argv: posix.join(stateDir, 'argv'),
     outputMarker: posix.join(stateDir, 'output-marker'),
-    ready: posix.join(stateDir, 'ready'),
   }
   const outputMarker = Buffer.from(`dsh-e2b-bootstrap:${randomUUID()}`)
   const output = new PassThrough()
@@ -577,7 +546,6 @@ export async function spawnE2BTerminal(
     }
     const command = `exec /bin/bash ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(stateDir)}\r`
     await sandbox.pty.sendInput(handle.pid, Buffer.from(command), signalOpts(spec.signal))
-    await waitUntilReady(sandbox, paths, completion, spec.signal)
     await waitForBootstrapOutput(outputFilter.ready, completion, spec.signal)
     const sessionId = await terminalSessionId(sandbox, handle.pid, controlEnvs, spec.signal)
     return new E2BTerminalHandle(
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 83e86892d4..f7adf8183c 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -316,7 +316,6 @@ function runtime(fake: FakeSandbox, getSandbox: () => Promise<Sandbox> = async (
   return {
     cwd: '/workspace',
     runtimeRoot: '/workspace/.dsh-e2b',
-    disposeMode: 'kill',
     getSandbox,
   } as unknown as E2BSandboxService
 }
@@ -372,8 +371,6 @@ describe('E2BOutputReader', () => {
     const overCap = new E2BOutputReader(2, 3, '/too-small')
     overCap.push(Buffer.from('abcd'))
     expect(overCap.readFrom(0)).toEqual({ text: 'cd', nextOffset: 4, lossy: true })
-    expect(() => overCap.readFrom(-1)).toThrow(/non-negative safe integer/)
-    expect(() => overCap.readFrom(1.5)).toThrow(/non-negative safe integer/)
   })
 })
 
@@ -1673,7 +1670,6 @@ describe('E2BSubprocessService', () => {
     expect(() => ctx.subprocess.spawn(spec({ argv: [] }))).toThrow(/non-empty program/)
     expect(() => ctx.subprocess.spawn(spec({ graceMs: 0 }))).toThrow(/positive finite/)
     expect(() => ctx.subprocess.spawn(spec({ signal: AbortSignal.abort('stop') }))).toThrow(/aborted before spawn/)
-    expect(() => ctx.subprocess.spawn(spec({ signal: { aborted: true, reason: undefined } as AbortSignal }))).toThrow(/aborted$/)
   })
 
   it('registers the package-owned empty invariant installer', async () => {
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index a4f4008a56..08d49bb87b 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -90,9 +90,6 @@ class FakeTerminalSandbox {
   readonly writes = new Map<string, string>()
   createOptions: Parameters<Sandbox['pty']['create']>[0] | undefined
   ambient = 'KEEP=visible\0UNICODE=你好\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
-  ready: string | Error = 'ready\n'
-  readyMisses = 0
-  readyReads = 0
   sessionId = '123\n'
   foreground = '456\n'
   groups = [123]
@@ -108,12 +105,9 @@ class FakeTerminalSandbox {
   sessionGroupsFailure: unknown
   foregroundFailure: unknown
   termFailure: unknown
-  ptyKillError: unknown
   removeError: unknown
   clearOnTerm = true
   clearOnKill = true
-  settleOnPtyKill = true
-  ptyKills = 0
   resolvedExecutable = '/usr/bin/node\n'
   requestedOutput = 'requested-shell$ '
   emitOutputMarker = true
@@ -144,15 +138,6 @@ class FakeTerminalSandbox {
         if (this.writeError !== undefined) throw this.writeError
         return files.map(() => ({}))
       },
-      read: async (): Promise<string> => {
-        this.readyReads += 1
-        if (this.readyMisses > 0) {
-          this.readyMisses -= 1
-          throw new FileNotFoundError('not ready')
-        }
-        if (this.ready instanceof Error) throw this.ready
-        return this.ready
-      },
       remove: async (path: string): Promise<void> => {
         this.removed.push(path)
         if (this.removeError !== undefined) throw this.removeError
@@ -237,12 +222,6 @@ class FakeTerminalSandbox {
           }
         }
       },
-      kill: async (pid: number): Promise<boolean> => {
-        this.ptyKills += 1
-        if (this.ptyKillError !== undefined) throw this.ptyKillError
-        if (this.settleOnPtyKill) this.handle.fail(137)
-        return pid === this.handle.pid
-      },
     },
   } as unknown as Sandbox
 }
@@ -251,7 +230,6 @@ function runtime(fake: FakeTerminalSandbox): E2BSandboxService {
   return {
     cwd: '/workspace',
     runtimeRoot: '/workspace/.dsh-e2b',
-    disposeMode: 'kill',
     getSandbox: async () => fake.sandbox,
   } as unknown as E2BSandboxService
 }
@@ -284,7 +262,6 @@ function holdRequestUntilAbort(started: PromiseWithResolvers<AbortSignal>) {
 describe('E2B terminal allocation', () => {
   it('hides bootstrap-shell bytes and preserves requested-shell bytes across the output boundary', async () => {
     const fake = new FakeTerminalSandbox()
-    fake.readyMisses = 1
     const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/terminal-one')
     let output = ''
     terminal.output.on('data', (chunk) => { output += String(chunk) })
@@ -417,12 +394,6 @@ describe('E2B terminal allocation', () => {
     expect(failedInput.commands).toContain('kill -TERM -- -123')
     expect(failedInput.groups).toEqual([])
 
-    const exited = new FakeTerminalSandbox()
-    exited.ready = new FileNotFoundError('not ready')
-    queueMicrotask(() => { exited.handle.succeed(0) })
-    await expect(spawnE2BTerminal(runtime(exited), spec(), '/runtime/exited'))
-      .rejects.toThrow('exited before publishing readiness')
-
     const invalidSession = new FakeTerminalSandbox()
     invalidSession.sessionId = 'not-a-session\n'
     invalidSession.clearOnTerm = false
@@ -431,7 +402,7 @@ describe('E2B terminal allocation', () => {
     expect(invalidSession.commands).toContain('kill -TERM -- -123')
     expect(invalidSession.commands).toContain('kill -KILL -- -123')
     expect(invalidSession.groups).toEqual([])
-    expect(invalidSession.ptyKills).toBe(1)
+    expect(invalidSession.handle.sdkKills).toBe(1)
     const lateData = invalidSession.createOptions?.onData
     if (lateData === undefined) throw new Error('missing captured terminal callback')
     expect(lateData(Buffer.from('late bytes'))).toBeUndefined()
@@ -442,12 +413,12 @@ describe('E2B terminal allocation', () => {
     await expect(spawnE2BTerminal(runtime(termFailed), spec(), '/runtime/term-failed'))
       .rejects.toThrow('bootstrap failed')
     expect(termFailed.commands).toContain('kill -KILL -- -123')
-    expect(termFailed.ptyKills).toBe(1)
+    expect(termFailed.handle.sdkKills).toBe(1)
 
     const uninspectable = new FakeTerminalSandbox()
     uninspectable.sendError = new Error('bootstrap failed')
     uninspectable.sessionGroupsFailure = 'session enumeration failed'
-    uninspectable.ptyKillError = new Error('PTY kill failed')
+    uninspectable.handle.sdkKillError = new Error('PTY kill failed')
     let uninspectableFailure: unknown
     try {
       await spawnE2BTerminal(runtime(uninspectable), spec(), '/runtime/uninspectable')
@@ -455,7 +426,6 @@ describe('E2B terminal allocation', () => {
       uninspectableFailure = error
     }
     expect(uninspectableFailure).toBeInstanceOf(AggregateError)
-    expect(uninspectable.ptyKills).toBe(1)
     expect(uninspectable.handle.sdkKills).toBe(1)
 
     const survivingGroups = new FakeTerminalSandbox()
@@ -468,7 +438,6 @@ describe('E2B terminal allocation', () => {
     const survivingPid = new FakeTerminalSandbox()
     survivingPid.sendError = new Error('bootstrap failed')
     survivingPid.groups = []
-    survivingPid.settleOnPtyKill = false
     survivingPid.handle.settleOnSdkKill = false
     await expect(spawnE2BTerminal(runtime(survivingPid), spec({ graceMs: 1 }), '/runtime/surviving-pid'))
       .rejects.toThrow('bootstrap failed')
@@ -491,12 +460,12 @@ describe('E2B terminal allocation', () => {
     const expiredDuringRollback = new FakeTerminalSandbox()
     expiredDuringRollback.sendError = new Error('bootstrap failed before timeout')
     expiredDuringRollback.groups = []
-    expiredDuringRollback.settleOnPtyKill = false
-    expiredDuringRollback.ptyKillError = new SandboxNotFoundError('sandbox expired')
+    expiredDuringRollback.handle.settleOnSdkKill = false
+    expiredDuringRollback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
     expiredDuringRollback.removeError = new SandboxNotFoundError('sandbox expired')
     await expect(spawnE2BTerminal(runtime(expiredDuringRollback), spec(), '/runtime/expired-rollback'))
       .rejects.toThrow('bootstrap failed before timeout')
-    expect(expiredDuringRollback.ptyKills).toBe(1)
+    expect(expiredDuringRollback.handle.sdkKills).toBe(1)
 
     const expiredBeforeSdkRollback = new FakeTerminalSandbox()
     expiredBeforeSdkRollback.handle.waitError = new Error('wait failed after timeout')
@@ -505,15 +474,6 @@ describe('E2B terminal allocation', () => {
     await expect(spawnE2BTerminal(runtime(expiredBeforeSdkRollback), spec(), '/runtime/expired-sdk-rollback'))
       .rejects.toThrow('wait failed after timeout')
 
-    const expiredDuringSdkFallback = new FakeTerminalSandbox()
-    expiredDuringSdkFallback.sendError = new Error('bootstrap failed before SDK fallback')
-    expiredDuringSdkFallback.groups = []
-    expiredDuringSdkFallback.settleOnPtyKill = false
-    expiredDuringSdkFallback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
-    expiredDuringSdkFallback.handle.settleOnSdkKill = false
-    await expect(spawnE2BTerminal(runtime(expiredDuringSdkFallback), spec(), '/runtime/expired-sdk-fallback'))
-      .rejects.toThrow('bootstrap failed before SDK fallback')
-
     const missingDuringDisconnect = new FakeTerminalSandbox()
     missingDuringDisconnect.sendError = new Error('bootstrap failed before disconnect')
     missingDuringDisconnect.handle.disconnectError = new SandboxNotFoundError('sandbox expired')
@@ -537,10 +497,6 @@ describe('E2B terminal allocation', () => {
     await expect(spawnE2BTerminal(runtime(createFailed), spec(), '/runtime/create'))
       .rejects.toThrow('create failed')
 
-    const readFailed = new FakeTerminalSandbox()
-    readFailed.ready = new Error('ready transport failed')
-    await expect(spawnE2BTerminal(runtime(readFailed), spec(), '/runtime/read'))
-      .rejects.toThrow('ready transport failed')
   })
 
   it('bounds a missing bootstrap-output boundary by process exit or cancellation', async () => {
@@ -560,7 +516,6 @@ describe('E2B terminal allocation', () => {
       '/runtime/cancel-output-boundary',
     )
     await vi.waitFor(() => { expect(cancelled.inputs).toHaveLength(1) })
-    await vi.waitFor(() => { expect(cancelled.readyReads).toBeGreaterThan(0) })
     await new Promise(resolve => setTimeout(resolve, 0))
     controller.abort(new Error('cancel output boundary'))
     await expect(cancelling).rejects.toThrow('cancel output boundary')
@@ -661,23 +616,23 @@ describe('E2B terminal lifecycle', () => {
   it('treats sandbox disappearance during PTY kill as quiescent', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
-    fake.settleOnPtyKill = false
-    fake.ptyKillError = new SandboxNotFoundError('sandbox expired')
+    fake.handle.settleOnSdkKill = false
+    fake.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
 
     await terminal.terminate()
-    expect(fake.ptyKills).toBe(1)
+    expect(fake.handle.sdkKills).toBe(1)
   })
 
   it('propagates a non-missing PTY kill failure', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
-    fake.settleOnPtyKill = false
-    fake.ptyKillError = new Error('PTY kill transport failed')
+    fake.handle.settleOnSdkKill = false
+    fake.handle.sdkKillError = new Error('PTY kill transport failed')
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
 
     await expect(terminal.terminate()).rejects.toThrow('PTY kill transport failed')
-    fake.ptyKillError = undefined
+    fake.handle.sdkKillError = undefined
     fake.handle.succeed(0)
     await terminal.done
     await terminal.terminate()
@@ -712,11 +667,11 @@ describe('E2B terminal lifecycle', () => {
     await terminal.terminate()
   })
 
-  it('escalates surviving process groups', async () => {
+  it('sends KILL before checking an expired force-cleanup deadline', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = [123, 456]
     fake.clearOnTerm = false
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/escalate')
+    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 0 }), '/runtime/escalate')
     const terminating = terminal.terminate()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
     await terminating
@@ -771,11 +726,11 @@ describe('E2B terminal lifecycle', () => {
   it('keeps a late command rejection authoritative after PTY kill', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
-    fake.settleOnPtyKill = false
+    fake.handle.settleOnSdkKill = false
     const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
     terminal.output.on('error', () => {})
     const cleanup = terminal.terminate()
-    while (fake.ptyKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
+    while (fake.handle.sdkKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
     await Promise.resolve()
     fake.handle.crash(new Error('late command transport failed'))
     await expect(terminal.done).rejects.toThrow('late command transport failed')
@@ -791,7 +746,7 @@ describe('E2B terminal lifecycle', () => {
 
     const livePid = new FakeTerminalSandbox()
     livePid.groups = []
-    livePid.settleOnPtyKill = false
+    livePid.handle.settleOnSdkKill = false
     const live = await spawnE2BTerminal(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
     await expect(live.terminate()).rejects.toThrow('surviving pid: 123')
     livePid.handle.succeed(0)
@@ -879,13 +834,13 @@ describe('E2B subprocess terminal service', () => {
     expect(fake.removed.some(path => path.includes('/terminals/'))).toBe(true)
   })
 
-  it('aborts and rolls back terminal setup that cannot publish readiness during disposal', async () => {
+  it('aborts and rolls back terminal setup that cannot publish its output boundary during disposal', async () => {
     const fake = new FakeTerminalSandbox()
-    fake.ready = new FileNotFoundError('not ready')
+    fake.emitOutputMarker = false
     const { ctx, fiber } = await service(fake)
     const spawning = ctx.subprocess.spawnTerminal(spec())
     const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
-    await vi.waitFor(() => { expect(fake.readyReads).toBeGreaterThan(0) })
+    await vi.waitFor(() => { expect(fake.inputs).toHaveLength(1) })
 
     await fiber.dispose()
     await rejected
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 87648e01e1..f682bc6847 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -716,6 +716,9 @@ importers:
 
   packages/bash/bash:
     devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3091,9 +3094,6 @@ importers:
 
   packages/credentials/credentials:
     devDependencies:
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants

From b1b2d63785a8b3a5341d2420401f7576ce12ff50 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 06:02:10 +0800
Subject: [PATCH 385/516] refactor(e2b): drop speculative cleanup retry state

---
 AGENTS.md                                     |  6 ++--
 docs/cordis-catalog/services.md               |  2 +-
 packages/e2b/e2b/README.i18n.yaml             |  4 +--
 packages/e2b/e2b/README.md                    |  2 +-
 packages/e2b/e2b/README.zh.md                 |  2 +-
 packages/e2b/e2b/src/index.ts                 | 23 +++++--------
 packages/e2b/e2b/tests/e2b.spec.ts            | 20 ++---------
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +--
 packages/e2b/subprocess-e2b/README.md         |  2 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  2 +-
 packages/e2b/subprocess-e2b/src/index.ts      |  6 ----
 packages/e2b/subprocess-e2b/src/process.ts    | 33 +++++--------------
 packages/e2b/subprocess-e2b/src/terminal.ts   |  9 +++--
 .../subprocess-e2b/tests/subprocess.spec.ts   | 27 ++++++++-------
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 17 ----------
 15 files changed, 48 insertions(+), 111 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 1d2a6d977c..87f545ee86 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,12 +14,12 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
   typert/      type graph generator, loader, and runtime registry
   llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
-  e2b/         E2B POC: sandbox owner + FS/subprocess adapters
+  e2b/         E2B POC: sandbox + FS/subprocess adapters
   bash/        bash executor seam + local impl + model-facing bash tools
   subprocess/  subprocess seam + local process-tree impl
   pty/         persistent PTY seam/backend/tools
-  fs/          filesystem seam + local impl + policy gate + read/write/edit tools
-  lsp/         language-server seam + local stdio provider + model-facing lsp tool
+  fs/          filesystem seam/backends/policy/tools
+  lsp/         language-server seam/local backend/tool
   skill/       skill provider registry + local impl + catalog/loader tool
   web/         web seam + search/fetch providers + model-facing web tools
   compact/     compaction seam + basic backend
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index db66ca5799..8af0e6ca30 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -591,7 +591,7 @@ Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout
 async getSandbox(): Promise<Sandbox>
 ```
 
-Source: [`packages/e2b/e2b/src/index.ts:76`](../../packages/e2b/e2b/src/index.ts)
+Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index c338fb0263..3587067d31 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 6045b313a91edafc25361eba3f3c4dacf56b4eb0
-README.zh.md: dc157d9b5167488530c7d63b59aed793ab6aa4c7
+README.md: 7ade7c3d6522d8fa6d54d7011766238451b17c9a
+README.zh.md: b683f33d2211106cf422e780b2b37904b0c640ad
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 6045b313a9..7ade7c3d65 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -26,7 +26,7 @@ Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapte
 
 Construction starts one sandbox creation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. Each adapter-internal E2B command shell receives a fresh randomized root-level `HOME`, so the SDK's fixed login shell does not resolve profile files from the mutable user home before the control command.
 
-Disposal first prevents new handle acquisition, then awaits setup and deletes the sandbox. A `SandboxNotFoundError` means expiry or another owner already deleted it and is accepted as quiescence. Initial directory setup failure also deletes the newly created sandbox; if that rollback fails, disposal retries it before releasing ownership. Provider plugins must load after this owner and dispose before it.
+Disposal first prevents new handle acquisition, then awaits setup and deletes the sandbox. A `SandboxNotFoundError` means expiry or another owner already deleted it and is accepted as quiescence. Initial directory setup failure makes one deletion attempt; the configured E2B timeout bounds a second failure. Provider plugins must load after this owner and dispose before it.
 
 ## Model Experience
 
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index dc157d9b51..b683f33d22 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -26,7 +26,7 @@
 
 构造阶段会启动一次沙箱创建。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。每个适配器内部的 E2B 命令 shell 都会获得一个位于根目录下、全新随机生成的 `HOME`，因此 SDK 固定使用的登录 shell 不会在控制命令之前解析可变用户主目录中的配置文件。
 
-资源释放会先阻止继续获取新句柄，再等待初始化完成，然后删除沙箱。`SandboxNotFoundError` 表示沙箱已因超时或被另一个所有者删除，因此可视为完全停稳。初始目录设置失败时也会删除新建沙箱；如果该回滚失败，资源释放会在解除所有权前重试。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+资源释放会先阻止继续获取新句柄，再等待初始化完成，然后删除沙箱。`SandboxNotFoundError` 表示沙箱已因超时或被另一个所有者删除，因此可视为完全停稳。初始目录设置失败时会尝试删除一次；若该尝试也失败，则由已配置的 E2B 超时约束沙箱的存活时间。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
 
 ## 模型体验
 
diff --git a/packages/e2b/e2b/src/index.ts b/packages/e2b/e2b/src/index.ts
index d6797b9147..906941d421 100644
--- a/packages/e2b/e2b/src/index.ts
+++ b/packages/e2b/e2b/src/index.ts
@@ -85,7 +85,6 @@ export class E2BSandboxService extends Service {
 
   private readonly config: ResolvedConfig
   private readonly ready: Promise<Sandbox>
-  private failedSetupSandbox: Sandbox | undefined
   private disposed = false
 
   constructor(ctx: Context, config: Config) {
@@ -108,21 +107,18 @@ export class E2BSandboxService extends Service {
 
     ctx.effect(() => async () => {
       this.disposed = true
-      let sandbox = this.failedSetupSandbox
-      if (sandbox === undefined) {
-        try {
-          sandbox = await this.ready
-        } catch {
-          sandbox = this.failedSetupSandbox
-        }
+      let sandbox: Sandbox
+      try {
+        sandbox = await this.ready
+      } catch (_sandboxSetupFailure) {
+        // open() either acquired no sandbox or already made the POC's one rollback attempt.
+        return
       }
-      if (sandbox === undefined) return
       try {
         await sandbox.kill()
       } catch (error: unknown) {
         if (!(error instanceof SandboxNotFoundError)) throw error
       }
-      this.failedSetupSandbox = undefined
     }, 'e2b sandbox teardown')
   }
 
@@ -174,10 +170,9 @@ export class E2BSandboxService extends Service {
     } catch (error: unknown) {
       try {
         await sandbox.kill()
-      } catch (_cleanupFailure) {
-        // Preserve the setup failure as the public error while retaining the
-        // created handle for the service disposer to retry this rollback.
-        this.failedSetupSandbox = sandbox
+      } catch (_sandboxSetupRollbackFailure) {
+        // TODO(e2b-setup-rollback): Add retry state only if a real double failure
+        // outlives E2B's configured sandbox timeout.
       }
       throw error
     }
diff --git a/packages/e2b/e2b/tests/e2b.spec.ts b/packages/e2b/e2b/tests/e2b.spec.ts
index e3a6c09039..b108bc68b0 100644
--- a/packages/e2b/e2b/tests/e2b.spec.ts
+++ b/packages/e2b/e2b/tests/e2b.spec.ts
@@ -180,7 +180,7 @@ describe('E2BSandboxService', () => {
     await fiber.dispose()
   })
 
-  it('preserves the setup failure even when cleanup also fails', async () => {
+  it('preserves the setup failure after its one rollback attempt fails', async () => {
     const fixture = fakeSandbox()
     fixture.run.mockRejectedValueOnce(new Error('chmod failed'))
     fixture.kill.mockRejectedValueOnce(new Error('cleanup failed'))
@@ -191,23 +191,7 @@ describe('E2BSandboxService', () => {
     expect(fixture.kill).toHaveBeenCalledOnce()
 
     await fiber.dispose()
-    expect(fixture.kill).toHaveBeenCalledTimes(2)
-  })
-
-  it.each([
-    ['retries a still-failing rollback', new Error('retry failed')],
-    ['accepts a setup sandbox that expired before retry', new SandboxNotFoundError('sandbox expired')],
-  ])('%s during disposal', async (_label, retryError) => {
-    const fixture = fakeSandbox()
-    fixture.run.mockRejectedValueOnce(new Error('chmod failed'))
-    fixture.kill.mockRejectedValueOnce(new Error('cleanup failed')).mockRejectedValueOnce(retryError)
-    sdk.create.mockResolvedValue(fixture.sandbox)
-    const ctx = new Context()
-    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
-
-    await expect(ctx.e2b.getSandbox()).rejects.toThrow('chmod failed')
-    await fiber.dispose()
-    expect(fixture.kill).toHaveBeenCalledTimes(2)
+    expect(fixture.kill).toHaveBeenCalledOnce()
   })
 
   it.each([
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 96fb24e21b..381ada5198 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 4e47566d55cf9400459993185f03482761c92096
-README.zh.md: 21ef231af700f72c2c5ec1fc651297ebdd17d49b
+README.md: 3ddfe5bc47309ba56d3f8af7720fcbe71ec8a302
+README.zh.md: c4db7bf8bb8a0f4b2f147dd22868978be5d1fcf4
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 4e47566d55..3ddfe5bc47 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -11,7 +11,7 @@ E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subpr
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
 - **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the sandbox user's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, fence publication, and retain an unproven setup cleanup for disposal retry. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, and fence publication; sandbox disposal or timeout bounds a setup rollback that also fails. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
 The default E2B base image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index 21ef231af7..c4db7bf8bb 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -11,7 +11,7 @@
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
 - **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变沙箱用户 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup、阻止发布，并保留未证明已完成的 setup 清理事务，供 dispose 重试。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup 并阻止发布；若 setup 回滚也失败，则由沙箱 dispose 或超时约束其存活时间。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
 E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 63cafcbfe0..976880ab01 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -29,7 +29,6 @@ export class E2BSubprocessService extends SubprocessService {
   private readonly live = new Set<E2BSubprocessHandle>()
   private readonly terminals = new Set<SubprocessTerminalHandle>()
   private readonly terminalSetups = new Map<Promise<void>, AbortController>()
-  private readonly failedTerminalSetupCleanups = new Set<() => Promise<void>>()
   private disposing = false
 
   /** @inheritdoc */
@@ -51,7 +50,6 @@ export class E2BSubprocessService extends SubprocessService {
       await Promise.all([...this.terminalSetups.keys()])
       const handles = [...this.live]
       const terminals = [...this.terminals]
-      const failedTerminalSetupCleanups = [...this.failedTerminalSetupCleanups]
       const pending: Promise<unknown>[] = []
       for (const handle of handles) {
         handle.terminate()
@@ -63,9 +61,6 @@ export class E2BSubprocessService extends SubprocessService {
       for (const terminal of terminals) {
         pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
       }
-      for (const cleanup of failedTerminalSetupCleanups) {
-        pending.push(cleanup().then(() => { this.failedTerminalSetupCleanups.delete(cleanup) }))
-      }
       const outcomes = await Promise.allSettled(pending)
       for (const outcome of outcomes) {
         if (outcome.status === 'rejected') throw outcome.reason
@@ -155,7 +150,6 @@ export class E2BSubprocessService extends SubprocessService {
         this.ctx.e2b,
         { ...spec, signal: setupSignal },
         stateDir,
-        (cleanup) => { this.failedTerminalSetupCleanups.add(cleanup) },
       )
       this.terminals.add(terminal)
       // oxlint-disable-next-line typescript/no-unnecessary-condition -- Remote allocation yields to disposal.
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index fe964a7395..c0aceda334 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -636,35 +636,18 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   }
 
   private async forceKillGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
-    let groupFailure: unknown
     try {
-      if (!await this.signalGroup(sandbox, processGroupId, 'KILL')) {
-        groupFailure = new Error('process-group KILL did not report delivery')
-      }
-    } catch (error: unknown) {
-      groupFailure = error
+      await this.signalGroup(sandbox, processGroupId, 'KILL')
+    } catch (_processGroupKillFailure) {
+      // SDK kill and the final liveness probe remain independent cleanup paths.
     }
-    let handleFailure: unknown
     try {
-      if (!await handle.kill()) handleFailure = new Error('E2B SDK kill did not report command termination')
-    } catch (error: unknown) {
-      handleFailure = error
+      await handle.kill()
+    } catch (_sdkKillFailure) {
+      // The final liveness probe, not either transport's self-report, proves cleanup.
     }
-    let proofFailure: unknown
-    try {
-      if (await this.waitForGroupExit(sandbox, processGroupId)) return
-      proofFailure = new Error(`remote process group ${processGroupId} remained live after force termination`)
-    } catch (error: unknown) {
-      proofFailure = error
-    }
-    throw new AggregateError(
-      [
-        ...(groupFailure === undefined ? [] : [groupFailure]),
-        ...(handleFailure === undefined ? [] : [handleFailure]),
-        proofFailure,
-      ],
-      'subprocess-e2b: force termination failed through both process-group and SDK transports',
-    )
+    if (await this.waitForGroupExit(sandbox, processGroupId)) return
+    throw new Error(`subprocess-e2b: remote process group ${processGroupId} remained live after force termination`)
   }
 
   private async waitForGroupExit(sandbox: Sandbox, processGroupId: number): Promise<boolean> {
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 3876191759..3108a4a60a 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -485,14 +485,12 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
  * @param runtime - Shared E2B sandbox owner.
  * @param spec - Fully specified terminal-process request.
  * @param stateDir - Private remote directory for one startup transaction.
- * @param retainFailedCleanup - Optional owner for retrying a cleanup transaction that could not prove quiescence.
  * @returns The live subprocess terminal handle.
  */
 export async function spawnE2BTerminal(
   runtime: E2BSandboxService,
   spec: SubprocessTerminalSpawnSpec,
   stateDir: string,
-  retainFailedCleanup?: (cleanup: () => Promise<void>) => void,
 ): Promise<E2BTerminalHandle> {
   const sandbox = await runtime.getSandbox()
   spec.signal?.throwIfAborted()
@@ -562,7 +560,7 @@ export async function spawnE2BTerminal(
     output.destroy()
     let terminalQuiescent = handle === undefined
     let stateRemoved = !stateDirectoryCreated
-    const retryCleanup = async (): Promise<void> => {
+    const cleanup = async (): Promise<void> => {
       const failures: Error[] = []
       if (!terminalQuiescent && handle !== undefined) {
         try {
@@ -588,9 +586,10 @@ export async function spawnE2BTerminal(
       }
     }
     try {
-      await retryCleanup()
+      await cleanup()
     } catch (cleanupError: unknown) {
-      retainFailedCleanup?.(retryCleanup)
+      // TODO(e2b-terminal-setup-rollback): Retain retry state only if a real
+      // double failure must be recovered before sandbox disposal or timeout.
       throw new AggregateError([asError(error), asError(cleanupError)], asError(error).message)
     }
     throw error
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index f7adf8183c..471716ef1a 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -808,7 +808,7 @@ describe('E2BSubprocessHandle', () => {
     await flush()
     handle.terminate()
     await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
     expect(fake.alive).toBe(true)
 
     fake.delaysKill = false
@@ -884,7 +884,7 @@ describe('E2BSubprocessHandle', () => {
 
     handle.terminate()
     await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
     fake.alive = false
     handle.terminate()
     await expect(handle.waitForExit()).resolves.toBe(true)
@@ -941,7 +941,7 @@ describe('E2BSubprocessHandle', () => {
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
 
     handle.terminate()
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
 
     fake.handle.killError = undefined
     handle.terminate()
@@ -960,7 +960,7 @@ describe('E2BSubprocessHandle', () => {
     )
     await vi.waitFor(() => { expect(absentGroup.startOptions).toBeDefined() })
     absentHandle.terminate()
-    await expect(absentHandle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(absentHandle.waitForExit()).rejects.toThrow('remained live after force termination')
     absentGroup.handle.killError = undefined
     absentHandle.terminate()
     await expect(absentHandle.waitForExit()).resolves.toBe(true)
@@ -978,7 +978,7 @@ describe('E2BSubprocessHandle', () => {
     )
     await vi.waitFor(() => { expect(optimisticSdk.startOptions).toBeDefined() })
     optimisticHandle.terminate()
-    await expect(optimisticHandle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(optimisticHandle.waitForExit()).rejects.toThrow('remained live after force termination')
     optimisticHandle.terminate()
     await expect(optimisticHandle.waitForExit()).resolves.toBe(true)
     optimisticSdk.releaseProcessGroupRead()
@@ -1322,7 +1322,7 @@ describe('E2BSubprocessHandle', () => {
     await expect(absent.waitForExit()).resolves.toBe(true)
   })
 
-  it('preserves publication and rollback failures when cleanup cannot be verified', async () => {
+  it('preserves publication failure and reports cleanup that cannot be verified', async () => {
     const fake = new FakeSandbox()
     fake.processGroupId = 'not-a-pid\n'
     fake.signalError = new Error('rollback signal failed')
@@ -1341,11 +1341,10 @@ describe('E2BSubprocessHandle', () => {
     const failures = Array.from(failure.errors as Iterable<unknown>)
     expect(failures).toHaveLength(2)
     expect(failures[0]).toBeInstanceOf(Error)
-    expect(failures[1]).toBeInstanceOf(AggregateError)
-    if (!(failures[0] instanceof Error) || !(failures[1] instanceof AggregateError)) throw new Error('expected nested errors')
+    expect(failures[1]).toBeInstanceOf(Error)
+    if (!(failures[0] instanceof Error) || !(failures[1] instanceof Error)) throw new Error('expected nested errors')
     expect(failures[0].message).toContain('invalid process-group id')
-    expect(failures[1].message).toBe('subprocess-e2b: force termination failed through both process-group and SDK transports')
-    expect(Array.from(failures[1].errors as Iterable<unknown>)).toContainEqual(new Error('rollback signal failed'))
+    expect(failures[1].message).toContain('remained live after force termination')
     expect(fake.handle.kills).toBe(1)
     const bounded = new AbortController()
     const waiting = handle.waitForExit(bounded.signal)
@@ -1494,7 +1493,7 @@ describe('E2BSubprocessHandle', () => {
     await flush()
 
     handle.terminate()
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
     fake.handle.killError = undefined
     handle.terminate()
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
@@ -1507,7 +1506,7 @@ describe('E2BSubprocessHandle', () => {
     const raced = new E2BSubprocessHandle(runtime(missingGroup), spec({ graceMs: 1 }), '/runtime/group-exit-race')
     await flush()
     raced.terminate()
-    await expect(raced.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(raced.waitForExit()).rejects.toThrow('remained live after force termination')
     missingGroup.handle.killError = undefined
     raced.terminate()
     await expect(raced.waitForExit()).resolves.toBe(true)
@@ -1522,7 +1521,7 @@ describe('E2BSubprocessHandle', () => {
     await flush()
 
     handle.terminate()
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
     expect(fake.alive).toBe(true)
 
     fake.sdkKillStops = true
@@ -1581,7 +1580,7 @@ describe('E2BSubprocessService', () => {
     await flush()
 
     await expect(fiber.dispose()).resolves.toBeUndefined()
-    await expect(handle.waitForExit()).rejects.toThrow('force termination failed through both')
+    await expect(handle.waitForExit()).rejects.toThrow('remained live after force termination')
 
     fake.handle.killError = undefined
     handle.terminate()
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 08d49bb87b..067910a10b 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -871,23 +871,6 @@ describe('E2B subprocess terminal service', () => {
     expect(fake.createOptions).toBeUndefined()
   })
 
-  it('retains failed terminal setup cleanup for disposal retry', async () => {
-    const fake = new FakeTerminalSandbox()
-    fake.sendError = new Error('bootstrap failed')
-    fake.clearOnTerm = false
-    fake.clearOnKill = false
-    const { ctx, fiber } = await service(fake)
-
-    await expect(ctx.subprocess.spawnTerminal(spec({ graceMs: 1 }))).rejects.toThrow('bootstrap failed')
-    expect(fake.groups).toEqual([123])
-    expect(fake.handle.disconnects).toBe(0)
-
-    fake.clearOnKill = true
-    await fiber.dispose()
-    expect(fake.groups).toEqual([])
-    expect(fake.handle.disconnects).toBe(1)
-  })
-
   it('releases naturally settled terminals and validates terminal requests', async () => {
     const { ctx, fiber, fake } = await service()
     for (const request of [

From 258bd4456b21bb037583d696b351a2fbb6ceb6e9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 06:02:22 +0800
Subject: [PATCH 386/516] test(e2b): poll sandbox list convergence

---
 packages/e2b/e2b/tests/composition.e2e.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 2eca4f1f63..bf53ba7bb9 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -178,6 +178,9 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
     await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
-    await expect(Sandbox.list({ apiKey }).nextItems()).resolves.toEqual([])
+    await expect.poll(async () => {
+      const sandboxes = await Sandbox.list({ apiKey }).nextItems()
+      return sandboxes.some(sandbox => sandbox.sandboxId === output.sandboxId)
+    }, { interval: 250, timeout: 5_000 }).toBe(false)
   }, 195_000)
 })

From 26b18ba189715c8a4ff40cb785c34daf83957e53 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 14:50:47 +0800
Subject: [PATCH 387/516] refactor(e2b): keep code runtime host-local

---
 ...rtable-execution-world-consumers.i18n.yaml |  4 +-
 ...7-28-portable-execution-world-consumers.md |  6 +--
 ...8-portable-execution-world-consumers.zh.md |  6 +--
 examples/headless-agent/e2b.cordis.yml        |  7 +--
 .../tests/fixtures/e2b/e2b/bin.ts             | 51 -------------------
 .../tests/fixtures/e2b/e2b/cordis.yml         |  9 ----
 packages/README.i18n.yaml                     |  4 +-
 packages/e2b/README.i18n.yaml                 |  4 +-
 packages/e2b/README.md                        |  2 +-
 packages/e2b/README.zh.md                     |  2 +-
 packages/e2b/e2b/README.i18n.yaml             |  4 +-
 packages/e2b/e2b/README.md                    |  2 +-
 packages/e2b/e2b/README.zh.md                 |  2 +-
 packages/e2b/e2b/tests/composition.e2e.ts     | 11 +---
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         |  2 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  2 +-
 packages/e2b/subprocess-e2b/src/index.ts      | 14 ++---
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  4 +-
 19 files changed, 29 insertions(+), 111 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index c7ce82595d..fb8a3344c1 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: 57c3a8a8b211279593359b02def865644052f549
-2026-07-28-portable-execution-world-consumers.zh.md: 8231913c26f75361add7a28bc40f7723c9b18728
+2026-07-28-portable-execution-world-consumers.md: fcc30d553f07a28b44227f614f62c2027f8f3dd3
+2026-07-28-portable-execution-world-consumers.zh.md: 5e1e73aee7b96ffe1ae9862f72114a48152ad218
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index 6f296bfa74..fcc30d553f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-28-portable-execution-world-consumers.zh.md)
 
 The filesystem and subprocess seams made file and ordinary process access replaceable, but PTY and LSP still reached host Node APIs directly. A remote execution provider therefore appeared to need separate PTY and LSP packages even though their domain behavior did not change. Those packages would be shallow adapters: each would duplicate an existing consumer merely to replace its file and process operations.
 
-A remote coding world is useful only when file operations, commands, terminals, language servers, and model-written programs share one sandbox identity. Moving the complete harness into that sandbox would also entangle provider experimentation with plugin loading, credentials, model transport, session durability, supervision, and deployment.
+A remote coding world is useful only when file operations, commands, terminals, and language servers share one sandbox identity. Moving the complete harness into that sandbox would also entangle provider experimentation with plugin loading, credentials, model transport, session durability, supervision, and deployment.
 
 Ordinary pipes do not cover one requirement. A persistent terminal needs PTY allocation, foreground-process-group inspection and signalling, and cleanup of the complete terminal session. Pretending those operations can be rebuilt in `dsh-pty-local` from an ordinary `spawn()` handle would either leak provider internals or weaken its lifecycle contract.
 
@@ -30,7 +30,7 @@ Generic consumers use that execution world:
 
 The opt-in E2B realization has exactly three provider-specific packages under `packages/e2b/`: `dsh-e2b` creates one sandbox and deletes it on timeout or disposal, `dsh-fs-e2b` implements `ctx.fs`, and `dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, PTYs, and remote Linux process groups. The two adapters obtain the sole SDK handle from the owner and never create private sandboxes.
 
-E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, subprocess Code Runtime processes, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, Code Runtime program/binding/output policy, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
+E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, the worker-backed Code Runtime and its program/binding/output policy, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
 
 The adapters retain only substrate mechanics. Filesystem canonicalization crosses the SDK's decoded command transport as strict base64-encoded NUL framing; streamed reads leave byte ceilings with consumers. Subprocess command output and environment snapshots use ASCII/base64 where SDK chunk decoding would otherwise lose bytes, while private control shells isolate profiles and later launches blank discovered credential-shaped names. Process and terminal cleanup uses remote groups and proves quiescence before settlement.
 
@@ -38,7 +38,7 @@ Sandbox state is deliberately ephemeral: timeout and disposal delete the remote
 
 ## Verification
 
-Focused package suites pin sandbox lifecycle, canonical path framing, filesystem metadata and atomic versions, subprocess publication/rollback, terminal text I/O and session cleanup, output limits, cancellation, disposal, and invariant registration. A credential-gated Loader composition exercises the same three-package provider through source imports and built exports, including FS/Bash visibility, hostile login profiles, byte-split UTF-8 output, process and terminal cleanup, LSP queries, Code Runtime bindings and cleanup, host-workspace isolation, and final sandbox deletion.
+Focused package suites pin sandbox lifecycle, canonical path framing, filesystem metadata and atomic versions, subprocess publication/rollback, terminal text I/O and session cleanup, output limits, cancellation, disposal, and invariant registration. A credential-gated Loader composition exercises the same three-package provider through source imports and built exports, including FS/Bash visibility, hostile login profiles, byte-split UTF-8 output, process and terminal cleanup, LSP queries, host-workspace isolation, and final sandbox deletion.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 471753573d..2ab0685a1d 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但若干上层能力仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY、LSP 与代码运行时包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
 
-只有文件操作、命令、终端、语言服务器和模型编写的程序共享同一个沙箱身份时，远程编码世界才有用。若把完整 harness 移入该沙箱，还会把提供方实验与插件加载、凭据、模型传输、会话持久性、监督和部署纠缠在一起。
+只有文件操作、命令、终端和语言服务器共享同一个沙箱身份时，远程编码世界才有用。若把完整 harness 移入该沙箱，还会把提供方实验与插件加载、凭据、模型传输、会话持久性、监督和部署纠缠在一起。
 
 普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期契约。
 
@@ -33,7 +33,7 @@ Status: implemented
 
 可选启用的 E2B 实现在 `packages/e2b/` 下恰好只有三个提供方专用包：`dsh-e2b` 创建一个沙箱，并在超时或资源释放时将其删除；`dsh-fs-e2b` 实现 `ctx.fs`；`dsh-subprocess-e2b` 基于 E2B Commands、PTY 和远程 Linux 进程组实现 `ctx.subprocess`。两个适配器都从所有者取得唯一的 SDK 句柄，绝不创建私有沙箱。
 
-E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取、子进程代码运行时进程，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态、代码运行时程序／绑定／输出策略，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
+E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态、基于 worker 的代码运行时及其程序／绑定／输出策略，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
 
 适配器只保留执行基底机制。文件系统规范化以严格的 base64 加 NUL 分帧穿过 SDK 已解码的命令传输；流式读取把字节上限留给消费方执行。进程管理命令输出与环境快照采用 ASCII/base64，避免 SDK 分片解码丢失字节；私有控制 shell 隔离 profile，后续启动会把已发现且名称呈凭据特征的环境变量置空。进程与终端清理使用远程进程组，并在结算前证明完全停稳。
 
@@ -41,7 +41,7 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 ## 验证
 
-聚焦的包测试套件锁定了沙箱生命周期、规范化路径分帧、文件系统元数据与原子版本、进程管理发布／回滚、终端文本 I/O 与会话清理、输出上限、取消、资源释放和不变式注册。一项受凭据门控的 Loader 组合通过源代码导入与构建后导出运行同一套三包提供方组合，其中包括 FS/Bash 可见性、恶意登录 profile、跨字节边界拆分的 UTF-8 输出、进程与终端清理、LSP 查询、代码运行时绑定与清理、宿主工作区隔离，以及最终沙箱删除。
+聚焦的包测试套件锁定了沙箱生命周期、规范化路径分帧、文件系统元数据与原子版本、进程管理发布／回滚、终端文本 I/O 与会话清理、输出上限、取消、资源释放和不变式注册。一项受凭据门控的 Loader 组合通过源代码导入与构建后导出运行同一套三包提供方组合，其中包括 FS/Bash 可见性、恶意登录 profile、跨字节边界拆分的 UTF-8 输出、进程与终端清理、LSP 查询、宿主工作区隔离，以及最终沙箱删除。
 
 ## 考虑过的替代方案
 
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index 724f30240d..a65b0baf81 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -1,6 +1,6 @@
 # POC overlay: keep the advanced headless agent and model-facing tools, but
 # place its filesystem and process substrate in one short-lived E2B sandbox;
-# the generic Bash, PTY, LSP, and Code Runtime consumers compose above them.
+# the generic Bash, PTY, and LSP consumers compose above them.
 - id: base
   name: '@cordisjs/plugin-include'
   config:
@@ -12,9 +12,6 @@
       - id: fs-local
         name: '@deepseek-ai/dsh-fs-local'
         disabled: true
-      - id: code-runtime
-        name: '@deepseek-ai/dsh-code-runtime-worker'
-        disabled: true
       - insert:
           - id: e2b
             name: '@deepseek-ai/dsh-e2b'
@@ -25,8 +22,6 @@
             name: '@deepseek-ai/dsh-subprocess-e2b'
           - id: fs-e2b
             name: '@deepseek-ai/dsh-fs-e2b'
-          - id: code-runtime-subprocess
-            name: '@deepseek-ai/dsh-code-runtime-subprocess'
           - id: sandbox-policy
             name: '@deepseek-ai/dsh-sandbox-policy'
             config:
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 570a244e88..7348d1d181 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -3,7 +3,6 @@ import { resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-code-runtime-subprocess'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
 import type {} from '@deepseek-ai/dsh-bash-local'
 import type {} from '@deepseek-ai/dsh-lsp-local'
@@ -175,52 +174,6 @@ try {
   const terminalTreeCleanup = stubbornProbe.stdout === 'gone'
   if (!terminalTreeCleanup) throw new Error(`E2B PTY left process ${stubbornPid} alive after close`)
 
-  const code = await ctx.codeRuntime.run({
-    program: `
-      console.log('remote-log 你好', 42)
-      const doubled: number = await bridge.double({ value: 21 })
-      let typed = false
-      try {
-        await bridge.fail({ reason: 'expected' })
-      } catch (error) {
-        typed = error instanceof BridgeError && (error as { member: string }).member === 'fail'
-      }
-      return { doubled, typed }
-    `,
-    bindings: [{
-      global: 'bridge',
-      errorClass: { name: 'BridgeError', memberNameProperty: 'member' },
-      functions: {
-        double: async (args) => {
-          const value = (args as { value: number }).value
-          return value * 2
-        },
-        fail: async () => { throw new Error('binding rejected') },
-      },
-    }],
-  })
-  const descendantPipe = await ctx.codeRuntime.run({
-    program: `
-      const childProcess = await import('node:child_process')
-      const child = childProcess.spawn(
-        process.execPath,
-        ['-e', 'setInterval(() => {}, 1000)', 'dsh-code-runtime-descendant'],
-        { stdio: ['ignore', 'inherit', 'inherit'] },
-      )
-      return child.pid > 0
-    `,
-    bindings: [],
-  })
-  const descendantProcesses = await sandbox.commands.list()
-  const descendantCleanup = !descendantProcesses.some(processInfo =>
-    JSON.stringify([processInfo.cmd, processInfo.args]).includes('dsh-code-runtime-descendant'),
-  )
-  if (!descendantCleanup) throw new Error('E2B Code Runtime left a pipe-holding descendant alive')
-  const remoteProcesses = await (await ctx.e2b.getSandbox()).commands.list()
-  const lingeringCodeRunners = remoteProcesses.filter(processInfo =>
-    JSON.stringify([processInfo.cmd, processInfo.args]).includes('code-runtime-runner.mjs'),
-  )
-
   process.stdout.write(`${JSON.stringify({
     sandboxId: (await ctx.e2b.getSandbox()).sandboxId,
     bashRead: bashRead.stdout.text,
@@ -237,10 +190,6 @@ try {
       treeCleanup: terminalTreeCleanup,
       scrollback: terminalScrollback.text,
     },
-    code,
-    descendantPipe,
-    descendantCleanup,
-    lingeringCodeRunners: lingeringCodeRunners.length,
   })}\n`)
 } finally {
   if (terminalId !== undefined) await ctx.pty.kill(owner, terminalId, 'fixture cleanup').catch(() => false)
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 043362aaa1..3a6deb7e49 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -52,12 +52,3 @@
           .ts: typescript
         shutdownTimeoutMs: 1000
         killGraceMs: 500
-
-- id: code-runtime-subprocess
-  name: '@deepseek-ai/dsh-code-runtime-subprocess'
-  config:
-    computeMs: 500
-    maxWallMs: 15000
-    maxOutputBytes: 4096
-    maxOldGenerationSizeMb: 128
-    killGraceMs: 500
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index f101375bc6..ce95627688 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 1fd0c9c2385f3169791a28f3ef50bb42792760af
-README.zh.md: f9f7d5ae8839ea7033a349ac7a0083a97780a21c
+README.md: a9a121d0cb13cd5e2148da8d754967359be06bab
+README.zh.md: c6500ebb2abce14fabf68b79ec20f5c23cf5d5f7
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index 6b1dc7506b..b93f48d8cd 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: 3c85b2790d3414af73625e65732df58ff9fec566
-README.zh.md: a759539fc054dd68e75f3c7660ccc3b762985af5
+README.md: adc002649e44faefd2f6bd84b7b45fb9fc6fa41d
+README.zh.md: d941de8da2cb831a69a165c86a825def68c2b319
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index 3c85b2790d..adc002649e 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -10,6 +10,6 @@ An experimental provider-composition POC that places one filesystem/process exec
 | [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
 | [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement executable lookup, managed process groups and stdio, remote spill files, and terminal sessions over E2B Commands and PTY APIs |
 
-The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), [`dsh-lsp-local`](../lsp/lsp-local/README.md), and [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox.
+The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), and [`dsh-lsp-local`](../lsp/lsp-local/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox. The worker-backed Code Runtime remains host-local and reaches that world only through the tools its programs call.
 
 This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [portable execution-world decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns both the generic composition and this POC boundary.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index a759539fc0..d941de8da2 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -10,6 +10,6 @@
 | [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
 | [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 与 PTY API 实现可执行文件查找、受管进程组与 stdio、远程 spill 文件及终端会话 |
 
-现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md)、[`dsh-lsp-local`](../lsp/lsp-local/README.md) 及 [`dsh-code-runtime-subprocess`](../code-runtime/code-runtime-subprocess/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md) 和 [`dsh-lsp-local`](../lsp/lsp-local/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。基于 worker 的代码运行时仍在宿主本地运行，只会通过其程序调用的工具触达该执行世界。
 
 该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[可移植执行世界决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)同时界定通用组合和此 POC 边界。
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 3587067d31..0256b3ccfe 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 7ade7c3d6522d8fa6d54d7011766238451b17c9a
-README.zh.md: b683f33d2211106cf422e780b2b37904b0c640ad
+README.md: 52f99178ce8c06e61c13ea9364769ac887db4410
+README.zh.md: 98ba7e79841f548ff6465fda4bc37170c17bc6e0
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 7ade7c3d65..52f99178ce 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -38,7 +38,7 @@ No direct invalidation; this package does not contribute request tokens.
 
 ## Known Limitations and Deferred Work
 
-- **This is not a whole-harness runtime** — Cordis services, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
+- **This is not a whole-harness runtime** — Cordis services, the worker-backed Code Runtime, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
 - **Sandbox state is ephemeral** — disposal and timeout delete the sandbox; reconnect, pause/leave retention, templates, volumes, and snapshots are outside this POC.
 - **No deployment platform is configured** — network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
 - **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access retains the base image's policy.
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index b683f33d22..98ba7e7984 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -38,7 +38,7 @@
 
 ## 已知限制与延后工作
 
-- **这不是完整的 harness 运行时**：Cordis 服务、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
+- **这不是完整的 harness 运行时**：Cordis 服务、基于 worker 的代码运行时、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
 - **沙箱状态是短暂的**：资源释放和超时都会删除沙箱；重新连接、pause/leave 保留、模板、卷和快照均不在本 POC 范围内。
 - **没有配置部署平台**：网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
 - **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用基础镜像的策略。
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index bf53ba7bb9..3f0b69668d 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -57,7 +57,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       const ptyFiber = await ctx.plugin(PtyService)
       const subprocessFiber = await ctx.plugin(E2BSubprocessService)
       const node = await ctx.subprocess.resolveExecutable('node')
-      const relativeNodePath = posix.relative(ctx.subprocess.cwd, posix.dirname(node)) || '.'
+      const relativeNodePath = posix.relative(ctx.e2b.cwd, posix.dirname(node)) || '.'
       await expect(ctx.subprocess.resolveExecutable('node', { PATH: relativeNodePath })).resolves.toBe(node)
       await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
       const environmentProbe = ctx.subprocess.spawn({
@@ -117,7 +117,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     }
   }, 70_000)
 
-  it('runs FS, Bash, PTY, LSP, and Code Runtime in one sandbox and deletes it', async () => {
+  it('runs FS, Bash, PTY, and LSP in one sandbox and deletes it', async () => {
     const { stdout, stderr } = await runLoaderSmoke({
       label: 'E2B composition',
       tempDirPrefix: 'dsh-e2b-composition-',
@@ -157,9 +157,6 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         interrupted: { sessionStatus: { kind: 'running' } },
         treeCleanup: true,
       },
-      descendantPipe: { value: true, logs: [] },
-      descendantCleanup: true,
-      lingeringCodeRunners: 0,
     })
     const terminalMotd = (output.terminal as { motd: string }).motd
     expect(terminalMotd.length).toBeGreaterThan(0)
@@ -171,10 +168,6 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
     expect(['stdin_read', 'inferred_idle']).toContain(
       (output.terminal as { interrupted: { waitReason: string } }).interrupted.waitReason,
     )
-    expect(output.code).toEqual({
-      value: { doubled: 42, typed: true },
-      logs: ['remote-log 你好 42'],
-    })
     const apiKey = process.env.E2B_API_KEY
     if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
     await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 381ada5198..0a18bf24a1 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 3ddfe5bc47309ba56d3f8af7720fcbe71ec8a302
-README.zh.md: c4db7bf8bb8a0f4b2f147dd22868978be5d1fcf4
+README.md: 3bb9802c3afa41f3949fceeb73e76ea5cebce744
+README.zh.md: 520f0ea1cde18ed523ba80015d3d4700730aba7a
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 3ddfe5bc47..3bb9802c3a 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, LSP, and subprocess Code Runtime consumers then execute in the shared remote sandbox without E2B-specific capability packages.
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, and LSP consumers then execute in the shared remote sandbox without E2B-specific capability packages.
 
 ## Behavior
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index c4db7bf8bb..520f0ea1cd 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY、LSP 以及使用 subprocess 的 Code Runtime 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
+[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY 和 LSP 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
 
 ## 行为
 
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 976880ab01..15e7feccdd 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -31,17 +31,9 @@ export class E2BSubprocessService extends SubprocessService {
   private readonly terminalSetups = new Map<Promise<void>, AbortController>()
   private disposing = false
 
-  /** @inheritdoc */
-  readonly cwd: string
-
-  /** @inheritdoc */
-  readonly runtimeRoot: string
-
   /** Create the E2B subprocess service and bind its disposal policy. */
   constructor(ctx: Context) {
     super(ctx)
-    this.cwd = ctx.e2b.cwd
-    this.runtimeRoot = ctx.e2b.runtimeRoot
     ctx.effect(() => async () => {
       this.disposing = true
       for (const controller of this.terminalSetups.values()) {
@@ -89,14 +81,14 @@ export class E2BSubprocessService extends SubprocessService {
     const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
     const result = await sandbox.commands.run(
       `${prefix}command -v -- ${quoteE2BShellArg(command)}`,
-      { cwd: this.cwd, envs: e2bControlEnvs(), ...signalOpts(signal) },
+      { cwd: this.ctx.e2b.cwd, envs: e2bControlEnvs(), ...signalOpts(signal) },
     )
     signal?.throwIfAborted()
     const executable = result.stdout.trim()
     if (executable.includes('\n') || (!posix.isAbsolute(executable) && !executable.includes('/'))) {
       throw new Error(`subprocess-e2b: executable ${JSON.stringify(command)} did not resolve to one absolute path`)
     }
-    return posix.resolve(this.cwd, executable)
+    return posix.resolve(this.ctx.e2b.cwd, executable)
   }
 
   /** @inheritdoc */
@@ -138,7 +130,7 @@ export class E2BSubprocessService extends SubprocessService {
       }
     }
     spec.signal?.throwIfAborted()
-    const stateDir = posix.join(this.runtimeRoot, 'terminals', randomUUID())
+    const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'terminals', randomUUID())
     const setup = Promise.withResolvers<void>()
     const setupController = new AbortController()
     const setupSignal = spec.signal === undefined
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 067910a10b..9973b5151a 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -775,10 +775,8 @@ describe('E2B subprocess terminal service', () => {
     return { ctx, fiber, fake }
   }
 
-  it('publishes execution-world coordinates and resolves remote executables', async () => {
+  it('resolves remote executables', async () => {
     const { ctx, fake } = await service()
-    expect(ctx.subprocess.cwd).toBe('/workspace')
-    expect(ctx.subprocess.runtimeRoot).toBe('/workspace/.dsh-e2b')
     await expect(ctx.subprocess.resolveExecutable('/bin/bash')).resolves.toBe('/bin/bash')
     await expect(ctx.subprocess.resolveExecutable('node', { PATH: '/custom/bin' }, new AbortController().signal))
       .resolves.toBe('/usr/bin/node')

From e6b3afbee9078429f18a11ce30b2c869e5532545 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 20:02:38 +0800
Subject: [PATCH 388/516] docs(e2b): remove code runtime residue

---
 .../2026-07-28-portable-execution-world-consumers.i18n.yaml   | 4 ++--
 .../2026-07-28-portable-execution-world-consumers.md          | 2 +-
 .../2026-07-28-portable-execution-world-consumers.zh.md       | 2 +-
 packages/e2b/README.i18n.yaml                                 | 4 ++--
 packages/e2b/README.md                                        | 2 +-
 packages/e2b/README.zh.md                                     | 2 +-
 packages/e2b/e2b/README.i18n.yaml                             | 4 ++--
 packages/e2b/e2b/README.md                                    | 2 +-
 packages/e2b/e2b/README.zh.md                                 | 2 +-
 9 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index fb8a3344c1..8cd6ad419a 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.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 .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
-2026-07-28-portable-execution-world-consumers.md: fcc30d553f07a28b44227f614f62c2027f8f3dd3
-2026-07-28-portable-execution-world-consumers.zh.md: 5e1e73aee7b96ffe1ae9862f72114a48152ad218
+2026-07-28-portable-execution-world-consumers.md: 2cfdf08ac369048994ebc64d498caaa0847b77de
+2026-07-28-portable-execution-world-consumers.zh.md: ce6650a284e7d64fb1277c758bb77c2394e942c8
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
index fcc30d553f..2cfdf08ac3 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
@@ -30,7 +30,7 @@ Generic consumers use that execution world:
 
 The opt-in E2B realization has exactly three provider-specific packages under `packages/e2b/`: `dsh-e2b` creates one sandbox and deletes it on timeout or disposal, `dsh-fs-e2b` implements `ctx.fs`, and `dsh-subprocess-e2b` implements `ctx.subprocess` over E2B Commands, PTYs, and remote Linux process groups. The two adapters obtain the sole SDK handle from the owner and never create private sandboxes.
 
-E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, the worker-backed Code Runtime and its program/binding/output policy, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
+E2B owns the mutable filesystem, managed command and Bash processes, terminal allocation and terminal-session groups, language-server processes and source reads, and adapter-private files under `.dsh-e2b`. The host owns Cordis and plugin objects, the agent loop, agent/session/goal state, session logs and persistence, LLM calls, prompts and tools, authority, skills, subagent orchestration, PTY buffers and readiness, LSP protocol state, and E2B SDK/network buffers. The overlay neither uploads nor synchronizes the host workspace.
 
 The adapters retain only substrate mechanics. Filesystem canonicalization crosses the SDK's decoded command transport as strict base64-encoded NUL framing; streamed reads leave byte ceilings with consumers. Subprocess command output and environment snapshots use ASCII/base64 where SDK chunk decoding would otherwise lose bytes, while private control shells isolate profiles and later launches blank discovered credential-shaped names. Process and terminal cleanup uses remote groups and proves quiescence before settlement.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 2ab0685a1d..68d022216c 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -33,7 +33,7 @@ Status: implemented
 
 可选启用的 E2B 实现在 `packages/e2b/` 下恰好只有三个提供方专用包：`dsh-e2b` 创建一个沙箱，并在超时或资源释放时将其删除；`dsh-fs-e2b` 实现 `ctx.fs`；`dsh-subprocess-e2b` 基于 E2B Commands、PTY 和远程 Linux 进程组实现 `ctx.subprocess`。两个适配器都从所有者取得唯一的 SDK 句柄，绝不创建私有沙箱。
 
-E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态、基于 worker 的代码运行时及其程序／绑定／输出策略，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
+E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终端会话组、语言服务器进程与源文件读取，以及 `.dsh-e2b` 下的适配器私有文件。宿主负责 Cordis 与插件对象、agent loop（智能体循环）、agent（智能体）状态、会话状态与目标状态、会话日志与持久化、LLM（大语言模型）调用、提示词与工具、权限、skill（技能）、subagent 编排、PTY 缓冲区与就绪状态、LSP 协议状态，以及 E2B SDK／网络缓冲区。该叠加层既不上传，也不同步宿主工作区。
 
 适配器只保留执行基底机制。文件系统规范化以严格的 base64 加 NUL 分帧穿过 SDK 已解码的命令传输；流式读取把字节上限留给消费方执行。进程管理命令输出与环境快照采用 ASCII/base64，避免 SDK 分片解码丢失字节；私有控制 shell 隔离 profile，后续启动会把已发现且名称呈凭据特征的环境变量置空。进程与终端清理使用远程进程组，并在结算前证明完全停稳。
 
diff --git a/packages/e2b/README.i18n.yaml b/packages/e2b/README.i18n.yaml
index b93f48d8cd..4125487253 100644
--- a/packages/e2b/README.i18n.yaml
+++ b/packages/e2b/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/e2b/README.md
-README.md: adc002649e44faefd2f6bd84b7b45fb9fc6fa41d
-README.zh.md: d941de8da2cb831a69a165c86a825def68c2b319
+README.md: f9758e2748aaa2acffb0e928752b2b0fb70cd0a4
+README.zh.md: de068c16d4309499f5dcaa2d08cd9b6cc3023d94
diff --git a/packages/e2b/README.md b/packages/e2b/README.md
index adc002649e..f9758e2748 100644
--- a/packages/e2b/README.md
+++ b/packages/e2b/README.md
@@ -10,6 +10,6 @@ An experimental provider-composition POC that places one filesystem/process exec
 | [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
 | [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement executable lookup, managed process groups and stdio, remote spill files, and terminal sessions over E2B Commands and PTY APIs |
 
-The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), and [`dsh-lsp-local`](../lsp/lsp-local/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox. The worker-backed Code Runtime remains host-local and reaches that world only through the tools its programs call.
+The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), and [`dsh-lsp-local`](../lsp/lsp-local/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox.
 
 This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [portable execution-world decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns both the generic composition and this POC boundary.
diff --git a/packages/e2b/README.zh.md b/packages/e2b/README.zh.md
index d941de8da2..de068c16d4 100644
--- a/packages/e2b/README.zh.md
+++ b/packages/e2b/README.zh.md
@@ -10,6 +10,6 @@
 | [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
 | [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 与 PTY API 实现可执行文件查找、受管进程组与 stdio、远程 spill 文件及终端会话 |
 
-现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md) 和 [`dsh-lsp-local`](../lsp/lsp-local/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。基于 worker 的代码运行时仍在宿主本地运行，只会通过其程序调用的工具触达该执行世界。
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md) 和 [`dsh-lsp-local`](../lsp/lsp-local/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。
 
 该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[可移植执行世界决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)同时界定通用组合和此 POC 边界。
diff --git a/packages/e2b/e2b/README.i18n.yaml b/packages/e2b/e2b/README.i18n.yaml
index 0256b3ccfe..3587067d31 100644
--- a/packages/e2b/e2b/README.i18n.yaml
+++ b/packages/e2b/e2b/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/e2b/e2b/README.md
-README.md: 52f99178ce8c06e61c13ea9364769ac887db4410
-README.zh.md: 98ba7e79841f548ff6465fda4bc37170c17bc6e0
+README.md: 7ade7c3d6522d8fa6d54d7011766238451b17c9a
+README.zh.md: b683f33d2211106cf422e780b2b37904b0c640ad
diff --git a/packages/e2b/e2b/README.md b/packages/e2b/e2b/README.md
index 52f99178ce..7ade7c3d65 100644
--- a/packages/e2b/e2b/README.md
+++ b/packages/e2b/e2b/README.md
@@ -38,7 +38,7 @@ No direct invalidation; this package does not contribute request tokens.
 
 ## Known Limitations and Deferred Work
 
-- **This is not a whole-harness runtime** — Cordis services, the worker-backed Code Runtime, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
+- **This is not a whole-harness runtime** — Cordis services, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
 - **Sandbox state is ephemeral** — disposal and timeout delete the sandbox; reconnect, pause/leave retention, templates, volumes, and snapshots are outside this POC.
 - **No deployment platform is configured** — network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
 - **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access retains the base image's policy.
diff --git a/packages/e2b/e2b/README.zh.md b/packages/e2b/e2b/README.zh.md
index 98ba7e7984..b683f33d22 100644
--- a/packages/e2b/e2b/README.zh.md
+++ b/packages/e2b/e2b/README.zh.md
@@ -38,7 +38,7 @@
 
 ## 已知限制与延后工作
 
-- **这不是完整的 harness 运行时**：Cordis 服务、基于 worker 的代码运行时、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
+- **这不是完整的 harness 运行时**：Cordis 服务、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
 - **沙箱状态是短暂的**：资源释放和超时都会删除沙箱；重新连接、pause/leave 保留、模板、卷和快照均不在本 POC 范围内。
 - **没有配置部署平台**：网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
 - **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用基础镜像的策略。

From f5866fc2023c2c190f61229a8da4aaf917e55a4a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 15:38:00 +0800
Subject: [PATCH 389/516] fix(e2b): address review round on cadence config,
 disposal, and SDK edge cases

- subprocess-e2b: the 20 ms remote poll cadence becomes a validated pollMs
  Config field (each tick is one control-plane request); the README documents
  the latency-versus-request-count trade.
- subprocess-e2b: extract src/remote.ts owning asError, signalOpts,
  commandOpts, delay, waitTick, and one tolerant signalRemoteGroups shared by
  the pgid-keyed process ladder and sid-keyed terminal ladder, so the two
  teardown paths keep identical error tolerance.
- subprocess-e2b: service disposal aggregates sibling cleanup failures into
  one AggregateError instead of discarding all but the first.
- subprocess-e2b: waitForProcessGroupId refuses published group ids <= 1, so
  a same-UID rewrite of the pid file cannot aim termination at kill -- -1;
  README documents the same-UID control-state limitation.
- subprocess-e2b: drain-grace expiry now releases an inherited-output E2B
  callback blocked on host backpressure before disconnecting, so the SDK
  settlement cannot stay pinned behind an unread host stream.
- subprocess-e2b: spawn/spawnTerminal stop validating typed spec fields
  (trust-TypeScript rule; pty-local validates its config before specs exist);
  resolveExecutable rejects separator-containing relative paths per the seam
  contract; terminal setups tracked as a Set of records.
- subprocess-e2b: PTY output push-without-backpressure is a documented
  contract (flowing consumer folds bytes; paused consumer buffers).
- fs-e2b: streamText normalizes the pinned SDK's empty-file '' return into an
  empty stream instead of throwing on getReader().
- e2b overlays: comment the one-world cwd invariant across e2b.cwd,
  workspaceRoot, and bash-local's implicit default workdir.
---
 docs/config-catalog.md                        | 14 +++
 examples/headless-agent/e2b.cordis.yml        |  6 ++
 .../tests/fixtures/e2b/e2b/cordis.yml         |  3 +
 packages/e2b/fs-e2b/src/index.ts              |  8 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  | 13 ++-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         | 13 ++-
 packages/e2b/subprocess-e2b/README.zh.md      | 13 ++-
 packages/e2b/subprocess-e2b/package.json      |  3 +
 packages/e2b/subprocess-e2b/src/index.ts      | 77 ++++++++++-----
 packages/e2b/subprocess-e2b/src/process.ts    | 77 +++++----------
 packages/e2b/subprocess-e2b/src/remote.ts     | 97 +++++++++++++++++++
 packages/e2b/subprocess-e2b/src/terminal.ts   | 64 ++++--------
 .../subprocess-e2b/tests/subprocess.spec.ts   | 72 +++++++++++++-
 .../e2b/subprocess-e2b/tests/terminal.spec.ts | 14 ++-
 15 files changed, 339 insertions(+), 139 deletions(-)
 create mode 100644 packages/e2b/subprocess-e2b/src/remote.ts

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index b8a49a7ba2..977921db07 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1813,6 +1813,20 @@ export interface Config {
 
 Source: [`packages/subagent/subagent-spawn/src/index.ts:25`](../packages/subagent/subagent-spawn/src/index.ts)
 
+## `@deepseek-ai/dsh-subprocess-e2b`
+
+Requires: `e2b`
+
+```ts config-catalog
+/** Configuration for the E2B subprocess adapter. */
+export interface Config {
+  /** Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request. */
+  pollMs?: number
+}
+```
+
+Source: [`packages/e2b/subprocess-e2b/src/index.ts:24`](../packages/e2b/subprocess-e2b/src/index.ts)
+
 ## `@deepseek-ai/dsh-system-prompt`
 
 ```ts config-catalog
diff --git a/examples/headless-agent/e2b.cordis.yml b/examples/headless-agent/e2b.cordis.yml
index a65b0baf81..61bdbc8aa7 100644
--- a/examples/headless-agent/e2b.cordis.yml
+++ b/examples/headless-agent/e2b.cordis.yml
@@ -1,6 +1,12 @@
 # POC overlay: keep the advanced headless agent and model-facing tools, but
 # place its filesystem and process substrate in one short-lived E2B sandbox;
 # the generic Bash, PTY, and LSP consumers compose above them.
+#
+# One-world invariant: e2b.cwd, sandbox-policy.workspaceRoot, and bash-local's
+# default workdir (implicit host process.cwd()) must all name the same remote
+# directory. Only e2b.cwd is created at sandbox open; dropping its !!js line
+# falls back to /home/user/workspace while Bash and PTY keep targeting the
+# host path, so every tool call fails with a remote spawn error.
 - id: base
   name: '@cordisjs/plugin-include'
   config:
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
index 3a6deb7e49..e6fd968779 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/cordis.yml
@@ -1,3 +1,6 @@
+# One-world invariant (same pairing as examples/headless-agent/e2b.cordis.yml):
+# e2b.cwd and sandbox-policy.workspaceRoot must name the same remote directory,
+# which is also bash-local's implicit default workdir.
 - id: e2b
   name: '@deepseek-ai/dsh-e2b'
   config:
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 3b0c835d8c..84c9ac7868 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -232,7 +232,13 @@ export class E2BFileSystem extends FileSystem {
     await this.requireRegular(target, signal)
     let stream: ReadableStream<Uint8Array>
     try {
-      stream = await sandbox.files.read(String(target.targetKey), { format: 'stream', ...signalOpts(signal) })
+      // The pinned SDK's stream overload lies for empty files: content-length 0
+      // returns '' instead of a ReadableStream.
+      const read = await sandbox.files.read(String(target.targetKey), { format: 'stream', ...signalOpts(signal) }) as
+        ReadableStream<Uint8Array> | string
+      stream = typeof read === 'string'
+        ? new ReadableStream<Uint8Array>({ start(controller) { controller.close() } })
+        : read
     } catch (error: unknown) {
       throw mapError(error, 'read', target.displayPath, signal)
     }
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 618472a6b8..9cad00b6eb 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -149,7 +149,7 @@ class FakeRemote {
         }
         return this.info(path)
       },
-      read: async (path: string, options: { format: 'bytes' | 'stream'; signal?: AbortSignal }): Promise<Uint8Array | ReadableStream<Uint8Array>> => {
+      read: async (path: string, options: { format: 'bytes' | 'stream'; signal?: AbortSignal }): Promise<Uint8Array | ReadableStream<Uint8Array> | string> => {
         this.checkAbort(options)
         if (this.nextReadError !== undefined) {
           const error = this.nextReadError
@@ -158,6 +158,8 @@ class FakeRemote {
         }
         const data = this.followed(path).node.data
         if (options.format === 'bytes') return data.slice()
+        // Pinned-SDK fidelity: a content-length-0 response returns '' even in stream format.
+        if (data.length === 0 && this.streamChunks === undefined) return ''
         const chunks = this.streamChunks ?? [data.slice()]
         return new ReadableStream<Uint8Array>({
           start: (controller) => {
@@ -375,6 +377,15 @@ describe('E2BFileSystem identity, metadata, and reads', () => {
     expect(initiallyBuffered).toBe('€')
   })
 
+  it('streams an empty file even though the pinned SDK returns a non-stream value', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/empty.txt', '')
+    const { fs } = await setup(remote)
+    let streamed = ''
+    for await (const chunk of await fs.streamText(await fs.resolve('empty.txt'))) streamed += chunk
+    expect(streamed).toBe('')
+  })
+
   it('cancels a remote stream when its consumer stops early', async () => {
     const remote = new FakeRemote()
     remote.file('/workspace/text.txt', 'ab')
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index 0a18bf24a1..d0ce148746 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 3bb9802c3afa41f3949fceeb73e76ea5cebce744
-README.zh.md: 520f0ea1cde18ed523ba80015d3d4700730aba7a
+README.md: 926d4f22f8e96daa103c236121d35e461290221a
+README.zh.md: d1634b6d1a701f7f4815135b4ec6bb86ad1a8c87
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 3bb9802c3a..926d4f22f8 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -2,16 +2,22 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, and LSP consumers then execute in the shared remote sandbox without E2B-specific capability packages.
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. Load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, and LSP consumers then execute in the shared remote sandbox without E2B-specific capability packages.
+
+## Configuration
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `pollMs` | `20` | Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request, so a larger value trades exit-observation latency for fewer requests. |
 
 ## Behavior
 
 - **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
-- **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides.
+- **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides, and rejects relative paths containing separators like every subprocess provider.
 - **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
 - **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the sandbox user's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
 - **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
-- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, and fence publication; sandbox disposal or timeout bounds a setup rollback that also fails. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Terminal output is pushed to the handle's stream without awaiting host backpressure: a flowing consumer (the PTY backend attaches one at construction) folds bytes into its own bounded state, while a paused consumer buffers in host memory. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, and fence publication; sandbox disposal or timeout bounds a setup rollback that also fails. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
 - **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
 
 The default E2B base image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`.
@@ -29,6 +35,7 @@ No direct invalidation; the named consumers own any request-prefix changes.
 - **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate the base64 transport even when this adapter exposes bounded raw-byte tails, so the subprocess seam's normal host-memory bound is not achieved and transport retention is larger than the source stream.
 - **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
 - **Private state lives for the sandbox lifetime** — process directories and valid spill files remain under `.dsh-e2b` until the owner deletes the sandbox; this POC supplies no in-sandbox sweep.
+- **Control state shares the sandbox user's UID** — E2B runs every command as the same default user, so `0700`/`0600` modes cannot isolate `.dsh-e2b` control files from concurrently running sandbox processes. A background process could rewrite `pid`/`exit-code` or read a not-yet-consumed `environment` file. The adapter validates published values and refuses group ids whose negative form is unsafe to signal (`<= 1`), but real isolation needs an E2B per-command user or an out-of-band control channel.
 - **Numeric process identities are not reuse-fenced** — E2B exposes numeric PID/PGID PTY input, signalling, and cleanup operations but no atomic identity-bound alternative. The adapter minimizes host round trips and live coverage exercises the reproducible stale-interrupt overlap; replacement is deferred until E2B adds an identity primitive or a failure demonstrates a narrower protocol.
 - **The initial environment probe inherits sandbox defaults** — E2B merges command overrides with default environment entries, so the probe cannot blank unknown credential-shaped names before enumerating them. A same-UID untrusted process already in the sandbox could inspect that short-lived control shell; this POC therefore does not support secrets in sandbox-default environment variables and requires an E2B replacement-environment primitive to close the gap.
 - **E2B exposes no signal fact** — an adapter-requested `SIGTERM` or `SIGKILL` is reported only when no wrapper-published direct exit code wins; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index 520f0ea1cd..d1634b6d1a 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -2,16 +2,22 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY 和 LSP 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
+[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY 和 LSP 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+| --- | --- | --- |
+| `pollMs` | `20` | 远程状态／存活轮询节奏（毫秒）；每个 tick 是一次控制面请求，调大该值以牺牲退出观察延迟换取更少的请求。 |
 
 ## 行为
 
 - **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
-- **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称。
+- **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称，并与所有 subprocess 提供方一致地拒绝含分隔符的相对路径。
 - **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
 - **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变沙箱用户 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
 - **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
-- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup 并阻止发布；若 setup 回滚也失败，则由沙箱 dispose 或超时约束其存活时间。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。终端输出推入句柄流时不等待宿主背压：流动的消费方（PTY 后端在构造时就挂上一个）把字节折叠进自身的有界状态，而暂停的消费方会在宿主内存中缓冲。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup 并阻止发布；若 setup 回滚也失败，则由沙箱 dispose 或超时约束其存活时间。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
 - **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
 
 E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。
@@ -29,6 +35,7 @@ E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：
 - **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界原始字节尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会累积 base64 传输内容，因此无法达到进程管理 seam 通常提供的宿主内存边界，而且传输保留量大于源数据流。
 - **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
 - **私有状态随沙箱生命周期存在**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下，直到所有者删除沙箱；本 POC 不提供沙箱内清理。
+- **控制状态与沙箱用户同 UID**：E2B 以同一默认用户运行每条命令，因此 `0700`/`0600` 权限无法把 `.dsh-e2b` 控制文件与并发运行的沙箱进程隔离开。后台进程可以改写 `pid`/`exit-code`，或读取尚未被消费的 `environment` 文件。适配器会验证已发布的值，并拒绝取负后不安全的进程组 ID（`<= 1`），但真正的隔离需要 E2B 提供按命令用户或带外控制通道。
 - **数值进程身份没有复用围栏**：E2B 公开基于数值 PID/PGID 的 PTY 输入、信号发送和清理操作，却没有与身份原子绑定的替代方案。适配器会尽量减少宿主往返，真实环境测试会覆盖可复现的陈旧中断重叠；在 E2B 新增身份原语，或实际故障证明需要更窄的协议之前，替代方案会继续延后。
 - **初始环境探测会继承沙箱默认值**：E2B 会把命令覆盖与默认环境条目合并，因此探测无法在枚举未知且形似凭据的名称之前将它们置空。一个已在沙箱内运行的同 UID 不可信进程可以检查该短时存在的控制 shell；因此，该 POC 不支持把 secret 放入沙箱默认环境变量，需要 E2B 的替换环境原语才能弥合该缺口。
 - **E2B 不公开信号事实**：适配器请求的 `SIGTERM` 或 `SIGKILL` 只有在包装层发布的直接退出码没有胜出时才报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
diff --git a/packages/e2b/subprocess-e2b/package.json b/packages/e2b/subprocess-e2b/package.json
index d73607d1f3..fa96e17293 100644
--- a/packages/e2b/subprocess-e2b/package.json
+++ b/packages/e2b/subprocess-e2b/package.json
@@ -32,6 +32,9 @@
     "@deepseek-ai/dsh-subprocess": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "devDependencies": {
     "@deepseek-ai/dsh-e2b": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 15e7feccdd..38b1d32465 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -7,6 +7,7 @@
 import { randomUUID } from 'node:crypto'
 import { posix } from 'node:path'
 import { Context } from 'cordis'
+import z from 'schemastery'
 import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
 import type {
   SubprocessHandle,
@@ -16,30 +17,53 @@ import type {
 } from '@deepseek-ai/dsh-subprocess'
 import { e2bControlEnvs, quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
 import { E2BSubprocessHandle } from './process.ts'
+import { asError, signalOpts } from './remote.ts'
 import { spawnE2BTerminal } from './terminal.ts'
 
-function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
-  return signal === undefined ? {} : { signal }
+/** Configuration for the E2B subprocess adapter. */
+export interface Config {
+  /** Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request. */
+  pollMs?: number
+}
+
+interface SchemaResolvedConfig extends Config {
+  pollMs: number
+}
+
+interface TerminalSetup {
+  done: Promise<void>
+  controller: AbortController
 }
 
 /** E2B command manager registered as `ctx.subprocess`. */
 export class E2BSubprocessService extends SubprocessService {
   static inject = ['e2b']
 
+  static Config: z<Config> = z.object({
+    pollMs: z.number().default(20),
+  })
+
   private readonly live = new Set<E2BSubprocessHandle>()
   private readonly terminals = new Set<SubprocessTerminalHandle>()
-  private readonly terminalSetups = new Map<Promise<void>, AbortController>()
+  private readonly terminalSetups = new Set<TerminalSetup>()
+  private readonly pollMs: number
   private disposing = false
 
   /** Create the E2B subprocess service and bind its disposal policy. */
-  constructor(ctx: Context) {
+  constructor(ctx: Context, config: Config) {
     super(ctx)
+    // Schemastery fills pollMs before construction; the type does not encode that step.
+    const { pollMs } = config as SchemaResolvedConfig
+    if (!Number.isSafeInteger(pollMs) || pollMs <= 0) {
+      throw new Error('subprocess-e2b: pollMs must be a positive safe integer')
+    }
+    this.pollMs = pollMs
     ctx.effect(() => async () => {
       this.disposing = true
-      for (const controller of this.terminalSetups.values()) {
-        controller.abort(new Error('subprocess-e2b: service disposed during terminal setup'))
+      for (const setup of this.terminalSetups) {
+        setup.controller.abort(new Error('subprocess-e2b: service disposed during terminal setup'))
       }
-      await Promise.all([...this.terminalSetups.keys()])
+      await Promise.all([...this.terminalSetups].map(setup => setup.done))
       const handles = [...this.live]
       const terminals = [...this.terminals]
       const pending: Promise<unknown>[] = []
@@ -54,9 +78,11 @@ export class E2BSubprocessService extends SubprocessService {
         pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
       }
       const outcomes = await Promise.allSettled(pending)
-      for (const outcome of outcomes) {
-        if (outcome.status === 'rejected') throw outcome.reason
-      }
+      const failures = outcomes.flatMap<unknown>(outcome => outcome.status === 'rejected'
+        ? [outcome.reason as unknown]
+        : [])
+      if (failures.length === 1) throw asError(failures[0])
+      if (failures.length > 1) throw new AggregateError(failures, 'subprocess-e2b: teardown failed')
     }, 'e2b subprocess teardown')
   }
 
@@ -77,6 +103,11 @@ export class E2BSubprocessService extends SubprocessService {
       signal?.throwIfAborted()
       return command
     }
+    if (command.includes('/')) {
+      throw new Error(
+        `subprocess-e2b: command ${JSON.stringify(command)} is a relative path; use an absolute path or a bare PATH name`,
+      )
+    }
     const path = env?.PATH
     const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
     const result = await sandbox.commands.run(
@@ -88,6 +119,7 @@ export class E2BSubprocessService extends SubprocessService {
     if (executable.includes('\n') || (!posix.isAbsolute(executable) && !executable.includes('/'))) {
       throw new Error(`subprocess-e2b: executable ${JSON.stringify(command)} did not resolve to one absolute path`)
     }
+    // A relative result comes from a relative PATH entry; the lookup ran with the shared cwd.
     return posix.resolve(this.ctx.e2b.cwd, executable)
   }
 
@@ -98,14 +130,11 @@ export class E2BSubprocessService extends SubprocessService {
     if (program === undefined || program.length === 0) {
       throw new Error('invalid argv: expected a non-empty program name at argv[0]')
     }
-    if (!Number.isFinite(spec.graceMs) || spec.graceMs <= 0) {
-      throw new Error('subprocess-e2b: graceMs must be a positive finite number')
-    }
     if (spec.signal?.aborted === true) {
       throw new Error(`aborted before spawn: ${String(spec.signal.reason)}`)
     }
     const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'processes', randomUUID())
-    const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir)
+    const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir, this.pollMs)
     this.live.add(handle)
     const release = async (): Promise<void> => {
       await handle.waitForExit()
@@ -124,24 +153,20 @@ export class E2BSubprocessService extends SubprocessService {
     if (program === undefined || program.length === 0) {
       throw new Error('subprocess-e2b: terminal argv must contain a program')
     }
-    for (const [name, value] of [['rows', spec.rows], ['cols', spec.cols], ['graceMs', spec.graceMs]] as const) {
-      if (!Number.isSafeInteger(value) || value <= 0) {
-        throw new Error(`subprocess-e2b: terminal ${name} must be a positive safe integer`)
-      }
-    }
     spec.signal?.throwIfAborted()
     const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'terminals', randomUUID())
-    const setup = Promise.withResolvers<void>()
-    const setupController = new AbortController()
+    const done = Promise.withResolvers<void>()
+    const setup: TerminalSetup = { done: done.promise, controller: new AbortController() }
     const setupSignal = spec.signal === undefined
-      ? setupController.signal
-      : AbortSignal.any([spec.signal, setupController.signal])
-    this.terminalSetups.set(setup.promise, setupController)
+      ? setup.controller.signal
+      : AbortSignal.any([spec.signal, setup.controller.signal])
+    this.terminalSetups.add(setup)
     try {
       const terminal = await spawnE2BTerminal(
         this.ctx.e2b,
         { ...spec, signal: setupSignal },
         stateDir,
+        this.pollMs,
       )
       this.terminals.add(terminal)
       // oxlint-disable-next-line typescript/no-unnecessary-condition -- Remote allocation yields to disposal.
@@ -159,8 +184,8 @@ export class E2BSubprocessService extends SubprocessService {
       })
       return terminal
     } finally {
-      this.terminalSetups.delete(setup.promise)
-      setup.resolve()
+      this.terminalSetups.delete(setup)
+      done.resolve()
     }
   }
 }
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index c0aceda334..feb21a70bc 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -21,8 +21,8 @@ import type {
 import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
 import { bootstrapEnvironment, readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
 import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
+import { asError, commandOpts, signalRemoteGroups, waitTick } from './remote.ts'
 
-const GROUP_POLL_MS = 20
 const OUTPUT_ENCODER_SOURCE = [
   '(async () => {',
   '  for await (const chunk of process.stdin) {',
@@ -48,10 +48,6 @@ function isValidProcessId(value: number): boolean {
   return Number.isSafeInteger(value) && value > 0
 }
 
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error))
-}
-
 class DeferredStdin extends Writable {
   constructor(private readonly ready: Promise<CommandHandle>) {
     super({ decodeStrings: false })
@@ -142,28 +138,6 @@ function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
   return bootstrap
 }
 
-function commandOpts(
-  envs: Record<string, string>,
-  signal: AbortSignal | undefined,
-): { envs: Record<string, string>; signal?: AbortSignal } {
-  return { envs: e2bControlEnvs(envs), ...(signal === undefined ? {} : { signal }) }
-}
-
-function waitTick(signal?: AbortSignal): Promise<boolean> {
-  if (signal?.aborted === true) return Promise.resolve(false)
-  return new Promise<boolean>((resolve) => {
-    const timer = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort)
-      resolve(true)
-    }, GROUP_POLL_MS)
-    const onAbort = (): void => {
-      clearTimeout(timer)
-      resolve(false)
-    }
-    signal?.addEventListener('abort', onAbort, { once: true })
-  })
-}
-
 const WAIT_ABORTED = Symbol('wait aborted')
 
 function waitWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | typeof WAIT_ABORTED> {
@@ -194,6 +168,8 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private readonly stdoutDecoder = new E2BBase64Decoder()
   private readonly stderrDecoder = new E2BBase64Decoder()
   private readonly terminationController = new AbortController()
+  /** Releases output waits that survive the command outcome, so blocked SDK callbacks settle. */
+  private readonly outputReleased = new AbortController()
   private readonly stdoutReader: E2BOutputReader | undefined
   private readonly stderrReader: E2BOutputReader | undefined
   private readonly paths: RemotePaths
@@ -212,11 +188,13 @@ export class E2BSubprocessHandle implements SubprocessHandle {
    * @param runtime - Shared E2B sandbox owner.
    * @param spec - Fully resolved subprocess request.
    * @param stateDir - Remote directory retaining process identity, status, and valid spills.
+   * @param pollMs - Remote status/liveness poll cadence.
    */
   constructor(
     private readonly runtime: E2BSandboxService,
     private readonly spec: SubprocessSpawnSpec,
     readonly stateDir: string,
+    private readonly pollMs = 20,
   ) {
     this.paths = {
       pid: posix.join(stateDir, 'pid'),
@@ -318,7 +296,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
     while (await this.groupAlive(sandbox, processGroupId, signal)) {
       this.throwTerminationFailure()
-      if (!await waitTick(signal)) return false
+      if (!await waitTick(this.pollMs, signal)) return false
     }
     this.throwTerminationFailure()
     if (signal?.aborted === true) return false
@@ -483,19 +461,21 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     await new Promise<void>((resolve, reject) => {
       const onDrain = (): void => { cleanup(); resolve() }
       const onClose = (): void => { cleanup(); resolve() }
-      const onTermination = (): void => { cleanup(); resolve() }
+      const onRelease = (): void => { cleanup(); resolve() }
       const onError = (error: Error): void => { cleanup(); reject(error) }
       const cleanup = (): void => {
         target.removeListener('drain', onDrain)
         target.removeListener('close', onClose)
         target.removeListener('error', onError)
-        this.terminationController.signal.removeEventListener('abort', onTermination)
+        this.terminationController.signal.removeEventListener('abort', onRelease)
+        this.outputReleased.signal.removeEventListener('abort', onRelease)
       }
       target.once('drain', onDrain)
       target.once('close', onClose)
       target.once('error', onError)
-      this.terminationController.signal.addEventListener('abort', onTermination, { once: true })
-      if (this.terminationController.signal.aborted) onTermination()
+      this.terminationController.signal.addEventListener('abort', onRelease, { once: true })
+      this.outputReleased.signal.addEventListener('abort', onRelease, { once: true })
+      if (this.terminationController.signal.aborted || this.outputReleased.signal.aborted) onRelease()
     })
   }
 
@@ -514,9 +494,14 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(pid)) {
           throw new Error(`subprocess-e2b: remote wrapper published invalid process-group id ${JSON.stringify(value)}`)
         }
+        // A same-UID sandbox process can rewrite this file; refuse ids whose
+        // negative form addresses every process (`kill -- -1`) or init's group.
+        if (pid <= 1) {
+          throw new Error(`subprocess-e2b: unsafe published process-group id ${pid}`)
+        }
         return pid
       }
-      const settled = await Promise.race([commandSettled, waitTick().then(() => false)])
+      const settled = await Promise.race([commandSettled, waitTick(this.pollMs).then(() => false)])
       if (settled) throw new Error('subprocess-e2b: remote command exited before publishing its process-group id')
     }
   }
@@ -545,13 +530,16 @@ export class E2BSubprocessHandle implements SubprocessHandle {
         this.outputDrainExpired = true
         this.stdoutReader?.invalidateSpill()
         this.stderrReader?.invalidateSpill()
+        // Release inherited-output waits so a callback blocked on host
+        // backpressure cannot keep the disconnected SDK settlement pending.
+        this.outputReleased.abort(new Error('subprocess-e2b: output drain grace expired'))
         await handle.disconnect()
         return { exitCode, signal: null }
       }
       if (completed !== undefined) return this.commandOutcome(completed)
       // TODO(e2b-status-watch): Replace collect/inherit control-plane polling
       // when E2B can observe direct-command exit independently of descendant-held output.
-      completed = await Promise.race([settlement, waitTick().then(() => undefined)])
+      completed = await Promise.race([settlement, waitTick(this.pollMs).then(() => undefined)])
     }
   }
 
@@ -622,7 +610,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private async terminateGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
     this.terminationSignal = 'SIGTERM'
     try {
-      await this.signalGroup(sandbox, processGroupId, 'TERM')
+      await signalRemoteGroups(sandbox, this.controlEnvs, [processGroupId], 'TERM')
       if (await this.waitForGroupExit(sandbox, processGroupId)) {
         this.markQuiescent()
         return
@@ -637,7 +625,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
 
   private async forceKillGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
     try {
-      await this.signalGroup(sandbox, processGroupId, 'KILL')
+      await signalRemoteGroups(sandbox, this.controlEnvs, [processGroupId], 'KILL')
     } catch (_processGroupKillFailure) {
       // SDK kill and the final liveness probe remain independent cleanup paths.
     }
@@ -654,7 +642,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     const deadline = Date.now() + this.spec.graceMs
     while (await this.groupAlive(sandbox, processGroupId)) {
       if (Date.now() >= deadline) return false
-      await waitTick()
+      await waitTick(this.pollMs)
     }
     return true
   }
@@ -663,21 +651,6 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     if (this.terminationFailure !== undefined) throw this.terminationFailure
   }
 
-  private async signalGroup(sandbox: Sandbox, pid: number, signal: 'TERM' | 'KILL'): Promise<boolean> {
-    // TODO(e2b-pgid-identity): Prefer an atomic identity-bound group signal if E2B adds one;
-    // a userspace identity precheck cannot close the numeric-PGID reuse race.
-    try {
-      await sandbox.commands.run(
-        `kill -${signal} -- -${pid}`,
-        commandOpts(this.controlEnvs, undefined),
-      )
-      return true
-    } catch (error: unknown) {
-      if (error instanceof CommandExitError || error instanceof SandboxNotFoundError) return false
-      throw error
-    }
-  }
-
   private async groupAlive(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<boolean> {
     const result = await sandbox.commands.run(
       `set -o pipefail; ps -eo pgid=,stat= | awk '$1 == ${pid} && $2 !~ /^[ZXx]/ { live=1 } END { if (live) print "live" }'`,
diff --git a/packages/e2b/subprocess-e2b/src/remote.ts b/packages/e2b/subprocess-e2b/src/remote.ts
new file mode 100644
index 0000000000..1937f54bf0
--- /dev/null
+++ b/packages/e2b/subprocess-e2b/src/remote.ts
@@ -0,0 +1,97 @@
+/**
+ * Shared remote-control helpers for the E2B subprocess adapter: SDK option
+ * shaping, poll ticks, and the one tolerant process-group signal used by both
+ * the ordinary-process and terminal teardown ladders.
+ */
+
+import { CommandExitError, e2bControlEnvs, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+import type { Sandbox } from '@deepseek-ai/dsh-e2b'
+
+/**
+ * Normalize an unknown rejection into an Error.
+ * @param error - Any thrown or rejected value.
+ * @returns The value itself when already an Error, else a stringified wrapper.
+ */
+export function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+/**
+ * Shape the optional-signal SDK options object.
+ * @param signal - Optional cancellation for one SDK request.
+ * @returns An options fragment that omits an undefined signal.
+ */
+export function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
+
+/**
+ * Shape control-shell command options with the isolated HOME override.
+ * @param envs - Explicit environment entries for the control command.
+ * @param signal - Optional cancellation for the SDK request.
+ * @returns Options for `sandbox.commands.run` control invocations.
+ */
+export function commandOpts(
+  envs: Record<string, string>,
+  signal?: AbortSignal,
+): { envs: Record<string, string>; signal?: AbortSignal } {
+  return { envs: e2bControlEnvs(envs), ...signalOpts(signal) }
+}
+
+/**
+ * Resolve after one duration.
+ * @param ms - Milliseconds to wait.
+ * @returns Settles after the timeout.
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/**
+ * Wait one poll interval or until the signal aborts.
+ * @param pollMs - Poll cadence in milliseconds.
+ * @param signal - Optional abort that ends the wait early.
+ * @returns `true` after a full tick, `false` when aborted first.
+ */
+export function waitTick(pollMs: number, signal?: AbortSignal): Promise<boolean> {
+  if (signal?.aborted === true) return Promise.resolve(false)
+  return new Promise<boolean>((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve(true)
+    }, pollMs)
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      resolve(false)
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/**
+ * Signal remote process groups, tolerating the shared teardown outcomes: a
+ * nonzero `kill` (groups already gone) and a disappeared sandbox. Both the
+ * pgid-keyed process ladder and the sid-keyed terminal ladder deliver signals
+ * through this single tolerance so they cannot drift apart.
+ * @param sandbox - Live SDK handle.
+ * @param envs - Control-shell environment entries.
+ * @param groups - Positive process-group ids to signal.
+ * @param signal - `TERM` or `KILL`.
+ */
+export async function signalRemoteGroups(
+  sandbox: Sandbox,
+  envs: Record<string, string>,
+  groups: readonly number[],
+  signal: 'TERM' | 'KILL',
+): Promise<void> {
+  // TODO(e2b-pgid-identity): Prefer an atomic identity-bound group signal if E2B adds one;
+  // a userspace identity precheck cannot close the numeric-PGID reuse race.
+  try {
+    await sandbox.commands.run(
+      `kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`,
+      commandOpts(envs),
+    )
+  } catch (error: unknown) {
+    if (!(error instanceof CommandExitError) && !(error instanceof SandboxNotFoundError)) throw error
+  }
+}
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index 3108a4a60a..fd10ecdd8e 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -25,8 +25,7 @@ import {
   readRemoteEnvironment,
   serializeRemoteEnvironment,
 } from './environment.ts'
-
-const POLL_MS = 20
+import { asError, commandOpts, delay, signalOpts, signalRemoteGroups } from './remote.ts'
 
 const TERMINAL_RUNNER_SOURCE = [
   '#!/bin/bash',
@@ -52,21 +51,6 @@ interface TerminalPaths {
   outputMarker: string
 }
 
-function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
-  return signal === undefined ? {} : { signal }
-}
-
-function commandOpts(
-  envs: Record<string, string>,
-  signal?: AbortSignal,
-): { envs: Record<string, string>; signal?: AbortSignal } {
-  return { envs: e2bControlEnvs(envs), ...signalOpts(signal) }
-}
-
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}
-
 class BootstrapOutputFilter {
   readonly ready: Promise<void>
 
@@ -134,10 +118,6 @@ async function waitForBootstrapOutput(
   })
 }
 
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error))
-}
-
 function parsePositiveId(value: string, message: string): number {
   const raw = value.trim()
   const id = Number(raw)
@@ -193,27 +173,12 @@ async function sessionProcessGroups(
   return [...groups]
 }
 
-async function signalGroups(
-  sandbox: Sandbox,
-  groups: number[],
-  signal: 'TERM' | 'KILL',
-  envs: Record<string, string>,
-): Promise<void> {
-  try {
-    await sandbox.commands.run(
-      `kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`,
-      commandOpts(envs),
-    )
-  } catch (error: unknown) {
-    if (!(error instanceof CommandExitError) && !(error instanceof SandboxNotFoundError)) throw error
-  }
-}
-
 async function awaitSessionEmpty(
   sandbox: Sandbox,
   sessionId: number,
   envs: Record<string, string>,
   graceMs: number,
+  pollMs: number,
   kill = false,
 ): Promise<number[]> {
   const deadline = Date.now() + graceMs
@@ -221,12 +186,12 @@ async function awaitSessionEmpty(
     const groups = await sessionProcessGroups(sandbox, sessionId, envs)
     if (groups.length === 0) return groups
     if (kill) {
-      await signalGroups(sandbox, groups, 'KILL', envs)
+      await signalRemoteGroups(sandbox, envs, groups, 'KILL')
       if (Date.now() >= deadline) return await sessionProcessGroups(sandbox, sessionId, envs)
     } else if (Date.now() >= deadline) {
       return groups
     }
-    await delay(Math.min(POLL_MS, Math.max(1, deadline - Date.now())))
+    await delay(Math.min(pollMs, Math.max(1, deadline - Date.now())))
   }
 }
 
@@ -236,6 +201,7 @@ async function rollbackUnpublishedTerminal(
   completion: Promise<CommandResult>,
   envs: Record<string, string>,
   graceMs: number,
+  pollMs: number,
 ): Promise<void> {
   let topLevelExited = false
   void completion.then(
@@ -256,11 +222,11 @@ async function rollbackUnpublishedTerminal(
     try {
       let groups = await sessionProcessGroups(sandbox, sessionId, envs)
       if (groups.length > 0) {
-        await signalGroups(sandbox, groups, 'TERM', envs)
-        groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs)
+        await signalRemoteGroups(sandbox, envs, groups, 'TERM')
+        groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, pollMs)
       }
       if (groups.length > 0) {
-        await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, true)
+        await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, pollMs, true)
       }
     } catch (error: unknown) {
       attemptFailures.push(asError(error))
@@ -280,7 +246,7 @@ async function rollbackUnpublishedTerminal(
   const proofFailures: Error[] = []
   if (sessionId !== undefined) {
     try {
-      const groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, true)
+      const groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, pollMs, true)
       if (groups.length > 0) {
         proofFailures.push(new Error(
           `subprocess-e2b: terminal setup rollback failed; surviving process groups: ${groups.join(', ')}`,
@@ -328,6 +294,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     private readonly controlEnvs: Record<string, string>,
     private readonly stateDir: string,
     private readonly graceMs: number,
+    private readonly pollMs: number,
   ) {
     this.pid = handle.pid
     this.done = this.waitForCommand()
@@ -441,8 +408,8 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
     let groups = await sessionProcessGroups(this.sandbox, this.sessionId, this.controlEnvs)
     if (groups.length > 0) {
       this.terminationSignal = 'SIGTERM'
-      await signalGroups(this.sandbox, groups, 'TERM', this.controlEnvs)
-      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs)
+      await signalRemoteGroups(this.sandbox, this.controlEnvs, groups, 'TERM')
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs, this.pollMs)
     }
     if (groups.length === 0 && !this.topLevelExited) {
       await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
@@ -457,7 +424,7 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
           throw error
         }
       }
-      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs, true)
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs, this.pollMs, true)
       if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
     }
     if (groups.length > 0) {
@@ -485,12 +452,14 @@ export class E2BTerminalHandle implements SubprocessTerminalHandle {
  * @param runtime - Shared E2B sandbox owner.
  * @param spec - Fully specified terminal-process request.
  * @param stateDir - Private remote directory for one startup transaction.
+ * @param pollMs - Remote session liveness poll cadence.
  * @returns The live subprocess terminal handle.
  */
 export async function spawnE2BTerminal(
   runtime: E2BSandboxService,
   spec: SubprocessTerminalSpawnSpec,
   stateDir: string,
+  pollMs = 20,
 ): Promise<E2BTerminalHandle> {
   const sandbox = await runtime.getSandbox()
   spec.signal?.throwIfAborted()
@@ -555,6 +524,7 @@ export async function spawnE2BTerminal(
       controlEnvs,
       stateDir,
       spec.graceMs,
+      pollMs,
     )
   } catch (error: unknown) {
     output.destroy()
@@ -565,7 +535,7 @@ export async function spawnE2BTerminal(
       if (!terminalQuiescent && handle !== undefined) {
         try {
           if (completion === undefined) await handle.kill()
-          else await rollbackUnpublishedTerminal(sandbox, handle, completion, controlEnvs, spec.graceMs)
+          else await rollbackUnpublishedTerminal(sandbox, handle, completion, controlEnvs, spec.graceMs, pollMs)
           terminalQuiescent = true
         } catch (cleanupError: unknown) {
           if (cleanupError instanceof SandboxNotFoundError) terminalQuiescent = true
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 471716ef1a..747dc936c6 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -519,6 +519,38 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('releases an inherited-output callback blocked on host backpressure at drain expiry', async () => {
+    const fake = new FakeSandbox()
+    const written: string[] = []
+    const stdoutWrite = vi.spyOn(process.stdout, 'write').mockImplementation(((chunk: Uint8Array) => {
+      written.push(Buffer.from(chunk).toString())
+      return false
+    }) as typeof process.stdout.write)
+    try {
+      const handle = new E2BSubprocessHandle(runtime(fake), spec({
+        graceMs: 5,
+        stdio: { stdin: 'ignore', stdout: 'inherit', stderr: { maxBytes: 4 } },
+      }), '/runtime/inherit-backpressure')
+      await flush()
+      let callbackSettled = false
+      const blocked = fake.stdout('blocked bytes').then(() => { callbackSettled = true })
+      await flush()
+      expect(callbackSettled).toBe(false)
+      fake.exitStatus = '0\n'
+
+      await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
+      await blocked
+      expect(callbackSettled).toBe(true)
+      expect(written.join('')).toBe('blocked bytes')
+      expect(fake.handle.disconnects).toBe(1)
+
+      handle.terminate()
+      await expect(handle.waitForExit()).resolves.toBe(true)
+    } finally {
+      stdoutWrite.mockRestore()
+    }
+  })
+
   it('waits for lossless raw-pipe output after the direct status is published', async () => {
     const fake = new FakeSandbox()
     const handle = new E2BSubprocessHandle(runtime(fake), spec({
@@ -1311,6 +1343,17 @@ describe('E2BSubprocessHandle', () => {
     expect(invalidGroup.commandsSeen).toContain('kill -KILL -- -4242')
     await expect(invalid.waitForExit()).resolves.toBe(true)
 
+    // A rewritten pid file must not aim the kill at every process (`-- -1`).
+    const unsafeGroup = new FakeSandbox()
+    unsafeGroup.processGroupId = '1\n'
+    unsafeGroup.delaysKill = true
+    unsafeGroup.sdkKillStops = false
+    unsafeGroup.afterProbe = () => { unsafeGroup.alive = false }
+    const unsafe = new E2BSubprocessHandle(runtime(unsafeGroup), spec(), '/runtime/unsafe-group')
+    await expect(unsafe.done).rejects.toThrow(/unsafe published process-group id 1/)
+    expect(unsafeGroup.commandsSeen).not.toContain('kill -KILL -- -1')
+    await expect(unsafe.waitForExit()).resolves.toBe(true)
+
     const absentGroup = new FakeSandbox()
     absentGroup.processGroupId = ''
     const absent = new E2BSubprocessHandle(runtime(absentGroup), spec(), '/runtime/absent-group')
@@ -1588,6 +1631,34 @@ describe('E2BSubprocessService', () => {
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
+  it('aggregates sibling cleanup failures instead of reporting only the first', async () => {
+    const { ctx, fiber } = await service()
+    const disposalErrors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
+    const first = {
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw new Error('first cleanup failed') }),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+    } as unknown as E2BSubprocessHandle
+    const second = {
+      terminate: vi.fn(),
+      waitForExit: vi.fn(async () => { throw new Error('second cleanup failed') }),
+      done: Promise.resolve({ exitCode: 0, signal: null }),
+    } as unknown as E2BSubprocessHandle
+    const live = (ctx.subprocess as unknown as { live: Set<E2BSubprocessHandle> }).live
+    live.add(first)
+    live.add(second)
+
+    await fiber.dispose()
+    const failure = disposalErrors[0]
+    expect(failure).toBeInstanceOf(AggregateError)
+    if (!(failure instanceof AggregateError)) throw new Error('expected AggregateError')
+    expect(failure.errors.map(error => (error as Error).message).sort()).toEqual([
+      'first cleanup failed',
+      'second cleanup failed',
+    ])
+  })
+
   it('waits for every owned cleanup before reporting a disposal failure', async () => {
     const { ctx, fiber } = await service()
     const failed = {
@@ -1667,7 +1738,6 @@ describe('E2BSubprocessService', () => {
   it('validates synchronous spawn preconditions', async () => {
     const { ctx } = await service()
     expect(() => ctx.subprocess.spawn(spec({ argv: [] }))).toThrow(/non-empty program/)
-    expect(() => ctx.subprocess.spawn(spec({ graceMs: 0 }))).toThrow(/positive finite/)
     expect(() => ctx.subprocess.spawn(spec({ signal: AbortSignal.abort('stop') }))).toThrow(/aborted before spawn/)
   })
 
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 9973b5151a..826732f057 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -793,6 +793,8 @@ describe('E2B subprocess terminal service', () => {
   it('rejects invalid executable lookup inputs and results', async () => {
     const { ctx, fake } = await service()
     await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('non-empty')
+    await expect(ctx.subprocess.resolveExecutable('./bin/server')).rejects.toThrow('is a relative path')
+    await expect(ctx.subprocess.resolveExecutable('node_modules/.bin/server')).rejects.toThrow('is a relative path')
     await expect(ctx.subprocess.resolveExecutable('node', undefined, AbortSignal.abort(new Error('stop'))))
       .rejects.toThrow('stop')
     fake.resolvedExecutable = 'node\n'
@@ -801,6 +803,15 @@ describe('E2B subprocess terminal service', () => {
     await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')
   })
 
+  it('rejects a non-positive poll cadence at load', async () => {
+    const ctx = new Context()
+    ctx.provide('e2b', runtime(new FakeTerminalSandbox()))
+    await expect(ctx.plugin(E2BSubprocessService, { pollMs: 0 }))
+      .rejects.toThrow('pollMs must be a positive safe integer')
+    const explicit = await ctx.plugin(E2BSubprocessService, { pollMs: 5 })
+    await explicit.dispose()
+  })
+
   it('owns live terminals through service disposal', async () => {
     const { ctx, fiber, fake } = await service()
     const terminal = await ctx.subprocess.spawnTerminal(spec({ signal: new AbortController().signal }))
@@ -873,9 +884,6 @@ describe('E2B subprocess terminal service', () => {
     const { ctx, fiber, fake } = await service()
     for (const request of [
       spec({ argv: [] }),
-      spec({ rows: 0 }),
-      spec({ cols: 1.5 }),
-      spec({ graceMs: 0 }),
       spec({ signal: AbortSignal.abort(new Error('cancelled')) }),
     ]) {
       await expect(ctx.subprocess.spawnTerminal(request)).rejects.toThrow()

From 6e1ae76c9bbf001b68dfdeac93f628f755fcdbbd Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 3 Aug 2026 02:17:04 +0800
Subject: [PATCH 390/516] test(e2b): satisfy the steer() receipt signature in
 Agent stubs

Master's steering-receipt API (agent.steer returns SteeringReceipt) reached
this branch through the parent sync; the two E2B live-fixture Agent stubs
return the same rejected-outcome receipt the pty test stubs use.
---
 examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts | 2 +-
 packages/e2b/e2b/tests/composition.e2e.ts             | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 7348d1d181..985b0a6121 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -22,7 +22,7 @@ const owner: Agent = {
   acceptsNextStep: false,
   ctx: ownerFiber.ctx,
   followup() {},
-  steer() {},
+  steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
   inject() {},
   send() {},
   cancel() {},
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 3f0b69668d..c09243183e 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -86,7 +86,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         acceptsNextStep: false,
         ctx,
         followup() {},
-        steer() {},
+        steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
         inject() {},
         send() {},
         cancel() {},

From d488330ba4890d12de3373718b243d4ac27b5783 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:04:33 +0800
Subject: [PATCH 391/516] fix(rebase): migrate the replayed E2B branch onto the
 rebased parent

The linear replay carried old-lineage content over parent-owned files;
this checkpoint restores them and adapts the branch to the parent's
post-rebase seam:

- restore all pty/lsp/subprocess/code-runtime surfaces to the parent's
  exact content (this branch claims none of them) and drop the net-zero
  code-runtime-e2b/pty-e2b/lsp-e2b residue and its registrations
- widen serializeRemoteEnvironment to the seam's NodeJS.ProcessEnv
  tombstone contract: an explicit undefined removes an ambient entry
- migrate the two E2B fixture Agent stubs to the Inbox-model interface
  and Session.create
- re-apply the branch's gen-doc-graphs roles, THIRD_PARTY_NOTICES e2b
  row, and packages/README group row (trimmed to the doc budget);
  regenerate catalogs and re-record bilingual pairings
---
 ...8-portable-execution-world-consumers.zh.md |  15 +-
 THIRD_PARTY_NOTICES.md                        |   2 +
 docs/architecture.zh.md                       |   1 -
 docs/capability-seams.md                      |  14 +-
 docs/config-catalog.md                        |  17 +
 .../tests/fixtures/e2b/e2b/bin.ts             |  13 +-
 examples/package.json                         |   3 -
 packages/README.i18n.yaml                     |   4 +-
 packages/README.md                            |   2 +-
 packages/code-runtime/README.i18n.yaml        |   4 +-
 packages/code-runtime/README.md               |   9 +-
 packages/code-runtime/README.zh.md            |  13 +-
 .../code-runtime-worker/README.i18n.yaml      |   4 +-
 .../code-runtime-worker/README.md             |   6 +-
 .../code-runtime-worker/README.zh.md          |  26 +-
 .../code-runtime-worker/src/index.ts          |  35 +-
 .../code-runtime/README.i18n.yaml             |   4 +-
 packages/code-runtime/code-runtime/README.md  |   2 +-
 .../code-runtime/code-runtime/README.zh.md    |  20 +-
 .../cordis/tool-cordis/src/api-catalog.ts     |  10 +
 packages/e2b/e2b/tests/composition.e2e.ts     |  13 +-
 .../e2b/subprocess-e2b/src/environment.ts     |  10 +-
 packages/lsp/README.i18n.yaml                 |   4 +-
 packages/lsp/README.md                        |   5 +-
 packages/lsp/README.zh.md                     |   5 +-
 packages/lsp/lsp-local/src/index.ts           | 199 ++++---
 packages/lsp/lsp-local/src/instance.ts        |  27 +-
 packages/lsp/lsp-local/tests/instance.spec.ts |   2 -
 packages/lsp/lsp/README.i18n.yaml             |   6 +-
 packages/pty/README.i18n.yaml                 |   4 +-
 packages/pty/README.md                        |   5 +-
 packages/pty/README.zh.md                     |   5 +-
 packages/pty/pty-local/src/sanitize.ts        | 188 +++++++
 packages/pty/pty-local/src/session.ts         | 513 ++++++++++++------
 packages/pty/pty-local/tests/sanitize.spec.ts |  34 +-
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.md                 |   7 +-
 packages/subprocess/README.zh.md              |  11 +-
 pnpm-lock.yaml                                | 230 +++++++-
 scripts/gen-doc-graphs.ts                     |  13 +-
 40 files changed, 1043 insertions(+), 446 deletions(-)
 create mode 100644 packages/pty/pty-local/src/sanitize.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index 68d022216c..ce6650a284 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但若干上层能力仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY、LSP 与代码运行时包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
+文件系统与进程管理 seam 使文件访问和普通进程访问具备可替换性，但 PTY 和 LSP 仍直接调用宿主 Node API。因此，即使领域行为没有变化，远程执行提供方看起来仍需要独立的 PTY 与 LSP 包（package）。这些包只会成为浅层适配器：每个包都仅为替换文件与进程操作而复制一个现有消费方。
 
 只有文件操作、命令、终端和语言服务器共享同一个沙箱身份时，远程编码世界才有用。若把完整 harness 移入该沙箱，还会把提供方实验与插件加载、凭据、模型传输、会话持久性、监督和部署纠缠在一起。
 
@@ -18,16 +18,13 @@ Status: implemented
 
 文件系统接口负责其他能力需要的路径事实，同时不公开其不透明目标身份：规范化进程路径、规范化 `file:` URI 和包含关系。现有完整文本与流式文本操作仍归文件系统负责；协议消费方在消费流时执行各自的保留上限。
 
-进程管理接口负责进程运行坐标与原语：规范化 cwd、私有运行时存储、可执行文件查找、以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使整个会话完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
+进程管理接口负责可执行文件查找与进程原语：以原始或收集模式 spawn 普通进程，以及 `spawnTerminal()`。终端操作是一项深层原语，其句柄负责文本 I/O、前台进程组、信号发送，以及一项须等待的 TERM→KILL 操作；该操作会结算所有在途句柄调用，并使提供方仍可观察到的每个会话成员完全停稳。其信号只取消分配；句柄一经发布，便负责自身生命周期。提示符检测、空闲推断、scrollback、沙箱策略和所有者生命周期仍由 PTY 消费方负责。
 
 通用消费方使用该执行世界：
 
 - `dsh-bash-local` 继续把 Bash 语义映射到普通的 `ctx.subprocess.spawn()`。
 - `dsh-lsp-local` 通过 `ctx.fs` 读取源文件并验证包含关系，通过 `ctx.subprocess` 解析和启动语言服务器，并让由提供方负责的文件 URI 贯穿初始化与结果渲染。一个提供方生命周期信号会在资源释放期间中止文件系统与协议操作，包括取得队列所有权之前的工作区查找；其 JSON-RPC、池化、同步和规范化保持不变。
-- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；写入被拒绝时不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。关闭操作会拒绝新的公开信号，并把完整会话的完全停稳委托给句柄上须等待的终止操作。
-- `dsh-code-runtime-subprocess` 通过 `ctx.fs` 物化无依赖 runner，并通过 `ctx.subprocess` 启动它，从而在本地或远程执行世界中保留代码运行时的绑定与输出契约。固定 runner 是位于 `ctx.subprocess.runtimeRoot` 下的适配器自有基础设施，因此其写入携带显式 `danger-full-access` 策略，而不继承面向模型的文件系统模式。它通过非插件子路径 `dsh-code-runtime-worker/runtime-host` 共享宿主侧 worker 机制，而不是复制这些机制。准备阶段让同一个生命周期信号贯穿文件系统解析、物化和可执行文件查找，使资源释放能够中止停滞的提供方操作。受堆上限约束的 worker 会在传输前拒绝过大的绑定帧；每个外层转发环节都会在转发前执行相同的上限检查；原始子进程管道承载以换行符分隔的 UTF-8 JSON，无需冗余的 base64 表示；launcher 会在回收 controller 前发布已接纳的终态帧，使继承 controller 管道的后代进程无法阻止完成；宿主仍会等待进程组完全停稳。
-
-`dsh-code-runtime-worker` 仍是独立实现。它是较小的进程内后端，可用于无法假定已安装 Node 可执行文件的单文件分发。远程文件系统／进程组合选择 `dsh-code-runtime-subprocess`；它们不需要提供方专用的代码运行时包。
+- `dsh-pty-local` 把持久 shell 语义映射到 `ctx.subprocess.spawnTerminal()`。本地 `node-pty` 与进程检查实现移入 `dsh-subprocess-local`；其他进程管理提供方则提供相同原语。`danger-full-access` 不需要 `ctx.sandbox`；受限模式要求同一执行世界中存在沙箱提供方，未挂载时会在 spawn 前失败。提供方开始写入时，系统会丢弃异步写入前检查期间收集的提示符与静默证据。取消会在在途写入结算期间保留发送预留，随后向前台进程组发送信号，因此延迟字节和该信号都无法落到后续发送；在途就绪检查无法释放该预留，写入被拒绝时也不会发送信号。绝对截止时间会在整个取消期间保持启用。信号发送失败会成为终结性传输失败。陈旧检查完成后，会针对当前发送恢复轮询。启动取消会立即开始终端回滚，而不等待停滞的就绪检查或信号发送调用。关闭操作会拒绝新的公开信号，并把提供方可观察会话成员的完全停稳委托给句柄上须等待的终止操作。
 
 ## E2B POC 边界
 
@@ -45,7 +42,7 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 ## 考虑过的替代方案
 
-**为每个远程提供方分别保留 PTY、LSP 和代码运行时包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
+**为每个远程提供方分别保留 PTY 与 LSP 包。** 不予采纳，因为这会在现有 seam 之上重复实现提供方机制。删除检验揭示了这一问题：删除这些适配器不应使领域行为散落到远程提供方中；通用消费方本已负责这些行为。
 
 **为每项能力或工具创建独立沙箱。** 不予采纳，因为文件与进程操作将无法共享身份或状态，从而破坏编码用例，并增加生命周期所有者的数量。
 
@@ -57,8 +54,6 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 **在文件系统 seam 中新增稳定的有界读取原语。** 不予采纳，因为只有 LSP 需要完整文档字节上限，而它可以在消费现有文本流时执行该上限。第二项原语会迫使每个提供方实现稳定句柄和不跟随符号链接的机制，远程提供方甚至需要辅助协议，却没有已观察到的并发替换缺陷。
 
-**删除 worker 线程代码运行时。** 不予采纳，因为可移植性不会消除其当前部署需求。进程管理后端需要 Node 可执行文件和文件系统物化，而 worker 后端两者都不需要，并且仍是受支持的单进程路径。
-
 **在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop。
 
 **把所有提供方操作都放进一个共享所有者包。** 不予采纳，因为沙箱身份与生命周期是所有者唯一的关注点。文件系统与进程管理保留各自独立的契约、测试和消费方，同时避免把所有者变成无边界的能力集合。
@@ -69,7 +64,7 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 ## 后果
 
-远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY、LSP 和基于进程管理的代码运行时组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
+远程执行提供方只需实现共享沙箱所有者，以及文件系统与进程管理适配器。Bash、PTY 与 LSP 组合在这些适配器之上，因此对这些能力的修复仍与提供方无关。
 
 基础接口更宽，一对文件系统／进程管理提供方必须在同一个执行世界上保持一致。新增操作仅限当前通用消费方所需的事实与生命周期机制；模型 schema、协议分帧、就绪策略和呈现不会渗入提供方。
 
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 1d169819b4..9060950bea 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -57,6 +57,8 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`clsx`](https://github.com/lukeed/clsx) | MIT |
 | [`commander`](https://github.com/tj/commander.js) | MIT |
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
+| [`dotenv`](https://github.com/motdotla/dotenv) | BSD-2-Clause |
+| [`e2b`](https://github.com/e2b-dev/e2b) | MIT |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
 | [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT |
 | [`immer`](https://github.com/immerjs/immer) | MIT |
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 2d1a0b43d5..9314a3fbfc 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -25,7 +25,6 @@
 |---|---|---|
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | 适配器注册表和模型流式调用 |
 | `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的单实例请求压力与表面压力 |
-| `ctx.e2b` | [`e2b/`](../packages/e2b/README.md) | 共享 E2B 沙箱 |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | 前台和后台命令执行 |
 | `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | 可执行文件查找、受管进程树、终端 |
 | `ctx.pty` | [`pty/`](../packages/pty/README.md) | 按 owner 隔离的持久化终端会话 |
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 50ebe88d4f..4ed8a260d4 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -98,6 +98,10 @@ flowchart LR
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_goal["goal"]
   svc_goals["ctx.goals<br/>Same-session goal domain"]
+  pkg_e2b["e2b"]
+  svc_e2b["ctx.e2b<br/>E2B sandbox lifecycle owner"]
+  pkg_fs_e2b["fs-e2b"]
+  pkg_subprocess_e2b["subprocess-e2b"]
   pkg_subprocess["subprocess"]
   svc_subprocess["ctx.subprocess<br/>Subprocess seam"]
   pkg_subprocess_local["subprocess-local"]
@@ -190,7 +194,9 @@ flowchart LR
   pkg_directory_picker --> svc_directoryPicker
   pkg_directory_picker_browse --> svc_directoryPicker
   pkg_directory_picker_native --> svc_directoryPicker
+  pkg_e2b --> svc_e2b
   pkg_fs --> svc_fs
+  pkg_fs_e2b --> svc_fs
   pkg_fs_local --> svc_fs
   pkg_fs_sandbox --> svc_fs
   pkg_goal --> svc_goals
@@ -241,6 +247,7 @@ flowchart LR
   pkg_subagent_fork --> svc_subagents
   pkg_subagent_spawn --> svc_subagents
   pkg_subprocess --> svc_subprocess
+  pkg_subprocess_e2b --> svc_subprocess
   pkg_subprocess_local --> svc_subprocess
   pkg_system_prompt --> svc_systemPrompt
   pkg_tasks --> svc_tasks
@@ -277,6 +284,8 @@ flowchart LR
   svc_credentials --> pkg_llm_deepseek
   svc_credentials --> pkg_llm_pi_ai
   svc_directoryPicker --> pkg_apiproxy
+  svc_e2b --> pkg_fs_e2b
+  svc_e2b --> pkg_subprocess_e2b
   svc_fs --> pkg_tool_fs
   svc_httpServer --> pkg_connection
   svc_httpServer --> pkg_hmr
@@ -390,7 +399,8 @@ flowchart LR
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
-| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
+| `ctx.e2b` | `core` | [`e2b`](../packages/e2b/e2b) | - | [`fs-e2b`](../packages/e2b/fs-e2b), [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | - | Owns one shared E2B SDK handle, remote working directory, and final sandbox disposition so both fundamental E2B providers inhabit the same Linux runtime. |
+| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local), [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation. |
 | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pwsh-local`](../packages/bash/pwsh-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them. |
 | `ctx.bashEnv` | `core` | [`bash-env`](../packages/bash/bash-env) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh) | - | Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace. |
 | `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface. |
@@ -399,7 +409,7 @@ flowchart LR
 | `ctx.approval` | `seam` | `approval` | [`acp`](../packages/acp/acp) | [`tools`](../packages/core/tools), [`tool-bash`](../packages/bash/tool-bash) | - | One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`. |
 | `ctx.permission` | `core` | [`permission`](../packages/ui/permission) | - | - | - | User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events. |
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
-| `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
+| `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 977921db07..58b319d662 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -399,6 +399,22 @@ export interface Config {
 
 Source: [`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
 
+## `@deepseek-ai/dsh-e2b`
+
+```ts config-catalog
+/** Configuration for the shared E2B sandbox owner. */
+export interface Config {
+  /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */
+  apiKey?: string
+  /** Shared remote working directory, created before adapters receive the sandbox. */
+  cwd?: string
+  /** E2B sandbox lifetime in milliseconds; expiry always deletes the sandbox. */
+  timeoutMs?: number
+}
+```
+
+Source: [`packages/e2b/e2b/src/index.ts:43`](../packages/e2b/e2b/src/index.ts)
+
 ## `@deepseek-ai/dsh-frontend-static`
 
 Requires: `httpServer`
@@ -2587,6 +2603,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-command-feedback` — requires `commands` ([`packages/feedback/command-feedback/src/index.ts`](../packages/feedback/command-feedback/src/index.ts))
 - `@deepseek-ai/dsh-command-goal` — requires `commands` · `goals` ([`packages/goal/command-goal/src/index.ts`](../packages/goal/command-goal/src/index.ts))
 - `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts))
+- `@deepseek-ai/dsh-fs-e2b` — requires `e2b` ([`packages/e2b/fs-e2b/src/index.ts`](../packages/e2b/fs-e2b/src/index.ts))
 - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts))
 - `@deepseek-ai/dsh-goal-session` — requires `agents` · `goals` · `sessions` ([`packages/goal/goal-session/src/index.ts`](../packages/goal/goal-session/src/index.ts))
 - `@deepseek-ai/dsh-host-directory-picker-auto` — requires `httpServer` · `loader` ([`packages/host/directory-picker-auto/src/index.ts`](../packages/host/directory-picker-auto/src/index.ts))
diff --git a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
index 985b0a6121..7a787c735b 100644
--- a/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
+++ b/examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts
@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { boot } from '@deepseek-ai/dsh-app-boot'
+import { Inbox } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-fs-e2b'
@@ -14,18 +15,20 @@ if (configPath === undefined) throw new Error('usage: bin.ts <cordis.yml>')
 const ctx = await boot('e2b-composition', resolve(configPath))
 const ownerFiber = ctx.plugin(() => {})
 const ownerId = SessionId('e2b-live-owner')
+const session = Session.create(ownerId)
 const owner: Agent = {
   id: ownerId,
   options: {},
-  session: new Session(ownerId),
+  session,
+  inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
   status: 'idle',
-  acceptsNextStep: false,
   ctx: ownerFiber.ctx,
-  followup() {},
-  steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
-  inject() {},
   send() {},
+  followup() {},
+  steer() {},
+  inject() {},
   cancel() {},
+  runMaintenance: task => task(new AbortController().signal),
   whenIdle: () => Promise.resolve(),
 }
 const unregisterOwner = ctx.agents.register(owner)
diff --git a/examples/package.json b/examples/package.json
index e4251c9475..48ac39f5ca 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -54,10 +54,7 @@
     "@deepseek-ai/dsh-sandbox": "workspace:*",
     "@deepseek-ai/dsh-sandbox-local": "workspace:*",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
-<<<<<<< HEAD
     "@deepseek-ai/dsh-scope": "workspace:*",
-=======
->>>>>>> 3f6c905d5e (Add E2B PTY, LSP, and code runtime providers)
     "@deepseek-ai/dsh-session": "workspace:*",
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:*",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:*",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index ce95627688..7e74d63f31 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: a9a121d0cb13cd5e2148da8d754967359be06bab
-README.zh.md: c6500ebb2abce14fabf68b79ec20f5c23cf5d5f7
+README.md: 1516c20ff55f366fe6af6b0be5495958708f29e3
+README.zh.md: 42f4d2b8d924b19fd3cde863dafb8c59d9c078cf
diff --git a/packages/README.md b/packages/README.md
index 125b466d72..98fc87a6b2 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -6,7 +6,7 @@ Packages use the `@deepseek-ai/dsh-*` scope. Cordis `Service` subclasses and fun
 
 ## Hierarchy
 
-Groups contain packages at `packages/<group>/<pkg>/`; names remain `@deepseek-ai/dsh-<pkg>`. **Group READMEs own package/ctx-key maps.**
+Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Group READMEs own package/ctx-key maps.**
 
 | Group | Role | Release expectation |
 |---|---|---|
diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml
index 30c5ca2572..3eb462d513 100644
--- a/packages/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/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/code-runtime/README.md
-README.md: 34eecc4874afc5a576ed129e72eeeb944b95f67f
-README.zh.md: 85d7a95a37cd1f4090062f3036a6634fde5011ee
+README.md: f20a287419b94b1a9dc1d8da7303fc4d3032cfd3
+README.zh.md: f5cd4c9949f2bd7a7d6d7cd078144910712a3819
diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md
index 34eecc4874..f20a287419 100644
--- a/packages/code-runtime/README.md
+++ b/packages/code-runtime/README.md
@@ -2,12 +2,11 @@
 
 English | [中文](README.zh.md)
 
-The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the generated TypeScript SDK); design in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
+The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the SDK generated in the loaded runtime's `language`); design in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| `code-runtime/` | Abstract code-execution seam (interface + vocabulary) | `ctx.codeRuntime` |
-| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend: fresh worker per run, TypeScript via host-side type-strip (annotations advisory, never type-checked), port-bridged bindings, budget/heap containment | registers `ctx.codeRuntime` |
-| [`e2b/code-runtime-e2b`](../e2b/code-runtime-e2b/README.md) | E2B backend: host type-strip and bindings, fresh remote runner/worker, framed bridge, remote process-group cleanup | registers `ctx.codeRuntime` |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution seam and shared vocabulary | `ctx.codeRuntime` |
+| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend | registers `ctx.codeRuntime` |
 
-Backends differ by execution substrate and source language—both readonly descriptors on the service—and register `ctx.codeRuntime` without touching the interface or its consumer. The E2B ownership split is recorded in the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md).
+Backends register the seam without changing its consumer. The child READMEs own language, isolation, and execution-budget details.
diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md
index 85d7a95a37..f5cd4c9949 100644
--- a/packages/code-runtime/README.zh.md
+++ b/packages/code-runtime/README.zh.md
@@ -1,13 +1,12 @@
-# code-runtime/：代码执行能力家族
+# code-runtime/ — 代码执行能力家族
 
 [English](README.md) | 中文
 
-代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：一个抽象运行时接口，用于针对宿主提供的异步绑定执行一段模型编写的程序，并捕获程序打印和返回的内容。消费方是工具注册表的 [Code Mode](../core/tools/README.md)（`tools: { mode: code }`，即 `run_code` 工具与生成的 TypeScript SDK）；设计记录在 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 中。这些都是**产品** 包。
+代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：一个抽象运行时接口，用于对宿主提供的异步绑定执行模型编写的程序，并捕获它打印和返回的内容。消费方是工具注册表的 [Code Mode](../core/tools/README.md)（`tools: { mode: code }`，即 `run_code` 工具和按所加载运行时 `language` 生成的 SDK）；设计见 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)。这些全是**产品**包。
 
-| 包 | 职责 | ctx 键 |
+| 包 | 职责 | ctx key |
 |---|---|---|
-| `code-runtime/` | 抽象代码执行 seam（接口 + 词汇） | `ctx.codeRuntime` |
-| [`code-runtime-worker/`](code-runtime-worker/README.md) | worker 线程后端：每次运行使用全新 worker，由宿主侧剥离 TypeScript 类型（类型注解仅供参考，绝不执行类型检查）、端口桥接绑定、预算／堆隔离 | 注册 `ctx.codeRuntime` |
-| [`e2b/code-runtime-e2b`](../e2b/code-runtime-e2b/README.md) | E2B 后端：宿主侧类型剥离与绑定、全新远程 runner／worker、分帧桥、远程进程组清理 | 注册 `ctx.codeRuntime` |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行 seam 与共享词汇 | `ctx.codeRuntime` |
+| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker 线程后端 | 注册 `ctx.codeRuntime` |
 
-不同后端的执行基底和源语言各异，二者都是服务上的只读描述符；后端注册 `ctx.codeRuntime`，无需修改接口或消费方。E2B 所有权拆分记录在[共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) 中。
+后端在不改变消费方的情况下注册该 seam。子 README 负责语言、隔离和执行预算细节。
diff --git a/packages/code-runtime/code-runtime-worker/README.i18n.yaml b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
index 10c721446f..8d3568e82e 100644
--- a/packages/code-runtime/code-runtime-worker/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-worker/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/code-runtime/code-runtime-worker/README.md
-README.md: 35196a0b4fba5cd0388246a70354308ece08b39f
-README.zh.md: 49871c38c540addd06f5d24793ae00b45e2f8bb0
+README.md: 590b79dcd1bc322350060b55767b09c6305edacc
+README.zh.md: 12c25f892bd20892cb47e593f16b6aadd9ffa84c
diff --git a/packages/code-runtime/code-runtime-worker/README.md b/packages/code-runtime/code-runtime-worker/README.md
index fbe387e4ea..590b79dcd1 100644
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -32,7 +32,7 @@ Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at
 
 ## The worker entry, unbuilt and built
 
-Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local JSON snapshotter is parity-tested against the session-owned canonical boundary; both sides flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. `tests/built-lib.e2e.ts` pins the real load path required by [docs/testing.md](../../../docs/testing.md).
+Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Its transitive runtime closure contains only Node built-ins and relative source modules, so a fresh checkout never requires a sibling workspace package's unbuilt `lib/` export. The worker-local and session-owned JSON boundaries both flatten and rebuild validated values around the message port so application nesting never reaches structured clone. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. The repository-wide requirement to exercise this published entry path belongs to the [testing policy](../../../docs/testing.md).
 
 The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
 
@@ -46,8 +46,8 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only; deployments requiring process-tree cleanup select `dsh-code-runtime-subprocess`, whose mounted subprocess provider owns that cleanup.
-- **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — the relied-on behavior is pinned by unit tests, with amaro/sucrase as named drop-in replacements if it shifts.
+- **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only, weaker than bash-local's process-group kill; orphan cleanup is a deployment concern until a container backend exists.
+- **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — amaro or sucrase are the named drop-in replacements if the relied-on behavior shifts.
 - **`computeMs` expiry can overshoot by up to one poll interval** — busy time is sampled every 25 ms (an internal constant, deliberately not config).
 - **Programs get a five-method `console` shim** (`log`/`info`/`warn`/`error`/`debug`) — deliberately not Node's full console surface.
 - **Intermediate binding values have no byte cap** — a program can exhaust process or worker memory with a value that never becomes outer output.
diff --git a/packages/code-runtime/code-runtime-worker/README.zh.md b/packages/code-runtime/code-runtime-worker/README.zh.md
index 57f2a1145a..12c25f892b 100644
--- a/packages/code-runtime/code-runtime-worker/README.zh.md
+++ b/packages/code-runtime/code-runtime-worker/README.zh.md
@@ -23,18 +23,18 @@
 - **每次运行使用一个全新 worker，不设池化**：程序所在的世界会随 worker 一同终止，不会留下需要记录的跨运行状态，也无法发生状态泄漏；仅凭会话日志即可重建运行。
 - **在执行上下文中，由宿主侧剥离类型**：程序会包裹在异步函数外壳中，通过 `node:module` 的 `stripTypeScriptTypes` 剥离类型（只支持可擦除语法；`enum`／namespace 会作为程序 `exception` 被拒绝，且不会启动 worker），再按字节位置切回原内容。之后程序作为 `AsyncFunction` 的函数体执行，因此顶层 `await`／`return` 可用。
 - **端口把对端视为不可信**：模型代码能够访问 `parentPort` 并伪造通信，因此任何代码读取入站消息前，系统都会验证其形状并重新构建（`null`、原始值、无效类型和格式错误的载荷会被静默丢弃；伪造的额外字段绝不会被带入）；宿主对每个调用 id 最多响应一次，只将绑定名称解析为自有属性（伪造的 `constructor` 无法沿原型链访问），丢弃结算后的回复，并验证每个绑定 resolve 值与完成值是否为无损 JSON。伪造的 `log`／`done` 消息无法绕过外层上限：宿主会再次验证，并统计每条获准日志以及完成值或诊断。worker 侧命名空间使用 null-prototype 和 `defineProperty`，因此形似 `__proto__` 的绑定名称只是普通键。
-- **绑定 reject 类属于请求数据**：可选命名空间描述符会指定构造器全局变量，以及用于接收失败成员名称的自有属性。worker 会创建并注入该真实类，使 `instanceof` 生效，同时无需硬编码 `tools` 或 `ToolCallError`；全局变量无效或冲突的声明会在启动 worker 前失败。失败路径使用模块捕获的错误与属性定义 intrinsic，以及 null-prototype 描述符，因此模型之后的修改无法把被拒绝的绑定变成 worker 崩溃。
-- **两个独立预算，因为对端不可信**：`computeMs` 统计 worker 实际测得的忙碌时间（轮询 `worker.performance.eventLoopUtilization()`）；热循环无法借助待完成的诱饵 dispatch 隐藏，程序等待慢工具时则不累计。`maxWallMs` 为忙碌时间无法观测的情况兜底（例如等待永远不会 resolve 的 promise）。二者最终都会调用 `worker.terminate()`，连同步热循环也能终止；堆溢出会表现为 worker 的 OOM 退出（`kind: 'worker-exit'`）。`maxWallMs` 在加载时会对照 `MAX_TIMER_DELAY_MS` 做范围校验：`setTimeout` 会把更长的延迟夹到 1 ms，仅有正数校验会放行一个在第一个 tick 就到期的上限。`computeMs` 不需要这道上界，因为它对照的是实测占用率，而不是喂给定时器。
-- **中间绑定值是完整 JSON**：绑定参数与 resolve 值会接受迭代式无损 JSON 验证。程序执行前，worker 会捕获自己 realm 中的普通容器原型身份，以及只用于外部 realm 的原生函数源码检查，因此构造器槽修改和用户编写的仿冒对象都无法改变容器分类。它还会捕获该 JSON 边界使用的每一个结构与计量 intrinsic，以无原型对象创建属性描述符，并绕过可变集合原型管理私有遍历状态；因此，模型对全局对象、原型方法或 `Object.prototype` 上形似描述符字段的修改，都无法改变验证、wire 传输或字节计量。值会展平为有深度上限的前序 wire 值，供 structured clone 使用，并在另一侧迭代式重建。它们没有字节、JavaScript 调用栈或嵌套 structured-clone 深度上限，绝不会进入外层输出账本或模型上下文；上限仍来自提供方／执行器获取限制与进程／worker 内存。
-- **日志主动流入一个外层账本**：console／stdout／stderr 文本按发送顺序穿过端口，因此超时或被终止的程序仍会显示已经打印的内容。worker 会按 JSON 字符串精确计费，并在发送完成值和异常诊断前，根据组合预算的剩余量预检；因此，抛出的百万字节 stack 会在 worker 边界变成固定的 `output-limit` 诊断。绕过补丁 stream 槽的原生写入会到达独立于完成端口的 pipe，因此宿主会针对这些字节和不可信伪造通信再次执行账本统计；在物化结果前，结算过程会持续进行有界 pipe 捕获，直到 worker 完成终止。`maxOutputBytes` 统计外层 `logs` 数组加完成值或失败消息载荷的 JSON 序列化；固定的 `CodeRunResult` 字段名、花括号、有界错误 kind 标签，以及后续呈现空白不计入这份可变载荷账本。未超过上限时会返回精确值；有损完成值属于 `invalid-output`，组合溢出属于 `output-limit`，不会用 inspected string 代替。失败会保留能容纳的已捕获前缀，之后按普通外层 `run_code` 落盘策略处理。
-- **空环境**：worker 使用 `env: {}` 和 `execArgv: []`，既没有环境凭据（比 spawn 命令的清理环境规则更严格），也不会继承 loader 标志。
-- **释放资源时等待完全停稳**：清理会把进行中的运行标记为 `abort`，并在 resolve 前等待每个 worker 退出。
+- **绑定调用被拒绝时使用的异常类属于请求数据**：可选命名空间描述符会指定构造器全局变量，以及用于接收调用失败的成员名称的自有属性。worker 会创建并注入该真实类，使 `instanceof` 生效，同时无需硬编码 `tools` 或 `ToolCallError`；全局变量无效或冲突的声明会在启动 worker 前失败。失败路径使用模块捕获的错误 intrinsic 与属性定义 intrinsic，以及 null-prototype 描述符，因此模型之后的修改无法把被拒绝的绑定变成 worker 崩溃。
+- **两个独立预算，因为对端不可信**：`computeMs` 统计 worker 实际测得的忙碌时间（轮询 `worker.performance.eventLoopUtilization()`）；热循环无法借助待完成的诱饵 dispatch 隐藏，程序等待慢工具时则不累计。`maxWallMs` 为忙碌时间无法观测的情况兜底（例如等待永远不会 resolve 的 promise）。二者最终都会调用 `worker.terminate()`，连同步热循环也能终止；堆溢出会表现为 worker 的 OOM 退出（`kind: 'worker-exit'`）。`maxWallMs` 在加载时会对照 `MAX_TIMER_DELAY_MS` 做范围校验：`setTimeout` 会把更长的延迟限制为 1 ms，仅有正数校验会放行一个在第一个 tick 就到期的上限。`computeMs` 不需要这道上界，因为它对照的是实测占用率，而不是喂给定时器。
+- **中间绑定值是完整 JSON**：绑定参数与 resolve 值会接受迭代式无损 JSON 验证。程序执行前，worker 会捕获自己 realm 中的普通容器原型身份，以及只用于外部 realm 的原生函数源码检查，因此构造器槽修改和用户编写的仿冒对象都无法改变容器分类。它还会捕获该 JSON 边界使用的每一个结构与计量 intrinsic，以无原型对象创建属性描述符，并绕过可变集合原型管理私有遍历状态；因此，模型对全局对象、原型方法或 `Object.prototype` 上形似描述符字段的修改，都无法改变验证、wire 传输或字节计量。值会展平为自身嵌套深度有界的前序 wire 值，供 structured clone 使用，并在另一侧迭代式重建。它们没有字节、JavaScript 调用栈或嵌套 structured-clone 深度上限，绝不会进入外层输出账本或模型上下文；上限仍来自提供方／执行器获取限制与进程／worker 内存。
+- **日志主动流入一个外层账本**：console／stdout／stderr 文本按产生顺序经端口传输，因此超时或被终止的程序仍会显示已经打印的内容。worker 会精确统计 JSON 字符串的字节数，并在发送完成值和异常诊断前，根据组合预算的剩余量预检；因此，抛出的百万字节 stack 会在 worker 边界变成固定的 `output-limit` 诊断。绕过补丁 stream 槽的原生写入会到达独立于完成端口的 pipe，因此宿主会针对这些字节和不可信伪造通信再次执行账本统计；在物化结果前，结算过程会持续进行有界 pipe 捕获，直到 worker 完成终止。`maxOutputBytes` 统计外层 `logs` 数组加完成值或失败消息载荷的 JSON 序列化；固定的 `CodeRunResult` 字段名、花括号、有界错误 kind 标签，以及后续呈现空白不计入这份可变载荷账本。未超过上限时会返回精确值；有损完成值属于 `invalid-output`，组合溢出属于 `output-limit`，不会用 inspected string 代替。失败会保留能容纳的已捕获前缀，之后按普通外层 `run_code` 落盘策略处理。
+- **空环境**：worker 使用 `env: {}` 和 `execArgv: []`，既不会获得环境变量中的凭据（比 spawn 命令的清理环境规则更严格），也不会继承 loader 标志。
+- **dispose（资源释放）时等待完全停稳**：清理会使进行中的运行以 `abort` 失败，并会等待每个 worker 退出后再完成。
 
 ## 未构建与已构建的 worker 入口
 
-源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地 JSON 快照器会与会话自有的规范边界执行一致性测试；消息端口两侧都会展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的 VFS Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。`tests/built-lib.e2e.ts` 固定了 [docs/testing.md](../../../docs/testing.md) 要求的真实加载路径。
+源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地和会话自有的 JSON 边界都会在消息端口周围展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的虚拟文件系统（VFS）Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。演练这个已发布入口路径的仓库级要求由[测试策略](../../../docs/testing.md)规定。
 
-SDK 接口是默认／具名 `WorkerCodeRuntime` 类与 `Config`。可操作的 `./worker` 子路径仅作为打包后的 spawn 入口存在；wire 协议与启动辅助模块是源代码私有的实现细节。
+SDK 对外提供默认及具名导出的 `WorkerCodeRuntime` 类，以及 `Config`。运行所用的 `./worker` 子路径仅作为打包后的 spawn 入口存在；wire 协议与启动辅助模块是源代码私有的实现细节。
 
 ## 模型体验
 
@@ -42,13 +42,13 @@ SDK 接口是默认／具名 `WorkerCodeRuntime` 类与 `Config`。可操作的
 
 #### KV Cache 影响
 
-不会直接失效；由具名消费方负责请求前缀变更。
+不会直接失效；由上述消费方负责请求前缀变更。
 
-## 已知限制与暂缓工作
+## 已知限制与暂缓事项
 
-- **程序 spawn 的 OS 进程在终止后仍会存活**：`worker.terminate()` 只结束线程；需要清理进程树的部署应选择 `dsh-code-runtime-subprocess`，由其挂载的子进程提供方负责该清理。
-- **类型剥离依赖 Node 的实验性 `stripTypeScriptTypes` API**：依赖的行为由单元测试固定；如其发生变化，amaro／sucrase 是已经点名的直接替代品。
+- **程序派生的 OS 进程在程序终止后仍会存活**：`worker.terminate()` 只结束线程，比 bash-local 的进程组终止更弱；在容器后端出现前，孤儿进程清理属于部署职责。
+- **类型剥离依赖 Node 的实验性 `stripTypeScriptTypes` API**：如依赖的行为发生变化，amaro 或 sucrase 是已经点名的直接替代品。
 - **`computeMs` 到期最多可能超过一个轮询间隔**：系统每 25 ms 采样一次忙碌时间（内部常量，有意不做成配置）。
-- **程序获得一个含 5 种方法的 `console` shim**（`log`／`info`／`warn`／`error`／`debug`）：有意不提供 Node 的完整 console 接口。
+- **程序获得一个含 5 个方法的 `console` shim**（`log`／`info`／`warn`／`error`／`debug`）：有意不提供 Node 的完整 console 接口。
 - **中间绑定值没有字节上限**：程序可以用永远不会成为外层输出的值耗尽进程或 worker 内存。
 - **默认 64 MiB 是拒绝边界，不是可恢复存储**：外层落盘只能保存发生 `output-limit` 后返回的有界日志和诊断；在运行时上限之外被拒绝的字节永远不会到达落盘层。
diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts
index 2ece0b5c39..43801899a2 100644
--- a/packages/code-runtime/code-runtime-worker/src/index.ts
+++ b/packages/code-runtime/code-runtime-worker/src/index.ts
@@ -21,10 +21,6 @@ import { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from
 import { decodeWorkerJson, encodeWorkerJson } from './worker-json.ts'
 import type { WorkerJsonWire } from './worker-json.ts'
 
-export { jsonStringBytesUpTo, jsonValueBytesUpTo, truncateJsonStringBytes } from './output-json.ts'
-export { decodeWorkerJson, encodeWorkerJson } from './worker-json.ts'
-export type { WorkerJsonWire } from './worker-json.ts'
-
 /** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */
 export interface Config {
   /**
@@ -169,19 +165,14 @@ function parseWorkerMessage(raw: unknown): WorkerToHost | undefined {
 }
 
 
-/** Shared outer-output accounting for one isolated run; binding values never enter it. */
-export class OutputLedger {
+/** One run's combined outer-output ledger; binding values never enter it. */
+class OutputLedger {
   private bytes = 2 // JSON serialization of the empty logs array: []
   private entries = 0
 
   constructor(private readonly maxBytes: number) {}
 
-  /**
-   * Admit one exact log entry, or report that the hard cap was crossed.
-   * @param text - Candidate log entry.
-   * @param sink - Accepted log entries for the current run.
-   * @returns Whether the complete entry fits the remaining outer-output budget.
-   */
+  /** Admit one exact log entry, or report that the hard cap was crossed. */
   admit(text: string, sink: string[]): boolean {
     const separatorBytes = this.entries > 0 ? 1 : 0
     const stringBytes = jsonStringBytesUpTo(text, this.maxBytes - this.bytes - separatorBytes)
@@ -192,33 +183,19 @@ export class OutputLedger {
     return true
   }
 
-  /**
-   * Finalize a successful absent-or-JSON completion against the combined cap.
-   * @param logs - Already accepted log entries.
-   * @param value - Optional lossless-JSON completion value.
-   * @returns A success result or an output-limit failure.
-   */
+  /** Finalize a successful absent-or-JSON completion against the combined cap. */
   success(logs: string[], value?: CodeJsonValue): CodeRunResult {
     if (value !== undefined && jsonValueBytesUpTo(value, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
     return { logs, ...value !== undefined ? { value } : {} }
   }
 
-  /**
-   * Finalize a failure diagnostic, with output-limit taking precedence when combined bytes exceed the cap.
-   * @param logs - Already accepted log entries.
-   * @param error - Candidate failure diagnostic.
-   * @returns The diagnostic result or an output-limit failure.
-   */
+  /** Finalize a failure diagnostic, with output-limit taking precedence when combined bytes exceed the cap. */
   failure(logs: string[], error: CodeRunFailure): CodeRunResult {
     if (jsonStringBytesUpTo(error.message, this.maxBytes - this.bytes) === undefined) return this.limit(logs)
     return { logs, error }
   }
 
-  /**
-   * Build the explicit output-limit failure while retaining a fitting prefix of the final log.
-   * @param logs - Candidate log entries in original order.
-   * @returns A capped output-limit result.
-   */
+  /** Build the explicit output-limit failure while retaining a fitting prefix of the final log. */
   limit(logs: string[]): CodeRunResult {
     const fullMessage = `outer output exceeded ${this.maxBytes} bytes`
     // The fixed diagnostic is ASCII, so every character is one byte plus the quotes.
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index 51c1466872..a6bd209c7b 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/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/code-runtime/code-runtime/README.md
-README.md: c7690412d0f1bc8556fc758da4e94c6ce5a08d8f
-README.zh.md: ecfa48a97c46113c52f13c7a6edfc5d6fbbc2285
+README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
+README.zh.md: 15fbcecf77b2318acf3b09101802cd032ae426d2
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index 4018cdf508..bb1c20d00a 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -34,5 +34,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
 - **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)).
-- **Isolation is backend-specific** — the worker backend is process-local, while the E2B backend reports `container` and keeps orchestration and bindings on the host; the descriptor remains informational rather than a security claim.
+- **Only the worker-thread backend ships** — `'process'`/`'container'` are declared well-known `isolation` values with no implementation; a hard security boundary awaits a container backend.
 - **Intermediate binding values have no byte cap** — implementations remain subject to structured-clone cost and process memory, while a provider or executor may already have imposed its own acquisition bound.
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index ecfa48a97c..15fbcecf77 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -4,21 +4,23 @@
 
 这是**代码执行 seam**：抽象的 `CodeRuntime` 服务（`ctx.codeRuntime`）只定义代码运行时做什么，即针对宿主提供的一组异步绑定运行一段模型编写的程序，并报告 `{ value, logs, error? }`，而不规定如何实现。
 
-此包是该能力的接口层（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。两者都由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有工具形状的内容都留在消费方。
+此包承担该能力三个组成部分中的接口职责（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。这两项职责均由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有与工具有关的内容都留在消费方。
 
 ## 服务 API（`ctx.codeRuntime`）
 
 | 成员 | 语义 |
 |---|---|
-| `run(request)` | 针对请求的绑定执行一段程序。**每一种程序结果都通过 error 字段完成 resolve**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底死亡（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 seam 本身时才 reject（例如资源释放后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
-| `language` | 只读描述符：`run` 期望的源语言（已知值为 `'typescript'`）。仅供参考，不作门禁；生成语言专用呈现的消费方会对该值执行分支，遇到无法呈现的语言时明确失败。 |
+| `run(request)` | 针对请求的绑定执行一段程序。**所有程序失败结果都通过 resolve 结果中的 error 字段报告**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底终止（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 seam 本身时才 reject（例如 dispose（资源释放）后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
+| `language` | 只读描述符：`run` 期望的源语言。已知值为 `'typescript'` 与 `'python'`——`dsh-tools` 能呈现的那些；其中只有 `'typescript'` 有已发布的后端。仅供参考，不作门禁；生成语言专用呈现的消费方会根据该值选择分支，遇到无法呈现的语言时明确失败。 |
 | `isolation` | 只读描述符：执行基底（`'worker-thread'`、`'process'`、`'container'`）。供部署与诊断使用，**不构成安全声明**。 |
 
-每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为不可信对等方（任意绑定名称都是自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；资源释放会终止进行中的运行，并且在完成前等待其退出。
+每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为敌对对等方（任意绑定名称都会成为自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；dispose 会终止进行中的运行，并且在完成前等待其退出。
 
 ## 词汇
 
-`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收 reject 成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
+`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
+
+binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的契约——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
 
 ## 模型体验
 
@@ -26,11 +28,11 @@
 
 #### KV Cache 影响
 
-不会直接失效；由具名消费方负责请求前缀变更。
+不会直接失效；由上述消费方负责请求前缀变更。
 
-## 已知限制与暂缓工作
+## 已知限制与暂缓事项
 
-- **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供活跃程序输出的流式日志或进度接口。
+- **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供正在运行的程序所产生输出的流式日志或进度接口。
 - **持久 REPL 风格内核已记录为未来工作**：在持久内核后端带来自己的日志方案前，运行之间不保留状态的契约继续有效（参见 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)）。
-- **隔离方式由后端决定**：worker 后端位于宿主进程内，而 E2B 后端报告 `container`，并把编排与绑定留在宿主；该描述符仍只提供信息，不构成安全声明。
+- **目前只提供 worker 线程后端**：`'process'`／`'container'` 是已经声明但没有实现的已知 `isolation` 值；强安全边界需要等待容器后端。
 - **中间绑定值没有字节上限**：实现仍受 structured-clone 成本与进程内存约束，而提供方或执行器可能已经应用自己的获取上限。
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 21848e55e2..5bd34a8642 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -304,6 +304,16 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'e2b',
+    summary: 'Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal.',
+    methods: [
+      {
+        signature: 'async getSandbox(): Promise<Sandbox>',
+        jsDoc: '/**\n * Return the shared live SDK handle.\n * @returns the created sandbox after the configured cwd exists.\n * @throws when E2B rejects creation or the service is disposing.\n */',
+      },
+    ],
+  },
   {
     key: 'fs',
     summary: 'Abstract filesystem provider.',
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index c09243183e..01316aeb2d 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -3,6 +3,7 @@ import { join, posix } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
+import { Inbox } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 import {
@@ -78,18 +79,20 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       expect(environmentProbe.collected.stdout?.readFrom(0).text).toBe('DIRECT=<> LEAK=<0>\n')
       await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
       const ownerId = SessionId('e2b-pty-env-owner')
+      const ownerSession = Session.create(ownerId)
       const owner: Agent = {
         id: ownerId,
         options: {},
-        session: new Session(ownerId),
+        session: ownerSession,
+        inbox: new Inbox(ownerSession, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
         status: 'idle',
-        acceptsNextStep: false,
         ctx,
-        followup() {},
-        steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
-        inject() {},
         send() {},
+        followup() {},
+        steer() {},
+        inject() {},
         cancel() {},
+        runMaintenance: task => task(new AbortController().signal),
         whenIdle: () => Promise.resolve(),
       }
       const backend = new LocalPtyBackend(ctx, {
diff --git a/packages/e2b/subprocess-e2b/src/environment.ts b/packages/e2b/subprocess-e2b/src/environment.ts
index 8daae9ccfd..7cdb1b7fbf 100644
--- a/packages/e2b/subprocess-e2b/src/environment.ts
+++ b/packages/e2b/subprocess-e2b/src/environment.ts
@@ -84,19 +84,21 @@ export function bootstrapEnvironment(raw: string): Record<string, string> {
 /**
  * Overlay explicit entries and serialize one validated E2B environment.
  * @param raw - The complete NUL-delimited remote environment.
- * @param explicit - Deliberate caller overrides applied after ambient scrubbing.
+ * @param explicit - Deliberate caller overrides applied after ambient scrubbing; an `undefined` tombstone removes an ambient entry.
  * @returns NUL-delimited `name=value` entries accepted by `env -i`.
  */
 export function serializeRemoteEnvironment(
   raw: string,
-  explicit: Readonly<Record<string, string>> | undefined,
+  explicit: Readonly<NodeJS.ProcessEnv> | undefined,
 ): string {
   const environment = scrubRemoteEnvironment(raw)
   for (const [name, value] of Object.entries(explicit ?? {})) {
-    if (name.length === 0 || name.includes('=') || name.includes('\0') || value.includes('\0')) {
+    if (name.length === 0 || name.includes('=') || name.includes('\0') || value?.includes('\0') === true) {
       throw new Error('subprocess-e2b: environment entries require non-empty NUL-free names without = and NUL-free values')
     }
-    environment.set(name, value)
+    // An explicit undefined is the seam's tombstone: remove the ambient entry.
+    if (value === undefined) environment.delete(name)
+    else environment.set(name, value)
   }
   return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
 }
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index be241ada6e..9919cdaba5 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: d8bc6047e7eadeb2993f1114564b41913b2970dc
-README.zh.md: d838af346626bb96299a3b702df0dabb6231c15a
+README.md: 7fbdf071735673fb0158f6fa66148be1c644a433
+README.zh.md: e059dbd80b7e38c0e447e54178162316dfd127c7
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index d8bc6047e7..7fbdf07173 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -7,10 +7,9 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 | Package | Role | ctx key |
 |---|---|---|
 | `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
-| [`lsp-local/`](lsp-local/README.md) | Generic multi-server local backend (spawn, JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
-| [`e2b/lsp-e2b`](../e2b/lsp-e2b/README.md) | Remote E2B backend (remote source reads and servers, byte-framed stdio bridge) | (registers providers on `ctx.lsp`) |
+| `lsp-local/` | Generic multi-server stdio backend over `ctx.fs` and `ctx.subprocess` (JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
 | `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
 The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
 
-See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the protocol design and the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) for the remote process/filesystem boundary.
+See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index d838af3466..e059dbd80b 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -7,10 +7,9 @@
 | 包 | 职责 | ctx key |
 |---|---|---|
 | `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
-| [`lsp-local/`](lsp-local/README.md) | 通用多服务器本地后端（spawn、JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
-| [`e2b/lsp-e2b`](../e2b/lsp-e2b/README.md) | 远程 E2B 后端（在远程读取源文件并运行服务器、采用字节分帧的 stdio 桥） | （在 `ctx.lsp` 上注册提供方） |
+| `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
 | `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
 接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
-协议设计见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，远程进程／文件系统边界见 [共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md)。
+设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts
index 3a2baa0c55..fc7e50787f 100644
--- a/packages/lsp/lsp-local/src/index.ts
+++ b/packages/lsp/lsp-local/src/index.ts
@@ -1,19 +1,16 @@
 /**
  * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table
  * of server commands and registers one isolated provider for each entry. Every provider lazily
- * single-flights one server process per canonical workspace realpath, serves transient-open queries
+ * single-flights one server process per canonical workspace target, serves transient-open queries
  * through it, and replaces a selected transport that fails before or during the next read-only
- * query. Providers read sources through Node APIs in the host namespace (not `ctx.fs`)
- * and trust their configured servers — no sandbox confinement.
+ * query. Providers read sources through `ctx.fs` and launch servers through
+ * `ctx.subprocess`, so both local and remote implementations share one host.
  *
  * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
  * unregisters from `ctx.lsp` and tears down every live server.
  * @module @deepseek-ai/dsh-lsp-local
  */
 
-import { accessSync, constants, statSync } from 'node:fs'
-import { delimiter, isAbsolute, join } from 'node:path'
-import { pathToFileURL } from 'node:url'
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
@@ -25,9 +22,9 @@ import type {
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { abortable, abortError } from './abort.ts'
 import { canonicalizeWorkspace, readHostSource } from './host.ts'
+import type { HostWorkspace } from './host.ts'
 import { LspInstance } from './instance.ts'
 import type { ConnectionSpawner } from './connection.ts'
-import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import type { InstanceSpec } from './instance.ts'
 
 export { canonicalizeWorkspace, readHostSource } from './host.ts'
@@ -47,10 +44,7 @@ export { LspConnection } from './connection.ts'
 export const name = 'lsp-local'
 
 /** Services required by this plugin. */
-export const inject = ['lsp', 'subprocess']
-
-/** Credential-shaped ambient env vars are NOT forwarded to the child by default. */
-
+export const inject = ['fs', 'lsp', 'subprocess']
 
 const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
 const DEFAULT_MAX_STDERR_BYTES = 1_000_000
@@ -92,6 +86,7 @@ export interface Config {
 
 /** One server config after schemastery fills every default. */
 type ResolvedServerConfig = Required<LspLocalServerConfig>
+type WorkspaceKey = HostWorkspace['target']['targetKey']
 
 const LspLocalServerConfig: z<LspLocalServerConfig> = z.object({
   command: z.string().required(),
@@ -111,27 +106,67 @@ export const Config: z<Config> = z.object({
   servers: z.dict(LspLocalServerConfig).required(),
 })
 
+/** Propagate teardown failures only after every sibling has settled. */
+function throwTeardownFailures(results: readonly PromiseSettledResult<void>[], message: string): void {
+  const failures: unknown[] = []
+  for (const result of results) {
+    if (result.status === 'rejected') failures.push(result.reason)
+  }
+  if (failures.length === 1) throw failures[0]
+  if (failures.length > 1) throw new AggregateError(failures, message)
+}
+
 /**
  * Register the configured stdio LSP providers. Resolves every executable at load (after credential
  * scrubbing) before publishing any provider; each process launches lazily on its first matching
  * query.
- * @param ctx - the plugin context (must inject `lsp`).
+ * @param ctx - the plugin context carrying `fs`, `lsp`, and `subprocess`.
  * @param config - the resolved plugin configuration (schemastery has filled every default).
  */
-export function apply(ctx: Context, config: Config): void {
+export async function apply(ctx: Context, config: Config): Promise<void> {
   const entries = Object.entries(config.servers)
   if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server')
 
+  const setupAbort = new AbortController()
+  const stopSetupCancellation = ctx.on('internal/plugin', (fiber) => {
+    // An async plugin callback must observe its own disposal before Cordis can
+    // run effect cleanup, because unload otherwise waits for this callback.
+    if (fiber === ctx.fiber && fiber.uid === null) {
+      setupAbort.abort(new Error('lsp-local setup disposed'))
+    }
+  })
+
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
-  const providers = entries.map(([providerId, rawConfig]) => {
-    if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
-    const resolved = rawConfig as ResolvedServerConfig
-    validateServerConfig(providerId, resolved)
-    const childEnv = buildChildEnv(resolved.env)
-    const executable = resolveExecutable(resolved.command, childEnv)
-    return new LocalLspProvider(providerId, resolved, childEnv, executable, spec => ctx.subprocess.spawn(spec))
-  })
+  const providers = await (async () => {
+    const lookups = entries.map(async ([providerId, rawConfig]) => {
+      if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
+      const resolved = rawConfig as ResolvedServerConfig
+      validateServerConfig(providerId, resolved)
+      const executable = await ctx.subprocess.resolveExecutable(
+        resolved.command,
+        resolved.env,
+        setupAbort.signal,
+      )
+      setupAbort.signal.throwIfAborted()
+      return new LocalLspProvider(
+        providerId,
+        ctx.fs,
+        resolved,
+        executable,
+        spec => ctx.subprocess.spawn(spec),
+      )
+    })
+    try {
+      return await Promise.all(lookups)
+    } catch (error: unknown) {
+      setupAbort.abort(error)
+      await Promise.allSettled(lookups)
+      throw error
+    } finally {
+      stopSetupCancellation()
+    }
+  })()
 
   ctx.effect(() => {
     const disposers: Array<() => void> = []
@@ -144,7 +179,8 @@ export function apply(ctx: Context, config: Config): void {
     return async () => {
       // Remove every route before process teardown so no new query can enter a draining provider.
       for (const dispose of disposers.reverse()) dispose()
-      await Promise.all(providers.map(provider => provider.disposeAll()))
+      const results = await Promise.allSettled(providers.map(provider => provider.disposeAll()))
+      throwTeardownFailures(results, 'lsp-local provider teardown failed')
     }
   }, 'lsp-local.registerProviders')
 }
@@ -181,16 +217,19 @@ function assertPositiveInteger(providerId: string, name: string, value: number):
 class LocalLspProvider implements LspProvider {
   readonly id: LspProviderId
   readonly extensionToLanguage: Readonly<Record<string, string>>
-  /** One live instance per canonical workspace realpath. */
-  private readonly instances = new Map<string, LspInstance>()
+  /** One live instance per stable canonical workspace identity. */
+  private readonly instances = new Map<WorkspaceKey, LspInstance>()
   /** One complete source-read→open→query→close serialization tail per canonical workspace. */
-  private readonly queues = new Map<string, Promise<void>>()
+  private readonly queues = new Map<WorkspaceKey, Promise<void>>()
+  /** Workspace canonicalizations that have not entered a provider-owned queue yet. */
+  private readonly workspaceLookups = new Set<Promise<void>>()
+  private readonly lifetime = new AbortController()
   private disposed = false
 
   constructor(
     providerId: string,
+    private readonly fs: Context['fs'],
     private readonly config: ResolvedServerConfig,
-    private readonly childEnv: Record<string, string>,
     private readonly executable: string,
     private readonly spawner: ConnectionSpawner,
   ) {
@@ -211,43 +250,60 @@ class LocalLspProvider implements LspProvider {
     if (signal?.aborted) throw abortError(signal)
   }
 
+  /** Fuse caller cancellation with provider disposal for every filesystem and protocol await. */
+  private querySignal(signal?: AbortSignal): AbortSignal {
+    return signal === undefined
+      ? this.lifetime.signal
+      : AbortSignal.any([signal, this.lifetime.signal])
+  }
+
   async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
-    // Honor an already-aborted signal before host I/O so a canceled request never starts a server.
+    // Honor an already-aborted signal before provider I/O so a canceled request never starts a server.
     this.assertActive(signal)
-    const workspace = await canonicalizeWorkspace(request.workspaceRoot, signal)
-    this.assertActive(signal)
-    return this.enqueue(workspace, signal, async () => {
-      this.assertActive(signal)
+    const querySignal = this.querySignal(signal)
+    const workspaceResult = canonicalizeWorkspace(this.fs, request.workspaceRoot, querySignal)
+    const workspaceLookup = workspaceResult.then(() => undefined, () => undefined)
+    this.workspaceLookups.add(workspaceLookup)
+    let workspace: HostWorkspace
+    try {
+      workspace = await workspaceResult
+    } finally {
+      this.workspaceLookups.delete(workspaceLookup)
+    }
+    this.assertActive(querySignal)
+    const workspaceKey = workspace.target.targetKey
+    return this.enqueue(workspaceKey, querySignal, async () => {
+      this.assertActive(querySignal)
       // Read inside the workspace queue but before spawning: a queued query sees current bytes when
       // its turn starts, while an invalid source still cannot leave an idle process pooled.
-      const source = await readHostSource(request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, querySignal)
       // Disposal may have snapshotted the instance map while host I/O was pending. Re-check before a
       // synchronous get-or-create so every spawned process remains owned by teardown.
-      this.assertActive(signal)
-      let instance = this.instanceFor(workspace)
+      this.assertActive(querySignal)
+      let instance = this.instanceFor(workspaceKey, workspace)
       try {
-        return await instance.query(request, source, signal)
+        return await instance.query(request, source, querySignal)
       } catch (error) {
         // A selected child can have died while idle or fail during the next write. Queries are
         // read-only, so replace that transport once and retry transparently.
         if (!instance.isTransportFailure(error)) throw error
         await instance.dispose()
-        this.evictIfCurrent(workspace, instance)
-        this.assertActive(signal)
-        instance = this.instanceFor(workspace)
-        return await instance.query(request, source, signal)
+        this.evictIfCurrent(workspaceKey, instance)
+        this.assertActive(querySignal)
+        instance = this.instanceFor(workspaceKey, workspace)
+        return await instance.query(request, source, querySignal)
       } finally {
         // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check.
         if (instance.dead) {
           await instance.dispose()
-          this.evictIfCurrent(workspace, instance)
+          this.evictIfCurrent(workspaceKey, instance)
         }
       }
     })
   }
 
   /** Serialize one complete query lifecycle for a canonical workspace. */
-  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
+  private enqueue<T>(workspace: WorkspaceKey, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
     const previous = this.queues.get(workspace) ?? Promise.resolve()
     const result = abortable(previous, signal).then(run)
     // The tail follows the actual prior work even when this caller aborts its wait. It never rejects,
@@ -261,34 +317,34 @@ class LocalLspProvider implements LspProvider {
   }
 
   /** Return or synchronously publish the one instance for a canonical workspace. */
-  private instanceFor(workspace: string): LspInstance {
+  private instanceFor(workspaceKey: WorkspaceKey, workspace: HostWorkspace): LspInstance {
     this.assertActive()
-    const existing = this.instances.get(workspace)
+    const existing = this.instances.get(workspaceKey)
     if (existing !== undefined) return existing
     const created = this.createInstance(workspace)
-    this.instances.set(workspace, created)
+    this.instances.set(workspaceKey, created)
     return created
   }
 
   /** Drop the slot iff it still contains this instance. */
-  private evictIfCurrent(workspace: string, instance: LspInstance): void {
+  private evictIfCurrent(workspace: WorkspaceKey, instance: LspInstance): void {
     /* v8 ignore next -- mismatch requires another query to replace the slot before this finally runs. */
     if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
   }
 
-  private createInstance(workspace: string): LspInstance {
+  private createInstance(workspace: HostWorkspace): LspInstance {
     const spec: InstanceSpec = {
       command: this.executable,
       args: this.config.args,
-      cwd: workspace,
-      env: this.childEnv,
+      cwd: workspace.canonicalPath,
+      workspaceUri: workspace.fileUrl,
+      env: this.config.env,
       configuration: this.config.configuration,
       initializationOptions: this.config.initializationOptions,
       maxMessageBytes: this.config.maxMessageBytes,
       maxStderrBytes: this.config.maxStderrBytes,
       shutdownTimeoutMs: this.config.shutdownTimeoutMs,
       killGraceMs: this.config.killGraceMs,
-      pathToFileUri: path => pathToFileURL(path).href,
     }
     return new LspInstance(spec, this.spawner)
   }
@@ -296,51 +352,18 @@ class LocalLspProvider implements LspProvider {
   /** Dispose every live instance and block further queries. */
   async disposeAll(): Promise<void> {
     this.disposed = true
+    this.lifetime.abort(new LspError('lsp-local provider is disposed', 'LSP_DISPOSED'))
     const live = [...this.instances.values()]
     const draining = [...this.queues.values()]
+    const resolving = [...this.workspaceLookups]
     this.instances.clear()
-    await Promise.all([
+    const results = await Promise.allSettled([
       ...live.map(instance => instance.dispose()),
       ...draining,
+      ...resolving,
     ])
     this.queues.clear()
-  }
-}
-
-/** The seam's scrubbed parent env (credential-shaped and DSH_* names dropped), plus the config's explicit env. */
-function buildChildEnv(extra: Record<string, string>): Record<string, string> {
-  return { ...scrubbedParentEnv(), ...extra }
-}
-
-/**
- * Resolve the server executable to an absolute path: an absolute command is verified directly; a
- * bare command is looked up on the child's PATH. Fails loudly when nothing is executable.
- */
-function resolveExecutable(command: string, childEnv: Record<string, string>): string {
-  if (isAbsolute(command)) {
-    // Verify an absolute command too, so an unavailable one fails at load, not on the first query.
-    if (!isExecutableFileSync(command)) {
-      throw new Error(`lsp-local: command "${command}" is not an executable file`)
-    }
-    return command
-  }
-  /* v8 ignore next -- buildChildEnv always sets PATH from the ambient env; the further fallbacks are defensive. */
-  const pathValue = childEnv.PATH ?? process.env.PATH ?? ''
-  for (const dir of pathValue.split(delimiter)) {
-    if (dir === '') continue
-    const candidate = join(dir, command)
-    if (isExecutableFileSync(candidate)) return candidate
-  }
-  throw new Error(`lsp-local: command "${command}" was not found on PATH`)
-}
-
-/** Synchronous regular-file and executable check used only at load-time resolution. */
-function isExecutableFileSync(path: string): boolean {
-  try {
-    if (!statSync(path).isFile()) return false
-    accessSync(path, constants.X_OK)
-    return true
-  } catch {
-    return false
+    this.workspaceLookups.clear()
+    throwTeardownFailures(results, 'lsp-local instance teardown failed')
   }
 }
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index 5a12192c62..318704b9fc 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -30,18 +30,12 @@ import {
 
 /** Everything an instance needs beyond the connection spec. */
 export interface InstanceSpec extends ConnectionSpec {
+  /** Canonical workspace file URI supplied by the filesystem provider. */
+  readonly workspaceUri: string
   /** Static `initialize` options forwarded to the server. */
   readonly initializationOptions: unknown
   /** Graceful `shutdown`/`exit` budget before escalation (ms). */
   readonly shutdownTimeoutMs: number
-  /** PID advertised to the server; `null` when client and server do not share a process namespace. */
-  readonly clientProcessId?: number | null
-  /**
-   * Encode one implementation-native absolute path as a file URI.
-   * @param path - Canonical workspace or source path.
-   * @returns A file URI interpreted in the server's filesystem namespace.
-   */
-  readonly pathToFileUri: (path: string) => string
 }
 
 /**
@@ -115,9 +109,11 @@ export class LspInstance {
 
   private async initialize(): Promise<void> {
     const initializeResult = await this.connection.request('initialize', {
-      processId: this.spec.clientProcessId === undefined ? process.pid : this.spec.clientProcessId,
-      rootUri: this.spec.pathToFileUri(this.spec.cwd),
-      workspaceFolders: [{ uri: this.spec.pathToFileUri(this.spec.cwd), name: 'workspace' }],
+      // A subprocess provider may run in another PID namespace or machine;
+      // the host PID would let the server monitor an unrelated process.
+      processId: null,
+      rootUri: this.spec.workspaceUri,
+      workspaceFolders: [{ uri: this.spec.workspaceUri, name: 'workspace' }],
       capabilities: CLIENT_CAPABILITIES,
       initializationOptions: this.spec.initializationOptions,
     }) as WireInitializeResult
@@ -154,7 +150,7 @@ export class LspInstance {
       throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION')
     }
 
-    const uri = this.spec.pathToFileUri(source.canonicalPath)
+    const uri = source.fileUrl
     let opened = false
     try {
       /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */
@@ -248,10 +244,9 @@ export class LspInstance {
     if (operation === 'hover') {
       return { kind: 'hover', hover: normalizeHover(payload) }
     }
-    // `spec.cwd` is the canonical workspace realpath (the provider canonicalizes before spawning),
-    // and every `file:` location URI is relative to it — so it is the root a caller must relativize
-    // display paths against, not the request's possibly-symlinked workspaceRoot.
-    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceRoot: this.spec.cwd }
+    // The filesystem provider owns URI syntax for the execution platform, which may differ from the
+    // harness host. Preserve that coordinate through rendering instead of reparsing `spec.cwd` there.
+    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceUri: this.spec.workspaceUri }
   }
 
   private answerServerRequest(method: string, params: unknown): Promise<unknown> {
diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts
index 22877a94c8..08bad67ae2 100644
--- a/packages/lsp/lsp-local/tests/instance.spec.ts
+++ b/packages/lsp/lsp-local/tests/instance.spec.ts
@@ -56,7 +56,6 @@ function makeInstance(
     maxStderrBytes: 100_000,
     shutdownTimeoutMs: 200,
     killGraceMs: 200,
-    pathToFileUri: path => pathToFileURL(path).href,
     ...overrides,
   }, spawnSubprocess, writer)
   live.push(instance)
@@ -92,7 +91,6 @@ function scriptInstance(script: string, overrides: Partial<InstanceSpec> = {}):
     maxStderrBytes: 100_000,
     shutdownTimeoutMs: 150,
     killGraceMs: 150,
-    pathToFileUri: path => pathToFileURL(path).href,
     ...overrides,
   }, spawnSubprocess)
   live.push(instance)
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index e63252c7f8..02649a8d39 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/README.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
-README.md: f96fc67ec8cb95f423eff9b312b7b591ec9d3008
-README.zh.md: 13ae9700e284ff238147538a571622066efc5747
+#   pnpm run verify-translation-pairing --write packages/lsp/lsp/README.md
+README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
+README.zh.md: cc412333e63b9469319240d67269bf0192ad3858
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index 2dff12e3da..65d541a7c1 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
-README.md: a6706ed653bc60909a23b3598c41bb10ef499cbe
-README.zh.md: 01fecf8d57d933168e91331c4d3c3e4666c13cdc
+README.md: a4f743056b4a524be9623b0f700f37e0534b463f
+README.zh.md: c84ad3f1b59afcdbbd111f1b82c57c56aa24fdcf
diff --git a/packages/pty/README.md b/packages/pty/README.md
index a6706ed653..a4f743056b 100644
--- a/packages/pty/README.md
+++ b/packages/pty/README.md
@@ -7,8 +7,7 @@ English | [中文](README.zh.md)
 | Package | Role | ctx key |
 |---|---|---|
 | [`pty`](pty/README.md) (`@deepseek-ai/dsh-pty`) | Backend registry, branded ids, exact-Agent ownership, session operations, and awaited cleanup | `ctx.pty` |
-| [`pty-local`](pty-local/README.md) (`@deepseek-ai/dsh-pty-local`) | Local `node-pty` backend, readiness detection, bounded terminal state, sandboxing, and process-session supervision | registers on `ctx.pty` |
-| [`e2b/pty-e2b`](../e2b/pty-e2b/README.md) (`@deepseek-ai/dsh-pty-e2b`) | E2B byte-PTY backend, remote foreground signaling, bounded terminal state, and awaited remote cleanup | registers on `ctx.pty` |
+| `pty-local` (`@deepseek-ai/dsh-pty-local`) | Shell backend over `ctx.subprocess.spawnTerminal`: readiness detection, bounded terminal state, sandbox policy, and session operations | registers on `ctx.pty` |
 | `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
-The core design lives in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md); the remote ownership boundary lives in the [shared E2B runtime note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md).
+The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index 01fecf8d57..c84ad3f1b5 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -7,8 +7,7 @@
 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | [`pty`](pty/README.md)（`@deepseek-ai/dsh-pty`） | 后端注册表、品牌化 id、精确的 Agent 所有权、会话操作与等待完成的清理 | `ctx.pty` |
-| [`pty-local`](pty-local/README.md)（`@deepseek-ai/dsh-pty-local`） | 本地 `node-pty` 后端、就绪检测、有界终端状态、沙箱与进程会话监管 | 注册到 `ctx.pty` |
-| [`e2b/pty-e2b`](../e2b/pty-e2b/README.md)（`@deepseek-ai/dsh-pty-e2b`） | E2B 字节 PTY 后端、远程前台信号传递、有界终端状态与等待完成的远程清理 | 注册到 `ctx.pty` |
+| `pty-local`（`@deepseek-ai/dsh-pty-local`） | `ctx.subprocess.spawnTerminal` 之上的 shell 后端：就绪检测、有界终端状态、沙箱策略与会话操作 | 注册到 `ctx.pty` |
 | `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
-核心设计记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中；远程所有权边界记录在 [共享 E2B 运行时 Agent Note](../../.agents/notes/implemented/feature/2026-07-27-e2b-remote-runtime-poc.md) 中。
+设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
diff --git a/packages/pty/pty-local/src/sanitize.ts b/packages/pty/pty-local/src/sanitize.ts
new file mode 100644
index 0000000000..1f28315fb1
--- /dev/null
+++ b/packages/pty/pty-local/src/sanitize.ts
@@ -0,0 +1,188 @@
+/** Streaming terminal-control sanitizer for the line-oriented first release. */
+
+import { Buffer } from 'node:buffer'
+
+/** OSC marker emitted by the controlled bash before each prompt. */
+export const PROMPT_MARKER_PREFIX = '133;D;'
+
+/** Exact printable prompt emitted after the private marker. */
+export const CONTROLLED_PROMPT = 'dsh> '
+
+/** One sanitized chunk plus whether it contained the owned prompt marker. */
+export interface SanitizedChunk {
+  text: string
+  prompt: boolean
+  /** Printable text after the latest owned marker in this chunk. */
+  promptTail?: string
+}
+
+/**
+ * Remove CSI/OSC/short escape sequences while preserving split-sequence carry.
+ * Full terminal emulation is deliberately deferred; ordinary line output and
+ * the private prompt marker are the supported contract.
+ */
+export class TerminalSanitizer {
+  private pending = ''
+  private discardMode: 'osc' | 'csi' | undefined
+  private discardOscEscape = false
+  private trailingCarriageReturn = false
+  private trackingPromptTail = false
+
+  constructor(private readonly maxPendingBytes: number) {}
+
+  /**
+   * Consume one decoded `node-pty` data chunk.
+   * @param chunk - decoded terminal data.
+   * @returns Printable text and whether the private prompt marker completed.
+   */
+  push(chunk: string): SanitizedChunk {
+    this.pending += this.discardPrefix(chunk)
+    let text = ''
+    let prompt = false
+    let includePromptTail = this.trackingPromptTail
+    let promptTail = ''
+    let index = 0
+    const appendText = (value: string): void => {
+      text += value
+      if (this.trackingPromptTail) promptTail += value
+    }
+    while (index < this.pending.length) {
+      const escape = this.pending.indexOf('\x1b', index)
+      if (escape < 0) {
+        appendText(this.pending.slice(index))
+        index = this.pending.length
+        break
+      }
+      appendText(this.pending.slice(index, escape))
+      if (escape + 1 >= this.pending.length) {
+        index = escape
+        break
+      }
+      const kind = this.pending[escape + 1]
+      if (kind === ']') {
+        const bel = this.pending.indexOf('\x07', escape + 2)
+        const stringTerminator = this.pending.indexOf('\x1b\\', escape + 2)
+        let end = -1
+        if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2)
+        else if (bel >= 0) end = bel + 1
+        else if (stringTerminator >= 0) end = stringTerminator + 2
+        if (end < 0) {
+          index = escape
+          break
+        }
+        const terminatorBytes = this.pending[end - 1] === '\x07' ? 1 : 2
+        const content = this.pending.slice(escape + 2, end - terminatorBytes)
+        if (content.startsWith(PROMPT_MARKER_PREFIX)) {
+          prompt = true
+          this.trackingPromptTail = true
+          includePromptTail = true
+          promptTail = ''
+        }
+        index = end
+        continue
+      }
+      if (kind === '[') {
+        let end = escape + 2
+        while (end < this.pending.length) {
+          const code = this.pending.charCodeAt(end)
+          if (code >= 0x40 && code <= 0x7e) break
+          end += 1
+        }
+        if (end >= this.pending.length) {
+          index = escape
+          break
+        }
+        index = end + 1
+        continue
+      }
+      // Two-byte escape family (save/restore cursor and similar).
+      index = escape + 2
+    }
+    this.pending = this.pending.slice(index)
+    this.enforcePendingBound()
+    return {
+      text: this.normalizeText(text),
+      prompt,
+      ...includePromptTail ? { promptTail } : {},
+    }
+  }
+
+  /**
+   * Flush a trailing printable fragment when the PTY exits.
+   * @returns Remaining printable text; incomplete escapes are discarded.
+   */
+  flush(): string {
+    const text = this.pending.startsWith('\x1b') ? '' : this.pending
+    this.pending = ''
+    this.discardMode = undefined
+    this.discardOscEscape = false
+    this.trackingPromptTail = false
+    const normalized = this.normalizeText(text)
+    if (!this.trailingCarriageReturn) return normalized
+    this.trailingCarriageReturn = false
+    return `${normalized}\n`
+  }
+
+  private normalizeText(text: string): string {
+    let complete = this.trailingCarriageReturn ? `\r${text}` : text
+    this.trailingCarriageReturn = false
+    if (complete.endsWith('\r')) {
+      complete = complete.slice(0, -1)
+      this.trailingCarriageReturn = true
+    }
+    return normalizeTerminalText(complete)
+  }
+
+  private enforcePendingBound(): void {
+    if (Buffer.byteLength(this.pending) <= this.maxPendingBytes) return
+    this.discardMode = this.pending[1] === ']' ? 'osc' : 'csi'
+    this.pending = ''
+  }
+
+  private discardPrefix(chunk: string): string {
+    if (this.discardMode === undefined) return chunk
+    if (this.discardMode === 'csi') {
+      for (let index = 0; index < chunk.length; index += 1) {
+        const code = chunk.charCodeAt(index)
+        if (code >= 0x40 && code <= 0x7e) {
+          this.discardMode = undefined
+          return chunk.slice(index + 1)
+        }
+      }
+      return ''
+    }
+
+    let index = 0
+    if (this.discardOscEscape) {
+      this.discardOscEscape = false
+      if (chunk.startsWith('\\')) {
+        this.discardMode = undefined
+        return chunk.slice(1)
+      }
+    }
+    while (index < chunk.length) {
+      if (chunk[index] === '\x07') {
+        this.discardMode = undefined
+        return chunk.slice(index + 1)
+      }
+      if (chunk[index] === '\x1b') {
+        if (chunk[index + 1] === '\\') {
+          this.discardMode = undefined
+          return chunk.slice(index + 2)
+        }
+        if (index + 1 === chunk.length) this.discardOscEscape = true
+      }
+      index += 1
+    }
+    return ''
+  }
+}
+
+/**
+ * Normalize CRLF and standalone carriage returns for line-oriented rendering.
+ * @param text - sanitized terminal text.
+ * @returns Line-normalized text with BEL removed.
+ */
+export function normalizeTerminalText(text: string): string {
+  return text.replaceAll('\r\n', '\n').replaceAll('\r', '\n').replaceAll('\x07', '')
+}
diff --git a/packages/pty/pty-local/src/session.ts b/packages/pty/pty-local/src/session.ts
index ebf6b559d1..25ed8fe586 100644
--- a/packages/pty/pty-local/src/session.ts
+++ b/packages/pty/pty-local/src/session.ts
@@ -1,7 +1,12 @@
-/** Local `node-pty` session: bounded output, readiness, signals, and teardown. */
+/** Persistent PTY session over the subprocess seam's terminal primitive. */
 
-import type { IDisposable, IPty } from 'node-pty'
-import { PtyTerminalSanitizer, PtyTextBuffer, ptySignalName, ptyUtf8Tail } from '@deepseek-ai/dsh-pty'
+import { Buffer } from 'node:buffer'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+} from '@deepseek-ai/dsh-subprocess'
+import { PtyError } from '@deepseek-ai/dsh-pty'
 import type {
   PtyBackendSession,
   PtyReadRequest,
@@ -16,30 +21,89 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
+import { CONTROLLED_PROMPT, TerminalSanitizer } from './sanitize.ts'
 
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
+function utf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
+  if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
+  const chars = Array.from(text)
+  let bytes = 0
+  let start = chars.length
+  while (start > 0) {
+    const next = Buffer.byteLength(chars[start - 1] as string)
+    if (bytes + next > maxBytes) break
+    bytes += next
+    start -= 1
+  }
+  return { text: chars.slice(start).join(''), truncated: true }
+}
+
+class BoundedTextBuffer {
+  private value = ''
+  private dropped = false
+
+  constructor(
+    private readonly maxBytes: number,
+    private readonly maxLines?: number,
+  ) {}
+
+  append(text: string): void {
+    if (text.length === 0) return
+    this.value += text
+    if (this.maxLines !== undefined) {
+      const lines = this.value.split('\n')
+      if (lines.length > this.maxLines) {
+        this.value = lines.slice(lines.length - this.maxLines).join('\n')
+        this.dropped = true
+      }
+    }
+    const tail = utf8Tail(this.value, this.maxBytes)
+    this.value = tail.text
+    this.dropped ||= tail.truncated
+  }
+
+  consume(): PtySendRead {
+    const delta = this.value
+    const truncated = this.dropped
+    this.value = ''
+    this.dropped = false
+    return { delta, truncated }
+  }
+
+  snapshot(): { text: string; truncated: boolean } {
+    return { text: this.value, truncated: this.dropped }
+  }
 }
 
 class LocalSendOperation implements PtySendOperation {
-  private readonly output: PtyTextBuffer
+  private readonly output: BoundedTextBuffer
   private readonly promise: PromiseWithResolvers<PtySendResult>
   private finished = false
+  private cancellationRequested = false
+  private initialForegroundLeftWait: boolean
+  private initialForegroundPgid: number | undefined
 
   constructor(
     maxBytes: number,
     readonly startedAt: number,
     private readonly onCancel: () => void,
   ) {
-    this.output = new PtyTextBuffer(maxBytes)
+    this.output = new BoundedTextBuffer(maxBytes)
     this.promise = Promise.withResolvers<PtySendResult>()
+    this.initialForegroundLeftWait = true
   }
 
   get done(): Promise<PtySendResult> {
     return this.promise.promise
   }
 
+  get settled(): boolean {
+    return this.finished
+  }
+
+  get cancelRequested(): boolean {
+    return this.cancellationRequested
+  }
+
   append(text: string): void {
     if (!this.finished) this.output.append(text)
   }
@@ -66,50 +130,75 @@ class LocalSendOperation implements PtySendOperation {
     return this.output.consume()
   }
 
+  setInitialForeground(foreground: SubprocessTerminalForeground | undefined): void {
+    this.initialForegroundPgid = foreground?.processGroupId
+    this.initialForegroundLeftWait = foreground?.inputWaiting !== true
+  }
+
+  acceptsStdinWait(pgid: number, waiting: boolean): boolean {
+    // The same group may still expose the wait that existed before terminal.write.
+    // Observe every poll so a departure before the exact-settlement threshold
+    // still makes a later return to that wait post-write evidence.
+    if (pgid !== this.initialForegroundPgid) return waiting
+    if (!waiting) this.initialForegroundLeftWait = true
+    return waiting && this.initialForegroundLeftWait
+  }
+
   cancel(): boolean {
     if (this.finished) return false
+    this.cancellationRequested = true
     this.onCancel()
     return true
   }
 }
 
-/** Backend session wrapping one `node-pty` process and its captured process tree. */
+/** Backend session wrapping one provider-owned terminal process. */
 export class LocalPtySession implements PtyBackendSession {
   motd = ''
   readonly pid: number
-  private readonly sanitizer: PtyTerminalSanitizer
-  private readonly scrollback: PtyTextBuffer
-  private readonly exitPromise: PromiseWithResolvers<void> = Promise.withResolvers<void>()
-  private readonly dataDisposable: IDisposable
-  private readonly exitDisposable: IDisposable
+  private readonly decoder = new TextDecoder()
+  private readonly sanitizer: TerminalSanitizer
+  private readonly scrollback: BoundedTextBuffer
+  private readonly outputEnded = Promise.withResolvers<void>()
+  private readonly completion: Promise<void>
   private statusValue: PtySessionStatus = { kind: 'running' }
+  // TODO(pty-send-state-consolidation): Fold the per-send fields below
+  // (active/activeTimer/activeDeadlineTimer/activeAbort/interrupting/
+  // activeWrite/pollingReady/polling) into one send-lifecycle owner; the
+  // cancellation/readiness interplay now has enough pinned tests to carry
+  // that refactor safely.
   private active: LocalSendOperation | undefined
   private activeTimer: NodeJS.Timeout | undefined
+  private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
+  private interrupting: LocalSendOperation | undefined
+  private activeWrite: Promise<boolean> | undefined
+  private pollingReady: LocalSendOperation | undefined
+  private polling = false
   private promptSeen = false
   private promptTextSeen = false
+  private promptTail = ''
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
   private closing = false
   private closePromise: Promise<void> | undefined
+  private transportFailure: Error | undefined
 
   constructor(
-    private readonly terminal: IPty,
-    private readonly inspector: ProcessInspector,
+    private readonly terminal: SubprocessTerminalHandle,
     private readonly config: ResolvedConfig,
   ) {
     this.pid = terminal.pid
-    this.sanitizer = new PtyTerminalSanitizer(config.maxReadBytes)
-    this.scrollback = new PtyTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
-    this.dataDisposable = terminal.onData((data) => { this.onData(data) })
-    this.exitDisposable = terminal.onExit(({ exitCode, signal }) => {
-      const tail = this.sanitizer.flush()
-      this.appendOutput(tail)
-      this.statusValue = { kind: 'exited', exitCode, signal: ptySignalName(signal) }
-      this.settleActive('session_exit')
-      this.exitPromise.resolve()
-    })
+    this.sanitizer = new TerminalSanitizer(config.maxReadBytes)
+    this.scrollback = new BoundedTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
+    terminal.output.on('data', this.onTerminalData)
+    terminal.output.once('end', this.onTerminalEnd)
+    terminal.output.once('error', this.onTerminalError)
+    this.completion = terminal.done.then(
+      outcome => this.onExit(outcome),
+      (error: unknown) => { this.onTransportFailure(error) },
+    )
   }
 
   /**
@@ -136,7 +225,14 @@ export class LocalPtySession implements PtyBackendSession {
   startSend(request: PtySendRequest): PtySendOperation {
     if (this.closing) throw new Error('PTY session is closing')
     if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
-    if (this.active !== undefined) throw new Error('PTY session already has an active send')
+    if (this.active !== undefined) {
+      const draining = this.activeWrite !== undefined
+        ? ' or draining provider write'
+        : this.interrupting !== undefined
+          ? ' or draining foreground interrupt'
+          : ''
+      throw new PtyError(`PTY session already has an active send${draining}`, 'SEND_ACTIVE')
+    }
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
     const operation = new LocalSendOperation(
@@ -145,29 +241,79 @@ export class LocalPtySession implements PtyBackendSession {
       () => { this.interrupt(operation) },
     )
     this.active = operation
-    this.lastOutputAt = Date.now()
-    this.promptSeen = false
-    this.promptTextSeen = false
+    this.resetReadinessEvidence()
 
     if (request.signal !== undefined) {
       const onAbort = (): void => { operation.cancel() }
       request.signal.addEventListener('abort', onAbort, { once: true })
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
-
-    try {
-      if (request.text.length > 0) this.terminal.write(request.text)
-      if (request.submit) this.terminal.write('\r')
-    } catch (error: unknown) {
-      this.clearActive()
-      operation.fail(error)
-      return operation
-    }
-
-    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
+    this.activeDeadlineTimer = setTimeout(() => {
+      if (this.active === operation) {
+        this.settleActive('timeout', this.activeWrite !== undefined || this.interrupting === operation)
+      }
+    }, this.config.timeoutMs)
+    void this.beginSend(operation, request)
     return operation
   }
 
+  private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
+    let foreground: SubprocessTerminalForeground | undefined
+    try {
+      foreground = await this.terminal.inspectForeground()
+    } catch (error: unknown) {
+      // A pre-write inspection failure while cancellation owns the slot must not
+      // release it: interruptOnce's in-flight foreground signal could land on a
+      // successor's foreground group. The interrupt path's post-signal tail
+      // resumes polling, whose guarded catch propagates a persistent failure.
+      // A retained settled operation implies that same in-flight interrupt, so
+      // this guard admits only an unsettled active send.
+      if (this.active === operation && !this.closing && this.interrupting !== operation) {
+        this.failActive(error)
+      }
+      return
+    }
+    try {
+      if (this.active !== operation || this.closing || this.interrupting === operation) return
+      operation.setInitialForeground(foreground)
+      const input = `${request.text}${request.submit ? '\r' : ''}`
+      if (input.length > 0 && !operation.cancelRequested) {
+        this.resetReadinessEvidence()
+        const write = this.terminal.write(input)
+        this.activeWrite = write.then(() => true, () => false)
+        try {
+          await write
+        } finally {
+          this.activeWrite = undefined
+        }
+      }
+      // Cancellation owns post-write signalling and reservation release.
+      if (operation.cancelRequested) return
+      if (this.active === operation && operation.settled) {
+        this.clearActive()
+        return
+      }
+      // Closing can race the awaited provider write even though static analysis sees only local assignments.
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited provider writes can close the session.
+      if (this.active === operation && !this.closing) {
+        this.pollingReady = operation
+        this.schedulePoll(operation)
+      }
+    } catch (error: unknown) {
+      if (this.active === operation && !this.closing) {
+        if (operation.settled) this.clearActive()
+        else this.failActive(error)
+      }
+    }
+  }
+
+  private resetReadinessEvidence(): void {
+    this.lastOutputAt = Date.now()
+    this.promptSeen = false
+    this.promptTextSeen = false
+    this.promptTail = ''
+  }
+
   read(request: PtyReadRequest): PtyReadResult {
     const snapshot = this.scrollback.snapshot()
     const lines = snapshot.text.split('\n')
@@ -182,7 +328,7 @@ export class LocalPtySession implements PtyBackendSession {
     const end = totalLines - offset
     const start = Math.max(0, end - count)
     const requested = lines.slice(start, end).join('\n')
-    const bounded = ptyUtf8Tail(requested, this.config.maxReadBytes)
+    const bounded = utf8Tail(requested, this.config.maxReadBytes)
     const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split('\n').length
     return {
       text: bounded.text,
@@ -193,16 +339,10 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
-  signal(signal: PtySignal): Promise<PtySignalResult> {
-    return Promise.resolve().then(() => {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
-      if (signal === 'SIGKILL' && pgid === this.pid) {
-        throw new Error('refusing to SIGKILL the PTY shell; use terminal_close')
-      }
-      this.inspector.signalGroup(pgid, signal)
-      return { delivered: true, targetPgid: pgid }
-    })
+  async signal(signal: PtySignal): Promise<PtySignalResult> {
+    if (this.closing) throw new Error('PTY session is closing')
+    const targetPgid = await this.terminal.signalForeground(signal)
+    return { delivered: true, targetPgid }
   }
 
   status(): PtySessionStatus {
@@ -221,21 +361,56 @@ export class LocalPtySession implements PtyBackendSession {
     return closing
   }
 
+  private readonly onTerminalData = (chunk: Buffer | Uint8Array | string): void => {
+    const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
+    this.onData(this.decoder.decode(bytes, { stream: true }))
+  }
+
+  private readonly onTerminalEnd = (): void => {
+    this.onData(this.decoder.decode())
+    this.appendOutput(this.sanitizer.flush())
+    this.outputEnded.resolve()
+  }
+
+  private readonly onTerminalError = (error: Error): void => {
+    this.onTransportFailure(error)
+    this.outputEnded.resolve()
+  }
+
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
     if (sanitized.prompt) {
-      const foregroundPgid = this.inspector.foregroundPgid(this.pid)
-      if (this.shellPgid === undefined) this.shellPgid = foregroundPgid
+      // TODO(pty-delayed-signal-prompt): With a reproducer, define a marker-generation boundary
+      // before attributing a signal-delayed prompt to a later send.
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
       this.promptSeen = true
-      this.promptTextSeen = sanitized.promptText === true
+      this.promptTail = ''
       this.lastOutputAt = Date.now()
-    } else if (this.promptSeen && sanitized.promptText === true) {
-      this.promptTextSeen = true
     }
+    if (this.promptSeen && sanitized.promptTail !== undefined) {
+      const remaining = Math.max(0, CONTROLLED_PROMPT.length + 1 - this.promptTail.length)
+      this.promptTail += sanitized.promptTail.slice(0, remaining)
+      if (sanitized.promptTail.length > remaining) this.promptTail = `${CONTROLLED_PROMPT}\0`
+      this.promptTextSeen = this.promptTail === CONTROLLED_PROMPT
+    }
+  }
+
+  private async onExit(outcome: SubprocessOutcome): Promise<void> {
+    await this.outputEnded.promise
+    if (this.transportFailure !== undefined) return
+    this.statusValue = { kind: 'exited', exitCode: outcome.exitCode, signal: outcome.signal }
+    this.settleActive('session_exit')
+  }
+
+  private onTransportFailure(error: unknown): void {
+    const failure = error instanceof Error ? error : new Error(String(error))
+    this.transportFailure ??= failure
+    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
+    this.failActive(failure)
+    void this.terminal.terminate().catch(() => {})
   }
 
   private appendOutput(text: string): void {
@@ -245,60 +420,94 @@ export class LocalPtySession implements PtyBackendSession {
     this.active?.append(text)
   }
 
-  private pollReadiness(operation: LocalSendOperation): void {
-    if (this.active !== operation) return
-    if (this.statusValue.kind === 'exited') {
-      this.settleActive('session_exit')
-      return
-    }
-    if (this.promptSeen && this.promptTextSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (this.shellPgid !== undefined && pgid === this.shellPgid) {
-        this.settleActive('stdin_read')
-        return
-      }
-    }
-    const elapsed = Date.now() - operation.startedAt
-    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
-    if (startupHasOutput && elapsed >= this.config.exactProbeAfterMs) {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid !== undefined && this.inspector.isStdinWaiting(pgid)) {
-        this.settleActive('stdin_read')
-        return
-      }
-    }
-    // A prompt candidate can race bash's foreground handoff, but an interactive
-    // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
-    // on waiting for shell ownership instead of letting a child marker suppress
-    // readiness until the absolute timeout. When a prompt marker was seen, the
-    // configured grace holds the fallback past the silence bound so polls in
-    // that window can observe the foreground handoff and settle as stdin_read.
-    const idleFor = Date.now() - this.lastOutputAt
-    const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
-    if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
-      this.settleActive('inferred_idle')
-      return
-    }
-    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
+  private schedulePoll(operation: LocalSendOperation, delayMs = this.config.pollIntervalMs): void {
+    if (this.active !== operation || this.interrupting === operation || this.polling) return
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
+    this.activeTimer = setTimeout(() => {
+      this.activeTimer = undefined
+      void this.pollReadiness(operation)
+    }, delayMs)
   }
 
-  private settleActive(waitReason: PtyWaitReason): void {
+  private async pollReadiness(operation: LocalSendOperation): Promise<void> {
+    if (this.active !== operation || this.polling) return
+    this.polling = true
+    try {
+      if (this.statusValue.kind === 'exited') {
+        this.settleActive('session_exit')
+        return
+      }
+      const foreground = await this.terminal.inspectForeground()
+      if (this.active !== operation || this.closing || this.interrupting === operation) return
+      const idleFor = Date.now() - this.lastOutputAt
+      if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
+        this.shellPgid = foreground.processGroupId
+      }
+      if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs
+        && foreground?.processGroupId === this.shellPgid) {
+        this.settleActive('stdin_read')
+        return
+      }
+      const elapsed = Date.now() - operation.startedAt
+      const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
+      const acceptsStdinWait = startupHasOutput && foreground !== undefined
+        && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting)
+      if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
+        this.settleActive('stdin_read')
+        return
+      }
+      // A prompt candidate can race bash's foreground handoff, but an interactive
+      // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
+      // on waiting for shell ownership instead of letting a child marker suppress
+      // readiness until the absolute timeout.
+      const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
+      if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
+        this.settleActive('inferred_idle')
+      }
+    } catch (error: unknown) {
+      if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error)
+    } finally {
+      this.polling = false
+      const active = this.active
+      // Awaited provider inspection can clear or replace the active send despite static analysis.
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited inspection can replace the active send.
+      if (active !== undefined && this.pollingReady === active) this.schedulePoll(active)
+    }
+  }
+
+  private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
     const scrollbackTruncated = this.scrollback.snapshot().truncated
-    this.clearActive()
+    if (retainOwnership) {
+      this.stopPolling()
+      this.activeAbort?.()
+      this.activeAbort = undefined
+    } else {
+      this.clearActive()
+    }
     operation.settle(waitReason, this.statusValue, scrollbackTruncated)
   }
 
   private stopPolling(): void {
-    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
+    this.stopReadinessPolling()
+    if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
+    this.activeDeadlineTimer = undefined
+  }
+
+  private stopReadinessPolling(): void {
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = undefined
+    this.pollingReady = undefined
   }
 
   private clearActive(): void {
+    const operation = this.active
     this.stopPolling()
     this.activeAbort?.()
     this.activeAbort = undefined
+    if (this.interrupting === operation) this.interrupting = undefined
+    this.pollingReady = undefined
     this.active = undefined
   }
 
@@ -311,104 +520,46 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
+    this.interrupting = operation
+    this.stopReadinessPolling()
+    void this.interruptOnce(operation)
+  }
+
+  private async interruptOnce(operation: LocalSendOperation): Promise<void> {
     try {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
-      this.inspector.signalGroup(pgid, 'SIGINT')
+      const activeWrite = this.activeWrite
+      if (activeWrite !== undefined && !await activeWrite) return
+      await this.terminal.signalForeground('SIGINT')
     } catch (error: unknown) {
-      this.failActive(error)
+      if (this.active === operation && !this.closing) this.onTransportFailure(error)
+      return
+    } finally {
+      if (this.interrupting === operation) this.interrupting = undefined
     }
-  }
-
-  private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
-    return members.filter(member => this.inspector.isAlive(member))
-  }
-
-  private descendants(): ProcessIdentity[] {
-    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
-  }
-
-  private async waitForExit(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
-    const deadline = Date.now() + this.config.disposeGraceMs
-    let survivors = this.survivors(members)
-    while (survivors.length > 0 && Date.now() < deadline) {
-      await delay(Math.min(25, Math.max(1, deadline - Date.now())))
-      survivors = this.survivors(members)
-    }
-    return survivors
-  }
-
-  private signalMembers(members: ProcessIdentity[], signal: 'SIGTERM' | 'SIGKILL'): void {
-    for (const member of members) {
-      try {
-        this.inspector.signalProcess(member, signal)
-      } catch (_alreadyExitedDuringSignal) {
-        // Identity is rechecked by the inspector; a same-tick exit is success.
-      }
-    }
-  }
-
-  private unionMembers(...groups: ProcessIdentity[][]): ProcessIdentity[] {
-    const members: ProcessIdentity[] = []
-    const seen = new Set<string>()
-    for (const group of groups) {
-      for (const member of group) {
-        const key = JSON.stringify([member.pid, member.started])
-        if (seen.has(key)) continue
-        seen.add(key)
-        members.push(member)
-      }
-    }
-    return members
-  }
-
-  private async stopDescendants(): Promise<ProcessIdentity[]> {
-    const captured = this.descendants()
-    this.signalMembers(captured, 'SIGTERM')
-    const capturedSurvivors = await this.waitForExit(captured)
-    // A TERM-handling descendant may have forked while winding down. Rescan
-    // while the shell can still reap every member, then kill both the fresh
-    // tree and captured survivors that were reparented out of that tree.
-    const members = this.unionMembers(capturedSurvivors, this.descendants())
-    this.signalMembers(members, 'SIGKILL')
-    const survivors = await this.waitForExit(members)
-    return this.survivors(this.unionMembers(survivors, this.descendants()))
-  }
-
-  private async stopShell(): Promise<void> {
-    try {
-      this.terminal.kill('SIGTERM')
-    } catch (_topLevelAlreadyExitedDuringTerm) {
-      // The exit notification remains authoritative.
-    }
-    if (this.statusValue.kind === 'running') {
-      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (this.statusValue.kind === 'running') {
-      try {
-        this.terminal.kill('SIGKILL')
-      } catch (_topLevelAlreadyExitedDuringKill) {
-        // The exit notification remains authoritative.
-      }
-      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (this.statusValue.kind === 'running') {
-      throw new Error(`PTY cleanup failed; surviving pids: ${this.pid}`)
+    if (this.active === operation && operation.settled) {
+      this.clearActive()
+    } else if (this.active === operation && !this.closing) {
+      this.pollingReady = operation
+      this.schedulePoll(operation, 0)
     }
   }
 
   private async closeOnce(reason: string): Promise<void> {
-    this.dataDisposable.dispose()
     // Stop readiness polling but retain the active operation: teardown settles
     // it as session_exit below, so an in-flight send is never mis-settled as
     // stdin_read/inferred_idle/timeout during the grace period.
     this.stopPolling()
-    const survivors = await this.stopDescendants()
-    if (survivors.length > 0) {
-      throw new Error(`PTY cleanup failed (${reason}); surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
+    try {
+      await this.terminal.terminate()
+    } catch (error: unknown) {
+      throw new Error(`PTY cleanup failed (${reason})`, { cause: error })
     }
-    await this.stopShell()
+    // Quiescence is the active send's terminal outcome.
     this.settleActive('session_exit')
-    this.exitDisposable.dispose()
+    await this.completion
+    this.terminal.output.off('data', this.onTerminalData)
+    this.terminal.output.off('end', this.onTerminalEnd)
+    this.terminal.output.off('error', this.onTerminalError)
+    if (this.transportFailure !== undefined) throw this.transportFailure
   }
 }
diff --git a/packages/pty/pty-local/tests/sanitize.spec.ts b/packages/pty/pty-local/tests/sanitize.spec.ts
index 06ec076358..f6649b3c6f 100644
--- a/packages/pty/pty-local/tests/sanitize.spec.ts
+++ b/packages/pty/pty-local/tests/sanitize.spec.ts
@@ -1,17 +1,17 @@
 import { describe, expect, it } from 'vitest'
-import { normalizePtyTerminalText, PtyTerminalSanitizer } from '@deepseek-ai/dsh-pty'
+import { normalizeTerminalText, TerminalSanitizer } from '@deepseek-ai/dsh-pty-local/src/sanitize.ts'
 
-describe('PtyTerminalSanitizer', () => {
+describe('TerminalSanitizer', () => {
   it('removes split CSI and owned OSC prompt markers', () => {
-    const sanitizer = new PtyTerminalSanitizer(64)
+    const sanitizer = new TerminalSanitizer(64)
     expect(sanitizer.push('red\x1b[3')).toEqual({ text: 'red', prompt: false })
     expect(sanitizer.push('1m text\x1b[0m\r\n')).toEqual({ text: ' text\n', prompt: false })
     expect(sanitizer.push('\x1b]133;')).toEqual({ text: '', prompt: false })
-    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptText: true })
+    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptTail: 'dsh> ' })
   })
 
   it('drops unrelated OSC, short escapes, BEL, and incomplete trailing escape', () => {
-    const sanitizer = new PtyTerminalSanitizer(64)
+    const sanitizer = new TerminalSanitizer(64)
     expect(sanitizer.push('a\x1b]0;title\x1b\\b\x1b7c\x07')).toEqual({ text: 'abc', prompt: false })
     expect(sanitizer.push('tail\x1b')).toEqual({ text: 'tail', prompt: false })
     expect(sanitizer.flush()).toBe('')
@@ -22,11 +22,11 @@ describe('PtyTerminalSanitizer', () => {
   })
 
   it('normalizes CRLF and standalone carriage returns', () => {
-    expect(normalizePtyTerminalText('a\r\nb\rc\x07')).toBe('a\nb\nc')
+    expect(normalizeTerminalText('a\r\nb\rc\x07')).toBe('a\nb\nc')
   })
 
   it('carries a trailing carriage return across data chunks and flushes standalone CR', () => {
-    const sanitizer = new PtyTerminalSanitizer(64)
+    const sanitizer = new TerminalSanitizer(64)
     expect(sanitizer.push('a\r')).toEqual({ text: 'a', prompt: false })
     expect(sanitizer.push('\nb')).toEqual({ text: '\nb', prompt: false })
     expect(sanitizer.push('\r')).toEqual({ text: '', prompt: false })
@@ -34,41 +34,41 @@ describe('PtyTerminalSanitizer', () => {
   })
 
   it('reports printable prompt text that follows a marker in a later chunk', () => {
-    const sanitizer = new PtyTerminalSanitizer(64)
-    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true })
-    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptText: true })
+    const sanitizer = new TerminalSanitizer(64)
+    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true, promptTail: '' })
+    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptTail: 'dsh> ' })
   })
 
   it('bounds and discards unterminated control sequences through their terminators', () => {
-    const oscBel = new PtyTerminalSanitizer(8)
+    const oscBel = new TerminalSanitizer(8)
     expect(oscBel.push(`\x1b]0;${'x'.repeat(16)}`)).toEqual({ text: '', prompt: false })
     expect(oscBel.push('more\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscSt = new PtyTerminalSanitizer(8)
+    const oscSt = new TerminalSanitizer(8)
     oscSt.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscSt.push('more\x1b')).toEqual({ text: '', prompt: false })
     expect(oscSt.push('\\tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscDirectSt = new PtyTerminalSanitizer(8)
+    const oscDirectSt = new TerminalSanitizer(8)
     oscDirectSt.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscDirectSt.push('more\x1b\\tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscFalseSt = new PtyTerminalSanitizer(8)
+    const oscFalseSt = new TerminalSanitizer(8)
     oscFalseSt.push(`\x1b]0;${'x'.repeat(16)}`)
     oscFalseSt.push('\x1b')
     expect(oscFalseSt.push('more')).toEqual({ text: '', prompt: false })
     expect(oscFalseSt.push('\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const oscNonTerminatingEscape = new PtyTerminalSanitizer(8)
+    const oscNonTerminatingEscape = new TerminalSanitizer(8)
     oscNonTerminatingEscape.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(oscNonTerminatingEscape.push('more\x1bxmore\x07tail')).toEqual({ text: 'tail', prompt: false })
 
-    const csi = new PtyTerminalSanitizer(8)
+    const csi = new TerminalSanitizer(8)
     expect(csi.push(`\x1b[${'1'.repeat(16)}`)).toEqual({ text: '', prompt: false })
     expect(csi.push('123')).toEqual({ text: '', prompt: false })
     expect(csi.push('mtext')).toEqual({ text: 'text', prompt: false })
 
-    const flushed = new PtyTerminalSanitizer(8)
+    const flushed = new TerminalSanitizer(8)
     flushed.push(`\x1b]0;${'x'.repeat(16)}`)
     expect(flushed.flush()).toBe('')
     expect(flushed.push('text')).toEqual({ text: 'text', prompt: false })
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 4097420382..0ebb5bd4af 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: cdea3803e903b31e895658745bc6dbf5a3c04c71
-README.zh.md: 95b02b6491077750f23ff12ffd14c1aa174609be
+README.md: f2b19436da40feb14d067e2cfc706222625680b5
+README.zh.md: 938312448dd5c0a691ed07ddc9843cf2c4445637
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index cdea3803e9..f2b19436da 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -2,12 +2,11 @@
 
 English | [中文](README.zh.md)
 
-The shared home for spawning managed child-process trees: fully-specified spawn specs with Node-shaped per-stream stdio dispositions (raw pipes, inherit, bounded tail-keep collection with spill files), the one credential scrub every harness spawner uses, offset-based incremental reads, tree-scoped signalling with SIGTERM→grace→SIGKILL escalation, and the cooperative dispose ladder. Command defaulting, shell semantics, deadlines, protocol framing, and presentation stay with consumers — the [bash executors](../bash/README.md), the [LSP host](../lsp/README.md), and the [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+The shared process substrate for one execution world: executable lookup, fully-specified managed child-process trees with raw or collected stdio, and one deep terminal-process primitive that owns PTY allocation, foreground groups, and provider-observable session cleanup. Command defaulting, shell semantics, deadlines, protocol framing, readiness, and presentation stay with consumers — the [bash executors](../bash/README.md), [LSP host](../lsp/README.md), [PTY shell backend](../pty/README.md), and [ACP subagent backend](../subagent/README.md). See the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 | Package | ctx key | Role |
 |---|---|---|
-| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: abstract `SubprocessService.spawn(spec)`, the fully-explicit `SubprocessSpawnSpec` with per-stream stdio dispositions, `SubprocessHandle` (streams, offset-based readers, terminate/waitForExit/dispose), and the shared scrub + `DSH_*`/`CollectedOutput` vocabulary |
-| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, per-disposition stream wiring, tail-keep truncation with bounded private spill files, the `DSH_*` merge order, tree signalling with escalation, the dispose ladder, and terminate-and-join disposal |
-| [`e2b/subprocess-e2b`](../e2b/subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | — | Experimental E2B implementation: remote Linux process groups and spill state in the shared `ctx.e2b` sandbox, with asynchronous PID acquisition and SDK buffering limitations |
+| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
+| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index 95b02b6491..938312448d 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -1,13 +1,12 @@
-# subprocess/：进程管理能力家族
+# subprocess/：子进程能力家族
 
 [English](README.md) | 中文
 
-spawn 受管子进程树的共用归属位置：完全显式的 spawn spec，其 stdio 处置方式（disposition）为 Node 形状、按流划分（原始管道、inherit、附带 spill 文件的有界尾部保留收集）；harness 中所有 spawn 调用方共用的那一份凭据清除；基于偏移量的增量读取；以进程树为范围、带 SIGTERM→宽限期→SIGKILL 升级的信号发送；以及协作式 dispose（资源释放）阶梯。命令默认值补全、shell 语义、deadline、协议分帧与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[进程管理器 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+这里集中提供一个执行世界的共享进程基底：可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：抽象的 `SubprocessService.spawn(spec)`、完全显式且带按流划分 stdio 处置方式的 `SubprocessSpawnSpec`、`SubprocessHandle`（流、基于偏移量的读取器、terminate/waitForExit/dispose），以及共享的凭据清除 + `DSH_*`/`CollectedOutput` 词汇 |
-| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、按处置方式接线的流、附带有界私有 spill 文件的尾部保留截断、`DSH_*` 合并次序、带升级的进程树信号发送、dispose 阶梯，以及先终止再等待退出的 dispose |
-| [`e2b/subprocess-e2b`](../e2b/subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | 无 | 实验性 E2B 实现：远程 Linux 进程组和共享 `ctx.e2b` 沙箱中的 spill 状态，但 PID 异步获取，且受 SDK 缓冲限制 |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
 
-服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
+即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f682bc6847..d2e7d0ec1c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -346,6 +346,12 @@ importers:
       '@deepseek-ai/dsh-credentials-local':
         specifier: workspace:*
         version: link:../packages/credentials/credentials-local
+      '@deepseek-ai/dsh-e2b':
+        specifier: workspace:*
+        version: link:../packages/e2b/e2b
+      '@deepseek-ai/dsh-fs-e2b':
+        specifier: workspace:*
+        version: link:../packages/e2b/fs-e2b
       '@deepseek-ai/dsh-fs-local':
         specifier: workspace:*
         version: link:../packages/fs/fs-local
@@ -493,6 +499,9 @@ importers:
       '@deepseek-ai/dsh-subagent-spawn':
         specifier: workspace:*
         version: link:../packages/subagent/subagent-spawn
+      '@deepseek-ai/dsh-subprocess-e2b':
+        specifier: workspace:*
+        version: link:../packages/e2b/subprocess-e2b
       '@deepseek-ai/dsh-subprocess-local':
         specifier: workspace:*
         version: link:../packages/subprocess/subprocess-local
@@ -716,9 +725,6 @@ importers:
 
   packages/bash/bash:
     devDependencies:
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3094,6 +3100,9 @@ importers:
 
   packages/credentials/credentials:
     devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3132,6 +3141,59 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/e2b/e2b:
+    dependencies:
+      e2b:
+        specifier: 2.29.1
+        version: 2.29.1
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-loader-smoke':
+        specifier: workspace:^
+        version: link:../../support/loader-smoke
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/e2b/fs-e2b:
+    devDependencies:
+      '@deepseek-ai/dsh-e2b':
+        specifier: workspace:^
+        version: link:../e2b
+      '@deepseek-ai/dsh-fs':
+        specifier: workspace:^
+        version: link:../../fs/fs
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/e2b/subprocess-e2b:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-e2b':
+        specifier: workspace:^
+        version: link:../e2b
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-subprocess':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/examples/acp-demo:
     devDependencies:
       '@cordisjs/plugin-include':
@@ -7848,6 +7910,9 @@ packages:
     resolution: {integrity: sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==}
     hasBin: true
 
+  '@bufbuild/protobuf@2.13.0':
+    resolution: {integrity: sha512-acq7c49vxfm1ggJ95P70TX7ABDM0vxr1SYD3BB0o0jnBLB4OAqeHyKuN+cD3w80gXEDQ2zxHpR6CUeA+O/aU9g==}
+
   '@chevrotain/types@11.1.2':
     resolution: {integrity: sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==}
 
@@ -7859,6 +7924,17 @@ packages:
     resolution: {integrity: sha512-y7/yvZ2TPAnR9+jnc00klvNNLkJiXFFrQA/hlLCcxA9a2A4zQIOimyFQ9XfwYKiGD1fb5GY8vbKIIgO8d5Tb2A==}
     engines: {node: '>= 20.12.0'}
 
+  '@connectrpc/connect-web@2.0.0-rc.3':
+    resolution: {integrity: sha512-w88P8Lsn5CCsA7MFRl2e6oLY4J/5toiNtJns/YJrlyQaWOy3RO8pDgkz+iIkG98RPMhj2thuBvsd3Cn4DKKCkw==}
+    peerDependencies:
+      '@bufbuild/protobuf': ^2.2.0
+      '@connectrpc/connect': 2.0.0-rc.3
+
+  '@connectrpc/connect@2.0.0-rc.3':
+    resolution: {integrity: sha512-ARBt64yEyKbanyRETTjcjJuHr2YXorzQo0etyS5+P6oSeW8xEuzajA9g+zDnMcj1hlX2dQE93foIWQGfpru7gQ==}
+    peerDependencies:
+      '@bufbuild/protobuf': ^2.2.0
+
   '@csstools/color-helpers@6.1.0':
     resolution: {integrity: sha512-064IFJdjTfUqnjpCVpMOdbr8FLQBhinbZj6yRv2An2E41O/pLEXqfFRWqGq/SxlE5PEUYTlvWsG2r8MswAVvkg==}
     engines: {node: '>=20.19.0'}
@@ -8478,6 +8554,14 @@ packages:
     resolution: {integrity: sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==}
     engines: {node: '>=12'}
 
+  '@isaacs/cliui@9.0.0':
+    resolution: {integrity: sha512-AokJm4tuBHillT+FpMtxQ60n8ObyXBatq7jD2/JA9dxbDDokKQm8KMht5ibGzLVU9IJDIKK4TPKgMHEYMn3lMg==}
+    engines: {node: '>=18'}
+
+  '@isaacs/fs-minipass@4.0.1':
+    resolution: {integrity: sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==}
+    engines: {node: '>=18.0.0'}
+
   '@joplin/turndown-plugin-gfm@1.0.67':
     resolution: {integrity: sha512-FZfW5EZfidhzd1IaY1uxHnIZPTVOxAdleMZ4/1U6Nt5b7+Qj5JThDnaIomuJtetnUBzuRNbe9FWMuqD4B3dlWA==}
 
@@ -10263,6 +10347,10 @@ packages:
     resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
     engines: {node: '>=18'}
 
+  chalk@5.6.2:
+    resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
+    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
   character-entities-html4@2.1.0:
     resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
 
@@ -10280,6 +10368,10 @@ packages:
     resolution: {integrity: sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==}
     engines: {node: '>= 20.19.0'}
 
+  chownr@3.0.0:
+    resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
+    engines: {node: '>=18'}
+
   clsx@2.1.1:
     resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
     engines: {node: '>=6'}
@@ -10306,6 +10398,9 @@ packages:
     resolution: {integrity: sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==}
     engines: {node: '>= 12'}
 
+  compare-versions@6.1.1:
+    resolution: {integrity: sha512-4hm4VPpIecmlg59CHXnRDnqGplJFrbLG4aFEl5vl6cK1u76ws3LLvX7ikFnTDl5vo39sjWD6AaDPYodJp/NNHg==}
+
   content-disposition@1.1.0:
     resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==}
     engines: {node: '>=18'}
@@ -10571,6 +10666,9 @@ packages:
     resolution: {integrity: sha512-svtcdpS8CgJyqAjEQIXdb3OjhFVVYjzGAPO8WGCmRbrml64SPw/jJD4GoE98aR7r25A0XcgrK3F02yw9R/vhQw==}
     engines: {node: '>=0.3.1'}
 
+  dockerfile-ast@0.7.1:
+    resolution: {integrity: sha512-oX/A4I0EhSkGqrFv0YuvPkBUSYp1XiY8O8zAKc8Djglx8ocz+JfOr8gP0ryRMC2myqvDLagmnZaU9ot1vG2ijw==}
+
   dom-accessibility-api@0.5.16:
     resolution: {integrity: sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==}
 
@@ -10590,6 +10688,10 @@ packages:
     resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
     engines: {node: '>= 0.4'}
 
+  e2b@2.29.1:
+    resolution: {integrity: sha512-n4aGNwRKTj2oct7BrOWfR4T+xGO834vbsrzfSlWUNJrhz615Lp+ad9hc8KtRaaHULKr/W/14Z6v4c7fqk3y0pg==}
+    engines: {node: '>=20.18.1'}
+
   eastasianwidth@0.2.0:
     resolution: {integrity: sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==}
 
@@ -10920,6 +11022,12 @@ packages:
     deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
     hasBin: true
 
+  glob@11.1.0:
+    resolution: {integrity: sha512-vuNwKSaKiqm7g0THUBu2x7ckSs3XJLXE+2ssL7/MfTGPLLcrJQ/4Uq1CjPTtO5cCIiRxqvN6Twy1qOwhL0Xjcw==}
+    engines: {node: 20 || >=22}
+    deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+    hasBin: true
+
   globals@17.7.0:
     resolution: {integrity: sha512-Czmyns5dUsq4seFBR/Kdydhmo8y9kC79hiSkPn0YcGtNnYWnrgt0vjrSjx9tspoDGWm2CMarffRuLjM4xUz8xg==}
     engines: {node: '>=18'}
@@ -11103,6 +11211,10 @@ packages:
   jackspeak@3.4.3:
     resolution: {integrity: sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==}
 
+  jackspeak@4.2.3:
+    resolution: {integrity: sha512-ykkVRwrYvFm1nb2AJfKKYPr0emF6IiXDYUaFx4Zn9ZuIH7MrzEZ3sD5RlqGXNRpHtvUHJyOnCEFxOlNDtGo7wg==}
+    engines: {node: 20 || >=22}
+
   jiti@2.7.0:
     resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
     hasBin: true
@@ -11599,6 +11711,10 @@ packages:
   minisearch@7.2.0:
     resolution: {integrity: sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==}
 
+  minizlib@3.1.0:
+    resolution: {integrity: sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==}
+    engines: {node: '>= 18'}
+
   mitt@3.0.1:
     resolution: {integrity: sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==}
 
@@ -11742,6 +11858,12 @@ packages:
       zod:
         optional: true
 
+  openapi-fetch@0.14.1:
+    resolution: {integrity: sha512-l7RarRHxlEZYjMLd/PR0slfMVse2/vvIAGm75/F7J6MlQ8/b9uUQmUF2kCPrQhJqMXSxmYWObVgeYXbFYzZR+A==}
+
+  openapi-typescript-helpers@0.0.15:
+    resolution: {integrity: sha512-opyTPaunsklCBpTK8JGef6mfPhLSnyy5a0IN9vKtx3+4aExf+KxEqYwIy3hqkedXIB97u357uLMJsOnm3GVjsw==}
+
   optionator@0.9.4:
     resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
     engines: {node: '>= 0.8.0'}
@@ -11828,6 +11950,10 @@ packages:
     resolution: {integrity: sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==}
     engines: {node: '>=16 || 14 >=14.18'}
 
+  path-scurry@2.0.2:
+    resolution: {integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==}
+    engines: {node: 18 || 20 || >=22}
+
   path-to-regexp@8.4.2:
     resolution: {integrity: sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==}
 
@@ -11848,6 +11974,9 @@ packages:
     resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
     engines: {node: '>=16.20.0'}
 
+  platform@1.3.6:
+    resolution: {integrity: sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg==}
+
   playwright-core@1.61.1:
     resolution: {integrity: sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==}
     engines: {node: '>=18'}
@@ -12226,6 +12355,10 @@ packages:
   tabbable@6.5.0:
     resolution: {integrity: sha512-wieBHXygIm7OyQOu5hQlkk62/WyCFYGlWg7L6/ZCUZwx0o398Zkn4pVmMyfYhfMG8kGrj/Krt8eIk6UKC6VzwA==}
 
+  tar@7.5.22:
+    resolution: {integrity: sha512-MFO/QzvtAOmJbkhOaCTvbGcFN9L9b+JunIsDwaKljSOdcLMea3NJ1k9Usz/rjdfSXTq4dfzfeS7W4p4YOAAHeA==}
+    engines: {node: '>=18'}
+
   tinybench@2.9.0:
     resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
 
@@ -12629,6 +12762,9 @@ packages:
   vscode-languageserver-protocol@3.18.2:
     resolution: {integrity: sha512-XRyDbT0Pp3sSNti3JmxVEUMySWCSi1hhM+/KUlCy1hV1zmrqpM1OwO12EAki8blhmLuIMpaJrYbo0OzGVfK2Qg==}
 
+  vscode-languageserver-textdocument@1.0.12:
+    resolution: {integrity: sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==}
+
   vscode-languageserver-types@3.18.0:
     resolution: {integrity: sha512-8TsGPNMIMiiBdkORgRSvLjuiEIiAFtO+KssmYWxQ+uSVvlf7RjK8YKCOjPzZ+YA04jXEV7+7LvkSmHkhpNS99g==}
 
@@ -12723,6 +12859,10 @@ packages:
   yallist@3.1.1:
     resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
 
+  yallist@5.0.0:
+    resolution: {integrity: sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==}
+    engines: {node: '>=18'}
+
   yaml@2.9.0:
     resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
     engines: {node: '>= 14.6'}
@@ -13326,6 +13466,8 @@ snapshots:
     dependencies:
       css-tree: 3.2.1
 
+  '@bufbuild/protobuf@2.13.0': {}
+
   '@chevrotain/types@11.1.2': {}
 
   '@clack/core@1.4.3':
@@ -13340,6 +13482,15 @@ snapshots:
       fast-wrap-ansi: 0.2.2
       sisteransi: 1.0.5
 
+  '@connectrpc/connect-web@2.0.0-rc.3(@bufbuild/protobuf@2.13.0)(@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.13.0))':
+    dependencies:
+      '@bufbuild/protobuf': 2.13.0
+      '@connectrpc/connect': 2.0.0-rc.3(@bufbuild/protobuf@2.13.0)
+
+  '@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.13.0)':
+    dependencies:
+      '@bufbuild/protobuf': 2.13.0
+
   '@csstools/color-helpers@6.1.0': {}
 
   '@csstools/css-calc@3.2.1(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
@@ -13756,6 +13907,12 @@ snapshots:
       wrap-ansi: 8.1.0
       wrap-ansi-cjs: wrap-ansi@7.0.0
 
+  '@isaacs/cliui@9.0.0': {}
+
+  '@isaacs/fs-minipass@4.0.1':
+    dependencies:
+      minipass: 7.1.3
+
   '@joplin/turndown-plugin-gfm@1.0.67': {}
 
   '@jridgewell/gen-mapping@0.3.13':
@@ -15310,6 +15467,8 @@ snapshots:
 
   chai@6.2.2: {}
 
+  chalk@5.6.2: {}
+
   character-entities-html4@2.1.0: {}
 
   character-entities-legacy@3.0.0: {}
@@ -15324,6 +15483,8 @@ snapshots:
     dependencies:
       readdirp: 5.0.0
 
+  chownr@3.0.0: {}
+
   clsx@2.1.1: {}
 
   color-convert@2.0.1:
@@ -15340,6 +15501,8 @@ snapshots:
 
   commander@8.3.0: {}
 
+  compare-versions@6.1.1: {}
+
   content-disposition@1.1.0: {}
 
   content-type@1.0.5: {}
@@ -15611,6 +15774,11 @@ snapshots:
 
   diff@9.0.0: {}
 
+  dockerfile-ast@0.7.1:
+    dependencies:
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-languageserver-types: 3.18.0
+
   dom-accessibility-api@0.5.16: {}
 
   dompurify@3.4.11:
@@ -15627,6 +15795,20 @@ snapshots:
       es-errors: 1.3.0
       gopd: 1.2.0
 
+  e2b@2.29.1:
+    dependencies:
+      '@bufbuild/protobuf': 2.13.0
+      '@connectrpc/connect': 2.0.0-rc.3(@bufbuild/protobuf@2.13.0)
+      '@connectrpc/connect-web': 2.0.0-rc.3(@bufbuild/protobuf@2.13.0)(@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.13.0))
+      chalk: 5.6.2
+      compare-versions: 6.1.1
+      dockerfile-ast: 0.7.1
+      glob: 11.1.0
+      openapi-fetch: 0.14.1
+      platform: 1.3.6
+      tar: 7.5.22
+      undici: 7.28.0
+
   eastasianwidth@0.2.0: {}
 
   ecdsa-sig-formatter@1.0.11:
@@ -16089,6 +16271,15 @@ snapshots:
       package-json-from-dist: 1.0.1
       path-scurry: 1.11.1
 
+  glob@11.1.0:
+    dependencies:
+      foreground-child: 3.3.1
+      jackspeak: 4.2.3
+      minimatch: 10.2.5
+      minipass: 7.1.3
+      package-json-from-dist: 1.0.1
+      path-scurry: 2.0.2
+
   globals@17.7.0: {}
 
   globrex@0.1.2: {}
@@ -16258,6 +16449,10 @@ snapshots:
     optionalDependencies:
       '@pkgjs/parseargs': 0.11.0
 
+  jackspeak@4.2.3:
+    dependencies:
+      '@isaacs/cliui': 9.0.0
+
   jiti@2.7.0: {}
 
   jose@6.2.3: {}
@@ -16942,6 +17137,10 @@ snapshots:
 
   minisearch@7.2.0: {}
 
+  minizlib@3.1.0:
+    dependencies:
+      minipass: 7.1.3
+
   mitt@3.0.1: {}
 
   mri@1.2.0: {}
@@ -17062,6 +17261,12 @@ snapshots:
       ws: 8.21.0
       zod: 4.4.3
 
+  openapi-fetch@0.14.1:
+    dependencies:
+      openapi-typescript-helpers: 0.0.15
+
+  openapi-typescript-helpers@0.0.15: {}
+
   optionator@0.9.4:
     dependencies:
       deep-is: 0.1.4
@@ -17194,6 +17399,11 @@ snapshots:
       lru-cache: 10.4.3
       minipass: 7.1.3
 
+  path-scurry@2.0.2:
+    dependencies:
+      lru-cache: 11.5.1
+      minipass: 7.1.3
+
   path-to-regexp@8.4.2: {}
 
   pathe@2.0.3: {}
@@ -17206,6 +17416,8 @@ snapshots:
 
   pkce-challenge@5.0.1: {}
 
+  platform@1.3.6: {}
+
   playwright-core@1.61.1: {}
 
   playwright@1.61.1:
@@ -17659,6 +17871,14 @@ snapshots:
 
   tabbable@6.5.0: {}
 
+  tar@7.5.22:
+    dependencies:
+      '@isaacs/fs-minipass': 4.0.1
+      chownr: 3.0.0
+      minipass: 7.1.3
+      minizlib: 3.1.0
+      yallist: 5.0.0
+
   tinybench@2.9.0: {}
 
   tinyexec@1.2.4: {}
@@ -18092,6 +18312,8 @@ snapshots:
       vscode-jsonrpc: 9.0.1
       vscode-languageserver-types: 3.18.0
 
+  vscode-languageserver-textdocument@1.0.12: {}
+
   vscode-languageserver-types@3.18.0: {}
 
   vue@3.5.39(typescript@6.0.3):
@@ -18163,6 +18385,8 @@ snapshots:
 
   yallist@3.1.1: {}
 
+  yallist@5.0.0: {}
+
   yaml@2.9.0: {}
 
   yocto-queue@0.1.0: {}
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index e254696491..e6d6acbdf2 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -70,6 +70,7 @@ const GROUP_ORDER = [
   'bash',
   'pty',
   'sandbox',
+  'e2b',
   'fs',
   'skill',
   'compact',
@@ -321,12 +322,20 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'core',
     note: 'Folds revisioned objective state from the session log and keeps live continuation activation process-local.',
   },
+  {
+    key: 'e2b',
+    pkg: 'e2b',
+    title: 'E2B sandbox lifecycle owner',
+    mode: 'core',
+    consumers: ['fs-e2b', 'subprocess-e2b'],
+    note: 'Owns one shared E2B SDK handle, remote working directory, and final sandbox disposition so both fundamental E2B providers inhabit the same Linux runtime.',
+  },
   {
     key: 'subprocess',
     pkg: 'subprocess',
     title: 'Subprocess seam',
     mode: 'seam',
-    implementations: ['subprocess-local'],
+    implementations: ['subprocess-local', 'subprocess-e2b'],
     consumers: ['bash-local', 'bash-sandbox', 'pty-local', 'lsp-local', 'subagent-acp', 'subagent-codex', 'subagent-claude-code'],
     note: 'The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation.',
   },
@@ -405,7 +414,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'fs',
     title: 'Filesystem provider seam',
     mode: 'seam',
-    implementations: ['fs-local', 'fs-sandbox'],
+    implementations: ['fs-local', 'fs-sandbox', 'fs-e2b'],
     consumers: ['tool-fs'],
     companions: ['fs-policy'],
     note: 'tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate.',

From 55c0a44bd97113a3437b562df6acfb87a619582d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:11:31 +0800
Subject: [PATCH 392/516] fix(e2b): trim published files to the hardened
 allowlist

Master's publication hardening enforces the exact package files list;
the three E2B manifests still published src and d.ts maps.
---
 packages/e2b/e2b/package.json            | 4 +---
 packages/e2b/fs-e2b/package.json         | 4 +---
 packages/e2b/subprocess-e2b/package.json | 4 +---
 3 files changed, 3 insertions(+), 9 deletions(-)

diff --git a/packages/e2b/e2b/package.json b/packages/e2b/e2b/package.json
index 82fda6b303..a77e3d9464 100644
--- a/packages/e2b/e2b/package.json
+++ b/packages/e2b/e2b/package.json
@@ -21,9 +21,7 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
diff --git a/packages/e2b/fs-e2b/package.json b/packages/e2b/fs-e2b/package.json
index cc96cba6c9..02925ee7c4 100644
--- a/packages/e2b/fs-e2b/package.json
+++ b/packages/e2b/fs-e2b/package.json
@@ -21,9 +21,7 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
diff --git a/packages/e2b/subprocess-e2b/package.json b/packages/e2b/subprocess-e2b/package.json
index fa96e17293..abf3d5973c 100644
--- a/packages/e2b/subprocess-e2b/package.json
+++ b/packages/e2b/subprocess-e2b/package.json
@@ -21,9 +21,7 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {

From 72419bc33351b659874a7be32b3b74c2053e1815 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Fri, 7 Aug 2026 21:29:14 +0800
Subject: [PATCH 393/516] test(e2b): cover the environment tombstone removal

The serializer's undefined-tombstone branch (from the seam's
NodeJS.ProcessEnv migration) removes an ambient entry; the composition
env test now exercises it against the scrubbed ambient KEEP entry.
---
 packages/e2b/subprocess-e2b/tests/subprocess.spec.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index 747dc936c6..d40c69df89 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -388,6 +388,8 @@ describe('E2BSubprocessHandle', () => {
         '--split-string': 'literal-value',
         DEEPSEEK_API_KEY: 'explicit-secret',
         DSH_MODE: 'test',
+        // The seam's tombstone: an explicit undefined removes the ambient entry.
+        KEEP: undefined,
       },
     }), '/workspace/.dsh-e2b/processes/one')
     expect(handle.pid).toBe(-1)
@@ -433,7 +435,7 @@ describe('E2BSubprocessHandle', () => {
       '/workspace/.dsh-e2b/processes/one/stderr.log',
     ])
     expect(fake.writtenFileData.get('/workspace/.dsh-e2b/processes/one/environment')).toBe(
-      'PATH=/bin\0KEEP=safe\0UNICODE=你好\0HOME=/home/user\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
+      'PATH=/bin\0UNICODE=你好\0HOME=/home/user\0FOO-BAR=hyphen-value\0--split-string=literal-value\0DEEPSEEK_API_KEY=explicit-secret\0DSH_MODE=test\0',
     )
 
     let piped = ''

From e0a31475fc0767f1f081f86de237592ebd5e915d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 00:27:21 +0800
Subject: [PATCH 394/516] chore(rebase): re-record the packages-README pairing
 after the cascade

The parent's round-two replay restored master's pairing record while
this branch's e2b group row changes both sides; re-record the pair.
---
 packages/README.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 7e74d63f31..143e7704c2 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 1516c20ff55f366fe6af6b0be5495958708f29e3
-README.zh.md: 42f4d2b8d924b19fd3cde863dafb8c59d9c078cf
+README.md: 98fc87a6b26a42c58bb63cba96cd6af384f3ec71
+README.zh.md: 86a316dca77efd5e5eb59e3fca7d53890a34901d

From 0569437ff3219757001c3d7501d88f24172a7575 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 01:16:24 +0800
Subject: [PATCH 395/516] chore(rebase): regenerate third-party notices and the
 module graph

Master turned THIRD_PARTY_NOTICES.md into generator output (the branch's
hand-added e2b row carried a stale dotenv entry), and the cascade's
ours-side resolution flattened the module graph to the parent's content;
both regenerate from the current tree.
---
 THIRD_PARTY_NOTICES.md |  1 -
 docs/module-graph.md   | 15 +++++++++++++++
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 9060950bea..48f04c9799 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -57,7 +57,6 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`clsx`](https://github.com/lukeed/clsx) | MIT |
 | [`commander`](https://github.com/tj/commander.js) | MIT |
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
-| [`dotenv`](https://github.com/motdotla/dotenv) | BSD-2-Clause |
 | [`e2b`](https://github.com/e2b-dev/e2b) | MIT |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
 | [`handlebars`](https://github.com/handlebars-lang/handlebars.js) | MIT |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 38a85a508a..91d584466b 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -204,6 +204,11 @@ flowchart TD
     pkg_credentials["credentials"]
     pkg_credentials_local["credentials-local"]
   end
+  subgraph group_e2b["packages/e2b"]
+    pkg_e2b["e2b"]
+    pkg_fs_e2b["fs-e2b"]
+    pkg_subprocess_e2b["subprocess-e2b"]
+  end
   subgraph group_examples["packages/examples"]
     pkg_acp_demo["acp-demo"]
     pkg_agent_spine_demo["agent-spine-demo"]
@@ -309,6 +314,7 @@ flowchart TD
   pkg_client_web --> pkg_invariants
   pkg_client_web_react --> pkg_invariants
   pkg_code_runtime --> pkg_invariants
+  pkg_e2b --> pkg_invariants
   pkg_jsonrpc_demo --> pkg_invariants
   pkg_host_apiproxy --> pkg_invariants
   pkg_host_directory_picker --> pkg_invariants
@@ -331,6 +337,9 @@ flowchart TD
   pkg_client_runtime --> pkg_typert_registry
   pkg_credentials --> pkg_brand
   pkg_credentials --> pkg_invariants
+  pkg_subprocess_e2b --> pkg_e2b
+  pkg_subprocess_e2b --> pkg_invariants
+  pkg_subprocess_e2b --> pkg_subprocess
   pkg_frontend_static --> pkg_host_webserver
   pkg_frontend_static --> pkg_invariants
   pkg_helper --> pkg_brand
@@ -591,6 +600,9 @@ flowchart TD
   pkg_tmux_context --> pkg_bash
   pkg_tmux_context --> pkg_invariants
   pkg_tmux_context --> pkg_session
+  pkg_fs_e2b --> pkg_e2b
+  pkg_fs_e2b --> pkg_fs
+  pkg_fs_e2b --> pkg_invariants
   pkg_host_directory_picker_browse --> pkg_client_locale
   pkg_host_directory_picker_browse --> pkg_client_runtime
   pkg_host_directory_picker_browse --> pkg_client_ui_primitives
@@ -1181,6 +1193,7 @@ flowchart TD
 | [`client-web`](../packages/client/web) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-web-react`](../packages/client/web-react) | `client` | [`invariants`](../packages/support/invariants) |
 | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | [`invariants`](../packages/support/invariants) |
+| [`e2b`](../packages/e2b/e2b) | `e2b` | [`invariants`](../packages/support/invariants) |
 | [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | [`invariants`](../packages/support/invariants) |
 | [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker`](../packages/host/directory-picker) | `host` | [`invariants`](../packages/support/invariants) |
@@ -1195,6 +1208,7 @@ flowchart TD
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-runtime`](../packages/client/runtime) | `client` | [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
 | [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
@@ -1264,6 +1278,7 @@ flowchart TD
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`fs-e2b`](../packages/e2b/fs-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |

From 10fc9405c772bbb75868d62d04487f3f529dabb4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:29:10 +0800
Subject: [PATCH 396/516] docs(e2b): re-home the overlay section on master's
 README

Master rewrote the headless README around the profile CLI and removed
cli-demo; the replay had resurrected the old body. The branch's claim is
the E2B overlay section alone, now inserted into master's text with the
credential-gated live composition e2e as the runnable instruction (the
config-file demo runner no longer exists).
---
 examples/headless-agent/README.i18n.yaml |  4 ++--
 examples/headless-agent/README.md        | 22 +++++++++-------------
 examples/headless-agent/README.zh.md     | 22 +++++++++-------------
 3 files changed, 20 insertions(+), 28 deletions(-)

diff --git a/examples/headless-agent/README.i18n.yaml b/examples/headless-agent/README.i18n.yaml
index 56c02d3e0a..4a71194e5f 100644
--- a/examples/headless-agent/README.i18n.yaml
+++ b/examples/headless-agent/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 examples/headless-agent/README.md
-README.md: 16c45d304eb0f06a2b062518b053db683cd402c0
-README.zh.md: 72d2813d174e74a3bf93c363b268499a44f1cd4f
+README.md: 6e80e56dec70c2be341ae5dfbad70e13a5109715
+README.zh.md: ea8c41b9ae75f0cee3edd78e59408f37c19182d3
diff --git a/examples/headless-agent/README.md b/examples/headless-agent/README.md
index 16c45d304e..6e80e56dec 100644
--- a/examples/headless-agent/README.md
+++ b/examples/headless-agent/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Headless one-shot agent wiring: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + JSONL persistence, with [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) as the app front door.
+This directory owns the replay and real-model test composition for a headless coding agent: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows and fresh-agent Ralph iteration + `todo_write` + JSONL persistence. It explicitly mounts the shared agent spine, one root agent, persistence, and checkpoint policy; it is not a second product front door.
 
 ## Run it
 
@@ -10,27 +10,23 @@ Headless one-shot agent wiring: DeepSeek V4 + local bash and filesystem tools +
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run demo:headless "fix the failing test in this workspace"
-pnpm run demo:headless --output-format json -- "summarize the implementation"
-pnpm run demo:headless --output-format stream-json -- "run the focused tests"
+pnpm run dsh run "fix the failing test in this workspace"
 ```
 
-Exactly one nonblank positional task is required; quote tasks containing spaces. There is no `-p` flag. `text` prints the last text-bearing assistant message, `json` prints one DSH-native result record, and `stream-json` emits the top-level session's canonical task-turn events before that record. Child sessions surface only through parent tool events and results.
+The product command is [`dsh run`](../../apps/cli/README.md): it accepts one nonblank task, creates and persists a fresh session, prints the final assistant text, and exits. The root `demo:headless` script is only an alias of that command.
 
-Each invocation creates and persists a fresh session, runs all model and tool steps in one turn, flushes, disposes, and exits. This is non-interactive automation: there is no prompt, approval, resume, second turn, or stdin context. The configured tools can mutate the launch workspace, run commands, spawn child agents, and consume provider tokens.
+Snapshot suites run this directory's configuration through [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts), an unexported test-only process that emits canonical session events as JSONL before its result record. That stream is test infrastructure, not a supported CLI output format. Child sessions surface only through parent tool events and results.
 
 ## E2B POC overlay
 
-[`e2b.cordis.yml`](e2b.cordis.yml) replaces the local filesystem and subprocess providers with one shared E2B sandbox while retaining `dsh-bash-local` and the same model-facing tools. Put `E2B_API_KEY` beside `DEEPSEEK_API_KEY` in the gitignored root `.env`, then run:
+[`e2b.cordis.yml`](e2b.cordis.yml) replaces the local filesystem and subprocess providers with one shared E2B sandbox while retaining `dsh-bash-local` and the same model-facing tools. Put `E2B_API_KEY` beside `DEEPSEEK_API_KEY` in the gitignored root `.env`, then run the credential-gated live composition, which drives FS, Bash, PTY, and LSP in one sandbox and proves final deletion:
 
 ```sh
-pnpm run demo:e2b "create hello.txt, read it back, and run pwd"
+pnpm exec vitest run --config vitest.e2e.config.ts packages/e2b/e2b/tests/composition.e2e.ts
 ```
 
-The overlay creates the same absolute cwd inside the sandbox, but it does not upload or mount the host workspace. File and Bash mutations exist only in E2B; Cordis, model calls, agent/session state, session logs, skills, and SDK buffers remain on the host. The demo kills its sandbox on timeout and disposal. It is a provider-composition POC, not a whole-harness migration or a workspace-sync feature.
+The overlay creates the same absolute cwd inside the sandbox, but it does not upload or mount the host workspace. File and Bash mutations exist only in E2B; Cordis, model calls, agent/session state, session logs, skills, and SDK buffers remain on the host. The composition kills its sandbox on timeout and disposal. It is a provider-composition POC, not a whole-harness migration or a workspace-sync feature.
 
-## Advanced and snapshot wiring
+## Advanced configuration
 
-[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the shipped leaf. [`advanced.cordis.snapshot.yml`](advanced.cordis.snapshot.yml) replaces only the live LLM with replay. The tests under [`tests/`](tests/) own the keyless real-Loader smoke, key-gated world-verified smoke, and the `stream-json` replay snapshot with its parent and child session fixtures.
-
-The package-level [CLI contract](../../packages/examples/cli-demo/README.md) documents output records, exit status, cancellation, persistence, and model/token effects.
+[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the test composition.
diff --git a/examples/headless-agent/README.zh.md b/examples/headless-agent/README.zh.md
index 72d2813d17..ea8c41b9ae 100644
--- a/examples/headless-agent/README.zh.md
+++ b/examples/headless-agent/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-无头单次 agent（智能体）接线：DeepSeek V4 + 本地 bash 与文件系统工具 + subagent 委托 + 工作流与新 agent Ralph 迭代 + `todo_write` + JSONL 持久化，并以 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) 作为应用入口。
+本目录负责 headless coding agent（智能体）的回放和真实模型测试组装：DeepSeek V4 + 本地 bash 与文件系统工具 + subagent 委托 + 工作流与全新 agent Ralph 迭代 + `todo_write` + JSONL 持久化。本目录显式挂载共享 agent 主干、一个根 agent、持久化和检查点策略；它不是第二个产品入口。
 
 ## 运行
 
@@ -10,27 +10,23 @@
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run demo:headless "fix the failing test in this workspace"
-pnpm run demo:headless --output-format json -- "summarize the implementation"
-pnpm run demo:headless --output-format stream-json -- "run the focused tests"
+pnpm run dsh run "fix the failing test in this workspace"
 ```
 
-必须提供且只能提供一个非空位置任务；含空格的任务需要加引号。没有 `-p` 标志。`text` 打印最后一条包含文本的 assistant 消息，`json` 打印一条 DSH 原生结果记录，`stream-json` 则在该记录之前发出顶层会话的规范任务轮次事件。子会话只通过父工具事件和结果对外显示。
+产品命令是 [`dsh run`](../../apps/cli/README.md)：它接受一项非空任务，创建并持久化新会话，打印最终 assistant 文本，然后退出。根目录的 `demo:headless` 脚本只是该命令的别名。
 
-每次调用都会创建并持久化新会话，在一个轮次中运行所有模型和工具步骤，然后刷新、释放并退出。这是非交互式自动化：没有提示符、批准、恢复、第二轮次或 stdin 上下文。已配置工具可以修改启动 workspace、运行命令、spawn 子 agent，并消耗提供方 token。
+快照套件通过 [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts) 运行本目录的配置。这个未导出且仅供测试使用的进程会在结果记录之前，以 JSONL 发出规范会话事件。该事件流属于测试基础设施，不是受支持的 CLI（命令行界面）输出格式。子会话只通过父会话的工具事件和结果对外显示。
 
 ## E2B POC overlay
 
-[`e2b.cordis.yml`](e2b.cordis.yml) 使用一个共享 E2B 沙箱替换本地文件系统与进程管理提供方，同时保留 `dsh-bash-local` 和相同的面向模型工具。请在 git 忽略的根目录 `.env` 中，将 `E2B_API_KEY` 与 `DEEPSEEK_API_KEY` 放在一起，然后运行：
+[`e2b.cordis.yml`](e2b.cordis.yml) 使用一个共享 E2B 沙箱替换本地文件系统与进程管理提供方，同时保留 `dsh-bash-local` 和相同的面向模型工具。请在 git 忽略的根目录 `.env` 中，将 `E2B_API_KEY` 与 `DEEPSEEK_API_KEY` 放在一起，然后运行凭据门控的实机组合测试；它在同一个沙箱中驱动 FS、Bash、PTY 和 LSP，并证明沙箱最终被删除：
 
 ```sh
-pnpm run demo:e2b "create hello.txt, read it back, and run pwd"
+pnpm exec vitest run --config vitest.e2e.config.ts packages/e2b/e2b/tests/composition.e2e.ts
 ```
 
-该 overlay 会在沙箱中创建拼写相同的绝对 cwd，但不会上传或挂载宿主工作区。文件与 Bash 变更只存在于 E2B；Cordis、模型调用、agent／会话状态、会话日志、skill（技能）和 SDK 缓冲仍在宿主上。演示会在超时和资源释放时终止其沙箱。它是提供方组合 POC，而不是完整 harness 迁移或工作区同步功能。
+该 overlay 会在沙箱中创建拼写相同的绝对 cwd，但不会上传或挂载宿主工作区。文件与 Bash 变更只存在于 E2B；Cordis、模型调用、agent／会话状态、会话日志、skill（技能）和 SDK 缓冲仍在宿主上。该组合会在超时和资源释放时终止其沙箱。它是提供方组合 POC，而不是完整 harness 迁移或工作区同步功能。
 
-## 高级与快照接线
+## 高级配置
 
-[`advanced.cordis.yml`](advanced.cordis.yml) 在已交付叶节点上添加 Code Mode 和 Cordis 工具。[`advanced.cordis.snapshot.yml`](advanced.cordis.snapshot.yml) 只将实时 LLM（大语言模型）替换为回放。[`tests/`](tests/) 下的测试拥有无密钥真实 Loader 冒烟测试、密钥门控的外部状态验证冒烟测试，以及带父子会话 fixture（测试前置数据）的 `stream-json` 回放快照。
-
-包级 [CLI 契约](../../packages/examples/cli-demo/README.md)记录输出记录、退出状态、取消、持久化以及模型／token 影响。
+[`advanced.cordis.yml`](advanced.cordis.yml) 在测试组装中添加 Code Mode 和 Cordis 工具。

From 450ec99325ebef5d21fdcae1a0ef62b98027dd68 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 22:37:38 +0800
Subject: [PATCH 397/516] fix(e2b): address the v7 review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- restore the parent's AGENTS.md body around this branch's e2b row (the
  replay had resurrected the pre-profile-CLI layout, deleting the api/,
  bundle/, settings/, and credentials/ groups); the fs/lsp row
  condensations stay for the word budget
- aggregate the composite rollback failure, not the original error, when
  private state cleanup also fails — a surviving remote group is no
  longer hidden by a later cleanup error (triple-failure regression)
- own the state directory before the makeDir RPC, matching the terminal
  transaction, so a cancellation racing a committed creation still
  enters cleanup
- drop the hidden pollMs parameter defaults; the schemastery default is
  the one home, and tests pass the cadence explicitly
- restore spawn/spawnTerminal graceMs validation to the seam's
  documented bound (the earlier removal cited subprocess-local as not
  validating; it does), with rejection regressions
---
 AGENTS.md                                     |  19 +-
 docs/config-catalog.md                        |   2 +-
 docs/module-graph.md                          |   3 +-
 packages/e2b/subprocess-e2b/package.json      |   2 +
 packages/e2b/subprocess-e2b/src/index.ts      |  15 ++
 packages/e2b/subprocess-e2b/src/process.ts    |   8 +-
 packages/e2b/subprocess-e2b/src/terminal.ts   |   2 +-
 .../subprocess-e2b/tests/subprocess.spec.ts   | 190 +++++++++++-------
 .../e2b/subprocess-e2b/tests/terminal.spec.ts |  96 +++++----
 packages/e2b/subprocess-e2b/tsconfig.json     |  15 +-
 pnpm-lock.yaml                                |   3 +
 11 files changed, 218 insertions(+), 137 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 87f545ee86..61812e586c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,10 +12,11 @@ DeepSeek Harness SDK is a plugin-based agent harness on vendored Cordis: **every
 vendor/      Vendored Cordis source — manifest + sync procedure in vendor/README.md
 packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
+  api/         Remote BFF assembly and TypeRT RPC gateway
   typert/      type graph generator, loader, and runtime registry
   llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
   e2b/         E2B POC: sandbox + FS/subprocess adapters
-  bash/        bash executor seam + local impl + model-facing bash tools
+  bash/        bash executor seam + local/pwsh impls + model-facing shell tools
   subprocess/  subprocess seam + local process-tree impl
   pty/         persistent PTY seam/backend/tools
   fs/          filesystem seam/backends/policy/tools
@@ -25,6 +26,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   compact/     compaction seam + basic backend
   context/     request-context plugins
   subagent/    subagent seam + spawn/fork/ACP backends + delegation tool
+  bundle/      profile plugin bundles: installable patch layers for dsh --profile
   workflow/    workflow seam + worker-thread engine + workflow tool
   todo/        todo_write tool
   plan/        plan mode as logged per-agent collaboration state
@@ -32,9 +34,11 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   cordis/      self-referential toolset: the agent inspects/mounts plugins in its own runtime
   hooks/       Claude Code/Codex hook bridges + shared wire-protocol library
   session-persistence/  persistence seam + JSONL/SQLite backends
+  settings/    user-settings seam + file-backed provider
+  credentials/ credential-reference seam + env-over-.env provider
   acp/         automation-only Agent Client Protocol server
-  ui/          TUI/JSON-RPC bridges; boot, approval, interaction plugins
-  examples/    demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load
+  ui/          JSON-RPC bridge; boot, approval, interaction plugins
+  examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load
   support/     dev/test infrastructure
   util/        zero-dependency utilities
 python/      Python SDK and bundled runtime (see python/README.md)
@@ -56,7 +60,7 @@ pnpm run clean           # remove build outputs and safe residue from deleted pa
 pnpm run test           # vitest unit tests
 pnpm run test:coverage  # CI coverage gate: per-file 100% on packages/*/*/src
 pnpm run test:e2e       # real-API tests; self-skip without DEEPSEEK_API_KEY
-pnpm run test:snapshot  # keyless ACP/headless/TUI replay vs expected outputs; filter: -t <name>
+pnpm run test:snapshot  # keyless ACP/headless replay vs expected outputs; filter: -t <name>
 pnpm run test:snapshot:record  # re-record expected outputs (needs key)
 pnpm run typecheck
 pnpm run lint
@@ -67,7 +71,6 @@ pnpm run hygiene        # knip + publint + workspace constraints + NodeNext cons
 pnpm run doc-sync       # all documentation gates; leaf list in scripts/run-gates.ts
 pnpm run website:build  # VitePress build (doubles as dead-link check)
 pnpm run demo:headless "task" # one-shot agent (needs DEEPSEEK_API_KEY)
-pnpm run demo:tui       # full-screen TUI coding agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:cordis    # the agent modifies its own runtime (needs key)
 pnpm run demo:acp       # ACP automation server (needs DEEPSEEK_API_KEY)
 ```
@@ -78,7 +81,7 @@ When required `gh`, `pnpm`, build, test, or generator commands fail because the
 
 ### Run relevant checks locally
 
-Agents MUST run relevant tests and checks before pushing; select them with [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md) and report only commands run.
+Run checks before pushes via [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md); report only commands run. After `gh stack sync`, validate immediately; do not merge before checks pass.
 
 - Match evidence to the surface: focused tests for behavior, snapshots for model or user output, `doc-sync` for docs, build/hygiene and built smokes for published paths, and real-API e2e for provider behavior.
 - Never default to the full suite or repeat a passing check for commit or push. CI owns exhaustive coverage and the platform matrix; rehearse all locally only by explicit request, for CI diagnosis, or for an irreducibly repository-wide change.
@@ -91,7 +94,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 ## Conventions
 
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
-- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only shapes) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). TUI/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
+- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only shapes) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
 - **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. If a package has no plausible relationship, an explained empty companion is correct ([package contract](packages/AGENTS.md)).
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns.
@@ -115,7 +118,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
-- **Use incremental merge commits.** Split independent changes. Pushed history may be rewritten before review; afterward prefer new commits. Fix the introducing PR before merging down-stack. If the base advances mid-merge, finish the checkpoint, push when authorized, then merge the newer tip separately ([rationale](.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)).
+- **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
 - **Label PRs:** one kind (`feature`/`bug-fix`/`doc`/`testing`/`cleanup`), each matching area; the [taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md) is extensible.
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
 - Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 58b319d662..c74358fd39 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1841,7 +1841,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/e2b/subprocess-e2b/src/index.ts:24`](../packages/e2b/subprocess-e2b/src/index.ts)
+Source: [`packages/e2b/subprocess-e2b/src/index.ts:25`](../packages/e2b/subprocess-e2b/src/index.ts)
 
 ## `@deepseek-ai/dsh-system-prompt`
 
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 91d584466b..2e71473379 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -340,6 +340,7 @@ flowchart TD
   pkg_subprocess_e2b --> pkg_e2b
   pkg_subprocess_e2b --> pkg_invariants
   pkg_subprocess_e2b --> pkg_subprocess
+  pkg_subprocess_e2b --> pkg_timeout
   pkg_frontend_static --> pkg_host_webserver
   pkg_frontend_static --> pkg_invariants
   pkg_helper --> pkg_brand
@@ -1208,7 +1209,7 @@ flowchart TD
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-runtime`](../packages/client/runtime) | `client` | [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
-| [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
+| [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
 | [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
diff --git a/packages/e2b/subprocess-e2b/package.json b/packages/e2b/subprocess-e2b/package.json
index abf3d5973c..007b88f1c9 100644
--- a/packages/e2b/subprocess-e2b/package.json
+++ b/packages/e2b/subprocess-e2b/package.json
@@ -28,6 +28,7 @@
     "@deepseek-ai/dsh-e2b": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
@@ -37,6 +38,7 @@
     "@deepseek-ai/dsh-e2b": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index 38b1d32465..c6d2dbd4eb 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -9,6 +9,7 @@ import { posix } from 'node:path'
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type {
   SubprocessHandle,
   SubprocessSpawnSpec,
@@ -35,6 +36,18 @@ interface TerminalSetup {
   controller: AbortController
 }
 
+/**
+ * Enforce the seam's documented grace bound (positive, finite, one Node timer),
+ * matching subprocess-local's spawn-time check; an unbounded grace would make
+ * the remote force-escalation deadline unreachable.
+ * @param graceMs - The spec's cleanup grace in milliseconds.
+ */
+function requireRepresentableGrace(graceMs: number): void {
+  if (!Number.isFinite(graceMs) || graceMs <= 0 || graceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
+}
+
 /** E2B command manager registered as `ctx.subprocess`. */
 export class E2BSubprocessService extends SubprocessService {
   static inject = ['e2b']
@@ -130,6 +143,7 @@ export class E2BSubprocessService extends SubprocessService {
     if (program === undefined || program.length === 0) {
       throw new Error('invalid argv: expected a non-empty program name at argv[0]')
     }
+    requireRepresentableGrace(spec.graceMs)
     if (spec.signal?.aborted === true) {
       throw new Error(`aborted before spawn: ${String(spec.signal.reason)}`)
     }
@@ -153,6 +167,7 @@ export class E2BSubprocessService extends SubprocessService {
     if (program === undefined || program.length === 0) {
       throw new Error('subprocess-e2b: terminal argv must contain a program')
     }
+    requireRepresentableGrace(spec.graceMs)
     spec.signal?.throwIfAborted()
     const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'terminals', randomUUID())
     const done = Promise.withResolvers<void>()
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index feb21a70bc..c80a2f5bd9 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -194,7 +194,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     private readonly runtime: E2BSandboxService,
     private readonly spec: SubprocessSpawnSpec,
     readonly stateDir: string,
-    private readonly pollMs = 20,
+    private readonly pollMs: number,
   ) {
     this.paths = {
       pid: posix.join(stateDir, 'pid'),
@@ -378,7 +378,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
           await this.removeFailedState(sandbox)
         } catch (cleanupError: unknown) {
           failure = new AggregateError(
-            [error, cleanupError],
+            [failure, cleanupError],
             'subprocess-e2b: command failed and private state cleanup failed',
           )
         }
@@ -398,8 +398,10 @@ export class E2BSubprocessHandle implements SubprocessHandle {
     const signal = this.terminationController.signal
     const ambient = await readRemoteEnvironment(sandbox, signal)
     this.controlEnvs = bootstrapEnvironment(ambient)
-    await sandbox.files.makeDir(this.stateDir, { signal })
+    // Own the directory before the request: a cancellation racing a committed
+    // creation must still enter cleanup (removal tolerates an absent path).
     this.stateDirectoryCreated = true
+    await sandbox.files.makeDir(this.stateDir, { signal })
     await sandbox.commands.run(
       `chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`,
       commandOpts(this.controlEnvs, signal),
diff --git a/packages/e2b/subprocess-e2b/src/terminal.ts b/packages/e2b/subprocess-e2b/src/terminal.ts
index fd10ecdd8e..c8f3bb57b7 100644
--- a/packages/e2b/subprocess-e2b/src/terminal.ts
+++ b/packages/e2b/subprocess-e2b/src/terminal.ts
@@ -459,7 +459,7 @@ export async function spawnE2BTerminal(
   runtime: E2BSandboxService,
   spec: SubprocessTerminalSpawnSpec,
   stateDir: string,
-  pollMs = 20,
+  pollMs: number,
 ): Promise<E2BTerminalHandle> {
   const sandbox = await runtime.getSandbox()
   spec.signal?.throwIfAborted()
diff --git a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
index d40c69df89..153b144ccd 100644
--- a/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/subprocess.spec.ts
@@ -324,6 +324,16 @@ async function flush(): Promise<void> {
   await new Promise(resolve => setTimeout(resolve, 0))
 }
 
+/** Construct the handle under test with the config default the service would pass. */
+function testHandle(
+  runtime: ConstructorParameters<typeof E2BSubprocessHandle>[0],
+  spec: ConstructorParameters<typeof E2BSubprocessHandle>[1],
+  stateDir: string,
+  pollMs = 20,
+): E2BSubprocessHandle {
+  return new E2BSubprocessHandle(runtime, spec, stateDir, pollMs)
+}
+
 describe('E2BOutputReader', () => {
   it('decodes base64 across arbitrary callback boundaries and rejects malformed framing', () => {
     const decoder = new E2BBase64Decoder()
@@ -379,7 +389,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     fake.processGroupId = '4343\n'
     fake.deferStart()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       argv: ['tool', 'argument with spaces'],
       stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 8, spill: { maxBytes: 32 } } },
       env: {
@@ -450,10 +460,23 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
   })
 
+  it('rejects an unrepresentable graceMs before any remote work', () => {
+    const ctx = new Context()
+    const service = Object.create(E2BSubprocessService.prototype) as E2BSubprocessService
+    Reflect.set(service, 'disposing', false)
+    Reflect.set(service, 'ctx', ctx)
+    for (const graceMs of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(() => service.spawn(spec({ graceMs }))).toThrow('graceMs must be a positive finite number')
+      void expect(service.spawnTerminal({
+        argv: ['bash'], cwd: '/w', rows: 24, cols: 80, graceMs,
+      })).rejects.toThrow('graceMs must be a positive finite number')
+    }
+  })
+
   it('rejects malformed environment entries before command start', async () => {
     for (const env of [{ 'BAD=NAME': 'x' }, { BAD: 'x\0INJECTED=1' }]) {
       const fake = new FakeSandbox()
-      const handle = new E2BSubprocessHandle(runtime(fake), spec({ env }), '/runtime/invalid-environment')
+      const handle = testHandle(runtime(fake), spec({ env }), '/runtime/invalid-environment')
       await expect(handle.done).rejects.toThrow('environment entries')
       expect(fake.startOptions).toBeUndefined()
       expect(fake.removed).toContain('/runtime/invalid-environment')
@@ -462,7 +485,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('preserves UTF-8 bytes when the ASCII transport is split across callbacks', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/split-utf8')
     await flush()
@@ -478,14 +501,14 @@ describe('E2BSubprocessHandle', () => {
 
   it('rejects malformed output transport without confusing it with a consumer sink failure', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/malformed-output')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/malformed-output')
     await flush()
     await fake.stdoutWire('%\n')
     fake.finish()
     await expect(handle.done).rejects.toThrow('invalid base64 output transport')
 
     const stderrFake = new FakeSandbox()
-    const stderrHandle = new E2BSubprocessHandle(runtime(stderrFake), spec(), '/runtime/malformed-stderr')
+    const stderrHandle = testHandle(runtime(stderrFake), spec(), '/runtime/malformed-stderr')
     await flush()
     await stderrFake.stderrWire('%\n')
     stderrFake.finish()
@@ -494,7 +517,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('rejects a naturally completed command whose encoder omits its completion frame', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/incomplete-output')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/incomplete-output')
     await flush()
     fake.alive = false
     fake.handle.succeed(0)
@@ -503,7 +526,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('bounds descendant-held output draining and withholds the incomplete spill', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-bound')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-bound')
     await flush()
     await fake.stdout('leader-output')
     fake.exitStatus = '0\n'
@@ -529,7 +552,7 @@ describe('E2BSubprocessHandle', () => {
       return false
     }) as typeof process.stdout.write)
     try {
-      const handle = new E2BSubprocessHandle(runtime(fake), spec({
+      const handle = testHandle(runtime(fake), spec({
         graceMs: 5,
         stdio: { stdin: 'ignore', stdout: 'inherit', stderr: { maxBytes: 4 } },
       }), '/runtime/inherit-backpressure')
@@ -555,7 +578,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('waits for lossless raw-pipe output after the direct status is published', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       graceMs: 1,
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/pipe-drain')
@@ -580,7 +603,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('accepts clean encoder completion inside the output-drain grace', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-complete')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-complete')
     await flush()
     fake.exitStatus = '0\n'
     fake.afterStatusRead = () => {
@@ -598,7 +621,7 @@ describe('E2BSubprocessHandle', () => {
     fake.delaysKill = true
     fake.delaysKillCompletion = true
     fake.sdkKillStops = false
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-signal')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 5 }), '/runtime/drain-signal')
     await flush()
 
     handle.terminate()
@@ -614,7 +637,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('preserves a published nonzero exit code when termination settles the SDK inside the drain grace', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-signal-settled')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 100 }), '/runtime/drain-signal-settled')
     await flush()
     fake.exitStatus = '7\n'
     fake.afterStatusRead = () => {
@@ -628,7 +651,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('rejects an invalid direct-command exit status', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/invalid-status')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/invalid-status')
     await flush()
     fake.exitStatus = '999\n'
     await expect(handle.done).rejects.toThrow('invalid exit code')
@@ -639,7 +662,7 @@ describe('E2BSubprocessHandle', () => {
   it('rolls back a published process group before rejecting a monitoring failure', async () => {
     const fake = new FakeSandbox()
     fake.statusError = new Error('status transport failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/status-failure')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/status-failure')
 
     await expect(handle.done).rejects.toThrow('status transport failed')
     expect(fake.commandsSeen).toContain('kill -TERM -- -4242')
@@ -650,7 +673,7 @@ describe('E2BSubprocessHandle', () => {
     failed.statusError = new Error('status transport failed')
     failed.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
     failed.handle.killError = new Error('SDK kill failed')
-    const retained = new E2BSubprocessHandle(runtime(failed), spec({ graceMs: 1 }), '/runtime/status-cleanup-failure')
+    const retained = testHandle(runtime(failed), spec({ graceMs: 1 }), '/runtime/status-cleanup-failure')
 
     await expect(retained.done).rejects.toThrow(
       'command monitoring failed and process-group rollback did not reach quiescence',
@@ -659,13 +682,30 @@ describe('E2BSubprocessHandle', () => {
     failed.handle.killError = undefined
     retained.terminate()
     await expect(retained.waitForExit()).resolves.toBe(true)
+
+    // A state-cleanup failure on top preserves the rollback failure instead of
+    // re-aggregating only the original monitoring error.
+    const triple = new FakeSandbox()
+    triple.statusError = new Error('status transport failed')
+    triple.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
+    triple.handle.killError = new Error('SDK kill failed')
+    triple.nextRemoveError = new Error('state cleanup failed')
+    const tripleHandle = testHandle(runtime(triple), spec({ graceMs: 1 }), '/runtime/triple-failure')
+    const failure = await tripleHandle.done.catch((error: unknown) => error as AggregateError)
+    expect(failure).toBeInstanceOf(AggregateError)
+    expect((failure as AggregateError).message).toContain('private state cleanup failed')
+    const nested = (failure as AggregateError).errors[0] as AggregateError
+    expect(nested.message).toContain('rollback did not reach quiescence')
+    triple.handle.killError = undefined
+    tripleHandle.terminate()
+    await expect(tripleHandle.waitForExit()).resolves.toBe(true)
   })
 
   it('surfaces deferred piped-stdin write and close failures as stream errors', async () => {
     const writeFake = new FakeSandbox()
     writeFake.deferStart()
     vi.spyOn(writeFake.handle, 'sendStdin').mockRejectedValueOnce('stdin rejected')
-    const writeHandle = new E2BSubprocessHandle(runtime(writeFake), spec({
+    const writeHandle = testHandle(runtime(writeFake), spec({
       stdio: { stdin: 'pipe', stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
     }), '/runtime/stdin-write-error')
     const writeError = once(writeHandle.stdin!, 'error')
@@ -677,7 +717,7 @@ describe('E2BSubprocessHandle', () => {
 
     const closeFake = new FakeSandbox()
     vi.spyOn(closeFake.handle, 'closeStdin').mockRejectedValueOnce(new Error('close rejected'))
-    const closeHandle = new E2BSubprocessHandle(runtime(closeFake), spec({
+    const closeHandle = testHandle(runtime(closeFake), spec({
       stdio: { stdin: 'pipe', stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
     }), '/runtime/stdin-close-error')
     await flush()
@@ -690,7 +730,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('collects bounded tails, retains valid spills, and maps natural nonzero exits', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: {
         stdin: { data: 'batch' },
         stdout: { maxBytes: 4, spill: { maxBytes: 16 } },
@@ -716,7 +756,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('removes a spill once the complete stream exceeds its cap', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: { maxBytes: 2, spill: { maxBytes: 3 } }, stderr: 'inherit' },
     }), '/runtime/oversize')
     await flush()
@@ -736,7 +776,7 @@ describe('E2BSubprocessHandle', () => {
   it('contains remote spill-removal failures and routes empty inherited output', async () => {
     const fake = new FakeSandbox()
     fake.nextRemoveError = new Error('already removed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'inherit', stderr: { maxBytes: 4, spill: { maxBytes: 8 } } },
     }), '/runtime/remove-error')
     await flush()
@@ -749,7 +789,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('terminates a process group with TERM and reports the signal outcome', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/term')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/term')
     await flush()
     handle.terminate()
     handle.terminate()
@@ -767,7 +807,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('makes termination a permanent no-op after natural quiescence is observed', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/natural-quiescence')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/natural-quiescence')
     await flush()
     fake.finish()
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
@@ -784,7 +824,7 @@ describe('E2BSubprocessHandle', () => {
   it('treats a zombie-only process group as quiescent', async () => {
     const fake = new FakeSandbox()
     fake.zombieOnly = true
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/zombie-quiescence')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/zombie-quiescence')
     await flush()
 
     await expect(handle.waitForExit()).resolves.toBe(true)
@@ -800,7 +840,7 @@ describe('E2BSubprocessHandle', () => {
     fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
     fake.handle.killError = new Error('SDK kill failed')
     fake.deferSignals()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/quiescent-race')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/quiescent-race')
     await flush()
 
     handle.terminate()
@@ -823,7 +863,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     fake.trapsTerm = true
     fake.handle.killError = new Error('already gone')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/kill')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/kill')
     await flush()
     handle.terminate()
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
@@ -838,7 +878,7 @@ describe('E2BSubprocessHandle', () => {
     fake.delaysKill = true
     fake.delaysKillCompletion = true
     fake.sdkKillStops = false
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/termination-fence')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/termination-fence')
     await flush()
     handle.terminate()
     await vi.waitFor(() => { expect(fake.handle.kills).toBe(1) })
@@ -856,7 +896,7 @@ describe('E2BSubprocessHandle', () => {
   it('honors termination requested before asynchronous startup finishes', async () => {
     const fake = new FakeSandbox()
     fake.deferStart()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/deferred-kill')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/deferred-kill')
     handle.terminate()
     fake.releaseStart()
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
@@ -879,7 +919,7 @@ describe('E2BSubprocessHandle', () => {
         signal?.addEventListener('abort', rejectAbort, { once: true })
       })
     }
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/stalled-preparation')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/stalled-preparation')
     await vi.waitFor(() => { expect(preparationSignal).toBeDefined() })
 
     handle.terminate()
@@ -893,7 +933,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     fake.deferProcessGroupRead()
     fake.signalErrors.push(commandError(1), commandError(1))
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/pre-publication-kill')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/pre-publication-kill')
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
 
     handle.terminate()
@@ -913,7 +953,7 @@ describe('E2BSubprocessHandle', () => {
     fake.delaysKillCompletion = true
     fake.sdkKillStops = false
     fake.handle.killResult = false
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/provisional-sdk-false')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/provisional-sdk-false')
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
 
     handle.terminate()
@@ -936,7 +976,7 @@ describe('E2BSubprocessHandle', () => {
       calls += 1
       return calls === 1 ? fake.sandbox : await reconnect.promise
     })
-    const handle = new E2BSubprocessHandle(delayedRuntime, spec(), '/runtime/pre-publication-observer')
+    const handle = testHandle(delayedRuntime, spec(), '/runtime/pre-publication-observer')
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
     handle.terminate()
 
@@ -957,7 +997,7 @@ describe('E2BSubprocessHandle', () => {
     fake.deferProcessGroupRead()
     fake.trapsTerm = true
     fake.handle.killError = new Error('SDK kill unavailable')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-group-kill')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-group-kill')
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
 
     handle.terminate()
@@ -971,7 +1011,7 @@ describe('E2BSubprocessHandle', () => {
     fake.deferProcessGroupRead()
     fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
     fake.handle.killError = new Error('SDK kill failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-failure')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/pre-publication-failure')
     await vi.waitFor(() => { expect(fake.startOptions).toBeDefined() })
 
     handle.terminate()
@@ -987,7 +1027,7 @@ describe('E2BSubprocessHandle', () => {
     absentGroup.deferProcessGroupRead()
     absentGroup.signalErrors.push(commandError(1), commandError(1))
     absentGroup.handle.killError = new Error('SDK kill failed without a provisional group')
-    const absentHandle = new E2BSubprocessHandle(
+    const absentHandle = testHandle(
       runtime(absentGroup),
       spec({ graceMs: 1 }),
       '/runtime/pre-publication-absent-group',
@@ -1005,7 +1045,7 @@ describe('E2BSubprocessHandle', () => {
     optimisticSdk.deferProcessGroupRead()
     optimisticSdk.signalErrors.push(commandError(1), commandError(1))
     optimisticSdk.sdkKillStops = false
-    const optimisticHandle = new E2BSubprocessHandle(
+    const optimisticHandle = testHandle(
       runtime(optimisticSdk),
       spec({ graceMs: 1 }),
       '/runtime/pre-publication-optimistic-sdk',
@@ -1021,14 +1061,14 @@ describe('E2BSubprocessHandle', () => {
 
   it('honors an already-aborted signal when constructing the asynchronous handle directly', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ signal: AbortSignal.abort('stop') }), '/runtime/pre-aborted')
+    const handle = testHandle(runtime(fake), spec({ signal: AbortSignal.abort('stop') }), '/runtime/pre-aborted')
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
   })
 
   it('reacts to a signal that aborts after the remote command has started', async () => {
     const fake = new FakeSandbox()
     const controller = new AbortController()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ signal: controller.signal }), '/runtime/live-abort')
+    const handle = testHandle(runtime(fake), spec({ signal: controller.signal }), '/runtime/live-abort')
     await flush()
     controller.abort('stop')
     await expect(handle.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
@@ -1036,7 +1076,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('can terminate a surviving process group after the command leader settles', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/surviving-group')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/surviving-group')
     await flush()
     await fake.completeOutput()
     fake.handle.succeed(0)
@@ -1054,7 +1094,7 @@ describe('E2BSubprocessHandle', () => {
   it('bounds waitForExit while startup or a live group is pending', async () => {
     const fake = new FakeSandbox()
     fake.deferStart()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/wait')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/wait')
     const beforeStart = new AbortController()
     const pending = handle.waitForExit(beforeStart.signal)
     beforeStart.abort()
@@ -1071,7 +1111,7 @@ describe('E2BSubprocessHandle', () => {
 
     const terminatingFake = new FakeSandbox()
     terminatingFake.deferStart()
-    const terminating = new E2BSubprocessHandle(runtime(terminatingFake), spec(), '/runtime/wait-termination-start')
+    const terminating = testHandle(runtime(terminatingFake), spec(), '/runtime/wait-termination-start')
     terminating.terminate()
     const beforeHandle = new AbortController()
     const handlePending = terminating.waitForExit(beforeHandle.signal)
@@ -1083,7 +1123,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('bounds both sides of the liveness-poll abort race', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/poll-abort')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/poll-abort')
     await flush()
 
     const beforeTick = new AbortController()
@@ -1114,7 +1154,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('observes a live group across one successful bounded poll', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/poll-success')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/poll-success')
     await flush()
     setTimeout(() => { fake.finish() }, 1)
     await expect(handle.waitForExit(new AbortController().signal)).resolves.toBe(true)
@@ -1124,7 +1164,7 @@ describe('E2BSubprocessHandle', () => {
   it('treats startup failure as no live tree and contains readiness rejection', async () => {
     const fake = new FakeSandbox()
     fake.backgroundError = new Error('start failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/fail')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/fail')
     await expect(handle.done).rejects.toThrow('start failed')
     expect(handle.pid).toBe(-1)
     expect(fake.removed).toContain('/runtime/fail/environment')
@@ -1132,7 +1172,7 @@ describe('E2BSubprocessHandle', () => {
     await expect(handle.waitForExit()).resolves.toBe(true)
     handle.terminate()
 
-    const unavailableHandle = new E2BSubprocessHandle(
+    const unavailableHandle = testHandle(
       runtime(new FakeSandbox(), async () => { throw new Error('sandbox unavailable') }),
       spec(),
       '/runtime/unavailable-start',
@@ -1142,14 +1182,14 @@ describe('E2BSubprocessHandle', () => {
 
     const envFailure = new FakeSandbox()
     envFailure.envError = new Error('ambient lookup failed')
-    const envHandle = new E2BSubprocessHandle(runtime(envFailure), spec(), '/runtime/env-failure')
+    const envHandle = testHandle(runtime(envFailure), spec(), '/runtime/env-failure')
     await expect(envHandle.done).rejects.toThrow('ambient lookup failed')
     expect(envFailure.removed).toEqual([])
 
     const expectEnvironmentFailure = async (name: string, wire: string, message: string): Promise<void> => {
       const fake = new FakeSandbox()
       fake.environmentWire = wire
-      const failed = new E2BSubprocessHandle(runtime(fake), spec(), `/runtime/${name}`)
+      const failed = testHandle(runtime(fake), spec(), `/runtime/${name}`)
       await expect(failed.done).rejects.toThrow(message)
     }
     const encodedEnvironment = Buffer.from('PATH=/bin\0').toString('base64')
@@ -1180,13 +1220,13 @@ describe('E2BSubprocessHandle', () => {
     const cleanupFailure = new FakeSandbox()
     cleanupFailure.backgroundError = new Error('start failed before credential consumption')
     cleanupFailure.nextRemoveError = new Error('credential cleanup failed')
-    const cleanupHandle = new E2BSubprocessHandle(runtime(cleanupFailure), spec(), '/runtime/cleanup-failure')
+    const cleanupHandle = testHandle(runtime(cleanupFailure), spec(), '/runtime/cleanup-failure')
     await expect(cleanupHandle.done).rejects.toThrow('command failed and private state cleanup failed')
 
     const absentState = new FakeSandbox()
     absentState.backgroundError = new Error('start failed after external cleanup')
     absentState.nextRemoveError = new FileNotFoundError('already removed')
-    const absentHandle = new E2BSubprocessHandle(runtime(absentState), spec(), '/runtime/absent-state')
+    const absentHandle = testHandle(runtime(absentState), spec(), '/runtime/absent-state')
     await expect(absentHandle.done).rejects.toThrow('start failed after external cleanup')
   })
 
@@ -1194,7 +1234,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     fake.deferStart()
     fake.backgroundError = new Error('start failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/fail-with-signal')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/fail-with-signal')
     const waiting = handle.waitForExit(new AbortController().signal)
     fake.releaseStart()
     await expect(handle.done).rejects.toThrow('start failed')
@@ -1209,7 +1249,7 @@ describe('E2BSubprocessHandle', () => {
       if (calls === 1) return fake.sandbox
       throw new Error('connection unavailable')
     })
-    const handle = new E2BSubprocessHandle(unavailable, spec(), '/runtime/unavailable')
+    const handle = testHandle(unavailable, spec(), '/runtime/unavailable')
     await flush()
     await expect(handle.waitForExit()).rejects.toThrow('connection unavailable')
     fake.finish()
@@ -1224,7 +1264,7 @@ describe('E2BSubprocessHandle', () => {
       calls += 1
       return calls === 1 ? fake.sandbox : await reconnect.promise
     })
-    const handle = new E2BSubprocessHandle(unavailable, spec(), '/runtime/reconnect-abort')
+    const handle = testHandle(unavailable, spec(), '/runtime/reconnect-abort')
     await flush()
     const controller = new AbortController()
     const waiting = handle.waitForExit(controller.signal)
@@ -1238,7 +1278,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('returns false when a liveness request itself is aborted and surfaces other probe failures', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/probe')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/probe')
     await flush()
     const controller = new AbortController()
     controller.abort()
@@ -1251,7 +1291,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('treats a timeout-killed sandbox as quiescent during liveness probing', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/expired-sandbox')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/expired-sandbox')
     await flush()
     fake.finish()
     await handle.done
@@ -1263,7 +1303,7 @@ describe('E2BSubprocessHandle', () => {
   it('treats a missing sandbox handle as quiescent during liveness acquisition', async () => {
     const fake = new FakeSandbox()
     let calls = 0
-    const handle = new E2BSubprocessHandle(runtime(fake, async () => {
+    const handle = testHandle(runtime(fake, async () => {
       calls += 1
       if (calls === 1) return fake.sandbox
       throw new SandboxNotFoundError('sandbox expired')
@@ -1280,7 +1320,7 @@ describe('E2BSubprocessHandle', () => {
   it('treats sandbox loss during termination as quiescent', async () => {
     const fake = new FakeSandbox()
     let calls = 0
-    const handle = new E2BSubprocessHandle(runtime(fake, async () => {
+    const handle = testHandle(runtime(fake, async () => {
       calls += 1
       if (calls === 1) return fake.sandbox
       throw new SandboxNotFoundError('sandbox expired')
@@ -1298,7 +1338,7 @@ describe('E2BSubprocessHandle', () => {
   it('makes batch stdin close failures best-effort', async () => {
     const fake = new FakeSandbox()
     vi.spyOn(fake.handle, 'sendStdin').mockRejectedValueOnce(new Error('closed'))
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: { data: 'ignored' }, stdout: { maxBytes: 4 }, stderr: { maxBytes: 4 } },
     }), '/runtime/stdin-closed')
     await flush()
@@ -1309,7 +1349,7 @@ describe('E2BSubprocessHandle', () => {
   it('rejects malformed SDK process ids and non-command settlement failures', async () => {
     const invalidPid = new FakeSandbox()
     invalidPid.handle.pid = 0
-    const invalid = new E2BSubprocessHandle(runtime(invalidPid), spec(), '/runtime/invalid-pid')
+    const invalid = testHandle(runtime(invalidPid), spec(), '/runtime/invalid-pid')
     await expect(invalid.done).rejects.toThrow(/invalid command pid 0/)
     expect(invalidPid.handle.kills).toBe(1)
     expect(invalidPid.removed).toContain('/runtime/invalid-pid/environment')
@@ -1318,7 +1358,7 @@ describe('E2BSubprocessHandle', () => {
     const failedRollback = new FakeSandbox()
     failedRollback.handle.pid = 0
     failedRollback.handle.killError = new Error('invalid handle kill failed')
-    const retained = new E2BSubprocessHandle(runtime(failedRollback), spec(), '/runtime/invalid-pid-retained')
+    const retained = testHandle(runtime(failedRollback), spec(), '/runtime/invalid-pid-retained')
     await expect(retained.done).rejects.toThrow('invalid command pid rollback did not reach quiescence')
     await expect(retained.waitForExit()).rejects.toThrow('invalid handle kill failed')
     failedRollback.handle.killError = undefined
@@ -1326,7 +1366,7 @@ describe('E2BSubprocessHandle', () => {
     await expect(retained.waitForExit()).resolves.toBe(true)
 
     const crashedFake = new FakeSandbox()
-    const crashed = new E2BSubprocessHandle(runtime(crashedFake), spec(), '/runtime/crashed')
+    const crashed = testHandle(runtime(crashedFake), spec(), '/runtime/crashed')
     await flush()
     crashedFake.alive = false
     crashedFake.handle.crash(new Error('command transport failed'))
@@ -1339,7 +1379,7 @@ describe('E2BSubprocessHandle', () => {
     invalidGroup.delaysKill = true
     invalidGroup.sdkKillStops = false
     invalidGroup.afterProbe = () => { invalidGroup.alive = false }
-    const invalid = new E2BSubprocessHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
+    const invalid = testHandle(runtime(invalidGroup), spec(), '/runtime/invalid-group')
     await expect(invalid.done).rejects.toThrow(/invalid process-group id/)
     expect(invalidGroup.handle.kills).toBe(1)
     expect(invalidGroup.commandsSeen).toContain('kill -KILL -- -4242')
@@ -1351,14 +1391,14 @@ describe('E2BSubprocessHandle', () => {
     unsafeGroup.delaysKill = true
     unsafeGroup.sdkKillStops = false
     unsafeGroup.afterProbe = () => { unsafeGroup.alive = false }
-    const unsafe = new E2BSubprocessHandle(runtime(unsafeGroup), spec(), '/runtime/unsafe-group')
+    const unsafe = testHandle(runtime(unsafeGroup), spec(), '/runtime/unsafe-group')
     await expect(unsafe.done).rejects.toThrow(/unsafe published process-group id 1/)
     expect(unsafeGroup.commandsSeen).not.toContain('kill -KILL -- -1')
     await expect(unsafe.waitForExit()).resolves.toBe(true)
 
     const absentGroup = new FakeSandbox()
     absentGroup.processGroupId = ''
-    const absent = new E2BSubprocessHandle(runtime(absentGroup), spec(), '/runtime/absent-group')
+    const absent = testHandle(runtime(absentGroup), spec(), '/runtime/absent-group')
     await flush()
     absentGroup.finish()
     await expect(absent.done).rejects.toThrow(/exited before publishing/)
@@ -1372,7 +1412,7 @@ describe('E2BSubprocessHandle', () => {
     fake.processGroupId = 'not-a-pid\n'
     fake.signalError = new Error('rollback signal failed')
     fake.handle.killError = new Error('SDK kill failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/failed-rollback')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/failed-rollback')
 
     let failure: unknown
     try {
@@ -1403,7 +1443,7 @@ describe('E2BSubprocessHandle', () => {
     naturallyGone.processGroupId = 'not-a-pid\n'
     naturallyGone.signalError = new Error('rollback signal failed')
     naturallyGone.handle.killError = new Error('SDK kill failed')
-    const observed = new E2BSubprocessHandle(runtime(naturallyGone), spec(), '/runtime/failed-rollback-observed')
+    const observed = testHandle(runtime(naturallyGone), spec(), '/runtime/failed-rollback-observed')
     await expect(observed.done).rejects.toThrow('process-group publication failed')
     naturallyGone.alive = false
     await expect(observed.waitForExit()).resolves.toBe(true)
@@ -1412,7 +1452,7 @@ describe('E2BSubprocessHandle', () => {
   it('waits for delayed process-group publication', async () => {
     const fake = new FakeSandbox()
     fake.processGroupReads.push('', '4242\n')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec(), '/runtime/delayed-group')
+    const handle = testHandle(runtime(fake), spec(), '/runtime/delayed-group')
     await vi.waitFor(() => { expect(handle.pid).toBe(4242) })
     fake.finish()
     await expect(handle.done).resolves.toEqual({ exitCode: 0, signal: null })
@@ -1420,7 +1460,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('handles output backpressure and contains a stderr sink failure', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
     }), '/runtime/backpressure')
     await flush()
@@ -1445,7 +1485,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('settles output backpressure when the consumer closes the pipe', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/backpressure-close')
     await flush()
@@ -1462,7 +1502,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('breaks output backpressure when termination owns the command', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/backpressure-termination')
     await flush()
@@ -1484,7 +1524,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('settles backpressure when a synchronous pipe write starts termination', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/backpressure-synchronous-termination')
     await flush()
@@ -1500,7 +1540,7 @@ describe('E2BSubprocessHandle', () => {
 
   it('contains a pipe callback failure instead of rejecting command settlement', async () => {
     const fake = new FakeSandbox()
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({
+    const handle = testHandle(runtime(fake), spec({
       stdio: { stdin: 'ignore', stdout: 'pipe', stderr: { maxBytes: 4 } },
     }), '/runtime/pipe-error')
     await flush()
@@ -1516,14 +1556,14 @@ describe('E2BSubprocessHandle', () => {
     const gone = new FakeSandbox()
     gone.trapsTerm = true
     gone.signalError = commandError(1)
-    const goneHandle = new E2BSubprocessHandle(runtime(gone), spec({ graceMs: 1 }), '/runtime/gone-signal')
+    const goneHandle = testHandle(runtime(gone), spec({ graceMs: 1 }), '/runtime/gone-signal')
     await flush()
     goneHandle.terminate()
     await expect(goneHandle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
 
     const failed = new FakeSandbox()
     failed.signalError = new Error('signal transport failed')
-    const failedHandle = new E2BSubprocessHandle(runtime(failed), spec(), '/runtime/failed-signal')
+    const failedHandle = testHandle(runtime(failed), spec(), '/runtime/failed-signal')
     await flush()
     failedHandle.terminate()
     await expect(failedHandle.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
@@ -1534,7 +1574,7 @@ describe('E2BSubprocessHandle', () => {
     const fake = new FakeSandbox()
     fake.signalErrors.push(new Error('TERM transport failed'), new Error('KILL transport failed'))
     fake.handle.killError = new Error('SDK kill failed')
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry-signal')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry-signal')
     await flush()
 
     handle.terminate()
@@ -1548,7 +1588,7 @@ describe('E2BSubprocessHandle', () => {
     missingGroup.trapsTerm = true
     missingGroup.signalErrors.push(undefined, commandError(1))
     missingGroup.handle.killError = new Error('SDK kill failed after group exit race')
-    const raced = new E2BSubprocessHandle(runtime(missingGroup), spec({ graceMs: 1 }), '/runtime/group-exit-race')
+    const raced = testHandle(runtime(missingGroup), spec({ graceMs: 1 }), '/runtime/group-exit-race')
     await flush()
     raced.terminate()
     await expect(raced.waitForExit()).rejects.toThrow('remained live after force termination')
@@ -1562,7 +1602,7 @@ describe('E2BSubprocessHandle', () => {
     fake.trapsTerm = true
     fake.sdkKillStops = false
     fake.signalErrors.push(undefined, new Error('KILL transport failed'))
-    const handle = new E2BSubprocessHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/optimistic-sdk-kill')
+    const handle = testHandle(runtime(fake), spec({ graceMs: 1 }), '/runtime/optimistic-sdk-kill')
     await flush()
 
     handle.terminate()
diff --git a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
index 826732f057..5472b2cfa7 100644
--- a/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
+++ b/packages/e2b/subprocess-e2b/tests/terminal.spec.ts
@@ -259,10 +259,20 @@ function holdRequestUntilAbort(started: PromiseWithResolvers<AbortSignal>) {
   }
 }
 
+/** Spawn the terminal under test with the config default the service would pass. */
+function testSpawn(
+  runtime: Parameters<typeof spawnE2BTerminal>[0],
+  spec: Parameters<typeof spawnE2BTerminal>[1],
+  stateDir: string,
+  pollMs = 20,
+): ReturnType<typeof spawnE2BTerminal> {
+  return spawnE2BTerminal(runtime, spec, stateDir, pollMs)
+}
+
 describe('E2B terminal allocation', () => {
   it('hides bootstrap-shell bytes and preserves requested-shell bytes across the output boundary', async () => {
     const fake = new FakeTerminalSandbox()
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/terminal-one')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/terminal-one')
     let output = ''
     terminal.output.on('data', (chunk) => { output += String(chunk) })
     await new Promise(resolve => setTimeout(resolve, 0))
@@ -314,7 +324,7 @@ describe('E2B terminal allocation', () => {
   it('inherits only safe ambient values and limits the allocation signal to setup', async () => {
     const fake = new FakeTerminalSandbox()
     const controller = new AbortController()
-    const terminal = await spawnE2BTerminal(
+    const terminal = await testSpawn(
       runtime(fake),
       spec({ env: undefined, signal: controller.signal }),
       '/runtime/abort-live',
@@ -335,7 +345,7 @@ describe('E2B terminal allocation', () => {
     const fake = new FakeTerminalSandbox()
     fake.deferCreate()
     const controller = new AbortController()
-    const spawning = spawnE2BTerminal(
+    const spawning = testSpawn(
       runtime(fake),
       spec({ signal: controller.signal }),
       '/runtime/allocation-cancel',
@@ -352,23 +362,23 @@ describe('E2B terminal allocation', () => {
 
   it('rejects malformed environment and argv values before PTY allocation', async () => {
     const invalidName = new FakeTerminalSandbox()
-    await expect(spawnE2BTerminal(runtime(invalidName), spec({ env: { 'BAD=NAME': 'x' } }), '/runtime/name'))
+    await expect(testSpawn(runtime(invalidName), spec({ env: { 'BAD=NAME': 'x' } }), '/runtime/name'))
       .rejects.toThrow('environment entries')
     expect(invalidName.createOptions).toBeUndefined()
 
     const invalidValue = new FakeTerminalSandbox()
-    await expect(spawnE2BTerminal(runtime(invalidValue), spec({ env: { BAD: 'x\0y' } }), '/runtime/value'))
+    await expect(testSpawn(runtime(invalidValue), spec({ env: { BAD: 'x\0y' } }), '/runtime/value'))
       .rejects.toThrow('environment entries')
 
     const invalidArg = new FakeTerminalSandbox()
-    await expect(spawnE2BTerminal(runtime(invalidArg), spec({ argv: ['/bin/bash', 'x\0y'] }), '/runtime/argv'))
+    await expect(testSpawn(runtime(invalidArg), spec({ argv: ['/bin/bash', 'x\0y'] }), '/runtime/argv'))
       .rejects.toThrow('argv must not contain NUL')
   })
 
   it('cleans malformed handles, bootstrap failures, and readiness failures', async () => {
     const failedState = new FakeTerminalSandbox()
     failedState.writeError = new Error('state write failed')
-    await expect(spawnE2BTerminal(runtime(failedState), spec(), '/runtime/state-write'))
+    await expect(testSpawn(runtime(failedState), spec(), '/runtime/state-write'))
       .rejects.toThrow('state write failed')
     expect(failedState.writes.get('/runtime/state-write/environment')).toContain('KEEP=visible\0')
     expect(failedState.removed).toContain('/runtime/state-write')
@@ -377,19 +387,19 @@ describe('E2B terminal allocation', () => {
     const stateAlreadyGone = new FakeTerminalSandbox()
     stateAlreadyGone.writeError = new Error('state write failed after external cleanup')
     stateAlreadyGone.removeError = new FileNotFoundError('state already gone')
-    await expect(spawnE2BTerminal(runtime(stateAlreadyGone), spec(), '/runtime/state-gone'))
+    await expect(testSpawn(runtime(stateAlreadyGone), spec(), '/runtime/state-gone'))
       .rejects.toThrow('state write failed after external cleanup')
 
     const invalidPid = new FakeTerminalSandbox()
     invalidPid.handle.pid = 0
-    await expect(spawnE2BTerminal(runtime(invalidPid), spec(), '/runtime/invalid-pid'))
+    await expect(testSpawn(runtime(invalidPid), spec(), '/runtime/invalid-pid'))
       .rejects.toThrow('invalid terminal pid 0')
     expect(invalidPid.handle.sdkKills).toBe(1)
     expect(invalidPid.removed).toContain('/runtime/invalid-pid')
 
     const failedInput = new FakeTerminalSandbox()
     failedInput.sendError = new Error('bootstrap failed')
-    await expect(spawnE2BTerminal(runtime(failedInput), spec(), '/runtime/input'))
+    await expect(testSpawn(runtime(failedInput), spec(), '/runtime/input'))
       .rejects.toThrow('bootstrap failed')
     expect(failedInput.commands).toContain('kill -TERM -- -123')
     expect(failedInput.groups).toEqual([])
@@ -397,7 +407,7 @@ describe('E2B terminal allocation', () => {
     const invalidSession = new FakeTerminalSandbox()
     invalidSession.sessionId = 'not-a-session\n'
     invalidSession.clearOnTerm = false
-    await expect(spawnE2BTerminal(runtime(invalidSession), spec(), '/runtime/session'))
+    await expect(testSpawn(runtime(invalidSession), spec(), '/runtime/session'))
       .rejects.toThrow('cannot resolve process session')
     expect(invalidSession.commands).toContain('kill -TERM -- -123')
     expect(invalidSession.commands).toContain('kill -KILL -- -123')
@@ -410,7 +420,7 @@ describe('E2B terminal allocation', () => {
     const termFailed = new FakeTerminalSandbox()
     termFailed.sendError = new Error('bootstrap failed')
     termFailed.termFailure = new Error('TERM transport failed')
-    await expect(spawnE2BTerminal(runtime(termFailed), spec(), '/runtime/term-failed'))
+    await expect(testSpawn(runtime(termFailed), spec(), '/runtime/term-failed'))
       .rejects.toThrow('bootstrap failed')
     expect(termFailed.commands).toContain('kill -KILL -- -123')
     expect(termFailed.handle.sdkKills).toBe(1)
@@ -421,7 +431,7 @@ describe('E2B terminal allocation', () => {
     uninspectable.handle.sdkKillError = new Error('PTY kill failed')
     let uninspectableFailure: unknown
     try {
-      await spawnE2BTerminal(runtime(uninspectable), spec(), '/runtime/uninspectable')
+      await testSpawn(runtime(uninspectable), spec(), '/runtime/uninspectable')
     } catch (error: unknown) {
       uninspectableFailure = error
     }
@@ -432,21 +442,21 @@ describe('E2B terminal allocation', () => {
     survivingGroups.sendError = new Error('bootstrap failed')
     survivingGroups.clearOnTerm = false
     survivingGroups.clearOnKill = false
-    await expect(spawnE2BTerminal(runtime(survivingGroups), spec({ graceMs: 1 }), '/runtime/surviving-groups'))
+    await expect(testSpawn(runtime(survivingGroups), spec({ graceMs: 1 }), '/runtime/surviving-groups'))
       .rejects.toThrow('bootstrap failed')
 
     const survivingPid = new FakeTerminalSandbox()
     survivingPid.sendError = new Error('bootstrap failed')
     survivingPid.groups = []
     survivingPid.handle.settleOnSdkKill = false
-    await expect(spawnE2BTerminal(runtime(survivingPid), spec({ graceMs: 1 }), '/runtime/surviving-pid'))
+    await expect(testSpawn(runtime(survivingPid), spec({ graceMs: 1 }), '/runtime/surviving-pid'))
       .rejects.toThrow('bootstrap failed')
 
     const waitFailed = new FakeTerminalSandbox()
     waitFailed.handle.waitError = new Error('wait failed')
     waitFailed.handle.settleOnSdkKill = false
     waitFailed.handle.sdkKillError = new Error('kill failed')
-    await expect(spawnE2BTerminal(runtime(waitFailed), spec(), '/runtime/wait-failed'))
+    await expect(testSpawn(runtime(waitFailed), spec(), '/runtime/wait-failed'))
       .rejects.toThrow('wait failed')
     expect(waitFailed.handle.sdkKills).toBe(1)
 
@@ -454,7 +464,7 @@ describe('E2B terminal allocation', () => {
     cleanupFailed.handle.pid = 0
     cleanupFailed.handle.sdkKillError = new Error('kill transport failed')
     cleanupFailed.removeError = new Error('remove transport failed')
-    await expect(spawnE2BTerminal(runtime(cleanupFailed), spec(), '/runtime/cleanup-failed'))
+    await expect(testSpawn(runtime(cleanupFailed), spec(), '/runtime/cleanup-failed'))
       .rejects.toThrow('invalid terminal pid 0')
 
     const expiredDuringRollback = new FakeTerminalSandbox()
@@ -463,7 +473,7 @@ describe('E2B terminal allocation', () => {
     expiredDuringRollback.handle.settleOnSdkKill = false
     expiredDuringRollback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
     expiredDuringRollback.removeError = new SandboxNotFoundError('sandbox expired')
-    await expect(spawnE2BTerminal(runtime(expiredDuringRollback), spec(), '/runtime/expired-rollback'))
+    await expect(testSpawn(runtime(expiredDuringRollback), spec(), '/runtime/expired-rollback'))
       .rejects.toThrow('bootstrap failed before timeout')
     expect(expiredDuringRollback.handle.sdkKills).toBe(1)
 
@@ -471,30 +481,30 @@ describe('E2B terminal allocation', () => {
     expiredBeforeSdkRollback.handle.waitError = new Error('wait failed after timeout')
     expiredBeforeSdkRollback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
     expiredBeforeSdkRollback.handle.settleOnSdkKill = false
-    await expect(spawnE2BTerminal(runtime(expiredBeforeSdkRollback), spec(), '/runtime/expired-sdk-rollback'))
+    await expect(testSpawn(runtime(expiredBeforeSdkRollback), spec(), '/runtime/expired-sdk-rollback'))
       .rejects.toThrow('wait failed after timeout')
 
     const missingDuringDisconnect = new FakeTerminalSandbox()
     missingDuringDisconnect.sendError = new Error('bootstrap failed before disconnect')
     missingDuringDisconnect.handle.disconnectError = new SandboxNotFoundError('sandbox expired')
-    await expect(spawnE2BTerminal(runtime(missingDuringDisconnect), spec(), '/runtime/missing-disconnect'))
+    await expect(testSpawn(runtime(missingDuringDisconnect), spec(), '/runtime/missing-disconnect'))
       .rejects.toThrow('bootstrap failed before disconnect')
 
     const failedDisconnect = new FakeTerminalSandbox()
     failedDisconnect.sendError = new Error('bootstrap failed with disconnect failure')
     failedDisconnect.handle.disconnectError = new Error('disconnect transport failed')
-    await expect(spawnE2BTerminal(runtime(failedDisconnect), spec(), '/runtime/failed-disconnect'))
+    await expect(testSpawn(runtime(failedDisconnect), spec(), '/runtime/failed-disconnect'))
       .rejects.toThrow('bootstrap failed with disconnect failure')
   })
 
   it('propagates setup cancellation and provider failures', async () => {
     const aborted = new FakeTerminalSandbox()
-    await expect(spawnE2BTerminal(runtime(aborted), spec({ signal: AbortSignal.abort(new Error('stop')) }), '/runtime/abort'))
+    await expect(testSpawn(runtime(aborted), spec({ signal: AbortSignal.abort(new Error('stop')) }), '/runtime/abort'))
       .rejects.toThrow('stop')
 
     const createFailed = new FakeTerminalSandbox()
     createFailed.createError = new Error('create failed')
-    await expect(spawnE2BTerminal(runtime(createFailed), spec(), '/runtime/create'))
+    await expect(testSpawn(runtime(createFailed), spec(), '/runtime/create'))
       .rejects.toThrow('create failed')
 
   })
@@ -502,7 +512,7 @@ describe('E2B terminal allocation', () => {
   it('bounds a missing bootstrap-output boundary by process exit or cancellation', async () => {
     const exited = new FakeTerminalSandbox()
     exited.emitOutputMarker = false
-    const exiting = spawnE2BTerminal(runtime(exited), spec(), '/runtime/missing-output-boundary')
+    const exiting = testSpawn(runtime(exited), spec(), '/runtime/missing-output-boundary')
     await vi.waitFor(() => { expect(exited.inputs).toHaveLength(1) })
     exited.handle.succeed(0)
     await expect(exiting).rejects.toThrow('terminal exited before publishing its output boundary')
@@ -510,7 +520,7 @@ describe('E2B terminal allocation', () => {
     const cancelled = new FakeTerminalSandbox()
     cancelled.emitOutputMarker = false
     const controller = new AbortController()
-    const cancelling = spawnE2BTerminal(
+    const cancelling = testSpawn(
       runtime(cancelled),
       spec({ signal: controller.signal }),
       '/runtime/cancel-output-boundary',
@@ -525,7 +535,7 @@ describe('E2B terminal allocation', () => {
 describe('E2B terminal lifecycle', () => {
   it('aborts and joins in-flight terminal operations before cleanup', async () => {
     const fake = new FakeTerminalSandbox()
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/in-flight-operations')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/in-flight-operations')
     const writeStarted = Promise.withResolvers<AbortSignal>()
     const inspectStarted = Promise.withResolvers<AbortSignal>()
     const signalStarted = Promise.withResolvers<AbortSignal>()
@@ -563,7 +573,7 @@ describe('E2B terminal lifecycle', () => {
   it('maps ordinary exits, closes output, and reports an absent foreground after exit', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/natural')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/natural')
     terminal.output.resume()
     const ended = once(terminal.output, 'end')
     fake.handle.succeed(7)
@@ -583,7 +593,7 @@ describe('E2B terminal lifecycle', () => {
   ] as const)('classifies an unrequested command exit %i', async (exitCode, expected) => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), `/runtime/exit-${exitCode}`)
+    const terminal = await testSpawn(runtime(fake), spec(), `/runtime/exit-${exitCode}`)
     fake.handle.fail(exitCode)
     await expect(terminal.done).resolves.toEqual(expected)
     await terminal.terminate()
@@ -593,7 +603,7 @@ describe('E2B terminal lifecycle', () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
     fake.zombieGroups = [123]
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/zombie-session')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/zombie-session')
 
     fake.handle.succeed(0)
     await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
@@ -605,7 +615,7 @@ describe('E2B terminal lifecycle', () => {
 
   it('treats a timeout-killed sandbox as quiescent during terminal cleanup', async () => {
     const fake = new FakeTerminalSandbox()
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/expired-sandbox')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/expired-sandbox')
     fake.sessionGroupsFailure = new SandboxNotFoundError('sandbox expired')
     fake.handle.succeed(0)
 
@@ -618,7 +628,7 @@ describe('E2B terminal lifecycle', () => {
     fake.groups = []
     fake.handle.settleOnSdkKill = false
     fake.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
 
     await terminal.terminate()
     expect(fake.handle.sdkKills).toBe(1)
@@ -629,7 +639,7 @@ describe('E2B terminal lifecycle', () => {
     fake.groups = []
     fake.handle.settleOnSdkKill = false
     fake.handle.sdkKillError = new Error('PTY kill transport failed')
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
 
     await expect(terminal.terminate()).rejects.toThrow('PTY kill transport failed')
     fake.handle.sdkKillError = undefined
@@ -643,7 +653,7 @@ describe('E2B terminal lifecycle', () => {
     ['propagates another failure', new Error('disconnect failed'), false],
   ] as const)('%s while disconnecting a settled terminal', async (_label, failure, accepted) => {
     const fake = new FakeTerminalSandbox()
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), `/runtime/disconnect-${accepted}`)
+    const terminal = await testSpawn(runtime(fake), spec(), `/runtime/disconnect-${accepted}`)
     fake.handle.disconnectError = failure
     fake.groups = []
     fake.handle.succeed(0)
@@ -655,7 +665,7 @@ describe('E2B terminal lifecycle', () => {
   it('rejects killing the terminal shell and propagates live foreground failures', async () => {
     const fake = new FakeTerminalSandbox()
     fake.foreground = '123\n'
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/signal')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/signal')
     await expect(terminal.signalForeground('SIGKILL')).rejects.toThrow('refusing to SIGKILL')
     fake.foreground = 'invalid\n'
     await expect(terminal.inspectForeground()).rejects.toThrow('cannot resolve foreground')
@@ -671,7 +681,7 @@ describe('E2B terminal lifecycle', () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = [123, 456]
     fake.clearOnTerm = false
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 0 }), '/runtime/escalate')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 0 }), '/runtime/escalate')
     const terminating = terminal.terminate()
     await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
     await terminating
@@ -682,7 +692,7 @@ describe('E2B terminal lifecycle', () => {
   it('surfaces cleanup failures and allows a later retry', async () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = [1]
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry')
     await expect(terminal.terminate()).rejects.toThrow('unsafe process group 1')
 
     fake.groups = []
@@ -694,7 +704,7 @@ describe('E2B terminal lifecycle', () => {
   it('propagates a process-group signalling transport failure before retry', async () => {
     const fake = new FakeTerminalSandbox()
     fake.termFailure = new Error('signal transport failed')
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/signal-failure')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/signal-failure')
     await expect(terminal.terminate()).rejects.toThrow('signal transport failed')
 
     fake.groups = []
@@ -704,7 +714,7 @@ describe('E2B terminal lifecycle', () => {
 
     const alreadyExited = new FakeTerminalSandbox()
     alreadyExited.termFailure = commandError(1)
-    const tolerant = await spawnE2BTerminal(runtime(alreadyExited), spec({ graceMs: 1 }), '/runtime/group-exited')
+    const tolerant = await testSpawn(runtime(alreadyExited), spec({ graceMs: 1 }), '/runtime/group-exited')
     const tolerantTermination = tolerant.terminate()
     await expect(tolerant.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
     await tolerantTermination
@@ -714,7 +724,7 @@ describe('E2B terminal lifecycle', () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
     fake.removeError = new Error('private state already gone')
-    const terminal = await spawnE2BTerminal(runtime(fake), spec(), '/runtime/reject-during-cleanup')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/reject-during-cleanup')
     terminal.output.on('error', () => {})
     const cleanup = terminal.terminate()
     await Promise.resolve()
@@ -727,7 +737,7 @@ describe('E2B terminal lifecycle', () => {
     const fake = new FakeTerminalSandbox()
     fake.groups = []
     fake.handle.settleOnSdkKill = false
-    const terminal = await spawnE2BTerminal(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
     terminal.output.on('error', () => {})
     const cleanup = terminal.terminate()
     while (fake.handle.sdkKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
@@ -741,20 +751,20 @@ describe('E2B terminal lifecycle', () => {
     const survivor = new FakeTerminalSandbox()
     survivor.clearOnTerm = false
     survivor.clearOnKill = false
-    const terminal = await spawnE2BTerminal(runtime(survivor), spec({ graceMs: 1 }), '/runtime/survivor')
+    const terminal = await testSpawn(runtime(survivor), spec({ graceMs: 1 }), '/runtime/survivor')
     await expect(terminal.terminate()).rejects.toThrow('surviving process groups: 123')
 
     const livePid = new FakeTerminalSandbox()
     livePid.groups = []
     livePid.handle.settleOnSdkKill = false
-    const live = await spawnE2BTerminal(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
+    const live = await testSpawn(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
     await expect(live.terminate()).rejects.toThrow('surviving pid: 123')
     livePid.handle.succeed(0)
     await live.done
 
     const crashed = new FakeTerminalSandbox()
     crashed.groups = []
-    const failed = await spawnE2BTerminal(runtime(crashed), spec(), '/runtime/crashed')
+    const failed = await testSpawn(runtime(crashed), spec(), '/runtime/crashed')
     const outputError = once(failed.output, 'error')
     crashed.handle.crash('transport gone')
     await expect(failed.done).rejects.toEqual('transport gone')
diff --git a/packages/e2b/subprocess-e2b/tsconfig.json b/packages/e2b/subprocess-e2b/tsconfig.json
index fda7cfc667..1bae0ef012 100644
--- a/packages/e2b/subprocess-e2b/tsconfig.json
+++ b/packages/e2b/subprocess-e2b/tsconfig.json
@@ -4,22 +4,27 @@
     "rootDir": "src",
     "outDir": "lib/types"
   },
-  "include": ["src"],
+  "include": [
+    "src"
+  ],
   "references": [
-    {
-      "path": "../../../vendor/cosmokit"
-    },
     {
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../e2b"
+      "path": "../../../vendor/cosmokit"
     },
     {
       "path": "../../subprocess/subprocess"
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../util/timeout"
+    },
+    {
+      "path": "../e2b"
     }
   ]
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d2e7d0ec1c..fab00ba9cb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -3190,6 +3190,9 @@ importers:
       '@deepseek-ai/dsh-subprocess':
         specifier: workspace:^
         version: link:../../subprocess/subprocess
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis

From b77dbf8ad8b307a18115bdcf808572f9ad76f71e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:06:26 +0800
Subject: [PATCH 398/516] fix(e2b): mount sandbox policy in live PTY test

---
 packages/e2b/e2b/package.json             | 1 +
 packages/e2b/e2b/tests/composition.e2e.ts | 8 +++++---
 pnpm-lock.yaml                            | 3 +++
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/packages/e2b/e2b/package.json b/packages/e2b/e2b/package.json
index a77e3d9464..5abacb278a 100644
--- a/packages/e2b/e2b/package.json
+++ b/packages/e2b/e2b/package.json
@@ -35,6 +35,7 @@
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/e2b/e2b/tests/composition.e2e.ts b/packages/e2b/e2b/tests/composition.e2e.ts
index 01316aeb2d..6da102a827 100644
--- a/packages/e2b/e2b/tests/composition.e2e.ts
+++ b/packages/e2b/e2b/tests/composition.e2e.ts
@@ -13,6 +13,7 @@ import {
 } from '@deepseek-ai/dsh-e2b'
 import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
 import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
 
@@ -51,10 +52,10 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         runtimeRoot: '/home/user/.dsh-e2b',
         getSandbox: async () => sandbox,
       } as never)
-      ctx.provide('sandboxPolicy', {
-        defaultMode: 'danger-full-access',
+      const sandboxPolicyFiber = await ctx.plugin(SandboxPolicyService, {
+        mode: 'danger-full-access',
         workspaceRoot: '/home/user',
-      } as never)
+      })
       const ptyFiber = await ctx.plugin(PtyService)
       const subprocessFiber = await ctx.plugin(E2BSubprocessService)
       const node = await ctx.subprocess.resolveExecutable('node')
@@ -114,6 +115,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
       await session.close('environment test complete')
       await subprocessFiber.dispose()
       await ptyFiber.dispose()
+      await sandboxPolicyFiber.dispose()
 
     } finally {
       await sandbox.kill().catch(() => false)
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fab00ba9cb..a92883786a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -3156,6 +3156,9 @@ importers:
       '@deepseek-ai/dsh-loader-smoke':
         specifier: workspace:^
         version: link:../../support/loader-smoke
+      '@deepseek-ai/dsh-sandbox-policy':
+        specifier: workspace:^
+        version: link:../../sandbox/sandbox-policy
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis

From 9c13a62702039e2f55c52f95fff02182e0b37af7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:37:46 +0800
Subject: [PATCH 399/516] fix(i18n): preserve merge conflicts without runtime

---
 ...matic-translation-pairing-merges.i18n.yaml |   4 +-
 ...08-automatic-translation-pairing-merges.md |  18 +-
 ...automatic-translation-pairing-merges.zh.md |  18 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +
 docs/development.zh.md                        |   2 +
 scripts/install-lefthook.mjs                  |  13 +-
 scripts/install-lefthook.spec.ts              |  27 ++-
 scripts/merge-translation-pairing-driver.sh   |  35 ++++
 scripts/merge-translation-pairing.ts          |  50 ++---
 scripts/translation-pairing-merge.spec.ts     | 195 +++++++++++++++++-
 scripts/translation-pairing-merge.ts          |  50 +++--
 12 files changed, 358 insertions(+), 60 deletions(-)
 create mode 100755 scripts/merge-translation-pairing-driver.sh

diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
index 7631476fb8..0c44f790b7 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.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 .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
-2026-08-08-automatic-translation-pairing-merges.md: e70864f1227fe11d7895dd85b0a99d166753a685
-2026-08-08-automatic-translation-pairing-merges.zh.md: 08da67d78e5cca23e3c5c698644c667813697812
+2026-08-08-automatic-translation-pairing-merges.md: ac4e0c11290abfd48d0f3caf037062aa2fe36c4d
+2026-08-08-automatic-translation-pairing-merges.zh.md: 38e8c0a5613a6bd0b3e76143a93c93653430d0c2
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
index e70864f122..ac4e0c1129 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
@@ -12,6 +12,8 @@ A bilingual consistency record contains the two owner files' exact blob hashes.
 
 `*.i18n.yaml` uses the repository-owned `dsh-translation-pairing` merge driver. The worktree-local Git installer registers its command alongside Lefthook setup; Git configuration remains local because a tracked attribute can name a driver but cannot carry its executable command.
 
+The installer loads the exact Node/tsx entrypoint before publishing worktree integration. Git invokes a checked-in shell launcher that does not require Node and repeats this probe before every driver execution. When the runtime or entrypoint is unavailable, the launcher materializes Git's ordinary three-way text result in the sidecar but returns a conflict even when that text merge is clean, so Git retains the unmerged index stages and never accepts unverified metadata.
+
 The driver parses the ancestor, current, and other records and loads the six owner blobs named by their hashes. It independently runs Git's default three-way text merge for the English and Chinese triplets, requires both merges to be clean, verifies language switchers and the pairing structural signature, stores the two merged blobs, and writes their hashes as the canonical record. This composes confirmations already present in both parents; it never records an ordinary one-sided documentation edit.
 
 The driver fails with an ordinary unresolved sidecar when a record is malformed, an object is missing, an owner uses another merge strategy (including a non-text `merge.default` inherited by an otherwise unspecified path), either owner has content conflicts, or the merged pair violates structural checks. Add/delete and rename shapes remain manual because their path ownership is not the same three-record operation.
@@ -20,9 +22,21 @@ The driver fails with an ordinary unresolved sidecar when a record is malformed,
 
 `pre-merge-commit` and `pre-commit` verify staged `.i18n.yaml` files against the exact index bytes of their owners. They validate driver output but do not regenerate records, so bypassing a hook cannot silently bless translation drift; the corpus-wide `doc-sync` check remains authoritative in CI.
 
+## Failure contract
+
+| Failure during a normal `git merge` | Observable state | Recovery |
+|---|---|---|
+| A fresh install cannot probe the driver or install Lefthook | No new driver or hook-path configuration is published; any newly added integration is rolled back to the previous hook lookup. | Restore the dependencies and rerun `node scripts/install-lefthook.mjs`. |
+| Node, tsx, or the driver entrypoint becomes unavailable after installation | The merge stops with the sidecar at `UU`, index stages 1/2/3 remain, the worktree sidecar contains Git's text result, `MERGE_HEAD` exists, and no commit is created. | Restore the dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. |
+| The repository-aware driver rejects the records | The merge stops with the sidecar unresolved and no commit; the driver prints the owner-repair and explicit-resolver path. | Repair the owner conflict or record, then run the printed resolver workflow or abort. |
+| The driver process crashes with a status above 128 | Git aborts the merge strategy without publishing `MERGE_HEAD` or unmerged index stages. | Repair the runtime and rerun the merge. |
+| `pre-merge-commit` rejects an otherwise clean file merge | No unmerged entries remain, the complete result is staged with `MERGE_HEAD`, and no merge commit is created. | Repair the hook failure and run `git commit`, or run `git merge --abort`. |
+
+An installer rollback failure reports both the original installation error and every rollback error. Because worktree configuration may then be partial, the contributor repairs or inspects it before merging instead of relying on a silent fallback.
+
 ## Verification
 
-Script tests exercise clean composition through a real custom-driver Git merge, explicit recovery from an unresolved index, mixed safe and owner-conflicted pairs, edited sidecars, non-text default merge configuration, record parsing, and worktree-local installation. The existing corpus verifier continues to prove that a committed record matches its two owners.
+Script tests exercise clean composition through the installed launcher, missing-runtime and broken-entrypoint text fallback, installer probe rollback, a rejecting `pre-merge-commit` hook, explicit recovery from an unresolved index, mixed safe and owner-conflicted pairs, edited sidecars, non-text default merge configuration, record parsing, and worktree-local installation. The existing corpus verifier continues to prove that a committed record matches its two owners.
 
 ## Alternatives considered
 
@@ -38,4 +52,4 @@ Script tests exercise clean composition through a real custom-driver Git merge,
 
 Installed worktrees automatically remove pairing-record-only conflicts while preserving human judgment for owner conflicts and translation quality. GitHub's hosted mergeability calculation does not run the worktree-local executable, so a contributor or agent must still merge the base and push the resulting commit before the remote conflict badge clears.
 
-The installer reserves `merge.dsh-translation-pairing.*` in worktree configuration and refuses a conflicting custom value. Merge execution depends on the installed Node dependencies, like the repository's contributor hooks; missing setup fails rather than selecting stale metadata.
+The installer reserves `merge.dsh-translation-pairing.*` in worktree configuration and refuses a conflicting custom value. Automatic composition depends on the installed Node dependencies, like the repository's contributor hooks; runtime loss produces a visible unresolved text result rather than selecting stale metadata.
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
index 08da67d78e..38e8c0a561 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
@@ -12,6 +12,8 @@ Status: implemented
 
 `*.i18n.yaml` 使用由仓库维护的 `dsh-translation-pairing` 合并驱动。worktree 本地的 Git 安装脚本在设置 Lefthook 的同时注册该驱动命令；Git 配置仍限定于当前 worktree，因为受跟踪的属性可以指定驱动，却无法携带其可执行命令。
 
+安装脚本会在发布 worktree 集成前加载确切的 Node/tsx 入口点。Git 会调用仓库内已提交且不依赖 Node 的 shell 启动器；该启动器会在每次执行驱动前重复这项探测。运行时或入口点不可用时，即使文本合并干净完成，启动器也会将 Git 的普通三方文本合并结果写入伴随文件并返回冲突状态，使 Git 保留未合并的索引阶段，绝不接受未经验证的元数据。
+
 驱动会解析祖先、当前和另一侧的记录，并加载其中 hash 指向的六个 Markdown blob。它分别对英文文档的三个 blob 与中文文档的三个 blob 运行 Git 默认的三方文本合并，要求两次合并都干净完成，校验语言切换行与配对结构签名，存储两个合并后的 blob，再将其 hash 写入规范记录。这一过程组合两个父提交中已经存在的确认；它绝不会为普通的单侧文档编辑写入记录。
 
 记录格式错误、对象缺失、配对文档采用其他合并策略（包括原本未单独指定策略的路径继承了非文本 `merge.default`）、任一配对文档存在内容冲突，或合并后的配对违反结构检查时，驱动会让伴随文件保持为普通的未解决冲突。新增、删除及重命名情形仍需手工处理，因为它们的路径归属关系无法由上述基于三份记录的操作处理。
@@ -20,9 +22,21 @@ Status: implemented
 
 `pre-merge-commit` 与 `pre-commit` 通过限定范围的配对检查，对照两侧文档在索引中的精确字节校验暂存的 `.i18n.yaml` 文件。这些钩子会验证驱动输出，但不会重新生成记录，因此绕过钩子也无法默默确认发生漂移的译文；CI 中全语料的 `doc-sync`（文档同步门禁）仍是权威检查。
 
+## 失败契约
+
+| 普通 `git merge` 期间的失败 | 可观察状态 | 恢复 |
+|---|---|---|
+| 全新安装无法探测驱动或安装 Lefthook | 不会发布新的驱动或钩子路径配置；任何新增集成都会回滚到原有的钩子查找方式。 | 恢复依赖并重新运行 `node scripts/install-lefthook.mjs`。 |
+| 安装后 Node、tsx 或驱动入口点变得不可用 | 合并停止，伴随文件状态为 `UU`；索引阶段 1/2/3 保留，worktree 中的伴随文件包含 Git 的文本结果，`MERGE_HEAD` 存在，且不创建提交。 | 恢复依赖并运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。 |
+| 了解仓库状态的驱动拒绝记录 | 合并停止，伴随文件保持未解决状态且不创建提交；驱动会打印修复配对文档和运行显式冲突解决命令的路径。 | 修复配对文档冲突或记录，然后运行打印出的冲突解决工作流，或中止合并。 |
+| 驱动进程以大于 128 的状态码崩溃 | Git 中止合并策略，既不写入 `MERGE_HEAD`，也不产生未合并的索引阶段。 | 修复运行时并重新执行合并。 |
+| `pre-merge-commit` 拒绝原本能干净完成的文件合并 | 不再有未合并条目，完整结果已暂存且 `MERGE_HEAD` 存在，但不会创建合并提交。 | 修复钩子失败并运行 `git commit`，或运行 `git merge --abort`。 |
+
+安装脚本回滚失败时，会同时报告最初的安装错误和每一项回滚错误。此时 worktree 配置可能只完成了一部分，因此贡献者会先修复或检查配置再执行合并，而不是依赖静默回退。
+
 ## 验证
 
-脚本测试通过一次使用真实自定义驱动的 Git 合并来覆盖无冲突组合，并覆盖从含未解决条目的索引中显式恢复、可安全解决的配对与配对文档冲突的配对并存、被编辑过的伴随文件、非文本默认合并配置、记录解析和 worktree 本地安装。既有的全语料校验器继续证明已提交的记录与两侧配对文档相符。
+脚本测试通过已安装的启动器覆盖无冲突组合，并覆盖运行时缺失与入口点损坏时的文本回退、安装脚本探测回滚、拒绝合并的 `pre-merge-commit` 钩子、从含未解决条目的索引中显式恢复、可安全解决的配对与配对文档冲突的配对并存、被编辑过的伴随文件、非文本默认合并配置、记录解析和 worktree 本地安装。既有的全语料校验器继续证明已提交的记录与两侧配对文档相符。
 
 ## 考虑过的替代方案
 
@@ -38,4 +52,4 @@ Status: implemented
 
 完成安装的 worktree 会自动消除仅由配对记录引起的冲突，同时仍由人工处理配对文档冲突并评判翻译质量。GitHub 托管的可合并性计算不会运行 worktree 本地的可执行命令，因此仍须由贡献者或 agent 将 base 分支合入当前分支并推送结果提交，远端冲突标记才会消失。
 
-安装脚本会在 worktree 配置中预留 `merge.dsh-translation-pairing.*`，并拒绝与之冲突的自定义值。与仓库贡献者钩子一样，合并过程依赖已安装的 Node 依赖；安装未完成时，合并会失败，而不是选择陈旧元数据。
+安装脚本会在 worktree 配置中预留 `merge.dsh-translation-pairing.*`，并拒绝与之冲突的自定义值。与仓库贡献者钩子一样，自动组合依赖已安装的 Node 依赖；运行时不可用时会产生可见的未解决文本结果，而不是选择陈旧元数据。
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 6397e9d97e..43f985604b 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: ad0447a0e121eaa31fb6e98502c6a55a9456d768
-development.zh.md: aef8b25d2115d00d5cfdb76b342a57662030feee
+development.md: 0032000e298ef49516d618e932258e79cf90e802
+development.zh.md: d681306e31991794519b62c3edbb6ca35ebc228b
diff --git a/docs/development.md b/docs/development.md
index ad0447a0e1..0032000e29 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -102,6 +102,8 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 The pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.
 
+The installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.
+
 lefthook is configured in `lefthook.yml` as a fast local checkpoint:
 
 - `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
diff --git a/docs/development.zh.md b/docs/development.zh.md
index aef8b25d21..d681306e31 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -102,6 +102,8 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
 
+安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。
+
 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
 - `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
diff --git a/scripts/install-lefthook.mjs b/scripts/install-lefthook.mjs
index b928582a8a..198f428b0a 100644
--- a/scripts/install-lefthook.mjs
+++ b/scripts/install-lefthook.mjs
@@ -31,9 +31,15 @@ const PAIRING_MERGE_DRIVER_CONFIG = [
   ['merge.dsh-translation-pairing.name', 'DeepSeek Harness bilingual pairing records'],
   [
     'merge.dsh-translation-pairing.driver',
-    'node --import tsx/esm scripts/merge-translation-pairing.ts %O %A %B %P',
+    'scripts/merge-translation-pairing-driver.sh %O %A %B %P',
   ],
 ]
+const PAIRING_MERGE_DRIVER_PROBE = [
+  '--import',
+  'tsx/esm',
+  'scripts/merge-translation-pairing.ts',
+  '--probe',
+]
 
 function errorCode(error) {
   return typeof error === 'object' && error !== null && 'code' in error
@@ -678,6 +684,10 @@ function installPairingMergeDriver(root, worktreeConfigPath) {
   }
 }
 
+function probePairingMergeDriver(root) {
+  capture(process.execPath, PAIRING_MERGE_DRIVER_PROBE, { cwd: root })
+}
+
 async function main() {
   if (process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true') return
   if (typeof lefthookPackage.bin?.lefthook !== 'string') return
@@ -767,6 +777,7 @@ async function main() {
     let pathChanged = false
     let rollbackPairingMergeDriver = () => {}
     try {
+      probePairingMergeDriver(root)
       rollbackPairingMergeDriver = installPairingMergeDriver(root, worktreeConfigPath)
       git(['config', '--worktree', 'core.hooksPath', hooksPath], root)
       pathChanged = worktreePath !== hooksPath
diff --git a/scripts/install-lefthook.spec.ts b/scripts/install-lefthook.spec.ts
index df9f1cd6d8..4d5b585213 100644
--- a/scripts/install-lefthook.spec.ts
+++ b/scripts/install-lefthook.spec.ts
@@ -18,7 +18,9 @@ import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 
 const installer = fileURLToPath(new URL('./install-lefthook.mjs', import.meta.url))
-const pairingMergeDriver = 'node --import tsx/esm scripts/merge-translation-pairing.ts %O %A %B %P'
+const pairingMergeDriver = 'scripts/merge-translation-pairing-driver.sh %O %A %B %P'
+const scriptsDirectory = fileURLToPath(new URL('.', import.meta.url))
+const tsxPackageDirectory = dirname(fileURLToPath(import.meta.resolve('tsx/package.json')))
 const fixtures: string[] = []
 // Multi-worktree cases spawn several Git and Node subprocesses; coverage concurrency can
 // legitimately exceed Vitest's default deadline without changing the installer behavior.
@@ -123,6 +125,12 @@ function installFakeLefthook(root: string): void {
   chmodSync(shim, 0o755)
 }
 
+function installPairingProbeFixture(root: string): void {
+  const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+  symlinkSync(scriptsDirectory, join(root, 'scripts'), linkType)
+  symlinkSync(tsxPackageDirectory, join(root, 'node_modules/tsx'), linkType)
+}
+
 function createFixture(names: { main?: string; linked?: string } = {}): Fixture {
   const container = mkdtempSync(join(tmpdir(), 'dsh-lefthook-'))
   fixtures.push(container)
@@ -152,6 +160,8 @@ function createFixture(names: { main?: string; linked?: string } = {}): Fixture
   write(join(linked, 'lefthook.yml'), 'linked-worktree-config\n')
   installFakeLefthook(main)
   installFakeLefthook(linked)
+  installPairingProbeFixture(main)
+  installPairingProbeFixture(linked)
   return fixture
 }
 
@@ -287,6 +297,7 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     git(fixture, fixture.main, ['worktree', 'add', '-b', 'late-linked', lateLinked])
     write(join(lateLinked, 'lefthook.yml'), 'late-linked-worktree-config\n')
     installFakeLefthook(lateLinked)
+    installPairingProbeFixture(lateLinked)
     expect(git(fixture, lateLinked, ['config', '--worktree', '--get', 'core.hooksPath'])).toBe(mainHooks)
 
     const linkedInstall = await runInstaller(fixture, lateLinked)
@@ -791,6 +802,20 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
     expect(readFileSync(legacyHook, 'utf8')).toBe('#!/bin/sh\n# legacy pre-push\n')
   })
 
+  it('does not publish worktree integration when the pairing driver probe fails', async () => {
+    const fixture = createFixture()
+    rmSync(join(fixture.main, 'node_modules/tsx'), { recursive: true, force: true })
+
+    const result = await runInstaller(fixture, fixture.main)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('merge-translation-pairing.ts --probe failed')
+    expect(gitResult(fixture, fixture.main, ['config', '--get', 'core.hooksPath']).status).toBe(1)
+    expect(gitResult(fixture, fixture.main, [
+      'config', '--get', 'merge.dsh-translation-pairing.driver',
+    ]).status).toBe(1)
+  })
+
   it('reports installation and hook-path rollback failures together', async () => {
     const fixture = createFixture()
 
diff --git a/scripts/merge-translation-pairing-driver.sh b/scripts/merge-translation-pairing-driver.sh
new file mode 100755
index 0000000000..c1fffaff20
--- /dev/null
+++ b/scripts/merge-translation-pairing-driver.sh
@@ -0,0 +1,35 @@
+#!/bin/sh
+
+if [ "$#" -ne 4 ]; then
+  echo 'merge-translation-pairing: expected <ancestor> <current> <other> <repository-path>' >&2
+  exit 129
+fi
+
+ancestor_path=$1
+current_path=$2
+other_path=$3
+meta_path=$4
+driver_directory=$(CDPATH= cd -P "$(dirname "$0")" && pwd) || exit 129
+driver_path=$driver_directory/merge-translation-pairing.ts
+
+if command -v node >/dev/null 2>&1 \
+  && node --import tsx/esm "$driver_path" --probe >/dev/null 2>&1; then
+  exec node --import tsx/esm "$driver_path" \
+    "$ancestor_path" "$current_path" "$other_path" "$meta_path"
+fi
+
+echo "merge-translation-pairing: runtime is unavailable; leaving an ordinary text conflict in $meta_path" >&2
+git merge-file \
+  -L "$meta_path:current" \
+  -L "$meta_path:ancestor" \
+  -L "$meta_path:other" \
+  -- "$current_path" "$ancestor_path" "$other_path"
+fallback_status=$?
+echo 'merge-translation-pairing: restore Node dependencies, then rerun the merge or `pnpm run resolve-translation-pairing-conflicts`; use `git merge --abort` to cancel' >&2
+
+# A clean text merge is still unverified pairing metadata, so the driver must
+# leave Git's index stages unresolved until the repository-aware resolver runs.
+if [ "$fallback_status" -gt 127 ]; then
+  exit "$fallback_status"
+fi
+exit 1
diff --git a/scripts/merge-translation-pairing.ts b/scripts/merge-translation-pairing.ts
index 30313d045a..dda2621a36 100644
--- a/scripts/merge-translation-pairing.ts
+++ b/scripts/merge-translation-pairing.ts
@@ -10,31 +10,35 @@ import {
 const args = process.argv.slice(2)
 
 try {
-  const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim()
-  if (args[0] === '--resolve') {
-    if (args.length !== 1) throw new Error('--resolve takes no paths; it inspects the unmerged index')
-    const resolved = resolveTranslationPairingConflicts(root)
-    if (resolved.length === 0) {
-      console.log('merge-translation-pairing: no unresolved pairing records')
-    } else {
-      for (const path of resolved) console.log(`merge-translation-pairing: resolved ${path}`)
-    }
+  if (args[0] === '--probe') {
+    if (args.length !== 1) throw new Error('--probe takes no other arguments')
   } else {
-    if (args.length !== 4) {
-      throw new Error('merge-driver mode requires <ancestor> <current> <other> <repository-path>')
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim()
+    if (args[0] === '--resolve') {
+      if (args.length !== 1) throw new Error('--resolve takes no paths; it inspects the unmerged index')
+      const resolved = resolveTranslationPairingConflicts(root)
+      if (resolved.length === 0) {
+        console.log('merge-translation-pairing: no unresolved pairing records')
+      } else {
+        for (const path of resolved) console.log(`merge-translation-pairing: resolved ${path}`)
+      }
+    } else {
+      if (args.length !== 4) {
+        throw new Error('merge-driver mode requires <ancestor> <current> <other> <repository-path>')
+      }
+      const [ancestorPath, currentPath, otherPath, metaPath] = args
+      if (ancestorPath === undefined || currentPath === undefined || otherPath === undefined || metaPath === undefined) {
+        throw new Error('merge-driver arguments are incomplete')
+      }
+      const result = mergeTranslationPairingRecords(
+        root,
+        metaPath,
+        readFileSync(ancestorPath, 'utf8'),
+        readFileSync(currentPath, 'utf8'),
+        readFileSync(otherPath, 'utf8'),
+      )
+      writeFileSync(currentPath, result.record)
     }
-    const [ancestorPath, currentPath, otherPath, metaPath] = args
-    if (ancestorPath === undefined || currentPath === undefined || otherPath === undefined || metaPath === undefined) {
-      throw new Error('merge-driver arguments are incomplete')
-    }
-    const result = mergeTranslationPairingRecords(
-      root,
-      metaPath,
-      readFileSync(ancestorPath, 'utf8'),
-      readFileSync(currentPath, 'utf8'),
-      readFileSync(otherPath, 'utf8'),
-    )
-    writeFileSync(currentPath, result.record)
   }
 } catch (error) {
   console.error(`merge-translation-pairing: ${error instanceof Error ? error.message : String(error)}`)
diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
index 6ddce4b30b..26f13748ed 100644
--- a/scripts/translation-pairing-merge.spec.ts
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -1,9 +1,9 @@
 /** Integration coverage for automatic and explicit pairing-record conflict resolution. */
 
 import { execFileSync, spawnSync } from 'node:child_process'
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { chmodSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
+import { delimiter, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts'
@@ -17,6 +17,8 @@ import {
 } from './translation-pairing-record.ts'
 
 const driver = fileURLToPath(new URL('./merge-translation-pairing.ts', import.meta.url))
+const driverLauncher = fileURLToPath(new URL('./merge-translation-pairing-driver.sh', import.meta.url))
+const workspaceRoot = fileURLToPath(new URL('../', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx/esm'))
 const fixtures: string[] = []
 
@@ -46,6 +48,16 @@ function shellQuote(value: string): string {
   return `"${value.replace(/["\\$`]/g, '\\$&')}"`
 }
 
+function installFixtureRuntime(root: string): void {
+  const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+  symlinkSync(
+    join(workspaceRoot, 'node_modules'),
+    join(root, 'node_modules'),
+    linkType,
+  )
+  symlinkSync(join(workspaceRoot, 'scripts'), join(root, 'scripts'), linkType)
+}
+
 function createFixture(attributes = true): Fixture {
   const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-merge-'))
   fixtures.push(root)
@@ -99,6 +111,17 @@ function commitPair(fixture: Fixture, source: string, zh: string, message: strin
   return sidecar
 }
 
+function commitTextCleanPair(fixture: Fixture, source: string, zh: string, message: string): void {
+  const sidecar = record(fixture.root, 'docs/guide.md', source, zh)
+  write(
+    fixture.root,
+    'docs/guide.i18n.yaml',
+    sidecar.replace('\nguide.zh.md:', '\n# Stable separator for independent line merges.\nguide.zh.md:'),
+  )
+  git(fixture, ['add', '.'])
+  git(fixture, ['commit', '-m', message])
+}
+
 function createDivergedPair(fixture: Fixture): { ancestor: string; current: string; other: string } {
   const ancestor = commitPair(fixture, baseSource, baseZh, 'base')
   git(fixture, ['switch', '-c', 'current'])
@@ -109,6 +132,15 @@ function createDivergedPair(fixture: Fixture): { ancestor: string; current: stri
   return { ancestor, current, other }
 }
 
+function createTextCleanDivergedPair(fixture: Fixture): void {
+  commitTextCleanPair(fixture, baseSource, baseZh, 'base')
+  git(fixture, ['switch', '-c', 'current'])
+  commitTextCleanPair(fixture, currentSource, baseZh, 'current source')
+  git(fixture, ['switch', 'master'])
+  commitTextCleanPair(fixture, baseSource, otherZh, 'other translation')
+  git(fixture, ['switch', 'current'])
+}
+
 function startStoppedPairingMerge(fixture: Fixture): void {
   createDivergedPair(fixture)
   const merge = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
@@ -279,13 +311,12 @@ describe('translation pairing merge composition', () => {
   it('runs as Git\'s custom driver and commits a clean composed record', () => {
     const fixture = createFixture()
     createDivergedPair(fixture)
-    const command = [
-      shellQuote(process.execPath),
-      '--import', shellQuote(tsxLoader),
-      shellQuote(driver),
-      '%O', '%A', '%B', '%P',
-    ].join(' ')
-    git(fixture, ['config', 'merge.dsh-translation-pairing.driver', command])
+    installFixtureRuntime(fixture.root)
+    git(fixture, [
+      'config',
+      'merge.dsh-translation-pairing.driver',
+      'scripts/merge-translation-pairing-driver.sh %O %A %B %P',
+    ])
 
     git(fixture, ['merge', '--no-edit', 'master'])
 
@@ -293,6 +324,152 @@ describe('translation pairing merge composition', () => {
     expectMergedPair(fixture)
   })
 
+  it('leaves an ordinary recoverable conflict when the configured runtime is unavailable', () => {
+    const fixture = createFixture()
+    const records = createDivergedPair(fixture)
+    const fakeBin = join(fixture.root, 'fake-bin')
+    const fakeNode = join(fakeBin, 'node')
+    write(fixture.root, 'fake-bin/node', '#!/bin/sh\nexit 72\n')
+    chmodSync(fakeNode, 0o755)
+    const command = [
+      shellQuote(driverLauncher),
+      '%O', '%A', '%B', '%P',
+    ].join(' ')
+    git(fixture, ['config', 'merge.dsh-translation-pairing.driver', command])
+    const headBefore = git(fixture, ['rev-parse', 'HEAD'])
+
+    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+      encoding: 'utf8',
+      env: {
+        ...fixture.env,
+        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
+      },
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('runtime is unavailable; leaving an ordinary text conflict')
+    expect(git(fixture, ['rev-parse', 'HEAD'])).toBe(headBefore)
+    expect(git(fixture, ['rev-parse', '--verify', 'MERGE_HEAD'])).not.toBe('')
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+    expect(git(fixture, ['ls-files', '--unmerged', '--', 'docs/guide.i18n.yaml']).split('\n')).toHaveLength(3)
+    const conflicted = readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')
+    expect(conflicted).toContain('<<<<<<< docs/guide.i18n.yaml:current')
+    for (const record of [records.current, records.other]) {
+      const dataLines = record.split('\n').filter(line => line !== '' && !line.startsWith('#')).join('\n')
+      expect(conflicted).toContain(dataLines)
+    }
+
+    expect(resolveTranslationPairingConflicts(fixture.root)).toEqual(['docs/guide.i18n.yaml'])
+    expectMergedPair(fixture)
+  })
+
+  it('falls back before a broken driver entrypoint can replace the launcher', () => {
+    const fixture = createFixture()
+    createDivergedPair(fixture)
+    const fakeBin = join(fixture.root, 'fake-bin')
+    const fakeNode = join(fakeBin, 'node')
+    write(
+      fixture.root,
+      'fake-bin/node',
+      '#!/bin/sh\nif [ "$3" = "--eval" ]; then exit 0; fi\nexit 72\n',
+    )
+    chmodSync(fakeNode, 0o755)
+    git(fixture, [
+      'config',
+      'merge.dsh-translation-pairing.driver',
+      `${shellQuote(driverLauncher)} %O %A %B %P`,
+    ])
+
+    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+      encoding: 'utf8',
+      env: {
+        ...fixture.env,
+        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
+      },
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('runtime is unavailable; leaving an ordinary text conflict')
+    expect(readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')).toContain(
+      '<<<<<<< docs/guide.i18n.yaml:current',
+    )
+  })
+
+  it('keeps a clean text fallback unresolved until the explicit resolver confirms it', () => {
+    const fixture = createFixture()
+    createTextCleanDivergedPair(fixture)
+    const fakeBin = join(fixture.root, 'fake-bin')
+    const fakeNode = join(fakeBin, 'node')
+    write(fixture.root, 'fake-bin/node', '#!/bin/sh\nexit 72\n')
+    chmodSync(fakeNode, 0o755)
+    git(fixture, [
+      'config',
+      'merge.dsh-translation-pairing.driver',
+      `${shellQuote(driverLauncher)} %O %A %B %P`,
+    ])
+
+    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+      encoding: 'utf8',
+      env: {
+        ...fixture.env,
+        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
+      },
+    })
+
+    expect(result.status).toBe(1)
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')
+    const canonicalRecord = renderTranslationPairingRecord(translationPairPaths('docs/guide.md'), {
+      sourceHash: gitBlobHash(Buffer.from(currentSource)),
+      zhHash: gitBlobHash(Buffer.from(otherZh)),
+    })
+    expect(readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')).toBe(
+      canonicalRecord.replace(
+        '\nguide.zh.md:',
+        '\n# Stable separator for independent line merges.\nguide.zh.md:',
+      ),
+    )
+
+    expect(resolveTranslationPairingConflicts(fixture.root)).toEqual(['docs/guide.i18n.yaml'])
+    expect(readFileSync(join(fixture.root, 'docs/guide.md'), 'utf8')).toBe(currentSource)
+    expect(readFileSync(join(fixture.root, 'docs/guide.zh.md'), 'utf8')).toBe(otherZh)
+    expect(readFileSync(join(fixture.root, 'docs/guide.i18n.yaml'), 'utf8')).toBe(canonicalRecord)
+  })
+
+  it('leaves a staged merge when the pre-merge-commit hook rejects it', () => {
+    const fixture = createFixture()
+    createDivergedPair(fixture)
+    installFixtureRuntime(fixture.root)
+    git(fixture, [
+      'config',
+      'merge.dsh-translation-pairing.driver',
+      'scripts/merge-translation-pairing-driver.sh %O %A %B %P',
+    ])
+    const hooks = join(fixture.root, 'hooks')
+    write(
+      fixture.root,
+      'hooks/pre-merge-commit',
+      '#!/bin/sh\necho "fixture pre-merge-commit rejection" >&2\nexit 77\n',
+    )
+    chmodSync(join(hooks, 'pre-merge-commit'), 0o755)
+    git(fixture, ['config', 'core.hooksPath', hooks])
+    const headBefore = git(fixture, ['rev-parse', 'HEAD'])
+
+    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-edit', 'master'], {
+      encoding: 'utf8',
+      env: fixture.env,
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('fixture pre-merge-commit rejection')
+    expect(git(fixture, ['rev-parse', 'HEAD'])).toBe(headBefore)
+    expect(git(fixture, ['rev-parse', '--verify', 'MERGE_HEAD'])).not.toBe('')
+    expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('')
+    expect(git(fixture, ['diff', '--cached', '--name-only']).split('\n')).toContain(
+      'docs/guide.i18n.yaml',
+    )
+    expectMergedPair(fixture)
+  })
+
   it('prints the recovery path when driver input is not composable', () => {
     const fixture = createFixture(false)
     const result = spawnSync(process.execPath, ['--import', tsxLoader, driver], {
diff --git a/scripts/translation-pairing-merge.ts b/scripts/translation-pairing-merge.ts
index 58b1be3fee..7c6d38469c 100644
--- a/scripts/translation-pairing-merge.ts
+++ b/scripts/translation-pairing-merge.ts
@@ -97,13 +97,13 @@ function assertDefaultTextMerge(root: string, paths: TranslationPairPaths): void
   }
 }
 
-function mergeBlobTriplet(
+function runTextMerge(
   root: string,
-  owner: string,
-  ancestor: Buffer,
-  current: Buffer,
-  other: Buffer,
-): Buffer {
+  label: string,
+  ancestor: Buffer | string,
+  current: Buffer | string,
+  other: Buffer | string,
+): { output: Buffer; status: number | null } {
   const temporary = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-merge-'))
   try {
     const ancestorPath = join(temporary, 'ancestor')
@@ -115,26 +115,37 @@ function mergeBlobTriplet(
     const result = spawnSync('git', [
       '-C', root,
       'merge-file', '-p',
-      '-L', `${owner}:current`,
-      '-L', `${owner}:ancestor`,
-      '-L', `${owner}:other`,
+      '-L', `${label}:current`,
+      '-L', `${label}:ancestor`,
+      '-L', `${label}:other`,
       currentPath, ancestorPath, otherPath,
     ], { maxBuffer: GIT_COMMAND_MAX_BUFFER })
     if (result.error) {
-      throw new Error(`merging ${owner} failed: ${result.error.message}`, { cause: result.error })
+      throw new Error(`merging ${label} failed: ${result.error.message}`, { cause: result.error })
     }
-    if (result.status !== 0) {
-      const kind = result.status !== null && result.status > 0 && result.status <= 127
-        ? 'has content conflicts'
-        : `failed with status ${String(result.status)}`
-      throw new Error(`${owner} ${kind}`)
-    }
-    return result.stdout
+    return { output: result.stdout, status: result.status }
   } finally {
     rmSync(temporary, { recursive: true, force: true })
   }
 }
 
+function mergeBlobTriplet(
+  root: string,
+  owner: string,
+  ancestor: Buffer,
+  current: Buffer,
+  other: Buffer,
+): Buffer {
+  const result = runTextMerge(root, owner, ancestor, current, other)
+  if (result.status !== 0) {
+    const kind = result.status !== null && result.status > 0 && result.status <= 127
+      ? 'has content conflicts'
+      : `failed with status ${String(result.status)}`
+    throw new Error(`${owner} ${kind}`)
+  }
+  return result.output
+}
+
 function loadRecordOwners(
   root: string,
   label: string,
@@ -243,11 +254,14 @@ function unmergedSidecars(root: string): Map<string, UnmergedStages> {
 function assertUneditedSidecar(
   root: string,
   metaPath: string,
+  ancestorRecord: string,
   currentRecord: string,
   otherRecord: string,
 ): void {
   const worktreeRecord = readFileSync(join(root, metaPath), 'utf8')
   if (worktreeRecord === currentRecord || worktreeRecord === otherRecord) return
+  const textMerge = runTextMerge(root, metaPath, ancestorRecord, currentRecord, otherRecord)
+  if (textMerge.status === 0 && textMerge.output.toString('utf8') === worktreeRecord) return
   const stageDataLines = [currentRecord, otherRecord]
     .flatMap(record => record.split(/\r?\n/))
     .filter(line => line !== '' && !line.startsWith('#'))
@@ -282,7 +296,7 @@ export function resolveTranslationPairingConflicts(root: string): string[] {
       const ancestorRecord = readGitBlob(root, stages.ancestor, `ancestor ${metaPath}`).toString('utf8')
       const currentRecord = readGitBlob(root, stages.current, `current ${metaPath}`).toString('utf8')
       const otherRecord = readGitBlob(root, stages.other, `other ${metaPath}`).toString('utf8')
-      assertUneditedSidecar(root, metaPath, currentRecord, otherRecord)
+      assertUneditedSidecar(root, metaPath, ancestorRecord, currentRecord, otherRecord)
       const result = mergeTranslationPairingRecords(
         root,
         metaPath,

From 58b89fb6b44654f5fedc496e4e5b3b325f17aae4 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:50:13 +0800
Subject: [PATCH 400/516] test(i18n): align merge failure fixtures

---
 .../request-response.expected.json            |  4 +-
 scripts/translation-pairing-merge.spec.ts     | 78 +++++++------------
 2 files changed, 28 insertions(+), 54 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 311b0ecc80..ec8c282b80 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
index 26f13748ed..118a2023b9 100644
--- a/scripts/translation-pairing-merge.spec.ts
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -58,6 +58,28 @@ function installFixtureRuntime(root: string): void {
   symlinkSync(join(workspaceRoot, 'scripts'), join(root, 'scripts'), linkType)
 }
 
+function startMergeWithFakeNode(
+  fixture: Fixture,
+  nodeScript = '#!/bin/sh\nexit 72\n',
+) {
+  const fakeBin = join(fixture.root, 'fake-bin')
+  const fakeNode = join(fakeBin, 'node')
+  write(fixture.root, 'fake-bin/node', nodeScript)
+  chmodSync(fakeNode, 0o755)
+  git(fixture, [
+    'config',
+    'merge.dsh-translation-pairing.driver',
+    `${shellQuote(driverLauncher)} %O %A %B %P`,
+  ])
+  return spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
+    encoding: 'utf8',
+    env: {
+      ...fixture.env,
+      PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
+    },
+  })
+}
+
 function createFixture(attributes = true): Fixture {
   const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-merge-'))
   fixtures.push(root)
@@ -327,24 +349,9 @@ describe('translation pairing merge composition', () => {
   it('leaves an ordinary recoverable conflict when the configured runtime is unavailable', () => {
     const fixture = createFixture()
     const records = createDivergedPair(fixture)
-    const fakeBin = join(fixture.root, 'fake-bin')
-    const fakeNode = join(fakeBin, 'node')
-    write(fixture.root, 'fake-bin/node', '#!/bin/sh\nexit 72\n')
-    chmodSync(fakeNode, 0o755)
-    const command = [
-      shellQuote(driverLauncher),
-      '%O', '%A', '%B', '%P',
-    ].join(' ')
-    git(fixture, ['config', 'merge.dsh-translation-pairing.driver', command])
     const headBefore = git(fixture, ['rev-parse', 'HEAD'])
 
-    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
-      encoding: 'utf8',
-      env: {
-        ...fixture.env,
-        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
-      },
-    })
+    const result = startMergeWithFakeNode(fixture)
 
     expect(result.status).toBe(1)
     expect(result.stderr).toContain('runtime is unavailable; leaving an ordinary text conflict')
@@ -366,27 +373,10 @@ describe('translation pairing merge composition', () => {
   it('falls back before a broken driver entrypoint can replace the launcher', () => {
     const fixture = createFixture()
     createDivergedPair(fixture)
-    const fakeBin = join(fixture.root, 'fake-bin')
-    const fakeNode = join(fakeBin, 'node')
-    write(
-      fixture.root,
-      'fake-bin/node',
+    const result = startMergeWithFakeNode(
+      fixture,
       '#!/bin/sh\nif [ "$3" = "--eval" ]; then exit 0; fi\nexit 72\n',
     )
-    chmodSync(fakeNode, 0o755)
-    git(fixture, [
-      'config',
-      'merge.dsh-translation-pairing.driver',
-      `${shellQuote(driverLauncher)} %O %A %B %P`,
-    ])
-
-    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
-      encoding: 'utf8',
-      env: {
-        ...fixture.env,
-        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
-      },
-    })
 
     expect(result.status).toBe(1)
     expect(result.stderr).toContain('runtime is unavailable; leaving an ordinary text conflict')
@@ -398,23 +388,7 @@ describe('translation pairing merge composition', () => {
   it('keeps a clean text fallback unresolved until the explicit resolver confirms it', () => {
     const fixture = createFixture()
     createTextCleanDivergedPair(fixture)
-    const fakeBin = join(fixture.root, 'fake-bin')
-    const fakeNode = join(fakeBin, 'node')
-    write(fixture.root, 'fake-bin/node', '#!/bin/sh\nexit 72\n')
-    chmodSync(fakeNode, 0o755)
-    git(fixture, [
-      'config',
-      'merge.dsh-translation-pairing.driver',
-      `${shellQuote(driverLauncher)} %O %A %B %P`,
-    ])
-
-    const result = spawnSync('git', ['-C', fixture.root, 'merge', '--no-commit', 'master'], {
-      encoding: 'utf8',
-      env: {
-        ...fixture.env,
-        PATH: `${fakeBin}${delimiter}${fixture.env.PATH ?? ''}`,
-      },
-    })
+    const result = startMergeWithFakeNode(fixture)
 
     expect(result.status).toBe(1)
     expect(git(fixture, ['diff', '--name-only', '--diff-filter=U'])).toBe('docs/guide.i18n.yaml')

From f34b2bb634b4959beb342b4cb6bdb38235b08a5c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:51:56 +0800
Subject: [PATCH 401/516] ci(e2b): add manual live sandbox workflow

---
 .github/workflows/e2b-e2e.yml | 58 +++++++++++++++++++++++++++++++++++
 scripts/ci-workflow.spec.ts   | 27 ++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 .github/workflows/e2b-e2e.yml

diff --git a/.github/workflows/e2b-e2e.yml b/.github/workflows/e2b-e2e.yml
new file mode 100644
index 0000000000..abbd0482ed
--- /dev/null
+++ b/.github/workflows/e2b-e2e.yml
@@ -0,0 +1,58 @@
+name: E2E (E2B sandbox)
+
+# This suite provisions external E2B sandboxes and is intentionally opt-in.
+# It has no push, pull_request, schedule, or workflow_call trigger.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  # CI runs must never report to the production telemetry endpoint baked
+  # into apps/cli/cordis.yml (AppCLIEntry disables the row when set).
+  DSH_TELEMETRY_DISABLED: '1'
+
+jobs:
+  e2b:
+    runs-on: ubuntu-latest
+    name: E2B live Loader composition
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install (immutable)
+        run: pnpm install --frozen-lockfile
+
+      # The tests self-skip locally when the credential is absent. A manually
+      # dispatched run must fail instead of reporting an all-skipped green.
+      - name: Preflight (require E2B API key)
+        env:
+          E2B_API_KEY: ${{ secrets.E2B_API_KEY_EXTERNAL }}
+        run: |
+          set -euo pipefail
+          if [ -z "${E2B_API_KEY:-}" ]; then
+            echo "::error::E2B_API_KEY is empty. Configure the E2B_API_KEY_EXTERNAL repository secret."
+            exit 1
+          fi
+          echo "E2B_API_KEY present."
+
+      # The Loader smoke runs package exports under plain Node in lib mode.
+      - name: Build (lib for the E2B Loader smoke)
+        run: pnpm run build
+
+      - name: E2B tests (live sandbox)
+        env:
+          E2B_API_KEY: ${{ secrets.E2B_API_KEY_EXTERNAL }}
+          DSH_E2E_MAX_WORKERS: '1'
+          DSH_EXAMPLE_MODE: lib
+        run: >-
+          pnpm exec vitest run --config vitest.e2e.config.ts
+          packages/e2b/e2b/tests/composition.e2e.ts
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index baeac7a8c0..0395fe8c36 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -28,6 +28,33 @@ describe('CI workflow', () => {
   })
 })
 
+describe('E2B e2e workflow', () => {
+  it('is manual-only and fails loud before running the focused live suite', () => {
+    const workflow = loadWorkflow('.github/workflows/e2b-e2e.yml')
+    expect(workflow.on).toEqual({ workflow_dispatch: null })
+    if (!isRecord(workflow.jobs) || !isRecord(workflow.jobs.e2b) || !Array.isArray(workflow.jobs.e2b.steps)) {
+      throw new TypeError('E2B e2e workflow must define the e2b job steps')
+    }
+
+    const steps = workflow.jobs.e2b.steps.filter(isRecord)
+    const preflight = steps.find(step => step.name === 'Preflight (require E2B API key)')
+    const e2b = steps.find(step => step.name === 'E2B tests (live sandbox)')
+
+    expect(preflight).toMatchObject({
+      env: { E2B_API_KEY: '${{ secrets.E2B_API_KEY_EXTERNAL }}' },
+    })
+    expect(preflight?.run).toContain('E2B_API_KEY_EXTERNAL repository secret')
+    expect(e2b).toMatchObject({
+      env: {
+        E2B_API_KEY: '${{ secrets.E2B_API_KEY_EXTERNAL }}',
+        DSH_E2E_MAX_WORKERS: '1',
+        DSH_EXAMPLE_MODE: 'lib',
+      },
+    })
+    expect(e2b?.run).toContain('packages/e2b/e2b/tests/composition.e2e.ts')
+  })
+})
+
 describe('Issue lifecycle workflow', () => {
   it('uses review signals instead of rerunning when a draft becomes ready', () => {
     const lifecycle = loadWorkflow('.github/workflows/issue-lifecycle.yml')

From 645fcf57137a82000f115aaabb7500b8682d6391 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 00:53:05 +0800
Subject: [PATCH 402/516] docs(agent-note): propose packages/ regrouping by
 measured clustering

RFC settling the target group map: fold the session family into one
session/ group, dissolve ui/ into interaction/ (+tui), boot/, and the
scaffold/ developer-tooling family (absorbing jsonrpc as server),
merge timeout/ into guard/, and rename cordis/ to self-modification/.
Zero npm renames now; five FIXME-tracked intended renames. Squash of
the reviewed RFC iterations (turtle1999 map corrections applied).
---
 .../2026-07-29-package-regrouping.i18n.yaml   |   6 +
 .../2026-07-29-package-regrouping.md          | 106 ++++++++++++++++++
 .../2026-07-29-package-regrouping.zh.md       | 106 ++++++++++++++++++
 3 files changed, 218 insertions(+)
 create mode 100644 .agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml
 create mode 100644 .agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
 create mode 100644 .agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md

diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml
new file mode 100644
index 0000000000..cdd772386f
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.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/proposed/architecture/2026-07-29-package-regrouping.md
+2026-07-29-package-regrouping.md: 9a56f9f5f1e0aef7d1f9efe60168ec1b0f41cce8
+2026-07-29-package-regrouping.zh.md: c49c5a1daffaff599f70f36b62e4dd3b5de3e5cf
diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
new file mode 100644
index 0000000000..9a56f9f5f1
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
@@ -0,0 +1,106 @@
+# Agent Note: Regroup packages/ by measured clustering
+
+Status: proposed
+
+English | [中文](2026-07-29-package-regrouping.zh.md)
+
+## Problem
+
+The two-level `packages/<group>/<pkg>` hierarchy ([original decision](../../archived/architecture/2026-06-20-package-hierarchy.md)) has drifted since June: 167 packages now sit in 40 groups, and several group boundaries no longer match how the packages actually cluster.
+
+- `ui/` mixes four unrelated planes: the human terminal channel (`tui`), the SDK's JSON-RPC server half (`jsonrpc`, whose peer dependency on `dsh-sdk-protocol` binds it to the `sdk/` stack), the human-interaction seams (`user-interaction`, `user-approval`, `permission`, `tool-ask-user`, `commands`), and channel-neutral boot glue (`app-boot`). Its own README narrates the mixture instead of stating a role.
+- The session family is fragmented across five groups — `session-persistence/`, `session-projection/`, `session-query/`, `session-title/`, and `telemetry/` — although the measured dependency edges tie them together (query → persistence, title → projection, projection → persistence; see [docs/module-graph.md](../../../../docs/module-graph.md)).
+- Two group names collide with unrelated packages: `telemetry/` (session reporting) vs `sdk/telemetry` = `dsh-telemetry` (launcher-side SDK telemetry), and `timeout/` (a tool-call guard) vs `util/timeout` (the generic promise utility).
+- `cordis/` names its group after the framework every package is built on, so the name discriminates nothing; its single package `tool-cordis` is the runtime self-modification toolset.
+- `sdk/` folder names are inconsistent: `sdk/sdk-client` and `sdk/sdk-protocol` repeat the group name while `sdk/telemetry`, `sdk/helper`, and `sdk/scripts` do not.
+
+The north star for the regrouping: **closely clustered packages share a group.** A cluster is measured — peer-dependency edges and co-change — not thematic. An isolated seam family may stand alone as a small group; the failure mode to avoid is the grab-bag whose name describes no single role.
+
+## Proposal
+
+Recompose six groups; every other group keeps today's boundary and contents (the dependency analysis confirmed the capability families — `bash/`, `pty/`, `code-runtime/`, `sandbox/`, `subprocess/`, `fs/`, `lsp/`, `web/`, `skill/`, and the rest — were already drawn correctly). npm package names do not change in this reorganization; the folder tree carries the whole change.
+
+| Group | Members (folder names) | From |
+|---|---|---|
+| `session/` | session-persistence, session-persistence-jsonl, session-persistence-sqlite, session-checkpoint-policy, session-projection, session-projection-cache, session-title, session-title-llm, session-title-first-message-llm, session-title-all-messages-llm, session-telemetry, session-telemetry-otel | `session-persistence/` + `session-projection/` + `session-title/` + `telemetry/` |
+| `interaction/` | user-interaction, user-approval, permission, tool-ask-user, commands, tui | `ui/` |
+| `boot/` | app-boot | `ui/` |
+| `scaffold/` | helper, scripts, create-sdk, protocol, client, server, telemetry | `sdk/` + `ui/jsonrpc` |
+| `guard/` | repeat-tool-guard, timeout-policy | `guard/` + `timeout/` |
+| `self-modification/` | tool-cordis | `cordis/` |
+
+- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (review: prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ends the group-name collision with `dsh-telemetry`.
+- **`interaction/`** is the human-collaboration plane plus the terminal channel that answers it: the question/approval seams, the permission preset, the model-facing `ask_user_question` tool, the human-command registry (`plan-mode` and `command-goal` already consume `commands` together with the interaction seams), and `tui` — the interactive channel is the plane's richest provider and consumer (peer edges to `commands` and `user-interaction`), and a one-package `tui/` group would spend a top-level name on one plugin.
+- **`boot/`** is a role-complete single-package group: the shared bin boot glue that belongs to no channel and no assembly (consumed by `apps/cli`, the `scaffold/` launcher, and the `examples/` demo bins).
+- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is today's `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/` in review: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it says nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style.
+- **`guard/`** keeps its documented role, loop-hygiene guards, and gains the tool-call timeout enforcer, dissolving the one-package `timeout/` group whose name collided with `util/timeout`.
+- **`self-modification/`** names the role `cordis/` obscured: the toolset with which the agent inspects and mounts plugins in its own live runtime, and the landing zone for future self-modification packages.
+
+40 groups become 37; the win is clustering correctness and truthful names, not count.
+
+## Deferred renames (FIXME markers)
+
+Five npm names should eventually change, but renaming inside the reorganization would turn a pure-move PR into an import-churn PR. Instead, the implementation adds a `FIXME` to each affected package's module JSDoc naming the intended new name. `FIXME` blocks a tagged release ([marker semantics](../../../../docs/development.md)), which is the wanted forcing function: these renames are only free while nothing external consumes the packages.
+
+| Current npm name | Intended name | Why |
+|---|---|---|
+| `@deepseek-ai/dsh-jsonrpc` | `@deepseek-ai/dsh-sdk-server` | Names the wire encoding, not the role; it is the server half of the SDK protocol |
+| `@deepseek-ai/dsh-telemetry` | `@deepseek-ai/dsh-sdk-telemetry` | Collides with the `dsh-session-telemetry` family; it is launcher-side SDK telemetry |
+| `@deepseek-ai/dsh-helper` | `@deepseek-ai/dsh-sdk-helper` | Indefensibly generic as a published name |
+| `@deepseek-ai/dsh-scripts` | `@deepseek-ai/dsh-sdk-scripts` | Same |
+| `@deepseek-ai/dsh-timeout-policy` | `@deepseek-ai/dsh-timeout-guard` | Suggestion, not settled: aligns the name with its `guard/` home; decide at resolution time |
+
+The first four are settled intent; resolving them converges the SDK wire stack's npm names on `dsh-sdk-*` (the npm prefix names the product stack; the `scaffold/` folder names the role). `@deepseek-ai/create-sdk` keeps its documented npm-initializer exception.
+
+## Implementation
+
+One mechanical PR, landed in a quiet window: a single conflict event for the many open PRs, an atomic documentation update, and pure-move reviewability (`git mv` + path fixes, rename detection intact). If review prefers, the same content splits into a three-PR stack (the session fold; `ui/` dissolution + `scaffold/`; `self-modification/` + `guard/` merge), at the cost of three rebase events for everyone else.
+
+A group move touches: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose (root and `apps/cli` READMEs, 7 script files + 22 docs files measured today; `verify-package-paths` gates the Markdown/TypeScript classes of stragglers). This list conveys the shape of the change, not a file inventory: every remaining group-path referent (workspace configs, test globs, lint keys) is found mechanically at implementation time by the acceptance gates failing loud, which is the repository's own misconfiguration rule.
+
+A group move does not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name (verified by grep before this proposal). Each FIXME lands in the same PR as the move that creates its context.
+
+`client/` and `host/` are out of scope and unchanged. The in-flight `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision; the only interaction is a trivial merge in the packages/README.md table.
+
+## Alternatives considered
+
+**Coarse domain buckets** (`exec/` = subprocess+sandbox+bash+pty+code-runtime, `workspace/` = fs+lsp+workspace, `orchestration/` = subagent+workflow+tasks, `knowledge/` = web+skill, `collab/` = plan+todo+goal; ~16 groups). Rejected: the measured graph contradicts the merges. `sandbox` and `subprocess` are shared infrastructure consumed across families (bash ×5, fs ×5, pty, lsp, mcp, subagent, sdk edges), `web` ↔ `skill` have zero edges, and a large bucket reproduces the `ui/` grab-bag at a larger scale.
+
+**Abstract layer names** (`capability/`, `policy/`, `extension/`, `provider/`). Rejected: they describe every plugin equally badly, and a `capability/` bucket would hold ~50 packages.
+
+**A full npm rename sweep** (`dsh-<group>-<pkg>` for every package). Rejected: npm names are flat, so group-prefixing adds churn across imports, configs, and fixtures with no disambiguation gain; targeted FIXME-tracked renames cover the actual collisions.
+
+**Performing the five renames inside the reorganization.** Rejected in review: renames multiply open-PR conflicts and destroy the pure-move review property. The FIXME markers keep them visible release blockers to resolve as small follow-up PRs.
+
+**A two-way session split** (`session-core/` + `session-utils/`). Rejected: query belongs to neither side cleanly, and `session-core` invites confusion with `core/session` (`dsh-session`, the live in-memory service, which stays in `core/`).
+
+**A three-way session split** (`session-store/` + `session-query/` + `session-utils/`), this RFC's first draft. Rejected in review: `session-utils/` was a negatively-defined annex ("derived, nothing load-bearing depends on it") — the grab-bag shape the north star forbids, and factually wrong besides (`session-query` peer-depends on `dsh-session-title`). The invented compound names also read machine-generated; one plain `session/` group says what a human would say. Query stays standalone in both drafts: it is an independently consumed read surface with its own tool package and backend.
+
+**Recomposing `ui/` as a single `channels/` group** (tui + jsonrpc + acp + interaction seams + boot). Rejected: the same grab-bag under a new name — those packages serve four planes, `jsonrpc`'s measured cluster is the SDK wire stack, and `acp/` is an automation transport, not a human channel.
+
+**A standalone one-package `tui/` group**, this RFC's first draft. Rejected in review: `tui` is the interaction plane's primary provider/consumer (peer edges to `commands`, `user-interaction`), and a top-level name spent on one plugin adds a group without adding information; it folds into `interaction/`.
+
+**Keeping the group name `sdk/`.** Rejected in review: the whole `packages/` tree is the SDK, so an `sdk/` group inside it discriminates nothing — the same disease as `cordis/`. `scaffold/` names the actual role (create, launch, and drive projects from outside).
+
+**Moving `app-boot` to `apps/`** (review question). Rejected: `apps/` is the assembly tier over the package tier, and `dsh-app-boot` is a library that package-tier code imports (`scaffold/scripts`' launcher peer-depends on it) — placing it in `apps/` would invert the tiers and put a workspace library outside the `packages/*/*` build globs. It stays a package; `boot/` is its role-complete home.
+
+**Moving `tool-cordis` into `core/`.** Rejected: self-modification is its own product seam, expected to grow; the spine stays minimal. The group was first named `self-evolve/`; review settled on `self-modification/` as the plainer term.
+
+**Renaming `context/` to `request-context/`.** Rejected: within this tree the group is unambiguous in situ; the churn is unjustified.
+
+## Acceptance criteria
+
+- The tree matches the map: the six recomposed groups hold exactly the listed members; the groups `ui/`, `sdk/`, `telemetry/`, `timeout/`, `cordis/`, `session-persistence/`, `session-projection/`, and `session-title/` no longer exist; every other group's contents are unchanged.
+- Zero npm renames: the workspace package-name set is identical before and after.
+- The five FIXME markers are present, each naming its intended new name.
+- New and updated group READMEs form complete bilingual triplets; the packages/README.md hierarchy table matches the tree; docs/module-graph.md is regenerated.
+- `pnpm run typecheck`, `pnpm run test`, `pnpm run doc-sync`, and `pnpm run hygiene` pass, and the unit/snapshot suites collect the same test files before and after the move (group-scoped globs in test configs must not silently match nothing).
+
+## Risks
+
+- **Open-PR conflicts.** Every open PR touching a moved file must rebase across the move. Mitigated by landing as one PR in a quiet window, publishing the mapping table in the PR body, and the moves being pure renames (rename detection resolves most hunks mechanically).
+- **Reference drift.** Docs or scripts citing old paths can go stale; `verify-package-paths` exists precisely for moved-package drift and runs in `doc-sync`.
+- **Translation load.** Five new group README triplets plus edits to existing pairs land in the implementation PR.
+- **Deferred renames are release blockers by design.** A FIXME that later proves wrong must be removed explicitly with rationale, never silently dropped.
+- **Single-package groups remain** (`boot/`, `self-modification/`, and existing ones such as `acp/`). Accepted deliberately: each is role-complete rather than a fragment of a family, and a truthful small group beats a nominal merge.
+- **What this gives up:** nothing functional — the change is navigational. Muscle memory and external links to old GitHub paths break, which is acceptable pre-release with no external consumers.
diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md
new file mode 100644
index 0000000000..c49c5a1daf
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md
@@ -0,0 +1,106 @@
+# Agent Note: 按实测聚类重新划分 packages/ 分组
+
+Status: proposed
+
+[English](2026-07-29-package-regrouping.md) | 中文
+
+## Problem
+
+两级 `packages/<group>/<pkg>` 层级结构（[原始决策](../../archived/architecture/2026-06-20-package-hierarchy.md)）自 6 月以来已经漂移：167 个包（package）如今坐落在 40 个组里，若干组边界已经对不上这些包的实际聚类。
+
+- `ui/` 混杂了四个互不相关的平面：人类终端通道（`tui`）、SDK 的 JSON-RPC 服务端一半（`jsonrpc`，它对 `dsh-sdk-protocol` 的对等依赖（peer dependency）把它绑在 `sdk/` 这一栈上）、人机交互 seam（`user-interaction`、`user-approval`、`permission`、`tool-ask-user`、`commands`），以及与通道无关的 boot 胶水（`app-boot`）。它自己的 README 只能逐一叙述这堆混杂，说不出一个统一职责。
+- 会话家族被割裂在五个组里——`session-persistence/`、`session-projection/`、`session-query/`、`session-title/` 与 `telemetry/`——而实测依赖边明明把它们连成一体（query → persistence、title → projection、projection → persistence；见 [docs/module-graph.md](../../../../docs/module-graph.md)）。
+- 两个组名与不相干的包撞名：`telemetry/`（会话上报）撞上 `sdk/telemetry` = `dsh-telemetry`（启动器侧 SDK telemetry），`timeout/`（一个工具调用守卫）撞上 `util/timeout`（通用 promise 工具）。
+- `cordis/` 拿所有包共同依托的框架给自己的组命名，这个名字因此毫无区分度；组里唯一的包 `tool-cordis` 是运行时自我修改工具集。
+- `sdk/` 的目录命名不一致：`sdk/sdk-client` 和 `sdk/sdk-protocol` 重复了组名，而 `sdk/telemetry`、`sdk/helper`、`sdk/scripts` 没有。
+
+这次重新分组的指导准则：**聚类紧密的包同处一组。**聚类以实测为准（对等依赖边与 co-change），而非按主题归类。孤立的 seam 家族可以自成一个小组；要避免的失败形态，是名字概括不出单一职责的大杂烩组。
+
+## Proposal
+
+重组六个组；其余每个组都保持今天的边界与内容不变（依赖分析确认各能力家族——`bash/`、`pty/`、`code-runtime/`、`sandbox/`、`subprocess/`、`fs/`、`lsp/`、`web/`、`skill/` 及其余——本来就划得正确）。这次重组不改任何 npm 包名；整个变更全部由目录树承载。
+
+| 组 | 成员（目录名） | 来源 |
+|---|---|---|
+| `session/` | session-persistence、session-persistence-jsonl、session-persistence-sqlite、session-checkpoint-policy、session-projection、session-projection-cache、session-title、session-title-llm、session-title-first-message-llm、session-title-all-messages-llm、session-telemetry、session-telemetry-otel | `session-persistence/` + `session-projection/` + `session-title/` + `telemetry/` |
+| `interaction/` | user-interaction、user-approval、permission、tool-ask-user、commands、tui | `ui/` |
+| `boot/` | app-boot | `ui/` |
+| `scaffold/` | helper、scripts、create-sdk、protocol、client、server、telemetry | `sdk/` + `ui/jsonrpc` |
+| `guard/` | repeat-tool-guard、timeout-policy | `guard/` + `timeout/` |
+| `self-modification/` | tool-cordis | `cordis/` |
+
+- **`session/`** 是持久会话数据平面：持久化 seam 连同其各后端与检查点策略、从该日志折叠（fold）出全量值对外供值的投影、日志兜底的标题，以及 OTel 上报。标题折叠本身就是读取侧的承重构件（`session-query` 对 `dsh-session-title` 声明对等依赖），所以标题属于数据平面，而非某个「派生服务」附属区。用这个朴素的名字是有意为之（评审意见：名字要像人起的）；旁边的 `core/session` 包仍是常驻内存的实时服务，本组则是围绕它的持久家族。`session-query/` 保持独立成组：这个读取／工具面自带模型工具和 SQLite FTS 后端，其消费不依赖持久化内部实现。吸收 `telemetry/` 之后，与 `dsh-telemetry` 的组名冲突就此终结。
+- **`interaction/`** 是人机协作平面加上应答它的终端通道：提问／批准 seam、权限预设、面向模型的 `ask_user_question` 工具、人类命令注册表（`plan-mode` 与 `command-goal` 已经把 `commands` 和各交互 seam 放在一起消费），以及 `tui`——这个交互通道是该平面最重的提供方与消费方（对 `commands` 与 `user-interaction` 均有对等依赖边），而一个单包 `tui/` 组会把一个顶层名字花在一个插件上。
+- **`boot/`** 是角色完备的单包组：不归属任何通道也不归属任何组装的共享 bin boot 胶水（被 `apps/cli`、`scaffold/` 的启动器和 `examples/` 各演示 bin 消费）。
+- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即今天的 `ui/jsonrpc`），以及启动器侧 telemetry。评审中从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致。
+- **`guard/`** 保留其文档记载的角色（循环卫生守卫），并新纳入强制执行工具调用超时的包；那个与 `util/timeout` 撞名的单包组 `timeout/` 随之解散。
+- **`self-modification/`** 把 `cordis/` 遮蔽掉的角色说了出来：它是 agent（智能体）检查并挂载自身实时运行时中插件所用的工具集，也是未来自我修改类包的落点。
+
+40 个组变为 37 个；收益在聚类正确与名实相符，不在数量增减。
+
+## Deferred renames (FIXME markers)
+
+五个 npm 名最终应当改掉，但在这次重组内部改名，会把一个纯移动的 PR（Pull Request）变成大量翻改 import 的 PR。实现改为在每个受影响包的模块 JSDoc 里加一条 `FIXME`，写明意图中的新名字。`FIXME` 会阻塞打 tag 的发布（[标记语义](../../../../docs/development.md)），这正是想要的倒逼机制：只有趁还没有外部消费方使用这些包时，这些改名才是零成本的。
+
+| 当前 npm 名 | 目标名 | 原因 |
+|---|---|---|
+| `@deepseek-ai/dsh-jsonrpc` | `@deepseek-ai/dsh-sdk-server` | 名字说的是协议编码而非角色；它是 SDK 协议的服务端一半 |
+| `@deepseek-ai/dsh-telemetry` | `@deepseek-ai/dsh-sdk-telemetry` | 与 `dsh-session-telemetry` 家族撞名；它是启动器侧 SDK telemetry |
+| `@deepseek-ai/dsh-helper` | `@deepseek-ai/dsh-sdk-helper` | 作为公开发布名空泛得站不住脚 |
+| `@deepseek-ai/dsh-scripts` | `@deepseek-ai/dsh-sdk-scripts` | 同上 |
+| `@deepseek-ai/dsh-timeout-policy` | `@deepseek-ai/dsh-timeout-guard` | 仅为建议、尚未定案：使名字与其 `guard/` 归属对齐；到解决时再定 |
+
+前四个是已定的意图；兑现之后，SDK 通信栈的 npm 名随之收敛为 `dsh-sdk-*`（npm 前缀指产品栈，`scaffold/` 目录名指角色）。`@deepseek-ai/create-sdk` 保留其文档记载的 npm 初始化器特例。
+
+## Implementation
+
+整个变更作为一个机械化 PR，在低活动窗口期合入：众多开放中的 PR 只经历一次冲突事件，文档得到一次原子更新，评审享有纯移动的可评审性（`git mv` 加路径修正，重命名检测完好）。若评审偏好拆分，同样的内容也可以拆成三个 PR 的堆叠（会话折叠；`ui/` 解散加 `scaffold/`；`self-modification/` 加 `guard/` 合并），代价是其他所有人要经历三次变基事件。
+
+组移动会触及：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文中以仓库根为基准的 `packages/...` 引用（根 README 与 `apps/cli` README、今天实测 7 个脚本文件加 22 个文档文件；`verify-package-paths` 兜住 Markdown／TypeScript 这两类漏网引用）。这份清单陈述的是变更的形态，不是文件清点：其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都在实现时由验收门禁的响亮失败机械地找出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
+
+组移动不触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包（提案之前已用 grep 核实）。每条 FIXME 都与创造其上下文的那次移动落在同一个 PR。
+
+`client/` 与 `host/` 不在本次范围内，保持不变。在途的 `experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策；两者唯一的交集是 packages/README.md 表格里一次很小的合并。
+
+## Alternatives considered
+
+**粗粒度领域桶**（`exec/` = subprocess+sandbox+bash+pty+code-runtime，`workspace/` = fs+lsp+workspace，`orchestration/` = subagent+workflow+tasks，`knowledge/` = web+skill，`collab/` = plan+todo+goal；约 16 个组）。不予采纳：实测依赖图与这些合并相矛盾。`sandbox` 和 `subprocess` 是被各家族跨界消费的共享基础设施（与 bash ×5、fs ×5、pty、lsp、mcp、subagent、sdk 均有依赖边），`web` ↔ `skill` 之间零依赖边，而大桶只会在更大尺度上复现 `ui/` 式大杂烩。
+
+**抽象分层名**（`capability/`、`policy/`、`extension/`、`provider/`）。不予采纳：这些名字对每个插件都同样地不达意，而且一个 `capability/` 桶会装下约 50 个包。
+
+**一轮全量 npm 重命名**（每个包都改为 `dsh-<group>-<pkg>`）。不予采纳：npm 包名是扁平的，加组前缀只会在 import、配置和 fixture 之间制造改动，却换不来任何消歧收益；用 FIXME 跟踪的定点改名足以覆盖真正的撞名。
+
+**在重组内部一并完成那五个改名。** 评审中否决：改名会成倍放大开放 PR 的冲突，并破坏纯移动的评审属性。FIXME 标记让这些改名保持为可见的发布阻塞项，留待以小型后续 PR 逐一解决。
+
+**会话两分法**（`session-core/` + `session-utils/`）。不予采纳：query 放哪一侧都不干净，而且 `session-core` 容易与 `core/session` 混淆（后者是 `dsh-session`，常驻内存的实时服务，留在 `core/` 不动）。
+
+**会话三分法**（`session-store/` + `session-query/` + `session-utils/`），即本 RFC 的初稿。评审中否决：`session-utils/` 是靠否定条件圈出来的附属区（「派生的、没有承重方依赖」）——正是指导准则禁止的大杂烩形态，而且事实层面也站不住（`session-query` 对 `dsh-session-title` 声明对等依赖）。杜撰的复合名也读起来不像人起的；一个朴素的 `session/` 组说的就是人会说的话。query 在两版草稿中都保持独立：它是被独立消费的读取面，自带自己的工具包与后端。
+
+**把 `ui/` 重组为单一 `channels/` 组**（tui + jsonrpc + acp + 交互 seam + boot）。不予采纳：不过是换个名字的同一个大杂烩——这些包服务于四个平面，`jsonrpc` 的实测聚类归属是 SDK 通信栈，而 `acp/` 是自动化传输通道，不是人类通道。
+
+**独立的单包 `tui/` 组**，即本 RFC 的初稿。评审中否决：`tui` 是交互平面最重的提供方／消费方（对 `commands`、`user-interaction` 有对等依赖边），把一个顶层名字花在一个插件上只添组不添信息；它折入 `interaction/`。
+
+**保留组名 `sdk/`。** 评审中否决：整个 `packages/` 树本身就是 SDK，树里的 `sdk/` 组毫无区分度——与 `cordis/` 同病。`scaffold/` 说出了实际角色（从外部创建、启动、驱动项目）。
+
+**把 `app-boot` 挪到 `apps/`**（评审提问）。不予采纳：`apps/` 是包层之上的组装层，而 `dsh-app-boot` 是被包层代码 import 的库（`scaffold/scripts` 的启动器对它声明对等依赖）——放进 `apps/` 会颠倒层级，并把一个 workspace 库放到 `packages/*/*` 构建 glob 之外。它仍是一个包；`boot/` 是它角色完备的家。
+
+**把 `tool-cordis` 挪进 `core/`。** 不予采纳：自我修改是独立的产品 seam，预期还会生长；主干保持精简。该组最初命名为 `self-evolve/`；评审定为更朴素的 `self-modification/`。
+
+**把 `context/` 改名为 `request-context/`。** 不予采纳：在这棵树里，该组就地看并无歧义；这份改动开销并不值得。
+
+## Acceptance criteria
+
+- 目录树与映射表一致：重组的六个组恰好持有所列成员；`ui/`、`sdk/`、`telemetry/`、`timeout/`、`cordis/`、`session-persistence/`、`session-projection/`、`session-title/` 这些组不复存在；其余每个组的内容不变。
+- npm 改名为零：workspace 的包名集合在前后完全相同。
+- 五条 FIXME 标记全部就位，每条都写明其意图中的新名字。
+- 新增与更新的组 README 构成完整的双语三文件配对；packages/README.md 的层级结构表与目录树一致；docs/module-graph.md 已重新生成。
+- `pnpm run typecheck`、`pnpm run test`、`pnpm run doc-sync`、`pnpm run hygiene` 全部通过，且单元／快照套件在移动前后收集到相同的测试文件（测试配置里按组划定的 glob 不得无声地匹配为空）。
+
+## Risks
+
+- **开放 PR 的冲突。** 每个触碰被移动文件的开放 PR 都必须跨过这次移动做变基。缓解方式：作为单个 PR 在低活动窗口期落地、在 PR 正文公布映射表，且移动都是纯改名（重命名检测可机械化解决大多数改动块）。
+- **引用漂移。** 引用旧路径的文档或脚本可能变得陈旧；`verify-package-paths` 正是为包移动造成的漂移而设，并随 `doc-sync`（文档同步门禁）运行。
+- **翻译负担。** 五组新的组 README 三文件配对，加上既有配对的修改，都随实现 PR 一同落地。
+- **推迟的改名按设计就是发布阻塞项。** 日后若某条 FIXME 被证明不对，必须连同理由显式移除，绝不允许无声消失。
+- **单包组依然存在**（`boot/`、`self-modification/`，以及 `acp/` 等既有单包组）。这是有意接受的：每个都是角色完备的整体而非某个家族的碎片，一个名实相符的小组胜过一次徒有其名的合并。
+- **这次变更放弃了什么：** 功能上一无所失——变更只关乎导航。肌肉记忆和指向旧 GitHub 路径的外部链接会失效；在 pre-release、尚无外部消费者的前提下，这可以接受。

From 7e445c3a676596b373cc20478384352ad86d8299 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 01:52:06 +0800
Subject: [PATCH 403/516] refactor(session): fold the session family into
 packages/session/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.

Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.
---
 .../2026-06-18-session-surface.i18n.yaml      |  4 +-
 .../2026-06-18-session-surface.md             |  6 +--
 .../2026-06-18-session-surface.zh.md          |  6 +--
 ...-07-21-log-backed-session-titles.i18n.yaml |  4 +-
 .../2026-07-21-log-backed-session-titles.md   |  2 +-
 ...2026-07-21-log-backed-session-titles.zh.md |  2 +-
 ...3-session-telemetry-otel-revival.i18n.yaml |  4 +-
 ...26-07-23-session-telemetry-otel-revival.md |  2 +-
 ...07-23-session-telemetry-otel-revival.zh.md |  2 +-
 .../2026-07-06-node-engine-floor.i18n.yaml    |  4 +-
 .../process/2026-07-06-node-engine-floor.md   |  2 +-
 .../2026-07-06-node-engine-floor.zh.md        |  2 +-
 ...-domain-kv-storage-and-workspace.i18n.yaml |  4 +-
 ...6-07-24-domain-kv-storage-and-workspace.md |  4 +-
 ...7-24-domain-kv-storage-and-workspace.zh.md |  2 +-
 ...root-and-derived-medium-recovery.i18n.yaml |  4 +-
 ...torage-root-and-derived-medium-recovery.md |  2 +-
 ...age-root-and-derived-medium-recovery.zh.md |  2 +-
 ...ssembled-assistant-messages-only.i18n.yaml |  4 +-
 ...06-20-assembled-assistant-messages-only.md |  2 +-
 ...20-assembled-assistant-messages-only.zh.md |  2 +-
 ...ld-session-persistence-interface.i18n.yaml |  4 +-
 ...6-20-fold-session-persistence-interface.md |  2 +-
 ...0-fold-session-persistence-interface.zh.md |  2 +-
 ...06-20-truncate-interrupted-turns.i18n.yaml |  4 +-
 .../2026-06-20-truncate-interrupted-turns.md  |  2 +-
 ...026-06-20-truncate-interrupted-turns.zh.md |  2 +-
 AGENTS.md                                     |  2 +-
 docs/architecture.i18n.yaml                   |  4 +-
 docs/architecture.md                          |  4 +-
 docs/architecture.zh.md                       |  4 +-
 docs/capability-seams.md                      | 12 ++---
 .../persistence.i18n.yaml                     |  4 +-
 docs/core-data-structures/persistence.md      |  6 +--
 docs/core-data-structures/persistence.zh.md   |  6 +--
 .../session-title.i18n.yaml                   |  4 +-
 docs/core-data-structures/session-title.md    |  4 +-
 docs/core-data-structures/session-title.zh.md |  4 +-
 docs/persistence-catalog.md                   |  4 +-
 knip.json                                     |  6 +--
 packages/README.i18n.yaml                     |  4 +-
 packages/README.md                            |  5 +-
 packages/README.zh.md                         |  5 +-
 packages/client/runtime/tsconfig.json         |  4 +-
 packages/client/ui-conversation/tsconfig.json |  2 +-
 packages/core/agent-loop/tsconfig.json        |  2 +-
 .../examples/acp-demo/tests/built-bin.e2e.ts  |  4 +-
 packages/examples/acp-demo/tsconfig.json      |  4 +-
 .../examples/agent-spine-demo/tsconfig.json   |  2 +-
 packages/goal/goal/tsconfig.json              |  2 +-
 packages/hooks/hooks-claude/tsconfig.json     |  2 +-
 packages/hooks/hooks-codex/tsconfig.json      |  2 +-
 packages/host/apiproxy/tsconfig.json          |  8 +--
 packages/llm/token-meter/tsconfig.json        |  2 +-
 packages/plan/plan-mode/tsconfig.json         |  2 +-
 packages/sdk/helper/tsconfig.json             |  4 +-
 packages/session-persistence/README.i18n.yaml |  6 ---
 packages/session-persistence/README.md        | 14 ------
 packages/session-persistence/README.zh.md     | 14 ------
 packages/session-projection/README.i18n.yaml  |  6 ---
 packages/session-projection/README.md         | 10 ----
 packages/session-projection/README.zh.md      | 10 ----
 .../session-query-sqlite/tsconfig.json        |  2 +-
 .../session-query/session-query/tsconfig.json |  4 +-
 packages/session-title/README.md              | 14 ------
 packages/session-title/README.zh.md           | 14 ------
 .../README.i18n.yaml                          |  6 +--
 packages/session/README.md                    | 49 +++++++++++++++++++
 packages/session/README.zh.md                 | 49 +++++++++++++++++++
 .../README.i18n.yaml                          |  0
 .../session-checkpoint-policy/README.md       |  0
 .../session-checkpoint-policy/README.zh.md    |  0
 .../session-checkpoint-policy/package.json    |  0
 .../session-checkpoint-policy/src/index.ts    |  0
 .../src/invariant.ts                          |  0
 .../tests/crash-recovery.e2e.ts               |  0
 .../tests/fixtures/crash-child.ts             |  0
 .../tests/session-checkpoint-policy.spec.ts   |  0
 .../session-checkpoint-policy/tsconfig.json   |  2 +-
 .../README.i18n.yaml                          |  0
 .../session-persistence-jsonl/README.md       |  0
 .../session-persistence-jsonl/README.zh.md    |  0
 .../session-persistence-jsonl/package.json    |  0
 .../session-persistence-jsonl/src/format.ts   |  0
 .../session-persistence-jsonl/src/index.ts    |  0
 .../src/invariant.ts                          |  0
 .../session-persistence-jsonl/src/win32.ts    |  0
 .../src/zstd-private-decoder.ts               |  0
 .../src/zstd-public-decoder.ts                |  0
 .../session-persistence-jsonl/src/zstd.ts     |  0
 .../tests/jsonl.spec.ts                       |  0
 .../tests/win32.spec.ts                       |  0
 .../tests/zstd.compat.spec.ts                 |  0
 .../tests/zstd.spec.ts                        |  0
 .../session-persistence-jsonl/tsconfig.json   |  2 +-
 .../README.i18n.yaml                          |  0
 .../session-persistence-sqlite/README.md      |  0
 .../session-persistence-sqlite/README.zh.md   |  0
 .../session-persistence-sqlite/package.json   |  0
 .../session-persistence-sqlite/src/index.ts   |  0
 .../src/invariant.ts                          |  0
 .../session-persistence-sqlite/src/schema.ts  |  0
 .../tests/sqlite.spec.ts                      |  0
 .../session-persistence-sqlite/tsconfig.json  |  2 +-
 .../session-persistence/README.i18n.yaml      |  0
 .../session-persistence/README.md             |  0
 .../session-persistence/README.zh.md          |  0
 .../session-persistence/package.json          |  0
 .../session-persistence/src/coordinator.ts    |  0
 .../session-persistence/src/index.ts          |  0
 .../session-persistence/src/invariant.ts      |  0
 .../session-persistence/src/preparations.ts   |  0
 .../session-persistence/src/revision.ts       |  0
 .../session-persistence/src/write-behind.ts   |  0
 .../session-persistence/tests/contract.ts     |  0
 .../tests/coordinator-contract.ts             |  0
 .../tests/persistence.spec.ts                 |  0
 .../tests/preparations.spec.ts                |  0
 .../tests/write-behind.spec.ts                |  0
 .../session-persistence/tsconfig.json         |  0
 .../session-projection-cache/README.i18n.yaml |  0
 .../session-projection-cache/README.md        |  0
 .../session-projection-cache/README.zh.md     |  0
 .../session-projection-cache/package.json     |  0
 .../session-projection-cache/src/index.ts     |  0
 .../session-projection-cache/src/invariant.ts |  0
 .../session-projection-cache/src/spec.ts      |  0
 .../tests/cache.spec.ts                       |  0
 .../session-projection-cache/tsconfig.json    |  2 +-
 .../session-projection/README.i18n.yaml       |  0
 .../session-projection/README.md              |  0
 .../session-projection/README.zh.md           |  0
 .../session-projection/package.json           |  0
 .../session-projection/src/index.ts           |  0
 .../session-projection/src/invariant.ts       |  0
 .../session-projection/src/types.ts           |  0
 .../session-projection/tests/registry.spec.ts |  0
 .../session-projection/tsconfig.json          |  0
 .../session-telemetry-otel/README.i18n.yaml   |  0
 .../session-telemetry-otel/README.md          |  0
 .../session-telemetry-otel/README.zh.md       |  0
 .../session-telemetry-otel/package.json       |  0
 .../session-telemetry-otel/src/index.ts       |  0
 .../session-telemetry-otel/src/invariant.ts   |  0
 .../session-telemetry-otel/src/user-id.ts     |  0
 .../tests/loader-composition.e2e.ts           |  0
 .../session-telemetry-otel/tests/otel.spec.ts |  0
 .../tests/user-id.spec.ts                     |  0
 .../session-telemetry-otel/tsconfig.json      |  0
 .../session-telemetry/README.i18n.yaml        |  0
 .../session-telemetry/README.md               |  0
 .../session-telemetry/README.zh.md            |  0
 .../session-telemetry/package.json            |  0
 .../session-telemetry/src/coordinator.ts      |  0
 .../session-telemetry/src/index.ts            |  0
 .../session-telemetry/src/invariant.ts        |  0
 .../session-telemetry/tests/redact.spec.ts    |  0
 .../session-telemetry/tests/telemetry.spec.ts |  0
 .../session-telemetry/tsconfig.json           |  0
 .../README.i18n.yaml                          |  0
 .../session-title-all-messages-llm/README.md  |  0
 .../README.zh.md                              |  0
 .../package.json                              |  0
 .../src/index.ts                              |  0
 .../src/invariant.ts                          |  0
 .../tests/provider.spec.ts                    |  0
 .../tsconfig.json                             |  0
 .../README.i18n.yaml                          |  0
 .../session-title-first-message-llm/README.md |  0
 .../README.zh.md                              |  0
 .../package.json                              |  0
 .../src/index.ts                              |  0
 .../src/invariant.ts                          |  0
 .../tests/loader-composition.spec.ts          |  0
 .../tests/provider.e2e.ts                     |  0
 .../tests/provider.spec.ts                    |  0
 .../tsconfig.json                             |  0
 .../session-title-llm/README.i18n.yaml        |  0
 .../session-title-llm/README.md               |  0
 .../session-title-llm/README.zh.md            |  0
 .../session-title-llm/package.json            |  0
 .../session-title-llm/src/index.ts            |  0
 .../session-title-llm/src/invariant.ts        |  0
 .../session-title-llm/tests/llm.spec.ts       |  0
 .../session-title-llm/tsconfig.json           |  0
 .../session-title/README.i18n.yaml            |  0
 .../session-title/README.md                   |  0
 .../session-title/README.zh.md                |  0
 .../session-title/package.json                |  0
 .../session-title/src/client.ts               |  0
 .../session-title/src/index.ts                |  0
 .../session-title/src/invariant.ts            |  0
 .../session-title/src/normalize.ts            |  0
 .../session-title/src/types.ts                |  0
 .../session-title/tests/invariant.spec.ts     |  0
 .../session-title/tests/persistence.spec.ts   |  0
 .../session-title/tests/projection.spec.ts    |  0
 .../session-title/tests/provider.spec.ts      |  0
 .../session-title/tests/rename.spec.ts        |  0
 .../tests/service-contracts.spec.ts           |  0
 .../session-title/tests/session-title.spec.ts |  0
 .../session-title/tsconfig.json               |  2 +-
 packages/subagent/subagent/tsconfig.json      |  2 +-
 packages/telemetry/README.i18n.yaml           |  6 ---
 packages/telemetry/README.md                  | 10 ----
 packages/telemetry/README.zh.md               | 10 ----
 packages/todo/tool-todo/README.i18n.yaml      |  4 +-
 packages/todo/tool-todo/README.md             |  2 +-
 packages/todo/tool-todo/README.zh.md          |  2 +-
 packages/todo/tool-todo/tsconfig.json         |  2 +-
 .../jsonrpc/tests/built-scope-carrier.e2e.ts  |  2 +-
 packages/ui/permission/tsconfig.json          |  2 +-
 packages/workspace/workspace/tsconfig.json    |  2 +-
 scripts/gen-cordis-catalog.ts                 | 12 ++---
 scripts/run-gates.ts                          |  2 +-
 scripts/type-equiv.manifest.json              | 28 +++++------
 .../verify-package-readme-model-experience.ts |  8 +--
 tsconfig.base.json                            | 16 ++----
 tsconfig.host.json                            | 24 ++++-----
 vitest.config.ts                              |  2 +-
 220 files changed, 258 insertions(+), 286 deletions(-)
 delete mode 100644 packages/session-persistence/README.i18n.yaml
 delete mode 100644 packages/session-persistence/README.md
 delete mode 100644 packages/session-persistence/README.zh.md
 delete mode 100644 packages/session-projection/README.i18n.yaml
 delete mode 100644 packages/session-projection/README.md
 delete mode 100644 packages/session-projection/README.zh.md
 delete mode 100644 packages/session-title/README.md
 delete mode 100644 packages/session-title/README.zh.md
 rename packages/{session-title => session}/README.i18n.yaml (71%)
 create mode 100644 packages/session/README.md
 create mode 100644 packages/session/README.zh.md
 rename packages/{session-persistence => session}/session-checkpoint-policy/README.i18n.yaml (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/README.md (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/README.zh.md (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/package.json (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/src/index.ts (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/src/invariant.ts (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/tests/crash-recovery.e2e.ts (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/tests/fixtures/crash-child.ts (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts (100%)
 rename packages/{session-persistence => session}/session-checkpoint-policy/tsconfig.json (89%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/README.i18n.yaml (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/README.md (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/README.zh.md (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/package.json (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/format.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/index.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/invariant.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/win32.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/zstd-private-decoder.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/zstd-public-decoder.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/src/zstd.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/tests/jsonl.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/tests/win32.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/tests/zstd.compat.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/tests/zstd.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-jsonl/tsconfig.json (87%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/README.i18n.yaml (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/README.md (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/README.zh.md (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/package.json (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/src/index.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/src/invariant.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/src/schema.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/tests/sqlite.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence-sqlite/tsconfig.json (87%)
 rename packages/{session-persistence => session}/session-persistence/README.i18n.yaml (100%)
 rename packages/{session-persistence => session}/session-persistence/README.md (100%)
 rename packages/{session-persistence => session}/session-persistence/README.zh.md (100%)
 rename packages/{session-persistence => session}/session-persistence/package.json (100%)
 rename packages/{session-persistence => session}/session-persistence/src/coordinator.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/src/index.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/src/invariant.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/src/preparations.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/src/revision.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/src/write-behind.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tests/contract.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tests/coordinator-contract.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tests/persistence.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tests/preparations.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tests/write-behind.spec.ts (100%)
 rename packages/{session-persistence => session}/session-persistence/tsconfig.json (100%)
 rename packages/{session-projection => session}/session-projection-cache/README.i18n.yaml (100%)
 rename packages/{session-projection => session}/session-projection-cache/README.md (100%)
 rename packages/{session-projection => session}/session-projection-cache/README.zh.md (100%)
 rename packages/{session-projection => session}/session-projection-cache/package.json (100%)
 rename packages/{session-projection => session}/session-projection-cache/src/index.ts (100%)
 rename packages/{session-projection => session}/session-projection-cache/src/invariant.ts (100%)
 rename packages/{session-projection => session}/session-projection-cache/src/spec.ts (100%)
 rename packages/{session-projection => session}/session-projection-cache/tests/cache.spec.ts (100%)
 rename packages/{session-projection => session}/session-projection-cache/tsconfig.json (90%)
 rename packages/{session-projection => session}/session-projection/README.i18n.yaml (100%)
 rename packages/{session-projection => session}/session-projection/README.md (100%)
 rename packages/{session-projection => session}/session-projection/README.zh.md (100%)
 rename packages/{session-projection => session}/session-projection/package.json (100%)
 rename packages/{session-projection => session}/session-projection/src/index.ts (100%)
 rename packages/{session-projection => session}/session-projection/src/invariant.ts (100%)
 rename packages/{session-projection => session}/session-projection/src/types.ts (100%)
 rename packages/{session-projection => session}/session-projection/tests/registry.spec.ts (100%)
 rename packages/{session-projection => session}/session-projection/tsconfig.json (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/README.i18n.yaml (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/README.md (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/README.zh.md (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/package.json (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/src/index.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/src/invariant.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/src/user-id.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/tests/loader-composition.e2e.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/tests/otel.spec.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/tests/user-id.spec.ts (100%)
 rename packages/{telemetry => session}/session-telemetry-otel/tsconfig.json (100%)
 rename packages/{telemetry => session}/session-telemetry/README.i18n.yaml (100%)
 rename packages/{telemetry => session}/session-telemetry/README.md (100%)
 rename packages/{telemetry => session}/session-telemetry/README.zh.md (100%)
 rename packages/{telemetry => session}/session-telemetry/package.json (100%)
 rename packages/{telemetry => session}/session-telemetry/src/coordinator.ts (100%)
 rename packages/{telemetry => session}/session-telemetry/src/index.ts (100%)
 rename packages/{telemetry => session}/session-telemetry/src/invariant.ts (100%)
 rename packages/{telemetry => session}/session-telemetry/tests/redact.spec.ts (100%)
 rename packages/{telemetry => session}/session-telemetry/tests/telemetry.spec.ts (100%)
 rename packages/{telemetry => session}/session-telemetry/tsconfig.json (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/README.i18n.yaml (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/README.md (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/README.zh.md (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/package.json (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/src/index.ts (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/src/invariant.ts (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/tests/provider.spec.ts (100%)
 rename packages/{session-title => session}/session-title-all-messages-llm/tsconfig.json (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/README.i18n.yaml (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/README.md (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/README.zh.md (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/package.json (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/src/index.ts (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/src/invariant.ts (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/tests/loader-composition.spec.ts (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/tests/provider.e2e.ts (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/tests/provider.spec.ts (100%)
 rename packages/{session-title => session}/session-title-first-message-llm/tsconfig.json (100%)
 rename packages/{session-title => session}/session-title-llm/README.i18n.yaml (100%)
 rename packages/{session-title => session}/session-title-llm/README.md (100%)
 rename packages/{session-title => session}/session-title-llm/README.zh.md (100%)
 rename packages/{session-title => session}/session-title-llm/package.json (100%)
 rename packages/{session-title => session}/session-title-llm/src/index.ts (100%)
 rename packages/{session-title => session}/session-title-llm/src/invariant.ts (100%)
 rename packages/{session-title => session}/session-title-llm/tests/llm.spec.ts (100%)
 rename packages/{session-title => session}/session-title-llm/tsconfig.json (100%)
 rename packages/{session-title => session}/session-title/README.i18n.yaml (100%)
 rename packages/{session-title => session}/session-title/README.md (100%)
 rename packages/{session-title => session}/session-title/README.zh.md (100%)
 rename packages/{session-title => session}/session-title/package.json (100%)
 rename packages/{session-title => session}/session-title/src/client.ts (100%)
 rename packages/{session-title => session}/session-title/src/index.ts (100%)
 rename packages/{session-title => session}/session-title/src/invariant.ts (100%)
 rename packages/{session-title => session}/session-title/src/normalize.ts (100%)
 rename packages/{session-title => session}/session-title/src/types.ts (100%)
 rename packages/{session-title => session}/session-title/tests/invariant.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/persistence.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/projection.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/provider.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/rename.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/service-contracts.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tests/session-title.spec.ts (100%)
 rename packages/{session-title => session}/session-title/tsconfig.json (90%)
 delete mode 100644 packages/telemetry/README.i18n.yaml
 delete mode 100644 packages/telemetry/README.md
 delete mode 100644 packages/telemetry/README.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
index 7c05a0ada8..911d0709f1 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.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 .agents/notes/implemented/architecture/2026-06-18-session-surface.md
-2026-06-18-session-surface.md: eeac53534c70099e4102aff9ef226702ea939654
-2026-06-18-session-surface.zh.md: c58d3da049cd6c18e564e596354f5d1831c4756f
+2026-06-18-session-surface.md: 1bb3baac5e9bea3f657cbd3be2623223bda78ce2
+2026-06-18-session-surface.zh.md: bfbfd097ffeca59dec163dff911315d0ed94d028
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
index eeac53534c..1bb3baac5e 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
@@ -64,9 +64,9 @@ Every surface-eligible event must carry `surfaceOp` or it would disappear from d
 
 - **`packages/core/session`**: `surface.ts` (`SurfaceManager`) maintains one ordered seq array for candidate acceptance and live projection; `SessionSurface` is its readonly public view. `SurfaceOp`/`SurfaceIntent` and the top-level session-event fields record how entries join it. `append()` requires a `SurfaceIntent` for surface events, `deriveMessages()` walks the surface as the sole derivation path, and `repair.ts` emits surface-aware closers. The seed constructor rejects a surface-eligible seed event missing its `surfaceOp` marker (see § Invariants).
 - **`packages/core/agent-loop`**: All surface-capable appends pass surface opts. Chunk seqs are collected for `assistant/message` provenance; `tool/call` seqs are captured for `tool/result` provenance.
-- **`packages/session-persistence/session-persistence-sqlite`**: Two new nullable TEXT columns (`source_event_seqs`, `surface_op`) on the `events` table; `SCHEMA_VERSION` bumped (bump-and-reject, no migration).
-- **`packages/session-persistence/session-persistence-jsonl`**: No changes required.
-- **`packages/session-persistence/session-persistence`**: Abstract interface unchanged.
+- **`packages/session/session-persistence-sqlite`**: Two new nullable TEXT columns (`source_event_seqs`, `surface_op`) on the `events` table; `SCHEMA_VERSION` bumped (bump-and-reject, no migration).
+- **`packages/session/session-persistence-jsonl`**: No changes required.
+- **`packages/session/session-persistence`**: Abstract interface unchanged.
 
 The surface is the foundation for future history manipulation. A compaction or tool-result-prune plugin appends one of the existing message-producing event types (a `user/message` carrying the summary, say) with `surfaceOp: { op: 'replace', start, end }` and `sourceEventSeqs` covering the shadowed entries — the new event takes the range's place on the surface while the plugin's own trace events (e.g. `compaction/start`, `compaction/end`) stay off it. Replay preserves the decision deterministically.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
index c58d3da049..bfbfd097ff 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -64,9 +64,9 @@ export type SurfaceOp =
 
 - **`packages/core/session`**：`surface.ts`（`SurfaceManager`）维护一个用于候选接纳和实时投影的有序 seq 数组；`SessionSurface` 是其只读公共视图。`SurfaceOp`/`SurfaceIntent` 与顶层会话事件字段记录条目如何加入它。`append()` 要求 surface 事件携带 `SurfaceIntent`，`deriveMessages()` 以遍历 surface 作为唯一派生路径，`repair.ts` 则发出 surface 感知的闭合事件。种子构造函数拒绝缺少 `surfaceOp` 标记的可进入 surface 的种子事件（见「不变式」一节）。
 - **`packages/core/agent-loop`**：所有涉及 surface 事件的追加操作都传入 surface 选项。收集分片 seq 用于 `assistant/message` 溯源；捕获 `tool/call` seq 用于 `tool/result` 溯源。
-- **`packages/session-persistence/session-persistence-sqlite`**：`events` 表新增两个可空 TEXT 列（`source_event_seqs`、`surface_op`）；`SCHEMA_VERSION` 递增（bump-and-reject，无迁移）。
-- **`packages/session-persistence/session-persistence-jsonl`**：无需改动。
-- **`packages/session-persistence/session-persistence`**：抽象接口不变。
+- **`packages/session/session-persistence-sqlite`**：`events` 表新增两个可空 TEXT 列（`source_event_seqs`、`surface_op`）；`SCHEMA_VERSION` 递增（bump-and-reject，无迁移）。
+- **`packages/session/session-persistence-jsonl`**：无需改动。
+- **`packages/session/session-persistence`**：抽象接口不变。
 
 Surface 是未来历史操纵的基础。压缩或 tool-result-prune 插件追加一个既有的消息产出事件类型（例如一条携带摘要的 `user/message`），附带 `surfaceOp: { op: 'replace', start, end }` 和覆盖被遮蔽条目的 `sourceEventSeqs`——新事件在 surface 上取代该范围的位置，而插件自身的 trace 事件（如 `compaction/start`、`compaction/end`）不进入 surface。回放以确定性方式保留该决策。
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
index 5c5054b0c9..e109560a2f 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.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 .agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
-2026-07-21-log-backed-session-titles.md: 5f4c53a5fb866663bbfaae6b3fdafb4660424804
-2026-07-21-log-backed-session-titles.zh.md: f9629c1109c8428c74270de9475423d29b99e8f1
+2026-07-21-log-backed-session-titles.md: 89e6e67fb9ece4c087ba7b1bc52e61b78b94586c
+2026-07-21-log-backed-session-titles.zh.md: 4df21be565f57db056f506df477f665908d1fdfa
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
index 5f4c53a5fb..89e6e67fb9 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
@@ -12,7 +12,7 @@ Session identity metadata is immutable, and the event log is the replay and fork
 
 ## Decision
 
-The [`session-title` capability family](../../../../packages/session-title/README.md) owns title state and generation policy. `@deepseek-ai/dsh-session-title` provides `ctx.sessionTitle`, a deterministic first-message fallback, and a registry for at most one optional asynchronous provider. `@deepseek-ai/dsh-session-title-llm` owns the common auxiliary-model request policy; separate first-message and all-user-messages plugins choose input cadence. The shared agent spine mounts only the fallback service. The Web host mounts that service plus the first-message model provider with explicit overridable limits, so a fresh Web session gains an immediate fallback and then a non-blocking model summary. Other compositions choose either model provider explicitly.
+The [`session-title` capability family](../../../../packages/session/README.md) owns title state and generation policy. `@deepseek-ai/dsh-session-title` provides `ctx.sessionTitle`, a deterministic first-message fallback, and a registry for at most one optional asynchronous provider. `@deepseek-ai/dsh-session-title-llm` owns the common auxiliary-model request policy; separate first-message and all-user-messages plugins choose input cadence. The shared agent spine mounts only the fallback service. The Web host mounts that service plus the first-message model provider with explicit overridable limits, so a fresh Web session gains an immediate fallback and then a non-blocking model summary. Other compositions choose either model provider explicitly.
 
 ### Event ownership and folding
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
index f9629c1109..4df21be565 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-[`session-title` 功能包族](../../../../packages/session-title/README.md)负责标题状态和生成策略。`@deepseek-ai/dsh-session-title` 提供 `ctx.sessionTitle`、确定性的首消息回退方案，以及一个至多接受单个可选异步提供方的注册表。`@deepseek-ai/dsh-session-title-llm` 负责通用的辅助模型请求策略；首消息插件和全部用户消息插件分别选择输入调度方式。共享 agent 主干只挂载回退服务。Web host 会挂载该服务和首消息模型提供方，并显式设置可覆盖的限制，因此新建的 Web 会话会立即获得回退标题，随后在不阻塞主响应的情况下获得模型摘要。其他组合需显式选择任一模型提供方。
+[`session-title` 功能包族](../../../../packages/session/README.md)负责标题状态和生成策略。`@deepseek-ai/dsh-session-title` 提供 `ctx.sessionTitle`、确定性的首消息回退方案，以及一个至多接受单个可选异步提供方的注册表。`@deepseek-ai/dsh-session-title-llm` 负责通用的辅助模型请求策略；首消息插件和全部用户消息插件分别选择输入调度方式。共享 agent 主干只挂载回退服务。Web host 会挂载该服务和首消息模型提供方，并显式设置可覆盖的限制，因此新建的 Web 会话会立即获得回退标题，随后在不阻塞主响应的情况下获得模型摘要。其他组合需显式选择任一模型提供方。
 
 ### 事件归属与折叠
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index 27786e85a2..58b5371ba2 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.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 .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
-2026-07-23-session-telemetry-otel-revival.md: f83128e8bf62e0718e59912c16c4e449855aaa1a
-2026-07-23-session-telemetry-otel-revival.zh.md: bef3bd9cbc22f363b92880864651dcaa782fc1de
+2026-07-23-session-telemetry-otel-revival.md: e6a213af65451a2ae26a5eb685c1a0f6ab220869
+2026-07-23-session-telemetry-otel-revival.zh.md: 4e834f8b129e2062064cf3497370fecf6f88db29
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
index f83128e8bf..e6a213af65 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
@@ -10,7 +10,7 @@ Every deployment that wants harness sessions in an observability stack must hand
 
 ## Decision
 
-`packages/telemetry/` revives the two reviewed packages under the SDK stance — the harness provides the capability, the deployment configures where records go and owns what leaves in them:
+`packages/session/` (formerly `telemetry/`) revives the two reviewed packages under the SDK stance — the harness provides the capability, the deployment configures where records go and owns what leaves in them:
 
 - **`@deepseek-ai/dsh-session-telemetry`** — the seam. `TelemetryBackend` (`emit`/`flush?`/`shutdown`), the service-registered `Telemetry` form, and `TelemetryCoordinator` owning capture: live adoption with cursor read-back and the per-append firehose (project → `structuredClone` → redact → `emit`, zero I/O), buffer-free on-demand replay from the canonical log, the fixed first-chunk-per-(turn, step) projection, the live `agent/error` relay, and live dispose-time `shutdown` records.
 - **The `telemetry/record` waterfall** — the delta over the branch version and the seam's redaction extension point. Every record passes it before reaching any backend; the seam ships NO rules of its own — the innermost `next()` is a pass-through, deployments mount their rules as listeners (stacking by transforming `next()`'s return value), and a throwing rule withholds the record fail-closed. Redaction applies to the exported copy only; the canonical log is never rewritten.
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index bef3bd9cbc..4e834f8b12 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-`packages/telemetry/` 以 SDK 立场复活这两个经过评审的包——harness 提供能力，部署方配置上报去向并对导出内容负责：
+`packages/session/`（原 `telemetry/`）以 SDK 立场复活这两个经过评审的包——harness 提供能力，部署方配置上报去向并对导出内容负责：
 
 - **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的实时收养与逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、从权威日志进行的无缓冲按需回放、固定的每个（轮次、步骤）组合首分片投影、实时 `agent/error` 转发，以及实时 dispose（资源释放）时的 `shutdown` 记录。
 - **`telemetry/record` waterfall（瀑布式事件）** —— 相对分支版本的增量，也是该 seam 的脱敏扩展点。每条记录抵达任何后端前必经此处；seam 自身不带任何规则——最内层 `next()` 原样透传，部署方以监听器挂载自己的规则（通过变换 `next()` 的返回值堆叠），抛异常的规则将该记录 fail-closed 扣下。脱敏只作用于导出副本；canonical log 永不改写。
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
index d96a3b4d6c..ddca590dea 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.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 .agents/notes/implemented/process/2026-07-06-node-engine-floor.md
-2026-07-06-node-engine-floor.md: e42b809f83fe388526ecbd74192989e0bcdbba67
-2026-07-06-node-engine-floor.zh.md: 92fa00f7a270f4506cba6c899e9edf6a2fdd3209
+2026-07-06-node-engine-floor.md: ad21fbfe034cbf4bb7b75aaac4113f3139a1832d
+2026-07-06-node-engine-floor.zh.md: 0d1c31ed74565f9b20116cd0e666246baad9bf79
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md
index e42b809f83..ad21fbfe03 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.md
@@ -14,7 +14,7 @@ Set `engines.node` to `^22.19.0 || >=24.0.0` and test keyless CI on `['22.19', 2
 
 Two Node features gate the source runtime:
 
-- **`node:sqlite`** — `packages/session-persistence/session-persistence-sqlite` does a top-level `import { DatabaseSync } from 'node:sqlite'`. The module dropped its `--experimental-sqlite` flag requirement at **22.13** (LTS) and **23.4** (Current); before those, importing it throws at load.
+- **`node:sqlite`** — `packages/session/session-persistence-sqlite` does a top-level `import { DatabaseSync } from 'node:sqlite'`. The module dropped its `--experimental-sqlite` flag requirement at **22.13** (LTS) and **23.4** (Current); before those, importing it throws at load.
 - **Native TypeScript type-stripping** — the built-mode `examples/headless-agent/tests/keyless-smoke.e2e.ts` smoke boots its unexported `.ts` driver under plain `node` (no tsx) and loads the example's `.ts` test adapter (`cli-mock-llm.ts`). Type-stripping is the default from **22.18** (LTS) and **23.6** (Current); before those it needs `--experimental-strip-types`.
 
 Those source features clear on the 22.x line at **22.18**, but the installed Pi adapter dependency raises the advertised LTS floor. `@deepseek-ai/dsh-llm-pi-ai` depends on `@earendil-works/pi-ai@0.79.3`, whose package declares `engines.node >=22.19.0`, so the LTS floor is **22.19**. The 24.x branch remains `>=24.0.0`. The disjoint range excludes Node 23 entirely: Node 23.0–23.5 still has at least one flagged source feature, and the 23 line is non-LTS/EOL, so advertising `>=23.6` would add a dead release line and a CI leg no deployment should use.
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
index 92fa00f7a2..0d1c31ed74 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 两个 Node 特性决定了源码运行时的门槛：
 
-- **`node:sqlite`**：`packages/session-persistence/session-persistence-sqlite` 在顶层执行 `import { DatabaseSync } from 'node:sqlite'`。该模块在 **22.13**（LTS）和 **23.4**（Current）取消了 `--experimental-sqlite` 标志要求；在此之前，导入它会在加载时抛出异常。
+- **`node:sqlite`**：`packages/session/session-persistence-sqlite` 在顶层执行 `import { DatabaseSync } from 'node:sqlite'`。该模块在 **22.13**（LTS）和 **23.4**（Current）取消了 `--experimental-sqlite` 标志要求；在此之前，导入它会在加载时抛出异常。
 - **原生 TypeScript 类型剥离**——构建模式的 `examples/headless-agent/tests/keyless-smoke.e2e.ts` 冒烟测试使用纯 `node`（无 tsx）启动该示例未导出的 `.ts` driver，并加载示例的 `.ts` 测试适配器（`cli-mock-llm.ts`）。类型剥离从 **22.18**（LTS）和 **23.6**（Current）起成为默认行为；更早版本需要 `--experimental-strip-types`。
 
 这些源码特性在 22.x 线上于 **22.18** 全部就绪，但已安装的 Pi 适配器依赖将宣传的 LTS 下限进一步提高。`@deepseek-ai/dsh-llm-pi-ai` 依赖 `@earendil-works/pi-ai@0.79.3`，后者的包声明 `engines.node >=22.19.0`，因此 LTS 下限为 **22.19**。24.x 分支保持 `>=24.0.0`。该不相交范围完全排除了 Node 23：Node 23.0–23.5 至少还有一个源码特性需要标志，而 23 线是非 LTS/已 EOL 的，宣传 `>=23.6` 会增加一条已终止的发布线和一条 CI 分支，而没有任何部署应当使用它。
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
index 176097ad5e..620fa2291f 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.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 .agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
-2026-07-24-domain-kv-storage-and-workspace.md: 230877628428dc88dbddeecfe5f4353cf15e151d
-2026-07-24-domain-kv-storage-and-workspace.zh.md: cb1fb1346a28b0c3249848705ca209f57cab766e
+2026-07-24-domain-kv-storage-and-workspace.md: 1cb2bc4b29c196dbb33292547c75d01a37f06772
+2026-07-24-domain-kv-storage-and-workspace.zh.md: 15460e305d2d9aca3009025cf0218eb6c54c7237
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
index 2308776284..1cb2bc4b29 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-24-domain-kv-storage-and-workspace.zh.md)
 
 ## Problem
 
-The host's only persistence surface is the session event log (`packages/session-persistence`: append-only, one file per session). Anything that does not belong to a single session has nowhere to live, and two real needs exist today:
+The host's only persistence surface is the session event log (`packages/session/session-persistence`: append-only, one file per session). Anything that does not belong to a single session has nowhere to live, and two real needs exist today:
 
 - **The workspace entity.** The GUI needs workspace as a real object: path, title, and the list of owned sessions. Ownership belongs to the workspace — "which sessions belong to this workspace" is not any single session's fact, so writing it into the session log is semantically wrong. Until now workspace was only a sidebar visual grouping derived from cwd, with no entity (that conclusion has been overturned).
 - **Dynamic session metadata** (the foreseeable second consumer). Cold session listings read only the first log line (an immutable creation-time snapshot); title, terminal status, and anything that evolves with the session is unavailable. The fix direction is a sidecar metadata table — exactly a KV table with high-frequency per-key updates.
@@ -26,7 +26,7 @@ Create the `packages/storage/` group — the `ctx.storage` hub (backend registry
 | `@deepseek-ai/dsh-storage-sqlite` | `packages/storage/storage-sqlite/` | registers backend `sqlite` | ✓ |
 | `@deepseek-ai/dsh-storage-domain` | `packages/storage/storage-domain/` | mounts `ctx.storage.domain` | ✓ |
 | `@deepseek-ai/dsh-workspace` | `packages/workspace/workspace/` | `ctx.workspace` | ✓ |
-| `SessionPersistence.delete` extension + cascade orchestration | `packages/session-persistence/*` | new method on the existing seam | ✗ future work (session side untouched this phase) |
+| `SessionPersistence.delete` extension + cascade orchestration | `packages/session/session-persistence*` | new method on the existing seam | ✗ future work (session side untouched this phase) |
 | `workspace.*` / `session.delete` RPC, GUI wiring, boot assembly | — | — | ✗ next phase |
 
 (workspace lives in its own group rather than `packages/host/`: the host group's naming rule requires the `dsh-host-*` prefix while this package is named `dsh-workspace`; and the workspace entity is a domain concept, not bound to the host assembly tier. Unrelated to the existing `workspace-context` package — that is an AGENTS.md instruction loader.)
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
index cb1fb1346a..15460e305d 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
@@ -26,7 +26,7 @@ host 侧唯一的持久化面是 session 事件日志（`packages/session-persis
 | `@deepseek-ai/dsh-storage-sqlite` | `packages/storage/storage-sqlite/` | 注册后端 `sqlite` | ✓ |
 | `@deepseek-ai/dsh-storage-domain` | `packages/storage/storage-domain/` | 挂载 `ctx.storage.domain` | ✓ |
 | `@deepseek-ai/dsh-workspace` | `packages/workspace/workspace/` | `ctx.workspace` | ✓ |
-| `SessionPersistence.delete` 扩面 + 级联删编排 | `packages/session-persistence/*` | 既有 seam 新方法 | ✗ future work（本期不动 session 侧） |
+| `SessionPersistence.delete` 扩面 + 级联删编排 | `packages/session/*` | 既有 seam 新方法 | ✗ future work（本期不动 session 侧） |
 | `workspace.*` / `session.delete` RPC、GUI 接线、boot 组装 | — | — | ✗ 下期 |
 
 （workspace 放独立组不放 `packages/host/`：host 组命名规则要求 `dsh-host-*` 前缀，而包名定为 `dsh-workspace`；且 workspace 实体是领域概念，不绑定 host 装配层。与既有 `workspace-context` 包无关——那是 AGENTS.md 指令加载器。）
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
index f1bd359e19..040d099f38 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.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 .agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
-2026-07-28-storage-root-and-derived-medium-recovery.md: 2edb60d204da736bf14ace6278fa4ee7b9e4b8f7
-2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 802ca16f399446777203581d246444e53d632a34
+2026-07-28-storage-root-and-derived-medium-recovery.md: c7b423770fcca89c54d3866db7701348351cc259
+2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 54a2bbc6496bd8cce594b3ce3a105e4be6e8ff64
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
index 2edb60d204..c7b423770f 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-28-storage-root-and-derived-medium-recovery.zh.md)
 
 The persisted projection cache ([RFC](2026-07-27-session-projection-and-command-log.md), shipped as `dsh-session-projection-cache`) surfaced two gaps in the storage substrate it landed on. Both are properties of the domain-KV stack ([design](2026-07-24-domain-kv-storage-and-workspace.md)), not of the cache itself, and both bite the cache first because it is the first *derived* medium on that stack.
 
-**Where the files actually live (root mismatch closed; resolve-once residual still open).** The shared base defaults the session store to the global harness home (`$DSH_HOME/sessions`, default `~/.dsh/sessions`), while the shipped Web overlay used to give the json backend the relative root `./.storages`: `workspace.json` and `session_projcache.json` landed under `<launch dir>/.storages/` — two launches from different directories shared their sessions yet saw different workspace registries and different projection caches, and the cache exists precisely to serve the cross-session cold listing, which missed for every session last cached under another launch directory. That mismatch is now closed: the overlay anchors `storage-json.root` to `$DSH_HOME/storages` with the same `!!js` expression the session root uses (`apps/cli/config/web.cordis.yml`). The residual hazard: `JsonStorageBackend` still never resolves its root — each unit open joins the path against whatever `process.cwd()` is at that moment (packages/storage/storage-json/src/index.ts); the shipped overlay root is already absolute and unaffected, but any relative root (bare Loader boots, tests) still splits on a later cwd change — the exact hazard the JSONL session backend resolves-once to prevent ("later process.cwd() changes cannot split one backend across roots", packages/session-persistence/session-persistence-jsonl/src/index.ts).
+**Where the files actually live (root mismatch closed; resolve-once residual still open).** The shared base defaults the session store to the global harness home (`$DSH_HOME/sessions`, default `~/.dsh/sessions`), while the shipped Web overlay used to give the json backend the relative root `./.storages`: `workspace.json` and `session_projcache.json` landed under `<launch dir>/.storages/` — two launches from different directories shared their sessions yet saw different workspace registries and different projection caches, and the cache exists precisely to serve the cross-session cold listing, which missed for every session last cached under another launch directory. That mismatch is now closed: the overlay anchors `storage-json.root` to `$DSH_HOME/storages` with the same `!!js` expression the session root uses (`apps/cli/config/web.cordis.yml`). The residual hazard: `JsonStorageBackend` still never resolves its root — each unit open joins the path against whatever `process.cwd()` is at that moment (packages/storage/storage-json/src/index.ts); the shipped overlay root is already absolute and unaffected, but any relative root (bare Loader boots, tests) still splits on a later cwd change — the exact hazard the JSONL session backend resolves-once to prevent ("later process.cwd() changes cannot split one backend across roots", packages/session/session-persistence-jsonl/src/index.ts).
 
 **How recovery works today.** Inside a healthy medium the cache is fully self-healing by design: a `stateVersion`-mismatched row is discarded and refolded, a log shrunk below a row's watermark is detected by the anchored restore floor and answered with one full re-read, and every background write is fail-soft. But at the *medium* level there is no recovery at all: a truncated, hand-edited, or version-bumped `session_projcache.json` fails `openJsonUnit` with `malformed-medium`/`version-mismatch` (packages/storage/storage-json/src/format.ts), a schema-drifted record fails domain open with `invalid-record` (packages/storage/storage-domain/src/index.ts), the rejection propagates through `SessionProjectionCache[Service.init]`, and under the CLI's fail-loud boot the assembly refuses to start. A file whose entire content is rebuildable from session logs can brick boot. This contradicts the cache package's own stated stance ("a stale or unreadable cache costs a longer tail replay, never a wrong value") and the cache domain spec's JSDoc ("version bumps discard the whole medium"), which today describes an aspiration, not the implementation. The same fail-loud path is *correct* for `workspace.json` — workspace records are authoritative, not derivable — so the missing concept is a per-domain declaration of authority, not a global behavior change.
 
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
index 802ca16f39..54a2bbc649 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
@@ -8,7 +8,7 @@ Status: proposed
 
 持久投影缓存（[RFC](2026-07-27-session-projection-and-command-log.md)，已作为 `dsh-session-projection-cache` 落地）暴露了它所依托的存储基座的两个缺口。二者都是 domain-KV 栈（[设计](2026-07-24-domain-kv-storage-and-workspace.md)）的属性而非缓存自身的问题，且都首先咬到缓存——因为它是这条栈上第一个*派生*介质。
 
-**文件到底存在哪（根错位已收口，resolve-once 残余仍开放）。** 共享 base 将会话存储默认为全局 harness home（`$DSH_HOME/sessions`，默认 `~/.dsh/sessions`），而出厂 Web overlay 曾给 json 后端相对根 `./.storages`：`workspace.json` 和 `session_projcache.json` 落在 `<启动目录>/.storages/` 下——从两个不同目录启动，会话相同，工作区注册表和投影缓存却各是一份，而缓存存在的意义恰恰是跨会话冷列表，凡上次在别的启动目录下缓存过的会话全部 miss。这一错位已消除：overlay 现以与会话根同一段 `!!js` 表达式把 `storage-json.root` 锚定到 `$DSH_HOME/storages`（`apps/cli/config/web.cordis.yml`）。残余隐患：`JsonStorageBackend` 仍从不 resolve 根——每次打开 unit 都把路径 join 到当时的 `process.cwd()` 上（packages/storage/storage-json/src/index.ts）；出厂 overlay 的根已是绝对路径不受影响，但任何相对根（裸 Loader 启动、测试）仍会被后续 cwd 变化劈开，JSONL 会话后端用「构造时 resolve 一次」防住的正是它（"later process.cwd() changes cannot split one backend across roots"，packages/session-persistence/session-persistence-jsonl/src/index.ts）。
+**文件到底存在哪（根错位已收口，resolve-once 残余仍开放）。** 共享 base 将会话存储默认为全局 harness home（`$DSH_HOME/sessions`，默认 `~/.dsh/sessions`），而出厂 Web overlay 曾给 json 后端相对根 `./.storages`：`workspace.json` 和 `session_projcache.json` 落在 `<启动目录>/.storages/` 下——从两个不同目录启动，会话相同，工作区注册表和投影缓存却各是一份，而缓存存在的意义恰恰是跨会话冷列表，凡上次在别的启动目录下缓存过的会话全部 miss。这一错位已消除：overlay 现以与会话根同一段 `!!js` 表达式把 `storage-json.root` 锚定到 `$DSH_HOME/storages`（`apps/cli/config/web.cordis.yml`）。残余隐患：`JsonStorageBackend` 仍从不 resolve 根——每次打开 unit 都把路径 join 到当时的 `process.cwd()` 上（packages/storage/storage-json/src/index.ts）；出厂 overlay 的根已是绝对路径不受影响，但任何相对根（裸 Loader 启动、测试）仍会被后续 cwd 变化劈开，JSONL 会话后端用「构造时 resolve 一次」防住的正是它（"later process.cwd() changes cannot split one backend across roots"，packages/session/session-persistence-jsonl/src/index.ts）。
 
 **现在是怎么恢复的。** 在健康介质内部，缓存按设计完全自愈：`stateVersion` 不匹配的行被丢弃重折，日志缩短到行水位以下由带锚的 restore floor 检出并以一次全量重读回答，每次后台写都是 fail-soft。但在*介质*层面完全没有恢复：被截断、被手改或版本被 bump 的 `session_projcache.json` 会让 `openJsonUnit` 以 `malformed-medium`/`version-mismatch` 失败（packages/storage/storage-json/src/format.ts），schema 漂移的记录让域 open 以 `invalid-record` 失败（packages/storage/storage-domain/src/index.ts），拒绝一路穿过 `SessionProjectionCache[Service.init]`，在 CLI 的 fail-loud 启动下整个组装拒绝启动。一个内容完全可从会话日志重建的文件能把启动搞死。这与缓存包自己声明的立场（"a stale or unreadable cache costs a longer tail replay, never a wrong value"）和缓存域 spec 的 JSDoc（"version bumps discard the whole medium"）相矛盾——后者今天描述的是愿望而非实现。同一条 fail-loud 路径对 `workspace.json` 却是*正确*的——工作区记录是权威数据，不可派生——所以缺的概念是按域声明权威性，而不是全局改行为。
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
index e252ed8190..d9dd98233e 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.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 .agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md
-2026-06-20-assembled-assistant-messages-only.md: ba8135a3d63f292cfedd23de8b4b9d43b4455e8c
-2026-06-20-assembled-assistant-messages-only.zh.md: 5d29655a0697d05f20e491d28272898a08ec3e0b
+2026-06-20-assembled-assistant-messages-only.md: edc756f71271065ec579a2becb8597190b34cdc8
+2026-06-20-assembled-assistant-messages-only.zh.md: e5f4f8a63a35f5f40c482a4a4855937cc8e6d544
diff --git a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md
index ba8135a3d6..edc756f712 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md
@@ -19,7 +19,7 @@ ACP `session/load` can replay prior assistant messages as complete content block
 ## Acceptance criteria
 
 - `SessionEventMap` drops `assistant/chunk`, or marks it as non-persisted if a transitional live event is needed.
-- [Session persistence docs](../../../../packages/session-persistence/session-persistence/README.md) no longer require every stream chunk to be stored verbatim.
+- [Session persistence docs](../../../../packages/session/session-persistence/README.md) no longer require every stream chunk to be stored verbatim.
 - `llm-replay` and ACP snapshots use an explicit replay fixture format or sidecar for model chunks.
 - `session/load` renders completed assistant messages from `assistant/message`.
 - Stored logs get much smaller and remain `seq`-contiguous without chunk holes.
diff --git a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
index 5d29655a06..e5f4f8a63a 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
@@ -19,7 +19,7 @@ ACP `session/load` 可以将先前的 assistant 消息作为完整内容块回
 ## 验收标准
 
 - `SessionEventMap` 移除 `assistant/chunk`，或在需要过渡性实时事件时将其标记为非持久化。
-- [会话持久化文档](../../../../packages/session-persistence/session-persistence/README.md)不再要求逐字存储每个流式分片。
+- [会话持久化文档](../../../../packages/session/session-persistence/README.md)不再要求逐字存储每个流式分片。
 - `llm-replay` 和 ACP 快照使用显式的回放 fixture 格式或伴随文件来存储模型分片。
 - `session/load` 从 `assistant/message` 渲染已完成的 assistant 消息。
 - 存储的日志大幅缩小，且删除分片后仍保持 `seq` 连续，不留下序号缺口。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
index 0ae596bf03..4c5b2d04de 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.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 .agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
-2026-06-20-fold-session-persistence-interface.md: 895b868b2a80d8655284bae1364a85e19e174da7
-2026-06-20-fold-session-persistence-interface.zh.md: d5ce0ed4532706ffadb43460cd0974507393a5ed
+2026-06-20-fold-session-persistence-interface.md: c0da160e766cf0bed532f0d11bd52e3a027dbe8b
+2026-06-20-fold-session-persistence-interface.zh.md: 93ab244429600bd15e2d8dadfa7dc218e37c2eff
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
index 895b868b2a..c0da160e76 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
@@ -22,7 +22,7 @@ The implementing PR should update the [capability seams](../../implemented/archi
 - `dsh-session` exports the persistence service type, coordinator, and contract helpers.
 - JSONL and SQLite backend packages depend on `dsh-session` directly.
 - `agent-loop` resume uses the session-owned service key.
-- [Session persistence](../../implemented/architecture/2026-06-14-session-persistence.md), [shared persistence write coordinator](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md), and [package docs](../../../../packages/session-persistence/session-persistence/README.md) explain why backend implementations remain separate.
+- [Session persistence](../../implemented/architecture/2026-06-14-session-persistence.md), [shared persistence write coordinator](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md), and [package docs](../../../../packages/session/session-persistence/README.md) explain why backend implementations remain separate.
 
 ## What we give up
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
index d5ce0ed453..93ab244429 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
@@ -22,7 +22,7 @@ Status: rejected — 独立的持久化接口包是为持久化后端设计的
 - `dsh-session` 导出持久化服务类型、协调器和契约辅助工具。
 - JSONL 和 SQLite 后端包直接依赖 `dsh-session`。
 - `agent-loop` 的恢复功能使用会话包拥有的服务键。
-- [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.md)、[共享持久化写入协调器](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)与[包文档](../../../../packages/session-persistence/session-persistence/README.md)说明后端实现为何仍保持独立。
+- [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.md)、[共享持久化写入协调器](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)与[包文档](../../../../packages/session/session-persistence/README.md)说明后端实现为何仍保持独立。
 
 ## 放弃了什么
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
index 09f42a9047..7e9b79fdeb 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.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 .agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md
-2026-06-20-truncate-interrupted-turns.md: 3c7acf8d673568f851edd52635a28f73d9bf5f6f
-2026-06-20-truncate-interrupted-turns.zh.md: f348e6a99d8214f7968d9f57931f9dddd37973be
+2026-06-20-truncate-interrupted-turns.md: c4b0084de537927a27829eb78990c6559bd1df7d
+2026-06-20-truncate-interrupted-turns.zh.md: 2d3eca74416eff360029e3ac77f04662878a0084
diff --git a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md
index 3c7acf8d67..c4b0084de5 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md
@@ -21,7 +21,7 @@ This makes the persisted turn boundary simple: a completed `turn/end` is the che
 - `TurnEndReasonMap` drops the `interrupted` variant.
 - `interruptedTurnClosers()` and its tests disappear.
 - The persistence coordinator's repair hook truncates backend-specific torn/open tail state without appending closers.
-- [Session persistence docs](../../../../packages/session-persistence/session-persistence/README.md) say load returns the last completed turn, plus no partial final turn.
+- [Session persistence docs](../../../../packages/session/session-persistence/README.md) say load returns the last completed turn, plus no partial final turn.
 - Snapshot and contract tests update together with the behavior they pin.
 - The session format version and recorded fixtures are refreshed; non-current stored logs are rejected per the pre-release format policy, with no migration path.
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
index f348e6a99d..2d3eca7441 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
@@ -21,7 +21,7 @@ Status: rejected — 单个轮次可以包含大量真实工作，包括多个
 - `TurnEndReasonMap` 移除 `interrupted` 变体。
 - `interruptedTurnClosers()` 及其测试删除。
 - 持久化协调器的修复钩子截断后端特有的撕裂或未关闭的尾部状态，不追加关闭事件。
-- [会话持久化文档](../../../../packages/session-persistence/session-persistence/README.md)说明加载返回最后一个已完成的轮次，不包含部分最终轮次。
+- [会话持久化文档](../../../../packages/session/session-persistence/README.md)说明加载返回最后一个已完成的轮次，不包含部分最终轮次。
 - 快照与契约测试随其所固定的行为一同更新。
 - 会话格式版本与记录的 fixture（测试前置数据）刷新；按预发布格式策略，非当前版本的存储日志被拒绝，不提供迁移路径。
 
diff --git a/AGENTS.md b/AGENTS.md
index 47a90f0065..7727539bd9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,7 +33,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   guard/       loop-hygiene plugins
   cordis/      self-referential toolset: the agent inspects/mounts plugins in its own runtime
   hooks/       Claude Code/Codex hook bridges + shared wire-protocol library
-  session-persistence/  persistence seam + JSONL/SQLite backends
+  session/     durable session data plane: persistence, projection, titles, reporting
   settings/    user-settings seam + file-backed provider
   credentials/ credential-reference seam + env-over-.env provider
   acp/         automation-only Agent Client Protocol server
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index e0ddc02423..4d10310333 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: e88bdac118e382d91c41c471d03182952d8a4508
-architecture.zh.md: 9314a3fbfc87d467a0f902fa1dae9e8f07e2eb28
+architecture.md: c14d68c47f6ed0786e8fc0b0650dbc67678250fb
+architecture.zh.md: df484762d29e170a5b1ba64f0637c5170c2c5ef4
diff --git a/docs/architecture.md b/docs/architecture.md
index e88bdac118..c14d68c47f 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -41,9 +41,9 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 | `ctx.tasks` | [`tasks/`](../packages/tasks/README.md) | background task registry, generic `task_*` controls |
 | `ctx.workflows` | [`workflow/`](../packages/workflow/README.md) | script-driven multi-agent orchestration |
 | `ctx.goals` | [`goal/`](../packages/goal/README.md) | persisted same-session goals |
-| `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | durable session-log storage |
+| `ctx.sessionPersistence` | [`session/`](../packages/session/README.md) | durable session-log storage |
 | `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | live-preferred exact/filter/trace queries over SQLite FTS, workspace-authorized model tools |
-| `ctx.sessionTitle` | [`session-title/`](../packages/session-title/README.md) | log-backed fallbacks, one optional asynchronous provider |
+| `ctx.sessionTitle` | [`session/session-title`](../packages/session/README.md) | log-backed fallbacks, one optional asynchronous provider |
 | `ctx.settings` | [`settings/`](../packages/settings/README.md) | per-plugin user-settings namespaces layered over composition entries |
 | `ctx.credentials` | [`credentials/`](../packages/credentials/README.md) | named secret references resolved per operation, never inlined in configuration |
 | `ctx.directoryPicker` | [`host/directory-picker`](../packages/host/directory-picker/README.md) | GUI-host directory picking (`native`/`browse` interactions) |
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 9314a3fbfc..df484762d2 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -41,9 +41,9 @@
 | `ctx.tasks` | [`tasks/`](../packages/tasks/README.md) | 后台任务注册表和通用 `task_*` 控制 |
 | `ctx.workflows` | [`workflow/`](../packages/workflow/README.md) | 脚本驱动的多 agent 编排 |
 | `ctx.goals` | [`goal/`](../packages/goal/README.md) | 持久化的同会话目标 |
-| `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | 会话日志的持久化存储 |
+| `ctx.sessionPersistence` | [`session/`](../packages/session/README.md) | 会话日志的持久化存储 |
 | `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | 基于 SQLite 全文搜索的实时优先精确检索／过滤／追踪、经工作区授权的模型工具 |
-| `ctx.sessionTitle` | [`session-title/`](../packages/session-title/README.md) | 基于日志的回退标题和单个可选异步提供方 |
+| `ctx.sessionTitle` | [`session/session-title`](../packages/session/README.md) | 基于日志的回退标题和单个可选异步提供方 |
 | `ctx.settings` | [`settings/`](../packages/settings/README.md) | 按插件划分的用户设置命名空间，分层叠加在装配条目之上 |
 | `ctx.credentials` | [`credentials/`](../packages/credentials/README.md) | 具名密钥引用，按操作解析，绝不内联进配置 |
 | `ctx.directoryPicker` | [`host/directory-picker`](../packages/host/directory-picker/README.md) | GUI 宿主目录选取（`native`／`browse` 交互） |
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 4ed8a260d4..60a19999f3 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -374,27 +374,27 @@ flowchart LR
 | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compact-basic`](../packages/compact/compact-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. |
 | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements. |
 | `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
-| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
 | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. |
 | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. |
-| `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
+| `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session/session-persistence) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
 | `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer. |
 | `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), `apiproxy` | - | Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage. |
-| `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/telemetry/session-telemetry) | [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
+| `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/session/session-telemetry) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
 | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. |
 | `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. |
 | `ctx.workspace` | `core` | [`workspace`](../packages/workspace/workspace) | - | `apiproxy` | - | Owns WorkspaceId-branded records over the domain facility; stable sessionIds accounts drive Host RPC and GUI projections. |
 | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference), [`tool-session-query`](../packages/session-query/tool-session-query) | - | The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations, while the model consumer owns workspace authority and cursor-free rendering. |
 | `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
-| `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session-title/session-title) | [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session-title/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
+| `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
 | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
 | `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | - | [`tool-ask-user`](../packages/ui/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
 | `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
-| `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session-projection/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session-title/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
-| `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session-projection/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
+| `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
+| `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
diff --git a/docs/core-data-structures/persistence.i18n.yaml b/docs/core-data-structures/persistence.i18n.yaml
index fe28a36f40..eccd3f146e 100644
--- a/docs/core-data-structures/persistence.i18n.yaml
+++ b/docs/core-data-structures/persistence.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 docs/core-data-structures/persistence.md
-persistence.md: 3d2bc7ff3b45cd3f38fca0b880a0df9adb928bad
-persistence.zh.md: 035f46d76e0189bd686e991c3d56d486b6f309d5
+persistence.md: 177d596d3d01134266f139b47430e1e5064d04d6
+persistence.zh.md: 6582c0d7d02d1976d5c3ca3322284098130ed4ad
diff --git a/docs/core-data-structures/persistence.md b/docs/core-data-structures/persistence.md
index 3d2bc7ff3b..177d596d3d 100644
--- a/docs/core-data-structures/persistence.md
+++ b/docs/core-data-structures/persistence.md
@@ -4,7 +4,7 @@ English | [中文](persistence.zh.md)
 
 The **durability seam** for the event log. [session.md](session.md) describes the in-memory `Session` — the append-only `SessionEvent` log that is the source of truth. This page describes how that log is made durable: the abstract `SessionPersistence` service, its backends, the flush checkpoint, crash recovery, and the metadata header that travels alongside the log. The event vocabulary the log carries is enumerated, member by member, in the generated [persistence log event catalog](../persistence-catalog.md).
 
-The seam is a textbook [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session-persistence/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted event type** — and two interchangeable backends implementing the same contract. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
+The seam is a textbook [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted event type** — and two interchangeable backends implementing the same contract. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
 
 ## The flush checkpoint
 
@@ -202,5 +202,5 @@ interface SessionPersistenceSnapshot {
 
 Both implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass `runPersistenceContract`, proving the seam is genuinely backend-agnostic:
 
-- **[dsh-session-persistence-jsonl](../../packages/session-persistence/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
-- **[dsh-session-persistence-sqlite](../../packages/session-persistence/session-persistence-sqlite)** — `node:sqlite`, one row per `SessionEvent`. The row shape `(session_id, seq, type, time, data, source_event_seqs, surface_op)` maps 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
+- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
+- **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)** — `node:sqlite`, one row per `SessionEvent`. The row shape `(session_id, seq, type, time, data, source_event_seqs, surface_op)` maps 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
diff --git a/docs/core-data-structures/persistence.zh.md b/docs/core-data-structures/persistence.zh.md
index 035f46d76e..6582c0d7d0 100644
--- a/docs/core-data-structures/persistence.zh.md
+++ b/docs/core-data-structures/persistence.zh.md
@@ -4,7 +4,7 @@
 
 事件日志的**持久性 seam**。[session.md](session.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.md)中逐项列举。
 
-该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session-persistence/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一契约的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
+该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一契约的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
 
 ## flush 检查点
 
@@ -202,5 +202,5 @@ interface SessionPersistenceSnapshot {
 
 两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过 `runPersistenceContract`，证明该 seam 确实与后端无关：
 
-- **[dsh-session-persistence-jsonl](../../packages/session-persistence/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
-- **[dsh-session-persistence-sqlite](../../packages/session-persistence/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行结构 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。
+- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
+- **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行结构 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。
diff --git a/docs/core-data-structures/session-title.i18n.yaml b/docs/core-data-structures/session-title.i18n.yaml
index 67f9ac765b..ed9955472c 100644
--- a/docs/core-data-structures/session-title.i18n.yaml
+++ b/docs/core-data-structures/session-title.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 docs/core-data-structures/session-title.md
-session-title.md: fff1aa1f6be45d0cfc4d7f6a9527ccb93561618f
-session-title.zh.md: 77a0a5e94053c94bf84bbc749cb6e260898b5d00
+session-title.md: 7bced67f07df3f00471f02b766922cdc3e4fd29e
+session-title.zh.md: e8e501d3aafee49395da3d9a8efd4e91a724f09e
diff --git a/docs/core-data-structures/session-title.md b/docs/core-data-structures/session-title.md
index fff1aa1f6b..7bced67f07 100644
--- a/docs/core-data-structures/session-title.md
+++ b/docs/core-data-structures/session-title.md
@@ -2,9 +2,9 @@
 
 English | [中文](session-title.zh.md)
 
-Durable latest-wins title state and the optional asynchronous provider vocabulary owned by [`@deepseek-ai/dsh-session-title`](../../packages/session-title/session-title). The shared LLM helper owns the exact auxiliary request record. Package READMEs own timing, fallback, failure, and fork behavior; the generated [persistence catalog](../persistence-catalog.md) owns the complete event declarations.
+Durable latest-wins title state and the optional asynchronous provider vocabulary owned by [`@deepseek-ai/dsh-session-title`](../../packages/session/session-title). The shared LLM helper owns the exact auxiliary request record. Package READMEs own timing, fallback, failure, and fork behavior; the generated [persistence catalog](../persistence-catalog.md) owns the complete event declarations.
 
-Sources: [`packages/session-title/session-title/src/index.ts`](../../packages/session-title/session-title/src/index.ts), [`packages/session-title/session-title-llm/src/index.ts`](../../packages/session-title/session-title-llm/src/index.ts)
+Sources: [`packages/session/session-title/src/index.ts`](../../packages/session/session-title/src/index.ts), [`packages/session/session-title-llm/src/index.ts`](../../packages/session/session-title-llm/src/index.ts)
 
 ## Durable title state
 
diff --git a/docs/core-data-structures/session-title.zh.md b/docs/core-data-structures/session-title.zh.md
index 77a0a5e940..e8e501d3aa 100644
--- a/docs/core-data-structures/session-title.zh.md
+++ b/docs/core-data-structures/session-title.zh.md
@@ -2,9 +2,9 @@
 
 [English](session-title.md) | 中文
 
-[`@deepseek-ai/dsh-session-title`](../../packages/session-title/session-title) 所拥有的持久、后写覆盖的标题状态与可选异步提供方词汇。共享 LLM（大语言模型）辅助组件负责精确的辅助请求记录。各包 README 负责时序、回退、失败与 fork 行为；生成的[持久化日志事件目录](../persistence-catalog.md)负责完整的事件声明。
+[`@deepseek-ai/dsh-session-title`](../../packages/session/session-title) 所拥有的持久、后写覆盖的标题状态与可选异步提供方词汇。共享 LLM（大语言模型）辅助组件负责精确的辅助请求记录。各包 README 负责时序、回退、失败与 fork 行为；生成的[持久化日志事件目录](../persistence-catalog.md)负责完整的事件声明。
 
-源码：[`packages/session-title/session-title/src/index.ts`](../../packages/session-title/session-title/src/index.ts)、[`packages/session-title/session-title-llm/src/index.ts`](../../packages/session-title/session-title-llm/src/index.ts)
+源码：[`packages/session/session-title/src/index.ts`](../../packages/session/session-title/src/index.ts)、[`packages/session/session-title-llm/src/index.ts`](../../packages/session/session-title-llm/src/index.ts)
 
 ## 持久标题状态
 
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 3845c2cb1a..daf2ea7ab2 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -557,7 +557,7 @@ Source: [`packages/core/session/src/types.ts:304`](../packages/core/session/src/
 
 Types: [SessionTitleEventData](core-data-structures/session-title.md)
 
-Source: [`packages/session-title/session-title/src/index.ts:100`](../packages/session-title/session-title/src/index.ts)
+Source: [`packages/session/session-title/src/index.ts:100`](../packages/session/session-title/src/index.ts)
 
 #### `session/title-llm-request` — log-only
 
@@ -568,7 +568,7 @@ Source: [`packages/session-title/session-title/src/index.ts:100`](../packages/se
 
 Types: [SessionTitleLlmRequestEventData](core-data-structures/session-title.md)
 
-Source: [`packages/session-title/session-title-llm/src/index.ts:43`](../packages/session-title/session-title-llm/src/index.ts)
+Source: [`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts)
 
 ### `step/*`
 
diff --git a/knip.json b/knip.json
index d154cd646b..0e82064200 100644
--- a/knip.json
+++ b/knip.json
@@ -283,7 +283,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/telemetry/session-telemetry-otel": {
+    "packages/session/session-telemetry-otel": {
       "entry": [
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
@@ -414,7 +414,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/session-title/session-title-first-message-llm": {
+    "packages/session/session-title-first-message-llm": {
       "entry": [
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
@@ -434,7 +434,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/session-persistence/session-checkpoint-policy": {
+    "packages/session/session-checkpoint-policy": {
       "entry": [
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 143e7704c2..44dd906b76 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 98fc87a6b26a42c58bb63cba96cd6af384f3ec71
-README.zh.md: 86a316dca77efd5e5eb59e3fca7d53890a34901d
+README.md: 9f8b3f936af6392239218d5389c91c87d0f7d1f9
+README.zh.md: 2f4e86cb541a8a34762b36cac57f456de96cac5d
diff --git a/packages/README.md b/packages/README.md
index 98fc87a6b2..9f8b3f936a 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -39,13 +39,10 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`bundle/`](bundle/README.md) | Installable `dsh --profile` patch layers | Product — stable surface |
 | [`cordis/`](cordis/README.md) | Cordis runtime integration: self-inspection, temporary Plugins, restricted repository Plugin loading | Product — stable surface |
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
-| [`session-persistence/`](session-persistence/README.md) | Persistence seam + JSONL/SQLite backends | Product — stable surface |
-| [`session-projection/`](session-projection/README.md) | Projection seam: domain fold units serve whole values | Product — stable surface |
+| [`session/`](session/README.md) | Durable session data plane: persistence seam + JSONL/SQLite backends, projection seam, log-backed titles, session reporting | Product — stable surface |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable surface |
-| [`session-title/`](session-title/README.md) | Log-backed session titles: fallback service and opt-in LLM providers | Product — stable surface |
 | [`settings/`](settings/README.md) | User-settings seam + file-backed provider | Product — stable surface |
 | [`credentials/`](credentials/README.md) | Credential-reference seam + env-over-`.env` provider | Product — stable surface |
-| [`telemetry/`](telemetry/README.md) | Session reporting: capture/redact seam, OTel backend | Product — stable surface |
 | [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable surface |
 | [`workspace/`](workspace/README.md) | Workspace entity | Product — stable surface |
 | [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 86a316dca7..2f4e86cb54 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -39,13 +39,10 @@
 | [`bundle/`](bundle/README.md) | 可安装的 `dsh --profile` 补丁层 | 产品：稳定表面 |
 | [`cordis/`](cordis/README.md) | Cordis 运行时集成：自检、临时 Plugin、受限 repository Plugin 加载 | 产品：稳定表面 |
 | [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定表面 |
-| [`session-persistence/`](session-persistence/README.md) | 持久化 seam + JSONL/SQLite 后端 | 产品：稳定表面 |
-| [`session-projection/`](session-projection/README.md) | 投影 seam：领域折叠单元供给全量值 | 产品：稳定表面 |
+| [`session/`](session/README.md) | 持久会话数据平面：持久化 seam + JSONL/SQLite 后端、投影 seam、日志支持的标题、会话上报 | 产品：稳定表面 |
 | [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 |
-| [`session-title/`](session-title/README.md) | 日志支撑的会话标题：回退服务与选用 LLM 提供方 | 产品：稳定表面 |
 | [`settings/`](settings/README.md) | 用户设置 seam + 文件 provider | 产品：稳定表面 |
 | [`credentials/`](credentials/README.md) | 凭据引用 seam + 环境叠加 `.env` provider | 产品：稳定表面 |
-| [`telemetry/`](telemetry/README.md) | 会话上报：捕获／脱敏 seam、OTel 后端 | 产品：稳定表面 |
 | [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 |
 | [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定表面 |
 | [`sdk/`](sdk/README.md) | 项目 SDK 工具 | 产品：稳定表面 |
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index f93546e855..71cfb229a9 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -30,10 +30,10 @@
       "path": "../../compact/compact"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
-      "path": "../../session-title/session-title"
+      "path": "../../session/session-title"
     },
     {
       "path": "../../llm/llm"
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
index 04b265bdd5..0505786841 100644
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../runtime"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../llm/token-meter"
diff --git a/packages/core/agent-loop/tsconfig.json b/packages/core/agent-loop/tsconfig.json
index 0949f18453..c3504e4eb4 100644
--- a/packages/core/agent-loop/tsconfig.json
+++ b/packages/core/agent-loop/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../core/system-prompt"
diff --git a/packages/examples/acp-demo/tests/built-bin.e2e.ts b/packages/examples/acp-demo/tests/built-bin.e2e.ts
index 6f67baa5a5..d09a0e333d 100644
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -34,8 +34,8 @@ const dshPackages = [
   'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt',
   'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash',
   'bash/bash-local', 'bash/tool-bash', 'subprocess/subprocess', 'subprocess/subprocess-local', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
-  'session-persistence/session-persistence',
-  'session-persistence/session-checkpoint-policy', 'session-persistence/session-persistence-jsonl',
+  'session/session-persistence',
+  'session/session-checkpoint-policy', 'session/session-persistence-jsonl',
   'acp/acp', 'examples/acp-demo', 'util/paths',
 ]
 const vendorPackages = [
diff --git a/packages/examples/acp-demo/tsconfig.json b/packages/examples/acp-demo/tsconfig.json
index 6eeffc5eef..34b48fc46a 100644
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -39,10 +39,10 @@
       "path": "../../context/workspace-context"
     },
     {
-      "path": "../../session-persistence/session-checkpoint-policy"
+      "path": "../../session/session-checkpoint-policy"
     },
     {
-      "path": "../../session-persistence/session-persistence-jsonl"
+      "path": "../../session/session-persistence-jsonl"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/examples/agent-spine-demo/tsconfig.json b/packages/examples/agent-spine-demo/tsconfig.json
index f245e9f4d0..e31863d3b1 100644
--- a/packages/examples/agent-spine-demo/tsconfig.json
+++ b/packages/examples/agent-spine-demo/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-title/session-title"
+      "path": "../../session/session-title"
     },
     {
       "path": "../../core/system-prompt"
diff --git a/packages/goal/goal/tsconfig.json b/packages/goal/goal/tsconfig.json
index f106707bd3..1484f5a4b9 100644
--- a/packages/goal/goal/tsconfig.json
+++ b/packages/goal/goal/tsconfig.json
@@ -33,7 +33,7 @@
       "path": "../../core/agent"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../typert/type-meta"
diff --git a/packages/hooks/hooks-claude/tsconfig.json b/packages/hooks/hooks-claude/tsconfig.json
index 445d0f68b1..e254c7146f 100644
--- a/packages/hooks/hooks-claude/tsconfig.json
+++ b/packages/hooks/hooks-claude/tsconfig.json
@@ -30,7 +30,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../subagent/subagent"
diff --git a/packages/hooks/hooks-codex/tsconfig.json b/packages/hooks/hooks-codex/tsconfig.json
index 3bd9bd91e5..46e8216404 100644
--- a/packages/hooks/hooks-codex/tsconfig.json
+++ b/packages/hooks/hooks-codex/tsconfig.json
@@ -30,7 +30,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../llm/llm"
diff --git a/packages/host/apiproxy/tsconfig.json b/packages/host/apiproxy/tsconfig.json
index 8686a9e468..58c63f5669 100644
--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -42,19 +42,19 @@
       "path": "../../core/tools"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
-      "path": "../../session-projection/session-projection-cache"
+      "path": "../../session/session-projection-cache"
     },
     {
       "path": "../../session-query/session-query"
     },
     {
-      "path": "../../session-title/session-title"
+      "path": "../../session/session-title"
     },
     {
       "path": "../../session-query/session-query"
diff --git a/packages/llm/token-meter/tsconfig.json b/packages/llm/token-meter/tsconfig.json
index b8b32e36fa..404607f87a 100644
--- a/packages/llm/token-meter/tsconfig.json
+++ b/packages/llm/token-meter/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../compact/compact"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/plan/plan-mode/tsconfig.json b/packages/plan/plan-mode/tsconfig.json
index a9b2d4dccf..6fa3cffbbc 100644
--- a/packages/plan/plan-mode/tsconfig.json
+++ b/packages/plan/plan-mode/tsconfig.json
@@ -33,7 +33,7 @@
       "path": "../../ui/commands"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/sdk/helper/tsconfig.json b/packages/sdk/helper/tsconfig.json
index 528b370a5c..f33033f47f 100644
--- a/packages/sdk/helper/tsconfig.json
+++ b/packages/sdk/helper/tsconfig.json
@@ -19,10 +19,10 @@
       "path": "../../hooks/hooks-codex"
     },
     {
-      "path": "../../session-persistence/session-persistence-jsonl"
+      "path": "../../session/session-persistence-jsonl"
     },
     {
-      "path": "../../session-persistence/session-persistence-sqlite"
+      "path": "../../session/session-persistence-sqlite"
     },
     {
       "path": "../../subagent/tool-subagent"
diff --git a/packages/session-persistence/README.i18n.yaml b/packages/session-persistence/README.i18n.yaml
deleted file mode 100644
index 85eb2bd27d..0000000000
--- a/packages/session-persistence/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/session-persistence/README.md
-README.md: 060f757b3568318b0be4b01b3a10d019d28eac3b
-README.zh.md: 67022565f7dabcbbccee30d5ce60fa559088ca39
diff --git a/packages/session-persistence/README.md b/packages/session-persistence/README.md
deleted file mode 100644
index 060f757b35..0000000000
--- a/packages/session-persistence/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# session-persistence/ — persistence capability family
-
-English | [中文](README.zh.md)
-
-This family defines durable session persistence, semantic checkpoint policy, and the shipped storage backends.
-
-| Package | Role | ctx key |
-|---|---|---|
-| [`session-persistence/`](session-persistence/README.md) | Defines the persistence service and shared write coordination | `ctx.sessionPersistence` |
-| [`session-checkpoint-policy/`](session-checkpoint-policy/README.md) | Applies semantic durability checkpoints | wraps `ctx.llm` and `ctx.tools` |
-| [`session-persistence-jsonl/`](session-persistence-jsonl/README.md) | Persists sessions in JSONL files | registers on `ctx.sessionPersistence` |
-| [`session-persistence-sqlite/`](session-persistence-sqlite/README.md) | Persists sessions in SQLite | registers on `ctx.sessionPersistence` |
-
-The [session-persistence decision](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md) records the family design.
diff --git a/packages/session-persistence/README.zh.md b/packages/session-persistence/README.zh.md
deleted file mode 100644
index 67022565f7..0000000000
--- a/packages/session-persistence/README.zh.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# session-persistence/：持久化能力家族
-
-[English](README.md) | 中文
-
-本家族定义持久会话数据的持久化机制、语义检查点策略以及随产品交付的存储后端。
-
-| 包 | 职责 | ctx 键 |
-|---|---|---|
-| [`session-persistence/`](session-persistence/README.md) | 定义持久化服务和共享写入协调机制 | `ctx.sessionPersistence` |
-| [`session-checkpoint-policy/`](session-checkpoint-policy/README.md) | 应用语义持久性检查点 | 包装 `ctx.llm` 和 `ctx.tools` |
-| [`session-persistence-jsonl/`](session-persistence-jsonl/README.md) | 将会话持久化到 JSONL 文件 | 注册到 `ctx.sessionPersistence` |
-| [`session-persistence-sqlite/`](session-persistence-sqlite/README.md) | 将会话持久化到 SQLite | 注册到 `ctx.sessionPersistence` |
-
-[会话持久化决策](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)记录了该家族的设计。
diff --git a/packages/session-projection/README.i18n.yaml b/packages/session-projection/README.i18n.yaml
deleted file mode 100644
index 5e03069b99..0000000000
--- a/packages/session-projection/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/session-projection/README.md
-README.md: f1fc8337bbea6663915c19f39fdf02f14190370d
-README.zh.md: 3323166f496fabafabcd96abeaec707a28ce552a
diff --git a/packages/session-projection/README.md b/packages/session-projection/README.md
deleted file mode 100644
index f1fc8337bb..0000000000
--- a/packages/session-projection/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# session-projection/ — session projection capability family
-
-English | [中文](README.zh.md)
-
-This family serves current, log-derived per-session state to client carriers.
-
-| Package | Role | ctx key |
-|---|---|---|
-| [`session-projection/`](session-projection/README.md) | Defines and drives session projection units | `ctx.sessionProjections` |
-| [`session-projection-cache/`](session-projection-cache/README.md) | Persists and restores projection checkpoints | `ctx.sessionProjectionCache` |
diff --git a/packages/session-projection/README.zh.md b/packages/session-projection/README.zh.md
deleted file mode 100644
index 3323166f49..0000000000
--- a/packages/session-projection/README.zh.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# session-projection/：会话投影能力家族
-
-[English](README.md) | 中文
-
-本家族向客户端载体提供从日志派生的当前逐会话状态。
-
-| 包 | 职责 | ctx 键 |
-|---|---|---|
-| [`session-projection/`](session-projection/README.md) | 定义并驱动会话投影单元 | `ctx.sessionProjections` |
-| [`session-projection-cache/`](session-projection-cache/README.md) | 持久化并恢复投影检查点 | `ctx.sessionProjectionCache` |
diff --git a/packages/session-query/session-query-sqlite/tsconfig.json b/packages/session-query/session-query-sqlite/tsconfig.json
index 1f09565c4a..2a74d8e326 100644
--- a/packages/session-query/session-query-sqlite/tsconfig.json
+++ b/packages/session-query/session-query-sqlite/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/session-query/session-query/tsconfig.json b/packages/session-query/session-query/tsconfig.json
index 0f17353fee..9e661c1c2c 100644
--- a/packages/session-query/session-query/tsconfig.json
+++ b/packages/session-query/session-query/tsconfig.json
@@ -24,10 +24,10 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-title/session-title"
+      "path": "../../session/session-title"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/session-title/README.md b/packages/session-title/README.md
deleted file mode 100644
index c2ccc1cd6d..0000000000
--- a/packages/session-title/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# session-title/ — log-backed session-title capability family
-
-English | [中文](README.zh.md)
-
-This family derives durable session titles from the session log, with an optional model-backed provider.
-
-| Package | Role | ctx key |
-|---|---|---|
-| [`session-title/`](session-title/README.md) | Owns title state, fallback behavior, provider registration, and refresh | `ctx.sessionTitle` |
-| [`session-title-llm/`](session-title-llm/README.md) | Provides shared model-backed title generation | — |
-| [`session-title-first-message-llm/`](session-title-first-message-llm/README.md) | Titles a session from its first eligible human message | registers on `ctx.sessionTitle` |
-| [`session-title-all-messages-llm/`](session-title-all-messages-llm/README.md) | Titles a session from all eligible human messages | registers on `ctx.sessionTitle` |
-
-Deployments may register one model-backed provider; the service retains a deterministic fallback when none is present.
diff --git a/packages/session-title/README.zh.md b/packages/session-title/README.zh.md
deleted file mode 100644
index b8df266a86..0000000000
--- a/packages/session-title/README.zh.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# session-title/：日志支持的会话标题能力族
-
-[English](README.md) | 中文
-
-该包族从会话日志派生持久会话标题，并支持可选的模型后端 provider。
-
-| 包 | 职责 | ctx key |
-|---|---|---|
-| [`session-title/`](session-title/README.md) | 负责标题状态、回退行为、provider 注册与刷新 | `ctx.sessionTitle` |
-| [`session-title-llm/`](session-title-llm/README.md) | 提供共享的模型标题生成能力 | — |
-| [`session-title-first-message-llm/`](session-title-first-message-llm/README.md) | 根据第一条合格的人类消息生成会话标题 | 注册到 `ctx.sessionTitle` |
-| [`session-title-all-messages-llm/`](session-title-all-messages-llm/README.md) | 根据所有合格的人类消息生成会话标题 | 注册到 `ctx.sessionTitle` |
-
-部署可注册一个模型后端 provider；未注册时，服务仍提供确定性回退。
diff --git a/packages/session-title/README.i18n.yaml b/packages/session/README.i18n.yaml
similarity index 71%
rename from packages/session-title/README.i18n.yaml
rename to packages/session/README.i18n.yaml
index 2c5d1f2788..b500a64611 100644
--- a/packages/session-title/README.i18n.yaml
+++ b/packages/session/README.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 packages/session-title/README.md
-README.md: c2ccc1cd6d329a58f673a9ea5d47ce2f35c9dc41
-README.zh.md: b8df266a861da5cb20a76d0738bba4993218c3d5
+#   pnpm run verify-translation-pairing --write packages/session/README.md
+README.md: 45eff16ad57ec1ccc8ebdd55db82f41b5adfc111
+README.zh.md: 2d67e28ef169f4e4376b2a644a3b842e5835df04
diff --git a/packages/session/README.md b/packages/session/README.md
new file mode 100644
index 0000000000..45eff16ad5
--- /dev/null
+++ b/packages/session/README.md
@@ -0,0 +1,49 @@
+# session/ — durable session data plane
+
+English | [中文](README.zh.md)
+
+The durable family around `core/session`'s live in-memory service: the persistence seam with its storage backends and checkpoint policy, the projection seam that serves whole log-derived values, log-backed titles, and outbound session telemetry. All **product** packages. `session-query/` remains a sibling group: the read/tool surface is consumed independently of persistence internals.
+
+## Persistence
+
+Durable session persistence, semantic checkpoint policy, and the shipped storage backends.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`session-persistence/`](session-persistence/README.md) | Defines the persistence service and shared write coordination | `ctx.sessionPersistence` |
+| [`session-checkpoint-policy/`](session-checkpoint-policy/README.md) | Applies semantic durability checkpoints | wraps `ctx.llm` and `ctx.tools` |
+| [`session-persistence-jsonl/`](session-persistence-jsonl/README.md) | Persists sessions in JSONL files | registers on `ctx.sessionPersistence` |
+| [`session-persistence-sqlite/`](session-persistence-sqlite/README.md) | Persists sessions in SQLite | registers on `ctx.sessionPersistence` |
+
+The [session-persistence decision](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md) records the persistence design.
+
+## Projection
+
+Serves current, log-derived per-session state to client carriers.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`session-projection/`](session-projection/README.md) | Defines and drives session projection units | `ctx.sessionProjections` |
+| [`session-projection-cache/`](session-projection-cache/README.md) | Persists and restores projection checkpoints | `ctx.sessionProjectionCache` |
+
+## Titles
+
+Derives durable session titles from the session log, with an optional model-backed provider.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`session-title/`](session-title/README.md) | Owns title state, fallback behavior, provider registration, and refresh | `ctx.sessionTitle` |
+| [`session-title-llm/`](session-title-llm/README.md) | Provides shared model-backed title generation | — |
+| [`session-title-first-message-llm/`](session-title-first-message-llm/README.md) | Titles a session from its first eligible human message | registers on `ctx.sessionTitle` |
+| [`session-title-all-messages-llm/`](session-title-all-messages-llm/README.md) | Titles a session from all eligible human messages | registers on `ctx.sessionTitle` |
+
+Deployments may register one model-backed provider; the service retains a deterministic fallback when none is present.
+
+## Telemetry
+
+Projects session activity into outbound telemetry and delegates delivery to a configured reporting backend. The [telemetry decision](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md) records the reporting boundary; the [mode decision](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md) records immediate, feedback-gated, and disabled delivery.
+
+| Package | Role |
+|---|---|
+| [`session-telemetry/`](session-telemetry/README.md) | Defines capture, redaction, projection, and live or on-demand backend delivery. |
+| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | Delivers telemetry through OpenTelemetry logs in `FULL`, `FEEDBACK_ONLY`, or `DISABLED` mode. |
diff --git a/packages/session/README.zh.md b/packages/session/README.zh.md
new file mode 100644
index 0000000000..2d67e28ef1
--- /dev/null
+++ b/packages/session/README.zh.md
@@ -0,0 +1,49 @@
+# session/：持久会话数据平面
+
+[English](README.md) | 中文
+
+围绕 `core/session` 常驻内存实时服务的持久家族：持久化 seam 连同其存储后端与检查点策略、供出日志派生全量值的投影 seam、日志支持的标题，以及外发会话遥测。全部都是**产品**包（package）。`session-query/` 仍是同级独立组：读取／工具面的消费不依赖持久化内部实现。
+
+## 持久化
+
+持久会话数据的持久化机制、语义检查点策略以及随产品交付的存储后端。
+
+| 包 | 职责 | ctx 键 |
+|---|---|---|
+| [`session-persistence/`](session-persistence/README.md) | 定义持久化服务和共享写入协调机制 | `ctx.sessionPersistence` |
+| [`session-checkpoint-policy/`](session-checkpoint-policy/README.md) | 应用语义持久性检查点 | 包装 `ctx.llm` 和 `ctx.tools` |
+| [`session-persistence-jsonl/`](session-persistence-jsonl/README.md) | 将会话持久化到 JSONL 文件 | 注册到 `ctx.sessionPersistence` |
+| [`session-persistence-sqlite/`](session-persistence-sqlite/README.md) | 将会话持久化到 SQLite | 注册到 `ctx.sessionPersistence` |
+
+[会话持久化决策](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)记录了持久化设计。
+
+## 投影
+
+向客户端载体提供从日志派生的当前逐会话状态。
+
+| 包 | 职责 | ctx 键 |
+|---|---|---|
+| [`session-projection/`](session-projection/README.md) | 定义并驱动会话投影单元 | `ctx.sessionProjections` |
+| [`session-projection-cache/`](session-projection-cache/README.md) | 持久化并恢复投影检查点 | `ctx.sessionProjectionCache` |
+
+## 标题
+
+从会话日志派生持久会话标题，并支持可选的模型后端 provider。
+
+| 包 | 职责 | ctx 键 |
+|---|---|---|
+| [`session-title/`](session-title/README.md) | 负责标题状态、回退行为、provider 注册与刷新 | `ctx.sessionTitle` |
+| [`session-title-llm/`](session-title-llm/README.md) | 提供共享的模型标题生成能力 | — |
+| [`session-title-first-message-llm/`](session-title-first-message-llm/README.md) | 根据第一条合格的人类消息生成会话标题 | 注册到 `ctx.sessionTitle` |
+| [`session-title-all-messages-llm/`](session-title-all-messages-llm/README.md) | 根据所有合格的人类消息生成会话标题 | 注册到 `ctx.sessionTitle` |
+
+部署可注册一个模型后端 provider；未注册时，服务仍提供确定性回退。
+
+## 遥测
+
+将会话活动投影为外发遥测，并将投递委派给配置的上报后端。[遥测决策](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)记录上报边界；[模式决策](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)记录即时、反馈门控与禁用投递。
+
+| 包 | 职责 |
+|---|---|
+| [`session-telemetry/`](session-telemetry/README.md) | 定义捕获、脱敏、投影，以及实时或按需后端投递。 |
+| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | 通过 OpenTelemetry 日志以 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 模式投递遥测。 |
diff --git a/packages/session-persistence/session-checkpoint-policy/README.i18n.yaml b/packages/session/session-checkpoint-policy/README.i18n.yaml
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/README.i18n.yaml
rename to packages/session/session-checkpoint-policy/README.i18n.yaml
diff --git a/packages/session-persistence/session-checkpoint-policy/README.md b/packages/session/session-checkpoint-policy/README.md
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/README.md
rename to packages/session/session-checkpoint-policy/README.md
diff --git a/packages/session-persistence/session-checkpoint-policy/README.zh.md b/packages/session/session-checkpoint-policy/README.zh.md
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/README.zh.md
rename to packages/session/session-checkpoint-policy/README.zh.md
diff --git a/packages/session-persistence/session-checkpoint-policy/package.json b/packages/session/session-checkpoint-policy/package.json
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/package.json
rename to packages/session/session-checkpoint-policy/package.json
diff --git a/packages/session-persistence/session-checkpoint-policy/src/index.ts b/packages/session/session-checkpoint-policy/src/index.ts
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/src/index.ts
rename to packages/session/session-checkpoint-policy/src/index.ts
diff --git a/packages/session-persistence/session-checkpoint-policy/src/invariant.ts b/packages/session/session-checkpoint-policy/src/invariant.ts
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/src/invariant.ts
rename to packages/session/session-checkpoint-policy/src/invariant.ts
diff --git a/packages/session-persistence/session-checkpoint-policy/tests/crash-recovery.e2e.ts b/packages/session/session-checkpoint-policy/tests/crash-recovery.e2e.ts
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/tests/crash-recovery.e2e.ts
rename to packages/session/session-checkpoint-policy/tests/crash-recovery.e2e.ts
diff --git a/packages/session-persistence/session-checkpoint-policy/tests/fixtures/crash-child.ts b/packages/session/session-checkpoint-policy/tests/fixtures/crash-child.ts
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/tests/fixtures/crash-child.ts
rename to packages/session/session-checkpoint-policy/tests/fixtures/crash-child.ts
diff --git a/packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts b/packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
similarity index 100%
rename from packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
rename to packages/session/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts
diff --git a/packages/session-persistence/session-checkpoint-policy/tsconfig.json b/packages/session/session-checkpoint-policy/tsconfig.json
similarity index 89%
rename from packages/session-persistence/session-checkpoint-policy/tsconfig.json
rename to packages/session/session-checkpoint-policy/tsconfig.json
index 1b81e05951..400f67a53b 100644
--- a/packages/session-persistence/session-checkpoint-policy/tsconfig.json
+++ b/packages/session/session-checkpoint-policy/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/session-persistence/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/README.i18n.yaml
rename to packages/session/session-persistence-jsonl/README.i18n.yaml
diff --git a/packages/session-persistence/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/README.md
rename to packages/session/session-persistence-jsonl/README.md
diff --git a/packages/session-persistence/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/README.zh.md
rename to packages/session/session-persistence-jsonl/README.zh.md
diff --git a/packages/session-persistence/session-persistence-jsonl/package.json b/packages/session/session-persistence-jsonl/package.json
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/package.json
rename to packages/session/session-persistence-jsonl/package.json
diff --git a/packages/session-persistence/session-persistence-jsonl/src/format.ts b/packages/session/session-persistence-jsonl/src/format.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/format.ts
rename to packages/session/session-persistence-jsonl/src/format.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/index.ts
rename to packages/session/session-persistence-jsonl/src/index.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/invariant.ts b/packages/session/session-persistence-jsonl/src/invariant.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/invariant.ts
rename to packages/session/session-persistence-jsonl/src/invariant.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/win32.ts b/packages/session/session-persistence-jsonl/src/win32.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/win32.ts
rename to packages/session/session-persistence-jsonl/src/win32.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/zstd-private-decoder.ts b/packages/session/session-persistence-jsonl/src/zstd-private-decoder.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/zstd-private-decoder.ts
rename to packages/session/session-persistence-jsonl/src/zstd-private-decoder.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/zstd-public-decoder.ts b/packages/session/session-persistence-jsonl/src/zstd-public-decoder.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/zstd-public-decoder.ts
rename to packages/session/session-persistence-jsonl/src/zstd-public-decoder.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/src/zstd.ts b/packages/session/session-persistence-jsonl/src/zstd.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/src/zstd.ts
rename to packages/session/session-persistence-jsonl/src/zstd.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
rename to packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts b/packages/session/session-persistence-jsonl/tests/win32.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts
rename to packages/session/session-persistence-jsonl/tests/win32.spec.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts b/packages/session/session-persistence-jsonl/tests/zstd.compat.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts
rename to packages/session/session-persistence-jsonl/tests/zstd.compat.spec.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts b/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-jsonl/tests/zstd.spec.ts
rename to packages/session/session-persistence-jsonl/tests/zstd.spec.ts
diff --git a/packages/session-persistence/session-persistence-jsonl/tsconfig.json b/packages/session/session-persistence-jsonl/tsconfig.json
similarity index 87%
rename from packages/session-persistence/session-persistence-jsonl/tsconfig.json
rename to packages/session/session-persistence-jsonl/tsconfig.json
index 044156938b..240c0b0ea9 100644
--- a/packages/session-persistence/session-persistence-jsonl/tsconfig.json
+++ b/packages/session/session-persistence-jsonl/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/session-persistence/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/README.i18n.yaml
rename to packages/session/session-persistence-sqlite/README.i18n.yaml
diff --git a/packages/session-persistence/session-persistence-sqlite/README.md b/packages/session/session-persistence-sqlite/README.md
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/README.md
rename to packages/session/session-persistence-sqlite/README.md
diff --git a/packages/session-persistence/session-persistence-sqlite/README.zh.md b/packages/session/session-persistence-sqlite/README.zh.md
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/README.zh.md
rename to packages/session/session-persistence-sqlite/README.zh.md
diff --git a/packages/session-persistence/session-persistence-sqlite/package.json b/packages/session/session-persistence-sqlite/package.json
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/package.json
rename to packages/session/session-persistence-sqlite/package.json
diff --git a/packages/session-persistence/session-persistence-sqlite/src/index.ts b/packages/session/session-persistence-sqlite/src/index.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/src/index.ts
rename to packages/session/session-persistence-sqlite/src/index.ts
diff --git a/packages/session-persistence/session-persistence-sqlite/src/invariant.ts b/packages/session/session-persistence-sqlite/src/invariant.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/src/invariant.ts
rename to packages/session/session-persistence-sqlite/src/invariant.ts
diff --git a/packages/session-persistence/session-persistence-sqlite/src/schema.ts b/packages/session/session-persistence-sqlite/src/schema.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/src/schema.ts
rename to packages/session/session-persistence-sqlite/src/schema.ts
diff --git a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts b/packages/session/session-persistence-sqlite/tests/sqlite.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
rename to packages/session/session-persistence-sqlite/tests/sqlite.spec.ts
diff --git a/packages/session-persistence/session-persistence-sqlite/tsconfig.json b/packages/session/session-persistence-sqlite/tsconfig.json
similarity index 87%
rename from packages/session-persistence/session-persistence-sqlite/tsconfig.json
rename to packages/session/session-persistence-sqlite/tsconfig.json
index 044156938b..240c0b0ea9 100644
--- a/packages/session-persistence/session-persistence-sqlite/tsconfig.json
+++ b/packages/session/session-persistence-sqlite/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/session-persistence/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
similarity index 100%
rename from packages/session-persistence/session-persistence/README.i18n.yaml
rename to packages/session/session-persistence/README.i18n.yaml
diff --git a/packages/session-persistence/session-persistence/README.md b/packages/session/session-persistence/README.md
similarity index 100%
rename from packages/session-persistence/session-persistence/README.md
rename to packages/session/session-persistence/README.md
diff --git a/packages/session-persistence/session-persistence/README.zh.md b/packages/session/session-persistence/README.zh.md
similarity index 100%
rename from packages/session-persistence/session-persistence/README.zh.md
rename to packages/session/session-persistence/README.zh.md
diff --git a/packages/session-persistence/session-persistence/package.json b/packages/session/session-persistence/package.json
similarity index 100%
rename from packages/session-persistence/session-persistence/package.json
rename to packages/session/session-persistence/package.json
diff --git a/packages/session-persistence/session-persistence/src/coordinator.ts b/packages/session/session-persistence/src/coordinator.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/coordinator.ts
rename to packages/session/session-persistence/src/coordinator.ts
diff --git a/packages/session-persistence/session-persistence/src/index.ts b/packages/session/session-persistence/src/index.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/index.ts
rename to packages/session/session-persistence/src/index.ts
diff --git a/packages/session-persistence/session-persistence/src/invariant.ts b/packages/session/session-persistence/src/invariant.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/invariant.ts
rename to packages/session/session-persistence/src/invariant.ts
diff --git a/packages/session-persistence/session-persistence/src/preparations.ts b/packages/session/session-persistence/src/preparations.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/preparations.ts
rename to packages/session/session-persistence/src/preparations.ts
diff --git a/packages/session-persistence/session-persistence/src/revision.ts b/packages/session/session-persistence/src/revision.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/revision.ts
rename to packages/session/session-persistence/src/revision.ts
diff --git a/packages/session-persistence/session-persistence/src/write-behind.ts b/packages/session/session-persistence/src/write-behind.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/src/write-behind.ts
rename to packages/session/session-persistence/src/write-behind.ts
diff --git a/packages/session-persistence/session-persistence/tests/contract.ts b/packages/session/session-persistence/tests/contract.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/tests/contract.ts
rename to packages/session/session-persistence/tests/contract.ts
diff --git a/packages/session-persistence/session-persistence/tests/coordinator-contract.ts b/packages/session/session-persistence/tests/coordinator-contract.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/tests/coordinator-contract.ts
rename to packages/session/session-persistence/tests/coordinator-contract.ts
diff --git a/packages/session-persistence/session-persistence/tests/persistence.spec.ts b/packages/session/session-persistence/tests/persistence.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/tests/persistence.spec.ts
rename to packages/session/session-persistence/tests/persistence.spec.ts
diff --git a/packages/session-persistence/session-persistence/tests/preparations.spec.ts b/packages/session/session-persistence/tests/preparations.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/tests/preparations.spec.ts
rename to packages/session/session-persistence/tests/preparations.spec.ts
diff --git a/packages/session-persistence/session-persistence/tests/write-behind.spec.ts b/packages/session/session-persistence/tests/write-behind.spec.ts
similarity index 100%
rename from packages/session-persistence/session-persistence/tests/write-behind.spec.ts
rename to packages/session/session-persistence/tests/write-behind.spec.ts
diff --git a/packages/session-persistence/session-persistence/tsconfig.json b/packages/session/session-persistence/tsconfig.json
similarity index 100%
rename from packages/session-persistence/session-persistence/tsconfig.json
rename to packages/session/session-persistence/tsconfig.json
diff --git a/packages/session-projection/session-projection-cache/README.i18n.yaml b/packages/session/session-projection-cache/README.i18n.yaml
similarity index 100%
rename from packages/session-projection/session-projection-cache/README.i18n.yaml
rename to packages/session/session-projection-cache/README.i18n.yaml
diff --git a/packages/session-projection/session-projection-cache/README.md b/packages/session/session-projection-cache/README.md
similarity index 100%
rename from packages/session-projection/session-projection-cache/README.md
rename to packages/session/session-projection-cache/README.md
diff --git a/packages/session-projection/session-projection-cache/README.zh.md b/packages/session/session-projection-cache/README.zh.md
similarity index 100%
rename from packages/session-projection/session-projection-cache/README.zh.md
rename to packages/session/session-projection-cache/README.zh.md
diff --git a/packages/session-projection/session-projection-cache/package.json b/packages/session/session-projection-cache/package.json
similarity index 100%
rename from packages/session-projection/session-projection-cache/package.json
rename to packages/session/session-projection-cache/package.json
diff --git a/packages/session-projection/session-projection-cache/src/index.ts b/packages/session/session-projection-cache/src/index.ts
similarity index 100%
rename from packages/session-projection/session-projection-cache/src/index.ts
rename to packages/session/session-projection-cache/src/index.ts
diff --git a/packages/session-projection/session-projection-cache/src/invariant.ts b/packages/session/session-projection-cache/src/invariant.ts
similarity index 100%
rename from packages/session-projection/session-projection-cache/src/invariant.ts
rename to packages/session/session-projection-cache/src/invariant.ts
diff --git a/packages/session-projection/session-projection-cache/src/spec.ts b/packages/session/session-projection-cache/src/spec.ts
similarity index 100%
rename from packages/session-projection/session-projection-cache/src/spec.ts
rename to packages/session/session-projection-cache/src/spec.ts
diff --git a/packages/session-projection/session-projection-cache/tests/cache.spec.ts b/packages/session/session-projection-cache/tests/cache.spec.ts
similarity index 100%
rename from packages/session-projection/session-projection-cache/tests/cache.spec.ts
rename to packages/session/session-projection-cache/tests/cache.spec.ts
diff --git a/packages/session-projection/session-projection-cache/tsconfig.json b/packages/session/session-projection-cache/tsconfig.json
similarity index 90%
rename from packages/session-projection/session-projection-cache/tsconfig.json
rename to packages/session/session-projection-cache/tsconfig.json
index baba6c805b..cf253dbe79 100644
--- a/packages/session-projection/session-projection-cache/tsconfig.json
+++ b/packages/session/session-projection-cache/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../session-persistence"
     },
     {
       "path": "../session-projection"
diff --git a/packages/session-projection/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
similarity index 100%
rename from packages/session-projection/session-projection/README.i18n.yaml
rename to packages/session/session-projection/README.i18n.yaml
diff --git a/packages/session-projection/session-projection/README.md b/packages/session/session-projection/README.md
similarity index 100%
rename from packages/session-projection/session-projection/README.md
rename to packages/session/session-projection/README.md
diff --git a/packages/session-projection/session-projection/README.zh.md b/packages/session/session-projection/README.zh.md
similarity index 100%
rename from packages/session-projection/session-projection/README.zh.md
rename to packages/session/session-projection/README.zh.md
diff --git a/packages/session-projection/session-projection/package.json b/packages/session/session-projection/package.json
similarity index 100%
rename from packages/session-projection/session-projection/package.json
rename to packages/session/session-projection/package.json
diff --git a/packages/session-projection/session-projection/src/index.ts b/packages/session/session-projection/src/index.ts
similarity index 100%
rename from packages/session-projection/session-projection/src/index.ts
rename to packages/session/session-projection/src/index.ts
diff --git a/packages/session-projection/session-projection/src/invariant.ts b/packages/session/session-projection/src/invariant.ts
similarity index 100%
rename from packages/session-projection/session-projection/src/invariant.ts
rename to packages/session/session-projection/src/invariant.ts
diff --git a/packages/session-projection/session-projection/src/types.ts b/packages/session/session-projection/src/types.ts
similarity index 100%
rename from packages/session-projection/session-projection/src/types.ts
rename to packages/session/session-projection/src/types.ts
diff --git a/packages/session-projection/session-projection/tests/registry.spec.ts b/packages/session/session-projection/tests/registry.spec.ts
similarity index 100%
rename from packages/session-projection/session-projection/tests/registry.spec.ts
rename to packages/session/session-projection/tests/registry.spec.ts
diff --git a/packages/session-projection/session-projection/tsconfig.json b/packages/session/session-projection/tsconfig.json
similarity index 100%
rename from packages/session-projection/session-projection/tsconfig.json
rename to packages/session/session-projection/tsconfig.json
diff --git a/packages/telemetry/session-telemetry-otel/README.i18n.yaml b/packages/session/session-telemetry-otel/README.i18n.yaml
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/README.i18n.yaml
rename to packages/session/session-telemetry-otel/README.i18n.yaml
diff --git a/packages/telemetry/session-telemetry-otel/README.md b/packages/session/session-telemetry-otel/README.md
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/README.md
rename to packages/session/session-telemetry-otel/README.md
diff --git a/packages/telemetry/session-telemetry-otel/README.zh.md b/packages/session/session-telemetry-otel/README.zh.md
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/README.zh.md
rename to packages/session/session-telemetry-otel/README.zh.md
diff --git a/packages/telemetry/session-telemetry-otel/package.json b/packages/session/session-telemetry-otel/package.json
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/package.json
rename to packages/session/session-telemetry-otel/package.json
diff --git a/packages/telemetry/session-telemetry-otel/src/index.ts b/packages/session/session-telemetry-otel/src/index.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/src/index.ts
rename to packages/session/session-telemetry-otel/src/index.ts
diff --git a/packages/telemetry/session-telemetry-otel/src/invariant.ts b/packages/session/session-telemetry-otel/src/invariant.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/src/invariant.ts
rename to packages/session/session-telemetry-otel/src/invariant.ts
diff --git a/packages/telemetry/session-telemetry-otel/src/user-id.ts b/packages/session/session-telemetry-otel/src/user-id.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/src/user-id.ts
rename to packages/session/session-telemetry-otel/src/user-id.ts
diff --git a/packages/telemetry/session-telemetry-otel/tests/loader-composition.e2e.ts b/packages/session/session-telemetry-otel/tests/loader-composition.e2e.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/tests/loader-composition.e2e.ts
rename to packages/session/session-telemetry-otel/tests/loader-composition.e2e.ts
diff --git a/packages/telemetry/session-telemetry-otel/tests/otel.spec.ts b/packages/session/session-telemetry-otel/tests/otel.spec.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/tests/otel.spec.ts
rename to packages/session/session-telemetry-otel/tests/otel.spec.ts
diff --git a/packages/telemetry/session-telemetry-otel/tests/user-id.spec.ts b/packages/session/session-telemetry-otel/tests/user-id.spec.ts
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/tests/user-id.spec.ts
rename to packages/session/session-telemetry-otel/tests/user-id.spec.ts
diff --git a/packages/telemetry/session-telemetry-otel/tsconfig.json b/packages/session/session-telemetry-otel/tsconfig.json
similarity index 100%
rename from packages/telemetry/session-telemetry-otel/tsconfig.json
rename to packages/session/session-telemetry-otel/tsconfig.json
diff --git a/packages/telemetry/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml
similarity index 100%
rename from packages/telemetry/session-telemetry/README.i18n.yaml
rename to packages/session/session-telemetry/README.i18n.yaml
diff --git a/packages/telemetry/session-telemetry/README.md b/packages/session/session-telemetry/README.md
similarity index 100%
rename from packages/telemetry/session-telemetry/README.md
rename to packages/session/session-telemetry/README.md
diff --git a/packages/telemetry/session-telemetry/README.zh.md b/packages/session/session-telemetry/README.zh.md
similarity index 100%
rename from packages/telemetry/session-telemetry/README.zh.md
rename to packages/session/session-telemetry/README.zh.md
diff --git a/packages/telemetry/session-telemetry/package.json b/packages/session/session-telemetry/package.json
similarity index 100%
rename from packages/telemetry/session-telemetry/package.json
rename to packages/session/session-telemetry/package.json
diff --git a/packages/telemetry/session-telemetry/src/coordinator.ts b/packages/session/session-telemetry/src/coordinator.ts
similarity index 100%
rename from packages/telemetry/session-telemetry/src/coordinator.ts
rename to packages/session/session-telemetry/src/coordinator.ts
diff --git a/packages/telemetry/session-telemetry/src/index.ts b/packages/session/session-telemetry/src/index.ts
similarity index 100%
rename from packages/telemetry/session-telemetry/src/index.ts
rename to packages/session/session-telemetry/src/index.ts
diff --git a/packages/telemetry/session-telemetry/src/invariant.ts b/packages/session/session-telemetry/src/invariant.ts
similarity index 100%
rename from packages/telemetry/session-telemetry/src/invariant.ts
rename to packages/session/session-telemetry/src/invariant.ts
diff --git a/packages/telemetry/session-telemetry/tests/redact.spec.ts b/packages/session/session-telemetry/tests/redact.spec.ts
similarity index 100%
rename from packages/telemetry/session-telemetry/tests/redact.spec.ts
rename to packages/session/session-telemetry/tests/redact.spec.ts
diff --git a/packages/telemetry/session-telemetry/tests/telemetry.spec.ts b/packages/session/session-telemetry/tests/telemetry.spec.ts
similarity index 100%
rename from packages/telemetry/session-telemetry/tests/telemetry.spec.ts
rename to packages/session/session-telemetry/tests/telemetry.spec.ts
diff --git a/packages/telemetry/session-telemetry/tsconfig.json b/packages/session/session-telemetry/tsconfig.json
similarity index 100%
rename from packages/telemetry/session-telemetry/tsconfig.json
rename to packages/session/session-telemetry/tsconfig.json
diff --git a/packages/session-title/session-title-all-messages-llm/README.i18n.yaml b/packages/session/session-title-all-messages-llm/README.i18n.yaml
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/README.i18n.yaml
rename to packages/session/session-title-all-messages-llm/README.i18n.yaml
diff --git a/packages/session-title/session-title-all-messages-llm/README.md b/packages/session/session-title-all-messages-llm/README.md
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/README.md
rename to packages/session/session-title-all-messages-llm/README.md
diff --git a/packages/session-title/session-title-all-messages-llm/README.zh.md b/packages/session/session-title-all-messages-llm/README.zh.md
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/README.zh.md
rename to packages/session/session-title-all-messages-llm/README.zh.md
diff --git a/packages/session-title/session-title-all-messages-llm/package.json b/packages/session/session-title-all-messages-llm/package.json
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/package.json
rename to packages/session/session-title-all-messages-llm/package.json
diff --git a/packages/session-title/session-title-all-messages-llm/src/index.ts b/packages/session/session-title-all-messages-llm/src/index.ts
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/src/index.ts
rename to packages/session/session-title-all-messages-llm/src/index.ts
diff --git a/packages/session-title/session-title-all-messages-llm/src/invariant.ts b/packages/session/session-title-all-messages-llm/src/invariant.ts
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/src/invariant.ts
rename to packages/session/session-title-all-messages-llm/src/invariant.ts
diff --git a/packages/session-title/session-title-all-messages-llm/tests/provider.spec.ts b/packages/session/session-title-all-messages-llm/tests/provider.spec.ts
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/tests/provider.spec.ts
rename to packages/session/session-title-all-messages-llm/tests/provider.spec.ts
diff --git a/packages/session-title/session-title-all-messages-llm/tsconfig.json b/packages/session/session-title-all-messages-llm/tsconfig.json
similarity index 100%
rename from packages/session-title/session-title-all-messages-llm/tsconfig.json
rename to packages/session/session-title-all-messages-llm/tsconfig.json
diff --git a/packages/session-title/session-title-first-message-llm/README.i18n.yaml b/packages/session/session-title-first-message-llm/README.i18n.yaml
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/README.i18n.yaml
rename to packages/session/session-title-first-message-llm/README.i18n.yaml
diff --git a/packages/session-title/session-title-first-message-llm/README.md b/packages/session/session-title-first-message-llm/README.md
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/README.md
rename to packages/session/session-title-first-message-llm/README.md
diff --git a/packages/session-title/session-title-first-message-llm/README.zh.md b/packages/session/session-title-first-message-llm/README.zh.md
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/README.zh.md
rename to packages/session/session-title-first-message-llm/README.zh.md
diff --git a/packages/session-title/session-title-first-message-llm/package.json b/packages/session/session-title-first-message-llm/package.json
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/package.json
rename to packages/session/session-title-first-message-llm/package.json
diff --git a/packages/session-title/session-title-first-message-llm/src/index.ts b/packages/session/session-title-first-message-llm/src/index.ts
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/src/index.ts
rename to packages/session/session-title-first-message-llm/src/index.ts
diff --git a/packages/session-title/session-title-first-message-llm/src/invariant.ts b/packages/session/session-title-first-message-llm/src/invariant.ts
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/src/invariant.ts
rename to packages/session/session-title-first-message-llm/src/invariant.ts
diff --git a/packages/session-title/session-title-first-message-llm/tests/loader-composition.spec.ts b/packages/session/session-title-first-message-llm/tests/loader-composition.spec.ts
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/tests/loader-composition.spec.ts
rename to packages/session/session-title-first-message-llm/tests/loader-composition.spec.ts
diff --git a/packages/session-title/session-title-first-message-llm/tests/provider.e2e.ts b/packages/session/session-title-first-message-llm/tests/provider.e2e.ts
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/tests/provider.e2e.ts
rename to packages/session/session-title-first-message-llm/tests/provider.e2e.ts
diff --git a/packages/session-title/session-title-first-message-llm/tests/provider.spec.ts b/packages/session/session-title-first-message-llm/tests/provider.spec.ts
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/tests/provider.spec.ts
rename to packages/session/session-title-first-message-llm/tests/provider.spec.ts
diff --git a/packages/session-title/session-title-first-message-llm/tsconfig.json b/packages/session/session-title-first-message-llm/tsconfig.json
similarity index 100%
rename from packages/session-title/session-title-first-message-llm/tsconfig.json
rename to packages/session/session-title-first-message-llm/tsconfig.json
diff --git a/packages/session-title/session-title-llm/README.i18n.yaml b/packages/session/session-title-llm/README.i18n.yaml
similarity index 100%
rename from packages/session-title/session-title-llm/README.i18n.yaml
rename to packages/session/session-title-llm/README.i18n.yaml
diff --git a/packages/session-title/session-title-llm/README.md b/packages/session/session-title-llm/README.md
similarity index 100%
rename from packages/session-title/session-title-llm/README.md
rename to packages/session/session-title-llm/README.md
diff --git a/packages/session-title/session-title-llm/README.zh.md b/packages/session/session-title-llm/README.zh.md
similarity index 100%
rename from packages/session-title/session-title-llm/README.zh.md
rename to packages/session/session-title-llm/README.zh.md
diff --git a/packages/session-title/session-title-llm/package.json b/packages/session/session-title-llm/package.json
similarity index 100%
rename from packages/session-title/session-title-llm/package.json
rename to packages/session/session-title-llm/package.json
diff --git a/packages/session-title/session-title-llm/src/index.ts b/packages/session/session-title-llm/src/index.ts
similarity index 100%
rename from packages/session-title/session-title-llm/src/index.ts
rename to packages/session/session-title-llm/src/index.ts
diff --git a/packages/session-title/session-title-llm/src/invariant.ts b/packages/session/session-title-llm/src/invariant.ts
similarity index 100%
rename from packages/session-title/session-title-llm/src/invariant.ts
rename to packages/session/session-title-llm/src/invariant.ts
diff --git a/packages/session-title/session-title-llm/tests/llm.spec.ts b/packages/session/session-title-llm/tests/llm.spec.ts
similarity index 100%
rename from packages/session-title/session-title-llm/tests/llm.spec.ts
rename to packages/session/session-title-llm/tests/llm.spec.ts
diff --git a/packages/session-title/session-title-llm/tsconfig.json b/packages/session/session-title-llm/tsconfig.json
similarity index 100%
rename from packages/session-title/session-title-llm/tsconfig.json
rename to packages/session/session-title-llm/tsconfig.json
diff --git a/packages/session-title/session-title/README.i18n.yaml b/packages/session/session-title/README.i18n.yaml
similarity index 100%
rename from packages/session-title/session-title/README.i18n.yaml
rename to packages/session/session-title/README.i18n.yaml
diff --git a/packages/session-title/session-title/README.md b/packages/session/session-title/README.md
similarity index 100%
rename from packages/session-title/session-title/README.md
rename to packages/session/session-title/README.md
diff --git a/packages/session-title/session-title/README.zh.md b/packages/session/session-title/README.zh.md
similarity index 100%
rename from packages/session-title/session-title/README.zh.md
rename to packages/session/session-title/README.zh.md
diff --git a/packages/session-title/session-title/package.json b/packages/session/session-title/package.json
similarity index 100%
rename from packages/session-title/session-title/package.json
rename to packages/session/session-title/package.json
diff --git a/packages/session-title/session-title/src/client.ts b/packages/session/session-title/src/client.ts
similarity index 100%
rename from packages/session-title/session-title/src/client.ts
rename to packages/session/session-title/src/client.ts
diff --git a/packages/session-title/session-title/src/index.ts b/packages/session/session-title/src/index.ts
similarity index 100%
rename from packages/session-title/session-title/src/index.ts
rename to packages/session/session-title/src/index.ts
diff --git a/packages/session-title/session-title/src/invariant.ts b/packages/session/session-title/src/invariant.ts
similarity index 100%
rename from packages/session-title/session-title/src/invariant.ts
rename to packages/session/session-title/src/invariant.ts
diff --git a/packages/session-title/session-title/src/normalize.ts b/packages/session/session-title/src/normalize.ts
similarity index 100%
rename from packages/session-title/session-title/src/normalize.ts
rename to packages/session/session-title/src/normalize.ts
diff --git a/packages/session-title/session-title/src/types.ts b/packages/session/session-title/src/types.ts
similarity index 100%
rename from packages/session-title/session-title/src/types.ts
rename to packages/session/session-title/src/types.ts
diff --git a/packages/session-title/session-title/tests/invariant.spec.ts b/packages/session/session-title/tests/invariant.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/invariant.spec.ts
rename to packages/session/session-title/tests/invariant.spec.ts
diff --git a/packages/session-title/session-title/tests/persistence.spec.ts b/packages/session/session-title/tests/persistence.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/persistence.spec.ts
rename to packages/session/session-title/tests/persistence.spec.ts
diff --git a/packages/session-title/session-title/tests/projection.spec.ts b/packages/session/session-title/tests/projection.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/projection.spec.ts
rename to packages/session/session-title/tests/projection.spec.ts
diff --git a/packages/session-title/session-title/tests/provider.spec.ts b/packages/session/session-title/tests/provider.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/provider.spec.ts
rename to packages/session/session-title/tests/provider.spec.ts
diff --git a/packages/session-title/session-title/tests/rename.spec.ts b/packages/session/session-title/tests/rename.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/rename.spec.ts
rename to packages/session/session-title/tests/rename.spec.ts
diff --git a/packages/session-title/session-title/tests/service-contracts.spec.ts b/packages/session/session-title/tests/service-contracts.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/service-contracts.spec.ts
rename to packages/session/session-title/tests/service-contracts.spec.ts
diff --git a/packages/session-title/session-title/tests/session-title.spec.ts b/packages/session/session-title/tests/session-title.spec.ts
similarity index 100%
rename from packages/session-title/session-title/tests/session-title.spec.ts
rename to packages/session/session-title/tests/session-title.spec.ts
diff --git a/packages/session-title/session-title/tsconfig.json b/packages/session/session-title/tsconfig.json
similarity index 90%
rename from packages/session-title/session-title/tsconfig.json
rename to packages/session/session-title/tsconfig.json
index 80aef8bbfb..ca7c8e65dd 100644
--- a/packages/session-title/session-title/tsconfig.json
+++ b/packages/session/session-title/tsconfig.json
@@ -30,7 +30,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../session-projection"
     }
   ]
 }
diff --git a/packages/subagent/subagent/tsconfig.json b/packages/subagent/subagent/tsconfig.json
index de2fff3d84..ccfecc02e4 100644
--- a/packages/subagent/subagent/tsconfig.json
+++ b/packages/subagent/subagent/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../core/scope"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../session-projection/session-projection"
diff --git a/packages/telemetry/README.i18n.yaml b/packages/telemetry/README.i18n.yaml
deleted file mode 100644
index 6f60d47612..0000000000
--- a/packages/telemetry/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/telemetry/README.md
-README.md: d1910323176738d1ecab8fe8e6c07a2811f0f5cd
-README.zh.md: 229cd3acc5ce3dc49a9c862efa824f4ee6a1fa7b
diff --git a/packages/telemetry/README.md b/packages/telemetry/README.md
deleted file mode 100644
index d191032317..0000000000
--- a/packages/telemetry/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# telemetry/ — session telemetry capability family
-
-English | [中文](README.zh.md)
-
-This family projects session activity into outbound telemetry and delegates delivery to a configured reporting backend. The [telemetry decision](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md) records the reporting boundary; the [mode decision](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md) records immediate, feedback-gated, and disabled delivery.
-
-| Package | Role |
-|---|---|
-| [`session-telemetry/`](session-telemetry/README.md) | Defines capture, redaction, projection, and live or on-demand backend delivery. |
-| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | Delivers telemetry through OpenTelemetry logs in `FULL`, `FEEDBACK_ONLY`, or `DISABLED` mode. |
diff --git a/packages/telemetry/README.zh.md b/packages/telemetry/README.zh.md
deleted file mode 100644
index 229cd3acc5..0000000000
--- a/packages/telemetry/README.zh.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# telemetry/：会话遥测能力家族
-
-[English](README.md) | 中文
-
-本家族将会话活动投影为外发遥测，并将投递委派给配置的上报后端。[遥测决策](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)记录上报边界；[模式决策](../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)记录即时、反馈门控与禁用投递。
-
-| 包 | 职责 |
-|---|---|
-| [`session-telemetry/`](session-telemetry/README.md) | 定义捕获、脱敏、投影，以及实时或按需后端投递。 |
-| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | 通过 OpenTelemetry 日志以 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 模式投递遥测。 |
diff --git a/packages/todo/tool-todo/README.i18n.yaml b/packages/todo/tool-todo/README.i18n.yaml
index 20b8dffbbf..6aa521df26 100644
--- a/packages/todo/tool-todo/README.i18n.yaml
+++ b/packages/todo/tool-todo/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/todo/tool-todo/README.md
-README.md: 914e89a000e4bb87ebd7844f05db3809c6726528
-README.zh.md: c88dbf976fa5110028fcc964ab9aa8efcc3244d3
+README.md: 7c993ac6f7f0047d008a09e5ff52cb752f94763c
+README.zh.md: 9cea66147beddab7d62ed7344cbe866495e28022
diff --git a/packages/todo/tool-todo/README.md b/packages/todo/tool-todo/README.md
index 914e89a000..7c993ac6f7 100644
--- a/packages/todo/tool-todo/README.md
+++ b/packages/todo/tool-todo/README.md
@@ -30,7 +30,7 @@ The canonical result is `{ todos, counts: { pending, inProgress, completed } }`;
 
 ## Session projection
 
-When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)), this package registers the `todos` projection unit under an injected child: `init` = `null` (no write yet), `apply` = take the whole list from each `todo/write` and clear to `null` on each `turn/start` (standing plan; `turn/end` keeps the finished checklist; every other event returns the same state reference), `view` = identity, `stateVersion` = 2. The key merges into `SessionProjectionMap` here (via the interface package's `/types` outlet); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected. Lifetime rationale: [todo plan clears on next turn](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md).
+When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `todos` projection unit under an injected child: `init` = `null` (no write yet), `apply` = take the whole list from each `todo/write` and clear to `null` on each `turn/start` (standing plan; `turn/end` keeps the finished checklist; every other event returns the same state reference), `view` = identity, `stateVersion` = 2. The key merges into `SessionProjectionMap` here (via the interface package's `/types` outlet); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected. Lifetime rationale: [todo plan clears on next turn](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md).
 
 ## Export shape
 
diff --git a/packages/todo/tool-todo/README.zh.md b/packages/todo/tool-todo/README.zh.md
index c88dbf976f..9cea66147b 100644
--- a/packages/todo/tool-todo/README.zh.md
+++ b/packages/todo/tool-todo/README.zh.md
@@ -30,7 +30,7 @@
 
 ## 会话投影
 
-当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)）时，本包在一个注入的子插件中注册 `todos` 投影单元：`init` = `null`（尚无写入）、`apply` = 从每个 `todo/write` 取整表，并在每个 `turn/start` 清为 `null`（当前有效计划；`turn/end` 保留刚完成的清单；其余事件都返回同一个状态引用）、`view` = 恒等、`stateVersion` = 2。该键在本包中合并进 `SessionProjectionMap`（经接口包的 `/types` 出口）；框架驱动该单元，载体通过历史尾页与 `session/projection` 推送帧提供该值。未挂载注册表的组合不受影响。生命周期理由见 [在下一轮次清空 todo 计划](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)。
+当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)）时，本包在一个注入的子插件中注册 `todos` 投影单元：`init` = `null`（尚无写入）、`apply` = 从每个 `todo/write` 取整表，并在每个 `turn/start` 清为 `null`（当前有效计划；`turn/end` 保留刚完成的清单；其余事件都返回同一个状态引用）、`view` = 恒等、`stateVersion` = 2。该键在本包中合并进 `SessionProjectionMap`（经接口包的 `/types` 出口）；框架驱动该单元，载体通过历史尾页与 `session/projection` 推送帧提供该值。未挂载注册表的组合不受影响。生命周期理由见 [在下一轮次清空 todo 计划](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)。
 
 ## 导出形状
 
diff --git a/packages/todo/tool-todo/tsconfig.json b/packages/todo/tool-todo/tsconfig.json
index b35157e58d..6160fdbeb7 100644
--- a/packages/todo/tool-todo/tsconfig.json
+++ b/packages/todo/tool-todo/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts b/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts
index 051b0eef20..1de16660a8 100644
--- a/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts
+++ b/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts
@@ -35,7 +35,7 @@ const [
   load("vendor/cordis/lib/index.js"),
   load("packages/examples/agent-spine-demo/lib/index.js"),
   load("packages/subagent/subagent/lib/index.js"),
-  load("packages/session-persistence/session-persistence-jsonl/lib/index.js"),
+  load("packages/session/session-persistence-jsonl/lib/index.js"),
   load("packages/ui/jsonrpc/lib/index.js"),
   load("packages/core/session/lib/index.js"),
 ]);
diff --git a/packages/ui/permission/tsconfig.json b/packages/ui/permission/tsconfig.json
index 9dc4afcd9a..b951d622a8 100644
--- a/packages/ui/permission/tsconfig.json
+++ b/packages/ui/permission/tsconfig.json
@@ -36,7 +36,7 @@
       "path": "../../support/invariants"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
       "path": "../../settings/settings"
diff --git a/packages/workspace/workspace/tsconfig.json b/packages/workspace/workspace/tsconfig.json
index 0bddf4672c..bbdf80fae2 100644
--- a/packages/workspace/workspace/tsconfig.json
+++ b/packages/workspace/workspace/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../util/brand"
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index b17cc5b4f8..2c347613e8 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -270,11 +270,11 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   DomainSpec: 'domain declaration contract is owned by packages/storage/storage-domain/README.md',
   StorageBackend: 'backend contract is owned by packages/storage/storage/src/backend.ts',
   StorageForms: 'merge-extensible form map is owned by packages/storage/storage/src/index.ts',
-  ProjectionDefinition: 'projection unit contract is owned by packages/session-projection/session-projection/README.md',
-  SessionProjectionMap: 'merge-extensible projection key map is owned by packages/session-projection/session-projection/src/types.ts',
-  ProjectionChangeListener: 'change-feed listener contract is owned by packages/session-projection/session-projection/src/index.ts',
-  ProjectionSnapshot: 'watermark snapshot shape is owned by packages/session-projection/session-projection/src/index.ts',
-  ProjectionCheckpoint: 'persisted checkpoint row map is owned by packages/session-projection/session-projection/src/index.ts',
+  ProjectionDefinition: 'projection unit contract is owned by packages/session/session-projection/README.md',
+  SessionProjectionMap: 'merge-extensible projection key map is owned by packages/session/session-projection/src/types.ts',
+  ProjectionChangeListener: 'change-feed listener contract is owned by packages/session/session-projection/src/index.ts',
+  ProjectionSnapshot: 'watermark snapshot shape is owned by packages/session/session-projection/src/index.ts',
+  ProjectionCheckpoint: 'persisted checkpoint row map is owned by packages/session/session-projection/src/index.ts',
   CommandExecution: 'executor return contract is owned by packages/ui/commands/src/index.ts',
   TypertContribution: 'registry contribution contract is owned by packages/typert/registry/README.md',
   TypertFace: 'registry face identity is owned by packages/typert/registry/README.md',
@@ -305,7 +305,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
   SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
   SubagentRunInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
-  TelemetryRecord: 'seam-local record contract is owned by packages/telemetry/session-telemetry/src/index.ts',
+  TelemetryRecord: 'seam-local record contract is owned by packages/session/session-telemetry/src/index.ts',
   WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 74a09a874e..258b70f87d 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -312,7 +312,7 @@ function nodeCompatSmokeGates(options: { cliSmoke?: boolean } = {}): Gate[] {
     pnpmExec('jsonl-zstd-smoke', [
       'vitest',
       'run',
-      'packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts',
+      'packages/session/session-persistence-jsonl/tests/zstd.compat.spec.ts',
     ], { label: 'JSONL Zstandard smoke' }),
     pnpmExec('dsh-source-launch-smoke', [
       'vitest',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 9c99ed4632..e4eaf15398 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -448,7 +448,7 @@
     {
       "doc": "docs/core-data-structures/persistence.md",
       "symbol": "SessionLocation",
-      "source": "packages/session-persistence/session-persistence/src/index.ts"
+      "source": "packages/session/session-persistence/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-query.md",
@@ -528,57 +528,57 @@
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleProviderId",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleModelProvenance",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleSource",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleEventData",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleSnapshot",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleLlmRequestEventData",
-      "source": "packages/session-title/session-title-llm/src/index.ts"
+      "source": "packages/session/session-title-llm/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleUserMessage",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleAutomaticMode",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleProviderRequest",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleProviderResult",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleProvider",
-      "source": "packages/session-title/session-title/src/index.ts"
+      "source": "packages/session/session-title/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-reference.md",
@@ -1323,12 +1323,12 @@
     {
       "doc": "docs/core-data-structures/persistence.md",
       "symbol": "SessionPersistenceRevision",
-      "source": "packages/session-persistence/session-persistence/src/revision.ts"
+      "source": "packages/session/session-persistence/src/revision.ts"
     },
     {
       "doc": "docs/core-data-structures/persistence.md",
       "symbol": "SessionPersistenceSnapshot",
-      "source": "packages/session-persistence/session-persistence/src/index.ts"
+      "source": "packages/session/session-persistence/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/session-query.md",
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 6fda3901b6..5930d39e26 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -109,8 +109,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/sdk/sdk-client': { kind: 'none', reason: 'Client-process library; the model surface lives in the spawned runtime\'s composed plugins.' },
   'packages/sdk/sdk-protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model surface.' },
   'packages/sdk/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' },
-  'packages/session-projection/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers no model surface.' },
-  'packages/session-projection/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers no model surface.' },
+  'packages/session/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers no model surface.' },
+  'packages/session/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers no model surface.' },
   'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' },
   'packages/session-query/session-query-sqlite': { kind: 'none', reason: 'The search backend returns hits only to callers and registers no model surface.' },
   'packages/settings/settings': { kind: 'indirect', reason: 'The seam stores and resolves user settings; consumer plugins own any model surface a value feeds.' },
@@ -118,8 +118,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/credentials/credentials': { kind: 'indirect', reason: 'The seam resolves credential references; the consuming adapter owns every model surface a value authorizes.' },
   'packages/credentials/credentials-local': { kind: 'indirect', reason: 'The file/environment provider stores credential values; consumers of ctx.credentials own any model surface.' },
   'packages/util/atomic-write': { kind: 'none', reason: 'Pure filesystem write primitive; registers no model surface.' },
-  'packages/telemetry/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers no model surface.' },
-  'packages/telemetry/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers no model surface.' },
+  'packages/session/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers no model surface.' },
+  'packages/session/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers no model surface.' },
   'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-badge': { kind: 'indirect', reason: 'The bundled provider delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-skill.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 0673c35b90..e09ab93743 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -54,11 +54,11 @@
       "@deepseek-ai/dsh-typert-generator": ["./packages/typert/generator/src/index.ts"],
       "@deepseek-ai/dsh-session/types": ["./packages/core/session/src/types.ts"],
       "@deepseek-ai/dsh-session/surface": ["./packages/core/session/src/surface.ts"],
-      "@deepseek-ai/dsh-session-projection/types": ["./packages/session-projection/session-projection/src/types.ts"],
+      "@deepseek-ai/dsh-session-projection/types": ["./packages/session/session-projection/src/types.ts"],
       "@deepseek-ai/dsh-tool-todo/types": ["./packages/todo/tool-todo/src/types.ts"],
       "@deepseek-ai/dsh-tool-todo/client": ["./packages/todo/tool-todo/src/client.ts"],
-      "@deepseek-ai/dsh-session-title/types": ["./packages/session-title/session-title/src/types.ts"],
-      "@deepseek-ai/dsh-session-title/client": ["./packages/session-title/session-title/src/client.ts"],
+      "@deepseek-ai/dsh-session-title/types": ["./packages/session/session-title/src/types.ts"],
+      "@deepseek-ai/dsh-session-title/client": ["./packages/session/session-title/src/client.ts"],
       "@deepseek-ai/dsh-plan-mode/types": ["./packages/plan/plan-mode/src/types.ts"],
       "@deepseek-ai/dsh-plan-mode/client": ["./packages/plan/plan-mode/src/client.ts"],
       "@deepseek-ai/dsh-pwsh-local": ["./packages/bash/pwsh-local/src/index.ts"],
@@ -106,13 +106,10 @@
         "./packages/cordis/*/src/invariant.ts",
         "./packages/sandbox/*/src/invariant.ts",
         "./packages/hooks/*/src/invariant.ts",
-        "./packages/session-persistence/*/src/invariant.ts",
-        "./packages/session-projection/*/src/invariant.ts",
-        "./packages/session-title/*/src/invariant.ts",
+        "./packages/session/*/src/invariant.ts",
         "./packages/session-query/*/src/invariant.ts",
         "./packages/settings/*/src/invariant.ts",
         "./packages/credentials/*/src/invariant.ts",
-        "./packages/telemetry/*/src/invariant.ts",
         "./packages/acp/*/src/invariant.ts",
         "./packages/storage/*/src/invariant.ts",
         "./packages/workspace/*/src/invariant.ts",
@@ -211,13 +208,10 @@
         "./packages/cordis/*/src",
         "./packages/sandbox/*/src",
         "./packages/hooks/*/src",
-        "./packages/session-persistence/*/src",
-        "./packages/session-projection/*/src",
+        "./packages/session/*/src",
         "./packages/session-query/*/src",
-        "./packages/session-title/*/src",
         "./packages/settings/*/src",
         "./packages/credentials/*/src",
-        "./packages/telemetry/*/src",
         "./packages/acp/*/src",
         "./packages/storage/*/src",
         "./packages/workspace/*/src",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 101c810c91..0f44c4b7de 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -112,12 +112,12 @@
     { "path": "./packages/api/gateway" },
     { "path": "./packages/api/remotes/tsconfig.host.json" },
     { "path": "./packages/typert/loader" },
-    { "path": "./packages/session-persistence/session-persistence" },
-    { "path": "./packages/session-persistence/session-checkpoint-policy" },
-    { "path": "./packages/session-persistence/session-persistence-jsonl" },
-    { "path": "./packages/session-persistence/session-persistence-sqlite" },
-    { "path": "./packages/session-projection/session-projection" },
-    { "path": "./packages/session-projection/session-projection-cache" },
+    { "path": "./packages/session/session-persistence" },
+    { "path": "./packages/session/session-checkpoint-policy" },
+    { "path": "./packages/session/session-persistence-jsonl" },
+    { "path": "./packages/session/session-persistence-sqlite" },
+    { "path": "./packages/session/session-projection" },
+    { "path": "./packages/session/session-projection-cache" },
     { "path": "./packages/session-query/session-query" },
     { "path": "./packages/session-query/session-query-sqlite" },
     { "path": "./packages/settings/settings" },
@@ -130,12 +130,12 @@
     { "path": "./packages/storage/storage-sqlite" },
     { "path": "./packages/storage/storage-domain" },
     { "path": "./packages/workspace/workspace" },
-    { "path": "./packages/session-title/session-title" },
-    { "path": "./packages/session-title/session-title-llm" },
-    { "path": "./packages/session-title/session-title-first-message-llm" },
-    { "path": "./packages/session-title/session-title-all-messages-llm" },
-    { "path": "./packages/telemetry/session-telemetry" },
-    { "path": "./packages/telemetry/session-telemetry-otel" },
+    { "path": "./packages/session/session-title" },
+    { "path": "./packages/session/session-title-llm" },
+    { "path": "./packages/session/session-title-first-message-llm" },
+    { "path": "./packages/session/session-title-all-messages-llm" },
+    { "path": "./packages/session/session-telemetry" },
+    { "path": "./packages/session/session-telemetry-otel" },
     { "path": "./packages/core/system-prompt" },
     { "path": "./packages/core/agent" },
     { "path": "./packages/ui/commands" },
diff --git a/vitest.config.ts b/vitest.config.ts
index 6eb1bda354..29ad406e75 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -224,7 +224,7 @@ export default defineConfig({
         // cover and remove with the client test lane above.
         'packages/ui/commands/src/index.ts',
         'packages/ui/commands/src/invariant.ts',
-        'packages/session-projection/session-projection/src/index.ts',
+        'packages/session/session-projection/src/index.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
         ...windowsCoverageExclusions,
         ...pwshCoverageExclusions,

From 3fc35c91ff490e3ad1ad5fed34aa1e3ed7145eec Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 03:13:49 +0800
Subject: [PATCH 404/516] refactor(packages): dissolve ui/ and rename sdk/ to
 scaffold/

git mv per the regrouping RFC: the five human-collaboration seams and
tui join packages/interaction/, app-boot becomes packages/boot/, and
jsonrpc joins the renamed scaffold/ (formerly sdk/) as its server half
beside client/protocol/create-sdk/helper/scripts/telemetry, whose
folders drop the legacy sdk- prefix. Three new group README triplets
replace the ui/ and sdk/ ones; tsconfig references/paths/globs,
knip keys, vitest globs, gate scripts, catalogs, docs, and the
lockfile follow. Adds the four settled FIXME rename markers
(dsh-sdk-server, dsh-sdk-telemetry, dsh-sdk-helper, dsh-sdk-scripts).

The scaffold folders diverge from their npm names until those renames
land, so tsconfig.base.json maps the three affected names explicitly
beside the group wildcard. Also repairs two pre-existing stale-path
classes the strengthened sweep surfaced: docs/web-styling.md's retired
web-ui host package and type-model spec fixture-literal joins.

app-boot's three Loader-composition specs time out at the default 5s
under full-suite parallel load on this filesystem (pre-existing;
pass isolated with --testTimeout=30000); interaction/scaffold/boot
suites otherwise green (687 passed).
---
 ...026-07-27-tui-chat-channel-module-split.md |  2 +-
 ...-07-27-tui-chat-channel-module-split.zh.md |  2 +-
 ...-07-24-tui-turn-end-stop-reason-notices.md |  2 +-
 ...-24-tui-turn-end-stop-reason-notices.zh.md |  2 +-
 ...17-dedicated-full-screen-tui-front-door.md |  2 +-
 ...dedicated-full-screen-tui-front-door.zh.md |  2 +-
 .../feature/2026-07-20-windows-tui-support.md |  2 +-
 .../2026-07-20-windows-tui-support.zh.md      |  2 +-
 .../2026-07-21-tui-skill-slash-command.md     |  2 +-
 .../2026-07-21-tui-skill-slash-command.zh.md  |  2 +-
 ...-07-27-assistant-timing-header-trailing.md |  2 +-
 ...-27-assistant-timing-header-trailing.zh.md |  2 +-
 ...7-26-execa-for-test-subprocess-plumbing.md |  2 +-
 ...6-execa-for-test-subprocess-plumbing.zh.md |  2 +-
 ...cutable-sdk-runtime-distribution.i18n.yaml |  4 +--
 ...ile-executable-sdk-runtime-distribution.md |  4 +--
 ...-executable-sdk-runtime-distribution.zh.md |  4 +--
 ...-20-config-hot-reload-resilience.i18n.yaml |  4 +--
 ...2026-07-20-config-hot-reload-resilience.md |  2 +-
 ...6-07-20-config-hot-reload-resilience.zh.md |  2 +-
 .../2026-07-06-approval-seam.i18n.yaml        |  4 +--
 .../feature/2026-07-06-approval-seam.md       |  4 +--
 .../feature/2026-07-06-approval-seam.zh.md    |  4 +--
 ...nt-persona-tool-filter-and-depth.i18n.yaml |  4 +--
 ...-subagent-persona-tool-filter-and-depth.md |  2 +-
 ...bagent-persona-tool-filter-and-depth.zh.md |  2 +-
 .../2026-07-16-harness-level-loop.i18n.yaml   |  4 +--
 .../feature/2026-07-16-harness-level-loop.md  |  2 +-
 .../2026-07-16-harness-level-loop.zh.md       |  2 +-
 ...7-19-plugin-command-registration.i18n.yaml |  4 +--
 .../2026-07-19-plugin-command-registration.md |  2 +-
 ...26-07-19-plugin-command-registration.zh.md |  2 +-
 ...26-07-20-dsh-cli-personal-config.i18n.yaml |  4 +--
 .../2026-07-20-dsh-cli-personal-config.md     |  2 +-
 .../2026-07-20-dsh-cli-personal-config.zh.md  |  2 +-
 ...continuable-background-subagents.i18n.yaml |  4 +--
 ...-07-21-continuable-background-subagents.md |  2 +-
 ...-21-continuable-background-subagents.zh.md |  2 +-
 ...ipt-sdk-and-sdk-subagent-backend.i18n.yaml |  4 +--
 ...typescript-sdk-and-sdk-subagent-backend.md |  4 +--
 ...escript-sdk-and-sdk-subagent-backend.zh.md |  4 +--
 ...ssion-projection-and-command-log.i18n.yaml |  4 +--
 ...7-27-session-projection-and-command-log.md |  2 +-
 ...7-session-projection-and-command-log.zh.md |  2 +-
 ...6-07-19-make-jsonrpc-directional.i18n.yaml |  4 +--
 .../2026-07-19-make-jsonrpc-directional.md    |  6 ++--
 .../2026-07-19-make-jsonrpc-directional.zh.md |  6 ++--
 AGENTS.md                                     |  4 ++-
 apps/cli/tsconfig.json                        |  2 +-
 docs/architecture.i18n.yaml                   |  4 +--
 docs/architecture.md                          |  2 +-
 docs/architecture.zh.md                       |  2 +-
 docs/capability-seams.md                      |  8 ++---
 docs/core-data-structures/approval.i18n.yaml  |  4 +--
 docs/core-data-structures/approval.md         |  4 +--
 docs/core-data-structures/approval.zh.md      |  4 +--
 docs/core-data-structures/commands.i18n.yaml  |  4 +--
 docs/core-data-structures/commands.md         |  4 +--
 docs/core-data-structures/commands.zh.md      |  4 +--
 .../user-interaction.i18n.yaml                |  4 +--
 docs/core-data-structures/user-interaction.md |  4 +--
 .../user-interaction.zh.md                    |  4 +--
 docs/testing.i18n.yaml                        |  4 +--
 docs/testing.md                               |  2 +-
 docs/testing.zh.md                            |  2 +-
 docs/tool-catalog.md                          |  2 +-
 knip.json                                     |  8 ++---
 packages/README.i18n.yaml                     |  4 +--
 packages/README.md                            |  5 +--
 packages/README.zh.md                         |  5 +--
 packages/acp/acp/tsconfig.json                |  2 +-
 packages/bash/tool-bash/tsconfig.json         |  2 +-
 packages/{sdk => boot}/README.i18n.yaml       |  6 ++--
 packages/boot/README.md                       |  9 +++++
 packages/boot/README.zh.md                    |  9 +++++
 .../{ui => boot}/app-boot/README.i18n.yaml    |  2 +-
 packages/{ui => boot}/app-boot/README.md      |  0
 packages/{ui => boot}/app-boot/README.zh.md   |  0
 packages/{ui => boot}/app-boot/package.json   |  0
 packages/{ui => boot}/app-boot/src/index.ts   |  0
 .../{ui => boot}/app-boot/src/invariant.ts    |  0
 packages/{ui => boot}/app-boot/src/profile.ts |  0
 .../app-boot/tests/app-boot.spec.ts           |  0
 .../app-boot/tests/config-dump.spec.ts        |  0
 .../app-boot/tests/config-reload.spec.ts      |  0
 .../app-boot/tests/hmr-config.spec.ts         |  0
 .../app-boot/tests/profile.spec.ts            |  0
 .../app-boot/tests/repository-cache.spec.ts   |  0
 .../app-boot/tests/user-patches.spec.ts       |  0
 packages/{ui => boot}/app-boot/tsconfig.json  |  0
 .../{ui => boot}/app-boot/tsdown.config.ts    |  0
 packages/bundle/README.i18n.yaml              |  6 ++++
 packages/client/connection/tsconfig.json      |  6 ++--
 packages/client/runtime/tsconfig.json         |  2 +-
 packages/client/ui-conversation/tsconfig.json |  2 +-
 packages/client/ui-permission/tsconfig.json   |  2 +-
 packages/client/ui-question/tsconfig.json     |  2 +-
 .../compact/command-compact/tsconfig.json     |  2 +-
 packages/compact/compact/README.i18n.yaml     |  4 +--
 packages/compact/compact/README.md            |  2 +-
 packages/compact/compact/README.zh.md         |  2 +-
 packages/core/tools/README.i18n.yaml          |  4 +--
 packages/core/tools/README.md                 |  2 +-
 packages/core/tools/README.zh.md              |  2 +-
 packages/core/tools/tsconfig.json             |  2 +-
 .../examples/acp-demo/tests/built-bin.e2e.ts  |  2 +-
 packages/examples/acp-demo/tsconfig.json      |  2 +-
 packages/examples/jsonrpc-demo/tsconfig.json  |  2 +-
 packages/fs/tool-fs/tsconfig.json             |  2 +-
 packages/goal/command-goal/tsconfig.json      |  2 +-
 packages/host/apiproxy/tsconfig.json          |  6 ++--
 packages/interaction/README.i18n.yaml         |  6 ++++
 packages/{ui => interaction}/README.md        |  6 ++--
 packages/{ui => interaction}/README.zh.md     |  6 ++--
 .../commands/README.i18n.yaml                 |  2 +-
 .../{ui => interaction}/commands/README.md    |  0
 .../{ui => interaction}/commands/README.zh.md |  0
 .../{ui => interaction}/commands/package.json |  0
 .../{ui => interaction}/commands/src/brand.ts |  0
 .../{ui => interaction}/commands/src/index.ts |  0
 .../commands/src/invariant.ts                 |  0
 .../commands/tests/commands.spec.ts           |  0
 .../commands/tests/invariant.spec.ts          |  0
 .../commands/tsconfig.json                    |  0
 .../interaction/permission/README.i18n.yaml   |  6 ++++
 .../{ui => interaction}/permission/README.md  |  0
 .../permission/README.zh.md                   |  0
 .../permission/package.json                   |  0
 .../permission/src/client.ts                  |  0
 .../permission/src/index.ts                   |  0
 .../permission/src/invariant.ts               |  0
 .../permission/src/types.ts                   |  0
 .../permission/tests/invariant.spec.ts        |  0
 .../permission/tests/permission.spec.ts       |  0
 .../permission/tests/projection.spec.ts       |  0
 .../permission/tsconfig.json                  |  0
 .../tool-ask-user/README.i18n.yaml            |  2 +-
 .../tool-ask-user/README.md                   |  0
 .../tool-ask-user/README.zh.md                |  0
 .../tool-ask-user/package.json                |  0
 .../tool-ask-user/src/index.ts                |  0
 .../tool-ask-user/src/invariant.ts            |  0
 .../tool-ask-user/tests/tool-ask-user.spec.ts |  0
 .../tool-ask-user/tsconfig.json               |  0
 .../user-approval/README.i18n.yaml            |  2 +-
 .../user-approval/README.md                   |  0
 .../user-approval/README.zh.md                |  0
 .../user-approval/package.json                |  0
 .../user-approval/src/index.ts                |  0
 .../user-approval/src/invariant.ts            |  0
 .../user-approval/src/types.ts                |  0
 .../user-approval/tests/approval.spec.ts      |  0
 .../user-approval/tests/invariant.spec.ts     |  0
 .../user-approval/tsconfig.json               |  0
 .../user-approval/tsdown.config.ts            |  0
 .../user-interaction/README.i18n.yaml         |  6 ++++
 .../user-interaction/README.md                |  0
 .../user-interaction/README.zh.md             |  0
 .../user-interaction/package.json             |  0
 .../user-interaction/src/index.ts             |  0
 .../user-interaction/src/invariant.ts         |  0
 .../user-interaction/src/types.ts             |  0
 .../tests/user-interaction.spec.ts            |  0
 .../user-interaction/tsconfig.json            |  0
 packages/plan/plan-mode/tsconfig.json         |  4 +--
 packages/{ui => scaffold}/README.i18n.yaml    |  6 ++--
 packages/{sdk => scaffold}/README.md          |  9 ++---
 packages/scaffold/README.zh.md                | 17 +++++++++
 .../client}/README.i18n.yaml                  |  2 +-
 .../sdk-client => scaffold/client}/README.md  |  0
 .../client}/README.zh.md                      |  0
 .../client}/package.json                      |  0
 .../sdk-client => scaffold/client}/src/api.ts |  0
 .../client}/src/client.ts                     |  0
 .../client}/src/dispose.ts                    |  0
 .../client}/src/index.ts                      |  0
 .../client}/src/invariant.ts                  |  0
 .../client}/src/types.ts                      |  0
 .../client}/tests/dispose.spec.ts             |  0
 .../client}/tests/fake-runtime.ts             |  0
 .../client}/tests/sdk-client.spec.ts          |  0
 .../client}/tsconfig.json                     |  2 +-
 .../create-sdk/README.i18n.yaml               |  2 +-
 .../{sdk => scaffold}/create-sdk/README.md    |  0
 .../{sdk => scaffold}/create-sdk/README.zh.md |  0
 .../{sdk => scaffold}/create-sdk/package.json |  0
 .../{sdk => scaffold}/create-sdk/src/args.ts  |  0
 .../{sdk => scaffold}/create-sdk/src/bin.ts   |  0
 .../create-sdk/src/command.ts                 |  0
 .../create-sdk/src/create-questions.ts        |  0
 .../create-sdk/src/create-wizard.ts           |  0
 .../create-sdk/src/headless.ts                |  0
 .../{sdk => scaffold}/create-sdk/src/index.ts |  0
 .../create-sdk/src/invariant.ts               |  0
 .../create-sdk/src/project-scaffolder.ts      |  0
 .../src/templates/assets/created.txt.tpl      |  0
 .../templates/assets/install-question.txt.tpl |  0
 .../src/templates/assets/next-steps.txt.tpl   |  0
 .../templates/assets/setup-failure.txt.tpl    |  0
 .../src/templates/assets/usage.txt.tpl        |  0
 .../src/templates/create-templates.ts         |  0
 .../create-sdk/tests/built-artifacts.e2e.ts   |  4 +--
 .../create-sdk/tests/create.snapshot.ts       |  0
 .../create-sdk/tests/create.spec.ts           |  0
 .../create-sdk/tests/link-workspace.e2e.ts    |  2 +-
 .../create-sdk/tsconfig.json                  |  0
 .../create-sdk/tsdown.config.ts               |  0
 .../{sdk => scaffold}/helper/README.i18n.yaml |  2 +-
 packages/{sdk => scaffold}/helper/README.md   |  0
 .../{sdk => scaffold}/helper/README.zh.md     |  0
 .../{sdk => scaffold}/helper/package.json     |  0
 .../helper/src/documents/cordis-yaml-file.ts  |  0
 .../helper/src/documents/env-file.ts          |  0
 .../helper/src/documents/package-json-file.ts |  0
 .../src/documents/pnpm-workspace-file.ts      |  0
 .../helper/src/documents/project-file.ts      |  0
 .../helper/src/documents/tsconfig-file.ts     |  0
 .../helper/src/features/builtin/app.ts        |  0
 .../helper/src/features/builtin/helpers.ts    |  0
 .../helper/src/features/builtin/index.ts      |  0
 .../helper/src/features/builtin/provider.ts   |  0
 .../helper/src/features/builtin/spine.ts      |  0
 .../helper/src/features/define-feature.ts     |  0
 .../src/features/feature-configurator.ts      |  0
 .../helper/src/features/feature.ts            |  0
 .../helper/src/features/registry.ts           |  0
 .../helper/src/features/resources.ts          |  0
 packages/{sdk => scaffold}/helper/src/ids.ts  |  0
 .../{sdk => scaffold}/helper/src/index.ts     |  4 +++
 .../{sdk => scaffold}/helper/src/invariant.ts |  0
 .../src/package-managers/link-workspace.ts    |  0
 .../src/package-managers/package-manager.ts   |  0
 .../src/plugins/local-plugin-blueprint.ts     |  0
 .../helper/src/project/change-set.ts          |  0
 .../src/project/npm-dependency-policy.ts      |  0
 .../src/project/project-edit-session.ts       |  0
 .../helper/src/project/sdk-project.ts         |  2 +-
 .../helper/src/project/types.ts               |  0
 .../src/questions/clack-nested-multiselect.ts |  0
 .../helper/src/questions/clack-prompt-port.ts |  0
 .../src/questions/headless-prompt-port.ts     |  0
 .../helper/src/questions/prompt-port.ts       |  0
 .../helper/src/questions/question.ts          |  0
 .../helper/src/templates/assets/README.md.tpl |  0
 .../helper/src/templates/assets/gitignore.tpl |  0
 .../helper/src/templates/assets/index.ts.tpl  |  0
 .../assets/local-plugin-tsdown.config.ts.tpl  |  0
 .../src/templates/assets/local-plugin.ts.tpl  |  0
 .../src/templates/assets/local-tool.ts.tpl    |  0
 .../src/templates/assets/package.json.tpl     |  0
 .../src/templates/assets/persona.txt.tpl      |  0
 .../templates/assets/tsconfig.base.json.tpl   |  0
 .../src/templates/assets/tsdown.config.ts.tpl |  0
 .../src/templates/assets/yarnrc.yml.tpl       |  0
 .../helper/src/templates/project-template.ts  |  0
 .../helper/src/templates/template-assets.ts   |  0
 .../helper/src/templates/text-template.ts     |  0
 .../helper/tests/documents.spec.ts            |  0
 .../helper/tests/headless-prompt-port.spec.ts |  0
 .../helper/tests/project.spec.ts              |  0
 .../helper/tests/questions.spec.ts            |  0
 .../{sdk => scaffold}/helper/tsconfig.json    |  0
 .../{sdk => scaffold}/helper/tsdown.config.ts |  0
 packages/scaffold/protocol/README.i18n.yaml   |  6 ++++
 .../protocol}/README.md                       |  6 ++--
 .../protocol}/README.zh.md                    |  0
 .../protocol}/package.json                    |  0
 .../protocol}/src/index.ts                    |  0
 .../protocol}/src/invariant.ts                |  0
 .../protocol}/src/transport.ts                |  0
 .../protocol}/src/types.ts                    |  0
 .../protocol}/tests/transport.spec.ts         |  0
 .../protocol}/tsconfig.json                   |  0
 .../scripts/README.i18n.yaml                  |  2 +-
 packages/{sdk => scaffold}/scripts/README.md  |  0
 .../{sdk => scaffold}/scripts/README.zh.md    |  0
 .../{sdk => scaffold}/scripts/package.json    |  0
 .../{sdk => scaffold}/scripts/src/args.ts     |  0
 packages/{sdk => scaffold}/scripts/src/bin.ts |  0
 .../{sdk => scaffold}/scripts/src/build.ts    |  0
 .../{sdk => scaffold}/scripts/src/command.ts  |  0
 .../{sdk => scaffold}/scripts/src/config.ts   |  0
 .../scripts/src/config/config-workflow.ts     |  0
 .../scripts/src/create-plugin.ts              |  0
 .../scripts/src/dev/tsdown-config.ts          |  0
 packages/scaffold/scripts/src/index.ts        | 11 ++++++
 .../scripts/src/invariant.ts                  |  0
 .../scripts/src/local-plugin-loader-hooks.ts  |  0
 .../{sdk => scaffold}/scripts/src/runtime.ts  |  0
 .../scripts/src/telemetry.ts                  |  0
 .../assets/config-install-failure.txt.tpl     |  0
 .../src/templates/assets/usage.txt.tpl        |  0
 .../src/templates/dsh-sdk-templates.ts        |  0
 .../__snapshots__/config.snapshot.ts.snap     |  0
 .../scripts/tests/config.snapshot.ts          |  0
 .../scripts/tests/scripts.spec.ts             |  0
 .../{sdk => scaffold}/scripts/tsconfig.json   |  2 +-
 .../scripts/tsdown.config.ts                  |  0
 packages/scaffold/server/README.i18n.yaml     |  6 ++++
 .../{ui/jsonrpc => scaffold/server}/README.md |  2 +-
 .../jsonrpc => scaffold/server}/README.zh.md  |  2 +-
 .../jsonrpc => scaffold/server}/package.json  |  0
 .../jsonrpc => scaffold/server}/src/index.ts  |  4 +++
 .../server}/src/invariant.ts                  |  0
 .../jsonrpc => scaffold/server}/src/server.ts |  0
 .../server}/tests/built-scope-carrier.e2e.ts  |  2 +-
 .../server}/tests/plugin-apply.spec.ts        |  0
 .../server}/tests/plugin-shape.spec.ts        |  0
 .../server}/tests/server.spec.ts              |  0
 .../jsonrpc => scaffold/server}/tsconfig.json |  2 +-
 .../telemetry/README.i18n.yaml                |  2 +-
 .../{sdk => scaffold}/telemetry/README.md     |  0
 .../{sdk => scaffold}/telemetry/README.zh.md  |  0
 .../{sdk => scaffold}/telemetry/package.json  |  0
 .../telemetry/src/anonymous-id.ts             |  0
 .../telemetry/src/consent-resolver.ts         |  0
 .../{sdk => scaffold}/telemetry/src/index.ts  |  4 +++
 .../telemetry/src/invariant.ts                |  0
 .../telemetry/src/payload.ts                  |  0
 .../telemetry/src/reporter.ts                 |  0
 .../telemetry/src/secret-redactor.ts          |  0
 .../telemetry/tests/anonymous-id.spec.ts      |  0
 .../telemetry/tests/consent-resolver.spec.ts  |  0
 .../telemetry/tests/payload.spec.ts           |  0
 .../telemetry/tests/reporter.spec.ts          |  0
 .../telemetry/tests/secret-redactor.spec.ts   |  0
 .../{sdk => scaffold}/telemetry/tsconfig.json |  0
 packages/sdk/README.zh.md                     | 16 ---------
 packages/sdk/scripts/src/index.ts             |  7 ----
 packages/sdk/sdk-protocol/README.i18n.yaml    |  6 ----
 .../subagent-dsh-sdk/README.i18n.yaml         |  4 +--
 packages/subagent/subagent-dsh-sdk/README.md  |  2 +-
 .../subagent/subagent-dsh-sdk/README.zh.md    |  2 +-
 .../tests/subagent-dsh-sdk.spec.ts            |  2 +-
 .../subagent/subagent-dsh-sdk/tsconfig.json   |  4 +--
 .../subagent/subagent-inprocess/tsconfig.json |  2 +-
 .../typert/generator/tests/type-model.spec.ts | 22 ++++++------
 packages/ui/jsonrpc/README.i18n.yaml          |  6 ----
 packages/ui/permission/README.i18n.yaml       |  6 ----
 packages/ui/user-interaction/README.i18n.yaml |  6 ----
 scripts/gen-cordis-catalog.ts                 | 10 +++---
 scripts/gen-third-party-notices.spec.ts       |  2 +-
 scripts/gen-tool-catalog.ts                   |  2 +-
 scripts/run-gates.ts                          |  2 +-
 scripts/type-equiv.manifest.json              | 36 +++++++++----------
 .../verify-package-readme-model-experience.ts | 18 +++++-----
 tsconfig.base.json                            | 23 ++++++++----
 tsconfig.host.json                            | 26 +++++++-------
 vendor/README.md                              |  8 ++---
 vitest.config.ts                              | 10 +++---
 vitest.snapshot.config.ts                     |  2 +-
 351 files changed, 368 insertions(+), 311 deletions(-)
 rename packages/{sdk => boot}/README.i18n.yaml (57%)
 create mode 100644 packages/boot/README.md
 create mode 100644 packages/boot/README.zh.md
 rename packages/{ui => boot}/app-boot/README.i18n.yaml (81%)
 rename packages/{ui => boot}/app-boot/README.md (100%)
 rename packages/{ui => boot}/app-boot/README.zh.md (100%)
 rename packages/{ui => boot}/app-boot/package.json (100%)
 rename packages/{ui => boot}/app-boot/src/index.ts (100%)
 rename packages/{ui => boot}/app-boot/src/invariant.ts (100%)
 rename packages/{ui => boot}/app-boot/src/profile.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/app-boot.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/config-dump.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/config-reload.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/hmr-config.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/profile.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/repository-cache.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tests/user-patches.spec.ts (100%)
 rename packages/{ui => boot}/app-boot/tsconfig.json (100%)
 rename packages/{ui => boot}/app-boot/tsdown.config.ts (100%)
 create mode 100644 packages/interaction/README.i18n.yaml
 rename packages/{ui => interaction}/README.md (71%)
 rename packages/{ui => interaction}/README.zh.md (69%)
 rename packages/{ui => interaction}/commands/README.i18n.yaml (79%)
 rename packages/{ui => interaction}/commands/README.md (100%)
 rename packages/{ui => interaction}/commands/README.zh.md (100%)
 rename packages/{ui => interaction}/commands/package.json (100%)
 rename packages/{ui => interaction}/commands/src/brand.ts (100%)
 rename packages/{ui => interaction}/commands/src/index.ts (100%)
 rename packages/{ui => interaction}/commands/src/invariant.ts (100%)
 rename packages/{ui => interaction}/commands/tests/commands.spec.ts (100%)
 rename packages/{ui => interaction}/commands/tests/invariant.spec.ts (100%)
 rename packages/{ui => interaction}/commands/tsconfig.json (100%)
 create mode 100644 packages/interaction/permission/README.i18n.yaml
 rename packages/{ui => interaction}/permission/README.md (100%)
 rename packages/{ui => interaction}/permission/README.zh.md (100%)
 rename packages/{ui => interaction}/permission/package.json (100%)
 rename packages/{ui => interaction}/permission/src/client.ts (100%)
 rename packages/{ui => interaction}/permission/src/index.ts (100%)
 rename packages/{ui => interaction}/permission/src/invariant.ts (100%)
 rename packages/{ui => interaction}/permission/src/types.ts (100%)
 rename packages/{ui => interaction}/permission/tests/invariant.spec.ts (100%)
 rename packages/{ui => interaction}/permission/tests/permission.spec.ts (100%)
 rename packages/{ui => interaction}/permission/tests/projection.spec.ts (100%)
 rename packages/{ui => interaction}/permission/tsconfig.json (100%)
 rename packages/{ui => interaction}/tool-ask-user/README.i18n.yaml (79%)
 rename packages/{ui => interaction}/tool-ask-user/README.md (100%)
 rename packages/{ui => interaction}/tool-ask-user/README.zh.md (100%)
 rename packages/{ui => interaction}/tool-ask-user/package.json (100%)
 rename packages/{ui => interaction}/tool-ask-user/src/index.ts (100%)
 rename packages/{ui => interaction}/tool-ask-user/src/invariant.ts (100%)
 rename packages/{ui => interaction}/tool-ask-user/tests/tool-ask-user.spec.ts (100%)
 rename packages/{ui => interaction}/tool-ask-user/tsconfig.json (100%)
 rename packages/{ui => interaction}/user-approval/README.i18n.yaml (79%)
 rename packages/{ui => interaction}/user-approval/README.md (100%)
 rename packages/{ui => interaction}/user-approval/README.zh.md (100%)
 rename packages/{ui => interaction}/user-approval/package.json (100%)
 rename packages/{ui => interaction}/user-approval/src/index.ts (100%)
 rename packages/{ui => interaction}/user-approval/src/invariant.ts (100%)
 rename packages/{ui => interaction}/user-approval/src/types.ts (100%)
 rename packages/{ui => interaction}/user-approval/tests/approval.spec.ts (100%)
 rename packages/{ui => interaction}/user-approval/tests/invariant.spec.ts (100%)
 rename packages/{ui => interaction}/user-approval/tsconfig.json (100%)
 rename packages/{ui => interaction}/user-approval/tsdown.config.ts (100%)
 create mode 100644 packages/interaction/user-interaction/README.i18n.yaml
 rename packages/{ui => interaction}/user-interaction/README.md (100%)
 rename packages/{ui => interaction}/user-interaction/README.zh.md (100%)
 rename packages/{ui => interaction}/user-interaction/package.json (100%)
 rename packages/{ui => interaction}/user-interaction/src/index.ts (100%)
 rename packages/{ui => interaction}/user-interaction/src/invariant.ts (100%)
 rename packages/{ui => interaction}/user-interaction/src/types.ts (100%)
 rename packages/{ui => interaction}/user-interaction/tests/user-interaction.spec.ts (100%)
 rename packages/{ui => interaction}/user-interaction/tsconfig.json (100%)
 rename packages/{ui => scaffold}/README.i18n.yaml (57%)
 rename packages/{sdk => scaffold}/README.md (64%)
 create mode 100644 packages/scaffold/README.zh.md
 rename packages/{sdk/sdk-client => scaffold/client}/README.i18n.yaml (80%)
 rename packages/{sdk/sdk-client => scaffold/client}/README.md (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/README.zh.md (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/package.json (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/api.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/client.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/dispose.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/index.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/invariant.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/src/types.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/tests/dispose.spec.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/tests/fake-runtime.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/tests/sdk-client.spec.ts (100%)
 rename packages/{sdk/sdk-client => scaffold/client}/tsconfig.json (93%)
 rename packages/{sdk => scaffold}/create-sdk/README.i18n.yaml (80%)
 rename packages/{sdk => scaffold}/create-sdk/README.md (100%)
 rename packages/{sdk => scaffold}/create-sdk/README.zh.md (100%)
 rename packages/{sdk => scaffold}/create-sdk/package.json (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/args.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/bin.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/command.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/create-questions.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/create-wizard.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/headless.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/index.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/invariant.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/project-scaffolder.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/assets/created.txt.tpl (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/assets/install-question.txt.tpl (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/assets/next-steps.txt.tpl (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/assets/setup-failure.txt.tpl (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/assets/usage.txt.tpl (100%)
 rename packages/{sdk => scaffold}/create-sdk/src/templates/create-templates.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/tests/built-artifacts.e2e.ts (87%)
 rename packages/{sdk => scaffold}/create-sdk/tests/create.snapshot.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/tests/create.spec.ts (100%)
 rename packages/{sdk => scaffold}/create-sdk/tests/link-workspace.e2e.ts (98%)
 rename packages/{sdk => scaffold}/create-sdk/tsconfig.json (100%)
 rename packages/{sdk => scaffold}/create-sdk/tsdown.config.ts (100%)
 rename packages/{sdk => scaffold}/helper/README.i18n.yaml (80%)
 rename packages/{sdk => scaffold}/helper/README.md (100%)
 rename packages/{sdk => scaffold}/helper/README.zh.md (100%)
 rename packages/{sdk => scaffold}/helper/package.json (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/cordis-yaml-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/env-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/package-json-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/pnpm-workspace-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/project-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/documents/tsconfig-file.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/builtin/app.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/builtin/helpers.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/builtin/index.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/builtin/provider.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/builtin/spine.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/define-feature.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/feature-configurator.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/feature.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/registry.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/features/resources.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/ids.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/index.ts (86%)
 rename packages/{sdk => scaffold}/helper/src/invariant.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/package-managers/link-workspace.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/package-managers/package-manager.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/plugins/local-plugin-blueprint.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/project/change-set.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/project/npm-dependency-policy.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/project/project-edit-session.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/project/sdk-project.ts (99%)
 rename packages/{sdk => scaffold}/helper/src/project/types.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/questions/clack-nested-multiselect.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/questions/clack-prompt-port.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/questions/headless-prompt-port.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/questions/prompt-port.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/questions/question.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/README.md.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/gitignore.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/index.ts.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/local-plugin.ts.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/local-tool.ts.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/package.json.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/persona.txt.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/tsconfig.base.json.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/tsdown.config.ts.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/assets/yarnrc.yml.tpl (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/project-template.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/template-assets.ts (100%)
 rename packages/{sdk => scaffold}/helper/src/templates/text-template.ts (100%)
 rename packages/{sdk => scaffold}/helper/tests/documents.spec.ts (100%)
 rename packages/{sdk => scaffold}/helper/tests/headless-prompt-port.spec.ts (100%)
 rename packages/{sdk => scaffold}/helper/tests/project.spec.ts (100%)
 rename packages/{sdk => scaffold}/helper/tests/questions.spec.ts (100%)
 rename packages/{sdk => scaffold}/helper/tsconfig.json (100%)
 rename packages/{sdk => scaffold}/helper/tsdown.config.ts (100%)
 create mode 100644 packages/scaffold/protocol/README.i18n.yaml
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/README.md (90%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/README.zh.md (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/package.json (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/src/index.ts (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/src/invariant.ts (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/src/transport.ts (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/src/types.ts (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/tests/transport.spec.ts (100%)
 rename packages/{sdk/sdk-protocol => scaffold/protocol}/tsconfig.json (100%)
 rename packages/{sdk => scaffold}/scripts/README.i18n.yaml (80%)
 rename packages/{sdk => scaffold}/scripts/README.md (100%)
 rename packages/{sdk => scaffold}/scripts/README.zh.md (100%)
 rename packages/{sdk => scaffold}/scripts/package.json (100%)
 rename packages/{sdk => scaffold}/scripts/src/args.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/bin.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/build.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/command.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/config.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/config/config-workflow.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/create-plugin.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/dev/tsdown-config.ts (100%)
 create mode 100644 packages/scaffold/scripts/src/index.ts
 rename packages/{sdk => scaffold}/scripts/src/invariant.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/local-plugin-loader-hooks.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/runtime.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/telemetry.ts (100%)
 rename packages/{sdk => scaffold}/scripts/src/templates/assets/config-install-failure.txt.tpl (100%)
 rename packages/{sdk => scaffold}/scripts/src/templates/assets/usage.txt.tpl (100%)
 rename packages/{sdk => scaffold}/scripts/src/templates/dsh-sdk-templates.ts (100%)
 rename packages/{sdk => scaffold}/scripts/tests/__snapshots__/config.snapshot.ts.snap (100%)
 rename packages/{sdk => scaffold}/scripts/tests/config.snapshot.ts (100%)
 rename packages/{sdk => scaffold}/scripts/tests/scripts.spec.ts (100%)
 rename packages/{sdk => scaffold}/scripts/tsconfig.json (88%)
 rename packages/{sdk => scaffold}/scripts/tsdown.config.ts (100%)
 create mode 100644 packages/scaffold/server/README.i18n.yaml
 rename packages/{ui/jsonrpc => scaffold/server}/README.md (95%)
 rename packages/{ui/jsonrpc => scaffold/server}/README.zh.md (95%)
 rename packages/{ui/jsonrpc => scaffold/server}/package.json (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/src/index.ts (92%)
 rename packages/{ui/jsonrpc => scaffold/server}/src/invariant.ts (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/src/server.ts (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/tests/built-scope-carrier.e2e.ts (98%)
 rename packages/{ui/jsonrpc => scaffold/server}/tests/plugin-apply.spec.ts (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/tests/plugin-shape.spec.ts (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/tests/server.spec.ts (100%)
 rename packages/{ui/jsonrpc => scaffold/server}/tsconfig.json (93%)
 rename packages/{sdk => scaffold}/telemetry/README.i18n.yaml (80%)
 rename packages/{sdk => scaffold}/telemetry/README.md (100%)
 rename packages/{sdk => scaffold}/telemetry/README.zh.md (100%)
 rename packages/{sdk => scaffold}/telemetry/package.json (100%)
 rename packages/{sdk => scaffold}/telemetry/src/anonymous-id.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/src/consent-resolver.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/src/index.ts (82%)
 rename packages/{sdk => scaffold}/telemetry/src/invariant.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/src/payload.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/src/reporter.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/src/secret-redactor.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tests/anonymous-id.spec.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tests/consent-resolver.spec.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tests/payload.spec.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tests/reporter.spec.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tests/secret-redactor.spec.ts (100%)
 rename packages/{sdk => scaffold}/telemetry/tsconfig.json (100%)
 delete mode 100644 packages/sdk/README.zh.md
 delete mode 100644 packages/sdk/scripts/src/index.ts
 delete mode 100644 packages/sdk/sdk-protocol/README.i18n.yaml
 delete mode 100644 packages/ui/jsonrpc/README.i18n.yaml
 delete mode 100644 packages/ui/permission/README.i18n.yaml
 delete mode 100644 packages/ui/user-interaction/README.i18n.yaml

diff --git a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
index 3cf9548d4d..9b2c456d88 100644
--- a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
+++ b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
@@ -7,7 +7,7 @@ English | [中文](2026-07-27-tui-chat-channel-module-split.zh.md)
 
 ## Problem
 
-`packages/ui/tui/src/index.ts` had grown past 2000 lines. Most of it was one `createTuiChat` factory: a ~1600-line closure holding roughly forty mutable variables and as many nested closures. Model selection, the ask-user-question queue, and session resume were tangled into that single scope, so a reader could not follow any one concern without holding the whole file in their head, and unrelated edits collided. A prior pass had grouped `src/` into `components/`, `session/`, `extension/`, but the entry file itself and the loose top-level input files (`autocomplete.ts`, `file-autocomplete.ts`, `skill-invocation.ts`, `xml-tool-output.ts`) were untouched.
+`packages/interaction/tui/src/index.ts` had grown past 2000 lines. Most of it was one `createTuiChat` factory: a ~1600-line closure holding roughly forty mutable variables and as many nested closures. Model selection, the ask-user-question queue, and session resume were tangled into that single scope, so a reader could not follow any one concern without holding the whole file in their head, and unrelated edits collided. A prior pass had grouped `src/` into `components/`, `session/`, `extension/`, but the entry file itself and the loose top-level input files (`autocomplete.ts`, `file-autocomplete.ts`, `skill-invocation.ts`, `xml-tool-output.ts`) were untouched.
 
 ## Decision
 
diff --git a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
index d5de02bd0f..44e8ffeac4 100644
--- a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
+++ b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
@@ -7,7 +7,7 @@ Archived: 2026-08-04
 
 ## Problem
 
-`packages/ui/tui/src/index.ts` 已超过 2000 行，其中绝大部分是单个 `createTuiChat` 工厂：一个约 1600 行的闭包，持有约四十个可变变量以及同等数量的嵌套闭包。模型选择、ask-user-question 队列、会话恢复都缠绕在这一个作用域里，读者无法在不把整份文件装进脑子的前提下理清任何单一关注点，互不相关的改动也会彼此冲突。此前一轮已把 `src/` 归组为 `components/`、`session/`、`extension/`，但入口文件本身以及散落在顶层的输入相关文件（`autocomplete.ts`、`file-autocomplete.ts`、`skill-invocation.ts`、`xml-tool-output.ts`）未动。
+`packages/interaction/tui/src/index.ts` 已超过 2000 行，其中绝大部分是单个 `createTuiChat` 工厂：一个约 1600 行的闭包，持有约四十个可变变量以及同等数量的嵌套闭包。模型选择、ask-user-question 队列、会话恢复都缠绕在这一个作用域里，读者无法在不把整份文件装进脑子的前提下理清任何单一关注点，互不相关的改动也会彼此冲突。此前一轮已把 `src/` 归组为 `components/`、`session/`、`extension/`，但入口文件本身以及散落在顶层的输入相关文件（`autocomplete.ts`、`file-autocomplete.ts`、`skill-invocation.ts`、`xml-tool-output.ts`）未动。
 
 ## Decision
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
index 62784ed7cd..998e9dfcdc 100644
--- a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
+++ b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
@@ -11,7 +11,7 @@ The TUI rendered transcript notices for `error`, `aborted`, `max-tokens`, `rejec
 
 ## 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.
+The `turn/end` case in `packages/interaction/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
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
index 162ba4ed44..ad53755259 100644
--- a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
+++ b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
@@ -11,7 +11,7 @@ TUI 会为 `error`、`aborted`、`max-tokens`、`rejected`、`interrupted` 这
 
 ## 决策
 
-`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 保留现有通知。
+`packages/interaction/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 保留现有通知。
 
 ## 备选方案
 
diff --git a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
index 1a04e738a2..184a05ed23 100644
--- a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
+++ b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
@@ -15,7 +15,7 @@ The interactive channel must remain a Cordis plugin over the same agent, session
 
 ## Decision
 
-DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior.
+DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior.
 
 The package is a terminal front door, not a complete application. A host mounts `@deepseek-ai/dsh-tui` before its configured agent and composes the backends, tools, and policies around it. The product CLI currently ships no terminal composition; non-interactive tasks use headless mode, Web owns the installed human surface, and ACP remains a separate automation protocol.
 
diff --git a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
index 75fc3d47aa..6ac3eefa51 100644
--- a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
+++ b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
@@ -15,7 +15,7 @@ Archived: 2026-08-04
 
 ## 决策
 
-DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。
+DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。
 
 该包是终端入口，而不是完整应用。宿主在已配置 agent 之前挂载 `@deepseek-ai/dsh-tui`，并围绕它组合后端、工具和策略。产品 CLI 目前不交付终端组合；非交互任务使用 headless 模式，Web 是已安装产品中面向人的界面，而 ACP 仍是独立的自动化协议。
 
diff --git a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
index 9308df7fb4..2c8e92671f 100644
--- a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
+++ b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
@@ -13,7 +13,7 @@ The TUI platform contract must follow the runtime shipped to users rather than t
 
 ## Decision
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) supports interactive terminals on Windows as well as macOS and Linux. The product continues to use pi-tui's `ProcessTerminal`; on Windows it enables virtual-terminal input after raw mode and avoids the Unix-only `SIGWINCH` refresh. DeepSeek Harness adds no platform rejection or reduced Windows mode.
+[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) supports interactive terminals on Windows as well as macOS and Linux. The product continues to use pi-tui's `ProcessTerminal`; on Windows it enables virtual-terminal input after raw mode and avoids the Unix-only `SIGWINCH` refresh. DeepSeek Harness adds no platform rejection or reduced Windows mode.
 
 The real Loader smoke selects a native pseudo-terminal boundary by host. macOS and Linux retain the Python POSIX PTY driver. Windows uses `node-pty` and ConPTY. Both drivers receive the same launch command, environment, terminal dimensions, marker-gated input actions, timeout, expected exit code, and output assertions, and all three smoke scenarios run on every supported platform.
 
diff --git a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
index 8b4a1eb4ce..cb5d05da2b 100644
--- a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
+++ b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
@@ -13,7 +13,7 @@ TUI 平台契约必须以交付给用户的运行时为准，而不是取决于
 
 ## 决策
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 在 Windows、macOS 和 Linux 上均支持交互式终端。产品继续使用 pi-tui 的 `ProcessTerminal`；在 Windows 上，它会在进入原始模式后启用虚拟终端输入，并避开仅适用于 Unix 的 `SIGWINCH` 刷新。DeepSeek Harness 不增加平台拒绝逻辑，也不采用功能受限的 Windows 模式。
+[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 在 Windows、macOS 和 Linux 上均支持交互式终端。产品继续使用 pi-tui 的 `ProcessTerminal`；在 Windows 上，它会在进入原始模式后启用虚拟终端输入，并避开仅适用于 Unix 的 `SIGWINCH` 刷新。DeepSeek Harness 不增加平台拒绝逻辑，也不采用功能受限的 Windows 模式。
 
 真实 Loader 冒烟测试根据宿主选择原生伪终端边界。macOS 和 Linux 继续使用 Python POSIX PTY 驱动，Windows 则使用 `node-pty` 和 ConPTY。两种驱动接收相同的启动命令、环境、终端尺寸、以标记为触发条件的输入动作、超时、预期退出码和输出断言；3 个冒烟场景都会在每个受支持平台上运行。
 
diff --git a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
index e151f92d0d..038d12a561 100644
--- a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
+++ b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
@@ -11,7 +11,7 @@ The [skill system](2026-07-05-skill-system.md) shipped with model-initiated load
 
 ## Decision
 
-The [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) front door owns a `/skill:<name> [instructions]` command. On submit it loads the named skill and delivers one text block as a user turn — sent with `agent.send()` while idle and `agent.steer()` while running, the same rule as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `<skill name="…">` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool. Its visibility and loading policy comes from the shared [independent model and user skill invocation policy](2026-07-28-skill-invocation-policy.md).
+The [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) front door owns a `/skill:<name> [instructions]` command. On submit it loads the named skill and delivers one text block as a user turn — sent with `agent.send()` while idle and `agent.steer()` while running, the same rule as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `<skill name="…">` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool. Its visibility and loading policy comes from the shared [independent model and user skill invocation policy](2026-07-28-skill-invocation-policy.md).
 
 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.
 
diff --git a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
index ac1c4da948..af01642c07 100644
--- a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
+++ b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
@@ -11,7 +11,7 @@ Archived: 2026-08-04
 
 ## Decision
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 前门拥有一条 `/skill:<name> [instructions]` 命令。提交时它加载指定的 skill，并投递一个文本块作为用户轮次——空闲时用 `agent.send()` 发送、运行中用 `agent.steer()` 中途引导，与普通编辑器输入遵循同一规则。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `<skill name="…">` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的功能；它不新增任何面向模型的工具。其可见性和加载策略来自共享的[模型与用户独立 skill 调用策略](2026-07-28-skill-invocation-policy.md)。
+[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 前门拥有一条 `/skill:<name> [instructions]` 命令。提交时它加载指定的 skill，并投递一个文本块作为用户轮次——空闲时用 `agent.send()` 发送、运行中用 `agent.steer()` 中途引导，与普通编辑器输入遵循同一规则。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `<skill name="…">` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的功能；它不新增任何面向模型的工具。其可见性和加载策略来自共享的[模型与用户独立 skill 调用策略](2026-07-28-skill-invocation-policy.md)。
 
 TUI 通过 `ctx.get('skills')` 读取 skill 服务，而非声明式注入，因为 skill 是条件挂载的：没有注册表的部署仍保有可用的前门，此时 `/skill:` 会报告 skill 不可用，而不是挂载失败。`createTuiChat` 是同步的，而 `ctx.skills.list()` 是异步的，所以自动补全先立即种入静态斜杠命令，待目录解析完成后再用 `skill:<name>` 条目重建 provider（提供方）；在 dispose（资源释放）之后才到达的解析结果会被丢弃，而被拒绝的查找会保留基础命令。
 
diff --git a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
index 2ef926cff9..ff4a310f08 100644
--- a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
+++ b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
@@ -13,7 +13,7 @@ The TUI assistant message opened with a single header line joining the `Assistan
 
 **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.
+`AssistantMessageComponent` (packages/interaction/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
 
diff --git a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
index 282ac1e65b..08ced9603d 100644
--- a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
+++ b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
@@ -13,7 +13,7 @@ TUI 的助手消息此前以一行开头，把 `Assistant` 标签和步骤计时
 
 **把标签与计时拆开；计时作为消息的末行渲染。**
 
-`AssistantMessageComponent`（packages/ui/tui/src/index.ts）现在把加粗的 `Assistant` 标签作为首行，并把暗色的计时串（仍由 `StreamingAssistantComponent.rebuild()` 组装为 `header`，settled 时含 `· Completed …` 后缀）作为最后一个子节点，追加在 reasoning 与正文之后。计时内容、隐藏零值桶以及完成时间的行为均不变——仅位置从消息顶部移到底部。
+`AssistantMessageComponent`（packages/interaction/tui/src/index.ts）现在把加粗的 `Assistant` 标签作为首行，并把暗色的计时串（仍由 `StreamingAssistantComponent.rebuild()` 组装为 `header`，settled 时含 `· Completed …` 后缀）作为最后一个子节点，追加在 reasoning 与正文之后。计时内容、隐藏零值桶以及完成时间的行为均不变——仅位置从消息顶部移到底部。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
index ca5edc50bf..76cc213ba8 100644
--- a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
@@ -11,7 +11,7 @@ Roughly ten e2e/smoke files re-derived the same spawn-collect-timeout choreograp
 
 Two related test-infra hand-rolls compounded the case:
 
-- `packages/support/llm-mock-server/src/cli.ts` hand-tokenized 17 value-taking `--flag value` options plus boolean flags (~45–60 lines of loop and value-extraction helpers) where the `node:util` `parseArgs` builtin is already the repo idiom (`cli-demo`, `acp-demo`, `verify-runtime-closure.ts`, `packages/sdk/scripts`).
+- `packages/support/llm-mock-server/src/cli.ts` hand-tokenized 17 value-taking `--flag value` options plus boolean flags (~45–60 lines of loop and value-extraction helpers) where the `node:util` `parseArgs` builtin is already the repo idiom (`cli-demo`, `acp-demo`, `verify-runtime-closure.ts`, `packages/scaffold/scripts`).
 - `apps/web/tests/smoke-real.e2e.ts` and `apps/web/tests/scaffold.ts` carried two verbatim copies of a regex `.env` parser (~20 lines) where the `process.loadEnvFile` builtin has exactly the required no-override semantics — and the vitest e2e/snapshot/web configs already load root `.env` with it before these files run, making the copies dead.
 - The snapshot harness hand-rolled three poll-until-deadline loops (`waitForPersistedTurnStart`/`waitForPersistedTurnEnd`/`waitForWorkspaceFile` in `packages/support/acp-snapshot/src/harness.ts`, ~55 lines) plus `waitForFile` in `crash-recovery.e2e.ts`, where `vi.waitFor`/`expect.poll` cover the shape — vitest is already a runtime dependency of `dsh-acp-snapshot`, so this adds nothing.
 
diff --git a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
index 186e5cd560..f597fd1e08 100644
--- a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
@@ -11,7 +11,7 @@ Archived: 2026-08-07
 
 另有两处相关的测试基础设施手写代码进一步强化了替换的理由：
 
-- `packages/support/llm-mock-server/src/cli.ts` 曾手工逐个切分 17 个带值的 `--flag value` 选项外加若干布尔标志（约 45–60 行的循环与取值辅助函数），而 `node:util` 内置的 `parseArgs` 早已是本仓库的惯用写法（`cli-demo`、`acp-demo`、`verify-runtime-closure.ts`、`packages/sdk/scripts`）。
+- `packages/support/llm-mock-server/src/cli.ts` 曾手工逐个切分 17 个带值的 `--flag value` 选项外加若干布尔标志（约 45–60 行的循环与取值辅助函数），而 `node:util` 内置的 `parseArgs` 早已是本仓库的惯用写法（`cli-demo`、`acp-demo`、`verify-runtime-closure.ts`、`packages/scaffold/scripts`）。
 - `apps/web/tests/smoke-real.e2e.ts` 与 `apps/web/tests/scaffold.ts` 曾携带两份逐字相同的正则 `.env` 解析器拷贝（约 20 行），而内置的 `process.loadEnvFile` 恰好具备所需的「不覆盖已有值」语义；并且 vitest 的 e2e/snapshot/web 配置在这些文件运行之前就已用它加载了根 `.env`，这两份拷贝实为死代码。
 - 快照 harness 曾手写三个「轮询直到截止时间」的循环（`packages/support/acp-snapshot/src/harness.ts` 中的 `waitForPersistedTurnStart`/`waitForPersistedTurnEnd`/`waitForWorkspaceFile`，约 55 行），外加 `crash-recovery.e2e.ts` 中的 `waitForFile`，而 `vi.waitFor`/`expect.poll` 正好覆盖这种形态；vitest 本来就是 `dsh-acp-snapshot` 的运行时依赖，因此这不新增任何东西。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
index 7a0b74dfaf..08d8319d33 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.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 .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
-2026-07-10-single-file-executable-sdk-runtime-distribution.md: f3da981c478ef08672a82f23ab9cd42e0f38ebab
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 5a8e15aab79875bdb08e6347199924c4215a2705
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: fe09e1b83f4f0a9f867f78351f643b1bd26d7c9d
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: ee49d7ea8fade9d3e323e8c6921479b8053809af
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
index f3da981c47..fe09e1b83f 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
@@ -27,8 +27,8 @@ Terminology reminder: pkg's `/snapshot` VFS has nothing to do with this repo's t
 
 The deterministic protocol implementation (`server.ts` / `transport.ts`) lands as two packages on the existing `acp/acp` + `examples/acp-demo` pattern — the serving surface is itself a plugin:
 
-- [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md) (`@deepseek-ai/dsh-jsonrpc`): the pure protocol plugin; on apply it mounts `HarnessSdkServer` plus a line-delimited JSON-RPC transport on the process stdio, with disposal through `ctx.effect()`. Whether to serve is decided by `cordis.yml`; a yml that does not mount it is a legitimate process that does not serve. Protocol-level exit belongs to the plugin (after answering and flushing the `shutdown` response it disposes the root runtime so persistence drains, then `exit(0)`; an HMR-style unload only stops the service without exiting the process).
-- [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md) (`@deepseek-ai/dsh-jsonrpc-demo`): a thin app bin — `installFailLoud` + `loadEnv` + config discovery + `boot()` from [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts), done once boot completes; the server is brought up by the `dsh-jsonrpc` entry in the yml. Its only dependency is app-boot. Process-level exit belongs to the bin (stdin EOF/SIGTERM → dispose then 0, SIGINT → 130).
+- [`packages/scaffold/server`](../../../../packages/scaffold/server/README.md) (`@deepseek-ai/dsh-jsonrpc`): the pure protocol plugin; on apply it mounts `HarnessSdkServer` plus a line-delimited JSON-RPC transport on the process stdio, with disposal through `ctx.effect()`. Whether to serve is decided by `cordis.yml`; a yml that does not mount it is a legitimate process that does not serve. Protocol-level exit belongs to the plugin (after answering and flushing the `shutdown` response it disposes the root runtime so persistence drains, then `exit(0)`; an HMR-style unload only stops the service without exiting the process).
+- [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md) (`@deepseek-ai/dsh-jsonrpc-demo`): a thin app bin — `installFailLoud` + `loadEnv` + config discovery + `boot()` from [`dsh-app-boot`](../../../../packages/boot/app-boot/src/index.ts), done once boot completes; the server is brought up by the `dsh-jsonrpc` entry in the yml. Its only dependency is app-boot. Process-level exit belongs to the bin (stdin EOF/SIGTERM → dispose then 0, SIGINT → 130).
 
 Config discovery has two channels and fails loudly when both are missing: the `DSH_CORDIS_CONFIG` environment variable first (the SDK client convention), then an argv positional argument; no default path and no built-in fallback whatsoever — "the plugins actually booted are decided by an external cordis.yml" is a hard semantic.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
index 5a8e15aab7..ee49d7ea8f 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
@@ -27,8 +27,8 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后
 
 确定性协议实现（`server.ts` / `transport.ts`）按 `acp/acp` + `examples/acp-demo` 的既有模式落为两包——对外服务接口本身也是插件：
 
-- [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并刷新 `shutdown` 响应后 dispose 根运行时以排空持久化，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
-- [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md)（`@deepseek-ai/dsh-jsonrpc-demo`）：轻量应用入口——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts) 的 `boot()`；`boot()` 完成后入口即完成，服务器由 `cordis.yml` 中的 `dsh-jsonrpc` 条目启动。它只依赖 `app-boot`。进程级退出归 `bin` 所有（stdin EOF/SIGTERM → dispose 后返回 0，SIGINT → 130）。
+- [`packages/scaffold/server`](../../../../packages/scaffold/server/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并刷新 `shutdown` 响应后 dispose 根运行时以排空持久化，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
+- [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md)（`@deepseek-ai/dsh-jsonrpc-demo`）：轻量应用入口——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/boot/app-boot/src/index.ts) 的 `boot()`；`boot()` 完成后入口即完成，服务器由 `cordis.yml` 中的 `dsh-jsonrpc` 条目启动。它只依赖 `app-boot`。进程级退出归 `bin` 所有（stdin EOF/SIGTERM → dispose 后返回 0，SIGINT → 130）。
 
 配置发现有两个通道，均缺失时立即报错：优先使用 `DSH_CORDIS_CONFIG` 环境变量（SDK 客户端约定），其次使用 argv 位置参数；没有默认路径或内置回退——「实际启动的插件由外部 `cordis.yml` 决定」是硬语义。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
index 6f4a6d363d..6e2c9a635d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.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 .agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
-2026-07-20-config-hot-reload-resilience.md: 0f15bb0aaacb6e06c416cbe35b44155279497eee
-2026-07-20-config-hot-reload-resilience.zh.md: 8a185c1915b5247150d8bb1dd5c42d69bd4f2a35
+2026-07-20-config-hot-reload-resilience.md: 2b98ee73e1c7734da9c0ae6df5e3de1af6a5cbeb
+2026-07-20-config-hot-reload-resilience.zh.md: 4ddf1f07f4ff5449f3bd91aa2b38f6045eb4e1c6
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
index 0f15bb0aaa..2b98ee73e1 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.md
@@ -38,4 +38,4 @@ HMR contains live refresh rejection. Its `registerConfig(filename, refresh)` met
 
 ## Testing
 
-`packages/ui/app-boot/tests/config-reload.spec.ts` boots real temporary Loader/Include trees and covers parse and shape rejection, import-before-dispose, plugin/config restoration, multi-entry rollback, ancestor disablement, overlay convergence, option identity, failed direct-update persistence, and failed programmatic moves. `packages/ui/app-boot/tests/hmr-config.spec.ts` covers existing and missing exact paths, add/change/removal, serialized coalescing, disposal drainage, non-`Error` normalization, failure broadcast, and rejecting-observer containment. `packages/host/webserver/tests/webserver.spec.ts` proves a service-gated startup failure rejects Loader composition with its bind diagnostic, `packages/typert/loader/tests/loader.spec.ts` exercises awaited programmatic removal through a real Loader consumer, and the ACP `pty-tools` snapshot guards concurrent composition from reordering equal-priority prompt sections.
+`packages/boot/app-boot/tests/config-reload.spec.ts` boots real temporary Loader/Include trees and covers parse and shape rejection, import-before-dispose, plugin/config restoration, multi-entry rollback, ancestor disablement, overlay convergence, option identity, failed direct-update persistence, and failed programmatic moves. `packages/boot/app-boot/tests/hmr-config.spec.ts` covers existing and missing exact paths, add/change/removal, serialized coalescing, disposal drainage, non-`Error` normalization, failure broadcast, and rejecting-observer containment. `packages/host/webserver/tests/webserver.spec.ts` proves a service-gated startup failure rejects Loader composition with its bind diagnostic, `packages/typert/loader/tests/loader.spec.ts` exercises awaited programmatic removal through a real Loader consumer, and the ACP `pty-tools` snapshot guards concurrent composition from reordering equal-priority prompt sections.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
index 8a185c1915..4ddf1f07f4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
@@ -38,4 +38,4 @@ HMR 收容实时刷新 rejection。其 `registerConfig(filename, refresh)` 方
 
 ## Testing
 
-`packages/ui/app-boot/tests/config-reload.spec.ts` 启动真实的临时 Loader/Include 树，并覆盖对解析和形状错误的拒绝、先导入再 dispose、插件/配置恢复、多配置项回滚、祖先禁用、overlay 收敛、option 对象身份、失败的直接更新不持久化以及失败的程序化移动。`packages/ui/app-boot/tests/hmr-config.spec.ts` 覆盖现有和缺失的确切路径、添加/变更/移除、串行化合并、dispose 排空、非 `Error` 值的规范化、失败广播以及对发生 rejection 的观察者的收容。`packages/host/webserver/tests/webserver.spec.ts` 证明受服务门控的启动失败会让 Loader 组合以其 bind 诊断 reject；`packages/typert/loader/tests/loader.spec.ts` 则通过真实 Loader 消费方演练可等待的程序化移除；ACP（Agent Client Protocol）的 `pty-tools` 快照会防止并发组合改变同优先级提示词段的顺序。
+`packages/boot/app-boot/tests/config-reload.spec.ts` 启动真实的临时 Loader/Include 树，并覆盖对解析和形状错误的拒绝、先导入再 dispose、插件/配置恢复、多配置项回滚、祖先禁用、overlay 收敛、option 对象身份、失败的直接更新不持久化以及失败的程序化移动。`packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖现有和缺失的确切路径、添加/变更/移除、串行化合并、dispose 排空、非 `Error` 值的规范化、失败广播以及对发生 rejection 的观察者的收容。`packages/host/webserver/tests/webserver.spec.ts` 证明受服务门控的启动失败会让 Loader 组合以其 bind 诊断 reject；`packages/typert/loader/tests/loader.spec.ts` 则通过真实 Loader 消费方演练可等待的程序化移除；ACP（Agent Client Protocol）的 `pty-tools` 快照会防止并发组合改变同优先级提示词段的顺序。
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
index fa097ae230..b5c6343382 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.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 .agents/notes/implemented/feature/2026-07-06-approval-seam.md
-2026-07-06-approval-seam.md: ae143a41302b7bcd6029345fa91ca4eda837c141
-2026-07-06-approval-seam.zh.md: 2f95f67ecd33b4c659e56d5f3cc6168bf01e35ce
+2026-07-06-approval-seam.md: a286e07d51a70232f9aab0af5d8a19622cd222d4
+2026-07-06-approval-seam.zh.md: 6656cfe46de663f0e89eacc78dcfb3425812f9e0
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.md b/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
index ae143a4130..a286e07d51 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
@@ -12,7 +12,7 @@ The routing problem is ownership: a permission request must reach the channel th
 
 ## Decision
 
-One package, `dsh-user-approval` (`packages/ui/user-approval`), owns the vocabulary and the `ctx.approval` service — the mechanism. The policy — who answers, and whether a session is asked at all — lives outside it: answerers are `approval/request` waterfall listeners registered by channel-owning plugins (the ACP bridge, host adapters, and test scripts), and a per-session policy tier can decide before a channel is involved. Consumers (`dsh-tools`' ask routing and the sandbox escalation gate) resolve a question to a closed outcome and derive their own tool results from it. This is deliberately one package, not the capability-seam three (see Alternatives).
+One package, `dsh-user-approval` (`packages/interaction/user-approval`), owns the vocabulary and the `ctx.approval` service — the mechanism. The policy — who answers, and whether a session is asked at all — lives outside it: answerers are `approval/request` waterfall listeners registered by channel-owning plugins (the ACP bridge, host adapters, and test scripts), and a per-session policy tier can decide before a channel is involved. Consumers (`dsh-tools`' ask routing and the sandbox escalation gate) resolve a question to a closed outcome and derive their own tool results from it. This is deliberately one package, not the capability-seam three (see Alternatives).
 
 ### How a deployment uses it
 
@@ -95,7 +95,7 @@ Snapshots record allowed and rejected sandbox escalation through `session/reques
 
 - **A single registered provider instead of waterfall listeners** — rejected: a `registerProvider()` surface forces every composition question — allowlist pre-filters, external hook deciders, scripted test answers, a policy gate in front of a human — inside one provider implementation. The waterfall gets composition, fail-closed absence, and HMR disposal from machinery the runtime already has; the seam's JSDoc pins the single-decision-slot convention instead of inventing a provider registry.
 - **An inline `tools/pre-execute` permission gate in the ACP bridge** — rejected: prompting for every bridge-owned call hardwires the asking policy into the transport, cannot serve a second asker (sandbox escalation happens after execution starts, with no pre-execute moment), and leaves hook-produced `ask` decisions without a shared mechanism.
-- **The generic user-interaction seam (`ctx.userInteraction`)** — rejected as the approval mechanism: the two share a skeleton (route by agent, block for a human, handle absence), but approval's contract is narrower in every dimension that matters: a closed outcome vocabulary instead of free text, a protocol-native prompt attached to a tool call instead of a generic form, mandatory fail-closed absence, and audit events. Approval therefore does not ride the shipped `packages/ui/user-interaction` / `ask_user_question` elicitation path — an elicitation form is not a permission prompt, and a free-text answer is not a closed outcome; sharing provider plumbing stays open if the two ever converge.
+- **The generic user-interaction seam (`ctx.userInteraction`)** — rejected as the approval mechanism: the two share a skeleton (route by agent, block for a human, handle absence), but approval's contract is narrower in every dimension that matters: a closed outcome vocabulary instead of free text, a protocol-native prompt attached to a tool call instead of a generic form, mandatory fail-closed absence, and audit events. Approval therefore does not ride the shipped `packages/interaction/user-interaction` / `ask_user_question` elicitation path — an elicitation form is not a permission prompt, and a free-text answer is not a closed outcome; sharing provider plumbing stays open if the two ever converge.
 - **Static optional injection in `dsh-tools`** — rejected: the vendored cordis `Inject` type has no optional flag — the object form maps service names to intercept config, and a declared inject gates the fiber. `ctx.get('approval')` is the documented opportunistic-consumption pattern (the `tool-bash` owner-token lookup, the loop's persistence probe), reads presence per call, and degrades correctly across HMR without extra machinery.
 - **The capability-seam three-package split** — rejected: interface/implementation/consumer fits a seam whose implementation is swappable (bash-local vs bash-sandbox). Here the service body is fixed mechanism and the variable part is listeners that live with their owners — splitting would manufacture an implementation package with nothing in it ("don't split preemptively").
 - **Offering `allow_always` now** — rejected: the protocol can express it, but honoring it means designing grant storage, scope identity, and revocation (§ Deferred). Advertising an option the harness cannot honor manufactures doomed grants.
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
index 2f95f67ecd..6656cfe46d 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-一个包`dsh-user-approval`（`packages/ui/user-approval`）负责定义词汇表和 `ctx.approval` 服务——即机制。策略——谁来应答、某个会话是否需要被询问——不在其中：应答者是 `approval/request` waterfall 监听器，由拥有通道的插件注册（ACP（Agent Client Protocol）桥、宿主适配器、测试脚本），而每会话的策略层可以在任何通道介入之前做出决定。消费方（`dsh-tools` 的 ask 路由和沙箱升级门禁）将问题解析为一个封闭结果，并从中派生各自的工具结果。刻意设计为一个包，而非能力 seam 的三包拆分（见「替代方案」）。
+一个包`dsh-user-approval`（`packages/interaction/user-approval`）负责定义词汇表和 `ctx.approval` 服务——即机制。策略——谁来应答、某个会话是否需要被询问——不在其中：应答者是 `approval/request` waterfall 监听器，由拥有通道的插件注册（ACP（Agent Client Protocol）桥、宿主适配器、测试脚本），而每会话的策略层可以在任何通道介入之前做出决定。消费方（`dsh-tools` 的 ask 路由和沙箱升级门禁）将问题解析为一个封闭结果，并从中派生各自的工具结果。刻意设计为一个包，而非能力 seam 的三包拆分（见「替代方案」）。
 
 ### 部署如何使用它
 
@@ -95,7 +95,7 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 - **单一注册提供方而非 waterfall 监听器**：否决。`registerProvider()` 接口迫使所有组合问题——允许列表预过滤、外部钩子决策者、脚本化测试应答、人类前面的策略门禁——都塞进一个提供方实现。waterfall 直接复用运行时已有的组合能力、缺失时默认拒绝行为和 HMR（热模块替换）资源释放机制；seam 的 JSDoc 以约定固定单决策槽语义，而非发明一个提供方注册表。
 - **在 ACP 桥中内联 `tools/pre-execute` 权限门禁**：否决。对桥拥有的每次调用都弹出提示，会将请求策略硬编码进传输层，无法服务第二个发起方（沙箱升级发生在执行开始之后，没有 pre-execute 时刻），且钩子产生的 `ask` 决策没有共享机制。
-- **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的契约在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/ui/user-interaction` / `ask_user_question` 信息征集路径——信息征集表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
+- **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的契约在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/interaction/user-interaction` / `ask_user_question` 信息征集路径——信息征集表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
 - **`dsh-tools` 中的静态可选注入**：否决。vendor 的 Cordis `Inject` 类型没有 optional 标志——对象形式将服务名映射到拦截配置，声明的 inject 会阻塞 fiber。`ctx.get('approval')` 是文档化的机会性消费模式（`tool-bash` 的 owner-token 查找、loop 的持久化探测），按调用读取存在性，跨 HMR 正确降级，无需额外机制。
 - **能力 seam 的三包拆分**：否决。接口/实现/消费方适合实现可替换的 seam（bash-local vs bash-sandbox）。此处服务体是固定机制，可变部分是留在各自通道拥有者插件中的监听器——拆分只会制造一个空的实现包（「不要预防性拆分」）。
 - **现在就提供 `allow_always`**：否决。协议能表达它，但兑现它意味着设计授权存储、作用域标识和撤销（§ 延后）。展示 harness 无法兑现的选项只会制造注定失败的授权。
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
index 205ce40bb2..b2e1785796 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.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 .agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
-2026-07-12-subagent-persona-tool-filter-and-depth.md: c690f4701a54272205eedf719fbfe0863bac566c
-2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: e14214b16c413eaa05bcea7bcdf9bca996e8d616
+2026-07-12-subagent-persona-tool-filter-and-depth.md: 2c5eaf8829e01536a2de34cc190573ff35e4ab77
+2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: 355db26ecaf57137420798474561d6a7032757cb
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
index c690f4701a..2c5eaf8829 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
@@ -53,7 +53,7 @@ The depth limit bounds recursive delegation independently of tool visibility. A
 
 The effective parent depth is the greater of durable `SessionHeader.delegationDepth` and runtime `AgentOptions.subagentDepth`. An in-process child records its derived depth in the session header, and resume restores that header, so a restart cannot lower the recursion count.
 
-Every public entry validates the domain rather than relying on one model-facing configuration path. Negative values, fractions, negative zero, non-finite values, unsafe integers, malformed stored parent depth, and derived overflow all reject. A direct `SubagentStartRequest` may omit the cap to leave depth unbounded; loader-resolved `dsh-tool-subagent` configuration instead defaults to `3`, accepts a numeric override, and uses explicit `'provider-managed'` to omit the cap for an out-of-process provider whose deployment owns its recursion budget. Three is a small finite default that still permits a root plus three descendant generations: the [SDK helper's generated subagent entries](../../../../packages/sdk/helper/src/features/builtin/index.ts) and [JSON-RPC example](../../../../examples/jsonrpc-agent/cordis.yml) use that general policy, while the shipped interactive ACP, headless, and REPL examples pin one. A numeric tool cap fails at provider mount when the provider lacks `depthLimit`.
+Every public entry validates the domain rather than relying on one model-facing configuration path. Negative values, fractions, negative zero, non-finite values, unsafe integers, malformed stored parent depth, and derived overflow all reject. A direct `SubagentStartRequest` may omit the cap to leave depth unbounded; loader-resolved `dsh-tool-subagent` configuration instead defaults to `3`, accepts a numeric override, and uses explicit `'provider-managed'` to omit the cap for an out-of-process provider whose deployment owns its recursion budget. Three is a small finite default that still permits a root plus three descendant generations: the [SDK helper's generated subagent entries](../../../../packages/scaffold/helper/src/features/builtin/index.ts) and [JSON-RPC example](../../../../examples/jsonrpc-agent/cordis.yml) use that general policy, while the shipped interactive ACP, headless, and REPL examples pin one. A numeric tool cap fails at provider mount when the provider lacks `depthLimit`.
 
 A deployment can combine depth and filtering, but the numeric cap does not synthesize a filter. The delegation tool stays visible at the cap because authorization may depend on runtime state; every attempted start checks the calling agent's current durable and runtime depth, and a rejected start returns an errored tool result without publishing a child. A deployment may separately deny delegation tools in children when its visibility policy is static. Neither choice changes the provider's conversation-history behavior.
 
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
index e14214b16c..355db26eca 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
@@ -53,7 +53,7 @@ subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `ma
 
 有效父级深度取持久 `SessionHeader.delegationDepth` 与运行时 `AgentOptions.subagentDepth` 中的较大值。进程内子 agent 把推导出的深度记录在会话 header 中，恢复时会重新载入该 header，因此重启无法降低递归计数。
 
-每个公开入口都自行验证值域，而非依赖单一的面向模型配置路径。负值、小数、负零、非有限值、不安全整数、格式错误的存储父级深度以及推导溢出均被拒绝。直接的 `SubagentStartRequest` 可以省略上限，让此机制不约束深度；经 loader 解析的 `dsh-tool-subagent` 配置则默认值为 `3`、接受数值覆盖，并使用显式的 `'provider-managed'` 来省略由进程外提供方部署拥有递归预算时的上限。三是一个较小的有限默认值，仍允许 root 加三代后代：[SDK 辅助函数生成的 subagent 条目](../../../../packages/sdk/helper/src/features/builtin/index.ts)和 [JSON-RPC 示例](../../../../examples/jsonrpc-agent/cordis.yml)采用这项通用策略，而已交付的交互式 ACP、headless 和 REPL 示例固定为一。提供方缺少 `depthLimit` 时，数值工具上限会在提供方挂载阶段失败。
+每个公开入口都自行验证值域，而非依赖单一的面向模型配置路径。负值、小数、负零、非有限值、不安全整数、格式错误的存储父级深度以及推导溢出均被拒绝。直接的 `SubagentStartRequest` 可以省略上限，让此机制不约束深度；经 loader 解析的 `dsh-tool-subagent` 配置则默认值为 `3`、接受数值覆盖，并使用显式的 `'provider-managed'` 来省略由进程外提供方部署拥有递归预算时的上限。三是一个较小的有限默认值，仍允许 root 加三代后代：[SDK 辅助函数生成的 subagent 条目](../../../../packages/scaffold/helper/src/features/builtin/index.ts)和 [JSON-RPC 示例](../../../../examples/jsonrpc-agent/cordis.yml)采用这项通用策略，而已交付的交互式 ACP、headless 和 REPL 示例固定为一。提供方缺少 `depthLimit` 时，数值工具上限会在提供方挂载阶段失败。
 
 部署可以组合深度与过滤，但数值上限不会合成过滤器。委派工具在上限处仍然可见，因为授权可能依赖运行时状态；每次尝试启动都会检查调用方 agent 当前的持久与运行时深度，被拒绝的启动返回错误工具结果，且不发布子 agent。可见性策略固定的部署可以另外在子 agent 中 deny 委派工具。两种选择都不改变提供方的对话历史行为。
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index 673e4869af..a54f2e9496 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.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 .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
-2026-07-16-harness-level-loop.md: 36a567204ee1082d48126369ee0b7277c9f24ca8
-2026-07-16-harness-level-loop.zh.md: cb8d29b4c77848613a6718ea3a343b0ee3294ea4
+2026-07-16-harness-level-loop.md: f37bea0842b3f40bf07c6660ad758d84ece23f1b
+2026-07-16-harness-level-loop.zh.md: 0ec2dc2294c1adf8b7f6f810bfaffa7e08c19ed2
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
index 36a567204e..f37bea0842 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
@@ -38,7 +38,7 @@ Time-based `/loop` or scheduled execution is a third policy and is not implement
 | `@deepseek-ai/dsh-goal` | `packages/goal/goal/`, domain service | Owns `GoalId`, compare-and-set `GoalRef`, `GoalSnapshot`, four-state `GoalPhase`, structured `GoalBlockReason`, process-local `GoalActivation`, replay folding, and `get`, `create`, `edit`, `pause`, `resume`, `complete`, `block`, `clear`, and `disarm` verbs. |
 | `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`, model-facing consumer | Registers exclusive `get_goal`, `create_goal`, and `update_goal`; authenticates live turn provenance and narrows autonomous-round authority to completion or blocking reports with machine-routable reason codes. |
 | `@deepseek-ai/dsh-goal-session` | `packages/goal/goal-session/`, continuation policy | Reserves, fences, admits, attributes, settles, cancels, and quiescently drains same-session goal rounds without importing the concrete loop. |
-| `@deepseek-ai/dsh-commands` | `packages/ui/commands/`, UI registry | Owns `CommandDefinition`, discovery, scoped registration, direct dispatch, `CommandResult`, and request cancellation for human-only commands. |
+| `@deepseek-ai/dsh-commands` | `packages/interaction/commands/`, UI registry | Owns `CommandDefinition`, discovery, scoped registration, direct dispatch, `CommandResult`, and request cancellation for human-only commands. |
 | `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`, human-command producer | Registers `/goal` status, creation, edit, pause, resume, and clear over the goal domain for TUI. |
 | `@deepseek-ai/dsh-tool-ralph` | `packages/workflow/tool-ralph/`, fixed workflow consumer | Registers `ralph({ objective, maxRounds? })`, validates the fresh structured provider and bounded `RalphRoundReport`, and returns `complete`, `blocked`, or `budget-limited`. |
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index cb8d29b4c7..0ec2dc2294 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -38,7 +38,7 @@ Status: implemented
 | `@deepseek-ai/dsh-goal` | `packages/goal/goal/`，领域服务 | 拥有 `GoalId`、比较并交换 `GoalRef`、`GoalSnapshot`、四状态 `GoalPhase`、结构化 `GoalBlockReason`、进程本地 `GoalActivation`、重放折叠，以及 `get`、`create`、`edit`、`pause`、`resume`、`complete`、`block`、`clear` 与 `disarm` 动词。 |
 | `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`，面向模型消费方 | 注册互斥的 `get_goal`、`create_goal` 与 `update_goal`；认证实时 Turn 来源，并把自治 Round 权限收窄到带机器可路由原因代码的完成或阻塞报告。 |
 | `@deepseek-ai/dsh-goal-session` | `packages/goal/goal-session/`，续行策略 | 在不导入具体 loop 的情况下，预留、设围栏、接纳、归属、结算、取消并排空同会话 Goal Round，直至完全停稳。 |
-| `@deepseek-ai/dsh-commands` | `packages/ui/commands/`，UI 注册表 | 拥有面向人类专用命令的 `CommandDefinition`、发现、作用域注册、直接分发、`CommandResult` 与请求取消。 |
+| `@deepseek-ai/dsh-commands` | `packages/interaction/commands/`，UI 注册表 | 拥有面向人类专用命令的 `CommandDefinition`、发现、作用域注册、直接分发、`CommandResult` 与请求取消。 |
 | `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`，人类命令生产方 | 为 TUI 注册构建在目标领域之上的 `/goal` 状态、创建、编辑、暂停、恢复与清除。 |
 | `@deepseek-ai/dsh-tool-ralph` | `packages/workflow/tool-ralph/`，固定工作流消费方 | 注册 `ralph({ objective, maxRounds? })`，验证全新结构化 provider 与有界 `RalphRoundReport`，并返回 `complete`、`blocked` 或 `budget-limited`。 |
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
index c3bbbe1d22..e58d618cf3 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.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 .agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
-2026-07-19-plugin-command-registration.md: 5233ce511dc9798733513ccbf6824f3e1b68d2e6
-2026-07-19-plugin-command-registration.zh.md: 7f41b9d2d00373901b51e3338fa51e1cadf886a9
+2026-07-19-plugin-command-registration.md: c8f0f2772a41948e9eb257a16f40194518c568f9
+2026-07-19-plugin-command-registration.zh.md: 94853393f5f71b29cfbd8da5443b3d73ded20e92
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
index 5233ce511d..c8f0f2772a 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
@@ -12,7 +12,7 @@ A shared mechanism must remain a UI concern rather than a model tool or agent-lo
 
 ## Decision
 
-`@deepseek-ai/dsh-commands` in `packages/ui/commands/` is the product command registry. The TUI app bundle mounts it beside its consuming front door; the [automation-only ACP app](../simplification/2026-07-23-acp-automation-only-protocol.md) and the executor-less, UI-less agent spine omit it. TUI injects the service, while command producers depend only on the registry and any domain they operate.
+`@deepseek-ai/dsh-commands` in `packages/interaction/commands/` is the product command registry. The TUI app bundle mounts it beside its consuming front door; the [automation-only ACP app](../simplification/2026-07-23-acp-automation-only-protocol.md) and the executor-less, UI-less agent spine omit it. TUI injects the service, while command producers depend only on the registry and any domain they operate.
 
 ### Registry contract
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
index 7f41b9d2d0..94853393f5 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
@@ -12,7 +12,7 @@ TUI 拥有斜杠命令。如果命令名、帮助文本、自动补全、分派
 
 ## 决策
 
-位于 `packages/ui/commands/` 的 `@deepseek-ai/dsh-commands` 是产品命令注册表。TUI 应用 bundle（组合包）把它挂载在消费该服务的入口旁；[仅面向自动化的 ACP（Agent Client Protocol）应用](../simplification/2026-07-23-acp-automation-only-protocol.md)和无执行器、无 UI 的智能体 spine（主干）都省略该服务。TUI 注入该服务，命令生产者只依赖注册表及其操作的领域。
+位于 `packages/interaction/commands/` 的 `@deepseek-ai/dsh-commands` 是产品命令注册表。TUI 应用 bundle（组合包）把它挂载在消费该服务的入口旁；[仅面向自动化的 ACP（Agent Client Protocol）应用](../simplification/2026-07-23-acp-automation-only-protocol.md)和无执行器、无 UI 的智能体 spine（主干）都省略该服务。TUI 注入该服务，命令生产者只依赖注册表及其操作的领域。
 
 ### 注册表契约
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index ee99911ee8..0cf926921b 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.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 .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
-2026-07-20-dsh-cli-personal-config.md: 2a8ae4b235823b4493d2f082d37b85806f45b662
-2026-07-20-dsh-cli-personal-config.zh.md: d8ff6c4fcc5da8f1db6f030e990118e30ae6fe41
+2026-07-20-dsh-cli-personal-config.md: c00432ba2b75cc42caf23e405c24acb33d839e7a
+2026-07-20-dsh-cli-personal-config.zh.md: b33a7fa321ca04f41e47386544ffc0f268a8b1b6
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
index 2a8ae4b235..c00432ba2b 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
@@ -48,4 +48,4 @@ The TUI and Web register the exact personal path through Cordis HMR after boot.
 
 ## Testing
 
-`packages/ui/app-boot/tests/user-patches.spec.ts` pins parsing, startup application, exact-path add/failure/recovery/removal, last-good rollback, failure broadcast, and preservation of app-owned patches. `apps/cli/tests/built-bin.e2e.ts` boots the real dsh bin over a profile and exercises the live patch layer end to end. Test launchers isolate `$DSH_HOME`, so a developer's real overlay cannot leak into fixtures.
+`packages/boot/app-boot/tests/user-patches.spec.ts` pins parsing, startup application, exact-path add/failure/recovery/removal, last-good rollback, failure broadcast, and preservation of app-owned patches. `apps/cli/tests/built-bin.e2e.ts` boots the real dsh bin over a profile and exercises the live patch layer end to end. Test launchers isolate `$DSH_HOME`, so a developer's real overlay cannot leak into fixtures.
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index d8ff6c4fcc..b33a7fa321 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -48,4 +48,4 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 
 ## Testing
 
-`packages/ui/app-boot/tests/user-patches.spec.ts` 固定解析、启动时应用、确切路径的新增／失败／恢复／移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`apps/cli/tests/built-bin.e2e.ts` 启动真实 dsh bin 并基于 profile 端到端验证实时 patch 层。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
+`packages/boot/app-boot/tests/user-patches.spec.ts` 固定解析、启动时应用、确切路径的新增／失败／恢复／移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`apps/cli/tests/built-bin.e2e.ts` 启动真实 dsh bin 并基于 profile 端到端验证实时 patch 层。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
index a7d065d42d..1d93b7f440 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.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 .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
-2026-07-21-continuable-background-subagents.md: 6bbbfb25fb24eba95de888c9d23c79e24fc8535b
-2026-07-21-continuable-background-subagents.zh.md: e23fbe67cc2d16a2c01a1b7ed4884008f8932dd4
+2026-07-21-continuable-background-subagents.md: e37abdd798242bc1086754e86a85ef46c08e59a3
+2026-07-21-continuable-background-subagents.zh.md: 799e1914bdeb571dc697652081be6b0170768655
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
index 6bbbfb25fb..e37abdd798 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
@@ -112,7 +112,7 @@ Task records and active-run associations are process-local. Persistence makes th
 - `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` pins the continuable durability boundary: an absent or detached flush listener and a permanent listener failure reject with `DURABILITY_FAILED`, a transient loop-checkpoint failure can succeed on the final confirmation, cancellation owns either final-checkpoint outcome, resume also confirms durability, and foreground runs remain best-effort. `packages/subagent/subagent/tests/continuation.spec.ts` drives the real stack (agent loop, JSONL persistence, spawn/fork providers, Task service, and `ctx.subagents`) keylessly: initial and resumed activations create fresh Tasks and dispose their runs before terminal; the descriptor event is pre-turn, model-hidden, versioned, durable under the service-allocated child id, and survives blocked or throwing initial prompt admission; cancellation, steering, cold follow-up, authorization, ownership conflicts, and resume races retain the contracts described above.
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` pins the `send_message` schema, coordinator attribution, both route renderings, the not-delivered failure, the no-agent rejection, and HMR disposal.
 - `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` covers the configured background route: continuable mode requires a resumable provider and returns both ids without requiring `send_message`, while one-shot mode keeps the plain Task acknowledgement even when the provider can resume.
-- `packages/sdk/helper/tests/project.spec.ts` pins the Task service and model-facing Task controls in generated spawn and fork compositions.
+- `packages/scaffold/helper/tests/project.spec.ts` pins the Task service and model-facing Task controls in generated spawn and fork compositions.
 - The keyless ACP snapshot scenario `subagent-continuable` (examples/acp-agent) pins the model-visible transcript: the two-id acknowledgement, a final durability-confirmation failure rendered through `task_output` without unconfirmed child output, and a `send_message` follow-up whose started Task fails with the id unavailable.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
index e23fbe67cc..799e1914bd 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
@@ -112,7 +112,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 - `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述契约。
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` 固定 `send_message` 的 schema、coordinator 来源标记、两种路由渲染、未送达失败、无 agent 时的拒绝，以及 HMR（热模块替换）dispose。
 - `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 覆盖配置的后台路由：可继续模式要求提供方可恢复，并在不要求 `send_message` 的情况下返回两个 id；即使提供方可以恢复，一次性模式仍保持普通的 Task 确认消息。
-- `packages/sdk/helper/tests/project.spec.ts` 固定生成的 spawn 与 fork 组合中的 Task 服务及面向模型的 Task 控制工具。
+- `packages/scaffold/helper/tests/project.spec.ts` 固定生成的 spawn 与 fork 组合中的 Task 服务及面向模型的 Task 控制工具。
 - 无密钥 ACP 快照场景 `subagent-continuable`（examples/acp-agent）固定模型可见的 transcript：双 id 确认消息、最终持久性确认失败（该失败通过 `task_output` 呈现，且不包含未经确认的 child 输出），以及一次 `send_message` 后续操作——其已启动的 Task 会带着「id 不可用」失败。
 
 ## 影响
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
index 6018cb1305..38dc165e7f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.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 .agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: 96ffd772810a7908ff452967aa0be0e540bc2d8c
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: 74ae4b81807d1267dc19f30d2bb51e50a775c4be
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: c5c6c4eac053e9a3adfa2a2a441ac492ba3391ac
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: 643ec36134a1ebe940da5de5b373fa0c25afcd42
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
index 96ffd77281..c5c6c4eac0 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
@@ -12,8 +12,8 @@ The stdio JSON-RPC serving surface (`@deepseek-ai/dsh-jsonrpc`, the [single-exe
 
 Three packages, layered exactly like the existing Python stack, plus one seam registration:
 
-- **`@deepseek-ai/dsh-sdk-protocol`** (`packages/sdk/sdk-protocol/`) — the wire made shared and nominal. `JsonRpcLineTransport` moves here verbatim from `dsh-jsonrpc` (which now imports it), and `types.ts` names every payload the server speaks: `InitializeParams/Result`, `SessionPromptParams/Result`, the four notification payloads, and the `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` indexes. The package root explicitly exports that complete interface and provides no source-module deep imports. The server's `notify()` call sites are typed against these named payloads, so server drift breaks compilation, not clients. One behavioral change: an error response now rejects with `JsonRpcResponseError` carrying the wire `code`/`data` (the Python client already preserved these; the old transport threw a bare `Error` with only the message).
-- **`@deepseek-ai/dsh-sdk-client`** (`packages/sdk/sdk-client/`) — the TypeScript twin of `python/sdk`: `HarnessClient` (spawn, frame, fan out notifications, typed error surfaces, close-to-quiescence via the shared dispose ladder) under `DeepSeekHarness`/`HarnessSession` (lazy start, memoized `initialize`, `run()` pairing one `session/prompt` with its `session.finished`). Its package-root consumer interface explicitly exports both client layers, caller-facing types, and the protocol-owned `JsonRpcResponseError`; source modules, normalization helpers, and the notification producer stay internal. `TurnResult.events` contains only the root session's typed events, while `notifications` retains session ids across the root and descendants discovered from `subagent.started`; session-tree scoping is client-side, mirroring `client.py`. Deliberate asymmetries with Python: the launch spec is explicit `command`/`args` (no bundled-runtime resolution — that is a distribution concern with no TS consumer yet); `env` replaces rather than merges (callers own credential policy; `scrubbedParentEnv` from the subprocess seam is one import away); `TurnResult` carries the structured `reason` (Python exposes only `status`); teardown walks a private stdin-EOF → SIGTERM → SIGKILL ladder to actual exit (the client runs outside any harness context, so it cannot ride `ctx.subprocess`).
+- **`@deepseek-ai/dsh-sdk-protocol`** (`packages/scaffold/protocol/`) — the wire made shared and nominal. `JsonRpcLineTransport` moves here verbatim from `dsh-jsonrpc` (which now imports it), and `types.ts` names every payload the server speaks: `InitializeParams/Result`, `SessionPromptParams/Result`, the four notification payloads, and the `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` indexes. The package root explicitly exports that complete interface and provides no source-module deep imports. The server's `notify()` call sites are typed against these named payloads, so server drift breaks compilation, not clients. One behavioral change: an error response now rejects with `JsonRpcResponseError` carrying the wire `code`/`data` (the Python client already preserved these; the old transport threw a bare `Error` with only the message).
+- **`@deepseek-ai/dsh-sdk-client`** (`packages/scaffold/client/`) — the TypeScript twin of `python/sdk`: `HarnessClient` (spawn, frame, fan out notifications, typed error surfaces, close-to-quiescence via the shared dispose ladder) under `DeepSeekHarness`/`HarnessSession` (lazy start, memoized `initialize`, `run()` pairing one `session/prompt` with its `session.finished`). Its package-root consumer interface explicitly exports both client layers, caller-facing types, and the protocol-owned `JsonRpcResponseError`; source modules, normalization helpers, and the notification producer stay internal. `TurnResult.events` contains only the root session's typed events, while `notifications` retains session ids across the root and descendants discovered from `subagent.started`; session-tree scoping is client-side, mirroring `client.py`. Deliberate asymmetries with Python: the launch spec is explicit `command`/`args` (no bundled-runtime resolution — that is a distribution concern with no TS consumer yet); `env` replaces rather than merges (callers own credential policy; `scrubbedParentEnv` from the subprocess seam is one import away); `TurnResult` carries the structured `reason` (Python exposes only `status`); teardown walks a private stdin-EOF → SIGTERM → SIGKILL ladder to actual exit (the client runs outside any harness context, so it cannot ride `ctx.subprocess`).
 - **`@deepseek-ai/dsh-subagent-dsh-sdk`** (`packages/subagent/subagent-dsh-sdk/`) — the second out-of-process `SubagentProvider`, structured as `subagent-acp`'s sibling: same all-false capabilities and `inheritsParentContext: false`, same publish-after-handshake ownership transaction, same result-never-rejects flattening through an `onError` sink, same parent-namespace run id. The child answer is read from streamed `session.event`s — the last complete `assistant/message`, else accumulated `text-delta` chunks, so partial answers survive cancellation. Stop reasons map from the child's structured `TurnEndReason` (`completed`/`max-tokens`/`aborted` pass through; everything else, including a settled-without-turn child, is `error`). Its `provider`/`model` config feeds the child's `initialize`; `env` is where deployments pass the child's own key and `DSH_CORDIS_CONFIG`.
 - **The subagent seam grows `out-of-process.ts`**: the provider-side vocabulary both out-of-process backends share — `NO_START_CAPABILITIES`, timing-bound validation, child cwd resolution (config override, else the delegating parent session's workspace), the never-reject `settleRunResult`, and the `subprocessRunHandle` publication. Process mechanics (spawn, env scrub, tree-scoped teardown) live in the `dsh-subprocess` seam; `subagent-acp` spawns through `ctx.subprocess`, while this backend spawns through the SDK client (the subprocess README's documented exception for SDK-managed transports) and applies the seam's `scrubbedParentEnv()` itself.
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
index 74ae4b8180..643ec36134 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
@@ -12,8 +12,8 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 三个包，分层与既有 Python 栈完全一致，外加一个 seam 注册：
 
-- **`@deepseek-ai/dsh-sdk-protocol`**（`packages/sdk/sdk-protocol/`）—— 把线协议做成共享且具名。`JsonRpcLineTransport` 从 `dsh-jsonrpc` 原样移入（后者现在导入它），`types.ts` 为服务器所说的每个载荷命名：`InitializeParams/Result`、`SessionPromptParams/Result`、四个通知载荷，以及 `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` 索引。该包根显式导出这一完整接口，且不提供指向源模块的深层导入。服务器的 `notify()` 调用点以这些具名载荷标注类型，服务器漂移会先破坏编译而不是破坏客户端。一处行为变化：错误响应现在以携带线上 `code`/`data` 的 `JsonRpcResponseError` 拒绝（Python 客户端本就保留这些；旧传输只抛携带消息的裸 `Error`）。
-- **`@deepseek-ai/dsh-sdk-client`**（`packages/sdk/sdk-client/`）—— `python/sdk` 的 TypeScript 孪生：`HarnessClient`（spawn、分帧、通知扇出、有类型的错误表面、经共享 dispose（资源释放）阶梯关闭至完全停稳）之上是 `DeepSeekHarness`/`HarnessSession`（惰性启动、记忆化 `initialize`、`run()` 把一个 `session/prompt` 与其 `session.finished` 配对）。其包根消费方接口显式导出两层客户端、面向调用方的类型，以及协议包所拥有的 `JsonRpcResponseError`；源模块、规范化辅助函数和通知投递端都保留为内部实现。`TurnResult.events` 只包含根会话的类型化事件，而 `notifications` 则保留根会话及从 `subagent.started` 发现的后代各自的会话 id；基于 `subagent.started` 血缘边的会话树范围限定在客户端完成，镜像 `client.py`。与 Python 的刻意不对称：启动规格是显式 `command`/`args`（无捆绑运行时解析——那是尚无 TS 消费方的发行问题）；`env` 整体替换而非合并（凭据策略归调用方；subprocess seam 的 `scrubbedParentEnv` 一个 import 即得）；`TurnResult` 携带结构化 `reason`（Python 只暴露 `status`）；拆除走私有的 stdin-EOF → SIGTERM → SIGKILL 阶梯直到真正退出（客户端运行在任何 harness 上下文之外，无法搭乘 `ctx.subprocess`）。
+- **`@deepseek-ai/dsh-sdk-protocol`**（`packages/scaffold/protocol/`）—— 把线协议做成共享且具名。`JsonRpcLineTransport` 从 `dsh-jsonrpc` 原样移入（后者现在导入它），`types.ts` 为服务器所说的每个载荷命名：`InitializeParams/Result`、`SessionPromptParams/Result`、四个通知载荷，以及 `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` 索引。该包根显式导出这一完整接口，且不提供指向源模块的深层导入。服务器的 `notify()` 调用点以这些具名载荷标注类型，服务器漂移会先破坏编译而不是破坏客户端。一处行为变化：错误响应现在以携带线上 `code`/`data` 的 `JsonRpcResponseError` 拒绝（Python 客户端本就保留这些；旧传输只抛携带消息的裸 `Error`）。
+- **`@deepseek-ai/dsh-sdk-client`**（`packages/scaffold/client/`）—— `python/sdk` 的 TypeScript 孪生：`HarnessClient`（spawn、分帧、通知扇出、有类型的错误表面、经共享 dispose（资源释放）阶梯关闭至完全停稳）之上是 `DeepSeekHarness`/`HarnessSession`（惰性启动、记忆化 `initialize`、`run()` 把一个 `session/prompt` 与其 `session.finished` 配对）。其包根消费方接口显式导出两层客户端、面向调用方的类型，以及协议包所拥有的 `JsonRpcResponseError`；源模块、规范化辅助函数和通知投递端都保留为内部实现。`TurnResult.events` 只包含根会话的类型化事件，而 `notifications` 则保留根会话及从 `subagent.started` 发现的后代各自的会话 id；基于 `subagent.started` 血缘边的会话树范围限定在客户端完成，镜像 `client.py`。与 Python 的刻意不对称：启动规格是显式 `command`/`args`（无捆绑运行时解析——那是尚无 TS 消费方的发行问题）；`env` 整体替换而非合并（凭据策略归调用方；subprocess seam 的 `scrubbedParentEnv` 一个 import 即得）；`TurnResult` 携带结构化 `reason`（Python 只暴露 `status`）；拆除走私有的 stdin-EOF → SIGTERM → SIGKILL 阶梯直到真正退出（客户端运行在任何 harness 上下文之外，无法搭乘 `ctx.subprocess`）。
 - **`@deepseek-ai/dsh-subagent-dsh-sdk`**（`packages/subagent/subagent-dsh-sdk/`）—— 第二个进程外 `SubagentProvider`，采用与 `subagent-acp` 对等的结构：同样的全 false 能力与 `inheritsParentContext: false`，同样的握手后发布所有权事务，同样通过 `onError` sink 将结果归一为绝不拒绝，同样的父命名空间 run id。子答案从流式 `session.event` 读取——最后一条完整 `assistant/message`，否则累积的 `text-delta` 块，部分答案在取消时得以保留。停止原因由子进程的结构化 `TurnEndReason` 映射（`completed`/`max-tokens`/`aborted` 直通；其余一切、包括未运行任何轮次便已结束的子进程，都是 `error`）。其 `provider`/`model` 配置喂给子进程的 `initialize`；`env` 是部署传入子进程自有密钥与 `DSH_CORDIS_CONFIG` 的地方。
 - **subagent seam 新增 `out-of-process.ts`**：两个进程外后端共享的 provider 侧词汇——`NO_START_CAPABILITIES`、时限校验、子进程 cwd 解析（配置覆盖、否则发起委托的父会话工作区）、绝不拒绝的 `settleRunResult`、以及 `subprocessRunHandle` 发布。进程机制（spawn、环境清理、进程树清理）属于 `dsh-subprocess` seam；`subagent-acp` 经 `ctx.subprocess` spawn 子进程，本后端则经 SDK 客户端 spawn 子进程（subprocess README 记载的 SDK 托管传输例外）并自行应用该 seam 的 `scrubbedParentEnv()`。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index 7adc61691c..0fe388a3dc 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.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 .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
-2026-07-27-session-projection-and-command-log.md: 8226325d4cd4047c3a9c41eb9427082c59753dd5
-2026-07-27-session-projection-and-command-log.zh.md: b55704f28799008b5e2323d846696e4768fcd6d6
+2026-07-27-session-projection-and-command-log.md: 2fc463ab6e65998c19b0a0fce186c7eb17dacbf6
+2026-07-27-session-projection-and-command-log.zh.md: 89877d3aabcd074863f912b334c927268014e4d8
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
index 8226325d4c..2fc463ab6e 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
@@ -123,7 +123,7 @@ Two log-only (non-surface, model-invisible) events, mirroring the `tool/call`/`t
 'command/done': { commandId: string; kind: 'success' | 'error'; text?: string }
 ```
 
-The host command executor (`packages/ui/commands`) appends `command/run` before invoking the handler and `command/done` at settlement — direct standalone appends on the receiving agent's session, in the same shape as every other plugin-owned log-only event after the [synthetic-turn removal](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md): no turn wraps them (turns describe model-loop executions only), persistence drains them at ordinary checkpoints, and the commands package's own invariant companion enforces the run/done pairing. The payload is structured — `name` and, by default, `args` are the parser's own split (`parseCommand`'s name and rawInput), so a consumer (a projection unit folding its own command records, a rich command card) never re-parses a line. A definition sets `recordInput: false` when its authoritative domain event owns the payload; `command/run` then omits `args` rather than duplicating it. `text` is the handler's verbatim outcome — factual data of the same nature as `tool/result.content`, not presentation (how it is laid out remains client-computed at render time, satisfying the "presentation never enters the log" red line). Domains that want the model to know the outcome keep doing what they do today (plan's narration, goal's inject) — that is a domain decision, unchanged.
+The host command executor (`packages/interaction/commands`) appends `command/run` before invoking the handler and `command/done` at settlement — direct standalone appends on the receiving agent's session, in the same shape as every other plugin-owned log-only event after the [synthetic-turn removal](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md): no turn wraps them (turns describe model-loop executions only), persistence drains them at ordinary checkpoints, and the commands package's own invariant companion enforces the run/done pairing. The payload is structured — `name` and, by default, `args` are the parser's own split (`parseCommand`'s name and rawInput), so a consumer (a projection unit folding its own command records, a rich command card) never re-parses a line. A definition sets `recordInput: false` when its authoritative domain event owns the payload; `command/run` then omits `args` rather than duplicating it. `text` is the handler's verbatim outcome — factual data of the same nature as `tool/result.content`, not presentation (how it is laid out remains client-computed at render time, satisfying the "presentation never enters the log" red line). Domains that want the model to know the outcome keep doing what they do today (plan's narration, goal's inject) — that is a domain decision, unchanged.
 
 Because committed events broadcast on the mux stream, refresh persistence, multi-tab sync, and fork/resume recovery all come for free. The `command.execute` RPC degrades to admission — `{ matched, commandId? }`: whether the line resolved, and the minted pairing id when it did, so the issuing client can correlate its request with the flow node the lifecycle events produce. The one-shot notice channel (`runDetached` → `noticeFor`) is retired.
 
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index b55704f287..89877d3aab 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -123,7 +123,7 @@ type UseProjection = {
 'command/done': { commandId: string; kind: 'success' | 'error'; text?: string }
 ```
 
-host 侧命令执行器（`packages/ui/commands`）在调用处理器前追加 `command/run`，在结算时追加 `command/done`——在接收 agent 的会话上直接独立追加，与[合成轮次移除](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md)之后所有插件自有 log-only 事件同一形状：没有轮次包裹它们（轮次只描述模型循环执行），持久化在常规检查点排空它们，run/done 配对由 commands 包自己的 invariant 伴生插件把守。载荷是结构化的——`name` 以及默认携带的 `args` 来自解析器自己的切分（`parseCommand` 的 name 与 rawInput），因此消费方（折叠自己命令记录的投影单元、富命令卡片）永远无需重新解析行文本。当载荷由权威领域事件持有时，命令定义会设置 `recordInput: false`；此时 `command/run` 省略 `args`，而不是重复该载荷。`text` 是处理器的原样结果——与 `tool/result.content` 同一性质的事实数据，不是呈现（版式如何编排仍由客户端在渲染时计算，满足「呈现永不入日志」这条红线）。想让模型知道结果的领域继续做它们今天在做的事（plan 的旁白、goal 的注入）——那是领域自己的决定，保持不变。
+host 侧命令执行器（`packages/interaction/commands`）在调用处理器前追加 `command/run`，在结算时追加 `command/done`——在接收 agent 的会话上直接独立追加，与[合成轮次移除](../../implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md)之后所有插件自有 log-only 事件同一形状：没有轮次包裹它们（轮次只描述模型循环执行），持久化在常规检查点排空它们，run/done 配对由 commands 包自己的 invariant 伴生插件把守。载荷是结构化的——`name` 以及默认携带的 `args` 来自解析器自己的切分（`parseCommand` 的 name 与 rawInput），因此消费方（折叠自己命令记录的投影单元、富命令卡片）永远无需重新解析行文本。当载荷由权威领域事件持有时，命令定义会设置 `recordInput: false`；此时 `command/run` 省略 `args`，而不是重复该载荷。`text` 是处理器的原样结果——与 `tool/result.content` 同一性质的事实数据，不是呈现（版式如何编排仍由客户端在渲染时计算，满足「呈现永不入日志」这条红线）。想让模型知道结果的领域继续做它们今天在做的事（plan 的旁白、goal 的注入）——那是领域自己的决定，保持不变。
 
 由于已提交事件会在 mux 流上广播，刷新后仍在、多标签页同步、fork/恢复后可还原这三件事随之全部自动获得。`command.execute` RPC 退化为准入判定——`{ matched, commandId? }`：该行是否匹配命中，以及命中时新铸的配对 id，发起命令的客户端据此把自己的请求与生命周期事件产出的 flow 节点关联起来。一次性通知通道（`runDetached` → `noticeFor`）就此下线。
 
diff --git a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.i18n.yaml b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.i18n.yaml
index cdebeeac5c..71d6fa82b5 100644
--- a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.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 .agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
-2026-07-19-make-jsonrpc-directional.md: 910b4988aca34dec499b2e34cb2a42042c81b0cb
-2026-07-19-make-jsonrpc-directional.zh.md: 9810cf758faa078583955ba541e2b2fe9ad9c855
+2026-07-19-make-jsonrpc-directional.md: 945d58a0c989dac2beeb129bfd545fe5674c63cd
+2026-07-19-make-jsonrpc-directional.zh.md: 181aab8cd2f2473f0b2694df1dff072fd805e69d
diff --git a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
index 910b4988ac..945d58a0c9 100644
--- a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
+++ b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.md
@@ -20,11 +20,11 @@ Return the settled outcome directly from `session/prompt` as `{ status, reason }
 
 ## Implementation plan
 
-1. In `packages/ui/jsonrpc/src/server.ts`, replace `SessionPromptResult.accepted` with `status: 'ok' | 'error' | 'aborted'` and the captured `TurnEndReason`. `HarnessSdkServer.prompt()` will return `completed` as `ok`, `aborted` as `aborted`, and every other current or merge-extensible reason as `error`; reaching idle without a `turn/end` remains an invariant error. Remove only `session.finished`, leaving `session.event`, `subagent.started`, and `subagent.finished` unchanged.
-2. In `packages/sdk/sdk-protocol/src/transport.ts`, narrow the shared class to the directions with consumers — inbound requests/outbound responses (the server) and outbound requests/inbound responses plus inbound notifications (the TypeScript SDK client) — removing only server-originated `request()` use and client-originated notification dispatch, or split the class into a server-side and client-side transport. Request result, method-not-found, and handler-error responses retain their current behavior and remain ordered after notifications emitted by the awaited handler.
+1. In `packages/scaffold/server/src/server.ts`, replace `SessionPromptResult.accepted` with `status: 'ok' | 'error' | 'aborted'` and the captured `TurnEndReason`. `HarnessSdkServer.prompt()` will return `completed` as `ok`, `aborted` as `aborted`, and every other current or merge-extensible reason as `error`; reaching idle without a `turn/end` remains an invariant error. Remove only `session.finished`, leaving `session.event`, `subagent.started`, and `subagent.finished` unchanged.
+2. In `packages/scaffold/protocol/src/transport.ts`, narrow the shared class to the directions with consumers — inbound requests/outbound responses (the server) and outbound requests/inbound responses plus inbound notifications (the TypeScript SDK client) — removing only server-originated `request()` use and client-originated notification dispatch, or split the class into a server-side and client-side transport. Request result, method-not-found, and handler-error responses retain their current behavior and remain ordered after notifications emitted by the awaited handler.
 3. In `python/sdk/src/deepseek_harness/client.py`, `models.py`, and `__init__.py`, remove `IncomingRequest`, `_requests`, `notify()`, `next_request()`, `respond()`, and `respond_error()`. Add a public validated `SessionPromptResponse` carrying status and reason, return it from `session_prompt()`, and keep an explicit reader guard that ignores unexpected server-request frames instead of allowing them to match a response waiter.
 4. In `python/sdk/src/deepseek_harness/api.py`, build `TurnResult.status` and a new `TurnResult.reason` from `SessionPromptResponse`, then delete the `session.finished` branch and second completion loop. Keep the subscription open during the request and preserve `_request_raw()`'s final notification drain so the last `turn/end` event and any subagent notification written before the response are collected before `Session.run()` reconstructs the final assistant message.
-5. Replace the symmetric transport-pair cases in `packages/sdk/sdk-protocol/tests/transport.spec.ts` with per-direction coverage, and update `server.spec.ts`, `plugin-apply.spec.ts`, and `built-scope-carrier.e2e.ts` for direct outcomes, ordering, overlap, shutdown, and the narrowed fake; update the TypeScript SDK client (`packages/sdk/sdk-client`) and its suites for response-based settlement. Update `python/sdk/tests/test_client.py` for response-based settlement, unexpected-request-frame handling, callback and concurrency behavior, and the removed public helpers. Update the JSON-RPC and bilingual Python SDK READMEs, export JSDoc and declarations, `scripts/smoke-python-runtime.py`, and the Python single-executable snapshot.
+5. Replace the symmetric transport-pair cases in `packages/scaffold/protocol/tests/transport.spec.ts` with per-direction coverage, and update `server.spec.ts`, `plugin-apply.spec.ts`, and `built-scope-carrier.e2e.ts` for direct outcomes, ordering, overlap, shutdown, and the narrowed fake; update the TypeScript SDK client (`packages/scaffold/client`) and its suites for response-based settlement. Update `python/sdk/tests/test_client.py` for response-based settlement, unexpected-request-frame handling, callback and concurrency behavior, and the removed public helpers. Update the JSON-RPC and bilingual Python SDK READMEs, export JSDoc and declarations, `scripts/smoke-python-runtime.py`, and the Python single-executable snapshot.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md
index 9810cf758f..181aab8cd2 100644
--- a/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-19-make-jsonrpc-directional.zh.md
@@ -20,11 +20,11 @@ JSON-RPC 桥接层把两个端点都建模为对称的对等端，但实际协
 
 ## 实施计划
 
-1. 在 `packages/ui/jsonrpc/src/server.ts` 中，用 `status: 'ok' | 'error' | 'aborted'` 和捕获的 `TurnEndReason` 替换 `SessionPromptResult.accepted`。`HarnessSdkServer.prompt()` 把 `completed` 映射为 `ok`，把 `aborted` 映射为 `aborted`，把其他当前已有或可通过声明合并扩展的原因映射为 `error`；进入空闲状态却没有 `turn/end` 仍视为不变量错误。只删除 `session.finished`，保持 `session.event`、`subagent.started` 和 `subagent.finished` 不变。
-2. 在 `packages/sdk/sdk-protocol/src/transport.ts` 中，把共享类收窄到有消费者的方向——入站请求/出站响应（服务端）与出站请求/入站响应及入站通知（TypeScript SDK 客户端）——只删除服务端发起的 `request()` 用法与客户端发起的通知分发，或把该类拆分为服务端与客户端两个传输。请求结果、方法不存在与处理器错误响应保持原有行为，并继续排在被等待处理器发出的通知之后。
+1. 在 `packages/scaffold/server/src/server.ts` 中，用 `status: 'ok' | 'error' | 'aborted'` 和捕获的 `TurnEndReason` 替换 `SessionPromptResult.accepted`。`HarnessSdkServer.prompt()` 把 `completed` 映射为 `ok`，把 `aborted` 映射为 `aborted`，把其他当前已有或可通过声明合并扩展的原因映射为 `error`；进入空闲状态却没有 `turn/end` 仍视为不变量错误。只删除 `session.finished`，保持 `session.event`、`subagent.started` 和 `subagent.finished` 不变。
+2. 在 `packages/scaffold/protocol/src/transport.ts` 中，把共享类收窄到有消费者的方向——入站请求/出站响应（服务端）与出站请求/入站响应及入站通知（TypeScript SDK 客户端）——只删除服务端发起的 `request()` 用法与客户端发起的通知分发，或把该类拆分为服务端与客户端两个传输。请求结果、方法不存在与处理器错误响应保持原有行为，并继续排在被等待处理器发出的通知之后。
 3. 在 `python/sdk/src/deepseek_harness/client.py`、`models.py` 和 `__init__.py` 中，删除 `IncomingRequest`、`_requests`、`notify()`、`next_request()`、`respond()` 和 `respond_error()`。新增公开且经过校验的 `SessionPromptResponse` 来携带状态与原因，由 `session_prompt()` 返回该对象，并保留明确的读取保护：忽略意外的服务端请求帧，避免它们命中响应等待器。
 4. 在 `python/sdk/src/deepseek_harness/api.py` 中，根据 `SessionPromptResponse` 构造 `TurnResult.status` 和新增的 `TurnResult.reason`，再删除 `session.finished` 分支与第二个完成循环。请求期间保持订阅打开，并保留 `_request_raw()` 最后的通知排空步骤，确保写在响应前的最后一条 `turn/end` 事件与任何 subagent 通知，都会在 `Session.run()` 重建最终助手消息之前被收集。
-5. 用按方向的覆盖替换 `packages/sdk/sdk-protocol/tests/transport.spec.ts` 中的对称传输对用例，并更新 `server.spec.ts`、`plugin-apply.spec.ts` 和 `built-scope-carrier.e2e.ts`，覆盖直接结果、顺序、重叠、关闭和收窄后的伪实现；同步更新 TypeScript SDK 客户端（`packages/sdk/sdk-client`）及其套件以采用基于响应的结束流程。更新 `python/sdk/tests/test_client.py`，覆盖基于响应的结束流程、意外请求帧处理、回调与并发行为，以及已删除的公开辅助方法。同步更新 JSON-RPC README、双语 Python SDK README、导出 JSDoc 与声明、`scripts/smoke-python-runtime.py` 和 Python 单可执行文件快照。
+5. 用按方向的覆盖替换 `packages/scaffold/protocol/tests/transport.spec.ts` 中的对称传输对用例，并更新 `server.spec.ts`、`plugin-apply.spec.ts` 和 `built-scope-carrier.e2e.ts`，覆盖直接结果、顺序、重叠、关闭和收窄后的伪实现；同步更新 TypeScript SDK 客户端（`packages/scaffold/client`）及其套件以采用基于响应的结束流程。更新 `python/sdk/tests/test_client.py`，覆盖基于响应的结束流程、意外请求帧处理、回调与并发行为，以及已删除的公开辅助方法。同步更新 JSON-RPC README、双语 Python SDK README、导出 JSDoc 与声明、`scripts/smoke-python-runtime.py` 和 Python 单可执行文件快照。
 
 ## 备选方案
 
diff --git a/AGENTS.md b/AGENTS.md
index 7727539bd9..7c9b795ddc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,7 +37,9 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   settings/    user-settings seam + file-backed provider
   credentials/ credential-reference seam + env-over-.env provider
   acp/         automation-only Agent Client Protocol server
-  ui/          JSON-RPC bridge; boot, approval, interaction plugins
+  interaction/ approval/interaction seams, permission, commands, ask-user tool
+  boot/        shared app-bin boot glue
+  scaffold/    project tooling: helper, launcher, initializer, SDK wire protocol + ends
   examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load
   support/     dev/test infrastructure
   util/        zero-dependency utilities
diff --git a/apps/cli/tsconfig.json b/apps/cli/tsconfig.json
index 36c4bad6dd..d830e8fba6 100644
--- a/apps/cli/tsconfig.json
+++ b/apps/cli/tsconfig.json
@@ -18,7 +18,7 @@
       "path": "../../vendor/include"
     },
     {
-      "path": "../../packages/ui/app-boot"
+      "path": "../../packages/boot/app-boot"
     },
     {
       "path": "../../packages/bundle/base"
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 4d10310333..76491a37fe 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: c14d68c47f6ed0786e8fc0b0650dbc67678250fb
-architecture.zh.md: df484762d29e170a5b1ba64f0637c5170c2c5ef4
+architecture.md: cee159452fc536c98a006cfa3ea92e9d21a1e77b
+architecture.zh.md: cf10e60a5d5e4fe3f39d72bef3d48fe7c2f3c105
diff --git a/docs/architecture.md b/docs/architecture.md
index c14d68c47f..cee159452f 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -163,7 +163,7 @@ Exceptions combine LLM interface/consumer, filesystem policy, web registries, an
 
 ### Bundles And Apps
 
-`dsh-agent-spine-demo` bundles a spine and optional goals. App packages own CLI, ACP automation, and JSON-RPC front doors ([README](../packages/examples/agent-spine-demo/README.md), [acp/](../packages/acp/README.md), [ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK defaults when config is absent ([Python SDK](../python/README.md)). Thin deployments use swappable backends and optional tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
+`dsh-agent-spine-demo` bundles a spine and optional goals. App packages own CLI, ACP automation, and JSON-RPC front doors ([README](../packages/examples/agent-spine-demo/README.md), [acp/](../packages/acp/README.md), [interaction/](../packages/interaction/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK defaults when config is absent ([Python SDK](../python/README.md)). Thin deployments use swappable backends and optional tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
 
 ### Where New Behavior Goes
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index df484762d2..cf10e60a5d 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -163,7 +163,7 @@ idle inject:
 
 ### 组合包与应用
 
-`dsh-agent-spine-demo` 组合一套主干和可选目标。应用包负责 CLI（命令行界面）、ACP 自动化入口和 JSON-RPC 入口（[README](../packages/examples/agent-spine-demo/README.md)、[acp/](../packages/acp/README.md)、[ui/](../packages/ui/README.md)）。`dsh-jsonrpc-agent` 启动外部 `cordis.yml`；Python SDK 在配置缺失时提供默认项（[Python SDK](../python/README.md)）。轻量部署使用可替换后端和可选工具（[examples/](../examples/AGENTS.md)、[可运行接线](cookbook/extension-cookbook.md#runnable-wirings)、[图谱](graph-atlas.md)）。
+`dsh-agent-spine-demo` 组合一套主干和可选目标。应用包负责 CLI（命令行界面）、ACP 自动化入口和 JSON-RPC 入口（[README](../packages/examples/agent-spine-demo/README.md)、[acp/](../packages/acp/README.md)、[interaction/](../packages/interaction/README.md)）。`dsh-jsonrpc-agent` 启动外部 `cordis.yml`；Python SDK 在配置缺失时提供默认项（[Python SDK](../python/README.md)）。轻量部署使用可替换后端和可选工具（[examples/](../examples/AGENTS.md)、[可运行接线](cookbook/extension-cookbook.md#runnable-wirings)、[图谱](graph-atlas.md)）。
 
 ### 新行为的归属位置
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 60a19999f3..c191f6a659 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -389,10 +389,10 @@ flowchart LR
 | `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
 | `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
-| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
-| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | - | [`tool-ask-user`](../packages/ui/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
+| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
+| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/interaction/user-interaction) | - | [`tool-ask-user`](../packages/interaction/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
-| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
+| `ctx.commands` | `core` | [`commands`](../packages/interaction/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
 | `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo), [`session-title`](../packages/session/session-title), [`host-apiproxy`](../packages/host/apiproxy) | - | Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values. |
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
@@ -407,7 +407,7 @@ flowchart LR
 | `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox), [`pty-local`](../packages/pty/pty-local) | - | Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement. |
 | `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/bash/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`pty-local`](../packages/pty/pty-local) | - | The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots. |
 | `ctx.approval` | `seam` | `approval` | [`acp`](../packages/acp/acp) | [`tools`](../packages/core/tools), [`tool-bash`](../packages/bash/tool-bash) | - | One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`. |
-| `ctx.permission` | `core` | [`permission`](../packages/ui/permission) | - | - | - | User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events. |
+| `ctx.permission` | `core` | [`permission`](../packages/interaction/permission) | - | - | - | User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events. |
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
diff --git a/docs/core-data-structures/approval.i18n.yaml b/docs/core-data-structures/approval.i18n.yaml
index 0679cd47bd..975f631805 100644
--- a/docs/core-data-structures/approval.i18n.yaml
+++ b/docs/core-data-structures/approval.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 docs/core-data-structures/approval.md
-approval.md: f1889b25e2bbbcb157b0bced070b1f157a867504
-approval.zh.md: 48222991312f9ae97c9249f1232b261d2393d282
+approval.md: 8f17f98101950e6413d67fb4cce6befc5aede069
+approval.zh.md: c19285572b667512427b71d4af214acbc2baf334
diff --git a/docs/core-data-structures/approval.md b/docs/core-data-structures/approval.md
index f1889b25e2..8f17f98101 100644
--- a/docs/core-data-structures/approval.md
+++ b/docs/core-data-structures/approval.md
@@ -2,9 +2,9 @@
 
 English | [中文](approval.zh.md)
 
-The user-approval seam of [dsh-user-approval](../../packages/ui/user-approval) answers one question: may this specific action proceed? It owns the shared request/outcome vocabulary, the `ctx.approval` dispatch service, the `approval/request` answerer waterfall, the log-only audit pair, and the per-session `ask`/`never` policy. UI channels may provide human answerers; the [ACP automation bridge](../../packages/acp/acp) provides one-shot machine decisions for its own agents. Callers such as [dsh-tools](../../packages/core/tools) and [dsh-tool-bash](../../packages/bash/tool-bash) consume the closed outcome and fail closed unless it is `allowed-once`.
+The user-approval seam of [dsh-user-approval](../../packages/interaction/user-approval) answers one question: may this specific action proceed? It owns the shared request/outcome vocabulary, the `ctx.approval` dispatch service, the `approval/request` answerer waterfall, the log-only audit pair, and the per-session `ask`/`never` policy. UI channels may provide human answerers; the [ACP automation bridge](../../packages/acp/acp) provides one-shot machine decisions for its own agents. Callers such as [dsh-tools](../../packages/core/tools) and [dsh-tool-bash](../../packages/bash/tool-bash) consume the closed outcome and fail closed unless it is `allowed-once`.
 
-Source: [`packages/ui/user-approval/src/index.ts`](../../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts`](../../packages/interaction/user-approval/src/index.ts)
 
 ## Identity and outcome
 
diff --git a/docs/core-data-structures/approval.zh.md b/docs/core-data-structures/approval.zh.md
index 4822299131..c19285572b 100644
--- a/docs/core-data-structures/approval.zh.md
+++ b/docs/core-data-structures/approval.zh.md
@@ -2,9 +2,9 @@
 
 [English](approval.md) | 中文
 
-[dsh-user-approval](../../packages/ui/user-approval) 的用户审批 seam 回答一个问题：这个具体操作是否可以继续？它拥有共享的请求/结果词汇、`ctx.approval` 分发服务、`approval/request` 应答者 waterfall（瀑布式事件）、仅记录日志的审计事件对，以及按会话的 `ask`/`never` 策略。UI 通道可以提供人类应答者；[ACP（Agent Client Protocol）自动化桥接层](../../packages/acp/acp)为其拥有的 agent（智能体）提供一次性机器决策。调用方如 [dsh-tools](../../packages/core/tools) 和 [dsh-tool-bash](../../packages/bash/tool-bash) 消费闭合的结果，除非结果为 `allowed-once`，否则一律拒绝。
+[dsh-user-approval](../../packages/interaction/user-approval) 的用户审批 seam 回答一个问题：这个具体操作是否可以继续？它拥有共享的请求/结果词汇、`ctx.approval` 分发服务、`approval/request` 应答者 waterfall（瀑布式事件）、仅记录日志的审计事件对，以及按会话的 `ask`/`never` 策略。UI 通道可以提供人类应答者；[ACP（Agent Client Protocol）自动化桥接层](../../packages/acp/acp)为其拥有的 agent（智能体）提供一次性机器决策。调用方如 [dsh-tools](../../packages/core/tools) 和 [dsh-tool-bash](../../packages/bash/tool-bash) 消费闭合的结果，除非结果为 `allowed-once`，否则一律拒绝。
 
-源码：[`packages/ui/user-approval/src/index.ts`](../../packages/ui/user-approval/src/index.ts)
+源码：[`packages/interaction/user-approval/src/index.ts`](../../packages/interaction/user-approval/src/index.ts)
 
 ## 标识与结果
 
diff --git a/docs/core-data-structures/commands.i18n.yaml b/docs/core-data-structures/commands.i18n.yaml
index 532151ef70..18df873acc 100644
--- a/docs/core-data-structures/commands.i18n.yaml
+++ b/docs/core-data-structures/commands.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 docs/core-data-structures/commands.md
-commands.md: 1390f736ff582a997ee710cfd27fce4e7db3461f
-commands.zh.md: 53aec9bd138773df7fceb45e5d6c30b7205dd0d9
+commands.md: 83ce9c2498df58110d9a9c2e7d5163a9df813e1c
+commands.zh.md: c486f480177c7ff8b35cc846beafac009cea42bb
diff --git a/docs/core-data-structures/commands.md b/docs/core-data-structures/commands.md
index 1390f736ff..83ce9c2498 100644
--- a/docs/core-data-structures/commands.md
+++ b/docs/core-data-structures/commands.md
@@ -2,9 +2,9 @@
 
 English | [中文](commands.zh.md)
 
-The human-command seam of [`dsh-commands`](../../packages/ui/commands). Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The [command Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) owns dispatch and lifecycle rationale; the [package README](../../packages/ui/commands/README.md) owns composition and limitations.
+The human-command seam of [`dsh-commands`](../../packages/interaction/commands). Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The [command Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) owns dispatch and lifecycle rationale; the [package README](../../packages/interaction/commands/README.md) owns composition and limitations.
 
-Source: [`packages/ui/commands/src/index.ts`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
 
 ## Input metadata
 
diff --git a/docs/core-data-structures/commands.zh.md b/docs/core-data-structures/commands.zh.md
index 53aec9bd13..c486f48017 100644
--- a/docs/core-data-structures/commands.zh.md
+++ b/docs/core-data-structures/commands.zh.md
@@ -2,9 +2,9 @@
 
 [English](commands.md) | 中文
 
-[`dsh-commands`](../../packages/ui/commands) 的用户命令 seam。交互式适配器用它发现插件拥有的命令，并针对确切的 agent（智能体）直接执行这些命令，而不创建模型消息。[命令 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) 负责分发与生命周期的决策依据；[包 README](../../packages/ui/commands/README.md) 负责组合方式与限制。
+[`dsh-commands`](../../packages/interaction/commands) 的用户命令 seam。交互式适配器用它发现插件拥有的命令，并针对确切的 agent（智能体）直接执行这些命令，而不创建模型消息。[命令 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) 负责分发与生命周期的决策依据；[包 README](../../packages/interaction/commands/README.md) 负责组合方式与限制。
 
-来源：[`packages/ui/commands/src/index.ts`](../../packages/ui/commands/src/index.ts)
+来源：[`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
 
 ## 输入元数据
 
diff --git a/docs/core-data-structures/user-interaction.i18n.yaml b/docs/core-data-structures/user-interaction.i18n.yaml
index 5480052231..3768cfcf7b 100644
--- a/docs/core-data-structures/user-interaction.i18n.yaml
+++ b/docs/core-data-structures/user-interaction.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 docs/core-data-structures/user-interaction.md
-user-interaction.md: 73727cbb754f10633d3213f67f7c3c9fdb215500
-user-interaction.zh.md: b6e95af4026e58c63c713d87ee9a86b3712b311f
+user-interaction.md: ec22eb28e9554d6454bf2670f73f2e9b199df014
+user-interaction.zh.md: 814f8911e41aecf568f627f76f8239bac4ea719b
diff --git a/docs/core-data-structures/user-interaction.md b/docs/core-data-structures/user-interaction.md
index 73727cbb75..ec22eb28e9 100644
--- a/docs/core-data-structures/user-interaction.md
+++ b/docs/core-data-structures/user-interaction.md
@@ -2,9 +2,9 @@
 
 English | [中文](user-interaction.zh.md)
 
-The user-interaction seam of [dsh-user-interaction](../../packages/ui/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`; the host runtime relays requests to its connected client.
+The user-interaction seam of [dsh-user-interaction](../../packages/interaction/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`; the host runtime relays requests to its connected client.
 
-Source: [`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-interaction/src/index.ts)
+Source: [`packages/interaction/user-interaction/src/index.ts`](../../packages/interaction/user-interaction/src/index.ts)
 
 ## Question options
 
diff --git a/docs/core-data-structures/user-interaction.zh.md b/docs/core-data-structures/user-interaction.zh.md
index b6e95af402..814f8911e4 100644
--- a/docs/core-data-structures/user-interaction.zh.md
+++ b/docs/core-data-structures/user-interaction.zh.md
@@ -2,9 +2,9 @@
 
 [English](user-interaction.md) | 中文
 
-[dsh-user-interaction](../../packages/ui/user-interaction) 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。UI surface 提供活跃的 `UserInteractionProvider`；host 运行时把请求转发给它连接的客户端。
+[dsh-user-interaction](../../packages/interaction/user-interaction) 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。UI surface 提供活跃的 `UserInteractionProvider`；host 运行时把请求转发给它连接的客户端。
 
-源码：[`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-interaction/src/index.ts)
+源码：[`packages/interaction/user-interaction/src/index.ts`](../../packages/interaction/user-interaction/src/index.ts)
 
 ## 问题选项
 
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
index 90970c8c57..0b7cdfdc76 100644
--- a/docs/testing.i18n.yaml
+++ b/docs/testing.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 docs/testing.md
-testing.md: fecf02fe887aac5c92c739523f10a0562eba6242
-testing.zh.md: a34f56fac72baa9916d5f96e83048ad54cf23d4a
+testing.md: 296dd769118cc5498ddb1bb9c41e2c060b2a5bce
+testing.zh.md: e9182495fbdbb1458c9ff5b30a9591f8b70f27c5
diff --git a/docs/testing.md b/docs/testing.md
index fecf02fe88..296dd76911 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -32,7 +32,7 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword
 
 - Product-visible plugins require a non-unit REAL-composition test. Hand-built `ctx.plugin(...)` suites are insufficient: boot test-only `cordis.yml` through Loader and app/process, mock only external/nondeterministic boundaries, and assert model-visible request/log, durable state, or user-visible output. Keep opt-ins out of shipped defaults.
 - A guard only guards if the regression actually fails it. For a plugin without `inject` (bundle/composition plugins), a Loader smoke stays green under a broken export shape — add an explicit `expect('default' in mod).toBe(false)` plus an `unwrapExports` round-trip assertion, and prove it: introduce the regression, watch red, revert.
-- "Real entry path" means the published artifact: a package `bin` runs built `lib/bin.js` under plain `node`, exposing failures tsx masks (settle races, module resolution, swallowed load failures). The same applies to non-index runtime entries (the worker-thread sibling `lib/worker.cjs`) and singleton modules shared across bundles (`packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts`). Keep the built-artifact smokes green (`packages/ui/*/tests/built-bin.e2e.ts`, `packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`), and assert a genuinely-missing config exits non-zero.
+- "Real entry path" means the published artifact: a package `bin` runs built `lib/bin.js` under plain `node`, exposing failures tsx masks (settle races, module resolution, swallowed load failures). The same applies to non-index runtime entries (the worker-thread sibling `lib/worker.cjs`) and singleton modules shared across bundles (`packages/scaffold/server/tests/built-scope-carrier.e2e.ts`). Keep the built-artifact smokes green (`packages/examples/*/tests/built-bin.e2e.ts`, `packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`), and assert a genuinely-missing config exits non-zero.
 
 ## Test resolution: source plane only
 
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
index a34f56fac7..e9182495fb 100644
--- a/docs/testing.zh.md
+++ b/docs/testing.zh.md
@@ -32,7 +32,7 @@ e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身
 
 - 产品可见的插件必须有一个非单元的真实组合测试。手动构建的 `ctx.plugin(...)` 套件不够：通过 Loader 和 app/process 启动仅用于测试的 `cordis.yml`，只 mock 外部/不确定边界，断言模型可见的请求/日志、持久状态或用户可见输出。不要把 opt-in 选项混入交付默认值。
 - 一个守卫只有在回归真的能让它失败时才有效。对于没有 `inject` 的插件（bundle/组合插件），Loader 冒烟测试在导出形状损坏时仍然绿着——需要添加显式的 `expect('default' in mod).toBe(false)` 加 `unwrapExports` 往返断言，并证明它有效：引入回归、观察变红、回退。
-- 「真实入口路径」指已发布的产物：包的 `bin` 所运行的是构建后的 `lib/bin.js`，并由普通 `node` 执行，从而暴露 tsx 会掩盖的失败（等待稳定时的竞态、模块解析、被吞掉的加载失败）。同样的规则适用于非 index 运行时入口（worker-thread 的同级文件 `lib/worker.cjs`），也适用于多个 bundle 共享的单例模块（`packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts`）。保持构建产物冒烟测试绿色（`packages/ui/*/tests/built-bin.e2e.ts`、`packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`），并断言真正缺失的配置以非零状态退出。
+- 「真实入口路径」指已发布的产物：包的 `bin` 所运行的是构建后的 `lib/bin.js`，并由普通 `node` 执行，从而暴露 tsx 会掩盖的失败（等待稳定时的竞态、模块解析、被吞掉的加载失败）。同样的规则适用于非 index 运行时入口（worker-thread 的同级文件 `lib/worker.cjs`），也适用于多个 bundle 共享的单例模块（`packages/scaffold/server/tests/built-scope-carrier.e2e.ts`）。保持构建产物冒烟测试绿色（`packages/examples/*/tests/built-bin.e2e.ts`、`packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`），并断言真正缺失的配置以非零状态退出。
 
 ## 测试解析：仅限源码
 
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index adb73f104d..0cb985d07d 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -107,7 +107,7 @@ Ask the user a concise question when you need confirmation, a choice, or missing
 }
 ```
 
-Source: [`packages/ui/tool-ask-user/src/index.ts`](../packages/ui/tool-ask-user/src/index.ts)
+Source: [`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts)
 
 ask_user_question pauses the tool call until the active UI provider returns a human answer.
 
diff --git a/knip.json b/knip.json
index 0e82064200..63db33e51c 100644
--- a/knip.json
+++ b/knip.json
@@ -513,7 +513,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/ui/jsonrpc": {
+    "packages/scaffold/server": {
       "entry": [
         "tests/**/*.spec.ts",
         "tests/**/*.e2e.ts"
@@ -523,7 +523,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/ui/commands": {
+    "packages/interaction/commands": {
       "entry": [
         "tests/**/*.spec.ts"
       ],
@@ -537,7 +537,7 @@
         "src/**/*.ts"
       ]
     },
-    "packages/sdk/create-sdk": {
+    "packages/scaffold/create-sdk": {
       "entry": [
         "src/bin.ts",
         "tests/**/*.spec.ts",
@@ -549,7 +549,7 @@
         "tests/**/*.ts"
       ]
     },
-    "packages/sdk/scripts": {
+    "packages/scaffold/scripts": {
       "entry": [
         "src/bin.ts",
         "tests/**/*.spec.ts",
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 44dd906b76..68da8ae611 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 9f8b3f936af6392239218d5389c91c87d0f7d1f9
-README.zh.md: 2f4e86cb541a8a34762b36cac57f456de96cac5d
+README.md: 198caca8c8b8231ece4d7160c809ba7b881e775c
+README.zh.md: bf2bf437796d904d135b610ff2c7a2d4d21b0298
diff --git a/packages/README.md b/packages/README.md
index 9f8b3f936a..198caca8c8 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -45,9 +45,10 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`credentials/`](credentials/README.md) | Credential-reference seam + env-over-`.env` provider | Product — stable surface |
 | [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable surface |
 | [`workspace/`](workspace/README.md) | Workspace entity | Product — stable surface |
-| [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
+| [`scaffold/`](scaffold/README.md) | Create/launch/drive project tooling: helper, launcher, initializer, wire protocol with both ends, launcher telemetry | Product — stable surface |
 | [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server | Product — stable surface |
-| [`ui/`](ui/README.md) | JSON-RPC integration, approval/interaction seams, ask-user tool | Product — stable surface |
+| [`interaction/`](interaction/README.md) | Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool | Product — stable surface |
+| [`boot/`](boot/README.md) | Shared app-bin boot glue | Product — stable surface |
 | [`host/`](host/README.md) | Web-GUI host half: API gateway + HTTP route server | Product — stable surface |
 | [`client/`](client/README.md) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins | Product — stable surface |
 | [`experimental/`](experimental/README.md) | Prototypes and internal plugins | Unreleased |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 2f4e86cb54..bf2bf43779 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -45,9 +45,10 @@
 | [`credentials/`](credentials/README.md) | 凭据引用 seam + 环境叠加 `.env` provider | 产品：稳定表面 |
 | [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 |
 | [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定表面 |
-| [`sdk/`](sdk/README.md) | 项目 SDK 工具 | 产品：稳定表面 |
+| [`scaffold/`](scaffold/README.md) | 创建／启动／驱动项目的工具：helper、启动器、初始化器、带两端的通信协议、启动器 telemetry | 产品：稳定表面 |
 | [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定表面 |
-| [`ui/`](ui/README.md) | JSON-RPC 集成、批准／交互 seam、用户问答工具 | 产品：稳定表面 |
+| [`interaction/`](interaction/README.md) | 人机协作平面：批准／交互 seam、权限预设、命令、用户问答工具 | 产品：稳定表面 |
+| [`boot/`](boot/README.md) | 共享的 app bin 启动粘合层 | 产品：稳定表面 |
 | [`host/`](host/README.md) | web GUI 宿主半侧：API 网关 + HTTP 路由服务器 | 产品：稳定表面 |
 | [`client/`](client/README.md) | web GUI 浏览器半侧：shell、协议层、对象服务、slot、`ui-*` 插件 | 产品：稳定表面 |
 | [`experimental/`](experimental/README.md) | 原型和内部插件 | 未发布 |
diff --git a/packages/acp/acp/tsconfig.json b/packages/acp/acp/tsconfig.json
index 3109e0eea8..177b3cb3cd 100644
--- a/packages/acp/acp/tsconfig.json
+++ b/packages/acp/acp/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../core/agent"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/bash/tool-bash/tsconfig.json b/packages/bash/tool-bash/tsconfig.json
index b122ed58ca..93cbe93786 100644
--- a/packages/bash/tool-bash/tsconfig.json
+++ b/packages/bash/tool-bash/tsconfig.json
@@ -39,7 +39,7 @@
       "path": "../../bash/bash-env"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     },
     {
       "path": "../../sandbox/sandbox"
diff --git a/packages/sdk/README.i18n.yaml b/packages/boot/README.i18n.yaml
similarity index 57%
rename from packages/sdk/README.i18n.yaml
rename to packages/boot/README.i18n.yaml
index 738a0610ab..151e5e5c08 100644
--- a/packages/sdk/README.i18n.yaml
+++ b/packages/boot/README.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 packages/sdk/README.md
-README.md: 3f99d6d45ddc64ac068457b0d03e533d21451a5f
-README.zh.md: 003383c5f6238b37893927813959d52d96350c3e
+#   pnpm run verify-translation-pairing --write packages/boot/README.md
+README.md: 7727f4fbab62a930051fd3b92d04513ac9f5d218
+README.zh.md: aa9a56619ee55c3be8feb58881f77c460861b1ac
diff --git a/packages/boot/README.md b/packages/boot/README.md
new file mode 100644
index 0000000000..7727f4fbab
--- /dev/null
+++ b/packages/boot/README.md
@@ -0,0 +1,9 @@
+# boot/ — shared app-bin boot glue
+
+English | [中文](README.zh.md)
+
+The channel-neutral boot library the app bins share. A role-complete single-package group: it belongs to no channel and no assembly — `apps/cli`, the [`scaffold/`](../scaffold/README.md) launcher, and the [`examples/`](../examples/README.md) demo bins all consume it.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `app-boot/` | Shared boot glue for the app bins: `.env` loading, fail-loud Loader guards, snapshot-aware config resolution, the settle-the-tree boot sequence | (library for the bins) |
diff --git a/packages/boot/README.zh.md b/packages/boot/README.zh.md
new file mode 100644
index 0000000000..aa9a56619e
--- /dev/null
+++ b/packages/boot/README.zh.md
@@ -0,0 +1,9 @@
+# boot/：共享的 app bin 启动粘合层
+
+[English](README.md) | 中文
+
+各 app bin 共享、与通道无关的启动库。一个角色完备的单包组：它不归属任何通道也不归属任何组装——`apps/cli`、[`scaffold/`](../scaffold/README.md) 启动器和 [`examples/`](../examples/README.md) 各演示 bin 都消费它。
+
+| 包 | 职责 | ctx 键 |
+|---|---|---|
+| `app-boot/` | app bin 的共享启动粘合层：加载 `.env`、会明确报错的 Loader 保护机制、感知快照的配置解析，以及等待整棵树停稳的启动序列 | （供各 bin 使用的库） |
diff --git a/packages/ui/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
similarity index 81%
rename from packages/ui/app-boot/README.i18n.yaml
rename to packages/boot/app-boot/README.i18n.yaml
index 24f04a21c1..3ae6f5427c 100644
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/README.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 packages/ui/app-boot/README.md
+#   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
 README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
 README.zh.md: 88d1c4ad0ced2f5a6440a1b64e34e738a842f938
diff --git a/packages/ui/app-boot/README.md b/packages/boot/app-boot/README.md
similarity index 100%
rename from packages/ui/app-boot/README.md
rename to packages/boot/app-boot/README.md
diff --git a/packages/ui/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
similarity index 100%
rename from packages/ui/app-boot/README.zh.md
rename to packages/boot/app-boot/README.zh.md
diff --git a/packages/ui/app-boot/package.json b/packages/boot/app-boot/package.json
similarity index 100%
rename from packages/ui/app-boot/package.json
rename to packages/boot/app-boot/package.json
diff --git a/packages/ui/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts
similarity index 100%
rename from packages/ui/app-boot/src/index.ts
rename to packages/boot/app-boot/src/index.ts
diff --git a/packages/ui/app-boot/src/invariant.ts b/packages/boot/app-boot/src/invariant.ts
similarity index 100%
rename from packages/ui/app-boot/src/invariant.ts
rename to packages/boot/app-boot/src/invariant.ts
diff --git a/packages/ui/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts
similarity index 100%
rename from packages/ui/app-boot/src/profile.ts
rename to packages/boot/app-boot/src/profile.ts
diff --git a/packages/ui/app-boot/tests/app-boot.spec.ts b/packages/boot/app-boot/tests/app-boot.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/app-boot.spec.ts
rename to packages/boot/app-boot/tests/app-boot.spec.ts
diff --git a/packages/ui/app-boot/tests/config-dump.spec.ts b/packages/boot/app-boot/tests/config-dump.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/config-dump.spec.ts
rename to packages/boot/app-boot/tests/config-dump.spec.ts
diff --git a/packages/ui/app-boot/tests/config-reload.spec.ts b/packages/boot/app-boot/tests/config-reload.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/config-reload.spec.ts
rename to packages/boot/app-boot/tests/config-reload.spec.ts
diff --git a/packages/ui/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/hmr-config.spec.ts
rename to packages/boot/app-boot/tests/hmr-config.spec.ts
diff --git a/packages/ui/app-boot/tests/profile.spec.ts b/packages/boot/app-boot/tests/profile.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/profile.spec.ts
rename to packages/boot/app-boot/tests/profile.spec.ts
diff --git a/packages/ui/app-boot/tests/repository-cache.spec.ts b/packages/boot/app-boot/tests/repository-cache.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/repository-cache.spec.ts
rename to packages/boot/app-boot/tests/repository-cache.spec.ts
diff --git a/packages/ui/app-boot/tests/user-patches.spec.ts b/packages/boot/app-boot/tests/user-patches.spec.ts
similarity index 100%
rename from packages/ui/app-boot/tests/user-patches.spec.ts
rename to packages/boot/app-boot/tests/user-patches.spec.ts
diff --git a/packages/ui/app-boot/tsconfig.json b/packages/boot/app-boot/tsconfig.json
similarity index 100%
rename from packages/ui/app-boot/tsconfig.json
rename to packages/boot/app-boot/tsconfig.json
diff --git a/packages/ui/app-boot/tsdown.config.ts b/packages/boot/app-boot/tsdown.config.ts
similarity index 100%
rename from packages/ui/app-boot/tsdown.config.ts
rename to packages/boot/app-boot/tsdown.config.ts
diff --git a/packages/bundle/README.i18n.yaml b/packages/bundle/README.i18n.yaml
index 27e50409cd..5199e0939e 100644
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/README.i18n.yaml
@@ -1,6 +1,12 @@
 # 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:
+<<<<<<<< HEAD:packages/bundle/README.i18n.yaml
 #   pnpm run verify-translation-pairing --write packages/bundle/README.md
 README.md: 4759170435a80e85731446cef21d24fff2abed66
 README.zh.md: 1ef610a1b7b3c591c9a900e04f2d8096b0b086b9
+========
+#   pnpm run verify-translation-pairing --write packages/interaction/tui/README.md
+README.md: c81cac891403e5294c4456ce4d4048ecd74666ce
+README.zh.md: 01055619f4df460284564f0a1816de366d809e01
+>>>>>>>> a58746f4cc (refactor(packages): dissolve ui/ and rename sdk/ to scaffold/):packages/interaction/tui/README.i18n.yaml
diff --git a/packages/client/connection/tsconfig.json b/packages/client/connection/tsconfig.json
index 6ff7fbfb25..58c04d18bd 100644
--- a/packages/client/connection/tsconfig.json
+++ b/packages/client/connection/tsconfig.json
@@ -16,7 +16,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../../util/brand"
@@ -28,10 +28,10 @@
       "path": "../../host/webserver"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     },
     {
-      "path": "../../ui/user-interaction"
+      "path": "../../interaction/user-interaction"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index 71cfb229a9..867b2f588c 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../host/apiproxy"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../../compact/compact"
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
index 0505786841..89d0067caf 100644
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -51,7 +51,7 @@
       "path": "../../support/invariants"
     },
     {
-      "path": "../../ui/permission"
+      "path": "../../interaction/permission"
     }
   ],
   "exclude": [
diff --git a/packages/client/ui-permission/tsconfig.json b/packages/client/ui-permission/tsconfig.json
index 32f84d6a2d..bfc71e2e3c 100644
--- a/packages/client/ui-permission/tsconfig.json
+++ b/packages/client/ui-permission/tsconfig.json
@@ -39,7 +39,7 @@
       "path": "../web-react"
     },
     {
-      "path": "../../ui/permission"
+      "path": "../../interaction/permission"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/client/ui-question/tsconfig.json b/packages/client/ui-question/tsconfig.json
index 6b5b0acc3a..1b920ce207 100644
--- a/packages/client/ui-question/tsconfig.json
+++ b/packages/client/ui-question/tsconfig.json
@@ -30,7 +30,7 @@
       "path": "../ui-slots"
     },
     {
-      "path": "../../ui/tool-ask-user"
+      "path": "../../interaction/tool-ask-user"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/compact/command-compact/tsconfig.json b/packages/compact/command-compact/tsconfig.json
index f99f2b98b4..c1040bf92a 100644
--- a/packages/compact/command-compact/tsconfig.json
+++ b/packages/compact/command-compact/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../compact"
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index 6463edbc33..1ab398842f 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: cd2404cda8d8702ca0400d3f23d9e1fe041495a1
-README.zh.md: ed6ccc630118dc1bd6d6ea761beefafadb4bd48f
+README.md: 5703540435b976cfc03987edca28e2b5cd24ae0d
+README.zh.md: 434b9bfa3d0d7f21fc262929ac72ff5ab15d5057
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index cd2404cda8..5703540435 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -68,7 +68,7 @@ Subclass `CompactService`, implement `compactIfNeeded`, `compactNow`, and `compa
 
 ## Recognizing a checkpoint outside the host program (`./checkpoint`)
 
-`COMPACT_CHECKPOINT_SOURCE` and `isCompactCheckpointSource()` are declared on the `@deepseek-ai/dsh-compact/checkpoint` subpath and re-exported from the root, so host-side consumers keep reading them from the root. The leaf imports no cordis and declares no module augmentation (the [`dsh-commands/brand`](../../ui/commands/README.md) shape), which is what lets a client or wire program name the checkpoint source: the package **root** cannot enter such a program at all, because it reaches `dsh-session`'s root and that `Context` merge declares the host `sessions` service against the client's own (`TS2717` — one program per side, per [development.md](../../../docs/development.md#typescript-project-layout)). The web client's transcript adapter pins its plugin literal to this leaf with a type-only import, so renaming the plugin id here is a compile error there.
+`COMPACT_CHECKPOINT_SOURCE` and `isCompactCheckpointSource()` are declared on the `@deepseek-ai/dsh-compact/checkpoint` subpath and re-exported from the root, so host-side consumers keep reading them from the root. The leaf imports no cordis and declares no module augmentation (the [`dsh-commands/brand`](../../interaction/commands/README.md) shape), which is what lets a client or wire program name the checkpoint source: the package **root** cannot enter such a program at all, because it reaches `dsh-session`'s root and that `Context` merge declares the host `sessions` service against the client's own (`TS2717` — one program per side, per [development.md](../../../docs/development.md#typescript-project-layout)). The web client's transcript adapter pins its plugin literal to this leaf with a type-only import, so renaming the plugin id here is a compile error there.
 
 ## Model Experience
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index ed6ccc6301..434b9bfa3d 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -68,7 +68,7 @@
 
 ## 在 host 程序之外识别检查点（`./checkpoint`）
 
-`COMPACT_CHECKPOINT_SOURCE` 与 `isCompactCheckpointSource()` 声明在 `@deepseek-ai/dsh-compact/checkpoint` 子路径上，并由包根重新导出，因此 host 侧消费方仍从根读取它们。该叶子不导入 cordis、也不声明任何模块增强（即 [`dsh-commands/brand`](../../ui/commands/README.md) 的形状），这正是客户端或 wire 程序能够命名该检查点来源的原因：包的**根**根本无法进入这类程序，因为它会到达 `dsh-session` 的根，而那处 `Context` 合并会让 host 的 `sessions` 服务与客户端自己的冲突（`TS2717`——每侧一个程序，见 [development.md](../../../docs/development.md#typescript-project-layout)）。Web 客户端的对话记录适配器用仅类型导入把它的插件字面量钉在该叶子上，因此在此处改插件 id 会让那边编译失败。
+`COMPACT_CHECKPOINT_SOURCE` 与 `isCompactCheckpointSource()` 声明在 `@deepseek-ai/dsh-compact/checkpoint` 子路径上，并由包根重新导出，因此 host 侧消费方仍从根读取它们。该叶子不导入 cordis、也不声明任何模块增强（即 [`dsh-commands/brand`](../../interaction/commands/README.md) 的形状），这正是客户端或 wire 程序能够命名该检查点来源的原因：包的**根**根本无法进入这类程序，因为它会到达 `dsh-session` 的根，而那处 `Context` 合并会让 host 的 `sessions` 服务与客户端自己的冲突（`TS2717`——每侧一个程序，见 [development.md](../../../docs/development.md#typescript-project-layout)）。Web 客户端的对话记录适配器用仅类型导入把它的插件字面量钉在该叶子上，因此在此处改插件 id 会让那边编译失败。
 
 ## 模型体验
 
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index c1bd91ce2b..e8157eed7e 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: 81cc57983d83fd19468017b217d4db9978f4e228
-README.zh.md: 9f875bd80a03d1d0f78625ee98eeaad9d118f871
+README.md: fd5cb85540e42e62de28f96bf59890da9561f51e
+README.zh.md: 5911b25b1d77710077063a643a29e500e4da8e95
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index 81cc57983d..fd5cb85540 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -45,7 +45,7 @@ The live registry pipeline has three transformable waterfalls, then the definiti
 - `ToolExecution` — the readonly pipeline view: immutable `{ token, callId, name, arguments, signal, agent?, parent? }`; the registry separately retains and re-fuses the original caller signal. `ToolDispatchExecution` is the `tools/execute`-only view whose required signal is mutable, so a wrapper may replace and restore it but cannot delete it. A nested call's `parent` is a `ToolExecutionToken`, not an execution object.
 - `ToolRunContext` — the execution passed to a tool body, extending `ToolExecution` with `deferContext(context)`. It defers one context until the tool's final result reaches the loop — typically a nested-dispatch context ferried by a composite tool, or a fresh plugin-sourced instruction minted by a leaf tool (`tool-goal`'s wrap-up) — even when the tool later throws or cancellation wins; it never injects immediately.
 - `ToolExecutionResult` — discriminated execution-local outcome. Success is `{ isError:false, value:JsonValue, content, meta?, additionalContexts? }`; failure is `{ isError:true, error:{ message, info? }, content, meta?, additionalContexts? }` and has no value. Call identity stays on the immutable `ToolExecution`. The registry snapshots, validates, and freezes the canonical value before rendering, then materializes the durable presentation fields before final observation. `ToolFailure.info` carries an internal `{ name, code }` for a `HarnessError`; `additionalContexts` preserves every deferred or post-execute identified `UserMessage` for the loop's post-result FIFO.
-- `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite is deliberately not offered; `ask` is serviced by [`ctx.approval`](../../ui/user-approval/README.md) when mounted and otherwise degrades to deny.
+- `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite is deliberately not offered; `ask` is serviced by [`ctx.approval`](../../interaction/user-approval/README.md) when mounted and otherwise degrades to deny.
 - `PostToolDecision` — accept may replace `content` or `value`, never both, and may attach `additionalContexts`; block turns feedback into a valueless failure. Content replacement preserves the canonical value and metadata. Value replacement is revalidated and rerenders content/metadata. Accept preserves tool-deferred contexts before decision contexts; block discards tool-deferred contexts and exposes only contexts explicitly supplied by the blocking decision.
 - `ToolGuard` — `(execution) => string | undefined`; the returned string is a final monotonic denial reason evaluated after the reorderable pre-execute waterfall and before dispatch.
 - `ToolCallView` / `ToolResultView` — provider-neutral `card`-tagged render intents a tool returns from `presentCall` / `presentResult` to own how a UI renders ITS calls (see "Tool-owned UI presentation").
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 9f875bd80a..5911b25b1d 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -45,7 +45,7 @@ tools:
 - `ToolExecution`：只读流水线视图：不可变的 `{ token, callId, name, arguments, signal, agent?, parent? }`；注册表会另行保留并重新融合调用方的原始信号。`ToolDispatchExecution` 是仅供 `tools/execute` 使用的视图，其必填信号可变，因此包装层可以替换并还原它，但不能删除它。嵌套调用的 `parent` 是 `ToolExecutionToken`，而不是执行对象。
 - `ToolRunContext`：传给工具主体的执行上下文，在 `ToolExecution` 基础上增加 `deferContext(context)`。它把一条上下文推迟到该工具的最终结果抵达循环时——通常是组合工具转运的嵌套分发上下文，也可以是叶子工具铸造的全新插件来源指令（如 `tool-goal` 的收尾注入）——即使工具后来抛出或取消胜出也不例外；该方法绝不会立即注入上下文。
 - `ToolExecutionResult`：可辨识的执行局部结果。成功形态为 `{ isError:false, value:JsonValue, content, meta?, additionalContexts? }`；失败形态为 `{ isError:true, error:{ message, info? }, content, meta?, additionalContexts? }`，且不含值。调用身份保留在不可变的 `ToolExecution` 上。注册表会在呈现前快照、验证并冻结规范值，随后在最终观测前实体化持久呈现字段。`ToolFailure.info` 携带内部的 `{ name, code }`，用于表示 `HarnessError`；`additionalContexts` 会保留每个通过延迟或 post-execute 加入且带标识的 `UserMessage`，供循环在结果后按 FIFO 顺序处理。
-- `PreToolDecision`：`{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`。该类型有意不提供输入改写；`ask` 在挂载 [`ctx.approval`](../../ui/user-approval/README.md) 时由它处理，否则退化为拒绝。
+- `PreToolDecision`：`{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`。该类型有意不提供输入改写；`ask` 在挂载 [`ctx.approval`](../../interaction/user-approval/README.md) 时由它处理，否则退化为拒绝。
 - `PostToolDecision`：接受决定可以替换 `content` 或 `value`（不能同时替换），并可附加 `additionalContexts`；阻止决定会把反馈变成无值失败。替换内容会保留规范值和元数据。替换值会重新验证，并重新呈现内容／元数据。接受决定会先保留工具延迟的上下文，再附加决定上下文；阻止决定会丢弃工具延迟的上下文，只公开阻止决定显式提供的上下文。
 - `ToolGuard`：`(execution) => string | undefined`；返回的字符串是最终单调拒绝理由，在可重排的前置执行 waterfall 之后、分发之前求值。
 - `ToolCallView` / `ToolResultView`：提供方无关、带 `card` 标签的呈现意图；工具通过 `presentCall` / `presentResult` 返回该意图，从而拥有 UI 呈现其自身调用的方式（参见「工具拥有的 UI 呈现」）。
diff --git a/packages/core/tools/tsconfig.json b/packages/core/tools/tsconfig.json
index 918112d7d0..de5756ecbd 100644
--- a/packages/core/tools/tsconfig.json
+++ b/packages/core/tools/tsconfig.json
@@ -33,7 +33,7 @@
       "path": "../../core/scope"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/examples/acp-demo/tests/built-bin.e2e.ts b/packages/examples/acp-demo/tests/built-bin.e2e.ts
index d09a0e333d..14b2c3f607 100644
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -33,7 +33,7 @@ const decompress = promisify(zstdDecompress)
 const dshPackages = [
   'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt',
   'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash',
-  'bash/bash-local', 'bash/tool-bash', 'subprocess/subprocess', 'subprocess/subprocess-local', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
+  'bash/bash-local', 'bash/tool-bash', 'subprocess/subprocess', 'subprocess/subprocess-local', 'context/workspace-context', 'support/invariants', 'boot/app-boot',
   'session/session-persistence',
   'session/session-checkpoint-policy', 'session/session-persistence-jsonl',
   'acp/acp', 'examples/acp-demo', 'util/paths',
diff --git a/packages/examples/acp-demo/tsconfig.json b/packages/examples/acp-demo/tsconfig.json
index 34b48fc46a..5c7193f1bb 100644
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -18,7 +18,7 @@
       "path": "../../../vendor/loader"
     },
     {
-      "path": "../../ui/app-boot"
+      "path": "../../boot/app-boot"
     },
     {
       "path": "../../acp/acp"
diff --git a/packages/examples/jsonrpc-demo/tsconfig.json b/packages/examples/jsonrpc-demo/tsconfig.json
index aba279d405..061bbf68c3 100644
--- a/packages/examples/jsonrpc-demo/tsconfig.json
+++ b/packages/examples/jsonrpc-demo/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../../../vendor/loader"
     },
     {
-      "path": "../../ui/app-boot"
+      "path": "../../boot/app-boot"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/fs/tool-fs/tsconfig.json b/packages/fs/tool-fs/tsconfig.json
index fb420b553c..a3f128143c 100644
--- a/packages/fs/tool-fs/tsconfig.json
+++ b/packages/fs/tool-fs/tsconfig.json
@@ -40,7 +40,7 @@
       "path": "../../sandbox/sandbox-policy"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     }
   ]
 }
diff --git a/packages/goal/command-goal/tsconfig.json b/packages/goal/command-goal/tsconfig.json
index 8b03235814..488c576922 100644
--- a/packages/goal/command-goal/tsconfig.json
+++ b/packages/goal/command-goal/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../goal"
diff --git a/packages/host/apiproxy/tsconfig.json b/packages/host/apiproxy/tsconfig.json
index 58c63f5669..64d7944892 100644
--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -66,13 +66,13 @@
       "path": "../../skill/skill"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     },
     {
-      "path": "../../ui/user-interaction"
+      "path": "../../interaction/user-interaction"
     },
     {
       "path": "../../workspace/workspace"
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
new file mode 100644
index 0000000000..2555e896a1
--- /dev/null
+++ b/packages/interaction/README.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 packages/interaction/README.md
+README.md: 506b47753fc9250f9f7bd971265421ad46a106b2
+README.zh.md: 34d336f3d3c10deab166d5c13bb86c13ee9bced0
diff --git a/packages/ui/README.md b/packages/interaction/README.md
similarity index 71%
rename from packages/ui/README.md
rename to packages/interaction/README.md
index 15754410a4..506b47753f 100644
--- a/packages/ui/README.md
+++ b/packages/interaction/README.md
@@ -1,8 +1,8 @@
-# ui/ — human and SDK-client integration surfaces
+# interaction/ — the human-collaboration plane
 
 English | [中文](README.zh.md)
 
-Human-facing channels and the out-of-process SDK server. These are **product** packages: real interfaces that a person or SDK client drives.
+The seams through which a human collaborates with a running agent — questions, approvals, permission presets, commands. These are **product** packages: real interfaces a person drives.
 
 | Package | Role | ctx key |
 |---|---|---|
@@ -11,7 +11,5 @@ Human-facing channels and the out-of-process SDK server. These are **product** p
 | [`permission/`](permission/README.md) | Presents and persists user-facing permission presets. | `ctx.permission` |
 | [`user-interaction/`](user-interaction/README.md) | Defines the provider-neutral human question/answer seam. | `ctx.userInteraction` |
 | [`tool-ask-user/`](tool-ask-user/README.md) | Exposes human questions to the model. | (registers on `ctx.tools`) |
-| [`jsonrpc/`](jsonrpc/README.md) | Serves out-of-process SDK clients over stdio JSON-RPC. | (drives `ctx.agents`) |
-| [`app-boot/`](app-boot/README.md) | Provides shared boot support for application launchers. | (library for the bins) |
 
 These packages integrate through existing agent and session contracts rather than changing the loop. Interactive applications provide the concrete command, approval, and question adapters; automation uses [`acp/`](../acp/README.md), and runnable demo bundles live under [`examples/`](../examples/README.md). The product [`dsh`](../../apps/cli/README.md) CLI composes these packages directly.
diff --git a/packages/ui/README.zh.md b/packages/interaction/README.zh.md
similarity index 69%
rename from packages/ui/README.zh.md
rename to packages/interaction/README.zh.md
index 4023b80085..34d336f3d3 100644
--- a/packages/ui/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -1,8 +1,8 @@
-# ui/：面向用户和 SDK 客户端的集成接口
+# interaction/：人机协作平面
 
 [English](README.md) | 中文
 
-面向用户的通道和进程外 SDK 服务器。这些是**产品**包：由用户或 SDK 客户端直接操作的真实接口。
+人与运行中的 agent（智能体）协作所经由的各个 seam——提问、审批、权限预设、命令。这些是**产品**包（package）：由用户直接操作的真实接口。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
@@ -11,7 +11,5 @@
 | [`permission/`](permission/README.md) | 呈现并持久化面向用户的权限预设。 | `ctx.permission` |
 | [`user-interaction/`](user-interaction/README.md) | 定义与提供方无关的用户问答 seam。 | `ctx.userInteraction` |
 | [`tool-ask-user/`](tool-ask-user/README.md) | 向模型公开用户问题。 | （注册到 `ctx.tools`） |
-| [`jsonrpc/`](jsonrpc/README.md) | 通过 stdio JSON-RPC 为进程外 SDK 客户端提供服务。 | （驱动 `ctx.agents`） |
-| [`app-boot/`](app-boot/README.md) | 为应用启动器提供共享启动支持。 | （供各 bin 使用的库） |
 
 这些包通过现有的 agent（智能体）和会话契约集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
diff --git a/packages/ui/commands/README.i18n.yaml b/packages/interaction/commands/README.i18n.yaml
similarity index 79%
rename from packages/ui/commands/README.i18n.yaml
rename to packages/interaction/commands/README.i18n.yaml
index be55a19ca3..967fa0d4ef 100644
--- a/packages/ui/commands/README.i18n.yaml
+++ b/packages/interaction/commands/README.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 packages/ui/commands/README.md
+#   pnpm run verify-translation-pairing --write packages/interaction/commands/README.md
 README.md: 1709bdcdce4e43d98cfea5ff3972ab95bfd3c33b
 README.zh.md: 569f2aa8293793b26d63ee16e3ea7600e04a8397
diff --git a/packages/ui/commands/README.md b/packages/interaction/commands/README.md
similarity index 100%
rename from packages/ui/commands/README.md
rename to packages/interaction/commands/README.md
diff --git a/packages/ui/commands/README.zh.md b/packages/interaction/commands/README.zh.md
similarity index 100%
rename from packages/ui/commands/README.zh.md
rename to packages/interaction/commands/README.zh.md
diff --git a/packages/ui/commands/package.json b/packages/interaction/commands/package.json
similarity index 100%
rename from packages/ui/commands/package.json
rename to packages/interaction/commands/package.json
diff --git a/packages/ui/commands/src/brand.ts b/packages/interaction/commands/src/brand.ts
similarity index 100%
rename from packages/ui/commands/src/brand.ts
rename to packages/interaction/commands/src/brand.ts
diff --git a/packages/ui/commands/src/index.ts b/packages/interaction/commands/src/index.ts
similarity index 100%
rename from packages/ui/commands/src/index.ts
rename to packages/interaction/commands/src/index.ts
diff --git a/packages/ui/commands/src/invariant.ts b/packages/interaction/commands/src/invariant.ts
similarity index 100%
rename from packages/ui/commands/src/invariant.ts
rename to packages/interaction/commands/src/invariant.ts
diff --git a/packages/ui/commands/tests/commands.spec.ts b/packages/interaction/commands/tests/commands.spec.ts
similarity index 100%
rename from packages/ui/commands/tests/commands.spec.ts
rename to packages/interaction/commands/tests/commands.spec.ts
diff --git a/packages/ui/commands/tests/invariant.spec.ts b/packages/interaction/commands/tests/invariant.spec.ts
similarity index 100%
rename from packages/ui/commands/tests/invariant.spec.ts
rename to packages/interaction/commands/tests/invariant.spec.ts
diff --git a/packages/ui/commands/tsconfig.json b/packages/interaction/commands/tsconfig.json
similarity index 100%
rename from packages/ui/commands/tsconfig.json
rename to packages/interaction/commands/tsconfig.json
diff --git a/packages/interaction/permission/README.i18n.yaml b/packages/interaction/permission/README.i18n.yaml
new file mode 100644
index 0000000000..b5883174dc
--- /dev/null
+++ b/packages/interaction/permission/README.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 packages/interaction/permission/README.md
+README.md: 814085ed6f2c9650854f377e1c97e442fc4211a4
+README.zh.md: 36880d6b8c3f0b39b88db1abb02534f30e3355fa
diff --git a/packages/ui/permission/README.md b/packages/interaction/permission/README.md
similarity index 100%
rename from packages/ui/permission/README.md
rename to packages/interaction/permission/README.md
diff --git a/packages/ui/permission/README.zh.md b/packages/interaction/permission/README.zh.md
similarity index 100%
rename from packages/ui/permission/README.zh.md
rename to packages/interaction/permission/README.zh.md
diff --git a/packages/ui/permission/package.json b/packages/interaction/permission/package.json
similarity index 100%
rename from packages/ui/permission/package.json
rename to packages/interaction/permission/package.json
diff --git a/packages/ui/permission/src/client.ts b/packages/interaction/permission/src/client.ts
similarity index 100%
rename from packages/ui/permission/src/client.ts
rename to packages/interaction/permission/src/client.ts
diff --git a/packages/ui/permission/src/index.ts b/packages/interaction/permission/src/index.ts
similarity index 100%
rename from packages/ui/permission/src/index.ts
rename to packages/interaction/permission/src/index.ts
diff --git a/packages/ui/permission/src/invariant.ts b/packages/interaction/permission/src/invariant.ts
similarity index 100%
rename from packages/ui/permission/src/invariant.ts
rename to packages/interaction/permission/src/invariant.ts
diff --git a/packages/ui/permission/src/types.ts b/packages/interaction/permission/src/types.ts
similarity index 100%
rename from packages/ui/permission/src/types.ts
rename to packages/interaction/permission/src/types.ts
diff --git a/packages/ui/permission/tests/invariant.spec.ts b/packages/interaction/permission/tests/invariant.spec.ts
similarity index 100%
rename from packages/ui/permission/tests/invariant.spec.ts
rename to packages/interaction/permission/tests/invariant.spec.ts
diff --git a/packages/ui/permission/tests/permission.spec.ts b/packages/interaction/permission/tests/permission.spec.ts
similarity index 100%
rename from packages/ui/permission/tests/permission.spec.ts
rename to packages/interaction/permission/tests/permission.spec.ts
diff --git a/packages/ui/permission/tests/projection.spec.ts b/packages/interaction/permission/tests/projection.spec.ts
similarity index 100%
rename from packages/ui/permission/tests/projection.spec.ts
rename to packages/interaction/permission/tests/projection.spec.ts
diff --git a/packages/ui/permission/tsconfig.json b/packages/interaction/permission/tsconfig.json
similarity index 100%
rename from packages/ui/permission/tsconfig.json
rename to packages/interaction/permission/tsconfig.json
diff --git a/packages/ui/tool-ask-user/README.i18n.yaml b/packages/interaction/tool-ask-user/README.i18n.yaml
similarity index 79%
rename from packages/ui/tool-ask-user/README.i18n.yaml
rename to packages/interaction/tool-ask-user/README.i18n.yaml
index bbd0ba0561..f88c303525 100644
--- a/packages/ui/tool-ask-user/README.i18n.yaml
+++ b/packages/interaction/tool-ask-user/README.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 packages/ui/tool-ask-user/README.md
+#   pnpm run verify-translation-pairing --write packages/interaction/tool-ask-user/README.md
 README.md: 7af356263ea6582a081e7c6de22fd317ca8b96df
 README.zh.md: 3f7b814b83c8c6957a4b2574ee69e87d45f65ae6
diff --git a/packages/ui/tool-ask-user/README.md b/packages/interaction/tool-ask-user/README.md
similarity index 100%
rename from packages/ui/tool-ask-user/README.md
rename to packages/interaction/tool-ask-user/README.md
diff --git a/packages/ui/tool-ask-user/README.zh.md b/packages/interaction/tool-ask-user/README.zh.md
similarity index 100%
rename from packages/ui/tool-ask-user/README.zh.md
rename to packages/interaction/tool-ask-user/README.zh.md
diff --git a/packages/ui/tool-ask-user/package.json b/packages/interaction/tool-ask-user/package.json
similarity index 100%
rename from packages/ui/tool-ask-user/package.json
rename to packages/interaction/tool-ask-user/package.json
diff --git a/packages/ui/tool-ask-user/src/index.ts b/packages/interaction/tool-ask-user/src/index.ts
similarity index 100%
rename from packages/ui/tool-ask-user/src/index.ts
rename to packages/interaction/tool-ask-user/src/index.ts
diff --git a/packages/ui/tool-ask-user/src/invariant.ts b/packages/interaction/tool-ask-user/src/invariant.ts
similarity index 100%
rename from packages/ui/tool-ask-user/src/invariant.ts
rename to packages/interaction/tool-ask-user/src/invariant.ts
diff --git a/packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts b/packages/interaction/tool-ask-user/tests/tool-ask-user.spec.ts
similarity index 100%
rename from packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts
rename to packages/interaction/tool-ask-user/tests/tool-ask-user.spec.ts
diff --git a/packages/ui/tool-ask-user/tsconfig.json b/packages/interaction/tool-ask-user/tsconfig.json
similarity index 100%
rename from packages/ui/tool-ask-user/tsconfig.json
rename to packages/interaction/tool-ask-user/tsconfig.json
diff --git a/packages/ui/user-approval/README.i18n.yaml b/packages/interaction/user-approval/README.i18n.yaml
similarity index 79%
rename from packages/ui/user-approval/README.i18n.yaml
rename to packages/interaction/user-approval/README.i18n.yaml
index cf9c8e1fce..36188334e7 100644
--- a/packages/ui/user-approval/README.i18n.yaml
+++ b/packages/interaction/user-approval/README.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 packages/ui/user-approval/README.md
+#   pnpm run verify-translation-pairing --write packages/interaction/user-approval/README.md
 README.md: 7b87a75d1c7c43874c484bc11f8deed45cb523ce
 README.zh.md: 3c02f8d673a62c3ee954da26f6341b433032a88c
diff --git a/packages/ui/user-approval/README.md b/packages/interaction/user-approval/README.md
similarity index 100%
rename from packages/ui/user-approval/README.md
rename to packages/interaction/user-approval/README.md
diff --git a/packages/ui/user-approval/README.zh.md b/packages/interaction/user-approval/README.zh.md
similarity index 100%
rename from packages/ui/user-approval/README.zh.md
rename to packages/interaction/user-approval/README.zh.md
diff --git a/packages/ui/user-approval/package.json b/packages/interaction/user-approval/package.json
similarity index 100%
rename from packages/ui/user-approval/package.json
rename to packages/interaction/user-approval/package.json
diff --git a/packages/ui/user-approval/src/index.ts b/packages/interaction/user-approval/src/index.ts
similarity index 100%
rename from packages/ui/user-approval/src/index.ts
rename to packages/interaction/user-approval/src/index.ts
diff --git a/packages/ui/user-approval/src/invariant.ts b/packages/interaction/user-approval/src/invariant.ts
similarity index 100%
rename from packages/ui/user-approval/src/invariant.ts
rename to packages/interaction/user-approval/src/invariant.ts
diff --git a/packages/ui/user-approval/src/types.ts b/packages/interaction/user-approval/src/types.ts
similarity index 100%
rename from packages/ui/user-approval/src/types.ts
rename to packages/interaction/user-approval/src/types.ts
diff --git a/packages/ui/user-approval/tests/approval.spec.ts b/packages/interaction/user-approval/tests/approval.spec.ts
similarity index 100%
rename from packages/ui/user-approval/tests/approval.spec.ts
rename to packages/interaction/user-approval/tests/approval.spec.ts
diff --git a/packages/ui/user-approval/tests/invariant.spec.ts b/packages/interaction/user-approval/tests/invariant.spec.ts
similarity index 100%
rename from packages/ui/user-approval/tests/invariant.spec.ts
rename to packages/interaction/user-approval/tests/invariant.spec.ts
diff --git a/packages/ui/user-approval/tsconfig.json b/packages/interaction/user-approval/tsconfig.json
similarity index 100%
rename from packages/ui/user-approval/tsconfig.json
rename to packages/interaction/user-approval/tsconfig.json
diff --git a/packages/ui/user-approval/tsdown.config.ts b/packages/interaction/user-approval/tsdown.config.ts
similarity index 100%
rename from packages/ui/user-approval/tsdown.config.ts
rename to packages/interaction/user-approval/tsdown.config.ts
diff --git a/packages/interaction/user-interaction/README.i18n.yaml b/packages/interaction/user-interaction/README.i18n.yaml
new file mode 100644
index 0000000000..f467aaf4e1
--- /dev/null
+++ b/packages/interaction/user-interaction/README.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 packages/interaction/user-interaction/README.md
+README.md: d234d6677bdd772f1bbd2c979c0d41f90aef5c32
+README.zh.md: c89210b6955a661313ca9e0e82e43da5a4d1db79
diff --git a/packages/ui/user-interaction/README.md b/packages/interaction/user-interaction/README.md
similarity index 100%
rename from packages/ui/user-interaction/README.md
rename to packages/interaction/user-interaction/README.md
diff --git a/packages/ui/user-interaction/README.zh.md b/packages/interaction/user-interaction/README.zh.md
similarity index 100%
rename from packages/ui/user-interaction/README.zh.md
rename to packages/interaction/user-interaction/README.zh.md
diff --git a/packages/ui/user-interaction/package.json b/packages/interaction/user-interaction/package.json
similarity index 100%
rename from packages/ui/user-interaction/package.json
rename to packages/interaction/user-interaction/package.json
diff --git a/packages/ui/user-interaction/src/index.ts b/packages/interaction/user-interaction/src/index.ts
similarity index 100%
rename from packages/ui/user-interaction/src/index.ts
rename to packages/interaction/user-interaction/src/index.ts
diff --git a/packages/ui/user-interaction/src/invariant.ts b/packages/interaction/user-interaction/src/invariant.ts
similarity index 100%
rename from packages/ui/user-interaction/src/invariant.ts
rename to packages/interaction/user-interaction/src/invariant.ts
diff --git a/packages/ui/user-interaction/src/types.ts b/packages/interaction/user-interaction/src/types.ts
similarity index 100%
rename from packages/ui/user-interaction/src/types.ts
rename to packages/interaction/user-interaction/src/types.ts
diff --git a/packages/ui/user-interaction/tests/user-interaction.spec.ts b/packages/interaction/user-interaction/tests/user-interaction.spec.ts
similarity index 100%
rename from packages/ui/user-interaction/tests/user-interaction.spec.ts
rename to packages/interaction/user-interaction/tests/user-interaction.spec.ts
diff --git a/packages/ui/user-interaction/tsconfig.json b/packages/interaction/user-interaction/tsconfig.json
similarity index 100%
rename from packages/ui/user-interaction/tsconfig.json
rename to packages/interaction/user-interaction/tsconfig.json
diff --git a/packages/plan/plan-mode/tsconfig.json b/packages/plan/plan-mode/tsconfig.json
index 6fa3cffbbc..4dde8fda45 100644
--- a/packages/plan/plan-mode/tsconfig.json
+++ b/packages/plan/plan-mode/tsconfig.json
@@ -27,10 +27,10 @@
       "path": "../../core/system-prompt"
     },
     {
-      "path": "../../ui/user-interaction"
+      "path": "../../interaction/user-interaction"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../../session/session-projection"
diff --git a/packages/ui/README.i18n.yaml b/packages/scaffold/README.i18n.yaml
similarity index 57%
rename from packages/ui/README.i18n.yaml
rename to packages/scaffold/README.i18n.yaml
index fba1f95c52..1480a14b69 100644
--- a/packages/ui/README.i18n.yaml
+++ b/packages/scaffold/README.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 packages/ui/README.md
-README.md: 15754410a4a81eb3fc898dd55269ddd1637e1dab
-README.zh.md: 4023b80085998f57ed321bfda3a0abdd08b70a28
+#   pnpm run verify-translation-pairing --write packages/scaffold/README.md
+README.md: b166a351a53afe075ecb794fe2bf6f0702a435ae
+README.zh.md: 6e2a65ea554487f48563c16e1defa37ef1a5e043
diff --git a/packages/sdk/README.md b/packages/scaffold/README.md
similarity index 64%
rename from packages/sdk/README.md
rename to packages/scaffold/README.md
index 3f99d6d45d..b166a351a5 100644
--- a/packages/sdk/README.md
+++ b/packages/scaffold/README.md
@@ -1,16 +1,17 @@
-# SDK packages
+# scaffold/ — create, launch, and drive projects from outside
 
 English | [中文](README.zh.md)
 
-This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process.
+This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named without the legacy `sdk-` prefix; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md).
 
 | Package | Role |
 |---|---|
 | [`helper/`](helper/README.md) | Provides the shared project-editing domain |
 | [`scripts/`](scripts/README.md) | Provides the `dsh-sdk` project commands |
 | [`create-sdk/`](create-sdk/README.md) | Creates new SDK projects |
-| [`sdk-protocol/`](sdk-protocol/README.md) | Defines the SDK runtime wire protocol |
-| [`sdk-client/`](sdk-client/README.md) | Drives a Harness runtime through the TypeScript client API |
+| [`protocol/`](protocol/README.md) | Defines the SDK runtime wire protocol |
+| [`client/`](client/README.md) | Drives a Harness runtime through the TypeScript client API |
+| [`server/`](server/README.md) | Serves out-of-process SDK clients over stdio JSON-RPC |
 | [`telemetry/`](telemetry/README.md) | Provides launcher telemetry, consent, and redaction primitives |
 
 `@deepseek-ai/create-sdk` follows npm's scoped initializer naming convention; the other packages follow the repository's `@deepseek-ai/dsh-*` convention. See the [developer-project workflow](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md), [project-editing architecture](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md), and [TypeScript SDK design](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md).
diff --git a/packages/scaffold/README.zh.md b/packages/scaffold/README.zh.md
new file mode 100644
index 0000000000..6e2a65ea55
--- /dev/null
+++ b/packages/scaffold/README.zh.md
@@ -0,0 +1,17 @@
+# scaffold/：从外部创建、启动、驱动项目
+
+[English](README.md) | 中文
+
+本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名，不带遗留的 `sdk-` 前缀；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
+
+| 包 | 职责 |
+|---|---|
+| [`helper/`](helper/README.md) | 提供共享的项目编辑领域 |
+| [`scripts/`](scripts/README.md) | 提供 `dsh-sdk` 项目命令 |
+| [`create-sdk/`](create-sdk/README.md) | 创建新的 SDK 项目 |
+| [`protocol/`](protocol/README.md) | 定义 SDK 运行时通信协议 |
+| [`client/`](client/README.md) | 通过 TypeScript 客户端 API 驱动 Harness 运行时 |
+| [`server/`](server/README.md) | 通过 stdio JSON-RPC 为进程外 SDK 客户端提供服务 |
+| [`telemetry/`](telemetry/README.md) | 提供启动器 telemetry、同意与脱敏原语 |
+
+`@deepseek-ai/create-sdk` 遵循 npm 的 scoped initializer 命名约定；其余包遵循仓库的 `@deepseek-ai/dsh-*` 约定。参见[开发者项目工作流](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md)、[项目编辑架构](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md)与 [TypeScript SDK 设计](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md)。
diff --git a/packages/sdk/sdk-client/README.i18n.yaml b/packages/scaffold/client/README.i18n.yaml
similarity index 80%
rename from packages/sdk/sdk-client/README.i18n.yaml
rename to packages/scaffold/client/README.i18n.yaml
index bff82b8aec..0a71141cd6 100644
--- a/packages/sdk/sdk-client/README.i18n.yaml
+++ b/packages/scaffold/client/README.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 packages/sdk/sdk-client/README.md
+#   pnpm run verify-translation-pairing --write packages/scaffold/client/README.md
 README.md: f27ec256330254156c45b136c21308529ea99e3d
 README.zh.md: bd23762500a4da469839da8ddb50455e3419b553
diff --git a/packages/sdk/sdk-client/README.md b/packages/scaffold/client/README.md
similarity index 100%
rename from packages/sdk/sdk-client/README.md
rename to packages/scaffold/client/README.md
diff --git a/packages/sdk/sdk-client/README.zh.md b/packages/scaffold/client/README.zh.md
similarity index 100%
rename from packages/sdk/sdk-client/README.zh.md
rename to packages/scaffold/client/README.zh.md
diff --git a/packages/sdk/sdk-client/package.json b/packages/scaffold/client/package.json
similarity index 100%
rename from packages/sdk/sdk-client/package.json
rename to packages/scaffold/client/package.json
diff --git a/packages/sdk/sdk-client/src/api.ts b/packages/scaffold/client/src/api.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/api.ts
rename to packages/scaffold/client/src/api.ts
diff --git a/packages/sdk/sdk-client/src/client.ts b/packages/scaffold/client/src/client.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/client.ts
rename to packages/scaffold/client/src/client.ts
diff --git a/packages/sdk/sdk-client/src/dispose.ts b/packages/scaffold/client/src/dispose.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/dispose.ts
rename to packages/scaffold/client/src/dispose.ts
diff --git a/packages/sdk/sdk-client/src/index.ts b/packages/scaffold/client/src/index.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/index.ts
rename to packages/scaffold/client/src/index.ts
diff --git a/packages/sdk/sdk-client/src/invariant.ts b/packages/scaffold/client/src/invariant.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/invariant.ts
rename to packages/scaffold/client/src/invariant.ts
diff --git a/packages/sdk/sdk-client/src/types.ts b/packages/scaffold/client/src/types.ts
similarity index 100%
rename from packages/sdk/sdk-client/src/types.ts
rename to packages/scaffold/client/src/types.ts
diff --git a/packages/sdk/sdk-client/tests/dispose.spec.ts b/packages/scaffold/client/tests/dispose.spec.ts
similarity index 100%
rename from packages/sdk/sdk-client/tests/dispose.spec.ts
rename to packages/scaffold/client/tests/dispose.spec.ts
diff --git a/packages/sdk/sdk-client/tests/fake-runtime.ts b/packages/scaffold/client/tests/fake-runtime.ts
similarity index 100%
rename from packages/sdk/sdk-client/tests/fake-runtime.ts
rename to packages/scaffold/client/tests/fake-runtime.ts
diff --git a/packages/sdk/sdk-client/tests/sdk-client.spec.ts b/packages/scaffold/client/tests/sdk-client.spec.ts
similarity index 100%
rename from packages/sdk/sdk-client/tests/sdk-client.spec.ts
rename to packages/scaffold/client/tests/sdk-client.spec.ts
diff --git a/packages/sdk/sdk-client/tsconfig.json b/packages/scaffold/client/tsconfig.json
similarity index 93%
rename from packages/sdk/sdk-client/tsconfig.json
rename to packages/scaffold/client/tsconfig.json
index 567c6582bb..a5456f5ad3 100644
--- a/packages/sdk/sdk-client/tsconfig.json
+++ b/packages/scaffold/client/tsconfig.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../sdk-protocol"
+      "path": "../protocol"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/sdk/create-sdk/README.i18n.yaml b/packages/scaffold/create-sdk/README.i18n.yaml
similarity index 80%
rename from packages/sdk/create-sdk/README.i18n.yaml
rename to packages/scaffold/create-sdk/README.i18n.yaml
index 27609d9a11..62d5bd3793 100644
--- a/packages/sdk/create-sdk/README.i18n.yaml
+++ b/packages/scaffold/create-sdk/README.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 packages/sdk/create-sdk/README.md
+#   pnpm run verify-translation-pairing --write packages/scaffold/create-sdk/README.md
 README.md: aa09236832a50abdcd2b158e0561db26bce19cf6
 README.zh.md: a4685e66bc3eb7924dd247a7b6b420f6bcc70990
diff --git a/packages/sdk/create-sdk/README.md b/packages/scaffold/create-sdk/README.md
similarity index 100%
rename from packages/sdk/create-sdk/README.md
rename to packages/scaffold/create-sdk/README.md
diff --git a/packages/sdk/create-sdk/README.zh.md b/packages/scaffold/create-sdk/README.zh.md
similarity index 100%
rename from packages/sdk/create-sdk/README.zh.md
rename to packages/scaffold/create-sdk/README.zh.md
diff --git a/packages/sdk/create-sdk/package.json b/packages/scaffold/create-sdk/package.json
similarity index 100%
rename from packages/sdk/create-sdk/package.json
rename to packages/scaffold/create-sdk/package.json
diff --git a/packages/sdk/create-sdk/src/args.ts b/packages/scaffold/create-sdk/src/args.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/args.ts
rename to packages/scaffold/create-sdk/src/args.ts
diff --git a/packages/sdk/create-sdk/src/bin.ts b/packages/scaffold/create-sdk/src/bin.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/bin.ts
rename to packages/scaffold/create-sdk/src/bin.ts
diff --git a/packages/sdk/create-sdk/src/command.ts b/packages/scaffold/create-sdk/src/command.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/command.ts
rename to packages/scaffold/create-sdk/src/command.ts
diff --git a/packages/sdk/create-sdk/src/create-questions.ts b/packages/scaffold/create-sdk/src/create-questions.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/create-questions.ts
rename to packages/scaffold/create-sdk/src/create-questions.ts
diff --git a/packages/sdk/create-sdk/src/create-wizard.ts b/packages/scaffold/create-sdk/src/create-wizard.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/create-wizard.ts
rename to packages/scaffold/create-sdk/src/create-wizard.ts
diff --git a/packages/sdk/create-sdk/src/headless.ts b/packages/scaffold/create-sdk/src/headless.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/headless.ts
rename to packages/scaffold/create-sdk/src/headless.ts
diff --git a/packages/sdk/create-sdk/src/index.ts b/packages/scaffold/create-sdk/src/index.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/index.ts
rename to packages/scaffold/create-sdk/src/index.ts
diff --git a/packages/sdk/create-sdk/src/invariant.ts b/packages/scaffold/create-sdk/src/invariant.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/invariant.ts
rename to packages/scaffold/create-sdk/src/invariant.ts
diff --git a/packages/sdk/create-sdk/src/project-scaffolder.ts b/packages/scaffold/create-sdk/src/project-scaffolder.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/project-scaffolder.ts
rename to packages/scaffold/create-sdk/src/project-scaffolder.ts
diff --git a/packages/sdk/create-sdk/src/templates/assets/created.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/created.txt.tpl
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/assets/created.txt.tpl
rename to packages/scaffold/create-sdk/src/templates/assets/created.txt.tpl
diff --git a/packages/sdk/create-sdk/src/templates/assets/install-question.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/install-question.txt.tpl
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/assets/install-question.txt.tpl
rename to packages/scaffold/create-sdk/src/templates/assets/install-question.txt.tpl
diff --git a/packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/next-steps.txt.tpl
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl
rename to packages/scaffold/create-sdk/src/templates/assets/next-steps.txt.tpl
diff --git a/packages/sdk/create-sdk/src/templates/assets/setup-failure.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/setup-failure.txt.tpl
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/assets/setup-failure.txt.tpl
rename to packages/scaffold/create-sdk/src/templates/assets/setup-failure.txt.tpl
diff --git a/packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl b/packages/scaffold/create-sdk/src/templates/assets/usage.txt.tpl
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl
rename to packages/scaffold/create-sdk/src/templates/assets/usage.txt.tpl
diff --git a/packages/sdk/create-sdk/src/templates/create-templates.ts b/packages/scaffold/create-sdk/src/templates/create-templates.ts
similarity index 100%
rename from packages/sdk/create-sdk/src/templates/create-templates.ts
rename to packages/scaffold/create-sdk/src/templates/create-templates.ts
diff --git a/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts b/packages/scaffold/create-sdk/tests/built-artifacts.e2e.ts
similarity index 87%
rename from packages/sdk/create-sdk/tests/built-artifacts.e2e.ts
rename to packages/scaffold/create-sdk/tests/built-artifacts.e2e.ts
index 4b2de078c7..827abe06a2 100644
--- a/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts
+++ b/packages/scaffold/create-sdk/tests/built-artifacts.e2e.ts
@@ -7,8 +7,8 @@ import { describe, expect, it } from 'vitest'
 
 const execFileAsync = promisify(execFile)
 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const createBin = join(repoRoot, 'packages/sdk/create-sdk/lib/bin.js')
-const scriptsBin = join(repoRoot, 'packages/sdk/scripts/lib/bin.js')
+const createBin = join(repoRoot, 'packages/scaffold/create-sdk/lib/bin.js')
+const scriptsBin = join(repoRoot, 'packages/scaffold/scripts/lib/bin.js')
 
 describe.skipIf(!existsSync(createBin) || !existsSync(scriptsBin))(
   'SDK built artifacts',
diff --git a/packages/sdk/create-sdk/tests/create.snapshot.ts b/packages/scaffold/create-sdk/tests/create.snapshot.ts
similarity index 100%
rename from packages/sdk/create-sdk/tests/create.snapshot.ts
rename to packages/scaffold/create-sdk/tests/create.snapshot.ts
diff --git a/packages/sdk/create-sdk/tests/create.spec.ts b/packages/scaffold/create-sdk/tests/create.spec.ts
similarity index 100%
rename from packages/sdk/create-sdk/tests/create.spec.ts
rename to packages/scaffold/create-sdk/tests/create.spec.ts
diff --git a/packages/sdk/create-sdk/tests/link-workspace.e2e.ts b/packages/scaffold/create-sdk/tests/link-workspace.e2e.ts
similarity index 98%
rename from packages/sdk/create-sdk/tests/link-workspace.e2e.ts
rename to packages/scaffold/create-sdk/tests/link-workspace.e2e.ts
index b7739acc16..b978c8217e 100644
--- a/packages/sdk/create-sdk/tests/link-workspace.e2e.ts
+++ b/packages/scaffold/create-sdk/tests/link-workspace.e2e.ts
@@ -17,7 +17,7 @@ import { scaffoldProject } from '../src/project-scaffolder.ts'
 
 const execFileAsync = promisify(execFile)
 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const builtScripts = join(repoRoot, 'packages/sdk/scripts/lib/bin.js')
+const builtScripts = join(repoRoot, 'packages/scaffold/scripts/lib/bin.js')
 const temporary: string[] = []
 
 function resolveCorepackHome(): string {
diff --git a/packages/sdk/create-sdk/tsconfig.json b/packages/scaffold/create-sdk/tsconfig.json
similarity index 100%
rename from packages/sdk/create-sdk/tsconfig.json
rename to packages/scaffold/create-sdk/tsconfig.json
diff --git a/packages/sdk/create-sdk/tsdown.config.ts b/packages/scaffold/create-sdk/tsdown.config.ts
similarity index 100%
rename from packages/sdk/create-sdk/tsdown.config.ts
rename to packages/scaffold/create-sdk/tsdown.config.ts
diff --git a/packages/sdk/helper/README.i18n.yaml b/packages/scaffold/helper/README.i18n.yaml
similarity index 80%
rename from packages/sdk/helper/README.i18n.yaml
rename to packages/scaffold/helper/README.i18n.yaml
index bb5acbdcc2..a62db5f38a 100644
--- a/packages/sdk/helper/README.i18n.yaml
+++ b/packages/scaffold/helper/README.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 packages/sdk/helper/README.md
+#   pnpm run verify-translation-pairing --write packages/scaffold/helper/README.md
 README.md: 416fcab9815e50ca662333eb6925cc37eb0c41c4
 README.zh.md: c50ec7aafa03377bd11759c50eeb2422a12fab68
diff --git a/packages/sdk/helper/README.md b/packages/scaffold/helper/README.md
similarity index 100%
rename from packages/sdk/helper/README.md
rename to packages/scaffold/helper/README.md
diff --git a/packages/sdk/helper/README.zh.md b/packages/scaffold/helper/README.zh.md
similarity index 100%
rename from packages/sdk/helper/README.zh.md
rename to packages/scaffold/helper/README.zh.md
diff --git a/packages/sdk/helper/package.json b/packages/scaffold/helper/package.json
similarity index 100%
rename from packages/sdk/helper/package.json
rename to packages/scaffold/helper/package.json
diff --git a/packages/sdk/helper/src/documents/cordis-yaml-file.ts b/packages/scaffold/helper/src/documents/cordis-yaml-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/cordis-yaml-file.ts
rename to packages/scaffold/helper/src/documents/cordis-yaml-file.ts
diff --git a/packages/sdk/helper/src/documents/env-file.ts b/packages/scaffold/helper/src/documents/env-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/env-file.ts
rename to packages/scaffold/helper/src/documents/env-file.ts
diff --git a/packages/sdk/helper/src/documents/package-json-file.ts b/packages/scaffold/helper/src/documents/package-json-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/package-json-file.ts
rename to packages/scaffold/helper/src/documents/package-json-file.ts
diff --git a/packages/sdk/helper/src/documents/pnpm-workspace-file.ts b/packages/scaffold/helper/src/documents/pnpm-workspace-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/pnpm-workspace-file.ts
rename to packages/scaffold/helper/src/documents/pnpm-workspace-file.ts
diff --git a/packages/sdk/helper/src/documents/project-file.ts b/packages/scaffold/helper/src/documents/project-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/project-file.ts
rename to packages/scaffold/helper/src/documents/project-file.ts
diff --git a/packages/sdk/helper/src/documents/tsconfig-file.ts b/packages/scaffold/helper/src/documents/tsconfig-file.ts
similarity index 100%
rename from packages/sdk/helper/src/documents/tsconfig-file.ts
rename to packages/scaffold/helper/src/documents/tsconfig-file.ts
diff --git a/packages/sdk/helper/src/features/builtin/app.ts b/packages/scaffold/helper/src/features/builtin/app.ts
similarity index 100%
rename from packages/sdk/helper/src/features/builtin/app.ts
rename to packages/scaffold/helper/src/features/builtin/app.ts
diff --git a/packages/sdk/helper/src/features/builtin/helpers.ts b/packages/scaffold/helper/src/features/builtin/helpers.ts
similarity index 100%
rename from packages/sdk/helper/src/features/builtin/helpers.ts
rename to packages/scaffold/helper/src/features/builtin/helpers.ts
diff --git a/packages/sdk/helper/src/features/builtin/index.ts b/packages/scaffold/helper/src/features/builtin/index.ts
similarity index 100%
rename from packages/sdk/helper/src/features/builtin/index.ts
rename to packages/scaffold/helper/src/features/builtin/index.ts
diff --git a/packages/sdk/helper/src/features/builtin/provider.ts b/packages/scaffold/helper/src/features/builtin/provider.ts
similarity index 100%
rename from packages/sdk/helper/src/features/builtin/provider.ts
rename to packages/scaffold/helper/src/features/builtin/provider.ts
diff --git a/packages/sdk/helper/src/features/builtin/spine.ts b/packages/scaffold/helper/src/features/builtin/spine.ts
similarity index 100%
rename from packages/sdk/helper/src/features/builtin/spine.ts
rename to packages/scaffold/helper/src/features/builtin/spine.ts
diff --git a/packages/sdk/helper/src/features/define-feature.ts b/packages/scaffold/helper/src/features/define-feature.ts
similarity index 100%
rename from packages/sdk/helper/src/features/define-feature.ts
rename to packages/scaffold/helper/src/features/define-feature.ts
diff --git a/packages/sdk/helper/src/features/feature-configurator.ts b/packages/scaffold/helper/src/features/feature-configurator.ts
similarity index 100%
rename from packages/sdk/helper/src/features/feature-configurator.ts
rename to packages/scaffold/helper/src/features/feature-configurator.ts
diff --git a/packages/sdk/helper/src/features/feature.ts b/packages/scaffold/helper/src/features/feature.ts
similarity index 100%
rename from packages/sdk/helper/src/features/feature.ts
rename to packages/scaffold/helper/src/features/feature.ts
diff --git a/packages/sdk/helper/src/features/registry.ts b/packages/scaffold/helper/src/features/registry.ts
similarity index 100%
rename from packages/sdk/helper/src/features/registry.ts
rename to packages/scaffold/helper/src/features/registry.ts
diff --git a/packages/sdk/helper/src/features/resources.ts b/packages/scaffold/helper/src/features/resources.ts
similarity index 100%
rename from packages/sdk/helper/src/features/resources.ts
rename to packages/scaffold/helper/src/features/resources.ts
diff --git a/packages/sdk/helper/src/ids.ts b/packages/scaffold/helper/src/ids.ts
similarity index 100%
rename from packages/sdk/helper/src/ids.ts
rename to packages/scaffold/helper/src/ids.ts
diff --git a/packages/sdk/helper/src/index.ts b/packages/scaffold/helper/src/index.ts
similarity index 86%
rename from packages/sdk/helper/src/index.ts
rename to packages/scaffold/helper/src/index.ts
index 85aba58a99..8c8e0db4b9 100644
--- a/packages/sdk/helper/src/index.ts
+++ b/packages/scaffold/helper/src/index.ts
@@ -1,6 +1,10 @@
 /**
  * Shared domain and infrastructure for DeepSeek Harness SDK project tooling.
  *
+ * FIXME: rename to `@deepseek-ai/dsh-sdk-helper` before the first tagged release —
+ * the current name is indefensibly generic as a published name
+ * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ *
  * @module @deepseek-ai/dsh-helper
  */
 
diff --git a/packages/sdk/helper/src/invariant.ts b/packages/scaffold/helper/src/invariant.ts
similarity index 100%
rename from packages/sdk/helper/src/invariant.ts
rename to packages/scaffold/helper/src/invariant.ts
diff --git a/packages/sdk/helper/src/package-managers/link-workspace.ts b/packages/scaffold/helper/src/package-managers/link-workspace.ts
similarity index 100%
rename from packages/sdk/helper/src/package-managers/link-workspace.ts
rename to packages/scaffold/helper/src/package-managers/link-workspace.ts
diff --git a/packages/sdk/helper/src/package-managers/package-manager.ts b/packages/scaffold/helper/src/package-managers/package-manager.ts
similarity index 100%
rename from packages/sdk/helper/src/package-managers/package-manager.ts
rename to packages/scaffold/helper/src/package-managers/package-manager.ts
diff --git a/packages/sdk/helper/src/plugins/local-plugin-blueprint.ts b/packages/scaffold/helper/src/plugins/local-plugin-blueprint.ts
similarity index 100%
rename from packages/sdk/helper/src/plugins/local-plugin-blueprint.ts
rename to packages/scaffold/helper/src/plugins/local-plugin-blueprint.ts
diff --git a/packages/sdk/helper/src/project/change-set.ts b/packages/scaffold/helper/src/project/change-set.ts
similarity index 100%
rename from packages/sdk/helper/src/project/change-set.ts
rename to packages/scaffold/helper/src/project/change-set.ts
diff --git a/packages/sdk/helper/src/project/npm-dependency-policy.ts b/packages/scaffold/helper/src/project/npm-dependency-policy.ts
similarity index 100%
rename from packages/sdk/helper/src/project/npm-dependency-policy.ts
rename to packages/scaffold/helper/src/project/npm-dependency-policy.ts
diff --git a/packages/sdk/helper/src/project/project-edit-session.ts b/packages/scaffold/helper/src/project/project-edit-session.ts
similarity index 100%
rename from packages/sdk/helper/src/project/project-edit-session.ts
rename to packages/scaffold/helper/src/project/project-edit-session.ts
diff --git a/packages/sdk/helper/src/project/sdk-project.ts b/packages/scaffold/helper/src/project/sdk-project.ts
similarity index 99%
rename from packages/sdk/helper/src/project/sdk-project.ts
rename to packages/scaffold/helper/src/project/sdk-project.ts
index e9302aa428..41b66fe7d0 100644
--- a/packages/sdk/helper/src/project/sdk-project.ts
+++ b/packages/scaffold/helper/src/project/sdk-project.ts
@@ -98,7 +98,7 @@ async function detectPackageManager(root: string, manifest: Readonly<PackageMani
 
 function linkedRepositoryRoot(root: string, manifest: Readonly<PackageManifest>): string | undefined {
   const spec = manifest.dependencies?.['@deepseek-ai/dsh-scripts']
-  const match = /^(?:file|link|portal):(.+)\/packages\/sdk\/scripts\/?$/.exec(spec ?? '')
+  const match = /^(?:file|link|portal):(.+)\/packages\/scaffold\/scripts\/?$/.exec(spec ?? '')
   return match?.[1] ? resolve(root, match[1]) : undefined
 }
 
diff --git a/packages/sdk/helper/src/project/types.ts b/packages/scaffold/helper/src/project/types.ts
similarity index 100%
rename from packages/sdk/helper/src/project/types.ts
rename to packages/scaffold/helper/src/project/types.ts
diff --git a/packages/sdk/helper/src/questions/clack-nested-multiselect.ts b/packages/scaffold/helper/src/questions/clack-nested-multiselect.ts
similarity index 100%
rename from packages/sdk/helper/src/questions/clack-nested-multiselect.ts
rename to packages/scaffold/helper/src/questions/clack-nested-multiselect.ts
diff --git a/packages/sdk/helper/src/questions/clack-prompt-port.ts b/packages/scaffold/helper/src/questions/clack-prompt-port.ts
similarity index 100%
rename from packages/sdk/helper/src/questions/clack-prompt-port.ts
rename to packages/scaffold/helper/src/questions/clack-prompt-port.ts
diff --git a/packages/sdk/helper/src/questions/headless-prompt-port.ts b/packages/scaffold/helper/src/questions/headless-prompt-port.ts
similarity index 100%
rename from packages/sdk/helper/src/questions/headless-prompt-port.ts
rename to packages/scaffold/helper/src/questions/headless-prompt-port.ts
diff --git a/packages/sdk/helper/src/questions/prompt-port.ts b/packages/scaffold/helper/src/questions/prompt-port.ts
similarity index 100%
rename from packages/sdk/helper/src/questions/prompt-port.ts
rename to packages/scaffold/helper/src/questions/prompt-port.ts
diff --git a/packages/sdk/helper/src/questions/question.ts b/packages/scaffold/helper/src/questions/question.ts
similarity index 100%
rename from packages/sdk/helper/src/questions/question.ts
rename to packages/scaffold/helper/src/questions/question.ts
diff --git a/packages/sdk/helper/src/templates/assets/README.md.tpl b/packages/scaffold/helper/src/templates/assets/README.md.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/README.md.tpl
rename to packages/scaffold/helper/src/templates/assets/README.md.tpl
diff --git a/packages/sdk/helper/src/templates/assets/gitignore.tpl b/packages/scaffold/helper/src/templates/assets/gitignore.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/gitignore.tpl
rename to packages/scaffold/helper/src/templates/assets/gitignore.tpl
diff --git a/packages/sdk/helper/src/templates/assets/index.ts.tpl b/packages/scaffold/helper/src/templates/assets/index.ts.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/index.ts.tpl
rename to packages/scaffold/helper/src/templates/assets/index.ts.tpl
diff --git a/packages/sdk/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl b/packages/scaffold/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
rename to packages/scaffold/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
diff --git a/packages/sdk/helper/src/templates/assets/local-plugin.ts.tpl b/packages/scaffold/helper/src/templates/assets/local-plugin.ts.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/local-plugin.ts.tpl
rename to packages/scaffold/helper/src/templates/assets/local-plugin.ts.tpl
diff --git a/packages/sdk/helper/src/templates/assets/local-tool.ts.tpl b/packages/scaffold/helper/src/templates/assets/local-tool.ts.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/local-tool.ts.tpl
rename to packages/scaffold/helper/src/templates/assets/local-tool.ts.tpl
diff --git a/packages/sdk/helper/src/templates/assets/package.json.tpl b/packages/scaffold/helper/src/templates/assets/package.json.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/package.json.tpl
rename to packages/scaffold/helper/src/templates/assets/package.json.tpl
diff --git a/packages/sdk/helper/src/templates/assets/persona.txt.tpl b/packages/scaffold/helper/src/templates/assets/persona.txt.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/persona.txt.tpl
rename to packages/scaffold/helper/src/templates/assets/persona.txt.tpl
diff --git a/packages/sdk/helper/src/templates/assets/tsconfig.base.json.tpl b/packages/scaffold/helper/src/templates/assets/tsconfig.base.json.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/tsconfig.base.json.tpl
rename to packages/scaffold/helper/src/templates/assets/tsconfig.base.json.tpl
diff --git a/packages/sdk/helper/src/templates/assets/tsdown.config.ts.tpl b/packages/scaffold/helper/src/templates/assets/tsdown.config.ts.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/tsdown.config.ts.tpl
rename to packages/scaffold/helper/src/templates/assets/tsdown.config.ts.tpl
diff --git a/packages/sdk/helper/src/templates/assets/yarnrc.yml.tpl b/packages/scaffold/helper/src/templates/assets/yarnrc.yml.tpl
similarity index 100%
rename from packages/sdk/helper/src/templates/assets/yarnrc.yml.tpl
rename to packages/scaffold/helper/src/templates/assets/yarnrc.yml.tpl
diff --git a/packages/sdk/helper/src/templates/project-template.ts b/packages/scaffold/helper/src/templates/project-template.ts
similarity index 100%
rename from packages/sdk/helper/src/templates/project-template.ts
rename to packages/scaffold/helper/src/templates/project-template.ts
diff --git a/packages/sdk/helper/src/templates/template-assets.ts b/packages/scaffold/helper/src/templates/template-assets.ts
similarity index 100%
rename from packages/sdk/helper/src/templates/template-assets.ts
rename to packages/scaffold/helper/src/templates/template-assets.ts
diff --git a/packages/sdk/helper/src/templates/text-template.ts b/packages/scaffold/helper/src/templates/text-template.ts
similarity index 100%
rename from packages/sdk/helper/src/templates/text-template.ts
rename to packages/scaffold/helper/src/templates/text-template.ts
diff --git a/packages/sdk/helper/tests/documents.spec.ts b/packages/scaffold/helper/tests/documents.spec.ts
similarity index 100%
rename from packages/sdk/helper/tests/documents.spec.ts
rename to packages/scaffold/helper/tests/documents.spec.ts
diff --git a/packages/sdk/helper/tests/headless-prompt-port.spec.ts b/packages/scaffold/helper/tests/headless-prompt-port.spec.ts
similarity index 100%
rename from packages/sdk/helper/tests/headless-prompt-port.spec.ts
rename to packages/scaffold/helper/tests/headless-prompt-port.spec.ts
diff --git a/packages/sdk/helper/tests/project.spec.ts b/packages/scaffold/helper/tests/project.spec.ts
similarity index 100%
rename from packages/sdk/helper/tests/project.spec.ts
rename to packages/scaffold/helper/tests/project.spec.ts
diff --git a/packages/sdk/helper/tests/questions.spec.ts b/packages/scaffold/helper/tests/questions.spec.ts
similarity index 100%
rename from packages/sdk/helper/tests/questions.spec.ts
rename to packages/scaffold/helper/tests/questions.spec.ts
diff --git a/packages/sdk/helper/tsconfig.json b/packages/scaffold/helper/tsconfig.json
similarity index 100%
rename from packages/sdk/helper/tsconfig.json
rename to packages/scaffold/helper/tsconfig.json
diff --git a/packages/sdk/helper/tsdown.config.ts b/packages/scaffold/helper/tsdown.config.ts
similarity index 100%
rename from packages/sdk/helper/tsdown.config.ts
rename to packages/scaffold/helper/tsdown.config.ts
diff --git a/packages/scaffold/protocol/README.i18n.yaml b/packages/scaffold/protocol/README.i18n.yaml
new file mode 100644
index 0000000000..df0623573b
--- /dev/null
+++ b/packages/scaffold/protocol/README.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 packages/scaffold/protocol/README.md
+README.md: dc42f385f6e7fd6327ca79887d3cf22d7c34ccdf
+README.zh.md: a292120be8b5b09aaadb05f9dbc272a51bd74831
diff --git a/packages/sdk/sdk-protocol/README.md b/packages/scaffold/protocol/README.md
similarity index 90%
rename from packages/sdk/sdk-protocol/README.md
rename to packages/scaffold/protocol/README.md
index 2d141e6f62..b8420eb19a 100644
--- a/packages/sdk/sdk-protocol/README.md
+++ b/packages/scaffold/protocol/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delimited JSON-RPC 2.0 transport class plus the named request, result, and notification types both wire ends speak. The package root enumerates the protocol consumer interface; source modules are not exported as deep imports. The server side is the [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) plugin; clients are [`dsh-sdk-client`](../sdk-client/README.md) (TypeScript) and the [Python SDK](../../../python/README.md) (which mirrors these shapes but does not import them). A pure library — no plugin, no Config, no registration.
+The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delimited JSON-RPC 2.0 transport class plus the named request, result, and notification types both wire ends speak. The package root enumerates the protocol consumer interface; source modules are not exported as deep imports. The server side is the [`dsh-jsonrpc`](../../scaffold/server/README.md) plugin; clients are [`dsh-sdk-client`](../client/README.md) (TypeScript) and the [Python SDK](../../../python/README.md) (which mirrors these shapes but does not import them). A pure library — no plugin, no Config, no registration.
 
 ## Transport
 
@@ -26,7 +26,7 @@ The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delim
 
 ## Model Experience
 
-None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) entry.
+None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving [`dsh-jsonrpc`](../../scaffold/server/README.md) entry.
 
 #### KV Cache effect
 
@@ -35,5 +35,5 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **No protocol-version negotiation** — the handshake carries only `serverInfo.version` (`0.0.1`, unvalidated by clients); pre-release stance, no compatibility promise.
-- **No cancel or session-close methods** — a client abandons a turn by closing the runtime process; see the [`dsh-jsonrpc` README](../../ui/jsonrpc/README.md).
+- **No cancel or session-close methods** — a client abandons a turn by closing the runtime process; see the [`dsh-jsonrpc` README](../../scaffold/server/README.md).
 - **Server→client requests are dead capability** — the transport supports them, but the server never sends one; the Python SDK's responder surface exists for future approval flows.
diff --git a/packages/sdk/sdk-protocol/README.zh.md b/packages/scaffold/protocol/README.zh.md
similarity index 100%
rename from packages/sdk/sdk-protocol/README.zh.md
rename to packages/scaffold/protocol/README.zh.md
diff --git a/packages/sdk/sdk-protocol/package.json b/packages/scaffold/protocol/package.json
similarity index 100%
rename from packages/sdk/sdk-protocol/package.json
rename to packages/scaffold/protocol/package.json
diff --git a/packages/sdk/sdk-protocol/src/index.ts b/packages/scaffold/protocol/src/index.ts
similarity index 100%
rename from packages/sdk/sdk-protocol/src/index.ts
rename to packages/scaffold/protocol/src/index.ts
diff --git a/packages/sdk/sdk-protocol/src/invariant.ts b/packages/scaffold/protocol/src/invariant.ts
similarity index 100%
rename from packages/sdk/sdk-protocol/src/invariant.ts
rename to packages/scaffold/protocol/src/invariant.ts
diff --git a/packages/sdk/sdk-protocol/src/transport.ts b/packages/scaffold/protocol/src/transport.ts
similarity index 100%
rename from packages/sdk/sdk-protocol/src/transport.ts
rename to packages/scaffold/protocol/src/transport.ts
diff --git a/packages/sdk/sdk-protocol/src/types.ts b/packages/scaffold/protocol/src/types.ts
similarity index 100%
rename from packages/sdk/sdk-protocol/src/types.ts
rename to packages/scaffold/protocol/src/types.ts
diff --git a/packages/sdk/sdk-protocol/tests/transport.spec.ts b/packages/scaffold/protocol/tests/transport.spec.ts
similarity index 100%
rename from packages/sdk/sdk-protocol/tests/transport.spec.ts
rename to packages/scaffold/protocol/tests/transport.spec.ts
diff --git a/packages/sdk/sdk-protocol/tsconfig.json b/packages/scaffold/protocol/tsconfig.json
similarity index 100%
rename from packages/sdk/sdk-protocol/tsconfig.json
rename to packages/scaffold/protocol/tsconfig.json
diff --git a/packages/sdk/scripts/README.i18n.yaml b/packages/scaffold/scripts/README.i18n.yaml
similarity index 80%
rename from packages/sdk/scripts/README.i18n.yaml
rename to packages/scaffold/scripts/README.i18n.yaml
index b148eb76ab..db65cb315f 100644
--- a/packages/sdk/scripts/README.i18n.yaml
+++ b/packages/scaffold/scripts/README.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 packages/sdk/scripts/README.md
+#   pnpm run verify-translation-pairing --write packages/scaffold/scripts/README.md
 README.md: 9a696bf5a4de9a80f0741f07a7e753733bc2f998
 README.zh.md: cf9fc2cbbe467eb86e89d9eb77e9bc34860b5a3a
diff --git a/packages/sdk/scripts/README.md b/packages/scaffold/scripts/README.md
similarity index 100%
rename from packages/sdk/scripts/README.md
rename to packages/scaffold/scripts/README.md
diff --git a/packages/sdk/scripts/README.zh.md b/packages/scaffold/scripts/README.zh.md
similarity index 100%
rename from packages/sdk/scripts/README.zh.md
rename to packages/scaffold/scripts/README.zh.md
diff --git a/packages/sdk/scripts/package.json b/packages/scaffold/scripts/package.json
similarity index 100%
rename from packages/sdk/scripts/package.json
rename to packages/scaffold/scripts/package.json
diff --git a/packages/sdk/scripts/src/args.ts b/packages/scaffold/scripts/src/args.ts
similarity index 100%
rename from packages/sdk/scripts/src/args.ts
rename to packages/scaffold/scripts/src/args.ts
diff --git a/packages/sdk/scripts/src/bin.ts b/packages/scaffold/scripts/src/bin.ts
similarity index 100%
rename from packages/sdk/scripts/src/bin.ts
rename to packages/scaffold/scripts/src/bin.ts
diff --git a/packages/sdk/scripts/src/build.ts b/packages/scaffold/scripts/src/build.ts
similarity index 100%
rename from packages/sdk/scripts/src/build.ts
rename to packages/scaffold/scripts/src/build.ts
diff --git a/packages/sdk/scripts/src/command.ts b/packages/scaffold/scripts/src/command.ts
similarity index 100%
rename from packages/sdk/scripts/src/command.ts
rename to packages/scaffold/scripts/src/command.ts
diff --git a/packages/sdk/scripts/src/config.ts b/packages/scaffold/scripts/src/config.ts
similarity index 100%
rename from packages/sdk/scripts/src/config.ts
rename to packages/scaffold/scripts/src/config.ts
diff --git a/packages/sdk/scripts/src/config/config-workflow.ts b/packages/scaffold/scripts/src/config/config-workflow.ts
similarity index 100%
rename from packages/sdk/scripts/src/config/config-workflow.ts
rename to packages/scaffold/scripts/src/config/config-workflow.ts
diff --git a/packages/sdk/scripts/src/create-plugin.ts b/packages/scaffold/scripts/src/create-plugin.ts
similarity index 100%
rename from packages/sdk/scripts/src/create-plugin.ts
rename to packages/scaffold/scripts/src/create-plugin.ts
diff --git a/packages/sdk/scripts/src/dev/tsdown-config.ts b/packages/scaffold/scripts/src/dev/tsdown-config.ts
similarity index 100%
rename from packages/sdk/scripts/src/dev/tsdown-config.ts
rename to packages/scaffold/scripts/src/dev/tsdown-config.ts
diff --git a/packages/scaffold/scripts/src/index.ts b/packages/scaffold/scripts/src/index.ts
new file mode 100644
index 0000000000..0af3ef0b30
--- /dev/null
+++ b/packages/scaffold/scripts/src/index.ts
@@ -0,0 +1,11 @@
+/**
+ * Public DeepSeek Harness SDK runtime entry points.
+ *
+ * FIXME: rename to `@deepseek-ai/dsh-sdk-scripts` before the first tagged release —
+ * the current name is indefensibly generic as a published name
+ * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ *
+ * @module @deepseek-ai/dsh-scripts
+ */
+
+export { runSDK, startSDK, type SdkBootContext } from './runtime.ts'
diff --git a/packages/sdk/scripts/src/invariant.ts b/packages/scaffold/scripts/src/invariant.ts
similarity index 100%
rename from packages/sdk/scripts/src/invariant.ts
rename to packages/scaffold/scripts/src/invariant.ts
diff --git a/packages/sdk/scripts/src/local-plugin-loader-hooks.ts b/packages/scaffold/scripts/src/local-plugin-loader-hooks.ts
similarity index 100%
rename from packages/sdk/scripts/src/local-plugin-loader-hooks.ts
rename to packages/scaffold/scripts/src/local-plugin-loader-hooks.ts
diff --git a/packages/sdk/scripts/src/runtime.ts b/packages/scaffold/scripts/src/runtime.ts
similarity index 100%
rename from packages/sdk/scripts/src/runtime.ts
rename to packages/scaffold/scripts/src/runtime.ts
diff --git a/packages/sdk/scripts/src/telemetry.ts b/packages/scaffold/scripts/src/telemetry.ts
similarity index 100%
rename from packages/sdk/scripts/src/telemetry.ts
rename to packages/scaffold/scripts/src/telemetry.ts
diff --git a/packages/sdk/scripts/src/templates/assets/config-install-failure.txt.tpl b/packages/scaffold/scripts/src/templates/assets/config-install-failure.txt.tpl
similarity index 100%
rename from packages/sdk/scripts/src/templates/assets/config-install-failure.txt.tpl
rename to packages/scaffold/scripts/src/templates/assets/config-install-failure.txt.tpl
diff --git a/packages/sdk/scripts/src/templates/assets/usage.txt.tpl b/packages/scaffold/scripts/src/templates/assets/usage.txt.tpl
similarity index 100%
rename from packages/sdk/scripts/src/templates/assets/usage.txt.tpl
rename to packages/scaffold/scripts/src/templates/assets/usage.txt.tpl
diff --git a/packages/sdk/scripts/src/templates/dsh-sdk-templates.ts b/packages/scaffold/scripts/src/templates/dsh-sdk-templates.ts
similarity index 100%
rename from packages/sdk/scripts/src/templates/dsh-sdk-templates.ts
rename to packages/scaffold/scripts/src/templates/dsh-sdk-templates.ts
diff --git a/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap b/packages/scaffold/scripts/tests/__snapshots__/config.snapshot.ts.snap
similarity index 100%
rename from packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap
rename to packages/scaffold/scripts/tests/__snapshots__/config.snapshot.ts.snap
diff --git a/packages/sdk/scripts/tests/config.snapshot.ts b/packages/scaffold/scripts/tests/config.snapshot.ts
similarity index 100%
rename from packages/sdk/scripts/tests/config.snapshot.ts
rename to packages/scaffold/scripts/tests/config.snapshot.ts
diff --git a/packages/sdk/scripts/tests/scripts.spec.ts b/packages/scaffold/scripts/tests/scripts.spec.ts
similarity index 100%
rename from packages/sdk/scripts/tests/scripts.spec.ts
rename to packages/scaffold/scripts/tests/scripts.spec.ts
diff --git a/packages/sdk/scripts/tsconfig.json b/packages/scaffold/scripts/tsconfig.json
similarity index 88%
rename from packages/sdk/scripts/tsconfig.json
rename to packages/scaffold/scripts/tsconfig.json
index d3dacea10b..2230a377ab 100644
--- a/packages/sdk/scripts/tsconfig.json
+++ b/packages/scaffold/scripts/tsconfig.json
@@ -8,7 +8,7 @@
   "references": [
     { "path": "../helper" },
     { "path": "../telemetry" },
-    { "path": "../../ui/app-boot" },
+    { "path": "../../boot/app-boot" },
     { "path": "../../../vendor/cordis" },
     { "path": "../../support/invariants" }
   ]
diff --git a/packages/sdk/scripts/tsdown.config.ts b/packages/scaffold/scripts/tsdown.config.ts
similarity index 100%
rename from packages/sdk/scripts/tsdown.config.ts
rename to packages/scaffold/scripts/tsdown.config.ts
diff --git a/packages/scaffold/server/README.i18n.yaml b/packages/scaffold/server/README.i18n.yaml
new file mode 100644
index 0000000000..0672ad22a6
--- /dev/null
+++ b/packages/scaffold/server/README.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 packages/scaffold/server/README.md
+README.md: 7ada4fbe6a53e90fcd45c20d9472cb87dbf6b4cf
+README.zh.md: b8362f7762b963ed6caff1b2ba87421152ecb483
diff --git a/packages/ui/jsonrpc/README.md b/packages/scaffold/server/README.md
similarity index 95%
rename from packages/ui/jsonrpc/README.md
rename to packages/scaffold/server/README.md
index 9cd4876b52..0afb3a38ec 100644
--- a/packages/ui/jsonrpc/README.md
+++ b/packages/scaffold/server/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The `jsonrpc` plugin serves newline-delimited JSON-RPC over stdio so out-of-process SDK clients can drive harness agents. [`HarnessSdkServer`](src/server.ts) owns the protocol methods and notifications; the transport and the named wire types live in [`dsh-sdk-protocol`](../../sdk/sdk-protocol/README.md), shared with the client SDKs; [`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) supplies the surrounding `cordis.yml` application.
+The `jsonrpc` plugin serves newline-delimited JSON-RPC over stdio so out-of-process SDK clients can drive harness agents. [`HarnessSdkServer`](src/server.ts) owns the protocol methods and notifications; the transport and the named wire types live in [`dsh-sdk-protocol`](../../scaffold/protocol/README.md), shared with the client SDKs; [`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) supplies the surrounding `cordis.yml` application.
 
 ## Wiring
 
diff --git a/packages/ui/jsonrpc/README.zh.md b/packages/scaffold/server/README.zh.md
similarity index 95%
rename from packages/ui/jsonrpc/README.zh.md
rename to packages/scaffold/server/README.zh.md
index a2b979da44..5305434abb 100644
--- a/packages/ui/jsonrpc/README.zh.md
+++ b/packages/scaffold/server/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`jsonrpc` 插件通过 stdio 提供以换行符分隔的 JSON-RPC，使进程外 SDK 客户端能够驱动 harness agent（智能体）。[`HarnessSdkServer`](src/server.ts) 负责协议方法和通知；传输与具名协议类型位于 [`dsh-sdk-protocol`](../../sdk/sdk-protocol/README.md)，与客户端 SDK 共享；[`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) 提供外围的 `cordis.yml` 应用。
+`jsonrpc` 插件通过 stdio 提供以换行符分隔的 JSON-RPC，使进程外 SDK 客户端能够驱动 harness agent（智能体）。[`HarnessSdkServer`](src/server.ts) 负责协议方法和通知；传输与具名协议类型位于 [`dsh-sdk-protocol`](../../scaffold/protocol/README.md)，与客户端 SDK 共享；[`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) 提供外围的 `cordis.yml` 应用。
 
 ## 组装
 
diff --git a/packages/ui/jsonrpc/package.json b/packages/scaffold/server/package.json
similarity index 100%
rename from packages/ui/jsonrpc/package.json
rename to packages/scaffold/server/package.json
diff --git a/packages/ui/jsonrpc/src/index.ts b/packages/scaffold/server/src/index.ts
similarity index 92%
rename from packages/ui/jsonrpc/src/index.ts
rename to packages/scaffold/server/src/index.ts
index 423f338877..9985cadfb4 100644
--- a/packages/ui/jsonrpc/src/index.ts
+++ b/packages/scaffold/server/src/index.ts
@@ -6,6 +6,10 @@
  * owns EOF and signal exits. Keep named plugin exports with no default export so
  * Loader `unwrapExports` preserves `name`, `inject`, `Config`, and `apply`.
  *
+ * FIXME: rename to `@deepseek-ai/dsh-sdk-server` before the first tagged release —
+ * the current name says the wire encoding, not the role; it is the server half of
+ * the SDK protocol ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ *
  * @module @deepseek-ai/dsh-jsonrpc
  */
 
diff --git a/packages/ui/jsonrpc/src/invariant.ts b/packages/scaffold/server/src/invariant.ts
similarity index 100%
rename from packages/ui/jsonrpc/src/invariant.ts
rename to packages/scaffold/server/src/invariant.ts
diff --git a/packages/ui/jsonrpc/src/server.ts b/packages/scaffold/server/src/server.ts
similarity index 100%
rename from packages/ui/jsonrpc/src/server.ts
rename to packages/scaffold/server/src/server.ts
diff --git a/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts b/packages/scaffold/server/tests/built-scope-carrier.e2e.ts
similarity index 98%
rename from packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts
rename to packages/scaffold/server/tests/built-scope-carrier.e2e.ts
index 1de16660a8..b3519110b5 100644
--- a/packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts
+++ b/packages/scaffold/server/tests/built-scope-carrier.e2e.ts
@@ -36,7 +36,7 @@ const [
   load("packages/examples/agent-spine-demo/lib/index.js"),
   load("packages/subagent/subagent/lib/index.js"),
   load("packages/session/session-persistence-jsonl/lib/index.js"),
-  load("packages/ui/jsonrpc/lib/index.js"),
+  load("packages/scaffold/server/lib/index.js"),
   load("packages/core/session/lib/index.js"),
 ]);
 
diff --git a/packages/ui/jsonrpc/tests/plugin-apply.spec.ts b/packages/scaffold/server/tests/plugin-apply.spec.ts
similarity index 100%
rename from packages/ui/jsonrpc/tests/plugin-apply.spec.ts
rename to packages/scaffold/server/tests/plugin-apply.spec.ts
diff --git a/packages/ui/jsonrpc/tests/plugin-shape.spec.ts b/packages/scaffold/server/tests/plugin-shape.spec.ts
similarity index 100%
rename from packages/ui/jsonrpc/tests/plugin-shape.spec.ts
rename to packages/scaffold/server/tests/plugin-shape.spec.ts
diff --git a/packages/ui/jsonrpc/tests/server.spec.ts b/packages/scaffold/server/tests/server.spec.ts
similarity index 100%
rename from packages/ui/jsonrpc/tests/server.spec.ts
rename to packages/scaffold/server/tests/server.spec.ts
diff --git a/packages/ui/jsonrpc/tsconfig.json b/packages/scaffold/server/tsconfig.json
similarity index 93%
rename from packages/ui/jsonrpc/tsconfig.json
rename to packages/scaffold/server/tsconfig.json
index 00ac7000e6..56419b6b84 100644
--- a/packages/ui/jsonrpc/tsconfig.json
+++ b/packages/scaffold/server/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../sdk/sdk-protocol"
+      "path": "../protocol"
     },
     {
       "path": "../../subagent/subagent"
diff --git a/packages/sdk/telemetry/README.i18n.yaml b/packages/scaffold/telemetry/README.i18n.yaml
similarity index 80%
rename from packages/sdk/telemetry/README.i18n.yaml
rename to packages/scaffold/telemetry/README.i18n.yaml
index 1604b40bf4..4d70fce157 100644
--- a/packages/sdk/telemetry/README.i18n.yaml
+++ b/packages/scaffold/telemetry/README.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 packages/sdk/telemetry/README.md
+#   pnpm run verify-translation-pairing --write packages/scaffold/telemetry/README.md
 README.md: c87735a93e7659f2913f4dd325176a8ae40cf29b
 README.zh.md: 24d6e72d988f94cdbc6aa01607edbfc105213267
diff --git a/packages/sdk/telemetry/README.md b/packages/scaffold/telemetry/README.md
similarity index 100%
rename from packages/sdk/telemetry/README.md
rename to packages/scaffold/telemetry/README.md
diff --git a/packages/sdk/telemetry/README.zh.md b/packages/scaffold/telemetry/README.zh.md
similarity index 100%
rename from packages/sdk/telemetry/README.zh.md
rename to packages/scaffold/telemetry/README.zh.md
diff --git a/packages/sdk/telemetry/package.json b/packages/scaffold/telemetry/package.json
similarity index 100%
rename from packages/sdk/telemetry/package.json
rename to packages/scaffold/telemetry/package.json
diff --git a/packages/sdk/telemetry/src/anonymous-id.ts b/packages/scaffold/telemetry/src/anonymous-id.ts
similarity index 100%
rename from packages/sdk/telemetry/src/anonymous-id.ts
rename to packages/scaffold/telemetry/src/anonymous-id.ts
diff --git a/packages/sdk/telemetry/src/consent-resolver.ts b/packages/scaffold/telemetry/src/consent-resolver.ts
similarity index 100%
rename from packages/sdk/telemetry/src/consent-resolver.ts
rename to packages/scaffold/telemetry/src/consent-resolver.ts
diff --git a/packages/sdk/telemetry/src/index.ts b/packages/scaffold/telemetry/src/index.ts
similarity index 82%
rename from packages/sdk/telemetry/src/index.ts
rename to packages/scaffold/telemetry/src/index.ts
index 107956fa39..17ea1d02c7 100644
--- a/packages/sdk/telemetry/src/index.ts
+++ b/packages/scaffold/telemetry/src/index.ts
@@ -7,6 +7,10 @@
  * the launcher command dispatch and the helper feature catalog lives outside
  * this package.
  *
+ * FIXME: rename to `@deepseek-ai/dsh-sdk-telemetry` before the first tagged release —
+ * the current name collides with the `dsh-session-telemetry` family; this is
+ * launcher-side SDK telemetry ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ *
  * @module @deepseek-ai/dsh-telemetry
  */
 
diff --git a/packages/sdk/telemetry/src/invariant.ts b/packages/scaffold/telemetry/src/invariant.ts
similarity index 100%
rename from packages/sdk/telemetry/src/invariant.ts
rename to packages/scaffold/telemetry/src/invariant.ts
diff --git a/packages/sdk/telemetry/src/payload.ts b/packages/scaffold/telemetry/src/payload.ts
similarity index 100%
rename from packages/sdk/telemetry/src/payload.ts
rename to packages/scaffold/telemetry/src/payload.ts
diff --git a/packages/sdk/telemetry/src/reporter.ts b/packages/scaffold/telemetry/src/reporter.ts
similarity index 100%
rename from packages/sdk/telemetry/src/reporter.ts
rename to packages/scaffold/telemetry/src/reporter.ts
diff --git a/packages/sdk/telemetry/src/secret-redactor.ts b/packages/scaffold/telemetry/src/secret-redactor.ts
similarity index 100%
rename from packages/sdk/telemetry/src/secret-redactor.ts
rename to packages/scaffold/telemetry/src/secret-redactor.ts
diff --git a/packages/sdk/telemetry/tests/anonymous-id.spec.ts b/packages/scaffold/telemetry/tests/anonymous-id.spec.ts
similarity index 100%
rename from packages/sdk/telemetry/tests/anonymous-id.spec.ts
rename to packages/scaffold/telemetry/tests/anonymous-id.spec.ts
diff --git a/packages/sdk/telemetry/tests/consent-resolver.spec.ts b/packages/scaffold/telemetry/tests/consent-resolver.spec.ts
similarity index 100%
rename from packages/sdk/telemetry/tests/consent-resolver.spec.ts
rename to packages/scaffold/telemetry/tests/consent-resolver.spec.ts
diff --git a/packages/sdk/telemetry/tests/payload.spec.ts b/packages/scaffold/telemetry/tests/payload.spec.ts
similarity index 100%
rename from packages/sdk/telemetry/tests/payload.spec.ts
rename to packages/scaffold/telemetry/tests/payload.spec.ts
diff --git a/packages/sdk/telemetry/tests/reporter.spec.ts b/packages/scaffold/telemetry/tests/reporter.spec.ts
similarity index 100%
rename from packages/sdk/telemetry/tests/reporter.spec.ts
rename to packages/scaffold/telemetry/tests/reporter.spec.ts
diff --git a/packages/sdk/telemetry/tests/secret-redactor.spec.ts b/packages/scaffold/telemetry/tests/secret-redactor.spec.ts
similarity index 100%
rename from packages/sdk/telemetry/tests/secret-redactor.spec.ts
rename to packages/scaffold/telemetry/tests/secret-redactor.spec.ts
diff --git a/packages/sdk/telemetry/tsconfig.json b/packages/scaffold/telemetry/tsconfig.json
similarity index 100%
rename from packages/sdk/telemetry/tsconfig.json
rename to packages/scaffold/telemetry/tsconfig.json
diff --git a/packages/sdk/README.zh.md b/packages/sdk/README.zh.md
deleted file mode 100644
index 003383c5f6..0000000000
--- a/packages/sdk/README.zh.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# SDK 包
-
-[English](README.md) | 中文
-
-本分组包含 Harness 项目的开发者工具，以及从另一个进程驱动 Harness 运行时的客户端栈。
-
-| 包 | 职责 |
-|---|---|
-| [`helper/`](helper/README.md) | 提供共享的项目编辑领域 |
-| [`scripts/`](scripts/README.md) | 提供 `dsh-sdk` 项目命令 |
-| [`create-sdk/`](create-sdk/README.md) | 创建新的 SDK 项目 |
-| [`sdk-protocol/`](sdk-protocol/README.md) | 定义 SDK 运行时协议格式 |
-| [`sdk-client/`](sdk-client/README.md) | 通过 TypeScript 客户端 API 驱动 Harness 运行时 |
-| [`telemetry/`](telemetry/README.md) | 提供启动器遥测、同意和脱敏原语 |
-
-`@deepseek-ai/create-sdk` 遵循 npm 的 scoped initializer 命名约定；其他包遵循仓库的 `@deepseek-ai/dsh-*` 约定。参见[开发者项目工作流](../../.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md)、[项目编辑架构](../../.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md)和 [TypeScript SDK 设计](../../.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md)。
diff --git a/packages/sdk/scripts/src/index.ts b/packages/sdk/scripts/src/index.ts
deleted file mode 100644
index 5180f885c8..0000000000
--- a/packages/sdk/scripts/src/index.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-/**
- * Public DeepSeek Harness SDK runtime entry points.
- *
- * @module @deepseek-ai/dsh-scripts
- */
-
-export { runSDK, startSDK, type SdkBootContext } from './runtime.ts'
diff --git a/packages/sdk/sdk-protocol/README.i18n.yaml b/packages/sdk/sdk-protocol/README.i18n.yaml
deleted file mode 100644
index f878b9fd63..0000000000
--- a/packages/sdk/sdk-protocol/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/sdk/sdk-protocol/README.md
-README.md: 2d141e6f62ac0d324933996c282a2d0380af29f2
-README.zh.md: bc459f8817c9477a451015f7629168e246ee531c
diff --git a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
index 3598c77d31..246d702892 100644
--- a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
+++ b/packages/subagent/subagent-dsh-sdk/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/subagent/subagent-dsh-sdk/README.md
-README.md: c0e2f4e9ece366e28492e32d97afa533fd948141
-README.zh.md: 4cf6c58fff44b1c11cf0a6c321da2c02d52bb8c9
+README.md: 0bbcfa105ecf024a2492d39d3bf8d28956110050
+README.zh.md: ffb1b8f4cddca4566a20593bdac54801ad8db38f
diff --git a/packages/subagent/subagent-dsh-sdk/README.md b/packages/subagent/subagent-dsh-sdk/README.md
index c0e2f4e9ec..0bbcfa105e 100644
--- a/packages/subagent/subagent-dsh-sdk/README.md
+++ b/packages/subagent/subagent-dsh-sdk/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The SDK provider runs each subagent as a complete DeepSeek Harness runtime in a fresh subprocess, driven over stdio JSON-RPC through the [TypeScript SDK client](../../sdk/sdk-client/README.md). It is the second out-of-process backend beside [`subagent-acp`](../subagent-acp/README.md), differing in the wire and the child contract: the ACP backend drives any Agent Client Protocol agent; this backend drives specifically a harness SDK runtime (`dsh-jsonrpc-agent` bin or packaged executable), so the child is a full peer harness — own `cordis.yml`-decided composition, session persistence, model route, and tools.
+The SDK provider runs each subagent as a complete DeepSeek Harness runtime in a fresh subprocess, driven over stdio JSON-RPC through the [TypeScript SDK client](../../scaffold/client/README.md). It is the second out-of-process backend beside [`subagent-acp`](../subagent-acp/README.md), differing in the wire and the child contract: the ACP backend drives any Agent Client Protocol agent; this backend drives specifically a harness SDK runtime (`dsh-jsonrpc-agent` bin or packaged executable), so the child is a full peer harness — own `cordis.yml`-decided composition, session persistence, model route, and tools.
 
 ## Start and ownership
 
diff --git a/packages/subagent/subagent-dsh-sdk/README.zh.md b/packages/subagent/subagent-dsh-sdk/README.zh.md
index 4cf6c58fff..ffb1b8f4cd 100644
--- a/packages/subagent/subagent-dsh-sdk/README.zh.md
+++ b/packages/subagent/subagent-dsh-sdk/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../sdk/sdk-client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程契约：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
+SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../scaffold/client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程契约：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
 
 ## 启动与所有权
 
diff --git a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
index 5603e0e9a0..e42a76c90c 100644
--- a/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
+++ b/packages/subagent/subagent-dsh-sdk/tests/subagent-dsh-sdk.spec.ts
@@ -24,7 +24,7 @@ import {
   type SdkRunSpec,
 } from '../src/run.ts'
 
-const fakeRuntime = fileURLToPath(new URL('../../../sdk/sdk-client/tests/fake-runtime.ts', import.meta.url))
+const fakeRuntime = fileURLToPath(new URL('../../../scaffold/client/tests/fake-runtime.ts', import.meta.url))
 
 /** A parent Agent stub. The SDK backend reads exactly one thing off it: the session header's cwd (the workspace its child inherits). */
 const fakeParent = { id: 'parent', session: { header: { cwd: process.cwd() } } } as unknown as Agent
diff --git a/packages/subagent/subagent-dsh-sdk/tsconfig.json b/packages/subagent/subagent-dsh-sdk/tsconfig.json
index 79ff03f1a4..2b9aa29e21 100644
--- a/packages/subagent/subagent-dsh-sdk/tsconfig.json
+++ b/packages/subagent/subagent-dsh-sdk/tsconfig.json
@@ -27,10 +27,10 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../sdk/sdk-client"
+      "path": "../../scaffold/client"
     },
     {
-      "path": "../../sdk/sdk-protocol"
+      "path": "../../scaffold/protocol"
     },
     {
       "path": "../subagent"
diff --git a/packages/subagent/subagent-inprocess/tsconfig.json b/packages/subagent/subagent-inprocess/tsconfig.json
index 22c00b3a94..23406e362e 100644
--- a/packages/subagent/subagent-inprocess/tsconfig.json
+++ b/packages/subagent/subagent-inprocess/tsconfig.json
@@ -39,7 +39,7 @@
       "path": "../../support/invariants"
     },
     {
-      "path": "../../ui/user-approval"
+      "path": "../../interaction/user-approval"
     }
   ]
 }
diff --git a/packages/typert/generator/tests/type-model.spec.ts b/packages/typert/generator/tests/type-model.spec.ts
index 40a91e3ef5..e1b5d99de9 100644
--- a/packages/typert/generator/tests/type-model.spec.ts
+++ b/packages/typert/generator/tests/type-model.spec.ts
@@ -419,7 +419,7 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
 
   it('rejects relative imports across face boundaries', () => {
     const root = copyFixture('typert-relative-face-')
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     const source = readFileSync(sourcePath, 'utf8')
       .replace("from '@fixture/host'", "from '../../host/src/index.ts'")
     writeFileSync(sourcePath, source)
@@ -435,7 +435,7 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
       join(root, 'packages/host/src/private.ts'),
       'export interface PrivateHost { readonly value: string }\n',
     )
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     const source = readFileSync(sourcePath, 'utf8')
       .replace(
         "import type { HostAgent, Payload } from '@fixture/host'",
@@ -458,7 +458,7 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
       join(root, 'packages/host/src/private.ts'),
       'export interface PrivateHost { readonly value: string }\n',
     )
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     writeFileSync(sourcePath, [
       readFileSync(sourcePath, 'utf8'),
       "export type { PrivateHost } from '@fixture/host/private'",
@@ -472,7 +472,7 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
 
   it('rejects cross-face namespace re-exports until the model has a namespace target', () => {
     const root = copyFixture('typert-namespace-reexport-')
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     writeFileSync(sourcePath, [
       readFileSync(sourcePath, 'utf8'),
       "export type * as HostNamespace from '@fixture/host'",
@@ -487,10 +487,10 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
   it('ignores cross-face namespace exports that are not package exports', () => {
     const root = copyFixture('typert-private-namespace-reexport-')
     writeFileSync(
-      join(root, 'packages/client/src/internal.ts'),
+      join(root, 'packages/client', 'src/internal.ts'),
       "export type * as HiddenHostNamespace from '@fixture/host'\n",
     )
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     writeFileSync(sourcePath, [
       "import './internal.ts'",
       readFileSync(sourcePath, 'utf8'),
@@ -503,7 +503,7 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
 
   it('records public symbols from explicit cross-face star re-exports', () => {
     const root = copyFixture('typert-star-reexport-')
-    const sourcePath = join(root, 'packages/client/src/index.ts')
+    const sourcePath = join(root, 'packages/client', 'src/index.ts')
     writeFileSync(
       sourcePath,
       readFileSync(sourcePath, 'utf8')
@@ -1138,7 +1138,7 @@ describe('WorkspaceTypertGenerator', { timeout: 60_000 }, () => {
 
   it('rejects a public Typert subpath that points outside the root-level face artifact', () => {
     const root = copyFixture('typert-artifact-path-')
-    const manifestPath = join(root, 'packages/client/package.json')
+    const manifestPath = join(root, 'packages/client', 'package.json')
     const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as {
       exports: Record<string, { types: string; default: string }>
     }
@@ -1154,7 +1154,7 @@ describe('WorkspaceTypertGenerator', { timeout: 60_000 }, () => {
 
   it('rejects absent Typert exports and package file entries', () => {
     const noSubpathRoot = copyFixture('typert-missing-artifact-export-')
-    const noSubpathManifest = join(noSubpathRoot, 'packages/client/package.json')
+    const noSubpathManifest = join(noSubpathRoot, 'packages/client', 'package.json')
     const noSubpath = JSON.parse(readFileSync(noSubpathManifest, 'utf8')) as Record<string, unknown>
     noSubpath.exports = './lib/index.js'
     writeFileSync(noSubpathManifest, `${JSON.stringify(noSubpath, null, 2)}\n`)
@@ -1163,7 +1163,7 @@ describe('WorkspaceTypertGenerator', { timeout: 60_000 }, () => {
     )
 
     const invalidSubpathRoot = copyFixture('typert-invalid-artifact-export-')
-    const invalidSubpathManifest = join(invalidSubpathRoot, 'packages/client/package.json')
+    const invalidSubpathManifest = join(invalidSubpathRoot, 'packages/client', 'package.json')
     const invalidSubpath = JSON.parse(readFileSync(invalidSubpathManifest, 'utf8')) as {
       exports: Record<string, unknown>
     }
@@ -1174,7 +1174,7 @@ describe('WorkspaceTypertGenerator', { timeout: 60_000 }, () => {
     )
 
     const noFilesRoot = copyFixture('typert-missing-artifact-files-')
-    const noFilesManifest = join(noFilesRoot, 'packages/client/package.json')
+    const noFilesManifest = join(noFilesRoot, 'packages/client', 'package.json')
     const noFiles = JSON.parse(readFileSync(noFilesManifest, 'utf8')) as Record<string, unknown>
     delete noFiles.files
     writeFileSync(noFilesManifest, `${JSON.stringify(noFiles, null, 2)}\n`)
diff --git a/packages/ui/jsonrpc/README.i18n.yaml b/packages/ui/jsonrpc/README.i18n.yaml
deleted file mode 100644
index d81f54f405..0000000000
--- a/packages/ui/jsonrpc/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/ui/jsonrpc/README.md
-README.md: 9cd4876b52f9527745b27041eb2555408c73fabd
-README.zh.md: a2b979da448c04c0578382889be2ae3ea6076166
diff --git a/packages/ui/permission/README.i18n.yaml b/packages/ui/permission/README.i18n.yaml
deleted file mode 100644
index cb48934488..0000000000
--- a/packages/ui/permission/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/ui/permission/README.md
-README.md: 4f7f560bb81eaad3b6b95b2742432fa252682d5a
-README.zh.md: d45f89e243ce2d8f6bb08943fb7e776ced106b5a
diff --git a/packages/ui/user-interaction/README.i18n.yaml b/packages/ui/user-interaction/README.i18n.yaml
deleted file mode 100644
index 1da849ed9b..0000000000
--- a/packages/ui/user-interaction/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/ui/user-interaction/README.md
-README.md: cba015e782623b3a5adf018303823577a0b96774
-README.zh.md: a5f944850c5ac4e05da59e8478167eef91796610
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 2c347613e8..08019b567e 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -275,7 +275,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   ProjectionChangeListener: 'change-feed listener contract is owned by packages/session/session-projection/src/index.ts',
   ProjectionSnapshot: 'watermark snapshot shape is owned by packages/session/session-projection/src/index.ts',
   ProjectionCheckpoint: 'persisted checkpoint row map is owned by packages/session/session-projection/src/index.ts',
-  CommandExecution: 'executor return contract is owned by packages/ui/commands/src/index.ts',
+  CommandExecution: 'executor return contract is owned by packages/interaction/commands/src/index.ts',
   TypertContribution: 'registry contribution contract is owned by packages/typert/registry/README.md',
   TypertFace: 'registry face identity is owned by packages/typert/registry/README.md',
   TypertPackageFilter: 'registry package query filter is owned by packages/typert/registry/README.md',
@@ -295,10 +295,10 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
   InvokeRemoteRequest: 'gateway invocation contract is owned by packages/api/gateway/README.md',
-  PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
-  PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
-  KnobState: 'projection unit state shape is owned by packages/ui/permission/README.md',
-  PermissionSelect: 'permissions projection payload is owned by packages/ui/permission/src/types.ts',
+  PresetOption: 'deployment menu metadata is owned by packages/interaction/permission/README.md',
+  PresetSpec: 'deployment preset composition is owned by packages/interaction/permission/README.md',
+  KnobState: 'projection unit state shape is owned by packages/interaction/permission/README.md',
+  PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
   ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
   Sandbox: 'external E2B SDK handle is owned by packages/e2b/e2b/README.md',
diff --git a/scripts/gen-third-party-notices.spec.ts b/scripts/gen-third-party-notices.spec.ts
index 8299114ff5..c9b1f41dbf 100644
--- a/scripts/gen-third-party-notices.spec.ts
+++ b/scripts/gen-third-party-notices.spec.ts
@@ -70,7 +70,7 @@ describe('tierExternalDeps', () => {
   it('keeps a package runtime when any shipping area declares it, and excludes workspace links', () => {
     const { manifests, names } = workspace({
       'package.json': { devDependencies: { shared: '^1' } },
-      'packages/ui/tui/package.json': { name: '@deepseek-ai/dsh-tui', dependencies: { shared: '^1', '@deepseek-ai/dsh-cli': 'workspace:^' } },
+      'packages/interaction/tui/package.json': { name: '@deepseek-ai/dsh-tui', dependencies: { shared: '^1', '@deepseek-ai/dsh-cli': 'workspace:^' } },
       'apps/cli/package.json': { name: '@deepseek-ai/dsh-cli' },
     })
 
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index b59aafe5f0..06475808e1 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -154,7 +154,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
   {
     pkg: '@deepseek-ai/dsh-tool-ask-user',
     dir: 'tool-ask-user',
-    source: 'packages/ui/tool-ask-user/src/index.ts',
+    source: 'packages/interaction/tool-ask-user/src/index.ts',
     requires: ['ctx.tools', 'ctx.userInteraction'],
     writes: ['tool/call', 'tool/result after a UI/provider answers the question'],
     async mount(ctx) {
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 258b70f87d..d99889d28b 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -619,7 +619,7 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'apps/cli/tests/built-bin.e2e.ts',
     'packages/examples/acp-demo/tests/built-bin.e2e.ts',
     'packages/host/directory-picker-native/tests/built-worker.e2e.ts',
-    'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts',
+    'packages/scaffold/server/tests/built-scope-carrier.e2e.ts',
     'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
     'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
     'packages/api/remotes/tests/built-lib.e2e.ts',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index e4eaf15398..903172e48f 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -234,32 +234,32 @@
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "CommandInputDescriptor",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "CommandDefinition",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "CommandInvocation",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "CommandResult",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "CommandDescriptor",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/commands.md",
       "symbol": "ParsedCommand",
-      "source": "packages/ui/commands/src/index.ts"
+      "source": "packages/interaction/commands/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/system-prompt.md",
@@ -733,62 +733,62 @@
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionOption",
-      "source": "packages/ui/user-interaction/src/types.ts"
+      "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionIntent",
-      "source": "packages/ui/user-interaction/src/types.ts"
+      "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionItem",
-      "source": "packages/ui/user-interaction/src/types.ts"
+      "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionRequest",
-      "source": "packages/ui/user-interaction/src/index.ts"
+      "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionAnswerItem",
-      "source": "packages/ui/user-interaction/src/types.ts"
+      "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "AskUserQuestionAnswer",
-      "source": "packages/ui/user-interaction/src/types.ts"
+      "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "UserInteractionProvider",
-      "source": "packages/ui/user-interaction/src/index.ts"
+      "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/user-interaction.md",
       "symbol": "UserInteractionError",
-      "source": "packages/ui/user-interaction/src/index.ts"
+      "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/approval.md",
       "symbol": "ApprovalRequestId",
-      "source": "packages/ui/user-approval/src/types.ts"
+      "source": "packages/interaction/user-approval/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/approval.md",
       "symbol": "ApprovalOutcome",
-      "source": "packages/ui/user-approval/src/types.ts"
+      "source": "packages/interaction/user-approval/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/approval.md",
       "symbol": "ApprovalPolicy",
-      "source": "packages/ui/user-approval/src/index.ts"
+      "source": "packages/interaction/user-approval/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/approval.md",
       "symbol": "ApprovalRequest",
-      "source": "packages/ui/user-approval/src/index.ts"
+      "source": "packages/interaction/user-approval/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/bash.md",
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 5930d39e26..a0eec4960f 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -103,12 +103,12 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/e2b/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/subprocess/subprocess-local': { kind: 'indirect', reason: 'The spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
-  'packages/sdk/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
-  'packages/sdk/helper': { kind: 'none', reason: 'The project domain edits files and registers no live agent or model surface.' },
-  'packages/sdk/scripts': { kind: 'indirect', reason: 'The launcher delegates model context to the loaded project plugin tree.' },
-  'packages/sdk/sdk-client': { kind: 'none', reason: 'Client-process library; the model surface lives in the spawned runtime\'s composed plugins.' },
-  'packages/sdk/sdk-protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model surface.' },
-  'packages/sdk/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' },
+  'packages/scaffold/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
+  'packages/scaffold/helper': { kind: 'none', reason: 'The project domain edits files and registers no live agent or model surface.' },
+  'packages/scaffold/scripts': { kind: 'indirect', reason: 'The launcher delegates model context to the loaded project plugin tree.' },
+  'packages/scaffold/client': { kind: 'none', reason: 'Client-process library; the model surface lives in the spawned runtime\'s composed plugins.' },
+  'packages/scaffold/protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model surface.' },
+  'packages/scaffold/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' },
   'packages/session/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers no model surface.' },
   'packages/session/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers no model surface.' },
   'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' },
@@ -138,10 +138,10 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
   'packages/tasks/tasks-local': { kind: 'indirect', reason: 'The registry backend delegates model rendering to producer plugins and dsh-tool-tasks.' },
   'packages/examples/acp-demo': { kind: 'indirect', reason: 'The app bundle delegates request composition to dsh-agent-spine-demo and dsh-acp.' },
-  'packages/ui/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
+  'packages/boot/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
   'packages/examples/jsonrpc-demo': { kind: 'indirect', reason: 'Only the externally configured plugin tree contributes model context.' },
-  'packages/ui/permission': { kind: 'indirect', reason: 'The service writes mechanism events rendered by dsh-user-approval and dsh-tool-bash.' },
-  'packages/ui/user-interaction': { kind: 'indirect', reason: 'Model-facing consumers render provider answers and seam errors.' },
+  'packages/interaction/permission': { kind: 'indirect', reason: 'The service writes mechanism events rendered by dsh-user-approval and dsh-tool-bash.' },
+  'packages/interaction/user-interaction': { kind: 'indirect', reason: 'Model-facing consumers render provider answers and seam errors.' },
   'packages/util/timeout': { kind: 'indirect', reason: 'Only timeout consumers render timeout outcomes.' },
   'packages/util/retention': { kind: 'indirect', reason: 'Only retention consumers render retained content and omission metadata.' },
   'packages/util/native-command': { kind: 'none', reason: 'The host-side subprocess runner registers no model surface.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index e09ab93743..b748020e11 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -70,12 +70,13 @@
       "@deepseek-ai/dsh-llm/brand": ["./packages/llm/llm/src/brand.ts"],
       "@deepseek-ai/dsh-llm-retry/types": ["./packages/llm/llm-retry/src/types.ts"],
       "@deepseek-ai/dsh-llm/message": ["./packages/llm/llm/src/message.ts"],
-      "@deepseek-ai/dsh-commands/brand": ["./packages/ui/commands/src/brand.ts"],
+      "@deepseek-ai/dsh-commands/brand": ["./packages/interaction/commands/src/brand.ts"],
       "@deepseek-ai/dsh-compact/checkpoint": ["./packages/compact/compact/src/checkpoint.ts"],
       "@deepseek-ai/dsh-tools/presentation": ["./packages/core/tools/src/presentation.ts"],
       "@deepseek-ai/dsh-tool-subagent-control/list-agents": ["./packages/subagent/tool-subagent-control/src/list-agents.ts"],
-      "@deepseek-ai/dsh-user-approval/types": ["./packages/ui/user-approval/src/types.ts"],
-      "@deepseek-ai/dsh-user-interaction/types": ["./packages/ui/user-interaction/src/types.ts"],
+      "@deepseek-ai/dsh-user-approval/types": ["./packages/interaction/user-approval/src/types.ts"],
+      "@deepseek-ai/dsh-user-interaction/types": ["./packages/interaction/user-interaction/src/types.ts"],
+      "@deepseek-ai/dsh-agent/brand": ["./packages/core/agent/src/brand.ts"],
       "@deepseek-ai/dsh-agent/invariant": ["./packages/core/agent/src/invariant.ts"],
       "@deepseek-ai/dsh-scope/invariant": ["./packages/core/scope/src/invariant.ts"],
       "@deepseek-ai/dsh-agent-loop/invariant": ["./packages/core/agent-loop/src/invariant.ts"],
@@ -113,8 +114,9 @@
         "./packages/acp/*/src/invariant.ts",
         "./packages/storage/*/src/invariant.ts",
         "./packages/workspace/*/src/invariant.ts",
-        "./packages/sdk/*/src/invariant.ts",
-        "./packages/ui/*/src/invariant.ts",
+        "./packages/scaffold/*/src/invariant.ts",
+        "./packages/interaction/*/src/invariant.ts",
+        "./packages/boot/*/src/invariant.ts",
         "./packages/examples/*/src/invariant.ts",
         "./packages/util/*/src/invariant.ts",
         "./packages/mcp/*/src/invariant.ts",
@@ -179,6 +181,12 @@
       "@deepseek-ai/dsh-client-ui-models": ["./packages/client/ui-models/src"],
       "@deepseek-ai/dsh-client-locale": ["./packages/client/locale/src"],
       "@deepseek-ai/dsh-client-web": ["./packages/client/web/src"],
+      // scaffold/ folders are role-named without the sdk- prefix (folder ≠ npm
+      // suffix), so the generic wildcard cannot map these three; the npm-side
+      // renames that restore symmetry are FIXME-tracked in the regrouping note.
+      "@deepseek-ai/dsh-sdk-client": ["./packages/scaffold/client/src"],
+      "@deepseek-ai/dsh-sdk-protocol": ["./packages/scaffold/protocol/src"],
+      "@deepseek-ai/dsh-jsonrpc": ["./packages/scaffold/server/src"],
       "@deepseek-ai/dsh-*": [
         "./packages/core/*/src",
         "./packages/prompt/*/src",
@@ -215,8 +223,9 @@
         "./packages/acp/*/src",
         "./packages/storage/*/src",
         "./packages/workspace/*/src",
-        "./packages/sdk/*/src",
-        "./packages/ui/*/src",
+        "./packages/scaffold/*/src",
+        "./packages/interaction/*/src",
+        "./packages/boot/*/src",
         "./packages/examples/*/src",
         "./packages/util/*/src",
         "./packages/mcp/*/src",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 0f44c4b7de..c1cc0705cf 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -138,7 +138,7 @@
     { "path": "./packages/session/session-telemetry-otel" },
     { "path": "./packages/core/system-prompt" },
     { "path": "./packages/core/agent" },
-    { "path": "./packages/ui/commands" },
+    { "path": "./packages/interaction/commands" },
     { "path": "./packages/goal/goal" },
     { "path": "./packages/goal/tool-goal" },
     { "path": "./packages/goal/goal-session" },
@@ -147,15 +147,15 @@
     { "path": "./packages/context/time-context" },
     { "path": "./packages/context/tmux-context" },
     { "path": "./packages/context/session-reference" },
-    { "path": "./packages/ui/user-interaction" },
-    { "path": "./packages/ui/user-approval" },
-    { "path": "./packages/ui/permission" },
+    { "path": "./packages/interaction/user-interaction" },
+    { "path": "./packages/interaction/user-approval" },
+    { "path": "./packages/interaction/permission" },
     { "path": "./packages/core/tools" },
     { "path": "./packages/skill/skill" },
     { "path": "./packages/skill/skill-badge" },
     { "path": "./packages/skill/skill-local" },
     { "path": "./packages/skill/tool-skill" },
-    { "path": "./packages/ui/tool-ask-user" },
+    { "path": "./packages/interaction/tool-ask-user" },
     { "path": "./packages/context/workspace-context" },
     { "path": "./packages/core/agent-loop" },
     { "path": "./packages/llm/llm-retry" },
@@ -212,8 +212,8 @@
     { "path": "./packages/bundle/base" },
     { "path": "./packages/bundle/headless" },
     { "path": "./packages/bundle/web-app" },
-    { "path": "./packages/ui/app-boot" },
-    { "path": "./packages/ui/jsonrpc" },
+    { "path": "./packages/boot/app-boot" },
+    { "path": "./packages/scaffold/server" },
     { "path": "./packages/examples/jsonrpc-demo" },
     { "path": "./packages/support/llm-replay" },
     { "path": "./packages/typert/generator" },
@@ -259,12 +259,12 @@
     { "path": "./packages/host/directory-picker-native" },
     { "path": "./packages/host/frontend-static" },
     { "path": "./packages/host/webserver" },
-    { "path": "./packages/sdk/sdk-client" },
-    { "path": "./packages/sdk/helper" },
-    { "path": "./packages/sdk/sdk-protocol" },
-    { "path": "./packages/sdk/scripts" },
-    { "path": "./packages/sdk/create-sdk" },
-    { "path": "./packages/sdk/telemetry" },
+    { "path": "./packages/scaffold/client" },
+    { "path": "./packages/scaffold/helper" },
+    { "path": "./packages/scaffold/protocol" },
+    { "path": "./packages/scaffold/scripts" },
+    { "path": "./packages/scaffold/create-sdk" },
+    { "path": "./packages/scaffold/telemetry" },
     { "path": "./packages/lsp/lsp" },
     { "path": "./packages/lsp/lsp-local" },
     { "path": "./packages/lsp/tool-lsp" },
diff --git a/vendor/README.md b/vendor/README.md
index 4bf1d43f46..02e33ea723 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -37,11 +37,11 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 5. **`schemastery/tsdown.config.ts` and `logger-console/tsdown.config.ts`**: ours, not upstream files — per-package build-shape overrides (dual ESM+CJS output; separate node/browser entries) for the repo-root tsdown build. They read the JS emitted under `lib/types` and then write the publish runtime entries under `lib/`. Like the regenerated tsconfigs, they are not part of the upstream sync surface.
 6. **`cordis/src/fiber.ts` lifecycle hardening**: locally closes three reentrant disposal gaps. An effect's owner-list wrapper is registered before its setup body runs, so an unload begun from inside setup awaits setup and every collected cleanup; synchronous setup failure removes the wrapper and rolls back collected cleanup. Async cleanup stays owner-visible until quiescence, and Cordis's internal effect composition joins an already-running cleanup while repeated public disposer calls retain their upstream single-shot result. Effect creation is rejected while the owner is `UNLOADING` (while `PENDING` and `LOADING` remain legal), preventing cleanup-time registrations from escaping the unload snapshot. Child fibers register and receive their parent-owned disposer before `internal/plugin` publication, resolve dependency declarations added by that notification before activation, drain effects attached while pending, skip plugin execution when reentrant disposal invalidates the load epoch before its first checkpoint, and contain teardown-notification failures per observer so one callback cannot starve peers or interrupt ownership cleanup. `Fiber.update()` returns its `internal/update` waterfall result, allowing Loader callers to await a restart while preserving synchronous config validation.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
-8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/ui/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
-9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/ui/app-boot/tests/hmr-config.spec.ts`.
-10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/ui/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git prepare run through the bundled pnpm.
+8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
+9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
+10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git prepare run through the bundled pnpm.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
-12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/ui/app-boot/tests/config-reload.spec.ts`.
+12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
 13. **`include/src/index.ts` serialized child-tree mutation and `hmr/src/index.ts` main-watcher initial-scan suppression**: every Include child-tree mutation (initial apply, refresh, `internal/update` patch re-application) runs through one per-Include queue, because the group's transactional `update` is not reentrant — two concurrent applies interleave create and rollback on the same entries and strand the Include fiber without ever settling. The HMR main watcher passes `ignoreInitial: true`: the initial scan re-announced files boot had just consumed, and its `add` for a config file refreshed an Include mid-initial-apply; once serialized, a failing initial apply's rollback disposed HMR, whose teardown drain waited on the queued refresh sitting behind that same apply — a deadlock that exited 13 with no diagnostic. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a user patch layer present at registration must apply once. Covered by the patch-overlay boot-failure built-bin case in `apps/cli/tests/built-bin.e2e.ts`.
 14. **`include/src/index.ts` `writeTask` type**: widened the optional `writeTask?: NodeJS.Timeout` property to `NodeJS.Timeout | undefined` — the debounced writer assigns `undefined` on flush, which `exactOptionalPropertyTypes` rejects on a plain optional. Type-only; no behavior change.
 
diff --git a/vitest.config.ts b/vitest.config.ts
index 29ad406e75..4456782519 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -32,8 +32,8 @@ const windowsUnsupportedPackages = process.platform === 'win32'
       'packages/subprocess/*',
       'packages/pty/pty-local',
       'packages/sandbox/sandbox-local',
-      'packages/sdk/create-sdk',
-      'packages/sdk/helper',
+      'packages/scaffold/create-sdk',
+      'packages/scaffold/helper',
     ]
   : []
 
@@ -83,7 +83,7 @@ const processBoundTests = [
   'packages/subprocess/subprocess-local/tests/spawn.spec.ts',
   'packages/context/time-context/tests/time-context.spec.ts',
   'packages/llm/llm-pi-ai/tests/adapter.spec.ts',
-  'packages/ui/app-boot/tests/app-boot.spec.ts',
+  'packages/boot/app-boot/tests/app-boot.spec.ts',
   'packages/workflow/workflow-workerthread/tests/session.spec.ts',
 ]
 
@@ -222,8 +222,8 @@ export default defineConfig({
         // Projection/command round: executor lifecycle branches and the
         // registry's drive tails need the same maturing lanes. TODO(gui):
         // cover and remove with the client test lane above.
-        'packages/ui/commands/src/index.ts',
-        'packages/ui/commands/src/invariant.ts',
+        'packages/interaction/commands/src/index.ts',
+        'packages/interaction/commands/src/invariant.ts',
         'packages/session/session-projection/src/index.ts',
         ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`),
         ...windowsCoverageExclusions,
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index 049688a0ec..cf9cae0780 100644
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -51,7 +51,7 @@ export default defineConfig({
       ...(process.env.DSH_EXAMPLE_MODE === 'lib' ? ['apps/web/tests/**/*.snapshot.ts'] : []),
       'apps/cli/tests/**/*.snapshot.ts',
       'examples/*/tests/**/*.snapshot.ts',
-      'packages/sdk/*/tests/**/*.snapshot.ts',
+      'packages/scaffold/*/tests/**/*.snapshot.ts',
     ],
     // Replay never writes committed outputs and every scenario owns its
     // mutable runtime state (the subprocess suites use a unique temp dir and

From 2a40cbf8efb0a9e9e3690b8c7ad0eb65a8d319c5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 03:40:42 +0800
Subject: [PATCH 405/516] refactor(packages): merge timeout/ into guard/,
 rename cordis/ to self-modification/

git mv timeout-policy beside repeat-tool-guard (both are loop-hygiene
policies on the tool-execution pipeline, and the timeout/ group name
collided with util/timeout) and tool-cordis into self-modification/
(naming the role the framework name obscured). Merged/renamed group
README triplets, tsconfig globs, generator sources, hierarchy tables,
catalogs, and the timeout-policy design note's group references
follow. Adds the fifth FIXME marker (dsh-timeout-guard, recorded as a
suggestion to settle at resolution time).

guard + self-modification suites: 197 passed.
---
 ...-07-28-dsh-guided-skill-session-commands.i18n.yaml |  6 +++---
 .../2026-07-28-dsh-guided-skill-session-commands.md   |  2 +-
 ...2026-07-28-dsh-guided-skill-session-commands.zh.md |  2 +-
 .../2026-07-07-tool-call-timeout-policy.i18n.yaml     |  4 ++--
 .../2026-07-07-tool-call-timeout-policy.md            |  4 ++--
 .../2026-07-07-tool-call-timeout-policy.zh.md         |  4 ++--
 ...2026-07-19-cooperative-tool-cancellation.i18n.yaml |  4 ++--
 .../2026-07-19-cooperative-tool-cancellation.md       |  2 +-
 .../2026-07-19-cooperative-tool-cancellation.zh.md    |  2 +-
 ...-package-manager-native-repository-cache.i18n.yaml |  4 ++--
 ...6-07-30-package-manager-native-repository-cache.md |  2 +-
 ...7-30-package-manager-native-repository-cache.zh.md |  2 +-
 ...26-07-08-self-referential-cordis-toolset.i18n.yaml |  4 ++--
 .../2026-07-08-self-referential-cordis-toolset.md     |  2 +-
 .../2026-07-08-self-referential-cordis-toolset.zh.md  |  2 +-
 ...2026-07-31-even-out-shipped-tool-rosters.i18n.yaml |  4 ++--
 .../2026-07-31-even-out-shipped-tool-rosters.md       |  2 +-
 .../2026-07-31-even-out-shipped-tool-rosters.zh.md    |  2 +-
 .../2026-07-29-shared-base-config-overlays.i18n.yaml  |  4 ++--
 .../2026-07-29-shared-base-config-overlays.md         |  4 ++--
 .../2026-07-29-shared-base-config-overlays.zh.md      |  4 ++--
 ...2026-07-04-prune-dead-core-spine-surface.i18n.yaml |  4 ++--
 .../2026-07-04-prune-dead-core-spine-surface.md       |  2 +-
 .../2026-07-04-prune-dead-core-spine-surface.zh.md    |  2 +-
 AGENTS.md                                             |  6 +++---
 README.i18n.yaml                                      |  4 ++--
 README.md                                             |  2 +-
 README.zh.md                                          |  2 +-
 docs/capability-seams.md                              |  2 +-
 docs/tool-catalog.md                                  |  6 +++---
 packages/README.i18n.yaml                             |  4 ++--
 packages/README.md                                    |  5 ++---
 packages/README.zh.md                                 |  5 ++---
 packages/boot/app-boot/src/index.ts                   |  2 +-
 packages/cordis/README.md                             | 10 ----------
 packages/cordis/README.zh.md                          | 10 ----------
 packages/guard/README.i18n.yaml                       |  4 ++--
 packages/guard/README.md                              |  3 ++-
 packages/guard/README.zh.md                           |  3 ++-
 .../timeout-policy/README.i18n.yaml                   |  2 +-
 packages/{timeout => guard}/timeout-policy/README.md  |  0
 .../{timeout => guard}/timeout-policy/README.zh.md    |  0
 .../{timeout => guard}/timeout-policy/package.json    |  0
 .../{timeout => guard}/timeout-policy/src/index.ts    |  6 ++++++
 .../timeout-policy/src/invariant.ts                   |  0
 .../timeout-policy/tests/timeout-policy.spec.ts       |  0
 .../{timeout => guard}/timeout-policy/tsconfig.json   |  0
 packages/interaction/permission/README.i18n.yaml      |  4 ++--
 .../interaction/user-interaction/README.i18n.yaml     |  4 ++--
 packages/scaffold/protocol/README.i18n.yaml           |  4 ++--
 packages/scaffold/server/README.i18n.yaml             |  4 ++--
 .../{cordis => self-modification}/README.i18n.yaml    |  6 +++---
 packages/self-modification/README.md                  | 10 ++++++++++
 packages/self-modification/README.zh.md               | 10 ++++++++++
 .../repository-plugin/README.i18n.yaml                |  2 +-
 .../repository-plugin/README.md                       |  0
 .../repository-plugin/README.zh.md                    |  0
 .../repository-plugin/package.json                    |  0
 .../repository-plugin/src/bin.ts                      |  0
 .../repository-plugin/src/format.ts                   |  0
 .../repository-plugin/src/index.ts                    |  0
 .../repository-plugin/src/invariant.ts                |  0
 .../repository-plugin/src/mcp.ts                      |  0
 .../repository-plugin/src/source.ts                   |  2 +-
 .../repository-plugin/tests/mcp-format.spec.ts        |  0
 .../repository-plugin/tests/repository-plugin.spec.ts |  0
 .../repository-plugin/tsconfig.json                   |  0
 .../repository-plugin/tsdown.config.ts                |  0
 .../tool-cordis/README.i18n.yaml                      |  2 +-
 .../tool-cordis/README.md                             |  0
 .../tool-cordis/README.zh.md                          |  0
 .../tool-cordis/package.json                          |  0
 .../tool-cordis/src/api-catalog.ts                    |  0
 .../tool-cordis/src/fiber-state.ts                    |  0
 .../tool-cordis/src/guard.ts                          |  0
 .../tool-cordis/src/index.ts                          |  0
 .../tool-cordis/src/inspect.ts                        |  0
 .../tool-cordis/src/invariant.ts                      |  0
 .../tool-cordis/src/mount.ts                          |  0
 .../tool-cordis/src/present.ts                        |  0
 .../tool-cordis/src/sandbox.ts                        |  0
 .../tool-cordis/tests/cordis-lifecycle.spec.ts        |  0
 .../tool-cordis/tests/cross-mount.spec.ts             |  0
 .../tool-cordis/tests/helpers.ts                      |  0
 .../tool-cordis/tests/inspect.spec.ts                 |  0
 .../tool-cordis/tests/integration.spec.ts             |  0
 .../tool-cordis/tests/mount.spec.ts                   |  0
 .../tool-cordis/tests/present.spec.ts                 |  0
 .../tool-cordis/tests/sandbox-context.spec.ts         |  0
 .../tool-cordis/tests/tool-cordis.spec.ts             |  0
 .../tool-cordis/tests/unmount-hmr.spec.ts             |  0
 .../tool-cordis/tsconfig.json                         |  0
 packages/timeout/README.i18n.yaml                     |  6 ------
 packages/timeout/README.md                            | 11 -----------
 packages/timeout/README.zh.md                         | 11 -----------
 .../typert/generator/tests/cordis-catalog.spec.ts     |  2 +-
 packages/web/tool-web/README.i18n.yaml                |  4 ++--
 packages/web/tool-web/README.md                       |  4 ++--
 packages/web/tool-web/README.zh.md                    |  4 ++--
 packages/web/tool-web/tsconfig.json                   |  2 +-
 packages/web/web-fetch-local/README.i18n.yaml         |  4 ++--
 packages/web/web-fetch-local/README.md                |  2 +-
 packages/web/web-fetch-local/README.zh.md             |  2 +-
 scripts/gen-cordis-catalog.ts                         |  2 +-
 scripts/gen-tool-catalog.ts                           |  2 +-
 tsconfig.base.json                                    |  6 ++----
 tsconfig.host.json                                    |  6 +++---
 107 files changed, 121 insertions(+), 145 deletions(-)
 delete mode 100644 packages/cordis/README.md
 delete mode 100644 packages/cordis/README.zh.md
 rename packages/{timeout => guard}/timeout-policy/README.i18n.yaml (79%)
 rename packages/{timeout => guard}/timeout-policy/README.md (100%)
 rename packages/{timeout => guard}/timeout-policy/README.zh.md (100%)
 rename packages/{timeout => guard}/timeout-policy/package.json (100%)
 rename packages/{timeout => guard}/timeout-policy/src/index.ts (91%)
 rename packages/{timeout => guard}/timeout-policy/src/invariant.ts (100%)
 rename packages/{timeout => guard}/timeout-policy/tests/timeout-policy.spec.ts (100%)
 rename packages/{timeout => guard}/timeout-policy/tsconfig.json (100%)
 rename packages/{cordis => self-modification}/README.i18n.yaml (55%)
 create mode 100644 packages/self-modification/README.md
 create mode 100644 packages/self-modification/README.zh.md
 rename packages/{cordis => self-modification}/repository-plugin/README.i18n.yaml (77%)
 rename packages/{cordis => self-modification}/repository-plugin/README.md (100%)
 rename packages/{cordis => self-modification}/repository-plugin/README.zh.md (100%)
 rename packages/{cordis => self-modification}/repository-plugin/package.json (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/bin.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/format.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/index.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/invariant.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/mcp.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/src/source.ts (98%)
 rename packages/{cordis => self-modification}/repository-plugin/tests/mcp-format.spec.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/tests/repository-plugin.spec.ts (100%)
 rename packages/{cordis => self-modification}/repository-plugin/tsconfig.json (100%)
 rename packages/{cordis => self-modification}/repository-plugin/tsdown.config.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/README.i18n.yaml (78%)
 rename packages/{cordis => self-modification}/tool-cordis/README.md (100%)
 rename packages/{cordis => self-modification}/tool-cordis/README.zh.md (100%)
 rename packages/{cordis => self-modification}/tool-cordis/package.json (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/api-catalog.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/fiber-state.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/guard.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/index.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/inspect.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/invariant.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/mount.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/present.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/src/sandbox.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/cordis-lifecycle.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/cross-mount.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/helpers.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/inspect.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/integration.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/mount.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/present.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/sandbox-context.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/tool-cordis.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tests/unmount-hmr.spec.ts (100%)
 rename packages/{cordis => self-modification}/tool-cordis/tsconfig.json (100%)
 delete mode 100644 packages/timeout/README.i18n.yaml
 delete mode 100644 packages/timeout/README.md
 delete mode 100644 packages/timeout/README.zh.md

diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml
index 8feded0ad4..a9e56019b3 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.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 .agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.md
-2026-07-28-dsh-guided-skill-session-commands.md: 454d090a55db8987f8e4987aba67deff1b21b1a0
-2026-07-28-dsh-guided-skill-session-commands.zh.md: 64dad4e39c6fd3e3341313c3f8dd2b04947695cf
+#   pnpm run verify-translation-pairing --write .agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
+2026-07-28-dsh-guided-skill-session-commands.md: 606513919a927af3bb7e9b74544fd8df9a1682ce
+2026-07-28-dsh-guided-skill-session-commands.zh.md: 39af4a3a554ba3053f25b3d034346d3e1f4ce237
diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
index 454d090a55..606513919a 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
@@ -25,7 +25,7 @@ The `dsh-migrate` skill is bundled under `skills/` (shipped through `DSH_BUNDLED
 
 `apps/cli/tests/args.spec.ts` gains routing for `migrate`/`upgrade` (bare discriminant) and exit-1 for every leaked option on either side of each subcommand.
 
-`packages/ui/tui/tests/tui.spec.ts` gains two fake-terminal cases in the existing skill describe block: `config.initialSkill` set delivers the rendered skill body as the first turn with no user input, and an unknown initial skill reports a notice without sending. `runSkillSession` itself is composition inside the module's `v8 ignore` block, like `runTui`/`runMeta`.
+`packages/interaction/tui/tests/tui.spec.ts` gains two fake-terminal cases in the existing skill describe block: `config.initialSkill` set delivers the rendered skill body as the first turn with no user input, and an unknown initial skill reports a notice without sending. `runSkillSession` itself is composition inside the module's `v8 ignore` block, like `runTui`/`runMeta`.
 
 No keyless PTY snapshot: per the maintainer's scope call for this change, unit coverage plus interactive verification suffices, and the seed rides the already-snapshotted `/skill:` render path. Both commands were verified interactively in tmux from a scratch cwd: `dsh migrate` loaded `dsh-migrate` and asked which source agent; `dsh upgrade` loaded `dsh-upgrade`, which pulled in `dsh-customize` and began checkout discovery.
 
diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
index 64dad4e39c..39af4a3a55 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
@@ -25,7 +25,7 @@ Archived: 2026-08-03
 
 `apps/cli/tests/args.spec.ts` 新增 `migrate`/`upgrade` 的路由（裸判别式），以及每个子命令两侧任一泄漏选项的退出码 1。
 
-`packages/ui/tui/tests/tui.spec.ts` 在既有 skill describe 块中新增两个伪终端用例：设置 `config.initialSkill` 时无需用户输入即把渲染后的 skill 正文作为首轮投递；未知的初始 skill 以通知形式报告且不发送。`runSkillSession` 本身是模块 `v8 ignore` 块内的组装，与 `runTui`/`runMeta` 相同。
+`packages/interaction/tui/tests/tui.spec.ts` 在既有 skill describe 块中新增两个伪终端用例：设置 `config.initialSkill` 时无需用户输入即把渲染后的 skill 正文作为首轮投递；未知的初始 skill 以通知形式报告且不发送。`runSkillSession` 本身是模块 `v8 ignore` 块内的组装，与 `runTui`/`runMeta` 相同。
 
 无 keyless PTY 快照：依据维护者对本次改动的范围裁定，单元覆盖加交互式验证已足够，且播种走的是已有快照的 `/skill:` 渲染路径。两个命令均已在 tmux 中从临时 cwd 交互式验证：`dsh migrate` 加载 `dsh-migrate` 并询问源 agent；`dsh upgrade` 加载 `dsh-upgrade`，后者引入 `dsh-customize` 并开始 checkout 发现。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
index f51277307f..e400692950 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.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 .agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
-2026-07-07-tool-call-timeout-policy.md: 69fd1ee721de69621d3b57c10d960da0651b94dd
-2026-07-07-tool-call-timeout-policy.zh.md: 0b8d07788dce152985e133923bb673f80175e68d
+2026-07-07-tool-call-timeout-policy.md: b85a4d2d60ef60d9f75bd47d4d405aa55c132af6
+2026-07-07-tool-call-timeout-policy.zh.md: e67b9e4223f486208061f3944369cf3ec06fe72d
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
index 69fd1ee721..b85a4d2d60 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
@@ -40,7 +40,7 @@ That the catch is the base `next` — not something outside the waterfall — is
 
 ### The `timeout-policy` plugin
 
-The plugin is `@deepseek-ai/dsh-timeout-policy`, a zero-config function/namespace plugin (`name` / `inject` / `apply`) in the `packages/timeout/` group. The per-tool budget is DECLARED on the tool, not on this plugin: a `ToolDefinition` carries an optional `timeoutMs`, which the owning tool plugin sets from its own config. `dsh-tool-web`, for example, resolves `fetchTimeoutMs` / `searchTimeoutMs` (default 30000) onto the `web_fetch` / `web_search` definitions:
+The plugin is `@deepseek-ai/dsh-timeout-policy`, a zero-config function/namespace plugin (`name` / `inject` / `apply`) in the `packages/guard/` group (originally its own `timeout/` group). The per-tool budget is DECLARED on the tool, not on this plugin: a `ToolDefinition` carries an optional `timeoutMs`, which the owning tool plugin sets from its own config. `dsh-tool-web`, for example, resolves `fetchTimeoutMs` / `searchTimeoutMs` (default 30000) onto the `web_fetch` / `web_search` definitions:
 
 ```yaml
 - id: timeout-policy
@@ -89,7 +89,7 @@ A future model-facing grep/glob tool can be implemented on top of `ctx.bash` wit
 
 ## Alternatives considered
 
-**Name the plugin `tool-timeout`.** The literal Agent Note name matched the `gen-tool-catalog` completeness guard's `packages/*/tool-*` glob, which requires every match to register a model-facing tool. This plugin registers none — it is a `tools/execute` wrapper — so a `tool-*` name would either fail `verify-tool-catalog` or force a misleading boot entry. The package is `@deepseek-ai/dsh-timeout-policy` in a new `packages/timeout/` group; the cordis.yml `id` can still be `timeout-policy`.
+**Name the plugin `tool-timeout`.** The literal Agent Note name matched the `gen-tool-catalog` completeness guard's `packages/*/tool-*` glob, which requires every match to register a model-facing tool. This plugin registers none — it is a `tools/execute` wrapper — so a `tool-*` name would either fail `verify-tool-catalog` or force a misleading boot entry. The package is `@deepseek-ai/dsh-timeout-policy` in what was then a new `timeout/` group, since folded into `packages/guard/`; the cordis.yml `id` can still be `timeout-policy`.
 
 **Keep per-tool timeout handling only.** This was the shape for `bash` and `web_fetch`, and it matches Claude Code and Codex for shell commands. It loses for web-style tools because every new timeout-capable tool must choose validation, cap semantics, docs, snapshots, and classification. The plugin centralizes policy and classification while leaving each tool's schema focused on business input.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
index 0b8d07788d..e67b9e4223 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
@@ -40,7 +40,7 @@ catch 是基础 `next`（而非 waterfall 之外的东西）这一点至关重
 
 ### `timeout-policy` 插件
 
-该插件是 `@deepseek-ai/dsh-timeout-policy`，一个零配置的函数/命名空间插件（`name` / `inject` / `apply`），位于 `packages/timeout/` 组。每个工具的预算声明在工具自身，而非本插件：`ToolDefinition` 携带一个可选的 `timeoutMs`，由拥有该工具的插件从自身配置中设置。例如 `dsh-tool-web` 将 `fetchTimeoutMs` / `searchTimeoutMs`（默认 30000）解析到 `web_fetch` / `web_search` 的定义上：
+该插件是 `@deepseek-ai/dsh-timeout-policy`，一个零配置的函数/命名空间插件（`name` / `inject` / `apply`），位于 `packages/guard/` 组。每个工具的预算声明在工具自身，而非本插件：`ToolDefinition` 携带一个可选的 `timeoutMs`，由拥有该工具的插件从自身配置中设置。例如 `dsh-tool-web` 将 `fetchTimeoutMs` / `searchTimeoutMs`（默认 30000）解析到 `web_fetch` / `web_search` 的定义上：
 
 ```yaml
 - id: timeout-policy
@@ -89,7 +89,7 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 
 ## 曾考虑的替代方案
 
-**将插件命名为 `tool-timeout`。** 字面的 Agent Note 名称匹配了 `gen-tool-catalog` 完整性守卫的 `packages/*/tool-*` glob，该 glob 要求每个匹配项注册一个面向模型的工具。本插件不注册任何工具——它是一个 `tools/execute` 包装器——因此 `tool-*` 名称要么导致 `verify-tool-catalog` 失败，要么强制产生一个误导性的启动条目。包为 `@deepseek-ai/dsh-timeout-policy`，位于新的 `packages/timeout/` 组；cordis.yml 的 `id` 仍可为 `timeout-policy`。
+**将插件命名为 `tool-timeout`。** 字面的 Agent Note 名称匹配了 `gen-tool-catalog` 完整性守卫的 `packages/*/tool-*` glob，该 glob 要求每个匹配项注册一个面向模型的工具。本插件不注册任何工具——它是一个 `tools/execute` 包装器——因此 `tool-*` 名称要么导致 `verify-tool-catalog` 失败，要么强制产生一个误导性的启动条目。包为 `@deepseek-ai/dsh-timeout-policy`，位于新的 `packages/guard/` 组；cordis.yml 的 `id` 仍可为 `timeout-policy`。
 
 **仅保留逐工具的超时处理。** 这是 `bash` 和 `web_fetch` 的既有形态，也与 Claude Code 和 Codex 对 shell 命令的做法一致。它对 web 类工具不利，因为每个新的支持超时的工具都必须自行选择校验方式、上限语义、文档、快照和分类。插件集中了策略和分类，让每个工具的 schema 专注于业务输入。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
index 2f56298d57..82d87580f8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.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 .agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
-2026-07-19-cooperative-tool-cancellation.md: be237f6ca9475699bb4af76896772a1a7409033d
-2026-07-19-cooperative-tool-cancellation.zh.md: dbc74588931a2ae75678b0026df7a8175b0d20b6
+2026-07-19-cooperative-tool-cancellation.md: 4e82452cd6883593d4693766bea803c97fa4c977
+2026-07-19-cooperative-tool-cancellation.zh.md: 1d9fd3dcc8fa65e6f06050be749eec6ac9e996c2
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
index be237f6ca9..4e82452cd6 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
@@ -46,7 +46,7 @@ This decision requires cancellation at the tool invocation seam only. Making sig
 
 ## Verification
 
-[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) proves the required exact signal types, readonly observer and tool views, mutable-but-required around-dispatch view, and `defineTool()` inference. [`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) covers pre-aborted materialization, phase skipping, policy and wrapper races, body invocation classification, caller-signal fusion, error precedence, context retention, and quiescent drainage. [`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) and [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) cover balanced durable results for undispatched siblings. [`code-mode.spec.ts`](../../../../packages/core/tools/tests/code-mode.spec.ts) and first-party integration suites cover explicit forwarding, while [`timeout-policy.spec.ts`](../../../../packages/timeout/timeout-policy/tests/timeout-policy.spec.ts) preserves timeout ownership.
+[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) proves the required exact signal types, readonly observer and tool views, mutable-but-required around-dispatch view, and `defineTool()` inference. [`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) covers pre-aborted materialization, phase skipping, policy and wrapper races, body invocation classification, caller-signal fusion, error precedence, context retention, and quiescent drainage. [`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) and [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) cover balanced durable results for undispatched siblings. [`code-mode.spec.ts`](../../../../packages/core/tools/tests/code-mode.spec.ts) and first-party integration suites cover explicit forwarding, while [`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) preserves timeout ownership.
 
 No registry test can prove that arbitrary third-party same-process code observes the signal or stops in bounded time. Capability tests continue to prove cancellation and quiescence at the boundary that owns each side effect.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
index dbc7458893..1d9fd3dcc8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
@@ -46,7 +46,7 @@ Status: implemented
 
 ## 验证
 
-[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) 证明必填的精确信号类型、观察者与工具的只读视图、环绕调度可替换但不可删除的视图，以及 `defineTool()` 推断。[`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) 覆盖进入时已中止的物化与阶段跳过、策略和包装层竞态、工具主体调用分类、调用方信号融合、错误优先级、上下文保留和完全停稳。[`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) 与 [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) 覆盖为未调度的同批调用补齐持久化结果。[`code-mode.spec.ts`](../../../../packages/core/tools/tests/code-mode.spec.ts) 和第一方集成测试覆盖显式转发，[`timeout-policy.spec.ts`](../../../../packages/timeout/timeout-policy/tests/timeout-policy.spec.ts) 保持超时归属。
+[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) 证明必填的精确信号类型、观察者与工具的只读视图、环绕调度可替换但不可删除的视图，以及 `defineTool()` 推断。[`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) 覆盖进入时已中止的物化与阶段跳过、策略和包装层竞态、工具主体调用分类、调用方信号融合、错误优先级、上下文保留和完全停稳。[`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) 与 [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) 覆盖为未调度的同批调用补齐持久化结果。[`code-mode.spec.ts`](../../../../packages/core/tools/tests/code-mode.spec.ts) 和第一方集成测试覆盖显式转发，[`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) 保持超时归属。
 
 任何注册表测试都无法证明任意第三方同进程代码会观察信号或在有界时间内停止。各能力的测试仍需在拥有相应副作用的边界证明取消与完全停稳。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
index 6c888c7cad..e556108299 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.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 .agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
-2026-07-30-package-manager-native-repository-cache.md: f8a6706065a936ca4a9abf2a50d266a60f09b252
-2026-07-30-package-manager-native-repository-cache.zh.md: b1fea3d655f8d7aeb466744dc27bbf4ba69993ec
+2026-07-30-package-manager-native-repository-cache.md: 0ea145f20a58e4e3e9feb7ba5574818c0352e2c4
+2026-07-30-package-manager-native-repository-cache.zh.md: ac72e5dc4ffa764e1dc430764a6f52fc083d32a4
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
index f8a6706065..0ea145f20a 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
@@ -44,4 +44,4 @@ An identical specifier permanently reuses its published entry. The caller change
 
 ## Testing
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` covers same-process single-flight, cross-instance cache reuse, exact-specifier separation, failed-stage cleanup and retry, and boundary validation. Its real local-Git case invokes the bundled pnpm, runs the fixture repository's `prepare` script, and reads the prepared file from the installed cache entry without network access.
+`packages/boot/app-boot/tests/repository-cache.spec.ts` covers same-process single-flight, cross-instance cache reuse, exact-specifier separation, failed-stage cleanup and retry, and boundary validation. Its real local-Git case invokes the bundled pnpm, runs the fixture repository's `prepare` script, and reads the prepared file from the installed cache entry without network access.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
index b1fea3d655..ac72e5dc4f 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
@@ -44,4 +44,4 @@ Loader 将 `pnpm@11.7.0` 作为固定版本的运行时依赖，并使用当前
 
 ## 测试
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 覆盖同进程 single-flight、跨实例缓存复用、精确 specifier 隔离、失败暂存清理与重试，以及边界校验。其真实本地 Git 用例会调用随附的 pnpm，运行 fixture（测试前置数据）仓库的 `prepare` 脚本，并在不访问网络的情况下，从已安装缓存项中读取准备后的文件。
+`packages/boot/app-boot/tests/repository-cache.spec.ts` 覆盖同进程 single-flight、跨实例缓存复用、精确 specifier 隔离、失败暂存清理与重试，以及边界校验。其真实本地 Git 用例会调用随附的 pnpm，运行 fixture（测试前置数据）仓库的 `prepare` 脚本，并在不访问网络的情况下，从已安装缓存项中读取准备后的文件。
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
index 487726c0e3..105a9d3cfd 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.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 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
-2026-07-08-self-referential-cordis-toolset.md: 335d5e808016ebc37c8457c5dcf4d7da9d8b8c93
-2026-07-08-self-referential-cordis-toolset.zh.md: 46d492cd92495a1e4d516db3f82c9e75486bc386
+2026-07-08-self-referential-cordis-toolset.md: 29d331008d4111ae00147f2ddd19a628135339ac
+2026-07-08-self-referential-cordis-toolset.zh.md: 55013b774b4b6b371d9cbe6ac492b4e95500a7ff
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
index 335d5e8080..29d331008d 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
@@ -12,7 +12,7 @@ First, model-written registration must be validated where it happens: a malforme
 
 ## Decision
 
-The toolset ships as [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) and is demoed by `examples/web-cordis`. It gives the model three tools over the live Cordis runtime in the current DSH process: inspect it, mount an in-memory temporary Plugin, and unmount that Plugin to quiescence.
+The toolset ships as [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/self-modification/tool-cordis/README.md) and is demoed by `examples/web-cordis`. It gives the model three tools over the live Cordis runtime in the current DSH process: inspect it, mount an in-memory temporary Plugin, and unmount that Plugin to quiescence.
 
 The vm isolates accidental global pollution, and the context façade hides framework internals. Neither restricts the authority of exposed services: a temporary Plugin can call `ctx.bash` with the host executor's privileges and reach the real filesystem and web services. It runs in the shared DSH runtime and may affect other sessions in that process. This is an opt-in development tool with bash-equivalent trust, not a security boundary or product default.
 
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
index 46d492cd92..55013b774b 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-该工具集以 [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) 发布，并由 `examples/web-cordis` 演示。它为模型提供三个工具，用于操作当前 DSH 进程中的活跃 Cordis 运行时：检查该运行时、挂载一个仅存于内存的临时 Plugin，再将该 Plugin 卸载至完全停稳。
+该工具集以 [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/self-modification/tool-cordis/README.md) 发布，并由 `examples/web-cordis` 演示。它为模型提供三个工具，用于操作当前 DSH 进程中的活跃 Cordis 运行时：检查该运行时、挂载一个仅存于内存的临时 Plugin，再将该 Plugin 卸载至完全停稳。
 
 vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节。但二者都不限制已暴露服务的权限：临时 Plugin 可以调用 `ctx.bash` 以宿主执行器的权限运行命令，也能访问真实的文件系统和网络服务。它运行在共享 DSH runtime 中，可能影响同一进程的其他 session。这是一个需要显式启用的开发工具，信任等级与 bash 相当，不是安全边界，也不是产品默认配置。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
index cbe53b9622..d1cef43cc1 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.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 .agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
-2026-07-31-even-out-shipped-tool-rosters.md: d12db993654d9f2b41a16a4663dc64aefe8e3a2f
-2026-07-31-even-out-shipped-tool-rosters.zh.md: 8381a457def1a909b300de52dc011e2437c7e9f3
+2026-07-31-even-out-shipped-tool-rosters.md: 0195620055da5e570d2f54792d950a88bab8d652
+2026-07-31-even-out-shipped-tool-rosters.zh.md: cc67f24720f650283daa4ee85a0a1af5358756a8
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
index d12db99365..0195620055 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
@@ -22,7 +22,7 @@ Two rows stay surface-specific. `tmux-context` is TUI-only because a browser sur
 
 Three capabilities stay out on the evidence their own packages record, and are listed here so "we forgot" and "we decided against" stay distinguishable.
 
-**`dsh-tool-cordis`** lets the model write JavaScript and mount it as a temporary plugin. Its README states the limit: "The sandbox is containment for honest code, not a security boundary — host-realm helpers on the sandbox global are reachable, so mount code can reach Node" ([Known limitations](../../../../packages/cordis/tool-cordis/README.md)). The `node:vm` realm lives inside the harness process while `dsh-sandbox-local` confines only the argv it spawns, so on the Web surface both the sandbox and the approval seam are bypassed rather than enforced.
+**`dsh-tool-cordis`** lets the model write JavaScript and mount it as a temporary plugin. Its README states the limit: "The sandbox is containment for honest code, not a security boundary — host-realm helpers on the sandbox global are reachable, so mount code can reach Node" ([Known limitations](../../../../packages/self-modification/tool-cordis/README.md)). The `node:vm` realm lives inside the harness process while `dsh-sandbox-local` confines only the argv it spawns, so on the Web surface both the sandbox and the approval seam are bypassed rather than enforced.
 
 **`dsh-web-fetch-local`** stays unmounted and `dsh-tool-web` keeps `fetch: false`. SSRF protection is deferred in the implementation ([`policy.ts`](../../../../packages/web/web-fetch-local/src/policy.ts) validates protocol, credentials, and length only) and the package says so: "this provider is an SSRF primitive and **must not be enabled** in a deployment that can reach sensitive internal network targets" ([README](../../../../packages/web/web-fetch-local/README.md)). The model chooses the target, which includes the harness's own gateway on loopback, private ranges, and cloud metadata endpoints.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
index 8381a457de..cc67f24720 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 有三项能力基于其自身包所记录的证据保持在外,列在这里是为了让「我们忘了」和「我们决定不要」保持可区分。
 
-**`dsh-tool-cordis`** 让模型写一段 JavaScript 并挂成临时插件。它的 README 写明了这个界限:「The sandbox is containment for honest code, not a security boundary — host-realm helpers on the sandbox global are reachable, so mount code can reach Node」([Known limitations](../../../../packages/cordis/tool-cordis/README.md))。`node:vm` 的 realm 就在 harness 进程内,而 `dsh-sandbox-local` 只约束它 spawn 出去的 argv,因此在 Web surface 上,沙箱与批准接缝是被绕过而非被执行。
+**`dsh-tool-cordis`** 让模型写一段 JavaScript 并挂成临时插件。它的 README 写明了这个界限:「The sandbox is containment for honest code, not a security boundary — host-realm helpers on the sandbox global are reachable, so mount code can reach Node」([Known limitations](../../../../packages/self-modification/tool-cordis/README.md))。`node:vm` 的 realm 就在 harness 进程内,而 `dsh-sandbox-local` 只约束它 spawn 出去的 argv,因此在 Web surface 上,沙箱与批准接缝是被绕过而非被执行。
 
 **`dsh-web-fetch-local`** 保持不挂,`dsh-tool-web` 保持 `fetch: false`。SSRF 防护在实现中是 deferred 状态([`policy.ts`](../../../../packages/web/web-fetch-local/src/policy.ts) 只校验协议、凭据与长度),包里也直说了:「this provider is an SSRF primitive and **must not be enabled** in a deployment that can reach sensitive internal network targets」([README](../../../../packages/web/web-fetch-local/README.md))。目标由模型选择,其中包括 harness 自己跑在环回地址上的网关、内网段和云元数据端点。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
index ecfb0ca0e8..4396748bc7 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.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 .agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
-2026-07-29-shared-base-config-overlays.md: 9fae9775e0b37acc99ce2eb5fc630e6f4f52bf1d
-2026-07-29-shared-base-config-overlays.zh.md: 20cc3e522c369315a1fafc84778fced0260581d0
+2026-07-29-shared-base-config-overlays.md: b2ca5cc8d3a160dd09550827d5f8148c14048ea4
+2026-07-29-shared-base-config-overlays.zh.md: e14aa87bdd6ed3bd711bb9786220b5baf0566e8e
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
index 9fae9775e0..b2ca5cc8d3 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
@@ -24,7 +24,7 @@ Precedence is list order, last write winning per row: base, then the surface ove
 
 A patch replaces its target row's whole `config` rather than merging, which shapes the split: a row whose value differs per surface lives in the overlays, never in the base, so no row is patched by three layers at once. Session identity therefore cannot ride a config key at all — it moved to `dsh-agent-loop`'s `CONFIGURED_AGENT_IDENTITIES_KEY`, as the launcher-owned identity record documented.
 
-`examples/tui-agent`, `examples/cordis-agent`, `examples/code-mode`, and `packages/examples/tui-demo` are deleted. The TUI tests move to `apps/cli/tests/`, the cordis-toolset e2e to `packages/cordis/tool-cordis/tests/`, and the supported Code Mode demo remains the ACP overlay at `examples/acp-agent/code-mode.cordis.yml`.
+`examples/tui-agent`, `examples/cordis-agent`, `examples/code-mode`, and `packages/examples/tui-demo` are deleted. The TUI tests move to `apps/cli/tests/`, the cordis-toolset e2e to `packages/self-modification/tool-cordis/tests/`, and the supported Code Mode demo remains the ACP overlay at `examples/acp-agent/code-mode.cordis.yml`.
 
 ## Alternatives considered
 
@@ -48,6 +48,6 @@ A patch whose `id` matches no row stays a no-op rather than an error. That is de
 
 Composition is checked by booting each tree through the real Loader and inspecting settled entries, not by reading YAML; both surfaces settle with zero unloaded rows, and Web starts its `httpServer` with sandboxed Bash and filesystem providers. Code Mode remains covered by the ACP overlay and programmatic TUI snapshots rather than a separate shipped TUI application.
 
-All eight terminal snapshot scenarios replay byte-identically after moving, and the 14-case PTY smoke passes, including two cases that assert a personal overlay reaches an **inserted** row — the behavior the vendored `plugin-include` fix enables ([`vendor/README.md`](../../../../vendor/README.md) local modification 8, covered by `packages/ui/app-boot/tests/config-reload.spec.ts`).
+All eight terminal snapshot scenarios replay byte-identically after moving, and the 14-case PTY smoke passes, including two cases that assert a personal overlay reaches an **inserted** row — the behavior the vendored `plugin-include` fix enables ([`vendor/README.md`](../../../../vendor/README.md) local modification 8, covered by `packages/boot/app-boot/tests/config-reload.spec.ts`).
 
 Flattening surfaced three latent defects, each fixed here: the TUI captured the optional `sessionQuery` service once at construction and so could permanently disable `/resume` when it won the mount race; the shipped session-store root silently reverted to a project-local `./.sessions`; and `--config-replace` was dropped by the resume handoff.
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
index 20cc3e522c..e14aa87bdd 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆分方式：取值因 surface 而异的配置项住在 overlay 中，绝不住在 base 里，从而没有任何配置项会被三层同时 patch。因此会话身份根本不能经由配置键传递——它迁移到了 `dsh-agent-loop` 的 `CONFIGURED_AGENT_IDENTITIES_KEY`，正如启动器持有身份的记录所述。
 
-`examples/tui-agent`、`examples/cordis-agent`、`examples/code-mode` 与 `packages/examples/tui-demo` 均被删除。TUI 测试迁往 `apps/cli/tests/`，cordis 工具集的 e2e 迁入 `packages/cordis/tool-cordis/tests/`，受支持的 Code Mode demo 则保留为 `examples/acp-agent/code-mode.cordis.yml` 中的 ACP overlay。
+`examples/tui-agent`、`examples/cordis-agent`、`examples/code-mode` 与 `packages/examples/tui-demo` 均被删除。TUI 测试迁往 `apps/cli/tests/`，cordis 工具集的 e2e 迁入 `packages/self-modification/tool-cordis/tests/`，受支持的 Code Mode demo 则保留为 `examples/acp-agent/code-mode.cordis.yml` 中的 ACP overlay。
 
 ## 备选方案
 
@@ -48,6 +48,6 @@ patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆
 
 组合的正确性通过用真实 Loader 启动每棵树并检查已就绪的条目来核对，而不是靠阅读 YAML：两个界面都能稳定完成且没有未加载项；Web 会以沙箱化 Bash 与文件系统提供方启动 `httpServer`。Code Mode 继续由 ACP overlay 与程序化 TUI 快照覆盖，而不再维护独立交付的 TUI 应用。
 
-全部八个终端快照场景在迁移后逐字节重放一致，14 个用例的 PTY 冒烟测试全部通过，其中两个用例断言个人 overlay 能触达一个 **insert 进来的**配置项——这正是 vendored `plugin-include` 修复所启用的行为（[`vendor/README.md`](../../../../vendor/README.md) 本地修改第 8 条，由 `packages/ui/app-boot/tests/config-reload.spec.ts` 覆盖）。
+全部八个终端快照场景在迁移后逐字节重放一致，14 个用例的 PTY 冒烟测试全部通过，其中两个用例断言个人 overlay 能触达一个 **insert 进来的**配置项——这正是 vendored `plugin-include` 修复所启用的行为（[`vendor/README.md`](../../../../vendor/README.md) 本地修改第 8 条，由 `packages/boot/app-boot/tests/config-reload.spec.ts` 覆盖）。
 
 平铺过程暴露出三处潜伏缺陷，均在此一并修复：TUI 曾在构造时一次性捕获可选的 `sessionQuery` 服务，因此在挂载竞争中胜出时会永久禁用 `/resume`；交付的会话存储根目录曾静默退回项目本地的 `./.sessions`；`--config-replace` 曾在 resume 交接中被丢弃。
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
index b7cfbde315..af8cad7d63 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.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 .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
-2026-07-04-prune-dead-core-spine-surface.md: 473f655ab0944b43f9b1193413801eb7a80286d8
-2026-07-04-prune-dead-core-spine-surface.zh.md: 3389c0161efa78252c9810d64f46d0cd8a7a034c
+2026-07-04-prune-dead-core-spine-surface.md: 7ee7ffc6e8c0f3672c98be6e23ef45a1abfc2b4e
+2026-07-04-prune-dead-core-spine-surface.zh.md: b65d607c1736545089c7116f8a14ab6e7510a8e1
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
index 473f655ab0..7ee7ffc6e8 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-04-prune-dead-core-spine-surface.zh.md)
 
 Several package-root exports, result fields, and convenience methods have no production consumer. They survive because tests import internals through public entry points or because a type anticipated a caller that never arrived. Each item is small in isolation, but together they enlarge the SDK contract, generated catalogs, documentation, and regression matrix without enabling a shipped path.
 
-The production corpus is `packages/*/*/src`, example sources/config, and runtime scripts. Tests, package READMEs, and Agent Note prose are evidence of publication but not fixed callers. `cordis_inspect` makes `packages/cordis/tool-cordis/src/api-catalog.ts` model-visible, and `cordis_mount` can invoke injected services through guarded real-service proxies, so catalogued service methods and returned shapes are a genuine dynamic product surface. The table therefore distinguishes absence of a fixed repository caller from unreachability: rows touching catalogued vocabulary intentionally contract what model-written mounts can discover and call, while package-root implementation helpers are not reached through that service façade. Exact-symbol searches produce the following inventory:
+The production corpus is `packages/*/*/src`, example sources/config, and runtime scripts. Tests, package READMEs, and Agent Note prose are evidence of publication but not fixed callers. `cordis_inspect` makes `packages/self-modification/tool-cordis/src/api-catalog.ts` model-visible, and `cordis_mount` can invoke injected services through guarded real-service proxies, so catalogued service methods and returned shapes are a genuine dynamic product surface. The table therefore distinguishes absence of a fixed repository caller from unreachability: rows touching catalogued vocabulary intentionally contract what model-written mounts can discover and call, while package-root implementation helpers are not reached through that service façade. Exact-symbol searches produce the following inventory:
 
 | Surface | Production evidence | Simplification |
 | --- | --- | --- |
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
index 3389c0161e..b65d607c17 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
@@ -8,7 +8,7 @@ Status: proposed
 
 若干包根导出、结果字段和便利方法没有生产消费方。它们之所以存活，要么是因为测试通过公开入口导入了内部实现，要么是因为某个类型预期了一个从未出现的调用者。每一项单独看都很小，但合在一起，它们扩大了 SDK 契约、生成的 catalog、文档和回归矩阵，却没有支撑任何已交付的路径。
 
-生产语料库是 `packages/*/*/src`、示例源码/配置和运行时脚本。测试、包 README 和 Agent Note 行文是发布的证据，但不是固定调用者。`cordis_inspect` 使 `packages/cordis/tool-cordis/src/api-catalog.ts` 对模型可见，`cordis_mount` 可以通过受保护的真实服务代理调用注入的服务，因此 catalog 中的服务方法和返回形状是真正的动态产品接口。下表因此区分「没有固定的仓库调用者」与「不可达」：涉及 catalog 词汇的行有意收缩模型编写的 mount 能发现和调用的内容，而包根实现辅助函数并不通过该服务门面可达。精确符号搜索得出以下清单：
+生产语料库是 `packages/*/*/src`、示例源码/配置和运行时脚本。测试、包 README 和 Agent Note 行文是发布的证据，但不是固定调用者。`cordis_inspect` 使 `packages/self-modification/tool-cordis/src/api-catalog.ts` 对模型可见，`cordis_mount` 可以通过受保护的真实服务代理调用注入的服务，因此 catalog 中的服务方法和返回形状是真正的动态产品接口。下表因此区分「没有固定的仓库调用者」与「不可达」：涉及 catalog 词汇的行有意收缩模型编写的 mount 能发现和调用的内容，而包根实现辅助函数并不通过该服务门面可达。精确符号搜索得出以下清单：
 
 | 接口 | 生产证据 | 简化方式 |
 | --- | --- | --- |
diff --git a/AGENTS.md b/AGENTS.md
index 7c9b795ddc..35fbc54ca6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,9 +29,9 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   bundle/      profile plugin bundles: installable patch layers for dsh --profile
   workflow/    workflow seam + worker-thread engine + workflow tool
   todo/        todo_write tool
-  plan/        plan mode as logged per-agent collaboration state
-  guard/       loop-hygiene plugins
-  cordis/      self-referential toolset: the agent inspects/mounts plugins in its own runtime
+  plan/        plan mode as logged collaboration state
+  guard/       loop-hygiene plugins + tool-call timeouts
+  self-modification/  the agent inspects/mounts plugins in its runtime
   hooks/       Claude Code/Codex hook bridges + shared wire-protocol library
   session/     durable session data plane: persistence, projection, titles, reporting
   settings/    user-settings seam + file-backed provider
diff --git a/README.i18n.yaml b/README.i18n.yaml
index c4ad1f0fd9..077f5fa7f2 100644
--- a/README.i18n.yaml
+++ b/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write README.md
-README.md: 64f06c0aec0905fa7deabbec0deea61e1c7a40d4
-README.zh.md: fee03118926028833c828809764ebb5f6375259e
+README.md: ff4cf661a060772973629844d43758d26ac1be02
+README.zh.md: 977de7f22244ff49579393edcce66d02c5782de4
diff --git a/README.md b/README.md
index 64f06c0aec..ff4cf661a0 100644
--- a/README.md
+++ b/README.md
@@ -76,7 +76,7 @@ Built-in capabilities cover file reading, editing, and search; shell and persist
 - **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.
 - **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).
 - **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).
-- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/cordis/tool-cordis/README.md).
+- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/self-modification/tool-cordis/README.md).
 
 ## Community
 
diff --git a/README.zh.md b/README.zh.md
index fee0311892..977de7f222 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -76,7 +76,7 @@ pnpm run demo:acp
 - **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。
 - **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。
 - **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。
-- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。
+- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。
 
 ## 社区
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index c191f6a659..4b46a6566b 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -389,7 +389,7 @@ flowchart LR
 | `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
 | `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm), [`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
-| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
+| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/self-modification/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-pty`](../packages/pty/tool-pty), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
 | `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/interaction/user-interaction) | - | [`tool-ask-user`](../packages/interaction/tool-ask-user) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
 | `ctx.commands` | `core` | [`commands`](../packages/interaction/commands) | - | - | - | Plugins register direct human commands without sending invocations to the model. |
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 0cb985d07d..699617eef4 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -280,7 +280,7 @@ Inspect the live Cordis runtime in the current DSH process. Read-only. Sections:
 }
 ```
 
-Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts)
+Source: [`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
 
 ### `cordis_mount`
 
@@ -301,7 +301,7 @@ Mount a temporary Cordis Plugin in the current DSH process. This creates an in-m
 }
 ```
 
-Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts)
+Source: [`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
 
 ### `cordis_unmount`
 
@@ -322,7 +322,7 @@ Unmount a current-process temporary Plugin created by cordis_mount. Waits for it
 }
 ```
 
-Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts)
+Source: [`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
 
 Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes.
 
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 68da8ae611..039e8bb78d 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 198caca8c8b8231ece4d7160c809ba7b881e775c
-README.zh.md: bf2bf437796d904d135b610ff2c7a2d4d21b0298
+README.md: 7589f37b174b94558bff9f74f860bb4b42705fb8
+README.zh.md: 4e99dd9313cca89e84ae0bfaf4a2179d726da864
diff --git a/packages/README.md b/packages/README.md
index 198caca8c8..7589f37b17 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -34,10 +34,9 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`spill/`](spill/README.md) | Spill capability family: storage seam, local impl, tool-result spill policy | Product — stable surface |
 | [`todo/`](todo/README.md) | The model-facing `todo_write` tool | Product — stable surface |
 | [`plan/`](plan/README.md) | Plan collaboration state with a direct entry command and reviewed exit | Product — stable surface |
-| [`timeout/`](timeout/README.md) | Tool-call `tools/execute` deadline enforcement | Product — stable surface |
-| [`guard/`](guard/README.md) | Loop-hygiene advisory repeat-call reminders | Product — stable surface |
+| [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders + the `tools/execute` deadline enforcer | Product — stable surface |
 | [`bundle/`](bundle/README.md) | Installable `dsh --profile` patch layers | Product — stable surface |
-| [`cordis/`](cordis/README.md) | Cordis runtime integration: self-inspection, temporary Plugins, restricted repository Plugin loading | Product — stable surface |
+| [`self-modification/`](self-modification/README.md) | The agent modifies its own runtime: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) and restricted repository Plugin loading | Product — stable surface |
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session/`](session/README.md) | Durable session data plane: persistence seam + JSONL/SQLite backends, projection seam, log-backed titles, session reporting | Product — stable surface |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable surface |
diff --git a/packages/README.zh.md b/packages/README.zh.md
index bf2bf43779..4e99dd9313 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -34,10 +34,9 @@
 | [`spill/`](spill/README.md) | 溢出能力系列：存储 seam、本地实现、工具结果溢出策略 | 产品：稳定表面 |
 | [`todo/`](todo/README.md) | 面向模型的 `todo_write` 工具 | 产品：稳定表面 |
 | [`plan/`](plan/README.md) | Plan 协作状态，提供直接进入命令与经评审的退出 | 产品：稳定表面 |
-| [`timeout/`](timeout/README.md) | 工具调用 `tools/execute` 截止时间强制执行 | 产品：稳定表面 |
-| [`guard/`](guard/README.md) | 循环卫生建议性重复调用提醒 | 产品：稳定表面 |
+| [`guard/`](guard/README.md) | 循环卫生守卫：建议性重复调用提醒 + `tools/execute` 截止时间强制执行器 | 产品：稳定表面 |
 | [`bundle/`](bundle/README.md) | 可安装的 `dsh --profile` 补丁层 | 产品：稳定表面 |
-| [`cordis/`](cordis/README.md) | Cordis 运行时集成：自检、临时 Plugin、受限 repository Plugin 加载 | 产品：稳定表面 |
+| [`self-modification/`](self-modification/README.md) | agent 修改自身运行时：检查实时运行时的插件与服务，挂载／卸载模型所写插件（[设计](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)），以及受限 repository Plugin 加载 | 产品：稳定表面 |
 | [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定表面 |
 | [`session/`](session/README.md) | 持久会话数据平面：持久化 seam + JSONL/SQLite 后端、投影 seam、日志支持的标题、会话上报 | 产品：稳定表面 |
 | [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 |
diff --git a/packages/boot/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts
index 5f90a5ee30..dec77aecab 100644
--- a/packages/boot/app-boot/src/index.ts
+++ b/packages/boot/app-boot/src/index.ts
@@ -641,7 +641,7 @@ export function assertEntriesLoaded(ctx: Context, binName: string): void {
 
 /**
  * Value mirrors used because Cordis's const enum has no runtime object to import.
- * Keep aligned with `packages/cordis/tool-cordis/src/fiber-state.ts` and
+ * Keep aligned with `packages/self-modification/tool-cordis/src/fiber-state.ts` and
  * `packages/client/web/src/loader-status.ts`.
  */
 const FIBER_PENDING = 0 as FiberState.PENDING
diff --git a/packages/cordis/README.md b/packages/cordis/README.md
deleted file mode 100644
index e8b0790f91..0000000000
--- a/packages/cordis/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# packages/cordis — Cordis runtime integration
-
-English | [中文](README.zh.md)
-
-Plugins that integrate Harness-owned formats with the Cordis runtime: the self-referential model toolset and the restricted repository Plugin runtime.
-
-| Package | Role | ctx key |
-|---|---|---|
-| [`tool-cordis/`](tool-cordis/README.md) | Model-facing runtime inspection and temporary-plugin tools | registers on `ctx.tools` |
-| [`repository-plugin/`](repository-plugin/README.md) | Repository skill and MCP composition | registers a Loader builtin |
diff --git a/packages/cordis/README.zh.md b/packages/cordis/README.zh.md
deleted file mode 100644
index c452f9a7ef..0000000000
--- a/packages/cordis/README.zh.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# packages/cordis — Cordis 运行时集成
-
-[English](README.md) | 中文
-
-把 Harness 所有的格式与 Cordis 运行时集成的插件：自指的面向模型工具集，以及受限的 repository Plugin 运行时。
-
-| 包 | 职责 | ctx key |
-|---|---|---|
-| [`tool-cordis/`](tool-cordis/README.md) | 面向模型的运行时检查和临时插件工具 | 注册到 `ctx.tools` |
-| [`repository-plugin/`](repository-plugin/README.md) | repository skill 与 MCP 组合 | 注册一个 Loader builtin |
diff --git a/packages/guard/README.i18n.yaml b/packages/guard/README.i18n.yaml
index 637a36063e..8251a76ed5 100644
--- a/packages/guard/README.i18n.yaml
+++ b/packages/guard/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/guard/README.md
-README.md: 8da2f2ddcc1432e7963e600b35549f5e26121af2
-README.zh.md: aa8b5bd1f7d10d90d1dc84d07a7aad81bfb4259c
+README.md: 5791474a2fd6aeda728d4c335c930069ade6e023
+README.zh.md: 82d779d2f1834317672b8fb03f2a4a875bb566fc
diff --git a/packages/guard/README.md b/packages/guard/README.md
index 8da2f2ddcc..5791474a2f 100644
--- a/packages/guard/README.md
+++ b/packages/guard/README.md
@@ -2,8 +2,9 @@
 
 English | [中文](README.zh.md)
 
-Behavioral guard plugins watch the agent loop for unproductive patterns and nudge the model back on course. A guard is a self-contained consumer of core seams, not a swappable capability.
+Behavioral guard plugins watch the agent loop for unproductive patterns and enforce per-call budgets. A guard is a self-contained consumer of core seams, not a swappable capability.
 
 | Package | Role | ctx key |
 |---|---|---|
 | [`repeat-tool-guard/`](repeat-tool-guard/README.md) | Advisory reminders for repeated tool calls | listens on tool and agent events |
+| [`timeout-policy/`](timeout-policy/README.md) | Arms per-call tool deadlines as deployment policy | registers a `tools/execute` listener |
diff --git a/packages/guard/README.zh.md b/packages/guard/README.zh.md
index aa8b5bd1f7..82d779d2f1 100644
--- a/packages/guard/README.zh.md
+++ b/packages/guard/README.zh.md
@@ -2,8 +2,9 @@
 
 [English](README.md) | 中文
 
-行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并推动模型回到正轨。guard 是 core seam 的自包含消费方，而非可替换能力。
+行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并强制执行单次调用预算。guard 是 core seam 的自包含消费方，而非可替换能力。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
 | [`repeat-tool-guard/`](repeat-tool-guard/README.md) | 针对重复工具调用的建议性提醒 | 监听工具和 agent 事件 |
+| [`timeout-policy/`](timeout-policy/README.md) | 以部署策略形式设置单次工具调用截止时间 | 注册 `tools/execute` 监听器 |
diff --git a/packages/timeout/timeout-policy/README.i18n.yaml b/packages/guard/timeout-policy/README.i18n.yaml
similarity index 79%
rename from packages/timeout/timeout-policy/README.i18n.yaml
rename to packages/guard/timeout-policy/README.i18n.yaml
index 377d2c528d..3c41810118 100644
--- a/packages/timeout/timeout-policy/README.i18n.yaml
+++ b/packages/guard/timeout-policy/README.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 packages/timeout/timeout-policy/README.md
+#   pnpm run verify-translation-pairing --write packages/guard/timeout-policy/README.md
 README.md: 3e5769e2f8b95392e9d489659c6bae634ab3ff18
 README.zh.md: bfba62cdfae8bb956aec43bcf6e8df12407d8ba2
diff --git a/packages/timeout/timeout-policy/README.md b/packages/guard/timeout-policy/README.md
similarity index 100%
rename from packages/timeout/timeout-policy/README.md
rename to packages/guard/timeout-policy/README.md
diff --git a/packages/timeout/timeout-policy/README.zh.md b/packages/guard/timeout-policy/README.zh.md
similarity index 100%
rename from packages/timeout/timeout-policy/README.zh.md
rename to packages/guard/timeout-policy/README.zh.md
diff --git a/packages/timeout/timeout-policy/package.json b/packages/guard/timeout-policy/package.json
similarity index 100%
rename from packages/timeout/timeout-policy/package.json
rename to packages/guard/timeout-policy/package.json
diff --git a/packages/timeout/timeout-policy/src/index.ts b/packages/guard/timeout-policy/src/index.ts
similarity index 91%
rename from packages/timeout/timeout-policy/src/index.ts
rename to packages/guard/timeout-policy/src/index.ts
index 61470ea6af..1c18fa5e13 100644
--- a/packages/timeout/timeout-policy/src/index.ts
+++ b/packages/guard/timeout-policy/src/index.ts
@@ -2,6 +2,12 @@
  * Cooperative tool-call timeout enforcer. A tool declares `timeoutMs` and
  * promises to honor `exec.signal`; this wrapper arms that deadline and maps its
  * own expiry to `TOOL_TIMEOUT` without racing or abandoning the tool promise.
+ *
+ * FIXME: settle the intended `@deepseek-ai/dsh-timeout-guard` rename before the
+ * first tagged release — suggestion only, aligning the name with its `guard/`
+ * home; decide at resolution time
+ * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ *
  * @module @deepseek-ai/dsh-timeout-policy
  */
 
diff --git a/packages/timeout/timeout-policy/src/invariant.ts b/packages/guard/timeout-policy/src/invariant.ts
similarity index 100%
rename from packages/timeout/timeout-policy/src/invariant.ts
rename to packages/guard/timeout-policy/src/invariant.ts
diff --git a/packages/timeout/timeout-policy/tests/timeout-policy.spec.ts b/packages/guard/timeout-policy/tests/timeout-policy.spec.ts
similarity index 100%
rename from packages/timeout/timeout-policy/tests/timeout-policy.spec.ts
rename to packages/guard/timeout-policy/tests/timeout-policy.spec.ts
diff --git a/packages/timeout/timeout-policy/tsconfig.json b/packages/guard/timeout-policy/tsconfig.json
similarity index 100%
rename from packages/timeout/timeout-policy/tsconfig.json
rename to packages/guard/timeout-policy/tsconfig.json
diff --git a/packages/interaction/permission/README.i18n.yaml b/packages/interaction/permission/README.i18n.yaml
index b5883174dc..34533f9da4 100644
--- a/packages/interaction/permission/README.i18n.yaml
+++ b/packages/interaction/permission/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/interaction/permission/README.md
-README.md: 814085ed6f2c9650854f377e1c97e442fc4211a4
-README.zh.md: 36880d6b8c3f0b39b88db1abb02534f30e3355fa
+README.md: 4f7f560bb81eaad3b6b95b2742432fa252682d5a
+README.zh.md: 79d0ce9c095d3426f3219f04d9cb7ec3b161a184
diff --git a/packages/interaction/user-interaction/README.i18n.yaml b/packages/interaction/user-interaction/README.i18n.yaml
index f467aaf4e1..feab1813a7 100644
--- a/packages/interaction/user-interaction/README.i18n.yaml
+++ b/packages/interaction/user-interaction/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/interaction/user-interaction/README.md
-README.md: d234d6677bdd772f1bbd2c979c0d41f90aef5c32
-README.zh.md: c89210b6955a661313ca9e0e82e43da5a4d1db79
+README.md: d62e75d110b8be339c5f9449b0834320f695ac99
+README.zh.md: 55258e85e56df2375ed8f195fa0b3b731a9cb816
diff --git a/packages/scaffold/protocol/README.i18n.yaml b/packages/scaffold/protocol/README.i18n.yaml
index df0623573b..b77c8fce63 100644
--- a/packages/scaffold/protocol/README.i18n.yaml
+++ b/packages/scaffold/protocol/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/scaffold/protocol/README.md
-README.md: dc42f385f6e7fd6327ca79887d3cf22d7c34ccdf
-README.zh.md: a292120be8b5b09aaadb05f9dbc272a51bd74831
+README.md: 35b62d2ffc43c54dc81f6a5ecfb1a0ef4294439d
+README.zh.md: a02ba94e7d8fae19bff48d8fda363e23fc173850
diff --git a/packages/scaffold/server/README.i18n.yaml b/packages/scaffold/server/README.i18n.yaml
index 0672ad22a6..46a18ec199 100644
--- a/packages/scaffold/server/README.i18n.yaml
+++ b/packages/scaffold/server/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/scaffold/server/README.md
-README.md: 7ada4fbe6a53e90fcd45c20d9472cb87dbf6b4cf
-README.zh.md: b8362f7762b963ed6caff1b2ba87421152ecb483
+README.md: e0e06e27320ab41f131a1a36a7ccbd26271ce67c
+README.zh.md: ed87a869180571a3cbb51c2ce92a0647e545ca3a
diff --git a/packages/cordis/README.i18n.yaml b/packages/self-modification/README.i18n.yaml
similarity index 55%
rename from packages/cordis/README.i18n.yaml
rename to packages/self-modification/README.i18n.yaml
index 2eacddb52c..9a6a070b95 100644
--- a/packages/cordis/README.i18n.yaml
+++ b/packages/self-modification/README.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 packages/cordis/README.md
-README.md: e8b0790f911d1acc1216d412191ca967e0e1ac27
-README.zh.md: c452f9a7ef69e7f5af8900153271d500f19f9e47
+#   pnpm run verify-translation-pairing --write packages/self-modification/README.md
+README.md: 53f700993cce8df8729fba5a92a9498fff2412cd
+README.zh.md: 9874ead263e9860b94992cb176be3c6f8c454ece
diff --git a/packages/self-modification/README.md b/packages/self-modification/README.md
new file mode 100644
index 0000000000..53f700993c
--- /dev/null
+++ b/packages/self-modification/README.md
@@ -0,0 +1,10 @@
+# self-modification/ — the agent modifies its own runtime
+
+English | [中文](README.zh.md)
+
+Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service surface, mount model-written plugins, and dispose them again — plus the restricted repository Plugin runtime. The group is the landing zone for future self-modification packages. Design home: [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`tool-cordis/`](tool-cordis/README.md) | Model-facing runtime inspection and temporary-plugin tools | registers on `ctx.tools` |
+| [`repository-plugin/`](repository-plugin/README.md) | Repository skill and MCP composition | registers a Loader builtin |
diff --git a/packages/self-modification/README.zh.md b/packages/self-modification/README.zh.md
new file mode 100644
index 0000000000..9874ead263
--- /dev/null
+++ b/packages/self-modification/README.zh.md
@@ -0,0 +1,10 @@
+# self-modification/：agent 修改自身运行时
+
+[English](README.md) | 中文
+
+这些面向模型的工具作用于 agent（智能体）自身所在的实时 Cordis 运行时，可检查已加载的插件和服务接口、挂载模型编写的插件，并将其 dispose（资源释放）——外加受限 repository Plugin 运行时。该组也是未来自我修改类包的落点。设计说明见[工具集 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
+
+| 包（package） | 角色 | ctx 键 |
+|---|---|---|
+| [`tool-cordis/`](tool-cordis/README.md) | `cordis_inspect`／`cordis_mount`／`cordis_unmount` 工具：读取当前进程运行时，并在一个自有分组 fiber 下管理内存中的临时插件 | 注册到 `ctx.tools` |
+| [`repository-plugin/`](repository-plugin/README.md) | 通过 DSH 自有子 Plugin 准备并挂载静态 repository skills 与通用 `.mcp.json` server | 注册一个 Loader builtin |
diff --git a/packages/cordis/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
similarity index 77%
rename from packages/cordis/repository-plugin/README.i18n.yaml
rename to packages/self-modification/repository-plugin/README.i18n.yaml
index daf43fa018..e0ce60a641 100644
--- a/packages/cordis/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/README.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 packages/cordis/repository-plugin/README.md
+#   pnpm run verify-translation-pairing --write packages/self-modification/repository-plugin/README.md
 README.md: 33cd763d7dbe21b72f9e604b7b2e313081cf656f
 README.zh.md: 903dfbe601cc76acb0c1e87453dc03ef0321409b
diff --git a/packages/cordis/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
similarity index 100%
rename from packages/cordis/repository-plugin/README.md
rename to packages/self-modification/repository-plugin/README.md
diff --git a/packages/cordis/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
similarity index 100%
rename from packages/cordis/repository-plugin/README.zh.md
rename to packages/self-modification/repository-plugin/README.zh.md
diff --git a/packages/cordis/repository-plugin/package.json b/packages/self-modification/repository-plugin/package.json
similarity index 100%
rename from packages/cordis/repository-plugin/package.json
rename to packages/self-modification/repository-plugin/package.json
diff --git a/packages/cordis/repository-plugin/src/bin.ts b/packages/self-modification/repository-plugin/src/bin.ts
similarity index 100%
rename from packages/cordis/repository-plugin/src/bin.ts
rename to packages/self-modification/repository-plugin/src/bin.ts
diff --git a/packages/cordis/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
similarity index 100%
rename from packages/cordis/repository-plugin/src/format.ts
rename to packages/self-modification/repository-plugin/src/format.ts
diff --git a/packages/cordis/repository-plugin/src/index.ts b/packages/self-modification/repository-plugin/src/index.ts
similarity index 100%
rename from packages/cordis/repository-plugin/src/index.ts
rename to packages/self-modification/repository-plugin/src/index.ts
diff --git a/packages/cordis/repository-plugin/src/invariant.ts b/packages/self-modification/repository-plugin/src/invariant.ts
similarity index 100%
rename from packages/cordis/repository-plugin/src/invariant.ts
rename to packages/self-modification/repository-plugin/src/invariant.ts
diff --git a/packages/cordis/repository-plugin/src/mcp.ts b/packages/self-modification/repository-plugin/src/mcp.ts
similarity index 100%
rename from packages/cordis/repository-plugin/src/mcp.ts
rename to packages/self-modification/repository-plugin/src/mcp.ts
diff --git a/packages/cordis/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
similarity index 98%
rename from packages/cordis/repository-plugin/src/source.ts
rename to packages/self-modification/repository-plugin/src/source.ts
index 3ccddc6c52..0befb82e42 100644
--- a/packages/cordis/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -11,7 +11,7 @@ import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { PREPARED_ENTRY_FILENAME } from './format.ts'
 
 // Value mirror: Cordis's const enum has no runtime object to import. Keep
-// aligned with `packages/cordis/tool-cordis/src/fiber-state.ts`.
+// aligned with `packages/self-modification/tool-cordis/src/fiber-state.ts`.
 const FIBER_ACTIVE = 2 as FiberState.ACTIVE
 
 /** Directory under the Harness home containing immutable repository generations. */
diff --git a/packages/cordis/repository-plugin/tests/mcp-format.spec.ts b/packages/self-modification/repository-plugin/tests/mcp-format.spec.ts
similarity index 100%
rename from packages/cordis/repository-plugin/tests/mcp-format.spec.ts
rename to packages/self-modification/repository-plugin/tests/mcp-format.spec.ts
diff --git a/packages/cordis/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
similarity index 100%
rename from packages/cordis/repository-plugin/tests/repository-plugin.spec.ts
rename to packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
diff --git a/packages/cordis/repository-plugin/tsconfig.json b/packages/self-modification/repository-plugin/tsconfig.json
similarity index 100%
rename from packages/cordis/repository-plugin/tsconfig.json
rename to packages/self-modification/repository-plugin/tsconfig.json
diff --git a/packages/cordis/repository-plugin/tsdown.config.ts b/packages/self-modification/repository-plugin/tsdown.config.ts
similarity index 100%
rename from packages/cordis/repository-plugin/tsdown.config.ts
rename to packages/self-modification/repository-plugin/tsdown.config.ts
diff --git a/packages/cordis/tool-cordis/README.i18n.yaml b/packages/self-modification/tool-cordis/README.i18n.yaml
similarity index 78%
rename from packages/cordis/tool-cordis/README.i18n.yaml
rename to packages/self-modification/tool-cordis/README.i18n.yaml
index fd2b5443ef..c25dda28e3 100644
--- a/packages/cordis/tool-cordis/README.i18n.yaml
+++ b/packages/self-modification/tool-cordis/README.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 packages/cordis/tool-cordis/README.md
+#   pnpm run verify-translation-pairing --write packages/self-modification/tool-cordis/README.md
 README.md: 9986310160c2b56126155a4c3ef84d66018d31c2
 README.zh.md: d955306e1e5d4154f58c771704782ece44a15c99
diff --git a/packages/cordis/tool-cordis/README.md b/packages/self-modification/tool-cordis/README.md
similarity index 100%
rename from packages/cordis/tool-cordis/README.md
rename to packages/self-modification/tool-cordis/README.md
diff --git a/packages/cordis/tool-cordis/README.zh.md b/packages/self-modification/tool-cordis/README.zh.md
similarity index 100%
rename from packages/cordis/tool-cordis/README.zh.md
rename to packages/self-modification/tool-cordis/README.zh.md
diff --git a/packages/cordis/tool-cordis/package.json b/packages/self-modification/tool-cordis/package.json
similarity index 100%
rename from packages/cordis/tool-cordis/package.json
rename to packages/self-modification/tool-cordis/package.json
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/api-catalog.ts
rename to packages/self-modification/tool-cordis/src/api-catalog.ts
diff --git a/packages/cordis/tool-cordis/src/fiber-state.ts b/packages/self-modification/tool-cordis/src/fiber-state.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/fiber-state.ts
rename to packages/self-modification/tool-cordis/src/fiber-state.ts
diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/self-modification/tool-cordis/src/guard.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/guard.ts
rename to packages/self-modification/tool-cordis/src/guard.ts
diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/self-modification/tool-cordis/src/index.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/index.ts
rename to packages/self-modification/tool-cordis/src/index.ts
diff --git a/packages/cordis/tool-cordis/src/inspect.ts b/packages/self-modification/tool-cordis/src/inspect.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/inspect.ts
rename to packages/self-modification/tool-cordis/src/inspect.ts
diff --git a/packages/cordis/tool-cordis/src/invariant.ts b/packages/self-modification/tool-cordis/src/invariant.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/invariant.ts
rename to packages/self-modification/tool-cordis/src/invariant.ts
diff --git a/packages/cordis/tool-cordis/src/mount.ts b/packages/self-modification/tool-cordis/src/mount.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/mount.ts
rename to packages/self-modification/tool-cordis/src/mount.ts
diff --git a/packages/cordis/tool-cordis/src/present.ts b/packages/self-modification/tool-cordis/src/present.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/present.ts
rename to packages/self-modification/tool-cordis/src/present.ts
diff --git a/packages/cordis/tool-cordis/src/sandbox.ts b/packages/self-modification/tool-cordis/src/sandbox.ts
similarity index 100%
rename from packages/cordis/tool-cordis/src/sandbox.ts
rename to packages/self-modification/tool-cordis/src/sandbox.ts
diff --git a/packages/cordis/tool-cordis/tests/cordis-lifecycle.spec.ts b/packages/self-modification/tool-cordis/tests/cordis-lifecycle.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/cordis-lifecycle.spec.ts
rename to packages/self-modification/tool-cordis/tests/cordis-lifecycle.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/cross-mount.spec.ts b/packages/self-modification/tool-cordis/tests/cross-mount.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/cross-mount.spec.ts
rename to packages/self-modification/tool-cordis/tests/cross-mount.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/helpers.ts b/packages/self-modification/tool-cordis/tests/helpers.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/helpers.ts
rename to packages/self-modification/tool-cordis/tests/helpers.ts
diff --git a/packages/cordis/tool-cordis/tests/inspect.spec.ts b/packages/self-modification/tool-cordis/tests/inspect.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/inspect.spec.ts
rename to packages/self-modification/tool-cordis/tests/inspect.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/integration.spec.ts b/packages/self-modification/tool-cordis/tests/integration.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/integration.spec.ts
rename to packages/self-modification/tool-cordis/tests/integration.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/self-modification/tool-cordis/tests/mount.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/mount.spec.ts
rename to packages/self-modification/tool-cordis/tests/mount.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/present.spec.ts b/packages/self-modification/tool-cordis/tests/present.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/present.spec.ts
rename to packages/self-modification/tool-cordis/tests/present.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts b/packages/self-modification/tool-cordis/tests/sandbox-context.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/sandbox-context.spec.ts
rename to packages/self-modification/tool-cordis/tests/sandbox-context.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts b/packages/self-modification/tool-cordis/tests/tool-cordis.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/tool-cordis.spec.ts
rename to packages/self-modification/tool-cordis/tests/tool-cordis.spec.ts
diff --git a/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts b/packages/self-modification/tool-cordis/tests/unmount-hmr.spec.ts
similarity index 100%
rename from packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts
rename to packages/self-modification/tool-cordis/tests/unmount-hmr.spec.ts
diff --git a/packages/cordis/tool-cordis/tsconfig.json b/packages/self-modification/tool-cordis/tsconfig.json
similarity index 100%
rename from packages/cordis/tool-cordis/tsconfig.json
rename to packages/self-modification/tool-cordis/tsconfig.json
diff --git a/packages/timeout/README.i18n.yaml b/packages/timeout/README.i18n.yaml
deleted file mode 100644
index 33a7a5b26d..0000000000
--- a/packages/timeout/README.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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 packages/timeout/README.md
-README.md: d9d8e8a829d8d466d1cc3e42a6c32ac4b3db428b
-README.zh.md: c5920258ade7022fb5b28a351ba060eb56e8bc3c
diff --git a/packages/timeout/README.md b/packages/timeout/README.md
deleted file mode 100644
index d9d8e8a829..0000000000
--- a/packages/timeout/README.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# timeout/ — tool-call timeout policy
-
-English | [中文](README.zh.md)
-
-This group applies deployment-configured deadlines to model-facing tool calls. Capabilities remain responsible for terminating their own work.
-
-| Package | Role |
-|---|---|
-| [`timeout-policy/`](timeout-policy/README.md) | Enforces configured per-tool call deadlines |
-
-The pure timing primitives live in [`util/timeout`](../util/timeout/README.md). See the [timeout-library decision](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md).
diff --git a/packages/timeout/README.zh.md b/packages/timeout/README.zh.md
deleted file mode 100644
index c5920258ad..0000000000
--- a/packages/timeout/README.zh.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# timeout/：工具调用超时策略
-
-[English](README.md) | 中文
-
-本分组将部署配置的截止时间应用于面向模型的工具调用。各项能力仍负责终止自身工作。
-
-| 包 | 职责 |
-|---|---|
-| [`timeout-policy/`](timeout-policy/README.md) | 强制执行配置的逐工具调用截止时间 |
-
-纯计时原语位于 [`util/timeout`](../util/timeout/README.md)。参见[超时库决策](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)。
diff --git a/packages/typert/generator/tests/cordis-catalog.spec.ts b/packages/typert/generator/tests/cordis-catalog.spec.ts
index 6e6b93dfdc..644bb28de2 100644
--- a/packages/typert/generator/tests/cordis-catalog.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog.spec.ts
@@ -18,7 +18,7 @@ describe('Typert-backed Cordis catalog', () => {
     expect(renderEvents([...model.events], CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-catalog/events.md'))
     expect(renderServices([...model.services], CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-catalog/services.md'))
     expect(projector.renderRuntimeApi(model)).toBe(
-      expected('packages/cordis/tool-cordis/src/api-catalog.ts'),
+      expected('packages/self-modification/tool-cordis/src/api-catalog.ts'),
     )
   })
 })
diff --git a/packages/web/tool-web/README.i18n.yaml b/packages/web/tool-web/README.i18n.yaml
index eb57a7b20a..4751678c04 100644
--- a/packages/web/tool-web/README.i18n.yaml
+++ b/packages/web/tool-web/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/web/tool-web/README.md
-README.md: 791ea87c655444e639ef85ccce737066ead8b749
-README.zh.md: ffcf2d9813dcb94d8106b2c7d5f8ee9fc25e1aaa
+README.md: 646601bb5bd6c27876918b7aca49962ae34bae33
+README.zh.md: 192b7020f5fac026f325448630b2e17d7ce6a0c4
diff --git a/packages/web/tool-web/README.md b/packages/web/tool-web/README.md
index 791ea87c65..646601bb5b 100644
--- a/packages/web/tool-web/README.md
+++ b/packages/web/tool-web/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The model-facing web tool suite — `web_search` and `web_fetch` — over the [web capability seam](../web/README.md) (`ctx.web`). It owns model-facing concerns only: tool names, JSON schemas, snake_case argument names, prompt sections, the result-count bound, result formatting, HTML→markdown presentation, and the UI presentation projection — `presentCall`, `presentResult` (a `card: 'web'` result card discriminated by `kind: 'search' | 'fetch'`), and the `output.presentationMeta` that carries the structured search sources or the fetch summary the lossy render text cannot (see the [web-result-card Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card.md)). All web access goes through `ctx.web`; this package never imports a concrete provider. Neither tool exposes a model-facing timeout — each tool's cooperative tool-call budget is declared here via config (`fetchTimeoutMs`/`searchTimeoutMs`, attached as `ToolDefinition.timeoutMs`) and enforced by [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md) (a `tools/execute` wrapper); each tool just forwards `exec.signal` to the seam.
+The model-facing web tool suite — `web_search` and `web_fetch` — over the [web capability seam](../web/README.md) (`ctx.web`). It owns model-facing concerns only: tool names, JSON schemas, snake_case argument names, prompt sections, the result-count bound, result formatting, HTML→markdown presentation, and the UI presentation projection — `presentCall`, `presentResult` (a `card: 'web'` result card discriminated by `kind: 'search' | 'fetch'`), and the `output.presentationMeta` that carries the structured search sources or the fetch summary the lossy render text cannot (see the [web-result-card Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card.md)). All web access goes through `ctx.web`; this package never imports a concrete provider. Neither tool exposes a model-facing timeout — each tool's cooperative tool-call budget is declared here via config (`fetchTimeoutMs`/`searchTimeoutMs`, attached as `ToolDefinition.timeoutMs`) and enforced by [`@deepseek-ai/dsh-timeout-policy`](../../guard/timeout-policy/README.md) (a `tools/execute` wrapper); each tool just forwards `exec.signal` to the seam.
 
 Each tool is registered independently; a product that wants only one disables the other via config (`{ search: false }` / `{ fetch: false }`). Search guidance mentions `web_fetch` only when fetch is also config-enabled; a search-only composition instead tells the model to use returned snippets and cite their URLs.
 
@@ -28,7 +28,7 @@ The normalized seam results are also the canonical tool values: `WebSearchResult
 | `searchTimeoutMs` | `30000` | Cooperative tool-call timeout budget (ms) for `web_search`. |
 | `fetchMaxOutputChars` | `200000` | Cap on source characters converted synchronously and on one complete `web_fetch` output (header, rendered body, and footer); a cut body gets the truncation notice when it fits. |
 
-`fetchTimeoutMs`/`searchTimeoutMs` declare each tool's cooperative timeout budget (attached as `ToolDefinition.timeoutMs`), enforced by [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md); the model-facing schema exposes no timeout argument. `fetchMaxOutputChars` bounds both synchronous conversion work and the complete rendered result: only that many source characters are converted, and the header, converted prefix, and truncation notice are then capped together. The default leaves headroom above the local provider's 100,000-character body cap, but rendered expansion can still make the final bound truncate the result.
+`fetchTimeoutMs`/`searchTimeoutMs` declare each tool's cooperative timeout budget (attached as `ToolDefinition.timeoutMs`), enforced by [`@deepseek-ai/dsh-timeout-policy`](../../guard/timeout-policy/README.md); the model-facing schema exposes no timeout argument. `fetchMaxOutputChars` bounds both synchronous conversion work and the complete rendered result: only that many source characters are converted, and the header, converted prefix, and truncation notice are then capped together. The default leaves headroom above the local provider's 100,000-character body cap, but rendered expansion can still make the final bound truncate the result.
 
 ```yaml
 - id: tool-web
diff --git a/packages/web/tool-web/README.zh.md b/packages/web/tool-web/README.zh.md
index ffcf2d9813..192b7020f5 100644
--- a/packages/web/tool-web/README.zh.md
+++ b/packages/web/tool-web/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向模型的 web 工具套件 `web_search` 与 `web_fetch`，构建于 [web 能力 seam](../web/README.md)（`ctx.web`）之上。它只负责面向模型的事项：工具名称、JSON Schema、snake_case 参数名称、提示词区段、结果数量上限、结果格式、HTML→markdown 呈现，以及 UI 呈现投影——`presentCall`、`presentResult`（以 `kind: 'search' | 'fetch'` 区分的 `card: 'web'` 结果卡片），以及承载有损渲染文本无法携带的结构化搜索来源或抓取摘要的 `output.presentationMeta`（见 [web-result-card Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card.md)）。所有 web 访问都通过 `ctx.web`；该包绝不导入具体提供方。两个工具都不公开面向模型的超时：每个工具的协作式工具调用超时预算通过配置在此声明（`fetchTimeoutMs`／`searchTimeoutMs`，附加为 `ToolDefinition.timeoutMs`），由 [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md)（`tools/execute` 包装层）强制执行；每个工具只把 `exec.signal` 转发给 seam。
+面向模型的 web 工具套件 `web_search` 与 `web_fetch`，构建于 [web 能力 seam](../web/README.md)（`ctx.web`）之上。它只负责面向模型的事项：工具名称、JSON Schema、snake_case 参数名称、提示词区段、结果数量上限、结果格式、HTML→markdown 呈现，以及 UI 呈现投影——`presentCall`、`presentResult`（以 `kind: 'search' | 'fetch'` 区分的 `card: 'web'` 结果卡片），以及承载有损渲染文本无法携带的结构化搜索来源或抓取摘要的 `output.presentationMeta`（见 [web-result-card Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card.md)）。所有 web 访问都通过 `ctx.web`；该包绝不导入具体提供方。两个工具都不公开面向模型的超时：每个工具的协作式工具调用超时预算通过配置在此声明（`fetchTimeoutMs`／`searchTimeoutMs`，附加为 `ToolDefinition.timeoutMs`），由 [`@deepseek-ai/dsh-timeout-policy`](../../guard/timeout-policy/README.md)（`tools/execute` 包装层）强制执行；每个工具只把 `exec.signal` 转发给 seam。
 
 每个工具独立注册；只需要其中一个工具的产品可以通过配置禁用另一个（`{ search: false }`／`{ fetch: false }`）。仅当抓取也通过配置启用时，搜索指引才会提及 `web_fetch`；仅启用搜索的组合则会要求模型使用返回的 snippet 并引用其 URL。
 
@@ -28,7 +28,7 @@
 | `searchTimeoutMs` | `30000` | `web_search` 的协作式工具调用超时预算（ms）。 |
 | `fetchMaxOutputChars` | `200000` | 同步转换的源字符数与单次完整 `web_fetch` 输出的上限（状态头、渲染后的主体与页脚合并计算）；主体被截断时，在能容纳的情况下附带截断提示。 |
 
-`fetchTimeoutMs`／`searchTimeoutMs` 声明每个工具的协作式超时预算（附加为 `ToolDefinition.timeoutMs`），由 [`@deepseek-ai/dsh-timeout-policy`](../../timeout/timeout-policy/README.md) 强制执行；面向模型的 schema 不公开超时参数。`fetchMaxOutputChars` 同时限制同步转换工作量和完整渲染结果：只转换至多该数量的源字符，随后对状态头、转换后的前缀和截断提示合并设限。默认值为本地提供方的 100,000 字符主体上限留出余量，但渲染膨胀仍可能使最终上限截断结果。
+`fetchTimeoutMs`／`searchTimeoutMs` 声明每个工具的协作式超时预算（附加为 `ToolDefinition.timeoutMs`），由 [`@deepseek-ai/dsh-timeout-policy`](../../guard/timeout-policy/README.md) 强制执行；面向模型的 schema 不公开超时参数。`fetchMaxOutputChars` 同时限制同步转换工作量和完整渲染结果：只转换至多该数量的源字符，随后对状态头、转换后的前缀和截断提示合并设限。默认值为本地提供方的 100,000 字符主体上限留出余量，但渲染膨胀仍可能使最终上限截断结果。
 
 ```yaml
 - id: tool-web
diff --git a/packages/web/tool-web/tsconfig.json b/packages/web/tool-web/tsconfig.json
index f6684272ce..232d6f6c50 100644
--- a/packages/web/tool-web/tsconfig.json
+++ b/packages/web/tool-web/tsconfig.json
@@ -25,7 +25,7 @@
       "path": "../../core/system-prompt"
     },
     {
-      "path": "../../timeout/timeout-policy"
+      "path": "../../guard/timeout-policy"
     },
     {
       "path": "../web"
diff --git a/packages/web/web-fetch-local/README.i18n.yaml b/packages/web/web-fetch-local/README.i18n.yaml
index 0e487b6ef5..5511f72975 100644
--- a/packages/web/web-fetch-local/README.i18n.yaml
+++ b/packages/web/web-fetch-local/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/web/web-fetch-local/README.md
-README.md: 8cadba2de7a2708252ebc7143840825fd4fe4549
-README.zh.md: b3f0707c448da7abaaafe2cdcf2520914ffff932
+README.md: 531bfc94a4b2867b1a81d2e0b398ec403186b347
+README.zh.md: 260227679b72ec993dbb9e42a9d2a814bf691e2c
diff --git a/packages/web/web-fetch-local/README.md b/packages/web/web-fetch-local/README.md
index 8cadba2de7..531bfc94a4 100644
--- a/packages/web/web-fetch-local/README.md
+++ b/packages/web/web-fetch-local/README.md
@@ -10,7 +10,7 @@ This is an **implementation** package: it registers a provider into `ctx.web`, i
 
 The provider owns **safe resource retrieval**: URL validation, HTTP transport, redirect policy, a resource-backstop timeout, abort propagation, byte caps, charset decoding, content-type classification, and binary rejection. `@deepseek-ai/dsh-tool-web` owns **presentation** (HTML→markdown, truncation formatting). A non-2xx HTTP response is a *result* (status code + decoded body), not an error; `WebError` is reserved for failures to safely retrieve or represent the resource.
 
-The provider's `timeoutMs` is a resource backstop for direct `ctx.web.fetch()` callers and misconfigured deployments, not the model-facing tool-call budget. [`dsh-timeout-policy`](../../timeout/timeout-policy/README.md) owns the `web_fetch` tool-call budget by arming `exec.signal`.
+The provider's `timeoutMs` is a resource backstop for direct `ctx.web.fetch()` callers and misconfigured deployments, not the model-facing tool-call budget. [`dsh-timeout-policy`](../../guard/timeout-policy/README.md) owns the `web_fetch` tool-call budget by arming `exec.signal`.
 
 A shipping web-tool deployment sets the provider backstop above the tool budget, so model calls normally return `TOOL_TIMEOUT`. If the outer deadline reaches the provider first, the provider reports `WEB_ABORTED` and the outer policy replaces it with `TOOL_TIMEOUT`. `WEB_FETCH_TIMEOUT` therefore identifies a direct seam caller whose provider budget elapsed.
 
diff --git a/packages/web/web-fetch-local/README.zh.md b/packages/web/web-fetch-local/README.zh.md
index b3f0707c44..260227679b 100644
--- a/packages/web/web-fetch-local/README.zh.md
+++ b/packages/web/web-fetch-local/README.zh.md
@@ -10,7 +10,7 @@
 
 提供方拥有**安全资源获取**：URL 验证、HTTP 传输、重定向策略、资源兜底超时、中止传播、字节上限、charset 解码、内容类型分类与二进制拒绝。`@deepseek-ai/dsh-tool-web` 拥有**呈现**（HTML→markdown、截断格式）。非 2xx HTTP 响应是*结果*（状态码 + 解码主体），不是错误；`WebError` 只用于无法安全获取或表示资源的失败。
 
-提供方的 `timeoutMs` 是直接 `ctx.web.fetch()` 调用方和配置有误的部署所用的资源兜底，不是面向模型的工具调用预算。[`dsh-timeout-policy`](../../timeout/timeout-policy/README.md) 拥有 `web_fetch` 工具调用预算，并让 `exec.signal` 在超时时触发，以强制执行该预算。
+提供方的 `timeoutMs` 是直接 `ctx.web.fetch()` 调用方和配置有误的部署所用的资源兜底，不是面向模型的工具调用预算。[`dsh-timeout-policy`](../../guard/timeout-policy/README.md) 拥有 `web_fetch` 工具调用预算，并让 `exec.signal` 在超时时触发，以强制执行该预算。
 
 已交付的 web 工具部署会把提供方兜底设为高于工具预算，因此模型调用通常返回 `TOOL_TIMEOUT`。如果外层截止期限先于提供方的兜底超时触发，提供方会报告 `WEB_ABORTED`，外层策略再将其替换为 `TOOL_TIMEOUT`。因此，`WEB_FETCH_TIMEOUT` 表明直接 seam 调用方的提供方预算已经耗尽。
 
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 08019b567e..302ec7fdd9 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -16,7 +16,7 @@ import { renderCordisCoreApiPages } from './cordis-core-api.ts'
 const root = resolve(import.meta.dirname, '..')
 const OUT_EVENTS = 'docs/cordis-catalog/events.md'
 const OUT_SERVICES = 'docs/cordis-catalog/services.md'
-const OUT_RUNTIME_API = 'packages/cordis/tool-cordis/src/api-catalog.ts'
+const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts'
 
 /** One primary core-data-structures page per project type used by a generated signature. */
 export const LINK_MAP: Readonly<Record<string, string>> = {
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 06475808e1..55ec5eb57f 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -226,7 +226,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
   {
     pkg: '@deepseek-ai/dsh-tool-cordis',
     dir: 'tool-cordis',
-    source: 'packages/cordis/tool-cordis/src/index.ts',
+    source: 'packages/self-modification/tool-cordis/src/index.ts',
     requires: ['ctx.tools'],
     writes: ['tool/call', 'tool/result', 'process-local temporary Plugin lifecycle'],
     async mount(ctx) {
diff --git a/tsconfig.base.json b/tsconfig.base.json
index b748020e11..d8b777a2ad 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -101,10 +101,9 @@
         "./packages/workflow/*/src/invariant.ts",
         "./packages/web/*/src/invariant.ts",
         "./packages/spill/*/src/invariant.ts",
-        "./packages/timeout/*/src/invariant.ts",
         "./packages/todo/*/src/invariant.ts",
         "./packages/bundle/*/src/invariant.ts",
-        "./packages/cordis/*/src/invariant.ts",
+        "./packages/self-modification/*/src/invariant.ts",
         "./packages/sandbox/*/src/invariant.ts",
         "./packages/hooks/*/src/invariant.ts",
         "./packages/session/*/src/invariant.ts",
@@ -210,10 +209,9 @@
         "./packages/workflow/*/src",
         "./packages/web/*/src",
         "./packages/spill/*/src",
-        "./packages/timeout/*/src",
         "./packages/todo/*/src",
         "./packages/bundle/*/src",
-        "./packages/cordis/*/src",
+        "./packages/self-modification/*/src",
         "./packages/sandbox/*/src",
         "./packages/hooks/*/src",
         "./packages/session/*/src",
diff --git a/tsconfig.host.json b/tsconfig.host.json
index c1cc0705cf..31631995cf 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -204,7 +204,7 @@
     { "path": "./packages/spill/spill" },
     { "path": "./packages/spill/spill-local" },
     { "path": "./packages/spill/spill-policy" },
-    { "path": "./packages/timeout/timeout-policy" },
+    { "path": "./packages/guard/timeout-policy" },
     { "path": "./packages/support/invariants" },
     { "path": "./packages/support/agent-loop-testkit" },
     { "path": "./packages/acp/acp" },
@@ -241,8 +241,8 @@
     { "path": "./packages/todo/tool-todo" },
     { "path": "./packages/plan/plan-mode" },
     { "path": "./packages/guard/repeat-tool-guard" },
-    { "path": "./packages/cordis/tool-cordis" },
-    { "path": "./packages/cordis/repository-plugin" },
+    { "path": "./packages/self-modification/tool-cordis" },
+    { "path": "./packages/self-modification/repository-plugin" },
     { "path": "./packages/hooks/hook-protocol" },
     { "path": "./packages/hooks/hooks-claude" },
     { "path": "./packages/hooks/hooks-codex" },

From 36cf4f32f4817d6865c1454d6cd5a18c4bb4cf77 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 03:48:07 +0800
Subject: [PATCH 406/516] docs(agent-note): flip the regrouping note to
 implemented

Move the triplet to implemented/architecture/, rewrite Proposal into a
present-tense Decision, fold Acceptance criteria and Risks into
Consequences (recording what pins the result), retitle the migration
section to what the move actually touched, and repoint the seven
inbound FIXME/README links.
---
 ...026-07-27-tui-chat-channel-module-split.md |    2 +-
 ...-07-27-tui-chat-channel-module-split.zh.md |    2 +-
 ...-07-24-tui-turn-end-stop-reason-notices.md |    2 +-
 ...-24-tui-turn-end-stop-reason-notices.zh.md |    2 +-
 ...17-dedicated-full-screen-tui-front-door.md |    2 +-
 ...dedicated-full-screen-tui-front-door.zh.md |    2 +-
 .../feature/2026-07-20-windows-tui-support.md |    2 +-
 .../2026-07-20-windows-tui-support.zh.md      |    2 +-
 .../2026-07-21-tui-skill-slash-command.md     |    2 +-
 .../2026-07-21-tui-skill-slash-command.zh.md  |    2 +-
 ...-07-27-assistant-timing-header-trailing.md |    2 +-
 ...-27-assistant-timing-header-trailing.zh.md |    2 +-
 ...sh-guided-skill-session-commands.i18n.yaml |    6 +-
 ...07-28-dsh-guided-skill-session-commands.md |    2 +-
 ...28-dsh-guided-skill-session-commands.zh.md |    2 +-
 ...7-26-execa-for-test-subprocess-plumbing.md |    2 +-
 ...6-execa-for-test-subprocess-plumbing.zh.md |    2 +-
 .../2026-07-29-package-regrouping.i18n.yaml   |    6 +
 .../2026-07-29-package-regrouping.md          |   60 +-
 .../2026-07-29-package-regrouping.zh.md       |   52 +-
 ...-yaml-and-user-environment-layer.i18n.yaml |    4 +-
 ...entials-yaml-and-user-environment-layer.md |    4 +-
 ...ials-yaml-and-user-environment-layer.zh.md |    4 +-
 ...-fail-loud-releases-the-terminal.i18n.yaml |    4 +-
 ...6-07-31-fail-loud-releases-the-terminal.md |    2 +-
 ...7-31-fail-loud-releases-the-terminal.zh.md |    2 +-
 ...3-cli-signal-shutdown-escalation.i18n.yaml |    4 +-
 ...26-08-03-cli-signal-shutdown-escalation.md |    2 +-
 ...08-03-cli-signal-shutdown-escalation.zh.md |    2 +-
 ...3-hmr-initial-scan-boot-deadlock.i18n.yaml |    4 +-
 ...26-08-03-hmr-initial-scan-boot-deadlock.md |    2 +-
 ...08-03-hmr-initial-scan-boot-deadlock.zh.md |    2 +-
 .../2026-07-28-feedback-command.i18n.yaml     |    4 +-
 .../feature/2026-07-28-feedback-command.md    |    2 +-
 .../feature/2026-07-28-feedback-command.zh.md |    2 +-
 ...-domain-kv-storage-and-workspace.i18n.yaml |    2 +-
 ...7-24-domain-kv-storage-and-workspace.zh.md |    2 +-
 .../2026-07-29-package-regrouping.i18n.yaml   |    6 -
 AGENTS.md                                     |   26 +-
 apps/cli/reference/README.i18n.yaml           |    4 +-
 apps/cli/reference/README.md                  |    2 +-
 apps/cli/reference/README.zh.md               |    2 +-
 docs/config-catalog.md                        |   62 +-
 docs/cordis-catalog/events.md                 |    6 +-
 docs/cordis-catalog/services.md               |   18 +-
 docs/event-producer-consumer.md               |   28 +-
 docs/module-graph.md                          |  354 +++--
 docs/persistence-catalog.md                   |   12 +-
 examples/web-cordis/README.i18n.yaml          |    4 +-
 examples/web-cordis/README.md                 |    4 +-
 examples/web-cordis/README.zh.md              |    4 +-
 packages/api/remotes/tsconfig.host.json       |    2 +-
 packages/bash/bash-env/tsconfig.json          |    2 +-
 packages/bundle/README.i18n.yaml              |   10 +-
 packages/bundle/README.md                     |    2 +-
 packages/bundle/README.zh.md                  |    2 +-
 .../compact/command-compact/README.i18n.yaml  |    4 +-
 packages/compact/command-compact/README.md    |    2 +-
 packages/compact/command-compact/README.zh.md |    2 +-
 .../credentials-local/README.i18n.yaml        |    4 +-
 .../credentials/credentials-local/README.md   |    2 +-
 .../credentials-local/README.zh.md            |    2 +-
 .../examples/jsonrpc-demo/README.i18n.yaml    |    4 +-
 packages/examples/jsonrpc-demo/README.md      |    4 +-
 packages/examples/jsonrpc-demo/README.zh.md   |    4 +-
 packages/feedback/README.i18n.yaml            |    4 +-
 packages/feedback/README.md                   |    2 +-
 packages/feedback/README.zh.md                |    2 +-
 .../command-feedback/README.i18n.yaml         |    4 +-
 packages/feedback/command-feedback/README.md  |    6 +-
 .../feedback/command-feedback/README.zh.md    |    6 +-
 .../feedback/command-feedback/tsconfig.json   |    2 +-
 packages/goal/command-goal/README.i18n.yaml   |    4 +-
 packages/goal/command-goal/README.md          |    2 +-
 packages/goal/command-goal/README.zh.md       |    2 +-
 packages/guard/timeout-policy/src/index.ts    |    2 +-
 .../interaction/permission/README.i18n.yaml   |    2 +-
 .../user-interaction/README.i18n.yaml         |    4 +-
 packages/plan/plan-mode/README.i18n.yaml      |    4 +-
 packages/plan/plan-mode/README.md             |    2 +-
 packages/plan/plan-mode/README.zh.md          |    2 +-
 packages/scaffold/README.i18n.yaml            |    4 +-
 packages/scaffold/README.md                   |    2 +-
 packages/scaffold/README.zh.md                |    2 +-
 packages/scaffold/client/README.i18n.yaml     |    4 +-
 packages/scaffold/client/README.md            |    2 +-
 packages/scaffold/client/README.zh.md         |    2 +-
 packages/scaffold/helper/src/index.ts         |    2 +-
 packages/scaffold/protocol/README.i18n.yaml   |    4 +-
 packages/scaffold/protocol/README.md          |    6 +-
 packages/scaffold/protocol/README.zh.md       |    6 +-
 packages/scaffold/scripts/src/index.ts        |    2 +-
 packages/scaffold/server/README.i18n.yaml     |    4 +-
 packages/scaffold/server/src/index.ts         |    2 +-
 packages/scaffold/telemetry/src/index.ts      |    3 +-
 .../subagent/subagent-codex/tsconfig.json     |    2 +-
 packages/subagent/subagent/tsconfig.json      |    4 +-
 .../typert/generator/tests/type-model.spec.ts |    4 +-
 packages/util/environment/README.i18n.yaml    |    4 +-
 packages/util/environment/README.md           |    2 +-
 packages/util/environment/README.zh.md        |    2 +-
 pnpm-lock.yaml                                | 1284 ++++++++---------
 .../request-response.expected.json            |    4 +-
 scripts/type-equiv.manifest.json              |    2 +-
 scripts/verify-package-paths.ts               |   16 +-
 105 files changed, 1089 insertions(+), 1112 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
 rename .agents/notes/{proposed => implemented}/architecture/2026-07-29-package-regrouping.md (56%)
 rename .agents/notes/{proposed => implemented}/architecture/2026-07-29-package-regrouping.zh.md (66%)
 delete mode 100644 .agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml

diff --git a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
index 9b2c456d88..3cf9548d4d 100644
--- a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
+++ b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.md
@@ -7,7 +7,7 @@ English | [中文](2026-07-27-tui-chat-channel-module-split.zh.md)
 
 ## Problem
 
-`packages/interaction/tui/src/index.ts` had grown past 2000 lines. Most of it was one `createTuiChat` factory: a ~1600-line closure holding roughly forty mutable variables and as many nested closures. Model selection, the ask-user-question queue, and session resume were tangled into that single scope, so a reader could not follow any one concern without holding the whole file in their head, and unrelated edits collided. A prior pass had grouped `src/` into `components/`, `session/`, `extension/`, but the entry file itself and the loose top-level input files (`autocomplete.ts`, `file-autocomplete.ts`, `skill-invocation.ts`, `xml-tool-output.ts`) were untouched.
+`packages/ui/tui/src/index.ts` had grown past 2000 lines. Most of it was one `createTuiChat` factory: a ~1600-line closure holding roughly forty mutable variables and as many nested closures. Model selection, the ask-user-question queue, and session resume were tangled into that single scope, so a reader could not follow any one concern without holding the whole file in their head, and unrelated edits collided. A prior pass had grouped `src/` into `components/`, `session/`, `extension/`, but the entry file itself and the loose top-level input files (`autocomplete.ts`, `file-autocomplete.ts`, `skill-invocation.ts`, `xml-tool-output.ts`) were untouched.
 
 ## Decision
 
diff --git a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
index 44e8ffeac4..d5de02bd0f 100644
--- a/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
+++ b/.agents/notes/archived/architecture/2026-07-27-tui-chat-channel-module-split.zh.md
@@ -7,7 +7,7 @@ Archived: 2026-08-04
 
 ## Problem
 
-`packages/interaction/tui/src/index.ts` 已超过 2000 行，其中绝大部分是单个 `createTuiChat` 工厂：一个约 1600 行的闭包，持有约四十个可变变量以及同等数量的嵌套闭包。模型选择、ask-user-question 队列、会话恢复都缠绕在这一个作用域里，读者无法在不把整份文件装进脑子的前提下理清任何单一关注点，互不相关的改动也会彼此冲突。此前一轮已把 `src/` 归组为 `components/`、`session/`、`extension/`，但入口文件本身以及散落在顶层的输入相关文件（`autocomplete.ts`、`file-autocomplete.ts`、`skill-invocation.ts`、`xml-tool-output.ts`）未动。
+`packages/ui/tui/src/index.ts` 已超过 2000 行，其中绝大部分是单个 `createTuiChat` 工厂：一个约 1600 行的闭包，持有约四十个可变变量以及同等数量的嵌套闭包。模型选择、ask-user-question 队列、会话恢复都缠绕在这一个作用域里，读者无法在不把整份文件装进脑子的前提下理清任何单一关注点，互不相关的改动也会彼此冲突。此前一轮已把 `src/` 归组为 `components/`、`session/`、`extension/`，但入口文件本身以及散落在顶层的输入相关文件（`autocomplete.ts`、`file-autocomplete.ts`、`skill-invocation.ts`、`xml-tool-output.ts`）未动。
 
 ## Decision
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
index 998e9dfcdc..62784ed7cd 100644
--- a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
+++ b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.md
@@ -11,7 +11,7 @@ The TUI rendered transcript notices for `error`, `aborted`, `max-tokens`, `rejec
 
 ## Decision
 
-The `turn/end` case in `packages/interaction/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.
+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
 
diff --git a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
index ad53755259..162ba4ed44 100644
--- a/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
+++ b/.agents/notes/archived/bug-fix/2026-07-24-tui-turn-end-stop-reason-notices.zh.md
@@ -11,7 +11,7 @@ TUI 会为 `error`、`aborted`、`max-tokens`、`rejected`、`interrupted` 这
 
 ## 决策
 
-`packages/interaction/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 保留现有通知。
+`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 保留现有通知。
 
 ## 备选方案
 
diff --git a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
index 184a05ed23..1a04e738a2 100644
--- a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
+++ b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.md
@@ -15,7 +15,7 @@ The interactive channel must remain a Cordis plugin over the same agent, session
 
 ## Decision
 
-DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior.
+DeepSeek Harness ships [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) as a dedicated Cordis plugin. It owns terminal input and presentation only; agent lifecycle, session persistence, tool execution, and the model-facing question tool remain separate composition entries. The plugin requires both stdin and stdout to be TTYs and fails instead of silently changing to line-oriented behavior.
 
 The package is a terminal front door, not a complete application. A host mounts `@deepseek-ai/dsh-tui` before its configured agent and composes the backends, tools, and policies around it. The product CLI currently ships no terminal composition; non-interactive tasks use headless mode, Web owns the installed human surface, and ACP remains a separate automation protocol.
 
diff --git a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
index 6ac3eefa51..75fc3d47aa 100644
--- a/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
+++ b/.agents/notes/archived/feature/2026-07-17-dedicated-full-screen-tui-front-door.zh.md
@@ -15,7 +15,7 @@ Archived: 2026-08-04
 
 ## 决策
 
-DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。
+DeepSeek Harness 将 [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 作为独立的 Cordis 插件交付。该插件只负责终端输入与呈现；agent 生命周期、会话持久化、工具执行以及模型可见的提问工具仍由不同组合项负责。插件要求 stdin 和 stdout 均为 TTY；条件不满足时会失败，不会静默切换为逐行输出。
 
 该包是终端入口，而不是完整应用。宿主在已配置 agent 之前挂载 `@deepseek-ai/dsh-tui`，并围绕它组合后端、工具和策略。产品 CLI 目前不交付终端组合；非交互任务使用 headless 模式，Web 是已安装产品中面向人的界面，而 ACP 仍是独立的自动化协议。
 
diff --git a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
index 2c8e92671f..9308df7fb4 100644
--- a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
+++ b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.md
@@ -13,7 +13,7 @@ The TUI platform contract must follow the runtime shipped to users rather than t
 
 ## Decision
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) supports interactive terminals on Windows as well as macOS and Linux. The product continues to use pi-tui's `ProcessTerminal`; on Windows it enables virtual-terminal input after raw mode and avoids the Unix-only `SIGWINCH` refresh. DeepSeek Harness adds no platform rejection or reduced Windows mode.
+[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) supports interactive terminals on Windows as well as macOS and Linux. The product continues to use pi-tui's `ProcessTerminal`; on Windows it enables virtual-terminal input after raw mode and avoids the Unix-only `SIGWINCH` refresh. DeepSeek Harness adds no platform rejection or reduced Windows mode.
 
 The real Loader smoke selects a native pseudo-terminal boundary by host. macOS and Linux retain the Python POSIX PTY driver. Windows uses `node-pty` and ConPTY. Both drivers receive the same launch command, environment, terminal dimensions, marker-gated input actions, timeout, expected exit code, and output assertions, and all three smoke scenarios run on every supported platform.
 
diff --git a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
index cb5d05da2b..8b4a1eb4ce 100644
--- a/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
+++ b/.agents/notes/archived/feature/2026-07-20-windows-tui-support.zh.md
@@ -13,7 +13,7 @@ TUI 平台契约必须以交付给用户的运行时为准，而不是取决于
 
 ## 决策
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 在 Windows、macOS 和 Linux 上均支持交互式终端。产品继续使用 pi-tui 的 `ProcessTerminal`；在 Windows 上，它会在进入原始模式后启用虚拟终端输入，并避开仅适用于 Unix 的 `SIGWINCH` 刷新。DeepSeek Harness 不增加平台拒绝逻辑，也不采用功能受限的 Windows 模式。
+[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 在 Windows、macOS 和 Linux 上均支持交互式终端。产品继续使用 pi-tui 的 `ProcessTerminal`；在 Windows 上，它会在进入原始模式后启用虚拟终端输入，并避开仅适用于 Unix 的 `SIGWINCH` 刷新。DeepSeek Harness 不增加平台拒绝逻辑，也不采用功能受限的 Windows 模式。
 
 真实 Loader 冒烟测试根据宿主选择原生伪终端边界。macOS 和 Linux 继续使用 Python POSIX PTY 驱动，Windows 则使用 `node-pty` 和 ConPTY。两种驱动接收相同的启动命令、环境、终端尺寸、以标记为触发条件的输入动作、超时、预期退出码和输出断言；3 个冒烟场景都会在每个受支持平台上运行。
 
diff --git a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
index 038d12a561..e151f92d0d 100644
--- a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
+++ b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.md
@@ -11,7 +11,7 @@ The [skill system](2026-07-05-skill-system.md) shipped with model-initiated load
 
 ## Decision
 
-The [`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) front door owns a `/skill:<name> [instructions]` command. On submit it loads the named skill and delivers one text block as a user turn — sent with `agent.send()` while idle and `agent.steer()` while running, the same rule as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `<skill name="…">` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool. Its visibility and loading policy comes from the shared [independent model and user skill invocation policy](2026-07-28-skill-invocation-policy.md).
+The [`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) front door owns a `/skill:<name> [instructions]` command. On submit it loads the named skill and delivers one text block as a user turn — sent with `agent.send()` while idle and `agent.steer()` while running, the same rule as ordinary editor input. The block is `renderSkillInvocation(skill, instructions)`: a `<skill name="…">` element wrapping the skill body, preceded by one resource-base line when the provider exposes one, with the user's trailing text appended after a blank line. The command is a TUI-only affordance; it adds no model-facing tool. Its visibility and loading policy comes from the shared [independent model and user skill invocation policy](2026-07-28-skill-invocation-policy.md).
 
 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.
 
diff --git a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
index af01642c07..ac1c4da948 100644
--- a/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
+++ b/.agents/notes/archived/feature/2026-07-21-tui-skill-slash-command.zh.md
@@ -11,7 +11,7 @@ Archived: 2026-08-04
 
 ## Decision
 
-[`@deepseek-ai/dsh-tui`](../../../../packages/interaction/tui/README.md) 前门拥有一条 `/skill:<name> [instructions]` 命令。提交时它加载指定的 skill，并投递一个文本块作为用户轮次——空闲时用 `agent.send()` 发送、运行中用 `agent.steer()` 中途引导，与普通编辑器输入遵循同一规则。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `<skill name="…">` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的功能；它不新增任何面向模型的工具。其可见性和加载策略来自共享的[模型与用户独立 skill 调用策略](2026-07-28-skill-invocation-policy.md)。
+[`@deepseek-ai/dsh-tui`](../../../../packages/ui/tui/README.md) 前门拥有一条 `/skill:<name> [instructions]` 命令。提交时它加载指定的 skill，并投递一个文本块作为用户轮次——空闲时用 `agent.send()` 发送、运行中用 `agent.steer()` 中途引导，与普通编辑器输入遵循同一规则。该文本块由 `renderSkillInvocation(skill, instructions)` 生成：一个包裹 skill 正文的 `<skill name="…">` 元素，当提供方暴露资源基址时在其前加一行资源基址行，用户尾随的文本在空行之后追加。该命令是 TUI 独有的功能；它不新增任何面向模型的工具。其可见性和加载策略来自共享的[模型与用户独立 skill 调用策略](2026-07-28-skill-invocation-policy.md)。
 
 TUI 通过 `ctx.get('skills')` 读取 skill 服务，而非声明式注入，因为 skill 是条件挂载的：没有注册表的部署仍保有可用的前门，此时 `/skill:` 会报告 skill 不可用，而不是挂载失败。`createTuiChat` 是同步的，而 `ctx.skills.list()` 是异步的，所以自动补全先立即种入静态斜杠命令，待目录解析完成后再用 `skill:<name>` 条目重建 provider（提供方）；在 dispose（资源释放）之后才到达的解析结果会被丢弃，而被拒绝的查找会保留基础命令。
 
diff --git a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
index ff4a310f08..2ef926cff9 100644
--- a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
+++ b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.md
@@ -13,7 +13,7 @@ The TUI assistant message opened with a single header line joining the `Assistan
 
 **Split the label from the timing; render the timing as the message's trailing line.**
 
-`AssistantMessageComponent` (packages/interaction/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.
+`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
 
diff --git a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
index 08ced9603d..282ac1e65b 100644
--- a/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
+++ b/.agents/notes/archived/feature/2026-07-27-assistant-timing-header-trailing.zh.md
@@ -13,7 +13,7 @@ TUI 的助手消息此前以一行开头，把 `Assistant` 标签和步骤计时
 
 **把标签与计时拆开；计时作为消息的末行渲染。**
 
-`AssistantMessageComponent`（packages/interaction/tui/src/index.ts）现在把加粗的 `Assistant` 标签作为首行，并把暗色的计时串（仍由 `StreamingAssistantComponent.rebuild()` 组装为 `header`，settled 时含 `· Completed …` 后缀）作为最后一个子节点，追加在 reasoning 与正文之后。计时内容、隐藏零值桶以及完成时间的行为均不变——仅位置从消息顶部移到底部。
+`AssistantMessageComponent`（packages/ui/tui/src/index.ts）现在把加粗的 `Assistant` 标签作为首行，并把暗色的计时串（仍由 `StreamingAssistantComponent.rebuild()` 组装为 `header`，settled 时含 `· Completed …` 后缀）作为最后一个子节点，追加在 reasoning 与正文之后。计时内容、隐藏零值桶以及完成时间的行为均不变——仅位置从消息顶部移到底部。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml
index a9e56019b3..8feded0ad4 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.i18n.yaml
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.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 .agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
-2026-07-28-dsh-guided-skill-session-commands.md: 606513919a927af3bb7e9b74544fd8df9a1682ce
-2026-07-28-dsh-guided-skill-session-commands.zh.md: 39af4a3a554ba3053f25b3d034346d3e1f4ce237
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.md
+2026-07-28-dsh-guided-skill-session-commands.md: 454d090a55db8987f8e4987aba67deff1b21b1a0
+2026-07-28-dsh-guided-skill-session-commands.zh.md: 64dad4e39c6fd3e3341313c3f8dd2b04947695cf
diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
index 606513919a..454d090a55 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.md
@@ -25,7 +25,7 @@ The `dsh-migrate` skill is bundled under `skills/` (shipped through `DSH_BUNDLED
 
 `apps/cli/tests/args.spec.ts` gains routing for `migrate`/`upgrade` (bare discriminant) and exit-1 for every leaked option on either side of each subcommand.
 
-`packages/interaction/tui/tests/tui.spec.ts` gains two fake-terminal cases in the existing skill describe block: `config.initialSkill` set delivers the rendered skill body as the first turn with no user input, and an unknown initial skill reports a notice without sending. `runSkillSession` itself is composition inside the module's `v8 ignore` block, like `runTui`/`runMeta`.
+`packages/ui/tui/tests/tui.spec.ts` gains two fake-terminal cases in the existing skill describe block: `config.initialSkill` set delivers the rendered skill body as the first turn with no user input, and an unknown initial skill reports a notice without sending. `runSkillSession` itself is composition inside the module's `v8 ignore` block, like `runTui`/`runMeta`.
 
 No keyless PTY snapshot: per the maintainer's scope call for this change, unit coverage plus interactive verification suffices, and the seed rides the already-snapshotted `/skill:` render path. Both commands were verified interactively in tmux from a scratch cwd: `dsh migrate` loaded `dsh-migrate` and asked which source agent; `dsh upgrade` loaded `dsh-upgrade`, which pulled in `dsh-customize` and began checkout discovery.
 
diff --git a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
index 39af4a3a55..64dad4e39c 100644
--- a/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
+++ b/.agents/notes/archived/feature/2026-07-28-dsh-guided-skill-session-commands.zh.md
@@ -25,7 +25,7 @@ Archived: 2026-08-03
 
 `apps/cli/tests/args.spec.ts` 新增 `migrate`/`upgrade` 的路由（裸判别式），以及每个子命令两侧任一泄漏选项的退出码 1。
 
-`packages/interaction/tui/tests/tui.spec.ts` 在既有 skill describe 块中新增两个伪终端用例：设置 `config.initialSkill` 时无需用户输入即把渲染后的 skill 正文作为首轮投递；未知的初始 skill 以通知形式报告且不发送。`runSkillSession` 本身是模块 `v8 ignore` 块内的组装，与 `runTui`/`runMeta` 相同。
+`packages/ui/tui/tests/tui.spec.ts` 在既有 skill describe 块中新增两个伪终端用例：设置 `config.initialSkill` 时无需用户输入即把渲染后的 skill 正文作为首轮投递；未知的初始 skill 以通知形式报告且不发送。`runSkillSession` 本身是模块 `v8 ignore` 块内的组装，与 `runTui`/`runMeta` 相同。
 
 无 keyless PTY 快照：依据维护者对本次改动的范围裁定，单元覆盖加交互式验证已足够，且播种走的是已有快照的 `/skill:` 渲染路径。两个命令均已在 tmux 中从临时 cwd 交互式验证：`dsh migrate` 加载 `dsh-migrate` 并询问源 agent；`dsh upgrade` 加载 `dsh-upgrade`，后者引入 `dsh-customize` 并开始 checkout 发现。
 
diff --git a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
index 76cc213ba8..ca5edc50bf 100644
--- a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md
@@ -11,7 +11,7 @@ Roughly ten e2e/smoke files re-derived the same spawn-collect-timeout choreograp
 
 Two related test-infra hand-rolls compounded the case:
 
-- `packages/support/llm-mock-server/src/cli.ts` hand-tokenized 17 value-taking `--flag value` options plus boolean flags (~45–60 lines of loop and value-extraction helpers) where the `node:util` `parseArgs` builtin is already the repo idiom (`cli-demo`, `acp-demo`, `verify-runtime-closure.ts`, `packages/scaffold/scripts`).
+- `packages/support/llm-mock-server/src/cli.ts` hand-tokenized 17 value-taking `--flag value` options plus boolean flags (~45–60 lines of loop and value-extraction helpers) where the `node:util` `parseArgs` builtin is already the repo idiom (`cli-demo`, `acp-demo`, `verify-runtime-closure.ts`, `packages/sdk/scripts`).
 - `apps/web/tests/smoke-real.e2e.ts` and `apps/web/tests/scaffold.ts` carried two verbatim copies of a regex `.env` parser (~20 lines) where the `process.loadEnvFile` builtin has exactly the required no-override semantics — and the vitest e2e/snapshot/web configs already load root `.env` with it before these files run, making the copies dead.
 - The snapshot harness hand-rolled three poll-until-deadline loops (`waitForPersistedTurnStart`/`waitForPersistedTurnEnd`/`waitForWorkspaceFile` in `packages/support/acp-snapshot/src/harness.ts`, ~55 lines) plus `waitForFile` in `crash-recovery.e2e.ts`, where `vi.waitFor`/`expect.poll` cover the shape — vitest is already a runtime dependency of `dsh-acp-snapshot`, so this adds nothing.
 
diff --git a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
index f597fd1e08..186e5cd560 100644
--- a/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
+++ b/.agents/notes/archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md
@@ -11,7 +11,7 @@ Archived: 2026-08-07
 
 另有两处相关的测试基础设施手写代码进一步强化了替换的理由：
 
-- `packages/support/llm-mock-server/src/cli.ts` 曾手工逐个切分 17 个带值的 `--flag value` 选项外加若干布尔标志（约 45–60 行的循环与取值辅助函数），而 `node:util` 内置的 `parseArgs` 早已是本仓库的惯用写法（`cli-demo`、`acp-demo`、`verify-runtime-closure.ts`、`packages/scaffold/scripts`）。
+- `packages/support/llm-mock-server/src/cli.ts` 曾手工逐个切分 17 个带值的 `--flag value` 选项外加若干布尔标志（约 45–60 行的循环与取值辅助函数），而 `node:util` 内置的 `parseArgs` 早已是本仓库的惯用写法（`cli-demo`、`acp-demo`、`verify-runtime-closure.ts`、`packages/sdk/scripts`）。
 - `apps/web/tests/smoke-real.e2e.ts` 与 `apps/web/tests/scaffold.ts` 曾携带两份逐字相同的正则 `.env` 解析器拷贝（约 20 行），而内置的 `process.loadEnvFile` 恰好具备所需的「不覆盖已有值」语义；并且 vitest 的 e2e/snapshot/web 配置在这些文件运行之前就已用它加载了根 `.env`，这两份拷贝实为死代码。
 - 快照 harness 曾手写三个「轮询直到截止时间」的循环（`packages/support/acp-snapshot/src/harness.ts` 中的 `waitForPersistedTurnStart`/`waitForPersistedTurnEnd`/`waitForWorkspaceFile`，约 55 行），外加 `crash-recovery.e2e.ts` 中的 `waitForFile`，而 `vi.waitFor`/`expect.poll` 正好覆盖这种形态；vitest 本来就是 `dsh-acp-snapshot` 的运行时依赖，因此这不新增任何东西。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
new file mode 100644
index 0000000000..e597017076
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.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/architecture/2026-07-29-package-regrouping.md
+2026-07-29-package-regrouping.md: bb9f7deb775a0922de8b20f766446ebf007718d3
+2026-07-29-package-regrouping.zh.md: 1d7d79e0cfad95382c036b3c99712775870aa48a
diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
similarity index 56%
rename from .agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
rename to .agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
index 9a56f9f5f1..bb9f7deb77 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
@@ -1,24 +1,24 @@
 # Agent Note: Regroup packages/ by measured clustering
 
-Status: proposed
+Status: implemented
 
 English | [中文](2026-07-29-package-regrouping.zh.md)
 
 ## Problem
 
-The two-level `packages/<group>/<pkg>` hierarchy ([original decision](../../archived/architecture/2026-06-20-package-hierarchy.md)) has drifted since June: 167 packages now sit in 40 groups, and several group boundaries no longer match how the packages actually cluster.
+The two-level `packages/<group>/<pkg>` hierarchy ([original decision](../../archived/architecture/2026-06-20-package-hierarchy.md)) had drifted since June: 167 packages sat in 42 groups, and several group boundaries no longer matched how the packages actually cluster.
 
-- `ui/` mixes four unrelated planes: the human terminal channel (`tui`), the SDK's JSON-RPC server half (`jsonrpc`, whose peer dependency on `dsh-sdk-protocol` binds it to the `sdk/` stack), the human-interaction seams (`user-interaction`, `user-approval`, `permission`, `tool-ask-user`, `commands`), and channel-neutral boot glue (`app-boot`). Its own README narrates the mixture instead of stating a role.
-- The session family is fragmented across five groups — `session-persistence/`, `session-projection/`, `session-query/`, `session-title/`, and `telemetry/` — although the measured dependency edges tie them together (query → persistence, title → projection, projection → persistence; see [docs/module-graph.md](../../../../docs/module-graph.md)).
-- Two group names collide with unrelated packages: `telemetry/` (session reporting) vs `sdk/telemetry` = `dsh-telemetry` (launcher-side SDK telemetry), and `timeout/` (a tool-call guard) vs `util/timeout` (the generic promise utility).
-- `cordis/` names its group after the framework every package is built on, so the name discriminates nothing; its single package `tool-cordis` is the runtime self-modification toolset.
-- `sdk/` folder names are inconsistent: `sdk/sdk-client` and `sdk/sdk-protocol` repeat the group name while `sdk/telemetry`, `sdk/helper`, and `sdk/scripts` do not.
+- `ui/` mixed four unrelated planes: the human terminal channel (`tui`), the SDK's JSON-RPC server half (`jsonrpc`, whose peer dependency on `dsh-sdk-protocol` binds it to the SDK wire stack), the human-interaction seams (`user-interaction`, `user-approval`, `permission`, `tool-ask-user`, `commands`), and channel-neutral boot glue (`app-boot`). Its own README narrated the mixture instead of stating a role.
+- The session family was fragmented across five groups — `session-persistence/`, `session-projection/`, `session-query/`, `session-title/`, and `telemetry/` — although the measured dependency edges tie them together (query → persistence, title → projection, projection → persistence; see [docs/module-graph.md](../../../../docs/module-graph.md)).
+- Two group names collided with unrelated packages: `telemetry/` (session reporting) vs `dsh-telemetry` (launcher-side SDK telemetry), and `timeout/` (a tool-call guard) vs `util/timeout` (the generic promise utility).
+- `cordis/` named its group after the framework every package is built on, so the name discriminated nothing; its single package `tool-cordis` is the runtime self-modification toolset.
+- The old `sdk/` folder names were inconsistent: `sdk/sdk-client` and `sdk/sdk-protocol` repeated the group name while `sdk/telemetry`, `sdk/helper`, and `sdk/scripts` did not.
 
 The north star for the regrouping: **closely clustered packages share a group.** A cluster is measured — peer-dependency edges and co-change — not thematic. An isolated seam family may stand alone as a small group; the failure mode to avoid is the grab-bag whose name describes no single role.
 
-## Proposal
+## Decision
 
-Recompose six groups; every other group keeps today's boundary and contents (the dependency analysis confirmed the capability families — `bash/`, `pty/`, `code-runtime/`, `sandbox/`, `subprocess/`, `fs/`, `lsp/`, `web/`, `skill/`, and the rest — were already drawn correctly). npm package names do not change in this reorganization; the folder tree carries the whole change.
+Six groups are recomposed; every other group keeps its prior boundary and contents (the dependency analysis confirmed the capability families — `bash/`, `pty/`, `code-runtime/`, `sandbox/`, `subprocess/`, `fs/`, `lsp/`, `web/`, `skill/`, and the rest — were already drawn correctly). npm package names did not change; the folder tree carries the whole change.
 
 | Group | Members (folder names) | From |
 |---|---|---|
@@ -29,18 +29,18 @@ Recompose six groups; every other group keeps today's boundary and contents (the
 | `guard/` | repeat-tool-guard, timeout-policy | `guard/` + `timeout/` |
 | `self-modification/` | tool-cordis | `cordis/` |
 
-- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (review: prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ends the group-name collision with `dsh-telemetry`.
+- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (review: prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ended the group-name collision with `dsh-telemetry`.
 - **`interaction/`** is the human-collaboration plane plus the terminal channel that answers it: the question/approval seams, the permission preset, the model-facing `ask_user_question` tool, the human-command registry (`plan-mode` and `command-goal` already consume `commands` together with the interaction seams), and `tui` — the interactive channel is the plane's richest provider and consumer (peer edges to `commands` and `user-interaction`), and a one-package `tui/` group would spend a top-level name on one plugin.
 - **`boot/`** is a role-complete single-package group: the shared bin boot glue that belongs to no channel and no assembly (consumed by `apps/cli`, the `scaffold/` launcher, and the `examples/` demo bins).
-- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is today's `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/` in review: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it says nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style.
+- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is the former `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/` in review: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it said nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style; the three affected npm names are mapped explicitly beside the group wildcard in `tsconfig.base.json` until the deferred renames land.
 - **`guard/`** keeps its documented role, loop-hygiene guards, and gains the tool-call timeout enforcer, dissolving the one-package `timeout/` group whose name collided with `util/timeout`.
 - **`self-modification/`** names the role `cordis/` obscured: the toolset with which the agent inspects and mounts plugins in its own live runtime, and the landing zone for future self-modification packages.
 
-40 groups become 37; the win is clustering correctness and truthful names, not count.
+42 groups became 39; the win is clustering correctness and truthful names, not count.
 
 ## Deferred renames (FIXME markers)
 
-Five npm names should eventually change, but renaming inside the reorganization would turn a pure-move PR into an import-churn PR. Instead, the implementation adds a `FIXME` to each affected package's module JSDoc naming the intended new name. `FIXME` blocks a tagged release ([marker semantics](../../../../docs/development.md)), which is the wanted forcing function: these renames are only free while nothing external consumes the packages.
+Five npm names should eventually change, but renaming inside the reorganization would have turned a pure-move PR into an import-churn PR. Instead, each affected package's module JSDoc carries a `FIXME` naming the intended new name. `FIXME` blocks a tagged release ([marker semantics](../../../../docs/development.md)), which is the wanted forcing function: these renames are only free while nothing external consumes the packages.
 
 | Current npm name | Intended name | Why |
 |---|---|---|
@@ -52,19 +52,17 @@ Five npm names should eventually change, but renaming inside the reorganization
 
 The first four are settled intent; resolving them converges the SDK wire stack's npm names on `dsh-sdk-*` (the npm prefix names the product stack; the `scaffold/` folder names the role). `@deepseek-ai/create-sdk` keeps its documented npm-initializer exception.
 
-## Implementation
+## What the move touched
 
-One mechanical PR, landed in a quiet window: a single conflict event for the many open PRs, an atomic documentation update, and pure-move reviewability (`git mv` + path fixes, rename detection intact). If review prefers, the same content splits into a three-PR stack (the session fold; `ui/` dissolution + `scaffold/`; `self-modification/` + `guard/` merge), at the cost of three rebase events for everyone else.
+The moves landed as `git mv` commits, one per region (the session fold; `ui/` dissolution + `scaffold/`; `guard/` merge + `self-modification/`), so rename detection carries review. A group move touched: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose and gate scripts. Remaining group-path referents (workspace configs, test globs, lint keys) were found mechanically by the acceptance gates failing loud — the repository's own misconfiguration rule.
 
-A group move touches: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose (root and `apps/cli` READMEs, 7 script files + 22 docs files measured today; `verify-package-paths` gates the Markdown/TypeScript classes of stragglers). This list conveys the shape of the change, not a file inventory: every remaining group-path referent (workspace configs, test globs, lint keys) is found mechanically at implementation time by the acceptance gates failing loud, which is the repository's own misconfiguration rule.
+A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name. Each FIXME landed in the same commit as the move that created its context.
 
-A group move does not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name (verified by grep before this proposal). Each FIXME lands in the same PR as the move that creates its context.
-
-`client/` and `host/` are out of scope and unchanged. The in-flight `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision; the only interaction is a trivial merge in the packages/README.md table.
+`client/` and `host/` were out of scope and are unchanged. The `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision; the only interaction is a trivial merge in the packages/README.md table.
 
 ## Alternatives considered
 
-**Coarse domain buckets** (`exec/` = subprocess+sandbox+bash+pty+code-runtime, `workspace/` = fs+lsp+workspace, `orchestration/` = subagent+workflow+tasks, `knowledge/` = web+skill, `collab/` = plan+todo+goal; ~16 groups). Rejected: the measured graph contradicts the merges. `sandbox` and `subprocess` are shared infrastructure consumed across families (bash ×5, fs ×5, pty, lsp, mcp, subagent, sdk edges), `web` ↔ `skill` have zero edges, and a large bucket reproduces the `ui/` grab-bag at a larger scale.
+**Coarse domain buckets** (`exec/` = subprocess+sandbox+bash+pty+code-runtime, `workspace/` = fs+lsp+workspace, `orchestration/` = subagent+workflow+tasks, `knowledge/` = web+skill, `collab/` = plan+todo+goal; ~16 groups). Rejected: the measured graph contradicts the merges. `sandbox` and `subprocess` are shared infrastructure consumed across families (bash ×5, fs ×5, pty, lsp, mcp, subagent, scaffold edges), `web` ↔ `skill` have zero edges, and a large bucket reproduces the `ui/` grab-bag at a larger scale.
 
 **Abstract layer names** (`capability/`, `policy/`, `extension/`, `provider/`). Rejected: they describe every plugin equally badly, and a `capability/` bucket would hold ~50 packages.
 
@@ -88,19 +86,11 @@ A group move does not touch: npm names, imports, `cordis.yml` configs, snapshot
 
 **Renaming `context/` to `request-context/`.** Rejected: within this tree the group is unambiguous in situ; the churn is unjustified.
 
-## Acceptance criteria
+## Consequences
 
-- The tree matches the map: the six recomposed groups hold exactly the listed members; the groups `ui/`, `sdk/`, `telemetry/`, `timeout/`, `cordis/`, `session-persistence/`, `session-projection/`, and `session-title/` no longer exist; every other group's contents are unchanged.
-- Zero npm renames: the workspace package-name set is identical before and after.
-- The five FIXME markers are present, each naming its intended new name.
-- New and updated group READMEs form complete bilingual triplets; the packages/README.md hierarchy table matches the tree; docs/module-graph.md is regenerated.
-- `pnpm run typecheck`, `pnpm run test`, `pnpm run doc-sync`, and `pnpm run hygiene` pass, and the unit/snapshot suites collect the same test files before and after the move (group-scoped globs in test configs must not silently match nothing).
-
-## Risks
-
-- **Open-PR conflicts.** Every open PR touching a moved file must rebase across the move. Mitigated by landing as one PR in a quiet window, publishing the mapping table in the PR body, and the moves being pure renames (rename detection resolves most hunks mechanically).
-- **Reference drift.** Docs or scripts citing old paths can go stale; `verify-package-paths` exists precisely for moved-package drift and runs in `doc-sync`.
-- **Translation load.** Five new group README triplets plus edits to existing pairs land in the implementation PR.
-- **Deferred renames are release blockers by design.** A FIXME that later proves wrong must be removed explicitly with rationale, never silently dropped.
-- **Single-package groups remain** (`boot/`, `self-modification/`, and existing ones such as `acp/`). Accepted deliberately: each is role-complete rather than a fragment of a family, and a truthful small group beats a nominal merge.
-- **What this gives up:** nothing functional — the change is navigational. Muscle memory and external links to old GitHub paths break, which is acceptable pre-release with no external consumers.
+- The tree matches the map: the six recomposed groups hold exactly the listed members; the groups `ui/`, `sdk/`, `telemetry/`, `timeout/`, `cordis/`, `session-persistence/`, `session-projection/`, and `session-title/` no longer exist; every other group's contents are unchanged. The workspace package-name set is identical before and after (zero npm renames), and the five FIXME markers pin the deferred ones. A FIXME that later proves wrong must be removed explicitly with rationale, never silently dropped.
+- What pins the result: `pnpm run typecheck`, the unit suites of every moved group, `verify-package-paths`, `verify-md-links`, and the corpus-wide translation pairing all pass on the moved tree; the group-scoped test globs in `vitest.snapshot.config.ts` were rewritten with the moves so the suites collect the same test files as before (a fail-open glob would silently drop coverage).
+- Every open PR touching a moved file rebases across the move once; the mapping table in the PR body and rename detection resolve most hunks mechanically.
+- Single-package groups remain (`boot/`, `self-modification/`, and existing ones such as `acp/`). Accepted deliberately: each is role-complete rather than a fragment of a family, and a truthful small group beats a nominal merge.
+- The `scaffold/` folders diverge from their npm names until the deferred renames land — the one transitional asymmetry, carried by three explicit `paths` entries in `tsconfig.base.json` and resolved by the FIXME renames.
+- What this gave up: nothing functional — the change is navigational. Muscle memory and external links to old GitHub paths break, which is acceptable pre-release with no external consumers.
diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
similarity index 66%
rename from .agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md
rename to .agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
index c49c5a1daf..1d7d79e0cf 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
@@ -1,24 +1,24 @@
 # Agent Note: 按实测聚类重新划分 packages/ 分组
 
-Status: proposed
+Status: implemented
 
 [English](2026-07-29-package-regrouping.md) | 中文
 
 ## Problem
 
-两级 `packages/<group>/<pkg>` 层级结构（[原始决策](../../archived/architecture/2026-06-20-package-hierarchy.md)）自 6 月以来已经漂移：167 个包（package）如今坐落在 40 个组里，若干组边界已经对不上这些包的实际聚类。
+两级 `packages/<group>/<pkg>` 层级结构（[原始决策](../../archived/architecture/2026-06-20-package-hierarchy.md)）自 6 月以来已经漂移：167 个包（package）彼时坐落在 42 个组里，若干组边界已经对不上这些包的实际聚类。
 
-- `ui/` 混杂了四个互不相关的平面：人类终端通道（`tui`）、SDK 的 JSON-RPC 服务端一半（`jsonrpc`，它对 `dsh-sdk-protocol` 的对等依赖（peer dependency）把它绑在 `sdk/` 这一栈上）、人机交互 seam（`user-interaction`、`user-approval`、`permission`、`tool-ask-user`、`commands`），以及与通道无关的 boot 胶水（`app-boot`）。它自己的 README 只能逐一叙述这堆混杂，说不出一个统一职责。
+- `ui/` 混杂了四个互不相关的平面：人类终端通道（`tui`）、SDK 的 JSON-RPC 服务端一半（`jsonrpc`，它对 `dsh-sdk-protocol` 的对等依赖（peer dependency）把它绑在 SDK 通信栈上）、人机交互 seam（`user-interaction`、`user-approval`、`permission`、`tool-ask-user`、`commands`），以及与通道无关的 boot 胶水（`app-boot`）。它自己的 README 只能逐一叙述这堆混杂，说不出一个统一职责。
 - 会话家族被割裂在五个组里——`session-persistence/`、`session-projection/`、`session-query/`、`session-title/` 与 `telemetry/`——而实测依赖边明明把它们连成一体（query → persistence、title → projection、projection → persistence；见 [docs/module-graph.md](../../../../docs/module-graph.md)）。
-- 两个组名与不相干的包撞名：`telemetry/`（会话上报）撞上 `sdk/telemetry` = `dsh-telemetry`（启动器侧 SDK telemetry），`timeout/`（一个工具调用守卫）撞上 `util/timeout`（通用 promise 工具）。
+- 两个组名与不相干的包撞名：`telemetry/`（会话上报）撞上 `dsh-telemetry`（启动器侧 SDK telemetry），`timeout/`（一个工具调用守卫）撞上 `util/timeout`（通用 promise 工具）。
 - `cordis/` 拿所有包共同依托的框架给自己的组命名，这个名字因此毫无区分度；组里唯一的包 `tool-cordis` 是运行时自我修改工具集。
-- `sdk/` 的目录命名不一致：`sdk/sdk-client` 和 `sdk/sdk-protocol` 重复了组名，而 `sdk/telemetry`、`sdk/helper`、`sdk/scripts` 没有。
+- 旧 `sdk/` 的目录命名不一致：`sdk/sdk-client` 和 `sdk/sdk-protocol` 重复了组名，而 `sdk/telemetry`、`sdk/helper`、`sdk/scripts` 没有。
 
 这次重新分组的指导准则：**聚类紧密的包同处一组。**聚类以实测为准（对等依赖边与 co-change），而非按主题归类。孤立的 seam 家族可以自成一个小组；要避免的失败形态，是名字概括不出单一职责的大杂烩组。
 
-## Proposal
+## Decision
 
-重组六个组；其余每个组都保持今天的边界与内容不变（依赖分析确认各能力家族——`bash/`、`pty/`、`code-runtime/`、`sandbox/`、`subprocess/`、`fs/`、`lsp/`、`web/`、`skill/` 及其余——本来就划得正确）。这次重组不改任何 npm 包名；整个变更全部由目录树承载。
+重组六个组；其余每个组都保持先前的边界与内容不变（依赖分析确认各能力家族——`bash/`、`pty/`、`code-runtime/`、`sandbox/`、`subprocess/`、`fs/`、`lsp/`、`web/`、`skill/` 及其余——本来就划得正确）。npm 包名一个未改；整个变更全部由目录树承载。
 
 | 组 | 成员（目录名） | 来源 |
 |---|---|---|
@@ -32,15 +32,15 @@ Status: proposed
 - **`session/`** 是持久会话数据平面：持久化 seam 连同其各后端与检查点策略、从该日志折叠（fold）出全量值对外供值的投影、日志兜底的标题，以及 OTel 上报。标题折叠本身就是读取侧的承重构件（`session-query` 对 `dsh-session-title` 声明对等依赖），所以标题属于数据平面，而非某个「派生服务」附属区。用这个朴素的名字是有意为之（评审意见：名字要像人起的）；旁边的 `core/session` 包仍是常驻内存的实时服务，本组则是围绕它的持久家族。`session-query/` 保持独立成组：这个读取／工具面自带模型工具和 SQLite FTS 后端，其消费不依赖持久化内部实现。吸收 `telemetry/` 之后，与 `dsh-telemetry` 的组名冲突就此终结。
 - **`interaction/`** 是人机协作平面加上应答它的终端通道：提问／批准 seam、权限预设、面向模型的 `ask_user_question` 工具、人类命令注册表（`plan-mode` 与 `command-goal` 已经把 `commands` 和各交互 seam 放在一起消费），以及 `tui`——这个交互通道是该平面最重的提供方与消费方（对 `commands` 与 `user-interaction` 均有对等依赖边），而一个单包 `tui/` 组会把一个顶层名字花在一个插件上。
 - **`boot/`** 是角色完备的单包组：不归属任何通道也不归属任何组装的共享 bin boot 胶水（被 `apps/cli`、`scaffold/` 的启动器和 `examples/` 各演示 bin 消费）。
-- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即今天的 `ui/jsonrpc`），以及启动器侧 telemetry。评审中从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致。
+- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即原先的 `ui/jsonrpc`），以及启动器侧 telemetry。评审中从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致；在推迟的改名落地之前，受影响的三个 npm 名在 `tsconfig.base.json` 里于组通配符旁显式映射。
 - **`guard/`** 保留其文档记载的角色（循环卫生守卫），并新纳入强制执行工具调用超时的包；那个与 `util/timeout` 撞名的单包组 `timeout/` 随之解散。
 - **`self-modification/`** 把 `cordis/` 遮蔽掉的角色说了出来：它是 agent（智能体）检查并挂载自身实时运行时中插件所用的工具集，也是未来自我修改类包的落点。
 
-40 个组变为 37 个；收益在聚类正确与名实相符，不在数量增减。
+42 个组变为 39 个；收益在聚类正确与名实相符，不在数量增减。
 
 ## Deferred renames (FIXME markers)
 
-五个 npm 名最终应当改掉，但在这次重组内部改名，会把一个纯移动的 PR（Pull Request）变成大量翻改 import 的 PR。实现改为在每个受影响包的模块 JSDoc 里加一条 `FIXME`，写明意图中的新名字。`FIXME` 会阻塞打 tag 的发布（[标记语义](../../../../docs/development.md)），这正是想要的倒逼机制：只有趁还没有外部消费方使用这些包时，这些改名才是零成本的。
+五个 npm 名最终应当改掉，但在这次重组内部改名，会把一个纯移动的 PR（Pull Request）变成大量翻改 import 的 PR。因此每个受影响包的模块 JSDoc 里带有一条 `FIXME`，写明意图中的新名字。`FIXME` 会阻塞打 tag 的发布（[标记语义](../../../../docs/development.md)），这正是想要的倒逼机制：只有趁还没有外部消费方使用这些包时，这些改名才是零成本的。
 
 | 当前 npm 名 | 目标名 | 原因 |
 |---|---|---|
@@ -52,19 +52,17 @@ Status: proposed
 
 前四个是已定的意图；兑现之后，SDK 通信栈的 npm 名随之收敛为 `dsh-sdk-*`（npm 前缀指产品栈，`scaffold/` 目录名指角色）。`@deepseek-ai/create-sdk` 保留其文档记载的 npm 初始化器特例。
 
-## Implementation
+## What the move touched
 
-整个变更作为一个机械化 PR，在低活动窗口期合入：众多开放中的 PR 只经历一次冲突事件，文档得到一次原子更新，评审享有纯移动的可评审性（`git mv` 加路径修正，重命名检测完好）。若评审偏好拆分，同样的内容也可以拆成三个 PR 的堆叠（会话折叠；`ui/` 解散加 `scaffold/`；`self-modification/` 加 `guard/` 合并），代价是其他所有人要经历三次变基事件。
+移动以 `git mv` 提交落地，每个区域一个提交（会话折叠；`ui/` 解散加 `scaffold/`；`guard/` 合并加 `self-modification/`），评审由重命名检测承载。组移动触及了：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文与门禁脚本中以仓库根为基准的 `packages/...` 引用。其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都由验收门禁的响亮失败机械地找了出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
 
-组移动会触及：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文中以仓库根为基准的 `packages/...` 引用（根 README 与 `apps/cli` README、今天实测 7 个脚本文件加 22 个文档文件；`verify-package-paths` 兜住 Markdown／TypeScript 这两类漏网引用）。这份清单陈述的是变更的形态，不是文件清点：其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都在实现时由验收门禁的响亮失败机械地找出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
+组移动未触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包。每条 FIXME 都与创造其上下文的那次移动落在同一个提交。
 
-组移动不触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包（提案之前已用 grep 核实）。每条 FIXME 都与创造其上下文的那次移动落在同一个 PR。
-
-`client/` 与 `host/` 不在本次范围内，保持不变。在途的 `experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策；两者唯一的交集是 packages/README.md 表格里一次很小的合并。
+`client/` 与 `host/` 不在本次范围内，保持不变。`experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策；两者唯一的交集是 packages/README.md 表格里一次很小的合并。
 
 ## Alternatives considered
 
-**粗粒度领域桶**（`exec/` = subprocess+sandbox+bash+pty+code-runtime，`workspace/` = fs+lsp+workspace，`orchestration/` = subagent+workflow+tasks，`knowledge/` = web+skill，`collab/` = plan+todo+goal；约 16 个组）。不予采纳：实测依赖图与这些合并相矛盾。`sandbox` 和 `subprocess` 是被各家族跨界消费的共享基础设施（与 bash ×5、fs ×5、pty、lsp、mcp、subagent、sdk 均有依赖边），`web` ↔ `skill` 之间零依赖边，而大桶只会在更大尺度上复现 `ui/` 式大杂烩。
+**粗粒度领域桶**（`exec/` = subprocess+sandbox+bash+pty+code-runtime，`workspace/` = fs+lsp+workspace，`orchestration/` = subagent+workflow+tasks，`knowledge/` = web+skill，`collab/` = plan+todo+goal；约 16 个组）。不予采纳：实测依赖图与这些合并相矛盾。`sandbox` 和 `subprocess` 是被各家族跨界消费的共享基础设施（与 bash ×5、fs ×5、pty、lsp、mcp、subagent、scaffold 均有依赖边），`web` ↔ `skill` 之间零依赖边，而大桶只会在更大尺度上复现 `ui/` 式大杂烩。
 
 **抽象分层名**（`capability/`、`policy/`、`extension/`、`provider/`）。不予采纳：这些名字对每个插件都同样地不达意，而且一个 `capability/` 桶会装下约 50 个包。
 
@@ -88,19 +86,11 @@ Status: proposed
 
 **把 `context/` 改名为 `request-context/`。** 不予采纳：在这棵树里，该组就地看并无歧义；这份改动开销并不值得。
 
-## Acceptance criteria
+## Consequences
 
-- 目录树与映射表一致：重组的六个组恰好持有所列成员；`ui/`、`sdk/`、`telemetry/`、`timeout/`、`cordis/`、`session-persistence/`、`session-projection/`、`session-title/` 这些组不复存在；其余每个组的内容不变。
-- npm 改名为零：workspace 的包名集合在前后完全相同。
-- 五条 FIXME 标记全部就位，每条都写明其意图中的新名字。
-- 新增与更新的组 README 构成完整的双语三文件配对；packages/README.md 的层级结构表与目录树一致；docs/module-graph.md 已重新生成。
-- `pnpm run typecheck`、`pnpm run test`、`pnpm run doc-sync`、`pnpm run hygiene` 全部通过，且单元／快照套件在移动前后收集到相同的测试文件（测试配置里按组划定的 glob 不得无声地匹配为空）。
-
-## Risks
-
-- **开放 PR 的冲突。** 每个触碰被移动文件的开放 PR 都必须跨过这次移动做变基。缓解方式：作为单个 PR 在低活动窗口期落地、在 PR 正文公布映射表，且移动都是纯改名（重命名检测可机械化解决大多数改动块）。
-- **引用漂移。** 引用旧路径的文档或脚本可能变得陈旧；`verify-package-paths` 正是为包移动造成的漂移而设，并随 `doc-sync`（文档同步门禁）运行。
-- **翻译负担。** 五组新的组 README 三文件配对，加上既有配对的修改，都随实现 PR 一同落地。
-- **推迟的改名按设计就是发布阻塞项。** 日后若某条 FIXME 被证明不对，必须连同理由显式移除，绝不允许无声消失。
-- **单包组依然存在**（`boot/`、`self-modification/`，以及 `acp/` 等既有单包组）。这是有意接受的：每个都是角色完备的整体而非某个家族的碎片，一个名实相符的小组胜过一次徒有其名的合并。
+- 目录树与映射表一致：重组的六个组恰好持有所列成员；`ui/`、`sdk/`、`telemetry/`、`timeout/`、`cordis/`、`session-persistence/`、`session-projection/`、`session-title/` 这些组不复存在；其余每个组的内容不变。workspace 的包名集合在前后完全相同（npm 改名为零），五条 FIXME 标记钉住推迟的改名。日后若某条 FIXME 被证明不对，必须连同理由显式移除，绝不允许无声消失。
+- 结果由以下检查钉住：`pnpm run typecheck`、每个被移动组的单元测试套件、`verify-package-paths`、`verify-md-links` 与全语料翻译配对在移动后的树上全部通过；`vitest.snapshot.config.ts` 中按组划定的测试 glob 随移动一并改写，套件收集到与移动前相同的测试文件（glob 匹配为空会无声地丢失覆盖）。
+- 每个触碰被移动文件的开放 PR 都跨过这次移动做一次变基；PR 正文中的映射表与重命名检测可机械化解决大多数改动块。
+- 单包组依然存在（`boot/`、`self-modification/`，以及 `acp/` 等既有单包组）。这是有意接受的：每个都是角色完备的整体而非某个家族的碎片，一个名实相符的小组胜过一次徒有其名的合并。
+- 在推迟的改名落地之前，`scaffold/` 的目录名与其 npm 名并不一致——这是唯一的过渡性不对称，由 `tsconfig.base.json` 里三条显式 `paths` 映射承载，并由 FIXME 改名最终消除。
 - **这次变更放弃了什么：** 功能上一无所失——变更只关乎导航。肌肉记忆和指向旧 GitHub 路径的外部链接会失效；在 pre-release、尚无外部消费者的前提下，这可以接受。
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
index ba4444166c..e083adcca5 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.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 .agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
-2026-08-04-credentials-yaml-and-user-environment-layer.md: 4ecbc41adf4e22c74ecf425c2caf628efdf7cf54
-2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 370179b442783f4f8ecd8e3badbd236a924f5f81
+2026-08-04-credentials-yaml-and-user-environment-layer.md: 44bdea243671093b34a6338ed1c95bf25bcc78f4
+2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 5f724c7a12365e6e87e03b5926f837a5251b6118
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
index 4ecbc41adf..44bdea2436 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
@@ -23,7 +23,7 @@ OPENAI_API_KEY: sk-…
 
 Because the document holds credentials and nothing else, every deviation is a rejection rather than a skipped entry: a non-mapping root, a key that is not a POSIX identifier, a non-string value, an empty string, a duplicate key, and malformed YAML all fail — loud at boot and at a write, warn-and-keep-the-last-good-snapshot on a live reload. A silently ignored key would read as "the secret I stored has no effect", which is the failure this change exists to remove. The dotenv physical-line editor is replaced by a patch of the parsed document, so comments and untouched entries keep their formatting, any string value round-trips (multi-line included), and no entry is unwritable for want of a quoting style. The writer lock, read-modify-write, atomic `0600` write under a `0700` directory, exact-path watcher, content-equality self-write suppression, and quiescent disposal are unchanged.
 
-**`$DSH_HOME/.env` is the user's ordinary environment layer.** `loadLayeredEnv` in [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) parses the invoking directory's `.env` and then the Harness home's, giving `user < project < inherited` by materializing each accepted value only when the process has no higher-layer value. The Harness home is resolved from the inherited environment *before* either file loads, so a project `.env` cannot redirect which user document is read. Only the product CLI layers these files; SDK and example bins keep loading their own directory through `loadEnv` and must not inherit a developer's `$DSH_HOME`.
+**`$DSH_HOME/.env` is the user's ordinary environment layer.** `loadLayeredEnv` in [`dsh-app-boot`](../../../../packages/boot/app-boot/README.md) parses the invoking directory's `.env` and then the Harness home's, giving `user < project < inherited` by materializing each accepted value only when the process has no higher-layer value. The Harness home is resolved from the inherited environment *before* either file loads, so a project `.env` cannot redirect which user document is read. Only the product CLI layers these files; SDK and example bins keep loading their own directory through `loadEnv` and must not inherit a developer's `$DSH_HOME`.
 
 Credential precedence distinguishes the inherited environment from discovered files: the inherited value stays the read-only per-run override, the managed document wins next, and project then user `.env` values remain writable fallbacks. A `set` therefore replaces a discovered-file value instead of rejecting a write that only the flattened `process.env` view would consider shadowed.
 
@@ -38,7 +38,7 @@ There is no migration. A key already in `$DSH_HOME/.env` keeps resolving as a fa
 
 ## Alternatives considered
 
-**Keep one `$DSH_HOME/.env` and teach the CLI to hoist it.** Rejected: hoisting the store is precisely what makes stored keys unrotatable, which is why [app-boot documented the exclusion](../../../../packages/ui/app-boot/README.md) in the first place. The conflict is the file's two jobs, not the loader.
+**Keep one `$DSH_HOME/.env` and teach the CLI to hoist it.** Rejected: hoisting the store is precisely what makes stored keys unrotatable, which is why [app-boot documented the exclusion](../../../../packages/boot/app-boot/README.md) in the first place. The conflict is the file's two jobs, not the loader.
 
 **`$DSH_HOME/.credentials.env` — a second dotenv file.** Rejected: dotenv suits an environment layer but cannot express "a managed document indexed by credential reference". It cannot reject a non-string or an unaddressable key, and its line editor already refused values it could not quote, leaving entries readable but unwritable.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
index 370179b442..5f724c7a12 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
@@ -23,7 +23,7 @@ OPENAI_API_KEY: sk-…
 
 因为该文档只存放凭据、别无他物，任何偏离都是拒绝而不是跳过条目：非 mapping 的根、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败——启动时和写入时响亮失败，运行期热重载则告警并保留最后可用快照。被静默忽略的键读起来就是「我存进去的密钥没有生效」，而这正是本次变更要消除的失败。dotenv 物理行编辑器被替换为对已解析文档打补丁，因此注释与未触及条目的排版都会保留，任何字符串值都能往返（含多行），也不会再有条目因为缺少可用引号样式而不可写。写锁、read-modify-write、`0700` 目录下的 `0600` 原子写、精确路径 watcher、按内容相等抑制自写、以及 dispose 时的完全停稳，均保持不变。
 
-**`$DSH_HOME/.env` 是用户的普通环境层。** [`dsh-app-boot`](../../../../packages/ui/app-boot/README.md) 中的 `loadLayeredEnv` 先解析调用目录的 `.env`，再解析 Harness home 的，并且只在进程中没有更高层值时物化每个已接受的值，从而得到 `用户 < 项目 < 继承`。Harness home 在两个文件加载*之前*就从继承的环境解析完毕，因此项目 `.env` 无法改变读取哪份用户文档。只有产品 CLI（命令行界面）叠加这两个文件；SDK 与示例 bin 仍通过 `loadEnv` 加载各自的目录，绝不继承开发者的 `$DSH_HOME`。
+**`$DSH_HOME/.env` 是用户的普通环境层。** [`dsh-app-boot`](../../../../packages/boot/app-boot/README.md) 中的 `loadLayeredEnv` 先解析调用目录的 `.env`，再解析 Harness home 的，并且只在进程中没有更高层值时物化每个已接受的值，从而得到 `用户 < 项目 < 继承`。Harness home 在两个文件加载*之前*就从继承的环境解析完毕，因此项目 `.env` 无法改变读取哪份用户文档。只有产品 CLI（命令行界面）叠加这两个文件；SDK 与示例 bin 仍通过 `loadEnv` 加载各自的目录，绝不继承开发者的 `$DSH_HOME`。
 
 凭据优先级会区分继承环境与发现的文件：继承值仍是只读的按次覆盖，其后是受管文档，再后是仍可写的项目与用户 `.env` 后备值。因此 `set` 会替换发现文件中的值，而不是因为扁平化的 `process.env` 视图认为写入会被遮蔽就加以拒绝。
 
@@ -38,7 +38,7 @@ OPENAI_API_KEY: sk-…
 
 ## Alternatives considered
 
-**保留单一的 `$DSH_HOME/.env`，让 CLI 去提升它。** 否决：提升存储本身正是让已存密钥无法轮换的原因，这也是 [app-boot 当初记录该排除](../../../../packages/ui/app-boot/README.md)的理由。冲突来自这个文件的两份工作，而不是加载器。
+**保留单一的 `$DSH_HOME/.env`，让 CLI 去提升它。** 否决：提升存储本身正是让已存密钥无法轮换的原因，这也是 [app-boot 当初记录该排除](../../../../packages/boot/app-boot/README.md)的理由。冲突来自这个文件的两份工作，而不是加载器。
 
 **`$DSH_HOME/.credentials.env`——第二个 dotenv 文件。** 否决：dotenv 适合环境层，却无法表达「一份按凭据引用索引的受管文档」。它无法拒绝非字符串或无法寻址的键，而且它的行编辑器本来就会拒绝无法加引号的值，留下可读却不可写的条目。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
index 4931fa907b..fda3830670 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.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 .agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
-2026-07-31-fail-loud-releases-the-terminal.md: 2a6e7fcbbdd5d35bcf70dee09fdb9e5592486b78
-2026-07-31-fail-loud-releases-the-terminal.zh.md: f75c21cf79b241e6714c10ec7df9ac25f3d978b4
+2026-07-31-fail-loud-releases-the-terminal.md: 5fe812e5fe64a1fab8ba9808d87f3581b6f5b206
+2026-07-31-fail-loud-releases-the-terminal.zh.md: 64459614dc3376a1c773de72cd36aa455894a03c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
index 2a6e7fcbbd..5fe812e5fe 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
@@ -52,7 +52,7 @@ The guarantee belongs to whichever bin owns the terminal: a surface that grabs t
 
 ## Testing
 
-`packages/ui/app-boot/tests/app-boot.spec.ts` covers the release contract: the hook is awaited before the exit commits, a rejecting hook still exits 1, a never-settling hook exits after `FAIL_LOUD_RELEASE_TIMEOUT_MS`, and a burst of rejections reports only the first while the release still completes.
+`packages/boot/app-boot/tests/app-boot.spec.ts` covers the release contract: the hook is awaited before the exit commits, a rejecting hook still exits 1, a never-settling hook exits after `FAIL_LOUD_RELEASE_TIMEOUT_MS`, and a burst of rejections reports only the first while the release still completes.
 
 Those fake-process tests cannot observe the two failure modes that matter most — process exit code with a real event loop, and terminal state after exit — so the regression lives in `apps/cli/tests/tui-keyless-smoke.e2e.ts`. It boots the shipped tree in a real PTY over `fixtures/tui-invalid-provider.cordis.yml` (a list-shaped `providers`, the mistake users actually make), expects exit 1, and asserts the captured bytes contain both the labelled boot rejection (`dsh: plugin tree failed to load:`) and `ESC[?2004l`. The same case pins the boot path end to end: it caught the [HMR initial-scan boot deadlock](2026-08-03-hmr-initial-scan-boot-deadlock.md) that silently exited 13 with the terminal stranded.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
index f75c21cf79..64459614dc 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
@@ -52,7 +52,7 @@ Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动
 
 ## Testing
 
-`packages/ui/app-boot/tests/app-boot.spec.ts` 覆盖 release 契约：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
+`packages/boot/app-boot/tests/app-boot.spec.ts` 覆盖 release 契约：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
 
 这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态被残留的 [HMR 初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
index 4752010ef6..36c7895ac2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.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 .agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
-2026-08-03-cli-signal-shutdown-escalation.md: 7c9715c37ee57be9fa0f67af0c19f0bfa84845da
-2026-08-03-cli-signal-shutdown-escalation.zh.md: f3485edc9e453c0b774f442bfce6d678d63f2224
+2026-08-03-cli-signal-shutdown-escalation.md: c8aac6e2be927bd1f4a445c00e0aaa870b10a465
+2026-08-03-cli-signal-shutdown-escalation.zh.md: 66fe7062ea35a6cc91dbdd6644088cb086a15439
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
index 7c9715c37e..c8aac6e2be 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
@@ -49,4 +49,4 @@ The controller is launcher infrastructure rather than a Cordis plugin: it makes
 
 `apps/cli/tests/headless-shutdown.e2e.ts` boots the real shipped Web/headless Loader tree in a PTY with a test-only plugin whose disposer announces entry and never settles. The test sends SIGINT after the observation URL, waits for proof that disposal started, sends SIGINT again, and requires exit 130. The source/artifact launch resolver keeps the same regression on both execution planes. This PTY case covers the user-visible process state; no model-output snapshot changes.
 
-`packages/telemetry/session-telemetry-otel/tests/otel.spec.ts` holds a real OTLP request open after timer export begins and pins that Cordis disposal returns at `shutdownTimeoutMillis`, despite the SDK's `forceFlush()` remaining pending. The collector is then released so the still-observed provider Promise settles cleanly.
+`packages/session/session-telemetry-otel/tests/otel.spec.ts` holds a real OTLP request open after timer export begins and pins that Cordis disposal returns at `shutdownTimeoutMillis`, despite the SDK's `forceFlush()` remaining pending. The collector is then released so the still-observed provider Promise settles cleanly.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
index f3485edc9e..66fe7062ea 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
@@ -49,4 +49,4 @@ headless 对完成的轮次仍以 0 退出，对其他轮次结束原因或 API
 
 `apps/cli/tests/headless-shutdown.e2e.ts` 在 PTY 中启动真实交付的 Web/headless Loader 插件树，并挂载一个仅用于测试的插件；该插件的 disposer 会声明已经进入清理流程，但永不结算。测试在观察地址出现后发送 SIGINT，等待 dispose 已启动的证据，再次发送 SIGINT，并要求进程以 130 退出。源码／产物启动解析器使两个执行平面都覆盖同一项回归。该 PTY 用例覆盖用户可见的进程状态；模型输出快照没有变化。
 
-`packages/telemetry/session-telemetry-otel/tests/otel.spec.ts` 在定时器导出开始后保持一条真实 OTLP 请求打开，并固定以下行为：即使 SDK 的 `forceFlush()` 仍待结算，Cordis dispose 也会在 `shutdownTimeoutMillis` 到期时返回。随后测试释放 collector，使仍受观察的提供方 Promise 干净结算。
+`packages/session/session-telemetry-otel/tests/otel.spec.ts` 在定时器导出开始后保持一条真实 OTLP 请求打开，并固定以下行为：即使 SDK 的 `forceFlush()` 仍待结算，Cordis dispose 也会在 `shutdownTimeoutMillis` 到期时返回。随后测试释放 collector，使仍受观察的提供方 Promise 干净结算。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
index 170627ea76..51fbed7ba9 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.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 .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
-2026-08-03-hmr-initial-scan-boot-deadlock.md: 4b3e259c216d258c321ab06c41225b33ed240d19
-2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: ce1bc8396ac6e7fb6ecb1647fe2b29cdc788c7e1
+2026-08-03-hmr-initial-scan-boot-deadlock.md: 1a70fbafc74a1bf7024c675ddad82acefc995b72
+2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: 5f8d50c4c0103eb2209eafb89cf34233c4c1bc35
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
index 4b3e259c21..1a70fbafc7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
@@ -38,4 +38,4 @@ One latent gap remains: a config edit made during a *failing* initial apply can
 
 ## Testing
 
-The `dsh` invalid-provider PTY case in `apps/cli/tests/tui-keyless-smoke.e2e.ts` pins the end-to-end contract: exit 1, the labelled `dsh: plugin tree failed to load:` diagnostic naming `$.providers`, and the bracketed-paste reset proving the tree was disposed. Before this fix the same case observed exit 13 with no diagnostic. Reload behavior stays covered by `packages/ui/app-boot/tests/config-reload.spec.ts` and `packages/ui/app-boot/tests/hmr-config.spec.ts`.
+The `dsh` invalid-provider PTY case in `apps/cli/tests/tui-keyless-smoke.e2e.ts` pins the end-to-end contract: exit 1, the labelled `dsh: plugin tree failed to load:` diagnostic naming `$.providers`, and the bracketed-paste reset proving the tree was disposed. Before this fix the same case observed exit 13 with no diagnostic. Reload behavior stays covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/boot/app-boot/tests/hmr-config.spec.ts`.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
index ce1bc8396a..5f8d50c4c0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
@@ -38,4 +38,4 @@
 
 ## 测试
 
-`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端契约：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/ui/app-boot/tests/config-reload.spec.ts` 与 `packages/ui/app-boot/tests/hmr-config.spec.ts` 覆盖。
+`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端契约：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/boot/app-boot/tests/config-reload.spec.ts` 与 `packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖。
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
index 8374a59b63..9f60321cc8 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-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 .agents/notes/implemented/feature/2026-07-28-feedback-command.md
-2026-07-28-feedback-command.md: 56660b3796c44d3d510dd2901e6a155498673d88
-2026-07-28-feedback-command.zh.md: ec03a5c4a0e96d5350085c3d8d26f2523962f1b5
+2026-07-28-feedback-command.md: 78cc9e89a5811b3f1520bae2bd971cbcf2522ede
+2026-07-28-feedback-command.zh.md: c8870ca2988501d7899ae826e1bbcbad0bef5678
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
index 56660b3796..78cc9e89a5 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.md
@@ -46,7 +46,7 @@ Surrounding whitespace is discarded, but nothing else is parsed. `/feedback /pla
 
 **Make `/feedback` a true no-op that records nothing.** The most literal reading of "does not do anything". Rejected because it makes the command pointless: the stated requirement was that the remark reach the session log.
 
-**Register the command inside an existing package** such as `packages/ui/commands`. Avoids a new group and its README pair. Rejected: `ctx.commands` is the registry, not a home for arbitrary command implementations, and the requester asked for a standalone package.
+**Register the command inside an existing package** such as `packages/interaction/commands`. Avoids a new group and its README pair. Rejected: `ctx.commands` is the registry, not a home for arbitrary command implementations, and the requester asked for a standalone package.
 
 **Parse structure out of the text** (category prefixes, severity markers). Rejected as speculative: no consumer needs that structure, and any control-word grammar makes the corresponding literal feedback unrecordable. Verbatim text is the widest surface a future consumer can narrow; a parsed one cannot be widened after the fact.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
index ec03a5c4a0..c8870ca298 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
@@ -46,7 +46,7 @@ Status: implemented
 
 **让 `/feedback` 成为真正的空操作，什么都不记录。** 这是对「什么都不做」最字面的理解。已否决：这会使命令失去意义——明确的要求是让这条评论进入会话日志。
 
-**在现有包中注册该命令**，例如 `packages/ui/commands`。可省去新分组及其双语 README。已否决：`ctx.commands` 是注册表，而不是任意命令实现的归属地；且请求者明确要求独立的包。
+**在现有包中注册该命令**，例如 `packages/interaction/commands`。可省去新分组及其双语 README。已否决：`ctx.commands` 是注册表，而不是任意命令实现的归属地；且请求者明确要求独立的包。
 
 **从文本中解析结构**（类别前缀、严重程度标记）。已否决，属于投机设计：没有消费方需要该结构，而任何控制词语法都会让对应的字面反馈无法记录。原样文本是未来消费方可以收窄的最宽接口；而已被解析的接口无法事后放宽。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
index 620fa2291f..8109eb4854 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
 2026-07-24-domain-kv-storage-and-workspace.md: 1cb2bc4b29c196dbb33292547c75d01a37f06772
-2026-07-24-domain-kv-storage-and-workspace.zh.md: 15460e305d2d9aca3009025cf0218eb6c54c7237
+2026-07-24-domain-kv-storage-and-workspace.zh.md: 2904065a7374803495a9bbf8ff4e044310d9bd02
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
index 15460e305d..2904065a73 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-host 侧唯一的持久化面是 session 事件日志（`packages/session-persistence`：仅追加、一 session 一文件）。凡是"不属于某个 session"的信息就没有落盘处，眼下有两个真实需求：
+host 侧唯一的持久化面是 session 事件日志（`packages/session/session-persistence`：仅追加、一 session 一文件）。凡是"不属于某个 session"的信息就没有落盘处，眼下有两个真实需求：
 
 - **workspace 实体**。GUI 要把 workspace 做成真实对象：路径、标题、关联 session 清单。归属关系由 workspace 持有——"哪些 session 属于这个 workspace"不是任何单个 session 自己的事实，塞进 session log 语义不成立。此前 workspace 只是 sidebar 上按 cwd 分组的视觉概念，没有实体（该结论已被推翻）。
 - **session 动态元信息**（可预见的第二个消费方）。冷会话列表只读日志首行 header（创建时的不可变快照），title、结束状态这类随会话推进变化的信息拿不到；补齐方向是 sidecar 元数据表——正是一张按 key 高频点更新的 KV 表。
diff --git a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml
deleted file mode 100644
index cdd772386f..0000000000
--- a/.agents/notes/proposed/architecture/2026-07-29-package-regrouping.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# 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/proposed/architecture/2026-07-29-package-regrouping.md
-2026-07-29-package-regrouping.md: 9a56f9f5f1e0aef7d1f9efe60168ec1b0f41cce8
-2026-07-29-package-regrouping.zh.md: c49c5a1daffaff599f70f36b62e4dd3b5de3e5cf
diff --git a/AGENTS.md b/AGENTS.md
index 35fbc54ca6..dcb001768e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,22 +25,22 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   web/         web seam + search/fetch providers + model-facing web tools
   compact/     compaction seam + basic backend
   context/     request-context plugins
-  subagent/    subagent seam + spawn/fork/ACP backends + delegation tool
-  bundle/      profile plugin bundles: installable patch layers for dsh --profile
+  subagent/    subagent seam + spawn/fork/ACP backends + tool
+  bundle/      installable dsh --profile patch-layer bundles
   workflow/    workflow seam + worker-thread engine + workflow tool
   todo/        todo_write tool
-  plan/        plan mode as logged collaboration state
-  guard/       loop-hygiene plugins + tool-call timeouts
-  self-modification/  the agent inspects/mounts plugins in its runtime
-  hooks/       Claude Code/Codex hook bridges + shared wire-protocol library
-  session/     durable session data plane: persistence, projection, titles, reporting
-  settings/    user-settings seam + file-backed provider
-  credentials/ credential-reference seam + env-over-.env provider
+  plan/        plan mode as logged state
+  guard/       loop-hygiene + tool-timeout plugins
+  self-modification/  the agent inspects/mounts its own plugins
+  hooks/       Claude Code/Codex hook bridges + wire-protocol library
+  session/     durable session data: persistence, projection, titles, telemetry
+  settings/    user-settings seam + file provider
+  credentials/ credential-reference seam + env/.env provider
   acp/         automation-only Agent Client Protocol server
-  interaction/ approval/interaction seams, permission, commands, ask-user tool
-  boot/        shared app-bin boot glue
-  scaffold/    project tooling: helper, launcher, initializer, SDK wire protocol + ends
-  examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load
+  interaction/ approval/interaction seams, permission, commands, ask-user
+  boot/        shared app-bin glue
+  scaffold/    project tooling: helper, launcher, initializer, SDK protocol
+  examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins)
   support/     dev/test infrastructure
   util/        zero-dependency utilities
 python/      Python SDK and bundled runtime (see python/README.md)
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 27e391320a..325de8db4e 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
-README.md: 496cecdb64e3254a2a77690f55f760b4cd90b521
-README.zh.md: 4673bf764347307a9b91e2a5474a8439cf67b481
+README.md: e616b420d60e0fa372bf38950207245cb60ced98
+README.zh.md: a65140e6dc9374e21bdd3018bce45432794a7b10
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index 496cecdb64..e616b420d6 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -69,7 +69,7 @@ The base bundle mounts the native DeepSeek adapter, settings and credential prov
 
 Session events stream as OTLP/HTTP logs by default. `DSH_TELEMETRY_OTLP_URL` selects another collector. Any non-empty `DSH_TELEMETRY_DISABLED` disables the telemetry row before boot. The shipped base has no telemetry redaction rule, so exported records can contain message text, tool arguments and results, and workspace paths; the [telemetry Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md) owns that deployment decision.
 
-The empty `repository-plugins` row lets profile patch layers mount prepared immutable repository Plugin generations. See the [repository Plugin contract](../../../packages/cordis/repository-plugin/README.md#standalone-app-configuration). The CLI also ships `@deepseek-ai/dsh-mcp-client` as a dependency for patch layers, but no MCP server is enabled by default because each server command is trusted executable code outside the agent sandbox.
+The empty `repository-plugins` row lets profile patch layers mount prepared immutable repository Plugin generations. See the [repository Plugin contract](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration). The CLI also ships `@deepseek-ai/dsh-mcp-client` as a dependency for patch layers, but no MCP server is enabled by default because each server command is trusted executable code outside the agent sandbox.
 
 ## Source launcher
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index 4673bf7643..a65140e6dc 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -69,7 +69,7 @@ dsh web --dump-config
 
 会话事件默认作为 OTLP/HTTP 日志流式发送。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。任何非空 `DSH_TELEMETRY_DISABLED` 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由[遥测 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)负责。
 
-空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 契约](../../../packages/cordis/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
+空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 契约](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
 
 ## 源码启动器
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index c74358fd39..254d85ccd1 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -76,7 +76,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
+Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
 
 Source: [`packages/examples/acp-demo/src/index.ts:39`](../packages/examples/acp-demo/src/index.ts)
 
@@ -639,7 +639,7 @@ export interface JsonRpcConfig {
 
 Depends on: `Readable` (`node:stream`) · `Writable` (`node:stream`)
 
-Source: [`packages/ui/jsonrpc/src/index.ts:25`](../packages/ui/jsonrpc/src/index.ts)
+Source: [`packages/scaffold/server/src/index.ts:29`](../packages/scaffold/server/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-deepseek`
 
@@ -1046,7 +1046,7 @@ export interface PresetSpec {
 
 Depends on: [`ApprovalPolicy`](core-data-structures/approval.md) · [`SandboxMode`](core-data-structures/sandbox.md)
 
-Source: [`packages/ui/permission/src/index.ts:140`](../packages/ui/permission/src/index.ts)
+Source: [`packages/interaction/permission/src/index.ts:140`](../packages/interaction/permission/src/index.ts)
 
 ## `@deepseek-ai/dsh-plan-mode`
 
@@ -1182,7 +1182,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/cordis/repository-plugin/src/index.ts:42`](../packages/cordis/repository-plugin/src/index.ts)
+Source: [`packages/self-modification/repository-plugin/src/index.ts:42`](../packages/self-modification/repository-plugin/src/index.ts)
 
 ## `@deepseek-ai/dsh-sandbox-local`
 
@@ -1273,7 +1273,7 @@ export interface Config {
 export type JsonlCompression = 'zstd' | 'none'
 ```
 
-Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:59`](../packages/session-persistence/session-persistence-jsonl/src/index.ts)
+Source: [`packages/session/session-persistence-jsonl/src/index.ts:59`](../packages/session/session-persistence-jsonl/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-persistence-sqlite`
 
@@ -1316,7 +1316,7 @@ export interface Config {
 export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 ```
 
-Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:67`](../packages/session-persistence/session-persistence-sqlite/src/index.ts)
+Source: [`packages/session/session-persistence-sqlite/src/index.ts:67`](../packages/session/session-persistence-sqlite/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-projection-cache`
 
@@ -1337,7 +1337,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/session-projection/session-projection-cache/src/index.ts:42`](../packages/session-projection/session-projection-cache/src/index.ts)
+Source: [`packages/session/session-projection-cache/src/index.ts:42`](../packages/session/session-projection-cache/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-query-sqlite`
 
@@ -1437,7 +1437,7 @@ export enum TelemetryMode {
 
 Depends on: `BatchLogRecordProcessorOptions` (`@opentelemetry/sdk-logs`) · `OTLPExporterNodeConfigBase` (`@opentelemetry/otlp-exporter-base`)
 
-Source: [`packages/telemetry/session-telemetry-otel/src/index.ts:80`](../packages/telemetry/session-telemetry-otel/src/index.ts)
+Source: [`packages/session/session-telemetry-otel/src/index.ts:80`](../packages/session/session-telemetry-otel/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title`
 
@@ -1455,7 +1455,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/session-title/session-title/src/index.ts:79`](../packages/session-title/session-title/src/index.ts)
+Source: [`packages/session/session-title/src/index.ts:79`](../packages/session/session-title/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title-all-messages-llm`
 
@@ -1466,9 +1466,9 @@ Requires: `sessionTitle` · `llm` · `sessions`
 export type Config = SessionTitleLlmConfig
 ```
 
-Depends on: [`SessionTitleLlmConfig`](../packages/session-title/session-title-llm/src/index.ts)
+Depends on: [`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/index.ts)
 
-Source: [`packages/session-title/session-title-all-messages-llm/src/index.ts:15`](../packages/session-title/session-title-all-messages-llm/src/index.ts)
+Source: [`packages/session/session-title-all-messages-llm/src/index.ts:15`](../packages/session/session-title-all-messages-llm/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-title-first-message-llm`
 
@@ -1479,9 +1479,9 @@ Requires: `sessionTitle` · `llm` · `sessions`
 export type Config = SessionTitleLlmConfig
 ```
 
-Depends on: [`SessionTitleLlmConfig`](../packages/session-title/session-title-llm/src/index.ts)
+Depends on: [`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/index.ts)
 
-Source: [`packages/session-title/session-title-first-message-llm/src/index.ts:15`](../packages/session-title/session-title-first-message-llm/src/index.ts)
+Source: [`packages/session/session-title-first-message-llm/src/index.ts:15`](../packages/session/session-title-first-message-llm/src/index.ts)
 
 ## `@deepseek-ai/dsh-settings-local`
 
@@ -1955,7 +1955,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/cordis/tool-cordis/src/index.ts:25`](../packages/cordis/tool-cordis/src/index.ts)
+Source: [`packages/self-modification/tool-cordis/src/index.ts:25`](../packages/self-modification/tool-cordis/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-fs`
 
@@ -2365,7 +2365,7 @@ export interface Config {
 export type ApprovalPolicy = 'ask' | 'never'
 ```
 
-Source: [`packages/ui/user-approval/src/index.ts:178`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:178`](../packages/interaction/user-approval/src/index.ts)
 
 ## `@deepseek-ai/dsh-web`
 
@@ -2602,7 +2602,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-command-compact` — requires `commands` · `compact` ([`packages/compact/command-compact/src/index.ts`](../packages/compact/command-compact/src/index.ts))
 - `@deepseek-ai/dsh-command-feedback` — requires `commands` ([`packages/feedback/command-feedback/src/index.ts`](../packages/feedback/command-feedback/src/index.ts))
 - `@deepseek-ai/dsh-command-goal` — requires `commands` · `goals` ([`packages/goal/command-goal/src/index.ts`](../packages/goal/command-goal/src/index.ts))
-- `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts))
+- `@deepseek-ai/dsh-commands` ([`packages/interaction/commands/src/index.ts`](../packages/interaction/commands/src/index.ts))
 - `@deepseek-ai/dsh-fs-e2b` — requires `e2b` ([`packages/e2b/fs-e2b/src/index.ts`](../packages/e2b/fs-e2b/src/index.ts))
 - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts))
 - `@deepseek-ai/dsh-goal-session` — requires `agents` · `goals` · `sessions` ([`packages/goal/goal-session/src/index.ts`](../packages/goal/goal-session/src/index.ts))
@@ -2612,17 +2612,17 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-lsp` ([`packages/lsp/lsp/src/index.ts`](../packages/lsp/lsp/src/index.ts))
 - `@deepseek-ai/dsh-pty` ([`packages/pty/pty/src/index.ts`](../packages/pty/pty/src/index.ts))
 - `@deepseek-ai/dsh-session` ([`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts))
-- `@deepseek-ai/dsh-session-checkpoint-policy` — requires `llm` · `sessionPersistence` · `sessions` · `tools` ([`packages/session-persistence/session-checkpoint-policy/src/index.ts`](../packages/session-persistence/session-checkpoint-policy/src/index.ts))
-- `@deepseek-ai/dsh-session-projection` ([`packages/session-projection/session-projection/src/index.ts`](../packages/session-projection/session-projection/src/index.ts))
+- `@deepseek-ai/dsh-session-checkpoint-policy` — requires `llm` · `sessionPersistence` · `sessions` · `tools` ([`packages/session/session-checkpoint-policy/src/index.ts`](../packages/session/session-checkpoint-policy/src/index.ts))
+- `@deepseek-ai/dsh-session-projection` ([`packages/session/session-projection/src/index.ts`](../packages/session/session-projection/src/index.ts))
 - `@deepseek-ai/dsh-skill-badge` — requires `skills` ([`packages/skill/skill-badge/src/index.ts`](../packages/skill/skill-badge/src/index.ts))
 - `@deepseek-ai/dsh-storage` ([`packages/storage/storage/src/index.ts`](../packages/storage/storage/src/index.ts))
 - `@deepseek-ai/dsh-subagent` ([`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts))
 - `@deepseek-ai/dsh-subprocess-local` ([`packages/subprocess/subprocess-local/src/index.ts`](../packages/subprocess/subprocess-local/src/index.ts))
 - `@deepseek-ai/dsh-tasks-local` ([`packages/tasks/tasks-local/src/index.ts`](../packages/tasks/tasks-local/src/index.ts))
-- `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/timeout/timeout-policy/src/index.ts`](../packages/timeout/timeout-policy/src/index.ts))
-- `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/ui/tool-ask-user/src/index.ts`](../packages/ui/tool-ask-user/src/index.ts))
+- `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/guard/timeout-policy/src/index.ts`](../packages/guard/timeout-policy/src/index.ts))
+- `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts))
 - `@deepseek-ai/dsh-tool-subagent-control` — requires `tools` · `subagents` ([`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts))
-- `@deepseek-ai/dsh-user-interaction` ([`packages/ui/user-interaction/src/index.ts`](../packages/ui/user-interaction/src/index.ts))
+- `@deepseek-ai/dsh-user-interaction` ([`packages/interaction/user-interaction/src/index.ts`](../packages/interaction/user-interaction/src/index.ts))
 - `@deepseek-ai/dsh-workspace` — requires `storageDomain` · `sessionPersistence` ([`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts))
 
 ## Seam packages (not directly loadable)
@@ -2636,7 +2636,7 @@ Abstract service classes — a deployment loads a concrete implementation packag
 - `@deepseek-ai/dsh-fs` — abstract `FileSystem` ([`packages/fs/fs/src/index.ts`](../packages/fs/fs/src/index.ts))
 - `@deepseek-ai/dsh-host-directory-picker` — abstract `DirectoryPicker` ([`packages/host/directory-picker/src/index.ts`](../packages/host/directory-picker/src/index.ts))
 - `@deepseek-ai/dsh-sandbox` — abstract `SandboxProvider` ([`packages/sandbox/sandbox/src/index.ts`](../packages/sandbox/sandbox/src/index.ts))
-- `@deepseek-ai/dsh-session-persistence` — abstract `SessionPersistence` ([`packages/session-persistence/session-persistence/src/index.ts`](../packages/session-persistence/session-persistence/src/index.ts))
+- `@deepseek-ai/dsh-session-persistence` — abstract `SessionPersistence` ([`packages/session/session-persistence/src/index.ts`](../packages/session/session-persistence/src/index.ts))
 - `@deepseek-ai/dsh-session-query` — abstract `SessionQueryService` ([`packages/session-query/session-query/src/index.ts`](../packages/session-query/session-query/src/index.ts))
 - `@deepseek-ai/dsh-settings` — abstract `Settings` ([`packages/settings/settings/src/index.ts`](../packages/settings/settings/src/index.ts))
 - `@deepseek-ai/dsh-spill` — abstract `SpillStore` ([`packages/spill/spill/src/index.ts`](../packages/spill/spill/src/index.ts))
@@ -2648,10 +2648,10 @@ Abstract service classes — a deployment loads a concrete implementation packag
 
 Imported as libraries by other packages; a `cordis.yml` cannot load them.
 
-- `@deepseek-ai/create-sdk` ([`packages/sdk/create-sdk/src/index.ts`](../packages/sdk/create-sdk/src/index.ts))
+- `@deepseek-ai/create-sdk` ([`packages/scaffold/create-sdk/src/index.ts`](../packages/scaffold/create-sdk/src/index.ts))
 - `@deepseek-ai/dsh-acp-snapshot` ([`packages/support/acp-snapshot/src/index.ts`](../packages/support/acp-snapshot/src/index.ts))
 - `@deepseek-ai/dsh-agent-loop-testkit` ([`packages/support/agent-loop-testkit/src/index.ts`](../packages/support/agent-loop-testkit/src/index.ts))
-- `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
+- `@deepseek-ai/dsh-app-boot` ([`packages/boot/app-boot/src/index.ts`](../packages/boot/app-boot/src/index.ts))
 - `@deepseek-ai/dsh-atomic-write` ([`packages/util/atomic-write/src/index.ts`](../packages/util/atomic-write/src/index.ts))
 - `@deepseek-ai/dsh-base` ([`packages/bundle/base/src/index.ts`](../packages/bundle/base/src/index.ts))
 - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
@@ -2662,7 +2662,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-client-web` ([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts))
 - `@deepseek-ai/dsh-client-web-react` ([`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts))
 - `@deepseek-ai/dsh-environment` ([`packages/util/environment/src/index.ts`](../packages/util/environment/src/index.ts))
-- `@deepseek-ai/dsh-helper` ([`packages/sdk/helper/src/index.ts`](../packages/sdk/helper/src/index.ts))
+- `@deepseek-ai/dsh-helper` ([`packages/scaffold/helper/src/index.ts`](../packages/scaffold/helper/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
 - `@deepseek-ai/dsh-jsonrpc-demo` ([`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts))
 - `@deepseek-ai/dsh-llm-mock-server` ([`packages/support/llm-mock-server/src/index.ts`](../packages/support/llm-mock-server/src/index.ts))
@@ -2671,13 +2671,13 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-paths` ([`packages/util/paths/src/index.ts`](../packages/util/paths/src/index.ts))
 - `@deepseek-ai/dsh-retention` ([`packages/util/retention/src/index.ts`](../packages/util/retention/src/index.ts))
 - `@deepseek-ai/dsh-scope` ([`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts))
-- `@deepseek-ai/dsh-scripts` ([`packages/sdk/scripts/src/index.ts`](../packages/sdk/scripts/src/index.ts))
-- `@deepseek-ai/dsh-sdk-client` ([`packages/sdk/sdk-client/src/index.ts`](../packages/sdk/sdk-client/src/index.ts))
-- `@deepseek-ai/dsh-sdk-protocol` ([`packages/sdk/sdk-protocol/src/index.ts`](../packages/sdk/sdk-protocol/src/index.ts))
-- `@deepseek-ai/dsh-session-telemetry` ([`packages/telemetry/session-telemetry/src/index.ts`](../packages/telemetry/session-telemetry/src/index.ts))
-- `@deepseek-ai/dsh-session-title-llm` ([`packages/session-title/session-title-llm/src/index.ts`](../packages/session-title/session-title-llm/src/index.ts))
+- `@deepseek-ai/dsh-scripts` ([`packages/scaffold/scripts/src/index.ts`](../packages/scaffold/scripts/src/index.ts))
+- `@deepseek-ai/dsh-sdk-client` ([`packages/scaffold/client/src/index.ts`](../packages/scaffold/client/src/index.ts))
+- `@deepseek-ai/dsh-sdk-protocol` ([`packages/scaffold/protocol/src/index.ts`](../packages/scaffold/protocol/src/index.ts))
+- `@deepseek-ai/dsh-session-telemetry` ([`packages/session/session-telemetry/src/index.ts`](../packages/session/session-telemetry/src/index.ts))
+- `@deepseek-ai/dsh-session-title-llm` ([`packages/session/session-title-llm/src/index.ts`](../packages/session/session-title-llm/src/index.ts))
 - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))
-- `@deepseek-ai/dsh-telemetry` ([`packages/sdk/telemetry/src/index.ts`](../packages/sdk/telemetry/src/index.ts))
+- `@deepseek-ai/dsh-telemetry` ([`packages/scaffold/telemetry/src/index.ts`](../packages/scaffold/telemetry/src/index.ts))
 - `@deepseek-ai/dsh-timeout` ([`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts))
 - `@deepseek-ai/dsh-type-meta` ([`packages/typert/type-meta/src/index.ts`](../packages/typert/type-meta/src/index.ts))
 - `@deepseek-ai/dsh-typert-generator` ([`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts))
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 7015d39bc8..2c99c451d2 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -325,7 +325,7 @@ Ask composed answerers for one decision. Return an outcome to claim the request
 
 Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [ApprovalService](../core-data-structures/approval.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/ui/user-approval/src/index.ts:30`](../../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts)
 
 ## `commands/*`
 
@@ -343,7 +343,7 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/ui/commands/src/index.ts:172`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
 
 ## `credentials/*`
 
@@ -822,7 +822,7 @@ Transform one outbound record before it reaches the backend. This waterfall is t
 'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
 ```
 
-Source: [`packages/telemetry/session-telemetry/src/index.ts:43`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/session/session-telemetry/src/index.ts:43`](../../packages/session/session-telemetry/src/index.ts)
 
 ## `tools/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 8af0e6ca30..56a0d0d2e6 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -262,7 +262,7 @@ overrideOf(session: Session): ApprovalPolicy | undefined
 
 Types: [Agent](../core-data-structures/core.md) · [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalPolicy](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [Session](../core-data-structures/session.md)
 
-Source: [`packages/ui/user-approval/src/index.ts:193`](../../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
 
 ## `ctx.bash` — `BashExecutor` (abstract seam)
 
@@ -451,7 +451,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](../core-data-structures/core.md) · [CommandDefinition](../core-data-structures/commands.md) · [CommandDescriptor](../core-data-structures/commands.md)
 
-Source: [`packages/ui/commands/src/index.ts:305`](../../packages/ui/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
 
 ## `ctx.compact` — `CompactService` (abstract seam)
 
@@ -1062,7 +1062,7 @@ set(session: Session, name: string): void
 
 Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/ui/permission/src/index.ts:159`](../../packages/ui/permission/src/index.ts)
+Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
 
 ## `ctx.planMode` — `PlanModeService`
 
@@ -1352,7 +1352,7 @@ abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot
 
 Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) · [SessionInspection](../core-data-structures/persistence.md) · [SessionLocation](../core-data-structures/persistence.md) · [SessionPersistenceSnapshot](../core-data-structures/persistence.md) · [SessionPreparation](../core-data-structures/persistence.md)
 
-Source: [`packages/session-persistence/session-persistence/src/index.ts:72`](../../packages/session-persistence/session-persistence/src/index.ts)
+Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
 
 ## `ctx.sessionProjectionCache` — `SessionProjectionCache`
 
@@ -1400,7 +1400,7 @@ async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnaps
 
 Types: [Session](../core-data-structures/session.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md)
 
-Source: [`packages/session-projection/session-projection-cache/src/index.ts:71`](../../packages/session-projection/session-projection-cache/src/index.ts)
+Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
 
 ## `ctx.sessionProjections` — `SessionProjectionRegistry`
 
@@ -1508,7 +1508,7 @@ restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseS
 
 Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/session-projection/session-projection/src/index.ts:156`](../../packages/session-projection/session-projection/src/index.ts)
+Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
 
 ## `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
 
@@ -1846,7 +1846,7 @@ register(provider: SessionTitleProvider): () => Promise<void>
 
 Types: [Session](../core-data-structures/session.md) · [SessionTitleProvider](../core-data-structures/session-title.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
 
-Source: [`packages/session-title/session-title/src/index.ts:261`](../../packages/session-title/session-title/src/index.ts)
+Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts)
 
 ## `ctx.settings` — `Settings` (abstract seam)
 
@@ -2473,7 +2473,7 @@ flush?(): void
 abstract shutdown(): Promise<void>
 ```
 
-Source: [`packages/telemetry/session-telemetry/src/index.ts:140`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/session/session-telemetry/src/index.ts)
 
 ## `ctx.tokenMeter` — `TokenMeterService`
 
@@ -2745,7 +2745,7 @@ async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 
 Types: [AskUserQuestionAnswer](../core-data-structures/user-interaction.md) · [AskUserQuestionRequest](../core-data-structures/user-interaction.md) · [UserInteractionProvider](../core-data-structures/user-interaction.md)
 
-Source: [`packages/ui/user-interaction/src/index.ts:51`](../../packages/ui/user-interaction/src/index.ts)
+Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts)
 
 ## `ctx.web` — `WebService`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 9699870ecc..f5ea3eba36 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -10,18 +10,18 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
 | `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
 | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
 | `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
 | `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
 | `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:185`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
 | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
 | `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
 | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), [`jsonrpc`](../packages/ui/jsonrpc) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:30`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:172`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy` |
+| `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:64`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
@@ -29,24 +29,24 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:56`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
-| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-title`](../packages/session-title/session-title) |
-| `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
-| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`loader-smoke`](../packages/support/loader-smoke), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
-| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
+| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/support/loader-smoke), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workspace-context`](../packages/context/workspace-context) |
+| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:283`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
-| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), `server`, [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:136`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
-| `telemetry/record` | `waterfall` | [`packages/telemetry/session-telemetry/src/index.ts:43`](../packages/telemetry/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/telemetry/session-telemetry) (`waterfall`) | - |
+| `telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
 | `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:173`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
-| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`timeout-policy`](../packages/timeout/timeout-policy) |
+| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
 | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:160`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
 | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:137`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
 | `tools/result` | `emit` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
@@ -64,7 +64,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `commands/changed` | `runtime` (`emit`) | `ui-command` |
 | `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-permission`, `ui-settings-general` |
 | `credentials/changed` | `runtime` (`emit`) | `ui-models` |
-| `internal/dispatch` | - | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
+| `internal/dispatch` | - | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workflow`](../packages/workflow/workflow) |
 | `internal/plugin` | - | `hmr`, `loader`, [`lsp-local`](../packages/lsp/lsp-local), `modules`, `webserver` |
 | `internal/service` | - | `gateway` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 2e71473379..6f47c36e97 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -93,41 +93,22 @@ flowchart TD
     pkg_spill_local["spill-local"]
     pkg_spill_policy["spill-policy"]
   end
-  subgraph group_timeout["packages/timeout"]
-    pkg_timeout_policy["timeout-policy"]
-  end
   subgraph group_todo["packages/todo"]
     pkg_tool_todo["tool-todo"]
   end
   subgraph group_plan["packages/plan"]
     pkg_plan_mode["plan-mode"]
   end
-  subgraph group_cordis["packages/cordis"]
-    pkg_repository_plugin["repository-plugin"]
-    pkg_tool_cordis["tool-cordis"]
-  end
   subgraph group_hooks["packages/hooks"]
     pkg_hook_protocol["hook-protocol"]
     pkg_hooks_claude["hooks-claude"]
     pkg_hooks_codex["hooks-codex"]
   end
-  subgraph group_session_persistence["packages/session-persistence"]
-    pkg_session_checkpoint_policy["session-checkpoint-policy"]
-    pkg_session_persistence["session-persistence"]
-    pkg_session_persistence_jsonl["session-persistence-jsonl"]
-    pkg_session_persistence_sqlite["session-persistence-sqlite"]
-  end
   subgraph group_session_query["packages/session-query"]
     pkg_session_query["session-query"]
     pkg_session_query_sqlite["session-query-sqlite"]
     pkg_tool_session_query["tool-session-query"]
   end
-  subgraph group_session_title["packages/session-title"]
-    pkg_session_title["session-title"]
-    pkg_session_title_all_messages_llm["session-title-all-messages-llm"]
-    pkg_session_title_first_message_llm["session-title-first-message-llm"]
-    pkg_session_title_llm["session-title-llm"]
-  end
   subgraph group_support["packages/support"]
     pkg_acp_snapshot["acp-snapshot"]
     pkg_agent_loop_testkit["agent-loop-testkit"]
@@ -139,19 +120,13 @@ flowchart TD
   subgraph group_acp["packages/acp"]
     pkg_acp["acp"]
   end
-  subgraph group_ui["packages/ui"]
-    pkg_app_boot["app-boot"]
-    pkg_commands["commands"]
-    pkg_jsonrpc["jsonrpc"]
-    pkg_permission["permission"]
-    pkg_tool_ask_user["tool-ask-user"]
-    pkg_user_approval["user-approval"]
-    pkg_user_interaction["user-interaction"]
-  end
   subgraph group_api["packages/api"]
     pkg_api_gateway["api-gateway"]
     pkg_api_remotes["api-remotes"]
   end
+  subgraph group_boot["packages/boot"]
+    pkg_app_boot["app-boot"]
+  end
   subgraph group_bundle["packages/bundle"]
     pkg_base["base"]
     pkg_headless["headless"]
@@ -219,6 +194,7 @@ flowchart TD
   end
   subgraph group_guard["packages/guard"]
     pkg_repeat_tool_guard["repeat-tool-guard"]
+    pkg_timeout_policy["timeout-policy"]
   end
   subgraph group_host["packages/host"]
     pkg_frontend_static["frontend-static"]
@@ -229,6 +205,13 @@ flowchart TD
     pkg_host_directory_picker_native["host-directory-picker-native"]
     pkg_host_webserver["host-webserver"]
   end
+  subgraph group_interaction["packages/interaction"]
+    pkg_commands["commands"]
+    pkg_permission["permission"]
+    pkg_tool_ask_user["tool-ask-user"]
+    pkg_user_approval["user-approval"]
+    pkg_user_interaction["user-interaction"]
+  end
   subgraph group_lsp["packages/lsp"]
     pkg_lsp["lsp"]
     pkg_lsp_local["lsp-local"]
@@ -248,16 +231,31 @@ flowchart TD
     pkg_sandbox_local["sandbox-local"]
     pkg_sandbox_policy["sandbox-policy"]
   end
-  subgraph group_sdk["packages/sdk"]
+  subgraph group_scaffold["packages/scaffold"]
     pkg_helper["helper"]
+    pkg_jsonrpc["jsonrpc"]
     pkg_scripts["scripts"]
     pkg_sdk_client["sdk-client"]
     pkg_sdk_protocol["sdk-protocol"]
     pkg_telemetry["telemetry"]
   end
-  subgraph group_session_projection["packages/session-projection"]
+  subgraph group_self_modification["packages/self-modification"]
+    pkg_repository_plugin["repository-plugin"]
+    pkg_tool_cordis["tool-cordis"]
+  end
+  subgraph group_session["packages/session"]
+    pkg_session_checkpoint_policy["session-checkpoint-policy"]
+    pkg_session_persistence["session-persistence"]
+    pkg_session_persistence_jsonl["session-persistence-jsonl"]
+    pkg_session_persistence_sqlite["session-persistence-sqlite"]
     pkg_session_projection["session-projection"]
     pkg_session_projection_cache["session-projection-cache"]
+    pkg_session_telemetry["session-telemetry"]
+    pkg_session_telemetry_otel["session-telemetry-otel"]
+    pkg_session_title["session-title"]
+    pkg_session_title_all_messages_llm["session-title-all-messages-llm"]
+    pkg_session_title_first_message_llm["session-title-first-message-llm"]
+    pkg_session_title_llm["session-title-llm"]
   end
   subgraph group_settings["packages/settings"]
     pkg_settings["settings"]
@@ -278,10 +276,6 @@ flowchart TD
     pkg_tasks_local["tasks-local"]
     pkg_tool_tasks["tool-tasks"]
   end
-  subgraph group_telemetry["packages/telemetry"]
-    pkg_session_telemetry["session-telemetry"]
-    pkg_session_telemetry_otel["session-telemetry-otel"]
-  end
   subgraph group_typert["packages/typert"]
     pkg_type_meta["type-meta"]
     pkg_typert_generator["typert-generator"]
@@ -457,10 +451,6 @@ flowchart TD
   pkg_spill --> pkg_invariants
   pkg_spill --> pkg_llm
   pkg_spill --> pkg_session
-  pkg_session_persistence --> pkg_brand
-  pkg_session_persistence --> pkg_invariants
-  pkg_session_persistence --> pkg_session
-  pkg_session_persistence --> pkg_timeout
   pkg_acp_snapshot --> pkg_invariants
   pkg_acp_snapshot --> pkg_session
   pkg_app_boot --> pkg_environment
@@ -504,6 +494,10 @@ flowchart TD
   pkg_sandbox_local --> pkg_invariants
   pkg_sandbox_local --> pkg_llm
   pkg_sandbox_local --> pkg_sandbox
+  pkg_session_persistence --> pkg_brand
+  pkg_session_persistence --> pkg_invariants
+  pkg_session_persistence --> pkg_session
+  pkg_session_persistence --> pkg_timeout
   pkg_session_projection --> pkg_invariants
   pkg_session_projection --> pkg_session
   pkg_llm_retry --> pkg_agent
@@ -551,17 +545,6 @@ flowchart TD
   pkg_hook_protocol --> pkg_bash
   pkg_hook_protocol --> pkg_invariants
   pkg_hook_protocol --> pkg_session
-  pkg_session_persistence_jsonl --> pkg_invariants
-  pkg_session_persistence_jsonl --> pkg_session
-  pkg_session_persistence_jsonl --> pkg_session_persistence
-  pkg_session_persistence_sqlite --> pkg_invariants
-  pkg_session_persistence_sqlite --> pkg_session
-  pkg_session_persistence_sqlite --> pkg_session_persistence
-  pkg_session_title --> pkg_brand
-  pkg_session_title --> pkg_invariants
-  pkg_session_title --> pkg_llm
-  pkg_session_title --> pkg_session
-  pkg_session_title --> pkg_session_projection
   pkg_llm_replay --> pkg_compact
   pkg_llm_replay --> pkg_invariants
   pkg_llm_replay --> pkg_llm
@@ -570,21 +553,6 @@ flowchart TD
   pkg_loader_smoke --> pkg_invariants
   pkg_loader_smoke --> pkg_llm
   pkg_loader_smoke --> pkg_session
-  pkg_commands --> pkg_agent
-  pkg_commands --> pkg_brand
-  pkg_commands --> pkg_invariants
-  pkg_commands --> pkg_scope
-  pkg_commands --> pkg_session
-  pkg_user_approval --> pkg_agent
-  pkg_user_approval --> pkg_brand
-  pkg_user_approval --> pkg_invariants
-  pkg_user_approval --> pkg_llm
-  pkg_user_approval --> pkg_scope
-  pkg_user_approval --> pkg_session
-  pkg_user_approval --> pkg_system_prompt
-  pkg_user_interaction --> pkg_agent
-  pkg_user_interaction --> pkg_invariants
-  pkg_user_interaction --> pkg_llm
   pkg_headless --> pkg_agent
   pkg_headless --> pkg_host_apiproxy
   pkg_headless --> pkg_host_webserver
@@ -614,6 +582,21 @@ flowchart TD
   pkg_host_directory_picker_native --> pkg_client_ui_slots
   pkg_host_directory_picker_native --> pkg_client_ui_workspace
   pkg_host_directory_picker_native --> pkg_invariants
+  pkg_commands --> pkg_agent
+  pkg_commands --> pkg_brand
+  pkg_commands --> pkg_invariants
+  pkg_commands --> pkg_scope
+  pkg_commands --> pkg_session
+  pkg_user_approval --> pkg_agent
+  pkg_user_approval --> pkg_brand
+  pkg_user_approval --> pkg_invariants
+  pkg_user_approval --> pkg_llm
+  pkg_user_approval --> pkg_scope
+  pkg_user_approval --> pkg_session
+  pkg_user_approval --> pkg_system_prompt
+  pkg_user_interaction --> pkg_agent
+  pkg_user_interaction --> pkg_invariants
+  pkg_user_interaction --> pkg_llm
   pkg_lsp_local --> pkg_brand
   pkg_lsp_local --> pkg_fs
   pkg_lsp_local --> pkg_invariants
@@ -631,18 +614,29 @@ flowchart TD
   pkg_sandbox_policy --> pkg_system_prompt
   pkg_scripts --> pkg_app_boot
   pkg_scripts --> pkg_invariants
+  pkg_session_persistence_jsonl --> pkg_invariants
+  pkg_session_persistence_jsonl --> pkg_session
+  pkg_session_persistence_jsonl --> pkg_session_persistence
+  pkg_session_persistence_sqlite --> pkg_invariants
+  pkg_session_persistence_sqlite --> pkg_session
+  pkg_session_persistence_sqlite --> pkg_session_persistence
   pkg_session_projection_cache --> pkg_invariants
   pkg_session_projection_cache --> pkg_session
   pkg_session_projection_cache --> pkg_session_persistence
   pkg_session_projection_cache --> pkg_session_projection
   pkg_session_projection_cache --> pkg_storage_domain
+  pkg_session_telemetry --> pkg_agent
+  pkg_session_telemetry --> pkg_invariants
+  pkg_session_telemetry --> pkg_session
+  pkg_session_title --> pkg_brand
+  pkg_session_title --> pkg_invariants
+  pkg_session_title --> pkg_llm
+  pkg_session_title --> pkg_session
+  pkg_session_title --> pkg_session_projection
   pkg_tasks --> pkg_agent
   pkg_tasks --> pkg_brand
   pkg_tasks --> pkg_invariants
   pkg_tasks --> pkg_session
-  pkg_session_telemetry --> pkg_agent
-  pkg_session_telemetry --> pkg_invariants
-  pkg_session_telemetry --> pkg_session
   pkg_workflow --> pkg_agent
   pkg_workflow --> pkg_brand
   pkg_workflow --> pkg_invariants
@@ -694,24 +688,10 @@ flowchart TD
   pkg_session_query --> pkg_session
   pkg_session_query --> pkg_session_persistence
   pkg_session_query --> pkg_session_title
-  pkg_session_title_llm --> pkg_invariants
-  pkg_session_title_llm --> pkg_llm
-  pkg_session_title_llm --> pkg_session
-  pkg_session_title_llm --> pkg_session_title
-  pkg_session_title_llm --> pkg_timeout
   pkg_acp --> pkg_agent
   pkg_acp --> pkg_invariants
   pkg_acp --> pkg_session
   pkg_acp --> pkg_user_approval
-  pkg_permission --> pkg_bash
-  pkg_permission --> pkg_commands
-  pkg_permission --> pkg_invariants
-  pkg_permission --> pkg_sandbox
-  pkg_permission --> pkg_sandbox_policy
-  pkg_permission --> pkg_session
-  pkg_permission --> pkg_session_projection
-  pkg_permission --> pkg_settings
-  pkg_permission --> pkg_user_approval
   pkg_api_remotes --> pkg_agent
   pkg_api_remotes --> pkg_goal
   pkg_api_remotes --> pkg_invariants
@@ -732,6 +712,15 @@ flowchart TD
   pkg_host_directory_picker_auto --> pkg_host_directory_picker_native
   pkg_host_directory_picker_auto --> pkg_host_webserver
   pkg_host_directory_picker_auto --> pkg_invariants
+  pkg_permission --> pkg_bash
+  pkg_permission --> pkg_commands
+  pkg_permission --> pkg_invariants
+  pkg_permission --> pkg_sandbox
+  pkg_permission --> pkg_sandbox_policy
+  pkg_permission --> pkg_session
+  pkg_permission --> pkg_session_projection
+  pkg_permission --> pkg_settings
+  pkg_permission --> pkg_user_approval
   pkg_pty_local --> pkg_agent
   pkg_pty_local --> pkg_invariants
   pkg_pty_local --> pkg_pty
@@ -739,6 +728,11 @@ flowchart TD
   pkg_pty_local --> pkg_sandbox_policy
   pkg_pty_local --> pkg_session
   pkg_pty_local --> pkg_subprocess
+  pkg_session_title_llm --> pkg_invariants
+  pkg_session_title_llm --> pkg_llm
+  pkg_session_title_llm --> pkg_session
+  pkg_session_title_llm --> pkg_session_title
+  pkg_session_title_llm --> pkg_timeout
   pkg_tasks_local --> pkg_agent
   pkg_tasks_local --> pkg_invariants
   pkg_tasks_local --> pkg_tasks
@@ -820,10 +814,6 @@ flowchart TD
   pkg_spill_policy --> pkg_session
   pkg_spill_policy --> pkg_spill
   pkg_spill_policy --> pkg_tools
-  pkg_timeout_policy --> pkg_invariants
-  pkg_timeout_policy --> pkg_llm
-  pkg_timeout_policy --> pkg_timeout
-  pkg_timeout_policy --> pkg_tools
   pkg_tool_todo --> pkg_agent
   pkg_tool_todo --> pkg_invariants
   pkg_tool_todo --> pkg_session
@@ -838,9 +828,6 @@ flowchart TD
   pkg_plan_mode --> pkg_system_prompt
   pkg_plan_mode --> pkg_tools
   pkg_plan_mode --> pkg_user_interaction
-  pkg_tool_cordis --> pkg_invariants
-  pkg_tool_cordis --> pkg_scope
-  pkg_tool_cordis --> pkg_tools
   pkg_hooks_codex --> pkg_agent
   pkg_hooks_codex --> pkg_hook_protocol
   pkg_hooks_codex --> pkg_invariants
@@ -848,12 +835,6 @@ flowchart TD
   pkg_hooks_codex --> pkg_session
   pkg_hooks_codex --> pkg_session_persistence
   pkg_hooks_codex --> pkg_tools
-  pkg_session_checkpoint_policy --> pkg_agent
-  pkg_session_checkpoint_policy --> pkg_invariants
-  pkg_session_checkpoint_policy --> pkg_llm
-  pkg_session_checkpoint_policy --> pkg_session
-  pkg_session_checkpoint_policy --> pkg_session_persistence
-  pkg_session_checkpoint_policy --> pkg_tools
   pkg_session_query_sqlite --> pkg_invariants
   pkg_session_query_sqlite --> pkg_session
   pkg_session_query_sqlite --> pkg_session_persistence
@@ -865,26 +846,12 @@ flowchart TD
   pkg_tool_session_query --> pkg_system_prompt
   pkg_tool_session_query --> pkg_timeout
   pkg_tool_session_query --> pkg_tools
-  pkg_session_title_all_messages_llm --> pkg_invariants
-  pkg_session_title_all_messages_llm --> pkg_llm
-  pkg_session_title_all_messages_llm --> pkg_session
-  pkg_session_title_all_messages_llm --> pkg_session_title
-  pkg_session_title_all_messages_llm --> pkg_session_title_llm
-  pkg_session_title_first_message_llm --> pkg_invariants
-  pkg_session_title_first_message_llm --> pkg_llm
-  pkg_session_title_first_message_llm --> pkg_session
-  pkg_session_title_first_message_llm --> pkg_session_title
-  pkg_session_title_first_message_llm --> pkg_session_title_llm
   pkg_agent_loop_testkit --> pkg_agent
   pkg_agent_loop_testkit --> pkg_invariants
   pkg_agent_loop_testkit --> pkg_llm
   pkg_agent_loop_testkit --> pkg_session
   pkg_agent_loop_testkit --> pkg_system_prompt
   pkg_agent_loop_testkit --> pkg_tools
-  pkg_tool_ask_user --> pkg_agent
-  pkg_tool_ask_user --> pkg_invariants
-  pkg_tool_ask_user --> pkg_tools
-  pkg_tool_ask_user --> pkg_user_interaction
   pkg_client_ui_command --> pkg_client_connection
   pkg_client_ui_command --> pkg_client_locale
   pkg_client_ui_command --> pkg_client_runtime
@@ -929,6 +896,14 @@ flowchart TD
   pkg_repeat_tool_guard --> pkg_agent
   pkg_repeat_tool_guard --> pkg_invariants
   pkg_repeat_tool_guard --> pkg_tools
+  pkg_timeout_policy --> pkg_invariants
+  pkg_timeout_policy --> pkg_llm
+  pkg_timeout_policy --> pkg_timeout
+  pkg_timeout_policy --> pkg_tools
+  pkg_tool_ask_user --> pkg_agent
+  pkg_tool_ask_user --> pkg_invariants
+  pkg_tool_ask_user --> pkg_tools
+  pkg_tool_ask_user --> pkg_user_interaction
   pkg_tool_lsp --> pkg_invariants
   pkg_tool_lsp --> pkg_llm
   pkg_tool_lsp --> pkg_lsp
@@ -952,13 +927,15 @@ flowchart TD
   pkg_tool_pty --> pkg_system_prompt
   pkg_tool_pty --> pkg_tasks
   pkg_tool_pty --> pkg_tools
-  pkg_tool_tasks --> pkg_agent
-  pkg_tool_tasks --> pkg_invariants
-  pkg_tool_tasks --> pkg_llm
-  pkg_tool_tasks --> pkg_retention
-  pkg_tool_tasks --> pkg_system_prompt
-  pkg_tool_tasks --> pkg_tasks
-  pkg_tool_tasks --> pkg_tools
+  pkg_tool_cordis --> pkg_invariants
+  pkg_tool_cordis --> pkg_scope
+  pkg_tool_cordis --> pkg_tools
+  pkg_session_checkpoint_policy --> pkg_agent
+  pkg_session_checkpoint_policy --> pkg_invariants
+  pkg_session_checkpoint_policy --> pkg_llm
+  pkg_session_checkpoint_policy --> pkg_session
+  pkg_session_checkpoint_policy --> pkg_session_persistence
+  pkg_session_checkpoint_policy --> pkg_tools
   pkg_session_telemetry_otel --> pkg_brand
   pkg_session_telemetry_otel --> pkg_command_feedback
   pkg_session_telemetry_otel --> pkg_invariants
@@ -966,6 +943,23 @@ flowchart TD
   pkg_session_telemetry_otel --> pkg_paths
   pkg_session_telemetry_otel --> pkg_session
   pkg_session_telemetry_otel --> pkg_session_telemetry
+  pkg_session_title_all_messages_llm --> pkg_invariants
+  pkg_session_title_all_messages_llm --> pkg_llm
+  pkg_session_title_all_messages_llm --> pkg_session
+  pkg_session_title_all_messages_llm --> pkg_session_title
+  pkg_session_title_all_messages_llm --> pkg_session_title_llm
+  pkg_session_title_first_message_llm --> pkg_invariants
+  pkg_session_title_first_message_llm --> pkg_llm
+  pkg_session_title_first_message_llm --> pkg_session
+  pkg_session_title_first_message_llm --> pkg_session_title
+  pkg_session_title_first_message_llm --> pkg_session_title_llm
+  pkg_tool_tasks --> pkg_agent
+  pkg_tool_tasks --> pkg_invariants
+  pkg_tool_tasks --> pkg_llm
+  pkg_tool_tasks --> pkg_retention
+  pkg_tool_tasks --> pkg_system_prompt
+  pkg_tool_tasks --> pkg_tasks
+  pkg_tool_tasks --> pkg_tools
   pkg_tool_workflow --> pkg_agent
   pkg_tool_workflow --> pkg_invariants
   pkg_tool_workflow --> pkg_llm
@@ -1028,10 +1022,6 @@ flowchart TD
   pkg_tool_subagent_report --> pkg_llm
   pkg_tool_subagent_report --> pkg_subagent
   pkg_tool_subagent_report --> pkg_tools
-  pkg_repository_plugin --> pkg_invariants
-  pkg_repository_plugin --> pkg_mcp_client
-  pkg_repository_plugin --> pkg_paths
-  pkg_repository_plugin --> pkg_skill_local
   pkg_hooks_claude --> pkg_agent
   pkg_hooks_claude --> pkg_hook_protocol
   pkg_hooks_claude --> pkg_invariants
@@ -1091,6 +1081,10 @@ flowchart TD
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
   pkg_sdk_protocol --> pkg_subagent
+  pkg_repository_plugin --> pkg_invariants
+  pkg_repository_plugin --> pkg_mcp_client
+  pkg_repository_plugin --> pkg_paths
+  pkg_repository_plugin --> pkg_skill_local
   pkg_tool_ralph --> pkg_agent
   pkg_tool_ralph --> pkg_invariants
   pkg_tool_ralph --> pkg_llm
@@ -1121,14 +1115,6 @@ flowchart TD
   pkg_subagent_spawn --> pkg_invariants
   pkg_subagent_spawn --> pkg_subagent
   pkg_subagent_spawn --> pkg_subagent_inprocess
-  pkg_jsonrpc --> pkg_agent
-  pkg_jsonrpc --> pkg_invariants
-  pkg_jsonrpc --> pkg_llm
-  pkg_jsonrpc --> pkg_llm_deepseek
-  pkg_jsonrpc --> pkg_scope
-  pkg_jsonrpc --> pkg_sdk_protocol
-  pkg_jsonrpc --> pkg_session
-  pkg_jsonrpc --> pkg_subagent
   pkg_agent_spine_demo --> pkg_agent
   pkg_agent_spine_demo --> pkg_agent_loop
   pkg_agent_spine_demo --> pkg_bash_env
@@ -1151,6 +1137,14 @@ flowchart TD
   pkg_agent_spine_demo --> pkg_tool_tasks
   pkg_agent_spine_demo --> pkg_tools
   pkg_agent_spine_demo --> pkg_workspace_context
+  pkg_jsonrpc --> pkg_agent
+  pkg_jsonrpc --> pkg_invariants
+  pkg_jsonrpc --> pkg_llm
+  pkg_jsonrpc --> pkg_llm_deepseek
+  pkg_jsonrpc --> pkg_scope
+  pkg_jsonrpc --> pkg_sdk_protocol
+  pkg_jsonrpc --> pkg_session
+  pkg_jsonrpc --> pkg_subagent
   pkg_sdk_client --> pkg_invariants
   pkg_sdk_client --> pkg_llm
   pkg_sdk_client --> pkg_sdk_protocol
@@ -1211,8 +1205,8 @@ flowchart TD
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
-| [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
-| [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`helper`](../packages/scaffold/helper) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
+| [`telemetry`](../packages/scaffold/telemetry) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`settings`](../packages/settings/settings) | `settings` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
 | [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
@@ -1244,9 +1238,8 @@ flowchart TD
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`app-boot`](../packages/ui/app-boot) | `ui` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
+| [`app-boot`](../packages/boot/app-boot) | `boot` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |
 | [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
 | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
@@ -1255,10 +1248,11 @@ flowchart TD
 | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
-| [`session-projection`](../packages/session-projection/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
-| [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`type-meta`](../packages/typert/type-meta) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pwsh-local`](../packages/bash/pwsh-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
@@ -1267,14 +1261,8 @@ flowchart TD
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| [`session-title`](../packages/session-title/session-title) | `session-title` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`commands`](../packages/ui/commands) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
-| [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
-| [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
@@ -1282,55 +1270,55 @@ flowchart TD
 | [`fs-e2b`](../packages/e2b/fs-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
 | [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`commands`](../packages/interaction/commands) | `interaction` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
+| [`user-approval`](../packages/interaction/user-approval) | `interaction` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
+| [`user-interaction`](../packages/interaction/user-interaction) | `interaction` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
 | [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
-| [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants) |
-| [`session-projection-cache`](../packages/session-projection/session-projection-cache) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
+| [`scripts`](../packages/scaffold/scripts) | `scaffold` | [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants) |
+| [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
+| [`session-telemetry`](../packages/session/session-telemetry) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`session-title`](../packages/session/session-title) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`session-telemetry`](../packages/telemetry/session-telemetry) | `telemetry` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`workspace`](../packages/workspace/workspace) | `workspace` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`storage`](../packages/storage/storage), [`storage-domain`](../packages/storage/storage-domain) |
-| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/ui/user-approval) |
-| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/ui/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`workspace`](../packages/workspace/workspace) | `workspace` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage`](../packages/storage/storage), [`storage-domain`](../packages/storage/storage-domain) |
+| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval) |
+| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
 | [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
 | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
-| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
+| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
 | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title) |
-| [`session-title-llm`](../packages/session-title/session-title-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`timeout`](../packages/util/timeout) |
-| [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
-| [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/ui/user-approval) |
-| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`typert-registry`](../packages/typert/registry) |
+| [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
+| [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
+| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
-| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`permission`](../packages/interaction/permission) | `interaction` | [`bash`](../packages/bash/bash), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
+| [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
-| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
-| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
 | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
 | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
-| [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
-| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`tools`](../packages/core/tools) |
-| [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session-projection/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
-| [`tool-cordis`](../packages/cordis/tool-cordis) | `cordis` | [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
-| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
-| [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy) | `session-persistence` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
-| [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query) |
+| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
+| [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-interaction`](../packages/interaction/user-interaction) |
+| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
 | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
-| [`session-title-all-messages-llm`](../packages/session-title/session-title-all-messages-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`session-title-llm`](../packages/session-title/session-title-llm) |
-| [`session-title-first-message-llm`](../packages/session-title/session-title-first-message-llm) | `session-title` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`session-title-llm`](../packages/session-title/session-title-llm) |
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
 | [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
@@ -1338,37 +1326,43 @@ flowchart TD
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
+| [`timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-ask-user`](../packages/interaction/tool-ask-user) | `interaction` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/interaction/user-interaction) |
 | [`tool-lsp`](../packages/lsp/tool-lsp) | `lsp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools) |
 | [`tool-bash-persistent`](../packages/pty/tool-bash-persistent) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-pty`](../packages/pty/tool-pty) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`pty`](../packages/pty/pty), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`tool-cordis`](../packages/self-modification/tool-cordis) | `self-modification` | [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
+| [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
+| [`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
+| [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
 | [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
-| [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | `telemetry` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
-| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
-| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`repository-plugin`](../packages/cordis/repository-plugin) | `cordis` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
-| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
 | [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/ui/permission) |
+| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
 | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
 | [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
 | [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
-| [`sdk-protocol`](../packages/sdk/sdk-protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`repository-plugin`](../packages/self-modification/repository-plugin) | `self-modification` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
-| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
-| [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
-| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
-| [`sdk-client`](../packages/sdk/sdk-client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session) |
-| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/sdk-client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
-| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`jsonrpc`](../packages/scaffold/server) | `scaffold` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`sdk-client`](../packages/scaffold/client) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
+| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index daf2ea7ab2..b238e56399 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -125,7 +125,7 @@ Source: [`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/type
 
 Types: [CallId](core-data-structures/core.md)
 
-Source: [`packages/ui/user-approval/src/index.ts:44`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:44`](../packages/interaction/user-approval/src/index.ts)
 
 #### `approval/decided` — log-only
 
@@ -141,7 +141,7 @@ Source: [`packages/ui/user-approval/src/index.ts:44`](../packages/ui/user-approv
 }
 ```
 
-Source: [`packages/ui/user-approval/src/index.ts:55`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:55`](../packages/interaction/user-approval/src/index.ts)
 
 #### `approval/policy` — log-only
 
@@ -161,7 +161,7 @@ Source: [`packages/ui/user-approval/src/index.ts:55`](../packages/ui/user-approv
 }
 ```
 
-Source: [`packages/ui/user-approval/src/index.ts:67`](../packages/ui/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:67`](../packages/interaction/user-approval/src/index.ts)
 
 ### `assistant/*`
 
@@ -211,7 +211,7 @@ Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/
 }
 ```
 
-Source: [`packages/ui/commands/src/index.ts:151`](../packages/ui/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:151`](../packages/interaction/commands/src/index.ts)
 
 #### `command/run` — log-only
 
@@ -229,7 +229,7 @@ Source: [`packages/ui/commands/src/index.ts:151`](../packages/ui/commands/src/in
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-Source: [`packages/ui/commands/src/index.ts:144`](../packages/ui/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:144`](../packages/interaction/commands/src/index.ts)
 
 ### `compact/*`
 
@@ -449,7 +449,7 @@ Source: [`packages/llm/llm-retry/src/index.ts:17`](../packages/llm/llm-retry/src
 'permission/preset': { preset: string }
 ```
 
-Source: [`packages/ui/permission/src/index.ts:50`](../packages/ui/permission/src/index.ts)
+Source: [`packages/interaction/permission/src/index.ts:50`](../packages/interaction/permission/src/index.ts)
 
 ### `plan/*`
 
diff --git a/examples/web-cordis/README.i18n.yaml b/examples/web-cordis/README.i18n.yaml
index 0564a4e0fc..86cc276a4e 100644
--- a/examples/web-cordis/README.i18n.yaml
+++ b/examples/web-cordis/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 examples/web-cordis/README.md
-README.md: 75c7610fecc20777607c7c8cbb6ed2fc7f590b73
-README.zh.md: 5c25347ee17037bbfc7d10a5507424ce52e3faff
+README.md: 21fe0a210b2e591a96dc254014a0f91ed9afa2ba
+README.zh.md: 35158affd5cbdd6f8fa7f5910500f21c2b241309
diff --git a/examples/web-cordis/README.md b/examples/web-cordis/README.md
index 75c7610fec..21fe0a210b 100644
--- a/examples/web-cordis/README.md
+++ b/examples/web-cordis/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Self-referential demonstration of [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md). The agent can inspect its current Cordis process and mount or unmount model-authored plugins in memory. Temporary plugins disappear when they are unmounted or the process exits and may affect other sessions in the same process.
+Self-referential demonstration of [`@deepseek-ai/dsh-tool-cordis`](../../packages/self-modification/tool-cordis/README.md). The agent can inspect its current Cordis process and mount or unmount model-authored plugins in memory. Temporary plugins disappear when they are unmounted or the process exits and may affect other sessions in the same process.
 
 ## Run it
 
@@ -18,4 +18,4 @@ Start the ACP automation server instead:
 pnpm run demo:cordis acp
 ```
 
-Both commands require `DEEPSEEK_API_KEY`. The [Cordis tool reference](../../packages/cordis/tool-cordis/README.md) owns the tool, lifecycle, and safety contracts.
+Both commands require `DEEPSEEK_API_KEY`. The [Cordis tool reference](../../packages/self-modification/tool-cordis/README.md) owns the tool, lifecycle, and safety contracts.
diff --git a/examples/web-cordis/README.zh.md b/examples/web-cordis/README.zh.md
index 5c25347ee1..35158affd5 100644
--- a/examples/web-cordis/README.zh.md
+++ b/examples/web-cordis/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md) 的自指示例。agent（智能体）可以检查当前 Cordis 进程，并在内存中挂载或卸载模型编写的插件。临时插件会在卸载或进程退出时消失，并可能影响同一进程中的其他会话。
+[`@deepseek-ai/dsh-tool-cordis`](../../packages/self-modification/tool-cordis/README.md) 的自指示例。agent（智能体）可以检查当前 Cordis 进程，并在内存中挂载或卸载模型编写的插件。临时插件会在卸载或进程退出时消失，并可能影响同一进程中的其他会话。
 
 ## 运行
 
@@ -18,4 +18,4 @@ pnpm run demo:cordis
 pnpm run demo:cordis acp
 ```
 
-这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全契约由 [Cordis 工具参考](../../packages/cordis/tool-cordis/README.md)定义。
+这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全契约由 [Cordis 工具参考](../../packages/self-modification/tool-cordis/README.md)定义。
diff --git a/packages/api/remotes/tsconfig.host.json b/packages/api/remotes/tsconfig.host.json
index 1d4c35a9e2..1082a0d94b 100644
--- a/packages/api/remotes/tsconfig.host.json
+++ b/packages/api/remotes/tsconfig.host.json
@@ -21,7 +21,7 @@
       "path": "../../core/session"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/bash/bash-env/tsconfig.json b/packages/bash/bash-env/tsconfig.json
index bcf5eb5229..d48ddfc73b 100644
--- a/packages/bash/bash-env/tsconfig.json
+++ b/packages/bash/bash-env/tsconfig.json
@@ -27,7 +27,7 @@
       "path": "../../core/tools"
     },
     {
-      "path": "../../session-persistence/session-persistence"
+      "path": "../../session/session-persistence"
     },
     {
       "path": "../../support/invariants"
diff --git a/packages/bundle/README.i18n.yaml b/packages/bundle/README.i18n.yaml
index 5199e0939e..98df59d988 100644
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/README.i18n.yaml
@@ -1,12 +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:
-<<<<<<<< HEAD:packages/bundle/README.i18n.yaml
 #   pnpm run verify-translation-pairing --write packages/bundle/README.md
-README.md: 4759170435a80e85731446cef21d24fff2abed66
-README.zh.md: 1ef610a1b7b3c591c9a900e04f2d8096b0b086b9
-========
-#   pnpm run verify-translation-pairing --write packages/interaction/tui/README.md
-README.md: c81cac891403e5294c4456ce4d4048ecd74666ce
-README.zh.md: 01055619f4df460284564f0a1816de366d809e01
->>>>>>>> a58746f4cc (refactor(packages): dissolve ui/ and rename sdk/ to scaffold/):packages/interaction/tui/README.i18n.yaml
+README.md: af06fe921a66378894a4ab0174ef403499f5f68c
+README.zh.md: ef2027e347b79e14574ba1164aa9fddd364327e9
diff --git a/packages/bundle/README.md b/packages/bundle/README.md
index 4759170435..af06fe921a 100644
--- a/packages/bundle/README.md
+++ b/packages/bundle/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Profile bundles: npm packages whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`, making them installable patch layers for `dsh --profile` compositions ([profile contract](../ui/app-boot/README.md#profiles)). A bundle's substance is its patch list; some also ship runtime glue plugins their patch mounts.
+Profile bundles: npm packages whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`, making them installable patch layers for `dsh --profile` compositions ([profile contract](../boot/app-boot/README.md#profiles)). A bundle's substance is its patch list; some also ship runtime glue plugins their patch mounts.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/bundle/README.zh.md b/packages/bundle/README.zh.md
index 1ef610a1b7..ef2027e347 100644
--- a/packages/bundle/README.zh.md
+++ b/packages/bundle/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 契约](../ui/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
+Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 契约](../boot/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/compact/command-compact/README.i18n.yaml b/packages/compact/command-compact/README.i18n.yaml
index 35ebe66e2b..68dfebd1b9 100644
--- a/packages/compact/command-compact/README.i18n.yaml
+++ b/packages/compact/command-compact/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/compact/command-compact/README.md
-README.md: 54f341e39447a423964b7d7435cfb638857eda6e
-README.zh.md: d4a122b8a19cdf907212ad019b2528ae52d03886
+README.md: 5af39e82928d64c11474199b6b30058e9d289f45
+README.zh.md: a582bd5272b2e39ac1ffbf839888a4006b6d44bc
diff --git a/packages/compact/command-compact/README.md b/packages/compact/command-compact/README.md
index 54f341e394..5af39e8292 100644
--- a/packages/compact/command-compact/README.md
+++ b/packages/compact/command-compact/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Human-facing `/compact` control over [`ctx.compact`](../compact/README.md). The plugin registers one global command through [`ctx.commands`](../../ui/commands/README.md), so every composed command adapter discovers and executes it without a model turn. The [queued manual compaction Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md) owns the admission, lock, and durability decisions.
+Human-facing `/compact` control over [`ctx.compact`](../compact/README.md). The plugin registers one global command through [`ctx.commands`](../../interaction/commands/README.md), so every composed command adapter discovers and executes it without a model turn. The [queued manual compaction Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md) owns the admission, lock, and durability decisions.
 
 ## Command contract
 
diff --git a/packages/compact/command-compact/README.zh.md b/packages/compact/command-compact/README.zh.md
index d4a122b8a1..a582bd5272 100644
--- a/packages/compact/command-compact/README.zh.md
+++ b/packages/compact/command-compact/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-通过 [`ctx.compact`](../compact/README.md) 提供面向用户的 `/compact` 压缩（compaction）控制。该插件通过 [`ctx.commands`](../../ui/commands/README.md) 注册一个全局命令，因此组合中的每个命令适配器都能发现并执行它，无需模型轮次。[排队手动压缩 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md)拥有接纳、锁与持久性决策。
+通过 [`ctx.compact`](../compact/README.md) 提供面向用户的 `/compact` 压缩（compaction）控制。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此组合中的每个命令适配器都能发现并执行它，无需模型轮次。[排队手动压缩 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md)拥有接纳、锁与持久性决策。
 
 ## 命令契约
 
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index 07a3efd5c3..182ac31809 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-local/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/credentials/credentials-local/README.md
-README.md: 8e95a890a8e38172cf8984653a01c59570f0061a
-README.zh.md: 04ad07ae4e703ab0416d1d8f1bb6a6ff90adf337
+README.md: 6051c07628c0214f9396d12554719c5614610826
+README.zh.md: c6f3901af925d4bd31d2dcfbf5f5f65de62dac81
diff --git a/packages/credentials/credentials-local/README.md b/packages/credentials/credentials-local/README.md
index 8e95a890a8..6051c07628 100644
--- a/packages/credentials/credentials-local/README.md
+++ b/packages/credentials/credentials-local/README.md
@@ -51,7 +51,7 @@ External edits publish `credentials/updated` per changed reference after the sna
 
 ## Security boundary
 
-The document is `0600` under a `0700` directory, which stops other OS users — **not** the model. Tool processes (bash, the filesystem tools) run as the same user, and the shipped `workspace-write` file policy confines mutations rather than reads, so they can read this file exactly like any other file the user owns; no sandbox mode singles it out. What the harness does hold to is narrower: it never hands the model a resolved path to the document, and never loads it into the process environment — unlike `$DSH_HOME/.env`, which is the user's ordinary environment layer (see [app-boot's Harness-home layers](../../ui/app-boot/README.md#profiles)) — so reaching the value takes a deliberate read of a path the agent was not given.
+The document is `0600` under a `0700` directory, which stops other OS users — **not** the model. Tool processes (bash, the filesystem tools) run as the same user, and the shipped `workspace-write` file policy confines mutations rather than reads, so they can read this file exactly like any other file the user owns; no sandbox mode singles it out. What the harness does hold to is narrower: it never hands the model a resolved path to the document, and never loads it into the process environment — unlike `$DSH_HOME/.env`, which is the user's ordinary environment layer (see [app-boot's Harness-home layers](../../boot/app-boot/README.md#profiles)) — so reaching the value takes a deliberate read of a path the agent was not given.
 
 That is discretion, not a boundary. A deployment that must keep provider keys away from its own agent cannot get there with file permissions; an OS-keychain provider — a store the model's processes cannot read at all — is the deferred answer and belongs beside this provider as a sibling package.
 
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index 04ad07ae4e..c6f3901af9 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -51,7 +51,7 @@ OPENAI_API_KEY: sk-…
 
 ## 安全边界
 
-文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的 Harness home 各层](../../ui/app-boot/README.md#profiles)）——因此要拿到这个值，需要刻意去读一条并未交给 agent（智能体）的路径。
+文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的 Harness home 各层](../../boot/app-boot/README.md#profiles)）——因此要拿到这个值，需要刻意去读一条并未交给 agent（智能体）的路径。
 
 这是审慎，不是边界。必须让提供方密钥远离自身 agent 的部署无法靠文件权限做到；OS 钥匙串提供方——一个模型的进程根本读不到的存储——才是延后的答案，它应当作为平级包与本提供方并列。
 
diff --git a/packages/examples/jsonrpc-demo/README.i18n.yaml b/packages/examples/jsonrpc-demo/README.i18n.yaml
index 4e7935dd3a..c47938ce3b 100644
--- a/packages/examples/jsonrpc-demo/README.i18n.yaml
+++ b/packages/examples/jsonrpc-demo/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/examples/jsonrpc-demo/README.md
-README.md: 2cc496da3e22baf9e87afe4c3ca183ae3f16a5ae
-README.zh.md: 98d397b3c346ee47e9a667b2ccec0179f009a05b
+README.md: fff8e78698cd3d6320606084ef5c533be7c52633
+README.zh.md: 75382b97ea1837cf1415e8a7f5004206596e168c
diff --git a/packages/examples/jsonrpc-demo/README.md b/packages/examples/jsonrpc-demo/README.md
index 2cc496da3e..fff8e78698 100644
--- a/packages/examples/jsonrpc-demo/README.md
+++ b/packages/examples/jsonrpc-demo/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../ui/jsonrpc/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. The published bin is `dsh-jsonrpc-agent`, and `lib/bin.js` also ships as the `dsh-jsonrpc-agent-pkg` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) used by the Python SDK.
+Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../scaffold/server/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. The published bin is `dsh-jsonrpc-agent`, and `lib/bin.js` also ships as the `dsh-jsonrpc-agent-pkg` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) used by the Python SDK.
 
 ## Config discovery
 
-The first non-empty channel wins: `$DSH_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the bin prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`dsh-app-boot`](../../ui/app-boot/README.md) makes plugin load failures fatal. This protocol does not use `DSH_SNAPSHOT`.
+The first non-empty channel wins: `$DSH_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the bin prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`dsh-app-boot`](../../boot/app-boot/README.md) makes plugin load failures fatal. This protocol does not use `DSH_SNAPSHOT`.
 
 A config without `dsh-jsonrpc` is valid and serves nothing; the bin does not designate a server plugin.
 
diff --git a/packages/examples/jsonrpc-demo/README.zh.md b/packages/examples/jsonrpc-demo/README.zh.md
index 98d397b3c3..75382b97ea 100644
--- a/packages/examples/jsonrpc-demo/README.zh.md
+++ b/packages/examples/jsonrpc-demo/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../ui/jsonrpc/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)交付。
+只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)交付。
 
 ## 配置发现
 
-第一个非空通道生效：先 `$DSH_CORDIS_CONFIG`，再位置参数 `argv[2]`。如果二者都没有指向现有文件，bin 会向 stderr 打印单行用法并以 1 退出；没有工作目录回退或内置回退。[`dsh-app-boot`](../../ui/app-boot/README.md) 会使插件加载失败成为致命错误。此协议不使用 `DSH_SNAPSHOT`。
+第一个非空通道生效：先 `$DSH_CORDIS_CONFIG`，再位置参数 `argv[2]`。如果二者都没有指向现有文件，bin 会向 stderr 打印单行用法并以 1 退出；没有工作目录回退或内置回退。[`dsh-app-boot`](../../boot/app-boot/README.md) 会使插件加载失败成为致命错误。此协议不使用 `DSH_SNAPSHOT`。
 
 不含 `dsh-jsonrpc` 的配置仍然有效，只是不提供任何服务；bin 不会指定服务器插件。
 
diff --git a/packages/feedback/README.i18n.yaml b/packages/feedback/README.i18n.yaml
index 4ad5a93fb5..d0fe492135 100644
--- a/packages/feedback/README.i18n.yaml
+++ b/packages/feedback/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/feedback/README.md
-README.md: d2a4a5a27e1c661d2f62b328578fd890a0c622ee
-README.zh.md: 2fa42e3bb5f05dfc425356f302f44e497b100f24
+README.md: af8e9d5c4903594299284d09f880aa8929f5e051
+README.zh.md: 01a26798d0b7dc8b376929252a60a99fff11b640
diff --git a/packages/feedback/README.md b/packages/feedback/README.md
index d2a4a5a27e..af8e9d5c49 100644
--- a/packages/feedback/README.md
+++ b/packages/feedback/README.md
@@ -8,4 +8,4 @@ The feedback family lets a human record a remark about the session without actin
 |---|---|---|
 | `command-feedback/` | Trigger-independent `feedback/record` event plus the human-facing `/feedback` producer | — |
 
-A recorded remark is log-only: it never enters the model surface or derived history. When mounted, [`dsh-session-telemetry-otel`](../telemetry/session-telemetry-otel/) observes `feedback/record` to release a pending telemetry prefix or warn that disabled telemetry leaves the feedback local; capture itself remains independent of that policy.
+A recorded remark is log-only: it never enters the model surface or derived history. When mounted, [`dsh-session-telemetry-otel`](../session/session-telemetry-otel) observes `feedback/record` to release a pending telemetry prefix or warn that disabled telemetry leaves the feedback local; capture itself remains independent of that policy.
diff --git a/packages/feedback/README.zh.md b/packages/feedback/README.zh.md
index 2fa42e3bb5..01a26798d0 100644
--- a/packages/feedback/README.zh.md
+++ b/packages/feedback/README.zh.md
@@ -8,4 +8,4 @@ feedback 家族让人类记录对会话的评价，但不据此采取任何动
 |---|---|---|
 | `command-feedback/` | 与触发方式无关的 `feedback/record` 事件，以及面向用户的 `/feedback` 生产方 | 无 |
 
-被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史。挂载后，[`dsh-session-telemetry-otel`](../telemetry/session-telemetry-otel/) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
+被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史。挂载后，[`dsh-session-telemetry-otel`](../session/session-telemetry-otel) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
diff --git a/packages/feedback/command-feedback/README.i18n.yaml b/packages/feedback/command-feedback/README.i18n.yaml
index ad645a61d3..20eb2741d6 100644
--- a/packages/feedback/command-feedback/README.i18n.yaml
+++ b/packages/feedback/command-feedback/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/feedback/command-feedback/README.md
-README.md: 1923267eb3a25a4be564fa4f4535f7a3459ca481
-README.zh.md: 674665167030aa6214e9acaa7e6f5314a78c5b14
+README.md: e2eb6d4cf2b40e83efad1fa158edd72578658f56
+README.zh.md: f87067d67cf9dcb8f4da97afe3a9d59eb828faf7
diff --git a/packages/feedback/command-feedback/README.md b/packages/feedback/command-feedback/README.md
index 1923267eb3..e2eb6d4cf2 100644
--- a/packages/feedback/command-feedback/README.md
+++ b/packages/feedback/command-feedback/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Trigger-independent session feedback plus human-facing `/feedback` capture. The package exports `recordFeedback(session, text)`, which appends one log-only `feedback/record` event. Its plugin registers one global command through [`ctx.commands`](../../ui/commands/README.md), so every composed command adapter discovers it; the shipped Web client executes it without a model turn.
+Trigger-independent session feedback plus human-facing `/feedback` capture. The package exports `recordFeedback(session, text)`, which appends one log-only `feedback/record` event. Its plugin registers one global command through [`ctx.commands`](../../interaction/commands/README.md), so every composed command adapter discovers it; the shipped Web client executes it without a model turn.
 
 ## Command contract
 
@@ -15,9 +15,9 @@ Surrounding whitespace is discarded, but feedback is otherwise unparsed: no trun
 
 ## What this plugin does and does not do
 
-`recordFeedback(session, text)` is the command-independent write path. It rejects empty normalized text and appends `feedback/record { text }`; a different UI, hook, or host integration can call it without constructing a slash command. The `/feedback` handler uses that producer and starts no model work. The optional [`dsh-session-telemetry-otel`](../../telemetry/session-telemetry-otel/) consumer observes the event without changing its capture contract.
+`recordFeedback(session, text)` is the command-independent write path. It rejects empty normalized text and appends `feedback/record { text }`; a different UI, hook, or host integration can call it without constructing a slash command. The `/feedback` handler uses that producer and starts no model work. The optional [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) consumer observes the event without changing its capture contract.
 
-The feedback text appears in exactly one durable payload: `feedback/record`. [`dsh-commands`](../../ui/commands/README.md) still appends its generic `command/run` / `command/done` pairing, but this definition sets `recordInput: false`, so `command/run` omits `args`; the paired `command/done` carries only the outcome. All three events are log-only and absent from the ordered surface, `deriveMessages()`, and model requests. These appends start persistence's ordinary eager drain, but neither producer forces `session/flush`, so acknowledgement means the feedback is in the log, not that it has reached disk. Rejected empty input leaves only the command pairing settled as `kind: 'error'`, with no `feedback/record`.
+The feedback text appears in exactly one durable payload: `feedback/record`. [`dsh-commands`](../../interaction/commands/README.md) still appends its generic `command/run` / `command/done` pairing, but this definition sets `recordInput: false`, so `command/run` omits `args`; the paired `command/done` carries only the outcome. All three events are log-only and absent from the ordered surface, `deriveMessages()`, and model requests. These appends start persistence's ordinary eager drain, but neither producer forces `session/flush`, so acknowledgement means the feedback is in the log, not that it has reached disk. Rejected empty input leaves only the command pairing settled as `kind: 'error'`, with no `feedback/record`.
 
 The event is authoritative rather than the command record because feedback may arrive through a trigger other than `/feedback`. Keeping the payload out of `command/run` avoids two records carrying the same text.
 
diff --git a/packages/feedback/command-feedback/README.zh.md b/packages/feedback/command-feedback/README.zh.md
index 6746651670..f87067d67c 100644
--- a/packages/feedback/command-feedback/README.zh.md
+++ b/packages/feedback/command-feedback/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-与触发方式无关的会话反馈，以及面向用户的 `/feedback` 采集。本包导出 `recordFeedback(session, text)`，后者追加一个仅写入日志的 `feedback/record` 事件。该插件通过 [`ctx.commands`](../../ui/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附的 Web 客户端无需模型轮次即可执行。
+与触发方式无关的会话反馈，以及面向用户的 `/feedback` 采集。本包导出 `recordFeedback(session, text)`，后者追加一个仅写入日志的 `feedback/record` 事件。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附的 Web 客户端无需模型轮次即可执行。
 
 ## 命令契约
 
@@ -15,9 +15,9 @@
 
 ## 本插件做什么、不做什么
 
-`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../telemetry/session-telemetry-otel/) 消费方会观察该事件，但不改变它的采集契约。
+`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集契约。
 
-反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../ui/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
+反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../interaction/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
 
 权威记录是该事件，而不是命令记录，因为反馈可能来自 `/feedback` 之外的触发方式。让载荷不进入 `command/run`，可避免两条记录携带相同文本。
 
diff --git a/packages/feedback/command-feedback/tsconfig.json b/packages/feedback/command-feedback/tsconfig.json
index 0a99f13f01..f59431af9a 100644
--- a/packages/feedback/command-feedback/tsconfig.json
+++ b/packages/feedback/command-feedback/tsconfig.json
@@ -15,7 +15,7 @@
       "path": "../../../vendor/cordis"
     },
     {
-      "path": "../../ui/commands"
+      "path": "../../interaction/commands"
     },
     {
       "path": "../../core/session"
diff --git a/packages/goal/command-goal/README.i18n.yaml b/packages/goal/command-goal/README.i18n.yaml
index 6586a5eda8..8f238d7429 100644
--- a/packages/goal/command-goal/README.i18n.yaml
+++ b/packages/goal/command-goal/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/goal/command-goal/README.md
-README.md: a02803b3ef7f93f0c4910ec2be662cc7836d9048
-README.zh.md: 9c6d0cc6e7309a138e17f1a2d5ad6c5285913394
+README.md: 1ac1b8a0e2cb360708b1759ab5eb9ec3de597821
+README.zh.md: cc5f7ba9bd3c5e50d3b7ce204d8d8c400e4f0955
diff --git a/packages/goal/command-goal/README.md b/packages/goal/command-goal/README.md
index a02803b3ef..1ac1b8a0e2 100644
--- a/packages/goal/command-goal/README.md
+++ b/packages/goal/command-goal/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Human-facing `/goal` control over [`ctx.goals`](../goal/README.md). The plugin registers one global command through [`ctx.commands`](../../ui/commands/README.md), so every composed command adapter discovers and executes it without a model turn. The [human goal-command Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md) owns the UX and composition decisions.
+Human-facing `/goal` control over [`ctx.goals`](../goal/README.md). The plugin registers one global command through [`ctx.commands`](../../interaction/commands/README.md), so every composed command adapter discovers and executes it without a model turn. The [human goal-command Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md) owns the UX and composition decisions.
 
 ## Command contract
 
diff --git a/packages/goal/command-goal/README.zh.md b/packages/goal/command-goal/README.zh.md
index 9c6d0cc6e7..cc5f7ba9bd 100644
--- a/packages/goal/command-goal/README.zh.md
+++ b/packages/goal/command-goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../ui/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md)负责用户体验与组合决策。
+面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md)负责用户体验与组合决策。
 
 ## 命令契约
 
diff --git a/packages/guard/timeout-policy/src/index.ts b/packages/guard/timeout-policy/src/index.ts
index 1c18fa5e13..f554b1a93e 100644
--- a/packages/guard/timeout-policy/src/index.ts
+++ b/packages/guard/timeout-policy/src/index.ts
@@ -6,7 +6,7 @@
  * FIXME: settle the intended `@deepseek-ai/dsh-timeout-guard` rename before the
  * first tagged release — suggestion only, aligning the name with its `guard/`
  * home; decide at resolution time
- * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
  *
  * @module @deepseek-ai/dsh-timeout-policy
  */
diff --git a/packages/interaction/permission/README.i18n.yaml b/packages/interaction/permission/README.i18n.yaml
index 34533f9da4..c8e4b28311 100644
--- a/packages/interaction/permission/README.i18n.yaml
+++ b/packages/interaction/permission/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/interaction/permission/README.md
 README.md: 4f7f560bb81eaad3b6b95b2742432fa252682d5a
-README.zh.md: 79d0ce9c095d3426f3219f04d9cb7ec3b161a184
+README.zh.md: d45f89e243ce2d8f6bb08943fb7e776ced106b5a
diff --git a/packages/interaction/user-interaction/README.i18n.yaml b/packages/interaction/user-interaction/README.i18n.yaml
index feab1813a7..aafe594c7e 100644
--- a/packages/interaction/user-interaction/README.i18n.yaml
+++ b/packages/interaction/user-interaction/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/interaction/user-interaction/README.md
-README.md: d62e75d110b8be339c5f9449b0834320f695ac99
-README.zh.md: 55258e85e56df2375ed8f195fa0b3b731a9cb816
+README.md: cba015e782623b3a5adf018303823577a0b96774
+README.zh.md: a5f944850c5ac4e05da59e8478167eef91796610
diff --git a/packages/plan/plan-mode/README.i18n.yaml b/packages/plan/plan-mode/README.i18n.yaml
index b24d4b1954..86afdb6310 100644
--- a/packages/plan/plan-mode/README.i18n.yaml
+++ b/packages/plan/plan-mode/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/plan/plan-mode/README.md
-README.md: f2a78fe98b6a85ce91d727e95ddf62e6f77546b7
-README.zh.md: e1b5f111fd8f761fdd8f25558463c0cc327a14be
+README.md: 6c8ba23b76e83665d4f8dcb5ecb41689347f6423
+README.zh.md: b306d5562af21dd9a95bb68c9acfc3f40c52136f
diff --git a/packages/plan/plan-mode/README.md b/packages/plan/plan-mode/README.md
index f2a78fe98b..6c8ba23b76 100644
--- a/packages/plan/plan-mode/README.md
+++ b/packages/plan/plan-mode/README.md
@@ -22,7 +22,7 @@ The Web client consumes the plugin-owned `/plan` command; other front doors may
 
 ## Session projection
 
-When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)), this package registers the `plan` projection unit under an injected child. The unit folds two event kinds: a `command/run` record named `plan` with recorded `args` sets the wanted target (`off` → inactive, anything else → active), and `plan/mode` commits the logged state and clears it; every other event returns the same state reference. `view` derives `{ active, pending }`, where `pending` is true only while an outstanding selection differs from the logged state — a pure replay quantity, so host restarts, other tabs, and cold reads all recover it from the log alone (the `/plan` handler calls `set()` before any failing path, keeping the logged request and the run plane from forking). The key merges into `SessionProjectionMap` from `src/types.ts` (served to host consumers via `./types` and client aggregates via `./client`); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected.
+When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `plan` projection unit under an injected child. The unit folds two event kinds: a `command/run` record named `plan` with recorded `args` sets the wanted target (`off` → inactive, anything else → active), and `plan/mode` commits the logged state and clears it; every other event returns the same state reference. `view` derives `{ active, pending }`, where `pending` is true only while an outstanding selection differs from the logged state — a pure replay quantity, so host restarts, other tabs, and cold reads all recover it from the log alone (the `/plan` handler calls `set()` before any failing path, keeping the logged request and the run plane from forking). The key merges into `SessionProjectionMap` from `src/types.ts` (served to host consumers via `./types` and client aggregates via `./client`); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected.
 
 ## Configuration
 
diff --git a/packages/plan/plan-mode/README.zh.md b/packages/plan/plan-mode/README.zh.md
index e1b5f111fd..b306d5562a 100644
--- a/packages/plan/plan-mode/README.zh.md
+++ b/packages/plan/plan-mode/README.zh.md
@@ -22,7 +22,7 @@ Web 客户端使用该插件提供的 `/plan` 命令；其他入口可以直接
 
 ## 会话投影
 
-当组合挂载 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)）时，本包会在一个注入的子插件中注册 `plan` 投影单元。该单元折叠两类事件：名为 `plan` 且携带已记录 `args` 的 `command/run` 记录会设置目标状态（`off` → 未激活，其余 → 激活），`plan/mode` 会提交已记录状态并清除该目标；其他任何事件都返回同一个状态引用。`view` 推导 `{ active, pending }`，其中 `pending` 仅在尚未落实的选择与已记录状态不同时为 true。该值完全由日志回放得出，因此 host 重启、其他标签页和冷读都能仅凭日志恢复它。`/plan` 处理器会在任何可能失败的路径之前调用 `set()`，避免已写入日志的请求与运行面分叉。key 由 `src/types.ts` 通过声明合并加入 `SessionProjectionMap`：host 消费方经 `./types` 获取，client 聚合经 `./client` 获取。框架负责驱动该单元，载体通过历史尾页和 `session/projection` 推送帧提供其值。未挂载注册表的组合不受影响。
+当组合挂载 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)）时，本包会在一个注入的子插件中注册 `plan` 投影单元。该单元折叠两类事件：名为 `plan` 且携带已记录 `args` 的 `command/run` 记录会设置目标状态（`off` → 未激活，其余 → 激活），`plan/mode` 会提交已记录状态并清除该目标；其他任何事件都返回同一个状态引用。`view` 推导 `{ active, pending }`，其中 `pending` 仅在尚未落实的选择与已记录状态不同时为 true。该值完全由日志回放得出，因此 host 重启、其他标签页和冷读都能仅凭日志恢复它。`/plan` 处理器会在任何可能失败的路径之前调用 `set()`，避免已写入日志的请求与运行面分叉。key 由 `src/types.ts` 通过声明合并加入 `SessionProjectionMap`：host 消费方经 `./types` 获取，client 聚合经 `./client` 获取。框架负责驱动该单元，载体通过历史尾页和 `session/projection` 推送帧提供其值。未挂载注册表的组合不受影响。
 
 ## 配置
 
diff --git a/packages/scaffold/README.i18n.yaml b/packages/scaffold/README.i18n.yaml
index 1480a14b69..7ddc22328c 100644
--- a/packages/scaffold/README.i18n.yaml
+++ b/packages/scaffold/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/scaffold/README.md
-README.md: b166a351a53afe075ecb794fe2bf6f0702a435ae
-README.zh.md: 6e2a65ea554487f48563c16e1defa37ef1a5e043
+README.md: 19c2f28f48d1c2d8747b635c10d6781c29e02f15
+README.zh.md: ecad2592eb32a30444f9112571379939da6afeec
diff --git a/packages/scaffold/README.md b/packages/scaffold/README.md
index b166a351a5..19c2f28f48 100644
--- a/packages/scaffold/README.md
+++ b/packages/scaffold/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named without the legacy `sdk-` prefix; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md).
+This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named without the legacy `sdk-` prefix; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md).
 
 | Package | Role |
 |---|---|
diff --git a/packages/scaffold/README.zh.md b/packages/scaffold/README.zh.md
index 6e2a65ea55..ecad2592eb 100644
--- a/packages/scaffold/README.zh.md
+++ b/packages/scaffold/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名，不带遗留的 `sdk-` 前缀；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
+本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名，不带遗留的 `sdk-` 前缀；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
 
 | 包 | 职责 |
 |---|---|
diff --git a/packages/scaffold/client/README.i18n.yaml b/packages/scaffold/client/README.i18n.yaml
index 0a71141cd6..c08016649d 100644
--- a/packages/scaffold/client/README.i18n.yaml
+++ b/packages/scaffold/client/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/scaffold/client/README.md
-README.md: f27ec256330254156c45b136c21308529ea99e3d
-README.zh.md: bd23762500a4da469839da8ddb50455e3419b553
+README.md: b33457875f81d11d09bab2e5aa5ce730e233c78a
+README.zh.md: 271f07ffb0f97abe005971962beb517acfdc05a4
diff --git a/packages/scaffold/client/README.md b/packages/scaffold/client/README.md
index f27ec25633..b33457875f 100644
--- a/packages/scaffold/client/README.md
+++ b/packages/scaffold/client/README.md
@@ -44,6 +44,6 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **No bundled-runtime resolution** — callers name the runtime executable explicitly; packaged-executable discovery stays Python-side until a TypeScript distribution consumer exists.
-- **No mid-turn cancel** — the wire has no prompt-cancel method; abandoning a turn means closing the runtime (see the protocol's [Known Limitations](../sdk-protocol/README.md)).
+- **No mid-turn cancel** — the wire has no prompt-cancel method; abandoning a turn means closing the runtime (see the protocol's [Known Limitations](../protocol/README.md)).
 - **No per-prompt result or cancel** — low-level `prompt()` returns only an enqueue receipt; high-level `run()` owns receipt-to-idle collection, and abandoning it means closing the runtime.
 - **Client→server notifications and server→client requests are unimplemented** on both wire ends; the transport carries them for future approval flows.
diff --git a/packages/scaffold/client/README.zh.md b/packages/scaffold/client/README.zh.md
index bd23762500..271f07ffb0 100644
--- a/packages/scaffold/client/README.zh.md
+++ b/packages/scaffold/client/README.zh.md
@@ -44,6 +44,6 @@ console.log(result.finalResponse)
 ## 已知限制与暂缓事项
 
 - **无捆绑运行时解析**——调用方显式指定运行时可执行文件；打包可执行文件的发现留在 Python 侧，直到出现 TypeScript 发行版消费方。
-- **无轮次中取消**——协议层没有提示词取消方法；放弃轮次意味着关闭运行时（见协议的 [已知限制](../sdk-protocol/README.md)）。
+- **无轮次中取消**——协议层没有提示词取消方法；放弃轮次意味着关闭运行时（见协议的 [已知限制](../protocol/README.md)）。
 - **没有逐提示词结果或取消**——低层 `prompt()` 只返回入队回执；高层 `run()` 负责从回执收集到 idle，放弃该过程意味着关闭运行时。
 - **客户端→服务端通知与服务端→客户端请求**在协议两端都未实现；传输层为未来审批流保留了承载能力。
diff --git a/packages/scaffold/helper/src/index.ts b/packages/scaffold/helper/src/index.ts
index 8c8e0db4b9..db4468aae5 100644
--- a/packages/scaffold/helper/src/index.ts
+++ b/packages/scaffold/helper/src/index.ts
@@ -3,7 +3,7 @@
  *
  * FIXME: rename to `@deepseek-ai/dsh-sdk-helper` before the first tagged release —
  * the current name is indefensibly generic as a published name
- * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
  *
  * @module @deepseek-ai/dsh-helper
  */
diff --git a/packages/scaffold/protocol/README.i18n.yaml b/packages/scaffold/protocol/README.i18n.yaml
index b77c8fce63..719a135b37 100644
--- a/packages/scaffold/protocol/README.i18n.yaml
+++ b/packages/scaffold/protocol/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/scaffold/protocol/README.md
-README.md: 35b62d2ffc43c54dc81f6a5ecfb1a0ef4294439d
-README.zh.md: a02ba94e7d8fae19bff48d8fda363e23fc173850
+README.md: 88a48957d0d44cec9f776d31eab7d25bd353de5f
+README.zh.md: c662d28ec6eea5fe4829030daf210a91fd70ff0f
diff --git a/packages/scaffold/protocol/README.md b/packages/scaffold/protocol/README.md
index b8420eb19a..88a48957d0 100644
--- a/packages/scaffold/protocol/README.md
+++ b/packages/scaffold/protocol/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delimited JSON-RPC 2.0 transport class plus the named request, result, and notification types both wire ends speak. The package root enumerates the protocol consumer interface; source modules are not exported as deep imports. The server side is the [`dsh-jsonrpc`](../../scaffold/server/README.md) plugin; clients are [`dsh-sdk-client`](../client/README.md) (TypeScript) and the [Python SDK](../../../python/README.md) (which mirrors these shapes but does not import them). A pure library — no plugin, no Config, no registration.
+The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delimited JSON-RPC 2.0 transport class plus the named request, result, and notification types both wire ends speak. The package root enumerates the protocol consumer interface; source modules are not exported as deep imports. The server side is the [`dsh-jsonrpc`](../server/README.md) plugin; clients are [`dsh-sdk-client`](../client/README.md) (TypeScript) and the [Python SDK](../../../python/README.md) (which mirrors these shapes but does not import them). A pure library — no plugin, no Config, no registration.
 
 ## Transport
 
@@ -26,7 +26,7 @@ The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delim
 
 ## Model Experience
 
-None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving [`dsh-jsonrpc`](../../scaffold/server/README.md) entry.
+None, as this package defines the client-facing wire protocol; the model-visible surfaces belong to the runtime plugins composed behind the serving [`dsh-jsonrpc`](../server/README.md) entry.
 
 #### KV Cache effect
 
@@ -35,5 +35,5 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **No protocol-version negotiation** — the handshake carries only `serverInfo.version` (`0.0.1`, unvalidated by clients); pre-release stance, no compatibility promise.
-- **No cancel or session-close methods** — a client abandons a turn by closing the runtime process; see the [`dsh-jsonrpc` README](../../scaffold/server/README.md).
+- **No cancel or session-close methods** — a client abandons a turn by closing the runtime process; see the [`dsh-jsonrpc` README](../server/README.md).
 - **Server→client requests are dead capability** — the transport supports them, but the server never sends one; the Python SDK's responder surface exists for future approval flows.
diff --git a/packages/scaffold/protocol/README.zh.md b/packages/scaffold/protocol/README.zh.md
index bc459f8817..c662d28ec6 100644
--- a/packages/scaffold/protocol/README.zh.md
+++ b/packages/scaffold/protocol/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按换行分帧的 JSON-RPC 2.0 传输类，加上协议两端共同使用的具名请求、结果与通知类型。包根枚举协议消费方接口；源模块不支持深层导入。服务端是 [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) 插件；客户端是 [`dsh-sdk-client`](../sdk-client/README.md)（TypeScript）与 [Python SDK](../../../python/README.md)（后者复现这些结构但不导入它们）。纯库——无插件、无 Config、无注册。
+DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按换行分帧的 JSON-RPC 2.0 传输类，加上协议两端共同使用的具名请求、结果与通知类型。包根枚举协议消费方接口；源模块不支持深层导入。服务端是 [`dsh-jsonrpc`](../server/README.md) 插件；客户端是 [`dsh-sdk-client`](../client/README.md)（TypeScript）与 [Python SDK](../../../python/README.md)（后者复现这些结构但不导入它们）。纯库——无插件、无 Config、无注册。
 
 ## 传输
 
@@ -26,7 +26,7 @@ DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按
 
 ## 模型体验
 
-无，因为此包定义面向客户端的协议格式；模型可见接口属于组合在对外服务入口 [`dsh-jsonrpc`](../../ui/jsonrpc/README.md) 后方的运行时插件。
+无，因为此包定义面向客户端的协议格式；模型可见接口属于组合在对外服务入口 [`dsh-jsonrpc`](../server/README.md) 后方的运行时插件。
 
 #### KV Cache 影响
 
@@ -35,5 +35,5 @@ DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按
 ## 已知限制与暂缓事项
 
 - **无协议版本协商**——握手只携带 `serverInfo.version`（`0.0.1`，客户端不校验）；处于预发布阶段，无兼容承诺。
-- **无取消与会话关闭方法**——客户端放弃轮次的方式是关闭运行时进程；见 [`dsh-jsonrpc` README](../../ui/jsonrpc/README.md)。
+- **无取消与会话关闭方法**——客户端放弃轮次的方式是关闭运行时进程；见 [`dsh-jsonrpc` README](../server/README.md)。
 - **server→client 请求是未使用的功能**——传输层支持，但服务器从不发送；Python SDK 的应答接口为未来审批流程预留。
diff --git a/packages/scaffold/scripts/src/index.ts b/packages/scaffold/scripts/src/index.ts
index 0af3ef0b30..0db62945f9 100644
--- a/packages/scaffold/scripts/src/index.ts
+++ b/packages/scaffold/scripts/src/index.ts
@@ -3,7 +3,7 @@
  *
  * FIXME: rename to `@deepseek-ai/dsh-sdk-scripts` before the first tagged release —
  * the current name is indefensibly generic as a published name
- * ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
  *
  * @module @deepseek-ai/dsh-scripts
  */
diff --git a/packages/scaffold/server/README.i18n.yaml b/packages/scaffold/server/README.i18n.yaml
index 46a18ec199..fc60d047d1 100644
--- a/packages/scaffold/server/README.i18n.yaml
+++ b/packages/scaffold/server/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/scaffold/server/README.md
-README.md: e0e06e27320ab41f131a1a36a7ccbd26271ce67c
-README.zh.md: ed87a869180571a3cbb51c2ce92a0647e545ca3a
+README.md: 0afb3a38ece57f74729a218dc85348fa6c7fa529
+README.zh.md: 5305434abbd83eb230dcdd81e72120d96da26cda
diff --git a/packages/scaffold/server/src/index.ts b/packages/scaffold/server/src/index.ts
index 9985cadfb4..f0261e1a21 100644
--- a/packages/scaffold/server/src/index.ts
+++ b/packages/scaffold/server/src/index.ts
@@ -8,7 +8,7 @@
  *
  * FIXME: rename to `@deepseek-ai/dsh-sdk-server` before the first tagged release —
  * the current name says the wire encoding, not the role; it is the server half of
- * the SDK protocol ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ * the SDK protocol ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
  *
  * @module @deepseek-ai/dsh-jsonrpc
  */
diff --git a/packages/scaffold/telemetry/src/index.ts b/packages/scaffold/telemetry/src/index.ts
index 17ea1d02c7..3c0a5beae7 100644
--- a/packages/scaffold/telemetry/src/index.ts
+++ b/packages/scaffold/telemetry/src/index.ts
@@ -9,7 +9,8 @@
  *
  * FIXME: rename to `@deepseek-ai/dsh-sdk-telemetry` before the first tagged release —
  * the current name collides with the `dsh-session-telemetry` family; this is
- * launcher-side SDK telemetry ([regrouping Agent Note](../../../../.agents/notes/proposed/architecture/2026-07-29-package-regrouping.md)).
+ * launcher-side SDK telemetry
+ * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
  *
  * @module @deepseek-ai/dsh-telemetry
  */
diff --git a/packages/subagent/subagent-codex/tsconfig.json b/packages/subagent/subagent-codex/tsconfig.json
index b9f33967ba..3bb974477e 100644
--- a/packages/subagent/subagent-codex/tsconfig.json
+++ b/packages/subagent/subagent-codex/tsconfig.json
@@ -24,7 +24,7 @@
       "path": "../../llm/llm"
     },
     {
-      "path": "../../sdk/sdk-protocol"
+      "path": "../../scaffold/protocol"
     },
     {
       "path": "../../core/session"
diff --git a/packages/subagent/subagent/tsconfig.json b/packages/subagent/subagent/tsconfig.json
index ccfecc02e4..c72f2ef68d 100644
--- a/packages/subagent/subagent/tsconfig.json
+++ b/packages/subagent/subagent/tsconfig.json
@@ -30,10 +30,10 @@
       "path": "../../session/session-persistence"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session/session-projection"
     },
     {
-      "path": "../../session-projection/session-projection-cache"
+      "path": "../../session/session-projection-cache"
     },
     {
       "path": "../../tasks/tasks"
diff --git a/packages/typert/generator/tests/type-model.spec.ts b/packages/typert/generator/tests/type-model.spec.ts
index e1b5d99de9..f8c41fb157 100644
--- a/packages/typert/generator/tests/type-model.spec.ts
+++ b/packages/typert/generator/tests/type-model.spec.ts
@@ -1264,14 +1264,14 @@ function configureDualRuntimeClient(root: string, splitProjects: boolean): void
   const hostAggregate = JSON.parse(readFileSync(hostAggregatePath, 'utf8')) as {
     references: { path: string }[]
   }
-  hostAggregate.references.push({ path: './packages/client/tsconfig.host.json' })
+  hostAggregate.references.push({ path: ['.', 'packages', 'client', 'tsconfig.host.json'].join('/') })
   writeFileSync(hostAggregatePath, `${JSON.stringify(hostAggregate, null, 2)}\n`)
 
   const clientAggregatePath = join(root, 'tsconfig.client.json')
   const clientAggregate = JSON.parse(readFileSync(clientAggregatePath, 'utf8')) as {
     references: { path: string }[]
   }
-  clientAggregate.references = [{ path: './packages/client/tsconfig.client.json' }]
+  clientAggregate.references = [{ path: ['.', 'packages', 'client', 'tsconfig.client.json'].join('/') }]
   writeFileSync(clientAggregatePath, `${JSON.stringify(clientAggregate, null, 2)}\n`)
 }
 
diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index 1c5f784bc4..633064ae4c 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/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/util/environment/README.md
-README.md: af6b0d9cc66b0bdfa1ad9ffb273260d0f4f06ddc
-README.zh.md: 98c3c69ec96f835721e042960fe044fe075e6159
+README.md: 599a9ba747905b66452b57717dabcc6f4678a3dd
+README.zh.md: 69f9c670bbb3ea1b2fbddaa7508a19dfb47fad12
diff --git a/packages/util/environment/README.md b/packages/util/environment/README.md
index af6b0d9cc6..599a9ba747 100644
--- a/packages/util/environment/README.md
+++ b/packages/util/environment/README.md
@@ -32,5 +32,5 @@ const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 
 ## Known Limitations and Deferred Work
 
-- **The snapshot is not a subprocess boundary** — every layer is also materialized into `process.env`, so ordinary project variables reach child processes under [`dsh-subprocess`](../../subprocess/subprocess/README.md)'s scrub. The product launcher's [`.env` contract](../../ui/app-boot/README.md#profiles) rejects bootstrap variables before materialization.
+- **The snapshot is not a subprocess boundary** — every layer is also materialized into `process.env`, so ordinary project variables reach child processes under [`dsh-subprocess`](../../subprocess/subprocess/README.md)'s scrub. The product launcher's [`.env` contract](../../boot/app-boot/README.md#profiles) rejects bootstrap variables before materialization.
 - **No per-workspace layer** — the project layer is the *invoking* directory, fixed at launch. A workspace selected later in the Web UI contributes nothing, deliberately: following it would let a model's own workspace change the harness environment mid-session.
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index 98c3c69ec9..69f9c670bb 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -32,5 +32,5 @@ const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 
 ## Known Limitations and Deferred Work
 
-- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 契约](../../ui/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
+- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 契约](../../boot/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
 - **没有按工作区划分的层**：项目层是*调用*目录，在启动时固定。之后在 Web UI 中选择的工作区不贡献任何内容，这是刻意的：跟随它等于让模型自己的工作区在会话中途改变 harness 的环境。
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a92883786a..e9726e9bee 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -142,7 +142,7 @@ importers:
         version: link:../../vendor/timer
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
-        version: link:../../packages/ui/app-boot
+        version: link:../../packages/boot/app-boot
       '@deepseek-ai/dsh-base':
         specifier: workspace:^
         version: link:../../packages/bundle/base
@@ -169,13 +169,13 @@ importers:
         version: link:../../packages/context/tmux-context
       '@deepseek-ai/dsh-tool-ask-user':
         specifier: workspace:^
-        version: link:../../packages/ui/tool-ask-user
+        version: link:../../packages/interaction/tool-ask-user
       '@deepseek-ai/dsh-tool-bash-persistent':
         specifier: workspace:^
         version: link:../../packages/pty/tool-bash-persistent
       '@deepseek-ai/dsh-tool-cordis':
         specifier: workspace:^
-        version: link:../../packages/cordis/tool-cordis
+        version: link:../../packages/self-modification/tool-cordis
       '@deepseek-ai/dsh-web-app':
         specifier: workspace:^
         version: link:../../packages/bundle/web-app
@@ -309,7 +309,7 @@ importers:
         version: link:../packages/examples/agent-spine-demo
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:*
-        version: link:../packages/ui/app-boot
+        version: link:../packages/boot/app-boot
       '@deepseek-ai/dsh-bash':
         specifier: workspace:*
         version: link:../packages/bash/bash
@@ -333,7 +333,7 @@ importers:
         version: link:../packages/goal/command-goal
       '@deepseek-ai/dsh-commands':
         specifier: workspace:*
-        version: link:../packages/ui/commands
+        version: link:../packages/interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:*
         version: link:../packages/compact/compact
@@ -378,7 +378,7 @@ importers:
         version: link:../packages/support/invariants
       '@deepseek-ai/dsh-jsonrpc':
         specifier: workspace:*
-        version: link:../packages/ui/jsonrpc
+        version: link:../packages/scaffold/server
       '@deepseek-ai/dsh-llm':
         specifier: workspace:*
         version: link:../packages/llm/llm
@@ -402,7 +402,7 @@ importers:
         version: link:../packages/lsp/lsp-local
       '@deepseek-ai/dsh-permission':
         specifier: workspace:*
-        version: link:../packages/ui/permission
+        version: link:../packages/interaction/permission
       '@deepseek-ai/dsh-plan-mode':
         specifier: workspace:*
         version: link:../packages/plan/plan-mode
@@ -420,7 +420,7 @@ importers:
         version: link:../packages/guard/repeat-tool-guard
       '@deepseek-ai/dsh-repository-plugin':
         specifier: workspace:*
-        version: link:../packages/cordis/repository-plugin
+        version: link:../packages/self-modification/repository-plugin
       '@deepseek-ai/dsh-sandbox':
         specifier: workspace:*
         version: link:../packages/sandbox/sandbox
@@ -438,13 +438,13 @@ importers:
         version: link:../packages/core/session
       '@deepseek-ai/dsh-session-checkpoint-policy':
         specifier: workspace:*
-        version: link:../packages/session-persistence/session-checkpoint-policy
+        version: link:../packages/session/session-checkpoint-policy
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:*
-        version: link:../packages/session-persistence/session-persistence-jsonl
+        version: link:../packages/session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:*
-        version: link:../packages/session-projection/session-projection
+        version: link:../packages/session/session-projection
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:*
         version: link:../packages/session-query/session-query
@@ -456,13 +456,13 @@ importers:
         version: link:../packages/context/session-reference
       '@deepseek-ai/dsh-session-telemetry-otel':
         specifier: workspace:*
-        version: link:../packages/telemetry/session-telemetry-otel
+        version: link:../packages/session/session-telemetry-otel
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:*
-        version: link:../packages/session-title/session-title
+        version: link:../packages/session/session-title
       '@deepseek-ai/dsh-session-title-first-message-llm':
         specifier: workspace:*
-        version: link:../packages/session-title/session-title-first-message-llm
+        version: link:../packages/session/session-title-first-message-llm
       '@deepseek-ai/dsh-settings-local':
         specifier: workspace:*
         version: link:../packages/settings/settings-local
@@ -516,13 +516,13 @@ importers:
         version: link:../packages/context/time-context
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:*
-        version: link:../packages/timeout/timeout-policy
+        version: link:../packages/guard/timeout-policy
       '@deepseek-ai/dsh-token-meter':
         specifier: workspace:*
         version: link:../packages/llm/token-meter
       '@deepseek-ai/dsh-tool-ask-user':
         specifier: workspace:*
-        version: link:../packages/ui/tool-ask-user
+        version: link:../packages/interaction/tool-ask-user
       '@deepseek-ai/dsh-tool-bash':
         specifier: workspace:*
         version: link:../packages/bash/tool-bash
@@ -531,7 +531,7 @@ importers:
         version: link:../packages/pty/tool-bash-persistent
       '@deepseek-ai/dsh-tool-cordis':
         specifier: workspace:*
-        version: link:../packages/cordis/tool-cordis
+        version: link:../packages/self-modification/tool-cordis
       '@deepseek-ai/dsh-tool-fs':
         specifier: workspace:*
         version: link:../packages/fs/tool-fs
@@ -588,10 +588,10 @@ importers:
         version: link:../packages/core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:*
-        version: link:../packages/ui/user-approval
+        version: link:../packages/interaction/user-approval
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:*
-        version: link:../packages/ui/user-interaction
+        version: link:../packages/interaction/user-interaction
       '@deepseek-ai/dsh-web':
         specifier: workspace:*
         version: link:../packages/web/web
@@ -665,7 +665,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -715,7 +715,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-typert-registry':
         specifier: workspace:^
         version: link:../../typert/registry
@@ -761,7 +761,7 @@ importers:
         version: link:../../util/paths
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
@@ -890,7 +890,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-subprocess-local':
         specifier: workspace:^
         version: link:../../subprocess/subprocess-local
@@ -911,7 +911,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -965,6 +965,43 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/boot/app-boot:
+    dependencies:
+      js-yaml:
+        specifier: ^4.2.0
+        version: 4.2.0
+    devDependencies:
+      '@cordisjs/plugin-hmr':
+        specifier: workspace:^
+        version: link:../../../vendor/hmr
+      '@cordisjs/plugin-include':
+        specifier: workspace:^
+        version: link:../../../vendor/include
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@cordisjs/plugin-timer':
+        specifier: workspace:^
+        version: link:../../../vendor/timer
+      '@deepseek-ai/dsh-environment':
+        specifier: workspace:^
+        version: link:../../util/environment
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-paths':
+        specifier: workspace:^
+        version: link:../../util/paths
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@types/js-yaml':
+        specifier: ^4.0.9
+        version: 4.0.9
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/bundle/base:
     dependencies:
       '@cordisjs/plugin-hmr':
@@ -999,7 +1036,7 @@ importers:
         version: link:../../goal/command-goal
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-compact-basic':
         specifier: workspace:^
         version: link:../../compact/compact-basic
@@ -1035,7 +1072,7 @@ importers:
         version: link:../../llm/llm-retry
       '@deepseek-ai/dsh-permission':
         specifier: workspace:^
-        version: link:../../ui/permission
+        version: link:../../interaction/permission
       '@deepseek-ai/dsh-plan-mode':
         specifier: workspace:^
         version: link:../../plan/plan-mode
@@ -1044,7 +1081,7 @@ importers:
         version: link:../../guard/repeat-tool-guard
       '@deepseek-ai/dsh-repository-plugin':
         specifier: workspace:^
-        version: link:../../cordis/repository-plugin
+        version: link:../../self-modification/repository-plugin
       '@deepseek-ai/dsh-sandbox-local':
         specifier: workspace:^
         version: link:../../sandbox/sandbox-local
@@ -1056,25 +1093,25 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-checkpoint-policy':
         specifier: workspace:^
-        version: link:../../session-persistence/session-checkpoint-policy
+        version: link:../../session/session-checkpoint-policy
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-session-query-sqlite':
         specifier: workspace:^
         version: link:../../session-query/session-query-sqlite
       '@deepseek-ai/dsh-session-telemetry-otel':
         specifier: workspace:^
-        version: link:../../telemetry/session-telemetry-otel
+        version: link:../../session/session-telemetry-otel
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
-        version: link:../../session-title/session-title
+        version: link:../../session/session-title
       '@deepseek-ai/dsh-session-title-first-message-llm':
         specifier: workspace:^
-        version: link:../../session-title/session-title-first-message-llm
+        version: link:../../session/session-title-first-message-llm
       '@deepseek-ai/dsh-settings-local':
         specifier: workspace:^
         version: link:../../settings/settings-local
@@ -1113,7 +1150,7 @@ importers:
         version: link:../../tasks/tasks-local
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:^
-        version: link:../../timeout/timeout-policy
+        version: link:../../guard/timeout-policy
       '@deepseek-ai/dsh-token-meter':
         specifier: workspace:^
         version: link:../../llm/token-meter
@@ -1170,10 +1207,10 @@ importers:
         version: link:../../typert/registry
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../ui/user-interaction
+        version: link:../../interaction/user-interaction
       '@deepseek-ai/dsh-web':
         specifier: workspace:^
         version: link:../../web/web
@@ -1328,7 +1365,7 @@ importers:
         version: link:../../host/webserver
       '@deepseek-ai/dsh-session-projection-cache':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection-cache
+        version: link:../../session/session-projection-cache
       '@deepseek-ai/dsh-storage':
         specifier: workspace:^
         version: link:../../storage/storage
@@ -1362,7 +1399,7 @@ importers:
     dependencies:
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-host-apiproxy':
         specifier: workspace:^
         version: link:../../host/apiproxy
@@ -1466,7 +1503,7 @@ importers:
         version: link:../ui-slots
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:^
         version: link:../../compact/compact
@@ -1484,10 +1521,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
-        version: link:../../session-title/session-title
+        version: link:../../session/session-title
       immer:
         specifier: ^10.1.1
         version: 10.2.0
@@ -1651,13 +1688,13 @@ importers:
         version: link:../../support/invariants
       '@deepseek-ai/dsh-permission':
         specifier: workspace:^
-        version: link:../../ui/permission
+        version: link:../../interaction/permission
       '@deepseek-ai/dsh-plan-mode':
         specifier: workspace:^
         version: link:../../plan/plan-mode
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-token-meter':
         specifier: workspace:^
         version: link:../../llm/token-meter
@@ -1895,7 +1932,7 @@ importers:
         version: link:../../support/invariants
       '@deepseek-ai/dsh-permission':
         specifier: workspace:^
-        version: link:../../ui/permission
+        version: link:../../interaction/permission
       '@types/react':
         specifier: ~18.3.1
         version: 18.3.31
@@ -2043,7 +2080,7 @@ importers:
         version: link:../ui-slots
       '@deepseek-ai/dsh-tool-ask-user':
         specifier: workspace:^
-        version: link:../../ui/tool-ask-user
+        version: link:../../interaction/tool-ask-user
       clsx:
         specifier: ^2.0.0
         version: 2.1.1
@@ -2068,7 +2105,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../ui/user-interaction
+        version: link:../../interaction/user-interaction
       '@types/react':
         specifier: ~18.3.1
         version: 18.3.31
@@ -2614,7 +2651,7 @@ importers:
         version: link:../../core/agent
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:^
         version: link:../compact
@@ -2871,83 +2908,6 @@ importers:
         specifier: ^4.0.0-rc.6
         version: link:../../../vendor/cordis
 
-  packages/cordis/repository-plugin:
-    dependencies:
-      zod:
-        specifier: ^4.4.3
-        version: 4.4.3
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-mcp-client':
-        specifier: workspace:^
-        version: link:../../mcp/mcp-client
-      '@deepseek-ai/dsh-paths':
-        specifier: workspace:^
-        version: link:../../util/paths
-      '@deepseek-ai/dsh-skill':
-        specifier: workspace:^
-        version: link:../../skill/skill
-      '@deepseek-ai/dsh-skill-local':
-        specifier: workspace:^
-        version: link:../../skill/skill-local
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/cordis/tool-cordis:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: ^1.0.0-rc.5
-        version: link:../../../vendor/loader
-      '@cordisjs/plugin-timer':
-        specifier: workspace:^
-        version: link:../../../vendor/timer
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-agent-loop':
-        specifier: workspace:^
-        version: link:../../core/agent-loop
-      '@deepseek-ai/dsh-agent-loop-testkit':
-        specifier: workspace:^
-        version: link:../../support/agent-loop-testkit
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-scope':
-        specifier: workspace:^
-        version: link:../../core/scope
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
   packages/core/agent:
     devDependencies:
       '@deepseek-ai/dsh-invariants':
@@ -2998,10 +2958,10 @@ importers:
         version: link:../session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../system-prompt
@@ -3093,7 +3053,7 @@ importers:
         version: link:../system-prompt
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -3219,16 +3179,16 @@ importers:
         version: link:../agent-spine-demo
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
-        version: link:../../ui/app-boot
+        version: link:../../boot/app-boot
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
       '@deepseek-ai/dsh-session-checkpoint-policy':
         specifier: workspace:^
-        version: link:../../session-persistence/session-checkpoint-policy
+        version: link:../../session/session-checkpoint-policy
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:^
         version: link:../../session-query/session-query
@@ -3316,7 +3276,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
-        version: link:../../session-title/session-title
+        version: link:../../session/session-title
       '@deepseek-ai/dsh-skill':
         specifier: workspace:^
         version: link:../../skill/skill
@@ -3367,7 +3327,7 @@ importers:
     dependencies:
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
-        version: link:../../ui/app-boot
+        version: link:../../boot/app-boot
     devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
@@ -3389,7 +3349,7 @@ importers:
         version: link:../../core/agent
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -3532,7 +3492,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -3639,7 +3599,7 @@ importers:
         version: link:../../core/agent
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-goal':
         specifier: workspace:^
         version: link:../goal
@@ -3688,7 +3648,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-type-meta':
         specifier: workspace:^
         version: link:../../typert/type-meta
@@ -3794,6 +3754,24 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/guard/timeout-policy:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/hooks/hook-protocol:
     devDependencies:
       '@deepseek-ai/dsh-bash':
@@ -3844,10 +3822,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../../subagent/subagent
@@ -3896,10 +3874,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-subprocess-local':
         specifier: workspace:^
         version: link:../../subprocess/subprocess-local
@@ -3923,7 +3901,7 @@ importers:
         version: link:../../util/brand
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-credentials':
         specifier: workspace:^
         version: link:../../credentials/credentials
@@ -3944,19 +3922,19 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-session-projection-cache':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection-cache
+        version: link:../../session/session-projection-cache
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:^
         version: link:../../session-query/session-query
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
-        version: link:../../session-title/session-title
+        version: link:../../session/session-title
       '@deepseek-ai/dsh-settings':
         specifier: workspace:^
         version: link:../../settings/settings
@@ -3971,10 +3949,10 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../ui/user-interaction
+        version: link:../../interaction/user-interaction
       '@deepseek-ai/dsh-workspace':
         specifier: workspace:^
         version: link:../../workspace/workspace
@@ -4152,6 +4130,137 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/interaction/commands:
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-scope':
+        specifier: workspace:^
+        version: link:../../core/scope
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/interaction/permission:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+    devDependencies:
+      '@deepseek-ai/dsh-bash':
+        specifier: workspace:^
+        version: link:../../bash/bash
+      '@deepseek-ai/dsh-commands':
+        specifier: workspace:^
+        version: link:../commands
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-sandbox':
+        specifier: workspace:^
+        version: link:../../sandbox/sandbox
+      '@deepseek-ai/dsh-sandbox-policy':
+        specifier: workspace:^
+        version: link:../../sandbox/sandbox-policy
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-projection':
+        specifier: workspace:^
+        version: link:../../session/session-projection
+      '@deepseek-ai/dsh-settings':
+        specifier: workspace:^
+        version: link:../../settings/settings
+      '@deepseek-ai/dsh-user-approval':
+        specifier: workspace:^
+        version: link:../user-approval
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/interaction/tool-ask-user:
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      '@deepseek-ai/dsh-user-interaction':
+        specifier: workspace:^
+        version: link:../user-interaction
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/interaction/user-approval:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-scope':
+        specifier: workspace:^
+        version: link:../../core/scope
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/interaction/user-interaction:
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/llm/llm:
     dependencies:
       schemastery:
@@ -4274,10 +4383,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-persistence-sqlite':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-sqlite
+        version: link:../../session/session-persistence-sqlite
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -4314,7 +4423,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -4415,7 +4524,7 @@ importers:
         version: link:../../util/timeout
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:^
-        version: link:../../timeout/timeout-policy
+        version: link:../../guard/timeout-policy
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
@@ -4474,7 +4583,7 @@ importers:
         version: link:../../code-runtime/code-runtime
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../ui/commands
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -4486,7 +4595,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -4495,7 +4604,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../ui/user-interaction
+        version: link:../../interaction/user-interaction
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -4724,7 +4833,25 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/sdk/create-sdk:
+  packages/scaffold/client:
+    devDependencies:
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-sdk-protocol':
+        specifier: workspace:^
+        version: link:../protocol
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/scaffold/create-sdk:
     dependencies:
       '@deepseek-ai/dsh-helper':
         specifier: workspace:^
@@ -4740,7 +4867,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/sdk/helper:
+  packages/scaffold/helper:
     dependencies:
       '@clack/core':
         specifier: ^1.4.3
@@ -4772,10 +4899,10 @@ importers:
         version: link:../../support/invariants
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-persistence-sqlite':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-sqlite
+        version: link:../../session/session-persistence-sqlite
       '@deepseek-ai/dsh-subprocess':
         specifier: workspace:^
         version: link:../../subprocess/subprocess
@@ -4792,56 +4919,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/sdk/scripts:
-    dependencies:
-      '@deepseek-ai/dsh-helper':
-        specifier: workspace:^
-        version: link:../helper
-      '@deepseek-ai/dsh-telemetry':
-        specifier: workspace:^
-        version: link:../telemetry
-      commander:
-        specifier: ^15.0.0
-        version: 15.0.0
-      node-addon-require-builtin:
-        specifier: ^0.1.4
-        version: 0.1.4
-    devDependencies:
-      '@deepseek-ai/dsh-app-boot':
-        specifier: workspace:^
-        version: link:../../ui/app-boot
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-      tsdown:
-        specifier: ^0.22.2
-        version: 0.22.2(oxc-resolver@11.20.0)(publint@0.3.21)(tsx@4.22.4)(typescript@6.0.3)
-      tsx:
-        specifier: ^4.22.4
-        version: 4.22.4
-
-  packages/sdk/sdk-client:
-    devDependencies:
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-sdk-protocol':
-        specifier: workspace:^
-        version: link:../sdk-protocol
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/sdk/sdk-protocol:
+  packages/scaffold/protocol:
     devDependencies:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
@@ -4859,7 +4937,81 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/sdk/telemetry:
+  packages/scaffold/scripts:
+    dependencies:
+      '@deepseek-ai/dsh-helper':
+        specifier: workspace:^
+        version: link:../helper
+      '@deepseek-ai/dsh-telemetry':
+        specifier: workspace:^
+        version: link:../telemetry
+      commander:
+        specifier: ^15.0.0
+        version: 15.0.0
+      node-addon-require-builtin:
+        specifier: ^0.1.4
+        version: 0.1.4
+    devDependencies:
+      '@deepseek-ai/dsh-app-boot':
+        specifier: workspace:^
+        version: link:../../boot/app-boot
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+      tsdown:
+        specifier: ^0.22.2
+        version: 0.22.2(oxc-resolver@11.20.0)(publint@0.3.21)(tsx@4.22.4)(typescript@6.0.3)
+      tsx:
+        specifier: ^4.22.4
+        version: 4.22.4
+
+  packages/scaffold/server:
+    dependencies:
+      schemastery:
+        specifier: ^3.17.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-spine-demo':
+        specifier: workspace:^
+        version: link:../../examples/agent-spine-demo
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-llm-deepseek':
+        specifier: workspace:^
+        version: link:../../llm/llm-deepseek
+      '@deepseek-ai/dsh-scope':
+        specifier: workspace:^
+        version: link:../../core/scope
+      '@deepseek-ai/dsh-sdk-protocol':
+        specifier: workspace:^
+        version: link:../protocol
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence-jsonl':
+        specifier: workspace:^
+        version: link:../../session/session-persistence-jsonl
+      '@deepseek-ai/dsh-subagent':
+        specifier: workspace:^
+        version: link:../../subagent/subagent
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/scaffold/telemetry:
     dependencies:
       yaml:
         specifier: ^2.9.0
@@ -4878,7 +5030,185 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-persistence/session-checkpoint-policy:
+  packages/self-modification/repository-plugin:
+    dependencies:
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-mcp-client':
+        specifier: workspace:^
+        version: link:../../mcp/mcp-client
+      '@deepseek-ai/dsh-paths':
+        specifier: workspace:^
+        version: link:../../util/paths
+      '@deepseek-ai/dsh-skill':
+        specifier: workspace:^
+        version: link:../../skill/skill
+      '@deepseek-ai/dsh-skill-local':
+        specifier: workspace:^
+        version: link:../../skill/skill-local
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/self-modification/tool-cordis:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: ^1.0.0-rc.5
+        version: link:../../../vendor/loader
+      '@cordisjs/plugin-timer':
+        specifier: workspace:^
+        version: link:../../../vendor/timer
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-loop':
+        specifier: workspace:^
+        version: link:../../core/agent-loop
+      '@deepseek-ai/dsh-agent-loop-testkit':
+        specifier: workspace:^
+        version: link:../../support/agent-loop-testkit
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-scope':
+        specifier: workspace:^
+        version: link:../../core/scope
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/session-query/session-query:
+    devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence':
+        specifier: workspace:^
+        version: link:../../session/session-persistence
+      '@deepseek-ai/dsh-session-title':
+        specifier: workspace:^
+        version: link:../../session/session-title
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/session-query/session-query-sqlite:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence':
+        specifier: workspace:^
+        version: link:../../session/session-persistence
+      '@deepseek-ai/dsh-session-persistence-sqlite':
+        specifier: workspace:^
+        version: link:../../session/session-persistence-sqlite
+      '@deepseek-ai/dsh-session-query':
+        specifier: workspace:^
+        version: link:../session-query
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/session-query/tool-session-query:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence':
+        specifier: workspace:^
+        version: link:../../session/session-persistence
+      '@deepseek-ai/dsh-session-persistence-jsonl':
+        specifier: workspace:^
+        version: link:../../session/session-persistence-jsonl
+      '@deepseek-ai/dsh-session-query':
+        specifier: workspace:^
+        version: link:../session-query
+      '@deepseek-ai/dsh-session-query-sqlite':
+        specifier: workspace:^
+        version: link:../session-query-sqlite
+      '@deepseek-ai/dsh-session-title':
+        specifier: workspace:^
+        version: link:../../session/session-title
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
+      '@deepseek-ai/dsh-timeout-policy':
+        specifier: workspace:^
+        version: link:../../guard/timeout-policy
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/session/session-checkpoint-policy:
     devDependencies:
       '@cordisjs/plugin-loader':
         specifier: workspace:^
@@ -4917,7 +5247,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-persistence/session-persistence:
+  packages/session/session-persistence:
     devDependencies:
       '@deepseek-ai/dsh-brand':
         specifier: workspace:^
@@ -4938,7 +5268,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-persistence/session-persistence-jsonl:
+  packages/session/session-persistence-jsonl:
     dependencies:
       koffi:
         specifier: ^3.1.0
@@ -4960,7 +5290,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-persistence/session-persistence-sqlite:
+  packages/session/session-persistence-sqlite:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -4979,7 +5309,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-projection/session-projection:
+  packages/session/session-projection:
     dependencies:
       zod:
         specifier: ^4.4.3
@@ -4995,7 +5325,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-projection/session-projection-cache:
+  packages/session/session-projection-cache:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -5012,7 +5342,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../session-persistence
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
         version: link:../session-projection
@@ -5026,63 +5356,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-query/session-query:
-    devDependencies:
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-persistence':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
-      '@deepseek-ai/dsh-session-title':
-        specifier: workspace:^
-        version: link:../../session-title/session-title
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/session-query/session-query-sqlite:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-persistence':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
-      '@deepseek-ai/dsh-session-persistence-sqlite':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-sqlite
-      '@deepseek-ai/dsh-session-query':
-        specifier: workspace:^
-        version: link:../session-query
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/session-query/tool-session-query:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
+  packages/session/session-telemetry:
     devDependencies:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
@@ -5090,44 +5364,66 @@ importers:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
-      '@deepseek-ai/dsh-session-persistence':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
-      '@deepseek-ai/dsh-session-persistence-jsonl':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
-      '@deepseek-ai/dsh-session-query':
-        specifier: workspace:^
-        version: link:../session-query
-      '@deepseek-ai/dsh-session-query-sqlite':
-        specifier: workspace:^
-        version: link:../session-query-sqlite
-      '@deepseek-ai/dsh-session-title':
-        specifier: workspace:^
-        version: link:../../session-title/session-title
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@deepseek-ai/dsh-timeout':
-        specifier: workspace:^
-        version: link:../../util/timeout
-      '@deepseek-ai/dsh-timeout-policy':
-        specifier: workspace:^
-        version: link:../../timeout/timeout-policy
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-title/session-title:
+  packages/session/session-telemetry-otel:
+    dependencies:
+      '@opentelemetry/api':
+        specifier: ^1.9.1
+        version: 1.9.1
+      '@opentelemetry/api-logs':
+        specifier: ^0.220.0
+        version: 0.220.0
+      '@opentelemetry/exporter-logs-otlp-http':
+        specifier: ^0.220.0
+        version: 0.220.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-exporter-base':
+        specifier: ^0.220.0
+        version: 0.220.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources':
+        specifier: ^2.9.0
+        version: 2.10.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-logs':
+        specifier: ^0.220.0
+        version: 0.220.0(@opentelemetry/api@1.9.1)
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-command-feedback':
+        specifier: workspace:^
+        version: link:../../feedback/command-feedback
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-paths':
+        specifier: workspace:^
+        version: link:../../util/paths
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-telemetry':
+        specifier: workspace:^
+        version: link:../session-telemetry
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/session/session-title:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -5150,18 +5446,18 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../session-persistence-jsonl
       '@deepseek-ai/dsh-session-persistence-sqlite':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-sqlite
+        version: link:../session-persistence-sqlite
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../session-projection
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-title/session-title-all-messages-llm:
+  packages/session/session-title-all-messages-llm:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -5186,7 +5482,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-title/session-title-first-message-llm:
+  packages/session/session-title-first-message-llm:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -5220,7 +5516,7 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/session-title/session-title-llm:
+  packages/session/session-title-llm:
     dependencies:
       schemastery:
         specifier: ^3.18.0
@@ -5541,13 +5837,13 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-session-projection-cache':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection-cache
+        version: link:../../session/session-projection-cache
       '@deepseek-ai/dsh-storage':
         specifier: workspace:^
         version: link:../../storage/storage
@@ -5673,7 +5969,7 @@ importers:
         version: link:../../support/loader-smoke
       '@deepseek-ai/dsh-sdk-protocol':
         specifier: workspace:^
-        version: link:../../sdk/sdk-protocol
+        version: link:../../scaffold/protocol
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -5719,10 +6015,10 @@ importers:
         version: link:../../support/loader-smoke
       '@deepseek-ai/dsh-sdk-client':
         specifier: workspace:^
-        version: link:../../sdk/sdk-client
+        version: link:../../scaffold/client
       '@deepseek-ai/dsh-sdk-protocol':
         specifier: workspace:^
-        version: link:../../sdk/sdk-protocol
+        version: link:../../scaffold/protocol
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -5816,7 +6112,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../ui/user-approval
+        version: link:../../interaction/user-approval
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -5896,10 +6192,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../subagent
@@ -5947,13 +6243,13 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../subagent
@@ -5993,10 +6289,10 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
+        version: link:../../session/session-persistence-jsonl
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../subagent
@@ -6231,91 +6527,6 @@ importers:
         specifier: ^4.0.0-rc.6
         version: link:../../../vendor/cordis
 
-  packages/telemetry/session-telemetry:
-    devDependencies:
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/telemetry/session-telemetry-otel:
-    dependencies:
-      '@opentelemetry/api':
-        specifier: ^1.9.1
-        version: 1.9.1
-      '@opentelemetry/api-logs':
-        specifier: ^0.220.0
-        version: 0.220.0
-      '@opentelemetry/exporter-logs-otlp-http':
-        specifier: ^0.220.0
-        version: 0.220.0(@opentelemetry/api@1.9.1)
-      '@opentelemetry/otlp-exporter-base':
-        specifier: ^0.220.0
-        version: 0.220.0(@opentelemetry/api@1.9.1)
-      '@opentelemetry/resources':
-        specifier: ^2.9.0
-        version: 2.10.0(@opentelemetry/api@1.9.1)
-      '@opentelemetry/sdk-logs':
-        specifier: ^0.220.0
-        version: 0.220.0(@opentelemetry/api@1.9.1)
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
-      '@deepseek-ai/dsh-command-feedback':
-        specifier: workspace:^
-        version: link:../../feedback/command-feedback
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-paths':
-        specifier: workspace:^
-        version: link:../../util/paths
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-telemetry':
-        specifier: workspace:^
-        version: link:../session-telemetry
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/timeout/timeout-policy:
-    devDependencies:
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-timeout':
-        specifier: workspace:^
-        version: link:../../util/timeout
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
   packages/todo/tool-todo:
     dependencies:
       schemastery:
@@ -6354,7 +6565,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-projection/session-projection
+        version: link:../../session/session-projection
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
@@ -6363,7 +6574,7 @@ importers:
         version: link:../../core/tools
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../ui/user-interaction
+        version: link:../../interaction/user-interaction
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -6382,7 +6593,7 @@ importers:
         version: link:../../support/invariants
       '@deepseek-ai/dsh-tool-cordis':
         specifier: workspace:^
-        version: link:../../cordis/tool-cordis
+        version: link:../../self-modification/tool-cordis
       '@deepseek-ai/dsh-typert-registry':
         specifier: workspace:^
         version: link:../registry
@@ -6440,217 +6651,6 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
-  packages/ui/app-boot:
-    dependencies:
-      js-yaml:
-        specifier: ^4.2.0
-        version: 4.2.0
-    devDependencies:
-      '@cordisjs/plugin-hmr':
-        specifier: workspace:^
-        version: link:../../../vendor/hmr
-      '@cordisjs/plugin-include':
-        specifier: workspace:^
-        version: link:../../../vendor/include
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@cordisjs/plugin-timer':
-        specifier: workspace:^
-        version: link:../../../vendor/timer
-      '@deepseek-ai/dsh-environment':
-        specifier: workspace:^
-        version: link:../../util/environment
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-paths':
-        specifier: workspace:^
-        version: link:../../util/paths
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@types/js-yaml':
-        specifier: ^4.0.9
-        version: 4.0.9
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/commands:
-    devDependencies:
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-scope':
-        specifier: workspace:^
-        version: link:../../core/scope
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/jsonrpc:
-    dependencies:
-      schemastery:
-        specifier: ^3.17.0
-        version: link:../../../vendor/schemastery
-    devDependencies:
-      '@cordisjs/plugin-loader':
-        specifier: workspace:^
-        version: link:../../../vendor/loader
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-agent-spine-demo':
-        specifier: workspace:^
-        version: link:../../examples/agent-spine-demo
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-llm-deepseek':
-        specifier: workspace:^
-        version: link:../../llm/llm-deepseek
-      '@deepseek-ai/dsh-scope':
-        specifier: workspace:^
-        version: link:../../core/scope
-      '@deepseek-ai/dsh-sdk-protocol':
-        specifier: workspace:^
-        version: link:../../sdk/sdk-protocol
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-persistence-jsonl':
-        specifier: workspace:^
-        version: link:../../session-persistence/session-persistence-jsonl
-      '@deepseek-ai/dsh-subagent':
-        specifier: workspace:^
-        version: link:../../subagent/subagent
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/permission:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
-      zod:
-        specifier: ^4.4.3
-        version: 4.4.3
-    devDependencies:
-      '@deepseek-ai/dsh-bash':
-        specifier: workspace:^
-        version: link:../../bash/bash
-      '@deepseek-ai/dsh-commands':
-        specifier: workspace:^
-        version: link:../commands
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-sandbox':
-        specifier: workspace:^
-        version: link:../../sandbox/sandbox
-      '@deepseek-ai/dsh-sandbox-policy':
-        specifier: workspace:^
-        version: link:../../sandbox/sandbox-policy
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-session-projection':
-        specifier: workspace:^
-        version: link:../../session-projection/session-projection
-      '@deepseek-ai/dsh-settings':
-        specifier: workspace:^
-        version: link:../../settings/settings
-      '@deepseek-ai/dsh-user-approval':
-        specifier: workspace:^
-        version: link:../user-approval
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/tool-ask-user:
-    devDependencies:
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      '@deepseek-ai/dsh-tools':
-        specifier: workspace:^
-        version: link:../../core/tools
-      '@deepseek-ai/dsh-user-interaction':
-        specifier: workspace:^
-        version: link:../user-interaction
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/user-approval:
-    dependencies:
-      schemastery:
-        specifier: ^3.18.0
-        version: link:../../../vendor/schemastery
-    devDependencies:
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      '@deepseek-ai/dsh-scope':
-        specifier: workspace:^
-        version: link:../../core/scope
-      '@deepseek-ai/dsh-session':
-        specifier: workspace:^
-        version: link:../../core/session
-      '@deepseek-ai/dsh-system-prompt':
-        specifier: workspace:^
-        version: link:../../core/system-prompt
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
-  packages/ui/user-interaction:
-    devDependencies:
-      '@deepseek-ai/dsh-agent':
-        specifier: workspace:^
-        version: link:../../core/agent
-      '@deepseek-ai/dsh-invariants':
-        specifier: workspace:^
-        version: link:../../support/invariants
-      '@deepseek-ai/dsh-llm':
-        specifier: workspace:^
-        version: link:../../llm/llm
-      cordis:
-        specifier: ^4.0.0-rc.7
-        version: link:../../../vendor/cordis
-
   packages/util/atomic-write:
     devDependencies:
       '@deepseek-ai/dsh-invariants':
@@ -6749,7 +6749,7 @@ importers:
         version: link:../../core/system-prompt
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:^
-        version: link:../../timeout/timeout-policy
+        version: link:../../guard/timeout-policy
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
@@ -7049,7 +7049,7 @@ importers:
         version: link:../../core/session
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../session-persistence/session-persistence
+        version: link:../../session/session-persistence
       '@deepseek-ai/dsh-storage':
         specifier: workspace:^
         version: link:../../storage/storage
@@ -7085,7 +7085,7 @@ importers:
         version: link:../../packages/examples/agent-spine-demo
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
-        version: link:../../packages/ui/app-boot
+        version: link:../../packages/boot/app-boot
       '@deepseek-ai/dsh-bash':
         specifier: workspace:^
         version: link:../../packages/bash/bash
@@ -7109,7 +7109,7 @@ importers:
         version: link:../../packages/goal/command-goal
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
-        version: link:../../packages/ui/commands
+        version: link:../../packages/interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:^
         version: link:../../packages/compact/compact
@@ -7154,7 +7154,7 @@ importers:
         version: link:../../packages/support/invariants
       '@deepseek-ai/dsh-jsonrpc':
         specifier: workspace:^
-        version: link:../../packages/ui/jsonrpc
+        version: link:../../packages/scaffold/server
       '@deepseek-ai/dsh-jsonrpc-demo':
         specifier: workspace:^
         version: link:../../packages/examples/jsonrpc-demo
@@ -7175,7 +7175,7 @@ importers:
         version: link:../../packages/util/paths
       '@deepseek-ai/dsh-permission':
         specifier: workspace:^
-        version: link:../../packages/ui/permission
+        version: link:../../packages/interaction/permission
       '@deepseek-ai/dsh-plan-mode':
         specifier: workspace:^
         version: link:../../packages/plan/plan-mode
@@ -7205,25 +7205,25 @@ importers:
         version: link:../../packages/core/scope
       '@deepseek-ai/dsh-sdk-protocol':
         specifier: workspace:^
-        version: link:../../packages/sdk/sdk-protocol
+        version: link:../../packages/scaffold/protocol
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../packages/core/session
       '@deepseek-ai/dsh-session-checkpoint-policy':
         specifier: workspace:^
-        version: link:../../packages/session-persistence/session-checkpoint-policy
+        version: link:../../packages/session/session-checkpoint-policy
       '@deepseek-ai/dsh-session-persistence':
         specifier: workspace:^
-        version: link:../../packages/session-persistence/session-persistence
+        version: link:../../packages/session/session-persistence
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
-        version: link:../../packages/session-persistence/session-persistence-jsonl
+        version: link:../../packages/session/session-persistence-jsonl
       '@deepseek-ai/dsh-session-persistence-sqlite':
         specifier: workspace:^
-        version: link:../../packages/session-persistence/session-persistence-sqlite
+        version: link:../../packages/session/session-persistence-sqlite
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../packages/session-projection/session-projection
+        version: link:../../packages/session/session-projection
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:^
         version: link:../../packages/session-query/session-query
@@ -7235,7 +7235,7 @@ importers:
         version: link:../../packages/context/session-reference
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
-        version: link:../../packages/session-title/session-title
+        version: link:../../packages/session/session-title
       '@deepseek-ai/dsh-settings':
         specifier: workspace:^
         version: link:../../packages/settings/settings
@@ -7280,13 +7280,13 @@ importers:
         version: link:../../packages/util/timeout
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:^
-        version: link:../../packages/timeout/timeout-policy
+        version: link:../../packages/guard/timeout-policy
       '@deepseek-ai/dsh-token-meter':
         specifier: workspace:^
         version: link:../../packages/llm/token-meter
       '@deepseek-ai/dsh-tool-ask-user':
         specifier: workspace:^
-        version: link:../../packages/ui/tool-ask-user
+        version: link:../../packages/interaction/tool-ask-user
       '@deepseek-ai/dsh-tool-bash':
         specifier: workspace:^
         version: link:../../packages/bash/tool-bash
@@ -7295,7 +7295,7 @@ importers:
         version: link:../../packages/pty/tool-bash-persistent
       '@deepseek-ai/dsh-tool-cordis':
         specifier: workspace:^
-        version: link:../../packages/cordis/tool-cordis
+        version: link:../../packages/self-modification/tool-cordis
       '@deepseek-ai/dsh-tool-fs':
         specifier: workspace:^
         version: link:../../packages/fs/tool-fs
@@ -7334,10 +7334,10 @@ importers:
         version: link:../../packages/typert/type-meta
       '@deepseek-ai/dsh-user-approval':
         specifier: workspace:^
-        version: link:../../packages/ui/user-approval
+        version: link:../../packages/interaction/user-approval
       '@deepseek-ai/dsh-user-interaction':
         specifier: workspace:^
-        version: link:../../packages/ui/user-interaction
+        version: link:../../packages/interaction/user-interaction
       '@deepseek-ai/dsh-web':
         specifier: workspace:^
         version: link:../../packages/web/web
@@ -14103,7 +14103,7 @@ snapshots:
 
   '@opentelemetry/api-logs@0.220.0':
     dependencies:
-      '@opentelemetry/api': 1.9.0
+      '@opentelemetry/api': 1.9.1
 
   '@opentelemetry/api@1.9.0': {}
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index ec8c282b80..40b3f620e3 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -8,11 +8,11 @@
       },
       {
         "role": "user",
-        "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Install\n\nClone the repository, then run the installer:\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\nThe installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, prompts for a DeepSeek API key, builds the required repository artifacts, and launches the Web UI.\n\nThe default active checkout is `~/.dsh/source/current`, and the launcher is linked into `~/.local/bin`. Re-run the installer to update. [`scripts/install.sh`](scripts/install.sh) owns alternate locations, update mechanics, and recovery options.\n\n## Use DeepSeek Harness\n\n### Web UI\n\nFor the recommended local interface, choose Web UI when the installer finishes. To start it later, or after updating the active checkout, build the repository and run:\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\nThe path above is the installer's default. If you set `DSH_SOURCE` or `DSH_CURRENT`, or reused an existing checkout, replace `~/.dsh/source/current` with that checkout path; see [`scripts/install.sh`](scripts/install.sh) for details. The Web UI is served at `http://127.0.0.1:3080` by default.\n\n### Profiles\n\n`dsh` boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nThe [CLI contract](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/cordis/tool-cordis/README.md).\n\n## Community\n\nFollow <a href=\"https://x.com/Deepseekharness\">DeepSeek Harness on Twitter</a> for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently in internal testing.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n"
+        "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Install\n\nClone the repository, then run the installer:\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\nThe installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, prompts for a DeepSeek API key, builds the required repository artifacts, and launches the Web UI.\n\nThe default active checkout is `~/.dsh/source/current`, and the launcher is linked into `~/.local/bin`. Re-run the installer to update. [`scripts/install.sh`](scripts/install.sh) owns alternate locations, update mechanics, and recovery options.\n\n## Use DeepSeek Harness\n\n### Web UI\n\nFor the recommended local interface, choose Web UI when the installer finishes. To start it later, or after updating the active checkout, build the repository and run:\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\nThe path above is the installer's default. If you set `DSH_SOURCE` or `DSH_CURRENT`, or reused an existing checkout, replace `~/.dsh/source/current` with that checkout path; see [`scripts/install.sh`](scripts/install.sh) for details. The Web UI is served at `http://127.0.0.1:3080` by default.\n\n### Profiles\n\n`dsh` boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nThe [CLI contract](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/self-modification/tool-cordis/README.md).\n\n## Community\n\nFollow <a href=\"https://x.com/Deepseekharness\">DeepSeek Harness on Twitter</a> for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently in internal testing.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n"
       },
       {
         "role": "assistant",
-        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
+        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
       },
       {
         "role": "user",
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 903172e48f..9180a3bd9a 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -443,7 +443,7 @@
     {
       "doc": "docs/core-data-structures/persistence.md",
       "symbol": "SessionInspection",
-      "source": "packages/session-persistence/session-persistence/src/index.ts"
+      "source": "packages/session/session-persistence/src/index.ts"
     },
     {
       "doc": "docs/core-data-structures/persistence.md",
diff --git a/scripts/verify-package-paths.ts b/scripts/verify-package-paths.ts
index f709354899..85c18e3cee 100644
--- a/scripts/verify-package-paths.ts
+++ b/scripts/verify-package-paths.ts
@@ -1,8 +1,8 @@
 /**
  * Find stale root-relative `packages/...` references in repo-authored prose and
- * TypeScript. A missing path is reported only when it names a real package leaf;
- * globs, placeholders, hypothetical packages, and unbuilt `lib/` output are
- * outside the check.
+ * TypeScript. A missing path is reported only when it names a real package leaf
+ * outside its own explaining group directory; globs, placeholders, hypothetical
+ * packages, and unbuilt `lib/` output are outside the check.
  */
 
 import { existsSync, globSync } from 'node:fs'
@@ -66,7 +66,15 @@ function isDriftedPackageReference(ref: string): boolean {
   const libAt = parts.indexOf('lib')
   if (libAt === 3 && existsSync(resolve(root, parts.slice(0, 3).join('/')))) return false
   // A missing reference is drift only when a path segment names a live package.
-  return ref.split('/').slice(1).some(segment => packageNames.has(segment))
+  // A leading segment that is itself an existing group directory is explained by
+  // the group, not by a relocated leaf sharing its name (`client` is both the
+  // client-modules group and the scaffold leaf), so only later segments count.
+  const segments = ref.split('/').slice(1)
+  const [group] = segments
+  const scanned = group !== undefined && segments.length > 1 && existsSync(resolve(root, 'packages', group))
+    ? segments.slice(1)
+    : segments
+  return scanned.some(segment => packageNames.has(segment))
 }
 
 /** Find missing package references whose path names a live package; bare paths, typos, and illustrative skeletons do not count. */

From ba3125234a4e968d19220eeac10642c41524fc19 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 18:06:07 +0800
Subject: [PATCH 407/516] docs: rename core-data-structures/ to subsystems/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The folder is becoming the home of one-doc-per-subsystem pages (intro +
data structures + cordis services/events), so the name must describe the
whole contract, not just the type-vocabulary third of it. Mechanical
rename rebuilt on current master: every inbound Markdown link, generator
constant, website route, type-equiv manifest path, and spec expectation
moves together; the zh sides of the notes whose prose names the folder
are aligned (子系统) in the same change; touched bilingual pairs
re-recorded; translation-prompt snapshot re-recorded (its example embeds
development.md). Historical Agent Note slugs keep their dated
filenames.
---
 ...eneric-long-running-tool-runtime.i18n.yaml |   4 +-
 ...06-20-generic-long-running-tool-runtime.md |   2 +-
 ...20-generic-long-running-tool-runtime.zh.md |   2 +-
 ...andatory-app-attribution-headers.i18n.yaml |   4 +-
 ...06-21-mandatory-app-attribution-headers.md |   2 +-
 ...21-mandatory-app-attribution-headers.zh.md |   2 +-
 ...stdin-env-trusted-plugin-surface.i18n.yaml |   4 +-
 ...0-bash-stdin-env-trusted-plugin-surface.md |   2 +-
 ...ash-stdin-env-trusted-plugin-surface.zh.md |   2 +-
 ...2026-07-15-agent-initiator-scope.i18n.yaml |   4 +-
 .../2026-07-15-agent-initiator-scope.md       |   2 +-
 .../2026-07-15-agent-initiator-scope.zh.md    |   2 +-
 .../2026-06-30-interception-seams.i18n.yaml   |   4 +-
 .../feature/2026-06-30-interception-seams.md  |   2 +-
 .../2026-06-30-interception-seams.zh.md       |   2 +-
 .../2026-07-05-dynamic-workflows.i18n.yaml    |   4 +-
 .../feature/2026-07-05-dynamic-workflows.md   |   2 +-
 .../2026-07-05-dynamic-workflows.zh.md        |   2 +-
 .../feature/2026-07-05-skill-system.i18n.yaml |   4 +-
 .../feature/2026-07-05-skill-system.md        |   2 +-
 .../feature/2026-07-05-skill-system.zh.md     |   2 +-
 .../feature/2026-07-06-sandbox.i18n.yaml      |   4 +-
 .../implemented/feature/2026-07-06-sandbox.md |   2 +-
 .../feature/2026-07-06-sandbox.zh.md          |   2 +-
 ...-10-parallel-tool-call-execution.i18n.yaml |   4 +-
 ...2026-07-10-parallel-tool-call-execution.md |   2 +-
 ...6-07-10-parallel-tool-call-execution.zh.md |   2 +-
 ...7-31-code-mode-language-dispatch.i18n.yaml |   4 +-
 .../2026-07-31-code-mode-language-dispatch.md |   4 +-
 ...26-07-31-code-mode-language-dispatch.zh.md |   4 +-
 ...-20-core-data-structures-catalog.i18n.yaml |   4 +-
 ...2026-06-20-core-data-structures-catalog.md |   4 +-
 ...6-06-20-core-data-structures-catalog.zh.md |   2 +-
 ...-fork-child-replay-seed-boundary.i18n.yaml |   4 +-
 ...6-06-22-fork-child-replay-seed-boundary.md |   2 +-
 ...6-22-fork-child-replay-seed-boundary.zh.md |   2 +-
 .agents/skills/dsh-code-review/SKILL.md       |   2 +-
 docs/AGENTS.md                                |   4 +-
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   8 +-
 docs/architecture.zh.md                       |   8 +-
 docs/config-catalog.md                        |  12 +-
 docs/cordis-catalog/events.md                 |  84 +--
 docs/cordis-catalog/services.md               |  78 +--
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   4 +-
 docs/development.zh.md                        |   4 +-
 docs/graph-atlas.md                           |   2 +-
 docs/i18n/style-samples.md                    |   4 +-
 docs/persistence-catalog.md                   |  26 +-
 ...ice-misclassified-child-failures.i18n.yaml |   4 +-
 ...ial-notice-misclassified-child-failures.md |   2 +-
 ...-notice-misclassified-child-failures.zh.md |   2 +-
 .../approval.i18n.yaml                        |   2 +-
 .../approval.md                               |   0
 .../approval.zh.md                            |   0
 .../bash.i18n.yaml                            |   0
 .../bash.md                                   |   0
 .../bash.zh.md                                |   0
 .../code-runtime.i18n.yaml                    |   0
 .../code-runtime.md                           |   0
 .../code-runtime.zh.md                        |   0
 .../commands.i18n.yaml                        |   2 +-
 .../commands.md                               |   0
 .../commands.zh.md                            |   0
 .../compaction.i18n.yaml                      |   2 +-
 .../compaction.md                             |   0
 .../compaction.zh.md                          |   0
 .../core.i18n.yaml                            |   2 +-
 .../core.md                                   |   0
 .../core.zh.md                                |   0
 .../credentials.i18n.yaml                     |   2 +-
 .../credentials.md                            |   0
 .../credentials.zh.md                         |   0
 .../filesystem.i18n.yaml                      |   0
 .../filesystem.md                             |   0
 .../filesystem.zh.md                          |   0
 .../goal.i18n.yaml                            |   0
 .../goal.md                                   |   0
 .../goal.zh.md                                |   0
 .../llm-streaming.i18n.yaml                   |   2 +-
 .../llm-streaming.md                          |   0
 .../llm-streaming.zh.md                       |   0
 .../lsp.i18n.yaml                             |   0
 .../lsp.md                                    |   0
 .../lsp.zh.md                                 |   0
 .../persistence.i18n.yaml                     |   2 +-
 .../persistence.md                            |   0
 .../persistence.zh.md                         |   0
 .../pty.i18n.yaml                             |   0
 .../pty.md                                    |   0
 .../pty.zh.md                                 |   0
 .../sandbox.i18n.yaml                         |   0
 .../sandbox.md                                |   0
 .../sandbox.zh.md                             |   0
 .../scope.i18n.yaml                           |   0
 .../scope.md                                  |   0
 .../scope.zh.md                               |   0
 .../session-query.i18n.yaml                   |   0
 .../session-query.md                          |   0
 .../session-query.zh.md                       |   0
 .../session-reference.i18n.yaml               |   2 +-
 .../session-reference.md                      |   0
 .../session-reference.zh.md                   |   0
 .../session-title.i18n.yaml                   |   2 +-
 .../session-title.md                          |   0
 .../session-title.zh.md                       |   0
 .../session.i18n.yaml                         |   2 +-
 .../session.md                                |   0
 .../session.zh.md                             |   0
 .../settings.i18n.yaml                        |   2 +-
 .../settings.md                               |   0
 .../settings.zh.md                            |   0
 .../skills.i18n.yaml                          |   2 +-
 .../skills.md                                 |   0
 .../skills.zh.md                              |   0
 .../spill.i18n.yaml                           |   0
 .../spill.md                                  |   0
 .../spill.zh.md                               |   0
 .../subagent.i18n.yaml                        |   0
 .../subagent.md                               |   0
 .../subagent.zh.md                            |   0
 .../subprocess.i18n.yaml                      |   0
 .../subprocess.md                             |   0
 .../subprocess.zh.md                          |   0
 .../system-prompt.i18n.yaml                   |   2 +-
 .../system-prompt.md                          |   0
 .../system-prompt.zh.md                       |   0
 .../tasks.i18n.yaml                           |   0
 .../tasks.md                                  |   0
 .../tasks.zh.md                               |   0
 .../token-meter.i18n.yaml                     |   0
 .../token-meter.md                            |   0
 .../token-meter.zh.md                         |   0
 .../tools.i18n.yaml                           |   2 +-
 .../tools.md                                  |   0
 .../tools.zh.md                               |   0
 .../typert.i18n.yaml                          |   0
 .../typert.md                                 |   0
 .../typert.zh.md                              |   0
 .../user-interaction.i18n.yaml                |   2 +-
 .../user-interaction.md                       |   0
 .../user-interaction.zh.md                    |   0
 .../web.i18n.yaml                             |   0
 .../web.md                                    |   0
 .../web.zh.md                                 |   0
 .../workflow.i18n.yaml                        |   0
 .../workflow.md                               |   0
 .../workflow.zh.md                            |   0
 docs/tool-catalog.md                          |   2 +-
 packages/bash/bash/README.i18n.yaml           |   4 +-
 packages/bash/bash/README.md                  |   2 +-
 packages/bash/bash/README.zh.md               |   2 +-
 packages/compact/compact/README.i18n.yaml     |   4 +-
 packages/compact/compact/README.md            |   2 +-
 packages/compact/compact/README.zh.md         |   2 +-
 packages/core/session/README.i18n.yaml        |   4 +-
 packages/core/session/README.md               |   2 +-
 packages/core/session/README.zh.md            |   2 +-
 packages/core/tools/src/index.ts              |   2 +-
 packages/goal/goal/README.i18n.yaml           |   4 +-
 packages/goal/goal/README.md                  |   2 +-
 packages/goal/goal/README.zh.md               |   2 +-
 packages/sandbox/sandbox/README.i18n.yaml     |   4 +-
 packages/sandbox/sandbox/README.md            |   2 +-
 packages/sandbox/sandbox/README.zh.md         |   2 +-
 .../session/session-title/README.i18n.yaml    |   6 +-
 packages/session/session-title/README.md      |   2 +-
 packages/session/session-title/README.zh.md   |   2 +-
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.md      |   2 +-
 packages/subprocess/subprocess/README.zh.md   |   2 +-
 packages/tasks/tasks/README.i18n.yaml         |   4 +-
 packages/tasks/tasks/README.md                |   2 +-
 packages/tasks/tasks/README.zh.md             |   2 +-
 .../typert/generator/src/cordis-catalog.ts    |   6 +-
 .../tests/cordis-catalog-contract.spec.ts     |   2 +-
 scripts/gen-config-catalog.ts                 |   6 +-
 scripts/gen-cordis-catalog.ts                 |   2 +-
 scripts/gen-doc-graphs.ts                     |   2 +-
 scripts/gen-persistence-catalog.ts            |   8 +-
 scripts/gen-tool-catalog.ts                   |   2 +-
 scripts/project-doc-site.spec.ts              |   8 +-
 .../request-response.expected.json            |   4 +-
 scripts/type-equiv.manifest.json              | 624 +++++++++---------
 website/docs.ts                               |  10 +-
 186 files changed, 564 insertions(+), 564 deletions(-)
 rename docs/{core-data-structures => subsystems}/approval.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/approval.md (100%)
 rename docs/{core-data-structures => subsystems}/approval.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/bash.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/bash.md (100%)
 rename docs/{core-data-structures => subsystems}/bash.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/code-runtime.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/code-runtime.md (100%)
 rename docs/{core-data-structures => subsystems}/code-runtime.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/commands.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/commands.md (100%)
 rename docs/{core-data-structures => subsystems}/commands.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/compaction.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/compaction.md (100%)
 rename docs/{core-data-structures => subsystems}/compaction.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/core.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/core.md (100%)
 rename docs/{core-data-structures => subsystems}/core.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/credentials.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/credentials.md (100%)
 rename docs/{core-data-structures => subsystems}/credentials.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/filesystem.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/filesystem.md (100%)
 rename docs/{core-data-structures => subsystems}/filesystem.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/goal.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/goal.md (100%)
 rename docs/{core-data-structures => subsystems}/goal.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/llm-streaming.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/llm-streaming.md (100%)
 rename docs/{core-data-structures => subsystems}/llm-streaming.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/lsp.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/lsp.md (100%)
 rename docs/{core-data-structures => subsystems}/lsp.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/persistence.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/persistence.md (100%)
 rename docs/{core-data-structures => subsystems}/persistence.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/pty.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/pty.md (100%)
 rename docs/{core-data-structures => subsystems}/pty.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/sandbox.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/sandbox.md (100%)
 rename docs/{core-data-structures => subsystems}/sandbox.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/scope.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/scope.md (100%)
 rename docs/{core-data-structures => subsystems}/scope.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/session-query.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/session-query.md (100%)
 rename docs/{core-data-structures => subsystems}/session-query.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/session-reference.i18n.yaml (79%)
 rename docs/{core-data-structures => subsystems}/session-reference.md (100%)
 rename docs/{core-data-structures => subsystems}/session-reference.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/session-title.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/session-title.md (100%)
 rename docs/{core-data-structures => subsystems}/session-title.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/session.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/session.md (100%)
 rename docs/{core-data-structures => subsystems}/session.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/settings.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/settings.md (100%)
 rename docs/{core-data-structures => subsystems}/settings.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/skills.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/skills.md (100%)
 rename docs/{core-data-structures => subsystems}/skills.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/spill.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/spill.md (100%)
 rename docs/{core-data-structures => subsystems}/spill.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/subagent.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/subagent.md (100%)
 rename docs/{core-data-structures => subsystems}/subagent.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/subprocess.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/subprocess.md (100%)
 rename docs/{core-data-structures => subsystems}/subprocess.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/system-prompt.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/system-prompt.md (100%)
 rename docs/{core-data-structures => subsystems}/system-prompt.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/tasks.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/tasks.md (100%)
 rename docs/{core-data-structures => subsystems}/tasks.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/token-meter.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/token-meter.md (100%)
 rename docs/{core-data-structures => subsystems}/token-meter.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/tools.i18n.yaml (80%)
 rename docs/{core-data-structures => subsystems}/tools.md (100%)
 rename docs/{core-data-structures => subsystems}/tools.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/typert.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/typert.md (100%)
 rename docs/{core-data-structures => subsystems}/typert.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/user-interaction.i18n.yaml (79%)
 rename docs/{core-data-structures => subsystems}/user-interaction.md (100%)
 rename docs/{core-data-structures => subsystems}/user-interaction.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/web.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/web.md (100%)
 rename docs/{core-data-structures => subsystems}/web.zh.md (100%)
 rename docs/{core-data-structures => subsystems}/workflow.i18n.yaml (100%)
 rename docs/{core-data-structures => subsystems}/workflow.md (100%)
 rename docs/{core-data-structures => subsystems}/workflow.zh.md (100%)

diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
index e1171d5877..cb9ed4275a 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.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 .agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
-2026-06-20-generic-long-running-tool-runtime.md: cb9d9487cd274696ae20dddab8c6888b4cf4b833
-2026-06-20-generic-long-running-tool-runtime.zh.md: fe5ca223975445991e7fe96376cbfccf432ad241
+2026-06-20-generic-long-running-tool-runtime.md: 90100ea8f146e505c4fbb95760781839bd4bd34a
+2026-06-20-generic-long-running-tool-runtime.zh.md: bdcd8e8fe2a50033177354ce5ce043c4b5264621
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index cb9d9487cd..90100ea8f1 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -23,7 +23,7 @@ Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into in
 
 ## Runtime contract
 
-The literal types live in the [task data-structure catalog](../../../../docs/core-data-structures/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
+The literal types live in the [task data-structure catalog](../../../../docs/subsystems/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
 
 `outputLimitBytes` is producer-owned presentation policy, not a registry buffer. The registry validates and projects it unchanged into `TaskSnapshot`; generic control surfaces apply the cap to complete model-facing output after adding their own status or notice metadata. Omitting it preserves the existing surface behavior, so the runtime does not impose a hidden default on unrelated producer families.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
index fe5ca22397..bdcd8e8fe2 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -23,7 +23,7 @@ Status: implemented
 
 ## 运行时契约
 
-字面类型见[任务数据结构目录](../../../../docs/core-data-structures/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
+字面类型见[任务数据结构目录](../../../../docs/subsystems/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
 
 `outputLimitBytes` 是生产方拥有的呈现策略，而非注册表缓冲区。注册表校验该值，并将其原样投影到 `TaskSnapshot`；通用控制接口添加自身的状态或通知元数据后，再将该上限应用于完整的面向模型输出。省略该值时保持现有接口行为，因此运行时不会向无关的生产方类别施加隐式默认值。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index b6788a47ef..3db3ea7fa4 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.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 .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
-2026-06-21-mandatory-app-attribution-headers.md: ad9d65805c8f0c96bd811b5036310d019760627e
-2026-06-21-mandatory-app-attribution-headers.zh.md: 3021c7fcca00f2e929d997625c303f9a27dbf673
+2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a
+2026-06-21-mandatory-app-attribution-headers.zh.md: cdada9cb235d57ad5cac98ebe0572013cac728ef
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
index ad9d65805c..de9125bc89 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
@@ -51,7 +51,7 @@ Endpoint detection is not part of this Agent Note because no endpoint-specific m
 
 The landed contract:
 
-- `dsh-llm` documents the mandatory `User-Agent` attribution contract for `LlmAdapter` authors (`LlmAdapter` JSDoc, package README, and the adapter-contract section of `docs/core-data-structures/llm-streaming.md`).
+- `dsh-llm` documents the mandatory `User-Agent` attribution contract for `LlmAdapter` authors (`LlmAdapter` JSDoc, package README, and the adapter-contract section of `docs/subsystems/llm-streaming.md`).
 - A shared helper (`attributionHeaders` / `userAgent`) constructs the app identity and the standard `User-Agent` value from package metadata, so adapters do not hand-copy version constants.
 - `dsh-llm-deepseek` sends the shared `User-Agent` on every request and its mock-server suite asserts the exact value.
 - `dsh-llm-pi-ai` sends the same `User-Agent` through pi-ai's `StreamOptions.headers` hook and its mock-server suite asserts the exact value.
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index 3021c7fcca..cdada9cb23 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -51,7 +51,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 已落地的契约：
 
-- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/core-data-structures/llm-streaming.md` 的适配器契约（adapter contract）章节）。
+- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器契约（adapter contract）章节）。
 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。
 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。
 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
index 5dbfcf94ef..459ffa188c 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.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 .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
-2026-06-30-bash-stdin-env-trusted-plugin-surface.md: 556d5dd86dfcc92c4628e68c19390f0033560d25
-2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 325e3d303bdb6836c8928fdae00de59fb954ff37
+2026-06-30-bash-stdin-env-trusted-plugin-surface.md: aa0c785be84bcb8a49f8a2670afa0f6bed6277db
+2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 48108fdd5b8217263590fba336480f1b487e882f
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
index 556d5dd86d..aa0c785be8 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
@@ -30,4 +30,4 @@ Three deliberate choices:
 
 ## Consequences
 
-Hook bridges pass JSON payloads and hook-specific variables through the existing bash seam, retaining its process-group, truncation, and spill behavior. The model surface remains unchanged, and the bash tool remains the sole owner of model-call request construction. The vocabulary lives in [the bash data-structure reference](../../../../docs/core-data-structures/bash.md).
+Hook bridges pass JSON payloads and hook-specific variables through the existing bash seam, retaining its process-group, truncation, and spill behavior. The model surface remains unchanged, and the bash tool remains the sole owner of model-call request construction. The vocabulary lives in [the bash data-structure reference](../../../../docs/subsystems/bash.md).
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
index 325e3d303b..48108fdd5b 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
@@ -30,4 +30,4 @@ Status: implemented
 
 ## 后果
 
-钩子桥接层通过既有的 bash seam 传递 JSON 载荷和钩子特定变量，保留其进程组终止、截断和溢出行为。模型接口面不变，bash 工具仍是模型调用请求构建的唯一所有者。相关词汇定义见 [bash 数据结构参考](../../../../docs/core-data-structures/bash.md)。
+钩子桥接层通过既有的 bash seam 传递 JSON 载荷和钩子特定变量，保留其进程组终止、截断和溢出行为。模型接口面不变，bash 工具仍是模型调用请求构建的唯一所有者。相关词汇定义见 [bash 数据结构参考](../../../../docs/subsystems/bash.md)。
diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
index 233164d4e4..c85bb100aa 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.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 .agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md
-2026-07-15-agent-initiator-scope.md: 69648100e76cfc212469854188d664357fec22f1
-2026-07-15-agent-initiator-scope.zh.md: 505d198ccd2a54af1a15fc1ad6c03b27d217eca0
+2026-07-15-agent-initiator-scope.md: 2f388ae1de3dd6583686e129a03f0cd76701e18d
+2026-07-15-agent-initiator-scope.zh.md: 64f70a4d1c3368d5621edb7251d0b567505affc0
diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md
index 69648100e7..2f388ae1de 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md
@@ -12,7 +12,7 @@ Deep process-local infrastructure sometimes needs a trusted initiating Agent bel
 
 ## Decision
 
-The mandatory `ctx.agents` service uses Node `AsyncLocalStorage` to carry the initiating Agent. It stores the exact `Agent` directly rather than introducing a one-field frame; a separate private run token records nested boundary lineage only for teardown bookkeeping and carries no identity. The [core-data catalog](../../../../docs/core-data-structures/core.md#initiating-agent) identifies the carried type.
+The mandatory `ctx.agents` service uses Node `AsyncLocalStorage` to carry the initiating Agent. It stores the exact `Agent` directly rather than introducing a one-field frame; a separate private run token records nested boundary lineage only for teardown bookkeeping and carries no identity. The [core-data catalog](../../../../docs/subsystems/core.md#initiating-agent) identifies the carried type.
 
 `currentInitiator()` reads optionally, `requireInitiator()` throws `no initiating agent is active`, and `withInitiator(agent, operation)` preserves the operation's exact synchronous value or Promise. `withoutInitiator(operation)` establishes a clearing boundary for work that must not inherit an Agent. Session remains derived as `agent.session`; turn, step, tool call, `signal`, model, `cwd`, sandbox, and authorization stay with their existing owners.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
index 505d198ccd..64f70a4d1c 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
@@ -12,7 +12,7 @@ harness 中存在两种有用但不同的上下文概念。Cordis `Context` 负
 
 ## 决策
 
-必需的 `ctx.agents` 服务使用 Node `AsyncLocalStorage` 携带发起 Agent。它直接存储同一个 `Agent`，不引入只有一个字段的帧；另一个私有运行标记只记录嵌套边界的谱系，供 teardown 记账使用，不携带身份。[核心数据目录](../../../../docs/core-data-structures/core.md#initiating-agent)标明了所携带的类型。
+必需的 `ctx.agents` 服务使用 Node `AsyncLocalStorage` 携带发起 Agent。它直接存储同一个 `Agent`，不引入只有一个字段的帧；另一个私有运行标记只记录嵌套边界的谱系，供 teardown 记账使用，不携带身份。[核心数据目录](../../../../docs/subsystems/core.md#initiating-agent)标明了所携带的类型。
 
 `currentInitiator()` 用于可选读取，`requireInitiator()` 抛出 `no initiating agent is active`，`withInitiator(agent, operation)` 保留操作返回的同步值或 Promise 本身。`withoutInitiator(operation)` 会建立清空边界，供不得继承 Agent 的工作使用。会话仍通过 `agent.session` 推导；轮次、步骤、工具调用、`signal`、模型、`cwd`、沙箱和授权继续由现有归属方管理。
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
index 3be447fe2f..8481cc20d5 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.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 .agents/notes/implemented/feature/2026-06-30-interception-seams.md
-2026-06-30-interception-seams.md: c318e41cfb1d64230b6151f1febad85d75b1451d
-2026-06-30-interception-seams.zh.md: 1b274fae4bc7fde326dbb0eeec54d57f73987803
+2026-06-30-interception-seams.md: 3b2c62cd4413f6d93cef247c51304a8d46753218
+2026-06-30-interception-seams.zh.md: 4e7b6a5ac9ca88919246508cf86c486b06888417
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md b/.agents/notes/implemented/feature/2026-06-30-interception-seams.md
index c318e41cfb..3b2c62cd44 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.md
@@ -56,4 +56,4 @@ The seam package does **not** declare `hook/*` session events (the durable hook-
 
 ## Consequences
 
-The canonical interception surface is uniformly typed without giving every extension the same power: hooks return decisions, execution wrappers wrap, terminal guards only deny, and final observers only observe. The loop owns session-start, pre-step claim settlement, post-tool context buffering, and stopping; `dsh-tools` owns identity sealing and the five-phase execution pipeline. Their contracts are documented in [architecture.md](../../../../docs/architecture.md), package READMEs, [core interception decisions](../../../../docs/core-data-structures/core.md#interception-decisions), and [tool structures](../../../../docs/core-data-structures/tools.md). The ACP bridge settles an initial pre-step rejection from its blocked no-step turn as `end_turn`, while hook-driven snapshots verify the observable bridge behavior end to end.
+The canonical interception surface is uniformly typed without giving every extension the same power: hooks return decisions, execution wrappers wrap, terminal guards only deny, and final observers only observe. The loop owns session-start, pre-step claim settlement, post-tool context buffering, and stopping; `dsh-tools` owns identity sealing and the five-phase execution pipeline. Their contracts are documented in [architecture.md](../../../../docs/architecture.md), package READMEs, [core interception decisions](../../../../docs/subsystems/core.md#interception-decisions), and [tool structures](../../../../docs/subsystems/tools.md). The ACP bridge settles an initial pre-step rejection from its blocked no-step turn as `end_turn`, while hook-driven snapshots verify the observable bridge behavior end to end.
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
index 1b274fae4b..4e7b6a5ac9 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
@@ -56,4 +56,4 @@ seam 包**不**声明 `hook/*` 会话事件（持久的钩子调用日志）；
 
 ## 后果
 
-规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/core-data-structures/core.md#interception-decisions) 与[工具结构](../../../../docs/core-data-structures/tools.md)中。ACP 桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
+规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP 桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
index 15054d6ba1..394af669cd 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.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 .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
-2026-07-05-dynamic-workflows.md: bba62098c66477a3f1929f9029e81c645bfc4d41
-2026-07-05-dynamic-workflows.zh.md: 2005ca14883ae137148541273900c7f3e65769a5
+2026-07-05-dynamic-workflows.md: b0fb2349e64093beab8220ea75715b55903772e3
+2026-07-05-dynamic-workflows.zh.md: 246727649be8acc17dac1335d353e9b1591e3890
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
index bba62098c6..b0fb2349e6 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
@@ -20,7 +20,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre
 
 ### The seam (dsh-workflow)
 
-`ctx.workflows` is an abstract `WorkflowService` in the bash shape — one engine per context, no named-provider registry (engines are deployment swaps, not co-residents). `start(request)` throws synchronously for a script that cannot begin; a returned `WorkflowRun`'s `result` NEVER rejects (failures resolve as `stopReason: 'error' | 'cancelled'`). The `workflow/*` events are observe-only emits carrying DATA SNAPSHOTS (id + meta; `workflow/end` omits the result value), per-listener contained, mirroring `subagent/start`/`subagent/end` — control stays with the run's holder. Vocabulary details: [core-data-structures/workflow.md](../../../../docs/core-data-structures/workflow.md).
+`ctx.workflows` is an abstract `WorkflowService` in the bash shape — one engine per context, no named-provider registry (engines are deployment swaps, not co-residents). `start(request)` throws synchronously for a script that cannot begin; a returned `WorkflowRun`'s `result` NEVER rejects (failures resolve as `stopReason: 'error' | 'cancelled'`). The `workflow/*` events are observe-only emits carrying DATA SNAPSHOTS (id + meta; `workflow/end` omits the result value), per-listener contained, mirroring `subagent/start`/`subagent/end` — control stays with the run's holder. Vocabulary details: [subsystems/workflow.md](../../../../docs/subsystems/workflow.md).
 
 ### The engine (dsh-workflow-workerthread): one worker thread per run
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
index 2005ca1488..246727649b 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
@@ -20,7 +20,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 ### seam（dsh-workflow）
 
-`ctx.workflows` 是 bash 形态的抽象 `WorkflowService`——每个上下文一个引擎，无命名提供方注册表（引擎是部署级替换，不是共存者）。`start(request)` 对无法启动的脚本同步抛出；返回的 `WorkflowRun` 的 `result` 永不 reject（失败时结算为 `stopReason: 'error' | 'cancelled'`）。`workflow/*` 事件是仅观察的 emit，携带数据快照（id + meta；`workflow/end` 省略 result 值），按监听器隔离，与 `subagent/start`/`subagent/end` 对称——控制权留在 run 的持有者手中。词汇详情见 [core-data-structures/workflow.md](../../../../docs/core-data-structures/workflow.md)。
+`ctx.workflows` 是 bash 形态的抽象 `WorkflowService`——每个上下文一个引擎，无命名提供方注册表（引擎是部署级替换，不是共存者）。`start(request)` 对无法启动的脚本同步抛出；返回的 `WorkflowRun` 的 `result` 永不 reject（失败时结算为 `stopReason: 'error' | 'cancelled'`）。`workflow/*` 事件是仅观察的 emit，携带数据快照（id + meta；`workflow/end` 省略 result 值），按监听器隔离，与 `subagent/start`/`subagent/end` 对称——控制权留在 run 的持有者手中。词汇详情见 [subsystems/workflow.md](../../../../docs/subsystems/workflow.md)。
 
 ### 引擎（dsh-workflow-workerthread）：每次运行一个 worker 线程
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index a98beff699..6fff14bc85 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.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 .agents/notes/implemented/feature/2026-07-05-skill-system.md
-2026-07-05-skill-system.md: a998d70ec934aed4bf7ce32aa711abd47b508a1d
-2026-07-05-skill-system.zh.md: 4fa7c4fd657c2f41f16b30679ec95e61a75f8a0c
+2026-07-05-skill-system.md: bb7c03a64a3d0d0f700e21bc96633f1c3ea181b9
+2026-07-05-skill-system.zh.md: 8e26e52d3366505a958dd4b19461edf8bf740b00
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
index a998d70ec9..bb7c03a64a 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
@@ -28,7 +28,7 @@ Local skill filesystem I/O goes through `ctx.fs` when a filesystem service is lo
 
 The registry's `list()` returns every winning summary, while model and user consumers apply the invocation predicates owned by the [independent invocation-policy decision](2026-07-28-skill-invocation-policy.md). The `skill({ name })` tool loads one model-invocable skill for the current agent cwd and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` supplies a directory, URL, or opaque provider-managed base for explicitly referenced scripts, references, and assets; resources load only as needed, without directory enumeration. An unresolved name reports that the skill is unknown or no longer available; invalid names and skills with `invocation.modelInvocable: false` retain distinct tool errors. The tool result is the model-visible disclosure path.
 
-The data structures and catalog/tool contract are documented in [skills.md](../../../../docs/core-data-structures/skills.md), with service signatures in the generated [services catalog](../../../../docs/cordis-catalog/services.md).
+The data structures and catalog/tool contract are documented in [skills.md](../../../../docs/subsystems/skills.md), with service signatures in the generated [services catalog](../../../../docs/cordis-catalog/services.md).
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 4fa7c4fd65..8e26e52d33 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -28,7 +28,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
 
-数据结构与目录/工具契约记录在 [skills.md](../../../../docs/core-data-structures/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/cordis-catalog/services.md)。
+数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/cordis-catalog/services.md)。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 7294f47357..00f475040c 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: 583b388815cd9b2b9cf94ce393839169ce3ffac3
-2026-07-06-sandbox.zh.md: e435b671a42ca5c3ea4f6800bf91d6e006da35d3
+2026-07-06-sandbox.md: 06c5590454a6947030d828f087b92f44207dad6e
+2026-07-06-sandbox.zh.md: 8f575e3cd14973aaaaf9254337b985110bc99d6b
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index 583b388815..06c5590454 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -200,7 +200,7 @@ Costs and accepted limits:
 In-repo precedents this design copies or contrasts with:
 
 - [The capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md) — the interface/implementation/consumer split and the "don't split preemptively" timing rule the second consumer satisfied.
-- The `dsh-bash` request/spec split ([the bash vocabulary catalog](../../../../docs/core-data-structures/bash.md)) — the complete `sandboxPolicy` rides its per-call carrier, and the explicit-`resolve()` defaulting convention.
+- The `dsh-bash` request/spec split ([the bash vocabulary catalog](../../../../docs/subsystems/bash.md)) — the complete `sandboxPolicy` rides its per-call carrier, and the explicit-`resolve()` defaulting convention.
 - [The approval seam Agent Note](2026-07-06-approval-seam.md) — the channel escalation asks through; its answerer waterfall, audit pair, and one-package rationale are recorded there.
 - [Event-sourced sessions](../architecture/2026-06-11-event-sourced-sessions.md) and [standalone log-only events](../simplification/2026-07-28-remove-synthetic-log-only-turns.md) — the log-as-store foundation the per-session modes fold over, and the explicit durability boundary the anchoring design obeys.
 - [The interception-seams Agent Note](2026-06-30-interception-seams.md) — the `tools/pre-execute` vocabulary the escalation gate deliberately does not reuse (an escalating call has no pre-execute moment of its own).
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index e435b671a4..8f575e3cd1 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -200,7 +200,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 本设计复制或对比的仓库内先例：
 
 - [能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)——接口/实现/消费方拆分与「不要过早拆分」的时机规则（第二个消费方满足了该规则）。
-- `dsh-bash` 的 request/spec 拆分（[bash 词汇目录](../../../../docs/core-data-structures/bash.md)）——完整的 `sandboxPolicy` 搭载其按调用载体，以及显式 `resolve()` 默认约定。
+- `dsh-bash` 的 request/spec 拆分（[bash 词汇目录](../../../../docs/subsystems/bash.md)）——完整的 `sandboxPolicy` 搭载其按调用载体，以及显式 `resolve()` 默认约定。
 - [批准 seam Agent Note](2026-07-06-approval-seam.md)——升级请求通过的通道；其应答器 waterfall（瀑布式事件）、审计对和单包理由记录在那里。
 - [事件溯源会话](../architecture/2026-06-11-event-sourced-sessions.md)与[独立纯日志事件](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)——按会话模式 fold 所依赖的日志即存储基础，以及锚定设计遵守的显式持久性边界。
 - [拦截 seam Agent Note](2026-06-30-interception-seams.md)——`tools/pre-execute` 词汇，升级门控刻意不复用它（升级调用没有自己的 pre-execute 时刻）。
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
index 3119d28d71..6462a2c873 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.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 .agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
-2026-07-10-parallel-tool-call-execution.md: 19f5dc189821433052edfa72613980a2e94e2cae
-2026-07-10-parallel-tool-call-execution.zh.md: 69bff90c11fa132ded325ef610dabf5c609f21af
+2026-07-10-parallel-tool-call-execution.md: 7fd540539fd358b3254470f420a0cc11f2927d45
+2026-07-10-parallel-tool-call-execution.zh.md: 985557974c79d4080c4e35ccbb9740439988261a
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
index 19f5dc1898..7fd540539f 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
@@ -14,7 +14,7 @@ The session log remains authoritative: every started call has an audit event, or
 
 ## Decision
 
-Each tool may provide an optional `isConcurrencySafe(args)` classifier. It is synchronous and pure: it examines only the current call's parsed arguments and performs no I/O or mutation. Only an explicit `true` opts in; a missing classifier, invalid arguments, a thrown classifier, or any other return value makes the call exclusive. The canonical type contract lives in the [tool data structures](../../../../docs/core-data-structures/tools.md).
+Each tool may provide an optional `isConcurrencySafe(args)` classifier. It is synchronous and pure: it examines only the current call's parsed arguments and performs no I/O or mutation. Only an explicit `true` opts in; a missing classifier, invalid arguments, a thrown classifier, or any other return value makes the call exclusive. The canonical type contract lives in the [tool data structures](../../../../docs/subsystems/tools.md).
 
 The classifier is deliberately unary. Returning `true` is the tool's promise that this call may overlap with any sibling call that also returns `true`; the scheduler does not compare calls or prove that their resource accesses are compatible.
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
index 69bff90c11..985557974c 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-每个工具都可以提供可选的 `isConcurrencySafe(args)` 分类器。该分类器必须是同步纯函数：它只检查当前调用已解析的参数，不执行 I/O 或任何变更。只有显式返回 `true` 才表示选择并行；分类器缺失、参数无效、分类器抛错或返回任何其他值，都会使该调用按独占方式执行。规范类型契约见[工具数据结构](../../../../docs/core-data-structures/tools.md)。
+每个工具都可以提供可选的 `isConcurrencySafe(args)` 分类器。该分类器必须是同步纯函数：它只检查当前调用已解析的参数，不执行 I/O 或任何变更。只有显式返回 `true` 才表示选择并行；分类器缺失、参数无效、分类器抛错或返回任何其他值，都会使该调用按独占方式执行。规范类型契约见[工具数据结构](../../../../docs/subsystems/tools.md)。
 
 分类器有意设计为一元函数。返回 `true` 表示工具承诺：此调用可以与任何同样返回 `true` 的并列调用重叠执行。调度器不会比较调用，也不会证明它们的资源访问相容。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
index 66ac99d37c..e6ca4048fd 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.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 .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
-2026-07-31-code-mode-language-dispatch.md: 96001252d6494d058a8df9974fb5a0d59e7d7112
-2026-07-31-code-mode-language-dispatch.zh.md: aa7eb2a6b4b9117f1d707b37afcdbe12b814bad2
+2026-07-31-code-mode-language-dispatch.md: 71e4fd5a30e90ac66132dbdcea16917bacc80b68
+2026-07-31-code-mode-language-dispatch.zh.md: 1dbb3d889d28669575980d3a667e4f168a5d72db
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
index 96001252d6..71e4fd5a30 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
@@ -17,7 +17,7 @@ Language selection is a lookup on `ctx.codeRuntime.language`, resolved lazily at
 - `SDK_RENDERERS` (index.ts) maps a language to its `tools:sdk` renderer — `typescript → renderToolsSdk`, `python → renderToolsSdkPy`. The `tools:sdk` section reads the loaded runtime's language and picks the renderer; `requireCodeRuntime` rejects a `mode: code`/`both` runtime whose language is absent from the table, naming the known languages.
 - `RUN_CODE_FLAVORS` (code-mode.ts) maps a language to its two model-facing `run_code` strings (tool `description` and the `code` parameter description), so a language's SDK section and its transport schema always agree.
 
-Both tables are read with `Object.hasOwn` before use so a language named `toString`/`constructor` cannot resolve an inherited `Object.prototype` member as a renderer. The two guards differ in reachability: `SDK_RENDERERS`' in-callback guard is unreachable because `requireCodeRuntime` validated the same `const` table earlier in the same callback (it carries a `/* v8 ignore */`), while `RUN_CODE_FLAVORS`' guard is the primary, publicly reachable rejection — any language absent from the flavor table hits it through `run_code`'s language-aware getters, which the public `schemas()` reaches without passing `requireCodeRuntime` first; the test reads one of those getters off the definition directly, under a language absent from both tables. A language present in `SDK_RENDERERS` but not `RUN_CODE_FLAVORS` is drift the shared `CodeSdkLanguage` `satisfies` pins reject at `typecheck`, so it is not an input either guard can see; what the guards still own is a mounted runtime reporting a language absent from both tables. Schema emission reads the runtime through `peekRuntime()` rather than `requireRuntime()`: `undefined` (no runtime mounted, reached by definition readers and `schemas()`, of which the doc-catalog harvest is the only shipped one and none of which feeds a model because assembly passes `requireCodeRuntime` first) degrades to the TypeScript flavor, whereas a mounted unknown language fails loud — this is NOT the silent fallback rejected below, which concerns emitting a wrong-language SDK for a real runtime. Adding a backend language is three parallel edits — a `CodeSdkLanguage` member and the two table entries — plus its renderer and the prose that names the well-known values instead of deriving them (the seam's `dsh-code-runtime` README pair, its `CodeRuntime.language` JSDoc, and the `docs/core-data-structures/code-runtime.md` pair; this package's own README pair and its `Config.mode` JSDoc — no gate checks any of it), with no `agent-loop` or registry-structure change.
+Both tables are read with `Object.hasOwn` before use so a language named `toString`/`constructor` cannot resolve an inherited `Object.prototype` member as a renderer. The two guards differ in reachability: `SDK_RENDERERS`' in-callback guard is unreachable because `requireCodeRuntime` validated the same `const` table earlier in the same callback (it carries a `/* v8 ignore */`), while `RUN_CODE_FLAVORS`' guard is the primary, publicly reachable rejection — any language absent from the flavor table hits it through `run_code`'s language-aware getters, which the public `schemas()` reaches without passing `requireCodeRuntime` first; the test reads one of those getters off the definition directly, under a language absent from both tables. A language present in `SDK_RENDERERS` but not `RUN_CODE_FLAVORS` is drift the shared `CodeSdkLanguage` `satisfies` pins reject at `typecheck`, so it is not an input either guard can see; what the guards still own is a mounted runtime reporting a language absent from both tables. Schema emission reads the runtime through `peekRuntime()` rather than `requireRuntime()`: `undefined` (no runtime mounted, reached by definition readers and `schemas()`, of which the doc-catalog harvest is the only shipped one and none of which feeds a model because assembly passes `requireCodeRuntime` first) degrades to the TypeScript flavor, whereas a mounted unknown language fails loud — this is NOT the silent fallback rejected below, which concerns emitting a wrong-language SDK for a real runtime. Adding a backend language is three parallel edits — a `CodeSdkLanguage` member and the two table entries — plus its renderer and the prose that names the well-known values instead of deriving them (the seam's `dsh-code-runtime` README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair; this package's own README pair and its `Config.mode` JSDoc — no gate checks any of it), with no `agent-loop` or registry-structure change.
 
 `code-mode.ts` depends only on the runtime seam (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer therefore lands independently of the protocol and backend PRs — it needs only the seam's `language` field, which is already on master.
 
@@ -37,7 +37,7 @@ The standard that cap serves is grammatical validity, and the boundary is delibe
 
 ## Consequences
 
-Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/core-data-structures/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the interface package must not import its consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the seam would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend.
+Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the interface package must not import its consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the seam would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend.
 
 The cost is that the Python branch of both tables is unreachable on this base: `CodeRuntime.language` is set by the loaded backend, the only published backend is `dsh-code-runtime-worker` (`'typescript'`), and the registry reads the loaded runtime rather than a config field, so no assembled application can select `renderToolsSdkPy` or `PYTHON_FLAVOR`. The model-visible surface is therefore unchanged by this note's work until a backend reporting `'python'` is published, and this PR's coverage is unit-level — the renderer output plus the dispatch and rejection paths. The keyless snapshot for the Python model interface belongs to the PR that publishes that backend, because only there does a real `cordis.yml` over published plugins produce a Python assembly; a snapshot example that mounted a fixture runtime here would assert against a test double, which [docs/testing.md](../../../../docs/testing.md) rejects as a substitute for the assembled application transcript.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
index aa7eb2a6b4..1dbb3d889d 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
@@ -17,7 +17,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 - `SDK_RENDERERS`（index.ts）把语言映射到它的 `tools:sdk` 渲染器——`typescript → renderToolsSdk`、`python → renderToolsSdkPy`。`tools:sdk` 段读取所加载运行时的语言并选出渲染器；`requireCodeRuntime` 拒绝其语言不在表中的 `mode: code`/`both` 运行时，并列出已知语言。
 - `RUN_CODE_FLAVORS`（code-mode.ts）把语言映射到它那两条面向模型的 `run_code` 字符串（工具 `description` 与 `code` 参数描述），使一种语言的 SDK 段与它的传输 schema 始终一致。
 
-两张表在使用前都以 `Object.hasOwn` 读取，这样名为 `toString`/`constructor` 的语言不会把继承自 `Object.prototype` 的成员解析成渲染器。两个守卫的可达性不同：`SDK_RENDERERS` 的段内守卫不可达，因为 `requireCodeRuntime` 已在同一回调更早处校验过同一张 `const` 表（它带 `/* v8 ignore */`）；而 `RUN_CODE_FLAVORS` 的守卫是主要的、可公开到达的拒绝路径——任何缺席 flavor 表的语言都经 `run_code` 的语言感知 getter 到达它，而公共 `schemas()` 抵达那些 getter 时并未先过 `requireCodeRuntime`；测试直读 definition 上的其中一个 getter，用的是对两张表都缺席的语言。「在 `SDK_RENDERERS` 里却不在 `RUN_CODE_FLAVORS` 里」这种漂移已由共享的 `CodeSdkLanguage` `satisfies` 在 `typecheck` 处拒绝，两个守卫都看不到这种输入；它们如今负责的是所挂载运行时报告了一门两张表都缺席的语言。schema 发射通过 `peekRuntime()` 而非 `requireRuntime()` 读取运行时：`undefined`（无运行时，由直读 definition 的读者与 `schemas()` 到达，其中 doc-catalog 采集是唯一已交付的一个，而它们都不会喂给模型，因为组装路径先过 `requireCodeRuntime`）降级到 TypeScript flavor，而挂载了未知语言则 fail loud——这不是下方被否决的静默回退，那指的是为真实运行时发出错误语言的 SDK。新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员加两条表项——再加它的渲染器，以及点名已知值而非从中派生的散文（seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/core-data-structures/code-runtime.md` 双语对；本包自己的 README 双语对与它的 `Config.mode` JSDoc，无任何 gate 检查其中任何一处），不动 `agent-loop`，也不动注册表结构。
+两张表在使用前都以 `Object.hasOwn` 读取，这样名为 `toString`/`constructor` 的语言不会把继承自 `Object.prototype` 的成员解析成渲染器。两个守卫的可达性不同：`SDK_RENDERERS` 的段内守卫不可达，因为 `requireCodeRuntime` 已在同一回调更早处校验过同一张 `const` 表（它带 `/* v8 ignore */`）；而 `RUN_CODE_FLAVORS` 的守卫是主要的、可公开到达的拒绝路径——任何缺席 flavor 表的语言都经 `run_code` 的语言感知 getter 到达它，而公共 `schemas()` 抵达那些 getter 时并未先过 `requireCodeRuntime`；测试直读 definition 上的其中一个 getter，用的是对两张表都缺席的语言。「在 `SDK_RENDERERS` 里却不在 `RUN_CODE_FLAVORS` 里」这种漂移已由共享的 `CodeSdkLanguage` `satisfies` 在 `typecheck` 处拒绝，两个守卫都看不到这种输入；它们如今负责的是所挂载运行时报告了一门两张表都缺席的语言。schema 发射通过 `peekRuntime()` 而非 `requireRuntime()` 读取运行时：`undefined`（无运行时，由直读 definition 的读者与 `schemas()` 到达，其中 doc-catalog 采集是唯一已交付的一个，而它们都不会喂给模型，因为组装路径先过 `requireCodeRuntime`）降级到 TypeScript flavor，而挂载了未知语言则 fail loud——这不是下方被否决的静默回退，那指的是为真实运行时发出错误语言的 SDK。新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员加两条表项——再加它的渲染器，以及点名已知值而非从中派生的散文（seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对；本包自己的 README 双语对与它的 `Config.mode` JSDoc，无任何 gate 检查其中任何一处），不动 `agent-loop`，也不动注册表结构。
 
 `code-mode.ts` 只依赖运行时 seam（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于协议和后端 PR 落地——它只需要 seam 的 `language` 字段，而该字段已在 master 上。
 
@@ -37,7 +37,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 ## Consequences
 
-新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在消费方的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/core-data-structures/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：接口包不得 import 其消费方的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 seam 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
+新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在消费方的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：接口包不得 import 其消费方的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 seam 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
 
 代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 4acabc8700..13c54fa458 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 7ee1e0ac3df7cb37fc9797702d44f409da820a94
-2026-06-20-core-data-structures-catalog.zh.md: 7cb0ae216f5c5f429c18d097862350997a8335d3
+2026-06-20-core-data-structures-catalog.md: 57433fdcb3c77976c4ba0cfe7d157f94dff331dd
+2026-06-20-core-data-structures-catalog.zh.md: 3956839c8211e294280805d9b6993e5607bfe04f
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 7ee1e0ac3d..57433fdcb3 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -1,4 +1,4 @@
-# Agent Note: Core-data-structures catalog and the `ts type-equiv` drift gate
+# Agent Note: Subsystems catalog and the `ts type-equiv` drift gate
 
 Status: implemented
 
@@ -12,7 +12,7 @@ So the work had two intertwined questions: **what belongs in such a catalog** (t
 
 ## Decision
 
-A new `docs/core-data-structures/` folder catalogs the vocabulary, with a new `verify-type-equiv` doc-sync gate that keeps every pasted type declaration and its JSDoc synchronized with source.
+A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type-equiv` doc-sync gate that keeps every pasted type declaration and its JSDoc synchronized with source.
 
 ### What counts as "core" — the spine-vs-seam line
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 7cb0ae216f..3956839c82 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-新增的 `docs/core-data-structures/` 目录对这些词汇编目，并配有新的 `verify-type-equiv` doc-sync（文档同步门禁），使每个粘贴的类型声明及其 JSDoc 与源码保持同步。
+新增的 `docs/subsystems/` 目录对这些词汇编目，并配有新的 `verify-type-equiv` doc-sync（文档同步门禁），使每个粘贴的类型声明及其 JSDoc 与源码保持同步。
 
 ### 何为「核心」——主干与 seam 的分界线
 
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
index 70d56bbca5..5ef82c77de 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.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 .agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
-2026-06-22-fork-child-replay-seed-boundary.md: ed3ec095bc14128f5ebc0a9188bc022ef97b1c8b
-2026-06-22-fork-child-replay-seed-boundary.zh.md: 1d938cbf6c9c32a144d58fed48e552d85aa9c625
+2026-06-22-fork-child-replay-seed-boundary.md: 27db3b768f2503121b0bc8912f9bc0fecb00a10d
+2026-06-22-fork-child-replay-seed-boundary.zh.md: f64fc55fc63e2caa4b50112407b645e6e7f12b0f
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
index ed3ec095bc..27db3b768f 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
@@ -44,6 +44,6 @@ This closes the routing correctness gap, and two recorded fork scenarios exercis
 
 ## Consequences
 
-- A new persisted header field across core + both backends; the core-data-structures catalog (`persistence.md`) is updated in the same change (its `SessionHeader` / `CreateSessionOptions` `type-equiv` blocks).
+- A new persisted header field across core + both backends; the subsystems catalog (`persistence.md`) is updated in the same change (its `SessionHeader` / `CreateSessionOptions` `type-equiv` blocks).
 - Existing SQLite databases at schema v2 are rejected on open (no user data pre-release).
 - Spawn replay is unchanged (`seedLength` 0). Fork replay now routes a child to its own script; covered by a regression in `llm-replay`'s tests (a child fixture whose seeded prefix carries a parent chunk — the derived child script must exclude it, proven red without the slice) and a persistence round-trip test (both backends, via the shared coordinator contract).
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
index 1d938cbf6c..f64fc55fc6 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
@@ -44,6 +44,6 @@ subagent 脚本由 [`deriveReplayScript`](../../../../packages/support/llm-repla
 
 ## 后果
 
-- core 与两个后端新增一个持久化 header 字段；核心数据结构目录（`persistence.md`）在同一变更中更新（其 `SessionHeader` / `CreateSessionOptions` 的 `type-equiv` 块）。
+- core 与两个后端新增一个持久化 header 字段；子系统目录（`persistence.md`）在同一变更中更新（其 `SessionHeader` / `CreateSessionOptions` 的 `type-equiv` 块）。
 - 既有的 schema v2 SQLite 数据库在打开时被拒绝（预发布阶段无用户数据）。
 - spawn 回放不变（`seedLength` 为 0）。fork 回放现在将子会话路由到自身的脚本；由 `llm-replay` 测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的分片——推导出的子会话脚本必须排除它，不做 slice 时该用例为红）以及一个持久化往返测试（两个后端，通过共享的 coordinator 契约）。
diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md
index f933beb86b..81f63fac2f 100644
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -21,7 +21,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
 
 1. **New prose receives semantic review.** Use [dsh-prose-standard](../dsh-prose-standard/SKILL.md) to critically review every added or changed Markdown passage, JSDoc, comment, prompt, description, diagnostic, and visible string. Verify required coverage, accuracy, placement, and editorial quality against the owning code or behavior; automated checks do not establish those properties.
 2. **Docs match the code.** Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home.
-3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [core-data-structures](../../../docs/core-data-structures/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
+3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [subsystems](../../../docs/subsystems/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
 4. **Registrations clean up.** Verify each new registry contribution satisfies the disposal-test contract in [packages/AGENTS.md](../../../packages/AGENTS.md).
 5. **Invariant companions are semantic.** For every touched `./invariant`, require an owner event-stream or mutable-data relationship at its authoritative boundary; service or method presence, plugin metadata or effects, and fixed pure examples belong in type, load, or unit tests. Accept an empty installer when its package-specific reason establishes that no plausible runtime relationship exists; do not demand an invented check merely to eliminate emptiness ([repository rule](../../../AGENTS.md#conventions); [package contract](../../../packages/AGENTS.md)).
 6. **Required evidence exists.** Verify the author ran the [relevant local checks](../../../AGENTS.md#run-relevant-checks-locally) for the diff and that CI covers the exhaustive matrix; review the semantic gaps neither can detect.
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index cd4e8aaaa5..3bbd4f330d 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -21,7 +21,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
 | [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ core-data-structures), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
-| [core-data-structures/](core-data-structures/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) |
+| [subsystems/](subsystems/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) |
 | [Agent Notes](../.agents/notes/README.md) | Decision records under their own lifecycle contract | Migration plans, checklists, and spec-speak once implemented; archived notes are frozen history |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
 | [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
@@ -37,7 +37,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The [core-data-structures catalog](core-data-structures/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](core-data-structures/core.md#what-counts-as-core)).
+- **The [core-data-structures catalog](subsystems/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
 - Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams".
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 76491a37fe..15a6ba3fb5 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: cee159452fc536c98a006cfa3ea92e9d21a1e77b
-architecture.zh.md: cf10e60a5d5e4fe3f39d72bef3d48fe7c2f3c105
+architecture.md: 7baf550128fe83528ce12bf2f9b40cfc8f78e322
+architecture.zh.md: 076edd0549fb7f648a7a1b06d7027a1e6eca735f
diff --git a/docs/architecture.md b/docs/architecture.md
index cee159452f..7baf550128 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -123,7 +123,7 @@ Adapter selection, dispatch, and iteration failures become terminal error or abo
 
 Other failures use `agent/error`; cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels capability preparation; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` reports its cause before clearing and aborting; idle calls emit nothing. Waking input that lands after the abort fires but before convergence runs at the driver's convergence boundary, while a `disposed` cancel leaves it parked ([cancel-convergence wake latch](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)). Durability distinguishes `aborted` cancellation from `disposed` teardown, which awaits quiescence ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)).
 
-Turn and step events are turn-enclosed; the loop appends `user/message` events only from entered batches inside a turn. A turn opens before the initial claim and pre-step, so rejection, empty input, cancellation, or failure closes a durable turn without any step events. Standalone `compact/* { turn: null }` events consume no turn, and their lock-time markers may interleave with inbox splices. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap).
+Turn and step events are turn-enclosed; the loop appends `user/message` events only from entered batches inside a turn. A turn opens before the initial claim and pre-step, so rejection, empty input, cancellation, or failure closes a durable turn without any step events. Standalone `compact/* { turn: null }` events consume no turn, and their lock-time markers may interleave with inbox splices. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](subsystems/session.md#why-a-turn-ended-turnendreasonmap).
 
 ### Agent Handles
 
@@ -147,9 +147,9 @@ Between turns, owners append log-only events through `Session`, flushing only fo
 
 ### Model Content
 
-Messages use typed blocks from merge-extensible `ContentBlockMap`; the pattern also types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New blocks coordinate adapters, UI, compaction, token metering, and persistence; replay measurements live in [token-meter.md](core-data-structures/token-meter.md).
+Messages use typed blocks from merge-extensible `ContentBlockMap`; the pattern also types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New blocks coordinate adapters, UI, compaction, token metering, and persistence; replay measurements live in [token-meter.md](subsystems/token-meter.md).
 
-Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, successful provenance, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract](core-data-structures/llm-streaming.md)).
+Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, successful provenance, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract](subsystems/llm-streaming.md)).
 
 ## Extension And Composition
 
@@ -157,7 +157,7 @@ Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is on
 
 Capabilities separate **interface / implementation / consumer** layers. Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks. See the [capability graph](capability-seams.md).
 
-Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](core-data-structures/subagent.md)).
+Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](subsystems/subagent.md)).
 
 `dsh-workspace-context` composes its baseline on the first `agent/pre-step` and folds it into the final entering batch right after the claimed prompt, so it reaches the first request with the direct prompt; rejection keeps it in the next-step inbox. When compaction removes that baseline from the visible surface, the next entering pre-step composes the current baseline and carries it in the same request. Filesystem changes projected after tools are likewise folded into the next entering pre-step instead of creating a later context-only step ([decision](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)). `dsh-paths` owns shared paths.
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index cf10e60a5d..076edd0549 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -123,7 +123,7 @@ idle inject:
 
 其他故障使用 `agent/error`；取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消功能准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。abort 触发后、收敛前到达的唤醒输入会在 driver 的收敛边界执行，而 `disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。持久化层以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
 
-轮次和步骤事件均位于轮次边界内；loop 只会在轮次内从进入步骤的批次追加 `user/message`。轮次会在首次领取与 pre-step 之前打开，因此拒绝、空输入、取消或失败会关闭一个不包含任何步骤事件的持久轮次。独立的 `compact/* { turn: null }` 事件不占用轮次，其锁定时刻标记可以与 inbox splice 交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap)。
+轮次和步骤事件均位于轮次边界内；loop 只会在轮次内从进入步骤的批次追加 `user/message`。轮次会在首次领取与 pre-step 之前打开，因此拒绝、空输入、取消或失败会关闭一个不包含任何步骤事件的持久轮次。独立的 `compact/* { turn: null }` 事件不占用轮次，其锁定时刻标记可以与 inbox splice 交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](subsystems/session.md#why-a-turn-ended-turnendreasonmap)。
 
 ### Agent 句柄
 
@@ -147,9 +147,9 @@ idle inject:
 
 ### 模型内容
 
-消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](core-data-structures/token-meter.md)。
+消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](subsystems/token-meter.md)。
 
-流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[契约](core-data-structures/llm-streaming.md)）。
+流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[契约](subsystems/llm-streaming.md)）。
 
 ## 扩展与组合
 
@@ -157,7 +157,7 @@ idle inject:
 
 能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[功能图](capability-seams.md)。
 
-例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](core-data-structures/subagent.md)）。
+例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。
 
 `dsh-workspace-context` 在第一次 `agent/pre-step` 组合基线并将它折入最终进入的批次、紧随已领取的直接提示词之后，使其与直接提示词一同抵达第一次请求；reject 则将它留在 next-step inbox。当压缩从可见表层移除该基线时，下一次进入步骤的 pre-step 会组合当前基线，并在同一请求中携带它。工具执行后投影的文件系统变更也会折入下一次进入步骤的 pre-step，而不会另外创建稍后的纯上下文步骤（[决策](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)）。`dsh-paths` 负责共享路径。
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 254d85ccd1..850f4731e2 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -3,7 +3,7 @@
 
 # Plugin Config Catalog
 
-Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md) documents the types these declarations reference.
+Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.
 
 This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.
 
@@ -106,7 +106,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`AgentOptions`](core-data-structures/core.md) · [`SessionId`](core-data-structures/core.md)
+Depends on: [`AgentOptions`](subsystems/core.md) · [`SessionId`](subsystems/core.md)
 
 Source: [`packages/core/agent-loop/src/index.ts:236`](../packages/core/agent-loop/src/index.ts)
 
@@ -1044,7 +1044,7 @@ export interface PresetSpec {
 }
 ```
 
-Depends on: [`ApprovalPolicy`](core-data-structures/approval.md) · [`SandboxMode`](core-data-structures/sandbox.md)
+Depends on: [`ApprovalPolicy`](subsystems/approval.md) · [`SandboxMode`](subsystems/sandbox.md)
 
 Source: [`packages/interaction/permission/src/index.ts:140`](../packages/interaction/permission/src/index.ts)
 
@@ -1234,7 +1234,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`SandboxMode`](core-data-structures/sandbox.md)
+Depends on: [`SandboxMode`](subsystems/sandbox.md)
 
 Source: [`packages/sandbox/sandbox-policy/src/index.ts:67`](../packages/sandbox/sandbox-policy/src/index.ts)
 
@@ -2193,7 +2193,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`AgentOptions`](core-data-structures/core.md)
+Depends on: [`AgentOptions`](subsystems/core.md)
 
 Source: [`packages/subagent/tool-subagent/src/index.ts:25`](../packages/subagent/tool-subagent/src/index.ts)
 
@@ -2212,7 +2212,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`SubagentReportDelivery`](core-data-structures/subagent.md)
+Depends on: [`SubagentReportDelivery`](subsystems/subagent.md)
 
 Source: [`packages/subagent/tool-subagent-report/src/index.ts:22`](../packages/subagent/tool-subagent-report/src/index.ts)
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 2c99c451d2..dd9cf5bfa5 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -3,7 +3,7 @@
 
 # Cordis Events Catalog
 
-Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around.
+Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.
 
 This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
 
@@ -31,7 +31,7 @@ A fully configured agent and live session were published. Setup is composition-o
 'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
 
@@ -51,7 +51,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
 'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
 
@@ -73,7 +73,7 @@ A step or turn errored. The machine reports a failure here even when the error h
 'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
@@ -95,7 +95,7 @@ One message left the inbox inside its open turn. If the proposed step is rejecte
 'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
 
 Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
@@ -114,7 +114,7 @@ One message was discarded from the live inbox.
 'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
@@ -133,7 +133,7 @@ One message entered the live inbox.
 'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
 
 Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
@@ -156,7 +156,7 @@ Reject a proposed step or replace the messages that enter it. Calling `next()` p
 'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [PreStepDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
+Types: [Agent](../subsystems/core.md) · [PreStepDecision](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
 
 Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
 
@@ -180,7 +180,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach
 'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [LlmCallConfig](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
 
@@ -207,7 +207,7 @@ Handle one failed model-request attempt before the loop retries or closes its st
 'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestErrorAction](../core-data-structures/core.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [LlmFailure](../subsystems/llm-streaming.md) · [RequestErrorAction](../subsystems/core.md) · [ResolvedRetryPolicy](../subsystems/llm-streaming.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
 
@@ -229,7 +229,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [SessionStartSource](../subsystems/core.md)
 
 Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
 
@@ -250,7 +250,7 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running`
 'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [AgentStatus](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
 
@@ -279,7 +279,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f
 'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
 
@@ -302,7 +302,7 @@ A declarative agent entry failed before it could publish a live agent. Consumers
 'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
 ```
 
-Types: [SessionId](../core-data-structures/core.md)
+Types: [SessionId](../subsystems/core.md)
 
 Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
 
@@ -323,7 +323,7 @@ Ask composed answerers for one decision. Return an outcome to claim the request
 'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
 ```
 
-Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [ApprovalService](../core-data-structures/approval.md) · [Scoped](../core-data-structures/scope.md)
+Types: [ApprovalOutcome](../subsystems/approval.md) · [ApprovalRequest](../subsystems/approval.md) · [ApprovalService](../subsystems/approval.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts)
 
@@ -367,7 +367,7 @@ Committed change to a provider-managed credential source: a `set`, an `unset`, o
 'credentials/updated'(ref: CredentialRef): void
 ```
 
-Types: [CredentialRef](../core-data-structures/credentials.md)
+Types: [CredentialRef](../subsystems/credentials.md)
 
 Source: [`packages/credentials/credentials/src/index.ts:67`](../../packages/credentials/credentials/src/index.ts)
 
@@ -408,7 +408,7 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
 ```
 
-Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md)
+Types: [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md)
 
 Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
 
@@ -428,7 +428,7 @@ Record a successful observation. Listeners must be synchronous recorders: throws
 'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
 ```
 
-Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md)
+Types: [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md)
 
 Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
 
@@ -448,7 +448,7 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
 ```
 
-Types: [FsTarget](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md)
+Types: [FsTarget](../subsystems/filesystem.md) · [FsWriteIntent](../subsystems/filesystem.md)
 
 Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
 
@@ -470,7 +470,7 @@ Goal mutation accepted by one live agent. The matching `goal/change` session eve
 'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [GoalChanged](../core-data-structures/goal.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../subsystems/core.md) · [GoalChanged](../subsystems/goal.md) · [Scoped](../subsystems/scope.md)
 
 Source: [`packages/goal/goal/src/domain.ts:114`](../../packages/goal/goal/src/domain.ts)
 
@@ -515,7 +515,7 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Types: [GenerateOptions](../core-data-structures/core.md) · [LlmService](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
+Types: [GenerateOptions](../subsystems/core.md) · [LlmService](../subsystems/llm-streaming.md) · [StreamChunk](../subsystems/llm-streaming.md)
 
 Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
 
@@ -540,7 +540,7 @@ Creation announcement during session publication. A synchronous throw vetoes and
 'session/created'(this: Scoped<Session>, session: Session): void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
+Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/core/session/src/index.ts:74`](../../packages/core/session/src/index.ts)
 
@@ -561,7 +561,7 @@ Emitted once when an announced session leaves the store, including publication r
 'session/disposed'(this: Scoped<Session>, session: Session): void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
+Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/core/session/src/index.ts:84`](../../packages/core/session/src/index.ts)
 
@@ -584,7 +584,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
+Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
 
 Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
 
@@ -604,7 +604,7 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
 'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
+Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/core/session/src/index.ts:105`](../../packages/core/session/src/index.ts)
 
@@ -629,7 +629,7 @@ One registered namespace's RAW user section changed, whether or not the resolved
 'settings/document-updated'(ns: SettingsNamespace, revision: number): void
 ```
 
-Types: [SettingsNamespace](../core-data-structures/settings.md)
+Types: [SettingsNamespace](../subsystems/settings.md)
 
 Source: [`packages/settings/settings/src/index.ts:170`](../../packages/settings/settings/src/index.ts)
 
@@ -656,7 +656,7 @@ Committed change to one registered namespace's resolved value. Emitted after the
 'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void
 ```
 
-Types: [SettingsNamespace](../core-data-structures/settings.md) · [SettingsUpdateSource](../core-data-structures/settings.md)
+Types: [SettingsNamespace](../subsystems/settings.md) · [SettingsUpdateSource](../subsystems/settings.md)
 
 Source: [`packages/settings/settings/src/index.ts:157`](../../packages/settings/settings/src/index.ts)
 
@@ -697,7 +697,7 @@ A published child settled. Scope-filtered dispatch uses the same delegating pare
 'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md)
+Types: [Scoped](../subsystems/scope.md) · [SubagentService](../subsystems/subagent.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts)
 
@@ -714,7 +714,7 @@ A provider became resolvable in the registry.
 'subagent/provider-added'(provider: SubagentProvider): void
 ```
 
-Types: [SubagentProvider](../core-data-structures/subagent.md)
+Types: [SubagentProvider](../subsystems/subagent.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts)
 
@@ -751,7 +751,7 @@ A provider established a published child. For in-process providers, `ctx.agents.
 'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md)
+Types: [Scoped](../subsystems/scope.md) · [SubagentService](../subsystems/subagent.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
 
@@ -775,7 +775,7 @@ Expert waterfall over the assembled sections, contexts, tools, and variables. Sc
 'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
 ```
 
-Types: [AssembleContext](../core-data-structures/system-prompt.md) · [Scoped](../core-data-structures/scope.md) · [SystemPrompt](../core-data-structures/system-prompt.md)
+Types: [AssembleContext](../subsystems/system-prompt.md) · [Scoped](../subsystems/scope.md) · [SystemPrompt](../subsystems/system-prompt.md)
 
 Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts)
 
@@ -865,7 +865,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri
 'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
 ```
 
-Types: [CodeDispatchLog](../core-data-structures/tools.md) · [ContentBlock](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [ToolRegistry](../core-data-structures/tools.md)
+Types: [CodeDispatchLog](../subsystems/tools.md) · [ContentBlock](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [ToolRegistry](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
 
@@ -887,7 +887,7 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
 'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [ToolDispatchExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
+Types: [Scoped](../subsystems/scope.md) · [ToolDispatchExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
 
@@ -910,7 +910,7 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
 'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
 ```
 
-Types: [PostToolDecision](../core-data-structures/tools.md) · [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
+Types: [PostToolDecision](../subsystems/tools.md) · [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
 
@@ -931,7 +931,7 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
 'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
 ```
 
-Types: [PreToolDecision](../core-data-structures/tools.md) · [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
+Types: [PreToolDecision](../subsystems/tools.md) · [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
 
@@ -950,7 +950,7 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
 'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
 ```
 
-Types: [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
+Types: [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
 
@@ -974,7 +974,7 @@ One `agent()` call settled (clean result, child failure, or run cancellation). P
 'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:81`](../../packages/workflow/workflow/src/index.ts)
 
@@ -995,7 +995,7 @@ One `agent()` call established a published child run. Paired with Events['workfl
 'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts)
 
@@ -1016,7 +1016,7 @@ A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves
 'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts)
 
@@ -1034,7 +1034,7 @@ The script emitted a narration line (a `log(message)` call).
 'workflow/log'(info: WorkflowRunInfo, message: string): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts)
 
@@ -1053,7 +1053,7 @@ The script entered a phase (a `phase(title)` call) — progress grouping for obs
 'workflow/phase'(info: WorkflowRunInfo, title: string): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:53`](../../packages/workflow/workflow/src/index.ts)
 
@@ -1071,7 +1071,7 @@ A workflow run started — the script's meta block validated, the body about to
 'workflow/start'(info: WorkflowRunInfo): void
 ```
 
-Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+Types: [WorkflowRunInfo](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:45`](../../packages/workflow/workflow/src/index.ts)
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 56a0d0d2e6..dbab056105 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -3,7 +3,7 @@
 
 # Cordis Services Catalog
 
-Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.
+Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.
 
 This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
 
@@ -42,7 +42,7 @@ async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<Agent
 async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [AgentOptions](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md)
+Types: [Agent](../subsystems/core.md) · [AgentOptions](../subsystems/core.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md)
 
 Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
 
@@ -214,7 +214,7 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md)
+Types: [Agent](../subsystems/core.md) · [SessionId](../subsystems/core.md)
 
 Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
 
@@ -260,7 +260,7 @@ async request(req: ApprovalRequest): Promise<ApprovalOutcome>
 overrideOf(session: Session): ApprovalPolicy | undefined
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalPolicy](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [Session](../core-data-structures/session.md)
+Types: [Agent](../subsystems/core.md) · [ApprovalOutcome](../subsystems/approval.md) · [ApprovalPolicy](../subsystems/approval.md) · [ApprovalRequest](../subsystems/approval.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
 
@@ -300,7 +300,7 @@ abstract run(spec: BashExecSpec): Promise<BashRunResult>
 abstract start(spec: BashExecSpec): BashProcess
 ```
 
-Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashProcess](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md)
+Types: [BashExecRequest](../subsystems/bash.md) · [BashExecSpec](../subsystems/bash.md) · [BashProcess](../subsystems/bash.md) · [BashRunResult](../subsystems/bash.md)
 
 Source: [`packages/bash/bash/src/index.ts:53`](../../packages/bash/bash/src/index.ts)
 
@@ -331,7 +331,7 @@ collect(execution: ToolExecution): DshEnvironment
 list(): BashEnvVariableInfo[]
 ```
 
-Types: [DshEnvironment](../core-data-structures/subprocess.md) · [ToolExecution](../core-data-structures/tools.md)
+Types: [DshEnvironment](../subsystems/subprocess.md) · [ToolExecution](../subsystems/tools.md)
 
 Source: [`packages/bash/bash-env/src/index.ts:89`](../../packages/bash/bash-env/src/index.ts)
 
@@ -396,7 +396,7 @@ Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and subs
 abstract run(request: CodeRunRequest): Promise<CodeRunResult>
 ```
 
-Types: [CodeRunRequest](../core-data-structures/code-runtime.md) · [CodeRunResult](../core-data-structures/code-runtime.md)
+Types: [CodeRunRequest](../subsystems/code-runtime.md) · [CodeRunResult](../subsystems/code-runtime.md)
 
 Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
 
@@ -449,7 +449,7 @@ find(agent: Agent, name: string): CommandDefinition | undefined
 async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [CommandDefinition](../core-data-structures/commands.md) · [CommandDescriptor](../core-data-structures/commands.md)
+Types: [Agent](../subsystems/core.md) · [CommandDefinition](../subsystems/commands.md) · [CommandDescriptor](../subsystems/commands.md)
 
 Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
 
@@ -514,7 +514,7 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): P
 abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```
 
-Types: [CompactionResult](../core-data-structures/compaction.md) · [CompactionTrigger](../core-data-structures/compaction.md)
+Types: [CompactionResult](../subsystems/compaction.md) · [CompactionTrigger](../subsystems/compaction.md)
 
 Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
 
@@ -560,7 +560,7 @@ abstract set(ref: CredentialRef, value: string): Promise<void>
 abstract unset(ref: CredentialRef): Promise<void>
 ```
 
-Types: [CredentialInfo](../core-data-structures/credentials.md) · [CredentialRef](../core-data-structures/credentials.md) · [ResolvedCredential](../core-data-structures/credentials.md)
+Types: [CredentialInfo](../subsystems/credentials.md) · [CredentialRef](../subsystems/credentials.md) · [ResolvedCredential](../subsystems/credentials.md)
 
 Source: [`packages/credentials/credentials/src/index.ts:77`](../../packages/credentials/credentials/src/index.ts)
 
@@ -719,7 +719,7 @@ abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent,
 abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>
 ```
 
-Types: [FsDirEntry](../core-data-structures/filesystem.md) · [FsEditOutcome](../core-data-structures/filesystem.md) · [FsEditRequest](../core-data-structures/filesystem.md) · [FsInfo](../core-data-structures/filesystem.md) · [FsPathInfo](../core-data-structures/filesystem.md) · [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md) · [FsWriteOutcome](../core-data-structures/filesystem.md) · [SandboxExecutionPolicy](../core-data-structures/sandbox.md)
+Types: [FsDirEntry](../subsystems/filesystem.md) · [FsEditOutcome](../subsystems/filesystem.md) · [FsEditRequest](../subsystems/filesystem.md) · [FsInfo](../subsystems/filesystem.md) · [FsPathInfo](../subsystems/filesystem.md) · [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md) · [FsWriteIntent](../subsystems/filesystem.md) · [FsWriteOutcome](../subsystems/filesystem.md) · [SandboxExecutionPolicy](../subsystems/sandbox.md)
 
 Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
 
@@ -814,7 +814,7 @@ block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
 @Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [CreateGoalRequest](../core-data-structures/goal.md) · [CreateGoalResult](../core-data-structures/goal.md) · [EditGoalRequest](../core-data-structures/goal.md) · [GoalBlockReason](../core-data-structures/goal.md) · [GoalRef](../core-data-structures/goal.md) · [GoalView](../core-data-structures/goal.md)
+Types: [Agent](../subsystems/core.md) · [CreateGoalRequest](../subsystems/goal.md) · [CreateGoalResult](../subsystems/goal.md) · [EditGoalRequest](../subsystems/goal.md) · [GoalBlockReason](../subsystems/goal.md) · [GoalRef](../subsystems/goal.md) · [GoalView](../subsystems/goal.md)
 
 Source: [`packages/goal/goal/src/index.ts:183`](../../packages/goal/goal/src/index.ts)
 
@@ -1008,7 +1008,7 @@ async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<Prepared
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Types: [AdapterRegistrationHandle](../core-data-structures/core.md) · [DirectoryRegistrationHandle](../core-data-structures/core.md) · [GenerateOptions](../core-data-structures/core.md) · [LlmAdapter](../core-data-structures/llm-streaming.md) · [LlmCallConfig](../core-data-structures/core.md) · [LlmConfigurableProvider](../core-data-structures/core.md) · [LlmDiscoveredModel](../core-data-structures/core.md) · [LlmModelDiscoveryRequest](../core-data-structures/core.md) · [LlmModelInfo](../core-data-structures/core.md) · [LlmProviderInfo](../core-data-structures/core.md) · [LlmResolvedModelInfo](../core-data-structures/core.md) · [PreparedLlmCall](../core-data-structures/llm-streaming.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
+Types: [AdapterRegistrationHandle](../subsystems/core.md) · [DirectoryRegistrationHandle](../subsystems/core.md) · [GenerateOptions](../subsystems/core.md) · [LlmAdapter](../subsystems/llm-streaming.md) · [LlmCallConfig](../subsystems/core.md) · [LlmConfigurableProvider](../subsystems/core.md) · [LlmDiscoveredModel](../subsystems/core.md) · [LlmModelDiscoveryRequest](../subsystems/core.md) · [LlmModelInfo](../subsystems/core.md) · [LlmProviderInfo](../subsystems/core.md) · [LlmResolvedModelInfo](../subsystems/core.md) · [PreparedLlmCall](../subsystems/llm-streaming.md) · [ResolvedRetryPolicy](../subsystems/llm-streaming.md) · [StreamChunk](../subsystems/llm-streaming.md)
 
 Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
 
@@ -1060,7 +1060,7 @@ optionOf(name: string): PresetOption
 set(session: Session, name: string): void
 ```
 
-Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
+Types: [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
 
 Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
 
@@ -1096,7 +1096,7 @@ get(agent: Agent): { active: boolean; pending?: boolean }
 set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../subsystems/core.md)
 
 Source: [`packages/plan/plan-mode/src/index.ts:183`](../../packages/plan/plan-mode/src/index.ts)
 
@@ -1178,7 +1178,7 @@ async kill(owner: Agent, id: PtySessionId, reason: string = 'model request'): Pr
 list(owner: Agent): PtySessionSnapshot[]
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [PtyBackend](../core-data-structures/pty.md) · [PtyReadRequest](../core-data-structures/pty.md) · [PtyReadResult](../core-data-structures/pty.md) · [PtySendOperation](../core-data-structures/pty.md) · [PtySendRequest](../core-data-structures/pty.md) · [PtySessionId](../core-data-structures/pty.md) · [PtySessionSnapshot](../core-data-structures/pty.md) · [PtySignal](../core-data-structures/pty.md) · [PtySignalResult](../core-data-structures/pty.md) · [PtySpawnRequest](../core-data-structures/pty.md) · [PtySpawnResult](../core-data-structures/pty.md)
+Types: [Agent](../subsystems/core.md) · [PtyBackend](../subsystems/pty.md) · [PtyReadRequest](../subsystems/pty.md) · [PtyReadResult](../subsystems/pty.md) · [PtySendOperation](../subsystems/pty.md) · [PtySendRequest](../subsystems/pty.md) · [PtySessionId](../subsystems/pty.md) · [PtySessionSnapshot](../subsystems/pty.md) · [PtySignal](../subsystems/pty.md) · [PtySignalResult](../subsystems/pty.md) · [PtySpawnRequest](../subsystems/pty.md) · [PtySpawnResult](../subsystems/pty.md)
 
 Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
 
@@ -1201,7 +1201,7 @@ Abstract process-sandbox service. confine must return enforcing argv or fail clo
 abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv
 ```
 
-Types: [ConfinedArgv](../core-data-structures/sandbox.md) · [SandboxPolicy](../core-data-structures/sandbox.md)
+Types: [ConfinedArgv](../subsystems/sandbox.md) · [SandboxPolicy](../subsystems/sandbox.md)
 
 Source: [`packages/sandbox/sandbox/src/index.ts:148`](../../packages/sandbox/sandbox/src/index.ts)
 
@@ -1229,7 +1229,7 @@ resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
 overrideOf(session: Session): SandboxMode | undefined
 ```
 
-Types: [SandboxExecutionPolicy](../core-data-structures/sandbox.md) · [SandboxMode](../core-data-structures/sandbox.md) · [SandboxPolicyRequest](../core-data-structures/sandbox.md) · [Session](../core-data-structures/session.md)
+Types: [SandboxExecutionPolicy](../subsystems/sandbox.md) · [SandboxMode](../subsystems/sandbox.md) · [SandboxPolicyRequest](../subsystems/sandbox.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/sandbox/sandbox-policy/src/index.ts:91`](../../packages/sandbox/sandbox-policy/src/index.ts)
 
@@ -1350,7 +1350,7 @@ abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
 abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
 ```
 
-Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) · [SessionInspection](../core-data-structures/persistence.md) · [SessionLocation](../core-data-structures/persistence.md) · [SessionPersistenceSnapshot](../core-data-structures/persistence.md) · [SessionPreparation](../core-data-structures/persistence.md)
+Types: [SessionEvent](../subsystems/core.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md) · [SessionInspection](../subsystems/persistence.md) · [SessionLocation](../subsystems/persistence.md) · [SessionPersistenceSnapshot](../subsystems/persistence.md) · [SessionPreparation](../subsystems/persistence.md)
 
 Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
 
@@ -1398,7 +1398,7 @@ async write(session: Session): Promise<void>
 async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>
 ```
 
-Types: [Session](../core-data-structures/session.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md)
+Types: [Session](../subsystems/session.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md)
 
 Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
 
@@ -1506,7 +1506,7 @@ viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
 restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
 ```
 
-Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
+Types: [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
 
 Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
 
@@ -1633,7 +1633,7 @@ async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promi
 async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>
 ```
 
-Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventResultFilter](../core-data-structures/session-query.md) · [SessionEventSearchDocument](../core-data-structures/session-query.md) · [SessionEventSearchPage](../core-data-structures/session-query.md) · [SessionEventSearchRequest](../core-data-structures/session-query.md) · [SessionEventTraceObservation](../core-data-structures/session-query.md) · [SessionEventTraceRequest](../core-data-structures/session-query.md) · [SessionEventWindow](../core-data-structures/session-query.md) · [SessionId](../core-data-structures/core.md) · [SessionLineageTrace](../core-data-structures/session-query.md) · [SessionLogSnapshot](../core-data-structures/session-query.md) · [SessionRecord](../core-data-structures/session-query.md) · [SessionResultFilter](../core-data-structures/session-query.md) · [SessionSearchExecContext](../core-data-structures/session-query.md) · [SessionSearchHit](../core-data-structures/session-query.md) · [SessionSearchPage](../core-data-structures/session-query.md) · [SessionSearchRequest](../core-data-structures/session-query.md) · [SessionSurfaceSnapshot](../core-data-structures/session-query.md) · [SessionTitleObservation](../core-data-structures/session-query.md) · [SessionTitleObservationResult](../core-data-structures/session-query.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
+Types: [SessionEventReadRequest](../subsystems/session-query.md) · [SessionEventRecord](../subsystems/session-query.md) · [SessionEventResultFilter](../subsystems/session-query.md) · [SessionEventSearchDocument](../subsystems/session-query.md) · [SessionEventSearchPage](../subsystems/session-query.md) · [SessionEventSearchRequest](../subsystems/session-query.md) · [SessionEventTraceObservation](../subsystems/session-query.md) · [SessionEventTraceRequest](../subsystems/session-query.md) · [SessionEventWindow](../subsystems/session-query.md) · [SessionId](../subsystems/core.md) · [SessionLineageTrace](../subsystems/session-query.md) · [SessionLogSnapshot](../subsystems/session-query.md) · [SessionRecord](../subsystems/session-query.md) · [SessionResultFilter](../subsystems/session-query.md) · [SessionSearchExecContext](../subsystems/session-query.md) · [SessionSearchHit](../subsystems/session-query.md) · [SessionSearchPage](../subsystems/session-query.md) · [SessionSearchRequest](../subsystems/session-query.md) · [SessionSurfaceSnapshot](../subsystems/session-query.md) · [SessionTitleObservation](../subsystems/session-query.md) · [SessionTitleObservationResult](../subsystems/session-query.md) · [SessionTitleSnapshot](../subsystems/session-title.md)
 
 Source: [`packages/session-query/session-query/src/index.ts:81`](../../packages/session-query/session-query/src/index.ts)
 
@@ -1663,7 +1663,7 @@ async listCandidates( agent: Agent, query: string = '', limit: number = this.con
 async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [PreparedReferencedMessage](../core-data-structures/session-reference.md) · [SessionReferenceCandidate](../core-data-structures/session-reference.md) · [SessionReferenceInput](../core-data-structures/session-reference.md)
+Types: [Agent](../subsystems/core.md) · [ContentBlock](../subsystems/core.md) · [PreparedReferencedMessage](../subsystems/session-reference.md) · [SessionReferenceCandidate](../subsystems/session-reference.md) · [SessionReferenceInput](../subsystems/session-reference.md)
 
 Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
 
@@ -1797,7 +1797,7 @@ list(): Session[]
 fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
 ```
 
-Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [PrepareSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md)
+Types: [CreateSessionOptions](../subsystems/persistence.md) · [PrepareSessionOptions](../subsystems/persistence.md) · [Session](../subsystems/session.md) · [SessionId](../subsystems/core.md)
 
 Source: [`packages/core/session/src/index.ts:807`](../../packages/core/session/src/index.ts)
 
@@ -1844,7 +1844,7 @@ async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnaps
 register(provider: SessionTitleProvider): () => Promise<void>
 ```
 
-Types: [Session](../core-data-structures/session.md) · [SessionTitleProvider](../core-data-structures/session-title.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
+Types: [Session](../subsystems/session.md) · [SessionTitleProvider](../subsystems/session-title.md) · [SessionTitleSnapshot](../subsystems/session-title.md)
 
 Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts)
 
@@ -1929,7 +1929,7 @@ async replace(ns: SettingsNamespace, section: object, expectedRevision?: number)
 async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
 ```
 
-Types: [SettingsDescribeOptions](../core-data-structures/settings.md) · [SettingsDescriptor](../core-data-structures/settings.md) · [SettingsNamespace](../core-data-structures/settings.md) · [SettingsPathOp](../core-data-structures/settings.md) · [SettingsRegisterOptions](../core-data-structures/settings.md) · [SettingsScope](../core-data-structures/settings.md)
+Types: [SettingsDescribeOptions](../subsystems/settings.md) · [SettingsDescriptor](../subsystems/settings.md) · [SettingsNamespace](../subsystems/settings.md) · [SettingsPathOp](../subsystems/settings.md) · [SettingsRegisterOptions](../subsystems/settings.md) · [SettingsScope](../subsystems/settings.md)
 
 Source: [`packages/settings/settings/src/index.ts:387`](../../packages/settings/settings/src/index.ts)
 
@@ -1987,7 +1987,7 @@ async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
 async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
 ```
 
-Types: [SkillCatalogSnapshot](../core-data-structures/skills.md) · [SkillDefinition](../core-data-structures/skills.md) · [SkillLookupOptions](../core-data-structures/skills.md) · [SkillProvider](../core-data-structures/skills.md) · [SkillProviderControl](../core-data-structures/skills.md) · [SkillRegistration](../core-data-structures/skills.md) · [SkillSummary](../core-data-structures/skills.md)
+Types: [SkillCatalogSnapshot](../subsystems/skills.md) · [SkillDefinition](../subsystems/skills.md) · [SkillLookupOptions](../subsystems/skills.md) · [SkillProvider](../subsystems/skills.md) · [SkillProviderControl](../subsystems/skills.md) · [SkillRegistration](../subsystems/skills.md) · [SkillSummary](../subsystems/skills.md)
 
 Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
 
@@ -2010,7 +2010,7 @@ Semantics every implementation must honor:
 abstract saveText(input: SaveTextSpill): Promise<SpillRef>
 ```
 
-Types: [SaveTextSpill](../core-data-structures/spill.md) · [SpillRef](../core-data-structures/spill.md)
+Types: [SaveTextSpill](../subsystems/spill.md) · [SpillRef](../subsystems/spill.md)
 
 Source: [`packages/spill/spill/src/index.ts:45`](../../packages/spill/spill/src/index.ts)
 
@@ -2248,7 +2248,7 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentDescendantListEntry](../core-data-structures/subagent.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentInterruptAuthority](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
+Types: [Agent](../subsystems/core.md) · [ContentBlock](../subsystems/core.md) · [ContinuableSetupContribution](../subsystems/subagent.md) · [ContinuableStart](../subsystems/subagent.md) · [ContinuableStartSpec](../subsystems/subagent.md) · [MessageId](../subsystems/core.md) · [SessionId](../subsystems/core.md) · [SubagentDescendantListEntry](../subsystems/subagent.md) · [SubagentFollowupOptions](../subsystems/subagent.md) · [SubagentInterruptAuthority](../subsystems/subagent.md) · [SubagentListEntry](../subsystems/subagent.md) · [SubagentProvider](../subsystems/subagent.md) · [SubagentReportOptions](../subsystems/subagent.md) · [SubagentRun](../subsystems/subagent.md) · [SubagentStartRequest](../subsystems/subagent.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
 
@@ -2297,7 +2297,7 @@ abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
 abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
 ```
 
-Types: [SubprocessHandle](../core-data-structures/subprocess.md) · [SubprocessSpawnSpec](../core-data-structures/subprocess.md) · [SubprocessTerminalHandle](../core-data-structures/subprocess.md) · [SubprocessTerminalSpawnSpec](../core-data-structures/subprocess.md)
+Types: [SubprocessHandle](../subsystems/subprocess.md) · [SubprocessSpawnSpec](../subsystems/subprocess.md) · [SubprocessTerminalHandle](../subsystems/subprocess.md) · [SubprocessTerminalSpawnSpec](../subsystems/subprocess.md)
 
 Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts)
 
@@ -2353,7 +2353,7 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine
 async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```
 
-Types: [AssembleContext](../core-data-structures/system-prompt.md) · [PromptContext](../core-data-structures/system-prompt.md) · [PromptSection](../core-data-structures/system-prompt.md) · [ToolProviderResult](../core-data-structures/system-prompt.md)
+Types: [AssembleContext](../subsystems/system-prompt.md) · [PromptContext](../subsystems/system-prompt.md) · [PromptSection](../subsystems/system-prompt.md) · [ToolProviderResult](../subsystems/system-prompt.md)
 
 Source: [`packages/core/system-prompt/src/index.ts:314`](../../packages/core/system-prompt/src/index.ts)
 
@@ -2448,7 +2448,7 @@ abstract onTaskDone(listener: TaskDoneListener): () => void
 abstract attachSurface(name: string): () => void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [TaskDoneListener](../core-data-structures/tasks.md) · [TaskId](../core-data-structures/tasks.md) · [TaskRead](../core-data-structures/tasks.md) · [TaskSnapshot](../core-data-structures/tasks.md) · [TaskStart](../core-data-structures/tasks.md)
+Types: [Agent](../subsystems/core.md) · [TaskDoneListener](../subsystems/tasks.md) · [TaskId](../subsystems/tasks.md) · [TaskRead](../subsystems/tasks.md) · [TaskSnapshot](../subsystems/tasks.md) · [TaskStart](../subsystems/tasks.md)
 
 Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts)
 
@@ -2507,7 +2507,7 @@ measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
 estimateMessage(message: Message): number
 ```
 
-Types: [EpochHeader](../core-data-structures/session.md) · [Message](../core-data-structures/core.md) · [Session](../core-data-structures/session.md) · [TokenMeasurement](../core-data-structures/token-meter.md)
+Types: [EpochHeader](../subsystems/session.md) · [Message](../subsystems/core.md) · [Session](../subsystems/session.md) · [TokenMeasurement](../subsystems/token-meter.md)
 
 Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
 
@@ -2547,7 +2547,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 pruneSession(session: Session): PruneResult
 ```
 
-Types: [ContentBlock](../core-data-structures/core.md) · [PruneResult](../core-data-structures/compaction.md) · [Session](../core-data-structures/session.md)
+Types: [ContentBlock](../subsystems/core.md) · [PruneResult](../subsystems/compaction.md) · [Session](../subsystems/session.md)
 
 Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
 
@@ -2630,7 +2630,7 @@ executionMode(exec: ToolExecutionInput): ToolExecutionMode
 async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 ```
 
-Types: [ScopeKey](../core-data-structures/scope.md) · [ToolDefinition](../core-data-structures/tools.md) · [ToolExecutionInput](../core-data-structures/tools.md) · [ToolExecutionMode](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolGuard](../core-data-structures/tools.md) · [ToolRestriction](../core-data-structures/tools.md) · [ToolSchema](../core-data-structures/tools.md)
+Types: [ScopeKey](../subsystems/scope.md) · [ToolDefinition](../subsystems/tools.md) · [ToolExecutionInput](../subsystems/tools.md) · [ToolExecutionMode](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolGuard](../subsystems/tools.md) · [ToolRestriction](../subsystems/tools.md) · [ToolSchema](../subsystems/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
 
@@ -2743,7 +2743,7 @@ registerProvider(provider: UserInteractionProvider): () => void
 async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 ```
 
-Types: [AskUserQuestionAnswer](../core-data-structures/user-interaction.md) · [AskUserQuestionRequest](../core-data-structures/user-interaction.md) · [UserInteractionProvider](../core-data-structures/user-interaction.md)
+Types: [AskUserQuestionAnswer](../subsystems/user-interaction.md) · [AskUserQuestionRequest](../subsystems/user-interaction.md) · [UserInteractionProvider](../subsystems/user-interaction.md)
 
 Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts)
 
@@ -2801,7 +2801,7 @@ async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearch
 async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
 ```
 
-Types: [WebFetchProvider](../core-data-structures/web.md) · [WebFetchRequest](../core-data-structures/web.md) · [WebFetchResult](../core-data-structures/web.md) · [WebSearchProvider](../core-data-structures/web.md) · [WebSearchRequest](../core-data-structures/web.md) · [WebSearchResult](../core-data-structures/web.md)
+Types: [WebFetchProvider](../subsystems/web.md) · [WebFetchRequest](../subsystems/web.md) · [WebFetchResult](../subsystems/web.md) · [WebSearchProvider](../subsystems/web.md) · [WebSearchRequest](../subsystems/web.md) · [WebSearchResult](../subsystems/web.md)
 
 Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
 
@@ -2819,7 +2819,7 @@ Workflow execution seam. Invalid requests throw before publication; a live run i
 abstract start(request: WorkflowStartRequest): WorkflowRun
 ```
 
-Types: [WorkflowRun](../core-data-structures/workflow.md) · [WorkflowStartRequest](../core-data-structures/workflow.md)
+Types: [WorkflowRun](../subsystems/workflow.md) · [WorkflowStartRequest](../subsystems/workflow.md)
 
 Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts)
 
@@ -2885,7 +2885,7 @@ archiveSession(sessionId: SessionId): Promise<void>
 async resolveByPath(path: string): Promise<Workspace | undefined>
 ```
 
-Types: [SessionId](../core-data-structures/core.md)
+Types: [SessionId](../subsystems/core.md)
 
 Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts)
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 43f985604b..13c766cc80 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: 0032000e298ef49516d618e932258e79cf90e802
-development.zh.md: d681306e31991794519b62c3edbb6ca35ebc228b
+development.md: 134109fd2a09dfa36aaf2ccdba14daccf896da60
+development.zh.md: 741a860770ee3b20fe94cb0b4993bb281b605b26
diff --git a/docs/development.md b/docs/development.md
index 0032000e29..134109fd2a 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -156,10 +156,10 @@ Pick the tag that matches the urgency so anyone scanning the code can tell a rel
 
 ### Documenting types verbatim (`ts type-equiv`)
 
-The [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
+The [core data structures](subsystems/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
 
 ```json
-{ "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
+{ "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
 `pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `"projection": "public-api"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.
diff --git a/docs/development.zh.md b/docs/development.zh.md
index d681306e31..741a860770 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -156,10 +156,10 @@ pnpm run demo:acp
 
 ### 逐字记录类型（`ts type-equiv`）
 
-[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[核心数据结构](subsystems/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
-{ "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
+{ "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
 `pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。
diff --git a/docs/graph-atlas.md b/docs/graph-atlas.md
index e783d5fddf..0c955c9480 100644
--- a/docs/graph-atlas.md
+++ b/docs/graph-atlas.md
@@ -3,7 +3,7 @@
 
 # Documentation Graph Index
 
-These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md).
+These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [subsystems/](subsystems/core.md).
 
 The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).
 
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index 87ef939730..b9a330f21d 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -14,9 +14,9 @@
 
 依赖约束规范：各类扩展插件仅依赖抽象接口，严禁直接依赖 `dsh-agent-loop`（该主循环支持替换实现）；唯一允许的特例是组合包 `dsh-agent-spine-demo`，它的职责是组装整套实体主干。
 
-> This document covers **behavior**; type shapes live in [core-data-structures/](../core-data-structures/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
+> This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
 
-本文档描述整体行为逻辑；类型定义存放于 [core-data-structures/](../core-data-structures/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
 
 ## ② 防御模式规则
 
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index b238e56399..04f992e536 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -3,11 +3,11 @@
 
 # Session Persistence Event Catalog
 
-Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](core-data-structures/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
+Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
 
 This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).
 
-The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.
+The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.
 
 ## Event envelope
 
@@ -123,7 +123,7 @@ Source: [`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/type
 }
 ```
 
-Types: [CallId](core-data-structures/core.md)
+Types: [CallId](subsystems/core.md)
 
 Source: [`packages/interaction/user-approval/src/index.ts:44`](../packages/interaction/user-approval/src/index.ts)
 
@@ -172,7 +172,7 @@ Source: [`packages/interaction/user-approval/src/index.ts:67`](../packages/inter
 'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
 ```
 
-Types: [StreamChunk](core-data-structures/llm-streaming.md)
+Types: [StreamChunk](subsystems/llm-streaming.md)
 
 Source: [`packages/core/session/src/types.ts:238`](../packages/core/session/src/types.ts)
 
@@ -188,7 +188,7 @@ Source: [`packages/core/session/src/types.ts:238`](../packages/core/session/src/
 'assistant/message': { turn: number; step: number; message: AssistantMessage; usage?: TokenUsage }
 ```
 
-Types: [TokenUsage](core-data-structures/llm-streaming.md)
+Types: [TokenUsage](subsystems/llm-streaming.md)
 
 Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/types.ts)
 
@@ -328,7 +328,7 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
 )
 ```
 
-Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md)
+Types: [ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
 
 Source: [`packages/compact/compact/src/types.ts:29`](../packages/compact/compact/src/types.ts)
 
@@ -555,7 +555,7 @@ Source: [`packages/core/session/src/types.ts:304`](../packages/core/session/src/
 'session/title': SessionTitleEventData
 ```
 
-Types: [SessionTitleEventData](core-data-structures/session-title.md)
+Types: [SessionTitleEventData](subsystems/session-title.md)
 
 Source: [`packages/session/session-title/src/index.ts:100`](../packages/session/session-title/src/index.ts)
 
@@ -566,7 +566,7 @@ Source: [`packages/session/session-title/src/index.ts:100`](../packages/session/
 'session/title-llm-request': SessionTitleLlmRequestEventData
 ```
 
-Types: [SessionTitleLlmRequestEventData](core-data-structures/session-title.md)
+Types: [SessionTitleLlmRequestEventData](subsystems/session-title.md)
 
 Source: [`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts)
 
@@ -616,7 +616,7 @@ Source: [`packages/subagent/subagent/src/descriptor.ts:37`](../packages/subagent
 'todo/write': { todos: TodoItem[] }
 ```
 
-Types: [TodoItem](core-data-structures/session.md)
+Types: [TodoItem](subsystems/session.md)
 
 Source: [`packages/core/session/src/types.ts:271`](../packages/core/session/src/types.ts)
 
@@ -633,7 +633,7 @@ Source: [`packages/core/session/src/types.ts:271`](../packages/core/session/src/
 'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
 ```
 
-Types: [CallId](core-data-structures/core.md)
+Types: [CallId](subsystems/core.md)
 
 Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/types.ts)
 
@@ -658,7 +658,7 @@ Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/
 'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
 ```
 
-Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md)
+Types: [CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md)
 
 Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/code-mode.ts)
 
@@ -681,7 +681,7 @@ Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/c
 'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
 ```
 
-Types: [CallId](core-data-structures/core.md)
+Types: [CallId](subsystems/core.md)
 
 Source: [`packages/core/tools/src/code-mode.ts:33`](../packages/core/tools/src/code-mode.ts)
 
@@ -726,7 +726,7 @@ Source: [`packages/core/session/src/types.ts:263`](../packages/core/session/src/
 'turn/end': { turn: number; reason: TurnEndReason }
 ```
 
-Types: [TurnEndReason](core-data-structures/session.md)
+Types: [TurnEndReason](subsystems/session.md)
 
 Source: [`packages/core/session/src/types.ts:224`](../packages/core/session/src/types.ts)
 
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
index 47a2e3fdd7..b54453f3c4 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.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 docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
-0004-landlock-partial-notice-misclassified-child-failures.md: db810fdc896f9734d1b581617838d72166f4efc9
-0004-landlock-partial-notice-misclassified-child-failures.zh.md: 4a31fb038c44b036e6a183040947295a47221967
+0004-landlock-partial-notice-misclassified-child-failures.md: ed59fa9d2b04623220a9bcd984fe6becdc619198
+0004-landlock-partial-notice-misclassified-child-failures.zh.md: 5cf3e4422a5b888553e12dfb97b8a26aad65e231
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
index db810fdc89..ed59fa9d2b 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
@@ -40,7 +40,7 @@ Stderr remains an in-band attribution channel. A confined child can deliberately
 
 ## Guardrails added
 
-- [`RunnerFailureRule`](../core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects) carries optional allowed exit codes, case-insensitive per-line fatal signatures, and case-insensitive exact informational-line exclusions.
+- [`RunnerFailureRule`](../subsystems/sandbox.md#wrapped-argv-and-classification-dialects) carries optional allowed exit codes, case-insensitive per-line fatal signatures, and case-insensitive exact informational-line exclusions.
 - [`dsh-sandbox-local`](../../packages/sandbox/sandbox-local/) maps Landlock to exit 125 plus a non-notice `landlock-run:` line while bwrap, Seatbelt, and custom runners remain signature-only.
 - [`dsh-bash-sandbox`](../../packages/bash/bash-sandbox/) directly spawns the provider argv, so a pre-start rejection uses the spawn-error channel instead of localized shell diagnostics. Settled foreground and background execution share one evidence-returning classifier; fatal evidence outranks denial, and foreground errors report the matched fatal line without changing captured stderr.
 - [`dsh-tool-fs-search`](../../packages/fs/tool-fs-search/) uses packaged ripgrep through `ctx.subprocess` and remains outside the sandboxed bash seam.
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
index 4a31fb038c..5cf3e4422a 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
@@ -40,7 +40,7 @@ stderr 仍是带内归因通道。受限子进程可以故意复现 runner 的
 
 ## 已添加的防护措施
 
-- [`RunnerFailureRule`](../core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects) 携带可选的允许退出码、不区分大小写的逐行致命签名，以及按不区分大小写的整行精确匹配排除的信息性行。
+- [`RunnerFailureRule`](../subsystems/sandbox.md#wrapped-argv-and-classification-dialects) 携带可选的允许退出码、不区分大小写的逐行致命签名，以及按不区分大小写的整行精确匹配排除的信息性行。
 - [`dsh-sandbox-local`](../../packages/sandbox/sandbox-local/) 把 Landlock 映射为退出码 125 加一行非通知的 `landlock-run:` 诊断，而 bwrap、Seatbelt 和自定义 runner 仍仅依据签名。
 - [`dsh-bash-sandbox`](../../packages/bash/bash-sandbox/) 直接 spawn 提供方 argv，因此启动前遭拒时使用 spawn 错误通道，而非本地化的 shell 诊断。已结算的前台与后台执行共用一个返回证据的分类器；致命证据优先于拒绝，前台错误会报告匹配到的致命行，同时保持捕获的 stderr 不变。
 - [`dsh-tool-fs-search`](../../packages/fs/tool-fs-search/) 通过 `ctx.subprocess` 运行打包的 ripgrep，并继续位于沙箱化 bash seam 之外。
diff --git a/docs/core-data-structures/approval.i18n.yaml b/docs/subsystems/approval.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/approval.i18n.yaml
rename to docs/subsystems/approval.i18n.yaml
index 975f631805..a3447601a4 100644
--- a/docs/core-data-structures/approval.i18n.yaml
+++ b/docs/subsystems/approval.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 docs/core-data-structures/approval.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/approval.md
 approval.md: 8f17f98101950e6413d67fb4cce6befc5aede069
 approval.zh.md: c19285572b667512427b71d4af214acbc2baf334
diff --git a/docs/core-data-structures/approval.md b/docs/subsystems/approval.md
similarity index 100%
rename from docs/core-data-structures/approval.md
rename to docs/subsystems/approval.md
diff --git a/docs/core-data-structures/approval.zh.md b/docs/subsystems/approval.zh.md
similarity index 100%
rename from docs/core-data-structures/approval.zh.md
rename to docs/subsystems/approval.zh.md
diff --git a/docs/core-data-structures/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/bash.i18n.yaml
rename to docs/subsystems/bash.i18n.yaml
diff --git a/docs/core-data-structures/bash.md b/docs/subsystems/bash.md
similarity index 100%
rename from docs/core-data-structures/bash.md
rename to docs/subsystems/bash.md
diff --git a/docs/core-data-structures/bash.zh.md b/docs/subsystems/bash.zh.md
similarity index 100%
rename from docs/core-data-structures/bash.zh.md
rename to docs/subsystems/bash.zh.md
diff --git a/docs/core-data-structures/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/code-runtime.i18n.yaml
rename to docs/subsystems/code-runtime.i18n.yaml
diff --git a/docs/core-data-structures/code-runtime.md b/docs/subsystems/code-runtime.md
similarity index 100%
rename from docs/core-data-structures/code-runtime.md
rename to docs/subsystems/code-runtime.md
diff --git a/docs/core-data-structures/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
similarity index 100%
rename from docs/core-data-structures/code-runtime.zh.md
rename to docs/subsystems/code-runtime.zh.md
diff --git a/docs/core-data-structures/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/commands.i18n.yaml
rename to docs/subsystems/commands.i18n.yaml
index 18df873acc..a741971a9a 100644
--- a/docs/core-data-structures/commands.i18n.yaml
+++ b/docs/subsystems/commands.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 docs/core-data-structures/commands.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/commands.md
 commands.md: 83ce9c2498df58110d9a9c2e7d5163a9df813e1c
 commands.zh.md: c486f480177c7ff8b35cc846beafac009cea42bb
diff --git a/docs/core-data-structures/commands.md b/docs/subsystems/commands.md
similarity index 100%
rename from docs/core-data-structures/commands.md
rename to docs/subsystems/commands.md
diff --git a/docs/core-data-structures/commands.zh.md b/docs/subsystems/commands.zh.md
similarity index 100%
rename from docs/core-data-structures/commands.zh.md
rename to docs/subsystems/commands.zh.md
diff --git a/docs/core-data-structures/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/compaction.i18n.yaml
rename to docs/subsystems/compaction.i18n.yaml
index 2ad9ea8e8a..7dc00cebfc 100644
--- a/docs/core-data-structures/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/core-data-structures/compaction.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/compaction.md
 compaction.md: f1df5b83bd43136af60988dabd9dc68fe32467a2
 compaction.zh.md: 52540250d466f81f51cf7c681bb6f1436e29a12d
diff --git a/docs/core-data-structures/compaction.md b/docs/subsystems/compaction.md
similarity index 100%
rename from docs/core-data-structures/compaction.md
rename to docs/subsystems/compaction.md
diff --git a/docs/core-data-structures/compaction.zh.md b/docs/subsystems/compaction.zh.md
similarity index 100%
rename from docs/core-data-structures/compaction.zh.md
rename to docs/subsystems/compaction.zh.md
diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/core.i18n.yaml
rename to docs/subsystems/core.i18n.yaml
index ee870f9334..3057ee36ee 100644
--- a/docs/core-data-structures/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/core-data-structures/core.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/core.md
 core.md: 8f413a7a064ad6f63e0caec31354869e51139020
 core.zh.md: d0f02f0cfc2cd30fc67aacf5b17d1daf324295c5
diff --git a/docs/core-data-structures/core.md b/docs/subsystems/core.md
similarity index 100%
rename from docs/core-data-structures/core.md
rename to docs/subsystems/core.md
diff --git a/docs/core-data-structures/core.zh.md b/docs/subsystems/core.zh.md
similarity index 100%
rename from docs/core-data-structures/core.zh.md
rename to docs/subsystems/core.zh.md
diff --git a/docs/core-data-structures/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/credentials.i18n.yaml
rename to docs/subsystems/credentials.i18n.yaml
index d44275d97e..f7899eaf6e 100644
--- a/docs/core-data-structures/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/core-data-structures/credentials.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/credentials.md
 credentials.md: ef74ddeb4346e18f8d5d33488657e5d50f1d754e
 credentials.zh.md: 09cf374a2346fd93aa834e3372321e6eeece6ed8
diff --git a/docs/core-data-structures/credentials.md b/docs/subsystems/credentials.md
similarity index 100%
rename from docs/core-data-structures/credentials.md
rename to docs/subsystems/credentials.md
diff --git a/docs/core-data-structures/credentials.zh.md b/docs/subsystems/credentials.zh.md
similarity index 100%
rename from docs/core-data-structures/credentials.zh.md
rename to docs/subsystems/credentials.zh.md
diff --git a/docs/core-data-structures/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/filesystem.i18n.yaml
rename to docs/subsystems/filesystem.i18n.yaml
diff --git a/docs/core-data-structures/filesystem.md b/docs/subsystems/filesystem.md
similarity index 100%
rename from docs/core-data-structures/filesystem.md
rename to docs/subsystems/filesystem.md
diff --git a/docs/core-data-structures/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
similarity index 100%
rename from docs/core-data-structures/filesystem.zh.md
rename to docs/subsystems/filesystem.zh.md
diff --git a/docs/core-data-structures/goal.i18n.yaml b/docs/subsystems/goal.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/goal.i18n.yaml
rename to docs/subsystems/goal.i18n.yaml
diff --git a/docs/core-data-structures/goal.md b/docs/subsystems/goal.md
similarity index 100%
rename from docs/core-data-structures/goal.md
rename to docs/subsystems/goal.md
diff --git a/docs/core-data-structures/goal.zh.md b/docs/subsystems/goal.zh.md
similarity index 100%
rename from docs/core-data-structures/goal.zh.md
rename to docs/subsystems/goal.zh.md
diff --git a/docs/core-data-structures/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/llm-streaming.i18n.yaml
rename to docs/subsystems/llm-streaming.i18n.yaml
index 7168f9bd85..1ff1a1d42b 100644
--- a/docs/core-data-structures/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/core-data-structures/llm-streaming.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md
 llm-streaming.md: 5c90b3ce4ac65a99997f6ba7ad5deac494b7f772
 llm-streaming.zh.md: 7fd0043234cb40d6b21cec6ff101993164785a6e
diff --git a/docs/core-data-structures/llm-streaming.md b/docs/subsystems/llm-streaming.md
similarity index 100%
rename from docs/core-data-structures/llm-streaming.md
rename to docs/subsystems/llm-streaming.md
diff --git a/docs/core-data-structures/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
similarity index 100%
rename from docs/core-data-structures/llm-streaming.zh.md
rename to docs/subsystems/llm-streaming.zh.md
diff --git a/docs/core-data-structures/lsp.i18n.yaml b/docs/subsystems/lsp.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/lsp.i18n.yaml
rename to docs/subsystems/lsp.i18n.yaml
diff --git a/docs/core-data-structures/lsp.md b/docs/subsystems/lsp.md
similarity index 100%
rename from docs/core-data-structures/lsp.md
rename to docs/subsystems/lsp.md
diff --git a/docs/core-data-structures/lsp.zh.md b/docs/subsystems/lsp.zh.md
similarity index 100%
rename from docs/core-data-structures/lsp.zh.md
rename to docs/subsystems/lsp.zh.md
diff --git a/docs/core-data-structures/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/persistence.i18n.yaml
rename to docs/subsystems/persistence.i18n.yaml
index eccd3f146e..697094b490 100644
--- a/docs/core-data-structures/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/core-data-structures/persistence.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/persistence.md
 persistence.md: 177d596d3d01134266f139b47430e1e5064d04d6
 persistence.zh.md: 6582c0d7d02d1976d5c3ca3322284098130ed4ad
diff --git a/docs/core-data-structures/persistence.md b/docs/subsystems/persistence.md
similarity index 100%
rename from docs/core-data-structures/persistence.md
rename to docs/subsystems/persistence.md
diff --git a/docs/core-data-structures/persistence.zh.md b/docs/subsystems/persistence.zh.md
similarity index 100%
rename from docs/core-data-structures/persistence.zh.md
rename to docs/subsystems/persistence.zh.md
diff --git a/docs/core-data-structures/pty.i18n.yaml b/docs/subsystems/pty.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/pty.i18n.yaml
rename to docs/subsystems/pty.i18n.yaml
diff --git a/docs/core-data-structures/pty.md b/docs/subsystems/pty.md
similarity index 100%
rename from docs/core-data-structures/pty.md
rename to docs/subsystems/pty.md
diff --git a/docs/core-data-structures/pty.zh.md b/docs/subsystems/pty.zh.md
similarity index 100%
rename from docs/core-data-structures/pty.zh.md
rename to docs/subsystems/pty.zh.md
diff --git a/docs/core-data-structures/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/sandbox.i18n.yaml
rename to docs/subsystems/sandbox.i18n.yaml
diff --git a/docs/core-data-structures/sandbox.md b/docs/subsystems/sandbox.md
similarity index 100%
rename from docs/core-data-structures/sandbox.md
rename to docs/subsystems/sandbox.md
diff --git a/docs/core-data-structures/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
similarity index 100%
rename from docs/core-data-structures/sandbox.zh.md
rename to docs/subsystems/sandbox.zh.md
diff --git a/docs/core-data-structures/scope.i18n.yaml b/docs/subsystems/scope.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/scope.i18n.yaml
rename to docs/subsystems/scope.i18n.yaml
diff --git a/docs/core-data-structures/scope.md b/docs/subsystems/scope.md
similarity index 100%
rename from docs/core-data-structures/scope.md
rename to docs/subsystems/scope.md
diff --git a/docs/core-data-structures/scope.zh.md b/docs/subsystems/scope.zh.md
similarity index 100%
rename from docs/core-data-structures/scope.zh.md
rename to docs/subsystems/scope.zh.md
diff --git a/docs/core-data-structures/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/session-query.i18n.yaml
rename to docs/subsystems/session-query.i18n.yaml
diff --git a/docs/core-data-structures/session-query.md b/docs/subsystems/session-query.md
similarity index 100%
rename from docs/core-data-structures/session-query.md
rename to docs/subsystems/session-query.md
diff --git a/docs/core-data-structures/session-query.zh.md b/docs/subsystems/session-query.zh.md
similarity index 100%
rename from docs/core-data-structures/session-query.zh.md
rename to docs/subsystems/session-query.zh.md
diff --git a/docs/core-data-structures/session-reference.i18n.yaml b/docs/subsystems/session-reference.i18n.yaml
similarity index 79%
rename from docs/core-data-structures/session-reference.i18n.yaml
rename to docs/subsystems/session-reference.i18n.yaml
index 85bbcf8877..f119c67913 100644
--- a/docs/core-data-structures/session-reference.i18n.yaml
+++ b/docs/subsystems/session-reference.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 docs/core-data-structures/session-reference.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/session-reference.md
 session-reference.md: 5375677f6a1748909743ca76d5191cb9e736a40a
 session-reference.zh.md: 3ff4a1719926bda0a9111482a7778a8c94553370
diff --git a/docs/core-data-structures/session-reference.md b/docs/subsystems/session-reference.md
similarity index 100%
rename from docs/core-data-structures/session-reference.md
rename to docs/subsystems/session-reference.md
diff --git a/docs/core-data-structures/session-reference.zh.md b/docs/subsystems/session-reference.zh.md
similarity index 100%
rename from docs/core-data-structures/session-reference.zh.md
rename to docs/subsystems/session-reference.zh.md
diff --git a/docs/core-data-structures/session-title.i18n.yaml b/docs/subsystems/session-title.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/session-title.i18n.yaml
rename to docs/subsystems/session-title.i18n.yaml
index ed9955472c..c85d4dfac1 100644
--- a/docs/core-data-structures/session-title.i18n.yaml
+++ b/docs/subsystems/session-title.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 docs/core-data-structures/session-title.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/session-title.md
 session-title.md: 7bced67f07df3f00471f02b766922cdc3e4fd29e
 session-title.zh.md: e8e501d3aafee49395da3d9a8efd4e91a724f09e
diff --git a/docs/core-data-structures/session-title.md b/docs/subsystems/session-title.md
similarity index 100%
rename from docs/core-data-structures/session-title.md
rename to docs/subsystems/session-title.md
diff --git a/docs/core-data-structures/session-title.zh.md b/docs/subsystems/session-title.zh.md
similarity index 100%
rename from docs/core-data-structures/session-title.zh.md
rename to docs/subsystems/session-title.zh.md
diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/session.i18n.yaml
rename to docs/subsystems/session.i18n.yaml
index 16e969bd94..dd7135e8d3 100644
--- a/docs/core-data-structures/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/core-data-structures/session.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/session.md
 session.md: 5d54b03df8ec3345e8bf04702f242e3aacf8ec39
 session.zh.md: 5a867cfe302bf02994bfe5a5a704bed55222e8ea
diff --git a/docs/core-data-structures/session.md b/docs/subsystems/session.md
similarity index 100%
rename from docs/core-data-structures/session.md
rename to docs/subsystems/session.md
diff --git a/docs/core-data-structures/session.zh.md b/docs/subsystems/session.zh.md
similarity index 100%
rename from docs/core-data-structures/session.zh.md
rename to docs/subsystems/session.zh.md
diff --git a/docs/core-data-structures/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/settings.i18n.yaml
rename to docs/subsystems/settings.i18n.yaml
index cf262dc1e9..f4518f4414 100644
--- a/docs/core-data-structures/settings.i18n.yaml
+++ b/docs/subsystems/settings.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 docs/core-data-structures/settings.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/settings.md
 settings.md: bd01c1d28407af9cab26f624a054a010e25a3ddd
 settings.zh.md: 1cb7f8b507f29f2b6876fd48b4c37284df235e53
diff --git a/docs/core-data-structures/settings.md b/docs/subsystems/settings.md
similarity index 100%
rename from docs/core-data-structures/settings.md
rename to docs/subsystems/settings.md
diff --git a/docs/core-data-structures/settings.zh.md b/docs/subsystems/settings.zh.md
similarity index 100%
rename from docs/core-data-structures/settings.zh.md
rename to docs/subsystems/settings.zh.md
diff --git a/docs/core-data-structures/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/skills.i18n.yaml
rename to docs/subsystems/skills.i18n.yaml
index d0ce7b7574..6ab9693cca 100644
--- a/docs/core-data-structures/skills.i18n.yaml
+++ b/docs/subsystems/skills.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 docs/core-data-structures/skills.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/skills.md
 skills.md: d862cbc07135680c2377b4c8c82c80d055344221
 skills.zh.md: 3f8c034ec2aa24b4acdbbc1e2ac27717c21649d5
diff --git a/docs/core-data-structures/skills.md b/docs/subsystems/skills.md
similarity index 100%
rename from docs/core-data-structures/skills.md
rename to docs/subsystems/skills.md
diff --git a/docs/core-data-structures/skills.zh.md b/docs/subsystems/skills.zh.md
similarity index 100%
rename from docs/core-data-structures/skills.zh.md
rename to docs/subsystems/skills.zh.md
diff --git a/docs/core-data-structures/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/spill.i18n.yaml
rename to docs/subsystems/spill.i18n.yaml
diff --git a/docs/core-data-structures/spill.md b/docs/subsystems/spill.md
similarity index 100%
rename from docs/core-data-structures/spill.md
rename to docs/subsystems/spill.md
diff --git a/docs/core-data-structures/spill.zh.md b/docs/subsystems/spill.zh.md
similarity index 100%
rename from docs/core-data-structures/spill.zh.md
rename to docs/subsystems/spill.zh.md
diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/subagent.i18n.yaml
rename to docs/subsystems/subagent.i18n.yaml
diff --git a/docs/core-data-structures/subagent.md b/docs/subsystems/subagent.md
similarity index 100%
rename from docs/core-data-structures/subagent.md
rename to docs/subsystems/subagent.md
diff --git a/docs/core-data-structures/subagent.zh.md b/docs/subsystems/subagent.zh.md
similarity index 100%
rename from docs/core-data-structures/subagent.zh.md
rename to docs/subsystems/subagent.zh.md
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/subprocess.i18n.yaml
rename to docs/subsystems/subprocess.i18n.yaml
diff --git a/docs/core-data-structures/subprocess.md b/docs/subsystems/subprocess.md
similarity index 100%
rename from docs/core-data-structures/subprocess.md
rename to docs/subsystems/subprocess.md
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
similarity index 100%
rename from docs/core-data-structures/subprocess.zh.md
rename to docs/subsystems/subprocess.zh.md
diff --git a/docs/core-data-structures/system-prompt.i18n.yaml b/docs/subsystems/system-prompt.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/system-prompt.i18n.yaml
rename to docs/subsystems/system-prompt.i18n.yaml
index 8d9cd0897f..5c39e3cbcb 100644
--- a/docs/core-data-structures/system-prompt.i18n.yaml
+++ b/docs/subsystems/system-prompt.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 docs/core-data-structures/system-prompt.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/system-prompt.md
 system-prompt.md: 59193c1881abcadbc8a1778cde92f5a6572eee24
 system-prompt.zh.md: 41e45417817895ccf6def70e510eca7422a65e41
diff --git a/docs/core-data-structures/system-prompt.md b/docs/subsystems/system-prompt.md
similarity index 100%
rename from docs/core-data-structures/system-prompt.md
rename to docs/subsystems/system-prompt.md
diff --git a/docs/core-data-structures/system-prompt.zh.md b/docs/subsystems/system-prompt.zh.md
similarity index 100%
rename from docs/core-data-structures/system-prompt.zh.md
rename to docs/subsystems/system-prompt.zh.md
diff --git a/docs/core-data-structures/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/tasks.i18n.yaml
rename to docs/subsystems/tasks.i18n.yaml
diff --git a/docs/core-data-structures/tasks.md b/docs/subsystems/tasks.md
similarity index 100%
rename from docs/core-data-structures/tasks.md
rename to docs/subsystems/tasks.md
diff --git a/docs/core-data-structures/tasks.zh.md b/docs/subsystems/tasks.zh.md
similarity index 100%
rename from docs/core-data-structures/tasks.zh.md
rename to docs/subsystems/tasks.zh.md
diff --git a/docs/core-data-structures/token-meter.i18n.yaml b/docs/subsystems/token-meter.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/token-meter.i18n.yaml
rename to docs/subsystems/token-meter.i18n.yaml
diff --git a/docs/core-data-structures/token-meter.md b/docs/subsystems/token-meter.md
similarity index 100%
rename from docs/core-data-structures/token-meter.md
rename to docs/subsystems/token-meter.md
diff --git a/docs/core-data-structures/token-meter.zh.md b/docs/subsystems/token-meter.zh.md
similarity index 100%
rename from docs/core-data-structures/token-meter.zh.md
rename to docs/subsystems/token-meter.zh.md
diff --git a/docs/core-data-structures/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
similarity index 80%
rename from docs/core-data-structures/tools.i18n.yaml
rename to docs/subsystems/tools.i18n.yaml
index cd2add6a82..a30f122038 100644
--- a/docs/core-data-structures/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/core-data-structures/tools.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/tools.md
 tools.md: 853eed16cff451edcc32bc3aa5c6bc7cabb0f518
 tools.zh.md: ec8809f6bebd185404828c5c5879f8eff832ea9a
diff --git a/docs/core-data-structures/tools.md b/docs/subsystems/tools.md
similarity index 100%
rename from docs/core-data-structures/tools.md
rename to docs/subsystems/tools.md
diff --git a/docs/core-data-structures/tools.zh.md b/docs/subsystems/tools.zh.md
similarity index 100%
rename from docs/core-data-structures/tools.zh.md
rename to docs/subsystems/tools.zh.md
diff --git a/docs/core-data-structures/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/typert.i18n.yaml
rename to docs/subsystems/typert.i18n.yaml
diff --git a/docs/core-data-structures/typert.md b/docs/subsystems/typert.md
similarity index 100%
rename from docs/core-data-structures/typert.md
rename to docs/subsystems/typert.md
diff --git a/docs/core-data-structures/typert.zh.md b/docs/subsystems/typert.zh.md
similarity index 100%
rename from docs/core-data-structures/typert.zh.md
rename to docs/subsystems/typert.zh.md
diff --git a/docs/core-data-structures/user-interaction.i18n.yaml b/docs/subsystems/user-interaction.i18n.yaml
similarity index 79%
rename from docs/core-data-structures/user-interaction.i18n.yaml
rename to docs/subsystems/user-interaction.i18n.yaml
index 3768cfcf7b..80ebb810c8 100644
--- a/docs/core-data-structures/user-interaction.i18n.yaml
+++ b/docs/subsystems/user-interaction.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 docs/core-data-structures/user-interaction.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/user-interaction.md
 user-interaction.md: ec22eb28e9554d6454bf2670f73f2e9b199df014
 user-interaction.zh.md: 814f8911e41aecf568f627f76f8239bac4ea719b
diff --git a/docs/core-data-structures/user-interaction.md b/docs/subsystems/user-interaction.md
similarity index 100%
rename from docs/core-data-structures/user-interaction.md
rename to docs/subsystems/user-interaction.md
diff --git a/docs/core-data-structures/user-interaction.zh.md b/docs/subsystems/user-interaction.zh.md
similarity index 100%
rename from docs/core-data-structures/user-interaction.zh.md
rename to docs/subsystems/user-interaction.zh.md
diff --git a/docs/core-data-structures/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/web.i18n.yaml
rename to docs/subsystems/web.i18n.yaml
diff --git a/docs/core-data-structures/web.md b/docs/subsystems/web.md
similarity index 100%
rename from docs/core-data-structures/web.md
rename to docs/subsystems/web.md
diff --git a/docs/core-data-structures/web.zh.md b/docs/subsystems/web.zh.md
similarity index 100%
rename from docs/core-data-structures/web.zh.md
rename to docs/subsystems/web.zh.md
diff --git a/docs/core-data-structures/workflow.i18n.yaml b/docs/subsystems/workflow.i18n.yaml
similarity index 100%
rename from docs/core-data-structures/workflow.i18n.yaml
rename to docs/subsystems/workflow.i18n.yaml
diff --git a/docs/core-data-structures/workflow.md b/docs/subsystems/workflow.md
similarity index 100%
rename from docs/core-data-structures/workflow.md
rename to docs/subsystems/workflow.md
diff --git a/docs/core-data-structures/workflow.zh.md b/docs/subsystems/workflow.zh.md
similarity index 100%
rename from docs/core-data-structures/workflow.zh.md
rename to docs/subsystems/workflow.zh.md
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 699617eef4..a100469102 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -3,7 +3,7 @@
 
 # Tool Schema Catalog
 
-Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [core-data-structures/](core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.
+Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [subsystems/](subsystems/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.
 
 This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator's boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).
 
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index 978de64ed1..eee269c121 100644
--- a/packages/bash/bash/README.i18n.yaml
+++ b/packages/bash/bash/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/bash/bash/README.md
-README.md: 88f519a21a0889d6b7649502c51077940c23709f
-README.zh.md: 294044692133da8baa57583146352e84c1ff9946
+README.md: 690f4e61740faf2648ecbc7f5995ec0fdaa64aee
+README.zh.md: c343e17bfd97eaf17316c034c263b0c71bb8327a
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index 88f519a21a..690f4e6174 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -31,7 +31,7 @@ Implementations subclass `BashExecutor` and implement the abstract methods. Disp
 
 `BashExecRequest` (command, workdir?, timeoutMs?, stdoutMaxBytes?, signal?, stdin?, env?, dshEnv?, sandboxPolicy?) resolves to `BashExecSpec` (command, workdir, timeoutMs, stdoutMaxBytes, signal?, stdin?, env?, dshEnv?, sandboxPolicy) before execution. `stdoutMaxBytes` is a trusted foreground-run capture budget for consumers that must parse complete bounded stdout; the model-facing bash tool does not expose it. `sandboxPolicy` is optional on the request and required-but-nullable on the resolved spec: it carries the complete per-call mode and workspace root. The sandbox tool path resolves it from the calling session through `ctx.sandboxPolicy`; a direct sandbox-executor caller falls back to deployment policy, while a non-sandboxing executor carries the field and confines nothing.
 
-The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md).
+The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [subsystems/bash.md](../../../docs/subsystems/bash.md).
 
 `stdin` and ordinary `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload and `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` values. `dshEnv` is a separate trusted overlay restricted by type to managed keys; the exported `DSH_ENV_PREFIX` is the single source for that namespace, its `DshEnvironmentKey` template type, executor scrubbing, registry validation, derived built-in names, and model guidance. Model bash uses the current snapshot collected by `ctx.bashEnv`. Implementations remove inherited managed keys, then merge `dshEnv` after ordinary `env`, so an omitted current fact cannot fall back to stale ambient state and an `env` entry cannot displace a managed value. The model-facing tool exposes none of these as parameters. All three remain optional on the resolved spec; absent means no input/overlay. See [the bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [the session environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index 2940446921..c343e17bfd 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -31,7 +31,7 @@
 
 `BashExecRequest`（command、workdir?、timeoutMs?、stdoutMaxBytes?、signal?、stdin?、env?、dshEnv?、sandboxPolicy?）在执行前解析为 `BashExecSpec`（command、workdir、timeoutMs、stdoutMaxBytes、signal?、stdin?、env?、dshEnv?、sandboxPolicy）。`stdoutMaxBytes` 是受信任前台运行的捕获预算，用于必须解析完整有界 stdout 的消费方；面向模型的 bash 工具不公开该字段。`sandboxPolicy` 在请求上可选，在已解析 spec 上必填但可为 null：它携带完整的每次调用模式与工作区根目录。沙箱工具路径通过 `ctx.sandboxPolicy` 从调用会话解析它；沙箱执行器的直接调用方回退到部署策略，非沙箱执行器则携带该字段但不作限制。
 
-每会话沙箱模式覆盖词汇（`'sandbox/mode'` 事件、`effectiveSandboxMode(events)` fold 以及 `setSandboxMode(session, mode)` 写入路径）不位于此处。它是所有强制执行家族共享的策略状态，属于 [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/)。`run()` 返回 `BashRunResult`；`start()` 返回 `BashProcess`，其增量读取与终止方法由 `dsh-tool-bash` 适配为通用任务注册。沙箱执行器会在前台结果与已结算进程句柄上标记 `BashSandboxInfo`。详见 `src/types.ts` 与 [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md)。
+每会话沙箱模式覆盖词汇（`'sandbox/mode'` 事件、`effectiveSandboxMode(events)` fold 以及 `setSandboxMode(session, mode)` 写入路径）不位于此处。它是所有强制执行家族共享的策略状态，属于 [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/)。`run()` 返回 `BashRunResult`；`start()` 返回 `BashProcess`，其增量读取与终止方法由 `dsh-tool-bash` 适配为通用任务注册。沙箱执行器会在前台结果与已结算进程句柄上标记 `BashSandboxInfo`。详见 `src/types.ts` 与 [subsystems/bash.md](../../../docs/subsystems/bash.md)。
 
 `stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的统一来源。模型 bash 使用 `ctx.bashEnv` 收集的当前快照。实现会移除继承的受管 key，再在普通 `env` 之后合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态，`env` 条目也无法顶掉受管值。面向模型的工具不将这三者中的任何一个公开为参数。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index 1ab398842f..1252d99e0f 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: 5703540435b976cfc03987edca28e2b5cd24ae0d
-README.zh.md: 434b9bfa3d0d7f21fc262929ac72ff5ab15d5057
+README.md: 2bf39cac91798b1e0fdb679d2a9b674caceffe22
+README.zh.md: 330b5b0cb9d5c2bf3953354112f3488447e71f87
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index 5703540435..2bf39cac91 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -24,7 +24,7 @@ All three operations are **abstract** — the backend owns trigger policy, reten
 | `compactNow(agent, signal)` | Explicitly compact one useful balanced older span even below automatic pressure. It synchronously reserves idle turn admission before yielding, writes nothing when no useful span exists, records a standalone `compact/* { turn: null }` attempt before summarization, and awaits its durability checkpoint before release. Expected operational failures use `ManualCompactionError`; cancellation rethrows the exact abort reason. |
 | `compactRegion(start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) from `agent.session` into a single replacement node whose source is `COMPACT_CHECKPOINT_SOURCE`. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
 
-`CompactionResult` keeps the raw summary and bookkeeping-event seqs available to callers alongside the shadowed range and token accounting; its drift-checked shape lives in the [compaction data-structure reference](../../../docs/core-data-structures/compaction.md#compactionresult).
+`CompactionResult` keeps the raw summary and bookkeeping-event seqs available to callers alongside the shadowed range and token accounting; its drift-checked shape lives in the [compaction data-structure reference](../../../docs/subsystems/compaction.md#compactionresult).
 
 `compactIfNeeded` and `compactNow` take a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization. Automatic and explicit-region brackets recover their numeric owner from the currently open turn. Manual brackets require no open turn and stamp `turn: null`.
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index 434b9bfa3d..330b5b0cb9 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -24,7 +24,7 @@
 | `compactNow(agent, signal)` | 即使未达到自动压力，也显式压缩一段有效、平衡的较早范围。该操作会在让出控制权前同步预留空闲轮次接纳；没有有效范围时不写入任何内容；在摘要前记录独立的 `compact/* { turn: null }` 尝试；释放预留前等待其持久性检查点。预期操作失败使用 `ManualCompactionError`；取消会原样重新抛出 abort 原因。 |
 | `compactRegion(start, end, agent, signal?)` | 强制将表层节点 `[start, end]`（包含两端 seq）从 `agent.session` 摘要为单个替换节点，其源为 `COMPACT_CHECKPOINT_SOURCE`。如果压缩已在进行、`start`／`end` 不是表层节点，或 `start` 在表层上位于 `end` 之后，则**抛出异常**。该范围是表层位置范围，不是数值 seq 区间：在之前的 replace 将新生成的高 seq 摘要节点放到已遮蔽范围的位置之后，表层顺序不再跟随 seq 顺序。 |
 
-`CompactionResult` 向调用方保留原始摘要与记录操作过程的事件 seq，同时保留已遮蔽范围与 token 计量；其结构由漂移检查保障，定义见 [压缩数据结构参考](../../../docs/core-data-structures/compaction.md#compactionresult)。
+`CompactionResult` 向调用方保留原始摘要与记录操作过程的事件 seq，同时保留已遮蔽范围与 token 计量；其结构由漂移检查保障，定义见 [压缩数据结构参考](../../../docs/subsystems/compaction.md#compactionresult)。
 
 `compactIfNeeded` 和 `compactNow` 必须传入 `signal`；`compactRegion` 的该参数可选。通过 `ctx.llm.stream()` 摘要的后端**必须** 将它转发到调用的 `GenerateOptions.signal`，因此 abort 或 fiber dispose（资源释放）会停止进行中的摘要。自动和显式范围标记对会从当前打开的轮次恢复其数字形式归属。手动标记对不要求存在打开的轮次，并标记 `turn: null`。
 
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index 0b2d50957e..c30b37e549 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
-README.md: e2c014a1448125b23475d6cdf52c02f10fc54794
-README.zh.md: a4aeead796961bd66a6c7ca1f9a66dffb60eba5d
+README.md: 07ee53006b390e5ad3979502b2f1aa24f5a6ce7a
+README.zh.md: d4a90de10b92a489f8f575b926d758b45d8f5051
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index e2c014a144..07ee53006b 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -56,7 +56,7 @@ The shared [storage codec](src/chunk-rows.ts) losslessly converts event sequence
 
 ### Surface types
 
-This package owns ordered surface projection, replacement validation, replay, and the type guards that distinguish append-origin from replacement events. The [surface type catalog](../../../docs/core-data-structures/session.md#surface-types) owns the exact shapes and field semantics. A human transcript must project append-origin events rather than `session.surface`, because landed replacements shadow history the reader already saw; model-facing consumers continue to read `session.surface`.
+This package owns ordered surface projection, replacement validation, replay, and the type guards that distinguish append-origin from replacement events. The [surface type catalog](../../../docs/subsystems/session.md#surface-types) owns the exact shapes and field semantics. A human transcript must project append-origin events rather than `session.surface`, because landed replacements shadow history the reader already saw; model-facing consumers continue to read `session.surface`.
 
 ### Request-header reconstruction (`request-header.ts`)
 
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index a4aeead796..d4a90de10b 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -56,7 +56,7 @@
 
 ### Surface 类型
 
-此包拥有有序 surface 投影、替换校验、回放，以及区分追加来源事件与替换事件的类型守卫。[surface 类型目录](../../../docs/core-data-structures/session.md#surface-types)拥有精确形状与字段语义。面向人的 transcript（文本记录）必须投影追加来源事件，而不是 `session.surface`，因为已落地的替换会遮蔽读者已经看到的历史；面向模型的消费方继续读取 `session.surface`。
+此包拥有有序 surface 投影、替换校验、回放，以及区分追加来源事件与替换事件的类型守卫。[surface 类型目录](../../../docs/subsystems/session.md#surface-types)拥有精确形状与字段语义。面向人的 transcript（文本记录）必须投影追加来源事件，而不是 `session.surface`，因为已落地的替换会遮蔽读者已经看到的历史；面向模型的消费方继续读取 `session.surface`。
 
 ### 请求头重建（`request-header.ts`）
 
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index b49350c1a3..657de4578e 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -39,7 +39,7 @@ import { renderToolsSdkPy } from './py-types.ts'
  * the flavor table is checked against too, so any of the three left out is a
  * typecheck failure. What no check reaches is the prose that names the values
  * instead of deriving them: the seam's `dsh-code-runtime` README pair, its
- * `CodeRuntime.language` JSDoc, and `docs/core-data-structures/code-runtime.md`
+ * `CodeRuntime.language` JSDoc, and `docs/subsystems/code-runtime.md`
  * with its zh pair, plus this package's own README pair and the
  * {@link Config.mode} JSDoc.
  */
diff --git a/packages/goal/goal/README.i18n.yaml b/packages/goal/goal/README.i18n.yaml
index d918caf377..6362a6d1e9 100644
--- a/packages/goal/goal/README.i18n.yaml
+++ b/packages/goal/goal/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/goal/goal/README.md
-README.md: fc2a672c11c68ad72437251b087a274e1c4388d3
-README.zh.md: eaaae5b333151b1d936effc593b21cac515471e2
+README.md: fc2fd8791096bcc9077ef7972da86b0e07c6f18e
+README.zh.md: 311ec1d03436cc45bbea28df96e66579852058b0
diff --git a/packages/goal/goal/README.md b/packages/goal/goal/README.md
index fc2a672c11..fc2fd87910 100644
--- a/packages/goal/goal/README.md
+++ b/packages/goal/goal/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Event-sourced same-session goal state. The service retains one current completion objective in an agent's existing session while keeping permission to continue as process-local activation. The [goal-domain Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) owns the design rationale; the [goal type catalog](../../../docs/core-data-structures/goal.md) records the literal data shapes.
+Event-sourced same-session goal state. The service retains one current completion objective in an agent's existing session while keeping permission to continue as process-local activation. The [goal-domain Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) owns the design rationale; the [goal type catalog](../../../docs/subsystems/goal.md) records the literal data shapes.
 
 ## Config
 
diff --git a/packages/goal/goal/README.zh.md b/packages/goal/goal/README.zh.md
index eaaae5b333..311ec1d034 100644
--- a/packages/goal/goal/README.zh.md
+++ b/packages/goal/goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前完成目标，同时将继续执行的权限作为进程本地续行启用状态。[goal 领域 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) 负责设计理由；[goal 类型目录](../../../docs/core-data-structures/goal.md)记录具体的数据形状。
+事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前完成目标，同时将继续执行的权限作为进程本地续行启用状态。[goal 领域 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) 负责设计理由；[goal 类型目录](../../../docs/subsystems/goal.md)记录具体的数据形状。
 
 ## 配置
 
diff --git a/packages/sandbox/sandbox/README.i18n.yaml b/packages/sandbox/sandbox/README.i18n.yaml
index 11f2a2ed86..99a5265418 100644
--- a/packages/sandbox/sandbox/README.i18n.yaml
+++ b/packages/sandbox/sandbox/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/sandbox/sandbox/README.md
-README.md: 1b522b2c72d00bfed89650aa7f22b65a72d26085
-README.zh.md: adccd4421a74ef073ad3ffc3a23bccb0354d99aa
+README.md: 8c1c747f6c7178f9c8c1a9827675ffa98f29aa6d
+README.zh.md: e43d1918a99fa96688632551a8f861c2c91f9c2a
diff --git a/packages/sandbox/sandbox/README.md b/packages/sandbox/sandbox/README.md
index 1b522b2c72..8c1c747f6c 100644
--- a/packages/sandbox/sandbox/README.md
+++ b/packages/sandbox/sandbox/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Abstract process-sandbox seam. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxExecutionPolicy` (the complete per-call mode + workspace root), `SandboxPolicy` (its confined subset), and the fail-closed `SANDBOX_UNAVAILABLE` error. Interface package of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): depends only on cordis (+ the harness error base), never on a backend.
 
-The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus the selected backend's enforcement completeness, denial dialect (`denialSignatures`), and structured runner-failure evidence (`runnerFailureRules`); when no backend is usable it throws rather than passing the argv through unconfined. The [core type catalog](../../../docs/core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects) owns the exact classifier shape.
+The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus the selected backend's enforcement completeness, denial dialect (`denialSignatures`), and structured runner-failure evidence (`runnerFailureRules`); when no backend is usable it throws rather than passing the argv through unconfined. The [core type catalog](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects) owns the exact classifier shape.
 
 Policy rides the call, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is just a new call with a wider policy.
 
diff --git a/packages/sandbox/sandbox/README.zh.md b/packages/sandbox/sandbox/README.zh.md
index adccd4421a..e43d1918a9 100644
--- a/packages/sandbox/sandbox/README.zh.md
+++ b/packages/sandbox/sandbox/README.zh.md
@@ -4,7 +4,7 @@
 
 抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务契约（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。
 
-用一句话概括契约：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
+用一句话概括契约：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
 
 策略随调用传递，而不属于提供方：两个消费方可以同时按不同策略施加限制（bash 使用 `read-only`，而受限制的子 agent（智能体）保持其状态目录可写）；获批的升权重试只是使用更宽策略发起的新调用。
 
diff --git a/packages/session/session-title/README.i18n.yaml b/packages/session/session-title/README.i18n.yaml
index b13c6ce917..f45602ce97 100644
--- a/packages/session/session-title/README.i18n.yaml
+++ b/packages/session/session-title/README.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 packages/session-title/session-title/README.md
-README.md: 9a5ec27c36f3411add37ebe231262eb5d205bc9e
-README.zh.md: 3960be40e74507279ed2f21927ee8ad4224fe138
+#   pnpm run verify-translation-pairing --write packages/session/session-title/README.md
+README.md: 13a2a1c298c3abb8c8987b9373edc46a071ce9db
+README.zh.md: 9e271c044033ce17b5c8c744fe7a9cf433c7f473
diff --git a/packages/session/session-title/README.md b/packages/session/session-title/README.md
index 9a5ec27c36..13a2a1c298 100644
--- a/packages/session/session-title/README.md
+++ b/packages/session/session-title/README.md
@@ -31,7 +31,7 @@ All limits are required; the library supplies no defaults.
 
 A provider supplies a branded stable id, automatic mode (`first-message` or `all-user-messages`), and `generate(request)`. The request carries the live session, all eligible messages through one fixed revision, the current logged main-request route when available, and cancellation. The result identifies a non-empty title, unique ordered source-message seqs from that request, and optional model provenance. The service normalizes and validates the result before it becomes durable.
 
-See the [session-title data structures](../../../docs/core-data-structures/session-title.md) and [implemented decision](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md).
+See the [session-title data structures](../../../docs/subsystems/session-title.md) and [implemented decision](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md).
 
 ## Model Experience
 
diff --git a/packages/session/session-title/README.zh.md b/packages/session/session-title/README.zh.md
index 3960be40e7..9e271c0440 100644
--- a/packages/session/session-title/README.zh.md
+++ b/packages/session/session-title/README.zh.md
@@ -31,7 +31,7 @@ Fork 出的会话会原样继承种子中的标题事件。首消息节奏不会
 
 提供方会提供带品牌类型的稳定 id、自动模式（`first-message` 或 `all-user-messages`）和 `generate(request)`。请求携带活跃会话、截至一次固定修订的所有符合条件消息、可用时当前已记录的主请求路由，以及取消信号。结果包含非空标题、该请求中唯一且有序的来源消息 seq，以及可选的模型来源信息。服务会在结果持久保存前进行规范化和验证。
 
-参见[会话标题数据结构](../../../docs/core-data-structures/session-title.md)与[已实现决策](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)。
+参见[会话标题数据结构](../../../docs/subsystems/session-title.md)与[已实现决策](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)。
 
 ## 模型体验
 
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index e67bf1a87f..86694c3c23 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: ec4a4e3328a5a600441d2e7983b3844f4ccc5e91
-README.zh.md: 3da79995fad9a2c8f2a6020ae18152a0e4459c71
+README.md: 6e4b9a9c50bc54a4752930ec14269d2c15233a76
+README.zh.md: d756cd9b7117d7ce9a2e79c6469d9fc188c9600b
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index ec4a4e3328..6e4b9a9c50 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -15,7 +15,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
-See the [subprocess data-structure catalog](../../../docs/core-data-structures/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+See the [subprocess data-structure catalog](../../../docs/subsystems/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 ## Model Experience
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 3da79995fa..d756cd9b71 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -15,7 +15,7 @@
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地的普通 spawn 与终端 spawn 都应用该定义；拥有自身 spawn 的 SDK 管理传输可直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
-参见[子进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+参见[子进程数据结构目录](../../../docs/subsystems/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 ## 模型体验
 
diff --git a/packages/tasks/tasks/README.i18n.yaml b/packages/tasks/tasks/README.i18n.yaml
index 7ceb8ff432..1d803e486e 100644
--- a/packages/tasks/tasks/README.i18n.yaml
+++ b/packages/tasks/tasks/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/tasks/tasks/README.md
-README.md: 2f822bad139020f0ebae0165aa4e8893853f635d
-README.zh.md: fdc619fbb46267b2ae550c85cb14fcf8a916f638
+README.md: b5a7380e0cb7df5dd20baecea8656db2aad3460a
+README.zh.md: f2e4b10d30d81c840f5598141bbe246634bf2884
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 2f822bad13..b5a7380e0c 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -20,7 +20,7 @@ Owned access compares the task's `SessionId` with the caller's. Ids such as `bas
 
 Implementations also owe the lifecycle semantics of the contract: registrations outlive producer and control-surface fibers, owner and service disposal cancel live work and await compliant producers, and settlement is first-wins — one terminal record, one round of contained listener notification, released waiters.
 
-See the [task type catalog](../../../docs/core-data-structures/tasks.md), the [runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md), and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md).
+See the [task type catalog](../../../docs/subsystems/tasks.md), the [runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md), and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md).
 
 ## Model Experience
 
diff --git a/packages/tasks/tasks/README.zh.md b/packages/tasks/tasks/README.zh.md
index fdc619fbb4..f2e4b10d30 100644
--- a/packages/tasks/tasks/README.zh.md
+++ b/packages/tasks/tasks/README.zh.md
@@ -20,7 +20,7 @@
 
 实现还必须兑现契约的生命周期语义：注册的存续期长于生产方 fiber 与控制表层 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
 
-参见[任务类型目录](../../../docs/core-data-structures/tasks.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)。
+参见[任务类型目录](../../../docs/subsystems/tasks.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)。
 
 ## 模型体验
 
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index e5c2c15a00..d62739acdd 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -701,7 +701,7 @@ function typeLinks(signature: string, linkedTypePages: Readonly<Record<string, s
     if (new RegExp(`\\b${name}\\b`).test(signature)) seen.add(name)
   }
   if (seen.size === 0) return ''
-  const links = [...seen].sort().map(n => `[${n}](../core-data-structures/${linkedTypePages[n]})`)
+  const links = [...seen].sort().map(n => `[${n}](../subsystems/${linkedTypePages[n]})`)
   return `Types: ${links.join(' · ')}`
 }
 
@@ -756,7 +756,7 @@ export function renderEvents(events: EventEntry[], policy: CordisCatalogPolicy):
     ...BANNER,
     '# Cordis Events Catalog',
     '',
-    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around.',
+    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.',
     '',
     GATE_NOTICE,
     '',
@@ -796,7 +796,7 @@ export function renderServices(services: ServiceEntry[], policy: CordisCatalogPo
     ...BANNER,
     '# Cordis Services Catalog',
     '',
-    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
+    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
     '',
     GATE_NOTICE,
     '',
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index d920ea82ca..edf653c3f4 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -155,7 +155,7 @@ describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => {
       '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param preset - deployment metadata outside the core catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, preset: PresetSpec, signal: AbortSignal): Promise<T>',
     ))
     expect(events).toHaveLength(1)
-    expect(renderEvents(events)).toContain('Types: [SessionEvent](../core-data-structures/core.md)')
+    expect(renderEvents(events)).toContain('Types: [SessionEvent](../subsystems/core.md)')
     expect(renderEvents(events)).not.toContain('[PresetSpec]')
   })
 
diff --git a/scripts/gen-config-catalog.ts b/scripts/gen-config-catalog.ts
index 920688df6d..ebceec916b 100644
--- a/scripts/gen-config-catalog.ts
+++ b/scripts/gen-config-catalog.ts
@@ -777,7 +777,7 @@ function requiresLine(inject: string[]): string {
 }
 
 /** Render one reference as a link: another plugin's config type → its section,
- * a curated core-data-structures name → its page, any other workspace type →
+ * a curated subsystems name → its page, any other workspace type →
  * its source file, an external type → named with its module, unlinked. */
 function refLink(ref: TypeRef, byName: Map<string, CatalogEntry>): string {
   const target = byName.get(ref.specifier)
@@ -785,7 +785,7 @@ function refLink(ref: TypeRef, byName: Map<string, CatalogEntry>): string {
     return `[\`${ref.alias}\`](#${slug(target.pkg)})`
   }
   const page = LINK_MAP[ref.imported]
-  if (page) return `[\`${ref.alias}\`](core-data-structures/${page})`
+  if (page) return `[\`${ref.alias}\`](subsystems/${page})`
   if (target) return `[\`${ref.alias}\`](../${target.entry})`
   return `\`${ref.alias}\` (\`${ref.specifier}\`)`
 }
@@ -819,7 +819,7 @@ export function render(entries: CatalogEntry[]): string {
     '',
     '# Plugin Config Catalog',
     '',
-    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md) documents the types these declarations reference.',
+    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
     '',
     'This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.',
     '',
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 302ec7fdd9..d9f3803547 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -18,7 +18,7 @@ const OUT_EVENTS = 'docs/cordis-catalog/events.md'
 const OUT_SERVICES = 'docs/cordis-catalog/services.md'
 const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts'
 
-/** One primary core-data-structures page per project type used by a generated signature. */
+/** One primary subsystems page per project type used by a generated signature. */
 export const LINK_MAP: Readonly<Record<string, string>> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index e6d6acbdf2..4f72b1d953 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -1344,7 +1344,7 @@ function renderIndex(docs: GraphDoc[]): string {
   const maintenance = 'mixed: each linked page declares generated, hybrid, or curated mode'
   return [
     ...generatedHeader('Documentation Graph Index'),
-    'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md).',
+    'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [subsystems/](subsystems/core.md).',
     '',
     'The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).',
     '',
diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts
index 685e4b65ef..800497ddb7 100644
--- a/scripts/gen-persistence-catalog.ts
+++ b/scripts/gen-persistence-catalog.ts
@@ -31,7 +31,7 @@ const EVENT_ENVELOPE_TYPE_NAMES = [
 
 type EventEnvelopeTypeName = typeof EVENT_ENVELOPE_TYPE_NAMES[number]
 
-/** Primary core-data-structures page for linked payload types. */
+/** Primary subsystems page for linked payload types. */
 const LINK_MAP: Record<string, string> = {
   CallId: 'core.md',
   ContentBlock: 'core.md',
@@ -330,7 +330,7 @@ function typeLinks(payload: string): string {
     if (new RegExp(`\\b${name}\\b`).test(payload)) seen.add(name)
   }
   if (seen.size === 0) return ''
-  const links = [...seen].sort().map(n => `[${n}](core-data-structures/${LINK_MAP[n]})`)
+  const links = [...seen].sort().map(n => `[${n}](subsystems/${LINK_MAP[n]})`)
   return `Types: ${links.join(' · ')}`
 }
 
@@ -352,11 +352,11 @@ export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnv
     '',
     '# Session Persistence Event Catalog',
     '',
-    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](core-data-structures/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
+    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
     '',
     'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).',
     '',
-    'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.',
+    'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.',
     '',
     '## Event envelope',
     '',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 55ec5eb57f..39ed4d7620 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -608,7 +608,7 @@ export function render(catalog: ToolCatalog): string {
     '',
     '# Tool Schema Catalog',
     '',
-    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [core-data-structures/](core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
+    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [subsystems/](subsystems/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
     '',
     'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).',
     '',
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 89e417558c..ebdce88f6d 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -271,7 +271,7 @@ describe('docsPages locale routes', () => {
 
   it('projects translated core-data pages while retaining explicit English fallbacks', () => {
     const rootPages = docsPages.filter(page => (
-      page.locale === 'root' && page.route.startsWith('reference/core-data-structures/')
+      page.locale === 'root' && page.route.startsWith('reference/subsystems/')
     ))
     const translated = rootPages.filter(page => page.contentLocale === 'zh-CN')
     const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US')
@@ -279,9 +279,9 @@ describe('docsPages locale routes', () => {
     expect(translated).toHaveLength(20)
     expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true)
     expect(fallbacks.map(page => page.source).sort()).toEqual([
-      'docs/core-data-structures/commands.md',
-      'docs/core-data-structures/goal.md',
-      'docs/core-data-structures/pty.md',
+      'docs/subsystems/commands.md',
+      'docs/subsystems/goal.md',
+      'docs/subsystems/pty.md',
     ])
   })
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 40b3f620e3..3d1ca11612 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](subsystems/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](subsystems/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 9180a3bd9a..56c1b094be 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -2,1566 +2,1566 @@
   "comment": "Maps each primary ` ```ts type-equiv ` or ` ```ts public-api ` block (by doc + declared symbol + projection) to the source declaration and original JSDoc it must match. Paired `.zh.md` blocks are byte-identical derivatives checked through their unsuffixed sibling and have no duplicate entry. Omit projection for the complete declaration; use public-api with a ` ```ts public-api ` block for a body-stripped public class declaration. verify-type-equiv.ts enforces a 1:1 correspondence between primary blocks and entries. Add an entry when you add a primary source-equivalence block; remove it when you remove the block.",
   "entries": [
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "Branded",
       "source": "packages/util/brand/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ContentBlockMap",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "AssistantProvenance",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "Message",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "MessageSourceMap",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ContextForm",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ContextSnapshotSection",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ContextFormed",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "FinishReasonMap",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "AdapterRegistrationHandle",
       "source": "packages/llm/llm/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmProviderInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmModelInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmModelDiscoveryRequest",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmDiscoveredModel",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmModelContext",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ReasoningEffortId",
       "source": "packages/llm/llm/src/brand.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmReasoningEffortInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmModelReasoningInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmResolvedModelInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "GenerateOptions",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "ToolSchema",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmCallConfig",
       "source": "packages/llm/llm/src/call-config.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmCallConfigAdapterDefaults",
       "source": "packages/llm/llm/src/call-config.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "SessionEvent",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "InboxTarget",
       "source": "packages/core/agent/src/inbox.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "CancelOptions",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "AgentCancelCause",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "Agent",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "PreStepDecision",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "RequestErrorAction",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "SessionStartSource",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/scope.md",
+      "doc": "docs/subsystems/scope.md",
       "symbol": "ScopeKey",
       "source": "packages/core/scope/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/scope.md",
+      "doc": "docs/subsystems/scope.md",
       "symbol": "Scoped",
       "source": "packages/core/scope/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/scope.md",
+      "doc": "docs/subsystems/scope.md",
       "symbol": "Scope",
       "source": "packages/core/scope/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/scope.md",
+      "doc": "docs/subsystems/scope.md",
       "symbol": "ScopeLayer",
       "source": "packages/core/scope/src/store.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalRef",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalPhase",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalBlockReason",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalSnapshot",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalView",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalSnapshotChangeMeta",
       "source": "packages/goal/goal/src/domain.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalClearChangeMeta",
       "source": "packages/goal/goal/src/domain.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalMessageSource",
       "source": "packages/goal/goal/src/domain.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "CreateGoalRequest",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "EditGoalRequest",
       "source": "packages/goal/goal/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/goal.md",
+      "doc": "docs/subsystems/goal.md",
       "symbol": "GoalChanged",
       "source": "packages/goal/goal/src/domain.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "CommandInputDescriptor",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "CommandDefinition",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "CommandInvocation",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "CommandResult",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "CommandDescriptor",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/commands.md",
+      "doc": "docs/subsystems/commands.md",
       "symbol": "ParsedCommand",
       "source": "packages/interaction/commands/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/system-prompt.md",
+      "doc": "docs/subsystems/system-prompt.md",
       "symbol": "AssembleContext",
       "source": "packages/core/system-prompt/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/system-prompt.md",
+      "doc": "docs/subsystems/system-prompt.md",
       "symbol": "PromptContext",
       "source": "packages/core/system-prompt/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/system-prompt.md",
+      "doc": "docs/subsystems/system-prompt.md",
       "symbol": "PromptSection",
       "source": "packages/core/system-prompt/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/system-prompt.md",
+      "doc": "docs/subsystems/system-prompt.md",
       "symbol": "ToolProviderResult",
       "source": "packages/core/system-prompt/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "StreamChunk",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmFailure",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "TokenUsage",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ContentBlockMap",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "AppIdentity",
       "source": "packages/llm/llm/src/attribution.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "BlockAssembler",
       "source": "packages/llm/llm/src/assembler.ts",
       "projection": "public-api"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "PreparedLlmCall",
       "source": "packages/llm/llm/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/llm-streaming.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmAdapter",
       "source": "packages/llm/llm/src/index.ts",
       "projection": "public-api"
     },
     {
-      "doc": "docs/core-data-structures/token-meter.md",
+      "doc": "docs/subsystems/token-meter.md",
       "symbol": "TokenMeasurement",
       "source": "packages/llm/token-meter/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/token-meter.md",
+      "doc": "docs/subsystems/token-meter.md",
       "symbol": "TokenSurfaceNode",
       "source": "packages/llm/token-meter/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "UserMessage",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SessionEventMap",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "EpochHeader",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "RequestContext",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "TodoItem",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SessionEvent",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "TurnEndCancelCause",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "TurnEndReasonMap",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SurfaceEventType",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SurfaceOp",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SurfaceIntent",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SessionSurface",
       "source": "packages/core/session/src/surface.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SurfaceFoldReplacement",
       "source": "packages/core/session/src/surface.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "SurfaceFoldResult",
       "source": "packages/core/session/src/surface.ts"
     },
     {
-      "doc": "docs/core-data-structures/session.md",
+      "doc": "docs/subsystems/session.md",
       "symbol": "Session",
       "source": "packages/core/session/src/index.ts",
       "projection": "public-api"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionHeader",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "CreateSessionOptions",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "RestoredSessionOptions",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "PrepareSessionOptions",
       "source": "packages/core/session/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionPreparationOptions",
       "source": "packages/core/session/src/preparation.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionPreparation",
       "source": "packages/core/session/src/preparation.ts",
       "projection": "public-api"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionInspection",
       "source": "packages/session/session-persistence/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionLocation",
       "source": "packages/session/session-persistence/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSurface",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionRecord",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionLogSnapshot",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionSurfaceSnapshot",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionTitleObservation",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionTitleObservationResult",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventRecord",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionLineageNode",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionLineageTrace",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionQueryErrorCode",
       "source": "packages/session-query/session-query/src/config.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventReadRequest",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventWindow",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventTraceRequest",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventTrace",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventTraceObservation",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleProviderId",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleModelProvenance",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleSource",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleEventData",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleSnapshot",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleLlmRequestEventData",
       "source": "packages/session/session-title-llm/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleUserMessage",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleAutomaticMode",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleProviderRequest",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleProviderResult",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-title.md",
+      "doc": "docs/subsystems/session-title.md",
       "symbol": "SessionTitleProvider",
       "source": "packages/session/session-title/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-reference.md",
+      "doc": "docs/subsystems/session-reference.md",
       "symbol": "SessionReferenceInput",
       "source": "packages/context/session-reference/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-reference.md",
+      "doc": "docs/subsystems/session-reference.md",
       "symbol": "SessionReferenceCandidate",
       "source": "packages/context/session-reference/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-reference.md",
+      "doc": "docs/subsystems/session-reference.md",
       "symbol": "PreparedReferencedMessage",
       "source": "packages/context/session-reference/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-reference.md",
+      "doc": "docs/subsystems/session-reference.md",
       "symbol": "SessionReferenceErrorCode",
       "source": "packages/context/session-reference/src/config.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolOutputDefinition",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolDefinition",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ValueSchemaSpec",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ParameterPropertySpec",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ParameterSchemaSpec",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "InferValue",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "InferArgs",
       "source": "packages/core/tools/src/schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionToken",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionInput",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecution",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolDispatchExecution",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionMode",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "CodeDispatchLog",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolRunContext",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolGuard",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolRestriction",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolFailure",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionSuccess",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionFailure",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ToolExecutionResult",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "PreToolDecision",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "PostToolDecision",
       "source": "packages/core/tools/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "JsonSchemaScalar",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "JsonSchemaType",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "JsonSchemaNode",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/tools.md",
+      "doc": "docs/subsystems/tools.md",
       "symbol": "ObjectJsonSchema",
       "source": "packages/core/tools/src/json-schema.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionOption",
       "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionIntent",
       "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionItem",
       "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionRequest",
       "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionAnswerItem",
       "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "AskUserQuestionAnswer",
       "source": "packages/interaction/user-interaction/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "UserInteractionProvider",
       "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/user-interaction.md",
+      "doc": "docs/subsystems/user-interaction.md",
       "symbol": "UserInteractionError",
       "source": "packages/interaction/user-interaction/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/approval.md",
+      "doc": "docs/subsystems/approval.md",
       "symbol": "ApprovalRequestId",
       "source": "packages/interaction/user-approval/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/approval.md",
+      "doc": "docs/subsystems/approval.md",
       "symbol": "ApprovalOutcome",
       "source": "packages/interaction/user-approval/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/approval.md",
+      "doc": "docs/subsystems/approval.md",
       "symbol": "ApprovalPolicy",
       "source": "packages/interaction/user-approval/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/approval.md",
+      "doc": "docs/subsystems/approval.md",
       "symbol": "ApprovalRequest",
       "source": "packages/interaction/user-approval/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashExecRequest",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashExecSpec",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashRunResult",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashSandboxInfo",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashProcess",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/bash.md",
+      "doc": "docs/subsystems/bash.md",
       "symbol": "BashProcessRead",
       "source": "packages/bash/bash/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskKindMap",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskStart",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskHooks",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskOutcome",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskSnapshot",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/tasks.md",
+      "doc": "docs/subsystems/tasks.md",
       "symbol": "TaskRead",
       "source": "packages/tasks/tasks/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtyWaitReason",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtySessionStatus",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtyBackend",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtyBackendSession",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtySendOperation",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/pty.md",
+      "doc": "docs/subsystems/pty.md",
       "symbol": "PtySendResult",
       "source": "packages/pty/pty/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "SandboxMode",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "ConfinedSandboxMode",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "SandboxExecutionPolicy",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "SandboxEnforcement",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "SandboxPolicy",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "SandboxPolicyRequest",
       "source": "packages/sandbox/sandbox-policy/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "RunnerFailureRule",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/sandbox.md",
+      "doc": "docs/subsystems/sandbox.md",
       "symbol": "ConfinedArgv",
       "source": "packages/sandbox/sandbox/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeJsonValue",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeRunRequest",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeRunResult",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeBindingNamespace",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeBindingErrorClass",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeBindingFunction",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/code-runtime.md",
+      "doc": "docs/subsystems/code-runtime.md",
       "symbol": "CodeRunFailure",
       "source": "packages/code-runtime/code-runtime/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsTarget",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsTargetKey",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsVersion",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsInfo",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsPathInfo",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsDirEntry",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsWriteIntent",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsWriteOutcome",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsEditRequest",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsEditOutcome",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsErrorCode",
       "source": "packages/fs/fs/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsPolicyExec",
       "source": "packages/fs/fs-policy/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/filesystem.md",
+      "doc": "docs/subsystems/filesystem.md",
       "symbol": "FileReadOutcome",
       "source": "packages/fs/tool-fs/src/read-render.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillSource",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillResourceBase",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillInvocationPolicy",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillSummary",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillCatalogSnapshot",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillCandidate",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillDefinition",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillRegistration",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillLookupOptions",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillProviderObservation",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillProvider",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "SkillProviderControl",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/skills.md",
+      "doc": "docs/subsystems/skills.md",
       "symbol": "Config",
       "source": "packages/skill/skill/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/compaction.md",
+      "doc": "docs/subsystems/compaction.md",
       "symbol": "CompactionResult",
       "source": "packages/compact/compact/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/compaction.md",
+      "doc": "docs/subsystems/compaction.md",
       "symbol": "CompactionTrigger",
       "source": "packages/compact/compact/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/compaction.md",
+      "doc": "docs/subsystems/compaction.md",
       "symbol": "ManualCompactionErrorCode",
       "source": "packages/compact/compact/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/compaction.md",
+      "doc": "docs/subsystems/compaction.md",
       "symbol": "PrunedEntry",
       "source": "packages/compact/compact-tool-result-prune/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/compaction.md",
+      "doc": "docs/subsystems/compaction.md",
       "symbol": "PruneResult",
       "source": "packages/compact/compact-tool-result-prune/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentCapabilities",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentStartRequest",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "ResolvedSubagentStartRequest",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "CoordinatorMessageSource",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentReportMessageSource",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentReportDelivery",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentReportOptions",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentFollowupOptions",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentInterruptAuthority",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentDescendantListEntry",
       "source": "packages/subagent/subagent/src/list-children.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "ContinuableStart",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "ContinuableCreateRequest",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "ContinuableCreateSpec",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentResult",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentStopReasonMap",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentRun",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subagent.md",
+      "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentProvider",
       "source": "packages/subagent/subagent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebSearchRequest",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebSearchResult",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebSearchSource",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebFetchRequest",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebFetchResult",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/web.md",
+      "doc": "docs/subsystems/web.md",
       "symbol": "WebFetchBody",
       "source": "packages/web/web/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/spill.md",
+      "doc": "docs/subsystems/spill.md",
       "symbol": "SaveTextSpill",
       "source": "packages/spill/spill/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/spill.md",
+      "doc": "docs/subsystems/spill.md",
       "symbol": "SpillOwner",
       "source": "packages/spill/spill/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/spill.md",
+      "doc": "docs/subsystems/spill.md",
       "symbol": "SpillSource",
       "source": "packages/spill/spill/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/spill.md",
+      "doc": "docs/subsystems/spill.md",
       "symbol": "SpillRef",
       "source": "packages/spill/spill/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/spill.md",
+      "doc": "docs/subsystems/spill.md",
       "symbol": "SpillLocator",
       "source": "packages/spill/spill/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/workflow.md",
+      "doc": "docs/subsystems/workflow.md",
       "symbol": "WorkflowStartRequest",
       "source": "packages/workflow/workflow/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/workflow.md",
+      "doc": "docs/subsystems/workflow.md",
       "symbol": "WorkflowMeta",
       "source": "packages/workflow/workflow/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/workflow.md",
+      "doc": "docs/subsystems/workflow.md",
       "symbol": "WorkflowResult",
       "source": "packages/workflow/workflow/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/workflow.md",
+      "doc": "docs/subsystems/workflow.md",
       "symbol": "WorkflowRun",
       "source": "packages/workflow/workflow/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspOperation",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspPosition",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspRange",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspQueryRequest",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspProviderQuery",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspLocation",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspHover",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspQueryResult",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspProvider",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/lsp.md",
+      "doc": "docs/subsystems/lsp.md",
       "symbol": "LspService",
       "source": "packages/lsp/lsp/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionPersistenceRevision",
       "source": "packages/session/session-persistence/src/revision.ts"
     },
     {
-      "doc": "docs/core-data-structures/persistence.md",
+      "doc": "docs/subsystems/persistence.md",
       "symbol": "SessionPersistenceSnapshot",
       "source": "packages/session/session-persistence/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionResultFilter",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventResultFilter",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSearchDocument",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionSearchCursor",
       "source": "packages/session-query/session-query/src/cursor.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionSearchRequest",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSearchRequest",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionSearchPage",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSearchPage",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSearchHit",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/session-query.md",
+      "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionSearchHit",
       "source": "packages/session-query/session-query/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessSpawnSpec",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessHandle",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessOutputReader",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessOutputRead",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessOutcome",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "DshEnvironmentKey",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "DshEnvironment",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "CollectedOutput",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessStdinMode",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessCollect",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessOutputMode",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessStdio",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/subprocess.md",
+      "doc": "docs/subsystems/subprocess.md",
       "symbol": "SubprocessCollectedOutputs",
       "source": "packages/subprocess/subprocess/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsNamespace",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsRegisterOptions",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsApplies",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsScope",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsDescriptor",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsUpdateSource",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/credentials.md",
+      "doc": "docs/subsystems/credentials.md",
       "symbol": "CredentialRef",
       "source": "packages/credentials/credentials/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/credentials.md",
+      "doc": "docs/subsystems/credentials.md",
       "symbol": "ResolvedCredential",
       "source": "packages/credentials/credentials/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/credentials.md",
+      "doc": "docs/subsystems/credentials.md",
       "symbol": "CredentialInfo",
       "source": "packages/credentials/credentials/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsDescribeOptions",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/subsystems/core.md",
       "symbol": "LlmConfigurableProvider",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/settings.md",
+      "doc": "docs/subsystems/settings.md",
       "symbol": "SettingsPathOp",
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTLookupMap",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTContextMap",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTLookupDefinition",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTCodec",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "InvocationParameterDescriptor",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "InvocationDescriptor",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTService",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTRemoteNamespaceMap",
       "source": "packages/typert/type-meta/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "InvokeRemoteRequest",
       "source": "packages/api/gateway/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypertGatewayErrorCode",
       "source": "packages/api/gateway/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypertGateway",
       "source": "packages/api/gateway/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/typert.md",
+      "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTClientRemote",
       "source": "packages/typert/type-meta/src/types.ts"
     }
diff --git a/website/docs.ts b/website/docs.ts
index 8db7951dbb..07f470319b 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -279,13 +279,13 @@ const coreDataReference = pairedPages(([
   ['settings.md', '用户设置', 'User settings', 21],
   ['credentials.md', '用户凭据', 'User credentials', 22],
 ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
-  source: `docs/core-data-structures/${file}`,
-  route: `reference/core-data-structures/${file}`,
+  source: `docs/subsystems/${file}`,
+  route: `reference/subsystems/${file}`,
   label: { root: rootLabel, en: enLabel },
   sidebar: { root: 'zh-reference', en: 'en-reference' },
   section: { root: '数据结构', en: 'Data structures' },
   order,
-  ...(file === 'core.md' ? { sourceAliases: ['docs/core-data-structures'] } : {}),
+  ...(file === 'core.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
 })))
 
 const reference = mirroredPages([
@@ -339,8 +339,8 @@ const reference = mirroredPages([
     ['pty.md', 'PTY 会话', 'PTY sessions', 8],
     ['commands.md', '命令', 'Human commands', 17],
   ] as const).map(([file, rootLabel, enLabel, order]): MirroredPage => ({
-    source: `docs/core-data-structures/${file}`,
-    route: `reference/core-data-structures/${file}`,
+    source: `docs/subsystems/${file}`,
+    route: `reference/subsystems/${file}`,
     contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },

From cf5e53e051bf34cfad9a47789a18dd0fa3224410 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 27 Jul 2026 22:37:05 +0800
Subject: [PATCH 408/516] docs: fix stale package README claims found while
 writing subsystem pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- dsh-host-webserver: the service is HttpServerService under ctx.httpServer
  (README said WebServerService/ctx.webServer, matching no symbol in source),
  and the dev-mode bundle-watch paragraph described machinery that moved to
  dsh-client-modules/dsh-client-hmr in the webserver rewrite — removed; those
  packages' READMEs already document the current pipeline.
- dsh-workspace: ctx.workspace.touchSession(id) does not exist; the
  activity-pinning chain was replaced by Workspace.insertSessionBefore
  (2026-07-25 session-list note) — the bullet now documents the real method.
- packages/storage group table: the domain package directory is
  storage-domain/, not domain/.

All three pairs updated on both sides and re-recorded.
---
 packages/host/webserver/README.i18n.yaml      | 4 ++--
 packages/host/webserver/README.md             | 2 --
 packages/host/webserver/README.zh.md          | 2 --
 packages/workspace/workspace/README.i18n.yaml | 2 +-
 packages/workspace/workspace/README.md        | 1 +
 5 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/packages/host/webserver/README.i18n.yaml b/packages/host/webserver/README.i18n.yaml
index 56fd0e7694..bd80f27f3e 100644
--- a/packages/host/webserver/README.i18n.yaml
+++ b/packages/host/webserver/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/host/webserver/README.md
-README.md: b6dccf2f81c9e2f0b9f53264eafe724edb560f07
-README.zh.md: dbfe420013ed67c48e47048341f020864aeef16a
+README.md: 569c3f0c19db2c308beaef35baaf915fd39768cd
+README.zh.md: b311ebffa3fb067e684e9e443c2ac02dab917d61
diff --git a/packages/host/webserver/README.md b/packages/host/webserver/README.md
index b6dccf2f81..569c3f0c19 100644
--- a/packages/host/webserver/README.md
+++ b/packages/host/webserver/README.md
@@ -8,8 +8,6 @@ The package knows no harness concepts and serves no files: the `/api` HTTP bridg
 
 A listen failure (EADDRINUSE…) throws out of activation and rejects Loader composition with the bind diagnostic; the failed candidate fiber is disposed. An HTTP request whose handling throws (a fallback owner's `decodeURIComponent` on a malformed %-escape, a client dropping mid-body) is answered 400 — or the socket destroyed when headers are already out — and logged as a warning; it never exits the process. An upgrade-handler exception or upgraded-socket transport error is logged as a warning and destroys its socket. Disposal starts `close()` and `closeAllConnections()`, destroys every tracked upgraded socket, and returns only after the HTTP server and those sockets have closed.
 
-In development, the client-plugin registry synchronously captures each built bundle's stat baseline before it returns, then polls those baselines and re-hashes changed content. Each rescan stages its candidate table, graph, and watch map before publishing them, so a baseline failure preserves the prior graph. An immediate rebuild therefore cannot disappear into an asynchronously established watch baseline; a rename window marks the path dirty, retains the last successful baseline, and forces a re-hash when the bundle reappears even with identical metadata.
-
 ## Model Experience
 
 None, as the package is a Web carrier between the browser and the HTTP/upgrade routes other plugins register; nothing here reaches a model request.
diff --git a/packages/host/webserver/README.zh.md b/packages/host/webserver/README.zh.md
index dbfe420013..b311ebffa3 100644
--- a/packages/host/webserver/README.zh.md
+++ b/packages/host/webserver/README.zh.md
@@ -8,8 +8,6 @@ Web HTTP 与 upgrade route 注册插件（默认导出 `HttpServerService`，配
 
 监听失败（EADDRINUSE……）会从激活过程抛出，以 bind 诊断使 Loader 组合 reject；失败的候选 fiber 会被 dispose（资源释放）。处理 HTTP 请求时抛错（例如 fallback 持有者的 `decodeURIComponent` 收到格式错误的百分号转义，或客户端在请求体传输中途断开）时，服务器会响应 400；若响应头已经发出，则销毁 socket，并记录 warning，但绝不会退出进程。upgrade handler 抛错或升级 socket 出现传输错误时，会记录 warning 并销毁对应 socket。资源释放会启动 `close()` 与 `closeAllConnections()`，销毁所有受跟踪的升级 socket，并仅在 HTTP server 与这些 socket 均已关闭后返回。
 
-在开发环境中，客户端插件注册表会在返回前同步捕获每个已构建 bundle 的 stat 基线，随后轮询这些基线，并在内容变化后重新计算哈希。每次重新扫描都会先暂存候选表、图和监听 map，再统一发布，因此基线失败会保留先前的图。这样，即时重建不会消失在异步建立的监听基线中；重命名窗口会把路径标记为脏，保留最近一次成功基线，并在 bundle 重新出现时强制重新计算哈希，即使其元数据完全相同也不例外。
-
 ## 模型体验
 
 无。该包只是浏览器与其他插件所注册 HTTP／upgrade route 之间的 Web 载体，其中没有任何内容会进入模型请求。
diff --git a/packages/workspace/workspace/README.i18n.yaml b/packages/workspace/workspace/README.i18n.yaml
index aa3db1bef6..7ba60b4109 100644
--- a/packages/workspace/workspace/README.i18n.yaml
+++ b/packages/workspace/workspace/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/workspace/workspace/README.md
-README.md: bfa044de50fc71dca95637487df50dc551d40e1b
+README.md: 057765e38de9cc700210eb8edeb1ddc7ffc861ff
 README.zh.md: f3be9611eba45db3719ce76ad6625f4787fab9ac
diff --git a/packages/workspace/workspace/README.md b/packages/workspace/workspace/README.md
index bfa044de50..057765e38d 100644
--- a/packages/workspace/workspace/README.md
+++ b/packages/workspace/workspace/README.md
@@ -12,6 +12,7 @@ The entity/storage rationale lives in the [domain Agent Note](../../../.agents/n
 - `ctx.workspace.get(id)` / `list()` / `resolveByPath(path)` — cache-served lookups. `list()` is synchronous and follows durable registry order; `resolveByPath` is async because it applies the same `realpath` canon and rejects a missing path rather than creating it.
 - `ctx.workspace.delete(id)` — removes only the Workspace registration, its durable order entry, and its session account. Unknown ids return `false`; a removed record returns `true`. The directory, user files, live Sessions, and persisted session logs are never touched, so those Sessions become Ungrouped. A table-write failure restores the prior order and published entity.
 - `Workspace.attachSession(id)` — validates a live or persisted session header cwd against the workspace path and prepends a new id. Unknown sessions, absent/unresolvable/non-directory cwd values, and mismatches reject without writing. `detachSession` removes only the candidate index entry.
+- `Workspace.insertSessionBefore(id, before?)` — moves an accounted session within the manual order, DOM-insertBefore-like: before the anchor, or appended when the anchor is omitted. A session or anchor absent from the account rejects without writing; a move to the current position resolves without writing. Workspace order never changes.
 - `ctx.workspace.archiveSession(id)` / `archivedSessionIds` — the registry-global archive set, layered over workspace accounting: an archived session disappears from grouping surfaces but keeps its session log and its `sessionIds` slot, so a future unarchive restores its position. Archiving accepts any live or persisted session (accounted or Ungrouped), resolves without writing for an already archived id, and rejects an unknown id. State written before the field existed parses with an empty set.
 - `Workspace.sessionIds` — synchronous id-plus-canonical-cwd membership projection in durable candidate order. Missing headers, invalid cwd values, and mismatches are filtered; the next workspace mutation prunes them. A medium indexing one session under two workspaces, claiming one path from two records, or diverging from durable workspace order rejects at startup.
 - `Workspace.status()` — uncached directory check, `'ok' | 'missing-dir'`; a missing directory never mutates the record.

From e3af8d2ed247d5440c931973e3b33613568e5ed1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 27 Jul 2026 22:48:20 +0800
Subject: [PATCH 409/516] docs: add eight lean subsystem pages covering every
 remaining service

permission, plan, invariants, http-server, storage (hub + backend seam +
domain form + domain/changed), workspace, tui, and client-modules complete
the docs/subsystems tier: every ctx service and event scope now has one
owning page, the precondition for generating per-subsystem service/event
reference into these pages. 25 new type-equiv manifest entries; 16 types
move from TYPE_LINK_EXEMPTIONS to LINK_MAP now that they have catalog
homes (dead InvariantRegistration exemption removed; catalogs
regenerated); core.md's sub-page table gains the eight rows in both
languages; the owning subsystems-catalog Agent Note records the coverage
extension. Chinese counterparts and pair records follow in the next
commit.
---
 ...2026-06-20-core-data-structures-catalog.md |   1 +
 ...6-06-20-core-data-structures-catalog.zh.md |   1 +
 docs/cordis-catalog/events.md                 |   2 +
 docs/subsystems/client-modules.md             |  63 +++
 docs/subsystems/core.md                       |   8 +
 docs/subsystems/core.zh.md                    |   8 +
 docs/subsystems/http-server.md                |  49 ++
 docs/subsystems/invariants.md                 |  59 ++
 docs/subsystems/permission.md                 |  63 +++
 docs/subsystems/plan.md                       |  39 ++
 docs/subsystems/storage.md                    | 125 +++++
 docs/subsystems/workspace.md                  | 121 ++++
 .../tests/cordis-catalog-contract.spec.ts     |   4 +-
 scripts/gen-cordis-catalog.ts                 | 521 +++++++++++++++---
 scripts/type-equiv.manifest.json              | 123 +++++
 15 files changed, 1104 insertions(+), 83 deletions(-)
 create mode 100644 docs/subsystems/client-modules.md
 create mode 100644 docs/subsystems/http-server.md
 create mode 100644 docs/subsystems/invariants.md
 create mode 100644 docs/subsystems/permission.md
 create mode 100644 docs/subsystems/plan.md
 create mode 100644 docs/subsystems/storage.md
 create mode 100644 docs/subsystems/workspace.md

diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 57433fdcb3..025cbd7ab7 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -58,3 +58,4 @@ The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and de
 - The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
+- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: the eight `ctx` services without a page (permission presets, plan mode, runtime invariants, the HTTP carrier, storage, TUI extensions, workspaces, client modules) gained lean pages, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 3956839c82..de644e8567 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -58,3 +58,4 @@ Status: implemented
 - 主干与 seam 分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
 - `ts type-equiv` 围栏是继 ` ```ts `（编译）和 ` ```ts ignore-check `（草稿）之后的第三种文档块类别。后续的姊妹门禁又增加了第四种 ` ```ts cordis-catalog `（生成签名），复用了相同的跳过并排除处理。
 - 添加或重塑核心类型现在附带一项文档义务，作者必须履行（门禁无法检测缺失的*新*类型），由 `dsh-code-review` 检查清单兜底。
+- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：原先没有页面的八个 `ctx` 服务（权限预设、计划模式、运行时不变式、HTTP 载体、存储、终端扩展、工作区、客户端模块）都获得了精简页面，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index dd9cf5bfa5..6d060cf26b 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -389,6 +389,8 @@ A domain record or the global singleton changed, emitted once per write strictly
 'domain/changed'(change: DomainChanged): void
 ```
 
+Types: [DomainChanged](../subsystems/storage.md)
+
 Source: [`packages/storage/storage-domain/src/events.ts:46`](../../packages/storage/storage-domain/src/events.ts)
 
 ## `fs/*`
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
new file mode 100644
index 0000000000..bd5ecdc85e
--- /dev/null
+++ b/docs/subsystems/client-modules.md
@@ -0,0 +1,63 @@
+# Client Modules
+
+English | [中文](client-modules.zh.md)
+
+The web plugin table: the Node half of the client module system in [dsh-client-modules](../../packages/client/modules), provided as `ctx.clientModuleHost` (`ClientModuleHostService`). It scans the host Loader's entries for `dshClient` packages, composes the `window.__DSH_BOOT__` entry graph, serves each bundle at `/plugins/<id>/client.js`, and taps the index render to inject the boot manifest — the four faces of one service. It is an optional capability of the web GUI stack, not part of the agent-loop spine, and it is a consumer of [dsh-host-webserver](../../packages/host/webserver): the carrier described in [http-server.md](http-server.md) supplies the prefix route and index tap this service registers. The same package's browser half (`ctx.modules`, the lazy-CJS module table that fetches and materializes these bundles) is kernel machinery documented in the [package README](../../packages/client/modules/README.md), not here.
+
+Source: [`packages/client/modules/src/client/manifest.ts`](../../packages/client/modules/src/client/manifest.ts)
+
+## The wire
+
+The graph is the wire single source between the Node and browser halves: the host composes `WebBootEntry` rows from scanned packages, injects the graph as the first script in `<head>` (`window.__DSH_BOOT__`, with `<` escaped so plugin-controlled strings cannot break out of the script element), and the shell parses it before booting anything. A page without a valid manifest cannot boot — the browser-side parser throws loud on a missing or malformed graph.
+
+```ts type-equiv
+/**
+ * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * single source: the host node half (package root) produces this same shape.
+ * `immediately` marks stage-one prefetch; `inject` is informational graph
+ * metadata (the authoritative edges live in each package's dshClient
+ * declaration and reach fibers through entry creation).
+ */
+interface WebBootEntry {
+  /** Entry name == package name. */
+  id: string
+  /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+  url: string
+  /** Bundle content hash (cache-busting consistency anchor). */
+  rev: string
+  /** Package-name dependency edges, informational (preflight display / HMR diffing). */
+  inject?: string[]
+  /** Stage-one prefetch mark: fetch + execute (factory registration) during module-face boot. */
+  immediately?: boolean
+}
+```
+
+```ts type-equiv
+/** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
+interface WebBootGraph {
+  /** Consistency anchor over the whole graph (content + bundle hashes). */
+  rev: string
+  /** Composed entries; order carries no semantics (activation order is fiber inject waiting). */
+  entries: WebBootEntry[]
+}
+```
+
+Each row's `rev` is the bundle's content hash and rides the URL as a cache-busting query; the graph `rev` hashes the composed rows, so any row change changes it. `immediately` marks the stage-one prefetch tier (fetch and execute during module-face boot, registration only); a lazy row is fetched on first import.
+
+## The scan
+
+A package joins the table by declaring `dshClient` (`platform: 'web'`, optional `inject` edges, optional `immediately`) in its package.json and exporting its built bundle at `exports["./client"]`. Package resolution anchors at the config tree's `ctx.baseUrl` — the cordis.yml directory, whose package declares every composed plugin as a dependency — and construction throws when that anchor is unset.
+
+Scanning is incremental per package; there is no full-rescan code path. Every cordis `internal/plugin` emission (fiber construction or disposal) marks the fiber's entry name dirty, and a microtask flush reconciles each dirty name against the live loader entries. The activation pass seeds the same dirty set with all current entries and flushes synchronously, so first scan and steady state share one implementation — with opposite failure postures. At activation, a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud `AggregateError` listing every broken package: the fiber FAILS and the boot's fail-loud sweep reports it. In steady state, a broken package logs a warning and must not poison the others.
+
+Package metadata — including the negative "not a client package" verdict — is cached per name and never expires: plugin-set changes take effect on restart. A fiber restart reuses its row and rev untouched; bundle content changes reach the graph only through `rebuilt()`.
+
+## The bundle route and index tap
+
+`GET`/`HEAD /plugins/<id>/client.js` serves the registered bundle from disk with `no-cache` (the rev query, not HTTP caching, anchors consistency); other methods are 405. An unknown id — or a registered row whose bundle is unreadable because it has not been built yet — answers a loud 404 rather than letting the carrier's SPA fallback ship HTML as JavaScript. The index tap injects the current graph on every index render, so a reload always boots against the live composition.
+
+## The service
+
+`ClientModuleHostService` (`ctx.clientModuleHost`, defined in [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)) exposes reads and the rebuild face; signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxclientmodulehost--clientmodulehostservice). `graph()` returns the current composed graph (a stable object between changes) and `clientPath(id)` the bundle's absolute path. `rebuilt(id)` is the only entry point through which bundle content reaches the graph: it re-hashes the file, and only a real rev change recomposes the graph and notifies. `onRebuilt` fires per changed bundle with the new rev; `onGraphChanged` fires after any flush that recomposed the graph (row added or removed, or a rebuilt rev change) and is pull-model — listeners re-read `graph()`. Both notification paths contain listener exceptions so one throwing subscriber cannot skip later subscribers or kill whatever triggered the flush.
+
+In development, [dsh-client-hmr](../../packages/client/hmr/README.md) is the registry's watch driver: its node half stat-polls every graph row's bundle from a synchronously captured baseline, calls `rebuilt(id)` on change, resyncs its watch set through `onGraphChanged`, and broadcasts rev changes to the browser half over SSE. Production graphs omit the HMR row entirely; the module host itself never watches files.
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 8f413a7a06..bde64a39e4 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -46,6 +46,14 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider availability, `WebError` |
 | [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
 | [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
+| [permission.md](permission.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event |
+| [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
+| [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
+| [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the static dist fallback, index taps |
+| [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
+| [tui.md](tui.md) | the terminal-extension seam: `TuiOverlayRequest`/`Host`/`Session`, close reasons and outcomes, the modal queue |
+| [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
+| [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
 
 > Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](../cordis-catalog/services.md).
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index d0f02f0cfc..1f21785cad 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -46,6 +46,14 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
 | [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
 | [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
+| [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
+| [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
+| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空伴随插件契约 |
+| [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
+| [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
+| [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
+| [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
+| [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 
 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](../cordis-catalog/services.md)。
 
diff --git a/docs/subsystems/http-server.md b/docs/subsystems/http-server.md
new file mode 100644
index 0000000000..565df72f27
--- /dev/null
+++ b/docs/subsystems/http-server.md
@@ -0,0 +1,49 @@
+# HTTP Server
+
+English | [中文](http-server.zh.md)
+
+[dsh-host-webserver](../../packages/host/webserver) is the web-shape HTTP carrier for the GUI host: a single `node:http` plugin providing `ctx.httpServer`, a named-route registry plus index.html transform taps over a static dist fallback. It is not part of the agent-loop spine and not a capability seam — it knows no harness concepts, and every feature surface (the `/api` bridge, plugin bundles, the HMR event stream) is a route some other plugin registers ([layering note](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)). Web (browser) shape only: Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server.
+
+Source: [`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
+
+## Routes
+
+```ts type-equiv
+/** Route match kind: 'exact' matches the pathname verbatim; 'prefix' p matches p and p/<anything>. */
+type WebRouteKind = 'exact' | 'prefix'
+```
+
+```ts type-equiv
+/** One named route registration. */
+interface WebRoute {
+  kind: WebRouteKind
+  /** Absolute pathname, no trailing slash. */
+  path: string
+  /** Owns the full response lifecycle (may hold the response open, e.g. SSE). */
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+```
+
+Match order is fixed: exact table first, then longest matching prefix, then the static dist fallback. Registration order carries no request-facing semantics — named routes are composed to be disjoint, and the fallback answers anything not yet claimed during the boot window. The fallback keeps locked semantics: non-GET/HEAD is 405, traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), and unknown extensions ship as octet-stream ([`static.ts`](../../packages/host/webserver/src/static.ts)).
+
+## Config
+
+```ts type-equiv
+/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+interface Config {
+  /** Listen host; the two supported values are loopback and all-interfaces. */
+  host: '127.0.0.1' | '0.0.0.0'
+  /** Listen port; zero requests an OS-assigned port. */
+  port: number
+  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
+  distIndex: string
+}
+```
+
+`host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); there is no TLS, auth, or origin policy, so a non-loopback bind exposes the server to that network. `distIndex` is an assembly fact the composing app resolves and injects.
+
+## The service
+
+`HttpServerService` (`ctx.httpServer`) listens immediately on activation; a listen failure (EADDRINUSE…) throws out of init — a FAILED fiber the boot's fail-loud sweep reports. `register(route)` adds one named route and returns its disposer; a duplicate `(kind, path)` throws, because route patterns are a composition-level contract and a collision is a misconfiguration. `tapIndex(transform)` adds a pure html-to-html transform applied to every index response — `/` and each SPA fallback — in registration order; [dsh-client-modules](../../packages/client/modules) uses it to inject the boot manifest. `port` reads the listening port, the OS-assigned value when `config.port` is 0.
+
+A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is logged as a warning and answered 400 — or the socket destroyed when headers are already out — never a process exit. Disposal pairs `close()` with `closeAllConnections()` because a handler may hold its response open (SSE) and such connections never end on their own; without the force-close, teardown would hang. The package never prints: the URL line belongs to the shell. Per-package operational detail, including the dev-mode bundle watch pipeline, stays in the [README](../../packages/host/webserver/README.md).
diff --git a/docs/subsystems/invariants.md b/docs/subsystems/invariants.md
new file mode 100644
index 0000000000..143a7feabb
--- /dev/null
+++ b/docs/subsystems/invariants.md
@@ -0,0 +1,59 @@
+# Runtime Invariants
+
+English | [中文](invariants.zh.md)
+
+[dsh-invariants](../../packages/support/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in [AGENTS.md](../../AGENTS.md#conventions); the seam design is owned by the [invariant-service Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md).
+
+Source: [`packages/support/invariants/src/index.ts`](../../packages/support/invariants/src/index.ts)
+
+## Selection
+
+```ts type-equiv
+/** Runtime invariant selection configured on the service plugin. */
+interface Config {
+  /** Global switch; defaults to `true`. */
+  readonly enabled?: boolean
+  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
+  readonly package_allowlist?: string[]
+  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
+  readonly package_blocklist?: string[]
+}
+```
+
+A package is selected when the service is enabled, the allowlist is empty or at least one pattern matches its full npm name, and no blocklist pattern matches — a blocklist match overrides an allowlist match. Entries compile with `new RegExp(source)`: matching is unanchored unless the source supplies `^` and `$`, and `/pattern/flags` syntax is not parsed. Validation fails loud at service startup: a blank, whitespace-padded, duplicate, or invalid entry throws instead of being skipped. A valid pattern may match no currently loaded package, so later loading and HMR stay deterministic; filters are fixed for the service lifetime ([README](../../packages/support/invariants/README.md)).
+
+## The installer
+
+```ts type-equiv
+/**
+ * Throw a package-attributed invariant failure.
+ * @param message - violated package contract without the standard prefix.
+ * @returns never because reporting a violation throws.
+ */
+type InvariantFailure = (message: string) => never
+```
+
+```ts type-equiv
+/** Install one package's checks into the registration's child context. */
+interface InvariantInstaller {
+  /**
+   * Install the package contribution.
+   * @param ctx - child context owned by this invariant registration.
+   * @param fail - reporter bound to the registering package name.
+   * @returns nothing, or a promise settling after asynchronous checks finish.
+   */
+  (ctx: Context, fail: InvariantFailure): void | Promise<void>
+  /** Services the child installer fiber may access. */
+  readonly inject?: Inject
+}
+```
+
+An enabled installer runs in a dedicated child Cordis fiber; `installer.inject` declares the services that fiber may access, and synchronous or asynchronous installer completion is joined before the registration succeeds. `fail(message)` throws `InvariantError` — `extends Error` with stable `code: 'INVARIANT'`, the owning `packageName`, and a message prefixed `invariant violated by "<package>": …` — so a violation is attributable without the registry importing any product package.
+
+## The service
+
+`ctx.invariants.register(packageName, installer)` reserves one active registration for the full npm package name and returns its effect-scoped disposer. The reservation holds even when filters keep the installer inactive, so two plugins can never silently claim the same package name; a duplicate, blank, or whitespace-containing name throws. An installer failure disposes the child fiber and releases the reservation atomically. The service owns every registration fiber while the returned disposer also belongs to the companion fiber: unloading either side removes listeners, trace state, and the reservation, so a companion can reload and register the same name again without retained state.
+
+## The companion contract
+
+Every workspace package owns a `./invariant` companion ([package contract](../../packages/AGENTS.md)); publication and registration are exhaustive, but assertions are deliberately not synthetic. A companion installs a check only when its package owns an observable event or mutable-data relationship; otherwise it exports an empty installer whose leading comment starts `No runtime invariant:` and explains, package-specifically, why nothing is checkable. `pnpm run verify-package-invariants` mechanically rejects generated markers, unexplained empty installers, non-empty installers that omit or ignore the reporter, incorrect registration names, and incomplete export, publication, dependency, or bundle wiring ([mechanical-rule Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)). The catalog of executable companions and the standard composition live in the [package README](../../packages/support/invariants/README.md).
diff --git a/docs/subsystems/permission.md b/docs/subsystems/permission.md
new file mode 100644
index 0000000000..49dd51ff86
--- /dev/null
+++ b/docs/subsystems/permission.md
@@ -0,0 +1,63 @@
+# Permission Presets
+
+English | [中文](permission.zh.md)
+
+The permission-preset layer of [dsh-permission](../../packages/ui/permission) (`ctx.permission`, `PermissionService`) bundles the two independent enforcement knobs — [sandbox mode](sandbox.md) (`sandbox/mode`) and [approval policy](approval.md) (`approval/policy`) — into named presets a client offers as one Permissions selector. It is one optional capability, not part of the agent-loop spine, and it owns no enforcement: execution, prompt narration, and replay keep reading their knob folds, and a preset switch only records intent and writes through each knob's canonical setter. The [package README](../../packages/ui/permission/README.md) owns composition status and limitations; the [sandbox switching design](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns the rationale.
+
+Source: [`packages/ui/permission/src/index.ts`](../../packages/ui/permission/src/index.ts)
+
+## The preset table
+
+A preset is a table key mapping to one sandbox/approval bundle plus optional client presentation; the default table ships `workspace-write` (`workspace-write` + `ask`) and `danger-full-access` (`danger-full-access` + `never`).
+
+```ts type-equiv
+/** One preset's sandbox/approval bundle and optional client presentation. */
+interface PresetSpec {
+  /** The `sandbox/mode` value the preset writes through. */
+  sandbox: SandboxMode
+  /** The `approval/policy` value the preset writes through. */
+  approval: ApprovalPolicy
+  /** The display label a client shows for this preset; the raw table key when omitted. */
+  name?: string
+  /** One user-facing sentence on what the preset means; omitted when not configured. */
+  description?: string
+}
+```
+
+```ts type-equiv
+/** The {@link PermissionService} config: the deployment's preset table. */
+interface Config {
+  /**
+   * The preset table: name → knob bundle. Defaults to `workspace-write`
+   * (workspace-write + ask) and `danger-full-access` (danger-full-access +
+   * never). The name `custom` is reserved for the derived not-a-preset state.
+   */
+  presets?: Record<string, PresetSpec>
+}
+```
+
+The service requires a confining `ctx.bash` executor and `ctx.approval`, and misconfiguration fails at plugin load: a table entry named `custom` throws (the name is reserved for the derived not-a-preset state), and composing over a bash executor that does not confine (no `sandboxMode` capability fact) throws, because presets bundle a sandbox mode.
+
+## Current preset and the derived `custom`
+
+`current(events)` derives the effective preset from the knobs, not from its own event alone: it folds the session's effective sandbox mode (falling back to the executor's configured mode) and effective approval policy (falling back to the approval service config, then `ask`), prefers a still-matching recorded selection, then the first matching table entry in declaration order, and otherwise returns `CUSTOM_PRESET` (`'custom'`). `custom` is derived-only: clients may display it as the current value, but it is never a switch target or an event payload.
+
+`names` lists the switchable presets in table declaration order; `optionOf(name)` builds the option a client renders for a table key (label falls back to the key) or for `custom`, and throws for any other name.
+
+```ts type-equiv
+/** The select-option shape a presentation layer advertises for one preset (or for the derived `custom` state). */
+interface PresetOption {
+  /** Stable option value: the table key, or `custom`. */
+  value: string
+  /** The display label. */
+  name: string
+  /** One user-facing sentence on what the value means. */
+  description?: string
+}
+```
+
+## Switching and the `permission/preset` event
+
+`set(session, name)` resolves the preset (unknown names throw), appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter — `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/ui/user-approval) — only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing at all.
+
+`permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve WHICH preset the user chose when two presets share a bundle; `effectivePermissionPreset(events)` folds the last one, and replay needs no catch-up state. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxpermission--permissionservice).
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
new file mode 100644
index 0000000000..f67e7734ca
--- /dev/null
+++ b/docs/subsystems/plan.md
@@ -0,0 +1,39 @@
+# Plan Mode
+
+English | [中文](plan.zh.md)
+
+Plan mode is logged per-agent collaboration state owned by [dsh-plan-mode](../../packages/plan/plan-mode) (`ctx.planMode`, `PlanModeService`): while active, a deployment-owned guidance section shapes each model request. It is **soft guidance**, deliberately independent of the [sandbox mode](sandbox.md) and [approval policy](approval.md) enforcement axes — those knobs never read or write plan state, and deployments needing a hard boundary combine them separately. The package is one optional capability, not part of the agent-loop spine; its surfaces are the `plan:policy` prompt section, the always-registered `exit_plan_mode` tool, and the `/plan` command. The [design note](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md) owns the rationale; the [package README](../../packages/plan/plan-mode/README.md) owns the model-experience and limitation detail.
+
+Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/src/index.ts)
+
+## Logged state and recovery
+
+`plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace [session event](session.md): durable and replayable, never in the model transcript. `foldPlanMode(events, end?)` returns the last logged value in the prefix, or `false` when there is none — the state in force is always a pure fold of the session log, so resume, fork, and compaction recover it with no live mirror, and UIs observe committed flips through `session/event`. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md).
+
+## Pending intent and the turn-boundary flush
+
+Because every session event is turn-enclosed, a user selection is held as pending intent until a turn boundary. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
+
+The service flushes one pending selection before the affected request assembly at three boundaries: prompt submission, ordinary turn continuation, and request-recovery retry. The flush runs after the downstream listener chain, so a selection arriving while an async listener awaits still shapes the request that boundary precedes. A flush failure is contained — plan policy can never block a prompt or turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
+
+## Configuration
+
+```ts type-equiv
+/** Deployment-owned plan guidance. */
+interface PlanModeConfig {
+  /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
+  section: string
+}
+```
+
+A missing, blank, or non-string `section` and any unknown key fail at plugin load rather than silently shaping nothing. While plan mode is active, the exact `section` text renders as the `plan:policy` [system-prompt section](system-prompt.md) at order 50; inactive plan mode contributes no text.
+
+## The exit tool and the `/plan` command
+
+[`exit_plan_mode`](../tool-catalog.md#deepseek-aidsh-plan-mode) stays registered while plan mode is inactive, so crossing the boundary changes only the prompt section, never the request tool catalog; execution outside plan mode fails. In plan mode it requires a complete markdown plan starting with a `#` heading and presents it for review through the [user-interaction seam](user-interaction.md). Approval returns `{ approved: true }` and records a silent (non-narrated) pending exit that flushes after the step — plan guidance holds for the rest of the assistant's tool batch, and the tool result itself narrates the transition. Keep-planning is a failed call carrying the user's feedback, so the model revises and presents again; a missing interaction channel and a service reload during review also fail the call rather than silently leaving plan mode.
+
+When [`ctx.commands`](commands.md) is composed, the plugin registers `/plan [off|message]`: bare `/plan` selects plan mode, any other non-empty message selects it and then submits the text through `agent.steer()` so it becomes the next step's ordinary logged user message under plan guidance, and the exact argument `off` selects inactive — which also cancels a not-yet-flushed pending entry before plan mode ever reaches a request.
+
+## The service
+
+`ctx.planMode` owns the logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool; `get`/`set` signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxplanmode--planmodeservice).
diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md
new file mode 100644
index 0000000000..5d54d7337b
--- /dev/null
+++ b/docs/subsystems/storage.md
@@ -0,0 +1,125 @@
+# Storage
+
+English | [中文](storage.zh.md)
+
+The storage subsystem persists everything that is not a session event log (session logs have their own seam — [persistence.md](persistence.md)). It is one optional capability, not part of the agent-loop spine, split as a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): the hub and backend interface ([dsh-storage](../../packages/storage/storage), `ctx.storage`), the backend implementations ([dsh-storage-json](../../packages/storage/storage-json), registered as `json`, and [dsh-storage-sqlite](../../packages/storage/storage-sqlite), registered as `sqlite`), and the domain data form ([dsh-storage-domain](../../packages/storage/storage-domain), `ctx.storageDomain`, also reachable as `ctx.storage.domain`) — the backend seam's only consumer and the typed API everything else uses. The hub performs no IO itself: backends own media, data forms own semantics, and product packages never touch backends directly. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).
+
+Source: [`packages/storage/storage/src/backend.ts`](../../packages/storage/storage/src/backend.ts) · [`packages/storage/storage-domain/src/spec.ts`](../../packages/storage/storage-domain/src/spec.ts) · [`packages/storage/storage-domain/src/events.ts`](../../packages/storage/storage-domain/src/events.ts)
+
+## The hub: `ctx.storage`
+
+`Storage` ([signatures](../cordis-catalog/services.md#ctxstorage--storage)) is a meeting point, not a store. `ctx.storage.backend` is a name → backend table: multiple backends stay mounted side by side, and which backend serves which consumer is that consumer's configuration (the domain layer's route table), never a hub-global choice. `register(name, backend)` returns the disposer; duplicate names and unknown lookups throw `StorageError`. Disposal only unregisters the name — the owning plugin closes the backend after unregistering. Each backend plugin also publishes a lifecycle-only service key (`storageBackendServiceKey(name)`), which form providers inject so their activation cannot race backend registration.
+
+Data forms mount on the hub under a merge-extensible key map:
+
+```ts type-equiv
+/**
+ * Data forms mountable on the hub, keyed by form name. Form owners extend
+ * this map via declaration merging (the domain layer merges
+ * `domain: DomainFacility`) and mount the facility in their `apply`.
+ */
+interface StorageForms {}
+```
+
+`mount(form, facility)` is an effect whose disposer unmounts; a second mount of the same key throws `duplicate-mount`. `form(form)` resolves a mounted facility and throws `form-not-mounted` until the owning plugin loads — assemblies order plugins accordingly rather than silently deferring. The domain layer merges `domain: DomainFacility`, so `ctx.storage.domain` and `ctx.storageDomain` are the same object.
+
+## The backend seam
+
+```ts type-equiv
+/**
+ * One registered backend. A backend owns exactly one medium and shares its
+ * lifecycle across all facets; facets are optional members — a backend that
+ * cannot serve a shape simply omits it, and resolution fails loud instead.
+ */
+interface StorageBackend {
+  /** Key-value data shape; absent when this backend cannot serve it. */
+  readonly kv?: KvFacet
+
+  /**
+   * Drain in-flight writes across all open units and release the medium.
+   * Idempotent; concurrent and repeated calls resolve once teardown finishes.
+   * @returns resolution after the medium is released.
+   */
+  close(): Promise<void>
+}
+```
+
+A backend owns one medium (a file-tree root, a database file) and exposes optional data-shape facets; `kv` is the only facet today. `KvFacet.open(descriptor)` opens one named unit — `KvUnitDescriptor` carries the name, format version, table names, and whether a global singleton slot exists — and returns a `KvUnit` with `loadAll`, `putRecord`, `deleteRecord`, `setGlobal`, and `close`. Unit and table names must match `UNIT_NAME_RE` (safe as a file name and as a SQL identifier segment); record keys are arbitrary strings that never reach file paths. A unit does not serialize concurrent writes — ordering belongs to the caller — but each single call is atomic on the medium and durable once resolved. A medium stamped with a different version rejects `version-mismatch`; one that cannot be parsed as the unit rejects `malformed-medium` (no migration, pre-release stance). [`backend.ts`](../../packages/storage/storage/src/backend.ts) is the normative clause-by-clause contract, and the shared conformance suite in [`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) asserts every clause against each backend. The [json backend](../../packages/storage/storage-json/README.md) republishes one whole human-readable file per unit atomically; the [sqlite backend](../../packages/storage/storage-sqlite/README.md) stores document-per-row in one database, the route for high-churn domains.
+
+## Declaring a domain
+
+A domain is declared once by its owning package as a spec object — the single source of the domain's identity, layout, and record schemas (zod, so `z.infer` keeps consumer types un-duplicated):
+
+```ts type-equiv
+/** Static declaration of one domain: identity, version, and record layout. */
+interface DomainSpec {
+  /** Domain name; must match `UNIT_NAME_RE` (doubles as the backend unit name). */
+  readonly name: string
+  /** Domain format version; a medium stamped with a different version rejects at open. */
+  readonly version: number
+  /** Optional global singleton slot. */
+  readonly global?: DomainGlobalSpec<unknown>
+  /** Table declarations keyed by table name; each name must match `UNIT_NAME_RE`. */
+  readonly tables: Record<string, DomainTableSpec>
+}
+```
+
+`defineDomain(spec)` pins the spec's literal types and fails loud at the owner's module load, before any medium is touched: a domain or table name outside `UNIT_NAME_RE`, a version that is not a non-negative integer, or a global schema that accepts `null` all throw (`null` is the medium's "never written" sentinel, so a stored nullable global could not round-trip). `domainTable<K, V>(schema)` declares one table with a phantom compile-time key type (typically a [branded id](core.md#branded-ids)); `descriptorOf(spec)` projects the backend-facing unit descriptor.
+
+## The open domain
+
+```ts type-equiv
+/** One open domain, typed by its spec. */
+interface Domain<S extends DomainSpec> {
+  /** Domain name from the spec. */
+  readonly name: string
+  /** Global singleton handle; a spec without `global` has no usable handle (`never`). */
+  readonly global: DomainGlobalHandleOf<S>
+  /**
+   * Resolve one declared table handle. Handles are stable — repeated calls
+   * return the same instance.
+   * @param name - Declared table name.
+   * @returns the typed table handle.
+   */
+  table<N extends keyof S['tables'] & string>(name: N): KvTable<TableKeyOf<S, N>, TableValueOf<S, N>>
+
+  /**
+   * Close this domain: reject new writes immediately, drain already-queued
+   * writes (their events still emit), release the backend unit, then free
+   * the domain name for a later open. Idempotent — repeated calls share one
+   * teardown. The consumer owns this call (typically as its own `ctx.effect`
+   * disposer); the facility closes any domain left open when it unmounts.
+   * @returns resolution after the unit is released.
+   */
+  close(): Promise<void>
+}
+```
+
+Reads are synchronous from authoritative in-memory state: `KvTable` exposes `get`/`entries`/`keys`/`size` (snapshot iterators that stay stable while queued writes land), and the global handle's `get()` serves the spec's `initial` until the first `set` materializes the slot on the medium. Every write — `put`, `delete`, `update`, `global.set` — queues on one per-domain chain and reaches backend durability first, then mutates memory, then emits `domain/changed`; a rejected backend write leaves memory untouched, so reads never diverge from the medium. `update(key, fn)` is an atomic read-modify-write at its chain slot (a missing key rejects `missing-key`); `delete` of an absent key resolves `false` with no write and no event. Returned records are the stored objects themselves, not copies — replace via `put`/`update`, never mutate in place.
+
+## The domain facility: `ctx.storageDomain`
+
+`DomainFacility` ([signatures](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)) opens declared domains over routed backends. Routing is the domain plugin's configuration, never the hub's: `backend` names the required default route and `routes` overrides it per domain name. `open(spec)` runs a strict sequence, each step failing the whole call: it rejects a name already open or still closing (`already-open`), resolves the route (`backend-not-found`), requires the backend's `kv` facet (`facet-unsupported`), opens the unit (backend `version-mismatch`/`malformed-medium` pass through), and validates every stored record and global against the spec's zod schemas (`invalid-record` with the offending table and key). The caller owns the returned handle and releases it with `Domain.close()`; domains still open when the plugin unmounts are closed by the facility, and a closed domain's name frees for reopening only after teardown fully completes. `get(name)` is an untyped diagnostic lookup onto the package-private `DomainImpl` runtime behind every typed handle; `closeAll()` is the unmount path.
+
+## The change event: `domain/changed`
+
+Every durable write emits one event strictly after the backend acknowledged durability, in the domain's write-chain order ([event entry](../cordis-catalog/events.md#domainchanged--emit)):
+
+```ts type-equiv
+/** Shared location fields of one durable domain change. */
+interface DomainChangedBase {
+  /** Owning domain name. */
+  readonly domain: string
+  /** Table name; `''` for a global-singleton write. */
+  readonly table: string
+  /** Record key; `''` for a global-singleton write. */
+  readonly key: string
+}
+```
+
+```ts type-equiv
+/** One durable domain change; a closed union — switch on `operation`. */
+type DomainChanged = DomainChangedPut | DomainChangedDeleted
+```
+
+`put` (inserts, overwrites, and global writes) carries the new snapshot in `value` — never the old value; a diffing consumer keeps its own previous snapshot. `deleted` is a tombstone with no value. The event is a notification, not a transaction participant: the commit point has passed at emission, so a synchronously throwing listener is contained with a logged warning rather than rejecting the already-durable write, and emitted values equal the in-memory state at emission. The event is in-process only; cross-process change push is deferred work recorded in the [package README](../../packages/storage/storage-domain/README.md).
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
new file mode 100644
index 0000000000..2726115457
--- /dev/null
+++ b/docs/subsystems/workspace.md
@@ -0,0 +1,121 @@
+# Workspaces
+
+English | [中文](workspace.zh.md)
+
+A workspace is the persistent record of a directory the user works in: a stable id over a canonical path, a display title, and the ordered account of sessions that belong to it. The subsystem is one package ([dsh-workspace](../../packages/workspace/workspace), `ctx.workspace`) — an optional host-side capability, not part of the agent-loop spine, and invisible to models (no tools, no prompt text, no session events). It stores its records through the [storage domain form](storage.md) and validates session membership against [`SessionHeader.cwd`](persistence.md#sessionheader--metadata-beside-the-log), so `storageDomain` and `sessionPersistence` are mandatory startup dependencies: an unavailable persistence peer leaves the plugin pending rather than being mistaken for an empty history. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md); bootstrap and GUI ordering: [Workspace UI product-flow Agent Note](../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md).
+
+Source: [`packages/workspace/workspace/src/types.ts`](../../packages/workspace/workspace/src/types.ts)
+
+## Identity
+
+```ts type-equiv
+/**
+ * Identifies one workspace record. A generated uuid, never the path: path
+ * normalization rewrites paths, and a reference anchor must stay stable.
+ */
+type WorkspaceId = Branded<'WorkspaceId'>
+```
+
+`WorkspaceId` is a [branded id](core.md#branded-ids). Path identity is separate: `realpathNormalize` (`fs.realpath`; trailing slashes, `..`, and symlinks resolved) is the one uniqueness canon — workspace paths are stored canonicalized, uniqueness is string equality of canonical paths (a symlink to an owned directory collides), and attach-time session cwd checks go through the same canon.
+
+## The workspace entity
+
+Consumers see only the `Workspace` interface; the implementation stays package-private.
+
+```ts type-equiv
+/**
+ * One workspace: a stable id over an existing directory, a display title, and
+ * an ordered candidate account of sessions. Membership requires both an id in
+ * that account and a session header whose canonical cwd equals the workspace
+ * path. Consumers only see this interface; the implementation stays private.
+ */
+interface Workspace {
+  /** Stable record id (generated uuid). */
+  readonly id: WorkspaceId
+
+  /**
+   * Canonical directory path: the `fs.realpath` of the path given at create
+   * time (trailing slashes, `..`, and symlinks all resolved). Never rewritten
+   * afterwards, even when the directory disappears (see {@link status}).
+   */
+  readonly path: string
+
+  /** Display title. Defaults to `basename(path)` at create; duplicates are allowed. */
+  readonly title: string
+
+  /** ISO-8601 creation instant, stamped at create and never rewritten. */
+  readonly createdAt: string
+
+  /** ISO-8601 instant of the last durable mutation (create counts as one). */
+  readonly updatedAt: string
+
+  /**
+   * Header-validated sessions in manually owned order: a new session is
+   * prepended at attach, explicit reordering goes through
+   * `insertSessionBefore`, and activity never reorders. The durable candidate
+   * account is filtered synchronously: missing headers, invalid cwd values,
+   * and canonical cwd mismatches are never returned. A subsequent workspace
+   * mutation prunes those filtered candidates durably.
+   */
+  readonly sessionIds: readonly SessionId[]
+
+  /**
+   * Replace the display title durably.
+   * @param title - New title; any string, duplicates across workspaces allowed.
+   * @returns resolution after durability.
+   */
+  setTitle(title: string): Promise<void>
+
+  /**
+   * Prepend a session to this workspace's candidate account. An already
+   * accounted id resolves without writing. A new id's live or persisted
+   * header cwd must resolve to an existing directory equal to {@link path};
+   * unknown ids, missing or invalid cwd values, and mismatches reject without
+   * writing.
+   * @param sessionId - The session to record.
+   * @returns resolution after durability.
+   */
+  attachSession(sessionId: SessionId): Promise<void>
+
+  /**
+   * Move an accounted session within the manual order, DOM-insertBefore-like:
+   * with an anchor the session lands before it, without one it appends to the
+   * end. Only the moved id changes position. A session or anchor absent from
+   * the account rejects without writing; a move to the current position
+   * resolves without writing (decided on the domain write chain).
+   * @param sessionId - The accounted session to move.
+   * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
+   * @returns resolution after durability.
+   */
+  insertSessionBefore(sessionId: SessionId, beforeSessionId?: SessionId): Promise<void>
+
+  /**
+   * Remove a session from this workspace's account. Idempotent: an id not on
+   * the account resolves without writing (decided on the domain write chain,
+   * like attach). Never touches the session's own stored log.
+   * @param sessionId - The session to remove.
+   * @returns resolution after durability.
+   */
+  detachSession(sessionId: SessionId): Promise<void>
+
+  /**
+   * Live directory check, uncached: whether {@link path} currently exists and
+   * is a directory. A missing directory never mutates the record — the
+   * directory may only be temporarily moved.
+   * @returns `'ok'` when the directory exists, `'missing-dir'` otherwise.
+   */
+  status(): Promise<'ok' | 'missing-dir'>
+}
+```
+
+Ownership truth is the record's ordered `sessionIds`, never derived from session cwd — but membership requires both: an id on the account and a header whose canonical cwd equals the workspace path, so one session structurally belongs to at most one workspace. Failed writes reject (`insertSessionBefore` account errors as `WorkspaceMoveInvalidError`, storage failures as plain errors); every accepted mutation stamps `updatedAt` and durably prunes candidates that no longer pass the membership check.
+
+## The registry: `ctx.workspace`
+
+`WorkspaceRegistry` ([signatures](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)) owns registration and resolution. `create(path, title?)` canonicalizes the path, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? basename(path)` prepended to the durable registry order — a new record cannot duplicate an existing display title (`WorkspaceNameConflictError`). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup completes exactly the marked mutation, and an unmarked order/table mismatch fails loud as corruption.
+
+Sessions get their cwd at create time from whoever creates them, not from this registry — the API gateway resolves a new session's cwd from the chosen workspace's `path` (falling back to an explicit or default cwd), creates the session so the cwd lands in its immutable [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log), then calls `attachSession`, which re-validates that stored header cwd against the workspace path. On the first successful start, the registry bootstraps history from persisted headers alone (`id`, `cwd`, `createdAt` — never event bodies), grouping sessions with a valid canonical cwd into per-directory workspaces, newest first; the initialized marker is written last so an interrupted bootstrap resumes safely. The bootstrap is one-time: cwd-less legacy sessions stay Ungrouped, and sessions created afterwards join a workspace only through `attachSession`.
+
+## Consumers
+
+[dsh-host-apiproxy](../../packages/host/apiproxy) is the product consumer: it serves workspace CRUD to GUI clients over `ctx.workspace` and performs the create-session-then-attach flow above. [dsh-workspace-context](../../packages/context/workspace-context) is **not** a consumer despite the name: it discovers AGENTS.md-style instruction files under an agent's own cwd and never touches `ctx.workspace` — the shared word refers to the user's working directory, not to this registry's entities.
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index edf653c3f4..30ef60e8fe 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -152,11 +152,11 @@ describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => {
 
   it('accepts linked, foundation, generic-parameter, and explicitly exempt signature types', () => {
     const events = collectEvents(make(
-      '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param preset - deployment metadata outside the core catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, preset: PresetSpec, signal: AbortSignal): Promise<T>',
+      '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param assembly - assembly result documented outside the subsystems catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, assembly: PromptAssembly, signal: AbortSignal): Promise<T>',
     ))
     expect(events).toHaveLength(1)
     expect(renderEvents(events)).toContain('Types: [SessionEvent](../subsystems/core.md)')
-    expect(renderEvents(events)).not.toContain('[PresetSpec]')
+    expect(renderEvents(events)).not.toContain('[PromptAssembly]')
   })
 
   it('aggregates every unclassified signature type with its source and remediation', () => {
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index d9f3803547..b710bebe76 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -1,25 +1,32 @@
 /**
- * Generate committed Cordis artifacts from the Typert catalog projector and
- * the independent vendored-core projector.
+ * Generate the Cordis event and service catalogs from static declarations.
+ * The walk enforces event modes, JSDoc parameter/return completeness, and
+ * signature type-link coverage; inherited Cordis services come from the
+ * curated table below. `--check` verifies both committed artifacts.
  */
 
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
-import {
-  projectCordisCatalog,
-  renderEvents,
-  renderServices,
-} from '@deepseek-ai/dsh-typert-generator'
-import type { CordisCatalogPolicy } from '@deepseek-ai/dsh-typert-generator'
+import { globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve, sep } from 'node:path'
+import ts from 'typescript'
 import { renderCordisCoreApiPages } from './cordis-core-api.ts'
+import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
+import { cordisModuleBody, eventMembers, serviceClasses } from './cordis-walk.ts'
 
 const root = resolve(import.meta.dirname, '..')
 const OUT_EVENTS = 'docs/cordis-catalog/events.md'
 const OUT_SERVICES = 'docs/cordis-catalog/services.md'
-const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts'
 
-/** One primary subsystems page per project type used by a generated signature. */
-export const LINK_MAP: Readonly<Record<string, string>> = {
+/** The fenced-block info string for generated signature blocks (skipped by
+ * doc-typecheck, since a bare signature fragment is not standalone-compilable). */
+const FENCE = 'ts cordis-catalog'
+
+/**
+ * One primary subsystems page per project type used by a generated
+ * signature. This stays curated because union names intentionally do not
+ * reuse the type-equivalence manifest's map-symbol entries and some symbols
+ * appear on more than one page.
+ */
+export const LINK_MAP: Record<string, string> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
   AgentOptions: 'core.md',
@@ -28,6 +35,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ContinuationDecision: 'core.md',
   ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
+  InboxPlacement: 'core.md',
   MessageId: 'core.md',
   HookContext: 'core.md',
   SettleReason: 'core.md',
@@ -49,7 +57,9 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   UserMessage: 'session.md',
   PreStepDecision: 'core.md',
   PreStepContext: 'core.md',
+  PromptDecision: 'core.md',
   RequestErrorAction: 'core.md',
+  RequestError: 'core.md',
   RequestFailureContext: 'core.md',
   PreparedReferencedMessage: 'session-reference.md',
   SessionReferenceCandidate: 'session-reference.md',
@@ -106,7 +116,6 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   PreparedLlmCall: 'llm-streaming.md',
   LlmService: 'llm-streaming.md',
   StreamChunk: 'llm-streaming.md',
-  SkillProviderControl: 'skills.md',
   CreateSessionOptions: 'persistence.md',
   PrepareSessionOptions: 'persistence.md',
   SessionHeader: 'persistence.md',
@@ -159,11 +168,9 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   SessionTitleObservationResult: 'session-query.md',
   SessionTitleProvider: 'session-title.md',
   SessionTitleSnapshot: 'session-title.md',
-  SkillCatalogSnapshot: 'skills.md',
   SkillDefinition: 'skills.md',
   SkillLookupOptions: 'skills.md',
   SkillProvider: 'skills.md',
-  SkillProviderObservation: 'skills.md',
   SkillRegistration: 'skills.md',
   SkillSummary: 'skills.md',
   SaveTextSpill: 'spill.md',
@@ -232,15 +239,27 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   WorkflowRun: 'workflow.md',
   WorkflowRunInfo: 'workflow.md',
   WorkflowStartRequest: 'workflow.md',
+  PresetOption: 'permission.md',
+  PresetSpec: 'permission.md',
+  InvariantInstaller: 'invariants.md',
+  WebRoute: 'http-server.md',
+  StorageBackend: 'storage.md',
+  StorageForms: 'storage.md',
+  Domain: 'storage.md',
+  DomainSpec: 'storage.md',
+  DomainChanged: 'storage.md',
+  DomainFacility: 'storage.md',
+  Workspace: 'workspace.md',
+  WorkspaceId: 'workspace.md',
+  WebBootGraph: 'client-modules.md',
 }
 
-/** TypeScript lib and pinned framework types with no repository-owned data page. */
-export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
+/** TypeScript lib and pinned framework types that have no repository-owned data page. */
+const FOUNDATION_TYPE_NAMES = new Set([
   'AbortSignal',
   'AsyncIterable',
   'Context',
   'Error',
-  'Map',
   'Partial',
   'Pick',
   'Promise',
@@ -248,8 +267,8 @@ export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
   'Readonly',
 ])
 
-/** Project types deliberately documented outside the core-data catalog. */
-export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
+/** Project types deliberately documented outside the subsystems catalog. */
+const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
   z: 'schemastery schema constructor is owned by vendor/schemastery (vendored upstream)',
   BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
@@ -261,15 +280,8 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
   ManualCompactAgentContext: 'manual compaction service input is owned by packages/compact/compact/src/index.ts',
-  DirectoryPickerCapability: 'picker interaction contract is owned by packages/host/directory-picker/README.md',
   CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
-  Domain: 'domain interface is owned by packages/storage/storage-domain/README.md',
-  DomainChanged: 'event-local snapshot is owned by packages/storage/storage-domain/src/events.ts',
-  DomainFacility: 'domain form facility is owned by packages/storage/storage-domain/README.md',
   DomainImpl: 'domain implementation contract is owned by packages/storage/storage-domain/README.md',
-  DomainSpec: 'domain declaration contract is owned by packages/storage/storage-domain/README.md',
-  StorageBackend: 'backend contract is owned by packages/storage/storage/src/backend.ts',
-  StorageForms: 'merge-extensible form map is owned by packages/storage/storage/src/index.ts',
   ProjectionDefinition: 'projection unit contract is owned by packages/session/session-projection/README.md',
   SessionProjectionMap: 'merge-extensible projection key map is owned by packages/session/session-projection/src/types.ts',
   ProjectionChangeListener: 'change-feed listener contract is owned by packages/session/session-projection/src/index.ts',
@@ -285,18 +297,13 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   TypeRTDisposer: 'TypeRT lifecycle contract is owned by packages/typert/type-meta/README.md',
   'z.core.JSONSchema.BaseSchema': 'zod projection output is owned by the zod v4 API',
   'z.core.ToJSONSchemaParams': 'zod projection parameters are owned by the zod v4 API',
-  InvariantInstaller: 'service-local contribution contract is owned by packages/support/invariants/README.md',
   LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
-  WebBootGraph: 'web boot graph wire shape is owned by packages/client/modules/src/client/index.ts',
-  WebRoute: 'route registration contract is owned by packages/host/webserver/src/index.ts',
-  WebUpgradeRoute:
-    'upgrade route registration contract is owned by packages/host/webserver/src/index.ts',
   ThemeTokens: 'service-local token dictionary is owned by packages/client/ui-theme/src/index.ts',
   Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
+  WebUpgradeRoute:
+    'upgrade route registration contract is owned by packages/host/webserver/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
   InvokeRemoteRequest: 'gateway invocation contract is owned by packages/api/gateway/README.md',
-  PresetOption: 'deployment menu metadata is owned by packages/interaction/permission/README.md',
-  PresetSpec: 'deployment preset composition is owned by packages/interaction/permission/README.md',
   KnobState: 'projection unit state shape is owned by packages/interaction/permission/README.md',
   PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
@@ -309,56 +316,403 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
-  Workspace: 'workspace entity contract is owned by packages/workspace/workspace/README.md',
-  WorkspaceId: 'branded id is owned by packages/workspace/workspace/README.md',
 }
 
-/** Repository data policy consumed by the Cordis catalog projector. */
-export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
-  linkedTypePages: LINK_MAP,
-  foundationTypeNames: FOUNDATION_TYPE_NAMES,
-  typeLinkExemptions: TYPE_LINK_EXEMPTIONS,
-  inheritedEvents: [
-    { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
-    { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
-    { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
-    { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
-    { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
-    { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
-    { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
-    { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
-    { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
-    { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:22' },
-    { name: 'hmr/config-update-failed', summary: 'A watched config-file refresh failed.', source: 'vendor/hmr/src/index.ts:29' },
-    { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
-    { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
-    { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
-    { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
-    { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
-  ],
-  inheritedServices: [
-    { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
-    { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
-    { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
-    { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
-    { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
-    { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
-    { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
-    { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
-    { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
-    { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
-  ],
+/** Collect named references from parameter, generic-constraint/default, and return types. */
+function signatureTypeNames(member: ts.MethodSignature | ts.MethodDeclaration, sf: ts.SourceFile): string[] {
+  const declared = new Set(member.typeParameters?.map(parameter => parameter.name.text) ?? [])
+  const referenced = new Set<string>()
+  const visit = (node: ts.Node): void => {
+    if (ts.isTypeReferenceNode(node)) referenced.add(node.typeName.getText(sf))
+    if (ts.isTypeQueryNode(node)) referenced.add(node.exprName.getText(sf))
+    ts.forEachChild(node, visit)
+  }
+  for (const parameter of member.typeParameters ?? []) {
+    if (parameter.constraint) visit(parameter.constraint)
+    if (parameter.default) visit(parameter.default)
+  }
+  for (const parameter of member.parameters) {
+    if (parameter.type) visit(parameter.type)
+  }
+  if (member.type) visit(member.type)
+  return [...referenced].filter(name => !declared.has(name)).sort()
 }
 
-/** CLI entry: default writes every artifact; `--check` reports stale files.
- * @returns nothing; writes files or reports freshness through the process.
+/** Append fail-closed signature type-link violations with actionable ownership choices. */
+function checkTypeLinks(
+  where: string,
+  member: ts.MethodSignature | ts.MethodDeclaration,
+  sf: ts.SourceFile,
+  violations: string[],
+): void {
+  for (const name of signatureTypeNames(member, sf)) {
+    if (Object.hasOwn(LINK_MAP, name)
+      || FOUNDATION_TYPE_NAMES.has(name)
+      || Object.hasOwn(TYPE_LINK_EXEMPTIONS, name)) continue
+    violations.push(
+      `${where} references unclassified type '${name}'. Add it to LINK_MAP with its subsystems page, `
+      + 'to FOUNDATION_TYPE_NAMES if TypeScript or Cordis owns it, or to TYPE_LINK_EXEMPTIONS with '
+      + 'the non-catalog documentation owner.',
+    )
+  }
+}
+
+/** Throw one aggregated diagnostic for every unclassified signature type. */
+function reportTypeLinkViolations(gate: string, violations: string[]): void {
+  if (violations.length === 0) return
+  throw new Error(
+    `${gate}: ${violations.length} signature type-link coverage violation(s):\n`
+    + violations.map(violation => `  ${violation}`).join('\n'),
+  )
+}
+
+/** One harness event, extracted from an `interface Events` block. */
+interface EventEntry {
+  /** Scoped name, e.g. `agent/request`. */
+  name: string
+  /** The scope prefix, e.g. `agent` (everything before the first `/`). */
+  scope: string
+  /** Full signature text (the method-signature member, JSDoc stripped). */
+  signature: string
+  /** Original declaration JSDoc, dedented from its containing interface. */
+  jsDoc: string
+  /** Dispatch mode from the `@mode` tag. */
+  mode: Mode
+  /** Description prose (JSDoc minus the `@mode` tag), one line per paragraph. */
+  doc: string
+  /** Source pointer `packages/…/file.ts:line` of the declaration. */
+  source: string
+}
+
+/** One public service method and the source contract attached to it. */
+interface ServiceMethodEntry {
+  /** Public method signature (body stripped). */
+  signature: string
+  /** Original method JSDoc, dedented from its containing class. */
+  jsDoc: string
+}
+
+/** One harness service, extracted from an `interface Context` block. */
+interface ServiceEntry {
+  /** The `ctx.<key>` name, e.g. `llm`. */
+  key: string
+  /** The service class/interface name, e.g. `LlmService`. */
+  type: string
+  /** Whether the service class is abstract (a seam interface). */
+  abstract: boolean
+  /** Class-level JSDoc prose, one line per paragraph. */
+  doc: string
+  /** Public methods (bodies stripped), in source order. */
+  methods: ServiceMethodEntry[]
+  /** Source pointer of the class declaration. */
+  source: string
+}
+
+/** A terse inherited-tier entry (pinned vendor surface). */
+interface InheritedEntry {
+  name: string
+  summary: string
+  /** Source pointer `vendor/…:line`. */
+  source: string
+}
+
+// cordisModuleBody / eventMembers / serviceClasses live in cordis-walk.ts.
+
+/** The signature text of a method-signature member (everything but a body). */
+function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.SourceFile): string {
+  const full = member.getText(sf)
+  const body = (member as { body?: ts.Node }).body
+  const sig = body ? full.slice(0, full.length - body.getText(sf).length) : full
+  return sig.replace(/\s*;?\s*$/, '').replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Copy a node's original JSDoc while removing only the indentation imposed by
+ * its containing interface or class.
  */
-export function main(): void {
-  const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
+function jsDocText(text: string, sf: ts.SourceFile, node: ts.Node): string {
+  const raw = rawJsDoc(text, node)
+  if (!raw) return ''
+  const start = text.lastIndexOf(raw, node.getStart(sf))
+  const { line } = sf.getLineAndCharacterOfPosition(start)
+  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
+  const indent = text.slice(lineStart, start)
+  return raw.split('\n')
+    .map((lineText, index) => index > 0 && lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText)
+    .join('\n')
+}
+
+/** Walk every harness `interface Events` block and extract its events, hard-
+ * erroring (aggregated) on any JSDoc-completeness violation: a missing/
+ * contradicted `@mode`, missing description prose, or an undocumented payload
+ * parameter. `scanRoot` defaults to the repo root; tests pass a fixture dir. */
+export function collectEvents(scanRoot: string = root): EventEntry[] {
+  const entries: EventEntry[] = []
+  const violations: string[] = []
+  const typeLinkViolations: string[] = []
+  for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
+    const abs = resolve(scanRoot, rel)
+    const text = readFileSync(abs, 'utf8')
+    if (!text.includes('interface Events')) continue
+    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
+    const body = cordisModuleBody(sf)
+    if (!body) continue
+    for (const { name, member } of eventMembers(body, sf)) {
+      const signature = memberSignature(member, sf)
+      const raw = rawJsDoc(text, member)
+      const { doc, mode } = parseJsDoc(raw)
+      const src = pointer(rel, sf, member)
+      const where = `event '${name}' (${src})`
+      checkTypeLinks(where, member, sf, typeLinkViolations)
+      if (!mode) {
+        violations.push(`${where} is missing an @mode tag. Add '@mode emit|waterfall|parallel|serial|bail' to its JSDoc (see AGENTS.md).`)
+      }
+      // Conclusive structural check: a trailing `next: () => …` parameter is a
+      // waterfall. (emit vs parallel vs serial is not structurally
+      // distinguishable, so it is trusted from the tag.)
+      const last = member.parameters.at(-1)
+      const hasNext = !!last && last.name.getText(sf) === 'next'
+      if (mode && hasNext && mode !== 'waterfall') {
+        violations.push(`${where} has a trailing 'next' parameter (structurally a waterfall) but is tagged '@mode ${mode}'. Fix the tag or the signature.`)
+      }
+      if (mode && !hasNext && mode === 'waterfall') {
+        violations.push(`${where} is tagged '@mode waterfall' but has no trailing 'next' parameter. A waterfall delegates via next().`)
+      }
+      if (!doc) violations.push(`${where} has no description prose. Say what happened / what a listener may do, above the block tags.`)
+      // Payload parameters need a non-empty @param. The `this` receiver is not
+      // payload, and a waterfall's trailing `next` is covered by its mode.
+      const { params } = parseTags(raw)
+      checkParams(where, 'event', member.parameters, params, sf,
+        p => (ts.isIdentifier(p.name) && p.name.text === 'this') || (hasNext && p === last), violations)
+      if (mode) entries.push({ name, scope: name.split('/')[0] ?? name, signature, jsDoc: jsDocText(text, sf, member), mode, doc, source: src })
+    }
+  }
+  reportViolations('gen-cordis-catalog', violations)
+  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
+  return entries
+}
+
+/** Walk every harness `interface Context` block + its service class, hard-
+ * erroring (aggregated) on any JSDoc-completeness violation: a class or public
+ * method without JSDoc prose, an undocumented parameter, a stale `@param`, a
+ * missing `@returns` on a non-void method, or an inferred (unannotated) return
+ * type the pure-AST walk cannot classify.
+ * `scanRoot` defaults to the repo root; tests pass a fixture dir. */
+export function collectServices(scanRoot: string = root): ServiceEntry[] {
+  const entries: ServiceEntry[] = []
+  const violations: string[] = []
+  const typeLinkViolations: string[] = []
+  for (const rel of globSync('packages/*/*/src/index.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
+    const abs = resolve(scanRoot, rel)
+    const text = readFileSync(abs, 'utf8')
+    if (!text.includes('interface Context')) continue
+    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
+    const body = cordisModuleBody(sf)
+    if (!body) continue
+    // Resolve each ctx key to its service class (shared walk) and emit an entry.
+    for (const { key, type, cls, abstract, doc: clsDoc } of serviceClasses(body, sf, rel, violations)) {
+      const methods: ServiceMethodEntry[] = []
+      for (const member of cls.members) {
+        if (!ts.isMethodDeclaration(member)) continue
+        // Only instance methods callable through `ctx.<key>` are surface;
+        // private, protected, and static methods are not.
+        const nonPublic = member.modifiers?.some(m =>
+          m.kind === ts.SyntaxKind.PrivateKeyword
+          || m.kind === ts.SyntaxKind.ProtectedKeyword
+          || m.kind === ts.SyntaxKind.StaticKeyword)
+          || ts.isPrivateIdentifier(member.name)
+        if (nonPublic) continue
+        const memberName = member.name.getText(sf)
+        if (memberName.startsWith('[')) continue // computed/symbol members
+        const where = `service method ctx.${key}.${memberName} (${pointer(rel, sf, member)})`
+        checkTypeLinks(where, member, sf, typeLinkViolations)
+        const raw = rawJsDoc(text, member)
+        methods.push({ signature: memberSignature(member, sf), jsDoc: jsDocText(text, sf, member) })
+        if (!raw) { violations.push(`${where} has no JSDoc.`); continue }
+        if (!parseJsDoc(raw).doc) violations.push(`${where} has no description prose above its block tags.`)
+        const { params, returns } = parseTags(raw)
+        // Every parameter needs a non-empty @param (`this` receiver exempt),
+        // and a non-void ANNOTATED result needs a non-empty @returns — the
+        // shared checkers carry the exact contract.
+        checkParams(where, 'service', member.parameters, params, sf,
+          p => ts.isIdentifier(p.name) && p.name.text === 'this', violations)
+        checkReturns(where, member.type, returns, sf, violations)
+      }
+      entries.push({
+        key,
+        type,
+        abstract,
+        doc: clsDoc,
+        methods,
+        source: pointer(rel, sf, cls),
+      })
+    }
+  }
+  reportViolations('gen-cordis-catalog', violations)
+  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
+  return entries.sort((a, b) => a.key.localeCompare(b.key))
+}
+
+/**
+ * The inherited tier — cordis core + loader/hmr/timer. Curated, terse, and
+ * hand-summarized because (a) it is pinned vendor source that changes only on a
+ * deliberate vendor sync, (b) the cordis-core `Context` mixes true ctx members
+ * with non-service fields (`root`, `baseUrl`, `logger`) that a blind walk would
+ * wrongly surface as services, and (c) the internal/* events carry no JSDoc to
+ * render. Source pointers are verified against vendor by `verify-md-links`'
+ * sibling check is N/A; keep them current on a vendor bump.
+ */
+const INHERITED_EVENTS: InheritedEntry[] = [
+  { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
+  { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
+  { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
+  { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
+  { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
+  { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
+  { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
+  { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
+  { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
+  { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
+  { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
+  { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
+  { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
+  { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
+  { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
+]
+
+export const INHERITED_SERVICES: InheritedEntry[] = [
+  { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
+  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
+  { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
+  { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
+  { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
+  { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
+  { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
+  { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
+  { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
+  { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
+]
+
+/** Render the cross-link "Types:" line for a signature, or '' if none apply. */
+function typeLinks(signature: string): string {
+  const seen = new Set<string>()
+  for (const name of Object.keys(LINK_MAP)) {
+    if (new RegExp(`\\b${name}\\b`).test(signature)) seen.add(name)
+  }
+  if (seen.size === 0) return ''
+  const links = [...seen].sort().map(n => `[${n}](../subsystems/${LINK_MAP[n]})`)
+  return `Types: ${links.join(' · ')}`
+}
+
+/** Render one harness event entry. */
+function renderEvent(e: EventEntry): string[] {
+  const out = [`### \`${e.name}\` — ${e.mode}`, '']
+  if (e.doc) out.push(e.doc, '')
+  out.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
+  const links = typeLinks(e.signature)
+  if (links) out.push(links, '')
+  out.push(`Source: [\`${e.source}\`](../../${e.source.split(':')[0]})`, '')
+  return out
+}
+
+/** Render one harness service entry. */
+function renderService(s: ServiceEntry): string[] {
+  const kind = s.abstract ? ' (abstract seam)' : ''
+  const out = [`## \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
+  if (s.doc) out.push(s.doc, '')
+  if (s.methods.length) {
+    const declarations = s.methods.flatMap((method, index) => [
+      ...(index > 0 ? [''] : []),
+      method.jsDoc,
+      method.signature,
+    ])
+    out.push('```' + FENCE, ...declarations, '```', '')
+    const links = typeLinks(s.methods.map(method => method.signature).join('\n'))
+    if (links) out.push(links, '')
+  }
+  out.push(`Source: [\`${s.source}\`](../../${s.source.split(':')[0]})`, '')
+  return out
+}
+
+/** The shared generated-file banner comment. */
+const BANNER = [
+  '<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.',
+  '     Run `pnpm run gen-cordis-catalog` to regenerate. -->',
+  '',
+]
+
+/** The shared GENERATED + freshness-gate + fence notice paragraph. */
+const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
+
+/** Render the events catalog (pure, deterministic given sorted inputs). */
+export function renderEvents(events: EventEntry[]): string {
+  const lines: string[] = [
+    ...BANNER,
+    '# Cordis Events Catalog',
+    '',
+    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.',
+    '',
+    GATE_NOTICE,
+    '',
+    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).',
+    '',
+    'Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`), **bail** (synchronous in-order dispatch until one listener returns a bail value; the scoped input-mutation events use it for an applied/not-applied answer).',
+    '',
+  ]
+  const scopes = [...new Set(events.map(e => e.scope))].sort()
+  for (const scope of scopes) {
+    lines.push(`## \`${scope}/*\``, '')
+    for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
+      lines.push(...renderEvent(e))
+    }
+  }
+  lines.push(
+    '## Inherited events (cordis core + loader/hmr/timer)',
+    '',
+    'The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier\'s prominence.',
+    '',
+  )
+  for (const e of INHERITED_EVENTS) {
+    lines.push(`- \`${e.name}\` — ${e.summary} ([\`${e.source}\`](../../${e.source.split(':')[0]}))`)
+  }
+  lines.push('')
+  return lines.join('\n')
+}
+
+/** Render the services catalog (pure, deterministic given sorted inputs). */
+export function renderServices(services: ServiceEntry[]): string {
+  const lines: string[] = [
+    ...BANNER,
+    '# Cordis Services Catalog',
+    '',
+    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
+    '',
+    GATE_NOTICE,
+    '',
+    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely. Detailed Context, Fiber, Registry, and Service APIs are generated in the [Cordis core API](core/context.md).',
+    '',
+  ]
+  for (const s of services) lines.push(...renderService(s))
+  lines.push(
+    '## Inherited `ctx` members (cordis core + loader/hmr/timer)',
+    '',
+    'The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier\'s prominence.',
+    '',
+  )
+  for (const s of INHERITED_SERVICES) {
+    lines.push(`- \`${s.name}\` — ${s.summary} ([\`${s.source}\`](../../${s.source.split(':')[0]}))`)
+  }
+  lines.push('')
+  return lines.join('\n')
+}
+
+/** CLI entry: `--write` (default) writes both catalogs, `--check` fails if
+ * either is stale. Guarded behind an entry-point check so importing this module
+ * for tests neither regenerates the committed files nor calls process.exit. */
+function main(): void {
   const outputs: [string, string][] = [
-    [OUT_EVENTS, renderEvents([...model.events], CORDIS_CATALOG_POLICY)],
-    [OUT_SERVICES, renderServices([...model.services], CORDIS_CATALOG_POLICY)],
-    [OUT_RUNTIME_API, projector.renderRuntimeApi(model)],
+    [OUT_EVENTS, renderEvents(collectEvents())],
+    [OUT_SERVICES, renderServices(collectServices())],
     ...renderCordisCoreApiPages(),
   ]
   if (process.argv.includes('--check')) {
@@ -368,7 +722,9 @@ export function main(): void {
       try {
         committed = readFileSync(resolve(root, out), 'utf8')
       } catch {
-        // Only ENOENT is expected; either read failure has the same remedy.
+        // Only ENOENT (not yet generated) is expected; a present-but-unreadable
+        // file is not a state this repo produces. Either way the remedy is the
+        // same — regenerate — so treat a read failure as "stale".
         committed = null
       }
       if (committed !== content) stale.push(out)
@@ -389,4 +745,7 @@ export function main(): void {
   console.log(`gen-cordis-catalog: wrote ${outputs.length} generated file(s).`)
 }
 
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) main()
+// Run only when invoked as a script, not when imported by a test.
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  main()
+}
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 56c1b094be..b53ff60989 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1564,6 +1564,129 @@
       "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTClientRemote",
       "source": "packages/typert/type-meta/src/types.ts"
+      "doc": "docs/subsystems/permission.md",
+      "symbol": "PresetSpec",
+      "source": "packages/interaction/permission/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/permission.md",
+      "symbol": "Config",
+      "source": "packages/interaction/permission/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/permission.md",
+      "symbol": "PresetOption",
+      "source": "packages/interaction/permission/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/plan.md",
+      "symbol": "PlanModeConfig",
+      "source": "packages/plan/plan-mode/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/invariants.md",
+      "symbol": "Config",
+      "source": "packages/support/invariants/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/invariants.md",
+      "symbol": "InvariantFailure",
+      "source": "packages/support/invariants/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/invariants.md",
+      "symbol": "InvariantInstaller",
+      "source": "packages/support/invariants/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/http-server.md",
+      "symbol": "WebRouteKind",
+      "source": "packages/host/webserver/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/http-server.md",
+      "symbol": "WebRoute",
+      "source": "packages/host/webserver/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/http-server.md",
+      "symbol": "Config",
+      "source": "packages/host/webserver/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "StorageForms",
+      "source": "packages/storage/storage/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "StorageBackend",
+      "source": "packages/storage/storage/src/backend.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "DomainSpec",
+      "source": "packages/storage/storage-domain/src/spec.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "Domain",
+      "source": "packages/storage/storage-domain/src/domain.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "DomainChangedBase",
+      "source": "packages/storage/storage-domain/src/events.ts"
+    },
+    {
+      "doc": "docs/subsystems/storage.md",
+      "symbol": "DomainChanged",
+      "source": "packages/storage/storage-domain/src/events.ts"
+    },
+    {
+      "doc": "docs/subsystems/tui.md",
+      "symbol": "TuiOverlayRequest",
+      "source": "packages/interaction/tui/src/extension.ts"
+    },
+    {
+      "doc": "docs/subsystems/tui.md",
+      "symbol": "TuiOverlayHost",
+      "source": "packages/interaction/tui/src/extension.ts"
+    },
+    {
+      "doc": "docs/subsystems/tui.md",
+      "symbol": "TuiOverlaySession",
+      "source": "packages/interaction/tui/src/extension.ts"
+    },
+    {
+      "doc": "docs/subsystems/tui.md",
+      "symbol": "TuiOverlayCloseReason",
+      "source": "packages/interaction/tui/src/extension.ts"
+    },
+    {
+      "doc": "docs/subsystems/tui.md",
+      "symbol": "TuiOverlayOutcome",
+      "source": "packages/interaction/tui/src/extension.ts"
+    },
+    {
+      "doc": "docs/subsystems/workspace.md",
+      "symbol": "WorkspaceId",
+      "source": "packages/workspace/workspace/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/workspace.md",
+      "symbol": "Workspace",
+      "source": "packages/workspace/workspace/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/client-modules.md",
+      "symbol": "WebBootEntry",
+      "source": "packages/client/modules/src/client/manifest.ts"
+    },
+    {
+      "doc": "docs/subsystems/client-modules.md",
+      "symbol": "WebBootGraph",
+      "source": "packages/client/modules/src/client/manifest.ts"
     }
   ]
 }

From 3f9c58855b0c11e6edf0385d49f8cf1cf491edf3 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 27 Jul 2026 23:29:15 +0800
Subject: [PATCH 410/516] docs: telemetry subsystem page and Chinese
 counterparts for the nine new pages

telemetry.md joins the eight pages after the OTel telemetry seam landed
on master (ctx.telemetry + telemetry/record were the one service and
event scope still without a page). All nine pages gain zh counterparts
translated whole-document per dsh-translate-docs; the eleven touched
pairs (nine new + core + the subsystems-catalog note) are recorded;
TelemetryRecord moves from TYPE_LINK_EXEMPTIONS to LINK_MAP and the
catalogs are regenerated.
---
 ...-20-core-data-structures-catalog.i18n.yaml |   4 +-
 ...2026-06-20-core-data-structures-catalog.md |   2 +-
 ...6-06-20-core-data-structures-catalog.zh.md |   2 +-
 docs/subsystems/client-modules.i18n.yaml      |   6 +
 docs/subsystems/client-modules.zh.md          |  63 ++++++++
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       |   1 +
 docs/subsystems/core.zh.md                    |   1 +
 docs/subsystems/http-server.i18n.yaml         |   6 +
 docs/subsystems/http-server.zh.md             |  49 ++++++
 docs/subsystems/invariants.i18n.yaml          |   6 +
 docs/subsystems/invariants.zh.md              |  59 +++++++
 docs/subsystems/permission.i18n.yaml          |   6 +
 docs/subsystems/permission.zh.md              |  63 ++++++++
 docs/subsystems/plan.i18n.yaml                |   6 +
 docs/subsystems/plan.zh.md                    |  39 +++++
 docs/subsystems/storage.i18n.yaml             |   6 +
 docs/subsystems/storage.zh.md                 | 125 +++++++++++++++
 docs/subsystems/telemetry.i18n.yaml           |   6 +
 docs/subsystems/telemetry.md                  | 109 +++++++++++++
 docs/subsystems/telemetry.zh.md               | 109 +++++++++++++
 docs/subsystems/workspace.i18n.yaml           |   6 +
 docs/subsystems/workspace.zh.md               | 121 ++++++++++++++
 scripts/gen-cordis-catalog.ts                 |   2 +-
 scripts/type-equiv.manifest.json              | 149 +++++++++---------
 25 files changed, 872 insertions(+), 78 deletions(-)
 create mode 100644 docs/subsystems/client-modules.i18n.yaml
 create mode 100644 docs/subsystems/client-modules.zh.md
 create mode 100644 docs/subsystems/http-server.i18n.yaml
 create mode 100644 docs/subsystems/http-server.zh.md
 create mode 100644 docs/subsystems/invariants.i18n.yaml
 create mode 100644 docs/subsystems/invariants.zh.md
 create mode 100644 docs/subsystems/permission.i18n.yaml
 create mode 100644 docs/subsystems/permission.zh.md
 create mode 100644 docs/subsystems/plan.i18n.yaml
 create mode 100644 docs/subsystems/plan.zh.md
 create mode 100644 docs/subsystems/storage.i18n.yaml
 create mode 100644 docs/subsystems/storage.zh.md
 create mode 100644 docs/subsystems/telemetry.i18n.yaml
 create mode 100644 docs/subsystems/telemetry.md
 create mode 100644 docs/subsystems/telemetry.zh.md
 create mode 100644 docs/subsystems/workspace.i18n.yaml
 create mode 100644 docs/subsystems/workspace.zh.md

diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 13c54fa458..5bc51a4e7d 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 57433fdcb3c77976c4ba0cfe7d157f94dff331dd
-2026-06-20-core-data-structures-catalog.zh.md: 3956839c8211e294280805d9b6993e5607bfe04f
+2026-06-20-core-data-structures-catalog.md: 718045bf7ce511a0b766e69e64ef7657eb221189
+2026-06-20-core-data-structures-catalog.zh.md: 1e8473a373c212fa08b171719edd5803e5aa3b05
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 025cbd7ab7..718045bf7c 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -58,4 +58,4 @@ The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and de
 - The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
-- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: the eight `ctx` services without a page (permission presets, plan mode, runtime invariants, the HTTP carrier, storage, TUI extensions, workspaces, client modules) gained lean pages, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
+- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: the nine `ctx` services without a page (permission presets, plan mode, runtime invariants, the HTTP carrier, storage, TUI extensions, workspaces, client modules, telemetry) gained lean pages, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index de644e8567..1e8473a373 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -58,4 +58,4 @@ Status: implemented
 - 主干与 seam 分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
 - `ts type-equiv` 围栏是继 ` ```ts `（编译）和 ` ```ts ignore-check `（草稿）之后的第三种文档块类别。后续的姊妹门禁又增加了第四种 ` ```ts cordis-catalog `（生成签名），复用了相同的跳过并排除处理。
 - 添加或重塑核心类型现在附带一项文档义务，作者必须履行（门禁无法检测缺失的*新*类型），由 `dsh-code-review` 检查清单兜底。
-- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：原先没有页面的八个 `ctx` 服务（权限预设、计划模式、运行时不变式、HTTP 载体、存储、终端扩展、工作区、客户端模块）都获得了精简页面，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
+- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：原先没有页面的九个 `ctx` 服务（权限预设、计划模式、运行时不变式、HTTP 载体、存储、终端扩展、工作区、客户端模块、遥测）都获得了精简页面，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
new file mode 100644
index 0000000000..a9a68fd065
--- /dev/null
+++ b/docs/subsystems/client-modules.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 docs/subsystems/client-modules.md
+client-modules.md: bd5ecdc85ea26b040e1705e373ceac4e7cb17b3c
+client-modules.zh.md: bbcdb04cdce8a0d5256d2490deb238812e9a47fc
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
new file mode 100644
index 0000000000..bbcdb04cdc
--- /dev/null
+++ b/docs/subsystems/client-modules.zh.md
@@ -0,0 +1,63 @@
+# Client 模块
+
+[English](client-modules.md) | 中文
+
+Web 插件表：[dsh-client-modules](../../packages/client/modules) 中 client 模块系统的 Node 半，以 `ctx.clientModuleHost`（`ClientModuleHostService`）形式提供。它扫描宿主 Loader 的 entry 找出 `dshClient` 包（package），组合出 `window.__DSH_BOOT__` entry 图，在 `/plugins/<id>/client.js` 提供各个 bundle，并经 index 转换（index tap）注入启动 manifest（元数据清单）——这是同一个服务的四个面。它是 Web GUI 栈的一项可选能力，不属于 agent loop（智能体循环）主干，并且是 [dsh-host-webserver](../../packages/host/webserver) 的消费方：[http-server.md](http-server.md) 所述的载体提供本服务注册的前缀路由与 index 转换。同一个包的浏览器半（`ctx.modules`，即拉取并物化这些 bundle 的 lazy CJS 模块表）属于内核机件，记录在[包 README](../../packages/client/modules/README.md)中，不在本页。
+
+源码：[`packages/client/modules/src/client/manifest.ts`](../../packages/client/modules/src/client/manifest.ts)
+
+## wire
+
+图是 Node 半与浏览器半之间的线上单源：宿主从扫描到的包组合出 `WebBootEntry` 行，把图作为 `<head>` 中的第一个脚本注入（`window.__DSH_BOOT__`，其中 `<` 已转义，插件可控的字符串因此无法逃出 script 元素），壳则在启动任何东西之前先解析它。没有有效 manifest 的页面无法启动——浏览器侧的解析器在图缺失或畸形时大声抛错。
+
+```ts type-equiv
+/**
+ * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * single source: the host node half (package root) produces this same shape.
+ * `immediately` marks stage-one prefetch; `inject` is informational graph
+ * metadata (the authoritative edges live in each package's dshClient
+ * declaration and reach fibers through entry creation).
+ */
+interface WebBootEntry {
+  /** Entry name == package name. */
+  id: string
+  /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+  url: string
+  /** Bundle content hash (cache-busting consistency anchor). */
+  rev: string
+  /** Package-name dependency edges, informational (preflight display / HMR diffing). */
+  inject?: string[]
+  /** Stage-one prefetch mark: fetch + execute (factory registration) during module-face boot. */
+  immediately?: boolean
+}
+```
+
+```ts type-equiv
+/** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
+interface WebBootGraph {
+  /** Consistency anchor over the whole graph (content + bundle hashes). */
+  rev: string
+  /** Composed entries; order carries no semantics (activation order is fiber inject waiting). */
+  entries: WebBootEntry[]
+}
+```
+
+每一行的 `rev` 是该 bundle 的内容哈希，并作为使缓存失效的查询参数附在 URL 上；图的 `rev` 对组合后的各行做哈希，因此任何一行的变化都会改变它。`immediately` 标记第一阶段预取档位（在模块面启动期间 fetch 并执行，只做工厂登记）；惰性行在首次 import 时才拉取。
+
+## 扫描
+
+包加入这张表的方式，是在自己的 package.json 中声明 `dshClient`（`platform: 'web'`、可选的 `inject` 边、可选的 `immediately`），并在 `exports["./client"]` 导出构建好的 bundle。包解析锚定在配置树的 `ctx.baseUrl`——即 cordis.yml 所在目录，该目录的包把每个被组合的插件声明为依赖——这一锚点未设置时，构造即抛错。
+
+扫描是单包增量的；不存在全量重扫代码路径。每次 cordis `internal/plugin` 发射都把该 fiber 的 entry 名标脏，一次微任务 flush 把每个脏名与实时 loader entry 对账。激活趟以全部当前 entry 灌入同一个脏集合并同步 flush，因此初扫与稳态共享一条实现——但失败姿态相反。激活时，已加载 entry 中的畸形声明或缺失 bundle 会聚合为一个大声的 `AggregateError`，列出每个损坏的包：该 fiber 进入 FAILED，由启动的大声失败 sweep 上报。稳态下，损坏的包只记录一条警告，且不得殃及其他包。
+
+包元数据——包括「非 client 包」这一否定结论——按名缓存且永不过期：插件集合的变更在重启后生效。fiber 重启原样复用其行与 rev；bundle 内容变更只经 `rebuilt()` 到达图。
+
+## 路由
+
+`GET`/`HEAD /plugins/<id>/client.js` 以 `no-cache` 从磁盘提供已注册的 bundle（锚定一致性的是 rev 查询参数，而非 HTTP 缓存）；其他方法返回 405。未知 id——或已注册、但 bundle 因尚未构建而不可读的行——回应一个大声的 404，而不是让载体的 SPA 回退把 HTML 当作 JavaScript 发出。index 转换在每次 index 渲染时注入当前图，因此刷新页面总是针对实时组合启动。
+
+## 服务
+
+`ClientModuleHostService`（`ctx.clientModuleHost`，定义于 [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)）暴露读取面与重建面；签名见生成的[服务目录](../cordis-catalog/services.md#ctxclientmodulehost--clientmodulehostservice)。`graph()` 返回当前组合出的图（两次变更之间是同一个稳定对象），`clientPath(id)` 返回该 bundle 的绝对路径。`rebuilt(id)` 是 bundle 内容到达图的唯一入口：它对文件重新哈希，只有 rev 真正变化才会重新组合图并发出通知。`onRebuilt` 按发生变化的 bundle 逐个触发并携带新 rev；`onGraphChanged` 在任何一次重新组合了图的 flush 之后触发（行的增删，或 rebuilt 带来的 rev 变化），并采用拉取模型——监听器自行重读 `graph()`。两条通知路径都会兜住监听器异常，因此一个抛错的订阅者既不能让后续订阅者被跳过，也不能杀死触发这次 flush 的一方。
+
+开发环境下，[dsh-client-hmr](../../packages/client/hmr/README.md) 是注册表的监视驱动：它的 Node 半从同步取得的基线出发，对图中每一行的 bundle 做 stat 轮询，变化时调用 `rebuilt(id)`，经 `onGraphChanged` 重新同步监视集合，并通过 SSE（Server-Sent Events）把 rev 变化广播给浏览器半。生产环境的图完全不含 HMR（热模块替换）行；模块宿主自身从不监视文件。
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 3057ee36ee..d0188cb2f3 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 8f413a7a064ad6f63e0caec31354869e51139020
-core.zh.md: d0f02f0cfc2cd30fc67aacf5b17d1daf324295c5
+core.md: 1d0bf6c61500817860dfdd452bddc25adbbeffcc
+core.zh.md: 06fd3b5a48d5267c9856c20589772047b6105b2c
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index bde64a39e4..1d0bf6c615 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -54,6 +54,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [tui.md](tui.md) | the terminal-extension seam: `TuiOverlayRequest`/`Host`/`Session`, close reasons and outcomes, the modal queue |
 | [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
 | [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
+| [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
 
 > Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](../cordis-catalog/services.md).
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 1f21785cad..06fd3b5a48 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -54,6 +54,7 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
+| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
 
 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](../cordis-catalog/services.md)。
 
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
new file mode 100644
index 0000000000..cb2c734255
--- /dev/null
+++ b/docs/subsystems/http-server.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 docs/subsystems/http-server.md
+http-server.md: 565df72f2720a1211f50650d4b1bc8d6df4a007a
+http-server.zh.md: 93b056648f044f6c79b85a6069deb3123f9a7a3e
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
new file mode 100644
index 0000000000..fc5e18414b
--- /dev/null
+++ b/docs/subsystems/http-server.zh.md
@@ -0,0 +1,49 @@
+# HTTP 服务器
+
+[English](http-server.md) | 中文
+
+[dsh-host-webserver](../../packages/host/webserver) 是 GUI 宿主 web 形态的 HTTP 载体：单个提供 `ctx.httpServer` 的 `node:http` 插件，由具名路由注册表加 index.html 转换挂点组成，兜底是静态 dist 回退。它不属于 agent loop（智能体循环）主干，也不是能力 seam：它不了解任何 harness 概念，每个功能表面（`/api` 桥接、插件 bundle、HMR（热模块替换）事件流）都是由其他插件注册的一条路由（[分层说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)）。仅限 web（浏览器）形态：Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，不经过本服务器。
+
+源码：[`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
+
+## 路由
+
+```ts type-equiv
+/** Route match kind: 'exact' matches the pathname verbatim; 'prefix' p matches p and p/<anything>. */
+type WebRouteKind = 'exact' | 'prefix'
+```
+
+```ts type-equiv
+/** One named route registration. */
+interface WebRoute {
+  kind: WebRouteKind
+  /** Absolute pathname, no trailing slash. */
+  path: string
+  /** Owns the full response lifecycle (may hold the response open, e.g. SSE). */
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+```
+
+匹配顺序固定：先查 exact 表，再取最长匹配前缀，最后落到静态 dist 回退。注册顺序不携带任何面向请求的语义：具名路由在组合上互不相交，启动窗口期内尚未被认领的请求全部由回退应答。回退保持锁定语义：非 GET/HEAD 返回 405，越出 dist 根目录的路径穿越返回 403，任何未命中都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 交付（[`static.ts`](../../packages/host/webserver/src/static.ts)）。
+
+## 配置
+
+```ts type-equiv
+/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+interface Config {
+  /** Listen host; the two supported values are loopback and all-interfaces. */
+  host: '127.0.0.1' | '0.0.0.0'
+  /** Listen port; zero requests an OS-assigned port. */
+  port: number
+  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
+  distIndex: string
+}
+```
+
+`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（刻意的网络暴露）；没有 TLS、认证或 origin 策略，因此绑定到非回环地址会把服务器暴露给该网络。`distIndex` 是组合应用解析后注入的组装事实。
+
+## 服务
+
+`HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动阶段的大声失败巡检报告。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层面的契约，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
+
+处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能保持响应打开（如 SSE（Server-Sent Events）），而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
new file mode 100644
index 0000000000..dc5a8a6d0d
--- /dev/null
+++ b/docs/subsystems/invariants.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 docs/subsystems/invariants.md
+invariants.md: 143a7feabbab18556f595a78c7aef17caa6d3028
+invariants.zh.md: ab7aa0221101400d552ff47e1cfa3275d99a0b6d
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
new file mode 100644
index 0000000000..ab7aa02211
--- /dev/null
+++ b/docs/subsystems/invariants.zh.md
@@ -0,0 +1,59 @@
+# 运行时不变式
+
+[English](invariants.md) | 中文
+
+[dsh-invariants](../../packages/support/invariants) 是面向包（package）自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 伴随插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；seam 设计由[不变式服务 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md)规定。
+
+源码：[`packages/support/invariants/src/index.ts`](../../packages/support/invariants/src/index.ts)
+
+## 选择
+
+```ts type-equiv
+/** Runtime invariant selection configured on the service plugin. */
+interface Config {
+  /** Global switch; defaults to `true`. */
+  readonly enabled?: boolean
+  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
+  readonly package_allowlist?: string[]
+  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
+  readonly package_blocklist?: string[]
+}
+```
+
+一个包被选中的条件是：服务已启用，允许列表为空或至少一个模式匹配其完整 npm 名称，且没有任何阻止列表模式匹配；阻止列表匹配优先于允许列表匹配。条目用 `new RegExp(source)` 编译：除非模式自带 `^` 和 `$`，匹配不锚定；`/pattern/flags` 语法不被解析。校验在服务启动时大声失败：空白、带空白填充、重复或无效的条目会抛出异常，而不是被跳过。有效模式可以不匹配任何当前已加载的包，因此后续加载与 HMR（热模块替换）保持确定性；过滤器在服务生命周期内固定不变（[README](../../packages/support/invariants/README.md)）。
+
+## 安装器
+
+```ts type-equiv
+/**
+ * Throw a package-attributed invariant failure.
+ * @param message - violated package contract without the standard prefix.
+ * @returns never because reporting a violation throws.
+ */
+type InvariantFailure = (message: string) => never
+```
+
+```ts type-equiv
+/** Install one package's checks into the registration's child context. */
+interface InvariantInstaller {
+  /**
+   * Install the package contribution.
+   * @param ctx - child context owned by this invariant registration.
+   * @param fail - reporter bound to the registering package name.
+   * @returns nothing, or a promise settling after asynchronous checks finish.
+   */
+  (ctx: Context, fail: InvariantFailure): void | Promise<void>
+  /** Services the child installer fiber may access. */
+  readonly inject?: Inject
+}
+```
+
+被启用的安装器在专属的子 Cordis fiber 中运行；`installer.inject` 声明该 fiber 可以访问的服务，注册成功之前会先等待安装器同步或异步地执行完毕。`fail(message)` 抛出 `InvariantError`（`extends Error`，带稳定的 `code: 'INVARIANT'`、所属 `packageName`，以及前缀为 `invariant violated by "<package>": …` 的消息），因此违规可归因，而注册表无需导入任何产品包。
+
+## 服务
+
+`ctx.invariants.register(packageName, installer)` 为完整 npm 包名保留唯一一个活跃注册，并返回其绑定到 effect 的 disposer。即使过滤器使安装器保持不活跃，保留依然成立，因此两个插件绝不可能静默认领同一个包名；重复、空白或含空白字符的名称会抛出异常。安装器失败会原子地 dispose（资源释放）子 fiber 并释放保留。服务拥有每个注册 fiber，而返回的 disposer 同时属于伴随插件的 fiber：卸载任一侧都会移除监听器、trace 状态和保留项，因此伴随插件可以重载并再次注册同一名称，不留残余状态。
+
+## 伴随插件契约
+
+每个工作区包都拥有一个 `./invariant` 伴随插件（[包契约](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但断言刻意不为凑数而虚构。只有当包对某个可观察事件或可变数据拥有所有权关系时，伴随插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行伴随插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
new file mode 100644
index 0000000000..f800d4ff08
--- /dev/null
+++ b/docs/subsystems/permission.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 docs/subsystems/permission.md
+permission.md: 49dd51ff86d0dbce26fca0ed21527f71bb144dec
+permission.zh.md: 5fb93e9f923582e6c530bac4a22e2ce62cff156d
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
new file mode 100644
index 0000000000..5fb93e9f92
--- /dev/null
+++ b/docs/subsystems/permission.zh.md
@@ -0,0 +1,63 @@
+# 权限预设
+
+[English](permission.md) | 中文
+
+[dsh-permission](../../packages/ui/permission) 的权限预设层（`ctx.permission`，`PermissionService`）把两个相互独立的强制执行旋钮，即[沙箱模式](sandbox.md)（`sandbox/mode`）与[审批策略](approval.md)（`approval/policy`），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自旋钮的折叠结果，预设切换只记录意图，并通过每个旋钮各自的规范 setter 写入。[包（package）README](../../packages/ui/permission/README.md) 负责组合状态与限制；[沙箱切换设计](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责决策依据。
+
+源码：[`packages/ui/permission/src/index.ts`](../../packages/ui/permission/src/index.ts)
+
+## 预设表
+
+预设是一个表键，映射到一组沙箱／审批组合，外加可选的客户端展示信息；默认预设表自带 `workspace-write`（`workspace-write` + `ask`）和 `danger-full-access`（`danger-full-access` + `never`）。
+
+```ts type-equiv
+/** One preset's sandbox/approval bundle and optional client presentation. */
+interface PresetSpec {
+  /** The `sandbox/mode` value the preset writes through. */
+  sandbox: SandboxMode
+  /** The `approval/policy` value the preset writes through. */
+  approval: ApprovalPolicy
+  /** The display label a client shows for this preset; the raw table key when omitted. */
+  name?: string
+  /** One user-facing sentence on what the preset means; omitted when not configured. */
+  description?: string
+}
+```
+
+```ts type-equiv
+/** The {@link PermissionService} config: the deployment's preset table. */
+interface Config {
+  /**
+   * The preset table: name → knob bundle. Defaults to `workspace-write`
+   * (workspace-write + ask) and `danger-full-access` (danger-full-access +
+   * never). The name `custom` is reserved for the derived not-a-preset state.
+   */
+  presets?: Record<string, PresetSpec>
+}
+```
+
+该服务要求一个施加沙箱隔离的 `ctx.bash` 执行器和 `ctx.approval`，配置错误在插件加载时即失败：名为 `custom` 的表项会抛出异常（该名称保留给派生的「非预设」状态）；在不施加隔离的 bash 执行器（没有 `sandboxMode` 能力事实）之上组合同样抛出异常，因为预设捆绑了一个沙箱模式。
+
+## 当前预设与派生的 `custom`
+
+`current(events)` 从旋钮派生实际生效的预设，而不是只看自身事件：它折叠会话的生效沙箱模式（回退到执行器配置的模式）与生效审批策略（先回退到审批服务配置，再回退到 `ask`），优先取仍然匹配的已记录选择，其次取声明顺序中第一个匹配的表项，否则返回 `CUSTOM_PRESET`（`'custom'`）。`custom` 只是派生值：客户端可以把它显示为当前值，但它绝不是切换目标，也绝不出现在事件 payload 中。
+
+`names` 按预设表声明顺序列出可切换的预设；`optionOf(name)` 为某个表键（label 回退为该键）或 `custom` 构建客户端渲染的选项，传入其他任何名称都会抛出异常。
+
+```ts type-equiv
+/** The select-option shape a presentation layer advertises for one preset (or for the derived `custom` state). */
+interface PresetOption {
+  /** Stable option value: the table key, or `custom`. */
+  value: string
+  /** The display label. */
+  name: string
+  /** One user-facing sentence on what the value means. */
+  description?: string
+}
+```
+
+## 切换与 `permission/preset` 事件
+
+`set(session, name)` 解析预设（未知名称抛出异常），在 `name` 尚不是生效预设时追加一条仅记日志的 `permission/preset` 事件，然后通过各旋钮自己的 setter（[dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) 的 `setSandboxMode` 与 [dsh-user-approval](../../packages/ui/user-approval) 的 `setApprovalPolicy`）写入，且仅当该旋钮的生效值发生变化时才写。同一轮次内，选择事件先于旋钮事件出现；重新选择当前生效的预设则什么都不追加。
+
+`permission/preset` 是持久、仅记日志的用户意图：它不进入模型 transcript（文本记录），模型可见的后果由旋钮事件经各自消费方承担；它存在是为了在两个预设共享同一个旋钮组合时，让 `current()` 仍能保住用户选择的究竟是哪一个预设；`effectivePermissionPreset(events)` 折叠最后一条，回放不需要任何追赶状态。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)；方法签名见生成的[服务目录](../cordis-catalog/services.md#ctxpermission--permissionservice)。
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
new file mode 100644
index 0000000000..3ae156615f
--- /dev/null
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
+plan.md: f67e7734ca3fd55c284d3d41227f8241de7b9f5f
+plan.zh.md: 565cf2016636acb6c26d20c731b9e6e374cee1da
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
new file mode 100644
index 0000000000..af21a6d027
--- /dev/null
+++ b/docs/subsystems/plan.zh.md
@@ -0,0 +1,39 @@
+# 计划模式
+
+[English](plan.md) | 中文
+
+计划模式是 [dsh-plan-mode](../../packages/plan/plan-mode) 拥有的、记录到日志的逐 agent（智能体）协作状态（`ctx.planMode`，`PlanModeService`）：激活期间，一段部署持有的指引段落会影响每个模型请求。它是**软性指引**，有意独立于[沙箱模式](sandbox.md)与[审批策略](approval.md)这两条强制执行轴：那些旋钮（knob）从不读写计划状态，需要硬边界的部署另行组合两者。该包（package）是一项可选能力，不属于 agent loop（智能体循环）主干；它的对外表面是 `plan:policy` 提示词段落、始终保持注册的 `exit_plan_mode` 工具和 `/plan` 命令。[设计说明](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)负责决策依据；[包 README](../../packages/plan/plan-mode/README.md) 负责模型体验与限制细节。
+
+源码：[`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/src/index.ts)
+
+## 已记录状态与恢复
+
+`plan/mode`（`{ active: boolean }`）是仅记日志、整值替换的[会话事件](session.md)：持久且可回放，绝不进入模型 transcript（文本记录）。`foldPlanMode(events, end?)` 返回前缀中最后一条已记录值，没有时返回 `false`：生效状态始终是会话日志的纯折叠，因此恢复、fork 与压缩（compaction）无需实时镜像即可将其复原，UI 通过 `session/event` 观察已提交的切换。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)。
+
+## 待定意图与轮次边界冲刷
+
+由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到轮次边界。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
+
+服务会在三类边界处、于受影响的请求组装之前冲刷一条待定选择：提示词提交、普通轮次延续和请求恢复重试。冲刷在下游监听器链之后运行，因此在某个异步监听器等待期间到达的选择，仍会影响该边界紧接其后的那个请求。冲刷失败会被隔离（计划策略绝不能阻塞提示词或轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
+
+## 配置
+
+```ts type-equiv
+/** Deployment-owned plan guidance. */
+interface PlanModeConfig {
+  /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
+  section: string
+}
+```
+
+`section` 缺失、为空白或不是字符串，以及任何未知键，都会在插件加载时失败，而不是静默地什么都不影响。计划模式激活期间，确切的 `section` 文本以 order 50 渲染为 `plan:policy` [系统提示词段落](system-prompt.md)；未激活的计划模式不贡献任何文本。
+
+## 退出工具与 `/plan` 命令
+
+[`exit_plan_mode`](../tool-catalog.md#deepseek-aidsh-plan-mode) 在计划模式未激活时仍保持注册，因此跨越边界只改变提示词段落，绝不改变请求的工具目录；在计划模式之外执行会失败。在计划模式中，它要求一份以 `#` 标题开头的完整 markdown 计划，并通过[用户交互 seam](user-interaction.md) 呈交评审。批准返回 `{ approved: true }`，并记录一个静默（不叙述）的待定退出，在该步骤之后冲刷：计划指引在 assistant 本批工具调用的剩余部分继续生效，而工具结果本身叙述这次转换。「继续规划」则是一次携带用户反馈的失败调用，模型据此修订并再次呈交；评审期间交互通道缺失或服务重载同样使调用失败，而不是静默离开计划模式。
+
+当 [`ctx.commands`](commands.md) 被组合时，插件注册 `/plan [off|message]`：单独的 `/plan` 选择计划模式；任何其他非空消息先选择计划模式，再通过 `agent.steer()` 提交该文本，使其在计划指引下成为下一步骤的普通已记录用户消息；确切参数 `off` 选择未激活，这还会在计划模式尚未进入任何请求之前，取消尚未冲刷的待定条目。
+
+## 服务
+
+`ctx.planMode` 拥有已记录的计划状态、边界处的应用与叙述、`plan:policy` 段落、`/plan` 命令和稳定注册的退出工具；`get`/`set` 签名见生成的[服务目录](../cordis-catalog/services.md#ctxplanmode--planmodeservice)。
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
new file mode 100644
index 0000000000..92387332f0
--- /dev/null
+++ b/docs/subsystems/storage.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 docs/subsystems/storage.md
+storage.md: 5d54d7337b5ef52e24179758130b9fa8cd196376
+storage.zh.md: c575f989fe4b3536ce3c8d3b3af08ebda418166d
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
new file mode 100644
index 0000000000..c575f989fe
--- /dev/null
+++ b/docs/subsystems/storage.zh.md
@@ -0,0 +1,125 @@
+# 存储
+
+[English](storage.md) | 中文
+
+存储子系统持久保存一切不属于会话事件日志的数据（会话日志有自己的 seam——见 [persistence.md](persistence.md)）。它是一项可选能力，不属于 agent loop（智能体循环）主干，并按[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)拆分：枢纽（hub）与后端接口（[dsh-storage](../../packages/storage/storage)，`ctx.storage`）、后端实现（注册为 `json` 的 [dsh-storage-json](../../packages/storage/storage-json) 与注册为 `sqlite` 的 [dsh-storage-sqlite](../../packages/storage/storage-sqlite)），以及领域数据形式（[dsh-storage-domain](../../packages/storage/storage-domain)，`ctx.storageDomain`，也可经 `ctx.storage.domain` 访问）——它是后端 seam 的唯一消费方，也是其他一切所使用的类型化 API。枢纽自身不做任何 IO：后端拥有介质，数据形式拥有语义，产品包（package）绝不直接触碰后端。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
+
+源码：[`packages/storage/storage/src/backend.ts`](../../packages/storage/storage/src/backend.ts) · [`packages/storage/storage-domain/src/spec.ts`](../../packages/storage/storage-domain/src/spec.ts) · [`packages/storage/storage-domain/src/events.ts`](../../packages/storage/storage-domain/src/events.ts)
+
+## 枢纽：`ctx.storage`
+
+`Storage`（[签名](../cordis-catalog/services.md#ctxstorage--storage)）是汇合点，不是存储本体。`ctx.storage.backend` 是一张名称 → 后端的表：多个后端并排保持挂载，哪个后端服务哪个消费方由该消费方自己的配置决定（即领域层的路由表），绝不是枢纽全局的选择。`register(name, backend)` 返回 disposer；重复名称与查找未知名称都抛出 `StorageError`。dispose（资源释放）只注销名称——由拥有插件在注销之后自行关闭后端。每个后端插件还会发布一个仅用于生命周期的服务键（`storageBackendServiceKey(name)`），数据形式提供方注入它，使自身激活不会与后端注册发生竞态。
+
+数据形式以一张可合并扩展的键 map 挂载到枢纽上：
+
+```ts type-equiv
+/**
+ * Data forms mountable on the hub, keyed by form name. Form owners extend
+ * this map via declaration merging (the domain layer merges
+ * `domain: DomainFacility`) and mount the facility in their `apply`.
+ */
+interface StorageForms {}
+```
+
+`mount(form, facility)` 是一个 effect，其 disposer 负责卸载；对同一键的第二次挂载抛出 `duplicate-mount`。`form(form)` 解析已挂载的 facility，在拥有插件加载之前抛出 `form-not-mounted`——组合方应据此安排插件顺序，而不是静默推迟。领域层合并 `domain: DomainFacility`，因此 `ctx.storage.domain` 与 `ctx.storageDomain` 是同一个对象。
+
+## 后端 seam
+
+```ts type-equiv
+/**
+ * One registered backend. A backend owns exactly one medium and shares its
+ * lifecycle across all facets; facets are optional members — a backend that
+ * cannot serve a shape simply omits it, and resolution fails loud instead.
+ */
+interface StorageBackend {
+  /** Key-value data shape; absent when this backend cannot serve it. */
+  readonly kv?: KvFacet
+
+  /**
+   * Drain in-flight writes across all open units and release the medium.
+   * Idempotent; concurrent and repeated calls resolve once teardown finishes.
+   * @returns resolution after the medium is released.
+   */
+  close(): Promise<void>
+}
+```
+
+一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并暴露可选的数据形状 facet；目前 `kv` 是唯一的 facet。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、格式版本、表名清单，以及是否存在全局单例槽位——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键是任意字符串，绝不进入文件路径。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的，且 resolve 后即已持久。介质上记录的版本与之不同时拒绝 `version-mismatch`；无法按该 unit 解析的介质拒绝 `malformed-medium`（不做迁移：预发布立场）。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性契约，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件对每个后端断言其中每一条款。[json 后端](../../packages/storage/storage-json/README.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.md)在单个数据库中按一行一文档存储，是高频更新领域的路由选择。
+
+## 声明领域
+
+领域由其拥有包声明一次，形式是一个 spec 对象——它是该领域的身份、布局和记录 schema 的单一来源（schema 用 zod 编写，因此 `z.infer` 让消费方类型无需重复声明）：
+
+```ts type-equiv
+/** Static declaration of one domain: identity, version, and record layout. */
+interface DomainSpec {
+  /** Domain name; must match `UNIT_NAME_RE` (doubles as the backend unit name). */
+  readonly name: string
+  /** Domain format version; a medium stamped with a different version rejects at open. */
+  readonly version: number
+  /** Optional global singleton slot. */
+  readonly global?: DomainGlobalSpec<unknown>
+  /** Table declarations keyed by table name; each name must match `UNIT_NAME_RE`. */
+  readonly tables: Record<string, DomainTableSpec>
+}
+```
+
+`defineDomain(spec)` 固定 spec 的字面量类型，并在拥有方的模块加载时、任何介质被触碰之前就大声失败：领域名或表名不匹配 `UNIT_NAME_RE`、版本不是非负整数、global schema 接受 `null`，这些都会抛出（`null` 是介质的「从未写入」哨兵值，可空的 global 一旦存储就无法往返还原）。`domainTable<K, V>(schema)` 声明一张表，其键类型是编译期的幻影类型（通常是[品牌化 id](core.md#branded-ids)）；`descriptorOf(spec)` 投影出面向后端的 unit 描述符。
+
+## 打开的领域
+
+```ts type-equiv
+/** One open domain, typed by its spec. */
+interface Domain<S extends DomainSpec> {
+  /** Domain name from the spec. */
+  readonly name: string
+  /** Global singleton handle; a spec without `global` has no usable handle (`never`). */
+  readonly global: DomainGlobalHandleOf<S>
+  /**
+   * Resolve one declared table handle. Handles are stable — repeated calls
+   * return the same instance.
+   * @param name - Declared table name.
+   * @returns the typed table handle.
+   */
+  table<N extends keyof S['tables'] & string>(name: N): KvTable<TableKeyOf<S, N>, TableValueOf<S, N>>
+
+  /**
+   * Close this domain: reject new writes immediately, drain already-queued
+   * writes (their events still emit), release the backend unit, then free
+   * the domain name for a later open. Idempotent — repeated calls share one
+   * teardown. The consumer owns this call (typically as its own `ctx.effect`
+   * disposer); the facility closes any domain left open when it unmounts.
+   * @returns resolution after the unit is released.
+   */
+  close(): Promise<void>
+}
+```
+
+读取是同步的，来自权威的内存态：`KvTable` 暴露 `get`/`entries`/`keys`/`size`（快照迭代器，在排队写入落地期间保持稳定），global 句柄的 `get()` 在第一次 `set` 将槽位物化到介质之前一直返回 spec 的 `initial`。每次写入——`put`、`delete`、`update`、`global.set`——都在同一条逐领域写链上排队，先到达后端持久性，再更新内存，最后发出 `domain/changed`；后端写入被拒时内存原样不动，因此读取绝不会偏离介质。`update(key, fn)` 在其写链槽位上是一次原子的读-改-写（键缺失时拒绝 `missing-key`）；`delete` 一个不存在的键 resolve 为 `false`，不产生写入也不产生事件。返回的记录就是存储的对象本身，不是副本——请经 `put`/`update` 整体替换，绝不要就地修改。
+
+## 领域 facility：`ctx.storageDomain`
+
+`DomainFacility`（[签名](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)）在经过路由的后端之上打开已声明的领域。路由是领域插件的配置，绝不属于枢纽：`backend` 指定必填的默认路由，`routes` 按领域名逐个覆盖。`open(spec)` 逐步执行，任一步失败都使整个调用失败：拒绝已打开或仍在关闭中的名称（`already-open`），解析路由（`backend-not-found`），要求后端具备 `kv` facet（`facet-unsupported`），打开 unit（后端的 `version-mismatch`/`malformed-medium` 原样透传），并按 spec 的 zod schema 校验每条已存储记录和 global（`invalid-record`，附带出错的表与键）。调用方拥有返回的句柄，并用 `Domain.close()` 释放它；插件卸载时仍处于打开状态的领域由 facility 负责关闭，已关闭领域的名称只有在拆除完全结束后才释放出来供重新打开。`get(name)` 是无类型的诊断查找；`closeAll()` 是卸载路径。
+
+## 变更事件：`domain/changed`
+
+每次持久写入都发出一个事件，严格发生在后端确认持久性之后，顺序遵循该领域的写链（[事件条目](../cordis-catalog/events.md#domainchanged--emit)）：
+
+```ts type-equiv
+/** Shared location fields of one durable domain change. */
+interface DomainChangedBase {
+  /** Owning domain name. */
+  readonly domain: string
+  /** Table name; `''` for a global-singleton write. */
+  readonly table: string
+  /** Record key; `''` for a global-singleton write. */
+  readonly key: string
+}
+```
+
+```ts type-equiv
+/** One durable domain change; a closed union — switch on `operation`. */
+type DomainChanged = DomainChangedPut | DomainChangedDeleted
+```
+
+`put`（插入、覆写和 global 写入）在 `value` 中携带新快照——绝不携带旧值；需要做差异比较的消费方自行保留上一份快照。`deleted` 是不携带值的墓碑。该事件是通知，不是事务参与者：发出时提交点已经过去，因此同步抛出的监听器会被兜住并记录一条警告，而不会让已经持久的写入被拒绝；发出的值等于发出时刻的内存态。该事件仅限进程内；跨进程的变更推送是延后工作，记录在[包 README](../../packages/storage/storage-domain/README.md)中。
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
new file mode 100644
index 0000000000..9f6fdb3af3
--- /dev/null
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
+telemetry.md: 4942a402dacb40ed64070c2b7824bfea7a14c872
+telemetry.zh.md: c99b287fd4cb4e9bc585ffe365ca08df37f6ccd1
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
new file mode 100644
index 0000000000..4942a402da
--- /dev/null
+++ b/docs/subsystems/telemetry.md
@@ -0,0 +1,109 @@
+# Telemetry
+
+English | [中文](telemetry.zh.md)
+
+Outbound session reporting, split as a [capability seam](../capability-seams.md): the seam ([dsh-session-telemetry](../../packages/telemetry/session-telemetry), `ctx.telemetry`) owns the capture points, the fixed chunk projection, the `telemetry/record` redaction waterfall, the handoff cursor, and the minimal backend contract; the backend a deployment loads ([dsh-session-telemetry-otel](../../packages/telemetry/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [seam README](../../packages/telemetry/session-telemetry/README.md).
+
+Source: [`packages/telemetry/session-telemetry/src/index.ts`](../../packages/telemetry/session-telemetry/src/index.ts)
+
+## The logical record
+
+```ts type-equiv
+/**
+ * Severity of a telemetry record, pre-mapped at capture so a receiver can
+ * alert with zero configuration: `error` for events whose own outcome flag
+ * says so (`tool/result.isError`, `turn/end` error reasons) and for
+ * `agent-error` operational records. Captured events otherwise default to
+ * `info`; `warn` remains available to `telemetry/record` policies and
+ * backends.
+ */
+type TelemetrySeverity = 'info' | 'warn' | 'error'
+```
+
+```ts type-equiv
+/**
+ * One logical record handed to a backend — the seam's whole outbound
+ * vocabulary. Ledger records mirror session-log events one-to-one;
+ * operational records (`channel: 'ops'`) carry the two signals with no log
+ * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
+ * identity so they can never be mistaken for ledger rows.
+ */
+interface TelemetryRecord {
+  /** Ledger (session-log mirror) or ops (operational signal) channel; backends keep the two under separate instrumentation scopes. */
+  channel: 'ledger' | 'ops'
+  /** Unix epoch milliseconds — the source event's append time for ledger records, the emission time for ops records. */
+  time: number
+  /** Pre-mapped alerting severity; see {@link TelemetrySeverity}. */
+  severity: TelemetrySeverity
+  /**
+   * Identity attributes, deliberately minimal: ledger records carry
+   * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
+   * `session.parent_id` when the header has them; ops records carry
+   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
+   * `turn`, `step`, `error.name`. Anything recoverable from the body is
+   * intentionally NOT duplicated here.
+   */
+  attributes: Record<string, string | number>
+  /**
+   * The complete payload: a deep copy of the session event's `data` for
+   * ledger records (JSON-serializable by `Session.append`'s own
+   * validation), or the op payload for ops records. Never mutated after
+   * handoff.
+   */
+  body: unknown
+}
+```
+
+Only the first `assistant/chunk` of each `(turn, step)` ships — the stream-started signal; the rest drop at capture, so `seq` gaps are routine on the wire and never a loss signal. Every other [session event](session.md) type, including plugin-merged ones the seam never heard of, passes through whole. Delivery is at-most-once downstream of the handoff; receivers dedupe on `(session.id, event.seq)`.
+
+## The backend contract
+
+```ts type-equiv
+/**
+ * The backend contract the coordinator hands records to — the minimum any
+ * reporting SDK satisfies with zero bending. {@link Telemetry} is its
+ * service-registered form; tests compose the coordinator with a bare
+ * implementation of this interface.
+ */
+interface TelemetryBackend {
+  /**
+   * Hand one record to the backend's pipeline. MUST be a non-blocking
+   * enqueue — the coordinator calls this synchronously from the
+   * `session/event` hot path, so anything slower than a queue push would tax
+   * the agent loop. Errors thrown here are contained by the coordinator and
+   * logged; they never reach the loop.
+   * @param record - the logical record to report; owned by the backend after the call.
+   */
+  emit(record: TelemetryRecord): void
+  /**
+   * Optional hint that a natural boundary (turn end) passed — a backend may
+   * forward it to its SDK's flush so records land at turn boundaries. Called
+   * fire-and-forget; implementations must not block and must not throw
+   * meaningfully (the coordinator contains exceptions). Most backends should
+   * leave this unimplemented and let their SDK's own batching cadence govern
+   * export timing: a backend that does implement it owns the interaction
+   * between its concurrent flushes and {@link shutdown}'s drain (the OTel
+   * backend removed its implementation for exactly that hazard — see the
+   * revival Agent Note).
+   */
+  flush?(): void
+  /**
+   * Forward the fiber's disposal to the SDK: flush whatever is queued and
+   * reach quiescence, per the SDK's own shutdown contract. Everything
+   * emitted before this call must still be delivered — including records
+   * enqueued while a {@link flush} hint is in flight, so a backend whose SDK
+   * guards against concurrent flushes orders behind the outstanding one (the
+   * coordinator emits its dispose-time `shutdown` markers immediately before
+   * calling this). Awaited by the coordinator's dispose; a rejection is
+   * logged as a warning and never fails application teardown.
+   * @returns resolves when the backend's pipeline has quiesced.
+   */
+  shutdown(): Promise<void>
+}
+```
+
+`Telemetry` (`ctx.telemetry`, [signatures](../cordis-catalog/services.md#ctxtelemetry--telemetry-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
+
+## The redact waterfall: `telemetry/record`
+
+Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics) between projection and `emit()` ([event entry](../cordis-catalog/events.md#telemetryrecord--waterfall)). The seam ships NO rules of its own: with no listener mounted, records reach the backend exactly as captured, so exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath; a throwing listener withholds that one record fail-closed inside the coordinator's containment. Redaction applies to the exported copy only — the canonical session log is never rewritten.
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
new file mode 100644
index 0000000000..c99b287fd4
--- /dev/null
+++ b/docs/subsystems/telemetry.zh.md
@@ -0,0 +1,109 @@
+# 遥测（telemetry）
+
+[English](telemetry.md) | 中文
+
+对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/telemetry/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端契约；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/telemetry/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的契约见 [seam README](../../packages/telemetry/session-telemetry/README.md)。
+
+源码：[`packages/telemetry/session-telemetry/src/index.ts`](../../packages/telemetry/session-telemetry/src/index.ts)
+
+## 逻辑记录
+
+```ts type-equiv
+/**
+ * Severity of a telemetry record, pre-mapped at capture so a receiver can
+ * alert with zero configuration: `error` for events whose own outcome flag
+ * says so (`tool/result.isError`, `turn/end` error reasons) and for
+ * `agent-error` operational records. Captured events otherwise default to
+ * `info`; `warn` remains available to `telemetry/record` policies and
+ * backends.
+ */
+type TelemetrySeverity = 'info' | 'warn' | 'error'
+```
+
+```ts type-equiv
+/**
+ * One logical record handed to a backend — the seam's whole outbound
+ * vocabulary. Ledger records mirror session-log events one-to-one;
+ * operational records (`channel: 'ops'`) carry the two signals with no log
+ * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
+ * identity so they can never be mistaken for ledger rows.
+ */
+interface TelemetryRecord {
+  /** Ledger (session-log mirror) or ops (operational signal) channel; backends keep the two under separate instrumentation scopes. */
+  channel: 'ledger' | 'ops'
+  /** Unix epoch milliseconds — the source event's append time for ledger records, the emission time for ops records. */
+  time: number
+  /** Pre-mapped alerting severity; see {@link TelemetrySeverity}. */
+  severity: TelemetrySeverity
+  /**
+   * Identity attributes, deliberately minimal: ledger records carry
+   * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
+   * `session.parent_id` when the header has them; ops records carry
+   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
+   * `turn`, `step`, `error.name`. Anything recoverable from the body is
+   * intentionally NOT duplicated here.
+   */
+  attributes: Record<string, string | number>
+  /**
+   * The complete payload: a deep copy of the session event's `data` for
+   * ledger records (JSON-serializable by `Session.append`'s own
+   * validation), or the op payload for ops records. Never mutated after
+   * handoff.
+   */
+  body: unknown
+}
+```
+
+每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。交接下游的投递为至多一次（at-most-once）；接收端基于 `(session.id, event.seq)` 去重。
+
+## 后端契约
+
+```ts type-equiv
+/**
+ * The backend contract the coordinator hands records to — the minimum any
+ * reporting SDK satisfies with zero bending. {@link Telemetry} is its
+ * service-registered form; tests compose the coordinator with a bare
+ * implementation of this interface.
+ */
+interface TelemetryBackend {
+  /**
+   * Hand one record to the backend's pipeline. MUST be a non-blocking
+   * enqueue — the coordinator calls this synchronously from the
+   * `session/event` hot path, so anything slower than a queue push would tax
+   * the agent loop. Errors thrown here are contained by the coordinator and
+   * logged; they never reach the loop.
+   * @param record - the logical record to report; owned by the backend after the call.
+   */
+  emit(record: TelemetryRecord): void
+  /**
+   * Optional hint that a natural boundary (turn end) passed — a backend may
+   * forward it to its SDK's flush so records land at turn boundaries. Called
+   * fire-and-forget; implementations must not block and must not throw
+   * meaningfully (the coordinator contains exceptions). Most backends should
+   * leave this unimplemented and let their SDK's own batching cadence govern
+   * export timing: a backend that does implement it owns the interaction
+   * between its concurrent flushes and {@link shutdown}'s drain (the OTel
+   * backend removed its implementation for exactly that hazard — see the
+   * revival Agent Note).
+   */
+  flush?(): void
+  /**
+   * Forward the fiber's disposal to the SDK: flush whatever is queued and
+   * reach quiescence, per the SDK's own shutdown contract. Everything
+   * emitted before this call must still be delivered — including records
+   * enqueued while a {@link flush} hint is in flight, so a backend whose SDK
+   * guards against concurrent flushes orders behind the outstanding one (the
+   * coordinator emits its dispose-time `shutdown` markers immediately before
+   * calling this). Awaited by the coordinator's dispose; a rejection is
+   * logged as a warning and never fails application teardown.
+   * @returns resolves when the backend's pipeline has quiesced.
+   */
+  shutdown(): Promise<void>
+}
+```
+
+`Telemetry`（`ctx.telemetry`，[签名](../cordis-catalog/services.md#ctxtelemetry--telemetry-abstract-seam)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
+
+## 脱敏 waterfall：`telemetry/record`
+
+每条记录在投影与 `emit()` 之间都要经过 `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics)（[事件条目](../cordis-catalog/events.md#telemetryrecord--waterfall)）。seam 自身不带任何规则：未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式扣下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
new file mode 100644
index 0000000000..5540d00aab
--- /dev/null
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
+workspace.md: 2726115457905687e3c2cfc35a7a3f7251e6347c
+workspace.zh.md: 190c44b2d73f9e123242c34b5429839abe3b9297
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
new file mode 100644
index 0000000000..190c44b2d7
--- /dev/null
+++ b/docs/subsystems/workspace.zh.md
@@ -0,0 +1,121 @@
+# 工作区
+
+[English](workspace.md) | 中文
+
+工作区（workspace）是用户工作目录的持久记录：一个建立在规范路径之上的稳定 id、一个显示标题，以及归属于它的会话的有序账本。该子系统是单个包（package）（[dsh-workspace](../../packages/workspace/workspace)，`ctx.workspace`）——一项宿主侧可选能力，不属于 agent loop（智能体循环）主干，并且对模型不可见（没有工具、没有提示词文本、没有会话事件）。它通过[存储领域数据形式](storage.md)存储自己的记录，并对照 [`SessionHeader.cwd`](persistence.md#sessionheader--metadata-beside-the-log) 校验会话成员资格，因此 `storageDomain` 与 `sessionPersistence` 是必需的启动依赖：持久化这一侧不可用时插件保持 pending，而不会被误认为历史为空。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)；引导与 GUI 顺序：[Workspace UI 产品流程 Agent Note](../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md)。
+
+源码：[`packages/workspace/workspace/src/types.ts`](../../packages/workspace/workspace/src/types.ts)
+
+## 标识
+
+```ts type-equiv
+/**
+ * Identifies one workspace record. A generated uuid, never the path: path
+ * normalization rewrites paths, and a reference anchor must stay stable.
+ */
+type WorkspaceId = Branded<'WorkspaceId'>
+```
+
+`WorkspaceId` 是[品牌化 id](core.md#branded-ids)。路径标识与之分离：`realpathNormalize`（`fs.realpath`；尾部斜杠、`..` 与符号链接全部解析）是唯一的一套唯一性规范——工作区路径以规范化形式存储，唯一性即规范路径的字符串相等（指向已被拥有目录的符号链接会与之冲突），attach 时的会话 cwd 检查也走同一套规范。
+
+## 工作区实体
+
+消费方只看到 `Workspace` 接口；实现保持包内私有。
+
+```ts type-equiv
+/**
+ * One workspace: a stable id over an existing directory, a display title, and
+ * an ordered candidate account of sessions. Membership requires both an id in
+ * that account and a session header whose canonical cwd equals the workspace
+ * path. Consumers only see this interface; the implementation stays private.
+ */
+interface Workspace {
+  /** Stable record id (generated uuid). */
+  readonly id: WorkspaceId
+
+  /**
+   * Canonical directory path: the `fs.realpath` of the path given at create
+   * time (trailing slashes, `..`, and symlinks all resolved). Never rewritten
+   * afterwards, even when the directory disappears (see {@link status}).
+   */
+  readonly path: string
+
+  /** Display title. Defaults to `basename(path)` at create; duplicates are allowed. */
+  readonly title: string
+
+  /** ISO-8601 creation instant, stamped at create and never rewritten. */
+  readonly createdAt: string
+
+  /** ISO-8601 instant of the last durable mutation (create counts as one). */
+  readonly updatedAt: string
+
+  /**
+   * Header-validated sessions in manually owned order: a new session is
+   * prepended at attach, explicit reordering goes through
+   * `insertSessionBefore`, and activity never reorders. The durable candidate
+   * account is filtered synchronously: missing headers, invalid cwd values,
+   * and canonical cwd mismatches are never returned. A subsequent workspace
+   * mutation prunes those filtered candidates durably.
+   */
+  readonly sessionIds: readonly SessionId[]
+
+  /**
+   * Replace the display title durably.
+   * @param title - New title; any string, duplicates across workspaces allowed.
+   * @returns resolution after durability.
+   */
+  setTitle(title: string): Promise<void>
+
+  /**
+   * Prepend a session to this workspace's candidate account. An already
+   * accounted id resolves without writing. A new id's live or persisted
+   * header cwd must resolve to an existing directory equal to {@link path};
+   * unknown ids, missing or invalid cwd values, and mismatches reject without
+   * writing.
+   * @param sessionId - The session to record.
+   * @returns resolution after durability.
+   */
+  attachSession(sessionId: SessionId): Promise<void>
+
+  /**
+   * Move an accounted session within the manual order, DOM-insertBefore-like:
+   * with an anchor the session lands before it, without one it appends to the
+   * end. Only the moved id changes position. A session or anchor absent from
+   * the account rejects without writing; a move to the current position
+   * resolves without writing (decided on the domain write chain).
+   * @param sessionId - The accounted session to move.
+   * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
+   * @returns resolution after durability.
+   */
+  insertSessionBefore(sessionId: SessionId, beforeSessionId?: SessionId): Promise<void>
+
+  /**
+   * Remove a session from this workspace's account. Idempotent: an id not on
+   * the account resolves without writing (decided on the domain write chain,
+   * like attach). Never touches the session's own stored log.
+   * @param sessionId - The session to remove.
+   * @returns resolution after durability.
+   */
+  detachSession(sessionId: SessionId): Promise<void>
+
+  /**
+   * Live directory check, uncached: whether {@link path} currently exists and
+   * is a directory. A missing directory never mutates the record — the
+   * directory may only be temporarily moved.
+   * @returns `'ok'` when the directory exists, `'missing-dir'` otherwise.
+   */
+  status(): Promise<'ok' | 'missing-dir'>
+}
+```
+
+所有权的真源是记录中有序的 `sessionIds`，绝不从会话 cwd 派生——但成员资格要求两者同时成立：账本上有其 id，且 header 的规范 cwd 等于工作区路径，因此一个会话在结构上至多属于一个工作区。失败的写入会拒绝（`insertSessionBefore` 的账本错误以 `WorkspaceMoveInvalidError` 拒绝，存储失败以普通错误拒绝）；每次被接受的变更都盖上 `updatedAt` 时间戳，并持久修剪不再通过成员资格检查的候选项。
+
+## 注册表：`ctx.workspace`
+
+`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样抛出 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好补完被标记的那次变更，而没有标记的顺序/表不一致则作为损坏大声失败。
+
+会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑，而没有 cwd 的历史遗留会话保持 Ungrouped。
+
+## 消费方
+
+[dsh-host-apiproxy](../../packages/host/apiproxy) 是产品消费方：它经 `ctx.workspace` 向 GUI 客户端提供工作区的 CRUD，并执行上文「先建会话再 attach」的流程。[dsh-workspace-context](../../packages/context/workspace-context) 尽管名字如此，却**不是**消费方：它在 agent 自己的 cwd 下发现 AGENTS.md 风格的指令文件，从不触碰 `ctx.workspace`——两者共用的这个词指的是用户的工作目录，而非本注册表的实体。
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index b710bebe76..b3fdfb7546 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -252,6 +252,7 @@ export const LINK_MAP: Record<string, string> = {
   Workspace: 'workspace.md',
   WorkspaceId: 'workspace.md',
   WebBootGraph: 'client-modules.md',
+  TelemetryRecord: 'telemetry.md',
 }
 
 /** TypeScript lib and pinned framework types that have no repository-owned data page. */
@@ -312,7 +313,6 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
   SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
   SubagentRunInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
-  TelemetryRecord: 'seam-local record contract is owned by packages/session/session-telemetry/src/index.ts',
   WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index b53ff60989..4650150a7d 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -199,7 +199,7 @@
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "GoalView",
-      "source": "packages/goal/goal/src/types.ts"
+      "source": "packages/goal/goal/src/domain.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
@@ -219,12 +219,12 @@
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "CreateGoalRequest",
-      "source": "packages/goal/goal/src/types.ts"
+      "source": "packages/goal/goal/src/domain.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "EditGoalRequest",
-      "source": "packages/goal/goal/src/types.ts"
+      "source": "packages/goal/goal/src/domain.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
@@ -1475,11 +1475,6 @@
       "symbol": "SettingsUpdateSource",
       "source": "packages/settings/settings/src/index.ts"
     },
-    {
-      "doc": "docs/subsystems/credentials.md",
-      "symbol": "CredentialRef",
-      "source": "packages/credentials/credentials/src/index.ts"
-    },
     {
       "doc": "docs/subsystems/credentials.md",
       "symbol": "ResolvedCredential",
@@ -1505,69 +1500,6 @@
       "symbol": "SettingsPathOp",
       "source": "packages/settings/settings/src/index.ts"
     },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTLookupMap",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTContextMap",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTLookupDefinition",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTCodec",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "InvocationParameterDescriptor",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "InvocationDescriptor",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTService",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTRemoteNamespaceMap",
-      "source": "packages/typert/type-meta/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "InvokeRemoteRequest",
-      "source": "packages/api/gateway/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypertGatewayErrorCode",
-      "source": "packages/api/gateway/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypertGateway",
-      "source": "packages/api/gateway/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/typert.md",
-      "symbol": "TypeRTClientRemote",
-      "source": "packages/typert/type-meta/src/types.ts"
-      "doc": "docs/subsystems/permission.md",
-      "symbol": "PresetSpec",
-      "source": "packages/interaction/permission/src/index.ts"
-    },
     {
       "doc": "docs/subsystems/permission.md",
       "symbol": "Config",
@@ -1687,6 +1619,81 @@
       "doc": "docs/subsystems/client-modules.md",
       "symbol": "WebBootGraph",
       "source": "packages/client/modules/src/client/manifest.ts"
+    },
+    {
+      "doc": "docs/subsystems/telemetry.md",
+      "symbol": "TelemetrySeverity",
+      "source": "packages/telemetry/session-telemetry/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/telemetry.md",
+      "symbol": "TelemetryRecord",
+      "source": "packages/telemetry/session-telemetry/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/telemetry.md",
+      "symbol": "TelemetryBackend",
+      "source": "packages/telemetry/session-telemetry/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTLookupMap",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTContextMap",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTLookupDefinition",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTCodec",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "InvocationParameterDescriptor",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "InvocationDescriptor",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTService",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTRemoteNamespaceMap",
+      "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "InvokeRemoteRequest",
+      "source": "packages/api/gateway/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypertGatewayErrorCode",
+      "source": "packages/api/gateway/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypertGateway",
+      "source": "packages/api/gateway/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "TypeRTClientRemote",
+      "source": "packages/typert/type-meta/src/types.ts"
     }
   ]
 }

From a8cf78630cbff2d1ea40128dfbfa1ace4e7b8b15 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 27 Jul 2026 23:52:35 +0800
Subject: [PATCH 411/516] docs: align zh subsystem pages with late en-side
 precision edits

The translators' clause-by-clause verification pass caught the English
pages' final wording refinements (tui built-in dialogs enumeration and
display()'s line-feed exception, invariants whitespace-padded/companion
phrasing, client-modules fiber-lifecycle parenthetical, storage strict
sequence, workspace first-successful-start) landing after the initial
zh versions; this aligns the eight pages and re-records their pairs.
---
 docs/subsystems/client-modules.i18n.yaml |  2 +-
 docs/subsystems/client-modules.zh.md     |  6 +++---
 docs/subsystems/core.i18n.yaml           |  2 +-
 docs/subsystems/core.zh.md               |  2 +-
 docs/subsystems/http-server.i18n.yaml    |  2 +-
 docs/subsystems/http-server.zh.md        |  6 +++---
 docs/subsystems/invariants.i18n.yaml     |  2 +-
 docs/subsystems/invariants.zh.md         | 10 +++++-----
 docs/subsystems/permission.i18n.yaml     |  2 +-
 docs/subsystems/permission.zh.md         |  6 +++---
 docs/subsystems/plan.i18n.yaml           |  2 +-
 docs/subsystems/plan.zh.md               |  4 ++--
 docs/subsystems/storage.i18n.yaml        |  2 +-
 docs/subsystems/storage.zh.md            |  4 ++--
 docs/subsystems/workspace.i18n.yaml      |  2 +-
 docs/subsystems/workspace.zh.md          |  6 +++---
 16 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index a9a68fd065..9c30e276d4 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/client-modules.md
 client-modules.md: bd5ecdc85ea26b040e1705e373ceac4e7cb17b3c
-client-modules.zh.md: bbcdb04cdce8a0d5256d2490deb238812e9a47fc
+client-modules.zh.md: e04bd8ac0c6a1566307559f02fc8075c907c0a7f
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index bbcdb04cdc..e04bd8ac0c 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -42,17 +42,17 @@ interface WebBootGraph {
 }
 ```
 
-每一行的 `rev` 是该 bundle 的内容哈希，并作为使缓存失效的查询参数附在 URL 上；图的 `rev` 对组合后的各行做哈希，因此任何一行的变化都会改变它。`immediately` 标记第一阶段预取档位（在模块面启动期间 fetch 并执行，只做工厂登记）；惰性行在首次 import 时才拉取。
+每一行的 `rev` 是该 bundle 的内容哈希，并作为使缓存失效的查询参数附在 URL 上；图的 `rev` 对组合后的各行做哈希，因此任何一行的变化都会改变它。`immediately` 标记第一阶段预取档位（在模块面启动期间 fetch 并执行，只做登记）；惰性行在首次 import 时才拉取。
 
 ## 扫描
 
 包加入这张表的方式，是在自己的 package.json 中声明 `dshClient`（`platform: 'web'`、可选的 `inject` 边、可选的 `immediately`），并在 `exports["./client"]` 导出构建好的 bundle。包解析锚定在配置树的 `ctx.baseUrl`——即 cordis.yml 所在目录，该目录的包把每个被组合的插件声明为依赖——这一锚点未设置时，构造即抛错。
 
-扫描是单包增量的；不存在全量重扫代码路径。每次 cordis `internal/plugin` 发射都把该 fiber 的 entry 名标脏，一次微任务 flush 把每个脏名与实时 loader entry 对账。激活趟以全部当前 entry 灌入同一个脏集合并同步 flush，因此初扫与稳态共享一条实现——但失败姿态相反。激活时，已加载 entry 中的畸形声明或缺失 bundle 会聚合为一个大声的 `AggregateError`，列出每个损坏的包：该 fiber 进入 FAILED，由启动的大声失败 sweep 上报。稳态下，损坏的包只记录一条警告，且不得殃及其他包。
+扫描是单包增量的；不存在全量重扫代码路径。fiber 构造或 dispose（资源释放）时的每次 cordis `internal/plugin` 发射都把该 fiber 的 entry 名标脏，一次微任务 flush 把每个脏名与实时 loader entry 对账。激活趟以全部当前 entry 灌入同一个脏集合并同步 flush，因此初扫与稳态共享一条实现——但失败姿态相反。激活时，已加载 entry 中的畸形声明或缺失 bundle 会聚合为一个大声的 `AggregateError`，列出每个损坏的包：该 fiber 进入 FAILED，由启动的大声失败 sweep 上报。稳态下，损坏的包只记录一条警告，且不得殃及其他包。
 
 包元数据——包括「非 client 包」这一否定结论——按名缓存且永不过期：插件集合的变更在重启后生效。fiber 重启原样复用其行与 rev；bundle 内容变更只经 `rebuilt()` 到达图。
 
-## 路由
+## bundle 路由与 index 转换
 
 `GET`/`HEAD /plugins/<id>/client.js` 以 `no-cache` 从磁盘提供已注册的 bundle（锚定一致性的是 rev 查询参数，而非 HTTP 缓存）；其他方法返回 405。未知 id——或已注册、但 bundle 因尚未构建而不可读的行——回应一个大声的 404，而不是让载体的 SPA 回退把 HTML 当作 JavaScript 发出。index 转换在每次 index 渲染时注入当前图，因此刷新页面总是针对实时组合启动。
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index d0188cb2f3..8bf98e026d 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/core.md
 core.md: 1d0bf6c61500817860dfdd452bddc25adbbeffcc
-core.zh.md: 06fd3b5a48d5267c9856c20589772047b6105b2c
+core.zh.md: 2b4766dcfcf1901de2bb8a8f9168888a67af7fba
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 06fd3b5a48..2b4766dcfc 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -48,7 +48,7 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
 | [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
 | [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
-| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空伴随插件契约 |
+| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
 | [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
 | [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index cb2c734255..8369b94dac 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/http-server.md
 http-server.md: 565df72f2720a1211f50650d4b1bc8d6df4a007a
-http-server.zh.md: 93b056648f044f6c79b85a6069deb3123f9a7a3e
+http-server.zh.md: 69e4a0bd7a1576737583625b23fac2ed05d8ca61
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index fc5e18414b..69e4a0bd7a 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -24,7 +24,7 @@ interface WebRoute {
 }
 ```
 
-匹配顺序固定：先查 exact 表，再取最长匹配前缀，最后落到静态 dist 回退。注册顺序不携带任何面向请求的语义：具名路由在组合上互不相交，启动窗口期内尚未被认领的请求全部由回退应答。回退保持锁定语义：非 GET/HEAD 返回 405，越出 dist 根目录的路径穿越返回 403，任何未命中都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 交付（[`static.ts`](../../packages/host/webserver/src/static.ts)）。
+匹配顺序固定：先查 exact 表，再取最长匹配前缀，最后落到静态 dist 回退。注册顺序不携带任何面向请求的语义：具名路由在组合上互不相交，启动窗口期内尚未被认领的请求全部由回退应答。回退遵循固定语义：非 GET/HEAD 返回 405，越出 dist 根目录的遍历返回 403，任何未命中都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供（[`static.ts`](../../packages/host/webserver/src/static.ts)）。
 
 ## 配置
 
@@ -44,6 +44,6 @@ interface Config {
 
 ## 服务
 
-`HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动阶段的大声失败巡检报告。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层面的契约，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
+`HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动的大声失败 sweep 上报。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层契约，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
 
-处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能保持响应打开（如 SSE（Server-Sent Events）），而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
+处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能像 SSE（Server-Sent Events）那样保持响应打开，而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包（package）从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
index dc5a8a6d0d..27b6ac8e87 100644
--- a/docs/subsystems/invariants.i18n.yaml
+++ b/docs/subsystems/invariants.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/invariants.md
 invariants.md: 143a7feabbab18556f595a78c7aef17caa6d3028
-invariants.zh.md: ab7aa0221101400d552ff47e1cfa3275d99a0b6d
+invariants.zh.md: fb497857c02202544edf44ccfe3a2935a988e30e
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
index ab7aa02211..fb497857c0 100644
--- a/docs/subsystems/invariants.zh.md
+++ b/docs/subsystems/invariants.zh.md
@@ -2,7 +2,7 @@
 
 [English](invariants.md) | 中文
 
-[dsh-invariants](../../packages/support/invariants) 是面向包（package）自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 伴随插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；seam 设计由[不变式服务 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md)规定。
+[dsh-invariants](../../packages/support/invariants) 是面向包（package）自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；seam 设计由[不变式服务 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md)规定。
 
 源码：[`packages/support/invariants/src/index.ts`](../../packages/support/invariants/src/index.ts)
 
@@ -20,7 +20,7 @@ interface Config {
 }
 ```
 
-一个包被选中的条件是：服务已启用，允许列表为空或至少一个模式匹配其完整 npm 名称，且没有任何阻止列表模式匹配；阻止列表匹配优先于允许列表匹配。条目用 `new RegExp(source)` 编译：除非模式自带 `^` 和 `$`，匹配不锚定；`/pattern/flags` 语法不被解析。校验在服务启动时大声失败：空白、带空白填充、重复或无效的条目会抛出异常，而不是被跳过。有效模式可以不匹配任何当前已加载的包，因此后续加载与 HMR（热模块替换）保持确定性；过滤器在服务生命周期内固定不变（[README](../../packages/support/invariants/README.md)）。
+一个包被选中的条件是：服务已启用，允许列表为空或至少一个模式匹配其完整 npm 名称，且没有任何阻止列表模式匹配；阻止列表匹配优先于允许列表匹配。条目用 `new RegExp(source)` 编译：除非模式自带 `^` 和 `$`，匹配不锚定；`/pattern/flags` 语法不被解析。校验在服务启动时大声失败：空白、首尾带空白、重复或无效的条目会抛出异常，而不是被跳过。有效模式可以不匹配任何当前已加载的包，因此后续加载与 HMR（热模块替换）保持确定性；过滤器在服务生命周期内固定不变（[README](../../packages/support/invariants/README.md)）。
 
 ## 安装器
 
@@ -52,8 +52,8 @@ interface InvariantInstaller {
 
 ## 服务
 
-`ctx.invariants.register(packageName, installer)` 为完整 npm 包名保留唯一一个活跃注册，并返回其绑定到 effect 的 disposer。即使过滤器使安装器保持不活跃，保留依然成立，因此两个插件绝不可能静默认领同一个包名；重复、空白或含空白字符的名称会抛出异常。安装器失败会原子地 dispose（资源释放）子 fiber 并释放保留。服务拥有每个注册 fiber，而返回的 disposer 同时属于伴随插件的 fiber：卸载任一侧都会移除监听器、trace 状态和保留项，因此伴随插件可以重载并再次注册同一名称，不留残余状态。
+`ctx.invariants.register(packageName, installer)` 为完整 npm 包名保留唯一一个活跃注册，并返回其绑定到 effect 的 disposer。即使过滤器使安装器保持不活跃，保留依然成立，因此两个插件绝不可能静默地认领同一个包名；重复、空白或含空白字符的名称会抛出异常。安装器失败会原子地 dispose（资源释放）子 fiber 并释放保留。服务拥有每个注册 fiber，而返回的 disposer 同时属于配套插件的 fiber：卸载任一侧都会移除监听器、trace 状态和保留项，因此配套插件可以重载并再次注册同一名称，不留残余状态。
 
-## 伴随插件契约
+## 配套插件契约
 
-每个工作区包都拥有一个 `./invariant` 伴随插件（[包契约](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但断言刻意不为凑数而虚构。只有当包对某个可观察事件或可变数据拥有所有权关系时，伴随插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行伴随插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
+每个工作区包都拥有一个 `./invariant` 配套插件（[包契约](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但刻意不合成断言。只有当包对某个可观察事件或可变数据拥有所有权关系时，配套插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行配套插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
index f800d4ff08..284f29bb62 100644
--- a/docs/subsystems/permission.i18n.yaml
+++ b/docs/subsystems/permission.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/permission.md
 permission.md: 49dd51ff86d0dbce26fca0ed21527f71bb144dec
-permission.zh.md: 5fb93e9f923582e6c530bac4a22e2ce62cff156d
+permission.zh.md: c2ab6ecdfb4b80511107bee41e080b06fae45f2c
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
index 5fb93e9f92..c2ab6ecdfb 100644
--- a/docs/subsystems/permission.zh.md
+++ b/docs/subsystems/permission.zh.md
@@ -2,13 +2,13 @@
 
 [English](permission.md) | 中文
 
-[dsh-permission](../../packages/ui/permission) 的权限预设层（`ctx.permission`，`PermissionService`）把两个相互独立的强制执行旋钮，即[沙箱模式](sandbox.md)（`sandbox/mode`）与[审批策略](approval.md)（`approval/policy`），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自旋钮的折叠结果，预设切换只记录意图，并通过每个旋钮各自的规范 setter 写入。[包（package）README](../../packages/ui/permission/README.md) 负责组合状态与限制；[沙箱切换设计](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责决策依据。
+[dsh-permission](../../packages/ui/permission) 的权限预设层（`ctx.permission`，`PermissionService`）把两个相互独立的强制执行旋钮（knob），即[沙箱模式](sandbox.md)（`sandbox/mode`）与[审批策略](approval.md)（`approval/policy`），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自旋钮的折叠结果，预设切换只记录意图，并通过每个旋钮各自的规范 setter 写入。[包（package）README](../../packages/ui/permission/README.md) 负责组合状态与限制；[沙箱切换设计](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责决策依据。
 
 源码：[`packages/ui/permission/src/index.ts`](../../packages/ui/permission/src/index.ts)
 
 ## 预设表
 
-预设是一个表键，映射到一组沙箱／审批组合，外加可选的客户端展示信息；默认预设表自带 `workspace-write`（`workspace-write` + `ask`）和 `danger-full-access`（`danger-full-access` + `never`）。
+预设是一个表键，映射到一个沙箱／审批组合，外加可选的客户端展示信息；默认预设表自带 `workspace-write`（`workspace-write` + `ask`）和 `danger-full-access`（`danger-full-access` + `never`）。
 
 ```ts type-equiv
 /** One preset's sandbox/approval bundle and optional client presentation. */
@@ -36,7 +36,7 @@ interface Config {
 }
 ```
 
-该服务要求一个施加沙箱隔离的 `ctx.bash` 执行器和 `ctx.approval`，配置错误在插件加载时即失败：名为 `custom` 的表项会抛出异常（该名称保留给派生的「非预设」状态）；在不施加隔离的 bash 执行器（没有 `sandboxMode` 能力事实）之上组合同样抛出异常，因为预设捆绑了一个沙箱模式。
+该服务要求一个施加隔离的 `ctx.bash` 执行器和 `ctx.approval`，配置错误在插件加载时即失败：名为 `custom` 的表项会抛出异常（该名称保留给派生的「非预设」状态）；在不施加隔离的 bash 执行器（没有 `sandboxMode` 能力事实）之上组合同样抛出异常，因为预设捆绑了一个沙箱模式。
 
 ## 当前预设与派生的 `custom`
 
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index 3ae156615f..c73912c178 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/plan.md
 plan.md: f67e7734ca3fd55c284d3d41227f8241de7b9f5f
-plan.zh.md: 565cf2016636acb6c26d20c731b9e6e374cee1da
+plan.zh.md: 27114c3c1c2acae3868b9c5bff37485b6da85377
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index af21a6d027..27114c3c1c 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -14,7 +14,7 @@
 
 由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到轮次边界。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
 
-服务会在三类边界处、于受影响的请求组装之前冲刷一条待定选择：提示词提交、普通轮次延续和请求恢复重试。冲刷在下游监听器链之后运行，因此在某个异步监听器等待期间到达的选择，仍会影响该边界紧接其后的那个请求。冲刷失败会被隔离（计划策略绝不能阻塞提示词或轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
+服务会在三类边界处、于受影响的请求组装之前冲刷一条待定选择：提示词提交、普通轮次延续和请求恢复重试。冲刷在下游监听器链之后运行，因此在某个异步监听器等待期间到达的选择，仍会影响紧随该边界的那个请求。冲刷失败会被收容（计划策略绝不能阻塞提示词或轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
 
 ## 配置
 
@@ -26,7 +26,7 @@ interface PlanModeConfig {
 }
 ```
 
-`section` 缺失、为空白或不是字符串，以及任何未知键，都会在插件加载时失败，而不是静默地什么都不影响。计划模式激活期间，确切的 `section` 文本以 order 50 渲染为 `plan:policy` [系统提示词段落](system-prompt.md)；未激活的计划模式不贡献任何文本。
+`section` 缺失、为空白或不是字符串，以及任何未知键，都会在插件加载时失败，而不是静默地不产生任何指引。计划模式激活期间，确切的 `section` 文本以 order 50 渲染为 `plan:policy` [系统提示词段落](system-prompt.md)；未激活的计划模式不贡献任何文本。
 
 ## 退出工具与 `/plan` 命令
 
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 92387332f0..6560eed831 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/storage.md
 storage.md: 5d54d7337b5ef52e24179758130b9fa8cd196376
-storage.zh.md: c575f989fe4b3536ce3c8d3b3af08ebda418166d
+storage.zh.md: 46346b64351322d40de166a71f7a3204c8902b2d
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index c575f989fe..46346b6435 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -64,7 +64,7 @@ interface DomainSpec {
 }
 ```
 
-`defineDomain(spec)` 固定 spec 的字面量类型，并在拥有方的模块加载时、任何介质被触碰之前就大声失败：领域名或表名不匹配 `UNIT_NAME_RE`、版本不是非负整数、global schema 接受 `null`，这些都会抛出（`null` 是介质的「从未写入」哨兵值，可空的 global 一旦存储就无法往返还原）。`domainTable<K, V>(schema)` 声明一张表，其键类型是编译期的幻影类型（通常是[品牌化 id](core.md#branded-ids)）；`descriptorOf(spec)` 投影出面向后端的 unit 描述符。
+`defineDomain(spec)` 固定 spec 的字面量类型，并在拥有方的模块加载时、任何介质被触碰之前就大声失败：领域名或表名不匹配 `UNIT_NAME_RE`、版本不是非负整数、global schema 接受 `null`，这些都会抛出（`null` 是介质的「从未写入」哨兵值，可空的 global 一旦存储就无法往返还原）。`domainTable<K, V>(schema)` 声明一张表，其键类型是仅存在于编译期的 phantom 类型（通常是[品牌化 id](core.md#branded-ids)）；`descriptorOf(spec)` 投影出面向后端的 unit 描述符。
 
 ## 打开的领域
 
@@ -99,7 +99,7 @@ interface Domain<S extends DomainSpec> {
 
 ## 领域 facility：`ctx.storageDomain`
 
-`DomainFacility`（[签名](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)）在经过路由的后端之上打开已声明的领域。路由是领域插件的配置，绝不属于枢纽：`backend` 指定必填的默认路由，`routes` 按领域名逐个覆盖。`open(spec)` 逐步执行，任一步失败都使整个调用失败：拒绝已打开或仍在关闭中的名称（`already-open`），解析路由（`backend-not-found`），要求后端具备 `kv` facet（`facet-unsupported`），打开 unit（后端的 `version-mismatch`/`malformed-medium` 原样透传），并按 spec 的 zod schema 校验每条已存储记录和 global（`invalid-record`，附带出错的表与键）。调用方拥有返回的句柄，并用 `Domain.close()` 释放它；插件卸载时仍处于打开状态的领域由 facility 负责关闭，已关闭领域的名称只有在拆除完全结束后才释放出来供重新打开。`get(name)` 是无类型的诊断查找；`closeAll()` 是卸载路径。
+`DomainFacility`（[签名](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)）在经过路由的后端之上打开已声明的领域。路由是领域插件的配置，绝不属于枢纽：`backend` 指定必填的默认路由，`routes` 按领域名逐个覆盖。`open(spec)` 按严格顺序执行，每一步失败都使整个调用失败：拒绝已打开或仍在关闭中的名称（`already-open`），解析路由（`backend-not-found`），要求后端具备 `kv` facet（`facet-unsupported`），打开 unit（后端的 `version-mismatch`/`malformed-medium` 原样透传），并按 spec 的 zod schema 校验每条已存储记录和 global（`invalid-record`，附带出错的表与键）。调用方拥有返回的句柄，并用 `Domain.close()` 释放它；插件卸载时仍处于打开状态的领域由 facility 负责关闭，已关闭领域的名称只有在拆除完全结束后才释放出来供重新打开。`get(name)` 是无类型的诊断查找，命中的是每个类型化句柄背后包内私有的 `DomainImpl` 运行时；`closeAll()` 是卸载路径。
 
 ## 变更事件：`domain/changed`
 
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index 5540d00aab..16ad3b95a3 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/workspace.md
 workspace.md: 2726115457905687e3c2cfc35a7a3f7251e6347c
-workspace.zh.md: 190c44b2d73f9e123242c34b5429839abe3b9297
+workspace.zh.md: 3a752617a58e4c9b62ec4084d2dc518015030952
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index 190c44b2d7..3a752617a5 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -2,7 +2,7 @@
 
 [English](workspace.md) | 中文
 
-工作区（workspace）是用户工作目录的持久记录：一个建立在规范路径之上的稳定 id、一个显示标题，以及归属于它的会话的有序账本。该子系统是单个包（package）（[dsh-workspace](../../packages/workspace/workspace)，`ctx.workspace`）——一项宿主侧可选能力，不属于 agent loop（智能体循环）主干，并且对模型不可见（没有工具、没有提示词文本、没有会话事件）。它通过[存储领域数据形式](storage.md)存储自己的记录，并对照 [`SessionHeader.cwd`](persistence.md#sessionheader--metadata-beside-the-log) 校验会话成员资格，因此 `storageDomain` 与 `sessionPersistence` 是必需的启动依赖：持久化这一侧不可用时插件保持 pending，而不会被误认为历史为空。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)；引导与 GUI 顺序：[Workspace UI 产品流程 Agent Note](../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md)。
+工作区（workspace）是用户工作目录的持久记录：一个建立在规范路径之上的稳定 id、一个显示标题，以及归属于它的会话的有序账本。该子系统是单个包（package）（[dsh-workspace](../../packages/workspace/workspace)，`ctx.workspace`）——一项宿主侧可选能力，不属于 agent loop（智能体循环）主干，并且对模型不可见（没有工具、没有提示词文本、没有会话事件）。它通过[存储领域数据形式](storage.md)存储自己的记录，并对照 [`SessionHeader.cwd`](persistence.md#sessionheader--metadata-beside-the-log) 校验会话成员资格，因此 `storageDomain` 与 `sessionPersistence` 是必需的启动依赖：持久化这一依赖不可用时，插件保持 pending，而不是把这种不可用误当作空历史。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)；引导与 GUI 顺序：[Workspace UI 产品流程 Agent Note](../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md)。
 
 源码：[`packages/workspace/workspace/src/types.ts`](../../packages/workspace/workspace/src/types.ts)
 
@@ -112,9 +112,9 @@ interface Workspace {
 
 ## 注册表：`ctx.workspace`
 
-`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样抛出 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好补完被标记的那次变更，而没有标记的顺序/表不一致则作为损坏大声失败。
+`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样传出原始 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好补完被标记的那次变更，而没有标记的顺序/表不一致则作为损坏大声失败。
 
-会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑，而没有 cwd 的历史遗留会话保持 Ungrouped。
+会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次成功启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑。引导只发生这一次：没有 cwd 的历史遗留会话保持 Ungrouped，此后创建的会话只能通过 `attachSession` 加入工作区。
 
 ## 消费方
 

From 061100f6f2cc1608a2c73811d74382f9d92b27d7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 00:20:38 +0800
Subject: [PATCH 412/516] docs: fix four factual errors found by Codex review
 round 1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- plan.md/.zh.md (+ plan-mode module JSDoc and README pair): the sole
  flush point is the prepended agent/step listener; prompt admission is
  pre-turn and never flushes — the pages had it backwards.
- workspace.md/.zh.md: pending-mutation recovery deletes the marked
  table row — completing an interrupted delete but rolling back an
  interrupted create; 'completes exactly the marked mutation' oversold.
- telemetry.md/.zh.md: delivery is best-effort with possible loss AND
  duplication, not at-most-once; TelemetryRecord.attributes JSDoc (source
  + both fences) now lists session.seed_length, which the coordinator
  emits for forked sessions.
- Agent Note consequence bullet: nine pages cover ten services (storage
  owns two keys); client-modules.zh.md wire-single-source phrasing.

Pairs re-recorded; plan-mode and telemetry suites green.
---
 .../2026-06-20-core-data-structures-catalog.i18n.yaml  |  4 ++--
 .../process/2026-06-20-core-data-structures-catalog.md |  2 +-
 .../2026-06-20-core-data-structures-catalog.zh.md      |  2 +-
 docs/subsystems/client-modules.i18n.yaml               |  2 +-
 docs/subsystems/client-modules.zh.md                   |  2 +-
 docs/subsystems/plan.i18n.yaml                         |  4 ++--
 docs/subsystems/plan.md                                |  2 +-
 docs/subsystems/plan.zh.md                             |  2 +-
 docs/subsystems/telemetry.i18n.yaml                    |  4 ++--
 docs/subsystems/telemetry.md                           | 10 +++++-----
 docs/subsystems/telemetry.zh.md                        | 10 +++++-----
 docs/subsystems/workspace.i18n.yaml                    |  4 ++--
 docs/subsystems/workspace.md                           |  2 +-
 docs/subsystems/workspace.zh.md                        |  2 +-
 packages/session/session-telemetry/src/index.ts        |  8 ++++----
 15 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 5bc51a4e7d..0883a5e9ab 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 718045bf7ce511a0b766e69e64ef7657eb221189
-2026-06-20-core-data-structures-catalog.zh.md: 1e8473a373c212fa08b171719edd5803e5aa3b05
+2026-06-20-core-data-structures-catalog.md: a8de47a462da13f316236fb7da3f4bfb57edae21
+2026-06-20-core-data-structures-catalog.zh.md: d84c2befaee4c2032b358ed1a7949ac0151ae74c
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 718045bf7c..a8de47a462 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -58,4 +58,4 @@ The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and de
 - The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
-- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: the nine `ctx` services without a page (permission presets, plan mode, runtime invariants, the HTTP carrier, storage, TUI extensions, workspaces, client modules, telemetry) gained lean pages, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
+- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: nine lean pages (permission presets, plan mode, runtime invariants, the HTTP carrier, storage — owning both `ctx.storage` and `ctx.storageDomain` — TUI extensions, workspaces, client modules, telemetry) cover the ten `ctx` services that had none, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 1e8473a373..d84c2befae 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -58,4 +58,4 @@ Status: implemented
 - 主干与 seam 分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
 - `ts type-equiv` 围栏是继 ` ```ts `（编译）和 ` ```ts ignore-check `（草稿）之后的第三种文档块类别。后续的姊妹门禁又增加了第四种 ` ```ts cordis-catalog `（生成签名），复用了相同的跳过并排除处理。
 - 添加或重塑核心类型现在附带一项文档义务，作者必须履行（门禁无法检测缺失的*新*类型），由 `dsh-code-review` 检查清单兜底。
-- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：原先没有页面的九个 `ctx` 服务（权限预设、计划模式、运行时不变式、HTTP 载体、存储、终端扩展、工作区、客户端模块、遥测）都获得了精简页面，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
+- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：九个精简页面（权限预设、计划模式、运行时不变式、HTTP 载体、存储——同时拥有 `ctx.storage` 与 `ctx.storageDomain`——终端扩展、工作区、客户端模块、遥测）覆盖了原先没有页面的十个 `ctx` 服务，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index 9c30e276d4..8988609cdf 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/client-modules.md
 client-modules.md: bd5ecdc85ea26b040e1705e373ceac4e7cb17b3c
-client-modules.zh.md: e04bd8ac0c6a1566307559f02fc8075c907c0a7f
+client-modules.zh.md: 5da7740e4c9272a3516f1a28712be7c95f29a6b3
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index e04bd8ac0c..5da7740e4c 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -8,7 +8,7 @@ Web 插件表：[dsh-client-modules](../../packages/client/modules) 中 client 
 
 ## wire
 
-图是 Node 半与浏览器半之间的线上单源：宿主从扫描到的包组合出 `WebBootEntry` 行，把图作为 `<head>` 中的第一个脚本注入（`window.__DSH_BOOT__`，其中 `<` 已转义，插件可控的字符串因此无法逃出 script 元素），壳则在启动任何东西之前先解析它。没有有效 manifest 的页面无法启动——浏览器侧的解析器在图缺失或畸形时大声抛错。
+图是 Node 半与浏览器半之间协议层的唯一事实来源：宿主从扫描到的包组合出 `WebBootEntry` 行，把图作为 `<head>` 中的第一个脚本注入（`window.__DSH_BOOT__`，其中 `<` 已转义，插件可控的字符串因此无法逃出 script 元素），壳则在启动任何东西之前先解析它。没有有效 manifest 的页面无法启动——浏览器侧的解析器在图缺失或畸形时大声抛错。
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index c73912c178..7c20a42864 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
-plan.md: f67e7734ca3fd55c284d3d41227f8241de7b9f5f
-plan.zh.md: 27114c3c1c2acae3868b9c5bff37485b6da85377
+plan.md: eb88047573536cd15be587b1419271bfbd93e9f1
+plan.zh.md: 5a838a045d63f2cabad80cad8af12df5da7e87f3
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index f67e7734ca..eb88047573 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -14,7 +14,7 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/s
 
 Because every session event is turn-enclosed, a user selection is held as pending intent until a turn boundary. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
 
-The service flushes one pending selection before the affected request assembly at three boundaries: prompt submission, ordinary turn continuation, and request-recovery retry. The flush runs after the downstream listener chain, so a selection arriving while an async listener awaits still shapes the request that boundary precedes. A flush failure is contained — plan policy can never block a prompt or turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
+The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception seam that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
 
 ## Configuration
 
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index 27114c3c1c..5a838a045d 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -14,7 +14,7 @@
 
 由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到轮次边界。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
 
-服务会在三类边界处、于受影响的请求组装之前冲刷一条待定选择：提示词提交、普通轮次延续和请求恢复重试。冲刷在下游监听器链之后运行，因此在某个异步监听器等待期间到达的选择，仍会影响紧随该边界的那个请求。冲刷失败会被收容（计划策略绝不能阻塞提示词或轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
+唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截 seam，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
 
 ## 配置
 
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index 9f6fdb3af3..d7544c7ddf 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: 4942a402dacb40ed64070c2b7824bfea7a14c872
-telemetry.zh.md: c99b287fd4cb4e9bc585ffe365ca08df37f6ccd1
+telemetry.md: cf6d3556a638375d939b29cc28941bf9c9ec7ea4
+telemetry.zh.md: 95eadb26581a6a96ce208d7c3b265d89455de4ba
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index 4942a402da..cf6d3556a6 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -38,10 +38,10 @@ interface TelemetryRecord {
   /**
    * Identity attributes, deliberately minimal: ledger records carry
    * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
-   * `session.parent_id` when the header has them; ops records carry
-   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
-   * `turn`, `step`, `error.name`. Anything recoverable from the body is
-   * intentionally NOT duplicated here.
+   * `session.parent_id` / `session.seed_length` when the header has them;
+   * ops records carry `telemetry.op`, `session.id`, and (for `agent-error`)
+   * `agent.id`, `turn`, `step`, `error.name`. Anything recoverable from the
+   * body is intentionally NOT duplicated here.
    */
   attributes: Record<string, string | number>
   /**
@@ -54,7 +54,7 @@ interface TelemetryRecord {
 }
 ```
 
-Only the first `assistant/chunk` of each `(turn, step)` ships — the stream-started signal; the rest drop at capture, so `seq` gaps are routine on the wire and never a loss signal. Every other [session event](session.md) type, including plugin-merged ones the seam never heard of, passes through whole. Delivery is at-most-once downstream of the handoff; receivers dedupe on `(session.id, event.seq)`.
+Only the first `assistant/chunk` of each `(turn, step)` ships — the stream-started signal; the rest drop at capture, so `seq` gaps are routine on the wire and never a loss signal. Every other [session event](session.md) type, including plugin-merged ones the seam never heard of, passes through whole. Delivery is best-effort: the cursor marks handed-off, not delivered, records can be lost (crash, reload window) and duplicated (cursor-less re-adoption, SDK retries), so receivers dedupe on `(session.id, event.seq)`.
 
 ## The backend contract
 
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index c99b287fd4..95eadb2658 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -38,10 +38,10 @@ interface TelemetryRecord {
   /**
    * Identity attributes, deliberately minimal: ledger records carry
    * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
-   * `session.parent_id` when the header has them; ops records carry
-   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
-   * `turn`, `step`, `error.name`. Anything recoverable from the body is
-   * intentionally NOT duplicated here.
+   * `session.parent_id` / `session.seed_length` when the header has them;
+   * ops records carry `telemetry.op`, `session.id`, and (for `agent-error`)
+   * `agent.id`, `turn`, `step`, `error.name`. Anything recoverable from the
+   * body is intentionally NOT duplicated here.
    */
   attributes: Record<string, string | number>
   /**
@@ -54,7 +54,7 @@ interface TelemetryRecord {
 }
 ```
 
-每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。交接下游的投递为至多一次（at-most-once）；接收端基于 `(session.id, event.seq)` 去重。
+每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。投递是尽力而为的：游标标记的是「已交接」而非「已送达」，记录可能丢失（崩溃、重载窗口）也可能重复（无游标的重新接管、SDK 重试），因此接收端基于 `(session.id, event.seq)` 去重。
 
 ## 后端契约
 
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index 16ad3b95a3..a50df35f91 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
-workspace.md: 2726115457905687e3c2cfc35a7a3f7251e6347c
-workspace.zh.md: 3a752617a58e4c9b62ec4084d2dc518015030952
+workspace.md: bade3526964055d5bf4448265c5898f1e66a1fce
+workspace.zh.md: b0437e42b644c1ce11d9a667972f7b236cf4caa1
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index 2726115457..bade352696 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -112,7 +112,7 @@ Ownership truth is the record's ordered `sessionIds`, never derived from session
 
 ## The registry: `ctx.workspace`
 
-`WorkspaceRegistry` ([signatures](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)) owns registration and resolution. `create(path, title?)` canonicalizes the path, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? basename(path)` prepended to the durable registry order — a new record cannot duplicate an existing display title (`WorkspaceNameConflictError`). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup completes exactly the marked mutation, and an unmarked order/table mismatch fails loud as corruption.
+`WorkspaceRegistry` ([signatures](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)) owns registration and resolution. `create(path, title?)` canonicalizes the path, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? basename(path)` prepended to the durable registry order — a new record cannot duplicate an existing display title (`WorkspaceNameConflictError`). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup resolves exactly the marked mutation — by deleting the marked table row, which completes an interrupted delete and rolls back an interrupted create (the registration is re-creatable, so rollback is the safe direction) — and an unmarked order/table mismatch fails loud as corruption.
 
 Sessions get their cwd at create time from whoever creates them, not from this registry — the API gateway resolves a new session's cwd from the chosen workspace's `path` (falling back to an explicit or default cwd), creates the session so the cwd lands in its immutable [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log), then calls `attachSession`, which re-validates that stored header cwd against the workspace path. On the first successful start, the registry bootstraps history from persisted headers alone (`id`, `cwd`, `createdAt` — never event bodies), grouping sessions with a valid canonical cwd into per-directory workspaces, newest first; the initialized marker is written last so an interrupted bootstrap resumes safely. The bootstrap is one-time: cwd-less legacy sessions stay Ungrouped, and sessions created afterwards join a workspace only through `attachSession`.
 
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index 3a752617a5..b0437e42b6 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -112,7 +112,7 @@ interface Workspace {
 
 ## 注册表：`ctx.workspace`
 
-`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样传出原始 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好补完被标记的那次变更，而没有标记的顺序/表不一致则作为损坏大声失败。
+`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样传出原始 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好解决被标记的那次变更——通过删除被标记的表行：这会补完被中断的 delete，并回滚被中断的 create（注册可以重建，因此回滚是安全方向）——而没有标记的顺序/表不一致则作为损坏大声失败。
 
 会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次成功启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑。引导只发生这一次：没有 cwd 的历史遗留会话保持 Ungrouped，此后创建的会话只能通过 `attachSession` 加入工作区。
 
diff --git a/packages/session/session-telemetry/src/index.ts b/packages/session/session-telemetry/src/index.ts
index 0198df3140..6a8e9ed2ad 100644
--- a/packages/session/session-telemetry/src/index.ts
+++ b/packages/session/session-telemetry/src/index.ts
@@ -71,10 +71,10 @@ export interface TelemetryRecord {
   /**
    * Identity attributes, deliberately minimal: ledger records carry
    * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
-   * `session.parent_id` when the header has them; ops records carry
-   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
-   * `turn`, `step`, `error.name`. Anything recoverable from the body is
-   * intentionally NOT duplicated here.
+   * `session.parent_id` / `session.seed_length` when the header has them;
+   * ops records carry `telemetry.op`, `session.id`, and (for `agent-error`)
+   * `agent.id`, `turn`, `step`, `error.name`. Anything recoverable from the
+   * body is intentionally NOT duplicated here.
    */
   attributes: Record<string, string | number>
   /**

From 0dd3ac14eb177fe1fb3802497846b847686c4249 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 00:36:30 +0800
Subject: [PATCH 413/516] docs: regenerate catalogs after the plan-mode JSDoc
 expansion shifted source lines

Codex round-2: the two-line module-JSDoc fix moved every later
declaration in packages/plan/plan-mode/src/index.ts, so the three
generated catalogs' source-line links went stale. Three one-line
regenerated updates; doc-sync back to 25/25.
---
 scripts/type-equiv.manifest.json | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 4650150a7d..e1f80b96b6 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1694,6 +1694,16 @@
       "doc": "docs/subsystems/typert.md",
       "symbol": "TypeRTClientRemote",
       "source": "packages/typert/type-meta/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/credentials.md",
+      "symbol": "CredentialRef",
+      "source": "packages/credentials/credentials/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/permission.md",
+      "symbol": "PresetSpec",
+      "source": "packages/interaction/permission/src/index.ts"
     }
   ]
 }

From bd62b6c0322c5eaa5ce10d54351f211352fb22f5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 11:20:22 +0800
Subject: [PATCH 414/516] docs: qualify the telemetry dedupe key as ledger-only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ds-review-bot: ops records deliberately omit event.seq, so the
(session.id, event.seq) dedupe advice cannot apply to them — they are
alert signals that tolerate duplicates. Both language sides; pair
re-recorded.
---
 docs/subsystems/telemetry.i18n.yaml | 4 ++--
 docs/subsystems/telemetry.md        | 2 +-
 docs/subsystems/telemetry.zh.md     | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index d7544c7ddf..e97a6f2e27 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: cf6d3556a638375d939b29cc28941bf9c9ec7ea4
-telemetry.zh.md: 95eadb26581a6a96ce208d7c3b265d89455de4ba
+telemetry.md: 92235a26fe278dfd6ac2b2ea5703b5c0d837b336
+telemetry.zh.md: e076abd90bd5054ddbfd6fbe7b725ee45d50a038
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index cf6d3556a6..92235a26fe 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -54,7 +54,7 @@ interface TelemetryRecord {
 }
 ```
 
-Only the first `assistant/chunk` of each `(turn, step)` ships — the stream-started signal; the rest drop at capture, so `seq` gaps are routine on the wire and never a loss signal. Every other [session event](session.md) type, including plugin-merged ones the seam never heard of, passes through whole. Delivery is best-effort: the cursor marks handed-off, not delivered, records can be lost (crash, reload window) and duplicated (cursor-less re-adoption, SDK retries), so receivers dedupe on `(session.id, event.seq)`.
+Only the first `assistant/chunk` of each `(turn, step)` ships — the stream-started signal; the rest drop at capture, so `seq` gaps are routine on the wire and never a loss signal. Every other [session event](session.md) type, including plugin-merged ones the seam never heard of, passes through whole. Delivery is best-effort: the cursor marks handed-off, not delivered, records can be lost (crash, reload window) and duplicated (cursor-less re-adoption, SDK retries), so receivers dedupe ledger records on `(session.id, event.seq)`; ops records deliberately omit that identity — they are signals to alert on, not entries to sum, and tolerate duplicates instead.
 
 ## The backend contract
 
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 95eadb2658..e076abd90b 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -54,7 +54,7 @@ interface TelemetryRecord {
 }
 ```
 
-每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。投递是尽力而为的：游标标记的是「已交接」而非「已送达」，记录可能丢失（崩溃、重载窗口）也可能重复（无游标的重新接管、SDK 重试），因此接收端基于 `(session.id, event.seq)` 去重。
+每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。投递是尽力而为的：游标标记的是「已交接」而非「已送达」，记录可能丢失（崩溃、重载窗口）也可能重复（无游标的重新接管、SDK 重试），因此接收端对 ledger 记录基于 `(session.id, event.seq)` 去重；ops 记录刻意省略这类标识——它们是用于告警的信号，而非用于累加的条目，重复被容忍而非被去重。
 
 ## 后端契约
 

From 3e1c7351bef4202a65c5f739254dce8a68212695 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 12:04:21 +0800
Subject: [PATCH 415/516] docs: state the plan-mode flush as a step boundary

ds-review-bot round 2: set() during an open multi-step turn applies at
the next request derivation in that same turn, so 'next turn boundary'
misstated the public timing contract (and propagated into the generated
catalogs). set()'s JSDoc, the module JSDoc, the pending-intent field
comment, and the subsystem page (both languages) now say step boundary;
catalogs regenerated; plan pair re-recorded.
---
 docs/subsystems/plan.i18n.yaml | 4 ++--
 docs/subsystems/plan.md        | 4 ++--
 docs/subsystems/plan.zh.md     | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index 7c20a42864..3295167755 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
-plan.md: eb88047573536cd15be587b1419271bfbd93e9f1
-plan.zh.md: 5a838a045d63f2cabad80cad8af12df5da7e87f3
+plan.md: c8bb6c9b6a0bcfd20ed6eadece4552d49f3c757c
+plan.zh.md: c8acedaef0724581227b57afbf81418a7e538aed
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index eb88047573..c8bb6c9b6a 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -10,9 +10,9 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/s
 
 `plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace [session event](session.md): durable and replayable, never in the model transcript. `foldPlanMode(events, end?)` returns the last logged value in the prefix, or `false` when there is none — the state in force is always a pure fold of the session log, so resume, fork, and compaction recover it with no live mirror, and UIs observe committed flips through `session/event`. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md).
 
-## Pending intent and the turn-boundary flush
+## Pending intent and the step-boundary flush
 
-Because every session event is turn-enclosed, a user selection is held as pending intent until a turn boundary. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
+Because every session event is turn-enclosed, a user selection is held as pending intent until the next step boundary — within the same turn when one is open. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
 
 The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception seam that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
 
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index 5a838a045d..c8acedaef0 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -10,9 +10,9 @@
 
 `plan/mode`（`{ active: boolean }`）是仅记日志、整值替换的[会话事件](session.md)：持久且可回放，绝不进入模型 transcript（文本记录）。`foldPlanMode(events, end?)` 返回前缀中最后一条已记录值，没有时返回 `false`：生效状态始终是会话日志的纯折叠，因此恢复、fork 与压缩（compaction）无需实时镜像即可将其复原，UI 通过 `session/event` 观察已提交的切换。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)。
 
-## 待定意图与轮次边界冲刷
+## 待定意图与步骤边界冲刷
 
-由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到轮次边界。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
+由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到下一个步骤边界——已有轮次开启时即在同一轮次之内。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
 
 唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截 seam，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
 

From 44b035c711482016e91438a163234ecdb8efbfe6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 28 Jul 2026 14:11:18 +0800
Subject: [PATCH 416/516] docs: qualify plan-mode timing and workspace no-write
 claims
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ds-review-bot round 3:
- set() after a turn's final step lands in a later turn (selection
  never forces continuation) — the same-turn phrasing overstated the
  guarantee; set() JSDoc + subsystem page (both languages).
- Workspace attach/insert/detach no-op claims now carry the
  filtered-candidate-prune caveat: mutate() durably prunes stale
  candidates even when the requested change is a no-op, a state the
  sessionIds contract explicitly permits; Workspace fence re-synced on
  both page sides; catalogs regenerated.
---
 docs/AGENTS.md                                |   4 +-
 docs/cordis-catalog/events.md                 |   5 +-
 docs/cordis-catalog/services.md               |  16 +-
 docs/subsystems/client-modules.i18n.yaml      |   4 +-
 docs/subsystems/client-modules.md             |   2 +-
 docs/subsystems/client-modules.zh.md          |   2 +-
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       |   1 -
 docs/subsystems/core.zh.md                    |   1 -
 docs/subsystems/http-server.i18n.yaml         |   4 +-
 docs/subsystems/http-server.md                |  10 +-
 docs/subsystems/http-server.zh.md             |   8 +-
 docs/subsystems/permission.i18n.yaml          |   4 +-
 docs/subsystems/permission.md                 |  15 +-
 docs/subsystems/permission.zh.md              |  15 +-
 docs/subsystems/plan.i18n.yaml                |   4 +-
 docs/subsystems/plan.md                       |   2 +-
 docs/subsystems/plan.zh.md                    |   2 +-
 docs/subsystems/telemetry.i18n.yaml           |   4 +-
 docs/subsystems/telemetry.md                  |  15 +-
 docs/subsystems/telemetry.zh.md               |  15 +-
 docs/subsystems/workspace.i18n.yaml           |   4 +-
 docs/subsystems/workspace.md                  |  13 +-
 docs/subsystems/workspace.zh.md               |  13 +-
 .../tests/cordis-catalog-contract.spec.ts     |   4 +-
 packages/workspace/workspace/README.i18n.yaml |   2 +-
 packages/workspace/workspace/README.zh.md     |   1 +
 packages/workspace/workspace/src/types.ts     |  13 +-
 scripts/gen-cordis-catalog.ts                 | 492 +++---------------
 scripts/type-equiv.manifest.json              |  39 +-
 30 files changed, 187 insertions(+), 531 deletions(-)

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 3bbd4f330d..488a7a1dd6 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -20,7 +20,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 |---|---|---|
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
-| [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ core-data-structures), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
+| [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
 | [subsystems/](subsystems/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) |
 | [Agent Notes](../.agents/notes/README.md) | Decision records under their own lifecycle contract | Migration plans, checklists, and spec-speak once implemented; archived notes are frozen history |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
@@ -37,7 +37,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The [core-data-structures catalog](subsystems/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
+- **The [subsystems catalog](subsystems/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
 - Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams".
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 6d060cf26b..fb05eaa8e6 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -824,6 +824,8 @@ Transform one outbound record before it reaches the backend. This waterfall is t
 'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
 ```
 
+Types: [TelemetryRecord](../subsystems/telemetry.md)
+
 Source: [`packages/session/session-telemetry/src/index.ts:43`](../../packages/session/session-telemetry/src/index.ts)
 
 ## `tools/*`
@@ -1090,8 +1092,7 @@ The framework events every plugin also sees, beyond the harness vocabulary above
 - `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:340`](../../vendor/cordis/src/events.ts))
 - `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:342`](../../vendor/cordis/src/events.ts))
 - `hmr/change` — A watched source file changed on disk. ([`vendor/hmr/src/index.ts:20`](../../vendor/hmr/src/index.ts))
-- `hmr/reload` — Plugins are being reloaded after a change. ([`vendor/hmr/src/index.ts:22`](../../vendor/hmr/src/index.ts))
-- `hmr/config-update-failed` — A watched config-file refresh failed. ([`vendor/hmr/src/index.ts:29`](../../vendor/hmr/src/index.ts))
+- `hmr/reload` — Plugins are being reloaded after a change. ([`vendor/hmr/src/index.ts:21`](../../vendor/hmr/src/index.ts))
 - `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:23`](../../vendor/loader/src/index.ts))
 - `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:24`](../../vendor/loader/src/index.ts))
 - `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index dbab056105..88f1762cff 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -377,6 +377,8 @@ onRebuilt(listener: (id: string, rev: string) => void): () => void
 onGraphChanged(listener: () => void): () => void
 ```
 
+Types: [WebBootGraph](../subsystems/client-modules.md)
+
 Source: [`packages/client/modules/src/index.ts:184`](../../packages/client/modules/src/index.ts)
 
 ## `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
@@ -866,6 +868,8 @@ tapIndex(transform: (html: string) => string): () => void
 applyIndexTaps(html: string): string
 ```
 
+Types: [WebRoute](../subsystems/http-server.md)
+
 Source: [`packages/host/webserver/src/index.ts:60`](../../packages/host/webserver/src/index.ts)
 
 ## `ctx.invariants` — `InvariantService`
@@ -884,6 +888,8 @@ Package-owned invariant registry with global and regex-based selection.
 register(packageName: string, installer: InvariantInstaller): () => void
 ```
 
+Types: [InvariantInstaller](../subsystems/invariants.md)
+
 Source: [`packages/support/invariants/src/index.ts:94`](../../packages/support/invariants/src/index.ts)
 
 ## `ctx.llm` — `LlmService`
@@ -1060,7 +1066,7 @@ optionOf(name: string): PresetOption
 set(session: Session, name: string): void
 ```
 
-Types: [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
+Types: [PresetOption](../subsystems/permission.md) · [PresetSpec](../subsystems/permission.md) · [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
 
 Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
 
@@ -2036,6 +2042,8 @@ mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => v
 form<K extends keyof StorageForms>(form: K): StorageForms[K]
 ```
 
+Types: [StorageForms](../subsystems/storage.md)
+
 Source: [`packages/storage/storage/src/index.ts:47`](../../packages/storage/storage/src/index.ts)
 
 ## `ctx.storageDomain` — `DomainFacility`
@@ -2079,6 +2087,8 @@ get(name: string): DomainImpl | undefined
 async closeAll(): Promise<void>
 ```
 
+Types: [Domain](../subsystems/storage.md) · [DomainSpec](../subsystems/storage.md)
+
 Source: [`packages/storage/storage-domain/src/index.ts:69`](../../packages/storage/storage-domain/src/index.ts)
 
 ## `ctx.subagents` — `SubagentService`
@@ -2473,6 +2483,8 @@ flush?(): void
 abstract shutdown(): Promise<void>
 ```
 
+Types: [TelemetryRecord](../subsystems/telemetry.md)
+
 Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/session/session-telemetry/src/index.ts)
 
 ## `ctx.tokenMeter` — `TokenMeterService`
@@ -2885,7 +2897,7 @@ archiveSession(sessionId: SessionId): Promise<void>
 async resolveByPath(path: string): Promise<Workspace | undefined>
 ```
 
-Types: [SessionId](../subsystems/core.md)
+Types: [SessionId](../subsystems/core.md) · [Workspace](../subsystems/workspace.md) · [WorkspaceId](../subsystems/workspace.md)
 
 Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts)
 
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index 8988609cdf..f0df40a866 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.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 docs/subsystems/client-modules.md
-client-modules.md: bd5ecdc85ea26b040e1705e373ceac4e7cb17b3c
-client-modules.zh.md: 5da7740e4c9272a3516f1a28712be7c95f29a6b3
+client-modules.md: 5dc89a87db7e79e4a297002fa059fdeffcceda20
+client-modules.zh.md: b3aa9c2aecf8e051a41b7b05f05d364b9ff8d2a6
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
index bd5ecdc85e..5dc89a87db 100644
--- a/docs/subsystems/client-modules.md
+++ b/docs/subsystems/client-modules.md
@@ -27,7 +27,7 @@ interface WebBootEntry {
   rev: string
   /** Package-name dependency edges, informational (preflight display / HMR diffing). */
   inject?: string[]
-  /** Stage-one prefetch mark: fetch + execute (factory registration) during module-face boot. */
+  /** Stage-one prefetch mark: load the script for factory registration during module-face boot. */
   immediately?: boolean
 }
 ```
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index 5da7740e4c..b3aa9c2aec 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -27,7 +27,7 @@ interface WebBootEntry {
   rev: string
   /** Package-name dependency edges, informational (preflight display / HMR diffing). */
   inject?: string[]
-  /** Stage-one prefetch mark: fetch + execute (factory registration) during module-face boot. */
+  /** Stage-one prefetch mark: load the script for factory registration during module-face boot. */
   immediately?: boolean
 }
 ```
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 8bf98e026d..a2af261bc6 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 1d0bf6c61500817860dfdd452bddc25adbbeffcc
-core.zh.md: 2b4766dcfcf1901de2bb8a8f9168888a67af7fba
+core.md: 3a8ccbef4163eabba1cd287284eda68135f2db13
+core.zh.md: 0cd6a57971ee98c75b52dd45b6f648632dab8a90
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 1d0bf6c615..3a8ccbef41 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -51,7 +51,6 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
 | [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the static dist fallback, index taps |
 | [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
-| [tui.md](tui.md) | the terminal-extension seam: `TuiOverlayRequest`/`Host`/`Session`, close reasons and outcomes, the modal queue |
 | [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
 | [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
 | [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 2b4766dcfc..0cd6a57971 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -51,7 +51,6 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
 | [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
-| [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index 8369b94dac..6f1facfad7 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.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 docs/subsystems/http-server.md
-http-server.md: 565df72f2720a1211f50650d4b1bc8d6df4a007a
-http-server.zh.md: 69e4a0bd7a1576737583625b23fac2ed05d8ca61
+http-server.md: 200d3eed683f203b65824ea3f62cf56ce3df912f
+http-server.zh.md: 9a12d3769a93270810927075be5f236875688b91
diff --git a/docs/subsystems/http-server.md b/docs/subsystems/http-server.md
index 565df72f27..200d3eed68 100644
--- a/docs/subsystems/http-server.md
+++ b/docs/subsystems/http-server.md
@@ -2,7 +2,7 @@
 
 English | [中文](http-server.zh.md)
 
-[dsh-host-webserver](../../packages/host/webserver) is the web-shape HTTP carrier for the GUI host: a single `node:http` plugin providing `ctx.httpServer`, a named-route registry plus index.html transform taps over a static dist fallback. It is not part of the agent-loop spine and not a capability seam — it knows no harness concepts, and every feature surface (the `/api` bridge, plugin bundles, the HMR event stream) is a route some other plugin registers ([layering note](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)). Web (browser) shape only: Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server.
+[dsh-host-webserver](../../packages/host/webserver) is the web-shape HTTP carrier for the GUI host: a single `node:http` plugin providing `ctx.httpServer`, a named-route registry, index.html transform taps, and a single claimable fallback seat. It is not part of the agent-loop spine and not a capability seam — it knows no harness concepts, and every feature surface (the `/api` bridge, plugin bundles, the HMR event stream) is a route some other plugin registers ([layering note](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)). Web (browser) shape only: Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server.
 
 Source: [`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
 
@@ -24,23 +24,21 @@ interface WebRoute {
 }
 ```
 
-Match order is fixed: exact table first, then longest matching prefix, then the static dist fallback. Registration order carries no request-facing semantics — named routes are composed to be disjoint, and the fallback answers anything not yet claimed during the boot window. The fallback keeps locked semantics: non-GET/HEAD is 405, traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), and unknown extensions ship as octet-stream ([`static.ts`](../../packages/host/webserver/src/static.ts)).
+Match order is fixed: exact table first, then longest matching prefix, then the registered fallback. Registration order carries no request-facing semantics — named routes are composed to be disjoint, and the fallback seat answers anything no named route claims; one owner only, a second registration throws. The shipped Web composition claims the seat with [`dsh-frontend-static`](../../packages/host/frontend-static/src/index.ts), the SPA dist server with locked semantics: non-GET/HEAD is 405, traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), and unknown extensions ship as octet-stream.
 
 ## Config
 
 ```ts type-equiv
-/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+/** Gateway config: the listen address. */
 interface Config {
   /** Listen host; the two supported values are loopback and all-interfaces. */
   host: '127.0.0.1' | '0.0.0.0'
   /** Listen port; zero requests an OS-assigned port. */
   port: number
-  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
-  distIndex: string
 }
 ```
 
-`host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); there is no TLS, auth, or origin policy, so a non-loopback bind exposes the server to that network. `distIndex` is an assembly fact the composing app resolves and injects.
+`host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); there is no TLS, auth, or origin policy, so a non-loopback bind exposes the server to that network. The dist location is an assembly fact of the frontend plugin that claims the seat.
 
 ## The service
 
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index 69e4a0bd7a..9a12d3769a 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -24,23 +24,21 @@ interface WebRoute {
 }
 ```
 
-匹配顺序固定：先查 exact 表，再取最长匹配前缀，最后落到静态 dist 回退。注册顺序不携带任何面向请求的语义：具名路由在组合上互不相交，启动窗口期内尚未被认领的请求全部由回退应答。回退遵循固定语义：非 GET/HEAD 返回 405，越出 dist 根目录的遍历返回 403，任何未命中都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供（[`static.ts`](../../packages/host/webserver/src/static.ts)）。
+匹配顺序固定：先查 exact 表，再取最长匹配前缀，最后落到已注册的回退。注册顺序不携带任何面向请求的语义：具名路由在组合上互不相交，任何未被具名路由认领的请求都由回退席位应答；席位只有一个所有者，第二次注册会抛出异常。发布的 Web 组合用 [`dsh-frontend-static`](../../packages/host/frontend-static/src/index.ts) 认领席位，即遵循固定语义的 SPA dist 服务器：非 GET/HEAD 返回 405，越出 dist 根目录的遍历返回 403，任何未命中都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 发送。
 
 ## 配置
 
 ```ts type-equiv
-/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+/** Gateway config: the listen address. */
 interface Config {
   /** Listen host; the two supported values are loopback and all-interfaces. */
   host: '127.0.0.1' | '0.0.0.0'
   /** Listen port; zero requests an OS-assigned port. */
   port: number
-  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
-  distIndex: string
 }
 ```
 
-`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（刻意的网络暴露）；没有 TLS、认证或 origin 策略，因此绑定到非回环地址会把服务器暴露给该网络。`distIndex` 是组合应用解析后注入的组装事实。
+`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（刻意的网络暴露）；没有 TLS、认证或 origin 策略，因此绑定到非回环地址会把服务器暴露给该网络。dist 位置是认领席位的前端插件的组装事实。
 
 ## 服务
 
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
index 284f29bb62..c63da5efdc 100644
--- a/docs/subsystems/permission.i18n.yaml
+++ b/docs/subsystems/permission.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 docs/subsystems/permission.md
-permission.md: 49dd51ff86d0dbce26fca0ed21527f71bb144dec
-permission.zh.md: c2ab6ecdfb4b80511107bee41e080b06fae45f2c
+permission.md: ec8cd4a923b617934f1612c31284103266aea4ef
+permission.zh.md: 4534c33e2715e4a500344f547c7895128877f4fb
diff --git a/docs/subsystems/permission.md b/docs/subsystems/permission.md
index 49dd51ff86..ec8cd4a923 100644
--- a/docs/subsystems/permission.md
+++ b/docs/subsystems/permission.md
@@ -2,9 +2,9 @@
 
 English | [中文](permission.zh.md)
 
-The permission-preset layer of [dsh-permission](../../packages/ui/permission) (`ctx.permission`, `PermissionService`) bundles the two independent enforcement knobs — [sandbox mode](sandbox.md) (`sandbox/mode`) and [approval policy](approval.md) (`approval/policy`) — into named presets a client offers as one Permissions selector. It is one optional capability, not part of the agent-loop spine, and it owns no enforcement: execution, prompt narration, and replay keep reading their knob folds, and a preset switch only records intent and writes through each knob's canonical setter. The [package README](../../packages/ui/permission/README.md) owns composition status and limitations; the [sandbox switching design](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns the rationale.
+The permission-preset layer of [dsh-permission](../../packages/interaction/permission) (`ctx.permission`, `PermissionService`) bundles the two independent enforcement knobs — [sandbox mode](sandbox.md) (`sandbox/mode`) and [approval policy](approval.md) (`approval/policy`) — into named presets a client offers as one Permissions selector. It is one optional capability, not part of the agent-loop spine, and it owns no enforcement: execution, prompt narration, and replay keep reading their knob folds, and a preset switch only records intent and writes through each knob's canonical setter. The [package README](../../packages/interaction/permission/README.md) owns composition status and limitations; the [sandbox switching design](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns the rationale.
 
-Source: [`packages/ui/permission/src/index.ts`](../../packages/ui/permission/src/index.ts)
+Source: [`packages/interaction/permission/src/index.ts`](../../packages/interaction/permission/src/index.ts)
 
 ## The preset table
 
@@ -25,7 +25,7 @@ interface PresetSpec {
 ```
 
 ```ts type-equiv
-/** The {@link PermissionService} config: the deployment's preset table. */
+/** The {@link PermissionService} config: preset table and composition default. */
 interface Config {
   /**
    * The preset table: name → knob bundle. Defaults to `workspace-write`
@@ -33,6 +33,11 @@ interface Config {
    * never). The name `custom` is reserved for the derived not-a-preset state.
    */
   presets?: Record<string, PresetSpec>
+  /**
+   * Default for new sessions. When omitted, the preset matching the composed
+   * sandbox and approval defaults is used.
+   */
+  defaultPreset?: string
 }
 ```
 
@@ -51,13 +56,13 @@ interface PresetOption {
   value: string
   /** The display label. */
   name: string
-  /** One user-facing sentence on what the value means. */
+  /** One user-facing sentence on what the value means; omitted when not configured. */
   description?: string
 }
 ```
 
 ## Switching and the `permission/preset` event
 
-`set(session, name)` resolves the preset (unknown names throw), appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter — `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/ui/user-approval) — only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing at all.
+`set(session, name)` resolves the preset (unknown names throw), appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter — `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/interaction/user-approval) — only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing at all.
 
 `permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve WHICH preset the user chose when two presets share a bundle; `effectivePermissionPreset(events)` folds the last one, and replay needs no catch-up state. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxpermission--permissionservice).
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
index c2ab6ecdfb..4534c33e27 100644
--- a/docs/subsystems/permission.zh.md
+++ b/docs/subsystems/permission.zh.md
@@ -2,9 +2,9 @@
 
 [English](permission.md) | 中文
 
-[dsh-permission](../../packages/ui/permission) 的权限预设层（`ctx.permission`，`PermissionService`）把两个相互独立的强制执行旋钮（knob），即[沙箱模式](sandbox.md)（`sandbox/mode`）与[审批策略](approval.md)（`approval/policy`），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自旋钮的折叠结果，预设切换只记录意图，并通过每个旋钮各自的规范 setter 写入。[包（package）README](../../packages/ui/permission/README.md) 负责组合状态与限制；[沙箱切换设计](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责决策依据。
+[dsh-permission](../../packages/interaction/permission) 的权限预设层（`ctx.permission`，`PermissionService`）把两个相互独立的强制执行旋钮（knob），即[沙箱模式](sandbox.md)（`sandbox/mode`）与[审批策略](approval.md)（`approval/policy`），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自旋钮的折叠结果，预设切换只记录意图，并通过每个旋钮各自的规范 setter 写入。[包（package）README](../../packages/interaction/permission/README.md) 负责组合状态与限制；[沙箱切换设计](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责决策依据。
 
-源码：[`packages/ui/permission/src/index.ts`](../../packages/ui/permission/src/index.ts)
+源码：[`packages/interaction/permission/src/index.ts`](../../packages/interaction/permission/src/index.ts)
 
 ## 预设表
 
@@ -25,7 +25,7 @@ interface PresetSpec {
 ```
 
 ```ts type-equiv
-/** The {@link PermissionService} config: the deployment's preset table. */
+/** The {@link PermissionService} config: preset table and composition default. */
 interface Config {
   /**
    * The preset table: name → knob bundle. Defaults to `workspace-write`
@@ -33,6 +33,11 @@ interface Config {
    * never). The name `custom` is reserved for the derived not-a-preset state.
    */
   presets?: Record<string, PresetSpec>
+  /**
+   * Default for new sessions. When omitted, the preset matching the composed
+   * sandbox and approval defaults is used.
+   */
+  defaultPreset?: string
 }
 ```
 
@@ -51,13 +56,13 @@ interface PresetOption {
   value: string
   /** The display label. */
   name: string
-  /** One user-facing sentence on what the value means. */
+  /** One user-facing sentence on what the value means; omitted when not configured. */
   description?: string
 }
 ```
 
 ## 切换与 `permission/preset` 事件
 
-`set(session, name)` 解析预设（未知名称抛出异常），在 `name` 尚不是生效预设时追加一条仅记日志的 `permission/preset` 事件，然后通过各旋钮自己的 setter（[dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) 的 `setSandboxMode` 与 [dsh-user-approval](../../packages/ui/user-approval) 的 `setApprovalPolicy`）写入，且仅当该旋钮的生效值发生变化时才写。同一轮次内，选择事件先于旋钮事件出现；重新选择当前生效的预设则什么都不追加。
+`set(session, name)` 解析预设（未知名称抛出异常），在 `name` 尚不是生效预设时追加一条仅记日志的 `permission/preset` 事件，然后通过各旋钮自己的 setter（[dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) 的 `setSandboxMode` 与 [dsh-user-approval](../../packages/interaction/user-approval) 的 `setApprovalPolicy`）写入，且仅当该旋钮的生效值发生变化时才写。同一轮次内，选择事件先于旋钮事件出现；重新选择当前生效的预设则什么都不追加。
 
 `permission/preset` 是持久、仅记日志的用户意图：它不进入模型 transcript（文本记录），模型可见的后果由旋钮事件经各自消费方承担；它存在是为了在两个预设共享同一个旋钮组合时，让 `current()` 仍能保住用户选择的究竟是哪一个预设；`effectivePermissionPreset(events)` 折叠最后一条，回放不需要任何追赶状态。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)；方法签名见生成的[服务目录](../cordis-catalog/services.md#ctxpermission--permissionservice)。
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index 3295167755..f82002420b 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
-plan.md: c8bb6c9b6a0bcfd20ed6eadece4552d49f3c757c
-plan.zh.md: c8acedaef0724581227b57afbf81418a7e538aed
+plan.md: 661a393b18f9154771c0b9358ad7f016a4fdec17
+plan.zh.md: 068b63fd9f3bf46b7962031bba154cc7fc7daafd
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index c8bb6c9b6a..661a393b18 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -12,7 +12,7 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/s
 
 ## Pending intent and the step-boundary flush
 
-Because every session event is turn-enclosed, a user selection is held as pending intent until the next step boundary — within the same turn when one is open. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
+Because every session event is turn-enclosed, a user selection is held as pending intent until the next step boundary — the next request derivation, in whichever turn it occurs (selection never forces continuation, so an intent recorded after a turn's final step lands in a later turn). `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
 
 The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception seam that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
 
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index c8acedaef0..068b63fd9f 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -12,7 +12,7 @@
 
 ## 待定意图与步骤边界冲刷
 
-由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到下一个步骤边界——已有轮次开启时即在同一轮次之内。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
+由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到下一个步骤边界——即下一次请求派生，落在哪个轮次就在哪个轮次生效（选择绝不强制续行，因此在某轮最后一步之后记录的意图会在之后的轮次落地）。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
 
 唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截 seam，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
 
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index e97a6f2e27..2eb634bb2d 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: 92235a26fe278dfd6ac2b2ea5703b5c0d837b336
-telemetry.zh.md: e076abd90bd5054ddbfd6fbe7b725ee45d50a038
+telemetry.md: cf570723650c32f048ee797923a58f09c777455d
+telemetry.zh.md: 1bcaa86264e3afd741d66d6ee718946e6151496f
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index 92235a26fe..cf57072365 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -2,9 +2,9 @@
 
 English | [中文](telemetry.zh.md)
 
-Outbound session reporting, split as a [capability seam](../capability-seams.md): the seam ([dsh-session-telemetry](../../packages/telemetry/session-telemetry), `ctx.telemetry`) owns the capture points, the fixed chunk projection, the `telemetry/record` redaction waterfall, the handoff cursor, and the minimal backend contract; the backend a deployment loads ([dsh-session-telemetry-otel](../../packages/telemetry/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [seam README](../../packages/telemetry/session-telemetry/README.md).
+Outbound session reporting, split as a [capability seam](../capability-seams.md): the seam ([dsh-session-telemetry](../../packages/session/session-telemetry), `ctx.telemetry`) owns the capture points, the fixed chunk projection, the `telemetry/record` redaction waterfall, the handoff cursor, and the minimal backend contract; the backend a deployment loads ([dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [seam README](../../packages/session/session-telemetry/README.md).
 
-Source: [`packages/telemetry/session-telemetry/src/index.ts`](../../packages/telemetry/session-telemetry/src/index.ts)
+Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
 
 ## The logical record
 
@@ -12,7 +12,7 @@ Source: [`packages/telemetry/session-telemetry/src/index.ts`](../../packages/tel
 /**
  * Severity of a telemetry record, pre-mapped at capture so a receiver can
  * alert with zero configuration: `error` for events whose own outcome flag
- * says so (`tool/result.isError`, `turn/end` error reasons) and for
+ * says so (the tool-result block's `isError`, `turn/end` error reasons) and for
  * `agent-error` operational records. Captured events otherwise default to
  * `info`; `warn` remains available to `telemetry/record` policies and
  * backends.
@@ -69,9 +69,10 @@ interface TelemetryBackend {
   /**
    * Hand one record to the backend's pipeline. MUST be a non-blocking
    * enqueue — the coordinator calls this synchronously from the
-   * `session/event` hot path, so anything slower than a queue push would tax
-   * the agent loop. Errors thrown here are contained by the coordinator and
-   * logged; they never reach the loop.
+   * `session/event` hot path or an explicit canonical-log capture, so anything
+   * slower than a queue push would tax the agent loop or feedback handling.
+   * Errors thrown here are contained by the coordinator and logged; they
+   * never reach the loop.
    * @param record - the logical record to report; owned by the backend after the call.
    */
   emit(record: TelemetryRecord): void
@@ -96,6 +97,8 @@ interface TelemetryBackend {
    * coordinator emits its dispose-time `shutdown` markers immediately before
    * calling this). Awaited by the coordinator's dispose; a rejection is
    * logged as a warning and never fails application teardown.
+   * The coordinator captures dispose-time shutdown markers immediately before
+   * this call for live capture; on-demand capture creates no ops records.
    * @returns resolves when the backend's pipeline has quiesced.
    */
   shutdown(): Promise<void>
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index e076abd90b..1bcaa86264 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -2,9 +2,9 @@
 
 [English](telemetry.md) | 中文
 
-对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/telemetry/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端契约；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/telemetry/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的契约见 [seam README](../../packages/telemetry/session-telemetry/README.md)。
+对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端契约；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的契约见 [seam README](../../packages/session/session-telemetry/README.md)。
 
-源码：[`packages/telemetry/session-telemetry/src/index.ts`](../../packages/telemetry/session-telemetry/src/index.ts)
+源码：[`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
 
 ## 逻辑记录
 
@@ -12,7 +12,7 @@
 /**
  * Severity of a telemetry record, pre-mapped at capture so a receiver can
  * alert with zero configuration: `error` for events whose own outcome flag
- * says so (`tool/result.isError`, `turn/end` error reasons) and for
+ * says so (the tool-result block's `isError`, `turn/end` error reasons) and for
  * `agent-error` operational records. Captured events otherwise default to
  * `info`; `warn` remains available to `telemetry/record` policies and
  * backends.
@@ -69,9 +69,10 @@ interface TelemetryBackend {
   /**
    * Hand one record to the backend's pipeline. MUST be a non-blocking
    * enqueue — the coordinator calls this synchronously from the
-   * `session/event` hot path, so anything slower than a queue push would tax
-   * the agent loop. Errors thrown here are contained by the coordinator and
-   * logged; they never reach the loop.
+   * `session/event` hot path or an explicit canonical-log capture, so anything
+   * slower than a queue push would tax the agent loop or feedback handling.
+   * Errors thrown here are contained by the coordinator and logged; they
+   * never reach the loop.
    * @param record - the logical record to report; owned by the backend after the call.
    */
   emit(record: TelemetryRecord): void
@@ -96,6 +97,8 @@ interface TelemetryBackend {
    * coordinator emits its dispose-time `shutdown` markers immediately before
    * calling this). Awaited by the coordinator's dispose; a rejection is
    * logged as a warning and never fails application teardown.
+   * The coordinator captures dispose-time shutdown markers immediately before
+   * this call for live capture; on-demand capture creates no ops records.
    * @returns resolves when the backend's pipeline has quiesced.
    */
   shutdown(): Promise<void>
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index a50df35f91..6a6488206c 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
-workspace.md: bade3526964055d5bf4448265c5898f1e66a1fce
-workspace.zh.md: b0437e42b644c1ce11d9a667972f7b236cf4caa1
+workspace.md: 5614631e828e51f3b515ae4af17451bd9eda1dbb
+workspace.zh.md: 11e8f0207a8db8b7612d6672cfe744523490aef7
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index bade352696..5614631e82 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -68,7 +68,9 @@ interface Workspace {
 
   /**
    * Prepend a session to this workspace's candidate account. An already
-   * accounted id resolves without writing. A new id's live or persisted
+   * accounted id resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs. A new id's
+   * live or persisted
    * header cwd must resolve to an existing directory equal to {@link path};
    * unknown ids, missing or invalid cwd values, and mismatches reject without
    * writing.
@@ -82,7 +84,9 @@ interface Workspace {
    * with an anchor the session lands before it, without one it appends to the
    * end. Only the moved id changes position. A session or anchor absent from
    * the account rejects without writing; a move to the current position
-   * resolves without writing (decided on the domain write chain).
+   * resolves without writing, aside from the durable filtered-candidate
+   * prune every accepted mutation performs; decided on the domain write
+   * chain.
    * @param sessionId - The accounted session to move.
    * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
    * @returns resolution after durability.
@@ -91,8 +95,9 @@ interface Workspace {
 
   /**
    * Remove a session from this workspace's account. Idempotent: an id not on
-   * the account resolves without writing (decided on the domain write chain,
-   * like attach). Never touches the session's own stored log.
+   * the account resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs; decided on
+   * the domain write chain like attach. Never touches the session's own stored log.
    * @param sessionId - The session to remove.
    * @returns resolution after durability.
    */
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index b0437e42b6..11e8f0207a 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -68,7 +68,9 @@ interface Workspace {
 
   /**
    * Prepend a session to this workspace's candidate account. An already
-   * accounted id resolves without writing. A new id's live or persisted
+   * accounted id resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs. A new id's
+   * live or persisted
    * header cwd must resolve to an existing directory equal to {@link path};
    * unknown ids, missing or invalid cwd values, and mismatches reject without
    * writing.
@@ -82,7 +84,9 @@ interface Workspace {
    * with an anchor the session lands before it, without one it appends to the
    * end. Only the moved id changes position. A session or anchor absent from
    * the account rejects without writing; a move to the current position
-   * resolves without writing (decided on the domain write chain).
+   * resolves without writing, aside from the durable filtered-candidate
+   * prune every accepted mutation performs; decided on the domain write
+   * chain.
    * @param sessionId - The accounted session to move.
    * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
    * @returns resolution after durability.
@@ -91,8 +95,9 @@ interface Workspace {
 
   /**
    * Remove a session from this workspace's account. Idempotent: an id not on
-   * the account resolves without writing (decided on the domain write chain,
-   * like attach). Never touches the session's own stored log.
+   * the account resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs; decided on
+   * the domain write chain like attach. Never touches the session's own stored log.
    * @param sessionId - The session to remove.
    * @returns resolution after durability.
    */
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index 30ef60e8fe..1b6589b6cf 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -152,11 +152,11 @@ describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => {
 
   it('accepts linked, foundation, generic-parameter, and explicitly exempt signature types', () => {
     const events = collectEvents(make(
-      '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param assembly - assembly result documented outside the subsystems catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, assembly: PromptAssembly, signal: AbortSignal): Promise<T>',
+      '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param preset - deployment metadata documented outside the subsystems catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, preset: PresetSpec, signal: AbortSignal): Promise<T>',
     ))
     expect(events).toHaveLength(1)
     expect(renderEvents(events)).toContain('Types: [SessionEvent](../subsystems/core.md)')
-    expect(renderEvents(events)).not.toContain('[PromptAssembly]')
+    expect(renderEvents(events)).not.toContain('[PresetSpec]')
   })
 
   it('aggregates every unclassified signature type with its source and remediation', () => {
diff --git a/packages/workspace/workspace/README.i18n.yaml b/packages/workspace/workspace/README.i18n.yaml
index 7ba60b4109..63d5ce0e8e 100644
--- a/packages/workspace/workspace/README.i18n.yaml
+++ b/packages/workspace/workspace/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workspace/workspace/README.md
 README.md: 057765e38de9cc700210eb8edeb1ddc7ffc861ff
-README.zh.md: f3be9611eba45db3719ce76ad6625f4787fab9ac
+README.zh.md: 7416875dbf2ee1652f6e1fa1663144d7407a1ae7
diff --git a/packages/workspace/workspace/README.zh.md b/packages/workspace/workspace/README.zh.md
index f3be9611eb..7416875dbf 100644
--- a/packages/workspace/workspace/README.zh.md
+++ b/packages/workspace/workspace/README.zh.md
@@ -12,6 +12,7 @@ DeepSeek Harness 的 Workspace 实体注册表（`ctx.workspace`）：通过领
 - `ctx.workspace.get(id)`/`list()`/`resolveByPath(path)`：由缓存提供的查找。`list()` 为同步操作，并遵循持久注册表顺序；`resolveByPath` 为异步操作，因为它采用相同的 `realpath` 规范化方式，并会拒绝缺失路径，而不是创建路径。
 - `ctx.workspace.delete(id)`：只移除 Workspace 注册记录、对应的持久顺序条目及会话归属记录。未知 id 返回 `false`，成功移除记录则返回 `true`。目录、用户文件、活跃会话和持久化会话日志绝不受影响，因此相关会话会进入 Ungrouped。表写入失败时会恢复原顺序和此前发布的实体。
 - `Workspace.attachSession(id)`：对照 workspace 路径验证实时或已持久化的会话头 cwd，并将新 id 前置。未知会话、缺失／无法解析／非目录的 cwd 值和不匹配情况都会在不写入的前提下被拒绝。`detachSession` 只移除候选索引条目。
+- `Workspace.insertSessionBefore(id, before?)`：在手动顺序内移动一个已记账的会话，语义类似 DOM 的 insertBefore：插到锚点之前，省略锚点则追加到末尾。会话或锚点不在记账中时拒绝且不写入；移动到当前位置时直接完成且不写入。Workspace 顺序绝不改变。
 - `ctx.workspace.archiveSession(id)`/`archivedSessionIds`：覆盖在 workspace 记账之上的注册表级全局归档集合：被归档的会话从各分组视图中消失，但其会话日志和 `sessionIds` 席位保持不变，未来取消归档时可恢复原位置。归档接受任何实时或已持久化的会话（无论已记账还是 Ungrouped），对已归档的 id 直接完成而不写入，并拒绝未知 id。在该字段出现之前写入的状态解析为一个空集合。
 - `Workspace.sessionIds`：按持久候选顺序提供同步 id 加规范 cwd 成员投影。缺失头部、无效 cwd 值和不匹配情况都被过滤；下一次 workspace 变更会剪除它们。如果同一存储介质将一个会话索引到两个 workspace 下、用两条记录声明同一路径，或偏离持久 workspace 顺序，启动会被拒绝。
 - `Workspace.status()`：未缓存的目录检查，返回 `'ok' | 'missing-dir'`；目录缺失绝不会改动记录。
diff --git a/packages/workspace/workspace/src/types.ts b/packages/workspace/workspace/src/types.ts
index 09d37213cc..555e94d45d 100644
--- a/packages/workspace/workspace/src/types.ts
+++ b/packages/workspace/workspace/src/types.ts
@@ -59,7 +59,9 @@ export interface Workspace {
 
   /**
    * Prepend a session to this workspace's candidate account. An already
-   * accounted id resolves without writing. A new id's live or persisted
+   * accounted id resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs. A new id's
+   * live or persisted
    * header cwd must resolve to an existing directory equal to {@link path};
    * unknown ids, missing or invalid cwd values, and mismatches reject without
    * writing.
@@ -73,7 +75,9 @@ export interface Workspace {
    * with an anchor the session lands before it, without one it appends to the
    * end. Only the moved id changes position. A session or anchor absent from
    * the account rejects without writing; a move to the current position
-   * resolves without writing (decided on the domain write chain).
+   * resolves without writing, aside from the durable filtered-candidate
+   * prune every accepted mutation performs; decided on the domain write
+   * chain.
    * @param sessionId - The accounted session to move.
    * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
    * @returns resolution after durability.
@@ -82,8 +86,9 @@ export interface Workspace {
 
   /**
    * Remove a session from this workspace's account. Idempotent: an id not on
-   * the account resolves without writing (decided on the domain write chain,
-   * like attach). Never touches the session's own stored log.
+   * the account resolves without writing, aside from the durable
+   * filtered-candidate prune every accepted mutation performs; decided on
+   * the domain write chain like attach. Never touches the session's own stored log.
    * @param sessionId - The session to remove.
    * @returns resolution after durability.
    */
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index b3fdfb7546..3cc277152e 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -1,32 +1,25 @@
 /**
- * Generate the Cordis event and service catalogs from static declarations.
- * The walk enforces event modes, JSDoc parameter/return completeness, and
- * signature type-link coverage; inherited Cordis services come from the
- * curated table below. `--check` verifies both committed artifacts.
+ * Generate committed Cordis artifacts from the Typert catalog projector and
+ * the independent vendored-core projector.
  */
 
-import { globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, resolve, sep } from 'node:path'
-import ts from 'typescript'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import {
+  projectCordisCatalog,
+  renderEvents,
+  renderServices,
+} from '@deepseek-ai/dsh-typert-generator'
+import type { CordisCatalogPolicy } from '@deepseek-ai/dsh-typert-generator'
 import { renderCordisCoreApiPages } from './cordis-core-api.ts'
-import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
-import { cordisModuleBody, eventMembers, serviceClasses } from './cordis-walk.ts'
 
 const root = resolve(import.meta.dirname, '..')
 const OUT_EVENTS = 'docs/cordis-catalog/events.md'
 const OUT_SERVICES = 'docs/cordis-catalog/services.md'
+const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts'
 
-/** The fenced-block info string for generated signature blocks (skipped by
- * doc-typecheck, since a bare signature fragment is not standalone-compilable). */
-const FENCE = 'ts cordis-catalog'
-
-/**
- * One primary subsystems page per project type used by a generated
- * signature. This stays curated because union names intentionally do not
- * reuse the type-equivalence manifest's map-symbol entries and some symbols
- * appear on more than one page.
- */
-export const LINK_MAP: Record<string, string> = {
+/** One primary subsystems page per project type used by a generated signature. */
+export const LINK_MAP: Readonly<Record<string, string>> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
   AgentOptions: 'core.md',
@@ -35,6 +28,7 @@ export const LINK_MAP: Record<string, string> = {
   ContinuationDecision: 'core.md',
   ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
+  InboxItem: 'core.md',
   InboxPlacement: 'core.md',
   MessageId: 'core.md',
   HookContext: 'core.md',
@@ -57,9 +51,7 @@ export const LINK_MAP: Record<string, string> = {
   UserMessage: 'session.md',
   PreStepDecision: 'core.md',
   PreStepContext: 'core.md',
-  PromptDecision: 'core.md',
   RequestErrorAction: 'core.md',
-  RequestError: 'core.md',
   RequestFailureContext: 'core.md',
   PreparedReferencedMessage: 'session-reference.md',
   SessionReferenceCandidate: 'session-reference.md',
@@ -116,6 +108,7 @@ export const LINK_MAP: Record<string, string> = {
   PreparedLlmCall: 'llm-streaming.md',
   LlmService: 'llm-streaming.md',
   StreamChunk: 'llm-streaming.md',
+  SkillProviderControl: 'skills.md',
   CreateSessionOptions: 'persistence.md',
   PrepareSessionOptions: 'persistence.md',
   SessionHeader: 'persistence.md',
@@ -168,9 +161,11 @@ export const LINK_MAP: Record<string, string> = {
   SessionTitleObservationResult: 'session-query.md',
   SessionTitleProvider: 'session-title.md',
   SessionTitleSnapshot: 'session-title.md',
+  SkillCatalogSnapshot: 'skills.md',
   SkillDefinition: 'skills.md',
   SkillLookupOptions: 'skills.md',
   SkillProvider: 'skills.md',
+  SkillProviderObservation: 'skills.md',
   SkillRegistration: 'skills.md',
   SkillSummary: 'skills.md',
   SaveTextSpill: 'spill.md',
@@ -237,8 +232,6 @@ export const LINK_MAP: Record<string, string> = {
   WebSearchRequest: 'web.md',
   WebSearchResult: 'web.md',
   WorkflowRun: 'workflow.md',
-  WorkflowRunInfo: 'workflow.md',
-  WorkflowStartRequest: 'workflow.md',
   PresetOption: 'permission.md',
   PresetSpec: 'permission.md',
   InvariantInstaller: 'invariants.md',
@@ -253,14 +246,17 @@ export const LINK_MAP: Record<string, string> = {
   WorkspaceId: 'workspace.md',
   WebBootGraph: 'client-modules.md',
   TelemetryRecord: 'telemetry.md',
+  WorkflowRunInfo: 'workflow.md',
+  WorkflowStartRequest: 'workflow.md',
 }
 
-/** TypeScript lib and pinned framework types that have no repository-owned data page. */
-const FOUNDATION_TYPE_NAMES = new Set([
+/** TypeScript lib and pinned framework types with no repository-owned data page. */
+export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
   'AbortSignal',
   'AsyncIterable',
   'Context',
   'Error',
+  'Map',
   'Partial',
   'Pick',
   'Promise',
@@ -269,7 +265,7 @@ const FOUNDATION_TYPE_NAMES = new Set([
 ])
 
 /** Project types deliberately documented outside the subsystems catalog. */
-const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
+export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
   z: 'schemastery schema constructor is owned by vendor/schemastery (vendored upstream)',
   BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
@@ -281,6 +277,7 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
   ManualCompactAgentContext: 'manual compaction service input is owned by packages/compact/compact/src/index.ts',
+  DirectoryPickerCapability: 'picker interaction contract is owned by packages/host/directory-picker/README.md',
   CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
   DomainImpl: 'domain implementation contract is owned by packages/storage/storage-domain/README.md',
   ProjectionDefinition: 'projection unit contract is owned by packages/session/session-projection/README.md',
@@ -318,401 +315,51 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
 }
 
-/** Collect named references from parameter, generic-constraint/default, and return types. */
-function signatureTypeNames(member: ts.MethodSignature | ts.MethodDeclaration, sf: ts.SourceFile): string[] {
-  const declared = new Set(member.typeParameters?.map(parameter => parameter.name.text) ?? [])
-  const referenced = new Set<string>()
-  const visit = (node: ts.Node): void => {
-    if (ts.isTypeReferenceNode(node)) referenced.add(node.typeName.getText(sf))
-    if (ts.isTypeQueryNode(node)) referenced.add(node.exprName.getText(sf))
-    ts.forEachChild(node, visit)
-  }
-  for (const parameter of member.typeParameters ?? []) {
-    if (parameter.constraint) visit(parameter.constraint)
-    if (parameter.default) visit(parameter.default)
-  }
-  for (const parameter of member.parameters) {
-    if (parameter.type) visit(parameter.type)
-  }
-  if (member.type) visit(member.type)
-  return [...referenced].filter(name => !declared.has(name)).sort()
+/** Repository data policy consumed by the Cordis catalog projector. */
+export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
+  linkedTypePages: LINK_MAP,
+  foundationTypeNames: FOUNDATION_TYPE_NAMES,
+  typeLinkExemptions: TYPE_LINK_EXEMPTIONS,
+  inheritedEvents: [
+    { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
+    { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
+    { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
+    { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
+    { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
+    { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
+    { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
+    { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
+    { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
+    { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
+    { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
+    { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
+    { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
+    { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
+    { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
+  ],
+  inheritedServices: [
+    { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
+    { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
+    { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
+    { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
+    { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
+    { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
+    { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
+    { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
+    { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
+    { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
+  ],
 }
 
-/** Append fail-closed signature type-link violations with actionable ownership choices. */
-function checkTypeLinks(
-  where: string,
-  member: ts.MethodSignature | ts.MethodDeclaration,
-  sf: ts.SourceFile,
-  violations: string[],
-): void {
-  for (const name of signatureTypeNames(member, sf)) {
-    if (Object.hasOwn(LINK_MAP, name)
-      || FOUNDATION_TYPE_NAMES.has(name)
-      || Object.hasOwn(TYPE_LINK_EXEMPTIONS, name)) continue
-    violations.push(
-      `${where} references unclassified type '${name}'. Add it to LINK_MAP with its subsystems page, `
-      + 'to FOUNDATION_TYPE_NAMES if TypeScript or Cordis owns it, or to TYPE_LINK_EXEMPTIONS with '
-      + 'the non-catalog documentation owner.',
-    )
-  }
-}
-
-/** Throw one aggregated diagnostic for every unclassified signature type. */
-function reportTypeLinkViolations(gate: string, violations: string[]): void {
-  if (violations.length === 0) return
-  throw new Error(
-    `${gate}: ${violations.length} signature type-link coverage violation(s):\n`
-    + violations.map(violation => `  ${violation}`).join('\n'),
-  )
-}
-
-/** One harness event, extracted from an `interface Events` block. */
-interface EventEntry {
-  /** Scoped name, e.g. `agent/request`. */
-  name: string
-  /** The scope prefix, e.g. `agent` (everything before the first `/`). */
-  scope: string
-  /** Full signature text (the method-signature member, JSDoc stripped). */
-  signature: string
-  /** Original declaration JSDoc, dedented from its containing interface. */
-  jsDoc: string
-  /** Dispatch mode from the `@mode` tag. */
-  mode: Mode
-  /** Description prose (JSDoc minus the `@mode` tag), one line per paragraph. */
-  doc: string
-  /** Source pointer `packages/…/file.ts:line` of the declaration. */
-  source: string
-}
-
-/** One public service method and the source contract attached to it. */
-interface ServiceMethodEntry {
-  /** Public method signature (body stripped). */
-  signature: string
-  /** Original method JSDoc, dedented from its containing class. */
-  jsDoc: string
-}
-
-/** One harness service, extracted from an `interface Context` block. */
-interface ServiceEntry {
-  /** The `ctx.<key>` name, e.g. `llm`. */
-  key: string
-  /** The service class/interface name, e.g. `LlmService`. */
-  type: string
-  /** Whether the service class is abstract (a seam interface). */
-  abstract: boolean
-  /** Class-level JSDoc prose, one line per paragraph. */
-  doc: string
-  /** Public methods (bodies stripped), in source order. */
-  methods: ServiceMethodEntry[]
-  /** Source pointer of the class declaration. */
-  source: string
-}
-
-/** A terse inherited-tier entry (pinned vendor surface). */
-interface InheritedEntry {
-  name: string
-  summary: string
-  /** Source pointer `vendor/…:line`. */
-  source: string
-}
-
-// cordisModuleBody / eventMembers / serviceClasses live in cordis-walk.ts.
-
-/** The signature text of a method-signature member (everything but a body). */
-function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.SourceFile): string {
-  const full = member.getText(sf)
-  const body = (member as { body?: ts.Node }).body
-  const sig = body ? full.slice(0, full.length - body.getText(sf).length) : full
-  return sig.replace(/\s*;?\s*$/, '').replace(/\s+/g, ' ').trim()
-}
-
-/**
- * Copy a node's original JSDoc while removing only the indentation imposed by
- * its containing interface or class.
+/** CLI entry: default writes every artifact; `--check` reports stale files.
+ * @returns nothing; writes files or reports freshness through the process.
  */
-function jsDocText(text: string, sf: ts.SourceFile, node: ts.Node): string {
-  const raw = rawJsDoc(text, node)
-  if (!raw) return ''
-  const start = text.lastIndexOf(raw, node.getStart(sf))
-  const { line } = sf.getLineAndCharacterOfPosition(start)
-  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
-  const indent = text.slice(lineStart, start)
-  return raw.split('\n')
-    .map((lineText, index) => index > 0 && lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText)
-    .join('\n')
-}
-
-/** Walk every harness `interface Events` block and extract its events, hard-
- * erroring (aggregated) on any JSDoc-completeness violation: a missing/
- * contradicted `@mode`, missing description prose, or an undocumented payload
- * parameter. `scanRoot` defaults to the repo root; tests pass a fixture dir. */
-export function collectEvents(scanRoot: string = root): EventEntry[] {
-  const entries: EventEntry[] = []
-  const violations: string[] = []
-  const typeLinkViolations: string[] = []
-  for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
-    const abs = resolve(scanRoot, rel)
-    const text = readFileSync(abs, 'utf8')
-    if (!text.includes('interface Events')) continue
-    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
-    const body = cordisModuleBody(sf)
-    if (!body) continue
-    for (const { name, member } of eventMembers(body, sf)) {
-      const signature = memberSignature(member, sf)
-      const raw = rawJsDoc(text, member)
-      const { doc, mode } = parseJsDoc(raw)
-      const src = pointer(rel, sf, member)
-      const where = `event '${name}' (${src})`
-      checkTypeLinks(where, member, sf, typeLinkViolations)
-      if (!mode) {
-        violations.push(`${where} is missing an @mode tag. Add '@mode emit|waterfall|parallel|serial|bail' to its JSDoc (see AGENTS.md).`)
-      }
-      // Conclusive structural check: a trailing `next: () => …` parameter is a
-      // waterfall. (emit vs parallel vs serial is not structurally
-      // distinguishable, so it is trusted from the tag.)
-      const last = member.parameters.at(-1)
-      const hasNext = !!last && last.name.getText(sf) === 'next'
-      if (mode && hasNext && mode !== 'waterfall') {
-        violations.push(`${where} has a trailing 'next' parameter (structurally a waterfall) but is tagged '@mode ${mode}'. Fix the tag or the signature.`)
-      }
-      if (mode && !hasNext && mode === 'waterfall') {
-        violations.push(`${where} is tagged '@mode waterfall' but has no trailing 'next' parameter. A waterfall delegates via next().`)
-      }
-      if (!doc) violations.push(`${where} has no description prose. Say what happened / what a listener may do, above the block tags.`)
-      // Payload parameters need a non-empty @param. The `this` receiver is not
-      // payload, and a waterfall's trailing `next` is covered by its mode.
-      const { params } = parseTags(raw)
-      checkParams(where, 'event', member.parameters, params, sf,
-        p => (ts.isIdentifier(p.name) && p.name.text === 'this') || (hasNext && p === last), violations)
-      if (mode) entries.push({ name, scope: name.split('/')[0] ?? name, signature, jsDoc: jsDocText(text, sf, member), mode, doc, source: src })
-    }
-  }
-  reportViolations('gen-cordis-catalog', violations)
-  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
-  return entries
-}
-
-/** Walk every harness `interface Context` block + its service class, hard-
- * erroring (aggregated) on any JSDoc-completeness violation: a class or public
- * method without JSDoc prose, an undocumented parameter, a stale `@param`, a
- * missing `@returns` on a non-void method, or an inferred (unannotated) return
- * type the pure-AST walk cannot classify.
- * `scanRoot` defaults to the repo root; tests pass a fixture dir. */
-export function collectServices(scanRoot: string = root): ServiceEntry[] {
-  const entries: ServiceEntry[] = []
-  const violations: string[] = []
-  const typeLinkViolations: string[] = []
-  for (const rel of globSync('packages/*/*/src/index.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
-    const abs = resolve(scanRoot, rel)
-    const text = readFileSync(abs, 'utf8')
-    if (!text.includes('interface Context')) continue
-    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
-    const body = cordisModuleBody(sf)
-    if (!body) continue
-    // Resolve each ctx key to its service class (shared walk) and emit an entry.
-    for (const { key, type, cls, abstract, doc: clsDoc } of serviceClasses(body, sf, rel, violations)) {
-      const methods: ServiceMethodEntry[] = []
-      for (const member of cls.members) {
-        if (!ts.isMethodDeclaration(member)) continue
-        // Only instance methods callable through `ctx.<key>` are surface;
-        // private, protected, and static methods are not.
-        const nonPublic = member.modifiers?.some(m =>
-          m.kind === ts.SyntaxKind.PrivateKeyword
-          || m.kind === ts.SyntaxKind.ProtectedKeyword
-          || m.kind === ts.SyntaxKind.StaticKeyword)
-          || ts.isPrivateIdentifier(member.name)
-        if (nonPublic) continue
-        const memberName = member.name.getText(sf)
-        if (memberName.startsWith('[')) continue // computed/symbol members
-        const where = `service method ctx.${key}.${memberName} (${pointer(rel, sf, member)})`
-        checkTypeLinks(where, member, sf, typeLinkViolations)
-        const raw = rawJsDoc(text, member)
-        methods.push({ signature: memberSignature(member, sf), jsDoc: jsDocText(text, sf, member) })
-        if (!raw) { violations.push(`${where} has no JSDoc.`); continue }
-        if (!parseJsDoc(raw).doc) violations.push(`${where} has no description prose above its block tags.`)
-        const { params, returns } = parseTags(raw)
-        // Every parameter needs a non-empty @param (`this` receiver exempt),
-        // and a non-void ANNOTATED result needs a non-empty @returns — the
-        // shared checkers carry the exact contract.
-        checkParams(where, 'service', member.parameters, params, sf,
-          p => ts.isIdentifier(p.name) && p.name.text === 'this', violations)
-        checkReturns(where, member.type, returns, sf, violations)
-      }
-      entries.push({
-        key,
-        type,
-        abstract,
-        doc: clsDoc,
-        methods,
-        source: pointer(rel, sf, cls),
-      })
-    }
-  }
-  reportViolations('gen-cordis-catalog', violations)
-  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
-  return entries.sort((a, b) => a.key.localeCompare(b.key))
-}
-
-/**
- * The inherited tier — cordis core + loader/hmr/timer. Curated, terse, and
- * hand-summarized because (a) it is pinned vendor source that changes only on a
- * deliberate vendor sync, (b) the cordis-core `Context` mixes true ctx members
- * with non-service fields (`root`, `baseUrl`, `logger`) that a blind walk would
- * wrongly surface as services, and (c) the internal/* events carry no JSDoc to
- * render. Source pointers are verified against vendor by `verify-md-links`'
- * sibling check is N/A; keep them current on a vendor bump.
- */
-const INHERITED_EVENTS: InheritedEntry[] = [
-  { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
-  { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
-  { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
-  { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
-  { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
-  { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
-  { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
-  { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
-  { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
-  { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
-  { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
-  { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
-  { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
-  { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
-  { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
-]
-
-export const INHERITED_SERVICES: InheritedEntry[] = [
-  { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
-  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
-  { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
-  { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
-  { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
-  { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
-  { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
-  { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
-  { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
-  { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
-]
-
-/** Render the cross-link "Types:" line for a signature, or '' if none apply. */
-function typeLinks(signature: string): string {
-  const seen = new Set<string>()
-  for (const name of Object.keys(LINK_MAP)) {
-    if (new RegExp(`\\b${name}\\b`).test(signature)) seen.add(name)
-  }
-  if (seen.size === 0) return ''
-  const links = [...seen].sort().map(n => `[${n}](../subsystems/${LINK_MAP[n]})`)
-  return `Types: ${links.join(' · ')}`
-}
-
-/** Render one harness event entry. */
-function renderEvent(e: EventEntry): string[] {
-  const out = [`### \`${e.name}\` — ${e.mode}`, '']
-  if (e.doc) out.push(e.doc, '')
-  out.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
-  const links = typeLinks(e.signature)
-  if (links) out.push(links, '')
-  out.push(`Source: [\`${e.source}\`](../../${e.source.split(':')[0]})`, '')
-  return out
-}
-
-/** Render one harness service entry. */
-function renderService(s: ServiceEntry): string[] {
-  const kind = s.abstract ? ' (abstract seam)' : ''
-  const out = [`## \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
-  if (s.doc) out.push(s.doc, '')
-  if (s.methods.length) {
-    const declarations = s.methods.flatMap((method, index) => [
-      ...(index > 0 ? [''] : []),
-      method.jsDoc,
-      method.signature,
-    ])
-    out.push('```' + FENCE, ...declarations, '```', '')
-    const links = typeLinks(s.methods.map(method => method.signature).join('\n'))
-    if (links) out.push(links, '')
-  }
-  out.push(`Source: [\`${s.source}\`](../../${s.source.split(':')[0]})`, '')
-  return out
-}
-
-/** The shared generated-file banner comment. */
-const BANNER = [
-  '<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.',
-  '     Run `pnpm run gen-cordis-catalog` to regenerate. -->',
-  '',
-]
-
-/** The shared GENERATED + freshness-gate + fence notice paragraph. */
-const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
-
-/** Render the events catalog (pure, deterministic given sorted inputs). */
-export function renderEvents(events: EventEntry[]): string {
-  const lines: string[] = [
-    ...BANNER,
-    '# Cordis Events Catalog',
-    '',
-    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.',
-    '',
-    GATE_NOTICE,
-    '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).',
-    '',
-    'Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`), **bail** (synchronous in-order dispatch until one listener returns a bail value; the scoped input-mutation events use it for an applied/not-applied answer).',
-    '',
-  ]
-  const scopes = [...new Set(events.map(e => e.scope))].sort()
-  for (const scope of scopes) {
-    lines.push(`## \`${scope}/*\``, '')
-    for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
-      lines.push(...renderEvent(e))
-    }
-  }
-  lines.push(
-    '## Inherited events (cordis core + loader/hmr/timer)',
-    '',
-    'The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier\'s prominence.',
-    '',
-  )
-  for (const e of INHERITED_EVENTS) {
-    lines.push(`- \`${e.name}\` — ${e.summary} ([\`${e.source}\`](../../${e.source.split(':')[0]}))`)
-  }
-  lines.push('')
-  return lines.join('\n')
-}
-
-/** Render the services catalog (pure, deterministic given sorted inputs). */
-export function renderServices(services: ServiceEntry[]): string {
-  const lines: string[] = [
-    ...BANNER,
-    '# Cordis Services Catalog',
-    '',
-    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
-    '',
-    GATE_NOTICE,
-    '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely. Detailed Context, Fiber, Registry, and Service APIs are generated in the [Cordis core API](core/context.md).',
-    '',
-  ]
-  for (const s of services) lines.push(...renderService(s))
-  lines.push(
-    '## Inherited `ctx` members (cordis core + loader/hmr/timer)',
-    '',
-    'The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier\'s prominence.',
-    '',
-  )
-  for (const s of INHERITED_SERVICES) {
-    lines.push(`- \`${s.name}\` — ${s.summary} ([\`${s.source}\`](../../${s.source.split(':')[0]}))`)
-  }
-  lines.push('')
-  return lines.join('\n')
-}
-
-/** CLI entry: `--write` (default) writes both catalogs, `--check` fails if
- * either is stale. Guarded behind an entry-point check so importing this module
- * for tests neither regenerates the committed files nor calls process.exit. */
-function main(): void {
+export function main(): void {
+  const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
   const outputs: [string, string][] = [
-    [OUT_EVENTS, renderEvents(collectEvents())],
-    [OUT_SERVICES, renderServices(collectServices())],
+    [OUT_EVENTS, renderEvents([...model.events], CORDIS_CATALOG_POLICY)],
+    [OUT_SERVICES, renderServices([...model.services], CORDIS_CATALOG_POLICY)],
+    [OUT_RUNTIME_API, projector.renderRuntimeApi(model)],
     ...renderCordisCoreApiPages(),
   ]
   if (process.argv.includes('--check')) {
@@ -722,9 +369,7 @@ function main(): void {
       try {
         committed = readFileSync(resolve(root, out), 'utf8')
       } catch {
-        // Only ENOENT (not yet generated) is expected; a present-but-unreadable
-        // file is not a state this repo produces. Either way the remedy is the
-        // same — regenerate — so treat a read failure as "stale".
+        // Only ENOENT is expected; either read failure has the same remedy.
         committed = null
       }
       if (committed !== content) stale.push(out)
@@ -745,7 +390,4 @@ function main(): void {
   console.log(`gen-cordis-catalog: wrote ${outputs.length} generated file(s).`)
 }
 
-// Run only when invoked as a script, not when imported by a test.
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
-  main()
-}
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) main()
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index e1f80b96b6..2bc097c88c 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -199,7 +199,7 @@
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "GoalView",
-      "source": "packages/goal/goal/src/domain.ts"
+      "source": "packages/goal/goal/src/types.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
@@ -219,12 +219,12 @@
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "CreateGoalRequest",
-      "source": "packages/goal/goal/src/domain.ts"
+      "source": "packages/goal/goal/src/types.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
       "symbol": "EditGoalRequest",
-      "source": "packages/goal/goal/src/domain.ts"
+      "source": "packages/goal/goal/src/types.ts"
     },
     {
       "doc": "docs/subsystems/goal.md",
@@ -1508,7 +1508,7 @@
     {
       "doc": "docs/subsystems/permission.md",
       "symbol": "PresetOption",
-      "source": "packages/interaction/permission/src/index.ts"
+      "source": "packages/interaction/permission/src/types.ts"
     },
     {
       "doc": "docs/subsystems/plan.md",
@@ -1575,31 +1575,6 @@
       "symbol": "DomainChanged",
       "source": "packages/storage/storage-domain/src/events.ts"
     },
-    {
-      "doc": "docs/subsystems/tui.md",
-      "symbol": "TuiOverlayRequest",
-      "source": "packages/interaction/tui/src/extension.ts"
-    },
-    {
-      "doc": "docs/subsystems/tui.md",
-      "symbol": "TuiOverlayHost",
-      "source": "packages/interaction/tui/src/extension.ts"
-    },
-    {
-      "doc": "docs/subsystems/tui.md",
-      "symbol": "TuiOverlaySession",
-      "source": "packages/interaction/tui/src/extension.ts"
-    },
-    {
-      "doc": "docs/subsystems/tui.md",
-      "symbol": "TuiOverlayCloseReason",
-      "source": "packages/interaction/tui/src/extension.ts"
-    },
-    {
-      "doc": "docs/subsystems/tui.md",
-      "symbol": "TuiOverlayOutcome",
-      "source": "packages/interaction/tui/src/extension.ts"
-    },
     {
       "doc": "docs/subsystems/workspace.md",
       "symbol": "WorkspaceId",
@@ -1623,17 +1598,17 @@
     {
       "doc": "docs/subsystems/telemetry.md",
       "symbol": "TelemetrySeverity",
-      "source": "packages/telemetry/session-telemetry/src/index.ts"
+      "source": "packages/session/session-telemetry/src/index.ts"
     },
     {
       "doc": "docs/subsystems/telemetry.md",
       "symbol": "TelemetryRecord",
-      "source": "packages/telemetry/session-telemetry/src/index.ts"
+      "source": "packages/session/session-telemetry/src/index.ts"
     },
     {
       "doc": "docs/subsystems/telemetry.md",
       "symbol": "TelemetryBackend",
-      "source": "packages/telemetry/session-telemetry/src/index.ts"
+      "source": "packages/session/session-telemetry/src/index.ts"
     },
     {
       "doc": "docs/subsystems/typert.md",

From f7323354bb9be166620fb47d106afb8abc53c315 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 30 Jul 2026 21:40:58 +0800
Subject: [PATCH 417/516] docs: generate each subsystem's cordis surface into
 its own page; delete the flat catalogs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rebuild of the region machinery (PR3) on the post-#904 Typert projection:
renderPageRegion/renderInheritedPage live in dsh-typert-generator beside the
projection; scripts/gen-cordis-catalog.ts owns the curated SERVICE_PAGE /
EVENT_SCOPE_PAGE / SERVICE_WALK_EXEMPTIONS / LINK_MAP partition (fail-loud in
both directions, with the independent Context-merge scan backstopping the
projection's blind spot), spliceRegion, and the guarded pair auto-record.
docs/cordis-catalog/ is deleted: the flat events/services catalogs dissolve
into per-page regions and docs/cordis-catalog/core moves to docs/cordis-api/
with the inherited tier as its own generated page. The partition absorbs the
post-regrouping surface: ctx.typert → invariants.md, ctx.directoryPicker →
workspace.md, skills/* events → skills.md, and the four launcher-provided tui
accessor values join the named exemptions.
---
 ...bagent-provider-lifecycle-events.i18n.yaml |    4 +-
 ...7-05-subagent-provider-lifecycle-events.md |    2 +-
 ...5-subagent-provider-lifecycle-events.zh.md |    2 +-
 .../2026-07-08-agent-scope-contexts.i18n.yaml |    4 +-
 .../2026-07-08-agent-scope-contexts.md        |    2 +-
 .../2026-07-08-agent-scope-contexts.zh.md     |    2 +-
 .../feature/2026-07-05-skill-system.i18n.yaml |    4 +-
 .../feature/2026-07-05-skill-system.md        |    2 +-
 .../feature/2026-07-05-skill-system.zh.md     |    2 +-
 ...subsystem-cordis-surface-regions.i18n.yaml |    6 +
 ...28-per-subsystem-cordis-surface-regions.md |   36 +
 ...per-subsystem-cordis-surface-regions.zh.md |   36 +
 docs/AGENTS.md                                |    2 +-
 docs/architecture.i18n.yaml                   |    4 +-
 docs/architecture.md                          |    2 +-
 docs/architecture.zh.md                       |    2 +-
 docs/config-catalog.md                        |    2 +-
 .../core => cordis-api}/context.md            |   40 +-
 .../core => cordis-api}/events.md             |   20 +-
 .../core => cordis-api}/fiber.md              |   44 +-
 docs/cordis-api/inherited.md                  |   39 +
 .../core => cordis-api}/registry.md           |    8 +-
 .../core => cordis-api}/service.md            |   18 +-
 docs/cordis-catalog/events.md                 | 1100 -------
 docs/cordis-catalog/services.md               | 2917 -----------------
 docs/cordis-primer.i18n.yaml                  |    4 +-
 docs/cordis-primer.md                         |    2 +-
 docs/cordis-primer.zh.md                      |    2 +-
 docs/cordis-tutorial/03-services.i18n.yaml    |    4 +-
 docs/cordis-tutorial/03-services.md           |    2 +-
 docs/cordis-tutorial/03-services.zh.md        |    2 +-
 docs/cordis-tutorial/04-events.i18n.yaml      |    4 +-
 docs/cordis-tutorial/04-events.md             |    4 +-
 docs/cordis-tutorial/04-events.zh.md          |    4 +-
 .../07-into-the-harness.i18n.yaml             |    4 +-
 docs/cordis-tutorial/07-into-the-harness.md   |    2 +-
 .../cordis-tutorial/07-into-the-harness.zh.md |    2 +-
 docs/cordis-tutorial/index.i18n.yaml          |    4 +-
 docs/cordis-tutorial/index.md                 |    2 +-
 docs/cordis-tutorial/index.zh.md              |    2 +-
 docs/graph-atlas.md                           |    2 +-
 docs/i18n/style-samples.md                    |    4 +-
 docs/persistence-catalog.md                   |    2 +-
 docs/subsystems/approval.i18n.yaml            |    4 +-
 docs/subsystems/approval.md                   |   82 +
 docs/subsystems/approval.zh.md                |   82 +
 docs/subsystems/bash.i18n.yaml                |    6 +-
 docs/subsystems/bash.md                       |   82 +
 docs/subsystems/bash.zh.md                    |   82 +
 docs/subsystems/client-modules.i18n.yaml      |    4 +-
 docs/subsystems/client-modules.md             |   57 +-
 docs/subsystems/client-modules.zh.md          |   57 +-
 docs/subsystems/code-runtime.i18n.yaml        |    6 +-
 docs/subsystems/code-runtime.md               |   30 +
 docs/subsystems/code-runtime.zh.md            |   30 +
 docs/subsystems/commands.i18n.yaml            |    4 +-
 docs/subsystems/commands.md                   |   86 +
 docs/subsystems/commands.zh.md                |   86 +
 docs/subsystems/compaction.i18n.yaml          |    4 +-
 docs/subsystems/compaction.md                 |  116 +
 docs/subsystems/compaction.zh.md              |  116 +
 docs/subsystems/core.i18n.yaml                |    4 +-
 docs/subsystems/core.md                       |  546 ++-
 docs/subsystems/core.zh.md                    |  546 ++-
 docs/subsystems/credentials.i18n.yaml         |    4 +-
 docs/subsystems/credentials.md                |   83 +
 docs/subsystems/credentials.zh.md             |   83 +
 docs/subsystems/filesystem.i18n.yaml          |    6 +-
 docs/subsystems/filesystem.md                 |  208 +-
 docs/subsystems/filesystem.zh.md              |  208 +-
 docs/subsystems/goal.i18n.yaml                |    6 +-
 docs/subsystems/goal.md                       |  132 +
 docs/subsystems/goal.zh.md                    |  132 +
 docs/subsystems/http-server.i18n.yaml         |    4 +-
 docs/subsystems/http-server.md                |   61 +
 docs/subsystems/http-server.zh.md             |   61 +
 docs/subsystems/invariants.i18n.yaml          |    4 +-
 docs/subsystems/invariants.md                 |   29 +
 docs/subsystems/invariants.zh.md              |   29 +
 docs/subsystems/llm-streaming.i18n.yaml       |    4 +-
 docs/subsystems/llm-streaming.md              |  188 ++
 docs/subsystems/llm-streaming.zh.md           |  188 ++
 docs/subsystems/permission.i18n.yaml          |    4 +-
 docs/subsystems/permission.md                 |   65 +-
 docs/subsystems/permission.zh.md              |   65 +-
 docs/subsystems/persistence.i18n.yaml         |    4 +-
 docs/subsystems/persistence.md                |  132 +
 docs/subsystems/persistence.zh.md             |  132 +
 docs/subsystems/plan.i18n.yaml                |    4 +-
 docs/subsystems/plan.md                       |   49 +-
 docs/subsystems/plan.zh.md                    |   49 +-
 docs/subsystems/pty.i18n.yaml                 |    6 +-
 docs/subsystems/pty.md                        |   93 +
 docs/subsystems/pty.zh.md                     |   93 +
 docs/subsystems/sandbox.i18n.yaml             |    6 +-
 docs/subsystems/sandbox.md                    |   62 +
 docs/subsystems/sandbox.zh.md                 |   62 +
 docs/subsystems/session-projection.i18n.yaml  |    6 +
 docs/subsystems/session-projection.md         |  262 ++
 docs/subsystems/session-projection.zh.md      |  262 ++
 docs/subsystems/session-query.i18n.yaml       |    6 +-
 docs/subsystems/session-query.md              |  138 +
 docs/subsystems/session-query.zh.md           |  138 +
 docs/subsystems/session-reference.i18n.yaml   |    4 +-
 docs/subsystems/session-reference.md          |   41 +
 docs/subsystems/session-reference.zh.md       |   41 +
 docs/subsystems/session-title.i18n.yaml       |    4 +-
 docs/subsystems/session-title.md              |   58 +
 docs/subsystems/session-title.zh.md           |   58 +
 docs/subsystems/session.i18n.yaml             |    4 +-
 docs/subsystems/session.md                    |  246 +-
 docs/subsystems/session.zh.md                 |  246 +-
 docs/subsystems/settings.i18n.yaml            |    4 +-
 docs/subsystems/settings.md                   |  148 +
 docs/subsystems/settings.zh.md                |  148 +
 docs/subsystems/skills.i18n.yaml              |    4 +-
 docs/subsystems/skills.md                     |   90 +
 docs/subsystems/skills.zh.md                  |   90 +
 docs/subsystems/spill.i18n.yaml               |    6 +-
 docs/subsystems/spill.md                      |   32 +
 docs/subsystems/spill.zh.md                   |   32 +
 docs/subsystems/storage.i18n.yaml             |    4 +-
 docs/subsystems/storage.md                    |  110 +-
 docs/subsystems/storage.zh.md                 |  110 +-
 docs/subsystems/subagent.i18n.yaml            |    6 +-
 docs/subsystems/subagent.md                   |  266 ++
 docs/subsystems/subagent.zh.md                |  266 ++
 docs/subsystems/subprocess.i18n.yaml          |    6 +-
 docs/subsystems/subprocess.md                 |   77 +-
 docs/subsystems/subprocess.zh.md              |   77 +-
 docs/subsystems/system-prompt.i18n.yaml       |    4 +-
 docs/subsystems/system-prompt.md              |  110 +
 docs/subsystems/system-prompt.zh.md           |  110 +
 docs/subsystems/tasks.i18n.yaml               |    6 +-
 docs/subsystems/tasks.md                      |  106 +
 docs/subsystems/tasks.zh.md                   |  106 +
 docs/subsystems/telemetry.i18n.yaml           |    4 +-
 docs/subsystems/telemetry.md                  |   72 +-
 docs/subsystems/telemetry.zh.md               |   72 +-
 docs/subsystems/token-meter.i18n.yaml         |    6 +-
 docs/subsystems/token-meter.md                |   47 +
 docs/subsystems/token-meter.zh.md             |   47 +
 docs/subsystems/tools.i18n.yaml               |    4 +-
 docs/subsystems/tools.md                      |  238 ++
 docs/subsystems/tools.zh.md                   |  238 ++
 docs/subsystems/typert.i18n.yaml              |    6 +-
 docs/subsystems/typert.md                     |   93 +
 docs/subsystems/typert.zh.md                  |   93 +
 docs/subsystems/user-interaction.i18n.yaml    |    4 +-
 docs/subsystems/user-interaction.md           |   44 +
 docs/subsystems/user-interaction.zh.md        |   44 +
 docs/subsystems/web.i18n.yaml                 |    6 +-
 docs/subsystems/web.md                        |   67 +
 docs/subsystems/web.zh.md                     |   67 +
 docs/subsystems/workflow.i18n.yaml            |    6 +-
 docs/subsystems/workflow.md                   |  152 +-
 docs/subsystems/workflow.zh.md                |  152 +-
 docs/subsystems/workspace.i18n.yaml           |    4 +-
 docs/subsystems/workspace.md                  |   95 +-
 docs/subsystems/workspace.zh.md               |   95 +-
 docs/tool-catalog.md                          |    2 +-
 docs/user/develop/framework/events.i18n.yaml  |    4 +-
 docs/user/develop/framework/events.md         |    2 +-
 docs/user/develop/framework/events.zh.md      |    2 +-
 docs/user/develop/framework/service.i18n.yaml |    4 +-
 docs/user/develop/framework/service.md        |    2 +-
 docs/user/develop/framework/service.zh.md     |    2 +-
 packages/core/agent-loop/README.i18n.yaml     |    4 +-
 packages/core/agent-loop/README.md            |    2 +-
 packages/core/agent-loop/README.zh.md         |    2 +-
 packages/core/agent/README.i18n.yaml          |    4 +-
 packages/core/agent/README.md                 |    2 +-
 packages/core/agent/README.zh.md              |    2 +-
 packages/core/session/README.i18n.yaml        |    4 +-
 packages/core/session/README.md               |    2 +-
 packages/core/session/README.zh.md            |    2 +-
 packages/core/system-prompt/README.i18n.yaml  |    4 +-
 packages/core/system-prompt/README.md         |    2 +-
 packages/core/system-prompt/README.zh.md      |    2 +-
 packages/core/tools/README.i18n.yaml          |    4 +-
 packages/core/tools/README.md                 |    4 +-
 packages/core/tools/README.zh.md              |    4 +-
 packages/fs/fs/README.i18n.yaml               |    4 +-
 packages/fs/fs/README.md                      |    2 +-
 packages/fs/fs/README.zh.md                   |    2 +-
 packages/goal/goal/README.i18n.yaml           |    4 +-
 packages/goal/goal/README.md                  |    2 +-
 packages/goal/goal/README.zh.md               |    2 +-
 .../user-approval/README.i18n.yaml            |    4 +-
 packages/interaction/user-approval/README.md  |    2 +-
 .../interaction/user-approval/README.zh.md    |    2 +-
 .../tool-cordis/README.i18n.yaml              |    4 +-
 .../self-modification/tool-cordis/README.md   |    2 +-
 .../tool-cordis/README.zh.md                  |    2 +-
 .../typert/generator/src/cordis-catalog.ts    |  145 +-
 .../tests/cordis-catalog-contract.spec.ts     |   14 +-
 .../generator/tests/cordis-catalog.spec.ts    |   24 +-
 scripts/cordis-core-api.spec.ts               |   14 +-
 scripts/cordis-core-api.ts                    |   14 +-
 scripts/cordis-walk.ts                        |   53 +-
 scripts/gen-config-catalog.ts                 |    2 +-
 scripts/gen-cordis-catalog-record.spec.ts     |  144 +
 scripts/gen-cordis-catalog.ts                 |  378 ++-
 scripts/gen-doc-graphs.ts                     |    2 +-
 scripts/gen-persistence-catalog.ts            |    2 +-
 scripts/gen-tool-catalog.ts                   |    2 +-
 scripts/project-doc-site.spec.ts              |    6 +-
 scripts/project-doc-site.ts                   |    6 +
 scripts/translation-pairing.manifest.json     |    2 +-
 scripts/translation-pairing.spec.ts           |   41 +
 scripts/translation-pairing.ts                |  109 +
 scripts/type-equiv.manifest.json              |   15 +
 scripts/verify-translation-pairing.ts         |   22 +
 website/docs.ts                               |   66 +-
 214 files changed, 10434 insertions(+), 4447 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
 create mode 100644 .agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
 rename docs/{cordis-catalog/core => cordis-api}/context.md (91%)
 rename docs/{cordis-catalog/core => cordis-api}/events.md (92%)
 rename docs/{cordis-catalog/core => cordis-api}/fiber.md (90%)
 create mode 100644 docs/cordis-api/inherited.md
 rename docs/{cordis-catalog/core => cordis-api}/registry.md (95%)
 rename docs/{cordis-catalog/core => cordis-api}/service.md (82%)
 delete mode 100644 docs/cordis-catalog/events.md
 delete mode 100644 docs/cordis-catalog/services.md
 create mode 100644 docs/subsystems/session-projection.i18n.yaml
 create mode 100644 docs/subsystems/session-projection.md
 create mode 100644 docs/subsystems/session-projection.zh.md
 create mode 100644 scripts/gen-cordis-catalog-record.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.i18n.yaml
index efeb9d72f3..336d9669ed 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.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 .agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md
-2026-07-05-subagent-provider-lifecycle-events.md: afd45027e8b56cbf1d17e6dec749d8602c81124d
-2026-07-05-subagent-provider-lifecycle-events.zh.md: 01e12946c74fc4fb33c96e047d2030e99b692f47
+2026-07-05-subagent-provider-lifecycle-events.md: 503c0d638785e3a4944c8903b8d7d469c68b1881
+2026-07-05-subagent-provider-lifecycle-events.zh.md: e7d1d8c398a6d77efb2dbccc365e0040f38f2d33
diff --git a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md
index afd45027e8..503c0d6387 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md
@@ -31,6 +31,6 @@ The events also complete the seam's vocabulary: `ctx.subagents` is a named regis
 ## Consequences
 
 - Consumers deriving state from a named provider react to `subagent/provider-added`/`-removed` instead of reading the registry at `apply` time; `dsh-tool-subagent` is the reference implementation.
-- **Addition fails loud; removal is contained per listener.** An addition listener may unwind registration. Removal runs during disposal, so one throwing listener is logged without starving later mirrors or disrupting teardown. `start()` still resolves the provider by name for every run, preventing stale tools from calling a removed backend. See the [events catalog](../../../../docs/cordis-catalog/events.md) and [producer/consumer map](../../../../docs/event-producer-consumer.md).
+- **Addition fails loud; removal is contained per listener.** An addition listener may unwind registration. Removal runs during disposal, so one throwing listener is logged without starving later mirrors or disrupting teardown. `start()` still resolves the provider by name for every run, preventing stale tools from calling a removed backend. See the [events catalog](../../../../docs/subsystems/subagent.md#cordis-surface) and [producer/consumer map](../../../../docs/event-producer-consumer.md).
 - **A window where the tool is absent.** Between backend disposal and re-registration (an HMR reload), the model sees no subagent tool. This is the honest state — the alternative is a tool that dispatches into nothing — and the tool registry's `tools/change` emit keeps prompt assembly current.
 - **Two waiting fibers sharing a `toolName` is an invalid config caught late.** If two loads of `dsh-tool-subagent` name different providers but the same `toolName`, both wait, and whichever provider arrives first registers; the second registration throws only when ITS provider arrives. `TODO(subagent-dup-toolname)` in the plugin records this blast radius; the tool registry's duplicate-name rejection remains the backstop.
diff --git a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.zh.md b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.zh.md
index 01e12946c7..e7d1d8c398 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.zh.md
@@ -31,6 +31,6 @@ Status: implemented
 ## 后果
 
 - 从命名提供方派生状态的消费方响应 `subagent/provider-added`/`-removed` 事件，而非在 `apply` 时读取注册表；`dsh-tool-subagent` 是参考实现。
-- **添加时大声失败；移除时按监听器隔离。** 添加监听器可以回滚注册。移除在 disposal 期间运行，因此单个监听器抛异常只会被记录到日志中，不会阻止后续镜像运行或干扰拆解流程。`start()` 仍在每次运行时按名称解析提供方，防止陈旧工具调用已移除的后端。见[事件目录](../../../../docs/cordis-catalog/events.md)与[生产者/消费方映射](../../../../docs/event-producer-consumer.md)。
+- **添加时大声失败；移除时按监听器隔离。** 添加监听器可以回滚注册。移除在 disposal 期间运行，因此单个监听器抛异常只会被记录日志，不会饿死后续镜像或干扰拆解流程。`start()` 仍在每次运行时按名称解析提供方，防止陈旧工具调用已移除的后端。见[事件目录](../../../../docs/subsystems/subagent.md#cordis-surface)与[生产者/消费方映射](../../../../docs/event-producer-consumer.md)。
 - **工具不存在的窗口期。** 在后端 disposal 与重新注册之间（HMR 重载期间），模型看不到 subagent 工具。这是诚实的状态——替代方案是一个向空处分发的工具——工具注册表发出的 `tools/change` 事件会使提示词组装保持最新状态。
 - **两个等待中的 fiber 共享同一 `toolName` 是无效配置，被延迟捕获。** 如果两个 `dsh-tool-subagent` 加载实例分别指定了不同的提供方但相同的 `toolName`，两者都会等待，先到达的提供方先注册；第二次注册仅在其提供方到达时才抛异常。插件中的 `TODO(subagent-dup-toolname)` 记录了这一影响范围；工具注册表的重名拒绝机制仍是最终防线。
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
index cdee6ab259..215f612f5e 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.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 .agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
-2026-07-08-agent-scope-contexts.md: 5e09bdbcae1e57e6b65eb7d1720a6e7a7f758a9f
-2026-07-08-agent-scope-contexts.zh.md: 4714045f28e0386a3a53b53437d063462e75a9f1
+2026-07-08-agent-scope-contexts.md: eb3f6f247bac1a1d81aa2644132c7b9cc04d602c
+2026-07-08-agent-scope-contexts.zh.md: 673dd8578bf545b1f14f3b7e7b89874d804e4ae9
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
index 5e09bdbcae..eb3f6f247b 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
@@ -104,7 +104,7 @@ An event about Agent A normally reaches unscoped listeners and A-scoped listener
 
 At the Cordis level, `Scoped<T>` is an opaque routing receiver. It carries the filter used to choose listeners but is not the domain object. Event signatures therefore keep the real `Agent`, tool execution, approval request, or other subject as an explicit argument that listeners can inspect.
 
-A listener registered with `{ global: true }` deliberately bypasses contextual audience filtering while its cleanup still follows the registering context. Registry-membership notifications remain unfiltered because they describe shared registry state rather than one agent's operation. The generated [event catalog](../../../../docs/cordis-catalog/events.md) is the exhaustive event reference.
+A listener registered with `{ global: true }` deliberately bypasses contextual audience filtering while its cleanup still follows the registering context. Registry-membership notifications remain unfiltered because they describe shared registry state rather than one agent's operation. The exhaustive event reference is the set of generated `cordis-surface` regions across the [subsystem pages](../../../../docs/subsystems/core.md) — each event scope on its owning page (`agent/*` and `agent-loop/*` on core.md itself).
 
 ### Creation publishes last and disposal revokes last
 
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
index 4714045f28..673dd8578b 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
@@ -104,7 +104,7 @@ setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插
 
 在 Cordis 层面，`Scoped<T>` 是一个不透明的路由接收器。它携带用于选择监听器的过滤器，但本身不是领域对象。因此事件签名将真实的 `Agent`、工具执行、审批请求或其他主体作为显式参数保留，供监听器检查。
 
-以 `{ global: true }` 注册的监听器有意绕过上下文受众过滤，但其清理仍跟随注册上下文。注册表成员变更通知保持不过滤，因为它们描述的是共享注册表状态而非某个 agent 的操作。生成的[事件目录](../../../../docs/cordis-catalog/events.md)是详尽的事件参考。
+以 `{ global: true }` 注册的监听器有意绕过上下文受众过滤，但其清理仍跟随注册上下文。注册表成员变更通知保持不过滤，因为它们描述的是共享注册表状态而非某个 agent 的操作。详尽的事件参考是各[子系统页面](../../../../docs/subsystems/core.md)上生成的 `cordis-surface` 区块的集合——每个事件作用域在其所属页面上（`agent/*` 与 `agent-loop/*` 在 core.md 本页）。
 
 ### 创建最后发布，dispose 最后撤销
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index 6fff14bc85..e0f79bacb0 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.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 .agents/notes/implemented/feature/2026-07-05-skill-system.md
-2026-07-05-skill-system.md: bb7c03a64a3d0d0f700e21bc96633f1c3ea181b9
-2026-07-05-skill-system.zh.md: 8e26e52d3366505a958dd4b19461edf8bf740b00
+2026-07-05-skill-system.md: 5961c535a1397c487b0255f8a27d60929c2eeace
+2026-07-05-skill-system.zh.md: 05bd880ecbd46f2b472eb2cc5442f11c07f89b4e
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
index bb7c03a64a..5961c535a1 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
@@ -28,7 +28,7 @@ Local skill filesystem I/O goes through `ctx.fs` when a filesystem service is lo
 
 The registry's `list()` returns every winning summary, while model and user consumers apply the invocation predicates owned by the [independent invocation-policy decision](2026-07-28-skill-invocation-policy.md). The `skill({ name })` tool loads one model-invocable skill for the current agent cwd and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` supplies a directory, URL, or opaque provider-managed base for explicitly referenced scripts, references, and assets; resources load only as needed, without directory enumeration. An unresolved name reports that the skill is unknown or no longer available; invalid names and skills with `invocation.modelInvocable: false` retain distinct tool errors. The tool result is the model-visible disclosure path.
 
-The data structures and catalog/tool contract are documented in [skills.md](../../../../docs/subsystems/skills.md), with service signatures in the generated [services catalog](../../../../docs/cordis-catalog/services.md).
+The data structures and catalog/tool contract are documented in [skills.md](../../../../docs/subsystems/skills.md), with service signatures in the generated [services catalog](../../../../docs/subsystems/skills.md#cordis-surface).
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 8e26e52d33..05bd880ecb 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -28,7 +28,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
 
-数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/cordis-catalog/services.md)。
+数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/subsystems/skills.md#cordis-surface)。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml
new file mode 100644
index 0000000000..102b0ce5fe
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.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/process/2026-07-28-per-subsystem-cordis-surface-regions.md
+2026-07-28-per-subsystem-cordis-surface-regions.md: ef65bfc4c7dadd7dafe1a38f41656e6ecc61ea50
+2026-07-28-per-subsystem-cordis-surface-regions.zh.md: 1df18d7260800b89c95a9d4aeb0301adb0ee56f6
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
new file mode 100644
index 0000000000..ef65bfc4c7
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
@@ -0,0 +1,36 @@
+# Agent Note: Per-subsystem generated cordis-surface regions
+
+Status: implemented
+
+English | [中文](2026-07-28-per-subsystem-cordis-surface-regions.zh.md)
+
+## Problem
+
+One subsystem's documentation was split across three homes: its hand-written subsystems page (introduction, data structures, verbs), its `ctx.<key>` slice of the flat generated `docs/cordis-catalog/services.md`, and its event scope's slice of the flat `docs/cordis-catalog/events.md`. A reader of bash.md had to open two more documents to see the service interface and events the page was describing, and nothing tied the three views together beyond hand-maintained links. The flat catalogs also sat outside the bilingual corpus (excluded from pairing because generated output is English-only), so the reference surface had no Chinese route at all.
+
+The [generated-catalog decision](../../archived/process/2026-06-20-generated-cordis-catalog.md) — generate from source, `@mode` tags cross-checked, fail-closed type-link coverage, the `ts cordis-catalog` fence — is not in question; what changed is WHERE the generated output lands.
+
+## Decision
+
+`gen-cordis-catalog.ts` injects each subsystem's service and event reference INTO its own page, between `<!-- BEGIN GENERATED cordis-surface … -->` / `<!-- END GENERATED cordis-surface -->` markers, and the flat services/events catalogs are deleted. One page per subsystem now carries introduction, data structures, and the generated wiring surface.
+
+- **Curated fail-loud partition.** `SERVICE_PAGE` maps every discovered `ctx.<key>` to exactly one page; `EVENT_SCOPE_PAGE` maps every event scope. The generator hard-errors in both directions — an unmapped discovered service/scope, and a mapped key/scope the walk no longer discovers — so the partition cannot drift from the source surface. An independent scan of EVERY `declare module 'cordis'` Context merge backstops the rendering walk's blind spot (it only sees a root `index.ts` with a same-named service class): a declared key the walk cannot render must carry a named `SERVICE_WALK_EXEMPTIONS` reason (today: the `ctx.agent` DX accessor, plus the interface-typed or non-index-declared lsp/apiProxy/appShell/tuiPrompt/tuiResumeHost), and stale exemptions hard-error; a `TODO(cordis-catalog-interface-services)` marks teaching the walk to render them.
+- **Byte-identical regions across the pair.** The generator writes the SAME English region bytes into `foo.md` and `foo.zh.md`, extending the existing rule that verbatim code fences match across a pair. `verify-translation-pairing` gained a dedicated region-identity check (`partitionGeneratedRegions` in `translation-pairing.ts` owns the marker grammar) that names a divergent or malformed region precisely; the whole-document structural signature still covers the region content a second time.
+- **Guarded pair auto-record.** A regeneration that changes region bytes would leave every touched pair out-of-sync, so the generator re-records a pair's `.i18n.yaml` itself — but ONLY when the write is region-confined: both sides' recorded blob hashes must match the pre-write bytes, and the region-STRIPPED content must be unchanged on both sides. Human-prose drift leaves the record stale so the pairing gate still forces the normal translation flow; a brand-new pair is never auto-recorded (the author's reviewed `--write` owns that). This keeps `.i18n.yaml` as plain `git hash-object` values — no stripped-hash semantics change.
+- **The inherited tier moved, not died.** The vendor `ctx` members and `internal/*`/loader/hmr/timer events render to `docs/cordis-api/inherited.md`, next to the relocated Cordis core API pages (`docs/cordis-catalog/core/` → `docs/cordis-api/`). Framework surface lives under a framework home; the harness pages stay repository-owned vocabulary.
+- **In-page links.** Signature `Types:` lines link sibling pages (`core.md`, `bash.md`); a type whose primary page is the rendering page is dropped from the line instead of self-linking. Pages reference their own region with `#cordis-surface` or a `#ctx<key>--<class>` anchor — every generated heading is preceded by an explicit `<a id>` carrying the GitHub slug (the historical flat-catalog anchor), so the fragments resolve identically on GitHub and the VitePress site, whose own slugger treats the punctuation-heavy headings differently.
+
+## Alternatives considered
+
+- **Keep the flat catalogs alongside the regions, both generated** — rejected: every JSDoc edit would produce double diff noise, and the scattering (one subsystem, three documents) this change exists to remove would survive.
+- **Generator-owned whole pages with hand-written intros in fragment files** — rejected: the narrative prose is the majority of every existing page and belongs in the reviewed document itself; markers cost one grammar rule and keep authors editing the real file.
+- **Localized regions (generator emits Chinese too)** — deferred, same status as the i18n README's long-standing note for the remaining generated docs: teaching the generator zh output means translating source JSDoc, which is machinery this change does not need. English regions inside zh pages match the existing status quo of English JSDoc inside verbatim fences.
+- **Hashing region-stripped content in `.i18n.yaml`** — rejected: the record would stop being `git hash-object` of the file, breaking the recover-last-confirmed-text property and every consumer that recomputes hashes.
+
+## Consequences
+
+- A subsystem's whole story is one page: `docs/subsystems/<name>.md` (and its pair) carries introduction, data structures/verbs, and the generated service/event surface; `docs/cordis-catalog/` no longer exists.
+- A new service or event scope cannot ship undocumented or unmapped: the generator fails until `SERVICE_PAGE`/`EVENT_SCOPE_PAGE` names its owning page, and the page must already exist with markers in both language sides.
+- Regeneration after a source-JSDoc change touches the affected pages in both languages plus (when region-confined) their pair records — a mechanical, reviewable diff; prose edits keep demanding the translation flow because the auto-record guard refuses them.
+- The website's subsystem nav lists every page (38 routes per locale: 35 translated pairs plus the three still-English-mirrored goal/pty/commands), replacing the two flat catalog nav entries; the Cordis API section gained `inherited.md`.
+- `packages/typert/generator/tests/cordis-catalog-contract.spec.ts` pins the region renderer (`renderPageRegion`), the same-page link-drop rule, and the fail-loud JSDoc/type-link validation; `scripts/translation-pairing.spec.ts` pins the marker grammar and blob-hash primitive; `scripts/gen-cordis-catalog-record.spec.ts` proves the auto-record guard refuses every invalid state (stale record, malformed or renamed-key sidecar, extra entries, prose drift, missing record, missing snapshot).
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
new file mode 100644
index 0000000000..1df18d7260
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 按子系统生成的 cordis-surface 区块
+
+Status: implemented
+
+[English](2026-07-28-per-subsystem-cordis-surface-regions.md) | 中文
+
+## 问题
+
+一个子系统的文档过去分散在三个归属：手写的 subsystems 页面（介绍、数据结构、动词）、平铺生成的 `docs/cordis-catalog/services.md` 中属于它的 `ctx.<key>` 切片，以及平铺的 `docs/cordis-catalog/events.md` 中属于其事件作用域的切片。bash.md 的读者必须再打开两份文档，才能看到该页面正在描述的服务接口与事件；除了手工维护的链接，没有任何机制把这三个视图联系在一起。平铺目录还游离在双语语料之外（生成输出只有英文，故被排除在配对之外），于是这个参考面完全没有中文入口。
+
+[生成式目录决策](../../archived/process/2026-06-20-generated-cordis-catalog.md)本身（从源码生成、`@mode` 标签交叉校验、失败关闭的类型链接覆盖、`ts cordis-catalog` 围栏）不在质疑之列；改变的只是生成输出「落在哪里」。
+
+## 决策
+
+`gen-cordis-catalog.ts` 把每个子系统的服务与事件参考注入到该子系统自己的页面内部，置于 `<!-- BEGIN GENERATED cordis-surface … -->` / `<!-- END GENERATED cordis-surface -->` 标记之间；平铺的 services/events 目录随之删除。现在每个子系统由一个页面同时承载介绍、数据结构和生成的接线表面。
+
+- **人工维护、响亮失败的划分。** `SERVICE_PAGE` 把发现的每个 `ctx.<key>` 映射到恰好一个页面；`EVENT_SCOPE_PAGE` 映射每个事件作用域。生成器在两个方向上都会直接报错（既有被发现却未映射的服务或作用域，也有已映射但遍历不再发现的键或作用域），因此划分不可能相对源码表面发生漂移。一个独立扫描会读取每一处 `declare module 'cordis'` 的 Context 合并，为渲染遍历的盲区（它只看得到根 `index.ts` 中同名服务类）兜底：遍历渲染不了的已声明键必须在 `SERVICE_WALK_EXEMPTIONS` 中带着点名理由（目前是 `ctx.agent` 这一 DX 访问器字段，加上接口类型或不在 index 声明的 lsp/apiProxy/appShell/tuiPrompt/tuiResumeHost），陈旧豁免同样直接报错；教会遍历渲染它们的后续工作由 `TODO(cordis-catalog-interface-services)` 标记。
+- **区块在配对两侧按字节一致。** 生成器把同一份英文区块字节写入 `foo.md` 和 `foo.zh.md`，是对「围栏代码块在配对两侧逐字节一致」这一既有规则的延伸。`verify-translation-pairing` 新增了专门的区块一致性检查（标记语法归 `translation-pairing.ts` 中的 `partitionGeneratedRegions` 所有），能精确点名出现分歧或格式错误的区块；整篇文档的结构签名仍会把区块内容再覆盖一遍。
+- **带防护的配对自动记录。** 一次改变区块字节的重新生成会让每个被触及的配对失去同步，因此生成器会自行重新记录配对的 `.i18n.yaml`，但仅限本次写入完全限定在区块内的情况：两侧记录的 blob hash 必须与写入前的字节相符，且两侧剥离区块后的内容必须没有变化。人工行文若有漂移，记录就保持陈旧，配对门禁因此仍会强制走正常翻译流程；全新的配对绝不自动记录（那归作者经评审的 `--write` 所有）。这样 `.i18n.yaml` 保持为纯粹的 `git hash-object` 值：不引入任何「剥离后 hash」的语义变化。
+- **继承层搬了家，而非消亡。** vendor 的 `ctx` 成员与 `internal/*`/loader/hmr/timer 事件渲染到 `docs/cordis-api/inherited.md`，紧邻迁移后的 Cordis 核心 API 页面（`docs/cordis-catalog/core/` → `docs/cordis-api/`）。框架表面落在框架自己的归属之下；harness 页面仍是仓库自有的词汇。
+- **页内链接。** 签名的 `Types:` 行链接到兄弟页面（`core.md`、`bash.md`）；若某个类型的主要页面就是正在渲染的页面，该类型会从该行去掉，而不是链接到自身。页面用 `#cordis-surface` 或 `#ctx<key>--<class>` 锚点引用自己的区块：每个生成标题前都有一个显式 `<a id>`，携带 GitHub slug（即平铺目录时期的历史锚点），因此这些片段在 GitHub 与 VitePress 站点上解析一致——后者自带的 slugger 对含大量标点的标题会得出不同结果。
+
+## 曾考虑的替代方案
+
+- **平铺目录与区块并存、两者都生成**：否决。每次 JSDoc 编辑都会产生双份 diff 噪音，而本次变更本要消除的分散状况（一个子系统、三份文档）也将延续。
+- **整页归生成器所有、手写介绍放进片段文件**：否决。叙述性行文占每个现有页面的大部分，应当留在被评审的文档本身；标记只花一条语法规则的成本，还让作者继续编辑真实文件。
+- **本地化区块（生成器同时输出中文）**：推迟，与 i18n README 中针对其余生成文档的长期备注同属一个状态：教会生成器输出中文意味着要翻译源码 JSDoc，而那是本次变更并不需要的机制。zh 页面里的英文区块，与「英文 JSDoc 出现在逐字节一致的围栏代码块内」这一既有现状相符。
+- **在 `.i18n.yaml` 中对剥离区块后的内容做 hash**：否决。记录将不再是文件的 `git hash-object`，这会破坏「还原上次确认文本」的性质，也会破坏每个自行重算 hash 的消费方。
+
+## 后果
+
+- 一个子系统的完整故事就在一个页面上：`docs/subsystems/<name>.md`（及其配对文件）承载介绍、数据结构／动词，以及生成的服务／事件表面；`docs/cordis-catalog/` 不复存在。
+- 新的服务或事件作用域无法在未记录、未映射的状态下落地：在 `SERVICE_PAGE`/`EVENT_SCOPE_PAGE` 点名其所属页面之前，生成器一直失败，而且该页面必须已经存在，并在两个语言侧都带有标记。
+- 源码 JSDoc 变更后的重新生成会触及两种语言的受影响页面，外加（当写入限定在区块内时）它们的配对记录：一份机械、可评审的 diff。行文编辑仍然要走翻译流程，因为自动记录防护会拒绝它们。
+- 网站的子系统导航列出每个页面（每个 locale 38 条路由：35 个已翻译配对，加上仍为英文镜像的 goal/pty/commands 三页），取代两个平铺目录导航项；Cordis API 一节新增 `inherited.md`。
+- `packages/typert/generator/tests/cordis-catalog-contract.spec.ts` 固定区块渲染器（`renderPageRegion`）、同页链接去除规则，以及响亮失败的 JSDoc 与类型链接校验；`scripts/translation-pairing.spec.ts` 固定标记语法与 blob hash 原语；`scripts/gen-cordis-catalog-record.spec.ts` 证明自动重录守卫拒绝每一种非法状态（陈旧记录、格式错误或键被改名的伴随记录、多余条目、行文漂移、记录缺失、快照缺失）。
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 488a7a1dd6..5194544f95 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -28,7 +28,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 | [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
 | Package README | Per-package config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc or catalog restatement, other packages' concerns |
 | [development.md](development.md) | Contributor onboarding: setup, daily workflow, and CI shape at summary level | Runtime rationale (→ Agent Notes), drifting gate inventories |
-| Generated catalogs: [cordis events](cordis-catalog/events.md), [cordis services](cordis-catalog/services.md), [Cordis core API](cordis-catalog/core/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/core.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind (regions included) |
 | Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
 
 ## Writing rules
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 15a6ba3fb5..2436ff9027 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 7baf550128fe83528ce12bf2f9b40cfc8f78e322
-architecture.zh.md: 076edd0549fb7f648a7a1b06d7027a1e6eca735f
+architecture.md: f593ee5c54e5bd2cbdaa5da9f2de54b7b08ec14b
+architecture.zh.md: 5780d54aad6085ef7811dfa94377a4c2478bfb99
diff --git a/docs/architecture.md b/docs/architecture.md
index 7baf550128..f593ee5c54 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -53,7 +53,7 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 
 ## Event
 
-Events are the service extension API ([catalog](cordis-catalog/events.md), [producer/consumer map](event-producer-consumer.md)).
+Events are the service extension API ([subsystems](subsystems/core.md), [producer/consumer map](event-producer-consumer.md)).
 
 ### Event Domains
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 076edd0549..5780d54aad 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -53,7 +53,7 @@
 
 ## 事件
 
-事件就是服务的扩展 API（[目录](cordis-catalog/events.md)、[生产方与消费方映射](event-producer-consumer.md)）。
+事件就是服务的扩展 API（[子系统](subsystems/core.md)、[生产方与消费方映射](event-producer-consumer.md)）。
 
 ### 事件域
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 850f4731e2..eb4472d629 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -3,7 +3,7 @@
 
 # Plugin Config Catalog
 
-Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.
+Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated `cordis-surface` region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.
 
 This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.
 
diff --git a/docs/cordis-catalog/core/context.md b/docs/cordis-api/context.md
similarity index 91%
rename from docs/cordis-catalog/core/context.md
rename to docs/cordis-api/context.md
index c0c1690c8f..320b23de1c 100644
--- a/docs/cordis-catalog/core/context.md
+++ b/docs/cordis-api/context.md
@@ -9,7 +9,7 @@ Root and child dependency containers for Cordis plugins.
 
 A context is a proxy: normal property reads go through the service resolver, while `extend()`, `isolate()`, and `intercept()` create scoped child contexts without mutating their parent.
 
-[Source](../../../vendor/cordis/src/context.ts#L42)
+[Source](../../vendor/cordis/src/context.ts#L42)
 
 ### ctx.extend(meta?)
 
@@ -34,7 +34,7 @@ The child prototypally inherits every property of this context; own properties o
 
 **Returns** a child context inheriting from this one.
 
-[Source](../../../vendor/cordis/src/context.ts#L99)
+[Source](../../vendor/cordis/src/context.ts#L99)
 
 ### ctx.isolate(name, label?)
 
@@ -63,7 +63,7 @@ Below the returned context, reads and writes of the service `name` resolve again
 
 **Returns** a child context whose `name` service resolves in the new scope.
 
-[Source](../../../vendor/cordis/src/context.ts#L121)
+[Source](../../vendor/cordis/src/context.ts#L121)
 
 ### ctx.intercept(name, config)
 
@@ -93,7 +93,7 @@ Plugins loaded under the returned context see `config` merged into the service's
 
 **Returns** a child context carrying the additional intercept entry.
 
-[Source](../../../vendor/cordis/src/context.ts#L139)
+[Source](../../vendor/cordis/src/context.ts#L139)
 
 ### ctx.root
 
@@ -104,7 +104,7 @@ root: this
 
 The root context of the application (every child context shares it). @experimental
 
-[Source](../../../vendor/cordis/src/context.ts#L22)
+[Source](../../vendor/cordis/src/context.ts#L22)
 
 ### ctx.baseUrl
 
@@ -115,7 +115,7 @@ baseUrl?: string
 
 Base URL used to resolve relative plugin/module specifiers, if the runtime sets one.
 
-[Source](../../../vendor/cordis/src/context.ts#L24)
+[Source](../../vendor/cordis/src/context.ts#L24)
 
 ### ctx.events
 
@@ -126,7 +126,7 @@ events: EventsService
 
 The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...).
 
-[Source](../../../vendor/cordis/src/context.ts#L26)
+[Source](../../vendor/cordis/src/context.ts#L26)
 
 ### ctx.logger
 
@@ -137,7 +137,7 @@ logger: LoggerService
 
 The logging service. Call `ctx.logger(name)` for a named logger.
 
-[Source](../../../vendor/cordis/src/context.ts#L28)
+[Source](../../vendor/cordis/src/context.ts#L28)
 
 ### ctx.reflect
 
@@ -148,7 +148,7 @@ reflect: ReflectService
 
 The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...).
 
-[Source](../../../vendor/cordis/src/context.ts#L30)
+[Source](../../vendor/cordis/src/context.ts#L30)
 
 ### ctx.registry
 
@@ -159,7 +159,7 @@ registry: RegistryService
 
 The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`).
 
-[Source](../../../vendor/cordis/src/context.ts#L32)
+[Source](../../vendor/cordis/src/context.ts#L32)
 
 ## Static members
 
@@ -172,7 +172,7 @@ static readonly effect: unique symbol
 
 Symbol key under which a disposer exposes its EffectMeta diagnostics tree.
 
-[Source](../../../vendor/cordis/src/context.ts#L44)
+[Source](../../vendor/cordis/src/context.ts#L44)
 
 ### Context.filter
 
@@ -183,7 +183,7 @@ static readonly filter: unique symbol
 
 Symbol key for a context's listener filter, consulted on every event dispatch.
 
-[Source](../../../vendor/cordis/src/context.ts#L46)
+[Source](../../vendor/cordis/src/context.ts#L46)
 
 ### Context.isolate
 
@@ -194,7 +194,7 @@ static readonly isolate: unique symbol
 
 Symbol key of the isolation map (see the `Context[symbols.isolate]` property).
 
-[Source](../../../vendor/cordis/src/context.ts#L48)
+[Source](../../vendor/cordis/src/context.ts#L48)
 
 ### Context.intercept
 
@@ -205,7 +205,7 @@ static readonly intercept: unique symbol
 
 Symbol key of the intercept map (see the `Context[symbols.intercept]` property).
 
-[Source](../../../vendor/cordis/src/context.ts#L50)
+[Source](../../vendor/cordis/src/context.ts#L50)
 
 ### Context.is(value)
 
@@ -230,7 +230,7 @@ Works across realms and across multiple copies of cordis, because the brand is k
 
 **Returns** `true` if `value` is a Cordis context, narrowing its type.
 
-[Source](../../../vendor/cordis/src/context.ts#L61)
+[Source](../../vendor/cordis/src/context.ts#L61)
 
 ## Service store and mixins
 
@@ -256,7 +256,7 @@ Read a service from the store without the inject requirement.
 
 **Returns** the service value, or `undefined` when not (yet) provided.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L17)
+[Source](../../vendor/cordis/src/reflect.ts#L17)
 
 ### ctx.set(name, value)
 
@@ -281,7 +281,7 @@ Only the fiber that provided the service may set it; setting an unprovided name
 - `name` — the service name.
 - `value` — the new service value.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L29)
+[Source](../../vendor/cordis/src/reflect.ts#L29)
 
 ### ctx.provide(name, value)
 
@@ -311,7 +311,7 @@ The service becomes visible to dependents in the same isolation scope once the f
 
 **Returns** a disposer that unregisters the service.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L44)
+[Source](../../vendor/cordis/src/reflect.ts#L44)
 
 ### ctx.accessor(name, options)
 
@@ -335,7 +335,7 @@ The accessor is removed when the current fiber unloads. Throws if the name is al
 - `name` — the context property name.
 - `options` — the `get` hook and optional `set` hook.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L56)
+[Source](../../vendor/cordis/src/reflect.ts#L56)
 
 ### ctx.mixin(name, mixins)
 
@@ -361,4 +361,4 @@ Each mixed-in key becomes an accessor that forwards to the service (binding meth
 - `name` — the context property holding the source service.
 - `mixins` — keys to forward, or a source-key → ctx-key map.
 
-[Source](../../../vendor/cordis/src/reflect.ts#L67)
+[Source](../../vendor/cordis/src/reflect.ts#L67)
diff --git a/docs/cordis-catalog/core/events.md b/docs/cordis-api/events.md
similarity index 92%
rename from docs/cordis-catalog/core/events.md
rename to docs/cordis-api/events.md
index 68cd109e8e..8b8eb2358e 100644
--- a/docs/cordis-catalog/core/events.md
+++ b/docs/cordis-api/events.md
@@ -3,7 +3,7 @@
 
 # Events
 
-The event-dispatch API mixed into every context. Harness event declarations and their dispatch modes are generated separately in the [Cordis events catalog](../events.md).
+The event-dispatch API mixed into every context. Harness event declarations and their dispatch modes are generated into each owning [subsystem page](../subsystems/core.md).
 
 ### ctx.parallel(name, ...args)
 
@@ -26,7 +26,7 @@ Dispatch an event, running all listeners concurrently.
 
 **Returns** a promise resolving once every listener has settled.
 
-[Source](../../../vendor/cordis/src/events.ts#L44)
+[Source](../../vendor/cordis/src/events.ts#L44)
 
 ### ctx.emit(name, ...args)
 
@@ -46,7 +46,7 @@ Dispatch an event synchronously, ignoring listener return values.
 - `name` — the event name.
 - `args` — arguments passed to every listener.
 
-[Source](../../../vendor/cordis/src/events.ts#L53)
+[Source](../../vendor/cordis/src/events.ts#L53)
 
 ### ctx.serial(name, ...args)
 
@@ -69,7 +69,7 @@ Dispatch an event, awaiting listeners in order until one bails.
 
 **Returns** the first bail value (non-null, non-false, non-undefined), if any.
 
-[Source](../../../vendor/cordis/src/events.ts#L63)
+[Source](../../vendor/cordis/src/events.ts#L63)
 
 ### ctx.bail(name, ...args)
 
@@ -92,7 +92,7 @@ Dispatch an event, calling listeners in order until one bails.
 
 **Returns** the first bail value (non-null, non-false, non-undefined), if any.
 
-[Source](../../../vendor/cordis/src/events.ts#L73)
+[Source](../../vendor/cordis/src/events.ts#L73)
 
 ### ctx.waterfall(name, ...args)
 
@@ -120,7 +120,7 @@ Each listener wraps the rest of the chain: calling `next()` invokes the next lis
 
 **Returns** the outermost listener's return value.
 
-[Source](../../../vendor/cordis/src/events.ts#L86)
+[Source](../../vendor/cordis/src/events.ts#L86)
 
 ### ctx.on(name, listener, options?)
 
@@ -144,7 +144,7 @@ Register an event listener owned by the current fiber.
 
 **Returns** a disposer removing the listener; `true` if it was still registered.
 
-[Source](../../../vendor/cordis/src/events.ts#L97)
+[Source](../../vendor/cordis/src/events.ts#L97)
 
 ### ctx.once(name, listener, options?)
 
@@ -168,7 +168,7 @@ Same as `on()`, but the listener disposes itself after its first call.
 
 **Returns** a disposer removing the listener; `true` if it was still registered.
 
-[Source](../../../vendor/cordis/src/events.ts#L106)
+[Source](../../vendor/cordis/src/events.ts#L106)
 
 ## EventOptions
 
@@ -184,7 +184,7 @@ interface EventOptions {
 }
 ```
 
-[Source](../../../vendor/cordis/src/events.ts#L112)
+[Source](../../vendor/cordis/src/events.ts#L112)
 
 ## DispatchMode
 
@@ -204,4 +204,4 @@ Event dispatch strategy used by the event service.
 type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'
 ```
 
-[Source](../../../vendor/cordis/src/events.ts#L32)
+[Source](../../vendor/cordis/src/events.ts#L32)
diff --git a/docs/cordis-catalog/core/fiber.md b/docs/cordis-api/fiber.md
similarity index 90%
rename from docs/cordis-catalog/core/fiber.md
rename to docs/cordis-api/fiber.md
index 35a991f789..36d2861ac6 100644
--- a/docs/cordis-catalog/core/fiber.md
+++ b/docs/cordis-api/fiber.md
@@ -34,7 +34,7 @@ Register a cleanup-aware effect on this fiber.
 
 **Returns** a disposer that tears the effect down and settles once done.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L420)
+[Source](../../vendor/cordis/src/fiber.ts#L420)
 
 ### ctx.fiber
 
@@ -45,7 +45,7 @@ fiber: Fiber
 
 The fiber (plugin runtime instance) that owns this context.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L12)
+[Source](../../vendor/cordis/src/fiber.ts#L12)
 
 ## The Fiber class
 
@@ -53,7 +53,7 @@ Runtime instance of one plugin application.
 
 A fiber tracks dependency state, validated config, lifecycle effects, and cleanup for the plugin context returned by `ctx.plugin()`.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L184)
+[Source](../../vendor/cordis/src/fiber.ts#L184)
 
 ### fiber.uid
 
@@ -64,7 +64,7 @@ public uid: number | null
 
 Unique id within the registry; 0 for the root fiber, `null` once disposed.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L186)
+[Source](../../vendor/cordis/src/fiber.ts#L186)
 
 ### fiber.ctx
 
@@ -75,7 +75,7 @@ public readonly ctx: Context
 
 The context this fiber's plugin runs in (extends the parent context).
 
-[Source](../../../vendor/cordis/src/fiber.ts#L188)
+[Source](../../vendor/cordis/src/fiber.ts#L188)
 
 ### fiber.config
 
@@ -86,7 +86,7 @@ public config: any
 
 The validated plugin config (updated by `update()`).
 
-[Source](../../../vendor/cordis/src/fiber.ts#L190)
+[Source](../../vendor/cordis/src/fiber.ts#L190)
 
 ### fiber.state
 
@@ -97,7 +97,7 @@ public state
 
 Current lifecycle state; transitions emit `internal/status`.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L192)
+[Source](../../vendor/cordis/src/fiber.ts#L192)
 
 ### fiber.dispose
 
@@ -108,7 +108,7 @@ public readonly dispose: () => Promise<void>
 
 Dispose this fiber: unload the plugin, then settle once cleanup finished.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L194)
+[Source](../../vendor/cordis/src/fiber.ts#L194)
 
 ### fiber.store
 
@@ -119,7 +119,7 @@ public store: Dict<Impl> | undefined
 
 Snapshot of required service implementations while loaded; `undefined` otherwise.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L196)
+[Source](../../vendor/cordis/src/fiber.ts#L196)
 
 ### fiber.inertia
 
@@ -130,7 +130,7 @@ public inertia: Promise<void> | undefined
 
 The in-flight load/unload transition, if one is currently running.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L198)
+[Source](../../vendor/cordis/src/fiber.ts#L198)
 
 ### fiber.name
 
@@ -141,7 +141,7 @@ get name()
 
 The plugin's display name, inherited from the nearest named ancestor, else `'root'`.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L341)
+[Source](../../vendor/cordis/src/fiber.ts#L341)
 
 ### fiber.assertActive()
 
@@ -159,7 +159,7 @@ Throw if the fiber has already been disposed.
 
 **Returns** nothing when the fiber is still active.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L356)
+[Source](../../vendor/cordis/src/fiber.ts#L356)
 
 ### fiber.effect(execute, label?)
 
@@ -190,7 +190,7 @@ Register a cleanup-aware effect on this fiber.
 
 **Returns** a disposer that tears the effect down and settles once done.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L420)
+[Source](../../vendor/cordis/src/fiber.ts#L420)
 
 ### fiber.getEffects()
 
@@ -207,7 +207,7 @@ Return metadata for currently registered effects.
 
 **Returns** one `EffectMeta` tree per labeled live effect.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L573)
+[Source](../../vendor/cordis/src/fiber.ts#L573)
 
 ### fiber.await()
 
@@ -225,7 +225,7 @@ Wait for current lifecycle work and rethrow startup errors.
 
 **Returns** this fiber, once it has settled into a stable state.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L702)
+[Source](../../vendor/cordis/src/fiber.ts#L702)
 
 ### fiber.restart()
 
@@ -243,7 +243,7 @@ Dispose and immediately reload this plugin with its current config.
 
 **Returns** a promise resolving once the reload settled.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L716)
+[Source](../../vendor/cordis/src/fiber.ts#L716)
 
 ### fiber.update(config, noSave?)
 
@@ -271,7 +271,7 @@ Runs the `internal/update` waterfall first, so update hooks (and HMR) can veto o
 
 **Returns** the update waterfall result; the default restart returns a promise.
 
-[Source](../../../vendor/cordis/src/fiber.ts#L734)
+[Source](../../vendor/cordis/src/fiber.ts#L734)
 
 ## Effect
 
@@ -292,7 +292,7 @@ type Effect<T = any> =
   | AsyncEffect<T>
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L83)
+[Source](../../vendor/cordis/src/fiber.ts#L83)
 
 ## Disposable
 
@@ -310,7 +310,7 @@ Disposers run in reverse registration order when the owning fiber unloads; they
 type Disposable<T = any> = () => T
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L74)
+[Source](../../vendor/cordis/src/fiber.ts#L74)
 
 ## EffectMeta
 
@@ -326,7 +326,7 @@ interface EffectMeta {
 }
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L96)
+[Source](../../vendor/cordis/src/fiber.ts#L96)
 
 ## CordisError
 
@@ -352,7 +352,7 @@ namespace CordisError {
 }
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L157)
+[Source](../../vendor/cordis/src/fiber.ts#L157)
 
 ## ValidationError
 
@@ -372,4 +372,4 @@ class ValidationError extends TypeError {
 }
 ```
 
-[Source](../../../vendor/cordis/src/fiber.ts#L19)
+[Source](../../vendor/cordis/src/fiber.ts#L19)
diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md
new file mode 100644
index 0000000000..5582bdd1ac
--- /dev/null
+++ b/docs/cordis-api/inherited.md
@@ -0,0 +1,39 @@
+<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
+     Run `pnpm run gen-cordis-catalog` to regenerate. -->
+
+# Inherited Cordis Surface
+
+The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).
+
+This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
+
+## Inherited `ctx` members (cordis core + loader/hmr/timer)
+
+- `ctx.on / ctx.once` — Register an event listener (disposable). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
+- `ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall` — Dispatch an event (sync / awaited / first-bail / veto-chain). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
+- `ctx.plugin / ctx.inject` — Load a plugin / declare required services. ([`vendor/cordis/src/registry.ts:164`](../../vendor/cordis/src/registry.ts))
+- `ctx.effect` — Register a disposable side effect tied to the fiber. ([`vendor/cordis/src/fiber.ts:9`](../../vendor/cordis/src/fiber.ts))
+- `ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin` — Low-level service-store access and binding. ([`vendor/cordis/src/reflect.ts:7`](../../vendor/cordis/src/reflect.ts))
+- `ctx.extend / ctx.isolate / ctx.intercept` — Derive a child context (scoped services / isolation / interception). ([`vendor/cordis/src/context.ts:42`](../../vendor/cordis/src/context.ts))
+- `ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger` — Ambient handles onto the running context graph. ([`vendor/cordis/src/context.ts:16`](../../vendor/cordis/src/context.ts))
+- `ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)` — Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick). ([`vendor/timer/src/index.ts:4`](../../vendor/timer/src/index.ts))
+- `ctx.loader` — The config Loader that booted the app (present under the loader). ([`vendor/loader/src/index.ts:30`](../../vendor/loader/src/index.ts))
+- `ctx.hmr` — The hot-module-reload watcher (present under the hmr plugin). ([`vendor/hmr/src/index.ts:15`](../../vendor/hmr/src/index.ts))
+
+## Inherited events (cordis core + loader/hmr/timer)
+
+- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:328`](../../vendor/cordis/src/events.ts))
+- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:330`](../../vendor/cordis/src/events.ts))
+- `internal/service` — Interception hook for a service binding (no core producer). ([`vendor/cordis/src/events.ts:332`](../../vendor/cordis/src/events.ts))
+- `internal/update` — Waterfall: a fiber config update is being applied. ([`vendor/cordis/src/events.ts:334`](../../vendor/cordis/src/events.ts))
+- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:336`](../../vendor/cordis/src/events.ts))
+- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:338`](../../vendor/cordis/src/events.ts))
+- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:340`](../../vendor/cordis/src/events.ts))
+- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:342`](../../vendor/cordis/src/events.ts))
+- `hmr/change` — A watched source file changed on disk. ([`vendor/hmr/src/index.ts:20`](../../vendor/hmr/src/index.ts))
+- `hmr/reload` — Plugins are being reloaded after a change. ([`vendor/hmr/src/index.ts:21`](../../vendor/hmr/src/index.ts))
+- `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:23`](../../vendor/loader/src/index.ts))
+- `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:24`](../../vendor/loader/src/index.ts))
+- `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
+- `loader/partial-dispose` — An entry is being partially disposed on reload. ([`vendor/loader/src/index.ts:26`](../../vendor/loader/src/index.ts))
+- `loader/patch-context` — A context is being patched during a reload. ([`vendor/loader/src/index.ts:27`](../../vendor/loader/src/index.ts))
diff --git a/docs/cordis-catalog/core/registry.md b/docs/cordis-api/registry.md
similarity index 95%
rename from docs/cordis-catalog/core/registry.md
rename to docs/cordis-api/registry.md
index 6b2e298c72..e6ddce5700 100644
--- a/docs/cordis-catalog/core/registry.md
+++ b/docs/cordis-api/registry.md
@@ -30,7 +30,7 @@ Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback is unloade
 
 **Returns** the fiber; awaiting it settles once loading finished.
 
-[Source](../../../vendor/cordis/src/registry.ts#L176)
+[Source](../../vendor/cordis/src/registry.ts#L176)
 
 ### ctx.plugin(plugin, ...args)
 
@@ -53,7 +53,7 @@ Load a plugin in the current context.
 
 **Returns** the fiber; awaiting it settles once loading finished (rejecting on config or startup errors).
 
-[Source](../../../vendor/cordis/src/registry.ts#L185)
+[Source](../../vendor/cordis/src/registry.ts#L185)
 
 ## Plugin
 
@@ -118,7 +118,7 @@ namespace Plugin {
 }
 ```
 
-[Source](../../../vendor/cordis/src/registry.ts#L92)
+[Source](../../vendor/cordis/src/registry.ts#L92)
 
 ## Inject
 
@@ -149,4 +149,4 @@ namespace Inject {
 }
 ```
 
-[Source](../../../vendor/cordis/src/registry.ts#L19)
+[Source](../../vendor/cordis/src/registry.ts#L19)
diff --git a/docs/cordis-catalog/core/service.md b/docs/cordis-api/service.md
similarity index 82%
rename from docs/cordis-catalog/core/service.md
rename to docs/cordis-api/service.md
index 84b74f98df..d4b0f06da1 100644
--- a/docs/cordis-catalog/core/service.md
+++ b/docs/cordis-api/service.md
@@ -9,7 +9,7 @@ Base class for services that expose a named API on `ctx`.
 
 Subclasses call `super(ctx, name)` from their constructor. The service is registered immediately and is automatically removed with the owning fiber.
 
-[Source](../../../vendor/cordis/src/service.ts#L11)
+[Source](../../vendor/cordis/src/service.ts#L11)
 
 ### service.name
 
@@ -20,7 +20,7 @@ public name!: string
 
 The service name this instance is registered under.
 
-[Source](../../../vendor/cordis/src/service.ts#L30)
+[Source](../../vendor/cordis/src/service.ts#L30)
 
 ## Static members
 
@@ -33,7 +33,7 @@ static readonly init: unique symbol
 
 Symbol key of an instance method run after construction (class plugins).
 
-[Source](../../../vendor/cordis/src/service.ts#L13)
+[Source](../../vendor/cordis/src/service.ts#L13)
 
 ### Service.check
 
@@ -44,7 +44,7 @@ static readonly check: unique symbol
 
 Symbol key of the availability predicate passed to `ctx.provide()`.
 
-[Source](../../../vendor/cordis/src/service.ts#L15)
+[Source](../../vendor/cordis/src/service.ts#L15)
 
 ### Service.config
 
@@ -55,7 +55,7 @@ static readonly config: unique symbol
 
 Symbol key of the phantom intercept-config type parameter.
 
-[Source](../../../vendor/cordis/src/service.ts#L17)
+[Source](../../vendor/cordis/src/service.ts#L17)
 
 ### Service.invoke
 
@@ -66,7 +66,7 @@ static readonly invoke: unique symbol
 
 Symbol key of the call body making a service callable (e.g. `ctx.logger()`).
 
-[Source](../../../vendor/cordis/src/service.ts#L19)
+[Source](../../vendor/cordis/src/service.ts#L19)
 
 ### Service.extend
 
@@ -77,7 +77,7 @@ static readonly extend: unique symbol
 
 Symbol key of the helper deriving an extended service instance.
 
-[Source](../../../vendor/cordis/src/service.ts#L21)
+[Source](../../vendor/cordis/src/service.ts#L21)
 
 ### Service.tracker
 
@@ -88,7 +88,7 @@ static readonly tracker: unique symbol
 
 Symbol key of the tracker metadata used for context tracing.
 
-[Source](../../../vendor/cordis/src/service.ts#L23)
+[Source](../../vendor/cordis/src/service.ts#L23)
 
 ### Service.resolveConfig
 
@@ -99,4 +99,4 @@ static readonly resolveConfig: unique symbol
 
 Symbol key of the intercept-config resolution helper below.
 
-[Source](../../../vendor/cordis/src/service.ts#L25)
+[Source](../../vendor/cordis/src/service.ts#L25)
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
deleted file mode 100644
index fb05eaa8e6..0000000000
--- a/docs/cordis-catalog/events.md
+++ /dev/null
@@ -1,1100 +0,0 @@
-<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
-     Run `pnpm run gen-cordis-catalog` to regenerate. -->
-
-# Cordis Events Catalog
-
-Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.
-
-This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
-
-The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).
-
-Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`).
-
-## `agent/*`
-
-### `agent/created` — emit
-
-A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
-
-```ts cordis-catalog
-/**
- * A fully configured agent and live session were published. Setup is
- * composition-only; `agent/session-start` is the first startup-driving seam.
- * Synchronous listener failure vetoes publication, while returned-promise
- * rejection is reported. Detach requested during dispatch waits until every
- * creation listener has observed the stable entry.
- * @param payload.agent - the newly registered agent with its live session and completed setup.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
-
-### `agent/disposed` — emit
-
-An agent left the registry; AgentLoop emits this after driver quiescence and scoped-registration unwind, but before session detachment. Custom registry users own their driver-ordering contract.
-
-```ts cordis-catalog
-/**
- * An agent left the registry; AgentLoop emits this after driver quiescence
- * and scoped-registration unwind, but before session detachment. Custom
- * registry users own their driver-ordering contract.
- * @param payload.agent - the exact agent removed from the registry.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
-
-### `agent/error` — emit
-
-A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
-
-```ts cordis-catalog
-/**
- * A step or turn errored. The machine reports a failure here even when
- * the error has no in-turn position for a durable record.
- * @param payload.agent - the agent whose turn errored.
- * @param payload.turn - the turn in which the failure surfaced.
- * @param payload.step - the step at which the failure surfaced.
- * @param payload.error - the failure, verbatim.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
-
-### `agent/inbox/claimed` — emit
-
-One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
-
-```ts cordis-catalog
-/**
- * One message left the inbox inside its open turn. If the proposed step
- * is rejected, the claimed message ends here: it is neither discarded nor
- * re-emitted as a user/message, and the turn closes without a step.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the claimed message.
- * @param payload.turn - the owning turn.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
-
-Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
-
-### `agent/inbox/discarded` — emit
-
-One message was discarded from the live inbox.
-
-```ts cordis-catalog
-/**
- * One message was discarded from the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the discarded message.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
-
-Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
-
-### `agent/inbox/inserted` — emit
-
-One message entered the live inbox.
-
-```ts cordis-catalog
-/**
- * One message entered the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the inserted message.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
-
-Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
-
-### `agent/pre-step` — waterfall
-
-Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
-
-```ts cordis-catalog
-/**
- * Reject a proposed step or replace the messages that enter it. Calling
- * `next()` preserves the current messages.
- * @param payload.agent - the agent proposing the step.
- * @param payload.messages - messages removed from the inbox for this step.
- * @param payload.turn - the turn that will own the step.
- * @param payload.step - the step proposed by the loop.
- * @param payload.signal - the current turn's cancellation signal.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode waterfall
- */
-'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
-```
-
-Types: [Agent](../subsystems/core.md) · [PreStepDecision](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md)
-
-Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
-
-### `agent/request` — waterfall
-
-Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this seam cannot mutate messages.
-
-```ts cordis-catalog
-/**
- * Replace the frozen call configuration. `await next()` yields the config
- * the machine would use (agent options on the first request, the logged
- * header afterwards); return a replacement to switch. Model-visible
- * content must use logged channels; this seam cannot mutate messages.
- * @param payload.agent - the agent making the model call.
- * @param payload.turn - the open turn number.
- * @param payload.step - the step whose request this is.
- * @param payload.signal - the current turn's explicit abort signal.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode waterfall
-*/
-'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
-```
-
-Types: [Agent](../subsystems/core.md) · [LlmCallConfig](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
-
-### `agent/request-error` — waterfall
-
-Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
-
-```ts cordis-catalog
-/**
- * Handle one failed model-request attempt before the loop retries or closes
- * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
- * when it owns recovery, or calls `next()` to delegate. The default
- * `undefined` leaves the failure terminal.
- * @param payload.agent - the agent whose request failed.
- * @param payload.turn - the turn containing the failed request.
- * @param payload.step - the step containing the failed request attempt.
- * @param payload.provider - the provider selected for the failed request.
- * @param payload.failure - serializable facts normalized at the final adapter boundary.
- * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
- * @param payload.signal - the turn abort signal.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode waterfall
- */
-'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
-```
-
-Types: [Agent](../subsystems/core.md) · [LlmFailure](../subsystems/llm-streaming.md) · [RequestErrorAction](../subsystems/core.md) · [ResolvedRetryPolicy](../subsystems/llm-streaming.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
-
-### `agent/session-start` — emit
-
-The session lifecycle began, once before the first turn. Use `agent.inject()` to seed model-facing context. This is a notification, not a veto; disposal requested by a lifecycle owner is rechecked before the driver starts.
-
-```ts cordis-catalog
-/**
- * The session lifecycle began, once before the first turn. Use
- * `agent.inject()` to seed model-facing context. This is a notification, not
- * a veto; disposal requested by a lifecycle owner is rechecked before the
- * driver starts.
- * @param payload.agent - the agent whose session lifecycle began.
- * @param payload.source - why the session started (fresh startup, resume, …).
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [SessionStartSource](../subsystems/core.md)
-
-Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
-
-### `agent/status` — emit
-
-Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
-
-```ts cordis-catalog
-/**
- * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
- * `running` synchronously after reserving cancellation; `idle` means no
- * driver remains scheduled or active.
- * @param payload.agent - the agent whose status flipped.
- * @param payload.status - the status just entered (the transition's destination).
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [AgentStatus](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
-
-### `agent/turn-stopping` — serial
-
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
-
-```ts cordis-catalog
-/**
- * The turn is about to close: the model owes no response (no live tool
- * calls, no fresh steering). Awaited before the boundary commits — a
- * listener that objects steers (`agent.steer(...)`) and the machine
- * re-reads its inbox: fresh steering runs another step, none closes the
- * turn. Data decides, so listener order cannot change the outcome. The
- * inverse control (stop a tool loop early) is data too: a tool result
- * carrying `concludesTurn` ends the turn at its step. The conclusion
- * never short-circuits already-submitted next-step work: same-step
- * `additionalContexts` or racing steering still runs, and the turn
- * closes only when that inbox drains.
- * @param payload.agent - the agent whose turn is at its stop boundary.
- * @param payload.turn - the turn about to close.
- * @param payload.signal - the current turn's explicit abort signal.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode serial
- */
-'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
-```
-
-Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
-
-## `agent-loop/*`
-
-### `agent-loop/config-start-failed` — emit
-
-A declarative agent entry failed before it could publish a live agent. Consumers that buffer work for the configured identity use this transient signal to reject that work instead of waiting forever. Normal factory teardown suppresses failures from the cancelled startup attempt.
-
-```ts cordis-catalog
-/**
- * A declarative agent entry failed before it could publish a live agent.
- * Consumers that buffer work for the configured identity use this
- * transient signal to reject that work instead of waiting forever. Normal
- * factory teardown suppresses failures from the cancelled startup attempt.
- * @param payload.sessionId - exact shared agent/session identity that failed startup.
- * @param payload.error - persistence, setup, or publication failure.
- * @mode emit
- */
-'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
-```
-
-Types: [SessionId](../subsystems/core.md)
-
-Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
-
-## `approval/*`
-
-### `approval/request` — waterfall
-
-Ask composed answerers for one decision. Return an outcome to claim the request or call `next()`; failure yields the fail-closed default. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
-
-```ts cordis-catalog
-/**
- * Ask composed answerers for one decision. Return an outcome to claim the
- * request or call `next()`; failure yields the fail-closed default.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @param req - the pending decision (agent, tool identity, reason, signal).
- * @mode waterfall
- */
-'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
-```
-
-Types: [ApprovalOutcome](../subsystems/approval.md) · [ApprovalRequest](../subsystems/approval.md) · [ApprovalService](../subsystems/approval.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts)
-
-## `commands/*`
-
-### `commands/change` — emit
-
-A command was registered or unregistered. This is an unfiltered registry notification because a global or scoped change may affect any UI view. Observer failures are contained and cannot veto the registry mutation.
-
-```ts cordis-catalog
-/**
- * A command was registered or unregistered. This is an unfiltered registry
- * notification because a global or scoped change may affect any UI view.
- * Observer failures are contained and cannot veto the registry mutation.
- * @mode emit
- */
-'commands/change'(): void
-```
-
-Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
-
-## `credentials/*`
-
-### `credentials/updated` — emit
-
-Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
-
-```ts cordis-catalog
-/**
- * Committed change to a provider-managed credential source: a `set`, an
- * `unset`, or an external edit observed in storage. Ambient
- * process-environment changes are not observable and never emit. Listener
- * failures are contained and logged — a sync throw and an async rejection
- * alike — without changing the committed operation's outcome, except
- * `INVARIANT`-coded failures, which rethrow after every listener ran;
- * that rethrow reaches the emitter only from synchronous listeners, so
- * invariant checks on this event must not be async functions.
- * @param ref - the reference whose stored value changed.
- * @mode emit
- */
-'credentials/updated'(ref: CredentialRef): void
-```
-
-Types: [CredentialRef](../subsystems/credentials.md)
-
-Source: [`packages/credentials/credentials/src/index.ts:67`](../../packages/credentials/credentials/src/index.ts)
-
-## `domain/*`
-
-### `domain/changed` — emit
-
-A domain record or the global singleton changed, emitted once per write strictly after the backend acknowledged durability. Events of one domain arrive in its write-chain order.
-
-```ts cordis-catalog
-/**
- * A domain record or the global singleton changed, emitted once per write
- * strictly after the backend acknowledged durability. Events of one
- * domain arrive in its write-chain order.
- * @param change - domain, table (`''` for global), key (`''` for global),
- * operation discriminant, and on `put` the new snapshot.
- * @mode emit
- */
-'domain/changed'(change: DomainChanged): void
-```
-
-Types: [DomainChanged](../subsystems/storage.md)
-
-Source: [`packages/storage/storage-domain/src/events.ts:46`](../../packages/storage/storage-domain/src/events.ts)
-
-## `fs/*`
-
-### `fs/edit-intent` — waterfall
-
-Single-slot decision for the next FileSystem.editText. Calling `next()` yields an unconditional edit; the first returned guard wins.
-
-```ts cordis-catalog
-/**
- * Single-slot decision for the next {@link FileSystem.editText}. Calling
- * `next()` yields an unconditional edit; the first returned guard wins.
- * @param target - the resolved target about to be edited.
- * @param actor - the opaque tool-execution context the decider keys off.
- * @mode waterfall
- */
-'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
-```
-
-Types: [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md)
-
-Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
-
-### `fs/observed` — emit
-
-Record a successful observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
-
-```ts cordis-catalog
-/**
- * Record a successful observation. Listeners must be synchronous recorders:
- * throws fail the tool call and returned promises are not awaited.
- * @param target - the target that was read/written/edited.
- * @param version - the version the actor now holds as its observation.
- * @param actor - the observing tool-execution context; undefined records nothing useful.
- * @mode emit
- */
-'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
-```
-
-Types: [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md)
-
-Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
-
-### `fs/write-intent` — waterfall
-
-Single-slot decision for the next FileSystem.writeText. Calling `next()` yields the bare provider's unconditional write; the first listener that returns an intent owns the decision rather than composing with peers.
-
-```ts cordis-catalog
-/**
- * Single-slot decision for the next {@link FileSystem.writeText}. Calling
- * `next()` yields the bare provider's unconditional write; the first listener
- * that returns an intent owns the decision rather than composing with peers.
- * @param target - the resolved target about to be written.
- * @param actor - the opaque tool-execution context the decider keys off.
- * @mode waterfall
- */
-'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
-```
-
-Types: [FsTarget](../subsystems/filesystem.md) · [FsWriteIntent](../subsystems/filesystem.md)
-
-Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
-
-## `goal/*`
-
-### `goal/changed` — emit
-
-Goal mutation accepted by one live agent. The matching `goal/change` session event has already committed. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
-
-```ts cordis-catalog
-/**
- * Goal mutation accepted by one live agent. The matching `goal/change`
- * session event has already committed. Listener failures are contained.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @param payload.agent - agent whose session owns the goal.
- * @param payload.change - fresh current projection or clear tombstone.
- * @mode emit
- */
-'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void
-```
-
-Types: [Agent](../subsystems/core.md) · [GoalChanged](../subsystems/goal.md) · [Scoped](../subsystems/scope.md)
-
-Source: [`packages/goal/goal/src/domain.ts:114`](../../packages/goal/goal/src/domain.ts)
-
-## `llm/*`
-
-### `llm/adapters-updated` — emit
-
-The provider topology changed: an adapter registered or unregistered routes, or the configurable-provider directory gained or lost entries. This is a payload-free registry notification fired at each commit point (including registration disposal); consumers re-read `listProviders()`, `listModels()`, or `listConfigurableProviders()` for the new state. Observer failures are contained and cannot veto the registry mutation.
-
-```ts cordis-catalog
-/**
- * The provider topology changed: an adapter registered or unregistered
- * routes, or the configurable-provider directory gained or lost entries.
- * This is a payload-free registry notification fired at each commit point
- * (including registration disposal); consumers re-read `listProviders()`,
- * `listModels()`, or `listConfigurableProviders()` for the new state.
- * Observer failures are contained and cannot veto the registry mutation.
- * @mode emit
- */
-'llm/adapters-updated'(): void
-```
-
-Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
-
-### `llm/stream` — waterfall
-
-Waterfall around every streaming model call (retry, replay, routing). Bound to the LlmService; call `next()` to reach the resolved adapter's stream, or yield your own chunks to short-circuit.
-
-```ts cordis-catalog
-/**
- * Waterfall around every streaming model call (retry, replay, routing).
- * Bound to the {@link LlmService}; call `next()` to reach the resolved
- * adapter's stream, or yield your own chunks to short-circuit.
- * @param options - the full request. A LOOP-built request carries the
- *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen
- *   (mutation throws): its content is a pure function of the session log (the
- *   reconstructability Agent Note), so listeners read it, never rewrite it.
- *   Hand-built calls do not carry that marker; their messages already obey
- *   the immutable creation contract.
- * @mode waterfall
- */
-'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
-```
-
-Types: [GenerateOptions](../subsystems/core.md) · [LlmService](../subsystems/llm-streaming.md) · [StreamChunk](../subsystems/llm-streaming.md)
-
-Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
-
-## `session/*`
-
-### `session/created` — emit
-
-Creation announcement during session publication. A synchronous throw vetoes and rolls back with a paired disposal; detach requested during dispatch is deferred. A returned-promise rejection is logged but cannot retroactively veto this synchronous boundary. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only sessions entered through that agent's context.
-
-```ts cordis-catalog
-/**
- * Creation announcement during session publication. A synchronous throw vetoes and rolls
- * back with a paired disposal; detach requested during dispatch is deferred.
- * A returned-promise rejection is logged but cannot retroactively veto this
- * synchronous boundary.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
- * receive only sessions entered through that agent's context.
- * @param session - the session just entered and announced.
- * @dshScopeScan unsupported
- * @mode emit
- */
-'session/created'(this: Scoped<Session>, session: Session): void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/core/session/src/index.ts:74`](../../packages/core/session/src/index.ts)
-
-### `session/disposed` — emit
-
-Emitted once when an announced session leaves the store, including publication rollback, but never for an entry whose creation announcement did not begin. Listener failures are logged and contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
-
-```ts cordis-catalog
-/**
- * Emitted once when an announced session leaves the store, including
- * publication rollback, but never for an entry whose creation announcement
- * did not begin. Listener failures are logged and contained.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
- * @param session - the session that is no longer live in the store.
- * @dshScopeScan unsupported
- * @mode emit
- */
-'session/disposed'(this: Scoped<Session>, session: Session): void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/core/session/src/index.ts:84`](../../packages/core/session/src/index.ts)
-
-### `session/event` — emit
-
-Post-commit, fire-and-forget append feed. The listener snapshot resolves before the log push, but callbacks run after it; observer failures are logged and contained without making the committed append fail. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only events from sessions entered through that agent's context.
-
-```ts cordis-catalog
-/**
- * Post-commit, fire-and-forget append feed. The listener snapshot resolves
- * before the log push, but callbacks run after it; observer failures are
- * logged and contained without making the committed append fail.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
- * receive only events from sessions entered through that agent's context.
- * @param session - the session whose log grew.
- * @param event - the appended event, exactly as recorded.
- * @dshScopeScan unsupported
- * @mode emit
- */
-'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
-
-Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
-
-### `session/flush` — parallel
-
-Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
-
-```ts cordis-catalog
-/**
- * Awaited parallel durability checkpoint: every listener runs and the
- * caller awaits all of them, with no waterfall veto. Scope-filtered dispatch
- * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
- * @param session - the session whose buffered events must reach durable storage.
- * @dshScopeScan unsupported
- * @mode parallel
- */
-'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/core/session/src/index.ts:105`](../../packages/core/session/src/index.ts)
-
-## `settings/*`
-
-### `settings/document-updated` — emit
-
-One registered namespace's RAW user section changed, whether or not the resolved value did. `settings/updated` is the consumer-facing event and stays deep-equal-gated; this one exists for configuration surfaces, which must learn that a field went from inherited to overridden (same resolved value, different meaning) and that their held revision is stale. Listener containment matches `settings/updated`.
-
-```ts cordis-catalog
-/**
- * One registered namespace's RAW user section changed, whether or not the
- * resolved value did. `settings/updated` is the consumer-facing event and
- * stays deep-equal-gated; this one exists for configuration surfaces,
- * which must learn that a field went from inherited to overridden (same
- * resolved value, different meaning) and that their held revision is
- * stale. Listener containment matches `settings/updated`.
- * @param ns - the namespace whose stored section changed.
- * @param revision - the namespace's new revision.
- * @mode emit
- */
-'settings/document-updated'(ns: SettingsNamespace, revision: number): void
-```
-
-Types: [SettingsNamespace](../subsystems/settings.md)
-
-Source: [`packages/settings/settings/src/index.ts:170`](../../packages/settings/settings/src/index.ts)
-
-### `settings/updated` — emit
-
-Committed change to one registered namespace's resolved value. Emitted after the provider persisted (for `update`) or published (`provider`) the change; never emitted when the resolved value is deep-equal. Listener failures are contained and logged — a sync throw and an async rejection alike — except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
-
-```ts cordis-catalog
-/**
- * Committed change to one registered namespace's resolved value. Emitted
- * after the provider persisted (for `update`) or published (`provider`)
- * the change; never emitted when the resolved value is deep-equal.
- * Listener failures are contained and logged — a sync throw and an async
- * rejection alike — except `INVARIANT`-coded failures, which rethrow
- * after every listener ran; that rethrow reaches the emitter only from
- * synchronous listeners, so invariant checks on this event must not be
- * async functions.
- * @param ns - the namespace whose resolved value changed.
- * @param next - the new resolved value.
- * @param prev - the previous resolved value.
- * @param source - whether the change entered through `update()` or the provider.
- * @mode emit
- */
-'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void
-```
-
-Types: [SettingsNamespace](../subsystems/settings.md) · [SettingsUpdateSource](../subsystems/settings.md)
-
-Source: [`packages/settings/settings/src/index.ts:157`](../../packages/settings/settings/src/index.ts)
-
-## `skills/*`
-
-### `skills/change` — emit
-
-A skill provider, runtime contribution, or provider-backed catalog may have changed. This is an unfiltered invalidation notification; consumers refetch the catalog for their own lookup options. Listener failures are contained and cannot veto the registry mutation.
-
-```ts cordis-catalog
-/**
- * A skill provider, runtime contribution, or provider-backed catalog may
- * have changed. This is an unfiltered invalidation notification; consumers
- * refetch the catalog for their own lookup options. Listener failures are
- * contained and cannot veto the registry mutation.
- * @mode emit
- */
-'skills/change'(): void
-```
-
-Source: [`packages/skill/skill/src/index.ts:283`](../../packages/skill/skill/src/index.ts)
-
-## `subagent/*`
-
-### `subagent/end` — emit
-
-A published child settled. Scope-filtered dispatch uses the same delegating parent carrier as `subagent/start`, so the lifecycle pair reaches the same scoped audience.
-
-```ts cordis-catalog
-/**
- * A published child settled. Scope-filtered dispatch uses the same delegating
- * parent carrier as `subagent/start`, so the lifecycle pair reaches the
- * same scoped audience.
- * @param info - the run identity and terminal outcome.
- * @dshScopeScan unsupported
- * @mode emit
- */
-'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [SubagentService](../subsystems/subagent.md)
-
-Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts)
-
-### `subagent/provider-added` — emit
-
-A provider became resolvable in the registry.
-
-```ts cordis-catalog
-/**
- * A provider became resolvable in the registry.
- * @param provider - the registered provider.
- * @mode emit
- */
-'subagent/provider-added'(provider: SubagentProvider): void
-```
-
-Types: [SubagentProvider](../subsystems/subagent.md)
-
-Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts)
-
-### `subagent/provider-removed` — emit
-
-A provider left the registry. Accepted runs remain holder-owned.
-
-```ts cordis-catalog
-/**
- * A provider left the registry. Accepted runs remain holder-owned.
- * @param name - the provider name that no longer resolves.
- * @mode emit
- */
-'subagent/provider-removed'(name: string): void
-```
-
-Source: [`packages/subagent/subagent/src/index.ts:142`](../../packages/subagent/subagent/src/index.ts)
-
-### `subagent/start` — emit
-
-A provider established a published child. For in-process providers, `ctx.agents.get(info.id)` resolves during this notification. Scope-filtered dispatch keys the carrier by the delegating parent, so a parent-scoped listener observes only its own delegations. Paired with `subagent/end`.
-
-```ts cordis-catalog
-/**
- * A provider established a published child. For in-process providers,
- * `ctx.agents.get(info.id)` resolves during this notification.
- * Scope-filtered dispatch keys the carrier by the delegating parent, so a
- * parent-scoped listener observes only its own delegations. Paired with
- * `subagent/end`.
- * @param info - the provider and published child identity.
- * @dshScopeScan unsupported
- * @mode emit
- */
-'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
-```
-
-Types: [Scoped](../subsystems/scope.md) · [SubagentService](../subsystems/subagent.md)
-
-Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
-
-## `system-prompt/*`
-
-### `system-prompt/assemble` — waterfall
-
-Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns.
-
-```ts cordis-catalog
-/**
- * Expert waterfall over the assembled sections, contexts, tools, and variables.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
- * receive only that scope's assemblies. The returned value is authoritative.
- * A supplied signal controls only this explicit assembly request and must not
- * be retained to control later turns.
- * @param assembly - the mutable assembly built from registered providers.
- * @param context - the caller's per-assembly context.
- * @mode waterfall
- */
-'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
-```
-
-Types: [AssembleContext](../subsystems/system-prompt.md) · [Scoped](../subsystems/scope.md) · [SystemPrompt](../subsystems/system-prompt.md)
-
-Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts)
-
-### `system-prompt/change` — emit
-
-Emitted when any prompt provider changes. This registry notification is unfiltered because a global change affects every scope.
-
-```ts cordis-catalog
-/**
- * Emitted when any prompt provider changes. This registry notification is
- * unfiltered because a global change affects every scope.
- * @mode emit
- */
-'system-prompt/change'(): void
-```
-
-Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/system-prompt/src/index.ts)
-
-## `telemetry/*`
-
-### `telemetry/record` — waterfall
-
-Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
-
-```ts cordis-catalog
-/**
- * Transform one outbound record before it reaches the backend. This
- * waterfall is the seam's redaction extension point. It ships NO rules
- * of its own: the
- * innermost `next()` passes the record through unchanged, and with no
- * listener mounted records reach the backend as captured, so exported
- * data is exactly as clean as the rules a deployment mounts. Listeners
- * stack by transforming `next()`'s return value; returning without
- * `next()` replaces everything beneath. Dispatched synchronously on the
- * capture hot path inside the coordinator's containment: a throwing
- * listener withholds that one record (fail-closed) and never reaches the
- * agent loop. Live capture dispatches at append time; on-demand capture
- * dispatches while reading the canonical log. Redaction applies to the
- * exported copy only; the canonical session log is never rewritten.
- * @param record - the candidate record, already the coordinator's own deep
- *   copy; listeners return a (possibly new) record and must not mutate it.
- * @mode waterfall
- */
-'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
-```
-
-Types: [TelemetryRecord](../subsystems/telemetry.md)
-
-Source: [`packages/session/session-telemetry/src/index.ts:43`](../../packages/session/session-telemetry/src/index.ts)
-
-## `tools/*`
-
-### `tools/change` — emit
-
-A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed — possibly for one scope only). An UNFILTERED registry-subject notification, deliberately not scope-filtered dispatch: a global change concerns every agent's next assembly, so a scoped listener subscribing here sees every change, not just its own scope's.
-
-```ts cordis-catalog
-/**
- * A tool was registered or unregistered, or a scoped restriction changed
- * (the available tool set changed — possibly for one scope only). An
- * UNFILTERED registry-subject notification, deliberately not scope-filtered
- * dispatch: a global change concerns every agent's next assembly, so a
- * scoped listener subscribing here sees every change, not just its own
- * scope's.
- * @mode emit
- */
-'tools/change'(): void
-```
-
-Source: [`packages/core/tools/src/index.ts:191`](../../packages/core/tools/src/index.ts)
-
-### `tools/code-dispatch-log` — waterfall
-
-Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bridge appends its `tool/code-dispatch` event. `next()` keeps the content unchanged; a listener may return replacement blocks (e.g. the spill policy's preview + locator for an oversized text result). Only the logged copy is affected — the program already received the complete value, and the model sees neither. A throwing listener is contained: the bridge falls back to logging the unshaped content. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
-
-```ts cordis-catalog
-/**
- * Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before
- * the bridge appends its `tool/code-dispatch` event. `next()` keeps the
- * content unchanged; a listener may return replacement blocks (e.g. the
- * spill policy's preview + locator for an oversized text result). Only the
- * logged copy is affected — the program already received the complete
- * value, and the model sees neither. A throwing listener is contained:
- * the bridge falls back to logging the unshaped content.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
- * @param dispatch - the parent execution, sub-call identity, and the settled content to log.
- * @mode waterfall
- */
-'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
-```
-
-Types: [CodeDispatchLog](../subsystems/tools.md) · [ContentBlock](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [ToolRegistry](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
-
-### `tools/execute` — waterfall
-
-Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a normalized result; wrappers may change only `exec.signal`, while call identity remains immutable. The registry re-fuses the original caller signal before the body, so replacement cannot detach caller cancellation; wrappers must still restore their signal and reach quiescence. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
-
-```ts cordis-catalog
-/**
- * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
- * a normalized result; wrappers may change only `exec.signal`, while call
- * identity remains immutable. The registry re-fuses the original caller
- * signal before the body, so replacement cannot detach caller cancellation;
- * wrappers must still restore their signal and reach quiescence.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
- * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
- * @mode waterfall
- */
-'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
-```
-
-Types: [Scoped](../subsystems/scope.md) · [ToolDispatchExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
-
-### `tools/post-execute` — waterfall
-
-Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this seam as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
-
-```ts cordis-catalog
-/**
- * Accept, replace, enrich, or block a normalized dispatch result. `next()`
- * accepts it unchanged; thrown tools still reach this seam as errors. Async
- * listeners must observe `exec.signal`; after they settle, caller
- * cancellation replaces only a successful accepted outcome with the code
- * selected by whether the tool body was invoked.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
- * @param exec - the call that just ran (name, parsed arguments, caller agent).
- * @param result - the dispatch outcome a listener may accept, replace, or block.
- * @mode waterfall
- */
-'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
-```
-
-Types: [PostToolDecision](../subsystems/tools.md) · [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
-
-### `tools/pre-execute` — waterfall
-
-Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approval support turns `ask` into denial. Async gates must observe `exec.signal`; the registry rechecks cancellation after they settle but never abandons their promise. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
-
-```ts cordis-catalog
-/**
- * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
- * approval support turns `ask` into denial. Async gates must observe
- * `exec.signal`; the registry rechecks cancellation after they settle but
- * never abandons their promise.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
- * @param exec - the pending call (name, parsed arguments, caller agent).
- * @mode waterfall
- */
-'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
-```
-
-Types: [PreToolDecision](../subsystems/tools.md) · [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
-
-### `tools/result` — emit
-
-Observe the frozen, lossless-JSON final outcome. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
-
-```ts cordis-catalog
-/**
- * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
- * @param exec - the execution object that traversed the pipeline.
- * @param result - a deep-frozen snapshot of the final returned result.
- * @mode emit
- */
-'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
-```
-
-Types: [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
-
-## `workflow/*`
-
-### `workflow/agent-end` — emit
-
-One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start'] by `agent.seq`, exactly once per started call on every stop path — on an engine termination path (a worker killed past its grace) the end is engine-synthesized with outcome `'cancelled'`.
-
-```ts cordis-catalog
-/**
- * One `agent()` call settled (clean result, child failure, or run
- * cancellation). Paired with {@link Events['workflow/agent-start']} by
- * `agent.seq`, exactly once per started call on every stop path — on an
- * engine termination path (a worker killed past its grace) the end is
- * engine-synthesized with outcome `'cancelled'`.
- * @param info - the run's identity snapshot.
- * @param agent - the call identity plus its outcome.
- * @mode emit
- */
-'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:81`](../../packages/workflow/workflow/src/index.ts)
-
-### `workflow/agent-start` — emit
-
-One `agent()` call established a published child run. Paired with Events['workflow/agent-end'] by `agent.seq`. A call that never receives a published run from the provider emits neither event in this pair.
-
-```ts cordis-catalog
-/**
- * One `agent()` call established a published child run. Paired with
- * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
- * receives a published run from the provider emits neither
- * event in this pair.
- * @param info - the run's identity snapshot.
- * @param agent - the call's sequence number, label, phase, and child id.
- * @mode emit
- */
-'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts)
-
-### `workflow/end` — emit
-
-A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves. Paired with Events['workflow/start'].
-
-```ts cordis-catalog
-/**
- * A workflow run settled (any stop reason). Fired when
- * {@link WorkflowRun.result} resolves. Paired with
- * {@link Events['workflow/start']}.
- * @param info - the run's identity snapshot.
- * @param result - the outcome data (stop reason, error, agent count) —
- *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
- * @mode emit
- */
-'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts)
-
-### `workflow/log` — emit
-
-The script emitted a narration line (a `log(message)` call).
-
-```ts cordis-catalog
-/**
- * The script emitted a narration line (a `log(message)` call).
- * @param info - the run's identity snapshot.
- * @param message - the logged message, verbatim.
- * @mode emit
- */
-'workflow/log'(info: WorkflowRunInfo, message: string): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts)
-
-### `workflow/phase` — emit
-
-The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics.
-
-```ts cordis-catalog
-/**
- * The script entered a phase (a `phase(title)` call) — progress grouping
- * for observers; no execution semantics.
- * @param info - the run's identity snapshot.
- * @param title - the phase title, verbatim.
- * @mode emit
- */
-'workflow/phase'(info: WorkflowRunInfo, title: string): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:53`](../../packages/workflow/workflow/src/index.ts)
-
-### `workflow/start` — emit
-
-A workflow run started — the script's meta block validated, the body about to execute. Paired with Events['workflow/end'].
-
-```ts cordis-catalog
-/**
- * A workflow run started — the script's meta block validated, the body
- * about to execute. Paired with {@link Events['workflow/end']}.
- * @param info - the run's identity snapshot (id + meta).
- * @mode emit
- */
-'workflow/start'(info: WorkflowRunInfo): void
-```
-
-Types: [WorkflowRunInfo](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:45`](../../packages/workflow/workflow/src/index.ts)
-
-## Inherited events (cordis core + loader/hmr/timer)
-
-The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier's prominence.
-
-- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:328`](../../vendor/cordis/src/events.ts))
-- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:330`](../../vendor/cordis/src/events.ts))
-- `internal/service` — Interception hook for a service binding (no core producer). ([`vendor/cordis/src/events.ts:332`](../../vendor/cordis/src/events.ts))
-- `internal/update` — Waterfall: a fiber config update is being applied. ([`vendor/cordis/src/events.ts:334`](../../vendor/cordis/src/events.ts))
-- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:336`](../../vendor/cordis/src/events.ts))
-- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:338`](../../vendor/cordis/src/events.ts))
-- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:340`](../../vendor/cordis/src/events.ts))
-- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:342`](../../vendor/cordis/src/events.ts))
-- `hmr/change` — A watched source file changed on disk. ([`vendor/hmr/src/index.ts:20`](../../vendor/hmr/src/index.ts))
-- `hmr/reload` — Plugins are being reloaded after a change. ([`vendor/hmr/src/index.ts:21`](../../vendor/hmr/src/index.ts))
-- `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:23`](../../vendor/loader/src/index.ts))
-- `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:24`](../../vendor/loader/src/index.ts))
-- `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
-- `loader/partial-dispose` — An entry is being partially disposed on reload. ([`vendor/loader/src/index.ts:26`](../../vendor/loader/src/index.ts))
-- `loader/patch-context` — A context is being patched during a reload. ([`vendor/loader/src/index.ts:27`](../../vendor/loader/src/index.ts))
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
deleted file mode 100644
index 88f1762cff..0000000000
--- a/docs/cordis-catalog/services.md
+++ /dev/null
@@ -1,2917 +0,0 @@
-<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
-     Run `pnpm run gen-cordis-catalog` to regenerate. -->
-
-# Cordis Services Catalog
-
-Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.
-
-This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
-
-The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely. Detailed Context, Fiber, Registry, and Service APIs are generated in the [Cordis core API](core/context.md).
-
-## `ctx.agentLoop` — `AgentLoop`
-
-Concrete agent factory and driver service.
-
-```ts cordis-catalog
-/**
- * Create an agent and session under one caller-supplied identity, owned by
- * the accessing fiber. Constructor-driven config calls mint a fresh combined
- * id before entering this boundary.
- * @param id - shared agent/session identity.
- * @param options - concrete loop options.
- * @param meta - optional fresh-session workspace metadata.
- * @returns the published running agent.
- */
-create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent
-
-/**
- * Create an owned agent on a caller-supplied session id.
- * @param ownerCtx - caller context that structurally owns the lifecycle.
- * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
- * @returns the published handle.
- */
-async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
-
-/**
- * Resume an owned agent from the configured persistence service.
- * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
- * @param options - persisted identity, loop options, setup, and cancellation.
- * @returns the published handle.
- */
-async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
-```
-
-Types: [Agent](../subsystems/core.md) · [AgentOptions](../subsystems/core.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md)
-
-Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
-
-## `ctx.agents` — `AgentRegistry`
-
-Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
-
-Initiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.
-
-```ts cordis-catalog
-/**
- * Read the Agent that initiated the inherited asynchronous driver chain.
- * Use this optional form for logging, tracing, metrics, or host attribution
- * that also supports agentless calls. When a parent creates a child, setup
- * reports the causal parent while `agentCtx.agent` identifies the child.
- * @returns the inherited Agent, or `undefined` outside an initiator boundary
- *   and inside an explicit clearing boundary.
- * @throws when this service instance has been disposed.
- */
-currentInitiator(): Agent | undefined
-
-/**
- * Read the initiating Agent and fail when no initiator boundary is active.
- * Use this for private helpers contractually below a driver, or for a
- * deployment-owned outbound request whose contract forbids agentless calls.
- * Generic or direct-call seams use optional lookup or explicit request fields.
- * @returns the inherited Agent.
- * @throws when no initiator is active or this service instance has been disposed.
- */
-requireInitiator(): Agent
-
-/**
- * Run an operation with one exact Agent as its process-local initiator. The
- * exact synchronous value or Promise returned by the operation is preserved.
- * Custom drivers and test harnesses wrap their complete returned foreground
- * lifetime.
- * A queue or wire receiver may establish this boundary only after validating
- * explicit identity and resolving the exact live Agent; this method does neither.
- * Detached work remains owned by the subsystem that starts it.
- * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
- * @param operation - synchronous or asynchronous operation to invoke.
- * @returns the exact value returned by `operation`.
- * @throws when the initiator scope is closing/disposed, or when `operation` throws.
- */
-withInitiator<T>(agent: Agent, operation: () => T): T
-
-/**
- * Run an operation inside a boundary that hides any inherited initiating
- * Agent. The exact synchronous value or Promise is preserved.
- * Use this while creating lazy shared timers, queue pumps, pool maintenance,
- * watchers, or exporters so they do not inherit the first Agent that happens
- * to initialize them. It clears only initiator attribution, not explicit
- * fields, and does not own or drain detached resources.
- * @param operation - synchronous or asynchronous operation to invoke without an initiator.
- * @returns the exact value returned by `operation`.
- * @throws when the initiator scope is closing/disposed, or when `operation` throws.
- */
-withoutInitiator<T>(operation: () => T): T
-
-/**
- * Register the agent-creation factory (the loop calls this on construction,
- * effect-scoped). A traced Cordis service is canonicalized to its concrete
- * target; each create/resume call is then traced through that caller's
- * context so ownership follows the caller without stacking proxy layers.
- * Throws if a factory is already registered. Returns the disposer; on
- * dispose the factory slot is cleared.
- * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
- * @returns the disposer that clears the factory slot. The exact
- *   Cordis effect disposer (single-shot): composite (generator) effects may
- *   yield it directly — exact identity nests the teardown in order.
- */
-setFactory(factory: AgentFactory): () => void
-
-/**
- * Create and publish a new agent through the registered factory.
- * Distinct from {@link register} (which records an already-constructed
- * agent): this constructs the agent and its session. Rejects if no factory is
- * registered or creation/setup fails. The resolved {@link AgentHandle} lets
- * the owner tear down exactly this agent.
- * @param options - shared identity, session seed/metadata, and agent options.
- * @returns the handle after setup, rollback-covered publication, and loop start complete.
- */
-async create(options: CreateAgentOptions): Promise<AgentHandle>
-
-/**
- * Load a persisted session and resume an agent on it through the registered
- * factory. Rejects if no factory is registered; the factory rejects if
- * session persistence is not configured or persistence/setup fails.
- * @param options - persisted identity, configuration, and optional setup.
- * @returns the handle after setup, rollback-covered publication, and loop start complete.
- */
-async resume(options: ResumeAgentOptions): Promise<AgentHandle>
-
-/**
- * Register a live agent. Throws if an agent with the same id is already
- * registered. Emits `agent/created` on registration and `agent/disposed`
- * when the calling fiber is disposed — both with the agent's scope carrier
- * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
- * emits are scope-filtered regardless of which context invoked `register`
- * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
- * requires passing the carrier). Returns the disposer.
- * @param agent - the already-constructed agent to record in the store.
- * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
- *   returns undefined without awaiting an in-flight teardown). Exact
- *   identity is load-bearing: a composite (generator) effect that owns a
- *   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
- *   function so Cordis nests the unregistration at that yield position;
- *   yielding a wrapper would leave it disposing as a concurrent sibling on
- *   owner unload, unregistering the agent (and emitting `agent/disposed`)
- *   while its final turn is still draining.
- */
-register(agent: Agent): () => void
-
-/**
- * Insert an already-constructed agent without announcing it. This is the
- * advanced ordered-lifecycle primitive used by the async agent factory: it
- * first completes setup while the agent is unpublished, then assigns the
- * returned detach closure into its pre-installed composite teardown before
- * calling {@link announce}. Ordinary callers use {@link register}.
- * @param agent - the prepared, unpublished agent.
- * @param owner - live agent whose scoped context created this agent, or
- *   undefined for a top-level runtime root. This is runtime ownership, not
- *   the resumed session's durable parent lineage.
- * @returns an idempotent closure that removes this exact entry and emits
- *   `agent/disposed` with listener failures contained. When called from a
- *   synchronous `agent/created` listener, removal and disposal wait until
- *   that creation dispatch unwinds.
- */
-enter(agent: Agent, owner: Agent | undefined): () => void
-
-/**
- * Announce an agent previously inserted with {@link enter}.
- * @param agent - the live inserted agent to announce.
- * @throws if `agent` is not the exact live registry entry for its id, or its
- *   creation announcement already began (including a reentrant call from a
- *   creation listener).
- */
-announce(agent: Agent): void
-
-/**
- * Look up a live agent.
- * @param id - the shared agent/session id to look up.
- * @returns the agent, or undefined when no live agent has that id.
- */
-get(id: SessionId): Agent | undefined
-
-/**
- * Test whether a live agent was created through one exact parent agent's
- * scoped context. Runtime ownership is independent of durable session
- * lineage and remains unambiguous when unrelated providers reuse an id.
- * @param id - the candidate child agent's shared agent/session id.
- * @param owner - the expected runtime creator agent.
- * @returns true only while the exact child entry is live under that owner.
- */
-isOwnedBy(id: SessionId, owner: Agent): boolean
-
-/**
- * All live agents, in registration order.
- * @returns a fresh array; mutating it does not affect the registry.
- */
-list(): Agent[]
-
-/**
- * All live top-level agents in registration order. A top-level agent was
- * created without an owning agent context; durable session lineage does not
- * affect this runtime relation, so a resumed fork may still be a root.
- * @returns a fresh array; mutating it does not affect the registry.
- */
-roots(): Agent[]
-```
-
-Types: [Agent](../subsystems/core.md) · [SessionId](../subsystems/core.md)
-
-Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
-
-## `ctx.approval` — `ApprovalService`
-
-Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session. It exposes deterministic policy changes to the model through the runtime-context snapshot and switch notices.
-
-```ts cordis-catalog
-/**
- * Switch one live agent's policy and queue the transition for its next model
- * step. Session initialization uses {@link setApprovalPolicy} directly
- * because there is no previously visible policy to change.
- * @param agent - the live agent whose policy is changing.
- * @param policy - the new effective policy.
- */
-setPolicy(agent: Agent, policy: ApprovalPolicy): void
-
-/**
- * Ask the composed answerers to decide one readonly same-process request.
- * The service borrows the request, agent, session, and live signal directly.
- * The request requires an open turn because the audit pair must be enclosed
- * by the durable log's commit/replay boundary; an idle ask rejects before
- * appending anything. The answerer phase always produces an outcome: an
- * aborted signal yields `'cancelled'`, a missing or throwing answerer yields
- * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
- * normalized to `'unavailable'`. A failure that prevents either audit append
- * from committing still rejects because returning an unlogged decision would
- * violate the pair. Session contains post-commit observer failures, so an
- * authoritative append cannot reject the request or suppress its matching
- * audit event.
- * @param req - the pending decision (agent, tool identity, reason, signal).
- * @returns the closed outcome; `'allowed-once'` is the only grant.
- * @throws when no turn is open or either audit event fails before the session
- *   append commit point.
- */
-async request(req: ApprovalRequest): Promise<ApprovalOutcome>
-
-/**
- * Read the session override without applying the configured default.
- * @param session - session whose log supplies the override.
- * @returns the last logged policy, or `undefined` without one.
- */
-overrideOf(session: Session): ApprovalPolicy | undefined
-```
-
-Types: [Agent](../subsystems/core.md) · [ApprovalOutcome](../subsystems/approval.md) · [ApprovalPolicy](../subsystems/approval.md) · [ApprovalRequest](../subsystems/approval.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
-
-## `ctx.bash` — `BashExecutor` (abstract seam)
-
-Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Implementations must honor these semantics:
-
-- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a BashRunResult.
-- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.
-- BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
-- A still-running background process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a background process survives an executor-only reload.
-
-```ts cordis-catalog
-/**
- * Apply implementation-owned defaults and caps to a request before execution.
- * @param request - the caller's request; omitted fields get this
- *   implementation's defaults, capped fields are clamped.
- * @returns the fully-specified spec to hand to {@link run}/{@link start}.
- */
-abstract resolve(request: BashExecRequest): BashExecSpec
-
-/**
- * Run a command in the foreground; resolves when it finishes.
- * @param spec - a resolved spec from {@link resolve}, never a raw request.
- * @returns the outcome; nonzero exits, timeout kills, and abort kills
- *   resolve with a descriptive result rather than reject.
- */
-abstract run(spec: BashExecSpec): Promise<BashRunResult>
-
-/**
- * Start a background process and return its handle immediately.
- * @param spec - a resolved spec from {@link resolve}, never a raw request.
- * @returns the live process handle (reads, kill, quiescence promise).
- */
-abstract start(spec: BashExecSpec): BashProcess
-```
-
-Types: [BashExecRequest](../subsystems/bash.md) · [BashExecSpec](../subsystems/bash.md) · [BashProcess](../subsystems/bash.md) · [BashRunResult](../subsystems/bash.md)
-
-Source: [`packages/bash/bash/src/index.ts:53`](../../packages/bash/bash/src/index.ts)
-
-## `ctx.bashEnv` — `BashEnvRegistry`
-
-Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model shell call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.
-
-```ts cordis-catalog
-/**
- * Register one environment contributor. Names and keys are unique; built-in
- * keys are reserved. Registration is disposed with the calling plugin fiber.
- * @param contributor - declared key ownership and per-execution resolver.
- * @returns the disposer that unregisters the contribution.
- */
-register(contributor: BashEnvContributor): () => void
-
-/**
- * Build the trusted `DSH_*` snapshot for one shell tool execution.
- * @param execution - the current tool execution.
- * @returns an immutable environment overlay containing built-ins and current contributions.
- */
-collect(execution: ToolExecution): DshEnvironment
-
-/**
- * Enumerate plugin-contributed variables without executing their resolvers.
- * @returns declarations sorted by environment variable name.
- */
-list(): BashEnvVariableInfo[]
-```
-
-Types: [DshEnvironment](../subsystems/subprocess.md) · [ToolExecution](../subsystems/tools.md)
-
-Source: [`packages/bash/bash-env/src/index.ts:89`](../../packages/bash/bash-env/src/index.ts)
-
-## `ctx.clientModuleHost` — `ClientModuleHostService`
-
-The web plugin table service: incremental dshClient scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
-
-```ts cordis-catalog
-/**
- * Current composed entry graph (stable object between changes).
- * @returns the graph served as `window.__DSH_BOOT__`.
- */
-graph(): WebBootGraph
-
-/**
- * Absolute path of an entry's client bundle.
- * @param id - entry id (package name).
- * @returns the path, or undefined for an unknown id.
- */
-clientPath(id: string): string | undefined
-
-/**
- * Re-hash one bundle (the HMR watch's registration hook — the only entry
- * point through which bundle content changes reach the graph).
- * @param id - entry id (package name).
- * @returns the new rev, or undefined for an unknown id.
- */
-rebuilt(id: string): string | undefined
-
-/**
- * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
- * @param listener - receives the entry id and its new bundle rev.
- * @returns the unsubscriber.
- */
-onRebuilt(listener: (id: string, rev: string) => void): () => void
-
-/**
- * Fires after any flush that recomposed the graph (row added/removed, or a
- * rebuilt rev change). Pull model: listeners re-read {@link graph}.
- * @param listener - notified with no payload.
- * @returns the unsubscriber.
- */
-onGraphChanged(listener: () => void): () => void
-```
-
-Types: [WebBootGraph](../subsystems/client-modules.md)
-
-Source: [`packages/client/modules/src/index.ts:184`](../../packages/client/modules/src/index.ts)
-
-## `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
-
-Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
-
-```ts cordis-catalog
-/**
- * Execute one program against the request's bindings and capture what it
- * emitted. See the class doc for the resolution contract (error is a result
- * field; rejection means seam misuse only).
- * @param request - the program, its bindings, and the abort signal; the
- *   request carries everything the runtime acts on, with no hidden defaults.
- * @returns the run's outcome: completion value (when transferable), the
- *   ordered log capture, and the failure (if any).
- */
-abstract run(request: CodeRunRequest): Promise<CodeRunResult>
-```
-
-Types: [CodeRunRequest](../subsystems/code-runtime.md) · [CodeRunResult](../subsystems/code-runtime.md)
-
-Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
-
-## `ctx.commands` — `CommandService`
-
-Human-command registry. Plain-context definitions are global; definitions registered through a command-injected child of an agent context shadow globals for that agent.
-
-```ts cordis-catalog
-/**
- * Register a global or calling-agent-scoped command.
- * @param definition - discovery metadata and direct UI handler.
- * @returns the exact effect disposer that unregisters this definition.
- */
-register(definition: CommandDefinition): () => void
-
-/**
- * List the effective immutable command descriptors for one agent.
- * @param agent - exact receiving agent and scoped-layer key.
- * @returns name-sorted descriptors after scoped shadowing.
- */
-list(agent: Agent): readonly CommandDescriptor[]
-
-/**
- * Resolve one effective command definition.
- * @param agent - exact receiving agent and scoped-layer key.
- * @param name - command name without a slash.
- * @returns the scoped shadow or global definition.
- */
-find(agent: Agent, name: string): CommandDefinition | undefined
-
-/**
- * Parse and execute a known command without sending it to the model.
- *
- * A resolved command's lifecycle is logged: `command/run` is appended
- * before the handler is invoked and `command/done` after settlement (a
- * thrown or aborted handler settles as `kind: 'error'`). Both are direct
- * log-only appends — no turn wraps them, and persistence drains them at
- * ordinary checkpoints. Admission misses (syntax or unknown name) log
- * nothing — they never entered a handler. A `command/run` append failure
- * fails the execution loud; a `command/done` append failure on the
- * handler-failure path is contained so the handler's own error stays the
- * reported failure.
- *
- * @param agent - exact receiving agent.
- * @param line - complete slash-command line.
- * @param signal - cancellation signal owned by the UI request.
- * @returns the settled execution (result + lifecycle pairing id), or
- *   `undefined` when syntax or name does not resolve.
- */
-async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>
-```
-
-Types: [Agent](../subsystems/core.md) · [CommandDefinition](../subsystems/commands.md) · [CommandDescriptor](../subsystems/commands.md)
-
-Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
-
-## `ctx.compact` — `CompactService` (abstract seam)
-
-Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
-
-```ts cordis-catalog
-/**
- * Consider automatic compaction for one explicit trigger. Pressure policy
- * uses the latest durable routed request, while context-overflow policy may
- * force a useful balanced reduction even below the normal threshold. Return
- * `null` when no safe range can be compacted. A single oversized retained
- * unit or request envelope cannot be repaired through surface compaction.
- *
- * @param agent - agent context owning the session surface and routing options.
- * @param trigger - normal pressure or provider-confirmed context overflow.
- * @param signal - cancellation signal; model-backed implementations must forward it.
- * @returns the compaction result, or `null` if no compaction was needed.
- */
-abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise<CompactionResult | null>
-
-/**
- * Explicitly compact useful history even below automatic pressure thresholds.
- * Implementations synchronously start an idle task before any asynchronous
- * work, select a useful range without writing on a no-op, then
- * append a standalone `compact/start` before summarization. That durable
- * marker is the compaction lock until one `compact/end` attempt. Later waking
- * prompts remain accepted in FIFO order and start only after the optional
- * durability checkpoint and idle-task settlement. Context injected while the
- * summary runs may sit between the marker pair; only the selected span must
- * remain stable.
- *
- * @param agent - idle agent whose durable history should be compacted.
- * @param signal - cancellation scoped to this compaction request.
- * @returns the compaction result, or `null` when no safe useful range exists.
- * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
- * changed-span, summarization/shrink, commit-stage, or persistence failures;
- * an aborted request preserves its exact abort reason. Failed attempts remain
- * visible in the log.
- */
-abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>
-
-/**
- * Forcibly compact a range of surface nodes into a single summary node.
- * `start` and `end` name an inclusive span by surface position, not numeric seq
- * order; replacements can make visible seqs non-monotonic. Both edges must be
- * balanced so assistant tool calls remain paired with their results. A model-
- * backed implementation forwards cancellation and rejects active, missing,
- * reversed, or unbalanced ranges. The target session is `agent.session`.
- * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
- * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
- * for the edge checks.
- *
- * @param start - first surface seq, inclusive.
- * @param end - last surface seq, inclusive.
- * @param agent - context whose session is mutated and whose routing options guide summarization.
- * @param signal - optional cancellation; model-backed implementations must forward it.
- * @throws when compaction is active or the range is missing, reversed, or unbalanced.
- * @returns the appended event seqs, summary, replaced range, and token accounting.
- */
-abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
-```
-
-Types: [CompactionResult](../subsystems/compaction.md) · [CompactionTrigger](../subsystems/compaction.md)
-
-Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
-
-## `ctx.credentials` — `Credentials` (abstract seam)
-
-Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
-
-```ts cordis-catalog
-/**
- * Resolve one reference to its current value. Resolution is per call:
- * consumers re-resolve at each operation and must not cache across
- * operations — that per-operation read is what makes a changed credential
- * reach the next operation without a restart.
- * @param ref - the reference to resolve.
- * @returns the value and its source, or `undefined` while unconfigured.
- */
-abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>
-
-/**
- * Describe one reference for configuration surfaces without exposing the
- * value.
- * @param ref - the reference to describe.
- * @returns configured state, supplying source, and writability.
- */
-abstract describe(ref: CredentialRef): Promise<CredentialInfo>
-
-/**
- * Durably store one value in the provider-managed writable source. Rejects
- * while a read-only source shadows the reference — the write would appear
- * to succeed while resolution keeps returning the shadowing value — and
- * rejects an empty value (use {@link unset}).
- * @param ref - the reference to store.
- * @param value - the non-empty secret value.
- */
-abstract set(ref: CredentialRef, value: string): Promise<void>
-
-/**
- * Remove one reference from the provider-managed writable source; removing
- * an absent reference is a no-op. Rejects while a read-only source shadows
- * the reference, like {@link set}.
- * @param ref - the reference to remove.
- */
-abstract unset(ref: CredentialRef): Promise<void>
-```
-
-Types: [CredentialInfo](../subsystems/credentials.md) · [CredentialRef](../subsystems/credentials.md) · [ResolvedCredential](../subsystems/credentials.md)
-
-Source: [`packages/credentials/credentials/src/index.ts:77`](../../packages/credentials/credentials/src/index.ts)
-
-## `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
-
-Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
-
-```ts cordis-catalog
-/**
- * The backend's interaction capability.
- * @returns the discriminated capability consumers switch on.
- */
-abstract capability(): DirectoryPickerCapability
-```
-
-Source: [`packages/host/directory-picker/src/index.ts:131`](../../packages/host/directory-picker/src/index.ts)
-
-## `ctx.e2b` — `E2BSandboxService`
-
-Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal. Creation begins at plugin construction; adapters await getSandbox before their first operation.
-
-```ts cordis-catalog
-/**
- * Return the shared live SDK handle.
- * @returns the created sandbox after the configured cwd exists.
- * @throws when E2B rejects creation or the service is disposing.
- */
-async getSandbox(): Promise<Sandbox>
-```
-
-Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
-
-## `ctx.fs` — `FileSystem` (abstract seam)
-
-Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
-
-```ts cordis-catalog
-/**
- * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
- * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
- * async even though the local backend only normalizes + realpaths.
- *
- * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
- * @param opts - optional cwd override and cancellation signal.
- * @returns the stable target; the same file yields the same `targetKey`.
- */
-abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
-
-/**
- * Return the canonical absolute path a subprocess in this filesystem's
- * execution world can open. The path is deliberately separate from
- * {@link FsTarget.targetKey}: consumers may pass this value to another OS
- * capability, but must continue treating the target key as opaque.
- * @param target - the resolved target whose process path is required.
- * @returns an absolute path in the backend's execution world.
- */
-abstract processPath(target: FsTarget): string
-
-/**
- * Return the canonical `file:` URI for a target in this filesystem's
- * execution world. Backends own URI encoding because the host platform may
- * differ from the execution platform.
- * @param target - the resolved target to encode.
- * @returns the target's canonical file URI.
- */
-abstract fileUrl(target: FsTarget): string
-
-/**
- * Test canonical containment without exposing or parsing backend target
- * keys. Both targets must come from this provider.
- * @param parent - canonical directory target.
- * @param child - canonical candidate target.
- * @returns true when `child` is `parent` or a descendant of it.
- */
-abstract contains(parent: FsTarget, child: FsTarget): boolean
-
-/**
- * Return target metadata, or `undefined` when the target does not exist.
- * @param target - the resolved target to stat.
- * @param signal - aborts the metadata round-trip.
- * @returns metadata only, never content; undefined for an absent target.
- */
-abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
-
-/**
- * Return path metadata without following the final path component when it is a
- * symbolic link. This is intentionally path-shaped, not target-shaped:
- * {@link resolve} follows symlinks to produce the stable identity used by
- * normal reads/writes, while `lstat` lets a consumer reject the path itself
- * before that follow happens.
- *
- * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
- * absent.
- * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
- * @param opts - `cwd` overrides the backend's default base for relative paths.
- * @param signal - aborts the metadata round-trip.
- * @returns metadata only, never content; undefined for an absent path.
- */
-abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
-
-/**
- * Read the whole regular text file as a single decoded string.
- * @param target - the resolved target to read.
- * @param signal - aborts the read.
- * @returns the full decoded UTF-8 content.
- */
-abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
-
-/**
- * Stream the whole regular text file as decoded text chunks (same text
- * semantics as {@link readText}, for large files). The backend owns
- * cross-chunk UTF-8 decoding and binary rejection so the policy layer never
- * touches raw bytes.
- * @param target - the resolved target to read.
- * @param signal - aborts the stream, including between chunks.
- * @returns the chunk iterable, decoded and validated like {@link readText}.
- */
-abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
-
-/**
- * List direct children of a directory in stable name order. Returns resolved
- * child targets plus cheap metadata only; never reads file contents.
- * @param target - the resolved directory target.
- * @param signal - aborts the listing.
- * @returns one entry per direct child, in stable name order.
- */
-abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
-
-/**
- * Atomically create or replace UTF-8 text. `expected` guards intent and
- * staleness; omission allows unconditional overwrite.
- * @param target - the resolved target to write.
- * @param content - the full new file content.
- * @param expected - the write intent guarding the write; omit for unconditional.
- * @param signal - aborts before the atomic rename takes effect.
- * @param sandboxPolicy - the per-call mode and workspace root this write
- *   runs under; a sandboxing backend fences the write by it, the bare backend
- *   ignores it. Omit to leave the backend its own default.
- * @returns the outcome, including the version the write produced.
- */
-abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>
-
-/**
- * Atomically edit literal text. When supplied, the version guard is checked
- * before matching so stale content reports `FS_STALE_VERSION`; omission edits
- * the current content without a freshness precondition.
- * @param target - the resolved target to edit.
- * @param edit - the literal search/replace request.
- * @param expected - the version guard; omit for an unconditional edit.
- * @param signal - aborts before the atomic rename takes effect.
- * @param sandboxPolicy - the per-call mode and workspace root this edit runs
- *   under; a sandboxing backend fences the edit by it, the bare backend
- *   ignores it. Omit to leave the backend its own default.
- * @returns the outcome, including the version the edit produced.
- */
-abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>
-```
-
-Types: [FsDirEntry](../subsystems/filesystem.md) · [FsEditOutcome](../subsystems/filesystem.md) · [FsEditRequest](../subsystems/filesystem.md) · [FsInfo](../subsystems/filesystem.md) · [FsPathInfo](../subsystems/filesystem.md) · [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md) · [FsWriteIntent](../subsystems/filesystem.md) · [FsWriteOutcome](../subsystems/filesystem.md) · [SandboxExecutionPolicy](../subsystems/sandbox.md)
-
-Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
-
-## `ctx.goals` — `GoalService`
-
-Goal service (`ctx.goals`) backed exclusively by the owning session log.
-
-```ts cordis-catalog
-/**
- * Read the current goal for one exact live agent.
- * @param agent - owning live agent.
- * @returns a fresh view or `undefined` when no goal is current.
- * @throws {@link GoalError} when the agent is not the registry's live instance.
- */
-get(agent: Agent): GoalView | undefined
-
-/**
- * Remove process-local continuation authority without changing durable goal
- * phase or revision. Lifecycle owners use this before unloading a driver;
- * a later human-authorized {@link resume} records the new activation edge.
- * @param agent - owning live agent.
- * @returns a fresh disarmed view, or `undefined` when no goal is current.
- */
-disarm(agent: Agent): GoalView | undefined
-
-/**
- * Create and arm a goal. A completed goal may be replaced; every other
- * current phase must be cleared or resumed instead.
- * @param agent - owning live agent.
- * @param request - objective and optional round cap.
- * @returns the created live view.
- */
-create(agent: Agent, request: CreateGoalRequest): GoalView
-
-/**
- * Edit objective and/or round cap without changing phase.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @param request - at least one replacement field.
- * @returns the edited view.
- */
-@Remote('edit') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
-
-/**
- * Pause an active goal and disarm automatic continuation.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @returns the paused view.
- */
-@Remote('pause') pause(agent: Agent, ref: GoalRef): GoalView
-
-/**
- * Resume and arm a stopped goal, or rearm an active goal after a
- * session-start edge, while its round budget still has capacity.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @returns the active view.
- */
-@Remote('resume') resume(agent: Agent, ref: GoalRef): GoalView
-
-/**
- * Mark a current non-complete goal complete and disarm it.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @returns the completed view.
- */
-@Remote('complete') complete(agent: Agent, ref: GoalRef): GoalView
-
-/**
- * Mark an active goal blocked and disarm it.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @param reason - policy-owned stable code and human-readable explanation.
- * @returns the blocked view with its durable reason.
- */
-block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
-
-/**
- * Clear the current goal while retaining a durable tombstone and history.
- * @param agent - owning live agent.
- * @param ref - expected current revision.
- * @returns the tombstone ref whose revision is one past the cleared snapshot.
- */
-@Remote('clear') clear(agent: Agent, ref: GoalRef): GoalRef
-
-/**
- * Create one Goal through the remote boundary.
- * @param agent - exact live Agent resolved from the wire identity.
- * @param request - objective and optional round cap.
- * @returns the created Goal identity.
- */
-@Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
-```
-
-Types: [Agent](../subsystems/core.md) · [CreateGoalRequest](../subsystems/goal.md) · [CreateGoalResult](../subsystems/goal.md) · [EditGoalRequest](../subsystems/goal.md) · [GoalBlockReason](../subsystems/goal.md) · [GoalRef](../subsystems/goal.md) · [GoalView](../subsystems/goal.md)
-
-Source: [`packages/goal/goal/src/index.ts:183`](../../packages/goal/goal/src/index.ts)
-
-## `ctx.httpServer` — `HttpServerService`
-
-The web-shape HTTP carrier service. Activation listens immediately (route registration order carries no request-facing semantics: named routes are composed to be disjoint, and the fallback seat answers anything not yet claimed during the boot window — 404 until its owner registers). A listen failure throws out of init — a FAILED fiber the boot's fail-loud sweep reports.
-
-```ts cordis-catalog
-/**
- * Register a named route. Duplicate (kind, path) throws — route patterns are
- * a composition-level contract, so a collision is a misconfiguration.
- * @param route - kind, path, and the owning handler.
- * @returns the disposer removing the route.
- */
-register(route: WebRoute): () => void
-
-/**
- * Register an exact-path HTTP upgrade route. Duplicate paths throw because
- * one socket can have only one protocol owner.
- * @param route - pathname and handler owning negotiation plus socket use.
- * @returns the disposer removing the route.
- */
-registerUpgrade(route: WebUpgradeRoute): () => void
-
-/**
- * Claim the fallback seat: the handler answering every request no named
- * route matches (the SPA dist server in the shipped Web composition). One
- * owner only — a second registration throws, because two fallbacks cannot
- * compose.
- * @param handler - owns the full response lifecycle of unmatched requests.
- * @returns the disposer releasing the seat.
- */
-registerFallback(handler: WebRoute['handler']): () => void
-
-/**
- * Register an index.html transform, applied by the fallback owner to every
- * index response ({@link applyIndexTaps}) in registration order.
- * @param transform - pure html-to-html function.
- * @returns the disposer removing the transform.
- */
-tapIndex(transform: (html: string) => string): () => void
-
-/**
- * Run an index.html body through the registered taps in registration order
- * — called by the fallback owner on every index response it renders.
- * @param html - the raw index.html body.
- * @returns the transformed body.
- */
-applyIndexTaps(html: string): string
-```
-
-Types: [WebRoute](../subsystems/http-server.md)
-
-Source: [`packages/host/webserver/src/index.ts:60`](../../packages/host/webserver/src/index.ts)
-
-## `ctx.invariants` — `InvariantService`
-
-Package-owned invariant registry with global and regex-based selection.
-
-```ts cordis-catalog
-/**
- * Register one package's invariant installer. The package name is reserved
- * even when filtering disables its checks. Enabled installers run in a child
- * fiber; failure disposes that fiber and releases the reservation.
- * @param packageName - full npm package name that owns the contribution.
- * @param installer - listener or startup-check installer for the child context.
- * @returns an effect-scoped disposer for the registration.
- */
-register(packageName: string, installer: InvariantInstaller): () => void
-```
-
-Types: [InvariantInstaller](../subsystems/invariants.md)
-
-Source: [`packages/support/invariants/src/index.ts:94`](../../packages/support/invariants/src/index.ts)
-
-## `ctx.llm` — `LlmService`
-
-The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
-
-```ts cordis-catalog
-/**
- * Register an adapter for the given provider routes. Throws `LlmError` with code
- * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).
- * Disposed with the fiber.
- * @param providers - every provider route this adapter should serve.
- * @param adapter - the adapter that streams calls for those providers.
- * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
- */
-registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle
-
-/**
- * Describe provider routes with a registered adapter.
- * @returns detached provider metadata in registration order.
- */
-listProviders(): LlmProviderInfo[]
-
-/**
- * Declare provider routes an adapter plugin can activate through
- * configuration. Registration is all-or-nothing: an empty list, invalid
- * entry, or a provider already declared by any registration throws
- * `LlmError` without registering the rest. Disposed with the fiber.
- * @param entries - every configurable provider this plugin owns.
- * @returns a handle that withdraws all of them, and can atomically replace them.
- */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
-
-/**
- * List every declared configurable provider, registered or dormant.
- * @returns detached directory entries in declaration order.
- */
-listConfigurableProviders(): LlmConfigurableProvider[]
-
-/**
- * Offer to interrogate provider endpoints on behalf of the settings
- * namespace this plugin owns. The namespace is the key because that is what
- * a configuration surface already holds from the configurable-provider
- * directory, and because a provider being *added* has no route to name yet.
- * Disposed with the fiber.
- * @param settingsNs - the namespace whose profiles this discovery serves.
- * @param discover - interrogates one endpoint; must honor `request.signal`.
- * @returns the disposer that withdraws the offer.
- */
-registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
-
-/**
- * Interrogate one provider endpoint for the models it advertises. The
- * request describes a draft, not a stored route, so nothing here reads or
- * writes settings or credentials — the caller owns both, and the reply is
- * candidate metadata a surface may offer for adoption.
- * @param settingsNs - namespace whose registered discovery serves this draft.
- * @param request - the endpoint, protocol, and one-shot credential to use.
- * @returns the advertised models, deduplicated in endpoint order.
- */
-async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
-
-/**
- * Resolve the retry policy captured when one provider route was registered.
- * @param provider - registered provider route to inspect.
- * @returns the provider-owned policy, with normal defaults already resolved.
- */
-providerRetryPolicy(provider: string): ResolvedRetryPolicy
-
-/**
- * Discover models advertised by one registered provider. Catalog membership
- * is advisory and never changes routing or request validation.
- * @param provider - registered provider route to inspect.
- * @returns detached model metadata in adapter-preferred order.
- */
-async listModels(provider: string): Promise<LlmModelInfo[]>
-
-/**
- * Resolve and validate all metadata from the adapter that owns one exact
- * route. The result is detached from adapter-owned objects; catalog
- * membership remains advisory and does not control request routing.
- * @param provider - registered provider route to inspect.
- * @param model - exact model id passed to the adapter.
- * @param signal - optional cancellation for adapter-owned asynchronous lookup.
- * @returns exact model identity plus available context and reasoning metadata.
- */
-async resolveModelInfo( provider: string, model: string, signal?: AbortSignal, ): Promise<LlmResolvedModelInfo>
-
-/**
- * Validate a conversation call config against its exact model capability and
- * materialize adapter-configured defaults. Unsupported explicit efforts
- * reject before provider I/O; no clamping or aliasing is performed. This
- * standalone query does not bind a later dispatch; use {@link prepareCall}
- * when logging and streaming must share one adapter registration.
- * @param config - provider/model route and optional request controls.
- * @param signal - optional cancellation for adapter-owned capability lookup.
- * @returns a detached config only when a default must be materialized.
- */
-async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>
-
-/**
- * Resolve one call under its current adapter registration. The returned
- * one-shot handle keeps that registration across header logging and dispatch,
- * so HMR cannot combine one adapter's capability result with another adapter.
- * @param config - provider/model route and optional request controls.
- * @param signal - optional cancellation for adapter-owned capability lookup.
- * @returns a prepared config and its registration-bound stream entry point.
- */
-async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
-
-/**
- * Stream one model call as raw chunks (token-level deltas). Replay state is
- * retained only when the same adapter instance owns its historical provider
- * and the target provider. Final adapter selection remains fixed through
- * asynchronous exact-model resolution and dispatch. Adapter selection,
- * dispatch, and iteration failures become terminal `error` or `aborted`
- * finish chunks; middleware, nested-call, cleanup, and consumer failures
- * remain thrown.
- * @param options - the full request; `options.provider` selects the adapter.
- * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
- */
-stream(options: GenerateOptions): AsyncIterable<StreamChunk>
-```
-
-Types: [AdapterRegistrationHandle](../subsystems/core.md) · [DirectoryRegistrationHandle](../subsystems/core.md) · [GenerateOptions](../subsystems/core.md) · [LlmAdapter](../subsystems/llm-streaming.md) · [LlmCallConfig](../subsystems/core.md) · [LlmConfigurableProvider](../subsystems/core.md) · [LlmDiscoveredModel](../subsystems/core.md) · [LlmModelDiscoveryRequest](../subsystems/core.md) · [LlmModelInfo](../subsystems/core.md) · [LlmProviderInfo](../subsystems/core.md) · [LlmResolvedModelInfo](../subsystems/core.md) · [PreparedLlmCall](../subsystems/llm-streaming.md) · [ResolvedRetryPolicy](../subsystems/llm-streaming.md) · [StreamChunk](../subsystems/llm-streaming.md)
-
-Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
-
-## `ctx.permission` — `PermissionService`
-
-Owns the deployment's permission presets and their write path. Requires a confining `ctx.bash` executor and `ctx.approval`; unmatched knob values are reported as CUSTOM_PRESET, not an error.
-
-```ts cordis-catalog
-/**
- * Resolve the preset matching the effective knob values. A still-matching
- * last selection wins shared-bundle ties; otherwise the first table match
- * wins, or {@link CUSTOM_PRESET} when no entry matches.
- * @param events - the session's events in log order.
- * @returns the effective preset name, or `custom` when nothing matches.
- */
-current(events: readonly SessionEvent[]): string
-
-/**
- * Build the whole select value for one folded knob state: every table
- * option in declaration order, `custom` appended exactly while derived.
- * @param state - the folded knob overrides.
- * @returns the `permissions` projection payload.
- */
-selectFor(state: KnobState): PermissionSelect
-
-/**
- * Resolve a preset's knob bundle.
- * @param name - the preset name to resolve.
- * @returns the configured bundle.
- * @throws when `name` is not in the table.
- */
-resolve(name: string): PresetSpec
-
-/**
- * Build the client option for a table entry or {@link CUSTOM_PRESET}. A
- * missing label falls back to the table key.
- * @param name - a table key, or `custom`.
- * @returns the option a client renders.
- * @throws when `name` is neither a table key nor `custom`.
- */
-optionOf(name: string): PresetOption
-
-/**
- * Record a changed preset, then update each changed knob through its own
- * setter. Selecting the effective preset again appends nothing.
- * @param session - the session the switch belongs to.
- * @param name - the preset to switch to; unknown names throw.
- */
-set(session: Session, name: string): void
-```
-
-Types: [PresetOption](../subsystems/permission.md) · [PresetSpec](../subsystems/permission.md) · [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
-
-Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
-
-## `ctx.planMode` — `PlanModeService`
-
-`ctx.planMode`: owns logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool. UIs observe committed flips through `session/event`; there is no live mirror.
-
-```ts cordis-catalog
-/**
- * Read the logged plan state and any selected state awaiting a boundary.
- *
- * @param agent The agent to read.
- * @returns Current logged state plus a pending selection, when present.
- */
-get(agent: Agent): { active: boolean; pending?: boolean }
-
-/**
- * Select whether plan mode should be active. Between turns the change
- * commits immediately — no request boundary would arrive until the next
- * prompt, so a queued intent would hang (the open-turn fold is the idle
- * signal: agent status stays `running` through post-turn checkpointing,
- * where a boundary equally never comes). During an open turn the
- * selection is held as pending intent for the next in-turn request
- * boundary. Repeated selection of the current or already-pending state is
- * a no-op.
- *
- * @param agent The agent to switch.
- * @param active Whether plan mode should be active.
- * @returns what happened: `committed` (logged now), `queued` (awaiting the
- * next boundary), `cancelled` (an opposite pending selection was cleared;
- * the logged state already matches), or `noop` (already in that state).
- */
-set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
-```
-
-Types: [Agent](../subsystems/core.md)
-
-Source: [`packages/plan/plan-mode/src/index.ts:183`](../../packages/plan/plan-mode/src/index.ts)
-
-## `ctx.pty` — `PtyService`
-
-In-process registry for replaceable PTY backends and exact-Agent sessions.
-
-```ts cordis-catalog
-/**
- * Register one backend type for this effect scope.
- * @param backend - provider with a non-empty unique type.
- * @returns disposer that removes exactly this contribution.
- */
-registerBackend(backend: PtyBackend): () => void
-
-/**
- * List registered backend types in registration order.
- * @returns fresh backend type names.
- */
-listBackends(): string[]
-
-/**
- * Create and publish one owner-scoped session after backend setup succeeds.
- * @param owner - exact registered Agent that owns access and cleanup.
- * @param request - backend type plus optional owner-local name and cwd.
- * @param signal - cancellation of unpublished setup.
- * @returns published identity, metadata, status, and MOTD.
- */
-async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult>
-
-/**
- * Test whether an exact owner has a published session or unpublished spawn.
- * @param owner - exact live owner to inspect.
- * @returns true across the entire spawn-to-close interval, with no publication gap.
- */
-hasOwnerActivity(owner: Agent): boolean
-
-/**
- * Start one exclusive interactive send.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param request - explicit text, submit behavior, and cancellation.
- * @returns live operation handle for foreground await or task registration.
- */
-startSend(owner: Agent, id: PtySessionId, request: PtySendRequest): PtySendOperation
-
-/**
- * Read one bounded scrollback page from an owned session.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param request - optional newest-relative offset and line count.
- * @returns bounded retained text and pagination metadata.
- */
-read(owner: Agent, id: PtySessionId, request: PtyReadRequest = {}): PtyReadResult
-
-/**
- * Deliver an allowed signal through an owned backend session.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param signal - allowed POSIX signal name.
- * @returns delivered foreground process-group identity.
- */
-signal(owner: Agent, id: PtySessionId, signal: PtySignal): Promise<PtySignalResult>
-
-/**
- * Close one owned session and remove it only after quiescent backend cleanup.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param reason - diagnostic cleanup reason.
- * @returns true for a newly closed session, false when the same close is already in flight.
- */
-async kill(owner: Agent, id: PtySessionId, reason: string = 'model request'): Promise<boolean>
-
-/**
- * List fresh snapshots for exactly one owner.
- * @param owner - exact owner whose sessions are visible.
- * @returns owner-visible snapshots in publication order.
- */
-list(owner: Agent): PtySessionSnapshot[]
-```
-
-Types: [Agent](../subsystems/core.md) · [PtyBackend](../subsystems/pty.md) · [PtyReadRequest](../subsystems/pty.md) · [PtyReadResult](../subsystems/pty.md) · [PtySendOperation](../subsystems/pty.md) · [PtySendRequest](../subsystems/pty.md) · [PtySessionId](../subsystems/pty.md) · [PtySessionSnapshot](../subsystems/pty.md) · [PtySignal](../subsystems/pty.md) · [PtySignalResult](../subsystems/pty.md) · [PtySpawnRequest](../subsystems/pty.md) · [PtySpawnResult](../subsystems/pty.md)
-
-Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
-
-## `ctx.sandbox` — `SandboxProvider` (abstract seam)
-
-Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
-
-```ts cordis-catalog
-/**
- * Wrap `argv` so it executes confined under `policy` on this host; the
- * caller spawns the returned argv in place of its own.
- * @param argv - the exact argv the caller is about to spawn (program plus
- *   arguments), NOT a shell string — a shell-shaped consumer passes
- *   `['bash', '-c', command]`.
- * @param policy - the file-effect policy this execution runs under,
- *   carried per call (see {@link SandboxPolicy}).
- * @returns the argv to spawn instead, plus the enforcement completeness
- *   the selected backend achieves for it.
- */
-abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv
-```
-
-Types: [ConfinedArgv](../subsystems/sandbox.md) · [SandboxPolicy](../subsystems/sandbox.md)
-
-Source: [`packages/sandbox/sandbox/src/index.ts:148`](../../packages/sandbox/sandbox/src/index.ts)
-
-## `ctx.sandboxPolicy` — `SandboxPolicyService`
-
-The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode, fallback workspace root, and current request-time policy section. Tool layers call resolve for each execution so a session's mode log and immutable cwd travel together to every enforcing capability.
-
-```ts cordis-catalog
-/**
- * Resolve the complete policy for one capability call. An approved explicit
- * mode outranks the session's last `sandbox/mode` event, which outranks the
- * deployment default. A session cwd is its workspace-write boundary; the
- * configured root is the fallback for agentless calls and sessions without a
- * cwd.
- * @param request - optional session and approved mode override.
- * @returns the fully resolved per-call mode and absolute workspace root.
- */
-resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
-
-/**
- * Read the session override without applying the deployment default.
- * @param session - session whose log supplies the override.
- * @returns the last logged mode, or `undefined` without one.
- */
-overrideOf(session: Session): SandboxMode | undefined
-```
-
-Types: [SandboxExecutionPolicy](../subsystems/sandbox.md) · [SandboxMode](../subsystems/sandbox.md) · [SandboxPolicyRequest](../subsystems/sandbox.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/sandbox/sandbox-policy/src/index.ts:91`](../../packages/sandbox/sandbox-policy/src/index.ts)
-
-## `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
-
-Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
-
-```ts cordis-catalog
-/**
- * Resolve this backend's independent local artifact for a session without
- * reading, creating, flushing, or otherwise materializing it. Backends such
- * as SQLite that do not own one artifact per session return `undefined`.
- * @param meta - the immutable session header whose artifact is requested.
- * @returns the backend-specific absolute location, when one exists.
- */
-abstract locate(meta: SessionHeader): SessionLocation | undefined
-
-/**
- * Register a new session's metadata. A backend MAY defer the physical write
- * until the first {@link append} (lazy materialization), in which case a
- * created-but-never-appended session is absent from {@link list}
- * — abandoned sessions leave nothing behind.
- * @param meta - the immutable header (id, version, cwd, lineage) to record.
- */
-abstract create(meta: SessionHeader): Promise<void>
-
-/**
- * Durably persist a batch of events. Honors the append-only and contiguous-
- * seq contracts: the first event's `seq` MUST equal the stored next-seq
- * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
- * serializable `event.data` with an error naming the offending event type.
- * @param id - the session the batch belongs to.
- * @param events - the contiguous batch to persist, in seq order.
- */
-abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
-
-/**
- * Prepare the exact unpublished Session used by resume. Implementations may
- * reuse object graphs retained by an earlier {@link inspect} after confirming
- * their durable revision is still current; disposal releases an unpublished
- * reservation. Revision retries require the durable log to remain unchanged
- * for one read/check round trip; continuous external writers may delay completion.
- * @param id - persisted session to prepare.
- * @param signal - optional cancellation for preparation work.
- * @returns one owned unpublished Session preparation.
- */
-async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>
-
-/**
- * Load an immutable balanced logical view and commit any required cold
- * recovery. A complete interrupted final turn is preserved and durably
- * closed with missing tool errors plus any open step and turn boundaries;
- * only a torn final record is discarded. Unknown versions and corruption in
- * the committed prefix reject. Implementations MUST NOT crash-repair an
- * identity still bound to a live Session: a balanced live log may return as a
- * durable snapshot, while an open live turn rejects. Returned values may be
- * shared with immutable live or prepared state and must not be mutated.
- * Revision-based implementations may wait for one stable read/check round trip.
- * @param id - the persisted session to reload.
- * @returns the header and a log ending on a balanced `turn/end`.
- */
-abstract load(id: SessionId): Promise<SessionInspection>
-
-/**
- * Inspect an immutable logical session without committing recovery or
- * publishing it. A cold complete interrupted turn receives synthetic closers
- * in memory and a torn physical tail remains untouched. An already-live
- * Session instead yields its current immutable snapshot, which may contain an
- * open turn and its `session/end-seed` boundary. Coordinator-backed
- * implementations retain the exact cold unpublished Session for bounded
- * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
- * already committing or reserved for resume remains exclusive, and inspection
- * may borrow its immutable view. Callers borrow only the immutable header and
- * log. Continuous external writers may delay revision convergence.
- * @param id - the persisted session to inspect.
- * @param signal - optional cancellation for queued and backend read work.
- * @returns the validated header and current logical event log.
- */
-abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
-
-/**
- * Read the stored events from `fromSeq` onward — the read-from-seq
- * primitive for read models that resume from a watermark (e.g. a persisted
- * projection cache folding only the tail past its checkpoint). Unlike
- * {@link inspect}, it is a detached physical suffix read: no preparation
- * cache, torn-tail truncation, synthetic closers, or coordinator-state
- * publication. Only events from the valid contiguous stored prefix are
- * returned, so a torn fragment never reaches the caller. `fromSeq` at or
- * beyond the stored prefix returns an empty event list (never an error).
- * Backends whose medium can seek by seq
- * (SQLite) read only the suffix; sequential media (JSONL, both encodings)
- * still parse the whole artifact and skip forward — the primitive bounds
- * what is RETURNED and refolded, not every backend's physical read.
- * @param id - the persisted session to read.
- * @param fromSeq - first event seq to include; a non-negative safe integer.
- * @param signal - optional cancellation for queued and backend read work.
- * @returns the header and the stored events with `seq >= fromSeq`.
- */
-abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
-
-/**
- * Lightweight listing from metadata, without a full-log parse.
- * @param signal - optional cancellation for backend listing work.
- * @returns one header per materialized session.
- */
-abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
-
-/**
- * List materialized sessions with cheap per-log change tokens.
- *
- * Repeated observations of an unchanged log return the same revision. A
- * successful mutating {@link load} repair changes the next listed revision.
- * Revisions also distinguish independently backed stores so backend-local
- * counters cannot compare equal across different persistence sources.
- * @param signal - optional cancellation for backend snapshot-listing work.
- * @returns one header and opaque revision per materialized session without loading full logs.
- */
-abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
-```
-
-Types: [SessionEvent](../subsystems/core.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md) · [SessionInspection](../subsystems/persistence.md) · [SessionLocation](../subsystems/persistence.md) · [SessionPersistenceSnapshot](../subsystems/persistence.md) · [SessionPreparation](../subsystems/persistence.md)
-
-Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
-
-## `ctx.sessionProjectionCache` — `SessionProjectionCache`
-
-The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus two mandatory points — `turn/end` and session disposal (the live-to-cold moment) — and serves the cold-read ladder: cached row, persistence `readFrom` tail, registry `restore`, durable write-back. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write or cold read.
-
-```ts cordis-catalog
-/**
- * The zero-I/O listing read: whole values viewed straight from the stored
- * rows (version-matching keys only), each cut carried with its watermark
- * so a client value store can seed under its higher-seq-wins rule — as
- * stale as the last durable checkpoint but never wrong, and never from an
- * unrelated log (the caller's header is the identity witness). Fresher
- * paths (the history tail baseline, {@link coldSnapshot}) supersede these
- * values whenever a session is actually opened.
- * @param meta - the listed session's header (identity witness; no log read).
- * @returns the cut (`asOfSeq` = lowest served-row watermark), or
- *   `undefined` when no usable row exists for this lifecycle.
- */
-cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined
-
-/**
- * Durably checkpoint one live session NOW (both mandatory points call
- * this; tests and carriers may too). The registry cut is snapshotted at
- * this boundary (states are live references), then the whole record is
- * replaced. NOT fail-soft — callers on the fail-soft paths contain it.
- * @param session - the live session to checkpoint.
- * @returns resolution after durability and event emission.
- */
-async write(session: Session): Promise<void>
-
-/**
- * Cold-read one persisted session's projections with zero full-log load:
- * cached rows + a persistence `readFrom` tail from the registry's restore
- * floor, refolded by the registry and written back (fail-soft) so the next
- * cold read starts closer. A cache row invalidated by a shrunk log
- * (crash-repair truncation) triggers one full re-read from seq 0 — the
- * ladder's slow rung, still no crash. Rejects when the session has no
- * persisted log (`not found` from the persistence seam).
- * @param id - the persisted session to read.
- * @param signal - optional cancellation for the persistence reads.
- * @returns the snapshot cut at the stored log end.
- */
-async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>
-```
-
-Types: [Session](../subsystems/session.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md)
-
-Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
-
-## `ctx.sessionProjections` — `SessionProjectionRegistry`
-
-`ctx.sessionProjections`: the projection unit table and its drive. The service subscribes to `session/event` once; every committed event passes every registered unit's `apply` (eager drive), and a changed state reference notifies the change feed with the schema-validated view. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect (disposer rides the calling fiber): an unloaded domain plugin's key disappears from snapshots and clients read it as capability absence. Duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
-
-```ts cordis-catalog
-/**
- * Register one domain's unit. The registration is an effect on the calling
- * context's fiber: disposing the fiber (or calling the returned disposer)
- * removes the key — and the unit's cached cells — from subsequent drives
- * and snapshots.
- * @param definition - key, boundary schema, pure unit functions, and stateVersion.
- * @returns the exact disposer that unregisters this unit.
- */
-register<K extends keyof SessionProjectionMap, S>(definition: ProjectionDefinition<K, S>): () => void
-
-/**
- * Subscribe to the change feed. The registration is an effect on the
- * calling context's fiber.
- * @param listener - called once per unit whose state reference changed, per committed event.
- * @returns the exact disposer that unsubscribes.
- */
-onChanged(listener: ProjectionChangeListener): () => void
-
-/**
- * One consistent cut over every registered unit for one session, read from
- * the watermark cache (missing cells fold lazily over the in-memory log).
- * Fully synchronous — every value and `asOfSeq` reflect the same log
- * position. Each value passes its unit's schema before leaving.
- * @param session - the session whose projection values are read.
- * @returns the snapshot; `values` is empty when no unit is registered.
- */
-snapshot(session: Session): ProjectionSnapshot
-
-/**
- * State-level checkpoint of every registered unit for one session, read
- * from the watermark cache (missing cells fold lazily over the in-memory
- * log). This is the write side of the persisted projection cache: the
- * returned rows are the `(key → {ver, seq, val})` part of the durable
- * `(sessionId, key, ver, seq, val)`
- * rows. Every `val` is a DETACHED structured clone — never the live
- * cell reference: the watermark cache is this registry's authoritative
- * mutable state, and a caller reaching the live reference could corrupt
- * every subsequent snapshot and frame through it (plain JSON by the unit
- * contract, so the clone is total).
- * @param session - the session whose unit states are checkpointed.
- * @returns one row per registered key; empty when no unit is registered.
- */
-checkpoint(session: Session): ProjectionCheckpoint
-
-/**
- * The stored seq a {@link restore} tail read over `checkpoint` must start
- * at: one event BELOW the lowest usable watermark (a row is usable when
- * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
- * pulls the floor to `0` — that key must refold the full log). The
- * one-below anchor is load-bearing: the tail then proves how far the
- * stored log still extends, so {@link restore} can detect a log that
- * shrank below a row's watermark (crash-repair truncation) instead of
- * serving the stale row as current — an empty tail read from the anchor
- * yields an end below every watermark and the restore rejects for a full
- * re-read.
- * @param checkpoint - persisted rows for one session (possibly stale or empty).
- * @returns the seq to hand the persistence `readFrom`, or `undefined`
- *   when no unit is registered (no read needed — {@link restore} would
- *   serve empty values regardless).
- */
-restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined
-
-/**
- * View a checkpoint's rows without any log read: for every registered
- * unit whose row's `ver` matches, serve the schema-validated
- * `view` of the stored state; mismatched or absent rows leave their key
- * absent (a cold or listing consumer treats it as not-yet-available and a
- * fuller read path refolds it). The zero-I/O rung of the read ladder —
- * values are as stale as their rows, never wrong.
- * @param checkpoint - persisted rows for one session (possibly stale or empty).
- * @returns whole values per key with a usable row; empty when none.
- */
-viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
-
-/**
- * Cold read: fold every registered unit over a stored log suffix, seeding
- * each from its checkpoint row when usable — the one read recipe (cached
- * state + forward tail replay + `view`) applied without a live `Session`.
- * Call with the events returned by a persistence
- * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
- * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
- * so a shrunk log is detected here. A row is usable iff its
- * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
- * (`seq >= baseSeq - 1`), and it does not claim events past the
- * supplied end (`seq <= endSeq`); an unusable row is discarded
- * and its key refolds from `init` — which is only sound over the full
- * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
- * from seq 0, e.g. after a crash-repair truncation shrank the log below
- * a row's watermark).
- * @param checkpoint - persisted rows for one session (possibly stale or empty).
- * @param events - the stored events with `seq >= baseSeq`, in seq order.
- * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
- * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
- *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
- *   refreshed checkpoint rows at that cut, ready for a durable write-back.
- */
-restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
-```
-
-Types: [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md)
-
-Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
-
-## `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
-
-Unified live-preferred session query service.
-
-Exact reads, filters, and traces are backend-independent concrete behavior. A backend implements full-text observation, reconciliation, ranking, cursor generations, and query execution on the same `ctx.sessionQuery` service.
-
-```ts cordis-catalog
-/**
- * Search the live-preferred logical corpus and group by session.
- * @param request - query text, metadata filters, page size, and cursor.
- * @param exec - optional cancellation control.
- * @returns session hits ranked by their strongest matching event.
- */
-abstract searchSessions( request: SessionSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionSearchHit>>
-
-/**
- * Search events within one live-preferred logical session.
- * @param request - target session, query text, filters, page size, and cursor.
- * @param exec - optional cancellation control.
- * @returns matching event hits and their target header from one indexed generation.
- */
-abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionEventSearchPage>
-
-/**
- * List the complete logical corpus using live-preferred records.
- * @param signal - optional cancellation for persistence listing.
- * @returns deterministic newest-first cloned session records.
- */
-listSessions(signal?: AbortSignal): Promise<SessionRecord[]>
-
-/**
- * Read and replay-validate one complete logical session log without making it live.
- * @param sessionId - live or persisted session id to read.
- * @returns cloned header and complete raw event log from one observation.
- * @throws when persistence, header compatibility, or replay validation fails.
- */
-async readSession(sessionId: SessionId): Promise<SessionLogSnapshot>
-
-/**
- * Filter the complete logical corpus with provider-independent predicates.
- * @param filters - ANDed session metadata and availability clauses.
- * @param signal - optional cancellation for persistence listing.
- * @returns matching cloned records in deterministic newest-first order.
- */
-async filterSessions( filters: readonly SessionResultFilter[], signal?: AbortSignal, ): Promise<SessionRecord[]>
-
-/**
- * Fold the latest log-backed title from one live-preferred logical session.
- * @param sessionId - live or persisted session id to read.
- * @param signal - optional cancellation for source resolution and title folding.
- * @returns latest title snapshot, or `undefined` when the log has no title event.
- */
-async readTitle( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleSnapshot | undefined>
-
-/**
- * Fold the latest title and return its source header from one corpus observation.
- * @param sessionId - live or persisted session id to read.
- * @param signal - optional cancellation for source resolution and title folding.
- * @returns cloned source header and optional latest title snapshot.
- */
-async readTitleSnapshot( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleObservation>
-
-/**
- * Fold titles for unique sessions from one cancellable corpus observation.
- *
- * Results preserve first-occurrence input order. Operational failures stay
- * isolated per session, while cancellation rejects the complete operation.
- * @param sessionIds - live or persisted session ids to observe.
- * @param signal - optional cancellation shared by all source reads.
- * @returns one fulfilled or rejected result per unique requested id.
- */
-async readTitleSnapshots( sessionIds: readonly SessionId[], signal?: AbortSignal, ): Promise<SessionTitleObservationResult[]>
-
-/**
- * List lightweight raw-log event records for one logical session.
- * @param sessionId - live-preferred session id to read.
- * @returns event records in ascending seq order.
- */
-async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>
-
-/**
- * Scan first-party semantic event documents with provider-independent filters.
- * @param sessionId - live-preferred session id to scan.
- * @param filters - ANDed metadata and literal-text predicates.
- * @returns matching semantic documents in ascending seq order.
- */
-async filterEvents( sessionId: SessionId, filters: readonly SessionEventResultFilter[], ): Promise<SessionEventSearchDocument[]>
-
-/**
- * Read one session's complete current model surface from one corpus observation.
- * @param sessionId - live-preferred session id to read.
- * @returns cloned header, current surface, and raw-log capture boundary.
- * @throws when source resolution fails or the session surface is invalid.
- */
-async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
-
-/**
- * Trace known ancestry and descendants from one corpus observation.
- * @param sessionId - logical session id to trace.
- * @param signal - optional cancellation for persistence listing.
- * @returns a complete lineage or an explicit unresolved parent boundary.
- * @throws when corpus resolution fails, the target is absent, or its known ancestry cycles.
- */
-async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>
-
-/**
- * Trace one event's direct positional and provenance relationships.
- * @param request - target session id and event seq.
- * @param signal - optional cancellation for persisted source resolution.
- * @returns source header, direct links, and the target's positional replacement chain.
- * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
- */
-async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>
-
-/**
- * Read one full event plus a bounded raw-log context window.
- * @param request - target session/seq and context sizes.
- * @param signal - optional cancellation for persisted source resolution.
- * @returns cloned target and neighboring events.
- */
-async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>
-```
-
-Types: [SessionEventReadRequest](../subsystems/session-query.md) · [SessionEventRecord](../subsystems/session-query.md) · [SessionEventResultFilter](../subsystems/session-query.md) · [SessionEventSearchDocument](../subsystems/session-query.md) · [SessionEventSearchPage](../subsystems/session-query.md) · [SessionEventSearchRequest](../subsystems/session-query.md) · [SessionEventTraceObservation](../subsystems/session-query.md) · [SessionEventTraceRequest](../subsystems/session-query.md) · [SessionEventWindow](../subsystems/session-query.md) · [SessionId](../subsystems/core.md) · [SessionLineageTrace](../subsystems/session-query.md) · [SessionLogSnapshot](../subsystems/session-query.md) · [SessionRecord](../subsystems/session-query.md) · [SessionResultFilter](../subsystems/session-query.md) · [SessionSearchExecContext](../subsystems/session-query.md) · [SessionSearchHit](../subsystems/session-query.md) · [SessionSearchPage](../subsystems/session-query.md) · [SessionSearchRequest](../subsystems/session-query.md) · [SessionSurfaceSnapshot](../subsystems/session-query.md) · [SessionTitleObservation](../subsystems/session-query.md) · [SessionTitleObservationResult](../subsystems/session-query.md) · [SessionTitleSnapshot](../subsystems/session-title.md)
-
-Source: [`packages/session-query/session-query/src/index.ts:81`](../../packages/session-query/session-query/src/index.ts)
-
-## `ctx.sessionReferences` — `SessionReferenceService`
-
-Exact-read consumer that prepares immutable cross-session message context.
-
-```ts cordis-catalog
-/**
- * List reference candidates, ranked by working-directory affinity.
- * @param agent - target agent; self is excluded and its cwd drives ranking.
- * @param query - optional case-insensitive session-id/cwd/title substring.
- * @param limit - optional positive result cap.
- * @param signal - optional cancellation boundary for host autocomplete teardown.
- * @returns candidates labeled by latest title or, when absent, session id.
- */
-async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
-
-/**
- * Snapshot all references before enqueue and return one aggregated durable context.
- * @param agent - target agent; references to it are rejected.
- * @param content - already host-normalized readable message content.
- * @param references - structured source sessions in mention order.
- * @param signal - optional cancellation boundary for host request teardown.
- * @returns detached content and optional referenced-session context.
- */
-async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
-```
-
-Types: [Agent](../subsystems/core.md) · [ContentBlock](../subsystems/core.md) · [PreparedReferencedMessage](../subsystems/session-reference.md) · [SessionReferenceCandidate](../subsystems/session-reference.md) · [SessionReferenceInput](../subsystems/session-reference.md)
-
-Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
-
-## `ctx.sessions` — `SessionStore`
-
-In-memory session store (`ctx.sessions`).
-
-Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
-
-```ts cordis-catalog
-/**
- * Create a session owned by the calling fiber: disposing that fiber stops
- * event notification and removes the session from the store. `options.seed`
- * populates the session with a copy of those events (replay/fork);
- * `options.meta` attaches creation metadata (validated absolute `cwd`, seed
- * and parent lineage, and delegation depth) as the immutable
- * {@link SessionHeader} (the store fills `version`/`id`/`createdAt`).
- *
- * For an agent whose session must be torn down IN ORDER with its loop (so the
- * loop's final events are published before the store attachment ends), do NOT use this
- * — fold the session lifecycle into the agent's own effect via
- * {@link prepare} + {@link enter} + {@link announce} (see
- * `dsh-agent-loop`'s creation transaction).
- *
- * @param id - the session id; omitted, the store mints `session-<n>`.
- * @param options - seed events and/or creation metadata for the header.
- * @returns the live session, already entered and announced.
- * @throws if a session with `id` already exists, metadata is not a plain
- *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
- *   non-absolute path (storage backends key directories off it).
- */
-create(id?: SessionId, options?: CreateSessionOptions): Session
-
-/**
- * Build a session WITHOUT entering it into the store — validate the id/cwd and
- * construct the {@link Session} (with its immutable {@link SessionHeader}).
- * Pairs with {@link enter} + {@link announce}: a caller that owns a composite
- * `ctx.effect` (the agent factory) folds the session lifecycle into that ONE
- * effect so a fiber unload tears the session + agent down as a single ORDERED
- * chain rather than as racing sibling effects — which would remove the publication hooks
- * before the driver's closing events commit, dropping them.
- *
- * @param id - the session id; omitted, the store mints `session-<n>`.
- * @param options - seed events and/or creation metadata for the header. With
- *   `seedSource: 'persistence'`, metadata and events must be fresh detached
- *   graphs whose ownership transfers to this call: they are validated and
- *   frozen in place through {@link Session.fromRestore}, so the caller must
- *   retain no mutable aliases.
- * @returns the constructed session, NOT yet in the store.
- * @throws if a session with `id` already exists, metadata is not a plain
- *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
- *   non-absolute path.
- */
-prepare(id?: SessionId, options?: PrepareSessionOptions): Session
-
-/**
- * Enter a {@link prepare}d session into the store: install the module-private
- * append publication hooks and add it to the store. Returns the DETACH
- * disposer (hooks + store removal). Does NOT emit `session/created` —
- * the caller yields this disposer inside its effect and THEN calls
- * {@link announce}, so a throwing `session/created` listener rolls the attach
- * back instead of leaking it.
- *
- * Re-checks the id for a duplicate: `prepare` and `enter` are public
- * cross-package primitives and a caller may interleave arbitrary work (or
- * another create) between them, so a stale prepared session must NOT overwrite
- * a live store entry of the same id — its detach disposer would later delete
- * the REAL session. The {@link create} convenience and the agent factory call
- * the two back-to-back so they never trip this, but the public seam cannot
- * assume that.
- *
- * @param session - a {@link prepare}d session not yet in the store.
- * @returns the detach disposer (publication hooks + store removal). When called from
- *   a synchronous `session/created` listener, removal and disposal wait until
- *   that creation dispatch unwinds.
- * @throws if a session with this id is already in the store.
- */
-enter(session: Session): () => void
-
-/** Emit `session/created` exactly once for an {@link enter}ed session (with
- * the carrier {@link enter} captured). Separate from {@link enter} so the
- * caller can yield the detach disposer first (rollback safety — see
- * {@link enter}).
- * @param session - the entered session to announce to listeners.
- * @throws if the session is not live or its announcement already began,
- *   including a reentrant call from a creation listener. */
-announce(session: Session): void
-
-/**
- * Dispatch the awaited `session/flush` durability checkpoint for `session`,
- * with the carrier captured at {@link enter}. THE flush entry point: the
- * store owns the carrier, so callers (the checkpoint policy's per-request
- * barrier, goal-session's idle checkpoint, teardown drains, and consumers
- * that flush themselves before reading storage) must come through here
- * rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner,
- * one spelling, and the scoped-dispatch invariant can pin it.
- * @param session - the session whose buffered events must reach durable storage.
- * @returns whether at least one durability listener participated, after every
- *   listener has settled successfully.
- * @throws the first registered listener failure after every listener settles.
- */
-async flush(session: Session): Promise<boolean>
-
-/**
- * Look up a live session.
- * @param id - the session id to look up.
- * @returns the session, or undefined when no live session has that id.
- */
-get(id: SessionId): Session | undefined
-
-/**
- * All live sessions, in creation order.
- * @returns a fresh array; mutating it does not affect the store.
- */
-list(): Session[]
-
-/**
- * Create a live child session from a stable prefix of a live source.
- * `boundary` is an inclusive source event seq; omitted means the source's
- * current last event. The selected slice may end with a between-turn event
- * but must not end inside an open turn.
- *
- * @param source - Live source session object or id.
- * @param boundary - Inclusive source event seq to fork through; omitted means
- *   the source's current last event, and omitted on an empty source forks an
- *   empty child.
- * @param childSessionId - Optional child session id; omitted delegates to
- *   `SessionStore`'s id policy.
- * @returns The created live child session.
- */
-fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
-```
-
-Types: [CreateSessionOptions](../subsystems/persistence.md) · [PrepareSessionOptions](../subsystems/persistence.md) · [Session](../subsystems/session.md) · [SessionId](../subsystems/core.md)
-
-Source: [`packages/core/session/src/index.ts:807`](../../packages/core/session/src/index.ts)
-
-## `ctx.sessionTitle` — `SessionTitleService`
-
-Log-backed title fold plus asynchronous fallback generation.
-
-```ts cordis-catalog
-/**
- * Read the latest folded title from one live or replayed session.
- * @param session - session whose log is the title source of truth.
- * @returns latest title snapshot, or `undefined` before eligible input.
- */
-get(session: Session): SessionTitleSnapshot | undefined
-
-/**
- * Accept an explicit user title. Appends a `session/title` event with the
- * `user` source, which pins the title: in-flight automatic generation is
- * superseded and later user messages schedule none (an explicit
- * {@link SessionTitleService.refresh} remains the deliberate unpin).
- * @param session - exact live session to rename.
- * @param title - raw user input; normalized before acceptance.
- * @returns the accepted title snapshot.
- * @throws {SessionTitleInvalidError} when the title normalizes to empty.
- * @throws {Error} when the session is not live or the service is disposed.
- */
-rename(session: Session, title: string): SessionTitleSnapshot
-
-/**
- * Explicitly retry the registered provider, or materialize the built-in
- * fallback when no provider is registered.
- * @param session - exact live session to refresh.
- * @param signal - optional caller cancellation.
- * @returns latest accepted title, or `undefined` when no eligible text exists.
- */
-async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
-
-/**
- * Register the sole optional title provider. Disposal aborts its pending and
- * active work before another provider may register.
- * @param provider - provider identity, cadence, and generation function.
- * @returns exact Cordis effect disposer, which settles after active calls quiesce.
- */
-register(provider: SessionTitleProvider): () => Promise<void>
-```
-
-Types: [Session](../subsystems/session.md) · [SessionTitleProvider](../subsystems/session-title.md) · [SessionTitleSnapshot](../subsystems/session-title.md)
-
-Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts)
-
-## `ctx.settings` — `Settings` (abstract seam)
-
-Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
-
-```ts cordis-catalog
-/**
- * Prepare the provider's user-editable document for a native editor. File
- * providers may materialize an absent document before returning its path;
- * non-file providers return undefined.
- * @returns the absolute local document path, or undefined for non-file storage.
- */
-prepareDocument(): Promise<string | undefined>
-
-/**
- * Register a namespace schema and receive its owner scope. The registration
- * is an effect on the calling plugin's fiber: disposing that fiber removes
- * the namespace and its observers. An invalid stored section fails the
- * registration itself — the earliest point where the schema can judge it.
- * @param ns - unique namespace; duplicate registration fails loud.
- * @param schema - schemastery schema resolving this namespace's value.
- * @param options - composition `base` layer and effect timing.
- * @returns the owner scope for reads, observation, and updates.
- */
-register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>
-
-/**
- * Describe every registered namespace for configuration surfaces, including
- * the composition `base` and raw user layers so a form can mark which fields
- * the user overrode (presence in `user`) and what a reset returns to.
- * @param options - redaction switch; wire surfaces must redact.
- * @returns one descriptor per registered namespace, in registration order.
- */
-describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
-
-/**
- * Read one registered namespace's resolved value.
- * @param ns - the namespace to read.
- * @returns the resolved value, or `undefined` while unregistered.
- */
-get(ns: SettingsNamespace): unknown
-
-/**
- * Merge a patch into one registered namespace's user layer, validate the
- * resolved candidate, persist through the provider, then commit and emit.
- * A validation failure rejects before anything is persisted. Writes to one
- * namespace are serialized: concurrent updates apply in call order, each
- * merging over the previous write's committed section.
- * @param ns - the registered namespace to update.
- * @param patch - plain-object patch over the user section.
- * @param expectedRevision - the descriptor `revision` the caller read; a
- *   namespace that moved past it rejects with {@link SettingsConflictError}.
- */
-async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>
-
-/**
- * Replace one registered namespace's user section wholesale, validate,
- * persist, then commit and emit. Keys absent from `section` fall back to the
- * composition `base` and schema defaults — this is the removal/reset path a
- * merge-only patch cannot express (`replace({})` re-inherits everything).
- * @param ns - the registered namespace to replace.
- * @param section - the complete next user section.
- * @param expectedRevision - the descriptor `revision` the caller read; a
- *   namespace that moved past it rejects with {@link SettingsConflictError}.
- */
-async replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>
-
-/**
- * Apply path-addressed edits to one registered namespace's user section,
- * validate, persist, then commit and emit. The ops are applied to the
- * section as it stands when the write reaches the front of the queue, so a
- * caller never has to restate fields it did not touch — and, crucially,
- * cannot delete fields it never saw. This is the write path for any caller
- * holding a redacted view; `replace` remains the wholesale reset.
- * @param ns - the registered namespace to edit.
- * @param ops - ordered path edits; later ops observe earlier ones.
- * @param expectedRevision - the descriptor `revision` the caller read; a
- *   namespace that moved past it rejects with {@link SettingsConflictError}.
- */
-async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
-```
-
-Types: [SettingsDescribeOptions](../subsystems/settings.md) · [SettingsDescriptor](../subsystems/settings.md) · [SettingsNamespace](../subsystems/settings.md) · [SettingsPathOp](../subsystems/settings.md) · [SettingsRegisterOptions](../subsystems/settings.md) · [SettingsScope](../subsystems/settings.md)
-
-Source: [`packages/settings/settings/src/index.ts:387`](../../packages/settings/settings/src/index.ts)
-
-## `ctx.skills` — `SkillService`
-
-Registry of skill providers. It merges provider catalogs with stable first-wins duplicate handling, exposes sorted invocation-neutral summaries, and loads full skill bodies on demand.
-
-```ts cordis-catalog
-/**
- * Register a borrowed same-process provider synchronously during plugin apply. Duplicate and
- * reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters
- * the provider and invalidates catalog caches.
- * @param create - synchronous factory receiving this registration's lifecycle and invalidation control.
- * @returns the exact Cordis effect disposer that unregisters this provider;
- *   composite effects may yield it directly to preserve teardown ordering.
- */
-registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void
-
-/**
- * Register a borrowed readonly runtime skill. Project entries outrank runtime entries, which
- * outrank user entries. Same-name runtime entries are first-wins; a duplicate logs a warning and
- * receives a no-op disposer so it cannot remove the winner.
- * @param skill - the skill definition input; omitted invocation and provider fields receive defaults.
- * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
- */
-register(skill: SkillRegistration): () => void
-
-/**
- * List invocation-neutral skill summaries for a workspace. Consumers apply
- * model or user invocation policy at their operational boundary. Lookup
- * options and provider candidates are readonly same-process values borrowed
- * throughout discovery.
- * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
- * @returns all sorted winning summaries.
- */
-async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>
-
-/**
- * Observe the current invocation-neutral catalog and whether discovery completed within a stable revision.
- * Incomplete observations are never cached, allowing consumers to retain last-good state and
- * retry on their next request boundary.
- * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
- * @returns sorted summaries plus discovery-completeness state.
- */
-async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
-
-/**
- * Load and validate the winning candidate, passing its opaque discovery locator back to the
- * provider. Cancellation is rechecked after selection, including cache hits, and raced against
- * loading so an uncooperative provider cannot hang the caller.
- * @param name - kebab-case skill name.
- * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
- * @returns the full skill, including body content, or `undefined`.
- */
-async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
-```
-
-Types: [SkillCatalogSnapshot](../subsystems/skills.md) · [SkillDefinition](../subsystems/skills.md) · [SkillLookupOptions](../subsystems/skills.md) · [SkillProvider](../subsystems/skills.md) · [SkillProviderControl](../subsystems/skills.md) · [SkillRegistration](../subsystems/skills.md) · [SkillSummary](../subsystems/skills.md)
-
-Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
-
-## `ctx.spillStore` — `SpillStore` (abstract seam)
-
-Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
-
-Semantics every implementation must honor:
-
-- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
-- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
-- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
-
-```ts cordis-catalog
-/**
- * Persist `input.content` to a session-scoped spill artifact.
- * @param input - the owner, provenance, suggested name, and full text to save.
- * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
- */
-abstract saveText(input: SaveTextSpill): Promise<SpillRef>
-```
-
-Types: [SaveTextSpill](../subsystems/spill.md) · [SpillRef](../subsystems/spill.md)
-
-Source: [`packages/spill/spill/src/index.ts:45`](../../packages/spill/spill/src/index.ts)
-
-## `ctx.storage` — `Storage`
-
-The storage hub service. Backends register under `backend`; data forms mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.
-
-```ts cordis-catalog
-/**
- * Mount a data-form facility on the hub. Mounting is an effect: the
- * returned disposer unmounts the form.
- * @param form - Form key declared in {@link StorageForms}.
- * @param facility - The facility instance to expose.
- * @returns the disposer that unmounts the form.
- */
-mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void
-
-/**
- * Resolve a mounted data form.
- * @param form - Form key declared in {@link StorageForms}.
- * @returns the mounted facility.
- */
-form<K extends keyof StorageForms>(form: K): StorageForms[K]
-```
-
-Types: [StorageForms](../subsystems/storage.md)
-
-Source: [`packages/storage/storage/src/index.ts:47`](../../packages/storage/storage/src/index.ts)
-
-## `ctx.storageDomain` — `DomainFacility`
-
-The mounted domain facility. Opens declared domains over routed backends; one facility instance owns the open-domain table and enforces single-open per domain name.
-
-```ts cordis-catalog
-/**
- * Open one declared domain. Steps, each failing the whole call: reject a
- * name that is already open (`already-open`); resolve the backend route
- * (`backend-not-found` passes through from the hub); require its `kv` facet
- * (`facet-unsupported`); open the unit projected from the spec (backend
- * `version-mismatch`/`malformed-medium` pass through); load and validate
- * every stored record against the spec's zod schemas (`invalid-record`
- * with the offending table and key); construct the domain.
- *
- * Lifecycle: the CALLER owns the returned handle and closes it via
- * `Domain.close()` (typically as its own `ctx.effect` disposer) — the
- * facility does not tie the domain to any consumer fiber. Domains still
- * open when the facility unmounts are closed by the plugin disposer.
- * @param spec - The domain declaration, typically from `defineDomain`.
- * @returns the opened domain handle, typed by the spec.
- */
-async open<S extends DomainSpec>(spec: S): Promise<Domain<S>>
-
-/**
- * Look up an open domain by name, untyped. Diagnostic surface (the package
- * invariant cross-checks change events against live domain state); typed
- * consumers hold the handle returned by {@link open}.
- * @param name - Domain name.
- * @returns the open domain runtime, or `undefined` when not open.
- */
-get(name: string): DomainImpl | undefined
-
-/**
- * Close every domain still open on this facility. The unmount path for
- * consumers that never called `Domain.close()` themselves; closing is
- * idempotent, so double-closing an already-closed domain is harmless.
- * @returns resolution after every unit is released.
- */
-async closeAll(): Promise<void>
-```
-
-Types: [Domain](../subsystems/storage.md) · [DomainSpec](../subsystems/storage.md)
-
-Source: [`packages/storage/storage-domain/src/index.ts:69`](../../packages/storage/storage-domain/src/index.ts)
-
-## `ctx.subagents` — `SubagentService`
-
-Named provider registry with one-shot runs, durable discovery, and continuable-child operations.
-
-```ts cordis-catalog
-/**
- * Establish one durable continuable child and deliver its initial prompt.
- * Resolves when the child's inbox accepts that prompt, without waiting for the
- * turn to start or for the message to reach the Session log; any earlier
- * failure rejects with no ids and rolls back the child entirely.
- * @param spec - provider, delegation request, and caller cancellation.
- * @returns the durable child id and the accepted prompt's message id.
- * @throws when continuation services are unavailable or materialization fails.
- */
-async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
-
-/**
- * Deliver one later message to a continuable child as its next FIFO turn. A
- * resident child's Agent inbox accepts it directly (waking a `waiting`
- * Activation), while an absent one is cold-resumed from its persisted
- * Session. The Agent inbox is the only queue, so every accepted message has
- * one observable order.
- * @param parent - the exact live direct parent authorizing this delivery.
- * @param childId - durable child session id.
- * @param content - user-role content to deliver.
- * @param options - durable provenance and caller cancellation, which stops the
- *   operation only before inbox acceptance.
- * @returns the accepted message's inbox id.
- * @throws when continuation services are unavailable, parent authority is
- *   rejected, or the message was not admitted.
- */
-async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>
-
-/**
- * Interrupt one live continuable child's current turn under a human parent
- * address or an exact live ancestor Agent. Fire-and-return: the cancel
- * signal is issued before this returns, but the target may keep running
- * until it observes the signal. Unclaimed pending inbox work, the Activation,
- * and published descendants are preserved; claimed work is not requeued.
- * Once the interrupted driver is idle, a waking send resumes the parked FIFO
- * queue. An absent target — including a one-shot or unknown id —
- * is an accepted no-op, as is a manager-less composition, which cannot own a
- * live Activation.
- * @param targetSessionId - the durable child session id to interrupt.
- * @param authority - the human parent address or exact live ancestor Agent.
- * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
- *   live target.
- */
-interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
-
-/**
- * Deliver selected content from one live continuable child to its durable
- * direct parent. The child is the authority credential; callers cannot name a
- * recipient. Reporting does not conclude the child's turn or Activation.
- * @param child - exact live reporting child.
- * @param content - selected model-facing content.
- * @param options - parent scheduling and pre-acceptance cancellation.
- * @returns the stable identity of the parent-accepted message.
- * @throws when continuation services are unavailable, sender authorization
- *   fails, or the direct parent is not live.
- */
-async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>
-
-/**
- * Compose one deployment capability into every continuable child's
- * unpublished creation context on fresh creation and cold resume. Grants wait
- * for the next Activation; removing the contribution revokes every resident
- * installation immediately.
- * @param contribution - synchronous child-scope installer.
- * @returns the exact Cordis effect disposer.
- */
-registerContinuableSetup(contribution: ContinuableSetupContribution): () => void
-
-/**
- * Close continuable admission below exact live parent Agents, stop only their
- * visible descendant Activations synchronously, then await admitted scoped
- * materializations and release those forests child-first. The scoped cutoff
- * lasts until each exact parent leaves the registry; unrelated parent trees
- * remain live.
- * @param parents - exact host-owned parent Agents entering teardown.
- * @returns once every retained descendant Activation released its `AgentHandle`.
- * @throws an aggregate error after all branches settle when any failed.
- */
-async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
-
-/**
- * Enumerate the parent's direct session-backed subagents without loading or
- * resuming an Agent and without any query seam: the listing merges the live
- * session store with optional session persistence (live-preferred) and
- * serves each child's durable mode/label from the registered `subagent`
- * projection unit down a three-rung ladder — the registry's watermark
- * snapshot for a live child; for a cold one, a durable projection-cache
- * row when the optional cache serves an own-suffix identity (its `seq`
- * gate proves the value postdates the fork seed, where a child's own
- * descriptor is immutable once appended), else one persistence inspection
- * folded through the registry. The
- * projection fold is the single classification authority; per-child
- * diagnostics relay a fold that served no identity or a failed inspection,
- * never a list-time descriptor parse. Absent persistence, enumeration is
- * live-only (a cold child cannot be resumed then either, so its absence is
- * capability absence, not an error). This service consults no Agent
- * registrations, Activations, or providers.
- *
- * Every persistence read receives `signal`, and the listing rechecks
- * cancellation around each of those awaits. Read rejections that settle
- * after an abort become a stable `SubagentError` with code `CANCELLED`.
- * @param parentSessionId - parent session whose direct children are listed.
- * @param signal - caller-owned cancellation forwarded to persistence reads
- *   and observed around every read await.
- * @returns children and per-child diagnostics ordered by `createdAt`, then id.
- * @throws {@link SubagentError} when the projection registry or the session
- *   store is not mounted, or the caller cancels the listing.
- */
-listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>
-
-/**
- * Enumerate the root's complete session-backed subagent tree in stable
- * pre-order from one live-preferred corpus, without loading or resuming an
- * Agent. Ordinary sessions and one-shot children remain traversal nodes so
- * continuable descendants below them are discovered; each returned entry
- * adds its durable `parentId` and root-relative `depth`. Identity resolution,
- * diagnostics, optional persistence, and cancellation follow the same
- * projection-backed contract as {@link listChildren}.
- * @param rootSessionId - session whose complete descendant tree is listed.
- * @param signal - caller-owned cancellation forwarded to persistence reads
- *   and observed around every read await.
- * @returns children and per-candidate diagnostics with tree position, in
- *   stable pre-order.
- * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
- */
-listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
-
-/**
- * Register a provider under its name. Registration is effect-scoped and HMR
- * safe; removing a provider blocks new starts but does not revoke runs that
- * were already returned to their holders.
- * @param provider - the trusted provider implementation.
- * @returns the exact Cordis effect disposer.
- */
-registerProvider(provider: SubagentProvider): () => void
-
-/**
- * Look up a provider by name.
- * @param name - the provider name.
- * @returns the provider, or undefined when absent.
- */
-getProvider(name: string): SubagentProvider | undefined
-
-/**
- * List registered provider names in insertion order.
- * @returns the registered names.
- */
-list(): string[]
-
-/**
- * Establish a published child on the named provider. Capability and semantic
- * checks run before delegation. Provider ownership lasts until its promise
- * fulfills; a rejection therefore has no run for the caller to dispose and
- * emits no run lifecycle events. Post-publication turn and infrastructure
- * failures settle through the returned run.
- * @param name - the provider to use.
- * @param request - child label, prompt, parent, signal, and optional capabilities.
- * @returns the published holder-owned run.
- */
-async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
-```
-
-Types: [Agent](../subsystems/core.md) · [ContentBlock](../subsystems/core.md) · [ContinuableSetupContribution](../subsystems/subagent.md) · [ContinuableStart](../subsystems/subagent.md) · [ContinuableStartSpec](../subsystems/subagent.md) · [MessageId](../subsystems/core.md) · [SessionId](../subsystems/core.md) · [SubagentDescendantListEntry](../subsystems/subagent.md) · [SubagentFollowupOptions](../subsystems/subagent.md) · [SubagentInterruptAuthority](../subsystems/subagent.md) · [SubagentListEntry](../subsystems/subagent.md) · [SubagentProvider](../subsystems/subagent.md) · [SubagentReportOptions](../subsystems/subagent.md) · [SubagentRun](../subsystems/subagent.md) · [SubagentStartRequest](../subsystems/subagent.md)
-
-Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
-
-## `ctx.subprocess` — `SubprocessService` (abstract seam)
-
-Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Implementations must honor these semantics:
-
-- Executable paths belong to one execution world shared with the mounted filesystem provider.
-- spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures.
-- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.
-- SubprocessHandle.terminate (and the spec's abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence.
-- Disposal of the service terminates all still-running managed processes and awaits their exit.
-- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.
-
-```ts cordis-catalog
-/**
- * Resolve one configured executable in this provider's execution world.
- * Absolute paths are verified; bare names use the provider's scrubbed PATH
- * plus explicit environment overrides. Relative paths containing separators
- * are rejected: no current consumer defines which directory they would
- * resolve against, so providers fail loud instead of guessing.
- * @param command - absolute executable path or bare PATH name.
- * @param env - explicit environment entries used for lookup.
- * @param signal - aborts remote or local lookup.
- * @returns a canonical executable path.
- */
-abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
-
-/**
- * Start one managed child process from a fully-specified spec; this seam
- * applies no defaults.
- * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.
- * @returns the live process handle (streams/readers, signalling, outcome promise).
- */
-abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
-
-/**
- * Allocate a real terminal and start one owned process session. This is the
- * only non-pipe process primitive: implementations own terminal byte I/O,
- * foreground groups, signals, and complete session-tree cleanup.
- * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
- * @returns the live terminal handle after allocation succeeds.
- */
-abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
-```
-
-Types: [SubprocessHandle](../subsystems/subprocess.md) · [SubprocessSpawnSpec](../subsystems/subprocess.md) · [SubprocessTerminalHandle](../subsystems/subprocess.md) · [SubprocessTerminalSpawnSpec](../subsystems/subprocess.md)
-
-Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts)
-
-## `ctx.systemPrompt` — `SystemPrompt`
-
-Registry service for the prompt inputs assembled before each model step.
-
-```ts cordis-catalog
-/**
- * Register an ordered prompt section in the calling context's scope. A scoped
- * section shadows a global section with the same name; duplicates within one
- * layer and non-finite orders throw. Registration and disposal emit
- * `system-prompt/change`.
- * @param section - the section to register.
- * @returns the exact Cordis effect disposer.
- */
-section(section: PromptSection): () => void
-
-/**
- * Register ordered dynamic context in the calling context's scope. Scoped
- * entries shadow global entries with the same name.
- * @param context - the context contribution to register.
- * @returns the exact Cordis effect disposer.
- */
-context(context: PromptContext): () => void
-
-/**
- * Register a tool-schema provider in the calling context's scope. Global and
- * matching scoped providers both contribute; returning the reserved
- * {@link TOOL_ORDER_REST} name makes assembly fail.
- * @param provider - evaluated for each assembly with its context.
- * @returns the exact Cordis effect disposer.
- */
-tools(provider: (context: AssembleContext) => ToolProviderResult): () => void
-
-/**
- * Register a prompt variable in the calling context's scope. Scoped values
- * shadow globals; invalid or duplicate names throw. A provider may return
- * `undefined`, but rendering a section that references that value then fails.
- * @param name - the `[a-z][a-z0-9_]*` reference name.
- * @param provider - evaluated for each assembly.
- * @returns the exact Cordis effect disposer.
- */
-variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
-
-/**
- * Assemble global and scoped providers, detach tool parameters, apply
- * canonical ordering, then run the assembly waterfall. Scoped sections and
- * variables shadow globals; the returned waterfall value is authoritative.
- * @param context - the optional scope and plugin-defined assembly fields.
- * @returns the authoritative post-waterfall assembly.
- */
-async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
-```
-
-Types: [AssembleContext](../subsystems/system-prompt.md) · [PromptContext](../subsystems/system-prompt.md) · [PromptSection](../subsystems/system-prompt.md) · [ToolProviderResult](../subsystems/system-prompt.md)
-
-Source: [`packages/core/system-prompt/src/index.ts:314`](../../packages/core/system-prompt/src/index.ts)
-
-## `ctx.tasks` — `TaskService` (abstract seam)
-
-Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Implementations must honor these semantics:
-
-- Registrations outlive producer and control-surface fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
-- Owned-task access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
-- Settlement is first-wins: one terminal record, one round of contained listener notification, and released waiters, even against a late producer outcome.
-- start refuses work while no control surface is attached, so a producer cannot start work that callers cannot collect or stop.
-
-```ts cordis-catalog
-/**
- * Preflight access, validation, and owner cleanup before starting and
- * atomically registering work. A throwing starter leaves nothing registered;
- * after it returns, registration cannot fail. Settlement records the outcome,
- * notifies listeners, and releases waiters.
- * @param spec - task identity, owner, and synchronous starter.
- * @returns the registry-issued `<kind>-N` id.
- */
-abstract start(spec: TaskStart): TaskId
-
-/**
- * List caller-owned and unowned tasks in registration order without exposing
- * another session's labels.
- * @param caller - reading agent; a non-agent caller sees only unowned tasks.
- * @returns fresh snapshots.
- */
-abstract list(caller?: Agent): TaskSnapshot[]
-
-/**
- * Return a non-consuming snapshot without changing its read cursor or notice
- * state. Throws for an unknown or foreign task.
- * @param id - task to look up.
- * @param caller - reading agent checked against the owner.
- * @returns a fresh snapshot.
- */
-abstract get(id: TaskId, caller?: Agent): TaskSnapshot
-
-/**
- * Read the next stream delta, or the idempotent final output after settlement.
- * A terminal read marks the task reported. Throws for an unknown or foreign
- * task.
- * @param id - task to read.
- * @param caller - reading agent checked against the owner.
- * @returns output text and the post-read snapshot.
- */
-abstract read(id: TaskId, caller?: Agent): TaskRead
-
-/**
- * Request cancellation, then mark the task stopping and reported. A producer
- * throw propagates without changing task state. Throws for an unknown or
- * foreign task.
- * @param id - task to cancel.
- * @param caller - killing agent checked against the owner.
- * @param reason - logged reason forwarded to the producer.
- * @returns `requested` for live work, otherwise `already-finished`.
- */
-abstract kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
-
-/**
- * Wait for settlement or timeout without cancelling the task. Caller abort
- * rejects only while the task is live; after settlement the terminal
- * snapshot wins so a notice suppressed for this waiter is still delivered.
- * Throws for invalid, unknown, or foreign input.
- * @param id - task to wait for.
- * @param timeoutMs - positive finite wait bound in milliseconds.
- * @param caller - waiting agent checked against the owner.
- * @param signal - optional cancellation of the wait itself.
- * @returns snapshot at settlement or timeout.
- */
-abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
-
-/**
- * Register an effect-scoped completion listener. Each listener is contained;
- * returned promises are observed but not awaited. No listener runs after
- * service disposal.
- * @param listener - receives each terminal snapshot and its exact owner.
- * @returns disposer that unregisters the listener.
- */
-abstract onTaskDone(listener: TaskDoneListener): () => void
-
-/**
- * Attach an effect-scoped surface that can read and stop tasks. {@link start}
- * refuses work while none is attached.
- * @param name - diagnostic label; duplicate names remain independent.
- * @returns disposer that detaches this surface.
- */
-abstract attachSurface(name: string): () => void
-```
-
-Types: [Agent](../subsystems/core.md) · [TaskDoneListener](../subsystems/tasks.md) · [TaskId](../subsystems/tasks.md) · [TaskRead](../subsystems/tasks.md) · [TaskSnapshot](../subsystems/tasks.md) · [TaskStart](../subsystems/tasks.md)
-
-Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts)
-
-## `ctx.telemetry` — `Telemetry` (abstract seam)
-
-The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
-
-```ts cordis-catalog
-/**
- * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
- * @param record - the logical record to report; owned by the backend after the call.
- */
-abstract emit(record: TelemetryRecord): void
-
-/** See {@link TelemetryBackend.flush}. */
-flush?(): void
-
-/**
- * See {@link TelemetryBackend.shutdown}.
- * @returns resolves when the backend's pipeline has quiesced.
- */
-abstract shutdown(): Promise<void>
-```
-
-Types: [TelemetryRecord](../subsystems/telemetry.md)
-
-Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/session/session-telemetry/src/index.ts)
-
-## `ctx.tokenMeter` — `TokenMeterService`
-
-Replay owner for one service-wide estimator and isolated per-session folds.
-
-```ts cordis-catalog
-/**
- * Measure current request pressure and surface through the durable tail.
- *
- * Provider usage is reused only when the latest successful call's canonical
- * request envelope matches `requestHeader` and its total is no lower than
- * that call's full heuristic anchor; otherwise the complete envelope and
- * surface are heuristically repriced.
- *
- * `requestHeader` affects request pressure only; surface fields always
- * describe the current session surface. Every call clones those positional
- * nodes, so measurement is O(surface).
- *
- * @param session - session to replay through its current durable tail.
- * @param requestHeader - optional effective request envelope replacing the latest logged header.
- * @returns a detached deeply immutable pressure and surface measurement.
- */
-measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
-
-/**
- * Heuristically price one model-visible message (instance face of the pure
- * `estimateMessage` export from `estimate.ts`).
- * @param message - message to price without mutation.
- * @returns content and role-framing tokens under the fixed service heuristic.
- */
-estimateMessage(message: Message): number
-```
-
-Types: [EpochHeader](../subsystems/session.md) · [Message](../subsystems/core.md) · [Session](../subsystems/session.md) · [TokenMeasurement](../subsystems/token-meter.md)
-
-Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
-
-## `ctx.toolResultPrune` — `ToolResultPruneService`
-
-Deterministic head/middle/tail pruning for current tool-result surface nodes.
-
-```ts cordis-catalog
-/**
- * Measure text content in Unicode code points; non-text blocks cost zero.
- * @param blocks - tool-result content to measure.
- * @returns total Unicode code points across text blocks.
- */
-measureContent(blocks: readonly ContentBlock[]): number
-
-/**
- * Replace an over-budget text middle while retaining rich-block order.
- * Text slicing is by Unicode code point, not UTF-16 code unit, so a retained
- * boundary cannot split a surrogate pair. Grapheme clusters may still split.
- * @param blocks - original tool-result content.
- * @returns pruned content, or `null` when the text is within budget.
- */
-pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
-
-/**
- * Prune every over-budget tool result from one stable current-surface snapshot.
- * Each replacement preserves the complete event data except for `content`,
- * points at the shadowed node for durable provenance and replay, and is
- * immediately preceded by a `compact/prune` shadow-price event pricing the
- * shadowed node through the injected token meter, so pure consumers can
- * subtract it without per-node state.
- * @param session - session whose current surface is rewritten.
- * @returns landed replacements and aggregate Unicode-code-point savings.
- * @throws when the session rejects a replacement; replacements committed
- * earlier in the pass remain durable.
- */
-pruneSession(session: Session): PruneResult
-```
-
-Types: [ContentBlock](../subsystems/core.md) · [PruneResult](../subsystems/compaction.md) · [Session](../subsystems/session.md)
-
-Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
-
-## `ctx.tools` — `ToolRegistry`
-
-Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.
-
-```ts cordis-catalog
-/**
- * Register globally or in the calling agent scope. Scoped tools shadow
- * globals; duplicates within one layer and the reserved `run_code` name fail.
- * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
- * @returns the exact disposer that unregisters the tool.
- */
-register(definition: ToolDefinition): () => void
-
-/**
- * Restrict global tools for the calling agent scope. Empty filters, unknown
- * names, scope-local names, and reserved transport names fail. Restrictions
- * intersect; scoped registrations remain visible.
- * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
- * @returns the exact disposer that lifts this restriction.
- */
-restrict(filter: ToolRestriction): () => void
-
-/**
- * Register a monotonic guard after the extensible `tools/pre-execute`
- * waterfall. A plain-context guard applies globally; one registered through
- * `agent.ctx` applies only to that agent. Any matching guard may deny by
- * returning a reason, while no guard can force-allow a call another guard
- * denied. The exact effect disposer is returned for ordered ownership and
- * HMR cleanup.
- * @param guard - synchronous check; a returned string denies the execution.
- * @returns the exact disposer that unregisters the guard.
- */
-guard(guard: ToolGuard): () => void
-
-/**
- * Look up a tool as one scope sees it (scoped
- * shadows global; a restricted-away global reads as absent). Presenters pass
- * the calling agent so the rendered card matches the definition that
- * actually executed.
- * @param name - the tool name as registered.
- * @param scope - the viewing scope (the agent); omitted = the global view.
- * @returns the definition the scope resolves, or undefined when none is visible.
- */
-get(name: string, scope?: ScopeKey): ToolDefinition | undefined
-
-/**
- * Project visible definitions onto the allowlisted model-facing schema fields,
- * excluding execution and presentation callbacks.
- * @param scope - the viewing scope (the agent); omitted = the global view.
- * @returns one deep-cloned schema per visible tool.
- */
-schemas(scope?: ScopeKey): ToolSchema[]
-
-/**
- * Classify a pending call through the caller's visible tool definition. Only
- * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
- * throwing classifiers are exclusive.
- * @param exec - call name, parsed arguments, and optional agent scope.
- * @returns the fail-closed scheduling mode.
- */
-executionMode(exec: ToolExecutionInput): ToolExecutionMode
-
-/**
- * Execute through pre-policy, guards, around-dispatch, post-policy,
- * definition-owned content finalization, and final notification. Tool and
- * listener failures resolve as materialized error results; an invisible tool
- * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen
- * snapshot final observers receive. Cancellation
- * arriving after entry and before final result materialization skips a
- * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a
- * successful started outcome with `ABORTED`; already-started work is still
- * drained and may retain a tool-owned structured error.
- * @param exec - the typed same-process call input. The registry assigns its
- *   correlation token before policy begins.
- * @returns the materialized final result.
- */
-async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
-```
-
-Types: [ScopeKey](../subsystems/scope.md) · [ToolDefinition](../subsystems/tools.md) · [ToolExecutionInput](../subsystems/tools.md) · [ToolExecutionMode](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolGuard](../subsystems/tools.md) · [ToolRestriction](../subsystems/tools.md) · [ToolSchema](../subsystems/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
-
-## `ctx.typert` — `TypertRegistry`
-
-Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
-
-```ts cordis-catalog
-/**
- * Register one generated contribution atomically for the calling fiber.
- * Duplicate package-face identities, schemas, invocation ids, or endpoints
- * reject the whole batch.
- * @param contribution - generated schemas, reflection, and Host invocations.
- * @returns the exact effect disposer that removes this contribution.
- */
-register(contribution: TypertContribution): TypeRTDisposer
-
-/**
- * Look up one schema by `<package>#<name>`.
- * @param key - global schema key.
- * @returns the live schema record, or `undefined` when absent.
- */
-get(key: string): TypertSchemaRecord | undefined
-
-/**
- * Resolve one required schema.
- * @param key - global schema key.
- * @returns the live schema record.
- * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
- */
-resolve(key: string): TypertSchemaRecord
-
-/**
- * Enumerate live schemas in registration order.
- * @param filter - optional package and face restriction.
- * @returns matching schema records.
- */
-list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
-
-/**
- * Look up generated reflection for one package face.
- * @param packageName - exact npm package name.
- * @param face - face to query; defaults to the host runtime.
- * @returns the live package record, or `undefined` when absent.
- */
-getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
-
-/**
- * Enumerate generated package reflection in registration order.
- * @param filter - optional package and face restriction.
- * @returns matching package records.
- */
-listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
-
-/**
- * Project a live Zod schema to JSON Schema without caching the result.
- * @param key - global schema key.
- * @param params - Zod projection parameters.
- * @returns a fresh JSON Schema document.
- */
-toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
-```
-
-Source: [`packages/typert/registry/src/service.ts:446`](../../packages/typert/registry/src/service.ts)
-
-## `ctx.typertGateway` — `TypertGatewayService`
-
-Resolve strict generated definitions or conservative SRC markers against current Cordis Services and TypeRT providers.
-
-```ts cordis-catalog
-/**
- * Invoke one live Remote method through strict generated reflection or SRC markers.
- * @param request - decoded endpoint and exact named wire arguments.
- * @returns the validated business result.
- * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
- */
-async invoke(request: InvokeRemoteRequest): Promise<unknown>
-```
-
-Source: [`packages/api/gateway/src/index.ts:78`](../../packages/api/gateway/src/index.ts)
-
-## `ctx.userInteraction` — `UserInteractionService`
-
-`ctx.userInteraction`: one active UI provider plus an `ask()` surface.
-
-```ts cordis-catalog
-/**
- * Register the UI provider. Only one provider may be active in a context.
- *
- * @param provider UI-side implementation that collects answers.
- * @returns Disposer that unregisters this provider.
- */
-registerProvider(provider: UserInteractionProvider): () => void
-
-/**
- * Ask the active UI provider and wait for the user's answer.
- *
- * When a caller supplies an agent, human interaction is valid only for the
- * exact live runtime root. Runtime ownership, not durable session lineage,
- * decides this boundary: an owned child has no human answerer and would
- * block forever, while a lineage-bearing session resumed as a new runtime
- * root may ask normally.
- *
- * @param request Questions, owner agent, and abort signal.
- * @returns The answer chosen or typed by the human.
- * @throws {UserInteractionError} code `CALLER_NOT_LIVE` when a supplied
- *   agent is not the registry's exact live instance, or `DELEGATED_CALLER`
- *   when that live agent is owned by another agent.
- */
-async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
-```
-
-Types: [AskUserQuestionAnswer](../subsystems/user-interaction.md) · [AskUserQuestionRequest](../subsystems/user-interaction.md) · [UserInteractionProvider](../subsystems/user-interaction.md)
-
-Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts)
-
-## `ctx.web` — `WebService`
-
-The web access service. Registered as `ctx.web` (one instance per context).
-
-Selection semantics (resolved at execution time, never order-dependent):
-
-- A configured id that is registered and `available()` → that provider.
-- A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
-- A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
-- No id configured, exactly one registered usable provider → that provider.
-- No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
-- No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
-
-```ts cordis-catalog
-/**
- * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
- * if its id is already registered for search. Returns a disposer; disposed
- * with the calling fiber.
- * @param provider - the provider; its `id` is the registry key.
- * @returns the disposer that unregisters the provider.
- */
-registerSearchProvider(provider: WebSearchProvider): () => void
-
-/**
- * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
- * if its id is already registered for fetch. Returns a disposer; disposed
- * with the calling fiber.
- * @param provider - the provider; its `id` is the registry key.
- * @returns the disposer that unregisters the provider.
- */
-registerFetchProvider(provider: WebFetchProvider): () => void
-
-/**
- * Run one search through the selected provider. Resolves the provider at call
- * time with the selection rules above; throws {@link WebError} when the
- * capability cannot run. The seam enforces `request.maxResults` on the result:
- * if the provider over-returns, `sources[]` is truncated and `truncated` set.
- * @param request - the query plus result-shaping options.
- * @param signal - optional cancellation signal forwarded to the provider.
- * @returns the provider's results, capped to `request.maxResults`.
- */
-async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
-
-/**
- * Retrieve one URL through the selected provider. Resolves the provider at
- * call time with the selection rules above; throws {@link WebError} when the
- * capability cannot run. A non-2xx response is a result, not a throw.
- * @param request - the URL plus retrieval options.
- * @param signal - optional cancellation signal forwarded to the provider.
- * @returns the retrieval outcome; non-2xx responses resolve descriptively.
- */
-async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
-```
-
-Types: [WebFetchProvider](../subsystems/web.md) · [WebFetchRequest](../subsystems/web.md) · [WebFetchResult](../subsystems/web.md) · [WebSearchProvider](../subsystems/web.md) · [WebSearchRequest](../subsystems/web.md) · [WebSearchResult](../subsystems/web.md)
-
-Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
-
-## `ctx.workflows` — `WorkflowService` (abstract seam)
-
-Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
-
-```ts cordis-catalog
-/**
- * Parse and execute a workflow script.
- * @param request - the script, its `args`, the parent agent, and an
- *   optional cancel signal.
- * @returns the live run; its `result` resolves when the script settles.
- */
-abstract start(request: WorkflowStartRequest): WorkflowRun
-```
-
-Types: [WorkflowRun](../subsystems/workflow.md) · [WorkflowStartRequest](../subsystems/workflow.md)
-
-Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts)
-
-## `ctx.workspace` — `WorkspaceRegistry`
-
-Durable workspace registry. Startup waits for `sessionPersistence`, builds one canonical-cwd header index, and completes the one-time history bootstrap before the service becomes active. The persistence dependency is mandatory so an unavailable peer can never be mistaken for an empty history and commit the initialized marker.
-
-```ts cordis-catalog
-/**
- * Create or reuse a workspace for an existing directory. The path is
- * canonicalized through `fs.realpath`; a nonexistent path rejects with the
- * original error and a non-directory rejects. Repeated calls for the same
- * canonical path return the existing entity without changing its title.
- * A newly created workspace is prepended to the durable registry order.
- * Different canonical paths may share a display title.
- * @param path - Existing directory to own, in any path spelling.
- * @param title - Display title used only when a new record is created.
- * @returns the existing or newly durable workspace.
- */
-async create(path: string, title?: string): Promise<Workspace>
-
-/**
- * Look up a workspace by id.
- * @param id - Workspace id.
- * @returns the workspace, or `undefined` when unknown.
- */
-get(id: WorkspaceId): Workspace | undefined
-
-/**
- * Synchronous workspace projection in durable registry order. Every
- * entity's `sessionIds` getter is already filtered by the startup/live
- * canonical-cwd header index; this method performs no persistence reads.
- * @returns a fresh ordered array of workspace entities.
- */
-list(): Workspace[]
-
-/**
- * Delete one workspace registration while retaining its directory and every
- * session log. The durable order is updated before the table deletion; a
- * failed table write restores the prior order and keeps the entity
- * published. Unknown ids are an idempotent no-op for domain callers.
- * @param id - Workspace registration to remove.
- * @returns `true` when a record was deleted, `false` when it was unknown.
- */
-delete(id: WorkspaceId): Promise<boolean>
-
-/**
- * Archive one session durably. The session must exist (live or in session
- * persistence); its workspace accounting — or lack of one — is irrelevant.
- * An already archived id resolves without writing.
- * @param sessionId - The session to archive.
- * @returns resolution after durability.
- */
-archiveSession(sessionId: SessionId): Promise<void>
-
-/**
- * Resolve by canonical directory path without creating or mutating a
- * workspace. A missing path rejects during `realpath`; an existing unowned
- * directory returns `undefined`.
- * @param path - Existing directory path in any spelling.
- * @returns the workspace owning the canonical path, when one exists.
- */
-async resolveByPath(path: string): Promise<Workspace | undefined>
-```
-
-Types: [SessionId](../subsystems/core.md) · [Workspace](../subsystems/workspace.md) · [WorkspaceId](../subsystems/workspace.md)
-
-Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts)
-
-## Inherited `ctx` members (cordis core + loader/hmr/timer)
-
-The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier's prominence.
-
-- `ctx.on / ctx.once` — Register an event listener (disposable). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
-- `ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall` — Dispatch an event (sync / awaited / first-bail / veto-chain). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
-- `ctx.plugin / ctx.inject` — Load a plugin / declare required services. ([`vendor/cordis/src/registry.ts:164`](../../vendor/cordis/src/registry.ts))
-- `ctx.effect` — Register a disposable side effect tied to the fiber. ([`vendor/cordis/src/fiber.ts:9`](../../vendor/cordis/src/fiber.ts))
-- `ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin` — Low-level service-store access and binding. ([`vendor/cordis/src/reflect.ts:7`](../../vendor/cordis/src/reflect.ts))
-- `ctx.extend / ctx.isolate / ctx.intercept` — Derive a child context (scoped services / isolation / interception). ([`vendor/cordis/src/context.ts:42`](../../vendor/cordis/src/context.ts))
-- `ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger` — Ambient handles onto the running context graph. ([`vendor/cordis/src/context.ts:16`](../../vendor/cordis/src/context.ts))
-- `ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)` — Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick). ([`vendor/timer/src/index.ts:4`](../../vendor/timer/src/index.ts))
-- `ctx.loader` — The config Loader that booted the app (present under the loader). ([`vendor/loader/src/index.ts:30`](../../vendor/loader/src/index.ts))
-- `ctx.hmr` — The hot-module-reload watcher (present under the hmr plugin). ([`vendor/hmr/src/index.ts:15`](../../vendor/hmr/src/index.ts))
diff --git a/docs/cordis-primer.i18n.yaml b/docs/cordis-primer.i18n.yaml
index 856ea2302b..ec67982eb5 100644
--- a/docs/cordis-primer.i18n.yaml
+++ b/docs/cordis-primer.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 docs/cordis-primer.md
-cordis-primer.md: ee65e6e702ecaeb506ce7334032c38e09c936cda
-cordis-primer.zh.md: 051dd7c956a4db107a4ef7d1414435f9c2b2603d
+cordis-primer.md: 4bcb2c9979994ca70f92031cbdc5dd22df9c1977
+cordis-primer.zh.md: d84beac54463ec193f009f506a4c9b1bda02c243
diff --git a/docs/cordis-primer.md b/docs/cordis-primer.md
index ee65e6e702..4bcb2c9979 100644
--- a/docs/cordis-primer.md
+++ b/docs/cordis-primer.md
@@ -2,7 +2,7 @@
 
 English | [中文](cordis-primer.zh.md)
 
-Cordis is the vendored plugin framework underneath the DeepSeek Harness SDK. This primer teaches the Cordis ideas a harness plugin author needs before reading the generated [events](cordis-catalog/events.md) and [services](cordis-catalog/services.md) catalogs; the [Cordis tutorial](cordis-tutorial/index.md) walks the same ideas hands-on. The vendored source and sync procedure live in [vendor/README.md](../vendor/README.md).
+Cordis is the vendored plugin framework underneath the DeepSeek Harness SDK. This primer teaches the Cordis ideas a harness plugin author needs before reading the generated service/event reference on the [subsystem pages](subsystems/core.md); the [Cordis tutorial](cordis-tutorial/index.md) walks the same ideas hands-on. The vendored source and sync procedure live in [vendor/README.md](../vendor/README.md).
 
 ## Cordis In Five Ideas
 
diff --git a/docs/cordis-primer.zh.md b/docs/cordis-primer.zh.md
index 051dd7c956..d84beac544 100644
--- a/docs/cordis-primer.zh.md
+++ b/docs/cordis-primer.zh.md
@@ -2,7 +2,7 @@
 
 [English](cordis-primer.md) | 中文
 
-Cordis 是 DeepSeek Harness SDK 底层以 vendor 方式引入的插件框架。本文介绍 harness 插件作者在阅读生成的[事件](cordis-catalog/events.md)与[服务](cordis-catalog/services.md)目录之前需要了解的 Cordis 核心概念；[Cordis 教程](cordis-tutorial/index.md)则通过实践逐一讲解这些概念。vendor 源码与同步流程见 [vendor/README.md](../vendor/README.md)。
+Cordis 是 DeepSeek Harness SDK 底层以 vendor 方式引入的插件框架。本文介绍 harness 插件作者在阅读[子系统页面](subsystems/core.md)上生成的服务/事件参考之前需要了解的 Cordis 核心概念；[Cordis 教程](cordis-tutorial/index.md)则通过实践逐一讲解这些概念。vendor 源码与同步流程见 [vendor/README.md](../vendor/README.md)。
 
 ## 五个核心概念
 
diff --git a/docs/cordis-tutorial/03-services.i18n.yaml b/docs/cordis-tutorial/03-services.i18n.yaml
index 2849ed8858..bdb7e19387 100644
--- a/docs/cordis-tutorial/03-services.i18n.yaml
+++ b/docs/cordis-tutorial/03-services.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 docs/cordis-tutorial/03-services.md
-03-services.md: 562b49ede0aa4cc1d58c4d6af7c7d5d1ebb2e4b1
-03-services.zh.md: 964f7e3654614d136b8765bb727f85a5a05587a8
+03-services.md: 82b08b7b8a2ec8a6b340dd1fdc7fa3de98cedff9
+03-services.zh.md: ba4152454eb79a21b183b867c0ba2ef32cd43923
diff --git a/docs/cordis-tutorial/03-services.md b/docs/cordis-tutorial/03-services.md
index 562b49ede0..82b08b7b8a 100644
--- a/docs/cordis-tutorial/03-services.md
+++ b/docs/cordis-tutorial/03-services.md
@@ -91,7 +91,7 @@ export function apply(ctx: Context) {
 
 ## Naming
 
-Service names live in one flat namespace per application. Prefix or namespace your own services distinctively (the harness claims plain names like `tools` and `llm`); the generated [services catalog](../cordis-catalog/services.md) lists every name the harness registers.
+Service names live in one flat namespace per application. Prefix or namespace your own services distinctively (the harness claims plain names like `tools` and `llm`); the generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) list every name the harness registers.
 
 Next: [Events](04-events.md) — communication without a shared service.
 
diff --git a/docs/cordis-tutorial/03-services.zh.md b/docs/cordis-tutorial/03-services.zh.md
index 964f7e3654..ba4152454e 100644
--- a/docs/cordis-tutorial/03-services.zh.md
+++ b/docs/cordis-tutorial/03-services.zh.md
@@ -91,7 +91,7 @@ export function apply(ctx: Context) {
 
 ## 命名
 
-每个应用中的服务名称共用一个扁平命名空间。请为自有服务添加有辨识度的前缀或命名空间（harness 已占用 `tools` 和 `llm` 等普通名称）；生成的[服务目录](../cordis-catalog/services.md)列出 harness 注册的每个名称。
+每个应用中的服务名称共用一个扁平命名空间。请为自有服务添加有辨识度的前缀或命名空间（harness 已占用 `tools` 和 `llm` 等普通名称）；[子系统页面](../subsystems/core.md)上生成的 `cordis-surface` 区块列出 harness 注册的每个名称。
 
 下一章：[事件](04-events.md)：无需共享服务即可通信。
 
diff --git a/docs/cordis-tutorial/04-events.i18n.yaml b/docs/cordis-tutorial/04-events.i18n.yaml
index e7dc182114..a78b8f690c 100644
--- a/docs/cordis-tutorial/04-events.i18n.yaml
+++ b/docs/cordis-tutorial/04-events.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 docs/cordis-tutorial/04-events.md
-04-events.md: 28ccb85d657afaabb5c6b4b1e9b10d6cf8710918
-04-events.zh.md: f78c971dcd9674d2a256c41000b627aecb2a572a
+04-events.md: b0563c71fada3efc760ff7183bc7a82e7e86934e
+04-events.zh.md: 0999cbf116eca452e54418132fbaefe3622b2c26
diff --git a/docs/cordis-tutorial/04-events.md b/docs/cordis-tutorial/04-events.md
index 28ccb85d65..b0563c71fa 100644
--- a/docs/cordis-tutorial/04-events.md
+++ b/docs/cordis-tutorial/04-events.md
@@ -89,7 +89,7 @@ Because `ctx.on()` is an effect, the listener disappears with the plugin — no
 | bail | `ctx.bail(name, ...args)` | Synchronous version of serial. |
 | waterfall | `ctx.waterfall(name, ...args, next)` | Around-middleware; see below. |
 
-Every harness event documents its mode in the generated [events catalog](../cordis-catalog/events.md).
+Every harness event documents its mode in the generated reference on its owning [subsystem page](../subsystems/core.md).
 
 ## Waterfall: transform or short-circuit
 
@@ -137,7 +137,7 @@ Walk through the second line: listener 1 runs first, calls `next()`, which invok
 
 The discipline that follows: **a waterfall listener that only observes or annotates must call `next()`**; returning without it is a deliberate short-circuit. Forgetting `next()` in a logging listener silently swallows the default behavior for everyone downstream. This is important enough that it is a standing rule of this repository ([waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)).
 
-The harness uses waterfalls for decisions that cooperating plugins may wrap or answer: [`agent/request`](../cordis-catalog/events.md#agentrequest--waterfall) lets a plugin replace the model-call config, and [`approval/request`](../cordis-catalog/events.md#approvalrequest--waterfall) lets a policy answer instead of the user.
+The harness uses waterfalls for decisions that cooperating plugins may wrap or answer: [`agent/request`](../subsystems/core.md#agentrequest--waterfall) lets a plugin replace the model-call config, and [`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) lets a policy answer instead of the user.
 
 Next: [Configuration](05-config.md) — plugin options from `cordis.yml`.
 
diff --git a/docs/cordis-tutorial/04-events.zh.md b/docs/cordis-tutorial/04-events.zh.md
index f78c971dcd..0999cbf116 100644
--- a/docs/cordis-tutorial/04-events.zh.md
+++ b/docs/cordis-tutorial/04-events.zh.md
@@ -89,7 +89,7 @@ export function apply(ctx: Context) {
 | bail | `ctx.bail(name, ...args)` | serial 的同步版本。 |
 | waterfall（瀑布式事件） | `ctx.waterfall(name, ...args, next)` | 环绕中间件，见下文。 |
 
-每个 harness 事件都会在生成的[事件目录](../cordis-catalog/events.md)中记录其模式。
+每个 harness 事件都会在其所属[子系统页面](../subsystems/core.md)的生成参考中记录其模式。
 
 ## waterfall：转换或短路
 
@@ -137,7 +137,7 @@ HELLO
 
 由此得到一项纪律：**只负责观察或标注的 waterfall 监听器必须调用 `next()`**；不调用就直接返回代表有意短路。如果日志监听器忘记调用 `next()`，会悄无声息地吞掉所有下游的默认行为。这一点极其重要，已成为本仓库的常设规则（[waterfall 语义](../cordis-primer.md#cordis-waterfall-semantics)）。
 
-harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../cordis-catalog/events.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../cordis-catalog/events.md#approvalrequest--waterfall) 允许策略代替用户作答。
+harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../subsystems/core.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) 允许策略代替用户作答。
 
 下一章：[配置](05-config.md)：来自 `cordis.yml` 的插件选项。
 
diff --git a/docs/cordis-tutorial/07-into-the-harness.i18n.yaml b/docs/cordis-tutorial/07-into-the-harness.i18n.yaml
index f3dde47f3a..fd29baab75 100644
--- a/docs/cordis-tutorial/07-into-the-harness.i18n.yaml
+++ b/docs/cordis-tutorial/07-into-the-harness.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 docs/cordis-tutorial/07-into-the-harness.md
-07-into-the-harness.md: e02f8f8d55b3fbe9087d46f8f50baeecb592c1c6
-07-into-the-harness.zh.md: 5f770267e8f3db04cd9cb0e92b6a6278cf05d5e4
+07-into-the-harness.md: 38483b5c4993a44562970782dca5f676e4cb84f6
+07-into-the-harness.zh.md: 59ce716bdace894682bc1c8e6e00cf174008c26c
diff --git a/docs/cordis-tutorial/07-into-the-harness.md b/docs/cordis-tutorial/07-into-the-harness.md
index e02f8f8d55..38483b5c49 100644
--- a/docs/cordis-tutorial/07-into-the-harness.md
+++ b/docs/cordis-tutorial/07-into-the-harness.md
@@ -101,7 +101,7 @@ Where to go next:
 
 - [Build a tool](../user/develop/basic/tool.md) — more of `defineTool`, including presentation and richer schemas.
 - [Three-layer capability design](../user/develop/practice/index.md) — how the harness structures replaceable capabilities.
-- The generated [services](../cordis-catalog/services.md) and [events](../cordis-catalog/events.md) catalogs — everything you can inject and listen to.
+- The generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) — everything you can inject and listen to, each on its owning page.
 - [Architecture](../architecture.md) — the system map these plugins live in.
 
 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/07-into-the-harness.zh.md b/docs/cordis-tutorial/07-into-the-harness.zh.md
index 5f770267e8..59ce716bda 100644
--- a/docs/cordis-tutorial/07-into-the-harness.zh.md
+++ b/docs/cordis-tutorial/07-into-the-harness.zh.md
@@ -101,7 +101,7 @@ logger 会先触发：`tools/result` 在结果物化过程中发出，发生在
 
 - [构建工具](../user/develop/basic/tool.md)：深入了解 `defineTool`，包括呈现和更丰富的 schema。
 - [三层能力设计](../user/develop/practice/index.md)：harness 如何组织可替换能力。
-- 生成的[服务](../cordis-catalog/services.md)与[事件](../cordis-catalog/events.md)目录：可以注入和监听的所有内容。
+- [子系统页面](../subsystems/core.md)上生成的 `cordis-surface` 区块：可以注入和监听的所有内容，各在其所属页面上。
 - [架构](../architecture.md)：这些插件所处的系统地图。
 
 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness-sdk)
diff --git a/docs/cordis-tutorial/index.i18n.yaml b/docs/cordis-tutorial/index.i18n.yaml
index 496a3fffa5..fa810d635f 100644
--- a/docs/cordis-tutorial/index.i18n.yaml
+++ b/docs/cordis-tutorial/index.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 docs/cordis-tutorial/index.md
-index.md: a20976706f520416236ca759ee33649d1601eaa9
-index.zh.md: f6989521d4b7dffac6114867cc12371af4e4316f
+index.md: 7a0bb6f8c736bf31d655a7763cfb7039c343d1a2
+index.zh.md: e6f6dc0cccef3f44273655b98b695bdc4632e95a
diff --git a/docs/cordis-tutorial/index.md b/docs/cordis-tutorial/index.md
index a20976706f..7a0bb6f8c7 100644
--- a/docs/cordis-tutorial/index.md
+++ b/docs/cordis-tutorial/index.md
@@ -6,7 +6,7 @@ Cordis is the plugin framework underneath the DeepSeek Harness SDK: a small runt
 
 The audience is agent developers. You do not need deep TypeScript experience; the [TypeScript notes](#typescript-notes) below explain the syntax that may be unfamiliar, and every chapter shows the exact commands and expected output.
 
-If you want the condensed concept reference instead of a walkthrough, read the [Cordis primer](../cordis-primer.md). The exhaustive API reference lives in the generated [events](../cordis-catalog/events.md) and [services](../cordis-catalog/services.md) catalogs and the [Cordis core API](../cordis-catalog/core/context.md) pages.
+If you want the condensed concept reference instead of a walkthrough, read the [Cordis primer](../cordis-primer.md). The exhaustive API reference lives in the generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) and the [Cordis core API](../cordis-api/context.md) pages.
 
 ## Setup
 
diff --git a/docs/cordis-tutorial/index.zh.md b/docs/cordis-tutorial/index.zh.md
index f6989521d4..e6f6dc0ccc 100644
--- a/docs/cordis-tutorial/index.zh.md
+++ b/docs/cordis-tutorial/index.zh.md
@@ -6,7 +6,7 @@ Cordis 是 DeepSeek Harness SDK 底层的插件框架：它是一个小型运行
 
 本教程面向 agent 开发者。你不需要深入掌握 TypeScript；下文的 [TypeScript 说明](#typescript-notes)会解释可能陌生的语法，并且每一章都会给出确切命令和预期输出。
 
-如果你想阅读精简的概念参考，而不是逐步实践，请参阅 [Cordis 入门](../cordis-primer.md)。详尽的 API 参考见生成的[事件](../cordis-catalog/events.md)与[服务](../cordis-catalog/services.md)目录，以及 [Cordis 核心 API](../cordis-catalog/core/context.md) 页面。
+如果你想阅读精简的概念参考，而不是逐步实践，请参阅 [Cordis 入门](../cordis-primer.md)。详尽的 API 参考见[子系统页面](../subsystems/core.md)上生成的 `cordis-surface` 区块，以及 [Cordis 核心 API](../cordis-api/context.md)页面。
 
 ## 准备工作
 
diff --git a/docs/graph-atlas.md b/docs/graph-atlas.md
index 0c955c9480..5b831520fb 100644
--- a/docs/graph-atlas.md
+++ b/docs/graph-atlas.md
@@ -3,7 +3,7 @@
 
 # Documentation Graph Index
 
-These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [subsystems/](subsystems/core.md).
+These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the [subsystem pages](subsystems/core.md) (types + the generated `cordis-surface` regions) and [tool-catalog.md](tool-catalog.md).
 
 The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).
 
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index b9a330f21d..432c95e684 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -14,9 +14,9 @@
 
 依赖约束规范：各类扩展插件仅依赖抽象接口，严禁直接依赖 `dsh-agent-loop`（该主循环支持替换实现）；唯一允许的特例是组合包 `dsh-agent-spine-demo`，它的职责是组装整套实体主干。
 
-> This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
+> This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the generated regions of [subsystems/](../subsystems/core.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
 
-本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见 [subsystems/](../subsystems/core.md) 中的生成区块；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
 
 ## ② 防御模式规则
 
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 04f992e536..04c3a492fe 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -3,7 +3,7 @@
 
 # Session Persistence Event Catalog
 
-Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
+Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
 
 This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).
 
diff --git a/docs/subsystems/approval.i18n.yaml b/docs/subsystems/approval.i18n.yaml
index a3447601a4..93c56707bf 100644
--- a/docs/subsystems/approval.i18n.yaml
+++ b/docs/subsystems/approval.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 docs/subsystems/approval.md
-approval.md: 8f17f98101950e6413d67fb4cce6befc5aede069
-approval.zh.md: c19285572b667512427b71d4af214acbc2baf334
+approval.md: 2045f2073b72fa265728cbf77b673053a2eaf371
+approval.zh.md: c021db14c4925acaeef5d984d9dfa88ad55bd8dd
diff --git a/docs/subsystems/approval.md b/docs/subsystems/approval.md
index 8f17f98101..2045f2073b 100644
--- a/docs/subsystems/approval.md
+++ b/docs/subsystems/approval.md
@@ -87,3 +87,85 @@ interface ApprovalRequest {
 `ctx.approval.request(req)` requires the requesting session to be inside an open turn. It appends `approval/asked`, obtains one outcome, appends the matching `approval/decided`, and resolves with that outcome. The `never` policy is enforced inside the service before waterfall dispatch, so even an answerer registered later with `prepend` cannot bypass it. Answerers return an outcome when they own the request or call `next()` to delegate; the first answer occupies the single decision slot.
 
 The audit events are log-only and do not enter the model transcript. Model-visible behavior is the caller's derived tool result plus the current runtime-context snapshot. Service disposal removes its context contribution; answerer listeners are independently effect-bound to their owning plugins.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxapproval--approvalservice"></a>
+
+### `ctx.approval` — `ApprovalService`
+
+Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session. It exposes deterministic policy changes to the model through the runtime-context snapshot and switch notices.
+
+```ts cordis-catalog
+/**
+ * Switch one live agent's policy and queue the transition for its next model
+ * step. Session initialization uses {@link setApprovalPolicy} directly
+ * because there is no previously visible policy to change.
+ * @param agent - the live agent whose policy is changing.
+ * @param policy - the new effective policy.
+ */
+setPolicy(agent: Agent, policy: ApprovalPolicy): void
+
+/**
+ * Ask the composed answerers to decide one readonly same-process request.
+ * The service borrows the request, agent, session, and live signal directly.
+ * The request requires an open turn because the audit pair must be enclosed
+ * by the durable log's commit/replay boundary; an idle ask rejects before
+ * appending anything. The answerer phase always produces an outcome: an
+ * aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+ * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+ * normalized to `'unavailable'`. A failure that prevents either audit append
+ * from committing still rejects because returning an unlogged decision would
+ * violate the pair. Session contains post-commit observer failures, so an
+ * authoritative append cannot reject the request or suppress its matching
+ * audit event.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @returns the closed outcome; `'allowed-once'` is the only grant.
+ * @throws when no turn is open or either audit event fails before the session
+ *   append commit point.
+ */
+async request(req: ApprovalRequest): Promise<ApprovalOutcome>
+
+/**
+ * Read the session override without applying the configured default.
+ * @param session - session whose log supplies the override.
+ * @returns the last logged policy, or `undefined` without one.
+ */
+overrideOf(session: Session): ApprovalPolicy | undefined
+```
+
+Types: [Agent](core.md) · [Session](session.md)
+
+Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
+
+<a id="approval-events"></a>
+
+### `approval/*` events
+
+<a id="approvalrequest--waterfall"></a>
+
+#### `approval/request` — waterfall
+
+Ask composed answerers for one decision. Return an outcome to claim the request or call `next()`; failure yields the fail-closed default. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+
+```ts cordis-catalog
+/**
+ * Ask composed answerers for one decision. Return an outcome to claim the
+ * request or call `next()`; failure yields the fail-closed default.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @mode waterfall
+ */
+'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/approval.zh.md b/docs/subsystems/approval.zh.md
index c19285572b..c021db14c4 100644
--- a/docs/subsystems/approval.zh.md
+++ b/docs/subsystems/approval.zh.md
@@ -87,3 +87,85 @@ interface ApprovalRequest {
 `ctx.approval.request(req)` 要求发起请求的会话处于一个尚未结束的轮次内。它追加 `approval/asked`，获取一个结果，追加对应的 `approval/decided`，然后以该结果完成。`never` 策略在服务内部、waterfall 分发之前强制执行，因此即使后来以 `prepend` 注册的应答者也无法绕过它。应答者在拥有该请求时返回结果，否则调用 `next()` 委托；第一个应答占据唯一的决策槽位。
 
 审计事件仅写入日志，不进入模型 transcript（文本记录）。模型可见的行为是调用方派生的工具结果与当前运行时上下文快照。服务 dispose（资源释放）时会移除其上下文贡献；应答者监听器独立地通过 effect 绑定到其所属插件。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxapproval--approvalservice"></a>
+
+### `ctx.approval` — `ApprovalService`
+
+Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session. It exposes deterministic policy changes to the model through the runtime-context snapshot and switch notices.
+
+```ts cordis-catalog
+/**
+ * Switch one live agent's policy and queue the transition for its next model
+ * step. Session initialization uses {@link setApprovalPolicy} directly
+ * because there is no previously visible policy to change.
+ * @param agent - the live agent whose policy is changing.
+ * @param policy - the new effective policy.
+ */
+setPolicy(agent: Agent, policy: ApprovalPolicy): void
+
+/**
+ * Ask the composed answerers to decide one readonly same-process request.
+ * The service borrows the request, agent, session, and live signal directly.
+ * The request requires an open turn because the audit pair must be enclosed
+ * by the durable log's commit/replay boundary; an idle ask rejects before
+ * appending anything. The answerer phase always produces an outcome: an
+ * aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+ * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+ * normalized to `'unavailable'`. A failure that prevents either audit append
+ * from committing still rejects because returning an unlogged decision would
+ * violate the pair. Session contains post-commit observer failures, so an
+ * authoritative append cannot reject the request or suppress its matching
+ * audit event.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @returns the closed outcome; `'allowed-once'` is the only grant.
+ * @throws when no turn is open or either audit event fails before the session
+ *   append commit point.
+ */
+async request(req: ApprovalRequest): Promise<ApprovalOutcome>
+
+/**
+ * Read the session override without applying the configured default.
+ * @param session - session whose log supplies the override.
+ * @returns the last logged policy, or `undefined` without one.
+ */
+overrideOf(session: Session): ApprovalPolicy | undefined
+```
+
+Types: [Agent](core.md) · [Session](session.md)
+
+Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
+
+<a id="approval-events"></a>
+
+### `approval/*` events
+
+<a id="approvalrequest--waterfall"></a>
+
+#### `approval/request` — waterfall
+
+Ask composed answerers for one decision. Return an outcome to claim the request or call `next()`; failure yields the fail-closed default. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+
+```ts cordis-catalog
+/**
+ * Ask composed answerers for one decision. Return an outcome to claim the
+ * request or call `next()`; failure yields the fail-closed default.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @mode waterfall
+ */
+'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index 30e15dbacc..f6ed20cace 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.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 docs/core-data-structures/bash.md
-bash.md: f83a133c8e049bc111cfabd2b59def18a1b2d607
-bash.zh.md: 27ca9f6e5a8e05cd4ffa86e72d433b6f22005f09
+#   pnpm run verify-translation-pairing --write docs/subsystems/bash.md
+bash.md: dd7649ce46bea5642270fa553eb3d82f2dc33e9b
+bash.zh.md: bba9ece2955cee66e941aa878299cff6c06a97a0
diff --git a/docs/subsystems/bash.md b/docs/subsystems/bash.md
index f83a133c8e..dd7649ce46 100644
--- a/docs/subsystems/bash.md
+++ b/docs/subsystems/bash.md
@@ -219,3 +219,85 @@ interface BashProcessRead {
 ## The service
 
 `BashExecutor` owns `resolve`, foreground `run`, background-process `start`, and the `sandboxMode` capability fact. `dsh-bash-local` owns command defaulting, timeout/abort classification, the terminal environment, and the background read merge; process groups, bounded collectors, spill files, credential scrubbing, and disposal quiescence are the [subprocess service](subprocess.md)'s. `dsh-tool-bash` owns model-facing rendering and adapts background handles into the [generic task runtime](tasks.md). `dsh-bash` owns the shell tools' shared exit-status contract: the exported `parseExitStatus`/`ParsedExitStatus` inverts the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append, and both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxbash--bashexecutor-abstract-seam"></a>
+
+### `ctx.bash` — `BashExecutor` (abstract seam)
+
+Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a BashRunResult.
+- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.
+- BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
+- A still-running background process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a background process survives an executor-only reload.
+
+```ts cordis-catalog
+/**
+ * Apply implementation-owned defaults and caps to a request before execution.
+ * @param request - the caller's request; omitted fields get this
+ *   implementation's defaults, capped fields are clamped.
+ * @returns the fully-specified spec to hand to {@link run}/{@link start}.
+ */
+abstract resolve(request: BashExecRequest): BashExecSpec
+
+/**
+ * Run a command in the foreground; resolves when it finishes.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the outcome; nonzero exits, timeout kills, and abort kills
+ *   resolve with a descriptive result rather than reject.
+ */
+abstract run(spec: BashExecSpec): Promise<BashRunResult>
+
+/**
+ * Start a background process and return its handle immediately.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the live process handle (reads, kill, quiescence promise).
+ */
+abstract start(spec: BashExecSpec): BashProcess
+```
+
+Source: [`packages/bash/bash/src/index.ts:53`](../../packages/bash/bash/src/index.ts)
+
+<a id="ctxbashenv--bashenvregistry"></a>
+
+### `ctx.bashEnv` — `BashEnvRegistry`
+
+Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model shell call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.
+
+```ts cordis-catalog
+/**
+ * Register one environment contributor. Names and keys are unique; built-in
+ * keys are reserved. Registration is disposed with the calling plugin fiber.
+ * @param contributor - declared key ownership and per-execution resolver.
+ * @returns the disposer that unregisters the contribution.
+ */
+register(contributor: BashEnvContributor): () => void
+
+/**
+ * Build the trusted `DSH_*` snapshot for one shell tool execution.
+ * @param execution - the current tool execution.
+ * @returns an immutable environment overlay containing built-ins and current contributions.
+ */
+collect(execution: ToolExecution): DshEnvironment
+
+/**
+ * Enumerate plugin-contributed variables without executing their resolvers.
+ * @returns declarations sorted by environment variable name.
+ */
+list(): BashEnvVariableInfo[]
+```
+
+Types: [DshEnvironment](subprocess.md) · [ToolExecution](tools.md)
+
+Source: [`packages/bash/bash-env/src/index.ts:89`](../../packages/bash/bash-env/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index 27ca9f6e5a..bba9ece295 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -219,3 +219,85 @@ interface BashProcessRead {
 ## 服务
 
 `BashExecutor` 拥有 `resolve`、前台 `run`、后台进程 `start` 以及 `sandboxMode` 能力事实。`dsh-bash-local` 拥有命令默认值补全、超时/中止分类、终端环境以及后台读取合并；进程组、有界收集器、spill 文件、凭据清除与 dispose（资源释放）后完全停稳归[进程管理器](subprocess.md)所有。`dsh-tool-bash` 拥有面向模型的渲染，并将后台句柄适配到[通用任务运行时](tasks.md)。`dsh-bash` 拥有 shell 工具共享的退出状态契约：导出的 `parseExitStatus`/`ParsedExitStatus` 是 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]` / `[killed by signal: X]` 标记的逆解析，两个工具的 `presentResult` 都用它把渲染文本拆分为 terminal 卡的输出正文与退出状态 pill。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxbash--bashexecutor-abstract-seam"></a>
+
+### `ctx.bash` — `BashExecutor` (abstract seam)
+
+Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a BashRunResult.
+- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.
+- BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
+- A still-running background process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a background process survives an executor-only reload.
+
+```ts cordis-catalog
+/**
+ * Apply implementation-owned defaults and caps to a request before execution.
+ * @param request - the caller's request; omitted fields get this
+ *   implementation's defaults, capped fields are clamped.
+ * @returns the fully-specified spec to hand to {@link run}/{@link start}.
+ */
+abstract resolve(request: BashExecRequest): BashExecSpec
+
+/**
+ * Run a command in the foreground; resolves when it finishes.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the outcome; nonzero exits, timeout kills, and abort kills
+ *   resolve with a descriptive result rather than reject.
+ */
+abstract run(spec: BashExecSpec): Promise<BashRunResult>
+
+/**
+ * Start a background process and return its handle immediately.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the live process handle (reads, kill, quiescence promise).
+ */
+abstract start(spec: BashExecSpec): BashProcess
+```
+
+Source: [`packages/bash/bash/src/index.ts:53`](../../packages/bash/bash/src/index.ts)
+
+<a id="ctxbashenv--bashenvregistry"></a>
+
+### `ctx.bashEnv` — `BashEnvRegistry`
+
+Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model shell call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.
+
+```ts cordis-catalog
+/**
+ * Register one environment contributor. Names and keys are unique; built-in
+ * keys are reserved. Registration is disposed with the calling plugin fiber.
+ * @param contributor - declared key ownership and per-execution resolver.
+ * @returns the disposer that unregisters the contribution.
+ */
+register(contributor: BashEnvContributor): () => void
+
+/**
+ * Build the trusted `DSH_*` snapshot for one shell tool execution.
+ * @param execution - the current tool execution.
+ * @returns an immutable environment overlay containing built-ins and current contributions.
+ */
+collect(execution: ToolExecution): DshEnvironment
+
+/**
+ * Enumerate plugin-contributed variables without executing their resolvers.
+ * @returns declarations sorted by environment variable name.
+ */
+list(): BashEnvVariableInfo[]
+```
+
+Types: [DshEnvironment](subprocess.md) · [ToolExecution](tools.md)
+
+Source: [`packages/bash/bash-env/src/index.ts:89`](../../packages/bash/bash-env/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index f0df40a866..ae61603169 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.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 docs/subsystems/client-modules.md
-client-modules.md: 5dc89a87db7e79e4a297002fa059fdeffcceda20
-client-modules.zh.md: b3aa9c2aecf8e051a41b7b05f05d364b9ff8d2a6
+client-modules.md: 19bcc6304e9d917c3950fd9857e7b2c2b3c16e73
+client-modules.zh.md: b0ad293cad2f67de1982ef271308b2a7f06ebaf4
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
index 5dc89a87db..19bcc6304e 100644
--- a/docs/subsystems/client-modules.md
+++ b/docs/subsystems/client-modules.md
@@ -58,6 +58,61 @@ Package metadata — including the negative "not a client package" verdict — i
 
 ## The service
 
-`ClientModuleHostService` (`ctx.clientModuleHost`, defined in [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)) exposes reads and the rebuild face; signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxclientmodulehost--clientmodulehostservice). `graph()` returns the current composed graph (a stable object between changes) and `clientPath(id)` the bundle's absolute path. `rebuilt(id)` is the only entry point through which bundle content reaches the graph: it re-hashes the file, and only a real rev change recomposes the graph and notifies. `onRebuilt` fires per changed bundle with the new rev; `onGraphChanged` fires after any flush that recomposed the graph (row added or removed, or a rebuilt rev change) and is pull-model — listeners re-read `graph()`. Both notification paths contain listener exceptions so one throwing subscriber cannot skip later subscribers or kill whatever triggered the flush.
+`ClientModuleHostService` (`ctx.clientModuleHost`, defined in [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)) exposes reads and the rebuild face; signatures are in the generated [service catalog](#ctxclientmodulehost--clientmodulehostservice). `graph()` returns the current composed graph (a stable object between changes) and `clientPath(id)` the bundle's absolute path. `rebuilt(id)` is the only entry point through which bundle content reaches the graph: it re-hashes the file, and only a real rev change recomposes the graph and notifies. `onRebuilt` fires per changed bundle with the new rev; `onGraphChanged` fires after any flush that recomposed the graph (row added or removed, or a rebuilt rev change) and is pull-model — listeners re-read `graph()`. Both notification paths contain listener exceptions so one throwing subscriber cannot skip later subscribers or kill whatever triggered the flush.
 
 In development, [dsh-client-hmr](../../packages/client/hmr/README.md) is the registry's watch driver: its node half stat-polls every graph row's bundle from a synchronously captured baseline, calls `rebuilt(id)` on change, resyncs its watch set through `onGraphChanged`, and broadcasts rev changes to the browser half over SSE. Production graphs omit the HMR row entirely; the module host itself never watches files.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxclientmodulehost--clientmodulehostservice"></a>
+
+### `ctx.clientModuleHost` — `ClientModuleHostService`
+
+The web plugin table service: incremental dshClient scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
+
+```ts cordis-catalog
+/**
+ * Current composed entry graph (stable object between changes).
+ * @returns the graph served as `window.__DSH_BOOT__`.
+ */
+graph(): WebBootGraph
+
+/**
+ * Absolute path of an entry's client bundle.
+ * @param id - entry id (package name).
+ * @returns the path, or undefined for an unknown id.
+ */
+clientPath(id: string): string | undefined
+
+/**
+ * Re-hash one bundle (the HMR watch's registration hook — the only entry
+ * point through which bundle content changes reach the graph).
+ * @param id - entry id (package name).
+ * @returns the new rev, or undefined for an unknown id.
+ */
+rebuilt(id: string): string | undefined
+
+/**
+ * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+ * @param listener - receives the entry id and its new bundle rev.
+ * @returns the unsubscriber.
+ */
+onRebuilt(listener: (id: string, rev: string) => void): () => void
+
+/**
+ * Fires after any flush that recomposed the graph (row added/removed, or a
+ * rebuilt rev change). Pull model: listeners re-read {@link graph}.
+ * @param listener - notified with no payload.
+ * @returns the unsubscriber.
+ */
+onGraphChanged(listener: () => void): () => void
+```
+
+Source: [`packages/client/modules/src/index.ts:184`](../../packages/client/modules/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index b3aa9c2aec..b0ad293cad 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -58,6 +58,61 @@ interface WebBootGraph {
 
 ## 服务
 
-`ClientModuleHostService`（`ctx.clientModuleHost`，定义于 [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)）暴露读取面与重建面；签名见生成的[服务目录](../cordis-catalog/services.md#ctxclientmodulehost--clientmodulehostservice)。`graph()` 返回当前组合出的图（两次变更之间是同一个稳定对象），`clientPath(id)` 返回该 bundle 的绝对路径。`rebuilt(id)` 是 bundle 内容到达图的唯一入口：它对文件重新哈希，只有 rev 真正变化才会重新组合图并发出通知。`onRebuilt` 按发生变化的 bundle 逐个触发并携带新 rev；`onGraphChanged` 在任何一次重新组合了图的 flush 之后触发（行的增删，或 rebuilt 带来的 rev 变化），并采用拉取模型——监听器自行重读 `graph()`。两条通知路径都会兜住监听器异常，因此一个抛错的订阅者既不能让后续订阅者被跳过，也不能杀死触发这次 flush 的一方。
+`ClientModuleHostService`（`ctx.clientModuleHost`，定义于 [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)）暴露读取面与重建面；签名见生成的[服务目录](#ctxclientmodulehost--clientmodulehostservice)。`graph()` 返回当前组合出的图（两次变更之间是同一个稳定对象），`clientPath(id)` 返回该 bundle 的绝对路径。`rebuilt(id)` 是 bundle 内容到达图的唯一入口：它对文件重新哈希，只有 rev 真正变化才会重新组合图并发出通知。`onRebuilt` 按发生变化的 bundle 逐个触发并携带新 rev；`onGraphChanged` 在任何一次重新组合了图的 flush 之后触发（行的增删，或 rebuilt 带来的 rev 变化），并采用拉取模型——监听器自行重读 `graph()`。两条通知路径都会兜住监听器异常，因此一个抛错的订阅者既不能让后续订阅者被跳过，也不能杀死触发这次 flush 的一方。
 
 开发环境下，[dsh-client-hmr](../../packages/client/hmr/README.md) 是注册表的监视驱动：它的 Node 半从同步取得的基线出发，对图中每一行的 bundle 做 stat 轮询，变化时调用 `rebuilt(id)`，经 `onGraphChanged` 重新同步监视集合，并通过 SSE（Server-Sent Events）把 rev 变化广播给浏览器半。生产环境的图完全不含 HMR（热模块替换）行；模块宿主自身从不监视文件。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxclientmodulehost--clientmodulehostservice"></a>
+
+### `ctx.clientModuleHost` — `ClientModuleHostService`
+
+The web plugin table service: incremental dshClient scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
+
+```ts cordis-catalog
+/**
+ * Current composed entry graph (stable object between changes).
+ * @returns the graph served as `window.__DSH_BOOT__`.
+ */
+graph(): WebBootGraph
+
+/**
+ * Absolute path of an entry's client bundle.
+ * @param id - entry id (package name).
+ * @returns the path, or undefined for an unknown id.
+ */
+clientPath(id: string): string | undefined
+
+/**
+ * Re-hash one bundle (the HMR watch's registration hook — the only entry
+ * point through which bundle content changes reach the graph).
+ * @param id - entry id (package name).
+ * @returns the new rev, or undefined for an unknown id.
+ */
+rebuilt(id: string): string | undefined
+
+/**
+ * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+ * @param listener - receives the entry id and its new bundle rev.
+ * @returns the unsubscriber.
+ */
+onRebuilt(listener: (id: string, rev: string) => void): () => void
+
+/**
+ * Fires after any flush that recomposed the graph (row added/removed, or a
+ * rebuilt rev change). Pull model: listeners re-read {@link graph}.
+ * @param listener - notified with no payload.
+ * @returns the unsubscriber.
+ */
+onGraphChanged(listener: () => void): () => void
+```
+
+Source: [`packages/client/modules/src/index.ts:184`](../../packages/client/modules/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index 02bbc9587a..05e7e67ed1 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.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 docs/core-data-structures/code-runtime.md
-code-runtime.md: fbce7d812b7609716fb43ae01610253008e0a92c
-code-runtime.zh.md: 700146cfaa9cfab37ec4d85e550020acf1d9f294
+#   pnpm run verify-translation-pairing --write docs/subsystems/code-runtime.md
+code-runtime.md: 12779f1aafc8930410ae0d695e3f617caafcf607
+code-runtime.zh.md: de563dd3430348f5cf3675d4bf124adeba170559
diff --git a/docs/subsystems/code-runtime.md b/docs/subsystems/code-runtime.md
index fbce7d812b..12779f1aaf 100644
--- a/docs/subsystems/code-runtime.md
+++ b/docs/subsystems/code-runtime.md
@@ -159,3 +159,33 @@ interface CodeRunFailure {
 ## The service
 
 `CodeRuntime` (`ctx.codeRuntime`, abstract — defined in [`packages/code-runtime/code-runtime/src/index.ts`](../../packages/code-runtime/code-runtime/src/index.ts)) is `run(request)` plus two readonly descriptors: `language` (what the program must be written in — `'typescript'` and `'python'` are the well-known values, those `dsh-tools` presents, and only `'typescript'` has a published backend; a consumer generating language-specific presentation switches on it and fails loud on one it cannot present) and `isolation` (the execution substrate — `'worker-thread'`, `'process'`, `'container'`; a diagnostic label, **not a security claim**). Implementations must keep runs isolated from each other (no cross-run state) and dispose to quiescence: in-flight runs are terminated and awaited before teardown completes.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
+
+### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
+
+Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
+
+```ts cordis-catalog
+/**
+ * Execute one program against the request's bindings and capture what it
+ * emitted. See the class doc for the resolution contract (error is a result
+ * field; rejection means seam misuse only).
+ * @param request - the program, its bindings, and the abort signal; the
+ *   request carries everything the runtime acts on, with no hidden defaults.
+ * @returns the run's outcome: completion value (when transferable), the
+ *   ordered log capture, and the failure (if any).
+ */
+abstract run(request: CodeRunRequest): Promise<CodeRunResult>
+```
+
+Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index 700146cfaa..de563dd343 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -159,3 +159,33 @@ interface CodeRunFailure {
 ## 服务
 
 `CodeRuntime`（`ctx.codeRuntime`，抽象服务，定义于 [`packages/code-runtime/code-runtime/src/index.ts`](../../packages/code-runtime/code-runtime/src/index.ts)）由 `run(request)` 加两个只读描述符组成：`language`（程序必须使用的语言，已知值为 `'typescript'` 与 `'python'`，即 `dsh-tools` 能呈现的那些，其中只有 `'typescript'` 有已发布的后端；生成语言相关展示的消费方据此切换，遇到无法展示的语言时应显式报错）和 `isolation`（执行基底，`'worker-thread'`、`'process'`、`'container'`；仅为诊断标签，**不构成安全承诺**）。实现必须保证各次运行彼此隔离（无跨运行状态），并在 dispose（资源释放）时等待系统完全停稳：teardown 要等到所有进行中的运行均已终止并结算后才完成。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
+
+### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
+
+Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
+
+```ts cordis-catalog
+/**
+ * Execute one program against the request's bindings and capture what it
+ * emitted. See the class doc for the resolution contract (error is a result
+ * field; rejection means seam misuse only).
+ * @param request - the program, its bindings, and the abort signal; the
+ *   request carries everything the runtime acts on, with no hidden defaults.
+ * @returns the run's outcome: completion value (when transferable), the
+ *   ordered log capture, and the failure (if any).
+ */
+abstract run(request: CodeRunRequest): Promise<CodeRunResult>
+```
+
+Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
index a741971a9a..3bd5420573 100644
--- a/docs/subsystems/commands.i18n.yaml
+++ b/docs/subsystems/commands.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 docs/subsystems/commands.md
-commands.md: 83ce9c2498df58110d9a9c2e7d5163a9df813e1c
-commands.zh.md: c486f480177c7ff8b35cc846beafac009cea42bb
+commands.md: c1ab6d9782f515321104d0cf4d9e037c6a68a18d
+commands.zh.md: 3b3d8def042b107c5098e76c511424f023975e77
diff --git a/docs/subsystems/commands.md b/docs/subsystems/commands.md
index 83ce9c2498..c1ab6d9782 100644
--- a/docs/subsystems/commands.md
+++ b/docs/subsystems/commands.md
@@ -97,3 +97,89 @@ interface ParsedCommand {
   readonly rawInput: string
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcommands--commandservice"></a>
+
+### `ctx.commands` — `CommandService`
+
+Human-command registry. Plain-context definitions are global; definitions registered through a command-injected child of an agent context shadow globals for that agent.
+
+```ts cordis-catalog
+/**
+ * Register a global or calling-agent-scoped command.
+ * @param definition - discovery metadata and direct UI handler.
+ * @returns the exact effect disposer that unregisters this definition.
+ */
+register(definition: CommandDefinition): () => void
+
+/**
+ * List the effective immutable command descriptors for one agent.
+ * @param agent - exact receiving agent and scoped-layer key.
+ * @returns name-sorted descriptors after scoped shadowing.
+ */
+list(agent: Agent): readonly CommandDescriptor[]
+
+/**
+ * Resolve one effective command definition.
+ * @param agent - exact receiving agent and scoped-layer key.
+ * @param name - command name without a slash.
+ * @returns the scoped shadow or global definition.
+ */
+find(agent: Agent, name: string): CommandDefinition | undefined
+
+/**
+ * Parse and execute a known command without sending it to the model.
+ *
+ * A resolved command's lifecycle is logged: `command/run` is appended
+ * before the handler is invoked and `command/done` after settlement (a
+ * thrown or aborted handler settles as `kind: 'error'`). Both are direct
+ * log-only appends — no turn wraps them, and persistence drains them at
+ * ordinary checkpoints. Admission misses (syntax or unknown name) log
+ * nothing — they never entered a handler. A `command/run` append failure
+ * fails the execution loud; a `command/done` append failure on the
+ * handler-failure path is contained so the handler's own error stays the
+ * reported failure.
+ *
+ * @param agent - exact receiving agent.
+ * @param line - complete slash-command line.
+ * @param signal - cancellation signal owned by the UI request.
+ * @returns the settled execution (result + lifecycle pairing id), or
+ *   `undefined` when syntax or name does not resolve.
+ */
+async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
+
+<a id="commands-events"></a>
+
+### `commands/*` events
+
+<a id="commandschange--emit"></a>
+
+#### `commands/change` — emit
+
+A command was registered or unregistered. This is an unfiltered registry notification because a global or scoped change may affect any UI view. Observer failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * A command was registered or unregistered. This is an unfiltered registry
+ * notification because a global or scoped change may affect any UI view.
+ * Observer failures are contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'commands/change'(): void
+```
+
+Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/commands.zh.md b/docs/subsystems/commands.zh.md
index c486f48017..3b3d8def04 100644
--- a/docs/subsystems/commands.zh.md
+++ b/docs/subsystems/commands.zh.md
@@ -97,3 +97,89 @@ interface ParsedCommand {
   readonly rawInput: string
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcommands--commandservice"></a>
+
+### `ctx.commands` — `CommandService`
+
+Human-command registry. Plain-context definitions are global; definitions registered through a command-injected child of an agent context shadow globals for that agent.
+
+```ts cordis-catalog
+/**
+ * Register a global or calling-agent-scoped command.
+ * @param definition - discovery metadata and direct UI handler.
+ * @returns the exact effect disposer that unregisters this definition.
+ */
+register(definition: CommandDefinition): () => void
+
+/**
+ * List the effective immutable command descriptors for one agent.
+ * @param agent - exact receiving agent and scoped-layer key.
+ * @returns name-sorted descriptors after scoped shadowing.
+ */
+list(agent: Agent): readonly CommandDescriptor[]
+
+/**
+ * Resolve one effective command definition.
+ * @param agent - exact receiving agent and scoped-layer key.
+ * @param name - command name without a slash.
+ * @returns the scoped shadow or global definition.
+ */
+find(agent: Agent, name: string): CommandDefinition | undefined
+
+/**
+ * Parse and execute a known command without sending it to the model.
+ *
+ * A resolved command's lifecycle is logged: `command/run` is appended
+ * before the handler is invoked and `command/done` after settlement (a
+ * thrown or aborted handler settles as `kind: 'error'`). Both are direct
+ * log-only appends — no turn wraps them, and persistence drains them at
+ * ordinary checkpoints. Admission misses (syntax or unknown name) log
+ * nothing — they never entered a handler. A `command/run` append failure
+ * fails the execution loud; a `command/done` append failure on the
+ * handler-failure path is contained so the handler's own error stays the
+ * reported failure.
+ *
+ * @param agent - exact receiving agent.
+ * @param line - complete slash-command line.
+ * @param signal - cancellation signal owned by the UI request.
+ * @returns the settled execution (result + lifecycle pairing id), or
+ *   `undefined` when syntax or name does not resolve.
+ */
+async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
+
+<a id="commands-events"></a>
+
+### `commands/*` events
+
+<a id="commandschange--emit"></a>
+
+#### `commands/change` — emit
+
+A command was registered or unregistered. This is an unfiltered registry notification because a global or scoped change may affect any UI view. Observer failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * A command was registered or unregistered. This is an unfiltered registry
+ * notification because a global or scoped change may affect any UI view.
+ * Observer failures are contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'commands/change'(): void
+```
+
+Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 7dc00cebfc..5481b2feb1 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: f1df5b83bd43136af60988dabd9dc68fe32467a2
-compaction.zh.md: 52540250d466f81f51cf7c681bb6f1436e29a12d
+compaction.md: 126c6c7c7df125cf991ea074e0165481c09455dc
+compaction.zh.md: 9fb01a41a92367b9bb3f4586f35b5d0baf613bbc
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index f1df5b83bd..126c6c7c7d 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -112,3 +112,119 @@ interface PruneResult {
   readonly charsRemoved: number
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcompact--compactservice-abstract-seam"></a>
+
+### `ctx.compact` — `CompactService` (abstract seam)
+
+Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
+
+```ts cordis-catalog
+/**
+ * Consider automatic compaction for one explicit trigger. Pressure policy
+ * uses the latest durable routed request, while context-overflow policy may
+ * force a useful balanced reduction even below the normal threshold. Return
+ * `null` when no safe range can be compacted. A single oversized retained
+ * unit or request envelope cannot be repaired through surface compaction.
+ *
+ * @param agent - agent context owning the session surface and routing options.
+ * @param trigger - normal pressure or provider-confirmed context overflow.
+ * @param signal - cancellation signal; model-backed implementations must forward it.
+ * @returns the compaction result, or `null` if no compaction was needed.
+ */
+abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise<CompactionResult | null>
+
+/**
+ * Explicitly compact useful history even below automatic pressure thresholds.
+ * Implementations synchronously start an idle task before any asynchronous
+ * work, select a useful range without writing on a no-op, then
+ * append a standalone `compact/start` before summarization. That durable
+ * marker is the compaction lock until one `compact/end` attempt. Later waking
+ * prompts remain accepted in FIFO order and start only after the optional
+ * durability checkpoint and idle-task settlement. Context injected while the
+ * summary runs may sit between the marker pair; only the selected span must
+ * remain stable.
+ *
+ * @param agent - idle agent whose durable history should be compacted.
+ * @param signal - cancellation scoped to this compaction request.
+ * @returns the compaction result, or `null` when no safe useful range exists.
+ * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
+ * changed-span, summarization/shrink, commit-stage, or persistence failures;
+ * an aborted request preserves its exact abort reason. Failed attempts remain
+ * visible in the log.
+ */
+abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>
+
+/**
+ * Forcibly compact a range of surface nodes into a single summary node.
+ * `start` and `end` name an inclusive span by surface position, not numeric seq
+ * order; replacements can make visible seqs non-monotonic. Both edges must be
+ * balanced so assistant tool calls remain paired with their results. A model-
+ * backed implementation forwards cancellation and rejects active, missing,
+ * reversed, or unbalanced ranges. The target session is `agent.session`.
+ * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
+ * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
+ * for the edge checks.
+ *
+ * @param start - first surface seq, inclusive.
+ * @param end - last surface seq, inclusive.
+ * @param agent - context whose session is mutated and whose routing options guide summarization.
+ * @param signal - optional cancellation; model-backed implementations must forward it.
+ * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+ * @returns the appended event seqs, summary, replaced range, and token accounting.
+ */
+abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
+```
+
+Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
+
+<a id="ctxtoolresultprune--toolresultpruneservice"></a>
+
+### `ctx.toolResultPrune` — `ToolResultPruneService`
+
+Deterministic head/middle/tail pruning for current tool-result surface nodes.
+
+```ts cordis-catalog
+/**
+ * Measure text content in Unicode code points; non-text blocks cost zero.
+ * @param blocks - tool-result content to measure.
+ * @returns total Unicode code points across text blocks.
+ */
+measureContent(blocks: readonly ContentBlock[]): number
+
+/**
+ * Replace an over-budget text middle while retaining rich-block order.
+ * Text slicing is by Unicode code point, not UTF-16 code unit, so a retained
+ * boundary cannot split a surrogate pair. Grapheme clusters may still split.
+ * @param blocks - original tool-result content.
+ * @returns pruned content, or `null` when the text is within budget.
+ */
+pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
+
+/**
+ * Prune every over-budget tool result from one stable current-surface snapshot.
+ * Each replacement preserves the complete event data except for `content`,
+ * points at the shadowed node for durable provenance and replay, and is
+ * immediately preceded by a `compact/prune` shadow-price event pricing the
+ * shadowed node through the injected token meter, so pure consumers can
+ * subtract it without per-node state.
+ * @param session - session whose current surface is rewritten.
+ * @returns landed replacements and aggregate Unicode-code-point savings.
+ * @throws when the session rejects a replacement; replacements committed
+ * earlier in the pass remain durable.
+ */
+pruneSession(session: Session): PruneResult
+```
+
+Types: [ContentBlock](core.md) · [Session](session.md)
+
+Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 52540250d4..9fb01a41a9 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -112,3 +112,119 @@ interface PruneResult {
   readonly charsRemoved: number
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcompact--compactservice-abstract-seam"></a>
+
+### `ctx.compact` — `CompactService` (abstract seam)
+
+Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
+
+```ts cordis-catalog
+/**
+ * Consider automatic compaction for one explicit trigger. Pressure policy
+ * uses the latest durable routed request, while context-overflow policy may
+ * force a useful balanced reduction even below the normal threshold. Return
+ * `null` when no safe range can be compacted. A single oversized retained
+ * unit or request envelope cannot be repaired through surface compaction.
+ *
+ * @param agent - agent context owning the session surface and routing options.
+ * @param trigger - normal pressure or provider-confirmed context overflow.
+ * @param signal - cancellation signal; model-backed implementations must forward it.
+ * @returns the compaction result, or `null` if no compaction was needed.
+ */
+abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise<CompactionResult | null>
+
+/**
+ * Explicitly compact useful history even below automatic pressure thresholds.
+ * Implementations synchronously start an idle task before any asynchronous
+ * work, select a useful range without writing on a no-op, then
+ * append a standalone `compact/start` before summarization. That durable
+ * marker is the compaction lock until one `compact/end` attempt. Later waking
+ * prompts remain accepted in FIFO order and start only after the optional
+ * durability checkpoint and idle-task settlement. Context injected while the
+ * summary runs may sit between the marker pair; only the selected span must
+ * remain stable.
+ *
+ * @param agent - idle agent whose durable history should be compacted.
+ * @param signal - cancellation scoped to this compaction request.
+ * @returns the compaction result, or `null` when no safe useful range exists.
+ * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
+ * changed-span, summarization/shrink, commit-stage, or persistence failures;
+ * an aborted request preserves its exact abort reason. Failed attempts remain
+ * visible in the log.
+ */
+abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>
+
+/**
+ * Forcibly compact a range of surface nodes into a single summary node.
+ * `start` and `end` name an inclusive span by surface position, not numeric seq
+ * order; replacements can make visible seqs non-monotonic. Both edges must be
+ * balanced so assistant tool calls remain paired with their results. A model-
+ * backed implementation forwards cancellation and rejects active, missing,
+ * reversed, or unbalanced ranges. The target session is `agent.session`.
+ * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
+ * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
+ * for the edge checks.
+ *
+ * @param start - first surface seq, inclusive.
+ * @param end - last surface seq, inclusive.
+ * @param agent - context whose session is mutated and whose routing options guide summarization.
+ * @param signal - optional cancellation; model-backed implementations must forward it.
+ * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+ * @returns the appended event seqs, summary, replaced range, and token accounting.
+ */
+abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
+```
+
+Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
+
+<a id="ctxtoolresultprune--toolresultpruneservice"></a>
+
+### `ctx.toolResultPrune` — `ToolResultPruneService`
+
+Deterministic head/middle/tail pruning for current tool-result surface nodes.
+
+```ts cordis-catalog
+/**
+ * Measure text content in Unicode code points; non-text blocks cost zero.
+ * @param blocks - tool-result content to measure.
+ * @returns total Unicode code points across text blocks.
+ */
+measureContent(blocks: readonly ContentBlock[]): number
+
+/**
+ * Replace an over-budget text middle while retaining rich-block order.
+ * Text slicing is by Unicode code point, not UTF-16 code unit, so a retained
+ * boundary cannot split a surrogate pair. Grapheme clusters may still split.
+ * @param blocks - original tool-result content.
+ * @returns pruned content, or `null` when the text is within budget.
+ */
+pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
+
+/**
+ * Prune every over-budget tool result from one stable current-surface snapshot.
+ * Each replacement preserves the complete event data except for `content`,
+ * points at the shadowed node for durable provenance and replay, and is
+ * immediately preceded by a `compact/prune` shadow-price event pricing the
+ * shadowed node through the injected token meter, so pure consumers can
+ * subtract it without per-node state.
+ * @param session - session whose current surface is rewritten.
+ * @returns landed replacements and aggregate Unicode-code-point savings.
+ * @throws when the session rejects a replacement; replacements committed
+ * earlier in the pass remain durable.
+ */
+pruneSession(session: Session): PruneResult
+```
+
+Types: [ContentBlock](core.md) · [Session](session.md)
+
+Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index a2af261bc6..48d6fc9c71 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 3a8ccbef4163eabba1cd287284eda68135f2db13
-core.zh.md: 0cd6a57971ee98c75b52dd45b6f648632dab8a90
+core.md: 7e62de88519e5c0bf3a1a0b94de93635767f9f7b
+core.zh.md: ef5b70ae336d55fd25c2251372705912473d07f7
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 3a8ccbef41..7e62de8851 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -53,9 +53,10 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
 | [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
 | [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
+| [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
 | [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
 
-> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](../cordis-catalog/services.md).
+> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](#cordis-surface).
 
 ## The `…Map → derived-union` pattern
 
@@ -780,3 +781,546 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 The one pipeline-authoring type that is core: what every registered tool *is* — a model-facing `ToolSchema` plus an `execute` function and optional final-content and UI callbacks. A tool author rarely constructs it by hand (the `defineTool` DSL builds it with typed args), but it is the contract the registry holds and the loop dispatches through.
 
 Its full fields, the `defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` typed schema DSL, the `ToolExecution`/`ToolExecutionResult` waterfall shapes, and the tool-presentation UI vocabulary are on **[tools.md](tools.md)**.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxagentloop--agentloop"></a>
+
+### `ctx.agentLoop` — `AgentLoop`
+
+Concrete agent factory and driver service.
+
+```ts cordis-catalog
+/**
+ * Create an agent and session under one caller-supplied identity, owned by
+ * the accessing fiber. Constructor-driven config calls mint a fresh combined
+ * id before entering this boundary.
+ * @param id - shared agent/session identity.
+ * @param options - concrete loop options.
+ * @param meta - optional fresh-session workspace metadata.
+ * @returns the published running agent.
+ */
+create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent
+
+/**
+ * Create an owned agent on a caller-supplied session id.
+ * @param ownerCtx - caller context that structurally owns the lifecycle.
+ * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
+async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
+
+/**
+ * Resume an owned agent from the configured persistence service.
+ * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+ * @param options - persisted identity, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
+async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
+```
+
+Types: [SessionHeader](persistence.md)
+
+Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
+
+<a id="ctxagents--agentregistry"></a>
+
+### `ctx.agents` — `AgentRegistry`
+
+Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
+
+Initiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.
+
+```ts cordis-catalog
+/**
+ * Read the Agent that initiated the inherited asynchronous driver chain.
+ * Use this optional form for logging, tracing, metrics, or host attribution
+ * that also supports agentless calls. When a parent creates a child, setup
+ * reports the causal parent while `agentCtx.agent` identifies the child.
+ * @returns the inherited Agent, or `undefined` outside an initiator boundary
+ *   and inside an explicit clearing boundary.
+ * @throws when this service instance has been disposed.
+ */
+currentInitiator(): Agent | undefined
+
+/**
+ * Read the initiating Agent and fail when no initiator boundary is active.
+ * Use this for private helpers contractually below a driver, or for a
+ * deployment-owned outbound request whose contract forbids agentless calls.
+ * Generic or direct-call seams use optional lookup or explicit request fields.
+ * @returns the inherited Agent.
+ * @throws when no initiator is active or this service instance has been disposed.
+ */
+requireInitiator(): Agent
+
+/**
+ * Run an operation with one exact Agent as its process-local initiator. The
+ * exact synchronous value or Promise returned by the operation is preserved.
+ * Custom drivers and test harnesses wrap their complete returned foreground
+ * lifetime.
+ * A queue or wire receiver may establish this boundary only after validating
+ * explicit identity and resolving the exact live Agent; this method does neither.
+ * Detached work remains owned by the subsystem that starts it.
+ * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
+ * @param operation - synchronous or asynchronous operation to invoke.
+ * @returns the exact value returned by `operation`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+withInitiator<T>(agent: Agent, operation: () => T): T
+
+/**
+ * Run an operation inside a boundary that hides any inherited initiating
+ * Agent. The exact synchronous value or Promise is preserved.
+ * Use this while creating lazy shared timers, queue pumps, pool maintenance,
+ * watchers, or exporters so they do not inherit the first Agent that happens
+ * to initialize them. It clears only initiator attribution, not explicit
+ * fields, and does not own or drain detached resources.
+ * @param operation - synchronous or asynchronous operation to invoke without an initiator.
+ * @returns the exact value returned by `operation`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+withoutInitiator<T>(operation: () => T): T
+
+/**
+ * Register the agent-creation factory (the loop calls this on construction,
+ * effect-scoped). A traced Cordis service is canonicalized to its concrete
+ * target; each create/resume call is then traced through that caller's
+ * context so ownership follows the caller without stacking proxy layers.
+ * Throws if a factory is already registered. Returns the disposer; on
+ * dispose the factory slot is cleared.
+ * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
+ * @returns the disposer that clears the factory slot. The exact
+ *   Cordis effect disposer (single-shot): composite (generator) effects may
+ *   yield it directly — exact identity nests the teardown in order.
+ */
+setFactory(factory: AgentFactory): () => void
+
+/**
+ * Create and publish a new agent through the registered factory.
+ * Distinct from {@link register} (which records an already-constructed
+ * agent): this constructs the agent and its session. Rejects if no factory is
+ * registered or creation/setup fails. The resolved {@link AgentHandle} lets
+ * the owner tear down exactly this agent.
+ * @param options - shared identity, session seed/metadata, and agent options.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
+async create(options: CreateAgentOptions): Promise<AgentHandle>
+
+/**
+ * Load a persisted session and resume an agent on it through the registered
+ * factory. Rejects if no factory is registered; the factory rejects if
+ * session persistence is not configured or persistence/setup fails.
+ * @param options - persisted identity, configuration, and optional setup.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
+async resume(options: ResumeAgentOptions): Promise<AgentHandle>
+
+/**
+ * Register a live agent. Throws if an agent with the same id is already
+ * registered. Emits `agent/created` on registration and `agent/disposed`
+ * when the calling fiber is disposed — both with the agent's scope carrier
+ * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
+ * emits are scope-filtered regardless of which context invoked `register`
+ * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
+ * requires passing the carrier). Returns the disposer.
+ * @param agent - the already-constructed agent to record in the store.
+ * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
+ *   returns undefined without awaiting an in-flight teardown). Exact
+ *   identity is load-bearing: a composite (generator) effect that owns a
+ *   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
+ *   function so Cordis nests the unregistration at that yield position;
+ *   yielding a wrapper would leave it disposing as a concurrent sibling on
+ *   owner unload, unregistering the agent (and emitting `agent/disposed`)
+ *   while its final turn is still draining.
+ */
+register(agent: Agent): () => void
+
+/**
+ * Insert an already-constructed agent without announcing it. This is the
+ * advanced ordered-lifecycle primitive used by the async agent factory: it
+ * first completes setup while the agent is unpublished, then assigns the
+ * returned detach closure into its pre-installed composite teardown before
+ * calling {@link announce}. Ordinary callers use {@link register}.
+ * @param agent - the prepared, unpublished agent.
+ * @param owner - live agent whose scoped context created this agent, or
+ *   undefined for a top-level runtime root. This is runtime ownership, not
+ *   the resumed session's durable parent lineage.
+ * @returns an idempotent closure that removes this exact entry and emits
+ *   `agent/disposed` with listener failures contained. When called from a
+ *   synchronous `agent/created` listener, removal and disposal wait until
+ *   that creation dispatch unwinds.
+ */
+enter(agent: Agent, owner: Agent | undefined): () => void
+
+/**
+ * Announce an agent previously inserted with {@link enter}.
+ * @param agent - the live inserted agent to announce.
+ * @throws if `agent` is not the exact live registry entry for its id, or its
+ *   creation announcement already began (including a reentrant call from a
+ *   creation listener).
+ */
+announce(agent: Agent): void
+
+/**
+ * Look up a live agent.
+ * @param id - the shared agent/session id to look up.
+ * @returns the agent, or undefined when no live agent has that id.
+ */
+get(id: SessionId): Agent | undefined
+
+/**
+ * Test whether a live agent was created through one exact parent agent's
+ * scoped context. Runtime ownership is independent of durable session
+ * lineage and remains unambiguous when unrelated providers reuse an id.
+ * @param id - the candidate child agent's shared agent/session id.
+ * @param owner - the expected runtime creator agent.
+ * @returns true only while the exact child entry is live under that owner.
+ */
+isOwnedBy(id: SessionId, owner: Agent): boolean
+
+/**
+ * All live agents, in registration order.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
+list(): Agent[]
+
+/**
+ * All live top-level agents in registration order. A top-level agent was
+ * created without an owning agent context; durable session lineage does not
+ * affect this runtime relation, so a resumed fork may still be a root.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
+roots(): Agent[]
+```
+
+Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+
+<a id="agent-events"></a>
+
+### `agent/*` events
+
+<a id="agentcreated--emit"></a>
+
+#### `agent/created` — emit
+
+A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
+
+```ts cordis-catalog
+/**
+ * A fully configured agent and live session were published. Setup is
+ * composition-only; `agent/session-start` is the first startup-driving seam.
+ * Synchronous listener failure vetoes publication, while returned-promise
+ * rejection is reported. Detach requested during dispatch waits until every
+ * creation listener has observed the stable entry.
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
+
+<a id="agentdisposed--emit"></a>
+
+#### `agent/disposed` — emit
+
+An agent left the registry; AgentLoop emits this after driver quiescence and scoped-registration unwind, but before session detachment. Custom registry users own their driver-ordering contract.
+
+```ts cordis-catalog
+/**
+ * An agent left the registry; AgentLoop emits this after driver quiescence
+ * and scoped-registration unwind, but before session detachment. Custom
+ * registry users own their driver-ordering contract.
+ * @param payload.agent - the exact agent removed from the registry.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
+
+<a id="agenterror--emit"></a>
+
+#### `agent/error` — emit
+
+A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
+
+```ts cordis-catalog
+/**
+ * A step or turn errored. The machine reports a failure here even when
+ * the error has no in-turn position for a durable record.
+ * @param payload.agent - the agent whose turn errored.
+ * @param payload.turn - the turn in which the failure surfaced.
+ * @param payload.step - the step at which the failure surfaced.
+ * @param payload.error - the failure, verbatim.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxclaimed--emit"></a>
+
+#### `agent/inbox/claimed` — emit
+
+One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
+
+```ts cordis-catalog
+/**
+ * One message left the inbox inside its open turn. If the proposed step
+ * is rejected, the claimed message ends here: it is neither discarded nor
+ * re-emitted as a user/message, and the turn closes without a step.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the claimed message.
+ * @param payload.turn - the owning turn.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxdiscarded--emit"></a>
+
+#### `agent/inbox/discarded` — emit
+
+One message was discarded from the live inbox.
+
+```ts cordis-catalog
+/**
+ * One message was discarded from the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the discarded message.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxinserted--emit"></a>
+
+#### `agent/inbox/inserted` — emit
+
+One message entered the live inbox.
+
+```ts cordis-catalog
+/**
+ * One message entered the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the inserted message.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
+
+<a id="agentpre-step--waterfall"></a>
+
+#### `agent/pre-step` — waterfall
+
+Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
+
+```ts cordis-catalog
+/**
+ * Reject a proposed step or replace the messages that enter it. Calling
+ * `next()` preserves the current messages.
+ * @param payload.agent - the agent proposing the step.
+ * @param payload.messages - messages removed from the inbox for this step.
+ * @param payload.turn - the turn that will own the step.
+ * @param payload.step - the step proposed by the loop.
+ * @param payload.signal - the current turn's cancellation signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
+'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
+
+<a id="agentrequest--waterfall"></a>
+
+#### `agent/request` — waterfall
+
+Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this seam cannot mutate messages.
+
+```ts cordis-catalog
+/**
+ * Replace the frozen call configuration. `await next()` yields the config
+ * the machine would use (agent options on the first request, the logged
+ * header afterwards); return a replacement to switch. Model-visible
+ * content must use logged channels; this seam cannot mutate messages.
+ * @param payload.agent - the agent making the model call.
+ * @param payload.turn - the open turn number.
+ * @param payload.step - the step whose request this is.
+ * @param payload.signal - the current turn's explicit abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+*/
+'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
+
+<a id="agentrequest-error--waterfall"></a>
+
+#### `agent/request-error` — waterfall
+
+Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+
+```ts cordis-catalog
+/**
+ * Handle one failed model-request attempt before the loop retries or closes
+ * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
+ * when it owns recovery, or calls `next()` to delegate. The default
+ * `undefined` leaves the failure terminal.
+ * @param payload.agent - the agent whose request failed.
+ * @param payload.turn - the turn containing the failed request.
+ * @param payload.step - the step containing the failed request attempt.
+ * @param payload.provider - the provider selected for the failed request.
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
+ * @param payload.signal - the turn abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
+'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+```
+
+Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
+
+<a id="agentsession-start--emit"></a>
+
+#### `agent/session-start` — emit
+
+The session lifecycle began, once before the first turn. Use `agent.inject()` to seed model-facing context. This is a notification, not a veto; disposal requested by a lifecycle owner is rechecked before the driver starts.
+
+```ts cordis-catalog
+/**
+ * The session lifecycle began, once before the first turn. Use
+ * `agent.inject()` to seed model-facing context. This is a notification, not
+ * a veto; disposal requested by a lifecycle owner is rechecked before the
+ * driver starts.
+ * @param payload.agent - the agent whose session lifecycle began.
+ * @param payload.source - why the session started (fresh startup, resume, …).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
+
+<a id="agentstatus--emit"></a>
+
+#### `agent/status` — emit
+
+Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
+
+```ts cordis-catalog
+/**
+ * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
+ * `running` synchronously after reserving cancellation; `idle` means no
+ * driver remains scheduled or active.
+ * @param payload.agent - the agent whose status flipped.
+ * @param payload.status - the status just entered (the transition's destination).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
+
+<a id="agentturn-stopping--serial"></a>
+
+#### `agent/turn-stopping` — serial
+
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
+
+```ts cordis-catalog
+/**
+ * The turn is about to close: the model owes no response (no live tool
+ * calls, no fresh steering). Awaited before the boundary commits — a
+ * listener that objects steers (`agent.steer(...)`) and the machine
+ * re-reads its inbox: fresh steering runs another step, none closes the
+ * turn. Data decides, so listener order cannot change the outcome. The
+ * inverse control (stop a tool loop early) is data too: a tool result
+ * carrying `concludesTurn` ends the turn at its step. The conclusion
+ * never short-circuits already-submitted next-step work: same-step
+ * `additionalContexts` or racing steering still runs, and the turn
+ * closes only when that inbox drains.
+ * @param payload.agent - the agent whose turn is at its stop boundary.
+ * @param payload.turn - the turn about to close.
+ * @param payload.signal - the current turn's explicit abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode serial
+ */
+'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
+
+<a id="agent-loop-events"></a>
+
+### `agent-loop/*` events
+
+<a id="agent-loopconfig-start-failed--emit"></a>
+
+#### `agent-loop/config-start-failed` — emit
+
+A declarative agent entry failed before it could publish a live agent. Consumers that buffer work for the configured identity use this transient signal to reject that work instead of waiting forever. Normal factory teardown suppresses failures from the cancelled startup attempt.
+
+```ts cordis-catalog
+/**
+ * A declarative agent entry failed before it could publish a live agent.
+ * Consumers that buffer work for the configured identity use this
+ * transient signal to reject that work instead of waiting forever. Normal
+ * factory teardown suppresses failures from the cancelled startup attempt.
+ * @param payload.sessionId - exact shared agent/session identity that failed startup.
+ * @param payload.error - persistence, setup, or publication failure.
+ * @mode emit
+ */
+'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
+```
+
+Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 0cd6a57971..ef5b70ae33 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -53,9 +53,10 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
+| [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
 | [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
 
-> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](../cordis-catalog/services.md)。
+> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](#cordis-surface)。
 
 <a id="the-map--derived-union-pattern"></a>
 
@@ -788,3 +789,546 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
 
 其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxagentloop--agentloop"></a>
+
+### `ctx.agentLoop` — `AgentLoop`
+
+Concrete agent factory and driver service.
+
+```ts cordis-catalog
+/**
+ * Create an agent and session under one caller-supplied identity, owned by
+ * the accessing fiber. Constructor-driven config calls mint a fresh combined
+ * id before entering this boundary.
+ * @param id - shared agent/session identity.
+ * @param options - concrete loop options.
+ * @param meta - optional fresh-session workspace metadata.
+ * @returns the published running agent.
+ */
+create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent
+
+/**
+ * Create an owned agent on a caller-supplied session id.
+ * @param ownerCtx - caller context that structurally owns the lifecycle.
+ * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
+async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
+
+/**
+ * Resume an owned agent from the configured persistence service.
+ * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+ * @param options - persisted identity, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
+async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
+```
+
+Types: [SessionHeader](persistence.md)
+
+Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
+
+<a id="ctxagents--agentregistry"></a>
+
+### `ctx.agents` — `AgentRegistry`
+
+Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
+
+Initiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.
+
+```ts cordis-catalog
+/**
+ * Read the Agent that initiated the inherited asynchronous driver chain.
+ * Use this optional form for logging, tracing, metrics, or host attribution
+ * that also supports agentless calls. When a parent creates a child, setup
+ * reports the causal parent while `agentCtx.agent` identifies the child.
+ * @returns the inherited Agent, or `undefined` outside an initiator boundary
+ *   and inside an explicit clearing boundary.
+ * @throws when this service instance has been disposed.
+ */
+currentInitiator(): Agent | undefined
+
+/**
+ * Read the initiating Agent and fail when no initiator boundary is active.
+ * Use this for private helpers contractually below a driver, or for a
+ * deployment-owned outbound request whose contract forbids agentless calls.
+ * Generic or direct-call seams use optional lookup or explicit request fields.
+ * @returns the inherited Agent.
+ * @throws when no initiator is active or this service instance has been disposed.
+ */
+requireInitiator(): Agent
+
+/**
+ * Run an operation with one exact Agent as its process-local initiator. The
+ * exact synchronous value or Promise returned by the operation is preserved.
+ * Custom drivers and test harnesses wrap their complete returned foreground
+ * lifetime.
+ * A queue or wire receiver may establish this boundary only after validating
+ * explicit identity and resolving the exact live Agent; this method does neither.
+ * Detached work remains owned by the subsystem that starts it.
+ * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
+ * @param operation - synchronous or asynchronous operation to invoke.
+ * @returns the exact value returned by `operation`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+withInitiator<T>(agent: Agent, operation: () => T): T
+
+/**
+ * Run an operation inside a boundary that hides any inherited initiating
+ * Agent. The exact synchronous value or Promise is preserved.
+ * Use this while creating lazy shared timers, queue pumps, pool maintenance,
+ * watchers, or exporters so they do not inherit the first Agent that happens
+ * to initialize them. It clears only initiator attribution, not explicit
+ * fields, and does not own or drain detached resources.
+ * @param operation - synchronous or asynchronous operation to invoke without an initiator.
+ * @returns the exact value returned by `operation`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+withoutInitiator<T>(operation: () => T): T
+
+/**
+ * Register the agent-creation factory (the loop calls this on construction,
+ * effect-scoped). A traced Cordis service is canonicalized to its concrete
+ * target; each create/resume call is then traced through that caller's
+ * context so ownership follows the caller without stacking proxy layers.
+ * Throws if a factory is already registered. Returns the disposer; on
+ * dispose the factory slot is cleared.
+ * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
+ * @returns the disposer that clears the factory slot. The exact
+ *   Cordis effect disposer (single-shot): composite (generator) effects may
+ *   yield it directly — exact identity nests the teardown in order.
+ */
+setFactory(factory: AgentFactory): () => void
+
+/**
+ * Create and publish a new agent through the registered factory.
+ * Distinct from {@link register} (which records an already-constructed
+ * agent): this constructs the agent and its session. Rejects if no factory is
+ * registered or creation/setup fails. The resolved {@link AgentHandle} lets
+ * the owner tear down exactly this agent.
+ * @param options - shared identity, session seed/metadata, and agent options.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
+async create(options: CreateAgentOptions): Promise<AgentHandle>
+
+/**
+ * Load a persisted session and resume an agent on it through the registered
+ * factory. Rejects if no factory is registered; the factory rejects if
+ * session persistence is not configured or persistence/setup fails.
+ * @param options - persisted identity, configuration, and optional setup.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
+async resume(options: ResumeAgentOptions): Promise<AgentHandle>
+
+/**
+ * Register a live agent. Throws if an agent with the same id is already
+ * registered. Emits `agent/created` on registration and `agent/disposed`
+ * when the calling fiber is disposed — both with the agent's scope carrier
+ * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
+ * emits are scope-filtered regardless of which context invoked `register`
+ * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
+ * requires passing the carrier). Returns the disposer.
+ * @param agent - the already-constructed agent to record in the store.
+ * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
+ *   returns undefined without awaiting an in-flight teardown). Exact
+ *   identity is load-bearing: a composite (generator) effect that owns a
+ *   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
+ *   function so Cordis nests the unregistration at that yield position;
+ *   yielding a wrapper would leave it disposing as a concurrent sibling on
+ *   owner unload, unregistering the agent (and emitting `agent/disposed`)
+ *   while its final turn is still draining.
+ */
+register(agent: Agent): () => void
+
+/**
+ * Insert an already-constructed agent without announcing it. This is the
+ * advanced ordered-lifecycle primitive used by the async agent factory: it
+ * first completes setup while the agent is unpublished, then assigns the
+ * returned detach closure into its pre-installed composite teardown before
+ * calling {@link announce}. Ordinary callers use {@link register}.
+ * @param agent - the prepared, unpublished agent.
+ * @param owner - live agent whose scoped context created this agent, or
+ *   undefined for a top-level runtime root. This is runtime ownership, not
+ *   the resumed session's durable parent lineage.
+ * @returns an idempotent closure that removes this exact entry and emits
+ *   `agent/disposed` with listener failures contained. When called from a
+ *   synchronous `agent/created` listener, removal and disposal wait until
+ *   that creation dispatch unwinds.
+ */
+enter(agent: Agent, owner: Agent | undefined): () => void
+
+/**
+ * Announce an agent previously inserted with {@link enter}.
+ * @param agent - the live inserted agent to announce.
+ * @throws if `agent` is not the exact live registry entry for its id, or its
+ *   creation announcement already began (including a reentrant call from a
+ *   creation listener).
+ */
+announce(agent: Agent): void
+
+/**
+ * Look up a live agent.
+ * @param id - the shared agent/session id to look up.
+ * @returns the agent, or undefined when no live agent has that id.
+ */
+get(id: SessionId): Agent | undefined
+
+/**
+ * Test whether a live agent was created through one exact parent agent's
+ * scoped context. Runtime ownership is independent of durable session
+ * lineage and remains unambiguous when unrelated providers reuse an id.
+ * @param id - the candidate child agent's shared agent/session id.
+ * @param owner - the expected runtime creator agent.
+ * @returns true only while the exact child entry is live under that owner.
+ */
+isOwnedBy(id: SessionId, owner: Agent): boolean
+
+/**
+ * All live agents, in registration order.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
+list(): Agent[]
+
+/**
+ * All live top-level agents in registration order. A top-level agent was
+ * created without an owning agent context; durable session lineage does not
+ * affect this runtime relation, so a resumed fork may still be a root.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
+roots(): Agent[]
+```
+
+Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+
+<a id="agent-events"></a>
+
+### `agent/*` events
+
+<a id="agentcreated--emit"></a>
+
+#### `agent/created` — emit
+
+A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
+
+```ts cordis-catalog
+/**
+ * A fully configured agent and live session were published. Setup is
+ * composition-only; `agent/session-start` is the first startup-driving seam.
+ * Synchronous listener failure vetoes publication, while returned-promise
+ * rejection is reported. Detach requested during dispatch waits until every
+ * creation listener has observed the stable entry.
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
+
+<a id="agentdisposed--emit"></a>
+
+#### `agent/disposed` — emit
+
+An agent left the registry; AgentLoop emits this after driver quiescence and scoped-registration unwind, but before session detachment. Custom registry users own their driver-ordering contract.
+
+```ts cordis-catalog
+/**
+ * An agent left the registry; AgentLoop emits this after driver quiescence
+ * and scoped-registration unwind, but before session detachment. Custom
+ * registry users own their driver-ordering contract.
+ * @param payload.agent - the exact agent removed from the registry.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
+
+<a id="agenterror--emit"></a>
+
+#### `agent/error` — emit
+
+A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
+
+```ts cordis-catalog
+/**
+ * A step or turn errored. The machine reports a failure here even when
+ * the error has no in-turn position for a durable record.
+ * @param payload.agent - the agent whose turn errored.
+ * @param payload.turn - the turn in which the failure surfaced.
+ * @param payload.step - the step at which the failure surfaced.
+ * @param payload.error - the failure, verbatim.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxclaimed--emit"></a>
+
+#### `agent/inbox/claimed` — emit
+
+One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
+
+```ts cordis-catalog
+/**
+ * One message left the inbox inside its open turn. If the proposed step
+ * is rejected, the claimed message ends here: it is neither discarded nor
+ * re-emitted as a user/message, and the turn closes without a step.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the claimed message.
+ * @param payload.turn - the owning turn.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxdiscarded--emit"></a>
+
+#### `agent/inbox/discarded` — emit
+
+One message was discarded from the live inbox.
+
+```ts cordis-catalog
+/**
+ * One message was discarded from the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the discarded message.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
+
+<a id="agentinboxinserted--emit"></a>
+
+#### `agent/inbox/inserted` — emit
+
+One message entered the live inbox.
+
+```ts cordis-catalog
+/**
+ * One message entered the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the inserted message.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
+
+<a id="agentpre-step--waterfall"></a>
+
+#### `agent/pre-step` — waterfall
+
+Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
+
+```ts cordis-catalog
+/**
+ * Reject a proposed step or replace the messages that enter it. Calling
+ * `next()` preserves the current messages.
+ * @param payload.agent - the agent proposing the step.
+ * @param payload.messages - messages removed from the inbox for this step.
+ * @param payload.turn - the turn that will own the step.
+ * @param payload.step - the step proposed by the loop.
+ * @param payload.signal - the current turn's cancellation signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
+'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
+```
+
+Types: [Scoped](scope.md) · [UserMessage](session.md)
+
+Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
+
+<a id="agentrequest--waterfall"></a>
+
+#### `agent/request` — waterfall
+
+Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this seam cannot mutate messages.
+
+```ts cordis-catalog
+/**
+ * Replace the frozen call configuration. `await next()` yields the config
+ * the machine would use (agent options on the first request, the logged
+ * header afterwards); return a replacement to switch. Model-visible
+ * content must use logged channels; this seam cannot mutate messages.
+ * @param payload.agent - the agent making the model call.
+ * @param payload.turn - the open turn number.
+ * @param payload.step - the step whose request this is.
+ * @param payload.signal - the current turn's explicit abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+*/
+'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
+
+<a id="agentrequest-error--waterfall"></a>
+
+#### `agent/request-error` — waterfall
+
+Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+
+```ts cordis-catalog
+/**
+ * Handle one failed model-request attempt before the loop retries or closes
+ * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
+ * when it owns recovery, or calls `next()` to delegate. The default
+ * `undefined` leaves the failure terminal.
+ * @param payload.agent - the agent whose request failed.
+ * @param payload.turn - the turn containing the failed request.
+ * @param payload.step - the step containing the failed request attempt.
+ * @param payload.provider - the provider selected for the failed request.
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
+ * @param payload.signal - the turn abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
+'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+```
+
+Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
+
+<a id="agentsession-start--emit"></a>
+
+#### `agent/session-start` — emit
+
+The session lifecycle began, once before the first turn. Use `agent.inject()` to seed model-facing context. This is a notification, not a veto; disposal requested by a lifecycle owner is rechecked before the driver starts.
+
+```ts cordis-catalog
+/**
+ * The session lifecycle began, once before the first turn. Use
+ * `agent.inject()` to seed model-facing context. This is a notification, not
+ * a veto; disposal requested by a lifecycle owner is rechecked before the
+ * driver starts.
+ * @param payload.agent - the agent whose session lifecycle began.
+ * @param payload.source - why the session started (fresh startup, resume, …).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
+
+<a id="agentstatus--emit"></a>
+
+#### `agent/status` — emit
+
+Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
+
+```ts cordis-catalog
+/**
+ * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
+ * `running` synchronously after reserving cancellation; `idle` means no
+ * driver remains scheduled or active.
+ * @param payload.agent - the agent whose status flipped.
+ * @param payload.status - the status just entered (the transition's destination).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
+
+<a id="agentturn-stopping--serial"></a>
+
+#### `agent/turn-stopping` — serial
+
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
+
+```ts cordis-catalog
+/**
+ * The turn is about to close: the model owes no response (no live tool
+ * calls, no fresh steering). Awaited before the boundary commits — a
+ * listener that objects steers (`agent.steer(...)`) and the machine
+ * re-reads its inbox: fresh steering runs another step, none closes the
+ * turn. Data decides, so listener order cannot change the outcome. The
+ * inverse control (stop a tool loop early) is data too: a tool result
+ * carrying `concludesTurn` ends the turn at its step. The conclusion
+ * never short-circuits already-submitted next-step work: same-step
+ * `additionalContexts` or racing steering still runs, and the turn
+ * closes only when that inbox drains.
+ * @param payload.agent - the agent whose turn is at its stop boundary.
+ * @param payload.turn - the turn about to close.
+ * @param payload.signal - the current turn's explicit abort signal.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode serial
+ */
+'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
+
+<a id="agent-loop-events"></a>
+
+### `agent-loop/*` events
+
+<a id="agent-loopconfig-start-failed--emit"></a>
+
+#### `agent-loop/config-start-failed` — emit
+
+A declarative agent entry failed before it could publish a live agent. Consumers that buffer work for the configured identity use this transient signal to reject that work instead of waiting forever. Normal factory teardown suppresses failures from the cancelled startup attempt.
+
+```ts cordis-catalog
+/**
+ * A declarative agent entry failed before it could publish a live agent.
+ * Consumers that buffer work for the configured identity use this
+ * transient signal to reject that work instead of waiting forever. Normal
+ * factory teardown suppresses failures from the cancelled startup attempt.
+ * @param payload.sessionId - exact shared agent/session identity that failed startup.
+ * @param payload.error - persistence, setup, or publication failure.
+ * @mode emit
+ */
+'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
+```
+
+Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index f7899eaf6e..7028d71f8d 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: ef74ddeb4346e18f8d5d33488657e5d50f1d754e
-credentials.zh.md: 09cf374a2346fd93aa834e3372321e6eeece6ed8
+credentials.md: 0bc2224ac039addc795d3806e8c85004f2bb84a7
+credentials.zh.md: 6f5ccd1572885434257d39eb0f659fcc7371ad1d
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index ef74ddeb43..0bc2224ac0 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -48,3 +48,86 @@ interface CredentialInfo {
 ## Change commits
 
 `credentials/updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration surfaces refreshing a "configured" badge.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcredentials--credentials-abstract-seam"></a>
+
+### `ctx.credentials` — `Credentials` (abstract seam)
+
+Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+
+```ts cordis-catalog
+/**
+ * Resolve one reference to its current value. Resolution is per call:
+ * consumers re-resolve at each operation and must not cache across
+ * operations — that per-operation read is what makes a changed credential
+ * reach the next operation without a restart.
+ * @param ref - the reference to resolve.
+ * @returns the value and its source, or `undefined` while unconfigured.
+ */
+abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>
+
+/**
+ * Describe one reference for configuration surfaces without exposing the
+ * value.
+ * @param ref - the reference to describe.
+ * @returns configured state, supplying source, and writability.
+ */
+abstract describe(ref: CredentialRef): Promise<CredentialInfo>
+
+/**
+ * Durably store one value in the provider-managed writable source. Rejects
+ * while a read-only source shadows the reference — the write would appear
+ * to succeed while resolution keeps returning the shadowing value — and
+ * rejects an empty value (use {@link unset}).
+ * @param ref - the reference to store.
+ * @param value - the non-empty secret value.
+ */
+abstract set(ref: CredentialRef, value: string): Promise<void>
+
+/**
+ * Remove one reference from the provider-managed writable source; removing
+ * an absent reference is a no-op. Rejects while a read-only source shadows
+ * the reference, like {@link set}.
+ * @param ref - the reference to remove.
+ */
+abstract unset(ref: CredentialRef): Promise<void>
+```
+
+Source: [`packages/credentials/credentials/src/index.ts:77`](../../packages/credentials/credentials/src/index.ts)
+
+<a id="credentials-events"></a>
+
+### `credentials/*` events
+
+<a id="credentialsupdated--emit"></a>
+
+#### `credentials/updated` — emit
+
+Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
+
+```ts cordis-catalog
+/**
+ * Committed change to a provider-managed credential source: a `set`, an
+ * `unset`, or an external edit observed in storage. Ambient
+ * process-environment changes are not observable and never emit. Listener
+ * failures are contained and logged — a sync throw and an async rejection
+ * alike — without changing the committed operation's outcome, except
+ * `INVARIANT`-coded failures, which rethrow after every listener ran;
+ * that rethrow reaches the emitter only from synchronous listeners, so
+ * invariant checks on this event must not be async functions.
+ * @param ref - the reference whose stored value changed.
+ * @mode emit
+ */
+'credentials/updated'(ref: CredentialRef): void
+```
+
+Source: [`packages/credentials/credentials/src/index.ts:67`](../../packages/credentials/credentials/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index 09cf374a23..6f5ccd1572 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -48,3 +48,86 @@ interface CredentialInfo {
 ## 变更提交
 
 `credentials/updated (ref)` 在 provider 管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxcredentials--credentials-abstract-seam"></a>
+
+### `ctx.credentials` — `Credentials` (abstract seam)
+
+Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
+
+```ts cordis-catalog
+/**
+ * Resolve one reference to its current value. Resolution is per call:
+ * consumers re-resolve at each operation and must not cache across
+ * operations — that per-operation read is what makes a changed credential
+ * reach the next operation without a restart.
+ * @param ref - the reference to resolve.
+ * @returns the value and its source, or `undefined` while unconfigured.
+ */
+abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>
+
+/**
+ * Describe one reference for configuration surfaces without exposing the
+ * value.
+ * @param ref - the reference to describe.
+ * @returns configured state, supplying source, and writability.
+ */
+abstract describe(ref: CredentialRef): Promise<CredentialInfo>
+
+/**
+ * Durably store one value in the provider-managed writable source. Rejects
+ * while a read-only source shadows the reference — the write would appear
+ * to succeed while resolution keeps returning the shadowing value — and
+ * rejects an empty value (use {@link unset}).
+ * @param ref - the reference to store.
+ * @param value - the non-empty secret value.
+ */
+abstract set(ref: CredentialRef, value: string): Promise<void>
+
+/**
+ * Remove one reference from the provider-managed writable source; removing
+ * an absent reference is a no-op. Rejects while a read-only source shadows
+ * the reference, like {@link set}.
+ * @param ref - the reference to remove.
+ */
+abstract unset(ref: CredentialRef): Promise<void>
+```
+
+Source: [`packages/credentials/credentials/src/index.ts:77`](../../packages/credentials/credentials/src/index.ts)
+
+<a id="credentials-events"></a>
+
+### `credentials/*` events
+
+<a id="credentialsupdated--emit"></a>
+
+#### `credentials/updated` — emit
+
+Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Listener failures are contained and logged — a sync throw and an async rejection alike — without changing the committed operation's outcome, except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
+
+```ts cordis-catalog
+/**
+ * Committed change to a provider-managed credential source: a `set`, an
+ * `unset`, or an external edit observed in storage. Ambient
+ * process-environment changes are not observable and never emit. Listener
+ * failures are contained and logged — a sync throw and an async rejection
+ * alike — without changing the committed operation's outcome, except
+ * `INVARIANT`-coded failures, which rethrow after every listener ran;
+ * that rethrow reaches the emitter only from synchronous listeners, so
+ * invariant checks on this event must not be async functions.
+ * @param ref - the reference whose stored value changed.
+ * @mode emit
+ */
+'credentials/updated'(ref: CredentialRef): void
+```
+
+Source: [`packages/credentials/credentials/src/index.ts:67`](../../packages/credentials/credentials/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 2f9478a7ba..cadc2b92d8 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/core-data-structures/filesystem.md
-filesystem.md: addded9f673ed435e95109d4fb772967514c0b87
-filesystem.zh.md: 1e378928ed570b97dbec73b836a7e6ff18726ff8
+#   pnpm run verify-translation-pairing --write docs/subsystems/filesystem.md
+filesystem.md: 1999399254fa5d72ab222a42a2fa8f4b890da50a
+filesystem.zh.md: 044a1c5be91ed8bec5d0442cc6f7edfde6870785
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index addded9f67..1999399254 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -181,7 +181,7 @@ interface FsEditOutcome {
 
 `dsh-fs` owns three events the tool dispatches and the policy plugin listens for, so the emitter (`dsh-tool-fs`) and the listener (`dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
-`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener would surface as the tool's `isError` result for a mutation that already succeeded. The generated catalog shows the exact signatures on [events.md](../cordis-catalog/events.md).
+`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener would surface as the tool's `isError` result for a mutation that already succeeded. The generated [cordis surface](#cordis-surface) below shows the exact signatures.
 
 ## Execution context (policy plugin)
 
@@ -258,4 +258,208 @@ type FsErrorCode =
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxfs--filesystem-abstract-seam"></a>
+
+### `ctx.fs` — `FileSystem` (abstract seam)
+
+Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
+
+```ts cordis-catalog
+/**
+ * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
+ * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
+ * async even though the local backend only normalizes + realpaths.
+ *
+ * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
+ * @param opts - optional cwd override and cancellation signal.
+ * @returns the stable target; the same file yields the same `targetKey`.
+ */
+abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
+
+/**
+ * Return the canonical absolute path a subprocess in this filesystem's
+ * execution world can open. The path is deliberately separate from
+ * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+ * capability, but must continue treating the target key as opaque.
+ * @param target - the resolved target whose process path is required.
+ * @returns an absolute path in the backend's execution world.
+ */
+abstract processPath(target: FsTarget): string
+
+/**
+ * Return the canonical `file:` URI for a target in this filesystem's
+ * execution world. Backends own URI encoding because the host platform may
+ * differ from the execution platform.
+ * @param target - the resolved target to encode.
+ * @returns the target's canonical file URI.
+ */
+abstract fileUrl(target: FsTarget): string
+
+/**
+ * Test canonical containment without exposing or parsing backend target
+ * keys. Both targets must come from this provider.
+ * @param parent - canonical directory target.
+ * @param child - canonical candidate target.
+ * @returns true when `child` is `parent` or a descendant of it.
+ */
+abstract contains(parent: FsTarget, child: FsTarget): boolean
+
+/**
+ * Return target metadata, or `undefined` when the target does not exist.
+ * @param target - the resolved target to stat.
+ * @param signal - aborts the metadata round-trip.
+ * @returns metadata only, never content; undefined for an absent target.
+ */
+abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
+
+/**
+ * Return path metadata without following the final path component when it is a
+ * symbolic link. This is intentionally path-shaped, not target-shaped:
+ * {@link resolve} follows symlinks to produce the stable identity used by
+ * normal reads/writes, while `lstat` lets a consumer reject the path itself
+ * before that follow happens.
+ *
+ * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
+ * absent.
+ * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
+ * @param opts - `cwd` overrides the backend's default base for relative paths.
+ * @param signal - aborts the metadata round-trip.
+ * @returns metadata only, never content; undefined for an absent path.
+ */
+abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
+
+/**
+ * Read the whole regular text file as a single decoded string.
+ * @param target - the resolved target to read.
+ * @param signal - aborts the read.
+ * @returns the full decoded UTF-8 content.
+ */
+abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
+
+/**
+ * Stream the whole regular text file as decoded text chunks (same text
+ * semantics as {@link readText}, for large files). The backend owns
+ * cross-chunk UTF-8 decoding and binary rejection so the policy layer never
+ * touches raw bytes.
+ * @param target - the resolved target to read.
+ * @param signal - aborts the stream, including between chunks.
+ * @returns the chunk iterable, decoded and validated like {@link readText}.
+ */
+abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
+
+/**
+ * List direct children of a directory in stable name order. Returns resolved
+ * child targets plus cheap metadata only; never reads file contents.
+ * @param target - the resolved directory target.
+ * @param signal - aborts the listing.
+ * @returns one entry per direct child, in stable name order.
+ */
+abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
+
+/**
+ * Atomically create or replace UTF-8 text. `expected` guards intent and
+ * staleness; omission allows unconditional overwrite.
+ * @param target - the resolved target to write.
+ * @param content - the full new file content.
+ * @param expected - the write intent guarding the write; omit for unconditional.
+ * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxPolicy - the per-call mode and workspace root this write
+ *   runs under; a sandboxing backend fences the write by it, the bare backend
+ *   ignores it. Omit to leave the backend its own default.
+ * @returns the outcome, including the version the write produced.
+ */
+abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>
+
+/**
+ * Atomically edit literal text. When supplied, the version guard is checked
+ * before matching so stale content reports `FS_STALE_VERSION`; omission edits
+ * the current content without a freshness precondition.
+ * @param target - the resolved target to edit.
+ * @param edit - the literal search/replace request.
+ * @param expected - the version guard; omit for an unconditional edit.
+ * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxPolicy - the per-call mode and workspace root this edit runs
+ *   under; a sandboxing backend fences the edit by it, the bare backend
+ *   ignores it. Omit to leave the backend its own default.
+ * @returns the outcome, including the version the edit produced.
+ */
+abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>
+```
+
+Types: [SandboxExecutionPolicy](sandbox.md)
+
+Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
+
+<a id="fs-events"></a>
+
+### `fs/*` events
+
+<a id="fsedit-intent--waterfall"></a>
+
+#### `fs/edit-intent` — waterfall
+
+Single-slot decision for the next FileSystem.editText. Calling `next()` yields an unconditional edit; the first returned guard wins.
+
+```ts cordis-catalog
+/**
+ * Single-slot decision for the next {@link FileSystem.editText}. Calling
+ * `next()` yields an unconditional edit; the first returned guard wins.
+ * @param target - the resolved target about to be edited.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
+'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
+```
+
+Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
+
+<a id="fsobserved--emit"></a>
+
+#### `fs/observed` — emit
+
+Record a successful observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
+
+```ts cordis-catalog
+/**
+ * Record a successful observation. Listeners must be synchronous recorders:
+ * throws fail the tool call and returned promises are not awaited.
+ * @param target - the target that was read/written/edited.
+ * @param version - the version the actor now holds as its observation.
+ * @param actor - the observing tool-execution context; undefined records nothing useful.
+ * @mode emit
+ */
+'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+```
+
+Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
+
+<a id="fswrite-intent--waterfall"></a>
+
+#### `fs/write-intent` — waterfall
+
+Single-slot decision for the next FileSystem.writeText. Calling `next()` yields the bare provider's unconditional write; the first listener that returns an intent owns the decision rather than composing with peers.
+
+```ts cordis-catalog
+/**
+ * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+ * `next()` yields the bare provider's unconditional write; the first listener
+ * that returns an intent owns the decision rather than composing with peers.
+ * @param target - the resolved target about to be written.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
+'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
+```
+
+Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 1e378928ed..044a1c5be9 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -181,7 +181,7 @@ interface FsEditOutcome {
 
 `dsh-fs` 拥有三个事件，由工具分发、策略插件监听，使发射方（`dsh-tool-fs`）与监听方（`dsh-fs-policy`）共享词汇，而发射方无需依赖策略插件。它们只携带 `dsh-fs` 词汇加一个不透明的 `object` actor，不含面向模型的概念，也不含 agent/会话所有者结构。
 
-`fs/write-intent` 与 `fs/edit-intent` 是**单槽决策 waterfall**：工具分发时附带一个默认 thunk（返回 `undefined`，即裸提供方），监听方完全决策而不调用 `next()`。该槽按注册顺序先到先得——由策略插件占据是部署约定，而非强制不变式。`fs/observed` 是一个即发即弃的记录事件，通过普通 `ctx.emit` 分发；其监听方必须是同步的、仅产生副作用，因为工具不会捕获该 emit 抛出的异常——抛出异常的监听方会导致工具为一次已经成功的变更返回 `isError` 结果。生成的目录在 [events.md](../cordis-catalog/events.md) 中展示确切签名。
+`fs/write-intent` 与 `fs/edit-intent` 是**单槽决策 waterfall**：工具分发时附带一个默认 thunk（返回 `undefined`，即裸提供方），监听方完全决策而不调用 `next()`。该槽按注册顺序先到先得——由策略插件占据是部署约定，而非强制不变式。`fs/observed` 是一个即发即弃的记录事件，通过普通 `ctx.emit` 分发；其监听方必须是同步的、仅产生副作用，因为工具不会捕获该 emit 抛出的异常——抛出异常的监听方会导致工具为一次已经成功的变更返回 `isError` 结果。下方生成的 [cordis surface](#cordis-surface) 展示确切签名。
 
 ## 执行上下文（策略插件）
 
@@ -258,4 +258,208 @@ type FsErrorCode =
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。生成的 wiring 目录在 [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam) 中展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxfs--filesystem-abstract-seam"></a>
+
+### `ctx.fs` — `FileSystem` (abstract seam)
+
+Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
+
+```ts cordis-catalog
+/**
+ * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
+ * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
+ * async even though the local backend only normalizes + realpaths.
+ *
+ * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
+ * @param opts - optional cwd override and cancellation signal.
+ * @returns the stable target; the same file yields the same `targetKey`.
+ */
+abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
+
+/**
+ * Return the canonical absolute path a subprocess in this filesystem's
+ * execution world can open. The path is deliberately separate from
+ * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+ * capability, but must continue treating the target key as opaque.
+ * @param target - the resolved target whose process path is required.
+ * @returns an absolute path in the backend's execution world.
+ */
+abstract processPath(target: FsTarget): string
+
+/**
+ * Return the canonical `file:` URI for a target in this filesystem's
+ * execution world. Backends own URI encoding because the host platform may
+ * differ from the execution platform.
+ * @param target - the resolved target to encode.
+ * @returns the target's canonical file URI.
+ */
+abstract fileUrl(target: FsTarget): string
+
+/**
+ * Test canonical containment without exposing or parsing backend target
+ * keys. Both targets must come from this provider.
+ * @param parent - canonical directory target.
+ * @param child - canonical candidate target.
+ * @returns true when `child` is `parent` or a descendant of it.
+ */
+abstract contains(parent: FsTarget, child: FsTarget): boolean
+
+/**
+ * Return target metadata, or `undefined` when the target does not exist.
+ * @param target - the resolved target to stat.
+ * @param signal - aborts the metadata round-trip.
+ * @returns metadata only, never content; undefined for an absent target.
+ */
+abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
+
+/**
+ * Return path metadata without following the final path component when it is a
+ * symbolic link. This is intentionally path-shaped, not target-shaped:
+ * {@link resolve} follows symlinks to produce the stable identity used by
+ * normal reads/writes, while `lstat` lets a consumer reject the path itself
+ * before that follow happens.
+ *
+ * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
+ * absent.
+ * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
+ * @param opts - `cwd` overrides the backend's default base for relative paths.
+ * @param signal - aborts the metadata round-trip.
+ * @returns metadata only, never content; undefined for an absent path.
+ */
+abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
+
+/**
+ * Read the whole regular text file as a single decoded string.
+ * @param target - the resolved target to read.
+ * @param signal - aborts the read.
+ * @returns the full decoded UTF-8 content.
+ */
+abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
+
+/**
+ * Stream the whole regular text file as decoded text chunks (same text
+ * semantics as {@link readText}, for large files). The backend owns
+ * cross-chunk UTF-8 decoding and binary rejection so the policy layer never
+ * touches raw bytes.
+ * @param target - the resolved target to read.
+ * @param signal - aborts the stream, including between chunks.
+ * @returns the chunk iterable, decoded and validated like {@link readText}.
+ */
+abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
+
+/**
+ * List direct children of a directory in stable name order. Returns resolved
+ * child targets plus cheap metadata only; never reads file contents.
+ * @param target - the resolved directory target.
+ * @param signal - aborts the listing.
+ * @returns one entry per direct child, in stable name order.
+ */
+abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
+
+/**
+ * Atomically create or replace UTF-8 text. `expected` guards intent and
+ * staleness; omission allows unconditional overwrite.
+ * @param target - the resolved target to write.
+ * @param content - the full new file content.
+ * @param expected - the write intent guarding the write; omit for unconditional.
+ * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxPolicy - the per-call mode and workspace root this write
+ *   runs under; a sandboxing backend fences the write by it, the bare backend
+ *   ignores it. Omit to leave the backend its own default.
+ * @returns the outcome, including the version the write produced.
+ */
+abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>
+
+/**
+ * Atomically edit literal text. When supplied, the version guard is checked
+ * before matching so stale content reports `FS_STALE_VERSION`; omission edits
+ * the current content without a freshness precondition.
+ * @param target - the resolved target to edit.
+ * @param edit - the literal search/replace request.
+ * @param expected - the version guard; omit for an unconditional edit.
+ * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxPolicy - the per-call mode and workspace root this edit runs
+ *   under; a sandboxing backend fences the edit by it, the bare backend
+ *   ignores it. Omit to leave the backend its own default.
+ * @returns the outcome, including the version the edit produced.
+ */
+abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>
+```
+
+Types: [SandboxExecutionPolicy](sandbox.md)
+
+Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
+
+<a id="fs-events"></a>
+
+### `fs/*` events
+
+<a id="fsedit-intent--waterfall"></a>
+
+#### `fs/edit-intent` — waterfall
+
+Single-slot decision for the next FileSystem.editText. Calling `next()` yields an unconditional edit; the first returned guard wins.
+
+```ts cordis-catalog
+/**
+ * Single-slot decision for the next {@link FileSystem.editText}. Calling
+ * `next()` yields an unconditional edit; the first returned guard wins.
+ * @param target - the resolved target about to be edited.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
+'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
+```
+
+Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
+
+<a id="fsobserved--emit"></a>
+
+#### `fs/observed` — emit
+
+Record a successful observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
+
+```ts cordis-catalog
+/**
+ * Record a successful observation. Listeners must be synchronous recorders:
+ * throws fail the tool call and returned promises are not awaited.
+ * @param target - the target that was read/written/edited.
+ * @param version - the version the actor now holds as its observation.
+ * @param actor - the observing tool-execution context; undefined records nothing useful.
+ * @mode emit
+ */
+'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+```
+
+Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
+
+<a id="fswrite-intent--waterfall"></a>
+
+#### `fs/write-intent` — waterfall
+
+Single-slot decision for the next FileSystem.writeText. Calling `next()` yields the bare provider's unconditional write; the first listener that returns an intent owns the decision rather than composing with peers.
+
+```ts cordis-catalog
+/**
+ * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+ * `next()` yields the bare provider's unconditional write; the first listener
+ * that returns an intent owns the decision rather than composing with peers.
+ * @param target - the resolved target about to be written.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
+'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
+```
+
+Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/goal.i18n.yaml b/docs/subsystems/goal.i18n.yaml
index 625556f99a..945ed658d2 100644
--- a/docs/subsystems/goal.i18n.yaml
+++ b/docs/subsystems/goal.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 docs/core-data-structures/goal.md
-goal.md: fc6a7e63e58fc7cd4bc524be1e66515593680d95
-goal.zh.md: c584cb375bd55c13c158e7ee22d7721040dffa05
+#   pnpm run verify-translation-pairing --write docs/subsystems/goal.md
+goal.md: 6f54a5261cb44c3fda389e37cb689a00061ab241
+goal.zh.md: 043263f3231b4c727f21ca0b8fc07d8adffa0559
diff --git a/docs/subsystems/goal.md b/docs/subsystems/goal.md
index fc6a7e63e5..6f54a5261c 100644
--- a/docs/subsystems/goal.md
+++ b/docs/subsystems/goal.md
@@ -143,3 +143,135 @@ interface GoalChanged {
 ## Service behavior
 
 [`GoalService`](../../packages/goal/goal/src/index.ts) resolves creation defaults, folds strict replay from durable `goal/change` events, enforces exact-live-agent identity and compare-and-set mutations, and emits contained `goal/changed` notifications. The package [README](../../packages/goal/goal/README.md) owns the callable and model-visible contract.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxgoals--goalservice"></a>
+
+### `ctx.goals` — `GoalService`
+
+Goal service (`ctx.goals`) backed exclusively by the owning session log.
+
+```ts cordis-catalog
+/**
+ * Read the current goal for one exact live agent.
+ * @param agent - owning live agent.
+ * @returns a fresh view or `undefined` when no goal is current.
+ * @throws {@link GoalError} when the agent is not the registry's live instance.
+ */
+get(agent: Agent): GoalView | undefined
+
+/**
+ * Remove process-local continuation authority without changing durable goal
+ * phase or revision. Lifecycle owners use this before unloading a driver;
+ * a later human-authorized {@link resume} records the new activation edge.
+ * @param agent - owning live agent.
+ * @returns a fresh disarmed view, or `undefined` when no goal is current.
+ */
+disarm(agent: Agent): GoalView | undefined
+
+/**
+ * Create and arm a goal. A completed goal may be replaced; every other
+ * current phase must be cleared or resumed instead.
+ * @param agent - owning live agent.
+ * @param request - objective and optional round cap.
+ * @returns the created live view.
+ */
+create(agent: Agent, request: CreateGoalRequest): GoalView
+
+/**
+ * Edit objective and/or round cap without changing phase.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @param request - at least one replacement field.
+ * @returns the edited view.
+ */
+@Remote('edit') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
+
+/**
+ * Pause an active goal and disarm automatic continuation.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the paused view.
+ */
+@Remote('pause') pause(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Resume and arm a stopped goal, or rearm an active goal after a
+ * session-start edge, while its round budget still has capacity.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the active view.
+ */
+@Remote('resume') resume(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Mark a current non-complete goal complete and disarm it.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the completed view.
+ */
+@Remote('complete') complete(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Mark an active goal blocked and disarm it.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @param reason - policy-owned stable code and human-readable explanation.
+ * @returns the blocked view with its durable reason.
+ */
+block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
+
+/**
+ * Clear the current goal while retaining a durable tombstone and history.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the tombstone ref whose revision is one past the cleared snapshot.
+ */
+@Remote('clear') clear(agent: Agent, ref: GoalRef): GoalRef
+
+/**
+ * Create one Goal through the remote boundary.
+ * @param agent - exact live Agent resolved from the wire identity.
+ * @param request - objective and optional round cap.
+ * @returns the created Goal identity.
+ */
+@Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/goal/goal/src/index.ts:183`](../../packages/goal/goal/src/index.ts)
+
+<a id="goal-events"></a>
+
+### `goal/*` events
+
+<a id="goalchanged--emit"></a>
+
+#### `goal/changed` — emit
+
+Goal mutation accepted by one live agent. The matching `goal/change` session event has already committed. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+
+```ts cordis-catalog
+/**
+ * Goal mutation accepted by one live agent. The matching `goal/change`
+ * session event has already committed. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param payload.agent - agent whose session owns the goal.
+ * @param payload.change - fresh current projection or clear tombstone.
+ * @mode emit
+ */
+'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void
+```
+
+Types: [Agent](core.md) · [Scoped](scope.md)
+
+Source: [`packages/goal/goal/src/domain.ts:114`](../../packages/goal/goal/src/domain.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/goal.zh.md b/docs/subsystems/goal.zh.md
index c584cb375b..043263f323 100644
--- a/docs/subsystems/goal.zh.md
+++ b/docs/subsystems/goal.zh.md
@@ -143,3 +143,135 @@ interface GoalChanged {
 ## 服务行为
 
 [`GoalService`](../../packages/goal/goal/src/index.ts) 解析创建默认值、从持久 `goal/change` 事件执行严格回放折叠、校验确切的活跃 agent 身份、以比较并设置方式执行变更，并发出 `goal/changed` 通知；监听器故障会被隔离。包 [README](../../packages/goal/goal/README.md) 负责记录可调用契约和面向模型的契约。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxgoals--goalservice"></a>
+
+### `ctx.goals` — `GoalService`
+
+Goal service (`ctx.goals`) backed exclusively by the owning session log.
+
+```ts cordis-catalog
+/**
+ * Read the current goal for one exact live agent.
+ * @param agent - owning live agent.
+ * @returns a fresh view or `undefined` when no goal is current.
+ * @throws {@link GoalError} when the agent is not the registry's live instance.
+ */
+get(agent: Agent): GoalView | undefined
+
+/**
+ * Remove process-local continuation authority without changing durable goal
+ * phase or revision. Lifecycle owners use this before unloading a driver;
+ * a later human-authorized {@link resume} records the new activation edge.
+ * @param agent - owning live agent.
+ * @returns a fresh disarmed view, or `undefined` when no goal is current.
+ */
+disarm(agent: Agent): GoalView | undefined
+
+/**
+ * Create and arm a goal. A completed goal may be replaced; every other
+ * current phase must be cleared or resumed instead.
+ * @param agent - owning live agent.
+ * @param request - objective and optional round cap.
+ * @returns the created live view.
+ */
+create(agent: Agent, request: CreateGoalRequest): GoalView
+
+/**
+ * Edit objective and/or round cap without changing phase.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @param request - at least one replacement field.
+ * @returns the edited view.
+ */
+@Remote('edit') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView
+
+/**
+ * Pause an active goal and disarm automatic continuation.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the paused view.
+ */
+@Remote('pause') pause(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Resume and arm a stopped goal, or rearm an active goal after a
+ * session-start edge, while its round budget still has capacity.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the active view.
+ */
+@Remote('resume') resume(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Mark a current non-complete goal complete and disarm it.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the completed view.
+ */
+@Remote('complete') complete(agent: Agent, ref: GoalRef): GoalView
+
+/**
+ * Mark an active goal blocked and disarm it.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @param reason - policy-owned stable code and human-readable explanation.
+ * @returns the blocked view with its durable reason.
+ */
+block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView
+
+/**
+ * Clear the current goal while retaining a durable tombstone and history.
+ * @param agent - owning live agent.
+ * @param ref - expected current revision.
+ * @returns the tombstone ref whose revision is one past the cleared snapshot.
+ */
+@Remote('clear') clear(agent: Agent, ref: GoalRef): GoalRef
+
+/**
+ * Create one Goal through the remote boundary.
+ * @param agent - exact live Agent resolved from the wire identity.
+ * @param request - objective and optional round cap.
+ * @returns the created Goal identity.
+ */
+@Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/goal/goal/src/index.ts:183`](../../packages/goal/goal/src/index.ts)
+
+<a id="goal-events"></a>
+
+### `goal/*` events
+
+<a id="goalchanged--emit"></a>
+
+#### `goal/changed` — emit
+
+Goal mutation accepted by one live agent. The matching `goal/change` session event has already committed. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+
+```ts cordis-catalog
+/**
+ * Goal mutation accepted by one live agent. The matching `goal/change`
+ * session event has already committed. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param payload.agent - agent whose session owns the goal.
+ * @param payload.change - fresh current projection or clear tombstone.
+ * @mode emit
+ */
+'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void
+```
+
+Types: [Agent](core.md) · [Scoped](scope.md)
+
+Source: [`packages/goal/goal/src/domain.ts:114`](../../packages/goal/goal/src/domain.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index 6f1facfad7..3674a95c44 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.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 docs/subsystems/http-server.md
-http-server.md: 200d3eed683f203b65824ea3f62cf56ce3df912f
-http-server.zh.md: 9a12d3769a93270810927075be5f236875688b91
+http-server.md: b9795fe98b432b6ef5f7d01a4d3e115c809fe642
+http-server.zh.md: c3ba02dce5c58f491921f1fb31f999f9da808bc5
diff --git a/docs/subsystems/http-server.md b/docs/subsystems/http-server.md
index 200d3eed68..b9795fe98b 100644
--- a/docs/subsystems/http-server.md
+++ b/docs/subsystems/http-server.md
@@ -45,3 +45,64 @@ interface Config {
 `HttpServerService` (`ctx.httpServer`) listens immediately on activation; a listen failure (EADDRINUSE…) throws out of init — a FAILED fiber the boot's fail-loud sweep reports. `register(route)` adds one named route and returns its disposer; a duplicate `(kind, path)` throws, because route patterns are a composition-level contract and a collision is a misconfiguration. `tapIndex(transform)` adds a pure html-to-html transform applied to every index response — `/` and each SPA fallback — in registration order; [dsh-client-modules](../../packages/client/modules) uses it to inject the boot manifest. `port` reads the listening port, the OS-assigned value when `config.port` is 0.
 
 A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is logged as a warning and answered 400 — or the socket destroyed when headers are already out — never a process exit. Disposal pairs `close()` with `closeAllConnections()` because a handler may hold its response open (SSE) and such connections never end on their own; without the force-close, teardown would hang. The package never prints: the URL line belongs to the shell. Per-package operational detail, including the dev-mode bundle watch pipeline, stays in the [README](../../packages/host/webserver/README.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxhttpserver--httpserverservice"></a>
+
+### `ctx.httpServer` — `HttpServerService`
+
+The web-shape HTTP carrier service. Activation listens immediately (route registration order carries no request-facing semantics: named routes are composed to be disjoint, and the fallback seat answers anything not yet claimed during the boot window — 404 until its owner registers). A listen failure throws out of init — a FAILED fiber the boot's fail-loud sweep reports.
+
+```ts cordis-catalog
+/**
+ * Register a named route. Duplicate (kind, path) throws — route patterns are
+ * a composition-level contract, so a collision is a misconfiguration.
+ * @param route - kind, path, and the owning handler.
+ * @returns the disposer removing the route.
+ */
+register(route: WebRoute): () => void
+
+/**
+ * Register an exact-path HTTP upgrade route. Duplicate paths throw because
+ * one socket can have only one protocol owner.
+ * @param route - pathname and handler owning negotiation plus socket use.
+ * @returns the disposer removing the route.
+ */
+registerUpgrade(route: WebUpgradeRoute): () => void
+
+/**
+ * Claim the fallback seat: the handler answering every request no named
+ * route matches (the SPA dist server in the shipped Web composition). One
+ * owner only — a second registration throws, because two fallbacks cannot
+ * compose.
+ * @param handler - owns the full response lifecycle of unmatched requests.
+ * @returns the disposer releasing the seat.
+ */
+registerFallback(handler: WebRoute['handler']): () => void
+
+/**
+ * Register an index.html transform, applied by the fallback owner to every
+ * index response ({@link applyIndexTaps}) in registration order.
+ * @param transform - pure html-to-html function.
+ * @returns the disposer removing the transform.
+ */
+tapIndex(transform: (html: string) => string): () => void
+
+/**
+ * Run an index.html body through the registered taps in registration order
+ * — called by the fallback owner on every index response it renders.
+ * @param html - the raw index.html body.
+ * @returns the transformed body.
+ */
+applyIndexTaps(html: string): string
+```
+
+Source: [`packages/host/webserver/src/index.ts:60`](../../packages/host/webserver/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index 9a12d3769a..c3ba02dce5 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -45,3 +45,64 @@ interface Config {
 `HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动的大声失败 sweep 上报。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层契约，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
 
 处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能像 SSE（Server-Sent Events）那样保持响应打开，而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包（package）从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxhttpserver--httpserverservice"></a>
+
+### `ctx.httpServer` — `HttpServerService`
+
+The web-shape HTTP carrier service. Activation listens immediately (route registration order carries no request-facing semantics: named routes are composed to be disjoint, and the fallback seat answers anything not yet claimed during the boot window — 404 until its owner registers). A listen failure throws out of init — a FAILED fiber the boot's fail-loud sweep reports.
+
+```ts cordis-catalog
+/**
+ * Register a named route. Duplicate (kind, path) throws — route patterns are
+ * a composition-level contract, so a collision is a misconfiguration.
+ * @param route - kind, path, and the owning handler.
+ * @returns the disposer removing the route.
+ */
+register(route: WebRoute): () => void
+
+/**
+ * Register an exact-path HTTP upgrade route. Duplicate paths throw because
+ * one socket can have only one protocol owner.
+ * @param route - pathname and handler owning negotiation plus socket use.
+ * @returns the disposer removing the route.
+ */
+registerUpgrade(route: WebUpgradeRoute): () => void
+
+/**
+ * Claim the fallback seat: the handler answering every request no named
+ * route matches (the SPA dist server in the shipped Web composition). One
+ * owner only — a second registration throws, because two fallbacks cannot
+ * compose.
+ * @param handler - owns the full response lifecycle of unmatched requests.
+ * @returns the disposer releasing the seat.
+ */
+registerFallback(handler: WebRoute['handler']): () => void
+
+/**
+ * Register an index.html transform, applied by the fallback owner to every
+ * index response ({@link applyIndexTaps}) in registration order.
+ * @param transform - pure html-to-html function.
+ * @returns the disposer removing the transform.
+ */
+tapIndex(transform: (html: string) => string): () => void
+
+/**
+ * Run an index.html body through the registered taps in registration order
+ * — called by the fallback owner on every index response it renders.
+ * @param html - the raw index.html body.
+ * @returns the transformed body.
+ */
+applyIndexTaps(html: string): string
+```
+
+Source: [`packages/host/webserver/src/index.ts:60`](../../packages/host/webserver/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
index 27b6ac8e87..8ef657b3a4 100644
--- a/docs/subsystems/invariants.i18n.yaml
+++ b/docs/subsystems/invariants.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 docs/subsystems/invariants.md
-invariants.md: 143a7feabbab18556f595a78c7aef17caa6d3028
-invariants.zh.md: fb497857c02202544edf44ccfe3a2935a988e30e
+invariants.md: 184d982bb27ab3ff98f715f0751c8bfcc1d08bea
+invariants.zh.md: bd2f83a018642832fe50ba5cca6dd82e2bd7d59b
diff --git a/docs/subsystems/invariants.md b/docs/subsystems/invariants.md
index 143a7feabb..184d982bb2 100644
--- a/docs/subsystems/invariants.md
+++ b/docs/subsystems/invariants.md
@@ -57,3 +57,32 @@ An enabled installer runs in a dedicated child Cordis fiber; `installer.inject`
 ## The companion contract
 
 Every workspace package owns a `./invariant` companion ([package contract](../../packages/AGENTS.md)); publication and registration are exhaustive, but assertions are deliberately not synthetic. A companion installs a check only when its package owns an observable event or mutable-data relationship; otherwise it exports an empty installer whose leading comment starts `No runtime invariant:` and explains, package-specifically, why nothing is checkable. `pnpm run verify-package-invariants` mechanically rejects generated markers, unexplained empty installers, non-empty installers that omit or ignore the reporter, incorrect registration names, and incomplete export, publication, dependency, or bundle wiring ([mechanical-rule Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)). The catalog of executable companions and the standard composition live in the [package README](../../packages/support/invariants/README.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxinvariants--invariantservice"></a>
+
+### `ctx.invariants` — `InvariantService`
+
+Package-owned invariant registry with global and regex-based selection.
+
+```ts cordis-catalog
+/**
+ * Register one package's invariant installer. The package name is reserved
+ * even when filtering disables its checks. Enabled installers run in a child
+ * fiber; failure disposes that fiber and releases the reservation.
+ * @param packageName - full npm package name that owns the contribution.
+ * @param installer - listener or startup-check installer for the child context.
+ * @returns an effect-scoped disposer for the registration.
+ */
+register(packageName: string, installer: InvariantInstaller): () => void
+```
+
+Source: [`packages/support/invariants/src/index.ts:94`](../../packages/support/invariants/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
index fb497857c0..bd2f83a018 100644
--- a/docs/subsystems/invariants.zh.md
+++ b/docs/subsystems/invariants.zh.md
@@ -57,3 +57,32 @@ interface InvariantInstaller {
 ## 配套插件契约
 
 每个工作区包都拥有一个 `./invariant` 配套插件（[包契约](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但刻意不合成断言。只有当包对某个可观察事件或可变数据拥有所有权关系时，配套插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行配套插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxinvariants--invariantservice"></a>
+
+### `ctx.invariants` — `InvariantService`
+
+Package-owned invariant registry with global and regex-based selection.
+
+```ts cordis-catalog
+/**
+ * Register one package's invariant installer. The package name is reserved
+ * even when filtering disables its checks. Enabled installers run in a child
+ * fiber; failure disposes that fiber and releases the reservation.
+ * @param packageName - full npm package name that owns the contribution.
+ * @param installer - listener or startup-check installer for the child context.
+ * @returns an effect-scoped disposer for the registration.
+ */
+register(packageName: string, installer: InvariantInstaller): () => void
+```
+
+Source: [`packages/support/invariants/src/index.ts:94`](../../packages/support/invariants/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index 1ff1a1d42b..bd1d833f51 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: 5c90b3ce4ac65a99997f6ba7ad5deac494b7f772
-llm-streaming.zh.md: 7fd0043234cb40d6b21cec6ff101993164785a6e
+llm-streaming.md: fe4a831660dd81b33a1cd7dc9a9d7026f3831991
+llm-streaming.zh.md: a10b696ec0887e139785fc7e95d8641e6496de79
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index 5c90b3ce4a..fe4a831660 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -255,3 +255,191 @@ interface ContentBlockMap {
 ```
 
 See [core.md § Content blocks and messages](core.md#content-blocks-and-messages) for the block interfaces.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxllm--llmservice"></a>
+
+### `ctx.llm` — `LlmService`
+
+The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
+
+```ts cordis-catalog
+/**
+ * Register an adapter for the given provider routes. Throws `LlmError` with code
+ * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).
+ * Disposed with the fiber.
+ * @param providers - every provider route this adapter should serve.
+ * @param adapter - the adapter that streams calls for those providers.
+ * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
+ */
+registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle
+
+/**
+ * Describe provider routes with a registered adapter.
+ * @returns detached provider metadata in registration order.
+ */
+listProviders(): LlmProviderInfo[]
+
+/**
+ * Declare provider routes an adapter plugin can activate through
+ * configuration. Registration is all-or-nothing: an empty list, invalid
+ * entry, or a provider already declared by any registration throws
+ * `LlmError` without registering the rest. Disposed with the fiber.
+ * @param entries - every configurable provider this plugin owns.
+ * @returns a handle that withdraws all of them, and can atomically replace them.
+ */
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
+
+/**
+ * List every declared configurable provider, registered or dormant.
+ * @returns detached directory entries in declaration order.
+ */
+listConfigurableProviders(): LlmConfigurableProvider[]
+
+/**
+ * Offer to interrogate provider endpoints on behalf of the settings
+ * namespace this plugin owns. The namespace is the key because that is what
+ * a configuration surface already holds from the configurable-provider
+ * directory, and because a provider being *added* has no route to name yet.
+ * Disposed with the fiber.
+ * @param settingsNs - the namespace whose profiles this discovery serves.
+ * @param discover - interrogates one endpoint; must honor `request.signal`.
+ * @returns the disposer that withdraws the offer.
+ */
+registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
+
+/**
+ * Interrogate one provider endpoint for the models it advertises. The
+ * request describes a draft, not a stored route, so nothing here reads or
+ * writes settings or credentials — the caller owns both, and the reply is
+ * candidate metadata a surface may offer for adoption.
+ * @param settingsNs - namespace whose registered discovery serves this draft.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @returns the advertised models, deduplicated in endpoint order.
+ */
+async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
+
+/**
+ * Resolve the retry policy captured when one provider route was registered.
+ * @param provider - registered provider route to inspect.
+ * @returns the provider-owned policy, with normal defaults already resolved.
+ */
+providerRetryPolicy(provider: string): ResolvedRetryPolicy
+
+/**
+ * Discover models advertised by one registered provider. Catalog membership
+ * is advisory and never changes routing or request validation.
+ * @param provider - registered provider route to inspect.
+ * @returns detached model metadata in adapter-preferred order.
+ */
+async listModels(provider: string): Promise<LlmModelInfo[]>
+
+/**
+ * Resolve and validate all metadata from the adapter that owns one exact
+ * route. The result is detached from adapter-owned objects; catalog
+ * membership remains advisory and does not control request routing.
+ * @param provider - registered provider route to inspect.
+ * @param model - exact model id passed to the adapter.
+ * @param signal - optional cancellation for adapter-owned asynchronous lookup.
+ * @returns exact model identity plus available context and reasoning metadata.
+ */
+async resolveModelInfo( provider: string, model: string, signal?: AbortSignal, ): Promise<LlmResolvedModelInfo>
+
+/**
+ * Validate a conversation call config against its exact model capability and
+ * materialize adapter-configured defaults. Unsupported explicit efforts
+ * reject before provider I/O; no clamping or aliasing is performed. This
+ * standalone query does not bind a later dispatch; use {@link prepareCall}
+ * when logging and streaming must share one adapter registration.
+ * @param config - provider/model route and optional request controls.
+ * @param signal - optional cancellation for adapter-owned capability lookup.
+ * @returns a detached config only when a default must be materialized.
+ */
+async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>
+
+/**
+ * Resolve one call under its current adapter registration. The returned
+ * one-shot handle keeps that registration across header logging and dispatch,
+ * so HMR cannot combine one adapter's capability result with another adapter.
+ * @param config - provider/model route and optional request controls.
+ * @param signal - optional cancellation for adapter-owned capability lookup.
+ * @returns a prepared config and its registration-bound stream entry point.
+ */
+async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
+
+/**
+ * Stream one model call as raw chunks (token-level deltas). Replay state is
+ * retained only when the same adapter instance owns its historical provider
+ * and the target provider. Final adapter selection remains fixed through
+ * asynchronous exact-model resolution and dispatch. Adapter selection,
+ * dispatch, and iteration failures become terminal `error` or `aborted`
+ * finish chunks; middleware, nested-call, cleanup, and consumer failures
+ * remain thrown.
+ * @param options - the full request; `options.provider` selects the adapter.
+ * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
+ */
+stream(options: GenerateOptions): AsyncIterable<StreamChunk>
+```
+
+Types: [AdapterRegistrationHandle](core.md) · [DirectoryRegistrationHandle](core.md) · [GenerateOptions](core.md) · [LlmCallConfig](core.md) · [LlmConfigurableProvider](core.md) · [LlmDiscoveredModel](core.md) · [LlmModelDiscoveryRequest](core.md) · [LlmModelInfo](core.md) · [LlmProviderInfo](core.md) · [LlmResolvedModelInfo](core.md)
+
+Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
+
+<a id="llm-events"></a>
+
+### `llm/*` events
+
+<a id="llmadapters-updated--emit"></a>
+
+#### `llm/adapters-updated` — emit
+
+The provider topology changed: an adapter registered or unregistered routes, or the configurable-provider directory gained or lost entries. This is a payload-free registry notification fired at each commit point (including registration disposal); consumers re-read `listProviders()`, `listModels()`, or `listConfigurableProviders()` for the new state. Observer failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * The provider topology changed: an adapter registered or unregistered
+ * routes, or the configurable-provider directory gained or lost entries.
+ * This is a payload-free registry notification fired at each commit point
+ * (including registration disposal); consumers re-read `listProviders()`,
+ * `listModels()`, or `listConfigurableProviders()` for the new state.
+ * Observer failures are contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'llm/adapters-updated'(): void
+```
+
+Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
+
+<a id="llmstream--waterfall"></a>
+
+#### `llm/stream` — waterfall
+
+Waterfall around every streaming model call (retry, replay, routing). Bound to the LlmService; call `next()` to reach the resolved adapter's stream, or yield your own chunks to short-circuit.
+
+```ts cordis-catalog
+/**
+ * Waterfall around every streaming model call (retry, replay, routing).
+ * Bound to the {@link LlmService}; call `next()` to reach the resolved
+ * adapter's stream, or yield your own chunks to short-circuit.
+ * @param options - the full request. A LOOP-built request carries the
+ *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen
+ *   (mutation throws): its content is a pure function of the session log (the
+ *   reconstructability Agent Note), so listeners read it, never rewrite it.
+ *   Hand-built calls do not carry that marker; their messages already obey
+ *   the immutable creation contract.
+ * @mode waterfall
+ */
+'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
+```
+
+Types: [GenerateOptions](core.md)
+
+Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index 7fd0043234..a10b696ec0 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -255,3 +255,191 @@ interface ContentBlockMap {
 ```
 
 块接口详见 [core.md § Content blocks and messages](core.md#content-blocks-and-messages)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxllm--llmservice"></a>
+
+### `ctx.llm` — `LlmService`
+
+The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
+
+```ts cordis-catalog
+/**
+ * Register an adapter for the given provider routes. Throws `LlmError` with code
+ * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).
+ * Disposed with the fiber.
+ * @param providers - every provider route this adapter should serve.
+ * @param adapter - the adapter that streams calls for those providers.
+ * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
+ */
+registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle
+
+/**
+ * Describe provider routes with a registered adapter.
+ * @returns detached provider metadata in registration order.
+ */
+listProviders(): LlmProviderInfo[]
+
+/**
+ * Declare provider routes an adapter plugin can activate through
+ * configuration. Registration is all-or-nothing: an empty list, invalid
+ * entry, or a provider already declared by any registration throws
+ * `LlmError` without registering the rest. Disposed with the fiber.
+ * @param entries - every configurable provider this plugin owns.
+ * @returns a handle that withdraws all of them, and can atomically replace them.
+ */
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
+
+/**
+ * List every declared configurable provider, registered or dormant.
+ * @returns detached directory entries in declaration order.
+ */
+listConfigurableProviders(): LlmConfigurableProvider[]
+
+/**
+ * Offer to interrogate provider endpoints on behalf of the settings
+ * namespace this plugin owns. The namespace is the key because that is what
+ * a configuration surface already holds from the configurable-provider
+ * directory, and because a provider being *added* has no route to name yet.
+ * Disposed with the fiber.
+ * @param settingsNs - the namespace whose profiles this discovery serves.
+ * @param discover - interrogates one endpoint; must honor `request.signal`.
+ * @returns the disposer that withdraws the offer.
+ */
+registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
+
+/**
+ * Interrogate one provider endpoint for the models it advertises. The
+ * request describes a draft, not a stored route, so nothing here reads or
+ * writes settings or credentials — the caller owns both, and the reply is
+ * candidate metadata a surface may offer for adoption.
+ * @param settingsNs - namespace whose registered discovery serves this draft.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @returns the advertised models, deduplicated in endpoint order.
+ */
+async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
+
+/**
+ * Resolve the retry policy captured when one provider route was registered.
+ * @param provider - registered provider route to inspect.
+ * @returns the provider-owned policy, with normal defaults already resolved.
+ */
+providerRetryPolicy(provider: string): ResolvedRetryPolicy
+
+/**
+ * Discover models advertised by one registered provider. Catalog membership
+ * is advisory and never changes routing or request validation.
+ * @param provider - registered provider route to inspect.
+ * @returns detached model metadata in adapter-preferred order.
+ */
+async listModels(provider: string): Promise<LlmModelInfo[]>
+
+/**
+ * Resolve and validate all metadata from the adapter that owns one exact
+ * route. The result is detached from adapter-owned objects; catalog
+ * membership remains advisory and does not control request routing.
+ * @param provider - registered provider route to inspect.
+ * @param model - exact model id passed to the adapter.
+ * @param signal - optional cancellation for adapter-owned asynchronous lookup.
+ * @returns exact model identity plus available context and reasoning metadata.
+ */
+async resolveModelInfo( provider: string, model: string, signal?: AbortSignal, ): Promise<LlmResolvedModelInfo>
+
+/**
+ * Validate a conversation call config against its exact model capability and
+ * materialize adapter-configured defaults. Unsupported explicit efforts
+ * reject before provider I/O; no clamping or aliasing is performed. This
+ * standalone query does not bind a later dispatch; use {@link prepareCall}
+ * when logging and streaming must share one adapter registration.
+ * @param config - provider/model route and optional request controls.
+ * @param signal - optional cancellation for adapter-owned capability lookup.
+ * @returns a detached config only when a default must be materialized.
+ */
+async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>
+
+/**
+ * Resolve one call under its current adapter registration. The returned
+ * one-shot handle keeps that registration across header logging and dispatch,
+ * so HMR cannot combine one adapter's capability result with another adapter.
+ * @param config - provider/model route and optional request controls.
+ * @param signal - optional cancellation for adapter-owned capability lookup.
+ * @returns a prepared config and its registration-bound stream entry point.
+ */
+async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
+
+/**
+ * Stream one model call as raw chunks (token-level deltas). Replay state is
+ * retained only when the same adapter instance owns its historical provider
+ * and the target provider. Final adapter selection remains fixed through
+ * asynchronous exact-model resolution and dispatch. Adapter selection,
+ * dispatch, and iteration failures become terminal `error` or `aborted`
+ * finish chunks; middleware, nested-call, cleanup, and consumer failures
+ * remain thrown.
+ * @param options - the full request; `options.provider` selects the adapter.
+ * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
+ */
+stream(options: GenerateOptions): AsyncIterable<StreamChunk>
+```
+
+Types: [AdapterRegistrationHandle](core.md) · [DirectoryRegistrationHandle](core.md) · [GenerateOptions](core.md) · [LlmCallConfig](core.md) · [LlmConfigurableProvider](core.md) · [LlmDiscoveredModel](core.md) · [LlmModelDiscoveryRequest](core.md) · [LlmModelInfo](core.md) · [LlmProviderInfo](core.md) · [LlmResolvedModelInfo](core.md)
+
+Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
+
+<a id="llm-events"></a>
+
+### `llm/*` events
+
+<a id="llmadapters-updated--emit"></a>
+
+#### `llm/adapters-updated` — emit
+
+The provider topology changed: an adapter registered or unregistered routes, or the configurable-provider directory gained or lost entries. This is a payload-free registry notification fired at each commit point (including registration disposal); consumers re-read `listProviders()`, `listModels()`, or `listConfigurableProviders()` for the new state. Observer failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * The provider topology changed: an adapter registered or unregistered
+ * routes, or the configurable-provider directory gained or lost entries.
+ * This is a payload-free registry notification fired at each commit point
+ * (including registration disposal); consumers re-read `listProviders()`,
+ * `listModels()`, or `listConfigurableProviders()` for the new state.
+ * Observer failures are contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'llm/adapters-updated'(): void
+```
+
+Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
+
+<a id="llmstream--waterfall"></a>
+
+#### `llm/stream` — waterfall
+
+Waterfall around every streaming model call (retry, replay, routing). Bound to the LlmService; call `next()` to reach the resolved adapter's stream, or yield your own chunks to short-circuit.
+
+```ts cordis-catalog
+/**
+ * Waterfall around every streaming model call (retry, replay, routing).
+ * Bound to the {@link LlmService}; call `next()` to reach the resolved
+ * adapter's stream, or yield your own chunks to short-circuit.
+ * @param options - the full request. A LOOP-built request carries the
+ *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen
+ *   (mutation throws): its content is a pure function of the session log (the
+ *   reconstructability Agent Note), so listeners read it, never rewrite it.
+ *   Hand-built calls do not carry that marker; their messages already obey
+ *   the immutable creation contract.
+ * @mode waterfall
+ */
+'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
+```
+
+Types: [GenerateOptions](core.md)
+
+Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
index c63da5efdc..6f6ba3b3c3 100644
--- a/docs/subsystems/permission.i18n.yaml
+++ b/docs/subsystems/permission.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 docs/subsystems/permission.md
-permission.md: ec8cd4a923b617934f1612c31284103266aea4ef
-permission.zh.md: 4534c33e2715e4a500344f547c7895128877f4fb
+permission.md: 60ed88a79d0e51922f4cdffafa8b547669b49f5d
+permission.zh.md: c06714fc6a111f56af680c3dea1764c90f09998d
diff --git a/docs/subsystems/permission.md b/docs/subsystems/permission.md
index ec8cd4a923..60ed88a79d 100644
--- a/docs/subsystems/permission.md
+++ b/docs/subsystems/permission.md
@@ -65,4 +65,67 @@ interface PresetOption {
 
 `set(session, name)` resolves the preset (unknown names throw), appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter — `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/interaction/user-approval) — only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing at all.
 
-`permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve WHICH preset the user chose when two presets share a bundle; `effectivePermissionPreset(events)` folds the last one, and replay needs no catch-up state. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxpermission--permissionservice).
+`permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve WHICH preset the user chose when two presets share a bundle; `effectivePermissionPreset(events)` folds the last one, and replay needs no catch-up state. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](#ctxpermission--permissionservice).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxpermission--permissionservice"></a>
+
+### `ctx.permission` — `PermissionService`
+
+Owns the deployment's permission presets and their write path. Requires a confining `ctx.bash` executor and `ctx.approval`; unmatched knob values are reported as CUSTOM_PRESET, not an error.
+
+```ts cordis-catalog
+/**
+ * Resolve the preset matching the effective knob values. A still-matching
+ * last selection wins shared-bundle ties; otherwise the first table match
+ * wins, or {@link CUSTOM_PRESET} when no entry matches.
+ * @param events - the session's events in log order.
+ * @returns the effective preset name, or `custom` when nothing matches.
+ */
+current(events: readonly SessionEvent[]): string
+
+/**
+ * Build the whole select value for one folded knob state: every table
+ * option in declaration order, `custom` appended exactly while derived.
+ * @param state - the folded knob overrides.
+ * @returns the `permissions` projection payload.
+ */
+selectFor(state: KnobState): PermissionSelect
+
+/**
+ * Resolve a preset's knob bundle.
+ * @param name - the preset name to resolve.
+ * @returns the configured bundle.
+ * @throws when `name` is not in the table.
+ */
+resolve(name: string): PresetSpec
+
+/**
+ * Build the client option for a table entry or {@link CUSTOM_PRESET}. A
+ * missing label falls back to the table key.
+ * @param name - a table key, or `custom`.
+ * @returns the option a client renders.
+ * @throws when `name` is neither a table key nor `custom`.
+ */
+optionOf(name: string): PresetOption
+
+/**
+ * Record a changed preset, then update each changed knob through its own
+ * setter. Selecting the effective preset again appends nothing.
+ * @param session - the session the switch belongs to.
+ * @param name - the preset to switch to; unknown names throw.
+ */
+set(session: Session, name: string): void
+```
+
+Types: [Session](session.md) · [SessionEvent](core.md)
+
+Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
index 4534c33e27..c06714fc6a 100644
--- a/docs/subsystems/permission.zh.md
+++ b/docs/subsystems/permission.zh.md
@@ -65,4 +65,67 @@ interface PresetOption {
 
 `set(session, name)` 解析预设（未知名称抛出异常），在 `name` 尚不是生效预设时追加一条仅记日志的 `permission/preset` 事件，然后通过各旋钮自己的 setter（[dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) 的 `setSandboxMode` 与 [dsh-user-approval](../../packages/interaction/user-approval) 的 `setApprovalPolicy`）写入，且仅当该旋钮的生效值发生变化时才写。同一轮次内，选择事件先于旋钮事件出现；重新选择当前生效的预设则什么都不追加。
 
-`permission/preset` 是持久、仅记日志的用户意图：它不进入模型 transcript（文本记录），模型可见的后果由旋钮事件经各自消费方承担；它存在是为了在两个预设共享同一个旋钮组合时，让 `current()` 仍能保住用户选择的究竟是哪一个预设；`effectivePermissionPreset(events)` 折叠最后一条，回放不需要任何追赶状态。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)；方法签名见生成的[服务目录](../cordis-catalog/services.md#ctxpermission--permissionservice)。
+`permission/preset` 是持久、仅记日志的用户意图：它不进入模型 transcript（文本记录），模型可见的后果由旋钮事件经各自消费方承担；它存在是为了在两个预设共享同一个旋钮组合时，让 `current()` 仍能保住用户选择的究竟是哪一个预设；`effectivePermissionPreset(events)` 折叠最后一条，回放不需要任何追赶状态。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)；方法签名见生成的[服务目录](#ctxpermission--permissionservice)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxpermission--permissionservice"></a>
+
+### `ctx.permission` — `PermissionService`
+
+Owns the deployment's permission presets and their write path. Requires a confining `ctx.bash` executor and `ctx.approval`; unmatched knob values are reported as CUSTOM_PRESET, not an error.
+
+```ts cordis-catalog
+/**
+ * Resolve the preset matching the effective knob values. A still-matching
+ * last selection wins shared-bundle ties; otherwise the first table match
+ * wins, or {@link CUSTOM_PRESET} when no entry matches.
+ * @param events - the session's events in log order.
+ * @returns the effective preset name, or `custom` when nothing matches.
+ */
+current(events: readonly SessionEvent[]): string
+
+/**
+ * Build the whole select value for one folded knob state: every table
+ * option in declaration order, `custom` appended exactly while derived.
+ * @param state - the folded knob overrides.
+ * @returns the `permissions` projection payload.
+ */
+selectFor(state: KnobState): PermissionSelect
+
+/**
+ * Resolve a preset's knob bundle.
+ * @param name - the preset name to resolve.
+ * @returns the configured bundle.
+ * @throws when `name` is not in the table.
+ */
+resolve(name: string): PresetSpec
+
+/**
+ * Build the client option for a table entry or {@link CUSTOM_PRESET}. A
+ * missing label falls back to the table key.
+ * @param name - a table key, or `custom`.
+ * @returns the option a client renders.
+ * @throws when `name` is neither a table key nor `custom`.
+ */
+optionOf(name: string): PresetOption
+
+/**
+ * Record a changed preset, then update each changed knob through its own
+ * setter. Selecting the effective preset again appends nothing.
+ * @param session - the session the switch belongs to.
+ * @param name - the preset to switch to; unknown names throw.
+ */
+set(session: Session, name: string): void
+```
+
+Types: [Session](session.md) · [SessionEvent](core.md)
+
+Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 697094b490..808abb402a 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: 177d596d3d01134266f139b47430e1e5064d04d6
-persistence.zh.md: 6582c0d7d02d1976d5c3ca3322284098130ed4ad
+persistence.md: 1edf3c88fbabe55058bbf94ed8f31decf47cb84a
+persistence.zh.md: dbebd9ff819c8d50cfa9748678dac09c86adde6d
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index 177d596d3d..1edf3c88fb 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -204,3 +204,135 @@ Both implement the same abstract `SessionPersistence` (locate/create/append/prep
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)** — `node:sqlite`, one row per `SessionEvent`. The row shape `(session_id, seq, type, time, data, source_event_seqs, surface_op)` maps 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
+
+### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
+
+Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
+
+```ts cordis-catalog
+/**
+ * Resolve this backend's independent local artifact for a session without
+ * reading, creating, flushing, or otherwise materializing it. Backends such
+ * as SQLite that do not own one artifact per session return `undefined`.
+ * @param meta - the immutable session header whose artifact is requested.
+ * @returns the backend-specific absolute location, when one exists.
+ */
+abstract locate(meta: SessionHeader): SessionLocation | undefined
+
+/**
+ * Register a new session's metadata. A backend MAY defer the physical write
+ * until the first {@link append} (lazy materialization), in which case a
+ * created-but-never-appended session is absent from {@link list}
+ * — abandoned sessions leave nothing behind.
+ * @param meta - the immutable header (id, version, cwd, lineage) to record.
+ */
+abstract create(meta: SessionHeader): Promise<void>
+
+/**
+ * Durably persist a batch of events. Honors the append-only and contiguous-
+ * seq contracts: the first event's `seq` MUST equal the stored next-seq
+ * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
+ * serializable `event.data` with an error naming the offending event type.
+ * @param id - the session the batch belongs to.
+ * @param events - the contiguous batch to persist, in seq order.
+ */
+abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
+
+/**
+ * Prepare the exact unpublished Session used by resume. Implementations may
+ * reuse object graphs retained by an earlier {@link inspect} after confirming
+ * their durable revision is still current; disposal releases an unpublished
+ * reservation. Revision retries require the durable log to remain unchanged
+ * for one read/check round trip; continuous external writers may delay completion.
+ * @param id - persisted session to prepare.
+ * @param signal - optional cancellation for preparation work.
+ * @returns one owned unpublished Session preparation.
+ */
+async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>
+
+/**
+ * Load an immutable balanced logical view and commit any required cold
+ * recovery. A complete interrupted final turn is preserved and durably
+ * closed with missing tool errors plus any open step and turn boundaries;
+ * only a torn final record is discarded. Unknown versions and corruption in
+ * the committed prefix reject. Implementations MUST NOT crash-repair an
+ * identity still bound to a live Session: a balanced live log may return as a
+ * durable snapshot, while an open live turn rejects. Returned values may be
+ * shared with immutable live or prepared state and must not be mutated.
+ * Revision-based implementations may wait for one stable read/check round trip.
+ * @param id - the persisted session to reload.
+ * @returns the header and a log ending on a balanced `turn/end`.
+ */
+abstract load(id: SessionId): Promise<SessionInspection>
+
+/**
+ * Inspect an immutable logical session without committing recovery or
+ * publishing it. A cold complete interrupted turn receives synthetic closers
+ * in memory and a torn physical tail remains untouched. An already-live
+ * Session instead yields its current immutable snapshot, which may contain an
+ * open turn and its `session/end-seed` boundary. Coordinator-backed
+ * implementations retain the exact cold unpublished Session for bounded
+ * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
+ * already committing or reserved for resume remains exclusive, and inspection
+ * may borrow its immutable view. Callers borrow only the immutable header and
+ * log. Continuous external writers may delay revision convergence.
+ * @param id - the persisted session to inspect.
+ * @param signal - optional cancellation for queued and backend read work.
+ * @returns the validated header and current logical event log.
+ */
+abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
+
+/**
+ * Read the stored events from `fromSeq` onward — the read-from-seq
+ * primitive for read models that resume from a watermark (e.g. a persisted
+ * projection cache folding only the tail past its checkpoint). Unlike
+ * {@link inspect}, it is a detached physical suffix read: no preparation
+ * cache, torn-tail truncation, synthetic closers, or coordinator-state
+ * publication. Only events from the valid contiguous stored prefix are
+ * returned, so a torn fragment never reaches the caller. `fromSeq` at or
+ * beyond the stored prefix returns an empty event list (never an error).
+ * Backends whose medium can seek by seq
+ * (SQLite) read only the suffix; sequential media (JSONL, both encodings)
+ * still parse the whole artifact and skip forward — the primitive bounds
+ * what is RETURNED and refolded, not every backend's physical read.
+ * @param id - the persisted session to read.
+ * @param fromSeq - first event seq to include; a non-negative safe integer.
+ * @param signal - optional cancellation for queued and backend read work.
+ * @returns the header and the stored events with `seq >= fromSeq`.
+ */
+abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+
+/**
+ * Lightweight listing from metadata, without a full-log parse.
+ * @param signal - optional cancellation for backend listing work.
+ * @returns one header per materialized session.
+ */
+abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
+
+/**
+ * List materialized sessions with cheap per-log change tokens.
+ *
+ * Repeated observations of an unchanged log return the same revision. A
+ * successful mutating {@link load} repair changes the next listed revision.
+ * Revisions also distinguish independently backed stores so backend-local
+ * counters cannot compare equal across different persistence sources.
+ * @param signal - optional cancellation for backend snapshot-listing work.
+ * @returns one header and opaque revision per materialized session without loading full logs.
+ */
+abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
+```
+
+Types: [SessionEvent](core.md) · [SessionId](core.md)
+
+Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 6582c0d7d0..dbebd9ff81 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -204,3 +204,135 @@ interface SessionPersistenceSnapshot {
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行结构 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
+
+### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
+
+Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
+
+```ts cordis-catalog
+/**
+ * Resolve this backend's independent local artifact for a session without
+ * reading, creating, flushing, or otherwise materializing it. Backends such
+ * as SQLite that do not own one artifact per session return `undefined`.
+ * @param meta - the immutable session header whose artifact is requested.
+ * @returns the backend-specific absolute location, when one exists.
+ */
+abstract locate(meta: SessionHeader): SessionLocation | undefined
+
+/**
+ * Register a new session's metadata. A backend MAY defer the physical write
+ * until the first {@link append} (lazy materialization), in which case a
+ * created-but-never-appended session is absent from {@link list}
+ * — abandoned sessions leave nothing behind.
+ * @param meta - the immutable header (id, version, cwd, lineage) to record.
+ */
+abstract create(meta: SessionHeader): Promise<void>
+
+/**
+ * Durably persist a batch of events. Honors the append-only and contiguous-
+ * seq contracts: the first event's `seq` MUST equal the stored next-seq
+ * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
+ * serializable `event.data` with an error naming the offending event type.
+ * @param id - the session the batch belongs to.
+ * @param events - the contiguous batch to persist, in seq order.
+ */
+abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
+
+/**
+ * Prepare the exact unpublished Session used by resume. Implementations may
+ * reuse object graphs retained by an earlier {@link inspect} after confirming
+ * their durable revision is still current; disposal releases an unpublished
+ * reservation. Revision retries require the durable log to remain unchanged
+ * for one read/check round trip; continuous external writers may delay completion.
+ * @param id - persisted session to prepare.
+ * @param signal - optional cancellation for preparation work.
+ * @returns one owned unpublished Session preparation.
+ */
+async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>
+
+/**
+ * Load an immutable balanced logical view and commit any required cold
+ * recovery. A complete interrupted final turn is preserved and durably
+ * closed with missing tool errors plus any open step and turn boundaries;
+ * only a torn final record is discarded. Unknown versions and corruption in
+ * the committed prefix reject. Implementations MUST NOT crash-repair an
+ * identity still bound to a live Session: a balanced live log may return as a
+ * durable snapshot, while an open live turn rejects. Returned values may be
+ * shared with immutable live or prepared state and must not be mutated.
+ * Revision-based implementations may wait for one stable read/check round trip.
+ * @param id - the persisted session to reload.
+ * @returns the header and a log ending on a balanced `turn/end`.
+ */
+abstract load(id: SessionId): Promise<SessionInspection>
+
+/**
+ * Inspect an immutable logical session without committing recovery or
+ * publishing it. A cold complete interrupted turn receives synthetic closers
+ * in memory and a torn physical tail remains untouched. An already-live
+ * Session instead yields its current immutable snapshot, which may contain an
+ * open turn and its `session/end-seed` boundary. Coordinator-backed
+ * implementations retain the exact cold unpublished Session for bounded
+ * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
+ * already committing or reserved for resume remains exclusive, and inspection
+ * may borrow its immutable view. Callers borrow only the immutable header and
+ * log. Continuous external writers may delay revision convergence.
+ * @param id - the persisted session to inspect.
+ * @param signal - optional cancellation for queued and backend read work.
+ * @returns the validated header and current logical event log.
+ */
+abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
+
+/**
+ * Read the stored events from `fromSeq` onward — the read-from-seq
+ * primitive for read models that resume from a watermark (e.g. a persisted
+ * projection cache folding only the tail past its checkpoint). Unlike
+ * {@link inspect}, it is a detached physical suffix read: no preparation
+ * cache, torn-tail truncation, synthetic closers, or coordinator-state
+ * publication. Only events from the valid contiguous stored prefix are
+ * returned, so a torn fragment never reaches the caller. `fromSeq` at or
+ * beyond the stored prefix returns an empty event list (never an error).
+ * Backends whose medium can seek by seq
+ * (SQLite) read only the suffix; sequential media (JSONL, both encodings)
+ * still parse the whole artifact and skip forward — the primitive bounds
+ * what is RETURNED and refolded, not every backend's physical read.
+ * @param id - the persisted session to read.
+ * @param fromSeq - first event seq to include; a non-negative safe integer.
+ * @param signal - optional cancellation for queued and backend read work.
+ * @returns the header and the stored events with `seq >= fromSeq`.
+ */
+abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+
+/**
+ * Lightweight listing from metadata, without a full-log parse.
+ * @param signal - optional cancellation for backend listing work.
+ * @returns one header per materialized session.
+ */
+abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
+
+/**
+ * List materialized sessions with cheap per-log change tokens.
+ *
+ * Repeated observations of an unchanged log return the same revision. A
+ * successful mutating {@link load} repair changes the next listed revision.
+ * Revisions also distinguish independently backed stores so backend-local
+ * counters cannot compare equal across different persistence sources.
+ * @param signal - optional cancellation for backend snapshot-listing work.
+ * @returns one header and opaque revision per materialized session without loading full logs.
+ */
+abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
+```
+
+Types: [SessionEvent](core.md) · [SessionId](core.md)
+
+Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index f82002420b..efe9e376c6 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
-plan.md: 661a393b18f9154771c0b9358ad7f016a4fdec17
-plan.zh.md: 068b63fd9f3bf46b7962031bba154cc7fc7daafd
+plan.md: ee4b911050863765960ba46952ba923a7115e129
+plan.zh.md: 0481bdf76adf2f00fe18073fe8daa5ba172bbfe1
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index 661a393b18..ee4b911050 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -36,4 +36,51 @@ When [`ctx.commands`](commands.md) is composed, the plugin registers `/plan [off
 
 ## The service
 
-`ctx.planMode` owns the logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool; `get`/`set` signatures are in the generated [service catalog](../cordis-catalog/services.md#ctxplanmode--planmodeservice).
+`ctx.planMode` owns the logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool; `get`/`set` signatures are in the generated [service catalog](#ctxplanmode--planmodeservice).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxplanmode--planmodeservice"></a>
+
+### `ctx.planMode` — `PlanModeService`
+
+`ctx.planMode`: owns logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool. UIs observe committed flips through `session/event`; there is no live mirror.
+
+```ts cordis-catalog
+/**
+ * Read the logged plan state and any selected state awaiting a boundary.
+ *
+ * @param agent The agent to read.
+ * @returns Current logged state plus a pending selection, when present.
+ */
+get(agent: Agent): { active: boolean; pending?: boolean }
+
+/**
+ * Select whether plan mode should be active. Between turns the change
+ * commits immediately — no request boundary would arrive until the next
+ * prompt, so a queued intent would hang (the open-turn fold is the idle
+ * signal: agent status stays `running` through post-turn checkpointing,
+ * where a boundary equally never comes). During an open turn the
+ * selection is held as pending intent for the next in-turn request
+ * boundary. Repeated selection of the current or already-pending state is
+ * a no-op.
+ *
+ * @param agent The agent to switch.
+ * @param active Whether plan mode should be active.
+ * @returns what happened: `committed` (logged now), `queued` (awaiting the
+ * next boundary), `cancelled` (an opposite pending selection was cleared;
+ * the logged state already matches), or `noop` (already in that state).
+ */
+set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/plan/plan-mode/src/index.ts:183`](../../packages/plan/plan-mode/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index 068b63fd9f..0481bdf76a 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -36,4 +36,51 @@ interface PlanModeConfig {
 
 ## 服务
 
-`ctx.planMode` 拥有已记录的计划状态、边界处的应用与叙述、`plan:policy` 段落、`/plan` 命令和稳定注册的退出工具；`get`/`set` 签名见生成的[服务目录](../cordis-catalog/services.md#ctxplanmode--planmodeservice)。
+`ctx.planMode` 拥有已记录的计划状态、边界处的应用与叙述、`plan:policy` 段落、`/plan` 命令和稳定注册的退出工具；`get`/`set` 签名见生成的[服务目录](#ctxplanmode--planmodeservice)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxplanmode--planmodeservice"></a>
+
+### `ctx.planMode` — `PlanModeService`
+
+`ctx.planMode`: owns logged plan state, boundary application and narration, the `plan:policy` section, the `/plan` command, and the stable exit tool. UIs observe committed flips through `session/event`; there is no live mirror.
+
+```ts cordis-catalog
+/**
+ * Read the logged plan state and any selected state awaiting a boundary.
+ *
+ * @param agent The agent to read.
+ * @returns Current logged state plus a pending selection, when present.
+ */
+get(agent: Agent): { active: boolean; pending?: boolean }
+
+/**
+ * Select whether plan mode should be active. Between turns the change
+ * commits immediately — no request boundary would arrive until the next
+ * prompt, so a queued intent would hang (the open-turn fold is the idle
+ * signal: agent status stays `running` through post-turn checkpointing,
+ * where a boundary equally never comes). During an open turn the
+ * selection is held as pending intent for the next in-turn request
+ * boundary. Repeated selection of the current or already-pending state is
+ * a no-op.
+ *
+ * @param agent The agent to switch.
+ * @param active Whether plan mode should be active.
+ * @returns what happened: `committed` (logged now), `queued` (awaiting the
+ * next boundary), `cancelled` (an opposite pending selection was cleared;
+ * the logged state already matches), or `noop` (already in that state).
+ */
+set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/plan/plan-mode/src/index.ts:183`](../../packages/plan/plan-mode/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/pty.i18n.yaml b/docs/subsystems/pty.i18n.yaml
index 11788e8e76..76b4500aea 100644
--- a/docs/subsystems/pty.i18n.yaml
+++ b/docs/subsystems/pty.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 docs/core-data-structures/pty.md
-pty.md: 97e1e662d1128ab0555e34f8284cf69d7d9d0d1a
-pty.zh.md: a57f7448274de583dbb110ba9499e15dfb4de5f9
+#   pnpm run verify-translation-pairing --write docs/subsystems/pty.md
+pty.md: 45b157c73926d85d5fc2bb037d3954da7bf75063
+pty.zh.md: 4409ef0b0504780b0b5564a34b61d4f1b2c02775
diff --git a/docs/subsystems/pty.md b/docs/subsystems/pty.md
index 97e1e662d1..45b157c739 100644
--- a/docs/subsystems/pty.md
+++ b/docs/subsystems/pty.md
@@ -89,3 +89,96 @@ interface PtySendResult {
 ## Ownership and durability
 
 `PtyService` attaches one awaited cleanup to the exact owner scope, rejects foreign operations, and keeps sessions alive across backend or tool-plugin reload. PTY state and raw bytes remain process-local. Model input and bounded returned output are durable through the existing `tool/call`, `tool/result`, and task-result paths rather than duplicate PTY session events.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxpty--ptyservice"></a>
+
+### `ctx.pty` — `PtyService`
+
+In-process registry for replaceable PTY backends and exact-Agent sessions.
+
+```ts cordis-catalog
+/**
+ * Register one backend type for this effect scope.
+ * @param backend - provider with a non-empty unique type.
+ * @returns disposer that removes exactly this contribution.
+ */
+registerBackend(backend: PtyBackend): () => void
+
+/**
+ * List registered backend types in registration order.
+ * @returns fresh backend type names.
+ */
+listBackends(): string[]
+
+/**
+ * Create and publish one owner-scoped session after backend setup succeeds.
+ * @param owner - exact registered Agent that owns access and cleanup.
+ * @param request - backend type plus optional owner-local name and cwd.
+ * @param signal - cancellation of unpublished setup.
+ * @returns published identity, metadata, status, and MOTD.
+ */
+async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult>
+
+/**
+ * Test whether an exact owner has a published session or unpublished spawn.
+ * @param owner - exact live owner to inspect.
+ * @returns true across the entire spawn-to-close interval, with no publication gap.
+ */
+hasOwnerActivity(owner: Agent): boolean
+
+/**
+ * Start one exclusive interactive send.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param request - explicit text, submit behavior, and cancellation.
+ * @returns live operation handle for foreground await or task registration.
+ */
+startSend(owner: Agent, id: PtySessionId, request: PtySendRequest): PtySendOperation
+
+/**
+ * Read one bounded scrollback page from an owned session.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param request - optional newest-relative offset and line count.
+ * @returns bounded retained text and pagination metadata.
+ */
+read(owner: Agent, id: PtySessionId, request: PtyReadRequest = {}): PtyReadResult
+
+/**
+ * Deliver an allowed signal through an owned backend session.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param signal - allowed POSIX signal name.
+ * @returns delivered foreground process-group identity.
+ */
+signal(owner: Agent, id: PtySessionId, signal: PtySignal): Promise<PtySignalResult>
+
+/**
+ * Close one owned session and remove it only after quiescent backend cleanup.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param reason - diagnostic cleanup reason.
+ * @returns true for a newly closed session, false when the same close is already in flight.
+ */
+async kill(owner: Agent, id: PtySessionId, reason: string = 'model request'): Promise<boolean>
+
+/**
+ * List fresh snapshots for exactly one owner.
+ * @param owner - exact owner whose sessions are visible.
+ * @returns owner-visible snapshots in publication order.
+ */
+list(owner: Agent): PtySessionSnapshot[]
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/pty.zh.md b/docs/subsystems/pty.zh.md
index a57f744827..4409ef0b05 100644
--- a/docs/subsystems/pty.zh.md
+++ b/docs/subsystems/pty.zh.md
@@ -89,3 +89,96 @@ interface PtySendResult {
 ## 归属与持久性
 
 `PtyService` 会将一项等待完成的清理附加到确切的拥有者作用域，拒绝其他拥有者的操作，并让会话在后端或工具插件重载期间保持存活。PTY 状态与原始字节仍局限在进程内。模型输入与有界返回输出通过现有 `tool/call`、`tool/result` 和任务结果路径持久保存，而不是重复记录 PTY 会话事件。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxpty--ptyservice"></a>
+
+### `ctx.pty` — `PtyService`
+
+In-process registry for replaceable PTY backends and exact-Agent sessions.
+
+```ts cordis-catalog
+/**
+ * Register one backend type for this effect scope.
+ * @param backend - provider with a non-empty unique type.
+ * @returns disposer that removes exactly this contribution.
+ */
+registerBackend(backend: PtyBackend): () => void
+
+/**
+ * List registered backend types in registration order.
+ * @returns fresh backend type names.
+ */
+listBackends(): string[]
+
+/**
+ * Create and publish one owner-scoped session after backend setup succeeds.
+ * @param owner - exact registered Agent that owns access and cleanup.
+ * @param request - backend type plus optional owner-local name and cwd.
+ * @param signal - cancellation of unpublished setup.
+ * @returns published identity, metadata, status, and MOTD.
+ */
+async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult>
+
+/**
+ * Test whether an exact owner has a published session or unpublished spawn.
+ * @param owner - exact live owner to inspect.
+ * @returns true across the entire spawn-to-close interval, with no publication gap.
+ */
+hasOwnerActivity(owner: Agent): boolean
+
+/**
+ * Start one exclusive interactive send.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param request - explicit text, submit behavior, and cancellation.
+ * @returns live operation handle for foreground await or task registration.
+ */
+startSend(owner: Agent, id: PtySessionId, request: PtySendRequest): PtySendOperation
+
+/**
+ * Read one bounded scrollback page from an owned session.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param request - optional newest-relative offset and line count.
+ * @returns bounded retained text and pagination metadata.
+ */
+read(owner: Agent, id: PtySessionId, request: PtyReadRequest = {}): PtyReadResult
+
+/**
+ * Deliver an allowed signal through an owned backend session.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param signal - allowed POSIX signal name.
+ * @returns delivered foreground process-group identity.
+ */
+signal(owner: Agent, id: PtySessionId, signal: PtySignal): Promise<PtySignalResult>
+
+/**
+ * Close one owned session and remove it only after quiescent backend cleanup.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param reason - diagnostic cleanup reason.
+ * @returns true for a newly closed session, false when the same close is already in flight.
+ */
+async kill(owner: Agent, id: PtySessionId, reason: string = 'model request'): Promise<boolean>
+
+/**
+ * List fresh snapshots for exactly one owner.
+ * @param owner - exact owner whose sessions are visible.
+ * @returns owner-visible snapshots in publication order.
+ */
+list(owner: Agent): PtySessionSnapshot[]
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
index 34691ad25b..efbd158e18 100644
--- a/docs/subsystems/sandbox.i18n.yaml
+++ b/docs/subsystems/sandbox.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 docs/core-data-structures/sandbox.md
-sandbox.md: 9e5feafe046f18dad49aeaf281793f0b8e03c240
-sandbox.zh.md: a1314d1b78eb0d46ea4c8ca5aa330ee83bf89132
+#   pnpm run verify-translation-pairing --write docs/subsystems/sandbox.md
+sandbox.md: dd960b3021dcdc87cfd36fd439cbec0a810dd736
+sandbox.zh.md: f526982a782144a0bf58abcde5d883e9dc813369
diff --git a/docs/subsystems/sandbox.md b/docs/subsystems/sandbox.md
index 9e5feafe04..dd960b3021 100644
--- a/docs/subsystems/sandbox.md
+++ b/docs/subsystems/sandbox.md
@@ -146,3 +146,65 @@ The [local provider](../../packages/sandbox/sandbox-local/README.md) owns operat
 `ctx.sandbox.confine(argv, policy)` returns a `ConfinedArgv` or throws `SandboxUnavailableError` with code `SANDBOX_UNAVAILABLE` when no usable backend exists. Consumers may also classify a failure while spawning or observing the returned argv; that attribution belongs to the consumer contract. Silent unconfined passthrough is never legal for a confined policy.
 
 Provider selection, probing, caching, and backend-specific enforcement reports belong to the [local provider](../../packages/sandbox/sandbox-local/README.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
+
+### `ctx.sandbox` — `SandboxProvider` (abstract seam)
+
+Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
+
+```ts cordis-catalog
+/**
+ * Wrap `argv` so it executes confined under `policy` on this host; the
+ * caller spawns the returned argv in place of its own.
+ * @param argv - the exact argv the caller is about to spawn (program plus
+ *   arguments), NOT a shell string — a shell-shaped consumer passes
+ *   `['bash', '-c', command]`.
+ * @param policy - the file-effect policy this execution runs under,
+ *   carried per call (see {@link SandboxPolicy}).
+ * @returns the argv to spawn instead, plus the enforcement completeness
+ *   the selected backend achieves for it.
+ */
+abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv
+```
+
+Source: [`packages/sandbox/sandbox/src/index.ts:148`](../../packages/sandbox/sandbox/src/index.ts)
+
+<a id="ctxsandboxpolicy--sandboxpolicyservice"></a>
+
+### `ctx.sandboxPolicy` — `SandboxPolicyService`
+
+The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode, fallback workspace root, and current request-time policy section. Tool layers call resolve for each execution so a session's mode log and immutable cwd travel together to every enforcing capability.
+
+```ts cordis-catalog
+/**
+ * Resolve the complete policy for one capability call. An approved explicit
+ * mode outranks the session's last `sandbox/mode` event, which outranks the
+ * deployment default. A session cwd is its workspace-write boundary; the
+ * configured root is the fallback for agentless calls and sessions without a
+ * cwd.
+ * @param request - optional session and approved mode override.
+ * @returns the fully resolved per-call mode and absolute workspace root.
+ */
+resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
+
+/**
+ * Read the session override without applying the deployment default.
+ * @param session - session whose log supplies the override.
+ * @returns the last logged mode, or `undefined` without one.
+ */
+overrideOf(session: Session): SandboxMode | undefined
+```
+
+Types: [Session](session.md)
+
+Source: [`packages/sandbox/sandbox-policy/src/index.ts:91`](../../packages/sandbox/sandbox-policy/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
index a1314d1b78..f526982a78 100644
--- a/docs/subsystems/sandbox.zh.md
+++ b/docs/subsystems/sandbox.zh.md
@@ -146,3 +146,65 @@ interface ConfinedArgv {
 `ctx.sandbox.confine(argv, policy)` 返回一个 `ConfinedArgv`，或在没有可用后端时抛出 `SandboxUnavailableError`（错误码 `SANDBOX_UNAVAILABLE`）。消费方也可以在 spawn 或观察所返回的 argv 时对失败进行分类；该归因属于消费方契约。对于受限策略，静默的无隔离透传永远不合法。
 
 提供方选择、探测、缓存和后端专有的强制执行报告归[本地提供方](../../packages/sandbox/sandbox-local/README.md)所有。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
+
+### `ctx.sandbox` — `SandboxProvider` (abstract seam)
+
+Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
+
+```ts cordis-catalog
+/**
+ * Wrap `argv` so it executes confined under `policy` on this host; the
+ * caller spawns the returned argv in place of its own.
+ * @param argv - the exact argv the caller is about to spawn (program plus
+ *   arguments), NOT a shell string — a shell-shaped consumer passes
+ *   `['bash', '-c', command]`.
+ * @param policy - the file-effect policy this execution runs under,
+ *   carried per call (see {@link SandboxPolicy}).
+ * @returns the argv to spawn instead, plus the enforcement completeness
+ *   the selected backend achieves for it.
+ */
+abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv
+```
+
+Source: [`packages/sandbox/sandbox/src/index.ts:148`](../../packages/sandbox/sandbox/src/index.ts)
+
+<a id="ctxsandboxpolicy--sandboxpolicyservice"></a>
+
+### `ctx.sandboxPolicy` — `SandboxPolicyService`
+
+The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode, fallback workspace root, and current request-time policy section. Tool layers call resolve for each execution so a session's mode log and immutable cwd travel together to every enforcing capability.
+
+```ts cordis-catalog
+/**
+ * Resolve the complete policy for one capability call. An approved explicit
+ * mode outranks the session's last `sandbox/mode` event, which outranks the
+ * deployment default. A session cwd is its workspace-write boundary; the
+ * configured root is the fallback for agentless calls and sessions without a
+ * cwd.
+ * @param request - optional session and approved mode override.
+ * @returns the fully resolved per-call mode and absolute workspace root.
+ */
+resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
+
+/**
+ * Read the session override without applying the deployment default.
+ * @param session - session whose log supplies the override.
+ * @returns the last logged mode, or `undefined` without one.
+ */
+overrideOf(session: Session): SandboxMode | undefined
+```
+
+Types: [Session](session.md)
+
+Source: [`packages/sandbox/sandbox-policy/src/index.ts:91`](../../packages/sandbox/sandbox-policy/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
new file mode 100644
index 0000000000..24b1c7b234
--- /dev/null
+++ b/docs/subsystems/session-projection.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 docs/subsystems/session-projection.md
+session-projection.md: 56f9fb43dddc482264aab52ceeb9b9920df148cd
+session-projection.zh.md: 4a2310fed4af6f018af07b5f2b46d3c28aa361a4
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
new file mode 100644
index 0000000000..56f9fb43dd
--- /dev/null
+++ b/docs/subsystems/session-projection.md
@@ -0,0 +1,262 @@
+# Session Projections
+
+English | [中文](session-projection.zh.md)
+
+The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the interface and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame today). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
+
+Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
+
+## The unit
+
+`SessionProjectionMap` is the merge-extensible type table for the whole chain (host unit, wire block, client hook); values are wire-JSON whole values, and rendering belongs to the slot system, never this layer. A domain contributes one `ProjectionDefinition` per key:
+
+```ts type-equiv
+/**
+ * One domain's state-driven computation unit: three pure synchronous
+ * functions plus declarations — never an opaque getter. The framework drives
+ * `apply` on every committed session event; the domain holds no
+ * subscriptions and owns only the mathematics. All three functions MUST be
+ * synchronous (an async unit would tear the carriers' consistency cut) and
+ * `state` MUST be plain JSON (the persisted-cache precondition).
+ */
+interface ProjectionDefinition<K extends keyof SessionProjectionMap, S> {
+  /** The projection key this unit owns (its `SessionProjectionMap` entry). */
+  key: K
+  /** Validates the wire payload (`view` output) before it leaves the host. */
+  schema: ZodType<SessionProjectionMap[K]>
+  /**
+   * State for the empty log.
+   * @returns the initial state.
+   */
+  init(): S
+  /**
+   * Pure transition: previous state + one committed event → next state. A
+   * unit uninterested in an event MUST return the same state reference — an
+   * unchanged reference (`Object.is`) produces zero downstream work.
+   * @param state - the state covering all prior events.
+   * @param event - the next committed session event.
+   * @returns the next state (same reference when the event is not the unit's).
+   */
+  apply(state: S, event: SessionEvent): S
+  /**
+   * State → wire payload (the read-side projection).
+   * @param state - the current state.
+   * @returns the whole current value for this unit's key.
+   */
+  view(state: S): SessionProjectionMap[K]
+  /**
+   * Persisted-cache invalidation anchor: bump whenever the state shape or the
+   * fold semantics change, so persisted `(sessionId, key, ver, seq, val)`
+   * rows from an older unit are discarded instead of being forward-applied
+   * into garbage. Non-negative integer.
+   */
+  stateVersion: number
+}
+```
+
+The whole-value event rule is load-bearing: a state-carrying log event carries the complete post-change state, never a bare delta — it keeps every transition trivially cheap and every served value self-describing (last-wins for consumers).
+
+## The snapshot and the change feed
+
+```ts type-equiv
+/**
+ * One consistent read cut over every registered unit for one session.
+ * `asOfSeq` is the shared watermark — the seq of the last event every value
+ * reflects (`-1` for an empty log, mirroring `session/subscribed.lastSeq`).
+ */
+interface ProjectionSnapshot {
+  /** Seq of the last event the values reflect; -1 for an empty log. */
+  asOfSeq: number
+  /** Whole current value per registered key. */
+  values: Partial<SessionProjectionMap>
+}
+```
+
+```ts type-equiv
+/**
+ * Change-feed listener: one unit's value changed for one session. `value` is
+ * the schema-validated `view` output; `seq` is the unit's watermark at
+ * emission (the seq of the event that caused the change).
+ */
+type ProjectionChangeListener = (
+  session: Session,
+  key: Extract<keyof SessionProjectionMap, string>,
+  value: unknown,
+  seq: number,
+) => void
+```
+
+`snapshot(session)` is fully synchronous — a carrier reads it in the same tick as its page slice, which is what makes `asOfSeq` one consistent cut — and every value passes its unit's schema before leaving (an accidentally-async `view` returns a Promise, which fails that boundary parse loudly). The change feed fires once per unit whose state *reference* changed, per committed event: the same-reference discipline in `apply` is the gate.
+
+## The registry: `ctx.sessionProjections`
+
+`SessionProjectionRegistry` ([signatures](#ctxsessionprojections--sessionprojectionregistry)) owns the drive: one `session/event` subscription, eager `apply` over every registered unit, and per-session per-unit watermark cells. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect whose disposer rides the calling fiber: an unloaded domain plugin's key (with its cached cells) disappears from subsequent drives and snapshots, and clients read that as capability absence; duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionprojectioncache--sessionprojectioncache"></a>
+
+### `ctx.sessionProjectionCache` — `SessionProjectionCache`
+
+The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus two mandatory points — `turn/end` and session disposal (the live-to-cold moment) — and serves the cold-read ladder: cached row, persistence `readFrom` tail, registry `restore`, durable write-back. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write or cold read.
+
+```ts cordis-catalog
+/**
+ * The zero-I/O listing read: whole values viewed straight from the stored
+ * rows (version-matching keys only), each cut carried with its watermark
+ * so a client value store can seed under its higher-seq-wins rule — as
+ * stale as the last durable checkpoint but never wrong, and never from an
+ * unrelated log (the caller's header is the identity witness). Fresher
+ * paths (the history tail baseline, {@link coldSnapshot}) supersede these
+ * values whenever a session is actually opened.
+ * @param meta - the listed session's header (identity witness; no log read).
+ * @returns the cut (`asOfSeq` = lowest served-row watermark), or
+ *   `undefined` when no usable row exists for this lifecycle.
+ */
+cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined
+
+/**
+ * Durably checkpoint one live session NOW (both mandatory points call
+ * this; tests and carriers may too). The registry cut is snapshotted at
+ * this boundary (states are live references), then the whole record is
+ * replaced. NOT fail-soft — callers on the fail-soft paths contain it.
+ * @param session - the live session to checkpoint.
+ * @returns resolution after durability and event emission.
+ */
+async write(session: Session): Promise<void>
+
+/**
+ * Cold-read one persisted session's projections with zero full-log load:
+ * cached rows + a persistence `readFrom` tail from the registry's restore
+ * floor, refolded by the registry and written back (fail-soft) so the next
+ * cold read starts closer. A cache row invalidated by a shrunk log
+ * (crash-repair truncation) triggers one full re-read from seq 0 — the
+ * ladder's slow rung, still no crash. Rejects when the session has no
+ * persisted log (`not found` from the persistence seam).
+ * @param id - the persisted session to read.
+ * @param signal - optional cancellation for the persistence reads.
+ * @returns the snapshot cut at the stored log end.
+ */
+async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>
+```
+
+Types: [Session](session.md) · [SessionHeader](persistence.md) · [SessionId](core.md)
+
+Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
+
+<a id="ctxsessionprojections--sessionprojectionregistry"></a>
+
+### `ctx.sessionProjections` — `SessionProjectionRegistry`
+
+`ctx.sessionProjections`: the projection unit table and its drive. The service subscribes to `session/event` once; every committed event passes every registered unit's `apply` (eager drive), and a changed state reference notifies the change feed with the schema-validated view. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect (disposer rides the calling fiber): an unloaded domain plugin's key disappears from snapshots and clients read it as capability absence. Duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
+
+```ts cordis-catalog
+/**
+ * Register one domain's unit. The registration is an effect on the calling
+ * context's fiber: disposing the fiber (or calling the returned disposer)
+ * removes the key — and the unit's cached cells — from subsequent drives
+ * and snapshots.
+ * @param definition - key, boundary schema, pure unit functions, and stateVersion.
+ * @returns the exact disposer that unregisters this unit.
+ */
+register<K extends keyof SessionProjectionMap, S>(definition: ProjectionDefinition<K, S>): () => void
+
+/**
+ * Subscribe to the change feed. The registration is an effect on the
+ * calling context's fiber.
+ * @param listener - called once per unit whose state reference changed, per committed event.
+ * @returns the exact disposer that unsubscribes.
+ */
+onChanged(listener: ProjectionChangeListener): () => void
+
+/**
+ * One consistent cut over every registered unit for one session, read from
+ * the watermark cache (missing cells fold lazily over the in-memory log).
+ * Fully synchronous — every value and `asOfSeq` reflect the same log
+ * position. Each value passes its unit's schema before leaving.
+ * @param session - the session whose projection values are read.
+ * @returns the snapshot; `values` is empty when no unit is registered.
+ */
+snapshot(session: Session): ProjectionSnapshot
+
+/**
+ * State-level checkpoint of every registered unit for one session, read
+ * from the watermark cache (missing cells fold lazily over the in-memory
+ * log). This is the write side of the persisted projection cache: the
+ * returned rows are the `(key → {ver, seq, val})` part of the durable
+ * `(sessionId, key, ver, seq, val)`
+ * rows. Every `val` is a DETACHED structured clone — never the live
+ * cell reference: the watermark cache is this registry's authoritative
+ * mutable state, and a caller reaching the live reference could corrupt
+ * every subsequent snapshot and frame through it (plain JSON by the unit
+ * contract, so the clone is total).
+ * @param session - the session whose unit states are checkpointed.
+ * @returns one row per registered key; empty when no unit is registered.
+ */
+checkpoint(session: Session): ProjectionCheckpoint
+
+/**
+ * The stored seq a {@link restore} tail read over `checkpoint` must start
+ * at: one event BELOW the lowest usable watermark (a row is usable when
+ * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
+ * pulls the floor to `0` — that key must refold the full log). The
+ * one-below anchor is load-bearing: the tail then proves how far the
+ * stored log still extends, so {@link restore} can detect a log that
+ * shrank below a row's watermark (crash-repair truncation) instead of
+ * serving the stale row as current — an empty tail read from the anchor
+ * yields an end below every watermark and the restore rejects for a full
+ * re-read.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns the seq to hand the persistence `readFrom`, or `undefined`
+ *   when no unit is registered (no read needed — {@link restore} would
+ *   serve empty values regardless).
+ */
+restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined
+
+/**
+ * View a checkpoint's rows without any log read: for every registered
+ * unit whose row's `ver` matches, serve the schema-validated
+ * `view` of the stored state; mismatched or absent rows leave their key
+ * absent (a cold or listing consumer treats it as not-yet-available and a
+ * fuller read path refolds it). The zero-I/O rung of the read ladder —
+ * values are as stale as their rows, never wrong.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns whole values per key with a usable row; empty when none.
+ */
+viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
+
+/**
+ * Cold read: fold every registered unit over a stored log suffix, seeding
+ * each from its checkpoint row when usable — the one read recipe (cached
+ * state + forward tail replay + `view`) applied without a live `Session`.
+ * Call with the events returned by a persistence
+ * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+ * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
+ * so a shrunk log is detected here. A row is usable iff its
+ * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
+ * (`seq >= baseSeq - 1`), and it does not claim events past the
+ * supplied end (`seq <= endSeq`); an unusable row is discarded
+ * and its key refolds from `init` — which is only sound over the full
+ * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
+ * from seq 0, e.g. after a crash-repair truncation shrank the log below
+ * a row's watermark).
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @param events - the stored events with `seq >= baseSeq`, in seq order.
+ * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
+ * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
+ *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
+ *   refreshed checkpoint rows at that cut, ready for a durable write-back.
+ */
+restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
+```
+
+Types: [Session](session.md) · [SessionEvent](core.md)
+
+Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
new file mode 100644
index 0000000000..4a2310fed4
--- /dev/null
+++ b/docs/subsystems/session-projection.zh.md
@@ -0,0 +1,262 @@
+# 会话投影
+
+[English](session-projection.md) | 中文
+
+会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是接口与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流契约：[包（package）README](../../packages/session/session-projection/README.md)。
+
+源码：[`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
+
+## 投影单元
+
+`SessionProjectionMap` 是整条链路（host 侧单元、协议块、客户端钩子）的 merge-extensible 类型表；值是协议层 JSON 全量值，渲染归 slot 体系管，永远不归本层。领域为每个 key 贡献一个 `ProjectionDefinition`：
+
+```ts type-equiv
+/**
+ * One domain's state-driven computation unit: three pure synchronous
+ * functions plus declarations — never an opaque getter. The framework drives
+ * `apply` on every committed session event; the domain holds no
+ * subscriptions and owns only the mathematics. All three functions MUST be
+ * synchronous (an async unit would tear the carriers' consistency cut) and
+ * `state` MUST be plain JSON (the persisted-cache precondition).
+ */
+interface ProjectionDefinition<K extends keyof SessionProjectionMap, S> {
+  /** The projection key this unit owns (its `SessionProjectionMap` entry). */
+  key: K
+  /** Validates the wire payload (`view` output) before it leaves the host. */
+  schema: ZodType<SessionProjectionMap[K]>
+  /**
+   * State for the empty log.
+   * @returns the initial state.
+   */
+  init(): S
+  /**
+   * Pure transition: previous state + one committed event → next state. A
+   * unit uninterested in an event MUST return the same state reference — an
+   * unchanged reference (`Object.is`) produces zero downstream work.
+   * @param state - the state covering all prior events.
+   * @param event - the next committed session event.
+   * @returns the next state (same reference when the event is not the unit's).
+   */
+  apply(state: S, event: SessionEvent): S
+  /**
+   * State → wire payload (the read-side projection).
+   * @param state - the current state.
+   * @returns the whole current value for this unit's key.
+   */
+  view(state: S): SessionProjectionMap[K]
+  /**
+   * Persisted-cache invalidation anchor: bump whenever the state shape or the
+   * fold semantics change, so persisted `(sessionId, key, ver, seq, val)`
+   * rows from an older unit are discarded instead of being forward-applied
+   * into garbage. Non-negative integer.
+   */
+  stateVersion: number
+}
+```
+
+全量值事件规则是承重结构：携带状态的日志事件携带的是变更后的完整状态，绝不是裸增量——这让每次状态转移始终足够廉价，也让每个被供给的值自描述（对消费方即 last-wins）。
+
+## 快照与变更流
+
+```ts type-equiv
+/**
+ * One consistent read cut over every registered unit for one session.
+ * `asOfSeq` is the shared watermark — the seq of the last event every value
+ * reflects (`-1` for an empty log, mirroring `session/subscribed.lastSeq`).
+ */
+interface ProjectionSnapshot {
+  /** Seq of the last event the values reflect; -1 for an empty log. */
+  asOfSeq: number
+  /** Whole current value per registered key. */
+  values: Partial<SessionProjectionMap>
+}
+```
+
+```ts type-equiv
+/**
+ * Change-feed listener: one unit's value changed for one session. `value` is
+ * the schema-validated `view` output; `seq` is the unit's watermark at
+ * emission (the seq of the event that caused the change).
+ */
+type ProjectionChangeListener = (
+  session: Session,
+  key: Extract<keyof SessionProjectionMap, string>,
+  value: unknown,
+  seq: number,
+) => void
+```
+
+`snapshot(session)` 是完全同步的：载体在切出页面切片的同一 tick 内读取它，`asOfSeq` 之所以是一个一致切面正系于此；且每个值在离开前都要经过其单元的 schema 校验（误写成异步的 `view` 会返回 Promise，让这道边界解析当场大声失败）。变更流对每个已提交事件、每个状态*引用*发生变化的单元各触发一次：`apply` 的同引用纪律就是那道闸门。
+
+## 注册表：`ctx.sessionProjections`
+
+`SessionProjectionRegistry`（[签名](#ctxsessionprojections--sessionprojectionregistry)）拥有驱动权：一份 `session/event` 订阅、对每个已注册单元的正向 `apply`，以及每会话每单元的水位线（watermark）cell。cell 惰性构建：在事件流过之后才注册的单元，或比注册表更早的会话，都在首次触达（事件或读取）时从 `init` 出发在内存日志上折叠。注册是一个 effect，其 disposer 随调用方 fiber 走：领域插件卸载后，其 key（连同缓存的 cell）从后续驱动与快照中消失，客户端将其读作能力缺失；key 重复直接 throw。领域插件在 `ctx.inject(['sessionProjections'], …)` 下注册，因此不带注册表的 headless 组装完全不受影响。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionprojectioncache--sessionprojectioncache"></a>
+
+### `ctx.sessionProjectionCache` — `SessionProjectionCache`
+
+The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus two mandatory points — `turn/end` and session disposal (the live-to-cold moment) — and serves the cold-read ladder: cached row, persistence `readFrom` tail, registry `restore`, durable write-back. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write or cold read.
+
+```ts cordis-catalog
+/**
+ * The zero-I/O listing read: whole values viewed straight from the stored
+ * rows (version-matching keys only), each cut carried with its watermark
+ * so a client value store can seed under its higher-seq-wins rule — as
+ * stale as the last durable checkpoint but never wrong, and never from an
+ * unrelated log (the caller's header is the identity witness). Fresher
+ * paths (the history tail baseline, {@link coldSnapshot}) supersede these
+ * values whenever a session is actually opened.
+ * @param meta - the listed session's header (identity witness; no log read).
+ * @returns the cut (`asOfSeq` = lowest served-row watermark), or
+ *   `undefined` when no usable row exists for this lifecycle.
+ */
+cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined
+
+/**
+ * Durably checkpoint one live session NOW (both mandatory points call
+ * this; tests and carriers may too). The registry cut is snapshotted at
+ * this boundary (states are live references), then the whole record is
+ * replaced. NOT fail-soft — callers on the fail-soft paths contain it.
+ * @param session - the live session to checkpoint.
+ * @returns resolution after durability and event emission.
+ */
+async write(session: Session): Promise<void>
+
+/**
+ * Cold-read one persisted session's projections with zero full-log load:
+ * cached rows + a persistence `readFrom` tail from the registry's restore
+ * floor, refolded by the registry and written back (fail-soft) so the next
+ * cold read starts closer. A cache row invalidated by a shrunk log
+ * (crash-repair truncation) triggers one full re-read from seq 0 — the
+ * ladder's slow rung, still no crash. Rejects when the session has no
+ * persisted log (`not found` from the persistence seam).
+ * @param id - the persisted session to read.
+ * @param signal - optional cancellation for the persistence reads.
+ * @returns the snapshot cut at the stored log end.
+ */
+async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>
+```
+
+Types: [Session](session.md) · [SessionHeader](persistence.md) · [SessionId](core.md)
+
+Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
+
+<a id="ctxsessionprojections--sessionprojectionregistry"></a>
+
+### `ctx.sessionProjections` — `SessionProjectionRegistry`
+
+`ctx.sessionProjections`: the projection unit table and its drive. The service subscribes to `session/event` once; every committed event passes every registered unit's `apply` (eager drive), and a changed state reference notifies the change feed with the schema-validated view. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect (disposer rides the calling fiber): an unloaded domain plugin's key disappears from snapshots and clients read it as capability absence. Duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
+
+```ts cordis-catalog
+/**
+ * Register one domain's unit. The registration is an effect on the calling
+ * context's fiber: disposing the fiber (or calling the returned disposer)
+ * removes the key — and the unit's cached cells — from subsequent drives
+ * and snapshots.
+ * @param definition - key, boundary schema, pure unit functions, and stateVersion.
+ * @returns the exact disposer that unregisters this unit.
+ */
+register<K extends keyof SessionProjectionMap, S>(definition: ProjectionDefinition<K, S>): () => void
+
+/**
+ * Subscribe to the change feed. The registration is an effect on the
+ * calling context's fiber.
+ * @param listener - called once per unit whose state reference changed, per committed event.
+ * @returns the exact disposer that unsubscribes.
+ */
+onChanged(listener: ProjectionChangeListener): () => void
+
+/**
+ * One consistent cut over every registered unit for one session, read from
+ * the watermark cache (missing cells fold lazily over the in-memory log).
+ * Fully synchronous — every value and `asOfSeq` reflect the same log
+ * position. Each value passes its unit's schema before leaving.
+ * @param session - the session whose projection values are read.
+ * @returns the snapshot; `values` is empty when no unit is registered.
+ */
+snapshot(session: Session): ProjectionSnapshot
+
+/**
+ * State-level checkpoint of every registered unit for one session, read
+ * from the watermark cache (missing cells fold lazily over the in-memory
+ * log). This is the write side of the persisted projection cache: the
+ * returned rows are the `(key → {ver, seq, val})` part of the durable
+ * `(sessionId, key, ver, seq, val)`
+ * rows. Every `val` is a DETACHED structured clone — never the live
+ * cell reference: the watermark cache is this registry's authoritative
+ * mutable state, and a caller reaching the live reference could corrupt
+ * every subsequent snapshot and frame through it (plain JSON by the unit
+ * contract, so the clone is total).
+ * @param session - the session whose unit states are checkpointed.
+ * @returns one row per registered key; empty when no unit is registered.
+ */
+checkpoint(session: Session): ProjectionCheckpoint
+
+/**
+ * The stored seq a {@link restore} tail read over `checkpoint` must start
+ * at: one event BELOW the lowest usable watermark (a row is usable when
+ * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
+ * pulls the floor to `0` — that key must refold the full log). The
+ * one-below anchor is load-bearing: the tail then proves how far the
+ * stored log still extends, so {@link restore} can detect a log that
+ * shrank below a row's watermark (crash-repair truncation) instead of
+ * serving the stale row as current — an empty tail read from the anchor
+ * yields an end below every watermark and the restore rejects for a full
+ * re-read.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns the seq to hand the persistence `readFrom`, or `undefined`
+ *   when no unit is registered (no read needed — {@link restore} would
+ *   serve empty values regardless).
+ */
+restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined
+
+/**
+ * View a checkpoint's rows without any log read: for every registered
+ * unit whose row's `ver` matches, serve the schema-validated
+ * `view` of the stored state; mismatched or absent rows leave their key
+ * absent (a cold or listing consumer treats it as not-yet-available and a
+ * fuller read path refolds it). The zero-I/O rung of the read ladder —
+ * values are as stale as their rows, never wrong.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns whole values per key with a usable row; empty when none.
+ */
+viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
+
+/**
+ * Cold read: fold every registered unit over a stored log suffix, seeding
+ * each from its checkpoint row when usable — the one read recipe (cached
+ * state + forward tail replay + `view`) applied without a live `Session`.
+ * Call with the events returned by a persistence
+ * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+ * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
+ * so a shrunk log is detected here. A row is usable iff its
+ * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
+ * (`seq >= baseSeq - 1`), and it does not claim events past the
+ * supplied end (`seq <= endSeq`); an unusable row is discarded
+ * and its key refolds from `init` — which is only sound over the full
+ * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
+ * from seq 0, e.g. after a crash-repair truncation shrank the log below
+ * a row's watermark).
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @param events - the stored events with `seq >= baseSeq`, in seq order.
+ * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
+ * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
+ *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
+ *   refreshed checkpoint rows at that cut, ready for a durable write-back.
+ */
+restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
+```
+
+Types: [Session](session.md) · [SessionEvent](core.md)
+
+Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index eca4715ba9..728a6cf8db 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.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 docs/core-data-structures/session-query.md
-session-query.md: e7514dd6c3bc20a07395663bff40ce65e1363b78
-session-query.zh.md: 4c3dd4d435dbd8a20fbd4db5da1a7d649c2e6d0b
+#   pnpm run verify-translation-pairing --write docs/subsystems/session-query.md
+session-query.md: 54ae1eaf34a17d4979a621e4fc310780b425364e
+session-query.zh.md: b770514757c30aa5d87b25e5d280b1ce6710cd9c
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index e7514dd6c3..54ae1eaf34 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -354,3 +354,141 @@ type SessionQueryErrorCode =
   | 'SESSION_QUERY_STALE_CURSOR'
   | 'SESSION_QUERY_SOURCE_CONFLICT'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
+
+### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
+
+Unified live-preferred session query service.
+
+Exact reads, filters, and traces are backend-independent concrete behavior. A backend implements full-text observation, reconciliation, ranking, cursor generations, and query execution on the same `ctx.sessionQuery` service.
+
+```ts cordis-catalog
+/**
+ * Search the live-preferred logical corpus and group by session.
+ * @param request - query text, metadata filters, page size, and cursor.
+ * @param exec - optional cancellation control.
+ * @returns session hits ranked by their strongest matching event.
+ */
+abstract searchSessions( request: SessionSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionSearchHit>>
+
+/**
+ * Search events within one live-preferred logical session.
+ * @param request - target session, query text, filters, page size, and cursor.
+ * @param exec - optional cancellation control.
+ * @returns matching event hits and their target header from one indexed generation.
+ */
+abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionEventSearchPage>
+
+/**
+ * List the complete logical corpus using live-preferred records.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns deterministic newest-first cloned session records.
+ */
+listSessions(signal?: AbortSignal): Promise<SessionRecord[]>
+
+/**
+ * Read and replay-validate one complete logical session log without making it live.
+ * @param sessionId - live or persisted session id to read.
+ * @returns cloned header and complete raw event log from one observation.
+ * @throws when persistence, header compatibility, or replay validation fails.
+ */
+async readSession(sessionId: SessionId): Promise<SessionLogSnapshot>
+
+/**
+ * Filter the complete logical corpus with provider-independent predicates.
+ * @param filters - ANDed session metadata and availability clauses.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns matching cloned records in deterministic newest-first order.
+ */
+async filterSessions( filters: readonly SessionResultFilter[], signal?: AbortSignal, ): Promise<SessionRecord[]>
+
+/**
+ * Fold the latest log-backed title from one live-preferred logical session.
+ * @param sessionId - live or persisted session id to read.
+ * @param signal - optional cancellation for source resolution and title folding.
+ * @returns latest title snapshot, or `undefined` when the log has no title event.
+ */
+async readTitle( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Fold the latest title and return its source header from one corpus observation.
+ * @param sessionId - live or persisted session id to read.
+ * @param signal - optional cancellation for source resolution and title folding.
+ * @returns cloned source header and optional latest title snapshot.
+ */
+async readTitleSnapshot( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleObservation>
+
+/**
+ * Fold titles for unique sessions from one cancellable corpus observation.
+ *
+ * Results preserve first-occurrence input order. Operational failures stay
+ * isolated per session, while cancellation rejects the complete operation.
+ * @param sessionIds - live or persisted session ids to observe.
+ * @param signal - optional cancellation shared by all source reads.
+ * @returns one fulfilled or rejected result per unique requested id.
+ */
+async readTitleSnapshots( sessionIds: readonly SessionId[], signal?: AbortSignal, ): Promise<SessionTitleObservationResult[]>
+
+/**
+ * List lightweight raw-log event records for one logical session.
+ * @param sessionId - live-preferred session id to read.
+ * @returns event records in ascending seq order.
+ */
+async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>
+
+/**
+ * Scan first-party semantic event documents with provider-independent filters.
+ * @param sessionId - live-preferred session id to scan.
+ * @param filters - ANDed metadata and literal-text predicates.
+ * @returns matching semantic documents in ascending seq order.
+ */
+async filterEvents( sessionId: SessionId, filters: readonly SessionEventResultFilter[], ): Promise<SessionEventSearchDocument[]>
+
+/**
+ * Read one session's complete current model surface from one corpus observation.
+ * @param sessionId - live-preferred session id to read.
+ * @returns cloned header, current surface, and raw-log capture boundary.
+ * @throws when source resolution fails or the session surface is invalid.
+ */
+async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
+
+/**
+ * Trace known ancestry and descendants from one corpus observation.
+ * @param sessionId - logical session id to trace.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns a complete lineage or an explicit unresolved parent boundary.
+ * @throws when corpus resolution fails, the target is absent, or its known ancestry cycles.
+ */
+async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>
+
+/**
+ * Trace one event's direct positional and provenance relationships.
+ * @param request - target session id and event seq.
+ * @param signal - optional cancellation for persisted source resolution.
+ * @returns source header, direct links, and the target's positional replacement chain.
+ * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+ */
+async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>
+
+/**
+ * Read one full event plus a bounded raw-log context window.
+ * @param request - target session/seq and context sizes.
+ * @param signal - optional cancellation for persisted source resolution.
+ * @returns cloned target and neighboring events.
+ */
+async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>
+```
+
+Types: [SessionId](core.md) · [SessionTitleSnapshot](session-title.md)
+
+Source: [`packages/session-query/session-query/src/index.ts:81`](../../packages/session-query/session-query/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index 4c3dd4d435..b770514757 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -354,3 +354,141 @@ type SessionQueryErrorCode =
   | 'SESSION_QUERY_STALE_CURSOR'
   | 'SESSION_QUERY_SOURCE_CONFLICT'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
+
+### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
+
+Unified live-preferred session query service.
+
+Exact reads, filters, and traces are backend-independent concrete behavior. A backend implements full-text observation, reconciliation, ranking, cursor generations, and query execution on the same `ctx.sessionQuery` service.
+
+```ts cordis-catalog
+/**
+ * Search the live-preferred logical corpus and group by session.
+ * @param request - query text, metadata filters, page size, and cursor.
+ * @param exec - optional cancellation control.
+ * @returns session hits ranked by their strongest matching event.
+ */
+abstract searchSessions( request: SessionSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionSearchHit>>
+
+/**
+ * Search events within one live-preferred logical session.
+ * @param request - target session, query text, filters, page size, and cursor.
+ * @param exec - optional cancellation control.
+ * @returns matching event hits and their target header from one indexed generation.
+ */
+abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionEventSearchPage>
+
+/**
+ * List the complete logical corpus using live-preferred records.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns deterministic newest-first cloned session records.
+ */
+listSessions(signal?: AbortSignal): Promise<SessionRecord[]>
+
+/**
+ * Read and replay-validate one complete logical session log without making it live.
+ * @param sessionId - live or persisted session id to read.
+ * @returns cloned header and complete raw event log from one observation.
+ * @throws when persistence, header compatibility, or replay validation fails.
+ */
+async readSession(sessionId: SessionId): Promise<SessionLogSnapshot>
+
+/**
+ * Filter the complete logical corpus with provider-independent predicates.
+ * @param filters - ANDed session metadata and availability clauses.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns matching cloned records in deterministic newest-first order.
+ */
+async filterSessions( filters: readonly SessionResultFilter[], signal?: AbortSignal, ): Promise<SessionRecord[]>
+
+/**
+ * Fold the latest log-backed title from one live-preferred logical session.
+ * @param sessionId - live or persisted session id to read.
+ * @param signal - optional cancellation for source resolution and title folding.
+ * @returns latest title snapshot, or `undefined` when the log has no title event.
+ */
+async readTitle( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Fold the latest title and return its source header from one corpus observation.
+ * @param sessionId - live or persisted session id to read.
+ * @param signal - optional cancellation for source resolution and title folding.
+ * @returns cloned source header and optional latest title snapshot.
+ */
+async readTitleSnapshot( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleObservation>
+
+/**
+ * Fold titles for unique sessions from one cancellable corpus observation.
+ *
+ * Results preserve first-occurrence input order. Operational failures stay
+ * isolated per session, while cancellation rejects the complete operation.
+ * @param sessionIds - live or persisted session ids to observe.
+ * @param signal - optional cancellation shared by all source reads.
+ * @returns one fulfilled or rejected result per unique requested id.
+ */
+async readTitleSnapshots( sessionIds: readonly SessionId[], signal?: AbortSignal, ): Promise<SessionTitleObservationResult[]>
+
+/**
+ * List lightweight raw-log event records for one logical session.
+ * @param sessionId - live-preferred session id to read.
+ * @returns event records in ascending seq order.
+ */
+async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>
+
+/**
+ * Scan first-party semantic event documents with provider-independent filters.
+ * @param sessionId - live-preferred session id to scan.
+ * @param filters - ANDed metadata and literal-text predicates.
+ * @returns matching semantic documents in ascending seq order.
+ */
+async filterEvents( sessionId: SessionId, filters: readonly SessionEventResultFilter[], ): Promise<SessionEventSearchDocument[]>
+
+/**
+ * Read one session's complete current model surface from one corpus observation.
+ * @param sessionId - live-preferred session id to read.
+ * @returns cloned header, current surface, and raw-log capture boundary.
+ * @throws when source resolution fails or the session surface is invalid.
+ */
+async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
+
+/**
+ * Trace known ancestry and descendants from one corpus observation.
+ * @param sessionId - logical session id to trace.
+ * @param signal - optional cancellation for persistence listing.
+ * @returns a complete lineage or an explicit unresolved parent boundary.
+ * @throws when corpus resolution fails, the target is absent, or its known ancestry cycles.
+ */
+async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>
+
+/**
+ * Trace one event's direct positional and provenance relationships.
+ * @param request - target session id and event seq.
+ * @param signal - optional cancellation for persisted source resolution.
+ * @returns source header, direct links, and the target's positional replacement chain.
+ * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+ */
+async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>
+
+/**
+ * Read one full event plus a bounded raw-log context window.
+ * @param request - target session/seq and context sizes.
+ * @param signal - optional cancellation for persisted source resolution.
+ * @returns cloned target and neighboring events.
+ */
+async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>
+```
+
+Types: [SessionId](core.md) · [SessionTitleSnapshot](session-title.md)
+
+Source: [`packages/session-query/session-query/src/index.ts:81`](../../packages/session-query/session-query/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-reference.i18n.yaml b/docs/subsystems/session-reference.i18n.yaml
index f119c67913..980c1a1a2d 100644
--- a/docs/subsystems/session-reference.i18n.yaml
+++ b/docs/subsystems/session-reference.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 docs/subsystems/session-reference.md
-session-reference.md: 5375677f6a1748909743ca76d5191cb9e736a40a
-session-reference.zh.md: 3ff4a1719926bda0a9111482a7778a8c94553370
+session-reference.md: 60e29c56ea372e100009b94caedea5327308432a
+session-reference.zh.md: 3ae9264abc15848646e5397dfcbeff764c038918
diff --git a/docs/subsystems/session-reference.md b/docs/subsystems/session-reference.md
index 5375677f6a..60e29c56ea 100644
--- a/docs/subsystems/session-reference.md
+++ b/docs/subsystems/session-reference.md
@@ -65,3 +65,44 @@ type SessionReferenceErrorCode =
   | 'SESSION_REFERENCE_BUDGET_EXCEEDED'
   | 'SESSION_REFERENCE_CANCELLED'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionreferences--sessionreferenceservice"></a>
+
+### `ctx.sessionReferences` — `SessionReferenceService`
+
+Exact-read consumer that prepares immutable cross-session message context.
+
+```ts cordis-catalog
+/**
+ * List reference candidates, ranked by working-directory affinity.
+ * @param agent - target agent; self is excluded and its cwd drives ranking.
+ * @param query - optional case-insensitive session-id/cwd/title substring.
+ * @param limit - optional positive result cap.
+ * @param signal - optional cancellation boundary for host autocomplete teardown.
+ * @returns candidates labeled by latest title or, when absent, session id.
+ */
+async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
+
+/**
+ * Snapshot all references before enqueue and return one aggregated durable context.
+ * @param agent - target agent; references to it are rejected.
+ * @param content - already host-normalized readable message content.
+ * @param references - structured source sessions in mention order.
+ * @param signal - optional cancellation boundary for host request teardown.
+ * @returns detached content and optional referenced-session context.
+ */
+async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
+```
+
+Types: [Agent](core.md) · [ContentBlock](core.md)
+
+Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-reference.zh.md b/docs/subsystems/session-reference.zh.md
index 3ff4a17199..3ae9264abc 100644
--- a/docs/subsystems/session-reference.zh.md
+++ b/docs/subsystems/session-reference.zh.md
@@ -65,3 +65,44 @@ type SessionReferenceErrorCode =
   | 'SESSION_REFERENCE_BUDGET_EXCEEDED'
   | 'SESSION_REFERENCE_CANCELLED'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionreferences--sessionreferenceservice"></a>
+
+### `ctx.sessionReferences` — `SessionReferenceService`
+
+Exact-read consumer that prepares immutable cross-session message context.
+
+```ts cordis-catalog
+/**
+ * List reference candidates, ranked by working-directory affinity.
+ * @param agent - target agent; self is excluded and its cwd drives ranking.
+ * @param query - optional case-insensitive session-id/cwd/title substring.
+ * @param limit - optional positive result cap.
+ * @param signal - optional cancellation boundary for host autocomplete teardown.
+ * @returns candidates labeled by latest title or, when absent, session id.
+ */
+async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
+
+/**
+ * Snapshot all references before enqueue and return one aggregated durable context.
+ * @param agent - target agent; references to it are rejected.
+ * @param content - already host-normalized readable message content.
+ * @param references - structured source sessions in mention order.
+ * @param signal - optional cancellation boundary for host request teardown.
+ * @returns detached content and optional referenced-session context.
+ */
+async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
+```
+
+Types: [Agent](core.md) · [ContentBlock](core.md)
+
+Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-title.i18n.yaml b/docs/subsystems/session-title.i18n.yaml
index c85d4dfac1..8b58415234 100644
--- a/docs/subsystems/session-title.i18n.yaml
+++ b/docs/subsystems/session-title.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 docs/subsystems/session-title.md
-session-title.md: 7bced67f07df3f00471f02b766922cdc3e4fd29e
-session-title.zh.md: e8e501d3aafee49395da3d9a8efd4e91a724f09e
+session-title.md: 3a2df284f2af14def284e502f4e37daaf4d7a262
+session-title.zh.md: 3a74baa9005459b35b658df95bdd7b57256b3e2e
diff --git a/docs/subsystems/session-title.md b/docs/subsystems/session-title.md
index 7bced67f07..3a2df284f2 100644
--- a/docs/subsystems/session-title.md
+++ b/docs/subsystems/session-title.md
@@ -144,3 +144,61 @@ interface SessionTitleProvider {
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessiontitle--sessiontitleservice"></a>
+
+### `ctx.sessionTitle` — `SessionTitleService`
+
+Log-backed title fold plus asynchronous fallback generation.
+
+```ts cordis-catalog
+/**
+ * Read the latest folded title from one live or replayed session.
+ * @param session - session whose log is the title source of truth.
+ * @returns latest title snapshot, or `undefined` before eligible input.
+ */
+get(session: Session): SessionTitleSnapshot | undefined
+
+/**
+ * Accept an explicit user title. Appends a `session/title` event with the
+ * `user` source, which pins the title: in-flight automatic generation is
+ * superseded and later user messages schedule none (an explicit
+ * {@link SessionTitleService.refresh} remains the deliberate unpin).
+ * @param session - exact live session to rename.
+ * @param title - raw user input; normalized before acceptance.
+ * @returns the accepted title snapshot.
+ * @throws {SessionTitleInvalidError} when the title normalizes to empty.
+ * @throws {Error} when the session is not live or the service is disposed.
+ */
+rename(session: Session, title: string): SessionTitleSnapshot
+
+/**
+ * Explicitly retry the registered provider, or materialize the built-in
+ * fallback when no provider is registered.
+ * @param session - exact live session to refresh.
+ * @param signal - optional caller cancellation.
+ * @returns latest accepted title, or `undefined` when no eligible text exists.
+ */
+async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Register the sole optional title provider. Disposal aborts its pending and
+ * active work before another provider may register.
+ * @param provider - provider identity, cadence, and generation function.
+ * @returns exact Cordis effect disposer, which settles after active calls quiesce.
+ */
+register(provider: SessionTitleProvider): () => Promise<void>
+```
+
+Types: [Session](session.md)
+
+Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-title.zh.md b/docs/subsystems/session-title.zh.md
index e8e501d3aa..3a74baa900 100644
--- a/docs/subsystems/session-title.zh.md
+++ b/docs/subsystems/session-title.zh.md
@@ -144,3 +144,61 @@ interface SessionTitleProvider {
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessiontitle--sessiontitleservice"></a>
+
+### `ctx.sessionTitle` — `SessionTitleService`
+
+Log-backed title fold plus asynchronous fallback generation.
+
+```ts cordis-catalog
+/**
+ * Read the latest folded title from one live or replayed session.
+ * @param session - session whose log is the title source of truth.
+ * @returns latest title snapshot, or `undefined` before eligible input.
+ */
+get(session: Session): SessionTitleSnapshot | undefined
+
+/**
+ * Accept an explicit user title. Appends a `session/title` event with the
+ * `user` source, which pins the title: in-flight automatic generation is
+ * superseded and later user messages schedule none (an explicit
+ * {@link SessionTitleService.refresh} remains the deliberate unpin).
+ * @param session - exact live session to rename.
+ * @param title - raw user input; normalized before acceptance.
+ * @returns the accepted title snapshot.
+ * @throws {SessionTitleInvalidError} when the title normalizes to empty.
+ * @throws {Error} when the session is not live or the service is disposed.
+ */
+rename(session: Session, title: string): SessionTitleSnapshot
+
+/**
+ * Explicitly retry the registered provider, or materialize the built-in
+ * fallback when no provider is registered.
+ * @param session - exact live session to refresh.
+ * @param signal - optional caller cancellation.
+ * @returns latest accepted title, or `undefined` when no eligible text exists.
+ */
+async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Register the sole optional title provider. Disposal aborts its pending and
+ * active work before another provider may register.
+ * @param provider - provider identity, cadence, and generation function.
+ * @returns exact Cordis effect disposer, which settles after active calls quiesce.
+ */
+register(provider: SessionTitleProvider): () => Promise<void>
+```
+
+Types: [Session](session.md)
+
+Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index dd7135e8d3..a7e81056e5 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 5d54b03df8ec3345e8bf04702f242e3aacf8ec39
-session.zh.md: 5a867cfe302bf02994bfe5a5a704bed55222e8ea
+session.md: 28b3f959b47a24373860c2334f9273286d072c95
+session.zh.md: 5870265f55892231700b65ac6ed69d827a0ab1ec
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 5d54b03df8..28b3f959b4 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -343,7 +343,7 @@ interface SurfaceFoldResult {
 
 ## `Session` public API
 
-The body-stripped declaration keeps the plain class's detached factory, state accessors, append boundary, and history projections synchronized with source. Store operations remain in the generated [`ctx.sessions` service catalog](../cordis-catalog/services.md#ctxsessions--sessionstore).
+The body-stripped declaration keeps the plain class's detached factory, state accessors, append boundary, and history projections synchronized with source. Store operations remain in the generated [`ctx.sessions` section](#ctxsessions--sessionstore).
 
 ```ts public-api
 /**
@@ -586,3 +586,247 @@ The hook bridges' `hook/invoked` / `hook/result` provenance pairs (from `@deepse
 What a persistence backend relies on: the durable log persists every event losslessly, **including** `assistant/chunk` — `seq` must stay contiguous, so chunks cannot be filtered out of the canonical log. A backend may choose its own storage encoding for an event batch as long as `load` returns the exact appended events (the JSONL backend's default packed chunk rows are such an encoding — see [persistence.md](persistence.md)). All `event.data` must be JSON-serializable; `Session.append` enforces this at the source (throwing on non-serializable data), so a bad event never enters the log and `session.events` always equals what a backend can persist. Adding an event type that carries non-serializable data, corrupts core execution nesting, or violates its owner's declared relation is a breaking change to the on-disk format.
 
 The backends that consume this contract are on [persistence.md](persistence.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessions--sessionstore"></a>
+
+### `ctx.sessions` — `SessionStore`
+
+In-memory session store (`ctx.sessions`).
+
+Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
+
+```ts cordis-catalog
+/**
+ * Create a session owned by the calling fiber: disposing that fiber stops
+ * event notification and removes the session from the store. `options.seed`
+ * populates the session with a copy of those events (replay/fork);
+ * `options.meta` attaches creation metadata (validated absolute `cwd`, seed
+ * and parent lineage, and delegation depth) as the immutable
+ * {@link SessionHeader} (the store fills `version`/`id`/`createdAt`).
+ *
+ * For an agent whose session must be torn down IN ORDER with its loop (so the
+ * loop's final events are published before the store attachment ends), do NOT use this
+ * — fold the session lifecycle into the agent's own effect via
+ * {@link prepare} + {@link enter} + {@link announce} (see
+ * `dsh-agent-loop`'s creation transaction).
+ *
+ * @param id - the session id; omitted, the store mints `session-<n>`.
+ * @param options - seed events and/or creation metadata for the header.
+ * @returns the live session, already entered and announced.
+ * @throws if a session with `id` already exists, metadata is not a plain
+ *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+ *   non-absolute path (storage backends key directories off it).
+ */
+create(id?: SessionId, options?: CreateSessionOptions): Session
+
+/**
+ * Build a session WITHOUT entering it into the store — validate the id/cwd and
+ * construct the {@link Session} (with its immutable {@link SessionHeader}).
+ * Pairs with {@link enter} + {@link announce}: a caller that owns a composite
+ * `ctx.effect` (the agent factory) folds the session lifecycle into that ONE
+ * effect so a fiber unload tears the session + agent down as a single ORDERED
+ * chain rather than as racing sibling effects — which would remove the publication hooks
+ * before the driver's closing events commit, dropping them.
+ *
+ * @param id - the session id; omitted, the store mints `session-<n>`.
+ * @param options - seed events and/or creation metadata for the header. With
+ *   `seedSource: 'persistence'`, metadata and events must be fresh detached
+ *   graphs whose ownership transfers to this call: they are validated and
+ *   frozen in place through {@link Session.fromRestore}, so the caller must
+ *   retain no mutable aliases.
+ * @returns the constructed session, NOT yet in the store.
+ * @throws if a session with `id` already exists, metadata is not a plain
+ *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+ *   non-absolute path.
+ */
+prepare(id?: SessionId, options?: PrepareSessionOptions): Session
+
+/**
+ * Enter a {@link prepare}d session into the store: install the module-private
+ * append publication hooks and add it to the store. Returns the DETACH
+ * disposer (hooks + store removal). Does NOT emit `session/created` —
+ * the caller yields this disposer inside its effect and THEN calls
+ * {@link announce}, so a throwing `session/created` listener rolls the attach
+ * back instead of leaking it.
+ *
+ * Re-checks the id for a duplicate: `prepare` and `enter` are public
+ * cross-package primitives and a caller may interleave arbitrary work (or
+ * another create) between them, so a stale prepared session must NOT overwrite
+ * a live store entry of the same id — its detach disposer would later delete
+ * the REAL session. The {@link create} convenience and the agent factory call
+ * the two back-to-back so they never trip this, but the public seam cannot
+ * assume that.
+ *
+ * @param session - a {@link prepare}d session not yet in the store.
+ * @returns the detach disposer (publication hooks + store removal). When called from
+ *   a synchronous `session/created` listener, removal and disposal wait until
+ *   that creation dispatch unwinds.
+ * @throws if a session with this id is already in the store.
+ */
+enter(session: Session): () => void
+
+/** Emit `session/created` exactly once for an {@link enter}ed session (with
+ * the carrier {@link enter} captured). Separate from {@link enter} so the
+ * caller can yield the detach disposer first (rollback safety — see
+ * {@link enter}).
+ * @param session - the entered session to announce to listeners.
+ * @throws if the session is not live or its announcement already began,
+ *   including a reentrant call from a creation listener. */
+announce(session: Session): void
+
+/**
+ * Dispatch the awaited `session/flush` durability checkpoint for `session`,
+ * with the carrier captured at {@link enter}. THE flush entry point: the
+ * store owns the carrier, so callers (the checkpoint policy's per-request
+ * barrier, goal-session's idle checkpoint, teardown drains, and consumers
+ * that flush themselves before reading storage) must come through here
+ * rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner,
+ * one spelling, and the scoped-dispatch invariant can pin it.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @returns whether at least one durability listener participated, after every
+ *   listener has settled successfully.
+ * @throws the first registered listener failure after every listener settles.
+ */
+async flush(session: Session): Promise<boolean>
+
+/**
+ * Look up a live session.
+ * @param id - the session id to look up.
+ * @returns the session, or undefined when no live session has that id.
+ */
+get(id: SessionId): Session | undefined
+
+/**
+ * All live sessions, in creation order.
+ * @returns a fresh array; mutating it does not affect the store.
+ */
+list(): Session[]
+
+/**
+ * Create a live child session from a stable prefix of a live source.
+ * `boundary` is an inclusive source event seq; omitted means the source's
+ * current last event. The selected slice may end with a between-turn event
+ * but must not end inside an open turn.
+ *
+ * @param source - Live source session object or id.
+ * @param boundary - Inclusive source event seq to fork through; omitted means
+ *   the source's current last event, and omitted on an empty source forks an
+ *   empty child.
+ * @param childSessionId - Optional child session id; omitted delegates to
+ *   `SessionStore`'s id policy.
+ * @returns The created live child session.
+ */
+fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
+```
+
+Types: [CreateSessionOptions](persistence.md) · [PrepareSessionOptions](persistence.md) · [SessionId](core.md)
+
+Source: [`packages/core/session/src/index.ts:807`](../../packages/core/session/src/index.ts)
+
+<a id="session-events"></a>
+
+### `session/*` events
+
+<a id="sessioncreated--emit"></a>
+
+#### `session/created` — emit
+
+Creation announcement during session publication. A synchronous throw vetoes and rolls back with a paired disposal; detach requested during dispatch is deferred. A returned-promise rejection is logged but cannot retroactively veto this synchronous boundary. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only sessions entered through that agent's context.
+
+```ts cordis-catalog
+/**
+ * Creation announcement during session publication. A synchronous throw vetoes and rolls
+ * back with a paired disposal; detach requested during dispatch is deferred.
+ * A returned-promise rejection is logged but cannot retroactively veto this
+ * synchronous boundary.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only sessions entered through that agent's context.
+ * @param session - the session just entered and announced.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/created'(this: Scoped<Session>, session: Session): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:74`](../../packages/core/session/src/index.ts)
+
+<a id="sessiondisposed--emit"></a>
+
+#### `session/disposed` — emit
+
+Emitted once when an announced session leaves the store, including publication rollback, but never for an entry whose creation announcement did not begin. Listener failures are logged and contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+
+```ts cordis-catalog
+/**
+ * Emitted once when an announced session leaves the store, including
+ * publication rollback, but never for an entry whose creation announcement
+ * did not begin. Listener failures are logged and contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+ * @param session - the session that is no longer live in the store.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/disposed'(this: Scoped<Session>, session: Session): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:84`](../../packages/core/session/src/index.ts)
+
+<a id="sessionevent--emit"></a>
+
+#### `session/event` — emit
+
+Post-commit, fire-and-forget append feed. The listener snapshot resolves before the log push, but callbacks run after it; observer failures are logged and contained without making the committed append fail. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only events from sessions entered through that agent's context.
+
+```ts cordis-catalog
+/**
+ * Post-commit, fire-and-forget append feed. The listener snapshot resolves
+ * before the log push, but callbacks run after it; observer failures are
+ * logged and contained without making the committed append fail.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only events from sessions entered through that agent's context.
+ * @param session - the session whose log grew.
+ * @param event - the appended event, exactly as recorded.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
+```
+
+Types: [Scoped](scope.md) · [SessionEvent](core.md)
+
+Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
+
+<a id="sessionflush--parallel"></a>
+
+#### `session/flush` — parallel
+
+Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+
+```ts cordis-catalog
+/**
+ * Awaited parallel durability checkpoint: every listener runs and the
+ * caller awaits all of them, with no waterfall veto. Scope-filtered dispatch
+ * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @dshScopeScan unsupported
+ * @mode parallel
+ */
+'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:105`](../../packages/core/session/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 5a867cfe30..5870265f55 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -345,7 +345,7 @@ interface SurfaceFoldResult {
 
 ## `Session` 公共 API
 
-去除方法体的声明与源码中的普通类保持同步，覆盖其脱离态工厂、状态访问器、追加边界和历史投影。存储操作仍由生成的 [`ctx.sessions` 服务目录](../cordis-catalog/services.md#ctxsessions--sessionstore)记录。
+去除方法体的声明与源码中的普通类保持同步，覆盖其脱离态工厂、状态访问器、追加边界和历史投影。存储操作仍由生成的 [`ctx.sessions` 小节](#ctxsessions--sessionstore)记录。
 
 ```ts public-api
 /**
@@ -590,3 +590,247 @@ interface TurnEndReasonMap {
 持久化后端依赖的契约如下：持久日志无损保存每个事件，**包括** `assistant/chunk`；`seq` 必须连续，因此不能从规范日志中过滤分片。后端可以为事件批次选择自己的存储编码，只要 `load` 返回与追加时完全一致的事件即可（JSONL 后端默认启用的打包分片行就是此类编码；见 [persistence.md](persistence.md)）。所有 `event.data` 都必须可序列化为 JSON；`Session.append` 会从源头强制这一要求（遇到不可序列化数据时抛出），因此错误事件绝不会进入日志，`session.events` 始终与后端可持久化的内容一致。新增会携带不可序列化数据、破坏核心执行嵌套或违反事件所有方声明关系的事件类型，都会构成磁盘格式的破坏性变更。
 
 消费此契约的后端见 [persistence.md](persistence.md)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessions--sessionstore"></a>
+
+### `ctx.sessions` — `SessionStore`
+
+In-memory session store (`ctx.sessions`).
+
+Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
+
+```ts cordis-catalog
+/**
+ * Create a session owned by the calling fiber: disposing that fiber stops
+ * event notification and removes the session from the store. `options.seed`
+ * populates the session with a copy of those events (replay/fork);
+ * `options.meta` attaches creation metadata (validated absolute `cwd`, seed
+ * and parent lineage, and delegation depth) as the immutable
+ * {@link SessionHeader} (the store fills `version`/`id`/`createdAt`).
+ *
+ * For an agent whose session must be torn down IN ORDER with its loop (so the
+ * loop's final events are published before the store attachment ends), do NOT use this
+ * — fold the session lifecycle into the agent's own effect via
+ * {@link prepare} + {@link enter} + {@link announce} (see
+ * `dsh-agent-loop`'s creation transaction).
+ *
+ * @param id - the session id; omitted, the store mints `session-<n>`.
+ * @param options - seed events and/or creation metadata for the header.
+ * @returns the live session, already entered and announced.
+ * @throws if a session with `id` already exists, metadata is not a plain
+ *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+ *   non-absolute path (storage backends key directories off it).
+ */
+create(id?: SessionId, options?: CreateSessionOptions): Session
+
+/**
+ * Build a session WITHOUT entering it into the store — validate the id/cwd and
+ * construct the {@link Session} (with its immutable {@link SessionHeader}).
+ * Pairs with {@link enter} + {@link announce}: a caller that owns a composite
+ * `ctx.effect` (the agent factory) folds the session lifecycle into that ONE
+ * effect so a fiber unload tears the session + agent down as a single ORDERED
+ * chain rather than as racing sibling effects — which would remove the publication hooks
+ * before the driver's closing events commit, dropping them.
+ *
+ * @param id - the session id; omitted, the store mints `session-<n>`.
+ * @param options - seed events and/or creation metadata for the header. With
+ *   `seedSource: 'persistence'`, metadata and events must be fresh detached
+ *   graphs whose ownership transfers to this call: they are validated and
+ *   frozen in place through {@link Session.fromRestore}, so the caller must
+ *   retain no mutable aliases.
+ * @returns the constructed session, NOT yet in the store.
+ * @throws if a session with `id` already exists, metadata is not a plain
+ *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+ *   non-absolute path.
+ */
+prepare(id?: SessionId, options?: PrepareSessionOptions): Session
+
+/**
+ * Enter a {@link prepare}d session into the store: install the module-private
+ * append publication hooks and add it to the store. Returns the DETACH
+ * disposer (hooks + store removal). Does NOT emit `session/created` —
+ * the caller yields this disposer inside its effect and THEN calls
+ * {@link announce}, so a throwing `session/created` listener rolls the attach
+ * back instead of leaking it.
+ *
+ * Re-checks the id for a duplicate: `prepare` and `enter` are public
+ * cross-package primitives and a caller may interleave arbitrary work (or
+ * another create) between them, so a stale prepared session must NOT overwrite
+ * a live store entry of the same id — its detach disposer would later delete
+ * the REAL session. The {@link create} convenience and the agent factory call
+ * the two back-to-back so they never trip this, but the public seam cannot
+ * assume that.
+ *
+ * @param session - a {@link prepare}d session not yet in the store.
+ * @returns the detach disposer (publication hooks + store removal). When called from
+ *   a synchronous `session/created` listener, removal and disposal wait until
+ *   that creation dispatch unwinds.
+ * @throws if a session with this id is already in the store.
+ */
+enter(session: Session): () => void
+
+/** Emit `session/created` exactly once for an {@link enter}ed session (with
+ * the carrier {@link enter} captured). Separate from {@link enter} so the
+ * caller can yield the detach disposer first (rollback safety — see
+ * {@link enter}).
+ * @param session - the entered session to announce to listeners.
+ * @throws if the session is not live or its announcement already began,
+ *   including a reentrant call from a creation listener. */
+announce(session: Session): void
+
+/**
+ * Dispatch the awaited `session/flush` durability checkpoint for `session`,
+ * with the carrier captured at {@link enter}. THE flush entry point: the
+ * store owns the carrier, so callers (the checkpoint policy's per-request
+ * barrier, goal-session's idle checkpoint, teardown drains, and consumers
+ * that flush themselves before reading storage) must come through here
+ * rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner,
+ * one spelling, and the scoped-dispatch invariant can pin it.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @returns whether at least one durability listener participated, after every
+ *   listener has settled successfully.
+ * @throws the first registered listener failure after every listener settles.
+ */
+async flush(session: Session): Promise<boolean>
+
+/**
+ * Look up a live session.
+ * @param id - the session id to look up.
+ * @returns the session, or undefined when no live session has that id.
+ */
+get(id: SessionId): Session | undefined
+
+/**
+ * All live sessions, in creation order.
+ * @returns a fresh array; mutating it does not affect the store.
+ */
+list(): Session[]
+
+/**
+ * Create a live child session from a stable prefix of a live source.
+ * `boundary` is an inclusive source event seq; omitted means the source's
+ * current last event. The selected slice may end with a between-turn event
+ * but must not end inside an open turn.
+ *
+ * @param source - Live source session object or id.
+ * @param boundary - Inclusive source event seq to fork through; omitted means
+ *   the source's current last event, and omitted on an empty source forks an
+ *   empty child.
+ * @param childSessionId - Optional child session id; omitted delegates to
+ *   `SessionStore`'s id policy.
+ * @returns The created live child session.
+ */
+fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
+```
+
+Types: [CreateSessionOptions](persistence.md) · [PrepareSessionOptions](persistence.md) · [SessionId](core.md)
+
+Source: [`packages/core/session/src/index.ts:807`](../../packages/core/session/src/index.ts)
+
+<a id="session-events"></a>
+
+### `session/*` events
+
+<a id="sessioncreated--emit"></a>
+
+#### `session/created` — emit
+
+Creation announcement during session publication. A synchronous throw vetoes and rolls back with a paired disposal; detach requested during dispatch is deferred. A returned-promise rejection is logged but cannot retroactively veto this synchronous boundary. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only sessions entered through that agent's context.
+
+```ts cordis-catalog
+/**
+ * Creation announcement during session publication. A synchronous throw vetoes and rolls
+ * back with a paired disposal; detach requested during dispatch is deferred.
+ * A returned-promise rejection is logged but cannot retroactively veto this
+ * synchronous boundary.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only sessions entered through that agent's context.
+ * @param session - the session just entered and announced.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/created'(this: Scoped<Session>, session: Session): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:74`](../../packages/core/session/src/index.ts)
+
+<a id="sessiondisposed--emit"></a>
+
+#### `session/disposed` — emit
+
+Emitted once when an announced session leaves the store, including publication rollback, but never for an entry whose creation announcement did not begin. Listener failures are logged and contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+
+```ts cordis-catalog
+/**
+ * Emitted once when an announced session leaves the store, including
+ * publication rollback, but never for an entry whose creation announcement
+ * did not begin. Listener failures are logged and contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+ * @param session - the session that is no longer live in the store.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/disposed'(this: Scoped<Session>, session: Session): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:84`](../../packages/core/session/src/index.ts)
+
+<a id="sessionevent--emit"></a>
+
+#### `session/event` — emit
+
+Post-commit, fire-and-forget append feed. The listener snapshot resolves before the log push, but callbacks run after it; observer failures are logged and contained without making the committed append fail. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only events from sessions entered through that agent's context.
+
+```ts cordis-catalog
+/**
+ * Post-commit, fire-and-forget append feed. The listener snapshot resolves
+ * before the log push, but callbacks run after it; observer failures are
+ * logged and contained without making the committed append fail.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only events from sessions entered through that agent's context.
+ * @param session - the session whose log grew.
+ * @param event - the appended event, exactly as recorded.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
+```
+
+Types: [Scoped](scope.md) · [SessionEvent](core.md)
+
+Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
+
+<a id="sessionflush--parallel"></a>
+
+#### `session/flush` — parallel
+
+Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+
+```ts cordis-catalog
+/**
+ * Awaited parallel durability checkpoint: every listener runs and the
+ * caller awaits all of them, with no waterfall veto. Scope-filtered dispatch
+ * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @dshScopeScan unsupported
+ * @mode parallel
+ */
+'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/session/src/index.ts:105`](../../packages/core/session/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
index f4518f4414..5c40419366 100644
--- a/docs/subsystems/settings.i18n.yaml
+++ b/docs/subsystems/settings.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 docs/subsystems/settings.md
-settings.md: bd01c1d28407af9cab26f624a054a010e25a3ddd
-settings.zh.md: 1cb7f8b507f29f2b6876fd48b4c37284df235e53
+settings.md: 9256bf9436d2e77093fc8c6a3728b62fc4e8d67f
+settings.zh.md: f6d662ebaf35eeb9d046353ea1087b0eb86e7068
diff --git a/docs/subsystems/settings.md b/docs/subsystems/settings.md
index bd01c1d284..9256bf9436 100644
--- a/docs/subsystems/settings.md
+++ b/docs/subsystems/settings.md
@@ -160,3 +160,151 @@ Every committed change — an in-process write or an externally observed provide
 /** Origin of one committed settings change. */
 type SettingsUpdateSource = 'update' | 'provider'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsettings--settings-abstract-seam"></a>
+
+### `ctx.settings` — `Settings` (abstract seam)
+
+Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
+
+```ts cordis-catalog
+/**
+ * Prepare the provider's user-editable document for a native editor. File
+ * providers may materialize an absent document before returning its path;
+ * non-file providers return undefined.
+ * @returns the absolute local document path, or undefined for non-file storage.
+ */
+prepareDocument(): Promise<string | undefined>
+
+/**
+ * Register a namespace schema and receive its owner scope. The registration
+ * is an effect on the calling plugin's fiber: disposing that fiber removes
+ * the namespace and its observers. An invalid stored section fails the
+ * registration itself — the earliest point where the schema can judge it.
+ * @param ns - unique namespace; duplicate registration fails loud.
+ * @param schema - schemastery schema resolving this namespace's value.
+ * @param options - composition `base` layer and effect timing.
+ * @returns the owner scope for reads, observation, and updates.
+ */
+register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>
+
+/**
+ * Describe every registered namespace for configuration surfaces, including
+ * the composition `base` and raw user layers so a form can mark which fields
+ * the user overrode (presence in `user`) and what a reset returns to.
+ * @param options - redaction switch; wire surfaces must redact.
+ * @returns one descriptor per registered namespace, in registration order.
+ */
+describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
+
+/**
+ * Read one registered namespace's resolved value.
+ * @param ns - the namespace to read.
+ * @returns the resolved value, or `undefined` while unregistered.
+ */
+get(ns: SettingsNamespace): unknown
+
+/**
+ * Merge a patch into one registered namespace's user layer, validate the
+ * resolved candidate, persist through the provider, then commit and emit.
+ * A validation failure rejects before anything is persisted. Writes to one
+ * namespace are serialized: concurrent updates apply in call order, each
+ * merging over the previous write's committed section.
+ * @param ns - the registered namespace to update.
+ * @param patch - plain-object patch over the user section.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>
+
+/**
+ * Replace one registered namespace's user section wholesale, validate,
+ * persist, then commit and emit. Keys absent from `section` fall back to the
+ * composition `base` and schema defaults — this is the removal/reset path a
+ * merge-only patch cannot express (`replace({})` re-inherits everything).
+ * @param ns - the registered namespace to replace.
+ * @param section - the complete next user section.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>
+
+/**
+ * Apply path-addressed edits to one registered namespace's user section,
+ * validate, persist, then commit and emit. The ops are applied to the
+ * section as it stands when the write reaches the front of the queue, so a
+ * caller never has to restate fields it did not touch — and, crucially,
+ * cannot delete fields it never saw. This is the write path for any caller
+ * holding a redacted view; `replace` remains the wholesale reset.
+ * @param ns - the registered namespace to edit.
+ * @param ops - ordered path edits; later ops observe earlier ones.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
+```
+
+Source: [`packages/settings/settings/src/index.ts:387`](../../packages/settings/settings/src/index.ts)
+
+<a id="settings-events"></a>
+
+### `settings/*` events
+
+<a id="settingsdocument-updated--emit"></a>
+
+#### `settings/document-updated` — emit
+
+One registered namespace's RAW user section changed, whether or not the resolved value did. `settings/updated` is the consumer-facing event and stays deep-equal-gated; this one exists for configuration surfaces, which must learn that a field went from inherited to overridden (same resolved value, different meaning) and that their held revision is stale. Listener containment matches `settings/updated`.
+
+```ts cordis-catalog
+/**
+ * One registered namespace's RAW user section changed, whether or not the
+ * resolved value did. `settings/updated` is the consumer-facing event and
+ * stays deep-equal-gated; this one exists for configuration surfaces,
+ * which must learn that a field went from inherited to overridden (same
+ * resolved value, different meaning) and that their held revision is
+ * stale. Listener containment matches `settings/updated`.
+ * @param ns - the namespace whose stored section changed.
+ * @param revision - the namespace's new revision.
+ * @mode emit
+ */
+'settings/document-updated'(ns: SettingsNamespace, revision: number): void
+```
+
+Source: [`packages/settings/settings/src/index.ts:170`](../../packages/settings/settings/src/index.ts)
+
+<a id="settingsupdated--emit"></a>
+
+#### `settings/updated` — emit
+
+Committed change to one registered namespace's resolved value. Emitted after the provider persisted (for `update`) or published (`provider`) the change; never emitted when the resolved value is deep-equal. Listener failures are contained and logged — a sync throw and an async rejection alike — except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
+
+```ts cordis-catalog
+/**
+ * Committed change to one registered namespace's resolved value. Emitted
+ * after the provider persisted (for `update`) or published (`provider`)
+ * the change; never emitted when the resolved value is deep-equal.
+ * Listener failures are contained and logged — a sync throw and an async
+ * rejection alike — except `INVARIANT`-coded failures, which rethrow
+ * after every listener ran; that rethrow reaches the emitter only from
+ * synchronous listeners, so invariant checks on this event must not be
+ * async functions.
+ * @param ns - the namespace whose resolved value changed.
+ * @param next - the new resolved value.
+ * @param prev - the previous resolved value.
+ * @param source - whether the change entered through `update()` or the provider.
+ * @mode emit
+ */
+'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void
+```
+
+Source: [`packages/settings/settings/src/index.ts:157`](../../packages/settings/settings/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/settings.zh.md b/docs/subsystems/settings.zh.md
index 1cb7f8b507..f6d662ebaf 100644
--- a/docs/subsystems/settings.zh.md
+++ b/docs/subsystems/settings.zh.md
@@ -160,3 +160,151 @@ interface SettingsDescribeOptions {
 /** Origin of one committed settings change. */
 type SettingsUpdateSource = 'update' | 'provider'
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsettings--settings-abstract-seam"></a>
+
+### `ctx.settings` — `Settings` (abstract seam)
+
+Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
+
+```ts cordis-catalog
+/**
+ * Prepare the provider's user-editable document for a native editor. File
+ * providers may materialize an absent document before returning its path;
+ * non-file providers return undefined.
+ * @returns the absolute local document path, or undefined for non-file storage.
+ */
+prepareDocument(): Promise<string | undefined>
+
+/**
+ * Register a namespace schema and receive its owner scope. The registration
+ * is an effect on the calling plugin's fiber: disposing that fiber removes
+ * the namespace and its observers. An invalid stored section fails the
+ * registration itself — the earliest point where the schema can judge it.
+ * @param ns - unique namespace; duplicate registration fails loud.
+ * @param schema - schemastery schema resolving this namespace's value.
+ * @param options - composition `base` layer and effect timing.
+ * @returns the owner scope for reads, observation, and updates.
+ */
+register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>
+
+/**
+ * Describe every registered namespace for configuration surfaces, including
+ * the composition `base` and raw user layers so a form can mark which fields
+ * the user overrode (presence in `user`) and what a reset returns to.
+ * @param options - redaction switch; wire surfaces must redact.
+ * @returns one descriptor per registered namespace, in registration order.
+ */
+describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
+
+/**
+ * Read one registered namespace's resolved value.
+ * @param ns - the namespace to read.
+ * @returns the resolved value, or `undefined` while unregistered.
+ */
+get(ns: SettingsNamespace): unknown
+
+/**
+ * Merge a patch into one registered namespace's user layer, validate the
+ * resolved candidate, persist through the provider, then commit and emit.
+ * A validation failure rejects before anything is persisted. Writes to one
+ * namespace are serialized: concurrent updates apply in call order, each
+ * merging over the previous write's committed section.
+ * @param ns - the registered namespace to update.
+ * @param patch - plain-object patch over the user section.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>
+
+/**
+ * Replace one registered namespace's user section wholesale, validate,
+ * persist, then commit and emit. Keys absent from `section` fall back to the
+ * composition `base` and schema defaults — this is the removal/reset path a
+ * merge-only patch cannot express (`replace({})` re-inherits everything).
+ * @param ns - the registered namespace to replace.
+ * @param section - the complete next user section.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>
+
+/**
+ * Apply path-addressed edits to one registered namespace's user section,
+ * validate, persist, then commit and emit. The ops are applied to the
+ * section as it stands when the write reaches the front of the queue, so a
+ * caller never has to restate fields it did not touch — and, crucially,
+ * cannot delete fields it never saw. This is the write path for any caller
+ * holding a redacted view; `replace` remains the wholesale reset.
+ * @param ns - the registered namespace to edit.
+ * @param ops - ordered path edits; later ops observe earlier ones.
+ * @param expectedRevision - the descriptor `revision` the caller read; a
+ *   namespace that moved past it rejects with {@link SettingsConflictError}.
+ */
+async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
+```
+
+Source: [`packages/settings/settings/src/index.ts:387`](../../packages/settings/settings/src/index.ts)
+
+<a id="settings-events"></a>
+
+### `settings/*` events
+
+<a id="settingsdocument-updated--emit"></a>
+
+#### `settings/document-updated` — emit
+
+One registered namespace's RAW user section changed, whether or not the resolved value did. `settings/updated` is the consumer-facing event and stays deep-equal-gated; this one exists for configuration surfaces, which must learn that a field went from inherited to overridden (same resolved value, different meaning) and that their held revision is stale. Listener containment matches `settings/updated`.
+
+```ts cordis-catalog
+/**
+ * One registered namespace's RAW user section changed, whether or not the
+ * resolved value did. `settings/updated` is the consumer-facing event and
+ * stays deep-equal-gated; this one exists for configuration surfaces,
+ * which must learn that a field went from inherited to overridden (same
+ * resolved value, different meaning) and that their held revision is
+ * stale. Listener containment matches `settings/updated`.
+ * @param ns - the namespace whose stored section changed.
+ * @param revision - the namespace's new revision.
+ * @mode emit
+ */
+'settings/document-updated'(ns: SettingsNamespace, revision: number): void
+```
+
+Source: [`packages/settings/settings/src/index.ts:170`](../../packages/settings/settings/src/index.ts)
+
+<a id="settingsupdated--emit"></a>
+
+#### `settings/updated` — emit
+
+Committed change to one registered namespace's resolved value. Emitted after the provider persisted (for `update`) or published (`provider`) the change; never emitted when the resolved value is deep-equal. Listener failures are contained and logged — a sync throw and an async rejection alike — except `INVARIANT`-coded failures, which rethrow after every listener ran; that rethrow reaches the emitter only from synchronous listeners, so invariant checks on this event must not be async functions.
+
+```ts cordis-catalog
+/**
+ * Committed change to one registered namespace's resolved value. Emitted
+ * after the provider persisted (for `update`) or published (`provider`)
+ * the change; never emitted when the resolved value is deep-equal.
+ * Listener failures are contained and logged — a sync throw and an async
+ * rejection alike — except `INVARIANT`-coded failures, which rethrow
+ * after every listener ran; that rethrow reaches the emitter only from
+ * synchronous listeners, so invariant checks on this event must not be
+ * async functions.
+ * @param ns - the namespace whose resolved value changed.
+ * @param next - the new resolved value.
+ * @param prev - the previous resolved value.
+ * @param source - whether the change entered through `update()` or the provider.
+ * @mode emit
+ */
+'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void
+```
+
+Source: [`packages/settings/settings/src/index.ts:157`](../../packages/settings/settings/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
index 6ab9693cca..84628f50b7 100644
--- a/docs/subsystems/skills.i18n.yaml
+++ b/docs/subsystems/skills.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 docs/subsystems/skills.md
-skills.md: d862cbc07135680c2377b4c8c82c80d055344221
-skills.zh.md: 3f8c034ec2aa24b4acdbbc1e2ac27717c21649d5
+skills.md: 78d510fafca0017b9528a215270172a74e9b0de1
+skills.zh.md: e88c9f1ba190eb1e90966d35c7dcc2eb86ecd6cc
diff --git a/docs/subsystems/skills.md b/docs/subsystems/skills.md
index d862cbc071..78d510fafc 100644
--- a/docs/subsystems/skills.md
+++ b/docs/subsystems/skills.md
@@ -218,3 +218,93 @@ interface Config {
 Before each later model step, the consumer applies exact tool visibility and digests the exact rendered entries between the `<available_skills>` tags from a complete snapshot. It derives the comparison baseline from the same entries in the newest recognizable visible catalog message sourced by the plugin. A changed digest appends a durable full replacement through `agent.inject()`; deleting every skill appends an explicit empty replacement. Incomplete snapshots preserve the last-good model view. If compaction hides every historical catalog message, the next complete snapshot re-establishes the current catalog; an empty view with no prior catalog emits nothing. These catalog messages are session history, not World State.
 
 The model-facing `skill({ name })` tool validates the kebab-case name, finds the summary in the invocation-neutral catalog, rejects it before loading unless `isModelInvocable` permits access, then rereads the complete definition for the calling agent cwd and rechecks the policy before returning content. It reports an unresolved skill as unknown or no longer available and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` resolves explicitly referenced scripts, references, and assets only as needed; the loaded result does not enumerate a skill directory. Body-only edits therefore change later tool calls without producing catalog messages or rewriting earlier tool results.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxskills--skillservice"></a>
+
+### `ctx.skills` — `SkillService`
+
+Registry of skill providers. It merges provider catalogs with stable first-wins duplicate handling, exposes sorted invocation-neutral summaries, and loads full skill bodies on demand.
+
+```ts cordis-catalog
+/**
+ * Register a borrowed same-process provider synchronously during plugin apply. Duplicate and
+ * reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters
+ * the provider and invalidates catalog caches.
+ * @param create - synchronous factory receiving this registration's lifecycle and invalidation control.
+ * @returns the exact Cordis effect disposer that unregisters this provider;
+ *   composite effects may yield it directly to preserve teardown ordering.
+ */
+registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void
+
+/**
+ * Register a borrowed readonly runtime skill. Project entries outrank runtime entries, which
+ * outrank user entries. Same-name runtime entries are first-wins; a duplicate logs a warning and
+ * receives a no-op disposer so it cannot remove the winner.
+ * @param skill - the skill definition input; omitted invocation and provider fields receive defaults.
+ * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
+ */
+register(skill: SkillRegistration): () => void
+
+/**
+ * List invocation-neutral skill summaries for a workspace. Consumers apply
+ * model or user invocation policy at their operational boundary. Lookup
+ * options and provider candidates are readonly same-process values borrowed
+ * throughout discovery.
+ * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+ * @returns all sorted winning summaries.
+ */
+async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>
+
+/**
+ * Observe the current invocation-neutral catalog and whether discovery completed within a stable revision.
+ * Incomplete observations are never cached, allowing consumers to retain last-good state and
+ * retry on their next request boundary.
+ * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+ * @returns sorted summaries plus discovery-completeness state.
+ */
+async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
+
+/**
+ * Load and validate the winning candidate, passing its opaque discovery locator back to the
+ * provider. Cancellation is rechecked after selection, including cache hits, and raced against
+ * loading so an uncooperative provider cannot hang the caller.
+ * @param name - kebab-case skill name.
+ * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+ * @returns the full skill, including body content, or `undefined`.
+ */
+async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
+```
+
+Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
+
+<a id="skills-events"></a>
+
+### `skills/*` events
+
+<a id="skillschange--emit"></a>
+
+#### `skills/change` — emit
+
+A skill provider, runtime contribution, or provider-backed catalog may have changed. This is an unfiltered invalidation notification; consumers refetch the catalog for their own lookup options. Listener failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * A skill provider, runtime contribution, or provider-backed catalog may
+ * have changed. This is an unfiltered invalidation notification; consumers
+ * refetch the catalog for their own lookup options. Listener failures are
+ * contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'skills/change'(): void
+```
+
+Source: [`packages/skill/skill/src/index.ts:283`](../../packages/skill/skill/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/skills.zh.md b/docs/subsystems/skills.zh.md
index 3f8c034ec2..e88c9f1ba1 100644
--- a/docs/subsystems/skills.zh.md
+++ b/docs/subsystems/skills.zh.md
@@ -218,3 +218,93 @@ interface Config {
 在后续每个模型步骤之前，消费方都会应用精确的工具可见性，并对完整快照中 `<available_skills>` 标签之间精确渲染的条目计算 digest。它以该插件所发布、最新一条可识别且仍可见的目录消息中的相同条目作为比较基线。digest 发生变化时，会通过 `agent.inject()` 追加一条持久的完整目录替换；删除所有 skill 时会追加一条显式的空替换。不完整快照会保留上一份可用模型视图。如果压缩（compaction）隐藏了所有历史目录消息，下一份完整快照会重新建立当前目录；如果视图为空且从未发布目录，则不发送任何内容。这些目录消息属于会话历史，而非 World State。
 
 面向模型的 `skill({ name })` 工具校验 kebab-case 名称，在与调用策略无关的目录中查找摘要，并在加载前通过 `isModelInvocable` 拒绝无权访问的 skill；随后它根据调用方 agent 的 cwd 重新读取完整定义，并在返回内容前再次检查策略。该工具将无法解析的 skill 报告为未知或已不可用，并返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 仅按需解析显式引用的脚本、参考资料和资产；加载结果不枚举 skill 目录。因此，仅修改正文会改变后续工具调用，而不会生成目录消息或改写先前工具结果。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxskills--skillservice"></a>
+
+### `ctx.skills` — `SkillService`
+
+Registry of skill providers. It merges provider catalogs with stable first-wins duplicate handling, exposes sorted invocation-neutral summaries, and loads full skill bodies on demand.
+
+```ts cordis-catalog
+/**
+ * Register a borrowed same-process provider synchronously during plugin apply. Duplicate and
+ * reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters
+ * the provider and invalidates catalog caches.
+ * @param create - synchronous factory receiving this registration's lifecycle and invalidation control.
+ * @returns the exact Cordis effect disposer that unregisters this provider;
+ *   composite effects may yield it directly to preserve teardown ordering.
+ */
+registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void
+
+/**
+ * Register a borrowed readonly runtime skill. Project entries outrank runtime entries, which
+ * outrank user entries. Same-name runtime entries are first-wins; a duplicate logs a warning and
+ * receives a no-op disposer so it cannot remove the winner.
+ * @param skill - the skill definition input; omitted invocation and provider fields receive defaults.
+ * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
+ */
+register(skill: SkillRegistration): () => void
+
+/**
+ * List invocation-neutral skill summaries for a workspace. Consumers apply
+ * model or user invocation policy at their operational boundary. Lookup
+ * options and provider candidates are readonly same-process values borrowed
+ * throughout discovery.
+ * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+ * @returns all sorted winning summaries.
+ */
+async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>
+
+/**
+ * Observe the current invocation-neutral catalog and whether discovery completed within a stable revision.
+ * Incomplete observations are never cached, allowing consumers to retain last-good state and
+ * retry on their next request boundary.
+ * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+ * @returns sorted summaries plus discovery-completeness state.
+ */
+async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
+
+/**
+ * Load and validate the winning candidate, passing its opaque discovery locator back to the
+ * provider. Cancellation is rechecked after selection, including cache hits, and raced against
+ * loading so an uncooperative provider cannot hang the caller.
+ * @param name - kebab-case skill name.
+ * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+ * @returns the full skill, including body content, or `undefined`.
+ */
+async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
+```
+
+Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
+
+<a id="skills-events"></a>
+
+### `skills/*` events
+
+<a id="skillschange--emit"></a>
+
+#### `skills/change` — emit
+
+A skill provider, runtime contribution, or provider-backed catalog may have changed. This is an unfiltered invalidation notification; consumers refetch the catalog for their own lookup options. Listener failures are contained and cannot veto the registry mutation.
+
+```ts cordis-catalog
+/**
+ * A skill provider, runtime contribution, or provider-backed catalog may
+ * have changed. This is an unfiltered invalidation notification; consumers
+ * refetch the catalog for their own lookup options. Listener failures are
+ * contained and cannot veto the registry mutation.
+ * @mode emit
+ */
+'skills/change'(): void
+```
+
+Source: [`packages/skill/skill/src/index.ts:283`](../../packages/skill/skill/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
index 17f210bc85..67b938a93a 100644
--- a/docs/subsystems/spill.i18n.yaml
+++ b/docs/subsystems/spill.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 docs/core-data-structures/spill.md
-spill.md: a798d8143b2849dc0cf49d04e7019ce796cdee45
-spill.zh.md: 1167c6f985dbc204dc7166b0fb5854dcf55bc72f
+#   pnpm run verify-translation-pairing --write docs/subsystems/spill.md
+spill.md: 41a3fdaf7d9b15fbc6d479724f77f579b8a98738
+spill.zh.md: 02a6fc4e88dfcfdb47f7639d988fc09c6bc42c69
diff --git a/docs/subsystems/spill.md b/docs/subsystems/spill.md
index a798d8143b..41a3fdaf7d 100644
--- a/docs/subsystems/spill.md
+++ b/docs/subsystems/spill.md
@@ -83,3 +83,35 @@ type SpillLocator = Branded<'SpillLocator'>
 `SpillStore` (`ctx.spillStore`, defined in [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)) is a one-method abstract service: `saveText(input) → Promise<SpillRef>`. It persists the FULL `content` and REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable). The seam owns storage only: no retention policy, no tool-result replacement, no retrieval/search API.
 
 The local backend ([dsh-spill-local](../../packages/spill/spill-local)) writes under `<root>/session-<hash>/<random>-<safeName>` — a configured or lazily-created private (0700) root, a `sha256(sessionId)` session subdir, and an exclusive owner-only (`open(path, 'wx', 0o600)`) write so a planted symlink cannot redirect it. Its `locator` is the local path and its `retrievalHint` tells the model to use `read` or `grep` on that path. The policy consumer ([dsh-spill-policy](../../packages/spill/spill-policy)) replaces an over-`maxInlineBytes` plain-text final result with a retention-library head/tail preview plus the spill reference, best-effort: a save failure keeps the original inline result rather than turning a successful call into an `isError`.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxspillstore--spillstore-abstract-seam"></a>
+
+### `ctx.spillStore` — `SpillStore` (abstract seam)
+
+Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
+
+Semantics every implementation must honor:
+
+- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
+- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
+- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
+
+```ts cordis-catalog
+/**
+ * Persist `input.content` to a session-scoped spill artifact.
+ * @param input - the owner, provenance, suggested name, and full text to save.
+ * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
+ */
+abstract saveText(input: SaveTextSpill): Promise<SpillRef>
+```
+
+Source: [`packages/spill/spill/src/index.ts:45`](../../packages/spill/spill/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/spill.zh.md b/docs/subsystems/spill.zh.md
index 1167c6f985..02a6fc4e88 100644
--- a/docs/subsystems/spill.zh.md
+++ b/docs/subsystems/spill.zh.md
@@ -83,3 +83,35 @@ type SpillLocator = Branded<'SpillLocator'>
 `SpillStore`（`ctx.spillStore`，定义于 [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)）是只有一个方法的抽象服务：`saveText(input) → Promise<SpillRef>`。它持久保存完整的 `content`，并在实际存储失败（权限、ENOSPC、后端不可用）时拒绝。该 seam 只负责存储：不负责保留策略、工具结果替换或检索／搜索 API。
 
 本地后端（[dsh-spill-local](../../packages/spill/spill-local)）写入 `<root>/session-<hash>/<random>-<safeName>`：根目录是已配置或延迟创建的私有（0700）目录，会话子目录采用 `sha256(sessionId)`，并通过排他的仅所有者可访问写入（`open(path, 'wx', 0o600)`）防止预先植入的符号链接重定向写入。其 `locator` 是本地路径，`retrievalHint` 则告知模型在该路径上使用 `read` 或 `grep`。策略消费方（[dsh-spill-policy](../../packages/spill/spill-policy)）会把超过 `maxInlineBytes` 的纯文本最终结果替换为保留库生成的首尾预览和落盘引用；该过程尽力而为：保存失败时保留原始内联结果，而不会把成功的调用变成 `isError`。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxspillstore--spillstore-abstract-seam"></a>
+
+### `ctx.spillStore` — `SpillStore` (abstract seam)
+
+Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
+
+Semantics every implementation must honor:
+
+- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
+- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
+- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
+
+```ts cordis-catalog
+/**
+ * Persist `input.content` to a session-scoped spill artifact.
+ * @param input - the owner, provenance, suggested name, and full text to save.
+ * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
+ */
+abstract saveText(input: SaveTextSpill): Promise<SpillRef>
+```
+
+Source: [`packages/spill/spill/src/index.ts:45`](../../packages/spill/spill/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 6560eed831..98092af5b3 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.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 docs/subsystems/storage.md
-storage.md: 5d54d7337b5ef52e24179758130b9fa8cd196376
-storage.zh.md: 46346b64351322d40de166a71f7a3204c8902b2d
+storage.md: 52dc84b699921e911276ce5214bc975abfd22fa4
+storage.zh.md: f614b77153e835264e1650515946a9d2acf70e57
diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md
index 5d54d7337b..52dc84b699 100644
--- a/docs/subsystems/storage.md
+++ b/docs/subsystems/storage.md
@@ -8,7 +8,7 @@ Source: [`packages/storage/storage/src/backend.ts`](../../packages/storage/stora
 
 ## The hub: `ctx.storage`
 
-`Storage` ([signatures](../cordis-catalog/services.md#ctxstorage--storage)) is a meeting point, not a store. `ctx.storage.backend` is a name → backend table: multiple backends stay mounted side by side, and which backend serves which consumer is that consumer's configuration (the domain layer's route table), never a hub-global choice. `register(name, backend)` returns the disposer; duplicate names and unknown lookups throw `StorageError`. Disposal only unregisters the name — the owning plugin closes the backend after unregistering. Each backend plugin also publishes a lifecycle-only service key (`storageBackendServiceKey(name)`), which form providers inject so their activation cannot race backend registration.
+`Storage` ([signatures](#ctxstorage--storage)) is a meeting point, not a store. `ctx.storage.backend` is a name → backend table: multiple backends stay mounted side by side, and which backend serves which consumer is that consumer's configuration (the domain layer's route table), never a hub-global choice. `register(name, backend)` returns the disposer; duplicate names and unknown lookups throw `StorageError`. Disposal only unregisters the name — the owning plugin closes the backend after unregistering. Each backend plugin also publishes a lifecycle-only service key (`storageBackendServiceKey(name)`), which form providers inject so their activation cannot race backend registration.
 
 Data forms mount on the hub under a merge-extensible key map:
 
@@ -99,11 +99,11 @@ Reads are synchronous from authoritative in-memory state: `KvTable` exposes `get
 
 ## The domain facility: `ctx.storageDomain`
 
-`DomainFacility` ([signatures](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)) opens declared domains over routed backends. Routing is the domain plugin's configuration, never the hub's: `backend` names the required default route and `routes` overrides it per domain name. `open(spec)` runs a strict sequence, each step failing the whole call: it rejects a name already open or still closing (`already-open`), resolves the route (`backend-not-found`), requires the backend's `kv` facet (`facet-unsupported`), opens the unit (backend `version-mismatch`/`malformed-medium` pass through), and validates every stored record and global against the spec's zod schemas (`invalid-record` with the offending table and key). The caller owns the returned handle and releases it with `Domain.close()`; domains still open when the plugin unmounts are closed by the facility, and a closed domain's name frees for reopening only after teardown fully completes. `get(name)` is an untyped diagnostic lookup onto the package-private `DomainImpl` runtime behind every typed handle; `closeAll()` is the unmount path.
+`DomainFacility` ([signatures](#ctxstoragedomain--domainfacility)) opens declared domains over routed backends. Routing is the domain plugin's configuration, never the hub's: `backend` names the required default route and `routes` overrides it per domain name. `open(spec)` runs a strict sequence, each step failing the whole call: it rejects a name already open or still closing (`already-open`), resolves the route (`backend-not-found`), requires the backend's `kv` facet (`facet-unsupported`), opens the unit (backend `version-mismatch`/`malformed-medium` pass through), and validates every stored record and global against the spec's zod schemas (`invalid-record` with the offending table and key). The caller owns the returned handle and releases it with `Domain.close()`; domains still open when the plugin unmounts are closed by the facility, and a closed domain's name frees for reopening only after teardown fully completes. `get(name)` is an untyped diagnostic lookup onto the package-private `DomainImpl` runtime behind every typed handle; `closeAll()` is the unmount path.
 
 ## The change event: `domain/changed`
 
-Every durable write emits one event strictly after the backend acknowledged durability, in the domain's write-chain order ([event entry](../cordis-catalog/events.md#domainchanged--emit)):
+Every durable write emits one event strictly after the backend acknowledged durability, in the domain's write-chain order ([event entry](#domainchanged--emit)):
 
 ```ts type-equiv
 /** Shared location fields of one durable domain change. */
@@ -123,3 +123,107 @@ type DomainChanged = DomainChangedPut | DomainChangedDeleted
 ```
 
 `put` (inserts, overwrites, and global writes) carries the new snapshot in `value` — never the old value; a diffing consumer keeps its own previous snapshot. `deleted` is a tombstone with no value. The event is a notification, not a transaction participant: the commit point has passed at emission, so a synchronously throwing listener is contained with a logged warning rather than rejecting the already-durable write, and emitted values equal the in-memory state at emission. The event is in-process only; cross-process change push is deferred work recorded in the [package README](../../packages/storage/storage-domain/README.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxstorage--storage"></a>
+
+### `ctx.storage` — `Storage`
+
+The storage hub service. Backends register under `backend`; data forms mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.
+
+```ts cordis-catalog
+/**
+ * Mount a data-form facility on the hub. Mounting is an effect: the
+ * returned disposer unmounts the form.
+ * @param form - Form key declared in {@link StorageForms}.
+ * @param facility - The facility instance to expose.
+ * @returns the disposer that unmounts the form.
+ */
+mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void
+
+/**
+ * Resolve a mounted data form.
+ * @param form - Form key declared in {@link StorageForms}.
+ * @returns the mounted facility.
+ */
+form<K extends keyof StorageForms>(form: K): StorageForms[K]
+```
+
+Source: [`packages/storage/storage/src/index.ts:47`](../../packages/storage/storage/src/index.ts)
+
+<a id="ctxstoragedomain--domainfacility"></a>
+
+### `ctx.storageDomain` — `DomainFacility`
+
+The mounted domain facility. Opens declared domains over routed backends; one facility instance owns the open-domain table and enforces single-open per domain name.
+
+```ts cordis-catalog
+/**
+ * Open one declared domain. Steps, each failing the whole call: reject a
+ * name that is already open (`already-open`); resolve the backend route
+ * (`backend-not-found` passes through from the hub); require its `kv` facet
+ * (`facet-unsupported`); open the unit projected from the spec (backend
+ * `version-mismatch`/`malformed-medium` pass through); load and validate
+ * every stored record against the spec's zod schemas (`invalid-record`
+ * with the offending table and key); construct the domain.
+ *
+ * Lifecycle: the CALLER owns the returned handle and closes it via
+ * `Domain.close()` (typically as its own `ctx.effect` disposer) — the
+ * facility does not tie the domain to any consumer fiber. Domains still
+ * open when the facility unmounts are closed by the plugin disposer.
+ * @param spec - The domain declaration, typically from `defineDomain`.
+ * @returns the opened domain handle, typed by the spec.
+ */
+async open<S extends DomainSpec>(spec: S): Promise<Domain<S>>
+
+/**
+ * Look up an open domain by name, untyped. Diagnostic surface (the package
+ * invariant cross-checks change events against live domain state); typed
+ * consumers hold the handle returned by {@link open}.
+ * @param name - Domain name.
+ * @returns the open domain runtime, or `undefined` when not open.
+ */
+get(name: string): DomainImpl | undefined
+
+/**
+ * Close every domain still open on this facility. The unmount path for
+ * consumers that never called `Domain.close()` themselves; closing is
+ * idempotent, so double-closing an already-closed domain is harmless.
+ * @returns resolution after every unit is released.
+ */
+async closeAll(): Promise<void>
+```
+
+Source: [`packages/storage/storage-domain/src/index.ts:69`](../../packages/storage/storage-domain/src/index.ts)
+
+<a id="domain-events"></a>
+
+### `domain/*` events
+
+<a id="domainchanged--emit"></a>
+
+#### `domain/changed` — emit
+
+A domain record or the global singleton changed, emitted once per write strictly after the backend acknowledged durability. Events of one domain arrive in its write-chain order.
+
+```ts cordis-catalog
+/**
+ * A domain record or the global singleton changed, emitted once per write
+ * strictly after the backend acknowledged durability. Events of one
+ * domain arrive in its write-chain order.
+ * @param change - domain, table (`''` for global), key (`''` for global),
+ * operation discriminant, and on `put` the new snapshot.
+ * @mode emit
+ */
+'domain/changed'(change: DomainChanged): void
+```
+
+Source: [`packages/storage/storage-domain/src/events.ts:46`](../../packages/storage/storage-domain/src/events.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index 46346b6435..f614b77153 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -8,7 +8,7 @@
 
 ## 枢纽：`ctx.storage`
 
-`Storage`（[签名](../cordis-catalog/services.md#ctxstorage--storage)）是汇合点，不是存储本体。`ctx.storage.backend` 是一张名称 → 后端的表：多个后端并排保持挂载，哪个后端服务哪个消费方由该消费方自己的配置决定（即领域层的路由表），绝不是枢纽全局的选择。`register(name, backend)` 返回 disposer；重复名称与查找未知名称都抛出 `StorageError`。dispose（资源释放）只注销名称——由拥有插件在注销之后自行关闭后端。每个后端插件还会发布一个仅用于生命周期的服务键（`storageBackendServiceKey(name)`），数据形式提供方注入它，使自身激活不会与后端注册发生竞态。
+`Storage`（[签名](#ctxstorage--storage)）是汇合点，不是存储本体。`ctx.storage.backend` 是一张名称 → 后端的表：多个后端并排保持挂载，哪个后端服务哪个消费方由该消费方自己的配置决定（即领域层的路由表），绝不是枢纽全局的选择。`register(name, backend)` 返回 disposer；重复名称与查找未知名称都抛出 `StorageError`。dispose（资源释放）只注销名称——由拥有插件在注销之后自行关闭后端。每个后端插件还会发布一个仅用于生命周期的服务键（`storageBackendServiceKey(name)`），数据形式提供方注入它，使自身激活不会与后端注册发生竞态。
 
 数据形式以一张可合并扩展的键 map 挂载到枢纽上：
 
@@ -99,11 +99,11 @@ interface Domain<S extends DomainSpec> {
 
 ## 领域 facility：`ctx.storageDomain`
 
-`DomainFacility`（[签名](../cordis-catalog/services.md#ctxstoragedomain--domainfacility)）在经过路由的后端之上打开已声明的领域。路由是领域插件的配置，绝不属于枢纽：`backend` 指定必填的默认路由，`routes` 按领域名逐个覆盖。`open(spec)` 按严格顺序执行，每一步失败都使整个调用失败：拒绝已打开或仍在关闭中的名称（`already-open`），解析路由（`backend-not-found`），要求后端具备 `kv` facet（`facet-unsupported`），打开 unit（后端的 `version-mismatch`/`malformed-medium` 原样透传），并按 spec 的 zod schema 校验每条已存储记录和 global（`invalid-record`，附带出错的表与键）。调用方拥有返回的句柄，并用 `Domain.close()` 释放它；插件卸载时仍处于打开状态的领域由 facility 负责关闭，已关闭领域的名称只有在拆除完全结束后才释放出来供重新打开。`get(name)` 是无类型的诊断查找，命中的是每个类型化句柄背后包内私有的 `DomainImpl` 运行时；`closeAll()` 是卸载路径。
+`DomainFacility`（[签名](#ctxstoragedomain--domainfacility)）在经过路由的后端之上打开已声明的领域。路由是领域插件的配置，绝不属于枢纽：`backend` 指定必填的默认路由，`routes` 按领域名逐个覆盖。`open(spec)` 按严格顺序执行，每一步失败都使整个调用失败：拒绝已打开或仍在关闭中的名称（`already-open`），解析路由（`backend-not-found`），要求后端具备 `kv` facet（`facet-unsupported`），打开 unit（后端的 `version-mismatch`/`malformed-medium` 原样透传），并按 spec 的 zod schema 校验每条已存储记录和 global（`invalid-record`，附带出错的表与键）。调用方拥有返回的句柄，并用 `Domain.close()` 释放它；插件卸载时仍处于打开状态的领域由 facility 负责关闭，已关闭领域的名称只有在拆除完全结束后才释放出来供重新打开。`get(name)` 是无类型的诊断查找，命中的是每个类型化句柄背后包内私有的 `DomainImpl` 运行时；`closeAll()` 是卸载路径。
 
 ## 变更事件：`domain/changed`
 
-每次持久写入都发出一个事件，严格发生在后端确认持久性之后，顺序遵循该领域的写链（[事件条目](../cordis-catalog/events.md#domainchanged--emit)）：
+每次持久写入都发出一个事件，严格发生在后端确认持久性之后，顺序遵循该领域的写链（[事件条目](#domainchanged--emit)）：
 
 ```ts type-equiv
 /** Shared location fields of one durable domain change. */
@@ -123,3 +123,107 @@ type DomainChanged = DomainChangedPut | DomainChangedDeleted
 ```
 
 `put`（插入、覆写和 global 写入）在 `value` 中携带新快照——绝不携带旧值；需要做差异比较的消费方自行保留上一份快照。`deleted` 是不携带值的墓碑。该事件是通知，不是事务参与者：发出时提交点已经过去，因此同步抛出的监听器会被兜住并记录一条警告，而不会让已经持久的写入被拒绝；发出的值等于发出时刻的内存态。该事件仅限进程内；跨进程的变更推送是延后工作，记录在[包 README](../../packages/storage/storage-domain/README.md)中。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxstorage--storage"></a>
+
+### `ctx.storage` — `Storage`
+
+The storage hub service. Backends register under `backend`; data forms mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.
+
+```ts cordis-catalog
+/**
+ * Mount a data-form facility on the hub. Mounting is an effect: the
+ * returned disposer unmounts the form.
+ * @param form - Form key declared in {@link StorageForms}.
+ * @param facility - The facility instance to expose.
+ * @returns the disposer that unmounts the form.
+ */
+mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void
+
+/**
+ * Resolve a mounted data form.
+ * @param form - Form key declared in {@link StorageForms}.
+ * @returns the mounted facility.
+ */
+form<K extends keyof StorageForms>(form: K): StorageForms[K]
+```
+
+Source: [`packages/storage/storage/src/index.ts:47`](../../packages/storage/storage/src/index.ts)
+
+<a id="ctxstoragedomain--domainfacility"></a>
+
+### `ctx.storageDomain` — `DomainFacility`
+
+The mounted domain facility. Opens declared domains over routed backends; one facility instance owns the open-domain table and enforces single-open per domain name.
+
+```ts cordis-catalog
+/**
+ * Open one declared domain. Steps, each failing the whole call: reject a
+ * name that is already open (`already-open`); resolve the backend route
+ * (`backend-not-found` passes through from the hub); require its `kv` facet
+ * (`facet-unsupported`); open the unit projected from the spec (backend
+ * `version-mismatch`/`malformed-medium` pass through); load and validate
+ * every stored record against the spec's zod schemas (`invalid-record`
+ * with the offending table and key); construct the domain.
+ *
+ * Lifecycle: the CALLER owns the returned handle and closes it via
+ * `Domain.close()` (typically as its own `ctx.effect` disposer) — the
+ * facility does not tie the domain to any consumer fiber. Domains still
+ * open when the facility unmounts are closed by the plugin disposer.
+ * @param spec - The domain declaration, typically from `defineDomain`.
+ * @returns the opened domain handle, typed by the spec.
+ */
+async open<S extends DomainSpec>(spec: S): Promise<Domain<S>>
+
+/**
+ * Look up an open domain by name, untyped. Diagnostic surface (the package
+ * invariant cross-checks change events against live domain state); typed
+ * consumers hold the handle returned by {@link open}.
+ * @param name - Domain name.
+ * @returns the open domain runtime, or `undefined` when not open.
+ */
+get(name: string): DomainImpl | undefined
+
+/**
+ * Close every domain still open on this facility. The unmount path for
+ * consumers that never called `Domain.close()` themselves; closing is
+ * idempotent, so double-closing an already-closed domain is harmless.
+ * @returns resolution after every unit is released.
+ */
+async closeAll(): Promise<void>
+```
+
+Source: [`packages/storage/storage-domain/src/index.ts:69`](../../packages/storage/storage-domain/src/index.ts)
+
+<a id="domain-events"></a>
+
+### `domain/*` events
+
+<a id="domainchanged--emit"></a>
+
+#### `domain/changed` — emit
+
+A domain record or the global singleton changed, emitted once per write strictly after the backend acknowledged durability. Events of one domain arrive in its write-chain order.
+
+```ts cordis-catalog
+/**
+ * A domain record or the global singleton changed, emitted once per write
+ * strictly after the backend acknowledged durability. Events of one
+ * domain arrive in its write-chain order.
+ * @param change - domain, table (`''` for global), key (`''` for global),
+ * operation discriminant, and on `put` the new snapshot.
+ * @mode emit
+ */
+'domain/changed'(change: DomainChanged): void
+```
+
+Source: [`packages/storage/storage-domain/src/events.ts:46`](../../packages/storage/storage-domain/src/events.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 57b960da91..e6ead80f87 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/core-data-structures/subagent.md
-subagent.md: b26a12d1d50305d86d7ada29cac83474009d81ce
-subagent.zh.md: 6c4c64ff22050b73699a97093acd0032668fde3d
+#   pnpm run verify-translation-pairing --write docs/subsystems/subagent.md
+subagent.md: cbf9043b36a5cb2ab37bb99c6dbbf5a18d1e0288
+subagent.zh.md: ffd8fefd8b9d128c21e1b91ee0ba1fb706638fa9
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index b26a12d1d5..cbf9043b36 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -433,3 +433,269 @@ The spawn and fork backends create an ordinary one-shot agent through `parent.ct
 
 - **Delegation depth** is durable `SessionHeader.delegationDepth` plus the merge-extensible runtime field `AgentOptions.subagentDepth`; absence means top-level depth zero, and the greater present value is authoritative. The seam owns both fields — the loop neither sets nor reads them — so an in-process child persists parent depth + 1, cold resume cannot lower it, and every start rejects a derived depth outside the safe-integer domain or above a defined absolute `request.maxDepth` cap.
 - **Fork seeding** uses `CreateAgentOptions.seed` (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/support/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsubagents--subagentservice"></a>
+
+### `ctx.subagents` — `SubagentService`
+
+Named provider registry with one-shot runs, durable discovery, and continuable-child operations.
+
+```ts cordis-catalog
+/**
+ * Establish one durable continuable child and deliver its initial prompt.
+ * Resolves when the child's inbox accepts that prompt, without waiting for the
+ * turn to start or for the message to reach the Session log; any earlier
+ * failure rejects with no ids and rolls back the child entirely.
+ * @param spec - provider, delegation request, and caller cancellation.
+ * @returns the durable child id and the accepted prompt's message id.
+ * @throws when continuation services are unavailable or materialization fails.
+ */
+async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
+
+/**
+ * Deliver one later message to a continuable child as its next FIFO turn. A
+ * resident child's Agent inbox accepts it directly (waking a `waiting`
+ * Activation), while an absent one is cold-resumed from its persisted
+ * Session. The Agent inbox is the only queue, so every accepted message has
+ * one observable order.
+ * @param parent - the exact live direct parent authorizing this delivery.
+ * @param childId - durable child session id.
+ * @param content - user-role content to deliver.
+ * @param options - durable provenance and caller cancellation, which stops the
+ *   operation only before inbox acceptance.
+ * @returns the accepted message's inbox id.
+ * @throws when continuation services are unavailable, parent authority is
+ *   rejected, or the message was not admitted.
+ */
+async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>
+
+/**
+ * Interrupt one live continuable child's current turn under a human parent
+ * address or an exact live ancestor Agent. Fire-and-return: the cancel
+ * signal is issued before this returns, but the target may keep running
+ * until it observes the signal. Unclaimed pending inbox work, the Activation,
+ * and published descendants are preserved; claimed work is not requeued.
+ * Once the interrupted driver is idle, a waking send resumes the parked FIFO
+ * queue. An absent target — including a one-shot or unknown id —
+ * is an accepted no-op, as is a manager-less composition, which cannot own a
+ * live Activation.
+ * @param targetSessionId - the durable child session id to interrupt.
+ * @param authority - the human parent address or exact live ancestor Agent.
+ * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
+ *   live target.
+ */
+interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
+
+/**
+ * Deliver selected content from one live continuable child to its durable
+ * direct parent. The child is the authority credential; callers cannot name a
+ * recipient. Reporting does not conclude the child's turn or Activation.
+ * @param child - exact live reporting child.
+ * @param content - selected model-facing content.
+ * @param options - parent scheduling and pre-acceptance cancellation.
+ * @returns the stable identity of the parent-accepted message.
+ * @throws when continuation services are unavailable, sender authorization
+ *   fails, or the direct parent is not live.
+ */
+async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>
+
+/**
+ * Compose one deployment capability into every continuable child's
+ * unpublished creation context on fresh creation and cold resume. Grants wait
+ * for the next Activation; removing the contribution revokes every resident
+ * installation immediately.
+ * @param contribution - synchronous child-scope installer.
+ * @returns the exact Cordis effect disposer.
+ */
+registerContinuableSetup(contribution: ContinuableSetupContribution): () => void
+
+/**
+ * Close continuable admission below exact live parent Agents, stop only their
+ * visible descendant Activations synchronously, then await admitted scoped
+ * materializations and release those forests child-first. The scoped cutoff
+ * lasts until each exact parent leaves the registry; unrelated parent trees
+ * remain live.
+ * @param parents - exact host-owned parent Agents entering teardown.
+ * @returns once every retained descendant Activation released its `AgentHandle`.
+ * @throws an aggregate error after all branches settle when any failed.
+ */
+async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
+
+/**
+ * Enumerate the parent's direct session-backed subagents without loading or
+ * resuming an Agent and without any query seam: the listing merges the live
+ * session store with optional session persistence (live-preferred) and
+ * serves each child's durable mode/label from the registered `subagent`
+ * projection unit down a three-rung ladder — the registry's watermark
+ * snapshot for a live child; for a cold one, a durable projection-cache
+ * row when the optional cache serves an own-suffix identity (its `seq`
+ * gate proves the value postdates the fork seed, where a child's own
+ * descriptor is immutable once appended), else one persistence inspection
+ * folded through the registry. The
+ * projection fold is the single classification authority; per-child
+ * diagnostics relay a fold that served no identity or a failed inspection,
+ * never a list-time descriptor parse. Absent persistence, enumeration is
+ * live-only (a cold child cannot be resumed then either, so its absence is
+ * capability absence, not an error). This service consults no Agent
+ * registrations, Activations, or providers.
+ *
+ * Every persistence read receives `signal`, and the listing rechecks
+ * cancellation around each of those awaits. Read rejections that settle
+ * after an abort become a stable `SubagentError` with code `CANCELLED`.
+ * @param parentSessionId - parent session whose direct children are listed.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
+ * @returns children and per-child diagnostics ordered by `createdAt`, then id.
+ * @throws {@link SubagentError} when the projection registry or the session
+ *   store is not mounted, or the caller cancels the listing.
+ */
+listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>
+
+/**
+ * Enumerate the root's complete session-backed subagent tree in stable
+ * pre-order from one live-preferred corpus, without loading or resuming an
+ * Agent. Ordinary sessions and one-shot children remain traversal nodes so
+ * continuable descendants below them are discovered; each returned entry
+ * adds its durable `parentId` and root-relative `depth`. Identity resolution,
+ * diagnostics, optional persistence, and cancellation follow the same
+ * projection-backed contract as {@link listChildren}.
+ * @param rootSessionId - session whose complete descendant tree is listed.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
+ * @returns children and per-candidate diagnostics with tree position, in
+ *   stable pre-order.
+ * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+ */
+listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
+
+/**
+ * Register a provider under its name. Registration is effect-scoped and HMR
+ * safe; removing a provider blocks new starts but does not revoke runs that
+ * were already returned to their holders.
+ * @param provider - the trusted provider implementation.
+ * @returns the exact Cordis effect disposer.
+ */
+registerProvider(provider: SubagentProvider): () => void
+
+/**
+ * Look up a provider by name.
+ * @param name - the provider name.
+ * @returns the provider, or undefined when absent.
+ */
+getProvider(name: string): SubagentProvider | undefined
+
+/**
+ * List registered provider names in insertion order.
+ * @returns the registered names.
+ */
+list(): string[]
+
+/**
+ * Establish a published child on the named provider. Capability and semantic
+ * checks run before delegation. Provider ownership lasts until its promise
+ * fulfills; a rejection therefore has no run for the caller to dispose and
+ * emits no run lifecycle events. Post-publication turn and infrastructure
+ * failures settle through the returned run.
+ * @param name - the provider to use.
+ * @param request - child label, prompt, parent, signal, and optional capabilities.
+ * @returns the published holder-owned run.
+ */
+async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
+```
+
+Types: [Agent](core.md) · [ContentBlock](core.md) · [MessageId](core.md) · [SessionId](core.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagent-events"></a>
+
+### `subagent/*` events
+
+<a id="subagentend--emit"></a>
+
+#### `subagent/end` — emit
+
+A published child settled. Scope-filtered dispatch uses the same delegating parent carrier as `subagent/start`, so the lifecycle pair reaches the same scoped audience.
+
+```ts cordis-catalog
+/**
+ * A published child settled. Scope-filtered dispatch uses the same delegating
+ * parent carrier as `subagent/start`, so the lifecycle pair reaches the
+ * same scoped audience.
+ * @param info - the run identity and terminal outcome.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentprovider-added--emit"></a>
+
+#### `subagent/provider-added` — emit
+
+A provider became resolvable in the registry.
+
+```ts cordis-catalog
+/**
+ * A provider became resolvable in the registry.
+ * @param provider - the registered provider.
+ * @mode emit
+ */
+'subagent/provider-added'(provider: SubagentProvider): void
+```
+
+Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentprovider-removed--emit"></a>
+
+#### `subagent/provider-removed` — emit
+
+A provider left the registry. Accepted runs remain holder-owned.
+
+```ts cordis-catalog
+/**
+ * A provider left the registry. Accepted runs remain holder-owned.
+ * @param name - the provider name that no longer resolves.
+ * @mode emit
+ */
+'subagent/provider-removed'(name: string): void
+```
+
+Source: [`packages/subagent/subagent/src/index.ts:142`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentstart--emit"></a>
+
+#### `subagent/start` — emit
+
+A provider established a published child. For in-process providers, `ctx.agents.get(info.id)` resolves during this notification. Scope-filtered dispatch keys the carrier by the delegating parent, so a parent-scoped listener observes only its own delegations. Paired with `subagent/end`.
+
+```ts cordis-catalog
+/**
+ * A provider established a published child. For in-process providers,
+ * `ctx.agents.get(info.id)` resolves during this notification.
+ * Scope-filtered dispatch keys the carrier by the delegating parent, so a
+ * parent-scoped listener observes only its own delegations. Paired with
+ * `subagent/end`.
+ * @param info - the provider and published child identity.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 6c4c64ff22..ffd8fefd8b 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -435,3 +435,269 @@ spawn 和 fork 后端通过 `parent.ctx` 创建一个普通的单次 agent，将
 
 - **委派深度**由持久 `SessionHeader.delegationDepth` 与可合并扩展的运行时字段 `AgentOptions.subagentDepth` 共同表示；缺失表示顶层深度为零，存在的较大值具有权威性。两个字段都归该 seam 所有——循环既不设置也不读取它们——因此进程内子 agent 会持久保存 parent 深度 + 1，冷恢复无法降低深度，而且每次 start 都会拒绝超出安全整数域、或高于已定义绝对 `request.maxDepth` 上限的派生深度。
 - **Fork 种子注入**使用 `CreateAgentOptions.seed`（一个 `SessionEvent[]` 前缀，经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递，与 `ctx.agents.resume()` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/support/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsubagents--subagentservice"></a>
+
+### `ctx.subagents` — `SubagentService`
+
+Named provider registry with one-shot runs, durable discovery, and continuable-child operations.
+
+```ts cordis-catalog
+/**
+ * Establish one durable continuable child and deliver its initial prompt.
+ * Resolves when the child's inbox accepts that prompt, without waiting for the
+ * turn to start or for the message to reach the Session log; any earlier
+ * failure rejects with no ids and rolls back the child entirely.
+ * @param spec - provider, delegation request, and caller cancellation.
+ * @returns the durable child id and the accepted prompt's message id.
+ * @throws when continuation services are unavailable or materialization fails.
+ */
+async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
+
+/**
+ * Deliver one later message to a continuable child as its next FIFO turn. A
+ * resident child's Agent inbox accepts it directly (waking a `waiting`
+ * Activation), while an absent one is cold-resumed from its persisted
+ * Session. The Agent inbox is the only queue, so every accepted message has
+ * one observable order.
+ * @param parent - the exact live direct parent authorizing this delivery.
+ * @param childId - durable child session id.
+ * @param content - user-role content to deliver.
+ * @param options - durable provenance and caller cancellation, which stops the
+ *   operation only before inbox acceptance.
+ * @returns the accepted message's inbox id.
+ * @throws when continuation services are unavailable, parent authority is
+ *   rejected, or the message was not admitted.
+ */
+async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>
+
+/**
+ * Interrupt one live continuable child's current turn under a human parent
+ * address or an exact live ancestor Agent. Fire-and-return: the cancel
+ * signal is issued before this returns, but the target may keep running
+ * until it observes the signal. Unclaimed pending inbox work, the Activation,
+ * and published descendants are preserved; claimed work is not requeued.
+ * Once the interrupted driver is idle, a waking send resumes the parked FIFO
+ * queue. An absent target — including a one-shot or unknown id —
+ * is an accepted no-op, as is a manager-less composition, which cannot own a
+ * live Activation.
+ * @param targetSessionId - the durable child session id to interrupt.
+ * @param authority - the human parent address or exact live ancestor Agent.
+ * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
+ *   live target.
+ */
+interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
+
+/**
+ * Deliver selected content from one live continuable child to its durable
+ * direct parent. The child is the authority credential; callers cannot name a
+ * recipient. Reporting does not conclude the child's turn or Activation.
+ * @param child - exact live reporting child.
+ * @param content - selected model-facing content.
+ * @param options - parent scheduling and pre-acceptance cancellation.
+ * @returns the stable identity of the parent-accepted message.
+ * @throws when continuation services are unavailable, sender authorization
+ *   fails, or the direct parent is not live.
+ */
+async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>
+
+/**
+ * Compose one deployment capability into every continuable child's
+ * unpublished creation context on fresh creation and cold resume. Grants wait
+ * for the next Activation; removing the contribution revokes every resident
+ * installation immediately.
+ * @param contribution - synchronous child-scope installer.
+ * @returns the exact Cordis effect disposer.
+ */
+registerContinuableSetup(contribution: ContinuableSetupContribution): () => void
+
+/**
+ * Close continuable admission below exact live parent Agents, stop only their
+ * visible descendant Activations synchronously, then await admitted scoped
+ * materializations and release those forests child-first. The scoped cutoff
+ * lasts until each exact parent leaves the registry; unrelated parent trees
+ * remain live.
+ * @param parents - exact host-owned parent Agents entering teardown.
+ * @returns once every retained descendant Activation released its `AgentHandle`.
+ * @throws an aggregate error after all branches settle when any failed.
+ */
+async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
+
+/**
+ * Enumerate the parent's direct session-backed subagents without loading or
+ * resuming an Agent and without any query seam: the listing merges the live
+ * session store with optional session persistence (live-preferred) and
+ * serves each child's durable mode/label from the registered `subagent`
+ * projection unit down a three-rung ladder — the registry's watermark
+ * snapshot for a live child; for a cold one, a durable projection-cache
+ * row when the optional cache serves an own-suffix identity (its `seq`
+ * gate proves the value postdates the fork seed, where a child's own
+ * descriptor is immutable once appended), else one persistence inspection
+ * folded through the registry. The
+ * projection fold is the single classification authority; per-child
+ * diagnostics relay a fold that served no identity or a failed inspection,
+ * never a list-time descriptor parse. Absent persistence, enumeration is
+ * live-only (a cold child cannot be resumed then either, so its absence is
+ * capability absence, not an error). This service consults no Agent
+ * registrations, Activations, or providers.
+ *
+ * Every persistence read receives `signal`, and the listing rechecks
+ * cancellation around each of those awaits. Read rejections that settle
+ * after an abort become a stable `SubagentError` with code `CANCELLED`.
+ * @param parentSessionId - parent session whose direct children are listed.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
+ * @returns children and per-child diagnostics ordered by `createdAt`, then id.
+ * @throws {@link SubagentError} when the projection registry or the session
+ *   store is not mounted, or the caller cancels the listing.
+ */
+listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>
+
+/**
+ * Enumerate the root's complete session-backed subagent tree in stable
+ * pre-order from one live-preferred corpus, without loading or resuming an
+ * Agent. Ordinary sessions and one-shot children remain traversal nodes so
+ * continuable descendants below them are discovered; each returned entry
+ * adds its durable `parentId` and root-relative `depth`. Identity resolution,
+ * diagnostics, optional persistence, and cancellation follow the same
+ * projection-backed contract as {@link listChildren}.
+ * @param rootSessionId - session whose complete descendant tree is listed.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
+ * @returns children and per-candidate diagnostics with tree position, in
+ *   stable pre-order.
+ * @throws {@link SubagentError} under the same conditions as {@link listChildren}.
+ */
+listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
+
+/**
+ * Register a provider under its name. Registration is effect-scoped and HMR
+ * safe; removing a provider blocks new starts but does not revoke runs that
+ * were already returned to their holders.
+ * @param provider - the trusted provider implementation.
+ * @returns the exact Cordis effect disposer.
+ */
+registerProvider(provider: SubagentProvider): () => void
+
+/**
+ * Look up a provider by name.
+ * @param name - the provider name.
+ * @returns the provider, or undefined when absent.
+ */
+getProvider(name: string): SubagentProvider | undefined
+
+/**
+ * List registered provider names in insertion order.
+ * @returns the registered names.
+ */
+list(): string[]
+
+/**
+ * Establish a published child on the named provider. Capability and semantic
+ * checks run before delegation. Provider ownership lasts until its promise
+ * fulfills; a rejection therefore has no run for the caller to dispose and
+ * emits no run lifecycle events. Post-publication turn and infrastructure
+ * failures settle through the returned run.
+ * @param name - the provider to use.
+ * @param request - child label, prompt, parent, signal, and optional capabilities.
+ * @returns the published holder-owned run.
+ */
+async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
+```
+
+Types: [Agent](core.md) · [ContentBlock](core.md) · [MessageId](core.md) · [SessionId](core.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagent-events"></a>
+
+### `subagent/*` events
+
+<a id="subagentend--emit"></a>
+
+#### `subagent/end` — emit
+
+A published child settled. Scope-filtered dispatch uses the same delegating parent carrier as `subagent/start`, so the lifecycle pair reaches the same scoped audience.
+
+```ts cordis-catalog
+/**
+ * A published child settled. Scope-filtered dispatch uses the same delegating
+ * parent carrier as `subagent/start`, so the lifecycle pair reaches the
+ * same scoped audience.
+ * @param info - the run identity and terminal outcome.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentprovider-added--emit"></a>
+
+#### `subagent/provider-added` — emit
+
+A provider became resolvable in the registry.
+
+```ts cordis-catalog
+/**
+ * A provider became resolvable in the registry.
+ * @param provider - the registered provider.
+ * @mode emit
+ */
+'subagent/provider-added'(provider: SubagentProvider): void
+```
+
+Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentprovider-removed--emit"></a>
+
+#### `subagent/provider-removed` — emit
+
+A provider left the registry. Accepted runs remain holder-owned.
+
+```ts cordis-catalog
+/**
+ * A provider left the registry. Accepted runs remain holder-owned.
+ * @param name - the provider name that no longer resolves.
+ * @mode emit
+ */
+'subagent/provider-removed'(name: string): void
+```
+
+Source: [`packages/subagent/subagent/src/index.ts:142`](../../packages/subagent/subagent/src/index.ts)
+
+<a id="subagentstart--emit"></a>
+
+#### `subagent/start` — emit
+
+A provider established a published child. For in-process providers, `ctx.agents.get(info.id)` resolves during this notification. Scope-filtered dispatch keys the carrier by the delegating parent, so a parent-scoped listener observes only its own delegations. Paired with `subagent/end`.
+
+```ts cordis-catalog
+/**
+ * A provider established a published child. For in-process providers,
+ * `ctx.agents.get(info.id)` resolves during this notification.
+ * Scope-filtered dispatch keys the carrier by the delegating parent, so a
+ * parent-scoped listener observes only its own delegations. Paired with
+ * `subagent/end`.
+ * @param info - the provider and published child identity.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
+'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index b2d38854b2..a3071e98a9 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: 023b122218ad1caa2b8e16c26b0bc8b0d4183c28
-subprocess.zh.md: 5ee9c782c0ce73ca9a2e694450ed38b8d548dc09
+#   pnpm run verify-translation-pairing --write docs/subsystems/subprocess.md
+subprocess.md: 0bc2bf86518bcc60bef02554b94471425f2ac433
+subprocess.zh.md: 5d6425707edcf1952c25dbdc91dbf7aab3779350
diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md
index 023b122218..0bc2bf8651 100644
--- a/docs/subsystems/subprocess.md
+++ b/docs/subsystems/subprocess.md
@@ -242,8 +242,83 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches quiescence for every session member the provider can still observe; providers document substrate-specific observability limits. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
 
-The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam).
+The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessservice-abstract-seam).
 
 ## Service behavior
 
 The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) implements them with detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the interface contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxe2b--e2bsandboxservice"></a>
+
+### `ctx.e2b` — `E2BSandboxService`
+
+Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal. Creation begins at plugin construction; adapters await getSandbox before their first operation.
+
+```ts cordis-catalog
+/**
+ * Return the shared live SDK handle.
+ * @returns the created sandbox after the configured cwd exists.
+ * @throws when E2B rejects creation or the service is disposing.
+ */
+async getSandbox(): Promise<Sandbox>
+```
+
+Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
+
+<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
+
+### `ctx.subprocess` — `SubprocessService` (abstract seam)
+
+Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- Executable paths belong to one execution world shared with the mounted filesystem provider.
+- spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures.
+- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.
+- SubprocessHandle.terminate (and the spec's abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence.
+- Disposal of the service terminates all still-running managed processes and awaits their exit.
+- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.
+
+```ts cordis-catalog
+/**
+ * Resolve one configured executable in this provider's execution world.
+ * Absolute paths are verified; bare names use the provider's scrubbed PATH
+ * plus explicit environment overrides. Relative paths containing separators
+ * are rejected: no current consumer defines which directory they would
+ * resolve against, so providers fail loud instead of guessing.
+ * @param command - absolute executable path or bare PATH name.
+ * @param env - explicit environment entries used for lookup.
+ * @param signal - aborts remote or local lookup.
+ * @returns a canonical executable path.
+ */
+abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
+
+/**
+ * Start one managed child process from a fully-specified spec; this seam
+ * applies no defaults.
+ * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.
+ * @returns the live process handle (streams/readers, signalling, outcome promise).
+ */
+abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
+
+/**
+ * Allocate a real terminal and start one owned process session. This is the
+ * only non-pipe process primitive: implementations own terminal byte I/O,
+ * foreground groups, signals, and complete session-tree cleanup.
+ * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
+ * @returns the live terminal handle after allocation succeeds.
+ */
+abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
+```
+
+Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index 5ee9c782c0..5d6425707e 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -242,8 +242,83 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，提供方则会记录执行基底特有的可观察性限制。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
 
-终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](../cordis-catalog/services.md#ctxsubprocess--subprocessservice-abstract-seam)中。
+终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessservice-abstract-seam)中。
 
 ## 服务行为
 
 抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxe2b--e2bsandboxservice"></a>
+
+### `ctx.e2b` — `E2BSandboxService`
+
+Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal. Creation begins at plugin construction; adapters await getSandbox before their first operation.
+
+```ts cordis-catalog
+/**
+ * Return the shared live SDK handle.
+ * @returns the created sandbox after the configured cwd exists.
+ * @throws when E2B rejects creation or the service is disposing.
+ */
+async getSandbox(): Promise<Sandbox>
+```
+
+Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
+
+<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
+
+### `ctx.subprocess` — `SubprocessService` (abstract seam)
+
+Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- Executable paths belong to one execution world shared with the mounted filesystem provider.
+- spawn returns immediately with a live handle; `done` resolves at process close with exit facts and rejects only for spawn-level failures.
+- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.
+- SubprocessHandle.terminate (and the spec's abort signal) escalates SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every platform. SubprocessHandle.waitForExit observes whole-tree liveness, so a consumer-owned teardown ladder can hold each tier on real quiescence.
+- Disposal of the service terminates all still-running managed processes and awaits their exit.
+- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.
+
+```ts cordis-catalog
+/**
+ * Resolve one configured executable in this provider's execution world.
+ * Absolute paths are verified; bare names use the provider's scrubbed PATH
+ * plus explicit environment overrides. Relative paths containing separators
+ * are rejected: no current consumer defines which directory they would
+ * resolve against, so providers fail loud instead of guessing.
+ * @param command - absolute executable path or bare PATH name.
+ * @param env - explicit environment entries used for lookup.
+ * @param signal - aborts remote or local lookup.
+ * @returns a canonical executable path.
+ */
+abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
+
+/**
+ * Start one managed child process from a fully-specified spec; this seam
+ * applies no defaults.
+ * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.
+ * @returns the live process handle (streams/readers, signalling, outcome promise).
+ */
+abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
+
+/**
+ * Allocate a real terminal and start one owned process session. This is the
+ * only non-pipe process primitive: implementations own terminal byte I/O,
+ * foreground groups, signals, and complete session-tree cleanup.
+ * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
+ * @returns the live terminal handle after allocation succeeds.
+ */
+abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
+```
+
+Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/system-prompt.i18n.yaml b/docs/subsystems/system-prompt.i18n.yaml
index 5c39e3cbcb..a1e14385f4 100644
--- a/docs/subsystems/system-prompt.i18n.yaml
+++ b/docs/subsystems/system-prompt.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 docs/subsystems/system-prompt.md
-system-prompt.md: 59193c1881abcadbc8a1778cde92f5a6572eee24
-system-prompt.zh.md: 41e45417817895ccf6def70e510eca7422a65e41
+system-prompt.md: 94ce40f8bf98dd4efe3514879c2527c2a7bd3b21
+system-prompt.zh.md: 37d366774089f91756433602a719e99b57747c17
diff --git a/docs/subsystems/system-prompt.md b/docs/subsystems/system-prompt.md
index 59193c1881..94ce40f8bf 100644
--- a/docs/subsystems/system-prompt.md
+++ b/docs/subsystems/system-prompt.md
@@ -76,3 +76,113 @@ interface PromptContext {
   readonly text: string | ((context: AssembleContext) => string)
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsystemprompt--systemprompt"></a>
+
+### `ctx.systemPrompt` — `SystemPrompt`
+
+Registry service for the prompt inputs assembled before each model step.
+
+```ts cordis-catalog
+/**
+ * Register an ordered prompt section in the calling context's scope. A scoped
+ * section shadows a global section with the same name; duplicates within one
+ * layer and non-finite orders throw. Registration and disposal emit
+ * `system-prompt/change`.
+ * @param section - the section to register.
+ * @returns the exact Cordis effect disposer.
+ */
+section(section: PromptSection): () => void
+
+/**
+ * Register ordered dynamic context in the calling context's scope. Scoped
+ * entries shadow global entries with the same name.
+ * @param context - the context contribution to register.
+ * @returns the exact Cordis effect disposer.
+ */
+context(context: PromptContext): () => void
+
+/**
+ * Register a tool-schema provider in the calling context's scope. Global and
+ * matching scoped providers both contribute; returning the reserved
+ * {@link TOOL_ORDER_REST} name makes assembly fail.
+ * @param provider - evaluated for each assembly with its context.
+ * @returns the exact Cordis effect disposer.
+ */
+tools(provider: (context: AssembleContext) => ToolProviderResult): () => void
+
+/**
+ * Register a prompt variable in the calling context's scope. Scoped values
+ * shadow globals; invalid or duplicate names throw. A provider may return
+ * `undefined`, but rendering a section that references that value then fails.
+ * @param name - the `[a-z][a-z0-9_]*` reference name.
+ * @param provider - evaluated for each assembly.
+ * @returns the exact Cordis effect disposer.
+ */
+variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
+
+/**
+ * Assemble global and scoped providers, detach tool parameters, apply
+ * canonical ordering, then run the assembly waterfall. Scoped sections and
+ * variables shadow globals; the returned waterfall value is authoritative.
+ * @param context - the optional scope and plugin-defined assembly fields.
+ * @returns the authoritative post-waterfall assembly.
+ */
+async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
+```
+
+Source: [`packages/core/system-prompt/src/index.ts:314`](../../packages/core/system-prompt/src/index.ts)
+
+<a id="system-prompt-events"></a>
+
+### `system-prompt/*` events
+
+<a id="system-promptassemble--waterfall"></a>
+
+#### `system-prompt/assemble` — waterfall
+
+Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns.
+
+```ts cordis-catalog
+/**
+ * Expert waterfall over the assembled sections, contexts, tools, and variables.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
+ * receive only that scope's assemblies. The returned value is authoritative.
+ * A supplied signal controls only this explicit assembly request and must not
+ * be retained to control later turns.
+ * @param assembly - the mutable assembly built from registered providers.
+ * @param context - the caller's per-assembly context.
+ * @mode waterfall
+ */
+'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts)
+
+<a id="system-promptchange--emit"></a>
+
+#### `system-prompt/change` — emit
+
+Emitted when any prompt provider changes. This registry notification is unfiltered because a global change affects every scope.
+
+```ts cordis-catalog
+/**
+ * Emitted when any prompt provider changes. This registry notification is
+ * unfiltered because a global change affects every scope.
+ * @mode emit
+ */
+'system-prompt/change'(): void
+```
+
+Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/system-prompt/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/system-prompt.zh.md b/docs/subsystems/system-prompt.zh.md
index 41e4541781..37d3667740 100644
--- a/docs/subsystems/system-prompt.zh.md
+++ b/docs/subsystems/system-prompt.zh.md
@@ -76,3 +76,113 @@ interface PromptContext {
   readonly text: string | ((context: AssembleContext) => string)
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsystemprompt--systemprompt"></a>
+
+### `ctx.systemPrompt` — `SystemPrompt`
+
+Registry service for the prompt inputs assembled before each model step.
+
+```ts cordis-catalog
+/**
+ * Register an ordered prompt section in the calling context's scope. A scoped
+ * section shadows a global section with the same name; duplicates within one
+ * layer and non-finite orders throw. Registration and disposal emit
+ * `system-prompt/change`.
+ * @param section - the section to register.
+ * @returns the exact Cordis effect disposer.
+ */
+section(section: PromptSection): () => void
+
+/**
+ * Register ordered dynamic context in the calling context's scope. Scoped
+ * entries shadow global entries with the same name.
+ * @param context - the context contribution to register.
+ * @returns the exact Cordis effect disposer.
+ */
+context(context: PromptContext): () => void
+
+/**
+ * Register a tool-schema provider in the calling context's scope. Global and
+ * matching scoped providers both contribute; returning the reserved
+ * {@link TOOL_ORDER_REST} name makes assembly fail.
+ * @param provider - evaluated for each assembly with its context.
+ * @returns the exact Cordis effect disposer.
+ */
+tools(provider: (context: AssembleContext) => ToolProviderResult): () => void
+
+/**
+ * Register a prompt variable in the calling context's scope. Scoped values
+ * shadow globals; invalid or duplicate names throw. A provider may return
+ * `undefined`, but rendering a section that references that value then fails.
+ * @param name - the `[a-z][a-z0-9_]*` reference name.
+ * @param provider - evaluated for each assembly.
+ * @returns the exact Cordis effect disposer.
+ */
+variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
+
+/**
+ * Assemble global and scoped providers, detach tool parameters, apply
+ * canonical ordering, then run the assembly waterfall. Scoped sections and
+ * variables shadow globals; the returned waterfall value is authoritative.
+ * @param context - the optional scope and plugin-defined assembly fields.
+ * @returns the authoritative post-waterfall assembly.
+ */
+async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
+```
+
+Source: [`packages/core/system-prompt/src/index.ts:314`](../../packages/core/system-prompt/src/index.ts)
+
+<a id="system-prompt-events"></a>
+
+### `system-prompt/*` events
+
+<a id="system-promptassemble--waterfall"></a>
+
+#### `system-prompt/assemble` — waterfall
+
+Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns.
+
+```ts cordis-catalog
+/**
+ * Expert waterfall over the assembled sections, contexts, tools, and variables.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
+ * receive only that scope's assemblies. The returned value is authoritative.
+ * A supplied signal controls only this explicit assembly request and must not
+ * be retained to control later turns.
+ * @param assembly - the mutable assembly built from registered providers.
+ * @param context - the caller's per-assembly context.
+ * @mode waterfall
+ */
+'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts)
+
+<a id="system-promptchange--emit"></a>
+
+#### `system-prompt/change` — emit
+
+Emitted when any prompt provider changes. This registry notification is unfiltered because a global change affects every scope.
+
+```ts cordis-catalog
+/**
+ * Emitted when any prompt provider changes. This registry notification is
+ * unfiltered because a global change affects every scope.
+ * @mode emit
+ */
+'system-prompt/change'(): void
+```
+
+Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/system-prompt/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
index 58920a53df..d28dcc2781 100644
--- a/docs/subsystems/tasks.i18n.yaml
+++ b/docs/subsystems/tasks.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 docs/core-data-structures/tasks.md
-tasks.md: a38055d3ef7aa18e62678f92eb5ac5ae2a09c205
-tasks.zh.md: f34d42e713c3a0c11cbf88d52e573bb100c52493
+#   pnpm run verify-translation-pairing --write docs/subsystems/tasks.md
+tasks.md: 6237607307cbab8511f968ed591e3e3b8b845c6a
+tasks.zh.md: 99a6fcc4f54c1b52e5c6fd393327cc768f064297
diff --git a/docs/subsystems/tasks.md b/docs/subsystems/tasks.md
index a38055d3ef..6237607307 100644
--- a/docs/subsystems/tasks.md
+++ b/docs/subsystems/tasks.md
@@ -152,3 +152,109 @@ interface TaskRead {
 ## Service behavior
 
 The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam defines atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, contained `onTaskDone` listeners, and the `attachSurface` availability fence; [`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) is the process-local implementation. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the seam contract, [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md) for the registry lifecycle, and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing surface.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtasks--taskservice-abstract-seam"></a>
+
+### `ctx.tasks` — `TaskService` (abstract seam)
+
+Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- Registrations outlive producer and control-surface fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
+- Owned-task access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
+- Settlement is first-wins: one terminal record, one round of contained listener notification, and released waiters, even against a late producer outcome.
+- start refuses work while no control surface is attached, so a producer cannot start work that callers cannot collect or stop.
+
+```ts cordis-catalog
+/**
+ * Preflight access, validation, and owner cleanup before starting and
+ * atomically registering work. A throwing starter leaves nothing registered;
+ * after it returns, registration cannot fail. Settlement records the outcome,
+ * notifies listeners, and releases waiters.
+ * @param spec - task identity, owner, and synchronous starter.
+ * @returns the registry-issued `<kind>-N` id.
+ */
+abstract start(spec: TaskStart): TaskId
+
+/**
+ * List caller-owned and unowned tasks in registration order without exposing
+ * another session's labels.
+ * @param caller - reading agent; a non-agent caller sees only unowned tasks.
+ * @returns fresh snapshots.
+ */
+abstract list(caller?: Agent): TaskSnapshot[]
+
+/**
+ * Return a non-consuming snapshot without changing its read cursor or notice
+ * state. Throws for an unknown or foreign task.
+ * @param id - task to look up.
+ * @param caller - reading agent checked against the owner.
+ * @returns a fresh snapshot.
+ */
+abstract get(id: TaskId, caller?: Agent): TaskSnapshot
+
+/**
+ * Read the next stream delta, or the idempotent final output after settlement.
+ * A terminal read marks the task reported. Throws for an unknown or foreign
+ * task.
+ * @param id - task to read.
+ * @param caller - reading agent checked against the owner.
+ * @returns output text and the post-read snapshot.
+ */
+abstract read(id: TaskId, caller?: Agent): TaskRead
+
+/**
+ * Request cancellation, then mark the task stopping and reported. A producer
+ * throw propagates without changing task state. Throws for an unknown or
+ * foreign task.
+ * @param id - task to cancel.
+ * @param caller - killing agent checked against the owner.
+ * @param reason - logged reason forwarded to the producer.
+ * @returns `requested` for live work, otherwise `already-finished`.
+ */
+abstract kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
+
+/**
+ * Wait for settlement or timeout without cancelling the task. Caller abort
+ * rejects only while the task is live; after settlement the terminal
+ * snapshot wins so a notice suppressed for this waiter is still delivered.
+ * Throws for invalid, unknown, or foreign input.
+ * @param id - task to wait for.
+ * @param timeoutMs - positive finite wait bound in milliseconds.
+ * @param caller - waiting agent checked against the owner.
+ * @param signal - optional cancellation of the wait itself.
+ * @returns snapshot at settlement or timeout.
+ */
+abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
+
+/**
+ * Register an effect-scoped completion listener. Each listener is contained;
+ * returned promises are observed but not awaited. No listener runs after
+ * service disposal.
+ * @param listener - receives each terminal snapshot and its exact owner.
+ * @returns disposer that unregisters the listener.
+ */
+abstract onTaskDone(listener: TaskDoneListener): () => void
+
+/**
+ * Attach an effect-scoped surface that can read and stop tasks. {@link start}
+ * refuses work while none is attached.
+ * @param name - diagnostic label; duplicate names remain independent.
+ * @returns disposer that detaches this surface.
+ */
+abstract attachSurface(name: string): () => void
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tasks.zh.md b/docs/subsystems/tasks.zh.md
index f34d42e713..99a6fcc4f5 100644
--- a/docs/subsystems/tasks.zh.md
+++ b/docs/subsystems/tasks.zh.md
@@ -152,3 +152,109 @@ interface TaskRead {
 ## 服务行为
 
 抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam 定义原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 监听器，以及 `attachSurface` 可用性防线；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部实现。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。seam 契约见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的接口见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtasks--taskservice-abstract-seam"></a>
+
+### `ctx.tasks` — `TaskService` (abstract seam)
+
+Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- Registrations outlive producer and control-surface fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
+- Owned-task access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
+- Settlement is first-wins: one terminal record, one round of contained listener notification, and released waiters, even against a late producer outcome.
+- start refuses work while no control surface is attached, so a producer cannot start work that callers cannot collect or stop.
+
+```ts cordis-catalog
+/**
+ * Preflight access, validation, and owner cleanup before starting and
+ * atomically registering work. A throwing starter leaves nothing registered;
+ * after it returns, registration cannot fail. Settlement records the outcome,
+ * notifies listeners, and releases waiters.
+ * @param spec - task identity, owner, and synchronous starter.
+ * @returns the registry-issued `<kind>-N` id.
+ */
+abstract start(spec: TaskStart): TaskId
+
+/**
+ * List caller-owned and unowned tasks in registration order without exposing
+ * another session's labels.
+ * @param caller - reading agent; a non-agent caller sees only unowned tasks.
+ * @returns fresh snapshots.
+ */
+abstract list(caller?: Agent): TaskSnapshot[]
+
+/**
+ * Return a non-consuming snapshot without changing its read cursor or notice
+ * state. Throws for an unknown or foreign task.
+ * @param id - task to look up.
+ * @param caller - reading agent checked against the owner.
+ * @returns a fresh snapshot.
+ */
+abstract get(id: TaskId, caller?: Agent): TaskSnapshot
+
+/**
+ * Read the next stream delta, or the idempotent final output after settlement.
+ * A terminal read marks the task reported. Throws for an unknown or foreign
+ * task.
+ * @param id - task to read.
+ * @param caller - reading agent checked against the owner.
+ * @returns output text and the post-read snapshot.
+ */
+abstract read(id: TaskId, caller?: Agent): TaskRead
+
+/**
+ * Request cancellation, then mark the task stopping and reported. A producer
+ * throw propagates without changing task state. Throws for an unknown or
+ * foreign task.
+ * @param id - task to cancel.
+ * @param caller - killing agent checked against the owner.
+ * @param reason - logged reason forwarded to the producer.
+ * @returns `requested` for live work, otherwise `already-finished`.
+ */
+abstract kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
+
+/**
+ * Wait for settlement or timeout without cancelling the task. Caller abort
+ * rejects only while the task is live; after settlement the terminal
+ * snapshot wins so a notice suppressed for this waiter is still delivered.
+ * Throws for invalid, unknown, or foreign input.
+ * @param id - task to wait for.
+ * @param timeoutMs - positive finite wait bound in milliseconds.
+ * @param caller - waiting agent checked against the owner.
+ * @param signal - optional cancellation of the wait itself.
+ * @returns snapshot at settlement or timeout.
+ */
+abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
+
+/**
+ * Register an effect-scoped completion listener. Each listener is contained;
+ * returned promises are observed but not awaited. No listener runs after
+ * service disposal.
+ * @param listener - receives each terminal snapshot and its exact owner.
+ * @returns disposer that unregisters the listener.
+ */
+abstract onTaskDone(listener: TaskDoneListener): () => void
+
+/**
+ * Attach an effect-scoped surface that can read and stop tasks. {@link start}
+ * refuses work while none is attached.
+ * @param name - diagnostic label; duplicate names remain independent.
+ * @returns disposer that detaches this surface.
+ */
+abstract attachSurface(name: string): () => void
+```
+
+Types: [Agent](core.md)
+
+Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index 2eb634bb2d..19cd6f6851 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: cf570723650c32f048ee797923a58f09c777455d
-telemetry.zh.md: 1bcaa86264e3afd741d66d6ee718946e6151496f
+telemetry.md: 131c5814f29d70c356989e62fda1db5c1c5448d6
+telemetry.zh.md: 5d4a9d9994457bc06a9e4194c4807f88789a3cf0
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index cf57072365..131c5814f2 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -105,8 +105,76 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry` (`ctx.telemetry`, [signatures](../cordis-catalog/services.md#ctxtelemetry--telemetry-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
+`Telemetry` (`ctx.telemetry`, [signatures](#ctxtelemetry--telemetry-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
 
 ## The redact waterfall: `telemetry/record`
 
-Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics) between projection and `emit()` ([event entry](../cordis-catalog/events.md#telemetryrecord--waterfall)). The seam ships NO rules of its own: with no listener mounted, records reach the backend exactly as captured, so exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath; a throwing listener withholds that one record fail-closed inside the coordinator's containment. Redaction applies to the exported copy only — the canonical session log is never rewritten.
+Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics) between projection and `emit()` ([event entry](#telemetryrecord--waterfall)). The seam ships NO rules of its own: with no listener mounted, records reach the backend exactly as captured, so exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath; a throwing listener withholds that one record fail-closed inside the coordinator's containment. Redaction applies to the exported copy only — the canonical session log is never rewritten.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtelemetry--telemetry-abstract-seam"></a>
+
+### `ctx.telemetry` — `Telemetry` (abstract seam)
+
+The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
+
+```ts cordis-catalog
+/**
+ * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+ * @param record - the logical record to report; owned by the backend after the call.
+ */
+abstract emit(record: TelemetryRecord): void
+
+/** See {@link TelemetryBackend.flush}. */
+flush?(): void
+
+/**
+ * See {@link TelemetryBackend.shutdown}.
+ * @returns resolves when the backend's pipeline has quiesced.
+ */
+abstract shutdown(): Promise<void>
+```
+
+Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/session/session-telemetry/src/index.ts)
+
+<a id="telemetry-events"></a>
+
+### `telemetry/*` events
+
+<a id="telemetryrecord--waterfall"></a>
+
+#### `telemetry/record` — waterfall
+
+Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+
+```ts cordis-catalog
+/**
+ * Transform one outbound record before it reaches the backend. This
+ * waterfall is the seam's redaction extension point. It ships NO rules
+ * of its own: the
+ * innermost `next()` passes the record through unchanged, and with no
+ * listener mounted records reach the backend as captured, so exported
+ * data is exactly as clean as the rules a deployment mounts. Listeners
+ * stack by transforming `next()`'s return value; returning without
+ * `next()` replaces everything beneath. Dispatched synchronously on the
+ * capture hot path inside the coordinator's containment: a throwing
+ * listener withholds that one record (fail-closed) and never reaches the
+ * agent loop. Live capture dispatches at append time; on-demand capture
+ * dispatches while reading the canonical log. Redaction applies to the
+ * exported copy only; the canonical session log is never rewritten.
+ * @param record - the candidate record, already the coordinator's own deep
+ *   copy; listeners return a (possibly new) record and must not mutate it.
+ * @mode waterfall
+ */
+'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
+```
+
+Source: [`packages/session/session-telemetry/src/index.ts:43`](../../packages/session/session-telemetry/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 1bcaa86264..5d4a9d9994 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -105,8 +105,76 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry`（`ctx.telemetry`，[签名](../cordis-catalog/services.md#ctxtelemetry--telemetry-abstract-seam)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
+`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry-abstract-seam)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
 
 ## 脱敏 waterfall：`telemetry/record`
 
-每条记录在投影与 `emit()` 之间都要经过 `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics)（[事件条目](../cordis-catalog/events.md#telemetryrecord--waterfall)）。seam 自身不带任何规则：未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式扣下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
+每条记录在投影与 `emit()` 之间都要经过 `telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics)（[事件条目](#telemetryrecord--waterfall)）。seam 自身不带任何规则：未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式扣下这一条记录。脱敏只作用于导出副本；权威会话日志永不改写。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtelemetry--telemetry-abstract-seam"></a>
+
+### `ctx.telemetry` — `Telemetry` (abstract seam)
+
+The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
+
+```ts cordis-catalog
+/**
+ * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+ * @param record - the logical record to report; owned by the backend after the call.
+ */
+abstract emit(record: TelemetryRecord): void
+
+/** See {@link TelemetryBackend.flush}. */
+flush?(): void
+
+/**
+ * See {@link TelemetryBackend.shutdown}.
+ * @returns resolves when the backend's pipeline has quiesced.
+ */
+abstract shutdown(): Promise<void>
+```
+
+Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/session/session-telemetry/src/index.ts)
+
+<a id="telemetry-events"></a>
+
+### `telemetry/*` events
+
+<a id="telemetryrecord--waterfall"></a>
+
+#### `telemetry/record` — waterfall
+
+Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+
+```ts cordis-catalog
+/**
+ * Transform one outbound record before it reaches the backend. This
+ * waterfall is the seam's redaction extension point. It ships NO rules
+ * of its own: the
+ * innermost `next()` passes the record through unchanged, and with no
+ * listener mounted records reach the backend as captured, so exported
+ * data is exactly as clean as the rules a deployment mounts. Listeners
+ * stack by transforming `next()`'s return value; returning without
+ * `next()` replaces everything beneath. Dispatched synchronously on the
+ * capture hot path inside the coordinator's containment: a throwing
+ * listener withholds that one record (fail-closed) and never reaches the
+ * agent loop. Live capture dispatches at append time; on-demand capture
+ * dispatches while reading the canonical log. Redaction applies to the
+ * exported copy only; the canonical session log is never rewritten.
+ * @param record - the candidate record, already the coordinator's own deep
+ *   copy; listeners return a (possibly new) record and must not mutate it.
+ * @mode waterfall
+ */
+'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
+```
+
+Source: [`packages/session/session-telemetry/src/index.ts:43`](../../packages/session/session-telemetry/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/token-meter.i18n.yaml b/docs/subsystems/token-meter.i18n.yaml
index 3f58d10153..e348aca7a0 100644
--- a/docs/subsystems/token-meter.i18n.yaml
+++ b/docs/subsystems/token-meter.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 docs/core-data-structures/token-meter.md
-token-meter.md: 05784e294485a11acf0e4c8972e4083b1786c943
-token-meter.zh.md: 0474d86188a111014e6d72e9962121c08a228d73
+#   pnpm run verify-translation-pairing --write docs/subsystems/token-meter.md
+token-meter.md: 0f53955b3e6afce84520314f4de453edaa897158
+token-meter.zh.md: 3ba22c54d599982d3f7bdbcb9160b6ffc3255e07
diff --git a/docs/subsystems/token-meter.md b/docs/subsystems/token-meter.md
index 05784e2944..0f53955b3e 100644
--- a/docs/subsystems/token-meter.md
+++ b/docs/subsystems/token-meter.md
@@ -41,3 +41,50 @@ interface TokenSurfaceNode {
 ```
 
 Surface order is authoritative; replacement nodes can have higher durable seqs than later positional nodes. The snapshot is immutable and does not grow when the underlying replay fold advances.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtokenmeter--tokenmeterservice"></a>
+
+### `ctx.tokenMeter` — `TokenMeterService`
+
+Replay owner for one service-wide estimator and isolated per-session folds.
+
+```ts cordis-catalog
+/**
+ * Measure current request pressure and surface through the durable tail.
+ *
+ * Provider usage is reused only when the latest successful call's canonical
+ * request envelope matches `requestHeader` and its total is no lower than
+ * that call's full heuristic anchor; otherwise the complete envelope and
+ * surface are heuristically repriced.
+ *
+ * `requestHeader` affects request pressure only; surface fields always
+ * describe the current session surface. Every call clones those positional
+ * nodes, so measurement is O(surface).
+ *
+ * @param session - session to replay through its current durable tail.
+ * @param requestHeader - optional effective request envelope replacing the latest logged header.
+ * @returns a detached deeply immutable pressure and surface measurement.
+ */
+measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
+
+/**
+ * Heuristically price one model-visible message (instance face of the pure
+ * `estimateMessage` export from `estimate.ts`).
+ * @param message - message to price without mutation.
+ * @returns content and role-framing tokens under the fixed service heuristic.
+ */
+estimateMessage(message: Message): number
+```
+
+Types: [EpochHeader](session.md) · [Message](core.md) · [Session](session.md)
+
+Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/token-meter.zh.md b/docs/subsystems/token-meter.zh.md
index 0474d86188..3ba22c54d5 100644
--- a/docs/subsystems/token-meter.zh.md
+++ b/docs/subsystems/token-meter.zh.md
@@ -41,3 +41,50 @@ interface TokenSurfaceNode {
 ```
 
 表层顺序具有权威性；替换节点的持久 seq 可能高于位置排在其后的节点。该快照不可变，不会随底层回放折叠推进而增长。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtokenmeter--tokenmeterservice"></a>
+
+### `ctx.tokenMeter` — `TokenMeterService`
+
+Replay owner for one service-wide estimator and isolated per-session folds.
+
+```ts cordis-catalog
+/**
+ * Measure current request pressure and surface through the durable tail.
+ *
+ * Provider usage is reused only when the latest successful call's canonical
+ * request envelope matches `requestHeader` and its total is no lower than
+ * that call's full heuristic anchor; otherwise the complete envelope and
+ * surface are heuristically repriced.
+ *
+ * `requestHeader` affects request pressure only; surface fields always
+ * describe the current session surface. Every call clones those positional
+ * nodes, so measurement is O(surface).
+ *
+ * @param session - session to replay through its current durable tail.
+ * @param requestHeader - optional effective request envelope replacing the latest logged header.
+ * @returns a detached deeply immutable pressure and surface measurement.
+ */
+measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
+
+/**
+ * Heuristically price one model-visible message (instance face of the pure
+ * `estimateMessage` export from `estimate.ts`).
+ * @param message - message to price without mutation.
+ * @returns content and role-framing tokens under the fixed service heuristic.
+ */
+estimateMessage(message: Message): number
+```
+
+Types: [EpochHeader](session.md) · [Message](core.md) · [Session](session.md)
+
+Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index a30f122038..8b0aa47c9a 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: 853eed16cff451edcc32bc3aa5c6bc7cabb0f518
-tools.zh.md: ec8809f6bebd185404828c5c5879f8eff832ea9a
+tools.md: 5d72bd54f0dc5995218087030f24c467c8ccbb38
+tools.zh.md: 2340d4c2d92c51aa9cc89f4694b626c76d05140b
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index 853eed16cf..5d72bd54f0 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -455,3 +455,241 @@ How a tool wants its call shown in a UI (an editor tool-call card, a CLI log lin
 `ToolCallKind` (`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`) picks an icon on a generic card. `FileLocation` (`{ path, line? }`), `FileDiff` (`{ path, oldText, newText }`), and `ReadFileLine` (`{ number, text }`, one 1-based numbered line of a read window) are the shared file-card vocabulary. The design is pinned in [the render-intent-union Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md); host/client runtimes project this neutral vocabulary into their own views.
 
 The full presentation field docs live in [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts). The `bash` schema and executor are on [bash.md](bash.md); generic background controls are on [tasks.md](tasks.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtools--toolregistry"></a>
+
+### `ctx.tools` — `ToolRegistry`
+
+Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.
+
+```ts cordis-catalog
+/**
+ * Register globally or in the calling agent scope. Scoped tools shadow
+ * globals; duplicates within one layer and the reserved `run_code` name fail.
+ * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
+ * @returns the exact disposer that unregisters the tool.
+ */
+register(definition: ToolDefinition): () => void
+
+/**
+ * Restrict global tools for the calling agent scope. Empty filters, unknown
+ * names, scope-local names, and reserved transport names fail. Restrictions
+ * intersect; scoped registrations remain visible.
+ * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
+ * @returns the exact disposer that lifts this restriction.
+ */
+restrict(filter: ToolRestriction): () => void
+
+/**
+ * Register a monotonic guard after the extensible `tools/pre-execute`
+ * waterfall. A plain-context guard applies globally; one registered through
+ * `agent.ctx` applies only to that agent. Any matching guard may deny by
+ * returning a reason, while no guard can force-allow a call another guard
+ * denied. The exact effect disposer is returned for ordered ownership and
+ * HMR cleanup.
+ * @param guard - synchronous check; a returned string denies the execution.
+ * @returns the exact disposer that unregisters the guard.
+ */
+guard(guard: ToolGuard): () => void
+
+/**
+ * Look up a tool as one scope sees it (scoped
+ * shadows global; a restricted-away global reads as absent). Presenters pass
+ * the calling agent so the rendered card matches the definition that
+ * actually executed.
+ * @param name - the tool name as registered.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns the definition the scope resolves, or undefined when none is visible.
+ */
+get(name: string, scope?: ScopeKey): ToolDefinition | undefined
+
+/**
+ * Project visible definitions onto the allowlisted model-facing schema fields,
+ * excluding execution and presentation callbacks.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns one deep-cloned schema per visible tool.
+ */
+schemas(scope?: ScopeKey): ToolSchema[]
+
+/**
+ * Classify a pending call through the caller's visible tool definition. Only
+ * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
+ * throwing classifiers are exclusive.
+ * @param exec - call name, parsed arguments, and optional agent scope.
+ * @returns the fail-closed scheduling mode.
+ */
+executionMode(exec: ToolExecutionInput): ToolExecutionMode
+
+/**
+ * Execute through pre-policy, guards, around-dispatch, post-policy,
+ * definition-owned content finalization, and final notification. Tool and
+ * listener failures resolve as materialized error results; an invisible tool
+ * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen
+ * snapshot final observers receive. Cancellation
+ * arriving after entry and before final result materialization skips a
+ * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a
+ * successful started outcome with `ABORTED`; already-started work is still
+ * drained and may retain a tool-owned structured error.
+ * @param exec - the typed same-process call input. The registry assigns its
+ *   correlation token before policy begins.
+ * @returns the materialized final result.
+ */
+async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
+```
+
+Types: [ScopeKey](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
+
+<a id="tools-events"></a>
+
+### `tools/*` events
+
+<a id="toolschange--emit"></a>
+
+#### `tools/change` — emit
+
+A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed — possibly for one scope only). An UNFILTERED registry-subject notification, deliberately not scope-filtered dispatch: a global change concerns every agent's next assembly, so a scoped listener subscribing here sees every change, not just its own scope's.
+
+```ts cordis-catalog
+/**
+ * A tool was registered or unregistered, or a scoped restriction changed
+ * (the available tool set changed — possibly for one scope only). An
+ * UNFILTERED registry-subject notification, deliberately not scope-filtered
+ * dispatch: a global change concerns every agent's next assembly, so a
+ * scoped listener subscribing here sees every change, not just its own
+ * scope's.
+ * @mode emit
+ */
+'tools/change'(): void
+```
+
+Source: [`packages/core/tools/src/index.ts:191`](../../packages/core/tools/src/index.ts)
+
+<a id="toolscode-dispatch-log--waterfall"></a>
+
+#### `tools/code-dispatch-log` — waterfall
+
+Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bridge appends its `tool/code-dispatch` event. `next()` keeps the content unchanged; a listener may return replacement blocks (e.g. the spill policy's preview + locator for an oversized text result). Only the logged copy is affected — the program already received the complete value, and the model sees neither. A throwing listener is contained: the bridge falls back to logging the unshaped content. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
+
+```ts cordis-catalog
+/**
+ * Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before
+ * the bridge appends its `tool/code-dispatch` event. `next()` keeps the
+ * content unchanged; a listener may return replacement blocks (e.g. the
+ * spill policy's preview + locator for an oversized text result). Only the
+ * logged copy is affected — the program already received the complete
+ * value, and the model sees neither. A throwing listener is contained:
+ * the bridge falls back to logging the unshaped content.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
+ * @param dispatch - the parent execution, sub-call identity, and the settled content to log.
+ * @mode waterfall
+ */
+'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
+```
+
+Types: [ContentBlock](core.md) · [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
+
+<a id="toolsexecute--waterfall"></a>
+
+#### `tools/execute` — waterfall
+
+Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a normalized result; wrappers may change only `exec.signal`, while call identity remains immutable. The registry re-fuses the original caller signal before the body, so replacement cannot detach caller cancellation; wrappers must still restore their signal and reach quiescence. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
+ * a normalized result; wrappers may change only `exec.signal`, while call
+ * identity remains immutable. The registry re-fuses the original caller
+ * signal before the body, so replacement cannot detach caller cancellation;
+ * wrappers must still restore their signal and reach quiescence.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
+ * @mode waterfall
+ */
+'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
+
+<a id="toolspost-execute--waterfall"></a>
+
+#### `tools/post-execute` — waterfall
+
+Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this seam as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Accept, replace, enrich, or block a normalized dispatch result. `next()`
+ * accepts it unchanged; thrown tools still reach this seam as errors. Async
+ * listeners must observe `exec.signal`; after they settle, caller
+ * cancellation replaces only a successful accepted outcome with the code
+ * selected by whether the tool body was invoked.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the call that just ran (name, parsed arguments, caller agent).
+ * @param result - the dispatch outcome a listener may accept, replace, or block.
+ * @mode waterfall
+ */
+'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
+
+<a id="toolspre-execute--waterfall"></a>
+
+#### `tools/pre-execute` — waterfall
+
+Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approval support turns `ask` into denial. Async gates must observe `exec.signal`; the registry rechecks cancellation after they settle but never abandons their promise. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
+ * approval support turns `ask` into denial. Async gates must observe
+ * `exec.signal`; the registry rechecks cancellation after they settle but
+ * never abandons their promise.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the pending call (name, parsed arguments, caller agent).
+ * @mode waterfall
+ */
+'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
+
+<a id="toolsresult--emit"></a>
+
+#### `tools/result` — emit
+
+Observe the frozen, lossless-JSON final outcome. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+
+```ts cordis-catalog
+/**
+ * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+ * @param exec - the execution object that traversed the pipeline.
+ * @param result - a deep-frozen snapshot of the final returned result.
+ * @mode emit
+ */
+'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index ec8809f6be..2340d4c2d9 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -455,3 +455,241 @@ type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
 `ToolCallKind`（`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`）用于为通用卡片选择图标。`FileLocation`（`{ path, line? }`）、`FileDiff`（`{ path, oldText, newText }`）与 `ReadFileLine`（`{ number, text }`，读取窗口中一行带 1-based 行号的内容）是共享的文件卡片词汇。该设计由[渲染意图联合类型 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md)固定；host/client 运行时将这套中性词汇投影为各自的视图。
 
 完整的展示字段文档见 [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)。`bash` schema 与执行器见 [bash.md](bash.md)；通用后台控制见 [tasks.md](tasks.md)。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtools--toolregistry"></a>
+
+### `ctx.tools` — `ToolRegistry`
+
+Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.
+
+```ts cordis-catalog
+/**
+ * Register globally or in the calling agent scope. Scoped tools shadow
+ * globals; duplicates within one layer and the reserved `run_code` name fail.
+ * @param definition - tool schema, execution, and optional finalization/presentation callbacks.
+ * @returns the exact disposer that unregisters the tool.
+ */
+register(definition: ToolDefinition): () => void
+
+/**
+ * Restrict global tools for the calling agent scope. Empty filters, unknown
+ * names, scope-local names, and reserved transport names fail. Restrictions
+ * intersect; scoped registrations remain visible.
+ * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
+ * @returns the exact disposer that lifts this restriction.
+ */
+restrict(filter: ToolRestriction): () => void
+
+/**
+ * Register a monotonic guard after the extensible `tools/pre-execute`
+ * waterfall. A plain-context guard applies globally; one registered through
+ * `agent.ctx` applies only to that agent. Any matching guard may deny by
+ * returning a reason, while no guard can force-allow a call another guard
+ * denied. The exact effect disposer is returned for ordered ownership and
+ * HMR cleanup.
+ * @param guard - synchronous check; a returned string denies the execution.
+ * @returns the exact disposer that unregisters the guard.
+ */
+guard(guard: ToolGuard): () => void
+
+/**
+ * Look up a tool as one scope sees it (scoped
+ * shadows global; a restricted-away global reads as absent). Presenters pass
+ * the calling agent so the rendered card matches the definition that
+ * actually executed.
+ * @param name - the tool name as registered.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns the definition the scope resolves, or undefined when none is visible.
+ */
+get(name: string, scope?: ScopeKey): ToolDefinition | undefined
+
+/**
+ * Project visible definitions onto the allowlisted model-facing schema fields,
+ * excluding execution and presentation callbacks.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns one deep-cloned schema per visible tool.
+ */
+schemas(scope?: ScopeKey): ToolSchema[]
+
+/**
+ * Classify a pending call through the caller's visible tool definition. Only
+ * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
+ * throwing classifiers are exclusive.
+ * @param exec - call name, parsed arguments, and optional agent scope.
+ * @returns the fail-closed scheduling mode.
+ */
+executionMode(exec: ToolExecutionInput): ToolExecutionMode
+
+/**
+ * Execute through pre-policy, guards, around-dispatch, post-policy,
+ * definition-owned content finalization, and final notification. Tool and
+ * listener failures resolve as materialized error results; an invisible tool
+ * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen
+ * snapshot final observers receive. Cancellation
+ * arriving after entry and before final result materialization skips a
+ * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a
+ * successful started outcome with `ABORTED`; already-started work is still
+ * drained and may retain a tool-owned structured error.
+ * @param exec - the typed same-process call input. The registry assigns its
+ *   correlation token before policy begins.
+ * @returns the materialized final result.
+ */
+async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
+```
+
+Types: [ScopeKey](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
+
+<a id="tools-events"></a>
+
+### `tools/*` events
+
+<a id="toolschange--emit"></a>
+
+#### `tools/change` — emit
+
+A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed — possibly for one scope only). An UNFILTERED registry-subject notification, deliberately not scope-filtered dispatch: a global change concerns every agent's next assembly, so a scoped listener subscribing here sees every change, not just its own scope's.
+
+```ts cordis-catalog
+/**
+ * A tool was registered or unregistered, or a scoped restriction changed
+ * (the available tool set changed — possibly for one scope only). An
+ * UNFILTERED registry-subject notification, deliberately not scope-filtered
+ * dispatch: a global change concerns every agent's next assembly, so a
+ * scoped listener subscribing here sees every change, not just its own
+ * scope's.
+ * @mode emit
+ */
+'tools/change'(): void
+```
+
+Source: [`packages/core/tools/src/index.ts:191`](../../packages/core/tools/src/index.ts)
+
+<a id="toolscode-dispatch-log--waterfall"></a>
+
+#### `tools/code-dispatch-log` — waterfall
+
+Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bridge appends its `tool/code-dispatch` event. `next()` keeps the content unchanged; a listener may return replacement blocks (e.g. the spill policy's preview + locator for an oversized text result). Only the logged copy is affected — the program already received the complete value, and the model sees neither. A throwing listener is contained: the bridge falls back to logging the unshaped content. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
+
+```ts cordis-catalog
+/**
+ * Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before
+ * the bridge appends its `tool/code-dispatch` event. `next()` keeps the
+ * content unchanged; a listener may return replacement blocks (e.g. the
+ * spill policy's preview + locator for an oversized text result). Only the
+ * logged copy is affected — the program already received the complete
+ * value, and the model sees neither. A throwing listener is contained:
+ * the bridge falls back to logging the unshaped content.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
+ * @param dispatch - the parent execution, sub-call identity, and the settled content to log.
+ * @mode waterfall
+ */
+'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
+```
+
+Types: [ContentBlock](core.md) · [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
+
+<a id="toolsexecute--waterfall"></a>
+
+#### `tools/execute` — waterfall
+
+Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a normalized result; wrappers may change only `exec.signal`, while call identity remains immutable. The registry re-fuses the original caller signal before the body, so replacement cannot detach caller cancellation; wrappers must still restore their signal and reach quiescence. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
+ * a normalized result; wrappers may change only `exec.signal`, while call
+ * identity remains immutable. The registry re-fuses the original caller
+ * signal before the body, so replacement cannot detach caller cancellation;
+ * wrappers must still restore their signal and reach quiescence.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
+ * @mode waterfall
+ */
+'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
+
+<a id="toolspost-execute--waterfall"></a>
+
+#### `tools/post-execute` — waterfall
+
+Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this seam as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Accept, replace, enrich, or block a normalized dispatch result. `next()`
+ * accepts it unchanged; thrown tools still reach this seam as errors. Async
+ * listeners must observe `exec.signal`; after they settle, caller
+ * cancellation replaces only a successful accepted outcome with the code
+ * selected by whether the tool body was invoked.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the call that just ran (name, parsed arguments, caller agent).
+ * @param result - the dispatch outcome a listener may accept, replace, or block.
+ * @mode waterfall
+ */
+'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
+
+<a id="toolspre-execute--waterfall"></a>
+
+#### `tools/pre-execute` — waterfall
+
+Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approval support turns `ask` into denial. Async gates must observe `exec.signal`; the registry rechecks cancellation after they settle but never abandons their promise. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+
+```ts cordis-catalog
+/**
+ * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
+ * approval support turns `ask` into denial. Async gates must observe
+ * `exec.signal`; the registry rechecks cancellation after they settle but
+ * never abandons their promise.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the pending call (name, parsed arguments, caller agent).
+ * @mode waterfall
+ */
+'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
+
+<a id="toolsresult--emit"></a>
+
+#### `tools/result` — emit
+
+Observe the frozen, lossless-JSON final outcome. Listener failures are contained. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+
+```ts cordis-catalog
+/**
+ * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+ * @param exec - the execution object that traversed the pipeline.
+ * @param result - a deep-frozen snapshot of the final returned result.
+ * @mode emit
+ */
+'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml
index 75b7837687..b8fdb092f2 100644
--- a/docs/subsystems/typert.i18n.yaml
+++ b/docs/subsystems/typert.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 docs/core-data-structures/typert.md
-typert.md: c70e50e2fea8455eb75dfdf8c309f659ab9cb2f9
-typert.zh.md: 2cd1636d4cc8dbcfa009073b4a8e1dcc8d5897e4
+#   pnpm run verify-translation-pairing --write docs/subsystems/typert.md
+typert.md: 8ce52837ceee8e9c8c4a61de28f972912faa2cf0
+typert.zh.md: ff6b45a517c75392ee87fa348d72bfae6cdf1efb
diff --git a/docs/subsystems/typert.md b/docs/subsystems/typert.md
index c70e50e2fe..8ce52837ce 100644
--- a/docs/subsystems/typert.md
+++ b/docs/subsystems/typert.md
@@ -201,3 +201,96 @@ interface TypeRTClientRemote extends TypeRTRemoteNamespaceMap {
   $mount(contribution: TypeRTRemoteContribution): Promise<TypeRTDisposer>
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtypert--typertregistry"></a>
+
+### `ctx.typert` — `TypertRegistry`
+
+Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
+
+```ts cordis-catalog
+/**
+ * Register one generated contribution atomically for the calling fiber.
+ * Duplicate package-face identities, schemas, invocation ids, or endpoints
+ * reject the whole batch.
+ * @param contribution - generated schemas, reflection, and Host invocations.
+ * @returns the exact effect disposer that removes this contribution.
+ */
+register(contribution: TypertContribution): TypeRTDisposer
+
+/**
+ * Look up one schema by `<package>#<name>`.
+ * @param key - global schema key.
+ * @returns the live schema record, or `undefined` when absent.
+ */
+get(key: string): TypertSchemaRecord | undefined
+
+/**
+ * Resolve one required schema.
+ * @param key - global schema key.
+ * @returns the live schema record.
+ * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
+ */
+resolve(key: string): TypertSchemaRecord
+
+/**
+ * Enumerate live schemas in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching schema records.
+ */
+list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
+
+/**
+ * Look up generated reflection for one package face.
+ * @param packageName - exact npm package name.
+ * @param face - face to query; defaults to the host runtime.
+ * @returns the live package record, or `undefined` when absent.
+ */
+getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
+
+/**
+ * Enumerate generated package reflection in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching package records.
+ */
+listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
+
+/**
+ * Project a live Zod schema to JSON Schema without caching the result.
+ * @param key - global schema key.
+ * @param params - Zod projection parameters.
+ * @returns a fresh JSON Schema document.
+ */
+toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
+```
+
+Types: [TypertContribution](invariants.md) · [TypertFace](invariants.md) · [TypertPackageFilter](invariants.md) · [TypertPackageRecord](invariants.md) · [TypertSchemaFilter](invariants.md) · [TypertSchemaRecord](invariants.md)
+
+Source: [`packages/typert/registry/src/service.ts:446`](../../packages/typert/registry/src/service.ts)
+
+<a id="ctxtypertgateway--typertgatewayservice"></a>
+
+### `ctx.typertGateway` — `TypertGatewayService`
+
+Resolve strict generated definitions or conservative SRC markers against current Cordis Services and TypeRT providers.
+
+```ts cordis-catalog
+/**
+ * Invoke one live Remote method through strict generated reflection or SRC markers.
+ * @param request - decoded endpoint and exact named wire arguments.
+ * @returns the validated business result.
+ * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
+ */
+async invoke(request: InvokeRemoteRequest): Promise<unknown>
+```
+
+Source: [`packages/api/gateway/src/index.ts:78`](../../packages/api/gateway/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md
index 2cd1636d4c..ff6b45a517 100644
--- a/docs/subsystems/typert.zh.md
+++ b/docs/subsystems/typert.zh.md
@@ -201,3 +201,96 @@ interface TypeRTClientRemote extends TypeRTRemoteNamespaceMap {
   $mount(contribution: TypeRTRemoteContribution): Promise<TypeRTDisposer>
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxtypert--typertregistry"></a>
+
+### `ctx.typert` — `TypertRegistry`
+
+Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
+
+```ts cordis-catalog
+/**
+ * Register one generated contribution atomically for the calling fiber.
+ * Duplicate package-face identities, schemas, invocation ids, or endpoints
+ * reject the whole batch.
+ * @param contribution - generated schemas, reflection, and Host invocations.
+ * @returns the exact effect disposer that removes this contribution.
+ */
+register(contribution: TypertContribution): TypeRTDisposer
+
+/**
+ * Look up one schema by `<package>#<name>`.
+ * @param key - global schema key.
+ * @returns the live schema record, or `undefined` when absent.
+ */
+get(key: string): TypertSchemaRecord | undefined
+
+/**
+ * Resolve one required schema.
+ * @param key - global schema key.
+ * @returns the live schema record.
+ * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
+ */
+resolve(key: string): TypertSchemaRecord
+
+/**
+ * Enumerate live schemas in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching schema records.
+ */
+list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
+
+/**
+ * Look up generated reflection for one package face.
+ * @param packageName - exact npm package name.
+ * @param face - face to query; defaults to the host runtime.
+ * @returns the live package record, or `undefined` when absent.
+ */
+getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
+
+/**
+ * Enumerate generated package reflection in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching package records.
+ */
+listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
+
+/**
+ * Project a live Zod schema to JSON Schema without caching the result.
+ * @param key - global schema key.
+ * @param params - Zod projection parameters.
+ * @returns a fresh JSON Schema document.
+ */
+toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
+```
+
+Types: [TypertContribution](invariants.md) · [TypertFace](invariants.md) · [TypertPackageFilter](invariants.md) · [TypertPackageRecord](invariants.md) · [TypertSchemaFilter](invariants.md) · [TypertSchemaRecord](invariants.md)
+
+Source: [`packages/typert/registry/src/service.ts:446`](../../packages/typert/registry/src/service.ts)
+
+<a id="ctxtypertgateway--typertgatewayservice"></a>
+
+### `ctx.typertGateway` — `TypertGatewayService`
+
+Resolve strict generated definitions or conservative SRC markers against current Cordis Services and TypeRT providers.
+
+```ts cordis-catalog
+/**
+ * Invoke one live Remote method through strict generated reflection or SRC markers.
+ * @param request - decoded endpoint and exact named wire arguments.
+ * @returns the validated business result.
+ * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
+ */
+async invoke(request: InvokeRemoteRequest): Promise<unknown>
+```
+
+Source: [`packages/api/gateway/src/index.ts:78`](../../packages/api/gateway/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/user-interaction.i18n.yaml b/docs/subsystems/user-interaction.i18n.yaml
index 80ebb810c8..342cf9b9f7 100644
--- a/docs/subsystems/user-interaction.i18n.yaml
+++ b/docs/subsystems/user-interaction.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 docs/subsystems/user-interaction.md
-user-interaction.md: ec22eb28e9554d6454bf2670f73f2e9b199df014
-user-interaction.zh.md: 814f8911e41aecf568f627f76f8239bac4ea719b
+user-interaction.md: a19155ae06af0133ae468c004b2e3b66f1de3fb8
+user-interaction.zh.md: dc5845a976068981b2761e26502eaf7dd95dcb01
diff --git a/docs/subsystems/user-interaction.md b/docs/subsystems/user-interaction.md
index ec22eb28e9..a19155ae06 100644
--- a/docs/subsystems/user-interaction.md
+++ b/docs/subsystems/user-interaction.md
@@ -132,3 +132,47 @@ class UserInteractionError extends HarnessError {
   }
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxuserinteraction--userinteractionservice"></a>
+
+### `ctx.userInteraction` — `UserInteractionService`
+
+`ctx.userInteraction`: one active UI provider plus an `ask()` surface.
+
+```ts cordis-catalog
+/**
+ * Register the UI provider. Only one provider may be active in a context.
+ *
+ * @param provider UI-side implementation that collects answers.
+ * @returns Disposer that unregisters this provider.
+ */
+registerProvider(provider: UserInteractionProvider): () => void
+
+/**
+ * Ask the active UI provider and wait for the user's answer.
+ *
+ * When a caller supplies an agent, human interaction is valid only for the
+ * exact live runtime root. Runtime ownership, not durable session lineage,
+ * decides this boundary: an owned child has no human answerer and would
+ * block forever, while a lineage-bearing session resumed as a new runtime
+ * root may ask normally.
+ *
+ * @param request Questions, owner agent, and abort signal.
+ * @returns The answer chosen or typed by the human.
+ * @throws {UserInteractionError} code `CALLER_NOT_LIVE` when a supplied
+ *   agent is not the registry's exact live instance, or `DELEGATED_CALLER`
+ *   when that live agent is owned by another agent.
+ */
+async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
+```
+
+Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/user-interaction.zh.md b/docs/subsystems/user-interaction.zh.md
index 814f8911e4..dc5845a976 100644
--- a/docs/subsystems/user-interaction.zh.md
+++ b/docs/subsystems/user-interaction.zh.md
@@ -132,3 +132,47 @@ class UserInteractionError extends HarnessError {
   }
 }
 ```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxuserinteraction--userinteractionservice"></a>
+
+### `ctx.userInteraction` — `UserInteractionService`
+
+`ctx.userInteraction`: one active UI provider plus an `ask()` surface.
+
+```ts cordis-catalog
+/**
+ * Register the UI provider. Only one provider may be active in a context.
+ *
+ * @param provider UI-side implementation that collects answers.
+ * @returns Disposer that unregisters this provider.
+ */
+registerProvider(provider: UserInteractionProvider): () => void
+
+/**
+ * Ask the active UI provider and wait for the user's answer.
+ *
+ * When a caller supplies an agent, human interaction is valid only for the
+ * exact live runtime root. Runtime ownership, not durable session lineage,
+ * decides this boundary: an owned child has no human answerer and would
+ * block forever, while a lineage-bearing session resumed as a new runtime
+ * root may ask normally.
+ *
+ * @param request Questions, owner agent, and abort signal.
+ * @returns The answer chosen or typed by the human.
+ * @throws {UserInteractionError} code `CALLER_NOT_LIVE` when a supplied
+ *   agent is not the registry's exact live instance, or `DELEGATED_CALLER`
+ *   when that live agent is owned by another agent.
+ */
+async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
+```
+
+Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
index e8ae658d3a..f3f0ab9758 100644
--- a/docs/subsystems/web.i18n.yaml
+++ b/docs/subsystems/web.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 docs/core-data-structures/web.md
-web.md: 20d07240c9d9fea2f1f5abbac810f349a3e81f9b
-web.zh.md: e2982ba571353752e3a7d10130599e8c8fe941f8
+#   pnpm run verify-translation-pairing --write docs/subsystems/web.md
+web.md: f300bf2daef172fe4a69c00f36c804cf874c189d
+web.zh.md: 0c72e343c1b6ea5de8e7c296014da35b0291a33b
diff --git a/docs/subsystems/web.md b/docs/subsystems/web.md
index 20d07240c9..f300bf2dae 100644
--- a/docs/subsystems/web.md
+++ b/docs/subsystems/web.md
@@ -133,3 +133,70 @@ Selection never depends on registration, config, or HMR order: a capability has
 ## The service
 
 `WebService` registers search and fetch providers, rejects duplicate ids with `WEB_DUPLICATE_PROVIDER`, and resolves providers at execution time with structured selection errors. The local fetch backend accepts only HTTP(S), rejects credentials, caps redirects, bytes, characters, and time, revalidates every same-origin redirect hop, and decodes the body; the tool owns presentation. Private-network blocking is deferred, so do not enable `web_fetch` where it can reach sensitive internal targets.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxweb--webservice"></a>
+
+### `ctx.web` — `WebService`
+
+The web access service. Registered as `ctx.web` (one instance per context).
+
+Selection semantics (resolved at execution time, never order-dependent):
+
+- A configured id that is registered and `available()` → that provider.
+- A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
+- A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
+- No id configured, exactly one registered usable provider → that provider.
+- No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
+- No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
+
+```ts cordis-catalog
+/**
+ * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for search. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
+registerSearchProvider(provider: WebSearchProvider): () => void
+
+/**
+ * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for fetch. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
+registerFetchProvider(provider: WebFetchProvider): () => void
+
+/**
+ * Run one search through the selected provider. Resolves the provider at call
+ * time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. The seam enforces `request.maxResults` on the result:
+ * if the provider over-returns, `sources[]` is truncated and `truncated` set.
+ * @param request - the query plus result-shaping options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the provider's results, capped to `request.maxResults`.
+ */
+async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
+
+/**
+ * Retrieve one URL through the selected provider. Resolves the provider at
+ * call time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. A non-2xx response is a result, not a throw.
+ * @param request - the URL plus retrieval options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the retrieval outcome; non-2xx responses resolve descriptively.
+ */
+async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
+```
+
+Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/web.zh.md b/docs/subsystems/web.zh.md
index e2982ba571..0c72e343c1 100644
--- a/docs/subsystems/web.zh.md
+++ b/docs/subsystems/web.zh.md
@@ -133,3 +133,70 @@ type WebFetchBody =
 ## 服务
 
 `WebService` 注册搜索与抓取提供方，以 `WEB_DUPLICATE_PROVIDER` 拒绝重复 id，并在执行时以结构化的选择错误解析提供方。本地抓取后端仅接受 HTTP(S)、拒绝凭证、限制重定向次数、字节数、字符数和时间、对每一跳同源重定向重新校验，并解码正文；展示由工具负责。SSRF／私有网络防护尚未实现，因此在能够触及敏感内部目标的环境中，禁止启用 `web_fetch`。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxweb--webservice"></a>
+
+### `ctx.web` — `WebService`
+
+The web access service. Registered as `ctx.web` (one instance per context).
+
+Selection semantics (resolved at execution time, never order-dependent):
+
+- A configured id that is registered and `available()` → that provider.
+- A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
+- A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
+- No id configured, exactly one registered usable provider → that provider.
+- No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
+- No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
+
+```ts cordis-catalog
+/**
+ * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for search. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
+registerSearchProvider(provider: WebSearchProvider): () => void
+
+/**
+ * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for fetch. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
+registerFetchProvider(provider: WebFetchProvider): () => void
+
+/**
+ * Run one search through the selected provider. Resolves the provider at call
+ * time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. The seam enforces `request.maxResults` on the result:
+ * if the provider over-returns, `sources[]` is truncated and `truncated` set.
+ * @param request - the query plus result-shaping options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the provider's results, capped to `request.maxResults`.
+ */
+async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
+
+/**
+ * Retrieve one URL through the selected provider. Resolves the provider at
+ * call time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. A non-2xx response is a result, not a throw.
+ * @param request - the URL plus retrieval options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the retrieval outcome; non-2xx responses resolve descriptively.
+ */
+async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
+```
+
+Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/workflow.i18n.yaml b/docs/subsystems/workflow.i18n.yaml
index 7f996a1c8e..4f581d8bae 100644
--- a/docs/subsystems/workflow.i18n.yaml
+++ b/docs/subsystems/workflow.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 docs/core-data-structures/workflow.md
-workflow.md: 8d271b89e71de6f6bef548aa8da61402ef9ada6e
-workflow.zh.md: 91a4902bbc004e911c8aa84adb6a4abeda9dd59f
+#   pnpm run verify-translation-pairing --write docs/subsystems/workflow.md
+workflow.md: 53cb8be2c975fba396c3d2023c60fc1da2ed9c8a
+workflow.zh.md: 652b68c833f7f20fe72307946d02f89558be2c2b
diff --git a/docs/subsystems/workflow.md b/docs/subsystems/workflow.md
index 8d271b89e7..53cb8be2c9 100644
--- a/docs/subsystems/workflow.md
+++ b/docs/subsystems/workflow.md
@@ -129,4 +129,154 @@ Hook misuse inside a script — bad arguments, unknown/deferred `agent()` option
 
 ## Events
 
-The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `workflow/agent-start`, `workflow/agent-end`, `workflow/end` — see the [events catalog](../cordis-catalog/events.md)) are **observe-only** emits carrying DATA SNAPSHOTS: every payload starts with `WorkflowRunInfo` (id + meta), never the live `WorkflowRun`, so a subscriber cannot gain `cancel`/`dispose`, and `workflow/end` deliberately omits the result value (a listener observing outcomes must not receive a mutable alias of the caller's result). Every emit is per-listener contained — a throwing subscriber is logged, never propagated, and cannot starve the listeners registered after it — and every listener receives its own payload clone, so mutating it corrupts neither the engine nor other listeners; the containment mirrors `subagent/start`/`subagent/end`.
+The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `workflow/agent-start`, `workflow/agent-end`, `workflow/end` — see the [events catalog](#cordis-surface)) are **observe-only** emits carrying DATA SNAPSHOTS: every payload starts with `WorkflowRunInfo` (id + meta), never the live `WorkflowRun`, so a subscriber cannot gain `cancel`/`dispose`, and `workflow/end` deliberately omits the result value (a listener observing outcomes must not receive a mutable alias of the caller's result). Every emit is per-listener contained — a throwing subscriber is logged, never propagated, and cannot starve the listeners registered after it — and every listener receives its own payload clone, so mutating it corrupts neither the engine nor other listeners; the containment mirrors `subagent/start`/`subagent/end`.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxworkflows--workflowservice-abstract-seam"></a>
+
+### `ctx.workflows` — `WorkflowService` (abstract seam)
+
+Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
+
+```ts cordis-catalog
+/**
+ * Parse and execute a workflow script.
+ * @param request - the script, its `args`, the parent agent, and an
+ *   optional cancel signal.
+ * @returns the live run; its `result` resolves when the script settles.
+ */
+abstract start(request: WorkflowStartRequest): WorkflowRun
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflow-events"></a>
+
+### `workflow/*` events
+
+<a id="workflowagent-end--emit"></a>
+
+#### `workflow/agent-end` — emit
+
+One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start'] by `agent.seq`, exactly once per started call on every stop path — on an engine termination path (a worker killed past its grace) the end is engine-synthesized with outcome `'cancelled'`.
+
+```ts cordis-catalog
+/**
+ * One `agent()` call settled (clean result, child failure, or run
+ * cancellation). Paired with {@link Events['workflow/agent-start']} by
+ * `agent.seq`, exactly once per started call on every stop path — on an
+ * engine termination path (a worker killed past its grace) the end is
+ * engine-synthesized with outcome `'cancelled'`.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call identity plus its outcome.
+ * @mode emit
+ */
+'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:81`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowagent-start--emit"></a>
+
+#### `workflow/agent-start` — emit
+
+One `agent()` call established a published child run. Paired with Events['workflow/agent-end'] by `agent.seq`. A call that never receives a published run from the provider emits neither event in this pair.
+
+```ts cordis-catalog
+/**
+ * One `agent()` call established a published child run. Paired with
+ * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
+ * receives a published run from the provider emits neither
+ * event in this pair.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call's sequence number, label, phase, and child id.
+ * @mode emit
+ */
+'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowend--emit"></a>
+
+#### `workflow/end` — emit
+
+A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves. Paired with Events['workflow/start'].
+
+```ts cordis-catalog
+/**
+ * A workflow run settled (any stop reason). Fired when
+ * {@link WorkflowRun.result} resolves. Paired with
+ * {@link Events['workflow/start']}.
+ * @param info - the run's identity snapshot.
+ * @param result - the outcome data (stop reason, error, agent count) —
+ *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
+ * @mode emit
+ */
+'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowlog--emit"></a>
+
+#### `workflow/log` — emit
+
+The script emitted a narration line (a `log(message)` call).
+
+```ts cordis-catalog
+/**
+ * The script emitted a narration line (a `log(message)` call).
+ * @param info - the run's identity snapshot.
+ * @param message - the logged message, verbatim.
+ * @mode emit
+ */
+'workflow/log'(info: WorkflowRunInfo, message: string): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowphase--emit"></a>
+
+#### `workflow/phase` — emit
+
+The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics.
+
+```ts cordis-catalog
+/**
+ * The script entered a phase (a `phase(title)` call) — progress grouping
+ * for observers; no execution semantics.
+ * @param info - the run's identity snapshot.
+ * @param title - the phase title, verbatim.
+ * @mode emit
+ */
+'workflow/phase'(info: WorkflowRunInfo, title: string): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:53`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowstart--emit"></a>
+
+#### `workflow/start` — emit
+
+A workflow run started — the script's meta block validated, the body about to execute. Paired with Events['workflow/end'].
+
+```ts cordis-catalog
+/**
+ * A workflow run started — the script's meta block validated, the body
+ * about to execute. Paired with {@link Events['workflow/end']}.
+ * @param info - the run's identity snapshot (id + meta).
+ * @mode emit
+ */
+'workflow/start'(info: WorkflowRunInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:45`](../../packages/workflow/workflow/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/workflow.zh.md b/docs/subsystems/workflow.zh.md
index 91a4902bbc..652b68c833 100644
--- a/docs/subsystems/workflow.zh.md
+++ b/docs/subsystems/workflow.zh.md
@@ -129,4 +129,154 @@ interface WorkflowRun {
 
 ## 事件
 
-`workflow/*` 事件（`workflow/start`、`workflow/phase`、`workflow/log`、`workflow/agent-start`、`workflow/agent-end`、`workflow/end`，见[事件目录](../cordis-catalog/events.md)）是**仅供观察**的 emit，携带数据快照：每个 payload 以 `WorkflowRunInfo`（id + meta）开头，而非活跃的 `WorkflowRun`，因此订阅者无法获得 `cancel`/`dispose`；`workflow/end` 刻意省略 result value（观察结果的监听器不得收到调用方 result 的可变别名）。每次 emit 对每个监听器隔离：抛出异常的订阅者被记录日志但不传播，不会饿死在它之后注册的监听器；每个监听器收到自己的 payload 克隆，因此修改它既不会损坏引擎也不会影响其他监听器。这种隔离方式与 `subagent/start`/`subagent/end` 一致。
+`workflow/*` 事件（`workflow/start`、`workflow/phase`、`workflow/log`、`workflow/agent-start`、`workflow/agent-end`、`workflow/end`，见[事件目录](#cordis-surface)）是**仅供观察**的 emit，携带数据快照：每个 payload 以 `WorkflowRunInfo`（id + meta）开头，而非活跃的 `WorkflowRun`，因此订阅者无法获得 `cancel`/`dispose`；`workflow/end` 刻意省略 result value（观察结果的监听器不得收到调用方 result 的可变别名）。每次 emit 对每个监听器隔离：抛出异常的订阅者被记录日志但不传播，不会饿死在它之后注册的监听器；每个监听器收到自己的 payload 克隆，因此修改它既不会损坏引擎也不会影响其他监听器。这种隔离方式与 `subagent/start`/`subagent/end` 一致。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxworkflows--workflowservice-abstract-seam"></a>
+
+### `ctx.workflows` — `WorkflowService` (abstract seam)
+
+Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
+
+```ts cordis-catalog
+/**
+ * Parse and execute a workflow script.
+ * @param request - the script, its `args`, the parent agent, and an
+ *   optional cancel signal.
+ * @returns the live run; its `result` resolves when the script settles.
+ */
+abstract start(request: WorkflowStartRequest): WorkflowRun
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflow-events"></a>
+
+### `workflow/*` events
+
+<a id="workflowagent-end--emit"></a>
+
+#### `workflow/agent-end` — emit
+
+One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start'] by `agent.seq`, exactly once per started call on every stop path — on an engine termination path (a worker killed past its grace) the end is engine-synthesized with outcome `'cancelled'`.
+
+```ts cordis-catalog
+/**
+ * One `agent()` call settled (clean result, child failure, or run
+ * cancellation). Paired with {@link Events['workflow/agent-start']} by
+ * `agent.seq`, exactly once per started call on every stop path — on an
+ * engine termination path (a worker killed past its grace) the end is
+ * engine-synthesized with outcome `'cancelled'`.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call identity plus its outcome.
+ * @mode emit
+ */
+'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:81`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowagent-start--emit"></a>
+
+#### `workflow/agent-start` — emit
+
+One `agent()` call established a published child run. Paired with Events['workflow/agent-end'] by `agent.seq`. A call that never receives a published run from the provider emits neither event in this pair.
+
+```ts cordis-catalog
+/**
+ * One `agent()` call established a published child run. Paired with
+ * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
+ * receives a published run from the provider emits neither
+ * event in this pair.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call's sequence number, label, phase, and child id.
+ * @mode emit
+ */
+'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowend--emit"></a>
+
+#### `workflow/end` — emit
+
+A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves. Paired with Events['workflow/start'].
+
+```ts cordis-catalog
+/**
+ * A workflow run settled (any stop reason). Fired when
+ * {@link WorkflowRun.result} resolves. Paired with
+ * {@link Events['workflow/start']}.
+ * @param info - the run's identity snapshot.
+ * @param result - the outcome data (stop reason, error, agent count) —
+ *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
+ * @mode emit
+ */
+'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowlog--emit"></a>
+
+#### `workflow/log` — emit
+
+The script emitted a narration line (a `log(message)` call).
+
+```ts cordis-catalog
+/**
+ * The script emitted a narration line (a `log(message)` call).
+ * @param info - the run's identity snapshot.
+ * @param message - the logged message, verbatim.
+ * @mode emit
+ */
+'workflow/log'(info: WorkflowRunInfo, message: string): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowphase--emit"></a>
+
+#### `workflow/phase` — emit
+
+The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics.
+
+```ts cordis-catalog
+/**
+ * The script entered a phase (a `phase(title)` call) — progress grouping
+ * for observers; no execution semantics.
+ * @param info - the run's identity snapshot.
+ * @param title - the phase title, verbatim.
+ * @mode emit
+ */
+'workflow/phase'(info: WorkflowRunInfo, title: string): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:53`](../../packages/workflow/workflow/src/index.ts)
+
+<a id="workflowstart--emit"></a>
+
+#### `workflow/start` — emit
+
+A workflow run started — the script's meta block validated, the body about to execute. Paired with Events['workflow/end'].
+
+```ts cordis-catalog
+/**
+ * A workflow run started — the script's meta block validated, the body
+ * about to execute. Paired with {@link Events['workflow/end']}.
+ * @param info - the run's identity snapshot (id + meta).
+ * @mode emit
+ */
+'workflow/start'(info: WorkflowRunInfo): void
+```
+
+Source: [`packages/workflow/workflow/src/index.ts:45`](../../packages/workflow/workflow/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index 6a6488206c..b2c2248876 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
-workspace.md: 5614631e828e51f3b515ae4af17451bd9eda1dbb
-workspace.zh.md: 11e8f0207a8db8b7612d6672cfe744523490aef7
+workspace.md: ca088a2091a7f47a3d52992fec13fae44061a608
+workspace.zh.md: e414c759a043f934e1a8b5d89c7a3b6101bbb6f4
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index 5614631e82..ca088a2091 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -117,10 +117,103 @@ Ownership truth is the record's ordered `sessionIds`, never derived from session
 
 ## The registry: `ctx.workspace`
 
-`WorkspaceRegistry` ([signatures](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)) owns registration and resolution. `create(path, title?)` canonicalizes the path, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? basename(path)` prepended to the durable registry order — a new record cannot duplicate an existing display title (`WorkspaceNameConflictError`). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup resolves exactly the marked mutation — by deleting the marked table row, which completes an interrupted delete and rolls back an interrupted create (the registration is re-creatable, so rollback is the safe direction) — and an unmarked order/table mismatch fails loud as corruption.
+`WorkspaceRegistry` ([signatures](#ctxworkspace--workspaceregistry)) owns registration and resolution. `create(path, title?)` canonicalizes the path, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? basename(path)` prepended to the durable registry order — a new record cannot duplicate an existing display title (`WorkspaceNameConflictError`). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup resolves exactly the marked mutation — by deleting the marked table row, which completes an interrupted delete and rolls back an interrupted create (the registration is re-creatable, so rollback is the safe direction) — and an unmarked order/table mismatch fails loud as corruption.
 
 Sessions get their cwd at create time from whoever creates them, not from this registry — the API gateway resolves a new session's cwd from the chosen workspace's `path` (falling back to an explicit or default cwd), creates the session so the cwd lands in its immutable [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log), then calls `attachSession`, which re-validates that stored header cwd against the workspace path. On the first successful start, the registry bootstraps history from persisted headers alone (`id`, `cwd`, `createdAt` — never event bodies), grouping sessions with a valid canonical cwd into per-directory workspaces, newest first; the initialized marker is written last so an interrupted bootstrap resumes safely. The bootstrap is one-time: cwd-less legacy sessions stay Ungrouped, and sessions created afterwards join a workspace only through `attachSession`.
 
 ## Consumers
 
 [dsh-host-apiproxy](../../packages/host/apiproxy) is the product consumer: it serves workspace CRUD to GUI clients over `ctx.workspace` and performs the create-session-then-attach flow above. [dsh-workspace-context](../../packages/context/workspace-context) is **not** a consumer despite the name: it discovers AGENTS.md-style instruction files under an agent's own cwd and never touches `ctx.workspace` — the shared word refers to the user's working directory, not to this registry's entities.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
+
+### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
+
+Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
+
+```ts cordis-catalog
+/**
+ * The backend's interaction capability.
+ * @returns the discriminated capability consumers switch on.
+ */
+abstract capability(): DirectoryPickerCapability
+```
+
+Source: [`packages/host/directory-picker/src/index.ts:131`](../../packages/host/directory-picker/src/index.ts)
+
+<a id="ctxworkspace--workspaceregistry"></a>
+
+### `ctx.workspace` — `WorkspaceRegistry`
+
+Durable workspace registry. Startup waits for `sessionPersistence`, builds one canonical-cwd header index, and completes the one-time history bootstrap before the service becomes active. The persistence dependency is mandatory so an unavailable peer can never be mistaken for an empty history and commit the initialized marker.
+
+```ts cordis-catalog
+/**
+ * Create or reuse a workspace for an existing directory. The path is
+ * canonicalized through `fs.realpath`; a nonexistent path rejects with the
+ * original error and a non-directory rejects. Repeated calls for the same
+ * canonical path return the existing entity without changing its title.
+ * A newly created workspace is prepended to the durable registry order.
+ * Different canonical paths may share a display title.
+ * @param path - Existing directory to own, in any path spelling.
+ * @param title - Display title used only when a new record is created.
+ * @returns the existing or newly durable workspace.
+ */
+async create(path: string, title?: string): Promise<Workspace>
+
+/**
+ * Look up a workspace by id.
+ * @param id - Workspace id.
+ * @returns the workspace, or `undefined` when unknown.
+ */
+get(id: WorkspaceId): Workspace | undefined
+
+/**
+ * Synchronous workspace projection in durable registry order. Every
+ * entity's `sessionIds` getter is already filtered by the startup/live
+ * canonical-cwd header index; this method performs no persistence reads.
+ * @returns a fresh ordered array of workspace entities.
+ */
+list(): Workspace[]
+
+/**
+ * Delete one workspace registration while retaining its directory and every
+ * session log. The durable order is updated before the table deletion; a
+ * failed table write restores the prior order and keeps the entity
+ * published. Unknown ids are an idempotent no-op for domain callers.
+ * @param id - Workspace registration to remove.
+ * @returns `true` when a record was deleted, `false` when it was unknown.
+ */
+delete(id: WorkspaceId): Promise<boolean>
+
+/**
+ * Archive one session durably. The session must exist (live or in session
+ * persistence); its workspace accounting — or lack of one — is irrelevant.
+ * An already archived id resolves without writing.
+ * @param sessionId - The session to archive.
+ * @returns resolution after durability.
+ */
+archiveSession(sessionId: SessionId): Promise<void>
+
+/**
+ * Resolve by canonical directory path without creating or mutating a
+ * workspace. A missing path rejects during `realpath`; an existing unowned
+ * directory returns `undefined`.
+ * @param path - Existing directory path in any spelling.
+ * @returns the workspace owning the canonical path, when one exists.
+ */
+async resolveByPath(path: string): Promise<Workspace | undefined>
+```
+
+Types: [SessionId](core.md)
+
+Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index 11e8f0207a..e414c759a0 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -117,10 +117,103 @@ interface Workspace {
 
 ## 注册表：`ctx.workspace`
 
-`WorkspaceRegistry`（[签名](../cordis-catalog/services.md#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样传出原始 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好解决被标记的那次变更——通过删除被标记的表行：这会补完被中断的 delete，并回滚被中断的 create（注册可以重建，因此回滚是安全方向）——而没有标记的顺序/表不一致则作为损坏大声失败。
+`WorkspaceRegistry`（[签名](#ctxworkspace--workspaceregistry)）拥有注册与解析。`create(path, title?)` 规范化路径，拒绝不存在的路径（原样传出原始 `ENOENT`）或非目录；当规范路径已被拥有时原样返回既有实体；否则创建一条标题为 `title ?? basename(path)` 的记录并前插到持久的注册表顺序中——新记录不得与既有显示标题重复（`WorkspaceNameConflictError`）。`get(id)` 与有序的 `list()` 是同步缓存读取；`resolveByPath(path)` 应用同一套 realpath 规范但不创建。`delete(id)` 只移除注册记录、顺序条目和会话账本——目录、用户文件、实时会话和已持久化日志一概不动，因此这些会话变为 Ungrouped（[决策](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）；未知 id 返回 `false`。create 与 delete 会在其两次写入（记录 + 顺序）可能分叉之前先持久写入一个待定变更标记；启动时恰好解决被标记的那次变更——通过删除被标记的表行：这会补完被中断的 delete，并回滚被中断的 create（注册可以重建，因此回滚是安全方向）——而没有标记的顺序/表不一致则作为损坏大声失败。
 
 会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次成功启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑。引导只发生这一次：没有 cwd 的历史遗留会话保持 Ungrouped，此后创建的会话只能通过 `attachSession` 加入工作区。
 
 ## 消费方
 
 [dsh-host-apiproxy](../../packages/host/apiproxy) 是产品消费方：它经 `ctx.workspace` 向 GUI 客户端提供工作区的 CRUD，并执行上文「先建会话再 attach」的流程。[dsh-workspace-context](../../packages/context/workspace-context) 尽管名字如此，却**不是**消费方：它在 agent 自己的 cwd 下发现 AGENTS.md 风格的指令文件，从不触碰 `ctx.workspace`——两者共用的这个词指的是用户的工作目录，而非本注册表的实体。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis surface
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
+
+### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
+
+Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
+
+```ts cordis-catalog
+/**
+ * The backend's interaction capability.
+ * @returns the discriminated capability consumers switch on.
+ */
+abstract capability(): DirectoryPickerCapability
+```
+
+Source: [`packages/host/directory-picker/src/index.ts:131`](../../packages/host/directory-picker/src/index.ts)
+
+<a id="ctxworkspace--workspaceregistry"></a>
+
+### `ctx.workspace` — `WorkspaceRegistry`
+
+Durable workspace registry. Startup waits for `sessionPersistence`, builds one canonical-cwd header index, and completes the one-time history bootstrap before the service becomes active. The persistence dependency is mandatory so an unavailable peer can never be mistaken for an empty history and commit the initialized marker.
+
+```ts cordis-catalog
+/**
+ * Create or reuse a workspace for an existing directory. The path is
+ * canonicalized through `fs.realpath`; a nonexistent path rejects with the
+ * original error and a non-directory rejects. Repeated calls for the same
+ * canonical path return the existing entity without changing its title.
+ * A newly created workspace is prepended to the durable registry order.
+ * Different canonical paths may share a display title.
+ * @param path - Existing directory to own, in any path spelling.
+ * @param title - Display title used only when a new record is created.
+ * @returns the existing or newly durable workspace.
+ */
+async create(path: string, title?: string): Promise<Workspace>
+
+/**
+ * Look up a workspace by id.
+ * @param id - Workspace id.
+ * @returns the workspace, or `undefined` when unknown.
+ */
+get(id: WorkspaceId): Workspace | undefined
+
+/**
+ * Synchronous workspace projection in durable registry order. Every
+ * entity's `sessionIds` getter is already filtered by the startup/live
+ * canonical-cwd header index; this method performs no persistence reads.
+ * @returns a fresh ordered array of workspace entities.
+ */
+list(): Workspace[]
+
+/**
+ * Delete one workspace registration while retaining its directory and every
+ * session log. The durable order is updated before the table deletion; a
+ * failed table write restores the prior order and keeps the entity
+ * published. Unknown ids are an idempotent no-op for domain callers.
+ * @param id - Workspace registration to remove.
+ * @returns `true` when a record was deleted, `false` when it was unknown.
+ */
+delete(id: WorkspaceId): Promise<boolean>
+
+/**
+ * Archive one session durably. The session must exist (live or in session
+ * persistence); its workspace accounting — or lack of one — is irrelevant.
+ * An already archived id resolves without writing.
+ * @param sessionId - The session to archive.
+ * @returns resolution after durability.
+ */
+archiveSession(sessionId: SessionId): Promise<void>
+
+/**
+ * Resolve by canonical directory path without creating or mutating a
+ * workspace. A missing path rejects during `realpath`; an existing unowned
+ * directory returns `undefined`.
+ * @param path - Existing directory path in any spelling.
+ * @returns the workspace owning the canonical path, when one exists.
+ */
+async resolveByPath(path: string): Promise<Workspace | undefined>
+```
+
+Types: [SessionId](core.md)
+
+Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts)
+<!-- END GENERATED cordis-surface -->
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index a100469102..8986847d1e 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -3,7 +3,7 @@
 
 # Tool Schema Catalog
 
-Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [subsystems/](subsystems/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.
+Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [subsystem pages](subsystems/core.md) (the types plus each page's generated `cordis-surface` wiring region) — this page is the *tools* the agent is offered.
 
 This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator's boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).
 
diff --git a/docs/user/develop/framework/events.i18n.yaml b/docs/user/develop/framework/events.i18n.yaml
index 769556da41..37dd601646 100644
--- a/docs/user/develop/framework/events.i18n.yaml
+++ b/docs/user/develop/framework/events.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 docs/user/develop/framework/events.md
-events.md: fcbdb5f39bf2078032affbc6469f7eecc795d3ba
-events.zh.md: 1979e0bc1dbb71e46f50a051dacee8ae3a1172a7
+events.md: c70150b4d9070063513021e420f253ff6d4e5de1
+events.zh.md: 813dc3631e0c776ad9c8763db65eebc3f2167578
diff --git a/docs/user/develop/framework/events.md b/docs/user/develop/framework/events.md
index fcbdb5f39b..c70150b4d9 100644
--- a/docs/user/develop/framework/events.md
+++ b/docs/user/develop/framework/events.md
@@ -101,7 +101,7 @@ declare module 'cordis' {
 
 ## Cordis events and session records
 
-Harness Cordis events use `namespace/action` names, including `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/result`, and `session/event`. The generated [event catalog](../../../cordis-catalog/events.md) records complete signatures and modes.
+Harness Cordis events use `namespace/action` names, including `agent/step`, `agent/request`, `agent/request-error`, `tools/result`, and `session/event`. The generated `cordis-surface` regions on the [subsystem pages](../../../subsystems/core.md) record complete signatures and modes.
 
 `turn/*`, `step/*`, `tool/call`, `tool/result`, and `compact/*` are durable session-event types, not same-named Cordis events. To observe them, listen to `session/event` and inspect `event.type`.
 
diff --git a/docs/user/develop/framework/events.zh.md b/docs/user/develop/framework/events.zh.md
index 1979e0bc1d..813dc3631e 100644
--- a/docs/user/develop/framework/events.zh.md
+++ b/docs/user/develop/framework/events.zh.md
@@ -101,7 +101,7 @@ declare module 'cordis' {
 
 ## Cordis 事件与会话记录
 
-Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/pre-step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[Events 目录](../../../cordis-catalog/events.md)。
+Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../../subsystems/core.md)上生成的 `cordis-surface` 区块。
 
 `turn/*`、`step/*`、`tool/call`、`tool/result` 和 `compact/*` 是持久化的会话事件类型，不是同名 Cordis 事件。需要观察它们时，监听 `session/event` 并检查 `event.type`。
 
diff --git a/docs/user/develop/framework/service.i18n.yaml b/docs/user/develop/framework/service.i18n.yaml
index ade6b8dc08..7cb2f4ff88 100644
--- a/docs/user/develop/framework/service.i18n.yaml
+++ b/docs/user/develop/framework/service.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 docs/user/develop/framework/service.md
-service.md: 1bf28cb3c7dfdfbd6d0babfa3b1688ac65eea01e
-service.zh.md: 78b9887a734b235bcff1d94a623e37cfeb2f41e3
+service.md: 040b1388cc431c30045e05f7d372ab5885bb3f9d
+service.zh.md: 0786b684c1688440a24cc729288835ad636f8ff7
diff --git a/docs/user/develop/framework/service.md b/docs/user/develop/framework/service.md
index 1bf28cb3c7..040b1388cc 100644
--- a/docs/user/develop/framework/service.md
+++ b/docs/user/develop/framework/service.md
@@ -140,7 +140,7 @@ This prevents a plugin from calling a service that no longer exists.
 
 ## Built-in Harness services
 
-The repository generates the service names, public methods, and source locations in the [service catalog](../../../cordis-catalog/services.md). Use that catalog and the service's TypeScript interface while developing a plugin; do not maintain a second static list.
+The repository generates the service names, public methods, and source locations into each service's [subsystem page](../../../subsystems/core.md). Use those generated regions and the service's TypeScript interface while developing a plugin; do not maintain a second static list.
 
 ## Next steps
 
diff --git a/docs/user/develop/framework/service.zh.md b/docs/user/develop/framework/service.zh.md
index 78b9887a73..0786b684c1 100644
--- a/docs/user/develop/framework/service.zh.md
+++ b/docs/user/develop/framework/service.zh.md
@@ -140,7 +140,7 @@ export function apply(ctx: Context) {
 
 ## Harness 内置服务
 
-仓库会自动生成[服务目录](../../../cordis-catalog/services.md)，其中包含服务名、公开方法和源码位置。开发插件时应以该目录和服务的 TypeScript 接口为准，不要维护另一份静态清单。
+服务名、公开方法和源码位置由仓库自动生成到各服务的[子系统页面](../../../subsystems/core.md)。开发插件时应以这些生成区块和服务接口的 TypeScript 类型为准，不要复制一份静态清单。
 
 ## 下一步
 
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index 2f165e76e4..fb18353290 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/core/agent-loop/README.md
-README.md: 2fdc60086bebc924089b5b8bd12f4b4456b1ead5
-README.zh.md: df0ba44ec5b010666737c0568bc5eeb220ff0d96
+README.md: 81bc4411977f7335defef5af82d4a67a740b2ed5
+README.zh.md: c190171513e17777ebaadda0d279487876a412b4
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 2fdc60086b..81bc441197 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -74,7 +74,7 @@ Within a step, exclusive calls form barriers; parallel-safe calls use a bounded
 ### What belongs to plugins
 
 Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy:
-- Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → definition-owned `finalizeContent` → `tools/result` pipeline; exact event signatures and modes live in the [generated event catalog](../../../docs/cordis-catalog/events.md)
+- Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → definition-owned `finalizeContent` → `tools/result` pipeline; exact event signatures and modes live in the generated regions of [core.md](../../../docs/subsystems/core.md#cordis-surface) and [tools.md](../../../docs/subsystems/tools.md#cordis-surface)
 - Compaction: pressure on `agent/pre-step`; canonical overflow repair on `agent/request-error`
 - Model-request recovery: `dsh-llm-retry` records and waits exact-provider normal or unbounded backoff on `agent/request-error`, emits non-surface `llm/retry` status, then returns a retry action
 - Sandbox, permission, plan mode: `tools/pre-execute` for extensible deny/ask, `tools.guard()` for monotonic owner policy, `tools/post-execute` for result decisions, and `tools/result` for final observation
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index df0ba44ec5..c190171513 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -74,7 +74,7 @@ interface Config {
 ### 插件负责的内容
 
 超出「调用模型、运行工具、重复」的所有内容，都属于监听事件分类体系的插件：
-- 钩子与策略：相关的 `agent/*` 检查点，加上受守卫保护的 `tools/pre-execute` → `tools/execute` → `tools/post-execute` → 定义拥有的 `finalizeContent` → `tools/result` 流水线；确切事件签名与 mode 位于生成的[事件目录](../../../docs/cordis-catalog/events.md)
+- 钩子与策略：相关的 `agent/*` 检查点，加上受守卫保护的 `tools/pre-execute` → `tools/execute` → `tools/post-execute` → 定义拥有的 `finalizeContent` → `tools/result` 流水线；确切事件签名与 mode 位于 [core.md](../../../docs/subsystems/core.md#cordis-surface) 与 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块
 - 压缩（compaction）：在 `agent/pre-step` 上观测压力；在 `agent/request-error` 上进行规范的溢出修复
 - 模型请求恢复：`dsh-llm-retry` 在 `agent/request-error` 上记录并等待按确切提供方配置的 normal 或无界退避，发出不进入表层的 `llm/retry` 状态，然后返回重试动作
 - 沙箱、权限、计划模式：使用 `tools/pre-execute` 提供可扩展的拒绝／询问，使用 `tools.guard()` 提供单调拥有方策略，使用 `tools/post-execute` 处理结果决定，并使用 `tools/result` 进行最终观测
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index 5c03669baf..4c6009d3b0 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/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/core/agent/README.md
-README.md: 2a69ab380eaad3929e27039582807037969eba64
-README.zh.md: 176f3f75cf0f6e3309b2f5d34afb4d562105608e
+README.md: 3a3bdf6a4b3bdc5bfef250495e84b7d90b003822
+README.zh.md: 8164829e18ddd89fd84c0c2b5e033fd69241b9aa
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index 2a69ab380e..3a3bdf6a4b 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -46,7 +46,7 @@ Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-age
 
 ### Live events
 
-`dsh-agent` declares the live `agent/*` coordination vocabulary so plugins do not depend on the concrete loop. Exact signatures, dispatch modes, scope-filtering rules, and payload contracts live in the generated [Cordis event catalog](../../../docs/cordis-catalog/events.md); the [architecture turn flow](../../../docs/architecture.md#turn-flow) shows their order relative to durable session events.
+`dsh-agent` declares the live `agent/*` coordination vocabulary so plugins do not depend on the concrete loop. Exact signatures, dispatch modes, scope-filtering rules, and payload contracts live in the generated region of [core.md](../../../docs/subsystems/core.md#cordis-surface); the [architecture turn flow](../../../docs/architecture.md#turn-flow) shows their order relative to durable session events.
 
 The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist. Setup is trusted composition-only code; the immediately following non-vetoing `agent/session-start` notification is the first supported startup injection point. `agent/disposed` always means the exact agent has left the registry. AgentLoop emits it after its driver is quiescent, while ordered teardown may still be detaching the session and unwinding the scope; custom agents registered directly own any stronger driver-ordering contract themselves.
 
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index 176f3f75cf..8164829e18 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -46,7 +46,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 ### 实时事件
 
-`dsh-agent` 声明实时 `agent/*` 协调词汇，使插件不必依赖具体循环。确切签名、分发 mode、作用域筛选规则与 payload 契约位于生成的 [Cordis 事件目录](../../../docs/cordis-catalog/events.md)；[架构轮次流](../../../docs/architecture.md#turn-flow) 展示它们与持久会话事件的相对顺序。
+`dsh-agent` 声明实时 `agent/*` 协调词汇，使插件不必依赖具体循环。确切签名、分发 mode、作用域筛选规则与 payload 契约位于 [core.md](../../../docs/subsystems/core.md#cordis-surface) 的生成区块；[架构轮次流](../../../docs/architecture.md#turn-flow) 展示它们与持久会话事件的相对顺序。
 
 生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序契约。
 
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index c30b37e549..8b1e462166 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
-README.md: 07ee53006b390e5ad3979502b2f1aa24f5a6ce7a
-README.zh.md: d4a90de10b92a489f8f575b926d758b45d8f5051
+README.md: 00e007ee6064f485bf80dfda0227ab6e834f6414
+README.zh.md: 5f06fee5d50bc2c9dc333874a8354fbf19d5248b
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index 07ee53006b..00e007ee60 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -30,7 +30,7 @@ Use the split lifecycle only when teardown must be ordered with another resource
 
 ### Live service events
 
-The store pairs announced creation with disposal, publishes post-commit append notifications with per-listener containment, and provides an awaited durability checkpoint. Exact signatures and scope behavior live in the generated [event catalog](../../../docs/cordis-catalog/events.md); payloads live in the [persistence catalog](../../../docs/persistence-catalog.md).
+The store pairs announced creation with disposal, publishes post-commit append notifications with per-listener containment, and provides an awaited durability checkpoint. Exact signatures and scope behavior live in the generated region of [session.md](../../../docs/subsystems/session.md#cordis-surface); payloads live in the [persistence catalog](../../../docs/persistence-catalog.md).
 
 ### Class: `Session`
 
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index d4a90de10b..5f06fee5d5 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -30,7 +30,7 @@
 
 ### 实时服务事件
 
-会话存储会将已通知的创建与释放配对，在提交后发布追加通知并逐个监听器收容失败，同时提供受等待的持久性检查点。确切签名和作用域行为见生成的[事件目录](../../../docs/cordis-catalog/events.md)；载荷见[持久化目录](../../../docs/persistence-catalog.md)。
+会话存储会将已通知的创建与释放配对，在提交后发布追加通知并逐个监听器收容失败，同时提供受等待的持久性检查点。确切签名和作用域行为见 [session.md](../../../docs/subsystems/session.md#cordis-surface) 的生成区块；载荷见[持久化目录](../../../docs/persistence-catalog.md)。
 
 ### 类：`Session`
 
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index 36f166dd86..c94d1722dc 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/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/core/system-prompt/README.md
-README.md: 23bc0e8177ad2a778df9522e254bfd5e03a9871f
-README.zh.md: b442239a50d539a8f079aa692c433d9defe57295
+README.md: e98c45a8829a945500ef5282d84e1904b31c68bf
+README.zh.md: 5b9e2feaf82866a52cd8197ff5e800decdf3ee7e
diff --git a/packages/core/system-prompt/README.md b/packages/core/system-prompt/README.md
index 23bc0e8177..e98c45a882 100644
--- a/packages/core/system-prompt/README.md
+++ b/packages/core/system-prompt/README.md
@@ -23,7 +23,7 @@ System prompt assembly registry. Plugins contribute ordered sections, tool schem
 
 ### Live events
 
-`system-prompt/assemble` is authoritative; listeners that replace entries must preserve any active Code Mode or structured-output protocol. Use [`ToolRegistry.restrict()`](../tools/README.md) when filtering must stay aligned across presentation, lookup, and execution. Registry-change notifications are unfiltered. The generated [event catalog](../../../docs/cordis-catalog/events.md) owns signatures and dispatch contracts.
+`system-prompt/assemble` is authoritative; listeners that replace entries must preserve any active Code Mode or structured-output protocol. Use [`ToolRegistry.restrict()`](../tools/README.md) when filtering must stay aligned across presentation, lookup, and execution. Registry-change notifications are unfiltered. The generated region of [system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) owns signatures and dispatch contracts.
 
 ### Key types
 
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index b442239a50..5b9e2feaf8 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -23,7 +23,7 @@
 
 ### 实时事件
 
-`system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。生成的[事件目录](../../../docs/cordis-catalog/events.md) 拥有签名与分发契约。
+`system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。[system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) 的生成区块拥有签名与分发契约。
 
 ### 关键类型
 
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index e8157eed7e..b19e86ce84 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: fd5cb85540e42e62de28f96bf59890da9561f51e
-README.zh.md: 5911b25b1d77710077063a643a29e500e4da8e95
+README.md: f3f25f908a4ba8016d38f7777fe72691dba4afb1
+README.zh.md: 796ee8e1aa8de88f979d825df5e0b4f39ab7bcf1
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index fd5cb85540..f3f25f908a 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -35,7 +35,7 @@ Cancellation is cooperative and quiescent. Every typed invocation supplies a cal
 
 ### Live events
 
-The live registry pipeline has three transformable waterfalls, then the definition-owned content finalizer, then the observe-only `tools/result` boundary; registry changes are deliberately unfiltered shared-state notifications. Exact signatures, dispatch modes, scope filtering, and failure-containment contracts live in the generated [Cordis event catalog](../../../docs/cordis-catalog/events.md), while the complete ordering is visualized in the generated [tool execution pipeline](../../../docs/tool-execution-pipeline.md). `tools/result` is live; the similarly named `tool/result` is the durable session event the agent loop appends afterwards.
+The live registry pipeline has three transformable waterfalls, then the definition-owned content finalizer, then the observe-only `tools/result` boundary; registry changes are deliberately unfiltered shared-state notifications. Exact signatures, dispatch modes, scope filtering, and failure-containment contracts live in the generated region of [tools.md](../../../docs/subsystems/tools.md#cordis-surface), while the complete ordering is visualized in the generated [tool execution pipeline](../../../docs/tool-execution-pipeline.md). `tools/result` is live; the similarly named `tool/result` is the durable session event the agent loop appends afterwards.
 
 ### Key types
 
@@ -56,7 +56,7 @@ The live registry pipeline has three transformable waterfalls, then the definiti
 - `tools/pre-execute` is the reorderable allow/deny/ask gate; `ctx.tools.guard()` adds monotonic owner policy after it.
 - `tools/execute` wraps normalized canonical dispatch for timeout, retry, or metrics. Wrappers may replace only the operational signal; a wrapper-authored success is normalized through the resolved tool's output declaration. Canonical-result provenance belongs to one immutable dispatch token, so a cached result from another call or tool is revalidated under the active declaration.
 - `tools/post-execute` may replace presentation content, replace the canonical value, block with feedback, or attach ordered contexts. A definition's optional `finalizeContent` then owns its last content-only invariant across normal results and outer pipeline failures; `tools/result` observes the immutable final outcome. Content replacement is not a confidentiality boundary: block or replace the value when programmatic consumers must not receive it.
-- Exact signatures and ordering live in the generated [event catalog](../../../docs/cordis-catalog/events.md) and [pipeline](../../../docs/tool-execution-pipeline.md).
+- Exact signatures and ordering live in the generated region of [tools.md](../../../docs/subsystems/tools.md#cordis-surface) and [pipeline](../../../docs/tool-execution-pipeline.md).
 - MCP servers: one plugin per server, discover tools, call `ctx.tools.register()` with the server's schemas.
 
 ### Typed tool parameter schemas
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 5911b25b1d..796ee8e1aa 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -35,7 +35,7 @@ tools:
 
 ### 实时事件
 
-实时注册表流水线先经过 3 个可变换的 waterfall，再经过由定义拥有的内容终结器，最后到达仅观测的 `tools/result` 边界；注册表变更有意作为不过滤的共享状态通知。确切签名、分发模式、作用域筛选和故障收容契约位于生成的 [Cordis 事件目录](../../../docs/cordis-catalog/events.md)，完整顺序则在生成的[工具执行流水线](../../../docs/tool-execution-pipeline.md)中可视化。`tools/result` 是实时事件；名称相近的 `tool/result` 是 agent loop 随后追加的持久会话事件。
+实时注册表流水线先经过 3 个可变换的 waterfall，再经过由定义拥有的内容终结器，最后到达仅观测的 `tools/result` 边界；注册表变更有意作为不过滤的共享状态通知。确切签名、分发 mode、作用域筛选和故障收容契约位于 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块，完整顺序则在生成的[工具执行流水线](../../../docs/tool-execution-pipeline.md)中可视化。`tools/result` 是实时事件；名称相近的 `tool/result` 是 agent loop 随后追加的持久会话事件。
 
 ### 关键类型
 
@@ -56,7 +56,7 @@ tools:
 - `tools/pre-execute` 是可重排的允许／拒绝／询问门禁；`ctx.tools.guard()` 在其后添加单调的拥有方策略。
 - `tools/execute` 会环绕包装规范化后的规范分发，以支持超时、重试或指标采集。包装层只能替换操作信号；包装层生成的成功结果会根据已解析工具的输出声明进行规范化。规范结果的来源属于一个不可变分发 token，因此，来自其他调用或工具的缓存结果会根据当前声明重新验证。
 - `tools/post-execute` 可以替换呈现内容、替换规范值、通过反馈阻止，或附加有序上下文。随后，定义可选的 `finalizeContent` 会在普通结果和外层流水线失败中维护其最终、仅涉及内容的不变式；`tools/result` 观测不可变的最终结果。内容替换不是保密边界：当编程消费方不得接收某个值时，应阻止或替换该值。
-- 确切签名与顺序位于生成的[事件目录](../../../docs/cordis-catalog/events.md)和[流水线](../../../docs/tool-execution-pipeline.md)中。
+- 确切签名与顺序位于 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块和[流水线](../../../docs/tool-execution-pipeline.md)中。
 - MCP 服务器：每个服务器使用一个插件；发现工具后，使用服务器的 schema 调用 `ctx.tools.register()`。
 
 ### 类型化工具参数 schema
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index d9b5f0ebc0..d9b0010670 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: bf1dd1c1eb65146258cd64e450749845522e7057
-README.zh.md: f3fcc0c3794b972233dc418e93bdd80b1cc8570a
+README.md: 5c58fc476b9b11a83bbe0d6c33ac782d94d6ffbc
+README.zh.md: 97d7104f3c4c0beca408397f9cb1cead39b0a76e
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index bf1dd1c1eb..5c58fc476b 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -37,7 +37,7 @@ The mutation runs inside the backend's per-target lock either way, so an uncondi
 
 ## The `fs/*` policy events
 
-This package declares three events (see the generated [events catalog](../../../docs/cordis-catalog/events.md)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
+This package declares three events (see the generated region of [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
 ## A provider seam, not the policy layer
 
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index f3fcc0c379..97d7104f3c 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -37,7 +37,7 @@
 
 ## `fs/*` 政策事件
 
-本包声明三个事件（见已生成的[事件目录](../../../docs/cordis-catalog/events.md)），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
 ## 提供方 seam，不是政策层
 
diff --git a/packages/goal/goal/README.i18n.yaml b/packages/goal/goal/README.i18n.yaml
index 6362a6d1e9..d8fbf8fc29 100644
--- a/packages/goal/goal/README.i18n.yaml
+++ b/packages/goal/goal/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/goal/goal/README.md
-README.md: fc2fd8791096bcc9077ef7972da86b0e07c6f18e
-README.zh.md: 311ec1d03436cc45bbea28df96e66579852058b0
+README.md: 98765a809820bcd4aeba31e1dd4ef6e92eb30760
+README.zh.md: dbc499104bac6cf09f9b1c871143da8781a8f082
diff --git a/packages/goal/goal/README.md b/packages/goal/goal/README.md
index fc2fd87910..98765a8098 100644
--- a/packages/goal/goal/README.md
+++ b/packages/goal/goal/README.md
@@ -17,7 +17,7 @@ Event-sourced same-session goal state. The service retains one current completio
 
 ## Service contract
 
-`ctx.goals` accepts only the exact live `Agent` instance registered under its id. `get()` returns a detached `GoalView`; mutations use a `GoalRef { id, revision }` compare-and-set fence and reject stale refs. The service exposes create, edit, pause, resume, complete, block, and clear verbs through the generated [service catalog](../../../docs/cordis-catalog/services.md). Creation default resolution is internal. `disarm()` is the lifecycle-only exception: it removes process-local continuation authority without writing a revision or emitting a mutation.
+`ctx.goals` accepts only the exact live `Agent` instance registered under its id. `get()` returns a detached `GoalView`; mutations use a `GoalRef { id, revision }` compare-and-set fence and reject stale refs. The service exposes create, edit, pause, resume, complete, block, and clear verbs through the generated region of [goal.md](../../../docs/subsystems/goal.md#cordis-surface). Creation default resolution is internal. `disarm()` is the lifecycle-only exception: it removes process-local continuation authority without writing a revision or emitting a mutation.
 
 At most one goal is current. Creation produces an active revision-one goal and arms it. A non-complete goal must be edited, transitioned, or cleared; a completed goal may be replaced by a globally fresh id. Edits retain phase, blocker reason, and activation. Pause, completion, blocking, and clear disarm activation. A block records a policy-owned lower-kebab-case code plus a normalized free-form explanation; provider limits, configured budgets, execution errors, and requests for human input all use this one durable phase rather than multiplying lifecycle states. Resume accepts a stopped phase or a disarmed active goal only while the configured round cap has remaining capacity; it clears any former blocker reason. An active armed goal rejects the redundant operation.
 
diff --git a/packages/goal/goal/README.zh.md b/packages/goal/goal/README.zh.md
index 311ec1d034..dbc499104b 100644
--- a/packages/goal/goal/README.zh.md
+++ b/packages/goal/goal/README.zh.md
@@ -17,7 +17,7 @@
 
 ## 服务契约
 
-`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回与内部状态脱离的 `GoalView`；变更通过 `GoalRef { id, revision }` 比较并设置屏障，并拒绝陈旧引用。服务通过生成的[服务目录](../../../docs/cordis-catalog/services.md)公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发出变更。
+`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回分离的 `GoalView`；变更通过 `GoalRef { id, revision }` 比较并设置限制，并拒绝陈旧引用。服务通过 [goal.md](../../../docs/subsystems/goal.md#cordis-surface) 的生成区块公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发送变更事件。
 
 最多只有一个当前目标。创建操作会生成 revision 为 1、phase 为 active 的目标并启用续行。未完成的目标必须编辑、转换或清除；已完成目标可以由拥有全局未使用过的 id 的目标替换。编辑会保留 phase、blocker reason 与 activation。暂停、完成、阻塞和清除都会停用续行。阻塞会记录策略自有的 lower-kebab-case 代码和规范化的自由文本说明；提供方限制、配置预算、执行错误与请求人工输入都使用这一种持久 phase，不会扩增生命周期状态。只有配置的 Round 上限仍有剩余容量时，resume 才接受已停止 phase 或 phase 为 active 但已停用续行的目标；它会清除原 blocker reason。phase 为 active 且已启用续行的目标会拒绝冗余操作。
 
diff --git a/packages/interaction/user-approval/README.i18n.yaml b/packages/interaction/user-approval/README.i18n.yaml
index 36188334e7..2122c0d101 100644
--- a/packages/interaction/user-approval/README.i18n.yaml
+++ b/packages/interaction/user-approval/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/interaction/user-approval/README.md
-README.md: 7b87a75d1c7c43874c484bc11f8deed45cb523ce
-README.zh.md: 3c02f8d673a62c3ee954da26f6341b433032a88c
+README.md: 0cf5d458863194e29f8c84168a6f089baabbf3d2
+README.zh.md: a48e4ff4650fbd90744c9d7c41878b6e0487127c
diff --git a/packages/interaction/user-approval/README.md b/packages/interaction/user-approval/README.md
index 7b87a75d1c..0cf5d45886 100644
--- a/packages/interaction/user-approval/README.md
+++ b/packages/interaction/user-approval/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Channel-neutral one-shot approval seam. `ctx.approval.request(req)` returns `allowed-once`, `rejected`, `cancelled`, or `unavailable`; missing or failing answerers fail closed, and a grant applies only to the requested action. Exact event signatures live in the generated [Cordis catalog](../../../docs/cordis-catalog/events.md).
+Channel-neutral one-shot approval seam. `ctx.approval.request(req)` returns `allowed-once`, `rejected`, `cancelled`, or `unavailable`; missing or failing answerers fail closed, and a grant applies only to the requested action. Exact event signatures live in the generated region of [approval.md](../../../docs/subsystems/approval.md#cordis-surface).
 
 Each request must belong to an open agent turn. The service appends a paired `approval/asked` and `approval/decided` audit record, while the model sees only the resulting logged tool outcome. An aborted request resolves `cancelled`; an audit append that fails before commit rejects rather than returning an unlogged decision.
 
diff --git a/packages/interaction/user-approval/README.zh.md b/packages/interaction/user-approval/README.zh.md
index 3c02f8d673..a48e4ff465 100644
--- a/packages/interaction/user-approval/README.zh.md
+++ b/packages/interaction/user-approval/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-与通道无关的一次性审批 seam。`ctx.approval.request(req)` 返回 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`；应答者缺失或失败时会以拒绝方式关闭，授权也只适用于所请求的操作。确切事件签名见生成的 [Cordis 目录](../../../docs/cordis-catalog/events.md)。
+与通道无关的一次性审批 seam。`ctx.approval.request(req)` 返回 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`；应答者缺失或失败时会以拒绝方式关闭，授权也只适用于所请求的操作。确切事件签名见 [approval.md](../../../docs/subsystems/approval.md#cordis-surface) 的生成区块。
 
 每个请求都必须属于一个尚未结束的 agent（智能体）轮次。服务会追加一对 `approval/asked` 与 `approval/decided` 审计记录，而模型只会看到由此产生且已写入日志的工具结果。已中止的请求会解析为 `cancelled`；如果审计记录的追加在提交前失败，Promise 会被拒绝，而不会返回一项未记录的决定。
 
diff --git a/packages/self-modification/tool-cordis/README.i18n.yaml b/packages/self-modification/tool-cordis/README.i18n.yaml
index c25dda28e3..ef1f441711 100644
--- a/packages/self-modification/tool-cordis/README.i18n.yaml
+++ b/packages/self-modification/tool-cordis/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/self-modification/tool-cordis/README.md
-README.md: 9986310160c2b56126155a4c3ef84d66018d31c2
-README.zh.md: d955306e1e5d4154f58c771704782ece44a15c99
+README.md: f2a65043a1d2f74553e98caf59ed3d38b5a70b7c
+README.zh.md: 66742094992d219ccfbd60b935dcd10e48cb12b8
diff --git a/packages/self-modification/tool-cordis/README.md b/packages/self-modification/tool-cordis/README.md
index 9986310160..f2a65043a1 100644
--- a/packages/self-modification/tool-cordis/README.md
+++ b/packages/self-modification/tool-cordis/README.md
@@ -28,7 +28,7 @@ The sandbox isolates globals but is not a security boundary. Node globals are ab
 
 ## The generated API catalog
 
-`src/api-catalog.ts` is generated from the same Typert `FaceModel` projection as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `scripts/gen-cordis-api.ts` is a compatibility entry point for that unified projection, not a second collector. `cordis_inspect` intersects the committed catalog with the live service store at call time; it has no runtime Typert dependency. Broad `api` / `events` reports render summaries and signatures only; an exact `name` opts into the retained method/event JSDoc, and unknown or non-running service targets fail loud.
+`src/api-catalog.ts` is generated from the same Typert `FaceModel` projection as the [subsystem pages' generated regions](../../../docs/subsystems/core.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `scripts/gen-cordis-api.ts` is a compatibility entry point for that unified projection, not a second collector. `cordis_inspect` intersects the committed catalog with the live service store at call time; it has no runtime Typert dependency. Broad `api` / `events` reports render summaries and signatures only; an exact `name` opts into the retained method/event JSDoc, and unknown or non-running service targets fail loud.
 
 ## Rendering
 
diff --git a/packages/self-modification/tool-cordis/README.zh.md b/packages/self-modification/tool-cordis/README.zh.md
index d955306e1e..6674209499 100644
--- a/packages/self-modification/tool-cordis/README.zh.md
+++ b/packages/self-modification/tool-cordis/README.zh.md
@@ -28,7 +28,7 @@
 
 ## 生成的 API 目录
 
-`src/api-catalog.ts` 与 [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) 由同一个 Typert `FaceModel` 投影生成，并由 `pnpm run verify-cordis-api`（位于 `doc-sync` 中）实施新鲜度门禁，绝不可手工编辑。`scripts/gen-cordis-api.ts` 是该统一投影的兼容入口，而非第二套收集器。`cordis_inspect` 在调用时把已提交的目录与存活服务 store 取交集；它在运行时不依赖 Typert。宽泛的 `api`／`events` 报告只渲染摘要与签名；精确 `name` 会选择保留的方法／事件 JSDoc，未知或未运行的服务目标会高声失败。
+`src/api-catalog.ts` 与[子系统页面的生成区块](../../../docs/subsystems/core.md)由同一个 Typert `FaceModel` 投影生成，并由 `pnpm run verify-cordis-api`（位于 `doc-sync` 中）实施新鲜度门禁，绝不可手工编辑。`scripts/gen-cordis-api.ts` 是该统一投影的兼容入口，而非第二套收集器。`cordis_inspect` 在调用时把已提交的目录与存活服务 store 取交集；它在运行时不依赖 Typert。宽泛的 `api`／`events` 报告只渲染摘要与签名；精确 `name` 会选择保留的方法／事件 JSDoc，未知或未运行的服务目标会高声失败。
 
 ## 渲染
 
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index d62739acdd..1950c255cb 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -694,32 +694,61 @@ function renderRuntimeApi(
   lines.push(']', '')
   return lines.join('\n')
 }
-/** Render the cross-link "Types:" line for a signature, or '' if none apply. */
-function typeLinks(signature: string, linkedTypePages: Readonly<Record<string, string>>): string {
+/** Opening region delimiter; injected content lives between the pair and the page owns everything outside. */
+export const REGION_BEGIN = '<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->'
+/** Closing region delimiter matching {@link REGION_BEGIN}. */
+export const REGION_END = '<!-- END GENERATED cordis-surface -->'
+
+/**
+ * Render the cross-link "Types:" line for a signature relative to one
+ * subsystems page, or '' if none apply. A type whose primary page IS the
+ * rendering page would link as a fragmentless self-link readers already sit
+ * on, so it is dropped instead.
+ */
+function typeLinks(signature: string, onPage: string, linkedTypePages: Readonly<Record<string, string>>): string {
   const seen = new Set<string>()
   for (const name of Object.keys(linkedTypePages)) {
     if (new RegExp(`\\b${name}\\b`).test(signature)) seen.add(name)
   }
-  if (seen.size === 0) return ''
-  const links = [...seen].sort().map(n => `[${n}](../subsystems/${linkedTypePages[n]})`)
+  const links = [...seen].sort()
+    .filter(name => linkedTypePages[name] !== onPage)
+    .map(name => `[${name}](${linkedTypePages[name]})`)
+  if (links.length === 0) return ''
   return `Types: ${links.join(' · ')}`
 }
 
-/** Render one harness event entry. */
-function renderEvent(e: EventEntry, linkedTypePages: Readonly<Record<string, string>>): string[] {
-  const out = [`### \`${e.name}\` — ${e.mode}`, '']
+/**
+ * GitHub's heading-slug algorithm (lowercase; drop everything but letters,
+ * numbers, spaces, hyphens; spaces become hyphens). Region headings carry
+ * backticks and em-dashes, which VitePress slugifies differently, so each
+ * generated heading is preceded by an explicit `<a id>` carrying this slug —
+ * the historical flat-catalog anchor — making `#ctx<key>--<class>` fragments
+ * resolve identically on GitHub and the published site.
+ */
+function githubSlug(heading: string): string {
+  return heading.toLowerCase().replace(/[^\p{L}\p{N} -]/gu, '').replaceAll(' ', '-')
+}
+
+/** The explicit-anchor line emitted before one generated heading. */
+function anchorFor(headingText: string): string[] {
+  return [`<a id="${githubSlug(headingText)}"></a>`, '']
+}
+
+/** Render one harness event entry onto its owning page, nested under its scope heading. */
+function renderEvent(e: EventEntry, onPage: string, linkedTypePages: Readonly<Record<string, string>>): string[] {
+  const out = [...anchorFor(`${e.name} — ${e.mode}`), `#### \`${e.name}\` — ${e.mode}`, '']
   if (e.doc) out.push(e.doc, '')
   out.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
-  const links = typeLinks(e.signature, linkedTypePages)
+  const links = typeLinks(e.signature, onPage, linkedTypePages)
   if (links) out.push(links, '')
   out.push(`Source: [\`${e.source}\`](../../${e.source.split(':')[0]})`, '')
   return out
 }
 
-/** Render one harness service entry. */
-function renderService(s: ServiceEntry, linkedTypePages: Readonly<Record<string, string>>): string[] {
+/** Render one harness service entry onto its owning page. */
+function renderService(s: ServiceEntry, onPage: string, linkedTypePages: Readonly<Record<string, string>>): string[] {
   const kind = s.abstract ? ' (abstract seam)' : ''
-  const out = [`## \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
+  const out = [...anchorFor(`ctx.${s.key} — ${s.type}${kind}`), `### \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
   if (s.doc) out.push(s.doc, '')
   if (s.methods.length) {
     const declarations = s.methods.flatMap((method, index) => [
@@ -728,7 +757,7 @@ function renderService(s: ServiceEntry, linkedTypePages: Readonly<Record<string,
       method.signature,
     ])
     out.push('```' + FENCE, ...declarations, '```', '')
-    const links = typeLinks(s.methods.map(method => method.signature).join('\n'), linkedTypePages)
+    const links = typeLinks(s.methods.map(method => method.signature).join('\n'), onPage, linkedTypePages)
     if (links) out.push(links, '')
   }
   out.push(`Source: [\`${s.source}\`](../../${s.source.split(':')[0]})`, '')
@@ -746,36 +775,62 @@ const BANNER = [
 const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
 
 /**
- * Render the events catalog deterministically.
- * @param events - validated event entries to render.
- * @param policy - type links and inherited events supplied by the caller.
+ * Render one page's generated `cordis-surface` region: the services mapped to
+ * the page, then the event scopes mapped to it, markers included. Pure and
+ * deterministic given sorted inputs; identical bytes land in both pair sides.
+ * @param page - the owning `docs/subsystems/` page basename, e.g. `core.md`.
+ * @param services - validated services mapped to this page.
+ * @param events - validated events whose scopes map to this page.
+ * @param policy - type links supplied by the caller.
+ * @returns the complete marker-delimited region text.
+ */
+export function renderPageRegion(page: string, services: ServiceEntry[], events: EventEntry[], policy: CordisCatalogPolicy): string {
+  const lines: string[] = [
+    REGION_BEGIN,
+    '',
+    '<a id="cordis-surface"></a>',
+    '',
+    '## Cordis surface',
+    '',
+    'Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).',
+    '',
+  ]
+  for (const s of services) lines.push(...renderService(s, page, policy.linkedTypePages))
+  const scopes = [...new Set(events.map(e => e.scope))].sort()
+  for (const scope of scopes) {
+    lines.push(...anchorFor(`${scope}/* events`), `### \`${scope}/*\` events`, '')
+    for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
+      lines.push(...renderEvent(e, page, policy.linkedTypePages))
+    }
+  }
+  while (lines.at(-1) === '') lines.pop()
+  lines.push(REGION_END)
+  return lines.join('\n')
+}
+
+/**
+ * Render the inherited (pinned vendor) tier as its own generated page.
+ * @param policy - inherited events and services supplied by the caller.
  * @returns the complete generated Markdown document.
  */
-export function renderEvents(events: EventEntry[], policy: CordisCatalogPolicy): string {
+export function renderInheritedPage(policy: CordisCatalogPolicy): string {
   const lines: string[] = [
     ...BANNER,
-    '# Cordis Events Catalog',
+    '# Inherited Cordis Surface',
     '',
-    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.',
+    'The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).',
     '',
     GATE_NOTICE,
     '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).',
-    '',
-    'Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`).',
+    '## Inherited `ctx` members (cordis core + loader/hmr/timer)',
     '',
   ]
-  const scopes = [...new Set(events.map(e => e.scope))].sort()
-  for (const scope of scopes) {
-    lines.push(`## \`${scope}/*\``, '')
-    for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
-      lines.push(...renderEvent(e, policy.linkedTypePages))
-    }
+  for (const s of policy.inheritedServices) {
+    lines.push(`- \`${s.name}\` — ${s.summary} ([\`${s.source}\`](../../${s.source.split(':')[0]}))`)
   }
   lines.push(
-    '## Inherited events (cordis core + loader/hmr/timer)',
     '',
-    'The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier\'s prominence.',
+    '## Inherited events (cordis core + loader/hmr/timer)',
     '',
   )
   for (const e of policy.inheritedEvents) {
@@ -784,35 +839,3 @@ export function renderEvents(events: EventEntry[], policy: CordisCatalogPolicy):
   lines.push('')
   return lines.join('\n')
 }
-
-/**
- * Render the services catalog deterministically.
- * @param services - validated service entries to render.
- * @param policy - type links and inherited services supplied by the caller.
- * @returns the complete generated Markdown document.
- */
-export function renderServices(services: ServiceEntry[], policy: CordisCatalogPolicy): string {
-  const lines: string[] = [
-    ...BANNER,
-    '# Cordis Services Catalog',
-    '',
-    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
-    '',
-    GATE_NOTICE,
-    '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely. Detailed Context, Fiber, Registry, and Service APIs are generated in the [Cordis core API](core/context.md).',
-    '',
-  ]
-  for (const s of services) lines.push(...renderService(s, policy.linkedTypePages))
-  lines.push(
-    '## Inherited `ctx` members (cordis core + loader/hmr/timer)',
-    '',
-    'The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier\'s prominence.',
-    '',
-  )
-  for (const s of policy.inheritedServices) {
-    lines.push(`- \`${s.name}\` — ${s.summary} ([\`${s.source}\`](../../${s.source.split(':')[0]}))`)
-  }
-  lines.push('')
-  return lines.join('\n')
-}
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index 1b6589b6cf..bde52505dc 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -10,8 +10,7 @@ import { afterEach, describe, expect, it } from 'vitest'
 import {
   collectEvents as collectEventsWithPolicy,
   collectServices as collectServicesWithPolicy,
-  renderEvents as renderEventsWithPolicy,
-  renderServices as renderServicesWithPolicy,
+  renderPageRegion,
 } from '../src/cordis-catalog.ts'
 import type {
   CordisCatalogPolicy,
@@ -35,12 +34,12 @@ function collectServices(root: string): ServiceEntry[] {
   return collectServicesWithPolicy(root, TEST_POLICY)
 }
 
-function renderEvents(events: EventEntry[]): string {
-  return renderEventsWithPolicy(events, TEST_POLICY)
+function renderEvents(events: EventEntry[], onPage = 'bash.md'): string {
+  return renderPageRegion(onPage, [], events, TEST_POLICY)
 }
 
-function renderServices(services: ServiceEntry[]): string {
-  return renderServicesWithPolicy(services, TEST_POLICY)
+function renderServices(services: ServiceEntry[], onPage = 'bash.md'): string {
+  return renderPageRegion(onPage, services, [], TEST_POLICY)
 }
 
 const TYPE_FIXTURES = [
@@ -155,7 +154,8 @@ describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => {
       '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param preset - deployment metadata documented outside the subsystems catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, preset: PresetSpec, signal: AbortSignal): Promise<T>',
     ))
     expect(events).toHaveLength(1)
-    expect(renderEvents(events)).toContain('Types: [SessionEvent](../subsystems/core.md)')
+    expect(renderEvents(events)).toContain('Types: [SessionEvent](core.md)')
+    expect(renderEvents(events, 'core.md')).not.toContain('Types: [SessionEvent]')
     expect(renderEvents(events)).not.toContain('[PresetSpec]')
   })
 
diff --git a/packages/typert/generator/tests/cordis-catalog.spec.ts b/packages/typert/generator/tests/cordis-catalog.spec.ts
index 644bb28de2..9474c15145 100644
--- a/packages/typert/generator/tests/cordis-catalog.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog.spec.ts
@@ -3,10 +3,10 @@ import { join, resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import {
   projectCordisCatalog,
-  renderEvents,
-  renderServices,
+  renderInheritedPage,
+  renderPageRegion,
 } from '../src/cordis-catalog.ts'
-import { CORDIS_CATALOG_POLICY } from '../../../../scripts/gen-cordis-catalog.ts'
+import { CORDIS_CATALOG_POLICY, EVENT_SCOPE_PAGE, REGION_BEGIN, REGION_END, SERVICE_PAGE } from '../../../../scripts/gen-cordis-catalog.ts'
 
 const workspaceRoot = resolve(import.meta.dirname, '../../../..')
 
@@ -15,8 +15,22 @@ describe('Typert-backed Cordis catalog', () => {
     const { projector, model } = projectCordisCatalog(workspaceRoot, CORDIS_CATALOG_POLICY)
     const expected = (path: string): string => readFileSync(join(workspaceRoot, path), 'utf8')
 
-    expect(renderEvents([...model.events], CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-catalog/events.md'))
-    expect(renderServices([...model.services], CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-catalog/services.md'))
+    expect(renderInheritedPage(CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-api/inherited.md'))
+    for (const page of [...new Set([...Object.values(SERVICE_PAGE), ...Object.values(EVENT_SCOPE_PAGE)])].sort()) {
+      const region = renderPageRegion(
+        page,
+        [...model.services].filter(s => SERVICE_PAGE[s.key] === page),
+        [...model.events].filter(e => EVENT_SCOPE_PAGE[e.scope] === page),
+        CORDIS_CATALOG_POLICY,
+      )
+      for (const side of [page, page.replace(/\.md$/, '.zh.md')]) {
+        const committed = expected(`docs/subsystems/${side}`)
+        const begin = committed.indexOf(REGION_BEGIN)
+        const end = committed.indexOf(REGION_END)
+        expect(begin, `docs/subsystems/${side} carries the region`).toBeGreaterThanOrEqual(0)
+        expect(committed.slice(begin, end + REGION_END.length)).toBe(region)
+      }
+    }
     expect(projector.renderRuntimeApi(model)).toBe(
       expected('packages/self-modification/tool-cordis/src/api-catalog.ts'),
     )
diff --git a/scripts/cordis-core-api.spec.ts b/scripts/cordis-core-api.spec.ts
index d35899553c..8aef4041a1 100644
--- a/scripts/cordis-core-api.spec.ts
+++ b/scripts/cordis-core-api.spec.ts
@@ -21,13 +21,13 @@ describe('Cordis core API generation', () => {
   it('renders the five detailed pages from pinned vendor declarations', () => {
     const pages = renderCordisCoreApiPages()
     expect([...pages.keys()]).toEqual(CORDIS_CORE_API_PAGES.map(page => page.out))
-    expect(pages.get('docs/cordis-catalog/core/context.md')).toContain('### ctx.extend(meta?)')
-    expect(pages.get('docs/cordis-catalog/core/events.md')).toContain('## DispatchMode')
-    expect(pages.get('docs/cordis-catalog/core/fiber.md')).toContain('## EffectMeta')
-    expect(pages.get('docs/cordis-catalog/core/registry.md')).toContain('## Plugin')
-    expect(pages.get('docs/cordis-catalog/core/service.md')).toContain('### Service.resolveConfig')
+    expect(pages.get('docs/cordis-api/context.md')).toContain('### ctx.extend(meta?)')
+    expect(pages.get('docs/cordis-api/events.md')).toContain('## DispatchMode')
+    expect(pages.get('docs/cordis-api/fiber.md')).toContain('## EffectMeta')
+    expect(pages.get('docs/cordis-api/registry.md')).toContain('## Plugin')
+    expect(pages.get('docs/cordis-api/service.md')).toContain('### Service.resolveConfig')
 
-    const fiber = pages.get('docs/cordis-catalog/core/fiber.md') ?? ''
+    const fiber = pages.get('docs/cordis-api/fiber.md') ?? ''
     expect(fiber).toContain('```\n\nRegister a cleanup-aware effect on this fiber.')
     expect(fiber).toContain('- `execute` — the effect body; see `Effect` for accepted shapes.')
     expect(fiber).toContain('**Returns** a disposer that tears the effect down and settles once done.')
@@ -39,7 +39,7 @@ describe('Cordis core API generation', () => {
     mkdirSync(join(root, 'vendor/cordis/src'), { recursive: true })
     writeFileSync(join(root, 'vendor/cordis/src/service.ts'), 'export class Service {\n  run(): string { return "ok" }\n}\n')
     const page: CordisCoreApiPage = {
-      out: 'docs/cordis-catalog/core/service.md',
+      out: 'docs/cordis-api/service.md',
       title: 'Service',
       intro: 'Service API.',
       sections: [{ kind: 'class', file: 'vendor/cordis/src/service.ts', symbol: 'Service' }],
diff --git a/scripts/cordis-core-api.ts b/scripts/cordis-core-api.ts
index a2400fdb54..a32c1ce8fa 100644
--- a/scripts/cordis-core-api.ts
+++ b/scripts/cordis-core-api.ts
@@ -26,7 +26,7 @@ export interface CordisCoreApiPage {
 /** Explicit editorial grouping for the pinned Cordis core surface. */
 export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
   {
-    out: 'docs/cordis-catalog/core/context.md',
+    out: 'docs/cordis-api/context.md',
     title: 'Context',
     intro: 'The context is the core Cordis object: every service, event, and lifecycle API is reached through `ctx`. Event methods are documented on [Events](events.md), effects and the current fiber on [Fiber](fiber.md), and plugin loading on [Registry](registry.md).',
     sections: [
@@ -35,9 +35,9 @@ export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
     ],
   },
   {
-    out: 'docs/cordis-catalog/core/events.md',
+    out: 'docs/cordis-api/events.md',
     title: 'Events',
-    intro: 'The event-dispatch API mixed into every context. Harness event declarations and their dispatch modes are generated separately in the [Cordis events catalog](../events.md).',
+    intro: 'The event-dispatch API mixed into every context. Harness event declarations and their dispatch modes are generated into each owning [subsystem page](../subsystems/core.md).',
     sections: [
       { kind: 'context-merge', file: 'vendor/cordis/src/events.ts' },
       { kind: 'decl', file: 'vendor/cordis/src/events.ts', symbol: 'EventOptions' },
@@ -45,7 +45,7 @@ export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
     ],
   },
   {
-    out: 'docs/cordis-catalog/core/fiber.md',
+    out: 'docs/cordis-api/fiber.md',
     title: 'Fiber',
     intro: 'A fiber is one loaded plugin instance: its lifecycle state, validated config, and registered effects. `ctx.fiber` is the current fiber, and `ctx.effect()` delegates to it.',
     sections: [
@@ -59,7 +59,7 @@ export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
     ],
   },
   {
-    out: 'docs/cordis-catalog/core/registry.md',
+    out: 'docs/cordis-api/registry.md',
     title: 'Registry',
     intro: 'Plugin loading and dependency injection.',
     sections: [
@@ -69,7 +69,7 @@ export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
     ],
   },
   {
-    out: 'docs/cordis-catalog/core/service.md',
+    out: 'docs/cordis-api/service.md',
     title: 'Service',
     intro: 'The base class for context services. A subclass loaded as a plugin registers itself as `ctx.<name>`.',
     sections: [
@@ -357,7 +357,7 @@ function declarationPaste(ctx: RenderContext, rel: string, symbol: string): { do
 
 function sourceLink(source: string): string {
   const [file, line] = source.split(':')
-  return `[Source](../../../${file}${line === undefined ? '' : `#L${line}`})`
+  return `[Source](../../${file}${line === undefined ? '' : `#L${line}`})`
 }
 
 function unlink(text: string): string {
diff --git a/scripts/cordis-walk.ts b/scripts/cordis-walk.ts
index e414b572d3..0111d1d042 100644
--- a/scripts/cordis-walk.ts
+++ b/scripts/cordis-walk.ts
@@ -1,7 +1,39 @@
-/** Locate the Cordis module merge used by the vendored core API projector. */
+/**
+ * AST helpers shared by the Cordis generators: locate the Cordis module merge
+ * in a source file and enumerate the `interface Context` keys it declares.
+ * The vendored core API projector consumes the merge body; the per-subsystem
+ * region generator's exhaustiveness backstop consumes the key scan.
+ */
 
+import { globSync, readFileSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
 import ts from 'typescript'
 
+/**
+ * Parse every file matching `pattern` (repo-relative, sorted, `/`-normalized)
+ * that textually mentions `interface Context`, yielding each file's cordis
+ * module-merge body. Files without a merge are skipped.
+ * @param scanRoot - Repository root the pattern is resolved against.
+ * @param pattern - Glob selecting the TypeScript files to scan.
+ * @returns One entry per file with a cordis module merge, in path order.
+ */
+export function contextMergeFiles(
+  scanRoot: string,
+  pattern: string,
+): { rel: string; sf: ts.SourceFile; text: string; body: ts.ModuleBlock }[] {
+  const out: { rel: string; sf: ts.SourceFile; text: string; body: ts.ModuleBlock }[] = []
+  for (const rel of globSync(pattern, { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
+    const abs = resolve(scanRoot, rel)
+    const text = readFileSync(abs, 'utf8')
+    if (!text.includes('interface Context')) continue
+    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
+    const body = cordisModuleBody(sf)
+    if (!body) continue
+    out.push({ rel, sf, text, body })
+  }
+  return out
+}
+
 /** The body of the cordis module merge in `sf`: `declare module 'cordis'`
  * (harness packages) or `declare module './context.ts'` (vendor core), or
  * null when the file has neither. */
@@ -13,3 +45,22 @@ export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
   }
   return null
 }
+
+/**
+ * Every `key: Type` property a `declare module 'cordis'` Context merge
+ * declares in one module body.
+ * @param body - The cordis module augmentation block.
+ * @param sf - Owning source file (for text extraction).
+ * @returns key → declared type-name text, in declaration order.
+ */
+export function contextKeyMap(body: ts.ModuleBlock, sf: ts.SourceFile): Map<string, string> {
+  const keyToType = new Map<string, string>()
+  for (const stmt of body.statements) {
+    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Context') continue
+    for (const member of stmt.members) {
+      if (!ts.isPropertySignature(member) || !member.type) continue
+      keyToType.set(member.name.getText(sf), member.type.getText(sf))
+    }
+  }
+  return keyToType
+}
diff --git a/scripts/gen-config-catalog.ts b/scripts/gen-config-catalog.ts
index ebceec916b..a79ffdd47f 100644
--- a/scripts/gen-config-catalog.ts
+++ b/scripts/gen-config-catalog.ts
@@ -819,7 +819,7 @@ export function render(entries: CatalogEntry[]): string {
     '',
     '# Plugin Config Catalog',
     '',
-    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
+    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated `cordis-surface` region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
     '',
     'This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.',
     '',
diff --git a/scripts/gen-cordis-catalog-record.spec.ts b/scripts/gen-cordis-catalog-record.spec.ts
new file mode 100644
index 0000000000..73720e8be8
--- /dev/null
+++ b/scripts/gen-cordis-catalog-record.spec.ts
@@ -0,0 +1,144 @@
+/**
+ * Negative-path coverage for the guarded pair auto-record
+ * (`maybeRecordPair`): the safety property is that regeneration re-records a
+ * pair's `.i18n.yaml` ONLY for a region-confined write over a well-formed,
+ * previously-consistent record — every other state is left for the pairing
+ * gate to report.
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { maybeRecordPair, REGION_BEGIN, REGION_END, spliceRegion } from './gen-cordis-catalog.ts'
+import { blobHash, renderPairMeta } from './translation-pairing.ts'
+
+const PAGE = 'docs/subsystems/fix.md'
+const ZH = 'docs/subsystems/fix.zh.md'
+const META = 'docs/subsystems/fix.i18n.yaml'
+
+function page(prose: string, region: string): string {
+  return `# Fix\n\n${prose}\n\n${REGION_BEGIN}\n${region}\n${REGION_END}\n`
+}
+
+const roots: string[] = []
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+/** Lay out a pair on disk and return { root, before } for a regeneration that already wrote `current`. */
+function setup(options: {
+  beforeEn: string
+  beforeZh: string
+  currentEn: string
+  currentZh: string
+  meta?: string | null
+  omitZhSnapshot?: boolean
+}): { root: string; before: Map<string, Buffer> } {
+  const root = mkdtempSync(join(tmpdir(), 'record-guard-'))
+  roots.push(root)
+  mkdirSync(join(root, 'docs/subsystems'), { recursive: true })
+  writeFileSync(join(root, PAGE), options.currentEn)
+  writeFileSync(join(root, ZH), options.currentZh)
+  const meta = options.meta === undefined
+    ? renderPairMeta(PAGE, blobHash(Buffer.from(options.beforeEn)), ZH, blobHash(Buffer.from(options.beforeZh)))
+    : options.meta
+  if (meta !== null) writeFileSync(join(root, META), meta)
+  const before = new Map<string, Buffer>([[PAGE, Buffer.from(options.beforeEn)]])
+  if (!options.omitZhSnapshot) before.set(ZH, Buffer.from(options.beforeZh))
+  return { root, before }
+}
+
+describe('maybeRecordPair', () => {
+  const beforeEn = page('prose.', 'old region')
+  const beforeZh = page('散文。', 'old region')
+  const currentEn = page('prose.', 'new region')
+  const currentZh = page('散文。', 'new region')
+
+  it('re-records a region-confined write over a consistent record', () => {
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(true)
+    expect(readFileSync(join(root, META), 'utf8'))
+      .toBe(renderPairMeta(PAGE, blobHash(Buffer.from(currentEn)), ZH, blobHash(Buffer.from(currentZh))))
+  })
+
+  it('refuses when the pair was already out of sync before the run', () => {
+    const stale = renderPairMeta(PAGE, blobHash(Buffer.from('drifted long ago\n')), ZH, blobHash(Buffer.from(beforeZh)))
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, meta: stale })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+    expect(readFileSync(join(root, META), 'utf8')).toBe(stale)
+  })
+
+  it('refuses a malformed record even when its hashes are current', () => {
+    // A renamed key with preserved hashes must stay the pairing gate's error,
+    // never become valid through regeneration.
+    const renamedKeys = [
+      '# comment',
+      `fixXmd: ${blobHash(Buffer.from(beforeEn))}`,
+      `fix.zh.md: ${blobHash(Buffer.from(beforeZh))}`,
+      '',
+    ].join('\n')
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, meta: renamedKeys })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+    expect(readFileSync(join(root, META), 'utf8')).toBe(renamedKeys)
+  })
+
+  it('refuses a record with extra entries', () => {
+    const extra = renderPairMeta(PAGE, blobHash(Buffer.from(beforeEn)), ZH, blobHash(Buffer.from(beforeZh)))
+      + `other.md: ${blobHash(Buffer.from(beforeEn))}\n`
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, meta: extra })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+  })
+
+  it('refuses a record with a duplicated expected key', () => {
+    // Map#set would collapse the duplicate back to size 2; the parser must
+    // reject the repeat instead of letting the guard accept the record.
+    const duplicated = [
+      `fix.md: ${blobHash(Buffer.from(beforeEn))}`,
+      `fix.md: ${blobHash(Buffer.from(beforeEn))}`,
+      `fix.zh.md: ${blobHash(Buffer.from(beforeZh))}`,
+      '',
+    ].join('\n')
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, meta: duplicated })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+    expect(readFileSync(join(root, META), 'utf8')).toBe(duplicated)
+  })
+
+  it('refuses when prose drifted alongside the region write', () => {
+    const proseDrift = page('prose, edited by a human.', 'new region')
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn: proseDrift, currentZh })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+  })
+
+  it('refuses a brand-new pair with no record', () => {
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, meta: null })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+  })
+
+  it('refuses when a side has no pre-write snapshot', () => {
+    const { root, before } = setup({ beforeEn, beforeZh, currentEn, currentZh, omitZhSnapshot: true })
+    expect(maybeRecordPair(PAGE, before, root)).toBe(false)
+  })
+})
+
+describe('spliceRegion', () => {
+  it('replaces exactly the cordis-surface region', () => {
+    const doc = `# T\n\nprose\n\n${REGION_BEGIN}\nold\n${REGION_END}\ntail\n`
+    expect(spliceRegion(doc, `${REGION_BEGIN}\nnew\n${REGION_END}`))
+      .toBe(`# T\n\nprose\n\n${REGION_BEGIN}\nnew\n${REGION_END}\ntail\n`)
+  })
+
+  it('fails loud on a page carrying only some other generator\'s region', () => {
+    // Another generator's markers satisfy the generic region grammar but must
+    // never be overwritten by THIS generator's splice.
+    const foreign = '# T\n\n<!-- BEGIN GENERATED other-surface (other-gen.ts) — do not edit between markers -->\ntheirs\n<!-- END GENERATED other-surface -->\n'
+    expect(() => spliceRegion(foreign, `${REGION_BEGIN}\nnew\n${REGION_END}`))
+      .toThrow('expected exactly 1 cordis-surface region, found 0 BEGIN/0 END')
+  })
+
+  it('fails loud on duplicate cordis-surface markers', () => {
+    const doubled = `${REGION_BEGIN}\na\n${REGION_END}\n${REGION_BEGIN}\nb\n${REGION_END}\n`
+    expect(() => spliceRegion(doubled, `${REGION_BEGIN}\nnew\n${REGION_END}`))
+      .toThrow('found 2 BEGIN/2 END')
+  })
+})
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 3cc277152e..120904d4b5 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -1,24 +1,156 @@
 /**
- * Generate committed Cordis artifacts from the Typert catalog projector and
- * the independent vendored-core projector.
+ * Generate the per-subsystem Cordis service/event reference regions from the
+ * Typert catalog projection. Every harness `ctx.<key>` service and event scope
+ * maps to exactly one `docs/subsystems/` page through the curated tables below;
+ * the generator injects each page's surface between its GENERATED markers —
+ * byte-identically into both language sides of the pair — and re-records a
+ * pair's `.i18n.yaml` only when nothing outside the region changed. The
+ * projection enforces event modes, JSDoc parameter/return completeness, and
+ * signature type-link coverage; the inherited (vendor) tier renders to
+ * `docs/cordis-api/inherited.md`. `--check` verifies every generated artifact.
  */
 
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import {
   projectCordisCatalog,
-  renderEvents,
-  renderServices,
+  renderInheritedPage,
+  renderPageRegion,
+  REGION_BEGIN,
+  REGION_END,
 } from '@deepseek-ai/dsh-typert-generator'
 import type { CordisCatalogPolicy } from '@deepseek-ai/dsh-typert-generator'
 import { renderCordisCoreApiPages } from './cordis-core-api.ts'
+import { contextKeyMap, contextMergeFiles } from './cordis-walk.ts'
+import {
+  blobHash,
+  parsePairMeta,
+  partitionGeneratedRegions,
+  renderPairMeta,
+} from './translation-pairing.ts'
 
 const root = resolve(import.meta.dirname, '..')
-const OUT_EVENTS = 'docs/cordis-catalog/events.md'
-const OUT_SERVICES = 'docs/cordis-catalog/services.md'
+const SUBSYSTEMS_DIR = 'docs/subsystems'
+const OUT_INHERITED = 'docs/cordis-api/inherited.md'
 const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts'
 
-/** One primary subsystems page per project type used by a generated signature. */
+export { REGION_BEGIN, REGION_END }
+
+/**
+ * The owning subsystems page for every harness `ctx.<key>` service the
+ * projection discovers. Fail-closed both ways: a discovered key absent here
+ * and an entry whose key the projection no longer discovers are both hard
+ * errors, so the partition can never silently drift from the service surface.
+ */
+export const SERVICE_PAGE: Record<string, string> = {
+  agentLoop: 'core.md',
+  agents: 'core.md',
+  approval: 'approval.md',
+  bash: 'bash.md',
+  bashEnv: 'bash.md',
+  clientModuleHost: 'client-modules.md',
+  codeRuntime: 'code-runtime.md',
+  commands: 'commands.md',
+  compact: 'compaction.md',
+  credentials: 'credentials.md',
+  directoryPicker: 'workspace.md',
+  e2b: 'subprocess.md',
+  fs: 'filesystem.md',
+  goals: 'goal.md',
+  httpServer: 'http-server.md',
+  invariants: 'invariants.md',
+  llm: 'llm-streaming.md',
+  permission: 'permission.md',
+  planMode: 'plan.md',
+  pty: 'pty.md',
+  sandbox: 'sandbox.md',
+  sandboxPolicy: 'sandbox.md',
+  sessionPersistence: 'persistence.md',
+  sessionQuery: 'session-query.md',
+  sessionReferences: 'session-reference.md',
+  sessionProjectionCache: 'session-projection.md',
+  sessionProjections: 'session-projection.md',
+  sessions: 'session.md',
+  settings: 'settings.md',
+  sessionTitle: 'session-title.md',
+  skills: 'skills.md',
+  spillStore: 'spill.md',
+  storage: 'storage.md',
+  storageDomain: 'storage.md',
+  subagents: 'subagent.md',
+  subprocess: 'subprocess.md',
+  systemPrompt: 'system-prompt.md',
+  tasks: 'tasks.md',
+  telemetry: 'telemetry.md',
+  tokenMeter: 'token-meter.md',
+  toolResultPrune: 'compaction.md',
+  tools: 'tools.md',
+  typert: 'typert.md',
+  typertGateway: 'typert.md',
+  userInteraction: 'user-interaction.md',
+  web: 'web.md',
+  workflows: 'workflow.md',
+  workspace: 'workspace.md',
+}
+
+/**
+ * Context keys declared in `interface Context` merges that the rendering
+ * projection cannot see, each with the reason and its documentation owner.
+ * The scan that enforces this list reads EVERY `declare module 'cordis'`
+ * Context merge under `packages/x/x/src/*.ts` — not only root `index.ts`
+ * files with a same-named service class — so a new service can never silently
+ * join this blind spot: it either enters {@link SERVICE_PAGE} or names itself
+ * here.
+ * TODO(cordis-catalog-interface-services): the interface-typed and
+ * non-index-declared entries would all render once the projection resolves a
+ * Context key through its declaring file's imports to the class declaration.
+ */
+export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
+  agent: 'not a service: the DX accessor field on Agent.ctx (root accessor defaulting to undefined) — docs/subsystems/core.md owns the Agent handle',
+  configuredAgentIdentities: 'not a service: launcher-provided boot-context value (ConfiguredAgentIdentities | undefined) — packages/core/agent-loop/README.md owns the launcher contract',
+  launcherSessionQueryPath: 'not a service: launcher-provided boot-context value (string | undefined) — packages/session-query/session-query-sqlite/README.md owns the launcher contract',
+  dshHomePath: 'not a service: boot-provided root accessor function (typeof dshHomePath | undefined) for Loader !!js config expressions — packages/boot/app-boot/README.md owns the boot contract',
+  headlessIo: 'not a service: launcher-provided root accessor value (HeadlessIo | undefined) for the headless bundle runner — packages/bundle/headless/README.md owns the launcher contract',
+  launcherEnvironment: 'not a service: launcher-provided root accessor value (EnvironmentSnapshot | undefined) — packages/util/environment/README.md owns the launcher contract',
+  lsp: 'interface-typed (LspService); implementing class Lsp is not the declared type name — packages/lsp/lsp/README.md owns the surface',
+  apiProxy: 'interface-typed (ApiProxy) with the class in api-proxy.ts, not index.ts — packages/host/apiproxy/README.md owns the surface',
+  appShell: 'client-side interface-typed browser service — packages/client/web/README.md owns the surface',
+  connection: 'client-side interface-typed browser service — packages/client/connection/README.md owns the surface',
+}
+
+/**
+ * The owning subsystems page for every harness event scope (the segment
+ * before the first `/`). Fail-closed exactly like {@link SERVICE_PAGE}.
+ * `slash` lives with the human-command surface: the client slash-input
+ * protocol parses toward command invocation and `dsh-ui-slash` owns the
+ * declarations, but commands.md owns the cross-package command story.
+ */
+export const EVENT_SCOPE_PAGE: Record<string, string> = {
+  'agent': 'core.md',
+  'agent-loop': 'core.md',
+  'approval': 'approval.md',
+  'commands': 'commands.md',
+  'credentials': 'credentials.md',
+  'domain': 'storage.md',
+  'fs': 'filesystem.md',
+  'goal': 'goal.md',
+  'llm': 'llm-streaming.md',
+  'session': 'session.md',
+  'settings': 'settings.md',
+  'skills': 'skills.md',
+  'subagent': 'subagent.md',
+  'system-prompt': 'system-prompt.md',
+  'telemetry': 'telemetry.md',
+  'tools': 'tools.md',
+  'workflow': 'workflow.md',
+}
+
+/**
+ * One primary subsystems page per project type used by a generated
+ * signature. This stays curated because union names intentionally do not
+ * reuse the type-equivalence manifest's map-symbol entries and some symbols
+ * appear on more than one page.
+ */
 export const LINK_MAP: Readonly<Record<string, string>> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
@@ -94,12 +226,12 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   FsWriteIntent: 'filesystem.md',
   FsWriteOutcome: 'filesystem.md',
   CreateGoalRequest: 'goal.md',
-  CreateGoalResult: 'goal.md',
   EditGoalRequest: 'goal.md',
   GoalBlockReason: 'goal.md',
   GoalChanged: 'goal.md',
   GoalRef: 'goal.md',
   GoalView: 'goal.md',
+  CreateGoalResult: 'goal.md',
   CommandDefinition: 'commands.md',
   CommandDescriptor: 'commands.md',
   CommandResult: 'commands.md',
@@ -248,6 +380,18 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   TelemetryRecord: 'telemetry.md',
   WorkflowRunInfo: 'workflow.md',
   WorkflowStartRequest: 'workflow.md',
+  ProjectionDefinition: 'session-projection.md',
+  SessionProjectionMap: 'session-projection.md',
+  ProjectionChangeListener: 'session-projection.md',
+  ProjectionSnapshot: 'session-projection.md',
+  ProjectionCheckpoint: 'session-projection.md',
+  DirectoryPickerCapability: 'workspace.md',
+  TypertContribution: 'invariants.md',
+  TypertFace: 'invariants.md',
+  TypertPackageFilter: 'invariants.md',
+  TypertPackageRecord: 'invariants.md',
+  TypertSchemaFilter: 'invariants.md',
+  TypertSchemaRecord: 'invariants.md',
 }
 
 /** TypeScript lib and pinned framework types with no repository-owned data page. */
@@ -277,31 +421,19 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
   ManualCompactAgentContext: 'manual compaction service input is owned by packages/compact/compact/src/index.ts',
-  DirectoryPickerCapability: 'picker interaction contract is owned by packages/host/directory-picker/README.md',
   CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
   DomainImpl: 'domain implementation contract is owned by packages/storage/storage-domain/README.md',
-  ProjectionDefinition: 'projection unit contract is owned by packages/session/session-projection/README.md',
-  SessionProjectionMap: 'merge-extensible projection key map is owned by packages/session/session-projection/src/types.ts',
-  ProjectionChangeListener: 'change-feed listener contract is owned by packages/session/session-projection/src/index.ts',
-  ProjectionSnapshot: 'watermark snapshot shape is owned by packages/session/session-projection/src/index.ts',
-  ProjectionCheckpoint: 'persisted checkpoint row map is owned by packages/session/session-projection/src/index.ts',
   CommandExecution: 'executor return contract is owned by packages/interaction/commands/src/index.ts',
-  TypertContribution: 'registry contribution contract is owned by packages/typert/registry/README.md',
-  TypertFace: 'registry face identity is owned by packages/typert/registry/README.md',
-  TypertPackageFilter: 'registry package query filter is owned by packages/typert/registry/README.md',
-  TypertPackageRecord: 'registry package record is owned by packages/typert/registry/README.md',
-  TypertSchemaFilter: 'registry schema query filter is owned by packages/typert/registry/README.md',
-  TypertSchemaRecord: 'registry schema record is owned by packages/typert/registry/README.md',
-  TypeRTDisposer: 'TypeRT lifecycle contract is owned by packages/typert/type-meta/README.md',
   'z.core.JSONSchema.BaseSchema': 'zod projection output is owned by the zod v4 API',
   'z.core.ToJSONSchemaParams': 'zod projection parameters are owned by the zod v4 API',
+  TypeRTDisposer: 'TypeRT lifecycle contract is owned by packages/typert/type-meta/README.md',
+  InvokeRemoteRequest: 'gateway invocation contract is owned by packages/api/gateway/README.md',
   LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
   ThemeTokens: 'service-local token dictionary is owned by packages/client/ui-theme/src/index.ts',
   Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
   WebUpgradeRoute:
     'upgrade route registration contract is owned by packages/host/webserver/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
-  InvokeRemoteRequest: 'gateway invocation contract is owned by packages/api/gateway/README.md',
   KnobState: 'projection unit state shape is owned by packages/interaction/permission/README.md',
   PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
@@ -351,15 +483,171 @@ export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
   ],
 }
 
-/** CLI entry: default writes every artifact; `--check` reports stale files.
+
+/**
+ * Splice a page's generated cordis-surface region into its Markdown content.
+ * The page must contain exactly one cordis-surface region (the markers are
+ * part of the hand-owned page skeleton once, then owned by the generator);
+ * zero or several is a partition error the caller reports with the page path.
+ * The match is on THIS generator's exact markers, not the generic region
+ * grammar, so a page carrying only some other generator's region fails loud
+ * instead of having that region overwritten.
+ * @param content - the page's current full Markdown text.
+ * @param region - the freshly rendered marker-delimited region.
+ * @returns the page text with the region replaced.
+ */
+export function spliceRegion(content: string, region: string): string {
+  const lines = content.split('\n')
+  const begins = lines.flatMap((line, index) => (line === REGION_BEGIN ? [index] : []))
+  const ends = lines.flatMap((line, index) => (line === REGION_END ? [index] : []))
+  if (begins.length !== 1 || ends.length !== 1) {
+    throw new Error(`expected exactly 1 cordis-surface region, found ${begins.length} BEGIN/${ends.length} END; add the BEGIN/END cordis-surface markers once`)
+  }
+  const begin = begins[0] ?? -1
+  const end = ends[0] ?? -1
+  if (end < begin) throw new Error('cordis-surface END marker precedes its BEGIN')
+  return [...lines.slice(0, begin), ...region.split('\n'), ...lines.slice(end + 1)].join('\n')
+}
+
+/**
+ * Compute every generated artifact: the inherited-tier page, the model-facing
+ * runtime API module, plus, per mapped subsystems page, the pair's two updated
+ * documents with the injected region. Fail-loud partition checks live here: an
+ * unmapped service/event scope, a mapping whose page file does not exist, a
+ * curated entry whose key/scope the projection no longer discovers, and a
+ * mapped page missing its markers are all aggregated errors.
+ * @returns `[repo-relative path, exact content]` for every generated artifact.
+ */
+export function computeOutputs(): [string, string][] {
+  const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
+  const services = [...model.services]
+  const events = [...model.events]
+  const problems: string[] = []
+
+  const discoveredKeys = new Set(services.map(s => s.key))
+  const discoveredScopes = new Set(events.map(e => e.scope))
+  for (const s of services) {
+    if (!Object.hasOwn(SERVICE_PAGE, s.key)) problems.push(`service ctx.${s.key} (${s.source}) has no SERVICE_PAGE entry; every service maps to exactly one subsystems page.`)
+  }
+  for (const scope of discoveredScopes) {
+    if (!Object.hasOwn(EVENT_SCOPE_PAGE, scope)) problems.push(`event scope '${scope}/*' has no EVENT_SCOPE_PAGE entry; every event scope maps to exactly one subsystems page.`)
+  }
+  for (const key of Object.keys(SERVICE_PAGE)) {
+    if (!discoveredKeys.has(key)) problems.push(`SERVICE_PAGE maps 'ctx.${key}' but the projection discovers no such service; remove the stale entry.`)
+  }
+  for (const scope of Object.keys(EVENT_SCOPE_PAGE)) {
+    if (!discoveredScopes.has(scope)) problems.push(`EVENT_SCOPE_PAGE maps '${scope}/*' but the projection discovers no such scope; remove the stale entry.`)
+  }
+  // The rendering projection only sees a Context key it can resolve to a
+  // documented service class. This independent scan reads EVERY Context merge
+  // so a key the projection cannot render must either be rendered (mapped) or
+  // carry a named SERVICE_WALK_EXEMPTIONS reason — never vanish silently.
+  const declaredKeys = new Map<string, string>()
+  for (const { rel, sf, body } of contextMergeFiles(root, 'packages/*/*/src/*.ts')) {
+    for (const key of contextKeyMap(body, sf).keys()) {
+      if (!declaredKeys.has(key)) declaredKeys.set(key, rel)
+    }
+  }
+  for (const [key, rel] of declaredKeys) {
+    const rendered = discoveredKeys.has(key)
+    const exempt = Object.hasOwn(SERVICE_WALK_EXEMPTIONS, key)
+    if (!rendered && !exempt) {
+      problems.push(`ctx.${key} (${rel}) is declared in a Context merge but invisible to the rendering projection; map it in SERVICE_PAGE (after making it renderable) or name it in SERVICE_WALK_EXEMPTIONS with its documentation owner.`)
+    }
+    if (rendered && exempt) problems.push(`ctx.${key} is rendered by the projection but still listed in SERVICE_WALK_EXEMPTIONS; remove the stale exemption.`)
+  }
+  for (const key of Object.keys(SERVICE_WALK_EXEMPTIONS)) {
+    if (!declaredKeys.has(key)) problems.push(`SERVICE_WALK_EXEMPTIONS names 'ctx.${key}' but no Context merge declares it; remove the stale exemption.`)
+  }
+  if (problems.length > 0) throw new Error(`gen-cordis-catalog: ${problems.length} partition violation(s):\n${problems.map(p => `  ${p}`).join('\n')}`)
+
+  const pages = [...new Set([...Object.values(SERVICE_PAGE), ...Object.values(EVENT_SCOPE_PAGE)])].sort()
+  const outputs: [string, string][] = [
+    [OUT_INHERITED, renderInheritedPage(CORDIS_CATALOG_POLICY)],
+    [OUT_RUNTIME_API, projector.renderRuntimeApi(model)],
+  ]
+  for (const page of pages) {
+    const region = renderPageRegion(
+      page,
+      services.filter(s => SERVICE_PAGE[s.key] === page),
+      events.filter(e => EVENT_SCOPE_PAGE[e.scope] === page),
+      CORDIS_CATALOG_POLICY,
+    )
+    for (const side of [page, page.replace(/\.md$/, '.zh.md')]) {
+      const rel = `${SUBSYSTEMS_DIR}/${side}`
+      let current: string
+      try {
+        current = readFileSync(resolve(root, rel), 'utf8')
+      } catch {
+        // Both pair sides must exist before a region can be injected; the
+        // pairing gate owns pair completeness, this generator names the miss.
+        problems.push(`${rel}: mapped subsystems page does not exist.`)
+        continue
+      }
+      try {
+        outputs.push([rel, spliceRegion(current, region)])
+      } catch (error) {
+        problems.push(`${rel}: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+  }
+  if (problems.length > 0) throw new Error(`gen-cordis-catalog: ${problems.length} page violation(s):\n${problems.map(p => `  ${p}`).join('\n')}`)
+  return outputs
+}
+
+/**
+ * Re-record a pair's `.i18n.yaml` after a region write ONLY when the write is
+ * region-confined: both sides' region-stripped content must be byte-equal to
+ * the region-stripped previous content whose hashes the record holds. The
+ * caller supplies the previous bytes (read before writing); human-content
+ * drift leaves the record untouched so the pairing gate still demands the
+ * normal translation flow.
+ * @param pageRel - repo-relative English page path (`docs/subsystems/x.md`).
+ * @param before - pre-write bytes per repo-relative path.
+ * @param scanRoot - repository root override for tests.
+ * @returns true when the record was refreshed.
+ */
+export function maybeRecordPair(pageRel: string, before: Map<string, Buffer>, scanRoot: string = root): boolean {
+  const zhRel = pageRel.replace(/\.md$/, '.zh.md')
+  const metaRel = pageRel.replace(/\.md$/, '.i18n.yaml')
+  const metaAbs = resolve(scanRoot, metaRel)
+  let meta: string
+  try {
+    meta = readFileSync(metaAbs, 'utf8')
+  } catch {
+    // No record yet: a brand-new pair is recorded by the author's --write
+    // after review, never silently by regeneration.
+    return false
+  }
+  // The record must be exactly the well-formed two-entry shape for THIS pair;
+  // a malformed or renamed-key sidecar is the pairing gate's problem to
+  // report, never something regeneration silently repairs into validity.
+  const recorded = parsePairMeta(meta)
+  const names = [pageRel, zhRel].map(rel => rel.split('/').at(-1) ?? rel)
+  if (!recorded || recorded.size !== 2 || !names.every(name => recorded.has(name))) return false
+  for (const rel of [pageRel, zhRel]) {
+    const previous = before.get(rel)
+    if (!previous) return false
+    if (recorded.get(rel.split('/').at(-1) ?? rel) !== blobHash(previous)) return false
+    const current = readFileSync(resolve(scanRoot, rel))
+    const strippedBefore = partitionGeneratedRegions(previous.toString('utf8')).stripped
+    const strippedAfter = partitionGeneratedRegions(current.toString('utf8')).stripped
+    if (strippedBefore !== strippedAfter) return false
+  }
+  const source = readFileSync(resolve(scanRoot, pageRel))
+  const zh = readFileSync(resolve(scanRoot, zhRel))
+  writeFileSync(metaAbs, renderPairMeta(pageRel, blobHash(source), zhRel, blobHash(zh)))
+  return true
+}
+
+/** CLI entry: default regenerates every artifact, `--check` fails if any is
+ * stale. Guarded behind an entry-point check so importing this module for
+ * tests neither regenerates the committed files nor calls process.exit.
  * @returns nothing; writes files or reports freshness through the process.
  */
 export function main(): void {
-  const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
   const outputs: [string, string][] = [
-    [OUT_EVENTS, renderEvents([...model.events], CORDIS_CATALOG_POLICY)],
-    [OUT_SERVICES, renderServices([...model.services], CORDIS_CATALOG_POLICY)],
-    [OUT_RUNTIME_API, projector.renderRuntimeApi(model)],
+    ...computeOutputs(),
     ...renderCordisCoreApiPages(),
   ]
   if (process.argv.includes('--check')) {
@@ -369,25 +657,51 @@ export function main(): void {
       try {
         committed = readFileSync(resolve(root, out), 'utf8')
       } catch {
-        // Only ENOENT is expected; either read failure has the same remedy.
+        // Only ENOENT (not yet generated) is expected; a present-but-unreadable
+        // file is not a state this repo produces. Either way the remedy is the
+        // same — regenerate — so treat a read failure as "stale".
         committed = null
       }
       if (committed !== content) stale.push(out)
     }
     if (stale.length === 0) {
-      console.log(`gen-cordis-catalog: ${outputs.length} generated file(s) are up to date.`)
+      console.log(`gen-cordis-catalog: ${outputs.length} generated file(s)/region(s) are up to date.`)
       process.exit(0)
     }
-    console.error(`gen-cordis-catalog: ${stale.join(' and ')} ${stale.length === 1 ? 'is' : 'are'} stale. Run \`pnpm run gen-cordis-catalog\` and commit the result.`)
+    console.error(`gen-cordis-catalog: stale — ${stale.join(', ')}. Run \`pnpm run gen-cordis-catalog\` and commit the result.`)
     process.exit(1)
   }
 
+  const before = new Map<string, Buffer>()
+  for (const [out] of outputs) {
+    try {
+      before.set(out, readFileSync(resolve(root, out)))
+    } catch {
+      // First generation of this artifact; nothing to guard, nothing to record.
+    }
+  }
+  let changedPages = 0
+  let recorded = 0
   for (const [out, content] of outputs) {
     const destination = resolve(root, out)
+    if (before.get(out)?.toString('utf8') === content) continue
     mkdirSync(dirname(destination), { recursive: true })
     writeFileSync(destination, content)
+    changedPages++
   }
-  console.log(`gen-cordis-catalog: wrote ${outputs.length} generated file(s).`)
+  for (const page of [...new Set([...Object.values(SERVICE_PAGE), ...Object.values(EVENT_SCOPE_PAGE)])]) {
+    const rel = `${SUBSYSTEMS_DIR}/${page}`
+    const zhRel = rel.replace(/\.md$/, '.zh.md')
+    const wroteEither = [rel, zhRel].some((side) => {
+      const previous = before.get(side)
+      return previous !== undefined && previous.toString('utf8') !== readFileSync(resolve(root, side), 'utf8')
+    })
+    if (wroteEither && maybeRecordPair(rel, before)) recorded++
+  }
+  console.log(`gen-cordis-catalog: ${outputs.length} artifact(s) computed, ${changedPages} written, ${recorded} pair record(s) refreshed.`)
 }
 
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) main()
+// Run only when invoked as a script, not when imported by a test.
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  main()
+}
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 4f72b1d953..1c4cce0fa3 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -1344,7 +1344,7 @@ function renderIndex(docs: GraphDoc[]): string {
   const maintenance = 'mixed: each linked page declares generated, hybrid, or curated mode'
   return [
     ...generatedHeader('Documentation Graph Index'),
-    'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [subsystems/](subsystems/core.md).',
+    'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the [subsystem pages](subsystems/core.md) (types + the generated `cordis-surface` regions) and [tool-catalog.md](tool-catalog.md).',
     '',
     'The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).',
     '',
diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts
index 800497ddb7..5294242e27 100644
--- a/scripts/gen-persistence-catalog.ts
+++ b/scripts/gen-persistence-catalog.ts
@@ -352,7 +352,7 @@ export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnv
     '',
     '# Session Persistence Event Catalog',
     '',
-    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
+    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
     '',
     'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).',
     '',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 39ed4d7620..a68ab874f0 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -608,7 +608,7 @@ export function render(catalog: ToolCatalog): string {
     '',
     '# Tool Schema Catalog',
     '',
-    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [subsystems/](subsystems/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
+    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [subsystem pages](subsystems/core.md) (the types plus each page\'s generated `cordis-surface` wiring region) — this page is the *tools* the agent is offered.',
     '',
     'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).',
     '',
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index ebdce88f6d..c2ca4136d3 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -276,7 +276,7 @@ describe('docsPages locale routes', () => {
     const translated = rootPages.filter(page => page.contentLocale === 'zh-CN')
     const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US')
 
-    expect(translated).toHaveLength(20)
+    expect(translated).toHaveLength(37)
     expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true)
     expect(fallbacks.map(page => page.source).sort()).toEqual([
       'docs/subsystems/commands.md',
@@ -286,11 +286,11 @@ describe('docsPages locale routes', () => {
   })
 
   it('publishes the Cordis core API under matching locale structures', () => {
-    const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md']
+    const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md', 'inherited.md']
     for (const file of files) {
       const root = docsPages.find(page => page.route === `reference/cordis-api/${file}`)
       const english = docsPages.find(page => page.route === `en/reference/cordis-api/${file}`)
-      expect(root?.source).toBe(`docs/cordis-catalog/core/${file}`)
+      expect(root?.source).toBe(`docs/cordis-api/${file}`)
       expect(root?.section).toBe('Cordis API')
       expect(english?.source).toBe(root?.source)
       expect(english?.section).toBe('Cordis Core API')
diff --git a/scripts/project-doc-site.ts b/scripts/project-doc-site.ts
index e3397237a3..55c7204d78 100644
--- a/scripts/project-doc-site.ts
+++ b/scripts/project-doc-site.ts
@@ -131,6 +131,12 @@ function destinationRange(rawNode: string, type: 'link' | 'image' | 'definition'
   return { start, end: rawNode.length }
 }
 
+// `#fragment` suffixes pass through verbatim. Generated cordis-surface
+// headings carry explicit `<a id>` anchors with the GitHub slug, so those
+// fragments resolve on the published site too; hand-written headings rely on
+// VitePress's own slugger, which differs from GitHub's for punctuation-heavy
+// text — hand-authored cross-page fragments should prefer plain-text headings
+// or explicit anchors.
 function splitTarget(url: string): { path: string; suffix: string } {
   const boundary = url.search(/[?#]/)
   if (boundary === -1) return { path: url, suffix: '' }
diff --git a/scripts/translation-pairing.manifest.json b/scripts/translation-pairing.manifest.json
index 7c77929ba3..112cd3ae4d 100644
--- a/scripts/translation-pairing.manifest.json
+++ b/scripts/translation-pairing.manifest.json
@@ -7,7 +7,7 @@
     "docs/agent-lifecycle.md",
     "docs/capability-seams.md",
     "docs/config-catalog.md",
-    "docs/cordis-catalog/",
+    "docs/cordis-api/",
     "docs/event-producer-consumer.md",
     "docs/graph-atlas.md",
     "docs/i18n/style-samples.md",
diff --git a/scripts/translation-pairing.spec.ts b/scripts/translation-pairing.spec.ts
index 1073495d08..b89df38f52 100644
--- a/scripts/translation-pairing.spec.ts
+++ b/scripts/translation-pairing.spec.ts
@@ -12,11 +12,13 @@ import {
   translationPairPaths,
 } from './translation-pairing-record.ts'
 import {
+  blobHash,
   isTranslationScopeFile,
   pairAnchorOfArgument,
   parseTranslationMarkdown,
   parseTranslationPairingCliArgs,
   parseTranslationPairingManifest,
+  partitionGeneratedRegions,
   translationStructureDiff,
   translationStructureSignature,
 } from './translation-pairing.ts'
@@ -292,3 +294,42 @@ describe('pair CLI arguments', () => {
     expect(() => parseTranslationPairingCliArgs(['--cached', '--write', 'docs/foo.md'])).toThrow('read-only')
   })
 })
+
+describe('generated regions', () => {
+  const BEGIN = '<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->'
+  const END = '<!-- END GENERATED cordis-surface -->'
+
+  it('partitions marker-delimited regions from the hand-owned remainder', () => {
+    const doc = `# T\n\nprose\n\n${BEGIN}\ninjected\n${END}\ntail\n`
+    const { regions, stripped } = partitionGeneratedRegions(doc)
+    expect(regions).toEqual([`${BEGIN}\ninjected\n${END}`])
+    expect(stripped).toBe('# T\n\nprose\n\ntail\n')
+  })
+
+  it('treats a document without markers as one hand-owned remainder', () => {
+    const { regions, stripped } = partitionGeneratedRegions('# T\n\nprose\n')
+    expect(regions).toEqual([])
+    expect(stripped).toBe('# T\n\nprose\n')
+  })
+
+  it('rejects unbalanced or nested markers', () => {
+    expect(() => partitionGeneratedRegions(`${END}\n`)).toThrow('without a BEGIN')
+    expect(() => partitionGeneratedRegions(`${BEGIN}\n`)).toThrow('without an END')
+    expect(() => partitionGeneratedRegions(`${BEGIN}\n${BEGIN}\n${END}\n`)).toThrow('nested')
+  })
+
+  it('rejects mismatched slugs and malformed marker lines', () => {
+    expect(() => partitionGeneratedRegions('<!-- BEGIN GENERATED a -->\nx\n<!-- END GENERATED b -->\n'))
+      .toThrow("END slug 'b' does not match its BEGIN slug 'a'")
+    expect(() => partitionGeneratedRegions('<!-- BEGIN GENERATED a --> trailing\nx\n<!-- END GENERATED a -->\n'))
+      .toThrow('malformed generated region marker line')
+    expect(() => partitionGeneratedRegions('x\n<!-- END GENERATED a --> tail\n'))
+      .toThrow('malformed generated region marker line')
+  })
+
+  it('computes the exact git blob hash', () => {
+    // `git hash-object` of the empty file and of "x\n" — pinned upstream values.
+    expect(blobHash(Buffer.from(''))).toBe('e69de29bb2d1d6434b8b29ae775ad8c2e48c5391')
+    expect(blobHash(Buffer.from('x\n'))).toBe('587be6b4c3f93f93c489c0111bba5596147a26cb')
+  })
+})
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
index 6d6893f843..417e836578 100644
--- a/scripts/translation-pairing.ts
+++ b/scripts/translation-pairing.ts
@@ -2,13 +2,122 @@
  * Pure parsing and structural helpers for the bilingual-document pairing
  * gate. Kept separate from the CLI so corpus discovery and signature behavior
  * can be regression-tested without reading or mutating the repository tree.
+ * Also the one home of the generated-region grammar and the pair-record
+ * primitives, shared by the pairing gate and the region-injecting generators.
  */
 
+import { createHash } from 'node:crypto'
+import { basename } from 'node:path'
 import { fromMarkdown } from 'mdast-util-from-markdown'
 import { gfmFromMarkdown } from 'mdast-util-gfm'
 import { gfm } from 'micromark-extension-gfm'
 import type { Nodes } from 'mdast'
 
+/** Complete opening marker line: `<!-- BEGIN GENERATED <slug> … -->` (slug captured). */
+const GENERATED_REGION_BEGIN_LINE = /^<!-- BEGIN GENERATED (\S+)(?: [^>]*)? -->$/
+/** Complete closing marker line: `<!-- END GENERATED <slug> -->` (slug captured). */
+const GENERATED_REGION_END_LINE = /^<!-- END GENERATED (\S+) -->$/
+/** Loose marker detector: any line that LOOKS like a region marker must parse as one. */
+const GENERATED_REGION_MARKER_HINT = /^<!-- (?:BEGIN|END) GENERATED /
+
+/**
+ * Extract every generated region (markers included) and the document with
+ * those regions removed. Regions are line-delimited: a marker occupies its
+ * whole line, must be a complete well-formed marker, and the closing slug
+ * must match the opener. The stripped form is what "human content" means for
+ * the region-aware pair-record guard.
+ *
+ * @param content - Full Markdown document text.
+ * @returns The regions in document order and the region-free remainder.
+ * @throws Error on an unopened END, unclosed BEGIN, nested BEGIN, malformed
+ *   marker line, or a closing slug that does not match its opener.
+ */
+export function partitionGeneratedRegions(content: string): { regions: string[]; stripped: string } {
+  const lines = content.split('\n')
+  const regions: string[] = []
+  const kept: string[] = []
+  let open: { slug: string; lines: string[] } | null = null
+  for (const line of lines) {
+    const begin = GENERATED_REGION_BEGIN_LINE.exec(line)
+    if (begin?.[1]) {
+      if (open) throw new Error('generated region BEGIN marker nested inside an open region')
+      open = { slug: begin[1], lines: [line] }
+      continue
+    }
+    const end = GENERATED_REGION_END_LINE.exec(line)
+    if (end?.[1]) {
+      if (!open) throw new Error('generated region END marker without a BEGIN')
+      if (end[1] !== open.slug) throw new Error(`generated region END slug '${end[1]}' does not match its BEGIN slug '${open.slug}'`)
+      open.lines.push(line)
+      regions.push(open.lines.join('\n'))
+      open = null
+      continue
+    }
+    if (GENERATED_REGION_MARKER_HINT.test(line)) {
+      throw new Error(`malformed generated region marker line: ${JSON.stringify(line)}`)
+    }
+    if (open) open.lines.push(line)
+    else kept.push(line)
+  }
+  if (open) throw new Error('generated region BEGIN marker without an END')
+  return { regions, stripped: kept.join('\n') }
+}
+
+/**
+ * Full git blob hash of file content (what `git hash-object` prints).
+ * @param content - Exact file bytes.
+ * @returns The 40-hex-digit SHA-1 blob hash.
+ */
+export function blobHash(content: Buffer): string {
+  const hash = createHash('sha1')
+  hash.update(`blob ${content.byteLength}\0`)
+  hash.update(content)
+  return hash.digest('hex')
+}
+
+const PAIR_META_LINE = /^([^:#]+\.md): ([0-9a-f]{40})$/
+
+/**
+ * Parse a `foo.i18n.yaml` consistency record into basename → recorded blob
+ * hash, or undefined when any non-comment line deviates from the exact
+ * `<basename>.md: <40-hex>` shape or repeats a key. Consumers must
+ * additionally require exactly the two expected basenames — a renamed key is
+ * a malformed record, never a silently-missing entry.
+ * @param content - Sidecar file text.
+ * @returns The recorded map, or undefined for a malformed record.
+ */
+export function parsePairMeta(content: string): Map<string, string> | undefined {
+  const out = new Map<string, string>()
+  for (const line of content.split('\n')) {
+    if (line === '' || line.startsWith('#')) continue
+    const match = PAIR_META_LINE.exec(line)
+    if (!match?.[1] || !match[2]) return undefined
+    if (out.has(match[1])) return undefined
+    out.set(match[1], match[2])
+  }
+  return out
+}
+
+/**
+ * Render a `foo.i18n.yaml` consistency record.
+ * @param source - Repo-relative English path.
+ * @param sourceHash - Blob hash of the English side.
+ * @param zh - Repo-relative Chinese path.
+ * @param zhHash - Blob hash of the Chinese side.
+ * @returns The exact sidecar file content.
+ */
+export function renderPairMeta(source: string, sourceHash: string, zh: string, zhHash: string): string {
+  return [
+    '# 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 ${source}`,
+    `${basename(source)}: ${sourceHash}`,
+    `${basename(zh)}: ${zhHash}`,
+    '',
+  ].join('\n')
+}
+
 /** Validated shape of `scripts/translation-pairing.manifest.json`. */
 export interface TranslationPairingManifest {
   /** Source documents exempt from pairing because they are generated, instructional, or bilingual by construction. */
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 2bc097c88c..317ddec122 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1679,6 +1679,21 @@
       "doc": "docs/subsystems/permission.md",
       "symbol": "PresetSpec",
       "source": "packages/interaction/permission/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/session-projection.md",
+      "symbol": "ProjectionDefinition",
+      "source": "packages/session/session-projection/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/session-projection.md",
+      "symbol": "ProjectionSnapshot",
+      "source": "packages/session/session-projection/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/session-projection.md",
+      "symbol": "ProjectionChangeListener",
+      "source": "packages/session/session-projection/src/index.ts"
     }
   ]
 }
diff --git a/scripts/verify-translation-pairing.ts b/scripts/verify-translation-pairing.ts
index 59818183e3..be5c1816ae 100644
--- a/scripts/verify-translation-pairing.ts
+++ b/scripts/verify-translation-pairing.ts
@@ -23,6 +23,7 @@ import {
   parseTranslationMarkdown,
   parseTranslationPairingCliArgs,
   parseTranslationPairingManifest,
+  partitionGeneratedRegions,
   isTranslationScopeFile,
   TRANSLATION_SCOPE_GLOB_EXCLUDES,
   translationStructureDiff,
@@ -227,6 +228,27 @@ for (const source of [...pairAnchors].sort()) {
     continue
   }
 
+  // Generated regions are language-invariant: the exact same generator output
+  // (markers included) must appear in both sides, in the same order. The
+  // structural signature below compares the region content again as part of
+  // the whole document; this dedicated check exists to name the divergence
+  // precisely and to reject a region grammar violation on either side.
+  let sourceRegions: { regions: string[]; stripped: string }
+  let zhRegions: { regions: string[]; stripped: string }
+  try {
+    sourceRegions = partitionGeneratedRegions(sourceContent.toString('utf8'))
+    zhRegions = partitionGeneratedRegions(zhContent.toString('utf8'))
+  } catch (error) {
+    errors.push(`${source} ↔ ${zh}: ${error instanceof Error ? error.message : String(error)}`)
+    state.set(source, 'out-of-sync')
+    continue
+  }
+  if (sourceRegions.regions.length !== zhRegions.regions.length
+    || sourceRegions.regions.some((region, index) => region !== zhRegions.regions[index])) {
+    errors.push(`${source} ↔ ${zh}: generated regions differ between the pair — regenerate (the generator writes both sides byte-identically)`)
+    state.set(source, 'out-of-sync')
+  }
+
   const sourceTree = parseTranslationMarkdown(sourceContent.toString('utf8'))
   const zhTree = parseTranslationMarkdown(zhContent.toString('utf8'))
   if (!linksTo(zhTree, basename(source))) {
diff --git a/website/docs.ts b/website/docs.ts
index 07f470319b..551224edaa 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -261,29 +261,46 @@ const coreDataReference = pairedPages(([
   ['core.md', '核心数据结构', 'Core data structures', 0],
   ['scope.md', '作用域', 'Scopes', 1],
   ['session.md', '会话', 'Sessions', 2],
-  ['system-prompt.md', '系统提示词', 'System prompts', 4],
-  ['tools.md', '工具', 'Tools', 5],
-  ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming', 6],
-  ['bash.md', 'Bash 执行', 'Bash execution', 7],
-  ['filesystem.md', '文件系统', 'Filesystem', 9],
-  ['code-runtime.md', '代码运行时', 'Code runtime', 10],
-  ['compaction.md', '上下文压缩', 'Compaction', 11],
-  ['subagent.md', '子代理', 'Subagents', 12],
-  ['workflow.md', '工作流', 'Workflows', 13],
-  ['skills.md', '技能', 'Skills', 14],
-  ['approval.md', '审批', 'Approvals', 15],
-  ['user-interaction.md', '用户交互', 'User interaction', 16],
-  ['sandbox.md', '沙箱', 'Sandboxing', 18],
-  ['web.md', 'Web 访问', 'Web access', 19],
-  ['persistence.md', '会话持久化', 'Session persistence', 20],
-  ['settings.md', '用户设置', 'User settings', 21],
-  ['credentials.md', '用户凭据', 'User credentials', 22],
+  ['session-query.md', '会话查询', 'Session query', 3],
+  ['session-reference.md', '会话引用', 'Session references', 4],
+  ['session-title.md', '会话标题', 'Session titles', 5],
+  ['settings.md', '用户设置', 'User settings', 6],
+  ['credentials.md', '用户凭据', 'User credentials', 7],
+  ['system-prompt.md', '系统提示词', 'System prompts', 8],
+  ['tools.md', '工具', 'Tools', 9],
+  ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming', 10],
+  ['token-meter.md', 'Token 计量', 'Token metering', 11],
+  ['bash.md', 'Bash 执行', 'Bash execution', 12],
+  ['subprocess.md', '子进程', 'Subprocesses', 13],
+  ['tasks.md', '后台任务', 'Background tasks', 14],
+  ['filesystem.md', '文件系统', 'Filesystem', 15],
+  ['lsp.md', 'LSP 导航', 'LSP navigation', 16],
+  ['code-runtime.md', '代码运行时', 'Code runtime', 17],
+  ['compaction.md', '上下文压缩', 'Compaction', 18],
+  ['subagent.md', '子代理', 'Subagents', 19],
+  ['workflow.md', '工作流', 'Workflows', 20],
+  ['skills.md', '技能', 'Skills', 21],
+  ['approval.md', '审批', 'Approvals', 22],
+  ['permission.md', '权限预设', 'Permission presets', 23],
+  ['plan.md', '计划模式', 'Plan mode', 24],
+  ['user-interaction.md', '用户交互', 'User interaction', 25],
+  ['sandbox.md', '沙箱', 'Sandboxing', 26],
+  ['web.md', 'Web 访问', 'Web access', 27],
+  ['spill.md', 'Spill 存储', 'Spill storage', 28],
+  ['persistence.md', '会话持久化', 'Session persistence', 29],
+  ['storage.md', '存储', 'Storage', 30],
+  ['workspace.md', '工作区', 'Workspaces', 31],
+  ['http-server.md', 'HTTP 服务器', 'HTTP server', 32],
+  ['client-modules.md', '客户端模块', 'Client modules', 33],
+  ['invariants.md', '运行时不变式', 'Runtime invariants', 35],
+  ['session-projection.md', '会话投影', 'Session projections', 36],
+  ['telemetry.md', '遥测', 'Telemetry', 37],
 ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
   source: `docs/subsystems/${file}`,
   route: `reference/subsystems/${file}`,
   label: { root: rootLabel, en: enLabel },
   sidebar: { root: 'zh-reference', en: 'en-reference' },
-  section: { root: '数据结构', en: 'Data structures' },
+  section: { root: '子系统', en: 'Subsystems' },
   order,
   ...(file === 'core.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
 })))
@@ -306,8 +323,6 @@ const reference = mirroredPages([
   ...([
     ['docs/config-catalog.md', 'reference/config-catalog.md', '插件配置', 'Plugin configuration'],
     ['docs/tool-catalog.md', 'reference/tool-catalog.md', 'Tool Schema', 'Tool schemas'],
-    ['docs/cordis-catalog/services.md', 'reference/cordis-catalog/services.md', '服务', 'Services'],
-    ['docs/cordis-catalog/events.md', 'reference/cordis-catalog/events.md', '事件', 'Events'],
     ['docs/persistence-catalog.md', 'reference/persistence-catalog.md', '持久化事件', 'Persistence events', 'deep'],
   ] as const).map(([source, route, rootLabel, enLabel, outline], order): MirroredPage => ({
     source,
@@ -325,8 +340,9 @@ const reference = mirroredPages([
     ['fiber.md', 'Fiber', 'Fiber'],
     ['registry.md', 'Plugin Registry', 'Plugin Registry'],
     ['service.md', 'Service', 'Service'],
+    ['inherited.md', '继承接口面', 'Inherited surface'],
   ] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
-    source: `docs/cordis-catalog/core/${file}`,
+    source: `docs/cordis-api/${file}`,
     route: `reference/cordis-api/${file}`,
     contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
@@ -335,16 +351,16 @@ const reference = mirroredPages([
     order,
   })),
   ...([
-    ['goal.md', '目标', 'Goals', 3],
-    ['pty.md', 'PTY 会话', 'PTY sessions', 8],
-    ['commands.md', '命令', 'Human commands', 17],
+    ['goal.md', '目标', 'Goals', 13],
+    ['pty.md', 'PTY 会话', 'PTY sessions', 25],
+    ['commands.md', '命令', 'Human commands', 37],
   ] as const).map(([file, rootLabel, enLabel, order]): MirroredPage => ({
     source: `docs/subsystems/${file}`,
     route: `reference/subsystems/${file}`,
     contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
-    section: { root: '数据结构', en: 'Data structures' },
+    section: { root: '子系统', en: 'Subsystems' },
     order,
   })),
   ...([

From 2886ba45db2a144d711fa3f009598d98aec0efe5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 03:48:16 +0800
Subject: [PATCH 418/516] docs: give subsystems/ its own README index; retire
 the data-structures-catalog framing

core.md doubled as the folder index: its intro claimed "this folder catalogs the data structures" and carried the 38-row page table, wording that predates the one-page-per-subsystem shape where every page also carries its generated Cordis surface. The folder index now lives in docs/subsystems/README.md (page table plus the type-equiv note), and core.md is one subsystem page among siblings: the spine vocabulary. Structural referents move with it: the docs/AGENTS.md tier table and update rule, development.md's type-equiv pointer, the dsh-code-review skill, the two owning catalog Agent Notes, and website/docs.ts (README projects as reference/subsystems/index.md and takes the docs/subsystems folder alias; sidebar orders shift by one). Remaining "data-structure catalog" / "sub-page" phrasing in active notes and READMEs is reworded to subsystem-page terms in both languages; touched pairs re-recorded; translation-prompt snapshot re-recorded (its example embeds development.md).
---
 ...eneric-long-running-tool-runtime.i18n.yaml |  4 +-
 ...06-20-generic-long-running-tool-runtime.md |  2 +-
 ...20-generic-long-running-tool-runtime.zh.md |  2 +-
 ...-20-core-data-structures-catalog.i18n.yaml |  2 +-
 ...2026-06-20-core-data-structures-catalog.md | 12 +--
 .../2026-07-02-tool-schema-catalog.i18n.yaml  |  4 +-
 .../process/2026-07-02-tool-schema-catalog.md |  2 +-
 .../2026-07-02-tool-schema-catalog.zh.md      |  2 +-
 .agents/skills/dsh-code-review/SKILL.md       |  2 +-
 docs/AGENTS.md                                | 14 +--
 docs/development.i18n.yaml                    |  4 +-
 docs/development.md                           |  2 +-
 docs/development.zh.md                        |  2 +-
 docs/subsystems/README.i18n.yaml              |  6 ++
 docs/subsystems/README.md                     | 50 +++++++++++
 docs/subsystems/README.zh.md                  | 50 +++++++++++
 docs/subsystems/compaction.i18n.yaml          |  4 +-
 docs/subsystems/compaction.md                 |  2 +-
 docs/subsystems/compaction.zh.md              |  2 +-
 docs/subsystems/core.i18n.yaml                |  4 +-
 docs/subsystems/core.md                       | 57 +-----------
 docs/subsystems/core.zh.md                    | 57 +-----------
 .../subprocess/subprocess/README.i18n.yaml    |  4 +-
 packages/subprocess/subprocess/README.md      |  2 +-
 packages/subprocess/subprocess/README.zh.md   |  2 +-
 scripts/project-doc-site.spec.ts              |  4 +-
 website/docs.ts                               | 90 ++++++++++---------
 27 files changed, 198 insertions(+), 190 deletions(-)
 create mode 100644 docs/subsystems/README.i18n.yaml
 create mode 100644 docs/subsystems/README.md
 create mode 100644 docs/subsystems/README.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
index cb9ed4275a..863045f2ce 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.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 .agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
-2026-06-20-generic-long-running-tool-runtime.md: 90100ea8f146e505c4fbb95760781839bd4bd34a
-2026-06-20-generic-long-running-tool-runtime.zh.md: bdcd8e8fe2a50033177354ce5ce043c4b5264621
+2026-06-20-generic-long-running-tool-runtime.md: 8cf6a34c3e4fc042bd73c147d83838734dfc9585
+2026-06-20-generic-long-running-tool-runtime.zh.md: 5af06b78e97980822687cdc82d9b0672a42b6fc2
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 90100ea8f1..8cf6a34c3e 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -23,7 +23,7 @@ Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into in
 
 ## Runtime contract
 
-The literal types live in the [task data-structure catalog](../../../../docs/subsystems/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
+The literal types live on the [tasks subsystem page](../../../../docs/subsystems/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
 
 `outputLimitBytes` is producer-owned presentation policy, not a registry buffer. The registry validates and projects it unchanged into `TaskSnapshot`; generic control surfaces apply the cap to complete model-facing output after adding their own status or notice metadata. Omitting it preserves the existing surface behavior, so the runtime does not impose a hidden default on unrelated producer families.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
index bdcd8e8fe2..5af06b78e9 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -23,7 +23,7 @@ Status: implemented
 
 ## 运行时契约
 
-字面类型见[任务数据结构目录](../../../../docs/subsystems/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
+字面类型见[任务子系统页面](../../../../docs/subsystems/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
 
 `outputLimitBytes` 是生产方拥有的呈现策略，而非注册表缓冲区。注册表校验该值，并将其原样投影到 `TaskSnapshot`；通用控制接口添加自身的状态或通知元数据后，再将该上限应用于完整的面向模型输出。省略该值时保持现有接口行为，因此运行时不会向无关的生产方类别施加隐式默认值。
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 0883a5e9ab..1b1a93fc99 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: a8de47a462da13f316236fb7da3f4bfb57edae21
+2026-06-20-core-data-structures-catalog.md: b358ad54652e5b16ae90037c128cf756bcfdaed3
 2026-06-20-core-data-structures-catalog.zh.md: d84c2befaee4c2032b358ed1a7949ac0151ae74c
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index a8de47a462..b358ad5465 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -16,16 +16,16 @@ A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type
 
 ### What counts as "core" — the spine-vs-seam line
 
-The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on a sub-page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
+The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own seam page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
 
-The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a sub-page detail.*** Worked through:
+The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a seam-page detail.*** Worked through:
 
 - A data structure is **core** if it flows through the agent-loop spine — the loop holds, derives, streams, or logs it on every turn regardless of which plugins load (`Message`, `StreamChunk`, `SessionEvent`, the `Agent` handle) — **or** it is the single headline type a plugin author writes against a pipeline (`ToolDefinition`).
-- `ToolDefinition` is core (it is what every tool author writes) **even though the loop never holds one** — authoring-importance overrides the strict flows-through-spine rule for this one headline type. But its typing machinery — `ValueSchemaSpec`, `ParameterSchemaSpec`, `InferValue`, and `InferArgs` — is a sub-page detail. That is the spine-vs-seam line made sharp.
+- `ToolDefinition` is core (it is what every tool author writes) **even though the loop never holds one** — authoring-importance overrides the strict flows-through-spine rule for this one headline type. But its typing machinery — `ValueSchemaSpec`, `ParameterSchemaSpec`, `InferValue`, and `InferArgs` — is a seam-page detail. That is the spine-vs-seam line made sharp.
 - `ToolSchema` is core (it is a field of `GenerateOptions`, the model request that flows through every step) even though it is conceptually part of the tool pipeline — *flows through the spine* wins over *conceptual home* when they conflict.
-- The tool-presentation vocabulary (`ToolCallView`/`ToolResultView`, …), the `SessionPersistence` durability seam, and bash vocabulary are sub-pages.
+- The tool-presentation vocabulary (`ToolCallView`/`ToolResultView`, …), the `SessionPersistence` durability seam, and bash vocabulary are seam pages.
 
-`core.md` is a **self-contained spine doc**: it states the exact type definition of each spine structure with minimal prose and links to sub-pages for the per-seam detail. The sub-pages are `llm-streaming.md`, `session.md`, `persistence.md` (split from session along the in-memory-model vs. durability-seam line), `tools.md`, and `bash.md`.
+`core.md` is a **self-contained spine doc**: it states the exact type definition of each spine structure with minimal prose and links to sibling seam pages for the per-seam detail; the folder's [README](../../../../docs/subsystems/README.md) indexes every page. The original seam pages are `llm-streaming.md`, `session.md`, `persistence.md` (split from session along the in-memory-model vs. durability-seam line), `tools.md`, and `bash.md`.
 
 ### The `ts type-equiv` mechanism — literal AND drift-proof
 
@@ -58,4 +58,4 @@ The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and de
 - The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
-- Since 2026-07-27 the sub-page tier spans every service-bearing subsystem: nine lean pages (permission presets, plan mode, runtime invariants, the HTTP carrier, storage — owning both `ctx.storage` and `ctx.storageDomain` — TUI extensions, workspaces, client modules, telemetry) cover the ten `ctx` services that had none, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
+- Since 2026-07-27 the seam-page tier spans every service-bearing subsystem: nine lean pages (permission presets, plan mode, runtime invariants, the HTTP carrier, storage — owning both `ctx.storage` and `ctx.storageDomain` — TUI extensions, workspaces, client modules, telemetry) cover the ten `ctx` services that had none, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml
index b1098546b7..d97c4dd0b7 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.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 .agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
-2026-07-02-tool-schema-catalog.md: c8cc69df428f6eee0f66ed976865afe2a0702448
-2026-07-02-tool-schema-catalog.zh.md: a1af928cc799974b93d2c8e29792790bc1f4e9e6
+2026-07-02-tool-schema-catalog.md: 673b51831512662c4e2cc3b79cd85b149c78f585
+2026-07-02-tool-schema-catalog.zh.md: 8e47d807a2490e362bb3db6d1d634c75c60997e3
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
index c8cc69df42..673b518315 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-02-tool-schema-catalog.zh.md)
 
 ## Problem
 
-The repository had no single reference for the names, descriptions, and JSON Schemas actually exposed to the model. Source declarations are scattered and runtime-composed, while the existing Cordis and data-structure catalogs cover wiring and vocabulary rather than tools.
+The repository had no single reference for the names, descriptions, and JSON Schemas actually exposed to the model. Source declarations are scattered and runtime-composed, while the existing Cordis reference and subsystem pages cover wiring and vocabulary rather than tools.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
index a1af928cc7..8e47d807a2 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-仓库此前没有一份统一的参考文档来记录实际暴露给模型的工具名称、描述与 JSON Schema。源码声明分散各处且在运行时组合，而既有的 Cordis 目录和数据结构目录覆盖的是接线与词汇，而非工具。
+仓库此前没有一份统一的参考文档来记录实际暴露给模型的工具名称、描述与 JSON Schema。源码声明分散各处且在运行时组合，而既有的 Cordis 参考和子系统页面覆盖的是接线与词汇，而非工具。
 
 ## 决策
 
diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md
index 81f63fac2f..c8a52f5d50 100644
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -21,7 +21,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
 
 1. **New prose receives semantic review.** Use [dsh-prose-standard](../dsh-prose-standard/SKILL.md) to critically review every added or changed Markdown passage, JSDoc, comment, prompt, description, diagnostic, and visible string. Verify required coverage, accuracy, placement, and editorial quality against the owning code or behavior; automated checks do not establish those properties.
 2. **Docs match the code.** Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home.
-3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [subsystems](../../../docs/subsystems/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
+3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [subsystems](../../../docs/subsystems/README.md) page and any `type-equiv` entry. Internal types need no catalog entry.
 4. **Registrations clean up.** Verify each new registry contribution satisfies the disposal-test contract in [packages/AGENTS.md](../../../packages/AGENTS.md).
 5. **Invariant companions are semantic.** For every touched `./invariant`, require an owner event-stream or mutable-data relationship at its authoritative boundary; service or method presence, plugin metadata or effects, and fixed pure examples belong in type, load, or unit tests. Accept an empty installer when its package-specific reason establishes that no plausible runtime relationship exists; do not demand an invented check merely to eliminate emptiness ([repository rule](../../../AGENTS.md#conventions); [package contract](../../../packages/AGENTS.md)).
 6. **Required evidence exists.** Verify the author ran the [relevant local checks](../../../AGENTS.md#run-relevant-checks-locally) for the diff and that CI covers the exhaustive matrix; review the semantic gaps neither can detect.
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 5194544f95..88c90678de 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -21,23 +21,25 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
 | [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
-| [subsystems/](subsystems/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) |
-| [Agent Notes](../.agents/notes/README.md) | Decision records under their own lifecycle contract | Migration plans, checklists, and spec-speak once implemented; archived notes are frozen history |
+| [subsystems/](subsystems/README.md) | One reference page per subsystem: literal type shapes, semantics, and the generated Cordis surface | Behavior narration (→ architecture.md) |
+| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and concise verification contract; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
 | [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
 | [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
-| Package README | Per-package config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc or catalog restatement, other packages' concerns |
-| [development.md](development.md) | Contributor onboarding: setup, daily workflow, and CI shape at summary level | Runtime rationale (→ Agent Notes), drifting gate inventories |
-| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/core.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind (regions included) |
+| Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
+| [development.md](development.md) | First-stop contributor onboarding: local setup, daily workflow, and CI shape at summary level; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), gate-by-gate enumerations that drift from `package.json` scripts |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind (regions included) |
 | Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
 
+Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type shapes → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link.
+
 ## Writing rules
 
 - **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The [subsystems catalog](subsystems/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
 - Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams".
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 13c766cc80..00673a9415 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: 134109fd2a09dfa36aaf2ccdba14daccf896da60
-development.zh.md: 741a860770ee3b20fe94cb0b4993bb281b605b26
+development.md: f7084403b30e8a6d12c4ef2b886f8fb61ed39b26
+development.zh.md: 9d3606cf741f25318c630e08e8ac84ad5ee8d345
diff --git a/docs/development.md b/docs/development.md
index 134109fd2a..f7084403b3 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -156,7 +156,7 @@ Pick the tag that matches the urgency so anyone scanning the code can tell a rel
 
 ### Documenting types verbatim (`ts type-equiv`)
 
-The [core data structures](subsystems/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
+The [subsystems](subsystems/README.md) pages paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
 
 ```json
 { "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 741a860770..9d3606cf74 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -156,7 +156,7 @@ pnpm run demo:acp
 
 ### 逐字记录类型（`ts type-equiv`）
 
-[核心数据结构](subsystems/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
 { "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
new file mode 100644
index 0000000000..ec72119627
--- /dev/null
+++ b/docs/subsystems/README.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 docs/subsystems/README.md
+README.md: 59e5a4db09d114e96c19dc0fe29a5ebe8d8c8d32
+README.zh.md: 6b5fa58bf45654708b08d780aa0e17a8d90b7e17
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
new file mode 100644
index 0000000000..59e5a4db09
--- /dev/null
+++ b/docs/subsystems/README.md
@@ -0,0 +1,50 @@
+# Subsystems
+
+English | [中文](README.zh.md)
+
+One page per subsystem of the DeepSeek Harness: what it is, the data structures it moves, and — where a `ctx` service or event scope backs it — a generated **Cordis surface** section carrying its service and event reference. The folder complements [architecture.md](../architecture.md), which describes *behavior* across subsystems (the service map, the session/turn/step lifecycle, the event taxonomy); each page here is the reference for one subsystem's vocabulary and wiring.
+
+| Page | Owns |
+|---|---|
+| [core.md](core.md) | the spine vocabulary every turn traffics in — `Message`/`ContentBlock`, `StreamChunk`, `SessionEvent`, the `Agent` handle, `ToolDefinition`, branded ids, the `…Map → derived-union` pattern |
+| [llm-streaming.md](llm-streaming.md) | the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
+| [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
+| [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
+| [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API seams |
+| [goal.md](goal.md) | persisted goal identity, lifecycle snapshots, activation, change records, and round attribution |
+| [commands.md](commands.md) | the human-command seam: definitions, adapter discovery, direct invocation, results, and parsing views |
+| [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events |
+| [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
+| [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits |
+| [credentials.md](credentials.md) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo`, provider source layers |
+| [session-query.md](session-query.md) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages |
+| [session-title.md](session-title.md) | durable title snapshots, source provenance, and the asynchronous provider contract |
+| [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
+| [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
+| [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
+| [approval.md](approval.md) | the one-shot user-approval seam: `ApprovalRequest`, `ApprovalOutcome`, per-session policy, audit and answerer contracts |
+| [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashProcess` handles |
+| [subprocess.md](subprocess.md) | the subprocess seam: fully-explicit `SubprocessSpawnSpec`, offset-based output readers, unclassified `SubprocessOutcome`, and the managed `DSH_*` environment vocabulary |
+| [pty.md](pty.md) | persistent terminal ids, backend/session contracts, send readiness, bounded reads, and owner-visible snapshots |
+| [sandbox.md](sandbox.md) | per-session policy resolution and the process-confinement seam: file-effect modes, execution/provider policies, `ConfinedArgv`, enforcement and fail-closed errors |
+| [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy |
+| [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` |
+| [lsp.md](lsp.md) | the LSP navigation seam: `LspQueryRequest`/`Result`, `LspProvider`/`Service`, four operations, `LspError` |
+| [skills.md](skills.md) | the skill service: discovery priority, `SkillSummary`/`SkillDefinition`, session-prefix catalog, model-facing `skill` loading |
+| [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface |
+| [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split |
+| [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider availability, `WebError` |
+| [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
+| [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
+| [permission.md](permission.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event |
+| [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
+| [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
+| [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the static dist fallback, index taps |
+| [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
+| [tui.md](tui.md) | the terminal-extension seam: `TuiOverlayRequest`/`Host`/`Session`, close reasons and outcomes, the modal queue |
+| [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
+| [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
+| [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
+| [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
+
+> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated **Cordis surface** section.
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
new file mode 100644
index 0000000000..6b5fa58bf4
--- /dev/null
+++ b/docs/subsystems/README.zh.md
@@ -0,0 +1,50 @@
+# 子系统
+
+[English](README.md) | 中文
+
+每个子系统一页，覆盖 DeepSeek Harness 的全部子系统：它是什么、它操作哪些数据结构，以及——当它由某个 `ctx` 服务或事件作用域支撑时——一段生成的 **Cordis surface** 小节，承载其服务与事件参考。本目录与 [architecture.md](../architecture.md) 互补：后者描述跨子系统的*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；这里的每一页是单个子系统词汇与接线的参考。
+
+| 页面 | 负责内容 |
+|---|---|
+| [core.md](core.md) | 每个轮次都在使用的主干词汇——`Message`/`ContentBlock`、`StreamChunk`、`SessionEvent`、`Agent` 句柄、`ToolDefinition`、品牌化 id，以及 `…Map → 派生联合` 模式 |
+| [llm-streaming.md](llm-streaming.md) | `StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
+| [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
+| [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
+| [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
+| [goal.md](goal.md) | 持久 goal 标识、生命周期快照、激活、变更记录与 Round 归属 |
+| [commands.md](commands.md) | 人类命令 seam：定义、适配器发现、直接调用、结果与解析视图 |
+| [session.md](session.md) | 完整的 `SessionEventMap` 变体目录、`TurnTrigger`/`TurnEndReason`、`deriveMessages()`、执行封闭与独立事件 |
+| [persistence.md](persistence.md) | 持久性 seam：`SessionPersistence`、JSONL + SQLite 后端、`session/flush`、崩溃恢复、`SessionHeader` |
+| [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
+| [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
+| [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
+| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 |
+| [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
+| [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
+| [user-interaction.md](user-interaction.md) | UI 支持的人工问答 seam：`AskUserQuestionRequest`、answer/options 词汇、提供方 API、错误分类体系 |
+| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 契约 |
+| [bash.md](bash.md) | bash 执行器 seam：`BashExecRequest`/`Spec`、`BashRunResult`、后台 `BashProcess` 句柄 |
+| [subprocess.md](subprocess.md) | 子进程 seam：完全显式的 `SubprocessSpawnSpec`、基于偏移的输出读取器、不含分类的 `SubprocessOutcome`，以及受管 `DSH_*` 环境词汇 |
+| [pty.md](pty.md) | 持久化终端 ID、后端/会话契约、发送就绪状态、有界读取与 owner 可见快照 |
+| [sandbox.md](sandbox.md) | 每会话策略解析与进程约束 seam：文件效果模式、执行/提供方策略、`ConfinedArgv`、强制执行与故障关闭错误 |
+| [code-runtime.md](code-runtime.md) | 代码执行 seam：`CodeRunRequest`/`Result`、绑定命名空间、捕获日志、`CodeRunFailure` 分类体系 |
+| [filesystem.md](filesystem.md) | 文件系统 seam：`FsTarget`、读/写/编辑结果、观测到的文件状态、`FsErrorCode` |
+| [lsp.md](lsp.md) | LSP 导航 seam：`LspQueryRequest`/`Result`、`LspProvider`/`Service`、四种操作、`LspError` |
+| [skills.md](skills.md) | skill（技能）服务：发现优先级、`SkillSummary`/`SkillDefinition`、会话前缀目录、面向模型的 `skill` 加载 |
+| [compaction.md](compaction.md) | 压缩（compaction）seam：`compact/*` 会话事件、`CompactionResult`、`CompactService` 接口 |
+| [subagent.md](subagent.md) | subagent seam：命名提供方注册表、`SubagentStartRequest`/`Result`/`Run`、启动时与运行时能力拆分 |
+| [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
+| [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
+| [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
+| [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
+| [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
+| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
+| [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
+| [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
+| [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
+| [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
+| [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
+| [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
+| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
+
+> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis surface** 小节。
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 5481b2feb1..eb2332a715 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 126c6c7c7df125cf991ea074e0165481c09455dc
-compaction.zh.md: 9fb01a41a92367b9bb3f4586f35b5d0baf613bbc
+compaction.md: eeea249fa7a9f95e607edb10e6a8c93a24162b64
+compaction.zh.md: 24c55f062404ff827292f324392347ad59bb7846
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 126c6c7c7d..eeea249fa7 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -20,7 +20,7 @@ The lock brackets the **whole** operation: `compact/start` is appended first, th
 
 The markers are lock time points, not an exclusive container. An unrelated idle injection can appear between a standalone manual start and end while summarization is pending. The manual path revalidates only its selected positional span, so that injected context survives after the replacement checkpoint. A live unmatched start blocks every entry point; an unmatched start before a newer `session/end-seed` is stale evidence from a prior lifecycle and is ignored.
 
-These variants are merged inside a `declare module '@deepseek-ai/dsh-session'` block, so — unlike the top-level types on the other sub-pages — they are not pasted as a drift-checked ` ```ts type-equiv ` block (the `verify-type-equiv` extractor matches only top-level declarations by name). The payload table above is the catalog entry; follow the source link for the authoritative shapes.
+These variants are merged inside a `declare module '@deepseek-ai/dsh-session'` block, so — unlike the top-level types on the other subsystem pages — they are not pasted as a drift-checked ` ```ts type-equiv ` block (the `verify-type-equiv` extractor matches only top-level declarations by name). The payload table above is the catalog entry; follow the source link for the authoritative shapes.
 
 ## `CompactionResult`
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 9fb01a41a9..24c55f0624 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -20,7 +20,7 @@
 
 这些标记表示锁的时间点，而不是排他的容器。摘要等待期间，不相关的空闲注入可以出现在独立的手动 start 与 end 之间。手动路径只重新验证所选位置 span，因此替换检查点之后仍保留该注入上下文。活动的未匹配 start 会阻塞所有入口点；较新 `session/end-seed` 之前的未匹配 start 是先前生命周期留下的陈旧证据，会被忽略。
 
-这些变体在 `declare module '@deepseek-ai/dsh-session'` 块内合并，因此——与其他子页面上的顶层类型不同——它们不以漂移检查的 ` ```ts type-equiv ` 块粘贴（`verify-type-equiv` 提取器只按名称匹配顶层声明）。上方的载荷表即为目录条目；权威形状请循源码链接查看。
+这些变体在 `declare module '@deepseek-ai/dsh-session'` 块内合并，因此——与其他子系统页面上的顶层类型不同——它们不以漂移检查的 ` ```ts type-equiv ` 块粘贴（`verify-type-equiv` 提取器只按名称匹配顶层声明）。上方的载荷表即为目录条目；权威形状请循源码链接查看。
 
 ## `CompactionResult`
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 48d6fc9c71..0994de32ec 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 7e62de88519e5c0bf3a1a0b94de93635767f9f7b
-core.zh.md: ef5b70ae336d55fd25c2251372705912473d07f7
+core.md: 8f27727d63e598fbf31b09a87ab53ad686155b4f
+core.zh.md: fff5bd502cbed6f2167eb23731fb5c3825efb7af
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 7e62de8851..8f27727d63 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -2,7 +2,7 @@
 
 English | [中文](core.zh.md)
 
-This folder catalogs the **data structures** of the DeepSeek Harness — what each core type represents, its literal shape, and where the full detail lives. It complements [architecture.md](../architecture.md), which describes *behavior* (the service map, the session/turn/step lifecycle, the event taxonomy); this page describes the *vocabulary* that behavior moves around.
+This page catalogs the **core** data structures of the DeepSeek Harness — what each spine type represents, its literal shape, and where the full detail lives. It complements [architecture.md](../architecture.md), which describes *behavior* (the service map, the session/turn/step lifecycle, the event taxonomy); this page describes the *vocabulary* that behavior moves around. The sibling subsystem pages are indexed in the [folder README](README.md).
 
 ## What counts as "core"
 
@@ -13,50 +13,8 @@ Precisely, a data structure is **core** if either:
 1. it flows through the agent-loop spine — the loop holds it, derives it, streams it, or logs it on every turn (a `Message`, a `StreamChunk`, a `SessionEvent`, the `Agent` handle itself), independent of which plugins are present; **or**
 2. it is the single headline type a plugin author writes against a pipeline — `ToolDefinition` (what every tool *is*).
 
-Everything else is documented on a **sub-page**, not here. The rule that draws the line: *the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a sub-page detail.* So `ToolDefinition` is core, but the `ValueSchemaSpec`/`ParameterSchemaSpec` inference machinery that types it, the `ToolCallView`/`ToolResultView` render-intent vocabulary that renders it, and the `SessionPersistence` seam that stores the event log are not — they live on the sub-pages below.
+Everything else is documented on its own subsystem page, not here. The rule that draws the line: *the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is another page’s detail.* So `ToolDefinition` is core, but the `ValueSchemaSpec`/`ParameterSchemaSpec` inference machinery that types it, the `ToolCallView`/`ToolResultView` render-intent vocabulary that renders it, and the `SessionPersistence` seam that stores the event log are not — they live on their own pages ([index](README.md)).
 
-| Sub-page | Owns |
-|---|---|
-| [llm-streaming.md](llm-streaming.md) | the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
-| [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
-| [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
-| [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API seams |
-| [goal.md](goal.md) | persisted goal identity, lifecycle snapshots, activation, change records, and round attribution |
-| [commands.md](commands.md) | the human-command seam: definitions, adapter discovery, direct invocation, results, and parsing views |
-| [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events |
-| [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
-| [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits |
-| [credentials.md](credentials.md) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo`, provider source layers |
-| [session-query.md](session-query.md) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages |
-| [session-title.md](session-title.md) | durable title snapshots, source provenance, and the asynchronous provider contract |
-| [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
-| [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
-| [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
-| [approval.md](approval.md) | the one-shot user-approval seam: `ApprovalRequest`, `ApprovalOutcome`, per-session policy, audit and answerer contracts |
-| [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashProcess` handles |
-| [subprocess.md](subprocess.md) | the subprocess seam: fully-explicit `SubprocessSpawnSpec`, offset-based output readers, unclassified `SubprocessOutcome`, and the managed `DSH_*` environment vocabulary |
-| [pty.md](pty.md) | persistent terminal ids, backend/session contracts, send readiness, bounded reads, and owner-visible snapshots |
-| [sandbox.md](sandbox.md) | per-session policy resolution and the process-confinement seam: file-effect modes, execution/provider policies, `ConfinedArgv`, enforcement and fail-closed errors |
-| [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy |
-| [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` |
-| [lsp.md](lsp.md) | the LSP navigation seam: `LspQueryRequest`/`Result`, `LspProvider`/`Service`, four operations, `LspError` |
-| [skills.md](skills.md) | the skill service: discovery priority, `SkillSummary`/`SkillDefinition`, session-prefix catalog, model-facing `skill` loading |
-| [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface |
-| [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split |
-| [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider availability, `WebError` |
-| [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
-| [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
-| [permission.md](permission.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event |
-| [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
-| [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
-| [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the static dist fallback, index taps |
-| [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
-| [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
-| [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
-| [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
-| [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
-
-> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](#cordis-surface).
 
 ## The `…Map → derived-union` pattern
 
@@ -323,15 +281,6 @@ interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
-  /**
-   * Whether the owning adapter knows this route only because configuration
-   * declared it — a gateway or self-hosted server it ships nothing about.
-   * Absent means the adapter draws no such distinction; false means it does
-   * and this route is one of its own. Only the adapter can answer: a stored
-   * profile is how a user-added route AND a corrected shipped one both look
-   * from outside.
-   */
-  declared?: boolean
 }
 ```
 
@@ -999,7 +948,7 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index ef5b70ae33..fff5bd502c 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -2,7 +2,7 @@
 
 [English](core.md) | 中文
 
-本目录编目 DeepSeek Harness 的**数据结构**：每个核心类型代表什么、它的字面形状，以及完整细节在哪里。它与 [architecture.md](../architecture.md) 互补——后者描述*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；本页描述行为所操作的*词汇*。
+本页编目 DeepSeek Harness 的**核心**数据结构：每个主干类型代表什么、它的字面形状，以及完整细节在哪里。它与 [architecture.md](../architecture.md) 互补——后者描述*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；本页描述行为所操作的*词汇*。同级的各子系统页面见[目录 README](README.md)。
 
 ## 什么算"核心"
 
@@ -13,50 +13,8 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数
 1. 它流经 agent loop 主干——循环在每个轮次中持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄本身），与当前加载了哪些插件无关；**或者**
 2. 它是插件作者面向某条流水线编写的代表性类型——`ToolDefinition`（每个工具*是什么*）。
 
-其他一切都记录在**子页面**上，而非本页。划线的规则是：*你编写、持有或接收的类型是核心；为它提供类型推导、渲染或持久化的机制是子页面细节*。因此 `ToolDefinition` 是核心，但为它提供类型推导的 `ValueSchemaSpec`/`ParameterSchemaSpec` 机制、为它提供渲染意图的 `ToolCallView`/`ToolResultView` 词汇，以及存储事件日志的 `SessionPersistence` seam 都不是——它们分别在下列子页面中。
+其他一切都记录在各自的子系统页面上，而非本页。划线的规则是：*你编写、持有或接收的类型是核心；为它提供类型推导、渲染或持久化的机制是其他页面的细节*。因此 `ToolDefinition` 是核心，但为它提供类型推导的 `ValueSchemaSpec`/`ParameterSchemaSpec` 机制、为它提供渲染意图的 `ToolCallView`/`ToolResultView` 词汇，以及存储事件日志的 `SessionPersistence` seam 都不是——它们各有自己的页面（[目录](README.md)）。
 
-| 子页面 | 负责内容 |
-|---|---|
-| [llm-streaming.md](llm-streaming.md) | `StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
-| [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
-| [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
-| [typert.md](typert.md) | Remote 调用 descriptor、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
-| [goal.md](goal.md) | 持久 goal 标识、生命周期快照、激活、变更记录与 Round 归属 |
-| [commands.md](commands.md) | 人类命令 seam：定义、适配器发现、直接调用、结果与解析视图 |
-| [session.md](session.md) | 完整的 `SessionEventMap` 变体目录、`TurnTrigger`/`TurnEndReason`、`deriveMessages()`、执行封闭与独立事件 |
-| [persistence.md](persistence.md) | 持久性 seam：`SessionPersistence`、JSONL + SQLite 后端、`session/flush`、崩溃恢复、`SessionHeader` |
-| [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
-| [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
-| [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
-| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 |
-| [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
-| [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
-| [user-interaction.md](user-interaction.md) | UI 支持的人工问答 seam：`AskUserQuestionRequest`、answer/options 词汇、提供方 API、错误分类体系 |
-| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 契约 |
-| [bash.md](bash.md) | bash 执行器 seam：`BashExecRequest`/`Spec`、`BashRunResult`、后台 `BashProcess` 句柄 |
-| [subprocess.md](subprocess.md) | 子进程 seam：完全显式的 `SubprocessSpawnSpec`、基于偏移的输出读取器、不含分类的 `SubprocessOutcome`，以及受管 `DSH_*` 环境词汇 |
-| [pty.md](pty.md) | 持久化终端 ID、后端/会话契约、发送就绪状态、有界读取与 owner 可见快照 |
-| [sandbox.md](sandbox.md) | 每会话策略解析与进程约束 seam：文件效果模式、执行/提供方策略、`ConfinedArgv`、强制执行与故障关闭错误 |
-| [code-runtime.md](code-runtime.md) | 代码执行 seam：`CodeRunRequest`/`Result`、绑定命名空间、捕获日志、`CodeRunFailure` 分类体系 |
-| [filesystem.md](filesystem.md) | 文件系统 seam：`FsTarget`、读/写/编辑结果、观测到的文件状态、`FsErrorCode` |
-| [lsp.md](lsp.md) | LSP 导航 seam：`LspQueryRequest`/`Result`、`LspProvider`/`Service`、四种操作、`LspError` |
-| [skills.md](skills.md) | skill（技能）服务：发现优先级、`SkillSummary`/`SkillDefinition`、会话前缀目录、面向模型的 `skill` 加载 |
-| [compaction.md](compaction.md) | 压缩（compaction）seam：`compact/*` 会话事件、`CompactionResult`、`CompactService` 接口 |
-| [subagent.md](subagent.md) | subagent seam：命名提供方注册表、`SubagentStartRequest`/`Result`/`Run`、启动时与运行时能力拆分 |
-| [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
-| [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
-| [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
-| [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
-| [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
-| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
-| [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
-| [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
-| [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
-| [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
-| [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
-| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
-
-> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](#cordis-surface)。
 
 <a id="the-map--derived-union-pattern"></a>
 
@@ -329,15 +287,6 @@ interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
-  /**
-   * Whether the owning adapter knows this route only because configuration
-   * declared it — a gateway or self-hosted server it ships nothing about.
-   * Absent means the adapter draws no such distinction; false means it does
-   * and this route is one of its own. Only the adapter can answer: a stored
-   * profile is how a user-added route AND a corrected shipped one both look
-   * from outside.
-   */
-  declared?: boolean
 }
 ```
 
@@ -1007,7 +956,7 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 86694c3c23..7a33a31d0c 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: 6e4b9a9c50bc54a4752930ec14269d2c15233a76
-README.zh.md: d756cd9b7117d7ce9a2e79c6469d9fc188c9600b
+README.md: c28361f5e767f81fe8d1ca4757aece83dccfea5c
+README.zh.md: 3ad73bdea3b137f1c9139fdb1b52c49eb10b5500
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index 6e4b9a9c50..c28361f5e7 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -15,7 +15,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
-See the [subprocess data-structure catalog](../../../docs/subsystems/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
+See the [subprocess subsystem page](../../../docs/subsystems/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
 
 ## Model Experience
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index d756cd9b71..3ad73bdea3 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -15,7 +15,7 @@
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地的普通 spawn 与终端 spawn 都应用该定义；拥有自身 spawn 的 SDK 管理传输可直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
-参见[子进程数据结构目录](../../../docs/subsystems/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+参见[子进程子系统页面](../../../docs/subsystems/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 ## 模型体验
 
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index c2ca4136d3..750b1935de 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -269,14 +269,14 @@ describe('docsPages locale routes', () => {
     }
   })
 
-  it('projects translated core-data pages while retaining explicit English fallbacks', () => {
+  it('projects translated subsystem pages while retaining explicit English fallbacks', () => {
     const rootPages = docsPages.filter(page => (
       page.locale === 'root' && page.route.startsWith('reference/subsystems/')
     ))
     const translated = rootPages.filter(page => page.contentLocale === 'zh-CN')
     const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US')
 
-    expect(translated).toHaveLength(37)
+    expect(translated).toHaveLength(39)
     expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true)
     expect(fallbacks.map(page => page.source).sort()).toEqual([
       'docs/subsystems/commands.md',
diff --git a/website/docs.ts b/website/docs.ts
index 551224edaa..9a28aeea4d 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -257,52 +257,54 @@ const cordisPrimerReference = pairedPages([
   },
 ])
 
-const coreDataReference = pairedPages(([
-  ['core.md', '核心数据结构', 'Core data structures', 0],
-  ['scope.md', '作用域', 'Scopes', 1],
-  ['session.md', '会话', 'Sessions', 2],
-  ['session-query.md', '会话查询', 'Session query', 3],
-  ['session-reference.md', '会话引用', 'Session references', 4],
-  ['session-title.md', '会话标题', 'Session titles', 5],
-  ['settings.md', '用户设置', 'User settings', 6],
-  ['credentials.md', '用户凭据', 'User credentials', 7],
-  ['system-prompt.md', '系统提示词', 'System prompts', 8],
-  ['tools.md', '工具', 'Tools', 9],
-  ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming', 10],
-  ['token-meter.md', 'Token 计量', 'Token metering', 11],
-  ['bash.md', 'Bash 执行', 'Bash execution', 12],
-  ['subprocess.md', '子进程', 'Subprocesses', 13],
-  ['tasks.md', '后台任务', 'Background tasks', 14],
-  ['filesystem.md', '文件系统', 'Filesystem', 15],
-  ['lsp.md', 'LSP 导航', 'LSP navigation', 16],
-  ['code-runtime.md', '代码运行时', 'Code runtime', 17],
-  ['compaction.md', '上下文压缩', 'Compaction', 18],
-  ['subagent.md', '子代理', 'Subagents', 19],
-  ['workflow.md', '工作流', 'Workflows', 20],
-  ['skills.md', '技能', 'Skills', 21],
-  ['approval.md', '审批', 'Approvals', 22],
-  ['permission.md', '权限预设', 'Permission presets', 23],
-  ['plan.md', '计划模式', 'Plan mode', 24],
-  ['user-interaction.md', '用户交互', 'User interaction', 25],
-  ['sandbox.md', '沙箱', 'Sandboxing', 26],
-  ['web.md', 'Web 访问', 'Web access', 27],
-  ['spill.md', 'Spill 存储', 'Spill storage', 28],
-  ['persistence.md', '会话持久化', 'Session persistence', 29],
-  ['storage.md', '存储', 'Storage', 30],
-  ['workspace.md', '工作区', 'Workspaces', 31],
-  ['http-server.md', 'HTTP 服务器', 'HTTP server', 32],
-  ['client-modules.md', '客户端模块', 'Client modules', 33],
-  ['invariants.md', '运行时不变式', 'Runtime invariants', 35],
-  ['session-projection.md', '会话投影', 'Session projections', 36],
-  ['telemetry.md', '遥测', 'Telemetry', 37],
+const subsystemsReference = pairedPages(([
+  ['README.md', '子系统', 'Subsystems', 0],
+  ['core.md', '核心数据结构', 'Core data structures', 1],
+  ['scope.md', '作用域', 'Scopes', 2],
+  ['session.md', '会话', 'Sessions', 3],
+  ['session-query.md', '会话查询', 'Session query', 4],
+  ['session-reference.md', '会话引用', 'Session references', 5],
+  ['session-title.md', '会话标题', 'Session titles', 6],
+  ['settings.md', '用户设置', 'User settings', 7],
+  ['credentials.md', '用户凭据', 'User credentials', 8],
+  ['system-prompt.md', '系统提示词', 'System prompts', 9],
+  ['tools.md', '工具', 'Tools', 10],
+  ['llm-streaming.md', 'LLM 流式响应', 'LLM streaming', 11],
+  ['token-meter.md', 'Token 计量', 'Token metering', 12],
+  ['bash.md', 'Bash 执行', 'Bash execution', 13],
+  ['subprocess.md', '子进程', 'Subprocesses', 14],
+  ['tasks.md', '后台任务', 'Background tasks', 15],
+  ['filesystem.md', '文件系统', 'Filesystem', 16],
+  ['lsp.md', 'LSP 导航', 'LSP navigation', 17],
+  ['code-runtime.md', '代码运行时', 'Code runtime', 18],
+  ['compaction.md', '上下文压缩', 'Compaction', 19],
+  ['subagent.md', '子代理', 'Subagents', 20],
+  ['workflow.md', '工作流', 'Workflows', 21],
+  ['skills.md', '技能', 'Skills', 22],
+  ['approval.md', '审批', 'Approvals', 23],
+  ['permission.md', '权限预设', 'Permission presets', 24],
+  ['plan.md', '计划模式', 'Plan mode', 25],
+  ['user-interaction.md', '用户交互', 'User interaction', 26],
+  ['sandbox.md', '沙箱', 'Sandboxing', 27],
+  ['web.md', 'Web 访问', 'Web access', 28],
+  ['spill.md', 'Spill 存储', 'Spill storage', 29],
+  ['persistence.md', '会话持久化', 'Session persistence', 30],
+  ['storage.md', '存储', 'Storage', 31],
+  ['workspace.md', '工作区', 'Workspaces', 32],
+  ['http-server.md', 'HTTP 服务器', 'HTTP server', 33],
+  ['client-modules.md', '客户端模块', 'Client modules', 34],
+  ['tui.md', 'TUI 扩展', 'TUI extensions', 35],
+  ['invariants.md', '运行时不变式', 'Runtime invariants', 36],
+  ['session-projection.md', '会话投影', 'Session projections', 37],
+  ['telemetry.md', '遥测', 'Telemetry', 38],
 ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
   source: `docs/subsystems/${file}`,
-  route: `reference/subsystems/${file}`,
+  route: file === 'README.md' ? 'reference/subsystems/index.md' : `reference/subsystems/${file}`,
   label: { root: rootLabel, en: enLabel },
   sidebar: { root: 'zh-reference', en: 'en-reference' },
   section: { root: '子系统', en: 'Subsystems' },
   order,
-  ...(file === 'core.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
+  ...(file === 'README.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
 })))
 
 const reference = mirroredPages([
@@ -351,9 +353,9 @@ const reference = mirroredPages([
     order,
   })),
   ...([
-    ['goal.md', '目标', 'Goals', 13],
-    ['pty.md', 'PTY 会话', 'PTY sessions', 25],
-    ['commands.md', '命令', 'Human commands', 37],
+    ['goal.md', '目标', 'Goals', 14],
+    ['pty.md', 'PTY 会话', 'PTY sessions', 26],
+    ['commands.md', '命令', 'Human commands', 38],
   ] as const).map(([file, rootLabel, enLabel, order]): MirroredPage => ({
     source: `docs/subsystems/${file}`,
     route: `reference/subsystems/${file}`,
@@ -385,6 +387,6 @@ export const docsPages: DocsPage[] = [
   ...develop,
   ...cordisTutorial,
   ...cordisPrimerReference,
-  ...coreDataReference,
+  ...subsystemsReference,
   ...reference,
 ]

From aa0ca6c8367488c21cd0666e389ca7424be81653 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 05:54:15 +0800
Subject: [PATCH 419/516] docs: anchor each subsystem page to its package
 group; make group READMEs thin tables
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

core.md read as a type grab-bag: LLM wire vocabulary up front, the agent/loop story buried, and no correspondence to packages/core. It now opens on the packages/core control spine — the package-by-package loop map with a Page column into session/system-prompt/tools/scope — and keeps only what the spine group declares plus the repo-wide patterns: the Agent handle with its delivery/cancellation/interception contracts, the SessionEvent envelope, branded ids, the …Map pattern. The conversation vocabulary (Message/ContentBlock, the model request, adapters — 17 type-equiv blocks) moves to llm-streaming.md, which now declares packages/llm end-to-end; the duplicate ContentBlockMap paste near its seam section folds into the moved section, and the manifest, LINK_MAP, README table rows, website label (Core data structures → Core), and inbound anchors follow.

Every packages/<group>/README pair is now a thin front door in one shape: a why-first intro (bash's seam-pattern-first paragraph rewritten as 'shell execution for the agent'), the package table, and a closing pointer to the owning docs/subsystems page — the bash-style table stays the load-bearing middle. Load-bearing trailing paragraphs relocate rather than vanish: the fs no-timeout rationale becomes a filesystem.md section (both languages), session's four sectioned tables merge into one 12-row table, examples' legacy-bin H2 collapses to a pointer at jsonrpc-demo's README, and design rationale that already lives in an Agent Note or subsystem page is now linked instead of restated. All 40 pair records re-recorded.
---
 ...-14-provider-routed-llm-adapters.i18n.yaml |   4 +-
 ...2026-07-14-provider-routed-llm-adapters.md |   2 +-
 ...6-07-14-provider-routed-llm-adapters.zh.md |  26 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |   4 +-
 .../2026-07-16-persistent-pty-sessions.md     |   2 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  |   2 +-
 docs/subsystems/README.i18n.yaml              |   4 +-
 docs/subsystems/README.md                     |   4 +-
 docs/subsystems/README.zh.md                  |   4 +-
 docs/subsystems/compaction.i18n.yaml          |   4 +-
 docs/subsystems/compaction.md                 |   2 +-
 docs/subsystems/compaction.zh.md              |   2 +-
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       | 937 +++++++----------
 docs/subsystems/core.zh.md                    | 939 +++++++-----------
 docs/subsystems/filesystem.i18n.yaml          |   4 +-
 docs/subsystems/filesystem.md                 |   4 +
 docs/subsystems/filesystem.zh.md              |   4 +
 docs/subsystems/llm-streaming.i18n.yaml       |   4 +-
 docs/subsystems/llm-streaming.md              | 417 ++++++--
 docs/subsystems/llm-streaming.zh.md           | 427 ++++++--
 docs/subsystems/session-reference.i18n.yaml   |   4 +-
 docs/subsystems/session-reference.md          |   2 +-
 docs/subsystems/session-reference.zh.md       |   2 +-
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |   2 +-
 docs/subsystems/subagent.zh.md                |   2 +-
 docs/subsystems/token-meter.i18n.yaml         |   4 +-
 docs/subsystems/token-meter.md                |   2 +-
 docs/subsystems/token-meter.zh.md             |   2 +-
 docs/subsystems/tools.i18n.yaml               |   4 +-
 docs/subsystems/tools.md                      |   2 +-
 docs/subsystems/tools.zh.md                   |   2 +-
 packages/acp/README.i18n.yaml                 |   4 +-
 packages/acp/README.md                        |   4 +-
 packages/acp/README.zh.md                     |   4 +-
 packages/bash/README.i18n.yaml                |   4 +-
 packages/bash/README.md                       |   2 +
 packages/bash/README.zh.md                    |   2 +
 packages/boot/README.i18n.yaml                |   4 +-
 packages/boot/README.md                       |   4 +-
 packages/boot/README.zh.md                    |   4 +-
 packages/client/README.i18n.yaml              |   4 +-
 packages/client/README.md                     |   2 +
 packages/client/README.zh.md                  |   2 +
 packages/code-runtime/README.i18n.yaml        |   4 +-
 packages/code-runtime/README.md               |   2 +
 packages/code-runtime/README.zh.md            |   2 +
 packages/compact/README.i18n.yaml             |   4 +-
 packages/compact/README.md                    |   2 +
 packages/compact/README.zh.md                 |   2 +
 packages/context/README.i18n.yaml             |   4 +-
 packages/context/README.md                    |   2 +
 packages/context/README.zh.md                 |   2 +
 packages/core/README.i18n.yaml                |   4 +-
 packages/core/README.md                       |   2 +
 packages/core/README.zh.md                    |   2 +
 packages/credentials/README.i18n.yaml         |   4 +-
 packages/credentials/README.md                |   2 +
 packages/credentials/README.zh.md             |   2 +
 packages/fs/README.i18n.yaml                  |   4 +-
 packages/fs/README.md                         |   2 +
 packages/fs/README.zh.md                      |   2 +
 packages/goal/README.i18n.yaml                |   4 +-
 packages/goal/README.md                       |   4 +-
 packages/goal/README.zh.md                    |   4 +-
 packages/guard/README.i18n.yaml               |   4 +-
 packages/guard/README.md                      |   2 +
 packages/guard/README.zh.md                   |   2 +
 packages/host/README.i18n.yaml                |   4 +-
 packages/host/README.md                       |   2 +
 packages/host/README.zh.md                    |   2 +
 packages/interaction/README.i18n.yaml         |   4 +-
 packages/interaction/README.md                |   2 +
 packages/interaction/README.zh.md             |   2 +
 packages/llm/README.i18n.yaml                 |   4 +-
 packages/llm/README.md                        |   2 +
 packages/llm/README.zh.md                     |   2 +
 packages/lsp/README.i18n.yaml                 |   4 +-
 packages/lsp/README.md                        |   2 +
 packages/lsp/README.zh.md                     |   2 +
 packages/plan/README.i18n.yaml                |   4 +-
 packages/plan/README.md                       |   2 +
 packages/plan/README.zh.md                    |   2 +
 packages/pty/README.i18n.yaml                 |   4 +-
 packages/pty/README.md                        |   2 +
 packages/pty/README.zh.md                     |   2 +
 packages/sandbox/README.i18n.yaml             |   4 +-
 packages/sandbox/README.md                    |   2 +
 packages/sandbox/README.zh.md                 |   2 +
 packages/self-modification/README.i18n.yaml   |   2 +-
 packages/self-modification/README.zh.md       |   4 +-
 packages/session-query/README.i18n.yaml       |   4 +-
 packages/session-query/README.md              |   2 +
 packages/session-query/README.zh.md           |   2 +
 packages/session/README.i18n.yaml             |   4 +-
 packages/session/README.md                    |   2 +
 packages/session/README.zh.md                 |   2 +
 packages/settings/README.i18n.yaml            |   4 +-
 packages/settings/README.md                   |   2 +
 packages/settings/README.zh.md                |   2 +
 packages/skill/README.i18n.yaml               |   4 +-
 packages/skill/README.md                      |   2 +
 packages/skill/README.zh.md                   |   2 +
 packages/spill/README.i18n.yaml               |   4 +-
 packages/spill/README.md                      |   2 +
 packages/spill/README.zh.md                   |   2 +
 packages/storage/README.i18n.yaml             |   4 +-
 packages/storage/README.md                    |   2 +
 packages/storage/README.zh.md                 |   2 +
 packages/subagent/README.i18n.yaml            |   4 +-
 packages/subagent/README.md                   |   2 +
 packages/subagent/README.zh.md                |   2 +
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.md                 |   2 +
 packages/subprocess/README.zh.md              |   2 +
 packages/support/README.i18n.yaml             |   4 +-
 packages/support/README.md                    |   2 +
 packages/support/README.zh.md                 |   2 +
 packages/tasks/README.i18n.yaml               |   4 +-
 packages/tasks/README.md                      |   2 +
 packages/tasks/README.zh.md                   |   2 +
 packages/todo/README.i18n.yaml                |   4 +-
 packages/todo/README.md                       |   2 +
 packages/todo/README.zh.md                    |   2 +
 packages/web/README.i18n.yaml                 |   4 +-
 packages/web/README.md                        |   2 +
 packages/web/README.zh.md                     |   2 +
 packages/workflow/README.i18n.yaml            |   4 +-
 packages/workflow/README.md                   |   2 +
 packages/workflow/README.zh.md                |   2 +
 packages/workspace/README.i18n.yaml           |   4 +-
 packages/workspace/README.md                  |   2 +
 packages/workspace/README.zh.md               |   2 +
 scripts/gen-cordis-catalog.ts                 |  32 +-
 scripts/type-equiv.manifest.json              |  39 +-
 website/docs.ts                               |   2 +-
 137 files changed, 1680 insertions(+), 1507 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
index 465a658ca8..2d39db2332 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.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 .agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
-2026-07-14-provider-routed-llm-adapters.md: 27277280e423553f79d5a34f512b673413f495ff
-2026-07-14-provider-routed-llm-adapters.zh.md: aeb09a500d5750ef2793bc9a7fc09834055a56a4
+2026-07-14-provider-routed-llm-adapters.md: 9039334370ba5d71eb71879970c2e572a5b023df
+2026-07-14-provider-routed-llm-adapters.zh.md: eff33496e1a61472534009533270f8f943ccc1f8
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
index 27277280e4..9039334370 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
@@ -84,7 +84,7 @@ The on-disk session format remains the pre-release pinned version `0`, with no c
 
 - Unit coverage exercises registry conflicts, request reconstruction, session validation, profile resolution, single-attempt option forwarding, native API selection including OpenAI Responses, conversion, replay validation, error mapping, caller cancellation, idle-timeout transport termination, content rewrites, and same-instance versus different-instance replay dispatch.
 - Keyless loop/session tests and ACP snapshots exercise durable provider/model metadata, resume and fork propagation, workflow/subagent overrides, and unchanged user-visible transcripts; the key-gated DeepSeek e2e retains real provider streaming and tool follow-up coverage.
-- Public JSDoc, package READMEs, architecture and core-data-structure docs, generated catalogs, examples, session fixtures, and Python SDK pairs use provider/model targets consistently and are checked by the repository documentation and type-equivalence gates.
+- Public JSDoc, package READMEs, architecture and subsystem docs, generated catalogs, examples, session fixtures, and Python SDK pairs use provider/model targets consistently and are checked by the repository documentation and type-equivalence gates.
 
 ## Risks
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
index aeb09a500d..eff33496e1 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
@@ -8,9 +8,9 @@ Status: implemented
 
 `dsh-llm` 按精确模型名称注册适配器。插件在 Cordis 启动时提供模型列表，`LlmService` 为列表中的每个字符串保存一个适配器，`GenerateOptions.model` 同时选择适配器与提供方模型。两个正式适配器都只面向相同的两个 DeepSeek 模型时，这种方式可以工作，但它混淆了两个独立决策：由哪个上游提供方承接请求，以及该提供方应运行哪个模型。
 
-这种混淆使提供方网关无法提供开放的模型目录。例如，OpenRouter 是一个包含大量模型 ID 的提供方，私有 OpenAI 兼容端点也可能在不修改 harness 插件树的情况下增加模型。目前，每个新选择的模型都必须在插件启动期间完成注册。同一个模型 ID 还可能存在于多个提供方中，因此仅按模型注册无法表达调用方预期使用的提供方。
+这种混淆使提供方网关无法提供开放的模型目录。例如，OpenRouter 是一个包含大量模型 ID 的提供方，私有 OpenAI 兼容端点也可能在不修改 Harness 插件树的情况下增加模型。目前，每个新选择的模型都必须在插件启动期间完成注册。同一个模型 ID 还可能存在于多个提供方中，因此仅按模型注册无法表达调用方预期使用的提供方。
 
-`dsh-llm-pi-ai` 没有暴露 pi-ai 的提供方抽象。它以内联方式构造 DeepSeek `openai-completions` 模型，应用 DeepSeek 专用载荷补丁，并将每条回放的助手消息标记为 DeepSeek。pi-ai 自身提供提供方/模型目录，能够选择 `openai-responses`、`anthropic-messages`、`google-generative-ai` 等 API，并保留提供方专用的响应 ID，以及后续轮次所需的推理（reasoning）和工具签名。harness 转换丢弃了这些来源信息，因此仅将内联模型替换为目录查询，会导致同模型回放与跨提供方移交不完整。
+`dsh-llm-pi-ai` 没有暴露 pi-ai 的提供方抽象。它以内联方式构造 DeepSeek `openai-completions` 模型，应用 DeepSeek 专用的 payload 补丁，并将每条回放的助手消息标记为 DeepSeek。pi-ai 自身提供提供方/模型目录，能够选择 `openai-responses`、`anthropic-messages`、`google-generative-ai` 等 API，并保留提供方专用的响应 ID，以及后续轮次所需的推理和工具签名。Harness 转换丢弃了这些来源信息，因此仅将内联模型替换为目录查询，会导致同模型回放与跨提供方移交不完整。
 
 适配器配置同样假定只存在一个 DeepSeek API 密钥和端点。通用后端需要为各提供方分别配置凭据和端点覆盖，同时继续由 pi-ai 处理 AWS、Google ADC、OAuth 等环境认证机制。
 
@@ -18,9 +18,9 @@ Status: implemented
 
 ### 提供方作为适配器注册键
 
-`GenerateOptions` 与 `LlmCallConfig` 在 `model: string` 之外携带 `provider: string`，`AgentOptions` 则携带对应的可选创建字段。只有两个值都非空时，agent loop（智能体循环）请求才有效；两个值也都是已记录请求头的一部分。`agent/request` 可以在任意步骤返回替换后的字段组合，因此会话可以切换提供方与模型，无需改变 Cordis 插件生命周期。
+`GenerateOptions` 与 `LlmCallConfig` 在 `model: string` 之外携带 `provider: string`，`AgentOptions` 则携带对应的可选创建字段。只有两个值都非空时，agent loop（智能体循环）请求才有效；两个值也都会写入请求头日志。`agent/request` 可以在任意步骤返回替换后的字段组合，因此会话可以切换提供方与模型，无需改变 Cordis 插件生命周期。
 
-`LlmService` 按提供方注册和解析适配器。`registerAdapter(providers, adapter)` 在修改注册表前检查整个提供方列表，遇到重复项时以 `DUPLICATE_ADAPTER` 拒绝注册，并将整组注册作为一个 effect 统一 dispose（资源释放）。模型 ID 不作为注册键；仍由选中的适配器负责验证或转发。后续的 [LLM 目录与 ACP（Agent Client Protocol）模型选择 Agent Note](2026-07-15-llm-model-catalog-and-acp-selection.md) 增加了建议性的 `listProviders()` / `listModels()` 发现接口，但不会把目录成员关系变成请求校验规则。
+`LlmService` 按提供方注册和解析适配器。`registerAdapter(providers, adapter)` 在修改注册表前检查整个提供方列表，遇到重复项时返回 `DUPLICATE_ADAPTER`，并将整组注册作为一个 effect 释放。模型 ID 不作为注册键；仍由选中的适配器负责验证或转发。后续的 [LLM 目录与 ACP 模型选择 Agent Note](2026-07-15-llm-model-catalog-and-acp-selection.md) 增加了建议性的 `listProviders()` / `listModels()` 发现接口，但不会把目录成员关系变成请求校验规则。
 
 在一个 Cordis 上下文中，一个提供方只能有一个适配器所有者。`dsh-llm-deepseek` 注册 `deepseek`；`dsh-llm-pi-ai` 也可以注册 `deepseek`，但同时加载两个所有者属于配置错误，不采用顺序规则或回退行为。若部署选择手写的 DeepSeek 实现，需从 pi-ai 配置中排除 `deepseek`；若部署选择 pi-ai 的 DeepSeek 实现，则不挂载 `dsh-llm-deepseek`。
 
@@ -28,29 +28,29 @@ Status: implemented
 
 ### 显式 pi-ai 提供方配置
 
-`dsh-llm-pi-ai` 接受一个非空的提供方配置列表。列表内的提供方名称必须唯一，并且存在于 pi-ai 的 `getProviders()` 结果中。每项配置包含提供方名称，以及可选的 `apiKey`、`baseURL`、headers、推理级别和预算、缓存保留设置、传输方式、SDK 超时、harness 流空闲超时，以及由提供方拥有的 `retryPolicy`。适配器强制将 pi-ai 的 `maxRetries` 设为零，使一次 `stream()` 调用只发起一次可见的提供方请求；`dsh-llm-retry` 则在 agent 失败步骤 seam 上执行解析后的策略。凭据不设全局值：显式密钥仅对所属配置生效；未提供密钥时，pi-ai 使用标准环境变量、OAuth token、AWS 凭据链、Google ADC 或其他提供方原生环境认证。显式空密钥属于无效配置，不会回退到环境认证。
+`dsh-llm-pi-ai` 接受一个非空的提供方配置列表。列表内的提供方名称必须唯一，并且存在于 pi-ai 的 `getProviders()` 结果中。每项配置包含提供方名称，以及可选的 `apiKey`、`baseURL`、headers、推理级别和预算、缓存保留设置、传输方式、SDK 超时、Harness 流空闲超时，以及由提供方拥有的 `retryPolicy`。适配器强制将 pi-ai 的 `maxRetries` 设为零，使一次 `stream()` 调用只发起一次可见的提供方请求；`dsh-llm-retry` 则在 agent 失败步骤 seam 上执行解析后的策略。凭据不设全局值：显式密钥仅对所属配置生效；未提供密钥时，pi-ai 使用标准环境变量、OAuth token、AWS 凭据链、Google ADC 或其他提供方原生环境认证。显式空密钥属于无效配置，不会回退到环境认证。
 
 插件通过一次全有或全无调用，将所有已配置的提供方名称注册到同一个 `PiAiAdapter`。请求按 provider 选择对应配置，并在 `getModels(provider)` 中查找模型以取得目录描述符。未知提供方会在插件加载时失败；未知模型会在网络 I/O 前以 `UNKNOWN_MODEL` 失败。适配器不会修改目录对象。当配置提供 `baseURL` 时，适配器复制选中的描述符，仅覆盖 `baseUrl`，使私有端点保留 pi-ai 的 API、能力、兼容标志、上下文限制与推理映射。私有端点必须实现所选提供方的协议，模型 ID 也仍须存在于已安装的 pi-ai 目录中。
 
-适配器调用 pi-ai 的 `streamSimple()`，因此每个目录模型会选择其注册的 API 实现；描述符为 `openai-responses` 时使用 OpenAI Responses，而非 Chat Completions。harness 的 temperature、最大 token 数、signal、session ID，以及提供方配置中的通用流选项均直接传递。配置 headers 与 harness 强制归因 headers 合并；发生保留名称冲突时，以 harness 归因为准。适配器不再维护 DeepSeek 专用载荷重写或提供方协议矩阵。
+适配器调用 pi-ai 的 `streamSimple()`，因此每个目录模型会选择其注册的 API 实现；描述符为 `openai-responses` 时使用 OpenAI Responses，而非 Chat Completions。Harness 的 temperature、最大 token 数、signal、session ID，以及提供方配置中的通用流选项均直接传递。配置 headers 与 Harness 强制归因 headers 合并；发生保留名称冲突时，以 Harness 归因为准。适配器不再维护 DeepSeek 专用 payload 重写或提供方协议矩阵。
 
-pi-ai 的通用流选项不支持停止序列。若 harness `stop` 选项已定义，`dsh-llm-pi-ai` 会以 `UNSUPPORTED_OPTION` 拒绝请求，不会静默忽略，也不会增加第二套提供方专用 payload 实现。`dsh-llm-deepseek` 继续通过原生请求序列化器支持 `stop`。
+pi-ai 的通用流选项不支持停止序列。若 Harness `stop` 选项已定义，`dsh-llm-pi-ai` 会以 `UNSUPPORTED_OPTION` 拒绝请求，不会静默忽略，也不会增加第二套提供方专用 payload 实现。`dsh-llm-deepseek` 继续通过原生请求序列化器支持 `stop`。
 
 ### 持久化助手来源信息与回放状态
 
 助手消息携带提供方无关的来源信息，其中包含请求的 `provider` 和 `model`，以及可选的 JSON 可序列化适配器回放状态。成功的 `assistant/message` 会话事件记录这些来源信息，`deriveMessages()` 返回助手消息时也会包含这些信息。用户、system、context 与工具结果消息不携带助手来源信息。provider/model 字段是 agent loop 的权威数据；适配器仅拥有其不透明回放状态 payload。
 
-成功的终止 `finish` 分片可以携带回放状态，`BlockAssembler` 会将其与 token 用量和结束原因一起保留。agent loop 会把该状态附加到组装后的助手来源信息，不再暴露响应改写 hook。错误或中止响应不会生成正常助手消息，因此不会进入后续模型历史。
+成功的终止 `finish` 分片可以携带回放状态，`BlockAssembler` 会将其与 token 用量和结束原因一起保留。只有当 `agent/step-result` 处理后的内容与提供方组装输出在结构上相等时，agent loop 才会把回放状态附加到助手来源信息。监听器重写内容后，provider/model 来源信息仍会保留，但已经陈旧的回放状态会被移除。错误或中止响应不会生成正常助手消息，因此不会进入后续模型历史。
 
-pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包含源 API/provider/model、响应 ID/model、停止原因，以及按索引对齐的文本、thinking 和工具调用签名。它不会重复 harness 内容块中已有的文本或工具参数，也不包含诊断信息、时间戳、用量或错误。后续请求中，只有历史提供方和目标提供方当前归同一个适配器实例所有时，`LlmService` 才会把回放状态交给目标适配器。适配器在能够恢复历史响应时，将 harness 记录的内容与回放状态组合，并负责所需的跨模型或跨提供方转换。适配器收到未知版本或块形状不匹配的回放状态时会显式失败；其他适配器只能收到提供方无关的内容与来源信息。
+pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包含源 API/provider/model、响应 ID/model、停止原因，以及按索引对齐的文本、thinking 和工具调用签名。它不会重复 Harness 内容块中已有的文本或工具参数，也不包含诊断信息、时间戳、用量或错误。后续请求中，只有历史提供方和目标提供方当前归同一个适配器实例所有时，`LlmService` 才会把回放状态交给目标适配器。适配器在能够恢复历史响应时，将 Harness 记录的内容与回放状态组合，并负责所需的跨模型或跨提供方转换。适配器收到未知版本或块形状不匹配的回放状态时会显式失败；其他适配器只能收到提供方无关的内容与来源信息。
 
 该状态属于模型可见的回放输入，因此遵循现有的[请求可重建规则](2026-07-05-reconstructable-requests.md)：它同时存在于终止 `finish` 分片和驱动派生的已组装 `assistant/message` 来源信息中。恢复和 fork 会原样保留该状态。压缩（compaction）遮蔽助手消息时，也会从活动 surface 中移除其回放状态；摘要属于普通的提供方无关内容。
 
 ### 在所有请求生产方中传播目标
 
-每个模型选择接口都同时携带 provider 与 model：声明式 agent、ACP 和 stdio 应用配置、JSON-RPC initialize 请求、subagent 覆盖与继承、工作流子 agent 覆盖，以及直接压缩摘要。subagent 先从父 agent 继承两个字段，再应用请求覆盖。系统提示词变量集合在 `model` 之外增加 `provider`。
+每个模型选择接口都同时携带 provider 与 model：声明式 agent、ACP（Agent Client Protocol）和 stdio 应用配置、JSON-RPC initialize 请求、subagent 覆盖与继承、工作流子 agent 覆盖，以及直接压缩摘要。subagent 先从父 agent 继承两个字段，再应用请求覆盖。系统提示词变量集合在 `model` 之外增加 `provider`。
 
-压缩配置在 `summarizationModel` 之外增加 `summarizationProvider`。两个值均为空时继承，均非空时选择显式目标；只配置其中一个会导致加载失败。继承优先使用最近一次记录的请求目标，没有时回退到 agent 创建选项。`compact/summary` 使用现有模型调用封装记录两个字段。
+压缩配置在 `summarizationModel` 之外增加 `summarizationProvider`。两个值均为空时继承，均非空时选择显式目标；只配置其中一个会导致加载失败。继承优先使用最近一次记录的请求目标，没有时回退到 agent 创建选项。`compact/summary` 使用现有模型调用 envelope 记录两个字段。
 
 JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方没有注册所有者时，其便利回退才会挂载 `dsh-llm-deepseek`；其他缺失的提供方会直接失败，不会猜测适配器。
 
@@ -68,7 +68,7 @@ JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方
 
 **每个提供方挂载一个 pi-ai 插件实例。** 独立实例可以隔离配置，但会重复插件声明，也无法实现配置注册的原子性。每个请求本就向同一个适配器提供 provider，因此经过验证的配置映射具有更小的生命周期接口。
 
-**接受任意内联 pi-ai 模型描述符。** 这种方式可支持目录外的私有模型 ID，但会将 pi-ai 的模型与兼容性 schema 暴露为 harness 配置，并要求适配器验证协议专用组合。当前版本通过覆盖目录模型的 `baseURL` 支持自定义端点；只有实际出现目录外部署需求后，才会另行决策是否支持自定义描述符。
+**接受任意内联 pi-ai 模型描述符。** 这种方式可支持目录外的私有模型 ID，但会将 pi-ai 的模型与兼容性 schema 暴露为 Harness 配置，并要求适配器验证协议专用组合。当前版本通过覆盖目录模型的 `baseURL` 支持自定义端点；只有实际出现目录外部署需求后，才会另行决策是否支持自定义描述符。
 
 ## 影响
 
@@ -84,7 +84,7 @@ JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方
 
 - 单元测试覆盖注册表冲突、请求重建、会话验证、配置解析、单次请求的选项转发、包括 OpenAI Responses 在内的原生 API 选择、转换、回放验证、错误映射、调用方取消、空闲超时导致的传输终止、内容重写，以及同一实例与不同实例间的回放分发。
 - 无密钥的 agent loop/会话测试和 ACP 快照覆盖持久化 provider/model 元数据、恢复与 fork 传播、工作流/subagent 覆盖，以及不变的用户可见 transcript（文本记录）；密钥门控的 DeepSeek e2e 测试保留真实提供方的流式输出与工具后续调用覆盖率。
-- 公共 JSDoc、包的 README、架构与核心数据结构文档、生成目录、示例、会话 fixture（测试前置数据）和 Python SDK 配对文档统一使用 provider/model 目标，并由仓库文档与类型等价门禁校验。
+- 公共 JSDoc、package README、架构与子系统文档、生成目录、示例、会话 fixture（测试前置数据）和 Python SDK 配对文档统一使用 provider/model 目标，并由仓库文档与类型等价门禁校验。
 
 ## 风险
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 72944d7433..7756f7803c 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: 88296a9318b2c398fead382153bd2c652dbd9e68
-2026-07-16-persistent-pty-sessions.zh.md: 40f26c67fe046ad292f05919501600bd2e146c62
+2026-07-16-persistent-pty-sessions.md: 219f48235d527cffbf66020ceb22e80ca473093d
+2026-07-16-persistent-pty-sessions.zh.md: 18b81cd6a8d3f9cdbaa8566e1b166c3877ae8742
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index 88296a9318..219f48235d 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -160,7 +160,7 @@ The package ships concise tool guidance explaining persistent state, owner isola
 - Subprocess process fixtures cover non-leader and non-main-thread stdin waits, zombie quiescence, unreadable process state, supported syscall tables, unsupported architectures, and false-positive rejection; macOS inspector logic is injected into the same unit suite.
 - Real `node-pty` and PTY-consumer tests jointly exercise shell state, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
 - A Loader-driven `cordis.yml` test mounts the real three-package composition. ACP and headless snapshots pin the six schemas, bounded results, and errors through opt-in overlays; TUI snapshots pin terminal and generic card presentation.
-- Package contracts, the architecture map, core data structures, generated catalogs, and the website API describe the same shipped surface.
+- Package contracts, the architecture map, subsystem pages, generated catalogs, and the website API describe the same shipped surface.
 - The repository CI-equivalent sequence owns type, lint, coverage, snapshot, documentation, build, hygiene, demo, and built-entry verification.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 40f26c67fe..18b81cd6a8 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -160,7 +160,7 @@ plugins:
 - 子进程 fixture 覆盖非 leader 与非主线程的 stdin 等待、僵尸进程完全停稳、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
 - 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合。ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。
-- 包契约、架构图、核心数据结构、生成目录和 website API 描述同一个已发布接口。
+- 包契约、架构图、子系统页面、生成目录和 website API 描述同一个已发布接口。
 - 仓库 CI 等价序列负责类型、lint、覆盖率、快照、文档、构建、hygiene、demo 和 built-entry 验证。
 
 ## 后果
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index ec72119627..3303bcb935 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/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 docs/subsystems/README.md
-README.md: 59e5a4db09d114e96c19dc0fe29a5ebe8d8c8d32
-README.zh.md: 6b5fa58bf45654708b08d780aa0e17a8d90b7e17
+README.md: d225e5f4eeb31d1e6c71cbd8311e28bae1e8b3a5
+README.zh.md: 9f78ac3e1c79440b053ee4e344dbdba2c11b3dfc
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
index 59e5a4db09..d225e5f4ee 100644
--- a/docs/subsystems/README.md
+++ b/docs/subsystems/README.md
@@ -6,8 +6,8 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 
 | Page | Owns |
 |---|---|
-| [core.md](core.md) | the spine vocabulary every turn traffics in — `Message`/`ContentBlock`, `StreamChunk`, `SessionEvent`, the `Agent` handle, `ToolDefinition`, branded ids, the `…Map → derived-union` pattern |
-| [llm-streaming.md](llm-streaming.md) | the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
+| [core.md](core.md) | the `packages/core` control spine: the package-by-package loop map, the `Agent` handle with its delivery/cancellation/interception contracts, the `SessionEvent` envelope, branded ids, the `…Map → derived-union` pattern |
+| [llm-streaming.md](llm-streaming.md) | the `packages/llm` conversation vocabulary — `Message`/`ContentBlock`, the assembled model request, the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
 | [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
 | [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API seams |
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index 6b5fa58bf4..9f78ac3e1c 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -6,8 +6,8 @@
 
 | 页面 | 负责内容 |
 |---|---|
-| [core.md](core.md) | 每个轮次都在使用的主干词汇——`Message`/`ContentBlock`、`StreamChunk`、`SessionEvent`、`Agent` 句柄、`ToolDefinition`、品牌化 id，以及 `…Map → 派生联合` 模式 |
-| [llm-streaming.md](llm-streaming.md) | `StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
+| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、`Agent` 句柄及其投递/取消/拦截契约、`SessionEvent` 信封、品牌化 id，以及 `…Map → 派生联合` 模式 |
+| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
 | [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index eb2332a715..86348bad3a 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: eeea249fa7a9f95e607edb10e6a8c93a24162b64
-compaction.zh.md: 24c55f062404ff827292f324392347ad59bb7846
+compaction.md: 5aef839192ea6f67bb409622187fe65fed795e73
+compaction.zh.md: 63b28518e68f71cc648d2f4e78a82bc5beafb621
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index eeea249fa7..5aef839192 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -224,7 +224,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 pruneSession(session: Session): PruneResult
 ```
 
-Types: [ContentBlock](core.md) · [Session](session.md)
+Types: [ContentBlock](llm-streaming.md) · [Session](session.md)
 
 Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 24c55f0624..63b28518e6 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -224,7 +224,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 pruneSession(session: Session): PruneResult
 ```
 
-Types: [ContentBlock](core.md) · [Session](session.md)
+Types: [ContentBlock](llm-streaming.md) · [Session](session.md)
 
 Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 0994de32ec..16c8e29cf2 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: 8f27727d63e598fbf31b09a87ab53ad686155b4f
-core.zh.md: fff5bd502cbed6f2167eb23731fb5c3825efb7af
+core.md: ba9319d377cf250148a145ba3f1fa1baa967c858
+core.zh.md: 276dc4f99f1f802e66aca050b2fbcdc178931611
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index 8f27727d63..ba9319d377 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -1,20 +1,29 @@
-# Core Data Structures
+# Core
 
 English | [中文](core.zh.md)
 
-This page catalogs the **core** data structures of the DeepSeek Harness — what each spine type represents, its literal shape, and where the full detail lives. It complements [architecture.md](../architecture.md), which describes *behavior* (the service map, the session/turn/step lifecycle, the event taxonomy); this page describes the *vocabulary* that behavior moves around. The sibling subsystem pages are indexed in the [folder README](README.md).
+The **core** subsystem is [`packages/core`](../../packages/core/README.md) — the control spine every composition boots: the event-sourced session log, system-prompt assembly, the tool registry, the agent vocabulary, and the concrete loop that drives them. This page owns the spine's shared vocabulary — the `Agent` handle, its delivery and interception contracts, and the repo-wide type patterns — and orients to the group's dedicated pages; the folder is indexed in the [subsystems README](README.md).
 
-## What counts as "core"
+## The spine, package by package
 
-The harness is a microkernel: a tiny core plus many plugins. Most types belong to one plugin or one capability. A handful, though, are the **spine** — the language the agent loop and its events traffic in on *every* turn, no matter which optional plugins are loaded. Those are "core".
+A turn flows through the six packages in one loop: the driver in [`agent-loop`](../../packages/core/agent-loop) claims a queued prompt, opens a turn on the [session log](session.md) (`ctx.sessions`), assembles the request prefix through [system-prompt](system-prompt.md) (`ctx.systemPrompt`) and derives history from the log, streams the model response through the [LLM seam](llm-streaming.md), dispatches tool calls through the [tool registry](tools.md) (`ctx.tools`), and appends every model-visible fact back onto the log before the next step derives from it.
 
-Precisely, a data structure is **core** if either:
+| Package | Owns | Page |
+|---|---|---|
+| `session/` | The append-only `SessionEvent` log and in-memory store — the single source of truth (`ctx.sessions`) | [session.md](session.md) |
+| `system-prompt/` | Prompt-section and tool-schema assembly (`ctx.systemPrompt`) | [system-prompt.md](system-prompt.md) |
+| `tools/` | The scoped tool registry and guarded execution pipeline (`ctx.tools`) | [tools.md](tools.md) |
+| `agent/` | The `Agent` interface, live registry, initiator scope, and `agent/*` event vocabulary (`ctx.agents`) | this page |
+| `agent-loop/` | The concrete driver implementing the public `Agent` contract (`ctx.agentLoop`) | this page |
+| `scope/` | The scoped-registration primitive the registries and loop build per-agent scoping on | [scope.md](scope.md) |
 
-1. it flows through the agent-loop spine — the loop holds it, derives it, streams it, or logs it on every turn (a `Message`, a `StreamChunk`, a `SessionEvent`, the `Agent` handle itself), independent of which plugins are present; **or**
-2. it is the single headline type a plugin author writes against a pipeline — `ToolDefinition` (what every tool *is*).
+`scope/` is the one non-service package: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) that sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle. `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; it runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent` — including when they need the initiating Agent — and never on `agent-loop` directly, so the loop stays swappable. The default composition that wires this spine into a runnable agent is [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md).
 
-Everything else is documented on its own subsystem page, not here. The rule that draws the line: *the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is another page’s detail.* So `ToolDefinition` is core, but the `ValueSchemaSpec`/`ParameterSchemaSpec` inference machinery that types it, the `ToolCallView`/`ToolResultView` render-intent vocabulary that renders it, and the `SessionPersistence` seam that stores the event log are not — they live on their own pages ([index](README.md)).
+<a id="what-counts-as-core"></a>
 
+## What this page owns
+
+The conversation vocabulary the loop moves — `Message`, `ContentBlock`, `StreamChunk`, the model request — is declared by [`packages/llm`](../../packages/llm/README.md) and documented on [llm-streaming.md](llm-streaming.md); the session-event, prompt-assembly, and tool vocabularies live on this group's dedicated pages above. What remains here is the vocabulary shared by everything: the `Agent` handle and its delivery, cancellation, and interception contracts (declared by `packages/core/agent`), the `SessionEvent` envelope, and the two type patterns every subsystem follows. The scoping rule is recorded in the [subsystems-catalog Agent Note](../../.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md): the type you write, hold, or receive is documented where its declaring subsystem is; the machinery that types, renders, or persists it stays on that machinery's page.
 
 ## The `…Map → derived-union` pattern
 
@@ -37,13 +46,14 @@ declare module '@deepseek-ai/dsh-llm' {
 }
 ```
 
-Five canonical maps use this pattern; a plugin author extends these:
+Six canonical maps use this pattern; a plugin author extends these:
 
 | Map | Package | Derives | Catalog |
 |---|---|---|---|
-| `ContentBlockMap` | dsh-llm | `ContentBlock` | [below](#content-blocks-and-messages) |
-| `MessageSourceMap` | dsh-llm | `MessageSource` | [below](#content-blocks-and-messages) |
-| `FinishReasonMap` | dsh-llm | `FinishReason` | [below](#the-model-request-and-result) |
+| `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
+| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
 | `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
 | `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
 
@@ -64,458 +74,6 @@ type Branded<B extends string> = string & { readonly [BRAND]: B }
 
 The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm) and `SessionId` (the shared live agent and durable session identity; dsh-session). Capability packages brand their own ids too, such as `TaskId` in [tasks.md](tasks.md).
 
-## Content blocks and messages
-
-A conversation is `Message`s; a message is an array of typed **content blocks**. The block union derives from `ContentBlockMap`.
-
-Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
-
-```ts type-equiv
-/**
- * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support.
- */
-interface ContentBlockMap {
-  'text': TextBlock
-  'reasoning': ReasoningBlock
-  'tool-call': ToolCallBlock
-  'tool-result': ToolResultBlock
-}
-```
-
-The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBlock` (thinking, distinct from visible text), `ToolCallBlock` (`id: CallId`, `name`, raw-JSON `arguments`), `ToolResultBlock` (`toolCallId`, nested `content: ContentBlock[]`, `isError?`). `ContentBlock = ContentBlockMap[ContentBlockType]`. The core set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the merge-extensible map together with the adapter/UI/compaction support that honors it.
-
-Source: [`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
-
-A `Message` is one identified, immutable role/source/content value. Model-produced assistant messages carry provider/model ownership and optional adapter-private replay metadata in their source:
-
-```ts type-equiv
-/** Provider ownership and adapter-private replay data for an assistant message. */
-interface AssistantProvenance {
-  /** Provider route that produced the message. */
-  provider: string
-  /** Provider model id that produced the message. */
-  model: string
-  /**
-   * Lossless-JSON adapter state needed to replay the provider response.
-   * `LlmService` exposes it to a target adapter only when that adapter instance
-   * currently owns both this historical provider and the target provider.
-   */
-  replayState?: unknown
-}
-```
-
-```ts type-equiv
-/** One immutable message representation shared by delivery, durable history, and model requests. */
-interface Message {
-  /** Stable identity preserved across every representation boundary. */
-  readonly id: MessageId
-  /** Provider-neutral conversation role. */
-  readonly role: 'system' | 'user' | 'assistant'
-  /** Exact model-facing blocks. */
-  readonly content: ContentBlock[]
-  /** Required producer provenance. */
-  readonly source: MessageSource
-}
-```
-
-Where a message came from is itself a merge-extensible sum type:
-
-```ts type-equiv
-/**
- * Where a message (or injected content) came from.
- * Merge-extensible sum type — plugins add their own `kind`s.
- */
-interface MessageSourceMap {
-  user: { kind: 'user' }
-  plugin: { kind: 'plugin'; plugin: string } & ContextFormed
-  model: ModelMessageSource
-  tool: ToolMessageSource
-}
-```
-
-Provenance and shape are two independent axes. `kind` answers *who produced this*; the optional `form` a producer mixes in answers *what shape of information it is*, so several producers may share one presentation and one producer may emit more than one shape over a session. The vocabulary is semantic and grows one value at a time; an absent or unrecognized value is the documented default, presented as opaque content:
-
-```ts type-equiv
-/**
- * What SHAPE of information a producer-supplied context carries, declared by
- * the producer beside its provenance.
- *
- * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
- * of thing it is*, and the two axes are deliberately independent — several
- * producers share one form (three snapshot producers today), and one producer
- * may emit more than one form over a session.
- *
- * The vocabulary is SEMANTIC, never visual: a value states that the content is
- * a file's instructions or a catalog of available items, and a consumer decides
- * what that looks like. Colors, icons, ordering, and collapse defaults are the
- * consumer's business and must not enter this union. It grows one value at a
- * time as producers gain the structured fields their form needs; an absent or
- * unknown value is the documented default, presented as opaque content.
- */
-type ContextForm =
-  /** Instructions read out of workspace files the model is expected to follow. */
-  | 'instructions'
-  /** A catalog of items available in this session, republished as it changes. */
-  | 'catalog'
-  /** Current state, where a later snapshot from the same producer supersedes an earlier one. */
-  | 'snapshot'
-  /** A one-off account of something that just happened; it supersedes nothing. */
-  | 'notice'
-  /** A message another agent addressed to this one. */
-  | 'relay'
-  /** Material lifted out of another session's log, possibly reduced on the way in. */
-  | 'recall'
-```
-
-```ts type-equiv
-/** One named contribution to a `snapshot`-form context, in assembly order. */
-interface ContextSnapshotSection {
-  /** The contributing subsystem's name. */
-  readonly name: string
-  /** That contribution's model-facing text, exactly as assembled. */
-  readonly text: string
-}
-```
-
-```ts type-equiv
-/**
- * Producer-declared {@link ContextForm} and the fields that form requires,
- * mixed into the source shapes that carry one.
- *
- * Discriminated by `form` so a producer cannot declare a shape without the
- * facts that shape is presented from: a `notice` must record its one-line
- * account, a `snapshot` its sections. Omitting `form` stays valid — an
- * undeclared context is the documented default.
- */
-type ContextFormed =
-  | { readonly form?: never }
-  | { readonly form: 'instructions' }
-  | { readonly form: 'catalog' }
-  | {
-    readonly form: 'snapshot'
-    /** The named contributions this snapshot assembled, in order. */
-    readonly sections: readonly ContextSnapshotSection[]
-  }
-  | {
-    readonly form: 'notice'
-    /** One-line account of what happened, shown without expanding the row. */
-    readonly summary: string
-  }
-  | { readonly form: 'relay' }
-  | { readonly form: 'recall' }
-```
-
-## Streaming
-
-Adapters emit a raw **chunk** protocol; the loop logs the chunks (replay fidelity) while feeding the same chunks through a `BlockAssembler` to rebuild blocks and messages. `StreamChunk` is a closed discriminated union over `type` — `block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`.
-
-The full union, the adapter contract (usage-before-finish, raw-JSON tool arguments, the two sanctioned error paths), and `BlockAssembler` live on **[llm-streaming.md](llm-streaming.md)**.
-
-<a id="the-model-request-and-result"></a>
-
-## The model request
-
-One model call is a fully-assembled `GenerateOptions`. The adapter answers with a raw `StreamChunk` stream; the consumer assembles it with `BlockAssembler` (see [llm-streaming.md](llm-streaming.md)).
-
-Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
-
-Provider and model discovery uses small provider-neutral descriptors. A model catalog is advisory: routing still keys on a registered provider, and an adapter may accept unlisted model ids.
-
-Registering an adapter returns a handle: the disposer, plus the atomic route replacement a plugin whose route set is user-configurable needs.
-
-```ts type-equiv
-/**
- * What {@link LlmService.registerAdapter} returns: the disposer, plus an
- * atomic route replacement for the same adapter instance.
- */
-interface AdapterRegistrationHandle {
-  /** Release every route this registration currently holds. */
-  (): void
-  /**
-   * Replace this registration's routes with `providers`, keeping the same
-   * adapter instance. The candidate set is validated in full first — a
-   * conflict with another adapter, an invalid name, or bad provider metadata
-   * throws and leaves the current routes untouched — and the swap itself is
-   * one synchronous section, so no request can observe a gap. An empty array
-   * is legal here (a settings section that emptied holds zero routes while
-   * staying registered), unlike an empty initial registration.
-   *
-   * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
-   * has been released: its routes are gone and its disposer has already run,
-   * so anything registered afterwards would have no owner left to release it.
-   * @param providers - the complete next route set for this registration.
-   */
-  replace(providers: string[]): void
-}
-```
-
-```ts type-equiv
-/** Display metadata for one registered provider route. */
-interface LlmProviderInfo {
-  /** Provider route key used by {@link GenerateOptions.provider}. */
-  id: string
-  /** Human-readable provider name for selectors and diagnostics. */
-  name: string
-}
-```
-
-Adapter plugins additionally declare which routes *could* run through `registerConfigurableProviders()`, addressing each one's user-settings section, so configuration surfaces can offer dormant providers before any route registers.
-
-```ts type-equiv
-/**
- * One provider route an adapter plugin can activate through configuration,
- * whether or not the route is currently registered. Configuration surfaces
- * merge this directory with `listProviders()` to offer every configurable
- * provider alongside its live/dormant state.
- */
-interface LlmConfigurableProvider {
-  /** Provider route key this entry activates when configured. */
-  provider: string
-  /** Human-readable provider name for configuration surfaces. */
-  displayName: string
-  /** User-settings namespace whose section configures this provider. */
-  settingsNs: string
-  /**
-   * Path from that namespace's section root to this provider's profile
-   * object; empty when the whole section is the profile.
-   */
-  settingsPath: readonly string[]
-}
-```
-
-```ts type-equiv
-/** One adapter-discovered model; catalog membership is advisory, not request validation. */
-interface LlmModelInfo {
-  /** Provider route that owns this model entry. */
-  provider: string
-  /** Model id passed to {@link GenerateOptions.model}. */
-  id: string
-  /** Human-readable model name for selectors. */
-  name: string
-  /** Optional user-facing distinction from otherwise similar models. */
-  description?: string
-}
-```
-
-A provider a surface is still drafting has no route and no catalog, so interrogation is described separately: the request carries the draft the user is editing, and the reply is candidates a surface may adopt rather than a catalog it must serve.
-
-```ts type-equiv
-/**
- * One interrogation of a provider endpoint that configuration has not stored
- * yet. Configuration surfaces send the draft a user is still editing, so the
- * request carries the endpoint and credential directly instead of naming a
- * route: a provider being added has no route to name.
- */
-interface LlmModelDiscoveryRequest {
-  /**
-   * Route the draft is editing, when it edits an existing one. A route whose
-   * adapter already knows its models answers from that knowledge instead of
-   * asking the endpoint — the adapter's own registry is the better answer, and
-   * it costs no network call.
-   */
-  provider?: string
-  /**
-   * Endpoint to interrogate. Optional because a route the adapter already
-   * describes needs none; a route it does not must supply one.
-   */
-  baseURL?: string
-  /** Wire protocol the endpoint speaks, when the draft names one. */
-  api?: string
-  /** Credential for this interrogation alone; the harness never stores it. */
-  apiKey?: string
-  /** Caller cancellation; implementations must settle promptly after it aborts. */
-  signal?: AbortSignal
-}
-```
-
-```ts type-equiv
-/**
- * One model an endpoint reports about itself. Every field but the id is
- * optional because most provider listings disclose an id and nothing else;
- * a surface adopting one of these still owes the capacities its adapter needs.
- */
-interface LlmDiscoveredModel {
-  /** Model id the endpoint accepts. */
-  id: string
-  /** Human-readable name when the endpoint supplies one. */
-  name?: string
-  /** Maximum combined request and response context, when disclosed. */
-  contextWindow?: number
-  /** Maximum output tokens, when disclosed. */
-  maxTokens?: number
-}
-```
-
-Correctness-sensitive metadata is resolved separately from the advisory catalog and is owned by the adapter serving the exact route. Context capacity, adapter call defaults, and reasoning choices share one exact-model result so consumers do not repeat authoritative model resolution.
-
-```ts type-equiv
-/** Provider-owned context capacity for one exact provider/model route. */
-interface LlmModelContext {
-  /** Maximum combined request and response context in tokens. */
-  contextWindow: number
-}
-```
-
-Reasoning effort is another exact-route capability. The core brands identifiers but does not enumerate their values; each adapter owns the ordered set, display names, and optional deployment default.
-
-```ts type-equiv
-/** Adapter-owned identifier for one model's selectable reasoning effort. */
-type ReasoningEffortId = Branded<'ReasoningEffortId'>
-```
-
-```ts type-equiv
-/** Display metadata for one adapter-owned reasoning effort. */
-interface LlmReasoningEffortInfo {
-  /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
-  id: ReasoningEffortId
-  /** Human-readable effort name for selectors and diagnostics. */
-  name: string
-  /** Optional user-facing distinction from otherwise similar efforts. */
-  description?: string
-}
-```
-
-```ts type-equiv
-/** Selectable reasoning efforts for one exact provider/model route. */
-interface LlmModelReasoningInfo {
-  /** Supported efforts in adapter-preferred display order. */
-  efforts: readonly LlmReasoningEffortInfo[]
-  /**
-   * Adapter-configured default materialized into requests when callers omit
-   * an effort. Absence preserves the provider's own default.
-   */
-  defaultEffort?: ReasoningEffortId
-}
-```
-
-```ts type-equiv
-/** Exact-route model metadata resolved by its owning adapter. */
-interface LlmResolvedModelInfo extends LlmModelInfo {
-  /** Provider-owned context capacity when known. */
-  context?: LlmModelContext
-  /** Adapter-configured per-request output cap materialized when callers omit one. */
-  defaultMaxTokens?: number
-  /** Adapter-owned selectable reasoning levels when exposed. */
-  reasoning?: LlmModelReasoningInfo
-}
-```
-
-```ts type-equiv
-/** A single model request, fully assembled. */
-interface GenerateOptions {
-  /** Registered provider route selecting the adapter instance. */
-  provider: string
-  model: string
-  /** Adapter-owned reasoning effort selected for this exact model. */
-  reasoningEffort?: ReasoningEffortId
-  /**
-   * Ordered conversation messages, exactly as the provider sees them (after
-   * the `system` slot). A loop-built request assembles them as
-   * the derived history (dsh-agent-loop); a hand-built one-shot passes any list.
-   */
-  messages: Message[]
-  /** System prompt text (adapters map to the provider's system slot). */
-  system?: string
-  /** Tool schemas (adapters map to the provider's `tools` field). */
-  tools?: ToolSchema[]
-  temperature?: number
-  maxTokens?: number
-  /**
-   * Stop sequences: generation halts as soon as the model produces any one of
-   * these strings (adapters map to the provider's stop field, e.g. OpenAI
-   * `stop`). The stop string itself is not included in the output.
-   */
-  stop?: string[]
-  signal?: AbortSignal
-  /**
-   * Session identity stamped by the loop for listener routing. Adapters ignore
-   * it; replay uses it to keep concurrent parent and child cursors independent.
-   */
-  sessionId?: Branded<'SessionId'>
-  /**
-   * Provider-neutral classification for an auxiliary model call. Adapters may
-   * map the purpose to model-hidden transport metadata or purpose-specific
-   * generation policy. Ordinary conversation requests leave it unset.
-   */
-  purpose?: 'compaction' | 'session-title'
-}
-```
-
-Why a model response stopped is a merge-extensible reason. Terminal provider failures carry the streaming contract's [`LlmFailure`](llm-streaming.md#llmfailure):
-
-```ts type-equiv
-/**
- * Why a model response stopped.
- * Merge-extensible so adapters can surface provider-specific reasons.
- */
-interface FinishReasonMap {
-  'stop': { kind: 'stop' }
-  'tool-calls': { kind: 'tool-calls' }
-  'max-tokens': { kind: 'max-tokens' }
-  'aborted': { kind: 'aborted'; failure: LlmFailure }
-  'error': { kind: 'error'; failure: LlmFailure }
-}
-```
-
-`FinishReason = FinishReasonMap[keyof FinishReasonMap]`. `TokenUsage` (per-call accounting with disjoint cache fields) is detailed on [llm-streaming.md](llm-streaming.md).
-
-`GenerateOptions.tools` carries `ToolSchema` — the JSON-schema description of a tool, as sent to the model. It is declared in dsh-llm (not dsh-tools) precisely because it is part of the request the loop assembles every step:
-
-```ts type-equiv
-/**
- * JSON-schema description of a tool, as sent to the model.
- *
- * Declared here (not in dsh-tools) because it is part of {@link GenerateOptions};
- * dsh-tools' ToolDefinition and dsh-system-prompt's PromptAssembly both import
- * it from this package.
- */
-interface ToolSchema {
-  name: string
-  description: string
-  /** JSON Schema object for the arguments. */
-  parameters: Record<string, unknown>
-}
-```
-
-The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` that produces it (schema + `execute`) is on [tools.md](tools.md).
-
-### The request envelope: `LlmCallConfig` and the logged header
-
-The loop builds each request from logged state. `EpochHeader` records call config, adapter-default provenance, rendered prompt, and authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
-
-`agent/request` receives a frozen call-config seed and may return a replacement to switch provider, model, reasoning effort, or sampling. Before the waterfall, the loop removes values marked as adapter defaults so exact-model preparation materializes the selected route's current values; unmarked explicit settings remain in the proposal. After the waterfall, preparation rejects unsupported explicit effort ids without clamping and logs the effective config plus provenance under the turn signal. The prepared call keeps one adapter registration through dispatch. Requests reaching `llm/stream` are deep-frozen, so mutation throws, and carry a process-local loop identity so observers do not confuse separately logged frozen auxiliary calls with conversation requests.
-
-On the wire, a loop-built request reads the `system` slot (the rendered prompt assembly) followed by the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps. The dev invariant recomputes exactly this equation against every loop-built request.
-
-```ts type-equiv
-/**
- * Provider, model, reasoning effort, and sampling scalars of one conversation's
- * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
- * the loop builds requests from the logged header rather than accepting these
- * per call.
- */
-interface LlmCallConfig {
-  provider: string
-  model: string
-  reasoningEffort?: ReasoningEffortId
-  temperature?: number
-  maxTokens?: number
-  stop?: string[]
-}
-```
-
-```ts type-equiv
-/**
- * Effective config fields supplied by exact-model adapter resolution rather
- * than by the caller's request proposal.
- */
-interface LlmCallConfigAdapterDefaults {
-  reasoningEffort?: true
-  maxTokens?: true
-}
-```
-
 ## Sessions
 
 A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. The event vocabulary derives from `SessionEventMap`:
@@ -531,7 +89,7 @@ Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/t
  *
  * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
  * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`).
+ * `assistant/message`, `tool/result`, `steering/message`).
  * Non-surface events (boundary markers, chunks, usage, errors) never carry
  * surface metadata — the compiler enforces this at `Session.append()`
  * call sites.
@@ -559,7 +117,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-The session event variants, `deriveMessages()` projection rules, `TurnEndReason` vocabulary, and execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
+The twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
 
 ## The agent handle
 
@@ -568,11 +126,72 @@ The session event variants, `deriveMessages()` projection rules, `TurnEndReason`
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
 ```ts type-equiv
-/** One of the two ordered pending-message lists owned by an agent. */
-type InboxTarget = 'next-turn' | 'next-step'
+/**
+ * Which inbox queue a {@link Agent.send} item joins:
+ * - `next-turn` — the item becomes its own turn, claimed at a turn boundary.
+ * - `next-step` — during prompt admission or an open turn, the item stages for
+ *   the next safe step boundary; otherwise it is promoted per its `wakeup`
+ *   flag.
+ */
+type SendTarget = 'next-turn' | 'next-step'
 ```
 
-Every pending occurrence is its `UserMessage`; `MessageId` is the sole identity. `Inbox.append`, `prepend`, `replace`, `remove`, `clear`, `splice`, and `claim` record normalized durable `agent/inbox/spliced` mutations and reject duplicate pending ids. `replace(messageId, newMessage)` and `remove(messageId)` locate the pending message across both lists; replacement may change identity and emits the old message as discarded followed by the new message as inserted. Ordinary removals and `clear()` are cancellations. `claim(target)` removes the proposed step batch — all `next-step` input plus, at a turn boundary, one `next-turn` message — through pure deletion splices without emitting discarded notifications, and the loop separately emits per-message claimed notifications. Whole-queue consumers such as UI projections reconstruct `nextTurn` and `nextStep` from the durable splices, while consumers following one message use the exact `agent/inbox/inserted`, `claimed`, and `discarded` notifications.
+```ts type-equiv
+/** Resolved inbox placement reported when an accepted message is enqueued. */
+type InboxPlacement = 'queued' | 'steering'
+```
+
+`InboxItemId` is a process-local branded string minted for each accepted FIFO occurrence. It is intentionally distinct from `MessageId`: sending the same immutable message twice creates two independently addressable pending items.
+
+```ts type-equiv
+/** One independently addressable accepted occurrence in an agent inbox. */
+interface InboxItem {
+  /** Agent-loop-minted occurrence identity. */
+  readonly id: InboxItemId
+  /** Identified message delivered by the caller. */
+  readonly message: UserMessage
+  /** Acceptance-time FIFO classification. */
+  readonly placement: InboxPlacement
+}
+```
+
+```ts type-equiv
+/** A user-requested mutation of one still-pending queued occurrence. */
+type InboxAction =
+  | { readonly kind: 'edit'; readonly content: ContentBlock[] }
+  | { readonly kind: 'remove' }
+  | { readonly kind: 'steer' }
+```
+
+```ts type-equiv
+/** Result of applying an inbox action at the synchronous ownership boundary. */
+type InboxActionResult = 'applied' | 'not-found' | 'steer-unavailable'
+```
+
+```ts type-equiv
+/**
+ * Options for the unified {@link Agent.send} primitive over the
+ * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
+ * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
+ * {@link Agent.inject} (`next-step`/no-wakeup).
+ *
+ * The object is complete so routing policy is explicit.
+ */
+interface SendOptions {
+  /** Queue the item joins. */
+  target: SendTarget
+  /**
+   * Whether this item makes the model run: wake a parked driver (`next-turn`)
+   * or force a continuation step (`next-step` while running). A `false`
+   * `next-turn` item queues without waking; a `false`
+   * `next-step` item attaches durable context without forcing another step
+   * (the injection preset).
+   */
+  wakeup: boolean
+}
+```
+
+The fixed-preset aliases own `target` and `wakeup`; their already identified `UserMessage` carries role, content, and provenance. Its `MessageId` remains stable when an edit replaces content or strict steer transfers the immutable message. The original queued occurrence ends and strict steer accepts a new steering occurrence with a distinct `InboxItemId`. Injection bypasses the FIFOs and never appears on inbox lifecycle events.
 
 ```ts type-equiv
 /** Options for {@link Agent.cancel}. */
@@ -580,25 +199,28 @@ interface CancelOptions {
   /**
    * Preserve queued and steering inbox items instead of discarding them. The
    * active turn is still aborted, but un-started and pending work survives for a
-   * later turn and no canceled inbox splice is logged.
+   * later turn and no `agent/inbox/discard` fires.
    */
-  keepInbox?: boolean | undefined
+  keepInbox?: boolean
 }
 ```
 
+`SteeringReceipt.outcome` always resolves. `admitted` identifies the turn and step whose immutable request history contains that exact message; `rejected` means lifecycle or terminal policy discarded it first. Synchronous input validation still throws from `steer()`.
+
 ```ts type-equiv
-/** Why an active agent driver was cancelled. */
+/** Stable runtime cause accepted by {@link Agent.cancel}. */
 type AgentCancelCause =
   | { readonly kind: 'user' }
   | { readonly kind: 'parent' }
-  | { readonly kind: 'hook'; readonly reason: string }
-  | { readonly kind: 'disposed' }
 ```
 
-`Agent` is an interface over the public live-agent contract. Its unified `send` method exposes target and wakeup routing directly; `followup`, `steer`, and `inject` are fixed-preset aliases.
+`Agent` is an interface over the public live-agent contract. Concrete drivers own the `followup`/`steer`/`inject` aliases and route them through `send`'s (`target` × `wakeup`) matrix.
 
 ```ts type-equiv
-/** Public live-agent handle. */
+/**
+ * Public live-agent handle with aliases over the unified delivery primitive.
+ * @typert object
+ */
 interface Agent {
   /** The single identity shared with {@link session}. */
   readonly id: SessionId
@@ -606,28 +228,78 @@ interface Agent {
   readonly options: AgentOptions
   /** The live session this agent drives; its log is the durable source of truth. */
   readonly session: Session
-  /** The agent-owned projection of durable pending work. */
-  readonly inbox: Inbox
   /** The current lifecycle state, mirrored on every `agent/status` transition. */
   readonly status: AgentStatus
+  /**
+   * Whether a `next-step` send currently stages for prompt admission or the
+   * open turn. Unlike {@link status}, this excludes admission exit and turn
+   * settlement, when a waking `next-step` send becomes a queued follow-up.
+   */
+  readonly acceptsNextStep: boolean
   /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
+  /**
+   * The unified delivery primitive over the (`target` × `wakeup`) matrix.
+   * It routes the caller's typed content and source as follows:
+   *
+   * - `next-turn` queues an item that becomes the sole ordinary message of its
+   *   own FIFO-ordered turn; `wakeup:true` wakes a
+   *   parked driver, while `wakeup:false` queues without waking.
+   * - `next-step` with `wakeup:true` stages steering during prompt admission
+   *   or an open turn; outside that window it falls back to a woken
+   *   `next-turn`.
+   * - `next-step` with `wakeup:false` injects durable model-facing context
+   *   without running the model: admission or an open turn stages it for the
+   *   next safe log position, while an injection outside that window appends
+   *   immediately without opening a turn. If admission closes without a turn,
+   *   a context-only boundary appends immediately; context staged beside
+   *   steering remains pending with it.
+   * The agent publishes or queues the identified frozen message as-is.
+   * @param message - identified model-facing content and its producer provenance.
+   * @param options - target queue and wakeup decision.
+   */
+  send(message: UserMessage, options: SendOptions): void
+
+  /**
+   * Reserve admission of the next ordinary turn while this agent is idle, so an
+   * operation can mutate durable history before any queued prompt derives a
+   * request from it. Already-accepted waking work has right of way, including a
+   * send whose wake is still a pending microtask. Later sends keep their
+   * ordinary placement, FIFO order, and `wakeup` facts, and
+   * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes
+   * a queued follow-up rather than steering; cancellation and disposal may
+   * still discard them. {@link inject} is not withheld. {@link whenIdle} treats
+   * a live reservation as activity, while lifecycle teardown does not await it.
+   * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work.
+   */
+  reserveTurnAdmission(): (() => void) | undefined
+
+  /**
+   * Mutate one still-pending queued occurrence synchronously. Editing preserves
+   * the message identity and queue position; removal publishes its terminal
+   * discard. Steer strictly transfers the message into the current next-step
+   * window, or returns `steer-unavailable` without changing the queued
+   * occurrence. Steering occurrences and driver-claimed items return
+   * `not-found`.
+   * @param id - independently addressable queued occurrence.
+   * @param action - edit, remove, or strict steer operation.
+   * @returns the applied outcome or the reason no mutation occurred.
+   */
+  updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult
+
   /**
    * Clear queued and steering work — unless `keepInbox` — and abort the active
-   * turn or between-turn task. The first cause wins for that activity. With no
-   * active activity, cancellation is a no-op and does not arm later work.
-   * @param cause - the stable caller intent carried by the active operation signal.
+   * turn. An effective call first emits `agent/cancel-requested` with the
+   * resolved typed cause. The first cause wins for the active turn, and
+   * `whenIdle()` resolves after cancellation reaches quiescence. Idle
+   * cancellation is a no-op and does not arm later work.
+   * @param cause - the stable caller intent carried by the current turn signal.
    * @param options - cancellation options; `keepInbox` preserves pending work.
    */
   cancel(cause: AgentCancelCause, options?: CancelOptions): void
 
-  /**
-   * Resolve after the current whole-agent activity reaches quiescence. This
-   * follows replacement work started before the observed driver retires,
-   * but does not identify the settlement of any particular message.
-   * @returns fulfillment after no active driver or maintenance task remains.
-   */
+  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
   whenIdle(): Promise<void>
 
   /**
@@ -662,29 +334,35 @@ interface Agent {
   followup(message: UserMessage): void
 
   /**
-   * Submit steering for the nearest step. An idle driver starts a turn;
-   * a running driver consumes it at its next step boundary.
-   * A rejected step leaves steering parked in the inbox until the next
-   * wake; cancellation or disposal may discard pending steering.
+   * Submit steering with a message-owned admission receipt — the
+   * `next-step`/wakeup preset of {@link send}. During prompt admission or an
+   * open turn, the message waits in the steering FIFO until a committed step
+   * snapshots it; outside that window it enters the ordinary queued FIFO. The
+   * receipt resolves `admitted` only after the message joins that step's
+   * immutable request history, or `rejected` when terminal policy,
+   * cancellation, or disposal discards it first. A non-terminal turn close may
+   * leave it staged for a later admitted prompt without settling the receipt.
    * @param message - identified steering content and its producer provenance.
+   * @returns the receipt for this exact message's eventual admission outcome.
    */
-  steer(message: UserMessage): void
+  steer(message: UserMessage): SteeringReceipt
 
   /**
-   * Queue model-facing context for the next pre-step without waking the
-   * driver. A running driver claims it at the nearest later step boundary;
-   * idle drivers leave it pending until follow-up or steering
-   * wakes them. It may miss a request whose pre-step already claimed its
-   * batch. Cancellation or disposal may discard pending context.
+   * Append model-facing context without running the model — the
+   * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn
+   * stages it at the next safe log position; outside that window it appends
+   * immediately without opening a turn. If admission closes without a turn,
+   * a context-only boundary appends immediately; context staged beside
+   * steering remains pending with it.
    * @param message - identified injected context and its producer provenance.
    */
   inject(message: UserMessage): void
 }
 ```
 
-`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `followup()` returns no handle: its `MessageId` identifies durable inbox insertion, claim, and discard facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([decision](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default.
+`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `acceptsNextStep` is the narrower routing predicate for callers that must choose between steering the current admission/turn and submitting a fresh admitted prompt. A live turn-admission reservation is quiescence-relevant without changing `status` or turning later queue entries into steering; its only authority is to defer the next driver claim until release. `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default.
 
-The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
+The cause is a TypeScript-enforced same-process input. An active `TurnCancellation` holder copies its discriminant into the runtime-only `AbortSignal.reason` and is retired before `turn/end` publication; the frozen `AbortSignal.reason` remains readable after that retirement. Only the loop reads the cause (`user`, `parent`, or lifecycle-only `disposed`) back off its own machine-private signal at settlement — there is no public reader, and a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
 
 The [event taxonomy](../architecture.md#event) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits.
 
@@ -694,19 +372,22 @@ The process-local initiator carried by `ctx.agents` is the exact `Agent` above,
 
 ## Interception decisions
 
-Pre-step decisions use the same identified `UserMessage` shape as durable user-role input. The entered batch is authoritative and preserves every message's identity and provenance. Hook bridges map their native decision fields onto this typed result.
+Prompt and post-tool decisions use the same identified `UserMessage` shape as durable user-role input. Each `additionalContexts` entry becomes a separate `user/message`, preserving its identity and provenance. Hook bridges map their native decision fields onto these typed results.
 
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
-`agent/pre-step` receives one payload carrying the exclusive claimed batch (`messages`), the proposed step's coordinates (`turn`, `step`), and the current turn's cancellation `signal`. The initial proposal runs inside an open turn before any step; a tool continuation may submit an empty claimed batch between steps:
-
-It returns a `PreStepDecision`. Reject opens no step. Enter supplies the complete message batch appended after `step/start`; claimed messages omitted by the final decision remain removed, while input inserted after the claim stays pending:
+`agent/prompt-submit` returns a `PromptDecision` before a turn opens. Allow may rewrite the claimed prompt or attach `additionalContexts`; block rejects admission without creating turn events:
 
 ```ts type-equiv
-/** Whether and with which messages the loop enters a proposed step. */
-type PreStepDecision =
-  | { kind: 'reject' }
-  | { kind: 'enter'; messages: UserMessage[] }
+/**
+ * Prompt interception result. `allow.content` replaces the prompt, while
+ * `additionalContexts` appends model-facing context before the turn starts.
+ * An `allow` returned by a listener is authoritative: a listener wrapping
+ * `next()` preserves both fields unless it intentionally replaces them.
+ */
+type PromptDecision =
+  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
+  | { kind: 'block'; reason: string }
 ```
 
 `agent/request-error` runs after a failed model step closes and before its turn closes. Listeners can repair durable state or await policy work while the failed turn's signal is still live. A handling listener returns `{ kind: 'retry' }` without calling `next()`; the default `undefined` leaves the failure terminal.
@@ -716,7 +397,12 @@ type PreStepDecision =
 type RequestErrorAction = { kind: 'retry' } | undefined
 ```
 
-`agent/pre-step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
+```ts type-equiv
+/** Model-request failure with an optional machine-routable provider code. */
+type RequestError = Error & { code?: string }
+```
+
+`agent/step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
 
 `agent/session-start` carries a `SessionStartSource` (why the session lifecycle began; a bridge keys its SessionStart matcher on it):
 
@@ -776,7 +462,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl
 
 Types: [SessionHeader](persistence.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:252`](../../packages/core/agent-loop/src/index.ts)
 
 <a id="ctxagents--agentregistry"></a>
 
@@ -954,6 +640,29 @@ Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/i
 
 ### `agent/*` events
 
+<a id="agentcancel-requested--emit"></a>
+
+#### `agent/cancel-requested` — emit
+
+Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained.
+
+```ts cordis-catalog
+/**
+ * Effective broad cancellation was requested, before queued/outbox work
+ * is cleared or the active turn is aborted. This observe-only notification
+ * cannot veto cancellation; listener failures are contained.
+ * @param agent - the agent whose current work is being cancelled.
+ * @param cause - the explicit typed cancellation cause.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, cause: AgentCancelCause): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts)
+
 <a id="agentcreated--emit"></a>
 
 #### `agent/created` — emit
@@ -967,11 +676,11 @@ A fully configured agent and live session were published. Setup is composition-o
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
- * @param payload.agent - the newly registered agent with its live session and completed setup.
+ * @param agent - the newly registered agent with its live session and completed setup.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
+'agent/created'(this: Scoped<Agent>, agent: Agent): void
 ```
 
 Types: [Scoped](scope.md)
@@ -989,11 +698,11 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
  * An agent left the registry; AgentLoop emits this after driver quiescence
  * and scoped-registration unwind, but before session detachment. Custom
  * registry users own their driver-ordering contract.
- * @param payload.agent - the exact agent removed from the registry.
+ * @param agent - the exact agent removed from the registry.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
+'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1004,111 +713,138 @@ Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/t
 
 #### `agent/error` — emit
 
-A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
+A step or turn errored. The machine reports a failure here (plus the logger) even when the error has no in-turn position for a durable record.
 
 ```ts cordis-catalog
 /**
- * A step or turn errored. The machine reports a failure here even when
- * the error has no in-turn position for a durable record.
- * @param payload.agent - the agent whose turn errored.
- * @param payload.turn - the turn in which the failure surfaced.
- * @param payload.step - the step at which the failure surfaced.
- * @param payload.error - the failure, verbatim.
+ * A step or turn errored. The machine reports a failure here (plus the
+ * logger) even when the error has no in-turn position for a durable record.
+ * @param agent - the agent whose turn errored.
+ * @param turn - the turn in which the failure surfaced.
+ * @param step - the step at which the failure surfaced.
+ * @param error - the failure, verbatim.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
+'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
 ```
 
 Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxclaimed--emit"></a>
+<a id="agentinboxdequeue--emit"></a>
 
-#### `agent/inbox/claimed` — emit
+#### `agent/inbox/dequeue` — emit
 
-One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
+The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message.
 
 ```ts cordis-catalog
 /**
- * One message left the inbox inside its open turn. If the proposed step
- * is rejected, the claimed message ends here: it is neither discarded nor
- * re-emitted as a user/message, and the turn closes without a step.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the claimed message.
- * @param payload.turn - the owning turn.
+ * The driver claimed one item out of the inbox: a queued item at a turn
+ * boundary, or steering drained between steps. Fires after the item leaves
+ * its FIFO and before it becomes a durable message.
+ * @param agent - the agent whose inbox item was claimed.
+ * @param item - the exact claimed occurrence.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
+'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdiscarded--emit"></a>
+<a id="agentinboxdiscard--emit"></a>
 
-#### `agent/inbox/discarded` — emit
+#### `agent/inbox/discard` — emit
 
-One message was discarded from the live inbox.
+Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item.
 
 ```ts cordis-catalog
 /**
- * One message was discarded from the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the discarded message.
+ * Pending inbox items were dropped without delivering them, so every
+ * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
+ * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,
+ * emits this after `agent/cancel-requested` when applicable and before
+ * aborting the active work. Fires once per drop with every dropped item.
+ * @param agent - the agent whose inbox items were dropped.
+ * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItem[]): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxinserted--emit"></a>
+<a id="agentinboxenqueue--emit"></a>
 
-#### `agent/inbox/inserted` — emit
+#### `agent/inbox/enqueue` — emit
 
-One message entered the live inbox.
+An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state.
 
 ```ts cordis-catalog
 /**
- * One message entered the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the inserted message.
+ * An item entered the queued or steering inbox. `placement` is the
+ * acceptance-time routing result; listeners must not reconstruct it from
+ * later agent or session state.
+ * @param agent - the owning agent.
+ * @param item - accepted occurrence, message, and resolved placement.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
-<a id="agentpre-step--waterfall"></a>
+<a id="agentinboxupdate--emit"></a>
 
-#### `agent/pre-step` — waterfall
+#### `agent/inbox/update` — emit
 
-Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
+A still-pending queued item changed content. The item id, placement, and position remain stable while the event carries the replacement message.
 
 ```ts cordis-catalog
 /**
- * Reject a proposed step or replace the messages that enter it. Calling
- * `next()` preserves the current messages.
- * @param payload.agent - the agent proposing the step.
- * @param payload.messages - messages removed from the inbox for this step.
- * @param payload.turn - the turn that will own the step.
- * @param payload.step - the step proposed by the loop.
- * @param payload.signal - the current turn's cancellation signal.
+ * A still-pending queued item changed content. The item id, placement, and
+ * position remain stable while the event carries the replacement message.
+ * @param agent - the owning agent.
+ * @param item - the complete post-update occurrence.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/update'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:321`](../../packages/core/agent/src/types.ts)
+
+<a id="agentprompt-submit--waterfall"></a>
+
+#### `agent/prompt-submit` — waterfall
+
+Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn.
+
+```ts cordis-catalog
+/**
+ * Allow, rewrite, or block one claimed prompt before it becomes a user
+ * message or opens a turn. Call `next()` for the unchanged default. The
+ * signal controls only this admission attempt; listeners may cooperate with
+ * it but must not retain it for a later attempt or turn.
+ * @param agent - the agent whose turn claimed the message.
+ * @param message - the frozen claimed message, including identity and source.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
+'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
 ```
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
@@ -1127,17 +863,17 @@ Replace the frozen call configuration. `await next()` yields the config the mach
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
  * content must use logged channels; this seam cannot mutate messages.
- * @param payload.agent - the agent making the model call.
- * @param payload.turn - the open turn number.
- * @param payload.step - the step whose request this is.
- * @param payload.signal - the current turn's explicit abort signal.
+ * @param agent - the agent making the model call.
+ * @param turn - the open turn number.
+ * @param step - the step whose request this is.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
 */
-'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
-Types: [Scoped](scope.md)
+Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
 
@@ -1145,25 +881,28 @@ Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/t
 
 #### `agent/request-error` — waterfall
 
-Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
 
 ```ts cordis-catalog
 /**
- * Handle one failed model-request attempt before the loop retries or closes
- * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
- * when it owns recovery, or calls `next()` to delegate. The default
- * `undefined` leaves the failure terminal.
- * @param payload.agent - the agent whose request failed.
- * @param payload.turn - the turn containing the failed request.
- * @param payload.step - the step containing the failed request attempt.
- * @param payload.provider - the provider selected for the failed request.
- * @param payload.failure - serializable facts normalized at the final adapter boundary.
- * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
- * @param payload.signal - the turn abort signal.
+ * Handle a model-request failure after its failed step has closed but
+ * before the failed turn closes. A listener returns `{ kind: 'retry' }`
+ * without calling `next()` when it owns the error, or calls `next()` to
+ * delegate. The default `undefined` leaves the failure terminal.
+ * @param agent - the agent whose request failed.
+ * @param turn - the open turn number.
+ * @param step - the failed step number.
+ * @param error - the original model-request failure.
+ * @param failure - serializable facts normalized at the final adapter boundary.
+ * @param priorFailures - immutable failures that already authorized another
+ * retry turn in this consecutive sequence.
+ * @param retryPolicy - immutable policy of the adapter registration that served
+ * the failed request, or `undefined` if no final adapter served it.
+ * @param signal - the turn abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
 ```
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
@@ -1182,12 +921,12 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
  * `agent.inject()` to seed model-facing context. This is a notification, not
  * a veto; disposal requested by a lifecycle owner is rechecked before the
  * driver starts.
- * @param payload.agent - the agent whose session lifecycle began.
- * @param payload.source - why the session started (fresh startup, resume, …).
+ * @param agent - the agent whose session lifecycle began.
+ * @param source - why the session started (fresh startup, resume, …).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
+'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1198,19 +937,18 @@ Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/t
 
 #### `agent/status` — emit
 
-Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
+Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event.
 
 ```ts cordis-catalog
 /**
- * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
- * `running` synchronously after reserving cancellation; `idle` means no
- * driver remains scheduled or active.
- * @param payload.agent - the agent whose status flipped.
- * @param payload.status - the status just entered (the transition's destination).
+ * Agent status changed (`idle` ⇄ `running`). `send()` does not enter
+ * `running` synchronously; drive lifecycle from this event.
+ * @param agent - the agent whose status flipped.
+ * @param status - the status just entered (the transition's destination).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
+'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1221,7 +959,7 @@ Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/t
 
 #### `agent/turn-stopping` — serial
 
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step.
 
 ```ts cordis-catalog
 /**
@@ -1231,17 +969,14 @@ The turn is about to close: the model owes no response (no live tool calls, no f
  * re-reads its inbox: fresh steering runs another step, none closes the
  * turn. Data decides, so listener order cannot change the outcome. The
  * inverse control (stop a tool loop early) is data too: a tool result
- * carrying `concludesTurn` ends the turn at its step. The conclusion
- * never short-circuits already-submitted next-step work: same-step
- * `additionalContexts` or racing steering still runs, and the turn
- * closes only when that inbox drains.
- * @param payload.agent - the agent whose turn is at its stop boundary.
- * @param payload.turn - the turn about to close.
- * @param payload.signal - the current turn's explicit abort signal.
+ * carrying `concludesTurn` ends the turn at its step.
+ * @param agent - the agent whose turn is at its stop boundary.
+ * @param turn - the turn about to close.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode serial
  */
-'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
+'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
 ```
 
 Types: [Scoped](scope.md)
@@ -1264,12 +999,12 @@ A declarative agent entry failed before it could publish a live agent. Consumers
  * Consumers that buffer work for the configured identity use this
  * transient signal to reject that work instead of waiting forever. Normal
  * factory teardown suppresses failures from the cancelled startup attempt.
- * @param payload.sessionId - exact shared agent/session identity that failed startup.
- * @param payload.error - persistence, setup, or publication failure.
+ * @param sessionId - exact shared agent/session identity that failed startup.
+ * @param error - persistence, setup, or publication failure.
  * @mode emit
  */
-'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
+'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:157`](../../packages/core/agent-loop/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index fff5bd502c..276dc4f99f 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -1,22 +1,29 @@
-# 核心数据结构
+# 核心
 
 [English](core.md) | 中文
 
-本页编目 DeepSeek Harness 的**核心**数据结构：每个主干类型代表什么、它的字面形状，以及完整细节在哪里。它与 [architecture.md](../architecture.md) 互补——后者描述*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；本页描述行为所操作的*词汇*。同级的各子系统页面见[目录 README](README.md)。
+**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有主干的共享词汇——`Agent` 句柄及其投递与拦截契约，以及全仓通用的类型模式——并指引到该组的专属页面；目录索引见[子系统 README](README.md)。
 
-## 什么算"核心"
+## 主干逐包速览
 
-harness 是一个微内核：一个极小的核心加上众多插件。大多数类型属于某一个插件或某一项能力。但有少数类型构成**主干**——agent loop（智能体循环）及其事件在*每一个*轮次中使用的语言，无论加载了哪些可选插件。这些就是"核心"。
+一个轮次按同一条循环流经六个包：[`agent-loop`](../../packages/core/agent-loop) 中的 driver 认领一条排队的 prompt，在[会话日志](session.md)（`ctx.sessions`）上开启轮次，通过 [system-prompt](system-prompt.md)（`ctx.systemPrompt`）组装请求前缀并从日志派生历史，经 [LLM seam](llm-streaming.md) 流式获取模型响应，经[工具注册表](tools.md)（`ctx.tools`）分发工具调用，并把每个模型可见的事实追加回日志，供下一步派生。
 
-精确地说，一个数据结构是**核心**的，当且仅当满足以下条件之一：
+| 包 | 负责内容 | 页面 |
+|---|---|---|
+| `session/` | 只追加的 `SessionEvent` 日志与内存 store——唯一事实来源（`ctx.sessions`） | [session.md](session.md) |
+| `system-prompt/` | 提示词段落与工具 schema 组装（`ctx.systemPrompt`） | [system-prompt.md](system-prompt.md) |
+| `tools/` | 带作用域的工具注册表与受保护的执行流水线（`ctx.tools`） | [tools.md](tools.md) |
+| `agent/` | `Agent` 接口、实时注册表、发起者作用域与 `agent/*` 事件词汇（`ctx.agents`） | 本页 |
+| `agent-loop/` | 实现公开 `Agent` 契约的具体 driver（`ctx.agentLoop`） | 本页 |
+| `scope/` | 注册表与循环用于构建按 agent 作用域的注册原语 | [scope.md](scope.md) |
 
-1. 它流经 agent loop 主干——循环在每个轮次中持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄本身），与当前加载了哪些插件无关；**或者**
-2. 它是插件作者面向某条流水线编写的代表性类型——`ToolDefinition`（每个工具*是什么*）。
+`scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是 `agent` seam 的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
 
-其他一切都记录在各自的子系统页面上，而非本页。划线的规则是：*你编写、持有或接收的类型是核心；为它提供类型推导、渲染或持久化的机制是其他页面的细节*。因此 `ToolDefinition` 是核心，但为它提供类型推导的 `ValueSchemaSpec`/`ParameterSchemaSpec` 机制、为它提供渲染意图的 `ToolCallView`/`ToolResultView` 词汇，以及存储事件日志的 `SessionPersistence` seam 都不是——它们各有自己的页面（[目录](README.md)）。
+<a id="what-counts-as-core"></a>
 
+## 本页拥有什么
 
-<a id="the-map--derived-union-pattern"></a>
+循环搬运的对话词汇——`Message`、`ContentBlock`、`StreamChunk`、模型请求——由 [`packages/llm`](../../packages/llm/README.md) 声明，记录在 [llm-streaming.md](llm-streaming.md)；会话事件、提示词组装与工具词汇在上表该组的专属页面。留在本页的是所有部分共享的词汇：`Agent` 句柄及其投递、取消与拦截契约（由 `packages/core/agent` 声明）、`SessionEvent` 信封，以及每个子系统都遵循的两个类型模式。范围界定规则记录在[子系统目录 Agent Note](../../.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md)：你编写、持有或接收的类型记录在其声明子系统所在之处；为它提供类型推导、渲染或持久化的机制留在该机制自己的页面。
 
 ## `…Map → derived-union` 模式
 
@@ -39,13 +46,14 @@ declare module '@deepseek-ai/dsh-llm' {
 }
 ```
 
-五个规范 map 使用此模式；插件作者扩展它们：
+六个规范 map 使用此模式；插件作者扩展它们：
 
 | Map | 包 | 派生 | 目录 |
 |---|---|---|---|
-| `ContentBlockMap` | dsh-llm | `ContentBlock` | [下文](#content-blocks-and-messages) |
-| `MessageSourceMap` | dsh-llm | `MessageSource` | [下文](#content-blocks-and-messages) |
-| `FinishReasonMap` | dsh-llm | `FinishReason` | [下文](#the-model-request-and-result) |
+| `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
+| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
 | `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
 | `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
 
@@ -68,460 +76,6 @@ type Branded<B extends string> = string & { readonly [BRAND]: B }
 
 两个核心 ID 是 `CallId`（关联工具调用及其结果；dsh-llm）和 `SessionId`（活跃 agent 与持久会话共享的标识；dsh-session）。能力包也会品牌化各自的 id，例如 [tasks.md](tasks.md) 中的 `TaskId`。
 
-<a id="content-blocks-and-messages"></a>
-
-## 内容块与消息
-
-一段对话由 `Message` 组成；一条消息是一个类型化**内容块**的数组。块的联合类型从 `ContentBlockMap` 派生。
-
-源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
-
-```ts type-equiv
-/**
- * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support.
- */
-interface ContentBlockMap {
-  'text': TextBlock
-  'reasoning': ReasoningBlock
-  'tool-call': ToolCallBlock
-  'tool-result': ToolResultBlock
-}
-```
-
-各块接口（完整字段见源码）：`TextBlock`（`text`）、`ReasoningBlock`（thinking，区别于可见文本）、`ToolCallBlock`（`id: CallId`、`name`、原始 JSON `arguments`）、`ToolResultBlock`（`toolCallId`、嵌套 `content: ContentBlock[]`、`isError?`）。`ContentBlock = ContentBlockMap[ContentBlockType]`。核心集仅限于每条交付路径都尊重的块——多模态内容（图像、音频等）没有核心块类型；需要的功能通过可合并扩展的 map 添加，同时提供适配器/UI/压缩支持。
-
-源码：[`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
-
-`Message` 是一个带标识且不可变的角色／来源／内容值。模型产生的 assistant 消息会在其来源中携带提供方／模型所有权与可选的适配器私有回放元数据：
-
-```ts type-equiv
-/** Provider ownership and adapter-private replay data for an assistant message. */
-interface AssistantProvenance {
-  /** Provider route that produced the message. */
-  provider: string
-  /** Provider model id that produced the message. */
-  model: string
-  /**
-   * Lossless-JSON adapter state needed to replay the provider response.
-   * `LlmService` exposes it to a target adapter only when that adapter instance
-   * currently owns both this historical provider and the target provider.
-   */
-  replayState?: unknown
-}
-```
-
-```ts type-equiv
-/** One immutable message representation shared by delivery, durable history, and model requests. */
-interface Message {
-  /** Stable identity preserved across every representation boundary. */
-  readonly id: MessageId
-  /** Provider-neutral conversation role. */
-  readonly role: 'system' | 'user' | 'assistant'
-  /** Exact model-facing blocks. */
-  readonly content: ContentBlock[]
-  /** Required producer provenance. */
-  readonly source: MessageSource
-}
-```
-
-消息来源本身也是一个可合并扩展的和类型：
-
-```ts type-equiv
-/**
- * Where a message (or injected content) came from.
- * Merge-extensible sum type — plugins add their own `kind`s.
- */
-interface MessageSourceMap {
-  user: { kind: 'user' }
-  plugin: { kind: 'plugin'; plugin: string } & ContextFormed
-  model: ModelMessageSource
-  tool: ToolMessageSource
-}
-```
-
-溯源与形态是相互独立的两根轴。`kind` 回答「由谁产生」；生产方可选混入的 `form` 回答「这是何种形态的信息」，因此多个生产方可以共用一种呈现，一个生产方在一次会话中也可以发出多种形态。该词汇表是语义的，逐个取值增长；未声明或无法识别的取值是有文档的默认，按不透明内容呈现：
-
-```ts type-equiv
-/**
- * What SHAPE of information a producer-supplied context carries, declared by
- * the producer beside its provenance.
- *
- * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
- * of thing it is*, and the two axes are deliberately independent — several
- * producers share one form (three snapshot producers today), and one producer
- * may emit more than one form over a session.
- *
- * The vocabulary is SEMANTIC, never visual: a value states that the content is
- * a file's instructions or a catalog of available items, and a consumer decides
- * what that looks like. Colors, icons, ordering, and collapse defaults are the
- * consumer's business and must not enter this union. It grows one value at a
- * time as producers gain the structured fields their form needs; an absent or
- * unknown value is the documented default, presented as opaque content.
- */
-type ContextForm =
-  /** Instructions read out of workspace files the model is expected to follow. */
-  | 'instructions'
-  /** A catalog of items available in this session, republished as it changes. */
-  | 'catalog'
-  /** Current state, where a later snapshot from the same producer supersedes an earlier one. */
-  | 'snapshot'
-  /** A one-off account of something that just happened; it supersedes nothing. */
-  | 'notice'
-  /** A message another agent addressed to this one. */
-  | 'relay'
-  /** Material lifted out of another session's log, possibly reduced on the way in. */
-  | 'recall'
-```
-
-```ts type-equiv
-/** One named contribution to a `snapshot`-form context, in assembly order. */
-interface ContextSnapshotSection {
-  /** The contributing subsystem's name. */
-  readonly name: string
-  /** That contribution's model-facing text, exactly as assembled. */
-  readonly text: string
-}
-```
-
-```ts type-equiv
-/**
- * Producer-declared {@link ContextForm} and the fields that form requires,
- * mixed into the source shapes that carry one.
- *
- * Discriminated by `form` so a producer cannot declare a shape without the
- * facts that shape is presented from: a `notice` must record its one-line
- * account, a `snapshot` its sections. Omitting `form` stays valid — an
- * undeclared context is the documented default.
- */
-type ContextFormed =
-  | { readonly form?: never }
-  | { readonly form: 'instructions' }
-  | { readonly form: 'catalog' }
-  | {
-    readonly form: 'snapshot'
-    /** The named contributions this snapshot assembled, in order. */
-    readonly sections: readonly ContextSnapshotSection[]
-  }
-  | {
-    readonly form: 'notice'
-    /** One-line account of what happened, shown without expanding the row. */
-    readonly summary: string
-  }
-  | { readonly form: 'relay' }
-  | { readonly form: 'recall' }
-```
-
-## 流式输出
-
-适配器发出原始**分片**协议；循环记录分片（回放保真度），同时将同一批分片送入 `BlockAssembler` 以重建块和消息。`StreamChunk` 是基于 `type` 的封闭判别联合——`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`。
-
-完整联合类型、适配器契约（usage-before-finish、原始 JSON 工具参数、两条认可的错误路径）和 `BlockAssembler` 在 **[llm-streaming.md](llm-streaming.md)** 中。
-
-<a id="the-model-request-and-result"></a>
-
-## 模型请求
-
-一次模型调用是一个完全组装好的 `GenerateOptions`。适配器以原始 `StreamChunk` 流作答；消费方用 `BlockAssembler` 组装它（见 [llm-streaming.md](llm-streaming.md)）。
-
-源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
-
-提供方与模型发现使用小型、提供方无关的描述符。模型目录仅供参考：路由仍以已注册提供方为键，适配器也可以接受未列出的模型 id。
-
-注册适配器会返回一个句柄：既是释放器，也带有原子的路由替换——路由集合由用户配置决定的插件正需要它。
-
-```ts type-equiv
-/**
- * What {@link LlmService.registerAdapter} returns: the disposer, plus an
- * atomic route replacement for the same adapter instance.
- */
-interface AdapterRegistrationHandle {
-  /** Release every route this registration currently holds. */
-  (): void
-  /**
-   * Replace this registration's routes with `providers`, keeping the same
-   * adapter instance. The candidate set is validated in full first — a
-   * conflict with another adapter, an invalid name, or bad provider metadata
-   * throws and leaves the current routes untouched — and the swap itself is
-   * one synchronous section, so no request can observe a gap. An empty array
-   * is legal here (a settings section that emptied holds zero routes while
-   * staying registered), unlike an empty initial registration.
-   *
-   * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
-   * has been released: its routes are gone and its disposer has already run,
-   * so anything registered afterwards would have no owner left to release it.
-   * @param providers - the complete next route set for this registration.
-   */
-  replace(providers: string[]): void
-}
-```
-
-```ts type-equiv
-/** Display metadata for one registered provider route. */
-interface LlmProviderInfo {
-  /** Provider route key used by {@link GenerateOptions.provider}. */
-  id: string
-  /** Human-readable provider name for selectors and diagnostics. */
-  name: string
-}
-```
-
-适配器插件还会通过 `registerConfigurableProviders()` 声明哪些路由*可以*运行，并指明每条路由的用户设置分节，使配置界面能在任何路由注册之前就呈现休眠的提供方。
-
-```ts type-equiv
-/**
- * One provider route an adapter plugin can activate through configuration,
- * whether or not the route is currently registered. Configuration surfaces
- * merge this directory with `listProviders()` to offer every configurable
- * provider alongside its live/dormant state.
- */
-interface LlmConfigurableProvider {
-  /** Provider route key this entry activates when configured. */
-  provider: string
-  /** Human-readable provider name for configuration surfaces. */
-  displayName: string
-  /** User-settings namespace whose section configures this provider. */
-  settingsNs: string
-  /**
-   * Path from that namespace's section root to this provider's profile
-   * object; empty when the whole section is the profile.
-   */
-  settingsPath: readonly string[]
-}
-```
-
-```ts type-equiv
-/** One adapter-discovered model; catalog membership is advisory, not request validation. */
-interface LlmModelInfo {
-  /** Provider route that owns this model entry. */
-  provider: string
-  /** Model id passed to {@link GenerateOptions.model}. */
-  id: string
-  /** Human-readable model name for selectors. */
-  name: string
-  /** Optional user-facing distinction from otherwise similar models. */
-  description?: string
-}
-```
-
-界面正在起草的提供方既没有路由也没有 catalog，因此询问被单独描述：请求携带用户正在编辑的草稿，回复是界面可以采纳的候选，而不是它必须服务的 catalog。
-
-```ts type-equiv
-/**
- * One interrogation of a provider endpoint that configuration has not stored
- * yet. Configuration surfaces send the draft a user is still editing, so the
- * request carries the endpoint and credential directly instead of naming a
- * route: a provider being added has no route to name.
- */
-interface LlmModelDiscoveryRequest {
-  /**
-   * Route the draft is editing, when it edits an existing one. A route whose
-   * adapter already knows its models answers from that knowledge instead of
-   * asking the endpoint — the adapter's own registry is the better answer, and
-   * it costs no network call.
-   */
-  provider?: string
-  /**
-   * Endpoint to interrogate. Optional because a route the adapter already
-   * describes needs none; a route it does not must supply one.
-   */
-  baseURL?: string
-  /** Wire protocol the endpoint speaks, when the draft names one. */
-  api?: string
-  /** Credential for this interrogation alone; the harness never stores it. */
-  apiKey?: string
-  /** Caller cancellation; implementations must settle promptly after it aborts. */
-  signal?: AbortSignal
-}
-```
-
-```ts type-equiv
-/**
- * One model an endpoint reports about itself. Every field but the id is
- * optional because most provider listings disclose an id and nothing else;
- * a surface adopting one of these still owes the capacities its adapter needs.
- */
-interface LlmDiscoveredModel {
-  /** Model id the endpoint accepts. */
-  id: string
-  /** Human-readable name when the endpoint supplies one. */
-  name?: string
-  /** Maximum combined request and response context, when disclosed. */
-  contextWindow?: number
-  /** Maximum output tokens, when disclosed. */
-  maxTokens?: number
-}
-```
-
-对正确性敏感的元数据与参考目录分开解析，并归服务该确切路由的适配器所有。上下文容量、适配器调用默认值和推理选项共用同一个确切模型结果，消费方因而无需重复执行权威模型解析。
-
-```ts type-equiv
-/** Provider-owned context capacity for one exact provider/model route. */
-interface LlmModelContext {
-  /** Maximum combined request and response context in tokens. */
-  contextWindow: number
-}
-```
-
-推理强度是另一项针对确切路由的能力。核心为标识符添加品牌类型，但不枚举其值；有序集合、展示名称和可选的部署默认值均由各适配器持有。
-
-```ts type-equiv
-/** Adapter-owned identifier for one model's selectable reasoning effort. */
-type ReasoningEffortId = Branded<'ReasoningEffortId'>
-```
-
-```ts type-equiv
-/** Display metadata for one adapter-owned reasoning effort. */
-interface LlmReasoningEffortInfo {
-  /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
-  id: ReasoningEffortId
-  /** Human-readable effort name for selectors and diagnostics. */
-  name: string
-  /** Optional user-facing distinction from otherwise similar efforts. */
-  description?: string
-}
-```
-
-```ts type-equiv
-/** Selectable reasoning efforts for one exact provider/model route. */
-interface LlmModelReasoningInfo {
-  /** Supported efforts in adapter-preferred display order. */
-  efforts: readonly LlmReasoningEffortInfo[]
-  /**
-   * Adapter-configured default materialized into requests when callers omit
-   * an effort. Absence preserves the provider's own default.
-   */
-  defaultEffort?: ReasoningEffortId
-}
-```
-
-```ts type-equiv
-/** Exact-route model metadata resolved by its owning adapter. */
-interface LlmResolvedModelInfo extends LlmModelInfo {
-  /** Provider-owned context capacity when known. */
-  context?: LlmModelContext
-  /** Adapter-configured per-request output cap materialized when callers omit one. */
-  defaultMaxTokens?: number
-  /** Adapter-owned selectable reasoning levels when exposed. */
-  reasoning?: LlmModelReasoningInfo
-}
-```
-
-```ts type-equiv
-/** A single model request, fully assembled. */
-interface GenerateOptions {
-  /** Registered provider route selecting the adapter instance. */
-  provider: string
-  model: string
-  /** Adapter-owned reasoning effort selected for this exact model. */
-  reasoningEffort?: ReasoningEffortId
-  /**
-   * Ordered conversation messages, exactly as the provider sees them (after
-   * the `system` slot). A loop-built request assembles them as
-   * the derived history (dsh-agent-loop); a hand-built one-shot passes any list.
-   */
-  messages: Message[]
-  /** System prompt text (adapters map to the provider's system slot). */
-  system?: string
-  /** Tool schemas (adapters map to the provider's `tools` field). */
-  tools?: ToolSchema[]
-  temperature?: number
-  maxTokens?: number
-  /**
-   * Stop sequences: generation halts as soon as the model produces any one of
-   * these strings (adapters map to the provider's stop field, e.g. OpenAI
-   * `stop`). The stop string itself is not included in the output.
-   */
-  stop?: string[]
-  signal?: AbortSignal
-  /**
-   * Session identity stamped by the loop for listener routing. Adapters ignore
-   * it; replay uses it to keep concurrent parent and child cursors independent.
-   */
-  sessionId?: Branded<'SessionId'>
-  /**
-   * Provider-neutral classification for an auxiliary model call. Adapters may
-   * map the purpose to model-hidden transport metadata or purpose-specific
-   * generation policy. Ordinary conversation requests leave it unset.
-   */
-  purpose?: 'compaction' | 'session-title'
-}
-```
-
-模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式契约的 [`LlmFailure`](llm-streaming.md#llmfailure)：
-
-```ts type-equiv
-/**
- * Why a model response stopped.
- * Merge-extensible so adapters can surface provider-specific reasons.
- */
-interface FinishReasonMap {
-  'stop': { kind: 'stop' }
-  'tool-calls': { kind: 'tool-calls' }
-  'max-tokens': { kind: 'max-tokens' }
-  'aborted': { kind: 'aborted'; failure: LlmFailure }
-  'error': { kind: 'error'; failure: LlmFailure }
-}
-```
-
-`FinishReason = FinishReasonMap[keyof FinishReasonMap]`。`TokenUsage`（逐调用计量，含不相交的缓存字段）详见 [llm-streaming.md](llm-streaming.md)。
-
-`GenerateOptions.tools` 携带 `ToolSchema`——工具的 JSON Schema 描述，发送给模型。它声明在 dsh-llm（而非 dsh-tools）中，正是因为它是循环每一步组装请求的一部分：
-
-```ts type-equiv
-/**
- * JSON-schema description of a tool, as sent to the model.
- *
- * Declared here (not in dsh-tools) because it is part of {@link GenerateOptions};
- * dsh-tools' ToolDefinition and dsh-system-prompt's PromptAssembly both import
- * it from this package.
- */
-interface ToolSchema {
-  name: string
-  description: string
-  /** JSON Schema object for the arguments. */
-  parameters: Record<string, unknown>
-}
-```
-
-面向模型的 `ToolSchema` 是协议格式；产出它的已注册 `ToolDefinition`（schema + `execute`）在 [tools.md](tools.md) 中。
-
-### 请求信封：`LlmCallConfig` 与记录的 header
-
-循环从已记录状态构建每个请求。`EpochHeader` 通过完整的 `request/header` 快照记录调用配置、适配器默认值来源、渲染后的提示词以及权威返回工具顺序（由 `toolOrder` 配置；未配置时按字典序）。结合派生历史，请求便可由会话日志重建。见 [session.md](session.md#the-request-header-event-requestheader) 与[可重建性 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
-
-`agent/request` 接收冻结的调用配置种子，并可返回替代值以切换提供方、模型、推理强度或采样参数。waterfall 开始前，循环会移除标记为适配器默认值的值，使确切模型准备过程填入所选路由的当前值；未带标记的显式设置仍保留在提议中。waterfall 结束后，准备过程会在轮次信号控制下拒绝显式指定但不受支持的推理强度 ID（不自动调整），并记录生效配置及其来源。准备完成的调用直至分派完成始终持有同一项适配器注册。到达 `llm/stream` 的请求会被深度冻结，因此变更会抛异常；请求还携带进程本地循环标识，使观察者不会把单独记录的冻结辅助调用误认成对话请求。
-
-在协议格式上，循环构建的请求先读取 `system` 槽位（渲染后的提示词组装），再读取派生历史——边界快照，其尾部在轮次首步是最新的 `user/message`，在后续步骤是上一步的工具结果。开发不变式针对每个循环构建的请求精确重算此等式。
-
-```ts type-equiv
-/**
- * Provider, model, reasoning effort, and sampling scalars of one conversation's
- * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
- * the loop builds requests from the logged header rather than accepting these
- * per call.
- */
-interface LlmCallConfig {
-  provider: string
-  model: string
-  reasoningEffort?: ReasoningEffortId
-  temperature?: number
-  maxTokens?: number
-  stop?: string[]
-}
-```
-
-```ts type-equiv
-/**
- * Effective config fields supplied by exact-model adapter resolution rather
- * than by the caller's request proposal.
- */
-interface LlmCallConfigAdapterDefaults {
-  reasoningEffort?: true
-  maxTokens?: true
-}
-```
-
 ## 会话
 
 `Session` 是一份类型化 `SessionEvent` 的**仅追加日志**——唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`），而非单独存储。事件词汇从 `SessionEventMap` 派生：
@@ -537,7 +91,7 @@ interface LlmCallConfigAdapterDefaults {
  *
  * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
  * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`).
+ * `assistant/message`, `tool/result`, `steering/message`).
  * Non-surface events (boundary markers, chunks, usage, errors) never carry
  * surface metadata — the compiler enforces this at `Session.append()`
  * call sites.
@@ -565,7 +119,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-会话事件变体、`deriveMessages()` 投影规则、`TurnEndReason` 词汇以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。
+十二种事件变体（`turn/start`、`turn/end`、`step/start`、`step/end`、`user/message`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`steering/message`、`todo/write`、`request/header`）、`deriveMessages()` 投影规则、`TurnTrigger`/`TurnEndReason` 原因以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。
 
 <a id="the-agent-handle"></a>
 
@@ -576,11 +130,72 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
 ```ts type-equiv
-/** One of the two ordered pending-message lists owned by an agent. */
-type InboxTarget = 'next-turn' | 'next-step'
+/**
+ * Which inbox queue a {@link Agent.send} item joins:
+ * - `next-turn` — the item becomes its own turn, claimed at a turn boundary.
+ * - `next-step` — during prompt admission or an open turn, the item stages for
+ *   the next safe step boundary; otherwise it is promoted per its `wakeup`
+ *   flag.
+ */
+type SendTarget = 'next-turn' | 'next-step'
 ```
 
-每个待处理入队项就是其 `UserMessage`；`MessageId` 是唯一标识。`Inbox.append`、`prepend`、`replace`、`remove`、`clear`、`splice` 与 `claim` 会记录规范化的持久 `agent/inbox/spliced` 变更，并拒绝重复的待处理 id。`replace(messageId, newMessage)` 与 `remove(messageId)` 通过 `MessageId` 跨两份列表定位待处理消息；替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。普通删除和 `clear()` 都表示取消。`claim(target)` 通过无 outcome 的纯删除 splice 移除拟进入步骤的批次——全部 `next-step` 输入，外加轮次边界上的一条 `next-turn` 消息——且不发出 discarded 通知；循环另行逐条发出 claimed 通知。UI 投影等整体队列消费方通过持久 splice 重建 `nextTurn` 与 `nextStep`，而跟踪单条消息的消费方使用精确的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知。
+```ts type-equiv
+/** Resolved inbox placement reported when an accepted message is enqueued. */
+type InboxPlacement = 'queued' | 'steering'
+```
+
+`InboxItemId` 是为每次获准进入 FIFO 的项铸造的进程本地品牌字符串。它有意区别于 `MessageId`：同一条不可变消息发送两次，会创建两个可独立寻址的待处理项。
+
+```ts type-equiv
+/** One independently addressable accepted occurrence in an agent inbox. */
+interface InboxItem {
+  /** Agent-loop-minted occurrence identity. */
+  readonly id: InboxItemId
+  /** Identified message delivered by the caller. */
+  readonly message: UserMessage
+  /** Acceptance-time FIFO classification. */
+  readonly placement: InboxPlacement
+}
+```
+
+```ts type-equiv
+/** A user-requested mutation of one still-pending queued occurrence. */
+type InboxAction =
+  | { readonly kind: 'edit'; readonly content: ContentBlock[] }
+  | { readonly kind: 'remove' }
+  | { readonly kind: 'steer' }
+```
+
+```ts type-equiv
+/** Result of applying an inbox action at the synchronous ownership boundary. */
+type InboxActionResult = 'applied' | 'not-found' | 'steer-unavailable'
+```
+
+```ts type-equiv
+/**
+ * Options for the unified {@link Agent.send} primitive over the
+ * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
+ * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
+ * {@link Agent.inject} (`next-step`/no-wakeup).
+ *
+ * The object is complete so routing policy is explicit.
+ */
+interface SendOptions {
+  /** Queue the item joins. */
+  target: SendTarget
+  /**
+   * Whether this item makes the model run: wake a parked driver (`next-turn`)
+   * or force a continuation step (`next-step` while running). A `false`
+   * `next-turn` item queues without waking; a `false`
+   * `next-step` item attaches durable context without forcing another step
+   * (the injection preset).
+   */
+  wakeup: boolean
+}
+```
+
+固定预设的别名方法自带 `target` 与 `wakeup`；其已有标识的 `UserMessage` 会携带角色、内容与 provenance。编辑替换内容或严格 steering（中途引导）转移不可变消息时，其 `MessageId` 都保持稳定。原 queued 单次入队项会结束，严格 steering 则接受一个具有不同 `InboxItemId` 的新 steering 单次入队项。注入绕过两个 FIFO，从不出现在 inbox 生命周期事件中。
 
 ```ts type-equiv
 /** Options for {@link Agent.cancel}. */
@@ -588,25 +203,28 @@ interface CancelOptions {
   /**
    * Preserve queued and steering inbox items instead of discarding them. The
    * active turn is still aborted, but un-started and pending work survives for a
-   * later turn and no canceled inbox splice is logged.
+   * later turn and no `agent/inbox/discard` fires.
    */
-  keepInbox?: boolean | undefined
+  keepInbox?: boolean
 }
 ```
 
+`SteeringReceipt.outcome` 始终会解析。`admitted` 标识其不可变请求历史包含该确切消息的轮次与步骤；`rejected` 表示生命周期或终止策略先丢弃了该消息。同步输入校验仍会从 `steer()` 抛出异常。
+
 ```ts type-equiv
-/** Why an active agent driver was cancelled. */
+/** Stable runtime cause accepted by {@link Agent.cancel}. */
 type AgentCancelCause =
   | { readonly kind: 'user' }
   | { readonly kind: 'parent' }
-  | { readonly kind: 'hook'; readonly reason: string }
-  | { readonly kind: 'disposed' }
 ```
 
-`Agent` 是覆盖公开活跃 agent 契约的接口。它的统一 `send` 方法直接公开目标与唤醒路由；`followup`、`steer` 和 `inject` 是固定预设别名。
+`Agent` 是覆盖公开活跃 agent 契约的接口。具体驱动器拥有 `followup`/`steer`/`inject` 别名方法，并将它们经由 `send` 的（`target` × `wakeup`）矩阵路由。
 
 ```ts type-equiv
-/** Public live-agent handle. */
+/**
+ * Public live-agent handle with aliases over the unified delivery primitive.
+ * @typert object
+ */
 interface Agent {
   /** The single identity shared with {@link session}. */
   readonly id: SessionId
@@ -614,28 +232,78 @@ interface Agent {
   readonly options: AgentOptions
   /** The live session this agent drives; its log is the durable source of truth. */
   readonly session: Session
-  /** The agent-owned projection of durable pending work. */
-  readonly inbox: Inbox
   /** The current lifecycle state, mirrored on every `agent/status` transition. */
   readonly status: AgentStatus
+  /**
+   * Whether a `next-step` send currently stages for prompt admission or the
+   * open turn. Unlike {@link status}, this excludes admission exit and turn
+   * settlement, when a waking `next-step` send becomes a queued follow-up.
+   */
+  readonly acceptsNextStep: boolean
   /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
+  /**
+   * The unified delivery primitive over the (`target` × `wakeup`) matrix.
+   * It routes the caller's typed content and source as follows:
+   *
+   * - `next-turn` queues an item that becomes the sole ordinary message of its
+   *   own FIFO-ordered turn; `wakeup:true` wakes a
+   *   parked driver, while `wakeup:false` queues without waking.
+   * - `next-step` with `wakeup:true` stages steering during prompt admission
+   *   or an open turn; outside that window it falls back to a woken
+   *   `next-turn`.
+   * - `next-step` with `wakeup:false` injects durable model-facing context
+   *   without running the model: admission or an open turn stages it for the
+   *   next safe log position, while an injection outside that window appends
+   *   immediately without opening a turn. If admission closes without a turn,
+   *   a context-only boundary appends immediately; context staged beside
+   *   steering remains pending with it.
+   * The agent publishes or queues the identified frozen message as-is.
+   * @param message - identified model-facing content and its producer provenance.
+   * @param options - target queue and wakeup decision.
+   */
+  send(message: UserMessage, options: SendOptions): void
+
+  /**
+   * Reserve admission of the next ordinary turn while this agent is idle, so an
+   * operation can mutate durable history before any queued prompt derives a
+   * request from it. Already-accepted waking work has right of way, including a
+   * send whose wake is still a pending microtask. Later sends keep their
+   * ordinary placement, FIFO order, and `wakeup` facts, and
+   * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes
+   * a queued follow-up rather than steering; cancellation and disposal may
+   * still discard them. {@link inject} is not withheld. {@link whenIdle} treats
+   * a live reservation as activity, while lifecycle teardown does not await it.
+   * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work.
+   */
+  reserveTurnAdmission(): (() => void) | undefined
+
+  /**
+   * Mutate one still-pending queued occurrence synchronously. Editing preserves
+   * the message identity and queue position; removal publishes its terminal
+   * discard. Steer strictly transfers the message into the current next-step
+   * window, or returns `steer-unavailable` without changing the queued
+   * occurrence. Steering occurrences and driver-claimed items return
+   * `not-found`.
+   * @param id - independently addressable queued occurrence.
+   * @param action - edit, remove, or strict steer operation.
+   * @returns the applied outcome or the reason no mutation occurred.
+   */
+  updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult
+
   /**
    * Clear queued and steering work — unless `keepInbox` — and abort the active
-   * turn or between-turn task. The first cause wins for that activity. With no
-   * active activity, cancellation is a no-op and does not arm later work.
-   * @param cause - the stable caller intent carried by the active operation signal.
+   * turn. An effective call first emits `agent/cancel-requested` with the
+   * resolved typed cause. The first cause wins for the active turn, and
+   * `whenIdle()` resolves after cancellation reaches quiescence. Idle
+   * cancellation is a no-op and does not arm later work.
+   * @param cause - the stable caller intent carried by the current turn signal.
    * @param options - cancellation options; `keepInbox` preserves pending work.
    */
   cancel(cause: AgentCancelCause, options?: CancelOptions): void
 
-  /**
-   * Resolve after the current whole-agent activity reaches quiescence. This
-   * follows replacement work started before the observed driver retires,
-   * but does not identify the settlement of any particular message.
-   * @returns fulfillment after no active driver or maintenance task remains.
-   */
+  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
   whenIdle(): Promise<void>
 
   /**
@@ -670,29 +338,35 @@ interface Agent {
   followup(message: UserMessage): void
 
   /**
-   * Submit steering for the nearest step. An idle driver starts a turn;
-   * a running driver consumes it at its next step boundary.
-   * A rejected step leaves steering parked in the inbox until the next
-   * wake; cancellation or disposal may discard pending steering.
+   * Submit steering with a message-owned admission receipt — the
+   * `next-step`/wakeup preset of {@link send}. During prompt admission or an
+   * open turn, the message waits in the steering FIFO until a committed step
+   * snapshots it; outside that window it enters the ordinary queued FIFO. The
+   * receipt resolves `admitted` only after the message joins that step's
+   * immutable request history, or `rejected` when terminal policy,
+   * cancellation, or disposal discards it first. A non-terminal turn close may
+   * leave it staged for a later admitted prompt without settling the receipt.
    * @param message - identified steering content and its producer provenance.
+   * @returns the receipt for this exact message's eventual admission outcome.
    */
-  steer(message: UserMessage): void
+  steer(message: UserMessage): SteeringReceipt
 
   /**
-   * Queue model-facing context for the next pre-step without waking the
-   * driver. A running driver claims it at the nearest later step boundary;
-   * idle drivers leave it pending until follow-up or steering
-   * wakes them. It may miss a request whose pre-step already claimed its
-   * batch. Cancellation or disposal may discard pending context.
+   * Append model-facing context without running the model — the
+   * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn
+   * stages it at the next safe log position; outside that window it appends
+   * immediately without opening a turn. If admission closes without a turn,
+   * a context-only boundary appends immediately; context staged beside
+   * steering remains pending with it.
    * @param message - identified injected context and its producer provenance.
    */
   inject(message: UserMessage): void
 }
 ```
 
-`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。`followup()` 不返回 handle：其 `MessageId` 标识持久 inbox 的插入、领取与丢弃事实，而不标识之后的助手输出或轮次结束。`whenIdle()` 观察整个 agent，因此只有显式拥有从回执到 idle 这一完整区间的调用方才能将其称为一次运行（[决策](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。
+`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。对于需要在把输入作为 steering 加入当前提示词准入／轮次，还是提交为一个新的待准入提示词之间做选择的调用方，`acceptsNextStep` 才是更窄且准确的路由判断条件。活动的轮次接纳预留与完全停稳相关，但不会改变 `status`，也不会把之后的队列项变成 steering；它的唯一权限是将驱动器的下一次认领延迟到释放时。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。
 
-cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
+cause 是由 TypeScript 强制约束的同进程输入。活跃的 `TurnCancellation` 持有者会把其判别字段复制到仅运行时的 `AbortSignal.reason`，并在发布 `turn/end` 前退役；冻结后的 `AbortSignal.reason` 仍可读取。只有 loop 会在结算时从自己机器私有的 signal 上读回 cause（`user`、`parent` 或仅用于生命周期的 `disposed`）——不存在公开的读取器，signal 也不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
 
 [事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。
 
@@ -702,19 +376,22 @@ cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有
 
 ## 拦截决策
 
-pre-step 决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。进入步骤的批次具有权威性，并保留每条消息的标识与 provenance。钩子桥接层把其原生决策字段映射到这一类型化结果上。
+提示词决策与工具后决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。每个 `additionalContexts` 条目都会成为一条独立的 `user/message`，保留各自的标识与 provenance。钩子桥接层把其原生决策字段映射到这些类型化结果上。
 
 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
-`agent/pre-step` 接收一个 payload，携带独占的已领取批次（`messages`）、拟进入步骤的坐标（`turn`、`step`）与当前轮次的取消 `signal`。首次提案在已打开的轮次内、任何步骤开始前运行；工具 continuation 可以在步骤之间提交空的已领取批次：
-
-它返回 `PreStepDecision`。reject 不会打开步骤。enter 提供在 `step/start` 后追加的完整消息批次；最终决策省略的已领取消息保持已删除，而领取后插入的输入仍留待后续处理：
+`agent/prompt-submit` 在轮次打开前返回 `PromptDecision`。allow 可以改写已领取的提示词或附加 `additionalContexts`；block 拒绝准入且不产生任何轮次事件：
 
 ```ts type-equiv
-/** Whether and with which messages the loop enters a proposed step. */
-type PreStepDecision =
-  | { kind: 'reject' }
-  | { kind: 'enter'; messages: UserMessage[] }
+/**
+ * Prompt interception result. `allow.content` replaces the prompt, while
+ * `additionalContexts` appends model-facing context before the turn starts.
+ * An `allow` returned by a listener is authoritative: a listener wrapping
+ * `next()` preserves both fields unless it intentionally replaces them.
+ */
+type PromptDecision =
+  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
+  | { kind: 'block'; reason: string }
 ```
 
 `agent/request-error` 在失败的模型步骤关闭之后、其轮次关闭之前运行。listener 可以在失败轮次的 signal 仍然存活时修复持久状态或 await 策略工作。处理该错误的 listener 返回 `{ kind: 'retry' }` 且不调用 `next()`；默认的 `undefined` 会让失败保持终态。
@@ -724,7 +401,12 @@ type PreStepDecision =
 type RequestErrorAction = { kind: 'retry' } | undefined
 ```
 
-`agent/pre-step` 是请求推导前唯一的串行边界。`agent/turn-stopping` 在轮次没有工具或 steering（中途引导）后续时运行，先于最后一次 steering 排空。
+```ts type-equiv
+/** Model-request failure with an optional machine-routable provider code. */
+type RequestError = Error & { code?: string }
+```
+
+`agent/step` 是请求推导前唯一的串行边界。`agent/turn-stopping` 在轮次没有工具或 steering（中途引导）后续时运行，先于最后一次 steering 排空。
 
 `agent/session-start` 携带 `SessionStartSource`（会话生命周期为何开始；桥接层据此匹配其 SessionStart）：
 
@@ -784,7 +466,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl
 
 Types: [SessionHeader](persistence.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:252`](../../packages/core/agent-loop/src/index.ts)
 
 <a id="ctxagents--agentregistry"></a>
 
@@ -962,6 +644,29 @@ Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/i
 
 ### `agent/*` events
 
+<a id="agentcancel-requested--emit"></a>
+
+#### `agent/cancel-requested` — emit
+
+Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained.
+
+```ts cordis-catalog
+/**
+ * Effective broad cancellation was requested, before queued/outbox work
+ * is cleared or the active turn is aborted. This observe-only notification
+ * cannot veto cancellation; listener failures are contained.
+ * @param agent - the agent whose current work is being cancelled.
+ * @param cause - the explicit typed cancellation cause.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, cause: AgentCancelCause): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts)
+
 <a id="agentcreated--emit"></a>
 
 #### `agent/created` — emit
@@ -975,11 +680,11 @@ A fully configured agent and live session were published. Setup is composition-o
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
- * @param payload.agent - the newly registered agent with its live session and completed setup.
+ * @param agent - the newly registered agent with its live session and completed setup.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
+'agent/created'(this: Scoped<Agent>, agent: Agent): void
 ```
 
 Types: [Scoped](scope.md)
@@ -997,11 +702,11 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
  * An agent left the registry; AgentLoop emits this after driver quiescence
  * and scoped-registration unwind, but before session detachment. Custom
  * registry users own their driver-ordering contract.
- * @param payload.agent - the exact agent removed from the registry.
+ * @param agent - the exact agent removed from the registry.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
+'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1012,111 +717,138 @@ Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/t
 
 #### `agent/error` — emit
 
-A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
+A step or turn errored. The machine reports a failure here (plus the logger) even when the error has no in-turn position for a durable record.
 
 ```ts cordis-catalog
 /**
- * A step or turn errored. The machine reports a failure here even when
- * the error has no in-turn position for a durable record.
- * @param payload.agent - the agent whose turn errored.
- * @param payload.turn - the turn in which the failure surfaced.
- * @param payload.step - the step at which the failure surfaced.
- * @param payload.error - the failure, verbatim.
+ * A step or turn errored. The machine reports a failure here (plus the
+ * logger) even when the error has no in-turn position for a durable record.
+ * @param agent - the agent whose turn errored.
+ * @param turn - the turn in which the failure surfaced.
+ * @param step - the step at which the failure surfaced.
+ * @param error - the failure, verbatim.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
+'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
 ```
 
 Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxclaimed--emit"></a>
+<a id="agentinboxdequeue--emit"></a>
 
-#### `agent/inbox/claimed` — emit
+#### `agent/inbox/dequeue` — emit
 
-One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
+The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message.
 
 ```ts cordis-catalog
 /**
- * One message left the inbox inside its open turn. If the proposed step
- * is rejected, the claimed message ends here: it is neither discarded nor
- * re-emitted as a user/message, and the turn closes without a step.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the claimed message.
- * @param payload.turn - the owning turn.
+ * The driver claimed one item out of the inbox: a queued item at a turn
+ * boundary, or steering drained between steps. Fires after the item leaves
+ * its FIFO and before it becomes a durable message.
+ * @param agent - the agent whose inbox item was claimed.
+ * @param item - the exact claimed occurrence.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
+'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdiscarded--emit"></a>
+<a id="agentinboxdiscard--emit"></a>
 
-#### `agent/inbox/discarded` — emit
+#### `agent/inbox/discard` — emit
 
-One message was discarded from the live inbox.
+Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item.
 
 ```ts cordis-catalog
 /**
- * One message was discarded from the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the discarded message.
+ * Pending inbox items were dropped without delivering them, so every
+ * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
+ * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,
+ * emits this after `agent/cancel-requested` when applicable and before
+ * aborting the active work. Fires once per drop with every dropped item.
+ * @param agent - the agent whose inbox items were dropped.
+ * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItem[]): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxinserted--emit"></a>
+<a id="agentinboxenqueue--emit"></a>
 
-#### `agent/inbox/inserted` — emit
+#### `agent/inbox/enqueue` — emit
 
-One message entered the live inbox.
+An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state.
 
 ```ts cordis-catalog
 /**
- * One message entered the live inbox.
- * @param payload.agent - the agent whose inbox changed.
- * @param payload.message - the inserted message.
+ * An item entered the queued or steering inbox. `placement` is the
+ * acceptance-time routing result; listeners must not reconstruct it from
+ * later agent or session state.
+ * @param agent - the owning agent.
+ * @param item - accepted occurrence, message, and resolved placement.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
+'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
 ```
 
-Types: [Scoped](scope.md) · [UserMessage](session.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
-<a id="agentpre-step--waterfall"></a>
+<a id="agentinboxupdate--emit"></a>
 
-#### `agent/pre-step` — waterfall
+#### `agent/inbox/update` — emit
 
-Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
+A still-pending queued item changed content. The item id, placement, and position remain stable while the event carries the replacement message.
 
 ```ts cordis-catalog
 /**
- * Reject a proposed step or replace the messages that enter it. Calling
- * `next()` preserves the current messages.
- * @param payload.agent - the agent proposing the step.
- * @param payload.messages - messages removed from the inbox for this step.
- * @param payload.turn - the turn that will own the step.
- * @param payload.step - the step proposed by the loop.
- * @param payload.signal - the current turn's cancellation signal.
+ * A still-pending queued item changed content. The item id, placement, and
+ * position remain stable while the event carries the replacement message.
+ * @param agent - the owning agent.
+ * @param item - the complete post-update occurrence.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
+'agent/inbox/update'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+```
+
+Types: [Scoped](scope.md)
+
+Source: [`packages/core/agent/src/types.ts:321`](../../packages/core/agent/src/types.ts)
+
+<a id="agentprompt-submit--waterfall"></a>
+
+#### `agent/prompt-submit` — waterfall
+
+Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn.
+
+```ts cordis-catalog
+/**
+ * Allow, rewrite, or block one claimed prompt before it becomes a user
+ * message or opens a turn. Call `next()` for the unchanged default. The
+ * signal controls only this admission attempt; listeners may cooperate with
+ * it but must not retain it for a later attempt or turn.
+ * @param agent - the agent whose turn claimed the message.
+ * @param message - the frozen claimed message, including identity and source.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
+'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
 ```
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
@@ -1135,17 +867,17 @@ Replace the frozen call configuration. `await next()` yields the config the mach
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
  * content must use logged channels; this seam cannot mutate messages.
- * @param payload.agent - the agent making the model call.
- * @param payload.turn - the open turn number.
- * @param payload.step - the step whose request this is.
- * @param payload.signal - the current turn's explicit abort signal.
+ * @param agent - the agent making the model call.
+ * @param turn - the open turn number.
+ * @param step - the step whose request this is.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
 */
-'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
-Types: [Scoped](scope.md)
+Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
 
@@ -1153,25 +885,28 @@ Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/t
 
 #### `agent/request-error` — waterfall
 
-Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
 
 ```ts cordis-catalog
 /**
- * Handle one failed model-request attempt before the loop retries or closes
- * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
- * when it owns recovery, or calls `next()` to delegate. The default
- * `undefined` leaves the failure terminal.
- * @param payload.agent - the agent whose request failed.
- * @param payload.turn - the turn containing the failed request.
- * @param payload.step - the step containing the failed request attempt.
- * @param payload.provider - the provider selected for the failed request.
- * @param payload.failure - serializable facts normalized at the final adapter boundary.
- * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
- * @param payload.signal - the turn abort signal.
+ * Handle a model-request failure after its failed step has closed but
+ * before the failed turn closes. A listener returns `{ kind: 'retry' }`
+ * without calling `next()` when it owns the error, or calls `next()` to
+ * delegate. The default `undefined` leaves the failure terminal.
+ * @param agent - the agent whose request failed.
+ * @param turn - the open turn number.
+ * @param step - the failed step number.
+ * @param error - the original model-request failure.
+ * @param failure - serializable facts normalized at the final adapter boundary.
+ * @param priorFailures - immutable failures that already authorized another
+ * retry turn in this consecutive sequence.
+ * @param retryPolicy - immutable policy of the adapter registration that served
+ * the failed request, or `undefined` if no final adapter served it.
+ * @param signal - the turn abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
 ```
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
@@ -1190,12 +925,12 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
  * `agent.inject()` to seed model-facing context. This is a notification, not
  * a veto; disposal requested by a lifecycle owner is rechecked before the
  * driver starts.
- * @param payload.agent - the agent whose session lifecycle began.
- * @param payload.source - why the session started (fresh startup, resume, …).
+ * @param agent - the agent whose session lifecycle began.
+ * @param source - why the session started (fresh startup, resume, …).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
+'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1206,19 +941,18 @@ Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/t
 
 #### `agent/status` — emit
 
-Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
+Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event.
 
 ```ts cordis-catalog
 /**
- * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
- * `running` synchronously after reserving cancellation; `idle` means no
- * driver remains scheduled or active.
- * @param payload.agent - the agent whose status flipped.
- * @param payload.status - the status just entered (the transition's destination).
+ * Agent status changed (`idle` ⇄ `running`). `send()` does not enter
+ * `running` synchronously; drive lifecycle from this event.
+ * @param agent - the agent whose status flipped.
+ * @param status - the status just entered (the transition's destination).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
+'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
 ```
 
 Types: [Scoped](scope.md)
@@ -1229,7 +963,7 @@ Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/t
 
 #### `agent/turn-stopping` — serial
 
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step.
 
 ```ts cordis-catalog
 /**
@@ -1239,17 +973,14 @@ The turn is about to close: the model owes no response (no live tool calls, no f
  * re-reads its inbox: fresh steering runs another step, none closes the
  * turn. Data decides, so listener order cannot change the outcome. The
  * inverse control (stop a tool loop early) is data too: a tool result
- * carrying `concludesTurn` ends the turn at its step. The conclusion
- * never short-circuits already-submitted next-step work: same-step
- * `additionalContexts` or racing steering still runs, and the turn
- * closes only when that inbox drains.
- * @param payload.agent - the agent whose turn is at its stop boundary.
- * @param payload.turn - the turn about to close.
- * @param payload.signal - the current turn's explicit abort signal.
+ * carrying `concludesTurn` ends the turn at its step.
+ * @param agent - the agent whose turn is at its stop boundary.
+ * @param turn - the turn about to close.
+ * @param signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode serial
  */
-'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
+'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
 ```
 
 Types: [Scoped](scope.md)
@@ -1272,12 +1003,12 @@ A declarative agent entry failed before it could publish a live agent. Consumers
  * Consumers that buffer work for the configured identity use this
  * transient signal to reject that work instead of waiting forever. Normal
  * factory teardown suppresses failures from the cancelled startup attempt.
- * @param payload.sessionId - exact shared agent/session identity that failed startup.
- * @param payload.error - persistence, setup, or publication failure.
+ * @param sessionId - exact shared agent/session identity that failed startup.
+ * @param error - persistence, setup, or publication failure.
  * @mode emit
  */
-'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
+'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:157`](../../packages/core/agent-loop/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index cadc2b92d8..e57b2aef45 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 1999399254fa5d72ab222a42a2fa8f4b890da50a
-filesystem.zh.md: 044a1c5be91ed8bec5d0442cc6f7edfde6870785
+filesystem.md: 591f1b4d4b1177ccbe7c2280d2054da5d4be8b99
+filesystem.zh.md: d599e48c1fba2d564a544f628ca3475b781e5cd5
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 1999399254..591f1b4d4b 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -256,6 +256,10 @@ type FsErrorCode =
 
 `FS_NOT_DIRECTORY`, `FS_PERMISSION_DENIED`, and `FS_IO_ERROR` are used by directory listing to distinguish an existing non-directory target, a denied listing, and an unexpected backend I/O failure. `FS_SANDBOX_DENIED` is a POLICY refusal from a sandbox-enforcing backend (`dsh-fs-sandbox`) — the mode fence denied a write/edit — distinct from `FS_PERMISSION_DENIED` (the host kernel refusing). `FS_NOT_OBSERVED` means the policy plugin has no prior-observation record for this owner (or a `createIfAbsent` hit an existing file). `FS_STALE_VERSION` means the backend version no longer matches the observed one (or an edit hit a missing target). Freshness authorization has no partial/full distinction, so there is no `FS_PARTIAL_OBSERVATION`.
 
+## No timeouts on file IO
+
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise, and an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+
 ## The service and the plugin
 
 `FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 044a1c5be9..d599e48c1f 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -256,6 +256,10 @@ type FsErrorCode =
 
 目录列表使用 `FS_NOT_DIRECTORY`、`FS_PERMISSION_DENIED` 与 `FS_IO_ERROR` 区分已存在但并非目录的目标、被拒绝的列表操作和意外的后端 I/O 失败。`FS_SANDBOX_DENIED` 是强制执行沙箱的后端（`dsh-fs-sandbox`）所作的策略拒绝——模式边界拒绝了写入/编辑——与 `FS_PERMISSION_DENIED`（宿主内核拒绝）不同。`FS_NOT_OBSERVED` 表示策略插件没有此所有者的先前观察记录（或 `createIfAbsent` 遇到了现有文件）。`FS_STALE_VERSION` 表示后端版本不再与观察到的版本匹配（或编辑操作遇到缺失目标）。新鲜度授权没有部分/完整之分，因此不存在 `FS_PARTIAL_OBSERVATION`。
 
+## 文件 IO 不设超时
+
+`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方 seam 也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的截止时间会成为无法兑现承诺的旋钮，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。两个参照 agent（Claude Code、Codex）出于同样原因不给文件 IO 计时；取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
+
 ## 服务与插件
 
 `FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index bd1d833f51..f6ce932ad9 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: fe4a831660dd81b33a1cd7dc9a9d7026f3831991
-llm-streaming.zh.md: a10b696ec0887e139785fc7e95d8641e6496de79
+llm-streaming.md: b3f850f4d07ad9e36d0e0db71dd9e0498e468767
+llm-streaming.zh.md: bb31c14b9bd0453399d83968b1062f67819caca3
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index fe4a831660..b3f850f4d0 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -2,10 +2,82 @@
 
 English | [中文](llm-streaming.zh.md)
 
-The wire-level streaming vocabulary of [dsh-llm](../../packages/llm/llm). [core.md](core.md) introduces `StreamChunk`, `Message`, and `ContentBlock`; this page owns the full chunk protocol, the adapter contract every adapter must obey, and the shared assembler.
+The conversation and streaming vocabulary of [`packages/llm`](../../packages/llm/README.md): the `Message`/`ContentBlock` shapes every request and durable history share, the fully-assembled model request, the raw `StreamChunk` protocol, the adapter contract every adapter must obey, and the shared assembler. The [core spine](core.md) holds and logs these values on every turn; this page declares them.
 
 Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 
+<a id="content-blocks-and-messages"></a>
+
+## Content blocks and messages
+
+A conversation is `Message`s; a message is an array of typed **content blocks**. The block union derives from `ContentBlockMap`.
+
+Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+```ts type-equiv
+/**
+ * Merge-extensible content blocks keyed by `type`. New core blocks must land
+ * with adapter, UI, and compaction support.
+ */
+interface ContentBlockMap {
+  'text': TextBlock
+  'reasoning': ReasoningBlock
+  'tool-call': ToolCallBlock
+  'tool-result': ToolResultBlock
+}
+```
+
+The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBlock` (thinking, distinct from visible text), `ToolCallBlock` (`id: CallId`, `name`, raw-JSON `arguments`), `ToolResultBlock` (`toolCallId`, nested `content: ContentBlock[]`, `isError?`). `ContentBlock = ContentBlockMap[ContentBlockType]`. The core set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the merge-extensible map together with the adapter/UI/compaction support that honors it.
+
+Source: [`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
+
+A `Message` is one identified, immutable role/source/content value. Model-produced assistant messages carry provider/model ownership and optional adapter-private replay metadata in their source:
+
+```ts type-equiv
+/** Provider ownership and adapter-private replay data for an assistant message. */
+interface AssistantProvenance {
+  /** Provider route that produced the message. */
+  provider: string
+  /** Provider model id that produced the message. */
+  model: string
+  /**
+   * Lossless-JSON adapter state needed to replay the provider response.
+   * `LlmService` exposes it to a target adapter only when that adapter instance
+   * currently owns both this historical provider and the target provider.
+   */
+  replayState?: unknown
+}
+```
+
+```ts type-equiv
+/** One immutable message representation shared by delivery, durable history, and model requests. */
+interface Message {
+  /** Stable identity preserved across every representation boundary. */
+  readonly id: MessageId
+  /** Provider-neutral conversation role. */
+  readonly role: 'system' | 'user' | 'assistant'
+  /** Exact model-facing blocks. */
+  readonly content: ContentBlock[]
+  /** Required producer provenance. */
+  readonly source: MessageSource
+}
+```
+
+Where a message came from is itself a merge-extensible sum type:
+
+```ts type-equiv
+/**
+ * Where a message (or injected content) came from.
+ * Merge-extensible sum type — plugins add their own `kind`s.
+ */
+interface MessageSourceMap {
+  user: { kind: 'user' }
+  plugin: { kind: 'plugin'; plugin: string }
+  model: ModelMessageSource
+  tool: ToolMessageSource
+}
+```
+
 ## `StreamChunk` — the raw protocol
 
 A streaming response interleaves several typed blocks (text, reasoning, multiple tool calls). `index` ties each delta to its block; `block-end` carries the fully-assembled `ContentBlock` so consumers don't have to re-assemble deltas themselves. It is a **closed** discriminated union — a `switch` over `type` ends with `assertNever`, so adding a variant breaks compilation at every consumer that must handle it.
@@ -15,9 +87,8 @@ A streaming response interleaves several typed blocks (text, reasoning, multiple
  * Raw streaming protocol emitted by adapters.
  * Block indexes correlate interleaved deltas, and `block-end` carries the
  * assembled block. Adapters emit usage before the terminal finish and nothing
- * afterward; tool arguments remain raw JSON strings. An adapter implementation
- * may throw, but `LlmService.stream()` normalizes that failure to a terminal
- * `error` or `aborted` finish before exposing it to consumers.
+ * afterward; tool arguments remain raw JSON strings. Failures either throw or
+ * end with `error`/`aborted`, and consumers must handle both paths.
  */
 type StreamChunk =
   | { type: 'block-start'; index: number; blockType: ContentBlockType }
@@ -65,10 +136,10 @@ Every adapter MUST obey these, and every consumer may rely on them:
 - **Provider stalls are bounded at the transport.** Both shipping remote adapters expose positive finite `streamIdleTimeoutMs` with a five-minute default. The watchdog arms only while iterator `next()` is outstanding, uses one stable signal for the whole request, maps its own expiry to `TIMEOUT`, and keeps an earlier caller abort as `ABORTED`.
 - **Context overflow has one canonical code.** Both DeepSeek adapters classify explicit provider detail through `isContextWindowExceededError()` and surface `CONTEXT_WINDOW_EXCEEDED`, whether the failure arrives as a thrown HTTP `LlmError` or an in-band finish error. Consumers route on the code, never provider text.
 - **An empty completion is a retryable error, not a silent success.** Both adapters map a terminal `stop` finish that carried no content blocks to `finish {kind:'error'}` with the canonical `EMPTY_RESPONSE` code, and `dsh-llm-retry` retries it by default; see [empty model responses are retryable](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md).
-- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below), the `User-Agent` baseline.
+- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test (mock server asserting the received header, or the library's header hook for a library-backed adapter).
 - **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmService` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content and provenance without the private state.
 
-Two independent implementations obey this contract: `dsh-llm-deepseek` uses direct fetch with SSE framing through `eventsource-parser`, while `dsh-llm-pi-ai` provides a generic multi-provider adapter through `@earendil-works/pi-ai`. Both carry cancellation and the idle watchdog to the provider request.
+This contract is pinned down by two deliberately independent implementations: `dsh-llm-deepseek` (direct fetch, SSE framing via `eventsource-parser`) and `dsh-llm-pi-ai` (a generic multi-provider adapter through `@earendil-works/pi-ai`). The library-backed adapter exercises the finish-chunk error path, while transport-boundary tests prove each idle watchdog stops its actual request.
 
 ## `ResolvedRetryPolicy`
 
@@ -142,9 +213,8 @@ declare class BlockAssembler {
   push(chunk: StreamChunk): void;
   /**
    * Assemble all blocks seen so far, in stream order.
-   * @returns one block per seen index, except that max-token truncation drops
-   *   tool calls that cannot be executed safely; an open block assembles from
-   *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
+   * @returns one block per seen index; an open block assembles from its
+   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
    */
   blocks(): ContentBlock[];
   /** Usage from the `usage` chunk; undefined until one arrives. */
@@ -162,6 +232,263 @@ declare class BlockAssembler {
 }
 ```
 
+<a id="the-model-request-and-result"></a>
+
+## The model request
+
+One model call is a fully-assembled `GenerateOptions`. The adapter answers with a raw [`StreamChunk`](#streamchunk--the-raw-protocol) stream; the consumer assembles it with [`BlockAssembler`](#blockassembler).
+
+Source: [`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+Provider and model discovery uses small provider-neutral descriptors. A model catalog is advisory: routing still keys on a registered provider, and an adapter may accept unlisted model ids.
+
+Registering an adapter returns a handle: the disposer, plus the atomic route replacement a plugin whose route set is user-configurable needs.
+
+```ts type-equiv
+/**
+ * What {@link LlmService.registerAdapter} returns: the disposer, plus an
+ * atomic route replacement for the same adapter instance.
+ */
+interface AdapterRegistrationHandle {
+  /** Release every route this registration currently holds. */
+  (): void
+  /**
+   * Replace this registration's routes with `providers`, keeping the same
+   * adapter instance. The candidate set is validated in full first — a
+   * conflict with another adapter, an invalid name, or bad provider metadata
+   * throws and leaves the current routes untouched — and the swap itself is
+   * one synchronous section, so no request can observe a gap. An empty array
+   * is legal here (a settings section that emptied holds zero routes while
+   * staying registered), unlike an empty initial registration.
+   *
+   * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
+   * has been released: its routes are gone and its disposer has already run,
+   * so anything registered afterwards would have no owner left to release it.
+   * @param providers - the complete next route set for this registration.
+   */
+  replace(providers: string[]): void
+}
+```
+
+```ts type-equiv
+/** Display metadata for one registered provider route. */
+interface LlmProviderInfo {
+  /** Provider route key used by {@link GenerateOptions.provider}. */
+  id: string
+  /** Human-readable provider name for selectors and diagnostics. */
+  name: string
+}
+```
+
+Adapter plugins additionally declare which routes *could* run through `registerConfigurableProviders()`, addressing each one's user-settings section, so configuration surfaces can offer dormant providers before any route registers.
+
+```ts type-equiv
+/**
+ * One provider route an adapter plugin can activate through configuration,
+ * whether or not the route is currently registered. Configuration surfaces
+ * merge this directory with `listProviders()` to offer every configurable
+ * provider alongside its live/dormant state.
+ */
+interface LlmConfigurableProvider {
+  /** Provider route key this entry activates when configured. */
+  provider: string
+  /** Human-readable provider name for configuration surfaces. */
+  displayName: string
+  /** User-settings namespace whose section configures this provider. */
+  settingsNs: string
+  /**
+   * Path from that namespace's section root to this provider's profile
+   * object; empty when the whole section is the profile.
+   */
+  settingsPath: readonly string[]
+}
+```
+
+```ts type-equiv
+/** One adapter-discovered model; catalog membership is advisory, not request validation. */
+interface LlmModelInfo {
+  /** Provider route that owns this model entry. */
+  provider: string
+  /** Model id passed to {@link GenerateOptions.model}. */
+  id: string
+  /** Human-readable model name for selectors. */
+  name: string
+  /** Optional user-facing distinction from otherwise similar models. */
+  description?: string
+}
+```
+
+Correctness-sensitive metadata is resolved separately from the advisory catalog and is owned by the adapter serving the exact route. Context capacity, adapter call defaults, and reasoning choices share one exact-model result so consumers do not repeat authoritative model resolution.
+
+```ts type-equiv
+/** Provider-owned context capacity for one exact provider/model route. */
+interface LlmModelContext {
+  /** Maximum combined request and response context in tokens. */
+  contextWindow: number
+}
+```
+
+Reasoning effort is another exact-route capability. The core brands identifiers but does not enumerate their values; each adapter owns the ordered set, display names, and optional deployment default.
+
+```ts type-equiv
+/** Adapter-owned identifier for one model's selectable reasoning effort. */
+type ReasoningEffortId = Branded<'ReasoningEffortId'>
+```
+
+```ts type-equiv
+/** Display metadata for one adapter-owned reasoning effort. */
+interface LlmReasoningEffortInfo {
+  /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
+  id: ReasoningEffortId
+  /** Human-readable effort name for selectors and diagnostics. */
+  name: string
+  /** Optional user-facing distinction from otherwise similar efforts. */
+  description?: string
+}
+```
+
+```ts type-equiv
+/** Selectable reasoning efforts for one exact provider/model route. */
+interface LlmModelReasoningInfo {
+  /** Supported efforts in adapter-preferred display order. */
+  efforts: readonly LlmReasoningEffortInfo[]
+  /**
+   * Adapter-configured default materialized into requests when callers omit
+   * an effort. Absence preserves the provider's own default.
+   */
+  defaultEffort?: ReasoningEffortId
+}
+```
+
+```ts type-equiv
+/** Exact-route model metadata resolved by its owning adapter. */
+interface LlmResolvedModelInfo extends LlmModelInfo {
+  /** Provider-owned context capacity when known. */
+  context?: LlmModelContext
+  /** Adapter-configured per-request output cap materialized when callers omit one. */
+  defaultMaxTokens?: number
+  /** Adapter-owned selectable reasoning levels when exposed. */
+  reasoning?: LlmModelReasoningInfo
+}
+```
+
+```ts type-equiv
+/** A single model request, fully assembled. */
+interface GenerateOptions {
+  /** Registered provider route selecting the adapter instance. */
+  provider: string
+  model: string
+  /** Adapter-owned reasoning effort selected for this exact model. */
+  reasoningEffort?: ReasoningEffortId
+  /**
+   * Ordered conversation messages, exactly as the provider sees them (after
+   * the `system` slot). A loop-built request assembles them as
+   * the derived history (dsh-agent-loop); a hand-built one-shot passes any list.
+   */
+  messages: Message[]
+  /** System prompt text (adapters map to the provider's system slot). */
+  system?: string
+  /** Tool schemas (adapters map to the provider's `tools` field). */
+  tools?: ToolSchema[]
+  temperature?: number
+  maxTokens?: number
+  /**
+   * Stop sequences: generation halts as soon as the model produces any one of
+   * these strings (adapters map to the provider's stop field, e.g. OpenAI
+   * `stop`). The stop string itself is not included in the output.
+   */
+  stop?: string[]
+  signal?: AbortSignal
+  /**
+   * Session identity stamped by the loop for listener routing. Adapters ignore
+   * it; replay uses it to keep concurrent parent and child cursors independent.
+   */
+  sessionId?: Branded<'SessionId'>
+  /**
+   * Provider-neutral classification for an auxiliary model call. Adapters may
+   * map the purpose to model-hidden transport metadata or purpose-specific
+   * generation policy. Ordinary conversation requests leave it unset.
+   */
+  purpose?: 'compaction' | 'session-title'
+}
+```
+
+Why a model response stopped is a merge-extensible reason. Terminal provider failures carry the streaming contract's [`LlmFailure`](#llmfailure):
+
+```ts type-equiv
+/**
+ * Why a model response stopped.
+ * Merge-extensible so adapters can surface provider-specific reasons.
+ */
+interface FinishReasonMap {
+  'stop': { kind: 'stop' }
+  'tool-calls': { kind: 'tool-calls' }
+  'max-tokens': { kind: 'max-tokens' }
+  'aborted': { kind: 'aborted'; failure: LlmFailure }
+  'error': { kind: 'error'; failure: LlmFailure }
+}
+```
+
+`FinishReason = FinishReasonMap[keyof FinishReasonMap]`. `TokenUsage` (per-call accounting with disjoint cache fields) is detailed [below](#tokenusage).
+
+`GenerateOptions.tools` carries `ToolSchema` — the JSON-schema description of a tool, as sent to the model. It is declared in dsh-llm (not dsh-tools) precisely because it is part of the request the loop assembles every step:
+
+```ts type-equiv
+/**
+ * JSON-schema description of a tool, as sent to the model.
+ *
+ * Declared here (not in dsh-tools) because it is part of {@link GenerateOptions};
+ * dsh-tools' ToolDefinition and dsh-system-prompt's PromptAssembly both import
+ * it from this package.
+ */
+interface ToolSchema {
+  name: string
+  description: string
+  /** JSON Schema object for the arguments. */
+  parameters: Record<string, unknown>
+}
+```
+
+The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` that produces it (schema + `execute`) is on [tools.md](tools.md).
+
+### The request envelope: `LlmCallConfig` and the logged header
+
+The loop builds each request from logged state. `EpochHeader` records call config, adapter-default provenance, rendered prompt, and authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
+
+`agent/request` receives a frozen call-config seed and may return a replacement to switch provider, model, reasoning effort, or sampling. Before the waterfall, the loop removes values marked as adapter defaults so exact-model preparation materializes the selected route's current values; unmarked explicit settings remain in the proposal. After the waterfall, preparation rejects unsupported explicit effort ids without clamping and logs the effective config plus provenance under the turn signal. The prepared call keeps one adapter registration through dispatch. Requests reaching `llm/stream` are deep-frozen, so mutation throws, and carry a process-local loop identity so observers do not confuse separately logged frozen auxiliary calls with conversation requests.
+
+On the wire, a loop-built request reads the `system` slot (the rendered prompt assembly) followed by the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps. The dev invariant recomputes exactly this equation against every loop-built request.
+
+FIXME(call-config-shape): revisit which remaining fields are genuinely epoch-level for cache purposes (`model` and the model-owned reasoning effort are explicit; the sampling scalars sit here out of caution).
+
+```ts type-equiv
+/**
+ * Provider, model, reasoning effort, and sampling scalars of one conversation's
+ * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
+ * the loop builds requests from the logged header rather than accepting these
+ * per call.
+ */
+interface LlmCallConfig {
+  provider: string
+  model: string
+  reasoningEffort?: ReasoningEffortId
+  temperature?: number
+  maxTokens?: number
+  stop?: string[]
+}
+```
+
+```ts type-equiv
+/**
+ * Effective config fields supplied by exact-model adapter resolution rather
+ * than by the caller's request proposal.
+ */
+interface LlmCallConfigAdapterDefaults {
+  reasoningEffort?: true
+  maxTokens?: true
+}
+```
+
 ## The seam
 
 `LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmService.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#content-blocks-and-streaming-dsh-llm).
@@ -171,8 +498,6 @@ declare class BlockAssembler {
 interface PreparedLlmCall {
   /** Detached, deep-frozen config with any adapter-owned default materialized. */
   readonly config: LlmCallConfig
-  /** Immutable retry policy captured with the adapter registration. */
-  readonly retryPolicy: ResolvedRetryPolicy
   /** Detached context metadata resolved with the registration-bound call. */
   readonly context?: LlmModelContext
   /** Config fields materialized by the captured adapter rather than proposed by the caller. */
@@ -239,22 +564,7 @@ declare abstract class LlmAdapter {
 }
 ```
 
-`ContentBlockType` (the key set the `index`-correlated blocks carry) derives from `ContentBlockMap`:
-
-```ts type-equiv
-/**
- * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support.
- */
-interface ContentBlockMap {
-  'text': TextBlock
-  'reasoning': ReasoningBlock
-  'tool-call': ToolCallBlock
-  'tool-result': ToolResultBlock
-}
-```
-
-See [core.md § Content blocks and messages](core.md#content-blocks-and-messages) for the block interfaces.
+`ContentBlockType` (the key set the `index`-correlated blocks carry) derives from [`ContentBlockMap`](#content-blocks-and-messages) above.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -293,9 +603,9 @@ listProviders(): LlmProviderInfo[]
  * entry, or a provider already declared by any registration throws
  * `LlmError` without registering the rest. Disposed with the fiber.
  * @param entries - every configurable provider this plugin owns.
- * @returns a handle that withdraws all of them, and can atomically replace them.
+ * @returns the disposer that withdraws all of them.
  */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () => void
 
 /**
  * List every declared configurable provider, registered or dormant.
@@ -303,29 +613,6 @@ registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): Dire
  */
 listConfigurableProviders(): LlmConfigurableProvider[]
 
-/**
- * Offer to interrogate provider endpoints on behalf of the settings
- * namespace this plugin owns. The namespace is the key because that is what
- * a configuration surface already holds from the configurable-provider
- * directory, and because a provider being *added* has no route to name yet.
- * Disposed with the fiber.
- * @param settingsNs - the namespace whose profiles this discovery serves.
- * @param discover - interrogates one endpoint; must honor `request.signal`.
- * @returns the disposer that withdraws the offer.
- */
-registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
-
-/**
- * Interrogate one provider endpoint for the models it advertises. The
- * request describes a draft, not a stored route, so nothing here reads or
- * writes settings or credentials — the caller owns both, and the reply is
- * candidate metadata a surface may offer for adoption.
- * @param settingsNs - namespace whose registered discovery serves this draft.
- * @param request - the endpoint, protocol, and one-shot credential to use.
- * @returns the advertised models, deduplicated in endpoint order.
- */
-async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
-
 /**
  * Resolve the retry policy captured when one provider route was registered.
  * @param provider - registered provider route to inspect.
@@ -375,22 +662,22 @@ async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<Ll
 async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
 
 /**
- * Stream one model call as raw chunks (token-level deltas). Replay state is
- * retained only when the same adapter instance owns its historical provider
- * and the target provider. Final adapter selection remains fixed through
- * asynchronous exact-model resolution and dispatch. Adapter selection,
- * dispatch, and iteration failures become terminal `error` or `aborted`
- * finish chunks; middleware, nested-call, cleanup, and consumer failures
- * remain thrown.
+ * Stream one model call as raw chunks (token-level deltas). Throws
+ * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
+ * `options.provider`. Replay state is retained only when the same adapter
+ * instance owns its historical provider and the target provider. Final
+ * adapter selection remains fixed through asynchronous exact-model resolution
+ * and dispatch. Selection, dispatch, and iteration failures retain their
+ * original Error identity and are tagged in a call-local scope for narrow
+ * agent-loop request recovery; middleware and nested-call failures remain
+ * untagged for the outer call.
  * @param options - the full request; `options.provider` selects the adapter.
  * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
  */
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Types: [AdapterRegistrationHandle](core.md) · [DirectoryRegistrationHandle](core.md) · [GenerateOptions](core.md) · [LlmCallConfig](core.md) · [LlmConfigurableProvider](core.md) · [LlmDiscoveredModel](core.md) · [LlmModelDiscoveryRequest](core.md) · [LlmModelInfo](core.md) · [LlmProviderInfo](core.md) · [LlmResolvedModelInfo](core.md)
-
-Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:232`](../../packages/llm/llm/src/index.ts)
 
 <a id="llm-events"></a>
 
@@ -415,7 +702,7 @@ The provider topology changed: an adapter registered or unregistered routes, or
 'llm/adapters-updated'(): void
 ```
 
-Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:71`](../../packages/llm/llm/src/index.ts)
 
 <a id="llmstream--waterfall"></a>
 
@@ -439,7 +726,5 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Types: [GenerateOptions](core.md)
-
-Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:60`](../../packages/llm/llm/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index a10b696ec0..bb31c14b9b 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -2,10 +2,84 @@
 
 [English](llm-streaming.md) | 中文
 
-[dsh-llm](../../packages/llm/llm) 的协议格式（wire format）级流式输出词汇。[core.md](core.md) 介绍了 `StreamChunk`、`Message` 与 `ContentBlock`；本页拥有完整的分片协议、每个适配器必须遵守的适配器契约（adapter contract），以及共享的 assembler。
+[`packages/llm`](../../packages/llm/README.md) 的对话与流式输出词汇：每个请求与持久历史共享的 `Message`/`ContentBlock` 形状、完整组装的模型请求、原始 `StreamChunk` 协议、每个适配器必须遵守的适配器契约（adapter contract），以及共享的 assembler。[核心主干](core.md)在每个轮次持有并记录这些值；本页声明它们。
 
 源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 
+<a id="content-blocks-and-messages"></a>
+
+## 内容块与消息
+
+一段对话由 `Message` 组成；一条消息是一个类型化**内容块**的数组。块的联合类型从 `ContentBlockMap` 派生。
+
+源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+```ts type-equiv
+/**
+ * Merge-extensible content blocks keyed by `type`. New core blocks must land
+ * with adapter, UI, and compaction support.
+ */
+interface ContentBlockMap {
+  'text': TextBlock
+  'reasoning': ReasoningBlock
+  'tool-call': ToolCallBlock
+  'tool-result': ToolResultBlock
+}
+```
+
+各块接口（完整字段见源码）：`TextBlock`（`text`）、`ReasoningBlock`（thinking，区别于可见文本）、`ToolCallBlock`（`id: CallId`、`name`、原始 JSON `arguments`）、`ToolResultBlock`（`toolCallId`、嵌套 `content: ContentBlock[]`、`isError?`）。`ContentBlock = ContentBlockMap[ContentBlockType]`。核心集仅限于每条交付路径都尊重的块——多模态内容（图像、音频等）没有核心块类型；需要的功能通过可合并扩展的 map 添加，同时提供适配器/UI/压缩支持。
+
+源码：[`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
+
+`Message` 是一个带标识且不可变的角色／来源／内容值。模型产生的 assistant 消息会在其来源中携带提供方／模型所有权与可选的适配器私有回放元数据：
+
+```ts type-equiv
+/** Provider ownership and adapter-private replay data for an assistant message. */
+interface AssistantProvenance {
+  /** Provider route that produced the message. */
+  provider: string
+  /** Provider model id that produced the message. */
+  model: string
+  /**
+   * Lossless-JSON adapter state needed to replay the provider response.
+   * `LlmService` exposes it to a target adapter only when that adapter instance
+   * currently owns both this historical provider and the target provider.
+   */
+  replayState?: unknown
+}
+```
+
+```ts type-equiv
+/** One immutable message representation shared by delivery, durable history, and model requests. */
+interface Message {
+  /** Stable identity preserved across every representation boundary. */
+  readonly id: MessageId
+  /** Provider-neutral conversation role. */
+  readonly role: 'system' | 'user' | 'assistant'
+  /** Exact model-facing blocks. */
+  readonly content: ContentBlock[]
+  /** Required producer provenance. */
+  readonly source: MessageSource
+}
+```
+
+消息来源本身也是一个可合并扩展的和类型：
+
+```ts type-equiv
+/**
+ * Where a message (or injected content) came from.
+ * Merge-extensible sum type — plugins add their own `kind`s.
+ */
+interface MessageSourceMap {
+  user: { kind: 'user' }
+  plugin: { kind: 'plugin'; plugin: string }
+  model: ModelMessageSource
+  tool: ToolMessageSource
+}
+```
+
+<a id="streamchunk--the-raw-protocol"></a>
+
 ## `StreamChunk`：原始协议
 
 一个流式响应交错包含多种类型的块（文本、推理（reasoning）、多个工具调用）。`index` 将每个 delta 关联到其所属块；`block-end` 携带完整组装好的 `ContentBlock`，消费方无需自行重新组装 delta。这是一个**封闭的**可辨识联合类型：对 `type` 的 `switch` 以 `assertNever` 结尾，因此新增变体会在每个必须处理它的消费方处触发编译错误。
@@ -15,9 +89,8 @@
  * Raw streaming protocol emitted by adapters.
  * Block indexes correlate interleaved deltas, and `block-end` carries the
  * assembled block. Adapters emit usage before the terminal finish and nothing
- * afterward; tool arguments remain raw JSON strings. An adapter implementation
- * may throw, but `LlmService.stream()` normalizes that failure to a terminal
- * `error` or `aborted` finish before exposing it to consumers.
+ * afterward; tool arguments remain raw JSON strings. Failures either throw or
+ * end with `error`/`aborted`, and consumers must handle both paths.
  */
 type StreamChunk =
   | { type: 'block-start'; index: number; blockType: ContentBlockType }
@@ -34,6 +107,8 @@ type StreamChunk =
   }
 ```
 
+<a id="llmfailure"></a>
+
 ## `LlmFailure`
 
 每个抛出的失败或最终适配器的带内失败都会规范化为一种可序列化、提供方无关的 payload。`providerRetryAfterMs` 是经校验、由提供方请求的正数延迟，而不是重试决策；`ProviderRequestId` 是用于诊断的不透明品牌字符串。
@@ -65,10 +140,10 @@ interface LlmFailure {
 - **提供方停顿在传输层受到时限约束。** 两个已交付的远程适配器都暴露正数且有限的 `streamIdleTimeoutMs`，默认五分钟。watchdog 只在 iterator `next()` 尚未完成时启动，整个请求使用同一个稳定 signal，把自身到期映射为 `TIMEOUT`，并把更早发生的调用方中止保留为 `ABORTED`。
 - **上下文溢出只有一个规范 code。** 两个 DeepSeek 适配器都通过 `isContextWindowExceededError()` 对提供方的显式细节分类并暴露 `CONTEXT_WINDOW_EXCEEDED`，无论失败以抛出的 HTTP `LlmError` 还是带内 finish error 到达。消费方按 code 路由，绝不依赖提供方文本。
 - **空 completion 是可重试错误，而不是静默的成功结果。** 两个适配器都把没有携带任何内容块的终止性 `stop` 结束映射为携带规范 `EMPTY_RESPONSE` code 的 `finish {kind:'error'}`，`dsh-llm-retry` 默认会重试它；详见[空模型响应可重试](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md)。
-- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送下文的 `attributionHeaders()`，即 `User-Agent` 基线。
+- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
 - **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容与 provenance，不会收到私有状态。
 
-两个彼此独立的实现遵循该契约：`dsh-llm-deepseek` 使用直接 fetch，并通过 `eventsource-parser` 进行 SSE（Server-Sent Events）分帧；`dsh-llm-pi-ai` 则通过 `@earendil-works/pi-ai` 提供通用多提供方适配器。两者都会把取消与空闲 watchdog 传递至提供方请求。
+该契约由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
 
 ## `ResolvedRetryPolicy`
 
@@ -76,7 +151,7 @@ interface LlmFailure {
 
 ## `AppIdentity`：应用归属
 
-每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该契约有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包 manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
+每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该契约有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包（package） manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
 
 ```ts type-equiv
 /**
@@ -96,6 +171,8 @@ interface AppIdentity {
 }
 ```
 
+<a id="tokenusage"></a>
+
 ## `TokenUsage`
 
 逐调用 token 记账。各计数**互不重叠**：`inputTokens` 只包含未缓存输入；缓存输入单独报告，计费输入是三者之和。若提供方把缓存命中折入单一提示词总数（如 DeepSeek 的 `prompt_tokens`），适配器会再将其扣除。`reasoningTokens` 存在时只是信息性细节，已经包含在 `outputTokens` 中；汇总时不得重复相加。
@@ -118,6 +195,8 @@ interface TokenUsage {
 }
 ```
 
+<a id="blockassembler"></a>
+
 ## `BlockAssembler`
 
 `BlockAssembler`（[`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)）是唯一的共享实现，负责把 `StreamChunk` 流折叠回 `ContentBlock`、usage、结束原因与回放状态。循环在记录原始分片的同时，把同一批分片送入 assembler，再将组装后的 assistant 内容连同其提供方/模型 provenance 一起存储。需要组装结果、又不想重新实现 fold 的消费方使用它。
@@ -142,9 +221,8 @@ declare class BlockAssembler {
   push(chunk: StreamChunk): void;
   /**
    * Assemble all blocks seen so far, in stream order.
-   * @returns one block per seen index, except that max-token truncation drops
-   *   tool calls that cannot be executed safely; an open block assembles from
-   *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
+   * @returns one block per seen index; an open block assembles from its
+   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
    */
   blocks(): ContentBlock[];
   /** Usage from the `usage` chunk; undefined until one arrives. */
@@ -162,6 +240,263 @@ declare class BlockAssembler {
 }
 ```
 
+<a id="the-model-request-and-result"></a>
+
+## 模型请求
+
+一次模型调用是一个完全组装好的 `GenerateOptions`。适配器以原始 [`StreamChunk`](#streamchunk--the-raw-protocol) 流作答；消费方用 [`BlockAssembler`](#blockassembler) 组装它。
+
+源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
+
+提供方与模型发现使用小型、提供方无关的描述符。模型目录仅供参考：路由仍以已注册提供方为键，适配器也可以接受未列出的模型 id。
+
+注册适配器会返回一个句柄：既是释放器，也带有原子的路由替换——路由集合由用户配置决定的插件正需要它。
+
+```ts type-equiv
+/**
+ * What {@link LlmService.registerAdapter} returns: the disposer, plus an
+ * atomic route replacement for the same adapter instance.
+ */
+interface AdapterRegistrationHandle {
+  /** Release every route this registration currently holds. */
+  (): void
+  /**
+   * Replace this registration's routes with `providers`, keeping the same
+   * adapter instance. The candidate set is validated in full first — a
+   * conflict with another adapter, an invalid name, or bad provider metadata
+   * throws and leaves the current routes untouched — and the swap itself is
+   * one synchronous section, so no request can observe a gap. An empty array
+   * is legal here (a settings section that emptied holds zero routes while
+   * staying registered), unlike an empty initial registration.
+   *
+   * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
+   * has been released: its routes are gone and its disposer has already run,
+   * so anything registered afterwards would have no owner left to release it.
+   * @param providers - the complete next route set for this registration.
+   */
+  replace(providers: string[]): void
+}
+```
+
+```ts type-equiv
+/** Display metadata for one registered provider route. */
+interface LlmProviderInfo {
+  /** Provider route key used by {@link GenerateOptions.provider}. */
+  id: string
+  /** Human-readable provider name for selectors and diagnostics. */
+  name: string
+}
+```
+
+适配器插件还会通过 `registerConfigurableProviders()` 声明哪些路由*可以*运行，并指明每条路由的用户设置分节，使配置界面能在任何路由注册之前就呈现休眠的提供方。
+
+```ts type-equiv
+/**
+ * One provider route an adapter plugin can activate through configuration,
+ * whether or not the route is currently registered. Configuration surfaces
+ * merge this directory with `listProviders()` to offer every configurable
+ * provider alongside its live/dormant state.
+ */
+interface LlmConfigurableProvider {
+  /** Provider route key this entry activates when configured. */
+  provider: string
+  /** Human-readable provider name for configuration surfaces. */
+  displayName: string
+  /** User-settings namespace whose section configures this provider. */
+  settingsNs: string
+  /**
+   * Path from that namespace's section root to this provider's profile
+   * object; empty when the whole section is the profile.
+   */
+  settingsPath: readonly string[]
+}
+```
+
+```ts type-equiv
+/** One adapter-discovered model; catalog membership is advisory, not request validation. */
+interface LlmModelInfo {
+  /** Provider route that owns this model entry. */
+  provider: string
+  /** Model id passed to {@link GenerateOptions.model}. */
+  id: string
+  /** Human-readable model name for selectors. */
+  name: string
+  /** Optional user-facing distinction from otherwise similar models. */
+  description?: string
+}
+```
+
+对正确性敏感的元数据与参考目录分开解析，并归服务该确切路由的适配器所有。上下文容量、适配器调用默认值和推理选项共用同一个确切模型结果，消费方因而无需重复执行权威模型解析。
+
+```ts type-equiv
+/** Provider-owned context capacity for one exact provider/model route. */
+interface LlmModelContext {
+  /** Maximum combined request and response context in tokens. */
+  contextWindow: number
+}
+```
+
+推理强度是另一项针对确切路由的能力。核心为标识符添加品牌类型，但不枚举其值；有序集合、展示名称和可选的部署默认值均由各适配器持有。
+
+```ts type-equiv
+/** Adapter-owned identifier for one model's selectable reasoning effort. */
+type ReasoningEffortId = Branded<'ReasoningEffortId'>
+```
+
+```ts type-equiv
+/** Display metadata for one adapter-owned reasoning effort. */
+interface LlmReasoningEffortInfo {
+  /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
+  id: ReasoningEffortId
+  /** Human-readable effort name for selectors and diagnostics. */
+  name: string
+  /** Optional user-facing distinction from otherwise similar efforts. */
+  description?: string
+}
+```
+
+```ts type-equiv
+/** Selectable reasoning efforts for one exact provider/model route. */
+interface LlmModelReasoningInfo {
+  /** Supported efforts in adapter-preferred display order. */
+  efforts: readonly LlmReasoningEffortInfo[]
+  /**
+   * Adapter-configured default materialized into requests when callers omit
+   * an effort. Absence preserves the provider's own default.
+   */
+  defaultEffort?: ReasoningEffortId
+}
+```
+
+```ts type-equiv
+/** Exact-route model metadata resolved by its owning adapter. */
+interface LlmResolvedModelInfo extends LlmModelInfo {
+  /** Provider-owned context capacity when known. */
+  context?: LlmModelContext
+  /** Adapter-configured per-request output cap materialized when callers omit one. */
+  defaultMaxTokens?: number
+  /** Adapter-owned selectable reasoning levels when exposed. */
+  reasoning?: LlmModelReasoningInfo
+}
+```
+
+```ts type-equiv
+/** A single model request, fully assembled. */
+interface GenerateOptions {
+  /** Registered provider route selecting the adapter instance. */
+  provider: string
+  model: string
+  /** Adapter-owned reasoning effort selected for this exact model. */
+  reasoningEffort?: ReasoningEffortId
+  /**
+   * Ordered conversation messages, exactly as the provider sees them (after
+   * the `system` slot). A loop-built request assembles them as
+   * the derived history (dsh-agent-loop); a hand-built one-shot passes any list.
+   */
+  messages: Message[]
+  /** System prompt text (adapters map to the provider's system slot). */
+  system?: string
+  /** Tool schemas (adapters map to the provider's `tools` field). */
+  tools?: ToolSchema[]
+  temperature?: number
+  maxTokens?: number
+  /**
+   * Stop sequences: generation halts as soon as the model produces any one of
+   * these strings (adapters map to the provider's stop field, e.g. OpenAI
+   * `stop`). The stop string itself is not included in the output.
+   */
+  stop?: string[]
+  signal?: AbortSignal
+  /**
+   * Session identity stamped by the loop for listener routing. Adapters ignore
+   * it; replay uses it to keep concurrent parent and child cursors independent.
+   */
+  sessionId?: Branded<'SessionId'>
+  /**
+   * Provider-neutral classification for an auxiliary model call. Adapters may
+   * map the purpose to model-hidden transport metadata or purpose-specific
+   * generation policy. Ordinary conversation requests leave it unset.
+   */
+  purpose?: 'compaction' | 'session-title'
+}
+```
+
+模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式契约的 [`LlmFailure`](#llmfailure)：
+
+```ts type-equiv
+/**
+ * Why a model response stopped.
+ * Merge-extensible so adapters can surface provider-specific reasons.
+ */
+interface FinishReasonMap {
+  'stop': { kind: 'stop' }
+  'tool-calls': { kind: 'tool-calls' }
+  'max-tokens': { kind: 'max-tokens' }
+  'aborted': { kind: 'aborted'; failure: LlmFailure }
+  'error': { kind: 'error'; failure: LlmFailure }
+}
+```
+
+`FinishReason = FinishReasonMap[keyof FinishReasonMap]`。`TokenUsage`（逐调用计量，含不相交的缓存字段）详见[下文](#tokenusage)。
+
+`GenerateOptions.tools` 携带 `ToolSchema`——工具的 JSON Schema 描述，发送给模型。它声明在 dsh-llm（而非 dsh-tools）中，正是因为它是循环每一步组装请求的一部分：
+
+```ts type-equiv
+/**
+ * JSON-schema description of a tool, as sent to the model.
+ *
+ * Declared here (not in dsh-tools) because it is part of {@link GenerateOptions};
+ * dsh-tools' ToolDefinition and dsh-system-prompt's PromptAssembly both import
+ * it from this package.
+ */
+interface ToolSchema {
+  name: string
+  description: string
+  /** JSON Schema object for the arguments. */
+  parameters: Record<string, unknown>
+}
+```
+
+面向模型的 `ToolSchema` 是协议格式；产出它的已注册 `ToolDefinition`（schema + `execute`）在 [tools.md](tools.md) 中。
+
+### 请求信封：`LlmCallConfig` 与记录的 header
+
+循环从已记录状态构建每个请求。`EpochHeader` 通过完整的 `request/header` 快照记录调用配置、适配器默认值来源、渲染后的提示词以及权威返回工具顺序（由 `toolOrder` 配置；未配置时按字典序）。结合派生历史，请求便可由会话日志重建。见 [session.md](session.md#the-request-header-event-requestheader) 与[可重建性 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
+
+`agent/request` 接收冻结的调用配置种子，并可返回替代值以切换提供方、模型、推理强度或采样参数。waterfall 开始前，循环会移除标记为适配器默认值的值，使确切模型准备过程填入所选路由的当前值；未带标记的显式设置仍保留在提议中。waterfall 结束后，准备过程会在轮次信号控制下拒绝显式指定但不受支持的推理强度 ID（不自动调整），并记录生效配置及其来源。准备完成的调用直至分派完成始终持有同一项适配器注册。到达 `llm/stream` 的请求会被深度冻结，因此变更会抛异常；请求还携带进程本地循环标识，使观察者不会把单独记录的冻结辅助调用误认成对话请求。
+
+在协议格式上，循环构建的请求先读取 `system` 槽位（渲染后的提示词组装），再读取派生历史——边界快照，其尾部在轮次首步是最新的 `user/message`，在后续步骤是上一步的工具结果。开发不变式针对每个循环构建的请求精确重算此等式。
+
+FIXME(call-config-shape)：重新审视其余哪些字段出于缓存目的确实属于 epoch 层级（`model` 和模型持有的推理强度已明确属于；采样标量目前出于谨慎保留在此）。
+
+```ts type-equiv
+/**
+ * Provider, model, reasoning effort, and sampling scalars of one conversation's
+ * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
+ * the loop builds requests from the logged header rather than accepting these
+ * per call.
+ */
+interface LlmCallConfig {
+  provider: string
+  model: string
+  reasoningEffort?: ReasoningEffortId
+  temperature?: number
+  maxTokens?: number
+  stop?: string[]
+}
+```
+
+```ts type-equiv
+/**
+ * Effective config fields supplied by exact-model adapter resolution rather
+ * than by the caller's request proposal.
+ */
+interface LlmCallConfigAdapterDefaults {
+  reasoningEffort?: true
+  maxTokens?: true
+}
+```
+
 ## seam
 
 `LlmAdapter` 是提供方 seam：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmService.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#content-blocks-and-streaming-dsh-llm)。
@@ -171,8 +506,6 @@ declare class BlockAssembler {
 interface PreparedLlmCall {
   /** Detached, deep-frozen config with any adapter-owned default materialized. */
   readonly config: LlmCallConfig
-  /** Immutable retry policy captured with the adapter registration. */
-  readonly retryPolicy: ResolvedRetryPolicy
   /** Detached context metadata resolved with the registration-bound call. */
   readonly context?: LlmModelContext
   /** Config fields materialized by the captured adapter rather than proposed by the caller. */
@@ -239,22 +572,7 @@ declare abstract class LlmAdapter {
 }
 ```
 
-`ContentBlockType`（`index` 关联块所携带的键集合）派生自 `ContentBlockMap`：
-
-```ts type-equiv
-/**
- * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support.
- */
-interface ContentBlockMap {
-  'text': TextBlock
-  'reasoning': ReasoningBlock
-  'tool-call': ToolCallBlock
-  'tool-result': ToolResultBlock
-}
-```
-
-块接口详见 [core.md § Content blocks and messages](core.md#content-blocks-and-messages)。
+`ContentBlockType`（带 `index` 关联的块所携带的键集合）从上文的 [`ContentBlockMap`](#content-blocks-and-messages) 派生。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -293,9 +611,9 @@ listProviders(): LlmProviderInfo[]
  * entry, or a provider already declared by any registration throws
  * `LlmError` without registering the rest. Disposed with the fiber.
  * @param entries - every configurable provider this plugin owns.
- * @returns a handle that withdraws all of them, and can atomically replace them.
+ * @returns the disposer that withdraws all of them.
  */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () => void
 
 /**
  * List every declared configurable provider, registered or dormant.
@@ -303,29 +621,6 @@ registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): Dire
  */
 listConfigurableProviders(): LlmConfigurableProvider[]
 
-/**
- * Offer to interrogate provider endpoints on behalf of the settings
- * namespace this plugin owns. The namespace is the key because that is what
- * a configuration surface already holds from the configurable-provider
- * directory, and because a provider being *added* has no route to name yet.
- * Disposed with the fiber.
- * @param settingsNs - the namespace whose profiles this discovery serves.
- * @param discover - interrogates one endpoint; must honor `request.signal`.
- * @returns the disposer that withdraws the offer.
- */
-registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
-
-/**
- * Interrogate one provider endpoint for the models it advertises. The
- * request describes a draft, not a stored route, so nothing here reads or
- * writes settings or credentials — the caller owns both, and the reply is
- * candidate metadata a surface may offer for adoption.
- * @param settingsNs - namespace whose registered discovery serves this draft.
- * @param request - the endpoint, protocol, and one-shot credential to use.
- * @returns the advertised models, deduplicated in endpoint order.
- */
-async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
-
 /**
  * Resolve the retry policy captured when one provider route was registered.
  * @param provider - registered provider route to inspect.
@@ -375,22 +670,22 @@ async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<Ll
 async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
 
 /**
- * Stream one model call as raw chunks (token-level deltas). Replay state is
- * retained only when the same adapter instance owns its historical provider
- * and the target provider. Final adapter selection remains fixed through
- * asynchronous exact-model resolution and dispatch. Adapter selection,
- * dispatch, and iteration failures become terminal `error` or `aborted`
- * finish chunks; middleware, nested-call, cleanup, and consumer failures
- * remain thrown.
+ * Stream one model call as raw chunks (token-level deltas). Throws
+ * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
+ * `options.provider`. Replay state is retained only when the same adapter
+ * instance owns its historical provider and the target provider. Final
+ * adapter selection remains fixed through asynchronous exact-model resolution
+ * and dispatch. Selection, dispatch, and iteration failures retain their
+ * original Error identity and are tagged in a call-local scope for narrow
+ * agent-loop request recovery; middleware and nested-call failures remain
+ * untagged for the outer call.
  * @param options - the full request; `options.provider` selects the adapter.
  * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
  */
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Types: [AdapterRegistrationHandle](core.md) · [DirectoryRegistrationHandle](core.md) · [GenerateOptions](core.md) · [LlmCallConfig](core.md) · [LlmConfigurableProvider](core.md) · [LlmDiscoveredModel](core.md) · [LlmModelDiscoveryRequest](core.md) · [LlmModelInfo](core.md) · [LlmProviderInfo](core.md) · [LlmResolvedModelInfo](core.md)
-
-Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:232`](../../packages/llm/llm/src/index.ts)
 
 <a id="llm-events"></a>
 
@@ -415,7 +710,7 @@ The provider topology changed: an adapter registered or unregistered routes, or
 'llm/adapters-updated'(): void
 ```
 
-Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:71`](../../packages/llm/llm/src/index.ts)
 
 <a id="llmstream--waterfall"></a>
 
@@ -439,7 +734,5 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Types: [GenerateOptions](core.md)
-
-Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:60`](../../packages/llm/llm/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-reference.i18n.yaml b/docs/subsystems/session-reference.i18n.yaml
index 980c1a1a2d..c1466bdcfc 100644
--- a/docs/subsystems/session-reference.i18n.yaml
+++ b/docs/subsystems/session-reference.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 docs/subsystems/session-reference.md
-session-reference.md: 60e29c56ea372e100009b94caedea5327308432a
-session-reference.zh.md: 3ae9264abc15848646e5397dfcbeff764c038918
+session-reference.md: f539a59b8d26182aff9746b6d6a39a86ba15cb45
+session-reference.zh.md: 82b6a6c5ec5c91372fc6a43b73ad1572fccf5b3a
diff --git a/docs/subsystems/session-reference.md b/docs/subsystems/session-reference.md
index 60e29c56ea..f539a59b8d 100644
--- a/docs/subsystems/session-reference.md
+++ b/docs/subsystems/session-reference.md
@@ -102,7 +102,7 @@ async listCandidates( agent: Agent, query: string = '', limit: number = this.con
 async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
 ```
 
-Types: [Agent](core.md) · [ContentBlock](core.md)
+Types: [Agent](core.md) · [ContentBlock](llm-streaming.md)
 
 Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-reference.zh.md b/docs/subsystems/session-reference.zh.md
index 3ae9264abc..82b6a6c5ec 100644
--- a/docs/subsystems/session-reference.zh.md
+++ b/docs/subsystems/session-reference.zh.md
@@ -102,7 +102,7 @@ async listCandidates( agent: Agent, query: string = '', limit: number = this.con
 async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
 ```
 
-Types: [Agent](core.md) · [ContentBlock](core.md)
+Types: [Agent](core.md) · [ContentBlock](llm-streaming.md)
 
 Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index e6ead80f87..a58335b9f1 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: cbf9043b36a5cb2ab37bb99c6dbbf5a18d1e0288
-subagent.zh.md: ffd8fefd8b9d128c21e1b91ee0ba1fb706638fa9
+subagent.md: c132c073459642b133e0d7e662ee98a8c9dfb694
+subagent.zh.md: e46f9aa98389842918ae37dda1477ef1b565e774
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index cbf9043b36..c132c07345 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -611,7 +611,7 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Types: [Agent](core.md) · [ContentBlock](core.md) · [MessageId](core.md) · [SessionId](core.md)
+Types: [Agent](core.md) · [ContentBlock](llm-streaming.md) · [MessageId](llm-streaming.md) · [SessionId](core.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
 
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index ffd8fefd8b..e46f9aa983 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -613,7 +613,7 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Types: [Agent](core.md) · [ContentBlock](core.md) · [MessageId](core.md) · [SessionId](core.md)
+Types: [Agent](core.md) · [ContentBlock](llm-streaming.md) · [MessageId](llm-streaming.md) · [SessionId](core.md)
 
 Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts)
 
diff --git a/docs/subsystems/token-meter.i18n.yaml b/docs/subsystems/token-meter.i18n.yaml
index e348aca7a0..17bbb937cc 100644
--- a/docs/subsystems/token-meter.i18n.yaml
+++ b/docs/subsystems/token-meter.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 docs/subsystems/token-meter.md
-token-meter.md: 0f53955b3e6afce84520314f4de453edaa897158
-token-meter.zh.md: 3ba22c54d599982d3f7bdbcb9160b6ffc3255e07
+token-meter.md: 8a01980191bf29b1fbc0f8b1d0b33d1fb149319c
+token-meter.zh.md: 7411ce26cb75697607a706469d7923d46ff3f421
diff --git a/docs/subsystems/token-meter.md b/docs/subsystems/token-meter.md
index 0f53955b3e..8a01980191 100644
--- a/docs/subsystems/token-meter.md
+++ b/docs/subsystems/token-meter.md
@@ -84,7 +84,7 @@ measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
 estimateMessage(message: Message): number
 ```
 
-Types: [EpochHeader](session.md) · [Message](core.md) · [Session](session.md)
+Types: [EpochHeader](session.md) · [Message](llm-streaming.md) · [Session](session.md)
 
 Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/token-meter.zh.md b/docs/subsystems/token-meter.zh.md
index 3ba22c54d5..7411ce26cb 100644
--- a/docs/subsystems/token-meter.zh.md
+++ b/docs/subsystems/token-meter.zh.md
@@ -84,7 +84,7 @@ measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
 estimateMessage(message: Message): number
 ```
 
-Types: [EpochHeader](session.md) · [Message](core.md) · [Session](session.md)
+Types: [EpochHeader](session.md) · [Message](llm-streaming.md) · [Session](session.md)
 
 Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 8b0aa47c9a..003e175399 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: 5d72bd54f0dc5995218087030f24c467c8ccbb38
-tools.zh.md: 2340d4c2d92c51aa9cc89f4694b626c76d05140b
+tools.md: b63014d1c2058c8fc7e96817d4bca858a1954482
+tools.zh.md: 2dc5802efce25a732a60c660191cd584ede623bb
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index 5d72bd54f0..b63014d1c2 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -596,7 +596,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri
 'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
 ```
 
-Types: [ContentBlock](core.md) · [Scoped](scope.md)
+Types: [ContentBlock](llm-streaming.md) · [Scoped](scope.md)
 
 Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
 
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index 2340d4c2d9..2dc5802efc 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -596,7 +596,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri
 'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
 ```
 
-Types: [ContentBlock](core.md) · [Scoped](scope.md)
+Types: [ContentBlock](llm-streaming.md) · [Scoped](scope.md)
 
 Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
 
diff --git a/packages/acp/README.i18n.yaml b/packages/acp/README.i18n.yaml
index ca4ec66f67..cd4555752b 100644
--- a/packages/acp/README.i18n.yaml
+++ b/packages/acp/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/acp/README.md
-README.md: 3ba247598f29f2244456061fe7f9a3282086148f
-README.zh.md: c13bc05b12fff2ef97b4d547936aa14a6556430a
+README.md: 97af6d164b265bf0e98e3c9f5a444cffad4face5
+README.zh.md: 266b108c108b9f543d93cbb727ddbc01ab4bef36
diff --git a/packages/acp/README.md b/packages/acp/README.md
index 3ba247598f..97af6d164b 100644
--- a/packages/acp/README.md
+++ b/packages/acp/README.md
@@ -2,10 +2,10 @@
 
 English | [中文](README.zh.md)
 
-The ACP group exposes harness agents to programmatic clients. It is an interoperability transport, not a presentation or human-interaction layer.
+The ACP group exposes harness agents to programmatic clients over the Agent Client Protocol. It is an interoperability transport, not a presentation or human-interaction layer; the matching out-of-process subagent *client* lives in [`subagent/subagent-acp`](../subagent/subagent-acp/README.md) because it implements the subagent provider interface.
 
 | Package | Role |
 |---|---|
 | [`acp/`](acp/README.md) | Automation-only ACP server. |
 
-The matching out-of-process subagent client remains in [`subagent/subagent-acp`](../subagent/subagent-acp/README.md) because it implements the subagent provider interface; arbitrary ACP clients may drive the same server contract.
+The server contract is documented in [`acp/README.md`](acp/README.md).
diff --git a/packages/acp/README.zh.md b/packages/acp/README.zh.md
index c13bc05b12..266b108c10 100644
--- a/packages/acp/README.zh.md
+++ b/packages/acp/README.zh.md
@@ -2,10 +2,10 @@
 
 [English](README.md) | 中文
 
-ACP（Agent Client Protocol）组将 harness 中的 agent（智能体）公开给程序化客户端。它是互操作传输层，而非展示层或人机交互层。
+ACP 组通过 Agent Client Protocol 把 harness agent 暴露给编程客户端。它是互操作传输层，不是展示或人机交互层；配对的进程外 subagent *客户端*在 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现的是 subagent 提供方接口。
 
 | 包 | 职责 |
 |---|---|
 | [`acp/`](acp/README.md) | 仅面向自动化的 ACP 服务器。 |
 
-与之匹配的进程外 subagent 客户端仍位于 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现 subagent 提供方接口；任意 ACP 客户端都可以按照同一服务器契约驱动该服务器。
+服务器契约见 [`acp/README.md`](acp/README.md)。
diff --git a/packages/bash/README.i18n.yaml b/packages/bash/README.i18n.yaml
index 4c4a2c6180..00321c8ab0 100644
--- a/packages/bash/README.i18n.yaml
+++ b/packages/bash/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/bash/README.md
-README.md: 601782caad24d3555a206365a3f1954d81af1cf0
-README.zh.md: 8b96c4f80ba8776bfd8bdde178178cea946ff36c
+README.md: 7395a051742af24b96842966b71297dc01853dca
+README.zh.md: 1d5825e077c46284dbd4895e285cda8f39c252a3
diff --git a/packages/bash/README.md b/packages/bash/README.md
index 601782caad..7395a05174 100644
--- a/packages/bash/README.md
+++ b/packages/bash/README.md
@@ -15,3 +15,5 @@ The capability family spans the canonical executor seam, its implementations, th
 | [`tool-pwsh/`](tool-pwsh/README.md) | Exposes PowerShell execution to the model. | (registers on `ctx.tools`) |
 
 A leaf `cordis.yml` selects one executor implementation and the model-facing tools it needs. A sandboxed composition also selects a `ctx.sandbox` provider; the [ACP example](../../examples/acp-agent/) shows one complete wiring.
+
+The subsystem reference — request/spec vocabulary, results, background processes, the service, and events — is [docs/subsystems/bash.md](../../docs/subsystems/bash.md).
diff --git a/packages/bash/README.zh.md b/packages/bash/README.zh.md
index 8b96c4f80b..1d5825e077 100644
--- a/packages/bash/README.zh.md
+++ b/packages/bash/README.zh.md
@@ -15,3 +15,5 @@
 | [`tool-pwsh/`](tool-pwsh/README.md) | 向模型公开 PowerShell 执行。 | （注册到 `ctx.tools`） |
 
 叶节点 `cordis.yml` 选择一个执行器实现和所需的面向模型工具。沙箱化组合还会选择一个 `ctx.sandbox` 提供方；[ACP（Agent Client Protocol）示例](../../examples/acp-agent/)展示一套完整接线。
+
+子系统参考——请求/spec 词汇、结果、后台进程、服务与事件——见 [docs/subsystems/bash.md](../../docs/subsystems/bash.md)。
diff --git a/packages/boot/README.i18n.yaml b/packages/boot/README.i18n.yaml
index 151e5e5c08..8f691dd089 100644
--- a/packages/boot/README.i18n.yaml
+++ b/packages/boot/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/boot/README.md
-README.md: 7727f4fbab62a930051fd3b92d04513ac9f5d218
-README.zh.md: aa9a56619ee55c3be8feb58881f77c460861b1ac
+README.md: 5e4e483b60adab0b22ddb5279f4cd8fb699b9c35
+README.zh.md: d49afa45b9fb93f6fa83944167057f0c933cd05d
diff --git a/packages/boot/README.md b/packages/boot/README.md
index 7727f4fbab..5e4e483b60 100644
--- a/packages/boot/README.md
+++ b/packages/boot/README.md
@@ -2,8 +2,10 @@
 
 English | [中文](README.zh.md)
 
-The channel-neutral boot library the app bins share. A role-complete single-package group: it belongs to no channel and no assembly — `apps/cli`, the [`scaffold/`](../scaffold/README.md) launcher, and the [`examples/`](../examples/README.md) demo bins all consume it.
+The channel-neutral boot library the app bins share: `apps/cli`, the [`scaffold/`](../scaffold/README.md) launcher, and the [`examples/`](../examples/README.md) demo bins all consume it.
 
 | Package | Role | ctx key |
 |---|---|---|
 | `app-boot/` | Shared boot glue for the app bins: `.env` loading, fail-loud Loader guards, snapshot-aware config resolution, the settle-the-tree boot sequence | (library for the bins) |
+
+The boot sequence and personal-config contract are documented in [`app-boot/README.md`](app-boot/README.md).
diff --git a/packages/boot/README.zh.md b/packages/boot/README.zh.md
index aa9a56619e..d49afa45b9 100644
--- a/packages/boot/README.zh.md
+++ b/packages/boot/README.zh.md
@@ -2,8 +2,10 @@
 
 [English](README.md) | 中文
 
-各 app bin 共享、与通道无关的启动库。一个角色完备的单包组：它不归属任何通道也不归属任何组装——`apps/cli`、[`scaffold/`](../scaffold/README.md) 启动器和 [`examples/`](../examples/README.md) 各演示 bin 都消费它。
+各 app bin 共享的、与渠道无关的启动库：`apps/cli`、[`scaffold/`](../scaffold/README.md) 启动器与 [`examples/`](../examples/README.md) demo bin 都消费它。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | `app-boot/` | app bin 的共享启动粘合层：加载 `.env`、会明确报错的 Loader 保护机制、感知快照的配置解析，以及等待整棵树停稳的启动序列 | （供各 bin 使用的库） |
+
+启动序列与个人配置契约见 [`app-boot/README.md`](app-boot/README.md)。
diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml
index e65d5246a4..2ce3e44fa7 100644
--- a/packages/client/README.i18n.yaml
+++ b/packages/client/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/client/README.md
-README.md: b6fa426fbe541e2b22d2bf5f19d4397361cf0899
-README.zh.md: 5a55bb8c2c31b5215fc73e75e1c4f3aca79add64
+README.md: 56b9363cc724515ecbd11127ea4c13aba84283df
+README.zh.md: edd378bf80b63e9ab2481ab555320ed18de85139
diff --git a/packages/client/README.md b/packages/client/README.md
index b6fa426fbe..56b9363cc7 100644
--- a/packages/client/README.md
+++ b/packages/client/README.md
@@ -38,3 +38,5 @@ The browser side of the dsh web GUI: shell boot, browser-host communication, sha
 | [`ui-models/`](ui-models/README.md) | Provides model-provider configuration and DeepSeek onboarding. |
 
 Each child reference owns its contract and detailed behavior. The [slot system standard](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md) and [web client architecture note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) own the cross-package composition and loading decisions.
+
+The subsystem reference is [client-modules.md](../../docs/subsystems/client-modules.md); the [slot system standard](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md) is the definitive slot model, and the [web client architecture note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) owns the loading chain and object layer.
diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md
index 5a55bb8c2c..edd378bf80 100644
--- a/packages/client/README.zh.md
+++ b/packages/client/README.zh.md
@@ -38,3 +38,5 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
 | [`ui-models/`](ui-models/README.md) | 提供模型提供方配置与 DeepSeek 配置引导。 |
 
 每个子文档负责自身的契约和详细行为。[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)与 [Web 客户端架构 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)负责跨包组合与加载决策。
+
+子系统参考是 [client-modules.md](../../docs/subsystems/client-modules.md)；[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)是权威 slot 模型，[web 客户端架构说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)拥有加载链与对象层。
diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml
index 3eb462d513..1f9b94c59b 100644
--- a/packages/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/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/code-runtime/README.md
-README.md: f20a287419b94b1a9dc1d8da7303fc4d3032cfd3
-README.zh.md: f5cd4c9949f2bd7a7d6d7cd078144910712a3819
+README.md: 45dd55b8609fd33b7116f6b2ea36df3b3332e419
+README.zh.md: ebf288a49f87ad01b1ec80c3843c87c91206af26
diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md
index f20a287419..45dd55b860 100644
--- a/packages/code-runtime/README.md
+++ b/packages/code-runtime/README.md
@@ -10,3 +10,5 @@ The code-execution capability seam (see [capability seams](../../.agents/notes/i
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend | registers `ctx.codeRuntime` |
 
 Backends register the seam without changing its consumer. The child READMEs own language, isolation, and execution-budget details.
+
+The subsystem reference — run requests/results, binding namespaces, the failure taxonomy — is [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md).
diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md
index f5cd4c9949..ebf288a49f 100644
--- a/packages/code-runtime/README.zh.md
+++ b/packages/code-runtime/README.zh.md
@@ -10,3 +10,5 @@
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker 线程后端 | 注册 `ctx.codeRuntime` |
 
 后端在不改变消费方的情况下注册该 seam。子 README 负责语言、隔离和执行预算细节。
+
+子系统参考——运行请求/结果、绑定命名空间、失败分类体系——见 [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md)。
diff --git a/packages/compact/README.i18n.yaml b/packages/compact/README.i18n.yaml
index 17357bea7b..bb5922ee75 100644
--- a/packages/compact/README.i18n.yaml
+++ b/packages/compact/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/compact/README.md
-README.md: 509ea2764250f42e492f787deba959a8dd9967b7
-README.zh.md: adc52690dbe9e904d8f24199cb78493dab3333a4
+README.md: 0a83b87f57e4c948ee6df9e622f17964aff00f0f
+README.zh.md: cba53ee7bb917a981a0fd4b77d833b8fb7dd2c3f
diff --git a/packages/compact/README.md b/packages/compact/README.md
index 509ea27642..0a83b87f57 100644
--- a/packages/compact/README.md
+++ b/packages/compact/README.md
@@ -12,3 +12,5 @@ A compaction capability family (see [capability seams](../../.agents/notes/imple
 | [`command-compact/`](command-compact/README.md) | Human compaction command | registers on `ctx.commands` |
 
 The backend, optional pruner, and human command compose through the seam; token measurement remains a separate LLM-family service. The [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) owns the dependency rationale.
+
+The subsystem reference — the `compact/*` events, `CompactionResult`, the service, pruning outcomes — is [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md); the seam's deliberate `dsh-session`/`dsh-llm` dependency is recorded in the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
diff --git a/packages/compact/README.zh.md b/packages/compact/README.zh.md
index adc52690db..cba53ee7bb 100644
--- a/packages/compact/README.zh.md
+++ b/packages/compact/README.zh.md
@@ -12,3 +12,5 @@
 | [`command-compact/`](command-compact/README.md) | 用户压缩命令 | 注册到 `ctx.commands` |
 
 后端、可选修剪器和用户命令通过该 seam 组合；token 测量仍是独立的 LLM（大语言模型）家族服务。[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)负责依赖关系的设计原理。
+
+子系统参考——`compact/*` 事件、`CompactionResult`、服务、剪除结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
diff --git a/packages/context/README.i18n.yaml b/packages/context/README.i18n.yaml
index f3acd7f2bf..efb18426a4 100644
--- a/packages/context/README.i18n.yaml
+++ b/packages/context/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/context/README.md
-README.md: a0b5eef51740b3aa67b9e158a00357f849b8bf57
-README.zh.md: d6ed8050f3a64f740a951883f0dc321ac08e978a
+README.md: 237f6191329f89834ec9bd9f72c0a1fd1d94651e
+README.zh.md: 7c55dd91dbf7e3fca222e4b6f6bed2769f5c253c
diff --git a/packages/context/README.md b/packages/context/README.md
index a0b5eef517..237f619132 100644
--- a/packages/context/README.md
+++ b/packages/context/README.md
@@ -12,3 +12,5 @@ Product plugins that add model-visible request context without defining a tool.
 | [`workspace-context/`](workspace-context/README.md) | Workspace-instruction context | — |
 
 The [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) explains its per-agent/session isolation and lifecycle split.
+
+Session references are documented in [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md); the [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) owns its per-agent/session isolation and lifecycle split.
diff --git a/packages/context/README.zh.md b/packages/context/README.zh.md
index d6ed8050f3..7c55dd91db 100644
--- a/packages/context/README.zh.md
+++ b/packages/context/README.zh.md
@@ -12,3 +12,5 @@
 | [`workspace-context/`](workspace-context/README.md) | workspace 指令上下文 | — |
 
 [`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)解释其逐 agent（智能体）／会话隔离和生命周期拆分。
+
+会话引用见 [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md)；[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)拥有其按 agent/会话隔离与生命周期拆分。
diff --git a/packages/core/README.i18n.yaml b/packages/core/README.i18n.yaml
index d43caa011e..aa542fe885 100644
--- a/packages/core/README.i18n.yaml
+++ b/packages/core/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/core/README.md
-README.md: d51ef73f7f545920f8cd527b2b0d597305ae86d0
-README.zh.md: 729f41fafb6b9585a66e58fe8d6ac63c1f235acc
+README.md: 40a888183a9338805d83c86bab9ae16f1c7bc04f
+README.zh.md: 496d547a173a63ac9d8d2ce0f005877dab92d358
diff --git a/packages/core/README.md b/packages/core/README.md
index d51ef73f7f..40a888183a 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -16,3 +16,5 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
 `scope` supplies the shared scoping primitive. `agent` owns the public seam, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable.
 
 Runnable compositions belong to [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md); this group owns only the swappable spine pieces.
+
+The subsystem reference — the package-by-package loop map, the `Agent` handle and its delivery/interception contracts — is [docs/subsystems/core.md](../../docs/subsystems/core.md); the default runnable composition is [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md).
diff --git a/packages/core/README.zh.md b/packages/core/README.zh.md
index 729f41fafb..496d547a17 100644
--- a/packages/core/README.zh.md
+++ b/packages/core/README.zh.md
@@ -16,3 +16,5 @@
 `scope` 提供共享作用域原语。`agent` 负责公开 seam，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。
 
 可运行组合属于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)；该分组只负责可替换的主干组件。
+
+子系统参考——逐包循环地图、`Agent` 句柄及其投递/拦截契约——见 [docs/subsystems/core.md](../../docs/subsystems/core.md)；默认可运行组合是 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)。
diff --git a/packages/credentials/README.i18n.yaml b/packages/credentials/README.i18n.yaml
index 04f14e8e75..38cbbb2968 100644
--- a/packages/credentials/README.i18n.yaml
+++ b/packages/credentials/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/credentials/README.md
-README.md: c08831c90333f8515bf86a5af717c38c50b50817
-README.zh.md: c9756c010af5d2db0fc41f3108eabdc7f1161293
+README.md: 75e3941ff6421ca7e41a71ab2bfe8b30209ce598
+README.zh.md: d7c958689fdffc82830a82b04e2a06802bc81634
diff --git a/packages/credentials/README.md b/packages/credentials/README.md
index c08831c903..75e3941ff6 100644
--- a/packages/credentials/README.md
+++ b/packages/credentials/README.md
@@ -10,3 +10,5 @@ The credential capability family separates reference resolution from its provide
 | [`credentials-local/`](credentials-local/README.md) | Environment and local-file provider | registers `ctx.credentials` |
 
 Configuration carries references, not secret values. Consumers resolve those references at their operation boundary; the child READMEs own mutation, precedence, and storage semantics.
+
+The subsystem reference — `CredentialRef`, per-operation resolution, UI-safe `CredentialInfo`, provider layers — is [docs/subsystems/credentials.md](../../docs/subsystems/credentials.md).
diff --git a/packages/credentials/README.zh.md b/packages/credentials/README.zh.md
index c9756c010a..d7c958689f 100644
--- a/packages/credentials/README.zh.md
+++ b/packages/credentials/README.zh.md
@@ -10,3 +10,5 @@
 | [`credentials-local/`](credentials-local/README.md) | 环境与本地文件提供方 | 注册 `ctx.credentials` |
 
 配置携带引用而非机密值。消费方在其操作边界解析这些引用；变更、优先级与存储语义由子级 README 负责。
+
+子系统参考——`CredentialRef`、按操作解析、对 UI 安全的 `CredentialInfo`、提供方层——见 [docs/subsystems/credentials.md](../../docs/subsystems/credentials.md)。
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index f4719447aa..b1e493f3c8 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: b15012e882b60847e1ad22edf08d1202ba64fe5b
-README.zh.md: 628f6c74894bc67559d49f7cf5d1378d0ece2382
+README.md: 162e2c75e92bc4ea6aba377c14db62e8ce83fbb9
+README.zh.md: b2929b17be6ce90051f0808c2cdf4bbf643f8f13
diff --git a/packages/fs/README.md b/packages/fs/README.md
index b15012e882..162e2c75e9 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -19,3 +19,5 @@ The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesyst
 ## No timeouts on file IO
 
 `read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+
+The subsystem reference — targets, outcomes, guards, policy events, the error taxonomy, and why file IO takes no timeout — is [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md); the sandbox fence in the [cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md).
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 628f6c7489..b2929b17be 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -19,3 +19,5 @@
 ## 文件 I/O 不设超时
 
 `read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
+
+子系统参考——目标、结果、防护、策略事件、错误分类体系，以及文件 IO 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
diff --git a/packages/goal/README.i18n.yaml b/packages/goal/README.i18n.yaml
index 4238bac3c4..d2a6bf0248 100644
--- a/packages/goal/README.i18n.yaml
+++ b/packages/goal/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/goal/README.md
-README.md: 9fc6b0c18b1862a8be08275785ea3b6185e9bdbc
-README.zh.md: 08f15bcc4e405e25d4dfd5981bbc99408833403c
+README.md: 9d307278b39ecee61df9feace9fec4235b45d794
+README.zh.md: 7217c174ba5382c53204ae3678be42375fc63db5
diff --git a/packages/goal/README.md b/packages/goal/README.md
index 9fc6b0c18b..9d307278b3 100644
--- a/packages/goal/README.md
+++ b/packages/goal/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The goal family owns durable objective state independently of the model-facing tools and continuation policy that consume it.
+Durable objective state for an agent session, owned independently of the model-facing tools and continuation policy that consume it. Goal state is part of the owning session log; consumers depend on `dsh-goal`, never on the concrete agent loop.
 
 | Package | Role | ctx key |
 |---|---|---|
@@ -11,4 +11,4 @@ The goal family owns durable objective state independently of the model-facing t
 | [`tool-goal/`](tool-goal/README.md) | Model-facing goal tools | — |
 | [`command-goal/`](command-goal/README.md) | Human-facing goal command | — |
 
-Goal state is part of the owning session log. Consumers depend on `dsh-goal`, not on the concrete agent loop; continuation behavior belongs in a separate plugin on the public agent seams.
+The subsystem reference — goal identity, lifecycle snapshots, activation, change records — is [docs/subsystems/goal.md](../../docs/subsystems/goal.md).
diff --git a/packages/goal/README.zh.md b/packages/goal/README.zh.md
index 08f15bcc4e..7217c174ba 100644
--- a/packages/goal/README.zh.md
+++ b/packages/goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-goal 家族负责持久目标状态，与消费该状态的面向模型工具和续行策略相互独立。
+agent 会话的持久目标状态，独立于消费它的模型工具与续跑策略。goal 状态是所属会话日志的一部分；消费方依赖 `dsh-goal`，绝不依赖具体 agent loop。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
@@ -11,4 +11,4 @@ goal 家族负责持久目标状态，与消费该状态的面向模型工具和
 | [`tool-goal/`](tool-goal/README.md) | 面向模型的目标工具 | 无 |
 | [`command-goal/`](command-goal/README.md) | 面向用户的目标命令 | 无 |
 
-目标状态是其所属会话日志的一部分。消费方依赖 `dsh-goal`，而不是具体的 agent loop（智能体循环）；续行行为由基于公开 agent seam 的独立插件负责。
+子系统参考——goal 标识、生命周期快照、激活、变更记录——见 [docs/subsystems/goal.md](../../docs/subsystems/goal.md)。
diff --git a/packages/guard/README.i18n.yaml b/packages/guard/README.i18n.yaml
index 8251a76ed5..b99cec734b 100644
--- a/packages/guard/README.i18n.yaml
+++ b/packages/guard/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/guard/README.md
-README.md: 5791474a2fd6aeda728d4c335c930069ade6e023
-README.zh.md: 82d779d2f1834317672b8fb03f2a4a875bb566fc
+README.md: f0a80b1f497ee5b2459bebb55f886b42d74e4323
+README.zh.md: c7747e2febcb1656925fd556743eb2dd28090e37
diff --git a/packages/guard/README.md b/packages/guard/README.md
index 5791474a2f..f0a80b1f49 100644
--- a/packages/guard/README.md
+++ b/packages/guard/README.md
@@ -8,3 +8,5 @@ Behavioral guard plugins watch the agent loop for unproductive patterns and enfo
 |---|---|---|
 | [`repeat-tool-guard/`](repeat-tool-guard/README.md) | Advisory reminders for repeated tool calls | listens on tool and agent events |
 | [`timeout-policy/`](timeout-policy/README.md) | Arms per-call tool deadlines as deployment policy | registers a `tools/execute` listener |
+
+Reminders travel as `additionalContexts` on the `tools/post-execute` decision and are appended as logged plugin-sourced `user/message` events ([tools](../../docs/subsystems/tools.md)); the timeout split across `dsh-timeout`, capability termination, and this policy layer is recorded in the [timeout-library Agent Note](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md).
diff --git a/packages/guard/README.zh.md b/packages/guard/README.zh.md
index 82d779d2f1..c7747e2feb 100644
--- a/packages/guard/README.zh.md
+++ b/packages/guard/README.zh.md
@@ -8,3 +8,5 @@
 |---|---|---|
 | [`repeat-tool-guard/`](repeat-tool-guard/README.md) | 针对重复工具调用的建议性提醒 | 监听工具和 agent 事件 |
 | [`timeout-policy/`](timeout-policy/README.md) | 以部署策略形式设置单次工具调用截止时间 | 注册 `tools/execute` 监听器 |
+
+提醒作为 `additionalContexts` 随 `tools/post-execute` 决策传递，并以插件来源的 `user/message` 事件记录（[工具](../../docs/subsystems/tools.md)）；跨 `dsh-timeout`、能力方终止与本策略层的超时拆分记录在[超时库 Agent Note](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)。
diff --git a/packages/host/README.i18n.yaml b/packages/host/README.i18n.yaml
index 1aaacd7ecb..0859a2571d 100644
--- a/packages/host/README.i18n.yaml
+++ b/packages/host/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/host/README.md
-README.md: 269a27f51c842f13bc11c175916b7be22db72bd2
-README.zh.md: 559bf785eb45d59a30f676b98c14143c69d57edd
+README.md: 926cb0b6b87a8ee76cb2dab745a31f620f4e7f5c
+README.zh.md: dc617084c756b80716f9a02bd2d22ba6954030f6
diff --git a/packages/host/README.md b/packages/host/README.md
index 269a27f51c..926cb0b6b8 100644
--- a/packages/host/README.md
+++ b/packages/host/README.md
@@ -15,3 +15,5 @@ The host side of the dsh web GUI: the API gateway every client shape shares, and
 | [`directory-picker-auto/`](directory-picker-auto/README.md) | Host-adaptive picker composition | mounts a backend |
 
 `apiproxy` remains transport-independent; [`client/connection`](../client/connection/README.md) supplies the browser/HTTP carrier. Picker implementations replace one another behind the shared seam.
+
+The subsystem references: [http-server.md](../../docs/subsystems/http-server.md) and [workspace.md](../../docs/subsystems/workspace.md) (the picker seam).
diff --git a/packages/host/README.zh.md b/packages/host/README.zh.md
index 559bf785eb..dc617084c7 100644
--- a/packages/host/README.zh.md
+++ b/packages/host/README.zh.md
@@ -15,3 +15,5 @@ dsh Web GUI 的宿主侧：所有客户端形态共享的 API 网关，以及承
 | [`directory-picker-auto/`](directory-picker-auto/README.md) | 宿主自适应选择器组合 | 挂载一个后端 |
 
 `apiproxy` 保持传输无关；[`client/connection`](../client/connection/README.md) 提供浏览器／HTTP 载体。选择器实现可在共享 seam 后互相替换。
+
+子系统参考：[http-server.md](../../docs/subsystems/http-server.md) 与 [workspace.md](../../docs/subsystems/workspace.md)（挑选 seam）。
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
index 2555e896a1..77539b60fb 100644
--- a/packages/interaction/README.i18n.yaml
+++ b/packages/interaction/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/interaction/README.md
-README.md: 506b47753fc9250f9f7bd971265421ad46a106b2
-README.zh.md: 34d336f3d3c10deab166d5c13bb86c13ee9bced0
+README.md: 31a306cb08fe69297b0d0843b57b5e491c0bbe44
+README.zh.md: 6eafe8726ba59edd3a6bf739deacc037a9b56b76
diff --git a/packages/interaction/README.md b/packages/interaction/README.md
index 506b47753f..31a306cb08 100644
--- a/packages/interaction/README.md
+++ b/packages/interaction/README.md
@@ -13,3 +13,5 @@ The seams through which a human collaborates with a running agent — questions,
 | [`tool-ask-user/`](tool-ask-user/README.md) | Exposes human questions to the model. | (registers on `ctx.tools`) |
 
 These packages integrate through existing agent and session contracts rather than changing the loop. Interactive applications provide the concrete command, approval, and question adapters; automation uses [`acp/`](../acp/README.md), and runnable demo bundles live under [`examples/`](../examples/README.md). The product [`dsh`](../../apps/cli/README.md) CLI composes these packages directly.
+
+The subsystem references: [approval.md](../../docs/subsystems/approval.md), [permission.md](../../docs/subsystems/permission.md), [user-interaction.md](../../docs/subsystems/user-interaction.md), [commands.md](../../docs/subsystems/commands.md), and [tui.md](../../docs/subsystems/tui.md). The automation-only ACP transport is [`acp/`](../acp/README.md), the SDK's JSON-RPC server half [`scaffold/server`](../scaffold/README.md), and the shared bin boot glue [`boot/`](../boot/README.md).
diff --git a/packages/interaction/README.zh.md b/packages/interaction/README.zh.md
index 34d336f3d3..6eafe8726b 100644
--- a/packages/interaction/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -13,3 +13,5 @@
 | [`tool-ask-user/`](tool-ask-user/README.md) | 向模型公开用户问题。 | （注册到 `ctx.tools`） |
 
 这些包通过现有的 agent（智能体）和会话契约集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
+
+子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)、[commands.md](../../docs/subsystems/commands.md) 与 [tui.md](../../docs/subsystems/tui.md)。仅自动化的 ACP 传输在 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半在 [`scaffold/server`](../scaffold/README.md)，共享 bin 启动胶水在 [`boot/`](../boot/README.md)。
diff --git a/packages/llm/README.i18n.yaml b/packages/llm/README.i18n.yaml
index 3c4ae19900..a35bf870d4 100644
--- a/packages/llm/README.i18n.yaml
+++ b/packages/llm/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/llm/README.md
-README.md: 92d9fbfa2b8c8db4700562009db49229b2189ab3
-README.zh.md: 5c6e7aad1db6511bdb660b86e257652128db131f
+README.md: 077ae600c89cff80cd71830e37bda00707c1d837
+README.zh.md: e2bdad7fd0b33116498b50bfa6527974fa140fc9
diff --git a/packages/llm/README.md b/packages/llm/README.md
index 92d9fbfa2b..077ae600c8 100644
--- a/packages/llm/README.md
+++ b/packages/llm/README.md
@@ -13,3 +13,5 @@ The LLM seam and its provider adapters. The interface package (`llm`) owns the a
 | [`llm-pi-ai/`](llm-pi-ai/README.md) | Multi-provider pi-ai adapter | registers on `ctx.llm` |
 
 Adapters register provider routes on the seam; retry and token measurement remain separate consumers. The child READMEs own routing, metadata, replay, and provider-wire details; the [LLM architecture decisions](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) own the rationale.
+
+The subsystem reference — messages and blocks, the model request, the `StreamChunk` protocol, the adapter contract — is [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md) (token measurement: [token-meter.md](../../docs/subsystems/token-meter.md)); see the [twin adapters](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md), [replay token meter](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md), and [routed model context](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Notes.
diff --git a/packages/llm/README.zh.md b/packages/llm/README.zh.md
index 5c6e7aad1d..e2bdad7fd0 100644
--- a/packages/llm/README.zh.md
+++ b/packages/llm/README.zh.md
@@ -13,3 +13,5 @@ LLM（大语言模型）seam 及其提供方适配器。接口包（`llm`）负
 | [`llm-pi-ai/`](llm-pi-ai/README.md) | 多提供方 pi-ai 适配器 | 注册到 `ctx.llm` |
 
 适配器在 seam 上注册提供方路由；重试与 token 测量仍是独立消费方。子 README 负责路由、元数据、回放和提供方协议细节；[LLM 架构决策](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)负责设计原理。
+
+子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器契约——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index 9919cdaba5..be1dc838ff 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: 7fbdf071735673fb0158f6fa66148be1c644a433
-README.zh.md: e059dbd80b7e38c0e447e54178162316dfd127c7
+README.md: 01c464c9993571990e0542df9fadb2848a6c9a79
+README.zh.md: fa7dddeb011bd34c1f9cbe3a9dbf746d7f163897
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index 7fbdf07173..01c464c999 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -13,3 +13,5 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
 
 See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
+
+The subsystem reference — operations, coordinates, requests/results, `LspError` — is [docs/subsystems/lsp.md](../../docs/subsystems/lsp.md); design rationale in the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md).
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index e059dbd80b..fa7dddeb01 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -13,3 +13,5 @@
 接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
 设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
+
+子系统参考——操作、坐标、请求/结果、`LspError`——见 [docs/subsystems/lsp.md](../../docs/subsystems/lsp.md)；设计依据见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)。
diff --git a/packages/plan/README.i18n.yaml b/packages/plan/README.i18n.yaml
index 3ae6755be6..4e34bac80c 100644
--- a/packages/plan/README.i18n.yaml
+++ b/packages/plan/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/plan/README.md
-README.md: 598974e105aaeaf3c35418aec0655de2a5ba6888
-README.zh.md: 0f54299af5d34555d86d82e83b92d185045e770f
+README.md: 535a2b02e297d7c3bc68538fa1d03226089372e0
+README.zh.md: f068bf37b44daa0d724fbb85ad85a4d62883e847
diff --git a/packages/plan/README.md b/packages/plan/README.md
index 598974e105..535a2b02e2 100644
--- a/packages/plan/README.md
+++ b/packages/plan/README.md
@@ -9,3 +9,5 @@ Plan mode is logged, per-agent collaboration state rather than a generic mode re
 | [`plan-mode/`](plan-mode/README.md) | Owns plan-mode state, guidance, commands, and review flow | `ctx.planMode` |
 
 The [plan-specific collaboration state](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md) decision records the family design.
+
+The subsystem reference — the `plan/mode` fold, the step-boundary flush, configuration, the exit tool — is [docs/subsystems/plan.md](../../docs/subsystems/plan.md); design in [plan-specific collaboration state](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md).
diff --git a/packages/plan/README.zh.md b/packages/plan/README.zh.md
index 0f54299af5..f068bf37b4 100644
--- a/packages/plan/README.zh.md
+++ b/packages/plan/README.zh.md
@@ -9,3 +9,5 @@ Plan mode 是按 agent（智能体）记录的协作状态，而不是通用模
 | [`plan-mode/`](plan-mode/README.md) | 负责 plan mode 状态、指引、命令和评审流程 | `ctx.planMode` |
 
 [plan 专用协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)决策记录了该家族的设计。
+
+子系统参考——`plan/mode` 折叠、步边界冲刷、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index 65d541a7c1..7f4c7f1f21 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/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/pty/README.md
-README.md: a4f743056b4a524be9623b0f700f37e0534b463f
-README.zh.md: c84ad3f1b59afcdbbd111f1b82c57c56aa24fdcf
+README.md: 2afb3cd61ef4bfba460716549d41f799e419ff46
+README.zh.md: 57a5c93047ccb970f499f02c0168db7e9f71b622
diff --git a/packages/pty/README.md b/packages/pty/README.md
index a4f743056b..2afb3cd61e 100644
--- a/packages/pty/README.md
+++ b/packages/pty/README.md
@@ -11,3 +11,5 @@ English | [中文](README.zh.md)
 | `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
 The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
+
+The subsystem reference — ids, backend/session contracts, send readiness, bounded reads — is [docs/subsystems/pty.md](../../docs/subsystems/pty.md); design and deferred boundaries in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index c84ad3f1b5..57a5c93047 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -11,3 +11,5 @@
 | `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
 设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
+
+子系统参考——id、后端/会话契约、发送就绪、有界读取——见 [docs/subsystems/pty.md](../../docs/subsystems/pty.md)；设计与延后边界见[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)。
diff --git a/packages/sandbox/README.i18n.yaml b/packages/sandbox/README.i18n.yaml
index c851d420ae..ab79d37170 100644
--- a/packages/sandbox/README.i18n.yaml
+++ b/packages/sandbox/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/sandbox/README.md
-README.md: 1ba56d22330c26302c9283b2319d983ebf902219
-README.zh.md: 5daf830854297fe14c6560dbcde8a380ad079a0e
+README.md: 61127118c895cce728ab0b4eed387f51054a83f1
+README.zh.md: 984a677aad6ab97579abf861ea8b99f149c07d08
diff --git a/packages/sandbox/README.md b/packages/sandbox/README.md
index 1ba56d2233..61127118c8 100644
--- a/packages/sandbox/README.md
+++ b/packages/sandbox/README.md
@@ -11,3 +11,5 @@ This family applies per-session confinement policy to process execution. It cove
 | [`sandbox-policy/`](sandbox-policy/README.md) | Resolves durable per-session sandbox policy | `ctx.sandboxPolicy` |
 
 See the [sandbox decision](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) for the capability boundary and the [filesystem integration decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) for cross-family policy use.
+
+The subsystem reference — modes and enforcement, per-call policy, wrapped-argv dialects, fail-closed errors — is [docs/subsystems/sandbox.md](../../docs/subsystems/sandbox.md); the boundary and the cross-family phase live in the [sandbox](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) and [cross-family fs sandbox](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) Agent Notes.
diff --git a/packages/sandbox/README.zh.md b/packages/sandbox/README.zh.md
index 5daf830854..984a677aad 100644
--- a/packages/sandbox/README.zh.md
+++ b/packages/sandbox/README.zh.md
@@ -11,3 +11,5 @@
 | [`sandbox-policy/`](sandbox-policy/README.md) | 解析持久的逐会话沙箱策略 | `ctx.sandboxPolicy` |
 
 [沙箱决策](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)记录了能力边界，[文件系统集成决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)记录了跨家族策略的使用方式。
+
+子系统参考——模式与强制执行、按调用策略、包装 argv 方言、故障关闭错误——见 [docs/subsystems/sandbox.md](../../docs/subsystems/sandbox.md)；边界与跨家族阶段见[沙箱](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)与[跨家族 fs 沙箱](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) Agent Note。
diff --git a/packages/self-modification/README.i18n.yaml b/packages/self-modification/README.i18n.yaml
index 9a6a070b95..53bbf9cdbb 100644
--- a/packages/self-modification/README.i18n.yaml
+++ b/packages/self-modification/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/self-modification/README.md
 README.md: 53f700993cce8df8729fba5a92a9498fff2412cd
-README.zh.md: 9874ead263e9860b94992cb176be3c6f8c454ece
+README.zh.md: 90030cda33f47d128041b7619546ac1309b8465a
diff --git a/packages/self-modification/README.zh.md b/packages/self-modification/README.zh.md
index 9874ead263..90030cda33 100644
--- a/packages/self-modification/README.zh.md
+++ b/packages/self-modification/README.zh.md
@@ -2,9 +2,11 @@
 
 [English](README.md) | 中文
 
-这些面向模型的工具作用于 agent（智能体）自身所在的实时 Cordis 运行时，可检查已加载的插件和服务接口、挂载模型编写的插件，并将其 dispose（资源释放）——外加受限 repository Plugin 运行时。该组也是未来自我修改类包的落点。设计说明见[工具集 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
+agent 修改自身运行时：检查已加载的插件与服务接口、挂载模型编写的插件并再次 dispose，外加受限 repository Plugin 运行时。该组是未来自我修改类包的落点。设计居所：[工具集 Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
 
 | 包（package） | 角色 | ctx 键 |
 |---|---|---|
 | [`tool-cordis/`](tool-cordis/README.md) | `cordis_inspect`／`cordis_mount`／`cordis_unmount` 工具：读取当前进程运行时，并在一个自有分组 fiber 下管理内存中的临时插件 | 注册到 `ctx.tools` |
 | [`repository-plugin/`](repository-plugin/README.md) | 通过 DSH 自有子 Plugin 准备并挂载静态 repository skills 与通用 `.mcp.json` server | 注册一个 Loader builtin |
+
+工具契约见 [`tool-cordis/README.md`](tool-cordis/README.md) 与 [`repository-plugin/README.md`](repository-plugin/README.md)。
diff --git a/packages/session-query/README.i18n.yaml b/packages/session-query/README.i18n.yaml
index 3911bf76a0..2922f4eb88 100644
--- a/packages/session-query/README.i18n.yaml
+++ b/packages/session-query/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/session-query/README.md
-README.md: a9c9f33e2dc67e837c2be728d2b1a937ce50f13d
-README.zh.md: a29dedba09271baa5836cb2d9d57c753ee41c660
+README.md: 3d5db8da74cb825c701fe50cf518505e9e6bcad9
+README.zh.md: fc430cbdc4130f77eb8857c4d88a2435ad0cc97f
diff --git a/packages/session-query/README.md b/packages/session-query/README.md
index a9c9f33e2d..3d5db8da74 100644
--- a/packages/session-query/README.md
+++ b/packages/session-query/README.md
@@ -9,3 +9,5 @@ This family provides authorized retrieval over live and durable session logs, in
 | [`session-query/`](session-query/README.md) | Defines trusted reads, relationship queries, and search operations | `ctx.sessionQuery` |
 | [`session-query-sqlite/`](session-query-sqlite/README.md) | Implements session queries with SQLite full-text search | `ctx.sessionQuery` |
 | [`tool-session-query/`](tool-session-query/README.md) | Exposes workspace-authorized session queries to the model | registers on `ctx.tools` |
+
+The subsystem reference — logical records, bounded reads, traces, filters, result pages — is [docs/subsystems/session-query.md](../../docs/subsystems/session-query.md).
diff --git a/packages/session-query/README.zh.md b/packages/session-query/README.zh.md
index a29dedba09..fc430cbdc4 100644
--- a/packages/session-query/README.zh.md
+++ b/packages/session-query/README.zh.md
@@ -9,3 +9,5 @@
 | [`session-query/`](session-query/README.md) | 定义可信读取、关系查询和搜索操作 | `ctx.sessionQuery` |
 | [`session-query-sqlite/`](session-query-sqlite/README.md) | 使用 SQLite 全文搜索实现会话查询 | `ctx.sessionQuery` |
 | [`tool-session-query/`](tool-session-query/README.md) | 向模型公开经过工作区授权的会话查询 | 注册到 `ctx.tools` |
+
+子系统参考——逻辑记录、有界读取、追踪、筛选器、结果页——见 [docs/subsystems/session-query.md](../../docs/subsystems/session-query.md)。
diff --git a/packages/session/README.i18n.yaml b/packages/session/README.i18n.yaml
index b500a64611..3829d946f0 100644
--- a/packages/session/README.i18n.yaml
+++ b/packages/session/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/session/README.md
-README.md: 45eff16ad57ec1ccc8ebdd55db82f41b5adfc111
-README.zh.md: 2d67e28ef169f4e4376b2a644a3b842e5835df04
+README.md: 586d1be0286a0de935b0b08313e6965452b85376
+README.zh.md: 60e58e6d471a48d3ced03a518e96aeeae79110e8
diff --git a/packages/session/README.md b/packages/session/README.md
index 45eff16ad5..586d1be028 100644
--- a/packages/session/README.md
+++ b/packages/session/README.md
@@ -47,3 +47,5 @@ Projects session activity into outbound telemetry and delegates delivery to a co
 |---|---|
 | [`session-telemetry/`](session-telemetry/README.md) | Defines capture, redaction, projection, and live or on-demand backend delivery. |
 | [`session-telemetry-otel/`](session-telemetry-otel/README.md) | Delivers telemetry through OpenTelemetry logs in `FULL`, `FEEDBACK_ONLY`, or `DISABLED` mode. |
+
+The subsystem references: [persistence.md](../../docs/subsystems/persistence.md), [session-projection.md](../../docs/subsystems/session-projection.md), [session-title.md](../../docs/subsystems/session-title.md), and [telemetry.md](../../docs/subsystems/telemetry.md). Only one title provider may register at a time; the demo spine mounts the fallback service and leaves both model providers out of default composition.
diff --git a/packages/session/README.zh.md b/packages/session/README.zh.md
index 2d67e28ef1..60e58e6d47 100644
--- a/packages/session/README.zh.md
+++ b/packages/session/README.zh.md
@@ -47,3 +47,5 @@
 |---|---|
 | [`session-telemetry/`](session-telemetry/README.md) | 定义捕获、脱敏、投影，以及实时或按需后端投递。 |
 | [`session-telemetry-otel/`](session-telemetry-otel/README.md) | 通过 OpenTelemetry 日志以 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 模式投递遥测。 |
+
+子系统参考：[persistence.md](../../docs/subsystems/persistence.md)、[session-projection.md](../../docs/subsystems/session-projection.md)、[session-title.md](../../docs/subsystems/session-title.md) 与 [telemetry.md](../../docs/subsystems/telemetry.md)。同一时间只允许一个标题提供方注册；demo 主干挂载回退服务，两个模型提供方都留在默认组合之外。
diff --git a/packages/settings/README.i18n.yaml b/packages/settings/README.i18n.yaml
index ec2d2124a3..146f0ad32e 100644
--- a/packages/settings/README.i18n.yaml
+++ b/packages/settings/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/settings/README.md
-README.md: 3f43647f0558abf53c373ef7d97af16c0e17d2fe
-README.zh.md: b5779bfe5da4cae148bcc6515ef13790f78bca7a
+README.md: 6f3719c58564a90fec3bd9f305cfaeb2b7bf0bf4
+README.zh.md: 0efb16dd4e5d5faa5f16814b94d55a20dc4c06c3
diff --git a/packages/settings/README.md b/packages/settings/README.md
index 3f43647f05..6f3719c585 100644
--- a/packages/settings/README.md
+++ b/packages/settings/README.md
@@ -8,3 +8,5 @@ This family resolves user-editable configuration through registered namespaces a
 |---|---|---|
 | [`settings/`](settings/README.md) | Defines namespace registration, layered resolution, and commits | `ctx.settings` |
 | [`settings-local/`](settings-local/README.md) | Stores settings in a local file and observes external edits | registers on `ctx.settings` |
+
+The subsystem reference — namespaces, owner scopes, resolution order, hot commits — is [docs/subsystems/settings.md](../../docs/subsystems/settings.md).
diff --git a/packages/settings/README.zh.md b/packages/settings/README.zh.md
index b5779bfe5d..0efb16dd4e 100644
--- a/packages/settings/README.zh.md
+++ b/packages/settings/README.zh.md
@@ -8,3 +8,5 @@
 |---|---|---|
 | [`settings/`](settings/README.md) | 定义命名空间注册、分层解析与提交 | `ctx.settings` |
 | [`settings-local/`](settings-local/README.md) | 在本地文件中存储设置并观察外部编辑 | 注册到 `ctx.settings` |
+
+子系统参考——命名空间、owner scope、解析顺序、热提交——见 [docs/subsystems/settings.md](../../docs/subsystems/settings.md)。
diff --git a/packages/skill/README.i18n.yaml b/packages/skill/README.i18n.yaml
index 74875f2aa3..758d0552f9 100644
--- a/packages/skill/README.i18n.yaml
+++ b/packages/skill/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/skill/README.md
-README.md: 533904859ad998de4f371a073fde98b68660097b
-README.zh.md: 1fad581cc61a05251f671577dcb7edab37281283
+README.md: cd606e778335249bf8ecc876d3b1a4e5feb79448
+README.zh.md: 4db7e2524596f4c62144ec7eabe7c6af63e2e270
diff --git a/packages/skill/README.md b/packages/skill/README.md
index 533904859a..cd606e7783 100644
--- a/packages/skill/README.md
+++ b/packages/skill/README.md
@@ -12,3 +12,5 @@ This family discovers reusable agent instructions and exposes them to the model
 | [`tool-skill/`](tool-skill/README.md) | Publishes the skill catalog and model-facing loader | registers on `ctx.tools` |
 
 This capability remains outside the core control spine and can use local, embedded, or remote providers without changing the model-facing contract.
+
+The subsystem reference — discovery priority, catalog snapshots, the `skill` loader — is [docs/subsystems/skills.md](../../docs/subsystems/skills.md).
diff --git a/packages/skill/README.zh.md b/packages/skill/README.zh.md
index 1fad581cc6..4db7e25245 100644
--- a/packages/skill/README.zh.md
+++ b/packages/skill/README.zh.md
@@ -12,3 +12,5 @@
 | [`tool-skill/`](tool-skill/README.md) | 发布 skill 目录和面向模型的 loader | 注册到 `ctx.tools` |
 
 该能力位于核心控制主干之外，可以使用本地、嵌入式或远程提供方，而无需更改面向模型的契约。
+
+子系统参考——发现优先级、目录快照、`skill` 加载器——见 [docs/subsystems/skills.md](../../docs/subsystems/skills.md)。
diff --git a/packages/spill/README.i18n.yaml b/packages/spill/README.i18n.yaml
index 95800ac03e..62ed26a59b 100644
--- a/packages/spill/README.i18n.yaml
+++ b/packages/spill/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/spill/README.md
-README.md: b96375b1a332cd6e3e4da9c8b1c98011aa97c8bc
-README.zh.md: c8495068edf1035937c99198dfdb5db65c9a9e59
+README.md: 74fd4837cb23767754174df168f2f4ba71c2b938
+README.zh.md: 16d677719a9c3f4245a2f446017641ff6b50ffa8
diff --git a/packages/spill/README.md b/packages/spill/README.md
index b96375b1a3..74fd4837cb 100644
--- a/packages/spill/README.md
+++ b/packages/spill/README.md
@@ -11,3 +11,5 @@ This family persists oversized tool output and replaces the inline result with a
 | [`spill-policy/`](spill-policy/README.md) | Applies the post-execution spill policy | listens on `ctx.tools` |
 
 See the [tool-output spill decision](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) for the boundary between storage, retention, and tool-owned output handling.
+
+The subsystem reference — `SaveTextSpill`, owners/sources, the branded locator — is [docs/subsystems/spill.md](../../docs/subsystems/spill.md); rationale in the [tool output spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md).
diff --git a/packages/spill/README.zh.md b/packages/spill/README.zh.md
index c8495068ed..16d677719a 100644
--- a/packages/spill/README.zh.md
+++ b/packages/spill/README.zh.md
@@ -11,3 +11,5 @@
 | [`spill-policy/`](spill-policy/README.md) | 应用执行后 spill 策略 | 监听 `ctx.tools` |
 
 参见[工具输出 spill 决策](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中记录了存储、保留和工具自有输出处理之间的边界。
+
+子系统参考——`SaveTextSpill`、owner/来源、品牌化定位符——见 [docs/subsystems/spill.md](../../docs/subsystems/spill.md)；依据见[工具输出 spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
diff --git a/packages/storage/README.i18n.yaml b/packages/storage/README.i18n.yaml
index 58fc19a4f8..ef32481991 100644
--- a/packages/storage/README.i18n.yaml
+++ b/packages/storage/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/storage/README.md
-README.md: a5f9d0204b93445699d28b1285a4a18f0408930e
-README.zh.md: 0710dfb57f96011755b253ad95a0f9d2c0923a70
+README.md: a178495fca5cc433182b8e75f20d479cb7c5bc99
+README.zh.md: 1a08f1676e5c699a55f9956a42059d1f5acf7e8d
diff --git a/packages/storage/README.md b/packages/storage/README.md
index a5f9d0204b..a178495fca 100644
--- a/packages/storage/README.md
+++ b/packages/storage/README.md
@@ -12,3 +12,5 @@ This family persists application data other than session event logs through name
 | [`storage-domain/`](storage-domain/README.md) | Provides validated domain-record storage | `ctx.storageDomain` |
 
 Consumers use a data form rather than accessing a backend directly. The [domain storage decision](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) records the family design.
+
+The subsystem reference — the backend seam, `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` — is [docs/subsystems/storage.md](../../docs/subsystems/storage.md).
diff --git a/packages/storage/README.zh.md b/packages/storage/README.zh.md
index 0710dfb57f..1a08f1676e 100644
--- a/packages/storage/README.zh.md
+++ b/packages/storage/README.zh.md
@@ -12,3 +12,5 @@
 | [`storage-domain/`](storage-domain/README.md) | 提供经过验证的领域记录存储 | `ctx.storageDomain` |
 
 消费方使用数据形式，而不是直接访问后端。[领域存储决策](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)记录了该家族的设计。
+
+子系统参考——后端 seam、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed`——见 [docs/subsystems/storage.md](../../docs/subsystems/storage.md)。
diff --git a/packages/subagent/README.i18n.yaml b/packages/subagent/README.i18n.yaml
index 11357c76d2..fe76e74a77 100644
--- a/packages/subagent/README.i18n.yaml
+++ b/packages/subagent/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/subagent/README.md
-README.md: 0a342569e66539e4987710b2e56f2946c97b1ac1
-README.zh.md: 5d2f7beef478b8bfd27b4772c7a951ea62cb10ef
+README.md: c8969ad313fc673456d2740b40d90c6d8db794ac
+README.zh.md: fb18afba5d8680408f0f37ab75056a3fb0ef660a
diff --git a/packages/subagent/README.md b/packages/subagent/README.md
index 0a342569e6..c8969ad313 100644
--- a/packages/subagent/README.md
+++ b/packages/subagent/README.md
@@ -19,3 +19,5 @@ This family lets an agent delegate work to child agents. Multiple named provider
 | [`tool-subagent-report/`](tool-subagent-report/README.md) | Provides the child-to-parent report channel | registers in child scopes |
 
 See the decisions for the [capability family](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable children](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [control tools](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
+
+The subsystem reference — start requests, results, live runs, the provider seam, continuable background children — is [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md); design rationale in the [subagent capability seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable background subagents](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [merged subagent control service](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Notes.
diff --git a/packages/subagent/README.zh.md b/packages/subagent/README.zh.md
index 5d2f7beef4..fb18afba5d 100644
--- a/packages/subagent/README.zh.md
+++ b/packages/subagent/README.zh.md
@@ -19,3 +19,5 @@
 | [`tool-subagent-report/`](tool-subagent-report/README.md) | 提供从子级到父级的报告通道 | 注册到子级作用域 |
 
 参见[能力家族](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续执行的子级](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)和[控制工具](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)决策。
+
+子系统参考——启动请求、结果、实时运行、提供方 seam、可续跑后台子 agent——见 [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md)；设计依据见 [subagent 能力 seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可续跑后台 subagent](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md) 与[合并 subagent 控制服务](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Note。
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 0ebb5bd4af..2088cbdb6b 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: f2b19436da40feb14d067e2cfc706222625680b5
-README.zh.md: 938312448dd5c0a691ed07ddc9843cf2c4445637
+README.md: 9a8628e2b6d16852895be33ae516c8b33b078502
+README.zh.md: d2c539fb1c66a914aa5f758d928fba01b5600d15
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index f2b19436da..9a8628e2b6 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -10,3 +10,5 @@ The shared process substrate for one execution world: executable lookup, fully-s
 | [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
+
+The subsystem reference — spawn specs, output readers, outcomes, the `DSH_*` environment — is [docs/subsystems/subprocess.md](../../docs/subsystems/subprocess.md); the seam decision in the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index 938312448d..d2c539fb1c 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -10,3 +10,5 @@
 | [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
 
 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
+
+子系统参考——spawn spec、输出读取器、结果、`DSH_*` 环境——见 [docs/subsystems/subprocess.md](../../docs/subsystems/subprocess.md)；seam 决定见 [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
diff --git a/packages/support/README.i18n.yaml b/packages/support/README.i18n.yaml
index 1b392a1729..824f20ae7e 100644
--- a/packages/support/README.i18n.yaml
+++ b/packages/support/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/support/README.md
-README.md: 15cb82d3d76a1241af8b40e1c8536292618409a9
-README.zh.md: ff8595b47f1a1220912dc77a072463adf74f7bf9
+README.md: bf0bba1ea7d21700a6743195ec966512c20e01bc
+README.zh.md: 47eba4d51c66914f388ba4a5925323173d5ed7e2
diff --git a/packages/support/README.md b/packages/support/README.md
index 15cb82d3d7..bf0bba1ea7 100644
--- a/packages/support/README.md
+++ b/packages/support/README.md
@@ -14,3 +14,5 @@ These packages support repository development, tests, and examples rather than p
 | [`llm-replay/`](llm-replay/README.md) | Replays recorded model responses for keyless tests and demos |
 
 A package moves out of `support/` when it gains a product contract and product consumers.
+
+The invariants contract is documented in [docs/subsystems/invariants.md](../../docs/subsystems/invariants.md).
diff --git a/packages/support/README.zh.md b/packages/support/README.zh.md
index ff8595b47f..47eba4d51c 100644
--- a/packages/support/README.zh.md
+++ b/packages/support/README.zh.md
@@ -14,3 +14,5 @@
 | [`llm-replay/`](llm-replay/README.md) | 为无密钥测试和演示回放已记录的模型响应 |
 
 当一个包获得产品契约和产品消费方时，它会移出 `support/`。
+
+不变式契约记录在 [docs/subsystems/invariants.md](../../docs/subsystems/invariants.md)。
diff --git a/packages/tasks/README.i18n.yaml b/packages/tasks/README.i18n.yaml
index 38cd47299c..d5df91be62 100644
--- a/packages/tasks/README.i18n.yaml
+++ b/packages/tasks/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/tasks/README.md
-README.md: 05ed9c439684337c45abe11f03c861a1b795b2ac
-README.zh.md: 16fe6c0a2b183b719cb6aa8ac068e34d51832a2b
+README.md: e0b6769cd1d28cc7159310a6ec6f5c8d94a81a24
+README.zh.md: d030081470a503fb52fd72dcc6f89f4c535dc38c
diff --git a/packages/tasks/README.md b/packages/tasks/README.md
index 05ed9c4396..e0b6769cd1 100644
--- a/packages/tasks/README.md
+++ b/packages/tasks/README.md
@@ -11,3 +11,5 @@ This family gives long-running tools one owner-isolated background-task protocol
 | [`tool-tasks/`](tool-tasks/README.md) | Exposes task control and completion notices to the model | registers on `ctx.tools` |
 
 See the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) decisions.
+
+The subsystem reference — the id scheme, the owner-fenced contract, snapshots — is [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md); design in the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Notes.
diff --git a/packages/tasks/README.zh.md b/packages/tasks/README.zh.md
index 16fe6c0a2b..d030081470 100644
--- a/packages/tasks/README.zh.md
+++ b/packages/tasks/README.zh.md
@@ -11,3 +11,5 @@
 | [`tool-tasks/`](tool-tasks/README.md) | 向模型公开任务控制和完成通知 | 注册到 `ctx.tools` |
 
 参见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和[任务注册表](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)决策。
+
+子系统参考——id 方案、拥有者围栏契约、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表 seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。
diff --git a/packages/todo/README.i18n.yaml b/packages/todo/README.i18n.yaml
index c75e09350a..57a1538b78 100644
--- a/packages/todo/README.i18n.yaml
+++ b/packages/todo/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/todo/README.md
-README.md: 66abf18131ee53d87e933757c40117841e94b07f
-README.zh.md: 38a6b3c22653b8e22cc0b693eb666620513a3d8c
+README.md: 6c7dccbbfb007737593550cea91444f8f735cf81
+README.zh.md: 3c1c35187b5111f1fdb607d70b980be57e3e79c1
diff --git a/packages/todo/README.md b/packages/todo/README.md
index 66abf18131..6c7dccbbfb 100644
--- a/packages/todo/README.md
+++ b/packages/todo/README.md
@@ -9,3 +9,5 @@ The model-facing todo capability. It is a single **product** package because one
 | [`tool-todo/`](tool-todo/README.md) | Stores and exposes the session's todo list. | (registers on `ctx.tools`) |
 
 The child README owns the tool, persistence, and rendering contract.
+
+The event payload is documented on [docs/subsystems/session.md](../../docs/subsystems/session.md).
diff --git a/packages/todo/README.zh.md b/packages/todo/README.zh.md
index 38a6b3c226..3c1c35187b 100644
--- a/packages/todo/README.zh.md
+++ b/packages/todo/README.zh.md
@@ -9,3 +9,5 @@
 | [`tool-todo/`](tool-todo/README.md) | 存储并公开会话的 todo 列表。 | （注册到 `ctx.tools`） |
 
 子级 README 负责工具、持久化和渲染契约。
+
+事件载荷记录在 [docs/subsystems/session.md](../../docs/subsystems/session.md)。
diff --git a/packages/web/README.i18n.yaml b/packages/web/README.i18n.yaml
index cd412d1a99..87177273da 100644
--- a/packages/web/README.i18n.yaml
+++ b/packages/web/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/web/README.md
-README.md: 65b3dde1e2f9c35c308a10ca80245064f7a0361e
-README.zh.md: 43b8b7d9c53336e984d9c61fa9b612fc1733e31f
+README.md: 811c8b3439a8962116df0e8b3ab4f6e282ecb3d2
+README.zh.md: e328447d5d026c0abc815b269179ba6c4cd9acfc
diff --git a/packages/web/README.md b/packages/web/README.md
index 65b3dde1e2..811c8b3439 100644
--- a/packages/web/README.md
+++ b/packages/web/README.md
@@ -14,3 +14,5 @@ This family provides provider-neutral web search and fetch operations plus the m
 | [`tool-web/`](tool-web/README.md) | Exposes web search and fetch to the model | registers on `ctx.tools` |
 
 The [web capability decision](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) records why search and fetch share one provider-selection service.
+
+The subsystem reference — search/fetch requests and results, availability, `WebError` — is [docs/subsystems/web.md](../../docs/subsystems/web.md); rationale (including deferred SSRF protection) in the [web capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md).
diff --git a/packages/web/README.zh.md b/packages/web/README.zh.md
index 43b8b7d9c5..e328447d5d 100644
--- a/packages/web/README.zh.md
+++ b/packages/web/README.zh.md
@@ -14,3 +14,5 @@
 | [`tool-web/`](tool-web/README.md) | 向模型公开 web 搜索和抓取 | 注册到 `ctx.tools` |
 
 [web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)记录了搜索和抓取共用一项提供方选择服务的原因。
+
+子系统参考——搜索/抓取请求与结果、可用性、`WebError`——见 [docs/subsystems/web.md](../../docs/subsystems/web.md)；依据（含延后的 SSRF 防护）见 [web 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)。
diff --git a/packages/workflow/README.i18n.yaml b/packages/workflow/README.i18n.yaml
index f02915a31d..05ad673c61 100644
--- a/packages/workflow/README.i18n.yaml
+++ b/packages/workflow/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/workflow/README.md
-README.md: 2416e26e73340a6d8624b8e77681dfc9f55fe7c5
-README.zh.md: a5c94a0a9799d78e5cca72394385b38d2fb2ba70
+README.md: 7b19cfd37f9b6870825d5e0761aed92908206b3a
+README.zh.md: 33b3f26780da1bf4efcd78242b2cfb212cef4c22
diff --git a/packages/workflow/README.md b/packages/workflow/README.md
index 2416e26e73..7b19cfd37f 100644
--- a/packages/workflow/README.md
+++ b/packages/workflow/README.md
@@ -12,3 +12,5 @@ This family runs model-authored orchestration workflows over subagents and expos
 | [`tool-ralph/`](tool-ralph/README.md) | Exposes the fixed fresh-agent Ralph workflow | registers on `ctx.tools` |
 
 Worker threads isolate workflow execution from the host event loop but are not a security boundary. See the [dynamic-workflow](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) and [Ralph tool](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) decisions.
+
+The subsystem reference — start requests, `WorkflowMeta`, results, live runs, `workflow/*` events — is [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md); decisions in the [dynamic-workflows](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) and [Ralph consumer](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Notes.
diff --git a/packages/workflow/README.zh.md b/packages/workflow/README.zh.md
index a5c94a0a97..33b3f26780 100644
--- a/packages/workflow/README.zh.md
+++ b/packages/workflow/README.zh.md
@@ -12,3 +12,5 @@
 | [`tool-ralph/`](tool-ralph/README.md) | 公开使用全新 agent（智能体）的固定 Ralph 工作流 | 注册到 `ctx.tools` |
 
 worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)决策。
+
+子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
diff --git a/packages/workspace/README.i18n.yaml b/packages/workspace/README.i18n.yaml
index 93dea4b3f0..c7723f6c56 100644
--- a/packages/workspace/README.i18n.yaml
+++ b/packages/workspace/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/workspace/README.md
-README.md: 9f6ead776c1e5d36af5b6917ad8f27725b11e6a0
-README.zh.md: aa691ec681112f4c25a6391c33eabd2711c7abfc
+README.md: 7e30f26a9854031b4907ad3e7edb35da5986d5d9
+README.zh.md: 6315ccb6b3a8b86161728e8296746efd0c334a29
diff --git a/packages/workspace/README.md b/packages/workspace/README.md
index 9f6ead776c..7e30f26a98 100644
--- a/packages/workspace/README.md
+++ b/packages/workspace/README.md
@@ -9,3 +9,5 @@ This family owns persistent workspaces: user directories with titles and ordered
 | [`workspace/`](workspace/README.md) | Registers workspaces and accounts for their sessions | `ctx.workspace` |
 
 The [workspace package reference](workspace/README.md) owns lifecycle, persistence, and deletion semantics.
+
+The subsystem reference — the entity, realpath canon, registration/resolution — is [docs/subsystems/workspace.md](../../docs/subsystems/workspace.md); storage design in the [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).
diff --git a/packages/workspace/README.zh.md b/packages/workspace/README.zh.md
index aa691ec681..6315ccb6b3 100644
--- a/packages/workspace/README.zh.md
+++ b/packages/workspace/README.zh.md
@@ -9,3 +9,5 @@
 | [`workspace/`](workspace/README.md) | 注册 workspace 并记录其会话归属 | `ctx.workspace` |
 
 [workspace 包参考](workspace/README.md)负责生命周期、持久化和删除语义。
+
+子系统参考——实体、realpath 规范、注册/解析——见 [docs/subsystems/workspace.md](../../docs/subsystems/workspace.md)；存储设计见 [domain KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 120904d4b5..35fef7beaf 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -156,30 +156,30 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   AgentCancelCause: 'core.md',
   AgentOptions: 'core.md',
   AgentStatus: 'core.md',
-  ContentBlock: 'core.md',
+  ContentBlock: 'llm-streaming.md',
   ContinuationDecision: 'core.md',
   ContinuationStop: 'core.md',
-  GenerateOptions: 'core.md',
+  GenerateOptions: 'llm-streaming.md',
   InboxItem: 'core.md',
   InboxPlacement: 'core.md',
-  MessageId: 'core.md',
+  MessageId: 'llm-streaming.md',
   HookContext: 'core.md',
   SettleReason: 'core.md',
-  AdapterRegistrationHandle: 'core.md',
-  DirectoryRegistrationHandle: 'core.md',
-  LlmCallConfig: 'core.md',
-  LlmModelContext: 'core.md',
-  LlmModelReasoningInfo: 'core.md',
-  LlmResolvedModelInfo: 'core.md',
+  AdapterRegistrationHandle: 'llm-streaming.md',
+  DirectoryRegistrationHandle: 'llm-streaming.md',
+  LlmCallConfig: 'llm-streaming.md',
+  LlmModelContext: 'llm-streaming.md',
+  LlmModelReasoningInfo: 'llm-streaming.md',
+  LlmResolvedModelInfo: 'llm-streaming.md',
   LlmFailure: 'llm-streaming.md',
-  LlmModelInfo: 'core.md',
-  LlmProviderInfo: 'core.md',
-  LlmConfigurableProvider: 'core.md',
-  LlmModelDiscoveryRequest: 'core.md',
-  LlmDiscoveredModel: 'core.md',
+  LlmModelInfo: 'llm-streaming.md',
+  LlmProviderInfo: 'llm-streaming.md',
+  LlmConfigurableProvider: 'llm-streaming.md',
+  LlmModelDiscoveryRequest: 'llm-streaming.md',
+  LlmDiscoveredModel: 'llm-streaming.md',
   ResolvedRetryPolicy: 'llm-streaming.md',
-  Message: 'core.md',
-  MessageSource: 'core.md',
+  Message: 'llm-streaming.md',
+  MessageSource: 'llm-streaming.md',
   UserMessage: 'session.md',
   PreStepDecision: 'core.md',
   PreStepContext: 'core.md',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 317ddec122..b3bf8eaec4 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -7,22 +7,17 @@
       "source": "packages/util/brand/src/index.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
-      "symbol": "ContentBlockMap",
-      "source": "packages/llm/llm/src/types.ts"
-    },
-    {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "AssistantProvenance",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "Message",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "MessageSourceMap",
       "source": "packages/llm/llm/src/message.ts"
     },
@@ -42,22 +37,22 @@
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "FinishReasonMap",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "AdapterRegistrationHandle",
       "source": "packages/llm/llm/src/index.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmProviderInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmModelInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
@@ -72,47 +67,47 @@
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmModelContext",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ReasoningEffortId",
       "source": "packages/llm/llm/src/brand.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmReasoningEffortInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmModelReasoningInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmResolvedModelInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "GenerateOptions",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ToolSchema",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmCallConfig",
       "source": "packages/llm/llm/src/call-config.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmCallConfigAdapterDefaults",
       "source": "packages/llm/llm/src/call-config.ts"
     },
@@ -1491,7 +1486,7 @@
       "source": "packages/settings/settings/src/index.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmConfigurableProvider",
       "source": "packages/llm/llm/src/types.ts"
     },
diff --git a/website/docs.ts b/website/docs.ts
index 9a28aeea4d..1f7fa316a5 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -259,7 +259,7 @@ const cordisPrimerReference = pairedPages([
 
 const subsystemsReference = pairedPages(([
   ['README.md', '子系统', 'Subsystems', 0],
-  ['core.md', '核心数据结构', 'Core data structures', 1],
+  ['core.md', '核心', 'Core', 1],
   ['scope.md', '作用域', 'Scopes', 2],
   ['session.md', '会话', 'Sessions', 3],
   ['session-query.md', '会话查询', 'Session query', 4],

From a2aa567371026f23ad1d20236f19c8e97be8cf29 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 3 Aug 2026 16:34:00 +0800
Subject: [PATCH 420/516] docs(subsystems): open core.md on agent
 creation/ownership and the Agent contract; enforce a complete folder index

core.md claimed to be the packages/core reference but opened on repo-wide type patterns and never documented the ownership vocabulary: AgentHandle, CreateAgentOptions, ResumeAgentOptions, and AgentFactory were TYPE_LINK_EXEMPTIONS pointing at a package README, invisible to the folder that calls itself the type reference. The page now reads spine map -> creation and ownership (AgentHandle pasted; the options and factory summarized with links into the generated registry section) -> the Agent handle (AgentStatus, AgentOptions, SteeringOutcome, SteeringReceipt, and SettleReason now pasted; the one settlement prose wall split by topic; delivery vocabulary ordered as a message travels) -> initiator -> interception -> a Sessions summary -> the ToolDefinition pointer -> an explicitly framed repo-wide patterns tail (the ...Map pattern, branded ids). The duplicate SessionEvent paste is gone -- session.md owns it and LINK_MAP follows -- the four ownership types moved from TYPE_LINK_EXEMPTIONS into LINK_MAP -> core.md, and three dead LINK_MAP entries (ContinuationDecision, ContinuationStop, HookContext) no longer name types absent from the source tree. The "what this page owns" meta-section folds into the intro.

The subsystems README index silently lost tasks.md and session-reference.md on both language sides during a base absorption; the rows are restored and scripts/project-doc-site.spec.ts now fails when any page misses either side of the index (proven red on a removed row). tools.md links ToolSchema to its llm-streaming.md declaration instead of calling it core; subagent.md links AgentHandle and CreateAgentOptions.seed to the new section. A new Agent Note records the package-anchored page-scoping decision; the 2026-06-20 catalog note marks its spine-vs-seam rule superseded as the page-scoping rule while keeping the type-equiv mechanism current, and docs/AGENTS.md cites the new note.
---
 ...-20-core-data-structures-catalog.i18n.yaml |   4 +-
 ...2026-06-20-core-data-structures-catalog.md |   2 +
 ...6-06-20-core-data-structures-catalog.zh.md |   4 +-
 ...package-anchored-subsystem-pages.i18n.yaml |   6 +
 ...-08-03-package-anchored-subsystem-pages.md |  34 +
 ...-03-package-anchored-subsystem-pages.zh.md |  34 +
 docs/AGENTS.md                                |   6 +-
 docs/subsystems/README.i18n.yaml              |   4 +-
 docs/subsystems/README.md                     |   7 +-
 docs/subsystems/README.zh.md                  |   7 +-
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       | 692 ++++++---------
 docs/subsystems/core.zh.md                    | 832 +++++++-----------
 docs/subsystems/http-server.i18n.yaml         |   2 +-
 docs/subsystems/http-server.zh.md             |   2 +-
 docs/subsystems/llm-streaming.i18n.yaml       |   4 +-
 docs/subsystems/llm-streaming.md              | 193 +++-
 docs/subsystems/llm-streaming.zh.md           | 193 +++-
 docs/subsystems/permission.i18n.yaml          |   4 +-
 docs/subsystems/permission.md                 |   2 +-
 docs/subsystems/permission.zh.md              |   2 +-
 docs/subsystems/persistence.i18n.yaml         |   4 +-
 docs/subsystems/persistence.md                |   2 +-
 docs/subsystems/persistence.zh.md             |   2 +-
 docs/subsystems/session-projection.i18n.yaml  |   4 +-
 docs/subsystems/session-projection.md         |   2 +-
 docs/subsystems/session-projection.zh.md      |   2 +-
 docs/subsystems/session.i18n.yaml             |   4 +-
 docs/subsystems/session.md                    |   2 +-
 docs/subsystems/session.zh.md                 |   2 +-
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |   4 +-
 docs/subsystems/subagent.zh.md                |   4 +-
 docs/subsystems/tools.i18n.yaml               |   4 +-
 docs/subsystems/tools.md                      |   2 +-
 docs/subsystems/tools.zh.md                   |   2 +-
 packages/interaction/README.i18n.yaml         |   4 +-
 packages/interaction/README.md                |   2 +-
 packages/interaction/README.zh.md             |   2 +-
 packages/self-modification/README.i18n.yaml   |   2 +-
 packages/self-modification/README.zh.md       |   2 -
 scripts/gen-cordis-catalog.ts                 |  13 +-
 scripts/project-doc-site.spec.ts              |  17 +-
 .../request-response.expected.json            |   4 +-
 scripts/type-equiv.manifest.json              |  30 +-
 website/docs.ts                               |   2 +-
 46 files changed, 1126 insertions(+), 1034 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
 create mode 100644 .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md

diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 1b1a93fc99..def34cdfbd 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: b358ad54652e5b16ae90037c128cf756bcfdaed3
-2026-06-20-core-data-structures-catalog.zh.md: d84c2befaee4c2032b358ed1a7949ac0151ae74c
+2026-06-20-core-data-structures-catalog.md: 9a3f80df592f28adc365d5e64cc15516d92b47b5
+2026-06-20-core-data-structures-catalog.zh.md: 96c606a3d65a67e757960c5cbc997e717f11e8d5
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index b358ad5465..9a3f80df59 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -16,6 +16,8 @@ A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type
 
 ### What counts as "core" — the spine-vs-seam line
 
+> **Superseded as the page-scoping rule** by [package-anchored subsystem pages](2026-08-03-package-anchored-subsystem-pages.md): each page now anchors to the package group that declares its vocabulary. The `ts type-equiv` mechanism below remains current.
+
 The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own seam page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
 
 The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a seam-page detail.*** Worked through:
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index d84c2befae..96c606a3d6 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -16,6 +16,8 @@ Status: implemented
 
 ### 何为「核心」——主干与 seam 的分界线
 
+> **作为页面范围界定规则已被取代**，见[按包锚定的子系统页面](2026-08-03-package-anchored-subsystem-pages.md)：每页现在锚定到声明其词汇的包分组。下文的 `ts type-equiv` 机制仍然有效。
+
 范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入子页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
 
 确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是子页面细节。*** 逐一验证如下：
@@ -25,7 +27,7 @@ Status: implemented
 - `ToolSchema` 是核心（它是流经每个步骤的模型请求 `GenerateOptions` 的一个字段），即使它在概念上属于工具流水线——当*流经主干*与*概念归属*冲突时，前者胜出。
 - 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇是子页面。
 
-`core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到子页面获取各 seam 的细节。子页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
+`core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到同级 seam 页面获取各 seam 的细节；目录的 [README](../../../../docs/subsystems/README.md) 索引全部页面。最初的 seam 页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
 
 ### `ts type-equiv` 机制——既逐字又防漂移
 
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
new file mode 100644
index 0000000000..7bc08eb82d
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.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/process/2026-08-03-package-anchored-subsystem-pages.md
+2026-08-03-package-anchored-subsystem-pages.md: 5ba7937f0c142727d343a107a3ff87f5f337931e
+2026-08-03-package-anchored-subsystem-pages.zh.md: 27d56158a69a8144b0915054032fb3b54493bd0b
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
new file mode 100644
index 0000000000..5ba7937f0c
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
@@ -0,0 +1,34 @@
+# Agent Note: Package-anchored subsystem pages and thin group READMEs
+
+Status: implemented
+
+English | [中文](2026-08-03-package-anchored-subsystem-pages.zh.md)
+
+## Problem
+
+The [subsystems catalog](2026-06-20-core-data-structures-catalog.md) scoped its front page by the spine-vs-seam rule: a type was "core" if the loop holds, derives, streams, or logs it on every turn. That rule selected types, not packages, so as the folder grew to forty-plus pages the front page became a cross-package grab-bag: LLM conversation vocabulary sat above the agent contracts, the creation/ownership vocabulary (`AgentHandle`, `CreateAgentOptions`, `ResumeAgentOptions`, `AgentFactory`) was documented nowhere in the folder because the generator exempted it to a package README, and a reader could not predict which page documents a type from where the type lives. Package-group READMEs meanwhile had no common shape — some carried sectioned tables, stray design essays, or trailing paragraphs that belonged on a subsystem page.
+
+## Decision
+
+Every `docs/subsystems/` page anchors to the package or package group that declares its vocabulary, and page membership follows the repository layout: [core.md](../../../../docs/subsystems/core.md) is the `packages/core` page (creation and ownership, the `Agent` handle with its delivery/cancellation/interception contracts, pointers to the group's dedicated pages), [llm-streaming.md](../../../../docs/subsystems/llm-streaming.md) owns `packages/llm` end-to-end, and so on. Repo-wide type patterns (`…Map → derived-union`, branded ids) stay on core.md in an explicitly framed closing section rather than interleaved with the package content. This supersedes the spine-vs-seam rule *as the page-scoping rule*; the placement heuristic that survives is simpler: a type is documented where its declaring package's page is, and machinery keeps living with its machinery.
+
+Every type a generated signature references must resolve somewhere in the folder: the agent ownership vocabulary moved from the generator's `TYPE_LINK_EXEMPTIONS` into `LINK_MAP → core.md`, so exemptions are reserved for genuinely service-local or vendored shapes. Each pasted declaration has one home (`SessionEvent` lives on [session.md](../../../../docs/subsystems/session.md); core.md summarizes and links).
+
+Every `packages/<group>/README.md` pair is a thin front door in one shape: a why-first intro paragraph, a package table (Package / Role / ctx key), and a closing pointer to the owning subsystems page. Load-bearing prose that outgrows that shape relocates to the owning subsystems page rather than being deleted.
+
+The [subsystems README](../../../../docs/subsystems/README.md) indexes every page in the folder on both language sides; `scripts/project-doc-site.spec.ts` enforces one table row per page, so a page added by a later PR (or absorbed in a merge) cannot silently miss the index.
+
+## Alternatives considered
+
+**Keep the spine-vs-seam scoping rule.** It answered "is this type core?" per type, which is why the front page accumulated types from four packages while missing half of `packages/core/agent`'s public surface. Predictability by repository layout won.
+
+**A flat single-document catalog.** Already rejected in the [original catalog note](2026-06-20-core-data-structures-catalog.md); the growth to forty-one pages confirmed that verdict.
+
+**Document ownership vocabulary only in package READMEs (the exemption status quo).** This left `AgentHandle` and the create/resume options invisible to the folder that claims to be the type reference, and the generated `Types:` footers could not link them.
+
+## Consequences
+
+- Which page documents a type is predictable from `packages/<group>/`; the subsystems README is a complete index enforced by test.
+- Generated signature footers link the agent ownership vocabulary instead of silently exempting it.
+- `verify-type-equiv`'s 1:1 manifest keeps each paste single-homed; the duplicate `SessionEvent` paste is gone.
+- The [original catalog note](2026-06-20-core-data-structures-catalog.md) remains the owner of the `ts type-equiv` drift-gate mechanism; only its page-scoping rule is superseded here.
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
new file mode 100644
index 0000000000..27d56158a6
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
@@ -0,0 +1,34 @@
+# Agent Note：按包锚定的子系统页面与轻薄的分组 README
+
+Status: implemented
+
+[English](2026-08-03-package-anchored-subsystem-pages.md) | 中文
+
+## Problem
+
+[子系统目录](2026-06-20-core-data-structures-catalog.md)最初用主干-vs-seam 规则界定首页范围：如果循环在每个轮次都持有、派生、流式传输或记录某个类型，它就是「核心」。该规则选择的是类型而非包，因此当目录增长到四十多页后，首页变成了跨包大杂烩：LLM 对话词汇排在 agent 契约之前，创建/所有权词汇（`AgentHandle`、`CreateAgentOptions`、`ResumeAgentOptions`、`AgentFactory`）在目录中无处记录（生成器把它们豁免给了某个包 README），读者无法根据类型所在位置预测哪一页记录它。与此同时，各包分组 README 没有统一形状——有的带分节表格、游离的设计短文，或本应属于子系统页面的尾部段落。
+
+## Decision
+
+每个 `docs/subsystems/` 页面锚定到声明其词汇的包或包分组，页面归属跟随仓库布局：[core.md](../../../../docs/subsystems/core.md) 是 `packages/core` 的页面（创建与所有权、`Agent` 句柄及其投递/取消/拦截契约、指向该组专属页面的指针），[llm-streaming.md](../../../../docs/subsystems/llm-streaming.md) 端到端拥有 `packages/llm`，依此类推。全仓通用类型模式（`…Map → 派生联合`、品牌化 id）保留在 core.md 一个明确标注的收尾小节中，而不是与包内容交错。这在*页面范围界定规则*的意义上取代了主干-vs-seam 规则；存活下来的放置启发式更简单：类型记录在其声明包对应的页面，机制仍与其机制放在一起。
+
+生成签名引用的每个类型都必须能在目录中某处解析：agent 所有权词汇从生成器的 `TYPE_LINK_EXEMPTIONS` 移入 `LINK_MAP → core.md`，因此豁免只留给真正服务本地或 vendored 的形状。每个粘贴的声明只有一个家（`SessionEvent` 位于 [session.md](../../../../docs/subsystems/session.md)；core.md 概括并链接）。
+
+每个 `packages/<group>/README.md` 配对都是统一形状的轻薄门面：一段以「为什么」开头的介绍、一张包表格（包 / 角色 / ctx 键）、一个指向拥有方子系统页面的收尾指针。超出该形状的承重散文迁移到拥有方子系统页面，而非删除。
+
+[子系统 README](../../../../docs/subsystems/README.md) 在两个语言侧索引目录中的每一页；`scripts/project-doc-site.spec.ts` 强制每页一行表格，因此后续 PR 新增（或合并吸收）的页面无法悄悄缺席索引。
+
+## Alternatives considered
+
+**保留主干-vs-seam 界定规则。**它逐类型回答「这个类型是核心吗？」，这正是首页积累了四个包的类型、却缺失 `packages/core/agent` 一半公开 surface 的原因。按仓库布局可预测性胜出。
+
+**扁平的单文档目录。**在[原目录 note](2026-06-20-core-data-structures-catalog.md) 中已被否决；增长到四十一页证实了该结论。
+
+**只在包 README 中记录所有权词汇（豁免的现状）。**这让 `AgentHandle` 与 create/resume 选项在自称类型参考的目录中不可见，生成的 `Types:` 页脚也无法链接它们。
+
+## Consequences
+
+- 哪一页记录某类型可由 `packages/<group>/` 预测；子系统 README 是由测试强制的完整索引。
+- 生成的签名页脚链接 agent 所有权词汇，而不是静默豁免。
+- `verify-type-equiv` 的 1:1 manifest 保证每个粘贴单一归属；重复的 `SessionEvent` 粘贴已移除。
+- [原目录 note](2026-06-20-core-data-structures-catalog.md) 仍拥有 `ts type-equiv` 漂移检查机制；此处仅取代其页面范围界定规则。
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 88c90678de..a5eca656db 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -21,8 +21,8 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
 | [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
-| [subsystems/](subsystems/README.md) | One reference page per subsystem: literal type shapes, semantics, and the generated Cordis surface | Behavior narration (→ architecture.md) |
-| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and concise verification contract; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
+| [subsystems/](subsystems/README.md) | One reference page per subsystem: type shapes, semantics, and the generated Cordis surface | Behavior narration (→ architecture.md) |
+| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and verification contract; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
 | [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
 | [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
@@ -39,7 +39,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
 - Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams".
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index 3303bcb935..f1636e0191 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/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 docs/subsystems/README.md
-README.md: d225e5f4eeb31d1e6c71cbd8311e28bae1e8b3a5
-README.zh.md: 9f78ac3e1c79440b053ee4e344dbdba2c11b3dfc
+README.md: 1c3d14aeb4fd11cbc45eaadd83f0b84de0dfda52
+README.zh.md: dda61d86c4d00117af851b4a55d16b97c6bc2f10
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
index d225e5f4ee..1c3d14aeb4 100644
--- a/docs/subsystems/README.md
+++ b/docs/subsystems/README.md
@@ -6,7 +6,7 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 
 | Page | Owns |
 |---|---|
-| [core.md](core.md) | the `packages/core` control spine: the package-by-package loop map, the `Agent` handle with its delivery/cancellation/interception contracts, the `SessionEvent` envelope, branded ids, the `…Map → derived-union` pattern |
+| [core.md](core.md) | the `packages/core` control spine: the package-by-package loop map, agent creation and ownership (`AgentHandle`), the `Agent` handle with its delivery/cancellation/interception contracts, and the repo-wide type patterns (`…Map → derived-union`, branded ids) |
 | [llm-streaming.md](llm-streaming.md) | the `packages/llm` conversation vocabulary — `Message`/`ContentBlock`, the assembled model request, the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
 | [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
@@ -19,6 +19,7 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | [credentials.md](credentials.md) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo`, provider source layers |
 | [session-query.md](session-query.md) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages |
 | [session-title.md](session-title.md) | durable title snapshots, source provenance, and the asynchronous provider contract |
+| [session-reference.md](session-reference.md) | structured cross-session references: `SessionReferenceInput`/`Candidate`, prepared message contexts, the stable error taxonomy |
 | [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
 | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
 | [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
@@ -36,12 +37,12 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider availability, `WebError` |
 | [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
 | [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
+| [tasks.md](tasks.md) | the background-task runtime: branded `TaskId`s, the producer contract, consumer views, `ctx.tasks` service behavior |
 | [permission.md](permission.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event |
 | [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
 | [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
-| [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the static dist fallback, index taps |
+| [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the claimable fallback seat, index taps |
 | [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
-| [tui.md](tui.md) | the terminal-extension seam: `TuiOverlayRequest`/`Host`/`Session`, close reasons and outcomes, the modal queue |
 | [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
 | [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
 | [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index 9f78ac3e1c..dda61d86c4 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -6,7 +6,7 @@
 
 | 页面 | 负责内容 |
 |---|---|
-| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、`Agent` 句柄及其投递/取消/拦截契约、`SessionEvent` 信封、品牌化 id，以及 `…Map → 派生联合` 模式 |
+| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截契约，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
 | [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
@@ -19,6 +19,7 @@
 | [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
 | [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
 | [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 |
+| [session-reference.md](session-reference.md) | 结构化跨会话引用：`SessionReferenceInput`/`Candidate`、prepared 消息上下文、稳定错误分类 |
 | [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
 | [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
 | [user-interaction.md](user-interaction.md) | UI 支持的人工问答 seam：`AskUserQuestionRequest`、answer/options 词汇、提供方 API、错误分类体系 |
@@ -36,12 +37,12 @@
 | [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
 | [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
 | [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
+| [tasks.md](tasks.md) | 后台任务运行时：品牌化 `TaskId`、producer 契约、consumer 视图、`ctx.tasks` 服务行为 |
 | [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
 | [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
 | [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
-| [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、静态 dist 回退、index 转换 |
+| [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、可认领的回退席位、index 转换 |
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
-| [tui.md](tui.md) | 终端扩展 seam：`TuiOverlayRequest`/`Host`/`Session`、关闭原因与结果、模态队列 |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 16c8e29cf2..caf9356ee9 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: ba9319d377cf250148a145ba3f1fa1baa967c858
-core.zh.md: 276dc4f99f1f802e66aca050b2fbcdc178931611
+core.md: cc9cc30677b0b657492d8a5118489e8b801f3fd3
+core.zh.md: 6878300dc2cbd82d220e17d2d6f5e1009f41c48f
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index ba9319d377..cc9cc30677 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -2,11 +2,11 @@
 
 English | [中文](core.zh.md)
 
-The **core** subsystem is [`packages/core`](../../packages/core/README.md) — the control spine every composition boots: the event-sourced session log, system-prompt assembly, the tool registry, the agent vocabulary, and the concrete loop that drives them. This page owns the spine's shared vocabulary — the `Agent` handle, its delivery and interception contracts, and the repo-wide type patterns — and orients to the group's dedicated pages; the folder is indexed in the [subsystems README](README.md).
+The **core** subsystem is [`packages/core`](../../packages/core/README.md) — the control spine every composition boots: the event-sourced session log, system-prompt assembly, the tool registry, the agent vocabulary, and the concrete loop that drives them. This page owns what the `agent`/`agent-loop` pair declares — how an agent is created and owned, and the `Agent` handle with its delivery, cancellation, and interception contracts — plus the two type patterns every subsystem follows; the group's dedicated pages and the rest of the folder are indexed in the [subsystems README](README.md).
 
 ## The spine, package by package
 
-A turn flows through the six packages in one loop: the driver in [`agent-loop`](../../packages/core/agent-loop) claims a queued prompt, opens a turn on the [session log](session.md) (`ctx.sessions`), assembles the request prefix through [system-prompt](system-prompt.md) (`ctx.systemPrompt`) and derives history from the log, streams the model response through the [LLM seam](llm-streaming.md), dispatches tool calls through the [tool registry](tools.md) (`ctx.tools`), and appends every model-visible fact back onto the log before the next step derives from it.
+A turn flows through the six packages in one loop: the driver in [`agent-loop`](../../packages/core/agent-loop) claims a queued prompt, opens a turn on the [session log](session.md) (`ctx.sessions`), assembles the request prefix through [system-prompt](system-prompt.md) (`ctx.systemPrompt`) and derives history from the log, streams the model response through the [LLM seam](llm-streaming.md), dispatches tool calls through the [tool registry](tools.md) (`ctx.tools`), and appends every model-visible fact back onto the log before the next step derives from it. The conversation vocabulary the loop moves — `Message`, `ContentBlock`, `StreamChunk`, the model request — is declared by [`packages/llm`](../../packages/llm/README.md) and documented on [llm-streaming.md](llm-streaming.md).
 
 | Package | Owns | Page |
 |---|---|---|
@@ -19,208 +19,45 @@ A turn flows through the six packages in one loop: the driver in [`agent-loop`](
 
 `scope/` is the one non-service package: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) that sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle. `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; it runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent` — including when they need the initiating Agent — and never on `agent-loop` directly, so the loop stays swappable. The default composition that wires this spine into a runnable agent is [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md).
 
-<a id="what-counts-as-core"></a>
+## Creation and ownership
 
-## What this page owns
+Consumers create agents through `ctx.agents` — `create()` builds a fresh session and agent under one caller-supplied `SessionId`, `resume()` loads a persisted session first — or declaratively through the loop's config entries. Programmatic creation returns the owner's handle:
 
-The conversation vocabulary the loop moves — `Message`, `ContentBlock`, `StreamChunk`, the model request — is declared by [`packages/llm`](../../packages/llm/README.md) and documented on [llm-streaming.md](llm-streaming.md); the session-event, prompt-assembly, and tool vocabularies live on this group's dedicated pages above. What remains here is the vocabulary shared by everything: the `Agent` handle and its delivery, cancellation, and interception contracts (declared by `packages/core/agent`), the `SessionEvent` envelope, and the two type patterns every subsystem follows. The scoping rule is recorded in the [subsystems-catalog Agent Note](../../.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md): the type you write, hold, or receive is documented where its declaring subsystem is; the machinery that types, renders, or persists it stays on that machinery's page.
-
-## The `…Map → derived-union` pattern
-
-Almost every extensible sum type in the harness follows one shape: an interface keyed by a discriminant tag (the `…Map`), from which the union is derived with `keyof`. Plugins add variants by **declaration merging** — no edit to the owning package.
-
-```ts ignore-check
-// The pattern, schematically:
-interface ThingMap {
-  'a': { kind: 'a'; /* … */ }
-  'b': { kind: 'b'; /* … */ }
-}
-type ThingKind = keyof ThingMap          // 'a' | 'b'
-type Thing = ThingMap[keyof ThingMap]    // the discriminated union
-
-// A plugin extends it without touching the source package:
-declare module '@deepseek-ai/dsh-llm' {
-  interface ThingMap {
-    'c': { kind: 'c'; /* … */ }
-  }
-}
-```
-
-Six canonical maps use this pattern; a plugin author extends these:
-
-| Map | Package | Derives | Catalog |
-|---|---|---|---|
-| `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
-| `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
-| `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
-| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
-| `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
-| `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
-
-Two large discriminated unions are the ones consumers `switch` over most: **`StreamChunk`** (the streaming protocol) and **`SessionEvent`** (the log entry). Per the repo convention, `switch` on the tag — don't chain `if`s — so each arm narrows and a typo'd tag fails to compile.
-
-## Branded IDs
-
-IDs that cross package boundaries are **branded** — structurally strings, but non-interchangeable at the type level (a `SessionId` cannot be passed where a `CallId` is expected). Construction goes through a per-type factory; comparison, logging, and JSON behave as ordinary strings.
-
-The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package.
-
-Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
-
-```ts type-equiv
-/** A string carrying a compile-time-only brand `B`. */
-type Branded<B extends string> = string & { readonly [BRAND]: B }
-```
-
-The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm) and `SessionId` (the shared live agent and durable session identity; dsh-session). Capability packages brand their own ids too, such as `TaskId` in [tasks.md](tasks.md).
-
-## Sessions
-
-A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. The event vocabulary derives from `SessionEventMap`:
-
-Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/agent/src/index.ts`](../../packages/core/agent/src/index.ts)
 
 ```ts type-equiv
 /**
- * One immutable entry in the session log.
+ * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
+ * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
+ * only the holder can tear this agent down. The registered factory provider is
+ * also a structural owner because the scoped agent depends on that provider's
+ * service surface; provider unload stops and drains every live handle it made.
+ * `dispose()` stops the loop, awaits its exit, unregisters the agent, removes
+ * its session from the store, and finally unwinds its scoped world.
  *
- * A proper discriminated union over `type` (not independent `type`/`data`
- * unions), so `switch (event.type)` narrows `event.data` without casts.
- *
- * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
- * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`, `steering/message`).
- * Non-surface events (boundary markers, chunks, usage, errors) never carry
- * surface metadata — the compiler enforces this at `Session.append()`
- * call sites.
+ * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is
+ * exposed only to the consumer owner that created it; the structural provider
+ * reaches the same teardown internally. Config-created agents (the loop's own
+ * startup) are owned by the loop fiber and never need a handle.
  */
-type SessionEvent<T extends SessionEventType = SessionEventType> = {
-  [K in SessionEventType]: {
-    type: K
-    /** Monotonic sequence number within the session. */
-    seq: number
-    /** Unix epoch milliseconds. */
-    time: number
-    data: SessionEventMap[K]
-  } & (K extends SurfaceEventType ? {
-    /**
-     * Seq numbers of events that are provenance sources of this event
-     * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
-     * or the surface nodes shadowed by a compaction replace node). An
-     * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
-     */
-    sourceEventSeqs?: number[]
-    /** How this event entered the surface; absent for non-surface events. */
-    surfaceOp?: SurfaceOp
-  } : object)
-}[T]
+interface AgentHandle {
+  agent: Agent
+  dispose(): Promise<void>
+}
 ```
 
-The twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
+`CreateAgentOptions` carries the shared identity and everything a fresh agent needs before publication: session metadata (`meta` — validated `cwd`, fork lineage, seed boundary, origin classification, delegation depth), an optional `seed` replay prefix for forks, per-agent `AgentOptions`, a creation-only cancellation `signal`, and `setup`. `ResumeAgentOptions` is the persisted-identity counterpart: `resumeSessionId`, `agentOptions`, `signal`, and `setup`. The `setup` callback (`AgentSetup`) composes the agent's scoped world while both ids are still unpublished — everything registered through `agentCtx` exists before `agent/created` and the first prompt assembly — and may return a synchronous commit invoked immediately before publication; a setup rejection, commit throw, or owner disposal rolls the transaction back without publishing either id.
+
+`AgentFactory` is the creation seam behind the registry: the loop registers its factory via `ctx.agents.setFactory()`, so consumers program against `ctx.agents` without depending on the concrete loop package. The exact `create`/`resume` signatures and their rollback contracts are in the [generated section](#ctxagents--agentregistry) below.
 
 ## The agent handle
 
-`Agent` is the surface every plugin (UI, hooks, orchestrators) programs against. The concrete implementation is package-internal to dsh-agent-loop; nothing outside the loop depends on it.
+`Agent` is the surface every plugin (UI, hooks, orchestrators) programs against; `ctx.agents.get(id)` returns it, and the [initiator scope](#initiating-agent) carries it. The concrete implementation is package-internal to dsh-agent-loop; nothing outside the loop depends on it. The unified `send` method exposes target and wakeup routing directly; `followup`, `steer`, and `inject` are fixed-preset aliases.
 
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
 ```ts type-equiv
-/**
- * Which inbox queue a {@link Agent.send} item joins:
- * - `next-turn` — the item becomes its own turn, claimed at a turn boundary.
- * - `next-step` — during prompt admission or an open turn, the item stages for
- *   the next safe step boundary; otherwise it is promoted per its `wakeup`
- *   flag.
- */
-type SendTarget = 'next-turn' | 'next-step'
-```
-
-```ts type-equiv
-/** Resolved inbox placement reported when an accepted message is enqueued. */
-type InboxPlacement = 'queued' | 'steering'
-```
-
-`InboxItemId` is a process-local branded string minted for each accepted FIFO occurrence. It is intentionally distinct from `MessageId`: sending the same immutable message twice creates two independently addressable pending items.
-
-```ts type-equiv
-/** One independently addressable accepted occurrence in an agent inbox. */
-interface InboxItem {
-  /** Agent-loop-minted occurrence identity. */
-  readonly id: InboxItemId
-  /** Identified message delivered by the caller. */
-  readonly message: UserMessage
-  /** Acceptance-time FIFO classification. */
-  readonly placement: InboxPlacement
-}
-```
-
-```ts type-equiv
-/** A user-requested mutation of one still-pending queued occurrence. */
-type InboxAction =
-  | { readonly kind: 'edit'; readonly content: ContentBlock[] }
-  | { readonly kind: 'remove' }
-  | { readonly kind: 'steer' }
-```
-
-```ts type-equiv
-/** Result of applying an inbox action at the synchronous ownership boundary. */
-type InboxActionResult = 'applied' | 'not-found' | 'steer-unavailable'
-```
-
-```ts type-equiv
-/**
- * Options for the unified {@link Agent.send} primitive over the
- * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
- * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
- * {@link Agent.inject} (`next-step`/no-wakeup).
- *
- * The object is complete so routing policy is explicit.
- */
-interface SendOptions {
-  /** Queue the item joins. */
-  target: SendTarget
-  /**
-   * Whether this item makes the model run: wake a parked driver (`next-turn`)
-   * or force a continuation step (`next-step` while running). A `false`
-   * `next-turn` item queues without waking; a `false`
-   * `next-step` item attaches durable context without forcing another step
-   * (the injection preset).
-   */
-  wakeup: boolean
-}
-```
-
-The fixed-preset aliases own `target` and `wakeup`; their already identified `UserMessage` carries role, content, and provenance. Its `MessageId` remains stable when an edit replaces content or strict steer transfers the immutable message. The original queued occurrence ends and strict steer accepts a new steering occurrence with a distinct `InboxItemId`. Injection bypasses the FIFOs and never appears on inbox lifecycle events.
-
-```ts type-equiv
-/** Options for {@link Agent.cancel}. */
-interface CancelOptions {
-  /**
-   * Preserve queued and steering inbox items instead of discarding them. The
-   * active turn is still aborted, but un-started and pending work survives for a
-   * later turn and no `agent/inbox/discard` fires.
-   */
-  keepInbox?: boolean
-}
-```
-
-`SteeringReceipt.outcome` always resolves. `admitted` identifies the turn and step whose immutable request history contains that exact message; `rejected` means lifecycle or terminal policy discarded it first. Synchronous input validation still throws from `steer()`.
-
-```ts type-equiv
-/** Stable runtime cause accepted by {@link Agent.cancel}. */
-type AgentCancelCause =
-  | { readonly kind: 'user' }
-  | { readonly kind: 'parent' }
-```
-
-`Agent` is an interface over the public live-agent contract. Concrete drivers own the `followup`/`steer`/`inject` aliases and route them through `send`'s (`target` × `wakeup`) matrix.
-
-```ts type-equiv
-/**
- * Public live-agent handle with aliases over the unified delivery primitive.
- * @typert object
- */
+/** Public live-agent handle. */
 interface Agent {
   /** The single identity shared with {@link session}. */
   readonly id: SessionId
@@ -228,78 +65,28 @@ interface Agent {
   readonly options: AgentOptions
   /** The live session this agent drives; its log is the durable source of truth. */
   readonly session: Session
+  /** The agent-owned projection of durable pending work. */
+  readonly inbox: Inbox
   /** The current lifecycle state, mirrored on every `agent/status` transition. */
   readonly status: AgentStatus
-  /**
-   * Whether a `next-step` send currently stages for prompt admission or the
-   * open turn. Unlike {@link status}, this excludes admission exit and turn
-   * settlement, when a waking `next-step` send becomes a queued follow-up.
-   */
-  readonly acceptsNextStep: boolean
   /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
-  /**
-   * The unified delivery primitive over the (`target` × `wakeup`) matrix.
-   * It routes the caller's typed content and source as follows:
-   *
-   * - `next-turn` queues an item that becomes the sole ordinary message of its
-   *   own FIFO-ordered turn; `wakeup:true` wakes a
-   *   parked driver, while `wakeup:false` queues without waking.
-   * - `next-step` with `wakeup:true` stages steering during prompt admission
-   *   or an open turn; outside that window it falls back to a woken
-   *   `next-turn`.
-   * - `next-step` with `wakeup:false` injects durable model-facing context
-   *   without running the model: admission or an open turn stages it for the
-   *   next safe log position, while an injection outside that window appends
-   *   immediately without opening a turn. If admission closes without a turn,
-   *   a context-only boundary appends immediately; context staged beside
-   *   steering remains pending with it.
-   * The agent publishes or queues the identified frozen message as-is.
-   * @param message - identified model-facing content and its producer provenance.
-   * @param options - target queue and wakeup decision.
-   */
-  send(message: UserMessage, options: SendOptions): void
-
-  /**
-   * Reserve admission of the next ordinary turn while this agent is idle, so an
-   * operation can mutate durable history before any queued prompt derives a
-   * request from it. Already-accepted waking work has right of way, including a
-   * send whose wake is still a pending microtask. Later sends keep their
-   * ordinary placement, FIFO order, and `wakeup` facts, and
-   * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes
-   * a queued follow-up rather than steering; cancellation and disposal may
-   * still discard them. {@link inject} is not withheld. {@link whenIdle} treats
-   * a live reservation as activity, while lifecycle teardown does not await it.
-   * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work.
-   */
-  reserveTurnAdmission(): (() => void) | undefined
-
-  /**
-   * Mutate one still-pending queued occurrence synchronously. Editing preserves
-   * the message identity and queue position; removal publishes its terminal
-   * discard. Steer strictly transfers the message into the current next-step
-   * window, or returns `steer-unavailable` without changing the queued
-   * occurrence. Steering occurrences and driver-claimed items return
-   * `not-found`.
-   * @param id - independently addressable queued occurrence.
-   * @param action - edit, remove, or strict steer operation.
-   * @returns the applied outcome or the reason no mutation occurred.
-   */
-  updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult
-
   /**
    * Clear queued and steering work — unless `keepInbox` — and abort the active
-   * turn. An effective call first emits `agent/cancel-requested` with the
-   * resolved typed cause. The first cause wins for the active turn, and
-   * `whenIdle()` resolves after cancellation reaches quiescence. Idle
-   * cancellation is a no-op and does not arm later work.
-   * @param cause - the stable caller intent carried by the current turn signal.
+   * turn or between-turn task. The first cause wins for that activity. With no
+   * active activity, cancellation is a no-op and does not arm later work.
+   * @param cause - the stable caller intent carried by the active operation signal.
    * @param options - cancellation options; `keepInbox` preserves pending work.
    */
   cancel(cause: AgentCancelCause, options?: CancelOptions): void
 
-  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
+  /**
+   * Resolve after the current whole-agent activity reaches quiescence. This
+   * follows replacement work started before the observed driver retires,
+   * but does not identify the settlement of any particular message.
+   * @returns fulfillment after no active driver or maintenance task remains.
+   */
   whenIdle(): Promise<void>
 
   /**
@@ -334,35 +121,86 @@ interface Agent {
   followup(message: UserMessage): void
 
   /**
-   * Submit steering with a message-owned admission receipt — the
-   * `next-step`/wakeup preset of {@link send}. During prompt admission or an
-   * open turn, the message waits in the steering FIFO until a committed step
-   * snapshots it; outside that window it enters the ordinary queued FIFO. The
-   * receipt resolves `admitted` only after the message joins that step's
-   * immutable request history, or `rejected` when terminal policy,
-   * cancellation, or disposal discards it first. A non-terminal turn close may
-   * leave it staged for a later admitted prompt without settling the receipt.
+   * Submit steering for the nearest step. An idle driver starts a turn;
+   * a running driver consumes it at its next step boundary.
+   * A rejected step leaves steering parked in the inbox until the next
+   * wake; cancellation or disposal may discard pending steering.
    * @param message - identified steering content and its producer provenance.
-   * @returns the receipt for this exact message's eventual admission outcome.
    */
-  steer(message: UserMessage): SteeringReceipt
+  steer(message: UserMessage): void
 
   /**
-   * Append model-facing context without running the model — the
-   * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn
-   * stages it at the next safe log position; outside that window it appends
-   * immediately without opening a turn. If admission closes without a turn,
-   * a context-only boundary appends immediately; context staged beside
-   * steering remains pending with it.
+   * Queue model-facing context for the next pre-step without waking the
+   * driver. A running driver claims it at the nearest later step boundary;
+   * idle drivers leave it pending until follow-up or steering
+   * wakes them. It may miss a request whose pre-step already claimed its
+   * batch. Cancellation or disposal may discard pending context.
    * @param message - identified injected context and its producer provenance.
    */
   inject(message: UserMessage): void
 }
 ```
 
-`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `acceptsNextStep` is the narrower routing predicate for callers that must choose between steering the current admission/turn and submitting a fresh admitted prompt. A live turn-admission reservation is quiescence-relevant without changing `status` or turning later queue entries into steering; its only authority is to defer the next driver claim until release. `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default.
+```ts type-equiv
+/**
+ * An agent's lifecycle state, emitted on every transition as `agent/status`:
+ * `idle` means no driver is active; `running` begins when waking input starts
+ * cancellable pre-step processing and lasts while the driver drains,
+ * closes, or checkpoints turns. Disposal removes the agent from its registry;
+ * it is not a third observable status.
+ */
+type AgentStatus = 'idle' | 'running'
+```
 
-The cause is a TypeScript-enforced same-process input. An active `TurnCancellation` holder copies its discriminant into the runtime-only `AbortSignal.reason` and is retired before `turn/end` publication; the frozen `AbortSignal.reason` remains readable after that retirement. Only the loop reads the cause (`user`, `parent`, or lifecycle-only `disposed`) back off its own machine-private signal at settlement — there is no public reader, and a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
+`running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `followup()` returns no handle: its `MessageId` identifies durable inbox insertion, claim, and discard facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([decision](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)).
+
+```ts type-equiv
+/** Merge-extensible agent creation options. Persona belongs to system-prompt sections. */
+interface AgentOptions {
+  /** Provider route (must have a registered adapter at call time). */
+  provider?: string
+  /** Model id interpreted by the selected provider adapter. */
+  model?: string
+  /** Maximum output tokens for each conversation-model request. */
+  maxTokens?: number
+}
+```
+
+Dispatch requires `provider` and `model` after `agent/request`. When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. An agent-scoped `deployment:persona` prompt section may shadow the global default persona.
+
+The inbox is the delivery vocabulary — two ordered pending-message lists the agent owns as a durable projection:
+
+```ts type-equiv
+/** One of the two ordered pending-message lists owned by an agent. */
+type InboxTarget = 'next-turn' | 'next-step'
+```
+
+Every pending occurrence is its `UserMessage`; `MessageId` is the sole identity. `Inbox.append`, `prepend`, `replace`, `remove`, `clear`, `splice`, and `claim` record normalized durable `agent/inbox/spliced` mutations and reject duplicate pending ids. `replace(messageId, newMessage)` and `remove(messageId)` locate the pending message across both lists; replacement may change identity and emits the old message as discarded followed by the new message as inserted. Ordinary removals and `clear()` are cancellations. `claim(target)` removes the proposed step batch — all `next-step` input plus, at a turn boundary, one `next-turn` message — through pure deletion splices without emitting discarded notifications, and the loop separately emits per-message claimed notifications. Whole-queue consumers such as UI projections reconstruct `nextTurn` and `nextStep` from the durable splices, while consumers following one message use the exact `agent/inbox/inserted`, `claimed`, and `discarded` notifications.
+
+Cancellation:
+
+```ts type-equiv
+/** Options for {@link Agent.cancel}. */
+interface CancelOptions {
+  /**
+   * Preserve queued and steering inbox items instead of discarding them. The
+   * active turn is still aborted, but un-started and pending work survives for a
+   * later turn and no canceled inbox splice is logged.
+   */
+  keepInbox?: boolean | undefined
+}
+```
+
+```ts type-equiv
+/** Why an active agent driver was cancelled. */
+type AgentCancelCause =
+  | { readonly kind: 'user' }
+  | { readonly kind: 'parent' }
+  | { readonly kind: 'hook'; readonly reason: string }
+  | { readonly kind: 'disposed' }
+```
+
+The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
 
 The [event taxonomy](../architecture.md#event) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits.
 
@@ -372,22 +210,19 @@ The process-local initiator carried by `ctx.agents` is the exact `Agent` above,
 
 ## Interception decisions
 
-Prompt and post-tool decisions use the same identified `UserMessage` shape as durable user-role input. Each `additionalContexts` entry becomes a separate `user/message`, preserving its identity and provenance. Hook bridges map their native decision fields onto these typed results.
+Pre-step decisions use the same identified `UserMessage` shape as durable user-role input. The entered batch is authoritative and preserves every message's identity and provenance. Hook bridges map their native decision fields onto this typed result.
 
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
-`agent/prompt-submit` returns a `PromptDecision` before a turn opens. Allow may rewrite the claimed prompt or attach `additionalContexts`; block rejects admission without creating turn events:
+`agent/pre-step` receives one payload carrying the exclusive claimed batch (`messages`), the proposed step's coordinates (`turn`, `step`), and the current turn's cancellation `signal`. The initial proposal runs inside an open turn before any step; a tool continuation may submit an empty claimed batch between steps:
+
+It returns a `PreStepDecision`. Reject opens no step. Enter supplies the complete message batch appended after `step/start`; claimed messages omitted by the final decision remain removed, while input inserted after the claim stays pending:
 
 ```ts type-equiv
-/**
- * Prompt interception result. `allow.content` replaces the prompt, while
- * `additionalContexts` appends model-facing context before the turn starts.
- * An `allow` returned by a listener is authoritative: a listener wrapping
- * `next()` preserves both fields unless it intentionally replaces them.
- */
-type PromptDecision =
-  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
-  | { kind: 'block'; reason: string }
+/** Whether and with which messages the loop enters a proposed step. */
+type PreStepDecision =
+  | { kind: 'reject' }
+  | { kind: 'enter'; messages: UserMessage[] }
 ```
 
 `agent/request-error` runs after a failed model step closes and before its turn closes. Listeners can repair durable state or await policy work while the failed turn's signal is still live. A handling listener returns `{ kind: 'retry' }` without calling `next()`; the default `undefined` leaves the failure terminal.
@@ -397,12 +232,7 @@ type PromptDecision =
 type RequestErrorAction = { kind: 'retry' } | undefined
 ```
 
-```ts type-equiv
-/** Model-request failure with an optional machine-routable provider code. */
-type RequestError = Error & { code?: string }
-```
-
-`agent/step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
+`agent/pre-step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
 
 `agent/session-start` carries a `SessionStartSource` (why the session lifecycle began; a bridge keys its SessionStart matcher on it):
 
@@ -411,12 +241,71 @@ type RequestError = Error & { code?: string }
 type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 ```
 
+## Sessions
+
+A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. Every entry carries a monotonic `seq`, a `time`, and a `type`-discriminated `data` payload; surface variants additionally carry `sourceEventSeqs` provenance and a `surfaceOp`.
+
+The `SessionEvent` envelope's exact conditional shape, the twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
+
 ## `ToolDefinition`
 
 The one pipeline-authoring type that is core: what every registered tool *is* — a model-facing `ToolSchema` plus an `execute` function and optional final-content and UI callbacks. A tool author rarely constructs it by hand (the `defineTool` DSL builds it with typed args), but it is the contract the registry holds and the loop dispatches through.
 
 Its full fields, the `defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` typed schema DSL, the `ToolExecution`/`ToolExecutionResult` waterfall shapes, and the tool-presentation UI vocabulary are on **[tools.md](tools.md)**.
 
+## Repo-wide type patterns
+
+Two patterns recur across every subsystem and are documented once, here.
+
+### The `…Map → derived-union` pattern
+
+Almost every extensible sum type in the harness follows one shape: an interface keyed by a discriminant tag (the `…Map`), from which the union is derived with `keyof`. Plugins add variants by **declaration merging** — no edit to the owning package.
+
+```ts ignore-check
+// The pattern, schematically:
+interface ThingMap {
+  'a': { kind: 'a'; /* … */ }
+  'b': { kind: 'b'; /* … */ }
+}
+type ThingKind = keyof ThingMap          // 'a' | 'b'
+type Thing = ThingMap[keyof ThingMap]    // the discriminated union
+
+// A plugin extends it without touching the source package:
+declare module '@deepseek-ai/dsh-llm' {
+  interface ThingMap {
+    'c': { kind: 'c'; /* … */ }
+  }
+}
+```
+
+Six canonical maps use this pattern; a plugin author extends these:
+
+| Map | Package | Derives | Catalog |
+|---|---|---|---|
+| `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
+| `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
+| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
+| `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
+| `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
+
+Two large discriminated unions are the ones consumers `switch` over most: **`StreamChunk`** (the streaming protocol) and **`SessionEvent`** (the log entry). Per the repo convention, `switch` on the tag — don't chain `if`s — so each arm narrows and a typo'd tag fails to compile.
+
+### Branded IDs
+
+IDs that cross package boundaries are **branded** — structurally strings, but non-interchangeable at the type level (a `SessionId` cannot be passed where a `CallId` is expected). Construction goes through a per-type factory; comparison, logging, and JSON behave as ordinary strings.
+
+The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package.
+
+Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
+
+```ts type-equiv
+/** A string carrying a compile-time-only brand `B`. */
+type Branded<B extends string> = string & { readonly [BRAND]: B }
+```
+
+The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm) and `SessionId` (the shared live agent and durable session identity; dsh-session). Capability packages brand their own ids too, such as `TaskId` in [tasks.md](tasks.md).
+
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
 <a id="cordis-surface"></a>
@@ -462,7 +351,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl
 
 Types: [SessionHeader](persistence.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:252`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
 
 <a id="ctxagents--agentregistry"></a>
 
@@ -634,35 +523,12 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
 ### `agent/*` events
 
-<a id="agentcancel-requested--emit"></a>
-
-#### `agent/cancel-requested` — emit
-
-Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained.
-
-```ts cordis-catalog
-/**
- * Effective broad cancellation was requested, before queued/outbox work
- * is cleared or the active turn is aborted. This observe-only notification
- * cannot veto cancellation; listener failures are contained.
- * @param agent - the agent whose current work is being cancelled.
- * @param cause - the explicit typed cancellation cause.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, cause: AgentCancelCause): void
-```
-
-Types: [Scoped](scope.md)
-
-Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts)
-
 <a id="agentcreated--emit"></a>
 
 #### `agent/created` — emit
@@ -676,11 +542,11 @@ A fully configured agent and live session were published. Setup is composition-o
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
- * @param agent - the newly registered agent with its live session and completed setup.
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/created'(this: Scoped<Agent>, agent: Agent): void
+'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -698,11 +564,11 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
  * An agent left the registry; AgentLoop emits this after driver quiescence
  * and scoped-registration unwind, but before session detachment. Custom
  * registry users own their driver-ordering contract.
- * @param agent - the exact agent removed from the registry.
+ * @param payload.agent - the exact agent removed from the registry.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
+'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -713,138 +579,111 @@ Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/t
 
 #### `agent/error` — emit
 
-A step or turn errored. The machine reports a failure here (plus the logger) even when the error has no in-turn position for a durable record.
+A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
 
 ```ts cordis-catalog
 /**
- * A step or turn errored. The machine reports a failure here (plus the
- * logger) even when the error has no in-turn position for a durable record.
- * @param agent - the agent whose turn errored.
- * @param turn - the turn in which the failure surfaced.
- * @param step - the step at which the failure surfaced.
- * @param error - the failure, verbatim.
+ * A step or turn errored. The machine reports a failure here even when
+ * the error has no in-turn position for a durable record.
+ * @param payload.agent - the agent whose turn errored.
+ * @param payload.turn - the turn in which the failure surfaced.
+ * @param payload.step - the step at which the failure surfaced.
+ * @param payload.error - the failure, verbatim.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
+'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
 ```
 
 Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdequeue--emit"></a>
+<a id="agentinboxclaimed--emit"></a>
 
-#### `agent/inbox/dequeue` — emit
+#### `agent/inbox/claimed` — emit
 
-The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message.
+One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
 
 ```ts cordis-catalog
 /**
- * The driver claimed one item out of the inbox: a queued item at a turn
- * boundary, or steering drained between steps. Fires after the item leaves
- * its FIFO and before it becomes a durable message.
- * @param agent - the agent whose inbox item was claimed.
- * @param item - the exact claimed occurrence.
+ * One message left the inbox inside its open turn. If the proposed step
+ * is rejected, the claimed message ends here: it is neither discarded nor
+ * re-emitted as a user/message, and the turn closes without a step.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the claimed message.
+ * @param payload.turn - the owning turn.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdiscard--emit"></a>
+<a id="agentinboxdiscarded--emit"></a>
 
-#### `agent/inbox/discard` — emit
+#### `agent/inbox/discarded` — emit
 
-Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item.
+One message was discarded from the live inbox.
 
 ```ts cordis-catalog
 /**
- * Pending inbox items were dropped without delivering them, so every
- * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
- * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,
- * emits this after `agent/cancel-requested` when applicable and before
- * aborting the active work. Fires once per drop with every dropped item.
- * @param agent - the agent whose inbox items were dropped.
- * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.
+ * One message was discarded from the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the discarded message.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItem[]): void
+'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxenqueue--emit"></a>
+<a id="agentinboxinserted--emit"></a>
 
-#### `agent/inbox/enqueue` — emit
+#### `agent/inbox/inserted` — emit
 
-An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state.
+One message entered the live inbox.
 
 ```ts cordis-catalog
 /**
- * An item entered the queued or steering inbox. `placement` is the
- * acceptance-time routing result; listeners must not reconstruct it from
- * later agent or session state.
- * @param agent - the owning agent.
- * @param item - accepted occurrence, message, and resolved placement.
+ * One message entered the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the inserted message.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxupdate--emit"></a>
+<a id="agentpre-step--waterfall"></a>
 
-#### `agent/inbox/update` — emit
+#### `agent/pre-step` — waterfall
 
-A still-pending queued item changed content. The item id, placement, and position remain stable while the event carries the replacement message.
+Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
 
 ```ts cordis-catalog
 /**
- * A still-pending queued item changed content. The item id, placement, and
- * position remain stable while the event carries the replacement message.
- * @param agent - the owning agent.
- * @param item - the complete post-update occurrence.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/inbox/update'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
-```
-
-Types: [Scoped](scope.md)
-
-Source: [`packages/core/agent/src/types.ts:321`](../../packages/core/agent/src/types.ts)
-
-<a id="agentprompt-submit--waterfall"></a>
-
-#### `agent/prompt-submit` — waterfall
-
-Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn.
-
-```ts cordis-catalog
-/**
- * Allow, rewrite, or block one claimed prompt before it becomes a user
- * message or opens a turn. Call `next()` for the unchanged default. The
- * signal controls only this admission attempt; listeners may cooperate with
- * it but must not retain it for a later attempt or turn.
- * @param agent - the agent whose turn claimed the message.
- * @param message - the frozen claimed message, including identity and source.
- * @param signal - the current turn's explicit abort signal.
+ * Reject a proposed step or replace the messages that enter it. Calling
+ * `next()` preserves the current messages.
+ * @param payload.agent - the agent proposing the step.
+ * @param payload.messages - messages removed from the inbox for this step.
+ * @param payload.turn - the turn that will own the step.
+ * @param payload.step - the step proposed by the loop.
+ * @param payload.signal - the current turn's cancellation signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
+'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
 ```
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
@@ -863,14 +702,14 @@ Replace the frozen call configuration. `await next()` yields the config the mach
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
  * content must use logged channels; this seam cannot mutate messages.
- * @param agent - the agent making the model call.
- * @param turn - the open turn number.
- * @param step - the step whose request this is.
- * @param signal - the current turn's explicit abort signal.
+ * @param payload.agent - the agent making the model call.
+ * @param payload.turn - the open turn number.
+ * @param payload.step - the step whose request this is.
+ * @param payload.signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
 */
-'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
 Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
@@ -881,28 +720,25 @@ Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/t
 
 #### `agent/request-error` — waterfall
 
-Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
 
 ```ts cordis-catalog
 /**
- * Handle a model-request failure after its failed step has closed but
- * before the failed turn closes. A listener returns `{ kind: 'retry' }`
- * without calling `next()` when it owns the error, or calls `next()` to
- * delegate. The default `undefined` leaves the failure terminal.
- * @param agent - the agent whose request failed.
- * @param turn - the open turn number.
- * @param step - the failed step number.
- * @param error - the original model-request failure.
- * @param failure - serializable facts normalized at the final adapter boundary.
- * @param priorFailures - immutable failures that already authorized another
- * retry turn in this consecutive sequence.
- * @param retryPolicy - immutable policy of the adapter registration that served
- * the failed request, or `undefined` if no final adapter served it.
- * @param signal - the turn abort signal.
+ * Handle one failed model-request attempt before the loop retries or closes
+ * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
+ * when it owns recovery, or calls `next()` to delegate. The default
+ * `undefined` leaves the failure terminal.
+ * @param payload.agent - the agent whose request failed.
+ * @param payload.turn - the turn containing the failed request.
+ * @param payload.step - the step containing the failed request attempt.
+ * @param payload.provider - the provider selected for the failed request.
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
+ * @param payload.signal - the turn abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
 ```
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
@@ -921,12 +757,12 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
  * `agent.inject()` to seed model-facing context. This is a notification, not
  * a veto; disposal requested by a lifecycle owner is rechecked before the
  * driver starts.
- * @param agent - the agent whose session lifecycle began.
- * @param source - why the session started (fresh startup, resume, …).
+ * @param payload.agent - the agent whose session lifecycle began.
+ * @param payload.source - why the session started (fresh startup, resume, …).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
+'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -937,18 +773,19 @@ Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/t
 
 #### `agent/status` — emit
 
-Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event.
+Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
 
 ```ts cordis-catalog
 /**
- * Agent status changed (`idle` ⇄ `running`). `send()` does not enter
- * `running` synchronously; drive lifecycle from this event.
- * @param agent - the agent whose status flipped.
- * @param status - the status just entered (the transition's destination).
+ * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
+ * `running` synchronously after reserving cancellation; `idle` means no
+ * driver remains scheduled or active.
+ * @param payload.agent - the agent whose status flipped.
+ * @param payload.status - the status just entered (the transition's destination).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
+'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -959,7 +796,7 @@ Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/t
 
 #### `agent/turn-stopping` — serial
 
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step.
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
 
 ```ts cordis-catalog
 /**
@@ -969,14 +806,17 @@ The turn is about to close: the model owes no response (no live tool calls, no f
  * re-reads its inbox: fresh steering runs another step, none closes the
  * turn. Data decides, so listener order cannot change the outcome. The
  * inverse control (stop a tool loop early) is data too: a tool result
- * carrying `concludesTurn` ends the turn at its step.
- * @param agent - the agent whose turn is at its stop boundary.
- * @param turn - the turn about to close.
- * @param signal - the current turn's explicit abort signal.
+ * carrying `concludesTurn` ends the turn at its step. The conclusion
+ * never short-circuits already-submitted next-step work: same-step
+ * `additionalContexts` or racing steering still runs, and the turn
+ * closes only when that inbox drains.
+ * @param payload.agent - the agent whose turn is at its stop boundary.
+ * @param payload.turn - the turn about to close.
+ * @param payload.signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode serial
  */
-'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
+'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
 ```
 
 Types: [Scoped](scope.md)
@@ -999,12 +839,12 @@ A declarative agent entry failed before it could publish a live agent. Consumers
  * Consumers that buffer work for the configured identity use this
  * transient signal to reject that work instead of waiting forever. Normal
  * factory teardown suppresses failures from the cancelled startup attempt.
- * @param sessionId - exact shared agent/session identity that failed startup.
- * @param error - persistence, setup, or publication failure.
+ * @param payload.sessionId - exact shared agent/session identity that failed startup.
+ * @param payload.error - persistence, setup, or publication failure.
  * @mode emit
  */
-'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
+'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:157`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 276dc4f99f..6878300dc2 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -2,11 +2,11 @@
 
 [English](core.md) | 中文
 
-**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有主干的共享词汇——`Agent` 句柄及其投递与拦截契约，以及全仓通用的类型模式——并指引到该组的专属页面；目录索引见[子系统 README](README.md)。
+**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有 `agent`/`agent-loop` 这对包所声明的内容——agent 如何被创建与拥有，以及 `Agent` 句柄及其投递、取消与拦截契约——外加每个子系统都遵循的两个类型模式；该组的专属页面与目录其余部分见[子系统 README](README.md)。
 
 ## 主干逐包速览
 
-一个轮次按同一条循环流经六个包：[`agent-loop`](../../packages/core/agent-loop) 中的 driver 认领一条排队的 prompt，在[会话日志](session.md)（`ctx.sessions`）上开启轮次，通过 [system-prompt](system-prompt.md)（`ctx.systemPrompt`）组装请求前缀并从日志派生历史，经 [LLM seam](llm-streaming.md) 流式获取模型响应，经[工具注册表](tools.md)（`ctx.tools`）分发工具调用，并把每个模型可见的事实追加回日志，供下一步派生。
+一个轮次按同一条循环流经六个包：[`agent-loop`](../../packages/core/agent-loop) 中的 driver 认领一条排队的 prompt，在[会话日志](session.md)（`ctx.sessions`）上开启轮次，通过 [system-prompt](system-prompt.md)（`ctx.systemPrompt`）组装请求前缀并从日志派生历史，经 [LLM seam](llm-streaming.md) 流式获取模型响应，经[工具注册表](tools.md)（`ctx.tools`）分发工具调用，并把每个模型可见的事实追加回日志，供下一步派生。循环搬运的对话词汇——`Message`、`ContentBlock`、`StreamChunk`、模型请求——由 [`packages/llm`](../../packages/llm/README.md) 声明，记录在 [llm-streaming.md](llm-streaming.md)。
 
 | 包 | 负责内容 | 页面 |
 |---|---|---|
@@ -19,13 +19,251 @@
 
 `scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是 `agent` seam 的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
 
-<a id="what-counts-as-core"></a>
+<a id="creation-and-ownership"></a>
 
-## 本页拥有什么
+## 创建与所有权
 
-循环搬运的对话词汇——`Message`、`ContentBlock`、`StreamChunk`、模型请求——由 [`packages/llm`](../../packages/llm/README.md) 声明，记录在 [llm-streaming.md](llm-streaming.md)；会话事件、提示词组装与工具词汇在上表该组的专属页面。留在本页的是所有部分共享的词汇：`Agent` 句柄及其投递、取消与拦截契约（由 `packages/core/agent` 声明）、`SessionEvent` 信封，以及每个子系统都遵循的两个类型模式。范围界定规则记录在[子系统目录 Agent Note](../../.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md)：你编写、持有或接收的类型记录在其声明子系统所在之处；为它提供类型推导、渲染或持久化的机制留在该机制自己的页面。
+消费方通过 `ctx.agents` 创建 agent——`create()` 在一个调用方提供的 `SessionId` 下构建全新会话与 agent，`resume()` 先加载持久会话——或者通过循环的声明式配置条目创建。编程式创建返回归属所有者的句柄：
 
-## `…Map → derived-union` 模式
+源码：[`packages/core/agent/src/index.ts`](../../packages/core/agent/src/index.ts)
+
+```ts type-equiv
+/**
+ * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
+ * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
+ * only the holder can tear this agent down. The registered factory provider is
+ * also a structural owner because the scoped agent depends on that provider's
+ * service surface; provider unload stops and drains every live handle it made.
+ * `dispose()` stops the loop, awaits its exit, unregisters the agent, removes
+ * its session from the store, and finally unwinds its scoped world.
+ *
+ * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is
+ * exposed only to the consumer owner that created it; the structural provider
+ * reaches the same teardown internally. Config-created agents (the loop's own
+ * startup) are owned by the loop fiber and never need a handle.
+ */
+interface AgentHandle {
+  agent: Agent
+  dispose(): Promise<void>
+}
+```
+
+`CreateAgentOptions` 携带共享标识以及新 agent 发布前所需的一切：会话元数据（`meta`——已校验的 `cwd`、fork 谱系、seed 边界、来源分类、委派深度）、fork 用的可选 `seed` 回放前缀、按 agent 的 `AgentOptions`、仅创建期有效的取消 `signal`，以及 `setup`。`ResumeAgentOptions` 是持久标识的对应物：`resumeSessionId`、`agentOptions`、`signal` 与 `setup`。`setup` 回调（`AgentSetup`）在两个 id 都尚未发布时组装 agent 的作用域世界——凡经 `agentCtx` 注册的内容都先于 `agent/created` 与第一次提示词组装存在——并可返回一个在发布前一刻调用的同步 commit；setup 拒绝、commit 抛出或所有者 dispose 都会回滚事务，两个 id 均不发布。
+
+`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚契约见下方[生成区块](#ctxagents--agentregistry)。
+
+<a id="the-agent-handle"></a>
+
+## Agent 句柄
+
+`Agent` 是每个插件（UI、钩子、orchestrator）面向编程的 surface；`ctx.agents.get(id)` 返回它，[发起者作用域](#initiating-agent)携带它。具体实现为 dsh-agent-loop 包内部细节；循环外没有任何组件依赖它。统一的 `send` 方法直接暴露 target 与 wakeup 路由；`followup`、`steer` 与 `inject` 是固定预设的别名方法。
+
+源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
+
+```ts type-equiv
+/** Public live-agent handle. */
+interface Agent {
+  /** The single identity shared with {@link session}. */
+  readonly id: SessionId
+  /** The provider route and model this agent's requests use. */
+  readonly options: AgentOptions
+  /** The live session this agent drives; its log is the durable source of truth. */
+  readonly session: Session
+  /** The agent-owned projection of durable pending work. */
+  readonly inbox: Inbox
+  /** The current lifecycle state, mirrored on every `agent/status` transition. */
+  readonly status: AgentStatus
+  /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
+  readonly ctx: Context
+
+  /**
+   * Clear queued and steering work — unless `keepInbox` — and abort the active
+   * turn or between-turn task. The first cause wins for that activity. With no
+   * active activity, cancellation is a no-op and does not arm later work.
+   * @param cause - the stable caller intent carried by the active operation signal.
+   * @param options - cancellation options; `keepInbox` preserves pending work.
+   */
+  cancel(cause: AgentCancelCause, options?: CancelOptions): void
+
+  /**
+   * Resolve after the current whole-agent activity reaches quiescence. This
+   * follows replacement work started before the observed driver retires,
+   * but does not identify the settlement of any particular message.
+   * @returns fulfillment after no active driver or maintenance task remains.
+   */
+  whenIdle(): Promise<void>
+
+  /**
+   * Run one non-turn maintenance task from the true idle phase. The task starts
+   * synchronously after claiming that phase; later waking input remains in the
+   * inbox until the task settles, while public status stays `idle`.
+   * `whenIdle()` follows both the task and any waking work released behind it.
+   * @param task - operation whose fulfillment or rejection is preserved, with a signal aborted by {@link cancel}.
+   * @throws synchronously when turn-driving or another maintenance task already owns the agent.
+   * @returns the task promise.
+   */
+  runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>
+
+  /**
+   * Route identified input to an inbox boundary and optionally wake the driver.
+   * Waking input submitted after active cancellation is queued for the next
+   * turn and runs when the aborted activity converges to idle; a `disposed`
+   * cancel leaves it parked. A wake submitted while already idle always opens
+   * its turn boundary, even when its message is cleared before the driver
+   * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
+   * @param message - identified content and its producer provenance.
+   * @param target - the preferred next-turn or next-step inbox boundary.
+   * @param wakeup - whether delivery may wake the driver.
+   */
+  send(message: UserMessage, target: InboxTarget, wakeup: boolean): void
+
+  /**
+   * Queue an ordinary follow-up turn and wake the driver. The item becomes the
+   * sole ordinary message of its own turn.
+   * @param message - identified prompt content and its producer provenance.
+   */
+  followup(message: UserMessage): void
+
+  /**
+   * Submit steering for the nearest step. An idle driver starts a turn;
+   * a running driver consumes it at its next step boundary.
+   * A rejected step leaves steering parked in the inbox until the next
+   * wake; cancellation or disposal may discard pending steering.
+   * @param message - identified steering content and its producer provenance.
+   */
+  steer(message: UserMessage): void
+
+  /**
+   * Queue model-facing context for the next pre-step without waking the
+   * driver. A running driver claims it at the nearest later step boundary;
+   * idle drivers leave it pending until follow-up or steering
+   * wakes them. It may miss a request whose pre-step already claimed its
+   * batch. Cancellation or disposal may discard pending context.
+   * @param message - identified injected context and its producer provenance.
+   */
+  inject(message: UserMessage): void
+}
+```
+
+```ts type-equiv
+/**
+ * An agent's lifecycle state, emitted on every transition as `agent/status`:
+ * `idle` means no driver is active; `running` begins when waking input starts
+ * cancellable pre-step processing and lasts while the driver drains,
+ * closes, or checkpoints turns. Disposal removes the agent from its registry;
+ * it is not a third observable status.
+ */
+type AgentStatus = 'idle' | 'running'
+```
+
+`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`followup()` 不返回句柄：其 `MessageId` 标识的是持久的 inbox 插入、认领与丢弃事实，而非之后的助手输出或轮次结束。`whenIdle()` 观察的是整个 agent，因此只有当调用方明确拥有从回执到空闲的这段区间时，才能把它称为一次 run（[决策](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。
+
+```ts type-equiv
+/** Merge-extensible agent creation options. Persona belongs to system-prompt sections. */
+interface AgentOptions {
+  /** Provider route (must have a registered adapter at call time). */
+  provider?: string
+  /** Model id interpreted by the selected provider adapter. */
+  model?: string
+  /** Maximum output tokens for each conversation-model request. */
+  maxTokens?: number
+}
+```
+
+在 `agent/request` 之后，分发要求 `provider` 与 `model` 都存在。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。agent 作用域的 `deployment:persona` 提示词段落可以遮蔽全局默认 persona。
+
+inbox 即投递词汇——agent 以持久投影形式拥有的两条有序待处理消息列表：
+
+```ts type-equiv
+/** One of the two ordered pending-message lists owned by an agent. */
+type InboxTarget = 'next-turn' | 'next-step'
+```
+
+每个待处理入队项就是其 `UserMessage`；`MessageId` 是唯一标识。`Inbox.append`、`prepend`、`replace`、`remove`、`clear`、`splice` 与 `claim` 会记录规范化的持久 `agent/inbox/spliced` 变更，并拒绝重复的待处理 id。`replace(messageId, newMessage)` 与 `remove(messageId)` 通过 `MessageId` 跨两份列表定位待处理消息；替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。普通删除和 `clear()` 都表示取消。`claim(target)` 通过无 outcome 的纯删除 splice 移除拟进入步骤的批次——全部 `next-step` 输入，外加轮次边界上的一条 `next-turn` 消息——且不发出 discarded 通知；循环另行逐条发出 claimed 通知。UI 投影等整体队列消费方通过持久 splice 重建 `nextTurn` 与 `nextStep`，而跟踪单条消息的消费方使用精确的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知。
+
+取消：
+
+```ts type-equiv
+/** Options for {@link Agent.cancel}. */
+interface CancelOptions {
+  /**
+   * Preserve queued and steering inbox items instead of discarding them. The
+   * active turn is still aborted, but un-started and pending work survives for a
+   * later turn and no canceled inbox splice is logged.
+   */
+  keepInbox?: boolean | undefined
+}
+```
+
+```ts type-equiv
+/** Why an active agent driver was cancelled. */
+type AgentCancelCause =
+  | { readonly kind: 'user' }
+  | { readonly kind: 'parent' }
+  | { readonly kind: 'hook'; readonly reason: string }
+  | { readonly kind: 'disposed' }
+```
+
+cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
+
+[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。
+
+<a id="initiating-agent"></a>
+
+## 发起 Agent
+
+`ctx.agents` 携带的进程本地 initiator 就是上面的确切 `Agent`，不是单独的 frame 或复制的标识。环境中存在该值既不能证明存活，也不代表授权；其生命周期与边界规则由 [initiator 作用域决策](../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)规定。
+
+## 拦截决策
+
+pre-step 决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。进入步骤的批次具有权威性，并保留每条消息的标识与 provenance。钩子桥接层把其原生决策字段映射到这一类型化结果上。
+
+源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
+
+`agent/pre-step` 接收一个 payload，携带独占的已领取批次（`messages`）、拟进入步骤的坐标（`turn`、`step`）与当前轮次的取消 `signal`。首次提案在已打开的轮次内、任何步骤开始前运行；工具 continuation 可以在步骤之间提交空的已领取批次：
+
+它返回 `PreStepDecision`。reject 不会打开步骤。enter 提供在 `step/start` 后追加的完整消息批次；最终决策省略的已领取消息保持已删除，而领取后插入的输入仍留待后续处理：
+
+```ts type-equiv
+/** Whether and with which messages the loop enters a proposed step. */
+type PreStepDecision =
+  | { kind: 'reject' }
+  | { kind: 'enter'; messages: UserMessage[] }
+```
+
+`agent/request-error` 在失败的模型步骤关闭之后、其轮次关闭之前运行。listener 可以在失败轮次的 signal 仍然存活时修复持久状态或 await 策略工作。处理该错误的 listener 返回 `{ kind: 'retry' }` 且不调用 `next()`；默认的 `undefined` 会让失败保持终态。
+
+```ts type-equiv
+/** Action returned by a listener that owns model-request recovery. */
+type RequestErrorAction = { kind: 'retry' } | undefined
+```
+
+`agent/pre-step` 是请求推导前唯一的串行边界。`agent/turn-stopping` 在轮次没有工具或 steering（中途引导）后续时运行，先于最后一次 steering 排空。
+
+`agent/session-start` 携带 `SessionStartSource`（会话生命周期为何开始；桥接层据此匹配其 SessionStart）：
+
+```ts type-equiv
+/** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */
+type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
+```
+
+## 会话
+
+`Session` 是一份类型化 `SessionEvent` 的**仅追加日志**——唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`），而非单独存储。每个条目携带单调的 `seq`、`time` 与按 `type` 判别的 `data` payload；surface 变体还额外携带 `sourceEventSeqs` provenance 与 `surfaceOp`。
+
+`SessionEvent` 信封的确切条件形状、十二种事件变体（`turn/start`、`turn/end`、`step/start`、`step/end`、`user/message`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`steering/message`、`todo/write`、`request/header`）、`deriveMessages()` 投影规则、`TurnTrigger`/`TurnEndReason` 原因以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。
+
+## `ToolDefinition`
+
+唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
+
+其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
+
+## 全仓通用类型模式
+
+两个模式在每个子系统中反复出现，只在此处记录一次。
+
+### `…Map → derived-union` 模式
 
 harness 中几乎所有可扩展的和类型都遵循同一形状：一个以判别标签为键的接口（`…Map`），联合类型由 `keyof` 派生。插件通过**声明合并**添加变体——无需修改拥有该类型的包（package）。
 
@@ -61,7 +299,7 @@ declare module '@deepseek-ai/dsh-llm' {
 
 <a id="branded-ids"></a>
 
-## 品牌化 ID
+### 品牌化 ID
 
 跨越包边界的 ID 都经过**品牌化**——结构上是字符串，但在类型层面不可互换（不能把 `SessionId` 传给需要 `CallId` 的位置）。每种类型通过各自的工厂构造；比较、日志记录和 JSON 行为与普通字符串相同。
 
@@ -76,351 +314,6 @@ type Branded<B extends string> = string & { readonly [BRAND]: B }
 
 两个核心 ID 是 `CallId`（关联工具调用及其结果；dsh-llm）和 `SessionId`（活跃 agent 与持久会话共享的标识；dsh-session）。能力包也会品牌化各自的 id，例如 [tasks.md](tasks.md) 中的 `TaskId`。
 
-## 会话
-
-`Session` 是一份类型化 `SessionEvent` 的**仅追加日志**——唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`），而非单独存储。事件词汇从 `SessionEventMap` 派生：
-
-源码：[`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
-
-```ts type-equiv
-/**
- * One immutable entry in the session log.
- *
- * A proper discriminated union over `type` (not independent `type`/`data`
- * unions), so `switch (event.type)` narrows `event.data` without casts.
- *
- * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
- * they only exist on {@link SurfaceEventType} variants (`user/message`,
- * `assistant/message`, `tool/result`, `steering/message`).
- * Non-surface events (boundary markers, chunks, usage, errors) never carry
- * surface metadata — the compiler enforces this at `Session.append()`
- * call sites.
- */
-type SessionEvent<T extends SessionEventType = SessionEventType> = {
-  [K in SessionEventType]: {
-    type: K
-    /** Monotonic sequence number within the session. */
-    seq: number
-    /** Unix epoch milliseconds. */
-    time: number
-    data: SessionEventMap[K]
-  } & (K extends SurfaceEventType ? {
-    /**
-     * Seq numbers of events that are provenance sources of this event
-     * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
-     * or the surface nodes shadowed by a compaction replace node). An
-     * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
-     */
-    sourceEventSeqs?: number[]
-    /** How this event entered the surface; absent for non-surface events. */
-    surfaceOp?: SurfaceOp
-  } : object)
-}[T]
-```
-
-十二种事件变体（`turn/start`、`turn/end`、`step/start`、`step/end`、`user/message`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`steering/message`、`todo/write`、`request/header`）、`deriveMessages()` 投影规则、`TurnTrigger`/`TurnEndReason` 原因以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。
-
-<a id="the-agent-handle"></a>
-
-## Agent 句柄
-
-`Agent` 是每个插件（UI、钩子、orchestrator）面向编程的 surface。具体实现为 dsh-agent-loop 包内部细节；循环外没有任何组件依赖它。
-
-源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
-
-```ts type-equiv
-/**
- * Which inbox queue a {@link Agent.send} item joins:
- * - `next-turn` — the item becomes its own turn, claimed at a turn boundary.
- * - `next-step` — during prompt admission or an open turn, the item stages for
- *   the next safe step boundary; otherwise it is promoted per its `wakeup`
- *   flag.
- */
-type SendTarget = 'next-turn' | 'next-step'
-```
-
-```ts type-equiv
-/** Resolved inbox placement reported when an accepted message is enqueued. */
-type InboxPlacement = 'queued' | 'steering'
-```
-
-`InboxItemId` 是为每次获准进入 FIFO 的项铸造的进程本地品牌字符串。它有意区别于 `MessageId`：同一条不可变消息发送两次，会创建两个可独立寻址的待处理项。
-
-```ts type-equiv
-/** One independently addressable accepted occurrence in an agent inbox. */
-interface InboxItem {
-  /** Agent-loop-minted occurrence identity. */
-  readonly id: InboxItemId
-  /** Identified message delivered by the caller. */
-  readonly message: UserMessage
-  /** Acceptance-time FIFO classification. */
-  readonly placement: InboxPlacement
-}
-```
-
-```ts type-equiv
-/** A user-requested mutation of one still-pending queued occurrence. */
-type InboxAction =
-  | { readonly kind: 'edit'; readonly content: ContentBlock[] }
-  | { readonly kind: 'remove' }
-  | { readonly kind: 'steer' }
-```
-
-```ts type-equiv
-/** Result of applying an inbox action at the synchronous ownership boundary. */
-type InboxActionResult = 'applied' | 'not-found' | 'steer-unavailable'
-```
-
-```ts type-equiv
-/**
- * Options for the unified {@link Agent.send} primitive over the
- * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
- * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
- * {@link Agent.inject} (`next-step`/no-wakeup).
- *
- * The object is complete so routing policy is explicit.
- */
-interface SendOptions {
-  /** Queue the item joins. */
-  target: SendTarget
-  /**
-   * Whether this item makes the model run: wake a parked driver (`next-turn`)
-   * or force a continuation step (`next-step` while running). A `false`
-   * `next-turn` item queues without waking; a `false`
-   * `next-step` item attaches durable context without forcing another step
-   * (the injection preset).
-   */
-  wakeup: boolean
-}
-```
-
-固定预设的别名方法自带 `target` 与 `wakeup`；其已有标识的 `UserMessage` 会携带角色、内容与 provenance。编辑替换内容或严格 steering（中途引导）转移不可变消息时，其 `MessageId` 都保持稳定。原 queued 单次入队项会结束，严格 steering 则接受一个具有不同 `InboxItemId` 的新 steering 单次入队项。注入绕过两个 FIFO，从不出现在 inbox 生命周期事件中。
-
-```ts type-equiv
-/** Options for {@link Agent.cancel}. */
-interface CancelOptions {
-  /**
-   * Preserve queued and steering inbox items instead of discarding them. The
-   * active turn is still aborted, but un-started and pending work survives for a
-   * later turn and no `agent/inbox/discard` fires.
-   */
-  keepInbox?: boolean
-}
-```
-
-`SteeringReceipt.outcome` 始终会解析。`admitted` 标识其不可变请求历史包含该确切消息的轮次与步骤；`rejected` 表示生命周期或终止策略先丢弃了该消息。同步输入校验仍会从 `steer()` 抛出异常。
-
-```ts type-equiv
-/** Stable runtime cause accepted by {@link Agent.cancel}. */
-type AgentCancelCause =
-  | { readonly kind: 'user' }
-  | { readonly kind: 'parent' }
-```
-
-`Agent` 是覆盖公开活跃 agent 契约的接口。具体驱动器拥有 `followup`/`steer`/`inject` 别名方法，并将它们经由 `send` 的（`target` × `wakeup`）矩阵路由。
-
-```ts type-equiv
-/**
- * Public live-agent handle with aliases over the unified delivery primitive.
- * @typert object
- */
-interface Agent {
-  /** The single identity shared with {@link session}. */
-  readonly id: SessionId
-  /** The provider route and model this agent's requests use. */
-  readonly options: AgentOptions
-  /** The live session this agent drives; its log is the durable source of truth. */
-  readonly session: Session
-  /** The current lifecycle state, mirrored on every `agent/status` transition. */
-  readonly status: AgentStatus
-  /**
-   * Whether a `next-step` send currently stages for prompt admission or the
-   * open turn. Unlike {@link status}, this excludes admission exit and turn
-   * settlement, when a waking `next-step` send becomes a queued follow-up.
-   */
-  readonly acceptsNextStep: boolean
-  /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
-  readonly ctx: Context
-
-  /**
-   * The unified delivery primitive over the (`target` × `wakeup`) matrix.
-   * It routes the caller's typed content and source as follows:
-   *
-   * - `next-turn` queues an item that becomes the sole ordinary message of its
-   *   own FIFO-ordered turn; `wakeup:true` wakes a
-   *   parked driver, while `wakeup:false` queues without waking.
-   * - `next-step` with `wakeup:true` stages steering during prompt admission
-   *   or an open turn; outside that window it falls back to a woken
-   *   `next-turn`.
-   * - `next-step` with `wakeup:false` injects durable model-facing context
-   *   without running the model: admission or an open turn stages it for the
-   *   next safe log position, while an injection outside that window appends
-   *   immediately without opening a turn. If admission closes without a turn,
-   *   a context-only boundary appends immediately; context staged beside
-   *   steering remains pending with it.
-   * The agent publishes or queues the identified frozen message as-is.
-   * @param message - identified model-facing content and its producer provenance.
-   * @param options - target queue and wakeup decision.
-   */
-  send(message: UserMessage, options: SendOptions): void
-
-  /**
-   * Reserve admission of the next ordinary turn while this agent is idle, so an
-   * operation can mutate durable history before any queued prompt derives a
-   * request from it. Already-accepted waking work has right of way, including a
-   * send whose wake is still a pending microtask. Later sends keep their
-   * ordinary placement, FIFO order, and `wakeup` facts, and
-   * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes
-   * a queued follow-up rather than steering; cancellation and disposal may
-   * still discard them. {@link inject} is not withheld. {@link whenIdle} treats
-   * a live reservation as activity, while lifecycle teardown does not await it.
-   * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work.
-   */
-  reserveTurnAdmission(): (() => void) | undefined
-
-  /**
-   * Mutate one still-pending queued occurrence synchronously. Editing preserves
-   * the message identity and queue position; removal publishes its terminal
-   * discard. Steer strictly transfers the message into the current next-step
-   * window, or returns `steer-unavailable` without changing the queued
-   * occurrence. Steering occurrences and driver-claimed items return
-   * `not-found`.
-   * @param id - independently addressable queued occurrence.
-   * @param action - edit, remove, or strict steer operation.
-   * @returns the applied outcome or the reason no mutation occurred.
-   */
-  updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult
-
-  /**
-   * Clear queued and steering work — unless `keepInbox` — and abort the active
-   * turn. An effective call first emits `agent/cancel-requested` with the
-   * resolved typed cause. The first cause wins for the active turn, and
-   * `whenIdle()` resolves after cancellation reaches quiescence. Idle
-   * cancellation is a no-op and does not arm later work.
-   * @param cause - the stable caller intent carried by the current turn signal.
-   * @param options - cancellation options; `keepInbox` preserves pending work.
-   */
-  cancel(cause: AgentCancelCause, options?: CancelOptions): void
-
-  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
-  whenIdle(): Promise<void>
-
-  /**
-   * Run one non-turn maintenance task from the true idle phase. The task starts
-   * synchronously after claiming that phase; later waking input remains in the
-   * inbox until the task settles, while public status stays `idle`.
-   * `whenIdle()` follows both the task and any waking work released behind it.
-   * @param task - operation whose fulfillment or rejection is preserved, with a signal aborted by {@link cancel}.
-   * @throws synchronously when turn-driving or another maintenance task already owns the agent.
-   * @returns the task promise.
-   */
-  runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>
-
-  /**
-   * Route identified input to an inbox boundary and optionally wake the driver.
-   * Waking input submitted after active cancellation is queued for the next
-   * turn and runs when the aborted activity converges to idle; a `disposed`
-   * cancel leaves it parked. A wake submitted while already idle always opens
-   * its turn boundary, even when its message is cleared before the driver
-   * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
-   * @param message - identified content and its producer provenance.
-   * @param target - the preferred next-turn or next-step inbox boundary.
-   * @param wakeup - whether delivery may wake the driver.
-   */
-  send(message: UserMessage, target: InboxTarget, wakeup: boolean): void
-
-  /**
-   * Queue an ordinary follow-up turn and wake the driver. The item becomes the
-   * sole ordinary message of its own turn.
-   * @param message - identified prompt content and its producer provenance.
-   */
-  followup(message: UserMessage): void
-
-  /**
-   * Submit steering with a message-owned admission receipt — the
-   * `next-step`/wakeup preset of {@link send}. During prompt admission or an
-   * open turn, the message waits in the steering FIFO until a committed step
-   * snapshots it; outside that window it enters the ordinary queued FIFO. The
-   * receipt resolves `admitted` only after the message joins that step's
-   * immutable request history, or `rejected` when terminal policy,
-   * cancellation, or disposal discards it first. A non-terminal turn close may
-   * leave it staged for a later admitted prompt without settling the receipt.
-   * @param message - identified steering content and its producer provenance.
-   * @returns the receipt for this exact message's eventual admission outcome.
-   */
-  steer(message: UserMessage): SteeringReceipt
-
-  /**
-   * Append model-facing context without running the model — the
-   * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn
-   * stages it at the next safe log position; outside that window it appends
-   * immediately without opening a turn. If admission closes without a turn,
-   * a context-only boundary appends immediately; context staged beside
-   * steering remains pending with it.
-   * @param message - identified injected context and its producer provenance.
-   */
-  inject(message: UserMessage): void
-}
-```
-
-`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。对于需要在把输入作为 steering 加入当前提示词准入／轮次，还是提交为一个新的待准入提示词之间做选择的调用方，`acceptsNextStep` 才是更窄且准确的路由判断条件。活动的轮次接纳预留与完全停稳相关，但不会改变 `status`，也不会把之后的队列项变成 steering；它的唯一权限是将驱动器的下一次认领延迟到释放时。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。
-
-cause 是由 TypeScript 强制约束的同进程输入。活跃的 `TurnCancellation` 持有者会把其判别字段复制到仅运行时的 `AbortSignal.reason`，并在发布 `turn/end` 前退役；冻结后的 `AbortSignal.reason` 仍可读取。只有 loop 会在结算时从自己机器私有的 signal 上读回 cause（`user`、`parent` 或仅用于生命周期的 `disposed`）——不存在公开的读取器，signal 也不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
-
-[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。
-
-## 发起 Agent
-
-`ctx.agents` 携带的进程本地 initiator 就是上面的确切 `Agent`，不是单独的 frame 或复制的标识。环境中存在该值既不能证明存活，也不代表授权；其生命周期与边界规则由 [initiator 作用域决策](../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)规定。
-
-## 拦截决策
-
-提示词决策与工具后决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。每个 `additionalContexts` 条目都会成为一条独立的 `user/message`，保留各自的标识与 provenance。钩子桥接层把其原生决策字段映射到这些类型化结果上。
-
-源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
-
-`agent/prompt-submit` 在轮次打开前返回 `PromptDecision`。allow 可以改写已领取的提示词或附加 `additionalContexts`；block 拒绝准入且不产生任何轮次事件：
-
-```ts type-equiv
-/**
- * Prompt interception result. `allow.content` replaces the prompt, while
- * `additionalContexts` appends model-facing context before the turn starts.
- * An `allow` returned by a listener is authoritative: a listener wrapping
- * `next()` preserves both fields unless it intentionally replaces them.
- */
-type PromptDecision =
-  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
-  | { kind: 'block'; reason: string }
-```
-
-`agent/request-error` 在失败的模型步骤关闭之后、其轮次关闭之前运行。listener 可以在失败轮次的 signal 仍然存活时修复持久状态或 await 策略工作。处理该错误的 listener 返回 `{ kind: 'retry' }` 且不调用 `next()`；默认的 `undefined` 会让失败保持终态。
-
-```ts type-equiv
-/** Action returned by a listener that owns model-request recovery. */
-type RequestErrorAction = { kind: 'retry' } | undefined
-```
-
-```ts type-equiv
-/** Model-request failure with an optional machine-routable provider code. */
-type RequestError = Error & { code?: string }
-```
-
-`agent/step` 是请求推导前唯一的串行边界。`agent/turn-stopping` 在轮次没有工具或 steering（中途引导）后续时运行，先于最后一次 steering 排空。
-
-`agent/session-start` 携带 `SessionStartSource`（会话生命周期为何开始；桥接层据此匹配其 SessionStart）：
-
-```ts type-equiv
-/** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */
-type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
-```
-
-## `ToolDefinition`
-
-唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
-
-其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
-
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
 <a id="cordis-surface"></a>
@@ -466,7 +359,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl
 
 Types: [SessionHeader](persistence.md)
 
-Source: [`packages/core/agent-loop/src/index.ts:252`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
 
 <a id="ctxagents--agentregistry"></a>
 
@@ -638,35 +531,12 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
 ### `agent/*` events
 
-<a id="agentcancel-requested--emit"></a>
-
-#### `agent/cancel-requested` — emit
-
-Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained.
-
-```ts cordis-catalog
-/**
- * Effective broad cancellation was requested, before queued/outbox work
- * is cleared or the active turn is aborted. This observe-only notification
- * cannot veto cancellation; listener failures are contained.
- * @param agent - the agent whose current work is being cancelled.
- * @param cause - the explicit typed cancellation cause.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, cause: AgentCancelCause): void
-```
-
-Types: [Scoped](scope.md)
-
-Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts)
-
 <a id="agentcreated--emit"></a>
 
 #### `agent/created` — emit
@@ -680,11 +550,11 @@ A fully configured agent and live session were published. Setup is composition-o
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
- * @param agent - the newly registered agent with its live session and completed setup.
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/created'(this: Scoped<Agent>, agent: Agent): void
+'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -702,11 +572,11 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
  * An agent left the registry; AgentLoop emits this after driver quiescence
  * and scoped-registration unwind, but before session detachment. Custom
  * registry users own their driver-ordering contract.
- * @param agent - the exact agent removed from the registry.
+ * @param payload.agent - the exact agent removed from the registry.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
+'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -717,138 +587,111 @@ Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/t
 
 #### `agent/error` — emit
 
-A step or turn errored. The machine reports a failure here (plus the logger) even when the error has no in-turn position for a durable record.
+A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
 
 ```ts cordis-catalog
 /**
- * A step or turn errored. The machine reports a failure here (plus the
- * logger) even when the error has no in-turn position for a durable record.
- * @param agent - the agent whose turn errored.
- * @param turn - the turn in which the failure surfaced.
- * @param step - the step at which the failure surfaced.
- * @param error - the failure, verbatim.
+ * A step or turn errored. The machine reports a failure here even when
+ * the error has no in-turn position for a durable record.
+ * @param payload.agent - the agent whose turn errored.
+ * @param payload.turn - the turn in which the failure surfaced.
+ * @param payload.step - the step at which the failure surfaced.
+ * @param payload.error - the failure, verbatim.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
+'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
 ```
 
 Types: [Scoped](scope.md)
 
 Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdequeue--emit"></a>
+<a id="agentinboxclaimed--emit"></a>
 
-#### `agent/inbox/dequeue` — emit
+#### `agent/inbox/claimed` — emit
 
-The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message.
+One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
 
 ```ts cordis-catalog
 /**
- * The driver claimed one item out of the inbox: a queued item at a turn
- * boundary, or steering drained between steps. Fires after the item leaves
- * its FIFO and before it becomes a durable message.
- * @param agent - the agent whose inbox item was claimed.
- * @param item - the exact claimed occurrence.
+ * One message left the inbox inside its open turn. If the proposed step
+ * is rejected, the claimed message ends here: it is neither discarded nor
+ * re-emitted as a user/message, and the turn closes without a step.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the claimed message.
+ * @param payload.turn - the owning turn.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxdiscard--emit"></a>
+<a id="agentinboxdiscarded--emit"></a>
 
-#### `agent/inbox/discard` — emit
+#### `agent/inbox/discarded` — emit
 
-Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item.
+One message was discarded from the live inbox.
 
 ```ts cordis-catalog
 /**
- * Pending inbox items were dropped without delivering them, so every
- * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
- * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,
- * emits this after `agent/cancel-requested` when applicable and before
- * aborting the active work. Fires once per drop with every dropped item.
- * @param agent - the agent whose inbox items were dropped.
- * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.
+ * One message was discarded from the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the discarded message.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItem[]): void
+'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxenqueue--emit"></a>
+<a id="agentinboxinserted--emit"></a>
 
-#### `agent/inbox/enqueue` — emit
+#### `agent/inbox/inserted` — emit
 
-An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state.
+One message entered the live inbox.
 
 ```ts cordis-catalog
 /**
- * An item entered the queued or steering inbox. `placement` is the
- * acceptance-time routing result; listeners must not reconstruct it from
- * later agent or session state.
- * @param agent - the owning agent.
- * @param item - accepted occurrence, message, and resolved placement.
+ * One message entered the live inbox.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the inserted message.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
+'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
-Types: [Scoped](scope.md)
+Types: [Scoped](scope.md) · [UserMessage](session.md)
 
 Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
 
-<a id="agentinboxupdate--emit"></a>
+<a id="agentpre-step--waterfall"></a>
 
-#### `agent/inbox/update` — emit
+#### `agent/pre-step` — waterfall
 
-A still-pending queued item changed content. The item id, placement, and position remain stable while the event carries the replacement message.
+Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
 
 ```ts cordis-catalog
 /**
- * A still-pending queued item changed content. The item id, placement, and
- * position remain stable while the event carries the replacement message.
- * @param agent - the owning agent.
- * @param item - the complete post-update occurrence.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @mode emit
- */
-'agent/inbox/update'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
-```
-
-Types: [Scoped](scope.md)
-
-Source: [`packages/core/agent/src/types.ts:321`](../../packages/core/agent/src/types.ts)
-
-<a id="agentprompt-submit--waterfall"></a>
-
-#### `agent/prompt-submit` — waterfall
-
-Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn.
-
-```ts cordis-catalog
-/**
- * Allow, rewrite, or block one claimed prompt before it becomes a user
- * message or opens a turn. Call `next()` for the unchanged default. The
- * signal controls only this admission attempt; listeners may cooperate with
- * it but must not retain it for a later attempt or turn.
- * @param agent - the agent whose turn claimed the message.
- * @param message - the frozen claimed message, including identity and source.
- * @param signal - the current turn's explicit abort signal.
+ * Reject a proposed step or replace the messages that enter it. Calling
+ * `next()` preserves the current messages.
+ * @param payload.agent - the agent proposing the step.
+ * @param payload.messages - messages removed from the inbox for this step.
+ * @param payload.turn - the turn that will own the step.
+ * @param payload.step - the step proposed by the loop.
+ * @param payload.signal - the current turn's cancellation signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
+'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
 ```
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
@@ -867,14 +710,14 @@ Replace the frozen call configuration. `await next()` yields the config the mach
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
  * content must use logged channels; this seam cannot mutate messages.
- * @param agent - the agent making the model call.
- * @param turn - the open turn number.
- * @param step - the step whose request this is.
- * @param signal - the current turn's explicit abort signal.
+ * @param payload.agent - the agent making the model call.
+ * @param payload.turn - the open turn number.
+ * @param payload.step - the step whose request this is.
+ * @param payload.signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
 */
-'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
 Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
@@ -885,28 +728,25 @@ Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/t
 
 #### `agent/request-error` — waterfall
 
-Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
+Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
 
 ```ts cordis-catalog
 /**
- * Handle a model-request failure after its failed step has closed but
- * before the failed turn closes. A listener returns `{ kind: 'retry' }`
- * without calling `next()` when it owns the error, or calls `next()` to
- * delegate. The default `undefined` leaves the failure terminal.
- * @param agent - the agent whose request failed.
- * @param turn - the open turn number.
- * @param step - the failed step number.
- * @param error - the original model-request failure.
- * @param failure - serializable facts normalized at the final adapter boundary.
- * @param priorFailures - immutable failures that already authorized another
- * retry turn in this consecutive sequence.
- * @param retryPolicy - immutable policy of the adapter registration that served
- * the failed request, or `undefined` if no final adapter served it.
- * @param signal - the turn abort signal.
+ * Handle one failed model-request attempt before the loop retries or closes
+ * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
+ * when it owns recovery, or calls `next()` to delegate. The default
+ * `undefined` leaves the failure terminal.
+ * @param payload.agent - the agent whose request failed.
+ * @param payload.turn - the turn containing the failed request.
+ * @param payload.step - the step containing the failed request attempt.
+ * @param payload.provider - the provider selected for the failed request.
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
+ * @param payload.signal - the turn abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
 ```
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
@@ -925,12 +765,12 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
  * `agent.inject()` to seed model-facing context. This is a notification, not
  * a veto; disposal requested by a lifecycle owner is rechecked before the
  * driver starts.
- * @param agent - the agent whose session lifecycle began.
- * @param source - why the session started (fresh startup, resume, …).
+ * @param payload.agent - the agent whose session lifecycle began.
+ * @param payload.source - why the session started (fresh startup, resume, …).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
+'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -941,18 +781,19 @@ Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/t
 
 #### `agent/status` — emit
 
-Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event.
+Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
 
 ```ts cordis-catalog
 /**
- * Agent status changed (`idle` ⇄ `running`). `send()` does not enter
- * `running` synchronously; drive lifecycle from this event.
- * @param agent - the agent whose status flipped.
- * @param status - the status just entered (the transition's destination).
+ * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
+ * `running` synchronously after reserving cancellation; `idle` means no
+ * driver remains scheduled or active.
+ * @param payload.agent - the agent whose status flipped.
+ * @param payload.status - the status just entered (the transition's destination).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
+'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
 ```
 
 Types: [Scoped](scope.md)
@@ -963,7 +804,7 @@ Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/t
 
 #### `agent/turn-stopping` — serial
 
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step.
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
 
 ```ts cordis-catalog
 /**
@@ -973,14 +814,17 @@ The turn is about to close: the model owes no response (no live tool calls, no f
  * re-reads its inbox: fresh steering runs another step, none closes the
  * turn. Data decides, so listener order cannot change the outcome. The
  * inverse control (stop a tool loop early) is data too: a tool result
- * carrying `concludesTurn` ends the turn at its step.
- * @param agent - the agent whose turn is at its stop boundary.
- * @param turn - the turn about to close.
- * @param signal - the current turn's explicit abort signal.
+ * carrying `concludesTurn` ends the turn at its step. The conclusion
+ * never short-circuits already-submitted next-step work: same-step
+ * `additionalContexts` or racing steering still runs, and the turn
+ * closes only when that inbox drains.
+ * @param payload.agent - the agent whose turn is at its stop boundary.
+ * @param payload.turn - the turn about to close.
+ * @param payload.signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode serial
  */
-'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
+'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
 ```
 
 Types: [Scoped](scope.md)
@@ -1003,12 +847,12 @@ A declarative agent entry failed before it could publish a live agent. Consumers
  * Consumers that buffer work for the configured identity use this
  * transient signal to reject that work instead of waiting forever. Normal
  * factory teardown suppresses failures from the cancelled startup attempt.
- * @param sessionId - exact shared agent/session identity that failed startup.
- * @param error - persistence, setup, or publication failure.
+ * @param payload.sessionId - exact shared agent/session identity that failed startup.
+ * @param payload.error - persistence, setup, or publication failure.
  * @mode emit
  */
-'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
+'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:157`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index 3674a95c44..572039f635 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/http-server.md
 http-server.md: b9795fe98b432b6ef5f7d01a4d3e115c809fe642
-http-server.zh.md: c3ba02dce5c58f491921f1fb31f999f9da808bc5
+http-server.zh.md: b84ea457bcd37eed361fde88fbf680d189aeebfb
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index c3ba02dce5..b84ea457bc 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -2,7 +2,7 @@
 
 [English](http-server.md) | 中文
 
-[dsh-host-webserver](../../packages/host/webserver) 是 GUI 宿主 web 形态的 HTTP 载体：单个提供 `ctx.httpServer` 的 `node:http` 插件，由具名路由注册表加 index.html 转换挂点组成，兜底是静态 dist 回退。它不属于 agent loop（智能体循环）主干，也不是能力 seam：它不了解任何 harness 概念，每个功能表面（`/api` 桥接、插件 bundle、HMR（热模块替换）事件流）都是由其他插件注册的一条路由（[分层说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)）。仅限 web（浏览器）形态：Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，不经过本服务器。
+[dsh-host-webserver](../../packages/host/webserver) 是 GUI 宿主 web 形态的 HTTP 载体：单个提供 `ctx.httpServer` 的 `node:http` 插件，由具名路由注册表、index.html 转换挂点与单一可认领的回退席位组成。它不属于 agent loop（智能体循环）主干，也不是能力 seam：它不了解任何 harness 概念，每个功能表面（`/api` 桥接、插件 bundle、HMR（热模块替换）事件流）都是由其他插件注册的一条路由（[分层说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)）。仅限 web（浏览器）形态：Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，不经过本服务器。
 
 源码：[`packages/host/webserver/src/index.ts`](../../packages/host/webserver/src/index.ts)
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index f6ce932ad9..f807656000 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: b3f850f4d07ad9e36d0e0db71dd9e0498e468767
-llm-streaming.zh.md: bb31c14b9bd0453399d83968b1062f67819caca3
+llm-streaming.md: c65416f449d1783f398cdd81b0d6987de83a6141
+llm-streaming.zh.md: ce79ecca53edf7213853df118489817451baa7b0
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index b3f850f4d0..c65416f449 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -72,12 +72,84 @@ Where a message came from is itself a merge-extensible sum type:
  */
 interface MessageSourceMap {
   user: { kind: 'user' }
-  plugin: { kind: 'plugin'; plugin: string }
+  plugin: { kind: 'plugin'; plugin: string } & ContextFormed
   model: ModelMessageSource
   tool: ToolMessageSource
 }
 ```
 
+Provenance and shape are two independent axes. `kind` answers *who produced this*; the optional `form` a producer mixes in answers *what shape of information it is*, so several producers may share one presentation and one producer may emit more than one shape over a session. The vocabulary is semantic and grows one value at a time; an absent or unrecognized value is the documented default, presented as opaque content:
+
+```ts type-equiv
+/**
+ * What SHAPE of information a producer-supplied context carries, declared by
+ * the producer beside its provenance.
+ *
+ * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
+ * of thing it is*, and the two axes are deliberately independent — several
+ * producers share one form (three snapshot producers today), and one producer
+ * may emit more than one form over a session.
+ *
+ * The vocabulary is SEMANTIC, never visual: a value states that the content is
+ * a file's instructions or a catalog of available items, and a consumer decides
+ * what that looks like. Colors, icons, ordering, and collapse defaults are the
+ * consumer's business and must not enter this union. It grows one value at a
+ * time as producers gain the structured fields their form needs; an absent or
+ * unknown value is the documented default, presented as opaque content.
+ */
+type ContextForm =
+  /** Instructions read out of workspace files the model is expected to follow. */
+  | 'instructions'
+  /** A catalog of items available in this session, republished as it changes. */
+  | 'catalog'
+  /** Current state, where a later snapshot from the same producer supersedes an earlier one. */
+  | 'snapshot'
+  /** A one-off account of something that just happened; it supersedes nothing. */
+  | 'notice'
+  /** A message another agent addressed to this one. */
+  | 'relay'
+  /** Material lifted out of another session's log, possibly reduced on the way in. */
+  | 'recall'
+```
+
+```ts type-equiv
+/** One named contribution to a `snapshot`-form context, in assembly order. */
+interface ContextSnapshotSection {
+  /** The contributing subsystem's name. */
+  readonly name: string
+  /** That contribution's model-facing text, exactly as assembled. */
+  readonly text: string
+}
+```
+
+```ts type-equiv
+/**
+ * Producer-declared {@link ContextForm} and the fields that form requires,
+ * mixed into the source shapes that carry one.
+ *
+ * Discriminated by `form` so a producer cannot declare a shape without the
+ * facts that shape is presented from: a `notice` must record its one-line
+ * account, a `snapshot` its sections. Omitting `form` stays valid — an
+ * undeclared context is the documented default.
+ */
+type ContextFormed =
+  | { readonly form?: never }
+  | { readonly form: 'instructions' }
+  | { readonly form: 'catalog' }
+  | {
+    readonly form: 'snapshot'
+    /** The named contributions this snapshot assembled, in order. */
+    readonly sections: readonly ContextSnapshotSection[]
+  }
+  | {
+    readonly form: 'notice'
+    /** One-line account of what happened, shown without expanding the row. */
+    readonly summary: string
+  }
+  | { readonly form: 'relay' }
+  | { readonly form: 'recall' }
+```
+
 ## `StreamChunk` — the raw protocol
 
 A streaming response interleaves several typed blocks (text, reasoning, multiple tool calls). `index` ties each delta to its block; `block-end` carries the fully-assembled `ContentBlock` so consumers don't have to re-assemble deltas themselves. It is a **closed** discriminated union — a `switch` over `type` ends with `assertNever`, so adding a variant breaks compilation at every consumer that must handle it.
@@ -87,8 +159,9 @@ A streaming response interleaves several typed blocks (text, reasoning, multiple
  * Raw streaming protocol emitted by adapters.
  * Block indexes correlate interleaved deltas, and `block-end` carries the
  * assembled block. Adapters emit usage before the terminal finish and nothing
- * afterward; tool arguments remain raw JSON strings. Failures either throw or
- * end with `error`/`aborted`, and consumers must handle both paths.
+ * afterward; tool arguments remain raw JSON strings. An adapter implementation
+ * may throw, but `LlmService.stream()` normalizes that failure to a terminal
+ * `error` or `aborted` finish before exposing it to consumers.
  */
 type StreamChunk =
   | { type: 'block-start'; index: number; blockType: ContentBlockType }
@@ -213,8 +286,9 @@ declare class BlockAssembler {
   push(chunk: StreamChunk): void;
   /**
    * Assemble all blocks seen so far, in stream order.
-   * @returns one block per seen index; an open block assembles from its
-   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
+   * @returns one block per seen index, except that max-token truncation drops
+   *   tool calls that cannot be executed safely; an open block assembles from
+   *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
    */
   blocks(): ContentBlock[];
   /** Usage from the `usage` chunk; undefined until one arrives. */
@@ -301,6 +375,15 @@ interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it — a gateway or self-hosted server it ships nothing about.
+   * Absent means the adapter draws no such distinction; false means it does
+   * and this route is one of its own. Only the adapter can answer: a stored
+   * profile is how a user-added route AND a corrected shipped one both look
+   * from outside.
+   */
+  declared?: boolean
 }
 ```
 
@@ -451,6 +534,55 @@ interface ToolSchema {
 
 The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` that produces it (schema + `execute`) is on [tools.md](tools.md).
 
+A provider a surface is still drafting has no route and no catalog, so interrogation is described separately: the request carries the draft the user is editing, and the reply is candidates a surface may adopt rather than a catalog it must serve.
+
+```ts type-equiv
+/**
+ * One interrogation of a provider endpoint that configuration has not stored
+ * yet. Configuration surfaces send the draft a user is still editing, so the
+ * request carries the endpoint and credential directly instead of naming a
+ * route: a provider being added has no route to name.
+ */
+interface LlmModelDiscoveryRequest {
+  /**
+   * Route the draft is editing, when it edits an existing one. A route whose
+   * adapter already knows its models answers from that knowledge instead of
+   * asking the endpoint — the adapter's own registry is the better answer, and
+   * it costs no network call.
+   */
+  provider?: string
+  /**
+   * Endpoint to interrogate. Optional because a route the adapter already
+   * describes needs none; a route it does not must supply one.
+   */
+  baseURL?: string
+  /** Wire protocol the endpoint speaks, when the draft names one. */
+  api?: string
+  /** Credential for this interrogation alone; the harness never stores it. */
+  apiKey?: string
+  /** Caller cancellation; implementations must settle promptly after it aborts. */
+  signal?: AbortSignal
+}
+```
+
+```ts type-equiv
+/**
+ * One model an endpoint reports about itself. Every field but the id is
+ * optional because most provider listings disclose an id and nothing else;
+ * a surface adopting one of these still owes the capacities its adapter needs.
+ */
+interface LlmDiscoveredModel {
+  /** Model id the endpoint accepts. */
+  id: string
+  /** Human-readable name when the endpoint supplies one. */
+  name?: string
+  /** Maximum combined request and response context, when disclosed. */
+  contextWindow?: number
+  /** Maximum output tokens, when disclosed. */
+  maxTokens?: number
+}
+```
+
 ### The request envelope: `LlmCallConfig` and the logged header
 
 The loop builds each request from logged state. `EpochHeader` records call config, adapter-default provenance, rendered prompt, and authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
@@ -498,6 +630,8 @@ interface LlmCallConfigAdapterDefaults {
 interface PreparedLlmCall {
   /** Detached, deep-frozen config with any adapter-owned default materialized. */
   readonly config: LlmCallConfig
+  /** Immutable retry policy captured with the adapter registration. */
+  readonly retryPolicy: ResolvedRetryPolicy
   /** Detached context metadata resolved with the registration-bound call. */
   readonly context?: LlmModelContext
   /** Config fields materialized by the captured adapter rather than proposed by the caller. */
@@ -603,9 +737,9 @@ listProviders(): LlmProviderInfo[]
  * entry, or a provider already declared by any registration throws
  * `LlmError` without registering the rest. Disposed with the fiber.
  * @param entries - every configurable provider this plugin owns.
- * @returns the disposer that withdraws all of them.
+ * @returns a handle that withdraws all of them, and can atomically replace them.
  */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () => void
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
 
 /**
  * List every declared configurable provider, registered or dormant.
@@ -613,6 +747,29 @@ registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () =
  */
 listConfigurableProviders(): LlmConfigurableProvider[]
 
+/**
+ * Offer to interrogate provider endpoints on behalf of the settings
+ * namespace this plugin owns. The namespace is the key because that is what
+ * a configuration surface already holds from the configurable-provider
+ * directory, and because a provider being *added* has no route to name yet.
+ * Disposed with the fiber.
+ * @param settingsNs - the namespace whose profiles this discovery serves.
+ * @param discover - interrogates one endpoint; must honor `request.signal`.
+ * @returns the disposer that withdraws the offer.
+ */
+registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
+
+/**
+ * Interrogate one provider endpoint for the models it advertises. The
+ * request describes a draft, not a stored route, so nothing here reads or
+ * writes settings or credentials — the caller owns both, and the reply is
+ * candidate metadata a surface may offer for adoption.
+ * @param settingsNs - namespace whose registered discovery serves this draft.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @returns the advertised models, deduplicated in endpoint order.
+ */
+async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
+
 /**
  * Resolve the retry policy captured when one provider route was registered.
  * @param provider - registered provider route to inspect.
@@ -662,22 +819,20 @@ async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<Ll
 async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
 
 /**
- * Stream one model call as raw chunks (token-level deltas). Throws
- * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
- * `options.provider`. Replay state is retained only when the same adapter
- * instance owns its historical provider and the target provider. Final
- * adapter selection remains fixed through asynchronous exact-model resolution
- * and dispatch. Selection, dispatch, and iteration failures retain their
- * original Error identity and are tagged in a call-local scope for narrow
- * agent-loop request recovery; middleware and nested-call failures remain
- * untagged for the outer call.
+ * Stream one model call as raw chunks (token-level deltas). Replay state is
+ * retained only when the same adapter instance owns its historical provider
+ * and the target provider. Final adapter selection remains fixed through
+ * asynchronous exact-model resolution and dispatch. Adapter selection,
+ * dispatch, and iteration failures become terminal `error` or `aborted`
+ * finish chunks; middleware, nested-call, cleanup, and consumer failures
+ * remain thrown.
  * @param options - the full request; `options.provider` selects the adapter.
  * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
  */
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Source: [`packages/llm/llm/src/index.ts:232`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
 
 <a id="llm-events"></a>
 
@@ -702,7 +857,7 @@ The provider topology changed: an adapter registered or unregistered routes, or
 'llm/adapters-updated'(): void
 ```
 
-Source: [`packages/llm/llm/src/index.ts:71`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
 
 <a id="llmstream--waterfall"></a>
 
@@ -726,5 +881,5 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Source: [`packages/llm/llm/src/index.ts:60`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index bb31c14b9b..ce79ecca53 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -72,12 +72,84 @@ interface Message {
  */
 interface MessageSourceMap {
   user: { kind: 'user' }
-  plugin: { kind: 'plugin'; plugin: string }
+  plugin: { kind: 'plugin'; plugin: string } & ContextFormed
   model: ModelMessageSource
   tool: ToolMessageSource
 }
 ```
 
+溯源与形态是相互独立的两根轴。`kind` 回答「由谁产生」；生产方可选混入的 `form` 回答「这是何种形态的信息」，因此多个生产方可以共用一种呈现，一个生产方在一次会话中也可以发出多种形态。该词汇表是语义的，逐个取值增长；未声明或无法识别的取值是有文档的默认，按不透明内容呈现：
+
+```ts type-equiv
+/**
+ * What SHAPE of information a producer-supplied context carries, declared by
+ * the producer beside its provenance.
+ *
+ * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
+ * of thing it is*, and the two axes are deliberately independent — several
+ * producers share one form (three snapshot producers today), and one producer
+ * may emit more than one form over a session.
+ *
+ * The vocabulary is SEMANTIC, never visual: a value states that the content is
+ * a file's instructions or a catalog of available items, and a consumer decides
+ * what that looks like. Colors, icons, ordering, and collapse defaults are the
+ * consumer's business and must not enter this union. It grows one value at a
+ * time as producers gain the structured fields their form needs; an absent or
+ * unknown value is the documented default, presented as opaque content.
+ */
+type ContextForm =
+  /** Instructions read out of workspace files the model is expected to follow. */
+  | 'instructions'
+  /** A catalog of items available in this session, republished as it changes. */
+  | 'catalog'
+  /** Current state, where a later snapshot from the same producer supersedes an earlier one. */
+  | 'snapshot'
+  /** A one-off account of something that just happened; it supersedes nothing. */
+  | 'notice'
+  /** A message another agent addressed to this one. */
+  | 'relay'
+  /** Material lifted out of another session's log, possibly reduced on the way in. */
+  | 'recall'
+```
+
+```ts type-equiv
+/** One named contribution to a `snapshot`-form context, in assembly order. */
+interface ContextSnapshotSection {
+  /** The contributing subsystem's name. */
+  readonly name: string
+  /** That contribution's model-facing text, exactly as assembled. */
+  readonly text: string
+}
+```
+
+```ts type-equiv
+/**
+ * Producer-declared {@link ContextForm} and the fields that form requires,
+ * mixed into the source shapes that carry one.
+ *
+ * Discriminated by `form` so a producer cannot declare a shape without the
+ * facts that shape is presented from: a `notice` must record its one-line
+ * account, a `snapshot` its sections. Omitting `form` stays valid — an
+ * undeclared context is the documented default.
+ */
+type ContextFormed =
+  | { readonly form?: never }
+  | { readonly form: 'instructions' }
+  | { readonly form: 'catalog' }
+  | {
+    readonly form: 'snapshot'
+    /** The named contributions this snapshot assembled, in order. */
+    readonly sections: readonly ContextSnapshotSection[]
+  }
+  | {
+    readonly form: 'notice'
+    /** One-line account of what happened, shown without expanding the row. */
+    readonly summary: string
+  }
+  | { readonly form: 'relay' }
+  | { readonly form: 'recall' }
+```
+
 <a id="streamchunk--the-raw-protocol"></a>
 
 ## `StreamChunk`：原始协议
@@ -89,8 +161,9 @@ interface MessageSourceMap {
  * Raw streaming protocol emitted by adapters.
  * Block indexes correlate interleaved deltas, and `block-end` carries the
  * assembled block. Adapters emit usage before the terminal finish and nothing
- * afterward; tool arguments remain raw JSON strings. Failures either throw or
- * end with `error`/`aborted`, and consumers must handle both paths.
+ * afterward; tool arguments remain raw JSON strings. An adapter implementation
+ * may throw, but `LlmService.stream()` normalizes that failure to a terminal
+ * `error` or `aborted` finish before exposing it to consumers.
  */
 type StreamChunk =
   | { type: 'block-start'; index: number; blockType: ContentBlockType }
@@ -221,8 +294,9 @@ declare class BlockAssembler {
   push(chunk: StreamChunk): void;
   /**
    * Assemble all blocks seen so far, in stream order.
-   * @returns one block per seen index; an open block assembles from its
-   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
+   * @returns one block per seen index, except that max-token truncation drops
+   *   tool calls that cannot be executed safely; an open block assembles from
+   *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
    */
   blocks(): ContentBlock[];
   /** Usage from the `usage` chunk; undefined until one arrives. */
@@ -309,6 +383,15 @@ interface LlmConfigurableProvider {
    * object; empty when the whole section is the profile.
    */
   settingsPath: readonly string[]
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it — a gateway or self-hosted server it ships nothing about.
+   * Absent means the adapter draws no such distinction; false means it does
+   * and this route is one of its own. Only the adapter can answer: a stored
+   * profile is how a user-added route AND a corrected shipped one both look
+   * from outside.
+   */
+  declared?: boolean
 }
 ```
 
@@ -459,6 +542,55 @@ interface ToolSchema {
 
 面向模型的 `ToolSchema` 是协议格式；产出它的已注册 `ToolDefinition`（schema + `execute`）在 [tools.md](tools.md) 中。
 
+界面正在起草的提供方既没有路由也没有 catalog，因此询问被单独描述：请求携带用户正在编辑的草稿，回复是界面可以采纳的候选，而不是它必须服务的 catalog。
+
+```ts type-equiv
+/**
+ * One interrogation of a provider endpoint that configuration has not stored
+ * yet. Configuration surfaces send the draft a user is still editing, so the
+ * request carries the endpoint and credential directly instead of naming a
+ * route: a provider being added has no route to name.
+ */
+interface LlmModelDiscoveryRequest {
+  /**
+   * Route the draft is editing, when it edits an existing one. A route whose
+   * adapter already knows its models answers from that knowledge instead of
+   * asking the endpoint — the adapter's own registry is the better answer, and
+   * it costs no network call.
+   */
+  provider?: string
+  /**
+   * Endpoint to interrogate. Optional because a route the adapter already
+   * describes needs none; a route it does not must supply one.
+   */
+  baseURL?: string
+  /** Wire protocol the endpoint speaks, when the draft names one. */
+  api?: string
+  /** Credential for this interrogation alone; the harness never stores it. */
+  apiKey?: string
+  /** Caller cancellation; implementations must settle promptly after it aborts. */
+  signal?: AbortSignal
+}
+```
+
+```ts type-equiv
+/**
+ * One model an endpoint reports about itself. Every field but the id is
+ * optional because most provider listings disclose an id and nothing else;
+ * a surface adopting one of these still owes the capacities its adapter needs.
+ */
+interface LlmDiscoveredModel {
+  /** Model id the endpoint accepts. */
+  id: string
+  /** Human-readable name when the endpoint supplies one. */
+  name?: string
+  /** Maximum combined request and response context, when disclosed. */
+  contextWindow?: number
+  /** Maximum output tokens, when disclosed. */
+  maxTokens?: number
+}
+```
+
 ### 请求信封：`LlmCallConfig` 与记录的 header
 
 循环从已记录状态构建每个请求。`EpochHeader` 通过完整的 `request/header` 快照记录调用配置、适配器默认值来源、渲染后的提示词以及权威返回工具顺序（由 `toolOrder` 配置；未配置时按字典序）。结合派生历史，请求便可由会话日志重建。见 [session.md](session.md#the-request-header-event-requestheader) 与[可重建性 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
@@ -506,6 +638,8 @@ interface LlmCallConfigAdapterDefaults {
 interface PreparedLlmCall {
   /** Detached, deep-frozen config with any adapter-owned default materialized. */
   readonly config: LlmCallConfig
+  /** Immutable retry policy captured with the adapter registration. */
+  readonly retryPolicy: ResolvedRetryPolicy
   /** Detached context metadata resolved with the registration-bound call. */
   readonly context?: LlmModelContext
   /** Config fields materialized by the captured adapter rather than proposed by the caller. */
@@ -611,9 +745,9 @@ listProviders(): LlmProviderInfo[]
  * entry, or a provider already declared by any registration throws
  * `LlmError` without registering the rest. Disposed with the fiber.
  * @param entries - every configurable provider this plugin owns.
- * @returns the disposer that withdraws all of them.
+ * @returns a handle that withdraws all of them, and can atomically replace them.
  */
-registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () => void
+registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle
 
 /**
  * List every declared configurable provider, registered or dormant.
@@ -621,6 +755,29 @@ registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): () =
  */
 listConfigurableProviders(): LlmConfigurableProvider[]
 
+/**
+ * Offer to interrogate provider endpoints on behalf of the settings
+ * namespace this plugin owns. The namespace is the key because that is what
+ * a configuration surface already holds from the configurable-provider
+ * directory, and because a provider being *added* has no route to name yet.
+ * Disposed with the fiber.
+ * @param settingsNs - the namespace whose profiles this discovery serves.
+ * @param discover - interrogates one endpoint; must honor `request.signal`.
+ * @returns the disposer that withdraws the offer.
+ */
+registerModelDiscovery( settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>, ): () => void
+
+/**
+ * Interrogate one provider endpoint for the models it advertises. The
+ * request describes a draft, not a stored route, so nothing here reads or
+ * writes settings or credentials — the caller owns both, and the reply is
+ * candidate metadata a surface may offer for adoption.
+ * @param settingsNs - namespace whose registered discovery serves this draft.
+ * @param request - the endpoint, protocol, and one-shot credential to use.
+ * @returns the advertised models, deduplicated in endpoint order.
+ */
+async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, ): Promise<LlmDiscoveredModel[]>
+
 /**
  * Resolve the retry policy captured when one provider route was registered.
  * @param provider - registered provider route to inspect.
@@ -670,22 +827,20 @@ async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<Ll
 async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>
 
 /**
- * Stream one model call as raw chunks (token-level deltas). Throws
- * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
- * `options.provider`. Replay state is retained only when the same adapter
- * instance owns its historical provider and the target provider. Final
- * adapter selection remains fixed through asynchronous exact-model resolution
- * and dispatch. Selection, dispatch, and iteration failures retain their
- * original Error identity and are tagged in a call-local scope for narrow
- * agent-loop request recovery; middleware and nested-call failures remain
- * untagged for the outer call.
+ * Stream one model call as raw chunks (token-level deltas). Replay state is
+ * retained only when the same adapter instance owns its historical provider
+ * and the target provider. Final adapter selection remains fixed through
+ * asynchronous exact-model resolution and dispatch. Adapter selection,
+ * dispatch, and iteration failures become terminal `error` or `aborted`
+ * finish chunks; middleware, nested-call, cleanup, and consumer failures
+ * remain thrown.
  * @param options - the full request; `options.provider` selects the adapter.
  * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
  */
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Source: [`packages/llm/llm/src/index.ts:232`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts)
 
 <a id="llm-events"></a>
 
@@ -710,7 +865,7 @@ The provider topology changed: an adapter registered or unregistered routes, or
 'llm/adapters-updated'(): void
 ```
 
-Source: [`packages/llm/llm/src/index.ts:71`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
 
 <a id="llmstream--waterfall"></a>
 
@@ -734,5 +889,5 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Source: [`packages/llm/llm/src/index.ts:60`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/permission.i18n.yaml b/docs/subsystems/permission.i18n.yaml
index 6f6ba3b3c3..3f9c9b533c 100644
--- a/docs/subsystems/permission.i18n.yaml
+++ b/docs/subsystems/permission.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 docs/subsystems/permission.md
-permission.md: 60ed88a79d0e51922f4cdffafa8b547669b49f5d
-permission.zh.md: c06714fc6a111f56af680c3dea1764c90f09998d
+permission.md: 6f9a37dbb784ccbaea74056519992e40f9c07c6d
+permission.zh.md: 8eda50fae09a67c41003d7a914fb139c4132a900
diff --git a/docs/subsystems/permission.md b/docs/subsystems/permission.md
index 60ed88a79d..6f9a37dbb7 100644
--- a/docs/subsystems/permission.md
+++ b/docs/subsystems/permission.md
@@ -125,7 +125,7 @@ optionOf(name: string): PresetOption
 set(session: Session, name: string): void
 ```
 
-Types: [Session](session.md) · [SessionEvent](core.md)
+Types: [Session](session.md) · [SessionEvent](session.md)
 
 Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/permission.zh.md b/docs/subsystems/permission.zh.md
index c06714fc6a..8eda50fae0 100644
--- a/docs/subsystems/permission.zh.md
+++ b/docs/subsystems/permission.zh.md
@@ -125,7 +125,7 @@ optionOf(name: string): PresetOption
 set(session: Session, name: string): void
 ```
 
-Types: [Session](session.md) · [SessionEvent](core.md)
+Types: [Session](session.md) · [SessionEvent](session.md)
 
 Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 808abb402a..295e5392ca 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: 1edf3c88fbabe55058bbf94ed8f31decf47cb84a
-persistence.zh.md: dbebd9ff819c8d50cfa9748678dac09c86adde6d
+persistence.md: 580ec250ebad3f2b51982f98a611268f26487321
+persistence.zh.md: 6676bf26e6eb0fb8f7dd9a94d17d4d70d1d1b271
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index 1edf3c88fb..580ec250eb 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -332,7 +332,7 @@ abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
 abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
 ```
 
-Types: [SessionEvent](core.md) · [SessionId](core.md)
+Types: [SessionEvent](session.md) · [SessionId](core.md)
 
 Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index dbebd9ff81..6676bf26e6 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -332,7 +332,7 @@ abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
 abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
 ```
 
-Types: [SessionEvent](core.md) · [SessionId](core.md)
+Types: [SessionEvent](session.md) · [SessionId](core.md)
 
 Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index 24b1c7b234..fc603d658d 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.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 docs/subsystems/session-projection.md
-session-projection.md: 56f9fb43dddc482264aab52ceeb9b9920df148cd
-session-projection.zh.md: 4a2310fed4af6f018af07b5f2b46d3c28aa361a4
+session-projection.md: 64351195028c62f623b32cbeb80c952795c1e9e6
+session-projection.zh.md: cf9036e6db3f82d84ffa3b8aa809c5617409659a
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
index 56f9fb43dd..6435119502 100644
--- a/docs/subsystems/session-projection.md
+++ b/docs/subsystems/session-projection.md
@@ -256,7 +256,7 @@ viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
 restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
 ```
 
-Types: [Session](session.md) · [SessionEvent](core.md)
+Types: [Session](session.md) · [SessionEvent](session.md)
 
 Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index 4a2310fed4..cf9036e6db 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -256,7 +256,7 @@ viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
 restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
 ```
 
-Types: [Session](session.md) · [SessionEvent](core.md)
+Types: [Session](session.md) · [SessionEvent](session.md)
 
 Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index a7e81056e5..2389cc806c 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 28b3f959b47a24373860c2334f9273286d072c95
-session.zh.md: 5870265f55892231700b65ac6ed69d827a0ab1ec
+session.md: 7735e90807f6fce1b3645096437b3e86189dc8ec
+session.zh.md: 09f34ac19c2f685bf5f8e5b11355b4c642c584d0
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 28b3f959b4..7735e90807 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -804,7 +804,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
 ```
 
-Types: [Scoped](scope.md) · [SessionEvent](core.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
 
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 5870265f55..09f34ac19c 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -808,7 +808,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
 ```
 
-Types: [Scoped](scope.md) · [SessionEvent](core.md)
+Types: [Scoped](scope.md)
 
 Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts)
 
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index a58335b9f1..994c04eaa5 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: c132c073459642b133e0d7e662ee98a8c9dfb694
-subagent.zh.md: e46f9aa98389842918ae37dda1477ef1b565e774
+subagent.md: 3bf3ac7c48bfa08be86314bb43263d4ee6198654
+subagent.zh.md: ddc3a715fbb6589dffc38f0e0c8b23bf35dddf6e
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index c132c07345..3bf3ac7c48 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -133,7 +133,7 @@ persisted Session
 | `waiting` | wake the same Activation |
 | no Activation | cold-resume a new Activation |
 
-`running` means the Agent has an active admission or turn, or waking inbox work; `waiting` means it is quiescent but still owns at least one child Activation that has not completed disposal; `settled` means quiescent with every owned child disposed, at which point the manager disposes the `AgentHandle` and removes the Activation. The manager derives these internal conditions from Agent quiescence and the owned-child set rather than maintaining a second execution state machine.
+`running` means the Agent has an active admission or turn, or waking inbox work; `waiting` means it is quiescent but still owns at least one child Activation that has not completed disposal; `settled` means quiescent with every owned child disposed, at which point the manager disposes the [`AgentHandle`](core.md#creation-and-ownership) and removes the Activation. The manager derives these internal conditions from Agent quiescence and the owned-child set rather than maintaining a second execution state machine.
 
 The Agent inbox is the only queue. Every continuation message becomes one `Agent.followup()` FIFO turn, so accepted messages have one observable order and a follow-up cannot redirect a turn already underway. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/enqueue`, `agent/inbox/dequeue`, and `agent/inbox/discard` events remain the message-lifecycle observations, and the continuation layer defines no subagent-specific delivery route.
 
@@ -432,7 +432,7 @@ Provider `start()` fulfills with a published run. The service mints a unique `ru
 The spawn and fork backends create an ordinary one-shot agent through `parent.ctx`, pass cancellation into core creation, and dispose through `AgentHandle`; a continuable child is instead created by the continuation manager through its own activation-owner scope. Provider removal blocks new starts without revoking accepted runs. Each child gets a new flat scope rather than inheriting parent registrations. Depth and fork seeding reuse existing agent and session vocabulary:
 
 - **Delegation depth** is durable `SessionHeader.delegationDepth` plus the merge-extensible runtime field `AgentOptions.subagentDepth`; absence means top-level depth zero, and the greater present value is authoritative. The seam owns both fields — the loop neither sets nor reads them — so an in-process child persists parent depth + 1, cold resume cannot lower it, and every start rejects a derived depth outside the safe-integer domain or above a defined absolute `request.maxDepth` cap.
-- **Fork seeding** uses `CreateAgentOptions.seed` (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/support/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
+- **Fork seeding** uses [`CreateAgentOptions.seed`](core.md#creation-and-ownership) (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/support/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index e46f9aa983..ddc3a715fb 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -133,7 +133,7 @@ persisted Session
 | `waiting` | 唤醒同一 Activation |
 | 无 Activation | 冷恢复一个新的 Activation |
 
-`running` 表示 Agent 拥有活跃的准入或轮次，或正在唤醒收件箱工作；`waiting` 表示它已停稳，但仍拥有至少一个尚未完成 dispose 的子 Activation；`settled` 表示已停稳且其拥有的每个子级都已 dispose，此时管理器会 dispose `AgentHandle` 并移除该 Activation。管理器根据 Agent 的完全停稳状态与其拥有的子级集合推导这些内部条件，而非维护第二套执行状态机。
+`running` 表示 Agent 拥有活跃的准入或轮次，或正在唤醒收件箱工作；`waiting` 表示它已停稳，但仍拥有至少一个尚未完成 dispose 的子 Activation；`settled` 表示已停稳且其拥有的每个子级都已 dispose，此时管理器会 dispose [`AgentHandle`](core.md#creation-and-ownership) 并移除该 Activation。管理器根据 Agent 的完全停稳状态与其拥有的子级集合推导这些内部条件，而非维护第二套执行状态机。
 
 Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `Agent.followup()` FIFO 轮次，因此已接受的消息共享同一个可观测顺序，且后续消息无法改变已在进行中的轮次。投递成功会返回被接受的 `MessageId`；既有的 `agent/inbox/enqueue`、`agent/inbox/dequeue` 与 `agent/inbox/discard` 事件仍是消息生命周期的观测点，继续执行层不定义任何 subagent 专属的投递路由。
 
@@ -434,7 +434,7 @@ interface SubagentProvider {
 spawn 和 fork 后端通过 `parent.ctx` 创建一个普通的单次 agent，将取消信号传入核心创建流程，并通过 `AgentHandle` 进行 dispose；而可继续子 agent 则由继续执行管理器通过其自己的 activation-owner 作用域创建。移除提供方会阻止新的 start，但不会撤销已接受的 run。每个子 agent 获得一个新的扁平作用域，而非继承父级注册。深度与 fork 种子注入复用既有的 agent 和会话词汇：
 
 - **委派深度**由持久 `SessionHeader.delegationDepth` 与可合并扩展的运行时字段 `AgentOptions.subagentDepth` 共同表示；缺失表示顶层深度为零，存在的较大值具有权威性。两个字段都归该 seam 所有——循环既不设置也不读取它们——因此进程内子 agent 会持久保存 parent 深度 + 1，冷恢复无法降低深度，而且每次 start 都会拒绝超出安全整数域、或高于已定义绝对 `request.maxDepth` 上限的派生深度。
-- **Fork 种子注入**使用 `CreateAgentOptions.seed`（一个 `SessionEvent[]` 前缀，经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递，与 `ctx.agents.resume()` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/support/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
+- **Fork 种子注入**使用 [`CreateAgentOptions.seed`](core.md#creation-and-ownership)（一个 `SessionEvent[]` 前缀，经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递，与 `ctx.agents.resume()` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/support/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 003e175399..21003bb796 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: b63014d1c2058c8fc7e96817d4bca858a1954482
-tools.zh.md: 2dc5802efce25a732a60c660191cd584ede623bb
+tools.md: 0551ee1c9dfa12b415c1f4575b5225f771cb53bc
+tools.zh.md: 50843b07f1d98b1c9d9222288b1273b34bee1e4a
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index b63014d1c2..0551ee1c9d 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -2,7 +2,7 @@
 
 English | [中文](tools.zh.md)
 
-The tool pipeline of [dsh-tools](../../packages/core/tools). [core.md](core.md) introduces `ToolDefinition` as the one pipeline-authoring type promoted to the spine and `ToolSchema` as the model-facing wire shape. This page owns the full `ToolDefinition`, the typed schema DSL that builds it, the guarded execution shapes, and the UI-presentation vocabulary.
+The tool pipeline of [dsh-tools](../../packages/core/tools). [core.md](core.md) introduces `ToolDefinition` as the one pipeline-authoring type promoted to the spine; the model-facing [`ToolSchema`](llm-streaming.md#the-model-request-and-result) wire shape is declared with the model request. This page owns the full `ToolDefinition`, the typed schema DSL that builds it, the guarded execution shapes, and the UI-presentation vocabulary.
 
 Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts) · [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)
 
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index 2dc5802efc..50843b07f1 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -2,7 +2,7 @@
 
 [English](tools.md) | 中文
 
-[dsh-tools](../../packages/core/tools) 的工具流水线。[core.md](core.md) 介绍了 `ToolDefinition`（唯一被提升到主干的流水线编写类型）和 `ToolSchema`（面向模型的协议格式（wire format）形状）。本页拥有完整的 `ToolDefinition`、用于构建它的类型化 schema DSL、受保护的执行形状，以及 UI 展示词汇。
+[dsh-tools](../../packages/core/tools) 的工具流水线。[core.md](core.md) 介绍了 `ToolDefinition`（唯一被提升到主干的流水线编写类型）；面向模型的 [`ToolSchema`](llm-streaming.md#the-model-request-and-result) 协议格式（wire format）形状与模型请求一起声明。本页拥有完整的 `ToolDefinition`、用于构建它的类型化 schema DSL、受保护的执行形状，以及 UI 展示词汇。
 
 源码：[`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts) · [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)
 
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
index 77539b60fb..f2321e732a 100644
--- a/packages/interaction/README.i18n.yaml
+++ b/packages/interaction/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/interaction/README.md
-README.md: 31a306cb08fe69297b0d0843b57b5e491c0bbe44
-README.zh.md: 6eafe8726ba59edd3a6bf739deacc037a9b56b76
+README.md: a72cd48bb1d3ec15b1116d576fac86619df59528
+README.zh.md: 170a557e40befaa0f7073f25e8a2b372958a6ec1
diff --git a/packages/interaction/README.md b/packages/interaction/README.md
index 31a306cb08..a72cd48bb1 100644
--- a/packages/interaction/README.md
+++ b/packages/interaction/README.md
@@ -14,4 +14,4 @@ The seams through which a human collaborates with a running agent — questions,
 
 These packages integrate through existing agent and session contracts rather than changing the loop. Interactive applications provide the concrete command, approval, and question adapters; automation uses [`acp/`](../acp/README.md), and runnable demo bundles live under [`examples/`](../examples/README.md). The product [`dsh`](../../apps/cli/README.md) CLI composes these packages directly.
 
-The subsystem references: [approval.md](../../docs/subsystems/approval.md), [permission.md](../../docs/subsystems/permission.md), [user-interaction.md](../../docs/subsystems/user-interaction.md), [commands.md](../../docs/subsystems/commands.md), and [tui.md](../../docs/subsystems/tui.md). The automation-only ACP transport is [`acp/`](../acp/README.md), the SDK's JSON-RPC server half [`scaffold/server`](../scaffold/README.md), and the shared bin boot glue [`boot/`](../boot/README.md).
+The subsystem references: [approval.md](../../docs/subsystems/approval.md), [permission.md](../../docs/subsystems/permission.md), [user-interaction.md](../../docs/subsystems/user-interaction.md), and [commands.md](../../docs/subsystems/commands.md). The automation-only ACP transport is [`acp/`](../acp/README.md), the SDK's JSON-RPC server half [`scaffold/server`](../scaffold/README.md), and the shared bin boot glue [`boot/`](../boot/README.md).
diff --git a/packages/interaction/README.zh.md b/packages/interaction/README.zh.md
index 6eafe8726b..170a557e40 100644
--- a/packages/interaction/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -14,4 +14,4 @@
 
 这些包通过现有的 agent（智能体）和会话契约集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
 
-子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)、[commands.md](../../docs/subsystems/commands.md) 与 [tui.md](../../docs/subsystems/tui.md)。仅自动化的 ACP 传输在 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半在 [`scaffold/server`](../scaffold/README.md)，共享 bin 启动胶水在 [`boot/`](../boot/README.md)。
+子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)与 [commands.md](../../docs/subsystems/commands.md)。仅自动化的 ACP 传输在 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半在 [`scaffold/server`](../scaffold/README.md)，共享 bin 启动胶水在 [`boot/`](../boot/README.md)。
diff --git a/packages/self-modification/README.i18n.yaml b/packages/self-modification/README.i18n.yaml
index 53bbf9cdbb..5a2f02826c 100644
--- a/packages/self-modification/README.i18n.yaml
+++ b/packages/self-modification/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/self-modification/README.md
 README.md: 53f700993cce8df8729fba5a92a9498fff2412cd
-README.zh.md: 90030cda33f47d128041b7619546ac1309b8465a
+README.zh.md: 18e03798b90e73f1d7e61ecf7010b8c472454a08
diff --git a/packages/self-modification/README.zh.md b/packages/self-modification/README.zh.md
index 90030cda33..18e03798b9 100644
--- a/packages/self-modification/README.zh.md
+++ b/packages/self-modification/README.zh.md
@@ -8,5 +8,3 @@ agent 修改自身运行时：检查已加载的插件与服务接口、挂载
 |---|---|---|
 | [`tool-cordis/`](tool-cordis/README.md) | `cordis_inspect`／`cordis_mount`／`cordis_unmount` 工具：读取当前进程运行时，并在一个自有分组 fiber 下管理内存中的临时插件 | 注册到 `ctx.tools` |
 | [`repository-plugin/`](repository-plugin/README.md) | 通过 DSH 自有子 Plugin 准备并挂载静态 repository skills 与通用 `.mcp.json` server | 注册一个 Loader builtin |
-
-工具契约见 [`tool-cordis/README.md`](tool-cordis/README.md) 与 [`repository-plugin/README.md`](repository-plugin/README.md)。
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 35fef7beaf..b053efe789 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -154,16 +154,17 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
 export const LINK_MAP: Readonly<Record<string, string>> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
+  AgentFactory: 'core.md',
+  AgentHandle: 'core.md',
   AgentOptions: 'core.md',
   AgentStatus: 'core.md',
   ContentBlock: 'llm-streaming.md',
-  ContinuationDecision: 'core.md',
-  ContinuationStop: 'core.md',
+  CreateAgentOptions: 'core.md',
   GenerateOptions: 'llm-streaming.md',
   InboxItem: 'core.md',
   InboxPlacement: 'core.md',
   MessageId: 'llm-streaming.md',
-  HookContext: 'core.md',
+  ResumeAgentOptions: 'core.md',
   SettleReason: 'core.md',
   AdapterRegistrationHandle: 'llm-streaming.md',
   DirectoryRegistrationHandle: 'llm-streaming.md',
@@ -188,7 +189,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   PreparedReferencedMessage: 'session-reference.md',
   SessionReferenceCandidate: 'session-reference.md',
   SessionReferenceInput: 'session-reference.md',
-  SessionEvent: 'core.md',
+  SessionEvent: 'session.md',
   SessionId: 'core.md',
   SessionStartSource: 'core.md',
   SessionLogSnapshot: 'session-query.md',
@@ -410,18 +411,15 @@ export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
 
 /** Project types deliberately documented outside the subsystems catalog. */
 export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
-  AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
   z: 'schemastery schema constructor is owned by vendor/schemastery (vendored upstream)',
   BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
   InsertReferenceRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
   ConsumeTokenRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
   InsertTextRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
-  AgentHandle: 'agent ownership handle is owned by packages/core/agent/README.md',
   BashEnvContributor: 'service-local extension type is owned by packages/bash/tool-bash/src/index.ts',
   BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
   ManualCompactAgentContext: 'manual compaction service input is owned by packages/compact/compact/src/index.ts',
-  CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
   DomainImpl: 'domain implementation contract is owned by packages/storage/storage-domain/README.md',
   CommandExecution: 'executor return contract is owned by packages/interaction/commands/src/index.ts',
   'z.core.JSONSchema.BaseSchema': 'zod projection output is owned by the zod v4 API',
@@ -437,7 +435,6 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   KnobState: 'projection unit state shape is owned by packages/interaction/permission/README.md',
   PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
-  ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
   Sandbox: 'external E2B SDK handle is owned by packages/e2b/e2b/README.md',
   SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
   SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 750b1935de..5d8f68f4cd 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -1,9 +1,9 @@
 /** Tests for the documentation website projection adapter. */
 
 import { execFileSync } from 'node:child_process'
-import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, globSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { basename, join, resolve } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { docsPages, type DocsPage } from '../website/docs.ts'
 import {
@@ -269,6 +269,19 @@ describe('docsPages locale routes', () => {
     }
   })
 
+  it('indexes every subsystem page in both sides of the folder README', () => {
+    const pages = globSync(join(repositoryRoot, 'docs/subsystems/*.md'))
+      .map(page => basename(page))
+      .filter(page => !page.endsWith('.zh.md') && page !== 'README.md')
+      .sort()
+    expect(pages.length).toBeGreaterThan(0)
+    for (const readme of ['README.md', 'README.zh.md']) {
+      const rows = readFileSync(join(repositoryRoot, 'docs/subsystems', readme), 'utf8')
+      const missing = pages.filter(page => !rows.includes(`| [${page}](${page}) |`))
+      expect(missing, `${readme} must carry one table row per subsystem page`).toEqual([])
+    }
+  })
+
   it('projects translated subsystem pages while retaining explicit English fallbacks', () => {
     const rootPages = docsPages.filter(page => (
       page.locale === 'root' && page.route.startsWith('reference/subsystems/')
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 3d1ca11612..137315cf39 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](subsystems/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [subsystems](subsystems/README.md) pages paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](subsystems/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index b3bf8eaec4..5f57b5167d 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -22,17 +22,17 @@
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ContextForm",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ContextSnapshotSection",
       "source": "packages/llm/llm/src/message.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "ContextFormed",
       "source": "packages/llm/llm/src/message.ts"
     },
@@ -57,12 +57,12 @@
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmModelDiscoveryRequest",
       "source": "packages/llm/llm/src/types.ts"
     },
     {
-      "doc": "docs/subsystems/core.md",
+      "doc": "docs/subsystems/llm-streaming.md",
       "symbol": "LlmDiscoveredModel",
       "source": "packages/llm/llm/src/types.ts"
     },
@@ -111,11 +111,6 @@
       "symbol": "LlmCallConfigAdapterDefaults",
       "source": "packages/llm/llm/src/call-config.ts"
     },
-    {
-      "doc": "docs/subsystems/core.md",
-      "symbol": "SessionEvent",
-      "source": "packages/core/session/src/types.ts"
-    },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "InboxTarget",
@@ -1689,6 +1684,21 @@
       "doc": "docs/subsystems/session-projection.md",
       "symbol": "ProjectionChangeListener",
       "source": "packages/session/session-projection/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/core.md",
+      "symbol": "AgentHandle",
+      "source": "packages/core/agent/src/index.ts"
+    },
+    {
+      "doc": "docs/subsystems/core.md",
+      "symbol": "AgentStatus",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/core.md",
+      "symbol": "AgentOptions",
+      "source": "packages/core/agent/src/types.ts"
     }
   ]
 }
diff --git a/website/docs.ts b/website/docs.ts
index 1f7fa316a5..3a31bf4baf 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -261,6 +261,7 @@ const subsystemsReference = pairedPages(([
   ['README.md', '子系统', 'Subsystems', 0],
   ['core.md', '核心', 'Core', 1],
   ['scope.md', '作用域', 'Scopes', 2],
+  ['typert.md', 'TypeRT', 'TypeRT', 39],
   ['session.md', '会话', 'Sessions', 3],
   ['session-query.md', '会话查询', 'Session query', 4],
   ['session-reference.md', '会话引用', 'Session references', 5],
@@ -293,7 +294,6 @@ const subsystemsReference = pairedPages(([
   ['workspace.md', '工作区', 'Workspaces', 32],
   ['http-server.md', 'HTTP 服务器', 'HTTP server', 33],
   ['client-modules.md', '客户端模块', 'Client modules', 34],
-  ['tui.md', 'TUI 扩展', 'TUI extensions', 35],
   ['invariants.md', '运行时不变式', 'Runtime invariants', 36],
   ['session-projection.md', '会话投影', 'Session projections', 37],
   ['telemetry.md', '遥测', 'Telemetry', 38],

From 0fb062d85e0854d7e4b6f925029699a9bcf1a303 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 02:39:12 +0800
Subject: [PATCH 421/516] feat(doc-gates): backstop every declared cordis
 event; deepen the Context scan to src/**

The rendering projection walks only files reachable from host-face package
exports, so client-face Events merges vanished silently (12 events) and the
services backstop's top-level glob missed 13 nested client Context keys.
Events now get the exact mirror of the service backstop (EVENT_WALK_EXEMPTIONS,
name-keyed because client events share scopes with rendered host events), both
scans read packages/*/*/src/**/*.ts, and the partition judgment is the pure
walkPartitionProblems() so every acceptance path is unit-provable.
---
 ...08-09-cordis-event-walk-backstop.i18n.yaml |   6 +
 .../2026-08-09-cordis-event-walk-backstop.md  |  38 ++++
 ...026-08-09-cordis-event-walk-backstop.zh.md |  38 ++++
 scripts/cordis-walk.ts                        |  27 ++-
 scripts/gen-cordis-catalog-partition.spec.ts  | 147 ++++++++++++++
 scripts/gen-cordis-catalog.ts                 | 188 ++++++++++++++----
 6 files changed, 401 insertions(+), 43 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
 create mode 100644 scripts/gen-cordis-catalog-partition.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml
new file mode 100644
index 0000000000..e968e7b54e
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.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/architecture/2026-08-09-cordis-event-walk-backstop.md
+2026-08-09-cordis-event-walk-backstop.md: 59aeb06149925dc93839df64145555f27257d7be
+2026-08-09-cordis-event-walk-backstop.zh.md: 4549e9d382e5ff17ddff30eafad8d6c7e66d61ed
diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
new file mode 100644
index 0000000000..59aeb06149
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
@@ -0,0 +1,38 @@
+# Agent Note: An independent Events backstop closes the cordis-surface exhaustiveness gap
+
+Status: implemented
+
+English | [中文](2026-08-09-cordis-event-walk-backstop.zh.md)
+
+## Problem
+
+`gen-cordis-catalog` renders every service and event the Typert host-face projection discovers, and fail-closed page maps (`SERVICE_PAGE`, `EVENT_SCOPE_PAGE`) guarantee each discovered key or scope lands on exactly one `docs/subsystems/` page. Discovery itself was only backstopped for services: an independent AST scan read every `declare module 'cordis'` Context merge and demanded each declared key be rendered or carry a named `SERVICE_WALK_EXEMPTIONS` reason.
+
+Events had no such backstop. The projection walks only files reachable from host-face package exports, so an `interface Events` merge in client-face code — or in any file the host analyzer cannot reach — vanished with no trace: 12 declared events (`slash/input-*`, `theme/change`, `locale/change`, and the client runtime's `*/changed` invalidation signals) were documented nowhere generated and nothing would ever notice a thirteenth. The services scan also globbed only `packages/*/*/src/*.ts`, so 13 client-face Context keys declared in nested files (`src/client/**`) were invisible to the very scan meant to prevent silent vanishing.
+
+## Decision
+
+Events get the exact mirror of the services backstop, and both scans read the full package source tree.
+
+`scripts/cordis-walk.ts` gains `eventNameList` (every member name of an `interface Events` merge, read from method and property members alike so a shape the projector would reject still enters the scan) and its merge-file prefilter matches the `declare module` heads instead of the literal text `interface Context`, so an Events-only merge file is not skipped. The scan glob in `gen-cordis-catalog` deepens from `packages/*/*/src/*.ts` to `packages/*/*/src/**/*.ts`.
+
+A new curated `EVENT_WALK_EXEMPTIONS` map names every declared event the projection cannot see, with the reason and the package README that owns its surface. Keys are full event names, not scopes: client-face events share scopes with rendered host events (`commands/changed` beside the host `commands/*` family), so a scope-level exemption would mask a host-face regression. The partition check is fail-closed in both directions, exactly like the service maps: an unexempted invisible event, an exemption for an event that renders, and an exemption no merge declares are all hard errors.
+
+The partition judgment moved out of `computeOutputs` into the pure `walkPartitionProblems(input, maps)` so every acceptance path is provable by unit test without running the Typert projection; `computeOutputs` feeds it the rendered model plus the independent scan and keeps aggregating page-splice errors as before.
+
+The audit that motivated this found the host face already complete: 48 rendered services + 10 walk exemptions covered all 58 host-visible Context keys, all 49 host events rendered, and every type name in every rendered signature is classified by the existing fail-closed `LINK_MAP`/`FOUNDATION_TYPE_NAMES`/`TYPE_LINK_EXEMPTIONS` check. The 25 findings (12 events, 13 keys) were all client-face; each now carries a named exemption pointing at its owning README, consistent with the existing `appShell`/`connection` precedent.
+
+## Verification
+
+`scripts/gen-cordis-catalog-partition.spec.ts` proves each acceptance path: the green partition, an invisible unexempted event (named with its declaring file), a stale rendered-event exemption, a stale never-declared exemption, the service mirror of each, unmapped rendered surface in both page maps, and the scan reaching a nested Events-only merge file. Deleting one live exemption from the real tree makes `gen-cordis-catalog` fail loud with the event's name and declaring file; restoring it returns the generator to a byte-identical no-op regeneration (85 artifacts, 0 written), which also proves the new exemptions exactly cover today's surface. `verify-cordis-catalog` in doc-sync executes the partition on every run.
+
+## Alternatives considered
+
+- **Render the client face instead of exempting it.** Analyzing `faces: ['host', 'client']` and giving client services/events generated regions is the real fix for the underlying blind spot, but it changes what the subsystems catalog IS (host-tier reference) and requires page decisions for browser-only surfaces; the existing `TODO(cordis-catalog-interface-services)` already tracks widening the projection. The backstop is the guarantee; rendering is an upgrade behind it.
+- **Scope-level event exemptions.** Smaller map, but `commands/changed` (client) shares the `commands` scope with rendered host events, so exempting a scope would swallow a future host-face event silently — the exact failure mode this note removes.
+- **Deriving exhaustiveness from Typert instead of a raw AST scan.** The projection and the backstop must fail independently: a Typert reachability bug is precisely what the backstop exists to catch, so the scan deliberately stays a plain `ts.createSourceFile` walk with no shared machinery.
+- **Gating the transitive type closure of rendered signatures.** Measured before deciding: every type name reachable in rendered signatures is already classified, and deeper field-of-field types are owned by the pages' hand-curated `type-equiv` pastes and package READMEs; a closure gate would force page homes for internals without a reader-facing need.
+
+## Consequences
+
+A new cordis event — host or client, any file depth — must either render onto a subsystems page or name itself in `EVENT_WALK_EXEMPTIONS` with its documentation owner; deleting one must retire its exemption. The same now holds for Context keys declared anywhere under `src/`. The curated maps grew by 25 client-face entries whose reasons all point at package READMEs, keeping the subsystems catalog a host-tier reference. `walkPartitionProblems` is the single home of the partition judgment; future backstop dimensions (e.g. rendering the client face, schema surfaces) extend it and its spec rather than re-inlining checks into `computeOutputs`.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
new file mode 100644
index 0000000000..4549e9d382
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
@@ -0,0 +1,38 @@
+# Agent Note（agent 决策记录）：独立的 Events 兜底扫描补上 cordis 表面完备性缺口
+
+Status: implemented
+
+[English](2026-08-09-cordis-event-walk-backstop.md) | 中文
+
+## Problem
+
+`gen-cordis-catalog` 渲染 Typert host face 投影发现的每个服务与事件，fail-closed 的页面映射（`SERVICE_PAGE`、`EVENT_SCOPE_PAGE`）保证每个被发现的 key 或 scope 恰好落在一个 `docs/subsystems/` 页面上。但"发现"本身此前只对服务有兜底：一条独立的 AST 扫描读取每个 `declare module 'cordis'` Context merge，要求每个声明的 key 要么被渲染、要么在 `SERVICE_WALK_EXEMPTIONS` 中给出具名理由。
+
+事件没有这样的兜底。投影只遍历从 host face 包导出可达的文件，因此 client face 代码——或 host 分析器无法触及的任何文件——里的 `interface Events` merge 会无声消失：12 个已声明事件（`slash/input-*`、`theme/change`、`locale/change`，以及 client runtime 的 `*/changed` 失效信号）不出现在任何生成文档中，而且再多一个也不会有任何机制察觉。服务扫描的 glob 也只有 `packages/*/*/src/*.ts`，于是声明在嵌套文件（`src/client/**`）中的 13 个 client face Context key 恰恰对这条为防止无声消失而存在的扫描不可见。
+
+## Decision
+
+事件获得与服务兜底完全对称的机制，且两条扫描都读取完整的包源码树。
+
+`scripts/cordis-walk.ts` 新增 `eventNameList`（`interface Events` merge 的每个成员名，方法与属性成员一并读取，使投影器会拒绝的形状也进入扫描），其 merge 文件预过滤改为匹配 `declare module` 头部而非字面文本 `interface Context`，从而不再跳过只含 Events 的 merge 文件。`gen-cordis-catalog` 的扫描 glob 从 `packages/*/*/src/*.ts` 加深为 `packages/*/*/src/**/*.ts`。
+
+新的人工维护映射 `EVENT_WALK_EXEMPTIONS` 为投影看不到的每个已声明事件命名，附理由与拥有其表面的包 README。键是完整事件名而非 scope：client face 事件与已渲染的 host 事件共享 scope（`commands/changed` 与 host 的 `commands/*` 家族并存），scope 级豁免会无声吞掉未来的 host face 回归。分区检查与服务映射一样双向 fail-closed：未豁免的不可见事件、已渲染事件的豁免、无任何 merge 声明的豁免，皆为硬错误。
+
+分区判定从 `computeOutputs` 中提取为纯函数 `walkPartitionProblems(input, maps)`，使每条验收路径都能以单元测试证明而无需运行 Typert 投影；`computeOutputs` 向它馈送渲染模型加独立扫描结果，页面拼接错误的聚合方式保持不变。
+
+促成本决定的审计发现 host face 本已完备：48 个渲染服务 + 10 条 walk 豁免覆盖全部 58 个 host 可见 Context key，49 个 host 事件全部渲染，且每个渲染签名中的每个类型名都已被既有的 fail-closed `LINK_MAP`/`FOUNDATION_TYPE_NAMES`/`TYPE_LINK_EXEMPTIONS` 检查分类。25 条发现（12 事件、13 key）全部在 client face；现在每条都带指向其所属 README 的具名豁免，与既有的 `appShell`/`connection` 先例一致。
+
+## Verification
+
+`scripts/gen-cordis-catalog-partition.spec.ts` 证明每条验收路径：绿色分区、不可见且未豁免的事件（报出声明文件）、已渲染事件的陈旧豁免、从未声明的陈旧豁免、服务侧的对称路径、两个页面映射中未映射的已渲染表面，以及扫描触达嵌套的仅含 Events 的 merge 文件。在真实源码树上删除一条现役豁免会让 `gen-cordis-catalog` 以事件名与声明文件大声失败；恢复后生成器回到字节相同的 no-op 再生成（85 个 artifact，0 写入），这同时证明新豁免恰好覆盖当下表面。doc-sync 中的 `verify-cordis-catalog` 每次运行都会执行该分区检查。
+
+## Alternatives considered
+
+- **渲染 client face 而非豁免。** 以 `faces: ['host', 'client']` 分析并给 client 服务/事件生成区块才是对盲区的根治，但它改变子系统目录的定位（host 层参考），并要求为纯浏览器表面做页面归属决策；既有的 `TODO(cordis-catalog-interface-services)` 已跟踪拓宽投影。兜底是保证，渲染是其上的升级。
+- **scope 级事件豁免。** 映射更小，但 `commands/changed`（client）与已渲染的 host 事件共享 `commands` scope，豁免整个 scope 会无声吞掉未来的 host face 事件——正是本决定要消除的失败模式。
+- **用 Typert 推导完备性而非原始 AST 扫描。** 投影与兜底必须独立失败：Typert 的可达性 bug 恰是兜底要捕获的对象，因此扫描刻意保持为不共享机制的朴素 `ts.createSourceFile` 遍历。
+- **对渲染签名的传递类型闭包设门。** 决定前先测量：渲染签名中可达的每个类型名都已分类，更深的字段套字段类型由页面手工维护的 `type-equiv` 粘贴与包 README 拥有；闭包门会在没有读者需求的情况下强迫内部类型认领页面。
+
+## Consequences
+
+新的 cordis 事件——host 或 client、任意文件深度——必须渲染到某个子系统页面，或在 `EVENT_WALK_EXEMPTIONS` 中以其文档所有者具名；删除事件时必须一并退役其豁免。声明在 `src/` 下任意位置的 Context key 现在同样如此。人工维护映射增加了 25 条 client face 条目，理由全部指向包 README，使子系统目录保持 host 层参考的定位。`walkPartitionProblems` 是分区判定的唯一居所；未来的兜底维度（如渲染 client face、schema 表面）应扩展它及其 spec，而非把检查重新内联进 `computeOutputs`。
diff --git a/scripts/cordis-walk.ts b/scripts/cordis-walk.ts
index 0111d1d042..a7c22bea02 100644
--- a/scripts/cordis-walk.ts
+++ b/scripts/cordis-walk.ts
@@ -11,7 +11,7 @@ import ts from 'typescript'
 
 /**
  * Parse every file matching `pattern` (repo-relative, sorted, `/`-normalized)
- * that textually mentions `interface Context`, yielding each file's cordis
+ * that textually contains a cordis module merge, yielding each file's
  * module-merge body. Files without a merge are skipped.
  * @param scanRoot - Repository root the pattern is resolved against.
  * @param pattern - Glob selecting the TypeScript files to scan.
@@ -25,7 +25,7 @@ export function contextMergeFiles(
   for (const rel of globSync(pattern, { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
-    if (!text.includes('interface Context')) continue
+    if (!text.includes("declare module 'cordis'") && !text.includes("declare module './context.ts'")) continue
     const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
     const body = cordisModuleBody(sf)
     if (!body) continue
@@ -64,3 +64,26 @@ export function contextKeyMap(body: ts.ModuleBlock, sf: ts.SourceFile): Map<stri
   }
   return keyToType
 }
+
+/**
+ * Every event name a `declare module 'cordis'` Events merge declares in one
+ * module body. Names are the literal member keys (`'agent/created'`), read
+ * from method and property members alike so a declaration shape the projector
+ * would reject still enters the exhaustiveness scan.
+ * @param body - The cordis module augmentation block.
+ * @param sf - Owning source file (for computed-name text extraction).
+ * @returns Declared event names, in declaration order.
+ */
+export function eventNameList(body: ts.ModuleBlock, sf: ts.SourceFile): string[] {
+  const names: string[] = []
+  for (const stmt of body.statements) {
+    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Events') continue
+    for (const member of stmt.members) {
+      if (!member.name) continue
+      names.push(ts.isStringLiteral(member.name) || ts.isIdentifier(member.name)
+        ? member.name.text
+        : member.name.getText(sf))
+    }
+  }
+  return names
+}
diff --git a/scripts/gen-cordis-catalog-partition.spec.ts b/scripts/gen-cordis-catalog-partition.spec.ts
new file mode 100644
index 0000000000..7de64fffde
--- /dev/null
+++ b/scripts/gen-cordis-catalog-partition.spec.ts
@@ -0,0 +1,147 @@
+/**
+ * Acceptance-path coverage for the cordis-surface partition backstops
+ * (`walkPartitionProblems` + the AST scan helpers): a declared Context key or
+ * Events member the rendering projection cannot see must carry a named walk
+ * exemption, an exemption must stay live in both directions, and the scan
+ * itself must reach nested (`src/**`) and Events-only merge files.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import ts from 'typescript'
+import { contextKeyMap, contextMergeFiles, eventNameList } from './cordis-walk.ts'
+import { walkPartitionProblems } from './gen-cordis-catalog.ts'
+import type { WalkPartitionInput, WalkPartitionMaps } from './gen-cordis-catalog.ts'
+
+const roots: string[] = []
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+/** A consistent baseline the red cases mutate one facet at a time. */
+function baseline(): { input: WalkPartitionInput; maps: WalkPartitionMaps } {
+  return {
+    input: {
+      renderedKeys: new Map([['llm', 'packages/llm/llm/src/index.ts:10']]),
+      renderedScopes: new Set(['llm']),
+      renderedEventNames: new Set(['llm/request']),
+      declaredKeys: new Map([
+        ['llm', 'packages/llm/llm/src/index.ts'],
+        ['theme', 'packages/client/ui-theme/src/client/index.ts'],
+      ]),
+      declaredEvents: new Map([
+        ['llm/request', 'packages/llm/llm/src/index.ts'],
+        ['theme/change', 'packages/client/ui-theme/src/client/index.ts'],
+      ]),
+    },
+    maps: {
+      servicePage: { llm: 'llm-streaming.md' },
+      serviceWalkExemptions: { theme: 'client-side — packages/client/ui-theme/README.md owns the surface' },
+      eventScopePage: { llm: 'llm-streaming.md' },
+      eventWalkExemptions: { 'theme/change': 'client-face — packages/client/ui-theme/README.md owns the surface' },
+    },
+  }
+}
+
+describe('walkPartitionProblems', () => {
+  it('accepts a partition where every declared key and event is rendered or exempted', () => {
+    const { input, maps } = baseline()
+    expect(walkPartitionProblems(input, maps)).toEqual([])
+  })
+
+  it('rejects a declared event that is neither rendered nor exempted, naming its file', () => {
+    const { input, maps } = baseline()
+    const problems = walkPartitionProblems(input, { ...maps, eventWalkExemptions: {} })
+    expect(problems).toEqual([
+      expect.stringContaining("event 'theme/change' (packages/client/ui-theme/src/client/index.ts) is declared in an Events merge but invisible"),
+    ])
+  })
+
+  it('rejects an event exemption whose event the projection renders', () => {
+    const { input, maps } = baseline()
+    const rendered = { ...input, renderedEventNames: new Set(['llm/request', 'theme/change']) }
+    expect(walkPartitionProblems(rendered, maps)).toEqual([
+      expect.stringContaining("event 'theme/change' is rendered by the projection but still listed in EVENT_WALK_EXEMPTIONS"),
+    ])
+  })
+
+  it('rejects an event exemption no Events merge declares', () => {
+    const { input, maps } = baseline()
+    const stale = { ...maps, eventWalkExemptions: { ...maps.eventWalkExemptions, 'gone/away': 'nothing owns this' } }
+    expect(walkPartitionProblems(input, stale)).toEqual([
+      expect.stringContaining("EVENT_WALK_EXEMPTIONS names 'gone/away' but no Events merge declares it"),
+    ])
+  })
+
+  it('rejects a declared Context key that is neither rendered nor exempted', () => {
+    const { input, maps } = baseline()
+    const problems = walkPartitionProblems(input, { ...maps, serviceWalkExemptions: {} })
+    expect(problems).toEqual([
+      expect.stringContaining('ctx.theme (packages/client/ui-theme/src/client/index.ts) is declared in a Context merge but invisible'),
+    ])
+  })
+
+  it('rejects an unmapped rendered service with its source pointer, and stale page maps both ways', () => {
+    const { input, maps } = baseline()
+    const problems = walkPartitionProblems(input, {
+      ...maps,
+      servicePage: { ghost: 'core.md' },
+      eventScopePage: { specter: 'core.md' },
+    })
+    expect(problems).toEqual(expect.arrayContaining([
+      expect.stringContaining('service ctx.llm (packages/llm/llm/src/index.ts:10) has no SERVICE_PAGE entry'),
+      expect.stringContaining("event scope 'llm/*' has no EVENT_SCOPE_PAGE entry"),
+      expect.stringContaining("SERVICE_PAGE maps 'ctx.ghost' but the projection discovers no such service"),
+      expect.stringContaining("EVENT_SCOPE_PAGE maps 'specter/*' but the projection discovers no such scope"),
+    ]))
+    expect(problems).toHaveLength(4)
+  })
+})
+
+describe('cordis-walk scan reach', () => {
+  it('finds Context keys and Events names in nested Events-only merge files', () => {
+    const root = mkdtempSync(join(tmpdir(), 'cordis-walk-'))
+    roots.push(root)
+    const dir = join(root, 'packages/client/ui-x/src/client')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, 'index.ts'), [
+      "declare module 'cordis' {",
+      '  interface Events {',
+      "    'x/changed'(): void",
+      '  }',
+      '}',
+      'export {}',
+      '',
+    ].join('\n'))
+    const merges = contextMergeFiles(root, 'packages/*/*/src/**/*.ts')
+    expect(merges.map(m => m.rel)).toEqual(['packages/client/ui-x/src/client/index.ts'])
+    const only = merges[0]
+    if (!only) throw new Error('scan returned no merge')
+    expect(eventNameList(only.body, only.sf)).toEqual(['x/changed'])
+    expect([...contextKeyMap(only.body, only.sf).keys()]).toEqual([])
+  })
+
+  it('reads string-literal and identifier member names from an Events merge', () => {
+    const sf = ts.createSourceFile('x.ts', [
+      "declare module 'cordis' {",
+      '  interface Events {',
+      "    'scope/list'(items: string[]): void",
+      '    plain(): void',
+      '  }',
+      '  interface Context {',
+      '    thing: ThingService',
+      '  }',
+      '}',
+      '',
+    ].join('\n'), ts.ScriptTarget.Latest, true)
+    const body = sf.statements[0] && ts.isModuleDeclaration(sf.statements[0]) && sf.statements[0].body
+      && ts.isModuleBlock(sf.statements[0].body)
+      ? sf.statements[0].body
+      : null
+    if (!body) throw new Error('fixture did not parse to a module block')
+    expect(eventNameList(body, sf)).toEqual(['scope/list', 'plain'])
+    expect([...contextKeyMap(body, sf)]).toEqual([['thing', 'ThingService']])
+  })
+})
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index b053efe789..ef2b6c0ed5 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -21,7 +21,7 @@ import {
 } from '@deepseek-ai/dsh-typert-generator'
 import type { CordisCatalogPolicy } from '@deepseek-ai/dsh-typert-generator'
 import { renderCordisCoreApiPages } from './cordis-core-api.ts'
-import { contextKeyMap, contextMergeFiles } from './cordis-walk.ts'
+import { contextKeyMap, contextMergeFiles, eventNameList } from './cordis-walk.ts'
 import {
   blobHash,
   parsePairMeta,
@@ -97,10 +97,11 @@ export const SERVICE_PAGE: Record<string, string> = {
  * Context keys declared in `interface Context` merges that the rendering
  * projection cannot see, each with the reason and its documentation owner.
  * The scan that enforces this list reads EVERY `declare module 'cordis'`
- * Context merge under `packages/x/x/src/*.ts` — not only root `index.ts`
- * files with a same-named service class — so a new service can never silently
- * join this blind spot: it either enters {@link SERVICE_PAGE} or names itself
- * here.
+ * Context merge under `packages/x/x/src/**` — any depth, not only root
+ * `index.ts` files with a same-named service class — so a new service can
+ * never silently join this blind spot: it either enters {@link SERVICE_PAGE}
+ * or names itself here. Client-face keys (the projection analyzes the host
+ * face only) name the package README that owns their surface.
  * TODO(cordis-catalog-interface-services): the interface-typed and
  * non-index-declared entries would all render once the projection resolves a
  * Context key through its declaring file's imports to the class declaration.
@@ -116,14 +117,27 @@ export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
   apiProxy: 'interface-typed (ApiProxy) with the class in api-proxy.ts, not index.ts — packages/host/apiproxy/README.md owns the surface',
   appShell: 'client-side interface-typed browser service — packages/client/web/README.md owns the surface',
   connection: 'client-side interface-typed browser service — packages/client/connection/README.md owns the surface',
+  chatFileMentions: 'client-side slot-contract accessor (ChatFileMentions) — packages/client/ui-conversation/README.md owns the surface',
+  command: 'client-side interface-typed browser service — packages/client/ui-command/README.md owns the surface',
+  conversation: 'client-side interface-typed browser service — packages/client/ui-conversation/README.md owns the surface',
+  layout: 'client-side interface-typed browser service — packages/client/ui-layout/README.md owns the surface',
+  locale: 'client-side interface-typed browser service — packages/client/locale/README.md owns the surface',
+  models: 'client-side interface-typed browser service — packages/client/ui-model/README.md owns the surface',
+  modules: 'client-side interface-typed browser service — packages/client/modules/README.md owns the surface',
+  remote: 'client-side interface-typed gateway accessor (ClientRemote) — packages/api/gateway/README.md owns the surface',
+  sessionHistory: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
+  slash: 'client-side interface-typed browser service — packages/client/ui-slash/README.md owns the surface',
+  slots: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
+  theme: 'client-side interface-typed browser service — packages/client/ui-theme/README.md owns the surface',
+  workspaces: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
 }
 
 /**
  * The owning subsystems page for every harness event scope (the segment
- * before the first `/`). Fail-closed exactly like {@link SERVICE_PAGE}.
- * `slash` lives with the human-command surface: the client slash-input
- * protocol parses toward command invocation and `dsh-ui-slash` owns the
- * declarations, but commands.md owns the cross-package command story.
+ * before the first `/`) the projection renders. Fail-closed exactly like
+ * {@link SERVICE_PAGE}. Client-face events (`slash/*`, `theme/change`, …) are
+ * invisible to the host-face projection and therefore never reach this map;
+ * {@link EVENT_WALK_EXEMPTIONS} names each one with its documentation owner.
  */
 export const EVENT_SCOPE_PAGE: Record<string, string> = {
   'agent': 'core.md',
@@ -145,6 +159,32 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
   'workflow': 'workflow.md',
 }
 
+/**
+ * Event names declared in `interface Events` merges that the rendering
+ * projection cannot see, each with the reason and its documentation owner.
+ * The mirror of {@link SERVICE_WALK_EXEMPTIONS} for events: an independent
+ * scan reads EVERY `declare module 'cordis'` Events merge under
+ * `packages/x/x/src/**`, so a declared event either renders onto a subsystems
+ * page (via {@link EVENT_SCOPE_PAGE}) or names itself here — never vanishes
+ * silently. Keys are full event names, not scopes: client-face events share
+ * scopes with rendered host events (`commands/changed` beside `commands/*`),
+ * so a scope-level exemption would mask a host-face regression.
+ */
+export const EVENT_WALK_EXEMPTIONS: Record<string, string> = {
+  'commands/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
+  'connection/reset': 'client-face transport signal — packages/client/runtime/README.md owns the surface',
+  'credentials/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
+  'locale/change': 'client-face locale switch signal — packages/client/locale/README.md owns the surface',
+  'models/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
+  'settings/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
+  'slash/input-begin-command': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
+  'slash/input-consume-token': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
+  'slash/input-insert-reference': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
+  'slash/input-insert-text': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
+  'slots/changed': 'client-face slot invalidation signal — packages/client/runtime/README.md owns the surface',
+  'theme/change': 'client-face theme switch signal — packages/client/ui-theme/README.md owns the surface',
+}
+
 /**
  * One primary subsystems page per project type used by a generated
  * signature. This stays curated because union names intentionally do not
@@ -506,56 +546,122 @@ export function spliceRegion(content: string, region: string): string {
   return [...lines.slice(0, begin), ...region.split('\n'), ...lines.slice(end + 1)].join('\n')
 }
 
+/** The declared-vs-rendered inputs {@link walkPartitionProblems} judges. */
+export interface WalkPartitionInput {
+  /** Service key → source pointer, as the rendering projection produced them. */
+  readonly renderedKeys: ReadonlyMap<string, string>
+  /** Event scopes the rendering projection produced. */
+  readonly renderedScopes: ReadonlySet<string>
+  /** Event names the rendering projection produced. */
+  readonly renderedEventNames: ReadonlySet<string>
+  /** Context key → first declaring file, from the independent AST scan. */
+  readonly declaredKeys: ReadonlyMap<string, string>
+  /** Event name → first declaring file, from the independent AST scan. */
+  readonly declaredEvents: ReadonlyMap<string, string>
+}
+
+/** The curated partition maps {@link walkPartitionProblems} enforces. */
+export interface WalkPartitionMaps {
+  readonly servicePage: Readonly<Record<string, string>>
+  readonly serviceWalkExemptions: Readonly<Record<string, string>>
+  readonly eventScopePage: Readonly<Record<string, string>>
+  readonly eventWalkExemptions: Readonly<Record<string, string>>
+}
+
+/**
+ * Judge the rendered surface and the independent AST scan against the curated
+ * partition maps, fail-closed in both directions for services AND events: a
+ * rendered key/scope must be mapped to a page, a mapped key/scope must still
+ * render, and — the backstop — a DECLARED key/event the projection cannot see
+ * must carry a named walk exemption (a rendered one must not). Pure so the
+ * acceptance paths are provable without running the projection.
+ * @param input - rendered surface plus the declared-key/event scans.
+ * @param maps - the curated page maps and walk exemptions.
+ * @returns one message per violation, empty when the partition holds.
+ */
+export function walkPartitionProblems(input: WalkPartitionInput, maps: WalkPartitionMaps): string[] {
+  const problems: string[] = []
+  for (const [key, source] of input.renderedKeys) {
+    if (!Object.hasOwn(maps.servicePage, key)) problems.push(`service ctx.${key} (${source}) has no SERVICE_PAGE entry; every service maps to exactly one subsystems page.`)
+  }
+  for (const scope of [...input.renderedScopes].sort()) {
+    if (!Object.hasOwn(maps.eventScopePage, scope)) problems.push(`event scope '${scope}/*' has no EVENT_SCOPE_PAGE entry; every event scope maps to exactly one subsystems page.`)
+  }
+  for (const key of Object.keys(maps.servicePage)) {
+    if (!input.renderedKeys.has(key)) problems.push(`SERVICE_PAGE maps 'ctx.${key}' but the projection discovers no such service; remove the stale entry.`)
+  }
+  for (const scope of Object.keys(maps.eventScopePage)) {
+    if (!input.renderedScopes.has(scope)) problems.push(`EVENT_SCOPE_PAGE maps '${scope}/*' but the projection discovers no such scope; remove the stale entry.`)
+  }
+  // The rendering projection only sees a Context key it can resolve to a
+  // documented service class. The independent scan reads EVERY Context merge
+  // so a key the projection cannot render must either be rendered (mapped) or
+  // carry a named SERVICE_WALK_EXEMPTIONS reason — never vanish silently.
+  for (const [key, rel] of input.declaredKeys) {
+    const rendered = input.renderedKeys.has(key)
+    const exempt = Object.hasOwn(maps.serviceWalkExemptions, key)
+    if (!rendered && !exempt) {
+      problems.push(`ctx.${key} (${rel}) is declared in a Context merge but invisible to the rendering projection; map it in SERVICE_PAGE (after making it renderable) or name it in SERVICE_WALK_EXEMPTIONS with its documentation owner.`)
+    }
+    if (rendered && exempt) problems.push(`ctx.${key} is rendered by the projection but still listed in SERVICE_WALK_EXEMPTIONS; remove the stale exemption.`)
+  }
+  for (const key of Object.keys(maps.serviceWalkExemptions)) {
+    if (!input.declaredKeys.has(key)) problems.push(`SERVICE_WALK_EXEMPTIONS names 'ctx.${key}' but no Context merge declares it; remove the stale exemption.`)
+  }
+  // The event mirror of the service backstop: the projection walks only files
+  // reachable from host-face package exports, so a client-face or unreachable
+  // Events merge would otherwise vanish without a trace.
+  for (const [name, rel] of input.declaredEvents) {
+    const rendered = input.renderedEventNames.has(name)
+    const exempt = Object.hasOwn(maps.eventWalkExemptions, name)
+    if (!rendered && !exempt) {
+      problems.push(`event '${name}' (${rel}) is declared in an Events merge but invisible to the rendering projection; make it renderable (mapped via EVENT_SCOPE_PAGE) or name it in EVENT_WALK_EXEMPTIONS with its documentation owner.`)
+    }
+    if (rendered && exempt) problems.push(`event '${name}' is rendered by the projection but still listed in EVENT_WALK_EXEMPTIONS; remove the stale exemption.`)
+  }
+  for (const name of Object.keys(maps.eventWalkExemptions)) {
+    if (!input.declaredEvents.has(name)) problems.push(`EVENT_WALK_EXEMPTIONS names '${name}' but no Events merge declares it; remove the stale exemption.`)
+  }
+  return problems
+}
+
 /**
  * Compute every generated artifact: the inherited-tier page, the model-facing
  * runtime API module, plus, per mapped subsystems page, the pair's two updated
  * documents with the injected region. Fail-loud partition checks live here: an
  * unmapped service/event scope, a mapping whose page file does not exist, a
- * curated entry whose key/scope the projection no longer discovers, and a
- * mapped page missing its markers are all aggregated errors.
+ * curated entry whose key/scope the projection no longer discovers, a declared
+ * Context key or Events member the projection cannot see without a named walk
+ * exemption, and a mapped page missing its markers are all aggregated errors.
  * @returns `[repo-relative path, exact content]` for every generated artifact.
  */
 export function computeOutputs(): [string, string][] {
   const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
   const services = [...model.services]
   const events = [...model.events]
-  const problems: string[] = []
 
-  const discoveredKeys = new Set(services.map(s => s.key))
-  const discoveredScopes = new Set(events.map(e => e.scope))
-  for (const s of services) {
-    if (!Object.hasOwn(SERVICE_PAGE, s.key)) problems.push(`service ctx.${s.key} (${s.source}) has no SERVICE_PAGE entry; every service maps to exactly one subsystems page.`)
-  }
-  for (const scope of discoveredScopes) {
-    if (!Object.hasOwn(EVENT_SCOPE_PAGE, scope)) problems.push(`event scope '${scope}/*' has no EVENT_SCOPE_PAGE entry; every event scope maps to exactly one subsystems page.`)
-  }
-  for (const key of Object.keys(SERVICE_PAGE)) {
-    if (!discoveredKeys.has(key)) problems.push(`SERVICE_PAGE maps 'ctx.${key}' but the projection discovers no such service; remove the stale entry.`)
-  }
-  for (const scope of Object.keys(EVENT_SCOPE_PAGE)) {
-    if (!discoveredScopes.has(scope)) problems.push(`EVENT_SCOPE_PAGE maps '${scope}/*' but the projection discovers no such scope; remove the stale entry.`)
-  }
-  // The rendering projection only sees a Context key it can resolve to a
-  // documented service class. This independent scan reads EVERY Context merge
-  // so a key the projection cannot render must either be rendered (mapped) or
-  // carry a named SERVICE_WALK_EXEMPTIONS reason — never vanish silently.
   const declaredKeys = new Map<string, string>()
-  for (const { rel, sf, body } of contextMergeFiles(root, 'packages/*/*/src/*.ts')) {
+  const declaredEvents = new Map<string, string>()
+  for (const { rel, sf, body } of contextMergeFiles(root, 'packages/*/*/src/**/*.ts')) {
     for (const key of contextKeyMap(body, sf).keys()) {
       if (!declaredKeys.has(key)) declaredKeys.set(key, rel)
     }
-  }
-  for (const [key, rel] of declaredKeys) {
-    const rendered = discoveredKeys.has(key)
-    const exempt = Object.hasOwn(SERVICE_WALK_EXEMPTIONS, key)
-    if (!rendered && !exempt) {
-      problems.push(`ctx.${key} (${rel}) is declared in a Context merge but invisible to the rendering projection; map it in SERVICE_PAGE (after making it renderable) or name it in SERVICE_WALK_EXEMPTIONS with its documentation owner.`)
+    for (const name of eventNameList(body, sf)) {
+      if (!declaredEvents.has(name)) declaredEvents.set(name, rel)
     }
-    if (rendered && exempt) problems.push(`ctx.${key} is rendered by the projection but still listed in SERVICE_WALK_EXEMPTIONS; remove the stale exemption.`)
-  }
-  for (const key of Object.keys(SERVICE_WALK_EXEMPTIONS)) {
-    if (!declaredKeys.has(key)) problems.push(`SERVICE_WALK_EXEMPTIONS names 'ctx.${key}' but no Context merge declares it; remove the stale exemption.`)
   }
+  const problems = walkPartitionProblems({
+    renderedKeys: new Map(services.map(s => [s.key, s.source])),
+    renderedScopes: new Set(events.map(e => e.scope)),
+    renderedEventNames: new Set(events.map(e => e.name)),
+    declaredKeys,
+    declaredEvents,
+  }, {
+    servicePage: SERVICE_PAGE,
+    serviceWalkExemptions: SERVICE_WALK_EXEMPTIONS,
+    eventScopePage: EVENT_SCOPE_PAGE,
+    eventWalkExemptions: EVENT_WALK_EXEMPTIONS,
+  })
   if (problems.length > 0) throw new Error(`gen-cordis-catalog: ${problems.length} partition violation(s):\n${problems.map(p => `  ${p}`).join('\n')}`)
 
   const pages = [...new Set([...Object.values(SERVICE_PAGE), ...Object.values(EVENT_SCOPE_PAGE)])].sort()

From bd659179f66ee397e6bcd9dcadede06c1eb192e4 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 03:20:17 +0800
Subject: [PATCH 422/516] docs(i18n): reproofread updated Chinese documentation

---
 ...26-06-11-content-block-vocabulary.i18n.yaml |  2 +-
 .../2026-06-11-content-block-vocabulary.zh.md  |  2 +-
 ...2026-06-11-event-sourced-sessions.i18n.yaml |  2 +-
 .../2026-06-11-event-sourced-sessions.zh.md    |  2 +-
 ...-06-11-microkernel-event-taxonomy.i18n.yaml |  2 +-
 ...2026-06-11-microkernel-event-taxonomy.zh.md |  2 +-
 .../2026-06-14-session-persistence.i18n.yaml   |  2 +-
 .../2026-06-14-session-persistence.zh.md       |  8 ++++----
 ...red-persistence-write-coordinator.i18n.yaml |  2 +-
 ...-shared-persistence-write-coordinator.zh.md |  6 +++---
 ...6-21-bounded-llm-request-recovery.i18n.yaml |  2 +-
 ...26-06-21-bounded-llm-request-recovery.zh.md |  8 ++++----
 ...2026-06-30-event-domain-semantics.i18n.yaml |  2 +-
 .../2026-06-30-event-domain-semantics.zh.md    |  2 +-
 ...26-07-05-reconstructable-requests.i18n.yaml |  2 +-
 .../2026-07-05-reconstructable-requests.zh.md  |  6 +++---
 ...on-pressure-and-overflow-recovery.i18n.yaml |  2 +-
 ...action-pressure-and-overflow-recovery.zh.md |  8 ++++----
 ...-send-and-coalesced-user-messages.i18n.yaml |  2 +-
 ...fied-send-and-coalesced-user-messages.zh.md |  6 +++---
 .../2026-07-23-toolview-dissolution.i18n.yaml  |  2 +-
 .../2026-07-23-toolview-dissolution.zh.md      |  8 ++++----
 ...ext-injection-from-turn-execution.i18n.yaml |  2 +-
 ...context-injection-from-turn-execution.zh.md |  4 ++--
 ...session-scope-and-provide-channel.i18n.yaml |  2 +-
 ...ent-session-scope-and-provide-channel.zh.md |  4 ++--
 ...-07-27-dispose-ladder-to-consumer.i18n.yaml |  2 +-
 ...2026-07-27-dispose-ladder-to-consumer.zh.md |  4 ++--
 ...6-07-29-dsh-source-launch-tsx-esm.i18n.yaml |  2 +-
 .../2026-07-29-dsh-source-launch-tsx-esm.zh.md |  2 +-
 ...uest-level-llm-config-credentials.i18n.yaml |  2 +-
 ...-request-level-llm-config-credentials.zh.md |  2 +-
 ...oundaries-and-atomic-registration.i18n.yaml |  2 +-
 ...al-boundaries-and-atomic-registration.zh.md |  2 +-
 .../2026-07-30-web-config-plane.i18n.yaml      |  2 +-
 .../2026-07-30-web-config-plane.zh.md          |  2 +-
 ...action-summary-prefix-cache-reuse.i18n.yaml |  2 +-
 ...compaction-summary-prefix-cache-reuse.zh.md |  2 +-
 ...7-21-semantic-session-checkpoints.i18n.yaml |  2 +-
 ...26-07-21-semantic-session-checkpoints.zh.md |  2 +-
 .../feature/2026-06-15-code-mode.i18n.yaml     |  2 +-
 .../feature/2026-06-15-code-mode.zh.md         |  4 ++--
 ...-06-18-compaction-capability-seam.i18n.yaml |  2 +-
 ...2026-06-18-compaction-capability-seam.zh.md |  2 +-
 .../2026-06-24-workspace-context.i18n.yaml     |  2 +-
 .../feature/2026-06-24-workspace-context.zh.md |  4 ++--
 .../2026-06-29-todo-write-tool.i18n.yaml       |  2 +-
 .../feature/2026-06-29-todo-write-tool.zh.md   |  4 ++--
 .../feature/2026-06-30-hook-bridges.i18n.yaml  |  2 +-
 .../feature/2026-06-30-hook-bridges.zh.md      |  2 +-
 .../2026-06-30-hook-protocol-lib.i18n.yaml     |  2 +-
 .../feature/2026-06-30-hook-protocol-lib.zh.md |  2 +-
 ...-16-durable-per-step-time-context.i18n.yaml |  2 +-
 ...6-07-16-durable-per-step-time-context.zh.md |  6 +++---
 .../2026-07-19-human-goal-command.i18n.yaml    |  2 +-
 .../2026-07-19-human-goal-command.zh.md        |  2 +-
 ...ersisted-same-session-goal-domain.i18n.yaml |  2 +-
 ...19-persisted-same-session-goal-domain.zh.md |  8 ++++----
 ...19-same-session-goal-round-driver.i18n.yaml |  2 +-
 ...-07-19-same-session-goal-round-driver.zh.md | 12 ++++++------
 ...26-07-21-cross-session-references.i18n.yaml |  2 +-
 .../2026-07-21-cross-session-references.zh.md  |  2 +-
 ...-07-24-web-session-model-selector.i18n.yaml |  2 +-
 ...2026-07-24-web-session-model-selector.zh.md |  2 +-
 ...6-07-28-tool-call-file-open-in-os.i18n.yaml |  2 +-
 .../2026-07-28-tool-call-file-open-in-os.zh.md |  2 +-
 ...ersistent-bash-str-replace-editor.i18n.yaml |  2 +-
 ...29-persistent-bash-str-replace-editor.zh.md |  2 +-
 .../2026-07-04-doc-tiers-and-budgets.i18n.yaml |  2 +-
 .../2026-07-04-doc-tiers-and-budgets.zh.md     | 12 ++++++------
 .../2026-07-22-fast-local-git-hooks.i18n.yaml  |  2 +-
 .../2026-07-22-fast-local-git-hooks.zh.md      |  4 ++--
 ...-27-wine-windows-gates-experiment.i18n.yaml |  2 +-
 ...6-07-27-wine-windows-gates-experiment.zh.md |  4 ++--
 ...6-06-20-public-agent-stop-surface.i18n.yaml |  2 +-
 .../2026-06-20-public-agent-stop-surface.zh.md |  2 +-
 .../2026-07-17-one-send-one-turn.i18n.yaml     |  2 +-
 .../2026-07-17-one-send-one-turn.zh.md         |  8 ++++----
 ...plan-specific-collaboration-state.i18n.yaml |  2 +-
 ...-22-plan-specific-collaboration-state.zh.md |  2 +-
 ...-collapse-persistence-flush-state.i18n.yaml |  2 +-
 ...7-23-collapse-persistence-flush-state.zh.md |  6 +++---
 ...ent-loop-observable-state-machine.i18n.yaml |  2 +-
 ...4-agent-loop-observable-state-machine.zh.md |  2 +-
 ...7-25-client-settings-locale-theme.i18n.yaml |  2 +-
 ...26-07-25-client-settings-locale-theme.zh.md |  6 +++---
 docs/cookbook/adding-an-llm-adapter.i18n.yaml  |  2 +-
 docs/cookbook/adding-an-llm-adapter.zh.md      |  2 +-
 docs/defensive-patterns.i18n.yaml              |  2 +-
 docs/defensive-patterns.zh.md                  |  4 ++--
 docs/user/develop/basic/config.i18n.yaml       |  2 +-
 docs/user/develop/basic/config.zh.md           |  2 +-
 docs/user/develop/basic/tool.i18n.yaml         |  2 +-
 docs/user/develop/basic/tool.zh.md             |  2 +-
 examples/acp-agent/README.i18n.yaml            |  2 +-
 examples/acp-agent/README.zh.md                |  2 +-
 examples/jsonrpc-agent/README.i18n.yaml        |  2 +-
 examples/jsonrpc-agent/README.zh.md            |  6 +++---
 native/README.i18n.yaml                        |  2 +-
 native/README.zh.md                            |  4 ++--
 native/landlock-run/README.i18n.yaml           |  2 +-
 native/landlock-run/README.zh.md               |  2 +-
 packages/acp/acp/README.i18n.yaml              |  2 +-
 packages/acp/acp/README.zh.md                  |  4 ++--
 packages/bash/bash-sandbox/README.i18n.yaml    |  2 +-
 packages/bash/bash-sandbox/README.zh.md        |  2 +-
 packages/client/hmr/README.i18n.yaml           |  2 +-
 packages/client/hmr/README.zh.md               |  2 +-
 packages/client/modules/README.i18n.yaml       |  2 +-
 packages/client/modules/README.zh.md           |  2 +-
 packages/client/runtime/README.i18n.yaml       |  2 +-
 packages/client/runtime/README.zh.md           | 10 +++++-----
 packages/client/schema-form/README.i18n.yaml   |  2 +-
 packages/client/schema-form/README.zh.md       |  2 +-
 packages/client/ui-layout/README.i18n.yaml     |  2 +-
 packages/client/ui-layout/README.zh.md         |  2 +-
 packages/client/ui-model/README.i18n.yaml      |  2 +-
 packages/client/ui-model/README.zh.md          |  2 +-
 packages/client/ui-models/README.i18n.yaml     |  2 +-
 packages/client/ui-models/README.zh.md         |  4 ++--
 packages/client/ui-settings/README.i18n.yaml   |  2 +-
 packages/client/ui-settings/README.zh.md       |  2 +-
 packages/client/ui-sidebar/README.i18n.yaml    |  2 +-
 packages/client/ui-sidebar/README.zh.md        |  2 +-
 packages/client/ui-skill/README.i18n.yaml      |  2 +-
 packages/client/ui-skill/README.zh.md          |  4 ++--
 packages/client/ui-slots/README.i18n.yaml      |  2 +-
 packages/client/ui-slots/README.zh.md          |  2 +-
 packages/client/ui-theme/README.i18n.yaml      |  2 +-
 packages/client/ui-theme/README.zh.md          |  4 ++--
 packages/client/web/README.i18n.yaml           |  2 +-
 packages/client/web/README.zh.md               |  2 +-
 .../code-runtime-worker/README.i18n.yaml       |  2 +-
 .../code-runtime-worker/README.zh.md           |  2 +-
 .../code-runtime/code-runtime/README.i18n.yaml |  2 +-
 .../code-runtime/code-runtime/README.zh.md     |  2 +-
 packages/context/time-context/README.i18n.yaml |  2 +-
 packages/context/time-context/README.zh.md     |  6 +++---
 packages/context/tmux-context/README.i18n.yaml |  2 +-
 packages/context/tmux-context/README.zh.md     |  2 +-
 .../context/workspace-context/README.i18n.yaml |  2 +-
 .../context/workspace-context/README.zh.md     |  6 +++---
 packages/examples/README.i18n.yaml             |  2 +-
 packages/examples/README.zh.md                 |  8 ++++----
 .../examples/agent-spine-demo/README.i18n.yaml |  2 +-
 .../examples/agent-spine-demo/README.zh.md     |  2 +-
 packages/goal/goal-session/README.i18n.yaml    |  2 +-
 packages/goal/goal-session/README.zh.md        |  2 +-
 packages/hooks/README.i18n.yaml                |  2 +-
 packages/hooks/README.zh.md                    |  2 +-
 packages/hooks/hook-protocol/README.i18n.yaml  |  2 +-
 packages/hooks/hook-protocol/README.zh.md      |  2 +-
 packages/host/apiproxy/README.i18n.yaml        |  2 +-
 packages/host/apiproxy/README.zh.md            | 18 +++++++++---------
 .../interaction/tool-ask-user/README.i18n.yaml |  2 +-
 .../interaction/tool-ask-user/README.zh.md     |  2 +-
 .../user-interaction/README.i18n.yaml          |  2 +-
 .../interaction/user-interaction/README.zh.md  |  2 +-
 packages/llm/llm-pi-ai/README.i18n.yaml        |  2 +-
 packages/llm/llm-pi-ai/README.zh.md            |  2 +-
 packages/llm/llm/README.i18n.yaml              |  2 +-
 packages/llm/llm/README.zh.md                  |  4 ++--
 packages/llm/token-meter/README.i18n.yaml      |  2 +-
 packages/llm/token-meter/README.zh.md          |  4 ++--
 packages/mcp/mcp-client/README.i18n.yaml       |  2 +-
 packages/mcp/mcp-client/README.zh.md           |  4 ++--
 .../sandbox/sandbox-local/README.i18n.yaml     |  2 +-
 packages/sandbox/sandbox-local/README.zh.md    |  4 ++--
 .../sandbox/sandbox-policy/README.i18n.yaml    |  2 +-
 packages/sandbox/sandbox-policy/README.zh.md   |  4 ++--
 .../repository-plugin/README.i18n.yaml         |  2 +-
 .../repository-plugin/README.zh.md             |  4 ++--
 .../session-persistence-jsonl/README.i18n.yaml |  4 ++--
 .../session-persistence-jsonl/README.zh.md     |  2 +-
 .../README.i18n.yaml                           |  4 ++--
 .../session-persistence-sqlite/README.zh.md    |  4 ++--
 .../session-persistence/README.i18n.yaml       |  4 ++--
 .../session/session-persistence/README.zh.md   | 16 ++++++++--------
 .../session-projection/README.i18n.yaml        |  4 ++--
 .../session/session-projection/README.zh.md    |  2 +-
 .../session-telemetry-otel/README.i18n.yaml    |  4 ++--
 .../session-telemetry-otel/README.zh.md        |  2 +-
 .../session/session-telemetry/README.i18n.yaml |  4 ++--
 .../session/session-telemetry/README.zh.md     |  2 +-
 packages/skill/tool-skill/README.i18n.yaml     |  2 +-
 packages/skill/tool-skill/README.zh.md         |  6 +++---
 packages/storage/storage/README.i18n.yaml      |  2 +-
 packages/storage/storage/README.zh.md          |  2 +-
 .../subagent-inprocess/README.i18n.yaml        |  2 +-
 .../subagent/subagent-inprocess/README.zh.md   |  6 +++---
 packages/support/llm-replay/README.i18n.yaml   |  2 +-
 packages/support/llm-replay/README.zh.md       |  4 ++--
 packages/support/loader-smoke/README.i18n.yaml |  2 +-
 packages/support/loader-smoke/README.zh.md     |  2 +-
 packages/tasks/tool-tasks/README.i18n.yaml     |  2 +-
 packages/tasks/tool-tasks/README.zh.md         |  2 +-
 packages/typert/README.i18n.yaml               |  2 +-
 packages/typert/README.zh.md                   |  2 +-
 packages/typert/generator/README.i18n.yaml     |  2 +-
 packages/typert/generator/README.zh.md         |  4 ++--
 packages/typert/registry/README.i18n.yaml      |  2 +-
 packages/typert/registry/README.zh.md          |  4 ++--
 packages/util/README.i18n.yaml                 |  2 +-
 packages/util/README.zh.md                     |  4 ++--
 packages/util/native-command/README.i18n.yaml  |  2 +-
 packages/util/native-command/README.zh.md      |  2 +-
 packages/util/retention/README.i18n.yaml       |  2 +-
 packages/util/retention/README.zh.md           |  2 +-
 python/README.i18n.yaml                        |  2 +-
 python/README.zh.md                            |  2 +-
 python/sdk/README.i18n.yaml                    |  2 +-
 python/sdk/README.zh.md                        |  2 +-
 212 files changed, 315 insertions(+), 315 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml
index 66dddfd425..0b150d8090 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.md
 2026-06-11-content-block-vocabulary.md: 5228724bb9101307db9929aaf7831b477c2a6022
-2026-06-11-content-block-vocabulary.zh.md: ffcbbc13dfe9176941f4838b0078d3850403a16c
+2026-06-11-content-block-vocabulary.zh.md: b43de335917c6b5304a94b296fcb8253827b0600
diff --git a/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md
index ffcbbc13df..b43de33591 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md
@@ -12,7 +12,7 @@ harness 需要一套统一的内部消息语言，供 agent loop（智能体循
 
 自主拥有词汇：消息是类型化内容块的数组（`text`、`reasoning`、`tool-call`、`tool-result`），其联合类型派生自可合并扩展的 `ContentBlockMap`，插件通过声明合并添加新的块类型。同一可合并扩展映射模式为所有「字符串化」字段提供类型（`MessageSource`、`FinishReason`、`TurnTrigger`、`TurnEndReason`）。流式输出采用原始分片协议；`BlockAssembler` 是唯一的共享组装实现。适配器负责转换为提供方的协议格式（wire format）——映射成本留在适配器中，正是它该在的地方。
 
-会话内上下文注入（`context/message`）和轮次中途 steering 最初渲染为带标签的 user-role 信封（system-reminder 模式），而非引入新角色，因此适配器无需承担额外负担。如今两者都投影为无包装的普通用户内容；见[注入内容信封 Agent Note](../simplification/2026-07-20-unwrap-injected-content-envelopes.md)。实际适配器验证已确认此渲染方式符合当前 DeepSeek 的行为；如果未来某提供方出现不兼容，应在该适配器内处理，而非引入新的规范角色。
+会话内上下文注入（`context/message`）和轮次中途 steering（中途引导）最初渲染为带标签的 user-role 信封（system-reminder 模式），而非引入新角色，因此适配器无需承担额外负担。如今两者都投影为无包装的普通用户内容；见[注入内容信封 Agent Note](../simplification/2026-07-20-unwrap-injected-content-envelopes.md)。实际适配器验证已确认此渲染方式符合当前 DeepSeek 的行为；如果未来某提供方出现不兼容，应在该适配器内处理，而非引入新的规范角色。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
index d224676be3..0eb64b3107 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md
 2026-06-11-event-sourced-sessions.md: 01f9628c1cfc000aca8654caf5edeff09411fdcc
-2026-06-11-event-sourced-sessions.zh.md: ec5c3e766dfa97c5612827023c5cc66bf01a8e6c
+2026-06-11-event-sourced-sessions.zh.md: 5de230de9e9f1303943b43f6fdeefaf8264aa3bf
diff --git a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
index ec5c3e766d..5de230de9e 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
@@ -14,7 +14,7 @@ MVP 要求严格的基于事件的追踪，以及完全可回放的会话（严
 
 追加操作是同步的（热路径从不阻塞于 I/O）；`session/event` 是同步通知；持久化插件在后台缓冲写入，并在每个轮次结束时触发的 `session/flush` 检查点处等待排空。
 
-顺序契约：agent loop（智能体循环）先领取 inbox 消息，再运行 `agent/pre-step`；只有 enter 决策才打开 `step/start`，随后在请求派生前追加返回的 `user/message` 批次。提供方输出组装并以 `assistant/message` 追加后才分派工具，因此持久日志记录工具实际遵循的确切消息。回归测试固定了这一顺序。
+顺序约定：agent loop（智能体循环）先领取 inbox 消息，再运行 `agent/pre-step`；只有 enter 决策才打开 `step/start`，随后在请求派生前追加返回的 `user/message` 批次。提供方输出组装并以 `assistant/message` 追加后才分派工具，因此持久日志记录工具实际遵循的确切消息。回归测试固定了这一顺序。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
index 3f1b629bc5..1d561dd14a 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
 2026-06-11-microkernel-event-taxonomy.md: 202595fed125966a5d77920536e7f4ee88f875fe
-2026-06-11-microkernel-event-taxonomy.zh.md: 899c96d86cb7e37d90df349ce5f3f932e0a72f95
+2026-06-11-microkernel-event-taxonomy.zh.md: 1365910157c36699bfe1fdb3a10aa0785948e0fa
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
index 899c96d86c..1365910157 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
@@ -15,7 +15,7 @@ Status: implemented
 - **waterfall（瀑布式事件）**（around-middleware）：插件可变换、否决、恢复或包装：`agent/pre-step`、`agent/request`、`agent/request-error`、`tools/pre-execute`、`tools/execute`、`tools/post-execute`、`llm/stream`、`system-prompt/assemble`。
 - **serial**（按监听器顺序依次 await）：用于 `agent/turn-stopping` 等有序检查点。
 - **parallel**（await 扇出）：每个监听器都必须获得独立执行的机会：`session/flush` 持久性检查点。
-- **emit**（同步 fire-and-forget）：用于 inbox 转换、生命周期、错误，以及包含不可变 `tools/result` 观测的事件。轮次与步骤边界由持久会话事件拥有。
+- **emit**（同步 fire-and-forget）：用于通知：inbox 转换、生命周期、错误，以及受错误隔离的 `tools/result` 观测；该观测接收不可变的最终结果。轮次与步骤边界由持久会话事件拥有。
 
 事件词汇定义在接口包中（dsh-agent 声明 agent/* 事件）；`@deepseek-ai/dsh-agent-loop` 是唯一的具体循环插件，且自身可替换——外部不得依赖它。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
index c3f4068862..6737b3f490 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-14-session-persistence.md
 2026-06-14-session-persistence.md: 00e129e57c7144fd62eec26f5854ee21dec4e964
-2026-06-14-session-persistence.zh.md: 1c98d5771819e8776d9f5cae4a147d2016ee5978
+2026-06-14-session-persistence.zh.md: 6e4e9ece56332ce74b01d60a111617c70e2a874a
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
index 1c98d57718..6e4e9ece56 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
@@ -19,11 +19,11 @@ Status: implemented
 
 以下关键选择记录于此，因为它们长期有效、存在争议且出人意料：
 
-- **规范的持久日志无损保留每个 `SessionEvent`，包括 `assistant/chunk`。** JSONL 存储可以将一段连续的增量事件编码为一条打包行，但逻辑读取方会重建精确的事件边界、序号与时间戳。`deriveMessages()` 跳过分片，而过滤分片的方案（Codex 的 `policy.rs`）很有吸引力，但 `seq = log.length` 以及 `events[i].seq === i` 验证要求*连续*的逻辑日志；过滤掉分片会留下空洞，同时破坏契约和恢复功能。基于分片过滤的投影可以作为派生视图在后续实现（带有自己的重新编号），但它不是规范日志。
-- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些 closer；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
-- **文件后端为规范实现，数据库后端为经过验证的直接替换。** `SessionEvent` 1:1 映射到一行 `(session_id, seq, type, time, data)`：`append` 是 INSERT（在一个断言连续 seq 契约的事务中），读取使用 SELECT … ORDER BY seq。`dsh-session-persistence-sqlite` 正是如此：一个 `SessionPersistence` 子类，接口无变化（opencode 在 SQLite/WAL 上运行的正是这个形状），且通过与 JSONL 后端相同的 `runPersistenceContract` 测试套件。该契约以相同的语义约束两个后端（惰性物化、逻辑关闭中断轮次、修复只提交一次、连续 seq），一次表达在文件字节上，一次表达在数据库行上。其数据库拥有专用的 application id 与单调递增的 schema 版本。系统会在一个事务中为全新文件创建所有表并写入这两个 header 值；未版本化文件若带有任何用户定义的 schema 对象或应用标识、当前版本文件若带有外部应用标识，以及任何非当前版本文件，都会在修改日志模式之前被拒绝。
+- **规范的持久日志无损保留每个 `SessionEvent`，包括 `assistant/chunk`。** JSONL 存储可以将一段连续的增量事件编码为一条打包行，但逻辑读取方会重建精确的事件边界、序号与时间戳。`deriveMessages()` 跳过分片，而过滤分片的方案（Codex 的 `policy.rs`）很有吸引力，但 `seq = log.length` 以及 `events[i].seq === i` 验证要求*连续*的逻辑日志；过滤掉分片会留下空洞，同时破坏约定和恢复功能。基于分片过滤的投影可以作为派生视图在后续实现（带有自己的重新编号），但它不是规范日志。
+- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些收尾事件；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
+- **文件后端为规范实现，数据库后端为经过验证的直接替换。** `SessionEvent` 1:1 映射到一行 `(session_id, seq, type, time, data)`：`append` 是 INSERT（在一个断言连续 seq 约定成立的事务中），读取使用 SELECT … ORDER BY seq。`dsh-session-persistence-sqlite` 正是如此：一个 `SessionPersistence` 子类，接口无变化（opencode 在 SQLite/WAL 上运行的正是这个形状），且通过与 JSONL 后端相同的 `runPersistenceContract` 测试套件。该约定以相同的语义约束两个后端（惰性物化、逻辑关闭中断轮次、修复只提交一次、连续 seq），一次表达在文件字节上，一次表达在数据库行上。其数据库拥有专用的 application id 与单调递增的 schema 版本。系统会在一个事务中为全新文件创建所有表并写入这两个 header 值；未版本化文件若带有任何用户定义的 schema 对象或应用标识、当前版本文件若带有外部应用标识，以及任何非当前版本文件，都会在修改日志模式之前被拒绝。
 - **元数据在日志之外。** 格式版本、cwd 和谱系是存储关注点，不是可回放的对话状态，因此它们存放在 `dsh-session` 拥有的 `SessionHeader` 中，并通过新的只读属性 `session.header` 附加到 `Session` 上——永远不进入 `SessionEventMap`，永远不到达 `deriveMessages()`。`createdAt` 是以 Unix epoch 毫秒表示的非负安全整数：运行时创建和持久化注册会拒绝小数值，JSONL 会验证解码后的 header，SQLite 则将其存入严格的 `INTEGER` 列。替代方案（一个可合并扩展的 `session/meta` 事件作为日志第 0 行）被否决：日志内事件会自然随 seed/fork 的会话携带，但元数据不是可回放状态，因此显式的日志外 header seam 是更清晰的取舍。（header 最初被拆分为不可变的 `SessionHeader` 加可变的 `SessionSummary`，二者的联合类型为 `SessionMeta`；可变 summary 后来因属于死状态而被移除——见 [移除可变会话摘要](../simplification/2026-06-19-drop-mutable-session-summary.md)。）
-- **`ctx.agents.create()` 和 `ctx.agents.resume()` 是异步工厂；恢复还跨越持久化边界。** `ctx.agents.resume({ resumeSessionId })` 通过 `ctx.sessionPersistence.prepare()` 取得精确的未发布 Session，以持久化 id 发布它，并继续其投影。[Session 准备阶段决策](2026-08-05-session-preparation.md)定义历史检查与恢复之间的复用。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
+- **`ctx.agents.create()` 和 `ctx.agents.resume()` 是异步工厂；恢复还跨越持久化边界。** `ctx.agents.resume({ resumeSessionId })` 通过 `ctx.sessionPersistence.prepare()` 取得原本那个尚未发布的会话，以持久化 id 发布该会话，并延续其投影。[会话准备决策](2026-08-05-session-preparation.md)负责历史检查与恢复之间的复用。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index d1ae953836..77c706518c 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
 2026-06-18-shared-persistence-write-coordinator.md: 12131ebf8380fb8ba816618f0cbaf72cb004623a
-2026-06-18-shared-persistence-write-coordinator.zh.md: a11926b602651d8a7dc641f61371e882685b508b
+2026-06-18-shared-persistence-write-coordinator.zh.md: 7c04ee921c9b3f965ef6bd6d2d203cf4cbd50ea2
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
index a11926b602..7c04ee921c 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 将一个后端无关的 `PersistenceCoordinator` 提取到 `dsh-session-persistence` 中。协调器统一拥有编排逻辑；每个第一方后端组合一个协调器实例（`new PersistenceCoordinator(ctx, this)`），实现一个小型 `PersistenceBackend` 钩子接口，并将其有状态的公开方法（`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`）委托给协调器。由后端拥有的元数据与修订版本列举会绕过协调器。
 
-组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不可变逻辑检查，以及通过 `load` 实现的默认准备回退。
+组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不修改状态的逻辑检查，以及通过 `load` 实现的默认准备回退。
 
 协调器为每个存活的 `Session` 实例持有一个生命周期条目：初始化，加上一个包私有写入控制器，后者负责待处理事件、固定批处理截止时间、活跃写入、失败保留和共享 flush 屏障。每个 `session/event` 都进入这条有界写入路径，`session/flush` 则绕过等待以观察完全停稳。控制器归并由 [flush 控制器简化](../simplification/2026-07-23-collapse-persistence-flush-state.md)定义；调度节奏由[有界批处理决策](2026-08-08-bounded-session-persistence-write-batching.md)定义。
 
@@ -35,7 +35,7 @@ Status: implemented
 
 ## 测试
 
-共享的 `runPersistenceContract`（公开 API 契约）为每个后端运行，并证明 `inspect` 会配平被中断的逻辑视图但不改变存储或修订版本，随后由 `prepare` 或 `load` 提交恢复。`runCoordinatorContract`（`tests/coordinator-contract.ts`）通过内存参考实现、JSONL 与 SQLite 覆盖接管、HMR、碰撞、会话与后端 dispose 排空和崩溃尾部修复。`persistence.spec.ts`、`preparations.spec.ts` 与 `write-behind.spec.ts` 覆盖准备复用与预留、有界准备状态淘汰、固定窗口后续批次、存活控制器清理、同 id 链尾竞态、失败批次重试与关闭顺序。各后端自身的测试规格只保留存储机制。每个真实后端都有一个经由协调器的崩溃尾部修复测试，以覆盖不透明 marker 分支，因为契约中的崩溃用例会产生合成 closers，却不会产生 torn marker。
+共享的 `runPersistenceContract`（公开 API 约定）为每个后端运行，并证明 `inspect` 会配平被中断的逻辑视图但不改变存储或修订版本，随后由 `prepare` 或 `load` 提交恢复。`runCoordinatorContract`（`tests/coordinator-contract.ts`）通过内存参考实现、JSONL 与 SQLite 覆盖接管、HMR、碰撞、会话与后端 dispose 排空和崩溃尾部修复。`persistence.spec.ts`、`preparations.spec.ts` 与 `write-behind.spec.ts` 覆盖准备复用与预留、有界准备状态淘汰、固定窗口后续批次、存活控制器清理、同 id 链尾竞态、失败批次重试与关闭顺序。各后端自身的测试规格只保留存储机制。每个真实后端都有一个经由协调器的崩溃尾部修复测试，以覆盖不透明 marker 分支，因为约定中的崩溃用例会产生合成 closers，却不会产生 torn marker。
 
 ## 曾考虑的替代方案
 
@@ -44,4 +44,4 @@ Status: implemented
 
 ## 后果
 
-协调器增加了一层间接、一个不透明的 torn marker、脱离会话生命周期的退役任务，以及有界的已准备 Session 状态，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查、准备与不可变检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时不会提交中断 closers；复用、预留与发布由 [Session 准备阶段决策](2026-08-05-session-preparation.md)定义。新后端只需实现存储原语，而无需复制有界写入生命周期。
+协调器增加了一层间接、一个不透明的 torn marker、脱离会话生命周期的退役任务，以及有界的已准备 Session 状态，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查、准备与不修改状态的检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时不会提交中断 closers；复用、预留与发布由 [Session 准备阶段决策](2026-08-05-session-preparation.md)定义。新后端只需实现存储原语，而无需复制有界写入生命周期。
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
index dc841c67bd..b038b0e02d 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
 2026-06-21-bounded-llm-request-recovery.md: 587f2d26eee922e91c8797018964f983890eb8ec
-2026-06-21-bounded-llm-request-recovery.zh.md: be52ece63ce794cb13cdf657b73bae6e9f42cf6d
+2026-06-21-bounded-llm-request-recovery.zh.md: 4efe4f946dac90f65f5b8af4a7c36037413616b6
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
index be52ece63c..4efe4f946d 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-06-21-bounded-llm-request-recovery.md) | 中文
 
-[按提供方配置的请求重试策略](../feature/2026-07-24-provider-retry-policies.md)在此基础上增加了确切提供方配置与显式无界 mode。本说明继续负责结构化失败事实、已关闭步骤的恢复边界、normal mode 的暂时性默认值、可见的单次尝试和持久重试状态。[LLM 流的终止失败](2026-07-29-terminal-llm-stream-failures.md)取代了其中关于抛出错误身份和 stream sidecar 的机制。
+[按提供方配置的请求重试策略](../feature/2026-07-24-provider-retry-policies.md)在此基础上增加了确切提供方配置与显式无界 mode。本说明继续负责结构化失败事实、已关闭步骤的恢复边界、normal mode 的暂时性默认值、可见的单次尝试和持久重试状态。[LLM 流的终止失败](2026-07-29-terminal-llm-stream-failures.md)取代了其中关于抛出错误身份和流伴随状态的机制。
 
 ## 问题
 
-提供方适配器可能在分发或迭代时抛出异常，也可能以 `finish { kind: 'error' | 'aborted' }` 结束。最终适配器边界会在 `dsh-agent-loop` 接收前把抛出值规范化为该终止 finish 协议；middleware 与结果处理缺陷仍会抛出。loop 会将终止模型请求失败交给 `agent/request-error`。未被处理的失败是终态；处理失败的监听器修复策略自有状态，返回 `{ kind: 'retry' }`，并停止 waterfall 委托。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回契约。
+提供方适配器可能在分发或迭代时抛出异常，也可能以 `finish { kind: 'error' | 'aborted' }` 结束。最终适配器边界会在 `dsh-agent-loop` 接收前把抛出值规范化为该终止 finish 协议；middleware 与结果处理缺陷仍会抛出。loop 会将终止模型请求失败交给 `agent/request-error`。未被处理的失败是终态；处理失败的监听器修复策略自有状态，返回 `{ kind: 'retry' }`，并停止 waterfall（瀑布式事件）委托。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回约定。
 
 该边界已能安全地再次发起请求。原始 `assistant/chunk` 事件携带失败的 `turn` 和 `step`；除非某条成功的 `assistant/message` 引用这些事件，否则消息派生会忽略它们。只有终止性 finish 成功且组装完成后，系统才会分发工具调用；重试则会从持久日志开启新的编号轮次。因此，harness 无需引入第二套响应生命周期或暂定输出协议，即可分隔两次尝试。
 
@@ -40,7 +40,7 @@ interface LlmFailure {
 
 `code` 仍是 `HarnessError` 建立的提供方无关机器路由分类体系；新字段是在提供方边界观测到的事实。`ProviderRequestId` 由 `dsh-llm` 拥有并构造，序列化后为提供方发放的字符串。该载荷有意不包含 `retryable`、`failover`、`partialOutput`、提供方、模型、阶段或路由 id 字段。是否可重试属于策略，提供方／模型已位于持久请求头中，部分输出则从失败步骤的 `assistant/chunk` 事件派生。
 
-`LlmError` 携带 `failure: LlmFailure`，并保持 `failure.code === error.code`。`FinishReasonMap.error` 和 `FinishReasonMap.aborted` 携带同一载荷，而不是并行的失败形状。最终适配器边界会从适配器抛出值中分离这些事实，并发出相应的终止 finish；未知 SDK 异常会获得 `UNKNOWN` 载荷。精确的抛出对象身份不会跨越 LLM stream seam。
+`LlmError` 携带 `failure: LlmFailure`，并保持 `failure.code === error.code`。`FinishReasonMap.error` 和 `FinishReasonMap.aborted` 携带同一载荷，而不是并行的失败形状。最终适配器边界会从适配器抛出值中分离这些事实，并发出相应的终止 finish；未知 SDK 异常会获得 `UNKNOWN` 载荷。精确的抛出对象身份不会跨越 LLM 流 seam。
 
 agent loop（智能体循环）会将终止 finish 的 `LlmFailure` 传给 `agent/request-error`，并在记录未恢复的 `turn/end.reason` 时使用同一载荷。
 
@@ -107,7 +107,7 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 ## 验证
 
 - `LlmFailure` 是适配器抛出、错误 finish 和中止 finish 使用的唯一可序列化载荷；在可用时，规范化保留稳定 code、状态、重试延迟、品牌化的提供方请求 id，以及调用方中止与适配器超时之间的分类。
-- 适配器抛出值会在抵达消费方前成为终止失败 chunk；middleware 与消费方异常仍在模型请求恢复之外抛出。
+- 适配器抛出值会在抵达消费方前成为终止失败分片；middleware 与消费方异常仍在模型请求恢复之外抛出。
 - DeepSeek 和 pi-ai 适配器测试覆盖具有代表性的 400、401/403、429、5xx、连接、格式错误／截断流、超时、中止、Retry-After 秒数／日期、请求 id 和未知 SDK 错误路径，恢复策略无需解析消息文本。
 - pi-ai 将 SDK 选项固定为零次重试，并针对可重试的提供方响应执行一次可观测的线路请求尝试；独立测试确保移除任一边界都会失败。
 - `agent/request-error` 携带当前失败事实、不可变的先前已重试失败事实，以及实际服务注册所对应的不可变重试策略；成功会清除历史，暂时性失败／上下文溢出交替发生的集成测试证明两种策略只消耗各自的有限预算。
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
index 2317a5a14e..2e69991c33 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
 2026-06-30-event-domain-semantics.md: 14102b105e7bcaa6a00ac9c406933f772fc45a6f
-2026-06-30-event-domain-semantics.zh.md: 91e490b57bcdc1ed95f0b8b40cc9e16ef4d36f29
+2026-06-30-event-domain-semantics.zh.md: 2607e59490d8ba139bb1289d0f2941894281f6c6
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
index 91e490b57b..2607e59490 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
@@ -21,7 +21,7 @@ harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）
 **三个域，各司其职，以一条边界规则统一。**
 
 - **`session/*`——持久的、可回放的事实日志。** 拥有 `SessionEventMap`；每条记录仅含 JSON（无活对象）。每次追加触发一次 `session/event` emit，加上 `session/flush` 并行持久性检查点。它同时也是实时 transcript（文本记录）源：想渲染或响应已发生事件的消费方在此订阅，因此实时渲染与回放投影共享同一路径。
-- **`agent/*`——运行时实时表面。** 始终携带活的 `Agent`。拦截 waterfall（瀑布式事件）（`agent/pre-step`、`agent/request`、`agent/request-error`）负责变换、拒绝或恢复；awaited `agent/turn-stopping` 观察停止边界；瞬态 emit 报告生命周期、状态、inbox 插入／领取／丢弃与错误。轮次和步骤边界不在此处——它们是持久的会话事件，从 `session/event` 读取；token 流（`assistant/chunk`）和中途 steering（以 `user/message` 呈现）同理。
+- **`agent/*`——运行时实时表面。** 始终携带活的 `Agent`。拦截 waterfall（瀑布式事件）（`agent/pre-step`、`agent/request`、`agent/request-error`）负责变换、拒绝或恢复；awaited `agent/turn-stopping` 观察停止边界；瞬态 emit 报告生命周期、状态、inbox 插入／领取／丢弃与错误。轮次和步骤边界不在此处——它们是持久的会话事件，从 `session/event` 读取；token 流（`assistant/chunk`）和作为一条 `user/message` 的轮次中途 steering（中途引导）同理。
 - **`tools/*`——工具注册表与执行 seam。**
 
 **边界规则：** 持久的、可回放的事实是 `SessionEvent`；实时拦截或瞬态/活对象信号是 `agent`/`tools` Cordis 事件。轮次或步骤边界是持久事实，因此存在于会话日志中并从 `session/event` 源读取——不会被镜像为 `agent/*` emit。
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
index 2926746ee1..1b5962f672 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
 2026-07-05-reconstructable-requests.md: ebca9b99cad791159302da9c2bbce9f4df147aab
-2026-07-05-reconstructable-requests.zh.md: 91ef3fd04502f2c2f092da60a8bd909cf7fa25df
+2026-07-05-reconstructable-requests.zh.md: e7ed83bbc553e86d53d88e442b0fd8992973c9e7
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
index 91ef3fd045..e7ed83bbc5 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
@@ -47,9 +47,9 @@ Status: implemented
 ## 后果
 
 - 一个日志无法解释的请求不可能被意外构造——无论是循环还是监听器；变异已构建的请求会抛异常；每个 header 变更都是持久的、可 diff 的日志事件。
-- 模型可见上下文使用已记录消息通道。`agent.inject()` 与工具 `additionalContexts` 进入 inbox，等待后续领取；必须与当前已领取批次一起结算的上下文由 `agent/pre-step` 返回。每个进入步骤的值都是带来源的持久 `user/message`，只付出一次代价并在后续成为可缓存前缀，代价是会在历史中累积直至压缩。
-- 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身的 reasoning-content 排除由服务端管理。
+- 模型可见上下文使用已记录消息通道。`agent.inject()` 与工具 `additionalContexts` 进入 inbox，等待后续领取；必须与当前已领取批次一起结算的上下文由 `agent/pre-step` 返回。每个进入步骤的值都是带来源的持久 `user/message`，只付出一次代价，此后即被前缀缓存，代价是会在历史中累积直至压缩。
+- 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身对思考内容的排除由服务端管理。
 - `agent/pre-step` 是当前请求的消息 seam；直接修改 inbox 则是最终进入后续请求的 seam。
-- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存击穿由相同的压力逻辑批量处理。
+- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存失效由相同的压力逻辑批量处理。
 - 会话日志每个循环实例增长一个 `request/header` 快照，并在真正变更时增加快照。它比 delta 编解码器更大，但相对分片密集型日志仍然很小，并只保留一种回放表示。`SESSION_FORMAT_VERSION` 保持 `0`；旧的 delta 事件被拒绝而非迁移。
 - 快照预期输出变更一次（每个 transcript（文本记录）增加其 header 事件）；写入文件系统的 fixture（测试前置数据）以规范化的撰写形式存储，工具参数使用 cwd 相对路径，因为回放只对 cwd 无关的参数路径做往返。
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
index cefb0b0dd2..03acf306b4 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
 2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 6fbd5e2c9d57da3f25c72c652ca50eb45b84323c
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: c46b3eeeb446165192ef44de938c9a5a657a02f8
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 8a480999038cf892842290e3ea3902683d87e431
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
index c46b3eeeb4..8a48099903 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
@@ -22,9 +22,9 @@ Compact-basic 会在每个拟议请求之前包装 `agent/pre-step`。在续步
 
 ### 请求恢复只覆盖最终模型边界
 
-`agent/request-error` 表示来自最终适配器边界的终止失败。适配器选择、分发、iterator 构造与迭代抛出会在 agent loop 消费前成为终止 `error` 或 `aborted` finish；适配器直接发出的终止 finish 进入同一路径。提示词装配、请求 middleware、请求日志、结果处理、工具、step 监听器与清理仍属于普通失败。[LLM 流的终止失败](2026-07-29-terminal-llm-stream-failures.md)规定这一规范化边界。
+`agent/request-error` 表示来自最终适配器边界的终止失败。适配器选择、分发、iterator 构造与迭代抛出会在 agent loop（智能体循环）消费前成为终止 `error` 或 `aborted` finish；适配器直接发出的终止 finish 进入同一路径。提示词装配、请求 middleware、请求日志、结果处理、工具、step 监听器与清理仍属于普通失败。[LLM（大语言模型）流的终止失败](2026-07-29-terminal-llm-stream-failures.md)规定这一规范化边界。
 
-恢复运行前，失败 step 已经关闭。负责处理的监听器修复持久状态、返回 `{ kind: 'retry' }`，并停止 waterfall 委托。循环随后关闭失败 turn，并从持久日志开启一个重试 turn，中间不发布空闲通知。重试策略与尝试计数由插件自己拥有；compact-basic 在链路到达终态 `agent/settled` 时清除对应 agent 的溢出计数。两个 DeepSeek 适配器都把识别出的提供方上下文限制错误规范化为 `CONTEXT_WINDOW_EXCEEDED`。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回边界。
+恢复运行前，失败 step 已经关闭。负责处理的监听器修复持久状态、返回 `{ kind: 'retry' }`，并停止 waterfall（瀑布式事件）委托。循环随后关闭失败 turn，并从持久日志开启一个重试 turn，中间不发布空闲通知。重试策略与尝试计数由插件自己拥有；compact-basic 在链路到达终态 `agent/settled` 时清除对应 agent 的溢出计数。两个 DeepSeek 适配器都把识别出的提供方上下文限制错误规范化为 `CONTEXT_WINDOW_EXCEEDED`。[重试动作决策](../simplification/2026-07-27-request-error-retry-action.md)规定这一返回边界。
 
 如果取消发生在 assistant 工具调用已经持久化之后、所有调用完成分发之前，循环会为每个尚未分发的调用记录一对合成的 `tool/call` 与 aborted `tool/result`，随后进入正常中止路径。因此，表层不会仅因取消赢得竞态而留下孤立的持久工具调用。
 
@@ -42,7 +42,7 @@ Compact-basic 会在每个拟议请求之前包装 `agent/pre-step`。在续步
 
 ## 测试
 
-单元测试覆盖最终适配器规范化边界、已关闭 turn 的重试编号与重置、取消与销毁、step 边界顺序、已路由信封压力、压力门控剪枝、剪枝独立解除压力、从已剪枝输入生成摘要、平衡溢出缩减、后续失败前已落盘的剪枝进展、generation 证明、上限、委托与辅助调用路由。真实循环测试覆盖抛出式和带内溢出，并验证剪枝或摘要压缩后的重试请求从替换表层重建。
+单元测试覆盖最终适配器规范化边界、已关闭 turn 的重试编号与重置、取消与销毁、step 边界顺序、已路由信封压力、压力门控剪枝、剪枝独立解除压力、从已剪枝输入生成摘要、平衡溢出缩减、后续失败前已落盘的剪枝进展、generation 证明、上限、委托与辅助调用路由。真实循环测试覆盖抛出式和带内溢出在经剪枝或摘要压缩后重建重试请求的过程。
 
 ## 考虑过的替代方案
 
@@ -58,4 +58,4 @@ Compact-basic 会在每个拟议请求之前包装 `agent/pre-step`。在续步
 
 代价是在共享 pre-step waterfall 中执行压力工作，并需要适配器持续维护溢出分类。提供方措辞与启发式字符密度仍是维护风险。表层压缩依然无法修复仅信封本身就超出窗口的情况，也不能拆分不可分割的非工具节点，或修复非可剪枝剩余部分仍然过大的工具单元。若可移除的文本工具结果是主要体积，可选剪枝器仍可修复原本不可分割的工具配对。
 
-[已领取 pre-step 生命周期](2026-07-31-claimed-pre-step-inbox-lifecycle.md)取代了本记录原先的 post-step 触发方式。服务拆分、独立 token meter、平衡范围契约、日志记录锁、摘要替换与唯一 `summarize()` 子类 hook 均保持不变。
+[已领取 pre-step 生命周期](2026-07-31-claimed-pre-step-inbox-lifecycle.md)取代了本记录原先的 post-step 触发方式。服务拆分、独立 token meter、平衡范围约定、日志记录锁、摘要替换与唯一 `summarize()` 子类 hook 均保持不变。
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
index e1d9a10415..831d3c790f 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
 2026-07-22-unified-send-and-coalesced-user-messages.md: f32d6ca65d5236e1fabdd177cdf54e36929c853f
-2026-07-22-unified-send-and-coalesced-user-messages.zh.md: 7647742166bb760139506f93af672f323b3b7b97
+2026-07-22-unified-send-and-coalesced-user-messages.zh.md: af829714276b1a77b8147d89a9be1c9ff6a007a5
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
index 7647742166..af82971427 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
@@ -18,13 +18,13 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send`
 
 **context/message 已移除。** 注入的上下文在 inbox 中使用同一个 `UserMessage` 值，并在获准时成为 `user/message` 事件；上下文生产方显式提供合适的非 `user` 类别 `source`，类型化 source 变体携带所有特定于领域的持久来源信息。对外接口、派生逻辑和 `SurfaceEventType` 都不再包含 `context/message`；需要判断“这是不是一条人类提示词？”的消费方改为读取 `source.kind === 'user'`，而不是事件类型。
 
-**Goal 继续执行归属使用正数 Round。** Goal 生命周期状态通过后续 [Goal 自有持久事件决策](2026-07-31-goal-owned-durable-events.md)定义的领域自有 `goal/change` 事件提交。正数 Round 只从已准入的继续执行 `user/message` 推进；goal 持久化不使用注入或 inbox 状态。
+**Goal 继续执行归属使用正数 Round。** Goal 生命周期状态通过后续的[Goal 自有持久事件决策](2026-07-31-goal-owned-durable-events.md)所定义的领域自有 `goal/change` 事件提交。正数 Round 只从已准入的继续执行 `user/message` 推进；goal 持久化不使用注入或 inbox 状态。
 
 **`send` 不返回标识。** 调用方已经持有完整消息及其不透明的 `MessageId`；消息的创建与冻结由[带标识的不可变消息值决策](2026-07-28-identified-immutable-message-values.md)负责，而不是由路由负责。
 
 **Inbox 变更只有一份持久投影和三种最小实时通知。** 每次 append、prepend、编辑、删除、取消与领取都会记录规范化的 `agent/inbox/spliced` 坐标。插入会发出 `agent/inbox/inserted { message }`；普通删除携带持久 `outcome: 'canceled'`，并发出 `agent/inbox/discarded { message }`；循环的原子 `claim()` 会记录纯删除 splice，随后发出 `agent/inbox/claimed { message, turn }`。`MessageId` 是唯一的单次出现标识，并在两个待处理列表间保持唯一。实时载荷刻意不携带 placement、outcome 或批次封套，因为这些事实由持久 splice 持有。
 
-**pre-step 会领取 next-step 输入，但不会为它单独创建轮次。** steering 和注入始终进入同一个 next-step inbox；steering 会唤醒驱动器，注入则不会。在轮次边界，驱动器会原子领取待处理的 next-step 输入，再领取一条排队提示词；在步骤之间则只领取 next-step 输入。领取会记录纯删除 splice，并针对每条消息发出一次 `agent/inbox/claimed { message, turn }`。随后 `agent/pre-step` 会拒绝拟议步骤，或返回进入步骤的完整批次。reject 与监听器失败都会让已领取批次保持已删除；领取后才到达的输入会等待后续边界。
+**pre-step 会领取 next-step 输入，但不会为它单独创建轮次。** steering 和注入始终进入同一个 next-step inbox；steering 会唤醒驱动器，注入则不会。在轮次边界，驱动器会原子领取待处理的 next-step 输入，再领取一条排队提示词；在步骤之间则只领取 next-step 输入。领取会记录纯删除 splice，并针对每条消息发出一次 `agent/inbox/claimed { message, turn }`。随后 `agent/pre-step` 会拒绝拟议步骤，或返回进入步骤的完整批次。拒绝与监听器失败都会让已领取批次保持已删除；领取后才到达的输入会等待后续边界。
 
 **一条已接受消息只保留一种表示。** 持久的用户角色输入和附加的模型可见上下文都直接使用带标识且冻结的 `UserMessage`。循环把该值与私有路由状态存放在一起，不会将其标识、内容或来源复制到另一种公开形状中。steering、注入和工具产生的上下文都会在 next-step inbox 中保留各自带标识的消息。[带标识的不可变消息值决策](2026-07-28-identified-immutable-message-values.md)取代了本记录此前的 `UserMessageData`/`AgentMessage` 层级，并将这一表示扩展到 assistant 消息和工具结果消息。
 
@@ -41,7 +41,7 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send`
 
 ## 后果
 
-投递接口现在是一个原语加三个自解释的预设，(`target` × `wakeup`) 矩阵把此前无法表达的组合显式化。同一个带标识消息值同时服务提示词、注入的上下文和 Goal Round，因此每一处“是否人类提示词？”检查都简化为一次 `source` 判断。`Agent` 契约仍是接口，因此其他实现和对象字面量形式的测试替身只需实现同一个最小结构接口。正数 Goal Round 从已准入的 `user/message` 事件折叠，而 goal 生命周期状态位于投递接口之外。空闲注入会保持待处理，不打开轮次也不运行模型；后续会唤醒的投递在 pre-step 将其放入进入步骤的批次时，它才成为 `user/message`。
+投递接口现在是一个原语加三个自解释的预设，(`target` × `wakeup`) 矩阵把此前无法表达的组合显式化。同一个带标识消息值同时服务提示词、注入的上下文和 Goal Round，因此每一处“是否人类提示词？”检查都简化为一次 `source` 判断。`Agent` 约定仍是接口，因此其他实现和对象字面量形式的测试替身只需实现同一个最小结构接口。正数 Goal Round 从已准入的 `user/message` 事件折叠，而 goal 生命周期状态位于投递接口之外。空闲注入会保持待处理，不打开轮次也不运行模型；后续会唤醒的投递在 pre-step 将其放入进入步骤的批次时，它才成为 `user/message`。
 
 `wakeup` 是“模型是否应当运行”的信号，因此 inbox 会区分能唤醒的排队工作与任何可领取的项：一个孤立的 `next-turn`/no-wakeup 队列项会停泊在空闲状态，并随下一次唤醒 send 一同带出，而 `whenIdle`/`cancel` 依据唤醒信号来结算完全停稳。每次插入与退出都会发布对应的实时通知，特定于领域的持久事实则通过类型化消息 source 传递，而非通过平行的元数据通道。直接使用待处理消息的表示方式，使持久 splice 与实时事件保持可关联，既无需维护第二个 steering 包装层，也避免数据发生分歧。后续的[已领取 pre-step inbox 生命周期](2026-07-31-claimed-pre-step-inbox-lifecycle.md)决策保留通过 `MessageId` 寻址的实时队列变更，并把单消息生命周期通知与持久的整体队列 splice 投影分离。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
index 09f0c27732..0c59d69ead 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.md
 2026-07-23-toolview-dissolution.md: be1bd9d161714194855988d76a632c667fae8c84
-2026-07-23-toolview-dissolution.zh.md: afe5e03e8345fca2a0f097d86873974f6d417ff2
+2026-07-23-toolview-dissolution.zh.md: c3f301002aac4c443dedc76fa747d8b45be6577a
diff --git a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
index afe5e03e83..c3f301002a 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-toolview-dissolution.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-23-toolview-dissolution.md) | 中文
 
-> 范围：独立工具环（ToolViewRegistry/ctx.toolviews/outlet）为何退役、被什么取代。本决策产出的落地态叙述归 [Web 客户端架构注](2026-07-19-gui-web-client-architecture.md)；一切现在所运行其上的注册模型归 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md)所有。后续的 [Client Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)决策仅取代本篇的 per-view 放置方式：Tool 名称分发仍使用 keyed slot，而非平行注册表。
+> 范围：独立工具环（ToolViewRegistry/ctx.toolviews/outlet）为何退役、被什么取代。本决策产出的落地态叙述归 [Web 客户端架构注](2026-07-19-gui-web-client-architecture.md)；一切现在所运行其上的注册模型归 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 所有。后续的 [Client Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md) 决策仅取代本篇的 per-view 放置方式：Tool 名称分发仍使用 keyed slot，而非平行注册表。
 
 ## Problem
 
@@ -14,15 +14,15 @@ Status: implemented
 
 工具环作为独立基础设施已消失：工具行是**各视图为自己声明的 keyed 子槽**，client 全域只剩一种注册模型。上述理由是空的——keyed slot 的 *key 空间*本就运行时开放（SlotMap 声明槽、从不声明 key；ask-user composer 的 `key: 'question'` 即先例），开放的 tool 名集合天然适配 `entryKey` 分发。
 
-本决策最初把 `'conversation.chat.toolview'` 放在 chat 条目下，由 chat 渲染点逐行分发。后续的 [Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)引入整体 Tool 席位，并让 `ui-tool` 拥有唯一的 keyed `'tool.call.toolview'` 子 slot。后续决策改变的是展示所有者，而非本决策的核心约束：Tool 注册继续使用普通 keyed-slot 机制，激活、替换、缓存、错误隔离、版本与 fallback 行为仍归框架所有。
+本决策最初把 `'conversation.chat.toolview'` 放在 chat 条目下，由 chat 渲染点逐行分发。后续的 [Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md) 将该放置方式移入整体 Tool 席位，并让 `ui-tool` 拥有一个 keyed `'tool.call.toolview'` 子 slot。后续决策改变的是展示所有者，而非本决策的核心约束：Tool 注册继续使用普通 keyed-slot 机制，激活、替换、缓存、错误隔离、版本与 fallback 行为仍归框架所有。
 
 ## 接受的语义变化
 
-四项行为增量是刻意接受而非疏漏。跨视图出场最初采用逐视图注册；后续 Note 记录了 root/subcall 编排为何足以支持一个 Tool 级展示所有者。同 key 重复注册从注册表的 later-wins 静默覆盖变为 loud throw——纪律修正而非损失。会话维分发若行需要，归组件内部（标配 kit 已带 `useSessions`），不走注册表谓词——今天没有已落地的会话变体样例。第三方在 registry 级覆盖形态（scoped 注册压过 global）不复存在；真出现的未来需求走 key 命名空间约定或组件内小 resolver，永不复活平行注册表。
+四项行为增量是刻意接受而非疏漏。跨视图出场最初采用逐视图注册；后续 Note 记录了为何 root/subcall 编排后来证明由一个 Tool 级展示所有者统一负责是合理的。同 key 重复注册从注册表的 later-wins 静默覆盖变为 loud throw——纪律修正而非损失。会话维分发若行需要，归组件内部（标配 kit 已带 `useSessions`），不走注册表谓词——今天没有已落地的会话变体样例。第三方在 registry 级覆盖形态（scoped 注册压过 global）不复存在；真出现的未来需求走 key 命名空间约定或组件内小 resolver，永不复活平行注册表。
 
 ## Alternatives considered
 
-**保留独立注册表（原形态）。** 拒绝：其多维分发的每一维都有更正确的家——展示所有权归显式声明的子 slot，会话维归已持有标配 kit 的组件内部。两步移完后剩下的只是一份没有任何独有能力的 slot 机器副本。
+**保留独立注册表（原形态）。** 拒绝：其多维分发的每一维都有更正确的家——展示所有权归显式声明的子 slot，会话维归已持有标配 kit 的组件内部。剩下的只是一份没有任何独有能力的 slot 机器副本。
 
 **把 `renderToolView` 提进标配 kit、注册表迁入 runtime 包。** 拒绝：Tool 展示是 Client UI 词汇；上提进 runtime 会把展示概念泄漏进数据对象层，且依然留着两套注册模型。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
index ae7f689398..4be81330b6 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
 2026-07-24-separate-context-injection-from-turn-execution.md: bb28d96cf1494d94ad7a7d4a4714e536c7072d2f
-2026-07-24-separate-context-injection-from-turn-execution.zh.md: fa9b9275cae67f4d5a34dac8a0236558596ab28f
+2026-07-24-separate-context-injection-from-turn-execution.zh.md: 6debc6cf5e8fb7358ca8697fa64f175fb700d991
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
index fa9b9275ca..6debc6cf5e 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
@@ -68,7 +68,7 @@ enter 分支的 `PreStepDecision.messages` 是拟议步骤的完整批次。wate
 
 ## 后果
 
-- idle 注入要到后续 pre-step 让它进入步骤后才会对模型可见，并可能被取消或 dispose 丢弃，而其持久 inbox 生命周期仍会保留记录。
+- idle 注入只有在后续 pre-step 接纳它后才会对模型可见，并可能被取消或 dispose 丢弃，而其持久 inbox 生命周期仍会保留记录。
 - 两条连续的 user-role 消息会取代一条烘焙后的提示词消息；提供方适配器会保留这一顺序。
-- 必须影响当前请求的上下文要从 `agent/pre-step` 返回；普通注入只保证由最近的后续边界交付。
+- 必须影响当前请求的上下文要从 `agent/pre-step` 返回；普通注入只支持在最近的后续边界交付。
 - 公共投递契约和收件箱记录保持精简：没有上下文附件、上下文放置元数据、提示词封套或重复的持久事件类型。
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
index 9c8308be74..7e3c02691b 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
 2026-07-25-web-client-session-scope-and-provide-channel.md: 3c51f06fca23a495f0fbc0cc4f1c289edea07b3b
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 06fc1005785d9d11b52839f91c3bb4b99cad7d63
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 1319a0d5a4eba4d70b0268605a0957c9a2eca7a9
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
index 06fc100578..1319a0d5a4 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-25-web-client-session-scope-and-provide-channel.md) | 中文
 
-> 范围：client Agent scope（actx）与定向事件、client/host 实体化对等模型、空会话 blank 位与复用（`connectWorkspace`）、per-session 供数通道（`sessions.provide`），以及承载这些能力的 host wire 小件（summary `blank` 列、`host/session-added` 帧字段、`host/commands-changed` 帧）。输入状态机与 slash 管线见[输入状态机 note](2026-07-25-web-input-machine-and-slash-pipeline.md)；命令业务面见[命令业务面 note](2026-07-25-web-command-surfaces-and-assembly.md)。
+> 范围：client Agent scope（actx）与定向事件、client/host 实体化对等模型、空会话 blank 位与复用（`connectWorkspace`）、逐会话供数通道（`sessions.provide`），以及承载这些能力的 host wire 小件（summary `blank` 列、`host/session-added` 帧字段、`host/commands-changed` 帧）。输入状态机与 slash 管线见[输入状态机 note](2026-07-25-web-input-machine-and-slash-pipeline.md)；命令业务面见[命令业务面 note](2026-07-25-web-command-surfaces-and-assembly.md)。
 
 ## 问题
 
@@ -74,7 +74,7 @@ Session 实例与 scope 同生命周期，存活资格 = host listed（一个判
 
 `workspaces.connectWorkspace(workspaceId): Promise<SessionId>`（归属 WorkspacesService——它同时持有 workspace 规范 path 与 sessions 引用）：
 
-- 复用臂：list mirror 中找 `blank && cwd == workspace.path && sessionIds.includes(id)`——host 自己的成员规则，绝不只按 cwd。没有账户槽位的 cwd 匹配（CLI/TUI 在 host cwd 创建的会话，或已删除/重建的注册）会打开一个任何分组表面都无法显示在该工作区下的会话，因此落到新建臂（见[成员复用修复](../bug-fix/2026-08-05-workspace-blank-session-reuse-membership.md)）；命中直接返回该 id，不新建。
+- 复用臂：list mirror 中找 `blank && cwd == workspace.path && sessionIds.includes(id)`——host 自己的成员规则，绝不只按 cwd。没有账户槽位的 cwd 匹配（CLI（命令行界面）/TUI 在 host cwd 创建的会话，或已删除/重建的注册）会打开一个任何分组表面都无法显示在该工作区下的会话，因此落到新建臂（见[成员复用修复](../bug-fix/2026-08-05-workspace-blank-session-reuse-membership.md)）；命中直接返回该 id，不新建。
 - 新建臂：未命中则 `session.create({workspaceId})`，返回新 id。
 - 未知 workspaceId fail loud（不静默创建到别处）。
 - 解析保证（两臂同契约）：promise resolve 时返回的 id 已在 list store 且 `sessions.binding(id)` 同步可解析——`SessionsService.create` 在 RPC 成功后同步投影列表再 resolve，使 draft 搬运方可以在 open 之前往新 scope 的 machine 写文本，不等 notifier flush。
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
index 9994bcb3b9..1f44d8b4b7 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
 2026-07-27-dispose-ladder-to-consumer.md: e9af88e8e7ef962213a74e96a249241cbe8d5994
-2026-07-27-dispose-ladder-to-consumer.zh.md: 89f8e107c56d42787c59bc6f8fa8fc7b3ef73208
+2026-07-27-dispose-ladder-to-consumer.zh.md: 74cbc624e9153637dcdceb521c04af811799fdb0
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
index 89f8e107c5..74cbc624e9 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-阶梯移入其唯一消费方。`dsh-subagent-acp` 拥有 `disposeAcpChild(child, eofGraceMs)`，完全构建在 seam 的公开动词之上：关闭 `stdin`，以 `eofGraceMs` 约束一次 `waitForExit`，随后调用 `terminate()`（其 SIGTERM→spec 宽限期→SIGKILL 升级已拥有信号定时器），再无界等待 `waitForExit()`，由子进程责任方证明整棵进程树已经退出。seam 保留 `kill`／`terminate`／`waitForExit`——机制而非策略——而 `waitForExit(signal?)` 恰是消费方阶梯在协作层确认进程树真正退出所需的停稳探针，无需从终止宽限期再派生一个定时器。seam 的句柄少了一个方法和一个导出接口。
+阶梯移入其唯一消费方。`dsh-subagent-acp` 拥有 `disposeAcpChild(child, eofGraceMs)`，完全构建在 seam 的公开动词之上：关闭 `stdin`，以 `eofGraceMs` 约束一次 `waitForExit`，随后调用 `terminate()`（其 SIGTERM→spec 宽限期→SIGKILL 升级已拥有信号定时器），再无界等待 `waitForExit()`，由子进程所有者证明整棵进程树已经退出。seam 保留 `kill`／`terminate`／`waitForExit`——机制而非策略——而 `waitForExit(signal?)` 恰是消费方阶梯在协作层确认进程树真正退出所需的完全停稳探针，无需从终止宽限期再派生一个定时器。seam 的句柄少了一个方法和一个导出接口。
 
 ## 曾考虑的替代方案
 
@@ -20,4 +20,4 @@ Status: implemented
 
 ## 后果
 
-买到的：seam 少了一个方法和一个类型；实现只欠四个动词，不欠拆卸策略；协作式 EOF 时间窗与调节它的 ACP 配置字段住在一起，而终止时间窗与最终的整树退出等待仅由子进程责任方拥有。代价：未来想要 EOF 打头拆卸的后端需针对这些动词写约 20 行（或直接搬 ACP 的辅助函数）；阶梯的层级测试位于 ACP 套件，seam 套件转而钉住阶梯所组合的动词（升级前有界 `waitForExit` 返回假，升级后无界等待整棵进程树退出），而非组合后的策略。
+换来的是：seam 少了一个方法和一个类型；实现只需提供四个动词，无需提供拆卸策略；协作式 EOF 时间窗与调节它的 ACP 配置字段住在一起，而终止时间窗与最终的整树退出等待仅由子进程所有者拥有。代价：未来想要 EOF 打头拆卸的后端需针对这些动词写约 20 行（或直接搬 ACP 的辅助函数）；阶梯的层级测试位于 ACP 套件，seam 套件转而钉住阶梯所组合的动词（升级前有界 `waitForExit` 返回假，升级后无界等待整棵进程树退出），而非组合后的策略。
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
index 92a30e931c..fd4c24db70 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
 2026-07-29-dsh-source-launch-tsx-esm.md: aabe6c2d6a92b5cc6568eee1d42df3a6998cf0ca
-2026-07-29-dsh-source-launch-tsx-esm.zh.md: fdeb8a976e02bb9311a6ec9d097d09151a998a04
+2026-07-29-dsh-source-launch-tsx-esm.zh.md: ecda8b273b3efc4773dbe3ed25a9ef0572b79ce4
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
index fdeb8a976e..ecda8b273b 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-29-dsh-source-launch-tsx-esm.md) | 中文
 
-> 取代[已归档的原生 TypeScript 源码启动](../../archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md)：Node 移除了该决策所依赖的能力。
+> 取代[原生 TypeScript 源码启动](../../archived/architecture/2026-07-28-dsh-native-typescript-source-launch.md)：Node 移除了该决策所依赖的能力。
 
 ## 问题
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
index 5524e0d54d..ae2347a7be 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
 2026-07-29-request-level-llm-config-credentials.md: 238400ea41f25a716729d1721c113645c2c8ba72
-2026-07-29-request-level-llm-config-credentials.zh.md: b0d04d4303bf0ccf5ebc74af8c4a3e493f861d63
+2026-07-29-request-level-llm-config-credentials.zh.md: b2075798c9eb77d8fd8baecbbea77993ccda328f
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
index b0d04d4303..b2075798c9 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 **按请求解析，而非重建 fiber。**适配器改为接收一个 options thunk（外加按流调用的凭据解析器），不再持有冻结的构造期事实，每个操作解析一次——即 Pi 的模式，连同其经测试固定的语义：跨越一次变更的两个请求看到两份配置，一个请求恰好解析一次，进行中的流保持其起始事实。这删掉了重建式设计所需的整套切换机制（`DUPLICATE_ADAPTER` 顺序问题、`NO_ADAPTER` 窗口、延迟激活状态机），并把密钥缺失变成*请求时*可行动的失败（`MISSING_CREDENTIAL` 点名每个配置入口），同时路由保持注册、catalog 保持可浏览。唯一在注册期捕获的事实——`ctx.llm` 注册表在 `registerAdapter` 时快照的重试策略（外加 pi-ai 的路由*集合*）——在其变化时于一个同步区段内原地重新注册同一适配器实例。
 
-**机密是引用，值藏在 `ctx.credentials` 背后。**配置（两个面）携带 `apiKeyEnv: DEEPSEEK_API_KEY`；三包凭据 seam 按操作解析它。`credentials-local` 把活跃进程环境（只读、优先——启动时覆盖是操作者意图，必须*可见地*只读，因此被遮蔽的写入直接拒绝而不是表面成功）叠加在 provider 管理的文档之上（可写、重载时整体替换快照使删除的条目绝不滞留——来自 Claude Code 增量重放（additive reapply）的教训）。该文档当时是 dotenv 形式的 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，并让旧路径转为用户的环境层。适配器通过 seam 解析该引用；仅在未挂载 seam 时，才通过各环境层解析。
+**机密是引用，值藏在 `ctx.credentials` 背后。**配置（两个面）携带 `apiKeyEnv: DEEPSEEK_API_KEY`；三包凭据 seam 按操作解析它。`credentials-local` 把活跃进程环境（只读、优先——启动时覆盖是操作者意图，必须*可见地*只读，因此被遮蔽的写入直接拒绝而不是表面成功）叠加在提供方管理的文档之上（可写、重载时整体替换快照使删除的条目绝不滞留——来自 Claude Code 增量重放（additive reapply）的教训）。该文档当时是 dotenv 形式的 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，并让旧路径转为用户的环境层。适配器通过 seam 解析该引用；仅在未挂载 seam 时，才通过各环境层解析。
 
 **按插件划分 namespace，schema ≡ `Config`。**每个适配器注册自己的 namespace（`llm-deepseek`、`llm-pi-ai`），schema 用其插件 `Config` schema，组合 `base` 用其 `cordis.yml` 条目——settings 分节与 entry 配置是同一种 YAML 形状，`resolveAdapterOptions`/`resolveProfiles` 对两者仍是唯一的显式 resolve 步骤。存活快照若违反 schema 之外的约束，则保留最后可用事实（seam 的最后可用值哲学向上延伸一层）；entry 配置本身仍会加载失败。pi-ai 的 `providers` 改为以路由为键的字典，base 层与用户层因此按提供方合并，路由集合也由结构直接表达；数组形状响亮失败并给出迁移指引，而空字典是合法的休眠姿态——组合可以裸挂该适配器，把每一条路由都留给用户面决定。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index 4becd41658..15189e7387 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
 2026-07-30-credential-boundaries-and-atomic-registration.md: 94b32c3cfaa3e1c5059573881a2f393d29aed3ac
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 2506ce391c9125323faf107e3c04c52785e0cc98
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 088e24cbfd7db9da73c2ed3e3d11fdef24249c37
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index 2506ce391c..088e24cbfd 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 ## 决策
 
-**凭据文档只归凭据提供方所有。**没有任何一个面会把它加载进 `process.env`。当时该文档是 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，因此如今被加载的正是那条旧路径——作为用户的普通环境层，其中不含任何 provider 管理的密钥。真正的启动环境，以及调用目录中由 bin 加载的 `.env`，仍然是那一层只读的环境来源，因此不挂载该提供方的组合，解析密钥的方式与从前完全一致，而存下的密钥跨重启仍然来源于文件、仍然可写——这一点由 Loader 组合中的一次真实重启来证明，而不是靠对 `describe()` 的单元断言。
+**凭据文档只归凭据提供方所有。**没有任何一个面会把它加载进 `process.env`。当时该文档是 `$DSH_HOME/.env`；[凭据文档拆分](2026-08-04-credentials-yaml-and-user-environment-layer.md)后来把它移到 `$DSH_HOME/.credentials.yaml`，因此如今被加载的正是那条旧路径——作为用户的普通环境层，其中不含任何提供方管理的密钥。真正的启动环境，以及调用目录中由 bin 加载的 `.env`，仍然是那一层只读的环境来源，因此不挂载该提供方的组合，解析密钥的方式与从前完全一致，而存下的密钥跨重启仍然来源于文件、仍然可写——这一点由 Loader 组合中的一次真实重启来证明，而不是靠对 `describe()` 的单元断言。
 
 **存下的凭据对模型没有边界，而 README 就是这么写的。**`0700` 目录下的 `0600` 挡得住其他 OS 用户；模型的 bash 与文件系统工具正是以同一用户身份运行，而已交付的默认值不约束任何东西。harness 真正守住的更窄，也就照这个宽度写下来：没有任何一个面会把该文档提升进 `process.env`，模型也从不会拿到它的解析后路径，因此要拿到这个值，需要刻意去读一条并未交给它的路径。OS 钥匙串（keychain）提供方——一个模型的进程根本读不到的存储——被记录为真正的答案，而不是靠一个残缺的方案去暗示它。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
index 1c04f72d28..6c9f7d8ce0 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
 2026-07-30-web-config-plane.md: 483058c8a24ad8c414278eba84f4226e973f2923
-2026-07-30-web-config-plane.zh.md: 9247aac52401cd570d37f4aad47d9da6bb194d19
+2026-07-30-web-config-plane.zh.md: 840ac7f2e46c82e7b858c353086e1a9541db563e
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
index 9247aac524..840ac7f2e4 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
@@ -12,7 +12,7 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 ## 决策
 
-**wire 领域挂上编译期 RPC 映射，拒绝落为错误码，失效落为帧。**`settings.describe/openDocument/update/replace/mutate`、`credentials.describe/set/unset`、`llm.providers` 与 `llm.models`（认领预留的 `host.listModels` 面）一同加入 `RpcMethodMap`，七处由编译器锁定的接线位点因此让契约、schema、处理器与客户端保持步调一致。seam 侧的拒绝折叠为 `settings-rejected {ns}`/`credential-rejected {ref}` 业务错误（HTTP 仍只是载体），三个 `HostFrame`——`host/settings-changed {ns}`、`host/credentials-changed {ref}`、`host/models-changed`——沿用 `host/commands-changed` 的形状，因此每个客户端都无需轮询即可收敛。settings 读取、原生操作与写入和 `pickDirectory`/`openPath` 一起进入连接守卫的特权集合：回环 + 同源，否则 403，因为暴露在局域网上的 dsh web 绝不能接受来自其他源的配置访问。
+**wire 领域挂上编译期 RPC 映射，拒绝落为错误码，失效落为帧。**`settings.describe/openDocument/update/replace/mutate`、`credentials.describe/set/unset`、`llm.providers` 与 `llm.models`（认领预留的 `host.listModels` 面）一同加入 `RpcMethodMap`，七处由编译器锁定的接线位点因此让约定、schema、处理器与客户端保持步调一致。seam 侧的拒绝折叠为 `settings-rejected {ns}`/`credential-rejected {ref}` 业务错误（HTTP 仍只是载体），三个 `HostFrame`——`host/settings-changed {ns}`、`host/credentials-changed {ref}`、`host/models-changed`——沿用 `host/commands-changed` 的形状，因此每个客户端都无需轮询即可收敛。settings 读取、原生操作与写入和 `pickDirectory`/`openPath` 一起进入连接守卫的特权集合：回环 + 同源，否则 403，因为暴露在局域网上的 dsh web 绝不能接受来自其他源的配置访问。
 
 **`describe()` 增加分层与结构化 secret 脱敏。**`SettingsDescriptor` 在生效值之外携带 `base`/`user`，表单据此按「字段是否出现在用户层」来标记「已覆盖」，而非按值是否不等（与 base *相等*的覆盖仍然是覆盖）。`describe({ redactSecrets: true })`——在每个 wire 面都强制启用——经由对 schema 的纯结构遍历（object/dict/array 容器；secret 角色子树整体是一个不透明叶节点）从全部三层剥除 `role('secret')` 子树，并把剥除的槽位枚举为 `{path, set}`，页面因此不必收到任何值就能渲染只写输入框。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml
index 2ede6629d7..2930ae70e4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-21-compaction-summary-prefix-cache-reuse.md
 2026-07-21-compaction-summary-prefix-cache-reuse.md: fb6524846f837b783423b3ed0e043cd4e1f7849d
-2026-07-21-compaction-summary-prefix-cache-reuse.zh.md: e6072313b7089b9dda14c298fcb94db786220501
+2026-07-21-compaction-summary-prefix-cache-reuse.zh.md: 96adc31d6d6c50b4e6bfee32a5b89388a33a6939
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md
index e6072313b7..96adc31d6d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.zh.md
@@ -42,4 +42,4 @@ Status: implemented
 
 - **单元：** `compact-basic.spec.ts` 断言辅助调用转发 `system`/`tools`/前导消息，并把压缩指令作为最后一条消息追加，且 `compactRegion` 回放最新的已路由 header 前缀。现有的内容断言通过回放的消息而非 transcript 字符串来读取摘要器输入。
 - **循环：** `compact-loop-repro.spec.ts` 依据摘要请求尾部 user 消息中的压缩指令对其分类，溢出恢复测试则继续在真实循环中固定对话请求与摘要请求的数量。
-- **快照：** 无密钥回放会从带标记的 `compact/summary` 重建一条规范成功流；[compaction-seam Agent Note](../feature/2026-06-18-compaction-capability-seam.md) 负责持久标记契约。
+- **快照：** 无密钥回放会从带标记的 `compact/summary` 重建一条规范成功流；[compaction-seam Agent Note](../feature/2026-06-18-compaction-capability-seam.md) 负责持久标记约定。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
index 3021149a93..05d9cfd033 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-21-semantic-session-checkpoints.md
 2026-07-21-semantic-session-checkpoints.md: 697d878dccbfab1ded9f73e134d594ba6f0665e1
-2026-07-21-semantic-session-checkpoints.zh.md: c6184b0b00db16f9e318f4cbd148b1f0525f03a5
+2026-07-21-semantic-session-checkpoints.zh.md: e4d432cfa4655fcf6b010ab944dc12095eca009c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
index c6184b0b00..e4d432cfa4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-`dsh-session-checkpoint-policy` 以零配置插件的形式与持久化后端共同加载，并负责语义持久性屏障。在 `agent/pre-step` 时，该插件会在推导下一个请求前刷新待持久化的提示词输入或前一批响应/结果。该插件惰性包装 `llm/stream`，在记录 `request/header` 之后、构造适配器流之前，刷新活动会话。该插件还在有序的执行前策略之后包装顶层 `tools/execute`，在进入工具主体前刷新已记录的 `tool/call`；嵌套分发则复用外层模型可见调用。循环的最终 `turn/end` 检查点仍是轮次的收尾边界，并会在处理另一个已排队轮次或观察到空闲状态之前完成。
+`dsh-session-checkpoint-policy` 以零配置插件的形式与持久化后端共同加载，并负责语义持久性屏障。在 `agent/pre-step` 时，该插件会在推导下一个请求前刷新待持久化的提示词输入或前一批响应/结果。该插件惰性包装 `llm/stream`，在记录 `request/header` 之后、构造适配器流之前，刷新当前会话。该插件还在有序的执行前策略之后包装顶层 `tools/execute`，在进入工具主体前刷新已记录的 `tool/call`；嵌套分发则复用外层模型可见调用。循环的最终 `turn/end` 检查点仍是轮次的收尾边界，并会在处理另一个已排队轮次或观察到空闲状态之前完成。
 
 持久化与检查点调度仍是相互独立的 Cordis 插件。后端使请求的 `session/flush` 边界持久化，但不选择边界；只加载后端而不加载本策略仍是有效组合，并保留循环提供的较粗检查点。第一方持久化应用与运行时会显式加载两者，专用部署则可以有意省略或替换本策略。注册顺序决定其他 `agent/pre-step` 监听器追加的事件是否先于本检查点；提示词输入以及前一批由循环自身记录的助手消息与有序结果都已在日志中。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index bc05e497c5..684b2510f0 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-15-code-mode.md
 2026-06-15-code-mode.md: 99bbed3edab32512f88ece9694d6519a1f89c2dd
-2026-06-15-code-mode.zh.md: ca1bbe9ed3e412186763d1ed4fca9ed06669d4c3
+2026-06-15-code-mode.zh.md: d6f0887f421296818b6bba7a26fc662c246cc28a
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index ca1bbe9ed3..d6f0887f42 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -48,7 +48,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **子调用上下文通过父调用延后。** 在 `run_code` 内部注入会破坏父调用/结果的相邻性，因此 `ToolRunContext.deferContext()` 按分发顺序收集每个子结果的 `additionalContexts` 条目。即使程序后来抛出异常，注册表仍携带该数组；循环只在外层结果与步骤中所有兄弟结果之后追加每个条目。外层 post-execute 阻止会丢弃工具延后的条目，只暴露阻止 decision 显式附加的上下文。
 
-**并发是有界的，而非被序列化。** 每次 run 拥有一个分发队列，严格按提交顺序启动调用，并通过 `registry.executionMode` 对每个调用分类——与原生循环所用的 fail-closed `isConcurrencySafe` 契约相同。连续的 parallel 类调用最多重叠 `maxParallelSubCalls` 个（默认 10；设为 `1` 恢复串行分发）；exclusive 类调用会排空池并单独运行。结算时放弃尚未开始的排队调用。本 note 交付的是被序列化的占位实现；取代它的调度器由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
+**并发是有界的，而非被序列化。** 每次 run 拥有一个分发队列，严格按提交顺序启动调用，并通过 `registry.executionMode` 对每个调用分类——与原生循环所用的 fail-closed `isConcurrencySafe` 约定相同。连续的 parallel 类调用最多重叠 `maxParallelSubCalls` 个（默认 10；设为 `1` 恢复串行分发）；exclusive 类调用会排空池并单独运行。结算时放弃尚未开始的排队调用。本 note 交付的是被序列化的占位实现；取代它的调度器由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
 
 **呈现。** `run_code` 的 render intent 按[呈现意图 Agent Note](../architecture/2026-07-02-tool-render-intent-union.md)在此决定：`presentCall` 创建一个 `generic` 卡片，`kind: 'execute'`，以程序文本作为标题，并将同一程序文本作为 `rawInput`；`run_code` 有意不声明 `presentResult`，因此 TUI 和宿主/客户端运行时（Web）会通过通用原始内容回退机制，使用最终持久化的 `tool/result.content` 补全该卡片，其中包括捕获的日志，以及返回值、失败信息或 post-policy 输出落盘预览。这不是 `terminal` 卡片：该卡片的语义是「工作目录中的 shell 命令」，程序不是。参见[结果卡片完整性说明](../../archived/bug-fix/2026-07-20-code-mode-result-card-completeness.md)。
 
@@ -85,7 +85,7 @@ worker 运行时只能约束程序的运行，而不构成安全边界：模型
 
 ### 模型看到的内容
 
-SDK 指示模型编写一个所加载运行时语言的异步函数体（默认可擦除 TypeScript；Python 运行时下为 Python `async` 函数体——见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。两种 flavor 用各自的原语陈述同一契约：相互独立的只读调用可以在 `Promise.all`（TypeScript）或 `asyncio.gather`（Python）下重叠，有副作用的调用按提交顺序单独运行，有依赖的工作用 `await` 排序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
+SDK 指示模型编写一个所加载运行时语言的异步函数体（默认可擦除 TypeScript；Python 运行时下为 Python `async` 函数体——见[语言分发 note](2026-07-31-code-mode-language-dispatch.md)），通过 `await tools.name(args)` 调用工具，在需要时捕获被拒绝的工具调用，并仅 return 或 log 应重新进入上下文的输出。两种 flavor 用各自的原语陈述同一约定：相互独立的只读调用可以在 `Promise.all`（TypeScript）或 `asyncio.gather`（Python）下重叠，有副作用的调用按提交顺序单独运行，有依赖的工作用 `await` 排序。声明前缀可能与原生 schema 一样大，尤其在 `'both'` 下，但对提供方缓存保持稳定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index 1917b118da..230bcb69f5 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
 2026-06-18-compaction-capability-seam.md: 390d091fd6e6f7fa1694ba78b90522b70948fe92
-2026-06-18-compaction-capability-seam.zh.md: d72793e6adde911a8623ac1c6b65df899381923e
+2026-06-18-compaction-capability-seam.zh.md: 59eb899acae0352a019cfc5252365e0116f84597
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index d72793e6ad..59eb899aca 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -33,7 +33,7 @@ Status: implemented
 
 早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将契约重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
 
-`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
+`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV Cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
 
 ### 成功的持久步骤工作完成后运行自动压力检查
 
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
index 0369670aea..f17347689c 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-24-workspace-context.md
 2026-06-24-workspace-context.md: 53a580aee50752b7c6daeff5caa42ba6409c8885
-2026-06-24-workspace-context.zh.md: dc1d6b5dc2c9f576e7298c891a3a1145f123a8db
+2026-06-24-workspace-context.zh.md: 79e5b0014801878595d3a5d71b8c4b23c5aad996
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
index dc1d6b5dc2..79e5b00148 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-该实现在 `packages/context/workspace-context` 中，包（package）名为 `@deepseek-ai/dsh-workspace-context`。它是请求上下文扩展，不是核心服务或文件系统后端。共享 demo 主干与 Host Runtime 根据显式的 `{ maxBytes } | false` 部署选择挂载它；`dsh web` 启用 65,536 字节预算，Host Runtime 的 headless 消费方则禁用它。该插件使用 `agent/pre-step`、不可变的 `tools/result` 结果、`session/event` 边界和可选的 `ctx.fs` 功能。
+该实现在 `packages/context/workspace-context` 中，包名为 `@deepseek-ai/dsh-workspace-context`。它是请求上下文扩展，不是核心服务或文件系统后端。共享 demo 主干与 Host Runtime 根据显式的 `{ maxBytes } | false` 部署选择挂载它；`dsh web` 启用 65,536 字节预算，Host Runtime 的 headless 消费方则禁用它。该插件使用 `agent/pre-step`、不可变的 `tools/result` 结果、`session/event` 边界和可选的 `ctx.fs` 功能。
 
 插件不会静态注入 `fs`。因此，不带提供方的产品树仍能正常启动；在文件系统提供方出现之前，插件保持无操作。所有生产读取都通过该提供方完成。候选项探测会解析每个路径并对结果执行 stat，因此会跟随最终路径组件的符号链接至其目标：指向普通文件的链接会被加载，缺失路径或非文件目标则确认为不存在。允许仓库拥有的链接跨越信任边界，是对最初不跟随探测方式的刻意反转；[跟随指令符号链接记录](2026-07-21-follow-instruction-symlinks.md)负责说明该决策及其残余风险。步骤信号与动态工具执行信号会贯穿解析、元数据探测和流式读取，因此取消不会等待无关的文件系统扫描。解析或 stat 异常归类为不可用：它只跳过该候选项，绝不被解释为已经加载的作用域被删除。
 
@@ -78,7 +78,7 @@ shell 命令不会触发发现。本地 bash 调用会启动全新的 shell，
 
 ## 后果
 
-工作区指引按会话隔离，并由 demo 入口、Web Host 与每一种工具展示模式共享。初始、嵌套与变更指令都保持持久且可回放。通用的会话／agent 上下文契约通过先在 inbox 中暂存、再持久进入的 user 消息携带带类型的来源数据，而不会把条目展平。
+工作区指引按会话隔离，并由 demo 入口、Web Host 与每一种工具展示模式共享。初始、嵌套与变更指令都保持持久且可回放。通用的会话／agent 上下文约定通过先在 inbox 中暂存、再持久进入的 user 消息携带带类型的来源数据，而不会把条目展平。
 
 仓库文本仍是不受信任的输入。低权威 user 角色框架、显式优先级说明和分隔符转义可以降低风险，但无法消除提示词注入。跟随候选符号链接到目标，会把该攻击面扩大至树外内容；因此，把 `ctx.fs` 限制在可信根目录内的权限与沙箱层才是真正的边界，它们让系统把工作区文件当作数据而不是权威（[跟随指令符号链接记录](2026-07-21-follow-instruction-symlinks.md)负责说明残余风险）。
 
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
index 5ea74ca411..fa5b21ccac 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
 2026-06-29-todo-write-tool.md: c4cf64b7876bd8b80df80fe6fc27005715f96b5e
-2026-06-29-todo-write-tool.zh.md: 1f797c5517df8affd66addecf2a8db43c1da3332
+2026-06-29-todo-write-tool.zh.md: 5efcaf1f6e7ea69b1dd8cd0fd31b9cbd931666db
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
index 1f797c5517..5efcaf1f6e 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结构化的任务列表。todo 列表有两个同等重要的用途：引导模型规划多步骤工作并保持当前活跃任务明确；同时为交互式宿主提供实时进度清单。调研的所有参考编码 agent（智能体），包括 claude-code、opencode、codex、oh-my-pi 和 pi，都提供了某种形式的此功能；本 harness 此前没有。
+harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结构化的任务列表。todo 列表有两个同等重要的用途：引导模型规划多步骤工作并保持当前活跃工作明确；同时为交互式宿主提供实时进度清单。调研的所有参考编码 agent（智能体），包括 claude-code、opencode、codex、oh-my-pi 和 pi，都提供了某种形式的此功能；本 harness 此前没有。
 
 ## 决策
 
@@ -34,7 +34,7 @@ claude-code V1 的条目是 `{ content, status, activeForm }`；后来（V2）
 
 ### 校验：低成本的中间路线
 
-schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重复的 `content`，并在 `allowParallelInProgress` 为 `false` 时拒绝超过一个活跃任务。排序和保持列表最新仍通过工具描述交给模型。被拒绝的写入返回 `isError` 结果，使模型自行修正。必填的部署策略及持久日志不变式独立于该策略这一约定，由[并行 in-progress Agent Note](2026-07-26-todo-parallel-in-progress.md) 负责。
+schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重复的 `content`，并在 `allowParallelInProgress` 为 `false` 时拒绝超过一个活跃任务。排序和保持列表最新仍通过工具描述交给模型。被拒绝的写入返回 `isError` 结果，使模型自行修正。必须采用的部署策略，以及持久不变式独立于该策略这一点，均由[并行 in-progress Agent Note](2026-07-26-todo-parallel-in-progress.md)负责。
 
 ## 为何没有 cordis-catalog 条目 / 没有 `@mode`
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
index 3b7a2c32a6..de978c055c 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-hook-bridges.md
 2026-06-30-hook-bridges.md: a31116818c57e18d04e656f371efd1101a63b6af
-2026-06-30-hook-bridges.zh.md: 8827408b67e2dd19f867a8658309f00231ba06c5
+2026-06-30-hook-bridges.zh.md: 0fa76c0cee0f74101e70f44d442daa2fb46e6649
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
index 8827408b67..0fa76c0cee 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
@@ -37,7 +37,7 @@ CC 桥接的 `ask` 结果是一条真正的权限路径，而非终态桥接决
 
 每个桥接的 `inject()` 和 additional-context 输入都显式传入 `{ kind: 'plugin', plugin: 'hooks-claude' | 'hooks-codex' }`。单元测试固定验证结果中的 `user/message.source` 为插件而非用户。
 
-`UserPromptSubmit` 在 `turn/start` 之后的 pre-step 运行，因此每次调用都会写入轮次范围的 `hook/invoked` / `hook/result` 对。reject 会让已领取输入保持删除，将轮次关闭为 blocked 且不包含步骤，并保留该 hook 对作为持久决策证据。Codex payload 会收到这个已打开轮次的 `turn_id`。
+`UserPromptSubmit` 在 `turn/start` 之后的 pre-step 运行，因此每次调用都会写入轮次范围的 `hook/invoked` / `hook/result` 对。拒绝会使已领取的输入维持移除状态，将轮次关闭为已阻止状态且不包含步骤，并保留该钩子对作为持久决策证据。Codex payload 会收到这个已打开轮次的 `turn_id`。
 
 ### 添加上下文不是否决——先 delegate，再 prepend
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
index 4a599f3310..9a76a6024c 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
 2026-06-30-hook-protocol-lib.md: 2edff0d501cd7695873c68054eeb3a1e9942eced
-2026-06-30-hook-protocol-lib.zh.md: 42e526fdf8073465d5f6faf99a6c92fbe09505f5
+2026-06-30-hook-protocol-lib.zh.md: e9ae51f5d7697017ecc153866bbb8c3f6fd34eb6
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
index 42e526fdf8..e9ae51f5d7 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 - **合并** — `mergeHookOutputs(outputs)`，将多个匹配钩子的输出折叠为一个最严格的 `MergedHookOutcome`：权限优先级 **deny > ask > allow**，halt 在首个 `continue:false` 时粘滞，阻止原因以 `\n\n` 拼接，context/system-messages 按序累积。
 - **`hook/*` 会话事件** — `hook/invoked` / `hook/result`，通过声明合并进入 `SessionEventMap`（仅日志，如 `compact/*`——不是 `SurfaceEventType`），配有 `appendHookInvoked`/`appendHookResult` 辅助函数，确保 invoked/result 配对与由所有者定义的执行关系在各桥接插件间保持一致。`appendHookResult` 还负责定义持久化记录的语义：decision 字符串（钩子解析出的 decision，否则 `continue:false` 时为 `'stop'`，否则为 `'pass'`）和 500 字符的 `stderrSummary` 截断均从本库的 `HookOutput` 派生，而非各桥接插件各自实现。
 
-**方言专属（桥接插件）：** 构建每个事件的 stdin payload（CC 的 base+per-event 字段集 vs Codex 的 snake_case 加 `turn_id`/`model` 额外字段）、方言的 env 与 `${CLAUDE_PLUGIN_ROOT}` 替换（CC）vs 无替换（Codex），以及将方言无关的 `HookOutput`/`MergedHookOutcome` 映射为 harness seam 专属的类型化 Decision（`PreToolDecision`、`PreStepDecision`、`ContinuationDecision`、`PostToolDecision`）。
+**方言专属（桥接插件）：** 构建每个事件的 stdin payload（CC 的 base+per-event 字段集 vs Codex 的 snake_case 加 `turn_id`/`model` 额外字段）、方言的 env 与 `${CLAUDE_PLUGIN_ROOT}` 替换（CC）vs 两者皆无（Codex），以及将方言无关的 `HookOutput`/`MergedHookOutcome` 映射为 harness seam 专属的类型化 Decision（`PreToolDecision`、`PreStepDecision`、`ContinuationDecision`、`PostToolDecision`）。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
index 536f913800..3975b65602 100644
--- a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md
 2026-07-16-durable-per-step-time-context.md: e1a5c65894913ad93f46db8ae45e5ef5ead215f3
-2026-07-16-durable-per-step-time-context.zh.md: 9cbf653f5d43060e99502b640eed7907ffbd3840
+2026-07-16-durable-per-step-time-context.zh.md: d353d2b4535cd2f6153adad084b4ca056f68dc8c
diff --git a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
index 9cbf653f5d..d353d2b453 100644
--- a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-`@deepseek-ai/dsh-time-context` 是位于 `packages/context/time-context/`、需要显式启用的函数插件。`context/` 分组容纳有界的请求上下文增强，这些增强既不定义工具也不定义服务；已交付示例不挂载此插件，因为时区披露与 token 成本属于部署策略。它注册一个前置的 `agent/pre-step` 监听器；需要读数且下游决策 enter 时，返回一条额外的 `UserMessage`。该消息携带来源 `{ kind: 'plugin', plugin: 'time-context' }`；受间隔抑制、reject 或失败的尝试不会追加任何内容。
+`@deepseek-ai/dsh-time-context` 是位于 `packages/context/time-context/`、需要显式启用的函数插件。`context/` 分组容纳有界的请求上下文增强，这些增强既不定义工具也不定义服务；已交付示例不挂载此插件，因为时区披露与 token 成本属于部署策略。它注册一个前置的 `agent/pre-step` 监听器；当应生成读数且下游决策为进入时，返回一条额外的 `UserMessage`。该消息携带来源 `{ kind: 'plugin', plugin: 'time-context' }`；被抑制、被拒绝或失败的尝试不会追加任何内容。
 
-监听器在 `step/start` 之前采样，并只在最终 enter 决策中结算读数。AgentLoop 会在 `step/start` 之后、请求派生之前记录它。因此，下游 reject 或失败会阻止读数进入持久历史。
+监听器在 `step/start` 之前采样，并仅在最终决定进入时确定该读数。AgentLoop 会在 `step/start` 之后、请求派生之前记录它。因此，下游拒绝或失败会阻止读数进入持久历史。
 
 省略可选配置 `timeZone` 时，插件在加载时解析一次 Node 进程的 IANA 时区；显式值由 `Intl.DateTimeFormat` 校验。时间戳包含数字 UTC 偏移和解析后的 IANA 时区。
 
@@ -44,7 +44,7 @@ Elapsed since the preceding step context: <duration-or-unavailable>.
 
 每个读数都作为普通表层节点保留，直至压缩将其隐藏；正数间隔调度绝不会移除已有读数。因此，后续请求会看到影响先前准备过程和步骤且尚未被隐藏的累计读数，而不是一个被原地改写的系统提示词值。
 
-插件不向系统提示词组装贡献任何内容。`request/header` 不包含时间上下文文本；请求重建从每个 `step/start` 取得完整的持久表层前缀。读数与请求无需一一对应，因为间隔抑制可以让请求进入步骤而不追加读数，reject 或失败则两者都不追加。插件通过 agent 注册表使用生命周期监听器，运行时不需要系统提示词服务。
+插件不向系统提示词组装贡献任何内容。`request/header` 不包含时间上下文文本；请求重建从每个 `step/start` 取得完整的持久表层前缀。读数与请求无需一一对应，因为间隔抑制可以让请求进入步骤而不追加读数，拒绝或失败则两者都不追加。插件通过 agent 注册表使用生命周期监听器，运行时不需要系统提示词服务。
 
 ## 测试
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
index 60cf540d45..689b04ef55 100644
--- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-human-goal-command.md
 2026-07-19-human-goal-command.md: 5fdd80f7423b80e84e58f7379130ee59a2e8a723
-2026-07-19-human-goal-command.zh.md: 74dd0a2bec923687c91ddf4ce7efe4cc5b25bfc9
+2026-07-19-human-goal-command.zh.md: 841e7195454b2e0cfc6f74fb28369022b84c5780
diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
index 74dd0a2bec..841e719545 100644
--- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
@@ -34,7 +34,7 @@ Status: implemented
 
 预期的 `GoalError` 失败会变为一个稳定且不含品牌化 id 的 `CommandResult.error`，使领域诊断不会向面向人类的界面泄露比较并交换内部细节，非法操作也绝不会进入模型历史。当前状态负责提供针对具体状态且可执行的恢复路径。其他异常仍是适配器可见的命令失败；若把程序缺陷当成普通领域错误，就会隐藏问题。命令处理器只执行同步领域变更，因此请求取消会在变更开始前由命令注册表决定，不存在需要回滚的外逸异步副作用。
 
-通用斜杠输入、状态文本与错误不会持久化。成功的 goal 变更会追加领域自有的 `goal/change` 事件，而且不会把模型上下文排队。该命令不会引入可能与领域事件不一致的第二份审计记录。
+通用斜杠输入、状态文本与错误不会持久化。成功的目标变更会追加领域自有的 `goal/change` 事件，而且不会将模型上下文加入队列。该命令不会引入可能与领域事件不一致的第二份审计记录。
 
 ### 应用组合
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
index 14c92dfce8..578218ce21 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
 2026-07-19-persisted-same-session-goal-domain.md: ce93a652f3910912fbf6afc28061de4d13eb2de2
-2026-07-19-persisted-same-session-goal-domain.zh.md: 7fb8dc3a6c76b91e0abf495782d51b30d3cd5b53
+2026-07-19-persisted-same-session-goal-domain.zh.md: ddb4fdedafbacbfec355a7a1c912a5f9545e208a
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
index 7fb8dc3a6c..ddb4fdedaf 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
@@ -18,9 +18,9 @@ Status: implemented
 
 ### 持久记录与回放
 
-每次变更都会追加带版本的 `goal/change` 会话事件，其中包含完整快照；clear 则包含带修订号的墓碑。会话日志是唯一的持久真源，因此持久化和 fork 会继承 goal 记录，而无需另设数据库或头字段。[Goal 自有持久事件决策](../architecture/2026-07-31-goal-owned-durable-events.md)负责 goal 状态与 inbox 状态、模型上下文之间的职责分离。
+每次变更都会追加带版本的 `goal/change` 会话事件，其中包含完整快照；清除时则包含带修订号的墓碑。会话日志是唯一的持久真源，因此持久化和 fork 会继承目标记录，而无需另设数据库或头字段。[目标自有持久事件决策](../architecture/2026-07-31-goal-owned-durable-events.md)负责将目标持久事件与收件箱状态和模型上下文分离。
 
-回放折叠只从 `goal/change` 派生生命周期变更，并校验 JSON 形状、新 id、修订连续性、生命周期转换、计数器以及单个 goal 内单调递增的时间戳。只有当前活跃修订上带正数且连续编号、已准入的 `user/message` 来源才会推进 Goal Round，且不能超过 `maxGoalRounds`；普通会话轮次不会影响该计数器。当前格式的畸形记录会使回放失败，而不会被忽略或修复。
+回放折叠只从 `goal/change` 派生生命周期变更，并校验 JSON 形状、新 id、修订连续性、生命周期转换、计数器以及单个目标内单调递增的时间戳。只有当前活跃修订上带正数且连续编号、已接纳的 `user/message` 来源才会推进 Goal Round，且不能超过 `maxGoalRounds`；普通会话轮次不会影响该计数器。当前格式的畸形记录会使回放失败，而不会被忽略或修复。
 
 增量回放会在每个有效事件后推进游标，并停留在首个损坏事件处，因此后续读取会报告同一个持久故障。重启后仍以持久日志为准。
 
@@ -36,12 +36,12 @@ Status: implemented
 
 ## 测试
 
-单元测试固定创建默认值、精确实时 agent 校验、比较并交换拒绝、所有生命周期转换、阻塞原因校验与保留、恢复时的上限执行、清除与替换、种子回放和 `SessionStore.fork()` 继承、会话启动与生命周期所有者解除激活、活跃目标重新激活、持久事件折叠、inbox 独立性、损坏事件的稳定回放、服务与监听器销毁、监听器隔离、挂钟后退钳制、严格记录解码、生命周期连续性，以及连续 Goal Round 归属。无密钥 Loader/stdio 进程测试通过测试专用 `cordis.yml` 挂载服务与生命周期消费方，再从外部读取持久 JSONL，以验证 goal 记录以及不存在未经请求的 Goal Round。包源码受仓库逐文件 100% 覆盖率门禁约束。
+单元测试固定创建默认值、精确实时 agent 校验、比较并交换拒绝、所有生命周期转换、阻塞原因校验与保留、恢复时的上限执行、清除与替换、种子回放和 `SessionStore.fork()` 继承、会话启动与生命周期所有者解除激活、活跃目标重新激活、持久事件折叠、收件箱独立性、损坏事件的稳定回放、服务与监听器销毁、监听器隔离、挂钟后退钳制、严格记录解码、生命周期连续性，以及连续 Goal Round 归属。无密钥 Loader/stdio 进程测试通过测试专用 `cordis.yml` 挂载服务与生命周期消费方，再从外部读取持久 JSONL，以验证目标记录以及不存在未经请求的 Goal Round。包源码受仓库逐文件 100% 覆盖率门禁约束。
 
 ## 考虑过的替代方案
 
 - **把目标存入独立数据库或会话头**——不予采纳，因为会话日志已经提供顺序、持久化、fork 前缀与可重建性；第二份存储会引入原子性和谱系问题。
-- **把每次持久变更与排队的模型上下文绑定。** 后续的 [Goal 自有持久事件决策](../architecture/2026-07-31-goal-owned-durable-events.md)不采用这一方案：goal 工具与已调度的继续执行提示词会在需要时暴露状态，而领域持久化不依赖队列结果。
+- **把每次持久变更与排队的模型上下文绑定。** 后续的 [Goal 自有持久事件决策](../architecture/2026-07-31-goal-owned-durable-events.md)不采用这一方案：目标工具与已调度的继续执行提示词会在需要时暴露状态，而领域持久化不依赖队列结果。
 - **持久化激活态并自动重启**——不予采纳，因为打开或恢复会话时必须等待人类输入；持久阶段记录状态，而不是再次消耗资源的授权。
 - **把所有会话轮次都计为 Goal Round**——不予采纳，因为同一会话可以包含人类澄清、检查和无关工作；只有归属于目标的继续执行轮次才消耗该预算。
 - **向 `dsh-agent-loop` 添加目标状态或通用循环抽象**——不予采纳，因为状态与继续执行策略可以通过现有插件、`Agent` 动词和事件组合，而无需赋予默认循环实现特权。
diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml
index 2f06720c93..4fd53a1941 100644
--- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md
 2026-07-19-same-session-goal-round-driver.md: a989b9d3487ebbf8ff11a4e34cb08029f1e4ace4
-2026-07-19-same-session-goal-round-driver.zh.md: b49a759c8f3577db30b8ab45449bb7faed85a7da
+2026-07-19-same-session-goal-round-driver.zh.md: 309b5ce45c2edb516a329f9992cea5558a2aeb8c
diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
index b49a759c8f..309b5ce45c 100644
--- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
@@ -20,15 +20,15 @@ Status: implemented
 
 ### 预留与接纳
 
-当 agent 空闲、没有竞争中的排队工作，且当前目标为 `active` 加 `armed` 时，驱动器会先检查点持久化待处理的目标变更，并在等待之后重新校验所有条件。若 `roundsStarted` 已等于 `maxGoalRounds`，它会记录代码为 `round-limit` 的 `blocked`；否则，它会先预留精确身份 `{ goalId, revision, round: roundsStarted + 1 }` 和完整渲染提示词，再以 `GoalMessageSource` 调用 `Agent.followup()`。提示词用 JSON 引号编码目标描述，使多行或类似标签的文本在熟悉框架中仍是无歧义的数据值。
+当 agent 空闲、没有竞争中的排队工作，且当前目标为 `active` 加 `armed` 时，驱动器会先将待处理的目标变更持久化到检查点，并在等待完成后重新校验所有条件。若 `roundsStarted` 已等于 `maxGoalRounds`，它会记录代码为 `round-limit` 的 `blocked`；否则，它会先预留精确身份 `{ goalId, revision, round: roundsStarted + 1 }` 和完整渲染提示词，再以 `GoalMessageSource` 调用 `Agent.followup()`。提示词用 JSON 引号编码目标描述，使多行或类似标签的文本在熟悉框架中仍是无歧义的数据值。
 
-`agent/pre-step` 瀑布是进入栅栏。正数目标来源只有在完全匹配驱动器待处理的身份和内容、实时目标仍具有相同 id 与修订号、激活态仍为 armed，并且该回合仍是下一个编号时才会进入步骤。插件在委托下游监听器前检查一次，在下游返回后再检查一次。第二次检查防止异步监听器编辑或暂停目标后，旧提示词仍进入步骤。
+`agent/pre-step` waterfall（瀑布式事件）是进入栅栏。正数目标来源只有在完全匹配驱动器待处理的身份和内容、实时目标仍具有相同 id 与修订号、激活态仍为 armed，并且该回合仍是下一个编号时才会进入。插件在委托下游监听器前检查一次，在下游返回后再检查一次。第二次检查防止异步监听器编辑或暂停目标后，旧提示词仍会进入。
 
-只有最终产生的 `user/message` 才是进入步骤的目标回合，并推进目标折叠。陈旧预留会关闭一个 blocked 的无步骤轮次；驱动器会把它标记为陈旧，不消耗回合数。若下游策略拒绝并非由陈旧状态导致，目标会进入 blocked，而不会绕过该策略自动重试。
+只有最终产生的 `user/message` 才是已进入的目标回合，并推进目标折叠。陈旧预留会关闭一个被阻塞的零步骤轮次；驱动器会把它标记为陈旧，不消耗回合数。若下游策略拒绝并非由陈旧状态导致，目标会进入 blocked，而不会绕过该策略自动重试。
 
 ### 人类工作与修订竞争
 
-预留的 `MessageId` 会区分驱动器自己的完整记录与其他所有提示词。预留之前已经排队的普通工作会阻止调度；自动提示词待处理时进入的普通工作会使该预留过期，因此混合的已领取批次会 reject 自动提案。目标回合已经进入步骤后到达的普通工作会保留在队列中，成为下一个独立轮次；只有 agent 再次空闲后才重新考虑继续执行。
+预留的 `MessageId` 会区分驱动器自己的完整记录与其他所有提示词。预留之前已经排队的普通工作会阻止调度；自动提示词待处理时进入的普通工作会使该预留过期，因此混合的已领取批次会拒绝自动提案。目标回合进入后到达的普通工作会保留在队列中，成为下一个独立轮次；只有 agent 再次空闲后才重新考虑继续执行。
 
 目标在回合内发生变更时会推进持久修订号。旧修订的结算不得覆盖该变更。驱动器会丢弃旧尝试的结果、读取新投影，并且只在新修订仍为 active 与 armed 时继续。因此，模型记录的完成、暂停、阻塞和编辑相对于物理轮次稍后的关闭原因具有最终权威。
 
@@ -53,9 +53,9 @@ Status: implemented
 
 每次 `goal/changed` 通知都会产生一个检查点义务。驱动器在预留工作前等待 `ctx.sessions.flush(session)`，随后检查是否出现了更新的变更、agent 生命周期变化或竞争提示词。轮次结束时的 flush 失败会在 `turn/end` 之后通过现有 `agent/error` 通知报告；即使并发的一次性注入已追加后续轮次，驱动器仍会找到对应的同一个已关闭轮次，把失败关联到对应的同一次尝试，并在下一次空闲决策前解除激活。
 
-广义取消会清除待处理 inbox 工作，并中止活跃 loop 阶段。目标驱动器通过 inbox 的领取／丢弃事件和持久的 aborted 轮次结束来跟踪预留消息。由于轮次现在会在首次领取前打开，取消可以关闭已领取的无步骤尝试；驱动器会把该尝试标记为已取消，并让随后的 idle 边沿暂停目标，与已准入尝试的处理方式相同。没有匹配目标尝试的取消只会移除进程内激活态。若暂停变更抛错，驱动器会回退到解除激活，避免已取消的自动工作重新启动。
+广义取消会清除待处理的收件箱工作，并中止活跃的循环阶段。目标驱动器通过收件箱领取／丢弃事件和持久化的 aborted 轮次结束事件来跟踪预留消息。由于轮次现在会在首次领取前打开，取消可以关闭已领取的零步骤尝试；驱动器会把该尝试标记为已取消，并让随后的空闲边沿暂停目标，与已接纳尝试的处理方式相同。没有匹配目标尝试的取消只会移除进程内激活态。若暂停变更抛错，驱动器会回退到解除激活，避免已取消的自动工作重新启动。
 
-`Agent.cancel()` 仍是唯一的公共广义取消动词。若消费方依赖其顺序，实现该接口的自定义 `Agent` 必须遵守 inbox、轮次结束、status 与完全停稳的顺序。
+`Agent.cancel()` 仍是唯一的公共广义取消动词。若消费方依赖这些顺序，实现该接口的自定义 `Agent` 必须遵守收件箱、轮次结束、状态与完全停稳的顺序。
 
 ### 进程生命周期
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
index e852c240f7..c5d0cab7a1 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-cross-session-references.md
 2026-07-21-cross-session-references.md: b2d428e0937fdd881720720401948a1c3e7ef1f6
-2026-07-21-cross-session-references.zh.md: a59657bfcd46393a5cd1c5a5076a6eddd5d065ff
+2026-07-21-cross-session-references.zh.md: e242e159329a5f1446b08547cd0f176b6c1af3f7
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
index a59657bfcd..e242e15932 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
@@ -26,7 +26,7 @@ TUI 用户需要把另一场对话中的相关工作带入一条新消息，但
 
 ## 消息所有权
 
-TUI 负责快照／直接消息事务，不扩展通用收件箱记录。agent 空闲时，它会在调用 `followup()` 前安装一次性的外层 `agent/pre-step` 监听器；enter 决策会把快照作为另一条消息接收，而 reject 或更早的普通丢弃会释放监听器，并且不写入任何消息。agent 运行时，TUI 会依次调用 `inject(snapshot)` 和 `steer(prompt)`，把两者放入 next-step inbox，等待后续同一次领取。pre-step reject 或失败会让这对已领取消息保持删除；领取后插入的消息继续等待。这一通用交付边界由[上下文分离决策](../architecture/2026-07-24-separate-context-injection-from-turn-execution.md)规定。
+TUI 负责快照／直接消息事务，不扩展通用收件箱记录。agent 空闲时，它会在调用 `followup()` 前安装一次性的外层 `agent/pre-step` 监听器；enter 决策会把快照作为另一条消息接收，而 reject 或更早的普通丢弃会释放监听器，并且不写入任何消息。agent 运行时，TUI 会依次调用 `inject(snapshot)` 和 `steer(prompt)`，把两者放入 next-step inbox，等待后续同一次领取。pre-step reject 或失败会使这对已领取消息维持已移除状态；领取后插入的消息继续等待。这一通用交付边界由[上下文分离决策](../architecture/2026-07-24-separate-context-injection-from-turn-execution.md)规定。
 
 引用准备过程不是新的 steering 协议，本身也不会创建轮次。空闲交付使用 `followup()` 和 pre-step 进入决策；运行期间的交付使用共享 next-step inbox，并保持快照顺序。
 
diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml
index 37839002ae..77104f258e 100644
--- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-web-session-model-selector.md
 2026-07-24-web-session-model-selector.md: 05e923fb3b5df72485ffb8d6ff5aa0104b19a8a0
-2026-07-24-web-session-model-selector.zh.md: bdfa2f856a799cc86600650829a2df62a7dfdc18
+2026-07-24-web-session-model-selector.zh.md: c1fd59ada0340a984ddf4a9dcc4c357f9609acb1
diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
index bdfa2f856a..c1fd59ada0 100644
--- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
@@ -40,4 +40,4 @@ Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlm
 
 ## 测试
 
-Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、建议性的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整目标提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及已删除模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会删除活动目录行，在选择替代模型之前固定该回退。
+Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、不受目录约束的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整目标提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及已删除模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会删除活动目录行，在选择替代模型之前固定该回退。
diff --git a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml
index 5f2f7bc9ae..b91d68b90f 100644
--- a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.md
 2026-07-28-tool-call-file-open-in-os.md: 499d3caa11e1f2c17d96e43b7846df72a31c0eb1
-2026-07-28-tool-call-file-open-in-os.zh.md: a658a7b55d2575ad1a5d8baccb80f0a8444d6db9
+2026-07-28-tool-call-file-open-in-os.zh.md: f5fdad90041915171dceab33ea77b2187419dc31
diff --git a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md
index a658a7b55d..f5fdad9004 100644
--- a/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-tool-call-file-open-in-os.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 文件工具的路径摘要（`read`／`write`／`edit` 参数中的 `path` 或 `file_path`）渲染为静止状态下即带下划线的链接，并使用 pointer 光标。点击路径会经 `WorkspacesService.openPath` 调用 `host.openPath`，相对路径以会话 cwd 为基准解析。带文件链接的行关闭参数展开（左侧图标不可点）；工具行（含 bash 与 todo 注册）去掉整行点击、整行悬停底色，以及点击打开 details 的手势。details 面板及其 inject 面仍保留供程序化选择；工具行不再驱动它们。
 
-`host.openPath` 是特权一元 RPC，仅接受来自回环地址且同源的浏览器请求（与 `host.pickDirectory` 相同的载体守卫）。平台适配器不经 shell 打开：macOS 为 `open`，Windows 为 PowerShell `Invoke-Item`，桌面 Linux 为 `xdg-open`；浏览器可渲染的文档会在 macOS 与桌面 Linux 上优先使用能够确定的默认浏览器。尽管 Node 将 WSL 报告为 `linux`，WSL 仍是一种独立的宿主形态：适配器根据其环境或 Microsoft 内核 release 识别它，用 `wslpath -w` 转换 Linux 路径，并将所得 Windows/UNC 路径交给同一 PowerShell 交接。打开器的平台信息和命令运行器可在测试中注入。仅含 URL 的 read 参数（`web_fetch`）不是文件链接。
+`host.openPath` 是特权一元 RPC，仅接受来自回环地址且同源的浏览器请求（与 `host.pickDirectory` 相同的载体守卫）。平台适配器不经 shell 打开：macOS 为 `open`，Windows 为 PowerShell `Invoke-Item`，桌面 Linux 为 `xdg-open`；浏览器可渲染的文档会在 macOS 与桌面 Linux 上优先使用指定的默认浏览器。尽管 Node 将 WSL 报告为 `linux`，WSL 仍是一种独立的宿主形态：适配器根据其环境或 Microsoft 内核 release 识别它，用 `wslpath -w` 转换 Linux 路径，并将所得 Windows/UNC 路径交给同一 PowerShell 交接。打开器的平台信息和命令运行器可在测试中注入。仅含 URL 的 read 参数（`web_fetch`）不是文件链接。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
index d5dbd53881..243eed83f8 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md
 2026-07-29-persistent-bash-str-replace-editor.md: c4750e30370bfd253064c39cb1adc0f5b2baa60d
-2026-07-29-persistent-bash-str-replace-editor.zh.md: 62073571ce2164d88897d4959caafd9cb1dbdd93
+2026-07-29-persistent-bash-str-replace-editor.zh.md: 14c52fc90d8619d63ca3acab2d85447fab5eb735
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
index 62073571ce..14c52fc90d 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 两个插件都进入 Python runtime 闭包。持久 Bash 的闭包还包含 PTY 服务／本地后端，以及该后端要求的沙箱服务。由于 `node-pty` 在 macOS 上会执行原生 `spawn-helper`，每个打包后的 macOS 运行时可执行文件都会携带一个 `-spawn-helper` 伴随文件；Linux 直接使用 `forkpty`。固定版本的 `node-pty` 补丁会先检查 `DSH_NODE_PTY_SPAWN_HELPER`，因此对当前提供非伴随 helper 的外部消费方而言，该变量仍是真正的覆盖项。未设置该覆盖时，补丁会在打包可执行文件的伴随文件存在时解析它，否则在普通 Node 运行中保留上游查找方式。若 helper 缺失或不可执行，macOS 构建器会在发布前失败。
 
-已交付的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) overlay 会在常规 Web 界面之上组合这两个插件，以满足与 Claude SWE 兼容的 RL 契约。它固定使用原生工具模式；完整的系统提示词在设置 `DSH_SYSTEM_PROMPT` 时采用其值，否则采用 `You are a helpful software engineer assistant.`，且不包含 harness 身份、源码 checkout 提示词段、Web 界面定位、Workspace 指令或工具模式指引。它会禁用其他所有面向模型的消费方，使模型恰好只收到持久 `bash` 和 `str_replace_editor` 两个 schema，同时保留 Web 宿主、浏览器、Workspace、持久化、沙箱与权限栈。本地 PTY 后端会在创建 shell 时解析会话的有效沙箱模式。只要该所有者仍有打开的 shell 或仍在进行中的 spawn，另一种权限模式就会在对应的会话事件提交前遭到拒绝；编辑器则继续经由 Web 文件系统沙箱运行。
+已交付的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) overlay 会在常规 Web 界面之上组合这两个插件，以满足与 Claude SWE 兼容的 RL 约定。它固定使用原生工具模式；完整的系统提示词在设置 `DSH_SYSTEM_PROMPT` 时采用其值，否则采用 `You are a helpful software engineer assistant.`，且不包含 harness 身份、源码 checkout 提示词段、Web 界面定位、Workspace 指令或工具模式指引。它会禁用其他所有面向模型的消费方，使模型恰好只收到持久 `bash` 和 `str_replace_editor` 两个 schema，同时保留 Web 宿主、浏览器、Workspace、持久化、沙箱与权限栈。本地 PTY 后端会在创建 shell 时解析会话的有效沙箱模式。只要该所有者仍有打开的 shell 或仍在进行中的 spawn，另一种权限模式就会在对应的会话事件提交前遭到拒绝；编辑器则继续经由 Web 文件系统沙箱运行。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
index ff01e8a69a..dec5dcfafd 100644
--- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md
 2026-07-04-doc-tiers-and-budgets.md: e7b3421d09a1ae5ab9a9373e8040832c1b0d4b97
-2026-07-04-doc-tiers-and-budgets.zh.md: 18bf98777c87512e6161a4529db66030ced47bfd
+2026-07-04-doc-tiers-and-budgets.zh.md: 157ad13f521d2a497180e25b70e3537a4afbc099
diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
index 18bf98777c..157ad13f52 100644
--- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
@@ -6,15 +6,15 @@ Status: implemented
 
 ## 问题
 
-尽管已有写作指导，常设文档仍不断累积重复规则、反复讲述的事件、重复的包（package）映射，以及陈旧的 Agent Note（agent 决策记录）摘要。该指导也未明确文档在层级中的位置如何限定其内容范围，以及按顺序引导读者学习的内容与面向查阅的材料有何不同。仅靠评审无法阻止这种增长，因此仓库需要在文档分类之外再配一套机械预算。
+尽管已有写作指导，常设文档仍不断累积重复规则、反复讲述的事故、重复的包映射，以及陈旧的 Agent Note 摘要。该指导也未明确文档在层级中的位置如何限定其内容范围，以及按顺序引导读者学习的内容与面向查阅的材料有何不同。仅靠评审无法阻止这种增长，因此仓库需要在文档分类体系之外再配一套可自动执行的预算。
 
 ## 决策
 
-- **结构遵循文档树。**[docs/AGENTS.md](../../../../docs/AGENTS.md) 是文档标准：文档负责承载其主题的详细内容，仅概述直接子项的目的、职责和高层行为，并链接到更深层内容的归属文档。[Agent Note](../../README.md) 仍不受这一结构契约约束。每份面向人的文档要么是按顺序引导读者达成结果的教程（tutorial），要么是查阅范围明确的参考文档（reference）；[事故复盘（postmortem）](../../../../docs/postmortem/README.md) 是范围限定于单个事件的参考文档，其时间线记录证据。教程结合读者的起始知识，按前置依赖顺序介绍概念。
+- **结构遵循文档树。**[docs/AGENTS.md](../../../../docs/AGENTS.md) 是文档标准：文档负责承载其主题的详细内容，仅概述直接子项的目的、职责和高层行为，并链接到更深层内容的归属文档。[Agent Note](../../README.md) 仍不受这一结构约定约束。每份面向人的文档要么是按顺序引导读者达成结果的教程（tutorial），要么是查阅范围明确的参考文档（reference）；[事故复盘（postmortem）](../../../../docs/postmortem/README.md) 是范围限定于单起事故的参考文档，其时间线记录证据。教程结合读者的起始知识，按前置依赖顺序介绍概念。
 - **每项事实只归属一处的层级分类。**文档标准为每种 Markdown 层级分配单一职责，禁止在事实归属层级之外重复陈述，并包含编写或评审任何文档时使用的赘余检查清单。
-- **范围窄且严格的预算门禁。**[scripts/verify-doc-budgets.ts](../../../../scripts/verify-doc-budgets.ts) 接入 `doc-sync`：[scripts/doc-budgets.manifest.json](../../../../scripts/doc-budgets.manifest.json) 列出的每份文档都必须低于其字数上限（采用 `wc -w` 语义，统计整个文件）；预算内文件缺失也会使门禁失败，使重命名无法悄然遗落其预算。范围刻意只涵盖容易膨胀的常设文档——根目录和子树中的 `AGENTS.md` 文件、`architecture.md`、`packages/README.md`，以及它们将内容移入的常设策略文档（`docs/testing.md`、`docs/defensive-patterns.md`）。参考文档、Agent Note 和包 README 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。
+- **范围窄且严格的预算门禁。**[scripts/verify-doc-budgets.ts](../../../../scripts/verify-doc-budgets.ts) 接入 `doc-sync`：[scripts/doc-budgets.manifest.json](../../../../scripts/doc-budgets.manifest.json) 列出的每份文档都必须低于其词数上限（采用 `wc -w` 语义，统计整个文件）；预算内文件缺失也会使门禁失败，使重命名无法悄然遗落其预算。范围刻意只涵盖容易膨胀的常设文档——根目录和子树中的 `AGENTS.md` 文件、`architecture.md`、`packages/README.md`，以及它们将内容移入的常设策略文档（`docs/testing.md`、`docs/defensive-patterns.md`）。参考文档、Agent Note 和包 README 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。
 - **上限是只进不退的执行红线。** 达到或低于目标的文档在上限逐步下调时保留至少 5% 的余量；高于目标的文档则维持冻结的上限，在达到目标之前不得增长（根 `AGENTS.md` ≤ 1,600 词；`architecture.md` ≤ 1,800；子树 `AGENTS.md` ≤ 600，但 `packages/AGENTS.md` ≤ 650、`docs/AGENTS.md` ≤ 1,250；`packages/README.md` ≤ 600）。门禁变红时，迁移或压缩内容；只有在 PR（Pull Request）描述中给出明确理由时才提高上限。
-- **精简的工作流 skill（技能），契约归文档。**[.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) 承载放置/审计/红灯门禁工作流，并以文档标准为真源，与 [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 和 i18n 契约之间的分工相同。
+- **精简的工作流 skill（技能），契约归文档。**[.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) 承载文档放置、审计和门禁失败处理工作流，并以文档标准为真源，与 [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 和 i18n 契约之间的分工相同。
 
 ## 曾考虑的替代方案
 
@@ -24,7 +24,7 @@ Status: implemented
 
 ## 后果
 
-- 向受预算约束的文档添加内容需要置换：将新增内容迁移到其分类体系归属地并留下指针，或压缩现有行文来腾出空间。只增不减会导致 CI 失败。
+- 向受预算约束的文档添加内容需要腾挪空间：将新增内容迁移到其分类体系归属地并留下链接，或压缩现有行文来腾出空间。只增不减会导致 CI 失败。
 - 结构评审先检查归属关系和文档形式，再进行句子层面的编辑，使较低层级的细节迁移到其归属文档，而不是在错误的位置加以润色。
 - 仍高于目标的受预算约束文档不得增长；达到目标后，将恢复 5% 的工作余量。
-- 字数是一个粗糙的代理指标，这是有意接受的：它无法判断质量，但它在内容被添加的那一刻强制触发迁移决策，而那正是作者拥有足够上下文来正确放置内容的时刻。
+- 词数是一个粗糙的代理指标，这是有意接受的：它无法判断质量，但它在内容被添加的那一刻强制触发迁移决策，而那正是作者拥有足够上下文来正确放置内容的时刻。
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
index e7f76356e2..0121a65219 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
 2026-07-22-fast-local-git-hooks.md: af8a9380fc3cbf4f672ca0b32faa7b187522cf11
-2026-07-22-fast-local-git-hooks.zh.md: 04f3a407e421c4d585b8b78b16b9055fd19ac756
+2026-07-22-fast-local-git-hooks.zh.md: 1b2c3bf42a65f35d96c266f5f3afb63f26039388
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
index 04f3a407e4..1b2c3bf42a 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
@@ -12,9 +12,9 @@ agent（智能体）已经会运行能够覆盖自身改动的测试和检查，
 
 ## 决策
 
-[lefthook.yml](../../../../lefthook.yml) 将两个钩子都保留为有界的本地检查点。Pre-commit 按顺序运行：仅用于格式化的 ESLint 配置修复改动过的 JavaScript 和 TypeScript 文件并重新暂存，不加载项目的 [Oxlint](2026-07-29-oxlint-linter.md) 配置验证这些文件并应用原生安全修复，`git diff --cached --check` 拒绝暂存 diff 中的空白错误，vendor manifest（元数据清单）守卫检查 vendor 源码元数据。Pre-push 运行 `pnpm run typecheck`；该命令会先准备好生成的 Host TypeRT 契约，再运行 Client 增量类型检查。
+[lefthook.yml](../../../../lefthook.yml) 将两个钩子都保留为有界的本地检查点。Pre-commit 按顺序运行：仅用于格式化的 ESLint 配置修复改动过的 JavaScript 和 TypeScript 文件并重新暂存，不加载项目的 [Oxlint](2026-07-29-oxlint-linter.md) 配置验证这些文件并应用原生安全修复，`git diff --cached --check` 拒绝暂存 diff 中的空白错误，vendor manifest（元数据清单）守卫检查 vendor 源码元数据。Pre-push 运行 `pnpm run typecheck`；该命令会先准备好生成的 Host TypeRT 约定，再运行 Client 增量类型检查。
 
-Pre-commit 不运行类型分析、测试、快照、文档检查、构建、`hygiene` 或门禁调度器。Pre-push 只增加仓库类型检查所需的 Host 契约构建。可选运行的 `check:all` 包脚本独立于这些钩子，从 [scripts/run-gates.ts](../../../../scripts/run-gates.ts) 中选择 `check-all` 调度器清单；它是贡献者命令，而非对 agent 的指令。
+Pre-commit 不运行类型分析、测试、快照、文档检查、构建、`hygiene` 或门禁调度器。Pre-push 只增加仓库类型检查所需的 Host 约定构建。可选运行的 `check:all` 包脚本独立于这些钩子，从 [scripts/run-gates.ts](../../../../scripts/run-gates.ts) 中选择 `check-all` 调度器清单；它是贡献者命令，而非对 agent 的指令。
 
 agent 检查待推送的 diff，并仅运行一次能够覆盖其行为的最小范围测试和检查。CI 负责全量覆盖率门禁、构建产物检查与平台矩阵。只有在明确要求、诊断 CI，或涉及全仓库的改动无法由范围更窄的证据得到可信验证时，才完整运行一遍本地检查矩阵。
 
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
index 19945a6580..cd55f494d7 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
 2026-07-27-wine-windows-gates-experiment.md: 1b01fe00dc1588482442a3cedc35eefa7fdb0975
-2026-07-27-wine-windows-gates-experiment.zh.md: b50739f5b63c5836248c94927037e38900abc84f
+2026-07-27-wine-windows-gates-experiment.zh.md: 3145a4aa6a06cacbab96dd37714617aeecdfdde0
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
index b50739f5b6..3145a4aa6a 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
@@ -14,7 +14,7 @@ Pull request 的 Windows 通道旨在验证两个阻断性 win32 表面，即 wo
 
 [ci.yml](../../../../.github/workflows/ci.yml) 中必需的 pull request `windows` 作业（`windows node 24 / wine blocking`）在 `ubuntu-latest` 上通过 Wine 用真实 Windows 二进制运行阻断门禁命令：校验和验证过的 win-x64 Node.js 执行 `tsc -b`、`tsdown` 与 VitePress 生产构建，因此工具链的 win32 分支——反斜杠路径处理、`CreateProcess` 派生语义、`@esbuild/win32-x64` 的 PE 加载、以及 rolldown/rollup 的 MSVC `.node` 插件——都真正执行。master 的 `serial-windows` 作业原封不动：完整的原生内核清单，包括本通道不运行的观察性可移植性门禁，仍在每次 master push 时于真实 `windows-2025` 上执行。
 
-依赖在 Linux 上原生安装，`supportedArchitectures` 扩展到 win32-x64，使 Windows 平台包物化进同一个 store；通过直接调用各工具的 JavaScript 入口绕开 cmd-shim 层，这正是 `run-gates` 最终派生的那些进程。`nodeLinker: hoisted` 是承重的，不是风格问题：一个独立原型保留了 pnpm 默认的 isolated 布局——包括在 Linux 预取的 store 上忠实地用 Windows pnpm 离线重装——而 Wine 下的 Windows Node 依然无法穿过 isolated 符号链接链解析 `@esbuild/win32-x64` 或加载 koffi 预编译产物，在任何仓库门禁运行前就失败了。扁平的真实文件布局才让门禁变得可达；本通道采纳了该原型的校验和固定，同时明确放弃其「Windows pnpm 安装依赖树」的目标（安装契约在此仍由 Linux 侧验证）。
+依赖在 Linux 上原生安装，`supportedArchitectures` 扩展到 win32-x64，使 Windows 平台包物化进同一个 store；通过直接调用各工具的 JavaScript 入口绕开 cmd-shim 层，这正是 `run-gates` 最终派生的那些进程。`nodeLinker: hoisted` 是承重的，不是风格问题：一个独立原型保留了 pnpm 默认的 isolated 布局——包括在 Linux 预取的 store 上忠实地用 Windows pnpm 离线重装——而 Wine 下的 Windows Node 依然无法穿过 isolated 符号链接链解析 `@esbuild/win32-x64` 或加载 koffi 预编译产物，在任何仓库门禁运行前就失败了。扁平的真实文件布局才让门禁变得可达；本通道采纳了该原型的校验和固定，同时明确放弃其「Windows pnpm 安装依赖树」的目标（安装约定在此仍由 Linux 侧验证）。
 
 该通道靠四个杠杆把墙钟时间保持在与 Linux CI 作业相当的水平：master 刷新的 pnpm store 缓存（只恢复，与 Linux 作业同键）、Wine 供给（apt 安装、Windows Node 下载、`wineboot`）与 `pnpm install` 并发运行、两个阻断表面并发运行——与 `run-gates` 在原生 Windows 上给它们的形状相同——以及按 runner 镜像为键的 apt 归档缓存，由 master 的 `wine apt cache` 作业播种，使每个 pull request 都能从默认分支作用域恢复。
 
@@ -32,7 +32,7 @@ Pull request 的 Windows 通道旨在验证两个阻断性 win32 表面，即 wo
 
 **在 Linux runner 内用 QEMU/KVM 跑完整 Windows 客户机。** 真实 NT 内核，保真度完整，包括大小写不敏感的 NTFS 与 ConPTY——但首个门禁运行前要花数十分钟下载镜像并做无人值守安装（兄弟实验分支 `exp/kvm-windows-ci` 实测端到端 40 分 19 秒）。只有配上会挤压 Actions 缓存预算的磁盘镜像缓存才可投入使用。
 
-**在 Wine 下由 Windows pnpm 执行安装。** 同一想法的更高保真度变体：把 MinGit 与 pnpm 放进 prefix，用 Linux 预取填充 store，再由 Windows Node 运行 `pnpm install --offline`，让安装契约本身以 win32 身份执行。它到达了安装但没到达门禁——Wine 的网络无法直接访问 registry，且 isolated 的 `node_modules` 布局即便在干净的离线安装后也挫败了 Windows 平台包的解析。本通道牺牲这份保真度（hoisted 布局、Linux 侧安装）来换取门禁可达；两份记录是同一裁决互补的两半。
+**在 Wine 下由 Windows pnpm 执行安装。** 同一想法的更高保真度变体：把 MinGit 与 pnpm 放进 prefix，用 Linux 预取填充 store，再由 Windows Node 运行 `pnpm install --offline`，让安装约定本身以 win32 身份执行。它到达了安装但没到达门禁——Wine 的网络无法直接访问 registry，且 isolated 的 `node_modules` 布局即便在干净的离线安装后也挫败了 Windows 平台包的解析。本通道牺牲这份保真度（hoisted 布局、Linux 侧安装）来换取门禁可达；两份记录是同一裁决互补的两半。
 
 **Linux 上的文件系统语义通道（casefold ext4、文件名 lint）。** 以近零成本捕获最高频的 Windows 故障类别，但对 win32 二进制什么也证明不了。作为兄弟实验分支 `exp/casefold-windows-ci` 探索；与本通道互补而非竞争。
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
index 451ffb98ca..3b50695584 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
 2026-06-20-public-agent-stop-surface.md: e9c713c7ba8c784d3d66fe8f391e1b197f7394d2
-2026-06-20-public-agent-stop-surface.zh.md: 5c1eb0ec8245c60613d6d4d7c1d105b5243bc938
+2026-06-20-public-agent-stop-surface.zh.md: 217c898eec6b9e232f2cf3982b2bec411e8d91ab
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
index 5c1eb0ec82..217c898eec 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
@@ -36,4 +36,4 @@ Status: implemented
 
 ## 相关
 
-本 Agent Note 只移除冗余的停止动词。轮次中途 steering 仍是一条有意保留的消息路径；完全停稳观察仍通过 `whenIdle()` 完成。最终交付接口包括 `followup()`、`steer()` 和 `inject()`；停止与观察仍通过 `cancel()` 和 `whenIdle()` 完成。
+本 Agent Note 只移除冗余的停止动词。轮次中途 steering 仍是一条有意保留的消息路径；完全停稳观察仍通过 `whenIdle()` 完成。最终的消息投递接口包括 `followup()`、`steer()` 和 `inject()`；停止与观察仍通过 `cancel()` 和 `whenIdle()` 完成。
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
index 3b9345a404..af534f7b4b 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
 2026-07-17-one-send-one-turn.md: 834eb2b3aace0a0aa5f86f483e7b7d7aabbe467e
-2026-07-17-one-send-one-turn.zh.md: d22893b912462cffffb0d6ecd81811e9cb5c523d
+2026-07-17-one-send-one-turn.zh.md: d05ce63c404ce4d10ac098e3a3c9617443cc278b
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
index d22893b912..d05ce63c40 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
@@ -16,11 +16,11 @@ Status: implemented
 
 规则很简单：一次成功的 `send()` 创建一个独立的 FIFO 队列项。该队列项如果运行，就是所在轮次中唯一的普通消息。队列项可能在启动前被丢弃，因此精确保证是最多一个轮次，而不是必定一个轮次；两次 send 绝不会被悄悄合并。
 
-消息插入之前，`send()` 会检查 agent 状态，并接受已有标识且经过深度冻结的值。持久 splice 与 `agent/inbox/inserted { message }` 会保留其 `MessageId`；在驱动器领取或丢弃该消息之前，可以通过 `Inbox.replace()` 与 `Inbox.remove()` 寻址。当前生命周期由[已领取 pre-step inbox 决策](../architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md)规定。
+消息插入之前，`send()` 会检查 agent 状态，并接受已有标识且经过深度冻结的值。持久化 splice 与 `agent/inbox/inserted { message }` 会保留其 `MessageId`；在驱动器领取或丢弃该消息之前，可以通过 `Inbox.replace()` 与 `Inbox.remove()` 寻址。当前生命周期由[已领取 pre-step inbox 决策](../architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md)规定。
 
 如果消息 A、B 都进入处理，B 的轮次只能在 A 记录 `turn/end` 且 A 的持久性检查点处理结束后开始。因此，B 的请求能看到 A 在同一会话日志中留下的已关闭结果。检查点错误会照常报告，但处理结束只表示解除这道顺序屏障，不表示失败的写入已经持久化。面向整个 agent 的 `cancel()`、dispose（资源释放）或 `turn/start` 之前的失败也可能丢弃尚未启动的队列项，而不打开一个空轮次。
 
-轮次边界上，循环会先打开轮次，再在待处理 next-step 输入之后领取一条 follow-up。`agent/pre-step` 要么拒绝提案，要么返回进入步骤的完整批次。被拒绝的 follow-up 保持已删除，并关闭一个 blocked 的无步骤轮次，不写入模型可见历史。实现中不存在混合普通 follow-up 分支。
+轮次边界上，循环会先打开轮次，再在待处理 next-step 输入之后领取一条 follow-up。`agent/pre-step` 要么拒绝提案，要么返回进入步骤的完整批次。被拒绝的 follow-up 保持已删除，并关闭一个受阻的无步骤轮次，不写入模型可见历史。实现中不存在混合普通 follow-up 分支。
 
 上述不合批规则只适用于普通 follow-up 输入。`steer()` 会把输入放入 next-step inbox 并唤醒驱动器。在轮次期间，循环可以在后续步骤边界领取它；agent 空闲时，这个会唤醒的 next-step 批次会启动一个新轮次。批次被领取后才到达的输入会等待后续边界，而取消或 dispose 可以将其丢弃。
 
@@ -35,11 +35,11 @@ Status: implemented
 - 单元测试和基于属性的测试从同一调用栈、相邻微任务、不同生产方和重入回调提交 send；每条消息都会得到一个按 FIFO 排序的独立轮次。
 - stdio 构建产物测试提交两行输入，并观察到两个模型请求和两个轮次边界。
 - 延迟和拒绝第一个轮次的检查点，都能让下一个轮次保持等待，并证明其请求可以看到前一条助手结果。
-- 失败路径测试覆盖 pre-step reject、监听器失败、广义取消、dispose 和 `turn/start` 之前的失败；首次 pre-step 的各种退出都会关闭边界平衡的无步骤轮次，消息不会合并，之后仍需处理的工作也能继续清空。
+- 失败路径测试覆盖 pre-step 拒绝、监听器失败、面向整个 agent 的取消、dispose 和 `turn/start` 之前的失败；首次 pre-step 的各种退出都会关闭边界平衡的无步骤轮次，消息不会合并，之后仍需处理的工作也能继续清空。
 - 其他测试分别覆盖轮次打开时、轮次失败后和空闲时的 `steer()`，以及待处理的 `inject()`、面向整个 agent 的状态和 `whenIdle()`。
 
 ## 后果
 
-普通轮次的边界可预测：消息 A、B 始终分开，B 只能在 A 关闭并到达检查点后运行。调用方仍然拿不到逐次 send 的完成句柄；待处理消息可通过其 `MessageId` 移除，广义取消可以丢弃整个尚未启动的队尾，而状态与完全停稳仍是面向整个 agent 的观察。
+普通轮次的边界可预测：消息 A、B 始终分开，B 只能在 A 关闭并到达检查点后运行。调用方仍然拿不到逐次 send 的完成句柄；待处理消息可通过其 `MessageId` 移除，面向整个 agent 的取消可以丢弃整个尚未启动的队尾，而状态与完全停稳仍是面向整个 agent 的观察。
 
 代价是模型请求和检查点都会增加。繁忙队列可能需要更长时间才能清空；如果生产方持续提交消息，队列也可能增长。只有建立显式且经过测量的契约后，才能重新引入普通 send 批处理。
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
index fbca845408..b6ef95a950 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
 2026-07-22-plan-specific-collaboration-state.md: d139f3d861244c80acfb604d17172461bbf0cd57
-2026-07-22-plan-specific-collaboration-state.zh.md: a11ed1f270f58fc49a41be0e475889f84fa7cd40
+2026-07-22-plan-specific-collaboration-state.zh.md: dbf90357e4c4967d9665533c9abd2b4e1838da27
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
index a11ed1f270..dbf90357e4 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
@@ -24,7 +24,7 @@ Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/`
 
 ### 边界与模型契约
 
-`plan/mode` 仅记录到日志且不进入表层，因此恢复、fork 和压缩都能恢复该状态，无需实时镜像。spawn 出的 agent 初始处于未激活状态，因为创建时没有 plan 选项。待生效的用户选择会在初始或续步 pre-step、或请求恢复重试时，于受影响的请求组装前写入日志；持久追加失败会让意图保持待定，留到后续边界处理。
+`plan/mode` 仅记录到日志且不进入表层，因此恢复、fork 和压缩（compaction）都能恢复该状态，无需实时镜像。spawn 出的 agent（智能体）初始处于未激活状态，因为创建时没有 plan 选项。待生效的用户选择会在初始或续步 pre-step 时，或在请求恢复重试时，于受影响的请求组装前写入日志；持久追加失败会让意图保持待定，留到后续边界处理。
 
 激活状态在提示词顺序 50 处贡献部署提供的区段。未激活状态不贡献区段，但 `exit_plan_mode` 在两种状态下都保持注册，因此状态转换会改变已记录的请求头，却不改变原生工具 schema 或 Code Mode SDK。用户发起的转换只会在上一条请求头描述相反状态时追加一条来源为插件的通知；第一次请求前的选择或最终状态未变化的选择不会追加通知，经批准的工具退出则依赖其工具结果，不再追加第二条通知。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
index 45d89e4af1..1bd3e02df3 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
 2026-07-23-collapse-persistence-flush-state.md: 2801079e5b322d076eced3a0113e7958d9b4c3b9
-2026-07-23-collapse-persistence-flush-state.zh.md: dfc8fc9576416b1f51f4f9c978f49aee4f39f938
+2026-07-23-collapse-persistence-flush-state.zh.md: d5b02ebc545a32fbdb44feed04ec2afbbafeff4b
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
index dfc8fc9576..d5b02ebc54 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-每个活跃的 `Session` 都有一个生命周期条目，其中包含初始化和一个包私有写入控制器。该控制器负责 `pending`、固定批处理计时器、可选的活跃写入、自动重试暂停和共享 flush 屏障。`session/event` 监听器将冻结的事件复制到 `pending`；第一个事件设定固定截止时间，后续事件加入但不会重置。一次写入会取出一个稳定的待处理前缀；写入期间接纳的事件仍留在待处理队列中，并形成另一个独立有界的后续批次。
+每个活跃的 `Session` 都有一个生命周期条目，其中包含初始化和一个包私有写入控制器。该控制器负责 `pending`、固定批处理计时器、可选的活跃写入、自动重试暂停和共享刷新屏障。`session/event` 监听器将冻结的事件复制到 `pending`；第一个事件设定固定截止时间，后续事件加入但不会重置。一次写入会取出一个稳定的待处理前缀；写入期间接纳的事件仍留在待处理队列中，并形成另一个独立有界的后续批次。
 
-`session/flush` 是即时完全停稳屏障。它等待初始化完成、取消批处理计时器、等待任何活跃尝试完成，并排空待处理事件，包括屏障运行期间接纳的事件。后台写入失败会被记录，但不会拒绝同步事件生产方；系统会恢复完整且顺序不变的批次，并暂停自动重试。新事件会开启新的固定窗口；显式 flush、退役或后端资源销毁会立即重试，并在失败再次发生时向调用方暴露失败。
+`session/flush` 是即时完全停稳屏障。它等待初始化完成、取消批处理计时器、等待任何活跃尝试完成，并排空待处理事件，包括屏障运行期间接纳的事件。后台写入失败会被记录，但不会拒绝同步事件生产方；系统会恢复完整且顺序不变的批次，并暂停自动重试。新事件会开启新的固定窗口；显式刷新、退役或后端资源销毁会立即重试，并在失败再次发生时向调用方暴露失败。
 
 初始化只进入现有的按 id 操作链一次，并在占有该轮执行权时调用未串行化的核心操作。该操作链与活跃控制器保持分离，因为公共 `create`、`append`、`load` 调用即使没有 `Session` 对象仍可能发生竞态，依然需要按标识串行执行。
 
@@ -44,6 +44,6 @@ Status: implemented
 
 ## 后果
 
-活跃会话条目把初始化与一个控制器放在一起；该控制器负责待处理事件、计时器、活跃写入、重试暂停和 flush 屏障。协调器仍以独立容器保存已持久化的标识状态、准备好的冷态 Session、标识退役等待方和按 id 操作链，因为即使不存在可写的活跃 Session，这些生命周期仍然存在。有界写入缩短了通常情况下因崩溃而丢失数据的窗口，相比即时调度产生更少的后端批次，同时不改变强制屏障。
+活跃会话条目把初始化与一个控制器放在一起；该控制器负责待处理事件、计时器、活跃写入、重试暂停和刷新屏障。协调器仍以独立容器保存已持久化的标识状态、准备好的冷态 Session、标识退役等待方和按 id 操作链，因为即使不存在可写的活跃 Session，这些生命周期仍然存在。有界写入缩短了通常情况下因崩溃而丢失数据的窗口，相比即时调度产生更少的后端批次，同时不改变强制屏障。
 
 `session/flush` 不再决定普通持久化何时开始。它仍是循环和检查点策略使用的顺序与错误观测边界，因此检查点成功仍表示在其完成前接纳的每个事件都已持久化。
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
index 507c607217..5067b15402 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
 2026-07-24-agent-loop-observable-state-machine.md: b1773fdf7fd3bcbea9c6b9a4a0ce37c715bce4ca
-2026-07-24-agent-loop-observable-state-machine.zh.md: a4ed98117b965b445ec0888c55a1b1b27887532a
+2026-07-24-agent-loop-observable-state-machine.zh.md: f47e5901ec97a44efa00cf79ef8ce52fdcac9878
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
index a4ed98117b..f47e5901ec 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
@@ -21,7 +21,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 - 待处理消息插入时会发出 `agent/inbox/inserted`，随后要么在原子纯删除领取后发出 `agent/inbox/claimed`，要么在普通删除后发出 `agent/inbox/discarded`。`MessageId` 关联确切消息；持久 splice 坐标保留 placement 与取消信息。inbox 事件描述插入、领取和丢弃，而不是轮次完成。
 - 已领取的轮次经过 pre-step 进入决策和零个或多个请求步骤。自动重试会关闭失败轮次并立即开启另一个轮次；`agent/settled` 只报告该重试链的终态轮次，且仍不同于 agent 整体转换到 `status === 'idle'`。
 
-循环保留四个状态机扩展事件。`agent/pre-step` 对独占的已领取批次执行 reject 或 enter 决策，并在每个拟议步骤前运行。`agent/request` 是冻结调用配置所用的 waterfall；配置只能来自 `await next()`，不再通过重复的位置参数提供。`agent/request-error` 串行确定需要等待的模型请求恢复由谁负责。当轮次原本已经没有剩余工作时，`agent/turn-stopping` 运行；需要再执行一个步骤的监听器使用 `agent.steer()` 记录真实的 steering，循环在所有监听器完成后根据这份数据作出决定。
+循环保留四个状态机扩展事件。`agent/pre-step` 对独占的已领取批次执行 reject 或 enter 决策，并在每个拟议步骤前运行。`agent/request` 是冻结调用配置所用的 waterfall；配置只能来自 `await next()`，不再通过重复的位置参数提供。`agent/request-error` 串行确定需要等待的模型请求恢复由谁负责。当轮次原本已经没有剩余工作时，`agent/turn-stopping` 运行；需要再执行一个步骤的监听器使用 `agent.steer()` 记录真实的 steering（中途引导），循环在所有监听器完成后根据这份数据作出决定。
 
 是否继续和终止执行由数据表达，不再由返回的控制枚举表达。工具调用和已接受的 steering 要求再执行一个步骤。携带 `concludesTurn` 的工具结果会在其所属步骤终止工具循环。循环不再暴露通用的 `ContinuationDecision` 或终止返回通道。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
index 1e375b34d3..c0bccacb78 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
 2026-07-25-client-settings-locale-theme.md: fdcdcff92fa324803d5f2343f3fc3d9dcca069c7
-2026-07-25-client-settings-locale-theme.zh.md: b1536a1515fa7022320934dfdabf94c815e8ba04
+2026-07-25-client-settings-locale-theme.zh.md: 9cf973aee29cc1072c2fdaf1ce67e0b8395f1d90
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
index b1536a1515..9cf973aee2 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
@@ -55,11 +55,11 @@ root
             └─ models (order 10)         ui-models 注册
 ```
 
-section/item contribution 使用 `ctx.slots.inject()`，不依赖 client manifest 的 apply 顺序；本地化 label 走 [全量接入 Note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md) 的 label thunk。SlotMap 类型分家：trigger/header/close/section 正家在 ui-settings contract（消费者 general/models 均依赖壳，无环）；`settings.general.item` 正家在 locale 包——它是全部 item 注册方的最低公共依赖（设置行必带文案），而声明方 general 的 contract 对 locale/ui-theme 不可达（会成环）；ui-theme 经 re-export seam 消费。
+section/item contribution 使用 `ctx.slots.inject()`，不依赖 client manifest（元数据清单）的 apply 顺序；本地化 label 走 [全量接入 Note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md) 的 label thunk。SlotMap 类型分家：trigger/header/close/section 正家在 ui-settings 约定（消费方 general/models 均依赖壳，无环）；`settings.general.item` 正家在 locale 包——它是全部 item 注册方的最低公共依赖（设置行必带文案），而声明方 general 的约定对 locale/ui-theme 不可达（会成环）；ui-theme 经 re-export seam 消费。
 
 ### slot 声明是一等可注入等待对象
 
-`SlotsService.inject()` 直接等待有类型约束的 ledger key；它不会将声明桥接为合成的 `slot:<name>` Cordis 服务。回调会跟随声明折叠与重新声明，而其控制器仍归贡献方插件 fiber 所有；直接向未声明 slot 注册仍会大声失败。这删除了陈旧 disposer 判在位机器和容易因拼写错误出错的平行服务命名空间。完整的生命周期与失败契约见 [slot 声明注入决策](../../implemented/architecture/2026-08-05-slot-declaration-injection.md)。
+`SlotsService.inject()` 直接等待有类型约束的 ledger key；它不会将声明桥接为合成的 `slot:<name>` Cordis 服务。回调会跟随声明撤销与重新声明，而其控制器仍归贡献方插件 fiber 所有；直接向未声明 slot 注册仍会显式报错。这移除了陈旧 disposer 的在位判定机制和容易因拼写错误出错的平行服务命名空间。完整的生命周期与失败约定见 [slot 声明注入决策](../../implemented/architecture/2026-08-05-slot-declaration-injection.md)。
 
 ### 服务契约
 
@@ -127,4 +127,4 @@ Locale 内置中文和 English；`setLocale`/`setTheme` 是唯一写入口，未
 
 ## 风险
 
-slot 声明与 contribution 的 apply 顺序不固定，所有 section/item 注册方必须使用 `ctx.slots.inject()`，而不能以服务或本地 disposer 作为在位信号。service event 可能早于行首次渲染，功能行 store 的 init 与 inject attach 都必须从 getter 对齐当前 snapshot。`settings.general.item` 的重复合并副本（locale、ui-theme）与 ui-settings 正家必须逐字一致，漂移即三处一起改。Layout 卸载时必须清理自己设置的全局属性，ThemeService dispose 时必须移除 matchMedia 监听，避免 HMR 后残留。
+slot 声明与 contribution 的 apply 顺序不固定，所有 section/item 注册方必须使用 `ctx.slots.inject()`，而不能以服务或本地 disposer 作为在位信号。服务事件可能早于行首次渲染，功能行 store 的 init 与 inject attach 都必须从 getter 对齐当前 snapshot。`settings.general.item` 的重复合并副本（locale、ui-theme）与 ui-settings 正家必须逐字一致，漂移即三处一起改。Layout 卸载时必须清理自己设置的全局属性，ThemeService dispose 时必须移除 matchMedia 监听，避免 HMR（热模块替换）后残留。
diff --git a/docs/cookbook/adding-an-llm-adapter.i18n.yaml b/docs/cookbook/adding-an-llm-adapter.i18n.yaml
index 13827c2b60..199a870ac9 100644
--- a/docs/cookbook/adding-an-llm-adapter.i18n.yaml
+++ b/docs/cookbook/adding-an-llm-adapter.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-an-llm-adapter.md
 adding-an-llm-adapter.md: 4fcc646ed2eea8a6170027d01761887aa28b0045
-adding-an-llm-adapter.zh.md: 35a671416f8160a6187a06f3dbd614dfe4faa778
+adding-an-llm-adapter.zh.md: eeeb84583fb9951745083b60385547d14f461266
diff --git a/docs/cookbook/adding-an-llm-adapter.zh.md b/docs/cookbook/adding-an-llm-adapter.zh.md
index 35a671416f..eeeb84583f 100644
--- a/docs/cookbook/adding-an-llm-adapter.zh.md
+++ b/docs/cookbook/adding-an-llm-adapter.zh.md
@@ -36,7 +36,7 @@ export function apply(ctx: Context, config: Config) {
 
 ## 实现结构
 
-让协议类型、请求序列化、传输解析、分片转换和适配器类分别承担独立职责；[`llm-deepseek`](../../packages/llm/llm-deepseek/README.md) 是参考布局。
+让协议格式（wire format）类型、请求序列化、传输解析、分片转换和适配器类分别承担独立职责；[`llm-deepseek`](../../packages/llm/llm-deepseek/README.md) 是参考布局。
 
 ## 验证
 
diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml
index 539a3f396e..a00432f1d5 100644
--- a/docs/defensive-patterns.i18n.yaml
+++ b/docs/defensive-patterns.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/defensive-patterns.md
 defensive-patterns.md: 6dc1708f0b9bbcb00ad4774006d6d60059accf6a
-defensive-patterns.zh.md: 4c376f1a5f2f6d5fbe85124ce473bc7af5ad4c8d
+defensive-patterns.zh.md: 2ff5cba2a94c5149f2b92b37845d23211ee7989d
diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md
index 4c376f1a5f..2ff5cba2a9 100644
--- a/docs/defensive-patterns.zh.md
+++ b/docs/defensive-patterns.zh.md
@@ -10,11 +10,11 @@
 
 ## 跨 seam 契约两侧都要遵守
 
-当一个实现边界接收到同一结果的多种表示时，应在跨越公共 seam 前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止 finish chunk 暴露模型请求失败；middleware 与消费方缺陷仍会抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化契约；通过真实消费方覆盖每种来源形式。
+当一个实现边界接收到同一结果的多种表示时，应在跨越公共 seam 前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止型 finish 分片暴露模型请求失败；middleware 缺陷与消费方缺陷仍会以异常形式抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化后的约定；通过真实消费方覆盖每种来源形式。
 
 ## 异步状态不是同步状态
 
-`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent 下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。
+`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent（智能体）下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。
 
 ## Dispose 必须达到完全停稳，而不仅仅是请求停止
 
diff --git a/docs/user/develop/basic/config.i18n.yaml b/docs/user/develop/basic/config.i18n.yaml
index 6bf0ddea72..2887d77209 100644
--- a/docs/user/develop/basic/config.i18n.yaml
+++ b/docs/user/develop/basic/config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/config.md
 config.md: 02998c32415b5ba7acf82700034cabc1f7314f33
-config.zh.md: 42af432b36d8f82871aa7d7b6a3a2eaf7427cdae
+config.zh.md: 161af5d6703b4cc77d63443a5a80846593d1c7fd
diff --git a/docs/user/develop/basic/config.zh.md b/docs/user/develop/basic/config.zh.md
index 42af432b36..161af5d670 100644
--- a/docs/user/develop/basic/config.zh.md
+++ b/docs/user/develop/basic/config.zh.md
@@ -93,7 +93,7 @@ export interface Config {
 
 ### 配置错误要响亮
 
-在 schema 中表达自身完备的约束，使无效配置在插件加载时失败。对服务或已注册资源的引用需要依赖注入；[服务教程](../framework/service.md)会介绍这项契约。
+在 schema 中表达自身完备的约束，使无效配置在插件加载时失败。对服务或已注册资源的引用需要依赖注入；[服务教程](../framework/service.md) 会介绍这项约定。
 
 ## 配合 HMR
 
diff --git a/docs/user/develop/basic/tool.i18n.yaml b/docs/user/develop/basic/tool.i18n.yaml
index 467ab841d6..cb9759860e 100644
--- a/docs/user/develop/basic/tool.i18n.yaml
+++ b/docs/user/develop/basic/tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/tool.md
 tool.md: 8505bdaf6fcece3235b0302d54e82ee8aed3cbab
-tool.zh.md: 1831afa9be74756cb9bb1e96515fefd3685ee4c2
+tool.zh.md: c6c579c5da9dc545c2795e65331810528c37219f
diff --git a/docs/user/develop/basic/tool.zh.md b/docs/user/develop/basic/tool.zh.md
index 1831afa9be..c6c579c5da 100644
--- a/docs/user/develop/basic/tool.zh.md
+++ b/docs/user/develop/basic/tool.zh.md
@@ -1,4 +1,4 @@
-# 构建工具
+# 开发一个工具
 
 [English](tool.md) | 中文
 
diff --git a/examples/acp-agent/README.i18n.yaml b/examples/acp-agent/README.i18n.yaml
index 0bfa1735ce..cf9fee7334 100644
--- a/examples/acp-agent/README.i18n.yaml
+++ b/examples/acp-agent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write examples/acp-agent/README.md
 README.md: 61c6efafe9dde4f91385beebdfd426c57006187b
-README.zh.md: 343e55722a4dda7c5cc5e0de6b5fecf250b9ab13
+README.zh.md: 6eaf9fb5a91c737254e785d8601961b547e4e9ca
diff --git a/examples/acp-agent/README.zh.md b/examples/acp-agent/README.zh.md
index 343e55722a..6eaf9fb5a9 100644
--- a/examples/acp-agent/README.zh.md
+++ b/examples/acp-agent/README.zh.md
@@ -9,7 +9,7 @@ pnpm run demo:acp             # needs DEEPSEEK_API_KEY (repo-root .env or env)
 pnpm run demo:code-mode       # same protocol with the Code Mode tool transport
 ```
 
-该叶节点加载 ACP 应用、DeepSeek 适配器、受沙箱限制的 bash 与文件系统栈、一次性批准策略、压缩（compaction）、subagent、工作流、钩子、派生会话查询索引和重复守卫。应用为每次 `session/new` 创建一个新 agent，将会话持久化到 JSONL，并保持 stdout 只含协议内容。可选 overlay 可添加会话查询、文件系统溢出存储、Code Mode 或 Web 抓取。
+该叶节点加载 ACP 应用、DeepSeek 适配器、受沙箱限制的 bash 与文件系统栈、一次性批准策略、压缩（compaction）、subagent、工作流、钩子、派生会话查询索引和重复守卫。应用为每次 `session/new` 创建一个新 agent，将会话持久化到 JSONL，并保持 stdout 只含协议内容。可选 overlay 可添加会话查询、文件系统 spill 存储、Code Mode 或 Web 抓取。
 
 ## 协议通道
 
diff --git a/examples/jsonrpc-agent/README.i18n.yaml b/examples/jsonrpc-agent/README.i18n.yaml
index ce35a749a0..e1c36e959c 100644
--- a/examples/jsonrpc-agent/README.i18n.yaml
+++ b/examples/jsonrpc-agent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write examples/jsonrpc-agent/README.md
 README.md: bcc1027d2edb30ab374dfa2ed13ad8e6360d923b
-README.zh.md: 197c25d7b4f5645aeb7e92d8c36ef4a423beb2e8
+README.zh.md: ce255e4dd70bf8c5c6edc51afbe03bb4c66560a0
diff --git a/examples/jsonrpc-agent/README.zh.md b/examples/jsonrpc-agent/README.zh.md
index 197c25d7b4..ce255e4dd7 100644
--- a/examples/jsonrpc-agent/README.zh.md
+++ b/examples/jsonrpc-agent/README.zh.md
@@ -26,11 +26,11 @@
 
 通过 Python SDK 的 `cordis` 选项或 `DSH_CORDIS_CONFIG` 传入配置路径。内置可执行文件已携带此文件中指定的每个插件；目标机器无需 Node.js。
 
-## 持久工具变体
+## 持久化工具变体
 
 [`persistent-tools.cordis.yml`](persistent-tools.cordis.yml) 是一个最小可运行变体，面向模型的能力严格只有：
 
-- agent 独占、状态持久的 `bash`
+- 所有者作用域内持久化的 `bash`
 - 提供 `view`、`create`、`str_replace` 与 `insert` 的 `str_replace_editor`
 
-它组合本地 PTY、文件系统 intent 策略与会话沙箱策略。
+它组合了本地 PTY、文件系统意图策略与会话沙箱策略。
diff --git a/native/README.i18n.yaml b/native/README.i18n.yaml
index 31a86ebe73..258111fbdb 100644
--- a/native/README.i18n.yaml
+++ b/native/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write native/README.md
 README.md: 51c8da7b57df15e65b8e431ee18ce6cebb89d54b
-README.zh.md: baf530157c6731893a66aea301c6dd962592defc
+README.zh.md: 55dd5eb0a197bd970b33f7943877fb3826858128
diff --git a/native/README.zh.md b/native/README.zh.md
index baf530157c..55dd5eb0a1 100644
--- a/native/README.zh.md
+++ b/native/README.zh.md
@@ -2,10 +2,10 @@
 
 [English](README.md) | 中文
 
-与 DeepSeek Harness 一同维护的原生源码和公开包。[`landlock-run/` workspace](landlock-run/README.md)负责 harness 使用的 Landlock 自限后执行启动器，包括其架构、由三个包组成的 npm 包家族、平台支持、开发工作流和[发布流程](landlock-run/docs/release.md)。
+与 DeepSeek Harness 一同维护的原生源码和公开包。[`landlock-run/` workspace](landlock-run/README.md) 负责 harness 使用的 Landlock 自限后执行启动器，包括其架构、由三个包组成的 npm 包家族、平台支持、开发工作流和[发布流程](landlock-run/docs/release.md)。
 
 ## Workspace 与发布边界
 
-`landlock-run/` 及其包属于仓库根 pnpm workspace，并共用根锁文件。开发和 CI 中的 harness 消费方直接使用当前 workspace 的入口包，因此启动器契约变更与消费方更新可以在同一个改动中落地并一起测试。
+`landlock-run/` 及其包属于仓库根 pnpm workspace，并共用根锁文件。开发和 CI 中的 harness 消费方直接使用当前 workspace 的入口包，因此启动器约定变更与消费方更新可以在同一个改动中落地并一起测试。
 
 主仓库的 `Landlock Run` 工作流为每个受支持架构构建并测试。`Landlock Run Release` 汇集这些原生产物，打包并验证三个 npm tarball，随后可选择以同一个启动器版本发布。入口包继续将平台包声明为 npm 可选依赖，因此 npm 仍然只会安装与用户操作系统和 CPU 匹配的包。
diff --git a/native/landlock-run/README.i18n.yaml b/native/landlock-run/README.i18n.yaml
index c204d571cf..2189d62b3c 100644
--- a/native/landlock-run/README.i18n.yaml
+++ b/native/landlock-run/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write native/landlock-run/README.md
 README.md: fcb8e8249e6728d925fd08c938a780b155d3d4ac
-README.zh.md: 8206ab8074d8d80fb9b11cff436bbd10e6dc34dd
+README.zh.md: c994087317be54d522d965de3e120da6fabb7ded
diff --git a/native/landlock-run/README.zh.md b/native/landlock-run/README.zh.md
index 8206ab8074..c994087317 100644
--- a/native/landlock-run/README.zh.md
+++ b/native/landlock-run/README.zh.md
@@ -39,7 +39,7 @@ if (probe(launcher) !== 'unusable') {
 - `launcherPath()`：当前宿主启动器的绝对路径（有意不检查是否存在；探测结果才是可用性信号）。
 - `probe(launcher?, { timeoutMs? })`：功能性强制执行探测，返回 `'full' | 'partial' | 'unusable'`。
 - `grantArgs({ readOnly?, readWrite? })`：启动器的授权 argv；未授予的一切都被拒绝。
-- `LAUNCHER_BIN` 和 `LAUNCHER_FAILURE_EXIT`（125）：契约常量。成功完成 exec 的子进程也可能返回 125，因此消费者必须同时看到致命诊断和该状态，才能将结果归因为 launcher 失败。
+- `LAUNCHER_BIN` 和 `LAUNCHER_FAILURE_EXIT`（125）：约定常量。成功完成 exec 的子进程也可能返回 125，因此消费方必须同时看到致命诊断和该状态，才能将结果归因为启动器失败。
 
 完整的二进制契约（argv 语法、退出码、报告行）锁定在 [docs/cli-contract.md](docs/cli-contract.md) 中。
 
diff --git a/packages/acp/acp/README.i18n.yaml b/packages/acp/acp/README.i18n.yaml
index e0353e1ff7..1c8c175eb0 100644
--- a/packages/acp/acp/README.i18n.yaml
+++ b/packages/acp/acp/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/acp/acp/README.md
 README.md: 9cc4a5e271c7200f6ad8799a4b8fa9e64b2ca893
-README.zh.md: 82aa5df2c7d87312d4b619a09582cc0c2d884398
+README.zh.md: 4856b44683b5594ad0211af907d1a12ce814d492
diff --git a/packages/acp/acp/README.zh.md b/packages/acp/acp/README.zh.md
index 82aa5df2c7..4856b44683 100644
--- a/packages/acp/acp/README.zh.md
+++ b/packages/acp/acp/README.zh.md
@@ -24,7 +24,7 @@
 | `initialize` | 协商受支持的版本，并仅公布基线提示词（无图像、音频或嵌入上下文能力）。不公布会话、编辑器、终端、文件系统或 MCP 能力。 |
 | `authenticate` | 空操作，因为服务器不公布身份验证方法。 |
 | `session/new` | 以绝对路径作为主 `cwd` 创建新 agent；接受空的 `additionalDirectories` 和 `mcpServers`，拒绝非空值。 |
-| `session/prompt` | 拼接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并等待整个 agent 进入 idle。正常完全停稳时报告 `end_turn`；显式 ACP 取消、资源释放，或准入被丢弃的提示词（turnless 槽位）时报告 `cancelled`。 |
+| `session/prompt` | 拼接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并等待整个 agent 进入空闲状态。正常完全停稳时报告 `end_turn`；显式 ACP 取消、资源释放，或准入被丢弃的提示词（无轮次槽位）时报告 `cancelled`。 |
 | `session/cancel` | 仅取消指定的 agent，并将其待处理提示词结算为 `cancelled`；未知 id 为空操作。 |
 | `session/update` | 为每个非空文本块发出一个 `agent_message_chunk`；这些文本块来自已提交的 `assistant/message`。省略原始增量和非消息事件。 |
 | `session/request_permission` | 为携带工具调用 id、由桥接层拥有的批准请求提供一次性允许／拒绝选项。客户端可以自动回答。 |
@@ -37,7 +37,7 @@
 
 客户端断开与 Cordis 释放共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，结算待处理提示词，然后只 drain 此连接确切拥有的 Agent 之下的可继续后代，再并行释放这些 handle，并等待全部结果结算后才报告失败。其他共享该上下文的前端会保留其可继续森林和准入。因此，仅 ACP 的插件重载不会遗留 agent。
 
-ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它表示提示词专属的轮次结果。已提交的 assistant 消息会在整个自有活动期间流式输出，agent 进入 idle 前发生的 steering（中途引导）或注入工作也可能参与其中。因此，因 token 上限而结束的轮次不会成为提示词级 ACP 停止原因（它们以 `end_turn` 结算）；关联轮次上的模型错误会立即 reject 提示词。
+ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它表示提示词专属的轮次结果。已提交的 assistant 消息会在整个自有活动期间流式输出，agent 进入空闲状态前发生的 steering（中途引导）或注入工作也可能参与其中。因此，因 token 上限而结束的轮次不会成为提示词级 ACP 停止原因（它们以 `end_turn` 结算）；关联轮次上的模型错误会立即拒绝该提示词。
 
 ## 运行
 
diff --git a/packages/bash/bash-sandbox/README.i18n.yaml b/packages/bash/bash-sandbox/README.i18n.yaml
index 2de1c468b8..b4eb8c4869 100644
--- a/packages/bash/bash-sandbox/README.i18n.yaml
+++ b/packages/bash/bash-sandbox/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/bash-sandbox/README.md
 README.md: 74c1e28f76db35603bb9f72e0522e16ece5589f7
-README.zh.md: 2593049ce09c7bc1ae0a996321bb27cbac449977
+README.zh.md: 34ad936f31bf4ce11e175653a3a895a56e4822cc
diff --git a/packages/bash/bash-sandbox/README.zh.md b/packages/bash/bash-sandbox/README.zh.md
index 2593049ce0..34ad936f31 100644
--- a/packages/bash/bash-sandbox/README.zh.md
+++ b/packages/bash/bash-sandbox/README.zh.md
@@ -18,7 +18,7 @@
 
 - **拒绝是结果事实。** 如果一次失败运行的 stderr 包含所选后端自身的拒绝方言，即提供方在每次包装时加上的特征（bwrap 下的 EROFS 文本、Landlock 下的 EACCES、Seatbelt 下的 EPERM），则结果报告 `BashRunResult.sandbox.denied: true`（从已收集的 stderr 尾部进行保守分类）。每次受限制运行还会携带执行时模式（`result.sandbox.mode`）与提供方强制执行完整性（`result.sandbox.enforcement`：`full`，或在较旧 Landlock ABI 上为 `partial`）。
 - **Runner 归因是保守的。** 进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且带有明确指向提供方 argv[0] 的来源信息时，才会将拒绝归因于 runner。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessService` 同步抛出同样带有来源信息的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，先按整行精确匹配排除信息性行，随后规则的可选退出码门控和余下 stderr 中的一行致命诊断必须同时匹配。匹配结果优先于拒绝；前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带匹配到的致命行，已结算的后台进程则会标记 `process.sandbox.runnerFailed`，Bash 结果生成方通过通用 `task_output` 渲染它。无论走哪条路径，受限制的后台句柄都会保留自身的模式／强制执行事实，并释放每进程计数。
-- **部署回退，每次调用策略。** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) 为每次工具调用解析完整的 `SandboxExecutionPolicy`：调用会话提供自身的模式覆盖与不可变 cwd 根目录，部署配置则为无 agent（智能体）调用提供回退。已批准的升权只更改该策略的模式，会话根目录仍然附着其上。`resolve()` 把策略带入 spec，因此来自不同项目的重叠命令会在各自的根目录与模式下运行、分类和报告。能力事实 `ctx.bash.sandboxMode` 报告已配置的默认值，因此工具层只在装载该执行器时才公布升权；静态 bash 工具描述则单独负责拒绝与升级引导。
+- **部署回退，每次调用策略。** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) 为每次工具调用解析完整的 `SandboxExecutionPolicy`：调用会话提供自身的模式覆盖与不可变 cwd 根目录，部署配置则为无 agent（智能体）调用提供回退。已批准的升权只更改该策略的模式，会话根目录仍然附着其上。`resolve()` 把策略带入 spec，因此来自不同项目的重叠命令会在各自的根目录与模式下运行、分类和报告。能力事实 `ctx.bash.sandboxMode` 报告已配置的默认值，因此工具层只在装载该执行器时才公布升权；静态 bash 工具描述则单独负责拒绝与升权引导。
 - **只限制文件影响。** 设计上不限制网络与进程可见性：模式词汇不会声称覆盖后端未强制执行的范围。
 - 进程机制（spawn、进程组终止、输出收集／spill、后台句柄、凭证清理）继承自 [`dsh-bash-local`](../bash-local/)；runner 选择位于 [`dsh-sandbox-local`](../../sandbox/sandbox-local/)。
 
diff --git a/packages/client/hmr/README.i18n.yaml b/packages/client/hmr/README.i18n.yaml
index 86859e79f6..f9ce3024f1 100644
--- a/packages/client/hmr/README.i18n.yaml
+++ b/packages/client/hmr/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/hmr/README.md
 README.md: 454c03cc3cd11722943efd025d164d9ca8233d25
-README.zh.md: fc4100c48e5db9ed6781117dd652232bbd7c7aaa
+README.zh.md: ea62600911458556a3dcc7c46854e97db751c3ef
diff --git a/packages/client/hmr/README.zh.md b/packages/client/hmr/README.zh.md
index fc4100c48e..ea62600911 100644
--- a/packages/client/hmr/README.zh.md
+++ b/packages/client/hmr/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-为通过外部脚本加载的客户端插件提供热重载。该静态加载配置项只组合进 `--dev` 图（`dsh web --dev`）；生产图省略该项，因此打包进 shell 的代码保持不活动。
+为通过脚本加载的客户端插件提供热重载。该静态加载配置项只组合进 `--dev` 图（`dsh web --dev`）；生产图省略该项，因此打包进 shell 的代码保持不活动。
 
 浏览器侧订阅系统 SSE（Server-Sent Events）通道（`GET /plugins/events`），每个 `rebuilt` 帧重载一个插件，并通过队列串行执行。每帧的顺序是：`invalidate`、`prefetch`（旧 fiber 仍在服务时加载并注册新组合包）、`registry.delete`（在 fiber dispose（资源释放）之前执行：仅 dispose fiber 会触发 vendored Loader 的 self-dispose 分支，把配置项标为禁用）、排空旧 fiber、删除 `entry.fiber`、移除自身拥有的 `<style data-plugin>` 标签、通过 `entry.refresh()` 重新导入并挂载、通过 `fiber.await()` 直接重新抛出启动失败。依赖方由 Cordis 自身重载：fiber 的激活 epoch 会串联其服务提供方的 uid，因此替换提供方 fiber 会级联所有依赖方，无需客户端图分析。node 侧使用一个 interval 检测重建：从同步基线开始 stat-poll 每个图组合包；新增一行后立即重新计算 hash；缺失行保持 dirty；只广播真实 rev 变更。因此，任何生成组合包的 tsdown watch 进程都能触发 HMR（热模块替换），无需 builder→host 通道。
 
diff --git a/packages/client/modules/README.i18n.yaml b/packages/client/modules/README.i18n.yaml
index fa284aabd7..2f7278eae2 100644
--- a/packages/client/modules/README.i18n.yaml
+++ b/packages/client/modules/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/modules/README.md
 README.md: 7d661c806955d0fac021dd6620994aab83c0f773
-README.zh.md: a1da42a552dbe8770fcb78bf458c01a0057ce8dd
+README.zh.md: aec59474fbf01857380709ebecb6ae99a6ca8174
diff --git a/packages/client/modules/README.zh.md b/packages/client/modules/README.zh.md
index a1da42a552..aec59474fb 100644
--- a/packages/client/modules/README.zh.md
+++ b/packages/client/modules/README.zh.md
@@ -8,7 +8,7 @@
 
 解析分支顺序（`import(specifier)`）：平台种子词 → 外壳实例；记忆化记录 → 表层；外壳自身的静态注册表（`registerStatic`，app-shell）→ 模块；已注册 factory → 物化；模块图记录（`window.__DSH_BOOT__`）→ 加载外部 classic script + 物化；其他情况一律抛出异常。这是构建时组合包纯度门禁的运行时镜像。交给 factory 的同步 `require` 采用相同顺序，但不含异步加载分支，并把观察到的边记录到模块记录中。`prefetch` 是第一阶段到达钩子（只加载脚本并注册 factory；并发调用共享一个进行中的任务）；`invalidate` 会丢弃 factory 与物化记录，使下一次 prefetch/import 重新加载脚本；它是 HMR（热模块替换）钩子。
 
-Node 侧会扫描已启用的 Loader 配置项以发现 web `dshClient` 包，解析每个 `exports["./client"]`，把构建后的组合包哈希写入启动图，并通过 `/plugins` 提供该文件及其 sourcemap。源码启动会把宿主侧导入映射到 TypeScript 源码，但仍消费客户端导出的构建产物；缺失文件共享一条构建要求，随后以 package/path list 列出各项，而无关的文件系统错误仍是独立故障。
+Node 侧会扫描已启用的 Loader 配置项以发现 web `dshClient` 包，解析每个 `exports["./client"]`，把构建后的组合包哈希写入启动图，并通过 `/plugins` 提供该文件及其 sourcemap。源码启动会把宿主侧导入映射到 TypeScript 源码，但仍消费这一构建后的客户端导出；缺失文件共享一条构建说明，随后以 package/path list 列出各项，而无关的文件系统错误仍是独立故障。
 
 ## 模型体验
 
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 1edac07d5e..92b9e2abfc 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/runtime/README.md
 README.md: a9b604974595b1b7856f74b72d36093491ec1bd1
-README.zh.md: 6eee14bdbe7a9fb86b0a12355e7d0a45cd500774
+README.zh.md: 8ee06e93b475398750ee74d4900a8c6917cf71f5
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 6eee14bdbe..8ee06e93b4 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -8,7 +8,7 @@
 
 `ctx.slots.inject(name, callback)` 将完整的 `SlotMap` key 作为贡献项的依赖，适用于贡献方插件可独立于声明条目激活的情形。声明存在时，它会同步运行 `callback`，否则等待；声明折叠会 dispose（资源释放）回调 effect，重新声明则会再次运行回调。控制器归调用方的插件 fiber 所有，因此卸载贡献方会取消等待或移除其活跃注册项。直接调用 `slots.register()` 向未声明 slot 注册仍会抛出异常。
 
-回调返回一个同步 disposer 或由多个 disposer 构成的 iterable。因此，generator 可以 yield 多个 `slots.register()` 调用，并将它们组成一项事务：setup 失败会回滚先前 yield 的 effect，teardown 则按逆序运行它们。声明生命周期使用专用的单调 declaration epoch（声明代次），因此，即使折叠与重新声明合并在同一次 renderer 通知中，回调仍会重启，而普通条目变更不会重启它。声明绑定的 teardown 与账本变更同步运行，在同一 tick 内的后续注册之前释放运行时资源。详见 [slot 声明注入决策](../../../.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md)。
+回调返回一个同步 disposer 或由多个 disposer 构成的 iterable。因此，generator 可以 yield 多个 `slots.register()` 调用，并将它们组成一项事务：setup 失败会回滚先前 yield 的注册项，teardown 则按逆序运行它们。声明生命周期使用专用的单调 declaration epoch（声明代次），因此，即使折叠与重新声明合并在同一次 renderer 通知中，回调仍会重启，而普通条目变更不会重启它。声明绑定的 teardown 与账本变更同步运行，在同一 tick 内的后续注册之前释放运行时资源。详见 [slot 声明注入决策](../../../.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md)。
 
 ## Workspace 与 Session 列表
 
@@ -18,7 +18,7 @@ Workspace 和 Session 列表各自具有单调的 `pending` → `ready` 基线
 
 `WorkspacesService.delete(workspaceId)` 在一元响应成功后从客户端投影中移除注册记录；对应的 `host/workspace-removed` 帧具有幂等性，并负责同步其他标签页。Session 状态与当前 Session selection 相互独立，因此 Workspace 消失后，其已纳入客户端投影的 Session 会立即投影到 Ungrouped 下。
 
-`WorkspaceListState.archivedSessionIds` 镜像 Host 的注册表级全局归档集合（一个按 Host 顺序的 `readonly SessionId[]`，仅在成员变化时才替换；需要 O(1) 查询的消费方自建临时 Set）。它是全快照状态：`workspace.list` 基线、`archiveSession` 一元回声和 `host/archived-sessions-changed` 帧各自安装完整集合。`WorkspacesService.archiveSession(sessionId)` 通过 wire 归档；投影层在当前 selection 落入归档集合时统一清空为 New Session 视图状态——一条规则同时覆盖本地回声、其他标签页的帧、以及重连基线恢复出一个离线期间被归档的 selection。在 `workspace.list` 请求进行中安装的集合还会取代该过期基线携带的集合。各分组视图在所有位置隐藏集合成员，而会话行本身仍留在列表 store 中。
+`WorkspaceListState.archivedSessionIds` 镜像 Host 的注册表级全局归档集合（一个按 Host 顺序的 `readonly SessionId[]`，仅在成员变化时才替换；需要 O(1) 查询的消费方自建临时 Set）。它是全快照状态：`workspace.list` 基线、`archiveSession` 一元回声和 `host/archived-sessions-changed` 帧各自安装完整集合。`WorkspacesService.archiveSession(sessionId)` 通过 wire 归档；投影扫描在当前 selection 落入归档集合时将其清空为 New Session 视图状态——一条规则同时覆盖本地回声、其他标签页的帧、以及重连基线恢复出一个离线期间被归档的 selection。在 `workspace.list` 请求进行中安装的集合还会取代该过期基线携带的集合。各分组视图在所有位置隐藏集合成员，而会话行本身仍留在列表 store 中。
 
 SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 observable；web-react 创建钩子。Workspace 业务状态不会进入 `SessionListState` 或配置项 store。
 
@@ -36,9 +36,9 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 面向人的 transcript（文本记录）
 
-`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并以相同身份落成 `user/message` 时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
+`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
 
-由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时这些字段不可用，后续补上溯源的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能契约：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
+由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时这些字段不可用，后续补上溯源的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
 
 ## 请求检查
 
@@ -54,7 +54,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 模型重试投影
 
-Session 对象会在事件 wire 边界依据生产方的完整字段契约，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括计时器、整数、状态、提供方延迟和非空诊断字段的边界。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose 时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。
+Session 对象会在事件 wire 边界依据生产方的完整字段约定，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括对计时器、整数、状态、提供方延迟和非空诊断字段的约束。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose 时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。
 
 ## 会话 fork
 
diff --git a/packages/client/schema-form/README.i18n.yaml b/packages/client/schema-form/README.i18n.yaml
index 1c3c759ceb..73ec057a53 100644
--- a/packages/client/schema-form/README.i18n.yaml
+++ b/packages/client/schema-form/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/schema-form/README.md
 README.md: 716cc7ba3c24f3a4de081e2d26f803b905235fac
-README.zh.md: 65b8767df84f90eedd70e9f8ac27d7d419f06f46
+README.zh.md: 61fff15ca6a21e6267da158640e3782422e865c3
diff --git a/packages/client/schema-form/README.zh.md b/packages/client/schema-form/README.zh.md
index 65b8767df8..61fff15ca6 100644
--- a/packages/client/schema-form/README.zh.md
+++ b/packages/client/schema-form/README.zh.md
@@ -20,4 +20,4 @@
 
 - **重建 schema 会执行所收到的信封**——`rehydrateSchema` 会重建一个活的 schemastery 校验器，而 schemastery 通过 `new Function` 复活序列化过的 callback，因此 schema 信封是可执行内容，而非惰性数据。只有信封来自提供该页面的同一受信任 host 时才安全；该协议没有跨信任边界使用的惰性表示。
 - **校验是草稿级的，而非逐字段**——`validateDraft` 报告 schemastery 的第一条失败消息及其 `$.path`；它不会把错误映射到各个控件。
-- **没有通用渲染器**——消费方在这些辅助函数上构建功能专用表单。[Web 配置面 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)记录该权衡。
+- **没有通用渲染器**——消费方在这些辅助函数上构建功能专用表单。[Web 配置面 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md) 记录该权衡。
diff --git a/packages/client/ui-layout/README.i18n.yaml b/packages/client/ui-layout/README.i18n.yaml
index d04c06b3da..613876693a 100644
--- a/packages/client/ui-layout/README.i18n.yaml
+++ b/packages/client/ui-layout/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-layout/README.md
 README.md: fa60520a20ac8a7f25d494879c68efb06a28998f
-README.zh.md: 6ca04c56c29a55f84fc7a6399a7feeb81d249899
+README.zh.md: dd23550cc8f0134ed1231c86d88825dab96e8e79
diff --git a/packages/client/ui-layout/README.zh.md b/packages/client/ui-layout/README.zh.md
index 6ca04c56c2..dd23550cc8 100644
--- a/packages/client/ui-layout/README.zh.md
+++ b/packages/client/ui-layout/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏的缩放边界是不可见命中条带，详情栏边界则保留其浮动胶囊；让步期间只有详情栏会收缩并随后自动关闭。关闭的侧边栏仍保留 56px 控制栏，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量，同时拥有一个 `<meta name="theme-color">`，其内容随计算后的 body 背景色更新）。在应用调色板和 token 后进行测量，可确保渲染后的背景保持为唯一颜色真源；呈现器在资源释放时会移除其自有的元数据节点，并一并清除其写入的其他全局状态。
+外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏的缩放边界是不可见命中条带，详情栏边界则保留其浮动胶囊；让步期间只有详情栏会收缩并随后自动关闭。关闭的侧边栏仍保留 56px 控制栏，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量，同时拥有一个 `<meta name="theme-color">`，其内容随计算后的 body 背景色更新）。在应用调色板和 token 后进行测量，可确保渲染后的背景成为唯一的颜色依据；呈现器在 dispose（资源释放）时会移除其自有的元数据节点，并一并清除其写入的其他全局状态。
 
 AppFrame 始终挂载会话栏和详情栏；已连接 Session 通过 `SessionProvider` 渲染。布局 store 是瞬时状态，侧边栏以默认宽度启动，详情栏则保持关闭，且该 store 从不读写 `localStorage`。hero 和其他未选中状态也会将详情栏的渲染宽度派生为零，但不会改变存储的宽度偏好。AppFrame 会跨越这些状态保留最后一个非 blank 会话 id：首个会话保持关闭；显式打开详情栏的操作会使用契约默认宽度；返回同一会话时恢复其未改变的宽度；选择不同会话时，详情栏会在绘制前关闭。会话 owner share 为空，侧边栏 owner share 只包含 `collapsed` 和 `width`；注册方通过标准钩子获取业务数据，并从各自的 inject 接口获取操作。
 
diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml
index 25020ab686..9f6db24bba 100644
--- a/packages/client/ui-model/README.i18n.yaml
+++ b/packages/client/ui-model/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-model/README.md
 README.md: 5a6f998476629566d35af32efa5d8bc5072a872b
-README.zh.md: 2bb22c55f1ae5af59f21e254804329d288806a90
+README.zh.md: 09fee7a2cfd22b773be569e37c4c31f8c299d707
diff --git a/packages/client/ui-model/README.zh.md b/packages/client/ui-model/README.zh.md
index 2bb22c55f1..09fee7a2cf 100644
--- a/packages/client/ui-model/README.zh.md
+++ b/packages/client/ui-model/README.zh.md
@@ -6,7 +6,7 @@
 
 Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择事实，但只有当该精确路由仍在已公布分组中时才会回显；删除该目录行会保留仍可路由的目标，但触发器会提示 `Select model`，系统不会合成陈旧行，且在用户选择已公布的模型之前不会显示 Effort 行。目录加载与选择共享一个代次计数器，旧响应不会覆盖新结果；连接重置会丢弃所有常驻目录投影，并在显示前重新拉取 Host 恢复的目标。各提供方的元数据获取失败会内联列出，同时可用分组仍可选择；选择失败会保留先前的目标和目录。
 
-当宿主报告没有适配器服务该会话的路由（`session.models.routable`）时，本插件经 `ctx.conversation.blocks` 抬起一个编辑器 block，输入框随之变为惰性并显示本插件自己的文案；恢复后无需重新加载即自动清除。它只跟随 `routable`：`null`（首次加载之前，或加载失败之后）绝不阻断，否则一个慢的宿主就会锁死一个本来能用的编辑器；目录成员关系同样不阻断，因为一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用。触发器自己的 `Select model` 回退仍然覆盖那种情形——那是显示，不是闸门。
+当宿主报告没有适配器服务该会话的路由（`session.models.routable`）时，本插件经 `ctx.conversation.blocks` 注册一个 composer 阻塞块，输入框随之停用并显示本插件自己的文案；恢复后无需重新加载即自动清除。它只跟随 `routable`：`null`（首次加载之前，或加载失败之后）绝不阻断，否则一个慢的宿主就会锁死一个本来可用的 composer；目录成员关系同样不阻断，因为一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用。触发器自己的 `Select model` 回退仍然覆盖那种情形——那是显示，不是闸门。
 
 目录按会话惰性解析（`ctx.models.directoryFor(sessionId)`），随会话作用域一并释放。已寻址 subagent 会话不公开任一入口，其目录会拒绝加载、选择与重新连接刷新，因为绑定到 agent（智能体）的普通模型 RPC 会在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index 5e7b29d244..ce82152632 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-models/README.md
 README.md: 66f23d3f77adae23fcebd3adbb6c5c47ce16ae2f
-README.zh.md: dcb35c624aca73b558532210750f684e5cc54e85
+README.zh.md: d0a5ad465e713680757a3e3734fc97dc31280a2e
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index dcb35c624a..d0a5ad465e 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -4,7 +4,7 @@
 
 模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。
 
-行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可以询问提供方它服务什么。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），以及各适配器自己的模型目录。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会让整个提供方从模型选择器里消失。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可查询提供方所提供的模型。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），以及各适配器自己的模型目录。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会让整个提供方从模型选择器里消失。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。凭据引用已配置时，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
@@ -16,7 +16,7 @@ pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，
 
 **获取可用模型**会针对表单**当前显示**的端点调用 `llm.discoverModels`，包括已修改但尚未保存的 API 地址和已键入但尚未存储的密钥，因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路——适配器自己的消息会显示在各行旁边，而这些行仍可手工编辑。
 
-**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个由唯一标识的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上以一条用户无从下手的原始正则失败。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。
+**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个标识唯一的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上抛出原始正则表达式错误。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。
 
 ## 模型体验
 
diff --git a/packages/client/ui-settings/README.i18n.yaml b/packages/client/ui-settings/README.i18n.yaml
index 5871fb996f..5954e72809 100644
--- a/packages/client/ui-settings/README.i18n.yaml
+++ b/packages/client/ui-settings/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-settings/README.md
 README.md: 785f0417f00ec8eb1f8c9273b4d81f8ca5ca1810
-README.zh.md: 8e7bd7325b78416345985ee25a56a5eb8b382478
+README.zh.md: 239987e379aaabd2edbfc9e09cd2fc8cef7a685e
diff --git a/packages/client/ui-settings/README.zh.md b/packages/client/ui-settings/README.zh.md
index 8e7bd7325b..239987e379 100644
--- a/packages/client/ui-settings/README.zh.md
+++ b/packages/client/ui-settings/README.zh.md
@@ -4,7 +4,7 @@
 
 设置外壳插件：一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`，并声明由注册方填充的 slot：`settings.trigger`／`settings.header`／`settings.close`（界面框架内容）、`settings.action`（内容标题栏中的有序操作）、`settings.section`（每项功能一页）和 `settings.onboarding`（由各功能持有、显示在全视口展示层中的有序页面）。外壳不自带文案：所有文本都来自注册方（ui-settings-general 拥有界面框架、「通用」分区和产品声明；各功能拥有各自的操作、分区、行和条件式首次使用引导页面）。导航 label 可以是跟随语言的 thunk，因此导航投影经 `resolveSlotLabel` 解析，并在分区账本更新或 locale revision 变化时重新渲染（`ctx.get('locale')` 可选读取，无硬 locale 依赖）。
 
-外壳将首次使用引导记录按升序投影，每次只挂载一个页面；接管界面框架（body 层级的展示层、遮罩、应用根节点 `inert`）经 ui-primitives 的 `OnboardingSurface` 由步骤自身持有，因此已挂载但仍在判定私有事实的步骤渲染 null 时不绘制也不阻塞任何内容——步骤判定期间外壳不会露出空白展示层。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调；完成或跳过当前页面后，所有权转交给下一项。持久化完成状态、能力就绪状态、文案、变更操作以及页面的外层包裹均由注册方持有，因此独立注册的流程无法堆叠，外壳也不会成为第二个配置事实来源。
+外壳将首次使用引导记录按升序投影，每次只挂载一个页面；接管界面框架（body 层级的展示层、遮罩、应用根节点 `inert`）经 ui-primitives 的 `OnboardingSurface` 由步骤自身持有，因此已挂载但仍在判定私有事实的步骤渲染 null 时不绘制也不阻塞任何内容——步骤判定期间外壳不会露出空白展示层。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调；完成或跳过当前页面后，所有权转交给下一项。持久化完成状态、能力就绪状态、文案、变更操作以及展示层包装均由注册方持有，因此独立注册的流程无法堆叠，外壳也不会成为第二个配置事实来源。
 
 ## 模型体验
 
diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml
index cc563215dc..9b00e02b2a 100644
--- a/packages/client/ui-sidebar/README.i18n.yaml
+++ b/packages/client/ui-sidebar/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-sidebar/README.md
 README.md: 45ae267d98b17bbc612cf932f5b95b42ba6ff4bf
-README.zh.md: 436baf0b2d50934ce4813ac53c532006d9d0d4fb
+README.zh.md: c0bae62de0811874a94810bd18c78378441db8a3
diff --git a/packages/client/ui-sidebar/README.zh.md b/packages/client/ui-sidebar/README.zh.md
index 436baf0b2d..c0bae62de0 100644
--- a/packages/client/ui-sidebar/README.zh.md
+++ b/packages/client/ui-sidebar/README.zh.md
@@ -12,7 +12,7 @@ New Session 会启动运行时的页面局部前端 Session Intent；真实 Work
 
 页脚承载 `sidebar.settings`：侧边栏只渲染固定在底部的布局 slot，并共享其栏状态（`wide`）；ui-settings 在此注册触发行和设置面板。
 
-`/client` 导出表层只包含插件主体（`apply`／`inject`）及契约类型；SidebarRoot、行组件和树派生仍由 slot 注册封装在包内。
+`/client` 导出表层只包含插件主体（`apply`／`inject`）及约定类型；SidebarRoot、行组件和树派生仍由 slot 注册封装在包内。
 
 ## 模型体验
 
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index 5aa997d003..b7c737a98f 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-skill/README.md
 README.md: 44953fe36ad337d0dd70e4d8c0cc2372b8924c9b
-README.zh.md: 8c21ef35eded61324d139dd32b7c1e38f8709d55
+README.zh.md: 3a8ac86d13114bdbbb78c33d907aba7bb1a10fc2
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 8c21ef35ed..3a8ac86d13 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -4,7 +4,7 @@
 
 skill（技能）调用 source 的浏览器端：把 `/` 触发的 `skill` source 注册进 `ctx.slash`。普通会话的候选来自 `skill.list` RPC，以每次调用的 `ClientSessionContext` 投影中的 `{sessionId}` 寻址，host 从会话 header 解析 `cwd`。宿主提供每一个用户可调用的 skill；`modelInvocable: false` 的条目（即 `disable-model-invocation` skill，此路径是其唯一入口）会以当前语言把仅限用户标记作为描述前缀带上。由目录寻址的可继续 subagent 在客户端解析为没有 skill 候选，因为现有 skill RPC 要求会话已挂载；查看其持久化历史不得激活它。目录按普通会话缓存，拉取走 single-flight；scope 创建时的 `warm` 钩子预热该会话的缓存项，`connection/reset` 清空全部缓存。结果按 `startsWith(query)` 过滤。
 
-pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文本（决策 21）——本 source 不实现任何裁决钩子，也没有引用 codec（旧的 `<skill>name</skill>` 形式已随移除裁定消失）。确定性在宿主侧：pre-step 手势边界（`dsh-tool-skill`）识别用户消息中任意位置、以空白为界、指名用户可调用 skill 的 `/name` token，并为每一种前端注入渲染后的 `<skill_content>`，因此菜单 pick、手动键入的 token 与 TUI/ACP 提示词都以同一种方式加载 skill。与宿主命令同名的名称仍解析为命令：裁决在客户端把该行认领走，它根本不会成为提示词——这是有意的优先级，与同行产品一致。列表 RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务；草稿 chip 视觉由 `lexicon` 扫描派生。
+pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文本（决策 21）——本 source 不实现任何裁决钩子，也没有引用 codec（旧的 `<skill>name</skill>` 形式已随移除裁定消失）。确定性在宿主侧：pre-step 手势边界（`dsh-tool-skill`）识别用户消息中任意位置、以空白为界、指名用户可调用 skill 的 `/name` token，并为每一种前端注入渲染后的 `<skill_content>`，因此菜单 pick、手动键入的 token 与 TUI/ACP（Agent Client Protocol）提示词都以同一种方式加载 skill。与宿主命令同名的名称仍解析为命令：裁决在客户端把该行认领走，它根本不会成为提示词——这是有意的优先级，与同行产品一致。列表 RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务；草稿 chip 视觉由 `lexicon` 扫描派生。
 
 `skill.list` 失败时 `candidates` 抛出异常，slash 壳层记录日志并折叠为静默的菜单组丢弃——菜单只显示 pending／ready 状态。
 
@@ -32,6 +32,6 @@ pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文
 
 ## 已知限制与暂缓事项
 
-- **仅含结果的 history 页使用通用行**：键控分派要求配对调用位于 runtime 窗口内；分页将调用留在窗口外时，结果没有工具身份。这项客户端呈现功能不会为了恢复该身份而扩展 history 协议契约。
+- **仅含结果的 history 页使用通用行**：键控分派要求配对调用位于运行时窗口内；分页将调用留在窗口外时，结果没有工具身份。这项客户端呈现功能不会为了恢复该身份而扩展 history 协议约定。
 - **文本是唯一依据**：引用是普通的草稿文本；手动键入的相同 token 就是同一个引用，宿主手势边界评判的是发出的文本，而不是菜单交互。chip 视觉由 lexicon 扫描派生；没有 occurrence 身份、位置跟踪，也没有提示词协议上的结构化引用载荷（两者都是台账事项）。
 - **预热落定之前打开的菜单**：在那次击键下不显示 skill 候选；下一次击键会重新轮询已落定的缓存。
diff --git a/packages/client/ui-slots/README.i18n.yaml b/packages/client/ui-slots/README.i18n.yaml
index dd103f395a..7b67f66d3b 100644
--- a/packages/client/ui-slots/README.i18n.yaml
+++ b/packages/client/ui-slots/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-slots/README.md
 README.md: bb489dea0c3848cf3d501dcf095a65fe1cef9ef6
-README.zh.md: b4a2915b9d85c45ef7c6dccf27761794e21aa65f
+README.zh.md: 91e4f817c414e11645aa4d3a1b9bcf94f9678805
diff --git a/packages/client/ui-slots/README.zh.md b/packages/client/ui-slots/README.zh.md
index b4a2915b9d..91e4f817c4 100644
--- a/packages/client/ui-slots/README.zh.md
+++ b/packages/client/ui-slots/README.zh.md
@@ -19,7 +19,7 @@ chain-kind slot 会反转键控路由：条目自行提名，而不是由分发
 
 store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 契约。引擎产物与 renderer host 契约携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制这一侧的 seam，只有 props 契约 hook 类型（`SnapshotSelectorHook`）位于这里。
 
-`SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与折叠时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装 seam（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
+`SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与移除时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装 seam（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
 
 ## 模型体验
 
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index eb915bff8d..6ca3d905b4 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-theme/README.md
 README.md: 648213b258169b2e8869a93d058fcc65aece175e
-README.zh.md: b807ebd66253c91dc8b79f01ac4d3b2335682001
+README.zh.md: 02481badc816e0eb42c0d2496c9a096d2dbdbccb
diff --git a/packages/client/ui-theme/README.zh.md b/packages/client/ui-theme/README.zh.md
index b807ebd662..02481badc8 100644
--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -6,7 +6,7 @@
 
 `src/styles/` 下有五张样式表，全部由 web 壳的 `base.css` 导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
 
-滚动条重新绑定契约：`scrollbar.css` 在 `body` 上把 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover` 绑定到 l1（基础表面）token，两条渲染路径都读取这一组变量。高层级表面（菜单、浮层、对话框）在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`；一次重新绑定即可为引擎实际走的那条路径换色。这组变量另一个合法的目标是 `transparent`，即完全不绘制滑块——[ui-sidebar](../ui-sidebar/README.md) 在指针不在栏内时就这样重新绑定自己的列。绑回 l1 那组不算重新绑定，它只是重述基础表面的默认值。
+滚动条重新绑定约定：`scrollbar.css` 在 `body` 上把 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover` 绑定到 l1（基础表面）token，两条渲染路径都读取这一组变量。高层级表面（菜单、浮层、对话框）在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`；一次重新绑定即可为引擎实际走的那条路径换色。这组变量的另一个合法目标是 `transparent`，即完全不绘制滑块——[ui-sidebar](../ui-sidebar/README.md) 在指针不在栏内时就这样重新绑定自己的列。绑回 l1 那组不算重新绑定，它只是重述基础表面的默认值。
 
 两条路径在构造上互斥。`scrollbar-width`／`scrollbar-color` 写在 `@supports not selector(::-webkit-scrollbar)` 之内，因为这两个属性中的任一个只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中——若无条件地同时声明，`--dsh-scrollbar-thumb-hover` 在任何引擎上都不会被渲染。因此 Firefox 走标准属性，WebKit 系引擎走伪元素，hover token 只经由伪元素这条路径渲染。推理过程与实测计算值见[滚动条 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)。
 
@@ -21,4 +21,4 @@
 ## 已知限制与暂缓事项
 
 - **第三方主题是表层，不是产品**：注册主题意味着覆盖同名别名变量；目前不会验证一组覆盖是否完整。
-- **token 样式表是颜色值的唯一权威来源**：会有意不补入 cssdesign 中缺失的值（例如设计中的 #4176E6 标签页蓝色）；一律采用最接近的语义 token（裁定于 2026-07-22）。设计负责人批准的新增值是例外：须在同一变更中以一个 static 梯度值加一个语义 alias 的形式进入（`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`，2026-08-07）。
+- **token 样式表是颜色值的唯一权威来源**：会有意不补入 cssdesign 中缺失的值（例如设计中的 #4176E6 标签页蓝色）；一律采用最接近的语义 token（裁定于 2026-07-22）。设计负责人批准的新增值是例外：须在同一变更中以一个静态尺度层级与一个语义别名的形式进入（`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`，2026-08-07）。
diff --git a/packages/client/web/README.i18n.yaml b/packages/client/web/README.i18n.yaml
index 9b652b3110..cf0e86691f 100644
--- a/packages/client/web/README.i18n.yaml
+++ b/packages/client/web/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/web/README.md
 README.md: 74c481d573fb716e624e639c74b35c82e6894f63
-README.zh.md: 08c69665a00377ff4bb11eee90031a45b3901753
+README.zh.md: 0e36107e50b2e22d65c126a4fd8873a89b0bb687
diff --git a/packages/client/web/README.zh.md b/packages/client/web/README.zh.md
index 08c69665a0..0e36107e50 100644
--- a/packages/client/web/README.zh.md
+++ b/packages/client/web/README.zh.md
@@ -23,4 +23,4 @@ Web 外壳内核：`new AppWebEntry(el, seams?).run()` 通过两阶段启动（w
 ## 已知限制与暂缓事项
 
 - **有意采用一次性渲染**：UI 等待启动 settle；只要一个配置项失败，加载页面就会保留并逐项显示醒目的报告，不提供部分可用性（渐进式渲染将作为独立项目恢复）。
-- **窄窗口外壳行为缺少组装后演练**：ui-layout 已实现让步链，但该包没有外壳级窄 viewport 验收用例。
+- **窄窗口外壳行为缺少组装后演练**：ui-layout 已实现让步链，但该包没有外壳级窄视口验收用例。
diff --git a/packages/code-runtime/code-runtime-worker/README.i18n.yaml b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
index 8d3568e82e..adddfd119a 100644
--- a/packages/code-runtime/code-runtime-worker/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-worker/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-worker/README.md
 README.md: 590b79dcd1bc322350060b55767b09c6305edacc
-README.zh.md: 12c25f892bd20892cb47e593f16b6aadd9ffa84c
+README.zh.md: e45aa484c0935d5b4b1626f5c4c7c72482cd5b5d
diff --git a/packages/code-runtime/code-runtime-worker/README.zh.md b/packages/code-runtime/code-runtime-worker/README.zh.md
index 12c25f892b..e45aa484c0 100644
--- a/packages/code-runtime/code-runtime-worker/README.zh.md
+++ b/packages/code-runtime/code-runtime-worker/README.zh.md
@@ -32,7 +32,7 @@
 
 ## 未构建与已构建的 worker 入口
 
-源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地和会话自有的 JSON 边界都会在消息端口周围展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的虚拟文件系统（VFS）Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。演练这个已发布入口路径的仓库级要求由[测试策略](../../../docs/testing.md)规定。
+源代码模式通过 Node 原生类型剥离加载只包含可擦除语法的 `src/worker.ts`。其传递运行时闭包只包含 Node 内置模块和相对源模块，因此全新 checkout 绝不需要兄弟工作区包尚未构建的 `lib/` 导出。worker 本地和会话自有的 JSON 边界都会在消息端口两侧展平并重建已验证值，使应用嵌套永远不会进入 structured clone。构建模式会把兄弟文件 `lib/worker.cjs` 作为文件系统路径传入，因为 pkg 的虚拟文件系统（VFS）Worker hook 要求 CommonJS；同一路径也可在普通 Node 下使用。对这个已发布入口路径进行测试的仓库级要求由[测试策略](../../../docs/testing.md)规定。
 
 SDK 对外提供默认及具名导出的 `WorkerCodeRuntime` 类，以及 `Config`。运行所用的 `./worker` 子路径仅作为打包后的 spawn 入口存在；wire 协议与启动辅助模块是源代码私有的实现细节。
 
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index a6bd209c7b..3f2ea68116 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime/README.md
 README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
-README.zh.md: 15fbcecf77b2318acf3b09101802cd032ae426d2
+README.zh.md: fff62b97b8ef76901e4680fb6c6c8ff4820ba35d
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index 15fbcecf77..fff62b97b8 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -20,7 +20,7 @@
 
 `CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
 
-binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的契约——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
+binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的约定——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
 
 ## 模型体验
 
diff --git a/packages/context/time-context/README.i18n.yaml b/packages/context/time-context/README.i18n.yaml
index 3ddda9bc7b..8e67848c71 100644
--- a/packages/context/time-context/README.i18n.yaml
+++ b/packages/context/time-context/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/context/time-context/README.md
 README.md: 9956918c63b49de8ec5e739bc3d9887e269930a8
-README.zh.md: fd338cc192c2168915017dd22ac6a1631d8cc21b
+README.zh.md: 3a9bb1012fc0639d9c3f6b104cea5a64d4b187d6
diff --git a/packages/context/time-context/README.zh.md b/packages/context/time-context/README.zh.md
index fd338cc192..3a9bb1012f 100644
--- a/packages/context/time-context/README.zh.md
+++ b/packages/context/time-context/README.zh.md
@@ -16,17 +16,17 @@
 
 省略 `timeZone` 时，插件会在加载时解析一次 Node 进程的系统时区。Node 遵循 `TZ`；如果没有该覆盖，时区由宿主或容器提供。显式 `timeZone` 必须是 IANA 标识符，并在插件加载时验证。
 
-`refreshIntervalMs` 必须是非负安全整数。省略或设为 `0` 时，会为每次信号尚未中止且返回 enter 的合格 pre-step 添加上下文。正数值只会在会话没有早先 time-context 注入、挂钟时间倒退，或自最新注入起已经过至少相应毫秒数时添加上下文。
+`refreshIntervalMs` 必须是非负安全整数。省略或设为 `0` 时，会为每次信号尚未中止且会进入步骤的合格步骤前处理添加上下文。正数值只会在会话没有早先 time-context 注入、挂钟时间倒退，或自最新注入起已经过至少相应毫秒数时添加上下文。
 
 ## 时序语义
 
-该插件会前置一个 `agent/pre-step` 监听器。需要注入且下游决策进入拟议步骤时，它会在返回批次中添加一条带来源的 `UserMessage`。AgentLoop 会在 `step/start` 之后、普通自动压缩（compaction）之前记录该上下文，其来源为 `{ kind: 'plugin', plugin: 'time-context' }`。被抑制、reject 或失败的 pre-step 不会记录任何内容。
+该插件会前置一个 `agent/pre-step` 监听器。需要注入且下游决策进入拟议步骤时，它会在返回批次中添加一条带来源的 `UserMessage`。AgentLoop 会在 `step/start` 之后、普通自动压缩（compaction）之前记录该上下文，其来源为 `{ kind: 'plugin', plugin: 'time-context' }`。被抑制、拒绝或失败的步骤前处理不会记录任何内容。
 
 正间隔调度会扫描原始持久会话事件，查找最新的上述源 `user/message`，包括已被压缩遮蔽的时间读数。因此，调度可以跨轮次以及进程恢复持续生效，不需要进程本地缓存状态。它会降低追加频率与历史增长，但绝不移除现有时间读数，且每个会话独立调度。
 
 第 1 步从前一条模型可见消息起测量，包括开启轮次的提示词。后续步骤从同一轮次中前一个 time-context 事件起测量。两种基线都使用持久会话事件时间戳；挂钟时间倒退时，经过时长限制为零。如果第一步缺少基线，或者后续步骤因间隔抑制而没有较早的同轮次时间读数，则报告 `unavailable`。
 
-时间读数记录的是一个已进入步骤的 pre-step 批次，不是已完成步骤或已传输请求。后续请求准备失败时，该读数可能已留在历史中；但下游 pre-step 监听器 reject 或失败时，该读数不会被记录。
+时间读数记录的是一个已进入步骤的步骤前批次，不是已完成步骤或已传输请求。后续请求准备失败时，该读数可能已留在历史中；但下游步骤前监听器拒绝或失败时，该读数不会被记录。
 
 单独发布的 `./invariant` 配套模块会根据当前未结束的轮次、下一个步骤前位置、经过时长基线与持久事件时间检查每个归因于插件的时间读数。其渲染时间戳必须可解析，且不能晚于该事件；采样与追加之间的进程挂起不会使时间读数失效。
 
diff --git a/packages/context/tmux-context/README.i18n.yaml b/packages/context/tmux-context/README.i18n.yaml
index c0446d8dfe..0e3f1898ad 100644
--- a/packages/context/tmux-context/README.i18n.yaml
+++ b/packages/context/tmux-context/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/context/tmux-context/README.md
 README.md: 26eff205b399bfcd20f55e91ef46cadbd70ae604
-README.zh.md: 6950443ce7ce9c46a605ef70500dd4f63c44163b
+README.zh.md: 7f256a829860df3f39e913d003b4e53d09243365
diff --git a/packages/context/tmux-context/README.zh.md b/packages/context/tmux-context/README.zh.md
index 6950443ce7..7f256a8298 100644
--- a/packages/context/tmux-context/README.zh.md
+++ b/packages/context/tmux-context/README.zh.md
@@ -33,7 +33,7 @@ exec tmux display-message -t "$TMUX_PANE" -p '<format>'
 
 ## 时序语义
 
-该插件会前置一个 `agent/pre-step` 监听器。需要注入且下游决策进入拟议步骤时，它会在返回批次前添加一条带来源的 `UserMessage`。AgentLoop 会在 `step/start` 之后记录该上下文，其来源为 `{ kind: 'plugin', plugin: 'tmux-context' }`。变化抑制与间隔调度会扫描原始持久会话事件中该来源的最近一次注入，因此调度可跨压缩与恢复的进程存续，无需进程内缓存状态；各会话独立调度。下游 pre-step 监听器 reject 或失败时，该读数不会被记录。
+该插件会前置一个 `agent/pre-step` 监听器。需要注入且下游决策进入拟议步骤时，它会向返回的批次前置添加一条带来源的 `UserMessage`。AgentLoop 会在 `step/start` 之后记录该上下文，其来源为 `{ kind: 'plugin', plugin: 'tmux-context' }`。变化抑制与间隔调度会扫描原始持久会话事件中该来源的最近一次注入，因此调度可跨压缩与恢复的进程存续，无需进程内缓存状态；各会话独立调度。下游 pre-step 监听器拒绝或失败时，该读数不会被记录。
 
 ## 模型体验
 
diff --git a/packages/context/workspace-context/README.i18n.yaml b/packages/context/workspace-context/README.i18n.yaml
index 08b1d7a675..3cf32ff662 100644
--- a/packages/context/workspace-context/README.i18n.yaml
+++ b/packages/context/workspace-context/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/context/workspace-context/README.md
 README.md: 7ab21bbf8c72f8424bc8d4fdad9153c7ed8bb7e9
-README.zh.md: 7ad68759ab811cdc5e848fd686c7fad612c9b6d9
+README.zh.md: eb807bfc0611854d54eda3ff26c97c6af51da529
diff --git a/packages/context/workspace-context/README.zh.md b/packages/context/workspace-context/README.zh.md
index 7ad68759ab..eb807bfc06 100644
--- a/packages/context/workspace-context/README.zh.md
+++ b/packages/context/workspace-context/README.zh.md
@@ -6,9 +6,9 @@
 
 ## 生命周期
 
-每个实时会话第一次符合条件的 `agent/pre-step` 会组合基线。当下游决策让非空的第一步批次进入时，插件会将基线折入最终批次、紧随已领取的直接提示词之后，使直接提示词与持久基线一同进入步骤 1，并共同抵达第一次请求。reject 或空的第一步决策会将基线留在 agent 的 `next-step` inbox，等待后续唤醒。loader 先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。若之前排队的 workspace 上下文仍在等待，插件会删除并替换该确切 inbox 条目，而不会不断累积副本。恢复后的会话会保留一条兼容的可见基线，并只追加当前文件的转换；如果发现、优先级、项目根目录或预算标识发生变化，则会将一条明确取代旧基线的完整基线折入进入步骤的批次。
+每个实时会话第一次符合条件的 `agent/pre-step` 会组合基线。当下游决策让非空的第一步批次进入时，插件会将基线折入最终批次、紧随已领取的直接提示词之后，使直接提示词与持久基线一同进入步骤 1，并共同抵达第一次请求。被拒绝或为空的第一步决策会将基线留在 agent（智能体）的 `next-step` inbox，等待后续唤醒。loader 先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。若之前排队的 workspace 上下文仍在等待，插件会删除并替换该确切 inbox 条目，而不会不断累积副本。恢复后的会话会保留一条兼容的可见基线，并只追加当前文件的转换；如果发现、优先级、项目根目录或预算标识发生变化，则会将一条明确取代旧基线的完整基线折入进入步骤的批次。
 
-该插件还会观察第一方 `read`、`write` 和 `edit` 调用成功后产生的不可变 `tools/result`。每个已接受的 touch 都会检查新达到的后代 scope 以及之前加载的每个 scope。每个已配置候选名称都是所在目录中的独立 scope：新出现的文件会在 agent inbox 中排入一项新增；已改变文件会排入一项替换；文件消失或成为同一目录中较早候选文件的重复项时，会排入一则移除通知。原生调用与 Code Mode 子分派共享该路径：嵌套 touch 会沿不透明的父级执行 token 逐层上浮，直到顶层结果落定；在 agent loop 步骤内产生的 touch，须等持久 `step/end` 后才开始异步投影。打开的步骤之外直接执行工具时，则立即投影。这样无需依赖文件系统时序，也能保持工具调用／结果／步骤的相邻关系。这种发现跟随结构化文件系统活动，而不是 shell `cd`，因为每次本地 bash 调用都启动新 shell，解析任意 shell 语法也不可靠。
+该插件还会观察第一方 `read`、`write` 和 `edit` 调用成功后产生的不可变 `tools/result`。每个已接受的 touch 都会检查新达到的后代 scope 以及之前加载的每个 scope。每个已配置候选名称都是所在目录中的独立 scope：新出现的文件会在 agent inbox 中排入一项新增；已改变文件会排入一项替换；文件消失或成为同一目录中较早候选文件的重复项时，会排入一则移除通知。原生调用与 Code Mode 子分派共享该路径：嵌套 touch 会沿不透明的父级执行 token 逐层上浮，直到顶层结果落定；在 agent loop（智能体循环）步骤内产生的 touch，须等持久 `step/end` 后才开始异步投影。打开的步骤之外直接执行工具时，则立即投影。这样无需依赖文件系统时序，也能保持工具调用／结果／步骤的相邻关系。这种发现跟随结构化文件系统活动，而不是 shell `cd`，因为每次本地 bash 调用都启动新 shell，解析任意 shell 语法也不可靠。
 
 指令读取使用可选 `ctx.fs` 提供方。该插件不会静态注入 `fs`，因此没有提供方的产品树仍可启动，指令加载在提供方出现前不执行任何操作。它会解析每个候选文件并对解析结果执行 stat，因此会跟随路径最后一段的 symlink 到其目标：指向常规文件的链接会加载目标内容，缺失路径或非文件目标（包括指向目录的链接）则已确认不存在。resolve 或 stat 异常会改为将该候选文件的 scope 标记为暂时不可用。前缀取消与动态工具取消会传播到解析、元数据探测与流式读取。文件加载后的提供方失败会视为暂时不可用，而非文件已删除的证据。
 
@@ -48,7 +48,7 @@ These instructions apply to work under `packages/app`. Use them as guidance when
 
 ## 状态与刷新
 
-模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整基线还会携带 `baseline: true`，以及从规范化的发现、优先级、项目根目录和预算配置派生的 `baselineIdentity`。匹配的持久 `user/message` 会确认已排队基线及其候选版本。进入步骤的 pre-step 会等待所有已排队投影完成，再把新组合的上下文折入最终批次，位置紧随已领取的消息，并移除 inbox 中仍待处理的副本；reject 则让当前上下文继续排队。若监听器改写掉已领取的 workspace 消息，又没有让替代消息进入，后续边界会重新组合当前上下文。即使后续复合结果被拦截，成功的嵌套文件 touch 也会聚合到父级执行 token 下；顶层结果会将这些 touch 交给当前打开的会话步骤，或直接交给逐 agent 投影队列。`step/end` 只会在自身边界进入持久历史后释放其暂存的 touch；串行投影会根据可见会话事件和当前 inbox 协调状态，再替换唯一一条待处理工作区上下文。
+模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整基线还会携带 `baseline: true`，以及从规范化的发现、优先级、项目根目录和预算配置派生的 `baselineIdentity`。匹配的持久 `user/message` 会确认已排队基线及其候选版本。进入步骤的 pre-step 会等待所有已排队投影完成，再把新组合的上下文折入最终批次，位置紧随已领取的消息，并移除 inbox 中仍待处理的副本；若被拒绝，当前上下文则继续排队。若监听器改写掉已领取的 workspace 消息，又没有让替代消息进入，后续边界会重新组合当前上下文。即使后续复合结果被拦截，成功的嵌套文件 touch 也会聚合到父级执行 token 下；顶层结果会将这些 touch 交给当前打开的会话步骤，或直接交给逐 agent 投影队列。`step/end` 只会在自身边界进入持久历史后释放其暂存的 touch；串行投影会根据可见会话事件和当前 inbox 协调状态，再替换唯一一条待处理工作区上下文。
 
 路径与 SHA-1 内容 digest 都未变时，不会重复注入。每会话、每 scope 提供方 cache 只存储 `{ path, version, digest, trimmedDigest }`：当提供方的不透明 `FsVersion` 与有效可见状态都匹配时，对账会跳过内容读取；版本改变会在任何模型可见更新之前触发有界读取与 SHA-1 确认。`trimmedDigest` 是针对去除空白后内容的 SHA-1，也是每目录重复 key，因此较早候选文件与某个未更改文件的内容收敛后，后者仍可被移除。恢复可行，因为 SHA-1 状态持久化在带类型的来源中，而空的内存版本 cache 只会导致一次确认读取。压缩（compaction）会在 scope 的上下文事件离开可见表层后重新启用它，即使缓存版本未变。移除是 tombstone，因此候选文件之后重新出现时会重新加载。只有在字节预算内实际渲染的模型可见变更才会进入来源、pending 状态和版本 cache；已省略变更仍可在后续 touch 处理，而相同 digest 的版本刷新只更新提供方 cache。
 
diff --git a/packages/examples/README.i18n.yaml b/packages/examples/README.i18n.yaml
index 506e867ef5..e77a9283b2 100644
--- a/packages/examples/README.i18n.yaml
+++ b/packages/examples/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/examples/README.md
 README.md: 2d672dcc307bb280cf3803f29128eba4988a8da0
-README.zh.md: e827e7cff4ff9d6521e5889e48270e06641ef38c
+README.zh.md: 24f64096dda0ccdac51afb90754ae25950750b89
diff --git a/packages/examples/README.zh.md b/packages/examples/README.zh.md
index e827e7cff4..24f64096dd 100644
--- a/packages/examples/README.zh.md
+++ b/packages/examples/README.zh.md
@@ -6,12 +6,12 @@
 
 | 包 | npm 名称 | 角色 |
 |---|---|---|
-| [`agent-spine-demo/`](agent-spine-demo/README.md) | `@deepseek-ai/dsh-agent-spine-demo` | 可复用的 agent 主干组合包 |
-| [`acp-demo/`](acp-demo/README.md) | `@deepseek-ai/dsh-acp-demo` | ACP 自动化应用组合包 |
+| [`agent-spine-demo/`](agent-spine-demo/README.md) | `@deepseek-ai/dsh-agent-spine-demo` | 可复用的 agent（智能体）主干组合包 |
+| [`acp-demo/`](acp-demo/README.md) | `@deepseek-ai/dsh-acp-demo` | ACP（Agent Client Protocol）自动化应用组合包 |
 | [`jsonrpc-demo/`](jsonrpc-demo/README.md) | `@deepseek-ai/dsh-jsonrpc-demo` | 外部配置 JSON-RPC 运行时 |
 
-`agent-spine-demo` 是共享组合包；`acp-demo` 添加自动化入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。产品单次执行归 `dsh run` 所有；本目录没有任何包提供该功能。
+`agent-spine-demo` 是共享组合包；`acp-demo` 添加自动化入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。产品单次执行由 `dsh run` 提供；本目录没有任何包提供该功能。
 
-这些包不是产品 API。产品 seam 与前端入口仍位于各自的归属组；演示组合包只选择具体组合。
+这些包不是产品 API。产品 seam 与前端入口仍位于各自的归属组；演示组合包选择具体组合。
 
 不要将此组与仓库根目录的 [`examples/`](../../examples/AGENTS.md) 混淆：该目录存放可运行的 `cordis.yml` **叶节点**；此组存放这些叶节点加载的 **组合包**。
diff --git a/packages/examples/agent-spine-demo/README.i18n.yaml b/packages/examples/agent-spine-demo/README.i18n.yaml
index 3398b7296d..43cdef4af8 100644
--- a/packages/examples/agent-spine-demo/README.i18n.yaml
+++ b/packages/examples/agent-spine-demo/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/examples/agent-spine-demo/README.md
 README.md: d1c3c28183956b4f66db7ed4a6f3a08588b5352c
-README.zh.md: 936a317d23bf942802ecdd87f5ea4005974e4125
+README.zh.md: cf372a428c16893b1d328ea60ad70c09d6d9725c
diff --git a/packages/examples/agent-spine-demo/README.zh.md b/packages/examples/agent-spine-demo/README.zh.md
index 936a317d23..cf372a428c 100644
--- a/packages/examples/agent-spine-demo/README.zh.md
+++ b/packages/examples/agent-spine-demo/README.zh.md
@@ -59,7 +59,7 @@ import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
 // workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
 ```
 
-组合包将每个字段转发给拥有它的子节点。应用包提供预创建的 agent：无头和 JSON-RPC 组合会创建 `main`，ACP 应用则在 `session/new` 按需创建 agent。提示词、工具、标题、skill、workspace context、不变式、goal 和任务设置沿用其所属包记录的 schema 与默认值。`pickSpineConfig()` 只复制该组合包拥有的字段，`dshHome` 值冲突会在组合时失败。
+组合包将每个字段转发给拥有它的子节点。应用包提供预创建的 agent：无头和 JSON-RPC 组合会创建 `main`，ACP 应用则在 `session/new` 按需创建 agent。提示词、工具、标题、skill、工作区上下文、不变式、目标和任务设置沿用其所属包记录的 schema 与默认值。`pickSpineConfig()` 只复制该组合包拥有的字段，`dshHome` 值冲突会在组合时失败。
 
 例如，`{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/dsh-'], package_blocklist: ['agent-loop$'] } }` 会让包拥有的配套插件保持挂载，但抑制被阻止的拥有者。Blocklist 匹配优先于 allowlist 匹配；正则表达式与生命周期规则见 [`dsh-invariants`](../../support/invariants/README.md)。
 
diff --git a/packages/goal/goal-session/README.i18n.yaml b/packages/goal/goal-session/README.i18n.yaml
index 0c44b4b476..686f8aaa3f 100644
--- a/packages/goal/goal-session/README.i18n.yaml
+++ b/packages/goal/goal-session/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/goal-session/README.md
 README.md: 89413062de8cbb49d7066ec3ae42769a99c939a2
-README.zh.md: 45f61f2ea02b4a8112a88a3425ef3893128b3098
+README.zh.md: 075592e4e77e3336c1e2c08769ee255569e53360
diff --git a/packages/goal/goal-session/README.zh.md b/packages/goal/goal-session/README.zh.md
index 45f61f2ea0..075592e4e7 100644
--- a/packages/goal/goal-session/README.zh.md
+++ b/packages/goal/goal-session/README.zh.md
@@ -23,7 +23,7 @@
 
 当对应的活跃 agent 实例处于 idle 状态，且目标 phase 为 active、已启用续行并有剩余容量时，驱动器先为待处理 goal 变更创建检查点，再预留 `roundsStarted + 1`，对应当前 `{ goalId, revision }`。它会排入一条 `<goal_round>` 提示词，并携带 `GoalMessageSource`。`agent/pre-step` 监听器会在下游监听器前后验证完整的已领取记录与当前 goal；只有进入步骤的 `user/message` 才会增加 `roundsStarted`。因陈旧而被拒绝的预留不会消耗 Round 编号。
 
-`MessageId` 通过持久 inbox 插入和领取来标识预留消息；它不标识轮次结果。用户消息不消耗 goal 上限。如果用户工作在预留前进入 inbox，或加入预留的待处理批次，自动工作会让行，直到 agent 进入 idle；混合批次中的待处理自动提示词会被拒绝，只有完成该检查点后才重新预留。
+`MessageId` 通过持久 inbox 插入和领取来标识预留消息；它不标识轮次结果。用户消息不消耗 goal 上限。如果用户工作在预留前进入 inbox，或加入预留的待处理批次，自动工作会让行，直到 agent 进入 idle；混合批次中的待处理自动提示词会被拒绝，只有在该检查点之后才重新预留。
 
 保留的提示词会点明经过 JSON 引用的目标与 `round/maxGoalRounds`，将当前工作区、工具结果和持久会话状态视为权威信息，要求在完成前提供证据，并要求在工作仍未完成时保持目标 active。引用可将多行或形似标签的目标文本保留为数据。goal 生命周期变更仍必须通过 `dsh-tool-goal` 的独立权限检查。
 
diff --git a/packages/hooks/README.i18n.yaml b/packages/hooks/README.i18n.yaml
index 6000d1396f..3aff382ea6 100644
--- a/packages/hooks/README.i18n.yaml
+++ b/packages/hooks/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/hooks/README.md
 README.md: 35989292313c6cef47c02041eb671a73ff7c5786
-README.zh.md: b5187fed159b0eaf5b2bace192152e612a85bc55
+README.zh.md: 3d169d1286f38658d98f4c5f8d016ef77e1b6517
diff --git a/packages/hooks/README.zh.md b/packages/hooks/README.zh.md
index b5187fed15..3d169d1286 100644
--- a/packages/hooks/README.zh.md
+++ b/packages/hooks/README.zh.md
@@ -10,4 +10,4 @@ hooks 子系统让用户像使用 Claude Code 和 Codex 一样，在生命周期
 | [`hooks-claude/`](hooks-claude/README.md) | Claude Code 钩子桥接 | 插件 |
 | [`hooks-codex/`](hooks-codex/README.md) | Codex 钩子桥接 | 插件 |
 
-共享库负责通用协议行为；各桥接负责自身方言的事件映射。子 README 记录这些契约。
+共享库负责通用协议行为；各桥接负责自身方言的事件映射。子 README 记录这些约定。
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index dda161c2d7..ae64984c31 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/hooks/hook-protocol/README.md
 README.md: e807d9597eb5f811195bab9a0ad2b30b545e1205
-README.zh.md: f9990c046d4e52a2fa911776e92fcf397d159633
+README.zh.md: b77c8d658eddf7ce60faaf171e6f41e09b8ef333
diff --git a/packages/hooks/hook-protocol/README.zh.md b/packages/hooks/hook-protocol/README.zh.md
index f9990c046d..b77c8d658e 100644
--- a/packages/hooks/hook-protocol/README.zh.md
+++ b/packages/hooks/hook-protocol/README.zh.md
@@ -19,7 +19,7 @@ Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它
 
 ## 原语
 
-- **`matcherDiagnostic(matcher, mode)` / `matchesMatcher(matcher, query, mode)`**：缺失、`''` 或 `'*'` 时匹配全部；`claude` mode 将纯 `[A-Za-z0-9_|]+` pattern 视为字面量（管道符 = 精确匹配多选），其他 pattern 视为正则；`codex` mode 始终使用未锚定正则。桥接解析器会丢弃没有 matcher 匹配对象的事件所带字段，再用 `matcherDiagnostic` 拒绝事件实际使用的无效正则，并在注册任何钩子之前给出稳定诊断。运行时谓词仍会将无效 pattern 隔离为不匹配，因此直接调用本库不会向 agent loop（智能体循环）抛异常。
+- **`matcherDiagnostic(matcher, mode)` / `matchesMatcher(matcher, query, mode)`**：缺失、`''` 或 `'*'` 时匹配全部；`claude` mode 将纯 `[A-Za-z0-9_|]+` pattern 视为字面量（管道符 = 精确匹配交替），其他 pattern 视为正则；`codex` mode 始终使用未锚定正则。桥接解析器会丢弃没有 matcher 匹配对象的事件所带的 matcher 字段，再用 `matcherDiagnostic` 拒绝事件实际使用的无效正则，并在注册任何钩子之前给出稳定诊断。运行时谓词仍会将无效 pattern 隔离为不匹配，因此直接调用本库不会向 agent loop（智能体循环）抛异常。
 - **`runHook(bash, hook, options, now)`**：要求并转发调用方拥有的 `options.signal`，将 `options.payload` 序列化到 hook stdin（当且仅当 `options.trailingNewline` 时添加尾随换行符），在执行器凭证清理后合并 `options.env`（`dsh-bash` 受信任插件接口），遵循 hook 的 `timeoutSec`（否则使用 `options.defaultTimeoutMs`；默认值属于桥接，其配置默认为 lib 的 `DEFAULT_HOOK_TIMEOUT_MS` 10 分钟参考值），再解码结果（将 `options.expectedEventName` 传递给 codec）。因此取消会到达执行器的进程组终止与 join 边界。它绝不抛出异常：执行器拒绝（基础设施故障）会变为 `HookOutput`，其 `exitCode: undefined`（非阻塞错误）。`now` 会被注入，以便测试持续时间。
 - **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** 解码退出状态与结构化 stdout。退出码为 2 时，会以 stderr 内容阻止执行；其他失败不阻塞。匹配的 hook 特定权限决策会覆盖遗留顶层决策；事件判别字段不匹配或缺失只会抑制事件特定字段。顶层字段仍与事件无关，成功但非 JSON 的输出会留给桥接处理。
 - **`mergeHookOutputs(outputs)`**：折叠在一个点上匹配的每个 hook 结果：权限优先级为 **deny > ask > allow**，从首个 `continue:false` 起，halt 状态保持不变，阻塞原因用 `\n\n` 连接，`additionalContext`／`systemMessages` 按顺序累积。
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 627f624235..1f02adea1d 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
 README.md: a3c9f214690144ec0f39a8690e4fd346f5e315e2
-README.zh.md: aeaf1b29e5a71674c9feedb30b67f9ce11c47340
+README.zh.md: 4de15316fe31d75361fd3b8655c7c1f7d5fa4a02
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index aeaf1b29e5..4de15316fe 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, reasoningEffort?, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml)。
+所有客户端形态共用的 API 网关：TS 约定（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, reasoningEffort?, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml)。
 
 ## 默认路由（`api-gateway` 设置段）
 
@@ -10,9 +10,9 @@
 
 会话按三级解析自己的路由，且每次读取都重新解析，而不是只在创建时种一次：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是这个默认值。重新解析正是让两个方向都成立的原因——已经跑过一轮的会话此后永远从自己的日志推导路由，改默认值不会重定向它；而仍然空白的会话（新建会话会复用一个，而不是再开一个）则会用上它创建之后才保存的默认值。
 
-`session.selectModel` 会把被接受的切换记录为新的默认值，实践中默认值就是这样选定的，没有另一个单独的手势。它存下来的是**解析后**的目标，因此适配器实体化出来的默认推理等级会按用户当时看到的样子钉住，日后适配器改了自己的默认值也不会悄悄移动已存的默认路由。写入是整段替换而非合并，因为切到一个不支持推理的模型必须清掉已存的等级；存储失败只记日志，不会撤销这次切换——它对自己所在的会话已经生效。没有设置提供方的部署保留组合条目，切换只停留在进程内。
+`session.selectModel` 会把被接受的切换记录为新的默认值，实践中默认值就是这样选定的，没有另一个单独的手势。它存下来的是**解析后**的目标，因此适配器实体化出来的默认推理等级会按用户当时看到的样子钉住，日后适配器改了自己的默认值也不会悄悄移动已存的默认路由。写入是整段替换而非合并，因为切到一个不带推理等级的模型必须清掉已存的等级；存储失败只记日志，不会撤销这次切换——它对自己所在的会话已经生效。没有设置提供方的部署保留组合条目，切换只停留在进程内。
 
-设置段里的 `reasoningEffort` 在插件配置中刻意没有对应字段：seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键，因此组合层设的推理等级会在此后每一次切到不支持推理的模型时继续存活。推理等级的部署级默认值属于适配器 profile，那里是按模型解析的。
+设置段里的 `reasoningEffort` 在插件配置中刻意没有对应字段：seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键，因此组合层设的推理等级会在此后每一次切到不带推理等级的模型时继续存活。推理等级的部署级默认值属于适配器 profile，那里是按模型解析的。
 
 存下来的路由不做注册表校验，两个方向都不做。默认值指向一个已在模型页删除的路由时，它照样作为会话的 `current` 送到 `session.models`——匹配不到任何已公布的分组，而这恰恰是让选择器提示重新选择、而不是显示一个部署根本够不着的模型的原因。静默修复它还会破坏刻意保留的反面情形：适配器可以服务一个自己目录未公布的模型。
 
@@ -24,7 +24,7 @@
 
 首个回答认领待处理请求之前，系统会对照该请求校验问题响应。多选题的回答项可以同时携带 `selected` 中的请求选项标签与非空 `custom` 文本；单选题的回答项必须二选一。标签重复、标签未知、id 不匹配、批次不完整以及自定义文本为空都会以 `bad-response` 拒绝。
 
-`session.history` 按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
+`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent（智能体），然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
@@ -32,9 +32,9 @@
 
 `session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的提供方／模型／推理（reasoning）目标及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。
 
-会话模型路由属于会话领域契约。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。`session.models` 还会报告 `routable`：当前目标的路由是否有适配器在服务。这一点刻意不由分组推导——一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用；而适配器已经消失的路由什么都服务不了。`session.prompt` 依据同一个事实以 `model-unavailable` 拒绝，而不是把整条 pre-step 路径走完再在适配器内部失败；客户端禁用输入框只是提示性设计，这个方法始终可被调用。
+会话模型路由属于会话领域约定。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。`session.models` 还会报告 `routable`：当前目标的路由是否有适配器在服务。这一点刻意不由分组推导——一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用；而适配器已经消失的路由什么都服务不了。`session.prompt` 依据同一个事实以 `model-unavailable` 拒绝，而不是把整条 pre-step 路径走完再在适配器内部失败；客户端禁用输入框只是提示性设计，这个方法始终可被调用。
 
-待处理的 queued 输入属于实时控制平面契约，而非对话历史。网关根据持久 `agent/inbox/spliced` 变更派生完整的 `next-turn` 队列，并在每次变更后及重连时广播权威 `session/queue` 快照；待处理的 `next-step` steering（中途引导）不进入此 Web 投影。在 `next-step` 内，用户来源的消息携带 `steering` placement，而注入上下文（审批通知、任务完成、附加快照）携带 `context`，领取前不对外呈现。面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知仍供生命周期观察方使用，但不用于构建队列视图。`session.updateQueue` 通过 `MessageId` 寻址单个项；编辑和移除经已挂载 Agent 的 `Inbox.splice()` 修改队列。claim 的纯删除 splice 会在 pre-step 准入前赢得竞态，因此之后的操作返回 `queue-item-not-found`。`session.cancel` 仅中止活动轮次并保留待处理 inbox 工作；取消达到完全停稳且结束中的轮次完成 flush 后，AgentLoop 按 FIFO 顺序认领下一条可唤醒消息，浏览器绝不重发或提升它。队列操作绝不恢复冷会话，客户端也绝不根据轮次或状态事件推断某项已退出队列。
+待处理的 queued 输入属于实时控制平面约定，而非对话历史。网关根据持久 `agent/inbox/spliced` 变更派生完整的 `next-turn` 队列，并在每次变更后及重连时广播权威 `session/queue` 快照；待处理的 `next-step` steering（中途引导）不进入此 Web 投影。在 `next-step` 内，用户来源的消息携带 `steering` placement，而注入上下文（审批通知、任务完成、附加快照）携带 `context`，领取前不对外呈现。面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知仍供生命周期观察方使用，但不用于构建队列视图。`session.updateQueue` 通过 `MessageId` 寻址单个项；编辑和移除经已挂载 Agent 的 `Inbox.splice()` 修改队列。claim 的纯删除 splice 会在 pre-step 准入前赢得竞态，因此之后的操作返回 `queue-item-not-found`。`session.cancel` 仅中止活动轮次并保留待处理 inbox 工作；取消达到完全停稳且结束中的轮次完成 flush 后，AgentLoop 按 FIFO 顺序认领下一条可唤醒消息，浏览器绝不重发或提升它。队列操作绝不恢复冷会话，客户端也绝不根据轮次或状态事件推断某项已退出队列。
 
 Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.create({ name })` 会在配置根目录下创建显示标题唯一的目录，而 `workspace.create({ path })` 会接纳已有的规范目录，并允许由 basename 派生的标题重复。`workspace.delete` 只移除 Workspace 注册记录，`session.create` 接受可选的预分配 Session id，`host/workspace-changed`、`host/workspace-removed` 与 `host/session-added` 则以任意到达顺序携带已提交的增量。`workspace.archiveSession` 向注册表级全局归档集合添加一个会话，并应答完整的更新后集合；`workspace.list` 携带该集合作为重连基线，`host/archived-sessions-changed` 在每次持久变更后推送完整快照。归档只把会话从各分组视图中隐藏，不触碰其日志和 workspace 记账；既非实时也未持久化的会话以 `session-not-found` 失败。删除注册记录会保留目录和会话日志；相关 Session 仍留在 `session.list` 中，并进入 Ungrouped。`SessionSummary.blank` 与 `host/session-added` 帧携带派生的零事件位：客户端隐藏空白会话并按 workspace 复用它们，在首个 `host/session-status(running:true)` 时翻转 blank，并以 `session.list` 作为重连权威；冷会话摘要永远不是空白：惰性持久化让从未追加过事件的会话根本不出现在 `list()` 中。
 
@@ -46,9 +46,9 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 `host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，桌面 Linux 为 `xdg-open`）。对于 `.html`、`.htm`、`.xhtml` 与 `.svg`，macOS 和桌面 Linux 会优先使用能够确定的默认浏览器；无法确定时回退到上述应用交接。WSL 会通过 `wslpath -w` 转换每个 Linux 路径，并将所得 Windows/UNC 路径交给 Windows `Invoke-Item`，浏览器可渲染的文档也不例外，而非假定存在 Linux 桌面文件关联。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。
 
-`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于 composer 的菜单：它返回每一个用户可调用的 skill 及其 `modelInvocable` 标志，让菜单能够标出仅限用户（`disable-model-invocation`）的条目——斜杠手势是这类条目唯一的入口。列表是 skill 领域唯一的 RPC——调用本身就是一次普通的 `session.prompt`，`dsh-tool-skill` 会在 pre-step 边界识别其中以空白为界的 `/name` token，并以注入的 `<skill_content>` 上下文作答，因此每一种前端（web、TUI、ACP、手动键入的文本）共享同一条确定性路径，没有专设的调用协议。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
+`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和 skill（技能）目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于 composer 的菜单：它返回每一个用户可调用的 skill 及其 `modelInvocable` 标志，让菜单能够标出仅限用户（`disable-model-invocation`）的条目——斜杠手势是这类条目唯一的入口。列表是 skill 领域唯一的 RPC——调用本身就是一次普通的 `session.prompt`，`dsh-tool-skill` 会在 pre-step 边界识别其中以空白为界的 `/name` token，并以注入的 `<skill_content>` 上下文作答，因此每一种前端（web、TUI、ACP（Agent Client Protocol）、手动键入的文本）共享同一条确定性路径，没有专设的调用协议。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
 
-`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个、也是最后一个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
+`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
 
 ## 载体层（`/client` + 根路径）
 
@@ -69,4 +69,4 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 - **没有协议版本字段**：客户端与宿主一同发布；只有出现独立发布的客户端后，`host.describe` 才会增加版本协商字段。
 - **搜索失败会包含提供方诊断信息**：网关是单用户本地服务。将其暴露给多名用户的载体必须用可安全公开的诊断信息替代内部搜索细节。
 - **Linux 原生选择器依赖桌面工具**：在 `native` 能力下，Zenity 和 KDialog 均未安装时，`host.pickDirectory` 会给出包含解决建议的错误提示；组合层面的回退是 browse 后端（见 [native 后端 README](../directory-picker-native/README.md)）。
-- **冷会话的 `updatedAt` 会把一次单纯的拾起算作写入（仅逐文件后端）**：已附加投影排除了 `session/end-seed` 边界，因为接手一个会话不算活动；但冷会话的 `updatedAt` 取自其日志文件的 mtime，而每一次持久写入都会刷新它，包括这条边界。`agentFor()` 会在首次触碰时恢复一个冷会话，因此在客户端里仅仅打开一个会话就会写入它。这只适用于 `locate()` 能解析出逐会话产物的场景，即 JSONL；SQLite 返回 `undefined`，因此它的冷会话回退到 `createdAt`，偏差方向相反——偏旧而不是偏新——且与这条边界无关。于是一个被触碰过却没有在里面工作过的会话，在重新附加之前会按晚于其最后一次真实活动的时间排序。要把两者区分开需要读取日志，而这恰恰是 mtime 路径存在的目的；在索引中存储一个最后活动字段可以从源头修好它，范围见[最后活动索引 Agent Note（agent 决策记录）](../../../.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md)。
+- **冷会话的 `updatedAt` 会把一次单纯的拾起算作写入（仅逐文件后端）**：已附加投影排除了 `session/end-seed` 边界，因为接手一个会话不算活动；但冷会话的 `updatedAt` 取自其日志文件的 mtime，而每一次持久写入都会刷新它，包括这条边界。`agentFor()` 会在首次触碰时恢复一个冷会话，因此在客户端里仅仅打开一个会话就会写入它。这只适用于 `locate()` 能解析出逐会话产物的场景，即 JSONL；SQLite 返回 `undefined`，因此它的冷会话回退到 `createdAt`，偏差方向相反——偏旧而不是偏新——且与这条边界无关。于是一个被触碰过却没有在里面工作过的会话，在重新附加之前会按晚于其最后一次真实活动的时间排序。要把两者区分开需要读取日志，而这恰恰是 mtime 路径存在的目的；在索引中存储一个最后活动字段可以从源头修好它，范围见[最后活动索引 Agent Note](../../../.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md)。
diff --git a/packages/interaction/tool-ask-user/README.i18n.yaml b/packages/interaction/tool-ask-user/README.i18n.yaml
index f88c303525..4feb6f3b0f 100644
--- a/packages/interaction/tool-ask-user/README.i18n.yaml
+++ b/packages/interaction/tool-ask-user/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/interaction/tool-ask-user/README.md
 README.md: 7af356263ea6582a081e7c6de22fd317ca8b96df
-README.zh.md: 3f7b814b83c8c6957a4b2574ee69e87d45f65ae6
+README.zh.md: 5e5e8f2a8208c003c68ce1f3992c0bd34f2cb552
diff --git a/packages/interaction/tool-ask-user/README.zh.md b/packages/interaction/tool-ask-user/README.zh.md
index 3f7b814b83..5e5e8f2a82 100644
--- a/packages/interaction/tool-ask-user/README.zh.md
+++ b/packages/interaction/tool-ask-user/README.zh.md
@@ -54,5 +54,5 @@
 ## 已知限制与暂缓事项
 
 - **待处理问题会阻塞工具调用，直至用户作答**：该工具未声明 `timeout-policy` 预算；取消仅沿用当前轮次的 `exec.signal`。
-- **运行时中归属于其他 agent 的 subagent 不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝由另一个 agent 所有的存活子级；该子级必须在最终结果中包含尚未解决的问题或决策。持久化会话谱系不能决定这一边界，因此带有谱系的会话恢复为运行时根后可以正常提问。
+- **运行时中归属于其他 agent 的 subagent 不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝归属于另一个 agent 的存活子级；该子级必须在最终结果中包含尚未解决的问题或决策。持久谱系不能决定这一边界，因此带有谱系的会话恢复为运行时根后可以正常提问。
 - **Native 回答渲染为 JSON 文本**：规范值仍为结构化数据，但模型侧结果使用紧凑 JSON，而非更丰富的内容块词汇。
diff --git a/packages/interaction/user-interaction/README.i18n.yaml b/packages/interaction/user-interaction/README.i18n.yaml
index aafe594c7e..6326ea0dee 100644
--- a/packages/interaction/user-interaction/README.i18n.yaml
+++ b/packages/interaction/user-interaction/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/interaction/user-interaction/README.md
 README.md: cba015e782623b3a5adf018303823577a0b96774
-README.zh.md: a5f944850c5ac4e05da59e8478167eef91796610
+README.zh.md: acfacd1cef8150d6995d5c6285b5a331310fb89b
diff --git a/packages/interaction/user-interaction/README.zh.md b/packages/interaction/user-interaction/README.zh.md
index a5f944850c..acfacd1cef 100644
--- a/packages/interaction/user-interaction/README.zh.md
+++ b/packages/interaction/user-interaction/README.zh.md
@@ -22,7 +22,7 @@
 
 对于单选题，`custom` 会覆盖选中的选项，且 `selected` 为空。对于多选题，`custom` 可以补充 `selected` 中的标签。UI 可以把跳过的条目保留为 `{ id, selected: [] }`，既维持现有回答形态，也保留该批次中的其他回答。
 
-请求包含 agent 时，`ask()` 会通过当前 `AgentRegistry` 验证该 agent 与注册表中的存活实例是同一对象，并且只允许运行时根调用。持久化会话谱系不构成权限依据：带有历史委托深度的会话恢复为新的运行时根后可以提问；由另一个 agent 所有的存活子级即使持久化深度为零也会被拒绝。不含 agent 的程序化请求继续沿用现有提供方路径。
+请求包含 agent 时，`ask()` 会通过当前 `AgentRegistry` 验证该 agent 与注册表中的存活实例是同一对象，并且只允许运行时根调用。持久谱系不构成权限依据：带有历史委托深度的会话恢复为新的运行时根后可以提问；归属于另一个 agent 的存活子级即使持久化记录的委托深度为零也会被拒绝。不含 agent 的程序化请求继续沿用现有提供方路径。
 
 ### 呈现意图
 
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 790989c5d6..37ea49150b 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/llm-pi-ai/README.md
 README.md: eb67ce889193aadbd694d7aae53e47c7d20703be
-README.zh.md: b4b3e3c208702fa10e5f434a70608702d0576fbd
+README.zh.md: 8b8e5e6a219841d700db7161a7352a1880c41165
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index b4b3e3c208..8b8e5e6a21 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -4,7 +4,7 @@
 
 基于 [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai) 的 harness LLM（大语言模型）seam 通用多提供方适配器。一个插件实例拥有一份以路由为键的提供方 profile 字典；每个请求使用 `GenerateOptions.provider` 选择 profile，并针对该路由已配置的 catalog 解析 `GenerateOptions.model`。点名了已安装 pi-ai 提供方的路由会继承其端点、协议格式与模型 catalog 作为默认值，并逐字段覆盖；pi-ai 未提供的路由则整体声明出来，因此接入 OpenAI 兼容网关、自建服务，或比已安装 catalog 更新的提供方，都属于配置而非改代码。
 
-包（package）根入口导出 Cordis 插件契约、`PiAiAdapter` 与 `supportedProtocols()`；profile 解析、catalog 物化、提供方构造、回放转换和流转换保留在包内部。
+包根入口导出 Cordis 插件约定、`PiAiAdapter` 与 `supportedProtocols()`；profile 解析、catalog 物化、提供方构造、回放转换和流转换保留在包内部。
 
 ## 配置
 
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 30660e1032..4b1eda16c0 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/llm/README.md
 README.md: ddbc2ea482ca0848fb0ee0813839cf5ff1829bcc
-README.zh.md: 7a3b615d134e27d7c9892d6f411066d89938175b
+README.zh.md: 0ebb99c6e3743b881905110985575d348f1c7601
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 7a3b615d13..0ebb99c6e3 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -26,7 +26,7 @@
 
 `LlmService` 将最终适配器选择、同步 dispatch、iterator 构造与迭代中的失败规范化为流协议唯一的终止形式：`finish { kind: 'error' | 'aborted', failure }`。部分增量输出后发生失败时，内容块可能仍未闭合；消费方会丢弃这些不完整输出。`llm/stream` middleware、嵌套调用、适配器清理和下游消费方的错误仍会抛出，因为它们属于插件或消费方失败，而非模型请求结果。已准备调用会暴露随其确切适配器注册一同捕获的不可变重试策略；完全由 middleware 处理的路由没有服务策略。
 
-询问端点属于配置期针对**草稿**的操作，因此以 settings namespace 而非提供方路由为键：界面正在新增的提供方还不存在，也就没有路由可点名。但请求仍可**点名**它正在编辑的路由，而已经描述该路由的适配器应当用自己的知识作答——元数据更好，且无需联网——这正是 `baseURL` 可选、两者必居其一的原因。除此之外，请求携带端点、协议，以及一条 harness 只用于这一次询问、绝不存储的凭据——这里既不读也不写 settings 与 credentials，回复是界面可供用户采纳的候选元数据，而不是已注册的 catalog。`LlmDiscoveredModel` 除 `id` 外每个字段都是可选的，因为大多数提供方列表只公布 id；采纳其中一条的界面仍要补上其适配器所需的容量。重复与不可用的 id 会被丢弃，无人服务的 namespace 以 `NO_DISCOVERY` 失败，既不点名路由也不给端点的请求以 `INVALID_DISCOVERY` 失败。
+询问端点属于配置期针对**草稿**的操作，因此以 settings namespace 而非提供方路由为键：界面正在新增的提供方还不存在，也就没有路由可点名。但请求仍可**点名**它正在编辑的路由，而已经描述该路由的适配器应当用自己的知识作答——元数据更好，且无需联网——这正是 `baseURL` 可选、两者至少要有一个的原因。除此之外，请求携带端点、协议，以及一条 harness 只用于这一次询问、绝不存储的凭据——这里既不读也不写 settings 与 credentials，回复是界面可供用户采纳的候选元数据，而不是已注册的 catalog。`LlmDiscoveredModel` 除 `id` 外每个字段都是可选的，因为大多数提供方列表只公布 id；采纳其中一条的界面仍要补上其适配器所需的容量。重复与不可用的 id 会被丢弃，无人服务的 namespace 以 `NO_DISCOVERY` 失败，既不点名路由也不给端点的请求以 `INVALID_DISCOVERY` 失败。
 
 提供方与模型元数据是发现接口，不是路由白名单。`registerAdapter()` 仍拥有提供方排他性，并为每条路由捕获适配器的重试策略；适配器则可以接受 `listModels()` 中不存在的模型 id，消费方禁止因模型未列出而拒绝请求。返回的 selector 元数据与输入脱离，无效或重复适配器配置项会以 `INVALID_ADAPTER` 或 `INVALID_CATALOG` 失败。
 
@@ -97,5 +97,5 @@
 - **`GenerateOptions` 采样只包含 `temperature`／`maxTokens`／`stop`**：没有 `tool_choice`、`top_p` 或 penalty 字段；有产生方落地时词汇才会增长（见 [已删除惰性旋钮](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)）。
 - **受产生方约束的变体在实际产生前不会加入**：`prefill`、每工具 `strict`、块 `cache` 提示与 `agent` 消息源变体因没有产生方而被剪除（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)）。
 - **`BlockAssembler` 只处理核心块类型**：如果插件添加块类型的流从未由 `block-end` 关闭，`blocks()` 会抛出异常。
-- **`APP_IDENTITY.url` 指向一个尚不存在的仓库**：该公开主页必须在首次发布前可访问。
+- **`APP_IDENTITY.url` 指向一个尚不存在的仓库**：该公开主页必须在发布前可访问。
 - **`GenerateOptions.sessionId` 是本地声明的品牌类型**：导入 dsh-session 的 `SessionId` 会产生循环；未来拥有 id 的包可以消除该权宜之计。
diff --git a/packages/llm/token-meter/README.i18n.yaml b/packages/llm/token-meter/README.i18n.yaml
index 5c5a597802..a174ba4233 100644
--- a/packages/llm/token-meter/README.i18n.yaml
+++ b/packages/llm/token-meter/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/token-meter/README.md
 README.md: 8f868f25f3c4caf1fdab5b50965aab41efecf5af
-README.zh.md: 3621105ff35606b62b0587063038116b4772c6cf
+README.zh.md: 8bdf86517abaff79b78346549ff79b2fff93486a
diff --git a/packages/llm/token-meter/README.zh.md b/packages/llm/token-meter/README.zh.md
index 3621105ff3..8bdf86517a 100644
--- a/packages/llm/token-meter/README.zh.md
+++ b/packages/llm/token-meter/README.zh.md
@@ -29,9 +29,9 @@ fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成
 
 `contextPressure` 携带可选的 `pressureTokens`（提供方报告的最新提示词规模，为未缓存输入加缓存读取与写入之和）、可选的 `projectedTokens`，以及来自最新一条 `request/context` 记录的可选 `contextWindow`。提供方报告用量前两个数字都保持缺失；路由适配器未公布容量时容量也保持缺失。输出不计入其中，因此轮次流式输出期间 `pressureTokens` 保持不动，等到下一个请求报告用量时才前进。
 
-`projectedTokens` 是「下一个请求的提示词要花多少」：在该样本之上，加上自取样以来表层增减部分的启发式重新计价，下界钳制为零，折叠走的是测量服务重放的同一份 `surface-fold.ts`。只有增量部分是估算的，因此这个数字既锚定在提供方读数上，又能在内容落地——或压缩遮蔽一段区间——的瞬间做出反应。最后这种情况正是该字段存在的理由：压缩通过直连的 `ctx.llm.stream()` 调用生成摘要，自身不追加任何用量，所以仅凭 `pressureTokens` 会一直报告压缩前的提示词规模，直到又跑完一整轮为止。占用率展示读取 `projectedTokens`。
+`projectedTokens` 是「下一个请求的提示词要花多少」：在该样本之上，加上自取样以来表层增减部分的启发式重新计价，下界钳制为零，折叠走的是测量服务重放的同一份 `surface-fold.ts`。只有增量部分是估算的，因此这个数字既锚定在提供方读数上，又能在内容落地——或压缩遮蔽一段区间——的瞬间做出反应。最后这种情况正是该字段存在的理由：压缩通过直连的 `ctx.llm.stream()` 调用生成摘要，自身不追加任何用量，所以仅凭 `pressureTokens` 会一直报告压缩前的提示词规模，直到再完成一整个轮次为止。占用率展示读取 `projectedTokens`。
 
-`contextBreakdown` 携带启发式的 `systemTokens`、`toolsTokens` 与 `messageTokens`，描述上下文的组成而非提供方计费规模。envelope 数字在每条 `request/header` 上按后者胜重新计价；消息数字重放 `surface-fold.ts`——与 `measure()` 运行的位置折叠是同一份——因此它在每个事件边界上都等于 `measure().surfaceTokens`，压缩会像缩小下一个请求那样缩小它。三个数字都使用测量服务的固定启发式规则，属于估算值：它们加起来不等于 `projectedTokens`——后者的提供方锚点恰好把这些明细行仍然带着的误差排除在外（按「4 字符 ≈ 1 token」计价，CJK 文本与 JSON schema 会被严重低估）。请把它们当作近似的**组成**呈现，而不是总量。
+`contextBreakdown` 携带启发式的 `systemTokens`、`toolsTokens` 与 `messageTokens`，描述上下文的组成而非提供方计费规模。envelope 数字在每条 `request/header` 上按后者胜重新计价；消息数字重放 `surface-fold.ts`——也就是 `measure()` 运行的同一个带位置 fold——因此它在每个事件边界上都等于 `measure().surfaceTokens`，压缩会像缩小下一个请求那样缩小它。三个数字都使用测量服务的固定启发式规则，属于估算值：它们加起来不等于 `projectedTokens`——后者的提供方锚点所体现的恰好是这些明细行仍然带着的误差（按「4 字符 ≈ 1 token」计价，CJK 文本与 JSON schema 会被严重低估）。请把它们当作近似的**组成**呈现，而不是总量。
 
 三个单元都使用标准的投影基线、实时帧、seq 高者胜值仓和 JSON 检查点路径。卸载 token-meter 会移除这三个键。不带投影 seam 的组合会保留测量服务的既有行为。
 
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index 9fa4504cca..ff00f20c67 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-client/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/mcp/mcp-client/README.md
 README.md: d7966595c68ff1ec4a288caf5d9fe4b0bf580cc5
-README.zh.md: eb9e0dbdb48423cc4bc698fda355e973e42bc7a3
+README.zh.md: 6537e52eaaea9193d2d95fd0ddf1b4202e5ace38
diff --git a/packages/mcp/mcp-client/README.zh.md b/packages/mcp/mcp-client/README.zh.md
index eb9e0dbdb4..6537e52eaa 100644
--- a/packages/mcp/mcp-client/README.zh.md
+++ b/packages/mcp/mcp-client/README.zh.md
@@ -61,7 +61,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 - 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
 - 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
 - Native／模型渲染保留现有文本投影：文本块以换行连接，图片、音频、资源和不受支持的块会变成占位符。
-- 断开／崩溃时：不自动重新连接。已注册工具会一直保留到插件完成资源释放或成功重新同步，针对已关闭传输的调用可能失败；请通过 HMR 重新加载或重启 Host 来重新连接。
+- 断开／崩溃时：不自动重新连接。已注册工具会一直保留到对插件执行 dispose（资源释放）或成功重新同步，针对已关闭传输的调用可能失败；请通过 HMR 重新加载或重启 Host 来重新连接。
 
 ## 消费的服务
 
@@ -75,7 +75,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 #### 模型看到的内容
 
-初始发现成功后，每个已声明的 MCP 工具都会显示为名为 `mcp__<serverName>__<rawName>`（或其确定性规范化形式）的原生工具，并携带服务器提供的描述和输入 schema。成功的重新同步会替换整个世代；对插件执行 dispose（资源释放）会移除该世代。
+初始发现成功后，每个已声明的 MCP 工具都会显示为名为 `mcp__<serverName>__<rawName>`（或其确定性规范化形式）的原生工具，并携带服务器提供的描述和输入 schema。成功的重新同步会替换整个世代；对插件执行 dispose 会移除该世代。
 
 #### Token 影响
 
diff --git a/packages/sandbox/sandbox-local/README.i18n.yaml b/packages/sandbox/sandbox-local/README.i18n.yaml
index cbc1e9ad55..13fa52ce9d 100644
--- a/packages/sandbox/sandbox-local/README.i18n.yaml
+++ b/packages/sandbox/sandbox-local/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox-local/README.md
 README.md: 23d3a32451c105c71c0a7399ed051288b70753f3
-README.zh.md: 165a6fc88a9fdd219c3ddb016cdf415504556d8c
+README.zh.md: 1890771faf8cab6b1842f973a999c7a9cf2dbb11
diff --git a/packages/sandbox/sandbox-local/README.zh.md b/packages/sandbox/sandbox-local/README.zh.md
index 165a6fc88a..1890771faf 100644
--- a/packages/sandbox/sandbox-local/README.zh.md
+++ b/packages/sandbox/sandbox-local/README.zh.md
@@ -8,11 +8,11 @@
 
 不受支持的平台和不可用 runner 会以 `SANDBOX_UNAVAILABLE` 拒绝执行；执行绝不会静默回退为不受限制。每次包装都携带结构化 runner 失败规则，使消费方能够区分损坏的沙箱与命令失败。[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责说明选择依据与 profile 差异。
 
-策略逐调用传入；提供方只存储机制与缓存的 runner 结论。每次包装都会报告强制执行完整度，以及后端专用的拒绝签名和 runner 失败规则。Landlock 只有在退出码为 125，且排除唯一精确匹配的部分强制执行通知后仍存在一行 `landlock-run:` 致命诊断时，才判定 runner 失败；携带该通知的子进程即使以 1、2 或 125 退出，也仍按子进程结果处理。Bubblewrap 和 Seatbelt 仍仅依据签名，因为两者的公开契约均未保留 launcher 失败状态。消费方会直接 spawn 返回的 argv，因此 runner 缺失或不可执行属于带外 spawn 失败，而成功启动的子进程以 126 或 127 退出时仍按普通结果处理。`runnerCommand` 会跳过探测，并要求为自定义 runner 自身的致命方言提供一个或多个非空、单行、不区分大小写的 `runnerFailureSignatures` 条目。由于其机制未知，它会同时携带两种 Linux 拒绝方言。`probeTimeoutMs` 限制功能探测。[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责说明选择与失败语义。
+策略逐调用传入；提供方只存储机制与缓存的 runner 结论。每次包装都会报告强制执行完整度，以及后端专用的拒绝签名和 runner 失败规则。Landlock 只有在退出码为 125，且仅排除完全匹配的部分强制执行通知后仍存在一行 `landlock-run:` 致命诊断时，才判定 runner 失败；携带该通知的子进程即使以 1、2 或 125 退出，也仍按子进程结果处理。Bubblewrap 和 Seatbelt 仍仅依据签名，因为两者的公开约定均未保留 launcher 失败状态。消费方会直接 spawn 返回的 argv，因此 runner 缺失或不可执行属于带外 spawn 失败，而成功启动的子进程以 126 或 127 退出时仍按普通结果处理。`runnerCommand` 会跳过探测，并要求为自定义 runner 自身的致命方言提供一个或多个非空、单行、不区分大小写的 `runnerFailureSignatures` 条目。由于其机制未知，它会同时携带两种 Linux 拒绝方言。`probeTimeoutMs` 限制功能探测。[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责说明选择与失败语义。
 
 Seatbelt profile 默认允许，但带 `(deny file-write*)` 和写入 allow-list，因此恰好约束相应模式承诺的文件操作：`read-only` 只授予 `/dev/null` 字面路径；`workspace-write` 另加工作区根目录、`/tmp` 和逐用户 darwin 临时目录（`os.tmpdir()`，即平台供 mkstemp 家族工具使用的真实临时区域）。每个根目录都经过规范化，因为 Seatbelt 匹配解析后的路径（`/tmp` 就是 `/private/tmp`）。Apple 将 `sandbox-exec` CLI（命令行界面）标为 deprecated，但所有 macOS 系统仍会提供它；若情况发生变化，功能探测会使执行被拒绝。
 
-[`@deepseek-ai/node-addon-landlock-run`](https://www.npmjs.com/package/@deepseek-ai/node-addon-landlock-run)提供平台 launcher、功能探测和 CLI 参数词汇。该提供方只负责模式到授权的映射与 runner 选择。把路径解析和探测解析保留在带版本的 binary 中，可防止契约漂移。
+[`@deepseek-ai/node-addon-landlock-run`](https://www.npmjs.com/package/@deepseek-ai/node-addon-landlock-run)提供平台 launcher、功能探测和 CLI 参数词汇。该提供方只负责模式到授权的映射与 runner 选择。把路径解析和探测解析保留在带版本的 binary 中，可防止约定漂移。
 
 ```yaml
 - id: sandbox
diff --git a/packages/sandbox/sandbox-policy/README.i18n.yaml b/packages/sandbox/sandbox-policy/README.i18n.yaml
index 0b626d5343..27bcc3b85f 100644
--- a/packages/sandbox/sandbox-policy/README.i18n.yaml
+++ b/packages/sandbox/sandbox-policy/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox-policy/README.md
 README.md: b2512790c5cf5b3a06523cf91b50dd5d288b1522
-README.zh.md: dda98b7aa4775ac2453704295df87c3c92025093
+README.zh.md: 58354adf55a55951cad1ea9adb88aea2457c7f7b
diff --git a/packages/sandbox/sandbox-policy/README.zh.md b/packages/sandbox/sandbox-policy/README.zh.md
index dda98b7aa4..58354adf55 100644
--- a/packages/sandbox/sandbox-policy/README.zh.md
+++ b/packages/sandbox/sandbox-policy/README.zh.md
@@ -17,7 +17,7 @@
 
 - `ctx.sandboxPolicy.resolve({ session?, mode? })`：解析一项完整的逐调用策略。显式批准的模式优先于会话最后一条 `sandbox/mode` 事件，后者又优先于 `defaultMode`；会话不可变的 `cwd` 会先按文件系统语义规范化，再成为 `workspaceRoot`，否则使用配置的回退值。规范化先于词法归一化，因此 `symlink/..` 与进程工作目录解析保持一致。
 - `ctx.sandboxPolicy.defaultMode`／`ctx.sandboxPolicy.workspaceRoot`：`resolve()` 使用的部署默认值与回退根目录。
-- `sandbox:policy`：直接派生自 `resolve({ session })` 的请求时缓存安全上下文贡献。它说明该模式中与具体能力无关的文件效果契约，以及 `workspace-write` 下规范化的会话工作区；工具归属方仍负责操作特定的拒绝与升权引导。
+- `sandbox:policy`：直接派生自 `resolve({ session })` 的请求时缓存安全上下文贡献。它说明该模式中与具体能力无关的文件操作约定，以及 `workspace-write` 下规范化的会话工作区；工具归属方仍负责特定于操作的拒绝与升权引导。
 - `effectiveSandboxMode(events)`：会话 `sandbox/mode` 事件的纯 fold（最后一次切换胜出，没有则为 `undefined`），在 `resolve()` 内使用。
 - `setSandboxMode(session, mode)`：逐会话覆盖的唯一写入路径：恰好追加一条 `sandbox/mode` 事件。切换本身就是事件；不会在带外修改模式。
 - `SANDBOX_MODES`：所有模式，用于选项展示与运行时验证。
@@ -34,7 +34,7 @@
 
 #### 模型看到的内容
 
-每个 agent 会话的当前运行时上下文快照中都有一项 `sandbox:policy` 贡献。它不枚举已装载的能力。工具插件继续负责操作与升级引导，批准策略单独贡献给同一份快照，计划引导仍由 `dsh-plan-mode` 的系统段落管理。
+每个 agent 会话的当前运行时上下文快照中都有一项 `sandbox:policy` 贡献。它不枚举已装载的能力。工具插件继续负责操作与升权引导，批准策略单独贡献给同一份快照，计划引导仍由 `dsh-plan-mode` 的系统段落管理。
 
 ##### 只读
 
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index e0ce60a641..5d9e9eabd2 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/self-modification/repository-plugin/README.md
 README.md: 33cd763d7dbe21b72f9e604b7b2e313081cf656f
-README.zh.md: 903dfbe601cc76acb0c1e87453dc03ef0321409b
+README.zh.md: 3cb2cadffdacd037486223793604127f10b162bb
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 903dfbe601..3cb2cadffd 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -30,7 +30,7 @@
 
 ## 独立应用配置
 
-每个 profile 都以之为起点的随附 `dsh-base` 组合包包含一个空 `repository-plugins` 配置项。用户可在用户 patch 层中替换该配置项的配置来启用精确指定的 GitHub generation：写入 `$DSH_HOME/profiles/<name>/cordis.patch.yml`，或写入各 profile 共享的 home 级 `$DSH_HOME/cordis.patch.yml`；`--patch` overlay 则只为单次运行 patch 同一配置项：
+随附的 `dsh-base` 组合包是每个 profile 的起点，其中包含一个空 `repository-plugins` 配置项。用户可在用户 patch 层中替换该配置项的配置来启用精确指定的 GitHub generation：写入 `$DSH_HOME/profiles/<name>/cordis.patch.yml`，或写入各 profile 共享的 home 级 `$DSH_HOME/cordis.patch.yml`；`--patch` overlay 则只为单次运行 patch 同一配置项：
 
 ```yaml
 - id: repository-plugins
@@ -43,7 +43,7 @@
 
 每个源都必须采用 `github:owner/repository#<ref>`。省略 `&path:` 时选择 `/.dsh-plugin`；显式路径是仓库内的绝对路径，并且必须以 `.dsh-plugin` 结尾。commit ref 提供最清晰的不可变身份；tag 和 branch 仍可作为精确配置值使用。`cacheDir` 可覆盖默认缓存根 `$DSH_HOME/cache/repository-plugins`。
 
-长期运行的 surface 通过 Cordis HMR（热模块替换）监视两个 `cordis.patch.yml` 层。有效的源列表变更会安装并替换整套 repository Plugin generation；拉取、准备、导入或插件应用失败时，最后一个可用树保持运行，并广播 `hmr/config-update-failed(filename, error)`。一次性运行只在启动时读取这些层，`--patch` overlay 则从不被监视。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入 repository Plugin 的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
+长期运行的 surface 通过 Cordis HMR（热模块替换）监视两个 `cordis.patch.yml` 层。有效的源列表变更会安装并替换整套仓库插件 generation；拉取、准备、导入或插件应用失败时，最后一个可用树保持运行，并广播 `hmr/config-update-failed(filename, error)`。一次性运行只在启动时读取这些层，`--patch` overlay 则从不被监视。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入仓库插件的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
 
 ## 准备阶段
 
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 2ab76b4da9..5a4c078a55 100644
--- a/packages/session/session-persistence-jsonl/README.i18n.yaml
+++ b/packages/session/session-persistence-jsonl/README.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 packages/session-persistence/session-persistence-jsonl/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence-jsonl/README.md
 README.md: b7fa8fc2918711dd24eeba67132a267452d401f9
-README.zh.md: 59d21c6171e857849c4ab48940d66962fffbfdeb
+README.zh.md: e260c7671a1f60eec23852ac27ee5da38425b5fd
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index 59d21c6171..e260c7671a 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -26,7 +26,7 @@ JSONL 持久会话存储后端：`SessionPersistence` 的一个具体实现（`d
 | `root` | `string`（必需） | 所有会话文件的根目录。**无默认值**：`process.cwd()` 默认值会随进程 cwd 变更（bash 调用、子进程）而分散文件。现有根必须是可读目录；缺失根在第一次实体化时创建。 |
 | `packChunks` | `boolean`（默认 `true`） | 将符合条件的 delta 分片连续段写为打包行（在真实编码会话上测得逻辑日志约小 60%）。设为 `false` 可用于每事件一行诊断；无论该写入侧开关如何，都能读取打包行。 |
 | `compression` | `'zstd' \| 'none'` | 默认 `'zstd'`；`'none'` 保留换行分隔 UTF-8 文本。 |
-| `preparedSessionCacheSize` | 正整数（默认 `5`） | 冷历史检查后保留、供恢复复用的未发布 Session 数量上限。 |
+| `preparedSessionCacheSize` | 正整数（默认 `5`） | 冷历史检查后保留、供恢复复用的未发布会话数量上限。 |
 | `writeBatchMaxDelayMs` | 正整数（默认 `200`） | 空闲的活动事件队列收到待写入事件后开启的固定合并窗口。后续事件不会重置窗口；flush 与 teardown 会绕过它。该值不限制事件循环、串行化操作或后端延迟。最大值为 Node 计时器上限 `2_147_483_647` ms。 |
 
 `locate(meta)` 返回已解析项目/会话目录内固定 transcript 的 `{ kind: 'jsonl', path }`。它不执行文件系统 I/O：可以在目录或文件存在前返回目标，现有文件也只包含最近一次 flush 完成的前缀。
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index f6d2d2926b..bb8335b826 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/README.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 packages/session-persistence/session-persistence-sqlite/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence-sqlite/README.md
 README.md: 4961f62bf6854c343d35b8406c9d721590274534
-README.zh.md: 8610ef56f737bac8781536ea26a5b48dbf67ed48
+README.zh.md: 237352d1661f505ec0352dfc3eae48d9b636e44a
diff --git a/packages/session/session-persistence-sqlite/README.zh.md b/packages/session/session-persistence-sqlite/README.zh.md
index 8610ef56f7..237352d166 100644
--- a/packages/session/session-persistence-sqlite/README.zh.md
+++ b/packages/session/session-persistence-sqlite/README.zh.md
@@ -22,7 +22,7 @@ SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[
 - **延迟实体化。**`create()` 只在内存记录意图，第一次 `append` 前不写行。从未 append 的会话没有 `sessions` 行，因此不在 `list()` 中（它精确报告有行的会话）。
 - **在 load 时关闭中断轮次。**`load()` 实现共享[崩溃恢复契约](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)：保留有效中断轮次，在一个事务中追加合成关闭事件，并只移除撕裂尾部行。已提交解析错误或序列缺口使会话无法加载。恢复会变更已存储行，因此下一次 append 从平衡日志和准确游标开始。
 - **非变更检查。**`inspect()` 返回不可变、平衡的逻辑视图，并可在内存中合成恢复 closer，但不会删除撕裂尾部行、追加恢复行或更改轻量修订。
-- **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。完整前缀读取在同一个读事务中捕获该 revision 及其事件行，`readStoredRevision()` 则只查询 session 行来校验保留的 preparation。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
+- **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。完整前缀读取在同一个读事务中捕获该修订及其事件行，`readStoredRevision()` 则只查询会话行来校验保留的准备结果。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
 
 ## 配置（schemastery）
 
@@ -37,7 +37,7 @@ interface Config {
 
 ## 写入路径
 
-与 JSONL 后端一样，插件将每个冻结的 `session/event` 复制到每个活动会话各自的 controller。第一个待处理事件会开启配置的固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个事务；该次写入期间接纳的事件会形成另一个独立有界的后续批次。`session/flush` 会取消等待并排空当前与待处理批次。Controller 会持久化一次 fork 种子，并保留写入游标，使恢复操作绝不重新 append 已存储事件；它还会在 apply 时为活动会话设置初始状态，因为 HMR（热模块替换）不回放 `session/created`。dispose（资源释放）会在关闭数据库前排空每个保留的 controller。每个事件仍各占一行 SQLite 记录；批处理只把更多 INSERT 归入同一个事务和同一次修订版本递增。
+与 JSONL 后端一样，插件将每个冻结的 `session/event` 复制到每个活动会话各自的 controller。第一个待处理事件会开启配置的固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个事务；该次写入期间接纳的事件会形成另一个独立有界的后续批次。`session/flush` 会取消等待并排空当前与待处理批次。Controller 会持久化一次 fork 种子，并保留写入游标，使恢复操作绝不重新 append 已存储事件；它还会在 apply 时为活动会话设置初始状态，因为 HMR（热模块替换）不回放 `session/created`。dispose（资源释放）会在关闭数据库前排空每个保留的 controller。每个事件仍各占一行 SQLite 记录；批处理只把更多 INSERT 归入同一个事务和同一次修订递增。
 
 ## 模型体验
 
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index 5b131371b8..b6c2b25e6f 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/README.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 packages/session-persistence/session-persistence/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence/README.md
 README.md: 89c7cd5ebaff6f9ce9df9b60a50121dff4ddeeb5
-README.zh.md: 1ef7eb6c6c507167f61bb5df7c4ce8183aac5d0d
+README.zh.md: 6b02f37343da07a80953ecb9d05e5903bd42d95c
diff --git a/packages/session/session-persistence/README.zh.md b/packages/session/session-persistence/README.zh.md
index 1ef7eb6c6c..6b02f37343 100644
--- a/packages/session/session-persistence/README.zh.md
+++ b/packages/session/session-persistence/README.zh.md
@@ -8,14 +8,14 @@
 
 ## 服务 API（`ctx.sessionPersistence`）
 
-| 方法 | 契约 |
+| 方法 | 约定 |
 |---|---|
 | `locate(meta): SessionLocation \| undefined` | 在不执行 I/O 或实体化的情况下解析绝对的每会话产物目标。没有独立本地产物的后端返回 `undefined`。 |
 | `create(meta): Promise<void>` | 注册新会话元数据。可以将物理写入延迟到第一次 `append`（延迟实体化）。 |
 | `append(id, events): Promise<void>` | 持久保存一个批次。仅追加；任何修复后，第一个事件 `seq` == 已存储 next-seq；非 JSON 可序列化数据会被拒绝，并命名违规类型。 |
-| `prepare(id, signal?): Promise<SessionPreparation>` | 预留恢复使用的精确未发布 Session。协调器会尽可能复用之前的检查结果、提交待处理恢复，并在 dispose 时将未发布 reservation 释放回有界缓存。 |
+| `prepare(id, signal?): Promise<SessionPreparation>` | 预留恢复所使用的那个未发布 Session。协调器会尽可能复用之前的检查结果、提交待处理恢复，并在 dispose 时将未发布 reservation 释放回有界缓存。 |
 | `load(id): Promise<{ meta; events }>` | 在升级受支持的同版本形状后返回不可变、平衡的逻辑日志，并提交冷恢复。实时 load 先 flush 其快照，并在轮次开放时拒绝；冷 load 保留中断的最终轮次，并用合成 `tool/result`/`step/end?`/`turn/end {interrupted}` 事件持久关闭它。只丢弃撕裂尾部碎片；已提交损坏、格式错误的形状和未知 `version` 会被拒绝。 |
-| `inspect(id, signal?): Promise<{ meta; events }>` | 返回已经升级、验证和深度冻结的逻辑视图，但不提交恢复或发布 Session。冷视图会获得仅存在于内存的合成恢复 closer，物理撕裂尾部保持不变；已经实时存在的视图则是当前不可变快照，可能包含打开的 turn。基于协调器的实现会在有界 LRU 中保留精确的冷未发布 Session，供后续 `prepare` 使用，但已存储 revision 变化后会丢弃并重新读取。同 id 检查共享进行中的读取。 |
+| `inspect(id, signal?): Promise<{ meta; events }>` | 返回已经升级、验证和深度冻结的逻辑视图，但不提交恢复或发布 Session。冷视图会获得仅存在于内存的合成恢复 closer，物理撕裂尾部保持不变；实时状态下的视图则是当前不可变快照，可能包含开放的轮次。基于协调器的实现会在有界 LRU 中保留该冷状态下未发布的 Session 本身，供后续 `prepare` 使用，但已存储修订值变化后会丢弃并重新读取。同 id 检查共享进行中的读取。 |
 | `readFrom(id, fromSeq, signal?): Promise<{ meta; events }>` | 脱离的物理后缀原语：返回 `seq >= fromSeq` 的有效已存储事件，不进入 preparation 缓存、不截断、不合成 closer，也不发布协调器状态。`fromSeq` 达到或超过已存储末尾时返回空事件列表；负数或非安全整数 `fromSeq` 会被拒绝。可寻址后端（SQLite）只读后缀，除非受支持的旧形状需要前缀上下文才能完成规范化；顺序后端（JSONL）解析整个产物并向前跳过。用于只续折水位之后尾部的 checkpoint 消费方。 |
 | `list(signal?): Promise<SessionHeader[]>` | 从元数据轻量列出，不解析完整日志。可选信号取消后端列表工作。零事件延迟实体化会话不在 `list` 中。 |
 | `listSnapshots(signal?): Promise<SessionPersistenceSnapshot[]>` | 返回轻量元数据和每份日志一个不透明、带品牌类型的修订值，不加载事件日志。日志及其后端存储不变时，修订保持相等；append 或变更性 load 修复后会改变；不会仅因两个存储使用相同本地计数器而冲突。可选信号请求取消后端发现工作；第一方后端会先等待所有已启动的列出工作结束，再予以拒绝，因此调用返回拒绝时，相关工作已完全停稳。 |
@@ -33,13 +33,13 @@
 
 每个 `session/event` 将事件复制到会话 controller。第一个待处理事件会开启固定批处理窗口；后续事件会加入该批次，但不会重置截止时间。配置的 `writeBatchMaxDelayMs` 只限制这段有意等待，而不限制事件循环、初始化、串行化操作或后端延迟。写入期间接纳的事件会形成一个新的有界批次。`session/flush` 会取消等待，并作为共享的完全停稳屏障，排空屏障运行期间接纳的事件。后台写入失败只记录一次日志，保留顺序不变的批次，并暂停自动重试；新事件会开启新的固定窗口，而显式 flush 或后端拆卸会立即重试，并在失败再次发生时向调用方暴露失败。
 
-崩溃修复只适用于冷状态。对于实时 id，`load(id)` 为权威内存日志制作快照，等待该快照持久，并只在平衡时返回；开放实时轮次会被拒绝，而不会收到合成中断 closer。对于冷 id，检查只读取、验证、冻结并构造一次未发布 Session；只有来源 revision 仍然是当前值时，重复检查才会复用该对象图。`prepare(id)` 在修复前执行相同校验，预留精确 Session，提交任何待处理的撕裂尾部或中断轮次修复，并将其返回用于发布。HMR 接管通过 `loadStored` 读取，应用协调器 cwd 检查，并绝不关闭活动轮次。
+崩溃修复只适用于冷状态。对于实时 id，`load(id)` 为权威内存日志制作快照，等待该快照持久，并只在平衡时返回；开放实时轮次会被拒绝，而不会收到合成中断 closer。对于冷 id，检查只读取、验证、冻结并构造一次未发布 Session；只有来源修订值仍然是当前值时，重复检查才会复用该对象图。`prepare(id)` 在修复前执行相同校验，预留该 Session 本身，提交任何待处理的撕裂尾部或中断轮次修复，并将其返回用于发布。HMR 接管通过 `loadStored` 读取，应用协调器 cwd 检查，并绝不关闭活动轮次。
 
-后端读取会在当前形状验证前，规范化明确受支持的同版本形状。消息标识机制引入前的消息会获得确定性的 id `legacy-message:<session-id>:<event-seq>`；工具结果的内容替换会继承其目标导入后的 id。react-loop 重构前的 `turn/start` 会移除过时的 trigger，已移除的 steering（中途引导）事件 `steering/message` 会转换为同一条带标识的 `user/message`；旧版 `turn/end` 会在不虚构无法获得的取消来源的前提下映射终止原因。协调器对 `load`、`inspect`、`readFrom`、无 owner 状态的认领和 HMR 前缀接管使用同一份规范化视图。存储仍然仅追加：读取不会重写旧记录，此后追加的事件使用当前形状。这些是[消息标识机制引入前的消息](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)与 [react-loop 重构前会话](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md)决策所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
+后端读取会在当前形状验证前，规范化明确受支持的同版本形状。消息标识机制引入前的消息会获得确定性的 id `legacy-message:<session-id>:<event-seq>`；工具结果的内容替换会继承其目标导入后的 id。react-loop 引入前的 `turn/start` 会移除过时的 trigger，已移除的 steering（中途引导）事件 `steering/message` 会转换为同一条带标识的 `user/message`；旧版 `turn/end` 会在不虚构无法获得的取消来源的前提下映射终止原因。协调器对 `load`、`inspect`、`readFrom`、无所有者状态的认领和 HMR 前缀接管使用同一份规范化视图。存储仍然仅追加：读取不会重写旧记录，此后追加的事件使用当前形状。这些是[消息标识机制引入前的消息](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)与 [react-loop 引入前会话](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md)决策所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
 
 实时会话发出 `session/disposed` 时，协调器等待其 controller，串行化最终 drain，然后释放该精确 `Session` 对象拥有的状态。失败退役会将 controller 保留在实时会话 map 中，使后端拆卸可重试。后端拆卸先停止事件接纳，flush 每个剩余 controller，等待每 id 操作，最后才关闭存储句柄。
 
-无副作用 `locate`、轻量 `listSnapshots` 和按 id 查询的 `readStoredRevision` 仍由后端负责，因为它们描述存储拓扑和 revision 身份，而非写入编排。`listSnapshots(signal?)` 将调用方传入的同一个信号传给后端发现流程，使观察者可在不脱离该工作的情况下取消。
+无副作用 `locate`、轻量 `listSnapshots` 和按 id 查询的 `readStoredRevision` 仍由后端负责，因为它们描述存储拓扑和修订身份，而非写入编排。`listSnapshots(signal?)` 将调用方传入的同一个信号传给后端发现流程，使观察者可在不脱离该工作的情况下取消。
 
 `PersistenceBackend<TornMarker>` 钩子（协调器与存储之间的唯一 seam）：
 
@@ -47,14 +47,14 @@
 |---|---|
 | `name` | dispose 失败 `AggregateError` 的后端标签。 |
 | `loadStored(id, signal?)` | 在全部存储范围中按 id 读取已存储前缀。用于恢复／加载、非修改式 inspect、实时接管和 create 冲突探测。可选信号属于仅观察读取。返回元数据标识 `id`；`revision` 精确标识返回的 header 和事件；当且仅当必须截断撕裂尾部时才存在不透明 `tornMarker`。 |
-| `readStoredRevision(id, signal?)` | 在不加载事件日志的情况下读取一个 id 当前的来源限定 revision。它使用与 `loadStored` 相同的 revision 表示；id 不存在时返回 `undefined`。 |
+| `readStoredRevision(id, signal?)` | 在不加载事件日志的情况下读取一个 id 当前的来源限定修订值。它使用与 `loadStored` 相同的修订值表示；id 不存在时返回 `undefined`。 |
 | `loadStoredFrom?(id, fromSeq, signal?)` | 服务 `readFrom` 背后的可选可寻址后缀读取：返回 header 和 `seq >= fromSeq` 的已存储事件，非变更、无撕裂标记。SQLite 实现它（`WHERE seq >= ?`）；不实现的后端使用协调器回退——`loadStored` 加向前跳过。 |
 | `appendBatch(meta, events, isMaterialized)` | 持久追加连续批次；尚未实体化时以原子方式延迟实体化。 |
 | `commitRepair(meta, tornMarker, closers)` | 使崩溃修复持久：截断撕裂尾部（当且仅当 `tornMarker !== undefined`；标记可为 falsy，例如 seq/offset `0`），并追加 `closers`。不要求原子性。由 load（截断 + closer）和实时接管（仅截断）使用。 |
 | `list(signal?)` | 列出全部已存储元数据，并遵循可选的取消信号。 |
 | `close?()` | 可选生命周期拆卸（例如关闭 db 句柄），在 dispose drain 后等待。 |
 
-协调器断言已存储 id，并在修复或实时接管前比较已存储/实时 cwd。其 `inspect()` 路径取得新鲜后端值的所有权，只验证和冻结一次，并在不调用 `commitRepair` 的情况下最多保留配置数量的未发布 Session。只有保留源的 revision 仍等于 `readStoredRevision` 时，系统才会复用或修复它；否则协调器会重新读取。该新鲜性校验不会增加跨进程写入排他。持久日志在一次读取与复核往返内保持不变时，revision 重试才能收敛；持续的外部写入可能延迟 `load`、`inspect` 或 `prepare`。`tornMarker` 完全不透明：协调器只测试 `!== undefined`，并将其原样往返给 `commitRepair`，绝不检查值（JSONL 后端使用待截断字节偏移，SQLite 后端使用待删除 seq）。第三方后端可以不用协调器直接实现抽象服务，但必须提供相同非变更检查和可信轻量快照修订。详见[写入协调器 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)。
+协调器断言已存储 id，并在修复或实时接管前比较已存储/实时 cwd。其 `inspect()` 路径取得新鲜后端值的所有权，只验证和冻结一次，并在不调用 `commitRepair` 的情况下最多保留配置数量的未发布 Session。只有保留源的修订值仍等于 `readStoredRevision` 时，系统才会复用或修复它；否则协调器会重新读取。该新鲜性校验不会增加跨进程写入排他。持久日志在一次读取与复核往返内保持不变时，修订值重试才能收敛；持续的外部写入可能延迟 `load`、`inspect` 或 `prepare`。`tornMarker` 完全不透明：协调器只测试 `!== undefined`，并将其原样往返给 `commitRepair`，绝不检查值（JSONL 后端使用待截断字节偏移，SQLite 后端使用待删除 seq）。第三方后端可以不用协调器直接实现抽象服务，但必须提供相同非变更检查和可信轻量快照修订。详见[写入协调器 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)。
 
 ## 元数据与位置类型
 
diff --git a/packages/session/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
index 34c1910b16..746d64865d 100644
--- a/packages/session/session-projection/README.i18n.yaml
+++ b/packages/session/session-projection/README.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 packages/session-projection/session-projection/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-projection/README.md
 README.md: a42e88c262915fc5e53cd72205079cbc8029a8df
-README.zh.md: f60a48bd41f0c33edb85a495ada9b6818ec46ee5
+README.zh.md: 02f1876fc95b5e400f63ae6a0dd1910da4f63c3b
diff --git a/packages/session/session-projection/README.zh.md b/packages/session/session-projection/README.zh.md
index f60a48bd41..02f1876fc9 100644
--- a/packages/session/session-projection/README.zh.md
+++ b/packages/session/session-projection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-会话投影 seam。它拥有 `ctx.sessionProjections`：该注册表在已提交的会话事件上驱动每个已注册的投影单元，并向载体提供完整的最终值，目前包括 api-proxy 历史尾页和 `session/projection` 推送帧。领域注册的只是纯数学；驱动权归框架。[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)记录了设计理由。
+会话投影 seam。它拥有 `ctx.sessionProjections`：该注册表在已提交的会话事件上驱动每个已注册的投影单元，并向载体提供完整的最终值，目前包括 api-proxy 历史尾页和 `session/projection` 推送帧。领域注册的只是纯数学；驱动权归框架。[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) 记录了设计理由。
 
 ## 服务：`SessionProjectionRegistry`（ctx 键：`sessionProjections`）
 
diff --git a/packages/session/session-telemetry-otel/README.i18n.yaml b/packages/session/session-telemetry-otel/README.i18n.yaml
index 0424414fac..f3a790b362 100644
--- a/packages/session/session-telemetry-otel/README.i18n.yaml
+++ b/packages/session/session-telemetry-otel/README.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 packages/telemetry/session-telemetry-otel/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-telemetry-otel/README.md
 README.md: 585995ce409255df9608bc33b76625374bc67669
-README.zh.md: 6d2cfa4d492cee7f90d557c83f5c1ab3c730c6e5
+README.zh.md: 889e46c24785c21cbb19e980291310ad096e761f
diff --git a/packages/session/session-telemetry-otel/README.zh.md b/packages/session/session-telemetry-otel/README.zh.md
index 6d2cfa4d49..889e46c247 100644
--- a/packages/session/session-telemetry-otel/README.zh.md
+++ b/packages/session/session-telemetry-otel/README.zh.md
@@ -29,7 +29,7 @@
 
 上传授权采用显式许可，且为 fail-closed。通过直接构造传入未知模式时，会在读取传输配置前失败。只有 `FULL` 接受对 `ctx.telemetry.emit()` 的直接调用。`FEEDBACK_ONLY` 向其按需协调器提供私有后端能力，并且仅在 `feedback/record` 对象已经存储于 `session.events[event.seq]` 且对象身份完全相同时，才将其视为同意；独立发出的总线值会被忽略。即使存在导出器选项，`DISABLED` 也绝不会构造 SDK 流水线。
 
-`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填，无默认值，且必须能解析为 `http(s)`；在 `DISABLED` 中可省略且不使用。在上传模式中，`shutdownTimeoutMillis` 是由 DSH 管理的有限正数外层截止时间，默认值为 3000 ms；`processor.maxExportBatchSize` 不是正整数时也会在插件加载时失败，因为 SDK 会接受该值，随后却在关闭时挂起。两个 SDK 配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是通过 `processor` 调节的 SDK 行为。该后端不实现 `flush()`：常规 flush 由批处理器负责。关闭期间，OTel 会先等待 `exporter.forceFlush()`，再进入受处理器 `exportTimeoutMillis` 限制的完成 promise；如果该传输 promise 始终不结算，本包会在 `shutdownTimeoutMillis` 到期时放弃等待，通过协调器记录已隔离的关闭失败，并让应用继续拆卸。该截止时间无法取消 SDK 传输，因此届时仍待处理的记录可能在进程退出时丢失。
+`exporter.url` 在 `FULL` 与 `FEEDBACK_ONLY` 中必填，无默认值，且必须能解析为 `http(s)`；在 `DISABLED` 中可省略且不使用。在上传模式中，`shutdownTimeoutMillis` 是由 DSH 管理的有限正数外层截止时间，默认值为 3000 ms；`processor.maxExportBatchSize` 不是正整数时也会在插件加载时失败，因为 SDK 会接受该值，随后却在关闭时挂起。两个 SDK 配置块都整体透传（passthrough）：`OTLPExporterNodeConfigBase` 的每个字段（`headers`、`timeoutMillis`、`compression`、`keepAlive` 等）都会到达导出器；批处理、导出节奏（`scheduledDelayMillis`）、重试、队列上限，以及持续失败下的丢失策略，都是通过 `processor` 调节的 SDK 行为。该后端不实现 `flush()`：常规 flush 由批处理器负责。关闭期间，OTel 会先等待 `exporter.forceFlush()`，再等待受处理器 `exportTimeoutMillis` 限制的完成 promise；如果该传输 promise 始终不结算，本包会在 `shutdownTimeoutMillis` 到期时放弃等待，通过协调器记录已隔离的关闭失败，并让应用继续拆卸。该截止时间无法取消 SDK 传输，因此届时仍待处理的记录可能在进程退出时丢失。
 
 ## 哪些数据会离开本机
 
diff --git a/packages/session/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml
index ee9c7288b1..3d7e51ebe9 100644
--- a/packages/session/session-telemetry/README.i18n.yaml
+++ b/packages/session/session-telemetry/README.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 packages/telemetry/session-telemetry/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-telemetry/README.md
 README.md: 67d95bcc62bbf6783f8dcd11f0236d8c926b557b
-README.zh.md: 1ee0e0eb14bb06c8ac669cd417f2ee2ce46ca430
+README.zh.md: cb251587fc1ce651fe45e1961770a29508f6a1e6
diff --git a/packages/session/session-telemetry/README.zh.md b/packages/session/session-telemetry/README.zh.md
index 1ee0e0eb14..cb251587fc 100644
--- a/packages/session/session-telemetry/README.zh.md
+++ b/packages/session/session-telemetry/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端契约之后，任何上报 SDK 都无需变形即可满足该契约。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包（package）一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
+遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端约定之后，任何上报 SDK 都无需变形即可满足该约定。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
 
 ## 后端契约
 
diff --git a/packages/skill/tool-skill/README.i18n.yaml b/packages/skill/tool-skill/README.i18n.yaml
index b9aa148fd1..58ae7e6afd 100644
--- a/packages/skill/tool-skill/README.i18n.yaml
+++ b/packages/skill/tool-skill/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/skill/tool-skill/README.md
 README.md: b7309657d85a3d2a19de78a4ee6173d742519daa
-README.zh.md: f430f4027c917c5c9b97a56d1a7d7a617670b25c
+README.zh.md: 10834e13b4bfb745b4cd084ce41f616a8dd95807
diff --git a/packages/skill/tool-skill/README.zh.md b/packages/skill/tool-skill/README.zh.md
index f430f4027c..10834e13b4 100644
--- a/packages/skill/tool-skill/README.zh.md
+++ b/packages/skill/tool-skill/README.zh.md
@@ -36,7 +36,7 @@
 
 #### 模型看到的内容
 
-如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：用户显式的手势边界（下文的 pre-step 监听器）会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个臂——包括清空后的目录——都携带同一句话。
+如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：用户显式的手势边界（下文的 pre-step 监听器）会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个分支——包括清空后的目录——都携带同一句话。
 
 ##### Skill 目录模板
 
@@ -149,11 +149,11 @@ Load referenced resources only as needed.
 
 #### 模型看到的内容
 
-已认领用户消息中任意位置、以空白为界、指名工作区目录中某个用户可调用 skill 的 `/name` token，会把该 skill 的完整 `<skill_content>` 渲染（与上文结果模板完全相同的形态）作为 `user` 角色的指令上下文注入，追加在该步骤所有其他注入之后——背景在前，模型要着手处理的材料在最后。只扫描直接的用户输入，检查在已加载定义上进行，未知名称和用户不可调用的名称保持为普通行文。这是 `disable-model-invocation` skill 唯一的入口，目录和 `skill` 工具永不暴露这类 skill；目录的结尾一句会告诉模型遵循注入块，而不是重新加载它。
+已认领的用户消息中任意位置、以空白为界、指名工作区目录中某个用户可调用 skill 的 `/name` token，会把该 skill 的完整 `<skill_content>` 渲染（与上文结果模板完全相同的形态）作为 `user` 角色的指令上下文注入，追加在该步骤所有其他注入之后——背景在前，模型要着手处理的材料在最后。只扫描直接的用户输入，检查在已加载定义上进行，未知名称和用户不可调用的名称保持为普通行文。这是 `disable-model-invocation` skill 唯一的入口，目录和 `skill` 工具永不暴露这类 skill；目录的结尾一句会告诉模型遵循注入块，而不是重新加载它。
 
 #### Token 影响
 
-每次手势会把一份渲染后的 skill 正文作为注入上下文加进该轮次——尺寸与同一 skill 的工具结果相同，按用户的请求确定性地支付，而非由模型自行裁量。同一步骤内对同一 skill 的重复手势只注入一次。
+每次手势会把一份渲染后的 skill 正文作为注入上下文加进该轮次——其大小与同一 skill 的工具结果相同；这项成本会在用户请求时确定产生，而非由模型自行裁量。同一步骤内对同一 skill 的重复手势只注入一次。
 
 #### KV Cache 影响
 
diff --git a/packages/storage/storage/README.i18n.yaml b/packages/storage/storage/README.i18n.yaml
index 4378ae55ad..09fa051bac 100644
--- a/packages/storage/storage/README.i18n.yaml
+++ b/packages/storage/storage/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/storage/storage/README.md
 README.md: bf827220afe0d8b1cbc53b3a12e6d0034004e1d2
-README.zh.md: 6c1a5b4c05f665cdedd16fa67b47c87a04737e7b
+README.zh.md: 86b6994d74a727275e0bcaea2a83bd51f93b6ca1
diff --git a/packages/storage/storage/README.zh.md b/packages/storage/storage/README.zh.md
index 6c1a5b4c05..86b6994d74 100644
--- a/packages/storage/storage/README.zh.md
+++ b/packages/storage/storage/README.zh.md
@@ -8,7 +8,7 @@
 
 - `ctx.storage.backend`：名称 → 后端表。多个后端并排保持挂载（`json`、`sqlite`）；为消费方提供服务的后端由该消费方自身的配置决定（领域层的路由表），绝非中心的全局选择。`register()` 返回资源释放函数；注册重复名称或查找未知名称时都会明确报错。
 - `ctx.storage.mount(form, facility)`／`ctx.storage.form(form)`：数据形式挂载。`StorageForms` 可通过合并扩展；领域层合并 `domain`，并通过 `ctx.storage.domain` 访问。
-- 后端拥有一种介质，并公开其支持的数据形状**分面**。当前分面为 `kv`；其确切契约由 `src/backend.ts` 负责。
+- 后端拥有一种介质，并公开其支持的数据形状**分面**。当前分面为 `kv`；`src/backend.ts` 负责定义其确切约定。
 
 ## 模型体验
 
diff --git a/packages/subagent/subagent-inprocess/README.i18n.yaml b/packages/subagent/subagent-inprocess/README.i18n.yaml
index d2e12854be..9bfe1023ee 100644
--- a/packages/subagent/subagent-inprocess/README.i18n.yaml
+++ b/packages/subagent/subagent-inprocess/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-inprocess/README.md
 README.md: 67f0cf5dd1ecb18542af56953a0eaa40988aca0d
-README.zh.md: 7536d265584f1f6c69027cda6bc4d81ad88b7c7c
+README.zh.md: 0cb9008e52088c2a3c554a4ab6a45e2345b34a08
diff --git a/packages/subagent/subagent-inprocess/README.zh.md b/packages/subagent/subagent-inprocess/README.zh.md
index 7536d26558..0cb9008e52 100644
--- a/packages/subagent/subagent-inprocess/README.zh.md
+++ b/packages/subagent/subagent-inprocess/README.zh.md
@@ -4,7 +4,7 @@
 
 本包是两个进程内提供方共用的运行驱动器。spawn 不传入会话初始内容；fork 传入父 agent（智能体）已完成轮次的前缀。其余机制，包括深度、子 agent 创建、可选的子 agent 定制、结果读取、取消和 dispose（资源释放），都在此共用同一套实现。
 
-## 启动契约
+## 启动约定
 
 `startInProcessRun(request, options): Promise<SubagentRun>` 只在子 agent 发布到 `ctx.agents` 后才兑现。启动被拒绝时，agent 工厂的未发布创建事务已经完全停稳，因此调用方绝不会收到创建到一半的句柄。
 
@@ -14,7 +14,7 @@
 2. 直接调用 `parent.ctx.agents.create`，把必需的请求信号传入工厂的创建事务。
 3. 在该事务未发布的设置窗口中，安装请求的 persona、工具限制和结构化输出运行时。
 4. 发布子 agent，保留返回的 `AgentHandle`，并通过先调用 `child.followup(prompt)`、再调用 `child.whenIdle()` 来驱动一项任务。
-5. 从完整的自有子运行中读取子 agent 自身最后一条 assistant 消息和最终持久轮次原因，并排除任何 fork 初始内容。
+5. 从完整的自有子运行中读取子 agent 自身最后一条 assistant 消息和最终持久化的轮次原因，并排除任何 fork 初始内容。
 
 子 agent 会获得父 agent 的工作目录／会话谱系；除非 `request.agentOptions` 覆盖，否则还会继承父 agent 的提供方、模型和输出 token 上限。它获得全新的扁平注册作用域：父级所有权不会导入父 agent 的工具限制，也不会建立权限子集。
 
@@ -26,7 +26,7 @@
 
 必需的请求信号同时覆盖启动阶段和实时运行。发布前，`AgentCreationTransaction` 会观察该信号、回滚并拒绝。工厂返回前会移除仅用于创建阶段的监听器；驱动器随即再次检查信号，然后安装最小化的实时运行监听器，从而消除交接竞态。发布后，中止会取消子 agent。
 
-兑现后，调用方拥有该运行。提供方插件卸载不会撤销它。`dispose()` 会移除实时中止监听器、记录取消，并委托给返回的 `AgentHandle.dispose()`；后者通过可复用的完全停稳事务停止循环、移除 agent 和会话，并展开有作用域的注册。取消决定所有尚未完成的进行中结果，并将其报告为 `aborted`；已经完成的轮次仍保持完成状态。
+兑现后，调用方拥有该运行。提供方插件卸载不会撤销它。`dispose()` 会移除实时中止监听器、记录取消，并委托给返回的 `AgentHandle.dispose()`；后者通过经记忆化的完全停稳事务停止循环、移除 agent 和会话，并撤销作用域内的注册。取消流程会接管所有尚未完成的进行中结果，并将其报告为 `aborted`；已经完成的轮次仍保持完成状态。
 
 ## spawn 与 fork 输入
 
diff --git a/packages/support/llm-replay/README.i18n.yaml b/packages/support/llm-replay/README.i18n.yaml
index e120b5007b..47650ae4de 100644
--- a/packages/support/llm-replay/README.i18n.yaml
+++ b/packages/support/llm-replay/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/support/llm-replay/README.md
 README.md: a6c087778b8e64124590fb6be7a652b58e1b6343
-README.zh.md: 241edb9c9b2400519155ccd7161eb7f34b9f5bbe
+README.zh.md: 05dcf994962ba37b58cfb18a68f0d3819d34db0a
diff --git a/packages/support/llm-replay/README.zh.md b/packages/support/llm-replay/README.zh.md
index 241edb9c9b..05dcf99496 100644
--- a/packages/support/llm-replay/README.zh.md
+++ b/packages/support/llm-replay/README.zh.md
@@ -8,7 +8,7 @@
 
 ## fixture 的工作方式
 
-fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件包含每个 `StreamChunk`，因此按 `(turn, step)` 分组即可重建每次 agent-loop `stream()` 调用的分片序列。压缩（compaction）摘要器成功时，日志记录方式有所不同：当 `compact/summary` 携带 `llmStreamCall: true` 和完整的 `rawOutput` 时，回放会在该事件的位置重建一条规范成功流，其中每个块各使用一对 `block-start`/`block-end`，带上已记录的 usage（如有），并以 `stop` 终止。提供方增量的精确切分不属于持久压缩结果。不带该标记的 `rawOutput` 并不意味着发生了本地 LLM 调用，因为模板摘要器和远程摘要器即使未使用此上下文的适配器，也可能保留完整输出。
+fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件包含每个 `StreamChunk`，因此按 `(turn, step)` 分组即可重建每次 agent loop（智能体循环）的 `stream()` 调用的分片序列。压缩（compaction）摘要器成功时，日志记录方式有所不同：当 `compact/summary` 携带 `llmStreamCall: true` 和完整的 `rawOutput` 时，回放会在该事件的位置重建一条规范成功流，其中每个块各使用一对 `block-start`/`block-end`，带上已记录的用量（如有），并以 `stop` 终止。提供方增量的精确切分不属于持久压缩结果。不带该标记的 `rawOutput` 并不意味着发生了本地 LLM 调用，因为模板摘要器和远程摘要器即使未使用此上下文的适配器，也可能保留完整输出。
 
 因此，录制就是「运行一次真实 agent 并收集 `.jsonl`」，由快照 harness 完成；该插件本身不录制。fixture 的 `request/header` 内容可能被标记化为 `{{system}}`/`{{tools}}`（harness 会在一个场景中固定该内容，并清除其余场景中的内容）；回放不受影响，因为派生过程只读取 `assistant/chunk` 和 `compact/summary` 事件以及第 0 行的会话 header。
 
@@ -20,7 +20,7 @@ fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `as
 
 父 agent 委托给进程内 subagent 的场景会记录多个日志：父会话使用 `session.jsonl`，每个子会话各使用一个日志（`session.1.jsonl` 等）。每个 agent 都在同一上下文中作为独立的 `Session` 运行，因此回放必须为每个 agent 提供各自的脚本。
 
-回放根据发起调用的会话 id 为每次调用建立键（`GenerateOptions.sessionId` 由 agent loop（智能体循环）写入）。实时会话 id 每次运行时都会重新随机生成，绝不会等于记录中的 id，因此实时会话按**首次调用顺序**绑定到已记录脚本：脚本按 header 中的 `createdAt` 排序（父会话在前，因为它必须先开始流式输出才能委托）；第一个发起调用的实时会话取得第一个脚本，下一个新会话取得下一个脚本，以此类推。此后每个会话分别推进自己的游标。没有 `sessionId` 的调用视为一个绑定主脚本的匿名会话，因此单会话场景的行为与以前完全相同。不同实时会话的数量超过已记录脚本数时会明确报错。
+回放根据发起调用的会话 id 为每次调用建立键（`GenerateOptions.sessionId` 由 agent loop 写入）。实时会话 id 每次运行时都会重新随机生成，绝不会等于记录中的 id，因此实时会话按**首次调用顺序**绑定到已记录脚本：脚本按 header 中的 `createdAt` 排序（父会话在前，因为它必须先开始流式输出才能委托）；第一个发起调用的实时会话取得第一个脚本，下一个新会话取得下一个脚本，以此类推。此后每个会话分别推进自己的游标。没有 `sessionId` 的调用视为一个绑定主脚本的匿名会话，因此单会话场景的行为与以前完全相同。不同实时会话的数量超过已记录脚本数时会明确报错。
 
 ## 配置
 
diff --git a/packages/support/loader-smoke/README.i18n.yaml b/packages/support/loader-smoke/README.i18n.yaml
index 4e49d185bc..3860dd6af7 100644
--- a/packages/support/loader-smoke/README.i18n.yaml
+++ b/packages/support/loader-smoke/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/support/loader-smoke/README.md
 README.md: e5a33beb95f4e5940364cf309c8ea5fea60686f1
-README.zh.md: 1f3c6235175b3cfdcefec111eac39b2361b0e05b
+README.zh.md: 32c7af5bef050d6d46e91783468bdd0aa66e5ca0
diff --git a/packages/support/loader-smoke/README.zh.md b/packages/support/loader-smoke/README.zh.md
index 1f3c623517..32c7af5bef 100644
--- a/packages/support/loader-smoke/README.zh.md
+++ b/packages/support/loader-smoke/README.zh.md
@@ -12,7 +12,7 @@
 
 ## 模型体验
 
-无，因为测试 harness 仅提交调用方测试的普通用户任务，并将提示词和工具组装交由已加载的插件树负责。
+无，因为测试 harness 仅提交调用方测试的普通用户任务，并将提示词和工具组装交由已加载的树负责。
 
 #### KV Cache 影响
 
diff --git a/packages/tasks/tool-tasks/README.i18n.yaml b/packages/tasks/tool-tasks/README.i18n.yaml
index bdd840f0bd..65b1128efb 100644
--- a/packages/tasks/tool-tasks/README.i18n.yaml
+++ b/packages/tasks/tool-tasks/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/tool-tasks/README.md
 README.md: 6e8e889c2330d6991cb384674b011e4d2e988268
-README.zh.md: 9e54e2de69f36d5d5b70094cab12e5503eaeb5fd
+README.zh.md: 3b9dbd4f895eb38f0ffc7951169ff292da8603f1
diff --git a/packages/tasks/tool-tasks/README.zh.md b/packages/tasks/tool-tasks/README.zh.md
index 9e54e2de69..3b9dbd4f89 100644
--- a/packages/tasks/tool-tasks/README.zh.md
+++ b/packages/tasks/tool-tasks/README.zh.md
@@ -18,7 +18,7 @@
 
 ## 完成通知
 
-一项尚未报告的完成会把 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` 注入到精确 owner 的 next-step inbox。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。注入是等待后续 pre-step 领取的持久上下文，并非唤醒；取消或 owner 释放可能在领取前丢弃它。kill 或针对已终止任务的 read/wait 会把交付标为已报告，并抑制重复通知。
+一项尚未报告的完成会把 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` 注入到确切所有者的 next-step 收件箱。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。注入是等待后续 pre-step 领取的持久上下文，并非唤醒；取消或 owner 释放可能在领取前丢弃它。kill 或针对已终止任务的 read/wait 会把交付标为已报告，并抑制重复通知。
 
 ## 配置
 
diff --git a/packages/typert/README.i18n.yaml b/packages/typert/README.i18n.yaml
index cf44d9aace..3a061e43fd 100644
--- a/packages/typert/README.i18n.yaml
+++ b/packages/typert/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/README.md
 README.md: ad9f843e48be0e3be85921ed8fd3ca4e2c327160
-README.zh.md: 0d4be016b766178b54f7e269583fa4200e3eb24b
+README.zh.md: aae74bf89f657f50f4519b2f8a0628fd391f8de3
diff --git a/packages/typert/README.zh.md b/packages/typert/README.zh.md
index 0d4be016b7..aae74bf89f 100644
--- a/packages/typert/README.zh.md
+++ b/packages/typert/README.zh.md
@@ -7,5 +7,5 @@ Typert 将源代码分析、运行时存储和 Loader 发现机制分离。
 | 包 | 职责 | Cordis 键 |
 |---|---|---|
 | [`registry/`](registry/README.md) | 存储运行时包反射和 schema | `ctx.typert` |
-| [`loader/`](loader/README.md) | 发现 Loader 条目并注册生成的宿主产物 | 消费 `ctx.loader` 和 `ctx.typert` |
+| [`loader/`](loader/README.md) | 发现 Loader 条目并注册生成的宿主产物 | 使用 `ctx.loader`、`ctx.typert` |
 | [`generator/`](generator/README.md) | 从源代码类型生成运行时产物 | 构建时库 |
diff --git a/packages/typert/generator/README.i18n.yaml b/packages/typert/generator/README.i18n.yaml
index 583835a63b..55fa47ebc9 100644
--- a/packages/typert/generator/README.i18n.yaml
+++ b/packages/typert/generator/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/generator/README.md
 README.md: 38030c2b7e07c70ab79001086640b6581943dbd9
-README.zh.md: afa45820b7c7fba77704b86902c8752cd45777e6
+README.zh.md: 0cf0a365785775a9461e9744d29a0da482e54d14
diff --git a/packages/typert/generator/README.zh.md b/packages/typert/generator/README.zh.md
index afa45820b7..0cf0a36578 100644
--- a/packages/typert/generator/README.zh.md
+++ b/packages/typert/generator/README.zh.md
@@ -4,7 +4,7 @@
 
 TypeScript 项目分析器和模型驱动的 Typert 生成器。在生成任何产物之前，它会先将开发者编写的源类型树转换为独立于编译器的 `FaceModel` 和 `TypeGraph` 数据。静态分析无需 Cordis 即可消费该模型；各产物生成组件均不会接收 TypeScript 抽象语法树（AST）或类型检查器对象。
 
-分析器可以分别使用由 `tsconfig.host.json` 或 `tsconfig.client.json` 初始化的独立 `ts.Program`。直接 Project Reference 确定 compiler project 成员关系；带 `dshClient` 的普通单 project package 可按公开 subpath 同时贡献 Host 与 Client 运行时 face，显式引用 `tsconfig.host.json` 或 `tsconfig.client.json` 的拆分 project 则只贡献所选 face。`package.json#exports` 确定所有跨包公开边界，跨 face 的边只能来自源码导入或重新导出。NPM 依赖拥有的类型（包括 `@types` 包中的全局声明）继续以 `external` 引用表示，不会被展开。
+分析器可以分别使用由 `tsconfig.host.json` 或 `tsconfig.client.json` 初始化的独立 `ts.Program`。直接项目引用确定编译器 face 的成员归属，而包子路径确定 TypeRT 运行时 face 的贡献：带 `dshClient` 的普通单项目包可以同时贡献 Host 与 Client 运行时模型；只有通过 `tsconfig.host.json` 或 `tsconfig.client.json` 显式引用的拆分项目，才会被限制在相应 face。`package.json#exports` 确定所有跨包公开边界，跨 face 的边只能来自源码导入或重新导出。NPM 依赖拥有的类型（包括 `@types` 包中的全局声明）继续以 `external` 引用表示，不会被展开。
 
 ## 分析模型
 
@@ -18,7 +18,7 @@ TypeScript 项目分析器和模型驱动的 Typert 生成器。在生成任何
 
 `WorkspaceTypertGenerator` 会遍历从 Cordis `Context` 或 `Events` 扩充声明及显式 `@typert` 声明可达的包公开导出，以发现贡献方。发布产物时，它要求宿主侧产物位于 `lib/typert.host.{js,d.ts}` 并以 `package/typert` 暴露，客户端侧产物位于 `lib/typert.client.{js,d.ts}` 并以 `package/client/typert` 暴露。生成的声明将 `TYPERT` 暴露为 `unknown`，因此参与贡献的业务包无需依赖运行时注册表。
 
-各包可自行选择是否发布，未提供对应公开入口的业务包无需生成 Typert 产物。仓库的 Host tsdown 会以 `tsconfig.host.json` 为唯一 program 种子运行 workspace TypeRT 生成；它既生成 Host 反射产物，也把 Host Remote 契约投影为 Client 使用的 `typert.remote-client.*`。后续 Client tsdown 不启动 TypeRT，也不分析 `tsconfig.client.json`。静态消费方仍可直接调用 `WorkspaceAnalyzer`，显式选择 face 与包子集，并在不发布或加载运行时产物的情况下分批处理包。
+各包可自行选择是否发布，未提供对应公开入口的业务包无需生成 Typert 产物。仓库的 Host tsdown 会以 `tsconfig.host.json` 为唯一 program 种子运行 workspace TypeRT 生成；它既生成 Host 反射产物，也把 Host Remote 约定投影为 Client 使用的 `typert.remote-client.*`。后续 Client tsdown 不启动 TypeRT，也不分析 `tsconfig.client.json`。静态消费方仍可直接调用 `WorkspaceAnalyzer`，显式选择 face 与包子集，并在不发布或加载运行时产物的情况下分批处理包。
 
 ## 本仓库的 Cordis 投影
 
diff --git a/packages/typert/registry/README.i18n.yaml b/packages/typert/registry/README.i18n.yaml
index 011834c52d..f7193bdd9f 100644
--- a/packages/typert/registry/README.i18n.yaml
+++ b/packages/typert/registry/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/registry/README.md
 README.md: fa227b1c8faf1abd5a6492d4b8fe7d0c51ceeef1
-README.zh.md: 343e43aaca6ddaa0bb5e8d3130c85f37e4b4cb93
+README.zh.md: b3dd820c9a4f23917e85631bedaf68e4fc5803c1
diff --git a/packages/typert/registry/README.zh.md b/packages/typert/registry/README.zh.md
index 343e43aaca..b3dd820c9a 100644
--- a/packages/typert/registry/README.zh.md
+++ b/packages/typert/registry/README.zh.md
@@ -9,8 +9,8 @@
 ## 公开 API
 
 - `TypertRegistry` 是默认插件，并提供 `ctx.typert`。
-- `ctx.typert.lookups.register()` 注册业务包拥有的 wire 声明和默认 resolver；`configure()` 注册 Host 组合拥有、可异步执行的 resolver。两者生命周期独立，配置可以先于 provider，卸载配置会恢复默认策略。
-- `ctx.typert.contexts.registerHost()` 和 `configureHost()` 将同一所有权拆分应用于 scoped Context 身份；`registerClient()` 提供对应的 Client Context binder。
+- `ctx.typert.lookups.register()` 注册由业务包拥有的协议声明和默认解析器；`configure()` 注册由宿主组合拥有且可异步执行的解析器。两者的生命周期相互独立：配置可以先于提供方注册，卸载配置会恢复默认策略。
+- `ctx.typert.contexts.registerHost()` 和 `configureHost()` 对具作用域的上下文身份采用同样的所有权划分；`registerClient()` 提供对应的客户端上下文绑定器。
 - `register(contribution)` 会在提交任何内容之前拒绝格式错误的标识，以及重复的包与 face 组合键或 schema 键，随后返回 Cordis effect 提供的同一资源释放函数。
 - `get(key)`、`resolve(key)` 和 `list(filter?)` 查询当前有效的 schema。`resolve()` 能区分格式错误的键、未注册的包，以及已注册但未以该名称提供 schema 的包。
 - `getPackage(packageName, face?)` 和 `listPackages(filter?)` 查询生成的服务、事件和对象反射信息；默认 face 为 `host`。
diff --git a/packages/util/README.i18n.yaml b/packages/util/README.i18n.yaml
index 82e5f323d8..69dbd9afbb 100644
--- a/packages/util/README.i18n.yaml
+++ b/packages/util/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/README.md
 README.md: b84f2cbb88981aa2edbde65d8a711b28cc5b48e9
-README.zh.md: 44834041aad8d891b5dcaf63e02be5641e878cdc
+README.zh.md: b1d7ccf14059892d57fb01502f177e0e618058b1
diff --git a/packages/util/README.zh.md b/packages/util/README.zh.md
index 44834041aa..b1d7ccf140 100644
--- a/packages/util/README.zh.md
+++ b/packages/util/README.zh.md
@@ -7,8 +7,8 @@
 | 包 | 职责 |
 |---|---|
 | [`brand/`](brand/README.md) | 提供带名义品牌的类型 |
-| [`paths/`](paths/README.md) | 解析 Harness 数据根目录和共享路径 |
+| [`paths/`](paths/README.md) | 解析 harness（智能体框架）数据根目录和共享路径 |
 | [`timeout/`](timeout/README.md) | 提供截止时间和超时分类原语 |
-| [`retention/`](retention/README.md) | 限制保留文本和项目集合的大小 |
+| [`retention/`](retention/README.md) | 限制保留文本和项集合的大小 |
 | [`atomic-write/`](atomic-write/README.md) | 以原子方式替换文件 |
 | [`native-command/`](native-command/README.md) | 不经 shell 运行宿主原生命令 |
diff --git a/packages/util/native-command/README.i18n.yaml b/packages/util/native-command/README.i18n.yaml
index 237ad82299..50116d2ef0 100644
--- a/packages/util/native-command/README.i18n.yaml
+++ b/packages/util/native-command/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/native-command/README.md
 README.md: dd9d1ddaf817b2ff77ec0cd01710053e918b4296
-README.zh.md: 3ff8a392f2c511295adb0bf5f62b6e0527cbaea6
+README.zh.md: 339db7f3adb402193ef14247413b02f80b6f728d
diff --git a/packages/util/native-command/README.zh.md b/packages/util/native-command/README.zh.md
index 3ff8a392f2..339db7f3ad 100644
--- a/packages/util/native-command/README.zh.md
+++ b/packages/util/native-command/README.zh.md
@@ -8,7 +8,7 @@
 
 它是**库，不是服务或插件**：没有 `ctx`、不注册任何东西、不持有状态、不发事件。
 
-## 接口面
+## Surface
 
 ```ts
 import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
diff --git a/packages/util/retention/README.i18n.yaml b/packages/util/retention/README.i18n.yaml
index b9ba96e765..62be2bd3ea 100644
--- a/packages/util/retention/README.i18n.yaml
+++ b/packages/util/retention/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/retention/README.md
 README.md: 45c88e9fc2d8df98f935fd1c3b43c4622802bd2a
-README.zh.md: 0fcb76a8ae381d3e3da54e90640a38cba9de12e8
+README.zh.md: 9419245908d7331c9db24019f1181fcaed848060
diff --git a/packages/util/retention/README.zh.md b/packages/util/retention/README.zh.md
index 0fcb76a8ae..9419245908 100644
--- a/packages/util/retention/README.zh.md
+++ b/packages/util/retention/README.zh.md
@@ -57,7 +57,7 @@ import type {
 | `web_fetch` | `TextRetainer`，`head` 或 `headTail` | 提供方/资源上限保留为提供方事实；retainer 只提供保留文本和省略元数据。 |
 | `web_search` | `ItemRetainer<WebSearchSource>`，`head` | 当提供方返回的来源超过面向模型的结果应包含的数量时，标准化「来源已达上限」通知。 |
 
-`read` 仍不属于这个通用库。其 `read-render` 辅助工具负责文件专用的分页契约：`offset`/`limit`、行号、`totalLines`、偏移越界错误、每行预览截断，以及所选窗口的字节上限。这是行窗口渲染器。单个 `Omitted` 数量无法表示该窗口两侧。
+`read` 仍不属于这个通用库。其 `read-render` 辅助工具负责文件专用的分页约定：`offset`/`limit`、行号、`totalLines`、偏移越界错误、每行预览截断，以及所选窗口的字节上限。这是行窗口渲染器。单个 `Omitted` 数量无法表示该窗口两侧。
 
 ## 使用形态
 
diff --git a/python/README.i18n.yaml b/python/README.i18n.yaml
index 8dadf07570..249bf6bb76 100644
--- a/python/README.i18n.yaml
+++ b/python/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write python/README.md
 README.md: 27637edb9d4d5e8714fe379a00b6aae3af1a541f
-README.zh.md: dd020aa507de965815fc05f8423b87e766a2fb42
+README.zh.md: 9eed37aa10cc1bc1265938968d8084ce1ef840ce
diff --git a/python/README.zh.md b/python/README.zh.md
index dd020aa507..9eed37aa10 100644
--- a/python/README.zh.md
+++ b/python/README.zh.md
@@ -13,7 +13,7 @@
 
 ## 行为
 
-除非调用方选择显式通道，否则 SDK 会启动匹配的内置运行时。客户端负责选择通道和注入默认配置；运行时本身始终要求显式配置。完整的解析与配置契约分别见 [SDK 参考](sdk/README.md)和[运行时载体参考](sdk-runtime/README.md)。
+除非调用方选择显式通道，否则 SDK 会启动匹配的内置运行时。客户端负责选择通道和注入默认配置；运行时本身始终要求显式配置。完整的解析与配置约定分别由 [SDK 参考](sdk/README.md) 和 [运行时载体参考](sdk-runtime/README.md) 定义。
 
 ## 贡献者工作流
 
diff --git a/python/sdk/README.i18n.yaml b/python/sdk/README.i18n.yaml
index 7b3bd7895f..081b8eb17e 100644
--- a/python/sdk/README.i18n.yaml
+++ b/python/sdk/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write python/sdk/README.md
 README.md: 2d545688c58a2f1b755e647d7cda9555249e41c4
-README.zh.md: 653256584f06c0e63b725953f7f27bc91fc198cc
+README.zh.md: 3f1e15bf8a148efd18fe66272bec2e0b28de8d21
diff --git a/python/sdk/README.zh.md b/python/sdk/README.zh.md
index 653256584f..3f1e15bf8a 100644
--- a/python/sdk/README.zh.md
+++ b/python/sdk/README.zh.md
@@ -31,7 +31,7 @@ with DeepSeekHarness(
 
 `provider` 用于选择当前 Cordis 组合已注册的提供方路由；`model` 是该适配器解析的模型 ID。`max_tokens` 是可选的正整数，用于限制根 agent（智能体）及其进程内后代每次请求的输出 token；省略时由提供方默认值控制。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 `deepseek-official`。自定义组合可以挂载 `llm-pi-ai`，在其中配置各提供方的凭据与端点，再选择 pi-ai 已安装目录中的任意提供方/模型组合。
 
-`Session.run()` 拥有一个从提示词的持久 inbox 回执开始、到整个 agent 下一次进入 idle 为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在 idle 前参与其中。
+`Session.run()` 拥有一个从收件箱持久接收该提示词时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
 
 `HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 `Session.run()` 时，`RunResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`RunResult.events` 只包含根会话事件，因此后代消息不会覆盖根会话回复。底层 `session_prompt()` 会立即返回已排队消息的 `MessageId`；绕过 `Session.run()` 的调用方必须自行负责后续的活动边界。
 

From ffb1f187ee4b49e3d7f190424ecc3ea0ff3f2552 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 06:21:41 +0800
Subject: [PATCH 423/516] ci: keep Wine required beside native Windows

---
 ...rial-cross-platform-ci-reference.i18n.yaml |   4 +-
 ...7-21-serial-cross-platform-ci-reference.md |   6 +-
 ...1-serial-cross-platform-ci-reference.zh.md |   6 +-
 ...ortable-required-pull-request-ci.i18n.yaml |   4 +-
 ...07-23-portable-required-pull-request-ci.md |   8 +-
 ...23-portable-required-pull-request-ci.zh.md |   8 +-
 ...n-setup-for-symmetric-ci-caching.i18n.yaml |   4 +-
 ...m-action-setup-for-symmetric-ci-caching.md |   4 +-
 ...ction-setup-for-symmetric-ci-caching.zh.md |   4 +-
 ...8-native-windows-pull-request-ci.i18n.yaml |   4 +-
 ...26-08-08-native-windows-pull-request-ci.md |  28 +-
 ...08-08-native-windows-pull-request-ci.zh.md |  28 +-
 .github/AGENTS.md                             |   2 +-
 .github/workflows/ci.yml                      | 126 ++++++++-
 AGENTS.md                                     |   1 +
 package.json                                  |   1 +
 scripts/ci-workflow.spec.ts                   |  40 ++-
 scripts/wine-windows-gates.sh                 | 247 ++++++++++++++++++
 18 files changed, 451 insertions(+), 74 deletions(-)
 create mode 100755 scripts/wine-windows-gates.sh

diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
index dcb6e18e88..67b965e4aa 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.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 .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
-2026-07-21-serial-cross-platform-ci-reference.md: dfd762ad4d4eec61bc3a17d96865ccc4ac936ab3
-2026-07-21-serial-cross-platform-ci-reference.zh.md: 580340db2fbfc14458a4bbfbfa157db75e74e027
+2026-07-21-serial-cross-platform-ci-reference.md: dd41cdb51bd226b19bc6aca498c7713a3cc9a6b7
+2026-07-21-serial-cross-platform-ci-reference.zh.md: c72872d77f5d821b0fc203bda8bc1944e6929d73
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
index dfd762ad4d..dd41cdb51b 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
@@ -16,7 +16,7 @@ Real-kernel sandbox proofs require specific hosted operating systems and archite
 
 ## Decision
 
-[CI](../../../../.github/workflows/ci.yml) gives pull-request and master-push events complementary responsibilities. Pull requests run consolidated Linux and Windows jobs plus the Node compatibility and Python contracts on standard GitHub-hosted capacity. A push to `master` skips those jobs and runs four explicit references: `serial / linux`, `serial / macos`, and `serial / windows` on standard hosted runners, plus `serial / linux (self-hosted standby)` on the in-house `vm-backup` pool — the hot-standby drill that continuously re-proves the failover target described in the [failover runbook](2026-07-26-ci-failover-runbook.md). They intentionally duplicate their short checkout, runtime setup, and immutable install sequences instead of hiding the operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks.
+[CI](../../../../.github/workflows/ci.yml) gives pull-request and master-push events complementary responsibilities. Pull requests run consolidated Linux and Wine-hosted Windows jobs plus the Node compatibility and Python contracts on standard GitHub-hosted capacity; an independent native Windows job reports the complete Windows inventory without participating in the required aggregate. A push to `master` skips those jobs and runs four explicit references: `serial / linux`, `serial / macos`, and `serial / windows` on standard hosted runners, plus `serial / linux (self-hosted standby)` on the in-house `vm-backup` pool — the hot-standby drill that continuously re-proves the failover target described in the [failover runbook](2026-07-26-ci-failover-runbook.md). They intentionally duplicate their short checkout, runtime setup, and immutable install sequences instead of hiding the operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks.
 
 Each reference job runs `pnpm run check:ci` without any shard selector. `DSH_GATE_CONCURRENCY=1` makes the top-level aggregate execute one ready gate at a time; coverage, snapshot replay, built-bin smoke, and publication validation also receive worker counts of one. The reference jobs may run beside one another, but each host's repository gates are serial and complete. Linux installs bubblewrap before replaying snapshots, and Windows enables Developer Mode before installing the symlinked workspace.
 
@@ -28,13 +28,13 @@ The standalone [Sandbox](../../../../.github/workflows/sandbox.yml) workflow bel
 
 Master reference jobs are diagnostic and do not participate in the pull request's required `all checks passed` result. The CI and Sandbox workflows keep their cross-platform references on master pushes. Performance is evaluated from completed hosted-job timestamps and reported as a measurement; it is not encoded as a `timeout-minutes` value.
 
-The portable reference uses GitHub's standard `ubuntu-latest`, `macos-latest`, and `windows-2025` labels. The required pull-request Windows job also runs on standard `windows-2025` under the [native Windows decision](2026-08-08-native-windows-pull-request-ci.md); when enabled, `serial / windows` remains a second complete, unsharded native-kernel oracle. Required pull-request jobs use portable standard capacity under the [required-CI decision](2026-07-23-portable-required-pull-request-ci.md). Higher-core hosted runners remain manual benchmarks because a correctness path must remain runnable without repository-external runner configuration.
+The portable reference uses GitHub's standard `ubuntu-latest`, `macos-latest`, and `windows-2025` labels. The required pull-request Windows job runs under Wine on `ubuntu-latest`, while the independent pull-request native job uses standard `windows-2025` under the [dual Windows decision](2026-08-08-native-windows-pull-request-ci.md); when enabled, `serial / windows` remains a second complete, unsharded native-kernel oracle. Required pull-request jobs use portable standard capacity under the [required-CI decision](2026-07-23-portable-required-pull-request-ci.md). Higher-core hosted runners remain manual benchmarks because a correctness path must remain runnable without repository-external runner configuration.
 
 ## Alternatives considered
 
 - **Set each timeout equal to its latency target** - rejected because scheduling variance would cancel correct work and suppress the evidence needed to diagnose a regression.
 - **Trust only the concurrent primary inventory** - rejected because scheduling and validation share implementation assumptions; a serial aggregate is an independent completeness check.
-- **Run the serial references on every pull request** - rejected because they duplicate complete cross-platform aggregates and add macOS work to every change; the required jobs already execute the blocking Linux and Windows contracts.
+- **Run the serial references on every pull request** - rejected because they duplicate complete cross-platform aggregates and add macOS work to every change; the required jobs already execute the blocking Linux and Wine-hosted Windows contracts, and the independent native job supplies the complete Windows result.
 - **Run the real-kernel Sandbox matrix on every pull request** - rejected because its four statuses do not participate in branch protection, while repeated installs, Landlock builds, and macOS unit parity consume runner capacity without changing the merge verdict. The master run retains the platform and installed-launcher signal.
 - **Use one operating-system matrix** - rejected because three named jobs make the reference surface visible without another selection mechanism.
 - **Run the serial reference on larger runners** - rejected because both required CI and its independent reference must remain runnable when organization-owned pools cannot allocate jobs.
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
index 580340db2f..c72872d77f 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和 Windows 作业，以及 Node 兼容性与 Python 契约。向 `master` 推送时会跳过这些作业，改为运行四个显式参考作业：在标准托管运行器上的 `serial / linux`、`serial / macos` 和 `serial / windows`，以及在公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——后者是热备演练，持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。
+[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和由 Wine 承载的 Windows 作业，以及 Node 兼容性与 Python 契约；一个独立的原生 Windows 作业会报告完整的 Windows 清单，但不参与必需聚合流程。向 `master` 推送时会跳过这些作业，改为运行四个显式参考作业：在标准托管运行器上的 `serial / linux`、`serial / macos` 和 `serial / windows`，以及在公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——后者是热备演练，持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。
 
 每个参考作业均在不设置任何分片选择器的情况下运行 `pnpm run check:ci`。`DSH_GATE_CONCURRENCY=1` 使顶层聚合每次只执行一个已经就绪的门禁；覆盖率、快照回放、built-bin 冒烟测试和发布验证的 worker 数量也设为 1。各参考作业可以彼此并行，但每台主机上的仓库门禁都串行运行且完整执行。Linux 在回放快照前安装 bubblewrap，Windows 则在安装采用符号链接的工作区前启用开发人员模式。
 
@@ -28,13 +28,13 @@ macOS 参考流程使用 fork 进程运行常规 Vitest 项目。macOS arm64 上
 
 master 分支的参考作业仅用于诊断，不参与拉取请求所要求的 `all checks passed` 结果。CI 与 Sandbox 工作流把跨平台参考流程保留在 master 推送上。系统根据已完成托管作业的时间戳评估性能，并将其报告为测量结果，而不是写成 `timeout-minutes` 值。
 
-可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签。依据[原生 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)，拉取请求必需的 Windows 作业也在标准 `windows-2025` 上运行；`serial / windows` 启用时，仍作为第二个完整且未分片的原生内核标尺。依据[必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，拉取请求必需作业使用可移植的标准容量。更高核心数的托管运行器仍仅用于手动基准测试，因为正确性路径必须无需仓库外部的运行器配置即可运行。
+可移植的参考流程使用 GitHub 标准的 `ubuntu-latest`、`macos-latest` 和 `windows-2025` 标签。拉取请求必需的 Windows 作业在 `ubuntu-latest` 上通过 Wine 运行，而独立的拉取请求原生作业依据[双 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)使用标准 `windows-2025`；`serial / windows` 启用时，仍作为第二个完整且未分片的原生内核标尺。依据[必需 CI 决策](2026-07-23-portable-required-pull-request-ci.md)，拉取请求必需作业使用可移植的标准容量。更高核心数的托管运行器仍仅用于手动基准测试，因为正确性路径必须无需仓库外部的运行器配置即可运行。
 
 ## 曾考虑的替代方案
 
 - **将每个超时值设为相应延迟目标**：不予采纳，因为调度波动会中止原本正确的执行，并使诊断回归所需的证据无法产生。
 - **仅信任并发执行的主门禁清单**：不予采纳，因为调度逻辑与校验逻辑共享实现假设；串行聚合流程是一项独立的完整性检查。
-- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业会重复完整的跨平台聚合流程，并为每项改动增加 macOS 工作；必需作业已经执行阻塞性的 Linux 和 Windows 契约。
+- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业会重复完整的跨平台聚合流程，并为每项改动增加 macOS 工作；必需作业已经执行阻塞性的 Linux 和由 Wine 承载的 Windows 契约，而独立原生作业提供完整的 Windows 结果。
 - **在每个拉取请求上运行真实内核 Sandbox 矩阵**：不予采纳，因为它的四个状态不参与分支保护，而重复安装、Landlock 构建以及为保持平台一致而运行的 macOS 单元测试会消耗运行器容量，却不会改变合并裁决。master 上的运行保留平台与已安装 launcher 的信号。
 - **使用一个操作系统矩阵**：不予采纳，因为三个具名作业无需另一套选择机制，就能让参考流程的构成清晰可见。
 - **在大型运行器上运行串行参考流程**：不予采纳，因为当组织自有运行器池无法分配作业时，必需 CI 及其独立参考流程都必须仍可运行。
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
index 768e4298c7..d5368b8b45 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.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 .agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
-2026-07-23-portable-required-pull-request-ci.md: 11de2b1dcbbdbdd7f9423131cd84c2940ac9218d
-2026-07-23-portable-required-pull-request-ci.zh.md: 02f5d758e1259d6a8e7cba70e439775bd1df2b28
+2026-07-23-portable-required-pull-request-ci.md: b7c637408afa32611c4e70073ddec9aaabfba7f5
+2026-07-23-portable-required-pull-request-ci.zh.md: 78cf1cce55920f7153f6a9ca6673dd172174d8dc
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
index 11de2b1dcb..b7c637408a 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
@@ -12,9 +12,9 @@ Billing health, a runner definition's `Ready` state, and a large autoscaling cei
 
 ## Decision
 
-[CI](../../../../.github/workflows/ci.yml) runs the required primary Node 24 jobs, plus the stable `all checks passed` aggregate, on repo-restricted enterprise 32-core pools. The aggregate performs no checkout or repository gate, but sharing the enterprise pool prevents the required verdict from introducing a separate standard-hosted billing dependency after its substantive jobs have already succeeded. The required Windows job runs on standard `windows-2025` under native Windows for the blocking surfaces and broader observational inventory ([native Windows decision](2026-08-08-native-windows-pull-request-ci.md)). Standard `ubuntu-latest` jobs retain Node 22.19, Node 26, and Python SDK compatibility, and the serial references remain the complete unsharded cross-platform definitions. Those standard-hosted jobs keep the portable execution boundary observable without duplicating the primary inventory on every pull request.
+[CI](../../../../.github/workflows/ci.yml) runs the required primary Node 24 jobs, plus the stable `all checks passed` aggregate, on repo-restricted enterprise 32-core pools. The aggregate performs no checkout or repository gate, but sharing the enterprise pool prevents the required verdict from introducing a separate standard-hosted billing dependency after its substantive jobs have already succeeded. The required Windows job runs Windows Node under Wine on standard `ubuntu-latest` for the blocking surfaces; an independent native `windows-2025` job starts automatically but does not participate in the aggregate ([dual Windows decision](2026-08-08-native-windows-pull-request-ci.md)). Standard `ubuntu-latest` jobs retain Node 22.19, Node 26, and Python SDK compatibility, and the serial references remain the complete unsharded cross-platform definitions. Those standard-hosted jobs keep the portable execution boundary observable without duplicating the primary inventory on every pull request.
 
-The two Linux primary jobs, Node compatibility, Python SDK, and `windows node 24 / native complete` remain dependencies of `all checks passed`; branch protection continues to require `e2e` and `all checks passed`. There is no automatic fallback when a remaining enterprise Linux label cannot allocate: the standard jobs continue to report their own contracts, but they cannot manufacture the missing required result.
+The two Linux primary jobs, Node compatibility, Python SDK, and `windows node 24 / wine blocking` remain dependencies of `all checks passed`; `windows node 24 / native complete` is deliberately absent. Branch protection continues to require `e2e` and `all checks passed`. There is no automatic fallback when a remaining enterprise Linux label cannot allocate: the standard jobs continue to report their own contracts, but they cannot manufacture the missing required result.
 
 The [larger-runner decision](2026-07-22-evidence-based-larger-hosted-runners.md) owns the current primary topology and its measurements. The [serial cross-platform reference](2026-07-21-serial-cross-platform-ci-reference.md) remains the independent standard-hosted completeness check, and the manual larger-runner suites retain size comparisons without expanding the ordinary required matrix.
 
@@ -30,6 +30,6 @@ The [larger-runner decision](2026-07-22-evidence-based-larger-hosted-runners.md)
 
 ## Consequences
 
-Ordinary pull requests spend enterprise capacity on the Linux critical path while the native Windows job uses standard Windows allocation. A live exact-head run proves the same commands that branch protection consumes; queue delay is reported separately from each job's `startedAt` to `completedAt` execution interval.
+Ordinary pull requests spend enterprise capacity on the Linux critical path while the Wine job keeps the required Windows verdict on standard Linux allocation. The independent native job uses standard Windows allocation without delaying or changing the aggregate. A live exact-head run distinguishes the commands branch protection consumes from the separate diagnostic contract; queue delay is reported separately from each job's `startedAt` to `completedAt` execution interval.
 
-Standard compatibility and required Windows jobs remain useful when enterprise allocation is degraded, but they do not make a blocked required Linux job or aggregate green. Recovering Linux availability may require restoring the complete standard-hosted topology; changing a pool definition's status alone is insufficient evidence that it can receive work.
+Standard compatibility, required Wine, and diagnostic native Windows jobs remain useful when enterprise allocation is degraded, but they do not make a blocked required Linux job or aggregate green. Recovering Linux availability may require restoring the complete standard-hosted topology; changing a pool definition's status alone is insufficient evidence that it can receive work.
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
index 02f5d758e1..78cf1cce55 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `windows-2025` 上以原生 Windows 环境运行，覆盖阻断性检查范围和更广泛的观测性清单（[原生 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)）。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，串行参考流程仍是完整且未分片的跨平台定义。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
+[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `ubuntu-latest` 上通过 Wine 运行 Windows Node，覆盖阻断性检查范围；一个独立的原生 `windows-2025` 作业会自动启动，但不参与聚合流程（[双 Windows 决策](2026-08-08-native-windows-pull-request-ci.md)）。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，串行参考流程仍是完整且未分片的跨平台定义。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
 
-两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / native complete` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
+两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / wine blocking` 继续作为 `all checks passed` 的依赖项；`windows node 24 / native complete` 被刻意排除。分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
 
 当前主拓扑及其测量结果由[大型运行器决策](2026-07-22-evidence-based-larger-hosted-runners.md)记录。[跨平台串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)继续作为独立的标准托管完整性检查，手动大型运行器套件则保留规格比较，同时不扩大普通必需矩阵。
 
@@ -30,6 +30,6 @@ Status: implemented
 
 ## 后果
 
-普通拉取请求会将企业级运行器容量用于 Linux 关键路径，而原生 Windows 作业使用标准 Windows 运行器容量。一次实际的分支头精确运行能够证明分支保护使用的同一组命令；排队延迟与每个作业从 `startedAt` 到 `completedAt` 的执行区间分开报告。
+普通拉取请求会将企业级运行器容量用于 Linux 关键路径，而 Wine 作业让必需的 Windows 判定继续使用标准 Linux 运行器容量。独立原生作业使用标准 Windows 运行器容量，不会延迟或改变聚合流程。一次实际的分支头精确运行会区分分支保护采用的命令与单独的诊断契约；排队延迟与每个作业从 `startedAt` 到 `completedAt` 的执行区间分开报告。
 
-企业级运行器分配能力下降时，标准兼容性作业和必需的 Windows 作业仍能提供有用证据，但无法让受阻的必需 Linux 作业或聚合流程变绿。恢复 Linux 可用性时，可能需要恢复完整的标准托管拓扑；仅改变运行器池定义的状态，不足以证明它可以接收作业。
+企业级运行器分配能力下降时，标准兼容性作业、必需的 Wine 作业与诊断性原生 Windows 作业仍能提供有用证据，但无法让受阻的必需 Linux 作业或聚合流程变绿。恢复 Linux 可用性时，可能需要恢复完整的标准托管拓扑；仅改变运行器池定义的状态，不足以证明它可以接收作业。
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
index 224544c058..86a1e15688 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.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 .agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 6fba2ce3b508d9d6fc879460a63c0e12673bd866
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: d9da8a4abe13772f3cc282392c03cdea54726c01
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 3d35d532216c1644f0d65039574453752e9be7ac
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: 9e74a0149c9dcd17a88e9ff74a4b29fdc8916f32
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
index 6fba2ce3b5..3d35d53221 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
@@ -13,8 +13,8 @@ Outside `landlock-run.yml`, each workflow that installed pnpm hand-provisioned i
 `pnpm/action-setup@v4` is the only pnpm provisioning mechanism in CI: no workflow runs `corepack enable`. The root dev dependency on `@yarnpkg/cli-dist` separately supplies the modern Yarn CLI exercised by the generated-project e2e; package-manager coverage therefore does not inherit the runner image's Yarn Classic. Caching remains per-job policy on top of pnpm provisioning, in three deliberate shapes:
 
 - **Symmetric cache** (restore and save): `actions/setup-node` with `cache: pnpm` — `e2e.yml`, `docs-pages.yml`, `pi-ai-provider-e2e.yml`, `build-exe-for-python-sdk.yml`, and the node-compat and two benchmark jobs of `ci.yml`. The larger-runner benchmark keeps its store cache Linux-only through a conditional `cache:` input; the consolidated benchmark caches on both platforms.
-- **Restore-only / producer pairing** (hand-rolled `actions/cache` steps): the three enterprise-runner PR jobs restore without saving, keeping cache compression/upload off their latency-sensitive paths — an asymmetry `setup-node`'s cache cannot express. Each configures a store outside the action's replaceable install directory and resolves that path, matching the master-push serial-linux producer's path and exact key; the enterprise jobs skip restore during self-hosted failover because that VM's persistent store is already warm.
-- **Cache-less or persistent** (no store-cache action): the required native Windows job, native serial-windows and serial-macos, plus `sandbox.yml` install from a cold or runner-local store. Extracting the many-file pnpm store costs more than a clean Windows install; the self-hosted standby and failover jobs instead reuse their VM's persistent pnpm store without transferring a hosted cache archive.
+- **Restore-only / producer pairing** (hand-rolled `actions/cache` steps): the three enterprise-runner PR jobs and the Wine-based required Windows job restore without saving, keeping cache compression/upload off their latency-sensitive paths — an asymmetry `setup-node`'s cache cannot express. Each configures a store outside the action's replaceable install directory and resolves that path, matching the master-push serial-linux producer's path and exact key; the enterprise jobs skip restore during self-hosted failover because that VM's persistent store is already warm.
+- **Cache-less or persistent** (no store-cache action): the independent native Windows job, native serial-windows and serial-macos, plus `sandbox.yml` install from a cold or runner-local store. Extracting the many-file pnpm store costs more than a clean Windows install; the self-hosted standby and failover jobs instead reuse their VM's persistent pnpm store without transferring a hosted cache archive.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
index d9da8a4abe..9e74a0149c 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
@@ -13,8 +13,8 @@ Status: implemented
 `pnpm/action-setup@v4` 是 CI 中提供 pnpm 的唯一机制：没有任何工作流运行 `corepack enable`。根目录的 `@yarnpkg/cli-dist` 开发依赖另行提供 generated-project e2e 所运行的现代 Yarn CLI（命令行界面）；因此，用于包管理器覆盖率的 Yarn 不会沿用 runner 镜像里的 Yarn Classic。缓存仍是叠加在 pnpm 提供机制上的按作业政策，保持三种刻意的形态：
 
 - **对称缓存**（既恢复也保存）：带 `cache: pnpm` 的 `actions/setup-node`——`e2e.yml`、`docs-pages.yml`、`pi-ai-provider-e2e.yml`、`build-exe-for-python-sdk.yml`，以及 `ci.yml` 的 node-compat 与两个 benchmark 作业。larger-runner benchmark 通过条件化的 `cache:` 输入让 store 缓存仅限 Linux；consolidated benchmark 在两个平台上都启用缓存。
-- **只恢复不上传／生产者配对**（手写的 `actions/cache` 步骤）：企业 runner 上的三个 PR（Pull Request）作业只恢复不保存，把缓存压缩／上传挡在它们的延迟敏感路径之外——这种不对称是 `setup-node` 的缓存无法表达的。每个作业都在 action 可替换的安装目录之外配置 store，并解析该路径，从而与 master 推送触发的 serial-linux 生产者所用的路径和精确键匹配；企业作业在自托管故障切换期间跳过恢复，因为该 VM 的持久 store 已经预热。
-- **无缓存或持久化**（不使用 store 缓存 action）：必需的原生 Windows 作业、原生 serial-windows 和 serial-macos，以及 `sandbox.yml` 均从冷 store 或 runner 本地 store 安装。解压含有大量文件的 pnpm store，成本高于在 Windows 上进行一次全新安装；自托管热备与故障切换作业则复用其 VM 的持久 pnpm store，不传输托管缓存归档。
+- **只恢复不上传／生产者配对**（手写的 `actions/cache` 步骤）：企业 runner 上的三个 PR（Pull Request）作业和基于 Wine 的必需 Windows 作业只恢复不保存，把缓存压缩／上传挡在它们的延迟敏感路径之外——这种不对称是 `setup-node` 的缓存无法表达的。每个作业都在 action 可替换的安装目录之外配置 store，并解析该路径，从而与 master 推送触发的 serial-linux 生产者所用的路径和精确键匹配；企业作业在自托管故障切换期间跳过恢复，因为该 VM 的持久 store 已经预热。
+- **无缓存或持久化**（不使用 store 缓存 action）：独立的原生 Windows 作业、原生 serial-windows 和 serial-macos，以及 `sandbox.yml` 均从冷 store 或 runner 本地 store 安装。解压含有大量文件的 pnpm store，成本高于在 Windows 上进行一次全新安装；自托管热备与故障切换作业则复用其 VM 的持久 pnpm store，不传输托管缓存归档。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index b1b0079115..8cc2763444 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: 80fccabdc9ddebba2204732677da31363b74a184
-2026-08-08-native-windows-pull-request-ci.zh.md: 9d00f4fad6eb817968609c3af1f278cc6794e7c7
+2026-08-08-native-windows-pull-request-ci.md: e98de723dfe118a297a2e9074d94d52dd6dddc47
+2026-08-08-native-windows-pull-request-ci.zh.md: 02ad94b095c8fd1361c4b113d486f8091bb9cf5a
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 80fccabdc9..e98de723df 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -1,4 +1,4 @@
-# Agent Note: Native Windows pull-request CI
+# Agent Note: Dual Wine and native Windows pull-request CI
 
 Status: implemented
 
@@ -6,34 +6,36 @@ English | [中文](2026-08-08-native-windows-pull-request-ci.zh.md)
 
 ## Problem
 
-The required pull-request Windows verdict must protect behavior that depends on the operating system, not only toolchain branches selected by `process.platform`. The Wine lane executed Windows Node and PE binaries over a Linux kernel and case-sensitive ext4, required a hoisted dependency layout and host-created symlinks, and omitted NTFS, DACL, ConPTY, crash-durability, and the broader observational Windows inventory. With the native serial references disabled, ordinary CI had no real Windows-kernel signal.
+The required pull-request Windows verdict needs a fast win32 toolchain signal without making the aggregate wait for scarce Windows capacity. The Wine lane provides that critical-path signal but executes over a Linux kernel and case-sensitive ext4, requires a hoisted dependency layout and host-created symlinks, and cannot prove NTFS, DACL, ConPTY, crash-durability, or native process behavior. With the native serial references disabled, ordinary CI also needs an automatic real Windows-kernel result on every pull-request head even when that result is not part of branch protection.
 
 ## Decision
 
-The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) runs on GitHub's standard `windows-2025` image under native PowerShell. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete`. The stable `windows` job id remains a dependency of `all checks passed`; its display name is `windows node 24 / native complete`.
+The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that run the workspace build and production site. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
 
-The aggregate keeps workspace build and production-site failures blocking while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
+Every pull request also starts an independent `windows-native` job named `windows node 24 / native complete` on GitHub's standard `windows-2025` image. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete` under native PowerShell. The job is deliberately absent from `all-checks-passed.needs`: the aggregate neither waits for it nor changes conclusion because of it, while the native job retains its own unmasked success or failure result.
+
+The native gate keeps workspace build and production-site failures blocking inside its own job while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
 
 The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path.
 
 The next exact-head run exposed one remaining observational built-bin failure: its lifecycle fixtures used `process.kill()` or `subprocess.kill()` to send `SIGTERM`, which unconditionally terminates a Windows target instead of delivering the registered process event for graceful disposal. POSIX acceptance still sends the real signal. On Windows the fixture requests that same registered event from inside the child, directly for a self-terminating probe and through a marker for parent-controlled lifecycle cases, so the assembled shutdown and disposal path remains covered without asserting an operating-system facility that does not exist. That acceptance then exposed the underlying early-shutdown race: a signal could dispose the root after boot returned while fallback HMR watchers were mounting, and the resulting inactive-service error escaped as a boot failure. Post-boot setup now admits work only while the authoritative root fiber is active and contains a concurrent setup error only when the same invocation's recorded signal already owns shutdown; unrelated HMR failures remain loud.
 
-Wine-only infrastructure is absent from the supported workflow: there is no apt-cache producer, compatibility script, hoisted snapshot install, Windows Node download, or local `check:windows-wine` command. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) remains historical evidence for its measured latency and fidelity trade-offs, not a current execution path.
-
 ## Alternatives considered
 
-**Keep Wine on the required path.** Its warm wall clock was close to Linux CI and it selected win32 toolchain branches, but the compatibility-specific layout and kernel gaps could report green while supported native behavior was broken. Latency no longer outweighs that missing signal.
+**Make native Windows a dependency of `all checks passed`.** This gives the aggregate the highest-fidelity Windows verdict, but makes every merge wait for the longest hosted job and for Windows capacity. The independent result keeps that signal automatic without changing the existing required path.
 
-**Restore the pre-Wine workflow verbatim.** The old definition captured the right runner boundary but also carried then-current provisioning and topology assumptions. Reconstructing the native job against the current actions, pnpm setup, gate graph, and aggregate dependency avoids reviving obsolete machinery.
+**Run only Wine on pull requests.** Wine reaches the blocking win32 toolchain branches quickly, but can report green while a real NT, NTFS, PowerShell, process, or addon contract is broken.
 
-**Run native Windows only after merge.** A post-merge reference diagnoses portability regressions after they enter `master`; it cannot protect a pull request while those references are disabled or delayed.
+**Mark the native job `continue-on-error`.** That would make its check appear successful after a gate failure. Keeping an ordinary independent job preserves the diagnostic conclusion; omission from aggregate `needs` is the only non-blocking mechanism.
 
-**Use an organization-owned larger Windows runner.** Larger images can reduce wall clock, but a required correctness path would then depend on repository-external labels and allocation. Standard `windows-2025` is the portable recovery boundary; larger runners remain benchmark targets.
+**Run native Windows only after merge.** A post-merge reference diagnoses portability regressions after they enter `master`; it does not give reviewers an exact-head native result.
+
+**Use an organization-owned larger Windows runner.** Larger images can reduce wall clock, but the diagnostic path would then depend on repository-external labels and allocation. Standard `windows-2025` is portable; larger runners remain benchmark targets.
 
 ## Consequences
 
-Pull requests receive a real NT kernel, NTFS, PowerShell, Windows process, and native addon signal before the aggregate can pass. The job is slower than the Wine compatibility lane and can queue on Windows capacity, but its green result now describes the supported host rather than an approximation.
+Wine preserves the required aggregate's existing critical path and job identity. Native Windows can still be pending or red when `all checks passed` turns green, so branch protection consumes Wine while reviewers and follow-up automation consume the separate native result.
 
-The native lane is also a portability inventory: its exact-head acceptance requires every blocking gate to pass and the final summary to contain no non-blocking failure. That distinction caught path contracts which a successful wrapper conclusion alone would have concealed.
+Every pull request nevertheless receives a real NT kernel, NTFS, PowerShell, Windows process, and native addon signal. The native job is slower than Wine and duplicates setup plus the two blocking builds, but it also executes the portability inventory that exposed path, watcher, and lifecycle defects hidden by the compatibility lane.
 
-Removing the Wine cache producer and local script deletes a separate install topology and its recurring compatibility failures. Native coverage and snapshots remain a named gap rather than being implied by the job name; they require their own tested contract before becoming part of this required lane.
+Maintainers must preserve two intentional execution topologies: the Wine snapshot uses Linux installation plus a hoisted layout to reach win32 binaries, while the native job uses the immutable workspace on Windows. A failure unique to either job must be classified against that boundary rather than weakened or silently skipped.
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 9d00f4fad6..02ad94b095 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 原生 Windows 拉取请求 CI
+# Agent Note: Wine 与原生 Windows 双通道拉取请求 CI
 
 Status: implemented
 
@@ -6,34 +6,36 @@ Status: implemented
 
 ## 问题
 
-拉取请求必需的 Windows 判定必须为依赖操作系统的行为提供保障，而不能只覆盖由 `process.platform` 选择的工具链分支。Wine 通道在 Linux 内核与区分大小写的 ext4 之上执行 Windows Node 和 PE 二进制文件，要求采用 hoisted 依赖布局和由宿主侧创建的符号链接，也没有覆盖 NTFS、DACL、ConPTY、崩溃持久性与更广泛的观测性 Windows 清单。原生串行参考流程停用期间，常规 CI 没有任何真实的 Windows 内核信号。
+拉取请求必需的 Windows 判定既需要快速的 win32 工具链信号，也不能让聚合流程等待稀缺的 Windows 容量。Wine 通道提供这项关键路径信号，但它运行在 Linux 内核与区分大小写的 ext4 之上，要求采用 hoisted 依赖布局和由宿主侧创建的符号链接，且无法证明 NTFS、DACL、ConPTY、崩溃持久性或原生进程行为。原生串行参考流程停用期间，即使真实 Windows 内核结果不属于分支保护，常规 CI 也需要针对每个拉取请求分支头自动产出该结果。
 
 ## 决策
 
-[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业在 GitHub 标准 `windows-2025` 镜像上使用原生 PowerShell 运行。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并运行 `pnpm run check:ci:windows-complete`。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项；其显示名称为 `windows node 24 / native complete`。
+[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
 
-聚合作业继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
+每个拉取请求还会在 GitHub 标准 `windows-2025` 镜像上启动一个独立的 `windows-native` 作业，名称为 `windows node 24 / native complete`。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并在原生 PowerShell 下运行 `pnpm run check:ci:windows-complete`。该作业被刻意排除在 `all-checks-passed.needs` 之外：聚合流程既不等待它，也不会因它改变结论；原生作业则保留自身未被掩盖的成功或失败结果。
+
+原生门禁在其自身作业内继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
 
 首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。
 
 下一次分支头精确运行暴露出观测项中剩余的一项 built-bin 故障：其生命周期 fixture（测试前置数据）通过 `process.kill()` 或 `subprocess.kill()` 发送 `SIGTERM`；在 Windows 上，这种调用会无条件终止目标进程，而不会交付为优雅释放所注册的进程事件。POSIX 验收仍发送真实信号。在 Windows 上，fixture 改为从子进程内部请求同一个已注册事件：自终止探测直接请求，由父进程控制的生命周期场景则通过标记请求；因此，完整组装后的关闭与释放路径仍得到覆盖，也无需断言操作系统提供了本不存在的信号机制。该项验收随即暴露出底层的提前关闭竞态：boot 返回后，回退 HMR watcher 仍在挂载，此时信号可能对根 fiber 执行 dispose（资源释放），由此产生的服务未激活错误会逸出并被报告为 boot 失败。boot 后 setup 现在只会在权威根 fiber 仍处于活跃状态时接纳工作；只有当本次调用所记录的信号已取得关闭流程所有权时，才会隔离并发 setup 错误，无关的 HMR 故障仍会响亮失败。
 
-受支持的工作流不含 Wine 专属基础设施：不存在 apt 缓存生产者、兼容性脚本、对仓库快照执行的 hoisted 安装、Windows Node 下载或本地 `check:windows-wine` 命令。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)仍作为其实测延迟与保真度取舍的历史证据，而非当前执行路径。
-
 ## 曾考虑的替代方案
 
-**在必需路径上保留 Wine。** 其热运行墙钟时间接近 Linux CI，也会选择 win32 工具链分支；但兼容性专属布局和内核缺口可能在受支持的原生行为已经损坏时仍报告绿灯。这项延迟收益不足以抵消该信号缺失的代价。
+**让原生 Windows 成为 `all checks passed` 的依赖项。** 这会为聚合流程提供保真度最高的 Windows 判定，但也会让每次合并等待最长的托管作业与 Windows 容量。独立结果能让该信号保持自动产生，而不改变现有必需路径。
 
-**逐字恢复 Wine 之前的工作流。** 旧定义确实捕获了正确的运行器边界，但也携带了当时的供应方式与拓扑假设。按照当前 action、pnpm 设置、门禁图和聚合依赖关系重新构建原生作业，可以避免重新引入过时机制。
+**只在拉取请求上运行 Wine。** Wine 能快速触达阻断性的 win32 工具链分支，但即使真实 NT、NTFS、PowerShell、进程或原生插件契约已经损坏，也可能报告绿灯。
 
-**只在合并后运行原生 Windows。** 合并后的参考流程只能在可移植性回归进入 `master` 后进行诊断；当这些参考流程被停用或延迟时，无法在拉取请求阶段提供保护。
+**将原生作业标记为 `continue-on-error`。** 门禁失败后，该设置会让其检查显示为成功。保留普通独立作业可维持诊断结论；仅从聚合流程的 `needs` 中省略它，才是不阻断的机制。
 
-**使用组织自有的大型 Windows 运行器。** 更大规格的运行器镜像可以缩短墙钟时间，但必需的正确性路径将因此依赖仓库外部的运行器标签与分配能力。标准 `windows-2025` 是可移植恢复边界；大型运行器仍作为基准测试目标。
+**只在合并后运行原生 Windows。** 合并后的参考流程只能在可移植性回归进入 `master` 后进行诊断；它无法向评审者提供分支头精确的原生结果。
+
+**使用组织自有的大型 Windows 运行器。** 更大规格的运行器镜像可以缩短墙钟时间，但诊断路径将因此依赖仓库外部的运行器标签与分配能力。标准 `windows-2025` 具备可移植性；大型运行器仍作为基准测试目标。
 
 ## 后果
 
-在聚合作业通过之前，拉取请求会获得来自真实 NT 内核、NTFS、PowerShell、Windows 进程和原生插件的信号。该作业比 Wine 兼容性通道更慢，也可能因 Windows 容量而排队，但其绿灯结果描述的是受支持的宿主，而非近似环境。
+Wine 保留必需聚合流程现有的关键路径和作业身份。`all checks passed` 变绿时，原生 Windows 仍可能处于待处理或红灯状态，因此分支保护采用 Wine 结果，而评审者和后续自动化采用独立的原生结果。
 
-原生通道也是一份可移植性清单：其分支头精确验收要求每个阻断门禁都通过，且最终汇总中不包含任何非阻断失败。这一区分发现了路径契约问题；若只看包装层的成功结论，这些问题本会被掩盖。
+尽管如此，每个拉取请求都会获得来自真实 NT 内核、NTFS、PowerShell、Windows 进程和原生插件的信号。原生作业比 Wine 更慢，并重复执行设置流程和两项阻断构建，但它也会运行那份可移植性清单；兼容性通道隐藏的路径、watcher 与生命周期缺陷正是由该清单暴露。
 
-移除 Wine 缓存生产者和本地脚本后，独立的安装拓扑及其反复出现的兼容性故障也随之消失。原生 Windows 覆盖率与快照仍是明确列出的缺口，不会仅由作业名称暗示已经纳入；二者都必须先建立各自经过测试的契约，才能成为该必需通道的一部分。
+维护者必须保留两种有意设计的执行拓扑：Wine 快照使用 Linux 安装加 hoisted 布局来触达 win32 二进制文件，而原生作业在 Windows 上使用不可变工作区。任一作业独有的失败都必须依据该边界分类，不得削弱或静默跳过。
diff --git a/.github/AGENTS.md b/.github/AGENTS.md
index c95b85e8e2..c18f5b5948 100644
--- a/.github/AGENTS.md
+++ b/.github/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — GitHub Actions
 
-Run jobs on Windows runners (`windows-*` labels) under native `pwsh`.
+Run jobs on Windows runners (`windows-*` labels) under native `pwsh`. The pull-request `windows` job is the deliberate exception: it runs Windows Node under Wine on hosted Linux and blocks `all checks passed`; `windows-native` runs automatically on `windows-2025` but reports independently — see the [dual-lane Agent Note](../.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md).
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0e96d50e50..c6e015da60 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -300,12 +300,121 @@ jobs:
       - name: Run complete keyless Python suite
         run: uv run --python 3.10 --group test --project python/sdk pytest
 
-  # One standard Windows box shares setup across the required build/site checks
-  # and the observational portability inventory. Serial worker bounds keep this
-  # recovery path portable; Linux owns duplicate lint, coverage, and snapshots.
-  # See the native-Windows pull-request CI decision:
+  # The required pull-request Windows signal: the two blocking win32 surfaces
+  # (workspace build, production site) execute with real, checksum-verified
+  # Windows Node under Wine on standard hosted Linux. The independent
+  # windows-native job below keeps the complete native-kernel inventory —
+  # including the observational portability gates this lane does not run —
+  # on real windows-2025. This job only provisions runner state (caches,
+  # apt); scripts/wine-windows-gates.sh owns the gate logic and is the same
+  # script the optional local gate `pnpm run check:windows-wine` runs.
+  # Current topology and fidelity limits live in
   # .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
   windows:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    name: windows node 24 / wine blocking
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+        with:
+          dest: ${{ runner.temp }}/setup-pnpm
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+
+      - name: Configure pnpm store path
+        id: pnpm-store
+        run: |
+          store_root="$HOME/.local/share/pnpm/store"
+          echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV"
+          store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)
+          echo "path=$store_path" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache/restore@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
+
+      # Master's wine-apt-cache job seeds the default-branch scope every pull
+      # request can read; a save from this job only reaches reruns of the
+      # same merge ref.
+      - name: Compose Wine apt cache key
+        id: wine-cache-key
+        run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/wine-debs
+          key: ${{ steps.wine-cache-key.outputs.key }}
+
+      # Runner provisioning only — a developer machine installs Wine through
+      # its own package manager; the gate script assumes a wine binary and
+      # fails loud without one. Wine from the apt cache when present; else
+      # download the full dependency closure once and keep it for the next
+      # run. The `wine` dispatcher package (not bare `wine64`) is what puts a
+      # binary on PATH.
+      - name: Install Wine
+        run: |
+          if compgen -G "$HOME/wine-debs/*.deb" > /dev/null; then
+            sudo apt-get install -y --no-install-recommends "$HOME"/wine-debs/*.deb
+          else
+            sudo apt-get update
+            sudo apt-get install -y --no-install-recommends --download-only wine
+            mkdir -p "$HOME/wine-debs"
+            cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/" 2>/dev/null || true
+            sudo apt-get install -y --no-install-recommends wine
+          fi
+
+      - name: Run the Wine Windows gates
+        run: bash scripts/wine-windows-gates.sh
+
+      - name: Shut down wineserver
+        if: always()
+        run: wineserver -k 2>/dev/null || true
+
+  # Master seeds the Wine apt-archive cache in the default-branch scope,
+  # which every pull request's windows job can restore; saves from
+  # pull-request runs are scoped to their own merge ref and help nobody
+  # else. Runs in seconds when the image version already has a cache.
+  wine-apt-cache:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    name: wine apt cache
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Compose Wine apt cache key
+        id: wine-cache-key
+        run: echo "key=wine-debs-${ImageOS:-linux}-${ImageVersion:-v0}" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache@v4
+        id: wine-cache
+        with:
+          path: ~/wine-debs
+          key: ${{ steps.wine-cache-key.outputs.key }}
+
+      - name: Download the Wine dependency closure
+        if: steps.wine-cache.outputs.cache-hit != 'true'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends --download-only wine
+          mkdir -p "$HOME/wine-debs"
+          cp /var/cache/apt/archives/*.deb "$HOME/wine-debs/"
+          du -sh "$HOME/wine-debs"
+
+  # Every pull request also gets a real Windows-kernel signal. This job keeps
+  # its own unmasked conclusion but is deliberately absent from
+  # all-checks-passed.needs, so it never delays or changes that required verdict.
+  # See the dual Wine/native pull-request CI decision:
+  # .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+  windows-native:
     if: github.event_name == 'pull_request'
     runs-on: windows-2025
     name: windows node 24 / native complete
@@ -337,7 +446,7 @@ jobs:
         shell: pwsh
         run: pnpm install --frozen-lockfile
 
-      - name: Run blocking and observational Windows gates concurrently
+      - name: Run complete native Windows gate inventory
         shell: pwsh
         run: pnpm run check:ci:windows-complete
 
@@ -742,9 +851,10 @@ jobs:
   # Single stable required check for branch protection: require "all checks
   # passed" instead of enumerating matrix legs whose names change as lanes and
   # node versions evolve. Every blocking job in THIS workflow must be listed in
-  # `needs`; observational Windows gates share the required Windows job but are
-  # marked non-blocking inside run-gates. (`needs` cannot reach across workflow
-  # files; e2e.yml stays its own check.)
+  # `needs`. The required Wine job is listed as `windows`; `windows-native` is
+  # deliberately absent so its independent result never delays or changes this
+  # verdict. (`needs` cannot reach across workflow files; e2e.yml stays its own
+  # check.)
   # `if: always()` is load-bearing: without it a failed dependency
   # would SKIP this job, and GitHub counts a skipped required check as passing
   # — so this job always runs and fails on any non-success result, including
diff --git a/AGENTS.md b/AGENTS.md
index ed9212b6d4..dcb001768e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -68,6 +68,7 @@ pnpm run typecheck
 pnpm run lint
 pnpm run duplication    # cross-file TypeScript clone detection
 pnpm run build          # tsc emits lib/types, tsdown bundles runtime
+pnpm run check:windows-wine  # ONLY when diagnosing a known Windows failure (needs wine); CI owns this signal
 pnpm run hygiene        # knip + publint + workspace constraints + NodeNext consumer check
 pnpm run doc-sync       # all documentation gates; leaf list in scripts/run-gates.ts
 pnpm run website:build  # VitePress build (doubles as dead-link check)
diff --git a/package.json b/package.json
index ed6d915d6e..864814ffe6 100644
--- a/package.json
+++ b/package.json
@@ -57,6 +57,7 @@
     "check:ci:windows-blocking": "tsx scripts/run-gates.ts ci-windows-blocking",
     "check:ci:windows-complete": "tsx scripts/run-gates.ts ci-windows-complete",
     "check:ci:windows-observational": "tsx scripts/run-gates.ts ci-windows-observational",
+    "check:windows-wine": "bash scripts/wine-windows-gates.sh",
     "check:node-compat": "tsx scripts/run-gates.ts node-compat",
     "knip": "knip --treat-config-hints-as-errors",
     "publint": "tsx scripts/publint-all.ts",
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index 558dc15548..05edaaef55 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -27,26 +27,40 @@ describe('CI workflow', () => {
     }
   })
 
-  it('runs the required Windows contract on a native hosted runner', () => {
+  it('keeps Wine blocking while native Windows reports independently', () => {
     const workflow = loadWorkflow('.github/workflows/ci.yml')
-    if (!isRecord(workflow.jobs) || !isRecord(workflow.jobs.windows)) {
-      throw new TypeError('CI workflow must define the windows job')
+    if (!isRecord(workflow.jobs)
+      || !isRecord(workflow.jobs.windows)
+      || !isRecord(workflow.jobs['windows-native'])
+      || !isRecord(workflow.jobs['all-checks-passed'])) {
+      throw new TypeError('CI workflow must define Wine, native Windows, and aggregate jobs')
     }
 
     const windows = workflow.jobs.windows
-    if (!Array.isArray(windows.steps)) throw new TypeError('windows job must define steps')
-    const steps: unknown[] = windows.steps
-    const commandSteps = steps.filter((step): step is Record<string, unknown> & { run: string } => (
+    const windowsNative = workflow.jobs['windows-native']
+    const aggregate = workflow.jobs['all-checks-passed']
+    if (!Array.isArray(windows.steps) || !Array.isArray(windowsNative.steps) || !Array.isArray(aggregate.needs)) {
+      throw new TypeError('Windows jobs must define steps and the aggregate must define needs')
+    }
+    const nativeCommandSteps = windowsNative.steps.filter((step): step is Record<string, unknown> & { run: string } => (
       isRecord(step) && typeof step.run === 'string'
     ))
 
-    expect(windows['runs-on']).toBe('windows-2025')
-    expect(windows.name).toBe('windows node 24 / native complete')
-    expect(commandSteps).toHaveLength(3)
-    expect(commandSteps.every(step => step.shell === 'pwsh')).toBe(true)
-    expect(commandSteps.map(step => step.run)).toContain('pnpm run check:ci:windows-complete')
-    expect(JSON.stringify(windows)).not.toMatch(/wine/i)
-    expect(workflow.jobs).not.toHaveProperty('wine-apt-cache')
+    expect(windows['runs-on']).toBe('ubuntu-latest')
+    expect(windows.name).toBe('windows node 24 / wine blocking')
+    expect(windows.if).toBe("github.event_name == 'pull_request'")
+    expect(JSON.stringify(windows)).toContain('bash scripts/wine-windows-gates.sh')
+    expect(workflow.jobs).toHaveProperty('wine-apt-cache')
+    expect(windowsNative['runs-on']).toBe('windows-2025')
+    expect(windowsNative.name).toBe('windows node 24 / native complete')
+    expect(windowsNative.if).toBe("github.event_name == 'pull_request'")
+    expect(windowsNative).not.toHaveProperty('continue-on-error')
+    expect(nativeCommandSteps).toHaveLength(3)
+    expect(nativeCommandSteps.every(step => step.shell === 'pwsh')).toBe(true)
+    expect(nativeCommandSteps.map(step => step.run)).toContain('pnpm run check:ci:windows-complete')
+    expect(JSON.stringify(windowsNative)).not.toMatch(/wine/i)
+    expect(aggregate.needs).toContain('windows')
+    expect(aggregate.needs).not.toContain('windows-native')
   })
 })
 
diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
new file mode 100755
index 0000000000..9bf904a767
--- /dev/null
+++ b/scripts/wine-windows-gates.sh
@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# Run the blocking Windows gates (workspace build, production site) with real
+# win-x64 Node.js under Wine — the same script the pull-request `windows` job
+# in ci.yml executes and the optional local gate `pnpm run check:windows-wine`
+# wraps. Owning rationale and fidelity limits:
+# .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+#
+# The working tree is never mutated: tracked plus untracked-unignored files
+# are snapshotted into a scratch directory, the Wine-specific pnpm overrides
+# (hoisted layout, win32-x64 platform packages) are appended to the SNAPSHOT's
+# pnpm-workspace.yaml, and the install and gates run there against the shared
+# pnpm store. The Wine prefix and the checksum-verified Windows Node zip
+# persist in .cache/wine-windows/ so reruns skip provisioning.
+#
+# Environment: DSH_WINE_NODE_MAJOR (default $PRIMARY_NODE_VERSION, then 24)
+# picks the Windows Node line; DSH_WINE_GATE_CACHE_DIR relocates the cache;
+# DSH_WINE_GATE_KEEP=1 preserves the scratch tree for inspection.
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+node_major="${DSH_WINE_NODE_MAJOR:-${PRIMARY_NODE_VERSION:-24}}"
+cache_dir="${DSH_WINE_GATE_CACHE_DIR:-$repo_root/.cache/wine-windows}"
+
+export WINEDEBUG='-all'
+export WINEARCH=win64
+# Skip Wine Mono / Gecko installers: Node needs neither.
+export WINEDLLOVERRIDES='mscoree,mshtml='
+export WINEPREFIX="$cache_dir/prefix"
+
+# ---- preflight: fail loud before any expensive work --------------------
+wine_bin=''
+for candidate in "$(command -v wine || true)" "$(command -v wine64 || true)" /usr/lib/wine/wine64; do
+  if [ -n "$candidate" ] && [ -x "$candidate" ]; then wine_bin="$candidate"; break; fi
+done
+# GNU coreutils sha256sum on Linux; perl shasum ships with macOS. Both
+# accept the same "<hash>  <file>" --check input.
+checksum_tool=''
+if command -v sha256sum > /dev/null; then
+  checksum_tool='sha256sum'
+elif command -v shasum > /dev/null; then
+  checksum_tool='shasum'
+fi
+missing=()
+[ -n "$wine_bin" ] || missing+=('wine (apt: wine | brew: wine-stable)')
+command -v curl > /dev/null || missing+=('curl')
+command -v unzip > /dev/null || missing+=('unzip')
+[ -n "$checksum_tool" ] || missing+=('sha256sum or shasum (apt: coreutils | macOS ships shasum)')
+if ! command -v pnpm > /dev/null; then corepack enable > /dev/null 2>&1 || true; fi
+command -v pnpm > /dev/null || missing+=('pnpm (corepack enable)')
+if (( ${#missing[@]} > 0 )); then
+  printf 'wine-windows-gates: missing required tool: %s\n' "${missing[@]}" >&2
+  exit 1
+fi
+
+# Verify file $2 against SHA-256 hex $1 with whichever tool preflight found.
+verify_sha256() {
+  case "$checksum_tool" in
+    sha256sum) printf '%s  %s\n' "$1" "$2" | sha256sum --check - > /dev/null ;;
+    shasum) printf '%s  %s\n' "$1" "$2" | shasum -a 256 --check - > /dev/null ;;
+  esac
+}
+
+scratch="$(mktemp -d "${TMPDIR:-/tmp}/dsh-wine-gates.XXXXXX")"
+cleanup() {
+  wineserver -k > /dev/null 2>&1 || true
+  if [ "${DSH_WINE_GATE_KEEP:-0}" = '1' ]; then
+    echo "wine-windows-gates: scratch tree kept at $scratch"
+  else
+    rm -rf "$scratch"
+  fi
+}
+trap cleanup EXIT
+mkdir -p "$cache_dir" "$scratch/logs"
+
+# ---- provision Windows Node, boot Wine, snapshot + install concurrently ----
+provision_node() {
+  # Latest release of the primary line, checksum-verified against the same
+  # dist directory. Offline runs fall back to the newest cached zip, loudly.
+  local version zip
+  version="$(curl -fsSL --max-time 30 https://nodejs.org/dist/index.json 2> /dev/null \
+    | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const v=JSON.parse(d).find(r=>r.version.startsWith('v$node_major.'));if(v)console.log(v.version)})" \
+    || true)"
+  if [ -n "$version" ]; then
+    zip="$cache_dir/node-$version-win-x64.zip"
+    if [ ! -f "$zip" ]; then
+      curl -fsSL -o "$zip.tmp" "https://nodejs.org/dist/$version/node-$version-win-x64.zip"
+      local expected
+      expected="$(curl -fsSL "https://nodejs.org/dist/$version/SHASUMS256.txt" \
+        | awk -v a="node-$version-win-x64.zip" '$2 == a { print $1; exit }')"
+      [ -n "$expected" ] || { echo "wine-windows-gates: no SHASUMS256 entry for node-$version-win-x64.zip" >&2; exit 1; }
+      verify_sha256 "$expected" "$zip.tmp"
+      mv "$zip.tmp" "$zip"
+    fi
+  else
+    zip="$(ls -t "$cache_dir"/node-v"$node_major".*-win-x64.zip 2> /dev/null | head -1 || true)"
+    [ -n "$zip" ] || { echo "wine-windows-gates: nodejs.org unreachable and no cached Windows Node v$node_major zip in $cache_dir" >&2; exit 1; }
+    echo "wine-windows-gates: nodejs.org unreachable; using cached $(basename "$zip")" >&2
+  fi
+  unzip -q -o "$zip" -d "$scratch/node-win"
+  echo "$scratch/node-win/$(basename "$zip" .zip)/node.exe" > "$scratch/node-win-path"
+}
+
+boot_wine() {
+  "$wine_bin" wineboot --init > /dev/null 2>&1 || true
+  wineserver -w || true
+}
+
+snapshot_and_install() {
+  # Tracked + untracked-unignored files, minus agent-session litter; the
+  # existence filter drops paths staged as deleted. Then the Wine-specific
+  # install-time overrides go on the SNAPSHOT only: hoisted because Windows
+  # Node under Wine does not realpath pnpm's isolated-layout symlinks, and
+  # win32-x64 so the Windows esbuild/rolldown/rollup binaries materialize.
+  # Neither is recorded in the lockfile, so --frozen-lockfile stays valid;
+  # --ignore-scripts skips host lifecycle scripts no gate loads.
+  git -C "$repo_root" ls-files -z --cached --others --exclude-standard -- . ':!:.claude' ':!:.codex' \
+    | while IFS= read -r -d '' file; do [ -e "$repo_root/$file" ] && printf '%s\0' "$file"; done \
+    | tar -C "$repo_root" --null --files-from=- -cf - \
+    | tar -C "$scratch/tree" -xf -
+  cat >> "$scratch/tree/pnpm-workspace.yaml" << 'EOF'
+
+nodeLinker: hoisted
+supportedArchitectures:
+  os: [current, win32]
+  cpu: [current, x64]
+EOF
+  # The hoisted linker — used only by this lane — has an upstream rename
+  # race (pnpm/pnpm#12880): parallel linkers staging a nested package copy
+  # (observed on the tree's nested esbuild versions) rename their _tmp_*
+  # directory onto a path another racer already claimed, and the loser
+  # exits ERR_PNPM_ENOENT although an identical re-install succeeds.
+  # Exactly that signature earns up to two retries on a clean tree — the
+  # snapshot contains no node_modules, so wiping them restores the
+  # pre-install state; any other failure, or the race still standing after
+  # the final attempt, fails loud with the log tail.
+  local attempt
+  for attempt in 1 2 3; do
+    (cd "$scratch/tree" && pnpm install --frozen-lockfile --ignore-scripts > "$scratch/logs/install.log" 2>&1) \
+      && return 0
+    grep -q 'ERR_PNPM_ENOENT.*rename.*_tmp_' "$scratch/logs/install.log" || break
+    (( attempt < 3 )) || break
+    echo "wine-windows-gates: pnpm hoisted-linker rename race (pnpm/pnpm#12880) on install attempt $attempt; retrying on a clean tree" >&2
+    find "$scratch/tree" -name node_modules -type d -prune -exec rm -rf {} +
+  done
+  tail -40 "$scratch/logs/install.log" >&2
+  return 1
+}
+
+mkdir "$scratch/tree"
+start=$SECONDS
+provision_node & node_pid=$!
+boot_wine & wine_pid=$!
+snapshot_and_install & install_pid=$!
+# Wait for EVERY child before judging any: a bare `wait` under set -e would
+# exit on the first failure and let the EXIT trap delete $scratch while the
+# other children still run inside it. Named statuses also make the report
+# point at the root cause instead of a downstream symptom.
+node_status=0; wait "$node_pid" || node_status=$?
+wine_status=0; wait "$wine_pid" || wine_status=$?
+install_status=0; wait "$install_pid" || install_status=$?
+provision_failed=0
+report_provision() {
+  if (( $2 != 0 )); then
+    echo "wine-windows-gates: FAILED $1 (exit $2)" >&2
+    provision_failed=$2
+  fi
+}
+report_provision 'Windows Node provisioning' "$node_status"
+report_provision 'wineboot' "$wine_status"
+report_provision 'workspace snapshot + pnpm install' "$install_status"
+if (( provision_failed != 0 )); then exit "$provision_failed"; fi
+node_win="$(cat "$scratch/node-win-path")"
+echo "wine-windows-gates: provisioned in $((SECONDS - start))s (wine $("$wine_bin" --version 2> /dev/null), node $(basename "$(dirname "$node_win")"))"
+
+# ---- resolve entrypoints, lay the vue link, smoke ------------------------
+# Node under Wine cannot attach stdio to pipes the caller owns (Socket open
+# EBADF at bootstrap), so every invocation routes stdio through a file.
+wine_node() {
+  local log="$1"
+  shift
+  local status=0
+  "$wine_bin" "$node_win" "$@" < /dev/null > "$log" 2>&1 || status=$?
+  return "$status"
+}
+
+cd "$scratch/tree"
+tsc_js='node_modules/typescript/bin/tsc'
+tsdown_js='node_modules/tsdown/dist/run.mjs'
+vitepress_js='node_modules/vitepress/bin/vitepress.js'
+[ -f "$vitepress_js" ] || vitepress_js='website/node_modules/vitepress/bin/vitepress.js'
+for entry in "$tsc_js" "$tsdown_js" "$vitepress_js"; do
+  [ -f "$entry" ] || { echo "wine-windows-gates: expected entrypoint missing after hoisted install: $entry" >&2; exit 1; }
+done
+# VitePress links vue into the site's node_modules at build time; Wine cannot
+# CREATE Windows symlinks (ENOTSUP) but follows pre-existing Unix ones.
+if [ -d node_modules/vue ] && [ ! -e website/node_modules/vue ]; then
+  mkdir -p website/node_modules
+  ln -s ../../node_modules/vue website/node_modules/vue
+fi
+
+wine_node "$scratch/logs/smoke.log" -p "'smoke: ' + process.platform + ' ' + process.arch + ' ' + process.version"
+cat "$scratch/logs/smoke.log"
+grep -q '^smoke: win32 x64' "$scratch/logs/smoke.log" || { echo 'wine-windows-gates: Windows Node smoke did not report win32 x64' >&2; exit 1; }
+
+# ---- the two blocking surfaces, concurrently ------------------------------
+# The build preserves the face order from package.json: compile and bundle the
+# Host face before compiling and bundling the Client face.
+# Both statuses are captured so one failure cannot hide the other's result.
+build_gate() {
+  wine_node "$scratch/logs/host-tsc.log" "$tsc_js" -b tsconfig.host.json --pretty false || return $?
+  wine_node "$scratch/logs/host-tsdown.log" "$tsdown_js" --env.DSH_BUILD_FACE host || return $?
+  wine_node "$scratch/logs/client-tsc.log" "$tsc_js" -b tsconfig.client.json --pretty false || return $?
+  wine_node "$scratch/logs/client-tsdown.log" "$tsdown_js" --env.DSH_BUILD_FACE client
+}
+site_gate() {
+  cd website
+  wine_node "$scratch/logs/site.log" "../$vitepress_js" build .
+}
+
+start=$SECONDS
+build_gate & build_pid=$!
+site_gate & site_pid=$!
+build_status=0
+wait "$build_pid" || build_status=$?
+site_status=0
+wait "$site_pid" || site_status=$?
+elapsed=$((SECONDS - start))
+
+report() {
+  local label="$1" status="$2"
+  shift 2
+  if (( status == 0 )); then
+    echo "wine-windows-gates: PASS $label (${elapsed}s window)"
+  else
+    echo "== FAILED $label (exit $status) ==" >&2
+    for log in "$@"; do tail -n 200 "$log" >&2 || true; done
+  fi
+}
+report 'build (Host tsc/tsdown, Client tsc/tsdown)' "$build_status" \
+  "$scratch/logs/host-tsc.log" \
+  "$scratch/logs/host-tsdown.log" \
+  "$scratch/logs/client-tsc.log" \
+  "$scratch/logs/client-tsdown.log"
+report 'production site (vitepress build)' "$site_status" "$scratch/logs/site.log"
+if (( build_status != 0 )); then exit "$build_status"; fi
+exit "$site_status"

From 5d46c11784f3582ccde015d7c648bba8e653caf9 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 10:24:11 +0800
Subject: [PATCH 424/516] docs(i18n): reconcile source-drifted translations

---
 ...andatory-app-attribution-headers.i18n.yaml |  2 +-
 ...21-mandatory-app-attribution-headers.zh.md |  4 ++--
 ...cutable-sdk-runtime-distribution.i18n.yaml |  2 +-
 ...-executable-sdk-runtime-distribution.zh.md |  2 +-
 ...07-16-explicit-turn-cancellation.i18n.yaml |  2 +-
 ...026-07-16-explicit-turn-cancellation.zh.md |  4 ++--
 .../2026-06-30-interception-seams.i18n.yaml   |  2 +-
 .../2026-06-30-interception-seams.zh.md       |  6 ++---
 .../feature/2026-07-06-sandbox.i18n.yaml      |  2 +-
 .../feature/2026-07-06-sandbox.zh.md          |  4 ++--
 .../2026-07-16-harness-level-loop.i18n.yaml   |  2 +-
 .../2026-07-16-harness-level-loop.zh.md       |  8 +++----
 ...3-session-telemetry-otel-revival.i18n.yaml |  2 +-
 ...07-23-session-telemetry-otel-revival.zh.md |  2 +-
 ...-20-core-data-structures-catalog.i18n.yaml |  2 +-
 ...6-06-20-core-data-structures-catalog.zh.md | 10 ++++----
 ...ssion-projection-and-command-log.i18n.yaml |  2 +-
 ...7-session-projection-and-command-log.zh.md |  2 +-
 examples/headless-agent/README.i18n.yaml      |  2 +-
 examples/headless-agent/README.zh.md          |  4 ++--
 packages/acp/README.i18n.yaml                 |  2 +-
 packages/acp/README.zh.md                     |  4 ++--
 packages/bash/README.i18n.yaml                |  2 +-
 packages/bash/README.zh.md                    |  8 +++----
 packages/bash/bash/README.i18n.yaml           |  2 +-
 packages/bash/bash/README.zh.md               |  2 +-
 .../client/ui-primitives/README.i18n.yaml     |  2 +-
 packages/client/ui-primitives/README.zh.md    | 12 +++++-----
 packages/compact/README.i18n.yaml             |  2 +-
 packages/compact/README.zh.md                 |  4 ++--
 packages/context/README.i18n.yaml             |  2 +-
 packages/context/README.zh.md                 |  2 +-
 packages/core/README.i18n.yaml                |  2 +-
 packages/core/README.zh.md                    |  2 +-
 packages/core/agent-loop/README.i18n.yaml     |  2 +-
 packages/core/agent-loop/README.zh.md         | 10 ++++----
 packages/core/agent/README.i18n.yaml          |  2 +-
 packages/core/agent/README.zh.md              |  2 +-
 packages/core/session/README.i18n.yaml        |  2 +-
 packages/core/session/README.zh.md            |  4 ++--
 packages/core/system-prompt/README.i18n.yaml  |  2 +-
 packages/core/system-prompt/README.zh.md      |  2 +-
 packages/core/tools/README.i18n.yaml          |  2 +-
 packages/core/tools/README.zh.md              |  4 ++--
 .../examples/jsonrpc-demo/README.i18n.yaml    |  2 +-
 packages/examples/jsonrpc-demo/README.zh.md   |  2 +-
 packages/fs/README.i18n.yaml                  |  2 +-
 packages/fs/README.zh.md                      | 12 +++++-----
 packages/fs/fs/README.i18n.yaml               |  2 +-
 packages/fs/fs/README.zh.md                   | 24 +++++++++----------
 packages/goal/README.i18n.yaml                |  2 +-
 packages/goal/README.zh.md                    |  2 +-
 packages/goal/command-goal/README.i18n.yaml   |  2 +-
 packages/goal/command-goal/README.zh.md       |  4 ++--
 packages/goal/goal/README.i18n.yaml           |  2 +-
 packages/goal/goal/README.zh.md               |  6 ++---
 packages/guard/README.i18n.yaml               |  2 +-
 packages/guard/README.zh.md                   |  4 ++--
 packages/host/README.i18n.yaml                |  2 +-
 packages/host/README.zh.md                    |  6 ++---
 packages/llm/README.i18n.yaml                 |  2 +-
 packages/llm/README.zh.md                     |  6 ++---
 packages/lsp/README.i18n.yaml                 |  2 +-
 packages/lsp/README.zh.md                     |  4 ++--
 packages/lsp/lsp-local/README.i18n.yaml       |  2 +-
 packages/lsp/lsp-local/README.zh.md           |  2 +-
 packages/plan/README.i18n.yaml                |  2 +-
 packages/plan/README.zh.md                    |  2 +-
 packages/plan/plan-mode/README.i18n.yaml      |  2 +-
 packages/plan/plan-mode/README.zh.md          |  2 +-
 packages/pty/README.i18n.yaml                 |  2 +-
 packages/pty/README.zh.md                     |  4 ++--
 packages/pty/pty-local/README.i18n.yaml       |  2 +-
 packages/pty/pty-local/README.zh.md           |  4 ++--
 packages/sandbox/sandbox/README.i18n.yaml     |  2 +-
 packages/sandbox/sandbox/README.zh.md         |  4 ++--
 packages/skill/README.i18n.yaml               |  2 +-
 packages/skill/README.zh.md                   |  2 +-
 packages/spill/README.i18n.yaml               |  2 +-
 packages/spill/README.zh.md                   |  2 +-
 packages/subagent/README.i18n.yaml            |  2 +-
 packages/subagent/README.zh.md                |  2 +-
 .../subagent-dsh-sdk/README.i18n.yaml         |  2 +-
 .../subagent/subagent-dsh-sdk/README.zh.md    |  2 +-
 packages/subagent/subagent/README.i18n.yaml   |  2 +-
 packages/subagent/subagent/README.zh.md       |  8 +++----
 .../tool-subagent-control/README.i18n.yaml    |  2 +-
 .../tool-subagent-control/README.zh.md        |  2 +-
 packages/subprocess/README.i18n.yaml          |  2 +-
 packages/subprocess/README.zh.md              |  2 +-
 .../subprocess/subprocess/README.i18n.yaml    |  2 +-
 packages/subprocess/subprocess/README.zh.md   |  2 +-
 packages/tasks/README.i18n.yaml               |  2 +-
 packages/tasks/README.zh.md                   |  4 ++--
 packages/todo/README.i18n.yaml                |  2 +-
 packages/todo/README.zh.md                    |  2 +-
 packages/web/README.i18n.yaml                 |  2 +-
 packages/web/README.zh.md                     |  2 +-
 packages/workflow/README.i18n.yaml            |  2 +-
 packages/workflow/README.zh.md                |  6 ++---
 packages/workspace/README.i18n.yaml           |  2 +-
 packages/workspace/README.zh.md               |  2 +-
 102 files changed, 165 insertions(+), 165 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index 3db3ea7fa4..b3db1ae497 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
 2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a
-2026-06-21-mandatory-app-attribution-headers.zh.md: cdada9cb235d57ad5cac98ebe0572013cac728ef
+2026-06-21-mandatory-app-attribution-headers.zh.md: a10abff8d6e2addf196bf48e2634110aa5e13b3b
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index cdada9cb23..a10abff8d6 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -49,9 +49,9 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 ## 验证
 
-已落地的契约：
+已落地的约定：
 
-- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器契约（adapter contract）章节）。
+- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器约定章节）。
 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。
 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。
 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
index 08d8319d33..aa1d2c9d6f 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
 2026-07-10-single-file-executable-sdk-runtime-distribution.md: fe09e1b83f4f0a9f867f78351f643b1bd26d7c9d
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: ee49d7ea8fade9d3e323e8c6921479b8053809af
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 0279e0cf032928e96bad9da02340cae753a0927f
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
index ee49d7ea8f..0279e0cf03 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
@@ -27,7 +27,7 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后
 
 确定性协议实现（`server.ts` / `transport.ts`）按 `acp/acp` + `examples/acp-demo` 的既有模式落为两包——对外服务接口本身也是插件：
 
-- [`packages/scaffold/server`](../../../../packages/scaffold/server/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并刷新 `shutdown` 响应后 dispose 根运行时以排空持久化，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
+- [`packages/scaffold/server`](../../../../packages/scaffold/server/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答并确保 `shutdown` 响应发送完毕后，对根运行时执行 dispose（资源释放），让待处理的持久化操作完成，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
 - [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md)（`@deepseek-ai/dsh-jsonrpc-demo`）：轻量应用入口——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/boot/app-boot/src/index.ts) 的 `boot()`；`boot()` 完成后入口即完成，服务器由 `cordis.yml` 中的 `dsh-jsonrpc` 条目启动。它只依赖 `app-boot`。进程级退出归 `bin` 所有（stdin EOF/SIGTERM → dispose 后返回 0，SIGINT → 130）。
 
 配置发现有两个通道，均缺失时立即报错：优先使用 `DSH_CORDIS_CONFIG` 环境变量（SDK 客户端约定），其次使用 argv 位置参数；没有默认路径或内置回退——「实际启动的插件由外部 `cordis.yml` 决定」是硬语义。
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
index 2f7893a09f..d7f1670f34 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
 2026-07-16-explicit-turn-cancellation.md: 2b7cb8cc77184edf1331764d28aefe748c1614a1
-2026-07-16-explicit-turn-cancellation.zh.md: 68089e2c48d239afbff4c10cba5a202b4b6ff262
+2026-07-16-explicit-turn-cancellation.zh.md: 729997d48df79bad9fa52cd76ec7fa1fab281ae3
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
index 68089e2c48..729997d48d 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
@@ -20,7 +20,7 @@ AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它
 
 对于轮次被认领前已取消的排队工作，驱动器只保留一个不携带取消原因的运行前标记。实际生效的 `cancel()` 会先发出仅供观察的 `agent/cancel-requested` 通知并携带最终确定的类型化取消原因，然后才清除排队工作和 steering（中途引导）工作或中止持有者；通知失败不能阻止此次停止，空闲状态下调用则不发出任何通知。通知观察者同步加入队列的工作也会被这次清除，而稍后由 signal 中止观察者加入队列的工作会被锁存，并在被中止的活动收敛到空闲时执行——`disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。若 `running` 监听器同步取消旧工作并发送替代提示词，驱动器会丢弃已中止的持有者，并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先，后续调用仍可清除新入队的待处理工作。
 
-显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 seam 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。pre-step 进入决策、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
+显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 seam 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。步骤前处理入口、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
 
 `ctx.agents` 仍只携带发起 Agent。环境中的 Agent 并不代表存活、当前轮次或取消权限。cause 读取器是 loop 私有的，它直接陈述机器私有的 slot 不变量（只有 `cancel()` 会中止轮次控制器，且总是携带规范的冻结 cause），而不是对 reason 做结构化再校验；不存在从任意 signal 读取 cause 的公开辅助函数。并发 Agent 会同时隔离各自的发起方身份和轮次 signal；子驱动会遮蔽父发起方，而父请求 signal 仍通过 subagent seam 传递。
 
@@ -30,7 +30,7 @@ Agent dispose（资源释放）会在活跃持有者上请求仅用于运行时
 
 ## 验证
 
-契约测试验证类型化调用方联合类型、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在 pre-step、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal；并断言同一轮次使用一个 signal，不同轮次使用全新的 signal，终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。
+约定测试验证类型化调用方联合类型、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在步骤前处理、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal；并断言同一轮次使用一个 signal，不同轮次使用全新的 signal，终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。
 
 发起方作用域测试断言所有钩子仍观察到同一个 Agent 且没有环境中的轮次 signal，并发 Agent 保持独立的身份与 signal，嵌套子驱动只遮蔽身份。竞态测试覆盖空闲状态取消、运行前取消、从 `running` 监听器提交替代提示词、重复取消以及取消与 dispose 竞争下的完全停稳。
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
index 8481cc20d5..3adc8a826f 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-interception-seams.md
 2026-06-30-interception-seams.md: 3b2c62cd4413f6d93cef247c51304a8d46753218
-2026-06-30-interception-seams.zh.md: 4e7b6a5ac9ca88919246508cf86c486b06888417
+2026-06-30-interception-seams.zh.md: 40989aa6bd6f2c103312c01fb4efbab21487adea
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
index 4e7b6a5ac9..40989aa6bd 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
@@ -16,7 +16,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 
 **Agent 事件**（`dsh-agent`）：
 - `agent/session-start({ agent, source })` ——emit，在第 1 轮次之前触发一次，携带 `SessionStartSource`（`startup` 表示全新/fork 创建，`resume` 表示重新加载的持久化会话；`clear`/`compact` 保留）。纯通知，不能阻塞启动（这是有意的空白：桥接可以记录/注入，但不管控启动）。监听器通过 `agent.inject()` 注入上下文。
-- `agent/pre-step({ agent, messages, turn, step, signal }, next) → PreStepDecision` ——waterfall，在每个拟议步骤之前、循环原子移除其独占 inbox 批次后触发。payload 携带该请求的 `turn`、`step` 与取消 `signal`（已退役的 `PreStepContext` 字段位于 payload 中；参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)）；没有中途输入的工具续步会收到空批次。`enter` 返回完整消息批次，其中包括监听器为当前请求贡献的上下文；`reject` 不打开步骤，并让已领取消息保持已删除。
+- `agent/pre-step({ agent, messages, turn, step, signal }, next) → PreStepDecision` ——waterfall，在每个拟议步骤之前、循环原子移除其独占 inbox 批次后触发。payload 携带该请求的 `turn`、`step` 与取消 `signal`（已退役的 `PreStepContext` 字段位于 payload 中；参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)）；没有中途输入的工具续步中，`messages` 为空。`enter` 返回完整消息批次，其中包括监听器为当前请求贡献的上下文；`reject` 不打开步骤，并让已领取消息保持移除状态。
 
 **`agent/turn-stopping`** 是自然停止边界上的一次 awaited 通知。需要再执行一步的监听器调用 `agent.steer()`，传入来源显式的 steering（中途引导）内容供模型使用；循环随后重新读取 outbox，继续执行或关闭轮次。
 
@@ -35,7 +35,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 
 ### 三个承重的循环决策
 
-1. **在每个拟议步骤运行 pre-step 策略。** 循环会在首次领取和决策之前打开轮次，因此 reject 会关闭一个持久、blocked 且不含步骤或模型可见消息的轮次。即使工具续步没有新取得所有权的输入，也会提交空批次，使逐请求上下文生产方可以把带日志的消息加入这一次请求。enter 时，循环先开启步骤，再把返回批次作为 `user/message` 追加，然后派生请求。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个已领取 follow-up 仍是其轮次中唯一的直接提示词。
+1. **在每个拟议步骤运行 pre-step 策略。** 循环会在首次领取和决策之前打开轮次，因此 reject 会关闭一个持久、blocked 且不含步骤或模型可见消息的轮次。即使工具续步没有新取得所有权的输入，也会提交空批次，使逐请求上下文生产方可以把会记录到日志中的消息加入这一次请求。enter 时，循环先开启步骤，再把返回批次作为 `user/message` 追加，然后派生请求。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个已领取 follow-up 仍是其轮次中唯一的直接提示词。
 
 2. **工具执行后的 `additionalContexts` 与异步注入进入活跃批次 FIFO，并在该批次结算时追加。** `content`/`feedback` 塑造 `execute()` 返回的结果，但每项上下文都是一条独立的带来源 `user/message`，而单个步骤或组合工具可以产生许多上下文。立即追加上下文会产生 `result(c1) → context → result(c2)` 的交错，或把嵌套上下文放在外层结果之前，破坏工具调用／工具结果邻接性。因此 `ToolRunContext.deferContext()` 会在失败路径上也收集嵌套调度上下文，`execute()` 在 `ToolExecutionResult` 上暴露有序数组，循环再把它接纳到与执行期间 `agent.inject()` 调用相同的 FIFO 中。FIFO 在批次结算时，在所有已记录结果之后追加，其中也包括被中断轮次关闭之前。被接受的外层调用将 deferred contexts 保留在 decision contexts 之前；被外层阻止时则丢弃 deferred contexts，只暴露阻止 decision 显式提供的上下文。
 
@@ -56,4 +56,4 @@ seam 包**不**声明 `hook/*` 会话事件（持久的钩子调用日志）；
 
 ## 后果
 
-规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP 桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
+规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的约定记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP（Agent Client Protocol）桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 00f475040c..755c076bca 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-sandbox.md
 2026-07-06-sandbox.md: 06c5590454a6947030d828f087b92f44207dad6e
-2026-07-06-sandbox.zh.md: 8f575e3cd14973aaaaf9254337b985110bc99d6b
+2026-07-06-sandbox.zh.md: 9f55626a8fd12782249284c83f1e76e1d2f89724
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index 8f575e3cd1..9f55626a8f 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -60,9 +60,9 @@ OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还
 
 #### 本地后端与随附 launcher
 
-`dsh-sandbox-local` 在提供方生命周期内选择一个平台 runner 并缓存结论。Linux 功能性探测 `bwrap` 然后 Landlock；macOS 使用 Seatbelt。不支持的平台和不可用的 runner 失败关闭。每次包装携带后端特定的拒绝签名和 runner 失败规则，以便 `dsh-bash-sandbox` 区分被拒绝的文件操作与损坏的沙箱。Landlock runner 失败需要退出码 125，加上一行不是通知的 `landlock-run:` 诊断；即使子进程以 1、2 或 125 退出，精确匹配的部分强制执行通知仍只是信息。Bubblewrap 和 Seatbelt 仍仅依据签名，因为两者的公开契约均未保留 launcher 失败状态。`runnerCommand` 保留面向运维人员的 `runnerFailureSignatures` 配置，要求其中条目均为非空单行，并将它们映射为一条内部致命规则。消费方会直接 spawn 每个返回的 argv，因此缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本会通过可归因的 `ENOENT`／`EACCES` spawn 通道失败，而成功启动的子进程以 126 或 127 退出时仍按普通结果处理。运维人员配置的脚本必然要先启动解释器，再应用自身 profile。
+`dsh-sandbox-local` 在提供方生命周期内选择一个平台 runner 并缓存结论。Linux 功能性探测 `bwrap` 然后 Landlock；macOS 使用 Seatbelt。不支持的平台和不可用的 runner 失败关闭。每次包装携带后端特定的拒绝签名和 runner 失败规则，以便 `dsh-bash-sandbox` 区分被拒绝的文件操作与损坏的沙箱。Landlock runner 失败需要退出码 125，加上一行不是通知的 `landlock-run:` 诊断；即使子进程以 1、2 或 125 退出，精确匹配的部分强制执行通知仍只是信息。Bubblewrap 和 Seatbelt 仍仅依据签名，因为两者的公开约定均未保留 launcher 失败状态。`runnerCommand` 保留面向运维人员的 `runnerFailureSignatures` 配置，要求其中条目均为非空单行，并将它们映射为一条内部致命规则。消费方会直接 spawn 每个返回的 argv，因此缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本会通过可归因的 `ENOENT`／`EACCES` spawn 通道失败，而成功启动的子进程以 126 或 127 退出时仍按普通结果处理。运维人员配置的脚本必然要先启动解释器，再应用自身 profile。
 
-launcher 是一个约 300 行的 C 程序（纯 C11，直接使用 Landlock UAPI——除静态链接的 musl 外无其他库，因此审计面仅为该文件加内核的稳定 syscall 契约）：`--ro <path>` / `--rw <path>` 授权，`--`，被包装的 argv；它为自身安装规则集并执行 `exec`（规则集跨 `execve` 继承，且它在限制前设置 `no_new_privs`）；`--probe` 在一个短生命周期子进程中强制最大规则集，仅当内核确实强制时才以 0 退出；所有 launcher 失败都会以 125 退出且不运行子进程，并打印一行致命的 `landlock-run:` 诊断。成功完成 exec 的子进程也可能返回 125，因此仅凭退出状态不能作为 launcher 失败的证据。较旧的 ABI 会在执行子进程之前打印精确的 `landlock-run: partial enforcement (older Landlock ABI)` 通知，因此该行不是致命证据。
+launcher 是一个约 300 行的 C 程序（纯 C11，直接使用 Landlock UAPI——除静态链接的 musl 外无其他库，因此审计面仅为该文件加内核的稳定 syscall 约定）：`--ro <path>` / `--rw <path>` 授权，`--`，被包装的 argv；它为自身安装规则集并执行 `exec`（规则集跨 `execve` 继承，且它在限制前设置 `no_new_privs`）；`--probe` 在一个短生命周期子进程中强制最大规则集，仅当内核确实强制时才以 0 退出；所有 launcher 失败都会以 125 退出且不运行子进程，并打印一行致命的 `landlock-run:` 诊断。成功完成 exec 的子进程也可能返回 125，因此仅凭退出状态不能作为 launcher 失败的证据。较旧的 ABI 会在执行子进程之前打印精确的 `landlock-run: partial enforcement (older Landlock ABI)` 通知，因此该行不是致命证据。
 
 Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 消费方同仓，并属于根 pnpm workspace。[仓库内 Landlock 发布决策](../process/2026-08-06-in-repository-landlock-release.md)负责共享锁文件、原生构建、打包演练和 npm 发布边界。平台二进制由 npm 选择，入口包拥有路径解析、探测、CLI 参数、致命前缀和部分强制执行通知，而 harness 将沙箱模式映射为授权。将入口点与其二进制一起版本化，使探测解析和启动语法保持对齐。
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index a54f2e9496..15d82777e1 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
 2026-07-16-harness-level-loop.md: f37bea0842b3f40bf07c6660ad758d84ece23f1b
-2026-07-16-harness-level-loop.zh.md: 0ec2dc2294c1adf8b7f6f810bfaffa7e08c19ed2
+2026-07-16-harness-level-loop.zh.md: 10f4cd2ac4991361261dd652d5d99dcb15d459be
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index 0ec2dc2294..10f4cd2ac4 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -42,11 +42,11 @@ Status: implemented
 | `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`，人类命令生产方 | 为 TUI 注册构建在目标领域之上的 `/goal` 状态、创建、编辑、暂停、恢复与清除。 |
 | `@deepseek-ai/dsh-tool-ralph` | `packages/workflow/tool-ralph/`，固定工作流消费方 | 注册 `ralph({ objective, maxRounds? })`，验证全新结构化 provider 与有界 `RalphRoundReport`，并返回 `complete`、`blocked` 或 `budget-limited`。 |
 
-详细契约分别由[目标领域](2026-07-19-persisted-same-session-goal-domain.md)、[Goal 自有事件](../architecture/2026-07-31-goal-owned-durable-events.md)、[模型目标工具](2026-07-19-model-facing-goal-tools.md)、[目标回合驱动器](2026-07-19-same-session-goal-round-driver.md)、[命令注册表](2026-07-19-plugin-command-registration.md)、[人类目标命令](2026-07-19-human-goal-command.md)与 [Ralph 工作流工具](2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note 拥有。
+详细约定分别由[目标领域](2026-07-19-persisted-same-session-goal-domain.md)、[目标自有事件](../architecture/2026-07-31-goal-owned-durable-events.md)、[模型目标工具](2026-07-19-model-facing-goal-tools.md)、[目标回合驱动器](2026-07-19-same-session-goal-round-driver.md)、[命令注册表](2026-07-19-plugin-command-registration.md)、[人类目标命令](2026-07-19-human-goal-command.md)与 [Ralph 工作流工具](2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note 拥有。
 
 ### 持久目标状态与实时权限
 
-一个会话至多有一个当前 goal。每次变更都通过持久 `goal/change` 事件提交，并携带带版本的完整快照或带修订号的 clear 墓碑；inbox 状态不参与其中。会话日志是唯一持久真源，因此普通持久化、恢复与 `SessionStore.fork()` 会携带 goal，无需第二个数据库或人为取消记录。
+一个会话至多有一个当前目标。每次变更都通过持久的 `goal/change` 事件提交；该事件携带带版本的完整快照或带修订号的清除墓碑，收件箱状态不参与其中。会话日志是唯一持久真源，因此普通持久化、恢复与 `SessionStore.fork()` 会携带目标，无需第二个数据库或人为取消记录。
 
 持久阶段只有 `active`、`paused`、`blocked` 与 `complete`。阻塞目标必须携带 `GoalBlockReason`，其中包含稳定的小写 kebab-case `code` 与非空的人类可读 `message`；用量限制、Round 耗尽、模型失败与策略拒绝都是原因代码，而不是额外生命周期阶段。独立激活态是 `armed` 或 `disarmed`，且永不持久化。创建与显式恢复会激活目标；停止转换、会话启动、fork 回放、驱动器替换和驱动器拆卸都会让目标保持未激活。
 
@@ -58,9 +58,9 @@ fork 会话会继承持久目标前缀，因为这是自然的重放结果。for
 
 ### 同会话续行
 
-Goal Round 驱动器为每个准确实时 agent 至多拥有一个待定预留。只有 goal 处于活跃且已激活状态、agent 空闲、不存在竞争性人类工作、最新变更已经通过持久性检查点、准确 goal id／revision／Round 仍匹配，并且下游 pre-step 策略接受时，它才会接纳预留。其 `agent/pre-step` 围栏会在下游监听器前后检查这些事实，防止编辑、暂停、人类消息或卸载竞争接纳陈旧工作。
+Goal Round 驱动器为每个特定的实时 agent 至多拥有一个待定预留。只有目标处于活跃且已激活状态、agent 空闲、不存在竞争性人类工作、最新变更已经通过持久性检查点、确切的目标 id／修订号／Round 仍匹配，并且下游 pre-step 策略接受时，它才会接纳预留。其 `agent/pre-step` 围栏会在下游监听器前后检查这些事实，防止编辑、暂停、人类消息或卸载竞争接纳过时工作。
 
-只有已准入、Round 为正数且来源为 goal 的 `user/message` 会计入一个 Round。陈旧预留会关闭一个 blocked 的无步骤轮次，不会消耗上限。并发 goal revision 会胜过旧 Round 的结算。
+只有已接纳、Round 为正数且带目标来源的 `user/message` 会计入一个 Round。陈旧预留会结束一个阻塞的零步骤轮次，不会消耗上限。并发目标修订会胜过旧 Round 的结算。
 
 普通 Turn 完成后，只有目标仍活跃、已激活且低于上限时才会安排另一个 Round。取消会暂停。速率限制或配额耗尽以代码 `usage-limited` 阻塞；上限耗尽使用 `round-limit`；队列失败使用 `queue-failed`；Turn 错误、max-token 停止、策略拒绝与未知终止结果使用各自对应的阻塞代码。独立组合的请求恢复插件可以在同一个 Turn 内重试暂时性 provider 失败；目标驱动器绝不会在异常终止结果后凭空发起另一个 Round。人类随后可以通过普通语言或 `/goal resume` 授权恢复。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index 58b5371ba2..be9c014650 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
 2026-07-23-session-telemetry-otel-revival.md: e6a213af65451a2ae26a5eb685c1a0f6ab220869
-2026-07-23-session-telemetry-otel-revival.zh.md: 4e834f8b129e2062064cf3497370fecf6f88db29
+2026-07-23-session-telemetry-otel-revival.zh.md: 1d607ce9a3b77ae96664af72599beacb34fd9b47
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index 4e834f8b12..1d607ce9a3 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 `packages/session/`（原 `telemetry/`）以 SDK 立场复活这两个经过评审的包——harness 提供能力，部署方配置上报去向并对导出内容负责：
 
-- **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的实时收养与逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、从权威日志进行的无缓冲按需回放、固定的每个（轮次、步骤）组合首分片投影、实时 `agent/error` 转发，以及实时 dispose（资源释放）时的 `shutdown` 记录。
+- **`@deepseek-ai/dsh-session-telemetry`** —— seam 本体。`TelemetryBackend`（`emit`/`flush?`/`shutdown`）、服务注册形态的 `Telemetry`、以及拥有捕获侧的 `TelemetryCoordinator`：带游标回读的实时纳管与逐 append 的 firehose（投影 → `structuredClone` → 脱敏 → `emit`，零 I/O）、从权威日志进行的无缓冲按需回放、固定的每个（轮次、步骤）组合首分片投影、实时 `agent/error` 转发，以及实时 dispose（资源释放）时的 `shutdown` 记录。
 - **`telemetry/record` waterfall（瀑布式事件）** —— 相对分支版本的增量，也是该 seam 的脱敏扩展点。每条记录抵达任何后端前必经此处；seam 自身不带任何规则——最内层 `next()` 原样透传，部署方以监听器挂载自己的规则（通过变换 `next()` 的返回值堆叠），抛异常的规则将该记录 fail-closed 扣下。脱敏只作用于导出副本；canonical log 永不改写。
 - **`@deepseek-ai/dsh-session-telemetry-otel`** —— 参考后端：OTel JS SDK 日志流水线（`LoggerProvider` → `BatchLogRecordProcessor` → OTLP/HTTP exporter），经 `exporter`/`processor` passthrough 原样配置。其默认 `FULL` 模式要求 `exporter.url`；后续的[反馈门控遥测决策](2026-08-05-feedback-gated-session-telemetry.md)增加了 `FEEDBACK_ONLY` 与 `DISABLED` 投递模式，但未移动脱敏或后端边界，而[无缓冲反馈回放](../simplification/2026-08-06-buffer-free-feedback-telemetry.md)避免在内存中创建会话前缀的第二份副本。
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index def34cdfbd..6f51f73b00 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
 2026-06-20-core-data-structures-catalog.md: 9a3f80df592f28adc365d5e64cc15516d92b47b5
-2026-06-20-core-data-structures-catalog.zh.md: 96c606a3d65a67e757960c5cbc997e717f11e8d5
+2026-06-20-core-data-structures-catalog.zh.md: 895f639446bc6c4e0fecbf1085197ba8b1810282
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 96c606a3d6..895f639446 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 核心数据结构目录与 `ts type-equiv` 漂移门禁
+# Agent Note: 子系统目录与 `ts type-equiv` 漂移门禁
 
 Status: implemented
 
@@ -18,14 +18,14 @@ Status: implemented
 
 > **作为页面范围界定规则已被取代**，见[按包锚定的子系统页面](2026-08-03-package-anchored-subsystem-pages.md)：每页现在锚定到声明其词汇的包分组。下文的 `ts type-equiv` 机制仍然有效。
 
-范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入子页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
+范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入自己的 seam 页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
 
-确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是子页面细节。*** 逐一验证如下：
+确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是 seam 页面细节。*** 逐一验证如下：
 
 - 一个数据结构是**核心**的，如果它流经 agent loop 主干——无论加载了哪些插件，循环在每个轮次都会持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄）——**或者**它是插件作者面对某条流水线时编写的唯一标志性类型（`ToolDefinition`）。
-- `ToolDefinition` 是核心（它是每个工具作者编写的东西），**即使循环从不持有它**——对于这一个标志性类型，编写层面的重要性压过了严格的「流经主干」规则。但它的类型推导机制——`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue` 与 `InferArgs`——是子页面细节。这就是主干与 seam 分界线的精确表述。
+- `ToolDefinition` 是核心（它是每个工具作者编写的东西），**即使循环从不持有它**——对于这一个标志性类型，编写层面的重要性压过了严格的「流经主干」规则。但它的类型推导机制——`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue` 与 `InferArgs`——是 seam 页面细节。这就是主干与 seam 分界线的精确表述。
 - `ToolSchema` 是核心（它是流经每个步骤的模型请求 `GenerateOptions` 的一个字段），即使它在概念上属于工具流水线——当*流经主干*与*概念归属*冲突时，前者胜出。
-- 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇是子页面。
+- 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇属于 seam 页面。
 
 `core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到同级 seam 页面获取各 seam 的细节；目录的 [README](../../../../docs/subsystems/README.md) 索引全部页面。最初的 seam 页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index 0fe388a3dc..d4aa713b5c 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
 2026-07-27-session-projection-and-command-log.md: 2fc463ab6e65998c19b0a0fce186c7eb17dacbf6
-2026-07-27-session-projection-and-command-log.zh.md: 89877d3aabcd074863f912b334c927268014e4d8
+2026-07-27-session-projection-and-command-log.zh.md: 0cc82d1aa65dc2b99882875d655ddbe17073354a
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index 89877d3aab..0cc82d1aa6 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -58,7 +58,7 @@ declare module 'cordis' {
 
 ### 已交付的消费方：subagent 身份单元
 
-注册表的两处既有读法已经服务于本 RFC 协议计划之外的一个已交付消费方：[subagent 列表经投影单元读取身份](../../implemented/architecture/2026-08-06-subagent-list-identity-projection.md)注册了 `subagent` 单元——从 `subagent/descriptor` 按 last-wins 折叠出的持久化 mode/label 身份——`SubagentService.listChildren` 对 live child 经 `snapshot()` 读取（水位缓存，零日志读），对 cold child 则用一次持久化整读的结果调用 `restore({}, events, 0)` 读取。注册表契约不变：没有失败通道、没有新读法——单元永不抛错，值缺席本身就是信号，缺席如何呈现是该消费方自己的决定。
+注册表的两处既有读法已经服务于本 RFC 协议计划之外的一个已交付消费方：[subagent 列表经投影单元读取身份](../../implemented/architecture/2026-08-06-subagent-list-identity-projection.md)注册了 `subagent` 单元——从 `subagent/descriptor` 按 last-wins 折叠出的持久的 mode/label 身份——`SubagentService.listChildren` 对 live child 经 `snapshot()` 读取（水位线缓存，零日志读），对 cold child 则对一次持久化读取所得的事件调用 `restore({}, events, 0)` 读取。注册表约定不变：没有失败通道、没有新读法——单元永不抛错，值缺席本身就是信号，缺席如何呈现是该消费方自己的决定。
 
 ### 协议层：历史尾页上的 projections 块
 
diff --git a/examples/headless-agent/README.i18n.yaml b/examples/headless-agent/README.i18n.yaml
index 4a71194e5f..07a1dc582a 100644
--- a/examples/headless-agent/README.i18n.yaml
+++ b/examples/headless-agent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write examples/headless-agent/README.md
 README.md: 6e80e56dec70c2be341ae5dfbad70e13a5109715
-README.zh.md: ea8c41b9ae75f0cee3edd78e59408f37c19182d3
+README.zh.md: 9e409735f03afc62cd788fa2a5d1afdef0fa6c2a
diff --git a/examples/headless-agent/README.zh.md b/examples/headless-agent/README.zh.md
index ea8c41b9ae..9e409735f0 100644
--- a/examples/headless-agent/README.zh.md
+++ b/examples/headless-agent/README.zh.md
@@ -19,13 +19,13 @@ pnpm run dsh run "fix the failing test in this workspace"
 
 ## E2B POC overlay
 
-[`e2b.cordis.yml`](e2b.cordis.yml) 使用一个共享 E2B 沙箱替换本地文件系统与进程管理提供方，同时保留 `dsh-bash-local` 和相同的面向模型工具。请在 git 忽略的根目录 `.env` 中，将 `E2B_API_KEY` 与 `DEEPSEEK_API_KEY` 放在一起，然后运行凭据门控的实机组合测试；它在同一个沙箱中驱动 FS、Bash、PTY 和 LSP，并证明沙箱最终被删除：
+[`e2b.cordis.yml`](e2b.cordis.yml) 使用一个共享 E2B 沙箱替换本地文件系统与子进程提供方，同时保留 `dsh-bash-local` 和相同的面向模型工具。请在 git 忽略的根目录 `.env` 中，将 `E2B_API_KEY` 与 `DEEPSEEK_API_KEY` 放在一起，然后运行凭据门控的实机组合测试；它在同一个沙箱中驱动 FS、Bash、PTY 和 LSP，并证明沙箱最终被删除：
 
 ```sh
 pnpm exec vitest run --config vitest.e2e.config.ts packages/e2b/e2b/tests/composition.e2e.ts
 ```
 
-该 overlay 会在沙箱中创建拼写相同的绝对 cwd，但不会上传或挂载宿主工作区。文件与 Bash 变更只存在于 E2B；Cordis、模型调用、agent／会话状态、会话日志、skill（技能）和 SDK 缓冲仍在宿主上。该组合会在超时和资源释放时终止其沙箱。它是提供方组合 POC，而不是完整 harness 迁移或工作区同步功能。
+该 overlay 会在沙箱中创建相同的绝对 cwd，但不会上传或挂载宿主工作区。文件与 Bash 变更只存在于 E2B；Cordis、模型调用、agent／会话状态、会话日志、skill（技能）和 SDK 缓冲仍在宿主上。该组合会在超时和资源释放时终止其沙箱。它是提供方组合 POC，而不是完整 harness 迁移或工作区同步功能。
 
 ## 高级配置
 
diff --git a/packages/acp/README.i18n.yaml b/packages/acp/README.i18n.yaml
index cd4555752b..08fe41b6ab 100644
--- a/packages/acp/README.i18n.yaml
+++ b/packages/acp/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/acp/README.md
 README.md: 97af6d164b265bf0e98e3c9f5a444cffad4face5
-README.zh.md: 266b108c108b9f543d93cbb727ddbc01ab4bef36
+README.zh.md: fb9f419e23aef5b3bdf0bdd486b331eb2f3f236a
diff --git a/packages/acp/README.zh.md b/packages/acp/README.zh.md
index 266b108c10..fb9f419e23 100644
--- a/packages/acp/README.zh.md
+++ b/packages/acp/README.zh.md
@@ -2,10 +2,10 @@
 
 [English](README.md) | 中文
 
-ACP 组通过 Agent Client Protocol 把 harness agent 暴露给编程客户端。它是互操作传输层，不是展示或人机交互层；配对的进程外 subagent *客户端*在 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现的是 subagent 提供方接口。
+ACP（Agent Client Protocol）组通过该协议将 harness 中的 agent（智能体）公开给程序化客户端。它是互操作传输层，不是展示或人机交互层；配对的进程外 subagent *客户端*在 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现的是 subagent 提供方接口。
 
 | 包 | 职责 |
 |---|---|
 | [`acp/`](acp/README.md) | 仅面向自动化的 ACP 服务器。 |
 
-服务器契约见 [`acp/README.md`](acp/README.md)。
+服务器约定见 [`acp/README.md`](acp/README.md)。
diff --git a/packages/bash/README.i18n.yaml b/packages/bash/README.i18n.yaml
index 00321c8ab0..a55672b9e1 100644
--- a/packages/bash/README.i18n.yaml
+++ b/packages/bash/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/README.md
 README.md: 7395a051742af24b96842966b71297dc01853dca
-README.zh.md: 1d5825e077c46284dbd4895e285cda8f39c252a3
+README.zh.md: 043394f429d406a6d14f00b6d8a0384bd022abe0
diff --git a/packages/bash/README.zh.md b/packages/bash/README.zh.md
index 1d5825e077..043394f429 100644
--- a/packages/bash/README.zh.md
+++ b/packages/bash/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-该能力家族涵盖规范执行器 seam、其实现、共享 shell 环境和面向模型的工具。这些全是**产品**包。
+该能力家族涵盖规范的执行器 seam、其实现、共享 shell 环境和面向模型的工具。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`bash/`](bash/README.md) | 定义实现与消费方共享的执行器契约。 | `ctx.bash` |
+| [`bash/`](bash/README.md) | 定义实现与消费方共享的执行器约定。 | `ctx.bash` |
 | [`bash-local/`](bash-local/README.md) | 通过本地 [`subprocess`](../subprocess/README.md) 服务执行命令。 | （注册 `ctx.bash`） |
 | [`bash-sandbox/`](bash-sandbox/README.md) | 在本地执行前应用已配置的 [`sandbox`](../sandbox/README.md) 后端。 | （注册 `ctx.bash`） |
-| [`pwsh-local/`](pwsh-local/README.md) | 以 Windows 专用进程行为执行 PowerShell 命令。 | （注册 `ctx.bash`） |
-| [`bash-env/`](bash-env/README.md) | 提供 shell 工具共享的托管 `DSH_*` 环境。 | `ctx.bashEnv` |
+| [`pwsh-local/`](pwsh-local/README.md) | 采用 Windows 特有的进程行为执行 PowerShell 命令。 | （注册 `ctx.bash`） |
+| [`bash-env/`](bash-env/README.md) | 提供 shell 工具共享的受管 `DSH_*` 环境。 | `ctx.bashEnv` |
 | [`tool-bash/`](tool-bash/README.md) | 向模型公开 Bash 执行和后台任务集成。 | （注册到 `ctx.tools`） |
 | [`tool-pwsh/`](tool-pwsh/README.md) | 向模型公开 PowerShell 执行。 | （注册到 `ctx.tools`） |
 
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index eee269c121..169a45d5cd 100644
--- a/packages/bash/bash/README.i18n.yaml
+++ b/packages/bash/bash/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/bash/README.md
 README.md: 690f4e61740faf2648ecbc7f5995ec0fdaa64aee
-README.zh.md: c343e17bfd97eaf17316c034c263b0c71bb8327a
+README.zh.md: f8bcfce06a406eb94a2486e9825f2beb11b8fd5e
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index c343e17bfd..f8bcfce06a 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -35,7 +35,7 @@
 
 `stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的统一来源。模型 bash 使用 `ctx.bashEnv` 收集的当前快照。实现会移除继承的受管 key，再在普通 `env` 之后合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态，`env` 条目也无法顶掉受管值。面向模型的工具不将这三者中的任何一个公开为参数。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 
-导出的 `parseExitStatus`（连同 `ParsedExitStatus`）是 shell 工具共享渲染契约的另一半：`dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 追加的 `[exit code: N]`／`[killed by signal: X]` marker 的逆解析。两个工具的 `presentResult` 都用它把渲染文本拆成 terminal 卡的输出正文与其退出状态 pill；它放在 seam 上，两个工具便永远不会在 marker 契约上漂移。
+导出的 `parseExitStatus`（连同 `ParsedExitStatus`）是 shell 工具共享渲染约定的一部分：它对 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]`／`[killed by signal: X]` marker 进行逆解析。两个工具的 `presentResult` 都用它把渲染文本拆成 terminal 卡的输出正文与退出状态 pill；它位于 seam 上，因此两个工具的 marker 约定不会发生偏离。
 
 ## 模型体验
 
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 42211f6d7a..5c8e7eaab6 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md
 README.md: 098a202a4ac9ee263ce1beaaee7a8624ebf26b80
-README.zh.md: 2b33af3316dede35cb5a226e41365f692a8b25d3
+README.zh.md: def1907f81d06b5afdf19af5f19ba17a269ed3c1
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index 2b33af3316..def1907f81 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。契约：api-contracts v3 §8。
+纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在且仅在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` 钩子（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。约定：api-contracts v3 §8。
 
 ## 悬浮卡片
 
-`HoverCard` 通过指针离开宽限期，让采用 portal 渲染的预览在跨越与锚点之间的间隙时仍可抵达。消费方还可传入 `copyText`：此时卡片为指针与键盘激活提供按钮语义，其无障碍名称会在 `copyLabel` 前缀后包含该值，通过包内剪贴板辅助函数原样写入该值，并且只有宿主接受写入后，才会临时将内容替换为 `copiedLabel`。与卡片相交的非折叠文本选区会阻止指针点击激活；成功反馈保持卡片原有高度，并随卡片关闭或在一秒后清除。`copyLabel` 和 `copiedLabel` 采用 label prop，是因为这个 zero-cordis 原子组件无法读取应用 locale；省略 `copyText` 时，卡片维持只读且可选择文本的行为。历史依据见[已归档的悬浮卡片复制 Agent Note](../../../.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md)。
+`HoverCard` 通过指针离开宽限期，使采用 portal 渲染的预览在跨过与锚点之间的间隙时仍可触及。消费方还可传入 `copyText`：此时卡片为指针与键盘激活提供按钮语义，其无障碍名称会在 `copyLabel` 前缀后包含该值，通过包内剪贴板辅助函数原样写入该值，并且只有宿主接受写入后，才会临时将内容替换为 `copiedLabel`。与卡片相交的非折叠文本选区会阻止指针点击激活；成功反馈保持卡片原有高度，并随卡片关闭或在一秒后清除。`copyLabel` 和 `copiedLabel` 采用 label prop，是因为这个 zero-cordis 原子组件无法读取应用 locale；省略 `copyText` 时，卡片维持只读且可选择文本的行为。历史依据见[已归档的悬浮卡片复制 Agent Note](../../../.agents/notes/archived/feature/2026-07-31-hover-card-click-copy.md)。
 
 ## Markdown 渲染
 
-`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有视图把命名真实文件的行内代码变成链接：token 保留代码样式并获得接到所解析 opener 的按钮，带解析器给出的无障碍标签与完整路径 `title`。渲染器绝不猜测什么长得像路径——未解析的 token 保持原样，提及只作用于已定稿的渲染（流式缓存不能烘进可能过期的 handler），锚点内部的 token 也保持原样，因为按钮不能嵌套在链接里。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性契约](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
+`MarkdownText` 通过 React 元素渲染来自不受信任 assistant 输出的 GFM 与 `$…$`、`$$…$$`、`\(…\)` 和 `\[…\]` TeX 公式，公式由 KaTeX 排版并禁用受信任命令；块级同一行 `$$…$$` 是显示公式并支持 `\tag{}`。一个小范围的 micromark 扩展允许由星号标记、以标点结尾的粗体在紧邻的 CJK 文本前闭合，以适应 CJK 文本通常省略 CommonMark 所要求空格的写法；单星号强调、紧邻非 CJK 文本的情况、转义、代码与数学公式仍沿用上游解析行为。它会省略原始 HTML，使相对链接及非 HTTP(S)/mailto 链接失效，以安全的外部链接属性打开 HTTP(S) 链接，并在不发送 referrer 的情况下渲染采用绝对 HTTP(S) URL 的图片；相对路径、绝对本地路径、`file:` URL 与不受支持的 scheme 会保留其 alt 文本。完整内容为绝对 HTTP(S) URL 的行内代码会保留代码样式，并获得同样安全的外部链接；命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。可选的 `fileMentions` 解析器让持有该组件的视图为命名真实文件的行内代码添加可点击入口：token 保留代码样式，并获得一个连接到解析所得 opener 的按钮，按钮带有解析器提供的无障碍标签和以完整路径为值的 `title`。渲染器绝不猜测哪些内容像路径：未解析的 token 保持不可交互；文件提及仅应用于已定稿的渲染（流式缓存不得固化可能过期的 handler）；锚点内的 token 也保持不可交互，因为按钮不能嵌套其中。回复流式输出期间，`MarkdownText` 增量解析：除末尾两个块外全部冻结为缓存的 React 元素，每个分片只重新解析其后的源文本尾部，因此每分片的工作量跟随尾部而非整个回复（[机制与 DOM 一致性约定](../../../.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md)）。`MessageText` 仍是用户创作内容使用的字面文本原语。`extractMarkdownPlainText` 会移除 Markdown 呈现标记以用于紧凑标签，同时将原始 HTML 保留为字面文本。元素间距、响应式图片、表格、链接与行内代码使用与 deepsuite `@deepseek/md` 相同的 `--dsw-alias-markdown-*` / `--dsw-font-markdown-*` token。围栏代码块通过 `CodeBlock` 渲染（语言横幅、复制控件，以及对已注册语法使用 shiki）。
 
 ## 终端输出
 
@@ -22,7 +22,7 @@
 
 ## Diff 渲染
 
-`DiffBlock` 将一次文件改动渲染为内联 diff 表层：每个文件一个粗体路径头、删除行（`- `，error token）在新增行（`+ `，success token）之上、同文件第二个 hunk 前一个 `⋯` gap，以及暗色 `└ +A -R · N file(s)` 页脚。各行使用 `white-space: pre` 并横向滚动，因此源码行保留其缩进而不软换行；超过 `maxLines`（默认 16，与 `TerminalBlock` 相同的切分算法）时折叠为头部切片加尾部切片，由展开按钮控制。新建（`oldText: null`）没有删除侧。复制控件写入带前缀的 diff 文本（路径头、`- `/`+ ` 行、gap），使多文件复制保持可归属，并浮在右上角而非占据自己的 banner 行。几何镜像 `CodeBlock`/`TerminalBlock`。原理：[Web diff 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)。
+`DiffBlock` 将一次文件改动渲染为内联 diff 表层：每个文件一个粗体路径头、删除行（`- `，error token）在新增行（`+ `，success token）之上、同文件第二个 hunk 前一个 `⋯` gap，以及暗色 `└ +A -R · N file(s)` 页脚。各行使用 `white-space: pre` 并横向滚动，因此源码行保留其缩进而不软换行；超过 `maxLines`（默认 16，与 `TerminalBlock` 相同的切分算法）时折叠为头部切片加尾部切片，由展开按钮控制。新建（`oldText: null`）没有删除侧。复制控件写入带前缀的 diff 文本（路径头、`- `/`+ ` 行、gap），使多文件复制保持可归属，并浮在右上角而非占据自己的 banner 行。几何结构与 `CodeBlock`/`TerminalBlock` 一致。原理：[Web diff 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)。
 
 ## 搜索结果
 
@@ -30,7 +30,7 @@
 
 ## Web 检索
 
-`WebBlock` 渲染一次已完成的 web 检索，用一个组件绘制 `web` 渲染意图的两种 kind（由 `kind` 判别）。`search` 在有序引用列表上方显示可选的 provider answer（通过 `MarkdownText`）：每个 source 是一个安全外链，以其标题为标签，或以其主机名为标签，当 URL 无法解析或没有主机名（`file:`/`data:` URL）时回退到原始 URL，因此标签绝不为空；其下渲染 snippet 与发布日期。只有 http(s) URL 会成为锚点（设置 `target`/`rel`）——这是 `MarkdownText` 对不受信任链接所用 allowlist 的 http(s) 子集（该 allowlist 还允许 `mailto:`，此处排除）；任何其他 URL 渲染为纯文本。整份列表渲染在一个定高滚动容器里（`max-height: 320px`、`overflow-y: auto`），因此超出该高度的列表在原地纵向滚动，而不是把卡片撑高；`<li value>` 固定每个 source 的引用编号，从 1 起连续，而不依赖 `<ol>` 的隐式计数。当一次 search 合法地返回无 answer 且无 source 时，卡片显示一个明确的空状态提示，而不是空的 `<ol>`（chat 行不呈现原始 result content）。`fetch` 显示一个紧凑摘要：带链接的最终 URL 及其 HTTP 状态。两者都会标记一次被截断的检索。原理：[Web result 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)与[来源滚动笔记](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)。
+`WebBlock` 渲染一次已完成的 web 检索，用一个组件绘制 `web` 渲染意图的两种 kind（由 `kind` 判别）。`search` 在有序引用列表上方显示可选的提供方回答（通过 `MarkdownText`）：每个 source 是一个安全外链，以其标题为标签，或以其主机名为标签，当 URL 无法解析或没有主机名（`file:`/`data:` URL）时回退到原始 URL，因此标签绝不为空；其下渲染 snippet 与发布日期。只有 http(s) URL 会成为锚点（设置 `target`/`rel`）——这是 `MarkdownText` 对不受信任链接所用 allowlist 的 http(s) 子集（该 allowlist 还允许 `mailto:`，此处排除）；任何其他 URL 渲染为纯文本。整份列表渲染在一个定高滚动容器里（`max-height: 320px`、`overflow-y: auto`），因此超出该高度的列表在原地纵向滚动，而不是把卡片撑高；`<li value>` 固定每个 source 的引用编号，从 1 起连续，而不依赖 `<ol>` 的隐式计数。当一次 search 合法地返回无 answer 且无 source 时，卡片显示一个明确的空状态提示，而不是空的 `<ol>`（chat 行不呈现原始 result content）。`fetch` 显示一个紧凑摘要：带链接的最终 URL 及其 HTTP 状态。两者都会标记一次被截断的检索。原理：[Web result 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)与[来源滚动笔记](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)。
 
 ## 模型体验
 
@@ -46,5 +46,5 @@
 - **字形级图标是重新绘制的近似版本**：鱼形标志（以及 ui-conversation 持有的闪光图标）来自字体字形，而本地设计数据无法导出其矢量几何；在获得精确导出路径前，使用手工重建版本代替。
 - **Pill 与 Input 没有设计来源**：两个原子组件均自行定义；与其相似的侧边栏搜索字段和视图标签条由消费方组合，不是这些原子组件。
 - **StateDot 没有 `Active` 变体**：支持的状态为 done、warning、ongoing 和 error。
-- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收，默认值即此前的硬编码字符串。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费者渲染与本地化之前逐字节一致。`WebBlock` 尚未跟进这一模式：它的来源列表与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
+- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收，默认值即此前的硬编码字符串。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费者渲染与本地化之前逐字节一致。`WebBlock` 尚未跟进这一模式：它的来源列表截断提示与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
 - **`TerminalBlock` 不是终端模拟器**：它渲染已结束或仍在运行的命令输出，而不是交互式会话：SGR 颜色与属性会被遵循，进度行所用的行内光标移动同样被遵循——回车、退格、行内擦除、制表位与字符宽度。绝对光标定位、清屏与备用屏幕序列会被剥离。基础 16 色中的洋红与青色没有对应 token，保持字面 rgb。
diff --git a/packages/compact/README.i18n.yaml b/packages/compact/README.i18n.yaml
index bb5922ee75..bdbb81127c 100644
--- a/packages/compact/README.i18n.yaml
+++ b/packages/compact/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/compact/README.md
 README.md: 0a83b87f57e4c948ee6df9e622f17964aff00f0f
-README.zh.md: cba53ee7bb917a981a0fd4b77d833b8fb7dd2c3f
+README.zh.md: 431e84ec645ae08da203e2d68e1f6813dd7ded2d
diff --git a/packages/compact/README.zh.md b/packages/compact/README.zh.md
index cba53ee7bb..431e84ec64 100644
--- a/packages/compact/README.zh.md
+++ b/packages/compact/README.zh.md
@@ -11,6 +11,6 @@
 | [`compact-tool-result-prune/`](compact-tool-result-prune/README.md) | 可选的无模型工具结果修剪 | `ctx.toolResultPrune` |
 | [`command-compact/`](command-compact/README.md) | 用户压缩命令 | 注册到 `ctx.commands` |
 
-后端、可选修剪器和用户命令通过该 seam 组合；token 测量仍是独立的 LLM（大语言模型）家族服务。[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)负责依赖关系的设计原理。
+后端、可选修剪器和用户命令通过该 seam 组合；token 测量仍是独立的 LLM（大语言模型）家族服务。[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 负责说明依赖关系的设计依据。
 
-子系统参考——`compact/*` 事件、`CompactionResult`、服务、剪除结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
+子系统参考——`compact/*` 事件、`CompactionResult`、服务、修剪结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在 [压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
diff --git a/packages/context/README.i18n.yaml b/packages/context/README.i18n.yaml
index efb18426a4..b8025ef2bd 100644
--- a/packages/context/README.i18n.yaml
+++ b/packages/context/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/context/README.md
 README.md: 237f6191329f89834ec9bd9f72c0a1fd1d94651e
-README.zh.md: 7c55dd91dbf7e3fca222e4b6f6bed2769f5c253c
+README.zh.md: 653fd971a884e1b356e5a366d91f81caefd681c5
diff --git a/packages/context/README.zh.md b/packages/context/README.zh.md
index 7c55dd91db..653fd971a8 100644
--- a/packages/context/README.zh.md
+++ b/packages/context/README.zh.md
@@ -9,7 +9,7 @@
 | [`session-reference/`](session-reference/README.md) | 其他会话的有界快照 | `ctx.sessionReferences` |
 | [`time-context/`](time-context/README.md) | 当前时间与耗时上下文 | — |
 | [`tmux-context/`](tmux-context/README.md) | tmux 位置上下文 | — |
-| [`workspace-context/`](workspace-context/README.md) | workspace 指令上下文 | — |
+| [`workspace-context/`](workspace-context/README.md) | 工作区指令上下文 | — |
 
 [`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)解释其逐 agent（智能体）／会话隔离和生命周期拆分。
 
diff --git a/packages/core/README.i18n.yaml b/packages/core/README.i18n.yaml
index aa542fe885..ff41da1511 100644
--- a/packages/core/README.i18n.yaml
+++ b/packages/core/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/README.md
 README.md: 40a888183a9338805d83c86bab9ae16f1c7bc04f
-README.zh.md: 496d547a173a63ac9d8d2ce0f005877dab92d358
+README.zh.md: c0a24d78cb8ff2a2b2ccc2d2a2f4294424be55b0
diff --git a/packages/core/README.zh.md b/packages/core/README.zh.md
index 496d547a17..c0a24d78cb 100644
--- a/packages/core/README.zh.md
+++ b/packages/core/README.zh.md
@@ -17,4 +17,4 @@
 
 可运行组合属于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)；该分组只负责可替换的主干组件。
 
-子系统参考——逐包循环地图、`Agent` 句柄及其投递/拦截契约——见 [docs/subsystems/core.md](../../docs/subsystems/core.md)；默认可运行组合是 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)。
+子系统参考——逐包循环地图、`Agent` 句柄及其投递/拦截约定——见 [docs/subsystems/core.md](../../docs/subsystems/core.md)；默认可运行组合是 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)。
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index fb18353290..f80bc0cc79 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent-loop/README.md
 README.md: 81bc4411977f7335defef5af82d4a67a740b2ed5
-README.zh.md: c190171513e17777ebaadda0d279487876a412b4
+README.zh.md: f14810ecf56f80c1f2a768aaf315415159e2c021
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index c190171513..f14810ecf5 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -10,7 +10,7 @@
 
 ### 公开 API
 
-创建与恢复属于同一个受回滚保护的事务：构造私有会话、实体 agent 和带作用域的上下文；等待可选 setup；进入两个注册表；依次宣告 `session/created` 和 `agent/created`；发出 `agent/session-start`；此后才启动驱动器。Setup 接收完整的带作用域 `Context`，作为受信任的同进程组合代码，并且不得驱动尚未发布的 agent。普通的类型化身份与选项输入遵循只读契约以借用方式传入；seed 事件与会话元数据会跨越持久会话边界，因此系统会验证并快照它们。可选的 `AbortSignal` 只取消加载／setup／发布，并在返回的 handle 可见前分离。
+创建与恢复属于同一个受回滚保护的事务：构造私有会话、具体 agent 和带作用域的上下文；等待可选 setup；进入两个注册表；依次宣告 `session/created` 和 `agent/created`；发出 `agent/session-start`；此后才启动驱动器。Setup 接收完整的带作用域 `Context`，作为受信任的同进程组合代码，并且不得驱动尚未发布的 agent。普通的类型化身份与选项输入遵循只读约定以借用方式传入；seed 事件与会话元数据会跨越持久会话边界，因此系统会验证并快照它们。可选的 `AbortSignal` 只取消加载／setup／发布，并在返回的 handle 可见前分离。
 
 调用方 fiber 与 AgentLoop 提供方共同拥有 agent。`AgentFactory.createAgent(ownerCtx, options)` 与 `resume(ownerCtx, options)` 显式接收调用方所有权，而工厂为 `sessions`/`llm`/`tools`/`systemPrompt` 保留自身的依赖上下文；这样，调用方可以只注入 `agents`，而不会缩减新 agent 的服务接口。调用方卸载、handle dispose（资源释放）或提供方卸载都会汇合到同一个记忆化的完全停稳边界。提供方关闭会同时等待资源 teardown，以及已经观测到停用的公开 create/resume 包装层，因此依赖消失后，任何 continuation 都无法继续发布。
 
@@ -53,11 +53,11 @@ interface Config {
 
 ### 包内部具体驱动器
 
-实体 `ReactLoopAgent`、其 inbox 与运行控制均为包内部实现。包根只导出插件／服务／配置契约，包导出映射不提供 `./src/*` 逃逸路径；生命周期拥有方通过 `ctx.agents` 创建 agent，而不是点名、构造或启动驱动器内部组件。一个准备完成的会话只能由一个实体驱动器认领；所有可观测行为都通过会话事件和 `agent/*` 事件分类体系发生。
+具体 `ReactLoopAgent`、其 inbox 与运行控制均为包内部实现。包根只导出插件／服务／配置约定，包导出映射不提供 `./src/*` 逃逸路径；生命周期拥有方通过 `ctx.agents` 创建 agent，而不是点名、构造或启动驱动器内部组件。一个准备完成的会话只能由一个具体驱动器认领；所有可观测行为都通过会话事件和 `agent/*` 事件分类体系发生。
 
-统一的 `send()` 原语按（`target` × `wakeup`）路由内容与来源；`followup`/`steer`/`inject` 是它的固定预设别名。`followup()` 追加到 `next-turn` FIFO 并唤醒驱动器，`steer()` 追加到 `next-step` inbox 并唤醒驱动器，`inject()` 则追加到同一个 `next-step` inbox，但不唤醒驱动器。在轮次边界，驱动器会先打开持久轮次，再原子领取待处理的 next-step 输入和一条排队提示词；在步骤之间则只领取 next-step 输入。领取通过纯删除 splice 移除批次，并针对每条消息发出 `agent/inbox/claimed { message, turn }`。随后 `agent/pre-step` 返回 reject，或返回拟进入步骤的完整消息。reject 后已领取批次保持已删除，并关闭不含步骤的轮次；领取后插入的输入仍等待后续处理，而空闲注入会一直等待，直到 follow-up 或 steering 唤醒驱动器。
+统一的 `send()` 原语按（`target` × `wakeup`）路由内容与来源；`followup`/`steer`/`inject` 是它的固定预设别名。`followup()` 追加到 `next-turn` FIFO 并唤醒驱动器，`steer()` 追加到 `next-step` inbox 并唤醒驱动器，`inject()` 则追加到同一个 `next-step` inbox，但不唤醒驱动器。在轮次边界，驱动器会先打开持久轮次，再原子领取待处理的 next-step 输入和一条排队提示词；在步骤之间则只领取 next-step 输入。领取通过纯删除 splice 移除批次，并针对每条消息发出 `agent/inbox/claimed { message, turn }`。随后 `agent/pre-step` 返回拒绝结果，或返回将进入拟议步骤的完整消息。拒绝后，已领取批次保持已删除，并关闭不含步骤的轮次；领取后插入的输入仍等待后续处理，而空闲注入会一直等待，直到 follow-up 或 steering 唤醒驱动器。
 
-每次 inbox 变更都会先发布一条规范化的 `agent/inbox/spliced` 事件，再修改实时投影。因此，插入、编辑、移除、领取与取消都通过同一组标准 splice 坐标回放。普通删除携带 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`；领取使用不带 outcome 的纯删除，随后由循环发出 `agent/inbox/claimed`。每次插入都会发出 `agent/inbox/inserted { message }`。`MessageId` 在两个待处理列表之间保持唯一，同步持久事件观察方可以从 splice 前投影重建被移除的值。
+每次 inbox 变更都会先发布一条规范化的 `agent/inbox/spliced` 事件，再修改实时投影。因此，插入、编辑、移除、领取与取消都通过同一组标准 splice 坐标回放。普通删除携带 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`；领取使用不带 outcome 的纯删除，随后由循环发出 `agent/inbox/claimed`。每次插入都会发出 `agent/inbox/inserted { message }`。`MessageId` 在两个待处理列表之间保持唯一，持久事件的同步观察方可以从 splice 前投影重建被移除的值。
 
 ### 循环生命周期（`agent.ts`）
 
@@ -67,7 +67,7 @@ interface Config {
 
 在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的字段，并填入配置的推理（reasoning）强度和输出 token 默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。请求 header 会记录生效配置以及哪些字段来自适配器。下一次 waterfall（瀑布式事件）前，循环会从提议中移除这些带标记字段，使当前精确路由重新填入自身默认值；未带标记的显式设置会跨步骤和路由变化保留。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例在恢复时会应用同一来源规则。
 
-插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会由 `ctx.llm` 作为终止 error 或 aborted finish 返回，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。abort 触发后、活动收敛到空闲前到达的唤醒输入会被锁存（`wakeRequested`），并在 driver 自身的收敛边界重放，无需再发一条唤醒 send 即可执行；`disposed` 取消从不锁存，而 agent 已处于空闲时发送的唤醒总是打开自己的 turn 边界（即使消息已被清除，状态也会显示瞬态 `idle → running → idle` 对）。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose（资源释放）则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)与[取消收敛窗口唤醒锁存](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)规定生命周期与竞态契约。
+插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会以终止错误或中止结束的形式由 `ctx.llm` 传来，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。abort 触发后、活动收敛到空闲前到达的唤醒输入会被锁存（`wakeRequested`），并在 driver 自身的收敛边界重放，无需再发一条唤醒 send 即可执行；`disposed` 取消从不锁存，而 agent 已处于空闲时发送的唤醒总是打开自己的 turn 边界（即使消息已被清除，状态也会显示瞬态 `idle → running → idle` 对）。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose 则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)与[取消收敛窗口唤醒锁存](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)规定生命周期与竞态约定。
 
 在步骤内，独占调用形成屏障；并行安全调用使用有界滚动池，并在启动前重新分类。只有分发／主体会重叠。策略、持久结果和结果上下文仍保持模型顺序。中止会停止新调用，drain 已启动的结果，并保留其已定案的结果上下文，不区分取消原因。内部调度器故障会停止新的分发，等待已启动的分发，然后在不虚构工具结果的情况下到达轮次错误边界。
 
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index 4c6009d3b0..b2d54ebc66 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent/README.md
 README.md: 3a3bdf6a4b3bdc5bfef250495e84b7d90b003822
-README.zh.md: 8164829e18ddd89fd84c0c2b5e033fd69241b9aa
+README.zh.md: 4295c15923f6a5c6132369bfe2137e3d34dec6b1
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index 8164829e18..4295c15923 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -50,7 +50,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序契约。
 
-大多数拦截点都是协作式 waterfall（瀑布式事件）。`agent/pre-step` 接收一个 payload，携带主体 `agent`、独占的已领取 `UserMessage[]` 以及拟进入的 `turn`、`step` 与取消 `signal`；当工具已经要求继续请求时，该批次可以为空。agent 作用域轮次 seam 在 payload 中携带显式 `AbortSignal`；其余轮次作用域 seam 通过其请求值接收它。监听器可以配合信号，但不得将它保留为控制另一轮次的权限。`agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
+大多数拦截点都是协作式 waterfall（瀑布式事件）。`agent/pre-step` 接收一个 payload，携带主体 `agent`、独占的已领取 `UserMessage[]` 以及拟进入的 `turn`、`step` 与取消 `signal`；当工具已经要求继续请求时，该批次可以为空。agent 作用域轮次 seam 在 payload 中携带显式 `AbortSignal`；其余轮次作用域 seam 通过其请求值接收它。监听器可以配合信号，但不得将它保留为控制另一轮次的权限。`agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域运行时设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
 
 `PreStepDecision` 要么是 `{ kind: 'reject' }`，要么是 `{ kind: 'enter', messages }`。enter 分支是拟进入步骤的完整、带标识且冻结的批次。包装下游 enter 的监听器会保留该批次，除非有意替换它；新增消息遵循 waterfall 的自然返回顺序。领取操作已经把候选消息从 inbox 删除，因此 reject 不会保留它们；领取后插入的消息仍等待后续边界。
 
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index 8b1e462166..abb9bfc6f2 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/session/README.md
 README.md: 00e007ee6064f485bf80dfda0227ab6e834f6414
-README.zh.md: 5f06fee5d50bc2c9dc333874a8354fbf19d5248b
+README.zh.md: e9d074f52db46cb42e497ad1ef49c2b37a6ec7d8
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index 5f06fee5d5..e9d074f52d 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -62,7 +62,7 @@
 
 `request/header` 记录非历史请求封装的完整规范快照，其原因为 `initial`、`resume` 或 `change`。其可选 `adapterDefaults` 映射会标记由精确模型解析填入的生效 `reasoningEffort` 或 `maxTokens` 值，使下一次请求提议能够将它们与显式对话设置区分开。`foldRequestHeader()` 选择最新快照；旧版增量事件和已移除的 `fallback` 原因会被拒绝。详见[可重建请求 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
 
-`user/message` 会直接存储完整的 `UserMessage`，其中包括路由或 pre-step 领取前创建的标识。无论它是直接人类提示词、合成注入，还是进入步骤的 Goal Round，都会原样呈现其 `content`；带类型的 `source` 是区分三者的唯一通道，并携带各领域专有的持久事实。`assistant/message` 和 `tool/result` 也会存储完整的消息值。轮次执行仍由 `turn/start` 与 `turn/end` 包围；`agent.inject()` 会把输入排队，直到某次 pre-step 返回 enter 并在轮次内记录它。
+`user/message` 会直接存储完整的 `UserMessage`，其中包括收件箱路由或进入步骤前创建的标识。无论它是直接人类提示词、合成注入，还是已进入的 Goal Round，都会原样呈现其 `content`；带类型的 `source` 是区分三者的唯一通道，并携带各领域专有的持久事实。`assistant/message` 和 `tool/result` 也会存储完整的消息值。轮次执行仍由 `turn/start` 与 `turn/end` 包围；`agent.inject()` 会把输入排队，直到后续某次 pre-step 领取它，并在 enter 决策中返回它。
 
 `tool/result` 持久保存一条带标识、user-role 的工具结果消息，以及可选内部失败标识和可选呈现元数据。工具成功时的规范 `value` 和便于人类阅读的规范失败消息只存在于执行本地；渲染后的错误内容是回放权威消息。
 
@@ -72,7 +72,7 @@
 
 `SessionEventMap` 可通过合并扩展：插件使用声明合并添加自身类型（压缩 seam 的 `compact/*`、有界恢复的非 surface `llm/retry`、hook（钩子）桥接层的 `hook/*`）；合并成员会出现在同一目录中。插件拥有其合并事件的关系不变量，包括是否允许纯日志事件出现在轮次之间。需要持久性的生产方通过 `Session` 追加，再等待 `ctx.sessions.flush(session)`，无需虚构一个执行轮次。
 
-此包还定义 `TurnEndReasonMap`，即用于轮次结束、可合并扩展且以 `kind` 为标签的和类型。`turn/start` 只携带轮次编号；之后进入步骤的 `user/message` 批次记录其输入，`llm/retry` 则记录请求恢复。
+此包还定义 `TurnEndReasonMap`，即用于轮次结束、可合并扩展且以 `kind` 为标签的和类型。`turn/start` 只携带轮次编号；随后已进入的 `user/message` 批次记录其输入，`llm/retry` 则记录请求恢复。
 
 被中断的实时轮次以 `{ kind: 'aborted', reason: AgentCancelCause }` 结束，在持久 transcript（文本记录）中保留类型化取消原因。持久化会将受支持旧格式中的粗粒度中止结果导入为 `{ kind: 'aborted', reason: { kind: 'legacy' } }`，因为该记录没有保留调用方。轮次失败携带 `{ kind: 'error', error }`；只有崩溃恢复会合成 `{ kind: 'interrupted' }`。
 
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index c94d1722dc..e4caa9b815 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/system-prompt/README.md
 README.md: e98c45a8829a945500ef5282d84e1904b31c68bf
-README.zh.md: 5b9e2feaf82866a52cd8197ff5e800decdf3ee7e
+README.zh.md: 5a838f4ed3cb1f57ecd9f41325e1612afaf5103a
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index 5b9e2feaf8..5a838f4ed3 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -36,7 +36,7 @@
 
 ### 扩展点
 
-- 段提供方：工具包（package）拥有跨调用引导（`tool:bash`、`tool:read` 等）；此插件拥有 `harness:identity` 与 `deployment:persona`。
+- 段提供方：工具包拥有跨调用引导（`tool:bash`、`tool:read` 等）；此插件拥有 `harness:identity` 与 `deployment:persona`。
 - 变量提供方：agent loop（智能体循环）注册 `model` 与 `cwd`；任何插件都可以注册自己拥有的事实（未来的 `date`、git 状态等）。
 - 工具 schema 提供方：`ToolRegistry` 自动将自身注册为工具提供方。
 - [`system-prompt/assemble` waterfall](#live-events)：按调用方协作式修改或替换组装结果。
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index b19e86ce84..b257ecbfa6 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/tools/README.md
 README.md: f3f25f908a4ba8016d38f7777fe72691dba4afb1
-README.zh.md: 796ee8e1aa8de88f979d825df5e0b4f39ab7bcf1
+README.zh.md: 675d9299037bc5225fcd117148c574eb646cf680
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 796ee8e1aa..675d929903 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -13,7 +13,7 @@ tools:
   mode: native   # native (default) | code | both
 ```
 
-`native` 以函数定义的形式贡献可见工具。`code` 贡献保留的 `run_code` 传输和生成的 `tools:sdk` 段；`both` 同时贡献两种形式。不能注册、遮蔽、限制或移除该保留传输。非原生模式要求所加载 `ctx.codeRuntime` 的 `language` 有已注册的 SDK 渲染器——TypeScript 经 [`dsh-code-runtime-worker`](../../code-runtime/code-runtime-worker/README.md) 交付；Python 渲染器内置，驱动任何报告 `language: 'python'` 的运行时（第一方 `dsh-code-runtime-python` 后端另行交付）。没有渲染器的运行时语言会让提示词组装响亮失败；如果 `systemPrompt.toolOrder` 条目指向当前模式未贡献的工具，系统会拒绝组装提示词。`system-prompt/assemble` 监听器可以替换注册表贡献；它返回的组装结果具有权威性，因此该监听器负责保留可用的 Code Mode 协议。
+`native` 以函数定义的形式贡献可见工具。`code` 贡献保留的 `run_code` 传输和生成的 `tools:sdk` 段；`both` 同时贡献两种形式。不能注册、遮蔽、限制或移除该保留传输。非原生模式要求所加载 `ctx.codeRuntime` 的 `language` 有已注册的 SDK 渲染器——TypeScript 经 [`dsh-code-runtime-worker`](../../code-runtime/code-runtime-worker/README.md) 交付；Python 渲染器内置，驱动任何报告 `language: 'python'` 的运行时（第一方 `dsh-code-runtime-python` 后端另行交付）。没有渲染器的运行时语言会导致提示词组装明确失败；如果 `systemPrompt.toolOrder` 条目指向当前模式未贡献的工具，系统会拒绝组装提示词。`system-prompt/assemble` 监听器可以替换注册表贡献；它返回的组装结果具有权威性，因此该监听器负责保留可用的 Code Mode 协议。
 
 ### 公开 API
 
@@ -114,7 +114,7 @@ ctx.tools.register(defineTool({
 
 ### Code Mode
 
-在 `code` 或 `both` 模式下，注册表为当前作用域公开保留的 `run_code` 传输和按所加载运行时语言生成的确定性 SDK——注册表按 `ctx.codeRuntime.language` 选择渲染器（`typescript` → 下方的 TypeScript SDK，`python` → Python SDK）。只有程序的外层日志与返回值会重新进入模型上下文。SDK 为每个可见工具声明精确的参数与规范输出类型（TypeScript 为 `ToolArgsMap`/`ToolOutputMap`，Python 为具名 `TypedDict`），每个绑定都会解析为该工具的规范 JSON 值。每个无损 JSON 绑定调用都会在原生调度契约下重新进入完整工具流水线（并发安全的调用最多可重叠 `maxParallelSubCalls` 个；独占调用单独运行并构成排序屏障），并在日志中与外层调用建立关联。拒绝及其他失败结果会以程序实际可见的 `ToolCallError` 形式拒绝，且只携带 `toolName` 和 `message`；Native 内容和内部错误码留在 Code 契约之外。普通副作用不会回滚，子调用的 `additionalContexts` 会通过父结果延迟，以保持调用／结果相邻。运行结算会中止并排空尚未完成的绑定；运行时失败以 `CodeRunFailedError` 形式出现。参见 [Code Mode 基础](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)、[类型化返回契约](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)和[代码运行时 seam](../../code-runtime/README.md)。可以运行 `pnpm run demo:code-mode` 试用。
+在 `code` 或 `both` 模式下，注册表为当前作用域公开保留的 `run_code` 传输和按所加载运行时语言生成的确定性 SDK——注册表按 `ctx.codeRuntime.language` 选择渲染器（`typescript` → 下方的 TypeScript SDK，`python` → Python SDK）。只有程序的外层日志与返回值会重新进入模型上下文。SDK 为每个可见工具声明精确的参数与规范输出类型（TypeScript 为 `ToolArgsMap`/`ToolOutputMap`，Python 为具名 `TypedDict`），每个绑定都会解析为该工具的规范 JSON 值。每个无损 JSON 绑定调用都会在原生调度约定下重新进入完整工具流水线（并发安全的调用最多可重叠 `maxParallelSubCalls` 个；独占调用单独运行并构成排序屏障），并在日志中与外层调用建立关联。拒绝及其他失败结果会以程序实际可见的 `ToolCallError` 形式拒绝，且只携带 `toolName` 和 `message`；Native 内容和内部错误码留在 Code 约定之外。普通副作用不会回滚，子调用的 `additionalContexts` 会通过父结果延迟，以保持调用／结果相邻。运行结算会中止并排空尚未完成的绑定；运行时失败以 `CodeRunFailedError` 形式出现。参见 [Code Mode 基础](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)、[类型化返回契约](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)和[代码运行时 seam](../../code-runtime/README.md)。可以运行 `pnpm run demo:code-mode` 试用。
 
 - **SDK 段**（`tools:sdk`，顺序 150）：一个惰性提示词段，每次组装时都会重新生成与所加载运行时语言相符的 SDK 文本。TypeScript 形态发出 `JsonValue`、精确的 `ToolArgsMap` / `ToolOutputMap`、`ToolName`、`ToolCallError` 声明、面向调用作用域可见最终能力的映射 `tools` 命名空间（特殊名称使用带引号的键），以及固定用法说明；Python 形态（`ctx.codeRuntime.language === 'python'`）发出等价的具名 `TypedDict` 与一个带相同用法说明的 `tools` 对象。其输出具有确定性：工具按字典序排列；工具集合不变时，文本逐字节相同（有利于前缀 cache）。两个代码生成器都已导出，且绝不会在提示词组装期间抛出：`jsonSchemaToTs` 处理统一 schema 的每种构造并将不受支持的原始构造降级为 `unknown`；`jsonSchemaToPy` 同理，降级为 `Any`（当某字段名不是合法的 `TypedDict` 属性时，或在 SDK 渲染之外被调用时——`TypedDict` 声明所需的命名上下文由该渲染提供——整个对象降级为 `dict[str, Any]`）。
 - **分发桥接层**（`run_code` 的 execute）：每个绑定调用都会在分发前快照为无损 JSON（`undefined`、`BigInt`、循环、稀疏数组、`-0` 和特殊对象会使该次调用被拒绝），经由每次运行独有、复用原生并发契约的池调度——调用严格按提交顺序启动，连续的 `isConcurrencySafe` 调用最多可重叠经校验的 `maxParallelSubCalls` 配置个（默认 10；设为 `1` 即恢复串行分发），被分类为独占的调用先排空池、单独运行并阻挡其后的调用——以外层执行的不透明 token 作为 `parent`，并经过完整的 pre-execute → guards → execute → post-execute → result 流水线。成功会返回策略处理后的最终规范值；失败以一条消息到达 worker，并成为 `ToolCallError(toolName, message)`。每个已启动的子调用在进入流水线时记录一条 `tool/code-dispatch-start` 事件（确定性 id `<parent>:code:<n>`，按提交顺序编号），并以一条携带完整模型可见 `content`/`isError` 结果的 `tool/code-dispatch` 事件完结（采用 `tool/result` 词汇，因此 UI 会沿原生路径呈现子调用——这对事件的 `time` 字段承载每个子调用的计时）；因 run 结算而被放弃的排队调用两者都不记录。`deriveMessages()` 既不公开这两个事件，也不持久化规范值。token 关联让以提交为语义的观察器能够把内部成功延迟到最终 `run_code` 结果，而无需公开实时外层执行；普通工具副作用不会回滚。每个子调用的 `additionalContexts` 条目都会按分发顺序通过外层 `ToolRunContext` 延迟；循环只在父级 `run_code` 结果之后追加这些上下文，从而保持相邻关系，并且即使程序后来失败，也会保留各自的来源／元数据。
diff --git a/packages/examples/jsonrpc-demo/README.i18n.yaml b/packages/examples/jsonrpc-demo/README.i18n.yaml
index c47938ce3b..5660d73494 100644
--- a/packages/examples/jsonrpc-demo/README.i18n.yaml
+++ b/packages/examples/jsonrpc-demo/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/examples/jsonrpc-demo/README.md
 README.md: fff8e78698cd3d6320606084ef5c533be7c52633
-README.zh.md: 75382b97ea1837cf1415e8a7f5004206596e168c
+README.zh.md: 207717c27ac7a0f91eaf888d7aed4ded1adef67c
diff --git a/packages/examples/jsonrpc-demo/README.zh.md b/packages/examples/jsonrpc-demo/README.zh.md
index 75382b97ea..207717c27a 100644
--- a/packages/examples/jsonrpc-demo/README.zh.md
+++ b/packages/examples/jsonrpc-demo/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)交付。
+只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) 交付。
 
 ## 配置发现
 
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index b1e493f3c8..aa010c33f2 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/README.md
 README.md: 162e2c75e92bc4ea6aba377c14db62e8ce83fbb9
-README.zh.md: b2929b17be6ce90051f0808c2cdf4bbf643f8f13
+README.zh.md: 196a2aad89203905148581d6364be7f02e2f4e35
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index b2929b17be..196a2aad89 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -2,22 +2,22 @@
 
 [English](README.md) | 中文
 
-文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品** 包。
+文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、策略门禁插件（已观察状态、编辑前读取、版本防护的写入／编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品**包。
 
 | 包 | 角色 | ctx 键 |
 |---|---|---|
-| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
+| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 策略事件 | `ctx.fs` |
 | `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
 | [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
-| `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
-| `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
+| `fs-sandbox/` | 强制实施沙箱约束的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根策略约束写入／编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
+| `fs-policy/` | 策略门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
 | `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、策略门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。策略（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去策略，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索约定；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
 
 ## 文件 I/O 不设超时
 
 `read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
 
-子系统参考——目标、结果、防护、策略事件、错误分类体系，以及文件 IO 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
+子系统参考——目标、结果、守卫、策略事件、错误分类体系，以及文件 I/O 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index d9b0010670..8141819240 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/fs/README.md
 README.md: 5c58fc476b9b11a83bbe0d6c33ac782d94d6ffbc
-README.zh.md: 97d7104f3c4c0beca408397f9cb1cead39b0a76e
+README.zh.md: 32faf67d6ed97914704ea5683f1fd987e2e64a93
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 97d7104f3c..32faf67d6e 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -2,18 +2,18 @@
 
 [English](README.md) | 中文
 
-**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
+**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
 
 本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
 
 | 层 | 包 | 角色 |
 |---|---|---|
 | 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 `read`/`write`/`edit` schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
-| 政策 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
+| 策略 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
 | 提供方 seam | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
 | 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
 
-未来的沙箱化、虚拟或远程后端只需实现该接口，政策层和工具层无需改变。
+未来的沙箱化、虚拟或远程后端只需实现该接口，策略层和工具层无需改变。
 
 ## 服务 API（`ctx.fs`）
 
@@ -26,7 +26,7 @@
 | `fileUrl(target)` | 返回采用执行世界平台语法的规范化 `file:` URI。编码由后端而非宿主进程负责。 |
 | `contains(parent, child)` | 在不公开或解析目标 key 的情况下，检查规范化身份相等或后代包含关系。两个目标都来自该提供方。 |
 | `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
-| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
+| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库自有的符号链接进入目标前拒绝它。 |
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
 | `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
 | `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
@@ -35,15 +35,15 @@
 
 无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
 
-## `fs/*` 政策事件
+## `fs/*` 策略事件
 
-本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和策略监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖策略插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
-## 提供方 seam，不是政策层
+## 提供方 seam，不是策略层
 
-`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使政策层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不** 负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的政策，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
+`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
 
-`editText` 留在该 seam 上，不由政策层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
+`editText` 留在该 seam 上，不由策略层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
 
 ## 词汇
 
@@ -55,11 +55,11 @@
 
 #### KV Cache 影响
 
-不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
+不会直接使缓存失效；上述消费方负责请求前缀的任何变化。
 
-## 已知限制与延期工作
+## 已知限制与暂缓事项
 
-- **契约只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
+- **约定只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
 - **只有十一个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
 - **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见有意采用的 [fs 能力族立场](../README.md)）。
 - **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。
diff --git a/packages/goal/README.i18n.yaml b/packages/goal/README.i18n.yaml
index d2a6bf0248..db694ef162 100644
--- a/packages/goal/README.i18n.yaml
+++ b/packages/goal/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/README.md
 README.md: 9d307278b39ecee61df9feace9fec4235b45d794
-README.zh.md: 7217c174ba5382c53204ae3678be42375fc63db5
+README.zh.md: fec870751b1f331bf4d09dcbee04d977183064ad
diff --git a/packages/goal/README.zh.md b/packages/goal/README.zh.md
index 7217c174ba..fec870751b 100644
--- a/packages/goal/README.zh.md
+++ b/packages/goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-agent 会话的持久目标状态，独立于消费它的模型工具与续跑策略。goal 状态是所属会话日志的一部分；消费方依赖 `dsh-goal`，绝不依赖具体 agent loop。
+agent 会话的持久目标状态，独立于消费它的面向模型工具与续行策略。goal 状态是所属会话日志的一部分；消费方依赖 `dsh-goal`，绝不依赖具体的 agent loop（智能体循环）。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
diff --git a/packages/goal/command-goal/README.i18n.yaml b/packages/goal/command-goal/README.i18n.yaml
index 8f238d7429..90285c2860 100644
--- a/packages/goal/command-goal/README.i18n.yaml
+++ b/packages/goal/command-goal/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/command-goal/README.md
 README.md: 1ac1b8a0e2cb360708b1759ab5eb9ec3de597821
-README.zh.md: cc5f7ba9bd3c5e50d3b7ce204d8d8c400e4f0955
+README.zh.md: 82750a102784fad7da1038a97478880f60001bdf
diff --git a/packages/goal/command-goal/README.zh.md b/packages/goal/command-goal/README.zh.md
index cc5f7ba9bd..82750a1027 100644
--- a/packages/goal/command-goal/README.zh.md
+++ b/packages/goal/command-goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md)负责用户体验与组合决策。
+面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md) 负责用户体验与组合决策。
 
 ## 命令契约
 
@@ -40,7 +40,7 @@
 
 #### 模型看到的内容
 
-斜杠输入、变更以及直接状态／错误输出不会进入模型请求。Goal 领域把变更记录为 `goal/change`；已启用的同会话驱动器可以在后续继续执行提示词中暴露结果状态。呈现文本绝不会记录到日志中。
+斜杠输入、变更以及直接状态／错误输出不会进入模型请求。goal 领域把变更记录为 `goal/change`；已启用的同会话驱动器可以在后续继续执行提示词中暴露结果状态。呈现文本绝不会记录到日志中。
 
 #### Token 影响
 
diff --git a/packages/goal/goal/README.i18n.yaml b/packages/goal/goal/README.i18n.yaml
index d8fbf8fc29..5593953d89 100644
--- a/packages/goal/goal/README.i18n.yaml
+++ b/packages/goal/goal/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/goal/README.md
 README.md: 98765a809820bcd4aeba31e1dd4ef6e92eb30760
-README.zh.md: dbc499104bac6cf09f9b1c871143da8781a8f082
+README.zh.md: 7f59fc4b538ad68bfcf0686b7651d0ec64470c2e
diff --git a/packages/goal/goal/README.zh.md b/packages/goal/goal/README.zh.md
index dbc499104b..7f59fc4b53 100644
--- a/packages/goal/goal/README.zh.md
+++ b/packages/goal/goal/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前完成目标，同时将继续执行的权限作为进程本地续行启用状态。[goal 领域 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) 负责设计理由；[goal 类型目录](../../../docs/subsystems/goal.md)记录具体的数据形状。
+事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前待完成目标，同时将继续执行的权限作为进程本地续行启用状态。[goal 领域 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) 负责设计理由；[goal 类型目录](../../../docs/subsystems/goal.md)记录具体的数据形状。
 
 ## 配置
 
@@ -17,7 +17,7 @@
 
 ## 服务契约
 
-`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回分离的 `GoalView`；变更通过 `GoalRef { id, revision }` 比较并设置限制，并拒绝陈旧引用。服务通过 [goal.md](../../../docs/subsystems/goal.md#cordis-surface) 的生成区块公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发送变更事件。
+`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回与内部状态脱离的 `GoalView`；变更以 `GoalRef { id, revision }` 作为比较并设置防护，并拒绝陈旧引用。服务通过 [goal.md](../../../docs/subsystems/goal.md#cordis-surface) 的生成区块公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发出变更。
 
 最多只有一个当前目标。创建操作会生成 revision 为 1、phase 为 active 的目标并启用续行。未完成的目标必须编辑、转换或清除；已完成目标可以由拥有全局未使用过的 id 的目标替换。编辑会保留 phase、blocker reason 与 activation。暂停、完成、阻塞和清除都会停用续行。阻塞会记录策略自有的 lower-kebab-case 代码和规范化的自由文本说明；提供方限制、配置预算、执行错误与请求人工输入都使用这一种持久 phase，不会扩增生命周期状态。只有配置的 Round 上限仍有剩余容量时，resume 才接受已停止 phase 或 phase 为 active 但已停用续行的目标；它会清除原 blocker reason。phase 为 active 且已启用续行的目标会拒绝冗余操作。
 
@@ -43,7 +43,7 @@ Goal 变更不会注入模型上下文。`get_goal` 等工具返回当前状态
 
 #### Token 影响
 
-Goal 变更事件本身不增加模型 token。工具结果与已调度的继续执行提示词分别计入其自身暴露的状态。
+Goal 变更事件本身不增加模型 token。工具结果和续行调度提示词各自暴露的状态会分别计入 token 用量。
 
 #### KV Cache 影响
 
diff --git a/packages/guard/README.i18n.yaml b/packages/guard/README.i18n.yaml
index b99cec734b..3097eeba3b 100644
--- a/packages/guard/README.i18n.yaml
+++ b/packages/guard/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/guard/README.md
 README.md: f0a80b1f497ee5b2459bebb55f886b42d74e4323
-README.zh.md: c7747e2febcb1656925fd556743eb2dd28090e37
+README.zh.md: 43f60599b737d66578b463386b872ca9cc3108e4
diff --git a/packages/guard/README.zh.md b/packages/guard/README.zh.md
index c7747e2feb..43f60599b7 100644
--- a/packages/guard/README.zh.md
+++ b/packages/guard/README.zh.md
@@ -1,8 +1,8 @@
-# guard/ — 循环卫生 guard 家族
+# guard/ — 循环健康 guard 家族
 
 [English](README.md) | 中文
 
-行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并强制执行单次调用预算。guard 是 core seam 的自包含消费方，而非可替换能力。
+行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并强制执行单次调用预算。guard 是核心 seam 的自包含消费方，而非可替换能力。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/host/README.i18n.yaml b/packages/host/README.i18n.yaml
index 0859a2571d..3eb8fe7eb8 100644
--- a/packages/host/README.i18n.yaml
+++ b/packages/host/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/README.md
 README.md: 926cb0b6b87a8ee76cb2dab745a31f620f4e7f5c
-README.zh.md: dc617084c756b80716f9a02bd2d22ba6954030f6
+README.zh.md: 7ef057ee56e56ddc2baa7092ccbe44fb161b7448
diff --git a/packages/host/README.zh.md b/packages/host/README.zh.md
index dc617084c7..7ef057ee56 100644
--- a/packages/host/README.zh.md
+++ b/packages/host/README.zh.md
@@ -6,14 +6,14 @@ dsh Web GUI 的宿主侧：所有客户端形态共享的 API 网关，以及承
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`apiproxy/`](apiproxy/README.md) | 共享宿主 API 网关和协议契约 | `ctx.apiProxy` |
+| [`apiproxy/`](apiproxy/README.md) | 共享宿主 API 网关和协议约定 | `ctx.apiProxy` |
 | [`webserver/`](webserver/README.md) | HTTP 路由载体 | `ctx.httpServer` |
 | [`frontend-static/`](frontend-static/README.md) | 占据 webserver 回退席位的 SPA dist 服务器 | 消费 `ctx.httpServer` |
-| [`directory-picker/`](directory-picker/README.md) | workspace 目录选择 seam | `ctx.directoryPicker` |
+| [`directory-picker/`](directory-picker/README.md) | 工作区目录选择 seam | `ctx.directoryPicker` |
 | [`directory-picker-native/`](directory-picker-native/README.md) | 原生目录选择器后端和浏览器交互 | 注册 `ctx.directoryPicker` |
 | [`directory-picker-browse/`](directory-picker-browse/README.md) | 应用内目录浏览器后端和交互 | 注册 `ctx.directoryPicker` |
 | [`directory-picker-auto/`](directory-picker-auto/README.md) | 宿主自适应选择器组合 | 挂载一个后端 |
 
 `apiproxy` 保持传输无关；[`client/connection`](../client/connection/README.md) 提供浏览器／HTTP 载体。选择器实现可在共享 seam 后互相替换。
 
-子系统参考：[http-server.md](../../docs/subsystems/http-server.md) 与 [workspace.md](../../docs/subsystems/workspace.md)（挑选 seam）。
+子系统参考：[http-server.md](../../docs/subsystems/http-server.md) 与 [workspace.md](../../docs/subsystems/workspace.md)（选择器 seam）。
diff --git a/packages/llm/README.i18n.yaml b/packages/llm/README.i18n.yaml
index a35bf870d4..a3ccfcf944 100644
--- a/packages/llm/README.i18n.yaml
+++ b/packages/llm/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/README.md
 README.md: 077ae600c89cff80cd71830e37bda00707c1d837
-README.zh.md: e2bdad7fd0b33116498b50bfa6527974fa140fc9
+README.zh.md: 95355d34c014a1b442da1028251301d6d4202c6b
diff --git a/packages/llm/README.zh.md b/packages/llm/README.zh.md
index e2bdad7fd0..95355d34c0 100644
--- a/packages/llm/README.zh.md
+++ b/packages/llm/README.zh.md
@@ -1,8 +1,8 @@
-# llm/ — LLM 能力家族
+# llm/ — LLM（大语言模型）能力家族
 
 [English](README.md) | 中文
 
-LLM（大语言模型）seam 及其提供方适配器。接口包（`llm`）负责抽象服务、内容块词汇和流式分片组装器；适配器是注册到 `ctx.llm` 的具体实现。这些全是**产品**包。
+LLM seam 及其提供方适配器。接口包（`llm`）负责抽象服务、内容块词汇和流式分片组装器；适配器是注册到 `ctx.llm` 的具体实现。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
@@ -14,4 +14,4 @@ LLM（大语言模型）seam 及其提供方适配器。接口包（`llm`）负
 
 适配器在 seam 上注册提供方路由；重试与 token 测量仍是独立消费方。子 README 负责路由、元数据、回放和提供方协议细节；[LLM 架构决策](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)负责设计原理。
 
-子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器契约——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
+子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器约定——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index be1dc838ff..abe4d95c7e 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/lsp/README.md
 README.md: 01c464c9993571990e0542df9fadb2848a6c9a79
-README.zh.md: fa7dddeb011bd34c1f9cbe3a9dbf746d7f163897
+README.zh.md: 7a24bffa0e92f30c16a3307357ba7f1aa295ef52
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index fa7dddeb01..7a24bffa0e 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品** 包。
+语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
@@ -10,7 +10,7 @@
 | `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
 | `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
-接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
+接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型约定。提供方注册的是**能力**而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
 设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
 
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index 03487d5719..116b0ae54e 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/packages/lsp/lsp-local/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/lsp/lsp-local/README.md
 README.md: 661c27d3326adfc3408b33550a63fe3ebe183a39
-README.zh.md: 83f0eaa1fb4caccc381a1623b791355b2f5c5b65
+README.zh.md: 9bc66ee00ff2f21df66b88aa607a555fd56e974b
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index 83f0eaa1fb..9bc66ee00f 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -9,7 +9,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 ## 功能
 
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
-- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其 dispose（资源释放）完成，并在新进程上重试该查询一次。
+- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。服务器仍存活时返回的错误不会触发重试；如果选中的池化传输在只读查询之前或期间发生故障，提供方会等待其 dispose（资源释放）完成，并在新进程上重试该查询一次。
 - 每次查询都使用兼容性优先的**临时打开**序列：通过 `ctx.fs` 流式读取源文件，同时解析并限制其字节数；随后执行 `textDocument/didOpen`（版本 1、完整文本）、所请求操作，再执行位于 `finally` 中的 `textDocument/didClose`。写入 `didOpen` 失败或取消时，会在池复用该实例前将其终止。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
 - 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方 dispose 会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找完成，随后排空每条队列与每个服务器。
 - 协议 shutdown 失败后，经由子进程 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
diff --git a/packages/plan/README.i18n.yaml b/packages/plan/README.i18n.yaml
index 4e34bac80c..8291b525f1 100644
--- a/packages/plan/README.i18n.yaml
+++ b/packages/plan/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/plan/README.md
 README.md: 535a2b02e297d7c3bc68538fa1d03226089372e0
-README.zh.md: f068bf37b44daa0d724fbb85ad85a4d62883e847
+README.zh.md: 1b28af328f6da5cfabb09093c339f6504316f0e7
diff --git a/packages/plan/README.zh.md b/packages/plan/README.zh.md
index f068bf37b4..1b28af328f 100644
--- a/packages/plan/README.zh.md
+++ b/packages/plan/README.zh.md
@@ -10,4 +10,4 @@ Plan mode 是按 agent（智能体）记录的协作状态，而不是通用模
 
 [plan 专用协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)决策记录了该家族的设计。
 
-子系统参考——`plan/mode` 折叠、步边界冲刷、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
+子系统参考——`plan/mode` 折叠、步骤边界刷新、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
diff --git a/packages/plan/plan-mode/README.i18n.yaml b/packages/plan/plan-mode/README.i18n.yaml
index 86afdb6310..7d4217d3d4 100644
--- a/packages/plan/plan-mode/README.i18n.yaml
+++ b/packages/plan/plan-mode/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/plan/plan-mode/README.md
 README.md: 6c8ba23b76e83665d4f8dcb5ecb41689347f6423
-README.zh.md: b306d5562af21dd9a95bb68c9acfc3f40c52136f
+README.zh.md: 275a87669802f38cd98886236ca63a09ffb3e410
diff --git a/packages/plan/plan-mode/README.zh.md b/packages/plan/plan-mode/README.zh.md
index b306d5562a..275a876698 100644
--- a/packages/plan/plan-mode/README.zh.md
+++ b/packages/plan/plan-mode/README.zh.md
@@ -8,7 +8,7 @@
 
 `plan/mode`（`{ active: boolean }`）是一个仅存在于日志中、每次以完整值替换的 `SessionEventMap` 成员。`foldPlanMode(events)` 返回最后记录的值，如果没有则返回 `false`，因此恢复、fork 和压缩（compaction）都能直接从会话日志恢复 plan 状态。UI 通过 `session/event` 观察已提交的切换。
 
-`ctx.planMode.set(agent, active)` 在 agent 空闲时立即提交——下一个 prompt 之前不会有任何边界到来，因此独立的 `plan/mode` 事件当场落账——在 agent 运行中则持有待生效选择、等下一个被接受的轮内 pre-step；返回值说明发生了哪种（`committed`/`queued`）、一次 `cancelled` 反转或 `noop`。`get(agent)` 返回 `{ active, pending? }`，将塑造当前步骤的日志状态与用户的轮中选择分开。初始与续步 pre-step 边界都在覆盖范围内；同一步骤的请求恢复重试会复用已冻结的 assembly，并将该选择保留到下一个 pre-step。当最后记录的请求头描述了另一状态时，用户选择的变更会贡献一条插件来源的 `user/message` 通知（两条提交路径皆然）。
+`ctx.planMode.set(agent, active)` 在 agent 空闲时立即提交——下一个 prompt 之前不会有任何边界到来，因此独立的 `plan/mode` 事件当场落账——在 agent 运行中则持有待生效选择，并等待下一个被接受的轮内 pre-step；返回值区分 `committed`、`queued`、表示反转的 `cancelled` 和 `noop`。`get(agent)` 返回 `{ active, pending? }`，将塑造当前步骤的日志状态与用户的轮中选择分开。初始与续步 pre-step 边界都在覆盖范围内；同一步骤的请求恢复重试会复用已冻结的 assembly，并将该选择保留到下一个 pre-step。当最后记录的请求头描述了另一状态时，用户选择的变更会贡献一条插件来源的 `user/message` 通知（两条提交路径皆然）。
 
 ## 模型与人类交互
 
diff --git a/packages/pty/README.i18n.yaml b/packages/pty/README.i18n.yaml
index 7f4c7f1f21..a5d814f00d 100644
--- a/packages/pty/README.i18n.yaml
+++ b/packages/pty/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/pty/README.md
 README.md: 2afb3cd61ef4bfba460716549d41f799e419ff46
-README.zh.md: 57a5c93047ccb970f499f02c0168db7e9f71b622
+README.zh.md: e0871e23b954b5e611670d0519b938c9fcb28e43
diff --git a/packages/pty/README.zh.md b/packages/pty/README.zh.md
index 57a5c93047..e0871e23b9 100644
--- a/packages/pty/README.zh.md
+++ b/packages/pty/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`PTY` 的全称是 **Pseudo-Terminal（伪终端）**。这项能力提供持久且限定所有者范围的终端会话，适用于需要跨工具调用保留状态或使用交互式 stdin 的工作流。PTY 是单次 bash 与文件系统工具的补充，不会取代后两者更严格的逐操作契约。
+`PTY` 的全称是 **Pseudo-Terminal（伪终端）**。这项能力提供持久且限定所有者范围的终端会话，适用于需要跨工具调用保留状态或使用交互式 stdin 的工作流。PTY 是单次 bash 与文件系统工具的补充，不会取代后两者更严格的逐操作约定。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
@@ -12,4 +12,4 @@
 
 设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
 
-子系统参考——id、后端/会话契约、发送就绪、有界读取——见 [docs/subsystems/pty.md](../../docs/subsystems/pty.md)；设计与延后边界见[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)。
+子系统参考——id、后端/会话约定、发送就绪、有界读取——见 [docs/subsystems/pty.md](../../docs/subsystems/pty.md)；设计与暂缓边界见[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)。
diff --git a/packages/pty/pty-local/README.i18n.yaml b/packages/pty/pty-local/README.i18n.yaml
index bd835a091d..238e2aa749 100644
--- a/packages/pty/pty-local/README.i18n.yaml
+++ b/packages/pty/pty-local/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/pty/pty-local/README.md
 README.md: 5acc92853e6e8fcb8938c48e391559bf4a28fb75
-README.zh.md: 353c2a4bdac7e8402fc63071dfb6fb85dcff66d5
+README.zh.md: 7d070a9a4aceab921264f020716fbdf16fdd57ff
diff --git a/packages/pty/pty-local/README.zh.md b/packages/pty/pty-local/README.zh.md
index 353c2a4bda..7d070a9a4a 100644
--- a/packages/pty/pty-local/README.zh.md
+++ b/packages/pty/pty-local/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 插件（`pty-local`）
 
-该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。Spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
+该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
 就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
@@ -32,5 +32,5 @@
 
 - 输出按行规范化；不支持全屏备用缓冲区交互。
 - 精确 stdin 等待检测取决于已挂载的进程管理提供方；无法证明该状态的提供方使用提示符标记和静默／超时就绪机制。
-- 清理保证以 `SubprocessTerminalHandle` 的保证为准；提供方特定的缺口属于该实现的契约，而非这个 PTY 消费方。
+- 清理保证以 `SubprocessTerminalHandle` 的保证为准；提供方特定的缺口属于该实现的约定，而非这个 PTY 消费方。
 - harness 进程退出后，会话无法继续存在。
diff --git a/packages/sandbox/sandbox/README.i18n.yaml b/packages/sandbox/sandbox/README.i18n.yaml
index 99a5265418..72a03cbfdd 100644
--- a/packages/sandbox/sandbox/README.i18n.yaml
+++ b/packages/sandbox/sandbox/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox/README.md
 README.md: 8c1c747f6c7178f9c8c1a9827675ffa98f29aa6d
-README.zh.md: e43d1918a99fa96688632551a8f861c2c91f9c2a
+README.zh.md: 1e9ecee967bfc3621d6fb441f405e84896fa7863
diff --git a/packages/sandbox/sandbox/README.zh.md b/packages/sandbox/sandbox/README.zh.md
index e43d1918a9..1e9ecee967 100644
--- a/packages/sandbox/sandbox/README.zh.md
+++ b/packages/sandbox/sandbox/README.zh.md
@@ -4,7 +4,7 @@
 
 抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务契约（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。
 
-用一句话概括契约：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
+用一句话概括约定：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
 
 策略随调用传递，而不属于提供方：两个消费方可以同时按不同策略施加限制（bash 使用 `read-only`，而受限制的子 agent（智能体）保持其状态目录可写）；获批的升权重试只是使用更宽策略发起的新调用。
 
@@ -39,5 +39,5 @@ sandbox mode "<mode>" is requested but no sandbox backend is usable on this host
 - **文件操作是完整的策略词汇**：该 seam 不表达网络、进程、系统调用、设备或凭据限制。
 - **只支持与宿主共享文件系统和内核的限制**：容器、microVM 与远程执行需要替换能力实现，而不是在此处增加提供方。
 - **拒绝报告是一种 stderr 方言**：该 seam 返回后端签名，而非类型化运行时拒绝通道，因此需要分类的消费方必须从子进程输出推断。
-- **Runner 诊断使用带内通道**：退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此受限子进程若故意模仿 runner，就可能造成可用性或诊断误归因。这无法绕过约束；带外 runner 状态通道暂缓实现。
+- **Runner 诊断使用带内通道**：退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此受限子进程若故意模仿 runner，就可能造成可用性或诊断误归因。这无法绕过限制；带外 runner 状态通道暂缓实现。
 - **每个上下文只有一个提供方**：同时组合不同沙箱机制需要提供方级阶梯或独立 Cordis 上下文；调用方逐调用选择策略，而非后端标识。
diff --git a/packages/skill/README.i18n.yaml b/packages/skill/README.i18n.yaml
index 758d0552f9..f782f16c34 100644
--- a/packages/skill/README.i18n.yaml
+++ b/packages/skill/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/skill/README.md
 README.md: cd606e778335249bf8ecc876d3b1a4e5feb79448
-README.zh.md: 4db7e2524596f4c62144ec7eabe7c6af63e2e270
+README.zh.md: ec43a531033799e5e5e920c1b2212f39a5699e81
diff --git a/packages/skill/README.zh.md b/packages/skill/README.zh.md
index 4db7e25245..ec43a53103 100644
--- a/packages/skill/README.zh.md
+++ b/packages/skill/README.zh.md
@@ -11,6 +11,6 @@
 | [`skill-local/`](skill-local/README.md) | 从本地文件系统发现 skill | 注册到 `ctx.skills` |
 | [`tool-skill/`](tool-skill/README.md) | 发布 skill 目录和面向模型的 loader | 注册到 `ctx.tools` |
 
-该能力位于核心控制主干之外，可以使用本地、嵌入式或远程提供方，而无需更改面向模型的契约。
+该能力位于核心控制主干之外，可以使用本地、嵌入式或远程提供方，而无需更改面向模型的约定。
 
 子系统参考——发现优先级、目录快照、`skill` 加载器——见 [docs/subsystems/skills.md](../../docs/subsystems/skills.md)。
diff --git a/packages/spill/README.i18n.yaml b/packages/spill/README.i18n.yaml
index 62ed26a59b..1d1ace946c 100644
--- a/packages/spill/README.i18n.yaml
+++ b/packages/spill/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/spill/README.md
 README.md: 74fd4837cb23767754174df168f2f4ba71c2b938
-README.zh.md: 16d677719a9c3f4245a2f446017641ff6b50ffa8
+README.zh.md: 2417bb793dca1cb10ead6208cb6ad896c18cdf03
diff --git a/packages/spill/README.zh.md b/packages/spill/README.zh.md
index 16d677719a..2417bb793d 100644
--- a/packages/spill/README.zh.md
+++ b/packages/spill/README.zh.md
@@ -12,4 +12,4 @@
 
 参见[工具输出 spill 决策](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中记录了存储、保留和工具自有输出处理之间的边界。
 
-子系统参考——`SaveTextSpill`、owner/来源、品牌化定位符——见 [docs/subsystems/spill.md](../../docs/subsystems/spill.md)；依据见[工具输出 spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
+子系统参考——`SaveTextSpill`、所有者/来源、品牌化定位符——见 [docs/subsystems/spill.md](../../docs/subsystems/spill.md)；依据见[工具输出 spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
diff --git a/packages/subagent/README.i18n.yaml b/packages/subagent/README.i18n.yaml
index fe76e74a77..c7d3ce46ee 100644
--- a/packages/subagent/README.i18n.yaml
+++ b/packages/subagent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/README.md
 README.md: c8969ad313fc673456d2740b40d90c6d8db794ac
-README.zh.md: fb18afba5d8680408f0f37ab75056a3fb0ef660a
+README.zh.md: 04351f26721849de730db6083f55abc8e8571ce4
diff --git a/packages/subagent/README.zh.md b/packages/subagent/README.zh.md
index fb18afba5d..04351f2672 100644
--- a/packages/subagent/README.zh.md
+++ b/packages/subagent/README.zh.md
@@ -18,6 +18,6 @@
 | [`tool-subagent-control/`](tool-subagent-control/README.md) | 向模型公开子级消息发送和列举操作 | 注册到 `ctx.tools` |
 | [`tool-subagent-report/`](tool-subagent-report/README.md) | 提供从子级到父级的报告通道 | 注册到子级作用域 |
 
-参见[能力家族](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续执行的子级](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)和[控制工具](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)决策。
+参见有关[能力家族](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续执行的子级](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)和[控制工具](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)的决策。
 
 子系统参考——启动请求、结果、实时运行、提供方 seam、可续跑后台子 agent——见 [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md)；设计依据见 [subagent 能力 seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可续跑后台 subagent](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md) 与[合并 subagent 控制服务](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Note。
diff --git a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
index 246d702892..3973b5dd92 100644
--- a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
+++ b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-dsh-sdk/README.md
 README.md: 0bbcfa105ecf024a2492d39d3bf8d28956110050
-README.zh.md: ffb1b8f4cddca4566a20593bdac54801ad8db38f
+README.zh.md: 5b196da8f11d71b065ee8111cec010b62edd896c
diff --git a/packages/subagent/subagent-dsh-sdk/README.zh.md b/packages/subagent/subagent-dsh-sdk/README.zh.md
index ffb1b8f4cd..5b196da8f1 100644
--- a/packages/subagent/subagent-dsh-sdk/README.zh.md
+++ b/packages/subagent/subagent-dsh-sdk/README.zh.md
@@ -16,7 +16,7 @@ SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepS
 
 ## 停止原因映射
 
-SDK 客户端返回自有子活动，而不是提示词结果。提供方读取该活动内最后一个持久 `turn/end`，并将其映射为 seam 词汇：`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余情况，包括 `error`、`interrupted`、`disposed`、未来变体或不含轮次的活动，均映射为 `error`，因此非正常停止绝不会报告为成功。发布后的传输层失败会通过 `onError` 诊断接收器（连接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；seam 契约禁止 `result` 被拒绝。
+SDK 客户端返回自有子活动，而不是提示词结果。提供方读取该活动内最后一个已持久化的 `turn/end`，并将其映射为 seam 词汇：`completed` → `completed`，`max-tokens` → `max-tokens`，`aborted` → `aborted`；其余情况，包括 `error`、`interrupted`、`disposed`、未来变体或不含轮次的活动，均映射为 `error`，因此非正常停止绝不会报告为成功。发布后的传输层失败会通过 `onError` 诊断接收器（连接到 `ctx.logger.warn`）压平为 `stopReason: 'error'`；seam 约定禁止 `result` 被拒绝。
 
 ## 能力与上下文
 
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 1025b0e342..23ed818ebb 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
 README.md: cd25bace16c91e8b44331dc8e5eab0987607e83a
-README.zh.md: 05b1e4dd4c74b6d62df8b0a310534fc9476f3ade
+README.zh.md: b385182f032da17e7326ac265f47a2a5046f918a
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 05b1e4dd4c..b385182f03 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -4,7 +4,7 @@
 
 subagent seam 允许一个 agent（智能体）通过具名提供方把工作委派给子 agent。调用方使用统一的服务 API（`ctx.subagents`）；提供方决定子 agent 在当前进程、另一进程还是未来的传输之上运行。
 
-[subagent 家族概述](../README.md)列出了实现和面向模型的消费方。本包负责提供方注册表、共享请求和结果契约、持久描述符以及可继续子级编排。多个具名提供方可以在该契约背后共存。
+[subagent 家族概述](../README.md)列出了实现和面向模型的消费方。本包负责提供方注册表、共享的请求与结果约定、持久描述符以及可继续子级编排。多个具名提供方可以在该约定背后共存。
 
 ## 服务 API
 
@@ -23,7 +23,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
 | `listChildren(parentSessionId, signal?)` | 按 `createdAt` 再按 id 的顺序列出由会话支撑的直接 subagent，包括其 `one-shot`／`continuable` 模式、`running`／`inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic，且不会加载或恢复它们。直接读取在线会话存储与可选的会话持久化（持久化缺席时仅枚举在线 child），并要求已挂载 `sessionProjections` 注册表；不要求 `ctx.agents`、继续执行管理器或任何查询服务。 |
-| `listDescendants(rootSessionId, signal?)` | 从同一份实时优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth`。普通会话与一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现。身份、diagnostic、依赖与取消契约均沿用 `listChildren()`。 |
+| `listDescendants(rootSessionId, signal?)` | 从同一份在线优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth`。普通会话与一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现。身份、diagnostic、依赖与取消约定均沿用 `listChildren()`。 |
 
 `SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。
 
@@ -80,13 +80,13 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代，因为停止一个轮次是幂等的，且不投递任何内容。
 
-当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置纪律从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，让消费方以之替换掉手中过时的身份而非永久滞留——绝不抛错。
+当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置规则从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，使消费方替换陈旧身份而不是将其保留——绝不抛错。
 
 `registerContinuableSetup()` 允许可选包添加子级作用域能力，而无需让继续执行管理器知道这些能力的名称。贡献会在 Activation 发布前同步安装，在设置失败时一并回滚，并随子级作用域释放。新授权须等到下一个 Activation，移除贡献则会立即撤销每个驻留安装项。
 
 ## 收集模型
 
-面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`），并在 `descendants` scope 下遍历 `listDescendants()`。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
+面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`），并在 `descendants` scope 下遍历 `listDescendants()`。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 明确报错，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 明确报错。完整约定见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
 
 可继续 Activation 会等待 best-effort 的最终会话 flush，但不会把 listener 参与视为持久性确认。一次性运行保留尽力执行的会话检查点，因此已完成的一次性 child 只有在其会话确实进入持久化存储时，才可在 dispose 后继续被发现；如果该检查点缺失，服务不会根据 Task 历史虚构目录条目。
 
diff --git a/packages/subagent/tool-subagent-control/README.i18n.yaml b/packages/subagent/tool-subagent-control/README.i18n.yaml
index 367a73fd1f..d25adaad9d 100644
--- a/packages/subagent/tool-subagent-control/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-control/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/tool-subagent-control/README.md
 README.md: 4d9991b720bbbff8862e693b6aaed332f414af0e
-README.zh.md: dc1c81fc3313a8dfa277f33ae745702ed5b9d34b
+README.zh.md: 6f7138571fa7f8cb500df1a513f92d1f7f2b82e6
diff --git a/packages/subagent/tool-subagent-control/README.zh.md b/packages/subagent/tool-subagent-control/README.zh.md
index dc1c81fc33..6f7138571f 100644
--- a/packages/subagent/tool-subagent-control/README.zh.md
+++ b/packages/subagent/tool-subagent-control/README.zh.md
@@ -6,7 +6,7 @@
 
 本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源标记为持久化来源 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
 
-`interrupt_agent(agent_id)` 将 `exec.agent` 作为 `ctx.subagents.interrupt()` 的确切在线 ancestor 授权传入：目标可以是直接 child 或更深的后代，由服务——而不是本工具——依据目标 Activation 记录的 lineage 校验调用方。只有目标的当前轮次会停止（`keepInbox`）：已排队的消息保持暂停直到之后的 `send_message`，已发布的后代继续运行，child 也仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标静止；目标不存在或已结算是被接受的 no-op，而 self、sibling、过期与非 ancestor 调用方会成为出错结果。
+`interrupt_agent(agent_id)` 将 `exec.agent` 作为 `ctx.subagents.interrupt()` 的确切在线 ancestor 授权传入：目标可以是直接 child 或更深的后代，由服务——而不是本工具——依据目标 Activation 记录的 lineage 校验调用方。只有目标的当前轮次会停止（`keepInbox`）：已排队的消息保持暂停直到之后的 `send_message`，已发布的后代继续运行，child 也仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标完全停稳；目标不存在或已结算是被接受的 no-op，而 self、sibling、过期与非 ancestor 调用方会成为出错结果。
 
 `list_agents` 接受一个可选的 `scope` 参数，会从调用它的 agent 推导根 id，并且不使用 cursor，将服务目录投影为可继续 child。默认的 `children` scope 读取 `ctx.subagents.listChildren()`；`descendants` 读取 `ctx.subagents.listDescendants()`，其单份语料的遍历会穿过普通会话与一次性 child，并按稳定 pre-order 以 `parent=<id> depth=<n>` 渲染保留下来的条目。`parent` 注释是持久化直接 parent 会话 id，可能指向输出中省略的普通会话。对于调用本工具的 agent，只有 depth-1 child 条目可作为 `send_message` 候选；更深的 child 条目只能作为 `interrupt_agent` 候选。状态来自在线 Agent 注册表：`running`（driver 活跃）、`idle`（驻留但处于轮次之间，可能在等待它启动的 agent）、`complete`（仅存于存储）。服务结果还包含由会话支撑的一次性 subagent，以供 UI 等消费方使用；但这些条目无法接受 `send_message`，因此会从这个模型工具中排除。diagnostic 仍然可见，并在 descendants scope 中带有位置。持久化身份和模式来自每个子 agent 的描述符，消息送达时的鉴权和 Activation 所有权检查仍归服务负责。
 
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 2088cbdb6b..c90e0949bd 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subprocess/README.md
 README.md: 9a8628e2b6d16852895be33ae516c8b33b078502
-README.zh.md: d2c539fb1c66a914aa5f758d928fba01b5600d15
+README.zh.md: 734a2a5a27f0337a3015989556e571f4d18228e0
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index d2c539fb1c..734a2a5a27 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这里集中提供一个执行世界的共享进程基底：可执行文件查找、具有原始或收集式 stdio 的完整指定受管子进程树，以及一项深层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+这里集中提供一个执行世界的共享进程基底：可执行文件查找、具有原始或收集式 stdio 的完全明确指定的受管子进程树，以及一项底层终端进程原语，负责 PTY 分配、前台进程组和提供方仍可观察到的会话成员清理。命令默认值补全、shell 语义、时限、协议分帧、就绪状态与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)、[PTY shell 后端](../pty/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[subprocess seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 7a33a31d0c..e81656d84a 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subprocess/subprocess/README.md
 README.md: c28361f5e767f81fe8d1ca4757aece83dccfea5c
-README.zh.md: 3ad73bdea3b137f1c9139fdb1b52c49eb10b5500
+README.zh.md: 828e8818ce3366bd955d83f7ccb5dab0f0379c46
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 3ad73bdea3..828e8818ce 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -11,7 +11,7 @@
 - spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，并结算在途句柄调用；提供方会记录执行基底特有的可观察性限制。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出时，输出流在已排队输出之后结束；存活传输失败会拒绝 `done`。这些操作保留为一项执行基底原语，因为普通管道无法分配控制终端或清理终端会话成员；就绪状态、scrollback 和所有者策略仍归 PTY 消费方所有。
+- `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，并结算在途句柄调用；提供方会记录执行基底特有的可观察性限制。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出时，输出流在已排队输出之后结束；仍处于活动状态的传输若发生故障，会使 `done` 拒绝。这些操作保留为一项执行基底原语，因为普通管道无法分配控制终端或清理终端会话成员；就绪状态、scrollback 和所有者策略仍归 PTY 消费方所有。
 - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地的普通 spawn 与终端 spawn 都应用该定义；拥有自身 spawn 的 SDK 管理传输可直接导入它。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
diff --git a/packages/tasks/README.i18n.yaml b/packages/tasks/README.i18n.yaml
index d5df91be62..bf9be6a596 100644
--- a/packages/tasks/README.i18n.yaml
+++ b/packages/tasks/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/README.md
 README.md: e0b6769cd1d28cc7159310a6ec6f5c8d94a81a24
-README.zh.md: d030081470a503fb52fd72dcc6f89f4c535dc38c
+README.zh.md: 97d258ffdc88b728ecabd9d20afaf228d620d8a4
diff --git a/packages/tasks/README.zh.md b/packages/tasks/README.zh.md
index d030081470..97d258ffdc 100644
--- a/packages/tasks/README.zh.md
+++ b/packages/tasks/README.zh.md
@@ -6,10 +6,10 @@
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
-| [`tasks/`](tasks/README.md) | 定义任务注册表和生命周期契约 | `ctx.tasks` |
+| [`tasks/`](tasks/README.md) | 定义任务注册表和生命周期约定 | `ctx.tasks` |
 | [`tasks-local/`](tasks-local/README.md) | 实现进程本地任务注册表 | 注册到 `ctx.tasks` |
 | [`tool-tasks/`](tool-tasks/README.md) | 向模型公开任务控制和完成通知 | 注册到 `ctx.tools` |
 
 参见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和[任务注册表](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)决策。
 
-子系统参考——id 方案、拥有者围栏契约、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表 seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。
+子系统参考——id 方案、拥有者围栏约定、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表 seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。
diff --git a/packages/todo/README.i18n.yaml b/packages/todo/README.i18n.yaml
index 57a1538b78..b9f4c9fef1 100644
--- a/packages/todo/README.i18n.yaml
+++ b/packages/todo/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/todo/README.md
 README.md: 6c7dccbbfb007737593550cea91444f8f735cf81
-README.zh.md: 3c1c35187b5111f1fdb607d70b980be57e3e79c1
+README.zh.md: 9c5d6a9cc3f6078d5609aea668684ea0e4275835
diff --git a/packages/todo/README.zh.md b/packages/todo/README.zh.md
index 3c1c35187b..9c5d6a9cc3 100644
--- a/packages/todo/README.zh.md
+++ b/packages/todo/README.zh.md
@@ -8,6 +8,6 @@
 |---|---|---|
 | [`tool-todo/`](tool-todo/README.md) | 存储并公开会话的 todo 列表。 | （注册到 `ctx.tools`） |
 
-子级 README 负责工具、持久化和渲染契约。
+子级 README 负责工具、持久化和渲染约定。
 
 事件载荷记录在 [docs/subsystems/session.md](../../docs/subsystems/session.md)。
diff --git a/packages/web/README.i18n.yaml b/packages/web/README.i18n.yaml
index 87177273da..0eaedfb018 100644
--- a/packages/web/README.i18n.yaml
+++ b/packages/web/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/README.md
 README.md: 811c8b3439a8962116df0e8b3ab4f6e282ecb3d2
-README.zh.md: e328447d5d026c0abc815b269179ba6c4cd9acfc
+README.zh.md: c7c0546c6a2527ba04bd802945c0dd4ee4353a37
diff --git a/packages/web/README.zh.md b/packages/web/README.zh.md
index e328447d5d..c7c0546c6a 100644
--- a/packages/web/README.zh.md
+++ b/packages/web/README.zh.md
@@ -13,6 +13,6 @@
 | [`web-fetch-local/`](web-fetch-local/README.md) | 抓取公共 HTTP 和 HTTPS 资源 | 注册到 `ctx.web` |
 | [`tool-web/`](tool-web/README.md) | 向模型公开 web 搜索和抓取 | 注册到 `ctx.tools` |
 
-[web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)记录了搜索和抓取共用一项提供方选择服务的原因。
+[web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) 记录了搜索和抓取共用一项提供方选择服务的原因。
 
 子系统参考——搜索/抓取请求与结果、可用性、`WebError`——见 [docs/subsystems/web.md](../../docs/subsystems/web.md)；依据（含延后的 SSRF 防护）见 [web 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)。
diff --git a/packages/workflow/README.i18n.yaml b/packages/workflow/README.i18n.yaml
index 05ad673c61..1d87cec1bf 100644
--- a/packages/workflow/README.i18n.yaml
+++ b/packages/workflow/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/README.md
 README.md: 7b19cfd37f9b6870825d5e0761aed92908206b3a
-README.zh.md: 33b3f26780da1bf4efcd78242b2cfb212cef4c22
+README.zh.md: 8460e22347a6c24b84f12f641479edb78bf1ed1e
diff --git a/packages/workflow/README.zh.md b/packages/workflow/README.zh.md
index 33b3f26780..8460e22347 100644
--- a/packages/workflow/README.zh.md
+++ b/packages/workflow/README.zh.md
@@ -1,4 +1,4 @@
-# workflow/：动态工作流能力家族
+# workflow/：动态工作流能力族
 
 [English](README.md) | 中文
 
@@ -11,6 +11,6 @@
 | [`tool-workflow/`](tool-workflow/README.md) | 向模型公开通用工作流执行 | 注册到 `ctx.tools` |
 | [`tool-ralph/`](tool-ralph/README.md) | 公开使用全新 agent（智能体）的固定 Ralph 工作流 | 注册到 `ctx.tools` |
 
-worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)决策。
+worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见 [动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) 和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) 决策。
 
-子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
+子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见 [动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
diff --git a/packages/workspace/README.i18n.yaml b/packages/workspace/README.i18n.yaml
index c7723f6c56..427a7aac69 100644
--- a/packages/workspace/README.i18n.yaml
+++ b/packages/workspace/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workspace/README.md
 README.md: 7e30f26a9854031b4907ad3e7edb35da5986d5d9
-README.zh.md: 6315ccb6b3a8b86161728e8296746efd0c334a29
+README.zh.md: e59f54ad3d22201304a8126e0b0fbcab79fd17a7
diff --git a/packages/workspace/README.zh.md b/packages/workspace/README.zh.md
index 6315ccb6b3..e59f54ad3d 100644
--- a/packages/workspace/README.zh.md
+++ b/packages/workspace/README.zh.md
@@ -8,6 +8,6 @@
 |---|---|---|
 | [`workspace/`](workspace/README.md) | 注册 workspace 并记录其会话归属 | `ctx.workspace` |
 
-[workspace 包参考](workspace/README.md)负责生命周期、持久化和删除语义。
+[workspace 包参考](workspace/README.md) 负责生命周期、持久化和删除语义。
 
 子系统参考——实体、realpath 规范、注册/解析——见 [docs/subsystems/workspace.md](../../docs/subsystems/workspace.md)；存储设计见 [domain KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。

From c9205901ecd6ef51ca06ecba0d5c49b124ebcc08 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 10:29:13 +0800
Subject: [PATCH 425/516] =?UTF-8?q?fix(doc-gates):=20review=20findings=20?=
 =?UTF-8?q?=E2=80=94=20scan=20every=20merge=20block,=20any=20quote=20style?=
 =?UTF-8?q?,=20.tsx=20too;=20self-check=20the=20scan?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ds-review-bot round: the backstop stopped at a file's first declare-module
block while the projection it guards reads them all; the textual prefilter
matched only single quotes; .tsx sources escaped the glob. All three are the
silent-vanish class the scan exists to prevent. contextMergeFiles now yields
one entry per block (quote-agnostic prefilter, ts+tsx patterns), and a third
partition direction requires everything rendered to be scan-visible, so a
future scan regression is a hard error. Spec fixture made projection-
consistent; the partially superseded 2026-07-28 regions note is rewritten to
the current mechanism and cross-linked both ways.
---
 ...08-09-cordis-event-walk-backstop.i18n.yaml |  4 +-
 .../2026-08-09-cordis-event-walk-backstop.md  |  6 +-
 ...026-08-09-cordis-event-walk-backstop.zh.md |  6 +-
 ...subsystem-cordis-surface-regions.i18n.yaml |  4 +-
 ...28-per-subsystem-cordis-surface-regions.md |  2 +-
 ...per-subsystem-cordis-surface-regions.zh.md |  2 +-
 scripts/cordis-walk.ts                        | 48 ++++++++-----
 scripts/gen-cordis-catalog-partition.spec.ts  | 68 ++++++++++++++++++-
 scripts/gen-cordis-catalog.ts                 | 17 ++++-
 9 files changed, 123 insertions(+), 34 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml
index e968e7b54e..5747d0da3f 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.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 .agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
-2026-08-09-cordis-event-walk-backstop.md: 59aeb06149925dc93839df64145555f27257d7be
-2026-08-09-cordis-event-walk-backstop.zh.md: 4549e9d382e5ff17ddff30eafad8d6c7e66d61ed
+2026-08-09-cordis-event-walk-backstop.md: 1d833858f9471c98f54b3793edd12e4710b8c0fc
+2026-08-09-cordis-event-walk-backstop.zh.md: 0cb0f3bd738b6cee703cee71f1c24741554df87a
diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
index 59aeb06149..1d833858f9 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-09-cordis-event-walk-backstop.zh.md)
 
 ## Problem
 
-`gen-cordis-catalog` renders every service and event the Typert host-face projection discovers, and fail-closed page maps (`SERVICE_PAGE`, `EVENT_SCOPE_PAGE`) guarantee each discovered key or scope lands on exactly one `docs/subsystems/` page. Discovery itself was only backstopped for services: an independent AST scan read every `declare module 'cordis'` Context merge and demanded each declared key be rendered or carry a named `SERVICE_WALK_EXEMPTIONS` reason.
+`gen-cordis-catalog` renders every service and event the Typert host-face projection discovers, and fail-closed page maps (`SERVICE_PAGE`, `EVENT_SCOPE_PAGE`) guarantee each discovered key or scope lands on exactly one `docs/subsystems/` page ([per-subsystem regions decision](../process/2026-07-28-per-subsystem-cordis-surface-regions.md) owns the page-region mechanism). Discovery itself was only backstopped for services: an independent AST scan read every `declare module 'cordis'` Context merge and demanded each declared key be rendered or carry a named `SERVICE_WALK_EXEMPTIONS` reason.
 
 Events had no such backstop. The projection walks only files reachable from host-face package exports, so an `interface Events` merge in client-face code — or in any file the host analyzer cannot reach — vanished with no trace: 12 declared events (`slash/input-*`, `theme/change`, `locale/change`, and the client runtime's `*/changed` invalidation signals) were documented nowhere generated and nothing would ever notice a thirteenth. The services scan also globbed only `packages/*/*/src/*.ts`, so 13 client-face Context keys declared in nested files (`src/client/**`) were invisible to the very scan meant to prevent silent vanishing.
 
@@ -14,7 +14,7 @@ Events had no such backstop. The projection walks only files reachable from host
 
 Events get the exact mirror of the services backstop, and both scans read the full package source tree.
 
-`scripts/cordis-walk.ts` gains `eventNameList` (every member name of an `interface Events` merge, read from method and property members alike so a shape the projector would reject still enters the scan) and its merge-file prefilter matches the `declare module` heads instead of the literal text `interface Context`, so an Events-only merge file is not skipped. The scan glob in `gen-cordis-catalog` deepens from `packages/*/*/src/*.ts` to `packages/*/*/src/**/*.ts`.
+`scripts/cordis-walk.ts` gains `eventNameList` (every member name of an `interface Events` merge, read from method and property members alike so a shape the projector would reject still enters the scan); the scan yields every `declare module 'cordis'` block in a file (the Typert analyzer reads them all, so stopping at the first would hide a second block's face), and its quote-agnostic prefilter matches the `declare module` heads instead of the literal text `interface Context`, so an Events-only or double-quoted merge file is not skipped. The scan glob in `gen-cordis-catalog` deepens from `packages/*/*/src/*.ts` to `packages/*/*/src/**/*.{ts,tsx}` (two patterns). A third partition direction guards the scan itself: every rendered service key and event name must also be visible to the scan, so a scan regression (glob, prefilter, block walk) is a hard error rather than a silent backstop decay.
 
 A new curated `EVENT_WALK_EXEMPTIONS` map names every declared event the projection cannot see, with the reason and the package README that owns its surface. Keys are full event names, not scopes: client-face events share scopes with rendered host events (`commands/changed` beside the host `commands/*` family), so a scope-level exemption would mask a host-face regression. The partition check is fail-closed in both directions, exactly like the service maps: an unexempted invisible event, an exemption for an event that renders, and an exemption no merge declares are all hard errors.
 
@@ -24,7 +24,7 @@ The audit that motivated this found the host face already complete: 48 rendered
 
 ## Verification
 
-`scripts/gen-cordis-catalog-partition.spec.ts` proves each acceptance path: the green partition, an invisible unexempted event (named with its declaring file), a stale rendered-event exemption, a stale never-declared exemption, the service mirror of each, unmapped rendered surface in both page maps, and the scan reaching a nested Events-only merge file. Deleting one live exemption from the real tree makes `gen-cordis-catalog` fail loud with the event's name and declaring file; restoring it returns the generator to a byte-identical no-op regeneration (85 artifacts, 0 written), which also proves the new exemptions exactly cover today's surface. `verify-cordis-catalog` in doc-sync executes the partition on every run.
+`scripts/gen-cordis-catalog-partition.spec.ts` proves each acceptance path: the green partition, an invisible unexempted event (named with its declaring file), a stale rendered-event exemption, a stale never-declared exemption, the service mirror of each, unmapped rendered surface in both page maps, rendered surface the scan cannot see (the third direction), and the scan reaching nested Events-only merges, every block of a multi-block file, double-quoted heads, and `.tsx` sources. Deleting one live exemption from the real tree makes `gen-cordis-catalog` fail loud with the event's name and declaring file; restoring it returns the generator to a byte-identical no-op regeneration (85 artifacts, 0 written), which also proves the new exemptions exactly cover today's surface. `verify-cordis-catalog` in doc-sync executes the partition on every run.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
index 4549e9d382..0cb0f3bd73 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-cordis-event-walk-backstop.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-`gen-cordis-catalog` 渲染 Typert host face 投影发现的每个服务与事件，fail-closed 的页面映射（`SERVICE_PAGE`、`EVENT_SCOPE_PAGE`）保证每个被发现的 key 或 scope 恰好落在一个 `docs/subsystems/` 页面上。但"发现"本身此前只对服务有兜底：一条独立的 AST 扫描读取每个 `declare module 'cordis'` Context merge，要求每个声明的 key 要么被渲染、要么在 `SERVICE_WALK_EXEMPTIONS` 中给出具名理由。
+`gen-cordis-catalog` 渲染 Typert host face 投影发现的每个服务与事件，fail-closed 的页面映射（`SERVICE_PAGE`、`EVENT_SCOPE_PAGE`）保证每个被发现的 key 或 scope 恰好落在一个 `docs/subsystems/` 页面上（页面区块机制归[按子系统区块决定](../process/2026-07-28-per-subsystem-cordis-surface-regions.md)所有）。但"发现"本身此前只对服务有兜底：一条独立的 AST 扫描读取每个 `declare module 'cordis'` Context merge，要求每个声明的 key 要么被渲染、要么在 `SERVICE_WALK_EXEMPTIONS` 中给出具名理由。
 
 事件没有这样的兜底。投影只遍历从 host face 包导出可达的文件，因此 client face 代码——或 host 分析器无法触及的任何文件——里的 `interface Events` merge 会无声消失：12 个已声明事件（`slash/input-*`、`theme/change`、`locale/change`，以及 client runtime 的 `*/changed` 失效信号）不出现在任何生成文档中，而且再多一个也不会有任何机制察觉。服务扫描的 glob 也只有 `packages/*/*/src/*.ts`，于是声明在嵌套文件（`src/client/**`）中的 13 个 client face Context key 恰恰对这条为防止无声消失而存在的扫描不可见。
 
@@ -14,7 +14,7 @@ Status: implemented
 
 事件获得与服务兜底完全对称的机制，且两条扫描都读取完整的包源码树。
 
-`scripts/cordis-walk.ts` 新增 `eventNameList`（`interface Events` merge 的每个成员名，方法与属性成员一并读取，使投影器会拒绝的形状也进入扫描），其 merge 文件预过滤改为匹配 `declare module` 头部而非字面文本 `interface Context`，从而不再跳过只含 Events 的 merge 文件。`gen-cordis-catalog` 的扫描 glob 从 `packages/*/*/src/*.ts` 加深为 `packages/*/*/src/**/*.ts`。
+`scripts/cordis-walk.ts` 新增 `eventNameList`（`interface Events` merge 的每个成员名，方法与属性成员一并读取，使投影器会拒绝的形状也进入扫描）；扫描产出文件中每一个 `declare module 'cordis'` 块（Typert 分析器读取全部块，止步于第一个会藏起第二个块的表面），其对引号风格不敏感的预过滤匹配 `declare module` 头部而非字面文本 `interface Context`，从而不再跳过只含 Events 或使用双引号的 merge 文件。`gen-cordis-catalog` 的扫描 glob 从 `packages/*/*/src/*.ts` 加深为 `packages/*/*/src/**/*.{ts,tsx}`（两个 pattern）。分区新增第三个方向守住扫描自身：投影渲染的每个服务 key 与事件名也必须对扫描可见，使扫描回归（glob、预过滤、块遍历）成为硬错误而非兜底的无声退化。
 
 新的人工维护映射 `EVENT_WALK_EXEMPTIONS` 为投影看不到的每个已声明事件命名，附理由与拥有其表面的包 README。键是完整事件名而非 scope：client face 事件与已渲染的 host 事件共享 scope（`commands/changed` 与 host 的 `commands/*` 家族并存），scope 级豁免会无声吞掉未来的 host face 回归。分区检查与服务映射一样双向 fail-closed：未豁免的不可见事件、已渲染事件的豁免、无任何 merge 声明的豁免，皆为硬错误。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 ## Verification
 
-`scripts/gen-cordis-catalog-partition.spec.ts` 证明每条验收路径：绿色分区、不可见且未豁免的事件（报出声明文件）、已渲染事件的陈旧豁免、从未声明的陈旧豁免、服务侧的对称路径、两个页面映射中未映射的已渲染表面，以及扫描触达嵌套的仅含 Events 的 merge 文件。在真实源码树上删除一条现役豁免会让 `gen-cordis-catalog` 以事件名与声明文件大声失败；恢复后生成器回到字节相同的 no-op 再生成（85 个 artifact，0 写入），这同时证明新豁免恰好覆盖当下表面。doc-sync 中的 `verify-cordis-catalog` 每次运行都会执行该分区检查。
+`scripts/gen-cordis-catalog-partition.spec.ts` 证明每条验收路径：绿色分区、不可见且未豁免的事件（报出声明文件）、已渲染事件的陈旧豁免、从未声明的陈旧豁免、服务侧的对称路径、两个页面映射中未映射的已渲染表面、扫描看不到的已渲染表面（第三方向），以及扫描触达嵌套的仅含 Events 的 merge、多块文件的每个块、双引号头部与 `.tsx` 源文件。在真实源码树上删除一条现役豁免会让 `gen-cordis-catalog` 以事件名与声明文件大声失败；恢复后生成器回到字节相同的 no-op 再生成（85 个 artifact，0 写入），这同时证明新豁免恰好覆盖当下表面。doc-sync 中的 `verify-cordis-catalog` 每次运行都会执行该分区检查。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml
index 102b0ce5fe..c343571dba 100644
--- a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.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 .agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
-2026-07-28-per-subsystem-cordis-surface-regions.md: ef65bfc4c7dadd7dafe1a38f41656e6ecc61ea50
-2026-07-28-per-subsystem-cordis-surface-regions.zh.md: 1df18d7260800b89c95a9d4aeb0301adb0ee56f6
+2026-07-28-per-subsystem-cordis-surface-regions.md: f6d4494d4195ba27f2898eecb27af32b433af88b
+2026-07-28-per-subsystem-cordis-surface-regions.zh.md: ee2a3c9730e6259e9f53d1b722b04b99819af65b
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
index ef65bfc4c7..f6d4494d41 100644
--- a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.md
@@ -14,7 +14,7 @@ The [generated-catalog decision](../../archived/process/2026-06-20-generated-cor
 
 `gen-cordis-catalog.ts` injects each subsystem's service and event reference INTO its own page, between `<!-- BEGIN GENERATED cordis-surface … -->` / `<!-- END GENERATED cordis-surface -->` markers, and the flat services/events catalogs are deleted. One page per subsystem now carries introduction, data structures, and the generated wiring surface.
 
-- **Curated fail-loud partition.** `SERVICE_PAGE` maps every discovered `ctx.<key>` to exactly one page; `EVENT_SCOPE_PAGE` maps every event scope. The generator hard-errors in both directions — an unmapped discovered service/scope, and a mapped key/scope the walk no longer discovers — so the partition cannot drift from the source surface. An independent scan of EVERY `declare module 'cordis'` Context merge backstops the rendering walk's blind spot (it only sees a root `index.ts` with a same-named service class): a declared key the walk cannot render must carry a named `SERVICE_WALK_EXEMPTIONS` reason (today: the `ctx.agent` DX accessor, plus the interface-typed or non-index-declared lsp/apiProxy/appShell/tuiPrompt/tuiResumeHost), and stale exemptions hard-error; a `TODO(cordis-catalog-interface-services)` marks teaching the walk to render them.
+- **Curated fail-loud partition.** `SERVICE_PAGE` maps every discovered `ctx.<key>` to exactly one page; `EVENT_SCOPE_PAGE` maps every event scope. The generator hard-errors in both directions — an unmapped discovered service/scope, and a mapped key/scope the walk no longer discovers — so the partition cannot drift from the source surface. Independent AST scans of every `declare module 'cordis'` merge block under `packages/*/*/src/**` backstop the projection's blind spots for services AND events: a declared Context key or Events member the projection cannot render must carry a named `SERVICE_WALK_EXEMPTIONS`/`EVENT_WALK_EXEMPTIONS` reason, stale exemptions hard-error, and everything rendered must also be visible to the scan ([events-backstop decision](../architecture/2026-08-09-cordis-event-walk-backstop.md) owns the scan contract); a `TODO(cordis-catalog-interface-services)` marks teaching the projection to render the interface-typed entries.
 - **Byte-identical regions across the pair.** The generator writes the SAME English region bytes into `foo.md` and `foo.zh.md`, extending the existing rule that verbatim code fences match across a pair. `verify-translation-pairing` gained a dedicated region-identity check (`partitionGeneratedRegions` in `translation-pairing.ts` owns the marker grammar) that names a divergent or malformed region precisely; the whole-document structural signature still covers the region content a second time.
 - **Guarded pair auto-record.** A regeneration that changes region bytes would leave every touched pair out-of-sync, so the generator re-records a pair's `.i18n.yaml` itself — but ONLY when the write is region-confined: both sides' recorded blob hashes must match the pre-write bytes, and the region-STRIPPED content must be unchanged on both sides. Human-prose drift leaves the record stale so the pairing gate still forces the normal translation flow; a brand-new pair is never auto-recorded (the author's reviewed `--write` owns that). This keeps `.i18n.yaml` as plain `git hash-object` values — no stripped-hash semantics change.
 - **The inherited tier moved, not died.** The vendor `ctx` members and `internal/*`/loader/hmr/timer events render to `docs/cordis-api/inherited.md`, next to the relocated Cordis core API pages (`docs/cordis-catalog/core/` → `docs/cordis-api/`). Framework surface lives under a framework home; the harness pages stay repository-owned vocabulary.
diff --git a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
index 1df18d7260..ee2a3c9730 100644
--- a/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
+++ b/.agents/notes/implemented/process/2026-07-28-per-subsystem-cordis-surface-regions.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 `gen-cordis-catalog.ts` 把每个子系统的服务与事件参考注入到该子系统自己的页面内部，置于 `<!-- BEGIN GENERATED cordis-surface … -->` / `<!-- END GENERATED cordis-surface -->` 标记之间；平铺的 services/events 目录随之删除。现在每个子系统由一个页面同时承载介绍、数据结构和生成的接线表面。
 
-- **人工维护、响亮失败的划分。** `SERVICE_PAGE` 把发现的每个 `ctx.<key>` 映射到恰好一个页面；`EVENT_SCOPE_PAGE` 映射每个事件作用域。生成器在两个方向上都会直接报错（既有被发现却未映射的服务或作用域，也有已映射但遍历不再发现的键或作用域），因此划分不可能相对源码表面发生漂移。一个独立扫描会读取每一处 `declare module 'cordis'` 的 Context 合并，为渲染遍历的盲区（它只看得到根 `index.ts` 中同名服务类）兜底：遍历渲染不了的已声明键必须在 `SERVICE_WALK_EXEMPTIONS` 中带着点名理由（目前是 `ctx.agent` 这一 DX 访问器字段，加上接口类型或不在 index 声明的 lsp/apiProxy/appShell/tuiPrompt/tuiResumeHost），陈旧豁免同样直接报错；教会遍历渲染它们的后续工作由 `TODO(cordis-catalog-interface-services)` 标记。
+- **人工维护、响亮失败的划分。** `SERVICE_PAGE` 把发现的每个 `ctx.<key>` 映射到恰好一个页面；`EVENT_SCOPE_PAGE` 映射每个事件作用域。生成器在两个方向上都会直接报错（既有被发现却未映射的服务或作用域，也有已映射但遍历不再发现的键或作用域），因此划分不可能相对源码表面发生漂移。独立的 AST 扫描读取 `packages/*/*/src/**` 下每一个 `declare module 'cordis'` merge 块，为投影在服务与事件两侧的盲区兜底：投影渲染不了的已声明 Context key 或 Events 成员必须在 `SERVICE_WALK_EXEMPTIONS`/`EVENT_WALK_EXEMPTIONS` 中带着点名理由，陈旧豁免直接报错，且投影渲染的一切也必须对扫描可见（扫描契约归[事件兜底决定](../architecture/2026-08-09-cordis-event-walk-backstop.md)所有）；教会投影渲染接口类型条目的后续工作由 `TODO(cordis-catalog-interface-services)` 标记。
 - **区块在配对两侧按字节一致。** 生成器把同一份英文区块字节写入 `foo.md` 和 `foo.zh.md`，是对「围栏代码块在配对两侧逐字节一致」这一既有规则的延伸。`verify-translation-pairing` 新增了专门的区块一致性检查（标记语法归 `translation-pairing.ts` 中的 `partitionGeneratedRegions` 所有），能精确点名出现分歧或格式错误的区块；整篇文档的结构签名仍会把区块内容再覆盖一遍。
 - **带防护的配对自动记录。** 一次改变区块字节的重新生成会让每个被触及的配对失去同步，因此生成器会自行重新记录配对的 `.i18n.yaml`，但仅限本次写入完全限定在区块内的情况：两侧记录的 blob hash 必须与写入前的字节相符，且两侧剥离区块后的内容必须没有变化。人工行文若有漂移，记录就保持陈旧，配对门禁因此仍会强制走正常翻译流程；全新的配对绝不自动记录（那归作者经评审的 `--write` 所有）。这样 `.i18n.yaml` 保持为纯粹的 `git hash-object` 值：不引入任何「剥离后 hash」的语义变化。
 - **继承层搬了家，而非消亡。** vendor 的 `ctx` 成员与 `internal/*`/loader/hmr/timer 事件渲染到 `docs/cordis-api/inherited.md`，紧邻迁移后的 Cordis 核心 API 页面（`docs/cordis-catalog/core/` → `docs/cordis-api/`）。框架表面落在框架自己的归属之下；harness 页面仍是仓库自有的词汇。
diff --git a/scripts/cordis-walk.ts b/scripts/cordis-walk.ts
index a7c22bea02..98763c0adf 100644
--- a/scripts/cordis-walk.ts
+++ b/scripts/cordis-walk.ts
@@ -9,41 +9,53 @@ import { globSync, readFileSync } from 'node:fs'
 import { resolve, sep } from 'node:path'
 import ts from 'typescript'
 
+/** Cheap textual prefilter for a cordis module merge, quote-style agnostic
+ * (the AST match below reads `stmt.name.text` and never sees the quotes). */
+const MERGE_HEAD = /declare module ['"](?:cordis|\.\/context\.ts)['"]/
+
 /**
- * Parse every file matching `pattern` (repo-relative, sorted, `/`-normalized)
- * that textually contains a cordis module merge, yielding each file's
- * module-merge body. Files without a merge are skipped.
- * @param scanRoot - Repository root the pattern is resolved against.
- * @param pattern - Glob selecting the TypeScript files to scan.
- * @returns One entry per file with a cordis module merge, in path order.
+ * Parse every file matching `patterns` (repo-relative, sorted, `/`-normalized)
+ * that textually contains a cordis module merge, yielding one entry per merge
+ * BLOCK — a file may legally hold several `declare module 'cordis'` blocks
+ * (the Typert analyzer reads them all), so the exhaustiveness scan must too.
+ * Files without a merge are skipped.
+ * @param scanRoot - Repository root the patterns are resolved against.
+ * @param patterns - Glob(s) selecting the TypeScript files to scan.
+ * @returns One entry per cordis module block, in path then source order.
  */
 export function contextMergeFiles(
   scanRoot: string,
-  pattern: string,
+  patterns: string | readonly string[],
 ): { rel: string; sf: ts.SourceFile; text: string; body: ts.ModuleBlock }[] {
   const out: { rel: string; sf: ts.SourceFile; text: string; body: ts.ModuleBlock }[] = []
-  for (const rel of globSync(pattern, { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
+  const rels = [...new Set(globSync(patterns as string | string[], { cwd: scanRoot }).map(s => s.split(sep).join('/')))].sort()
+  for (const rel of rels) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
-    if (!text.includes("declare module 'cordis'") && !text.includes("declare module './context.ts'")) continue
+    if (!MERGE_HEAD.test(text)) continue
     const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
-    const body = cordisModuleBody(sf)
-    if (!body) continue
-    out.push({ rel, sf, text, body })
+    for (const body of cordisModuleBodies(sf)) out.push({ rel, sf, text, body })
   }
   return out
 }
 
-/** The body of the cordis module merge in `sf`: `declare module 'cordis'`
- * (harness packages) or `declare module './context.ts'` (vendor core), or
- * null when the file has neither. */
-export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
+/** Every cordis module-merge body in `sf`: `declare module 'cordis'` (harness
+ * packages) or `declare module './context.ts'` (vendor core), in source order. */
+export function cordisModuleBodies(sf: ts.SourceFile): ts.ModuleBlock[] {
+  const bodies: ts.ModuleBlock[] = []
   for (const stmt of sf.statements) {
     if (!ts.isModuleDeclaration(stmt) || !ts.isStringLiteral(stmt.name)) continue
     if (stmt.name.text !== 'cordis' && stmt.name.text !== './context.ts') continue
-    if (stmt.body && ts.isModuleBlock(stmt.body)) return stmt.body
+    if (stmt.body && ts.isModuleBlock(stmt.body)) bodies.push(stmt.body)
   }
-  return null
+  return bodies
+}
+
+/** The FIRST cordis module-merge body in `sf`, or null without one — for the
+ * vendor core-API renderer whose input files carry exactly one merge; the
+ * exhaustiveness scan uses {@link cordisModuleBodies} to read them all. */
+export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
+  return cordisModuleBodies(sf)[0] ?? null
 }
 
 /**
diff --git a/scripts/gen-cordis-catalog-partition.spec.ts b/scripts/gen-cordis-catalog-partition.spec.ts
index 7de64fffde..2c6ef2584d 100644
--- a/scripts/gen-cordis-catalog-partition.spec.ts
+++ b/scripts/gen-cordis-catalog-partition.spec.ts
@@ -61,12 +61,33 @@ describe('walkPartitionProblems', () => {
 
   it('rejects an event exemption whose event the projection renders', () => {
     const { input, maps } = baseline()
-    const rendered = { ...input, renderedEventNames: new Set(['llm/request', 'theme/change']) }
-    expect(walkPartitionProblems(rendered, maps)).toEqual([
+    // A projection that renders theme/change necessarily renders the theme
+    // scope too; the fixture models that and maps the scope so the only
+    // violation is the stale exemption.
+    const rendered = {
+      ...input,
+      renderedScopes: new Set(['llm', 'theme']),
+      renderedEventNames: new Set(['llm/request', 'theme/change']),
+    }
+    const mapped = { ...maps, eventScopePage: { llm: 'llm-streaming.md', theme: 'client-modules.md' } }
+    expect(walkPartitionProblems(rendered, mapped)).toEqual([
       expect.stringContaining("event 'theme/change' is rendered by the projection but still listed in EVENT_WALK_EXEMPTIONS"),
     ])
   })
 
+  it('rejects rendered surface the independent scan cannot see, naming the scan as the defect', () => {
+    const { input, maps } = baseline()
+    const blind = {
+      ...input,
+      declaredKeys: new Map([['theme', 'packages/client/ui-theme/src/client/index.ts']]),
+      declaredEvents: new Map([['theme/change', 'packages/client/ui-theme/src/client/index.ts']]),
+    }
+    expect(walkPartitionProblems(blind, maps)).toEqual([
+      expect.stringContaining('ctx.llm is rendered by the projection but the independent scan finds no Context merge declaring it'),
+      expect.stringContaining("event 'llm/request' is rendered by the projection but the independent scan finds no Events merge declaring it"),
+    ])
+  })
+
   it('rejects an event exemption no Events merge declares', () => {
     const { input, maps } = baseline()
     const stale = { ...maps, eventWalkExemptions: { ...maps.eventWalkExemptions, 'gone/away': 'nothing owns this' } }
@@ -123,6 +144,49 @@ describe('cordis-walk scan reach', () => {
     expect([...contextKeyMap(only.body, only.sf).keys()]).toEqual([])
   })
 
+  it('yields every merge block of a multi-block file, double-quoted heads, and .tsx sources', () => {
+    const root = mkdtempSync(join(tmpdir(), 'cordis-walk-'))
+    roots.push(root)
+    const dir = join(root, 'packages/client/ui-x/src')
+    mkdirSync(dir, { recursive: true })
+    // The Typert analyzer reads every cordis module block in a file; the
+    // backstop must not stop at the first one, skip the double-quoted legal
+    // form, or ignore .tsx sources.
+    writeFileSync(join(dir, 'split.ts'), [
+      "declare module 'cordis' {",
+      '  interface Context {',
+      '    first: FirstService',
+      '  }',
+      '}',
+      'declare module "cordis" {',
+      '  interface Events {',
+      "    'second/changed'(): void",
+      '  }',
+      '}',
+      'export {}',
+      '',
+    ].join('\n'))
+    writeFileSync(join(dir, 'view.tsx'), [
+      "declare module 'cordis' {",
+      '  interface Context {',
+      '    fromTsx: TsxService',
+      '  }',
+      '}',
+      'export {}',
+      '',
+    ].join('\n'))
+    const merges = contextMergeFiles(root, ['packages/*/*/src/**/*.ts', 'packages/*/*/src/**/*.tsx'])
+    expect(merges.map(m => m.rel)).toEqual([
+      'packages/client/ui-x/src/split.ts',
+      'packages/client/ui-x/src/split.ts',
+      'packages/client/ui-x/src/view.tsx',
+    ])
+    const keys = merges.flatMap(m => [...contextKeyMap(m.body, m.sf).keys()])
+    const events = merges.flatMap(m => eventNameList(m.body, m.sf))
+    expect(keys).toEqual(['first', 'fromTsx'])
+    expect(events).toEqual(['second/changed'])
+  })
+
   it('reads string-literal and identifier member names from an Events merge', () => {
     const sf = ts.createSourceFile('x.ts', [
       "declare module 'cordis' {",
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index ef2b6c0ed5..aaae6f7649 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -573,7 +573,9 @@ export interface WalkPartitionMaps {
  * partition maps, fail-closed in both directions for services AND events: a
  * rendered key/scope must be mapped to a page, a mapped key/scope must still
  * render, and — the backstop — a DECLARED key/event the projection cannot see
- * must carry a named walk exemption (a rendered one must not). Pure so the
+ * must carry a named walk exemption (a rendered one must not). A third
+ * direction guards the scan itself: everything rendered must also be declared
+ * to the scan, so a scan blind spot cannot decay silently. Pure so the
  * acceptance paths are provable without running the projection.
  * @param input - rendered surface plus the declared-key/event scans.
  * @param maps - the curated page maps and walk exemptions.
@@ -622,6 +624,17 @@ export function walkPartitionProblems(input: WalkPartitionInput, maps: WalkParti
   for (const name of Object.keys(maps.eventWalkExemptions)) {
     if (!input.declaredEvents.has(name)) problems.push(`EVENT_WALK_EXEMPTIONS names '${name}' but no Events merge declares it; remove the stale exemption.`)
   }
+  // Self-check the scan itself: everything the projection renders is declared
+  // in a Context/Events merge the scan must also reach, so a rendered key or
+  // event the scan cannot see means the SCAN regressed (glob, prefilter, or
+  // block walk) — a partial blind spot that exemption staleness alone would
+  // never surface.
+  for (const key of input.renderedKeys.keys()) {
+    if (!input.declaredKeys.has(key)) problems.push(`ctx.${key} is rendered by the projection but the independent scan finds no Context merge declaring it; the scan has a blind spot (glob, prefilter, or module-block walk) — fix the scan, not the maps.`)
+  }
+  for (const name of input.renderedEventNames) {
+    if (!input.declaredEvents.has(name)) problems.push(`event '${name}' is rendered by the projection but the independent scan finds no Events merge declaring it; the scan has a blind spot (glob, prefilter, or module-block walk) — fix the scan, not the maps.`)
+  }
   return problems
 }
 
@@ -642,7 +655,7 @@ export function computeOutputs(): [string, string][] {
 
   const declaredKeys = new Map<string, string>()
   const declaredEvents = new Map<string, string>()
-  for (const { rel, sf, body } of contextMergeFiles(root, 'packages/*/*/src/**/*.ts')) {
+  for (const { rel, sf, body } of contextMergeFiles(root, ['packages/*/*/src/**/*.ts', 'packages/*/*/src/**/*.tsx'])) {
     for (const key of contextKeyMap(body, sf).keys()) {
       if (!declaredKeys.has(key)) declaredKeys.set(key, rel)
     }

From 80019566f217c0fed069d419d283d8059236a1a2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 10:56:05 +0800
Subject: [PATCH 426/516] =?UTF-8?q?chore(doc-gates):=20keep=20cordisModule?=
 =?UTF-8?q?Bodies=20module-local=20=E2=80=94=20knip=20flags=20the=20unused?=
 =?UTF-8?q?=20export?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 scripts/cordis-walk.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/scripts/cordis-walk.ts b/scripts/cordis-walk.ts
index 98763c0adf..3f878be13c 100644
--- a/scripts/cordis-walk.ts
+++ b/scripts/cordis-walk.ts
@@ -40,8 +40,9 @@ export function contextMergeFiles(
 }
 
 /** Every cordis module-merge body in `sf`: `declare module 'cordis'` (harness
- * packages) or `declare module './context.ts'` (vendor core), in source order. */
-export function cordisModuleBodies(sf: ts.SourceFile): ts.ModuleBlock[] {
+ * packages) or `declare module './context.ts'` (vendor core), in source order.
+ * Module-local: consumers walk blocks through {@link contextMergeFiles}. */
+function cordisModuleBodies(sf: ts.SourceFile): ts.ModuleBlock[] {
   const bodies: ts.ModuleBlock[] = []
   for (const stmt of sf.statements) {
     if (!ts.isModuleDeclaration(stmt) || !ts.isStringLiteral(stmt.name)) continue

From 10ef3d4924925a1c77372a6b8707c7c0b4b79f29 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 03:05:29 +0800
Subject: [PATCH 427/516] docs,feat(doc-gates): fix 15 dead anchor fragments;
 verify-md-links now validates fragments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A corpus sweep under the doc/prose standards found 15 links whose #fragment
named no anchor in its target — reworded headings, one relocated contract
(tool-fs → the group README's no-timeout rule), and zh sides citing English
slugs their Chinese headings never produce. Fixed all 15 (zh sides get the
conventional explicit <a id> + English fragment), fixed the one generator-owned
instance at its source (gen-doc-graphs), and extended verify-md-links to
resolve fragments onto Markdown targets — same-file anchors included — against
heading slugs and explicit <a id>, so the class is gated instead of manually
grepped. Remaining probes (narrated history, duplication shingles, comment
transcripts, budgets) came back clean; sibling-adapter README symmetry and
implemented-note contrasts are deliberate keeps.
---
 .../2026-06-24-web-capability-seam.i18n.yaml  |   2 +-
 .../2026-06-24-web-capability-seam.zh.md      |   2 +
 ...26-08-09-md-fragment-anchor-gate.i18n.yaml |   6 +
 .../2026-08-09-md-fragment-anchor-gate.md     |  32 ++++
 .../2026-08-09-md-fragment-anchor-gate.zh.md  |  32 ++++
 .agents/skills/dsh-doc-standards/SKILL.md     |   2 +-
 docs/AGENTS.md                                |   2 +-
 docs/agent-lifecycle.md                       |   2 +-
 docs/subsystems/llm-streaming.i18n.yaml       |   4 +-
 docs/subsystems/llm-streaming.md              |   2 +-
 docs/subsystems/llm-streaming.zh.md           |   2 +-
 packages/boot/app-boot/README.i18n.yaml       |   2 +-
 packages/boot/app-boot/README.zh.md           |   2 +
 packages/core/scope/README.i18n.yaml          |   4 +-
 packages/core/scope/README.md                 |   2 +-
 packages/core/scope/README.zh.md              |   2 +-
 packages/core/system-prompt/README.i18n.yaml  |   2 +-
 packages/core/system-prompt/README.zh.md      |   2 +
 packages/core/tools/README.i18n.yaml          |   4 +-
 packages/core/tools/README.md                 |   2 +-
 packages/core/tools/README.zh.md              |   2 +-
 .../credentials-local/README.i18n.yaml        |   2 +-
 .../credentials-local/README.zh.md            |   2 +
 packages/fs/tool-fs/README.i18n.yaml          |   4 +-
 packages/fs/tool-fs/README.md                 |   2 +-
 packages/fs/tool-fs/README.zh.md              |   2 +-
 scripts/gen-doc-graphs.ts                     |   2 +-
 scripts/verify-md-links.spec.ts               |  83 ++++++++++
 scripts/verify-md-links.ts                    | 148 ++++++++++++++----
 29 files changed, 304 insertions(+), 53 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
 create mode 100644 .agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
 create mode 100644 scripts/verify-md-links.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
index fc370429b6..331aff7916 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
 2026-06-24-web-capability-seam.md: b705236690859961ed69b307dbb59ebefcbd65ac
-2026-06-24-web-capability-seam.zh.md: e3dc836004bf785c6811e4c4014e105266dbaade
+2026-06-24-web-capability-seam.zh.md: 15a16b12119f69cec632e219585600d261fda54f
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
index e3dc836004..15a16b1211 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
@@ -322,6 +322,8 @@ SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他
 
 **大量 web 内容可能损害上下文质量。** 提供方强制执行字节/字符上限并报告 `truncated`；`tool-web` 格式化有界的模型输出，附带清晰的继续或后续引导。
 
+<a id="deferred-work"></a>
+
 ## 推迟工作
 
 - `web_fetch` 的 SSRF/私有网络防护：阻断私有、回环、链路本地、多播及其他非公开目的地，使 `web_fetch` 不再是 SSRF 原语。正确实现不仅仅是 URL 字符串检查——需要先 DNS 解析再连接到已验证的 IP（防御 DNS rebinding/TOCTOU）、跨重定向的每跳重新验证，以及 IPv6 边缘处理（私有范围、IPv4 映射地址）。所调研的参考实现均未做 IP 级阻断（OpenCode 做前缀检查后直接 fetch；Claude Code 依赖集中式主机名黑名单加「私有 URL 会失败」的提示词），因此没有可复制的实现，且这是 harness 唯一的 SSRF 防线——值得一次专门的设计/spike。在其落地之前，`web_fetch` 只能在无法触达敏感内部目标的部署中启用。
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml
new file mode 100644
index 0000000000..734da74005
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.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/process/2026-08-09-md-fragment-anchor-gate.md
+2026-08-09-md-fragment-anchor-gate.md: 190ecb0ed07152761377961ca6221c25908082b0
+2026-08-09-md-fragment-anchor-gate.zh.md: ab08609d8b1410ccf0f36a6ced68729ac20c7658
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
new file mode 100644
index 0000000000..190ecb0ed0
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
@@ -0,0 +1,32 @@
+# Agent Note: verify-md-links validates fragment anchors, closing the last dead-link class
+
+Status: implemented
+
+English | [中文](2026-08-09-md-fragment-anchor-gate.zh.md)
+
+## Problem
+
+`verify-md-links` proved a relative link's target file exists but never looked at the `#fragment`, and the documentation standard compensated with a manual rule: grep anchors yourself before renaming a heading. A corpus sweep found 15 links whose fragments named no anchor in their target — three distinct decay modes: a heading reworded after the link was written (`#security-and-authority-are-explicit-non-goals` vs the note's current `Security and authority are non-goals`), a contract relocated to a different owning document (`tool-fs` linking the seam README for the no-timeout rule that now lives in the group README), and zh pair sides linking English slugs their Chinese headings never produce (`#deferred-work` against `## 推迟工作`). None of these fail any gate, and each silently strands the reader at the top of the target page.
+
+## Decision
+
+`verify-md-links` now resolves fragments too. For every relative link whose target is a Markdown file — same-file `#anchor` links included, which the old checker skipped entirely — the fragment must name a real anchor in the target: a heading's GitHub slug (repeated headings get the renderer's `-1`, `-2`, … suffixes) or an explicit `<a id>`. Fragments onto non-Markdown targets (`file.ts#L10`) carry renderer-owned semantics and stay out of scope, as do external and root-absolute URLs. Anchor sets are collected lazily for any existing target, so links INTO archived notes and vendor documents are validated without making those files sources.
+
+The slug function is GitHub's algorithm, duplicated from `gen-cordis-catalog`'s region-anchor renderer rather than shared across the script/package boundary; the corpus passing this gate is what keeps the two in sync. Chinese pair sides follow the existing repository convention (`docs/glossary.zh.md`, `docs/cordis-primer.zh.md`): keep the English fragment in the link and place an explicit `<a id>` before the Chinese heading, so both language sides expose identical anchors.
+
+The 15 broken fragments are fixed in the same change: stale slugs retargeted to the current headings, the relocated no-timeout contract now linked at its owning group README, and four zh documents given explicit anchors. `docs/AGENTS.md` and the `dsh-doc-standards` skill no longer prescribe the manual anchor grep for Markdown links; anchors cited from TypeScript strings still need one.
+
+## Verification
+
+`scripts/verify-md-links.spec.ts` proves the acceptance paths: slugging (backticks, punctuation, repeat suffixes, explicit `<a id>`), a resolving mixed-link document, a dead same-file fragment, a dead cross-file fragment, and a missing target still reported as `target` rather than `anchor`. The gate runs over the full corpus in doc-sync (`verify-md-links`, 1613 files) and passes only after the 15 fixes — the corpus itself is the red-to-green evidence for each decay mode.
+
+## Alternatives considered
+
+- **Keep the manual-grep rule.** It demonstrably did not hold: the 15 fragments decayed under a gate-driven maintenance culture, because heading rewrites happen in PRs that never look at inbound links. A mechanical invariant belongs in an executed gate.
+- **Point zh links at Chinese-slug anchors.** GitHub slugs CJK headings fine, but the corpus convention is already explicit `<a id>` + English fragments (glossary, primer), which also survives renderers that strip non-ASCII; adopting a second convention would split the corpus.
+- **Share `githubSlug` with the typert generator.** A one-function import would couple a doc gate to a package build; the algorithm is three lines and the corpus gate itself detects divergence (a generator anchor the gate cannot resolve fails the build the moment a page links it).
+- **Validate VitePress slugs as well.** The published site's dead-link check already runs in `website:build`; generated regions carry explicit anchors precisely so the two renderers agree, and hand headings that diverge would fail there.
+
+## Consequences
+
+Renaming a heading now breaks the build wherever a Markdown link cites its anchor, instead of stranding readers; authors fix the inbound links in the same change, exactly as they already must for file renames. Same-file anchors are no longer a blind spot, so zh pages must anchor any English fragment they use. The manual pre-rename grep survives only for anchors cited from TypeScript string literals.
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
new file mode 100644
index 0000000000..ab08609d8b
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
@@ -0,0 +1,32 @@
+# Agent Note（agent 决策记录）：verify-md-links 校验 fragment 锚点，关闭最后一类死链
+
+Status: implemented
+
+[English](2026-08-09-md-fragment-anchor-gate.md) | 中文
+
+## Problem
+
+`verify-md-links` 只证明相对链接的目标文件存在，从不检查 `#fragment`，文档标准以一条人工规则补偿：重命名标题前自己 grep 锚点。一次语料扫描发现 15 条链接的 fragment 在目标中没有对应锚点——三种衰变模式：链接写下后标题被改写（`#security-and-authority-are-explicit-non-goals` 对 note 现在的 `Security and authority are non-goals`）、契约搬迁到另一份属主文档（`tool-fs` 链到 seam README，而无超时规则现居 group README）、zh 侧链接其中文标题永远不会生成的英文 slug（`#deferred-work` 对 `## 推迟工作`）。这些都不触发任何 gate，且每条都把读者悄悄丢在目标页顶部。
+
+## Decision
+
+`verify-md-links` 现在也解析 fragment。对每条目标为 Markdown 文件的相对链接——包括旧检查器完全跳过的同文件 `#anchor` 链接——fragment 必须命名目标中的真实锚点：标题的 GitHub slug（重复标题获得渲染器的 `-1`、`-2`……后缀）或显式 `<a id>`。指向非 Markdown 目标的 fragment（`file.ts#L10`）语义归渲染器所有，不在范围内；外部与根绝对 URL 同样不检查。锚点集合对任意存在的目标惰性收集，因此链入归档 note 与 vendor 文档的链接照常校验，而这些文件不会因此成为扫描源。
+
+slug 函数是 GitHub 的算法，从 `gen-cordis-catalog` 的区块锚点渲染器复制而来，而非跨脚本/包边界共享；语料通过本 gate 即是两者保持同步的机制。中文侧沿用既有语料惯例（`docs/glossary.zh.md`、`docs/cordis-primer.zh.md`）：链接保留英文 fragment，在中文标题前放置显式 `<a id>`，使两个语言侧暴露相同的锚点。
+
+15 条坏 fragment 在同一变更中修复：陈旧 slug 重定向到当前标题，搬迁的无超时契约改链其属主 group README，四份中文文档补上显式锚点。`docs/AGENTS.md` 与 `dsh-doc-standards` skill 不再为 Markdown 链接开人工 grep 锚点的处方；从 TypeScript 字符串引用的锚点仍需人工 grep。
+
+## Verification
+
+`scripts/verify-md-links.spec.ts` 证明各验收路径：slug 化（反引号、标点、重复后缀、显式 `<a id>`）、全部可解析的混合链接文档、死的同文件 fragment、死的跨文件 fragment、以及缺失目标仍报 `target` 而非 `anchor`。gate 在 doc-sync 中跑完整语料（`verify-md-links`，1613 个文件），且只有在 15 条修复之后才通过——语料本身就是每种衰变模式由红转绿的证据。
+
+## Alternatives considered
+
+- **保留人工 grep 规则。** 它被证明守不住：15 条 fragment 在 gate 驱动的维护文化下仍然衰变，因为改写标题的 PR 从不会去看入链。可机械检查的不变式应进入被执行的 gate。
+- **让中文链接指向中文 slug 锚点。** GitHub 对 CJK 标题的 slug 没问题，但语料惯例已是显式 `<a id>` + 英文 fragment（glossary、primer），且它在剥离非 ASCII 的渲染器下也存活；引入第二种惯例会割裂语料。
+- **与 typert 生成器共享 `githubSlug`。** 为一个函数引入包构建耦合不值得；算法只有三行，语料 gate 本身能探测分歧（生成器产出而 gate 无法解析的锚点，在任何页面链接它的那一刻即失败）。
+- **同时校验 VitePress slug。** 发布站点的死链检查已在 `website:build` 中运行；生成区块正是为两种渲染器一致而携带显式锚点，手写标题若有分歧会在那里失败。
+
+## Consequences
+
+重命名标题现在会在任何 Markdown 链接引用其锚点处使构建失败，而非把读者丢在页顶；作者须在同一变更中修复入链，与文件重命名的既有义务完全一致。同文件锚点不再是盲区，中文页面使用英文 fragment 时必须补锚点。人工的重命名前 grep 只对 TypeScript 字符串字面量中的锚点保留。
diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md
index 020768c200..49ab835752 100644
--- a/.agents/skills/dsh-doc-standards/SKILL.md
+++ b/.agents/skills/dsh-doc-standards/SKILL.md
@@ -29,7 +29,7 @@ Then check constraints that make placement expensive or wrong:
 
 - Paired docs (`pnpm run verify-translation-pairing --list`) cost a zh counterpart update and a `--write` re-record on every edit — prefer an unpaired home for content that will churn.
 - Generated catalogs are never hand-edited; if the fact belongs there, change the generator's source.
-- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown links, `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments, but nothing catches heading-anchor fragments — grep `#the-heading` across the repo yourself (one anchor is hardcoded in `scripts/gen-cordis-catalog.ts`).
+- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings (one lives in `scripts/gen-cordis-catalog.ts`) still need a manual grep.
 - A move is atomic: remove from the old home, add to the new home, and fix every inbound link in the same change.
 
 ## Audit the corpus
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index a5eca656db..8d019fce08 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -72,6 +72,6 @@ Hunt these in any doc; the [dsh-doc-standards](../.agents/skills/dsh-doc-standar
 
 ## Cross-reference with machine-checkable links, never free prose
 
-Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` catches missing targets; the [cross-link Agent Note](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md) owns the rationale.
+Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors ([rationale](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md)).
 
 The gate checks file existence, not `#anchor` validity — verify anchors yourself when linking to one.
diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md
index 5bf2c4454c..8690c792be 100644
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -3,7 +3,7 @@
 
 # Agent Turn And Step Lifecycle
 
-This sequence is the visual companion to [architecture.md](architecture.md#loop-lifecycle-session--turn--step). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
+This sequence is the visual companion to [architecture.md](architecture.md#default-loop-lifecycle). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
 
 ```mermaid
 sequenceDiagram
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index f807656000..0945fee0a3 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: c65416f449d1783f398cdd81b0d6987de83a6141
-llm-streaming.zh.md: ce79ecca53edf7213853df118489817451baa7b0
+llm-streaming.md: 1705c45697df98b51ba9f69c8c91b3a8a18dea76
+llm-streaming.zh.md: 591326582c96023df5a184e19e3e4fc812187fb4
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index c65416f449..1705c45697 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -623,7 +623,7 @@ interface LlmCallConfigAdapterDefaults {
 
 ## The seam
 
-`LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmService.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#content-blocks-and-streaming-dsh-llm).
+`LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmService.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#model-content).
 
 ```ts type-equiv
 /** One model call whose config and adapter registration were resolved together. */
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index ce79ecca53..591326582c 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -631,7 +631,7 @@ interface LlmCallConfigAdapterDefaults {
 
 ## seam
 
-`LlmAdapter` 是提供方 seam：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmService.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#content-blocks-and-streaming-dsh-llm)。
+`LlmAdapter` 是提供方 seam：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmService.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#model-content)。
 
 ```ts type-equiv
 /** One model call whose config and adapter registration were resolved together. */
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index 3ae6f5427c..fd61b9bec2 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
 README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
-README.zh.md: 88d1c4ad0ced2f5a6440a1b64e34e738a842f938
+README.zh.md: 454d504be72c2120ec4aeaa1b22545e7d6ba2fee
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 88d1c4ad0c..454d504be7 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -31,6 +31,8 @@ Loader 并发挂载各个条目，因此当其他环节失败时，某个界面
 
 此包不包含 loader 钩子，也不提供开发模式接口。[`dsh` 应用](../../../apps/cli/README.md)持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。
 
+<a id="profiles"></a>
+
 ## Profile
 
 profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则大声失败。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会大声失败（即 `dsh plugin` 路径）。
diff --git a/packages/core/scope/README.i18n.yaml b/packages/core/scope/README.i18n.yaml
index c9212a3998..5db40dd188 100644
--- a/packages/core/scope/README.i18n.yaml
+++ b/packages/core/scope/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/core/scope/README.md
-README.md: 4f32573779a15e8c34b4936bfe75549dfc86d9f6
-README.zh.md: 16ec60a5489f909a46fd5f803dbf08490cd07988
+README.md: ecb442e39e40d5b97a07ccf8a71a190c4009ede8
+README.zh.md: f223d339129bcbef5c5f19ba6d0b453874944c4b
diff --git a/packages/core/scope/README.md b/packages/core/scope/README.md
index 4f32573779..ecb442e39e 100644
--- a/packages/core/scope/README.md
+++ b/packages/core/scope/README.md
@@ -23,7 +23,7 @@ The optional `@deepseek-ai/dsh-scope/invariant` companion owns that runtime asse
 
 ## Design contract
 
-The registration context determines both visibility and ownership, preventing a registration from being visible in one scope but disposed with another. Scopes route trusted same-process plugins; they are not sandboxes or authority boundaries. See the [agent-scope Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals) for rationale and security non-goals.
+The registration context determines both visibility and ownership, preventing a registration from being visible in one scope but disposed with another. Scopes route trusted same-process plugins; they are not sandboxes or authority boundaries. See the [agent-scope Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals) for rationale and security non-goals.
 
 Scope-aware services define a concrete `ScopeLayer` that aggregates their heterogeneous tables and domain helpers. `ScopedLayers.effect()` accepts one synchronous action returning one synchronous undo, installs that undo before optional notification, and reclaims an exact-scope layer only when the complete aggregate is empty. `notify` defaults to `true`; the supplied callback owns whether observer failures throw or are contained. `EntryValues` remains internal, the storage classes are imported from the package root rather than a `/store` subpath, and the shared storage does not define registry-specific filtering or iteration policy. See the [shared scoped-layer storage Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md).
 
diff --git a/packages/core/scope/README.zh.md b/packages/core/scope/README.zh.md
index 16ec60a548..f223d33912 100644
--- a/packages/core/scope/README.zh.md
+++ b/packages/core/scope/README.zh.md
@@ -23,7 +23,7 @@
 
 ## 设计契约
 
-注册上下文同时决定可见性和所有权，防止注册在一个作用域中可见、却随另一个作用域 dispose（资源释放）。作用域用于路由受信任的同进程插件；它们不是沙箱或权限边界。原理与明确排除的安全目标见 [agent 作用域 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals)。
+注册上下文同时决定可见性和所有权，防止注册在一个作用域中可见、却随另一个作用域 dispose（资源释放）。作用域用于路由受信任的同进程插件；它们不是沙箱或权限边界。原理与明确排除的安全目标见 [agent 作用域 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)。
 
 感知作用域的服务会定义具体 `ScopeLayer`，聚合各自不同的表与领域辅助函数。`ScopedLayers.effect()` 接受一个返回同步撤销函数的同步动作，在可选通知前安装该撤销函数，并且只有在完整聚合为空时才回收精确作用域层。`notify` 默认为 `true`；由所提供的回调决定观测方失败是向外抛出还是在内部处理。`EntryValues` 保持内部可见；存储类从包根而非 `/store` 子路径导入；共享存储不定义注册表专属的筛选或迭代策略。详见[共享作用域层存储 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)。
 
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index c94d1722dc..6d56bec297 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/system-prompt/README.md
 README.md: e98c45a8829a945500ef5282d84e1904b31c68bf
-README.zh.md: 5b9e2feaf82866a52cd8197ff5e800decdf3ee7e
+README.zh.md: bf659ea9961a9bb796c1ee1045ac7dad22bb997f
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index 5b9e2feaf8..bf659ea996 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -21,6 +21,8 @@
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void`：贡献提示词变量，在段文本中以 `{{name}}` 引用。带作用域变量会为该 agent 遮蔽同名全局变量。同层重复或无法引用的名称会抛出；`undefined` 表示「本次组装没有值」。随调用 fiber 一并 dispose。
 - `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>`：为一个调用方组装提示词：将全局层与 `context.scope` 的层合并，并在变换 seam 前分离工具 schema。它经过按作用域筛选的 `system-prompt/assemble` waterfall，并返回其权威结果。可选的 `context.signal` 显式控制本次组装请求；提供方与监听器可以配合该信号，但不得将它保留给另一轮次。当已配置的 `toolOrder` 指名提供方 `knownNames` 全集以外的工具，或提供方返回保留的其余项名称时，调用会被拒绝。
 
+<a id="live-events"></a>
+
 ### 实时事件
 
 `system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。[system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) 的生成区块拥有签名与分发契约。
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index b19e86ce84..19d71e4dff 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: f3f25f908a4ba8016d38f7777fe72691dba4afb1
-README.zh.md: 796ee8e1aa8de88f979d825df5e0b4f39ab7bcf1
+README.md: 97aa97c6ca7675ff5b891e62224a4d1d7780ef42
+README.zh.md: f402722c81e1c7be9f45202a7bc79bfc85a41512
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index f3f25f908a..97aa97c6ca 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -18,7 +18,7 @@ tools:
 ### Public API
 
 - `ctx.tools.register(definition: ToolDefinition): () => void` Register a trusted typed same-process definition with a mandatory canonical `output` declaration. The layer is the calling context's scope: a plain plugin context registers globally; an agent's `agent.ctx` registers for that agent alone, shadowing a same-named global tool there. Duplicate names within one layer throw; non-native modes also reject the reserved `run_code` transport name. Missing or unsupported output declarations and a non-positive or non-finite `timeoutMs` fail at registration. The optional synchronous `finalizeContent` callback is snapshotted when a call starts and may replace only final model-facing content after every pipeline outcome is normalized, including an error discovered while materializing another result field. Disposed with the calling fiber.
-- `ctx.tools.restrict(filter)` applies an agent-scoped allow/deny mask to global tools and throws from a plain context. The filter is snapshotted at registration; multiple masks intersect and scope-local tools merge afterwards. Deny masks admit later unnamed globals, while allow masks exclude later names. Unknown, local, or reserved names and empty filters reject. This is live visibility composition, not an authority boundary; see the [scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals).
+- `ctx.tools.restrict(filter)` applies an agent-scoped allow/deny mask to global tools and throws from a plain context. The filter is snapshotted at registration; multiple masks intersect and scope-local tools merge afterwards. Deny masks admit later unnamed globals, while allow masks exclude later names. Unknown, local, or reserved names and empty filters reject. This is live visibility composition, not an authority boundary; see the [scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals).
 - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined` Resolution as one scope sees it (shadowing applied; a restricted-away global reads as absent) — presenters pass the calling agent so the card matches what executed.
 - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]` Schemas of everything the scope can see (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog.md](../../../docs/tool-catalog.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog Agent Note](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)).
 - `ctx.tools.guard(guard: ToolGuard): () => void` Register a monotonic synchronous execution guard after `tools/pre-execute`: returning a reason denies the call, while `undefined` leaves it unchanged. A plain-context guard applies globally; an `agent.ctx` guard applies only to that agent. Later waterfall listeners cannot turn a guard denial back into permission. Disposed with the calling fiber.
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 796ee8e1aa..f402722c81 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -18,7 +18,7 @@ tools:
 ### 公开 API
 
 - `ctx.tools.register(definition: ToolDefinition): () => void`：注册一个受信任、带类型的同进程定义，其中必须包含规范的 `output` 声明。所在层由调用上下文的作用域决定：普通插件上下文会全局注册；agent 的 `agent.ctx` 只为该 agent 注册，并在此处遮蔽同名全局工具。同一层内名称重复会抛出；非原生模式还会拒绝保留的 `run_code` 传输名称。缺失或不受支持的输出声明，以及非正数或非有限的 `timeoutMs`，都会使注册失败。可选的同步 `finalizeContent` 回调会在调用开始时创建快照；在所有流水线结果规范化之后，它只能替换最终面向模型的内容，包括实体化其他结果字段时发现的错误。随调用 fiber dispose（资源释放）。
-- `ctx.tools.restrict(filter)`：对全局工具应用 agent 作用域的允许／拒绝掩码；从普通上下文调用会抛出。筛选器在注册时创建快照；多个掩码取交集，随后再合并作用域本地工具。拒绝掩码会接纳后来出现且未点名的全局工具，而允许掩码会排除后来出现的名称。未知、本地或保留名称以及空筛选器都会被拒绝。这是实时可见性组合，不是权限边界；参见[作用域安全非目标](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals)。
+- `ctx.tools.restrict(filter)`：对全局工具应用 agent 作用域的允许／拒绝掩码；从普通上下文调用会抛出。筛选器在注册时创建快照；多个掩码取交集，随后再合并作用域本地工具。拒绝掩码会接纳后来出现且未点名的全局工具，而允许掩码会排除后来出现的名称。未知、本地或保留名称以及空筛选器都会被拒绝。这是实时可见性组合，不是权限边界；参见[作用域安全非目标](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)。
 - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined`：按某个作用域所见的结果解析（应用遮蔽；被限制掉的全局工具视为不存在）。呈现器会传入发起调用的 agent，使卡片与实际执行内容一致。
 - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]`：返回该作用域可见的所有 schema（不含 `execute` 函数）。已交付工具的 schema 收录在 [docs/tool-catalog.md](../../../docs/tool-catalog.md) 中；该目录通过启动每个工具插件并采集此方法的结果生成（参见[工具 schema 目录 Agent Note](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)）。
 - `ctx.tools.guard(guard: ToolGuard): () => void`：在 `tools/pre-execute` 之后注册单调同步执行守卫：返回理由会拒绝调用，返回 `undefined` 则保持原决定。普通上下文守卫全局生效；`agent.ctx` 守卫只对该 agent 生效。后续 waterfall（瀑布式事件）监听器无法将守卫的拒绝重新变为允许。随调用 fiber dispose。
diff --git a/packages/credentials/credentials-local/README.i18n.yaml b/packages/credentials/credentials-local/README.i18n.yaml
index 182ac31809..f0971f5d17 100644
--- a/packages/credentials/credentials-local/README.i18n.yaml
+++ b/packages/credentials/credentials-local/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/credentials/credentials-local/README.md
 README.md: 6051c07628c0214f9396d12554719c5614610826
-README.zh.md: c6f3901af925d4bd31d2dcfbf5f5f65de62dac81
+README.zh.md: 23f48080136b5d212bef34d931a74773c5da4fd3
diff --git a/packages/credentials/credentials-local/README.zh.md b/packages/credentials/credentials-local/README.zh.md
index c6f3901af9..23f4808013 100644
--- a/packages/credentials/credentials-local/README.zh.md
+++ b/packages/credentials/credentials-local/README.zh.md
@@ -49,6 +49,8 @@ OPENAI_API_KEY: sk-…
 
 外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。提供方自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则明确报错。
 
+<a id="security-boundary"></a>
+
 ## 安全边界
 
 文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的 Harness home 各层](../../boot/app-boot/README.md#profiles)）——因此要拿到这个值，需要刻意去读一条并未交给 agent（智能体）的路径。
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index e9000e3500..301816a56e 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md
-README.md: 28880860dc6c89745eb21fbf732d04f596f9b07f
-README.zh.md: 8af0aec51e71681211bbd5a4f582be8b8b0271b8
+README.md: 6f96970d8194c0992f9b955b95aec092185054b2
+README.zh.md: 2de8b02cd47f07af5a04a85694aec05214772a7f
diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md
index 28880860dc..6f96970d81 100644
--- a/packages/fs/tool-fs/README.md
+++ b/packages/fs/tool-fs/README.md
@@ -150,4 +150,4 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 - **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies bash-backed `glob` and `grep` rather than extending the filesystem seam.
 - **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`.
-- **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only ([provider rationale](../fs/README.md#no-io-deadline)).
+- **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only ([provider rationale](../README.md#no-timeouts-on-file-io)).
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index 8af0aec51e..2de8b02cd4 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -150,4 +150,4 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 - **未交付面向模型的目录列表工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 [`dsh-tool-fs-search`](../tool-fs-search/) 包则提供基于 bash 的 `glob` 与 `grep`，而不是扩展文件系统 seam。
 - **`read` 只处理 UTF-8 文本文件**：二进制安全读取和 PDF/图像/多模态内容均延期处理；目录目标为 `FS_NOT_REGULAR_FILE`。
-- **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见[提供方理由](../fs/README.md#no-io-deadline)）。
+- **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见[提供方理由](../README.md#no-timeouts-on-file-io)）。
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 1c4cce0fa3..cc26b6b0af 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -1154,7 +1154,7 @@ function renderLifecycle(): string {
   const maintenance = 'curated Mermaid sequence; exact event signatures live in the generated Cordis catalog'
   return [
     ...generatedHeader('Agent Turn And Step Lifecycle'),
-    'This sequence is the visual companion to [architecture.md](architecture.md#loop-lifecycle-session--turn--step). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.',
+    'This sequence is the visual companion to [architecture.md](architecture.md#default-loop-lifecycle). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.',
     '',
     '```mermaid',
     'sequenceDiagram',
diff --git a/scripts/verify-md-links.spec.ts b/scripts/verify-md-links.spec.ts
new file mode 100644
index 0000000000..4578583472
--- /dev/null
+++ b/scripts/verify-md-links.spec.ts
@@ -0,0 +1,83 @@
+/**
+ * Acceptance-path coverage for fragment validation in `verify-md-links`: a
+ * `#fragment` onto a Markdown target — same-file anchors included — must name
+ * a real heading slug or explicit `<a id>`, while non-Markdown fragments and
+ * external targets stay out of scope.
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { documentAnchors, findViolations, githubSlug } from './verify-md-links.ts'
+
+const roots: string[] = []
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function layout(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), 'md-links-'))
+  roots.push(root)
+  for (const [rel, content] of Object.entries(files)) {
+    mkdirSync(join(root, rel, '..'), { recursive: true })
+    writeFileSync(join(root, rel), content)
+  }
+  return root
+}
+
+function violationsIn(root: string, rel: string): { url: string; reason: string }[] {
+  const cache = new Map<string, Set<string>>()
+  const anchorsOf = (abs: string): Set<string> => {
+    const hit = cache.get(abs)
+    if (hit) return hit
+    const anchors = documentAnchors(readFileSync(abs, 'utf8'))
+    cache.set(abs, anchors)
+    return anchors
+  }
+  return findViolations(join(root, rel), anchorsOf, root).map(({ url, reason }) => ({ url, reason }))
+}
+
+describe('documentAnchors', () => {
+  it('slugs headings, suffixes repeats, and reads explicit <a id> anchors', () => {
+    const anchors = documentAnchors([
+      '# My Doc',
+      '## Live `events` — mode!',
+      '## Repeat',
+      '## Repeat',
+      '<a id="hand-anchor"></a>',
+      '',
+    ].join('\n'))
+    expect(anchors).toEqual(new Set(['my-doc', 'live-events--mode', 'repeat', 'repeat-1', 'hand-anchor']))
+    expect(githubSlug('Security and authority are non-goals')).toBe('security-and-authority-are-non-goals')
+  })
+})
+
+describe('findViolations fragments', () => {
+  it('accepts resolving same-file and cross-file fragments, non-md fragments, and externals', () => {
+    const root = layout({
+      'a.md': '# A\n\n## Deferred work\n\n[self](#deferred-work) [b](b.md#part-two) [code](x.ts#L10) [ext](https://x.example/#frag)\n',
+      'b.md': '# B\n\n## Part two\n',
+      'x.ts': 'export {}\n',
+    })
+    expect(violationsIn(root, 'a.md')).toEqual([])
+  })
+
+  it('rejects a same-file fragment that names no heading or <a id>', () => {
+    const root = layout({ 'a.md': '# A\n\n[gone](#deferred-work)\n' })
+    expect(violationsIn(root, 'a.md')).toEqual([{ url: '#deferred-work', reason: 'anchor' }])
+  })
+
+  it('rejects a cross-file fragment missing from the target document', () => {
+    const root = layout({
+      'a.md': '# A\n\n[stale](b.md#old-heading)\n',
+      'b.md': '# B\n\n## New heading\n',
+    })
+    expect(violationsIn(root, 'a.md')).toEqual([{ url: 'b.md#old-heading', reason: 'anchor' }])
+  })
+
+  it('still rejects a missing target file, reported as target not anchor', () => {
+    const root = layout({ 'a.md': '# A\n\n[ghost](missing.md#anything)\n' })
+    expect(violationsIn(root, 'a.md')).toEqual([{ url: 'missing.md#anything', reason: 'target' }])
+  })
+})
diff --git a/scripts/verify-md-links.ts b/scripts/verify-md-links.ts
index 969b0f5e44..0286f6d516 100644
--- a/scripts/verify-md-links.ts
+++ b/scripts/verify-md-links.ts
@@ -1,8 +1,10 @@
 /**
- * Verify that relative Markdown links, images, and definitions resolve. URL,
- * root-absolute, and in-page targets are excluded; query strings and fragments
- * do not affect resolution against the source file. The checker never rewrites,
- * and symlinked instruction files are deduped.
+ * Verify that relative Markdown links, images, and definitions resolve — the
+ * target file must exist AND a `#fragment` onto a Markdown target (including
+ * a same-file `#anchor`) must name a real heading slug or explicit `<a id>`.
+ * URL and root-absolute targets are excluded; query strings do not affect
+ * resolution against the source file. The checker never rewrites, and
+ * symlinked instruction files are deduped.
  */
 
 import { existsSync, readFileSync } from 'node:fs'
@@ -28,21 +30,22 @@ const PATTERNS = [
   'skills/**/*.md',
 ]
 
-/** A broken relative link: a target path that does not resolve to a file. */
+/** A broken relative link: a missing target path or a missing anchor on it. */
 interface Violation {
   file: string
   /** 1-based line where the link/image/definition node starts. */
   line: number
   url: string
+  /** What failed: the target file or the fragment onto it. */
+  reason: 'target' | 'anchor'
 }
 
 /**
  * True for targets this gate must NOT check: scheme-qualified URLs (`https:`,
- * `mailto:`, …), protocol-relative (`//host`), root-absolute (`/path`), and
- * pure in-page anchors (`#frag`). Everything else is a relative path we own.
+ * `mailto:`, …), protocol-relative (`//host`), and root-absolute (`/path`).
+ * Pure in-page anchors (`#frag`) ARE checked, against the source file itself.
  */
-function isExternalOrAnchor(url: string): boolean {
-  if (url.startsWith('#')) return true
+function isExternal(url: string): boolean {
   if (url.startsWith('//')) return true
   if (url.startsWith('/')) return true
   // A scheme like `https:` / `mailto:` — a colon before any slash, dot, or hash.
@@ -69,22 +72,105 @@ function pathPart(url: string): string {
   }
 }
 
-/** Find every broken relative cross-link in one Markdown file via its AST. */
-function findViolations(absPath: string): Violation[] {
-  const file = relative(root, absPath)
+/** The percent-decoded `#fragment` of a link target, or null when it has none. */
+function fragmentPart(url: string): string | null {
+  const hash = url.indexOf('#')
+  if (hash === -1) return null
+  const raw = url.slice(hash + 1).replace(/\?.*$/, '')
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    // Same stance as pathPart: a malformed escape names no anchor anyone
+    // meant, so the raw text flows into the lookup and is reported missing.
+    return raw
+  }
+}
+
+/**
+ * GitHub's heading-slug algorithm (lowercase; drop everything but letters,
+ * numbers, spaces, hyphens; spaces become hyphens) — the same rule
+ * `gen-cordis-catalog`'s region anchors are built from, kept in sync by the
+ * corpus passing this gate rather than by a shared import across the
+ * script/package boundary.
+ * @param heading - the rendered heading text.
+ * @returns the anchor GitHub assigns the first occurrence of the heading.
+ */
+export function githubSlug(heading: string): string {
+  return heading.toLowerCase().replace(/[^\p{L}\p{N} -]/gu, '').replaceAll(' ', '-')
+}
+
+/**
+ * Every anchor one Markdown document exposes: each heading's GitHub slug
+ * (repeated headings get the renderer's `-1`, `-2`, … suffixes) plus every
+ * explicit `<a id="…">`. Lowercased for case-insensitive fragment matching.
+ * @param source - the document's full Markdown text.
+ * @returns the set of valid fragments for links into this document.
+ */
+export function documentAnchors(source: string): Set<string> {
+  const anchors = new Set<string>()
+  const seen = new Map<string, number>()
+  const tree = parseMarkdown(source)
+  visitMarkdown(tree, (node: Nodes): void => {
+    if (node.type === 'heading') {
+      const text = source.slice(node.position?.start.offset ?? 0, node.position?.end.offset ?? 0)
+        .replace(/^#{1,6}\s+/, '')
+        .replace(/[`*_]/g, '')
+      const base = githubSlug(text)
+      const bump = seen.get(base) ?? 0
+      seen.set(base, bump + 1)
+      anchors.add(bump === 0 ? base : `${base}-${bump}`)
+    }
+  })
+  for (const match of source.matchAll(/<a id="([^"]+)"/g)) anchors.add((match[1] ?? '').toLowerCase())
+  return anchors
+}
+
+/** Lazily collect and cache the anchor set of any existing Markdown file. */
+function anchorCache(): (absPath: string) => Set<string> {
+  const cache = new Map<string, Set<string>>()
+  return (absPath) => {
+    const hit = cache.get(absPath)
+    if (hit) return hit
+    const anchors = documentAnchors(readFileSync(absPath, 'utf8'))
+    cache.set(absPath, anchors)
+    return anchors
+  }
+}
+
+/**
+ * Find every broken relative cross-link in one Markdown file via its AST: a
+ * relative target that does not exist, or a fragment onto a Markdown file
+ * (same-file `#anchor` links included) that names no heading slug or explicit
+ * `<a id>` there. Fragments onto non-Markdown targets (`file.ts#L10`) carry
+ * renderer-owned semantics and are not judged.
+ * @param absPath - absolute path of the Markdown source to scan.
+ * @param anchorsOf - anchor lookup shared across files for cross-link checks.
+ * @param scanRoot - repository root violations are reported relative to.
+ * @returns one entry per broken link, in document order.
+ */
+export function findViolations(
+  absPath: string,
+  anchorsOf: (abs: string) => Set<string>,
+  scanRoot: string = root,
+): Violation[] {
+  const file = relative(scanRoot, absPath)
   const dir = dirname(absPath)
   const source = readFileSync(absPath, 'utf8')
   const tree = parseMarkdown(source)
   const out: Violation[] = []
 
   const check = (url: string, node: Nodes): void => {
-    if (isExternalOrAnchor(url)) return
+    if (isExternal(url)) return
     const target = pathPart(url)
-    // A bare `#anchor` reduced to empty path is a same-file anchor — skip.
-    if (target === '') return
-    const resolved = resolve(dir, target)
+    const resolved = target === '' ? absPath : resolve(dir, target)
     if (!existsSync(resolved)) {
-      out.push({ file, line: node.position?.start.line ?? 0, url })
+      out.push({ file, line: node.position?.start.line ?? 0, url, reason: 'target' })
+      return
+    }
+    const fragment = fragmentPart(url)
+    if (fragment === null || !resolved.endsWith('.md')) return
+    if (!anchorsOf(resolved).has(fragment.toLowerCase())) {
+      out.push({ file, line: node.position?.start.line ?? 0, url, reason: 'anchor' })
     }
   }
 
@@ -96,18 +182,22 @@ function findViolations(absPath: string): Violation[] {
   return out
 }
 
-// Archived notes remain valid link targets, but their historical outbound links are frozen.
-const files = uniqueRepoFiles(root, PATTERNS, isArchivedAgentNotePath)
-const all = files.flatMap(file => findViolations(file.abs))
-const checked = files.length
+// Run only when invoked as a script, not when imported by the spec.
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  // Archived notes remain valid link targets, but their historical outbound links are frozen.
+  const files = uniqueRepoFiles(root, PATTERNS, isArchivedAgentNotePath)
+  const anchorsOf = anchorCache()
+  const all = files.flatMap(file => findViolations(file.abs, anchorsOf))
+  const checked = files.length
 
-if (all.length === 0) {
-  console.log(`verify-md-links: ${checked} file(s) checked, all relative cross-links resolve.`)
-  process.exit(0)
-}
+  if (all.length === 0) {
+    console.log(`verify-md-links: ${checked} file(s) checked, all relative cross-links and fragments resolve.`)
+    process.exit(0)
+  }
 
-console.error('verify-md-links: broken relative cross-links found (target does not exist):')
-for (const v of all) {
-  console.error(`  ${v.file}:${v.line}  ${v.url}`)
+  console.error('verify-md-links: broken relative cross-links found:')
+  for (const v of all) {
+    console.error(`  ${v.file}:${v.line}  ${v.url}  (${v.reason === 'target' ? 'target does not exist' : 'no such anchor in target'})`)
+  }
+  process.exit(1)
 }
-process.exit(1)

From dad596348419e15a3f93943d0ea89410b6fe9e03 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 10:39:11 +0800
Subject: [PATCH 428/516] =?UTF-8?q?fix(doc-gates):=20review=20findings=20?=
 =?UTF-8?q?=E2=80=94=20GitHub-slugger=20parity=20and=20the=20surviving=20o?=
 =?UTF-8?q?ld-rule=20prose?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ds-review-bot round: slugs now come from RENDERED heading text (links,
inline code, emphasis) with underscores kept and GitHub's occupied-set
repeat suffixes; explicit <a id> anchors register only from real HTML flow
(fences, inline code, and comments no longer produce phantoms); fragment
matching is exact-case since element ids are. anchorCache is exported and
the spec reuses it. The contradicting 'gate checks file existence, not
#anchor validity' sentence in docs/AGENTS.md is gone; the dsh-doc-standards
residual caveat names the real TS-string anchor homes; the 2026-06-18
cross-link note is updated to shipped behavior and cross-linked with the
fragment-gate note.
---
 ...6-06-18-markdown-cross-link-lint.i18n.yaml |  4 +-
 .../2026-06-18-markdown-cross-link-lint.md    |  4 +-
 .../2026-06-18-markdown-cross-link-lint.zh.md |  4 +-
 ...26-08-09-md-fragment-anchor-gate.i18n.yaml |  4 +-
 .../2026-08-09-md-fragment-anchor-gate.md     | 12 ++--
 .../2026-08-09-md-fragment-anchor-gate.zh.md  | 12 ++--
 .agents/skills/dsh-doc-standards/SKILL.md     |  2 +-
 docs/AGENTS.md                                |  2 -
 scripts/verify-md-links.spec.ts               | 49 ++++++++++----
 scripts/verify-md-links.ts                    | 64 +++++++++++--------
 10 files changed, 97 insertions(+), 60 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml
index bc6582cb20..e5112c08e1 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.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 .agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
-2026-06-18-markdown-cross-link-lint.md: b8b1337e9d758da6a4cc0bb46a6b37906357f877
-2026-06-18-markdown-cross-link-lint.zh.md: 9b627ebb17a0567424ca0caaeac8edd9b36917f2
+2026-06-18-markdown-cross-link-lint.md: 21c6884d3fd891794a11125a9aa51ac2bcb29059
+2026-06-18-markdown-cross-link-lint.zh.md: 444cf6eb97d95049d4e6b7bb5f44138051f6577a
diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
index b8b1337e9d..21c6884d3f 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
@@ -20,11 +20,11 @@ A fourth `doc-sync` gate, `verify-md-links` (`scripts/verify-md-links.ts`), mirr
 
 Scope matches the other gates plus the AGENTS.md pair and the repo-authored agent-skill Markdown under `.agents/skills/` (those skill files cross-link into the docs tree, so this reorg rewrote links in them too): `README.md`, `docs/**/*.md`, `packages/*/README.md`, `AGENTS.md`, `packages/AGENTS.md`, `.agents/skills/**/*.md`, deduped by real path (the `CLAUDE.md` symlinks resolve onto the AGENTS.md files). It is wired into `doc-sync`, so relevant documentation changes and CI exercise the same broken-link check.
 
-This gate checks *existence*, not anchor validity: a link to a real file with a `#wrong-heading` fragment still passes (the file resolves; the fragment is stripped).
+The gate now also checks `#fragment` anchors on Markdown targets — same-file anchors included — against heading slugs and explicit `<a id>`; the [fragment-anchor decision](2026-08-09-md-fragment-anchor-gate.md) owns that mechanism and the slug rules.
 
 ## Alternatives considered
 
-**Anchor-level validity checking** — heavier and lower-value; file-level dead links are the failure that actually bit. The scope cut is deliberate: authors verify `#fragment` anchors themselves when linking to one.
+**Anchor-level validity checking** — deferred here as heavier and lower-value (file-level dead links were the failure that had actually bit), leaving authors to verify `#fragment` anchors themselves. That manual rule did not hold; the [fragment-anchor decision](2026-08-09-md-fragment-anchor-gate.md) later added the check.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
index 9b627ebb17..444cf6eb97 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
@@ -20,11 +20,11 @@ Status: implemented
 
 检查范围与其他门禁一致，并额外包含 AGENTS.md 文件对以及 `.agents/skills/` 下仓库自有的 agent skill（技能）Markdown（这些 skill 文件会交叉链接到 docs 目录树，因此本次重组也改写了其中的链接）：`README.md`、`docs/**/*.md`、`packages/*/README.md`、`AGENTS.md`、`packages/AGENTS.md`、`.agents/skills/**/*.md`。系统按真实路径去重（`CLAUDE.md` symlink 会解析到 AGENTS.md 文件）。该检查接入 `doc-sync`，因此相关文档变更与 CI 执行同一套断链检查。
 
-本门禁检查的是*文件存在性*，而非锚点有效性：指向一个真实文件但带有 `#wrong-heading` 片段的链接仍会通过（文件路径可解析；片段被剥除）。
+本门禁现在也检查 Markdown 目标上的 `#fragment` 锚点——包括同文件锚点——对照标题 slug 与显式 `<a id>`；该机制与 slug 规则归 [fragment 锚点决定](2026-08-09-md-fragment-anchor-gate.md)所有。
 
 ## 曾考虑的替代方案
 
-**锚点级有效性检查**：更重且价值更低；实际造成问题的是文件级死链。这一范围裁剪是有意为之：作者在链接到某个锚点时自行验证 `#fragment`。
+**锚点级有效性检查**：当时以更重且价值更低为由推迟（实际咬过人的是文件级死链），把 `#fragment` 验证留给作者人工完成。该人工规则没有守住；[fragment 锚点决定](2026-08-09-md-fragment-anchor-gate.md)后来补上了这项检查。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml
index 734da74005..842fd1f468 100644
--- a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.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 .agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
-2026-08-09-md-fragment-anchor-gate.md: 190ecb0ed07152761377961ca6221c25908082b0
-2026-08-09-md-fragment-anchor-gate.zh.md: ab08609d8b1410ccf0f36a6ced68729ac20c7658
+2026-08-09-md-fragment-anchor-gate.md: e02a917bedd9649a2326e3fb1f53072ac05c88a8
+2026-08-09-md-fragment-anchor-gate.zh.md: dcc0644ae064c161ef5232654993f0e6c872064c
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
index 190ecb0ed0..e02a917bed 100644
--- a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.md
@@ -10,23 +10,23 @@ English | [中文](2026-08-09-md-fragment-anchor-gate.zh.md)
 
 ## Decision
 
-`verify-md-links` now resolves fragments too. For every relative link whose target is a Markdown file — same-file `#anchor` links included, which the old checker skipped entirely — the fragment must name a real anchor in the target: a heading's GitHub slug (repeated headings get the renderer's `-1`, `-2`, … suffixes) or an explicit `<a id>`. Fragments onto non-Markdown targets (`file.ts#L10`) carry renderer-owned semantics and stay out of scope, as do external and root-absolute URLs. Anchor sets are collected lazily for any existing target, so links INTO archived notes and vendor documents are validated without making those files sources.
+`verify-md-links` now resolves fragments too (superseding the deferred scope cut in the [cross-link decision](2026-06-18-markdown-cross-link-lint.md)). For every relative link whose target is a Markdown file — same-file `#anchor` links included, which the old checker skipped entirely — the fragment must name a real anchor in the target: a heading's GitHub slug or an explicit `<a id>` in real HTML flow (code samples and commented-out anchors register nothing). Slugs are computed from the RENDERED heading text via the repository's own `markdownHeadingLines`, so links, inline code, and emphasis inside a heading slug as GitHub renders them; underscores survive (`#showcase-web_fetch`); repeated slugs get GitHub's occupied-set `-1`, `-2`, … suffixes; matching is exact-case, since element ids are case-sensitive. Fragments onto non-Markdown targets (`file.ts#L10`) carry renderer-owned semantics and stay out of scope, as do external and root-absolute URLs. Anchor sets are collected lazily for any existing target (`anchorCache`), so links INTO archived notes and vendor documents are validated without making those files sources.
 
-The slug function is GitHub's algorithm, duplicated from `gen-cordis-catalog`'s region-anchor renderer rather than shared across the script/package boundary; the corpus passing this gate is what keeps the two in sync. Chinese pair sides follow the existing repository convention (`docs/glossary.zh.md`, `docs/cordis-primer.zh.md`): keep the English fragment in the link and place an explicit `<a id>` before the Chinese heading, so both language sides expose identical anchors.
+The slug function differs from `gen-cordis-catalog`'s region-anchor slugger (which drops underscores): the generator's headings are always reachable through its explicit `<a id>` anchors, so the two need not share one rule. Chinese pair sides follow the existing repository convention (`docs/glossary.zh.md`, `docs/cordis-primer.zh.md`): keep the English fragment in the link and place an explicit `<a id>` before the Chinese heading, so both language sides expose identical anchors.
 
-The 15 broken fragments are fixed in the same change: stale slugs retargeted to the current headings, the relocated no-timeout contract now linked at its owning group README, and four zh documents given explicit anchors. `docs/AGENTS.md` and the `dsh-doc-standards` skill no longer prescribe the manual anchor grep for Markdown links; anchors cited from TypeScript strings still need one.
+The 15 broken fragments are fixed in the same change: stale slugs retargeted to the current headings, the relocated no-timeout contract now linked at its owning group README, and four zh documents given explicit anchors. `docs/AGENTS.md` and the `dsh-doc-standards` skill no longer prescribe the manual anchor grep for Markdown links; it survives only for anchors cited from TypeScript strings whose output never reaches gate-scanned Markdown (today's three all render into scanned pages, so the gate covers them through the committed output).
 
 ## Verification
 
-`scripts/verify-md-links.spec.ts` proves the acceptance paths: slugging (backticks, punctuation, repeat suffixes, explicit `<a id>`), a resolving mixed-link document, a dead same-file fragment, a dead cross-file fragment, and a missing target still reported as `target` rather than `anchor`. The gate runs over the full corpus in doc-sync (`verify-md-links`, 1613 files) and passes only after the 15 fixes — the corpus itself is the red-to-green evidence for each decay mode.
+`scripts/verify-md-links.spec.ts` proves the acceptance paths: rendered-text slugging (backticks, punctuation, a linked heading, kept underscores), occupied-set repeat suffixes, `<a id>` ignored inside fences/inline code/comments, a resolving mixed-link document, dead same-file and cross-file fragments, a case-variant fragment, and a missing target still reported as `target` rather than `anchor`. The gate runs over the full corpus in doc-sync (`verify-md-links`) and passes only after the 15 fixes — the corpus itself is the red-to-green evidence for each decay mode.
 
 ## Alternatives considered
 
 - **Keep the manual-grep rule.** It demonstrably did not hold: the 15 fragments decayed under a gate-driven maintenance culture, because heading rewrites happen in PRs that never look at inbound links. A mechanical invariant belongs in an executed gate.
 - **Point zh links at Chinese-slug anchors.** GitHub slugs CJK headings fine, but the corpus convention is already explicit `<a id>` + English fragments (glossary, primer), which also survives renderers that strip non-ASCII; adopting a second convention would split the corpus.
-- **Share `githubSlug` with the typert generator.** A one-function import would couple a doc gate to a package build; the algorithm is three lines and the corpus gate itself detects divergence (a generator anchor the gate cannot resolve fails the build the moment a page links it).
+- **Share `githubSlug` with the typert generator.** A one-function import would couple a doc gate to a package build, and the two rules genuinely differ (the generator strips underscores; its anchors are explicit `<a id>`s the gate reads directly), so divergence is by design, not drift.
 - **Validate VitePress slugs as well.** The published site's dead-link check already runs in `website:build`; generated regions carry explicit anchors precisely so the two renderers agree, and hand headings that diverge would fail there.
 
 ## Consequences
 
-Renaming a heading now breaks the build wherever a Markdown link cites its anchor, instead of stranding readers; authors fix the inbound links in the same change, exactly as they already must for file renames. Same-file anchors are no longer a blind spot, so zh pages must anchor any English fragment they use. The manual pre-rename grep survives only for anchors cited from TypeScript string literals.
+Renaming a heading now breaks the build wherever a Markdown link cites its anchor, instead of stranding readers; authors fix the inbound links in the same change, exactly as they already must for file renames. Same-file anchors are no longer a blind spot, so zh pages must anchor any English fragment they use. The manual pre-rename grep survives only for anchors cited from TypeScript strings whose output never reaches gate-scanned Markdown.
diff --git a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
index ab08609d8b..dcc0644ae0 100644
--- a/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-md-fragment-anchor-gate.zh.md
@@ -10,23 +10,23 @@ Status: implemented
 
 ## Decision
 
-`verify-md-links` 现在也解析 fragment。对每条目标为 Markdown 文件的相对链接——包括旧检查器完全跳过的同文件 `#anchor` 链接——fragment 必须命名目标中的真实锚点：标题的 GitHub slug（重复标题获得渲染器的 `-1`、`-2`……后缀）或显式 `<a id>`。指向非 Markdown 目标的 fragment（`file.ts#L10`）语义归渲染器所有，不在范围内；外部与根绝对 URL 同样不检查。锚点集合对任意存在的目标惰性收集，因此链入归档 note 与 vendor 文档的链接照常校验，而这些文件不会因此成为扫描源。
+`verify-md-links` 现在也解析 fragment（取代[跨链接决定](2026-06-18-markdown-cross-link-lint.md)中被推迟的范围裁剪）。对每条目标为 Markdown 文件的相对链接——包括旧检查器完全跳过的同文件 `#anchor` 链接——fragment 必须命名目标中的真实锚点：标题的 GitHub slug，或真实 HTML 流中的显式 `<a id>`（代码示例与注释掉的锚点不注册任何东西）。slug 由仓库自有的 `markdownHeadingLines` 从**渲染后**的标题文本计算，因此标题内的链接、行内代码与强调都按 GitHub 的渲染结果 slug；下划线保留（`#showcase-web_fetch`）；重复 slug 获得 GitHub 的占用集 `-1`、`-2`……后缀；匹配区分大小写，因为元素 id 本就区分大小写。指向非 Markdown 目标的 fragment（`file.ts#L10`）语义归渲染器所有，不在范围内；外部与根绝对 URL 同样不检查。锚点集合对任意存在的目标惰性收集（`anchorCache`），因此链入归档 note 与 vendor 文档的链接照常校验，而这些文件不会因此成为扫描源。
 
-slug 函数是 GitHub 的算法，从 `gen-cordis-catalog` 的区块锚点渲染器复制而来，而非跨脚本/包边界共享；语料通过本 gate 即是两者保持同步的机制。中文侧沿用既有语料惯例（`docs/glossary.zh.md`、`docs/cordis-primer.zh.md`）：链接保留英文 fragment，在中文标题前放置显式 `<a id>`，使两个语言侧暴露相同的锚点。
+slug 函数与 `gen-cordis-catalog` 的区块锚点 slugger 不同（后者丢弃下划线）：生成器的标题总能通过其显式 `<a id>` 锚点到达，两者无需共享一条规则。中文侧沿用既有语料惯例（`docs/glossary.zh.md`、`docs/cordis-primer.zh.md`）：链接保留英文 fragment，在中文标题前放置显式 `<a id>`，使两个语言侧暴露相同的锚点。
 
-15 条坏 fragment 在同一变更中修复：陈旧 slug 重定向到当前标题，搬迁的无超时契约改链其属主 group README，四份中文文档补上显式锚点。`docs/AGENTS.md` 与 `dsh-doc-standards` skill 不再为 Markdown 链接开人工 grep 锚点的处方；从 TypeScript 字符串引用的锚点仍需人工 grep。
+15 条坏 fragment 在同一变更中修复：陈旧 slug 重定向到当前标题，搬迁的无超时契约改链其属主 group README，四份中文文档补上显式锚点。`docs/AGENTS.md` 与 `dsh-doc-standards` skill 不再为 Markdown 链接开人工 grep 锚点的处方；人工 grep 只对输出从不进入受检 Markdown 的 TypeScript 字符串锚点保留（当下三处全部渲染进受检页面，gate 经由提交的产物覆盖它们）。
 
 ## Verification
 
-`scripts/verify-md-links.spec.ts` 证明各验收路径：slug 化（反引号、标点、重复后缀、显式 `<a id>`）、全部可解析的混合链接文档、死的同文件 fragment、死的跨文件 fragment、以及缺失目标仍报 `target` 而非 `anchor`。gate 在 doc-sync 中跑完整语料（`verify-md-links`，1613 个文件），且只有在 15 条修复之后才通过——语料本身就是每种衰变模式由红转绿的证据。
+`scripts/verify-md-links.spec.ts` 证明各验收路径：渲染文本 slug 化（反引号、标点、含链接标题、保留下划线）、占用集重复后缀、围栏/行内代码/注释中的 `<a id>` 不注册、全部可解析的混合链接文档、死的同文件与跨文件 fragment、大小写变体 fragment、以及缺失目标仍报 `target` 而非 `anchor`。gate 在 doc-sync 中跑完整语料（`verify-md-links`），且只有在 15 条修复之后才通过——语料本身就是每种衰变模式由红转绿的证据。
 
 ## Alternatives considered
 
 - **保留人工 grep 规则。** 它被证明守不住：15 条 fragment 在 gate 驱动的维护文化下仍然衰变，因为改写标题的 PR 从不会去看入链。可机械检查的不变式应进入被执行的 gate。
 - **让中文链接指向中文 slug 锚点。** GitHub 对 CJK 标题的 slug 没问题，但语料惯例已是显式 `<a id>` + 英文 fragment（glossary、primer），且它在剥离非 ASCII 的渲染器下也存活；引入第二种惯例会割裂语料。
-- **与 typert 生成器共享 `githubSlug`。** 为一个函数引入包构建耦合不值得；算法只有三行，语料 gate 本身能探测分歧（生成器产出而 gate 无法解析的锚点，在任何页面链接它的那一刻即失败）。
+- **与 typert 生成器共享 `githubSlug`。** 为一个函数引入包构建耦合不值得，且两条规则确实不同（生成器剥离下划线；其锚点是 gate 直接读取的显式 `<a id>`），分歧是设计使然而非漂移。
 - **同时校验 VitePress slug。** 发布站点的死链检查已在 `website:build` 中运行；生成区块正是为两种渲染器一致而携带显式锚点，手写标题若有分歧会在那里失败。
 
 ## Consequences
 
-重命名标题现在会在任何 Markdown 链接引用其锚点处使构建失败，而非把读者丢在页顶；作者须在同一变更中修复入链，与文件重命名的既有义务完全一致。同文件锚点不再是盲区，中文页面使用英文 fragment 时必须补锚点。人工的重命名前 grep 只对 TypeScript 字符串字面量中的锚点保留。
+重命名标题现在会在任何 Markdown 链接引用其锚点处使构建失败，而非把读者丢在页顶；作者须在同一变更中修复入链，与文件重命名的既有义务完全一致。同文件锚点不再是盲区，中文页面使用英文 fragment 时必须补锚点。人工的重命名前 grep 只对输出从不进入受检 Markdown 的 TypeScript 字符串锚点保留。
diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md
index 49ab835752..2df8d3774f 100644
--- a/.agents/skills/dsh-doc-standards/SKILL.md
+++ b/.agents/skills/dsh-doc-standards/SKILL.md
@@ -29,7 +29,7 @@ Then check constraints that make placement expensive or wrong:
 
 - Paired docs (`pnpm run verify-translation-pairing --list`) cost a zh counterpart update and a `--write` re-record on every edit — prefer an unpaired home for content that will churn.
 - Generated catalogs are never hand-edited; if the fact belongs there, change the generator's source.
-- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings (one lives in `scripts/gen-cordis-catalog.ts`) still need a manual grep.
+- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings still need a manual grep when their output never reaches gate-scanned Markdown (today's three — `scripts/gen-doc-graphs.ts`, `scripts/gen-persistence-catalog.ts`, `packages/typert/generator/src/cordis-catalog.ts` — all render into scanned pages, so the gate catches them via the committed output).
 - A move is atomic: remove from the old home, add to the new home, and fix every inbound link in the same change.
 
 ## Audit the corpus
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 8d019fce08..672f6ba6f6 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -73,5 +73,3 @@ Hunt these in any doc; the [dsh-doc-standards](../.agents/skills/dsh-doc-standar
 ## Cross-reference with machine-checkable links, never free prose
 
 Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors ([rationale](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md)).
-
-The gate checks file existence, not `#anchor` validity — verify anchors yourself when linking to one.
diff --git a/scripts/verify-md-links.spec.ts b/scripts/verify-md-links.spec.ts
index 4578583472..5be9231a3e 100644
--- a/scripts/verify-md-links.spec.ts
+++ b/scripts/verify-md-links.spec.ts
@@ -5,11 +5,11 @@
  * external targets stay out of scope.
  */
 
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
-import { documentAnchors, findViolations, githubSlug } from './verify-md-links.ts'
+import { anchorCache, documentAnchors, findViolations, githubSlug } from './verify-md-links.ts'
 
 const roots: string[] = []
 afterEach(() => {
@@ -27,19 +27,11 @@ function layout(files: Record<string, string>): string {
 }
 
 function violationsIn(root: string, rel: string): { url: string; reason: string }[] {
-  const cache = new Map<string, Set<string>>()
-  const anchorsOf = (abs: string): Set<string> => {
-    const hit = cache.get(abs)
-    if (hit) return hit
-    const anchors = documentAnchors(readFileSync(abs, 'utf8'))
-    cache.set(abs, anchors)
-    return anchors
-  }
-  return findViolations(join(root, rel), anchorsOf, root).map(({ url, reason }) => ({ url, reason }))
+  return findViolations(join(root, rel), anchorCache(), root).map(({ url, reason }) => ({ url, reason }))
 }
 
 describe('documentAnchors', () => {
-  it('slugs headings, suffixes repeats, and reads explicit <a id> anchors', () => {
+  it('slugs rendered heading text, suffixes repeats, and reads explicit <a id> anchors', () => {
     const anchors = documentAnchors([
       '# My Doc',
       '## Live `events` — mode!',
@@ -51,6 +43,34 @@ describe('documentAnchors', () => {
     expect(anchors).toEqual(new Set(['my-doc', 'live-events--mode', 'repeat', 'repeat-1', 'hand-anchor']))
     expect(githubSlug('Security and authority are non-goals')).toBe('security-and-authority-are-non-goals')
   })
+
+  it('keeps underscores the way GitHub does', () => {
+    expect(githubSlug('Showcase: web_fetch')).toBe('showcase-web_fetch')
+    expect(documentAnchors('## Showcase: web_fetch\n')).toEqual(new Set(['showcase-web_fetch']))
+  })
+
+  it('slugs a heading containing a link from its rendered text', () => {
+    expect(documentAnchors('## [Install](setup.md)\n')).toEqual(new Set(['install']))
+  })
+
+  it('bumps repeat suffixes past occupied slugs, matching GitHub', () => {
+    const anchors = documentAnchors(['## Repeat', '## Repeat-1', '## Repeat', ''].join('\n'))
+    expect(anchors).toEqual(new Set(['repeat', 'repeat-1', 'repeat-2']))
+  })
+
+  it('ignores <a id> inside code fences, inline code, and HTML comments', () => {
+    const anchors = documentAnchors([
+      '# Doc',
+      '```md',
+      '<a id="fenced"></a>',
+      '```',
+      'Inline `<a id="inline"></a>` sample.',
+      '<!-- <a id="commented"></a> -->',
+      '<a id="real"></a>',
+      '',
+    ].join('\n'))
+    expect(anchors).toEqual(new Set(['doc', 'real']))
+  })
 })
 
 describe('findViolations fragments', () => {
@@ -68,6 +88,11 @@ describe('findViolations fragments', () => {
     expect(violationsIn(root, 'a.md')).toEqual([{ url: '#deferred-work', reason: 'anchor' }])
   })
 
+  it('rejects a case-variant fragment: element ids are case-sensitive', () => {
+    const root = layout({ 'a.md': '# A\n\n## Default Loop\n\n[case](#Default-Loop)\n' })
+    expect(violationsIn(root, 'a.md')).toEqual([{ url: '#Default-Loop', reason: 'anchor' }])
+  })
+
   it('rejects a cross-file fragment missing from the target document', () => {
     const root = layout({
       'a.md': '# A\n\n[stale](b.md#old-heading)\n',
diff --git a/scripts/verify-md-links.ts b/scripts/verify-md-links.ts
index 0286f6d516..8d4b99fe5d 100644
--- a/scripts/verify-md-links.ts
+++ b/scripts/verify-md-links.ts
@@ -10,7 +10,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import type { Nodes } from 'mdast'
-import { parseMarkdown, visitMarkdown } from './markdown.ts'
+import { markdownHeadingLines, parseMarkdown, visitMarkdown } from './markdown.ts'
 import { isArchivedAgentNotePath, uniqueRepoFiles } from './repo-files.ts'
 
 const root = resolve(import.meta.dirname, '..')
@@ -88,45 +88,59 @@ function fragmentPart(url: string): string | null {
 
 /**
  * GitHub's heading-slug algorithm (lowercase; drop everything but letters,
- * numbers, spaces, hyphens; spaces become hyphens) — the same rule
- * `gen-cordis-catalog`'s region anchors are built from, kept in sync by the
- * corpus passing this gate rather than by a shared import across the
- * script/package boundary.
- * @param heading - the rendered heading text.
+ * numbers, underscores, spaces, hyphens; spaces become hyphens). Underscores
+ * survive (`## Showcase: web_fetch` → `#showcase-web_fetch`), unlike
+ * `gen-cordis-catalog`'s region-anchor slugs — the generator's headings are
+ * always reachable through its explicit `<a id>` anchors, so the two need not
+ * share one rule.
+ * @param heading - the RENDERED heading text (Markdown syntax already gone).
  * @returns the anchor GitHub assigns the first occurrence of the heading.
  */
 export function githubSlug(heading: string): string {
-  return heading.toLowerCase().replace(/[^\p{L}\p{N} -]/gu, '').replaceAll(' ', '-')
+  return heading.toLowerCase().replace(/[^\p{L}\p{N}_ -]/gu, '').replaceAll(' ', '-')
 }
 
 /**
- * Every anchor one Markdown document exposes: each heading's GitHub slug
- * (repeated headings get the renderer's `-1`, `-2`, … suffixes) plus every
- * explicit `<a id="…">`. Lowercased for case-insensitive fragment matching.
+ * Every anchor one Markdown document exposes: each heading's GitHub slug —
+ * computed from the RENDERED heading text, so links, images, inline code, and
+ * emphasis inside a heading slug the way GitHub renders them — plus every
+ * explicit `<a id="…">` that appears in real HTML flow (a fenced or inline
+ * code sample and a commented-out anchor register nothing). Repeated slugs
+ * get GitHub's occupied-set `-1`, `-2`, … suffixes: each collision bumps the
+ * ORIGINAL slug's counter until a free name is found, so `Repeat`, `Repeat-1`,
+ * `Repeat` yields `repeat`, `repeat-1`, `repeat-2`. Matching is exact —
+ * element ids are case-sensitive.
  * @param source - the document's full Markdown text.
  * @returns the set of valid fragments for links into this document.
  */
 export function documentAnchors(source: string): Set<string> {
   const anchors = new Set<string>()
-  const seen = new Map<string, number>()
-  const tree = parseMarkdown(source)
-  visitMarkdown(tree, (node: Nodes): void => {
-    if (node.type === 'heading') {
-      const text = source.slice(node.position?.start.offset ?? 0, node.position?.end.offset ?? 0)
-        .replace(/^#{1,6}\s+/, '')
-        .replace(/[`*_]/g, '')
-      const base = githubSlug(text)
-      const bump = seen.get(base) ?? 0
-      seen.set(base, bump + 1)
-      anchors.add(bump === 0 ? base : `${base}-${bump}`)
+  const occurrences = new Map<string, number>()
+  for (const heading of markdownHeadingLines(source)) {
+    const base = githubSlug(heading.text)
+    let result = base
+    let bump = occurrences.get(base) ?? 0
+    while (anchors.has(result)) {
+      bump += 1
+      result = `${base}-${bump}`
     }
+    occurrences.set(base, bump)
+    anchors.add(result)
+  }
+  visitMarkdown(parseMarkdown(source), (node: Nodes): void => {
+    if (node.type !== 'html') return
+    const html = node.value.replace(/<!--[\s\S]*?-->/g, '')
+    for (const match of html.matchAll(/<a id="([^"]+)"/g)) anchors.add(match[1] ?? '')
   })
-  for (const match of source.matchAll(/<a id="([^"]+)"/g)) anchors.add((match[1] ?? '').toLowerCase())
   return anchors
 }
 
-/** Lazily collect and cache the anchor set of any existing Markdown file. */
-function anchorCache(): (absPath: string) => Set<string> {
+/**
+ * Lazily collect and cache the anchor set of any existing Markdown file —
+ * shared across all scanned sources so a target parses once.
+ * @returns the memoized absolute-path → anchor-set lookup.
+ */
+export function anchorCache(): (absPath: string) => Set<string> {
   const cache = new Map<string, Set<string>>()
   return (absPath) => {
     const hit = cache.get(absPath)
@@ -169,7 +183,7 @@ export function findViolations(
     }
     const fragment = fragmentPart(url)
     if (fragment === null || !resolved.endsWith('.md')) return
-    if (!anchorsOf(resolved).has(fragment.toLowerCase())) {
+    if (!anchorsOf(resolved).has(fragment)) {
       out.push({ file, line: node.position?.start.line ?? 0, url, reason: 'anchor' })
     }
   }

From 7ff0cbcb7e37e95a865db9f4a2f0eb6389a57953 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 11:02:16 +0800
Subject: [PATCH 429/516] docs: complete Chinese proofreading and generated
 reference pairing

---
 ...026-06-11-runtime-arg-validation.i18n.yaml |    4 +-
 .../2026-06-11-runtime-arg-validation.zh.md   |    4 +-
 .../2026-07-08-agent-scope-contexts.i18n.yaml |    2 +-
 .../2026-07-08-agent-scope-contexts.zh.md     |   20 +-
 ...07-12-agent-scope-runtime-design.i18n.yaml |    2 +-
 ...026-07-12-agent-scope-runtime-design.zh.md |   66 +-
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |    2 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |   64 +-
 ...7-19-gui-web-client-architecture.i18n.yaml |    2 +-
 ...26-07-19-gui-web-client-architecture.zh.md |   30 +-
 ...-19-zstandard-jsonl-session-logs.i18n.yaml |    2 +-
 ...6-07-19-zstandard-jsonl-session-logs.zh.md |    8 +-
 ...7-23-client-plugin-loading-model.i18n.yaml |    2 +-
 ...26-07-23-client-plugin-loading-model.zh.md |   18 +-
 ...ompiler-independent-typert-model.i18n.yaml |    2 +-
 ...27-compiler-independent-typert-model.zh.md |   24 +-
 ...directory-picker-capability-seam.i18n.yaml |    2 +-
 ...-28-directory-picker-capability-seam.zh.md |   46 +-
 ...-29-terminal-llm-stream-failures.i18n.yaml |    2 +-
 ...6-07-29-terminal-llm-stream-failures.zh.md |   20 +-
 ...adapter-owned-max-token-defaults.i18n.yaml |    2 +-
 ...-30-adapter-owned-max-token-defaults.zh.md |    2 +-
 ...07-30-client-locale-full-rollout.i18n.yaml |    2 +-
 ...026-07-30-client-locale-full-rollout.zh.md |   22 +-
 ...-07-30-command-row-copy-contract.i18n.yaml |    2 +-
 ...2026-07-30-command-row-copy-contract.zh.md |   20 +-
 ...-followup-enqueue-and-owned-runs.i18n.yaml |    2 +-
 ...7-30-followup-enqueue-and-owned-runs.zh.md |    4 +-
 ...-manager-native-repository-cache.i18n.yaml |    2 +-
 ...kage-manager-native-repository-cache.zh.md |    4 +-
 ...30-session-end-seed-log-boundary.i18n.yaml |    2 +-
 ...-07-30-session-end-seed-log-boundary.zh.md |   12 +-
 ...-static-repository-plugin-format.i18n.yaml |    2 +-
 ...7-30-static-repository-plugin-format.zh.md |   24 +-
 ...claimed-pre-step-inbox-lifecycle.i18n.yaml |    2 +-
 ...-31-claimed-pre-step-inbox-lifecycle.zh.md |   18 +-
 ...runtime-portable-identifier-seam.i18n.yaml |    2 +-
 ...ode-runtime-portable-identifier-seam.zh.md |   18 +-
 ...-07-31-goal-owned-durable-events.i18n.yaml |    2 +-
 ...2026-07-31-goal-owned-durable-events.zh.md |    6 +-
 ...26-08-01-packaged-ripgrep-search.i18n.yaml |    2 +-
 .../2026-08-01-packaged-ripgrep-search.zh.md  |   14 +-
 ...08-02-typert-remote-method-calls.i18n.yaml |    2 +-
 ...026-08-02-typert-remote-method-calls.zh.md |   36 +-
 ...-pi-ai-declared-provider-catalog.i18n.yaml |    2 +-
 ...8-03-pi-ai-declared-provider-catalog.zh.md |   16 +-
 ...4-configuration-source-ownership.i18n.yaml |    2 +-
 ...08-04-configuration-source-ownership.zh.md |   14 +-
 ...-yaml-and-user-environment-layer.i18n.yaml |    2 +-
 ...ials-yaml-and-user-environment-layer.zh.md |   14 +-
 ...-a-provider-from-the-models-page.i18n.yaml |    2 +-
 ...ring-a-provider-from-the-models-page.zh.md |    2 +-
 ...-provider-endpoint-interrogation.i18n.yaml |    2 +-
 ...raft-provider-endpoint-interrogation.zh.md |   10 +-
 ...08-04-websocket-downlink-carrier.i18n.yaml |    2 +-
 ...026-08-04-websocket-downlink-carrier.zh.md |   12 +-
 ...e-session-jsonl-restore-pipeline.i18n.yaml |    2 +-
 ...large-session-jsonl-restore-pipeline.zh.md |    8 +-
 ...026-08-05-profile-plugin-bundles.i18n.yaml |    2 +-
 .../2026-08-05-profile-plugin-bundles.zh.md   |    4 +-
 .../2026-08-05-session-preparation.i18n.yaml  |    2 +-
 .../2026-08-05-session-preparation.zh.md      |    6 +-
 ...08-05-slot-declaration-injection.i18n.yaml |    2 +-
 ...026-08-05-slot-declaration-injection.zh.md |   10 +-
 ...8-06-agent-event-payload-objects.i18n.yaml |    2 +-
 ...26-08-06-agent-event-payload-objects.zh.md |    6 +-
 ...ubagent-list-identity-projection.i18n.yaml |    2 +-
 ...06-subagent-list-identity-projection.zh.md |   20 +-
 ...arkdown-incremental-ast-renderer.i18n.yaml |    2 +-
 ...eb-markdown-incremental-ast-renderer.zh.md |   12 +-
 ...8-06-web-shell-dist-chunk-layout.i18n.yaml |    2 +-
 ...26-08-06-web-shell-dist-chunk-layout.zh.md |   22 +-
 ...ssion-persistence-write-batching.i18n.yaml |    2 +-
 ...d-session-persistence-write-batching.zh.md |   10 +-
 ...ient-tool-presentation-ownership.i18n.yaml |    2 +-
 ...8-client-tool-presentation-ownership.zh.md |   26 +-
 ...-20-config-hot-reload-resilience.i18n.yaml |    2 +-
 ...6-07-20-config-hot-reload-resilience.zh.md |    4 +-
 .../2026-07-27-glob-sampling.i18n.yaml        |    2 +-
 .../bug-fix/2026-07-27-glob-sampling.zh.md    |   16 +-
 ...d-scrollbars-and-reserved-gutter.i18n.yaml |    2 +-
 ...hemed-scrollbars-and-reserved-gutter.zh.md |    8 +-
 ...-07-28-web-agent-runtime-context.i18n.yaml |    2 +-
 ...2026-07-28-web-agent-runtime-context.zh.md |   12 +-
 ...2026-07-28-web-gui-feedback-loop.i18n.yaml |    2 +-
 .../2026-07-28-web-gui-feedback-loop.zh.md    |   10 +-
 ...9-human-transcript-append-origin.i18n.yaml |    2 +-
 ...07-29-human-transcript-append-origin.zh.md |   38 +-
 ...7-29-pnpm-setup-runner-isolation.i18n.yaml |    2 +-
 ...26-07-29-pnpm-setup-runner-isolation.zh.md |    4 +-
 ...cky-composer-conversation-scroll.i18n.yaml |    2 +-
 ...-sticky-composer-conversation-scroll.zh.md |   16 +-
 ...29-web-details-session-lifecycle.i18n.yaml |    2 +-
 ...-07-29-web-details-session-lifecycle.zh.md |    4 +-
 ...07-30-approval-panel-command-cap.i18n.yaml |    2 +-
 ...026-07-30-approval-panel-command-cap.zh.md |   18 +-
 ...-30-composer-context-stack-order.i18n.yaml |    2 +-
 ...6-07-30-composer-context-stack-order.zh.md |    8 +-
 ...-07-30-hover-popup-pointer-grace.i18n.yaml |    2 +-
 ...2026-07-30-hover-popup-pointer-grace.zh.md |    8 +-
 ...select-custom-answer-composition.i18n.yaml |    2 +-
 ...lti-select-custom-answer-composition.zh.md |    4 +-
 ...rce-checkout-workdir-distinction.i18n.yaml |    2 +-
 ...-source-checkout-workdir-distinction.zh.md |   18 +-
 ...ranscript-log-ordered-projection.i18n.yaml |    2 +-
 ...eb-transcript-log-ordered-projection.zh.md |   40 +-
 ...text-layers-share-one-scrollport.i18n.yaml |    2 +-
 ...ser-text-layers-share-one-scrollport.zh.md |   12 +-
 ...1-english-compaction-checkpoints.i18n.yaml |    2 +-
 ...07-31-english-compaction-checkpoints.zh.md |    4 +-
 ...-fail-loud-releases-the-terminal.i18n.yaml |    2 +-
 ...7-31-fail-loud-releases-the-terminal.zh.md |   18 +-
 ...-fork-anchor-floors-to-event-seq.i18n.yaml |    2 +-
 ...7-31-fork-anchor-floors-to-event-seq.zh.md |    6 +-
 ...6-07-31-web-stop-preserves-queue.i18n.yaml |    2 +-
 .../2026-07-31-web-stop-preserves-queue.zh.md |    4 +-
 ...-ask-user-delegated-caller-guard.i18n.yaml |    2 +-
 ...8-01-ask-user-delegated-caller-guard.zh.md |    4 +-
 ...-08-02-goal-round-wrapup-message.i18n.yaml |    2 +-
 ...2026-08-02-goal-round-wrapup-message.zh.md |   20 +-
 ...ions-require-completed-turn-tail.i18n.yaml |    2 +-
 ...-actions-require-completed-turn-tail.zh.md |    2 +-
 ...odo-first-composer-context-order.i18n.yaml |    2 +-
 ...02-todo-first-composer-context-order.zh.md |    2 +-
 ...3-cli-signal-shutdown-escalation.i18n.yaml |    2 +-
 ...08-03-cli-signal-shutdown-escalation.zh.md |    6 +-
 ...3-hmr-initial-scan-boot-deadlock.i18n.yaml |    2 +-
 ...08-03-hmr-initial-scan-boot-deadlock.zh.md |   18 +-
 ...-composer-tab-gutter-reservation.i18n.yaml |    2 +-
 ...8-04-composer-tab-gutter-reservation.zh.md |   18 +-
 ...versation-column-one-axis-scroll.i18n.yaml |    2 +-
 ...-conversation-column-one-axis-scroll.zh.md |   12 +-
 ...-04-load-pre-react-loop-sessions.i18n.yaml |    2 +-
 ...6-08-04-load-pre-react-loop-sessions.zh.md |   10 +-
 ...ontext-meter-blind-to-compaction.i18n.yaml |    2 +-
 ...05-context-meter-blind-to-compaction.zh.md |   16 +-
 ...actions-require-a-completed-turn.i18n.yaml |    2 +-
 ...ail-actions-require-a-completed-turn.zh.md |    6 +-
 ...e-blank-session-reuse-membership.i18n.yaml |    2 +-
 ...space-blank-session-reuse-membership.zh.md |   16 +-
 ...-08-06-api-key-format-validation.i18n.yaml |    2 +-
 ...2026-08-06-api-key-format-validation.zh.md |   30 +-
 ...rding-step-owned-takeover-chrome.i18n.yaml |    2 +-
 ...nboarding-step-owned-takeover-chrome.zh.md |   22 +-
 ...06-provider-credential-lifecycle.i18n.yaml |    2 +-
 ...-08-06-provider-credential-lifecycle.zh.md |   10 +-
 ...-attribution-observed-top-ledger.i18n.yaml |    2 +-
 ...roll-attribution-observed-top-ledger.zh.md |    8 +-
 ...e-unpriced-replace-compatibility.i18n.yaml |    2 +-
 ...rface-unpriced-replace-compatibility.zh.md |    8 +-
 ...6-06-21-subagent-capability-seam.i18n.yaml |    2 +-
 .../2026-06-21-subagent-capability-seam.zh.md |   24 +-
 .../feature/2026-07-05-skill-system.i18n.yaml |    2 +-
 .../feature/2026-07-05-skill-system.zh.md     |   22 +-
 ...-07-08-background-subagent-tasks.i18n.yaml |    2 +-
 ...2026-07-08-background-subagent-tasks.zh.md |   16 +-
 ...26-07-20-dsh-cli-personal-config.i18n.yaml |    2 +-
 .../2026-07-20-dsh-cli-personal-config.zh.md  |   32 +-
 ...continuable-background-subagents.i18n.yaml |    2 +-
 ...-21-continuable-background-subagents.zh.md |   40 +-
 ...subagent-catalog-and-list-agents.i18n.yaml |    2 +-
 ...ble-subagent-catalog-and-list-agents.zh.md |   30 +-
 ...026-07-23-web-assistant-markdown.i18n.yaml |    2 +-
 .../2026-07-23-web-assistant-markdown.zh.md   |    8 +-
 ...7-23-web-permission-and-approval.i18n.yaml |    2 +-
 ...26-07-23-web-permission-and-approval.zh.md |   16 +-
 ...model-facing-session-query-tools.i18n.yaml |    2 +-
 ...-24-model-facing-session-query-tools.zh.md |   20 +-
 ...n-list-browsing-and-manual-order.i18n.yaml |    2 +-
 ...ssion-list-browsing-and-manual-order.zh.md |   40 +-
 ...-07-25-workspace-ui-product-flow.i18n.yaml |    2 +-
 ...2026-07-25-workspace-ui-product-flow.zh.md |   36 +-
 ...-07-26-todo-parallel-in-progress.i18n.yaml |    2 +-
 ...2026-07-26-todo-parallel-in-progress.zh.md |   14 +-
 ...ative-workspace-directory-picker.i18n.yaml |    2 +-
 ...27-native-workspace-directory-picker.zh.md |    4 +-
 ...-07-27-skill-catalog-hot-refresh.i18n.yaml |    2 +-
 ...2026-07-27-skill-catalog-hot-refresh.zh.md |   12 +-
 ...-27-trajectory-inspection-ledger.i18n.yaml |    2 +-
 ...6-07-27-trajectory-inspection-ledger.zh.md |   16 +-
 ...6-07-27-web-session-fork-actions.i18n.yaml |    2 +-
 .../2026-07-27-web-session-fork-actions.zh.md |   20 +-
 .../2026-07-27-web-session-search.i18n.yaml   |    2 +-
 .../2026-07-27-web-session-search.zh.md       |   14 +-
 ...07-27-web-subagent-conversations.i18n.yaml |    2 +-
 ...026-07-27-web-subagent-conversations.zh.md |   26 +-
 ...ntinuable-subagent-conversations.i18n.yaml |    2 +-
 ...8-continuable-subagent-conversations.zh.md |   16 +-
 ...026-07-28-cross-workspace-resume.i18n.yaml |    2 +-
 .../2026-07-28-cross-workspace-resume.zh.md   |   10 +-
 .../2026-07-28-feedback-command.i18n.yaml     |    2 +-
 .../feature/2026-07-28-feedback-command.zh.md |    6 +-
 ...26-07-28-skill-invocation-policy.i18n.yaml |    2 +-
 .../2026-07-28-skill-invocation-policy.zh.md  |   10 +-
 .../2026-07-28-web-terminal-card.i18n.yaml    |    2 +-
 .../2026-07-28-web-terminal-card.zh.md        |   14 +-
 ...0-config-only-repository-plugins.i18n.yaml |    2 +-
 ...07-30-config-only-repository-plugins.zh.md |   12 +-
 ...continuable-subagent-report-tool.i18n.yaml |    2 +-
 ...-30-continuable-subagent-report-tool.zh.md |   20 +-
 ...0-current-sandbox-policy-context.i18n.yaml |    2 +-
 ...07-30-current-sandbox-policy-context.zh.md |   10 +-
 ...seek-onboarding-credential-setup.i18n.yaml |    2 +-
 ...deepseek-onboarding-credential-setup.zh.md |    8 +-
 ...6-07-30-queued-manual-compaction.i18n.yaml |    2 +-
 .../2026-07-30-queued-manual-compaction.zh.md |    8 +-
 .../2026-07-30-search-render-card.i18n.yaml   |    2 +-
 .../2026-07-30-search-render-card.zh.md       |   10 +-
 ...versioned-gui-welcome-onboarding.i18n.yaml |    2 +-
 ...-30-versioned-gui-welcome-onboarding.zh.md |    8 +-
 .../2026-07-30-web-diff-card.i18n.yaml        |    2 +-
 .../feature/2026-07-30-web-diff-card.zh.md    |   24 +-
 ...026-07-30-web-queue-steer-action.i18n.yaml |    2 +-
 .../2026-07-30-web-queue-steer-action.zh.md   |   18 +-
 .../2026-07-30-web-read-card.i18n.yaml        |    2 +-
 .../feature/2026-07-30-web-read-card.zh.md    |   18 +-
 ...6-07-30-web-result-card-frontend.i18n.yaml |    2 +-
 .../2026-07-30-web-result-card-frontend.zh.md |   24 +-
 .../2026-07-30-web-result-card.i18n.yaml      |    2 +-
 .../feature/2026-07-30-web-result-card.zh.md  |   16 +-
 ...l-row-unified-expand-and-inspect.i18n.yaml |    2 +-
 ...-tool-row-unified-expand-and-inspect.zh.md |   16 +-
 ...1-browser-derived-initial-locale.i18n.yaml |    2 +-
 ...07-31-browser-derived-initial-locale.zh.md |    8 +-
 ...7-31-code-mode-language-dispatch.i18n.yaml |    2 +-
 ...26-07-31-code-mode-language-dispatch.zh.md |   14 +-
 ...31-even-out-shipped-tool-rosters.i18n.yaml |    2 +-
 ...-07-31-even-out-shipped-tool-rosters.zh.md |   18 +-
 ...-31-gui-full-access-confirmation.i18n.yaml |    2 +-
 ...6-07-31-gui-full-access-confirmation.zh.md |   20 +-
 ...mission-default-for-new-sessions.i18n.yaml |    2 +-
 ...-permission-default-for-new-sessions.zh.md |    6 +-
 ...07-31-session-archive-global-set.i18n.yaml |    2 +-
 ...026-07-31-session-archive-global-set.zh.md |   18 +-
 ...7-31-telemetry-anonymous-user-id.i18n.yaml |    2 +-
 ...26-07-31-telemetry-anonymous-user-id.zh.md |   14 +-
 .../2026-07-31-web-default-search.i18n.yaml   |    2 +-
 .../2026-07-31-web-default-search.zh.md       |    2 +-
 ...7-31-web-telemetry-default-mount.i18n.yaml |    2 +-
 ...26-07-31-web-telemetry-default-mount.zh.md |   24 +-
 ...6-07-31-web-workspace-file-links.i18n.yaml |    2 +-
 .../2026-07-31-web-workspace-file-links.zh.md |   16 +-
 ...-workspace-write-surface-default.i18n.yaml |    2 +-
 ...7-31-workspace-write-surface-default.zh.md |    6 +-
 ...026-08-01-pwsh-tool-and-executor.i18n.yaml |    2 +-
 .../2026-08-01-pwsh-tool-and-executor.zh.md   |   22 +-
 ...2026-08-02-pwsh-tool-bash-parity.i18n.yaml |    2 +-
 .../2026-08-02-pwsh-tool-bash-parity.zh.md    |   20 +-
 ...ssion-search-not-shipped-default.i18n.yaml |    2 +-
 ...2-session-search-not-shipped-default.zh.md |   14 +-
 ...6-08-02-web-thinking-tail-scroll.i18n.yaml |    2 +-
 .../2026-08-02-web-thinking-tail-scroll.zh.md |   16 +-
 ...2-win32-in-process-folder-dialog.i18n.yaml |    2 +-
 ...08-02-win32-in-process-folder-dialog.zh.md |   18 +-
 .../2026-08-03-fs-tool-error-remedy.i18n.yaml |    2 +-
 .../2026-08-03-fs-tool-error-remedy.zh.md     |   24 +-
 ...6-08-03-web-search-source-scroll.i18n.yaml |    2 +-
 .../2026-08-03-web-search-source-scroll.zh.md |   24 +-
 ...code-and-codex-subagent-backends.i18n.yaml |    2 +-
 ...ude-code-and-codex-subagent-backends.zh.md |    8 +-
 ...nter-revealed-sidebar-scrollbars.i18n.yaml |    2 +-
 ...-pointer-revealed-sidebar-scrollbars.zh.md |   30 +-
 ...4-web-composer-shared-width-axis.i18n.yaml |    2 +-
 ...08-04-web-composer-shared-width-axis.zh.md |   14 +-
 ...b-context-source-and-steer-marks.i18n.yaml |    2 +-
 ...4-web-context-source-and-steer-marks.zh.md |   14 +-
 ...4-web-latency-throughput-metrics.i18n.yaml |    2 +-
 ...08-04-web-latency-throughput-metrics.zh.md |    8 +-
 ...eb-slash-command-fuzzy-discovery.i18n.yaml |    2 +-
 ...04-web-slash-command-fuzzy-discovery.zh.md |   12 +-
 ...composer-context-meter-breakdown.i18n.yaml |    2 +-
 ...-05-composer-context-meter-breakdown.zh.md |   10 +-
 ...26-08-05-context-form-vocabulary.i18n.yaml |    2 +-
 .../2026-08-05-context-form-vocabulary.zh.md  |   28 +-
 ...feedback-gated-session-telemetry.i18n.yaml |    2 +-
 ...-05-feedback-gated-session-telemetry.zh.md |    2 +-
 .../2026-08-05-pwsh-ui-bash-parity.i18n.yaml  |    2 +-
 .../2026-08-05-pwsh-ui-bash-parity.zh.md      |   10 +-
 ...-08-05-web-preview-product-badge.i18n.yaml |    2 +-
 ...2026-08-05-web-preview-product-badge.zh.md |    4 +-
 ...26-08-06-bundled-dsh-badge-skill.i18n.yaml |    2 +-
 .../2026-08-06-bundled-dsh-badge-skill.zh.md  |    2 +-
 ...06-resolved-theme-color-metadata.i18n.yaml |    2 +-
 ...-08-06-resolved-theme-color-metadata.zh.md |    4 +-
 ...08-06-session-completed-done-dot.i18n.yaml |    2 +-
 ...026-08-06-session-completed-done-dot.zh.md |   12 +-
 .../2026-08-06-web-install-manifest.i18n.yaml |    2 +-
 .../2026-08-06-web-install-manifest.zh.md     |    6 +-
 .../2026-08-06-web-skill-tool-row.i18n.yaml   |    2 +-
 .../2026-08-06-web-skill-tool-row.zh.md       |    8 +-
 ...default-model-follows-the-picker.i18n.yaml |    2 +-
 ...-07-default-model-follows-the-picker.zh.md |   14 +-
 ...6-08-08-dsh-run-headless-command.i18n.yaml |    2 +-
 .../2026-08-08-dsh-run-headless-command.zh.md |    2 +-
 ...8-user-explicit-skill-invocation.i18n.yaml |    2 +-
 ...08-08-user-explicit-skill-invocation.zh.md |   12 +-
 ...26-06-11-vendor-cordis-as-source.i18n.yaml |    2 +-
 .../2026-06-11-vendor-cordis-as-source.zh.md  |    6 +-
 .../2026-06-17-ts-build-config.i18n.yaml      |    2 +-
 .../process/2026-06-17-ts-build-config.zh.md  |   10 +-
 ...-bilingual-docs-and-pairing-gate.i18n.yaml |    4 +-
 ...6-07-02-bilingual-docs-and-pairing-gate.md |    2 +-
 ...7-02-bilingual-docs-and-pairing-gate.zh.md |    2 +-
 ...fig-solution-root-two-aggregates.i18n.yaml |    2 +-
 ...sconfig-solution-root-two-aggregates.zh.md |    6 +-
 ...-incremental-pr-base-retargeting.i18n.yaml |    2 +-
 ...7-26-incremental-pr-base-retargeting.zh.md |    2 +-
 ...30-generated-third-party-notices.i18n.yaml |    2 +-
 ...-07-30-generated-third-party-notices.zh.md |   26 +-
 ...30-independent-ci-consumer-build.i18n.yaml |    2 +-
 ...-07-30-independent-ci-consumer-build.zh.md |    2 +-
 ...-31-coverage-exempt-heavy-suites.i18n.yaml |    2 +-
 ...6-07-31-coverage-exempt-heavy-suites.zh.md |   12 +-
 ...staller-adopts-existing-checkout.i18n.yaml |    2 +-
 ...1-installer-adopts-existing-checkout.zh.md |   22 +-
 ...thub-stacks-and-optional-rebases.i18n.yaml |    2 +-
 ...e-github-stacks-and-optional-rebases.zh.md |    2 +-
 ...-04-forward-only-pr-issue-status.i18n.yaml |    2 +-
 ...6-08-04-forward-only-pr-issue-status.zh.md |    4 +-
 ...-06-coverage-uncovered-locations.i18n.yaml |    2 +-
 ...6-08-06-coverage-uncovered-locations.zh.md |   24 +-
 ...8-06-doc-site-carries-its-images.i18n.yaml |    2 +-
 ...26-08-06-doc-site-carries-its-images.zh.md |   20 +-
 ...6-in-repository-landlock-release.i18n.yaml |    2 +-
 ...08-06-in-repository-landlock-release.zh.md |    4 +-
 ...remotes-generated-contract-build.i18n.yaml |    2 +-
 ...api-remotes-generated-contract-build.zh.md |   26 +-
 ...08-08-browser-gif-evidence-chain.i18n.yaml |    2 +-
 ...026-08-08-browser-gif-evidence-chain.zh.md |   10 +-
 ...-20-remove-stdio-and-echo-agents.i18n.yaml |    2 +-
 ...6-07-20-remove-stdio-and-echo-agents.zh.md |   16 +-
 ...6-merge-subagent-control-service.i18n.yaml |    2 +-
 ...07-26-merge-subagent-control-service.zh.md |   12 +-
 ...subagent-continuation-operations.i18n.yaml |    2 +-
 ...med-subagent-continuation-operations.zh.md |    2 +-
 ...-remove-synthetic-log-only-turns.i18n.yaml |    2 +-
 ...7-28-remove-synthetic-log-only-turns.zh.md |    6 +-
 ...7-29-shared-base-config-overlays.i18n.yaml |    2 +-
 ...26-07-29-shared-base-config-overlays.zh.md |   14 +-
 .../2026-07-30-private-agent-send.i18n.yaml   |    2 +-
 .../2026-07-30-private-agent-send.zh.md       |    6 +-
 ...y-neutral-sandbox-policy-context.i18n.yaml |    2 +-
 ...ility-neutral-sandbox-policy-context.zh.md |    4 +-
 ...7-31-drop-user-message-edit-stub.i18n.yaml |    2 +-
 ...26-07-31-drop-user-message-edit-stub.zh.md |    6 +-
 ...-31-one-route-to-add-a-workspace.i18n.yaml |    2 +-
 ...6-07-31-one-route-to-add-a-workspace.zh.md |   36 +-
 ...t-invariants-from-shipped-config.i18n.yaml |    2 +-
 ...-omit-invariants-from-shipped-config.zh.md |    2 +-
 ...ndows-powershell-picker-fallback.i18n.yaml |    2 +-
 ...p-windows-powershell-picker-fallback.zh.md |   30 +-
 .../2026-08-04-remove-tui-package.i18n.yaml   |    2 +-
 .../2026-08-04-remove-tui-package.zh.md       |    8 +-
 ...r-bubbles-drop-the-branch-action.i18n.yaml |    2 +-
 ...-user-bubbles-drop-the-branch-action.zh.md |    6 +-
 .../2026-08-08-remove-cli-demo.i18n.yaml      |    2 +-
 .../2026-08-08-remove-cli-demo.zh.md          |    6 +-
 ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml |    2 +-
 .../2026-07-24-web-gui-browser-e2e-lane.zh.md |   40 +-
 ...itest-jsdom-webstorage-ownership.i18n.yaml |    2 +-
 ...30-vitest-jsdom-webstorage-ownership.zh.md |    4 +-
 ...-30-web-browser-snapshot-ci-gate.i18n.yaml |    2 +-
 ...6-07-30-web-browser-snapshot-ci-gate.zh.md |   12 +-
 ...n-reasoning-chunk-browser-stress.i18n.yaml |    2 +-
 ...pt-in-reasoning-chunk-browser-stress.zh.md |   12 +-
 ...7-29-durable-last-activity-index.i18n.yaml |    2 +-
 ...26-07-29-durable-last-activity-index.zh.md |   32 +-
 ...8-semantic-composer-chain-phases.i18n.yaml |    2 +-
 ...08-08-semantic-composer-chain-phases.zh.md |    8 +-
 ...07-17-sdk-follow-up-capabilities.i18n.yaml |    2 +-
 ...026-07-17-sdk-follow-up-capabilities.zh.md |   48 +-
 .../2026-08-01-windows-pwsh-default.i18n.yaml |    2 +-
 .../2026-08-01-windows-pwsh-default.zh.md     |   18 +-
 ...t-first-npm-baseline-publication.i18n.yaml |    2 +-
 ...ifact-first-npm-baseline-publication.zh.md |   26 +-
 ...ency-swaps-rejected-by-nih-audit.i18n.yaml |    2 +-
 ...pendency-swaps-rejected-by-nih-audit.zh.md |   14 +-
 README.i18n.yaml                              |    2 +-
 README.zh.md                                  |    6 +-
 apps/cli/README.i18n.yaml                     |    2 +-
 apps/cli/README.zh.md                         |    2 +-
 apps/cli/reference/README.i18n.yaml           |    2 +-
 apps/cli/reference/README.zh.md               |   12 +-
 docs/agent-lifecycle.i18n.yaml                |    6 +
 docs/agent-lifecycle.zh.md                    |   84 +
 docs/api-gateway.i18n.yaml                    |    2 +-
 docs/api-gateway.zh.md                        |   50 +-
 docs/architecture.i18n.yaml                   |    2 +-
 docs/architecture.zh.md                       |   38 +-
 docs/capability-seams.i18n.yaml               |    6 +
 docs/capability-seams.zh.md                   |  425 +++
 docs/config-catalog.i18n.yaml                 |    6 +
 docs/config-catalog.zh.md                     | 2684 +++++++++++++++++
 docs/cookbook/adding-a-package.i18n.yaml      |    2 +-
 docs/cookbook/adding-a-package.zh.md          |   20 +-
 docs/cookbook/adding-a-tool.i18n.yaml         |    2 +-
 docs/cookbook/adding-a-tool.zh.md             |   18 +-
 docs/cookbook/extension-cookbook.i18n.yaml    |    2 +-
 docs/cookbook/extension-cookbook.zh.md        |   28 +-
 ...sponding-to-pr-review-on-a-stack.i18n.yaml |    2 +-
 .../responding-to-pr-review-on-a-stack.zh.md  |    4 +-
 docs/cordis-api/context.i18n.yaml             |    6 +
 docs/cordis-api/context.zh.md                 |  366 +++
 docs/cordis-api/events.i18n.yaml              |    6 +
 docs/cordis-api/events.zh.md                  |  209 ++
 docs/cordis-api/fiber.i18n.yaml               |    6 +
 docs/cordis-api/fiber.zh.md                   |  377 +++
 docs/cordis-api/registry.i18n.yaml            |    6 +
 docs/cordis-api/registry.zh.md                |  154 +
 docs/cordis-api/service.i18n.yaml             |    6 +
 docs/cordis-api/service.zh.md                 |  104 +
 .../cordis-tutorial/01-first-plugin.i18n.yaml |    2 +-
 docs/cordis-tutorial/01-first-plugin.zh.md    |    4 +-
 docs/development.i18n.yaml                    |    2 +-
 docs/development.zh.md                        |   28 +-
 docs/event-producer-consumer.i18n.yaml        |    6 +
 docs/event-producer-consumer.zh.md            |   83 +
 docs/graph-atlas.i18n.yaml                    |    6 +
 docs/graph-atlas.zh.md                        |   26 +
 docs/i18n/README.i18n.yaml                    |    4 +-
 docs/i18n/README.md                           |    4 +-
 docs/i18n/README.zh.md                        |   14 +-
 docs/i18n/terminology.md                      |    4 +-
 docs/i18n/translation-rules.i18n.yaml         |    2 +-
 docs/module-graph.i18n.yaml                   |    6 +
 docs/module-graph.zh.md                       | 1370 +++++++++
 docs/persistence-catalog.i18n.yaml            |    6 +
 docs/persistence-catalog.zh.md                |  775 +++++
 ...0003-web-agent-gui-feedback-loop.i18n.yaml |    2 +-
 .../0003-web-agent-gui-feedback-loop.zh.md    |   12 +-
 ...ice-misclassified-child-failures.i18n.yaml |    2 +-
 ...-notice-misclassified-child-failures.zh.md |    6 +-
 docs/subsystems/core.i18n.yaml                |    2 +-
 docs/subsystems/core.zh.md                    |   12 +-
 docs/subsystems/credentials.i18n.yaml         |    2 +-
 docs/subsystems/credentials.zh.md             |   10 +-
 docs/subsystems/lsp.i18n.yaml                 |    2 +-
 docs/subsystems/persistence.i18n.yaml         |    2 +-
 docs/subsystems/persistence.zh.md             |    4 +-
 docs/subsystems/scope.i18n.yaml               |    2 +-
 docs/subsystems/settings.i18n.yaml            |    2 +-
 docs/subsystems/settings.zh.md                |   14 +-
 docs/subsystems/subagent.i18n.yaml            |    2 +-
 docs/subsystems/subagent.zh.md                |   26 +-
 docs/subsystems/tools.i18n.yaml               |    2 +-
 docs/subsystems/tools.zh.md                   |    6 +-
 docs/subsystems/typert.i18n.yaml              |    2 +-
 docs/subsystems/typert.zh.md                  |   12 +-
 docs/subsystems/user-interaction.i18n.yaml    |    2 +-
 docs/subsystems/user-interaction.zh.md        |    4 +-
 docs/testing.i18n.yaml                        |    2 +-
 docs/testing.zh.md                            |   12 +-
 docs/tool-catalog.i18n.yaml                   |    6 +
 docs/tool-catalog.zh.md                       | 1553 ++++++++++
 docs/tool-execution-pipeline.i18n.yaml        |    6 +
 docs/tool-execution-pipeline.zh.md            |   64 +
 docs/user/develop/basic/publish.i18n.yaml     |    2 +-
 docs/user/develop/basic/publish.zh.md         |   14 +-
 docs/user/guide/config.i18n.yaml              |    2 +-
 docs/user/guide/config.zh.md                  |    4 +-
 docs/user/guide/index.i18n.yaml               |    2 +-
 docs/user/guide/index.zh.md                   |   26 +-
 docs/user/guide/providers.i18n.yaml           |    2 +-
 docs/user/guide/providers.zh.md               |    8 +-
 docs/user/guide/quickstart.i18n.yaml          |    2 +-
 docs/user/guide/quickstart.zh.md              |   14 +-
 docs/web-styling.i18n.yaml                    |    2 +-
 docs/web-styling.zh.md                        |    6 +-
 examples/web-cordis/README.i18n.yaml          |    2 +-
 examples/web-cordis/README.zh.md              |    2 +-
 packages/README.i18n.yaml                     |    2 +-
 packages/README.zh.md                         |   78 +-
 packages/api/README.i18n.yaml                 |    2 +-
 packages/api/README.zh.md                     |    4 +-
 packages/api/gateway/README.i18n.yaml         |    2 +-
 packages/api/gateway/README.zh.md             |    4 +-
 packages/api/remotes/README.i18n.yaml         |    2 +-
 packages/api/remotes/README.zh.md             |    2 +-
 packages/bash/bash-env/README.i18n.yaml       |    2 +-
 packages/bash/bash-env/README.zh.md           |   24 +-
 packages/bash/pwsh-local/README.i18n.yaml     |    2 +-
 packages/bash/pwsh-local/README.zh.md         |    4 +-
 packages/bash/tool-bash/README.i18n.yaml      |    2 +-
 packages/bash/tool-bash/README.zh.md          |   10 +-
 packages/bash/tool-pwsh/README.i18n.yaml      |    2 +-
 packages/bash/tool-pwsh/README.zh.md          |   46 +-
 packages/boot/app-boot/README.i18n.yaml       |    2 +-
 packages/boot/app-boot/README.zh.md           |   30 +-
 packages/bundle/README.i18n.yaml              |    2 +-
 packages/bundle/README.zh.md                  |    2 +-
 packages/bundle/headless/README.i18n.yaml     |    2 +-
 packages/bundle/headless/README.zh.md         |    2 +-
 packages/bundle/web-app/README.i18n.yaml      |    2 +-
 packages/bundle/web-app/README.zh.md          |    4 +-
 packages/client/README.i18n.yaml              |    2 +-
 packages/client/README.zh.md                  |   10 +-
 packages/client/connection/README.i18n.yaml   |    2 +-
 packages/client/connection/README.zh.md       |    4 +-
 packages/client/test-runtime/README.i18n.yaml |    2 +-
 packages/client/test-runtime/README.zh.md     |   10 +-
 .../client/ui-conversation/README.i18n.yaml   |    2 +-
 packages/client/ui-conversation/README.zh.md  |   12 +-
 .../client/ui-deliverables/README.i18n.yaml   |    2 +-
 packages/client/ui-deliverables/README.zh.md  |   10 +-
 .../ui-settings-general/README.i18n.yaml      |    2 +-
 .../client/ui-settings-general/README.zh.md   |    4 +-
 packages/client/ui-tool/README.i18n.yaml      |    2 +-
 packages/client/ui-tool/README.zh.md          |   32 +-
 packages/client/ui-workspace/README.i18n.yaml |    2 +-
 packages/client/ui-workspace/README.zh.md     |   12 +-
 .../credentials/credentials/README.i18n.yaml  |    2 +-
 packages/credentials/credentials/README.zh.md |   20 +-
 packages/feedback/README.i18n.yaml            |    2 +-
 packages/feedback/README.zh.md                |    4 +-
 .../command-feedback/README.i18n.yaml         |    2 +-
 .../feedback/command-feedback/README.zh.md    |   14 +-
 .../tool-str-replace-editor/README.i18n.yaml  |    2 +-
 .../fs/tool-str-replace-editor/README.zh.md   |   10 +-
 .../directory-picker-native/README.i18n.yaml  |    2 +-
 .../host/directory-picker-native/README.zh.md |    6 +-
 .../host/frontend-static/README.i18n.yaml     |    2 +-
 packages/host/frontend-static/README.zh.md    |    2 +-
 packages/host/webserver/README.i18n.yaml      |    2 +-
 packages/host/webserver/README.zh.md          |    8 +-
 .../pty/tool-bash-persistent/README.i18n.yaml |    2 +-
 .../pty/tool-bash-persistent/README.zh.md     |   14 +-
 .../README.i18n.yaml                          |    2 +-
 .../README.i18n.yaml                          |    2 +-
 .../README.i18n.yaml                          |    2 +-
 .../session-persistence/README.i18n.yaml      |    2 +-
 .../session-projection-cache/README.i18n.yaml |    2 +-
 .../session-projection/README.i18n.yaml       |    2 +-
 .../session-telemetry-otel/README.i18n.yaml   |    2 +-
 .../session-telemetry/README.i18n.yaml        |    2 +-
 .../README.i18n.yaml                          |    2 +-
 .../README.i18n.yaml                          |    2 +-
 .../session-title-llm/README.i18n.yaml        |    2 +-
 packages/settings/README.i18n.yaml            |    2 +-
 packages/settings/README.zh.md                |    2 +-
 .../settings/settings-local/README.i18n.yaml  |    2 +-
 packages/settings/settings-local/README.zh.md |   20 +-
 packages/settings/settings/README.i18n.yaml   |    2 +-
 packages/settings/settings/README.zh.md       |   16 +-
 packages/skill/skill-badge/README.i18n.yaml   |    2 +-
 packages/skill/skill-badge/README.zh.md       |    2 +-
 .../subagent-claude-code/README.i18n.yaml     |    2 +-
 .../subagent-claude-code/README.zh.md         |   10 +-
 .../subagent/subagent-codex/README.i18n.yaml  |    2 +-
 packages/subagent/subagent-codex/README.zh.md |   14 +-
 .../support/acp-snapshot/README.i18n.yaml     |    2 +-
 packages/support/acp-snapshot/README.zh.md    |   12 +-
 packages/typert/type-meta/README.i18n.yaml    |    2 +-
 packages/typert/type-meta/README.zh.md        |   16 +-
 packages/util/atomic-write/README.i18n.yaml   |    2 +-
 packages/util/atomic-write/README.zh.md       |    8 +-
 packages/util/environment/README.i18n.yaml    |    2 +-
 packages/util/environment/README.zh.md        |    8 +-
 python/development.i18n.yaml                  |    2 +-
 python/development.zh.md                      |   12 +-
 scripts/project-doc-site.spec.ts              |   42 +-
 scripts/translation-pairing.manifest.json     |   13 +-
 scripts/translation-pairing.spec.ts           |   11 +
 scripts/translation-pairing.ts                |   21 +
 scripts/verify-translation-pairing.ts         |    3 +-
 website/docs.ts                               |   53 +-
 565 files changed, 10606 insertions(+), 2171 deletions(-)
 create mode 100644 docs/agent-lifecycle.i18n.yaml
 create mode 100644 docs/agent-lifecycle.zh.md
 create mode 100644 docs/capability-seams.i18n.yaml
 create mode 100644 docs/capability-seams.zh.md
 create mode 100644 docs/config-catalog.i18n.yaml
 create mode 100644 docs/config-catalog.zh.md
 create mode 100644 docs/cordis-api/context.i18n.yaml
 create mode 100644 docs/cordis-api/context.zh.md
 create mode 100644 docs/cordis-api/events.i18n.yaml
 create mode 100644 docs/cordis-api/events.zh.md
 create mode 100644 docs/cordis-api/fiber.i18n.yaml
 create mode 100644 docs/cordis-api/fiber.zh.md
 create mode 100644 docs/cordis-api/registry.i18n.yaml
 create mode 100644 docs/cordis-api/registry.zh.md
 create mode 100644 docs/cordis-api/service.i18n.yaml
 create mode 100644 docs/cordis-api/service.zh.md
 create mode 100644 docs/event-producer-consumer.i18n.yaml
 create mode 100644 docs/event-producer-consumer.zh.md
 create mode 100644 docs/graph-atlas.i18n.yaml
 create mode 100644 docs/graph-atlas.zh.md
 create mode 100644 docs/module-graph.i18n.yaml
 create mode 100644 docs/module-graph.zh.md
 create mode 100644 docs/persistence-catalog.i18n.yaml
 create mode 100644 docs/persistence-catalog.zh.md
 create mode 100644 docs/tool-catalog.i18n.yaml
 create mode 100644 docs/tool-catalog.zh.md
 create mode 100644 docs/tool-execution-pipeline.i18n.yaml
 create mode 100644 docs/tool-execution-pipeline.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml
index 0697332171..b18ca244be 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.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
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md
 2026-06-11-runtime-arg-validation.md: e0bca0ff24c5adc7ca58007932dff6580694b01d
-2026-06-11-runtime-arg-validation.zh.md: 09958147766b4015d6bebf786c4947b9d2941f74
+2026-06-11-runtime-arg-validation.zh.md: c98bde0ed2dd568a394aae74fb9f5549c3f61105
diff --git a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
index 0995814776..c98bde0ed2 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-`defineTool`（[统一 schema DSL](2026-07-20-unified-json-value-schema-dsl.md)）为工具作者的 `execute(args)` 提供了经 `InferArgs<S>` 映射的类型化参数。但该类型只是对运行时值的编译期声明，而这个值实际上是模型生成的 JSON：没有任何机制强制模型遵守 schema，因此畸形调用（缺少必需键、声明为数字的位置传入字符串，或字面量超出声明的集合）会以「仅名义类型化」的状态到达 `execute`。工具函数体随后要么在错误形状上崩溃，要么静默地行为异常。
+`defineTool`（[统一 schema DSL](2026-07-20-unified-json-value-schema-dsl.md)）为工具作者的 `execute(args)` 提供了经 `InferArgs<S>` 映射的类型化参数。但该类型只是对运行时值的编译期声明，而这个值实际上是模型生成的 JSON：没有任何机制强制模型遵守 schema，因此畸形调用（缺少必需键、声明为数字的位置传入字符串，或字面量超出声明的集合）会以「仅在名义上类型化」的状态到达 `execute`。工具函数体随后要么在错误形状上崩溃，要么静默地行为异常。
 
 ## 决策
 
 `validateArgs(spec, args): string[]` 编译 `ParameterSchemaSpec`，并委托共享的 `validateJsonSchemaValue()` 遍历器，对格式正确的声明返回可读的违规列表。`defineTool` 在定义时对编译后的参数 schema 创建快照，并在调用类型化函数体之前执行校验；存在违规时会抛出 `ToolArgsError`（`INVALID_ARGS`），注册表将其作为模型可据以修正的错误结果返回。
 
-校验器与编译器因此共享完全一致的语义：隐式参数根是开放对象；必需键仅来自 `required: true`；默认值仍是注解；显式嵌套对象遵循其声明的开放性；数组通过 `items` 递归；标量字面量约束保证类型正确；`oneOf` 仅在恰好一个分支匹配时才接受。原始注册的工具自行负责输入校验。
+校验器与编译器因此共享完全一致的语义：隐式参数根是开放对象；必需键仅来自 `required: true`；默认值仍是注解；显式嵌套对象遵循其声明的开放性；数组通过 `items` 递归；标量字面量约束保证类型正确；`oneOf` 仅在恰好一个分支匹配时才接受。直接注册的工具自行负责输入校验。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
index 215f612f5e..efed9ca5ea 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
 2026-07-08-agent-scope-contexts.md: eb3f6f247bac1a1d81aa2644132c7b9cc04d602c
-2026-07-08-agent-scope-contexts.zh.md: 673dd8578bf545b1f14f3b7e7b89874d804e4ae9
+2026-07-08-agent-scope-contexts.zh.md: fe82ac18d07de97330e86461e6bdf86edc37d2ae
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
index 673dd8578b..fe82ac18d0 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
@@ -18,14 +18,14 @@ Status: implemented
 
 Cordis 是 SDK 底层的插件框架。Cordis **上下文**是插件用来访问服务和注册效果的对象，效果的清理跟随该上下文。[Cordis 入门](../../../../docs/cordis-primer.md)对该框架有更详细的说明。
 
-对大多数贡献者而言，完整契约是四条规则：
+对大多数贡献者而言，完整约定是四条规则：
 
 | 问题 | 规则 |
 |---|---|
 | 在哪里为某个 agent 注册行为？ | 通过 `agent.ctx` 调用普通注册 API |
 | 某个 agent 的操作能看到什么？ | 部署全局加上该 agent 的层，按所属服务的合并规则 |
 | 哪些作用域监听器会运行？ | 无作用域监听器加上为该操作所属 agent 注册的监听器 |
-| 该层存在多久？ | setup 在发布前完成；dispose 保留该层直到工作完全停稳 |
+| 该层存在多久？ | setup 在发布前完成；dispose（资源释放）保留该层直到工作完全停稳 |
 
 作用域是扁平的。解析永远不会遍历父级或兄弟作用域，生命周期所有权也不意味着注册继承。
 
@@ -49,14 +49,14 @@ flowchart LR
 
 ### 注册来源决定可见性与清理
 
-通过普通插件上下文进行的注册是部署全局的，随该插件一起 dispose（资源释放）。同一方法通过 `agent.ctx` 调用则贡献给一个 agent，随该 agent 的作用域一起 dispose。
+通过普通插件上下文进行的注册是部署全局的，随该插件一起 dispose。同一方法通过 `agent.ctx` 调用则贡献给一个 agent，随该 agent 的作用域一起 dispose。
 
 | 注册来源 | 默认可见性 | 随谁 dispose |
 |---|---|---|
 | 普通插件上下文 | 每个符合条件的 agent 视图 | 注册插件 |
 | `agent.ctx` | 仅该 agent 的视图 | agent 作用域 |
 
-工具、提示词段落与变量、工具限制、守卫以及作用域事件监听器都遵循此契约。命名的本地值通常对该 agent 遮蔽同名全局值；各所属服务文档会说明例外与合并行为。
+工具、提示词段落与变量、工具限制、守卫以及作用域事件监听器都遵循此约定。命名的本地值通常对该 agent 遮蔽同名全局值；各所属服务文档会说明例外与合并行为。
 
 普通贡献者的模式是在 agent setup 期间注册完整的本地世界：
 
@@ -88,7 +88,7 @@ await handle.dispose()
 ctx.tools.get('review_summary', handle.agent)  // undefined: scope is gone
 ```
 
-setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插件和服务。其契约仅限组合：不支持通过 cast 或内部注册表调用来驱动或发布正在构建中的 agent。
+setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插件和服务。其约定仅限组合：不支持通过 cast 或内部注册表调用来驱动或发布正在构建中的 agent。
 
 ### 操作选择视图
 
@@ -96,7 +96,7 @@ setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插
 
 工具查找与执行接收其所服务的 agent。提示词组装接收正在构建请求的 agent 的组装上下文。事件分发接收其领域主体。这使共享服务实例可在多个 agent 间复用，同时让每个操作的视图保持显式。
 
-只有采纳了作用域契约的服务才会解析 agent 层。`agent.ctx` 不会自动改变任意 Cordis 服务调用的行为。
+只有采纳了作用域约定的服务才会解析 agent 层。`agent.ctx` 不会自动改变任意 Cordis 服务调用的行为。
 
 ### 作用域事件将路由与事件数据分离
 
@@ -108,13 +108,13 @@ setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插
 
 ### 创建最后发布，dispose 最后撤销
 
-`ctx.agents.create()` 和 `resume()` 构建未发布的会话、作用域、agent 和驱动器。它们等待 `setup`，同步调用其可选的 `AgentSetupCommit`，准入最终的会话和 agent 条目，按序公告，启动循环，然后才返回 handle。该提交操作让可变的配置状态在所有 setup 的 await 均结算后，于确切的发布边界重新校验；若其抛出异常，则会在公告任何一个身份前回滚私有事务，而成功提交后的撤销属于普通的实时拆卸。
+`ctx.agents.create()` 和 `resume()` 构建未发布的会话、作用域、agent 和驱动器。它们等待 `setup`，同步调用其可选的 `AgentSetupCommit`，准入最终的会话和 agent 条目，按序公告，启动循环，然后才返回 handle。该提交操作让可变的配置状态在所有 setup 的 await 均结算后，于确切的发布边界重新校验；若其抛出异常，则会在公告任何一个身份前回滚私有事务，而成功提交后的撤销属于普通的存活期拆除。
 
 可选的创建信号仅在创建或恢复挂起期间取消工作。promise resolve 后，返回的 `AgentHandle` 拥有显式 dispose 权。
 
 如果加载、setup、可选的 setup 提交、准入或发布失败，私有事务回滚其准备的一切。使用同一个调用方提供的存活 ID 的并发操作可能都到达 setup，但最终注册表条目只准入一个；每个失败者拒绝并清理其私有资源。在等待 dispose 完成后的顺序复用仍然有效。
 
-`AgentHandle.dispose()` 反转边界。它停用创建或驱动，等待同步发布解除，停止并排空驱动器和最终会话刷写，分离 agent 和会话，最后 dispose 作用域。重复或竞争的 dispose 请求合并为一个完成 promise。
+`AgentHandle.dispose()` 反转边界。它停用创建或驱动，等待同步发布完成退栈，停止并排空驱动器和最终会话刷写，分离 agent 和会话，最后 dispose 作用域。重复或竞争的 dispose 请求合并为一个完成 promise。
 
 调用方的 Cordis 上下文和具体的 AgentLoop 工厂是结构性共同所有者。卸载任一方都会 dispose 事务或存活 agent。
 
@@ -152,7 +152,7 @@ agent 作用域组合的是受信的同进程注册。它不沙箱化插件、
 
 ### 向每个注册传递 agent 选项
 
-类似 `tools.register(definition, { agent })` 的 API 在每个注册表中重复作用域管道，且允许可见性所有权与清理所有权漂移。通过 `agent.ctx` 注册使两个事实跟随同一个 Cordis effect owner。
+类似 `tools.register(definition, { agent })` 的 API 在每个注册表中重复作用域传递逻辑，且允许可见性所有权与清理所有权漂移。通过 `agent.ctx` 注册使两个事实跟随同一个 Cordis effect owner。
 
 ### 过滤事件但保持注册表全局
 
@@ -160,7 +160,7 @@ agent 作用域组合的是受信的同进程注册。它不沙箱化插件、
 
 ### 为每个 agent 创建独立的服务图
 
-所需的视图是共享部署服务加上一个本地注册层。每 agent 一个图会重复适配器，并使共享持久化、提供方注册表和应用启动复杂化。
+所需的视图是共享部署服务加上一个本地注册层。每个 agent 一个服务图会重复适配器，并使共享持久化、提供方注册表和应用启动复杂化。
 
 ### 继承父级注册作用域
 
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index dbdc4347f6..527ac2d6b3 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
 2026-07-12-agent-scope-runtime-design.md: b93c291957fab98ab9d0d04eb816bb01a15a0b51
-2026-07-12-agent-scope-runtime-design.zh.md: 8b1332c23ce3b6c0332fcde40b4f4ac8dd20aa45
+2026-07-12-agent-scope-runtime-design.zh.md: 2dbdcab2ce3a7f92bf537d93a65dfe44374ec07c
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
index 8b1332c23c..2dbdcab2ce 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Agent 作用域运行时设计与正确性
+# Agent Note: agent 作用域运行时设计与正确性
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-[agent 作用域契约](2026-07-08-agent-scope-contexts.md)对贡献者而言很简单：通过 `agent.ctx` 注册，解析出一个全局加单 agent 的视图，仅在 setup 完成后发布，并保持作用域直到工作停止。运行时必须在协作式插件框架、异步创建、可重入监听器、持久化会话提交以及 worker 或进程故障等场景下维护这份契约。
+[agent（智能体）作用域约定](2026-07-08-agent-scope-contexts.md)对贡献者而言很简单：通过 `agent.ctx` 注册，解析出一个全局加单 agent 的视图，仅在 setup 完成后发布，并保持作用域直到工作停止。运行时必须在协作式插件框架、异步创建、可重入监听器、持久化会话提交以及 worker 或进程故障等场景下维护这份约定。
 
 主要的设计风险是为每个竞态条件引入第二套机制。独立的预留、就绪哨兵、取消中继、快照层和保护注册表可能镜像同一个事实，直到没有读者能分辨哪个才是权威的。这些机制还会诱使运行时把可信的类型化调用当作敌对的序列化边界来处理。
 
@@ -23,18 +23,18 @@ Status: implemented
 | 选择全局加某个 agent 的注册 | 不透明作用域键、路由载体与共享 layer store |
 | 拥有一个活跃的 agent 或会话 | 由其 disposer 捕获的单条注册表条目 |
 | 协调创建/恢复 | 单个 `AgentCreationTransaction` |
-| 保护持久化、队列、模型或协议格式数据 | 在该边界处一次性物化 |
-| 在同一进程内传递类型化值 | Readonly 借用契约 |
-| 组合模型可见的提示词与工具表面 | 单个共享工具视图加权威的 assembly-waterfall 结果 |
+| 保护持久化、队列、模型或协议格式（wire format）数据 | 在该边界处一次性物化 |
+| 在同一进程内传递类型化值 | Readonly 借用约定 |
+| 组合模型可见的提示词与工具表面 | 单个共享工具视图加 assembly waterfall（瀑布式事件）的权威结果 |
 | 协调 subagent、worker 和进程关闭 | 单个取消信号加该边界独立的终止态/完全停稳态事实 |
 
 本 Agent Note 余下部分按依赖顺序展开这些选择：Cordis 机制、作用域路由、创建与会话提交、工具与提示词、subagent 与工作流，最后是可执行检查。
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md)仍然是贡献者契约。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md)仍然是贡献者约定。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
 
 ## Cordis 模型：上下文、fiber、effect、receiver 与 waterfall
 
-理解实现需要五个 Cordis 概念。上下文选择服务和注册所有权；fiber 是一个活跃的插件或子生命周期；effect 将清理逻辑附加到 fiber；事件接收器选择监听器；waterfall（瀑布式事件）让监听器按顺序变换或否决一个操作。
+理解实现需要五个 Cordis 概念。上下文选择服务和注册所有权；fiber 是一个活跃的插件或子生命周期；effect 将清理逻辑附加到 fiber；事件接收器选择监听器；waterfall 让监听器按顺序变换或否决一个操作。
 
 ### 上下文是贯穿单个服务图的所有权路径
 
@@ -56,7 +56,7 @@ Cordis 使用 dispatch receiver（`this`）过滤监听器，而 harness 的监
 
 因此，产品辅助函数构造载体并单独传递领域主体。这防止监听器路由变成另一套对象模型，并使事件签名在不了解载体内部的情况下也可理解。
 
-Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()`：调用它则委托给剩余监听器和基础操作，不调用则否决或替换下游结果。Waterfall 驱动提示词组装和工具策略；普通 emit 事件同步通知，parallel 事件等待所有监听器但没有否决结果。
+Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()`：调用它则委托给剩余监听器和基础操作，不调用则否决或替换下游结果。waterfall 驱动提示词组装和工具策略；普通 emit 事件同步通知，parallel 事件等待所有监听器但没有否决结果。
 
 ## 作用域路由：一个不透明键选择一层
 
@@ -82,7 +82,7 @@ Receiver 是一个小型载体而非领域对象的透明代理。需要 agent 
 
 类型标记拒绝普通的裸 receiver 误用，开发环境不变式覆盖直接 JavaScript 或强制转换的 dispatch。主体保持显式，因为路由正确性和有用的事件数据是不同的关注点。
 
-## Agent 创建：一个事务拥有完整操作
+## agent 创建：一个事务拥有完整操作
 
 创建和恢复是一个具有多个阶段的异步生命周期，而非多个生命周期。`AgentCreationTransaction` 拥有调用方和工厂的活跃性、可选取消、私有资源、发布、回滚，以及每个所有者观察到的记忆化拆除。
 
@@ -104,7 +104,7 @@ detach 闭包捕获其确切注册表条目。它仅在映射仍指向该注册
 
 ### Setup 是私有世界内的可信组合
 
-Setup 接收完整的子上下文，可以等待插件激活。它可以注册工具、提示词段、限制、监听器和其他 effect，但公开契约不支持通过强制转换或内部注册表调用来驱动或发布正在创建中的 agent。
+Setup 接收完整的子上下文，可以等待插件激活。它可以注册工具、提示词段、限制、监听器和其他 effect，但公开约定不支持通过强制转换或内部注册表调用来驱动或发布正在创建中的 agent。
 
 事务将异步加载和 setup 与停用进行竞争，而非无限等待外部代码拥有的 promise。如果取消或所有者卸载获胜，即使外部 promise 永不结算，公开创建也会在事务拥有的清理之后拒绝。
 
@@ -120,7 +120,7 @@ Setup 接收完整的子上下文，可以等待插件激活。它可以注册
 6. 发射 `agent/session-start`。
 7. 启动 driver。
 
-Agent 在两个注册表和创建通知都达成一致之前绝不驱动。同步监听器可以否决或 dispose 一个所有者；事务记录发布进行中，并等待该回调栈展开后再继续拆除。每个已开始的创建宣告在回滚期间都有匹配的销毁宣告。
+agent 在两个注册表和创建通知都达成一致之前绝不驱动。同步监听器可以否决或 dispose 一个所有者；事务记录发布进行中，并等待该回调栈展开后再继续拆除。每个已开始的创建宣告在回滚期间都有匹配的销毁宣告。
 
 以下序列图隔离了非显而易见的竞态：同步创建监听器可以在发布调用栈仍拥有两个注册表条目时请求 dispose。拆除必须立即停用，但要等待该栈展开后才停止和分离任何东西。
 
@@ -172,7 +172,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 追加遵循一个序列：
 
-1. 物化持久化事件和表面意图。
+1. 物化持久化事件和呈现意图。
 2. 取得 SessionEntry 的独占所有权，并拒绝该注册表条目上的重入追加。
 3. 解析作用域回调并运行内部不变式验证。
 4. 恰好推送一次；这是提交点。
@@ -185,7 +185,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 ## 信任边界：仅在所有权真正变更时复制
 
-运行时区分类型化的进程内契约与序列化及持久化边界。这是值和回调的主要简化规则。
+运行时区分类型化的进程内约定与序列化及持久化边界。这是值和回调的主要简化规则。
 
 | 边界 | 所有权规则 |
 |---|---|
@@ -196,9 +196,9 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 | 持久化会话或持久化数据 | 在提交前物化并验证 |
 | Worker、进程或协议格式消息 | 序列化、验证并拥有解码后的值 |
 
-测试中构造恶意 getter、在交接后替换类型化回调、或强制转换伪造服务对象的做法本身不定义生产契约。运行时在数据跨越解析器、队列、模型、持久化、文件、worker、进程或协议格式（wire format）边界时保留检查，并在可信进程内依赖 readonly 类型加插件纪律。
+测试中构造恶意 getter、在交接后替换类型化回调、或强制转换伪造服务对象的做法本身不定义生产约定。运行时在数据跨越解析器、队列、模型、持久化、文件、worker、进程或协议格式边界时保留检查，并在可信进程内依赖 readonly 类型加插件纪律。
 
-回调隔离与数据所有权是分开的。监听器是任意扩展代码，即使其参数是可信的也可能抛出异常；发布和提交后路径仍按其事件契约隔离失败。
+回调隔离与数据所有权是分开的。监听器是任意扩展代码，即使其参数是可信的也可能抛出异常；发布和提交后路径仍按其事件约定隔离失败。
 
 ## 工具与提示词：单一视图、权威组装、已提交的结果
 
@@ -206,7 +206,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 ### 一个解析器定义工具视图
 
-私有解析器应用当前展示模式、活跃的全局限制、精确的局部叠加和局部遮蔽。Schema、查找、执行、Code Mode SDK 生成和限制验证都使用该解析器或其限制前的全局名称视图。
+私有解析器应用当前展示模式、活跃的全局限制、精确的局部叠加和局部遮蔽。schema、查找、执行、Code Mode SDK 生成和限制验证都使用该解析器或其限制前的全局名称视图。
 
 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md#tool-filtering-is-one-live-global-view-rule)拥有用户可见的 allow/deny 语义。实现要求是一致性：被过滤掉的全局工具不能通过另一条查找路径仍可执行，局部遮蔽的定义就是被展示和执行的同一个定义。
 
@@ -216,7 +216,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 注册表为每次执行分配一个新的带品牌的 `Symbol` token。嵌套的 Code Mode 调用将外层 token 作为 `parent` 携带，因此结构化输出可以通过标识将内层捕获与其外层 `run_code` 结果关联。
 
-注册表分配的新 Symbol 提供无碰撞的执行标识，无需 WeakSet 成员注册表。调用方无法通过 `ToolExecutionInput` 提供执行自身的 token；它们仅在注册表创建后接收流水线拥有的 `ToolExecution`。这是一个可信的类型化契约，而非针对任意强制转换或 JavaScript 调用方的运行时防御。
+注册表分配的新 Symbol 提供无碰撞的执行标识，无需 WeakSet 成员注册表。调用方无法通过 `ToolExecutionInput` 提供执行自身的 token；它们仅在注册表创建后接收流水线拥有的 `ToolExecution`。这是一个可信的类型化约定，而非针对任意强制转换或 JavaScript 调用方的运行时防御。
 
 参数在模型/工具 JSON 进入流水线时一次性物化。Pre-、around- 和 post-execute 监听器操作类型化的 execution 和决策。Call ID 关联、审批、单调守卫和 Code Mode 嵌套仍然是显式的关系检查。
 
@@ -238,7 +238,7 @@ Scope 直接解决了真正的隔离问题。结构化输出贡献注册在子
 
 对于 Code Mode SDK 调用，内层成功结果记录 `{ parentToken, value }` 而非提交。观察者等待 token 匹配 `parentToken` 的 `run_code` 执行，仅在该外层最终结果也成功时才提交。程序失败、运行时中止或外层 post-policy 拒绝会丢弃待定值。
 
-一旦值处于待定或已提交状态，作用域单调守卫拒绝后续工具调用。成功的结构化输出执行会调用 `exec.concludeTurn()`，因此其自身不可变结果携带 `concludesTurn: true`，循环在该步骤结束工具循环。Schema 验证失败仍然是普通的 `INVALID_ARGS` 工具错误，子级可以在同一轮次内重试。
+一旦值处于待定或已提交状态，作用域单调守卫拒绝后续工具调用。成功的结构化输出执行会调用 `exec.concludeTurn()`，因此其自身不可变结果携带 `concludesTurn: true`，循环在该步骤结束工具循环。schema 验证失败仍然是普通的 `INVALID_ARGS` 工具错误，子级可以在同一轮次内重试。
 
 纯 Code Mode 的注册表贡献从原生 wire schema 中省略 `structured_output`，并通过生成的 SDK 暴露它。Assembly waterfall 可以有意改变该展示；执行仍然针对子作用域定义进行验证，监听器拥有其创建的任何替代模型可见路由的一致性。
 
@@ -252,21 +252,21 @@ Scope 直接解决了真正的隔离问题。结构化输出贡献注册在子
 | 工具结果 | 观察不可变的已提交结果 | 结构化输出必须仅提交实际逃出流水线的结果 |
 | 轮次 continuation | 通过已提交工具结果终止 | 已提交的终端输出必须结束轮次 |
 
-`ToolGuard` 是单调策略注册表。已提交的工具观察是上述被隔离的 `tools/result` 点。终端结构化输出在自身执行上标记 `concludesTurn`，因此终止性成为权威结果上的数据，而不是独立 hook 决策。
+`ToolGuard` 是单调策略注册表。已提交的工具观察是上述被隔离的 `tools/result` 点。终端结构化输出在自身执行上标记 `concludesTurn`，因此终止性成为权威结果上的数据，而不是独立钩子决策。
 
-### Skill 和 approval 服务信任类型化调用方
+### skill（技能）和 approval 服务信任类型化调用方
 
-Skill 注册表定义和 approval 策略是 readonly 的同进程契约。它们的服务不克隆回调对象，也不防御交接后的回调替换。
+skill 注册表定义和 approval 策略是 readonly 的同进程约定。它们的服务不克隆回调对象，也不防御交接后的回调替换。
 
-Skill 仍然验证外部 skill 文件和解析的提供方输出，通过调用 agent 的工具视图路由目录，并精确 dispose 注册。Approval 仍然解析策略、观察取消、按 `request.agent` 路由 `approval/request`、记录持久化审计对，并隔离应答者和提交后观察者的失败。
+skill 仍然验证外部 skill 文件和解析的提供方输出，通过调用 agent 的工具视图路由目录，并精确 dispose 注册。Approval 仍然解析策略、观察取消、按 `request.agent` 路由 `approval/request`、记录持久化审计对，并隔离应答者和提交后观察者的失败。
 
 ## Subagent：发布即 start promise
 
 Subagent 启动有一次所有权转移。提供方拥有未发布资源，直到其 start promise 以一个已发布 run 兑现；调用方拥有返回的 run 并必须 dispose 它。
 
-### 服务契约有一个取消通道
+### 服务约定有一个取消通道
 
-`SubagentProvider.start()` 和 `SubagentService.start()` 返回 `Promise<SubagentRun>`。Promise 会在后端跨过发布边界后兑现，因此调用方和 `subagent/start` 观察者从不需要第二个 `run.started` promise。提供方工作如果在发布前失败，`start()` 就会被拒绝；发布后的提示词、轮次、取消与基础设施结果会通过 `SubagentRun.result` 结算，且不会隐藏 child id，这也是[持久化目录决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)所要求的契约。
+`SubagentProvider.start()` 和 `SubagentService.start()` 返回 `Promise<SubagentRun>`。Promise 会在后端跨过发布边界后兑现，因此调用方和 `subagent/start` 观察者从不需要第二个 `run.started` promise。提供方工作如果在发布前失败，`start()` 就会被拒绝；发布后的提示词、轮次、取消与基础设施结果会通过 `SubagentRun.result` 结算，且不会隐藏 child id，这也是[持久化目录决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)所要求的约定。
 
 `SubagentStartRequest.signal` 是必需的。中止它会在启动期间，以及已发布 run 的剩余就绪或轮次工作中请求取消。`SubagentRun.dispose()` 也请求取消并等待完全停稳。没有单独的公开 `run.cancel()` 通道。
 
@@ -314,11 +314,11 @@ Worker 边界仍然序列化请求和结果。宿主保留首个终端结果仲
 
 ## 正确性强制
 
-该设计通过类型、运行时逃逸点、生成的契约和行为测试来强制执行。没有哪一层被要求证明它无法观察到的东西。
+该设计通过类型、运行时逃逸点、生成的约定和行为测试来强制执行。没有哪一层被要求证明它无法观察到的东西。
 
 ### 类型使常规路径难以误用
 
-Readonly 契约描述借用的同进程值。`Scoped<T>` 标记事件接收器，`agentEvents()` 融合载体和主体，工具输入省略注册表拥有的 token，subagent 异步返回类型直接暴露发布与结算。
+Readonly 约定描述借用的同进程值。`Scoped<T>` 标记事件接收器，`agentEvents()` 融合载体和主体，工具输入省略注册表拥有的 token，subagent 异步返回类型直接暴露发布与结算。
 
 TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进程消息或持久化文件，因此运行时强制保留在这些逃逸点。
 
@@ -326,9 +326,9 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 `dsh-scope/invariant` 配套插件在被选用时验证每个声明的作用域事件使用带标记的载体，以及暴露主体的事件族使用匹配的键。独立的 `dsh-session/invariant` 贡献在追加提交前暂存 trace 验证，并在同一事件提交后推进；二者都通过 `ctx.invariants` 注册。
 
-该插件不通过扫描注册表来管控可信 setup，也不拒绝通过强制转换构造的提示词 assembly 对象。这些检查会将组合契约变成推测性的运行时机制，却不保护真实的外部边界。
+该插件不通过扫描注册表来管控可信 setup，也不拒绝通过强制转换构造的提示词 assembly 对象。这些检查会将组合约定变成推测性的运行时机制，却不保护真实的外部边界。
 
-### 生成的产物使公开契约保持对齐
+### 生成的产物使公开约定保持对齐
 
 事件目录、服务目录、生产者/消费方矩阵、配置目录、模块图、工具目录、type-equiv 块和作用域事件解析器映射都是从源码生成或受新鲜度门禁约束的。[TypeScript 语义门禁 Agent Note](../process/2026-07-14-typescript-program-backed-semantic-gates.md)拥有 Program 构造、语义事件发现和解析器生成规则。
 
@@ -336,7 +336,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ## 曾考虑的替代方案
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered)拥有公开扁平作用域契约的替代方案。此处的替代方案关注实现形态。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered)拥有公开扁平作用域约定的替代方案。此处的替代方案关注实现形态。
 
 ### 使用透明代理作为作用域载体
 
@@ -348,7 +348,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ### 对每个类型化的同进程参数做快照
 
-通用复制防御有状态 getter 和违反 readonly 契约的调用方，但增加分配、重复验证器和可能遗忘复制的路径。物化属于解析器、队列、模型、持久化、worker、进程和协议格式边界——即所有权真正变更的地方。
+通用复制防御有状态 getter 和违反 readonly 约定的调用方，但增加分配、重复验证器和可能遗忘复制的路径。物化属于解析器、队列、模型、持久化、worker、进程和协议格式边界——即所有权真正变更的地方。
 
 ### 为就绪、取消和 dispose 提供独立控制器
 
@@ -375,10 +375,10 @@ Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化
 - 作用域贡献仅在其精确的 agent 视图中可见，并随该作用域一起 dispose。
 - 创建和恢复不暴露部分配置的句柄；最终写入注册表时的失败者和发布失败清理每个已准备的资源。
 - Dispose 在 driver 排空和最终会话工作期间保留作用域监听器和持久化，然后撤销作用域。
-- 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 契约。
+- 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 约定。
 - ToolRegistry 的展示、查找和执行在专家 assembly 变换之前解析相同的活跃视图，已提交的结果有一个不可变的观察点。
 - 注册表贡献是确定性输入，而可信的 assembly waterfall 拥有最终的模型可见组合。
-- Subagent start 仅返回已发布的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的完全停稳契约。
+- Subagent start 仅返回已发布的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的完全停稳约定。
 - Worker/进程结果优先级和清理在死亡、迟到消息和有界拆除下保持正确。
 
 ### 代价与局限
@@ -387,6 +387,6 @@ Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化
 
 可信的 `system-prompt/assemble` 监听器可以移除或替换 Code Mode 和结构化输出协议片段。这是有意为之：监听器拥有最终组合，必须保持部署期望仍可用的任何协议。
 
-该设计信任同进程中的类型化插件。它不防御任意强制转换、有状态 getter、违反 readonly 契约的修改，或插件有意在支持的组合 API 之外使用环境服务访问。
+该设计信任同进程中的类型化插件。它不防御任意强制转换、有状态 getter、违反 readonly 约定的修改，或插件有意在支持的组合 API 之外使用环境服务访问。
 
 [安全与权限非目标](2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)仍然是根本性的。这些机制证明注册组合、发布和生命期所有权；它们不证明隔离或父到子的非升权。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 65cbe478ae..76877fd12c 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
 2026-07-19-gui-layering-and-rpc-protocol.md: 8e020e4fe9b60100671c0cf0e98e28532d850f94
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 55fa8084083aa83fbb4a38f8e41d2e5624b6e58e
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 06b861ef61e83985b5c3640ff8eddfa5f6845c81
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 55fa808408..06b861ef61 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -1,4 +1,4 @@
-# RFC: GUI 分层与 RPC 协议——host/client 按能力支持方分层、四象限消息模型与 fetch 载体
+# Agent Note: GUI 分层与 RPC 协议——host/client 按能力提供方分层、四象限消息模型与 fetch 载体
 
 Status: implemented
 
@@ -8,20 +8,20 @@ Status: implemented
 
 ## Problem
 
-需要提供 UI 对接层，除已有 ACP/stdio基础版本外，还需要 Web(server) 、 Electron 、等其他产品 UI 形态。我们把这些形态统一称为 Client。希望有如下能力支持:
-- 以 `dsh` 进程，同时支持 `dsh web`(启动) 和 `dsh run`(headless) ，一个进程两种模式（设计预留）
+需要提供 UI 对接层，除已有 ACP（Agent Client Protocol）/stdio 基线外，还需要 Web（server）、Electron 等其他产品 UI 形态。我们把这些形态统一称为 Client。希望具备以下能力：
+- 一个 `dsh` 进程同时支持 `dsh web`（启动）和 `dsh run`（headless），一个进程两种模式（设计预留）
 - 以与 `dsh web` 同构的 Web 技术形态，在 Electron 中启动
 
 那么当前的工程代码需要稳定的分层职责模型，便于以后接入各类 client 形态。
 
-同时各消费端的物理通道不同（浏览器 HTTP／WebSocket、进程内 fetch/SSE、将来 IPC），还需要一个通道无关的消息模型和单一契约事实源，让「加一个方法」「换一种载体」互不牵连，且 wire 上的每条消息可类型校验、可观测、可对账。
+同时各消费方的物理通道不同（浏览器 HTTP／WebSocket、进程内 fetch/SSE（Server-Sent Events）、将来 IPC），还需要一个通道无关的消息模型和约定的单一真源，让「加一个方法」「换一种载体」互不牵连，且 wire 上的每条消息可类型校验、可观测、可对账。
 
 ## Decision
 
 ### 分层
 
-目录按照如下分层:
-- `packages/host/*`: 包只提供 Host 侧能力（代表了以现在 Harness 实体插件系统为主体的 Node.js 代码核心工程），除此之外，还包含
+目录按照如下分层：
+- `packages/host/*`：包只提供 Host 侧能力（代表了基于现有 harness 插件系统的 Node.js 代码核心工程），除此之外，还包含
     - 统一后端协议（fetch、HTTP、流式接口等）定义和支持，见本篇「消息协议」起各节
 - `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住三类包（两条轴归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有）：
     - **纯库**（`ui-slots`、`web-react`、`ui-primitives`，外加内核包 `loader`）：普通根入口包，静态打包进壳；前三者播种进模块表。
@@ -49,7 +49,7 @@ harness core packages ──────────────────┘
 
 - `runtime → apiproxy` 单向；apiproxy 仅依赖类型定义。
 - client 侧包**永不 import** host 侧包的运行时（只吃 `/api`、`/client` 两个浏览器安全子路径）。
-- `webserver` 不依赖 `runtime`：它提供 `{ fetch }` 特定实现 ——「webserver ← runtime」只是运行时注入关系，不是包依赖。
+- `webserver` 不依赖 `runtime`：它提供一个 `{ fetch }` 形状的实现 ——「webserver ← runtime」只是运行时注入关系，不是包依赖。
 - client 侧跨包 import 插件包一律走 `/client` 子路径，且插件包之间只限类型 import——跨插件值 import 在 tsdown 纯度门禁处即构建错误（值层面的协作走 cordis 服务；边规则归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有）。
 
 TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.json` = solution；`tsconfig.host.json` = host 侧 + 测试，排除 `packages/client`；`tsconfig.client.json` = client 各包及其测试）：两侧在相同键（`sessions`、`loader`）下以不同服务合并 cordis `Context` 接口，单一 program 会同时看到两份声明合并而报冲突。共享叶子包（session/llm/tools/apiproxy 等）只构建一次，由两个 program 共同引用（[拓扑](../process/2026-07-22-tsconfig-solution-root-two-aggregates.md)）。
@@ -60,11 +60,11 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 
 | 层 | 包 | 职责 | 关键纪律 |
 |---|---|---|---|
-| 前置层 | `dsh-host-apiproxy` | TS/zod 定义 (api/)+ fetch 抽象 (fetch/：handler + 客户端基类) | 做简单、所有接入方都要；Node/浏览器皆可 import；协议内容见下文「消息协议」起各节；client 不得经 ctx 绕开 api |
+| 前置层 | `dsh-host-apiproxy` | TS/zod 定义 (api/)+ fetch 抽象 (fetch/：handler + 客户端基类) | 保持简单——每个消费方都需要它；Node/浏览器皆可 import；协议内容见下文「消息协议」起各节；client 不得经 ctx 绕开 api |
 | 装配层 | `dsh-host-runtime` | 插件组合 + ApiProxy 集成 + web UI 插件挂载（覆盖八个 dshClient 包的内存 Loader 树）；host 级配置归属地（defaults/persistenceRoot，将来用户 profile） | 装什么插件、给什么默认值只在这里定；壳不得改装配 |
 | 承载层 | `dsh-host-webserver` | Web 形态 HTTP 与 upgrade：静态服务 + `/api/*`→handler 转发 + WebSocket upgrade route + close 语义；插件 bundle 端点 + `__DSH_BOOT__` manifest（元数据清单）注入（由 web 插件注册表供给） | Web（浏览器访问）专用；零 workspace 依赖（注册表经结构注入到达）；Electron 不复用它 |
 | client 库 | `dsh-client-ui-slots` / `dsh-client-web-react` / `dsh-client-ui-primitives` | slot 注册表核心 / ctx↔React 胶合 / 纯 React 原子组件 | 组件零 cordis 运行时依赖；由壳播种进 loader 模块表 |
-| client 插件 | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | 浏览器侧 cordis 插件树（wire 消费者、核心服务、主题、i18n、布局、侧栏、对话、轨迹）——见 Web 客户端架构 RFC | 双入口（node 半边=空 apply；实现在 `src/client/`）；消费面唯一经 ApiProxy |
+| client 插件 | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | 浏览器侧 cordis 插件树（wire 消费方、核心服务、主题、i18n、布局、侧栏、对话、轨迹）——见 Web 客户端架构 RFC | 双入口（node 半边=空 apply；实现在 `src/client/`）；消费面唯一经 ApiProxy |
 | 应用态 | `@deepseek-ai/dsh`（apps/cli）+ `dsh-frontend`（apps/web，vite 应用） | bin 粗分发 + 每形态一个拼装模块（web.ts / headless.ts）；vite 应用是 `dsh-client-web` 壳表面之上的薄 main | 形态间动态 import 互不加载；dist 定位等 workspace 知识留在 app |
 
 #### 命名规则
@@ -116,7 +116,7 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 
 `ClientResponse` 的 HTTP 应答体是 `RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }`——载体层回执，**不是** RpcMessage（response 不再有 response）；迟到/重复应答收 `not-pending`，逻辑收敛面是 `*/resolved` 帧。
 
-## 类型体系：函数签名即事实源
+## 类型体系：函数签名即真源
 
 ### RpcMethodMap 与派生泛型（`api/rpc-map.ts`）
 
@@ -151,7 +151,7 @@ export type ResponseValue<K> =
 - **锚定**：schema 统一 `satisfies z.ZodType<Wire<T>>`（`api/rpc.schema.ts`）。`Wire<T>` 是深度「| undefined」宽化——仓库开 `exactOptionalPropertyTypes` 而 zod `.optional()` 输出 `T | undefined`，直接锚原类型全线不可用；JSON wire 上缺席与 undefined 同形，宽化不损失校验语义。透传宽分支（`SessionEvent`/`ContentBlock`/帧 union/`RpcError`）与 brand id schema 用显式 cast + 注释。
 - brand cast 单点：每个 schema 文件的 id cast 收口一处（`rpcIdSchema` 是 rpc.schema.ts 唯一 cast 点）。
 
-## 契约面（ApiProxy）
+## 约定面（ApiProxy）
 
 根接口 `ApiProxy = { sessions, host, events, respond }`（`api/index.ts`）。新 client-request 域 = 新的一对文件（`<域>.ts` + `<域>.schema.ts`）+ 根接口一个字段 + map 加行。
 
@@ -163,7 +163,7 @@ export type ResponseValue<K> =
 |---|---|---|---|
 | `session.list` | `{ cursor?: string }`（cursor 留座不实现） | `{ items: SessionSummary[] }` | 已持久化 session，updatedAt 倒序；v1 不建索引 |
 
-其余方法（`session.create`/`session.history`/`session.rename`/`session.prompt`/`session.cancel`/`host.describe`）的参数与返回不在此复写——签名即事实源，见 `api/sessions.ts`、`api/host.ts` 与 `RpcMethodMap`。
+其余方法（`session.create`/`session.history`/`session.rename`/`session.prompt`/`session.cancel`/`host.describe`）的参数与返回不在此复写——签名即真源，见 `api/sessions.ts`、`api/host.ts` 与 `RpcMethodMap`。
 
 ### 帧（server→client，具名 union）
 
@@ -173,7 +173,7 @@ export type ResponseValue<K> =
 |---|---|---|
 | `session/event` | `{ sessionId; event: SessionEvent }` | 核心透传：core 事件原样过，`assistant/chunk` 即 token 流，无独立 delta 帧 |
 
-其余帧型不在此复写，union 全集见 `api/events.ts` 的 `MuxFrame`/`HostFrame`。语义上须知三点：`session/subscribed` 的 lastSeq 供 history 补缝竞态检测；`approval/question` 的 requested 帧可应答（rpcId 稳定）、resolved 帧是收敛面；`host/agent-error` 是无 turn 位置 live 失败的唯一出口。
+其余帧型不在此复写，union 全集见 `api/events.ts` 的 `MuxFrame`/`HostFrame`。语义上须知三点：`session/subscribed` 的 lastSeq 供 history 补缺口竞态检测；`approval/question` 的 requested 帧可应答（rpcId 稳定）、resolved 帧是收敛面；`host/agent-error` 是无 turn 位置 live 失败的唯一出口。
 
 **透传纪律**：wire 上的事件/消息/内容块就是 core 类型（`SessionEvent`/`ContentBlock`），不造第二套 DTO；类型经 `import type` 依赖链直达浏览器。`SessionEventMap` merge-extensible：client 对未知 type documented-default（忽略），事件 schema 留「合法信封+未知类型」分支——信封仍严格，不是字段级 passthrough。
 
@@ -181,11 +181,11 @@ export type ResponseValue<K> =
 
 - **历史 = 事件重放**：一套 fold（client 侧），历史分页与 live 增量同一条代码路径；server 不做物化快照第二套。history **页边界对齐消息边界**（绝不从消息中间截断；chunk 随定稿消息归组），尾页含进行中 partial 的 chunk。
 - **prompt 关联**：prompt 的 rpcId 经 MessageSource（`'user-rpc'`）透传进 `user/message` 事件，client 以此把乐观回显转正。
-- **重连 = 重建**：不做续传 cursor（`mux` 的 `since` 签名留座、传了忽略）；断线重开流 + 重拉 history；`subscribed.lastSeq` 与 history 尾 seq 比对，有缝再补拉一次。
-- **冷会话处理遵循所有权**：`session.history` 与 `session.fork` 的源端读取会在不获取 Agent 的情况下检查持久化存储，而绑定到 Agent 的普通会话方法（如 `prompt`）则通过在途表去重后恢复会话。由会话支撑的 subagent 会拒绝这条通用恢复路径，且附加状态不对客户端暴露（`running` 已经覆盖）。
-- **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：契约与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
+- **重连 = 重建**：不做续传 cursor（`mux` 的 `since` 签名留座、传了忽略）；断线重开流 + 重拉 history；`subscribed.lastSeq` 与 history 尾 seq 比对，如有缺口，再补拉一次。
+- **冷会话处理遵循所有权**：`session.history` 与 `session.fork` 的源端读取会在不获取 agent（智能体） 的情况下检查持久化存储，而绑定到 agent 的普通会话方法（如 `prompt`）则通过在途表去重后恢复会话。由会话支撑的 subagent 会拒绝这条通用恢复路径，且附加状态不对客户端暴露（`running` 已经覆盖）。
+- **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：约定与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
 - **不设协议版本**：client 与 host 绑定发布，`host.describe` 无 protocolVersion 字段；出现独立发布的 client 时再引入。
-- **预留接缝纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。（`session.rename` 已从本清单毕业：追加 user 来源的 `session/title` 事件。）
+- **预留 seam纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。（`session.rename` 已从本清单毕业：追加 user 来源的 `session/title` 事件。）
 
 ## 客户端载体：AbstractApiClient 类体系（`fetch/client.ts`）
 
@@ -193,7 +193,7 @@ export type ResponseValue<K> =
 
 ### IApiClient：caller 视图
 
-与 `ApiProxy` 同域树，但 unary 方法**收业务 payload 直传**——载体 mint rpcId 并包信封，业务代码永不 mint；需要本次调用 rpcId 的从返回的 `RpcResponse` 回显里读。`ApiProxy` 是 impl 侧实现的窄形签名契约，`IApiClient` 是 client 侧消费的 payload 直传视图，`AbstractApiClient` 桥接两者。方法逐 key 从 `RpcMethodMap` 派生——map 加行即机械更新。
+与 `ApiProxy` 同域树，但 unary 方法**收业务 payload 直传**——载体 mint rpcId 并包信封，业务代码永不 mint；需要本次调用 rpcId 的从返回的 `RpcResponse` 回显里读。`ApiProxy` 是 impl 侧实现的窄形签名约定，`IApiClient` 是 client 侧消费的 payload 直传视图，`AbstractApiClient` 桥接两者。方法逐 key 从 `RpcMethodMap` 派生——map 加行即机械更新。
 
 ### 基类持有的协议路径
 
@@ -207,47 +207,47 @@ export type ResponseValue<K> =
 
 ### 实例级 envelope 观测切面
 
-四象限全形均过 `onEnvelope`；基类实现是**实例持有的微任务合批缓冲**（帧风暴不逐帧惊扰消费者；模块级状态会跨实例/测试泄漏，故实例持有）。观测者经 `subscribeEnvelopes(listener)` 订阅（收整批 `readonly RpcMessage[]`，返回退订函数）；listener 抛异常被隔离（观测不得反噬载体）。无订阅者时零缓冲成本。当前没有任何现役消费者订阅——该切面是 wire 诊断的预留位（已退役的 RPC 调试面板是它的首个消费者，将来的诊断消费者接入时不动载体）。
+四象限全形均过 `onEnvelope`；基类实现是**实例持有的微任务合批缓冲**（帧风暴不逐帧惊扰消费方；模块级状态会跨实例/测试泄漏，故实例持有）。观测者经 `subscribeEnvelopes(listener)` 订阅（收整批 `readonly RpcMessage[]`，返回退订函数）；listener 抛异常被隔离（观测不得反噬载体）。无订阅者时零缓冲成本。当前没有任何现役消费方订阅——该切面是 wire 诊断的预留位（已退役的 RPC 调试面板是它的首个消费方，将来的诊断消费方接入时不动载体）。
 
 ### 子类表（传输承载）
 
 | 子类 | 所在包 | doFetch | 用途 |
 |---|---|---|---|
-| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh run` headless 即协议第二真实消费者 |
+| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh run` headless 即协议第二个真正的消费方 |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
-| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，契约/基类零改 |
+| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
 
 ## 怎么扩展（操作清单）
 
-**加一个 unary 方法（5 步）**：①域接口加方法签名（参数/返回内联，这是唯一事实源）；②`RpcMethodMap` 加一行；③`<域>.schema.ts` 加 request/value schema 对（锚 `Wire<RequestPayload<'…'>>`）；④handler `UNARY_ROUTES` 加一行（handler 的 Web 承载见 Web 客户端架构 RFC）；⑤impl 实现（回显 `request.rpcId`）。client 侧 `IApiClient`/`AbstractApiClient` 的域方法表同步加一行透传。
+**加一个 unary 方法（5 步）**：①域接口加方法签名（参数/返回内联，这是唯一真源）；②`RpcMethodMap` 加一行；③`<域>.schema.ts` 加 request/value schema 对（锚 `Wire<RequestPayload<'…'>>`）；④handler `UNARY_ROUTES` 加一行（handler 的 Web 承载见 Web 客户端架构 RFC）；⑤impl 实现（回显 `request.rpcId`）。client 侧 `IApiClient`/`AbstractApiClient` 的域方法表同步加一行透传。
 
 **加一个帧型（3 步）**：①`MuxFrame`/`HostFrame` union 加一支（可应答帧须注明 rpcId 稳定语义）；②帧 schema 加一支；③消费端 fold/路由的 documented-default 已兜底未知型，按需加显式分支。
 
 **加一个错误码（2 步）**：①`RpcErrorDetailsMap` 加一行（details 必填）；②`rpcErrorSchema` discriminatedUnion 加一支。
 
-**接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。契约与基类零改。
+**接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。约定与基类零改。
 
-**升格一个预留接缝**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
+**升格一个预留 seam**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
 
 ## Consequences
 
-所有 client 形态消费同一契约：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
+所有 client 形态消费同一约定：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留 seam（fork/inject/task.list/listModels/hostInstanceId）在真正的消费方出现前保持休眠。
 
 ## Alternatives considered
 
 | 放弃项 | 一句话理由 |
 |---|---|
-| 按「产品形态」分包（web 一族、electron 一族） | 形态间共享的是 host/client 两侧能力而非形态本身；能力支持方分层让新形态零新包 |
-| 混合体建包（如 headless 独立包） | 混合体只有一个消费者（它自己的 app），建包是无主抽象；拼装写在 app 里可读可弃 |
-| 消费型 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开契约，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
+| 按「产品形态」分包（web 一族、electron 一族） | 形态间共享的是 host/client 两侧能力而非形态本身；能力提供方分层让新形态零新包 |
+| 混合体建包（如 headless 独立包） | 混合体只有一个消费方（它自己的 app），建包是无主抽象；拼装写在 app 里可读可弃 |
+| 作为消费方的 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开约定，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
 | webserver 依赖 runtime（省 handler 注入） | 结构 typing 注入让 webserver 可被 sidecar/测试复用且零 workspace 依赖；包依赖会把装配知识拖进承载层 |
 | 包名不带组前缀（沿用 dsh-<尾段>） | `dsh-runtime`/`dsh-web-ui` 在扁平 npm 命名空间里失去归属信息；代价只是每包一条显式 paths |
-| 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、契约双份人肉对齐、命名无 convention 自然漂移 |
+| 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、约定双份人肉对齐、命名无 convention 自然漂移 |
 | 三信封模型（Request/Response/Frame 各一信封，签名不感知方向） | rpcId 是逻辑层关联，帧与应答的方向语义靠通道推断在换载体时即失效 |
-| 具名 Request/Response 类型对为事实源（map 登记类型对） | 平铺具名类型是同一事实的第二个名字；签名 infer 反推让加方法只改一处 |
-| REST 风格路径 | 消费者是自家 client，无第三方 REST 体验诉求；RPC 直映方法表更机械 |
+| 具名 Request/Response 类型对为真源（map 登记类型对） | 平铺具名类型是同一事实的第二个名字；签名 infer 反推让加方法只改一处 |
+| REST 风格路径 | 消费方是自家 client，无第三方 REST 体验诉求；RPC 直映方法表更机械 |
 | DTO 层（wire 专用第二套结构） | core 类型 type-only 直达浏览器零成本；DTO 是永久的双向同步税 |
-| cursor 续传（mux since 实装） | 重连=重建（opencode 同款）覆盖 v1 全部需求；签名留座，实装等真实消费者 |
+| cursor 续传（mux since 实装） | 重连=重建（opencode 同款）覆盖 v1 全部需求；签名留座，实装等真正的消费方 |
 | createApiClient 工厂函数（原实现） | 平台差异（传输/观测）是继承切面不是参数；类体系让 fixture 在协议层替换而不是包一层假信封 |
 | 对 `command.execute` 应用 30 秒传输时限 | 命令耗时属于操作本身，而非传输健康预算；该时限会终止本应继续运行的长时处理器，调用方／连接取消已提供所需的停止路径 |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index d3bbc7da9d..7a82202c72 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
 2026-07-19-gui-web-client-architecture.md: e25d002b92df2016faf4073108aa905b65a1b115
-2026-07-19-gui-web-client-architecture.zh.md: cf31220aad61e4845f7fe90b73bf5da4432e53de
+2026-07-19-gui-web-client-architecture.zh.md: 78a212dc18c1f553a6f782ed60822e36a622bda3
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index cf31220aad..78a212dc18 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -1,10 +1,10 @@
-# RFC: Web 客户端架构——client cordis 插件树、slot 体系与 React-free 对象层
+# Agent Note: Web 客户端架构——client cordis 插件树、slot 体系与 React-free 对象层
 
 Status: implemented
 
 [English](2026-07-19-gui-web-client-architecture.md) | 中文
 
-> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/契约面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
+> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/约定面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
 
 ## Problem
 
@@ -30,27 +30,27 @@ Status: implemented
 
 ## client cordis 树与装载链
 
-装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双层 boot、热重载——归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` seam；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一层预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE 帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
+装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双阶段 boot、热重载——归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` seam；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一阶段预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE（Server-Sent Events）帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
 
 类型宇宙在聚合层拆分——`tsconfig.host.json` 是 host program、`tsconfig.client.json` 是 client program，二者由 solution 根 `tsconfig.json` 引用，因为两侧都在相同键（`sessions`、`loader`）上对 cordis `Context` 做声明合并且服务不同；client 包经纯类型子路径（`@deepseek-ai/dsh-session/types` 等）消费协议词汇，host 侧的声明合并不会搭车进入 client program。
 
 ## slot 体系：页面怎么拼
 
-slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)——本文整体移交给它。此处只留一段定位摘要：壳只渲染 `'root'`；插件用单独一次 `register` 调用组合 UI——占坑、声明并授权子坑（`children` spec 对象）、声明 store、注入业务面；组件 props 分四份额自动推导到达（`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject），各有唯一真源。`SlotMap` 声明合并仍是类型权威，entry 只携带 owner 份额（「谁注入的，类型归谁」）；每个被渲染的注册项都在 per-entry 错误边界之内。
+slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)——本文整体移交给它。此处只留一段定位摘要：壳只渲染 `'root'`；插件用单独一次 `register` 调用组合 UI——占用一个 slot、声明并授权其子 slot（`children` spec 对象）、声明 store、注入业务面；组件 props 以四个自动推导的份额传入（`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject），各有唯一真源。`SlotMap` 声明合并仍是类型权威，entry 只携带 owner 份额（「谁注入的，类型归谁」）；每个被渲染的注册项都在 per-entry 错误边界之内。
 
 实现的家：注册表核心与 props 份额类型在 `packages/client/ui-slots`，出口组件/渲染器/uSES 桥在 `packages/client/web-react`。
 
 ## 服务与 scope 寻址
 
-服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
+服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图 slot 注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装 seam）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：运行时把 Code Dispatch 拓扑投影进每个 root 递归的 `subCalls`；ui-conversation 把这个已排序 root 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或拓扑；ui-tool 渲染传入的树，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
+slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list slot 的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：运行时把 Code Dispatch 拓扑投影进每个 root 递归的 `subCalls`；ui-conversation 把这个已排序 root 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或拓扑；ui-tool 渲染传入的树，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
 
-**scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
+**scope 寻址**与 host 侧 agent（智能体） scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 
 ## 数据对象层（`packages/client/runtime/src/client/sessions/`）
 
-帧从这里进、快照从这里出、fold 坐在中间——React-free（零 React import，grep 可断言）：
+帧从这里进、快照从这里出、投影坐在中间——React-free（零 React import，grep 可断言）：
 
 ```
 mux/host 帧（ConnectionController 泵入，sinks 注入）
@@ -69,24 +69,24 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 ```
 
 - **Session**（session.ts）：懒建、常驻——建成后在后台持续吃帧，切走切回秒显。操作面：`prompt`/`cancel`（RPC 透传；失败落进快照的 `promptError`）、`open`（拉尾页 history，幂等）、`loadOlder`（向上翻页，防重入）、`resync`（重连 = 清窗口重跑 open）。订阅面：`subscribe`/`getSnapshot`（恒返缓存引用）——`implements ObservableSnapshot<ConversationSnapshot>`，构造时挂 `useSelector = bindSnapshotSelector(this)`，Session 本身就是 uSES 源。帧分发是一个 switch：`session/event` 帧按 seq 去重（唯一去重键），open 在途时缓冲，否则追加 + 增量投影；open/缝合按 seq 合并 live 缓冲并去重，`subscribed.lastSeq` 超出窗口尾则回补一次。
-- **ConversationSnapshot**（conversation.ts）：不可变快照契约——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。
+- **ConversationSnapshot**（conversation.ts）：不可变快照约定——`nodes`（供用户阅读的 transcript（文本记录），日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。
 - **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。
 - **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。
-- **TranscriptAdapter / PartialAccumulator**：对话记录是按日志顺序投影的 append 来源 surface（`@deepseek-ai/dsh-session/surface` 的 `isAppendSurfaceEvent`），外加每次落地的压缩检查点一个标记——绝不用模型 surface，后者遮蔽被替换的范围，会抹掉读者已经看过的对话。节点顺序天然按 seq 单调，因此既无核心 `seq === index` 断言需要满足，也没有降级分支。分片不贡献任何节点（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。
+- **TranscriptAdapter / PartialAccumulator**：transcript 是按日志顺序投影的 append 来源 surface（`@deepseek-ai/dsh-session/surface` 的 `isAppendSurfaceEvent`），外加每次落地的压缩（compaction）检查点一个标记——绝不用模型 surface，后者遮蔽被替换的范围，会抹掉读者已经看过的对话。节点顺序天然按 seq 单调，因此既无核心 `seq === index` 断言需要满足，也没有降级分支。分片不贡献任何节点（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。
 - **ConnectionController**（在 `packages/client/connection`）：开 mux/host 双流、for-await 泵入，代际围栏之内指数退避重连（500ms 翻倍至 10s 封顶、抖动、无限重试）；sinks 单向注入（Controller 不认识 Session）。重连 = 重建：`onConnected` → 列表刷新 + 各已打开会话 resync。对象层只面向 `IApiClient`；Web 承载以 HTTP POST 载两个 client→server 象限、以[每逻辑流一条 WebSocket](2026-08-04-websocket-downlink-carrier.md)载两个 server→client 象限，客户端类族归分层 RFC 属地。
 
 ## React 面（`packages/client/web-react`）
 
 胶水包就是整条 ctx↔React 边界；组件保持零框架依赖。
 
-- 快照 store 引擎**住 runtime 包**（zustand vanilla + 草稿式更新，缺省 `flush: 'sync'`，帧驱动 store 可选 `'raf'` 合批，可选整值 localStorage 持久化，dev 深冻结——全部从 `runtime` 的 `./client` 主出口导出，无子路径）：store 产物是裸的可观察源，不带任何 hook 成员。插件只经 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 的 `defineStore` 声明触及引擎。web-react 在绑定处（`bindSnapshotSelector`，按源缓存）从 React 消费的唯一数据契约合成每个 hook：`ObservableSnapshot<T>`（`getSnapshot`/`subscribe`）——Session 对象与快照 store 同构满足它。业务插件包只依赖 runtime 与 ui-slots；web-react 是仅壳可用的胶水。
-- `bindSnapshotSelector(source)`：把一个源绑定为经 uSES-with-selector 的带类型 selector hook。uSES 契约四条按构造成立：getSnapshot 恒返缓存引用；subscribe 是绑定期闭包（引用永稳）；纯 CSR 不传 server snapshot；相等性缺省 `Object.is`，按调用可选 `shallowEqual`。
+- 快照 store 引擎**住 runtime 包**（zustand vanilla + 草稿式更新，缺省 `flush: 'sync'`，帧驱动 store 可选 `'raf'` 合批，可选整值 localStorage 持久化，dev 深冻结——全部从 `runtime` 的 `./client` 主出口导出，无子路径）：store 产物是裸的可观察源，不带任何 hook 成员。插件只经 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 的 `defineStore` 声明触及引擎。web-react 在绑定处（`bindSnapshotSelector`，按源缓存）从 React 消费的唯一数据约定合成每个 hook：`ObservableSnapshot<T>`（`getSnapshot`/`subscribe`）——Session 对象与快照 store 同构满足它。业务插件包只依赖 runtime 与 ui-slots；web-react 是仅壳可用的胶水。
+- `bindSnapshotSelector(source)`：把一个源绑定为经 uSES-with-selector 的带类型 selector hook。uSES 约定四条按构造成立：getSnapshot 恒返缓存引用；subscribe 是绑定期闭包（引用永稳）；纯 CSR 不传 server snapshot；相等性缺省 `Object.is`，按调用可选 `shallowEqual`。
 - `useInvoke(fn)`：把异步动作包成引用恒定的触发器加 pending 标志；pending 走 per-hook 外部 store 经 uSES 读出（渲染路径零 setState），并发调用计数，invoke 引用永不变。
-- 相等性协议，全链一致：生产端结构共享；消费端以 `Object.is` 或 `shallowEqual` 短路；`React.memo` 浅比较。深比较全链禁止。
+- 相等性协议，全链一致：生产端结构共享；消费方以 `Object.is` 或 `shallowEqual` 短路；`React.memo` 浅比较。深比较全链禁止。
 
 ## 目录形态
 
-Client 包位于 `packages/client/*`，`apps/web` 是壳 boot 导出之上的薄 Vite 应用。插件包的浏览器半边在 `src/client/` 下；**一切构建产物落 `lib/`**——node 半边为 `lib/index.js`/`lib/invariant.js`，浏览器 bundle 为 `lib/client.js`（共享 tsdown client 预设两者皆出；无 `dist/` 目录，`exports["./client"]` 指向 `./lib/client.js`）。`ui-slots`、web-react 与 runtime 构成基础设施方向；功能插件通过 service 与 slot 协作，不导入展示实现。
+Client 包位于 `packages/client/*`，`apps/web` 是壳 boot 导出之上的薄 Vite 应用。插件包的浏览器半边在 `src/client/` 下；**一切构建产物落 `lib/`**——node 半边为 `lib/index.js`/`lib/invariant.js`，浏览器 bundle 为 `lib/client.js`（共享 tsdown client 预设两者皆出；无 `dist/` 目录，`exports["./client"]` 指向 `./lib/client.js`）。`ui-slots`、web-react 与 runtime 构成基础设施方向；功能插件通过服务与 slot 协作，不导入展示实现。
 
 多域插件包的 client 半边还按未来包边界再拆——ui-conversation 即样板：
 
@@ -108,7 +108,7 @@ src/client/
 ## 怎么开发
 
 - **新 UI 功能** = 新插件包：package.json 声明 `dshClient`（+ `inject` 拓扑），浏览器半边写在 `src/client/`（apply 挂服务/建 store、注册 slot），无 host 逻辑时 node 半边保持空 apply，用共享预设构建。把插件加进 host 配置；manifest 与装载随之自动跟上。
-- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——契约合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
+- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——约定合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
 - **消费新帧类型**：带 sessionId → Session 分发 switch 加一个分支；host 级 → Manager 路由表；UI 需要时给 `ConversationSnapshot` 加字段并守住引用纪律。
 - **状态住哪**：业务数据（事件、流式、待答）→ 永远对象层；父知道的 → renderSlot 现场的 owner props；单组件私有（滚动、搜索词、展开集）→ 组件状态；跨 entry 共享或跨重挂载存活（选中、草稿、面板宽）→ entry 声明的 store（[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)）。
 - **通知通道**：帧驱动/异步 = `markDirty` 合批；受控输入需要同 tick 的用户手势直接回响 = `notifyNow`。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
index acb9d72ef1..91f2d8742b 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
 2026-07-19-zstandard-jsonl-session-logs.md: 93fc20f931c75552352834b9340e7d38680d4254
-2026-07-19-zstandard-jsonl-session-logs.zh.md: 061d7fcb55c775eed10e99bae47777d32cc8eee1
+2026-07-19-zstandard-jsonl-session-logs.zh.md: 48dde6018bc022c90735ca351207be46cd0956a2
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
index 061d7fcb55..48dde6018b 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量庞大的 `assistant/chunk` 记录。原始文本便于检查，但重复的 JSON 键和模型文本会增加存储与 I/O 开销。压缩编码必须保留既有的 append/fsync 提交边界、首次物化时的无冲突发布、崩溃修复以及仅元数据列举；如果每轮都重写整个压缩文件，就会失去这些属性。
 
-编码还必须在部署边界上保持显式。快照 fixture 与外部逐行读取器需要原始 JSONL，而后端无法在同一根目录中安全猜测压缩产物与原始产物，也不能静默迁移预发布会话数据。
+编码还必须在部署边界上保持显式。快照 fixture（测试前置数据）与外部逐行读取器需要原始 JSONL，而后端无法在同一根目录中安全猜测压缩产物与原始产物，也不能静默迁移预发布会话数据。
 
 ## 决策
 
@@ -20,7 +20,7 @@ JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量
 
 ### 帧与写入路径
 
-压缩产物是标准独立 [Zstandard 帧](https://datatracker.ietf.org/doc/html/rfc8878)的串联：第一个带校验和的帧只包含头部行，后续每个持久追加批次各占一个带校验和的帧。正常 agent loop 批次就是轮次提交，因此帧边界保留既有持久化检查点，同时不让存储层依赖轮次事件类型。
+压缩产物是标准独立 [Zstandard 帧](https://datatracker.ietf.org/doc/html/rfc8878)的串联：第一个带校验和的帧只包含头部行，后续每个持久追加批次各占一个带校验和的帧。正常 agent loop（智能体循环）批次就是轮次提交，因此帧边界保留既有持久化检查点，同时不让存储层依赖轮次事件类型。
 
 压缩使用 Node 内置的 [`zstdCompress` 与 `zstdDecompress`](https://nodejs.org/download/release/v22.19.0/docs/api/zlib.html)，仓库最低支持的 Node 22.19 已提供这些 API。后端启用 `ZSTD_c_checksumFlag`，其余采用 Node 默认值，不公开压缩级别调节项，也不增加依赖。Node 将该 API 标记为实验性，因此 Node 22.19、24 与 26 兼容性门禁会执行同一个辅助实现。
 
@@ -36,9 +36,9 @@ JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量
 
 ### 消费方与验证
 
-CLI、ACP 与 stdio 应用包公开对称的 `persistenceCompression` 透传配置。web 宿主装配与普通应用组合省略该选项并使用压缩默认值。快照录制与回放组合显式选择 `'none'`，因为提交的 fixture 是回放与规范化过程使用的原始 JSONL 输入。
+CLI（命令行界面）、ACP（Agent Client Protocol）与 stdio 应用包公开对称的 `persistenceCompression` 透传配置。web 宿主装配与普通应用组合省略该选项并使用压缩默认值。快照录制与回放组合显式选择 `'none'`，因为提交的 fixture 是回放与规范化过程使用的原始 JSONL 输入。
 
-共享持久化契约与协调器契约会针对两种编码运行。后端测试覆盖标准帧与校验和互操作性、仅头部列举、追加回滚、编码不匹配拒绝、完整帧损坏，以及横跨头部、块和校验和尾部的最终帧撕裂。默认运行时、构建后二进制、headless、ACP 与 Python 冒烟测试会断言压缩后缀与 Zstandard 魔数，或解码头部；读取原始内容的测试则显式退出压缩。
+共享持久化约定与协调器约定会针对两种编码运行。后端测试覆盖标准帧与校验和互操作性、仅头部列举、追加回滚、编码不匹配拒绝、完整帧损坏，以及横跨头部、块和校验和尾部的最终帧撕裂。默认运行时、构建后二进制、headless、ACP 与 Python 冒烟测试会断言压缩后缀与 Zstandard 魔数，或解码头部；读取原始内容的测试则显式退出压缩。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
index f8a9c8c260..33ff739db9 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
 2026-07-23-client-plugin-loading-model.md: 2dc0c68e5f20bd790c2362f92c16dece171babf5
-2026-07-23-client-plugin-loading-model.zh.md: ce7850e37b9ae2735565a35ce3de28f4f290ed04
+2026-07-23-client-plugin-loading-model.zh.md: abe62f4c03147cc4716103e531adb812f073e622
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
index ce7850e37b..abe62f4c03 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: client 插件装载——普通包、dshClient 插件与双层 boot
+# Agent Note: client 插件装载——普通包、dshClient 插件与双阶段 boot
 
 Status: implemented
 
@@ -31,7 +31,7 @@ host 侧，cordis 插件装载站在 Node 的模块机制之上——require cac
 - **普通包**是模块系统自身所需的绝对基座，加上尚未转成 DI 的库：react 家族、cordis、`@deepseek-ai/dsh-client-modules`（模块系统本身——它永远不可能是插件，因为模块先于一切模块）、web 壳内核，以及——暂时——ui-slots、web-react、ui-primitives。普通包打进壳 bundle、播种进模块表、对 host 图不可见。
 - **插件包**是其余一切。每个都携带 `dshClient` manifest（元数据清单）声明（`{ platform, inject, immediately? }`）和同一种统一形态：共享 tsdown 预设产出 `lib/client.js`，`exports["./client"]` 指向该 bundle。每个都是 host 独家撰写的图里受治理的 entry。当前包括：connection、runtime、ui-theme、i18n、hmr（仅进 dev 图）、ui-layout、ui-sidebar、ui-conversation、ui-model-selector、ui-question、ui-trajectory。
 
-manifest 拥有包的装载契约：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册与 `--dev` 开关。
+manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册与 `--dev` 开关。
 
 新增一个插件包：声明 `dshClient`，经共享预设产出 `./client` bundle，把包名加进负责组合的 app 的名册。除此之外无需任何交接。
 
@@ -72,21 +72,21 @@ vendored Loader 经其 `internal` seam 消费模块系统——唯一调用点
 
 为什么名册是 yml 行而不是扫描？因为哪些插件组合进一次部署是组合决策，不是包属性——一个 dshClient 包存在于仓库里，不代表这次部署要挂载它，扫描发现无从替人做这个决定；node 半只扫描配置树实际挂载了的东西。
 
-**第一层——模块面。**壳在图之上建起模块系统，然后并行预取每个 `immediately` 行。预取即加载外部脚本，只登记工厂。单行预取失败在这里被吞下：第二层 import 时会重试加载并拥有那次大声失败，因此一个坏行藏不住其他行。`immediately` 是预取标记——不是屏障，不是身份。包声明它，注册表把它带进图行。基础设施插件（connection、runtime、ui-theme、i18n，外加 hmr）声明它；UI 插件则径直按需到达。
+**第一阶段——模块面。**壳在图之上建起模块系统，然后并行预取每个 `immediately` 行。预取即加载外部脚本，只登记工厂。单行预取失败在这里被吞下：第二阶段 import 时会重试加载并拥有那次大声失败，因此一个坏行藏不住其他行。`immediately` 是预取标记——不是屏障，不是身份。包声明它，注册表把它带进图行。基础设施插件（connection、runtime、ui-theme、i18n，外加 hmr）声明它；UI 插件则径直按需到达。
 
-**第二层——插件面。**
+**第二阶段——插件面。**
 
 1. 内核挂载 vendored Loader，在任何 entry 存在之前就把模块系统注入为 `internal`。顺序有讲究：`tree.import` 的裸 import 兜底分支在浏览器里绝不能跑到。
 2. 它为图中每一行创建 entry，外加 app-shell 伪行。装配 entry 是内核自己追加的壳自有代码——向模块系统静态登记，绝不进 host 图——因此与其余一切共乘同一套 entry 生命周期与状态覆盖。
 3. 创建顺序不携带任何语义；fiber 经服务等待激活。
-4. `settled` = 每个 entry 已创建 + `loader.await()` 停稳 + 一次全 ACTIVE 扫描。扫描列出每个 import 失败、FAILED 或 PENDING 的 fiber 及其缺失的服务。它存在的理由：cordis 的 inject 等待没有超时——这次扫描就是大声失败的兜底线。
+4. `settled` = 每个 entry 已创建 + `loader.await()` 完全停稳 + 一次全 ACTIVE 扫描。扫描列出每个 import 失败、FAILED 或 PENDING 的 fiber 及其缺失的服务。它存在的理由：cordis 的 inject 等待没有超时——这次扫描就是大声失败的兜底线。
 5. loading 页的启动状态是经 `internal/status` 对真实 fiber 状态的投影。settled 翻转即一次性切换到真实 UI。
 
 ### 热重载：一个驱动插件，自行监视的 bundle
 
-热重载是否启用是一项组合决策：dev 组合挂载 `client-hmr` 行（一个常规的插件包，由 `--dev` 追加），其 node 半带来 bundle 监视与 SSE 通道；prod 组合不挂载，两者皆无。
+热重载是否启用是一项组合决策：dev 组合挂载 `client-hmr` 行（一个常规的插件包，由 `--dev` 追加），其 node 半带来 bundle 监视与 SSE（Server-Sent Events）通道；prod 组合不挂载，两者皆无。
 
-重建好的 bundle 怎么变成重载信号？hmr 的 node 半自己观察——没有构建器来通知它。它从 `ctx.clientModuleHost.clientPath(id)` 读取图上各行的 bundle 路径，由 HMR 自持的单个定时器对当前图上的每一行做 stat 轮询。新增图行时，顺序固定为先同步取得 stat 基线，再立即调用 `clientModuleHost.rebuilt(id)`：在模块 host 算出图哈希之后、取得基线之前发生的写入会被这次立即重哈希捕获；取得基线之后发生的写入则会留下 stat 差异，供下一次轮询捕获。这避开了 `fs.watchFile`：它以异步首次 stat 建立基线，可能把构造期间的重建静默吸收进基线。监视集合的成员随 `onGraphChanged` 更新；消失的行撤下监视，轮询时缺失的 bundle 则让对应行保持标脏状态，文件重现时即使元数据相同也强制重哈希。mtime/size 变化或行处于标脏状态时，`clientModuleHost.rebuilt(id)` 是重哈希的唯一入口；当 `rev` 真的变了，node 半才在 `GET /plugins/events` 上广播 `rebuilt` 帧——这是一条系统级 SSE（Server-Sent Events）通道，连接即发全量图，变更时发 `rebuilt` 帧，仅供呈现的 wire，永不进会话日志。轮询是刻意选择：inotify 在 weka 网络挂载上不触发，构建侧监视器需要 `--poll` 也是同一原因；轮询间隔是一个经校验的配置字段（默认 500ms），dispose（资源释放）会清掉那一个定时器。重建 bundle 则是任意一个 tsdown watch 进程的事——`scripts/dev-web.ts` 仍作为 watch 构建入口保留，其包清单在启动时扫描 `packages/*/*/package.json` 按 dshClient 发现——构建器与 host 共享零协议。写一半的 bundle 被撕裂读取会自愈：写入完成期间 stat 持续变化，下一个轮询节拍会再次重哈希并广播最终的 rev。
+重建好的 bundle 怎么变成重载信号？hmr 的 node 半自己观察——没有构建器来通知它。它从 `ctx.clientModuleHost.clientPath(id)` 读取图上各行的 bundle 路径，由 HMR 自持的单个定时器对当前图上的每一行做 stat 轮询。新增图行时，顺序固定为先同步取得 stat 基线，再立即调用 `clientModuleHost.rebuilt(id)`：在模块 host 算出图哈希之后、取得基线之前发生的写入会被这次立即重哈希捕获；取得基线之后发生的写入则会留下 stat 差异，供下一次轮询捕获。这避开了 `fs.watchFile`：它以异步首次 stat 建立基线，可能把构造期间的重建静默吸收进基线。监视集合的成员随 `onGraphChanged` 更新；消失的行撤下监视，轮询时缺失的 bundle 则让对应行保持标脏状态，文件重现时即使元数据相同也强制重哈希。mtime/size 变化或行处于标脏状态时，`clientModuleHost.rebuilt(id)` 是重哈希的唯一入口；当 `rev` 真的变了，node 半才在 `GET /plugins/events` 上广播 `rebuilt` 帧——这是一条系统级 SSE 通道，连接即发全量图，变更时发 `rebuilt` 帧，仅供呈现的 wire，永不进会话日志。轮询是刻意选择：inotify 在 weka 网络挂载上不触发，构建侧监视器需要 `--poll` 也是同一原因；轮询间隔是一个经校验的配置字段（默认 500ms），dispose（资源释放）会清掉那一个定时器。重建 bundle 则是任意一个 tsdown watch 进程的事——`scripts/dev-web.ts` 仍作为 watch 构建入口保留，其包清单在启动时扫描 `packages/*/*/package.json` 按 dshClient 发现——构建器与 host 共享零协议。写一半的 bundle 被撕裂读取会自愈：写入完成期间 stat 持续变化，下一个轮询节拍会再次重哈希并广播最终的 rev。
 
 浏览器侧，驱动插件每帧重载一个插件，串行执行：
 
@@ -108,7 +108,7 @@ vendored Loader 经其 `internal` seam 消费模块系统——唯一调用点
 |---|---|---|---|
 | react 家族 / cordis | 平台单例 | 打进壳，已播种 | 永为普通包（绝对基座） |
 | vendored `@cordisjs/plugin-loader` | entry 治理（两侧同一份代码） | 编译期浏览器化，内核挂载 | 不动（vendor 政策） |
-| `dsh-client-modules` | client 模块系统 | lazy CJS 模块表；双层 boot | 永为普通包（模块先于模块） |
+| `dsh-client-modules` | client 模块系统 | lazy CJS 模块表；双阶段 boot | 永为普通包（模块先于模块） |
 | `dsh-client-web` | 壳内核 + AppRoot + app-shell 装配 | 自足（手写状态 store，零插件值 import） | 持续缩小 |
 | `dsh-client-ui-slots` | slot 注册表核心 | 普通包，已播种 | 升格为插件；接收 runtime 的 slots 机件 |
 | `dsh-client-web-react` | ctx↔React 胶水 | 普通包，已播种 | 升格为插件；渲染器安装移入其 apply |
@@ -126,7 +126,7 @@ wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模
 
 接受的代价：vendored Loader 在浏览器里背着闲置机件（EntryTree 持久化是 no-op，分组/隔离未用）；开发期每次修改插件都要付一次 bundle 重建加 fiber 重挂；图中 `inject` 行仅是信息性说明——激活的真相在服务层——因此不匹配会在 settled 扫描时浮出，而不是在图校验时被拦下；三个尚未升格的库在各自的 DI 转换落地之前保持静态 import 的导出面；每个 bundle 多出一份 sourcemap 产物，外部脚本失败也只能给出粗粒度的 URL 诊断，不能像显式 fetch 那样报告 HTTP 状态。
 
-名册的终局（2026-07-25 随配置树 boot 迁移落地）：名册住 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml`，`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量已消失，重组一次部署等于换 yml/overlay。图的组合器从 webserver 侧的注册表迁进 `dsh-client-modules` 的 node 半（该包按本 note 的升级法则升格为双面——其消费方现经 cordis DI 到达），传输拆分同轮落地：webserver 变为朴素路由注册插件，`/api/*` 绑定迁到 connection 的 node 半、走升格后的 `api-gateway` 插件（`dsh-host-apiproxy` 提供 `ctx.apiProxy`），dev 的 bundle 监视与 SSE 通道迁到 hmr 的 node 半。
+名册的终局（2026-07-25 随配置树 boot 迁移落地）：名册位于 `apps/cli/config/web.cordis.yml`，`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量已消失，重组一次部署等于换 yml/overlay。图的组合器从 webserver 侧的注册表迁进 `dsh-client-modules` 的 node 半（该包按本 note 的升级法则升格为双面——其消费方现经 cordis DI 到达），传输拆分同轮落地：webserver 变为朴素路由注册插件，`/api/*` 绑定迁到 connection 的 node 半、走升格后的 `api-gateway` 插件（`dsh-host-apiproxy` 提供 `ctx.apiProxy`），dev 的 bundle 监视与 SSE（Server-Sent Events）通道迁到 hmr 的 node 半。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
index 1c6a23eec8..d4ff0f5d44 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.md
 2026-07-27-compiler-independent-typert-model.md: 15641e5f785c5d2daecbfc2d5cffedd64d8384a7
-2026-07-27-compiler-independent-typert-model.zh.md: 7bddd3ffde343346c163f55ef493c32bad1e8314
+2026-07-27-compiler-independent-typert-model.zh.md: acc7be0a5f747dea1ce2fe7497575e50494fd754
diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
index 7bddd3ffde..acc7be0a5f 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-直接从 TypeScript AST 拼接 Zod 和反射文本，会把类型分析、业务语义识别与单个生成目标绑在一起。这样的生成器只能回答“这段语法能否生成”，无法提供包、face、公开导出、service、event、对象及其类型关系的标准表示，也无法供静态检查和后续生成目标复用。
+直接从 TypeScript AST 拼接 Zod 和反射文本，会把类型分析、业务语义识别与单个生成目标绑在一起。这样的生成器只能回答「这段语法能否生成」，无法提供包、face、公开导出、服务、事件、对象及其类型关系的标准表示，也无法供静态检查和后续生成目标复用。
 
 host 与 client 属于独立 TypeScript project；把两者放进同一个 `ts.Program` 会合并冲突的 Cordis `Context` 与 `Events` 声明。与此同时，client 类型仍需显式引用 host 类型，因此完全隔离或在两边复制类型都不能表达真实依赖。
 
@@ -16,38 +16,38 @@ host 与 client 属于独立 TypeScript project；把两者放进同一个 `ts.P
 
 TypeGraph 保存开发者写下的计算前类型结构，包括泛型参数与应用、显式继承、conditional、mapped、递归引用和 JSDoc。无法无损表示的可达类型使分析失败；某个 emitter 无法处理已经建模的节点时由该 emitter 失败，而不是把类型展平或降级为 `unknown`。
 
-每个 face 独立拥有 PackageModel 和 TypeGraph。`tsconfig.host.json` 与 `tsconfig.client.json` 的直接 project references 决定 package 的 face 归属，`package.json#exports` 决定公开边界。跨 face 关系只来自源码中的显式 import 或 re-export，并作为独立 link 保留；外部 npm 类型记录为 External，不读取或复制其声明。
+每个 face 独立拥有 PackageModel 和 TypeGraph。`tsconfig.host.json` 与 `tsconfig.client.json` 的直接 project references 决定包的 face 归属，`package.json#exports` 决定公开边界。跨 face 关系只来自源码中的显式 import 或 re-export，并作为独立 link 保留；外部 npm 类型记录为 External，不读取或复制其声明。
 
-PackageModel 识别 Cordis service、event、`@typert object` 引用对象和 `@typert schema` 数据根。service 与 object 只暴露 public instance member，排除 constructor、static、private 和 protected；继承边保留在 TypeGraph 中，不复制为扁平成员。缺少 public property、parameter 或 return 类型标注时，`check` 模式报错，`write` 模式写入 checker 推断结果后重建 project 并再次以严格模式分析。
+PackageModel 识别 Cordis 服务、事件、`@typert object` 引用对象和 `@typert schema` 数据根。服务与 object 只暴露 public instance member，排除 constructor、static、private 和 protected；继承边保留在 TypeGraph 中，不复制为扁平成员。缺少 public property、parameter 或 return 类型标注时，`check` 模式报错，`write` 模式写入 checker 推断结果后重建 project 并再次以严格模式分析。
 
-[`dsh-typert-registry`](../../../../packages/typert/registry/README.md) 提供 `ctx.typert`，且只负责运行时注册：一个 contribution 原子携带 package-face reflection 与可选 Zod schema，并随 Cordis effect 撤销。注册表不分析 TypeScript，也不合并两个 face。JSON Schema 是对已注册 Zod schema 的按需投影。
+[`dsh-typert-registry`](../../../../packages/typert/registry/README.md) 提供 `ctx.typert`，且只负责运行时注册：一个 contribution 原子携带包-face reflection 与可选 Zod schema，并在 Cordis effect 执行 dispose（资源释放）时将其撤销。注册表不分析 TypeScript，也不合并两个 face。JSON Schema 是对已注册 Zod schema 的按需投影。
 
-包产物发布仍通过 package exports 采用显式 opt-in。`WorkspaceTypertGenerator` 仅在被调用时校验所请求 face 的根目录产物协议：host face 必须通过面向用户的 subpath `package/typert` 暴露 `package/lib/typert.host.{js,d.ts}`，client face 必须通过 `package/client/typert` 暴露 `package/lib/typert.client.{js,d.ts}`；它不会修改这些 exports。后续的 [TypeRT Remote 设计](2026-08-02-typert-remote-method-calls.md) 为根目录 build、typecheck、lint 与文档类型检查增加了全仓 Host 契约 pass。对于已 opt-in 的 Host 包，该 pass 会在消费方解析两者之前生成本地反射产物与严格的 Host-for-Client `/remote` 契约。生成的本地声明将 `TYPERT` 类型保持为 `unknown`，因此业务包不依赖注册表。
+包产物发布仍通过包导出采用显式 opt-in。`WorkspaceTypertGenerator` 被调用时，会逐一校验请求的 face：host face 必须通过面向用户的 subpath `package/typert` 暴露根产物 `package/lib/typert.host.{js,d.ts}`，client face 必须通过 `package/client/typert` 暴露根产物 `package/lib/typert.client.{js,d.ts}`；它绝不会修改这些 exports。后续的 [TypeRT Remote 设计](2026-08-02-typert-remote-method-calls.md) 为根目录 build、类型检查、lint 与文档类型检查增加了全仓 Host 约定检查。对于已 opt-in 的 Host 包，该 pass 会在消费方解析两者之前生成本地反射产物与严格的 Host-for-Client `/remote` 约定。生成的本地声明将 `TYPERT` 类型保持为 `unknown`，因此业务包不依赖注册表。
 
 构建期的 `CordisCatalogProjector` 一次消费分析后的 `FaceModel` 与 `TypeGraph`，生成 `docs/cordis-catalog/events.md`、`docs/cordis-catalog/services.md`，以及为 `tool-cordis` 提交的静态 `SERVICE_API`、`EVENT_API` 和 `TYPE_API` catalog。`tool-cordis` 读取该静态 catalog，运行时不依赖 `ctx.typert`。[`dsh-typert-loader`](../../../../packages/typert/loader/README.md) 与注册表仍是独立的运行时路径：loader 监听 Cordis Loader 配置项生命周期事件，导入显式发布的 `./typert` host 产物，并通过 `ctx.typert` 注册；两者都不是当前 `cordis_inspect` catalog 的数据源。
 
 ## Verification contract
 
-提交内的小型双 face project 对完整类型模型及其源码声明索引做 snapshot。全仓分批分析与直接聚焦分析必须为相同 face 生成模型等价的 `FaceModel` 与 `TypeGraph`。类型级全集和运行时集合比较保证每种 node、target、declaration 与 member discriminant 都来自真实 TypeScript syntax；字段语义矩阵覆盖所有 keyword、type operator、literal value 类目，以及泛型、参数、tuple、mapped modifier、import attributes、abstract、predicate 和 enum initializer 的各个状态。
+仓库内的小型双 face project 对完整类型模型及其源码声明索引做快照。全仓分批分析与直接聚焦分析必须为相同 face 生成模型等价的 `FaceModel` 与 `TypeGraph`。编译期穷尽映射和运行时集合比较保证每种 node、target、declaration 与 member discriminant 都由源码编写的 TypeScript syntax 覆盖；字段语义矩阵覆盖所有 keyword、type operator、literal value 类目，以及泛型、参数、tuple、mapped modifier、import attributes、abstract、predicate 和 enum initializer 的各个状态。
 
 `SyntaxZoo` 中每个 property 的源码类型经 TypeScript printer 标准化后，必须与 TypeGraph 渲染结果逐项相等，随后所有渲染 declaration 再交给 TypeScript 编译。这一层检查节点内部信息是否无损，包括无插值 template literal、带 type argument 的 type query 和受约束 `infer`，不以 discriminant 覆盖或代码覆盖率代替结构等价。
 
-边界用例固定同 face 与跨 face 的显式包导入、跨 face 命名 re-export、精确 export alias、qualified `import()` link 和全局 `@types` External 归属，并拒绝 package 自有 TypeScript 诊断、相对路径越界、`package.json#exports` 之外的引用，以及尚无模型 target 的跨 face namespace re-export。interface declaration merging 显式保留每个 authored part，无法无损表示的其他 merge 失败。
+边界用例固定同 face 与跨 face 的显式包导入、跨 face 命名 re-export、精确 export alias、qualified `import()` link 和全局 `@types` External 归属，并拒绝源自包自有文件的 TypeScript 诊断、相对路径越界、`package.json#exports` 之外的引用，以及尚无模型 target 的跨 face namespace re-export。interface declaration merging 显式保留每个 authored part，无法无损表示的其他 merge 失败。
 
-Zod emitter 对支持的节点和各类 literal 逐类执行成功与失败 parse，对不支持的节点逐类断言明确的 `TypertEmitError`。Emitter fixture 对生成的 Zod JavaScript 与 `.d.ts` 文本做快照，执行 JavaScript，并对声明做类型检查。`dsh-typert-registry` 测试固定原子注册、查询、JSON Schema 和 effect 撤销，`dsh-typert-loader` 测试还证明延迟挂载、卸载及未完成 dynamic import 的释放行为。真实 `dsh-tools` 纵切从模型生成 contribution，经运行时注册表加载后，将其服务、事件与关联类型记录同已提交的静态 `SERVICE_API`、`EVENT_API` 和 `TYPE_API` 对照。全仓 projector 测试重新生成两份 Cordis catalog 文档与 `tool-cordis` API catalog，并要求三份文本同已提交产物逐字节一致。
+Zod emitter 对支持的节点和各类 literal 逐类执行成功与失败 parse，对不支持的节点逐类断言明确的 `TypertEmitError`。Emitter fixture（测试前置数据）对生成的 Zod JavaScript 与 `.d.ts` 文本做快照，执行 JavaScript，并对声明做类型检查。`dsh-typert-registry` 测试固定原子注册、查询、JSON Schema 和 effect dispose，`dsh-typert-loader` 测试还证明 dynamic import 仍处于等待状态时的延迟挂载、卸载和 dispose。真实 `dsh-tools` 纵切从模型生成 contribution，经运行时注册表加载后，将其服务、事件与关联类型记录同已提交的静态 `SERVICE_API`、`EVENT_API` 和 `TYPE_API` 对照。全仓 projector 测试重新生成两份 Cordis catalog 文档与 `tool-cordis` API catalog，并要求三份文本同已提交产物逐字节一致。
 
 ## Alternatives considered
 
-**直接保存 TypeScript AST。** AST 能保留源码写法，但会让每个消费者依赖 compiler 生命周期、node identity 和 checker 上下文，无法形成稳定的架构边界，因此只在提取阶段使用。
+**直接保存 TypeScript AST。** AST 能保留源码写法，但会让每个消费方依赖 compiler 生命周期、node identity 和 checker 上下文，无法形成稳定的架构边界，因此只在提取阶段使用。
 
 **基于 checker 的最终类型生成。** 展平后的 `ts.Type` 便于直接遍历，却丢失泛型、conditional、mapped 和 alias application 的开发者表达，无法满足反射与后续生成需要。
 
-**合并 host/client project 或复制 host 类型。** 合并会污染 Cordis declaration merging；复制会产生第二份类型事实源。独立 face 加显式 cross-face link 保留了 project 隔离与真实引用关系。
+**合并 host/client project 或复制 host 类型。** 合并会污染 Cordis declaration merging；复制会产生第二个类型真源。独立 face 加显式 cross-face link 保留了 project 隔离与真实引用关系。
 
 **让 `dsh-typert-registry` 承担类型解析和跨包合成。** 这会把 TypeScript compiler、Cordis 生命周期和具体 schema 策略重新耦合。注册表保持为生成 artifact 的生命周期容器，复杂分析留在构建期模型。
 
 ## Consequences
 
-新增生成目标或静态检查可复用同一 TypeGraph，业务类目也可在 PackageModel 上扩展，而无需再次解析 AST。保留计算前类型和独立 face 的代价是模型比打平后的 schema 更复杂，emitter 必须显式声明支持范围并对缺失能力失败。
+新增生成目标或静态检查可复用同一 TypeGraph，业务类目也可在 PackageModel 上扩展，而无需再次解析 AST。保留计算前类型和独立 face 的代价是模型比打平后的 schema 更复杂，emitter 必须显式声明支持范围，并在缺少相应能力时失败。
 
-包级显式 opt-in 使产物发布与 exports 由各包自行管理。仓库编排仍可为每个已 opt-in 的包运行全仓 Host 契约 pass；该 pass 仍由后续 Remote Gateway Agent Note 负责说明。静态 Cordis catalog 可从标准模型复现，同时不把 `tool-cordis` 与运行时注册表状态耦合。`ctx.typert` 只反映当前运行时中已挂载的产物；对于消费方直接导入后仍持有的 Zod 实例，卸载流程无法控制。
+包级显式 opt-in 使产物发布与 exports 由各包自行管理。仓库编排仍可为每个已 opt-in 的包运行全仓 Host 约定检查；该 pass 仍由后续 Remote Gateway Agent Note 负责说明。静态 Cordis catalog 可从标准模型复现，同时不把 `tool-cordis` 与运行时注册表状态耦合。`ctx.typert` 只反映当前运行时中已挂载的产物；对于消费方直接导入后仍持有的 Zod 实例，卸载流程无法控制。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
index 048536527a..3cd70dd035 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
 2026-07-28-directory-picker-capability-seam.md: 01968990db81852dbf965a90fc151bab357ecb55
-2026-07-28-directory-picker-capability-seam.zh.md: ffbb939eabcca3e16711a4cadcadad50660a9e04
+2026-07-28-directory-picker-capability-seam.zh.md: 063ac7b0220c07d5b7caa3d892b7ec17e7e117ee
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
index ffbb939eab..063ac7b022 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
@@ -1,48 +1,48 @@
-# Agent Note：web GUI 宿主的能力可辨识目录选择 seam
+# Agent Note: web GUI 宿主的能力可辨识目录选择 seam
 
-状态：已实现
+Status: implemented
 
 [English](2026-07-28-directory-picker-capability-seam.md) | 中文
 
 ## 问题
 
-web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入缝）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互契约**，不是同一契约的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
+web GUI 的「打开本地文件夹」流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅用于测试的注入 seam）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是另一种交互约定，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库「一切皆插件」的立场。
 
 ## 决策
 
-在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一契约方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。
+在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一约定方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在*交互形态*——压平成统一方法集会逼每个后端伪装另一方的形态。
 
-**client 侧靠 slot 组合，而非按广播分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 契约相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 广播与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的 wire 事实不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。
+**client 侧靠 slot 组合，而非按声明分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 约定相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 声明与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的协议信息不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。
 
 并入本决策的位置与策略裁决：
 
-- **不用 `ctx.fs` seam。** `packages/fs/` 是面向模型／会话的存储栈（policy 事件、sandbox 可换后端）。骑上去会把 GUI 浏览耦合进模型的限制后端——为模型换 `fs-sandbox` 绝不能改变 GUI 行为——而 OS 事实（home 锚定、隐藏约定）也不是存储原语。picker seam 保持无展示、无模型；`packages/host/` 是它消费方域的家。
-- **依赖调研（手写 vs 引入）。** Node 标准库本身就是维护中的跨平台 OS 层（`readdir(withFileTypes)`、`homedir`、路径语义）；调研过的替代品都过不了依赖门槛——文件管理器包（`node-file-manager`、`files-and-folders`、Syncfusion 的 provider）是整套 HTTP 应用（契合度不过），盘符工具（原生插件 `drivelist`、约七年未更的 `windows-drive-letters`）健康度／比例失当。browse 后端是标准库上的薄适配。
-- **隐藏条目：返回并打标。** 宿主标注 `hidden`（POSIX 点前缀约定）并返回全部条目；客户端过滤。展示策略留在客户端，"显示隐藏"开关正是作为这一纯客户端改动落地：标签固定的 footer 开关，其状态由按下态呈现承载（`aria-pressed` + 勾选符号）；以点开头的路径草稿前缀会显出它所指名的隐藏条目；当前选中项则不受隐藏与前缀两种过滤影响（它锚定着双栏视图）。Windows 的 `FILE_ATTRIBUTE_HIDDEN` 不被 dirent 暴露——记为限制，直到原生探测值回其成本。
-- **路径编辑器的取消范围：对话框卡片。** browse 客户端的路径编辑器在按 Escape 与焦点离开卡片时取消，两者都在卡片范围的包装层而非输入框上监听——Tab 把焦点停到某个过滤命中的行之后，输入框已不在事件路径上，但 Escape 仍须收起编辑器（而非对话框），其后的焦点离开也仍须取消。不取消的豁免：窗口／标签页失焦、卡片内焦点移动，以及指针路径（编辑期间行与开关在 mousedown 时抑制焦点夺取）。预填与草稿末段过滤所用的分隔符从 `listing.home` 推断；下文的线上字段替代方案记录了被延期的权威形态。编辑器与其过滤的列表之间的 combobox 语义（`aria-expanded`／`aria-controls`／active-descendant、结果播报）同样被延期——目前二者在辅助技术看来是彼此独立的控件。
-- **路径编辑器自我点明，各栏跟随草稿。** 点击即编辑的区域不再是隐形的：栏右端坐着一枚铅笔图标，悬停／聚焦时**整条栏**以编辑器自身的那只框亮起——轮廓与内边距在两种模式下都由栏承载，于是悬停预览的正是点击后出现的那只输入框，区域与输入框互换时也没有任何尺寸变化。编辑器打开期间，各栏跟随草稿，而不是停在它打开那一刻恰好列出的层级——末段对其目录部分所指的层级做前缀过滤，无一匹配的末段解除过滤（还在拼写中的名字不该把正在拼写它的那一栏清空），而其余任何目录部分都会在停顿 250ms 后被扫描，并经由每次导航共用的那套以选中项为锚的双栏落地落定，于是键入路径移动 Miller 视图的方式与 crumb 跳转完全一致——继续键入即下潜、删掉末段即上退——全程不必离开编辑器。**分栏个数才是不变量**：最后一栏永远是路径所指的那一层，其上一层在它旁边，只有展示根会独占一栏。"只要任意一栏碰巧列出了该目录就跳过扫描"是更省事、也是错的规则——删掉一段之后，正在键入的那一层会留在左栏，而它自己的子栏仍立在右边，于是两栏不再读作"我在哪儿、我从哪儿来"。只有最后一栏自己的末段不需要扫描。一种落地形态、两个调用方：提交的路径关闭编辑器并呈现失败，草稿跟随扫描则两者都不做。该扫描是推测性的——键入到一半的目录多数时候读不出来——因此失败时保留最后一次可读的分栏并保持沉默。Enter 仍是权威提交：自提交至落地由它独占视图（同一批按键武装的防抖计时器会被扣住，而不是顶掉这次导航；提交被拒后仍扣住，直到下一次编辑），也只有它把失败呈现出来。有两点是刻意为之。等待以草稿为键，而非以它指名的目录部分为键，于是顶掉在飞扫描的那次按键会重新武装等待，被拒提交之后的编辑也能释放那道扣留；而它读取的分栏是 ref 而非依赖，否则落地会重新武装等待，遇到以不同拼写作答的宿主便会永远扫描下去。以及，走过的路不回退：关闭编辑器——包括取消——都把分栏留在草稿带到的地方，由面包屑指明、Open 的兜底目标随之而动，因为操作者亲眼看着它们移动。若落地卸载了键盘操作者 Tab 停留的那一行，焦点会被重新停回编辑器——Modal 并没有焦点陷阱。另有两条规则保证一次按键只让视图移动一次：这段行走会**等齐两程**，而不套用提交导航的等待上限（推测性扫描没有任何东西在等它，先落单栏再升级恰恰就是它要避免的那次闪动，而且一旦末段按键中止了缓慢的父层级这一程，双栏视图就会永久丢失）；末段也只过滤**最后一栏**——去收窄一个草稿已经走开的分栏，会让视图先因收窄动一次、再因它自己的落地动一次。此外，层级会持续应答产生它的那段目录文本（`scanned`），因为宿主会规范化它收到的东西：`..` 段与 Windows 的正斜杠都会抵达一个自身路径拼写不同的层级；没有这份记忆，这类草稿会每敲一键就重扫一次，而且永远过滤不了。
-- **导航以选中项为锚、安静且有界地落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），落地即双栏：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在 200ms 等待上限内落定时，目标与父层级两程以**同一帧**落地——在此之前陈旧视图持续渲染，导航换栏时因此没有中间的单栏闪现——超出该上限则目标即刻单独提交（Enter 提交的导航绝不会被滞塞的父层级扣作人质），迟到的父层级这一程再就地升级这次落地。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会在线上将其中止（因此在落地窗口内按 Escape 即撤回整次导航）；父层级这一程失败，或被截断的父窗口缺少目标时，都保留单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。加载指示器遵循同一安静规则：它浮于内容右下角（绝不是会挪动布局的一行；截断／错误行占据左下角，并在扫描期间持续渲染），且仅在扫描超出 300ms 静默窗口后才出现，因此本地列举切换时什么也不显示。行选取被刻意豁免于同一帧规则：选取后立即分栏本身就是其选中态反馈（aria-current、crumb 跟随），而导航除了换栏本身没有任何东西可确认这次点击。三个时序常量——200ms 父层级上限、300ms 静默窗口，以及编辑器的 250ms 草稿停顿——都按本地列举校准；远程部署（每层级一次 RPC，通常 100–400ms）会落在静默窗口之内、crumb 上却没有按下态，而且要先付停顿再付 RPC 分栏才跟上——待远程消费方落地时，三者一并重新审视。
+- **不用 `ctx.fs` seam。** `packages/fs/` 是面向模型／会话的存储栈（policy 事件、沙箱可换后端）。骑上去会把 GUI 浏览耦合进模型的限制后端——为模型换 `fs-sandbox` 绝不能改变 GUI 行为——而 OS 事实（home 锚定、隐藏约定）也不是存储原语。picker seam 保持无展示、无模型；`packages/host/` 是它消费方域的家。
+- **依赖调研（手写 vs 引入）。** Node 标准库本身就是维护中的跨平台 OS 层（`readdir(withFileTypes)`、`homedir`、路径语义）；调研过的替代品都过不了依赖门槛——文件管理器包（`node-file-manager`、`files-and-folders`、Syncfusion 的提供方）是整套 HTTP 应用（契合度不过），盘符工具（原生插件 `drivelist`、约七年未更的 `windows-drive-letters`）健康度／比例失当。browse 后端是标准库上的薄适配器。
+- **隐藏条目：返回并打标。** 宿主标注 `hidden`（POSIX 点前缀约定）并返回全部条目；客户端过滤。展示策略留在客户端，「显示隐藏」开关正是作为这一纯客户端改动落地：标签固定的 footer 开关，其状态由按下态呈现承载（`aria-pressed` + 勾选符号）；以点开头的路径草稿前缀会显出它所指名的隐藏条目；当前选中项则不受隐藏与前缀两种过滤影响（它锚定着双栏视图）。Windows 的 `FILE_ATTRIBUTE_HIDDEN` 不被 dirent 暴露——记为限制，直到原生探测值回其成本。
+- **路径编辑器的取消范围：对话框卡片。** browse 客户端的路径编辑器在按 Escape 与焦点离开卡片时取消，两者都在卡片范围的包装层而非输入框上监听——Tab 把焦点停到某个过滤命中的行之后，输入框已不在事件路径上，但 Escape 仍须收起编辑器（而非对话框），其后的焦点离开也仍须取消。不取消的豁免：窗口／标签页失焦、卡片内焦点移动，以及指针路径（编辑期间行与开关在 mousedown 时抑制焦点夺取）。预填与草稿末段过滤所用的分隔符从 `listing.home` 推断；下文的协议字段替代方案记录了被延期的权威形态。编辑器与其过滤的列表之间的 combobox 语义（`aria-expanded`／`aria-controls`／active-descendant、结果播报）同样被延期——目前二者在辅助技术看来是彼此独立的控件。
+- **路径编辑器自我点明，各栏跟随草稿。** 点击即编辑的区域不再是隐形的：栏右端坐着一枚铅笔图标，悬停／聚焦时**整条栏**以编辑器自身的那只框亮起——轮廓与内边距在两种模式下都由栏承载，于是悬停预览的正是点击后出现的那只输入框，区域与输入框互换时也没有任何尺寸变化。编辑器打开期间，各栏跟随草稿，而不是停在它打开那一刻恰好列出的层级——末段对其目录部分所指的层级做前缀过滤，无一匹配的末段解除过滤（还在拼写中的名字不该把正在拼写它的那一栏清空），而其余任何目录部分都会在停顿 250ms 后被扫描，并经由每次导航共用的那套以选中项为锚的双栏落地落定，于是键入路径移动 Miller 视图的方式与 crumb 跳转完全一致——继续键入即下潜、删掉末段即上退——全程不必离开编辑器。**分栏个数才是不变量**：最后一栏永远是路径所指的那一层，其上一层在它旁边，只有展示根会独占一栏。「只要任意一栏碰巧列出了该目录就跳过扫描」是更省事、也是错的规则——删掉一段之后，正在键入的那一层会留在左栏，而它自己的子栏仍立在右边，于是两栏不再读作「我在哪儿、我从哪儿来」。只有最后一栏自己的末段不需要扫描。一种落地形态、两个调用方：提交的路径关闭编辑器并呈现失败，草稿跟随扫描则两者都不做。该扫描是推测性的——键入到一半的目录多数时候读不出来——因此失败时保留最后一次可读的分栏并保持沉默。Enter 仍是权威提交：自提交至落地由它独占视图（同一批按键武装的防抖计时器会被扣住，而不是顶掉这次导航；提交被拒后仍扣住，直到下一次编辑），也只有它把失败呈现出来。有两点是刻意为之。等待以草稿为键，而非以它指名的目录部分为键，于是顶掉在飞扫描的那次按键会重新武装等待，被拒提交之后的编辑也能释放那道扣留；而它读取的分栏是 ref 而非依赖，否则落地会重新武装等待，遇到以不同拼写作答的宿主便会永远扫描下去。以及，走过的路不回退：关闭编辑器——包括取消——都把分栏留在草稿带到的地方，由面包屑指明、Open 的兜底目标随之而动，因为操作者亲眼看着它们移动。若落地卸载了键盘操作者 Tab 停留的那一行，焦点会被重新停回编辑器——Modal 并没有焦点陷阱。另有两条规则保证一次按键只让视图移动一次：这段行走会**等齐两程**，而不套用提交导航的等待上限（推测性扫描没有任何东西在等它，先落单栏再升级恰恰就是它要避免的那次闪动，而且一旦末段按键中止了缓慢的父层级这一程，双栏视图就会永久丢失）；末段也只过滤**最后一栏**——去收窄一个草稿已经走开的分栏，会让视图先因收窄动一次、再因它自己的落地动一次。此外，层级会持续应答产生它的那段目录文本（`scanned`），因为宿主会解析它收到的东西：`..` 段与 Windows 的正斜杠都会抵达一个自身路径拼写不同的层级；没有这份记忆，这类草稿会每敲一键就重扫一次，而且永远过滤不了。
+- **导航以选中项为锚、安静且有界地落地。** 在展示根之外（与 crumb 头部渲染的是同一塌缩，因此 crumb 与分栏形态永不相左），落地即双栏：重新选中目标在父层级中的实际条目（Windows 上按平台惯例折叠大小写），右侧展示其子项，因此 crumb 跳转读作后退一栏，而不是塌缩成单列。父层级这一程在 200ms 等待上限内落定时，目标与父层级两程以**同一帧**落地——在此之前陈旧视图持续渲染，导航换栏时因此没有中间的单栏闪现——超出该上限则目标即刻单独提交（Enter 提交的导航绝不会被滞塞的父层级扣作人质），迟到的父层级这一程再就地升级这次落地。父层级这一程在落地的 supersession 范围下运行，任何较新的意图都会通过协议将其中止（因此在落地窗口内按 Escape 即撤回整次导航）；父层级这一程失败，或被截断的父窗口缺少目标时，都保留单栏落地——升级的存在正是为了锚定选中项，绝不能反而让它悬空。加载指示器遵循同一安静规则：它浮于内容右下角（绝不是会挪动布局的一行；截断／错误行占据左下角，并在扫描期间持续渲染），且仅在扫描超出 300ms 静默窗口后才出现，因此本地列举切换时什么也不显示。行选取被刻意豁免于同一帧规则：选取后立即分栏本身就是其选中态反馈（aria-current、crumb 跟随），而导航除了换栏本身没有任何东西可确认这次点击。三个时序常量——200ms 父层级上限、300ms 静默窗口，以及编辑器的 250ms 草稿停顿——都按本地列举校准；远程部署（每层级一次 RPC，通常 100–400ms）会落在静默窗口之内、crumb 上却没有按下态，而且要先付停顿再付 RPC 分栏才跟上——待远程消费方落地时，三者一并重新审视。
 - **符号链接：为可进入性而跟随。** 用 `stat` 探测符号链接（断链／循环→跳过）；面包屑保留操作者导航的逻辑路径，`workspace.create` 在接纳时本就做 realpath 规范化。
-- **列举层级有上限，且流式处理。** 单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端目录列举的同一上限）。层级经 `opendir` 流入一个按名排序、容量 `maxEntries + 1` 的候选窗口，内存保持 O(maxEntries)，可进入性探测只触及窗口内候选；线上 `DirectoryListing` 携带必填的 `truncated` 标志，让客户端明示不完整而不是静默缺尾。窗口内的断链符号链接不从窗口外回填——发生过驱逐本身已把层级标记为截断。窗口插入为二分查找、满窗尾部单次比较即拒绝（超大层级不能为每个 dirent 付出一次全窗扫描），且 `list(path, signal)` 透传载体的请求信号，滞塞网络目录的扫描不会在调用方断连后继续存活——扫描中的每个 await（打开、每次读取、每次符号链接探测）都与信号赛跑，中止路径放弃而非等待 close（Node 会把 close 排在在飞读取之后），被放弃的 settlement 全部吞掉，清理不会以未处理拒绝的形式冒出。无上限的层级对超大或恶意构造的目录就是内存／响应性漏洞。
-- **全盘可浏览，不做 roots 配置。** `workspace.create` 接受任意路径且 API 本就提供驱动 bash 的方法，浏览根只会是 UX 范围而非边界；没有消费方的可配置性过不了证据门槛。等到有部署需要再做。
-- **native 后端保留。** 插件化正是目的：多方都能提供该 seam（Electron 壳可以经自己的对话框 API 提供 `native` 交互）。kind 命名：最初选了 `dialog` 后被放弃——browse 交互同样以对话框呈现（应用内弹窗），这个词起不到判别作用；`native` 命名的是选择器运行的位置。
+- **列举层级有上限，且流式处理。** 单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端目录列举的同一上限）。层级经 `opendir` 流入一个按名排序、容量 `maxEntries + 1` 的候选窗口，内存保持 O(maxEntries)，可进入性探测只触及窗口内候选；协议中的 `DirectoryListing` 携带必填的 `truncated` 标志，让客户端明示不完整而不是静默缺尾。窗口内的断链符号链接不从窗口外回填——发生过驱逐本身已把层级标记为截断。窗口以二分查找确定插入位置、满窗尾部单次比较即拒绝（超大层级不能为每个 dirent 付出一次全窗扫描），且 `list(path, signal)` 透传载体的请求信号，滞塞网络目录的扫描不会在调用方断连后继续存活——扫描中的每个 await（打开、每次读取、每次符号链接探测）都与信号赛跑，中止路径放弃而非等待 close（Node 会把 close 排在在飞读取之后），被放弃的 settlement 全部吞掉，清理不会以未处理拒绝的形式冒出。无上限的层级对超大或恶意构造的目录就是内存／响应性漏洞。
+- **全文件系统范围，不做 roots 配置。** `workspace.create` 接受任意路径且 API 本就提供驱动 bash 的方法，浏览根只会是 UX 范围而非边界；没有消费方的可配置性过不了证据门槛。等到有部署需要再做。
+- **native 后端保留。** 插件化正是目的：多个提供方都能提供该 seam（Electron 壳可以经自己的对话框 API 提供 `native` 交互）。kind 命名：最初选了 `dialog` 后被放弃——browse 交互同样以对话框呈现（应用内弹窗），这个词起不到判别作用；`native` 命名的是选择器运行的位置。
 
 ## 曾考虑的替代方案
 
-- **给 `ctx.fs` 增加浏览方法。** 否决：上述权限域耦合；且面向展示的列举契约（hidden 标志、面包屑、home 锚点）不属于存储 seam。
-- **统一方法集的 seam（`pick(): path`）。** 否决：应用内浏览器无法藏在一次宿主侧调用后面——浏览循环在客户端，需要协议上的原语；而对话框实现不了原语。交互差异不可约，故用判别标签。
-- **apiproxy 里直接调标准库（不建 seam）。** 否决：换装点仍是改网关源码，失去 fixture／测试后端，与促成这项工作的插件教义相悖。
+- **给 `ctx.fs` 增加浏览方法。** 否决：上述权限域耦合；且面向展示的列举约定（hidden 标志、面包屑、home 锚点）不属于存储 seam。
+- **统一方法集的 seam（`pick(): path`）。** 否决：应用内浏览器无法藏在一次宿主侧调用后面——浏览循环在客户端，需要协议上的原语；而原生选择器无法实现这些原语。交互差异不可约，故用判别标签。
+- **apiproxy 里直接调标准库（不建 seam）。** 否决：换装点仍是改网关源码，失去 fixture（测试前置数据）／测试后端，与促成这项工作的插件教义相悖。
 - **引入文件管理器／盘符枚举依赖。** 按上文调研否决；依赖政策要求记录于此。
-- **动作标签随状态翻转的"显示隐藏"开关（"隐藏隐藏文件"）。** 否决：会翻转的动作标签在状态与动作之间有歧义，还把否定叠了两层；固定标签加按下态呈现一次说清两者。
+- **动作标签随状态翻转的「显示隐藏」开关（「隐藏隐藏文件」）。** 否决：会翻转的动作标签在状态与动作之间有歧义，还把否定叠了两层；固定标签加按下态呈现一次说清两者。
 - **纯 relatedTarget 失焦取消（不做 mousedown 抑制）。** 否决：Safari 在指针按下时不给按钮聚焦，点击触发的 focusout 因而携带空 `relatedTarget`，会在点击落地前就取消编辑器；编辑期作用的 mousedown 抑制加上锚定卡片的 relatedTarget 守卫才能同时覆盖指针与键盘路径。
-- **在 Miller 视图上方常驻一个路径输入框。** 否决：面包屑本就在回答"我在哪儿"，再常驻一个字段是重复回答，还要从 500px 卡片里挪走一行——那是列需要的高度。图标加悬停亮起的区域，把这个入口放在了已经回答该问题的那一栏上。
-- **每敲一个键就扫描草稿，或只在 Enter 时扫描。** 每键扫描：走完一段路径就是每个字符一次列举，其中多数目录操作者只是路过而非停留。只在 Enter 时扫描（最初落地的行为）：整个编辑过程中各栏与所键入文本各说各话——正是本条所回应的抱怨。250ms 的停顿把扫描收敛为"键入真正停下来的每个目录一次"。
-- **前缀无一匹配时清空该栏（最初落地的行为）。** 否决：名字敲到一半时"无匹配"才是常态，于是恰恰在操作者需要它确认名字时把栏清空了；解除过滤保住了层级的可读性，代价只是短暂的宽松。
-- **在 `DirectoryListing` 上增设线上 `separator` 字段（宿主标注 `path.sep`）。** 延期而非否决：它才是权威形态——含反斜杠的 POSIX 家目录会击穿 `listing.home` 启发式——但它触及 seam 类型与每个后端；browse 客户端的 `separatorOf` 挂着指向本方案的 TODO，直到下次安排线上变更。
+- **在 Miller 视图上方常驻一个路径输入框。** 否决：面包屑本就在回答「我在哪儿」，再常驻一个字段是重复回答，还要从 500px 卡片里挪走一行——那是列需要的高度。图标加悬停亮起的区域，把这个入口放在了已经回答该问题的那一栏上。
+- **每敲一个键就扫描草稿，或只在 Enter 时扫描。** 每键扫描：走完一段路径就是每个字符一次列举，其中多数次列举针对的目录，操作者只是在键入时经过，并未停驻。只在 Enter 时扫描（最初落地的行为）：整个编辑过程中各栏与所键入文本各说各话——正是本条所回应的抱怨。250ms 的停顿把扫描收敛为「键入真正停下来的每个目录一次」。
+- **前缀无一匹配时清空该栏（最初落地的行为）。** 否决：名字敲到一半时「无匹配」才是常态，于是恰恰在操作者需要它确认名字时把栏清空了；解除过滤保住了层级的可读性，代价只是短暂的宽松。
+- **在 `DirectoryListing` 上增设 `separator` 协议字段（宿主标注 `path.sep`）。** 延期而非否决：它才是权威形态——含反斜杠的 POSIX 家目录会击穿 `listing.home` 启发式——但它触及 seam 类型与每个后端；browse 客户端的 `separatorOf` 挂着指向本方案的 TODO，直到下次安排协议变更。
 
 ## 后果
 
 - `cordis.yml` 决定交互形态；`apps/cli` 挂 [`-auto` 选择器](../feature/2026-07-29-directory-picker-adaptive-default.md)，它在启动时判定宿主处境并自行挂载 `-native` 或 `-browse`，一行仍同时切换后端与 UI；直接组合某个后端行即固定交互。
 - 协议新增 `host.listDirectory`／`host.createDirectory` 与四个错误码；connection fixture 提供确定性浏览树与确定性 `pickDirectory` 路径供无密钥组装测试使用。
-- 未来的新交互（或提供 `native` 交互的 Electron 实现）只是一个双面后端包——无需网关手术，也不动 ui-workspace。
+- 未来的新交互（或提供 `native` 交互的 Electron 提供方）只是一个双面后端包——无需网关手术，也不动 ui-workspace。
 - `ApiProxyDefaults.pickDirectory`（仅测试注入）删除；测试像提供其他服务一样提供 stub `ctx.directoryPicker`。
diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml
index 2bef24442d..dba9bcbee1 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md
 2026-07-29-terminal-llm-stream-failures.md: 1e26973360f07c212016c6a44103448a3510a75b
-2026-07-29-terminal-llm-stream-failures.zh.md: d3eeb0534f6cb8d4d1ad167cca089314eb02b513
+2026-07-29-terminal-llm-stream-failures.zh.md: f4fd4e0e2a555d87394aa43d8b3a9712ee369eb2
diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
index d3eeb0534f..f4fd4e0e2a 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
@@ -4,34 +4,34 @@ Status: implemented
 
 [English](2026-07-29-terminal-llm-stream-failures.md) | 中文
 
-本说明仅取代[有界 LLM 请求恢复](2026-06-21-bounded-llm-request-recovery.md)与[调用后上下文溢出恢复](2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)中关于抛出错误身份和调用局部 sidecar 的机制。上述说明继续规定结构化失败事实、重试策略、持久尝试与压缩恢复。
+本说明仅取代[有界 LLM（大语言模型）请求恢复](2026-06-21-bounded-llm-request-recovery.md)与[调用后上下文溢出恢复](2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)中关于抛出错误身份和调用局部 sidecar 的机制。上述说明继续规定结构化失败事实、重试策略、持久尝试与压缩（compaction）恢复。
 
 ## Problem
 
-适配器失败曾有两种公共表示：选择、分发、iterator 构造或迭代抛出的异常，以及带内的 `finish { kind: 'error' | 'aborted' }`。`LlmService` 会在以 stream 为 key 的 sidecar 中标记抛出对象，使 agent loop 能将其与 middleware 和消费方失败区分开。消费方仍需用 catch 包围迭代、signal 检查、chunk 日志记录和组装；正确性因此取决于证明是哪条语句抛错，并查询附着于精确返回 iterable 的元数据。
+适配器失败曾有两种公共表示：选择、分发、iterator 构造或迭代抛出的异常，以及带内的 `finish { kind: 'error' | 'aborted' }`。`LlmService` 会在以流为键的 sidecar 中标记抛出对象，使 agent loop（智能体循环）能将其与 middleware 和消费方失败区分开。消费方仍需用 catch 包围迭代、signal 检查、分片日志记录和组装；正确性因此取决于证明是哪条语句抛错，并查询附着于所返回的那个 iterable 的元数据。
 
-重试策略也采用同样的间接归属。尽管 `prepareCall()` 已捕获服务注册，策略仍要在分发后通过 stream sidecar 查找。因此，由 wrapper 提供服务的路由与由适配器提供服务的路由共用一个不透明查询 API，尽管两者的权威不同。
+重试策略也采用同样的间接归属。尽管 `prepareCall()` 已捕获服务注册，策略仍要在分发后通过流 sidecar 查找。因此，由包装层提供服务的路由与由适配器提供服务的路由共用一个不透明查询 API，尽管两者的权威不同。
 
 ## Decision
 
-`LlmService` 是一次适配器尝试的规范化边界。它只捕获最终适配器选择、同步分发、iterator 构造与 `next()` 失败，将抛出值转换为不可变 `LlmFailure`，并发出一个终止 `finish`。调用方取消或 `ABORTED` 失败选择 aborted reason；其他适配器失败选择 error。适配器也可以直接发出这两种终止 reason。
+`LlmService` 是一次适配器尝试的规范化边界。它只捕获最终适配器选择、同步分发、iterator 构造与 `next()` 失败，将抛出值转换为不可变 `LlmFailure`，并发出一个终止 `finish`。调用方取消或 `ABORTED` 失败选择 aborted 结束原因；其他适配器失败选择 error 结束原因。适配器也可以直接发出任一终止原因。
 
-适配器所属的 catch 会在每个 chunk 被 yield 前结束。来自 `llm/stream` middleware、嵌套调用、适配器清理、chunk 消费方、日志记录、signal 检查与组装的错误仍作为缺陷或生命周期失败抛出；它们绝不进入模型请求恢复。部分 delta 之后的传输失败可能留下未关闭块，因此流 invariant 只允许终止 error 或 aborted finish 带有未关闭块。不会从这些不完整输出组装 assistant 消息或工具调用。
+适配器所属的 catch 会在每个分片被 yield 前结束。来自 `llm/stream` middleware、嵌套调用、适配器清理、分片消费方、日志记录、signal 检查与组装的错误仍作为缺陷或生命周期失败抛出；它们绝不进入模型请求恢复。部分 delta 之后的传输失败可能留下未关闭块，因此流 invariant 只允许在终止 finish 的结束原因为 error 或 aborted 时存在未关闭块。不会从这些不完整输出组装 assistant 消息或工具调用。
 
 `PreparedLlmCall` 公开随其配置和注册捕获的不可变重试策略。一次性句柄复用与配置不匹配仍是同步的 `INVALID_PREPARED_CALL` 误用错误。完全由 `llm/stream` middleware 提供服务的路由没有准备完成的注册，因此也没有服务策略。
 
-agent loop 只消费一种失败表示。它不再使用分类 catch，而是直接迭代并记录 chunk、检查终止 finish，再把其中的失败事实与准备完成的策略传给 `agent/request-error`。公共的 `isLlmAdapterFailure`、`llmFailureOf` 和 `llmRetryPolicyOf` sidecar API 不再存在。
+agent loop 只消费一种失败表示。它不再使用分类 catch，而是直接迭代并记录分片、检查终止 finish，再把其中的失败事实与准备完成的策略传给 `agent/request-error`。公共的 `isLlmAdapterFailure`、`llmFailureOf` 和 `llmRetryPolicyOf` sidecar API 不再存在。
 
 ## Alternatives considered
 
-**保留调用局部错误标记。** 这会保留抛出对象身份，但要求每个消费方捕获一段包含自身易失败工作的区域，并让分类依赖 iterable wrapper 的身份。原始错误对象在持久恢复中没有作用；规范化事实才是有用的边界值。
+**保留调用局部错误标记。** 这会保留抛出对象身份，但要求每个消费方捕获一段包含自身易失败工作的区域，并让分类依赖 iterable 包装层的身份。原始错误对象无法在恢复中发挥持久作用；规范化事实才是有用的边界值。
 
-**要求所有适配器发出失败 chunk，并禁止抛出。** 库 iterator、transport 与 JavaScript 分发仍可能抛错。要求每个适配器复制同一 catch 边界会重复归属，也无法保护 `LlmService` 的直接消费方免受不完整实现影响。
+**要求所有适配器发出失败分片，并禁止抛出。** 库 iterator、transport 与 JavaScript 分发仍可能抛错。要求每个适配器复制同一 catch 边界会造成职责重复，也无法保护 `LlmService` 的直接消费方免受不完整实现影响。
 
-**在 agent loop 中捕获所有迭代错误。** 如果不恢复同一套 sidecar 溯源机制，loop 无法可靠区分提供方失败与 middleware、session append、取消或组装失败。分类属于发起适配器调用的边界。
+**在 agent loop 中捕获所有迭代错误。** 如果不恢复同一套 sidecar 溯源机制，loop 无法可靠区分提供方失败与 middleware、会话追加、取消或组装失败。分类属于发起适配器调用的边界。
 
 **在流式输出前返回 `Result`。** 流前结果无法表示部分输出之后的传输失败，除非增加第二套响应生命周期。现有终止 chunk 已能表示早期和后期尝试结果。
 
 ## Consequences
 
-所有 `LlmService.stream()` 消费方都通过一种带类型的终止协议接收适配器运行失败，而编程与生命周期失败保留普通异常语义。恢复放弃精确抛出对象身份，只暴露与原对象分离的提供方无关事实。流服务承担略多的适配器管道工作，但消费方删除了溯源 catch 与以 stream 为 key 的元数据。准备完成的调用显式携带策略，而仅由 middleware 路由的调用仍明确没有策略。
+所有 `LlmService.stream()` 消费方都通过一种带类型的终止协议接收适配器运行失败，而编程与生命周期失败保留普通异常语义。恢复放弃精确抛出对象身份，只暴露与原对象分离的提供方无关事实。流服务承担略多的适配器管道工作，但消费方删除了溯源 catch 与以流为键的元数据。准备完成的调用显式携带策略，而仅由 middleware 提供服务的路由仍明确没有策略。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml
index 752dc0f1aa..5c0849d9f6 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md
 2026-07-30-adapter-owned-max-token-defaults.md: a522848fd4482f84859e587505b6a5e6f5c72d60
-2026-07-30-adapter-owned-max-token-defaults.zh.md: 8db6a06199fc1c4e73c86492d12dc86edafe8c7e
+2026-07-30-adapter-owned-max-token-defaults.zh.md: 5d5b4007d124028f1703fb34a7b50815cbc0a99a
diff --git a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
index 8db6a06199..5d5b4007d1 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
@@ -10,7 +10,7 @@ LLM（大语言模型）适配器可以序列化显式的 `GenerateOptions.maxTo
 
 ## Decision
 
-`LlmResolvedModelInfo.defaultMaxTokens` 携带一条确切提供方／模型路由的可选单次请求输出上限，该值由适配器配置。`LlmService` 将其校验为正安全整数，并且仅在调用方省略值时才填入 `LlmCallConfig.maxTokens`。准备后的调用会将已填入的 `maxTokens` 和 `reasoningEffort` 字段标记为适配器默认值；显式请求值或 Agent 选项不带该标记，因此优先且不会被自动调整。
+`LlmResolvedModelInfo.defaultMaxTokens` 携带一条确切提供方／模型路由的可选单次请求输出上限，该值由适配器配置。`LlmService` 将其校验为正的安全整数，并且仅在调用方省略值时才填入 `LlmCallConfig.maxTokens`。准备后的调用会将已填入的 `maxTokens` 和 `reasoningEffort` 字段标记为适配器默认值；显式请求值或 agent 选项不带该标记，因此优先且不会被自动调整。
 
 agent loop 仍在记录 `request/header` 前准备调用，因此生效配置及其适配器默认值来源会在分派前成为持久请求事实。下一次 `agent/request` waterfall（瀑布式事件）前，agent loop 会从提议中移除带标记字段，随后精确模型解析会再次填入当前路由的默认值。因此，切换提供方／模型不会把前一个适配器的默认值误当成显式覆盖，而显式对话值则会保留。直接调用 `LlmService.stream()` 时，也会在最终适配器边界解析同一默认值。该字段是请求默认值，而非模型输出硬上限；保留提供方持有默认值的适配器会省略它。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.i18n.yaml
index 2efe235e28..7254478110 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.md
 2026-07-30-client-locale-full-rollout.md: 09baf5876029295f7a80b6a0fe6a6395d98f406c
-2026-07-30-client-locale-full-rollout.zh.md: 806916aea15a21fd24fdfc4654976b3c4577a675
+2026-07-30-client-locale-full-rollout.zh.md: a2f9b619be9928a713d5dbf527d7c2278e84bd1f
diff --git a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.zh.md b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.zh.md
index 806916aea1..a2f9b619be 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-client-locale-full-rollout.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-typed locale 标准席位（`locale:` 注册声明 → 框架注入强类型 `t`）落地后，只有四个先行包接入；其余 client 包的文案仍是硬编码的中英混杂字面量。全量迁移需要几个先行包没有触及的机制与边界决定：注册期文本（导航行、视图 tab 的 label）在语言切换时如何刷新；zero-cordis 的 ui-primitives 原子组件如何拿到文案；哪些字符串**刻意不**本地化——没有记录的边界会诱使后来者"补完"翻译。
+typed locale 标准席位（`locale:` 注册声明 → 框架注入强类型 `t`）落地后，只有四个先行包接入；其余 client 包的文案仍是硬编码的中英混杂字面量。全量迁移需要几个先行包没有触及的机制与边界决定：注册期文本（导航行、视图 tab 的 label）在语言切换时如何刷新；zero-cordis 的 ui-primitives 原子组件如何拿到文案；哪些字符串**刻意不**本地化——没有记录的边界会诱使未来的 agent（智能体）「补完」翻译。
 
 ## Decision
 
@@ -14,32 +14,32 @@ typed locale 标准席位（`locale:` 注册声明 → 框架注入强类型 `t`
 
 **组件文案走标准 `t` 席位；深层子组件用 prop 下传**，类型写 `XxxProps['t']`。字典规范形态不变：`zh satisfies Record<string, string>` 为 key 源、`en satisfies Record<XxxKey, string>` 锁双语平衡。
 
-**zero-cordis 原子组件（ui-primitives）文案 props 化**：`HoverCard` 的 `copyLabel`/`copiedLabel`、`TerminalBlock`/`JsonTree` 的 `labels`、`CodeBlock` 的 `copyLabel`/`copiedLabel`、`MarkdownText` 的 `codeLabels`、`JsonBlock` 的 `truncatedLabel`、`ConnectionBanner` 的 `label`、`Modal` 的 `closeLabel`——默认值即原硬编码字符串，不传 props 的消费者渲染逐字节不变。已本地化的插件从自己的 `t` 席位传字典驱动的 label；传对象 props 的调用点按 `t` 身份 memo（`MarkdownText` 的组件表按 `codeLabels` 身份缓存）。
+**zero-cordis 原子组件（ui-primitives）文案 props 化**：`HoverCard` 的 `copyLabel`/`copiedLabel`、`TerminalBlock`/`JsonTree` 的 `labels`、`CodeBlock` 的 `copyLabel`/`copiedLabel`、`MarkdownText` 的 `codeLabels`、`JsonBlock` 的 `truncatedLabel`、`ConnectionBanner` 的 `label`、`Modal` 的 `closeLabel`——默认值即原硬编码字符串，不传 props 的消费方渲染逐字节不变。已本地化的插件从自己的 `t` 席位传字典驱动的 label；传对象 props 的调用点按 `t` 身份 memo（`MarkdownText` 的组件表按 `codeLabels` 身份缓存）。
 
 **不翻译边界（刻意决定，不是欠账）：**
 
-- **错误/失败类字符串一律英文**：client 自产的兜底串（`command failed`、plan 切换失败）、RpcError message、wire 透出的 `error.message (code)` 原样呈现。
-- **设计字面量不进字典**：tool 行 variant 标题（Think/Bash/…）、SYSTEM/USER 类 kind 徽标、Plan chip 字标、StatsLine 全部指标——中英界面显示一致。
+- **错误/失败类字符串一律英文**：client 自产的兜底串（`command failed`、plan 切换失败）、RpcError 消息、wire 透出的 `error.message (code)` 原样呈现。
+- **设计字面量不进字典**：工具行 variant 标题（Think/Bash/…）、SYSTEM/USER 类 kind 徽标、Plan chip 字标、整个 StatsLine——中英界面显示一致。
 - **ui-trajectory 整包缓做**（开发者检查面，术语密集，单独裁决）。
 - **boot 文案保持硬编码**（AppRoot 渲染早于 locale 服务可用）。
 
 **派生层保持纯函数，本地化只在渲染层**：ui-workspace 的 `relativeTime` 返回结构化 `{unit, n}` 由渲染组合字典模板；blank 会话/未分组桶的存储标题不变，渲染按 `blank` 标志/`workspaceId` 缺席替换本地化文案；**搜索态 blank 行一律排除**（双语标题无法与单语查询稳定匹配）。日期不引 Intl：格式模板进字典（消息时钟 `clock.md`/`clock.ymd`，workspace hover `date.ymd`），格式化函数吃 `t` 参数保持纯。
 
-**测试与 e2e 口径**：`makeTranslate(...dicts)`（dsh-client-test-runtime）镜像服务查找链（首个命中字典胜出、key 兜底、`{name}` 插值），组件测试的 `t` 桩统一用它并以真实 props 席位定型。web e2e 统一 `newEnglishPage`（boot 前钉 `dsh.locale=en`），built-boot snapshot 同样钉 en——golden 对语言迁移免疫；settings 语言切换用例绕开该 helper 并开启 `zh-CN` 浏览器，因为初始 locale 跟随 `navigator`（[由浏览器推导初始 locale](../feature/2026-07-31-browser-derived-initial-locale.md)）。
+**测试与 e2e 口径**：`makeTranslate(...dicts)`（dsh-client-test-runtime）镜像服务查找链（首个命中字典胜出、key 兜底、`{name}` 插值），组件测试的 `t` 桩统一用它并以真实 props 席位定型。web e2e 统一通过 `newEnglishPage` 打开（boot 前钉 `dsh.locale=en`），built-boot 快照同样钉 en——预期输出不受本地化迁移影响；settings 语言切换用例绕开该 helper 并开启 `zh-CN` 浏览器，因为初始 locale 跟随 `navigator`（[由浏览器推导初始 locale](../feature/2026-07-31-browser-derived-initial-locale.md)）。
 
-[settings/locale/theme 分层 Note](../../proposed/architecture/2026-07-25-client-settings-locale-theme.md) 中"apply 层订阅 `locale/change` 重注册刷新 label"的机制已被本决定取代（thunk + revision 生命周期）。
+[settings/locale/theme 分层 Note](../../proposed/architecture/2026-07-25-client-settings-locale-theme.md) 中「apply 层订阅 `locale/change` 重注册刷新 label」的机制已被本决定取代（thunk + revision 生命周期）。
 
 ## Alternatives considered
 
-- **label 保持 string、语言切换时重注册**（先行包的旧形态）：boot 每包一次注册已很重，`locale/change` 监听者重注册会放大成风暴；ledger version 抖动还会击穿一切按 version 缓存的投影。thunk 把刷新成本移到读取点，读取点本来就跟随 revision。
-- **给 ui-primitives 造 locale context/注入通道**：破坏 zero-cordis 边界（原子组件从此依赖运行时），且强迫未本地化消费者（ui-trajectory）陪跑。props 化让每个消费者独立决定。
+- **label 保持 string、语言切换时重注册**（先行包的旧形态）：boot 已经为每个包注册一次，`locale/change` 监听者重注册会放大成风暴；ledger version 抖动还会击穿一切按 version 缓存的投影。thunk 把刷新成本移到读取点，读取点本来就跟随 revision。
+- **给 ui-primitives 造 locale 上下文/注入通道**：破坏 zero-cordis 边界（原子组件从此依赖运行时），且强迫未本地化消费方（ui-trajectory）陪跑。props 化让每个消费方独立决定。
 - **错误串进字典**：错误面是排障面，英文原样最利于搜索与上报比对；且 wire 透出串本就不可译，半译反而制造混合语言。
 - **日期用 `toLocaleString()`/Intl**：跟随浏览器/OS 语言而非应用语言，切换后必然产生混合文本；字典模板量小且与消息时钟同构。
-- **blank 行参与搜索（匹配本地化标题或存储标题）**：任一选择都在某个语言下"看得见搜不到"；占位行本无信息量，整体排除语义最稳。
+- **blank 行参与搜索（匹配本地化标题或存储标题）**：任一选择都在某个语言下「看得见搜不到」；占位行本无信息量，整体排除语义最稳。
 
 ## Consequences
 
 - 语言切换全 UI 即时刷新且零重注册；新包接入 = 字典 + declare-merge + `locale: NS` 三步，无手写胶水。
-- 代价：list label 的消费方必须知道 `resolveSlotLabel`（裸读 `options.label` 拿到函数）；类型上 `SlotLabel` 已挡住多数误用。
-- ui-primitives 的中文默认值在英文语言下依旧是中文，**直到消费点传 label**——未迁移包（ui-trajectory 的 JsonTree）显示英文默认恰好符合其整包英文现状。
+- 代价：list label 的消费方必须知道 `resolveSlotLabel`（裸读 `options.label` 现在可能拿到函数）；类型上 `SlotLabel` 已挡住多数误用。
+- ui-primitives 的中文默认值在英文语言下依旧是中文，**直到消费方传入 labels**——未迁移的 JsonTree 消费方（ui-trajectory）显示其英文默认值，恰好符合其整包英文现状。
 - e2e 英文钉死意味着 zh 默认态主要靠包级组件测试与 settings 语言切换用例覆盖，浏览器 e2e 不再验证 zh 文案。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.i18n.yaml
index 330a279b35..3b769c20db 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.md
 2026-07-30-command-row-copy-contract.md: f6d5199389b3907780c501894e2861e6add85e77
-2026-07-30-command-row-copy-contract.zh.md: 4afaf31640c07e88765060681739f262f322769e
+2026-07-30-command-row-copy-contract.zh.md: 250c8090e357c02b68bdf9b75efac0cd163c6343
diff --git a/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.zh.md b/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.zh.md
index 4afaf31640..250c8090e3 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-command-row-copy-contract.zh.md
@@ -1,16 +1,16 @@
-# Agent Note: Command row copy is split between the row and the handler
+# Agent Note: 命令条目文案分别由条目与 handler 负责
 
 Status: implemented
 
 [English](2026-07-30-command-row-copy-contract.md) | 中文
 
-## Problem
+## 问题
 
-Web 命令行由一对落库的[命令生命周期事件](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md)渲染出 `标题 · 摘要`：标题是由 `command/run` 重建的分派命令行（`/permission workspace-write`），摘要是 `command/done` 的原样 `text`（`Permission preset: workspace-write.`）。两半各自成文、互不知情，于是一行里命令名出现两次、参数也出现两次——最糟的一例正是用户每次用 Access chip 切换权限时得到的那一行。
+Web 命令条目由一对落库的[命令生命周期事件](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md)渲染出 `标题 · 摘要`：标题是由 `command/run` 重建的分派命令行（`/permission workspace-write`），摘要是 `command/done` 的原样 `text`（`Permission preset: workspace-write.`）。两半各自成文、互不知情，于是一行里命令名出现两次、参数也出现两次——最糟的一例正是用户每次用 Access chip 切换权限时得到的那一行。
 
-## Decision
+## 决策
 
-命令行两半的职责互不重叠，各自只按自己那一半来写。
+命令条目两半的职责互不重叠，各自只按自己那一半来写。
 
 行标题就是裸命令名——没有 `/`，也没有参数。`/` 属于编辑器的输入语法，不属于一条已落定的记录；参数也不该由这一行来报告：摘要已经说清了这条命令做了什么。对于 `command/run` 那一页已滑出客户端窗口的跨窗口节点，`GenericCommandCard` 仍保留 `命令` 兜底标题。
 
@@ -18,9 +18,9 @@ Web 命令行由一对落库的[命令生命周期事件](../../proposed/archite
 
 这条规则禁的是*标签*，不是用词。`Permission preset: workspace-write.` 之所以出局，是因为 `Permission preset:` 是给一个值加的题头，而这个题头正是标题本身。恰好含有命令名的领域名词不是题头，因此保留：`/plan` 仍返回 `Plan mode off.` 与 `Plan mode on. Use /plan off to leave.`（`plan · Plan mode off.` 说的是那个模式，句尾是一条指引，不是回声），`/goal` 仍返回 `Goal cleared.`。真正被这条规则拦下的，是 handler 在自己的值前面写出 `<命令名> <名词>：` 的那一类。
 
-日志本身未变：`command/run` 保留结构化的 `name`／`args` 拆分，因此更丰富的已注册命令行仍可从同一个节点渲染参数，无需第二条数据通道。
+日志本身未变：`command/run` 保留结构化的 `name`／`args` 拆分，因此更丰富的已注册命令条目仍可从同一个节点渲染参数，无需第二条数据通道。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **保留分派命令行作标题，只缩短落定文案。** 参数仍会出现在分隔点两侧（`permission workspace-write · preset workspace-write`），而这正是被指出的重复。
 
@@ -28,8 +28,8 @@ Web 命令行由一对落库的[命令生命周期事件](../../proposed/archite
 
 **由这一行从落定文案里剥掉开头的命令名。** 呈现层会悄悄改写 handler 写就的文案，而任何换一种措辞表达结果的 handler 都会让这套启发式失效。
 
-**彻底禁止命令名出现在自己的落定文案里，并把 `/plan`、`/goal` 一并改写。** 这种更宽的禁令代价大于收益：无论在行上还是作为独立的 TUI 通知，`Plan mode off.` 与 `Goal cleared.` 都是这些结果最清楚的句子，而满足"禁名字"所需的缩写（`off.`、`cleared.`）读起来只是残句。值得去掉的冗余是题头。
+**彻底禁止命令名出现在自己的落定文案里，并把 `/plan`、`/goal` 一并改写。** 这种更宽的禁令代价大于收益：无论在行上还是作为独立的 TUI 通知，`Plan mode off.` 与 `Goal cleared.` 都是这些结果最清楚的句子，而满足「禁名字」所需的缩短形式（`off.`、`cleared.`）读起来只是残句。值得去掉的冗余是题头。
 
-## Consequences
+## 后果
 
-每一条命令行都变短了，而且这条规则可扩展：新命令的作者写结果时无需知道由哪个界面渲染，任何界面也都不必再去重。代价是分派参数离开了折叠行——命令仍在执行时，行上只有名字和 `执行中…`——以及"不加题头"这条规则是靠评审执行的约定，而非门禁。`/permission` 的文案由 permission 包的命令测试钉住，装配后的行文案由 [seeded-history](../../../../apps/web/tests/snapshots/seeded-history/command-row.expected.md) web 预期输出钉住：因为 `/permission` 完全在 host 上执行，它能无密钥地抵达一条真实的落定命令行。
+每一条命令条目都变短了，而且这条规则可扩展：新命令的作者写结果时无需知道由哪个界面渲染，任何界面也都不必再去重。代价是分派参数离开了折叠行——命令仍在执行时，行上只有名字和 `执行中…`——以及「不加题头」这条规则是靠评审执行的约定，而非门禁。`/permission` 的文案由 permission 包的命令测试钉住，装配后的行文案由 [seeded-history](../../../../apps/web/tests/snapshots/seeded-history/command-row.expected.md) web 预期输出钉住：由于 `/permission` 完全在 host 上执行，该预期输出无需密钥即可覆盖一条真实的已落定命令条目。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
index 2b16888d38..b4863f08b5 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
 2026-07-30-followup-enqueue-and-owned-runs.md: 54f4af75eeb29b06504fa2629b0665f3e5f4c4ee
-2026-07-30-followup-enqueue-and-owned-runs.zh.md: 62c0d998a8bf94df8cabfccf23ea8b2a4da92c4d
+2026-07-30-followup-enqueue-and-owned-runs.zh.md: 51f82b7c703be13165e0cd7d7b354ea14e3a965e
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
index 62c0d998a8..51f82b7c70 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
@@ -14,11 +14,11 @@ Status: implemented
 
 保留 `Agent.followup(message): void`，使其仅执行入队。`Agent.whenIdle()` 和 `agent/status` 仍用于观察整个 agent 的生命周期；二者都不结算单条消息。Inbox 持久性会记录已标识消息及其准入或取消，但不会把后续输出归属于该消息。
 
-底层 SDK 协议在入队成功后立即以 `{ messageId }` 响应 `session/prompt`。它通过 `session.event` 传输持久事实，通过 `session.status` 发布整个 agent 的状态转换，且不包含 `session.finished`。底层客户端可以观察该回执和之后的 idle，但不会收到提示词结果。
+底层 SDK 协议在入队成功后立即以 `{ messageId }` 响应 `session/prompt`。它通过 `session.event` 流式传输持久事实，通过 `session.status` 发布整个 agent 的状态转换，且不包含 `session.finished`。底层客户端可以观察该回执和之后的 idle，但不会收到提示词结果。
 
 只有明确拥有一个活动区间时，高层自动化 API 才返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其 `finalResponse` 是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行可以报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。
 
-ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，其他情况均报告通用的 `end_turn`。token 上限的轮次结束不归因于提示词：它们以 `end_turn` 结算。与该提示词关联的轮次上的模型错误会立即以该错误 reject 提示词（错误按其所属轮次归因），而 turnless 槽位（准入已丢弃提示词）会在 idle 时以 `cancelled` 结算，与显式 ACP 取消或资源释放并列。
+ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，其他情况均报告通用的 `end_turn`。token 上限的轮次结束不归因于提示词：它们以 `end_turn` 结算。与该提示词关联的轮次上的模型错误会立即以该错误拒绝提示词（错误按其所属轮次归因），而 turnless 槽位（准入已丢弃提示词）会在 idle 时以 `cancelled` 结算，与显式 ACP 取消或dispose（资源释放）并列。
 
 Goal 续行只保留 `MessageId`，用于识别持久排队和已准入的 goal 消息。它在整个 agent 进入 idle 时根据持久 goal 状态推进，不把消息映射到轮次结果。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
index e556108299..53eb3cefe5 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
 2026-07-30-package-manager-native-repository-cache.md: 0ea145f20a58e4e3e9feb7ba5574818c0352e2c4
-2026-07-30-package-manager-native-repository-cache.zh.md: ac72e5dc4ffa764e1dc430764a6f52fc083d32a4
+2026-07-30-package-manager-native-repository-cache.zh.md: a4ad07c42eec7b05f51b18aaf54fcfedaa4d4b3c
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
index ac72e5dc4f..a4ad07c42e 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-独立运行的 Harness 应用不能依赖开发者自有的 SDK 工程来声明并安装仓库依赖。因此，加载配置中的 GitHub 仓库需要一道持久的获取、准备与缓存边界；但如果在 DSH 内实现 Git 传输、托管来源语法、包（package）准备流程和内容存储，就会重复实现包管理器。若要求用户另行安装包管理器，则只需修改配置即可使用的功能还会依赖宿主环境的额外配置。
+独立运行的 Harness 应用不能依赖开发者自有的 SDK 工程来声明并安装仓库依赖。因此，加载配置中的 GitHub 仓库需要一道持久的获取、准备与缓存边界；但如果在 DSH 内实现 Git 传输、托管来源语法、包准备流程和内容存储，就会重复实现包管理器。若要求用户另行安装包管理器，则只需修改配置即可使用的功能还会依赖宿主环境的额外配置。
 
 缓存还需要明确更新标识。若没有独立的刷新协议，可变分支名无法既永久缓存，又反映后续 commit。
 
@@ -16,7 +16,7 @@ vendor 中的 `@cordisjs/plugin-loader/repository` 导出 `RepositoryCache`：
 
 Loader 将 `pnpm@11.7.0` 作为固定版本的运行时依赖，并使用当前 Node 可执行文件调用该包的 JavaScript 入口。它绝不探测全局可执行文件，也不经 Corepack 调用。每次缓存未命中都会创建一个隔离工程，其中只有一个名为 `repository` 的依赖；Git 与 GitHub 来源的解析和获取、pnpm 自身的内容寻址 store、依赖安装，以及仓库依赖图中的生命周期脚本均由 pnpm 负责。
 
-隔离工作区设置 `dangerouslyAllowAllBuilds: true`。用户配置的仓库及其依赖图都属于受信任的可执行代码：DSH 读取任何已声明资产之前，生命周期脚本就可能运行。子进程会收到 Git 与 pnpm 所需的常规宿主进程状态，但会移除环境中名称形似凭据（`KEY`、`PASSWORD`、`SECRET`、`TOKEN`）的变量。该机制不新增 OAuth、token 转发或私有仓库认证契约。
+隔离工作区设置 `dangerouslyAllowAllBuilds: true`。用户配置的仓库及其依赖图都属于受信任的可执行代码：DSH 读取任何已声明资产之前，生命周期脚本就可能运行。子进程会收到 Git 与 pnpm 所需的常规宿主进程状态，但会移除环境中名称形似凭据（`KEY`、`PASSWORD`、`SECRET`、`TOKEN`）的变量。该机制不新增 OAuth、token 转发或私有仓库认证约定。
 
 缓存项以精确 specifier 的 SHA-256 命名。同一进程内针对相同 specifier 的并发请求共享一项任务。安装在同级临时目录中进行；只有安装成功且存在包目录和标记时，系统才会把暂存目录原子重命名为最终键对应的目录。失败的暂存目录会被删除；如果另一进程已发布有效项，则以该项为准。后续进程会先校验标记与包目录，再返回稳定的 `node_modules/repository` 路径。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
index 7665dc3290..0bb3092b67 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
 2026-07-30-session-end-seed-log-boundary.md: 26cd67ccbfdf5dfc62e44a53c877acf6d2fee34a
-2026-07-30-session-end-seed-log-boundary.zh.md: 5ce12681da3ee46cc7c69aa6d432d25712db17fd
+2026-07-30-session-end-seed-log-boundary.zh.md: 70391ba8b629694cc83f1960ea3fdd94cd32f032
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
index 5ce12681da..70391ba8b6 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-拥有独立开／闭括号的插件无法区分一个已死的标记和一个存活的标记。`compact/start` … `compact/end` 就是已发布的实例：当接手一份日志、而它最后的压缩事件是一个未配对的 `compact/start` 时，"上一个写入方在压缩中途死掉了"与"此刻正有一次压缩在运行"在存储历史中是逐字节相同的。所有方只能二选一：拒绝压缩一份其实空闲的日志（把会话卡死），或者在一份确实繁忙的日志上继续压缩。
+在会话日志中拥有独立开／闭括号的插件无法区分一个已死的标记和一个存活的标记。`compact/start` … `compact/end` 就是已发布的实例：当接手一份日志、而它最后的压缩（compaction）事件是一个未配对的 `compact/start` 时，「上一个写入方在压缩中途死掉了」与「此刻正有一次压缩在运行」在存储历史中是逐字节相同的。该括号所有方只能二选一：拒绝压缩一份其实空闲的日志（把会话卡死），或者在一份确实繁忙的日志上继续压缩。
 
 日志中没有任何东西标出继承历史在哪里结束。`session/created`、`session/disposed` 与 `session/flush` 是 cordis 运行时信号，不是日志事件；`agent/session-start` 只发射不落盘。`Session.firstLiveSeq` 本来就精确地持有这个答案——本生命周期第一次自有写入的 seq——但只存在于内存中，因此读取存储字节的消费方看不到它。
 
@@ -14,13 +14,13 @@ Status: implemented
 
 ## Decision
 
-`Session` 的构造函数紧接显式传入的构造种子（包括空种子）之后追加仅日志事件 `session/end-seed`，作为带种子会话的第一次实时写入，位置正是 `firstLiveSeq` 指出的 seq。该事件是那个字段的持久投影：`firstLiveSeq` 为持有对象的消费方回答本生命周期的写入从哪里开始，`session/end-seed` 则为只持有存储字节的消费方回答同一问题。它的 payload 为空——位置与 `time` 承载全部含义——并且不是 `SurfaceEventType`，因此不产生消息，也无法扰动派生历史。这个 seq-0 标记把从空日志恢复的会话与真正的全新会话区分开来，从而防止恢复期间应用新会话默认值。
+`Session` 的构造函数紧接显式传入的构造种子（包括空种子）之后追加仅日志事件 `session/end-seed`，作为带种子会话的第一次自有写入，位置正是 `firstLiveSeq` 指出的 seq。该事件是那个字段的持久投影：`firstLiveSeq` 为持有对象的消费方回答本生命周期的写入从哪里开始，`session/end-seed` 则为只持有存储字节的消费方回答同一问题。它的 payload 为空——位置与 `time` 承载全部含义——并且不是 `SurfaceEventType`，因此不产生消息，也无法扰动派生历史。这个 seq-0 标记把从空日志恢复的会话与真正的全新会话区分开来，从而防止恢复期间应用新会话默认值。
 
 括号所有方按位置读取它：在 `session/end-seed` 之前的未配对开启标记具有更小的 seq，来自构造种子，并且属于一个已结束的生命周期。核心写入该边界但不从中读取任何内容；每个括号的词汇表仍归其所属插件，因此在没有消费方来塑形之前，核心不会先发布谓词辅助函数。
 
-选择构造函数，是因为它是每一个带种子会话都必经的唯一收窄处。全部六个入口都会到达它：`agents.resume()`、在已持久化 id 上的配置驱动启动（`restoreOrCreateConfigured`）、`sessions.fork()`、子代理 fork 子会话、`coordinator.adopt()` 的实时前缀路径，以及裸的 `sessions.create(id, {seed})`。在持久化加载时写入的边界会漏掉两条 fork 路径——而一个继承了仍在运行的父会话开放 `compact/start` 的 fork 子会话，恰恰是必须可判定的场景。在 loop 启动时写入的边界会漏掉 `fork()` 与 `adopt()`，并且不得不在 `SessionStartSource: 'startup'` 上触发——那正是 fork 子会话发布的取值，于是该字段将不再具有区分力。
+选择构造函数，是因为它是每一个带种子会话都必经的唯一收窄处。全部六个入口都会到达它：`agents.resume()`、在已持久化 id 上的配置驱动启动（`restoreOrCreateConfigured`）、`sessions.fork()`、subagent fork 子会话、`coordinator.adopt()` 的实时前缀路径，以及裸的 `sessions.create(id, {seed})`。在持久化加载时写入的边界会漏掉两条 fork 路径——而一个继承了仍在运行的父会话开放 `compact/start` 的 fork 子会话，恰恰是必须可判定的场景。在 loop 启动时写入的边界会漏掉 `fork()` 与 `adopt()`，并且不得不在 `SessionStartSource: 'startup'` 上触发——那正是 fork 子会话发布的取值，于是该字段将不再具有区分力。
 
-两条守卫让这个标记保持精确。省略种子时不写入任何内容，因为这是全新会话。种子本身已以该事件结尾时不会重复标记，这让写入具备幂等性。幂等性是承重的，而不是为了整洁：每次绑定到 Agent 的冷会话接手都会经过 `agentFor()`；没有这条守卫，重复的控件操作即使没有执行任何工作，也会让日志增长。只执行检查的 `session.history` 与 `session.fork` 源端路径不会在源会话中创建这条边界。
+两条守卫让这个标记保持精确。省略种子时不写入任何内容，因为这是全新会话。种子本身已以该事件结尾时不会重复标记，这让写入具备幂等性。幂等性是承重的，而不是为了整洁：每次绑定到 Agent 的冷会话接手都会经过 `agentFor()`；没有这条守卫，重复的控制操作即使没有执行任何工作，也会让日志增长。只执行检查的 `session.history` 与 `session.fork` 源端路径不会在源会话中创建这条边界。
 
 ## 持久化无需任何改动
 
@@ -48,8 +48,8 @@ Status: implemented
 
 买到的：一条边界，在一处写入，对全部六条带种子启动路径都正确——包括持久化层方案触及不到的 fork 缺口。持久化各包保留纯读取路径。`firstLiveSeq` 获得一个持久孪生体，而不是关于同一边界的第二套彼此竞争的概念。
 
-代价：带种子会话的日志长了一个事件，空日志恢复也包括在内。seq 期望会随这条边界移动。两处更新是承重的而非机械的：telemetry 的收养测试断言该边界*会*被导出，因为它是本生命周期的自有写入；属性测试套件的回放不变式则是"种子逐字节复现，外加一个仅日志边界"，并把幂等性作为独立属性。
+代价：带种子会话的日志长了一个事件，空日志恢复也包括在内。seq 期望会随这条边界移动。两处更新是承重的而非机械的：telemetry 的接管测试断言该边界*会*被导出，因为它是本生命周期的自有写入；属性测试套件的回放不变式则是「种子逐字节复现，外加一个仅日志边界」，并把幂等性作为独立属性。
 
 `session/end-seed` 加入了落盘词汇表。在预发布立场下（`SESSION_FORMAT_VERSION` 固定为 `0`，不作兼容承诺），更旧的日志只是没有它，而没有边界的日志会正确地判定没有任何内容属于构造种子历史。
 
-[排队手动压缩决策](../feature/2026-07-30-queued-manual-compaction.md)如今提供了第一个消费方。其尾部扫描会分别查找未匹配的 `compact/start` 与最新 end-seed，只把位于该边界之后的 start 视为活动锁，并在同一个回放转换上清除不变量追踪状态。该谓词仍位于压缩包中，不会成为通用核心辅助函数。
+[排队手动压缩决策](../feature/2026-07-30-queued-manual-compaction.md)如今提供了第一个消费方。其尾部扫描会分别查找未匹配的 `compact/start` 与最新 end-seed，只把位于该边界之后的 start 视为存活，并在同一个回放转换上清除不变量追踪状态。该谓词仍位于压缩功能所在的包中，不会成为通用核心辅助函数。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 6319b99fb2..5938463c32 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
 2026-07-30-static-repository-plugin-format.md: c9d755b925a6ea05eed71e75803397d2672df9f4
-2026-07-30-static-repository-plugin-format.zh.md: 361de64d2e98b9fb4ac42963e4ae48e77fbc7016
+2026-07-30-static-repository-plugin-format.zh.md: f747ffeb6d763412dbd6d161e474da35eb7ce5a0
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index 361de64d2e..f747ffeb6d 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -1,28 +1,28 @@
-# Agent Note：静态 repository Plugin 格式
+# Agent Note: 静态 repository 插件格式
 
-状态：已实现
+Status: implemented
 
 [English](2026-07-30-static-repository-plugin-format.md) | 中文
 
 ## 问题
 
-一个已经包含可复用 skills 或 MCP server 声明的仓库，应当能被独立 Harness 应用使用，而不必先变成 Harness SDK 项目，也不应被迫改写现有布局。常见仓库只需新增一个 `.dsh-plugin` 目录，同时仍可把原有 skills 与 `.mcp.json` 放在仓库其他位置。与此同时，如果把任意仓库入口都当作 Cordis Plugin，就会让每个仓库成为新的无限制运行时扩展表面，并绕过现有的 skill 与 MCP 生命周期所有者。
+一个已经包含可复用 skill（技能） 或 MCP server 声明的仓库，应当能被独立 Harness 应用使用，而不必先变成 Harness SDK 项目，也不应被迫改写现有布局。常见仓库只需新增一个 `.dsh-plugin` 目录，同时仍可把原有 skills 与 `.mcp.json` 放在仓库其他位置。与此同时，如果把任意仓库入口都当作 Cordis Plugin，就会让每个仓库成为新的无限制运行时扩展面，并绕过现有的 skill 与 MCP 生命周期所有者。
 
-[Package-manager-native repository cache](2026-07-30-package-manager-native-repository-cache.md) 会准备一个精确 package source，但有意不了解任何 DSH 格式。因此本层需要一种兼容 package manager 的创作格式、确定性的已准备产物，以及在 Loader dispose 和替换期间仍保持事务性的 Cordis 组合。
+[包管理器原生仓库缓存](2026-07-30-package-manager-native-repository-cache.md) 会准备一个精确 package source，但有意不了解任何 DSH 格式。因此本层需要一种兼容 package manager 的创作格式、确定性的已准备产物，以及在 Loader dispose（资源释放）和替换期间仍保持事务性的 Cordis 组合。
 
 ## 决策
 
-`@deepseek-ai/dsh-repository-plugin` 负责一个受限的 `.dsh-plugin` package 格式，且只允许两类贡献：skill 根和一个通用 `.mcp.json`。Package metadata 使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径；两者至少需要一个。路径可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的 Plugin 可以拥有其 package 上方相邻的子树，却不能访问无关宿主路径。
+`@deepseek-ai/dsh-repository-plugin` 负责一个受限的 `.dsh-plugin` 包格式，且只允许两类贡献：skill 根和一个通用 `.mcp.json`。Package metadata 使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径；两者至少需要一个。路径可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的 Plugin 可以拥有其 package 上方相邻的子树，却不能访问无关宿主路径。
 
-`.dsh-plugin` package 把 `dsh-plugin-prepare` 声明为普通 package-manager `prepare` 脚本。Helper 会校验 metadata 与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。`.mjs` 扩展名避免强迫仓库作者在 package metadata 中设置 `type: module`。生成模块来自固定、无 import 的模板，只包含规范化 manifest、由 manifest 派生的 `inject` 列表（`loader`，加上按声明能力加入的 `skills`／`tools`，使包装 fiber 在其子插件所需服务上门控），以及对 `dsh-repository-plugin` Loader builtin 的委托。准备阶段永远不会发现、转译、打包或保留自定义仓库入口。
+`.dsh-plugin` package 把 `dsh-plugin-prepare` 声明为普通 package-manager `prepare` 脚本。Helper 会校验 metadata 与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。`.mjs` 扩展名避免强迫仓库作者在 package metadata 中设置 `type: module`。生成模块来自固定、无 import 的模板，只包含规范化 manifest（元数据清单）、由 manifest 派生的 `inject` 列表（`loader`，加上按声明能力加入的 `skills`／`tools`，使包装 fiber 在其子插件所需服务上门控），以及对 `dsh-repository-plugin` Loader builtin 的委托。准备阶段永远不会发现、转译、打包或保留自定义仓库入口。
 
-加载 DSH package 会以 effect 方式注册该 builtin。生成的包装模块使用 `import.meta.url` 把 builtin 挂载为自己的子级，因此所有贡献都归属于包装 fiber，并在 Loader 移除或回滚时消失。Builtin 会在读取资源前重新校验已准备 manifest 与路径包含关系。它只组合现有实现，而不自行注册 skills 或 MCP 工具。
+加载 DSH 包会将该 builtin 注册为 effect。生成的包装层使用 `import.meta.url` 把 builtin 挂载为自己的子级，因此所有贡献都归属于包装 fiber，并在 Loader 移除或回滚时消失。Builtin 会在读取资源前重新校验已准备 manifest 与路径包含关系。它只组合现有实现，而不自行注册 skills 或 MCP 工具。
 
 每份已准备 skill 集合都会挂载 `dsh-skill-local`，使用唯一的 `repository:<package-name>` 提供方名称、仅包含复制后的自定义根，并禁用监视。因此 `dsh-skill-local` 新增两个通用配置字段：`providerName` 和 `includeDefaultRoots`。默认值保持原有单一本地提供方行为；repository 实例设置不同名称并排除项目／用户根，使多个实例既不冲突，也不会重复宿主本地发现。
 
-`.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配层接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。严格的 `${NAME}` 进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。因此 MCP 连接失败会继续沿用“Plugin 成功但不注册工具”的既有行为，不会被重新分类为 repository 准备或 Loader 失败。
+`.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配器接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。形如 `${NAME}` 的完整进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。因此 MCP 连接失败会继续沿用「Plugin 成功但不注册工具」的既有行为，不会被重新分类为 repository 准备或 Loader 失败。
 
-未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容契约。Hooks、commands、agents、apps、任意 Cordis 代码、marketplace 和发现同样不受支持。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本格式 package。
+未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容约定。Hooks、commands、agents、apps、任意 Cordis 代码、marketplace 和发现同样不受支持。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本格式 package。
 
 ## 考虑过的替代方案
 
@@ -39,11 +39,11 @@
 ## 后果
 
 - 现有 skill／MCP 仓库可以新增一个很小的 `.dsh-plugin/package.json`，无需移动资源或采用 SDK 项目。
-- 已准备输出是确定性的静态胶水；已配置仓库及其依赖生命周期仍是受信任的可执行 package-manager 输入，而非 sandbox。
-- 多个 repository Plugin 通过提供方名称和普通 MCP server-name 唯一性共存；重复名称经现有 registry 失败，并参与 Loader 回滚。
+- 已准备输出是确定性的静态胶水；已配置仓库及其依赖生命周期仍是受信任的可执行 package-manager 输入，而非沙箱。
+- 多个 repository Plugin 通过提供方名称和普通 MCP server-name 唯一性共存；重复名称会由现有注册表判定为失败，并参与 Loader 回滚。
 - Cache 内的源码编辑不会实时出现；必须选择另一个精确 source／ref／path／config。
 - 新增贡献类型必须提供显式格式和 DSH 自有运行时消费方；它不能意外以 repository JavaScript 形式进入。
 
 ## 测试
 
-聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。Keyless headless 示例通过真实 `cordis.yml` 加载一份签入的已准备包装模块，并快照 repository skill 写入日志的模型目录行。
+聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP、DataJunction 风格 stdio 及环境变量值，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。Keyless headless 示例通过真实 `cordis.yml` 加载一份签入的已准备包装模块，并对 repository skill 写入日志的模型目录行生成快照。
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
index 3128996f1e..18e7911025 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
 2026-07-31-claimed-pre-step-inbox-lifecycle.md: 5184c00335b3084a8eb6d58fa33a0af8d3a16ed6
-2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 4966ccc8a3a7535022c04f9445ca75102ccca71e
+2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 461d926b5143c9bb76dcb07a96315083d599a1f8
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
index 4966ccc8a3..461d926b51 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：在单一 pre-step 决策前领取 inbox 输入
+# Agent Note: 在单一 pre-step 决策前领取 inbox 输入
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-循环此前把一个步骤边界拆成提示词准备、提示词准入与串行 step hook。准入结果可以保留或丢弃已领取输入，实时队列事件还携带了与持久 inbox 状态重复的形状。插件不得不在修改 inbox、改写已提交批次与直接追加会话历史之间选择，而观察方无法依赖一套明确顺序。
+agent loop（智能体循环）此前把一个步骤边界拆成提示词准备、提示词准入与串行步骤钩子。准入结果可以保留或丢弃已领取输入，实时队列事件还携带了与持久 inbox 状态重复的数据结构。插件不得不在修改 inbox、改写已提交批次与直接追加会话历史之间选择，而观察方无法依赖一套明确顺序。
 
 单次出现专属的 inbox wrapper 也重复了每个 `UserMessage` 已有的标识。它把插入、编辑、领取、取消、重连投影与步骤进入合并成一套协议，但仅追加会话本就拥有持久队列投影。
 
@@ -16,9 +16,9 @@ Status: implemented
 
 `PreStepDecision` 为 `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`。reject 不会打开步骤，会让已领取批次保持已删除，并将轮次关闭为 blocked，且不产生任何步骤事件。空的 enter、取消以及 `step/start` 前的失败同样会关闭一个边界平衡的无步骤轮次。enter 提供在 `step/start` 后以 `user/message` 追加的完整批次。包装 `next()` 的监听器会保留下游变更，除非有意替换，因此全部消息改写只在最终返回值中一次性结算。系统不再存在 `agent/prompt-prepare`、`agent/prompt-submit` 或 `agent/step` seam。
 
-持久 inbox 仍是两份通过 `MessageId` 寻址的 `UserMessage[]` 列表。`append`、`prepend` 与 `splice` 接受 target；`replace(messageId, newMessage)` 与 `remove(messageId)` 则在提交规范化 splice 前，通过 `MessageId` 跨两份列表定位待处理消息。替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。每次插入发出 `agent/inbox/inserted { message }`；普通删除记录 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`。领取是循环在 inbox 上的内部步骤边界操作，记录不带通知或 outcome 的纯删除，因此循环可以自行发布 claimed 事件。这些实时事件不增加 placement、outcome 或批次字段。
+持久 inbox 仍是两份通过 `MessageId` 寻址的 `UserMessage[]` 列表。`append`、`prepend` 与 `splice` 接受 target；`replace(messageId, newMessage)` 与 `remove(messageId)` 则在提交规范化 splice 前，通过 `MessageId` 跨两份列表定位待处理消息。替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。每次插入发出 `agent/inbox/inserted { message }`；普通删除记录 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`。领取是循环在 inbox 上的内部步骤边界操作，记录不带通知或 outcome 的纯删除，因此 agent loop 可以自行发布 claimed 事件。这些实时事件不增加 placement、outcome 或批次字段。
 
-两类事件表面服务不同消费方。跟踪单条消息的观察方使用 `agent/inbox/inserted`、`claimed` 与 `discarded`。包括 Web 队列投影和重连基线在内的整体队列消费方使用持久 `agent/inbox/spliced` 流；UI 编辑与移除经 `Inbox.splice()` 或其他 Inbox 变更方法进入，从而让同一投影记录所有变化。
+两类事件接口服务于不同消费方。跟踪单条消息的观察方使用 `agent/inbox/inserted`、`claimed` 与 `discarded`。包括 Web 队列投影和重连基线在内的整体队列消费方使用持久 `agent/inbox/spliced` 流；UI 编辑与移除经 `Inbox.splice()` 或其他 Inbox 变更方法进入，从而让同一投影记录所有变化。
 
 必须对当前步骤进行原子改写的插件从 `agent/pre-step` 返回消息。只需要稍后上下文的插件可以直接修改 `agent.inbox`。Workspace context 同时使用两条路径：异步文件系统投影会暂存一条可替换的 `next-step` 消息，而下一次进入步骤的 pre-step 会把该消息或新组合的基线折入最终批次，并移除仍待处理的副本。reject 会让该条目继续排队。
 
@@ -26,16 +26,16 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**保留分离的 prepare 与 admit hook。** 这样准备阶段可以在领取前修改 inbox，准入阶段可以在领取后改写，但同一边界会出现两个顺序表面，取消归属也会变得模糊。
+**保留分离的 prepare 与 admit hook。** 这样准备阶段可以在领取前修改 inbox，准入阶段可以在领取后改写，但同一边界会出现两套顺序机制，取消归属也会变得模糊。
 
-**reject 时把已领取批次重新入队。** 这看似保留重试行为，却会让否决隐式修改队列；若不为每个竞态加围栏，还会复制后续工作，并使 claim 无法成为原子所有权转移。
+**reject 时把已领取批次重新入队。** 这看似保留重试行为，却会让否决隐式修改队列；若不为每个竞态加围栏，还会导致后续工作重复，并使 claim 无法成为原子所有权转移。
 
-**在每个实时事件上携带 placement 与 outcome。** 持久 splice 已经拥有这些事实。实时通知重复它们会建立可能漂移的第二份契约，而持有确切消息标识的消费方并不需要这些字段。
+**在每个实时事件上携带 placement 与 outcome。** 持久 splice 已经拥有这些事实。实时通知重复它们会建立可能漂移的第二套约定，而持有确切消息标识的消费方并不需要这些字段。
 
 ## 验证
 
-Agent-loop 覆盖固定先 `turn/start`、再领取、后 pre-step 的顺序、实时事件的确切载荷、边界平衡的无步骤 reject、最终批次改写、领取后插入的输入、监听器失败与取消。Inbox 和消费方测试固定纯领取删除、普通删除的 canceled 结果、workspace-context 的暂存、替换与同一步骤进入、plan/goal/hook 行为、UI 清理、压缩、检查点以及恢复后的持久投影。生成的事件与类型目录只公开新的 seam 与载荷。
+Agent-loop 覆盖固定先 `turn/start`、再领取、后 pre-step 的顺序、实时事件的确切载荷、边界平衡的无步骤 reject、最终批次改写、领取后插入的输入、监听器失败与取消。Inbox 和消费方测试固定纯领取删除、普通删除的 canceled 结果、workspace-context 的暂存、替换与同一步骤进入、plan/goal/hook 行为、UI 清理、压缩（compaction）、检查点以及恢复后的持久投影。生成的事件与类型目录只公开新的 seam 与载荷。
 
 ## 后果
 
-循环在每个步骤前只有一个需等待的决策，对输入也只有一次所有权转移。已领取消息不会隐式返回 inbox；后续插入保持独立。实时事件与其他 inbox 通知保持对称，但不镜像持久元数据；插件可以显式选择精确的当前步骤改写，或普通的后续 inbox 投递。
+循环在每个步骤前只有一个需等待的决策，对输入也只有一次所有权转移。已领取消息不会隐式返回 inbox；后续插入保持独立。实时事件与其他 inbox 通知保持对称，但不镜像持久元数据；插件可以显式选择仅针对当前步骤的改写，或普通的后续 inbox 投递。
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
index 45436c96e6..0a3ec9f475 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
 2026-07-31-code-runtime-portable-identifier-seam.md: 9e9df50235b3505458e3645e2c6ff6e9bd439183
-2026-07-31-code-runtime-portable-identifier-seam.zh.md: 31d2410ee4809d0693f2e7897e61c50163bb0758
+2026-07-31-code-runtime-portable-identifier-seam.zh.md: 62880dc3920af470fae8d54fe9bd061d7e7b54b3
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
index 31d2410ee4..62880dc392 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：code-runtime seam 拥有可移植标识符排除集
+# Agent Note: code-runtime seam 拥有可移植标识符排除集
 
 Status: implemented
 
@@ -6,13 +6,13 @@ Status: implemented
 
 ## Problem
 
-code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性契约。
+code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性约定。
 
-一个针对不同语言（CPython，将在本 stack 后续 PR 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使 seam 的一个实现伸手进入另一个兄弟实现。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
+一个针对不同语言（CPython，将在本 stack 后续 PR（Pull Request） 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使 seam 的一个实现伸手进入另一个兄弟实现。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
 
 ## Decision
 
-seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除契约，每个后端导入它们而非重新声明：
+seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除约定，每个后端导入它们而非重新声明：
 
 - `PORTABLE_RESERVED_WORDS`——ECMAScript 与 Python 保留字的联集。任何命名空间 global 或 error-class 名称匹配其中之一，都在所有后端上被拒绝，因此 `lambda` 即便是合法的 JS 参数名也被拒绝。新增一门语言即扩宽此联集，这是对现有绑定名称的一次有意的破坏性复审。
 - `RESERVED_BINDING_GLOBALS`——某个后端在程序命名空间中拥有的 global：`console`（worker 的日志捕获）、`__dsh_main__`/`__builtins__`/`__name__`（Python bootstrap 的包装器与预置模块 global），以及 `__debug__`（不是 seed 的槽位，而是 CPython 编译期常量，赋值会被拒，故以该名注入的 global 不可达——同一种可移植性分裂，只是机制不同）。在所有后端上被拒绝，使命名空间列表无法选到一个在某后端能用、在另一后端冲突的名称。
@@ -21,24 +21,24 @@ seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移
 
 seam 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记录在 `CodeBindingNamespace.global` 与 `CodeBindingErrorClass` 上），去掉 JS 专有的 `$`。worker 直接以 seam 名消费这些共享常量——binding-global 与 error-class 名称用 `PORTABLE_RESERVED_WORDS`、后端拥有槽位用 `RESERVED_BINDING_GLOBALS`、error member 用 `RESERVED_ERROR_MEMBERS` 加 `DUNDER_MEMBER`——不再本地起别名；其 `IDENTIFIER` 正则去掉 `$`。
 
-尽管本 PR 只交付一个后端，这些常量仍置于 seam：要点正是该契约与语言无关，且拥有权在任何单一语言之上。违反它的后端才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
+尽管本 PR 只交付一个后端，这些常量仍置于 seam：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的后端才是 bug，而共享集合正是复审者查看「可移植」含义的地方。
 
 ## Scope
 
 本 PR 只交付 seam 扩展与 worker 对它的采用。这里不交付任何 Python 后端、`py-types` 渲染器或 Code Mode 的语言分发——它们是本 stack 中依赖这些导出的后续 PR。seam README 中仅描述 worker 的措辞保持不变，理由相同：链接到一个尚不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
 
-`RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本契约要防止的可移植性分裂。
+`RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本约定要防止的可移植性分裂。
 
 ## Alternatives considered
 
 **每个后端声明自己的排除集。** 拒绝：这让可移植承诺变成逐后端成立。调用方在 worker 上测过的绑定列表可能被 Python 拒绝，而这正是 seam 存在要防止的分裂。
 
-**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的实现会为一个二者都不拥有的契约伸手进入兄弟实现。契约属于二者之上，即 seam。
+**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的实现会为一个二者都不拥有的约定伸手进入兄弟实现。约定属于二者之上，即 seam。
 
 **在可移植标识符子集中保留 `$`。** 拒绝：`$` 是 JS 专有拼写。允许它会让 `$tools` 通过 worker 却在每个非 JS 后端上失败，为纯粹表面的好处破坏可移植性。
 
 ## Consequences
 
-获得：一个地方——seam 包——定义什么是可移植绑定名称，每个后端通过导入执行同一契约。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
+获得：一个地方——seam 包——定义什么是可移植绑定名称，每个后端通过导入执行同一约定。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
 
-代价：现有使用含 `$` global 的 worker 调用方现在会在标识符校验时失败。在预发布立场下这是一次被纠正的地基，而非需要 shim 的兼容性破坏。worker 的 seam-misuse 测试新增了 `$tools`、Python 异常成员（`args`）、dunder（`__dict__`）与一个 Python 拥有的 global（`__dsh_main__`）等用例，从 worker 侧证明共享集合被执行。
+代价：现有使用含 `$` global 的 worker 调用方现在会在标识符校验时失败。在预发布立场下这是修正后的基础，而非需要 shim 的兼容性破坏。worker 的 seam-misuse 测试新增了 `$tools`、Python 异常成员（`args`）、dunder（`__dict__`）与一个 Python 拥有的 global（`__dsh_main__`）等用例，证明 worker 侧会依据共享集合执行排除规则。
diff --git a/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml
index 589ecbf5fd..f12335047c 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.md
 2026-07-31-goal-owned-durable-events.md: ac0358469958319f7629adb5e96845b7e0013297
-2026-07-31-goal-owned-durable-events.zh.md: 9b45cdd7990bfc1fdfbb63650e40b41e5ba2918d
+2026-07-31-goal-owned-durable-events.zh.md: b4b1e3709cca6044a35d59185f8e15a93edb7590
diff --git a/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.zh.md b/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.zh.md
index 9b45cdd799..b4b1e3709c 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.zh.md
@@ -16,7 +16,7 @@ Goal 领域需要持久状态，但不需要拥有待处理的模型输入。继
 
 `GoalMessageSource` 只标识已准入且为正数的继续执行 Round。匹配的 `user/message` 会推进 `roundsStarted`；普通用户消息与 inbox splice 事件不会改变 goal 状态。Goal 包不会插入、领取、移除或检查 inbox 消息。`@deepseek-ai/dsh-goal-session` 仍通过公开 inbox 生命周期负责排队和跟踪自己的继续执行提示词。
 
-激活态仍只存在于进程中。服务在缓存观察事件时，将同步追加的事件序号与目标激活态关联；回放或外部追加的变更默认处于 `disarmed`。会话日志仍是唯一的持久权威。
+激活态仍只存在于进程中。服务在缓存观察事件时，将同步追加的事件序号与所请求的激活状态关联；回放或外部追加的变更默认处于 disarmed 状态。会话日志仍是唯一的持久权威。
 
 该领域不会自动把每次变更投影为模型输入。Goal 工具返回当前状态；真正调度工作时，继续执行提示词包含目标描述与 Round 状态。未来如果需要始终可见的 goal 上下文，应由独立上下文插件拥有其 inbox 消息，而不是把它作为持久化副作用。
 
@@ -28,6 +28,6 @@ Goal 领域需要持久状态，但不需要拥有待处理的模型输入。继
 
 ## 后果
 
-Goal 状态不依赖 inbox 放置与准入。回放只有一条变更路径，投影直接由 `goal/change` 推进，继续执行消息只携带 Round 归属。模型不会收到仅用于变更的 `<goal_state>` 消息；模型可见状态来自 goal 工具与已调度的继续执行提示词。直接写入会话的插件仍受信任，并且可以追加畸形变更；严格折叠与 invariant 配套模块会拒绝这些变更。
+Goal 状态不依赖 inbox 放置与准入。回放只有一条变更路径，投影直接由 `goal/change` 推进，继续执行消息只携带 Round 归属。模型不会收到仅用于变更的 `<goal_state>` 消息；模型可见状态来自 goal 工具与已调度的继续执行提示词。直接写入会话的写入方仍受信任，并且可以追加畸形变更；严格折叠与 invariant 配套模块会拒绝这些变更。
 
-聚焦的 goal、goal-session、command、TUI 与 client fixture 测试固定持久回放、正数 Round 计数、inbox 独立性、投影更新和恢复会话行为。无密钥进程测试检查持久的 `goal/change` 事件，并验证仅创建 goal 不会启动继续执行 Round。
+聚焦的 goal、goal-session、command、TUI 与 client fixture（测试前置数据）测试固定持久回放、正数 Round 计数、inbox 独立性、投影更新和恢复会话行为。无密钥进程测试检查持久的 `goal/change` 事件，并验证仅创建 goal 不会启动继续执行 Round。
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
index f63372c8b4..262b57e436 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
 2026-08-01-packaged-ripgrep-search.md: 7c515618a18b61bd90177a6fdf19bbd52e564209
-2026-08-01-packaged-ripgrep-search.zh.md: f2b1a12c737f772bff6a6c91c17f7453dbc89748
+2026-08-01-packaged-ripgrep-search.zh.md: 4acf4eeb6f9153b8181ba493bf566cd7387a1984
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
index f2b1a12c73..4acf4eeb6f 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
@@ -12,19 +12,19 @@ Status: implemented
 
 ## 决策
 
-`@deepseek-ai/dsh-tool-fs-search` 现在运行 PACKAGED（打包的）ripgrep 二进制（`@vscode/ripgrep`，一个 npm 依赖，其可选平台包随附二进制），经由 `ctx.subprocess` seam：`runRipgrep()` 以纯 argv 向量 spawn `rgPath`，向量前缀 `--no-config`，配以 collect 模式 stdout/stderr、`graceMs` 与转发的 `exec.signal`。`rgPath` 在首次调用时懒解析（进程内 memoize）：`@vscode/ripgrep` 在模块求值阶段解析其平台包，静态导入会把平台包缺失/损坏（`--omit=optional`、安装不全）变成 Loader 组合加载失败——这正是本次改动要消除的加载期失败模式。不再有 shell 层，执行路径上的 shell 引号边界随之消失；`singleQuote` 工具与其 shell spawn 测试一并删除。原始流使用 seam 的诊断尾部 collect 形态（无 spill 文件——工具从不读取原始 spill 路径；lossy stdout 读取以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败）。终止宽限与 stderr 尾部预算成为经校验的 `Config` 字段（`graceMs` 默认 3000，`stderrMaxBytes` 默认 64 KiB），不再继承自 bash-local 的配置。注册变为无条件——加载期 `command -v rg` 探针与条件注册决策被删除，连同那条 "rg not found" 警告。本包注入 `tools`、`systemPrompt` 与 `subprocess`。
+`@deepseek-ai/dsh-tool-fs-search` 现在运行 PACKAGED（打包的）ripgrep 二进制（`@vscode/ripgrep`，一个 NPM 依赖，其可选平台包随附二进制），经由 `ctx.subprocess` seam：`runRipgrep()` 以纯 argv 向量 spawn `rgPath`，向量前缀 `--no-config`，配以 collect 模式 stdout/stderr、`graceMs` 与转发的 `exec.signal`。`rgPath` 在首次调用时懒解析（进程内 memoize）：`@vscode/ripgrep` 在模块求值阶段解析其平台包，静态导入会把平台包缺失/损坏（`--omit=optional`、安装不全）变成 loader 组合失败——这正是本次改动要消除的加载期失败模式。不再有 shell 层，执行路径上的 shell 引号边界随之消失；`singleQuote` 工具与其 shell spawn 测试一并删除。原始流使用 seam 的诊断尾部 collect 形态（无 spill 文件——工具从不读取原始 spill 路径；lossy stdout 读取以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败）。终止宽限与 stderr 尾部预算成为经校验的 `Config` 字段（`graceMs` 默认 3000，`stderrMaxBytes` 默认 64 KiB），不再继承自 bash-local 的配置。注册变为无条件——加载期 `command -v rg` 探针与条件注册决策被删除，连同那条 "rg not found" 警告。本包注入 `tools`、`systemPrompt` 与 `subprocess`。
 
 退出语义仍由工具拥有：退出码 0 为有结果的成功，1 为成功的空搜索，其余归入既有 `SEARCH_*` 词汇（无效模式、启动失败、信号杀死、原始输出溢出）。超时是挂在工具定义上的协作式工具调用预算：`@deepseek-ai/dsh-timeout-policy` 中止 `exec.signal`，subprocess seam 的终止升级提供硬终止，工具报告 `SEARCH_ABORTED`。工作目录为会话 header cwd（存在时），否则为 `process.cwd()`——不再有执行器配置可供默认化，因此回退由工具自己拥有。
 
-`fs-glob-sampling` ACP 快照场景改为执行真实的打包二进制，作用于一个用固定 mtime 钉住 `--sort=modified` 顺序的预制工作区，取代 PATH 注入的 `rg` 替身（仅 POSIX：展示路径携带 `/` 分隔符，会话日志比较无法归一化）。
+`fs-glob-sampling` ACP（Agent Client Protocol）快照场景改为执行真实的打包二进制，作用于一个用固定 mtime 钉住 `--sort=modified` 顺序的预制工作区，取代 PATH 注入的 `rg` 替身（仅 POSIX：展示路径携带 `/` 分隔符，会话日志比较无法归一化）。
 
 ## 备选方案
 
 **保留 bash seam 与探针，仅把 `rg` 记为必需宿主依赖。** 否决：宿主依赖正是本次改动要消除的失败模式，而让发现工具支持 Windows 正是此举的目的；写进文档的依赖仍是依赖。
 
-**让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试 seam 会消费的公开部署面，而真实二进制本身足够确定——通过 fixture mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
+**让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试 seam 会消费的公开部署面，而真实二进制本身足够确定——通过 fixture（测试前置数据）的 mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
 
-**改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于"不存在 glob 引擎"的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具契约。
+**改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于「不存在 glob 引擎」的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具约定。
 
 ## 后果
 
@@ -33,6 +33,6 @@ Status: implemented
 - spawn 不受沙箱约束（普通的 `ctx.subprocess` 调用），因此前缀 `--no-config`：宿主的 `RIPGREP_CONFIG_PATH`（或二进制旁的 `rg.conf`）否则可注入 `--pre` 预处理器，对每个匹配文件执行任意命令。加上 `--no-config` 后，任何配置文件——因而任何预处理器——都无法触及搜索。
 - 原始输出溢出路径的形态改变：旧的 bash 承载路径继承了 bash-local 常开的 spill，可能留下没人读的多 MB 临时文件；subprocess seam 现在无 spill 收集，溢出是纯粹的错误（`SEARCH_RAW_OUTPUT_OVERFLOW`，"narrow pattern, path, or include and retry"），不返回任何内容。
 - 加载期失败模式改变：subprocess seam 损坏现在让首次搜索调用失败（`SEARCH_FAILED`），而非通过探针使插件加载失败；二进制缺失是带打包路径的启动失败，而不是 PATH 问题。
-- 集成套件的 fixture 去掉了 Windows 无法表示的文件名（名称含 `"`），保证套件在每个平台都能重放。
-- 重新生成 `THIRD_PARTY_NOTICES.md` 暴露了一个由新依赖带出的潜在生成器 bug：Node 的 `fs.globSync` 返回操作系统原生分隔符，因此在 Windows 上 notices 分层中带 `/` 后缀的 dev 区前缀永远匹配不上，dev-only 包（测试工具、support 叶子）被错分为 runtime。生成器现在在入口处归一化清单路径，notices 与平台无关。
-- `@vscode/ripgrep` 依赖为 runtime 层增加其 MIT 行；pnpm 11 截断的虚拟存储目录名需要在 notices 生成器的元数据查找中增加内容扫描回退。
+- 集成套件的 fixture 去掉了 Windows 无法表示的文件名（名称含 `"`），保证套件在每个平台都能回放。
+- 重新生成 `THIRD_PARTY_NOTICES.md` 暴露了一个由新依赖带出的潜在生成器 bug：Node 的 `fs.globSync` 返回操作系统原生分隔符，因此在 Windows 上 notices 分层中带 `/` 后缀的 dev 区前缀永远匹配不上，dev-only 包（测试工具、support 叶子）被错分到运行时层。生成器现在在入口处归一化 manifest（元数据清单）路径，notices 与平台无关。
+- `@vscode/ripgrep` 依赖为运行时层增加其 MIT 行；pnpm 11 截断的虚拟存储目录名需要在 notices 生成器的元数据查找中增加内容扫描回退。
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index d3f73c3b5c..dfe291e9d0 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
 2026-08-02-typert-remote-method-calls.md: f3db8b9eec5eb8fb610fc58edad9313e4f715326
-2026-08-02-typert-remote-method-calls.zh.md: da4459432e8c9e08821bcded2921cbd33fc5e8c8
+2026-08-02-typert-remote-method-calls.zh.md: 2290b701eff7ca601b500efbfcf7bdc59c01bcba
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index da4459432e..2290b701ef 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -10,7 +10,7 @@ Host API Proxy 同时承担直接方法调用、带状态交互和 Session 事
 
 本决策只涵盖一次请求对应一次结果的定向方法调用。Permission、Approval 等带状态交互以及 Session 事件流仍采用独立设计。
 
-直接方法调用的契约属于实现该行为的业务 Service。业务开发者只需声明哪些方法可以远程调用，无需再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
+直接方法调用的约定属于实现该行为的业务 Service。业务开发者只需声明哪些方法可以远程调用，无需再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
 
 Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以不同类型合并同名 Cordis `Context`。Remote 投影不能把完整 Host 声明导入消费端，也不能依赖 Browser 专属类型；未来 TUI 若复用这套编程界面，也只能看到 Remote 标记的方法。本期不实现 TUI 接入，但实现边界不得阻断这种同构复用。
 
@@ -18,11 +18,11 @@ Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以
 
 业务 Service 继承 `GatewayService`，并通过 `@Remote` 或 `@RemoteScope()` 声明可调用方法；已有其他基类的 Service 可以改用 `bindTypeRTGateway()` 暴露同一绑定。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
 
-Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client Remote Service；该投影和 Remote 抽象保持平台无关，以便未来 TUI 复用。
+Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一约定的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client Remote Service；该投影和 Remote 抽象保持平台无关，以便未来 TUI 复用。
 
 `@deepseek-ai/dsh-api-gateway` 位于 `packages/api/gateway`，提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.remote`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在 Connection 共享的 `/api` RPC channel 上；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
 
-`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 契约，而不导入具体 Gateway 实现。
+`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 约定，而不导入具体 Gateway 实现。
 
 ## 组件和 Cordis 服务
 
@@ -42,7 +42,7 @@ Host Gateway 不依赖 `ctx.agents`、`ctx.sessions`、`ctx.goals` 或 `ctx.http
 
 ## 业务声明
 
-普通直接调用使用 `@Remote`。现有方法的参数和结果已经是预期的 Remote 契约时，直接装饰该方法，不为此重命名。只有 wire 契约需要不同的请求或结果形态时，才新增 `remoteExport*` 适配器，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
+普通直接调用使用 `@Remote`。现有方法的参数和结果已经是预期的 Remote 约定时，直接装饰该方法，不为此重命名。只有 wire 约定需要不同的请求或结果形态时，才新增 `remoteExport*` 适配器，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
 
 ```text
 export class GoalService extends GatewayService {
@@ -87,7 +87,7 @@ export class ScopedGoalService extends GatewayService {
 
 ## Decorator 与显式 Gateway facet
 
-Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteScope('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
+Decorator 只表达“该方法参与 Remote 约定”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteScope('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
 
 SRC 运行时允许 decorator 在 `dsh-type-meta` 内部的 `WeakMap` 记录 prototype、方法名和调用模式。它不向 Service 实例、prototype、constructor 或方法函数写入自定义属性。
 
@@ -147,7 +147,7 @@ InvocationDescriptor {
 
 参数顺序来自方法签名，HTTP 字段来自参数名或 lookup 声明。取消 descriptor 只保留最后一个 `signal` 位置，并使其不进入具名 `args`；实际 signal 由 Connection 或直接调用 Gateway 的调用方提供。Gateway 不根据请求内容推断可选字段、Context 类型、lookup 类型或缺失参数，也不会合成业务默认值。
 
-LIB codec 带有 Zod schema 和“package + 公共 subpath + export name”的规范 `typeSymbol`；SRC codec 只标记 `src-json`。Host 和消费端运行在不同 JavaScript realm 时会各自持有 Zod 实例，但这些实例由同一 TypeRT 模型和 symbol key 生成。
+LIB codec 带有 Zod schema 和「package + 公共 subpath + export name」的规范 `typeSymbol`；SRC codec 只标记 `src-json`。Host 和消费端运行在不同 JavaScript realm 时会各自持有 Zod 实例，但这些实例由同一 TypeRT 模型和 symbol key 生成。
 
 descriptor 只存在于两端本地 registry。wire 上只有 `/api` channel、endpoint 和 `{ args }` payload；Host 用自己的 descriptor 解码和调用，Client 用自己的对应 descriptor 编码参数和验证结果。
 
@@ -217,7 +217,7 @@ Host lib build
 
 现有顶层 `build` 仍表现为先 `build:lib`、再 `build:web`，但 `build:lib` 内部必须先完成 Host 与 Remote artifact，再启动 Client TypeScript 编译。一次干净构建不能依赖上次残留的 `.d.ts`。
 
-即使主要输入是源文件，需要通过编译器解析消费方 surface 的仓库门禁也有相同的前置条件。公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先执行 Host 契约 pass。门禁调度器仅可在显式的 TypeRT 契约依赖或完整构建依赖完成后使用对应的 `*:contracts-ready` 变体，使并行 lane 既不会读取缺失的声明，也不会针对同一输出并发运行多个生成器。
+即使主要输入是源文件，需要通过编译器解析消费方 surface 的仓库门禁也有相同的前置条件。公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先执行 Host 约定 pass。门禁调度器仅可在显式的 TypeRT 约定依赖或完整构建依赖完成后使用对应的 `*:contracts-ready` 变体，使并行 lane 既不会读取缺失的声明，也不会针对同一输出并发运行多个生成器。
 
 ## `/remote` 包入口
 
@@ -236,7 +236,7 @@ Host lib build
 import goalsRemote from '@deepseek-ai/dsh-goal/remote'
 ```
 
-该 import 让 `.d.ts` 的 map augmentation 进入当前 TypeScript project，同时把同一契约的 JS descriptor 作为值交给运行时。未 import 的业务包不会扩展当前 project 的 Remote API 类型。
+该 import 让 `.d.ts` 的 map augmentation 进入当前 TypeScript project，同时把同一约定的 JS descriptor 作为值交给运行时。未 import 的业务包不会扩展当前 project 的 Remote API 类型。
 
 业务 package 的发布文件必须同时包含 `lib/typert.remote-client.d.ts.map` 和 map 指向的 `src` 文件。生成 DTS 以 `//# sourceMappingURL=typert.remote-client.d.ts.map` 引用相邻 map；map 中的 source 从 `lib` 相对指向业务源码，例如 `../src/index.ts`。`/remote` export 不单独列出 map，package `files` 负责把它与源码一起发布。
 
@@ -309,7 +309,7 @@ await ctx.remote.$mount(goalsRemote)
 await ctx.remote.$mount(sessionsRemote)
 ```
 
-Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientRemote` 契约和 Cordis `ctx.remote` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
+Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientRemote` 约定和 Cordis `ctx.remote` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
 
 `ctx.remote.$mount()` 把 contribution 注册到 `TypeRT.remotes`，安装它的 namespace Service 和具体方法，并在它们就绪后才 resolve。调用该方法的 Cordis fiber 持有 disposer。endpoint 重复、同一 namespace/method 模式冲突或 descriptor 与现有类型身份冲突时直接失败。
 
@@ -343,7 +343,7 @@ Remote DTS、Remote JS、`TypeRTClientRemote`、`InvocationDescriptor`、Remote
 
 TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均不属于本期实现。
 
-Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 契约变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
+Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 约定变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
 
 ## SRC 与 LIB 运行模式
 
@@ -454,7 +454,7 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 - TypeRT generator：分析 Host/Client Program，生成本地 face 和 Remote 消费端投影，并生成规范 symbol/Zod 信息。
 - TypeRT runtime：分别保存当前环境的 local reflection 与导入的 Remote contribution。
 - `@deepseek-ai/dsh-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 Remote namespace Service 和方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
-- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientRemote` 契约向业务包暴露合并后的 Remote 类型。
+- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientRemote` 约定向业务包暴露合并后的 Remote 类型。
 - Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、共享 `/api` route 与复合 FetchHandler、API Proxy 回退、RPC envelope、rpcId、序列化、trust 和错误传输。
 - Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
 - API Proxy Host 组合：向 API Remotes 提供 Web Agent 默认值和 scope 设置，并让旧方法使用同一个 `agentFor()`。
@@ -474,7 +474,7 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 **让 decorator 在运行时完成严格反射。** JavaScript decorator 无法恢复擦除后的 TypeScript 类型、公共符号身份和完整 Zod codec；向 constructor 注入 compiler 私有 symbol 又会隐藏业务类的真实依赖，因此严格信息由 TypeRT compiler 生成。
 
-**SRC 启动时使用 preload、loader hook 或完整 `ts.Program`。** 这能复用 LIB 分析，但增加所有源码启动入口的要求。SRC 只需要可用的弱 descriptor，因此采用 decorator 标记、函数参数名和显式 provider；严格检查留给 LIB contract pass。
+**SRC 启动时使用 preload、loader hook 或完整 `ts.Program`。** 这能复用 LIB 分析，但增加所有源码启动入口的要求。SRC 只需要可用的弱 descriptor，因此采用 decorator 标记、函数参数名和显式 provider；严格检查留给 LIB 约定 pass。
 
 **手写 Client interface。** 手写接口不能保证只包含 Remote 标记的方法，也会与 Host 签名、lookup ID 和 Zod schema 漂移，因此 Client 类型从 Host Program 自动投影。
 
@@ -490,9 +490,9 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 ## 验证
 
-- Goal Service 直接装饰业务签名已经符合 Remote 契约的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
+- Goal Service 直接装饰业务签名已经符合 Remote 约定的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
 - 一次干净的 `build:lib` 会在 Client 编译前生成 Host 与消费方 Remote 产物，包括业务包 `/remote` 下的 JS、DTS 和 declaration map。
-- `clean` 后，单独运行 `typecheck`、`lint` 或 `doc-typecheck` 都会重新生成 Remote 契约；pre-push 钩子使用同一个已包含契约准备步骤的 typecheck，CI 中的源码消费方则等待一次共享的契约 pass。
+- `clean` 后，单独运行 `typecheck`、`lint` 或 `doc-typecheck` 都会重新生成 Remote 约定；pre-push 钩子使用同一个已包含约定准备步骤的 typecheck，CI 中的源码消费方则等待一次共享的约定 pass。
 - 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `ctx.remote.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
 - 挂载同一次 import 得到的 JS contribution 会提供 endpoint、参数、结果、lookup、Context 和 Zod 反射，并在无需手写 stub 的情况下实体化调用。
 - Root 与 Agent-scoped 调用会经过真实的共享 `/api` carrier，将 `agentId` 解析为活 Agent，调用原始 Goal receiver，并通过既有 RPC envelope 返回。
@@ -504,19 +504,19 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 ## 后果
 
-Remote API 类型依赖生成的 `lib` 声明，构建与门禁编排必须在对 Host 和 Client 消费方进行编译或语义分析之前完成 Host 契约 pass；顺序错误会使干净环境中的命令依赖陈旧产物。
+Remote API 类型依赖生成的 `lib` 声明，构建与门禁编排必须在对 Host 和 Client 消费方进行编译或语义分析之前完成 Host 约定 pass；顺序错误会使干净环境中的命令依赖陈旧产物。
 
-源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布契约。
+源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布约定。
 
 SRC 弱 descriptor 不验证普通 JSON 内部结构。Host Remote 签名变化后，Web 和严格类型消费方必须重新执行 lib build，因为系统没有增量 contract watcher。
 
 公共类型唯一性要求业务 DTO 具有纯类型出口，可能暴露现有包中 Host 类型与实现入口混杂的问题。构建会拒绝这些边界，而不是复制类型掩盖问题。
 
-类型 import 与运行时 contribution 是两种不同效果。`import type {}` 只扩展静态 Remote surface；真实调用环境遗漏 value contribution 时，Client Remote Service 必须以明确的“Remote 未挂载”错误失败。
+类型 import 与运行时 contribution 是两种不同效果。`import type {}` 只扩展静态 Remote surface；真实调用环境遗漏 value contribution 时，Client Remote Service 必须以明确的「Remote 未挂载」错误失败。
 
 Browser 与 Host 各自持有 Zod 实例，不能依赖对象 identity 跨 realm 比较；一致性只由规范 symbol key、同一生成模型和 wire 行为保证。
 
-消费端可以导入 Host 当前未挂载的 Remote contract。类型表示“该协议能力已被消费端选择”，不保证目标进程当前存在对应 Service；运行时 endpoint 不可用必须明确失败。
+消费端可以导入 Host 当前未挂载的 Remote contract。类型表示「该协议能力已被消费端选择」，不保证目标进程当前存在对应 Service；运行时 endpoint 不可用必须明确失败。
 
 Connection 的通用 channel API 必须同时适合当前 HTTP carrier 和后续 WebSocket carrier。若 Client Remote 或 Gateway 暴露 `fetch`、HTTP request 或 route handle，WebSocket 迁移会再次穿透 Remote 层，因此这些物理对象必须留在 Connection 内部。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
index 2969995da6..fb4922d5c5 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
 2026-08-03-pi-ai-declared-provider-catalog.md: f908eb6293b77680193fcd8f7be7a9089477855a
-2026-08-03-pi-ai-declared-provider-catalog.zh.md: ce91abd6dc71f790c72766cd3f819096d596182c
+2026-08-03-pi-ai-declared-provider-catalog.zh.md: 9ed1abc5cedbba637466531f7fc48f73c1e18a0d
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
index ce91abd6dc..9ed1abc5ce 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
@@ -14,14 +14,14 @@ Status: implemented
 
 提供方路由是一份**声明**，已安装 catalog 是它的默认值。`resolveProfiles` 不再拿路由键去核对 `getBuiltinProviders()`，而是把每条路由解析成一份物化模型列表，外加服务它的 pi-ai `Provider`：
 
-- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——本 note 写就时为 `id`、`name`、`contextWindow`、`maxTokens`；[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 之后加入了 `reasoningEfforts` 与 `compat`，当初「推理沿用已安装条目或直接缺席」的立场也在那里被重新审视（孤立的能力布尔量仍被拒绝；带 wire 拼写的逐档位完整声明没有它那个问题）。定价与输入模态仍不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。物化时以已安装条目铺底、再覆盖已配置的字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
+- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——本 note 写就时为 `id`、`name`、`contextWindow`、`maxTokens`；[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 之后加入了 `reasoningEfforts` 与 `compat`，当初「推理（reasoning）沿用已安装条目或直接缺席」的立场也在那里被重新审视（孤立的能力布尔量仍被拒绝；带 wire 拼写的逐档位完整声明没有它那个问题）。定价与输入模态仍不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。物化时以已安装条目铺底、再覆盖已配置的字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
 - `provider.ts` 构造路由的 `Provider`。保持 catalog 协议不变的 catalog 路由会**复用**已安装提供方，只替换 `getModels()`；其余路由都由 `createProvider()` 基于一张协议表构造，表中条目正是 pi-ai 自己的提供方工厂所用的 `@earendil-works/pi-ai/api/*.lazy` factory。该表刻意窄于 pi-ai 的完整 API 集合——只保留 profile 能用密钥、端点与标头完整描述的协议，因此 Bedrock（SigV4 加 region）、Vertex（project、location、ADC）、Azure（提供方环境加 api-version）与 Codex（OAuth）不在其中，而不是被当作无法认证的路由提供出去。catalog 路由仍可经自己的 provider 抵达它们；被拒的只有显式覆盖。
 - `adapter.ts` 把每次解析变成一份**不可变快照**——profiles 加上持有这些 provider 的 `createModels()` 集合——每个操作都在自己第一个 `await` 之前整体捕获一份。
-- 模型**显式配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`；从已安装 catalog 继承来的那份不会：pi-ai 要求 `Model.maxTokens` 表示模型的输出**能力**，而 `defaultMaxTokens` 是部署选定、发给未点名上限的请求的那个值，把前者物化成后者会让每个请求都被一个无人选择的数字封顶。
+- 模型**显式配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`；从已安装 catalog 继承来的那份不会：pi-ai 要求 `Model.maxTokens` 表示模型的输出*能力*，而 `defaultMaxTokens` 是部署选定、发给未点名上限的请求的那个值，把前者物化成后者会让每个请求都被一个无人选择的数字封顶。
 
 ### 快照，而不是共享集合
 
-`Models.streamSimple()` 惰性解析 provider——在返回的流首次被消费时，而那已在适配器 await 路由凭据之后。因此就地改动的单一集合，会让一个在旧配置下开始的请求在新配置下结束，或者撞上一个已不存在的 provider，尽管 `llm.prepareCall()` 早已冻结了该步的 config 并捕获了其适配器注册。配置变化改为构造**新**集合，正在被使用的那个原封不动，于是 seam 的每步冻结得以贯通到底：回复途中切换模型在下一步生效，绝不影响在途的那一步。
+`Models.streamSimple()` 惰性解析 provider——在返回的流首次被消费时，而那已在适配器 await 路由凭据之后。因此就地改动的单一集合，会让一个在旧配置下开始的请求在新配置下结束，或者撞上一个已不存在的 provider，尽管 `llm.prepareCall()` 早已冻结了该步的 config 并捕获了其适配器注册。配置变化改为构造*新*集合，正在被使用的那个原封不动，于是 seam 的每步冻结得以贯通到底：回复途中切换模型在下一步生效，绝不影响在途的那一步。
 
 ### 目录原子替换
 
@@ -39,11 +39,11 @@ pi-ai 把没有推理元数据的模型报告为只支持 `off` 一档，而适
 
 ### 凭据留在 pi-ai 之外
 
-pi-ai 的 `Models` 自带一套凭据概念——按提供方 id 索引的 `CredentialStore`，配合 `envApiKeyAuth` 解析 `credential.key ?? env(VAR)`。采用它会在 `ctx.credentials` 之外制造第二个凭据事实源，更糟的是会把 harness 明确禁止的环境回落重新引进来：点名了却取不到的 `apiKeyEnv` 必须以 `MISSING_CREDENTIAL` 失败，而不是用环境里恰好持有的某个无关密钥完成认证。
+pi-ai 的 `Models` 自带一套凭据概念——按提供方 id 索引的 `CredentialStore`，配合 `envApiKeyAuth` 解析 `credential.key ?? env(VAR)`。采用它会在 `ctx.credentials` 之外制造第二个凭据真源，更糟的是会把 harness 明确禁止的环境回落重新引进来：点名了却取不到的 `apiKeyEnv` 必须以 `MISSING_CREDENTIAL` 失败，而不是用环境里恰好持有的某个无关密钥完成认证。
 
 `ModelsImpl.applyAuth` 会把 `options.apiKey` 当作该请求的密钥，但这条路必须经由一个声明了 api-key 方法的提供方：`resolveProviderAuth` 在覆盖存在时短路到该方法，否则依次落到凭据存储与环境发现；若提供方压根没有 api-key 方法，它返回空，请求随即以 `Provider is not configured` 失败。因此 harness 一如既往经自身 seam 解析路由密钥，并把结果作为请求的 `apiKey` 传入；该集合构造时不带任何凭据存储。
 
-路由的 auth 由此推出。catalog 路由保留已安装提供方自己的 `auth`，从而为不点名凭据的 profile 保住其提供方原生环境发现，且在 `api` 覆盖之下同样保留：提供方读哪个环境是提供方自身的属性，而非其模型所讲协议格式的属性。例外是没有 api-key 方法的 catalog 提供方——`openai-codex` 只走 OAuth——此时点名了凭据的 profile 会在提供方原有 auth 之外再获得 harness 的方法，否则它配置的密钥会在任何请求发出之前被拒。这类路由上不点名凭据的 profile 什么也不加、并保留那句诚实的拒绝：本适配器没有可供解析的 OAuth 存储。手工声明的路由则获得一个 harness 自有的 `ApiKeyAuth`，它报告「已配置但无密钥」而非「未配置」，把该要求留给协议——那才是它真正所在的位置：pi-ai 的 OpenAI 兼容实现仍要求密钥或 `Authorization` 标头，并且会自己说出来。
+路由的 auth 由此推出。catalog 路由保留已安装提供方自己的 `auth`，从而为不点名凭据的 profile 保住其提供方原生环境发现，且在 `api` 覆盖之下同样保留：提供方读哪个环境是提供方自身的属性，而非其模型所讲协议格式（wire format）的属性。例外是没有 api-key 方法的 catalog 提供方——`openai-codex` 只走 OAuth——此时点名了凭据的 profile 会在提供方原有 auth 之外再获得 harness 的方法，否则它配置的密钥会在任何请求发出之前被拒。这类路由上不点名凭据的 profile 什么也不加、并保留那句诚实的拒绝：本适配器没有可供解析的 OAuth 存储。手工声明的路由则获得一个 harness 自有的 `ApiKeyAuth`，它报告「已配置但无密钥」而非「未配置」，把该要求留给协议——那才是它真正所在的位置：pi-ai 的 OpenAI 兼容实现仍要求密钥或 `Authorization` 标头，并且会自己说出来。
 
 ## Alternatives considered
 
@@ -54,14 +54,14 @@ pi-ai 的 `Models` 自带一套凭据概念——按提供方 id 索引的 `Cred
 
 - **保留单个可变 `Models` 集合并重新同步。** 分配更少，且对每个同步完成解析的操作都是正确的；唯独对那个不同步的操作恰恰是错的：`stream()` 会在捕获模型与派发模型之间 await 一次凭据。
 - **用「先 dispose 再注册」模拟目录原子替换。** 无需改 seam，且在新集合有效时确实可用——而那正是从不需要原子性的那种情形。
-- **运行时动态 catalog**——`fetchModels` 加 `ModelsStore`，后台刷新。本次变更拒绝：它把模型列表变成需要缓存、失效与离线路径的外部可变状态，而产品需求是一次性的发现动作、其结果由用户采纳进 `settings.yaml`。该动作属于配置界面，与之一并暂缓；`settings.yaml` 始终是「路由服务什么」的唯一事实源。
+- **运行时动态 catalog**——`fetchModels` 加 `ModelsStore`，后台刷新。本次变更拒绝：它把模型列表变成需要缓存、失效与离线路径的外部可变状态，而产品需求是一次性的发现动作、其结果由用户采纳进 `settings.yaml`。该动作属于配置界面，与之一并暂缓；`settings.yaml` 始终是「路由服务什么」的唯一真源。
 
 ## Consequences
 
-配置一个提供方不再取决于 pi-ai 的发布节奏。网关、自建服务，或比锁定 catalog 更新的模型，都是一次 `settings.yaml` 编辑，过期的上下文窗口也能就地更正。废弃的 `/compat` 导入已经消失，因此 pi-ai 删除它不再是破坏性事件。`defaultMaxTokens` 现在只在部署明确给出时才自配置流出，不会从 catalog 元数据里发明一个上限。
+配置一个提供方不再取决于 pi-ai 的发布节奏。网关、自建服务，或比锁定 catalog 更新的模型，都是一次 `settings.yaml` 编辑，过期的上下文窗口也能就地更正。废弃的 `/compat` 导入已经消失，因此 pi-ai 删除它不再是破坏性事件。`defaultMaxTokens` 现在会在部署明确给出时从配置中传入，不会从 catalog 元数据里发明一个上限。
 
 代价是：声明式路由会让 `settings.yaml` 变长，因为它必须自报端点、协议与模型 id。`api` 作用于整条路由，因此混合协议的 catalog 路由无法承载另一种协议的模型——把它拆成两个路由键是变通办法。没有任何环节查询提供方的 `/models`，因此模型列表的新鲜度只到最近一次编辑为止。有一种情形下报错形状发生变化：auth 解析不出任何值的路由，现在会在任何网络调用之前把 pi-ai 自己的诊断作为错误 `finish` 分片呈现，而此前的适配器会发出无密钥请求并呈现提供方的 401。
 
 ## Testing
 
-`tests/catalog.spec.ts` 针对本地 mock 服务器端到端覆盖该契约：手工声明的路由带着自己的凭据流向自己的端点、它在可配置提供方目录中的出现、每模型覆盖从已安装 catalog 继承默认值、向 catalog 路由添加模型、带与不带端点覆盖的协议改指、catalog 独有元数据在覆盖后存活、无密钥姿态及其 `Authorization` 标头变通、只走 OAuth 的 catalog 路由用 profile 点名的密钥完成认证而无密钥者保持未配置、改指协议的路由保留其 catalog auth，以及每一种点名路由或模型的解析失败。`tests/catalog.spec.ts` 还钉住了快照与目录两项契约：在途请求即便其路由集在 credential await 期间改变，仍抵达它解析时对应的端点；下一个请求取用新配置；冲突的声明路由让目录保持完好；声明路由的条目随其 profile 出现与离开。`packages/llm/llm/tests/topology.spec.ts` 覆盖 `replace`——拒绝他人已拥有的候选同时保住当前集合、接受对自身条目的替换、允许空集合，以及 dispose 之后失败。`tests/sdk-options.spec.ts` 把 SDK 边界从已移除的 `/compat` 导入改指到协议表的 lazy api 模块，同时钉住「setup 失败以终止性错误分片而非抛出的形式抵达」。twin 的[设计验证角色](2026-06-13-twin-llm-adapters.md)不变。
+`tests/catalog.spec.ts` 针对本地 mock 服务器端到端覆盖该约定：手工声明的路由带着自己的凭据流向自己的端点、它在可配置提供方目录中的出现、每模型覆盖从已安装 catalog 继承默认值、向 catalog 路由添加模型、带与不带端点覆盖的协议改指、catalog 独有元数据在覆盖后存活、无密钥姿态及其 `Authorization` 标头变通、只走 OAuth 的 catalog 路由用 profile 点名的密钥完成认证而无密钥者保持未配置、改指协议的路由保留其 catalog auth，以及每一种点名路由或模型的解析失败。`tests/catalog.spec.ts` 还钉住了快照与目录两项约定：在途请求即便其路由集在 credential await 期间改变，仍抵达它解析时对应的端点；下一个请求取用新配置；冲突的声明路由让目录保持完好；声明路由的条目随其 profile 出现与离开。`packages/llm/llm/tests/topology.spec.ts` 覆盖 `replace`——拒绝他人已拥有的候选同时保住当前集合、接受对自身条目的替换、允许空集合，以及 dispose 之后失败。`tests/sdk-options.spec.ts` 把 SDK 边界从已移除的 `/compat` 导入改指到协议表的 lazy api 模块，同时钉住「setup 失败以终止性错误分片而非抛出的形式抵达」。twin 的[设计验证角色](2026-06-13-twin-llm-adapters.md)不变。
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 22935b42ca..6e2e6e1453 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
 2026-08-04-configuration-source-ownership.md: ef30a22c120af1437f348e52843e1dd45c9837ae
-2026-08-04-configuration-source-ownership.zh.md: c1567c6e823a0bc8ed8d1f9ed50a11a5d204ede8
+2026-08-04-configuration-source-ownership.zh.md: ef352ce4c7b8eef8fc2dcd3aa7154bda770ffd4e
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index c1567c6e82..ef352ce4c7 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -16,7 +16,7 @@ endpoint 可以被项目重定向。调用目录的 `.env` 和其他层一样会
 
 ## Decision
 
-**非密钥值走同一条顺序。** 每个本身不是凭据的可配置值都按同一顺序解析；各领域的差别只在于哪些层存在。
+**非机密值走同一条顺序。** 每个本身不是凭据的可配置值都按同一顺序解析；各领域的差别只在于哪些层存在。
 
 ```text
 explicit for this run     per-operation override, CLI argument
@@ -29,7 +29,7 @@ explicit for this run     per-operation override, CLI argument
 
 自上而下依次是：本次运行的显式意图、用户 settings、composition、本次启动的 shell、被发现的文件、默认值。
 
-settings 在 composition 之上，因为 [settings seam](2026-07-28-user-settings-seam.md) 就是这么做的：插件把自己的 cordis entry config 注册为 `base` 层，用户 section 叠加其上，而 seam 无法区分某个值是 profile 的 bundle 设的，还是它的用户 patch 层或某个 `--patch` overlay 设的——它们都以 entry config 的形式抵达。产品 CLI（命令行界面）没有高于已存 settings 的手段，因此需要把某字段钉死、不被用户已存 settings 覆盖的部署方，应自带 bin 或 loader 配置树，或者干脆不挂载 settings provider。composition 仍然高于环境，所以 shell 里陈旧的 `DEEPSEEK_BASE_URL` 无法改写已配置的 endpoint。
+settings 在 composition 之上，因为 [settings seam](2026-07-28-user-settings-seam.md) 就是这么做的：插件把自己的 cordis entry config 注册为 `base` 层，用户 section 叠加其上，而 seam 无法区分某个值是 profile 的 bundle 设的，还是它的用户 patch 层或某个 `--patch` overlay 设的——它们都以 entry config 的形式抵达。产品 CLI（命令行界面）没有高于已存 settings 的手段，因此需要把某字段钉死、不被用户已存 settings 覆盖的部署方，应自带 bin 或 loader 配置树，或者干脆不挂载 settings 提供方。composition 仍然高于环境，所以 shell 里陈旧的 `DEEPSEEK_BASE_URL` 无法改写已配置的 endpoint。
 
 **凭据保留一条更窄的独立顺序**，本 Note 不把它并入上表：
 
@@ -40,13 +40,13 @@ inherited process environment      (read-only, wins)
 > $DSH_HOME/.env
 ```
 
-继承环境优先，因为 `DEEPSEEK_API_KEY=… dsh`、CI 机密与容器 `-e` 是运维必须能按次施加、且无需改动机器状态的那一种覆盖；而它无法从进程内部修改，就必须*可见地*只读。配置本应只携带*引用*——解析哪个名字——该名字本身遵循上面的非密钥顺序。
+继承环境优先，因为 `DEEPSEEK_API_KEY=… dsh`、CI 机密与容器 `-e` 是运维必须能按次施加、且无需改动机器状态的那一种覆盖；而它无法从进程内部修改，就必须*可见地*只读。配置本应只携带*引用*——解析哪个名字——该名字本身遵循上面的非机密顺序。
 
 **harness 被启动于其中的项目默认可信，且不做询问。** 一个 checkout 可以携带自己的 endpoint、自己的普通变量和自己的密钥；密钥排在受管存储之下，因此通过 Models 页存下的密钥绝不会被 checkout 中恰好带有的那一个顶掉。`EnvironmentSnapshot.getFrom(name, sources)` 仍然只搜索调用方点名的层，省略某层仍是拒绝而不是降级——该机制是为「某一层必须不可达」的那些决策准备的，而项目层今天不在其列。
 
-**信任不延伸到改变 harness 本身。** `loadLayeredEnv` 会在加载时、且在物化任何内容之前，拒绝任何设置了下列变量的 `.env`：决定进程如何启动的（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD`）、决定运行时在执行被要求运行的程序之前先执行哪些代码的（`BASH_ENV`、`PERL5OPT`、`PYTHONSTARTUP`、`RUBYOPT`、`JAVA_TOOL_OPTIONS`、Git 的钩子命令）、决定模型可见指令从哪里加载的（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），以及决定网络如何抵达与信任的（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
+**信任不延伸到改变 harness 本身。** `loadLayeredEnv` 会在加载时、且在物化任何内容之前，拒绝任何设置了下列变量的 `.env`：决定进程如何启动的（`PATH`、`SHELL`、`NODE_OPTIONS`、`LD_PRELOAD`）、决定运行时在执行被要求运行的程序之前先执行哪些代码的（`BASH_ENV`、`PERL5OPT`、`PYTHONSTARTUP`、`RUBYOPT`、`JAVA_TOOL_OPTIONS`、Git 的钩子命令）、决定模型可见指令从哪里加载的（整个 `DSH_*` 命名空间、`HOME`、`XDG_*`），以及决定网络如何访问以及如何建立信任的（proxy 与 CA 变量）。匹配不区分大小写，因此 `https_proxy` 不是绕过手段。
 
-这条界线在于：它们无需任何用户动作、在任何一轮开始之前、且在权限策略与沙箱之外就生效。`DSH_PERMISSION_MODE` 会关掉让「信任项目」根本成立的那道审批，而 `BASH_ENV` 会在 bash 工具发出的每一次 `bash -c` 上执行项目指定的文件——项目的代码在 agent 的策略下运行是约定，项目改写那份策略不是。一个变量一个变量地枚举是必输的游戏，所以整个 `DSH_*` 命名空间被拒绝而不是只拒绝一份经审查的子集，也所以这份清单是按变量*做什么*而不是按哪个运行时拥有它来组织的。不设逃生门：逃生门本身总得从某处读取，而任何被发现的文件能设置的东西，就是那个漏洞本身。
+这条界线在于：它们无需任何用户动作、在任何轮次开始之前、且在权限策略与沙箱之外就生效。`DSH_PERMISSION_MODE` 会关掉让「信任项目」根本成立的那道审批，而 `BASH_ENV` 会在 bash 工具每次发出 `bash -c` 时执行项目指定的文件——项目的代码在 agent（智能体）的策略下运行是约定，项目改写那份策略不是。一个变量一个变量地枚举是必输的游戏，所以整个 `DSH_*` 命名空间被拒绝而不是只拒绝一份经审查的子集，也所以这份清单是按变量*做什么*而不是按哪个运行时拥有它来组织的。不设逃生门：逃生门本身总得从某处读取，而任何被发现的文件能设置的东西，就是那个漏洞本身。
 
 **`packages/util/environment` 拥有该快照**，刻意做成 utility 而不是三包能力 seam。快照在 Cordis 启动前就冻结，并由启动器一次性注入，因此不存在需要切换的运行时实现；消费方需要的只是类型和纯函数，而 `util/` 包能提供这些且不必依赖 UI 包。`environmentOf(ctx)` 返回启动器的快照，或者返回只含继承环境的那一层——SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，它那唯一一层确实就是它被启动时的环境，因此同样的受信查询在那里原样继续工作。
 
@@ -57,12 +57,12 @@ inherited process environment      (read-only, wins)
 - Web 凭据表单现在能压过用户 `.env` 里更旧的密钥；只有在启动 shell 里 export 的密钥才会让它变成只读，诊断信息也会这么说。
 - 含 `DSH_*`、`PATH` 或 proxy 变量的 `.env` 会导致启动失败而不是被应用。把开关放在仓库 `.env` 里的开发者需要改放到 shell——这是一次刻意且响亮的破坏。
 - composition 不再会被陈旧的 shell endpoint 覆盖。但它仍然会被用户已存的 `settings.yaml` 覆盖，这是 settings seam 的分层方式，本 Note 不改变它；产品 CLI 没有高于它的标志，因此需要压过已存 settings 的部署方要自带 bin 或 loader 配置树。
-- 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件；其余变量抵达子进程的限制记录在环境包中。
+- 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件；环境包将其余变量仍可抵达子进程这一点记录为一项限制。
 - Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求经 seam 解析是另一件事。
 
 ## Alternatives considered
 
-**按「来源由谁书写」把凭据并入非密钥顺序。** 尝试过并放弃：它读起来很顺，但 settings seam 已经把 composition 固定在用户 section *之下*，因此「部署授权」根本不是该 seam 能表达的一层；而把 `.credentials.yaml` 抬到启动环境之上，会夺走 CI、容器和一次性 `DEEPSEEK_API_KEY=…` 所依赖的那唯一一种覆盖。两条各自说清自身形状成因的顺序，好过一条两边都描述不准的顺序。
+**按「来源由谁书写」把凭据并入非机密顺序。** 尝试过并放弃：它读起来很顺，但 settings seam 已经把 composition 固定在用户 section *之下*，因此「由部署方写入」根本不是该 seam 能表达的一层；而把 `.credentials.yaml` 抬到启动环境之上，会夺走 CI、容器和一次性 `DEEPSEEK_API_KEY=…` 所依赖的那唯一一种覆盖。两条各自说清自身形状成因的顺序，好过一条两边都描述不准的顺序。
 
 **在项目被显式信任之前，不给它路由与凭据能力。** 作为产品立场被否决：checkout 默认可信，不询问，也不存储信任记录。残留风险是真实的、值得写明——克隆一个携带 `.env`、其中指定了另一个 endpoint 或密钥的仓库，会让该会话经由它——处理它的地方是日后的 project trust 门禁，而不是一条让常见情形都要走仪式的规则。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
index e083adcca5..dffcbad0af 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.md
 2026-08-04-credentials-yaml-and-user-environment-layer.md: 44bdea243671093b34a6338ed1c95bf25bcc78f4
-2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 5f724c7a12365e6e87e03b5926f837a5251b6118
+2026-08-04-credentials-yaml-and-user-environment-layer.zh.md: 3772c1b5cfe6e644490bae927acf5b043572435e
diff --git a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
index 5f724c7a12..3772c1b5cf 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-credentials-yaml-and-user-environment-layer.zh.md
@@ -6,22 +6,22 @@ Status: implemented
 
 ## Problem
 
-`$DSH_HOME/.env` 同时承担了两件互不相容的工作。它是 [`credentials-local`](../../../../packages/credentials/credentials-local/README.md) 的可写密钥存储，因此任何表层都不能把它提升进 `process.env`——一旦提升，每个已存密钥都会读作只读的启动时覆盖，从而阻断从 Models 页轮换密钥。但它的文件名和 dotenv 格式承诺的是一个环境文件，于是用户把非密钥值放进去，而那些值哪儿也到不了：同一个文件里，一个能用的 `DEEPSEEK_API_KEY` 旁边的 `DEEPSEEK_BASE_URL` 会被静默忽略，因为只有凭据 provider 读这份文档，而它只寻址凭据引用。
+`$DSH_HOME/.env` 同时承担了两件互不相容的工作。它是 [`credentials-local`](../../../../packages/credentials/credentials-local/README.md) 的可写密钥存储，因此任何表层都不能把它提升进 `process.env`——一旦提升，每个已存密钥都会读作只读的启动时覆盖，从而阻断从 Models 页轮换密钥。但它的文件名和 dotenv 格式承诺的是一个环境文件，于是用户把非机密值放进去，而那些值哪儿也到不了：同一个文件里，一个能用的 `DEEPSEEK_API_KEY` 旁边的 `DEEPSEEK_BASE_URL` 会被静默忽略，因为只有凭据 provider 读这份文档，而它只寻址凭据引用。
 
-一个文件无法既是由 Harness 拥有并隔离的存储，又是按普通环境规则传播的层。[请求级凭据决策](2026-07-29-request-level-llm-config-credentials.md)当初选择 dotenv 是为了对齐同类产品的 home `.env`，而这种混同直到有非密钥值需要用同一个文件时才暴露出来。
+一个文件无法既是由 Harness 拥有并隔离的存储，又是按普通环境规则传播的层。[请求级凭据决策](2026-07-29-request-level-llm-config-credentials.md)当初选择 dotenv 是为了对齐同类产品的 home `.env`，而这种混同直到有非机密值需要用同一个文件时才暴露出来。
 
 ## Decision
 
 两件工作在 Harness home 下拆成两个文件。
 
-**`.credentials.yaml` 是 provider 管理的存储。** 一个从 `CredentialRef` 到非空字符串的严格 YAML mapping，没有 `version` 字段，也没有包装层：
+**`.credentials.yaml` 是 provider 管理的存储。** 一份从 `CredentialRef` 到非空字符串的严格 YAML 映射，没有 `version` 字段，也没有包装层：
 
 ```yaml
 DEEPSEEK_API_KEY: sk-…
 OPENAI_API_KEY: sk-…
 ```
 
-因为该文档只存放凭据、别无他物，任何偏离都是拒绝而不是跳过条目：非 mapping 的根、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败——启动时和写入时响亮失败，运行期热重载则告警并保留最后可用快照。被静默忽略的键读起来就是「我存进去的密钥没有生效」，而这正是本次变更要消除的失败。dotenv 物理行编辑器被替换为对已解析文档打补丁，因此注释与未触及条目的排版都会保留，任何字符串值都能往返（含多行），也不会再有条目因为缺少可用引号样式而不可写。写锁、read-modify-write、`0700` 目录下的 `0600` 原子写、精确路径 watcher、按内容相等抑制自写、以及 dispose 时的完全停稳，均保持不变。
+因为该文档只存放凭据、别无他物，任何偏离都是拒绝而不是跳过条目：根节点不是映射、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败——启动时和写入时响亮失败，运行期热重载则告警并保留最后可用快照。被静默忽略的键读起来就是「我存进去的密钥没有生效」，而这正是本次变更要消除的失败。dotenv 物理行编辑器被替换为对已解析文档打补丁，因此注释与未触及条目的排版都会保留，任何字符串值都能往返（含多行），也不会再有条目因为缺少可用引号样式而不可写。写锁、read-modify-write、`0700` 目录下的 `0600` 原子写、精确路径 watcher、按内容相等抑制自写、以及 dispose 时的完全停稳，均保持不变。
 
 **`$DSH_HOME/.env` 是用户的普通环境层。** [`dsh-app-boot`](../../../../packages/boot/app-boot/README.md) 中的 `loadLayeredEnv` 先解析调用目录的 `.env`，再解析 Harness home 的，并且只在进程中没有更高层值时物化每个已接受的值，从而得到 `用户 < 项目 < 继承`。Harness home 在两个文件加载*之前*就从继承的环境解析完毕，因此项目 `.env` 无法改变读取哪份用户文档。只有产品 CLI（命令行界面）叠加这两个文件；SDK 与示例 bin 仍通过 `loadEnv` 加载各自的目录，绝不继承开发者的 `$DSH_HOME`。
 
@@ -32,9 +32,9 @@ OPENAI_API_KEY: sk-…
 ## Consequences
 
 - 放弃的：留在 `$DSH_HOME/.env` 里的密钥会被物化进 `process.env`，因而会按[子进程凭据清洗](../../../../packages/subprocess/subprocess/README.md)的规则抵达子进程，而不再留在 provider 内部。它仍是 `.credentials.yaml` 之下的可写后备值；需要由 Harness 拥有并隔离的密钥属于受管文档，后者永不物化。
-- 换来的：用户 `.env` 里的非密钥值终于生效，这正是最初的缺陷；文档格式可以拒绝它无法承担的内容；`0600` 保护的是一个只存密钥的文件，而不是一个我们同时叫用户往里写普通配置的文件。
-- provider 写入时用的 `0600` 同样约束它读取的内容：在 POSIX 上，只要文档带有任何 group 或 other 权限位，就会在读取内容之前让启动失败——启动时与每次 reload 都检查，诊断里给出 `chmod 600` 的修复命令。Windows 没有可检查的 mode（其 ACL 无法在此表达），因此跳过该检查而不是伪造它。
-- `0600` 这条边界仍然只挡其他 OS 用户、挡不住模型，本次拆分未改变这一点——该限制及 keychain provider 的延后项归 [provider README](../../../../packages/credentials/credentials-local/README.md) 所有。
+- 换来的：用户 `.env` 里的非机密值终于生效，这正是最初的缺陷；文档格式可以拒绝它无法承担的内容；`0600` 保护的是一个只存密钥的文件，而不是一个我们同时叫用户往里写普通配置的文件。
+- 提供方写入时使用的 `0600` 同样约束它读取的内容：在 POSIX 上，只要文档带有任何 group 或 other 权限位，就会在读取内容之前让启动失败——启动时与每次 reload 都检查，诊断里给出 `chmod 600` 的修复命令。Windows 没有可检查的 mode（其 ACL 无法在此表达），因此跳过该检查而不是伪造它。
+- `0600` 这条边界仍然只挡其他 OS 用户、挡不住模型，本次拆分未改变这一点——该限制及 keychain 提供方的延后项归 [提供方 README](../../../../packages/credentials/credentials-local/README.md) 所有。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
index 4c5c87821f..141a08a5b6 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
 2026-08-04-declaring-a-provider-from-the-models-page.md: 53996e488c467e00754837b83b7a33994d4813ee
-2026-08-04-declaring-a-provider-from-the-models-page.zh.md: fa61c48492eabf51f3d325078ceffa84ac52d12c
+2026-08-04-declaring-a-provider-from-the-models-page.zh.md: 3a952aa0a02e0b2906bf16bcc46d14a8f7f71bc4
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
index fa61c48492..3a952aa0a0 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-下面两层已经让 pi-ai 路由变成[一份声明](2026-08-03-pi-ai-declared-provider-catalog.md)，并给了 host [询问草稿端点](2026-08-04-draft-provider-endpoint-interrogation.md)的能力。但两者都没有抵达不编辑 YAML 的人：Models 页仍然只为每个提供方提供一个 API 密钥输入框和一个装着 API 地址的折叠区，因此接入一个网关意味着打开 `$DSH_HOME/settings.yaml` 并知道 profile 的形状，更正一个过期的上下文窗口也是如此。能力已经存在，界面却没有暴露它。
+下面两层已经让 pi-ai 路由变成[一份声明](2026-08-03-pi-ai-declared-provider-catalog.md)，并给了 host [询问草稿端点](2026-08-04-draft-provider-endpoint-interrogation.md)的能力。但两者都没有抵达不编辑 YAML 的人：Models 页仍然只为每个提供方提供一个 API 密钥输入框和一个装着 API 地址的折叠区，因此接入一个网关意味着打开 `$DSH_HOME/settings.yaml` 并知道 profile 的形状，更正一个陈旧的上下文窗口也是如此。能力已经存在，界面却没有暴露它。
 
 缺的是两件事，而它们的形状并不相同。编辑既有路由的模型，是一张已经存在的卡片上的一个*字段*；声明一条路由则是一次*创建*：路由 id 正在此处被选定，而在选定之前根本没有可编辑的 settings 地址。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml
index ae96598b48..9b8339d0e2 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
 2026-08-04-draft-provider-endpoint-interrogation.md: 65545098cd1063c40081481c1ac8f0afdb4fb390
-2026-08-04-draft-provider-endpoint-interrogation.zh.md: cb09042904f4ab1558c0c214d275a934234955ac
+2026-08-04-draft-provider-endpoint-interrogation.zh.md: 6300e357182e0e81028c6d01026ea93c4fc5202f
diff --git a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
index cb09042904..6300e35718 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 当 pi-ai 路由变成[一份声明而非 catalog 查表](2026-08-03-pi-ai-declared-provider-catalog.md)之后，要接入一个 OpenAI 兼容网关的人，必须先知道它的模型 id 才能完成配置。适配器不再把人限制在已安装 catalog 里——这正是那次改动的目的——但也意味着没有任何东西告诉用户该端点究竟服务什么，而这类端点大多在 `GET /models` 上公布了这份列表。
 
-显而易见的答案——后台刷新的运行时动态 catalog——已随下层一并被拒绝：它会把路由的模型列表变成需要缓存、失效语义与离线路径的外部可变状态，而产品需求要窄得多。真正需要的是**只问一次**，其答案由用户采纳进 `settings.yaml`——从而让 `settings.yaml` 始终是唯一决定路由服务什么的东西。
+显而易见的答案——后台刷新的运行时动态 catalog——已随下层一并被拒绝：它会把路由的模型列表变成需要缓存、失效语义与离线路径的外部可变状态，而产品需求要窄得多。真正需要的是*只问一次*，其答案由用户采纳进 `settings.yaml`，从而让 `settings.yaml` 始终是决定路由服务内容的唯一真源。
 
 麻烦之处在于，被问的对象还不存在。正在新增的提供方没有路由、没有已存 profile、也没有已存凭据；端点与密钥都是用户尚在输入的表单值。而现有的每个 seam 操作都以已注册的提供方路由为键，因此没有一个能承载它。
 
@@ -19,13 +19,13 @@ Status: implemented
 - `ctx.llm.registerModelDiscovery(settingsNs, discover)` 让适配器插件为自己拥有的 namespace 提供「询问端点」的能力，`ctx.llm.discoverModels(settingsNs, request)` 发起询问。没有任何办法枚举哪些 namespace 注册过：询问不了的界面会从那句拒绝里知道，而一份无人消费的列表只会变成一个什么都不做的必填协议字段。以 namespace 为键是对的，因为配置界面已经从可配置提供方目录里拿到了它，也因为正在新增的提供方没有路由可点名。
 - `LlmModelDiscoveryRequest` 携带草稿——可选的 `provider`、可选的 `baseURL`、可选的 `api`、可选的 `apiKey`，以及一个 signal——且 `provider` 与 `baseURL` 至少要有一个，才有东西可答。`provider` 之所以存在，是因为适配器已经描述过的路由直接由它自己的注册表作答、完全不联网；只有它未描述的路由才会抵达某个端点。这条路径不写 settings 与 credentials。唯一的读取是请求所点名路由的凭据：配置界面拿到的是脱敏描述符而非已存的机密，因此草稿里的 `apiKey` 只在用户正键入时才存在；没有这次读取，已配置好的路由就会被不带认证地询问，只换回一个 401。键入的密钥优先，因为那正是被测试的那一把。
 - `LlmDiscoveredModel` 除 `id` 外每个字段都可选，因为大多数列表只公布 id。回复是候选而非 catalog：采纳其中一条的界面仍要补上适配器所需的容量。
-- `llm.discoverModels` 把同一份草稿送过协议层。它的 `apiKey` 是 secret 可以搭乘的第三个、也是最后一个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。它确实会像其他承载机密的载荷一样随客户端外发信封同行，`subscribeEnvelopes()` 观察者看得到；把那个抽头脱敏是整个配置面的改动，不该由这一个方法独自决定。除密钥之外它被钉在回环还有第二个理由：它让宿主向调用方选定的 URL 发起 GET 并回报结果，这是匿名 LAN 调用者不该拥有的探测能力。每一种拒绝都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。
+- `llm.discoverModels` 把同一份草稿送过协议层。它的 `apiKey` 是可承载机密的第三个、也是最后一个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。它确实会像其他承载机密的载荷一样随客户端外发信封同行，`subscribeEnvelopes()` 观察者看得到；把那个抽头脱敏是整个配置面的改动，不该由这一个方法独自决定。除密钥之外它被钉在回环还有第二个理由：它让宿主向调用方选定的 URL 发起 GET 并回报结果，这是匿名 LAN 调用者不该拥有的探测能力。每一种拒绝都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。
 
 `dsh-llm-pi-ai` 的实现只是一次朴素的 `GET {baseURL}/models`，且仅限 OpenAI 兼容协议。它们的列表形状是网关、自建服务与官方端点三方一致认可的那一种，而这正是该动作存在的场景。其余协议一律以 `DISCOVERY_UNSUPPORTED` 回答，让界面回退到手工填写，而不是把猜错的响应形状报成一个空提供方。`baseURL` 按前缀而非待解析 URL 处理，因此 `https://gateway.example/openai/v1` 这类部署路径会保留其路径段。回复在四兆字节上限下读取，且上限落在实际收到的字节上——端点是用户自己填的 URL，因此会先看声明的 `content-length` 作为善意提示，但绝不把它当作边界；这与 `dsh-web-fetch` 面对自己的调用方提供 URL 时所用的两段式形状一致。
 
 ### 为什么不用 pi-ai 自己的 refresh 机制
 
-pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与 `ModelsStore`，而下层本来就在构造 pi-ai `Provider` 对象。把询问接到它们上面，意味着每问一次就要构造一个用完即弃的 provider 与集合，而那个 store 的全部目的——跨运行持久化 catalog——恰恰与「`settings.yaml` 拥有 catalog」的决定相抵触。而且它什么也换不来：**没有任何一个 pi-ai 内置 provider 实现了 `fetchModels`**，因此 HTTP 调用及其响应解析无论如何都是本包的代码。直接 fetch 才如实说出正在发生的事。路由已存的凭据由本插件自己那套逐请求解析器取出，且只在真正要联网的那条分支上进行，因此 catalog 路由作答时既不触碰凭据，也不会因为一把这次询问根本用不上的密钥而失败。
+pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与 `ModelsStore`，而下层本来就在构造 pi-ai `Provider` 对象。把询问接到它们上面，意味着每问一次就要构造一个用完即弃的提供方与集合，而那个 store 的全部目的——跨运行持久化 catalog——恰恰与「`settings.yaml` 拥有 catalog」的决定相抵触。而且它什么也换不来：**没有任何一个 pi-ai 内置提供方实现了 `fetchModels`**，因此 HTTP 调用及其响应解析无论如何都是本包的代码。直接 fetch 才如实说出正在发生的事。路由已存的凭据由本插件自己那套逐请求解析器取出，且只在真正要联网的那条分支上进行，因此 catalog 路由作答时既不触碰凭据，也不会因为一把这次询问根本用不上的密钥而失败。
 
 ## Alternatives considered
 
@@ -33,7 +33,7 @@ pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与
 
 **把能力挂在 `LlmAdapter` 上。** 适配器要经由路由注册才能抵达，因此问题相同；而且这会让一个适配器实例去回答它并不服务的端点的问题。
 
-**让 host 读已存 profile，而不是接受草稿。** 对已配置好的提供方来说，不会有 secret 跨越协议层。但这样一来新增提供方就必须先保存一份不可用的配置，而端点已改却尚未保存的表单会静默地去询问旧地址。接受草稿让用户看见的与被询问的保持一致——凭据是唯一的例外，因为它是界面从不被展示、因而永远无法放进草稿的那个字段。
+**让 host 读已存 profile，而不是接受草稿。** 对已配置好的提供方来说，不会有机密跨越协议层。但这样一来新增提供方就必须先保存一份不可用的配置，而端点已改却尚未保存的表单会静默地去询问旧地址。接受草稿让用户看见的与被询问的保持一致——凭据是唯一的例外，因为它是界面从不被展示、因而永远无法放进草稿的那个字段。
 
 **询问 pi-ai 的每一种协议。** Anthropic 的列表恰好与 OpenAI 共用同一层信封，而 Google 的不是。只支持容易的那几种会让覆盖范围变得任意；更糟的是，猜错的响应形状会与「该提供方没有模型」无法区分。一个明说自己无法被询问的协议，会把用户送去手工填写——那正是既定的回退路径。
 
@@ -43,7 +43,7 @@ pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与
 
 接入网关的人可以直接问它服务什么，而不必去翻它的文档；答案以候选形式抵达，由用户自己挑选，而不是被背着写进配置。seam 因此多了一个刻意保持很小的注册表：每个 namespace 一份、不存储、除 fiber 外没有生命周期。
 
-代价是：协议层多了第三个承载 secret 的载荷，配置面的只写接口从两个方法变成三个。发现能力按协议而非按提供方划分——一个 Anthropic 兼容网关即便其列表能被解析，也仍须手工填写。而且由于没有任何环节会重跑该询问，模型列表的新鲜度依旧只到最近一次编辑为止；这与下层刻意做出的取舍是同一个。
+代价是：协议层多了第三个承载机密的载荷，配置面的只写接口从两个方法变成三个。发现能力按协议而非按提供方划分——一个 Anthropic 兼容网关即便其列表能被解析，也仍须手工填写。而且由于没有任何环节会重跑该询问，模型列表的新鲜度依旧只到最近一次编辑为止；这与下层刻意做出的取舍是同一个。
 
 ## Testing
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
index 2a4879b6aa..8596301883 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
 2026-08-04-websocket-downlink-carrier.md: b41ad687725c55acb8517fe7e93d645f007a0453
-2026-08-04-websocket-downlink-carrier.zh.md: 568240ec14592fba8444e5cc0a3bae2b35c45b94
+2026-08-04-websocket-downlink-carrier.zh.md: 054b91d6b5b8c061eab32e79c4353f6183bd200f
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
index 568240ec14..054b91d6b5 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
@@ -12,17 +12,17 @@ Status: implemented
 
 浏览器真实载体为两类下行流各开一条独立 WebSocket：`/api/events.mux` 只发送 `MuxFrame`，`/api/events.host` 只发送 `HostFrame`。每条 text message 是一份完整的 `ServerRequest` JSON；客户端继续先校验信封，再按路径校验具体 frame union，并把窄形 `RpcRequest<Frame>` 交给既有 `ConnectionController`。两条流保持独立生命周期和无跨流顺序保证，任一条结束仍使整个 connection generation 失败并按既有退避策略重建。
 
-WebSocket 只承担 host→browser 下行。所有 client→host unary 调用和对 server request 的 `respond` 继续使用既有 `POST /api/*`；不在 WebSocket 上接收任何客户端业务 message。`WebApiClient` 因而同时持有 HTTP `fetch` 上行与 WebSocket 下行，而 fixture 和 `InProcessApiClient(toFetchHandler(api))` 继续实现同一 `IApiClient` 双流抽象。进程内 fetch 载体保留 SSE 编解码来检验通道无关的协议同构，但网络 `/api/events.*` GET 只回答 upgrade required，不作为浏览器兼容回退。
+WebSocket 只承担 host→browser 下行。所有 client→host unary 调用和对 server request 的 `respond` 继续使用既有 `POST /api/*`；不在 WebSocket 上接收任何客户端业务消息。`WebApiClient` 因而同时持有 HTTP `fetch` 上行与 WebSocket 下行，而 fixture（测试前置数据）和 `InProcessApiClient(toFetchHandler(api))` 继续实现同一 `IApiClient` 双流抽象。进程内 fetch 载体保留 SSE 编解码来检验通道无关的协议同构，但网络 `/api/events.*` GET 只回答 upgrade required，不作为浏览器兼容回退。
 
 ## Upgrade 与生命周期边界
 
-`dsh-host-webserver` 提供与普通 route 并列的精确 upgrade-route 注册缝，只按 pathname 分发 Node upgrade socket，隔离原始 socket 错误，并在 server teardown 期间等待仍存活的升级连接关闭；它不认识 Harness 帧或 WebSocket message。`dsh-client-connection` 拥有 WebSocket handshake、frame 写出和 stream cancellation，并在 upgrade 前复用 `/api` 的 Host／Origin 信任栅栏。未受信任的 authority 或跨来源 Origin 在 `ctx.apiProxy.events.*` 启动前即被拒绝。
+`dsh-host-webserver` 提供与普通 route 并列的精确 upgrade-route 注册 seam，只按 pathname 分发 Node upgrade socket，隔离原始 socket 错误，并在 server teardown 期间等待仍存活的升级连接关闭；它不认识 Harness 帧或 WebSocket 消息。`dsh-client-connection` 拥有 WebSocket handshake、frame 写出和流取消，并在 upgrade 前复用 `/api` 的 Host／Origin 信任栅栏。未受信任的 authority 或跨来源 Origin 在 `ctx.apiProxy.events.*` 启动前即被拒绝。
 
-浏览器 abort 或 socket close 会取消对应的 host stream；plugin teardown 还会等待该 source iterator 完成清理。host stream 中途抛错时，载体发送一份现有的 `stream/error` frame 后关闭 socket；客户端把该 frame 收敛为连接丢失，不投递给业务 sink。每条 WebSocket 独立报告 open，既有 readiness handshake 仍等待 mux、host 都 open 且 `host.describe` HTTP 调用成功后才发布 connected。
+浏览器 abort 或 socket close 会取消对应的 host 流；插件 teardown 还会等待该 source iterator 完成清理。host 流中途抛错时，载体发送一份现有的 `stream/error` frame 后关闭 socket；客户端把该 frame 收敛为连接丢失，不投递给业务 sink。每条 WebSocket 独立报告 open，既有 readiness handshake 仍等待 mux、host 都 open 且 `host.describe` HTTP 调用成功后才发布 connected。
 
 ## Verification
 
-webserver 契约测试钉住 upgrade pathname 分发、重复注册拒绝、disposer 与 teardown；connection 的真实网络测试钉住两条 WebSocket 各自的信任检查、open、schema 信封、frame 顺序、stream error 与 close cancellation；客户端测试同时证明下行创建 `ws:`／`wss:` URL，而 unary 与 `respond` 仍调用 HTTP `fetch`。组装后的 keyless browser replay 继续覆盖 Chromium、真实 host、HTTP 上行与 WebSocket 下行整链。
+webserver 约定测试钉住 upgrade pathname 分发、重复注册拒绝、资源释放与 teardown；connection 的真实网络测试钉住两条 WebSocket 各自的信任检查、open、schema 信封、frame 顺序、流错误与 close cancellation；客户端测试同时证明下行创建 `ws:`／`wss:` URL，而 unary 与 `respond` 仍调用 HTTP `fetch`。组装后的 keyless browser replay 继续覆盖 Chromium、真实 host、HTTP 上行与 WebSocket 下行整链。
 
 ## Alternatives considered
 
@@ -32,8 +32,8 @@ webserver 契约测试钉住 upgrade pathname 分发、重复注册拒绝、disp
 
 **保留网络 SSE 回退。** 双载体会让生产浏览器路径可因代理或握手差异静默分叉，并让连接上限问题继续存在于一个受支持分支；预发布阶段只交付 WebSocket 下行，失败由既有重连与连接状态显式呈现。
 
-**依赖 HTTP/2 扩大并发连接能力。** 内置开发服务器是明文 Node HTTP/1.1，部署前置代理也不是产品可依赖的不变式；物理下行应直接使用不受该连接池限制的浏览器原语。
+**依赖 HTTP/2 扩大并发连接能力。** 内置开发服务器是明文 Node HTTP/1.1，部署前置代理也不是产品可依赖的不变式；物理下行直接使用不受该连接池限制的浏览器原语。
 
 ## Consequences
 
-每个 Web 页面仍有两条长期下行连接，但它们不再消耗浏览器的 HTTP/1.1 六连接配额；runtime 继续消费原有双流并保留所有重连、补缝和跨流无序语义。代价是 webserver 多一个 upgrade 注册面，connection host 半依赖 WebSocket 实现，并需分别维护浏览器 WebSocket 与进程内 SSE 两种物理编解码；它们共享同一 `ServerRequest`／frame schema 和 `IApiClient` 语义，避免形成第二套业务协议。
+每个 Web 页面仍有两条长期下行连接，但它们不再消耗浏览器的 HTTP/1.1 六连接配额；运行时继续消费原有双流并保留所有重连、seam 修复和跨流无序语义。代价是 webserver 多一个 upgrade 注册面，connection 包的 host 半部新增 WebSocket 实现依赖，并需分别维护浏览器 WebSocket 与进程内 SSE 两种物理编解码；它们共享同一 `ServerRequest`／frame schema 和 `IApiClient` 语义，避免形成第二套应用协议。
diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
index 8a4b3606a8..a38ac586f7 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.md
 2026-08-05-large-session-jsonl-restore-pipeline.md: eab53c683880ef7095233ed8122e532eb5add547
-2026-08-05-large-session-jsonl-restore-pipeline.zh.md: 039e0c193179677b57e742d55f4c7df6bdff852f
+2026-08-05-large-session-jsonl-restore-pipeline.zh.md: e334afde3eacda4ab3c838eaae114acdfeb9bae8
diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
index 039e0c1931..e334afde3e 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解码专用首帧并将其解析为会话头部，后续明文帧则按顺序产出并送入 JSONL 扫描器。
 
-`ZstdFrameDecoder` 为可互换的同步实现提供统一生命周期。首选实现会探测受支持 Node 22、24 与 26 的流结构，在所有完整帧之间复用一个私有原生解码上下文和临时缓冲区，最后只关闭一次。如果私有结构不可用，工厂会选择使用公共 `zstdDecompressSync` 的实现，并保持相同的迭代器和校验和错误契约。迭代器产出的临时视图会在进入下一次迭代前被消费。
+`ZstdFrameDecoder` 为可互换的同步实现提供统一生命周期。首选实现会探测受支持的 Node 22、24 与 26 的流结构，在所有完整帧之间复用一个私有原生解码上下文和临时缓冲区，最后只关闭一次。如果私有结构不可用，工厂会选择使用公共 `zstdDecompressSync` 的实现，并保持相同的迭代器和校验和错误约定。迭代器产出的临时视图会在进入下一次迭代前被消费。
 
 累计帧处理时间约达 500 ms 后，异步读取器会在下一帧边界让出事件循环，并在继续前观察取消信号。单个帧仍是不可分割的同步操作。完整帧必须通过帧结束与校验和验证；只有结构上不完整的最终帧才使用既有前缀解码器进行恢复。
 
@@ -32,7 +32,7 @@ Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解
 
 持久化层把刚物化的 JSON 值转移给 `Session.fromRestore`。这些值是已分离且无环的树，打包的分片行也会展开成新分配的事件。因此，恢复专用路径使用一次 `for...in` 与 `switch` 校验固定事件信封，按事件判别字段执行当前数据形状检查，并通过显式 `pending` 数组迭代冻结所拥有的对象图，不使用循环跟踪集合。`surface` 校验会记录一次转换计划；当同一个候选事件进入日志时，系统直接提交该计划，不再对同一事件规划两次。
 
-普通创建与 fork 路径使用的借用 `seed` 仍会创建 JSON 快照，并使用支持循环检测的通用深度冻结。因此，这项特化仅改变持久恢复，不会放宽调用方所有值的准入要求。
+普通创建与 fork 路径使用的借用 `seed` 仍会创建 JSON 快照，并使用支持循环检测的通用深度冻结。因此，这项特化仅改变持久恢复，不会放宽调用方拥有的值的准入要求。
 
 ## 考虑过的替代方案
 
@@ -41,7 +41,7 @@ Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解
 - **扫描前拼接全部明文**：不予采纳，因为该方案会同时保留压缩输入、完整明文、整份日志的 UTF-8 字符串、行元数据和解析记录，并会重新扫描撕裂帧前缀。
 - **实现流式 JSON 解析器**：不予采纳，因为 JSONL 已提供记录边界；使用原生换行搜索与 `JSON.parse` 就能移除大型中间结构，无需自行维护另一套解析器或改变 JSON 语义。
 - **冻结恢复事件时共享一个 `WeakSet`**：不予采纳，因为 JSON 物化不可能产生循环引用，而该集合会对每个对象增加一次查找，并在遍历期间保留完整对象图。
-- **跳过恢复值的校验或冻结**：不予采纳，因为持久存储属于运行时边界，而 `Session.events` 承诺已接受历史不可变。优化路径利用更强的所有权事实特化这些操作，而不是将其移除。
+- **跳过恢复值的校验或冻结**：不予采纳，因为持久存储属于运行时边界，而 `Session.events` 承诺已接受的历史不可变。优化路径利用更强的所有权事实特化这些操作，而不是将其移除。
 
 ## 后果
 
@@ -49,4 +49,4 @@ Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解
 
 快速解码器依赖运行时探测的 Node 内部接口，但接口不兼容时会改用公共实现，不会改变正确性。系统会在协作式帧边界让出点观察取消信号；截止时间并不是单个帧内部严格的挂钟时间上限。完整事件数组仍会驻留内存，因为它是活跃会话的权威日志；该流水线移除的是重复表示，并未对这份状态做分页。
 
-测试会强制执行两种解码器实现，比对帧顺序和损坏处理行为，覆盖协作式取消与撕裂尾部恢复，并保留既有会话信封、`surface` 与不可变性契约。
+测试会强制使用两种解码器实现，比对帧顺序和损坏处理行为，覆盖协作式取消与撕裂尾部恢复，并保留既有会话信封、`surface` 与不可变性约定。
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index 3e1d038514..be4726cb54 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
 2026-08-05-profile-plugin-bundles.md: 8613e600ad633818abb4319e614230340c3b3876
-2026-08-05-profile-plugin-bundles.zh.md: 03a771364c4f3262801f28e68b96ec5de633e5ec
+2026-08-05-profile-plugin-bundles.zh.md: 3a35f944e115371b5f4702bbe81ec9bc3c314ef0
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index 03a771364c..3a35f944e1 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
+一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest（元数据清单）`dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
 
 已交付的组合改造成了组合包：`@deepseek-ai/dsh-base`（原有基础行合并为一次插入）、`@deepseek-ai/dsh-web-app`（原 web overlay，外加一个接管原启动器代码的运行时粘合插件——前端 dist 解析、web 表层提示词段落、bash 运行时变量、URL 行）、`@deepseek-ai/dsh-headless`（叠加在 base + web-app 之上的一次性 runner 插件）。`dsh web` 保留为携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile，而通用的 `dsh --profile <name>` 只启动 profile，不携带任务；`dsh --config` 被移除（其用途迁移到 `--patch`）。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并在 `add`／`remove` 后调和 `dsh.profile.bundles`（没有组合包声明的包会给出警告，保持为普通依赖）。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 - **依赖扫描加部分 `patchOrder`**（最初的草案）：扫描 `dependencies` 找出组合包、未列出者按字母序排列，会产生两个真源和一条隐式决胜规则；一份显式有序的 `dsh.profile.bundles` 列表更小、完全确定。在 profile 内直接 `pnpm add` 只会安装一个库，不激活任何 patch——行为显式，没有暗中扫描。
 - **内置组合包使用 `link:` 条目**：pnpm 无法对指向安装目录的 `link:` 做版本管理、安装或更新，它会把机器路径嵌进用户文件，并且在安装目录移动后失效。双锚点解析加上每次启动修复的符号链接回退提供了同样的保证（「组合包来自安装目录」），且没有这些繁文缛节。
-- **在组合包 manifest（元数据清单）中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是启动器 patch 的普通配置行，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` seam 是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
+- **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是启动器 patch 的普通配置行，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` seam 是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
 - **组合包的传递式自动应用**：只有直接列在 `dsh.profile.bundles` 中的条目才贡献层；想重新导出另一个组合包 patch 的元组合包，必须在自己的 patch 文件中显式完成。
 
 ## Consequences
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
index 09e63a6a1c..d59721303b 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-session-preparation.md
 2026-08-05-session-preparation.md: 69d39f552ed3041403a24b5aefb435e4e721b09c
-2026-08-05-session-preparation.zh.md: a0ca27eb63552566c918c299bd5fba976687812c
+2026-08-05-session-preparation.zh.md: 23681c7cb52d670482bc83e665ec7731dea98bbd
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
index a0ca27eb63..23681c7cb5 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
@@ -14,13 +14,13 @@ Status: implemented
 
 `SessionPreparation` 持有一个精确的未发布 `Session`，直至发布或回滚。它属于 Session 生命周期，不属于 agent 生命周期或激活机制。新建流程包装 `SessionStore.prepare()` 的结果；持久化恢复则从 `SessionPersistence.prepare()` 取得准备对象。
 
-agent loop（智能体循环）通过同一条设置与发布流水线消费这两种形式：先取得准备对象，围绕 `preparation.session` 构建私有 agent 上下文，等待可选设置完成，再发布该精确 Session 和 agent，并在所有退出路径上 dispose 准备对象。发布后，实时生命周期由现有 Session 与 agent 存储接管；`SessionPreparation` 本身不负责任何 agent 行为。
+agent loop（智能体循环）通过同一条设置与发布流水线消费这两种形式：先取得准备对象，围绕 `preparation.session` 构建私有 agent 上下文，等待可选设置完成，再发布该精确 Session 和 agent，并在所有退出路径上对准备对象执行 dispose（资源释放）。发布后，实时生命周期由现有 Session 与 agent 存储接管；`SessionPreparation` 本身不负责任何 agent 行为。
 
 该机制细化了 [agent 生命周期与所有权决策](2026-06-18-agent-lifecycle-and-ownership-seams.md)中的发布边界，但不替换其所有权模型。
 
 ## 持久化准备生命周期
 
-使用协调器的持久化实现会将一个冷源加载为准备完成的 Session。后端转移新鲜、彼此无别名的元数据和事件，以及标识这些精确值的来源限定 revision；Session 恢复路径直接验证并冻结这些对象图，不再复制。协调器计算中断轮次的 closer，并且只构造一次精确的未发布 Session。其不可变 header 与平衡逻辑事件日志构成读取方借用的 `SessionInspection`，revision 则保留在持久化内部。
+使用协调器的持久化实现会将一个冷源加载为准备完成的 Session。后端转移新鲜、彼此无别名的元数据和事件，以及标识这些精确值的来源限定 revision；Session 恢复路径直接验证并冻结这些对象图，不再复制。协调器计算中断轮次的 closer，并且只构造一次精确的未发布 Session。其不可变 header 与已配平的逻辑事件日志构成读取方借用的 `SessionInspection`，revision 则保留在持久化内部。
 
 `inspect(id, signal?)` 不修改存储。合成 closer 只存在于准备完成的内存视图中，撕裂的物理尾部保持不变。同 id 调用方共享进行中的冷读。准备完成后，该对象可以进入每个协调器自己的 LRU；第一方后端可配置容量，默认保留五个。协调器复用保留源之前会读取该 id 的当前 revision；如果不匹配，就淘汰处于就绪阶段的源并重新完成冷实体化。已经进入提交或为恢复而预留的源仍由其所有者独占，因此并发检查会借用该不可变视图，直至发布或释放。
 
@@ -47,7 +47,7 @@ agent loop（智能体循环）通过同一条设置与发布流水线消费这
 
 ## 验证
 
-共享持久化契约覆盖无变更且已配平的冷检查与后续修复。`persistence.spec.ts` 与 `preparations.spec.ts` 覆盖同 id 进行中读取共享、检查与准备之间的精确 Session 复用、在历史读取与恢复前由 revision 触发刷新、修复只提交一次、独占预留、设置失败后释放、就绪项 LRU 淘汰、预留期间拒绝 append，以及只允许发布预留 Session。后端测试覆盖完整读取与轻量读取使用同一 revision 身份。agent loop 与 continuable subagent 测试覆盖统一发布流水线，以及取消和拆卸期间从检查到恢复的路径。
+共享持久化约定覆盖无变更且已配平的冷检查与后续修复。`persistence.spec.ts` 与 `preparations.spec.ts` 覆盖同 id 进行中读取共享、检查与准备之间的精确 Session 复用、在历史读取与恢复前由 revision 触发刷新、修复只提交一次、独占预留、设置失败后释放、就绪项 LRU 淘汰、预留期间拒绝 append，以及只允许发布预留 Session。后端测试覆盖完整读取与轻量读取使用同一 revision 身份。agent loop 与 continuable subagent 测试覆盖统一发布流水线，以及取消和拆卸期间从检查到恢复的路径。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
index 43c5433343..db32a6923b 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md
 2026-08-05-slot-declaration-injection.md: cb15125977c060144553d7cf75e3c2c26fb1b23b
-2026-08-05-slot-declaration-injection.zh.md: 385cab875bb445ba1ca324fc9b45363b8daf50b6
+2026-08-05-slot-declaration-injection.zh.md: e93ba5e62bbfc76b242a7383bac0e93c1bcc8ff6
diff --git a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
index 385cab875b..e93ba5e62b 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
@@ -1,4 +1,4 @@
-# Agent Note（agent 决策记录）：slot 声明注入与重载生命周期
+# Agent Note: slot 声明注入与重载生命周期
 
 Status: implemented
 
@@ -20,7 +20,7 @@ slot 级热替换还要求两个相互独立的所有者。移除声明方插件
 
 动态重载代码使用普通 Cordis 插件 fiber 作为替换单元：通过 `ctx.plugin()` 激活新模块；挂载替换模块之前，先 dispose 并等待旧 fiber；该 fiber 的 `slots.inject` 与 `slots.register` effect 会随之退出。renderer 订阅会观察到账本移除并卸载组件；无需建立 slot 自有的 fiber 树。
 
-## 失败与生命周期契约
+## 失败与生命周期约定
 
 如果注入创建时声明已经存在，回调 setup 失败会同步上报。延迟声明出现后发生的回调失败，会先取消订阅并回滚已收集的 effect，再在 slot 通知刷新之外上报，避免一个注册方使其他 listener 得不到执行机会。直接调用 `slots.register()` 向未声明 slot 注册仍会抛出异常：注入是显式机制，不会削弱加载时验证。
 
@@ -28,11 +28,11 @@ slot 级热替换还要求两个相互独立的所有者。移除声明方插件
 
 ## 备选方案
 
-**将 `ConversationService` 或其他服务用作顺序屏障。** 服务存在并不能标识相应声明，也不会跟随声明的重载生命周期；只负责呈现的贡献方还会因此产生虚假的包（package）依赖。
+**将 `ConversationService` 或其他服务用作顺序屏障。** 服务存在并不能标识相应声明，也不会跟随声明的重载生命周期；只负责呈现的贡献方还会因此产生虚假的包依赖。
 
-**将每项声明桥接为 `slot:<name>` Cordis 服务。** 这会污染服务命名空间，使拼错的动态 key 变成静默的服务等待，并把账本状态伪装成业务 capability。原生 slot 注入无需改变 Cordis 拓扑，即可提供同样的等待能力。
+**将每项声明桥接为 `slot:<name>` Cordis 服务。** 这会污染服务命名空间，使拼错的动态 key 变成静默的服务等待，并把账本状态伪装成业务能力。原生 slot 注入无需改变 Cordis 拓扑，即可提供同样的等待能力。
 
-**为每个 slot 创建 Cordis 上下文或 fiber。** 贡献方需要的是自身插件生命周期与声明生命周期的交集，而不是声明方的 capability。slot 所有的上下文会引入 capability 继承和双父级拆卸问题，却无法改善账本所有权。
+**为每个 slot 创建 Cordis 上下文或 fiber。** 贡献方需要的是自身插件生命周期与声明生命周期的交集，而不是声明方的能力。slot 所有的上下文会引入 capability 继承和双父级拆卸问题，却无法改善账本所有权。
 
 **让 `register()` 隐式等待。** 对未声明目标立即失败是一项有价值的配置检查。显式注入能够区分有意独立排序的贡献与错误组合。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
index b6e58aabc7..177796eea6 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.md
 2026-08-06-agent-event-payload-objects.md: 470c8fb3f9282005829846307778d3d1088c3888
-2026-08-06-agent-event-payload-objects.zh.md: ff201a7c3134c0ef809c9a798d65412541f9f1e7
+2026-08-06-agent-event-payload-objects.zh.md: 4e76dd97552a7e3cedb68c0e6c17779e77d68d4d
diff --git a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
index ff201a7c31..4e76dd9755 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Agent 作用域事件 dispatch 单个 payload 对象
+# Agent Note: agent 作用域事件 dispatch 单个 payload 对象
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Agent 作用域事件历来采用位置参数：开头的 `agent` 主体、事件专属字段，以及末尾用于 waterfall（瀑布式事件）/serial 事件的 `next`。新增字段或退役上下文类型（如 `PreStepContext` 与 `RequestFailureContext`）都会迫使跨包重写每个监听器和 emitter，契约也一直分散在参数列表中，而不是集中在一个具名 payload 中。
+agent（智能体）作用域事件历来采用位置参数：开头的 `agent` 主体、事件专属字段，以及末尾用于 waterfall（瀑布式事件）/serial 事件的 `next`。新增字段或退役上下文类型（如 `PreStepContext` 与 `RequestFailureContext`）都会迫使跨包重写每个监听器和 emitter，约定也一直分散在参数列表中，而不是集中在一个具名 payload 中。
 
 ## 决策
 
@@ -18,7 +18,7 @@ dispatch 是融合的：`agentEvents(ctx, agent)`（以及一次性 `emitAgentEv
 
 ## 考虑过的替代方案
 
-**保留位置签名。** 新增字段或退役上下文类型依旧会重写每个监听器和 emitter，契约也会继续分散在参数列表中，而不是集中在一个具名 payload 中。
+**保留位置签名。** 新增字段或退役上下文类型依旧会重写每个监听器和 emitter，约定也会继续分散在参数列表中，而不是集中在一个具名 payload 中。
 
 **在每个 dispatch 位置手工构造主体。** loop 的中间设计调用 `ctx.waterfall(this.carrier, …)`，传入手工构造的 `{ agent: this, … }` payload；它避免了每次 dispatch 的分配，却重复了主体注入，并让作用域键与 payload 主体分叉。融合的 dispatcher 是每种 dispatch 模式的唯一注入点。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
index 0168528557..39340b3b70 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
 2026-08-06-subagent-list-identity-projection.md: ba023d04805ff3335c8f243510aa8ddc15fe13d6
-2026-08-06-subagent-list-identity-projection.zh.md: 368a70f5b3e5a27e4e1c648e8819476d40a57709
+2026-08-06-subagent-list-identity-projection.zh.md: 778d69fefc55ebcd10b195e21cd7222959e095e8
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
index 368a70f5b3..778d69fefc 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
@@ -10,19 +10,19 @@ Status: implemented
 
 同一根因还有第二个症状：host 侧的 `hasSubagentDescriptor()` 在每次 Agent 绑定 RPC 的属主判定上扫描目标会话的 own suffix，即便 `SessionHeader.origin` 已经回答了同一个问题的绝大部分。
 
-根因在于 [durable-subagent-catalog 决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)把描述符事件（`subagent/descriptor`）定为目录的唯一持久权威，却没有为描述符读取配任何缓存层，并把逐 child 双读明确接受为"无索引的正确性基线"。[web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)（#1569）已把"是不是 subagent"放进了 header（`SessionHeader.origin`），身份判定不再读日志；mode 与 label 仍然要扫。
+根因在于 [durable-subagent-catalog 决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)把描述符事件（`subagent/descriptor`）定为目录的唯一持久权威，却没有为描述符读取配任何缓存层，并把逐 child 双读明确接受为「无索引的正确性基线」。[web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)（#1569）已把「是不是 subagent」放进了 header（`SessionHeader.origin`），身份判定不再读日志；mode 与 label 仍然要扫。
 
 ## 决策
 
-mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠，unit 是折叠规则的唯一权威；`listChildren` 不再依赖 session-query——枚举是 subagent 自管的 live-preferred 合并，取值走三级"算完即止"阶梯：live child 同步读注册表的既有水位缓存（零日志读）；cold child 先问可选的 `sessionProjectionCache` checkpoint，取到过 seq 门的身份即定值；否则一次 `persistence.inspect` 整读加 `registry.restore` 折叠。无索引、不自建缓存、无回写。
+mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠，unit 是折叠规则的唯一权威；`listChildren` 不再依赖 session-query——枚举是 subagent 自管的 live-preferred 合并，取值走三级「算完即止」阶梯：live child 同步读注册表的既有水位缓存（零日志读）；cold child 先问可选的 `sessionProjectionCache` checkpoint，取到过 seq 门的身份即定值；否则一次 `persistence.inspect` 整读加 `registry.restore` 折叠。无索引、不自建缓存、无回写。
 
 消除逐 child 扫描的出路有三类：把 mode/label 提升进 header（写路承担）；为投影建持久派生（checkpoint 阶梯，或随查询索引重建落值、读端对账）；读时现算（live 走水位缓存，cold 一次整读）。本记录取第三条。"值随查询索引落库"曾是本记录的定稿方向并一度施工，最终整体退役：查询基础设施被迫认识领域词汇，而唯一消费方读时现算即可满足——live child 的零读由 session-projection 既有水位缓存白拿，cold child 的一次整读被"算完即止"显式接受。前两条与退役理由详见考虑过的替代方案一节。
 
 要点：
 
 - **subagent 列表不依赖 session-query**：枚举由 subagent 自管的 live-preferred 合并完成，mode/label 经 `ctx.sessionProjections` 取值；没有 query backend 的部署照常列表。
-- **取值三级"算完即止"阶梯**：live child 读 `sessionProjections.snapshot()`（注册表既有水位缓存，零日志读）；cold child 先读可选 `sessionProjectionCache.cachedSnapshot(header)`，values 含非 null 且过 seq 门（`seq >= seedLength ?? 0`）的 `subagent` 身份即直接用；否则一次 `persistence.inspect` 整读加 `registry.restore({}, events, 0)` 折叠；再没有就没有——不自建缓存、无回写、无索引。
-- **`subagent` projection unit 是折叠规则唯一权威**：live snapshot、cold restore、GUI history 的 detached 折叠全部经 registry 计算，不存在第二份描述符解释逻辑。
+- **取值三级「算完即止」阶梯**：live child 读 `sessionProjections.snapshot()`（注册表既有水位缓存，零日志读）；cold child 先读可选 `sessionProjectionCache.cachedSnapshot(header)`，values 含非 null 且过 seq 门（`seq >= seedLength ?? 0`）的 `subagent` 身份即直接用；否则一次 `persistence.inspect` 整读加 `registry.restore({}, events, 0)` 折叠；再没有就没有——不自建缓存、无回写、无索引。
+- **`subagent` projection unit 是折叠规则唯一权威**：live 快照、cold restore、GUI history 的 detached 折叠全部经注册表计算，不存在第二份描述符解释逻辑。
 - **header、描述符（v2）、session-persistence、session-projection(-cache)、session-query(-sqlite) 全部零改动**；存量数据第一次被列表时一次 `inspect` 现算获得精确值，无 unknown 降级态、无迁移。
 
 与既有记录的关系：
@@ -62,7 +62,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 - **persistence 缺席退为 live-only 枚举，不报错**：没有 persistence 的部署，cold child 本就无法 resume，列出 live child 仍然有意义。（对照：旧实现在 sessionQuery 缺失时整体拒绝。）
 - persistence 列表失败使整次枚举失败；per-child 隔离只作用于逐 child 的冷读。
 
-### 取值：三级"算完即止"阶梯
+### 取值：三级「算完即止」阶梯
 
 对每个枚举出的 child，mode/label 取值走三级阶梯——算完即止，不自建缓存、无回写（第三级与 apiproxy `session.history` 的冷读同款）：
 
@@ -78,12 +78,12 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 - 冷路径的生命周期见证：preparation 的结果必须仍指向枚举时的那个生命周期——见证字段集与旧 SOURCE_CONFLICT 检查同款七字段（version、id、createdAt、cwd、parentSession、seedLength、delegationDepth）；同 id 删除后重新发布的会话对旧 parent 的目录降级为 `corrupt` 行，不外漏新 owner 的 child。
 - 冷读并发以常数 4 有界——它约束的是本地介质的一次只读扫描而非部署行为；出现联网 persistence backend 时提升为验证过的 `Config` 字段。
 - 冷读成本如实记录：cache 未挂载或未命中时，cold child 每次列表才付一次整读，成本与其 transcript 大小成正比；定案"算完即止"，不自建缓存。整读经 `inspect()` 走 [Session 准备阶段](2026-08-05-session-preparation.md)的冷读，同 id 短期重复读取可命中其 LRU 复用，但列表不依赖此。live child 全程零日志读。
-- 取消：每次 persistence 读前后检查调用方 signal，abort 之后才结算的读拒绝归一化为稳定错误码 `CANCELLED`。
+- 取消：每次持久化读前后检查调用方 signal，abort 之后才结算的读拒绝归一化为稳定错误码 `CANCELLED`。
 
 ### 权威模型
 
 - session log 是唯一权威；本方案不新增任何派生持久化——没有索引值、没有自己的 checkpoint、没有进程 memo；第二级读取的 `sessionProjectionCache` checkpoint 是既有组合项的派生数据，本方案只读不写。取值现算现弃，值的新鲜度就是读取时点的 live 状态或持久化 revision（own descriptor 一经追加不可变——缓存身份过 seq 门后无陈旧性问题，门防的是种子回放的祖先身份）。
-- Session 与 persistence 写路完全不感知列表与投影消费：没有事件监听回写，没有写时折叠。
+- Session 与持久化写路完全不感知列表与投影消费：没有事件监听回写，没有写时折叠。
 - 枚举与取值不构成第二个鉴权来源，也不让尚未发布的 child 可见——两个来源只见已发布的 live 记录与已落盘的持久化记录，与 durable-subagent-catalog 记录对派生读面立下的规则一致。
 
 ### `listChildren` 行形状与消费面
@@ -124,7 +124,7 @@ export type SubagentListEntry =
 已知边界偏差（有意接受，随本记录留档）：
 
 - 死于发布窗口的 fork child，seed 里若有祖先描述符，last-wins 会给出祖先身份，误现为 child 行；恢复仍按 own-suffix 折叠权威失败（`NOT_RESUMABLE`）。旧实现靠 `seedLength` 过滤将其 omit；projection unit 看不到 header，接受此残骸级偏差（`subagentTiming` 有同类既有暴露）。
-- own suffix 出现多个描述符，旧实现判 corrupt，现 last-wins 取末者（provider 契约本就保证恰一）。
+- own suffix 出现多个描述符，旧实现判 corrupt，现 last-wins 取末者（提供方约定本就保证恰一）。
 - live/persisted header 冲突，旧实现是 per-child corrupt；现枚举 live 优先、不做一致性校验，冲突不再被察觉，以 live 记录成行。
 - 损坏存储的源读失败（如坏 surface 被冷读整读拒收），旧实现映射 per-child `corrupt`，现统一成 `unavailable` 行（读侧无从区分成因）。
 - 未知 parent，旧实现经 session-query 抛 not-found（'parent session … was not found'）；现自管合并对不存在的 parent 得到空子集，枚举返回空列表，wire 上后续操作落到 child 级 subagent-not-found——语义与文案的静默变化，显式接受。
@@ -147,13 +147,13 @@ export type SubagentListEntry =
 
 **mode/label 进 SessionHeader。** 零读保证最强——列表只看 header 就能成行。但 header 形状变更传导两个 persistence backend 与 header 兼容检查；SQLite 存量直接拒收，JSONL 存量只能 unknown 降级或 backfill。读时现算对存量的答案是"第一次列表一次 `inspect` 现算"，不碰持久格式。
 
-**projection-cache 阶梯（v3 稿：`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的第三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
+**projection-cache 阶梯（v3 稿：`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
 
 **给 persistence 加有界读原语抢救存量。** 为一次性问题新开 seam 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
 
 **list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强契约加算不出即 omit 更干净。
 
-**彻底删除 diagnostic 行（v5 一稿）。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担契约与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
+**彻底删除 diagnostic 行（v5 一稿）。** 删除会让库损坏不再可见、让行静默消失，wire/tool/GUI 反要各自承担契约与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
 
 **registry 计算失败通道（per-unit 容错加 `failures` 附加字段）。** 为把损坏、版本不认识报告给消费方，曾考虑让 registry 捕获 unit 异常并在 snapshot 旁附 per-key 失败态。被否：failure 不是值，也不必是通道——unit 永不抛错，缺席本身就是信号，"大不了算出来没有"，如何呈现是消费方要考虑的事。该路线讨论顺带留下一个独立观察：vendor cordis 的 `emit`（[vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)）对 listener 抛错零捕获，投影驱动挂在 `session/event` 上时 unit 异常会沿 emit 逃逸——这加重了"unit 永不抛错"纪律的分量，但 emit 容错的修复不属于本记录范围。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
index 20d21565b5..bb791431f5 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md
 2026-08-06-web-markdown-incremental-ast-renderer.md: 3599bfcc78dc4eefe5e82f461a469bdba15f3aae
-2026-08-06-web-markdown-incremental-ast-renderer.zh.md: 2e00977da58ef29a77c45abcecf0f3bb62737929
+2026-08-06-web-markdown-incremental-ast-renderer.zh.md: 1934953a704319a5cde3f7bf2182982ecc5ea527
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
index 2e00977da5..1934953a70 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
@@ -6,19 +6,19 @@ Status: implemented
 
 ## Problem
 
-`MarkdownText` 在每次流式发布时都重新解析整个已累积的回复:react-markdown 的纯字符串 API 每次渲染都新建 unified processor,并对全文跑完 micromark → mdast → hast → React,因此每个 chunk 的主线程工作量随回复长度线性增长,整个流的累计成本随之二次增长。既有缓解手段(帧级合并、隔离的流式尾部、围栏 plain 臂)约束的是这份工作跑多频繁、波及多广,从未约束每次重新解析多少文本。修复它需要 AST 级输入——冻结已定型的块、只重新解析源文本尾部——这是纯字符串封装在结构上无法表达的。
+`MarkdownText` 在每次流式发布时都重新解析整个已累积的回复：react-markdown 的纯字符串 API 每次渲染都新建 unified processor，并对全文跑完 micromark → mdast → hast → React，因此每个分片的主线程工作量随回复长度线性增长，整个流的累计成本随之二次增长。既有缓解手段（帧级合并、隔离的流式尾部、纯文本围栏分支）约束的是这份工作跑多频繁、波及多广，从未约束每次重新解析多少文本。修复它需要 AST 级输入——冻结已定型的块、只重新解析源文本尾部——这是纯字符串包装层在结构上无法表达的。
 
 ## Decision
 
-`MarkdownText` 直接渲染 mdast,并在流式期间增量解析:
+`MarkdownText` 直接渲染 mdast，并在流式期间增量解析：
 
 - **语法**([parse.ts](../../../../packages/client/ui-primitives/src/markdown/parse.ts)):`parseGfm`(流式臂与 `extractMarkdownPlainText`)和 `parseGfmWithMath`(定稿臂)以被替换的 remark 插件所包装的同一组 micromark 扩展调用 `mdast-util-from-markdown`,因此各处块边界完全一致。`mathCompatibility`(原 `remarkMathCompatibility`)现在直接导出其 micromark 扩展。
 - **增量解析**([incremental.ts](../../../../packages/client/ui-primitives/src/markdown/incremental.ts)):CommonMark 块解析按行推进,追加文本只会重塑解析前沿。`IncrementalMarkdownParser` 保留末尾两个块不稳定(最后一块是前沿;倒数第二块是安全裕量),冻结其前的所有块,只从最后一个冻结块的 `position.end.offset` 起重新解析源尾部——用的是解析器自己的偏移量,没有任何自制源扫描。每个源区间在整个流中解析 O(1) 次而非每 chunk 一次;单个巨型块(未闭合围栏)退化为旧的全量重解析成本,不会更差。非追加输入在递增的 generation 下重置状态。
-- **渲染**([render.tsx](../../../../packages/client/ui-primitives/src/markdown/render.tsx)、[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)):一个对 mdast 节点类型的 switch 取代 remark-rehype + react-markdown,逐字节复刻被替换管线的 DOM——表格对齐渲染为 `text-align` 样式、紧凑列表段落解包、任务列表类名与复选框空格、脚注区(其页内锚点本就被协议白名单降为纯文本)、字面 raw HTML、会与字面 HTML 文本相邻显形的分隔换行,以及 rehype-katex 的三臂容错链,KaTeX HTML 经浏览器自带的 `DOMParser` 映射为 React(无包裹元素,首/末子元素的 margin 规则仍能作用于 `.katex-display`;React 18 会把 `.katex-mathml` 子树放进 HTML 命名空间,与被替换管线完全一致——既有限制,不在本对等性契约范围内,对承担视觉渲染的 `.katex-html` 臂不可见)。冻结块缓存其 React 元素并保持源偏移 key,跨过冻结边界时走 reconcile 而非重挂载;`MarkdownText` 已 memo 化。
+- **渲染**([render.tsx](../../../../packages/client/ui-primitives/src/markdown/render.tsx)、[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)):一个对 mdast 节点类型的 switch 取代 remark-rehype + react-markdown,逐字节复刻被替换流水线的 DOM——表格对齐渲染为 `text-align` 样式、紧凑列表段落解包、任务列表类名与复选框空格、脚注区(其页内锚点本就被协议白名单降为纯文本)、字面 raw HTML、会与字面 HTML 文本相邻显形的分隔换行,以及 rehype-katex 的三臂容错链,KaTeX HTML 经浏览器自带的 `DOMParser` 映射为 React(无包裹元素,首/末子元素的 margin 规则仍能作用于 `.katex-display`;React 18 会把 `.katex-mathml` 子树放进 HTML 命名空间,与被替换管线完全一致——既有限制,不在本对等性约定范围内,对承担视觉渲染的 `.katex-html` 臂不可见)。冻结块缓存其 React 元素并保持源偏移 key,跨过冻结边界时走 reconcile 而非重挂载;`MarkdownText` 已 memo 化。
 
-DOM 由 `tests/fixtures/markdown-dom` 钉死:fixture 录制自替换前的 react-markdown 实现,新渲染器必须在空白规整序列化器下复现。fixture 差异即用户可见的 markdown 样式变更,必须按此评审,绝不能为重构而重录。`tests/markdown-incremental.spec.tsx` 承载等价性性质——以 1/3/7/16 字节分块,在每个追加前缀处,常驻组件的 DOM 都等于全新挂载——外加冻结边界的 DOM 节点同一性与重置行为。
+DOM 由 `tests/fixtures/markdown-dom` 钉死：fixture（测试前置数据）录制自替换前的 react-markdown 实现,新渲染器必须在空白规整序列化器下复现。fixture 差异即用户可见的 markdown 样式变更,必须按此评审,绝不能为重构而重录。`tests/markdown-incremental.spec.tsx` 承载等价性性质——以 1/3/7/16 字节分块,在每个追加前缀处,常驻组件的 DOM 都等于全新挂载——外加冻结边界的 DOM 节点同一性与重置行为。
 
-这推翻了[助手 Markdown Note](../feature/2026-07-23-web-assistant-markdown.md) 中被否决的备选("维护一个自定义 React walker"):增量需求是当时不存在的新证据,walker 的安全敏感分支(URL 白名单、图片策略、惰性 HTML)本就是产品自有函数,而该依赖不再删减自有代码——它阻塞了架构。该 Note 的不可信输出策略与渲染器选型不变。
+这推翻了[助手 Markdown Note](../feature/2026-07-23-web-assistant-markdown.md) 中被否决的备选（「维护一个自定义 React walker」）：增量需求是当时不存在的新证据,walker 的安全敏感分支(URL 白名单、图片策略、惰性 HTML)本就是产品自有函数,而该依赖不再删减自有代码——它阻塞了架构。该 Note 的不可信输出策略与渲染器选型不变。
 
 ## Alternatives considered
 
@@ -30,4 +30,4 @@ DOM 由 `tests/fixtures/markdown-dom` 钉死:fixture 录制自替换前的 react
 
 ## Consequences
 
-流式的每 chunk 工作量现在跟随不稳定尾部而非整个回复,react-markdown、remark-gfm、remark-math、rehype-katex、unified 及 hast 链退出浏览器 bundle(`mdast-util-math` 与 `micromark-util-sanitize-uri` 成为直接依赖;两者原本就是传递依赖)。包自有约 25 个节点映射、其测试以及 KaTeX DOM 转换——代价由冻结其输出的 fixture 契约对冲。两个行为偏差,均在定稿的全量解析处自愈:定义落在冻结边界另一侧的引用式链接或脚注在流式期间渲染为字面文本;当脚注定义先冻结而引用块仍不稳定时,脚注引用可能闪回字面文本。本模块与 KaTeX 转换假定浏览器 DOM(`DOMParser`),这个 client-only 包本就如此。
+流式的每 chunk 工作量现在跟随不稳定尾部而非整个回复,react-markdown、remark-gfm、remark-math、rehype-katex、unified 及 hast 链退出浏览器 bundle(`mdast-util-math` 与 `micromark-util-sanitize-uri` 成为直接依赖;两者原本就是传递依赖)。包自有约 25 个节点映射、其测试以及 KaTeX DOM 转换——代价由冻结其输出的 fixture 约定对冲。两个行为偏差,均在定稿的全量解析处自愈:定义落在冻结边界另一侧的引用式链接或脚注在流式期间渲染为字面文本;当脚注定义先冻结而引用块仍不稳定时,脚注引用可能闪回字面文本。本模块与 KaTeX 转换假定浏览器 DOM(`DOMParser`),这个 client-only 包本就如此。
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
index 815f5eee75..3b80f87a89 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
 2026-08-06-web-shell-dist-chunk-layout.md: 1c7b4273dc243685317b149e2fd7fddf2a6c18d1
-2026-08-06-web-shell-dist-chunk-layout.zh.md: 6f4b94e0bd7412e480458e34922273b389aa8892
+2026-08-06-web-shell-dist-chunk-layout.zh.md: d1435215d3c077efc3afaac7b3a7a1c2e2ffdae7
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
index 6f4b94e0bd..d1435215d3 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Web 壳产物的 chunk 切分与目录布局
+# Agent Note: Web 壳产物的分片拆分与目录布局
 
 Status: implemented
 
@@ -6,26 +6,26 @@ Status: implemented
 
 ## Problem
 
-apps/web 的壳此前打成单一约 1.2 MB（minified）的 index chunk，其中约八成是 vendor 字节——KaTeX、boot 语法与 shiki 引擎、react-dom、markdown 管线——与全部 workspace 壳代码（约五分之一）熔在一起。任何一行壳代码改动都让整个 chunk 换哈希，回头客户端全量重新下载；`dist/assets/` 是 100 多个文件的单层平铺（主 chunk、23 个懒加载语法 chunk、59 个 KaTeX 字体面、sourcemap 混居），无从导航。
+apps/web 的壳此前打成单一约 1.2 MB（minified）的 index 分片，其中约八成是 vendor 字节——KaTeX、boot 语法与 shiki 引擎、react-dom、markdown 流水线——与全部 workspace 壳代码（约五分之一）熔在一起。任何一行壳代码改动都让整个 chunk 换哈希，再次访问的客户端全量重新下载；`dist/assets/` 是 100 多个文件的单层平铺（主分片、23 个懒加载语法 chunk、59 个 KaTeX 字体面、sourcemap 混居），无从导航。
 
 ## Decision
 
-`apps/web/vite.config.ts` 以 `manualChunks` 把壳切成两个初始 chunk，并以输出命名函数归类目录；整套配置零正则——精确包名 Set、文件名清单、扩展名清单。
+`apps/web/vite.config.ts` 以 `manualChunks` 把壳切成两个初始分片，并以输出命名函数归类目录；整套配置零正则——精确包名 Set、文件名清单、扩展名清单。
 
 **成员归属**（`VENDOR_PACKAGES`，按精确 npm 包名）：
 
-- `vendor` = 三个重渲染家族：math（katex）、highlight（shiki）、markdown（micromark/mdast 解析管线——其上的增量 React 渲染器是 workspace 代码，不在此列）。成员以 `VENDOR_PACKAGES` 为活口径，清单 = workspace 代码**直接 import** 的包：其余私有传递依赖（oniguruma 系、@shikijs/core、字符表等数十个）只被清单成员引用，rollup 的 chunk 着色自动将其并入 vendor；与 index 侧共享的依赖回落 index，只稀释几 KB，不构成正确性问题。
-- **vendor 全员必须 react-free（边界不变量）**：rollup 会把入口与 manual chunk 共享的模块并入 manual chunk——清单里出现任何 import react/jsx-runtime 的包，唯一一份 react 副本就会被拽进 vendor、脱离 index。markdown/math 的 React 渲染侧是 workspace 代码天然住 index，react 族因此全部钉在 index。
-- `index`（默认 chunk）= react 族（react、react-dom、scheduler、use-sync-external-store）、vendored cordis、全部 workspace 代码及未列入的小件（anser、clsx）。
+- `vendor` = 三个重渲染家族：math（katex）、highlight（shiki）、markdown（micromark/mdast 解析流水线——其上的增量 React 渲染器是 workspace 代码，不在此列）。成员以 `VENDOR_PACKAGES` 为活口径，清单 = workspace 代码**直接 import** 的包：其余私有传递依赖（oniguruma 系、@shikijs/core、字符表等数十个）只被清单成员引用，rollup 的分片着色自动将其并入 vendor；与 index 侧共享的依赖回落 index，只稀释几 KB，不构成正确性问题。
+- **vendor 全员必须 react-free（边界不变量）**：rollup 会把入口与 manual chunk 共享的模块并入 manual chunk——清单里出现任何 import react/jsx-runtime 的包，唯一一份 react 副本就会被拽进 vendor、脱离 index。markdown/math 的 React 渲染侧是 workspace 代码，天然住 index，react 族因此全部钉在 index。
+- `index`（默认分片）= react 族（react、react-dom、scheduler、use-sync-external-store）、vendored cordis、全部 workspace 代码及未列入的小件（anser、clsx）。
 - `@shikijs/langs` 特判：boot 语法（`BOOT_GRAMMAR_FILES`：typescript、shellscript、json——highlight.ts 静态 import 的三件，均为零内部 import 的自含数据模块）进 vendor；其余 23 个懒加载语法不做指派，各自保持按需 chunk。
-- `index.html` 由 vite 自动接线：index 走 `<script>`、vendor 走 `<link rel="modulepreload">`，两 chunk 并行拉取，无瀑布。
+- `index.html` 由 vite 自动接线：index 走 `<script>`、vendor 走 `<link rel="modulepreload">`，两个分片并行拉取，无串行加载瀑布。
 
 **目录布局**（`chunkFileNames` + `assetFileNames`）：
 
 - `assets/` 根只留 index 与 vendor 的 js（含随行 sourcemap）与 css。
 - 语法 chunk 归 `assets/langs/`。判据是 chunk 的 `moduleIds` 含 `@shikijs/langs` 成员，而非 facade：内嵌语法共享 chunk（php/ruby/mdx 内嵌 html+javascript，被 rollup 拆出共享）**没有 facade**，facade 判据会漏；index/vendor 按名排除，因 vendor 合法携带 boot 三语法。
-- 字体归 `assets/fonts/`（`FONT_EXTENSIONS`：woff2/woff/ttf；今日全部为 vendor.css 引用的 KaTeX 字面——katex.min.css 虽由 index 侧组件 import，css 模块同样经 manualChunks 归属、随 `katex` 落入 vendor.css；浏览器按需只拉 woff2，且仅在公式渲染时）。
-- sourcemap 无需安排：rollup 把 `.map` 写在各自 js 旁并以裸相对文件名引用，chunk 挪目录 map 自动跟随。
+- 字体归 `assets/fonts/`（`FONT_EXTENSIONS`：woff2/woff/ttf；今日全部为 vendor.css 引用的 KaTeX 字体面——katex.min.css 虽由 index 侧组件 import，css 模块同样经 manualChunks 归属、随 `katex` 落入 vendor.css；浏览器按需只拉 woff2，且仅在公式渲染时）。
+- sourcemap 无需安排：rollup 把 `.map` 写在各自 js 旁并以裸相对文件名引用，分片挪目录时 map 自动跟随。
 
 跨目录引用（index 的动态 import 指向 `langs/`、语法 chunk 间同目录相对引用、vendor.css 相对引用 `fonts/`）均由构建器生成，运行时零配套改动；host 侧 webserver 按静态前缀原样服务嵌套路径。
 
@@ -40,11 +40,11 @@ apps/web 的壳此前打成单一约 1.2 MB（minified）的 index chunk，其
 
 ## Verification
 
-审计工具随库：`node scripts/attribute-chunk-bytes.mjs <chunk.js>`（零依赖 sourcemap VLQ 字节归属，按 npm 包/workspace 目录聚合）。以其复核：vendor 不含任何 workspace 字节、react 族（含 react/jsx-runtime）全量位于 index、index 的 npm 侧仅剩 react 族与 anser/clsx；懒语法 chunk 数量与 `LAZY_GRAMMARS` 表一一对应；浏览器 keyless replay 用例与改动前基线逐字一致（本机环境性红除外），两 chunk 壳装载渲染无回归。
+审计工具随库：`node scripts/attribute-chunk-bytes.mjs <chunk.js>`（零依赖 sourcemap VLQ 字节归属，按 npm 包/workspace 目录聚合）。以其复核：vendor 不含任何 workspace 字节、react 族（含 react/jsx-runtime）全量位于 index、index 的 npm 侧仅剩 react 族与 anser/clsx；懒语法 chunk 数量与 `LAZY_GRAMMARS` 表一一对应；浏览器 keyless replay 用例与改动前基线逐字一致（特定于本机环境的报红除外），双分片壳装载渲染无回归。
 
 ## Consequences
 
 - 壳代码改动只重哈希 index（约为产物三分之一）；vendor（约三分之二）跨壳版本缓存稳定，仅依赖升级时失效。
 - `dist/assets/` 可导航：根两对 js/css，`langs/` 按需语法，`fonts/` 字体。
 - 维护成本：workspace 代码新增对某渲染家族门面包的直接 import 时需同步 `VENDOR_PACKAGES`（漏列仅稀释 index，不致坏）；在 highlight.ts 扩 boot 语法集而未同步 `BOOT_GRAMMAR_FILES` 时，该语法静默落入 index，仅产物审计可见。
-- webserver 静态面尚无压缩，gzip 体量是潜在值；传输层压缩是另一项独立决策。
+- webserver 静态面尚无压缩，gzip 体积收益仍有待实现；传输层压缩是另一项独立决策。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
index 05c9a1fdd2..0a84e714f2 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
 2026-08-08-bounded-session-persistence-write-batching.md: 46dc612492fa1bfa805f77f865f14b168f52776f
-2026-08-08-bounded-session-persistence-write-batching.zh.md: 4aafdd652aad87cfe74a449428cdbbf13312d260
+2026-08-08-bounded-session-persistence-write-batching.zh.md: 1713dc0cf4280b12e1be871d5cecc64569276106
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
index 4aafdd652a..1713dc0cf4 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
@@ -26,7 +26,7 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 `writeBatchMaxDelayMs` 只限制控制器为批处理而主动等待的时间。事件循环调度、初始化、此前的串行化操作和后端 I/O 都可能延后持久化完成时间，因此该选项并不对 fsync 完成时间或崩溃数据丢失提供硬性 SLA。
 
-`session/flush` 会取消剩余等待，并充当共享的完全停稳屏障。它会在完成前等待活跃写入尝试，并排空屏障运行期间接纳的每个事件。Session 退役与后端 dispose（资源释放）共用该屏障，因此生命周期 teardown 绝不会等待批处理计时器。检查点策略仍会在模型请求与顶层工具副作用之前设置强制屏障。
+`session/flush` 会取消剩余等待，并充当共享的完全停稳屏障。它会在完成前等待活跃写入尝试，并排空屏障运行期间接纳的每个事件。会话退役与后端 dispose（资源释放）共用该屏障，因此生命周期 teardown 绝不会等待批处理计时器。检查点策略仍会在模型请求与顶层工具副作用之前设置强制屏障。
 
 每个事件仍会按原有顺序和形态持久化。控制器会在接纳时复制每个事件；任何 `assistant/chunk`、`seq`、`time`、surface 元数据或存储记录都不会被删除或重写。因此，JSONL 可以在一个追加帧中编码更多事件，SQLite 可以在一个事务中插入更多事件行，而无需改变任一种磁盘格式或 schema 版本。
 
@@ -38,7 +38,7 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 **不持久化流式分片事件。** 这里不采纳：这会改变事件日志作为真源的地位及恢复语义，而不只是改变物理写入节奏。在无信息损失的替代方案独立定义回放、fork、来源信息、序列和崩溃行为之前，现有的[拒绝仅保留组装消息的决策](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)仍是防护规则。[打包行决策](2026-07-26-packed-chunk-rows-by-default.md)仍是配套的 JSONL 存储体积优化。
 
-**仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序契约。
+**仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序约定。
 
 **按最新事件重置防抖窗口。** 不采纳：持续不断的流式响应可能无限期推迟首次写入。由第一个待处理事件启动的固定窗口，为主动合并等待提供了真正的上界。
 
@@ -46,14 +46,14 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 ## 验证
 
-控制器测试使用假时钟证明固定且不会重置的 200 ms 窗口、即时且可共享的 flush 屏障、屏障运行期间接纳的事件、在活跃写入之后已超过窗口时限的尾部批次、有序保留失败批次、暂停自动重试，以及显式 flush 会重试与其重叠发生的后台失败。协调器测试会在 Session 通知、退役、冲突回收和 teardown 路径中验证该控制器。JSONL 与 SQLite 测试套件继续覆盖存储格式、事务、恢复和共享持久化契约。
+控制器测试使用假时钟证明固定且不会重置的 200 ms 窗口、即时且可共享的 flush 屏障、屏障运行期间接纳的事件、在活跃写入之后已超过窗口时限的尾部批次、有序保留失败批次、暂停自动重试，以及显式 flush 会重试与其重叠发生的后台失败。协调器测试会在 Session 通知、退役、冲突回收和 teardown 路径中验证该控制器。JSONL 与 SQLite 测试套件继续覆盖存储格式、事务、恢复和共享持久化约定。
 
 ## 后果
 
 高频事件突发通常会减少持久化追加操作，同时保持逻辑事件数量完全不变。减少幅度取决于事件到达速率和后端延迟：位于同一 200 ms 窗口内的突发事件会成为一个批次，而强制 flush 与稀疏事件仍可能产生小批次。
 
-本决策不会限制因后端缓慢而积压的待处理事件数量或字节数，也不会减少 SQLite 行数或解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放契约，而不是再引入一条隐式计时器规则。
+本决策不会限制因后端缓慢而积压的待处理事件数量或字节数，也不会减少 SQLite 行数或解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放约定，而不是再引入一条隐式计时器规则。
 
 接纳后的事件在配置窗口内可能只存在于内存中，此后在等待调度或后端工作完成期间也可能如此。部署可以选择较小的值以缩短普通丢失窗口，也可以选择较大的值以加强批处理。显式持久性边界保持不变，并会绕过等待。
 
-新的 deep module 让计时器、活跃写入、待处理前缀、重试暂停和屏障由一个所有方统一负责。`PersistenceCoordinator` 继续负责初始化和按标识串行化；后端仍只负责持久存储原语。`SESSION_FORMAT_VERSION` 与 SQLite `SCHEMA_VERSION` 均不变。
+新的 deep module 统一负责计时器、活跃写入、待处理前缀、重试暂停和屏障。`PersistenceCoordinator` 继续负责初始化和按标识串行化；后端仍只负责持久存储原语。`SESSION_FORMAT_VERSION` 与 SQLite `SCHEMA_VERSION` 均不变。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index e1beb13c2c..514f36ed36 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
 2026-08-08-client-tool-presentation-ownership.md: 9ea7d7dfc5e18e541550569795c5e1db84d6ad91
-2026-08-08-client-tool-presentation-ownership.zh.md: 11a42ad69e4374afa6dccd3af74b8bd1b5e5c6f1
+2026-08-08-client-tool-presentation-ownership.zh.md: 18a6f5ba45f4ec470ea94c440ce4fa65c1bc6cdc
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index 11a42ad69e..18a6f5ba45 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Client Tool 展示所有权
+# Agent Note: Client 工具展示所有权
 
 Status: implemented
 
@@ -6,25 +6,25 @@ Status: implemented
 
 ## Problem
 
-Client Runtime 已经把 Tool 调用投影成稳定的生命周期：它按 `callId` 配对 call/result 事件，保留 running 与 settled 两种形态，并按 root call 索引 Code Dispatch 子调用。但 chat view 仍拥有整套展示链路：它在 ChatFlow 中放置 root call，把每个 root 与 subcall 编排在一起，按 Tool 名称分发每个原子调用，携带通用 fallback 与 card model，注册第一方 Tool view，并在 details panel 中复用这些 model。
+Client 运行时已经把工具调用投影成稳定的生命周期：它按 `callId` 配对 call/result 事件，保留 running 与 settled 两种形态，并按 root call 索引 Code Dispatch 子调用。但 chat view 仍拥有整套展示链路：它在 ChatFlow 中放置 root call，把每个 root 与 subcall 编排在一起，按 Tool 名称分发每个原子调用，携带通用 fallback 与 card model，注册第一方 Tool view，并在 details panel 中复用这些 model。
 
-这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的 Tool 专属编排契约。增加 Tool 专属 Session projection 会重复 Runtime 已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
+这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的工具专属编排约定。增加工具专属会话 projection 会重复运行时已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
 
 ## Decision
 
-Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。Runtime 将 Code Dispatch 规范化为递归 `ToolCallBlock`：每个 root 或 child 通过自己的 `subCalls` 拥有下一层调用，`ConversationSnapshot` 不再公开单独的 parent-to-children map。
+工具成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。运行时将 Code Dispatch 规范化为递归 `ToolCallBlock`：每个 root 或 child 通过自己的 `subCalls` 拥有下一层调用，`ConversationSnapshot` 不再公开单独的 parent-to-children map。
 
-这里的“一级概念”只描述 UI 所有权，不增加 Runtime 数据种类。`ConversationNode` 仍是 transcript projection，`ChatFlowItem` 仍是 conversation 对节点进行排序与分组后得到的渲染单元，`ToolCallBlock` 仍是单次调用的标准数据，而 `ToolCallTree` 只负责 Tool 内部的 root/subcall 展示编排。Command 继续通过独立的 `'conversation.chat.commandview'` 席位渲染，不并入 Tool。
+这里的「一级概念」只描述 UI 所有权，不增加运行时数据种类。`ConversationNode` 仍是 transcript（文本记录）projection，`ChatFlowItem` 仍是 conversation 对节点进行排序与分组后得到的渲染单元，`ToolCallBlock` 仍是单次调用的标准数据，而 `ToolCallTree` 只负责 Tool 内部的 root/subcall 展示编排。Command 继续通过独立的 `'conversation.chat.commandview'` 席位渲染，不并入 Tool。
 
 `ui-conversation` 拥有有序放置。`deriveChatFlow()` 仍决定 settled Tool group 在哪里出现，`ChatView` 仍追加 running call、维护滚动 anchor 与 selection，并提供宿主动作。对于每个 root call，它使用 root block、selected call id、session cwd 以及 open-file/inspect 回调渲染 single/session 的 `'conversation.chat.tool'` 席位。它不读取 Code Dispatch child、不按 Tool 名称分支，也不导入 Tool 专属 view 或 card model。
 
 `ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 直接递归遍历 root block 的 `subCalls`，并让每一层调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。它不读取 Session，也不维护第二份调用拓扑。
 
-业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 seam 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
+业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。skill（技能）仍是普通工具，`ui-skill` 通过该 seam 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
 
 details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 通过 single/session 的 `'conversation.details.tool'` 席位委托 selected output body；`ui-tool` 渲染能够识别 card 的输出，插件缺席时由席位 fallback 保留 raw result text。因此 card model 只有一个生产代码所有者，也不需要引入反向实现依赖。
 
-Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 作为官方顶级概念改变 parent/child identity；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示 seam，这个包边界不会增加 Tool projector/fold registry。
+运行时仍是工具生命周期与调用拓扑的权威。Code Dispatch 因会改变 parent/child identity 而成为官方顶级概念；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示 seam，这个包边界不会增加 Tool projector/fold registry。
 
 ## Runtime 与渲染链路
 
@@ -46,7 +46,7 @@ ConversationSnapshot.runningCalls     |
                                                                `- GenericToolCard fallback
 ```
 
-Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) 私下按 parent callId 索引 child lifecycle，并供 Live [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 与历史 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 共用。它把 children 递归投影到 root `ToolCallBlock`，child 变化时只复制所属祖先路径；未变化的 sibling、其他 root，以及没有 Tool 拓扑变化的 snapshot 引用保持稳定，供 React selector 与 memo 跳过无关更新。Tool UI 直接消费这两个路径统一后的树，不重复 call/result 配对、历史 replay 或缓存索引。
+Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) 私下按 parent callId 索引 child lifecycle，并供实时 [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 与历史 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 共用。它把 children 递归投影到 root `ToolCallBlock`，child 变化时只复制所属祖先路径；未变化的 sibling、其他 root，以及没有 Tool 拓扑变化的 snapshot 引用保持稳定，供 React selector 与 memo 跳过无关更新。Tool UI 直接消费这两个路径统一后的树，不重复 call/result 配对、历史 replay 或缓存索引。
 
 [`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只在 `nodes` 引用变化时重新执行 [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)，把连续 settled Tool result 合为 `tool-group`；running root call 则追加在 flow tail。两条路径最终都进入同一个 `ToolSeat`，因此 settled/running 形态共享整体 Tool 席位。selection 只传给包含该 call 的 root，`ToolCallTree` 再沿该 root 的局部树递归渲染。
 
@@ -54,19 +54,19 @@ Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sess
 
 | 所有者 | 主要代码 | 拥有的责任 | 明确不拥有 |
 |---|---|---|---|
-| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、递归 parent/child 树、snapshot 结构共享 | Tool 名称对应的业务视图 |
+| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、递归 parent/child 树、快照结构共享 | Tool 名称对应的业务视图 |
 | `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)、[`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx)、[`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow 顺序、settled group、running tail、scroll anchor、selection 与宿主动作、整体 Tool 席位声明 | subcall 组合、按 `toolName` 分发、Generic fallback、Tool card model |
 | `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts)、[`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx)、[`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall 组合、原子 keyed dispatch、Generic fallback、Tool card model 与内置 Tool view | ChatFlow 排序、Session Event fold |
 | 业务 Tool 插件 | [`ui-skill` 注册例](../../../../packages/client/ui-skill/src/client/index.ts) | 一个或多个 wire Tool name 的原子 view | root/subcall 位置与生命周期配对 |
 | details 路径 | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx)、[`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected call 定位、card-aware output 与 raw fallback | chat 调用树编排 |
 
-## Slot 与 owner 契约
+## Slot 与 owner 约定
 
 slot 声明同时限定渲染所有权。conversation chat entry 通过 `children` 声明 `'conversation.chat.tool'`，因此只有 `ChatView` 放置整体 Tool 席位；`ui-tool` 注册该席位时再通过 `children` 声明 `'tool.call.toolview'`，因此只有 `ToolCallTree` 渲染原子 Tool 席位。业务插件只注册 keyed entry，不参与 root/subcall 编排，也不建立与 slot 平行的 registry。
 
 整体席位的 `ToolTreeOwnerProps` 携带 root `callId`、`toolName`、`ToolCallBlock`、`selectedCallId`、session `cwd`、`openFile(path)` 与 `inspectCall(callId)`。`ToolCallTree` 把 root 或 child 转成相同的 `ToolCallOwnerProps`，并把 inspect 收窄成当前 call 的回调。原子 owner 不携带 `ReactNode`、Cordis `Context`、Session service 或 projector；业务 view 只消费一个标准调用块和宿主动作。
 
-席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 契约：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
+席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 约定：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
 
 业务插件遵循同一个注册形态：
 
@@ -86,7 +86,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 ## Verification
 
-测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主契约；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
+测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主约定；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
 
 ## Alternatives considered
 
@@ -94,7 +94,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 **只移动 Tool React 组件与 card model。** 拒绝：`ChatView` 仍会拥有 Tool 名称分发与 Code Dispatch 编排，只是改变文件路径，没有改变责任。
 
-**增加业务专属 Session projector 或 fold。** 拒绝：普通 Tool view 消费 Runtime 已重建的标准 call block。第二套 registry 会为 call identity 与历史 replay 建立两个权威。只有会改变日志拓扑或生命周期的能力才应获得 Runtime 级扩展。
+**增加业务专属 Session projector 或 fold。** 拒绝：普通 Tool view 消费 Runtime 已重建的标准 call block。第二套 registry 会为 call identity 与历史 replay 建立两个权威。只有会改变日志拓扑或生命周期的功能才应获得运行时级扩展。
 
 **让每个原子 Tool view 递归渲染自己的 subcall。** 拒绝：原子注册方只接收一个 Tool call，不应知道自己是 root 还是 child。递归 root/child 编排统一归 `ui-tool` 的 `ToolCallTree`。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
index 6e2c9a635d..0d29db621d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-20-config-hot-reload-resilience.md
 2026-07-20-config-hot-reload-resilience.md: 2b98ee73e1c7734da9c0ae6df5e3de1af6a5cbeb
-2026-07-20-config-hot-reload-resilience.zh.md: 4ddf1f07f4ff5449f3bd91aa2b38f6045eb4e1c6
+2026-07-20-config-hot-reload-resilience.zh.md: 0a3652a7cac589b601d7fd30d0c713d4585be830
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
index 4ddf1f07f4..0a3652a7ca 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-config-hot-reload-resilience.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-无效的 `cordis.yml` 编辑不得杀死运行中的 agent（智能体）；但若一次看似有效的更新先部分替换 Loader 树，后续配置项才失败，仅仅保住进程仍不够。调用方还需要能观察到被拒绝的实时更新，同时不能让同一个错误被当作未处理的启动失败。个人配置还带来第二项要求：HMR（热模块替换）必须观察其模块根目录之外的一个确切文件，包括启动后才创建的文件或父目录。
+无效的 `cordis.yml` 编辑不得杀死运行中的 agent（智能体）；但若一次看似有效的更新先部分替换 Loader 树，后续配置项才失败，仅仅保住进程仍不够。调用方还需要能观察到被拒绝的实时更新，同时不能让同一个错误被当作未处理的启动失败。个人配置还带来第二项要求：HMR（热模块替换）必须观察其模块根目录之外的一个确切文件，即使该文件或其父目录在启动后才创建也不例外。
 
 ## Decision
 
@@ -16,7 +16,7 @@ vendor 中的 Cordis 生命周期和 Loader 插件提供可等待、带补偿的
 
 Loader 会先导入变化后的模块名，再 dispose（资源释放）活动 fiber。它会 await 候选项的应用；若失败，则 dispose 候选项的 effect，并恢复先前的插件或配置。组内对账会并发启动各候选项，等待每项结果，并会在拒绝前恢复已变更的配置项、添加项、移除项和移动项。只有程序化变更成功后才会持久化。这是一种补偿事务：生命周期 effect 可能短暂可见；回滚失败会报告为 `AggregateError`，而不会被误称为树已保留。
 
-Include 读取并校验尚未提交的候选内容，把补丁应用到其副本，对账 Loader 树，然后才提交缓存内容和解析数据。解析、校验、应用或回滚失败后，`refresh()` 会向调用方 reject。初始加载继续快速失败；只有文件不存在时才可以使用 `initial`。YAML/JSON 结果若不是数组即为无效；文件刷新和 Include 配置更新都会重新应用补丁，且不修改缓存的解析结果。
+Include 读取并校验尚未提交的候选内容，把补丁应用到其副本，对账 Loader 树，然后才提交缓存内容和解析数据。解析、校验、应用或回滚失败后，`refresh()` 会向调用方 reject。初始加载仍会明确报错；只有文件不存在时才可以使用 `initial`。YAML/JSON 结果若不是数组即为无效；文件刷新和 Include 配置更新都会重新应用补丁，且不修改缓存的解析结果。
 
 HMR 收容实时刷新 rejection。其 `registerConfig(filename, refresh)` 方法从最近的现有祖先目录开始监听一个确切路径，串行化并合并刷新，并返回一个异步 disposer；该 disposer 会关闭 watcher 并排空活跃工作。确切路径和普通配置文件的刷新都使用此队列。失败会被规范化为 `Error`、记入日志，并通过并行事件 `hmr/config-update-failed(filename, error)` 广播；发生 rejection 的观察者会被记录，但不会阻止后续刷新。创建、变更和移除均会被观察。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
index 6a898fa0a4..6b430602ec 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-glob-sampling.md
 2026-07-27-glob-sampling.md: 67912cf290b127a96819d57f30387197af68323d
-2026-07-27-glob-sampling.zh.md: e339a5f87b483849df60feb726b061fe85074300
+2026-07-27-glob-sampling.zh.md: 400df369e2a537abbd8c49e0df02cd0b80f86f1b
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
index e339a5f87b..400df369e2 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
@@ -20,21 +20,21 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-**只保留按修改时间排序的前部。** 测量实际故障形态后否决。某些部署需要这种稳定排序；但重视工作区定位的部署可以显式选择具有代表性的数据，而不必要求模型怀疑自己拿到的唯一一批路径。
+**只保留按修改时间排序的前部。**测量实际故障形态后否决。某些部署需要这种稳定排序；但重视工作区定位的部署可以显式选择具有代表性的数据，而不必要求模型怀疑自己拿到的唯一一批路径。
 
-**为采样选项提供默认值。** 否决。没有全产品范围的证据支持把任一排序作为隐式契约，因此每个组合都必须选择一种，配置错误则在加载时失败。
+**为采样选项提供默认值。**否决。没有全产品范围的证据支持把任一排序作为隐式约定，因此每个组合都必须选择一种，配置错误则在加载时失败。
 
-**对所有结果采样。** 否决。完整结果没有因截断损失任何信息，因此按修改时间排序仍有助于回答关注新旧时间的问题。只有当截取前部已经无法描述整体时，才开始采样。
+**对所有结果采样。**否决。完整结果没有因截断损失任何信息，因此按修改时间排序仍有助于回答关注新旧时间的问题。只有当截取前部已经无法描述整体时，才开始采样。
 
-**改为最新优先排序。** 否决。这只会改变哪一棵结果集中的子树可能占据主导；既取消了现有的最旧优先契约，也没有让受限页面更具代表性。
+**改为最新优先排序。**否决。这只会改变哪一棵结果密集的子树可能占据主导；既取消了现有的最旧优先约定，也没有让受限页面更具代表性。
 
-**仅在偏斜超过阈值时采样。** 否决。目前没有证据支持适用于所有部署的统一阈值，模型也无法判断当前采用的是哪一种排序契约。现有上限是可以清楚解释的切换点。
+**仅在偏斜超过阈值时采样。**否决。目前没有证据支持适用于所有部署的统一阈值，模型也无法判断当前采用的是哪一种排序约定。现有上限是可以清楚解释的切换点。
 
-**在顶层以下递归平衡。** 暂缓。按第一路径段做平衡已经修复观测到的故障；更深层的平衡需要一套尚无依据的深度与广度取舍策略。
+**在顶层以下递归平衡。**暂缓。按第一路径段做平衡已经修复观测到的故障；更深层的平衡需要一套尚无依据的深度与广度取舍策略。
 
-**新增面向模型的 `list` 工具。** 实现评审后否决。默认编程组合已经提供通用 bash，模型也理解 `ls`；重复工具会永久增加 schema 与提示词所占的 token，并引入排序、分页、符号链接、转义、UI 与快照契约，却没有独立的安全或策略收益。不向模型提供 bash 工具的精简部署也不会因本次改动获得目录定位能力。
+**新增面向模型的 `list` 工具。**实现评审后否决。默认编程组合已经提供通用 bash，模型也理解 `ls`；重复工具会永久增加 schema 与提示词所占的 token，并引入排序、分页、符号链接、转义、UI 与快照约定，却没有独立的安全或策略收益。不向模型提供 bash 工具的精简部署也不会因本次改动获得目录定位能力。
 
-**拒绝 `*`，或在不含分隔符的模式前静默加上根目录锚点。** 否决。同样的「在任意深度匹配文件名」行为使 `*.ts` 可以有效地跨目录树搜索。记录这条规则能够保留正常工作的 Ripgrep 语义。
+**拒绝 `*`，或在不含分隔符的模式前静默加上根目录锚点。**否决。同样的「在任意深度匹配文件名」行为使 `*.ts` 可以有效地跨目录树搜索。记录这条规则能够保留正常工作的 Ripgrep 语义。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
index 7950dc88f3..1eb96e4d24 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-28-themed-scrollbars-and-reserved-gutter.md
 2026-07-28-themed-scrollbars-and-reserved-gutter.md: ba3d9d3c94cf9a775c43c14e292187b3a43935fe
-2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 51d668f584ee254183d5d1cf709140df2556e8d0
+2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: c0577e158e111651c917a43b7aa65f1d904d7af1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
index 51d668f584..c0577e158e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
@@ -20,9 +20,9 @@ Status: implemented
 
 两种渲染互斥，而这种互斥是被强制的，不是假定的。`scrollbar-width` 或 `scrollbar-color` 只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中。因此无条件地同时声明会让 hover token 在任何地方都得不到渲染：实现了 hover 伪元素的引擎，恰恰就是被标准属性静音的那些，而 Firefox 没有 hover 伪元素可作退路。于是标准属性写在 `@supports not selector(::-webkit-scrollbar)` 之内，该条件只在伪元素未被实现处为真，因此 Firefox 走标准属性路径，WebKit 系引擎走伪元素路径。WebKit 规则不再反向加门禁：不实现这些伪元素的引擎会把它们当作未知选择器丢弃，因此加门禁只是重述选择器匹配本身已经做的事。对于旧到不支持 `selector()` 函数的引擎，该条件无效，从而求值为假并选中伪元素路径——对于这条判断下现实存在的 16.4 之前的 Safari，这正是正确的一侧。
 
-两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
+两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定约定，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 Agent Note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
 
-`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定契约由机械检查而非人工审阅把关。
+`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定约定由机械检查而非人工审阅把关。
 
 抬升表面集合是从调色板自身的暗色抬升阶梯解析出来的——暗色取值落在 `bg-layer-2` 或 `bg-layer-3` 上的那些表面 token，而这一档正是 l1/l2 之分所编码的层级差。最初的做法是从已经做了重新绑定的样式表反向推导，那是不成立的：这样得到的集合只能确认别人已经记得的部分，而尚无人重新绑定的表面——恰恰就是这项检查存在的理由——会把自己定义成「非抬升」。`--dsw-specific-tip` 证明了这一点：它解析到与菜单表面相同的那一档，待办面板在它上面滚动却没有重新绑定，而推导式的检查依然是绿的。
 
@@ -42,7 +42,7 @@ Status: implemented
 
 **把这两个属性绑定在 `html` 上。** 这是文档级皮肤最自然的落点，而它的失败是可测量的：规则挂在 `html` 上时，chromium 中滚动容器计算出的 `scrollbar-color` 为 `auto`，因为别名 token 在那个作用域内不存在。
 
-**只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定契约——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
+**只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定约定——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
 
 **不加 `@supports` 门禁，无条件同时声明标准属性与伪元素。** 这正是本次变更最初提交的形态，被评审发现。在 chromium 中于带 `scrollbar-gutter: stable`（使条带可观测）的探针元素上实测：单独一条 8px 的 `::-webkit-scrollbar` 预留出 30px 条带（样式表指定的宽度加上浏览器自带的按钮），而给同一元素加上 `scrollbar-width: thin` 后降到 `thin` 所预留的 10px——说明伪元素规则是被丢弃，而不是被合并。全部 `::-webkit-scrollbar-thumb:hover` 规则随之失效，因此两个 hover token 与四处抬升表面的 hover 重新绑定，在多数用户实际使用的引擎上都是死代码。
 
@@ -57,7 +57,7 @@ Status: implemented
 - 客户端的每个滚动容器都绘制带主题的滑块：亮色基础表面为 `rgb(229, 229, 229)`，暗色基础表面为 `rgb(60, 60, 61)`，重新绑定到 l2 的暗色抬升表面为 `rgb(84, 85, 87)`。侧边栏内的滚动区域经由同一组间接变量，只在指针到达时才绘制滑块。
 - 两种渲染分别指定，因此改动滑块的几何或 hover 行为需要改两处：一处在 `scrollbar-width`／`scrollbar-color`，一处在伪元素。让两者都经由这组间接变量，把这份重复限制在 Firefox 与 WebKit 不共用的那些属性上。
 - hover token（`--dsw-alias-scrollbar-hover-l1`／`-l2`）只在伪元素路径上渲染。Firefox 通过 `scrollbar-color` 只表述一个滑块颜色，其 hover 表现由引擎自行推导，因此对 hover 颜色的设计改动在 Chromium 与 Safari 上可见，在 Firefox 上不可见。这是 `scrollbar-color` 本身的限制，不是这张样式表的限制。
-- `body *` 匹配所有元素，涉及的两个属性其效果本就被浏览器限制在实际会滚动的元素上。代价是一个覆盖面很宽的选择器；另一种选择是一个不生效的重新绑定契约。
+- `body *` 匹配所有元素，涉及的两个属性其效果本就被浏览器限制在实际会滚动的元素上。代价是一个覆盖面很宽的选择器；另一种选择是一个不生效的重新绑定约定。
 - 工作区列表在任何列表长度下都永久少了预留空位那一条宽度。这正是该修复换来的代价：以稳定的行几何，换掉只在列表较短时才可读的时间戳。
 - 调色板中没有轨道 token，因此日后若设计需要不透明轨道，要新增一个别名 token，而不是在这张样式表里写字面颜色。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
index 967a0ebcf4..d40bdb486e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-28-web-agent-runtime-context.md
 2026-07-28-web-agent-runtime-context.md: 6c2bb8faf0db56d2a29b47726ab295c3501cce2d
-2026-07-28-web-agent-runtime-context.zh.md: 09cbbdeabc244c265381b1ad67c3629b4c0763f5
+2026-07-28-web-agent-runtime-context.zh.md: 810f5df6712116baf1d00a7040f6f7be9b73fea1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
index 09cbbdeabc..810f5df671 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
@@ -6,27 +6,27 @@ Status: implemented
 
 ## 问题
 
-CLI 共享 base 配置了空的部署 persona，Web overlay 没有替换它，而 Web 启动器既未添加源码提示词段，也未添加交互界面提示词段。会话 header 会记录工作目录，供工具与持久化使用，但模型提示词既不说明该目录，也不标识 DeepSeek Harness Web GUI。因此，当用户提出「修改这个页面的主题」之类的请求时，即使用户指的是承载当前会话的 GUI，agent 也只能在所选项目中搜索一个未明确说明的页面。
+CLI（命令行界面）共享 base 配置了空的部署 persona，Web overlay 没有替换它，而 Web 启动器既未添加源码提示词段，也未添加交互界面提示词段。会话 header 会记录工作目录，供工具与持久化使用，但模型提示词既不说明该目录，也不标识 DeepSeek Harness Web GUI。因此，当用户提出「修改这个页面的主题」之类的请求时，即使用户指的是承载当前会话的 GUI，agent（智能体）也会在所选项目中搜索一个未明确说明的页面。
 
 ## 决策
 
-Web profile 会组合 `dsh-base` 与 `dsh-web-app` 两个组合包。Web 组合包提供一段简洁的编码 agent persona，其中包含解析后的 `{{model}}` 与会话 `{{cwd}}`；当 `surfaceContext` 为 true 时，其 `web-runtime` 插件会添加 `app:web-surface` 提示词段。挂载 profile 配置树前，`dsh web` 别名会读取组合后的同一项设置，并且仅在启用表层上下文时安装现有的 `harness:source` 提示词段。无头组合包和拥有完整提示词的 profile 都会设置 `surfaceContext: false`，从而抑制 Web 提示词与受管 shell 事实；Web 别名也会抑制源码提示词段，而无需检查 overlay 路径。每项已挂载的提示词贡献仍会在 agent loop（智能体循环）等消费方发出 request header 前激活。源码提示词段的措辞，以及其中不得从一条路径推断另一条路径的警告，均由另行记录的[源码 checkout 与工作目录区分决策](2026-07-30-source-checkout-workdir-distinction.md)负责。
+Web profile 会组合 `dsh-base` 与 `dsh-web-app` 两个组合包。Web 组合包提供一段简洁的编码 agent persona，其中包含解析后的 `{{model}}` 与会话 `{{cwd}}`；当 `surfaceContext` 为 true 时，其 `web-runtime` 插件会添加 `app:web-surface` 提示词段。挂载 profile 配置树前，`dsh web` 别名会读取组合后的同一项设置，并且仅在启用界面上下文时安装现有的 `harness:source` 提示词段。无头组合包和拥有完整提示词的 profile 都会设置 `surfaceContext: false`，从而抑制 Web 提示词与受管 shell 事实；Web 别名也会抑制源码提示词段，而无需检查 overlay 路径。每项已挂载的提示词贡献仍会在 agent loop（智能体循环）等消费方发出 request header 前激活。源码提示词段的措辞，以及其中不得从一条路径推断另一条路径的警告，均由另行记录的[源码 checkout 与工作目录区分决策](2026-07-30-source-checkout-workdir-distinction.md)负责。
 
 Web 提示词段把未限定的「这个页面」「这个 GUI」或「这个应用」解释为 DeepSeek Harness Web GUI。同时，它会明确说明浏览器不会隐式提供 DOM、路由或截图上下文，使模型能够识别产品，但不会声称掌握未收到的视觉状态。组装后的文本会记录在 `request/header` 中，从而保持「模型可见内容必须有日志记录」这一不变量。
 
 ## 验证
 
-Web 运行时单元测试会固定启用和禁用 `surfaceContext` 时的行为，Web 别名单元测试则会固定组合后配置行对源码提示词段的默认启用与显式禁用门控。无密钥的 Web fresh-round-trip 场景会启动已交付的 base 与 Web 组合包，通过 HTTP／SSE 应用运行一个真实会话，并在规范化源码路径与工作目录后对系统提示词前缀生成快照。该快照按请求顺序固定 harness 身份、源码 checkout、Web 界面定位，以及解析后的编码 agent persona。Core Web 快照会应用 RL overlay，并固定不含源码提示词段或 Web 提示词段的完整系统提示词。
+Web 运行时单元测试会固定启用和禁用 `surfaceContext` 时的行为，Web 别名单元测试则会固定组合后配置行对源码提示词段的默认启用与显式禁用门控。无密钥的 Web fresh-round-trip 场景会启动已交付的 base 与 Web 组合包，通过 HTTP／SSE（Server-Sent Events）应用运行一个真实会话，并在规范化源码路径与工作目录后对系统提示词前缀生成快照。该快照按请求顺序固定 harness 身份、源码 checkout、Web 界面定位，以及解析后的编码 agent persona。Core Web 快照会应用 RL overlay，并固定不含源码提示词段或 Web 提示词段的完整系统提示词。
 
 ## 考虑过的替代方案
 
-**每次提示词都发送 URL、DOM 或截图。** 本次故障只需要稳定的产品定位；当前根 URL 无法标识所选组件，消息契约中也不存在视觉捕获内容。添加动态页面状态需要另行设计可记录的模型输入，不属于本次修复的隐含范围。
+**每次提示词都发送 URL、DOM 或截图。** 本次故障只需要稳定的产品定位；当前根 URL 无法标识所选组件，消息约定中也不存在视觉捕获内容。添加动态页面状态需要另行设计可记录的模型输入，不属于本次修复的隐含范围。
 
 **要求会话 Workspace 必须是 harness checkout。** Workspace cwd 是用户任务的目标，可以合理地指向空项目或其他仓库。将其与应用源码位置混为一谈会破坏这一边界，并且仍无法消除已安装版本或外部启动会话中的歧义。
 
-**把 Web 文案放入全局 harness 身份。** `dsh-system-prompt` 还服务于 TUI、ACP、SDK 和不在浏览器中运行的自定义部署。该界面事实应由组装 Web 应用负责。
+**把 Web 文案放入全局 harness 身份。** `dsh-system-prompt` 还服务于 TUI、ACP（Agent Client Protocol）、SDK 和不在浏览器中运行的自定义部署。该界面事实应由组装 Web 应用负责。
 
-**为所有 CLI 界面修改现有源码位置提示词段。** TUI 也复用源码位置提示词段，而该段只陈述 checkout 事实。单独保留 Web 界面定位可以维持这份可复用契约，避免错误地告诉无头或终端 agent 它们正处于浏览器中。
+**为所有 CLI 界面修改现有源码位置提示词段。** TUI 也复用源码位置提示词段，而该段只陈述 checkout 事实。单独保留 Web 界面定位可以维持这份可复用约定，避免错误地告诉无头或终端 agent 它们正处于浏览器中。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
index 0e8b50db1a..ba1531be74 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-28-web-gui-feedback-loop.md
 2026-07-28-web-gui-feedback-loop.md: aa488e1df087722c072d98c67d47cdf63a42f6b8
-2026-07-28-web-gui-feedback-loop.zh.md: d9de988e5a2cc57794ff628b65eb050dee610747
+2026-07-28-web-gui-feedback-loop.zh.md: 17d25eaf8ec49423b554b7993ff7f9e267f7c91c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
index d9de988e5a..17d25eaf8e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
@@ -8,21 +8,21 @@ Status: implemented
 
 Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道用户正在查看哪个 URL。[运行时上下文决策](2026-07-28-web-agent-runtime-context.md)提供前一项事实，但 GUI 编辑仍然没有可执行的验收目标：源码编辑、产物构建、监听中的进程与用户已打开的页面只是互不关联的观察结果。仓库提供的入口让错误的替代方案显得合理，因为 `apps/web/package.json` 将 `vite` 暴露为 `dev` 脚本，而裸 Vite 即使无法注入 `window.__DSH_BOOT__`，仍会返回 HTTP 200。
 
-[事故复盘](../../../../docs/postmortem/0003-web-agent-gui-feedback-loop.md)集中记录事件日志时间线，并解释原有检查为何会接受错误的页面、进程和端口。
+[事故复盘（postmortem）](../../../../docs/postmortem/0003-web-agent-gui-feedback-loop.md)集中记录事件日志时间线，并解释原有检查为何会接受错误的页面、进程和端口。
 
 ## 决策
 
 常规 `dsh web` 组合会挂载 Web 组合包的 `web-runtime` 插件，由它发布一个规范的回环 URL 及其实际运行时模式，同时将二者作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 和 `DSH_WEB_MODE=production|development` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。拥有完整提示词的 profile 会把该配置行的 `surfaceContext` 设为 false，并且不会收到该提示词段和这些受管变量中的任何一个；Web 启动器也会使用同一项设置来抑制其源码 checkout 提示词段。
 
-按模式区分的提示词让 agent 而非用户负责隐藏的启动契约。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
+按模式区分的提示词让 agent 而非用户负责隐藏的启动约定。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
 
 `apps/web` 开发脚本和 Vite 配置都会在打开端口前拒绝服务模式。诊断信息会指出 `apps/web` 只是一个仅供构建的外壳，说明只有 `dsh web` 才会注入 `window.__DSH_BOOT__`，并给出生产入口与 HMR 入口路径。Vite 构建模式保持不变。
 
-静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务契约负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。
+静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务约定负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。
 
 ## 验证
 
-无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI 冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发契约。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
+无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI（命令行界面）冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发约定。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
 
 ## 考虑过的替代方案
 
@@ -36,4 +36,4 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 ## 影响
 
-常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式契约会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
+常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式约定会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
index cbc9924c07..7bce30803e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-29-human-transcript-append-origin.md
 2026-07-29-human-transcript-append-origin.md: 9804d3d8d67a4ad00c3d395c2081fd47e03c254a
-2026-07-29-human-transcript-append-origin.zh.md: 909f0756dd29c9deddb840a188eb19a773f92d29
+2026-07-29-human-transcript-append-origin.zh.md: ad952b697a11bd8f2d72785ec013bcf3e973db04
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
index 909f0756dd..ad952b697a 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
@@ -1,53 +1,53 @@
-# Agent Note: 人类可读记录投影追加来源的事件
+# Agent Note: 人类 transcript 投影追加来源的事件
 
 Status: implemented
 
 [English](2026-07-29-human-transcript-append-origin.md) | 中文
 
-## Problem
+## 问题
 
-终端与宿主历史网关都把模型可见的 surface 当作人类可读记录（transcript）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message` 和 `assistant/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志溯源信息与引用它的替换之间。
+终端与宿主历史网关都把模型可见的 surface 当作人类 transcript（文本记录）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message` 和 `assistant/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志溯源信息与引用它的替换之间。
 
 日志本身没有丢失任何内容。`Session.events` 仍保存着每条原始消息和完整的工具结果；surface 只决定接下来发送给模型的内容。缺陷完全在投影层。
 
-## Decision
+## 决策
 
-模型投影与人类投影是分开的，而事件属于哪一种由事件自身的标记决定。`dsh-session` 在浏览器安全的 `surface` 模块中导出按两种 `SurfaceOp` 变体划分的谓词 `isAppendSurfaceEvent(event)` 与 `isReplacementSurfaceEvent(event)`。追加来源的事件是记录的持久来源，替换副本仅供模型使用。凡是必须准确发送模型所见内容的部分——`deriveMessages`、token 记账、压缩后端、工具配对、注入上下文的存活判断、跨会话引用投影——都继续读取 `session.surface`。
+模型投影与人类投影是分开的，而事件属于哪一种由事件自身的标记决定。`dsh-session` 在浏览器安全的 `surface` 模块中导出按两种 `SurfaceOp` 变体划分的谓词 `isAppendSurfaceEvent(event)` 与 `isReplacementSurfaceEvent(event)`。追加来源的事件是 transcript 的持久来源，替换副本仅供模型使用。凡是必须准确发送模型所见内容的部分——`deriveMessages`、token 记账、压缩后端、工具配对、注入上下文的存活判断、跨会话引用投影——都继续读取 `session.surface`。
 
-终端从追加来源的 surface 事件回放记录，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且两条路径都按同一个标记对 surface 事件分类，因此实时到达的压缩与恢复后回放同一份日志会产生相同的记录。只有回放会重新推导 `tool/call` 的配对关系：调用事件自身不携带标记，其归属继承自公布它的 `assistant/message`，而实时监听器必然刚刚渲染过后者。
+终端从追加来源的 surface 事件回放 transcript，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且两条路径都按同一个标记对 surface 事件分类，因此实时到达的压缩与恢复后回放同一份日志会产生相同的 transcript。只有回放会重新推导 `tool/call` 的配对关系：调用事件自身不携带标记，其归属继承自公布它的 `assistant/message`，而实时监听器必然刚刚渲染过后者。
 
-检查点通过压缩接缝自身的契约来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
+检查点通过压缩seam自身的约定来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
 
 `session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。
 
-持久事件、RPC 信封、压缩事务与模型可见的 surface 都没有变化，也不需要迁移。
+已持久化事件、RPC 信封、压缩事务与模型可见的 surface 都没有变化，也不需要迁移。
 
-## Deferred
+## 延后事项
 
-浏览器客户端在[Web 记录投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份 append 来源记录并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝该范围。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。
+浏览器客户端在[Web transcript 投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份追加来源 transcript并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝这个检查点。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，旧规则会把整段被遮蔽的范围一起拉到该页。
 
 终端的[已归档实时压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用独立标记对中的事件驱动现有的单格指示器。它既不改变本文所负责的完成标记，也不添加规模信息：检查点的 `sourceEventSeqs` 仍可供经另行论证的计数或区间使用。因此，进度显示既不需要修改标记内容，也不以提取 `renderReplacement(event)` 为前置条件。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的契约，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。接缝已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
+**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的约定，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。seam已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
 
 **继续把检查点渲染为注入上下文卡片。** 被否决：带框的检查点是为模型撰写的指令信封，不是人类对话内容。展示它却隐藏它替换掉的历史，正好颠倒了读者的需要。
 
-**持久化第二份展示用记录。** 被否决：仅追加的日志已经包含权威源材料，平行记录换不来任何东西，反而增加迁移与一致性工作。
+**持久化第二份展示用 transcript。** 被否决：仅追加的日志已经包含权威源材料，平行 transcript换不来任何东西，反而增加迁移与一致性工作。
 
-**用 `compact/*` 括号而不是检查点来推导标记。** 就记录而言被否决：括号是围绕一次操作的一对时间点标记，而记录需要的是 surface 真正发生变化的位置。括号适合作为进度与耗时的来源，而本次变更并不渲染这些。
+**用 `compact/*` 括号而不是检查点来推导标记。** 就 transcript 而言被否决：括号是围绕一次操作的一对时间点标记，而 transcript 需要的是 surface 真正发生变化的位置。括号适合作为进度与耗时的来源，而本次变更并不渲染这些。
 
 **像 `session-query` 为搜索所做的那样重新折叠日志来分类事件（`current`／`shadowed`／`log-only`）。** 被否决：折叠回答的是整份日志的问题，而投影问的是逐事件的问题，事件自身的标记已能以常数时间给出答案。
 
-## Consequences
+## 后果
 
 压缩不再抹掉终端历史；被压缩多次的会话会按日志顺序显示每次落地压缩对应的一行标记。分页的每一页可以携带比以前更多的原始事件，因为额度只花在人类或模型真正产生的消息上。
 
-`rebuildTranscript` 现在会为整份日志中的每个追加来源事件物化一个组件，并在挂载时、终端配色方案变化时以及每次切换 reasoning 时运行。压缩此前正好为压缩所服务的那些长会话限制了这项工作量，因此这份开销现在随会话长度增长，而不再随 surface 增长。这正是本次修复要做的取舍——保留历史才是目的——但窗口化或复用策略属于第一个真正测到重建变慢的人，而不属于日后某个疑惑工作量为何增长的性能分析者。
+`rebuildTranscript` 现在会为整份日志中的每个追加来源事件物化一个组件，并在挂载时、终端配色方案变化时以及每次切换推理（reasoning）时运行。压缩此前正好为压缩所服务的那些长会话限制了这项工作量，因此这份开销现在随会话长度增长，而不再随 surface 增长。这正是本次修复要做的取舍——保留历史才是目的——但窗口化或复用策略属于第一个真正测到重建变慢的人，而不属于日后某个疑惑工作量为何增长的性能分析者。
 
-`dsh-tui` 为一个纯谓词新增了对 `dsh-compact` 接缝的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。
+`dsh-tui` 为一个纯谓词新增了对 `dsh-compact` seam的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。
 
-两项行为随其测试一起改变。表层替换的终端测试此前钉住的是抹除（“隐藏被遮蔽的工具调用”），现在钉住的是保留加恰好一行标记，其中被裁剪的结果副本、重新生成的 assistant 消息以及来自其他插件的替换都不渲染任何内容。压缩快照场景此前声称钉住压缩，却写入了 `workspace-context` 来源；现在它写入真实的检查点来源，并重新录制三份 fixture，以显示被保留的提示、完整的工具卡片和那行标记。
+两项行为随其测试一起改变。表层替换的终端测试此前钉住的是抹除（「隐藏被遮蔽的工具调用」），现在钉住的是保留加恰好一行标记，其中被裁剪的结果副本、重新生成的 assistant 消息以及来自其他插件的替换都不渲染任何内容。压缩快照场景此前声称钉住压缩，却写入了 `workspace-context` 来源；现在它写入真实的检查点来源，并重新录制三份 fixture（测试前置数据），以显示被保留的提示、完整的工具卡片和那行标记。
 
-上文的实时／回放等价性由 fixture 钉住，而不只是在此断言：`surface-replayed-compaction` 在挂载时替换已经存在，其录制结果与实时路径的 `surface-after-compaction-wide` 逐字节一致。改动任一路径都会破坏这项相等——这正是要点：回放投影才是当初对用户造成回归的部分，两份 fixture 必须一起变动。
+上文的实时／回放等价性由 fixture 钉住，而不只是在此断言：`surface-replayed-compaction` 挂载时替换事件已存储，其录制结果与实时路径的 `surface-after-compaction-wide` 逐字节一致。改动任一路径都会破坏这项相等——这正是要点：回放投影才是当初对用户造成回归的部分，两份 fixture 必须一起变动。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml
index b1bdfe74c2..11c7a8935a 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-29-pnpm-setup-runner-isolation.md
 2026-07-29-pnpm-setup-runner-isolation.md: 74b672b3f90ea445ad1a8e283a5904056059b2f8
-2026-07-29-pnpm-setup-runner-isolation.zh.md: 32c667dc09e561504e8e053bf2a338ed2190d9e8
+2026-07-29-pnpm-setup-runner-isolation.zh.md: fde4cb747e41ea7dafe87ca3ccd0e872c45dd3b1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md
index 32c667dc09..fde4cb747e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-[主 CI 工作流](../../../../.github/workflows/ci.yml)中的每个 `pnpm/action-setup` 步骤都设置 `dest: ${{ runner.temp }}/setup-pnpm`。每个 runner 服务独占自己的临时目录，因此一个设置过程无法替换另一个 runner 的安装目录。持久 store 的复用仍由 `PNPM_CONFIG_STORE_DIR` 独立处理，遵循 [pnpm 提供机制决策](../process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md)。
+[主 CI 工作流](../../../../.github/workflows/ci.yml)中的每个 `pnpm/action-setup` 步骤都设置 `dest: ${{ runner.temp }}/setup-pnpm`。每个 runner 服务独占自己的临时目录，因此一个设置过程无法替换另一个 runner 的安装目录。持久 store 的复用仍由 `PNPM_CONFIG_STORE_DIR` 独立处理，遵循 [pnpm 配置决策](../process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md)。
 
 [工作流回归测试](../../../../scripts/ci-workflow.spec.ts)会找出 `ci.yml` 中的每个 `pnpm/action-setup` 步骤，并拒绝缺少 runner 专属目标目录的步骤。这可确保后续新增的作业也处于同一隔离边界内。
 
@@ -24,4 +24,4 @@ Status: implemented
 
 ## 后果
 
-pnpm 可执行文件采用临时安装，并按 runner 隔离；包下载仍使用已配置的持久或缓存 store。托管作业使用相同的显式目标目录，不改变缓存政策。工作流中的每个设置步骤因此增加三行配置；只有在 pnpm 提供机制有意迁移到另一种隔离机制时，才需要更新回归测试。
+pnpm 可执行文件采用临时安装，并按 runner 隔离；包下载仍使用已配置的持久或缓存 store。托管作业使用相同的显式目标目录，不改变缓存政策。工作流中的每个设置步骤因此增加三行配置；只有在 pnpm 配置有意改用另一种隔离机制时，才需要更新回归测试。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
index fdb487f16b..373e0d70d7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-29-sticky-composer-conversation-scroll.md
 2026-07-29-sticky-composer-conversation-scroll.md: 8657080078e475d6e90f17a6c0f8cb5b2fb1555d
-2026-07-29-sticky-composer-conversation-scroll.zh.md: a588903adf51c6fcdd01f851d4f5e6570f695242
+2026-07-29-sticky-composer-conversation-scroll.zh.md: 7b9a59933d979577ea50d339f4bb276557e67081
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md
index a588903adf..7b9a59933d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md
@@ -1,22 +1,22 @@
-# Agent Note: 固定标题栏，sticky 编辑器位于 transcript 滚动容器内
+# Agent Note: 固定标题栏，sticky 编辑器位于 transcript（文本记录）滚动容器内
 
 Status: implemented
 
 [English](2026-07-29-sticky-composer-conversation-scroll.md) | 中文
 
-## Problem
+## 问题
 
 活跃会话列把滚动拆成两段：聊天（以及 trajectory）视图自有 `overflow-y: auto`，编辑器栈则作为该滚动容器的兄弟节点坐在下方。指针落在统计行或输入区上时，滚轮打在不可滚动区域上因而毫无效果——只有指针在消息列表上时 transcript 才会移动。草稿变长时更糟：textarea 本身也是滚动容器，编辑器上的滚轮可能被截在那里。会话标题栏必须以普通 chrome 占据列顶（不能在滚动容器内 `position: sticky`），而编辑器必须与 transcript 贴在同一滚动容器底部，使页脚上的滚轮能带动内容流动。
 
-## Decision
+## 决策
 
-`ConversationRoot` 始终拥有同一个 `data-conversation-scroll` 主体，其中严格 `conversation.session` view outlet 位于 `data-composer-seat` 之前；该 seat 包住整条 `'conversation.composer'` chain 输出（`overlay: true` 下的 fallback 与选举出的 overlay 兄弟节点）。独立的严格 `conversation.session.header` outlet 作为 `flex: none` 列 chrome 位于滚动容器上方，并在 Session 仍为 blank 时隐藏。固定的父级树让滚动主体与 composer seat 从无 session、blank Hero 到活跃对话始终保持挂载。活跃阶段 CSS 以 `position: sticky; bottom: 0` 钉住该 seat，使用户未贴底时 Question／Approval 接管仍可见；Hero CSS 在滚动主体内居中 fallback 栈。ChatView 与 Trajectory/Waterfall 仅在宿主之外挂载时（单元测试）保留本地 scroller；位于宿主下时设为 `overflow: visible`，并通过 `closest('[data-conversation-scroll]')` 解析贴底跟随与前置锚定。
+`ConversationRoot` 始终拥有同一个 `data-conversation-scroll` 主体，其中严格 `conversation.session` view outlet 位于 `data-composer-seat` 之前；该 seat 包住整条 `'conversation.composer'` chain 输出（`overlay: true` 下的 fallback 与选举出的 overlay 兄弟节点）。独立的严格 `conversation.session.header` outlet 作为 `flex: none` 列 chrome 位于滚动容器上方，并在 Session 仍为 blank 时隐藏。固定的父级树让滚动主体与 composer seat 从无会话、blank Hero 到活跃对话始终保持挂载。活跃阶段 CSS 以 `position: sticky; bottom: 0` 钉住该 seat，使用户未贴底时 Question／Approval 接管仍可见；Hero CSS 在滚动主体内居中 fallback 栈。ChatView 与 Trajectory/Waterfall 仅在宿主之外挂载时（单元测试）保留本地 scroller；位于宿主下时设为 `overflow: visible`，并通过 `closest('[data-conversation-scroll]')` 解析贴底跟随与前置锚定。
 
 会话统计挂在 `'conversation.composer.dock'`（位于 `'conversation.input.dock'` 之上）。InputBar 的 textarea 在宿主内以 `{ passive: false }` 链式处理 `wheel`：在限高 textarea 仍能沿该方向滚动时保留原生手势；仅在自身边缘才 `preventDefault` 并将 `deltaY` 施加到宿主。
 
-Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图，而不是使用整个滚动容器的高度差。分页开始时，`ChatView` 记录第一个可见的 `data-chat-anchor-key` 及其相对滚动容器的顶部位置；请求在途期间，每次读者滚动都会重新选择当前可见的稳定锚点；页面到达后则按该行矩形的前后差值补偿。到达底部或追加读者自己的消息会取消分页锚点，因此迟到的页面不能把视图从最新内容拉走。贴底跟随采用存储状态，而不是原始滚动几何状态；读者输入如何被识别——即以与设备无关的方式偏离由最近一次交付或写入的 `scrollTop` 构成的 observed-top ledger——由[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)负责。`ChatView` 的单个 `ResizeObserver` 只会在贴底所有权仍保持时跟随流式输出、工具展开与草稿尺寸变化，且每个 chunk 不会触发第二次滚动写入。
+Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图，而不是使用整个滚动容器的高度差。分页开始时，`ChatView` 记录第一个可见的 `data-chat-anchor-key` 及其相对滚动容器的顶部位置；请求在途期间，每次读者滚动都会重新选择当前可见的稳定锚点；页面到达后则按该行矩形的前后差值补偿。到达底部或追加读者自己的消息会取消分页锚点，因此迟到的页面不能把视图从最新内容拉走。贴底跟随采用存储状态，而不是原始滚动几何状态；读者输入如何被识别——即以与设备无关的方式偏离由最近一次交付或写入的 `scrollTop` 构成的 observed-top ledger——由[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)负责。`ChatView` 的单个 `ResizeObserver` 只会在贴底所有权仍保持时跟随流式输出、工具展开与草稿尺寸变化，且每个分片不会触发第二次滚动写入。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **标题栏与编辑器都在同一列滚动容器内 sticky。** 标题栏否决：它必须作为固定布局 chrome 占据顶部，而不是参与滚动容器的 sticky 层。
 
@@ -28,6 +28,6 @@ Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图
 
 **为每一种浏览器滚动输入来源建模。** 此次窄范围修复不采用：已复现的桌面端路径使用滚轮／触控板输入。指针／触控滚动、拖动原生滚动条、键盘滚动、焦点导航与嵌套 overflow 所有权当时被留在输入来源模型之外，也未为此新增通用输入状态机。[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)后来通过 observed-top ledger 泛化了归因，补上了这一延后事项，且仍未引入输入状态机。
 
-## Consequences
+## 后果
 
-在页脚上滚轮会滚动 transcript；可见布局是固定标题栏、可滚动 transcript 与 sticky 底部编辑器。统计出现在每一个活跃视图标签上。宿主下的嵌套视图 scroller 被抑制，因而 Trajectory 的 sticky Turn 标题贴在列宿主上。并发历史加载、流式输出、工具展开与编辑器重排会保留读者的滚动决定，包括 Chromium 先推进合成器几何状态再交付事件，以及流收尾阶段的收缩钳制。贴底跟随所有权依据[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)扩展到每一种读者输入。无 session → blank Hero 与 Hero → active 都保持同一 textarea DOM 节点以及 InputHub 草稿。
+在页脚上滚轮会滚动 transcript；可见布局是固定标题栏、可滚动 transcript 与 sticky 底部编辑器。统计出现在每一个活跃视图标签上。宿主下的嵌套视图 scroller 被抑制，因而 Trajectory 的 sticky 轮次标题贴在列宿主上。并发历史加载、流式输出、工具展开与编辑器重排会保留读者的滚动决定，包括 Chromium 先推进合成器几何状态再交付事件，以及流收尾阶段的收缩钳制。贴底跟随所有权依据[读者滚动归因笔记](2026-08-06-reader-scroll-attribution-observed-top-ledger.md)扩展到每一种读者输入。无会话 → blank Hero 与 Hero → active 都保持同一 textarea DOM 节点以及 InputHub 草稿。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
index f314df3e08..e753a0e762 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-29-web-details-session-lifecycle.md
 2026-07-29-web-details-session-lifecycle.md: 41b89fc059a02e56f53b27e5a5b48fb9488b93d7
-2026-07-29-web-details-session-lifecycle.zh.md: 82fb5e0c2608cccbb786a21971a74958417b4f10
+2026-07-29-web-details-session-lifecycle.zh.md: 56be5f73874a72162f61f47539f041566f18aec3
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
index 82fb5e0c26..56be5f7387 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 **在 New Session 点击处理器中关闭详情栏。** 之所以否决：未选中表面没有会话作用域的详情，不得修改几何信息。详情栏是否关闭，应由随后对两个已定义会话 owner 的比较决定。
 
-**按会话持久化面板几何信息。** 之所以否决：产品契约需要移除陈旧上下文，而不是新增一张保存各宽度的映射。按会话保存几何信息还会在用户返回时重新打开详情栏，与选定的离开即关闭行为相悖。
+**按会话持久化面板几何信息。** 之所以否决：产品约定需要移除陈旧上下文，而不是新增一张保存各宽度的映射。按会话保存几何信息还会在用户返回时重新打开详情栏，与选定的离开即关闭行为相悖。
 
 **在会话基线就绪后保留持久化布局。** 之所以否决：这会仅为验证陈旧的查看状态，在呈现组件中重复实现启动生命周期。瞬时默认值无需就绪标志即可使重新加载具有确定性。
 
@@ -26,4 +26,4 @@ Status: implemented
 
 ## 后果
 
-详情栏在启动时保持关闭，首次会话物化时亦然。显式打开操作会使用契约默认宽度。切换到不同会话会忘记拖动后的详情宽度，因为关闭操作会写入零值，重新打开时则使用该默认值。未选中状态会将轨道的渲染宽度派生为零，同时保持首选几何信息不变；经由这些状态返回同一会话时，会恢复其宽度。重新加载会忘记侧边栏几何信息，并使详情栏恢复关闭状态。布局行为测试覆盖初始默认值、首次物化、直接及经 hero 中转的会话切换、返回同一会话，以及不存在布局存储的情况；无密钥浏览器 e2e 则通过已交付的组合驱动相同的 owner 过渡，同时检查完整网格轨道和浏览器错误。
+详情栏在启动时保持关闭，首次会话物化时亦然。显式打开操作会使用约定的默认宽度。切换到不同会话会忘记拖动后的详情宽度，因为关闭操作会写入零值，重新打开时则使用该默认值。未选中状态会将轨道的渲染宽度派生为零，同时保持首选几何信息不变；经由这些状态返回同一会话时，会恢复其宽度。重新加载会忘记侧边栏几何信息，并使详情栏恢复关闭状态。布局行为测试覆盖初始默认值、首次物化、直接及经 hero 中转的会话切换、返回同一会话，以及不存在布局存储的情况；无密钥浏览器 e2e 则通过已交付的组合驱动相同的 owner 过渡，同时检查完整网格轨道和浏览器错误。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
index 77608b33f4..91dd4d352d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-30-approval-panel-command-cap.md
 2026-07-30-approval-panel-command-cap.md: 1e4b75c106b71605a004ef35301445da76ec8cf0
-2026-07-30-approval-panel-command-cap.zh.md: aa9f708b78c8ace735e1c96c0ff9ab0a7a4d526a
+2026-07-30-approval-panel-command-cap.zh.md: 963dca00a6eda6c3bfd145828c8d7553625a4511
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
index aa9f708b78..963dca00a6 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 面板的理由与命令移入同一个滚动区域（`data-approval-scroll`），其高度上限与 composer 的草稿区完全相同；琥珀色状态条与操作按钮行位于该区域之外，因此无论内容多长，两个按钮都留在卡片内。
 
-这个上限是一个值、两个消费者，以 `--dsh-composer-text-max-height: 336px` 声明在 `ConversationRoot` 的 `.composerSeat` 上——它是 composer 链唯一的共同祖先，因为兜底的 InputBar 与被选中的接管面板是兄弟节点。`InputBar` 的草稿滚动容器与面板的滚动区域都读取它，于是同一个容器不可能给它的两种状态设出不同上限：设计同学要求的"可以跟输入框最大高度统一"，如今是样式表中的一个事实，而不是抄在两个文件里的一个数字。该区域取 `box-sizing: border-box`，因此上限指的是它的外框高度，与 composer 草稿区占据的是同一个盒子。
+这个上限是一个值、两个消费者，以 `--dsh-composer-text-max-height: 336px` 声明在 `ConversationRoot` 的 `.composerSeat` 上——它是 composer 链唯一的共同祖先，因为兜底的 InputBar 与被选中的接管面板是兄弟节点。`InputBar` 的草稿滚动容器与面板的滚动区域都读取它，于是同一个容器不可能给它的两种状态设出不同上限：设计同学要求的「可以跟输入框最大高度统一」，如今是样式表中的一个事实，而不是抄在两个文件里的一个数字。该区域取 `box-sizing: border-box`，因此上限指的是它的外框高度，与 composer 草稿区占据的是同一个盒子。
 
 该区域自身是一个 Tab 停靠点（`tabIndex={0}`，带名称的 `role="group"`）。提问 composer 的滚动体不需要这样做——它的选项行本身可聚焦，会把容器一起带过去；而这里除文本之外别无内容：没有自己的停靠点，仅用键盘的用户能走到按钮却走不到命令尾部，于是可能批准了自己没读完的东西。
 
@@ -22,31 +22,31 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**给整张卡片设上限，而不是给文本区域设。** 一条声明，不需要重构结构，而且它读起来就是字面意义上的"与输入框相同的最大高度"。之所以否决：卡片还装着状态条和操作按钮行——总高 336px 时，理由与命令只能分到约 250px，比它们所取代的草稿区更矮，而且两边数字能对上纯属状态条高度的巧合。给文本区域设上限，才能让两种状态在同一文本高度处收住，而这正是让底部不再跳动的那条性质。
+**给整张卡片设上限，而不是给文本区域设。** 一条声明，不需要重构结构，而且它读起来就是字面意义上的「与输入框相同的最大高度」。之所以否决：卡片还装着状态条和操作按钮行——总高 336px 时，理由与命令只能分到约 250px，比它们所取代的草稿区更矮，而且两边数字能对上纯属状态条高度的巧合。给文本区域设上限，才能让两种状态在同一文本高度处收住，而这正是让底部不再跳动的那条性质。
 
 **像提问 composer 那样按视口设上限（`min(60vh, 520px)`）。** 同为接管面板的兄弟组件已经这么做了，因此这是本地既有先例。之所以否决：设计同学的要求是与 InputBar 对齐，而两个接管面板形态并不相同——提问 composer 的滚动内容是一组需要用户互相比较的选项，能占多少视口就该占多少；审批面板的滚动内容则是一条命令，用户在决定之前扫读即可。按视口设上限还会让容器高度在被选中时再次跳动，只是方向相反。
 
-**对命令做省略号或截断处理。** 不需要滚动区域，不需要上限，按钮也不会移位。之所以否决：命令正是被审批的对象，隐去它的尾部等于要求用户为自己读不到的文本背书。在这里截断还是不可恢复的——面板就是审批的全部界面，没有"展开更多"的落脚处。
+**对命令做省略号或截断处理。** 不需要滚动区域，不需要上限，按钮也不会移位。之所以否决：命令正是被审批的对象，隐去它的尾部等于要求用户为自己读不到的文本背书。在这里截断还是不可恢复的——面板就是审批的全部界面，没有「展开更多」的落脚处。
 
 **把操作按钮行留在滚动区域内，只给该区域设上限。** 比把按钮行固定住少动几处。之所以否决：这会把缺陷搬进卡片内部——按钮滚出该区域，用户得先发现有滚动条才能碰到它们。
 
 ## 后果
 
 - 长命令在卡片内滚动，拒绝／允许按钮留在屏幕内。在构建产物客户端上于 900x1000 与 900x700 实测：该区域报告的 `scrollHeight` 超过 `clientHeight`，两个按钮都留在卡片内、也都留在视口内。
-- 选中接管面板不再改变 composer 容器能达到的高度，因此审批到来或解决时，上方的会话流不会有数百像素的重排。
+- 选中接管面板不再改变 composer 容器能达到的高度，因此审批到来或解决时，上方的 transcript（文本记录）不会有数百像素的重排。
 - InputBar 的 14 行上限现在通过一个自 `.composerSeat` 继承而来的自定义属性解析，且落在真正滚动草稿的那个盒子上（[两层文本共用同一个滚动容器](2026-07-31-composer-text-layers-share-one-scrollport.md)把该声明从自增高镜像层移了出去）。把输入栏渲染到该容器之外会丢掉这条声明（一个没有兜底值的未解析 `var()`），因此未来的 composer 宿主必须带上这个属性——这也正是它声明在共享容器上、而不是应用根节点上的原因。
-- 该场景录制的命令是一段 200 个 token 的字符块，远超一次往返所需。这个代价是有意付出的：没有能越过上限的内容，这个上限无法被证伪，而模型会把任何规整的载荷压缩掉（第一次录制时，模型把"alpha 重复 400 次"写成了 `printf 'alpha %.0s' {1..400}`，一条什么也证明不了的单行命令）。
+- 该场景录制的命令是一段 200 个 token 的字符块，远超一次往返所需。这个代价是有意付出的：没有能越过上限的内容，这个上限无法被证伪，而模型会把任何规整的载荷压缩掉（第一次录制时，模型把「alpha 重复 400 次」写成了 `printf 'alpha %.0s' {1..400}`，一条什么也证明不了的单行命令）。
 
 ## 验证
 
 `apps/web/tests/approval-composer.e2e.ts` 驱动的是真实组合：一个只读会话、一次被拒绝的写入、模型的越权重试，以及在面板上点击完成的回应。几何断言在两个视口高度上针对活动面板执行，并有守卫防止它空洞地成立——该区域必须确实处在滚动状态，且实测上限必须等于 composer 自身的上限，后者由测试在发送之前从活动的草稿滚动容器上读出，而不是把该像素值写死。
 
-在构建产物客户端上双向确认过。撤销上限后，该区域报告 `scrolls: false`，并长到命令的完整高度（900x1000 下，录制的字符块为 1798px，而设上限后为 336px）；在 900x700 下卡片高 680px、视口高 700px，操作按钮行底边落在 y=749——正在折叠之下，与设计同学的反馈完全一致。恢复上限后，该场景在回放模式下通过。
+在构建产物客户端上双向确认过。撤销上限后，该区域报告 `scrolls: false`，并长到命令的完整高度（900x1000 下，录制的字符块为 1798px，而设上限后为 336px）；在 900x700 下卡片高 680px、视口高 700px，操作按钮行底边落在 y=749——位于视口下方，与设计同学的反馈完全一致。恢复上限后，该场景在回放模式下通过。
 
-要复现按钮跑到屏幕外，需要的是比滚动视口更高的卡片，而不只是一张很高的卡片。composer 容器为 `position: sticky; bottom: 0`，因此在卡片尚能容纳时它会一直吸附在视口底部，按钮仍然可见——在 900x1000 下，未设上限的卡片吃掉了整个会话流，却仍把操作按钮行留在屏幕内。只有当卡片长过滚动视口，sticky 才再也无法守住底边，按钮行随之沉入折叠之下。
+要复现按钮跑到屏幕外，需要的是比滚动视口更高的卡片，而不只是一张很高的卡片。composer 容器为 `position: sticky; bottom: 0`，因此在滚动视口尚能容纳卡片时它会一直吸附在视口底部，按钮仍然可见——在 900x1000 下，未设上限的卡片吃掉了整个 transcript，却仍把操作按钮行留在屏幕内。只有当卡片长过滚动视口，sticky 才再也无法守住底边，按钮行随之沉入视口下方。
 
-几何断言块与 golden 仅在回放模式下执行，这样录制模式才能走到写入 fixture 那一步，而不是在布局检查处中断。
+几何断言块与 golden 仅在回放模式下执行，这样录制模式才能走到写入 fixture（测试前置数据）那一步，而不是在布局检查处中断。
 
-该场景只保留一份 golden —— 等待中的面板；回应之后的状态改为对世界作断言（决策结果、越权命令写出的那个文件、`DONE`、面板消失、输入框重新可用）。最初还录了一份"已回应会话流"的 golden，它在 Linux CI 上失败了：第一次被拒绝的尝试渲染的是操作系统自己的拒绝文本，而这段文本因平台而异（macOS 为 `bash: notes.txt: Operation not permitted`，Linux 为 `bash: line 1: notes.txt: Read-only file system`）。任何会话流中含有被沙箱拒绝命令的场景都会继承这一点，因此这类拒绝只能进断言，绝不能进 golden。
+该场景只保留一份 golden——等待中的面板；回应之后的状态改为对世界作断言（决策结果、越权命令写出的那个文件、`DONE`、面板消失、输入框重新可用）。最初还录了一份"已回应 transcript"的 golden，它在 Linux CI 上失败了：第一次被拒绝的尝试渲染的是操作系统自己的拒绝文本，而这段文本因平台而异（macOS 为 `bash: notes.txt: Operation not permitted`，Linux 为 `bash: line 1: notes.txt: Read-only file system`）。任何 transcript 中含有被沙箱拒绝命令的场景都会继承这一点，因此这类拒绝只能进断言，绝不能进 golden。
 
 该面板以客户端模组包的形式发布：单跑 `pnpm run build:web` 不会带上对 `ApprovalPanel.module.css` 的改动，也不会带上 `ApprovalPanel.tsx` 中新增的 `data-` 钩子——必须先执行包构建，否则浏览器测试通道会对着一个比工作树更旧的客户端做断言。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
index fa83836e46..8e8b4bcbf0 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-30-composer-context-stack-order.md
 2026-07-30-composer-context-stack-order.md: 150225ce27fa8459703170622cef754b7694e2fc
-2026-07-30-composer-context-stack-order.zh.md: f13ffc3c1136707a86ba5636a5b69304a132df01
+2026-07-30-composer-context-stack-order.zh.md: dc9c75b35fb6a34c06326c916fd422483d57289c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
index f13ffc3c11..dc9c75b35f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
@@ -10,15 +10,15 @@ Goal、Todo 与 Queue 独立注册到同一个 `conversation.input.dock` 列表
 
 ## 决策
 
-[Todo 优先的对齐决策](2026-08-02-todo-first-composer-context-order.md)规定当前的升序排列。本记录保留围绕该顺序的堆栈契约：数值间隔使未来条目可以声明预期位置，不必依赖插件激活顺序；composer bar 位于列表之后。
+[Todo 优先的对齐决策](2026-08-02-todo-first-composer-context-order.md)规定当前的升序排列。本记录保留围绕该顺序的堆栈约定：数值间隔使未来条目可以声明预期位置，不必依赖插件激活顺序；composer bar 位于列表之后。
 
 `ConversationRoot` 负责独立上下文卡片之间的 6px 间距。Goal 是一张独立的 752×36px 卡片，折叠后的 Todo 是一张独立的 752×44px 卡片。Queue 是末端 dock 条目：其 776px 包装层包含相同的 752px 面板列，并减去共享间距与具名的 5px 布局重叠量，因此后渲染的 composer 卡片只覆盖 Queue 边缘。空条目渲染为 null，不占用间距。
 
-顺序与重叠是两项独立契约。注册顺序定义语义层级，stack 上的 CSS 变量定义共享几何。系统不能仅因 Queue 是最后一个可见条目，就推断它可以与 composer 重叠，因为没有 Queue 时，Goal 或 Todo 可能成为最后一个可见上下文卡片，而它们必须与 composer 保持间隔。
+顺序与重叠是两项独立约定。注册顺序定义语义层级，stack 上的 CSS 变量定义共享几何。系统不能仅因 Queue 是最后一个可见条目，就推断它可以与 composer 重叠，因为没有 Queue 时，Goal 或 Todo 可能成为最后一个可见上下文卡片，而它们必须与 composer 保持间隔。
 
 ## 验证
 
-注册测试固定了三个顺序值。无密钥 Queue 浏览器场景同时渲染 Todo、Goal 和 Queue，固定它们的无障碍顺序，并检查其可见卡片边缘；聚焦的 Goal 与 Queue 场景覆盖各自的独立状态。
+注册测试固定了三个顺序值。无密钥 Queue 浏览器场景同时渲染 Todo、Goal 和 Queue，固定它们的无障碍顺序，并检查其可见卡片边缘；分别针对 Goal 与 Queue 的场景覆盖各自的独立状态。
 
 ## 考虑过的替代方案
 
@@ -26,7 +26,7 @@ Goal、Todo 与 Queue 独立注册到同一个 `conversation.input.dock` 列表
 
 **在 `ConversationRoot` 中分别渲染每个已知 dock id。** 不予采纳，因为这会把可扩展的列表 slot 变成硬编码的组件清单，并迫使 owner 在每新增一个注册方时随之修改。
 
-**让最后一个 dock 条目贴卡。** 不予采纳，因为 Goal 和 Todo 是独立卡片；Goal 或 Todo 缺席时的组合不得改变剩余卡片的界面语义。
+**让最后一个 dock 条目与 composer 相接。** 不予采纳，因为 Goal 和 Todo 是独立卡片；Goal 或 Todo 缺席时的组合不得改变剩余卡片的界面语义。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml
index ed2f7646bc..6e364d9a3e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-30-hover-popup-pointer-grace.md
 2026-07-30-hover-popup-pointer-grace.md: 3f60c98ec6453b633feebe408cbc0c0c49eedea1
-2026-07-30-hover-popup-pointer-grace.zh.md: db10e156103284383f911684b2c92977a0315275
+2026-07-30-hover-popup-pointer-grace.zh.md: f53d77bae7b7f223621c4c42779e1a6a616aa485
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md
index db10e15610..f53d77bae7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-hover-popup-pointer-grace.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-工作区浏览器行弹出的两种弹层都处于指针无法抵达的位置。`HoverCard` 在指针离开锚点的第一个 `pointerleave` 上就关闭，其卡片还设置了 `pointer-events: none`；但卡片位于锚点右边缘外 8px 处，因此通往卡片的每条路径都要穿过既不属于锚点也不属于卡片的区域，卡片在指针抵达之前就已被销毁——它本应展示的完整工作区路径和会话标题只能匆匆一瞥。行操作菜单传入了 `closeOnPointerLeave`，而其处理器挂在传送后的列表上：把指针移回打开该列表的 `...` 触发按钮会关闭列表，越过列表边缘的任何一次抖动同样如此，且没有任何折返窗口。
+工作区浏览器行弹出的两种弹层都处于指针无法抵达的位置。`HoverCard` 在指针离开锚点的第一个 `pointerleave` 上就关闭，其卡片还设置了 `pointer-events: none`；但卡片位于锚点右边缘外 8px 处，因此通往卡片的每条路径都要穿过既不属于锚点也不属于卡片的区域，卡片在指针抵达之前就已被销毁——它本应展示的完整工作区路径和会话标题只能匆匆一瞥。行操作菜单传入了 `closeOnPointerLeave`，而其处理器挂在传送后的列表上：把指针移回打开该列表的 `...` 触发按钮会关闭列表，指针越过列表边缘同样会将其关闭，且没有任何折返窗口。
 
 ## 决策
 
 `usePointerGrace`（[packages/client/ui-primitives/src/pointer-grace.ts](../../../../packages/client/ui-primitives/src/pointer-grace.ts)）持有唯一一个可取消的延迟关闭，由两个原子组件共享，`POINTER_GRACE_MS` 为 200。离开会启动关闭，折返则取消它。因此指针可以安全穿越锚点与弹层之间的间隙，而真正移开的指针仍会关闭弹层。
 
-`HoverCard` 在离开时启动宽限期而不再立即关闭，其卡片也不再设置 `pointer-events: none`，因此指针停在卡片上即可让它保持打开。在已打开状态下重新进入只取消待执行的关闭，而不重启停留计时，从而避免指针穿越间隙时卡片闪烁。在卡片上按下指针用于开始文本选择，不会关闭卡片；只有锚点区域内的按下和所有者将 `disabled` 置真，才会抢在宽限期之前立即关闭卡片。
+`HoverCard` 在离开时启动宽限期而不再立即关闭，其卡片也不再设置 `pointer-events: none`，因此指针停在卡片上即可让它保持打开。在已打开状态下重新进入只取消待执行的关闭，而不重启停留计时，从而避免指针穿越间隙时卡片闪烁。在卡片上按下指针用于开始文本选择，不会关闭卡片；只有在锚点区域内发生按下操作，或所有者将 `disabled` 置真时，才会抢在宽限期之前立即关闭卡片。
 
 `Menu` 把指针离开关闭的处理从传送后的列表移到包裹 span 上。React 的 enter/leave 遍历基于 React 树进行，因此触发按钮与传送后的列表在这里属于同一区域：穿越两者之间 4px 的间隙、或把指针移回触发按钮，都不再算作离开。只有在列表打开时才会启动离开关闭；由所有者驱动的关闭（选择、Escape、外部点击）会在一个仅以 `open` 为依赖的 effect 中解除待执行的宽限关闭——若把它折叠进外部点击的 effect，则每次重新渲染都会取消宽限期，因为所有者每次都传入新的 `onClose` 闭包。
 
@@ -20,7 +20,7 @@ Status: implemented
 
 **仅通过外部点击和 Escape 关闭这两种弹层。** 之所以否决：两者都由悬停唤起，且没有可见的关闭标识；在指针已移到其他行之后仍让它们停留，会把卡片遗留在无关内容之上。
 
-**扩大锚点的命中区域，使其与弹层相接。** 之所以否决：8px 与 4px 的偏移来自设计稿，而一个不可见的桥接元素还必须跟随这两个固定定位弹层已经在滚动和缩放时执行的每一次重新定位。
+**扩大锚点的命中区域，使其与弹层相接。** 之所以否决：8px 与 4px 的偏移来自设计稿，而一个不可见的桥接元素还必须跟随这两个固定定位弹层已经在滚动和调整窗口大小时执行的每一次重新定位。
 
 **保留悬浮卡片的 `pointer-events: none`，只加入宽限期。** 之所以否决：那样指针停在卡片上时命中的是卡片背后的元素，宽限期仍会到期，并关闭用户刚刚够到的卡片。
 
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 后果
 
-悬浮卡片现在可被命中，显示期间会遮挡其覆盖区域的 244px——这是可抵达性的代价；它依然只在指针位于行或卡片上时存在。行菜单现在能承受触发按钮与列表之间的往返，而因自身原因关闭的菜单也不会被残留的待执行关闭重新关掉。未设置 `closeOnPointerLeave` 的菜单不受影响——只有设置该属性时才会挂上包裹层处理器。
+悬浮卡片现在可被命中，显示期间会遮挡其覆盖区域的 244px——这是可抵达性的代价；它依然只在指针位于行或卡片上时存在。行菜单现在能承受触发按钮与列表之间的往返，而因自身原因关闭的菜单重新打开后，也不会被残留的待执行关闭关掉。未设置 `closeOnPointerLeave` 的菜单不受影响——只有设置该属性时才会挂上包裹层处理器。
 
 ## 测试
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml
index 2f06390bdf..58e1d5691f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-30-multi-select-custom-answer-composition.md
 2026-07-30-multi-select-custom-answer-composition.md: 581beec89a0f0018ec2df687f5dfe1b1b5b86d22
-2026-07-30-multi-select-custom-answer-composition.zh.md: 5c9cb59822aca3fbf49fbbdf522c76f963df3480
+2026-07-30-multi-select-custom-answer-composition.zh.md: 796d379312483be5063a3a5d67dd6a0d0e37803e
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md
index 5c9cb59822..796d379312 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-multi-select-custom-answer-composition.zh.md
@@ -18,8 +18,8 @@ Status: implemented
 
 **把自定义文本编码为另一个 `selected` 标签。** 不予采纳，因为这样会抹去调用方提供的选项标签与用户填写文本之间的区别，削弱校验，并迫使消费方推断哪个值属于自定义内容。
 
-**允许所有问题同时使用 `selected` 与 `custom`。** 不予采纳，因为单选题只表示一个回答；允许选中选项与自定义文本并存会使其基数含义模糊。组合形式仅适用于显式选择多项回答的问题。
+**允许所有问题同时使用 `selected` 与 `custom`。** 不予采纳，因为单选题只表示一个回答；允许选中选项与自定义文本并存会使其基数含义模糊。组合形式仅适用于显式启用多回答的问题。
 
 ## 后果
 
-多选 UI 可以完整表达用户的回答，不会丢弃任一来源。提供方和消费方继续使用现有 DTO，而请求感知的校验器会根据 `multiSelect` 判断是否允许组合。Web 组件与组装浏览器的覆盖率、TUI 覆盖率、宿主响应覆盖率和工具投影覆盖率共同固定组合结果。Web、TUI 与工具投影覆盖率还固定了仅含标签的回答形态；组装后的无密钥 TUI 覆盖率固定终端中的组合回答流程，单选题的宿主覆盖率则固定其余的互斥规则。
+多选 UI 可以完整表达用户的回答，不会丢弃任一来源。提供方和消费方继续使用现有 DTO，而请求感知的校验器会根据 `multiSelect` 判断是否允许组合。Web 组件与组装浏览器的测试覆盖、TUI 测试覆盖、宿主响应测试覆盖和工具投影测试覆盖共同固定组合结果。Web、TUI 与工具投影测试覆盖还固定了仅含标签的回答形态；组装后的无密钥 TUI 测试覆盖固定终端中的组合回答流程，单选题的宿主测试覆盖则固定其余的互斥规则。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml
index 311c4971d3..527471cd2e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-30-source-checkout-workdir-distinction.md
 2026-07-30-source-checkout-workdir-distinction.md: ba6d9dd12b55a54d4ae8d2e91ad83ac3c1dc47fd
-2026-07-30-source-checkout-workdir-distinction.zh.md: ffc2ac7baa2b1bb8ce54607638c35869fc338825
+2026-07-30-source-checkout-workdir-distinction.zh.md: 06b09f82f294a70795090a9aec1b2220bd6e7512
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md
index ffc2ac7baa..06b09f82f2 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.zh.md
@@ -4,30 +4,30 @@ Status: implemented
 
 [English](2026-07-30-source-checkout-workdir-distinction.md) | 中文
 
-## Problem
+## 问题
 
-`harness:source` 提示词段遵循[源码位置决策](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md)，但原有措辞把 checkout 称为“你自己的源代码”，却没有区分该路径与会话 workspace。在 persona 不声明 `{{cwd}}` 的普通 TUI 配置中，这可能是系统提示词开头附近唯一固定的绝对路径。因此，DeepSeek V4 可能会直接用 harness checkout 回答“what's the workdir?”，而不是确定会话的当前工作目录。
+`harness:source` 提示词段遵循[源码位置决策](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md)，但原有措辞把 checkout 称为「你自己的源代码」，却没有区分该路径与会话 workspace。在 persona 不声明 `{{cwd}}` 的普通 TUI 配置中，这可能是系统提示词开头附近唯一固定的绝对路径。因此，DeepSeek V4 可能会直接用 harness checkout 回答「what's the workdir?」，而不是确定会话的当前工作目录。
 
 直接断言 checkout 不是工作目录同样不准确。`dsh meta` 会有意让源码 checkout 同时充当这两个值。
 
-## Decision
+## 决策
 
-该提示词段将路径标识为“DeepSeek Harness implementation checkout”。它说明 checkout 位置与当前工作目录是两个可能不同的值，禁止从 checkout 路径推断工作目录，指示模型使用 `pwd`，并限定该 checkout 只用于检查或扩展 DSH 自身。
+该提示词段将路径标识为「DeepSeek Harness implementation checkout」。它说明 checkout 位置与当前工作目录是两个可能不同的值，禁止从 checkout 路径推断工作目录，指示模型使用 `pwd`，并限定该 checkout 只用于检查或扩展 DSH 自身。
 
 路径推导方式、全局 `harness:source` 所有权和 `-99` 顺序均保持不变。将两者描述为概念上独立、而不是始终不相等，使这条指令在普通项目会话和 `dsh meta` 中都准确。
 
-## Verification
+## 验证
 
-`dsh-app-boot` 单元测试固定了完整文本及其顺序。CLI 无密钥 PTY 冒烟测试检查组装后的请求 header。TUI 的 `source-checkout-workdir` 快照把该提示词段挂载为 `/opt/dsh-source`，通过录制的 DeepSeek V4 turn 提问“what's the workdir?”，并要求回放 transcript 运行 `pwd`，报告生成的 workspace 而不是 checkout。
+`dsh-app-boot` 单元测试固定了完整文本及其顺序。CLI（命令行界面）无密钥 PTY 冒烟测试检查组装后的请求 header。TUI 的 `source-checkout-workdir` 快照把该提示词段挂载为 `/opt/dsh-source`，通过录制的 DeepSeek V4 turn 提问「what's the workdir?」，并要求回放 transcript（文本记录）运行 `pwd`，报告生成的 workspace 而不是 checkout。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **声明 checkout 永远不是工作目录。**拒绝：`dsh meta` 会有意让它们指向同一路径。
 
-**把当前工作目录写入全局源码提示词段。**拒绝：源码提示词段由 launcher 全局持有，而工作目录属于各个会话；将两者合并会重复 loop 对 `cwd` 的所有权，还会让稳定的源码事实随 agent 变化。
+**把当前工作目录写入全局源码提示词段。**拒绝：源码提示词段由 launcher 全局持有，而工作目录属于各个会话；将两者合并会与 agent loop（智能体循环）对 `cwd` 的所有权重复，还会让稳定的源码事实随 agent 变化。
 
 **从提示词中删除源码路径。**拒绝：launcher 从无关项目启动时，自引用 DSH 工具仍需要可靠的 checkout 位置。
 
-## Consequences
+## 后果
 
 提示词会变长，直接询问工作目录时可能多花一次廉价的 `pwd` 工具调用。作为交换，模型不再把 harness 实现路径当作隐含的任务 workspace；当 meta 模式使两个值重合时，提示词仍然准确。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index cede7ea5d9..abed6fce03 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-30-web-transcript-log-ordered-projection.md
 2026-07-30-web-transcript-log-ordered-projection.md: 3b7aaeb1178ff79e38a1b9646a9dc78efaeae48b
-2026-07-30-web-transcript-log-ordered-projection.zh.md: acd198b6d3f3c5d57e233e09ee66f5d151e4f8f1
+2026-07-30-web-transcript-log-ordered-projection.zh.md: ec60a8cdb464ded8ddc2ec46f499fe4ccc4c2f8a
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index acd198b6d3..ec60a8cdb4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -1,18 +1,18 @@
-# Agent Note: 浏览器会话是按日志顺序投影的人类对话记录
+# Agent Note: 浏览器会话是按日志顺序投影的面向人的 transcript（文本记录）
 
 Status: implemented
 
 [English](2026-07-30-web-transcript-log-ordered-projection.md) | 中文
 
-## Problem
+## 问题
 
-浏览器客户端从模型可见的 surface 构建会话：`FoldAdapter` 在历史窗口上运行核心 `SurfaceManager` 并读取 `surface.nodes`。一次成功的压缩会用一个检查点节点替换一段 surface 范围，因此该替换一落地，Web 流就把它所遮蔽的每条消息折叠成一行灰暗的上下文——那是用户已经读过的对话。日志中什么都没丢失；缺陷完全在投影层，而[终端与宿主历史网关已按同一方式修复](2026-07-29-human-transcript-append-origin.md)，浏览器留给了本次变更。
+浏览器客户端从模型可见的 surface 构建会话：`FoldAdapter` 在历史窗口上运行核心 `SurfaceManager` 并读取 `surface.nodes`。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，Web 流就把它所遮蔽的每条消息折叠成一行灰暗的上下文——那是用户已经读过的对话。日志中什么都没丢失；缺陷完全在投影层，而[终端与宿主网关已按同一方式修复](2026-07-29-human-transcript-append-origin.md)，浏览器留给了本次变更。
 
 surface 顺序还让另外两个问题成为结构性的。一次替换之后它并非按 seq 升序——`SurfaceManager` 把高 seq 的检查点拼接到它所遮蔽范围的位置上——因此按数值 seq 归并进该数组的仅日志节点（斜杠命令行、被打断的冻结节点）可能被冲刷到检查点之前，再也无法交错回保留下来的尾部。而且由于分页不再为 replacement 副本消耗 `maxMessages` 额度，一页现在可以携带一个 `surfaceOp.start` 落在窗口之外的检查点；核心 fold 拒绝该范围，于是 `nodes()` 退回到一次宽容的线性扫描、打印一条 `console.error`，并发布一个描述该失败的 `foldDegraded` 标志。
 
-## Decision
+## 决策
 
-`TranscriptAdapter` 取代 `FoldAdapter`，并且从不查询 surface 顺序。它按日志顺序投影原始窗口：每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，外加每次落地的压缩检查点一个 `CompactionSummaryNode` 标记。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话，标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不在对话中标记任何边界。凡必须发送模型所见内容的一切仍读 surface；这是人类投影，两者现在在两个前端上都已分离。
+`TranscriptAdapter` 取代 `FoldAdapter`，并且从不查询 surface 顺序。它按日志顺序投影原始窗口：每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，外加每次落地的压缩检查点一个 `CompactionSummaryNode` 标记。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话，标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入 transcript：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不在对话中标记任何边界。凡必须发送模型所见内容的一切仍读 surface；这是人类投影，两者现在在两个前端上都已分离。
 
 节点顺序天然按 seq 单调，由此有三个结果。仅日志的 `command/run` / `command/done` 对折叠成 `CommandNode`，按 seq 插入一个本已单调的数组——无锚点，无重排。`Session` 保留被打断的冻结节点的归属，用一次普通排序按其分数 seq 归并，而这现在恰好就是流顺序。检查点所引被遮蔽范围落在窗口之外的窗口没有范围需要解析，因此标记正常渲染且不打印任何日志。
 
@@ -26,7 +26,7 @@ surface 顺序还让另外两个问题成为结构性的。一次替换之后它
 
 ## 识别检查点：同一份声明，在编译期钉住
 
-识别需要三个条件同时成立，与终端一致：`event.type === 'user/message'`、压缩缝隙的检查点插件来源，**以及** `isReplacementSurfaceEvent(event)`。一条 append 的插件来源 `user/message` 是注入上下文——跨会话引用卡片——不是压缩。
+识别需要三个条件同时成立，与终端一致：`event.type === 'user/message'`、压缩 seam 的检查点插件来源，**以及** `isReplacementSurfaceEvent(event)`。一条 append 的插件来源 `user/message` 是注入上下文——跨会话引用卡片——不是压缩。
 
 从 `packages/client/*` 程序无法到达的是 `dsh-compact` 的**根部**，而不是这个包。根部会到达 `dsh-session` 的根部，后者的 cordis `Context` 合并声明了宿主侧 `sessions: SessionStore`，与客户端的 `sessions: ISessions` 冲突——`TS2717`，即 [development.md](../../../../docs/development.md#typescript-project-layout) 中每侧一个 program 的规则；这一点对仅类型导入同样成立，因为该冲突是编译器事实而非打包器事实。
 
@@ -37,7 +37,7 @@ import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpo
 const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 ```
 
-重命名缝隙的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。
+重命名 seam 的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。
 
 `packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` 作为行为侧的另一半保留，用由权威**值**构造的检查点驱动适配器。该测试以值导入方式从不含 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 叶子路径取得该值，并刻意不加载 compact 包根或经由它可达的宿主侧 `Context` 合并。
 
@@ -45,34 +45,34 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 ## #835 的位置锚点是为什么而存在，以及为什么它是被溶解而非丢失
 
-尚未合并的排队式手动压缩分支用另一种方式修同一个交错缺陷：为每个事件记录一个锚点——追加时的 surface 尾部——并把被遮蔽的锚点重定向到检查点上。该机制的存在是为了让位置锚点在 surface **重排**中存活。人类对话记录永不被重排，因此锚点没有任何东西需要重定向：前提被移除，修复并未被丢弃。该机制在本基线上并不存在，本次也不撰写它。
+尚未合并的排队式手动压缩分支用另一种方式修同一个交错缺陷：为每个事件记录一个锚点——追加时的 surface 尾部——并把被遮蔽的锚点重定向到检查点上。该机制的存在是为了让位置锚点在 surface **重排**中存活。面向人的 transcript 永不被重排，因此锚点没有任何东西需要重定向：前提被移除，修复并未被丢弃。该机制在本基线上并不存在，本次也未实现它。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-**从新叶子值导入该谓词**，并把 `dsh-compact` 加入客户端 `INLINE_SAFE` 白名单。已拒绝：客户端需要的是插件 id，不是谓词——一个类型就够了，而被擦除的导入根本不会抵达纯度门禁，因此无需向它放行任何东西。白名单只在值导入时才有意义，而在那里它是笔糟糕的交换：`INLINE_SAFE` 按标识符*前缀*匹配，因此放行该包会连它那个会导入 cordis 的根部一起放行。
+**从新叶子值导入该谓词**，并把 `dsh-compact` 加入客户端 `INLINE_SAFE` 白名单。已拒绝：客户端需要的是插件 id，不是谓词——一个类型就够了，而被擦除的导入根本不会抵达纯度门禁，因此无需向它放行任何东西。白名单只在值导入时才有意义，而在那里这是一项糟糕的权衡：`INLINE_SAFE` 按标识符*前缀*匹配，因此放行该包会连它那个会导入 cordis 的根部一起放行。
 
-**一条纯形状规则**——任何 replacement `user/message` 都是压缩。已拒绝：它今天正确只因为压缩是 replacement `user/message` 的唯一生产者，一旦这点改变便无任何机制能捕获。那个 pin 测试只花一个文件，就精确消除了这一风险。
+**一条纯形状规则**——任何 replacement `user/message` 都是压缩。已拒绝：它今天正确只因为压缩是 replacement `user/message` 的唯一生产者，一旦这点改变便无任何机制能捕获。那个 pin 测试只需一个文件，就精确消除了这一风险。
 
-**在宿主侧给检查点打标**，经投影或线协议。已拒绝：这最贴合“经 cordis 服务协作”的规则，但客户端今天折叠的是原始 `SessionEvent`，因此这意味着一次线协议契约变更——为一个纯谓词付出的代价不成比例。
+**在宿主侧给检查点打标**，经投影或线协议。已拒绝：这最贴合「经 cordis 服务协作」的规则，但客户端今天折叠的是原始 `SessionEvent`，因此这意味着一次线协议约定变更——为一个纯谓词付出的代价不成比例。
 
-**把冻结节点的归属移进适配器**（`nodes(extraNodes)`），像那个未合并分支所做的那样。已拒绝：被打断的节点来自 `Session` 已经在窗口上运行的 `turn/end` 清扫，而在按 seq 单调的记录之上，简单形态就是正确的——适配器返回节点，会话按 seq 归并冻结节点。加宽适配器签名什么也换不到，还会把清扫与它的产物拆开。
+**把冻结节点的归属移进适配器**（`nodes(extraNodes)`），像那个未合并分支所做的那样。已拒绝：被打断的节点来自 `Session` 已经在窗口上运行的 `turn/end` 清扫，而在按 seq 单调的 transcript 之上，简单形态就是正确的——适配器返回节点，会话按 seq 归并冻结节点。加宽适配器签名什么也换不到，还会把清扫与它的产物拆开。
 
-**把 `foldDegraded` 留作一个防御性标志。** 已拒绝：它描述的是一个已不再运行的 fold 的特定失败。一个消费方无法据以行动、只能通过 `console.error` 到达的标志，是一份虚假契约。
+**把 `foldDegraded` 留作一个防御性标志。** 已拒绝：它描述的是一个已不再运行的 fold 的特定失败。一个消费方无法据以行动、只能通过 `console.error` 到达的标志，是一份虚假约定。
 
 **把最近的 `/compact` 行与下一个检查点配对。** 已拒绝：两者之间可能落入上下文注入，并发或格式异常的生命周期记录也必须降级而不误取其他检查点。命令结果则指明权威摘要事件；引用存在歧义时不配对任何内容。
 
-**解析英文结算文本中的条目数量和 token 数量。** 已拒绝：处理器文案是呈现文本，而非稳定的数据契约。标记读取本已持有这两个值的结构化 `compact/summary` 载荷。
+**解析英文结算文本中的条目数量和 token 数量。** 已拒绝：处理器文案是呈现文本，而非稳定的数据约定。标记读取本已持有这两个值的结构化 `compact/summary` 载荷。
 
-## Consequences
+## 后果
 
-压缩不再抹掉 Web 历史；一个被压缩多次的会话按日志顺序显示每次落地压缩一个标记，而同一窗口在实时与冷恢复之后渲染完全相同。分页缺口是被构造性闭合而非被防御，`ConversationSnapshot` 少了一个已发布字段，这触及十三个文件。
+压缩不再抹掉 Web 历史；一个被压缩多次的会话按日志顺序显示每次落地压缩一个标记，而同一窗口在实时与冷恢复之后渲染完全相同。分页缺口从设计上得以消除，而不是靠防御性处理来规避，`ConversationSnapshot` 少了一个已发布字段，这触及十三个文件。
 
-`ConversationNode` 增加第八个分支，因此每个穷尽消费方都多一个分支：`MessageItem` 通过新的 `CompactionItem` 渲染标记，trajectory 布局加宽它的“无单元格”分支，使标记不贡献单元格但仍推进耗时游标。
+`ConversationNode` 增加第八个分支，因此每个穷尽消费方都多一个分支：`MessageItem` 通过新的 `CompactionItem` 渲染标记，trajectory 布局加宽它的「无单元格」分支，使标记不贡献单元格但仍推进耗时游标。
 
-性能契约未变，且现在更易表述：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用——因此分片风暴零成本、`nodes()` 甚至不会重算——未变化的节点保持其对象标识。窗口仍随会话长度而非随 surface 增长，这正是本修复存在所要做的交换；一次压缩过去恰好为压缩所服务的长会话限制了投影规模。
+性能约定未变，且现在更易表述：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用——因此分片风暴零成本、`nodes()` 甚至不会重算——未变化的节点保持其对象标识。窗口仍随会话长度而非随 surface 增长，这正是本修复有意作出的权衡；一次压缩过去恰好为压缩所服务的长会话限制了投影规模。
 
 Web e2e 场景现在围绕它录制的那一轮上的压缩事务播种一次真实的手动命令生命周期，因此 aria 基准经真实宿主与真实浏览器钉住完整行为：录制的提问与完整工具输出仍在屏幕上，其后恰好一条 `compact` 行报告规模，展开后会显示确切摘要。录制本身未被触碰、保持模型真实——回放从录制自身的 surface 派生出手动压缩。
 
-## Deferred
+## 延后事项
 
 终端的[已归档压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用实时独立标记对驱动单格指示器，并不改变此浏览器投影。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
index 6b8933a5f8..71f89e6866 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-composer-text-layers-share-one-scrollport.md
 2026-07-31-composer-text-layers-share-one-scrollport.md: ba11384409714d6a64a964d63197705acf39d213
-2026-07-31-composer-text-layers-share-one-scrollport.zh.md: 9a4a2bcc9f947d385d1ff9fc6367b9a3eab17733
+2026-07-31-composer-text-layers-share-one-scrollport.zh.md: cf0ce7bc344f6566d56a9e3cd81a63be5f68d614
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
index 9a4a2bcc9f..cf0ce7bc34 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx)）：`<textarea>` 持有取值、选区与光标，但它自己的字形以 `color: transparent` 渲染；用户看到的每一个字符都由其下的 `[data-input-backdrop]` 层绘制，该层同时承载 claim token 高亮、chip 与提示影子文本。这一拆分正是 chip 与高亮得以存在的前提——textarea 无法为自身文本的某个区间单独设置样式。草稿框的高度上限为 14 行，因此超过上限之后总得有东西滚动。
+composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx)）：`<textarea>` 持有值、选区与光标，但它自己的字形以 `color: transparent` 渲染；用户看到的每一个字符都由其下的 `[data-input-backdrop]` 层绘制，该层同时承载 claim token 高亮、chip 与提示影子文本。这一拆分正是 chip 与高亮得以存在的前提——textarea 无法为自身文本的某个区间单独设置样式。草稿框的高度上限为 14 行，因此超过上限之后总得有东西滚动。
 
 两层各自持有一个滚动偏移，会分两个阶段失效，本次改动是其中的第二个。
 
 第一个阶段是静态的。backdrop 为 `position: absolute; inset: 0; overflow: hidden`——只裁剪、不滚动——浏览器也不会把它的偏移与 textarea 关联起来，于是超过上限之后光标在动而文字冻结在第 1 行。未达上限时这一点不可见，因为两层都停在 0；该缺陷与高度上限同龄，藏在所有截图所捕获的那个静止状态背后。当时的修复是用一个 `scroll` 监听把 textarea 的 `scrollTop` 镜像到 backdrop 上，这让两层在**静止时**保持一致。
 
-第二个阶段正是随后被用户报告的现象：从长草稿的顶部快速滑到底部时，光标像带着惯性一样从自己的文字里往上飞出去，过一会儿又落回原位。原因就是那个镜像。滚轮手势在合成线程上滚动 textarea，不经过主线程；而驱动赋值的 `scroll` 事件在其后才派发，因此中间这些帧里光标位于新偏移、每一个字形却仍位于旧偏移。在同一套几何的独立环境上实测：把偏移改变 200px 并在本任务结束之前读取光标与其字形之间的距离，chromium 分离 203px、firefox 202px、WebKit 203px，一两帧之后才收敛到固定的行盒常量（3/2/3）。每个引擎、每次手势都如此，且滑动越快分离越远。
+第二个阶段正是随后被用户报告的现象：从长草稿的顶部快速滑动时，光标像带着惯性一样从自己的文字里往上飞出去，过一会儿又落回原位。原因就是那个镜像。滚轮手势在合成线程上滚动 textarea，不经过主线程；而驱动赋值的 `scroll` 事件在其后才派发，因此中间这些帧里光标位于新偏移、每一个字形却仍位于旧偏移。在同一套几何的独立环境上实测：把偏移改变 200px 并在本任务结束之前读取光标与其字形之间的距离，chromium 分离 203px、firefox 202px、WebKit 203px，一两帧之后才收敛到固定的行盒常量（3/2/3）。每个引擎、每次手势都如此，且滑动越快分离越远。
 
 任何监听都无法消除这个间隙，因为这个间隙正是监听的定义：它在自己所响应的那件事之后才运行。凡是用 JavaScript 维持两个盒子相等的做法，都会落后于那个不经询问就搬动其中一个盒子的合成器一帧。
 
@@ -52,7 +52,7 @@ composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/cl
 
 **去掉 backdrop，直接给 textarea 自己的文本上样式。** 这会消除分层，也一并消除这一整类失步。被否决是因为它不可实现：textarea 只渲染一段统一的文本，claim token 高亮、chip 与提示影子文本——backdrop 存在的理由——无从表达。为修滚动而失去它们，是拿一个有界缺陷换一次功能删除。
 
-**用 `contenteditable` div 渲染草稿。** 一个元素、一个偏移、区间可上样式。因代价与缺陷严重不成比例被否决：`contenteditable` 会把输入法组合、撤销/重做、选区语义与粘贴规范化重新压回我们身上，而这些目前都由 textarea 加输入状态机处理，且状态机已经持有一份假定 textarea 取值语义的撤销日志。
+**用 `contenteditable` div 渲染草稿。** 一个元素、一个偏移、区间可上样式。因代价与缺陷严重不成比例被否决：`contenteditable` 会把输入法组合、撤销/重做、选区语义与粘贴规范化重新压回我们身上，而这些目前都由 textarea 加输入状态机处理，且状态机已经持有一份假定 textarea 值语义的撤销日志。
 
 **给三层都加 `scrollbar-gutter: stable`。** 在 textarea 还是滚动者时试过并已回退：WebKit 只对 `overflow-y: auto` 生效、不对 `overflow: hidden` 生效，那 8px 的差距原样留着，却让每个 chromium 用户无条件损失 8px 文本列宽。现在已无意义——三层共享同一包含块，没有什么需要预留。
 
@@ -63,9 +63,9 @@ composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/cl
 - 光标不可能离开自己的字形。浏览器滚动的是同一个盒子，因此「textarea 把某一行放在哪」与「backdrop 把这一行画在哪」之间的距离在任何偏移下都是一个固定的行盒常量，手势进行中也不例外。场景测试度量的正是这个数。
 - 滚动条从 textarea 移到了滚动容器上——视觉位置相同，只是外移了一层。`.card` 的 l2 token 绑定仍会继承下去。
 - chip、claim token 高亮与文本引用标记在滚动时仍与其字形对齐，因为它们定位在 backdrop 内部、随之移动。除去掉哨兵之外，装饰扫描没有变化。
-- 在 Firefox 与 WebKit 上，点进一个草稿超过上限的 composer 现在还会把会话记录滚动到底部：光标的 scroll-into-view 会越过 composer 的滚动容器一路走到会话记录的滚动容器，而一个比自身盒子矮的 textarea 从不会引发这一步。chromium 不会。已实测，并试过 `overscroll-behavior: contain` 与 `contain: paint`，两者都拦不住这次上行——没有任何 CSS 能终止 scroll-into-view 的接力。接受：它滚向底部，而 composer 本来就在底部，而其替代方案是在每个引擎上都出现光标与文字明显分离。
+- 在 Firefox 与 WebKit 上，点进一个草稿超过上限的 composer 现在还会把会话 transcript（文本记录）滚动到底部：光标的 scroll-into-view 会越过 composer 的滚动容器一路走到transcript 的滚动容器，而一个比自身盒子矮的 textarea 从不会引发这一步。chromium 不会。已实测，并试过 `overscroll-behavior: contain` 与 `contain: paint`，两者都拦不住这次上行——没有任何 CSS 能终止 scroll-into-view 的接力。接受：它滚向底部，而 composer 本来就在底部，而其替代方案是在每个引擎上都出现光标与文字明显分离。
 - 翻页与拖拽选区的行为未变，二者均做了新旧对照实测。`PageDown`/`PageUp` 本来就不会移动 textarea 的插入点——chromium 是滚动一页并保持 `selectionStart` 不变，新旧几何皆然，区别只在于滚的是哪个盒子。拖拽选区越过下边缘仍会自动滚动，且落点一致（chromium 628/628、firefox 625/620、WebKit 170/170——WebKit 自动滚动较慢，但改动前后一样慢）。
-- composer 自己发起的 `focus()` 全部加了 `preventScroll`——解锁/切会话的 effect，以及工具栏按钮上那个保持焦点的 mousedown——因此一次没有任何手势要求的聚焦，不会再通过更高的 textarea 的回视链把 transcript 挪走。抑制这条链之后，光标就回到了我们手上，而这在一条路径上确实要紧：composer 的 DOM 跨会话复用，因此切到更长的草稿时旧偏移会留着，而换值会把光标放到新草稿的末尾。三引擎实测，这会让光标落在停在 0 的盒子下方 940px 处；于是该 effect 会在自己的滚动容器里把它带回来，落点 625/628——正是旧几何靠浏览器达到的 628。mousedown 那条不需要回视：光标没动过，而下一次敲键会拿到浏览器原生的回视。另一个只负责回视的 effect 会处理渲染后才到达的非空草稿：`ConversationSession` 在自己的 mount effect 中注入持久化草稿，而该 effect 在本组件的 effect 之后运行，否则第一次回视会量到空镜像，且不会再为随后出现的草稿重跑。第二个 effect 从不聚焦，因此发送后清空或发送失败后恢复这类普通的空/非空转换不会从其他控件夺走焦点。
+- composer 自己发起的 `focus()` 全部加了 `preventScroll`——解锁/切会话的 effect，以及工具栏按钮上那个保持焦点的 mousedown——因此一次没有任何手势要求的聚焦，不会再通过更高的 textarea 的回视链把 transcript 挪走。抑制这条链之后，光标就回到了我们手上，而这在一条路径上确实要紧：composer 的 DOM 跨会话复用，因此切到更长的草稿时旧偏移会留着，而换值会把光标放到新草稿的末尾。三引擎实测，这会让光标落在停在 0 的盒子下方 940px 处；于是该 effect 会在自己的滚动容器里把它带回来，落点 625/628——正是旧几何靠浏览器达到的 628。mousedown 那条不需要回视：光标没动过，而下一次敲键会拿到浏览器原生的回视。另一个只负责回视的 effect 会处理渲染后才到达的非空草稿：`ConversationSession` 在自己的 mount effect 中注入持久化草稿，而该 effect 在本组件的 effect 之后运行，因此如果没有这个独立 effect，第一次回视会量到空镜像，且不会再为随后出现的草稿重跑。第二个 effect 从不聚焦，因此发送后清空或发送失败后恢复这类普通的空/非空转换不会从其他控件夺走焦点。
 - 撤销/重做可以在不恢复光标、也不回视的情况下改动草稿：状态机重放上一版草稿，DOM 选区停在浏览器钳位后的位置。这早于本次改动且未被改动——在此点名，是因为另外两处恢复都会回视，会让这处遗漏看起来像有意为之；真被报告时 helper 就在旁边。
 - 任何新增在 backdrop 旁边的层都属于滚动容器**内部**，并且必须与草稿等高，否则就会重新引入这一缺陷。这是 composer 长期存在的风险点：两层拆分对 chip 与高亮是承重的，因此耦合必须来自结构，而不是靠维护。
 
@@ -73,7 +73,7 @@ composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/cl
 
 [input-bar.spec.tsx](../../../../packages/client/ui-conversation/tests/input-bar.spec.tsx) 中的单元用例断言 jsdom 能看见的部分：同一个滚动盒同时包含 textarea 与 backdrop，backdrop 的文本现在就是草稿本身、不多不少，且渲染后才到达的持久化草稿会回视其光标，同时不从其他控件夺走焦点。jsdom 对任何元素都报告 `scrollHeight === clientHeight` 且从不滚动，因此几何属于浏览器场景；滚轮接力用例改为桩接滚动容器的度量，而非 textarea 的。
 
-[composer-draft-scroll.e2e.ts](../../../../apps/web/tests/composer-draft-scroll.e2e.ts) 在 chromium 中针对构建产物度量其余部分：全新工作区空会话的 composer 中一份 40 行草稿，零模型调用。每个度量都在光标自己的坐标系里读取——即 textarea 把第 n 行放在哪，含其自身偏移——再与 backdrop 同一行文本上的 DOM Range 相比，因为这个差值正是用户看到的东西。决定性的用例改变偏移，并**在本任务结束之前**重新读取该差值，也就是在任何 `scroll` 监听可能运行之前：单一滚动容器下为 0，镜像方案下则是整个增量。空洞性保护先断言草稿确实超过了带上限的盒子；其余用例分别覆盖高度上限、三层同一折行宽度、滚轮手势、以换行结尾的草稿，以及过去由 textarea 自身滚动承担的光标回视路径——滚离光标后输入，必须把滚动容器带回光标处。
+[composer-draft-scroll.e2e.ts](../../../../apps/web/tests/composer-draft-scroll.e2e.ts) 在 chromium 中针对构建产物度量其余部分：全新工作区的空白 composer 中一份 40 行草稿，零模型调用。每个度量都在光标自己的坐标系里读取——即 textarea 把第 n 行放在哪，含其自身偏移——再与 backdrop 同一行文本上的 DOM Range 相比，因为这个差值正是用户看到的东西。决定性的用例改变偏移，并**在本任务结束之前**重新读取该差值，也就是在任何 `scroll` 监听可能运行之前：单一滚动容器下为 0，镜像方案下则是整个增量。空洞性保护先断言草稿确实超过了带上限的盒子；其余用例分别覆盖高度上限、三层同一折行宽度、滚轮手势、以换行结尾的草稿，以及过去由 textarea 自身滚动承担的光标回视路径——滚离光标后输入，必须把滚动容器带回光标处。
 
 另有一个用例端到端覆盖粘贴路径：短草稿、光标停在末尾，然后派发一个携带真实剪贴板数据的 `paste` 事件——与 Cmd-V 送达的是同一个事件，走同一个处理器——再检查偏移与所粘内容的最后一行。它等待的是偏移而不是「草稿是否溢出」，因为恢复发生在状态机提交草稿之后的下一帧；没有这次回视的构建会卡在这个等待上失败。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
index 7d68e52c82..a972cf44ae 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-english-compaction-checkpoints.md
 2026-07-31-english-compaction-checkpoints.md: dc95ed187a6ba5b86800f06ebefb2776995f9421
-2026-07-31-english-compaction-checkpoints.zh.md: 7cd4179430ed775f3807af5a02e81838e495c81e
+2026-07-31-english-compaction-checkpoints.zh.md: 5b89dca449309abaefe3143f66a2878e2d9eea47
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
index 7cd4179430..5b89dca449 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
@@ -12,14 +12,14 @@ Status: implemented
 
 `COMPACTION_INSTRUCTION` 要求生成英语的内部工程检查点。它要求模型在必要时翻译叙述性源材料，同时保留精确的字面量；这包括路径、命令、错误、标识符、签名，以及精确性重要时的引用措辞。检查点的标题及简洁的工程项目符号仍沿用既有的结构化格式。
 
-这项要求被整合到尾部压缩指令的第一句话中。回放的系统提示词、工具和对话历史与已路由请求保持字节级一致，因此该变更保留 [compaction summary prefix-cache note](2026-07-21-compaction-summary-prefix-cache-reuse.md) 所确立的前缀缓存复用。
+这项要求被整合到尾部压缩指令的第一句话中。回放的系统提示词、工具和对话历史与已路由请求保持字节级一致，因此该变更保留 [压缩摘要前缀缓存说明](2026-07-21-compaction-summary-prefix-cache-reuse.md) 所确立的前缀缓存复用。
 
 ## 考虑过的替代方案
 
 - **让回放的对话决定检查点语言**——不采纳：检查点是持久的提示词前缀，保留短暂的对话文体可能在后续压缩中放大这种影响。
 - **约束对话模型的语言**——不采纳：该策略针对内部检查点，而不是用户可见的对话；对整个对话施加规则会不必要地改变正常交互。
 - **要求仅输出 ASCII**——不采纳：ASCII 是字符集约束，而非工程文体约束，并会不必要地扭曲合法的字面量和技术材料。
-- **在末尾追加一句独立的仅限英语要求**——不采纳：在指令开头的输出契约中说明该要求更简洁，也直接将其与所请求的检查点绑定。
+- **在末尾追加一句独立的仅限英语要求**——不采纳：在指令开头的输出约定中说明该要求更简洁，也直接将其与所请求的检查点绑定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
index fda3830670..6bf16a8981 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-fail-loud-releases-the-terminal.md
 2026-07-31-fail-loud-releases-the-terminal.md: 5fe812e5fe64a1fab8ba9808d87f3581b6f5b206
-2026-07-31-fail-loud-releases-the-terminal.zh.md: 64459614dc3376a1c773de72cd36aa455894a03c
+2026-07-31-fail-loud-releases-the-terminal.zh.md: d5fdf72013259a60df64e8f79e64169770f3435c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
index 64459614dc..d5fdf72013 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
@@ -1,10 +1,10 @@
-# Agent Note：fail-loud 在退出前释放终端
+# Agent Note: fail-loud 在退出前释放终端
 
 Status: implemented
 
 [English](2026-07-31-fail-loud-releases-the-terminal.md) | 中文
 
-## Problem
+## 问题
 
 配置校验失败的 `dsh` 启动会打印诊断信息，然后把用户丢回一个损坏的 shell：输入不可见，下一条命令还会被残留文本弄乱：
 
@@ -21,20 +21,20 @@ Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动
 
 `/exit` 路径从不受影响，因为它会释放整棵树，从而进入 TUI 自身的 `shutdown()`：先 `drainInput()`（吸收尚未返回的响应），再 `ui.stop()`。缺陷在于**启动失败**没有通往这同一套拆卸流程的路径。
 
-## Decision
+## 决策
 
 `installFailLoud` 新增可选的 `release` 拆卸回调，在诊断信息与退出之间被等待：
 
 - 诊断信息在 release **之前**写出，因此卡住或失败的 disposer 无法吞掉失败原因。
 - 使用闩锁（latch）而非卸载监听器，来保证被报告的始终是第一个 rejection。若在拆卸期间移除监听器，第二个并发 rejection 就会变成未捕获错误，Node 会在拆卸中途杀死进程——恰好残留下本次要恢复的终端状态。后续 rejection（包括 release 自身的）都会落入已挂起的退出流程。
 - release 以 `FAIL_LOUD_RELEASE_TIMEOUT_MS`（2 秒）为上限，且其 rejection 被吞掉。卡住或失败的 disposer 只会延迟致命退出，绝不会取消它。该定时器保持 **referenced**：一旦 `unref()`，Node 就会在事件循环清空后、恰恰在报告这次失败时以 0 退出，因为 `unhandledRejection` 监听器抑制了默认的致命退出。
-- 不传 `release` 时行为与此前完全一致，因此 ACP、JSON-RPC 和各 demo bin 均无变化。
+- 不传 `release` 时行为与此前完全一致，因此 ACP（Agent Client Protocol）、JSON-RPC 和各 demo bin 均无变化。
 
 `dsh` 的 TUI 启动器传入的 release 会释放根上下文，从而执行 TUI 已有的 `shutdown()` 并把终端交还。
 
 启动器在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值。rejection 到达时 `boot()` 尚未结算，因此在 `await` 之后赋值的 `app.current` 恰好在回调需要它的那一刻仍是 `undefined`。`prepare` 在 Loader 安装之后、任何配置树条目挂载之前运行，覆盖了条目可能 rejection 的整个窗口。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **在 fail-loud 处理函数里直接重置终端**（写 `ESC [ ? 2004 l`、弹出键盘协议、清除 raw 模式）。这会在一个并不拥有终端的包里重复 pi-tui 的拆卸逻辑，并随 pi-tui 启动序列的变化而漂移。它同样无法吸收尚未返回的 Device Attributes 响应——而这正是弄乱下一个提示符的原因，只有在 stdin 仍处于 raw 模式时排空它才能解决。
 
@@ -44,16 +44,16 @@ Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动
 
 **调整配置顺序，让 `llm-pi-ai` 先于 `ui-tui` 挂载。** 顺序并不是 Loader 提供的保证，而且未来任何条目都可能在 TUI 挂载之后失败。
 
-## Consequences
+## 后果
 
 启动失败现在会在退出前多付出一次树释放的代价（上限 2 秒），退出码仍为 1。作为交换，配置错误的 `dsh` 会交还一个可用的 shell，而不是需要 `stty sane` 或 `reset` 才能恢复的终端。
 
 这项保证属于**拥有终端的那个 bin**：任何抢占终端状态却不传 `release` 的界面都会重新引入该缺陷。`installFailLoud` 自身无法察觉这一点，因为它看不到已挂载的插件对进程做了什么。
 
-## Testing
+## 测试
 
-`packages/boot/app-boot/tests/app-boot.spec.ts` 覆盖 release 契约：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
+`packages/boot/app-boot/tests/app-boot.spec.ts` 覆盖 release 约定：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
 
-这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态被残留的 [HMR 初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
+这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态未被恢复的 [HMR（热模块替换）初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
 
 测试规范要求：只要改动终端拆卸，就必须有 PTY 用例——这就是它。`/exit` 路径保留其原有断言，确认正常退出时同样会出现该重置序列。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
index c4a5595fea..e2f3b7945f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-fork-anchor-floors-to-event-seq.md
 2026-07-31-fork-anchor-floors-to-event-seq.md: 2cc8d66942442aca69c930be880cc41d56bced13
-2026-07-31-fork-anchor-floors-to-event-seq.zh.md: 9f443f3d5165c01c6585d33bd6a37e90e9b3bf95
+2026-07-31-fork-anchor-floors-to-event-seq.zh.md: 10a8a994f544834d31ec7b3b4ad7d08b4b7d731d
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
index 9f443f3d51..10a8a994f5 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
@@ -18,11 +18,11 @@ host 的切分规则从来不是障碍。被中止的轮次会记录一条 reaso
 
 向下取整落在锚点自身所在的轮次内，不会回退：每一轮都以 `turn/start` 开头，所以 `turnEnd.seq - 1` 不可能是上一轮的 `turn/end`。host 随后按「首个位于锚点或其之后的 `turn/end`」收口，命中的正是读者点击的那一轮，与消息级 fork 按钮在已完成轮次上一贯承诺的整轮语义一致。
 
-apiproxy 的 fork 用例固定了 host 这一侧的契约：落在被中止轮次内的取整锚点会切穿该轮，并把它种进子会话。
+apiproxy 的 fork 用例固定了 host 这一侧的约定：落在被中止轮次内的取整锚点会将该轮纳入切分结果，并以该轮初始化子会话。
 
 ## 备选方案
 
-**让 wire 接受分数 `atSeq`。** 否决：host 契约要的是事件 seq，而不是连续坐标上的某个位置；分数形式只是某一个客户端的渲染约定，一旦放行，`atSeq` 会成为所有携带 seq 的载荷中唯一容忍非整数的字段。
+**让 wire 接受分数 `atSeq`。** 否决：host 约定要的是事件 seq，而不是连续坐标上的某个位置；分数形式只是某一个客户端的渲染约定，一旦放行，`atSeq` 会成为所有携带 seq 的载荷中唯一容忍非整数的字段。
 
 **在已中断的消息上隐藏 fork 按钮。** 否决：从读者主动叫停的那一轮分叉，恰恰是最需要 fork 的场景之一，而 host 侧这个能力一直是好的。
 
@@ -30,6 +30,6 @@ apiproxy 的 fork 用例固定了 host 这一侧的契约：落在被中止轮
 
 ## 影响
 
-从已停止的轮次 fork 会得到一个种子切到该轮 `turn/end` 的子会话。被冻结的残缺文本是从 chunk 事件重建出来的，从未成为 `assistant/message`，因此它不会进入子会话的模型上下文——正如源会话恢复时它也不会进入一样，子会话拿到的上下文与源会话一致。
+从已停止的轮次 fork 会得到一个初始化内容截至该轮 `turn/end` 的子会话。被冻结的残缺文本是从分片事件重建出来的，从未成为 `assistant/message`，因此它不会进入子会话的模型 transcript（文本记录）——正如源会话恢复时它也不会进入一样，子会话拿到的上下文与源会话一致。
 
 fork 失败在 chat 入口仍然是静默的。这个 bug 能存活至今，正是因为该调用点丢弃了自己的 rejection；把 fork 错误呈现到 UI 上是另一件事。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
index c78049cc8d..7324984631 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-web-stop-preserves-queue.md
 2026-07-31-web-stop-preserves-queue.md: b8bba45009c126495a8b03ee36d6eb2cccac9a93
-2026-07-31-web-stop-preserves-queue.zh.md: 0e1fffae8819bea81b91fae10c76dbadc78474fe
+2026-07-31-web-stop-preserves-queue.zh.md: dce4f431f1f433afce69689cd5220e36a68b85e2
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
index 0e1fffae88..dce4f431f1 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
@@ -16,7 +16,7 @@ Web 停止按钮调用 `session.cancel`，后者映射到广义 `agent.cancel({
 
 AgentLoop 不会启动并发的替代轮次。它会关闭并 flush 被中断的轮次，达到取消的完全停稳，然后通过现有 FIFO 驱动器认领下一个可唤醒的 queued 入队项。该认领会发出 `agent/inbox/dequeue`，因此 Host 的权威 `session/queue` 快照会退役已认领行，并使剩余队尾保持可见。浏览器既不重发，也不提升任何行。忽略取消的工作会延迟这一交接，直到该工作结算。
 
-该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认契约仍为广义取消，ACP 和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。
+该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认约定仍为广义取消，ACP（Agent Client Protocol）和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。
 
 ## 考虑过的替代方案
 
@@ -30,7 +30,7 @@ AgentLoop 不会启动并发的替代轮次。它会关闭并 flush 被中断的
 
 ## 验证
 
-AgentLoop 覆盖会保持一个活动模型流，将两个可唤醒轮次排队，使用 `keepInbox` 取消，并固定验证先中止、后完成的轮次原因，FIFO 用户消息顺序，不存在 discard 事件，以及最终空闲状态。无密钥 Web 场景通过 HTTP／SSE 驱动已组装组合：它停止一个卡住的轮次，观察队尾保持可见时下一个 queued 入队项开始，再停止该轮次，并观察最后一个 queued 入队项完成。其可访问性快照固定了中间的 Queue 保留状态。
+AgentLoop 覆盖测试会保持一个活动模型流，将两个可唤醒轮次排队，使用 `keepInbox` 取消，并固定验证先中止、后完成的轮次原因，FIFO 用户消息顺序，不存在 discard 事件，以及最终空闲状态。无密钥 Web 场景通过 HTTP/SSE（Server-Sent Events）驱动已组装的组合：它停止一个卡住的轮次，观察队尾保持可见时下一个 queued 入队项开始，再停止该轮次，并观察最后一个 queued 入队项完成。其可访问性快照固定了中间的 Queue 保留状态。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
index 39bf79e628..746dd01ce0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
 2026-08-01-ask-user-delegated-caller-guard.md: 0350a7383f7ace6ecd742c98db18f8b977720cf9
-2026-08-01-ask-user-delegated-caller-guard.zh.md: 9c19722feb4586e07845fd20279574301267542d
+2026-08-01-ask-user-delegated-caller-guard.zh.md: 811a550bacc6f9019fdd08c7b555bc11753a9477
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
index 9c19722feb..811a550bac 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 以运行时所有权为权限依据。携带谱系的会话在无所有者的情况下恢复时就是运行时根，可以提问；存活子级即使持久化 `delegationDepth` 为零，仍无资格提问。不带 agent 的程序化调用继续沿用现有提供方路径。
 
-共享失败文本与具体消费方无关，并给出可执行指引：子级把尚未解决的问题或决策写入最终结果。委托契约本就会把该结果传给父级，父级可据此决定是否询问人类。服务和子级都不会宣称存在实际上并不存在的向上消息传递或回答转发能力。
+共享失败文本与具体消费方无关，并给出可执行指引：子级把尚未解决的问题或决策写入最终结果。委托约定本就会把该结果传给父级，父级可据此决定是否询问人类。服务和子级都不会宣称存在实际上并不存在的向上消息传递或回答转发能力。
 
 该安全边界与浏览器的 composer 选举相互独立。提议的[语义 composer 阶段](../../proposed/architecture/2026-08-08-semantic-composer-chain-phases.md)解决已有待处理交互与只读 subagent 界面的排序方式；它不会削弱此运行时守卫。
 
@@ -34,6 +34,6 @@ Status: implemented
 
 运行时中归属于其他 agent 的子级调用会以稳定的结构化错误快速失败，而不是挂起。注册表中的确切存活根和不带 agent 的程序化调用仍有资格提问，包括带有历史子级谱系的已恢复会话。`ask_user_question` 与 `exit_plan_mode` 会收到相同的中性纠正指引，而其模型可见 schema 和系统提示词前缀保持不变；只有追加的错误结果发生变化，因此现有 KV Cache 前缀仍可复用。
 
-## Testing
+## 测试
 
 服务测试覆盖持久化深度为零的存活子级、深度为一的已恢复运行时根、缺失注册表、仅 id 相同的陈旧对象，以及每次拒绝都不调用提供方。工具与 plan-mode 测试证明两个消费方都会呈现中性的 `DELEGATED_CALLER` 结果，且绝不触达提供方。无密钥组装快照委托一个尝试调用 `ask_user_question` 的子级，固定其错误工具结果和最终交接，并证明父级可以完成，而不是一直等待回答。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
index c8784f5991..8ee0551df5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.md
 2026-08-02-goal-round-wrapup-message.md: c6bc3d5912b0789efde55880c2be892e98e34a5b
-2026-08-02-goal-round-wrapup-message.zh.md: 0a504b4dcc61feb932775b3d9ffd8424f3b0597d
+2026-08-02-goal-round-wrapup-message.zh.md: 46876f09edfea631b9621caf417ecf4df4ccff2d
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
index 0a504b4dcc..46876f09ed 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：Goal Round 收尾消息
+# Agent Note: Goal Round 收尾消息
 
 Status: implemented
 
@@ -6,26 +6,26 @@ Status: implemented
 
 ## 问题
 
-自主 Goal Round 报告 `update_goal` `complete` 或 `blocked` 时，物理轮次在工具结果处直接终结，模型在调用之后再无发言机会。会话终止在一张裸的 `update_goal` 卡片上，内测同学的观感是 agent 话说到一半戛然而止：模型调用前的文本通常预告了一份汇报（“目标达成，标记完成：”）却永远没有下文，因为标准 tool-use 预期是工具结果之后还有一条 assistant 消息，而 Goal Round 提示词与工具描述都没有说明这次调用是终点。硬停止来自 [goal 工具决策](../feature/2026-07-19-model-facing-goal-tools.md)，本 note 取代其中的轮次停止条款。
+自主 Goal Round 报告 `update_goal` `complete` 或 `blocked` 时，物理轮次在工具结果处直接终结，模型在调用之后再无发言机会。会话终止在一张裸的 `update_goal` 卡片上，内测同学的观感是 agent（智能体）话说到一半戛然而止：模型调用前的文本通常预告了一份汇报（「目标达成，标记完成：」）却永远没有下文，因为标准 tool-use 预期是工具结果之后还有一条 assistant 消息，而 Goal Round 提示词与工具描述都没有说明这次调用是终点。硬停止来自 [goal 工具决策](../feature/2026-07-19-model-facing-goal-tools.md)，本 Agent Note 取代其中的轮次停止条款。
 
 ## 决策
 
-Goal Round 的 `complete` 或 `blocked` 成功不再调用 `concludeTurn()`。工具改为在自己的结果上附带一条收尾上下文：以 `{ kind: 'plugin', plugin: 'tool-goal' }` 为 source 的 user 消息，携带 `<goal_complete>`/`<goal_blocked>` 指令，要求模型向用户写出有依据的收尾消息且不再调用工具。之后轮次经由 agent loop 常规的无工具调用停止路径结束，因此不存在新的 loop 原语，steering 语义不受影响。人类直接变更保持原样、不注入指令。代价是每个 goal 生命周期一次额外模型请求，而非每轮一次。
+Goal Round 的 `complete` 或 `blocked` 成功不再调用 `concludeTurn()`。工具改为在自己的结果上附带一条收尾上下文：以 `{ kind: 'plugin', plugin: 'tool-goal' }` 为 source 的 user 消息，携带 `<goal_complete>`/`<goal_blocked>` 指令，要求模型向用户写出有依据的收尾消息且不再调用工具。之后轮次经由 agent loop（智能体循环）常规的无工具调用停止路径结束，因此不存在新的 loop 原语，steering（中途引导）语义不受影响。人类直接变更保持原样、不注入指令。代价是每个 goal 生命周期一次额外模型请求，而非每个 Round 一次。
 
-指令措辞通过在 `deepseek-v4-pro` 上用重构的 Goal Round 转录做 A/B 采样选定：结构化指令（结果、验证、产物、后续）在完整度上稳定优于极简“总结一下”；补充“以会话内证据为准”的 grounding 条款让无依据细节从断言事实退为带保留的建议；而无指令对照组的收尾方差很大，包括言之凿凿的文件级细节编造。
+指令措辞通过在 `deepseek-v4-pro` 上用重构的 Goal Round transcript（文本记录）做 A/B 采样选定：结构化指令（结果、验证、产物、后续）在完整度上稳定优于极简「总结一下」；补充「以会话内证据为准」的 grounding 条款让无依据细节从断言事实退为带保留的建议；而无指令对照组的收尾方差很大，包括言之凿凿的文件级细节编造。
 
-为让 keyless 证明可脚本化，快照设施补了一项能力：`dsh-llm-replay` 会针对实时请求解析脚本条目中的 `{{fromRequest:<regex>}}` 占位符，因为静态伴随文件不可能预知模型必须回填进 `update_goal` 的随机生成 goal id。
+为让 keyless 证明可脚本化，快照 harness 补了一项能力：`dsh-llm-replay` 会针对实时请求解析脚本条目中的 `{{fromRequest:<regex>}}` 占位符，因为静态伴随文件不可能预知模型必须回填进 `update_goal` 的随机生成 goal id。
 
 ## 验证
 
-`tool-goal` 包测试钉住两个终态 action 注入的上下文（source、标签、objective、禁止再调工具条款）与不存在的 `concludesTurn`，以及人类直接 pause 与 complete 的不注入路径，文件覆盖率 100%。`llm-replay` 单元测试钉住占位符契约：最后一次匹配取胜的捕获、无捕获组时整体匹配回退，以及未匹配、非法、未闭合模式的明确报错。新增 keyless ACP 快照 `goal-wrapup` 驱动成品应用走完 create → 第一轮 → 自主 complete，并在持久会话日志与 ACP stdout 流中同时断言 plugin 来源的收尾注入、同轮内的收尾 assistant 消息与 `completed` 轮次结束。
+`tool-goal` 包测试钉住两个终态 action 注入的上下文（source、标签、objective、禁止再调工具条款）与不存在的 `concludesTurn`，以及人类直接 pause 与 complete 的不注入路径，文件覆盖率 100%。`llm-replay` 单元测试钉住占位符约定：最后一次匹配取胜的捕获、无捕获组时整体匹配回退，以及未匹配、非法、未闭合模式的明确报错。新增 keyless ACP 快照 `goal-wrapup` 驱动成品应用走完 create → 第一个 Round → 自主 complete，并在持久会话日志与 ACP stdout 流中同时断言 plugin 来源的收尾注入、同一轮次内的收尾 assistant 消息与 `completed` 轮次结束。
 
 ## 曾考虑的替代方案
 
 - **在 `update_goal` 的 UI 卡片上展示完成文本** — 拒绝：`complete` 如今不携带任何自由文本；新增 `summary` 参数会让面向用户的汇报走工具参数通道，而且依然砍掉了模型在结果之后的自然发言。
-- **保留 `concludeTurn()` 并新增“再多一步纯文本”的 loop 原语** — 拒绝：为常规停止路径已经能提供的行为（只要没有结果终结轮次）增加新的 `agent-loop` 机制。
-- **把指令写进工具结果内容** — 拒绝：goal 工具的规范输出是被程序化消费的紧凑 JSON；在其中混入散文指令会把模型侧契约和工具的可回放值搅在一起。
+- **保留 `concludeTurn()` 并新增「再多一步纯文本」的 loop 原语** — 拒绝：为常规停止路径已经能提供的行为（只要没有结果终结轮次）增加新的 `agent-loop` 机制。
+- **把指令写进工具结果内容** — 拒绝：goal 工具的规范输出是被程序化消费的紧凑 JSON；在其中混入散文指令会把模型侧约定和工具的可回放值搅在一起。
 
-## Consequences
+## 后果
 
-每个自主 goal 都以一条面向用户的收尾消息结束，而非一张裸工具卡片，代价是每个 goal 生命周期一次模型请求。`concludeTurn()` 保留其 loop 语义，但在 subagent 结构化输出之外失去了唯一的一方调用者。快照场景现在可以通过 `{{fromRequest:...}}` 脚本化只在运行时才存在的值，为任何“回显 id”类工具流程（不限于 goal）解锁 keyless 覆盖。
+每个自主 goal 都以一条面向用户的收尾消息结束，而非一张裸工具卡片，代价是每个 goal 生命周期一次模型请求。`concludeTurn()` 保留其 loop 语义，但在 subagent 结构化输出之外失去了唯一的第一方调用者。快照场景现在可以通过 `{{fromRequest:...}}` 脚本化只在运行时才存在的值，为任何「回显 id」类工具流程（不限于 goal）解锁 keyless 覆盖。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.i18n.yaml
index 7f4b8c7824..f6e85d05e1 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md
 2026-08-02-message-fork-actions-require-completed-turn-tail.md: abdcbc79948c67619bb70a8a87741046f65b8838
-2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md: a93b572c6db3c76ce3869747fd9a7660bf3ea395
+2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md: 7df9b04e982e9d290030cb9be6c27bb68541aaeb
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md b/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md
index a93b572c6d..7df9b04e98 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.zh.md
@@ -12,7 +12,7 @@ Web 会话把分支操作挂到每个轮次中最后一个文本非空的 assist
 
 `ConversationSnapshot.turnEnds` 保留原始事件窗口中的已完成轮次边界。会话视图按各边界遍历 transcript（文本记录）节点，仅当边界的最后一个节点是用户消息、持久 steering（中途引导）消息或含内容的 assistant 消息时才启用分支操作。开放轮次没有符合条件的消息；如果后面还有工具结果、只有推理内容的中断、轮次错误或其他 transcript 节点，较早消息上的分支操作会保持不可用。不可用的控件仍然可见、可聚焦、可悬停；`aria-disabled`、tooltip 与 `aria-describedby` 会说明已完成尾部这一要求，且不会发送 Host 请求。复制和时钟仍可在既有消息 chrome 下使用，Host 按已完成轮次 fork 的语义保持不变。
 
-本资格判定中消息气泡的那一半已被 [user 气泡分支移除决策](../simplification/2026-08-06-user-bubbles-drop-the-branch-action.md)取代：user 与 steering 气泡不再渲染该控件，因此只有内容 assistant 尾部可以 fork；assistant 侧门禁及其可见但不可用的呈现保持有效。
+本资格判定中消息气泡的那一半已被 [user 气泡分支移除决策](../simplification/2026-08-06-user-bubbles-drop-the-branch-action.md)取代：user 与 steering 气泡不再渲染该控件，因此只有含内容的 assistant 尾部可以 fork；assistant 侧门禁及其可见但不可用的呈现保持有效。
 
 本决策收紧了较早的 [Web 会话 fork 操作决策](../feature/2026-07-27-web-session-fork-actions.md)所定义的消息资格。Session 行 fork 仍选择最新的已完成轮次；符合条件的消息操作仍通过共享 client 运行时操作传递其事件 seq。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
index eeac8a251c..c68279a2b4 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.md
 2026-08-02-todo-first-composer-context-order.md: 26962426c763c6911fc61acab09cdb96725922b1
-2026-08-02-todo-first-composer-context-order.zh.md: a81401ffeb8df5855b584a5727e24067d9fb1e70
+2026-08-02-todo-first-composer-context-order.zh.md: 2bd09a95832b22afc919a6f2d18bef94d4209c40
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
index a81401ffeb..2bd09a9583 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
@@ -14,7 +14,7 @@ composer 上下文堆栈将 Goal 渲染在 Todo 之前，但 Harness 设计稿
 
 Todo、Goal 与可见的 Queue 面板共用 800px composer 宽度上限内的 752px 卡片列。Queue 保留 776px 包装层，并在两侧各留 12px 透明内缩，因为该包装层负责与 composer 重叠。Todo 是独立卡片，而非包装层，因此其响应式宽度和最大宽度都会直接扣除两层内缩。Goal 使用相同的响应式卡片列，并将内层横条的宽度上限设为 752px，从而在低于桌面宽度上限时也保持边缘对齐。
 
-[composer 堆栈契约](2026-07-30-composer-context-stack-order.md)继续规定卡片间距，以及仅限 Queue 与 composer 重叠。本决策只取代该记录中 Goal 优先的顺序。
+[composer 堆栈约定](2026-07-30-composer-context-stack-order.md)继续规定卡片间距，以及仅限 Queue 与 composer 重叠。本决策只取代该记录中 Goal 优先的顺序。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
index 36c7895ac2..5c7deb9700 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
 2026-08-03-cli-signal-shutdown-escalation.md: c8aac6e2be927bd1f4a445c00e0aaa870b10a465
-2026-08-03-cli-signal-shutdown-escalation.zh.md: 66fe7062ea35a6cc91dbdd6644088cb086a15439
+2026-08-03-cli-signal-shutdown-escalation.zh.md: 14e2149eb5153b3743e188c6b233d000b36d60db
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
index 66fe7062ea..14e2149eb5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
@@ -1,6 +1,6 @@
-# Agent Note：Web 与 headless 的有界信号关闭和重复信号强制退出
+# Agent Note: Web 与 headless 的有界信号关闭和重复信号强制退出
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-03-cli-signal-shutdown-escalation.md) | 中文
 
@@ -39,7 +39,7 @@ headless 对完成的轮次仍以 0 退出，对其他轮次结束原因或 API
 
 ## 后果
 
-健康的退出流程仍会对整棵 Cordis 插件树执行 dispose。已知的遥测等待最多会在 3 秒后解除；其他退出流程卡死时，如无进一步输入，最多等待 5 秒，再次收到信号则立即结束进程。强制退出或受截止时间限制的退出可能中断遥测导出或尚未完成的清理工作；只有优雅关闭契约已经失败，或用户明确要求强制退出时，才会有意接受这一结果。
+健康的退出流程仍会对整棵 Cordis 插件树执行 dispose。已知的遥测等待最多会在 3 秒后解除；其他退出流程卡死时，如无进一步输入，最多等待 5 秒，再次收到信号则立即结束进程。强制退出或受截止时间限制的退出可能中断遥测导出或尚未完成的清理工作；只有优雅关闭约定已经失败，或用户明确要求强制退出时，才会有意接受这一结果。
 
 该控制器属于启动器基础设施，而不是 Cordis 插件：它不会声称 dispose 已经完成，也不会削弱普通 disposer 必须达到完全停稳状态的生命周期规则。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
index 51fbed7ba9..fad349792a 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
 2026-08-03-hmr-initial-scan-boot-deadlock.md: 1a70fbafc74a1bf7024c675ddad82acefc995b72
-2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: 5f8d50c4c0103eb2209eafb89cf34233c4c1bc35
+2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: c52c2c2f4e7375e4c783e43c58e6fe0e3eb6b44b
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
index 5f8d50c4c0..c52c2c2f4e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
@@ -1,6 +1,6 @@
-# Agent Note：HMR 初始扫描使失败的启动死锁为静默的 exit 13
+# Agent Note: HMR（热模块替换）初始扫描使失败的启动陷入死锁，最终静默地以 13 退出
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-03-hmr-initial-scan-boot-deadlock.md) | 中文
 
@@ -11,16 +11,16 @@
 两个缺陷叠加：
 
 1. **并发的 Include apply 破坏事务化的 group update。** HMR 主 watcher 的 chokidar 初始扫描会把每个已存在的文件重新宣告为 `add`。其中配置文件的 `add` 在 Include 的首次 apply 尚未结束时触发了 `Include.refresh()`（内容去重键 `this.content` 只在 apply 完成后才提交）。同一 group 上两个并发的 `EntryGroup.update` 会在相同条目上交错执行 create 与回滚，导致 Include fiber 永远无法结算：`loader.create` 挂起，`boot()` 既不 resolve 也不 reject，事件循环排空后 Node 以 13 退出。
-2. **仅序列化 apply 会让失败回滚死锁。** 将 Include 的变更排入队列后，首次 apply 失败时的回滚会释放每个已挂载条目——包括 `hmr`，而它的拆卸会等待自身的 refresh 任务排空。扫描触发的 refresh 任务正排在 Include 队列中、位于正在回滚的那次 apply 之后：回滚等 HMR，HMR 等 refresh，refresh 等 apply。
+2. **仅序列化 apply 会让失败回滚死锁。** 将 Include 的变更排入队列后，首次 apply 失败时的回滚会对每个已挂载条目执行 dispose（资源释放）——包括 `hmr`，而它的拆卸会等待自身的 refresh 任务排空。扫描触发的 refresh 任务正排在 Include 队列中、位于正在回滚的那次 apply 之后：回滚等 HMR，HMR 等 refresh，refresh 等 apply。
 
-## 决定
+## 决策
 
 两处修复都落在 vendored 包中（记录于 `vendor/README.md`）：
 
-- `include/src/index.ts` 将每次子树变更——首次 apply、refresh、`internal/update` 补丁重应用——汇入每个 Include 一条的 promise 队列。group 的事务化 `update` 不可重入，因此序列化是正确性要求，而不是吞吐取舍。`refresh()` 也在队列内读取文件，使其内容变更判断与前一任务提交后的状态比较。
+- `include/src/index.ts` 将每次子树变更——首次 apply、refresh、`internal/update` 补丁重应用——汇入每个 Include 各自的一条 promise 队列。group 的事务化 `update` 不可重入，因此序列化是正确性要求，而不是吞吐取舍。`refresh()` 也在队列内读取文件，使其内容变更判断与前一任务提交后的状态比较。
 - `hmr/src/index.ts` 给主 watcher 传入 `ignoreInitial: true`。初始扫描只会重新宣告启动刚刚消费过的文件；抑制它同时消除了启动期 refresh 和对已加载模块的多余 `add` 事件。`registerConfig()` 保留自己 `ignoreInitial: false` 的 watcher，因为注册时已存在的个人配置必须恰好应用一次。
 
-两者齐备后，失败的启动走上预期路径：唯一一次 apply 失败，回滚释放整棵树（执行 TUI 自身的 shutdown、恢复终端），`loader.create` reject，`boot()` 重新抛出带标签的诊断并以 1 退出。
+两者齐备后，失败的启动走上预期路径：唯一一次 apply 失败，回滚对整棵树执行 dispose（执行 TUI 自身的 shutdown、恢复终端），`loader.create` reject，`boot()` 重新抛出带标签的诊断并以 1 退出。
 
 ## 曾考虑的替代方案
 
@@ -28,14 +28,14 @@
 
 **只做序列化。** 把破坏转化为上述回滚死锁；进程仍然静默地以 13 退出。
 
-**在 HMR 拆卸时取消排队中的 refresh。** 需要在 `refreshConfig` 的任务循环和 Include 队列中铺设取消机制，而 `ignoreInitial` 已把该场景从每次启动中移除；在真实触发条件出现之前不值得引入这套机构。
+**在 HMR 拆卸时取消排队中的 refresh。** 需要在 `refreshConfig` 的任务循环和 Include 队列中铺设取消机制，而 `ignoreInitial` 已把该场景从每次启动中移除；在真实触发条件出现之前不值得引入这套机制。
 
 ## 后果
 
 落在 watcher 启动扫描窗口内的配置文件编辑，现在由下一个 `change` 事件而非扫描本身拾取；稳态的重载行为不变。
 
-仍留有一个潜在缺口：在一次*失败的*首次 apply 期间进行的配置编辑，仍可能排入一个被回滚的 HMR 拆卸所等待的 refresh——同样的死锁形态，但触发窗口缩小到一次失败启动的人力尺度。若它真的发生，修复方向是在 HMR 拆卸时取消 refresh 任务。
+仍留有一个潜在缺口：在一次*失败的*首次 apply 期间进行的配置编辑，仍可能排入一个被回滚的 HMR 拆卸所等待的 refresh——同样的死锁形态，但触发窗口达到一次失败启动这样的人可操作时间尺度。若它真的发生，修复方向是在 HMR 拆卸时取消 refresh 任务。
 
 ## 测试
 
-`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端契约：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/boot/app-boot/tests/config-reload.spec.ts` 与 `packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖。
+`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端约定：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已完成 dispose 的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/boot/app-boot/tests/config-reload.spec.ts` 与 `packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
index c4a8fd6268..64ec136c6d 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md
 2026-08-04-composer-tab-gutter-reservation.md: 3b28c35c1f11676e41cabde76d1b0d16c688f034
-2026-08-04-composer-tab-gutter-reservation.zh.md: 26e8b6bff73a01e6518f3918d201330c1d029876
+2026-08-04-composer-tab-gutter-reservation.zh.md: 8c435d85a2a068684ac4781296963f822df43484
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
index 26e8b6bff7..8c435d85a2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
@@ -10,15 +10,15 @@ composer 座位在组件树中只有一个节点、一个位置，但它究竟
 
 在 Chat 中它是会话列滚动容器（`[data-conversation-scroll]`）的 sticky **子元素**，因而依附于该容器的 content box——而占布局宽度的滚动条会把这个盒子收窄一条滚动条的宽度。声明了 `data-conversation-composer-overlay` 的视图（Trajectory 即是其一）会把会话列的滚动搬进视图自身：以该属性为条件的那条分支把滚动容器留作 `overflow: hidden`，并把座位改为绝对定位——对齐的是 padding box，而滚动条从不收窄这个盒子。
 
-于是只要对话记录超出一屏——任何带历史的会话的常态——两个标签页就恰好相差一条滚动条的宽度。输入卡片是居中的，因此在 8px 的滚动条下切换标签页会让它横向移动 4px，而右侧留白整整变化 8px。同一位移也出现在 Chat 内部：对话增长到开始滚动的那一刻，以及从 hero 态进入第一个可滚动轮次时。
+于是只要transcript（文本记录）超出一屏——任何带历史的会话的常态——两个标签页就恰好相差一条滚动条的宽度。输入卡片是居中的，因此在 8px 的滚动条下切换标签页会让它横向移动 4px，而右侧留白整整变化 8px。同一位移也出现在 Chat 内部：transcript 增长到开始滚动的那一刻，以及从 hero 态进入第一个可滚动轮次时。
 
 ## 决策
 
 `.scrollBody` 无条件声明 `scrollbar-gutter: stable`，overlay 分支则把同一个盒子在两个轴向上都声明为滚动容器——`overflow-x: hidden; overflow-y: auto`——而不再是 `overflow: hidden`。
 
-这两半是同一处改动。预留使两种状态依附于同一个宽度；把 overlay 分支声明为滚动容器，才使这条预留真正抵达它。选 `stable` 而非 `auto`，是因为 `auto` 只在盒子确实溢出时才预留，而"溢出与否"恰恰就是两个标签页之间的那点差别——`auto` 的写法只是把缺陷重述一遍，并不能修掉它。
+这两半是同一处改动。预留使两种状态依附于同一个宽度；把 overlay 分支声明为滚动容器，才使这条预留真正抵达它。选 `stable` 而非 `auto`，是因为 `auto` 只在盒子确实溢出时才预留，而「溢出与否」恰恰就是两个标签页之间的那点差别——`auto` 的写法只是把缺陷重述一遍，并不能修掉它。
 
-overlay 状态是一个没有任何东西会去滚动它的滚动容器：视图把它填满（`flex: 1 1 0`，且自带裁剪），座位不在常规流中，因此没有任何手势与裁剪行为发生变化。变化的是引擎会认哪些声明。WebKit 对 `overflow-y: auto` 的盒子应用 `scrollbar-gutter`，对 hidden 的盒子则忽略它——这是在本应用 composer 自身的图层上实测所得，并记录于 [composer 滚动容器记录](2026-07-31-composer-text-layers-share-one-scrollport.md)——所以把预留留在一个 hidden 盒子上，会在 Chromium 上成立，在 Safari 上悄无声息地不成立。
+overlay 状态是一个没有任何东西会去滚动它的滚动容器：视图把它填满（`flex: 1 1 0`，且自带裁剪），座位不在常规流中，因此没有任何手势与裁剪行为发生变化。变化的是引擎会认哪些声明。WebKit 对 `overflow-y: auto` 的盒子应用 `scrollbar-gutter`，对 hidden 的盒子则忽略它——这是在本应用 composer 自身的图层上实测所得，并记录于 [composer 滚动视口记录](2026-07-31-composer-text-layers-share-one-scrollport.md)——所以把预留留在一个 hidden 盒子上，会在 Chromium 上成立，在 Safari 上悄无声息地不成立。
 
 横向轴是显式声明的，而不是交给推导：单轴滚动的盒子会把另一轴的 `visible` 计算为 `auto`，于是只要某个视图的内容第一次伸出列外，它就会长出自己的横向滚动条。
 
@@ -30,21 +30,21 @@ overlay 状态是一个没有任何东西会去滚动它的滚动容器：视图
 
 **保留 `overflow: hidden`，只加 `scrollbar-gutter: stable`。** 单行版本。它能在浏览器车道所用的引擎上修掉可见症状，却把症状原封不动留在 Safari 上，而且任何测试都不会失败——这正是改动的后一半所要防的失效模式。
 
-**让 Chat 的 composer 座位也移出滚动容器，使 overlay 的几何成为唯一的几何。** 这是从根上删掉差异，而不是调和它，代价是放弃一项刻意的性质：sticky 座位位于滚动流之内，因此在 composer 上滚轮会带动对话记录（[sticky composer](2026-07-29-sticky-composer-conversation-scroll.md)），其上方的渐隐遮罩也由座位自身的背景绘制。两者都是有主、有覆盖的既有行为；为了消除 8px 的不对称而重建它们，是更大的改动而非更小的。
+**让 Chat 的 composer 座位也移出滚动容器，使 overlay 的几何成为唯一的几何。** 这是从根上删掉差异，而不是调和它，代价是放弃一项刻意的性质：sticky 座位位于滚动流之内，因此在 composer 上滚轮会带动对话记录（[sticky composer](2026-07-29-sticky-composer-conversation-scroll.md)），其上方的渐隐遮罩也由座位自身的背景绘制。两者都是已有明确归属且各有测试覆盖的行为；为了消除 8px 的不对称而重建它们，是更大的改动而非更小的。
 
 **给会话列加上一条滚动条宽度的内边距，而不是预留滚动条槽。** 内边距无论是否存在滚动条都会生效，因此在每种状态下都无条件付出这份宽度，而且它把一个由引擎在布局期决定的值钉死在样式表里。否决理由与侧边栏列表当初否决它时相同。
 
 ## 后果
 
-- Chat 的内容列永久变窄 8px——hero 态与对话记录尚短、根本不绘制滚动条时同样如此。这就是这笔交易：以最宽的列换取卡片在任何内容高度下都只有一个位置。
-- 一条声明覆盖三种切换，因为这三者本就是同一个差异：Chat ↔ Trajectory、Chat 内部的短对话 ↔ 可滚动对话，以及 hero ↔ 第一个可滚动轮次。
+- Chat 的内容列永久变窄 8px——hero 态与transcript 尚短、根本不绘制滚动条时同样如此。这就是这笔交易：以最宽的列换取卡片在任何内容高度下都只有一个位置。
+- 一条声明覆盖三种切换，因为这三者本就是同一个差异：Chat ↔ Trajectory、Chat 内部 transcript 较短 ↔ transcript 可滚动，以及 hero ↔ 第一个可滚动轮次。
 - overlay 状态现在是一个滚动容器。今天其中没有任何内容会溢出；将来若有视图允许自身内容超出会话列，这个盒子会滚动而不是裁剪，那个视图就需要像 Trajectory 视图那样自带裁剪。
-- 提交的 golden 记录了预留的带宽，因此样式表中 `::-webkit-scrollbar` 宽度的变化——决定这条预留有多宽的那个值——会在本场景中与在侧边栏场景中一样，以可评审的 diff 形式出现。
+- 提交的 golden 记录了预留条带，因此样式表中 `::-webkit-scrollbar` 宽度的变化——决定这条预留有多宽的那个值——会在本场景中与在侧边栏场景中一样，以可评审的 diff 形式出现。
 
 ## 测试
 
 `apps/web/tests/composer-tab-geometry.e2e.ts` 在两个标签页下测量输入卡片的矩形，分别取卡片处于宽度上限的视口与卡片随列收缩的视口，并断言这两个矩形是同一个矩形。只有真实引擎能报告这件事：jsdom 给每个元素的盒子尺寸都是零，也没有滚动条，因此单元测试只能断言那些声明存在，无法断言两种状态落在同一位置。出于同一原因，本次没有附带读取 CSS 文本的单元测试——它只会把声明复述一遍，并不会补上浏览器车道尚未确立的事实。
 
-该场景启动 chromium 时去掉了 Playwright 默认的 `--hide-scrollbars`，这一点是承重的：带上该参数时滚动条不占任何布局宽度，两个标签页在改动前后同样一致，文件中的每一处比较都会空洞地通过。实测：带上该参数时，改动前的层叠让两侧带宽都是 0；去掉它则是 8 与 0。
+该场景启动 chromium 时去掉了 Playwright 默认的 `--hide-scrollbars`，这一点是承重的：带上该参数时滚动条不占任何布局宽度，两个标签页在改动前后同样一致，文件中的每一处比较都会空洞地通过。实测：带上该参数时，改动前的层叠让两条预留带的宽度都是 0；去掉它则分别是 8 与 0。
 
-随后，改动前的层叠会被注入页面——滚动容器上 `scrollbar-gutter: auto`，overlay 分支上 `overflow: hidden`——并在其下测量同样的两个标签页，这正是把"卡片确实没动"与"标签页切换根本没到达布局"区分开的那一步。它把上报的症状复现为一个数字：每条边 4px，恰是 8px 带宽的一半。golden 把这份对照与修复后的状态并排记录，因此 fixture 承载的是这次改动所消除的那个差值，而不仅仅是它的缺席。
+随后，改动前的层叠会被注入页面——滚动容器上 `scrollbar-gutter: auto`，overlay 分支上 `overflow: hidden`——并在其下测量同样的两个标签页，这正是把「卡片确实没动」与「标签页切换根本没到达布局」区分开的那一步。它把上报的症状复现为一个数字：每条边 4px，恰是 8px 带宽的一半。golden 把这份对照与修复后的状态并排记录，因此 fixture（测试前置数据）承载的是这次改动所消除的那个差值，而不仅仅是它的缺席。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
index 754ca8bbd0..9f804b5ea9 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
 2026-08-04-conversation-column-one-axis-scroll.md: 9a487c506a75033d0854f08e95da24704309003d
-2026-08-04-conversation-column-one-axis-scroll.zh.md: 23441a7c8655d1f19d3c0fe0f661f81f69b55dba
+2026-08-04-conversation-column-one-axis-scroll.zh.md: b86f86f55757dff4fddab4c4e2ac64fa7c19fe59
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
index 23441a7c86..b86f86f557 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
@@ -1,6 +1,6 @@
-# Agent Note：会话列只在一个轴上滚动
+# Agent Note: 会话列只在一个轴上滚动
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-04-conversation-column-one-axis-scroll.md) | 中文
 
@@ -10,7 +10,7 @@
 
 这处外溢是设计使然，保持不变。真正让它对用户可见的是它所处的滚动容器。`[data-conversation-scroll]` 只声明了 `overflow-y: auto`，另一个轴留在初始值 `visible`；而一个在某一轴上滚动的盒子，会把另一轴的 `visible` 计算为 `auto`。于是每一条比该椭圆窄的列都真的给出了一段横向滚动范围——在笔记本实际会产生的几档宽度上，实测为 24–95px。
 
-## 决定
+## 决策
 
 `.scrollBody` 声明 `overflow-x: hidden`。这条列明确声明自己是单轴滚动容器，而不是把第二个轴交给推导。
 
@@ -20,7 +20,7 @@
 
 **把椭圆缩到列内。** 否决。椭圆的宽度正是让它 `stdDeviation="50"` 的模糊随输入卡片缩放的依据（figma 313:14109）；约束宽度会使列越窄模糊越紧，等于为修一条滚动条而制造一处视觉回归。
 
-**给椭圆套一层裁剪盒。** 否决。这层盒子唯一的职责是抵消列本就会裁剪的溢出，而推导出的 `overflow-x: auto` 仍然留在原处，等着下一个外溢的元素——会话流里这样的候选者不少。
+**给椭圆套一层裁剪盒。** 否决。这层盒子唯一的职责是抵消列本就会裁剪的溢出，而推导出的 `overflow-x: auto` 仍然留在原处，等着下一个外溢的元素——transcript（文本记录）里这样的候选者不少。
 
 **依赖外框的 `.centerCol { overflow: hidden }`。** 它帮不上忙。那处裁剪在滚动容器之外，只能在列边界处遮住椭圆探出的部分，而里面的容器照样可以滚过去够到它。用户报告的那条滚动条属于内层容器。
 
@@ -28,9 +28,9 @@
 
 ## 测试
 
-[apps/web/tests/conversation-column-overflow.e2e.ts](../../../../apps/web/tests/conversation-column-overflow.e2e.ts) 扫过一组把椭圆宽度夹在中间的视口宽度，在每一档上向列横向滚轮并读取 `scrollLeft`。提交的 golden 逐档记录该关系；最宽的一档是椭圆根本不外溢的对照。
+[apps/web/tests/conversation-column-overflow.e2e.ts](../../../../apps/web/tests/conversation-column-overflow.e2e.ts) 扫过一组把椭圆宽度夹在中间的视口宽度，在每一档上于列上触发横向滚轮事件并读取 `scrollLeft`。提交的 golden 逐档记录该关系；最宽的一档是椭圆根本不外溢的对照。
 
-两道防线保证该场景不流于形式。空断言防线断言窄档上椭圆确实仍伸出列外，使这项主张不可能因为症状出于无关原因消失而通过。变异对照则在页面内把 `overflow-x: auto` 强制改回，证明同一手势在同一时序下能把列带到正向滚动边界。测试直接测量该边界，因为稳定的滚动条槽可能让部分外溢处于滚动原点的负向。没有这项对照，`scrollLeft` 读到 0 同样可以解释为滚轮根本没送达。
+两道防线保证该场景不流于形式。空断言防线断言窄档上椭圆确实仍伸出列外，使这项主张不可能因为症状出于无关原因消失而通过。变异对照则在页面内把 `overflow-x: auto` 强制改回，证明同一手势在同一时序下能把列带到正向滚动边界。测试直接测量该边界，因为稳定的滚动条槽可能让部分外溢处于滚动原点的负向。没有这项对照，`scrollLeft` 读到 0 同样可以解释为滚轮事件根本没送达。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
index 02ea7ca431..c4244fd963 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
 2026-08-04-load-pre-react-loop-sessions.md: b7dcad1ff7fe0aa8239ac03f52b50dfa55417515
-2026-08-04-load-pre-react-loop-sessions.zh.md: 14c6dcc7b4da016ebef424a66fae0b96fb469cd4
+2026-08-04-load-pre-react-loop-sessions.zh.md: 0bd4391fa09cf4c554e77fef03575f9f1788bc01
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
index 14c6dcc7b4..0bd4391fa0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
@@ -14,23 +14,23 @@ react-loop 简化在保持 `SESSION_FORMAT_VERSION` 为 0 的同时更改了持
 
 `PersistenceCoordinator` 会在后端解码后识别 react-loop 重构前的确切形状，并将其投影为当前读取视图。它移除已废弃的 `turn/start.trigger`，把 `steering/message` 转换为同一条带标识的 `user/message`，将旧版失败事实映射为当前结构化错误，把 `disposed` 折叠为带 `disposed` 原因的已中止轮次，并用仅供持久化导入使用的 `{ kind: 'legacy' }` 原因表示粗粒度中止记录，因为无法获得其调用方。
 
-协调器会把该投影应用于 `load`、`inspect`、接管、HMR 前缀比较和 `readFrom`。可寻址的 `readFrom` 通常只读取后缀；如果后缀包含需要更早替换标识的旧版事件，协调器会先加载并规范化完整前缀，再返回所请求的 seq 范围。
+协调器会把该投影应用于 `load`、`inspect`、接管、HMR（热模块替换）前缀比较和 `readFrom`。可寻址的 `readFrom` 通常只读取后缀；如果后缀包含需要更早替换标识的旧版事件，协调器会先加载并规范化完整前缀，再返回所请求的 seq 范围。
 
-导入器不会合成 inbox splice。恢复后的 react-loop 重构前 agent 从空的待处理列表开始，这与基线运行时无法持久化待处理 inbox 工作的行为一致。已存储产物仍然仅追加，后续事件使用当前格式。
+导入器不会合成 inbox splice。恢复后的 react-loop 重构前 agent（智能体）从空的待处理列表开始，这与基线运行时无法持久化待处理 inbox 工作的行为一致。已存储产物仍然仅追加，后续事件使用当前格式。
 
 ## 考虑过的替代方案
 
-**将同版本记录视为不受支持。** 这符合预发布阶段的默认立场，但会使 PR 基线产生的会话无法恢复，尽管已移除的 steering 内容和终止事实都有完整映射。
+**将同版本记录视为不受支持。** 这符合预发布阶段的默认立场，但会使 PR（Pull Request）基线产生的会话无法恢复，尽管已移除的 steering 内容和终止事实都有完整映射。
 
 **将旧 inbox 通知回放为持久 splice。** 这些通知不是会话事件，也无法提供可信的待处理状态快照。如果无法获知每一次领取和丢弃，就推断插入操作，会让已消费的工作再次执行。
 
 **将粗粒度中止记录归因于现有调用方。** 将其映射到 `user`、`parent` 或 `hook` 会虚构来源。专用的 `legacy` 原因既能保留停止分类，也不会产生虚假的审计事实。
 
-**重写已存储的 JSONL 和 SQLite 记录。** 重写会违反仅追加契约，并要求为读取兼容边界建立后端专用的原子迁移机制。
+**重写已存储的 JSONL 和 SQLite 记录。** 重写会违反仅追加约定，并要求为读取兼容边界建立后端专用的原子迁移机制。
 
 ## 后果
 
-以重构基线格式写入的会话可以通过当前 AgentLoop 恢复，并完整保留 steering 内容、轮次边界、错误事实和停止分类。共享协调器契约覆盖内存、JSONL 和 SQLite 的 `load`／`inspect`／`readFrom`，包括 SQLite 后缀回退；组装后的 JSONL agent 恢复用例会验证历史 transcript（文本记录）可见，同时两个新 inbox 列表都从空状态开始。
+以重构基线格式写入的会话可以通过当前 AgentLoop 恢复，并完整保留 steering 内容、轮次边界、错误事实和停止分类。共享协调器约定覆盖内存、JSONL 和 SQLite 的 `load`／`inspect`／`readFrom`，包括 SQLite 后缀回退；组装后的 JSONL agent 恢复用例会验证历史 transcript（文本记录）可见，同时两个新 inbox 列表都从空状态开始。
 
 此例外支持基线格式，不支持重构开发期间产生的中间格式。具体而言，它没有为更早的实验性 `agent/inbox/spliced` 载荷定义迁移。通过确切形状识别，当前格式外观相似但结构错误的记录仍会走拒绝路径，不会被猜测性地转换为有效记录。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
index dfaaea4ab7..21705c72ee 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
 2026-08-05-context-meter-blind-to-compaction.md: 8f4845c3c9bf52c5c3a2d39dee2ff25bda30c7bd
-2026-08-05-context-meter-blind-to-compaction.zh.md: 94ada0a9118db63876d5805ef5a8197d9c764102
+2026-08-05-context-meter-blind-to-compaction.zh.md: 7df587d61cc487497a3a95263e10e3aa6f65943b
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
index 94ada0a911..7df587d61c 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：上下文仪表看不见压缩
+# Agent Note: 上下文仪表看不见压缩
 
 Status: implemented
 
@@ -6,22 +6,22 @@ Status: implemented
 
 ## 问题
 
-composer 的[上下文仪表](../feature/2026-08-05-composer-context-meter-breakdown.md)的圆环、百分比与 `~已用 / 容量` 标题都取自 `contextPressure.pressureTokens`，即提供方报告的最新提示词规模。这个数字只在某个请求报告用量时才会移动，而压缩不报告用量：`compact-basic` 通过直连的 `ctx.llm.stream()` 调用生成摘要，只追加 `compact/start`、`compact/summary`、用作替换的 `user/message` 和 `compact/end`——没有 `assistant/message`，也没有用量分片。
+composer 的[上下文仪表](../feature/2026-08-05-composer-context-meter-breakdown.md)的圆环、百分比与 `~已用 / 容量` 标题都取自 `contextPressure.pressureTokens`，即提供方报告的最新提示词规模。这个数字只在某个请求报告用量时才会移动，而压缩（compaction）不报告用量：`compact-basic` 通过直连的 `ctx.llm.stream()` 调用生成摘要，只追加 `compact/start`、`compact/summary`、用作替换的 `user/message` 和 `compact/end`——没有 `assistant/message`，也没有用量分片。
 
-于是在唯一一个专门用来改变它的操作面前，这块仪表纹丝不动。通过真实 agent loop 驱动一次 `compactNow`：
+于是在唯一一个专门用来改变它的操作面前，这块仪表纹丝不动。通过真实的 agent loop（智能体循环）驱动一次 `compactNow`：
 
 ```
 BEFORE compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messages 4365]
 AFTER  compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messages  286]
 ```
 
-折叠表层得出的组成明细行下降了 93%。而圆环——那个主要的可操作元素，也正是用户压缩完立刻会去点开面板的理由——完全没动，而且要等到又跑完一整轮才会动。此时面板上的标题与明细行相差一个数量级以上，恰恰发生在读者最可能去把明细行加总的时刻。
+折叠表层得出的组成明细行下降了 93%。而圆环——那个主要的可操作元素，也正是用户压缩完立刻会去点开面板的理由——完全没动，而且要等到又跑完一整个轮次才会动。此时面板上的标题与明细行相差一个数量级以上，恰恰发生在读者最可能去把明细行加总的时刻。
 
 ## 决策
 
 `contextPressure` 发布第二个分子 `projectedTokens`：在提供方样本之上，加上自取样以来表层增减部分的启发式重新计价，下界钳制为零。该折叠通过共享的 `surface-fold.ts` 携带已计价的表层，并在用量样本落地时记下 `sampledSurfaceTokens`——记录时机在同一条事件加入表层**之前**，因此 `assistant/message` 锚定的正是它自己那次请求实际携带的表层。`stateVersion` 提升到 3。
 
-只有增量部分是估算的。锚点保持提供方精确值，从而把估算器对 CJK 文本与 JSON schema 的系统性低估挡在占用率数字之外，同时又让这个数字能在内容落地或某段区间被遮蔽的瞬间做出反应。`contextOccupancy` 读取 `projectedTokens`，并回退到裸样本，因此从不含该字段的检查点恢复出来的投影会退化为旧行为，而不是直接消失。
+只有增量部分是估算的。锚点保持提供方精确值，从而把估算器对 CJK 文本与 JSON Schema 的系统性低估挡在占用率数字之外，同时又让这个数字能在内容落地或某段区间被遮蔽的瞬间做出反应。`contextOccupancy` 读取 `projectedTokens`，并回退到裸样本，因此从不含该字段的检查点恢复出来的投影会退化为旧行为，而不是直接消失。
 
 这推翻了[上下文仪表决策](../feature/2026-08-05-composer-context-meter-breakdown.md)中「圆环、标题与进度条总长保持提供方精确值」的那一半。那条决策真正想守住的东西——不要把启发式明细行按比例缩放到提供方总量、从而伪造精度——依然守住了：明细行仍未被缩放，标题仍不等于它们之和。改变的是这样一个认识：「提供方精确、但描述的是两次压缩之前那个请求」并不是更真实的数字。
 
@@ -35,12 +35,12 @@ AFTER  compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messag
 
 ## 影响
 
-占用率现在随每个表层事件推进，而不再是每轮跳一次，因此一轮中产生工具结果时圆环会持续爬升，而不是等到轮次结束才跳变——压缩落地的瞬间它也会掉下来。代价是线路上多了投影帧：`contextPressure` 每个表层事件推一帧，也就是 `contextBreakdown` 本来就在跑的频率。
+占用率现在随每个表层事件推进，而不再是每个轮次跳一次，因此一个轮次中产生工具结果时圆环会持续爬升，而不是等到轮次结束才跳变——压缩落地的瞬间它也会掉下来。代价是线路上多了投影帧：`contextPressure` 每个表层事件推一帧，也就是 `contextBreakdown` 本来就在跑的频率。
 
 面板的组成明细行仍然加不出标题数字，但现在只剩一个能讲清楚的原因，而不是两个：明细行带着估算器的误差，标题的锚点不带。剩下的抓手是估算精度（在 `estimate.ts` 里做 CJK 感知加权），它不改动任何 seam。
 
-`sampledSurfaceTokens` 依赖一个前提：在某个步骤的请求与它的用量报告之间，不会有新内容加入表层。循环在 `buildRequest` 之前接纳 steering 与 context，在 `assistant/message` 之后才排空工具结果，因此该前提成立；即便将来不再成立，误差也被限制在一条消息以内，并在下一个样本处自行纠正。
+`sampledSurfaceTokens` 依赖一个前提：在某个步骤的请求与它的用量报告之间，不会有新内容加入表层。agent loop 在 `buildRequest` 之前接纳 steering（中途引导）与上下文，在 `assistant/message` 之后才排空工具结果，因此该前提成立；即便将来不再成立，误差也被限制在一条消息以内，并在下一个样本处自行纠正。
 
 ## 测试
 
-`packages/llm/token-meter/tests/token-usage-projection.spec.ts` 覆盖了样本在表层增长与一次压缩上的推进（样本保持不动而投影值缩小），以及启发式误差会把数字压到负数时的零钳制。`packages/client/ui-conversation/tests/context-meter.spec.tsx` 钉住圆环读取投影值这一点，`chat-stats.spec.tsx` 钉住 `contextOccupancy` 的优先级与回退。上面那组端到端数字来自在挂载了投影注册表的真实 `AgentLoop` 上驱动 `BasicCompactService.compactNow`。
+`packages/llm/token-meter/tests/token-usage-projection.spec.ts` 覆盖了投影值在表层增长与一次压缩期间的延续更新（样本保持不动而投影值缩小），以及启发式误差会把数字压到负数时的零钳制。`packages/client/ui-conversation/tests/context-meter.spec.tsx` 钉住圆环读取投影值这一点，`chat-stats.spec.tsx` 钉住 `contextOccupancy` 的优先级与回退。上面那组端到端数字来自在挂载了投影注册表的真实 `AgentLoop` 上驱动 `BasicCompactService.compactNow`。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml
index 0050d26e51..712163f307 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.md
 2026-08-05-turn-tail-actions-require-a-completed-turn.md: 44a890c955089096204a5b2a2833905c9ef9f7ed
-2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md: 58ca9b2519101cae12121cd74e13bdaa90ce23cb
+2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md: afd7fbe5a0cdd097c919fb3457dfed1771d5651b
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md
index 58ca9b2519..afd7fbe5a0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-turn-tail-actions-require-a-completed-turn.zh.md
@@ -14,7 +14,7 @@ assistant IconActions 此前只从已定稿的 transcript（文本记录）推
 
 `assistantActionsSeqs` 接收 `ConversationSnapshot.turnEnds`，只在事件窗口中存在该轮次 `turn/end` 时才授予该行。已完成轮次内部的归属不变，仍是其最后一条含内容文本的 assistant。仍在产出步骤的轮次不授予任何座位，因此其叙述不会挂载该行；轮次关闭时，座位在已定稿答案下方一次性出现。
 
-这与分支控件和运行时长标签使用的完成事实相同，因此同一行的三个部分现在口径一致。轮次是否完成读自持久的 `turn/end` 事件，而不是从 `running`、流式 partial 或在途工具调用推断，与[已完成轮次尾部决策](2026-08-02-message-fork-actions-require-completed-turn-tail.md)一致。任何 reason 类别都会关闭轮次，因此已中止轮次冻结的尾部保留其操作栏，而崩溃遗留的开放轮次会在加载时由日志修复补上 `turn/end`。
+这与分支控件和运行时长标签使用的完成事实相同，因此同一行的三个部分现在口径一致。轮次是否完成读自持久的 `turn/end` 事件，而不是从 `running`、流式 partial 或在途工具调用推断，与[已完成轮次尾部决策](2026-08-02-message-fork-actions-require-completed-turn-tail.md)一致。任何结束原因类别都会关闭轮次，因此已中止轮次冻结的尾部保留其操作栏，而崩溃遗留的开放轮次会在加载时由日志修复补上 `turn/end`。
 
 `hasContentText` 移入 `chat-flow.ts`，由 `AssistantMarkdown` 导入，使归属门控与挂载门控无法各自漂移。
 
@@ -24,8 +24,8 @@ assistant IconActions 此前只从已定稿的 transcript（文本记录）推
 
 **轮次进行中保留该行，只把控件置为不可用。** 不予采纳：轮次中间的叙述不是一个降级的答案，它根本不是答案。复制仍然会写入一句中间文本，该行在轮次结束时仍然要移动到真正的尾部。
 
-**让每个已定稿的内容节点长期保留该行。** 在此重新否决，理由与最初的决策相同：在每一步下重复复制、分支和时钟会打乱流程。它也解决不了本次报告的问题，因为分支控件只有落在尾部才有意义。
+**让每个已定稿的内容节点长期保留该行。** 在此重新否决，理由与最初的决策相同：在每一步下重复复制、分支和时钟会使流程显得杂乱。它也解决不了本次报告的问题，因为分支控件只有落在尾部才有意义。
 
 ## 后果
 
-运行中的轮次在触发它的用户气泡之下不再有任何消息操作栏，而此前每个已完成轮次仍保留各自的座位；座位在 `turn/end` 到达时一次性出现，此刻已定稿答案下方会多出一行 28px。`turn/end` 落在加载窗口之外的轮次不授予座位，而翻页不会造成这种情况，因为一个轮次的结束事件排在它自己的节点之后。`apps/web/tests/turn-tail-actions.e2e.ts` 通过组装后的应用钉住两种状态：`hang` sidecar 作用在第二次模型调用上，把一个首步先叙述再调用 bash 的轮次挂住，两份 golden 分别记录挂起中的流程和停止之后的流程。包级测试直接覆盖该推导以及运行中轮次的渲染结果。
+运行中的轮次在触发它的用户气泡之下不再有任何消息操作栏，而更早的每个已完成轮次仍保留各自的座位；座位在 `turn/end` 到达时一次性出现，此刻已定稿答案下方会多出一行 28px。`turn/end` 落在加载窗口之外的轮次不授予座位，而翻页不会造成这种情况，因为一个轮次的结束事件排在它自己的节点之后。`apps/web/tests/turn-tail-actions.e2e.ts` 通过组装后的应用钉住两种状态：`hang` sidecar 作用在第二次模型调用上，把一个首步先叙述再调用 bash 的轮次挂住，两份预期输出分别记录挂起中的流程和停止之后的流程。包级测试直接覆盖该推导以及运行中轮次的渲染结果。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.i18n.yaml
index 7737670466..e82314c28b 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.md
 2026-08-05-workspace-blank-session-reuse-membership.md: 910a10e9ada1a835df7a38a04fb04c504b0921df
-2026-08-05-workspace-blank-session-reuse-membership.zh.md: 7e7aa899f73955b3d34a1eff3d9fedde097a17f0
+2026-08-05-workspace-blank-session-reuse-membership.zh.md: 0581b768679d78716c1bf70cfffec825c7281783
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.zh.md
index 7e7aa899f7..0581b76867 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-workspace-blank-session-reuse-membership.zh.md
@@ -1,16 +1,16 @@
-# Agent Note：工作区新建会话复用了 cwd 匹配但未入账的空白会话
+# Agent Note: 工作区新建会话复用了 cwd 匹配但未入账的空白会话
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-05-workspace-blank-session-reuse-membership.md) | 中文
 
 ## 问题
 
-在侧边栏某个工作区分组的 `+` 上创建会话时，有时会进入一个新会话，但侧边栏把它显示在「未分组」而不是点击的那个工作区下——「进入了新会话，但工作区没有被选中」。故障只出现在注册在 CLI 运行目录（即 `defaults.cwd = process.cwd()`，实际场景里就是 harness 检出目录本身）上的工作区，并且一旦该目录下存在 CLI 创建的空白会话就会出现。
+在侧边栏某个工作区分组的 `+` 上创建会话时，有时会进入一个新会话，但侧边栏把它显示在「未分组」而不是点击的那个工作区下——「进入了新会话，但工作区没有被选中」。故障只出现在注册在 CLI（命令行界面）运行目录（即 `defaults.cwd = process.cwd()`，实际场景里就是 harness 检出目录本身）上的工作区，并且一旦该目录下存在 CLI 创建的空白会话就会出现。
 
-根因：`connectWorkspace` 的空白会话复用扫描只按 `cwd` 相等匹配会话列表镜像。host 自己的成员规则要求**同时**满足：会话 id 在工作区账户（`sessionIds`）中，**且**会话 header 的规范化 cwd 等于工作区路径（[Workspace UI product flow](../feature/2026-07-25-workspace-ui-product-flow.md)）；只有 cwd 匹配而没有账户槽位的恰恰就是「未分组」的情形。复用扫描忽略了账户槽位，因此任何 cwd 匹配的**在线空白**会话都会被选中——包括 CLI/TUI/headless 入口在 host cwd 创建的 `main-session-*` 会话（`session.create({})` 回退到 `defaults.cwd`，从不挂到任何工作区）。当这样的会话在线且空白（尚无 `turn/start`）时，下一次在该路径注册的工作区上点击 `+` 就会复用它，导航打开的是一个任何分组表面都无法显示在该工作区下的会话。其他路径的工作区不受影响，因为那里不会积累未入账的空白会话；而 host-cwd 工作区每次 CLI 运行都会积累一个。
+根因：`connectWorkspace` 的空白会话复用扫描只按 `cwd` 相等匹配会话列表镜像。host 自己的成员规则要求**同时**满足：会话 id 在工作区账户（`sessionIds`）中，**且**会话 header 的规范化 cwd 等于工作区路径（[Workspace UI product flow](../feature/2026-07-25-workspace-ui-product-flow.md)）；只有 cwd 匹配而没有账户槽位的恰恰就是「未分组」的情形。复用扫描忽略了账户槽位，因此任何 cwd 匹配的**在线空白**会话都会被选中——包括 CLI/TUI/headless 入口在 host cwd 创建的 `main-session-*` 会话（`session.create({})` 回退到 `defaults.cwd`，从不挂到任何工作区）。当这样的会话在线且空白（尚无 `turn/start`）时，下一次在该路径注册的工作区上点击 `+` 就会复用它，导航打开的是一个任何分组界面都无法显示在该工作区下的会话。其他路径的工作区不受影响，因为那里不会积累未入账的空白会话；而 host-cwd 工作区每次 CLI 运行都会积累一个。
 
-## 决定
+## 决策
 
 复用扫描现在要求工作区成员关系：`blank` 且 `summary.cwd === workspace.path` 且 `workspace.sessionIds.includes(summary.id)` 且未归档。仅 cwd 匹配的情况落到 `session.create({ workspaceId })`，创建并挂接新会话，使工作区拥有它——这与流程中「不存在空白会话」时的既有分支完全相同。
 
@@ -18,12 +18,12 @@
 
 **收养游离会话而不是新建。** 让 `session.create({ workspaceId })` 挂接一个 cwd 匹配但未入账的空白会话。否决：静默地把 CLI 创建的会话挂到工作区上，越过了账户边界，令人意外；而且客户端没有成员视图就无法区分「游离会话」与「工作区自己的空白会话」——而成员视图本身就是本次修复。
 
-**复用时就地挂接，新增一条 wire 操作。** 需要在导航热路径上新增 `workspace.attachSession` RPC，并且会话仍会有一帧显示在「未分组」；没有产品需求值得新增这个表面。
+**复用时就地挂接，新增一条 wire 操作。** 需要在导航热路径上新增 `workspace.attachSession` RPC，并且会话仍会有一帧显示在「未分组」；没有产品需求值得新增这个接口。
 
 ## 后果
 
-游离空白会话仍显示在「未分组」（用户仍可手动打开），但不再被某个工作区的新建会话流程劫持。成员校验是复用扫描的新增条件，有一个可观察的镜像滞后边界：在会话镜像已新而工作区账户帧滞后的窗口里，工作区自己的成员空白会话可能因成员校验失败而错过复用，多创建一个空白——表现为该工作区下出现第二个「新会话」行，与旧故障形态（打开一个任何分组表面都无法显示的会话）不同。两个窗口都是瞬态的，按工作区的合并逻辑仍然防止并发创建互相竞争。无 host、wire 或持久化格式变更。
+游离空白会话仍显示在「未分组」（用户仍可手动打开），但不再被某个工作区的新建会话流程劫持。成员校验是复用扫描的新增条件，有一个可观察的镜像滞后边界：在会话镜像已是最新而工作区账户帧滞后的窗口里，工作区自己的成员空白会话可能因成员校验失败而错过复用，多创建一个空白——表现为该工作区下出现第二个「新会话」行，与旧故障形态（打开一个任何分组界面都无法显示的会话）不同。两个窗口都是瞬态的，按工作区的合并逻辑仍然防止并发创建互相竞争。无 host、wire 或持久化格式变更。
 
 ## 测试
 
-`packages/client/runtime/tests/workspaces-service.spec.ts` 覆盖四种结果：成员空白会话被复用（无 create RPC）；cwd 匹配但非成员的游离空白会话**不被**复用、改为创建全新入账会话（回归用例）；已归档空白会话不被复用；首次 prompt 被拒后成员空白会话仍可复用。完整客户端套件（`pnpm run test:gui`）保持绿色。
+`packages/client/runtime/tests/workspaces-service.spec.ts` 覆盖四种结果：成员空白会话被复用（无 create RPC）；cwd 匹配但非成员的游离空白会话**不被**复用、改为创建全新入账会话（回归用例）；已归档空白会话不被复用；首次提示词被拒后成员空白会话仍可复用。完整客户端套件（`pnpm run test:gui`）保持绿色。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index f4f105e124..3a9d189fb5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
 2026-08-06-api-key-format-validation.md: 2174cb466c6af72f15005ce1ba3dec8100de6f2f
-2026-08-06-api-key-format-validation.zh.md: f9b7d6518fedc42e5264c46beaa1a78619139c58
+2026-08-06-api-key-format-validation.zh.md: 540239c34637eb5940be105127f3367e0969acfa
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index f9b7d6518f..540239c346 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -4,9 +4,9 @@ Status: implemented
 
 [English](2026-08-06-api-key-format-validation.md) | 中文
 
-## Problem
+## 问题
 
-一个含有 HTTP header value 无法承载的字符的 API Key，曾被每一层配置界面接受，直到构造请求时才失败——离引发它的那个字段已经很远。
+一个含有 HTTP header value 无法承载的字符的 API Key，曾被每个配置入口接受，直到构造请求时才失败——离引发它的那个字段已经很远。
 
 把含 emoji、中文或全角标点的 Key 粘进 Web 模型设置页，保存会报成功。第一轮对话随即失败于 `Cannot convert argument to a ByteString because the character at index 7 has a value of 55357 which is greater than 255`——其中的下标与码点是 UTF-16 内部细节，不附带任何可执行动作，却泄露了 Key 中某一个字符的码点。`llm-deepseek` 之所以产出这句，是因为 `fetch` 在 [adapter.ts](../../../../packages/llm/llm-deepseek/src/adapter.ts) 的 `try` 内部构造 `Bearer` header，而那个 `catch` 把一切失败都标为 `TRANSPORT`；该标签又在 `DEFAULT_RETRYABLE_CODES` 之中，于是一个永久且确定的故障还会被重试三次。
 
@@ -14,7 +14,7 @@ Status: implemented
 
 空白字符能通过每一道检查。`ProviderEditor` 判的是 `keyDraft.length`，于是三个空格构成的 Key 会被存下，随后以 `Bearer` 加若干空格去认证。两个适配器都不检查来自凭据或环境的 Key——而那正是 Models 页写入的路径，也就是用户真正走的路径。
 
-## Decision
+## 决策
 
 一条规则定义什么是合法 Key：**trim 之后非空，且每个字符都落在 `[\x21-\x7E]`**——可打印 ASCII，不含空格。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 ### 不变量属于每一层，启发式属于人所在的那一层
 
-字符集规则是不变量。非 ASCII 字符对任何 provider 都**不可能**在 header value 中传输，因此在浏览器、在各个 resolver、在每一次凭据读取上执行它，是结构上的一致而非约定上的一致。
+字符集规则是不变量。非 ASCII 字符对任何提供方都**不可能**在 header value 中传输，因此在浏览器、在各个 resolver、在每一次凭据读取上执行它，是结构上的一致而非约定上的一致。
 
 形状规则是对人如何粘贴的猜测，因此**只在浏览器中运行**。`llm-pi-ai` 前面挂着 OpenAI、Anthropic 以及任意手工声明的网关，本仓库并不掌握它们的 Key 格式；若这条规则运行在 resolver 中，一个签发形如 `TENANT1=abc` 的网关会让用户被彻底锁死、无路可走——设置页拒绝它，手写的 `.env` 在读取时同样被拒。把启发式限制在粘贴动作发生的那一层，环境变量便始终是那条出路。
 
@@ -32,7 +32,7 @@ Status: implemented
 
 规则作用于*已提供*的值；至于究竟有没有提供，由各个调用方自行判断。
 
-**未点名凭据。** 省略 `apiKeyEnv` 的 pi-ai profile 可以在 harness 持有的凭据路径之外鉴权。[provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) 中的 `routeAuth` 保留内置 catalog provider 自身的鉴权，正是为了让 provider 原生的 ambient 发现继续工作；而该 catalog 附带的 `openai-codex` 通过 OAuth 鉴权。`namesCredential` 承载这一区分；省略不是需要校验的值。
+**未点名凭据。** 省略 `apiKeyEnv` 的 pi-ai profile 可以在 harness 持有的凭据路径之外鉴权。[provider.ts](../../../../packages/llm/llm-pi-ai/src/provider.ts) 中的 `routeAuth` 保留内置 catalog 提供方自身的鉴权，正是为了让 provider 原生的 ambient 发现继续工作；而该 catalog 附带的 `openai-codex` 通过 OAuth 鉴权。`namesCredential` 承载这一区分；省略不是需要校验的值。
 
 **Web UI 中留空的输入框。** 即便某个 provider 的 Key 已经存好，该输入框也是空着打开的——`keyStored` 的文案写的是「已配置——输入新值以替换」——所以留空意味着*保持已存储的值*。`ProviderEditor` 在草稿为空时完全跳过 `credentials.set`，这一点保持不变：留空绝不拦截提交，否则改一个 base URL 都得重新输一遍 Key。
 
@@ -42,15 +42,15 @@ Status: implemented
 
 ### 规则住在哪里
 
-`normalizeApiKey` 是 `dsh-llm` seam 的一个模块，与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则，因此它拥有两个当前消费者而非一个预设消费者。它返回 trim 后的值，或一个原因（`empty`、`illegalCharacters`）。
+`normalizeApiKey` 是 `dsh-llm` seam 的一个模块，与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则，因此它拥有两个当前消费方而非一个预设消费方。它返回 trim 后的值，或一个原因（`empty`、`illegalCharacters`）。
 
 两个适配器同样都需要那句完全相同的「拒绝一个已存储凭据」的诊断，差别仅在包名前缀。`LlmError` 声明在 seam 的 `index.ts` 中，因此 `assertUsableApiKey(raw, pkg, ref)` 就住在它旁边，两个适配器都不再各留一份。断言模块本身保持零依赖：把 `LlmError` 引入 `api-key.ts` 会与 `index.ts` 对它的再导出成环。
 
 客户端无法引入其中任何一个：client 包只 reference client 包，因此 `packages/client/ui-models` 在自己的 `apiKey.ts` 中镜像这个断言并持有本地化文案，正如 `validateDeepSeekModels` 镜像 host 侧的 `catalogModel` schema。两侧在注释中互相指名。
 
-### 各个界面各做什么
+### 各处分别做什么
 
-| 界面 | 行为 |
+| 位置 | 行为 |
 |---|---|
 | `dsh-llm` | 拥有 `normalizeApiKey`、`assertUsableApiKey` 与 `INVALID_CREDENTIAL_CODE`，后者刻意不进 `DEFAULT_RETRYABLE_CODES`。 |
 | `llm-deepseek` `resolveApiKey` | 归一化凭据 seam 或环境返回的值，以 `INVALID_CREDENTIAL` 拒绝，消息指明模型设置页，绝不回显 Key。 |
@@ -58,11 +58,11 @@ Status: implemented
 | `llm-pi-ai` `discoverModels` | 在构造 header 之前归一化，使非法 Key 成为凭据故障而非端点不可达。不带 Key 的探测保持未鉴权。 |
 | `ui-models` | 镜像字符集规则，加入形状启发式，在探测与 `credentials.set` 之前 trim `keyDraft`，并修正 `stringAt` 的空值判断。留空的输入框仍是可以提交的空操作；只含空白的输入框则是字段级失败。提交**与端点探测**同时受拦截，因此被拒绝的密钥不会白花一次往返去换取字段上已经写明的答案；失败呈现在字段上，与既有的 `modelFailure` 模式一致。 |
 
-`ProviderEditor` 同时服务 DeepSeek 与 pi-ai 两种布局，因此一处客户端改动覆盖两个 provider。`CustomProviderCard` 为手工声明的路由承载同一套判定。
+`ProviderEditor` 同时服务 DeepSeek 与 pi-ai 两种布局，因此一处客户端改动覆盖两个提供方。`CustomProviderCard` 为手工声明的路由承载同一套判定。
 
 `credentials-local` 刻意不动。它存储各类凭据，而可打印 ASCII 是 HTTP header 的约束而非凭据存储的约束；它既有的、拒绝任何 dotenv 样式都无法表示的值的行为保持原样。
 
-## Alternatives considered
+## 曾考虑的替代方案
 
 **由 client 与 host 共享一个校验模块。** 被 source plane 布局否决：client 包只 reference client 包外加 `vendor/cordis` 与 `support/invariants`，把它放宽到够得着 host 包会撞上这一分割本就要隔开的两份 `Context` 合并。在两侧各镜像一行断言并各配一份测试，是此处的既定形态。
 
@@ -74,15 +74,15 @@ Status: implemented
 
 **让形状启发式也在 resolver 中运行。** 更对称，且能拦住直接写进 `.env` 的整行环境变量。因上文所述的锁死风险而否决：resolver 中的一次误判会让用户无路可走，浏览器中的一次误判则仍留有环境变量这条路。
 
-**在保存时探测 provider 以证明 Key 可用。** 它能关掉最初报告的那件事——保存报成功、第一轮才失败。因超出范围而否决，且在当时的代码上无法建成：对 pi-ai 恰好自带 catalog 的那些 provider，`discoverModels` 会在任何网络调用之前短路到内置 catalog，因而对 Key 什么都验证不了；而 DeepSeek 卡片根本没有探测。验证器的价值在于分清「Key 被拒」与「无法连通」，而这正是本次改动让其变得可靠的区分；先建验证器只会得到一个分不清自身结果的验证器。同类产品也不在保存时验证，因此保存时的阻断式网络调用会是一个意外行为，而非一处缺失。
+**在保存时探测 provider 以证明 Key 可用。** 它能关掉最初报告的那件事——保存报成功、第一轮才失败。因超出范围而否决，且在当时的代码上无法建成：对 pi-ai 恰好自带 catalog 的那些提供方，`discoverModels` 会在任何网络调用之前短路到内置 catalog，因而对 Key 什么都验证不了；而 DeepSeek 卡片根本没有探测。验证器的价值在于分清「Key 被拒」与「无法连通」，而这正是本次改动让其变得可靠的区分；先建验证器只会得到一个分不清自身结果的验证器。同类产品也不在保存时验证，因此保存时的阻断式网络调用会是一个意外行为，而非一处缺失。
 
-## Consequences
+## 后果
 
 格式错误的 Key 在持有它的那个字段上就被拒绝；格式错误的已存储 Key 以 `INVALID_CREDENTIAL` 失败，消息指明修复位置且不含 Key 的任何片段。由于该 code 位于 `DEFAULT_RETRYABLE_CODES` 之外，一个确定性的凭据故障不再被当作瞬时传输抖动重试三次。`llm-pi-ai` 的探测把非法 Key 报为凭据故障，而非端点不可达。
 
-形状启发式可能拒绝一个真实的 Key。最初的写法匹配任意「全大写标识符接 `=`」，评审指出其覆盖面比预期更宽：一个以 padding 结尾的全大写 base64 Key（`ABCD==`）会命中它并不像的赋值形态。要求分隔符之后必须是非 `=` 字符即可排除 padding——base64 的 padding 只出现在末尾。剩下的形态（大写名称、一个 `=`、然后是值）是已知 provider 不会签发的，且该规则只在浏览器中运行，因此仍撞上它的用户可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
+形状启发式可能拒绝一个真实的 Key。最初的写法匹配任意「全大写标识符接 `=`」，评审指出其覆盖面比预期更宽：一个以 padding 结尾的全大写 base64 Key（`ABCD==`）会命中它并不像的赋值形态。要求分隔符之后必须是非 `=` 字符即可排除 padding——base64 的 padding 只出现在末尾。剩下的形态（大写名称、一个 `=`、然后是值）是已知提供方不会签发的，且该规则只在浏览器中运行，因此仍撞上它的用户可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
 
-限定为可打印 ASCII 比传输本身的要求更严：header value 是可以承载 `\x80`–`\xFF` 的。放行 latin-1 会让 `é` 通过并换回一个语焉不详的 401，而不是一次本地的、有解释的拒绝，因此从严是刻意的。若某个 provider 签发 latin-1 的 Key，这条规则需要放宽。
+限定为可打印 ASCII 比传输本身的要求更严：header value 是可以承载 `\x80`–`\xFF` 的。放行 latin-1 会让 `é` 通过并换回一个语焉不详的 401，而不是一次本地的、有解释的拒绝，因此从严是刻意的。若某个提供方签发 latin-1 的 Key，这条规则需要放宽。
 
 字符集断言存在两份，每个 source plane 一份。布局禁止共享它；两侧各自带测试并在注释中指名其孪生体。
 
@@ -90,7 +90,7 @@ Status: implemented
 
 把这件事做错的最大代价，会是把「未指定」当成「非法」：一条施加到 `undefined` 上的规则会打断每一条依赖 ambient 发现或 OAuth 鉴权的路由，而一个会拦截提交的空输入框，则会让改动任何其他设置都必须重新输入 Key。这两点都由测试钉住，而不是仅仰赖谨慎。
 
-## Testing
+## 测试
 
 `packages/llm/llm/tests/api-key.spec.ts` 以整张输入表驱动 `normalizeApiKey` 与 `assertUsableApiKey`——空值、纯空白、带首尾空白、含中间空格、C0 控制字符、emoji、中文、全角、latin-1，以及可打印 ASCII 的边界字符——并钉住一次拒绝携带 `INVALID_CREDENTIAL` 且不含 Key 的任何部分。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
index a08d6323dd..378358d0cb 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.md
 2026-08-06-onboarding-step-owned-takeover-chrome.md: 4b3bbbc03c4494359297ae6e54bcc9a74c387e80
-2026-08-06-onboarding-step-owned-takeover-chrome.zh.md: 548285d285939325a26df3b8d70c43fe952813a9
+2026-08-06-onboarding-step-owned-takeover-chrome.zh.md: 88e27649d719c0ef7cd2b4604c507c40845a715d
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
index 548285d285..88e27649d7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
@@ -1,6 +1,6 @@
-# Agent Note：首次使用引导的接管界面框架移入步骤自身
+# Agent Note: 首次使用引导的接管界面框架移入步骤自身
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-06-onboarding-step-owned-takeover-chrome.md) | 中文
 
@@ -10,26 +10,26 @@
 
 于是每次在 hero（空白或无会话）状态下刷新页面，会话列表一变 `ready` 就弹出整屏不透明层——亮色主题下是白色——并阻断全部交互，时长恰好等于一次凭据/设置 RPC 往返；之后已配置好的步骤自我完成，图层消失。用户看到的就是每次刷新在 workspace/会话列表落地的瞬间闪一下白屏。
 
-## 决定
+## 决策
 
-接管界面框架属于步骤，不属于外壳。新增零 cordis 原语 `OnboardingSurface`（ui-primitives）：渲染 portal 到 body 的浮层／遮罩／展示层——CSS 类名与几何从 `SettingsRoot.module.css` 逐字迁移——并在自身挂载生命周期内保持 `#root` 为 `inert`。两个步骤组件只把各自的**可见**分支包进该原语；既有的 `null` 分支由此在构造上不绘制、不阻塞任何内容，因为界面框架已是同一次渲染决策的一部分。
+接管界面框架属于步骤，不属于外壳。新增零 Cordis 原语 `OnboardingSurface`（ui-primitives）：渲染 portal 到 body 的浮层／遮罩／展示层——CSS 类名与几何从 `SettingsRoot.module.css` 逐字迁移——并在自身挂载生命周期内保持 `#root` 为 `inert`。两个步骤组件只把各自的**可见**分支包进该原语；既有的 `null` 分支由此在构造上不绘制、不阻塞任何内容，因为界面框架已是同一次渲染决策的一部分。
 
-`SettingsRoot` 的协调器原样保留（有序账本投影、每次挂载一个步骤、本地完成集合、`stepId`／`complete`／`openSection` currency），但对当选步骤裸渲染——不再有 portal、展示层和 inert 效果。`settings.onboarding` 的 slot 契约现在写明：注册方持有外层包裹，且在私有事实未决时必须渲染 `null`。
+`SettingsRoot` 的协调器原样保留（有序账本投影、每次挂载一个步骤、本地完成集合、`stepId`／`complete`／`openSection` currency），但对当选步骤裸渲染——不再有 portal、展示层和 inert 效果。`settings.onboarding` 的 slot 约定现在写明：注册方持有外层包裹，且在私有事实未决时必须渲染 `null`。
 
 ## 曾考虑的替代方案
 
-**条件注册（账本即有内容信号）。** 私有 join 解析出「需要介入」后才注册条目。架构上干净（在 commit point 发布），但改动更大：join 的加载必须从对话框上移到各插件的 apply，注册／销毁在两个包里都变成响应式接线。对本缺陷而言过重，否决。
+**条件注册（账本即有内容信号）。** 私有 join 解析出「需要介入」后才注册条目。架构上干净（在 commit point 发布），但改动更大：join 的加载必须从对话框上移到各插件的 apply，注册／dispose（资源释放）在两个包里都变成响应式接线。对本缺陷而言过重，否决。
 
-**把 `settings.onboarding` 改成 chain 并把完成集合外置为 store。** composer takeover 的版型；做过原型后回退。selector 只能判定 owner props，私有就绪事实仍然只能在组件内部解析——chain 买来的是当前两个步骤并不需要的路由通用性，代价却是跨三个包的契约变更。
+**把 `settings.onboarding` 改成 chain 并把完成集合外置为 store。** composer takeover 的版型；做过原型后回退。selector 只能判定 owner props，私有就绪事实仍然只能在组件内部解析——chain 买来的是当前两个步骤并不需要的路由通用性，代价却是跨三个包的约定变更。
 
-**在渲染点探测 slot 输出为空。** `renderSlot` 无条件返回 outlet 元素，owner 无法据步骤的 `null` 分支；探测已渲染 DOM 是否为空需要先提交再撤回的手法，其动态翻转会失去 paint 前的保证。
+**在渲染点探测 slot 输出为空。** `renderSlot` 无条件返回 outlet 元素，owner 无法根据步骤的 `null` 进行分支判断；探测已渲染 DOM 是否为空需要先提交再撤回的手法，其动态翻转会失去 paint 前的保证。
 
 ## 后果
 
-步骤已挂载但尚未判定期间，应用保持可见且可交互：判定窗口内 `#root` 不再是 `inert`（此前是在不透明图层背后被置灰）。对真正未配置的用户，接管层比从前晚一个 join 往返出现——但一出现就带着内容，而不是先露出空白展示层再填充。
+步骤已挂载但尚未判定期间，应用保持可见且可交互：判定窗口内 `#root` 不再是 `inert`（此前在不透明图层背后处于 inert 状态）。对真正未配置的用户，接管层比从前晚一个 join 往返出现——但一出现就带着内容，而不是先露出空白展示层再填充。
 
-未来若有步骤注册后不把可见内容包进 `OnboardingSurface`，会无遮罩地裸渲染在应用之上；slot 契约的 JSDoc 已把包裹写为注册方的义务。
+未来若有步骤注册后不把可见内容包进 `OnboardingSurface`，会无遮罩地裸渲染在应用之上；slot 约定的 JSDoc 已把包裹写为注册方的义务。
 
 ## 测试
 
-`packages/client/ui-primitives/tests/onboarding-surface.spec.tsx` 钉住原语行为：内容外的 body portal、遮罩／展示层类名存在、`#root` 的 `inert` 恰好持续挂载生命周期，以及无 `#root` 的组合。`packages/client/ui-settings/tests/settings-root.spec.tsx` 钉住反转后的外壳契约：已挂载步骤什么都不渲染时，无接管界面框架、无 inert。`apps/web/tests/onboarding-deepseek-config.e2e.ts` 新增本缺陷的整装回归钉：已配置世界刷新页面，同时在浏览器网络边界扣住所有 `settings.describe` 响应——把步骤的判定窗口从 loopback 下不可见拉宽到数百毫秒，这正是断言保持非空洞的关键——页内 8ms 采样器证明接管界面框架从未挂载、`#root` 从未变为 inert。该文件的既有场景与步骤 spec（`ui-settings-general`、`ui-models`）原样通过——样式表逐字迁移，遮罩选择器与几何钉子得以幸存。
+`packages/client/ui-primitives/tests/onboarding-surface.spec.tsx` 钉住原语行为：包裹内容的 body portal、遮罩／展示层类名存在、`#root` 的 `inert` 恰好持续挂载生命周期，以及无 `#root` 的组合。`packages/client/ui-settings/tests/settings-root.spec.tsx` 钉住反转后的外壳约定：已挂载步骤什么都不渲染时，无接管界面框架、无 inert。`apps/web/tests/onboarding-deepseek-config.e2e.ts` 新增本缺陷的整装回归钉：已配置世界刷新页面，同时在浏览器网络边界扣住所有 `settings.describe` 响应——把步骤的判定窗口从 loopback 下不可见拉宽到数百毫秒，这正是断言保持非空洞的关键——页内 8 ms 采样器证明接管界面框架从未挂载、`#root` 从未变为 inert。该文件的既有场景与步骤 spec（`ui-settings-general`、`ui-models`）原样通过——样式表逐字迁移，遮罩选择器与几何钉子得以幸存。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
index de0b20d867..c80c9a5d8d 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.md
 2026-08-06-provider-credential-lifecycle.md: c28788921e8f1b233b44e19b29ad4d4acaa25022
-2026-08-06-provider-credential-lifecycle.zh.md: 2ea3b21fb6ceb4fa38a0cad0daf47c3b6a98a664
+2026-08-06-provider-credential-lifecycle.zh.md: d11aee5c5f014315c016e77f157cbac2624f844c
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
index 2ea3b21fb6..d11aee5c5f 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
@@ -10,18 +10,18 @@ Models 编辑器横跨互相独立的 settings 与凭据 RPC 领域。之前它
 
 ## 决策
 
-提供方保存仍在现有 wire 领域上按先 settings、后凭据的两阶段顺序执行，但卡片会把成功的 settings 响应视为提交检查点。它会在尝试 `credentials.set` 之前，用返回的脱敏 descriptor 替换比较基准子树与预期 revision；如果第二阶段失败，草稿密钥与卡片会继续显示，重试不会产生 settings op，只会再次写入凭据。首次 settings 提交之前发生的真实并发变更仍会以 `settings-conflict` 失败。UI 与 DeepSeek 直连 resolver 边界均会去除所输密钥的首尾空白，且只有标准化密钥非空时，pi-ai 才会记录派生引用；留空密钥会具化一个空的、不带引用的 profile，以便使用提供方原生凭据发现。
+提供方保存仍在现有 wire 领域上按先 settings、后凭据的两阶段顺序执行，但卡片会把成功的 settings 响应视为提交检查点。它会在尝试 `credentials.set` 之前，用返回的脱敏 descriptor 替换比较基准子树与预期 revision；如果第二阶段失败，草稿密钥与卡片会继续显示，重试不会产生 settings op，只会再次写入凭据。首次 settings 提交之前发生的真实并发变更仍会以 `settings-conflict` 失败。UI 与 DeepSeek 直连 resolver 边界均会去除所输密钥的首尾空白，且只有标准化密钥非空时，pi-ai 才会记录派生引用；留空密钥会生成一个空的、不带引用的 profile，以便使用提供方原生凭据发现。
 
 只有当联接所得的行识别出该页面派生的精确 `<ROUTE>_API_KEY` 引用，并将其报告为已配置且可写时，删除操作才会清除该凭据。它会先取消设置该凭据，再取消设置用户层 profile；如果 settings 阶段失败，该行及其已冻结的目标仍可见，便于重试。两项 unset 都具备幂等性。自定义引用、环境凭据、缺失的凭据，以及联接无法识别目标的凭据均会保留。行的无障碍 Edit/Delete 名称以及破坏性对话框的标题、说明和最终操作都使用同一个稳定的 `Display Name (route-id)` 标识；当两个字符串相同时，标识会简化为路由 id。对话框会说明是否一并删除已存密钥，并在自身内显示操作失败，而不是用加载错误横幅替换整个页面。行只根据不含值的联接结果展示 API 密钥状态：确认已配置的引用凭据显示为绿色实心点，确认缺失的具名引用显示为红色实心点，无引用的提供方原生认证或无法取得凭据补充信息时则不显示状态点。每个状态点都有无障碍文案和工具提示；「应用」成功后的本地状态消息会使用同一个提供方标识，且绝不回显任何机密内容。
 
 ## 曾考虑的替代方案
 
-**添加跨领域事务 RPC。**settings 与凭据分属不同的主管服务与持久存储；引入新的 Host 事务会扩大公开 wire 面，而且仍需要补偿提供方特定的持久化失败。UI 检查点让当前的有序阶段变得可恢复，无需添加第四项配置契约。
+**添加跨领域事务 RPC。** settings 与凭据分属不同的主管服务与持久存储；引入新的 Host 事务会扩大公开 wire 面，而且仍需要补偿提供方特定的持久化失败。UI 检查点让当前的有序阶段变得可恢复，无需添加第四项配置约定。
 
-**删除被移除 profile 所指定的每一个凭据引用。**自定义引用可能被共享、由外部管理，或有意在 profile 反复增删时存留。与该页面派生目标精确相等，再加上已配置且可写的状态，是页面所能获得的最小范围证据；比这更弱的判定都有可能删除不属于它的凭据。
+**删除被移除 profile 所指定的每一个凭据引用。** 自定义引用可能被共享、由外部管理，或有意在 profile 反复增删时存留。与该页面派生目标精确相等，再加上已配置且可写的状态，是页面所能获得的最小范围证据；比这更弱的判定都有可能删除不属于它的凭据。
 
-**先删除 settings，再重建 profile 以作补偿。**浏览器只持有脱敏后的子树，无法忠实重建并发编辑。先删除凭据可以让权威 profile 在部分失败时仍然可见，并且无需合成配置就能安全重试。
+**先删除 settings，再重建 profile 以作补偿。** 浏览器只持有脱敏后的子树，无法忠实重建并发编辑。先删除凭据可以让权威 profile 在部分失败时仍然可见，并且无需合成配置就能安全重试。
 
 ## 后果
 
-Models 页可以从任一第二阶段失败中恢复，无需重新加载，也不会泄露机密或产生虚假的并发冲突；空密钥的 pi-ai profile 会保留 Bedrock、Vertex 与其他提供方原生认证。已确认的状态清晰可见，同时不会把路由存活状态、原生认证或凭据查询失败误报为错误；即使该行继续显示绿色，密钥替换成功也仍然可观察。删除由页面管理的提供方不再遗留可重用的本地密钥，而存在歧义的凭据会有意保留，交由手动管理。保存与删除在跨持久存储时仍非原子操作：进程可能在两个阶段之间崩溃，但它们的顺序与幂等性会留下可观察、可重试的状态。组件测试固定了部分成功后的重试、空密钥原生认证、密钥首尾空白处理、状态可见性、目标标识、清理所有权，以及凭据／settings 拒绝顺序；无密钥的浏览器场景固定了双语无障碍文案，并验证确认删除会同时清除 `settings.yaml` profile 与 `.credentials.yaml` 条目。此决策细化了 [web 配置平面 note](../architecture/2026-07-30-web-config-plane.md) 中记录的 Models 应用语义。
+Models 页可以从任一第二阶段失败中恢复，无需重新加载，也不会泄露机密或产生虚假的并发冲突；空密钥的 pi-ai profile 会保留 Bedrock、Vertex 与其他提供方原生认证。已确认的状态清晰可见，同时不会把路由存活状态、原生认证或凭据查询失败误报为错误；即使该行继续显示绿色，密钥替换成功也仍然可观察。删除由页面管理的提供方不再遗留可重用的本地密钥，而存在歧义的凭据会有意保留，交由手动管理。保存与删除在跨持久存储时仍非原子操作：进程可能在两个阶段之间崩溃，但它们的顺序与幂等性会留下可观察、可重试的状态。组件测试固定了部分成功后的重试、空密钥原生认证、密钥首尾空白处理、状态可见性、目标标识、清理所有权，以及凭据／settings 拒绝顺序；无密钥的浏览器场景固定了双语无障碍文案，并验证确认删除会同时清除 `settings.yaml` profile 与 `.credentials.yaml` 条目。此决策细化了 [web 配置平面 Agent Note](../architecture/2026-07-30-web-config-plane.md) 中记录的 Models 应用语义。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
index 1c861833cf..2982e05c65 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
 2026-08-06-reader-scroll-attribution-observed-top-ledger.md: 2dcd0178e4216d4d3e2edcd3bfcc05b63606c333
-2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: ffb03fdb68c9cb040e311077dd698b310a033fdd
+2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: 7a1142cdd793cfce46bfd3908ab28345701aec7a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
index ffb03fdb68..7a1142cdd7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
@@ -12,13 +12,13 @@ ChatView 的贴底跟随此前只把滚轮／触控板手势识别为读者输
 
 读者输入不再依据设备来识别。ChatView 维护一份 observed-top ledger（`observedTopRef`）：即最近一次由主线程交付、或由组件自身写入的 `scrollTop`，并在每一个程序化写入点（贴底跟随、打开时恢复、前置锚定、尺寸变化跟随以及滚动交付本身）同步记录。滚动事件到达时，偏离 `min(ledger, floor)` 超过半像素的位置即为读者输入；落在 ledger 上的位置（迟到的程序化交付），或恰好落在收缩后底部上的位置（内容收缩后的浏览器钳制），则维持当前的所有权状态。此后所有权只经由读者输入、按既有阈值规则变化：位置距底部在 `FOLLOW_THRESHOLD` 以内则重新贴底，超出则释放跟随并显示「回到底部」。滚轮监听器及其 epoch 簿记已删除；组件只监听 `scroll`，因此滚轮、触控、滚动条、键盘以及未来任何输入来源都由同一条规则覆盖。
 
-## 契约变更：收缩与重新增长被合并的钳制
+## 约定变更：收缩与重新增长被合并的钳制
 
-如果一次收缩钳制的布局在同一次渲染更新内、赶在该钳制的滚动事件交付之前重新增长，那么这个事件在几何上与读者输入无法区分，因此它现在会被判读为读者并释放跟随（可经「回到底部」恢复）。现实中由 React 提交（commit）驱动的收缩与重新增长仍会被吸收：layout effect 中的跟随会在每次提交后重新贴底并重新记录 ledger，而仅收缩的钳制会恰好落在 `min(ledger, floor)` 上。只有在同一次更新内先收缩再重新增长的非 React 重排会被误归因。旧的滚轮模型在这种竞态情形下会保持跟随；单元测试契约已在同一变更中改写为只吸收纯收缩的保证。
+如果一次收缩钳制的布局在同一次渲染更新内、赶在该钳制的滚动事件交付之前重新增长，那么这个事件在几何上与读者输入无法区分，因此它现在会被判读为读者并释放跟随（可经「回到底部」恢复）。现实中由 React 提交（commit）驱动的收缩与重新增长仍会被吸收：layout effect 中的跟随会在每次提交后重新贴底并重新记录 ledger，而仅收缩的钳制会恰好落在 `min(ledger, floor)` 上。只有在同一次更新内先收缩再重新增长的非 React 重排会被误归因。旧的滚轮模型在这种竞态情形下会保持跟随；单元测试约定已在同一变更中改写为只吸收纯收缩的保证。
 
 ## 测试
 
-`packages/client/ui-conversation/tests/chat-view.spec.tsx` 中的单元测试直接钉住 ledger 契约：`readerScroll` 辅助函数交付一个组件从未写入过的位置，程序化交付落在 ledger 上，流收尾阶段的收缩钳制保持跟随。`apps/web/tests/chat-scroll-contract.e2e.ts` 中的两个场景扩展了[浏览器 e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)：在已停稳的 transcript 上做键盘翻页，以及对着按节奏推进的流式输出做一次触控式惯性快滑（momentum fling）；两者在仅认滚轮的实现下均为红、在 ledger 下均为绿。
+`packages/client/ui-conversation/tests/chat-view.spec.tsx` 中的单元测试直接钉住 ledger 约定：`readerScroll` 辅助函数交付一个组件从未写入过的位置，程序化交付落在 ledger 上，流收尾阶段的收缩钳制保持跟随。`apps/web/tests/chat-scroll-contract.e2e.ts` 中的两个场景扩展了[浏览器 e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)：在已停稳的 transcript 上做键盘翻页，以及对着按节奏推进的流式输出做一次触控式惯性快滑（momentum fling）；两者在仅认滚轮的实现下均为红、在 ledger 下均为绿。
 
 该车道的 Chromium 无法合成任何非滚轮的设备滚动，这限定了 e2e 能真实驱动的范围：触控来源的 `Input.synthesizeScrollGesture` 与手工构造的 `Input.dispatchTouchEvent` 序列都能交付 DOM 事件，却从不移动滚动容器（无头模式与 Xvfb 下的有头模式皆然）；`default` 手势来源合成的是滚轮事件；合成器滚动条则完全无视合成的鼠标输入，且只有移除 `--hide-scrollbars` 后才能看到滚动条槽。键盘是唯一可用的非滚轮原语，因此由它承担真实输入流水线的证明；快滑场景则把触控的特征（组件从未写入过的逐帧衰减位移）直接回放进滚动容器。
 
@@ -34,4 +34,4 @@ ChatView 的贴底跟随此前只把滚轮／触控板手势识别为读者输
 
 ## 后果
 
-每种读者输入现在都以同一方式拥有贴底跟随，而代码更少：滚轮监听器、它的 epoch 计数器以及输入前基线簿记均已移除，归因搭载在组件本就维护的状态之上。sticky-composer 笔记中的布局、滚轮链式处理与前置锚定决策原样保留，仍为权威；其窄范围的输入来源规则由本笔记取代。代价就是上文的契约变更：一次收缩与重新增长被合并的非 React 钳制现在会暂停跟随，直到读者回到底部或按下「回到底部」；以此换来流式输出期间触控、滚动条与键盘的正确性。e2e 车道获得的非滚轮覆盖仅限其浏览器能够合成的范围；若手势合成在未来某个 Chromium 版本中开始可用，可以在不改变所断言契约的前提下，把快滑模拟替换为真实的触控划动。
+每种读者输入现在都以同一方式拥有贴底跟随，而代码更少：滚轮监听器、它的 epoch 计数器以及输入前基线簿记均已移除，归因搭载在组件本就维护的状态之上。sticky-composer 笔记中的布局、滚轮链式处理与前置锚定决策原样保留，仍为权威；其窄范围的输入来源规则由本笔记取代。代价就是上文的约定变更：一次收缩与重新增长被合并的非 React 钳制现在会暂停跟随，直到读者回到底部或按下「回到底部」；以此换来流式输出期间触控、滚动条与键盘的正确性。e2e 车道获得的非滚轮覆盖仅限其浏览器能够合成的范围；若手势合成在未来某个 Chromium 版本中开始可用，可以在不改变所断言约定的前提下，把快滑模拟替换为真实的触控划动。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
index bb344c5afe..d6caa87acb 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.md
 2026-08-06-token-surface-unpriced-replace-compatibility.md: 77b778fba695f560eb68af6da2f416e61ccff181
-2026-08-06-token-surface-unpriced-replace-compatibility.zh.md: dd4c5883c4c6d37809c2f8100f266655d8ba600c
+2026-08-06-token-surface-unpriced-replace-compatibility.zh.md: 1a18551b1e0c1e7e78f32d69caec1d0956a4075d
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
index dd4c5883c4..1a18551b1e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
@@ -8,19 +8,19 @@ Status: implemented
 
 `contextPressure` 与 `contextBreakdown` 两个投影只维护一份滚动累计的表层 token 总量，外加至多一条待结算的影子价格（shadow price）声明，因此其持久化检查点在会话整个生命周期内保持 O(1)。当前的替换生产方会紧贴在替换之前追加一条 `compact/summary` 或 `compact/prune` 计量事件；其 `shadowedTokenCount` 对被替换区间精确计价，`foldSurfaceProjection` 再把它换算成有符号增量。
 
-影子价格协议引入之前录制的会话，其日志中的替换没有相邻的计量事件。O(1) 状态无法重建被替换区间的价格，而折叠此前把每一次未计价替换都当作契约违规并抛出异常，于是回放这类会话会在第一处替换就中断（`token surface: replace at seq … has no adjacent shadow price`），会话从此永远无法打开。
+影子价格协议引入之前录制的会话，其日志中的替换没有相邻的计量事件。O(1) 状态无法重建被替换区间的价格，而折叠此前把每一次未计价替换都当作约定违规并抛出异常，于是回放这类会话会在第一处替换就中断（`token surface: replace at seq … has no adjacent shadow price`），会话从此永远无法打开。
 
 ## 决策
 
 到达时没有已就位声明的替换以价格中性的方式折叠：`foldSurfaceProjection` 返回 `deltaTokens: 0`，相当于把被替换区间计价为恰好等于其替换内容的成本，回放随即继续。因中间插入的事件而过期的声明也走同一条中性路径，因为折叠无法把它与从未计量过的日志区分开。
 
-已就位但指向**另一个**区间的声明仍会抛出异常。此时计量事件确实相邻，说明生产方写入了互相矛盾的相邻事件：这是现行影子价格契约的违规，不是历史数据，必须响亮失败，而不能任由总量悄然漂移。
+已就位但指向**另一个**区间的声明仍会抛出异常。此时计量事件确实相邻，说明生产方写入了互相矛盾的相邻事件：这是现行影子价格约定的违规，不是历史数据，必须明确报错，而不能任由总量悄然漂移。
 
 两个投影共用同一个折叠，因此二者都不新增状态字段，也不提升 `stateVersion`。`surface-fold.ts` 与 `ctx.tokenMeter.measure()` 不受影响：它们持有逐节点的已计价表层，本来就不需要声明协议。
 
 ## 备选方案
 
-**维持抛出异常。**保住了严格的生产方契约，但协议之前的每个会话都将永远无法回放，而投影本就是为服务回放而存在的。
+**维持抛出异常。**保住了严格的生产方约定，但协议之前的每个会话都将永远无法回放，而投影本就是为回放服务的。
 
 **在投影状态中持久化完整的已计价表层。**可以对任意被替换区间精确计价，但检查点会随每条模型可见消息各增加一个节点、无上限地增长，恰恰破坏了影子价格协议所要守住的 O(1) 约束（见[上下文仪表的 Agent Note](2026-08-05-context-meter-blind-to-compaction.md)）。
 
@@ -28,7 +28,7 @@ Status: implemented
 
 未计价的替换让总量保持不动而不是缩小，因此被压缩（compaction）掉的区段仍被计入：`contextBreakdown.messageTokens` 保留这部分多计的量；`contextPressure.projectedTokens` 会高估占用率，但只持续到下一个用量样本重新锚定为止，因为该数字追踪的是自样本以来的增减，而非绝对水平。误差方向是安全的：高估占用率最坏不过是招致一次更早的压缩。
 
-响亮失败保留在它仍有意义的地方：区间不匹配的相邻声明是现行生产方的缺陷，仍会抛出异常。
+明确报错机制仍保留在有意义的场景中：区间不匹配的相邻声明是现行生产方的缺陷，仍会抛出异常。
 
 ## 测试
 
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index 1884c12c93..45dc5edb5c 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
 2026-06-21-subagent-capability-seam.md: 752e639b09ea2ac0ba19841ddfe38b15b44d22e9
-2026-06-21-subagent-capability-seam.zh.md: 6009aeda6773357a4217f8956fb510c2116bbe3f
+2026-06-21-subagent-capability-seam.zh.md: f0b0ba2ab8b0bb7b611e995c56e30db68b21cfa7
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index 6009aeda67..f0b0ba2ab8 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -1,37 +1,37 @@
-# Agent Note: Subagent 能力 seam
+# Agent Note: subagent 能力 seam
 
 Status: implemented
 
 [English](2026-06-21-subagent-capability-seam.md) | 中文
 
-> 完整 seam 已交付：`dsh-subagent` 接口与 `dsh-tool-subagent` 消费方；两个进程内后端（`dsh-subagent-spawn`、`dsh-subagent-fork`）；嵌套 agent 快照基础设施（[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)）；以及进程外的 ACP、Codex 与 Claude Code 后端（[ACP Agent Note](2026-06-22-acp-subagent-backend.md)、[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）。
+> 完整 seam 已交付：`dsh-subagent` 接口与 `dsh-tool-subagent` 消费方；两个进程内后端（`dsh-subagent-spawn`、`dsh-subagent-fork`）；嵌套 agent（智能体）快照基础设施（[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)）；以及进程外的 ACP（Agent Client Protocol）、Codex 与 Claude Code 后端（[ACP Agent Note](2026-06-22-acp-subagent-backend.md)、[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）。
 
 ## 问题
 
-harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent（智能体）将工作委派给另一个 agent。这一意图在 `Agent`/`AgentLoop` 接口中已有草案（[packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts)、[packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)）：一个创建选项引用父 agent（fork = 用父会话的事件日志初始化子会话；spawn = 全新会话），子 agent 以 `Agent` 句柄返回，使 steering（中途引导）和事件订阅可以统一工作。本 Agent Note 实现了这个 seam；上方横幅列出了已交付的内容。
+harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent 将工作委派给另一个 agent。这一意图在 `Agent`/`AgentLoop` 接口中已有草案（[packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts)、[packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)）：一个创建选项引用父 agent（fork = 用父会话的事件日志初始化子会话；spawn = 全新会话），子 agent 以 `Agent` 句柄返回，使 steering（中途引导）和事件订阅可以统一工作。本 Agent Note 实现了这个 seam；上方横幅列出了已交付的内容。
 
-决定整体设计走向的核心需求是：**多种 subagent 实现必须在运行时共存**。一个父 agent 可能在同一个会话中既需要一个廉价的进程内子 agent 处理有限范围的子任务，又需要一个隔离的进程外子 agent（通过 ACP（Agent Client Protocol））。我们预见的传输方式：
+决定整体设计走向的核心需求是：**多种 subagent 实现必须在运行时共存**。一个父 agent 可能在同一个会话中既需要一个廉价的进程内子 agent 处理有限范围的子任务，又需要一个隔离的进程外子 agent（通过 ACP）。我们预见的传输方式：
 
 - **进程内**：在同一个 `Context` 上创建一个具体的子 `Agent`（最廉价，且鉴于现有 agent 工厂几乎零成本）；
 - **ACP**：作为 ACP *客户端*驱动另一个 agent 进程（可以是自身的另一个实例）；
-- **Codex app-server 与 Claude Code Agent SDK**：当前的一次性兄弟提供方，将同一个命名提供方 seam 应用于官方产品进程（[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）；
+- **Codex app-server 与 Claude Code Agent SDK**：当前的一次性同类提供方，将同一个命名提供方 seam 应用于官方产品进程（[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）；
 - 后续：**A2A**，采用同样的进程外形态：「启动子 agent、发送提示词、结算、取消」。
 
 ## 曾考虑的替代方案
 
 ### 为何不采用 bash seam 的形状
 
-bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个上下文中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（接口 / 实现 / 消费方）；只是「一个 vs. 多个实现」这个维度不同。
+bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个上下文中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（接口、实现、消费方）；只是「一个 vs. 多个实现」这个维度不同。
 
 ## 决策
 
 ### 由三个包构成的 seam
 
-新建包（package）组 `packages/subagent/`：
+新建包组 `packages/subagent/`：
 
 | 包 | 角色 |
 |---|---|
-| `@deepseek-ai/dsh-subagent` | 接口：`SubagentService`（`ctx.subagents`）、`SubagentProvider`、`SubagentRun`、请求/结果/能力词汇、`subagent/*` 事件 |
+| `@deepseek-ai/dsh-subagent` | 接口：`SubagentService`（`ctx.subagents`）、`SubagentProvider`、`SubagentRun`、请求、结果、能力词汇、`subagent/*` 事件 |
 | `@deepseek-ai/dsh-subagent-spawn` | 实现：通过 `ctx.agents.create` 创建全新的进程内子 agent |
 | `@deepseek-ai/dsh-subagent-fork` | 实现：用父 agent 日志快照初始化的进程内子 agent |
 | `@deepseek-ai/dsh-subagent-acp` | 实现：作为 ACP 客户端驱动已配置的子进程 |
@@ -45,8 +45,8 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 ### 两类可选能力，两种发现方式
 
-- **启动时功能**（`outputSchema`、`depthLimit`、`toolFilter`、`persona`）挂在静态的 `provider.capabilities` 描述符上。服务在委派之前检查每个被请求的功能，如果提供方不支持则**大声拒绝**（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不接受后静默忽略。这些功能必须在 run 存在之前检查，因此不能是运行时方法。
-- **可继续创建**使用可选的 `SubagentProvider.prepareContinuable` 方法；方法是否存在本身即为能力，TypeScript 类型收窄即为发现机制，因此不需要可能与实现失同步的独立 flag。继续执行管理器直接通过 `AgentHandle` 负责后续投递与从持久化存储恢复，而一次性 `SubagentRun` 没有 steering 或 resume 操作，具体由[可继续 subagent](2026-07-28-continuable-subagent-conversations.md)细化。
+- **启动时功能**（`outputSchema`、`depthLimit`、`toolFilter`、`persona`）挂在静态的 `provider.capabilities` 描述符上。服务在委派之前检查每个被请求的功能，如果提供方不支持则**明确拒绝**（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不接受后静默忽略。这些功能必须在 run 存在之前检查，因此不能是运行时方法。
+- **可继续创建**使用可选的 `SubagentProvider.prepareContinuable` 方法；方法是否存在本身即为能力，TypeScript 类型收窄即为发现机制，因此不需要可能与实现失同步的独立 flag。继续执行管理器直接通过 `AgentHandle` 负责后续投递与冷恢复，而一次性 `SubagentRun` 没有 steering 或 resume 操作，具体由[可继续 subagent](2026-07-28-continuable-subagent-conversations.md) 细化。
 
 ### Fork 与 fresh 是独立后端，而非一个 flag
 
@@ -58,7 +58,7 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 ### 同步收集（首版）
 
-`dsh-tool-subagent` 将其执行信号传给 `start()`，等待子 agent 结果，并在报告前 dispose 该 run。非完成态的结果变为错误结果，而非成功的部分输出；相互独立的结果与 dispose rejection 会保留两项 diagnostic。
+`dsh-tool-subagent` 将其执行信号传给 `start()`，等待子 agent 结果，并在报告前 dispose 该 run。非完成态的结果变为错误结果，而非成功的部分输出；结果与 dispose 的拒绝相互独立，且两项诊断信息都会保留。
 
 ### 提供方选择是配置，不面向模型
 
@@ -66,7 +66,7 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 ## 测试
 
-注册表与工具测试仅用包内脚本化提供方替换非确定性的子进程边界，同时运行真实的 `SubagentService`、生命周期、任务集成和面向模型的工具。提供方与消费方的 export 形状仍保留 Loader 回归覆盖，以防止[事后分析 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) 中描述的失败。注册表测试覆盖重载安全性、重名和启动时能力拒绝；嵌套 agent 场景通过[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)进行无密钥回放；进程内后端还有真实循环的单元测试和带密钥的 e2e 测试。
+注册表与工具测试仅用包内脚本化提供方替换非确定性的子进程边界，同时运行真实的 `SubagentService`、生命周期、任务集成和面向模型的工具。提供方与消费方的 export 形状仍保留 Loader 回归覆盖，以防止[事故复盘（postmortem）0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) 中描述的失败。注册表测试覆盖重载安全性、重名和启动时能力拒绝；嵌套 agent 场景通过[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)进行无密钥回放；进程内后端还有真实循环的单元测试和带密钥的 e2e 测试。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index e0f79bacb0..5229a4b034 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-05-skill-system.md
 2026-07-05-skill-system.md: 5961c535a1397c487b0255f8a27d60929c2eeace
-2026-07-05-skill-system.zh.md: 05bd880ecbd46f2b472eb2cc5442f11c07f89b4e
+2026-07-05-skill-system.zh.md: fe3cf200278c2dd5449e1442228419845593056b
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 05bd880ecb..fe3cf20027 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Skill 系统——面向 agent 的渐进式指令披露
+# Agent Note: skill 系统——面向 agent 的渐进式指令披露
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Agent（智能体）产品已趋同于一种 skill（技能）模式：保持请求提示词精简，仅列出可用的指令包，当模型判定某任务匹配时再加载完整正文。Codex、Claude Code、OpenCode 与 Kimi Code 在细节上各有不同，但都将发现元数据与完整指令分离，使工作区能承载可复用的行为而无需在每个轮次支付全量提示词开销。
+agent（智能体）产品已趋同于一种 skill（技能）模式：保持请求提示词精简，仅列出可用的指令包，当模型判定某任务匹配时再加载完整正文。Codex、Claude Code、OpenCode 与 Kimi Code 在细节上各有不同，但都将发现元数据与完整指令分离，使工作区能承载可复用的行为而无需在每个轮次支付全量提示词开销。
 
 DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和工具使用指南存放在工作区或用户的 agent 配置旁，而非硬编码到 agent loop（智能体循环）中。
 
@@ -16,31 +16,31 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 专用的随包提供方可以贡献不可变的 skill，无需文件系统发现。交付的 CLI（命令行界面）默认将 `@deepseek-ai/dsh-skill-badge` 声明为禁用；启用其组合配置行，就会通过同一个注册表和消费方贡献官方徽章指令（见[决策](2026-08-06-bundled-dsh-badge-skill.md)）。
 
-提供方插件在 `apply()` 期间同步注册。提供方成员资格是由直接 effect 持有的状态：注册与 dispose（资源释放）同步地使已完成的目录失效，发现操作按需读取当前提供方映射而非监听注册表变更事件。提供方目录从等待的 `list()` 调用返回排序后的候选项，远程提供方在此过程中执行初始化、认证和发现，同时遵守查找的 abort 信号。注册表校验每个候选项，按排名、提供方注册顺序和提供方内部顺序以先到先得方式解决同名 skill 冲突，然后按 skill 名称排序摘要以保证消费方获得确定性结果。它仅缓存已完成的目录快照，并在发现过程中提供方/运行时修订版本发生变化时重试，因此卸载操作不会将一个陈旧且不可解析的 skill 冻结到会话目录中。运行时 `ctx.skills.register(...)` 仍作为嵌入式进程内 skill 的便捷方式保留，使用 project 优先于 user 的优先级；`runtime` 保留为注册表拥有的提供方名称。
+提供方插件在 `apply()` 期间同步注册。提供方成员资格是由 effect 直接持有的状态：注册与 dispose（资源释放）同步地使已完成的目录失效，发现操作按需读取当前提供方映射而非监听注册表变更事件。提供方目录从等待的 `list()` 调用返回排序后的候选项，远程提供方在此过程中执行初始化、认证和发现，同时遵守查找的 abort 信号。注册表校验每个候选项，按排名、提供方注册顺序和提供方内部顺序以先到先得方式解决同名 skill 冲突，然后按 skill 名称排序摘要以保证消费方获得确定性结果。它仅缓存已完成的目录快照，并在发现过程中提供方/运行时修订版本发生变化时重试，因此卸载操作不会将一个陈旧且不可解析的 skill 冻结到会话目录中。运行时 `ctx.skills.register(...)` 仍作为嵌入式进程内 skill 的便捷方式保留，使用 project 优先于 user 的优先级；`runtime` 保留为注册表拥有的提供方名称。
 
 本地提供方按先到先得的排名顺序扫描 cwd 敏感的项目根目录、自定义根目录和用户根目录：项目 `.dsh`、项目 `.agents`、`customSkillDirs`、用户 `.dsh`，然后是用户 `.agents`。用户 `.dsh/skills` 扫描跳过 `.system`，以免系统拥有的目录被当作普通用户内容处理。本地提供方不会合成内置系统 skill；已配置的 bundled 根目录和专用提供方会提供额外 skill。
 
-每个 skill 是 `<name>/SKILL.md` 或带 YAML frontmatter 的 `<name>.md`。`name` 和 `description` 为必填；`whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable` 为可选。名称采用 kebab-case。调用字段会投影到类型化的嵌套策略中，具体由[模型与用户独立调用决策](2026-07-28-skill-invocation-policy.md)定义；解析器会拒绝旧的驼峰拼写。YAML frontmatter 使用 `yaml` 包（package）解析，而非 `js-yaml` 或手写解析器：`yaml` 是本包有限 frontmatter 需求已声明的现代解析器，窄解析器要么拒绝用户预期可用的合法 YAML，要么膨胀为一个未经评审的 YAML 子集。
+每个 skill 是 `<name>/SKILL.md` 或带 YAML frontmatter 的 `<name>.md`。`name` 和 `description` 为必填；`whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable` 为可选。名称采用 kebab-case。调用字段会投影到类型化的嵌套策略中，具体由[模型与用户独立调用决策](2026-07-28-skill-invocation-policy.md)定义；解析器会拒绝旧的驼峰拼写。YAML frontmatter 使用 `yaml` 包解析，而非 `js-yaml` 或手写解析器：`yaml` 是本包已声明用于满足有限 frontmatter 需求的现代解析器，窄解析器要么拒绝用户预期可用的合法 YAML，要么膨胀为一个未经评审的 YAML 子集。
 
-本地 skill 的文件系统 I/O 在加载了文件系统服务时通过 `ctx.fs` 进行：项目根目录查找使用 `resolve` 和 `stat` 探测 `.git`，根目录发现使用 `listDir`，skill 读取使用 `readText`。Node 文件系统作为后备，供在不挂载 fs seam 的最小上下文中加载 `dsh-skill-local` 时使用。缺失的根目录、不可读或格式错误的 skill 文件、以及提供方 `list()` 的瞬态失败均降级为警告并跳过，使一个坏源不会导致所有 agent 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方契约。
+本地 skill 的文件系统 I/O 在加载了文件系统服务时通过 `ctx.fs` 进行：项目根目录查找使用 `resolve` 和 `stat` 探测 `.git`，根目录发现使用 `listDir`，skill 读取使用 `readText`。Node 文件系统作为后备，供在不挂载 fs seam 的最小上下文中加载 `dsh-skill-local` 时使用。缺失的根目录、不可读或格式错误的 skill 文件、以及提供方 `list()` 的瞬态失败均降级为警告并跳过，使一个坏源不会导致所有 agent 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方约定。
 
 `dsh-tool-skill` 在会话的第一个 `agent/pre-step` 注入一个持久化的 user-role `<system-reminder>` 目录，作为带来源的 `user/message`，且仅当该 agent 的工具视图解析到本插件精确的 `skill` 注册时才注入。该目录仅包含排序后的 skill 名称与描述；不包含正文、路径、来源、提供方和路由提示。描述经过空白规范化、XML 转义，并受 `catalogDescriptionMaxLength` 上限约束，其默认值为 `500`，最小值为 `3`。完整的 skill 正文从不包含在目录中。（目录最初通过仅请求的[会话前缀 seam](../../archived/feature/2026-07-07-session-prefix.md)（已归档）传递；[统一带来源消息的决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)将其移入持久化历史。）
 
 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
 
-数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/subsystems/skills.md#cordis-surface)。
+数据结构与目录/工具约定记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/subsystems/skills.md#cordis-surface)。
 
 ## 曾考虑的替代方案
 
 **将完整 skill 正文注入每条系统提示词。** 否决，因为这破坏了渐进式披露，使每个请求都为可能不适用的指令付出代价。
 
-**仅以斜杠命令暴露 skill。** 否决，因为模型主动加载是核心能力；面向人类的命令广播不改变发现机制。
+**仅以斜杠命令暴露 skill。** 否决，因为模型主动加载是核心能力；面向人类的命令展示不改变发现机制。
 
-**将本地文件系统扫描直接放入 `ctx.skills`。** 否决，因为编码 agent、Web agent 和未来的插件生态需要不同的 skill 来源。提供方注册表与 subagent seam 镜像：注册表拥有冲突解决和消费方，实现拥有加载。
+**将本地文件系统扫描直接放入 `ctx.skills`。** 否决，因为编码 agent、Web agent 和未来的插件生态需要不同的 skill 来源。提供方注册表与 subagent seam 镜像：注册表拥有冲突解决和消费方，实现负责加载。
 
 **使用系统提示词段落。** 否决，因为渲染后的系统提示词是单一字符串，而目录是一条 user-role `<system-reminder>` 消息。[仅请求的会话前缀 seam](../../archived/feature/2026-07-07-session-prefix.md)（已归档）是最初的机制；统一带来源消息的决策移除该 seam 后，目录改为具有相同消息形状的持久化带来源注入。
 
-**在 `~/.dsh/skills/.system` 下物化内置 DSH 编写 skill。** 否决，因为打包的 skill 不应在启动时写入用户主目录，嵌入式或远程提供方在配置后提供 skill。
+**在 `~/.dsh/skills/.system` 下物化内置 DSH 编写 skill。** 否决，因为打包的 skill 不会在启动时写入用户主目录，嵌入式或远程提供方在配置后提供 skill。
 
 **递归发现嵌套的 `**/SKILL.md`。** 否决。扁平文件和一级目录包覆盖了配置的根目录，同时使重复处理和目录顺序易于推理。
 
@@ -48,10 +48,10 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 ## 后果
 
-agent-core 主干包含一个目录贡献者、一个本地提供方和一个面向模型的工具。Skill 发现是 cwd 敏感的，因此以不同会话 cwd 值创建 agent 的调用方可以按设计观察到不同的项目 skill 覆盖。
+agent-core 主干包含一个目录贡献者、一个本地提供方和一个面向模型的工具。skill 发现是 cwd 敏感的，因此以不同会话 cwd 值创建 agent 的调用方可以按设计观察到不同的项目 skill 覆盖。
 
 目录对于固定的根目录集合和运行时注册修订版本是确定性的。本地提供方会监视已配置的根目录，并在发生相关磁盘变化后使已完成的目录失效；运行时注册和提供方释放也会使其失效。
 
 ## 延后
 
-Fork 的 skill 上下文（`context: fork`）、参数声明与提示（`arguments` 和 `argument-hint`）、以及逐 skill 的工具约束（`allowed-tools` 和 `disallowed-tools`）不在已交付的契约范围内。注册表、本地提供方和面向模型的工具不解析、不广播、也不执行这些字段。直接用户调用曾作为 TUI 功能交付，基于共享调用策略和受信的 `get()` 原语；见[已归档的 TUI skill 斜杠命令](../../archived/feature/2026-07-21-tui-skill-slash-command.md)。
+fork 的 skill 上下文（`context: fork`）、参数声明与提示（`arguments` 和 `argument-hint`）、以及逐 skill 的工具约束（`allowed-tools` 和 `disallowed-tools`）不在已交付的约定范围内。注册表、本地提供方和面向模型的工具不解析、不广播、也不强制执行这些字段。直接用户调用曾作为 TUI 功能交付，基于共享调用策略和受信的 `get()` 原语；见[已归档的 TUI skill 斜杠命令](../../archived/feature/2026-07-21-tui-skill-slash-command.md)。
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
index d50b2323e3..0669efd1f4 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md
 2026-07-08-background-subagent-tasks.md: 679c57c3173a32b8cfccc6611b4ba74487e7f7e3
-2026-07-08-background-subagent-tasks.zh.md: 487943ab5cfe78226cde912854099fc56a5833a6
+2026-07-08-background-subagent-tasks.zh.md: ebfbb85add2f73d62b680407a6277c71f01f318e
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
index 487943ab5c..ebfbb85add 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 [subagent seam](2026-06-21-subagent-capability-seam.md) 会返回 `SubagentRun`，但原先面向模型的工具会同步收集每一次运行。因此，各自独立的慢速委派要么一直占用父调用，要么按串行方式运行。
 
-subagent 需要与其他长时间运行的工具相同的启动、收集、列出、停止、归属、通知和清理行为，但不应采用进程流语义。子会话仍是详细记录；父级只需最终答案和任务状态。后台子级的存活时间还会超过启动它的工具调用，因此必须明确其取消和拥有者资源释放契约。
+subagent 需要与其他长时间运行的工具相同的启动、收集、列出、停止、归属、通知和清理行为，但不应采用进程流语义。子会话仍是详细记录；父级只需最终答案和任务状态。后台子级的存活时间还会超过启动它的工具调用，因此必须明确其取消和拥有者 dispose（资源释放）约定。
 
 ## 决策
 
@@ -16,7 +16,7 @@ subagent 需要与其他长时间运行的工具相同的启动、收集、列
 
 后台 subagent 使用[通用后台任务运行时](../architecture/2026-06-20-generic-long-running-tool-runtime.md)。`task_output`、`task_list` 和 `task_kill` 负责收集、列出、取消、完成通知和提示词引导；系统不提供 subagent 专用的配套工具。
 
-前台调用保留其同步契约：等待提供方启动和 `run.result`；仅当状态为 `completed` 时返回最终文本；将其他终止原因映射为出错的工具结果；并且始终在返回前释放该运行。
+前台调用保留其同步约定：等待提供方启动和 `run.result`；仅当状态为 `completed` 时返回最终文本；将其他终止原因映射为出错的工具结果；并且始终在返回前对该运行执行 dispose。
 
 对于后台调用，工具会验证父级，并在调用 `ctx.tasks.start()` 前拒绝已中止的执行信号。任务运行时会在调用生产者启动器前，预检控制接口和拥有者清理。该启动器创建独立的 `AbortController` 并启动 `ctx.subagents.start()`；返回 id 之后，工具调用的信号不再拥有该子级。
 
@@ -24,14 +24,14 @@ subagent 需要与其他长时间运行的工具相同的启动、收集、列
 
 - `kind` 为 `subagent`，`label` 为模型提供的描述，`owner` 为父 agent（智能体）。
 - `cancel(reason?)` 中止任务自有的控制器。同一个信号同时覆盖尚未完成的提供方启动和已发布 run 的剩余工作。
-- `done` 等待提供方启动、子级结果和 `run.dispose()`。已完成的运行返回最终文本，已中止的运行变为 `killed`，其他停止原因变为 `failed`。启动、结果和资源释放失败会转换为失败结果，而不是被拒绝的任务 Promise。
+- `done` 等待提供方启动、子级结果和 `run.dispose()`。已完成的运行返回最终文本，已中止的运行变为 `killed`，其他停止原因变为 `failed`。启动、结果和 dispose 失败会转换为失败结果，而不是被拒绝的任务 Promise。
 - `readOutput` 不存在。任务存活期间，`task_output` 只返回状态；结算后，它以幂等方式返回最终输出。中间的子级活动仍保留在子会话中。
 
 ## 生命周期
 
-后台 subagent 归属于其父 agent，不会在拥有者关闭后持久存续。任务运行时将清理附加到对应拥有者的确切作用域。agent 资源释放会取消任务，并在 `AgentHandle.dispose()` 完成前等待启动回滚或子级资源释放，避免泄漏子 agent 和会话。
+后台 subagent 归属于其父 agent，不会在拥有者关闭后持久存续。任务运行时将清理附加到对应拥有者的确切作用域。agent dispose 会取消任务，并在 `AgentHandle.dispose()` 完成前等待启动回滚或子级 dispose，避免泄漏子 agent 和会话。
 
-完成通知会发送给启动时捕获的确切拥有者。如果拥有者清理过程已经释放了注入目标，该通知将被丢弃；生命周期保证是清理，而不是通知。
+完成通知会发送给启动时捕获的确切拥有者。如果拥有者清理过程已经对注入目标执行了 dispose，该通知将被丢弃；生命周期保证是清理，而不是通知。
 
 ## 模型引导
 
@@ -51,14 +51,14 @@ subagent 需要与其他长时间运行的工具相同的启动、收集、列
 
 agent 和日志可能以会话为作用域，但任务注册表和可预测 id 属于运行时全局范围。因此，通用拥有者防线同样适用于 subagent 和所有其他生产者。
 
-### 增量子 transcript 输出
+### 增量子 transcript（文本记录）输出
 
 将子级历史以流式方式写入父级，会模糊日志边界，并使提供方行为分化。此接口只公开最终输出；更丰富的观察应由会话或 UI 工具承担。
 
 ## 测试
 
-单元测试覆盖固定了停止原因映射、在报告前释放资源、启动与结果失败、对预中止的拒绝、从启动调用信号分离、在提供方发布前后取消、通过真实任务工具收集、无控制接口的预检防线、运行时缺失失败，以及每实例 schema 开关。快照覆盖固定了面向模型的 schema。
+单元测试锁定了停止原因映射、在报告前释放资源、启动与结果失败、对预中止的拒绝、从启动调用信号分离、在提供方发布前后取消、通过真实任务工具收集、无控制接口的预检防线、运行时缺失失败，以及每实例 schema 开关。快照测试锁定了面向模型的 schema。
 
 ## 影响
 
-父级可以并行分派慢速委派任务，并通过与 bash 共用的任务控制来收集结果。子级工作不再占用启动它的工具调用，但在收集、终止或拥有者释放之前可以继续消耗资源。提示词引导鼓励收集；拥有者清理则提供硬性生命周期边界。需要同步委派的部署可以按工具实例禁用后台模式。
+父级可以并行分派慢速委派任务，并通过与 bash 共用的任务控制来收集结果。子级工作不再占用启动它的工具调用，但在收集、终止或拥有者 dispose 之前可以继续消耗资源。提示词引导鼓励收集；拥有者清理则提供硬性生命周期边界。需要同步委派的部署可以按工具实例禁用后台模式。
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index 0cf926921b..e9e90f0c4f 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
 2026-07-20-dsh-cli-personal-config.md: c00432ba2b75cc42caf23e405c24acb33d839e7a
-2026-07-20-dsh-cli-personal-config.zh.md: b33a7fa321ca04f41e47386544ffc0f268a8b1b6
+2026-07-20-dsh-cli-personal-config.zh.md: b2fbd4b68acd92496ca2b087b172504dd93abd88
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index b33a7fa321..b2fbd4b68a 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -4,29 +4,29 @@ Status: implemented
 
 [English](2026-07-20-dsh-cli-personal-config.md) | 中文
 
-## Problem
+## 问题
 
-开发者自己的偏好——TUI 使用哪个提供方和模型、个人凭证、私有的适配器路由——除了改动已提交的文件之外无处安放。要把 TUI 示例指向个人的 Anthropic 代理 Opus 路由，只能在工作区里改 `examples/tui-agent/cordis.yml` 和 `.env`，既有提交密钥的风险，又要在每个 checkout 里重复一遍。也没有可安装的命令：想在任意项目目录里运行这个 agent，必须回到仓库根目录调用示例脚本。Loader 元数据是静态的，所以「条件组合使用 overlay」（AGENTS.md）——但 overlay 此前只以已提交的同级文件形式存在，没有机器级的层。
+开发者自己的偏好——TUI 使用哪个提供方和模型、个人凭证、私有的适配器路由——除了改动已提交的文件之外无处安放。要把 TUI 示例指向个人的 Anthropic 代理 Opus 路由，只能在工作区里改 `examples/tui-agent/cordis.yml` 和 `.env`，既有提交密钥的风险，又要在每个 checkout 里重复一遍。也没有可安装的命令：想在任意项目目录里运行这个 agent（智能体），必须回到仓库根目录调用示例脚本。Loader 元数据是静态的，所以「条件组合使用 overlay」（AGENTS.md）——但 overlay 此前只以已提交的同级文件形式存在，没有机器级的层。
 
-## Decision
+## 决策
 
-下文的各入口模式，以及个人文件的名称与位置，已被 [profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)取代：`dsh` 启动 profile，个人层变成逐 profile 与 home 级的 `cordis.patch.yml`。保留不变的是本笔记的实质：以 Harness home 作为机器级层的根目录、在随附组合之上使用 patch 语义，以及解析时的大声失败。
+下文的各入口模式，以及个人文件的名称与位置，已被 [profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)取代：`dsh` 启动 profile，个人层变成逐 profile 与 home 级的 `cordis.patch.yml`。保留不变的是本笔记的实质：以 Harness home 作为机器级层的根目录、在随附组合之上使用 patch 语义，以及解析失败时明确报错。
 
-两个耦合的部分，与 `dsh web` PR（#443）提出的 `apps/` 装配层对齐：
+两个耦合的部分，与 `dsh web` PR（Pull Request）#443提出的 `apps/` 装配层对齐：
 
-**`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 是位于 `packages/*` 库之上的产品组装层。一个 bin 负责分发默认交互式 TUI、`-p`/`--prompt` 无头轮次和 `web` 界面。TUI 以调用目录为 workspace，启动 `examples/tui-agent/cordis.yml`（或 `--config` 指定的配置）。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，并使用 tsx 的 ESM hook 运行应用；该契约由[源码启动决策](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)维护。`pnpm run demo:tui` 运行同一入口。
+**`dsh` CLI（命令行界面，`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 是位于 `packages/*` 库之上的产品组装层。一个 bin 负责分发默认交互式 TUI、`-p`/`--prompt` 无头轮次和 `web` 界面。TUI 以调用目录为 workspace，启动 `examples/tui-agent/cordis.yml`（或 `--config` 指定的配置）。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，并使用 tsx 的 ESM hook 运行应用；该约定由[源码启动决策](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)维护。`pnpm run demo:tui` 运行同一入口。
 
-**个人配置（`dsh-app-boot`）。** 个人 overlay 存放在 Harness home——`$DSH_HOME`，否则 `~/.dsh`——由共享的 [`resolveDshHome`](../architecture/2026-07-24-single-harness-home-resolver.md)（`@deepseek-ai/dsh-paths`）解析，与 skills、AGENTS.md 解析所依据的单一根目录相同。dsh 的 TUI、Web 和无头界面使用其中两个可选文件；各示例 bin 仍然逐字节按已提交的配置树启动：
+**个人配置（`dsh-app-boot`）。** 个人 overlay 存放在 Harness home——`$DSH_HOME`，否则 `~/.dsh`——由共享的 [`resolveDshHome`](../architecture/2026-07-24-single-harness-home-resolver.md)（`@deepseek-ai/dsh-paths`）解析，与 skill（技能）和 AGENTS.md 解析所依据的单一根目录相同。dsh 的 TUI、Web 和无头界面使用其中两个可选文件；各示例 bin 仍然逐字节按已提交的配置树启动：
 
 - `.env`——在调用目录的 `.env` 之后加载；`process.loadEnvFile` 从不覆盖已有值，因此优先级为环境变量 > 项目 `.env` > 个人 `.env`。
 - `config.yaml`——顶层 YAML 数组，元素为 `@cordisjs/plugin-include` 的 `PatchOptions`，用 include 自己的 `!!js` 方言解析（`loadPersonalPatches`）并传给 `boot()`，由它作为根 include 的 `patches` 转发。补丁语义与交付的 surface overlay 一致：按 id 定位的补丁替换该配置项的整个 `config`，`insert` 追加配置项，未匹配的 id 静默不执行任何操作。[仓库插件集成](2026-07-30-config-only-repository-plugins.md)通过一个已交付配置项，使精确 GitHub 源列表成为纯配置选择。
-- 文件缺失即无 overlay；文件存在但不可读、不可解析或非数组则在启动时抛出（配置错误响亮失败，绝不静默跳过）。
+- 文件缺失即无 overlay；文件存在但不可读、不可解析或非数组则在启动时抛出（配置错误会明确导致启动失败，绝不静默跳过）。
 
-PTY 冒烟测试的启动器把 `$DSH_HOME` 隔离到每个测试自己的目录，与它已有的 `DSH_AGENTS_HOME` 隔离方式完全一致，开发者真实的个人 overlay 不可能泄漏进 fixture；只有 dsh CLI 读取个人配置，因此其他测试启动器无需改动。
+PTY 冒烟测试的启动器把 `$DSH_HOME` 隔离到每个测试自己的目录，与它已有的 `DSH_AGENTS_HOME` 隔离方式完全一致，开发者真实的个人 overlay 不可能泄漏进 fixture（测试前置数据）；只有 dsh CLI 读取个人配置，因此其他测试启动器无需改动。
 
-TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人配置路径。每次新增、变更或移除都会以事务方式通过启动器自己的组合闭包重新组合完整 patch 列表，因此新的个人 patch 落在启动时相同的层次位置。YAML 无效或 Loader 候选被拒时，最后一个可用树保持活动状态，并广播 `hmr/config-update-failed(filename, Error)`；无头界面只在启动时读取该文件。Include 在已提交配置文件刷新时也会重新应用其 patch（见[配置热重载韧性 Agent Note](../bug-fix/2026-07-20-config-hot-reload-resilience.md)）。
+TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人配置路径。每次新增、变更或移除都会以事务方式通过启动器自己的组合闭包重新组合完整 patch 列表，因此新的个人 patch 落在启动时相同的层次位置。YAML 无效或 Loader 候选被拒时，最后一棵可用的配置树保持活动状态，并广播 `hmr/config-update-failed(filename, Error)`；无头界面只在启动时读取该文件。Include 在已提交配置文件刷新时也会重新应用其 patch（见[配置热重载韧性 Agent Note](../bug-fix/2026-07-20-config-hot-reload-resilience.md)）。
 
-## Alternatives considered
+## 曾考虑的替代方案
 
 **另设一个 `bin/dsh` 包装脚本并由其占用 `dsh` 名称。** 否决，因为 `apps/cli` 是统一的产品 CLI，负责分发默认 TUI、无头和 Web 界面。两个相互竞争的入口会在 `$PATH` 和产品身份上冲突。
 
@@ -34,11 +34,11 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 
 **个人完整 `cordis.yml` 去 include 请求的配置。** 否决：个人文件将不得不写死叶子配置的路径，而该路径随 checkout 变化；补丁反转了依赖方向，bin 仍然选择配置树，个人层只做修正。
 
-**把个人补丁深合并进配置项配置。** 否决：会使补丁语义与已提交 overlay 和 vendor 的 include 分叉；整个 `config` 替换已是成文契约。
+**把个人补丁深合并进配置项配置。** 否决：会使补丁语义与已提交 overlay 和 vendor 的 include 分叉；整个 `config` 替换已是成文约定。
 
-**用环境变量开关代替存在性判断。** 否决：默认关闭的个人配置永远不会被用起来；存在即生效加上每个测试的显式隔离，让实际运行获得 overlay、测试获得封闭性。
+**用环境变量开关代替存在性判断。** 否决：默认关闭的个人配置永远不会被用起来；存在即生效加上每个测试的显式隔离，让实际运行获得 overlay、测试保持隔离。
 
-## Consequences
+## 后果
 
 - 在任意目录运行 `dsh`（以及 `pnpm run demo:tui`），无需修改 checkout，即可应用个人提供方、模型、仓库插件和其他 Loader 配置项；已针对个人 Anthropic 代理与 Opus 4.8 端到端验证，包括一次 bash 工具往返。
 - 由于按 id 定位的补丁替换整个 `config`，个人覆盖必须复述它保留的基础字段，并可能随基础配置项形态变化而漂移；诊断手段是 loader 的「配置项未找到/名称不匹配」警告和 [`dsh --dump-config`](../../../../apps/cli/README.md#profiles)（打印这些补丁合成出的配置树）。
@@ -46,6 +46,6 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 - `dsh-app-boot` 依赖 `js-yaml`，并直接导入 include 的 `!!js` YAML 方言（`entryListSchema`）；与 `apps/cli` 一样依赖 `@deepseek-ai/dsh-paths` 以获取 `resolveDshHome`。
 - 只有长时间运行的 TUI 和 Web 进程进行实时监视。无头自动化使用确定性的启动配置，退出时不会保留 watcher。
 
-## Testing
+## 测试
 
-`packages/boot/app-boot/tests/user-patches.spec.ts` 固定解析、启动时应用、确切路径的新增／失败／恢复／移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`apps/cli/tests/built-bin.e2e.ts` 启动真实 dsh bin 并基于 profile 端到端验证实时 patch 层。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
+`packages/boot/app-boot/tests/user-patches.spec.ts` 固定解析、启动时应用、确切路径的新增、失败、恢复、移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`apps/cli/tests/built-bin.e2e.ts` 启动真实 dsh bin 并基于 profile 端到端验证实时 patch 层。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
index 1d93b7f440..98d84c8e19 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
 2026-07-21-continuable-background-subagents.md: e37abdd798242bc1086754e86a85ef46c08e59a3
-2026-07-21-continuable-background-subagents.zh.md: 799e1914bdeb571dc697652081be6b0170768655
+2026-07-21-continuable-background-subagents.zh.md: 33bf9a1b7e4568ba0e4b2ea99ac590df9440c93f
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
index 799e1914bd..33bf9a1b7e 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-21-continuable-background-subagents.md) | 中文
 
-本记录已由[可继续的 subagent](2026-07-28-continuable-subagent-conversations.md)取代——后者以一个持久 Session 加至多一个进程内 Activation（驻留期）替换了其基于 Task 的 activation 模型、路由、取消和持久性语义。其服务放置与提供方功能策略此前已由[将 subagent 控制合并到 subagent 服务](../simplification/2026-07-26-merge-subagent-control-service.md)和[以意图命名的 subagent 继续执行操作](../simplification/2026-07-27-intent-named-subagent-continuation-operations.md)取代。仅持久 child 会话与 descriptor 的设计依据仍然有效。
+本记录已由[可继续的 subagent](2026-07-28-continuable-subagent-conversations.md)取代——后者以一个持久会话加至多一个进程内 Activation（激活）替换了其基于 Task 的 activation 模型、路由、取消和持久性语义。其服务放置与提供方能力策略此前已由[将 subagent 控制合并到 subagent 服务](../simplification/2026-07-26-merge-subagent-control-service.md)和[以意图命名的 subagent 继续执行操作](../simplification/2026-07-27-intent-named-subagent-continuation-operations.md)取代。仅持久 child 会话与 descriptor 的设计依据仍然有效。
 
 ## 问题
 
@@ -14,9 +14,9 @@ Task、run 和 child 会话具有不同的生命周期。一个 Task 表示一
 
 ## 决策
 
-一个可继续的后台 subagent，是由一系列 Task 支撑的短期激活共同组成的持久化 child 会话。child session id、transcript（文本记录）、谱系及声明的组合配置均保留在持久化存储中。每次初始激活或恢复激活都会创建新的 Task、`AgentHandle` 和 `SubagentRun`，驱动一个轮次、收集结果，并在 Task 进入终态前 dispose 该 run。
+一个可继续的后台 subagent，是由一系列 Task 支撑的激活共同组成的持久化 child 会话。child 会话 id、transcript（文本记录）、谱系及声明的组合配置均保留在持久化存储中。每次初始激活或恢复激活都会创建新的 Task、`AgentHandle` 和 `SubagentRun`，驱动一个轮次、收集结果，并在 Task 进入终态前 dispose 该 run。
 
-Task 的结果和取消边界属于 child 激活，不属于为该激活提供第一条消息的调用方。Task 访问根据 parent session id 授权，而 Task 注册表仍保留当前存活的精确 parent Agent 实例，用于通知与资源清理。因此，只要 parent 仍是运行时 owner，parent 消息和用户消息便会共享同一个激活结果：
+Task 的结果和取消边界属于 child 激活，不属于为该激活提供第一条消息的调用方。Task 访问根据 parent 会话 id 授权，而 Task 注册表仍保留当前存活的精确 parent Agent 实例，用于通知与资源清理。因此，只要 parent 仍是运行时 owner，parent 消息和用户消息便会共享同一个激活结果：
 
 ```text
 durable child Session
@@ -25,35 +25,35 @@ durable child Session
   activation 3: Task 3 -> SubagentRun -> AgentHandle -> dispose
 ```
 
-前台委派保持一次性行为。继续执行覆盖后台的进程内 spawn 和 fork child。每个 `tool-subagent` 实例都会选择 `backgroundMode: 'one-shot' | 'continuable'`；配置为可继续模式时，所挂载提供方必须具备 `resume` 功能，而可恢复的提供方仍可采用一次性后台策略。在下述 ACP（Agent Client Protocol）后续工作完成前，ACP child 仍保持一次性行为。
+前台委派保持一次性行为。继续执行覆盖后台的进程内 spawn 和 fork child。每个 `tool-subagent` 实例都会选择 `backgroundMode: 'one-shot' | 'continuable'`；配置为可继续模式时，所挂载提供方必须具备 `resume` 能力，而可恢复的提供方仍可采用一次性后台策略。在下述 ACP（Agent Client Protocol）后续工作完成前，ACP child 仍保持一次性行为。
 
-`ctx.subagents` 是唯一的公开服务。普通 `start` 不感知 child 集合、Activation 与持久化：它校验提供方功能、解析一次性描述符、分发一个 run、观察 run 生命周期，并返回由持有方负责的 run。注入的内部继续执行管理器负责管理稳定的 child id、可继续描述符持久化与查找、Activation 生命周期，以及通过 `startContinuable` 和 `followup` 进行的路由；管理器自行组合 child 之前，提供方通过私有闭包提供准备数据。按提供方绑定的 `@deepseek-ai/dsh-tool-subagent` 插件及面向用户的适配器调用这些意图操作来处理可继续后台工作；前台和一次性后台委派使用普通 `start`。全局命名的模型工具是 `@deepseek-ai/dsh-tool-subagent-control` 中的可选轻量适配器，它是否存在不会决定是否启动可继续工作。parent 到 child 的枚举、一次性／可继续模式共享的描述符身份与 `list_agents` 属于[持久化 subagent 目录](2026-07-22-durable-subagent-catalog-and-list-agents.md)。
+`ctx.subagents` 是唯一的公开服务。普通 `start` 不感知 child 集合、Activation 与持久化：它校验提供方能力、解析一次性描述符、分发一个 run、观察 run 生命周期，并返回由持有方负责的 run。注入的内部继续执行管理器负责管理稳定的 child id、可继续描述符持久化与查找、Activation 生命周期，以及通过 `startContinuable` 和 `followup` 进行的路由；管理器自行组合 child 之前，提供方通过私有闭包提供准备数据。按提供方绑定的 `@deepseek-ai/dsh-tool-subagent` 插件及面向用户的适配器调用这些意图操作来处理可继续后台工作；前台和一次性后台委派使用普通 `start`。全局命名的模型工具是 `@deepseek-ai/dsh-tool-subagent-control` 中的可选轻量适配器，它是否存在不会决定是否启动可继续工作。parent 到 child 的枚举、一次性／可继续模式共享的描述符身份与 `list_agents` 属于[持久化 subagent 目录](2026-07-22-durable-subagent-catalog-and-list-agents.md)。
 
 ### Task 与取消的所有权
 
 初始后台委派请求 `ctx.subagents` 启动 child 并注册其 Task。可继续提供方只有在确认本次激活的最终会话状态已持久化后，才会返回成功的 run 结果。Task 结算流程等待该结果，通过继续执行管理器的结算路径调用 `run.dispose()`，然后才记录 `TaskOutcome`；`task_kill` 中止活跃 run，其结算路径仍会 dispose 该 run。因此，终态 Task 会留下持久化 child 会话，但不会留下存活的 child agent。必需的持久性检查点若没有已安装的监听器或任一监听器失败，run 会以稳定错误码 `DURABILITY_FAILED` 拒绝，并将检查点失败保留为失败原因；管理器会记录失败的 Task，其详情说明最新状态未确认已持久化，因此恢复时可能不可用或已陈旧。
 
-后续每个轮次都会创建另一个 Task。该轮 producer 持有的执行资源仅服务于这次激活，不属于 child 会话。它只会到达一次终态、只产生一个结果，也不会重新打开。Task 注册表中当前注册的那个存活 parent agent 实例仍是其 owner：dispose 该实例会取消、等待并移除其 Task。Task API 会授权 session id 与该 owner 匹配的调用方，但 id 相同的替代实例不会成为通知或资源清理目标。这一设计保留 `settleRun()` 契约，并使 Task 所拥有的存活 child 数量受并发工作量限制，而不是随历史会话数量增长。
+后续每个轮次都会创建另一个 Task。该轮 producer 持有的执行资源仅服务于这次激活，不属于 child 会话。它只会到达一次终态、只产生一个结果，也不会重新打开。Task 注册表中当前注册的那个存活 parent agent 实例仍是其 owner：dispose 该实例会取消、等待并移除其 Task。Task API 会授权 session id 与该 owner 匹配的调用方，但 id 相同的替代实例不会成为通知或资源清理目标。这一设计保留 `settleRun()` 约定，并使 Task 所拥有的存活 child 数量受并发工作量限制，而不是随历史会话数量增长。
 
 用户界面适配器打开 child 会话时，只读取持久化 transcript，不会仅为展示而恢复 agent。用户输入通过继续执行管理器，启动或加入与 parent 输入相同的 Task 激活。由用户启动的 Task 会保留当前加载的精确 parent Agent 作为通知目标，`task_output` 仍是唯一结果路径。只要 Task 尚未标记为已报告，现有完成监听器最多注入一条主动通知；`kill`、终态读取或终态等待都可能将其标记为已报告，并抑制这条通知。因此，仅允许在该 parent 实例保持存活时进行用户交互。可以比 parent 存活更久、并将结论显式合并回去的用户自有会话属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)，不属于这一由 Task 持有的生命周期。
 
 如果没有附加 Task 控制面，`TaskService.start()` 会拒绝 producer。因此，接受 child 输入的用户界面适配器必须附加 Task 控制面，或运行于加载了 `@deepseek-ai/dsh-tool-tasks` 的部署中；仅加载 Task 服务并不足够。SDK 生成的 spawn 与 fork 组合在挂载 subagent 工具时，也会挂载 `@deepseek-ai/dsh-tasks-local` 与 `@deepseek-ai/dsh-tool-tasks`。这项依赖是 parent 和用户启动的激活共用 Task 结果、取消和通知路径所付出的代价。
 
-取消始终作用于当前完整激活。如果用户消息和 parent 消息已经加入同一个轮次，任一调用方发起取消都会中止该轮次、dispose 其 run，并将对应 Task 结算为 `killed`；这些消息没有独立的结果或取消权。`followup()` 要求调用方提供信号；若在线 steering 正在等待请求准入时该信号被中止，激活自有的 controller 会被中止，以便提供方丢弃待处理消息，并且该调用仅在子 agent 完全停稳后结算。若需要独立取消，后续消息必须另起轮次，而不能加入当前轮次。
+取消始终作用于当前完整激活。如果用户消息和 parent 消息已经加入同一个轮次，任一调用方发起取消都会中止该轮次、dispose 其 run，并将对应 Task 结算为 `killed`；这些消息没有独立的结果或取消权。`followup()` 要求调用方提供信号；若在线 steering（中途引导）正在等待请求准入时该信号被中止，激活自有的 controller 会被中止，以便提供方丢弃待处理消息，并且该调用仅在子 agent 完全停稳后结算。若需要独立取消，后续消息必须另起轮次，而不能加入当前轮次。
 
 从持久化存储恢复的 Task 会在查找描述符或等待任何提供方操作之前，创建由本次激活持有的 `AbortController`；描述符查找、直接 parent 鉴权和描述符归并都在该 Task producer 内部执行，因此同一信号覆盖它们，其失败会将该 Task 结算为 `failed`。对于不接受信号的持久化调用，可以让底层 I/O 执行完毕；但继续执行管理器必须在每次这类 await 返回后重新检查取消状态，如已取消，之后不得开始或发布任何 child 工作。在 Agent 发布前收到中止信号时，提供方必须先回滚其创建事务并达到完全停稳状态，然后才让恢复调用以拒绝结束。Agent 发布后，提供方必须消除创建期间移交取消信号时的竞态，在返回前将同一信号附加到存活 run；之后取消会停止 child 轮次。即使提供方的恢复调用尚未返回 `SubagentRun`，`task_kill` 与对确切 owner 实例的 dispose 仍通过这条路径生效。Task 结算会等待回滚或 run dispose 完成，只有在激活完全停稳后才记录 `killed`。
 
 ### 活跃 run 关联
 
-继续执行管理器在进程内维护 child session id 到当前 Task 的关联，并在提供方发布后将 run 填入该关联。它会在等待提供方 start 或 resume 之前安装 Task 关联，填入返回的 run，并且只在 run dispose 完成且 Task 终态发布后才移除该关联。该关联只用于让 parent 发送方和用户发送方找到同一次激活；它不是持久化 child 目录、公开的 `ManagedSubagent`、准入预留或 run 状态机。
+继续执行管理器在进程内维护 child 会话 id 到当前 Task 的关联，并在提供方发布后将 run 填入该关联。它会在等待提供方 start 或 resume 之前安装 Task 关联，填入返回的 run，并且只在 run dispose 完成且 Task 终态发布后才移除该关联。该关联只用于让 parent 发送方和用户发送方找到同一次激活；它不是持久化 child 目录、公开的 `ManagedSubagent`、准入预留或 run 状态机。
 
-对于可继续 child 的初始激活，继续执行管理器会在创建 Task 前分配稳定的 child session id，并将其作为 `SubagentProviderStartRequest.continuation` 传递；进程内 spawn 和 fork 会发布这一确切 id，而不是在内部另行分配。普通 `SubagentStartRequest` 不含 continuation 字段。后台工具返回规范的 `{ kind: 'background', taskId, subagentId }`，渲染为 `started subagent <childId> as task <taskId>`。child id 在多次激活中始终指代同一个持久化对话，Task id 则只指代当前激活。初始 Task 失败，或进程在 child 首次 flush 之前退出，都可能留下一个 **unmaterialized child**：调用方持有 child id，但不存在持久化 header 和描述符。后续按 id 的操作会报告该 id 不可用（已启动的 Task 会带着该详情失败），持久化枚举也不会列出它。
+对于可继续 child 的初始激活，继续执行管理器会在创建 Task 前分配稳定的 child 会话 id，并将其作为 `SubagentProviderStartRequest.continuation` 传递；进程内 spawn 和 fork 会发布这一确切 id，而不是在内部另行分配。普通 `SubagentStartRequest` 不含 continuation 字段。后台工具返回规范的 `{ kind: 'background', taskId, subagentId }`，渲染为 `started subagent <childId> as task <taskId>`。child id 在多次激活中始终指代同一个持久化对话，Task id 则只指代当前激活。初始 Task 失败，或进程在 child 首次 flush 之前退出，都可能留下一个 **unmaterialized child**：调用方持有 child id，但不存在持久化 header 和描述符。后续按 id 的操作会报告该 id 不可用（已启动的 Task 会带着该详情失败），持久化枚举也不会列出它。
 
 每个可继续 child 轮次都通过这条由 Task 支撑的路径准入。非终态 Task 是唯一受支持的存活激活；不存在激活时，其 run 已被 dispose，持久化 child 可以恢复。在路由任何按 id 的操作之前，继续执行管理器会同步将自身关联与 `ctx.agents.get(childId)` 比较。如果注册表中的 Agent 没有关联，或者它与所关联的 `run.localAgent` 不同，就属于所有权冲突：管理器会失败，而不会接管 idle Agent 或附加未受跟踪的轮次。二者均不存在时，可以从持久化存储恢复；如果检查后又有竞争方发布，仍会在 Agent 注册表的冲突边界上失败。
 
-系统依据 Task 关联进行路由。运行中的 Task 通过 run 可选且提供确认语义的 `SubagentRun.steer` 功能接收在线消息。Task 不存在时，系统创建新 Task，并从持久化存储恢复 child。进程内 spawn 和 fork 会先同步要求 child 处于 `running` 状态，并拒绝已经提交结构化捕获的 child；随后调用 `Agent.steer()`，等待该消息专属的准入回执。默认循环会为每个 steering 项目提供一份归属于该消息的回执；只有在 `agent/step` 与异步提示词组装成功后，系统追加该消息、捕获不可变的请求历史并提交 `step/start`，回执才会解析为 `admitted`。终止型轮次策略、取消和 dispose（资源释放）会将待处理回执解析为 `rejected`。非终止型轮次关闭可以把待处理 steering 带入后续排队轮次，但不会确认其准入。提供方必须在调用 `Agent.steer()` 前检查存活状态，避免其 idle 路径在观察到的 run 之外启动轮次。如果查找关联之后、请求获准之前，Task 结算或终止策略率先完成，`steer()` 会拒绝，`send_message` 会报告消息未送达，而且该次调用不会改用从持久化存储恢复路径；在 Task 终态发布后重试，才可能启动下一次激活。
+系统依据 Task 关联进行路由。运行中的 Task 通过 run 可选且提供确认语义的 `SubagentRun.steer` 能力接收在线消息。Task 不存在时，系统创建新 Task，并从持久化存储恢复 child。进程内 spawn 和 fork 会先同步要求 child 处于 `running` 状态，并拒绝已经提交结构化捕获的 child；随后调用 `Agent.steer()`，等待该消息专属的准入回执。默认循环会为每个 steering 项目提供一份归属于该消息的回执；只有在 `agent/step` 与异步提示词组装成功后，系统追加该消息、捕获不可变的请求历史并提交 `step/start`，回执才会解析为 `admitted`。终止型轮次策略、取消和 dispose 会将待处理回执解析为 `rejected`。非终止型轮次关闭可以把待处理 steering 带入后续排队轮次，但不会确认其准入。提供方必须在调用 `Agent.steer()` 前检查存活状态，避免其 idle 路径在观察到的 run 之外启动轮次。如果查找关联之后、请求获准之前，Task 结算或终止策略率先完成，`steer()` 会拒绝，`send_message` 会报告消息未送达，而且该次调用不会改用从持久化存储恢复路径；在 Task 终态发布后重试，才可能启动下一次激活。
 
-继续执行管理器不会串行化两个通过其外部路径同时争抢已停止 child 的调用方，也不会为结果产生与 dispose 之间的阶段单独建立 settling 状态。在 producer 首次 await 之前同步安装的关联，使本进程内每个 child 只准入一次激活——resume 加载期间竞争的 `followup` 会观察到待处理的激活并显式失败——而绕开该关联的发布仍会在 Agent 注册表相同会话的冲突边界上失败。发送也可能因与启动、取消、完成或清理发生竞态而失败。这些限制是明确的，而非隐藏在更大的生命周期抽象之后。
+继续执行管理器不会串行化两个通过其外部路径同时争抢已停止 child 的调用方，也不会为结果产生与 dispose 之间的阶段单独建立 settling 状态。在 producer 首次 await 之前同步安装的关联，使本进程内每个 child 一次只准入一个激活——resume 加载期间竞争的 `followup` 会观察到待处理的激活并显式失败——而绕开该关联的发布仍会在 Agent 注册表相同会话的冲突边界上失败。发送也可能因与启动、取消、完成或清理发生竞态而失败。这些限制是明确的，而非隐藏在更大的生命周期抽象之后。
 
 ### 面向模型的 `send_message`
 
@@ -67,25 +67,25 @@ durable child Session
 
 发送到现有 run 的消息没有独立结果，其效果体现在当前 Task 的最终结果中。启动的后续轮次具有新 Task 的结果，并使用现有 `task_output` 读取路径。subagent 层不会再注入第二份完成通知。
 
-用户输入使用同一个 `followup` 操作。UI 可以展示 child transcript 和当前 Task 状态，取消操作则以已加载 parent 作为调用方访问 Task 服务。工具 schema 与 UI 适配器消费同一个服务契约，不建立彼此独立的执行路径。
+用户输入使用同一个 `followup` 操作。UI 可以展示 child transcript 和当前 Task 状态，取消操作则以已加载 parent 作为调用方访问 Task 服务。工具 schema 与 UI 适配器消费同一个服务约定，不建立彼此独立的执行路径。
 
 ### 持久化 child handle 与从持久化存储恢复
 
-继续执行管理器在创建 Task 前，通过 seam 的 `snapshotSubagentDescriptor()`（基于 [`snapshotJsonValue`](../../../../packages/core/session/src/json.ts) 构建）对每项描述符输入建立快照；这一边界与 Agent 消息现有的分离式无损 JSON 边界一致。作用于 child 作用域的 setup contribution——由进程内驱动前置安装的一次性 `agent/prompt-submit` 监听器——会在下游 prompt admission 能够阻止请求或抛出异常之前追加一个对模型隐藏的 `subagent/descriptor` 事件。admission 获准后才会开启 child 的初始轮次；admission 被拒绝时，描述符会作为轮次前的仅日志事实保留，并由该 activation 最终的必需检查点持久化。该事件不携带 `surfaceOp`，不进入模型历史，并在压缩替换 surface 历史时继续保留。只有在加载已知 child id 对应的 child 会话后，能在该 child 自身的后缀中（`seedLength` 之后，因此 fork seed 不会泄露祖先的描述符）得到受支持的描述符，且会话 header 将调用方标识为直接 parent 时，该 id 才可恢复。
+继续执行管理器在创建 Task 前，通过 seam 的 `snapshotSubagentDescriptor()`（基于 [`snapshotJsonValue`](../../../../packages/core/session/src/json.ts) 构建）对每项描述符输入建立快照；这一边界与 Agent 消息现有的分离式无损 JSON 边界一致。作用于 child 作用域的 setup contribution——由进程内驱动前置安装的一次性 `agent/prompt-submit` 监听器——会在下游 prompt admission 能够阻止请求或抛出异常之前追加一个对模型隐藏的 `subagent/descriptor` 事件。admission 获准后才会开启 child 的初始轮次；admission 被拒绝时，描述符会作为轮次前的仅日志事实保留，并由该 activation 最终的必需检查点持久化。该事件不携带 `surfaceOp`，不进入模型历史，并在压缩（compaction）替换 surface 历史时继续保留。只有在加载已知 child id 对应的 child 会话后，能在该 child 自身的后缀中（`seedLength` 之后，因此 fork seed 不会泄露祖先的描述符）得到受支持的描述符，且会话 header 将调用方标识为直接 parent 时，该 id 才可恢复。
 
-版本化描述符的可继续分支（[descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts) 中的 `SUBAGENT_DESCRIPTOR_VERSION`）携带 `mode: 'continuable'`、subagent 提供方名称、已解析的 child `agentOptions.provider` 和 `agentOptions.model`，以及可选的 `persona` 与 `toolFilter`。它不会对可通过声明合并扩展的 `AgentOptions` 对象建立快照：与此无关的扩展值不会仅因无法表示为 JSON 而导致继续执行失败。描述符会特意省略 `subagentDepth`；从持久化存储恢复时，系统依赖持久化 header 中的 `delegationDepth`，而不根据描述符重建深度。`outputSchema` 属于单次激活的结果契约，不属于持久化 child 组合配置。child header 仍是 child id、`cwd`、`parentSession`、`seedLength` 和 `delegationDepth` 的权威信息，持久化 child transcript 则负责保存 fork seed 和后续历史。[`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) 会在 header 值和运行时值中取最大值，因此重建后的运行时选项可以加深持久化值，但绝不能降低它，恢复后的 child 无法重新获得顶层委派预算。
+版本化描述符的可继续分支（[descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts) 中的 `SUBAGENT_DESCRIPTOR_VERSION`）携带 `mode: 'continuable'`、subagent 提供方名称、已解析的 child `agentOptions.provider` 和 `agentOptions.model`，以及可选的 `persona` 与 `toolFilter`。它不会对可通过声明合并扩展的 `AgentOptions` 对象建立快照：与此无关的扩展值不会仅因无法表示为 JSON 而导致继续执行失败。描述符会特意省略 `subagentDepth`；从持久化存储恢复时，系统依赖持久化 header 中的 `delegationDepth`，而不根据描述符重建深度。`outputSchema` 属于单次激活的结果约定，不属于持久化 child 组合配置。child header 仍是 child id、`cwd`、`parentSession`、`seedLength` 和 `delegationDepth` 的权威信息，持久化 child transcript 则负责保存 fork seed 和后续历史。[`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) 会在 header 值和运行时值中取最大值，因此重建后的运行时选项可以加深持久化值，但绝不能降低它，恢复后的 child 无法重新获得顶层委派预算。
 
 从持久化存储恢复不能依赖 `SubagentRun` 的可选方法，因为该 run 已被 dispose，并且进程重启后不会保留。run 表示一次可 dispose 的激活，只暴露作用于当前激活的操作。`SubagentRun.steer?()` 这一名称明确指代提供确认语义且仅适用于在线消息的功能，以免该功能与服务编排或面向模型的工具混淆。
 
-内部继续执行管理器的恢复路径会加载已知 child 会话、归并其描述符、根据持久化的 `parentSession` 鉴权，并在其创建的 Task 内部运行。它通过私有服务闭包传递完全解析的 `SubagentProviderResumeRequest`，其中包含由 Task 持有的取消信号；该闭包只负责在检查提供方功能后进行分发，并执行 `start` 所使用的普通 run 生命周期观察。选中的 `SubagentProvider.resume?()` 负责传输相关的重建（进程内：在当前加载的 parent 作用域下执行 `parent.ctx.agents.resume`），并返回一个新 run。提供方是否存在该方法本身就是继续执行功能，无需额外功能标志。`SubagentService.followup()` 在关联 run 的 `steer?()` 操作与该持久化恢复路径之间做出选择。私有的提供方分发与提供方本身都不会枚举持久化 child 或关联 Task。
+内部继续执行管理器的恢复路径会加载已知 child 会话、归并其描述符、根据持久化的 `parentSession` 鉴权，并在其创建的 Task 内部运行。它通过私有服务闭包传递完全解析的 `SubagentProviderResumeRequest`，其中包含由 Task 持有的取消信号；该闭包只负责在检查提供方能力后进行分发，并执行 `start` 所使用的普通 run 生命周期观察。选中的 `SubagentProvider.resume?()` 负责传输相关的重建（进程内：在当前加载的 parent 作用域下执行 `parent.ctx.agents.resume`），并返回一个新 run。提供方是否存在该方法本身就是继续执行功能，无需额外功能标志。`SubagentService.followup()` 在关联 run 的 `steer?()` 操作与该持久化恢复路径之间做出选择。私有的提供方分发与提供方本身都不会枚举持久化 child 或关联 Task。
 
 后台工具会在调用 `TaskService.start()` 前校验描述符输入并建立快照。同步校验失败会拒绝工具调用，且不会创建 Task。除此之外，工具会立即返回 child id 和 Task id，不等待 child 发布或描述符持久化完成。进程内可继续提供方会在 child 进入 idle 后、读取结果之前执行最终的 `SessionStore.flush()`；返回 `true` 表示至少有一个持久性监听器参与，返回 `false` 表示必需的检查点失败，而拒绝则携带监听器失败。此操作会在 child 仍存活时重试循环中失败的检查点。如果最终确认失败，提供方会拒绝而不返回未经确认的输出，继续执行管理器会 dispose 该 run，已经创建的 Task 会结算为 `failed`，其详情包含持久性诊断。最终确认期间发生取消时，尚未发布的激活结果由取消操作接管；即使 child 轮次已记录为完成，或之后的检查点失败，也不能取代 Task 的 `killed` 结果。前台一次性运行仍保留循环仅尽力执行检查点的行为。进程内 spawn 和 fork 会在当前已加载的 parent 作用域下重建组合配置。恢复 fork 时只加载 child 自己的持久化 transcript，其中已经包含初始创建时捕获的已完成轮次前缀；系统绝不会再次 fork parent 更新后的历史。恢复 parent 不会立即恢复其 child。
 
-TODO（ACP 继续执行）：将远端 ACP session id 作为提供方专用描述符数据持久化，并实现 `AcpProvider.resume?()`，依次执行 spawn、initialize、`loadSession` 和 prompt。初始 ACP run 必须检查 `initialize.agentCapabilities.loadSession`，恢复后的每个进程必须使用同一个持久化后端；`loadSession` 回放的历史消息不得计入新激活的输出。由于 ACP 的加载支持是按 child 协商的，不能仅根据提供方是否存在该方法来确定，因此该后续工作还必须定义 start 结果如何声明单个 child 支持继续执行，之后才能将 ACP child 写入持久化目录。
+TODO（ACP 继续执行）：将远端 ACP 会话 id 作为提供方专用描述符数据持久化，并实现 `AcpProvider.resume?()`，依次执行 spawn、initialize、`loadSession` 和 prompt。初始 ACP run 必须检查 `initialize.agentCapabilities.loadSession`，恢复后的每个进程必须使用同一个持久化后端；`loadSession` 回放的历史消息不得计入新激活的输出。由于 ACP 的加载支持是按 child 协商的，不能仅根据提供方是否存在该方法来确定，因此该后续工作还必须定义 start 结果如何声明单个 child 支持继续执行，之后才能将 ACP child 写入持久化目录。
 
 ### 结果与通知所有权
 
-每次可继续 child 激活都恰好拥有一个 Task 和一个 `TaskOutcome`，无论第一条消息由 parent 还是用户提供。只要 Task 尚未标记为已报告，通用 Task 报告契约最多会向保留的 parent owner 注入一条主动完成通知；读取、等待和取消都可能抑制该通知。发送到运行中激活的消息会加入该激活，不会创建第二个 Task 或第二份结果。child transcript 是面向用户的详细记录；Task 输出是面向 parent 的最终结果。
+每次可继续 child 激活都恰好拥有一个 Task 和一个 `TaskOutcome`，无论第一条消息由 parent 还是用户提供。只要 Task 尚未标记为已报告，通用 Task 报告约定最多会向保留的 parent owner 注入一条主动完成通知；读取、等待和取消都可能抑制该通知。发送到运行中激活的消息会加入该激活，不会创建第二个 Task 或第二份结果。child transcript 是面向用户的详细记录；Task 输出是面向 parent 的最终结果。
 
 Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可在重启后恢复，但不会恢复中断的 Task、其结果或通知。持久化 Task 恢复属于另一个问题。
 
@@ -95,7 +95,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 
 **允许用户轮次不使用 Task。** parent 消息加入此类轮次后，没有对应的 Task 结果或完成通知；UI 取消对 parent 所发消息的影响也不明确。让每次激活都拥有一个 Task，可使完成与取消成为 child 轮次的属性，而不是初始调用方的属性。
 
-**在 child 会话整个生命周期内复用一个 Task。** 终态 Task 无法自然地再次进入运行状态，一个结果也无法表示多个轮次。每次激活创建新 Task 可以保留通用 Task 契约。
+**在 child 会话整个生命周期内复用一个 Task。** 终态 Task 无法自然地再次进入运行状态，一个结果也无法表示多个轮次。每次激活创建新 Task 可以保留通用 Task 约定。
 
 **为每条消息创建 Task。** 发送到现有 run 的消息会加入已有轮次，不产生独立的最终结果；为这类消息创建 Task，会重复当前 Task，或报告一个它并不拥有的结果。只有启动新激活的消息才会创建 Task。
 
@@ -109,7 +109,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 
 ## 测试
 
-- `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述契约。
+- `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop（智能体循环）、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述约定。
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` 固定 `send_message` 的 schema、coordinator 来源标记、两种路由渲染、未送达失败、无 agent 时的拒绝，以及 HMR（热模块替换）dispose。
 - `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 覆盖配置的后台路由：可继续模式要求提供方可恢复，并在不要求 `send_message` 的情况下返回两个 id；即使提供方可以恢复，一次性模式仍保持普通的 Task 确认消息。
 - `packages/scaffold/helper/tests/project.spec.ts` 固定生成的 spawn 与 fork 组合中的 Task 服务及面向模型的 Task 控制工具。
@@ -123,5 +123,5 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 - 活跃 run 关联只能协调一个运行时。多个进程同时恢复时不会串行化；此类部署需要持久化层的租约或 compare-and-set 操作。
 - 用户交互要求作为 owner 的那个精确 parent Agent 实例保持存活，因为 dispose owner 会取消并移除其 Task。用户交互还要求附加 Task 控制面。若要单独与 child 交互，后续必须将 Task 访问所有权与持久化通知目标分离。
 - 后台工具会在 child 发布和描述符持久化之前返回 child id 和 Task id。启动失败、最终持久性确认失败，或进程在 child 首次 flush 之前退出，都会使 Task 失败，并可能留下 unmaterialized 或陈旧的 child id；按 id 的控制操作会将缺失状态报告为不可用，而不会追溯修改工具确认消息。
-- 将显式组合字段持久化到 child 日志后，其无损 JSON 与兼容性契约便成为恢复契约的一部分。后续如需支持其他组合配置输入，必须明确更改描述符版本，不能隐式持久化可通过声明合并扩展的 `AgentOptions` 字段。
+- 将显式组合字段持久化到 child 日志后，其无损 JSON 与兼容性约定便成为恢复约定的一部分。后续如需支持其他组合配置输入，必须明确更改描述符版本，不能隐式持久化可通过声明合并扩展的 `AgentOptions` 字段。
 - Task 记录和活跃 run 关联位于进程内，而 child 会话具有持久性。重启会恢复会话，但不会恢复进行中的工作或其 Task 通知。
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
index e4df6863da..5e4e651093 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
 2026-07-22-durable-subagent-catalog-and-list-agents.md: 61bda2a52f2ea5db0a582fe668643a13b967f091
-2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: a2bc36200d8c67b8da9dd3d55ea4179baa72e691
+2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: fb60e63f23fae3146963e0fe4a7df44d0b497281
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
index a2bc36200d..fb60e63f23 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
@@ -1,4 +1,4 @@
-# Agent Note（agent 决策记录）：持久化 subagent 目录与 list_agents
+# Agent Note: 持久化 subagent 目录与 list_agents
 
 Status: implemented
 
@@ -8,11 +8,11 @@ Status: implemented
 
 可继续的后台 subagent 会公开稳定的 child id，并将重建数据持久化在该 child 的会话中，因此 `send_message` 无需任何列表查询操作即可恢复已知 child。发现功能有两类需求不同的消费方：UI 可以同时展示一次性工作和可继续对话，而模型只应收到适合使用 `send_message` 的 child。[可继续 subagent](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)负责持久化 Session 与 Activation 设计；本记录负责共享的持久化清单及面向模型的投影。
 
-枚举必须交叉核对不可变的会话谱系、描述符有效性与实时优先的会话语料，而不能仅为展示就加载或恢复 Agent。追踪谱系可以提供候选项，却无法区分普通会话 fork 与 subagent，因此 child 日志需要持久化分类。契约还必须定义生命周期模式、缺失或损坏的记录、删除、不受支持的版本，以及反复加载大量 child 日志会如何影响服务与工具消费方。
+枚举必须交叉核对不可变的会话谱系、描述符有效性与实时优先的会话语料，而不能仅为展示就加载或恢复 Agent。追踪谱系可以提供候选项，却无法区分普通会话 fork 与 subagent，因此 child 日志需要持久化分类。约定还必须定义生命周期模式、缺失或损坏的记录、删除、不受支持的版本，以及反复加载 child 日志会如何影响服务与工具消费方。
 
 ## 决策
 
-**列表读路径已被取代。**[subagent 列表经投影单元读取身份](../architecture/2026-08-06-subagent-list-identity-projection.md)取代了本记录的枚举与逐 child 读取设计:`listChildren` 现在直接合并存活会话存储与可选的会话持久化,并从注册的 `subagent` projection unit 读取每个 child 的 mode/label——不依赖会话查询,也不在列表时扫描描述符;当前的列表语义(含 diagnostic 映射)以该记录为准。本记录仍是描述符持久化、以 mode 判别的描述符作为持久身份、直接 parent 鉴权与面向模型的 `list_agents` 投影的权威;下文基于追踪的读取机制是决策背景,不再是当前行为。
+**列表读路径已被取代。**[subagent 列表经投影单元读取身份](../architecture/2026-08-06-subagent-list-identity-projection.md)取代了本记录的枚举与逐 child 读取设计：`listChildren` 现在直接合并存活会话存储与可选的会话持久化，并从注册的 `subagent` projection unit 读取每个 child 的 mode/label——不依赖会话查询，也不在列表时扫描描述符；当前的列表语义（含 diagnostic 映射）以该记录为准。本记录仍是描述符持久化、以 mode 判别的描述符作为持久身份、直接 parent 鉴权与面向模型的 `list_agents` 投影的权威；下文基于追踪的读取机制是决策背景，不再是当前行为。
 
 parent 到 child 的枚举是一项带消费方专用投影的服务功能。`SubagentService.listChildren(parentSessionId: SessionId)`（[subagent/src/index.ts](../../../../packages/subagent/subagent/src/index.ts)）执行以下操作：
 
@@ -23,27 +23,27 @@ parent 到 child 的枚举是一项带消费方专用投影的服务功能。`Su
 - 将语料活动状态单独报告为 `running` 或 `inactive`，但不暗示已完成或可恢复；
 - 按 `createdAt` 升序、再按 child id 升序稳定返回所有结果 child。
 
-每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`）；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 契约负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
+每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`）；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 约定负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
 
 ### 枚举决策
 
 第一版消费 `ctx.sessionQuery.traceSession(parentSessionId)`，并且只考虑追踪结果的第一层后代。目标可以存活，也可以只存在于持久化存储中；追踪逻辑语料不会加载或恢复 Agent。会话查询已经使用实时优先规则合并 `ctx.sessions` 与 `ctx.sessionPersistence`，保持不可变 header 一致性，根据 `SessionHeader.parentSession` 推导直接 child 谱系，并按 `createdAt` 升序、child id 升序排列 sibling。`listChildren()` 不会重复实现这套语料逻辑，也不会检查继续执行管理器的进程内 Activation map。
 
-语料构建先于逐 child 描述符检查。构建初始追踪时如果发生持久化列表查询失败、所观测语料中任意位置的存活／持久化 header 冲突或目标谱系无效，整个 `list_agents` 调用都会失败，因为此时不存在可信的候选集。只有初始追踪成功后的失败才会被隔离到单个候选；因此，这项逐 child 契约中的“损坏 child”是指已加载的事件 surface 或描述符数据损坏，而不是语料级 header 冲突。
+语料构建先于逐 child 描述符检查。构建初始追踪时如果发生持久化列表查询失败、所观测语料中任意位置的存活／持久化 header 冲突或目标谱系无效，整个 `list_agents` 调用都会失败，因为此时不存在可信的候选集。只有初始追踪成功后的失败才会被隔离到单个候选；因此，这项逐 child 约定中的「损坏 child」是指已加载的事件 surface 或描述符数据损坏，而不是语料级 header 冲突。
 
 会话谱系涵盖的范围比 subagent 身份更广：普通 `ctx.sessions.fork()` 也会创建直接 child。会话 header 不新增 `kind` 判别字段；每个候选必须改为在自身后缀中恰好包含一个有效的 `subagent/descriptor` 事件。`SubagentService.start()` 会在普通提供方分发前解析 `{ mode: 'one-shot', provider, label? }`，而继续执行管理器会在初始创建 child 时为 `{ mode: 'continuable', ...composition }` 建立快照并将其作为 seed。本地进程内的一次性驱动只在初始创建期间追加已解析的描述符，从持久化存储冷恢复时不会追加其他描述符；第二个事件属于损坏，而不是另一次 Activation 的证据。Agent 创建是一次性运行的发布边界：拒绝表示没有发布 child，而发布后的提示词、轮次、取消与基础设施结果会通过返回的 run 结算，且不会隐藏其 id。描述符事件是已追踪 child 属于由会话支撑的 subagent 的唯一证据。缺少该事件的候选属于普通 fork、没有本地会话记录的远端 child 或其他非 subagent 会话，系统会将其排除且不产生 diagnostic。
 
-已发布的逻辑记录同时也是活动状态来源：`SessionRecord.live` 表示 `running`，而 `live: false, persisted: true` 表示 `inactive`。活动状态直接来自追踪结果，不会导致额外加载 child 日志。`inactive` 既不表示执行成功，也不表示可恢复：它可能表示已结算的一次性历史，也可能表示 `send_message` 可以为其物化另一次 Activation 的可继续 child。反过来，`running` 只表示会话存活：位于继续执行管理器对应 Activation 之外的存活可继续 Agent 仍会显示为 `running`，但 `send_message` 会将其作为所有权冲突拒绝。child 会话发布前不可见，也不会添加进程内 Activation 条目作为第二个候选来源或活动状态来源。列表查询是一份快照，可能与发布、dispose 或后续消息发生竞态；`send_message` 仍是消息送达时的权威操作。
+已发布的逻辑记录同时也是活动状态来源：`SessionRecord.live` 表示 `running`，而 `live: false, persisted: true` 表示 `inactive`。活动状态直接来自追踪结果，不会导致额外加载 child 日志。`inactive` 既不表示执行成功，也不表示可恢复：它可能表示已结算的一次性历史，也可能表示 `send_message` 可以为其物化另一次 Activation 的可继续 child。反过来，`running` 只表示会话存活：位于继续执行管理器对应 Activation 之外的存活可继续 Agent 仍会显示为 `running`，但 `send_message` 会将其作为所有权冲突拒绝。child 会话发布前不可见，也不会添加进程内 Activation 条目作为第二个候选来源或活动状态来源。列表查询是一份快照，可能与发布、dispose（资源释放）或后续消息发生竞态；`send_message` 仍是消息送达时的权威操作。
 
-subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法只在被调用时才会解析这个可选服务，并动态加载可选的会话查询运行时；因此，普通 subagent 导入、start 和 follow-up 都不会触发该包求值。列表查询直接由 `SubagentService` 负责：它解释查询返回的谱系、事件和存活状态，无需解析基于 Activation 的继续执行管理器，也不会查询 Agent 注册信息、Activation 或提供方；因此，仅包含会话、`subagents` 和 `sessionQuery` 的部署即使缺少 `agents` 也能执行列表查询。如果查询服务缺失，该方法会在加载运行时或执行查询工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在既不安装也不加载会话查询的情况下使用 `send_message`；列表工具 fiber 会在必需服务可用前保持未激活状态，而其他直接服务消费方会收到同一项明确的调用时契约。这一段的依赖姿态——可选 `sessionQuery`、其错误码与列表工具的加载要求——同属被取代的读路径：现行错误码（`SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`、`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`）与收窄后的加载要求以[取代记录](../architecture/2026-08-06-subagent-list-identity-projection.md)为准。
+subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法只在被调用时才会解析这个可选服务，并动态加载可选的会话查询运行时；因此，普通 subagent 导入、start 和 follow-up 都不会触发该包求值。列表查询直接由 `SubagentService` 负责：它解释查询返回的谱系、事件和存活状态，无需解析基于 Activation 的继续执行管理器，也不会查询 Agent 注册信息、Activation 或提供方；因此，仅包含会话、`subagents` 和 `sessionQuery` 的部署即使缺少 `agents` 也能执行列表查询。如果查询服务缺失，该方法会在加载运行时或执行查询工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在既不安装也不加载会话查询的情况下使用 `send_message`；列表工具 fiber 会在必需服务可用前保持未激活状态，而其他直接服务消费方会收到同一项明确的调用时约定。这一段的依赖姿态——可选 `sessionQuery`、其错误码与列表工具的加载要求——同属被取代的读路径：现行错误码（`SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`、`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`）与收窄后的加载要求以[取代记录](../architecture/2026-08-06-subagent-list-identity-projection.md)为准。
 
 `listChildren(parentSessionId, signal?)` 会把调用方的取消信号转发给 `traceSession()` 和条件性精确 `readEvent()` 操作。`listEvents()` 不接受取消参数，因此列表查询路径会在等待该操作的前后，以及每个候选处理完成后检查信号。如果取消信号触发后有查询操作以拒绝结算，服务会将结果归一化为 `SubagentError`，并携带稳定错误码 `CANCELLED`；后端中止错误或可映射为 diagnostic 的查询错误均不会逃逸，也不会使调用以成功的部分列表返回。
 
-这条描述符读取路径是正确性基线，并不声称工作量只与直接 child 数量呈线性关系。令 D 为直接 child 候选数量，C 为每次持久化列表查询所扫描的持久化会话数量，L_i 为候选 i 的完整日志大小。一次语料追踪后，每个候选都会执行 `sessionQuery.listEvents(childId)`。没有描述符的候选会被排除；含有多个描述符的候选会直接产生 diagnostic，无需再次读取；只有恰好含有一个描述符的候选才会通过 `sessionQuery.readEvent({ sessionId: childId, seq })` 再次加载。此次读取返回的不可变会话 header 必须与追踪时观测到的相同，包括直接 parent 关系，并且读取目标仍必须是先前定位的描述符事件；任何不一致均视为该 child 损坏。对于只存在于持久化存储中的最坏情况，每次精确读取都会重复执行 `persistence.list()`、加载完整 child 日志并克隆其中的事件，因此忽略常数因子后的工作量为 O(D × C + Σ L_i)；恰好含有一个描述符的候选承担两次这类成本，其他候选只承担一次。存活候选同样会对其完整日志取得一份分离的内存快照；读取其描述符时则会取得两份。会话查询通过持久化 seam 的非变更 `inspect()` 读取解析持久化候选：它返回有效的已存储前缀，既不修复撕裂的尾部，也不关闭中断的 turn，因此列表查询是存储只读操作；修复仍是恢复路径的职责。第一版接受这些重复读取，将其作为无索引的正确性基线，但部署必须将语料总量和 child 日志大小，而不仅是直接 child 数量，视为容量约束。列表查询不会创建 Agent，也不会追加任何目录、描述符或修复事件。对模型隐藏的描述符始终位于对话 surface 之外，并且会在压缩后保留，因此经过压缩和未经压缩的 child 必须枚举出相同结果。
+这条描述符读取路径是正确性基线，并不声称工作量只与直接 child 数量呈线性关系。令 D 为直接 child 候选数量，C 为每次持久化列表查询所扫描的持久化会话数量，L_i 为候选 i 的完整日志大小。一次语料追踪后，每个候选都会执行 `sessionQuery.listEvents(childId)`。没有描述符的候选会被排除；含有多个描述符的候选会直接产生 diagnostic，无需再次读取；只有恰好含有一个描述符的候选才会通过 `sessionQuery.readEvent({ sessionId: childId, seq })` 再次加载。此次读取返回的不可变会话 header 必须与追踪时观测到的相同，包括直接 parent 关系，并且读取目标仍必须是先前定位的描述符事件；任何不一致均视为该 child 损坏。对于只存在于持久化存储中的最坏情况，每次精确读取都会重复执行 `persistence.list()`、加载完整 child 日志并克隆其中的事件，因此忽略常数因子后的工作量为 O(D × C + Σ L_i)；恰好含有一个描述符的候选承担两次这类成本，其他候选只承担一次。存活候选同样会对其完整日志取得一份分离的内存快照；读取其描述符时则会取得两份。会话查询通过持久化 seam 的非变更 `inspect()` 读取解析持久化候选：它返回有效的已存储前缀，既不修复撕裂的尾部，也不关闭中断的轮次，因此列表查询是存储只读操作；修复仍是恢复路径的职责。第一版接受这些重复读取，将其作为无索引的正确性基线，但部署必须将语料总量和 child 日志大小，而不仅是直接 child 数量，视为容量约束。列表查询不会创建 Agent，也不会追加任何目录、描述符或修复事件。对模型隐藏的描述符始终位于对话 surface 之外，并且会在压缩（compaction）后保留，因此经过压缩和未经压缩的 child 必须枚举出相同结果。
 
 如果实测规模日后需要索引，该索引属于派生状态：会话 header 和 child 描述符仍是权威信息，重建或损坏回退必须复现相同结果。索引不能成为第二个鉴权来源，也不能让尚未发布的 child 变得可见。
 
-### `list_agents` 契约
+### `list_agents` 约定
 
 `SubagentService.listChildren(parentSessionId: SessionId)` 返回 `Promise<SubagentListEntry[]>`，其中的单个数组不会将 child 与 diagnostic 分开，而是保留追踪结果中的候选顺序。`SubagentListEntry` 是一个由只读 `kind` 判别的封闭联合类型：
 
@@ -52,7 +52,7 @@ subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务
 
 有效描述符产生一个 child 条目，逐 child 检查失败产生一个 diagnostic 条目，缺少描述符的候选不产生条目。`mode` 是持久化创建策略；`activity` 是进程本地语料快照。活动状态既不是 `AgentStatus`、管理器内部的 Activation 状态，也不是持久化结果，结果不公开内部 `createdAt` 排序键。成功完成、失败、取消和停止原因等精确 Activation 状态与持久化结果需要单独的持久化激活记录，不在本功能范围内。
 
-面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并在执行或渲染前通过显式的 request-to-spec 步骤解析请求（`undefined` → `children`）。解析后的 `children` scope 调用 `SubagentService.listChildren(rootSessionId)`，`descendants` scope 则调用 `SubagentService.listDescendants(rootSessionId)`。其内部输出投影中的 `id` 与 `parent` 会一直保持为品牌化的 `SessionId` 值，直到工具 JSON 边界。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
+面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并在执行或渲染前通过显式的 request-to-spec 步骤解析请求（`undefined` → `children`）。解析后的 `children` scope 调用 `SubagentService.listChildren(rootSessionId)`，`descendants` scope 则调用 `SubagentService.listDescendants(rootSessionId)`。其内部输出投影中的 `id` 与 `parent` 会一直保持为品牌化的 `SessionId` 值，直到工具 JSON 边界。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
 
 在已被取代的追踪读路径中，diagnostic 使用三种固定原因。格式错误的事件 surface、精确加载 child 时发现的 header 冲突、读取结果中的不可变 header 与追踪到的候选不一致或不再指向请求的直接 parent、读取目标不再是先前定位的描述符事件、格式错误的描述符内容和多个描述符事件映射为 `corrupt`。未知描述符版本映射为 `unsupported`。逐 child 读取产生的 `SESSION_QUERY_SESSION_NOT_FOUND`、`SESSION_QUERY_EVENT_NOT_FOUND` 和 `SESSION_QUERY_PERSISTENCE_FAILED` 映射为 `unavailable`。这项阶段边界是有意为之：初始追踪期间发生持久化故障会让操作失败，而同一故障如果始于候选读取期间，可能会让每个受影响的 child 分别产生一条相同的 `unavailable` diagnostic；第一版既不合并这些 diagnostic，也不会把它们提升为全局失败。缺少描述符则作为非 subagent 排除，且不产生 diagnostic。配置错误、窗口错误和未识别的失败不属于 child diagnostic，会作为操作失败继续向上传播。每条 diagnostic 都标识 child id 及原因，不暴露对模型隐藏的描述符内容；系统会排除该候选，而其他健康的 sibling 仍然可见。系统绝不会读取不属于追踪结果直接后代的会话，也不会为它们产生 diagnostic。
 
@@ -80,23 +80,23 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 
 **持久化 parent 会话目录事件。** 直接 child header 已经提供持久化枚举种子，child 描述符则是重建的权威信息。第二份 parent 日志会重复状态，并造成跨会话顺序和陈旧条目行为，却无助于按 id 恢复。
 
-**要求每次底层启动都提供显示标签。** 这会保证 UI 文本一致，却会把展示关注点引入 workflow、传输、测试和程序化启动契约。底层请求保持标签可选；高层委派与继续执行 API 在本就拥有该概念时提供标签，UI 消费方则为无标签的一次性 child 选择回退展示。
+**要求每次底层启动都提供显示标签。** 这会保证 UI 文本一致，却会把展示关注点引入 workflow、传输、测试和程序化启动约定。底层请求保持标签可选；高层委派与继续执行 API 在本就拥有该概念时提供标签，UI 消费方则为无标签的一次性 child 选择回退展示。
 
 **某个 child 无法加载时让整次列表查询失败。** 这种做法不会让损坏问题被忽略，但一个损坏的 sibling 会让每个健康 child 都不再可见。逐 child diagnostic 在保持每次排除明确可见的同时，也保留了发现能力。
 
 **分别返回 child 和 diagnostic 数组。** 分离的数组会引入两个排序域，或者要求公开另一个排序键才能重建候选顺序。一个带判别字段的条目数组既能保留追踪顺序，也能保证 child 与 diagnostic 字段的类型安全。
 
-**通过会触发修复的 `load()` 路径读取候选。** 复用恢复路径的 `load()` 语义可以让发现提前持久化地关闭中断尾部，但会把列表查询变成变更操作，并使其失败模式与写协调耦合。会话查询的语料读取本就使用非变更的 `inspect()` 契约，因此列表查询保持存储只读，尾部修复留给真正需要它的恢复路径。
+**通过会触发修复的 `load()` 路径读取候选。** 复用恢复路径的 `load()` 语义可以让发现提前持久化地关闭中断尾部，但会把列表查询变成变更操作，并使其失败模式与写协调耦合。会话查询的语料读取本就使用非变更的 `inspect()` 约定，因此列表查询保持存储只读，尾部修复留给真正需要它的恢复路径。
 
 **立即为查询分页或设置上限（暂缓）。** 这可以限制一次结果的大小，但会使模型发现成为有状态操作，而且除非模型继续跟随 cursor，否则可能隐藏更早的 child。第一版没有 cursor、分页参数或候选数量上限配置，而是返回经稳定排序的完整集合；如果实测规模需要限制，服务级限制仍留待后续决策。
 
 ## 测试
 
 - `packages/subagent/subagent/tests/service.spec.ts` 固定两种模式下的描述符 v2 解析，并证明无标签的底层启动会在分发给提供方之前解析出一次性描述符。`packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 证明本地驱动会在初始轮次内追加该描述符，在取消落入工厂到 run 的交接窗口时返回已发布 id，并让结果与句柄释放失败保留在独立通道中。委派工具测试固定其现有显示说明的传递，并保留相互独立的结果与 dispose diagnostic。
-- `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；带类型的稳定错误码；以及后代列表的迭代式稳定 pre-order、穿过普通与一次性中间节点、带位置 diagnostic、生命周期复验与取消。一个伴随规格(已随查询式读取路径一起退役)曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
-- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（一个可选 `scope` 枚举）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、由注册表推导的 child／diagnostic／空结果文本形式、带持久化 label 的已结束 child 端到端列表、descendants scope 在在线 waiting 分支上的 pre-order parent/depth 注释、两个 scope 的取消信号转发、无调用 agent 时的拒绝、要求 `agents` 但不再注入 `sessionQuery` 的加载契约，以及 HMR dispose。
+- `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；带类型的稳定错误码；以及后代列表的迭代式稳定 pre-order、穿过普通与一次性中间节点、带位置 diagnostic、生命周期复验与取消。一个伴随规格（已随查询式读取路径一起退役）曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
+- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（一个可选 `scope` 枚举）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、由注册表推导的 child／diagnostic／空结果文本形式、带持久化 label 的已结束 child 端到端列表、descendants scope 在在线 waiting 分支上的 pre-order parent/depth 注释、两个 scope 的取消信号转发、无调用 agent 时的拒绝、要求 `agents` 但不再注入 `sessionQuery` 的加载约定，以及 HMR dispose。
 - 无密钥 ACP 快照场景 `subagent-list-agents`（examples/acp-agent）使用仅限快照的 `subagent/end` 标记为第二个 parent 轮次设置边界，随后针对 subagent 服务、投影注册表和 JSONL 持久化真实执行 `list_agents`，渲染 `<id> [complete] — <label>`。
-- 无密钥快照场景 `subagent-diagnostic`（examples/headless-agent）钉住现行列表的模型可见诊断分类，包括无描述符的定局 child 以 `corrupt` diagnostic 出现。
+- 无密钥快照场景 `subagent-diagnostic`（examples/headless-agent）钉住现行列表的模型可见诊断分类，包括无描述符的已结算 child 以 `corrupt` diagnostic 出现。
 - 无密钥 ACP 快照场景 `subagent-published-run-failure` 会发布一个真实的一次性 child，注入相互独立的 run result 与 handle dispose 失败，并在 parent 工具结果中保留两项 diagnostic。
 
 ## 影响
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
index e78ab9abbd..7e50021fd6 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
 2026-07-23-web-assistant-markdown.md: ad86559e3b5294b6bd67d69ff5c6ce37a5172008
-2026-07-23-web-assistant-markdown.zh.md: b47375db843ea1c81b913e3f7ac8cd1bbc278830
+2026-07-23-web-assistant-markdown.zh.md: d1f06b4019812b0fee3c481efecaf214a137c8a7
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
index b47375db84..d1f06b4019 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
@@ -12,7 +12,7 @@ Web 对话通过会话事件、历史回放与流式累积保留 assistant Markd
 
 `@deepseek-ai/dsh-client-ui-primitives` 导出 `MarkdownText`，用作不受信任的 assistant 文本渲染器；`ui-conversation` 仅为 assistant `text` 块选择该渲染器。已完成的历史消息、流式输出尾部与被中断的部分输出已经共用 `AssistantMarkdown`，因此无需更改事件或快照，它们便会采用同一渲染器。用户消息与 steering 消息继续使用 `MessageText`，并保持按字面渲染。
 
-`MarkdownText` 以 `mdast-util-from-markdown` 加 GFM micromark 扩展解析，并经包内自有渲染器渲染 mdast 树，轮次流式输出期间增量解析（[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有该机制及其 DOM 一致性契约）。它覆盖 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，且不解析原始 HTML。一个 micromark attention 扩展复用 CommonMark resolver，同时允许至少两个星号组成的连续序列在 Unicode 标点后闭合，前提是其后紧邻 CJK 文本。这一例外涵盖流式输出期间与完成后无空格 CJK 文本中以标点结尾的粗体；单星号强调、紧邻非 CJK 文本的情况、已转义源文本、代码与数学公式仍沿用上游解析行为。围栏代码经共享的 `CodeBlock` 路由；该组件用客户端的 shiki 单例（`--shiki-*` token）高亮已注册语法，否则回退为纯等宽文本。轮次流式输出期间，围栏停留在纯文本分支，以免每收到一个分片就对增长中的围栏重新分词。
+`MarkdownText` 以 `mdast-util-from-markdown` 加 GFM micromark 扩展解析，并经包内自有渲染器渲染 mdast 树，轮次流式输出期间增量解析（[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有该机制及其 DOM 一致性约定）。它覆盖 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，且不解析原始 HTML。一个 micromark attention 扩展复用 CommonMark resolver，同时允许至少两个星号组成的连续序列在 Unicode 标点后闭合，前提是其后紧邻 CJK 文本。这一例外涵盖流式输出期间与完成后无空格 CJK 文本中以标点结尾的粗体；单星号强调、紧邻非 CJK 文本的情况、已转义源文本、代码与数学公式仍沿用上游解析行为。围栏代码经共享的 `CodeBlock` 路由；该组件用客户端的 shiki 单例（`--shiki-*` token）高亮已注册语法，否则回退为纯等宽文本。轮次流式输出期间，围栏停留在纯文本分支，以免每收到一个分片就对增长中的围栏重新分词。
 
 视觉间距、表格、链接、引用块、行内代码与代码块外框遵循 deepsuite `@deepseek/md`（`markdown.css` / `code-block.css`），并使用同一套 `--dsw-alias-markdown-*`、`--dsw-font-markdown-*`、`--dsw-alias-border-l*` 与 `--dsw-alias-label-*` token。链接使用 `--dsw-alias-state-business-primary`（deepsuite 的样式表使用 `--dsw-alias-brand-text`，仅在 newDesign 下为蓝色；design-platform 将 brand-text 保持为近黑色，此处不做重新调色）。当单个行内代码 token 完全由绝对 HTTP(S) URL 构成时，其代码外框会包含一个与普通链接相同、可通过键盘聚焦的安全外链锚点；端口、路径与查询文本保持不变，而命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。`CodeBlock` 提供语言横幅与复制控件（`复制` / `复制成功`）。已完成的文本通过定稿语法的数学扩展渲染 KaTeX；`mathCompatibility` 将 `\(...\)`、`\[...\]` 和块级同一行 `$$...$$` 映射为同一套标准数学 AST 节点。这是一层小范围的解析器兼容层，不是正则重写，也不修复格式错误的模型输出。流式输出在完成前保持按字面渲染，避免不完整公式闪现错误。引用胶囊、标题锚点、thinking-small markdown 变体，以及自定义 □/☑ 任务标记仍不在范围内；GFM 任务列表继续使用原生复选框。
 
@@ -26,15 +26,15 @@ assistant 生成的链接目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。
 
 ## 考虑过的替代方案
 
-**将现有的 mdast 与 micromark 开发依赖提升为正式依赖，并维护自定义 React walker。**此方案避免引入新的解析器体系，但产品需要自行负责每种节点映射、GFM 扩展和安全敏感的渲染分支。专用 React 渲染器将这套遍历交由上游维护，同时保留 AST 到 React 的处理路径。*后因新证据被推翻——增量流式解析需要纯字符串封装无法提供的 AST 级输入；该决策由[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有。*
+**将现有的 mdast 与 micromark 开发依赖提升为正式依赖，并维护自定义 React walker。**此方案避免引入新的解析器体系，但产品需要自行负责每种节点映射、GFM 扩展和安全敏感的渲染分支。专用 React 渲染器将这套遍历交由上游维护，同时保留 AST 到 React 的处理路径。*后因新证据被推翻——增量流式解析需要仅接受字符串的包装层无法提供的 AST 级输入；该决策由[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有。*
 
 **将 `MessageText` 替换为 Markdown 渲染。**这会产生格式化用户提示词与 steering 的副作用。在产品明确选择此行为之前，这两类输入内容仍按字面渲染。
 
 **将 Markdown 解析为会话快照。**这会让 React 节点或呈现层 AST 成为持久的运行时状态，并重新引入最终输出与流式输出之间的模式边界。解析仍留在呈现层的叶节点中。
 
-**通过净化启用原始 HTML。** 原始 HTML 当前没有产品需求，并且会扩大可执行内容边界，因此保持禁用，无需增加净化器依赖。远程图片由后续的[图片策略](2026-07-30-web-remote-markdown-images.md)约束。
+**通过净化启用原始 HTML。**原始 HTML 当前没有产品需求，并且会扩大可执行内容边界，因此保持禁用，无需增加净化器依赖。远程图片由后续的[图片策略](2026-07-30-web-remote-markdown-images.md)约束。
 
-**移植 deepsuite 的 Prism `highlight.css` 与 mdast 管线。**外观一致性由 CSS Modules 与共享的 `--dsw-*` token 负责；高亮仍走现有的 shiki 允许列表，使客户端不必引入第二套高亮器或 Prism class 契约。
+**移植 deepsuite 的 Prism `highlight.css` 与 mdast 流水线。**外观一致性由 CSS Modules 与共享的 `--dsw-*` token 负责；高亮仍走现有的 shiki 允许列表，使客户端不必引入第二套高亮器或 Prism class 约定。
 
 **为处理 CJK 标点边界而预处理 Markdown 源文本，或在解析后修复文本节点。**源文本重写必须在解析器掌握这些区别之前复现转义、代码、数学公式与定界符规则；文本节点修复则已经丢失部分源文本意图，也无法与已解析的行内节点组合。在分词器边界扩展 attention 可保留上游 resolver，并将差异限制在定界符的适用条件上。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
index 3c006bc9f1..7c8910602f 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.md
 2026-07-23-web-permission-and-approval.md: 06e184fe32ac684e3d8b0820d915ca7c372a5760
-2026-07-23-web-permission-and-approval.zh.md: b74e93006cb95c398eb464a9bd9a59e8c9cc57be
+2026-07-23-web-permission-and-approval.zh.md: 9c8718169b720f55065d5e4a416f65c94f83cc9c
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
index b74e93006c..9c8718169b 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
@@ -6,28 +6,28 @@ Status: implemented
 
 ## 问题
 
-Web 承载层启动的是一个不受限的 agent（智能体）：`bootHost` 组合了 `dsh-bash-local` 与 `dsh-fs-local`，因此每个 Web 会话都以完整文件访问权限运行，既无审批通道，也无权限管控——而 ACP 组合早在数月前就已交付完整的沙箱化产品路径（沙箱提供方 + 策略归属 + 受限的 bash/fs + 审批 + 预设）。Web 协议契约其实早已预留了对应位置——`approval/requested`/`approval/resolved` 的 mux 帧、携带 `ApprovalResponsePayload` 的 `POST /api/respond`、client 侧的 `pendingBuffers`——但 host 的 `respond` 只是一个 stub，没有应答者把 `ctx.approval` 桥接到流上，没有 RPC 暴露权限选择，PendingCard 把审批渲染成可见却无法应答的样子。
+Web 承载层启动的是一个不受限的 agent（智能体）：`bootHost` 组合了 `dsh-bash-local` 与 `dsh-fs-local`，因此每个 Web 会话都以完整文件访问权限运行，既无审批通道，也无权限管控——而 ACP 组合早在数月前就已交付完整的沙箱化产品路径（沙箱提供方 + 策略归属 + 受限的 bash/fs + 审批 + 预设）。Web 协议约定其实早已预留了对应位置——`approval/requested`/`approval/resolved` 的 mux 帧、携带 `ApprovalResponsePayload` 的 `POST /api/respond`、client 侧的 `pendingBuffers`——但 host 的 `respond` 只是一个 stub，没有应答者把 `ctx.approval` 桥接到流上，没有 RPC 暴露权限选择，PendingCard 把审批渲染成可见却无法应答的样子。
 
 ## 决策
 
 Web 承载层组合与 acp-agent 相同的沙箱化产品路径：`dsh-sandbox-local`、`dsh-sandbox-policy`、`dsh-bash-sandbox`、`dsh-fs-sandbox`、`dsh-user-approval` 与 `dsh-permission`，由 `BootHostOptions.sandbox` 提供部署默认值（`mode`，默认 `workspace-write`；`approvalPolicy`，默认 `ask`）。
 
-`createApiProxy` 拥有审批 pending 注册表。它的 `approval/request` waterfall（瀑布式事件）应答者从会话刚追加的 `approval/asked` 审计事件中读取审批 id（没有审计事件的 ask 属于外部通道，予以委托），为每个问题 mint 一个稳定的 rpcId，向每个打开的 mux 流广播可应答的 `approval/requested` 帧，并在每次 mux 打开时原样重放仍处于 pending 的帧——这正是契约早已承诺的刷新恢复基线。`respond` 按回显的 rpcId 路由，用既有的 zod schema 校验 `ApprovalResponsePayload`，将载荷的审计关联与所路由的条目交叉核对，解析应答者，并广播 `approval/resolved`；ask 的中断信号会以 `cancelled` 撤回该问题。
+`createApiProxy` 拥有审批 pending 注册表。它的 `approval/request` waterfall（瀑布式事件）应答者从会话刚追加的 `approval/asked` 审计事件中读取审批 id（没有审计事件的 ask 属于外部通道，予以委托），为每个问题生成一个稳定的 rpcId，向每个打开的 mux 流广播可应答的 `approval/requested` 帧，并在每次 mux 打开时原样重放仍处于 pending 的帧——这正是约定早已承诺的刷新恢复基线。`respond` 按回显的 rpcId 路由，用既有的 zod schema 校验 `ApprovalResponsePayload`，将载荷的审计关联与所路由的条目交叉核对，调用应答者完成应答，并广播 `approval/resolved`；ask 的中断信号会以 `cancelled` 撤回该问题。
 
-权限选择依托两个新的一元 RPC，`session.permissions` 与 `session.setPermission`，把 `ctx.permission` 投影为一个由协议拥有的 `PermissionOption` DTO（沿用 ACP bridge 的先例：每个协议拥有自己的呈现形状）。无权限的组合提供空的选择项，client 隐藏该控件。空闲期的切换以后写胜出（last-write-wins）的方式保存在 proxy 侧的 pending map 中，并在 `agent/pre-step` 时冲刷，因为旋钮事件必须保持轮次内闭合以支持持久回放；共享的 `hasOpenTurn` 折叠迁入 `dsh-session`，取代了 `dsh-user-approval`、ACP bridge 与 proxy 中各自的私有副本。
+权限选择依托两个新的一元 RPC，`session.permissions` 与 `session.setPermission`，把 `ctx.permission` 投影为一个由协议拥有的 `PermissionOption` DTO（沿用 ACP bridge 的先例：每个协议拥有自己的呈现形状）。无权限的组合提供空的权限选项列表，client 隐藏该控件。空闲期的切换以后写胜出（last-write-wins）的方式保存在 proxy 侧的 pending map 中，并在 `agent/pre-step` 时统一应用，因为旋钮事件必须保持轮次内闭合以支持持久回放；共享的 `hasOpenTurn` 折叠迁入 `dsh-session`，取代了 `dsh-user-approval`、ACP bridge 与 proxy 中各自的私有副本。
 
-在 client 侧，`Session` 新增了 `permissions` 与 `setPermission`，审批应答则依托运行时的 `PendingWait` 载体。按照设计师草稿，处于 pending 的审批会接管 composer：`ApprovalPanel` 注册为由会话声明的 `conversation.composer` 链中一个按选择器路由的条目（即 ui-question 模式），以理由标题、配对的命令与一次性的拒绝／允许按钮取代 InputBar；ui-conversation 契约中的 `PendingApproval` 领域面拥有 `ApprovalResponsePayload` 在该载体上的协议编码（wire encoding），广播的 resolved 帧使该等待落定并恢复 composer。pending 问题通过 ui-question 接管 composer，包括 `plan-review` 决策形状。侧边栏用一枚优先级高于运行中圆环的琥珀色警示圆点，同步呈现每个被阻塞的交互，搜索期间也不例外：manager 跟踪每个会话的审批与问题请求标识，而非读取 Session 实例；它只把满足 plan-review composer 二元呈现约束的请求分类为计划审查，并在问题与审批并发时优先呈现第一个 pending 问题，以匹配 composer 路由。实例化前的缓冲会保留每个仍有效的请求标识，替换回放产生的重复项，并移除已解决的请求，因此侧边栏状态绝不会比可应答的 `PendingWait` 存续得更久；跟踪以连接代次为单位清除，以保证重开后的回放才是权威依据。从未实例化过的会话仍会点亮该圆点。composer 底行的 chip 经会话注入面挂载 `PermissionSelect` 控件。连接 fixture（测试前置数据）与 host 保持一致：它的常驻审批可应答一次，其权限选择项按会话持久保存。
+在 client 侧，`Session` 新增了 `permissions` 与 `setPermission`，审批应答则依托运行时的 `PendingWait` 载体。按照设计师草稿，处于 pending 的审批会接管 composer：`ApprovalPanel` 注册为由会话声明的 `conversation.composer` 链中一个按选择器路由的条目（即 ui-question 模式），以理由标题、配对的命令与一次性的拒绝／允许按钮取代 InputBar；ui-conversation 约定中的 `PendingApproval` 领域面拥有 `ApprovalResponsePayload` 在该载体上的协议编码（wire encoding），广播的 resolved 帧使该等待落定并恢复 composer。pending 问题通过 ui-question 接管 composer，包括 `plan-review` 决策形状。侧边栏用一枚优先级高于运行中圆环的琥珀色警示圆点，同步呈现每个被阻塞的交互，搜索期间也不例外：manager 跟踪每个会话的审批与问题请求标识，而非读取 Session 实例；它只把满足 plan-review composer 二元呈现约束的请求分类为计划审查，并在问题与审批并发时优先呈现第一个 pending 问题，以匹配 composer 路由。实例化前的缓冲会保留每个仍有效的请求标识，替换回放产生的重复项，并移除已解决的请求，因此侧边栏状态绝不会比可应答的 `PendingWait` 存续得更久；跟踪以连接代次为单位清除，以保证重开后的回放才是权威依据。从未实例化过的会话仍会点亮该圆点。composer 底行的 chip 经会话注入面挂载 `PermissionSelect` 控件。连接 fixture（测试前置数据）与 host 保持一致：它的常驻审批可应答一次，其权限选择项按会话持久保存。
 
 ## 曾考虑的替代方案
 
-**在 Web 协议上复用 ACP 的 `session/set_config_option` 形状。** 不予采纳：Web 契约的一元方法注册表（`RpcMethodMap` + 逐方法的 zod schema）是它自成一体的方言；一个通用的 config-option 接口会为一个选择项绕开编译期锁定的 schema 表。一对专用方法让两侧都能从签名推导得出。
+**在 Web 协议上复用 ACP 的 `session/set_config_option` 形状。** 不予采纳：Web 约定的一元方法注册表（`RpcMethodMap` + 逐方法的 zod schema）是它自成一体的方言；一个通用的 config-option 接口会为一个选择项绕开编译期锁定的 schema 表。一对专用方法让两侧都能从签名推导得出。
 
 **用一个会话事件承载 pending 交互，而非实时注册表。** 不予采纳：可应答请求是瞬态的交互状态，而非持久的会话数据——审批的 `approval/asked`/`decided` 审计对已经记录了持久的那一半。持久化 requested 帧会在回放时重新问出已经作废的问题。
 
-**仅在存在 mux 订阅者时才注册应答者。** 不予采纳：pending 条目必须在 client 断连后依然存活（刷新恢复正是要点所在），因此注册表的生命周期长于任何单个流；一个受订阅者门控的应答者，会让在重载窗口期间关闭的 ask 落空。
+**仅在存在 mux 订阅者时才注册应答者。** 不予采纳：pending 条目必须在 client 断连后依然存活（刷新恢复正是要点所在），因此注册表的生命周期长于任何单个流；一个受订阅者门控的应答者，会导致重载窗口期间发起的 ask 以默认拒绝的方式失败。
 
-**点击即乐观移除卡片。** 不予采纳：广播的 resolved 帧才是真相；点击即移除会隐藏一个因拒绝回执或传输失败而仍然悬置的问题。面板改为在本地禁用其按钮，并在失败时重新启用。
+**点击即乐观移除卡片。** 不予采纳：广播的 resolved 帧才是真相；点击即移除会隐藏一个因回执被拒或传输失败而仍然悬置的问题。面板改为在本地禁用其按钮，并在失败时重新启用。
 
 ## 后果
 
-Web 会话从受限状态启动（默认 `workspace-write` + `ask`），一次沙箱拒绝的升级会以可应答的卡片形式抵达浏览器；部署方可以通过 `BootHostOptions.sandbox` 放宽或收紧默认值，无需触动装配。问题应答使用同一注册表模式（ui-question 基于问题 pending 表），Session 导航会在用户打开会话前识别审批、计划审阅与普通问题等待。权限选择在每次挂载时读取一次；来自另一个 client 切换的实时刷新暂缓实现。覆盖率：proxy 注册表与权限 RPC 的单元测试套件、会话对象与 fixture 的单元测试套件、针对 fixture 模式审批应答与预设切换的无密钥 Web 冒烟测试，以及真实组合的 plan-review 与问题快照；这些快照会固定 pending 侧边栏状态直至解决。
+Web 会话从受限状态启动（默认 `workspace-write` + `ask`），一次沙箱拒绝的升级会以可应答的卡片形式抵达浏览器；部署方可以通过 `BootHostOptions.sandbox` 放宽或收紧默认值，无需触动装配。问题应答使用同一注册表模式（ui-question 基于问题 pending 表），Session 导航会在用户打开会话前识别审批、计划审查与普通问题等待。权限选择在每次挂载时读取一次；来自另一个 client 切换的实时刷新暂缓实现。测试覆盖：proxy 注册表与权限 RPC 的单元测试套件、会话对象与 fixture 的单元测试套件、针对 fixture 模式审批应答与预设切换的无密钥 Web 冒烟测试，以及真实组合的 plan-review 与问题快照；这些快照会固定 pending 侧边栏状态直至解决。
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
index b11dc50cd6..c02bd6523c 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-model-facing-session-query-tools.md
 2026-07-24-model-facing-session-query-tools.md: 863f557f11f89ff8dfc121b7da0b653852528394
-2026-07-24-model-facing-session-query-tools.zh.md: d8deaba15f111537a16deafe73ed6dd708ea044a
+2026-07-24-model-facing-session-query-tools.zh.md: 584733de7b00f22f186838b058a24c31ff035905
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
index d8deaba15f..584733de7b 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-统一的 `ctx.sessionQuery` 服务对优先使用实时数据的会话日志提供精确读取、过滤、关系追踪与全文搜索，但模型无法直接使用该服务。若把提供方请求类型交给模型，还会暴露不稳定的分页游标、受信任的语料范围、存储形态的时间值，以及更适合程序化消费者而非模型推理的结果记录。大型追踪与事件负载另有输出大小问题，但若在该消费者内部解决，就会重复 harness 的通用 spill 机制，并使会话查询工具与其他工具的行为不一致。
+统一的 `ctx.sessionQuery` 服务对优先使用实时数据的会话日志提供精确读取、过滤、关系追踪与全文搜索，但模型无法直接使用该服务。若把提供方请求类型交给模型，还会暴露不稳定的分页游标、受信任的语料范围、存储形态的时间值，以及更适合程序化消费方而非模型推理的结果记录。大型追踪与事件负载另有输出大小问题，但若在该消费方内部解决，就会重复 harness 的通用 spill 机制，并使会话查询工具与其他工具的行为不一致。
 
 ## 决策
 
-`@deepseek-ai/dsh-tool-session-query` 是 `ctx.sessionQuery` 面向模型的消费者。它注册五个职责单一的只读工具：`session_search`、`session_event_search`、`session_trace`、`session_event_trace` 和 `session_event_read`。该包依赖接口而非 SQLite 实现，负责模型参数校验与易读文本渲染，并贡献一个精简的提示词段，说明历史搜索以及从搜索转向追踪／读取的工作流。
+`@deepseek-ai/dsh-tool-session-query` 是 `ctx.sessionQuery` 面向模型的消费方。它注册五个职责单一的只读工具：`session_search`、`session_event_search`、`session_trace`、`session_event_trace` 和 `session_event_read`。该包依赖接口而非 SQLite 实现，负责模型参数校验与易读文本渲染，并贡献一个精简的提示词段，说明历史搜索以及从搜索转向追踪／读取的工作流。
 
-该包入口仅作为配置、提示词注册与工具注册的公开组合根。内部模块沿执行边界划分：`input.ts` 负责模型 schema、规范化与过滤条件构造；`service-boundary.ts` 包含提供方调用与面向模型的安全错误转换；`workspace-access.ts` 负责调用者身份、工作区授权、标题访问与谱系投影；`operations.ts` 编排五个服务工作流；`presentation.ts` 渲染工具结果与调用卡片。这样可让策略留在其所属层，同时不改变包契约。
+该包入口仅作为配置、提示词注册与工具注册的公开组合根。内部模块沿执行边界划分：`input.ts` 负责模型 schema、规范化与过滤条件构造；`service-boundary.ts` 包含提供方调用与面向模型的安全错误转换；`workspace-access.ts` 负责调用者身份、工作区授权、标题访问与谱系投影；`operations.ts` 编排五个服务工作流；`presentation.ts` 渲染工具结果与调用卡片。这样可让策略留在其所属层，同时不改变包约定。
 
 `session_search` 按会话聚合全文匹配，并公开带类型的会话与事件元数据过滤条件。`session_event_search` 搜索一个会话，默认目标为调用者的当前会话。`session_trace` 返回完整的已授权祖先链与递归后代树。`session_event_trace` 返回一个事件所有已知的位置替换关系与直接来源关系。`session_event_read` 以未删节 JSON 返回准确的目标事件，并可选择汇总一个有界的原始事件窗口；省略 `before` 与 `after` 时只返回目标。
 
@@ -20,7 +20,7 @@ Status: implemented
 
 ## 工作区权限
 
-每个执行器都从不可变的 `ToolExecution.exec.agent` 身份推导调用者，绝不接受模型提供的工作区。只有当目标观测中的 `cwd` 与调用者会话的 `cwd` 完全相同时，目标才获授权。跨会话搜索始终附加该工作区过滤条件。直接操作先预检目标，然后在渲染负载前，校验与每一页事件搜索结果、事件追踪、事件读取、谱系目标或折叠标题来自同一服务观测的会话头。这样，即使实时或持久化目标在检查与使用之间被替换，也无法跨越工作区边界。谱系渲染在遇到未授权的祖先或后代子树时停止，且不泄露被隐藏的会话 id。调用者会话没有 `cwd` 时只能检查自身会话；缺少 agent 身份时按失败关闭处理。
+每个执行器都从不可变的 `ToolExecution.exec.agent` 身份推导调用者，绝不接受模型提供的工作区。只有当目标观测中的 `cwd` 与调用者会话的 `cwd` 完全相同时，目标才获授权。跨会话搜索始终附加该工作区过滤条件。直接操作先预检目标，然后在渲染负载前，校验与每一页事件搜索结果、事件追踪、事件读取、谱系目标或折叠标题来自同一服务观测的会话头。这样，即使实时或持久化目标在检查与使用之间被替换，也无法跨越工作区边界。谱系渲染在遇到未授权的祖先或后代子树时停止，且不泄露被隐藏的会话 id。调用者会话没有 `cwd` 时只能检查自身会话；缺少 agent（智能体）身份时按失败关闭处理。
 
 每个受信任的 `ctx.sessionQuery` 调用都会经过同一个模型边界净化器。它首先检查执行信号，准确保留调用者取消。对于其他失败，它会尽力把可获得的语料或提供方诊断链写入内部日志；当值无法安全检查时，则改用固定占位符。诊断格式化与错误分类各自受到保护，因此无法打印的嵌套 cause 既不会逃逸，也不会阻止对外层错误进行安全分类；分类不安全或日志记录失败时，则返回固定的通用错误码 `SESSION_QUERY_TOOL_FAILED` 及其消息。逐标题失败也会先经过同一个净化器，再转为不可用标记。工具自身的输入校验与授权错误在该服务边界之外创建，因此仍保留精确消息。
 
@@ -28,11 +28,11 @@ Status: implemented
 
 ## 无游标结果与 spill
 
-两个搜索工具都不向模型公开游标、偏移量、页大小或模型可控的结果限制。一次执行会在观察到的代保持有效时持续跟随提供方游标，并收集不超过配置项 `maxSearchResults` 的结果，其默认值为 100。达到上限的结果会要求模型缩小查询或过滤范围；代发生变化时会报告必须重试完整搜索。搜索执行通过工具截止时间与服务中止信号传递可配置的 `searchTimeoutMs`，默认值为 30 秒。由于内部页面共享与代绑定的游标，两个搜索工具在 agent loop 调度器中都以独占方式执行；精确追踪与读取工具则允许和兄弟工具并行执行，因为其观测可以容忍期间发生的提交。
+两个搜索工具都不向模型公开游标、偏移量、页大小或模型可控的结果限制。一次执行会在观察到的代保持有效时持续跟随提供方游标，并收集不超过配置项 `maxSearchResults` 的结果，其默认值为 100。达到上限的结果会要求模型缩小查询或过滤范围；代发生变化时会报告必须重试完整搜索。搜索执行通过工具截止时间与服务中止信号传递可配置的 `searchTimeoutMs`，默认值为 30 秒。由于内部页面共享与代绑定的游标，两个搜索工具在 agent loop（智能体循环）调度器中都以独占方式执行；精确追踪与读取工具则允许和兄弟工具并行执行，因为其观测可以容忍期间发生的提交。
 
-追踪与读取工具同样不公开谱系分页或字符分页。规范结果采用纯文本，并在服务已有的事件窗口与搜索数量资源边界内保持完整。每个精确执行器都会将未经替换的工具执行信号传递给目标授权与服务追踪或读取。在服务解析过程中，已知实时事件追踪、事件读取与标题读取在遵循预中止的同时仍不访问持久化。会话谱系追踪会将该信号传递给全语料持久化列表；持久化事件追踪与读取则将其传递给目标列表和检查。每个已启动的后端调用都会等待清理完成后再保留准确的中止原因，即使该后端忽略了取消也不例外。通用的 `tools/post-execute` spill 策略负责行内字节保留：当已配置的部署收到过大的文本时，该策略会用有界预览、不可透明推导的定位符与读取提示替换文本，同时在 spill 存储中保留完整结果。会话查询消费者既不导入 `ctx.spillStore`，也不实现第二套截断格式。
+追踪与读取工具同样不公开谱系分页或字符分页。规范结果采用纯文本，并在服务已有的事件窗口与搜索数量资源边界内保持完整。每个精确执行器都会将未经替换的工具执行信号传递给目标授权与服务追踪或读取。在服务解析过程中，已知实时事件追踪、事件读取与标题读取在遵循预中止的同时仍不访问持久化。会话谱系追踪会将该信号传递给全语料持久化列举操作；持久化事件追踪与读取则将其传递给目标列举与检查操作。每个已启动的后端调用都会等待清理完成后再保留准确的中止原因，即使该后端忽略了取消也不例外。通用的 `tools/post-execute` spill 策略负责行内字节保留：当已配置的部署收到过大的文本时，该策略会用有界预览、不透明定位符与读取提示替换文本，同时在 spill 存储中保留完整结果。会话查询消费方既不导入 `ctx.spillStore`，也不实现第二套截断格式。
 
-会话级结果在可用时包含最新折叠标题。每次工具执行都会通过一次优先使用实时数据的语料观测批量读取唯一标题 id，最多使用服务通过 `persistedInspectConcurrency` 配置的持久化检查 worker，其默认值为 4，并将准确的工具执行信号传递给持久化列表与检查操作。实时来源会直接折叠；每个持久化 worker 都会把已完成的来源折叠为分离的会话头／标题观测，并在取出下一个 id 前释放完整日志，因此批次只保留小型投影值。对于搜索工具，该执行信号携带已配置的搜索截止时间。取消不会启动排队中的标题检查，并会在已经启动的检查全部完成后拒绝完整的工具执行；标题缺失、格式错误或发生操作性失败时，错误只影响对应 id，同时保留基础结果、渲染不可用标记并记录底层错误，而授权不匹配则按失败关闭处理。搜索结果包含最强匹配事件与提供方摘录，追踪包含完整的已授权关系，事件读取保持邻近事件表现易读，同时只为被请求的目标保留精确 JSON。
+会话级结果在可用时包含最新折叠标题。每次工具执行都会通过一次优先使用实时数据的语料观测批量读取唯一标题 id，最多使用服务通过 `persistedInspectConcurrency` 配置的持久化检查 worker，其默认值为 4，并将准确的工具执行信号传递给持久化列举与检查操作。实时来源会直接折叠；每个持久化 worker 都会把已完成的来源折叠为分离的会话头／标题观测，并在取出下一个 id 前释放完整日志，因此批次只保留小型投影值。对于搜索工具，该执行信号携带已配置的搜索截止时间。取消不会启动排队中的标题检查，并会在已经启动的检查全部完成后拒绝完整的工具执行；标题缺失、格式错误或发生操作性失败时，错误只影响对应 id，同时保留基础结果、渲染不可用标记并记录底层错误，而授权不匹配则按失败关闭处理。搜索结果包含最强匹配事件与提供方摘录，追踪包含完整的已授权关系，事件读取保持邻近事件表现易读，同时只为被请求的目标保留精确 JSON。
 
 ## 宿主组合
 
@@ -42,14 +42,14 @@ Status: implemented
 
 - **向模型公开提供方游标**：不予采纳，因为记录工具结果或开始下一个模型步骤会改变相关会话或全局代，导致游标通常在模型能够复用前就已过期。
 - **增加工具本地截断、偏移量或 spill 文件**：不予采纳，因为执行后 spill 策略已经统一负责各工具的完整结果保留与读取。
-- **允许访问所有持久化会话或由模型提供工作区过滤条件**：不予采纳，因为 `ctx.sessionQuery` 是受信任服务，面向模型的消费者必须执行调用者权限边界。
+- **允许访问所有持久化会话或由模型提供工作区过滤条件**：不予采纳，因为 `ctx.sessionQuery` 是受信任服务，面向模型的消费方必须执行调用者权限边界。
 - **把搜索、追踪与精确读取合并为一个带操作选择器的工具**：不予采纳，因为职责单一的名称能为模型提供更清晰的 schema、默认值、表现意图与后续选择。
 - **只返回一层谱系**：不予采纳，因为 spill 已消除行内大小方面的理由，而单层输出会遗漏关系且没有继续读取路径。
 
 ## 验证
 
-包级测试固定参数校验、过滤条件转换、时间戳规范化、精确工作区授权、父级过滤预授权与抵御预言机探测、变更观测拒绝、普通值与对抗性未知值的服务诊断脱敏、尽力记录循环 cause、日志失败隔离、身份缺失行为、隐藏边界裁剪、当前步骤排除、内部提供方翻页、搜索独占与精确读取并行分类、数量上限、精确信号传递、中止原因保留、持久化清理静止、单次扫描且并发有界的批量标题扩充、先投影再取出下一个任务的顺序、抑制排队工作、等待已启动 worker 静止、逐会话头校验、标题回退、代表性搜索／追踪／读取渲染、通用表现与可释放注册。集成覆盖使用真实 SQLite FTS 提供方查询实时与持久化会话。发布配置与 TUI/Web 组合测试证明面向模型的消费方不存在于 TUI、Web 与无头界面，而组装后的 ACP 请求头快照证明自动化界面默认不包含它。包自身的 Loader 冒烟测试与专用无密钥 ACP 快照显式挂载该消费方，并配套启用超时与 spill 支持，固定其提示词指引、schema 以及与路径无关的精确事件读取保留行为。
+包级测试固定参数校验、过滤条件转换、时间戳规范化、精确工作区授权、父级过滤预授权与抵御预言机探测、变更观测拒绝、普通值与对抗性未知值的服务诊断脱敏、尽力记录循环 cause、日志失败隔离、身份缺失行为、隐藏边界裁剪、当前步骤排除、内部提供方翻页、搜索独占与精确读取并行分类、数量上限、精确信号传递、中止原因保留、持久化清理完全停稳、单次扫描且并发有界的批量标题扩充、先投影再取出下一个任务的顺序、抑制排队工作、等待已启动 worker 完全停稳、逐会话头校验、标题回退、代表性搜索／追踪／读取渲染、通用表现与可释放注册。集成覆盖使用真实 SQLite FTS 提供方查询实时与持久化会话。发布配置与 TUI/Web 组合测试证明面向模型的消费方不存在于 TUI、Web 与无头界面，而组装后的 ACP 请求头快照证明自动化界面默认不包含它。包自身的 Loader 冒烟测试与专用无密钥 ACP 快照显式挂载该消费方，并配套启用超时与 spill 支持，固定其提示词指引、schema 以及与路径无关的精确事件读取保留行为。
 
 ## 后果
 
-模型无需获得存储权限或继续状态，即可通过与提供方无关的方式访问既往会话工作。搜索具有有限的单次调用工作边界，若要命中前 100 条以后的结果，可能需要缩小查询；搜索调用不能与兄弟工具重叠执行，而精确观测仍可并行调度。完整追踪与事件负载可能表现为 spill 引用而不是行内文本。严格的 `cwd` 字符串相等选择了保守安全边界，而不解析通过符号链接等价的路径。自定义组合可以在不挂载 spill 的情况下使用该工具，但这表示它们明确接受完整追踪与读取结果直接出现在行内。
+模型无需获得存储权限或继续状态，即可通过提供方无关的方式访问既往会话工作。搜索具有有限的单次调用工作边界，若要命中前 100 条以后的结果，可能需要缩小查询；搜索调用不能与兄弟工具重叠执行，而精确观测仍可并行调度。完整追踪与事件负载可能表现为 spill 引用而不是行内文本。严格的 `cwd` 字符串相等选择了保守安全边界，而不解析通过符号链接等价的路径。自定义组合可以在不挂载 spill 的情况下使用该工具，但这表示它们明确接受完整追踪与读取结果直接出现在行内。
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
index fe955d125d..746c8740b4 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
 2026-07-25-session-list-browsing-and-manual-order.md: bd04e7f74c8a4540d68e60ad68965e05de76bce9
-2026-07-25-session-list-browsing-and-manual-order.zh.md: 8ec5f71943a68a70f46fbd4c7702e4556b1892ec
+2026-07-25-session-list-browsing-and-manual-order.zh.md: 216ade7b723f82740d485a435d360a060a2b42d9
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
index 8ec5f71943..216ade7b72 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
@@ -6,55 +6,55 @@ Status: implemented
 
 ## Problem
 
-[Workspace UI 完整产品流](2026-07-25-workspace-ui-product-flow.md)交付了分组 session 列表的首个形态,并把 Rename、拖拽排序等操作明确划出当期范围。设计稿(figma 239-10458 及关联画面)随后补齐了这些交互:列表要能切换成不分组的平铺视图、session 行悬停要出详情卡与操作菜单、workspace 要能改名、组内 session 要能手动排序。
+[Workspace UI 完整产品流](2026-07-25-workspace-ui-product-flow.md)交付了分组会话列表的首个形态，并把 Rename、拖拽排序等操作明确划出当期范围。设计稿（figma 239-10458 及关联画面）随后补齐了这些交互：列表要能切换成不分组的平铺视图、会话行悬停要出详情卡与操作菜单、workspace 要能改名、组内会话要能手动排序。
 
-两条既有机制挡在前面。其一,host 在每条 `session/event` 上把活跃 session durable 地提到 workspace 账本最前(活动置顶),任何手动排序都会被下一次活动打乱——两种排序权威不可调和。其二,浏览区域被劈在两个包里:ui-sidebar 拥有列表、搜索和组头行,ui-workspace 只借一个 picker 坑放弹层;每加一个 workspace 域的对话框都要跨包接线,归属越来越拧。
+两条既有机制挡在前面。其一，host 在每条 `session/event` 上把活跃会话持久化地提到 workspace 账本最前（活动置顶），任何手动排序都会被下一次活动打乱——两种排序权威不可调和。其二，浏览区域被劈在两个包里：ui-sidebar 拥有列表、搜索和组头行，ui-workspace 只借一个 picker slot 放弹层；每加一个 workspace 域的对话框都要跨包接线，归属越来越拧。
 
 ## Decision
 
 ### 平铺行与浏览态
 
-group-by 菜单提供 WorkSpace / In one list 两种模式。WorkSpace 模式按 `WorkspaceView.sessionIds` 的手动序在各组内展示同级 session 行；In one list 把所有 session 合并后严格按 `updatedAt` 新→旧排序。两种模式都不把 `parentId` 投影成列表层级，fork 谱系只保留为 session 数据；完整 fork 行为由 [Web session fork 操作](2026-07-27-web-session-fork-actions.md)定义。模式选择持久化在浏览器(`dsh.workspace.view`),刷新保持。
+group-by 菜单提供 WorkSpace / In one list 两种模式。WorkSpace 模式按 `WorkspaceView.sessionIds` 的手动序在各组内展示同级会话行；In one list 把所有会话合并后严格按 `updatedAt` 新→旧排序。两种模式都不把 `parentId` 投影成列表层级，fork 谱系只保留为会话数据；完整 fork 行为由 [Web 会话 fork 操作](2026-07-27-web-session-fork-actions.md)定义。模式选择持久化在浏览器（`dsh.workspace.view`），刷新保持。
 
 ### 行交互
 
-- session 行悬停 500ms 出详情卡(全名/相对时间/状态行;状态本期只有 running/idle 两态,枚举扩展待 wire 增补 status 字段)。卡片与行菜单互斥:菜单开启或拖拽进行中不出卡。
-- session 行 … 菜单:Rename / Fork session / Delete session，其中 Rename 与 Fork 已接线，Delete 仍为纯视觉；workspace 组头 … 菜单的 Rename / Delete workspace 均已接线。菜单鼠标移出即关。
-- 支撑件:`Menu` 新增 label 条目、danger 行、`closeOnPointerLeave`;新增 `HoverCard`(portal 定位、开启延时、disabled 守卫)。
+- 会话行悬停 500ms 出详情卡（完整标题、相对时间、状态行；状态本期只有 running/idle 两态，枚举扩展待协议格式（wire format）增补 status 字段）。卡片与行菜单互斥：菜单开启或拖拽进行中不出卡。
+- 会话行 … 菜单：Rename / Fork session / Delete session，其中 Rename 与 Fork 已接线，Delete 仍为纯视觉；workspace 组头 … 菜单的 Rename / Delete workspace 均已接线。菜单鼠标移出即关。
+- 支撑件：`Menu` 新增 label 条目、danger 行、`closeOnPointerLeave`；新增 `HoverCard`（portal 定位、开启延时、disabled 守卫）。
 
 ### workspace.rename
 
 `workspace.rename({ workspaceId, title })`：title trim 后非空；同名 no-op 与重名查重都在 Host 的 Workspace 操作串行链内求值（与按名称创建共链，并发的显式命名操作不能穿插出重名或乱序假成功），冲突返回 `workspace-name-conflict`。按路径收编可以派生出已有 title，因为拥有身份的是 canonical path，而不是 title（见[身份决策](../bug-fix/2026-07-31-same-basename-workspace-adoption.md)）。落盘经 `setTitle` 的 mutate 通道，`domain/changed` 监听自动广播 `host/workspace-changed` 帧。UI 为标准 Modal，client 侧另做重名预检。
 
-### 手动排序:insertSessionBefore 取代活动置顶
+### 手动排序：insertSessionBefore 取代活动置顶
 
-`session/event` → `touchSession` 活动置顶链整体删除;workspace 账本序改为纯手动拥有——新 session attach 时前插,显式重排走 `workspace.insertSessionBefore({ workspaceId, sessionId, beforeSessionId? })`(DOM insertBefore 语义:锚给了插锚前,缺省 append 到末尾)。实体只对不在账的 session/锚抛类型化的 `WorkspaceMoveInvalidError`,handler 仅把它映射为业务码 `workspace-move-invalid`,存储故障保持 internal。
+`session/event` → `touchSession` 活动置顶链整体删除；workspace 账本序改为纯手动拥有——新会话 attach 时前插，显式重排走 `workspace.insertSessionBefore({ workspaceId, sessionId, beforeSessionId? })`（DOM insertBefore 语义：有锚点时插到锚点前，省略时 append 到末尾）。实体只对不在账的会话/锚抛类型化的 `WorkspaceMoveInvalidError`，handler 仅把它映射为业务码 `workspace-move-invalid`，存储故障保持 internal。
 
-UI 为组内 session 行的 HTML5 拖拽(仅 workspace 分组、非搜索态；fork 子与源会话一样独立排序)。顺序权威完全在 host:drop 只发 RPC,client 零本地重排,视图靠响应体 upsert 与 changed 帧刷新;失败即无事发生。client 的 upsert 拒绝比已装载投影更旧(`updatedAt`)的快照,防迟到的一元响应回滚更新的帧。
+UI 为组内会话行的 HTML5 拖拽（仅 workspace 分组、非搜索态；fork 子会话及其源会话各自独立排序）。顺序权威完全在 host：drop 只发 RPC，client 零本地重排，视图靠响应体 upsert 与 changed 帧刷新；失败即无事发生。client 的 upsert 拒绝比已装载投影更旧（`updatedAt`）的快照，防迟到的一元响应回滚较新的帧。
 
 ### 壳/区域切分
 
-ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settings,以及一个 `sidebar.workspaces` 洞;壳与区域的契约只有两个事实 `{ wide, expandSidebar }`。ui-workspace 全权拥有浏览区域(section header、搜索、分组树与平铺、全部 workspace 对话框、拖拽)及其 groupBy store;rail 态的搜索/添加工作区图标也归区域,经 `expandSidebar()` 请求壳展开。picker 拆为核心件 `WorkspacePickFlow`(区域内直接组件组合;在[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)之前名为 `WorkspaceCreateFlow`)与薄包装 `WorkspacePicker`(继续填 ui-conversation 的 hero 坑);原 `sidebar.workspace` picker 坑与声明感知延迟注册随之删除。
+ui-sidebar 缩为列几何壳：品牌行、折叠状态机、New Session、Settings，以及一个 `sidebar.workspaces` slot；壳与区域的约定只有两个事实 `{ wide, expandSidebar }`。ui-workspace 全权拥有浏览区域（section header、搜索、分组树与平铺、全部 workspace 对话框、拖拽）及其 groupBy store；rail 态的搜索/添加工作区图标也归区域，经 `expandSidebar()` 请求壳展开。picker 拆为核心件 `WorkspacePickFlow`（区域内直接组件组合；在[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)之前名为 `WorkspaceCreateFlow`）与薄包装 `WorkspacePicker`（继续填 ui-conversation 的 hero slot）；原 `sidebar.workspace` picker slot 与声明感知延迟注册随之删除。
 
 ## Alternatives considered
 
-**保留活动置顶、拖拽仅作临时调整** —— 手动序在下一次 session 活动即被打乱,形同虚设;两种排序权威并存无法向用户解释。也考虑过「拖过一次即冻结该 workspace 的活动置顶」的折中,状态多一档、语义更难讲,直接删除更干净。
+**保留活动置顶、拖拽仅作临时调整**——手动序在下一次会话活动即被打乱，形同虚设；两种排序权威并存无法向用户解释。也考虑过「拖过一次即冻结该 workspace 的活动置顶」的折中，状态多一档、语义更难讲，直接删除更干净。
 
-**排序报文用数字下标** —— `{ index }` 在拖拽窗口期会漂移:host 前插新 session(如 Intent 材料化)后同一下标指向别的行。锚点式 insertBefore 对前插与过滤投影天然免疫。
+**排序报文用数字下标**——`{ index }` 在拖拽窗口期会漂移：host 前插新会话（如 Intent 材料化）后同一下标指向别的行。锚点式 insertBefore 对前插与过滤投影天然免疫。
 
-**drop 后乐观重排** —— client 先行重排需失败回滚,对象层多一块纠缠态;本地/局域网往返毫秒级,等 host 响应的简单方案肉眼无感。顺序权威单一化(完全信 host)后,前端永不发明顺序。
+**drop 后乐观重排**——client 先行重排需失败回滚，对象层多一块纠缠态；本地/局域网往返毫秒级，等 host 响应的简单方案肉眼无感。顺序权威单一化（完全信 host）后，前端永不发明顺序。
 
-**rename 对话框留在 ui-sidebar(最小改动)** —— 正是问题本身:workspace 域的对话框散落在借来的坑里,每加一个(Delete 确认框将至)都重演跨包接线。评审中先议了「只挪 rename Modal」的中间态,最终裁定整个浏览区域归 ui-workspace,壳只留几何。
+**rename 对话框留在 ui-sidebar（最小改动）**——正是问题本身：workspace 域的对话框散落在借来的位置里，每加一个（Delete 确认框将至）都重演跨包接线。评审中先议了「只挪 rename Modal」的中间态，最终裁定整个浏览区域归 ui-workspace，壳只留几何。
 
-**WorkSpace 模式按 fork 谱系嵌套 session** —— 嵌套会让当前子会话依赖祖先展开态才能可见，也让组内手动序只能移动根节点；`parentId` 是 lineage 数据，不是列表导航结构。所有 session 拍平成同级行后，每行都可独立打开、搜索与排序；In one list 仍因没有 workspace 持久化载体而禁用拖拽。
+**WorkSpace 模式按 fork 谱系嵌套会话**——嵌套会让当前子会话依赖祖先展开态才能可见，也让组内手动序只能移动根节点；`parentId` 是 lineage 数据，不是列表导航结构。所有会话拍平成同级行后，每行都可独立打开、搜索与排序；In one list 仍因没有 workspace 持久化载体而禁用拖拽。
 
 ## Consequences
 
-- 手动序是唯一的 workspace 账本序权威:用户排好的顺序不再被活动打乱;代价是「最近活跃浮到最上」的行为消失,活跃感知转由行内状态点与时间标签承担。`WorkspaceView.sessionIds` 的 wire 契约随之改为手动序措辞。
-- 壳/区域两事实契约把 workspace 域的后续功能(Delete 确认、跨组移动、Ungrouped 收编)全部收进 ui-workspace 单包;ui-sidebar 不再随 session 列表功能演进。
-- 平铺模式不支持排序与分组入口(建到指定 workspace 需切回分组视图),是拍板接受的范围收窄。
-- session Delete 的功能接线与状态枚举扩 wire,留待后续迭代。
+- 手动序是唯一的 workspace 账本序权威：用户排好的顺序不再被活动打乱；代价是「最近活跃浮到最上」的行为消失，活跃感知转由行内状态点与时间标签承担。`WorkspaceView.sessionIds` 的协议格式约定随之改为手动序措辞。
+- 壳/区域两事实约定把 workspace 域的后续功能（Delete 确认、跨组移动、Ungrouped 收编）全部收进 ui-workspace 单包；ui-sidebar 不再随会话列表功能演进。
+- 平铺模式不支持重排，也没有在 workspace 中创建会话的入口（建到指定 workspace 需切回分组视图），是拍板接受的范围收窄。
+- 会话 Delete 的功能接线与扩充协议格式中的状态枚举，留待后续迭代。
 
 ## Testing
 
-包级用例覆盖派生(deriveGroups/deriveFlat)、同级 session 行、两处 apply 注册与透传、host 实体移位语义、rename/insertSessionBefore 的 RPC 实现与 fixture 桩；`apps/web` keyless snapshot 回归覆盖装配后的应用，并钉住 fork 后没有 session 展开控件。
+包级用例覆盖派生（deriveGroups/deriveFlat）、同级会话行、两处 apply 注册与透传、host 实体移位语义、rename/insertSessionBefore 的 RPC 实现与 fixture（测试前置数据）桩；`apps/web` keyless 快照回归覆盖装配后的应用，并钉住 fork 后没有会话展开控件。
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
index d8232afa44..5fd9467179 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
 2026-07-25-workspace-ui-product-flow.md: 7a6a41e19d2930fbcbf7ba5fc9e6809d96e23166
-2026-07-25-workspace-ui-product-flow.zh.md: a40f374fd794b11bff0de72cbc822fd638cd267c
+2026-07-25-workspace-ui-product-flow.zh.md: 14f33b0eebcf8885670e72cfb6e2c9a87b7a3432
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
index a40f374fd7..14f33b0eeb 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
@@ -1,9 +1,9 @@
 # Agent Note: Workspace UI 完整产品动线
 
-[English](2026-07-25-workspace-ui-product-flow.md) | 中文
-
 Status: implemented
 
+[English](2026-07-25-workspace-ui-product-flow.md) | 中文
+
 ## Problem
 
 [Domain KV storage 与 Workspace entity](../../proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)定义了 Workspace 的持久实体、路径规范和有序 Session 账本，但没有定义 Host 接线、历史数据初始化或 GUI 动线。GUI 同时呈现 Workspace 和 Session；用户进入 New Session 后必须立即输入，即使此时还没有 Host Session，甚至没有 Host Workspace。
@@ -25,11 +25,11 @@ Host 在 Workspace entity 上提供以下 GUI 接线：
 | `session.create({ workspaceId, sessionId? })` | 从 Workspace 解析 cwd，以可选预分配 id 幂等创建 Session 并 attach |
 | `session.create({ cwd })` | 保留给非 Workspace 调用方，创建 Ungrouped Session |
 
-`workspaceRoot` 是独立 Host 配置，未配置时回退到 Host cwd；它与保存 Workspace domain 数据的 `storageRoot` 无关。Host stream 推送 Workspace 与 Session 增量，包括 `host/workspace-removed`；Client 重连后分别刷新 `workspace.list` 与 `session.list` 基线。删除注册记录的所有权与安全边界由 [Workspace 注册记录删除 Agent Note](2026-07-27-workspace-registration-deletion.md)定义。
+`workspaceRoot` 是独立 Host 配置，未配置时回退到 Host cwd；它与保存 Workspace domain 数据的 `storageRoot` 无关。Host 流推送 Workspace 与 Session 增量，包括 `host/workspace-removed`；Client 重连后分别刷新 `workspace.list` 与 `session.list` 基线。删除注册记录的所有权与安全边界由 [Workspace 注册记录删除 Agent Note](2026-07-27-workspace-registration-deletion.md)定义。
 
-Workspace 的 `sessionIds` 是有序候选索引。成员投影同时要求 id 位于索引且对应 `SessionHeader.cwd` canonical 后等于 Workspace path；SessionHeader 不增加 `workspaceId`。cwd 匹配但未入索引的 Session 保持 Ungrouped，索引命中但 header 缺失、cwd 无效或 cwd 不匹配的 id 被过滤。同一 Session 被两个 Workspace 索引占用属于损坏状态并 fail loud。
+Workspace 的 `sessionIds` 是有序候选索引。成员投影同时要求 id 位于索引且对应 `SessionHeader.cwd` canonical 后等于 Workspace path；SessionHeader 不增加 `workspaceId`。cwd 匹配但未入索引的 Session 保持 Ungrouped，索引命中但 header 缺失、cwd 无效或 cwd 不匹配的 id 被过滤。同一 Session 被两个 Workspace 索引占用属于损坏状态并明确报错。
 
-Workspace domain 以 durable marker 区分“从未初始化”和“已初始化但为空”。marker 未设置时，Registry 只调用 `SessionPersistence.list()` 读取 header 元数据，不调用 `load`、`inspect`、history 或解析事件正文；有效 cwd 按 canonical path 分组，组内 Session 与 Workspace 组均按 header `createdAt` 降序初始化。Bootstrap 可重入，最后才写 marker；marker 写入后，绕过 `workspaceId` 的新 Session 不再被自动收编。
+Workspace domain 以 durable marker 区分「从未初始化」和「已初始化但为空」。marker 未设置时，注册表只调用 `SessionPersistence.list()` 读取 header 元数据，既不调用 `load` 或 `inspect`，也不读取历史数据或解析事件正文；有效 cwd 按 canonical path 分组，组内 Session 与 Workspace 组均按 header `createdAt` 降序初始化。Bootstrap 可重入，最后才写 marker；marker 写入后，绕过 `workspaceId` 的新 Session 不再被自动收编。
 
 ### Client 对象模型
 
@@ -56,15 +56,15 @@ Session 自己持有首条输入并驱动一条内部流水线：必要时以预
 
 ### 首次发送与恢复
 
-前端 Session 的 `pendingPrompt` 在 Host 接受消息前始终保留原文。首次发送按 Workspace materialize、Session attach、prompt send 顺序推进：
+前端 Session 的 `pendingPrompt` 在 Host 接受消息前始终保留原文。首次发送按 Workspace materialize、Session attach、提示词发送顺序推进：
 
 1. Workspace 创建失败时，Workspace Intent 保留输入与错误，Session 仍指向该对象。
 2. Session 创建在发布前失败时，Session Intent 回到可编辑状态，以同一预分配 SessionId 重试。
-3. `workspace-attach-failed` 证明 Session 已发布；同一 Session 对象进入真实列表并保留 prompt，后续重试 attach。
-4. prompt 失败时，Session 保留 prompt 并只重试 send，不重复创建 Workspace 或 Session。
-5. Session 创建期间若页面切换到另一个 Intent，旧 Session 即使随后发布也不自动发送；它保留原 prompt 和可见错误。
+3. `workspace-attach-failed` 证明 Session 已发布；同一 Session 对象进入真实列表并保留提示词，后续重试 attach。
+4. 提示词发送失败时，Session 保留提示词并只重试发送，不重复创建 Workspace 或 Session。
+5. Session 创建期间若页面切换到另一个 Intent，旧 Session 即使随后发布也不自动发送；它保留原提示词和可见错误。
 
-RPC lost response、Host frame 先于 completion 和 completion 先于 Host frame 都通过预分配 SessionId 与对象身份收敛。Manager 对 Host view 做有序 upsert，本地 materialize 时优先保留原对象身份，不生成同 id 的临时第二行。
+RPC 响应丢失、Host frame 先于 completion 和 completion 先于 Host frame 都通过预分配 SessionId 与对象身份收敛。Manager 对 Host view 做有序 upsert，本地 materialize 时优先保留原对象身份，不生成同 id 的临时第二行。
 
 ### Sidebar 与排序
 
@@ -72,7 +72,7 @@ Workspace 组严格使用 Host 返回的持久顺序。Bootstrap 一次性确定
 
 组内严格使用 `Workspace.sessionIds`。新 attach 的 Session 放在首位，后续某个 Session 活跃时 Host 只前移该 id 并持久化。Client 不在 Session list 到达后按时间整体重排，因此不会先显示一套 Workspace 顺序再因 hydration 瞬间跳动。
 
-前端 Session Intent 只有在目标是真实 Workspace 时才作为 “New session” 行显示，并临时计入该组 Session 数量；目标是 Workspace Intent 时，Workspace 与 Session 都不进入 sidebar。Intent 发布后由同一预分配 id 对应的真实行接替，刷新后 Intent 行和临时计数一起消失。搜索模式不保存或筛选 Intent 行。
+前端 Session Intent 只有在目标是真实 Workspace 时才作为 「New session」 行显示，并临时计入该组 Session 数量；目标是 Workspace Intent 时，Workspace 与 Session 都不进入 sidebar。Intent 发布后由同一预分配 id 对应的真实行接替，刷新后 Intent 行和临时计数一起消失。搜索模式不保存或筛选 Intent 行。
 
 无法归入任何 Workspace 的真实 Session 进入 Ungrouped。Host `session-added` 与 `workspace-changed` 可以任意顺序到达，列表合并不依赖 frame 顺序。
 
@@ -80,19 +80,19 @@ Workspace 组严格使用 Host 返回的持久顺序。Bootstrap 一次性确定
 
 ### React 与 slot 边界
 
-React 组件只消费 `useSessions`、`useWorkspaces` 与 session-scoped hooks，不拥有实体生命周期。Zustand store 只保留布局、当前 view、普通真实 Session 的 composer 文本和其他纯呈现状态；Session/Workspace Intent、materialize phase、错误和 retained prompt 位于 React-free runtime 对象层。
+React 组件只消费 `useSessions`、`useWorkspaces` 与 session-scoped 钩子，不拥有实体生命周期。Zustand store 只保留布局、当前 view、普通真实 Session 的 composer 文本和其他纯呈现状态；Session/Workspace Intent、materialize phase、错误和 retained prompt 位于 React-free 运行时对象层。
 
-Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSession`、`updateSessionPrompt`、`sendSession`、`open` 与 `toggleSidebar`。Workspace picker 复用同一组件与 `createWorkspace` seam；owner 只提供 popover 开关、锚点和选中回调。呈现层不直接发送 `host/workspace-changed`，Host event 只由 Host mutation 与 stream adapter 产生。
+Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSession`、`updateSessionPrompt`、`sendSession`、`open` 与 `toggleSidebar`。Workspace picker 复用同一组件与 `createWorkspace` seam；owner 只提供 popover 开关、锚点和选中回调。呈现层不直接发送 `host/workspace-changed`，Host 事件只由 Host mutation 与流适配器产生。
 
 ## Alternatives considered
 
 **为待创建 Workspace 与 Session 保存独立页面记录。** 该方案在 materialize 后需要替换身份并转交输入、错误、焦点和 sidebar 行；对象自身的 Intent 状态可以保持身份连续。
 
-**由呈现层或 root Zustand store 编排对象生命周期。** 该方案会重复 Manager/Service 的职责，并把领域状态带回 React。标准化动作由 runtime service 提供，slot 只注入呈现所需的窄接口。
+**由呈现层或 root Zustand store 编排对象生命周期。** 该方案会重复 Manager 与服务的职责，并把领域状态带回 React。标准化动作由 runtime service 提供，slot 只注入呈现所需的窄接口。
 
-**零态立即创建 Host Session 或 Host persistence intent。** 未输入页面会进入 Host 生命周期，并改变刷新语义；前端 Session 在首次发送前只保留 page-local Intent。
+**零态立即创建 Host Session 或 Host 持久化 Intent。** 未输入页面会进入 Host 生命周期，并改变刷新语义；前端 Session 在首次发送前只保留 page-local Intent。
 
-**显式 Create Workspace 延迟到首次发送。** 用户确认后 sidebar 仍看不到真实空 Workspace，“创建 Workspace”与“准备 Session”语义混合；只有系统自动产生的零 Workspace Intent 延迟 materialize。
+**显式 Create Workspace 延迟到首次发送。** 用户确认后 sidebar 仍看不到真实空 Workspace，「创建 Workspace」与「准备 Session」语义混合；只有系统自动产生的零 Workspace Intent 延迟 materialize。
 
 **持续按 cwd 动态派生 Workspace。** 该方案无法表达空 Workspace、稳定显示名和显式顺序，也会自动收编非 Workspace 调用方；cwd 只用于一次历史 bootstrap 与成员双向校验。
 
@@ -104,7 +104,7 @@ Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSe
 
 - 完全无 Workspace 的零态不写 Host 且允许输入；显式 Create Workspace 立即创建并显示空 Workspace。
 - 前端 Session 与 Workspace 在 materialize 前后保持对象身份，输入、错误、焦点和 sidebar 投影始终来自对象层。
-- 首发按 Workspace、Session、prompt 顺序推进，各成功阶段不回滚，输入在 prompt 接受前不丢失，创建重试使用同一 SessionId。
+- 首发按 Workspace、Session、提示词顺序推进，各成功阶段不回滚，输入在提示词被接受前不丢失，创建重试使用同一 SessionId。
 - Workspace list 只读取 header 完成一次可重入 bootstrap；initialized 的空 registry 重启不重复初始化，成员读取同时校验索引与 canonical cwd。
 - 初始默认目标只在两份基线 ready 后确定一次；Workspace 组不因 hydration 或 Session 活跃整体重排，单个活跃 Session 只前移自身。
 - 真实 Workspace 下的前端 Session 临时计入 sidebar 数量，Workspace Intent 保持隐藏，发布与刷新都不会留下重复行或重复计数。
@@ -116,6 +116,6 @@ Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSe
 
 - SessionHeader 不记录最后活跃时间，历史 bootstrap 只能按 `createdAt` 初始化；此后由真实 Session 活跃事件逐项前移。
 - 历史 cwd 缺失、目录无效或 realpath 失败的 Session 留在 Ungrouped；本期没有手动收编入口。
-- 页面刷新会丢弃未 materialize 的 Workspace/Session Intent 和尚未被 Host 接受的输入，这是 page-local 契约。
+- 页面刷新会丢弃未 materialize 的 Workspace/Session Intent 和尚未被 Host 接受的输入，这是 page-local 约定。
 - 显式 Create Workspace 立即落盘，用户不发送就离开也会留下空 Workspace。
 - Host Session 在首个事件前仍遵循现有懒持久化语义；前端 Intent 不改变 Host 重启后的空 Session 行为。
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
index 8a92dd2fd1..43076fbfe4 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
 2026-07-26-todo-parallel-in-progress.md: 8d047f33ab1aebd8c0de2a0a5e90e7efb1b28154
-2026-07-26-todo-parallel-in-progress.zh.md: 26b7081e7b4e3688a46a2857da91ba45328532a9
+2026-07-26-todo-parallel-in-progress.zh.md: 64047e8b27e779e6ca23ea6c435bcdfecf38066d
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
index 26b7081e7b..64047e8b27 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 把单一 `in_progress` 上限从固定规则改为部署策略，并要求每个组合都作出选择：
 
-- `packages/todo/tool-todo/src/index.ts` 新增必填的 `Config.allowParallelInProgress` 字段。为 `true` 时，`execute` 接受任意数量的活跃条目，描述指示模型把每个正在处理的任务标记为 `in_progress`（并行工作时可以有多个，顺序工作时只有一个），并在仍有工作未完成时至少保留一个；为 `false` 时，描述要求恰好一个，`execute` 拒绝标记更多的调用。
+- `packages/todo/tool-todo/src/index.ts` 新增必填的 `Config.allowParallelInProgress` 字段。为 `true` 时，`execute` 接受任意数量的活跃条目，描述指示模型把每个正在处理的任务标记为 `in_progress`（并行工作时可以有多个，顺序工作时只有一个），并在仍有工作未完成时至少保留一个；为 `false` 时，描述要求恰好一个，`execute` 拒绝标记多个活跃条目的调用。
 - `packages/todo/tool-todo/src/invariant.ts` 中的持久日志不变式不再拒绝含多个活跃条目的快照，且不跟随该配置，因此此前持久化的日志不受影响，并行快照在任一策略下都能干净回放。
 
 其余编码的不变式保持不变：`content` 去除首尾空白后非空且唯一、status 为合法枚举值。本决定取代[原始设计的校验决策](2026-06-29-todo-write-tool.md)中「至多一个活跃」的条款；该 Agent Note 的其余部分（整列表替换、日志支撑的状态、单一所有者）依然成立。
@@ -23,7 +23,7 @@ Status: implemented
 
 ## 该策略是部署层的选择
 
-并发的活跃任务是否合理，取决于工具无法观测的运行时并发情况——但一个部署的 agent 是否会并发展开工作，在组装期就是可知的。因此该策略是必填的 `Config` 字段，而非常量或默认值：每个 cordis.yml 组合都会有意设置 `allowParallelInProgress`，为可能并行展开工作的 agent 选择 `true`，或为单活跃项纪律选择 `false`。
+并发的活跃任务是否合理，取决于工具无法观测的运行时并发情况——但一个部署的 agent（智能体）是否会并发展开工作，在组装期就是可知的。因此该策略是必填的 `Config` 字段，而非常量或默认值：每个 cordis.yml 组合都会有意设置 `allowParallelInProgress`，为可能并行展开工作的 agent 选择 `true`，或为单活跃项纪律选择 `false`。
 
 该开关会同时改变面向模型的指令与接受的输入。把两者拆开才是 bug：描述要求只保留一个活跃任务、而 `execute` 却接受多个，等于教给模型一条工具并不遵守的规则；反过来则会拒绝描述所邀请的调用。描述中只有活跃状态那一句会变化，因为这是该策略唯一改变的指令。
 
@@ -37,18 +37,18 @@ Status: implemented
 
 ## 展示面是本次改动的一部分
 
-解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本分支 stack（栈叠）在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个 PR 的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。面板重做把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本分支仍需修的那一处。
+解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本分支 stack（栈叠）在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个 PR（Pull Request）的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。面板重做把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本分支仍需修的那一处。
 
 工具行改用 `toolviews/plan-summary.ts` 中的 `planSummary`。它给出第一个活跃条目，并计数其余活跃项，因此工具行报告的是有多少任务在跑，而不是暗示只有一个。列出全部活跃条目被否决了：工具行是单行，无上界的拼接会溢出——在列表做不到的地方，计数能够可预测地降级。该推导放在 toolviews 域内而非 `contract/`（域间共享面）：面板自行内联计算其计数，与工具行不共享任何东西，因此放进 contract 会声明一种已不存在的共享关系。
 
-`planSummary` 把任务名与计数作为两个独立字段返回，而不是一个拼好的字符串，因为工具行用 `overflow: hidden` / `text-overflow: ellipsis` 截断其摘要文本。计数接在任务名之后时位于可截断文本的末端，于是恰恰是让计数变得有意义的那些场景——窄视口、长任务名——会把它裁掉，让并行计划看起来与顺序计划无异。因此工具行把计数交给共享的 `ToolRow`，作为 `summarySuffix`——一个紧邻被省略号截断的摘要文本、且不会收缩的槽位；一个预先拼好的字符串无法表达这个切分，而把计数放到任务名之前也被否决了：读者首先要找的是任务名。
+`planSummary` 把任务名与计数作为两个独立字段返回，而不是一个拼好的字符串，因为工具行用 `overflow: hidden` / `text-overflow: ellipsis` 截断其摘要文本。计数接在任务名之后时位于可截断文本的末端，于是恰恰是让计数变得有意义的那些场景——窄视口、长任务名——会把它裁掉，让并行计划看起来与顺序计划无异。因此工具行把计数交给共享的 `ToolRow`，作为 `summarySuffix`——一个紧邻被省略号截断的摘要文本、且不会收缩的slot；一个预先拼好的字符串无法表达这个切分，而把计数放到任务名之前也被否决了：读者首先要找的是任务名。
 
-`summarySuffix` 是 `ToolRow` 上的槽位，而不是 todo 工具行自有的标记：每个 toolview 都经由这个共享组件渲染，而它的 `summary` 是一个会被省略号截断的普通字符串，容不下一个必须挺过截断的片段。该后缀落在 `.summary` 规则之外，因此重复了该规则的 `font-size` 与 `line-height`——Web 外壳把正文字号留在浏览器默认值而非该行的 14px，所以未加样式的 span 会明显大于同一 24px 行内与之并列的文本。错误行会丢弃该后缀，因为它折叠态的摘要是失败行，而非任何由调用 args 推导出的内容。
+`summarySuffix` 是 `ToolRow` 上的slot，而不是 todo 工具行自有的标记：每个 toolview 都经由这个共享组件渲染，而它的 `summary` 是一个会被省略号截断的普通字符串，容不下一个必须挺过截断的片段。该后缀落在 `.summary` 规则之外，因此重复了该规则的 `font-size` 与 `line-height`——Web 外壳把正文字号留在浏览器默认值而非该行的 14px，所以未加样式的 span 会明显大于同一 24px 行内与之并列的文本。错误行会丢弃该后缀，因为它折叠态的摘要是失败行，而非任何由调用 args 推导出的内容。
 
 ## 暂缓项
 
-两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试契约的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
+两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试约定的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
 
 ## 后果
 
-现在 todo 列表可以忠实反映并行执行，并且每个展示面都能一次渲染多个活跃标记：计划横条的表头会计数活跃条目，工具行则需要上述推导。设置 `allowParallelInProgress: true` 的组合不再拒绝一种此前无效的快照形状；设置为 `false` 的组合仍保留旧的拒绝行为，而持久日志不变式两者都接受。面向模型的描述发生了变化，这重新记录了 tool-catalog 页面以及每个带有 todo schema 的快照 sidecar。此处不记录数量：该集合会随每个新落地的 pin 场景增长，而本 Note 先前记过的两次点时刻计数都在几天内失实。有效规则是：改动工具描述的分支必须刷新它分叉之后落地的那些 sidecar —— 包括固定 subagent 类工具的编号文件 `tool-schemas.<n>.expected.json`，其 schema 不被父场景覆盖 —— `pnpm run test:snapshot:refresh` 可以无 key 地对整个语料完成刷新。web fixture 的 todo 样本现在有两个条目处于 `in_progress`，因此两个由 fixture 驱动的展示面渲染的都是并行计划。`packages/client/ui-conversation/tests/todo-panel.spec.tsx` 在 src 上固定工具行摘要与计划横条，ACP `todo-write` 场景录制的是三条目、两个活跃的计划，而 `apps/web/tests/todo-row.snapshot.ts` 在组装后的应用中固定这两个面——它从构建产物 `packages/client/*/lib/client.js` 启动，因此是唯一覆盖 keyed 注册与打包接线的地方。该文件把 `summary`、`suffix` 与横条表头记录为独立字段，因此即便拼接后的文本读起来一样，把 `+N` 计数折回摘要字符串也会改变预期输出。
+现在 todo 列表可以忠实反映并行执行，并且每个展示面都能一次渲染多个活跃标记：计划横条的表头会计数活跃条目，工具行则需要上述推导。设置 `allowParallelInProgress: true` 的组合不再拒绝一种此前无效的快照形状；设置为 `false` 的组合仍保留旧的拒绝行为，而持久日志不变式两者都接受。面向模型的描述发生了变化，这重新记录了 tool-catalog 页面以及每个带有 todo schema 的快照伴随文件。此处不记录数量：该集合会随每个新落地的 pin 场景增长，而本 Agent Note 先前记过的两次时点统计都在几天内失实。有效规则是：改动工具描述的分支必须刷新它分叉之后落地的那些伴随文件——包括固定 subagent 类工具的编号文件 `tool-schemas.<n>.expected.json`，其 schema 不被父场景覆盖——`pnpm run test:snapshot:refresh` 可以无 key 地对整个语料完成刷新。web fixture（测试前置数据）的 todo 样本现在有两个条目处于 `in_progress`，因此两个由 fixture 驱动的展示面渲染的都是并行计划。`packages/client/ui-conversation/tests/todo-panel.spec.tsx` 在 src 上固定工具行摘要与计划横条，ACP（Agent Client Protocol）`todo-write` 场景录制的是三条目、两个活跃的计划，而 `apps/web/tests/todo-row.snapshot.ts` 在组装后的应用中固定这两个面——它从构建产物 `packages/client/*/lib/client.js` 启动，因此是唯一覆盖 keyed 注册与打包接线的地方。该文件把 `summary`、`suffix` 与横条表头记录为独立字段，因此即便拼接后的文本读起来一样，把 `+N` 计数折回摘要字符串也会改变预期输出。
diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
index dade9b5d90..3d0e167856 100644
--- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-native-workspace-directory-picker.md
 2026-07-27-native-workspace-directory-picker.md: a36f7b239a9115fe5eb33472ec5084818a66e9f2
-2026-07-27-native-workspace-directory-picker.zh.md: bb3e2fc6f7c77c8ace97e53435297326f937e4e8
+2026-07-27-native-workspace-directory-picker.zh.md: e45d45a95b27b19d573d6bd709357d08a2e2f3fc
diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
index bb3e2fc6f7..e45d45a95b 100644
--- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 工作区管理器必须在选择回调运行前插入或更新返回的工作区。因此，新纳入的目录会立即显示其 basename。再次打开已注册的路径时，则保留该工作区现有的标题。
 
-## 交互契约
+## 交互约定
 
 - 在 macOS、Windows 和 Linux 上，选择器一次只允许选择一个目录。
 - 取消系统对话框不会显示提示，并返回 `null`。
@@ -27,7 +27,7 @@ Status: implemented
 
 只有来自回环套接字、且携带同源浏览器元数据的请求才能调用原生对话框 RPC。该 RPC 不使用默认的 30 秒请求超时，因为系统对话框可能无限期保持打开；调用方中止或连接中止仍会传递至平台进程。
 
-平台适配器不经 shell 打开对话框——POSIX 上 spawn 原生工具，Windows 上是子进程 COM 会话：
+平台适配器不经 shell 打开对话框——POSIX 上 spawn 原生工具，Windows 上进行进程内 COM 交互：
 
 - macOS：`osascript` 和系统文件夹选择器。
 - Windows：koffi `IFileOpenDialog` 子进程，使用宿主接受的最佳线程 DPI 感知（可用时为 per-monitor-v2；不支持 PMv2 的主机级联到 per-monitor 或 system-aware）（见[进程内对话框 Note](2026-08-02-win32-in-process-folder-dialog.md)）；该层无回退——失败原样上报（见[PowerShell 链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）。
diff --git a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
index b0e6012183..551a34b48f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-skill-catalog-hot-refresh.md
 2026-07-27-skill-catalog-hot-refresh.md: 43c2da75aeb0031dffb5f47d7e76805baa2920e5
-2026-07-27-skill-catalog-hot-refresh.zh.md: 04d39dd767e5438c57d3eb29523a8ff26592465c
+2026-07-27-skill-catalog-hot-refresh.zh.md: 60b08cd7b82dfe4edc5f8136d756df2c9097b3fe
diff --git a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
index 04d39dd767..60b08cd7b8 100644
--- a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
@@ -12,13 +12,13 @@ skill（技能）摘要是模型的路由输入，但本地 skill 可在会话
 
 ## 决策
 
-skill 服务将目录成员关系与指令正文加载分离。`ctx.skills.snapshot()` 返回摘要及一个完整性位。`ctx.skills.registerProvider(factory)` 会向同步工厂提供一项注册作用域内的 `{ signal, invalidate }` 控制能力：`invalidate()` 只会将该精确活动注册标记为脏，并丢弃已完成目录缓存；注册失败或释放时，信号会中止。提供方返回的数组是完整发现的简写形式；显式的不完整观测可以保留可读候选项供直接加载，但不能缓存，也不能作为面向模型消费方的权威结果。在发现期间，如果提供方或运行时 generation 发生变化，系统会重试一次；如果这次重试也被后续修订取代，则最新候选项会作为不完整且不缓存的观测返回。资源释放或替换后的延迟失效操作不会执行任何操作，因为该能力已被撤销。
+skill 能力将目录成员关系与指令正文加载分离。`ctx.skills.snapshot()` 返回摘要及一个完整性位。`ctx.skills.registerProvider(factory)` 会向同步工厂提供一项注册作用域内的 `{ signal, invalidate }` 控制能力：`invalidate()` 只会将该精确活动注册标记为脏，并丢弃已完成目录缓存；注册失败或 dispose（资源释放）时，信号会中止。提供方返回的数组是完整发现的简写形式；显式的不完整观测可以保留可读候选项供直接加载，但不能缓存，也不能作为面向模型消费方的权威结果。在发现期间，如果提供方或运行时 generation 发生变化，系统会重试一次；如果这次重试也被后续修订取代，则最新候选项会作为不完整且不缓存的观测返回。dispose 或替换后的延迟失效操作不会执行任何操作，因为该能力已被撤销。
 
 `@deepseek-ai/dsh-skill-local` 直接依赖 Chokidar，并观察与目录相关的宿主路径。已有根目录会监视其直属 skill bundle 目录、平铺的 Markdown 条目和直属 `SKILL.md` 条目文件。新增、移除和目录变更会使成员关系失效；文件变更还支持刷新 frontmatter 中的 `name` 和 `description`。bundle 内更深层的资源文件会被忽略。同一微任务批次中的事件会合并为一次失效。项目 watcher 使用有界集合，并按最久未观察顺序淘汰。
 
 系统从缺失根目录最近的现有祖先开始，使用 `fs.watchFile` 每次跟进一层缺失路径片段；真实根目录出现后，再交给 Chokidar。每次发现操作都会在扫描前重新探测所保留的根目录／祖先模式。即使子项移除在根目录 `unlinkDir` 事件之前就触发失效并发布权威空目录，或者该事件根本没有到达，这项独立探测也会在删除后重新建立祖先观察。Chokidar 配置公开原生事件或轮询模式、写入稳定性、轮询间隔、符号链接跟随选项和项目 watcher 容量。第一方 `write` 和 `edit` 工具观察会同步使相关提供方失效，因此下一个模型步骤无需等待宿主事件投递，就能看到自身改动。watcher 启动或运行失败会被记录并触发重试；发现过程仍会返回可读候选项供直接加载，但会报告不完整观测。资源销毁会关闭 watcher，并忽略延迟回调。
 
-`@deepseek-ai/dsh-tool-skill` 在首次观察到非空完整目录且返回 enter 的 `agent/pre-step` 中，贡献一条带来源的 `UserMessage`。每次 pre-step，它都会应用 `skill` 工具的精确可见性，对 `<available_skills>` 标签之间精确渲染的文本计算哈希，并从后向前扫描只读会话事件且不复制，以查找该插件发布的最新一条可识别且仍可见的目录。digest 变化时，插件会向 enter 决策贡献完整替换目录；所有 skill 消失时也包含显式空目录，reject 或监听器失败则不记录任何内容。如果没有目录仍然可见，但历史事件中存在可识别目录，则说明压缩（compaction）已将其遮蔽，下一次完整且进入步骤的观察会重新建立当前目录，包括空 tombstone。如果当前目录为空且历史上从未发布目录，则不发送任何内容；不完整快照则保留最后一次完整的模型视图。反向扫描通常在最新且仍可见的目录处停止；当压缩遮蔽所有目录时，它会以一次 O(session-events) 扫描的成本确认这一事实。
+`@deepseek-ai/dsh-tool-skill` 在首次观察到非空完整目录且返回 enter 的 `agent/pre-step` 中，贡献一条带来源的 `UserMessage`。每次 pre-step，它都会应用 `skill` 工具的精确可见性，对 `<available_skills>` 标签之间精确渲染的文本计算哈希，并从后向前扫描只读会话事件且不复制，以查找该插件发布的最新一条可识别且仍可见的目录。digest 变化时，插件会向 enter 决策贡献完整替换目录；所有 skill 消失时也包含显式空目录，reject 或监听器失败则不记录任何内容。如果没有目录仍然可见，但历史事件中存在可识别目录，则说明压缩（compaction）已将其遮蔽，下一次进入步骤时的完整观测会重新建立当前目录，包括空 tombstone。如果当前目录为空且历史上从未发布目录，则不发送任何内容；不完整快照则保留最后一次完整的模型视图。反向扫描通常在最新且仍可见的目录处停止；当压缩遮蔽所有目录时，它会以一次 O(session-events) 扫描的成本确认这一事实。
 
 TUI 将同一失效通知作为界面状态而非会话历史来消费。`skills/change` 不携带 diff；TUI 会为活动会话的 cwd 重新获取 `snapshot()`，仅应用最新的完整结果，并在观测不完整时保留先前命令。完整的空结果会清除陈旧补全项。pi-tui 在其提供方被替换时会关闭自动补全，因此如果目录在用户输入斜杠命令名称期间到达，还会触发一次仅用于更新建议的当前草稿重查。
 
@@ -33,10 +33,10 @@ TUI 将同一失效通知作为界面状态而非会话历史来消费。`skills
 - **将实时目录放入 World State**：不予采纳，因为目录替换是模型可见的会话输入，必须能够从事件日志重建。持久注入历史已经提供回放、恢复、fork 和压缩语义，无需再引入一套可变状态层。
 - **只依赖 `fs/observed`**：不予采纳，因为 IDE、Git、shell 命令和外部进程都不会经过该 seam。该事件仍作为第一方工具的低延迟快速路径，宿主监视则补齐覆盖。
 - **为每个 `SKILL.md` 正文计算哈希或版本**：不予采纳，因为模型最初只看到名称和描述，提供方已经在每次工具调用时重新读取正文。正文修订会产生目录流量，却不会改变路由，也不足以成为改写历史工具结果的理由。
-- **监视每个 bundle 资源**：不予采纳，因为参考资料、脚本和产物都是按需加载的，不影响类别列表。宽泛的递归监视会增加失效、描述符压力和平台差异，却不能改善路由。
+- **监视每个 bundle 资源**：不予采纳，因为参考资料、脚本和资源都是按需加载的，不影响类别列表。宽泛的递归监视会增加失效、描述符压力和平台差异，却不能改善路由。
 - **将部分发现或失败发现发布为新目录**：不予采纳，因为暂时读取失败不能证明文件已删除。完整性位让面向模型的消费方保留最后一次完整目录，直到完整观察成功。
-- **保留公开的 `invalidateProvider(provider)`**：不予采纳，因为这会公开一项注册表变更方法，并要求调用方重复提供注册表已经持有的身份。发给工厂的闭包会将失效绑定到单个注册，并在释放后失去作用，因此观察方既不需要访问注册表，也不需要提供方身份。
-- **现在提取通用 Cordis 文件监视服务**：暂缓，直到另一个消费方确立可复用的服务契约。本地提供方标出了其 Chokidar 和缺失根目录观测边界，以便后续提取；skill 路径过滤以及对提供方失效闭包的调用仍属于 skill 专用逻辑。
+- **保留公开的 `invalidateProvider(provider)`**：不予采纳，因为这会公开一项注册表变更方法，并要求调用方重复提供注册表已经持有的身份。发给工厂的闭包会将失效绑定到单个注册，并在 dispose 后失去作用，因此观察方既不需要访问注册表，也不需要提供方身份。
+- **现在提取通用 Cordis 文件监视服务**：暂缓，直到另一个消费方确立可复用的服务约定。本地提供方标出了其 Chokidar 和缺失根目录观测边界，以便后续提取；skill 路径过滤以及对提供方失效闭包的调用仍属于 skill 专用逻辑。
 
 ## 影响
 
@@ -44,5 +44,5 @@ TUI 将同一失效通知作为界面状态而非会话历史来消费。`skills
 - TUI 的 `/skill:` 补全会收敛到同一份完整目录，而不会让每次按键都阻塞于发现；打开的斜杠命令名称草稿会在目录到达时刷新。
 - 目录消息采用仅追加、日志记录和全量列表快照。它们会保留较早的可重用 token；替换目录会显式停用陈旧名称，每次 digest 实际变化时，token 成本与当前目录大小成正比。
 - 仅修改正文不会产生目录消息。后续工具调用会看到当前内容，而先前工具结果仍准确记录模型之前加载的内容。
-- 缺失根目录轮询和 Chokidar 引入一个有人维护的运行时依赖、宿主 watcher 资源、有界检测延迟和部署可调参数。有界项目集合与资源销毁契约会限制这些成本。
+- 缺失根目录轮询和 Chokidar 引入一个有人维护的运行时依赖、宿主 watcher 资源、有界检测延迟和部署可调参数。有界项目集合与资源销毁约定会限制这些成本。
 - 远程或未来的可变提供方会保留各自注册作用域内的失效闭包，并通过自身观察机制调用它；注册表不会强制采用通用 watcher 或 TTL。
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
index 71c2325bb3..ba3cd5180e 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-trajectory-inspection-ledger.md
 2026-07-27-trajectory-inspection-ledger.md: e3fc22234c1df449c99eac90af27de7da0b6f202
-2026-07-27-trajectory-inspection-ledger.zh.md: abf8fd3bcaeabba6061bd415acbe8ddefef7ac79
+2026-07-27-trajectory-inspection-ledger.zh.md: 736523ebb02b8ea3c6e4cdbf9bc27f67779c7426
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
index abf8fd3bca..736523ebb0 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：轨迹检查记录表
+# Agent Note: 轨迹检查记录表
 
 Status: implemented
 
@@ -16,13 +16,13 @@ Status: implemented
 - 事件类型与内容构成两个稳定列。角色标签朝内容侧对齐，嵌套子工具略微缩进，内容预览使用 CSS 截断以适应可用宽度。token 用量和耗时留在检查器中。
 - 产品正文使用现有无衬线字体栈。轮次 id、token 数、耗时、工具调用、原始载荷和其他机器数据使用现有代码字体栈。
 - 现有主题 token 同时负责亮色和暗色渲染。中性边框与表面构成整体结构；区分度较低的角色色帮助扫读而不表达成功或失败语义，业务蓝色则标识选择状态、链接和焦点。
-- 客户端 runtime 提供独立于 Session 和 SessionManager 的只读历史数据源。每个已激活的数据源自行拥有原始条目、分页、实时缺口修复和重连重建；普通会话快照仍然只是 Chat 所需的折叠投影。Trajectory 在挂载期间打开该数据源的尾部，当用户到达已加载范围顶部时请求一页更早的历史，再按需派生事件顺序、上下文谱系、schema 索引和请求，避免让所有会话消费者承担这些结构。
-- 普通生成调用与压缩调用形成一条按时间排序的请求投影，以 purpose 区分而不是放入不同集合。生效的提示词状态及其变化附着在引入它们的请求上；压缩和提示词变化都不是独立检查实体。请求编号和累计用量覆盖已加载的历史窗口，并随更早页面到达而扩展。
+- 客户端运行时提供独立于 Session 和 SessionManager 的只读历史数据源。每个已激活的数据源自行拥有原始条目、分页、实时缺口修复和重连重建；普通会话快照仍然只是 Chat 所需的折叠投影。Trajectory 在挂载期间打开该数据源的尾部，当用户到达已加载范围顶部时请求一页更早的历史，再按需派生事件顺序、上下文谱系、schema 索引和请求，避免让所有会话消费方承担这些结构。
+- 普通生成调用与压缩调用形成一条按时间排序的请求投影，以用途区分而不是放入不同集合。生效的提示词状态及其变化附着在引入它们的请求上；压缩和提示词变化都不是独立检查实体。请求编号和累计用量覆盖已加载的历史窗口，并随更早页面到达而扩展。
 - 调用 schema 来自当前生效且已记录的请求头。无密钥快照 fixture（测试前置数据）有意将该目录替换为非数组 token `{{tools}}`，持久化检查边界会将其视为不可用，而不是尝试投影或虚构 schema。
-- 选择记录或请求后，轨迹视图内部会打开检查器，其标签页和概览区域随实体类型变化：Markdown 消息提供渲染、源码、来源和层级视图；工具提供 JSON 载荷／结果和 schema 视图；请求提供选项、用量、计时和结果跳转。可滚动的概述区域默认保持滚动条滑块透明，直到悬停或 `focus-within` 时才显示，同时保留滚动条预留空间和滚动行为。图片以媒体形式渲染，而不是显示为序列化数据。
-- 折叠轮次时保留其第一条记录，将后续行替换为紧凑的步骤和工具调用数量；折叠助手时对其工具调用后代应用相同交互。全局控件可以分别折叠或展开这两个层级。
+- 选择记录或请求后，轨迹视图内部会打开检查器，其标签页和概述区域随实体类型变化：Markdown 消息提供渲染、源码、来源和层级视图；工具提供 JSON 载荷／结果和 schema 视图；请求提供选项、用量、计时和结果跳转。可滚动的概述区域默认保持滚动条滑块透明，直到悬停或 `focus-within` 时才显示，同时保留滚动条预留空间和滚动行为。图片以媒体形式渲染，而不是显示为序列化数据。
+- 折叠轮次时保留其第一条记录，将后续行替换为紧凑的步骤数和工具调用数；折叠助手时对其工具调用后代应用相同交互。全局控件可同时折叠或展开这两个层级。
 - 长记录表初始时将已加载尾部置于底部，只挂载视口对应的行窗口及有界的额外缓冲行。仅含请求的分隔行并入下一个具备可测高度的虚拟项，末尾分隔行则保留固定留白，因此虚拟化器不会管理零高度项。可安全用于 DOM 的语义行键与 ARIA 索引使标识不依赖挂载位置。只要已知尾部之前仍有更早历史，即使当前已加载投影低于常规行数阈值，也会立即启用虚拟化。基于稳定键的虚拟化器锚定会在向前补页和尾部追加时保留当前可见项；只有分页完成导致虚拟化停用时，才使用手动滚动高度兜底。选择、时间线聚焦、折叠、搜索和末尾跟随均按稳定的事件或工具调用标识定位，不要求对应 DOM 行已存在。初始定位完成前以及更早页面仍在等待时，明确的加载行会遮住真实记录。原始窗口的基准序号即使在一页未增加任何 surface 可见节点时，也能检测到这次向前补页。
-- 移除独立的 waterfall（瀑布式事件）标签页。固定在记录表上方的 Overview 区域将所有 `startedAt` 已知的已加载记录按各自耗时投影到三条语义计时轨道。仍有更早前缀尚未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会遮住截断边缘并加载一页更早历史，而不会为未知历史虚构耗时；悬停在该控件上会隐藏普通的时间线光标。已完成的助手时间条以首个非空 token 增量为分界，用不同颜色按真实比例表示 TTFT 与解码时间；计时不完整时退化为单一助手色。悬停 500 ms 后会显示精确起止时刻、总耗时、TTFT 和解码时间，而不依赖浏览器原生 tooltip 的延迟。向左或向右拖动会提交包含边界的区间筛选：任何活动区间与所选区间相交的记录都会保留，计时未知的记录会从聚焦后的记录表中移除，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除区间选择；右键拖动则只会平移已放大的 viewport，不会改变该选区。聚焦后，Overview 区域仍保留完整时间范围，以便在不失去方位的情况下调整或清除选择。
+- 移除独立的 waterfall（瀑布式事件）标签页。固定在记录表上方的 Overview 区域将所有 `startedAt` 已知的已加载记录按各自耗时投影到三条语义计时轨道。仍有更早前缀尚未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会遮住截断边缘并加载一页更早历史，而不会为未知历史虚构耗时；悬停在该控件上会隐藏普通的时间线光标。已完成的助手时间条以首个非空 token 增量为分界，用不同颜色按真实比例表示 TTFT 与解码时间；计时不完整时退化为单一助手色。悬停 500 ms 后会显示精确起止时刻、总耗时、TTFT 和解码时间，而不依赖浏览器原生 tooltip 的延迟。向左或向右拖动会提交包含边界的区间筛选：任何活动区间与所选区间任一边界重叠的记录都会保留，计时未知的记录会从聚焦后的记录表中移除，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除区间选择；右键拖动则只会平移已放大的 viewport，不会改变该选区。聚焦后，Overview 区域仍保留完整时间范围，以便在不失去方位的情况下调整或清除选择。
 - 实时历史更新仅在用户已经跟随记录表末尾时保留底部位置。向上滚动会清除跟随状态，因此流式分块和新追加的记录不会打断对旧记录的检查。末尾跟随与虚拟化器测量仅响应行键和高度，而非内容标识，因此仅含文本的流式帧既不会丢弃测量缓存，也不会重复执行 DOM 滚动写入。
 - token 流式输出会复用已完成历史的检查结果、布局、请求编号、Overview 投影和搜索结果。每个帧只追加当前未完成助手的单元格，并在查询处于激活状态时搜索这部分内容；文本与推理（reasoning）增量不会重新折叠或扫描已加载前缀，而消息完成、工具生命周期、压缩、`rewrite` 及其他结构事件会重建受影响的投影。在这些投影重建前，检查记录表会丢弃已完成步骤中没有任何投影读取的 token 载荷，但会保留首个可见 token 用于计时、保留所有用量分片用于核算，并保留未完成或中断步骤的所有分片；独立历史数据源仍保留原始条目。
 - 历史折叠只把已加载的 surface 事件重新编号为紧凑连续的输入并交给规范 surface manager，再将其节点映射回会话绝对序号。因此，结构事件会保留规范的替换校验，而无需重放 token 分片，也不会为未加载的序号实体化合成事件。
@@ -45,7 +45,7 @@ Status: implemented
 
 **复用全局 Chat 详情栏。** 不予采纳：这会让局部检查与会话导航耦合，还会使行点击意外改变另一个视图的状态。
 
-**由 Trajectory CSS 覆盖 composer seat。** 不予采纳：跨包（package）选择器会依赖生成类选择器的优先级和样式表顺序。显式视图标记让 seat 几何形状和活跃阶段优先级留在 `ConversationRoot` 中，而 Trajectory 只负责自身内部的避让空间。
+**由 Trajectory CSS 覆盖 composer seat。** 不予采纳：跨包选择器会依赖生成类选择器的优先级和样式表顺序。显式视图标记让 seat 几何形状和活跃阶段优先级留在 `ConversationRoot` 中，而 Trajectory 只负责自身内部的避让空间。
 
 **将计时保留在独立的 waterfall 标签页中。** 不予采纳：占位实现汇总的是节点数而非记录计时，并迫使用户离开想要聚焦的记录。保留完整时间范围的 Overview 区域让计时和筛选后的记录处于同一视觉上下文中。
 
@@ -53,4 +53,4 @@ Status: implemented
 
 ## 后果
 
-轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、来源、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表契约锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
+轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、来源、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表约定锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
index 5268ea62f9..228ee9daab 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-web-session-fork-actions.md
 2026-07-27-web-session-fork-actions.md: 578e59ec92e003fe5c8cdfe951a595f3a7371ecf
-2026-07-27-web-session-fork-actions.zh.md: d90124f6e6e164b0a1e0fce734f52976630cd848
+2026-07-27-web-session-fork-actions.zh.md: 30c6fbbe7930ab17ca707d8a8fa0d4fc288d150e
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
index d90124f6e6..30c6fbbe79 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Web session fork 操作
+# Agent Note: Web 会话 fork 操作
 
 Status: implemented
 
@@ -6,30 +6,30 @@ Status: implemented
 
 ## Problem
 
-Session store 已提供按完成轮前缀创建子会话的 fork 原语，但 Web 端没有一份统一的交互契约。Session 行菜单只能表达「从最新完成轮分支」，消息 IconActions 还需要表达「从这条消息所在轮分支」；如果两处各自解释边界、切换与失败行为，同一个用户动作会形成两套语义。把 fork 子会话嵌套在源会话下还会让新选中的子会话依赖祖先展开态才能看见，并削弱 workspace 的手动排序模型。
+会话存储已提供按已完成轮次前缀创建子会话的 fork 原语，但 Web 端没有一份统一的交互约定。会话行菜单只能表达「从最新已完成轮次分支」，消息 IconActions 还需要表达「从这条消息所在轮次分支」；如果两处各自解释边界、切换与失败行为，同一个用户动作会形成两套语义。把 fork 子会话嵌套在源会话下还会让新选中的子会话依赖祖先展开态才能看见，并削弱 workspace 的手动排序模型。
 
 ## Decision
 
 本决策中的消息资格部分由[已完成轮次尾部决策](../bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)收紧；共享运行时操作、注入归属、标题处理和同级列表决策仍然有效。
 
-Web 的 session 行菜单与消息 IconActions 共用 client runtime 的 `sessions.fork` 操作。Session 行传 `{ sessionId, increaseTitle: true }`，因此在源会话最后一个已完成轮次处分支；符合条件且位于已完成轮次尾部的消息传 `{ sessionId, atSeq: node.seq, increaseTitle: true }`，因此在以该消息结束的轮次处分支。`increaseTitle` 只由 client 消费：子会话进入本地列表后，client 把源会话持久化标题尾部的 `(N)` 或 `（N）` 递增并保留括号样式，无编号时追加 ` (1)`，没有持久化标题时不改名；Host fork 请求仍只有 `sessionId` 与可选的 `atSeq`。改名成功后调用方才打开子会话；fork 或改名失败时保持源会话与当前选择不变，改名失败时已创建的子会话仍留在列表中。
+Web 的会话行菜单与消息 IconActions 共用 client runtime 的 `sessions.fork` 操作。会话行传 `{ sessionId, increaseTitle: true }`，因此在源会话最后一个已完成轮次处分支；符合条件且位于已完成轮次尾部的消息传 `{ sessionId, atSeq: node.seq, increaseTitle: true }`，因此在以该消息结束的轮次处分支。`increaseTitle` 只由 client 消费：子会话进入本地列表后，client 把源会话持久化标题尾部的 `(N)` 或 `（N）` 递增并保留括号样式，无编号时追加 ` (1)`，没有持久化标题时不改名；Host fork 请求仍只有 `sessionId` 与可选的 `atSeq`。改名成功后调用方才打开子会话；fork 或改名失败时保持源会话与当前选择不变，改名失败时已创建的子会话仍留在列表中。
 
-`forkAt(seq)` 只在 ui-conversation 的 apply 注入层接触 session 服务，消息组件只回传事件 `seq`。Session 行同理只通过 ui-workspace 的注入回调发起操作；两个呈现包都不持有 session mutation 状态，也不复制 host 的边界求值。
+`forkAt(seq)` 只在 ui-conversation 的 apply 注入层接触会话服务，消息组件只回传事件 `seq`。会话行同理只通过 ui-workspace 的注入回调发起操作；两个呈现包都不持有 session mutation 状态，也不复制 host 的边界求值。
 
-Session lineage 不投影成列表层级。WorkSpace 模式按 `WorkspaceView.sessionIds` 的手动序把源会话与所有 fork 子会话显示为同级行，每行都可独立打开、搜索和拖拽；In one list 模式继续按 `updatedAt` 严格排序；Ungrouped 组在没有 workspace 账本时也按 recency 排序。`parentId` 仍用于 lineage 和后续查询，但不控制 session 列表可见性。
+会话 lineage 不投影成列表层级。WorkSpace 模式按 `WorkspaceView.sessionIds` 的手动序把源会话与所有 fork 子会话显示为同级行，每行都可独立打开、搜索和拖拽；In one list 模式继续按 `updatedAt` 严格排序；Ungrouped 组在没有 workspace 账本时也按 recency 排序。`parentId` 仍用于 lineage 和后续查询，但不控制 session 列表可见性。
 
 ## Alternatives considered
 
-**只接 session 行菜单。** 否决：用户在消息处已经选择了更精确的上下文，强迫其回到列表只能退化为最新完成轮，且已展示的消息分支图标会成为无响应控件。
+**只接会话行菜单。** 否决：用户在消息处已经选择了更精确的上下文，强迫其回到列表只能退化为最新已完成轮次，且已展示的消息分支图标会成为无响应控件。
 
-**只允许用户消息分支。** 否决：已定稿 assistant 内容同样有稳定事件 `seq`，host 会把它归入所属完成轮；让两个外观相同的分支按钮只有一个可用会制造不可见的行为差异。
+**只允许用户消息分支。** 否决：已定稿 assistant 内容同样有稳定事件 `seq`，host 会把它归入所属已完成轮次；让两个外观相同的分支按钮只有一个可用会制造不可见的行为差异。
 
 **按 `parentId` 把 fork 子会话嵌套在源会话下。** 否决：lineage 不是导航所有权；嵌套要求自动展开祖先才能看见当前项，并让子会话无法参与 workspace 的同级手动排序。
 
-**由消息组件直接调用 session 服务。** 否决：client 组件不得接触 `ctx` 或业务服务；注入回调让 mutation 留在 apply 世界，组件保持纯 props。
+**由消息组件直接调用会话服务。** 否决：client 组件不得接触 `ctx` 或业务服务；注入回调让 mutation 留在 apply 世界，组件完全由 props 驱动。
 
 ## Consequences
 
-用户可从 session 行或符合条件的已完成轮次尾部消息创建分支，两处最终走同一个 runtime/host 操作；消息点位保留精确事件边界，列表点位保留「最新完成轮」快捷语义。连续 fork 的标题按 `(1)`、`(2)` 递增，而不是重复追加 `(1)`；全角括号标题保持全角样式。所有 fork 子会话立即作为普通同级行出现，列表不再需要 session 展开状态、递归节点或 twist 控件。
+用户可从会话行或符合条件的已完成轮次尾部消息创建分支，两处最终走同一个 runtime/host 操作；消息点位保留精确事件边界，列表点位保留「最新已完成轮次」快捷语义。连续 fork 的标题按 `(1)`、`(2)` 递增，而不是重复追加 `(1)`；全角括号标题保持全角样式。所有 fork 子会话立即作为普通同级行出现，列表不再需要 session 展开状态、递归节点或 twist 控件。
 
-Fork 与子会话改名失败都保持静默并保留源选择，避免一个派生操作破坏当前阅读位置；该取舍也意味着 UI 暂不提供失败原因或重试入口。包级测试固定符合条件的消息 `seq` 转发、标题递增与同级列表派生，`apps/web/tests/message-actions.e2e.ts` 通过装配后的应用执行 assistant 消息分支与 session 行菜单分支。
+Fork 与子会话改名失败都保持静默并保留源会话的选中状态，避免一个派生操作破坏当前阅读位置；该取舍也意味着 UI 暂不提供失败原因或重试入口。包级测试固定符合条件的消息 `seq` 转发、标题递增与同级列表派生，`apps/web/tests/message-actions.e2e.ts` 通过装配后的应用执行 assistant 消息分支与 session 行菜单分支。
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
index 7701e5fcc7..d41e205703 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-web-session-search.md
 2026-07-27-web-session-search.md: 4c49c0e61ca1b15181e767e4f65353312f8a3e3f
-2026-07-27-web-session-search.zh.md: e9aa00656443e544bad623540d07ff785b1285ef
+2026-07-27-web-session-search.zh.md: 7f4cc9caf9738700ed5f24b3d0593f08d06117ac
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
index e9aa006564..7f4cc9caf9 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
@@ -10,17 +10,17 @@ Web 侧边栏会展示会话标题及其 Workspace 归属，但无法根据只
 
 ## 决策
 
-Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据库挂载 [`@deepseek-ai/dsh-session-query-sqlite`](../../../../packages/session-query/session-query-sqlite/README.md)。服务启动时处于 ACTIVE 状态，而其 `node:sqlite` 模块与连接私有句柄分别要到首次内容查询才会导入和打开。这让 Node 22 的启动输出在使用搜索前不会出现 SQLite 实验性警告，但并不承诺在首次搜索导入该模块时抑制警告。每个服务实例都独占自己的索引，因此并行 CLI 或 Web 调用可维持 SQLite 后端的单一所有者契约，又不会留下进程级派生文件。数据库从空状态启动，并在该首次查询时惰性对齐实时会话与持久化会话。它仍是与规范 JSONL 持久化相互独立的可丢弃派生索引。
+Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据库挂载 [`@deepseek-ai/dsh-session-query-sqlite`](../../../../packages/session-query/session-query-sqlite/README.md)。服务启动时处于 ACTIVE 状态，而其 `node:sqlite` 模块与连接私有句柄分别要到首次内容查询才会导入和打开。这让 Node 22 的启动输出在使用搜索前不会出现 SQLite 实验性警告，但并不承诺在首次搜索导入该模块时抑制警告。每个服务实例都独占自己的索引，因此并行 CLI 或 Web 调用可维持 SQLite 后端的单一所有者约定，又不会留下进程级派生文件。数据库从空状态启动，并在该首次查询时惰性对齐实时会话与持久化会话。它仍是与规范 JSONL 持久化相互独立的可丢弃派生索引。
 
 宿主网关通过现有的类型化 RPC 栈公开 `session.search`。它根据 `session.list` 使用的同一组可见摘要推导授权集合，向 `ctx.sessionQuery.searchSessions` 请求全局排序后的当前 surface `user/message` 和 `assistant/message` 匹配项，并持续消费提供方分页，直到获得 20 个已授权会话及一个前瞻项，或结果流耗尽。首个提供方页面请求 20 个命中；如果第一页返回 `SESSION_QUERY_INVALID_LIMIT`，页面大小会依次折半为 10、5、2、1，并在续传和陈旧世代重启中沿用探测所得的大小。每个命中的会话 id、最佳匹配会话 id、surface 和事件类型都会经过重新校验，其 snippet 才能离开宿主。发出的 snippet 最多包含 240 个 Unicode 码点；宿主与传输 schema 共用协议边界及码点安全的截断辅助函数，而传输 schema 会在客户端解析时独立强制执行 snippet 上限。将可能很大的授权集合排除在 SQLite 绑定之外，可避开可移植变量上限，同时保持全局排序。响应仍只有一个有界页面；`hasMore` 会指示 UI 提示用户缩小查询范围，而不是公开分页能力。陈旧的续传会丢弃当前尝试的部分结果、去重条目和游标，然后依据原始可见性快照从第一页重新开始。上限探测与陈旧重试共用 100 次提供方调用的限制（因此最多检查 2,000 个命中）；如果某页命中数超过其请求的上限、续传游标重复，或用尽该调用预算后结果流仍未耗尽，都会直接返回 `internal` 业务错误，不返回部分结果。载体信号会取消已被取代的工作，包括持久化列表枚举、分批受限执行的冷会话元数据 stat，以及每一次提供方调用；即使同时收到上限拒绝或陈旧拒绝，也以取消为准。查询服务缺失或索引／查询故障无法恢复时，仍作为业务错误处理，不会修改规范会话存储。
 
 [`WorkspaceBrowser`](../../../../packages/client/ui-workspace/README.md) 有意将元数据搜索与内容搜索保持独立。其默认界面文案为英文；输入框及防御性请求路径会移除 NUL，将查询限制在请求 schema 规定的 500 个 UTF-16 code unit 内且不会拆分 surrogate pair。非空白查询会立即从会话列表中计算不区分大小写的标题和 Workspace 子串匹配，在 250 ms 防抖后发起内容请求，在查询变化时中止前一请求，并忽略陈旧的完成结果。它先按新近程度排列本地匹配，再合并由后端排序且仅匹配内容的结果，按会话 id 去重；无论常规分组模式如何，最终都渲染为扁平列表。每一行显示标题、Workspace，并在存在时显示一行摘要片段。选择某一行只会打开对应会话，并保留查询条件；不会跳转至确切事件。
 
-结果上限是单一协议常量，而非逐连接状态。`SESSION_SEARCH_RESULT_LIMIT` 位于 `dsh-host-apiproxy` 中强制执行它的响应 schema 旁边，`SessionsService.searchResultLimit` 则把该常量重新公开给呈现插件。功能包要取用它，必须显式扩展 sessions 域的对外面：`ISessions`（即注入为 `ctx.sessions` 的那个面，也因此是测试运行时的 sessions 替身必须实现的面）在该上限旁声明了搜索动作。连接 handle 不携带它：逐连接字段会暗示该上限随传输层变化或由服务端协商，而 schema 固定的 `max` 恰恰禁止这一点，并且会让同一事实在同一模块内拥有两处归属。
+结果上限是单一协议常量，而非逐连接状态。`SESSION_SEARCH_RESULT_LIMIT` 位于 `dsh-host-apiproxy` 中强制执行它的响应 schema 旁边，`SessionsService.searchResultLimit` 则把该常量重新公开给呈现插件。功能要取用它，必须显式扩展 sessions 域的对外面：`ISessions`（即注入为 `ctx.sessions` 的那个面，也因此是测试运行时的 sessions 替身必须实现的面）在该上限旁声明了搜索动作。连接 handle 不携带它：逐连接字段会暗示该上限随传输层变化或由服务端协商，而 schema 固定的 `max` 恰恰禁止这一点，并且会让同一事实在同一模块内拥有两处归属。
 
-内容匹配沿用 SQLite 后端经过规范化的字面 token／短语语义。共享语义投影会排除推理（reasoning）块，因此 UI 搜索绝不会将模型的私有推理作为命中或 snippet 返回；派生索引的 schema 版本会随之前进，使现有持久化索引重建并移除先前的这些文档。FTS5 运算符只作为数据处理，此搜索界面不提供拼写错误纠正、模糊匹配、前缀匹配或任意子串扩展。特别是，`unicode61` 分词器可能将一段连续中文视作单个 token，因此不保证 `搜索` 之类的较短查询能匹配 `会话搜索功能` 的内部片段。标题与 Workspace 匹配仍采用普通的客户端子串匹配。
+内容匹配沿用 SQLite 后端经过规范化的字面 token／短语语义。共享语义投影会排除推理（reasoning）块，因此 UI 搜索绝不会将模型的私有推理作为命中或 snippet 返回；派生索引的 schema 版本会递增，使现有持久化索引重建并移除先前的这些文档。FTS5 运算符只作为数据处理，此搜索界面不提供拼写错误纠正、模糊匹配、前缀匹配或任意子串扩展。特别是，`unicode61` 分词器可能将一段连续中文视作单个 token，因此不保证 `搜索` 之类的较短查询能匹配 `会话搜索功能` 的内部片段。标题与 Workspace 匹配仍采用普通的客户端子串匹配。
 
-## 故障与可见性契约
+## 故障与可见性约定
 
 搜索绝不会扩大会话可见范围：没有可供服务的 cwd 的冷会话会被排除，原因与它们不出现在 `session.list` 中相同；只有 id 位于这条基线中的提供方命中才能离开宿主。被遮蔽事件和纯日志事件、消息内容之外的工具事件、错误、待办事项及其他追踪记录都不会产生 UI 命中结果。
 
@@ -29,8 +29,8 @@ Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据
 ## 曾考虑的替代方案
 
 - **在浏览器中扫描每个会话的历史记录**：不予采纳，因为这会让 UI 承担传输与折叠开销；除非加载冷态日志，否则还会漏掉这些日志；并会重复实现已经由 `ctx.sessionQuery` 负责的语义提取与源对齐。
-- **首版即加入 trigram 或模糊搜索**：不予采纳，因为这会改变索引大小、排序、短查询行为与产品预期。trigram 本身也无法解决双字查询。首版沿用现有后端契约，将召回扩展留作另一项基于度量结果的决策。
-- **返回事件地址并跳转至确切匹配位置**：本版不予采纳，因为对话虚拟化与稳定的事件导航需要单独的 UI 契约。会话级导航本身已有价值，无需让搜索与这项工作耦合。
+- **首版即加入 trigram 或模糊搜索**：不予采纳，因为这会改变索引大小、排序、短查询行为与产品预期。trigram 本身也无法解决双字查询。首版沿用现有后端约定，将召回扩展留作另一项基于度量结果的决策。
+- **返回事件地址并跳转至确切匹配位置**：本版不予采纳，因为对话虚拟化与稳定的事件导航需要单独的 UI 约定。会话级导航本身已有价值，无需让搜索与这项工作耦合。
 - **在侧边栏公开游标分页**：不予采纳，改为固定显示前 20 条结果并提示缩小查询范围；这样可使交互与取消状态保持有界。
 
 ## 后果
@@ -41,4 +41,4 @@ Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据
 
 ## 测试
 
-宿主测试将请求与响应校验、可见会话过滤、事件和 surface 过滤、结果与 snippet 边界、共享调用预算内的自适应提供方上限、沿用探测所得上限的陈旧世代重启、游标与跨页去重行为、取消优先级及故障映射固定为契约。SQLite 生命周期测试将启动时激活、首次搜索时的打开与失败、共享就绪状态以及未打开状态下的处置固定为契约；语义提取测试与 SQLite／fixture 搜索测试将排除仅存在于推理中的文本固定为契约。Node 22 兼容性门禁会构建 CLI 与 Web 产物，在移除环境级警告抑制并采用隔离的临时 home／提供方环境后，以普通 Node 启动随产品交付的 `dsh web`／`AppCLIEntry` 组合，等待启动完成并稳定，再沿随产品交付的信号路径对其执行 dispose（资源释放）。fixture（测试前置数据）、运行时与 UI 测试将以匹配位置为中心的有界 snippet、无状态委托、500 个 code unit 的查询边界、防抖／中止／陈旧响应行为、本地回退、合并顺序、去重、英文文案、ARIA 树成员关系、行渲染与导航语义固定为契约。无密钥的组装层 Web 测试会在保留惰性打开配置的同时，播种一段尚未打开的持久化对话，通过 SQLite 索引按可见消息内容找到它，捕获侧边栏结果，打开该会话，并验证查询条件仍然保留。
+宿主测试将请求与响应校验、可见会话过滤、事件和 surface 过滤、结果与 snippet 边界、共享调用预算内的自适应提供方上限、沿用探测所得上限的陈旧世代重启、游标与跨页去重行为、取消优先级及故障映射固定为约定。SQLite 生命周期测试将启动时激活、首次搜索时的打开与失败、共享就绪状态以及未打开状态下的 dispose（资源释放）固定为约定；语义提取测试与 SQLite／fixture（测试前置数据）搜索测试将排除仅存在于推理中的文本固定为约定。Node 22 兼容性门禁会构建 CLI 与 Web 产物，在移除环境级警告抑制并采用隔离的临时 home／提供方环境后，以普通 Node 启动随产品交付的 `dsh web`／`AppCLIEntry` 组合，等待启动完成并稳定，再沿随产品交付的信号路径对其执行 dispose。fixture、运行时与 UI 测试将以匹配位置为中心的有界 snippet、无状态委托、500 个 code unit 的查询边界、防抖／中止／陈旧响应行为、本地回退、合并顺序、去重、英文文案、ARIA 树成员关系、行渲染与导航语义固定为约定。无密钥的组装层 Web 测试会在保留惰性打开配置的同时，播种一段尚未打开的持久化对话，通过 SQLite 索引按可见消息内容找到它，捕获侧边栏结果，打开该会话，并验证查询条件仍然保留。
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index 4453cca8eb..1c35cafbef 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-web-subagent-conversations.md
 2026-07-27-web-subagent-conversations.md: 46c4949c56ebffe78e5ffda126a5784a1c648421
-2026-07-27-web-subagent-conversations.zh.md: 6b2d7bbec1133cdeb2d0cd31a6f9a43b068d21f5
+2026-07-27-web-subagent-conversations.zh.md: 4b5ff938550b6c452680e36331372db65bd6f3d7
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index 6b2d7bbec1..4b5ff93855 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 由会话支撑的 subagent 具有持久化身份、持久化 transcript（文本记录）与直接 child 目录，但普通会话谱系无法将它们与 fork 区分开，也无法证明其描述符 mode 与继续执行授权。否则，绑定到 agent（智能体）的通用 Host 操作可能在其直接 parent 继续执行 owner 之外恢复或驱动 child。
 
-浏览器必须遵守[可继续 subagent 契约](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)：一个可继续 child 在进程内最多只能有一项 Activation，只能通过确切的存活直接 parent 接受后续工作，并将 agent inbox 用作唯一的 FIFO。查看历史不得创建 Activation。inbox 消息一经接受，HTTP 调用方既不拥有其执行过程，也不会获得取消句柄。
+浏览器必须遵守[可继续 subagent 约定](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)：一个可继续 child 在进程内最多只能有一项 Activation，只能通过确切的存活直接 parent 接受后续工作，并将 agent inbox 用作唯一的 FIFO。查看历史不得创建 Activation。inbox 消息一经接受，HTTP 调用方既不拥有其执行过程，也不会获得取消句柄。
 
 UI 还必须保留[持久化目录](../../implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)的成员、mode 与 diagnostic。共享服务报告采用实时优先规则的语料活动状态，而 Web 投影会将其替换为确切 child Agent driver 的 `running` 或 `inactive` 状态。这两种活动状态都不是持久化结果，也不承诺继续执行会成功。
 
@@ -20,7 +20,7 @@ Web 产品通过页头操作公开选中会话中由会话支撑的直接 subage
 
 通用 Host 领域遵守同一所有权边界。`session.history` 与 `session.fork` 的源端会读取已附加 Session 或检查持久化存储，而不获取 Agent；history 从所检查的确切前缀归并冷态投影值，fork 则发布一个普通的独立会话。绑定到 Agent 的通用会话、命令与目标路由会对由会话支撑的 subagent 返回 `agent-busy`；显式 id 的 `session.create` 接纳与仅针对已附加会话的队列控件亦然。拒绝分类器接受粗粒度 `origin` 标记、会话自身后缀中的 `subagent/descriptor`，或 parent 对其确切的存活运行时所有权；这些信号只会阻止通用路径取得所有权，绝不取代目录 mode 或直接 parent 授权。
 
-停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)，该契约会暂停而非丢弃待处理工作。one-shot child 在 Web 端仍不可取消。
+停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)，该约定会暂停而非丢弃待处理工作。one-shot child 在 Web 端仍不可取消。
 
 本决策涵盖 Web 端发现、transcript 查看与经 parent 授权的用户继续交互。它不会让 subagent 成为用户独立所有的对象；这类产品仍然属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)。
 
@@ -28,14 +28,14 @@ Web 产品通过页头操作公开选中会话中由会话支撑的直接 subage
 
 Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-14602&p=f)、[层级展开](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-15917&p=f)与 [child 对话](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=388-18584&p=f)画框是非规范性的交互与视觉参考。本记录负责生命周期、协议与失败语义。
 
-| 设计意图 | 已交付契约 |
+| 设计意图 | 已交付约定 |
 | --- | --- |
 | 会话页头可打开紧凑的 child 列表。 | 触发器会汇总仅含 subagent 的完整后代谱系；树按服务顺序显示每个直接目录条目，包括已禁用的 diagnostic。 |
 | 选择一行会复用对话 UI。 | 已寻址历史绝不激活 child；只有 parent 存活的可继续行才保留普通输入框。 |
 | 嵌套 agent 会逐层展开。 | 每行携带一层 `hasChildren` 快照；展开时会立即预留已知直接后代行，随后仍只加载该行的直接目录，并保留其自身的 parent 地址。 |
-| 条目显示 label、状态、token 用量与活跃耗时，同时避免侧边栏条目重复。 | mode 与 `running`／`inactive` 活动状态会同时以文字和视觉呈现；可选 title、持久化 token 用量与活跃轮次耗时来自列表保留的投影值。紧凑耗时从一天起省略更小的单位，而悬停和无障碍名称仍保留精确的整秒数。`SessionHeader.origin` 会移除重复的导航条目，但不授予任何功能权限。 |
+| 条目显示 label、状态、token 用量与活跃耗时，同时避免侧边栏条目重复。 | mode 与 `running`／`inactive` 活动状态会同时以文字和视觉呈现；可选 title、持久化 token 用量与活跃轮次耗时来自列表保留的投影值。紧凑耗时从一天起省略更小的单位，而悬停和无障碍名称仍保留精确的整秒数。`SessionHeader.origin` 会移除重复的导航条目，但不授予任何能力。 |
 
-## 产品契约
+## 产品约定
 
 只有当完整的直接目录空响应与会话摘要投影相符，二者均表明没有已知的 subagent 后代时，才不显示页头操作。其触发器会统计经不间断的 `origin: 'subagent'` 谱系可达的每个已知会话摘要后代，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。由于普通侧边栏行会隐藏 origin 为 subagent 的会话，Workspace 浏览器会在每个可见的普通行上索引同一条不间断谱系：任何运行中的后代都会让该行显示蓝色活动指示器，并在悬停与无障碍文本中给出确切数量，同时不会把空闲 parent 描述为正在运行。普通 fork 会开启单独的聚合子树。待处理交互优先于 parent 的运行中状态；二者无论哪一项存在都会保持为主要状态，而后代活动则成为悬停与无障碍状态中的第二项。两者均不存在时，后代活动优先于未查看的完成提醒；最后一个运行中的后代停止后，该提醒会恢复。每个健康的直接目录行都携带读取时的 `hasChildren` 提示，该值只根据持久化 `origin: 'subagent'` 的直接谱系 header 派生；正常的健康与 diagnostic subagent 候选都会携带该标记，而普通 fork 不会。该预查不读取任何后代事件日志，展开后仍以描述符支撑的目录为权威依据。当摘要在该目录尚不存在时或在一次陈旧的空响应后确认已有后代时，该操作会保持可见，并且在打开它以刷新目录之前仅显示禁用的加载行；仅由摘要支撑的行绝不会提供导航能力。UI 会在交互前就省略已知叶子节点的展开控件；该提示不承诺 child 会一直是叶子。已展开的直接目录加载期间，已知谱系会为每个直接后代预留一行禁用的加载行，而不会递归获取后代目录。随后树会呈现可继续与 one-shot 行；one-shot 的可选 label 缺失时，回退到其会话 id。损坏、不受支持或不可用的候选仍以禁用的 diagnostic 行显示。
 
@@ -45,11 +45,11 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 选择一行后，系统会先记录其确切地址，再打开常驻客户端 `Session`。历史分页、事件 fold、工具渲染意图、title 与实时 mux 归并都会复用普通对话机制。面包屑导航使用目录 label，只会沿 `origin: 'subagent'` 行的父链接逐级回溯，包含第一个普通 owner，并让普通 fork 保持单层。从已寻址 subagent 创建 fork 时，会生成具有直接源谱系的普通 fork，并将其附加到最近拥有 Workspace 的祖先。目录是一棵 ARIA 树，支持懒加载式 ArrowRight／ArrowLeft 展开与折叠、线性 ArrowUp／ArrowDown 导航、Home／End、Escape 以及焦点恢复。
 
-one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
+one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
 
 已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
-## 宿主适配器与协议契约
+## 宿主适配器与协议约定
 
 `@deepseek-ai/dsh-host-apiproxy` 拥有浏览器安全的 `subagents` 域：
 
@@ -63,7 +63,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 普通 `session.history` 路由对于普通会话和 subagent 会话同样只执行观察，但它既不携带目录地址，也不授予继续执行权限。每条需要 Agent 的普通路由都会在恢复冷会话前经过共享所有权栅栏；`session.cancel` 与 `session.updateQueue` 会直接执行同一检查，因为它们有意只查询已附加的 Agent。
 
-适配器仍位于 `dsh-host-apiproxy`；`dsh-host-webserver` 仍作为载体。浏览器代码通过现有连接包（package）导入契约，绝不直接访问宿主 `ctx`，从而保持 [GUI RPC 分层](../../implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)。
+适配器仍位于 `dsh-host-apiproxy`；`dsh-host-webserver` 仍作为载体。浏览器代码通过现有连接包导入约定，绝不直接访问宿主 `ctx`，从而保持 [GUI RPC 分层](../../implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)。
 
 ## 客户端对象层与呈现
 
@@ -83,19 +83,19 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 **对已寻址 child 使用普通会话 API。** 不予采纳，因为通用历史不携带目录 mode 校验，而绑定到 Agent 的通用控件会有意拒绝 subagent，不会授予直接 parent 继续执行授权。
 
-**将适配器放入 webserver。** 不予采纳，因为目录与继续执行是通道无关的客户端功能；webserver 只承载已校验的消息。
+**将适配器放入 webserver。** 不予采纳，因为目录与继续执行是通道无关的客户端能力；webserver 只承载已校验的消息。
 
 **新建 UI 包。** 不予采纳，因为 `ui-subagent` 已经负责 Web subagent 引用，也是目录与已寻址 child 呈现的统一 owner。
 
 **自动恢复缺失的 parent。** 不予采纳，因为继续执行要求确切的存活直接 parent。child 导航不得改变 parent 生命周期。
 
-**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
+**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
 
 **只显示可继续 child。** 不予采纳，因为持久化目录有意描述由会话支撑的两种 mode。one-shot transcript 即使绝不接受后续消息，仍然有用。
 
 **根据谱系推断 mode 或侧边栏过滤。** 不予采纳，因为普通 fork 共享 `parentSession`。由描述符支撑的目录负责提供 mode；单独的 `origin` 标记只是低成本的导航分类器。
 
-**构建预先加载的递归树或专用目录流。** 就当前规模而言不予采纳。只读 header 的一层可展开性预查会在不读取后代事件的情况下保证点击前的稳定性，而展开仍是懒加载式权威直接 child 读取；现有 Host 帧会更新活动状态、恢复 parent 行的可展开性，并触发有界的成员刷新。
+**构建预先加载的递归树或专用目录流。** 就当前规模而言不予采纳。仅基于 header 的一层可展开性预查会在不读取后代事件的情况下保证点击前的稳定性，而展开仍是懒加载式权威直接 child 读取；现有 Host 帧会更新活动状态、恢复 parent 行的可展开性，并触发有界的成员刷新。
 
 **让 child 在 parent 消失后仍能独立交互。** 不予采纳，因为独立生命周期与用户所有权需要 side session 语义。
 
@@ -111,7 +111,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 ## 后果
 
 - 目录读取可能重新扫描持久化谱系与每个直接候选的描述符日志，但可展开性只复用该追踪中已有的后代 header；Web 活动基线会为每个健康行增加一次 Agent 注册表查找，随后使用现有实时帧，而 token 用量与耗时会复用投影基线和推送，无需按行读取日志，成员刷新则保持去抖动和单次并发。
-- parent 可用性、child 活动状态与 `hasChildren` 都是快照。列出之后，发布、dispose、其他发送方或其他进程都可能抢先改变状态；类型化提示词失败仍属预期行为。
+- parent 可用性、child 活动状态与 `hasChildren` 都是快照。列出之后，发布、dispose（资源释放）、其他发送方或其他进程都可能抢先改变状态；类型化提示词失败仍属预期行为。
 - child 可能在历史获取与 mux 订阅之间发布，因此现有序号归并也涵盖从冷态转为存活的已寻址路径。
 - 持久化 origin 会为 child header 与列表投影添加一个有意保持弱约束的产品分类字段；它不能变成授权捷径。
-- 除对正在运行的可继续 child 的当前轮次 Stop（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）之外，UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
+- 除对正在运行的可继续 child 的当前轮次 Stop（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）之外，UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index 82639d4aa8..cd3cdfe70c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
 2026-07-28-continuable-subagent-conversations.md: 56d9abb2b09577b2fba14b9a655a941417e0c493
-2026-07-28-continuable-subagent-conversations.zh.md: 77f497ceeef35dcc519242dca30c81759cc3b907
+2026-07-28-continuable-subagent-conversations.zh.md: 40b6cc3e4d1685192cbd29131ac6987df51a2aeb
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index 77f497ceee..40b6cc3e4d 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -1,4 +1,4 @@
-# Agent Note（agent 决策记录）：可继续的 subagent
+# Agent Note: 可继续的 subagent
 
 Status: implemented
 
@@ -54,7 +54,7 @@ inbox 接受消息前发生任何失败，操作都会在不返回任何 id 的
 
 空闲的历史会话没有 `AgentHandle`。第一条通过鉴权的 `next-turn` 投递会根据持久化会话恢复激活，并将消息提交到其 inbox。冷恢复使用经过身份认证的确切在线 parent Agent 执行鉴权；当该 parent 有激活时，还使用它建立所有权，但绝不使用 parent 执行重建。
 
-激活作为消费方会直接持有已发布的 `AgentHandle` 直至结算，而管理器的私有 activation-owner 作用域则是其 Cordis 结构化所有者。可继续 subagent 路径不创建任何中间的带结果执行包装层，包括 `SubagentRun`；一次性委派保持不变，且不属于该生命周期。远程提供方不在此处的范围内，引入时需要单独的激活所有权契约。激活 dispose 后，历史会话不消耗运行时内存。
+激活会直接持有已发布的 `AgentHandle` 直至结算，而管理器的私有 activation-owner 作用域则是其 Cordis 结构化所有者。可继续 subagent 路径不创建任何中间的带结果执行包装层，包括 `SubagentRun`；一次性委派保持不变，且不属于该生命周期。远程提供方不在此处的范围内，引入时需要单独的激活所有权约定。激活 dispose 后，历史会话不消耗运行时内存。
 
 ### 激活生命周期
 
@@ -77,7 +77,7 @@ settled
 no Activation
 ```
 
-`running` 表示 Agent 正在执行准入或轮次，或者 inbox 中存在会唤醒 Agent 的工作。`waiting` 表示 Agent 已经完全停稳，但激活仍持有至少一个尚未完成 dispose 的 child 激活。`settled` 表示 Agent 已经完全停稳且所有持有的 child 都已 dispose；随后管理器会 dispose `AgentHandle` 并移除激活。
+`running` 表示 Agent 有正在进行的准入或轮次，或者 inbox 中存在会唤醒 Agent 的工作。`waiting` 表示 Agent 已经完全停稳，但激活仍持有至少一个尚未完成 dispose 的 child 激活。`settled` 表示 Agent 已经完全停稳且所有持有的 child 都已 dispose；随后管理器会 dispose `AgentHandle` 并移除激活。
 
 管理器根据 Agent 是否完全停稳以及所持 child 集合派生这些状态，而不是维护第二套执行状态机。在 `running` 时投递的 `next-turn` 会进入 Agent inbox。在 `waiting` 时投递的 `next-turn` 会唤醒同一个 Agent，并使激活回到 `running`。在 dispose 完成后投递消息则会冷恢复新激活。
 
@@ -99,7 +99,7 @@ Agent inbox 是唯一队列。每条继续执行消息都使用 `Agent.followup(
 
 ### child 所有权
 
-每次激活都持有自身的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`。由于一个会话至多有一次在线激活，child 会话 id 足以标识在线 child，无需另一个运行时 incarnation 引用。`SessionHeader.parentSession` 记录持久化的直接 parent 身份，`ownedChildren` 中的成员关系则记录进程内所有权关系。
+每次激活都持有自身的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`。由于一个会话至多有一个在线激活，child 会话 id 足以标识在线 child，无需另一个运行时 incarnation 引用。`SessionHeader.parentSession` 记录持久化的直接 parent 身份，`ownedChildren` 中的成员关系则记录进程内所有权关系。
 
 当经过身份认证的 parent 自身是由继续执行管理器管理的激活时，启动 child 或提交由 parent 发起的工作，会在 child 可以运行或消息可以进入其 inbox 前，将 child 会话 id 加入该 parent 的 `ownedChildren`。该集合非空时，这个 parent 不能结算或 dispose。顶层 Agent 或其他非继续执行 Agent 没有激活，也不会加入该等待图。
 
@@ -109,11 +109,11 @@ Agent inbox 是唯一队列。每条继续执行消息都使用 `Agent.followup(
 
 顶层拆卸由宿主负责，而不表示为另一次激活。管理器卸载会调用其内部的管理器全局 drain，同步关闭准入，等待每个已获准的物化过程完成发布或回滚，停止稳定的在线森林，并按 child-first 顺序释放。拥有选定顶层 Agent 的宿主使用 `drainContinuableDescendants(parents)`：确切的 Agent 身份只关闭这些根之下的准入，直到每个身份离开注册表，而无关森林和管理器全局准入保持在线；管理器会在第一次 await 之前停止其可见后代，只等待这些根之下已获准的物化过程，并且只释放选定分支。每个已物化的 start 和在线投递都会在与 inbox 提交相同的同步区间内重新检查调用方取消、适用的 draining 作用域、Activation dispose 和确切的 parent 权限，因此只要拆卸或 parent 替换先于接受发生，就会阻止向正在关闭的 handle 投递。只有适用的 drain 结算后，宿主才能 dispose 自己的顶层 Agent；只有管理器全局 drain 会先于管理器作用域 dispose。
 
-activation-owner 作用域之所以存在，是因为普通 Cordis owner effect 按注册逆序撤销，无法表达动态 child 图。管理器初始化时先注册私有作用域的结构化 disposer，再注册自身的 drain disposer，使逆序撤销先执行 drain、再释放该作用域；如果只在与后续 Agent handle 相同的作用域上注册 cleanup effect，结构化 handle dispose 就可能绕过 child-first 顺序。每个物化过程都会在启动内部事务前注册其屏障参与项，并对其确切的在线祖先建立快照，然后保持跟踪，直到安装 Activation 或完全回滚。Activation 会以弱引用方式记录其属于这组祖先，因此中间 Agent 即使离开注册表，也不会让仍在线的后代脱离宿主根节点的可见范围。每个 Activation 都会在取消或递归回调前安装一个记忆化的 dispose promise，使限定作用域的宿主关闭、全局管理器卸载、child 释放和正常结算能够汇合，而不会重复释放。取消会在等待缓慢的后代清理之前自顶向下传播；handle 释放仍是 child-first。同级分支独立 drain；系统会记录单次 dispose 失败，但仍会尝试其余选中 handle，聚合 drain 则在所有选中分支结算后报告失败。这次进程内拆卸不会销毁持久化 child 会话。
+activation-owner 作用域之所以存在，是因为普通 Cordis owner effect 按注册逆序撤销，无法表达动态 child 图。管理器初始化时先注册私有作用域的结构化 disposer，再注册自身的 drain disposer，使逆序撤销先执行 drain、再释放该作用域；如果只在与后续 Agent handle 相同的作用域上注册 cleanup effect，结构化 handle dispose 就可能绕过 child-first 顺序。每个物化过程都会在启动内部事务前注册其屏障参与项，并对其确切的在线祖先建立快照，然后保持跟踪，直到安装 Activation 或完全回滚。Activation 会保留其在这组祖先中的弱成员关系，因此中间 Agent 即使离开注册表，也不会让仍在线的后代脱离宿主根节点的可见范围。每个 Activation 都会在取消或递归回调前安装一个记忆化的 dispose promise，使限定作用域的宿主关闭、全局管理器卸载、child 释放和正常结算能够汇合，而不会重复释放。取消会在等待缓慢的后代清理之前自顶向下传播；handle 释放仍是 child-first。同级分支独立 drain；系统会记录单次 dispose 失败，但仍会尝试其余选中 handle，聚合 drain 则在所有选中分支结算后报告失败。这次进程内拆卸不会销毁持久化 child 会话。
 
 ### 报告投递扩展
 
-可选的 child 作用域 `report(output)` 工具不会改变 Activation 驻留状态，也不会增加另一条队列。它每轮可调用零次或多次，不允许指定接收方，而是推导在线的直接 parent；投递采用静默注入还是唤醒 parent follow-up，由部署配置选择。[report 工具 Agent Note](2026-07-30-continuable-subagent-report-tool.md)规定其权限、确认、设置贡献和投递契约。
+后来添加的可选 child 作用域 `report(output)` 工具不会改变 Activation 驻留状态，也不会增加另一条队列。它每轮可调用零次或多次，不允许指定接收方，而是推导在线的直接 parent；投递采用静默注入还是唤醒 parent follow-up，由部署配置选择。[report 工具 Agent Note](2026-07-30-continuable-subagent-report-tool.md)规定其权限、确认、设置贡献和投递约定。
 
 ### 延后的 steering（中途引导）
 
@@ -143,7 +143,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ### 范围
 
-本版本覆盖可继续的进程内 child，一次性委派保持不变。远程提供方必须具备单独的激活 handle，以及等价的认证控制与 child-first 完全停稳契约，才能支持同样的行为。
+本版本覆盖可继续的进程内 child，一次性委派保持不变。远程提供方必须具备单独的激活 handle，以及等价的认证控制与 child-first 完全停稳约定，才能支持同样的行为。
 
 它不新增 host-user 继续执行、subagent steering 操作、持久化邮箱、跨进程 lease、中断 inbox 工作的自动回放、团队权限、工作流权限、公开驻留查询、新的在线激活数量或后代总数限制，以及运行时缓存；后来的[当前轮次中断](2026-08-06-continuable-subagent-interrupt.md)在此生命周期之上补充了唯一的公开停止操作。现有委派深度策略保持不变。可选的 child 到 parent 报告是后续消费该生命周期的功能，不属于基础可继续能力。
 
@@ -169,7 +169,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 **在没有 host 消费方的情况下暴露 host-user follow-up。** 公开的权限铸造方法和用户分支可以在没有历史 parent 的情况下实现冷恢复，但没有生产 host 适配器调用该操作。在具体的经认证宿主交互能够收到私有能力之前，该 seam 只接受确切的在线 parent。
 
-**返回 subagent 专属的投递路由。** `started`、`queued` 和 `resumed` 等标签重复了激活与 inbox 状态，却没有给调用方提供独立结果。复用 `MessageId` 和现有 inbox 事件，可以让投递关联继续由其所属的 Agent 契约承载。
+**返回 subagent 专属的投递路由。** `started`、`queued` 和 `resumed` 等标签重复了激活与 inbox 状态，却没有给调用方提供独立结果。复用 `MessageId` 和现有 inbox 事件，可以让投递关联继续由其所属的 Agent 约定承载。
 
 **使用 child 引用计数。** 计数无法识别哪个 child 仍持有拆卸工作，也允许重复递减错误。身份集合会显式保留取消和 dispose 义务。
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.i18n.yaml
index df8239ba4b..62a22d215c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.md
 2026-07-28-cross-workspace-resume.md: e8a8636911015a5b300b45a30e268ee1be5d47d1
-2026-07-28-cross-workspace-resume.zh.md: 9e5e126f4b204927d7fb134a196dd0d0a98468d4
+2026-07-28-cross-workspace-resume.zh.md: c56641be35bb37fb8aafb7613bdf8b8158e198d9
diff --git a/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.zh.md b/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.zh.md
index 9e5e126f4b..c56641be35 100644
--- a/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.zh.md
@@ -16,15 +16,15 @@ Status: implemented
 
 ## Decision
 
-共享 CLI 配置提供 Harness home 下的同一个会话根目录，选择器获得 workspace 范围，交接过程携带目标目录。
+共享 CLI（命令行界面）配置提供 Harness home 下的同一个会话根目录，选择器获得 workspace 范围，交接过程携带目标目录。
 
-**存储。** 共享 base 在 `apps/cli/config/base.cordis.yml` 中拥有默认值：其 `session-persistence-jsonl` 配置项调用由 app-boot 提供的 `dshHomePath('sessions')`，该函数使用规范的 `DSH_HOME` 解析器及其标准的 `~/.dsh` 回退值。因此 TUI、Web 与 headless 使用同一个默认值，无需针对会话的启动器补丁或槽位。若 overlay 或个人 patch 显式声明根目录，它会整体替换该配置项的 `config`，并继续作为部署的权威选择。
+**存储。** 共享 base 在 `apps/cli/config/base.cordis.yml` 中拥有默认值：其 `session-persistence-jsonl` 配置项调用由 app-boot 提供的 `dshHomePath('sessions')`，该函数使用规范的 `DSH_HOME` 解析器及其标准的 `~/.dsh` 回退值。因此 TUI、Web 与 headless 使用同一个默认值，无需针对会话的启动器补丁或 slot。若 overlay 或个人 patch 显式声明根目录，它会整体替换该配置项的 `config`，并继续作为部署的权威选择。
 
 **是范围，不是排除。** 当前 workspace 之外的 workspace 是一种展示范围，而不是禁用理由。`showResume()` 汇总每一条记录，`ResumePicker` 持有一个 `'workspace' | 'all'` 的 `scope`，默认为当前 workspace，因此常见场景毫无变化。Tab 切换范围；范围行会说明当前生效的范围，以及另一个范围下的数量；在全 workspace 范围中每一行都报告自己的 workspace，而该标签只在展示它的范围里才加入可搜索文本。切换范围会清空查询和选中项，使高亮行始终属于可见列表；而逐行的 workspace 行会让该范围下的每一行在终端里多占一行，可见条数预算已经把这一点计入。
 
 因此 `summarizeResumeCandidate` 去掉了 `'different workspace'`，并新增 `'session has no recorded workspace'`。这是一条真正新增的拒绝理由，而不是改名：没有 `cwd` 的头部没有指明任何目录供宿主进入，所以即便它的日志完好也无法完成交接。
 
-**交接。** `TuiResumeHost.handoff` 在 `SessionId` 之外还接收目标 `cwd`。`preflightResume` 把两者一起解析并一起返回，因此调用方无法从它展示过的那一行里重新推导出一个陈旧目录——在列表展示与预检之间 `cwd` 发生了移动的记录，会在*重新读取到的*目录中恢复，这也是原先「拒绝已移动的 cwd」的行为如今变成携带新路径完成交接的原因。已交付的宿主在释放应用之前切换目录：不可达的目录必须在调用方还能恢复终端时就拒绝，因为拆卸之后已经没有任何所有者可供汇报。恢复始终使用默认的 `dsh --resume` 界面，因为 `meta` 会拒绝父级选项；交接过程已经进入持久化保存的目标目录。
+**交接。** `TuiResumeHost.handoff` 在 `SessionId` 之外还接收目标 `cwd`。`preflightResume` 把两者一起解析并一起返回，因此调用方无法从它展示过的那一行里重新推导出一个陈旧目录——在列表展示与预检之间 `cwd` 发生了变化的记录，会在*重新读取到的*目录中恢复，这也是原先「拒绝发生变化的 cwd」的行为如今变成携带新路径完成交接的原因。已交付的宿主在 dispose（资源释放）应用之前切换目录：不可达的目录必须在调用方还能恢复终端时就拒绝，因为拆卸之后已经没有任何所有者可供汇报。恢复始终使用默认的 `dsh --resume` 接口，因为 `meta` 会拒绝父级选项；交接过程已经进入持久化保存的目标目录。
 
 ## Alternatives considered
 
@@ -36,7 +36,7 @@ Status: implemented
 
 **把所有 workspace 铺成一个扁平列表。** 否决：这会丢掉绝大多数场景想要的「本项目」默认值，而在一个繁忙的 home 目录里，当前项目的会话会和无关会话争夺注意力。
 
-**让宿主从还原后的会话头部推断目录。** 否决：会话头部是面向模型与提示词的状态，在启动*之后*才还原，而目录必须在 `execve` *之前*进入。显式传递它能让这个顺序在边界处保持可见。
+**让宿主从还原后的会话头部推断目录。** 否决：会话头部是面向模型与提示词的状态，在启动*之后*才还原，而目录必须在 `execve` *之前*进入。显式传递它能让这个顺序在 seam 处保持可见。
 
 ## Consequences
 
@@ -46,4 +46,4 @@ Status: implemented
 
 ## Testing
 
-TUI 测试覆盖默认范围隐藏其他 workspace 但报告其数量、Tab 显示它们并带上逐行 workspace 标签、再按 Tab 返回时清空查询与选中项、按 workspace 标签搜索、无 cwd 的记录仍可见但不可选，以及交接同时收到 id 和在预检时重新读取到的 workspace。原先「拒绝已移动的 cwd」的用例现在断言交接携带新目录。构建后的 CLI PTY 测试会运行共享配置默认值与每进程派生的查询索引。无密钥 TUI 快照固定选择器的两个范围，包括范围行、逐行 workspace 行，以及页脚中的 Tab 提示。手动执行的一次跨 workspace 恢复在进程层面验证了替换后进程的工作目录变为目标 workspace。
+TUI 测试覆盖默认范围隐藏其他 workspace 但报告其数量、Tab 显示它们并带上逐行 workspace 标签、再按 Tab 返回时清空查询与选中项、按 workspace 标签搜索、无 cwd 的记录仍可见但不可选，以及交接同时收到 id 和在预检时重新读取到的 workspace。原先「拒绝发生变化的 cwd」的用例现在断言交接携带新目录。构建后的 CLI PTY 测试会检验共享配置默认值与每进程派生的查询索引。无密钥 TUI 快照固定选择器的两个范围，包括范围行、逐行 workspace 行，以及页脚中的 Tab 提示。手动执行的一次跨 workspace 恢复在进程层面验证了替换后进程的工作目录变为目标 workspace。
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
index 9f60321cc8..e0133df46f 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-feedback-command.md
 2026-07-28-feedback-command.md: 78cc9e89a5811b3f1520bae2bd971cbcf2522ede
-2026-07-28-feedback-command.zh.md: c8870ca2988501d7899ae826e1bbcbad0bef5678
+2026-07-28-feedback-command.zh.md: b0bba25ec3331123cb86066fc6c89186f2297cc9
diff --git a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
index c8870ca298..b0bba25ec3 100644
--- a/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-feedback-command.zh.md
@@ -14,11 +14,11 @@ Status: implemented
 
 位于 `packages/feedback/command-feedback/` 的 `@deepseek-ai/dsh-command-feedback` 通过 `ctx.commands` 注册一个全局 `feedback` 命令。`/feedback <text>` 给出确认；空输入或仅含空白的输入返回直接用法错误。处理器是同步的，只注入 `commands`，且没有任何配置。
 
-本包（package）声明仅写入日志的 `feedback/record { text }` 会话事件，并导出 `recordFeedback(session, text)`，作为不依赖命令的生产方。该生产方丢弃前后空白，拒绝空结果，并且恰好追加一个事件。`/feedback` 委托给它，因此其他 UI、钩子或 host 集成无需构造斜杠命令也能记录同一个领域事实。
+本包声明仅写入日志的 `feedback/record { text }` 会话事件，并导出 `recordFeedback(session, text)`，作为不依赖命令的生产方。该生产方丢弃前后空白，拒绝空结果，并且恰好追加一个事件。`/feedback` 委托给它，因此其他 UI、钩子或 host 集成无需构造斜杠命令也能记录同一个领域事实。
 
 `dsh-commands` 仍会围绕 `/feedback` 写入 `command/run` / `command/done` 生命周期配对，但该命令设置了 `recordInput: false`。因此，它的 `command/run` 携带命令标识与来源，但不携带 `args`；反馈文本只存在于 `feedback/record` 中，而 `command/done` 携带确认结果。三个记录都仅写入日志且非 surface。它们的追加会进入持久化的常规有界写入路径；没有任何环节强制 flush，因此确认文本报告的是反馈已进入日志，而非已经落盘。
 
-采集对正在运行的 agent 与模型仍不产生后续动作。可选的 OTel 遥测包后续增加了一个基础设施消费方：它在 `FEEDBACK_ONLY` 模式下将 `feedback/record` 作为释放触发器，在 `DISABLED` 模式下将其作为本地警告触发器，且不改变反馈事件或命令路径。见[反馈门控的会话遥测](2026-08-05-feedback-gated-session-telemetry.md)。
+采集对正在运行的 agent（智能体）与模型仍不产生后续动作。可选的 OTel 遥测包后续增加了一个基础设施消费方：它在 `FEEDBACK_ONLY` 模式下将 `feedback/record` 作为释放触发器，在 `DISABLED` 模式下将其作为仅限本地的警告触发器，且不改变反馈事件或命令路径。见[反馈门控的会话遥测](2026-08-05-feedback-gated-session-telemetry.md)。
 
 ### 为何反馈拥有自己的事件
 
@@ -34,7 +34,7 @@ Status: implemented
 
 ### 一个新的分组
 
-`packages/feedback/` 是新分组，因为现有分组都不拥有此职责：`goal/` 负责目标状态，`session-title/` 负责标题，`core/` 是产品主干。该分组只包含一个生产方包；跨领域的消费方留在各自所属的分组，而不是迫使这个包不断膨胀。
+`packages/feedback/` 是新分组，因为现有分组都不拥有此职责：`goal/` 负责目标状态，`session-title/` 负责标题，`core/` 是产品主干。该分组只包含一个生产方包；跨领域的消费方留在各自所属的分组，而不是迫使这个分组不断膨胀。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
index ea1b12edeb..1f652e9eee 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
 2026-07-28-skill-invocation-policy.md: 9d34bcb77ab7933ef9bf4e9b5227dade39903667
-2026-07-28-skill-invocation-policy.zh.md: 4b190dbd095306d41837bd9734049f5e3d85da72
+2026-07-28-skill-invocation-policy.zh.md: f196bcb66b05d2c7ba4b82a4e1124e335ef8aeb1
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
index 4b190dbd09..f196bcb66b 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
@@ -8,17 +8,17 @@ Status: implemented
 
 skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会移除禁止模型调用的 skill，而 `ctx.skills.get()` 仍是不过滤内容的可信 loader。该设计足以支持由模型发起的加载，却无法表示与 Claude 兼容的四类 skill：仅向用户公开、仅向模型公开、同时向两者公开，或者两者均不公开。TUI 从面向模型过滤后的列表中生成用户自动补全，并允许通过 `get()` 加载任意精确名称，这进一步放大了两类调用策略不匹配的问题。
 
-本地解析器还将一种内部驼峰式拼写暴露为 frontmatter。若要支持既有的负向字段 `disable-model-invocation` 和正向字段 `user-invocable`，需要建立持久且对称的领域表示，同时避免把所有可能出现的 YAML 键都变成跨包的无类型契约。
+本地解析器还将一种内部驼峰式拼写暴露为 frontmatter。若要支持既有的负向字段 `disable-model-invocation` 和正向字段 `user-invocable`，需要建立持久且对称的领域表示，同时避免把所有可能出现的 YAML 键都变成跨包的无类型约定。
 
 ## 决策
 
-`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入 seam 可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行契约后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
+`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入 seam 可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行约定后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
 
 `ctx.skills.list()` 返回所有胜出的摘要，不再替任何调用接口选择策略。`isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 保持策略无关，因为可信内部调用方可能需要任意定义；对外消费方则必须在展示或加载 skill 之前执行自身对应的判定函数。模型工具和 TUI 会在调用 `get()` 前检查与调用策略无关的摘要，随后再次检查已加载的定义：被拒绝的名称绝不会进入定义加载流程，发现与加载之间发生策略变更也无法暴露该 skill 的正文。
 
 本地提供方只接受拼写完全一致的 kebab-case frontmatter 键 `disable-model-invocation` 和 `user-invocable`。它接受 YAML 布尔值，以及不区分大小写的 `true`/`false`、`yes`/`no`、`on`/`off` 和 `1`/`0`，与 Claude skills 实际支持的布尔写法一致。它将 `disable-model-invocation` 映射为相反的正向字段，即使两个键都不存在，也会根据默认值填充两个正向字段。若使用外部驼峰式拼写或提供非布尔调用值，发现流程会丢弃整个 skill，并给出有针对性的警告；本仓库尚处于发布前阶段，因此不为磁盘格式保留兼容别名。调用数据校验遵循失败时默认拒绝原则，因为忽略这类数据会默认授予权限，可能使 skill 暴露在已禁用的接口上；与之不同，类型错误的可选 `whenToUse` 和 `metadata` 值会被省略，因为它们不参与调用判定。
 
-面向模型的 `dsh-tool-skill` 目录和 loader 执行 `isModelInvocable`。TUI 的 `/skill:` 自动补全与精确名称 loader 在本地执行用户字段，因此仅允许用户调用的 skill 即使不出现在模型发现结果中，仍会在此处显示并可加载，同时不会将可选的 skill peer 变成运行时导入。由 launcher 预置、供引导式 `dsh migrate` 和 `dsh upgrade` 会话使用的初始 skill 沿用同一条 TUI 路径，因此必须保持允许用户调用。浏览器的 `skill.list` RPC 提供的是由用户选择、但仍要求模型加载的引用，因此只公开同时允许模型和用户调用的 skill；本次改动不新增让浏览器直接加载 skill 的 RPC。
+面向模型的 `dsh-tool-skill` 目录和 loader 执行 `isModelInvocable`。TUI 的 `/skill:` 自动补全与精确名称 loader 在本地根据用户字段执行策略，因此仅允许用户调用的 skill 即使不出现在模型发现结果中，仍会在此处显示并可加载，同时不会将可选的 skill 对等依赖（peer dependency）变成运行时导入。由 launcher 预置、供引导式 `dsh migrate` 和 `dsh upgrade` 会话使用的初始 skill 沿用同一条 TUI 路径，因此必须保持允许用户调用。浏览器的 `skill.list` RPC 提供的是由用户选择、但仍要求模型加载的引用，因此只公开同时允许模型和用户调用的 skill；本次改动不新增让浏览器直接加载 skill 的 RPC。
 
 这些规则允许以下四种组合：
 
@@ -39,12 +39,12 @@ skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会
 
 **在 `ctx.skills.get()` 内执行调用策略。** 不予采纳，因为 `get()` 无法判断调用方是模型工具、人类命令还是可信编排逻辑。在此处过滤还会使两个接口均禁止调用的组合无法被检查或管理。
 
-**将驼峰式 frontmatter 作为别名处理。** 不予采纳，因为外部格式遵循采用 kebab-case 的 Claude skills 契约，而本仓库尚未发布，无需承担兼容义务。快速失败可以避免暗中保留不符合标准的拼写。
+**将驼峰式 frontmatter 作为别名处理。** 不予采纳，因为外部格式遵循采用 kebab-case 的 Claude skills 约定，而本仓库尚未发布，无需承担兼容义务。显式失败可以避免暗中保留不符合标准的拼写。
 
 **增加由浏览器端直接调用 skill 的 RPC。** 本次改动不予采纳，因为现有浏览器流程插入的是模型引用，而非已经加载的指令正文。因此，该流程应当取模型与用户调用策略的交集；直接由用户加载的接口需要单独设计协议与日志记录方式。
 
 ## 后果
 
-提供方与运行时注册对外提供小而类型明确的调用契约，同时本地 YAML 仍可扩展。每个新的发现消费方都必须明确选择模型判定函数、用户判定函数、两者的交集，或可信且不过滤的访问方式；如果遗漏这项选择，评审时可以直接看出问题，而不会再被注册表行为掩盖。
+提供方与运行时注册对外提供小而类型明确的调用约定，同时本地 YAML 仍可扩展。每个新的发现消费方都必须明确选择模型判定函数、用户判定函数、两者的交集，或可信且不过滤的访问方式；如果遗漏这项选择，评审时可以直接看出问题，而不会再被注册表行为掩盖。
 
 无密钥 ACP（Agent Client Protocol）快照固定了模型目录的变更：其中包含仅允许模型调用的 skill，并排除仅允许用户调用的 skill。组装后的无密钥 TUI 快照按精确名称发现并加载一个仅允许用户调用的 skill，随后在加载正文前拒绝一个仅允许模型调用的 skill；真实 Loader/PTY 冒烟测试通过随产品交付的终端进程证明了同一条仅允许用户调用的路径。真实宿主上的 Chromium 快照固定了浏览器在全部四种策略组合下的交集行为。TUI 单元测试覆盖这些组合以及资源释放竞态；注册表、本地解析器、模型工具和 API 代理测试则覆盖默认值、支持的布尔写法、格式错误的值、旧键拒绝、精确名称加载时的策略执行，以及浏览器侧的策略交集。
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
index 53dba67c61..45bb845cd6 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
 2026-07-28-web-terminal-card.md: 026b32fed2c79533abfadc58314e2844ff556414
-2026-07-28-web-terminal-card.zh.md: 4c74d880c5795cf85f32391b27e6ffd2c5074870
+2026-07-28-web-terminal-card.zh.md: ff0b7f327560e9dba379a0d36596b267b739aaa7
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index 4c74d880c5..ff0b7f3275 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -12,15 +12,15 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 ## Decision
 
-`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
+`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图约定交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道 seam；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为约定把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
 
-该组件的契约：
+该组件的约定：
 
 - **提示符行，每条命令行一行。** 命令的每一行各占一行：标签，其后原样跟随该行。因此一个在两行上承载两条 shell 命令的 `command` 就读作它本身的两条命令，而不是被压成一行并省略号截断。标签取 cwd 的最后一段路径，当 cwd 等于 `home` prop 时取 `~`——浏览器没有 `$HOME`，因此由调用方提供绝对家目录，不提供时该折叠不生效。视图不带 cwd 时渲染一个纯 `$`。末尾换行是终止符，不是一条空的末命令。只有**第一行**携带该标签：视图只知道一个工作目录——调用开始处的那个——而后面的行完全可能在别处运行，命令里一个 `cd` 就足以改变它。把标签在各行重复，等于陈述一个此处无人知晓的逐行目录，这与运行状态点只出现一次是同一个理由。其余行保留一个裸 `$`，因此它们仍读作提示符。
 - **整次调用一枚运行状态点，位于第一行。** 它是 `StateDot` 四种状态中的三种：运行期间为追逐动画，与渲染状态徽章相同的退出状态为红色，干净落定为绿色——与工具行行首图标使用同一个指示器，因此一行与其自身的卡片不可能对同一条命令产生分歧。该状态点存在的理由是：读者对一条 shell 命令的第一个问题就是它是否仍在运行；没有它时，这一点只能从「没有输出」推断，而一条落定后无输出的命令看起来也一样。它以脱离文档流的方式落在卡片以**自身左内边距**预留的落区里，因此既不会缩进其命令，也不依赖命令自身的文本度量来与之对齐。该预留用 padding 而非 margin，是因为每个渲染点都会整条重写 `margin` 来设定自己的缩进——那会静默取消基于 margin 的落区，并让容器把状态点裁掉。无论有多少行，都只有一枚：视图携带的退出状态属于整次调用，而 bash 不报告逐条命令的状态，因此每行一枚状态点就等于在断言——一条在失败调用中其实成功了的命令行自身失败了。那一处视觉隐藏的文本标签具有相同的作用域，因为 `StateDot` 是 `aria-hidden`，而每行一个标签会被辅助技术读成好几个各自独立的结果。
 - **不软换行。** 输出行使用 `white-space: pre`，置于横向滚动的容器内。列对齐得以保留；长行滚动，而非折行。
-- **高度上限与展开控件。** 输出超过 `DEFAULT_TERMINAL_MAX_LINES`（16）行时，显示 `ceil(max/2)` 行首部加余下的尾部行数，中间是一个按钮，报告被隐藏的行数并可展开。计数针对的是剥除输出末尾终止符之后解析出的行，因此以换行结尾的 N 行输出就是 N 行。切分算法保留原 TUI transcript 折叠卡片的行为，因此既有的首尾选择保持稳定。
-- **ANSI 颜色。** `anser` 切分 SGR 分段；`ui-primitives/src/ansi.ts` 把每段解析为内联样式，渲染成 React span。只设前景色的分段把基本 16 色映射到 `--dsw-*` 主题 token，使作者指定的颜色在两种主题下都可读；自行绘制背景的分段则前后景都保留 anser 给出的字面 rgb，以保住它意图中的对比度，256 色板、truecolor 以及本设计系统没有对应 token 的两种基本色同样如此。不承载颜色的转义序列（OSC 串、非 CSI 转义、无显示意义的 C0 控制符）在解析前被剥除，因此绝不会以字面字符抵达 DOM。光标移动在该剥除之前先行结算，且落在逐行的列缓冲里而不是靠字符串手术，因为回车与退格**只移动**光标——两者都不擦除任何东西，所以读者看到的就是每一列最后被写入的内容。`100%` 后接回车再接 `OK` 显示为 `OK0%`，因为这次重绘比它下面的帧更短；末尾 `abc` 加一个退格仍显示 `abc`，因为没有任何东西覆盖过那个 `c`；`abc` 加两个退格再接 `XY` 显示 `aXY`。这些用例都对照真实终端核实过，因为先前「截断加删除」的近似看起来是对的，实际并不对。SGR 状态按列打戳，与终端按单元格存储颜色的方式一致，因此部分覆盖会保留每个存活字符自身的颜色：红色 `bad`、三个退格、再写 `ok`，显示为 `okd` 且那个 `d` 仍是红的。CSI 序列不占列，只改变后续写入被打上的状态——这也正是回车不会重置颜色的原因，以及 SGR 状态会从一行延续到下一行、而不是在每个换行处关闭的原因。行内擦除属于同一次重放，因为 `\r\x1b[K` 是每个 spinner 与进度条都会写的同一个惯用法——只建模 `\r` 会让上一帧的尾巴留在原处，那是终端从未显示过的文本。只有 `m` 会累加进单元格样式；光标或擦除序列不能累加，否则状态串会随每次重绘线性增长，并发出 anser 只能丢弃的边界。SGR 按单元格以**归一化记录**保存（前景、背景、属性集合），而不是序列历史：累积原始序列会让每个状态边界重新发射整条链，因此不做完整 reset 的换色输出会发射 O(n^2) 个字符——3200 个这样的单元格产生 25 MB 并最终 `RangeError`，远低于 bash 自身的输出上限。该记录也让所有 chalk 系工具写出的属性闭合码（`39`、`49`、`22`、`24` 等）真正闭合其属性，且每个边界只为它开启的状态发射一条规范序列。一个分段也必须**收束**：重放收敛到扫描结束时的状态，而不是最后一个被写入单元格的状态——因为最后一次写入之后的 reset 不改变任何单元格，却结束了该分段；没有这一步，以 `\x1b[0m` 结尾的行会把颜色泄漏到其后所有行。光标按终端列推进，因此制表符前进到下一个 8 列制表位、宽字符占两列（其续列在首列被覆盖后变为空白而非合拢），组合标记不占列。宽度依据 emoji **presentation** 而非 U+2600–U+27BF 整个区块：`\u2713`——每条进度行都会写的对勾——只占一列，把该区块整体当作双宽恰好会错位这张卡片赖以存在的那类输出。写入宽字符对的任一半都会把另一半清成空白，因为终端无法让一个双格字形只留下一格：`a\tb` 之后用 `XY` 重绘显示为 `XY      b`，因为两个字符的重绘到不了第 8 列。
+- **高度上限与展开控件。** 输出超过 `DEFAULT_TERMINAL_MAX_LINES`（16）行时，显示 `ceil(max/2)` 行首部加余下的尾部行数，中间是一个按钮，报告被隐藏的行数并可展开。计数针对的是剥除输出末尾终止符之后解析出的行，因此以换行结尾的 N 行输出就是 N 行。切分算法保留原 TUI transcript（文本记录）折叠卡片的行为，因此既有的首尾选择保持稳定。
+- **ANSI 颜色。** `anser` 切分 SGR 分段；`ui-primitives/src/ansi.ts` 把每段解析为内联样式，渲染成 React span。只设前景色的分段把基本 16 色映射到 `--dsw-*` 主题 token，使作者指定的颜色在两种主题下都可读；自行绘制背景的分段则前后景都保留 anser 给出的字面 rgb，以保住它意图中的对比度，256 色板、truecolor 以及本设计系统没有对应 token 的两种基本色同样如此。不承载颜色的转义序列（OSC 串、非 CSI 转义、无显示意义的 C0 控制符）在解析前被剥除，因此绝不会以字面字符抵达 DOM。光标移动在该剥除之前先行结算，且落在逐行的列缓冲里而不是靠字符串手术，因为回车与退格**只移动**光标——两者都不擦除任何东西，所以读者看到的就是每一列最后被写入的内容。`100%` 后接回车再接 `OK` 显示为 `OK0%`，因为这次重绘比它下面的帧更短；末尾 `abc` 加一个退格仍显示 `abc`，因为没有任何东西覆盖过那个 `c`；`abc` 加两个退格再接 `XY` 显示 `aXY`。这些用例都对照真实终端核实过，因为先前「截断加删除」的近似看起来是对的，实际并不对。SGR 状态按列打戳，与终端按单元格存储颜色的方式一致，因此部分覆盖会保留每个存活字符自身的颜色：红色 `bad`、三个退格、再写 `ok`，显示为 `okd` 且那个 `d` 仍是红的。CSI 序列不占列，只改变后续写入被打上的状态——这也正是回车不会重置颜色的原因，以及 SGR 状态会从一行延续到下一行、而不是在每个换行处关闭的原因。行内擦除属于同一次重放，因为 `\r\x1b[K` 是每个 spinner 与进度条都会写的同一个惯用法——只建模 `\r` 会让上一帧的尾巴留在原处，那是终端从未显示过的文本。只有 `m` 会累加进单元格样式；光标或擦除序列不能累加，否则状态串会随每次重绘线性增长，并发出 anser 只能丢弃的边界。SGR 按单元格以**归一化记录**保存（前景、背景、属性集合），而不是序列历史：累积原始序列会让每个状态边界重新发射整条链，因此不做完整 reset 的换色输出会发射 O(n^2) 个字符——3200 个这样的单元格产生 25 MB 并最终触发 `RangeError`，远低于 bash 自身的输出上限。该记录也让所有 chalk 系工具写出的属性闭合码（`39`、`49`、`22`、`24` 等）真正闭合其属性，且每个边界只为它开启的状态发射一条规范序列。一个分段也必须**收束**：重放收敛到扫描结束时的状态，而不是最后一个被写入单元格的状态——因为最后一次写入之后的 reset 不改变任何单元格，却结束了该分段；没有这一步，以 `\x1b[0m` 结尾的行会把颜色泄漏到其后所有行。光标按终端列推进，因此制表符前进到下一个 8 列制表位、宽字符占两列（其续列在首列被覆盖后变为空白而非合拢），组合标记不占列。宽度依据 emoji **presentation** 而非 U+2600–U+27BF 整个区块：`\u2713`——每条进度行都会写的对勾——只占一列，把该区块整体当作双宽恰好会错位这张卡片赖以存在的那类输出。写入宽字符对的任一半都会把另一半清成空白，因为终端无法让一个双格字形只留下一格：`a\tb` 之后用 `XY` 重绘显示为 `XY      b`，因为两个字符的重绘到不了第 8 列。
 - **退出状态与复制。** 非零退出码或信号渲染一枚状态徽章，与 bash 工具自身渲染器所作的退出状态区分一致；干净退出不渲染徽章，落定后的空输出渲染一处变暗的占位文字——该判定读的是卡片实际渲染的解析行，而非原始文本，因为只含转义或控制字节的输出能通过 `trim()` 却解析不出任何可见内容，否则就会画出一片空行外加一个把不可见字节写进剪贴板的复制控件。复制控件复制的是原始输出文本而非渲染后的树，因此提示符行与徽章不会进入剪贴板。
 
 几何尺寸、圆角与字体沿用 `CodeBlock`，因此终端卡片与围栏代码块在视觉上一致；`white-space: pre` 加横向滚动是有意的分歧。两个组件都需要的剪贴板写入从 `CodeBlock` 中提取到包内部的 `src/clipboard.ts`，不对外导出，因此它仍是这两个块的实现细节。
@@ -41,7 +41,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 **复用 `CodeBlock` 并传入 `console` 语言，而不新建组件。** 已否决：`CodeBlock` 会软换行，而软换行正是本次要修的缺陷，且它没有退出状态、没有 cwd 提示符行、没有高度上限、也不处理 ANSI。把四项终端专属关注点加进共享的代码围栏组件，等于把它们强加给每一个 markdown 围栏。两个组件改为共享几何与字体 token，那是唯一一处「一套实现对两者都正确」的部分。
 
-**手写 SGR 解析器。** 已否决：SGR 解析器恰是[优先采用维护良好的依赖而非手写](../process/2026-07-26-dependencies-over-hand-rolling.md)所指明不该自持的那类实现——它的边界情形（256 色板与 truecolor 形式、`reverse`、多参数分段、未终止的序列）各自只在没人会写进测试的输出上失效，因此手写版本会在很长时间内一直微妙地出错。对照那条策略的门槛如实陈述：`anser` **并未**删除任何既有自持代码。它是一次能力增补，而那条 Agent Note 把这与净删除式的简化区分开来；它清过的是健康度与边界契合这两半门槛。`anser` 未覆盖而仍由我们手写的部分是：主题 token 的颜色映射、非 CSI 序列的剥除、回车重绘，以及供高度上限切片的逐行 span 折叠。
+**手写 SGR 解析器。** 已否决：SGR 解析器恰是[优先采用维护良好的依赖而非手写](../process/2026-07-26-dependencies-over-hand-rolling.md)所指明不该自持的那类实现——它的边界情形（256 色板与 truecolor 形式、`reverse`、多参数分段、未终止的序列）各自只在没人会写进测试的输出上失效，因此手写版本会在很长时间内一直微妙地出错。对照那条策略的门槛如实陈述：`anser` **并未**删除任何既有自持代码。它是一次能力增补，而那条 Agent Note 把这与净删除式的简化区分开来；它通过的是健康度与边界契合这两半门槛。`anser` 未覆盖而仍由我们手写的部分是：主题 token 的颜色映射、非 CSI 序列的剥除、回车重绘，以及供高度上限切片的逐行 span 折叠。
 
 ## Consequences
 
@@ -49,7 +49,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 `TerminalBlock` 只读取 terminal 视图携带的字段，因此它始终是渲染意图内容的纯函数——不查会话状态，与产出该视图的 presenter 一样可安全回放。不具备终端能力的 UI 仍从桥接层拿到围栏式回退；工具的结果形态未作任何改动。
 
-在当前已交付的 wire 上，`run_code` 子派发不会得到终端卡片：`session.ts` 把 `tool/code-dispatch(-start)` 折叠为 `callView: null`／`resultView: null`，而 host 的 `viewFor` 只呈现顶层的 `tool/call`／`tool/result`，因此嵌套的 bash 调用保持通用的压平形式。两条分支都已钉住——注入视图后的解析路径，以及 wire 实际投递的无视图形态——因此这个缺口是被记录下来的，而非暗含的。把 presenter 视图贯穿 code-dispatch wire 属于那道接缝自身的改动。
+在当前已交付的 wire 上，`run_code` 子派发不会得到终端卡片：`session.ts` 把 `tool/code-dispatch(-start)` 折叠为 `callView: null`／`resultView: null`，而 host 的 `viewFor` 只呈现顶层的 `tool/call`／`tool/result`，因此嵌套的 bash 调用保持通用的压平形式。两条分支都已钉住——注入视图后的解析路径，以及 wire 实际投递的无视图形态——因此这个缺口是被记录下来的，而非暗含的。把 presenter 视图贯穿 code-dispatch wire 属于那道 seam 自身的改动。
 
 内嵌渲染的许可仅授予 terminal 意图。将来想要内嵌的意图需要有自己的边界与自己的决定，且需针对此处记录的理由来论证，而不是仅针对「只在面板」这条约定本身。
 
@@ -59,7 +59,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 `packages/client/ui-tool/tests/terminal-card.spec.tsx` 固定每个渲染点上的接线：`terminalCardModel` 的推导及其每一处 null 分支、结果标题替换待定标题、cwd 针对会话 workspace 解析的全部四种情形、切换选中调用时面板重置卡片展开态、对话行受展开控制的输出体与面板的全高输出体的对比、`BashRow` 的常驻卡片及其与自身摘要行状态点的一致性，以及面板 Output 区段（含 run_code 子派发与超出窗口的调用头）。该文件在没有门禁压力的情况下写成——`packages/client/ui-tool/src/*` 位于 `vitest.config.ts` 的覆盖率 `exclude` 列表中，因此覆盖率运行不会统计其中任何文件。
 
-`apps/web/tests/terminal-card.snapshot.ts` 在构建后的客户端产物上固定组装完整的应用：同一渲染意图在两个对话渲染点、以及两种对话行形态下的表现——因为 bash 调用只有经由带键的 `BashRow` 注册才得到常驻卡片，而其他任何声明 terminal 的工具名都落到渲染点兜底行上，其输出体受展开控制。fixture 第 65 轮改名为 `bash`、第 60 轮保留 `fx-bash`，于是一份 fixture 覆盖两种形态，并把第 60 轮的命令改为两行，使构建产物快照钉住逐行提示区及其单枚状态点（`dotsPerPromptRow: [1, 0]`）。该终端轮有意排在 todo 轮**之前**：站立计划会在下一次 `turn/start` 时退役，若追加在其后就会让 dock 的计划条变空，并连带毁掉 todo 表面自身的覆盖；该轮还承载第 60 轮两个提示行无法覆盖的部分——解析到 `--dsw-*` token 的 SGR 分段、超出对话上限的输出、嵌套 cwd，以及在样本旁另行标注的非零退出码。样本正文有意**不含** `[exit code: N]` 行：真实的 bash presenter 正是因为卡片以徽章单独呈现退出状态，才把该标记从正文中消费掉；若保留它，钉住的将是一帧把退出状态显示两次的画面——而产品路径产不出这一帧。
+`apps/web/tests/terminal-card.snapshot.ts` 在构建后的客户端产物上固定组装完整的应用：同一渲染意图在两个对话渲染点、以及两种对话行形态下的表现——因为 bash 调用只有经由带键的 `BashRow` 注册才得到常驻卡片，而其他任何声明 terminal 的工具名都落到渲染点兜底行上，其输出体受展开控制。fixture 第 65 轮次改名为 `bash`、第 60 轮次保留 `fx-bash`，于是一份 fixture 覆盖两种形态，并把第 60 轮次的命令改为两行，使构建产物快照钉住逐行提示区及其单枚状态点（`dotsPerPromptRow: [1, 0]`）。该终端轮次有意排在 todo 轮次**之前**：当前计划会在下一次 `turn/start` 时退役，若追加在其后就会让 dock 的计划条变空，并连带毁掉 todo 表面自身的覆盖；该轮次还承载第 60 轮次两个提示行无法覆盖的部分——解析到 `--dsw-*` token 的 SGR 分段、超出对话上限的输出、嵌套 cwd，以及在样本旁另行标注的非零退出码。样本正文有意**不含** `[exit code: N]` 行：真实的 bash presenter 正是因为卡片以徽章单独呈现退出状态，才把该标记从正文中消费掉；若保留它，钉住的将是一帧把退出状态显示两次的画面——而产品路径产不出这一帧。
 
 `apps/web/tests/navigation-panes.e2e.ts` 在其既有的 `echo NAVIGATION_OK` bash 调用上新增真实浏览器场景，断言 jsdom 无法计算的部分：把输出面板挤压到窄于内容宽度后，行仍保持单行且面板产生横向溢出；运行状态点解析为绿色的 success token，而不是字面颜色（没有真实主题样式表时，`--dsw-*` 变量根本不产生计算值），且它位于卡片盒之内、提示标签之左——这正是那道 gutter 内边距所拥有的不变量；复制控件走的是页面自身的异步 Clipboard API，而非 `execCommand` 兜底路径。其 `terminal-card.expected.md` 基准记录了提示行中已解析的 workspace——这正是不带 `workdir` 的 bash 调用应当显示的内容，而非一个裸 `$`。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
index 1491968f15..ee10e63c02 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
 2026-07-30-config-only-repository-plugins.md: 2057125fc78596dd4e5eb153f77b828f83d9ceff
-2026-07-30-config-only-repository-plugins.zh.md: 6e741b46be716e21a11c2f508fb5e6d0505c76d0
+2026-07-30-config-only-repository-plugins.zh.md: afda636c6592e26e80cd2f8f665f92d3010f28f7
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
index 6e741b46be..afda636c65 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
@@ -12,19 +12,19 @@ Status: implemented
 
 已交付的 TUI 和 Web／无头 `cordis.yml` 配置树包含一个空的 `repository-plugins` 配置项。用户只需修改 `$DSH_HOME/config.yaml`，用 `repositories` 列表替换该配置项的配置。每一项采用 `github:owner/repository#<ref>`，并可追加 `&path:/.../.dsh-plugin`；省略时选择 `/.dsh-plugin`。必须显式指定 ref；路径是仓库内的绝对路径，并以 `.dsh-plugin` 结尾；重复的规范化说明符在安装前即被拒绝。不提供插件市场、发现索引、HTTPS URL 词汇或隐式的最新版本。
 
-`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择配置的仓库子包（package），运行包括 `prepare` 在内的普通生命周期，并原子发布该精确说明符。DSH 宿主只导入生成的 `dsh-plugin.mjs` 包装模块并将其挂载为子 fiber，因此 skill（技能）与 MCP 仍沿用格式包定义的所有者、失败契约和清理行为。
+`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择配置的仓库子包，运行包括 `prepare` 在内的普通生命周期，并原子发布该精确说明符。DSH 宿主只导入生成的 `dsh-plugin.mjs` 包装层并将其挂载为子 fiber，因此 skill（技能）与 MCP 仍沿用格式包定义的所有者、失败约定和清理行为。
 
 ## 实时更新与失败
 
-`dsh-app-boot` 通过一个辅助函数挂载根 Include，并保留其确切的 Loader `Entry`。TUI 和 Web 通过 Cordis HMR（热模块替换）注册 `$DSH_HOME/config.yaml`；无头界面在启动时读取同一文件，但不保留监视器。监视器更新会重新构建 Include 补丁列表，先放置不可变的应用自有补丁，再放置新解析的个人补丁。因此，Web 生成的端口、会话根目录、信任和前端值会在每次个人编辑后保留，除非后续个人补丁有意替换相应配置项。
+`dsh-app-boot` 通过一个辅助函数挂载根 Include，并保留其确切的 Loader `Entry`。TUI 和 Web 通过 Cordis HMR（热模块替换）注册 `$DSH_HOME/config.yaml`；无头模式在启动时读取同一文件，但不保留监视器。监视器更新会重新构建 Include 补丁列表，先放置不可变的应用自有补丁，再放置新解析的个人补丁。因此，Web 生成的端口、会话根目录、信任和前端值会在每次个人编辑后保留，除非后续个人补丁有意替换相应配置项。
 
-Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader 以事务方式协调候选配置：成功时提交新源列表；拉取、准备、包装模块导入、格式或子插件失败时拒绝候选配置，并保留或恢复最后一个可用树。HMR 会把捕获的值规范化为 `Error`，记录错误，并广播并行的 `hmr/config-update-failed(filename, error)` 事件；观察者失败不会中断刷新处理。MCP 传输连接失败仍沿用现有 MCP 客户端所收束的「插件成功加载但无工具」结果，因此不会被重新分类为配置更新失败。
+Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader 以事务方式协调候选配置：成功时提交新源列表；拉取、准备、包装层导入、格式或子插件失败时拒绝候选配置，并保留或恢复最后一个可用树。HMR 会把捕获的值规范化为 `Error`，记录错误，并广播相应的 `hmr/config-update-failed(filename, error)` 事件；观察者失败不会中断刷新处理。MCP 传输连接失败仍沿用现有 MCP 客户端所收束的「插件成功加载但无工具」结果，因此不会被重新分类为配置更新失败。
 
 相同说明符会永久复用同一个缓存版本。HMR 监视配置，而非已缓存的仓库代码；用户必须改变 ref、路径或源列表，才能选择另一个版本。
 
 ## 信任边界
 
-配置仓库即授权该仓库及其依赖中的包管理器生命周期代码以用户的文件系统权限运行。pnpm 子进程会移除名称中含有 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN` 的环境变量，但这只会减少凭据暴露，并非沙箱。固定的运行时包装模块会阻止仓库作者提供的 Cordis 入口成为受支持插件格式的一部分；它无法让包准备过程安全执行不受信任的代码。
+配置仓库即授权该仓库及其依赖中的包管理器生命周期代码以用户的文件系统权限运行。pnpm 子进程会移除名称中含有 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN` 的环境变量，但这只会减少凭据暴露，并非沙箱。固定的运行时包装层会阻止仓库作者提供的 Cordis 入口成为受支持插件格式的一部分；它无法让包准备过程安全执行不受信任的代码。
 
 ## 考虑过的替代方案
 
@@ -36,7 +36,7 @@ Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader
 
 **监视缓存内容，或自动刷新相同 ref。** 否决，因为一个配置值必须标识一个不可变的已准备版本。后台远端解析会在没有配置差异的情况下改变可执行代码，并使回滚依赖可变的远端状态。
 
-**广播 `unknown` 失败载荷。** 在 HMR 边界否决。JavaScript 内部可以抛出任意值，但公开事件始终接收规范化的 `Error`，从而为观察者提供稳定契约，并在需要时把原始值保留为错误原因。
+**广播 `unknown` 失败载荷。** 在 HMR 边界否决。JavaScript 内部可以抛出任意值，但公开事件始终接收规范化的 `Error`，从而为观察者提供稳定约定，并在需要时把原始值保留为错误原因。
 
 ## 后果
 
@@ -47,4 +47,4 @@ Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader
 
 ## 测试
 
-仓库包测试固定源规范化、默认和嵌套 `.dsh-plugin` 路径、缓存根解析、重复项拒绝、已准备包装模块加载及资源释放。App-boot 测试通过真实 HMR／Include／Loader 路径驱动确切路径的新增、两类失败、恢复、移除、失败事件及生成补丁保留。一个无密钥 PTY 冒烟测试仅通过个人配置启动已交付的 `dsh` 组合，并从预置的不可变缓存版本中调用一个 skill。
+仓库包测试固定源规范化、默认和嵌套 `.dsh-plugin` 路径、缓存根解析、重复项拒绝、已准备包装层加载及资源释放。App-boot 测试通过真实 HMR／Include／Loader 路径驱动确切路径的新增、两类失败、恢复、移除、失败事件及生成补丁保留。一个无密钥 PTY 冒烟测试仅通过个人配置启动已交付的 `dsh` 组合，并从预置的不可变缓存版本中调用一个 skill。
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
index 54966549ba..0a06bb5f51 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
 2026-07-30-continuable-subagent-report-tool.md: 8324f1fa08f7dace6153712575e7e70a07ee9344
-2026-07-30-continuable-subagent-report-tool.zh.md: e7599c1d85328e83c7773718101b59e763a1e37f
+2026-07-30-continuable-subagent-report-tool.zh.md: 7adc4acc470bd701eee756e7d9ef89d287852a57
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
index e7599c1d85..7adc4acc47 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
@@ -1,4 +1,4 @@
-# Agent Note（agent 决策记录）：可继续 subagent 报告工具
+# Agent Note: 可继续 subagent 报告工具
 
 Status: implemented
 
@@ -8,15 +8,15 @@ Status: implemented
 
 可继续的进程内 subagent 能够接收 parent 后续发来的消息、保留后代、结算并冷恢复，但基础生命周期无法让它们将选中内容发送给直接 parent。child 的完整输出已可从持久化会话中重建，因此缺失的能力是显式投递，而非结果存储。
 
-如果将每条 assistant 最终消息都视为隐式结果，就会混淆轮次完成与报告。长期运行的 child 可能在某个轮次中无内容可报告，也可能在另一个轮次多次报告进展，而且报告后必须仍可继续工作。因此，接收方权限、静默投递与唤醒投递、确认、持久性和重试行为都需要一份显式契约。
+如果将每条 assistant 最终消息都视为隐式结果，就会混淆轮次完成与报告。长期运行的 child 可能在某个轮次中无内容可报告，也可能在另一个轮次多次报告进展，而且报告后必须仍可继续工作。因此，接收方权限、静默投递与唤醒投递、确认、持久性和重试行为都需要一份显式约定。
 
 ## 决策
 
-新增可独立安装的 `@deepseek-ai/dsh-tool-subagent-report` 包（package）。它会向每个可继续进程内 child Activation 贡献一个普通的面向模型 `report` 工具。child 在一个轮次中可调用零次或多次。调用成功既不会结束该轮次或结算 Activation，也不会阻止 parent 之后继续 follow-up；完成轮次也绝不会自动报告。
+新增可独立安装的 `@deepseek-ai/dsh-tool-subagent-report` 包。它会向每个可继续进程内 child Activation 贡献一个普通的面向模型 `report` 工具。child 在一个轮次中可调用零次或多次。调用成功既不会结束该轮次或结算 Activation，也不会阻止 parent 之后继续 follow-up；完成轮次也绝不会自动报告。
 
 该功能是协作控制，不是承载结果的执行包装层。它不新增 Task、`SubagentRun`、结果 promise、Activation 状态、投递队列或回放路径。
 
-### 面向模型的契约
+### 面向模型的约定
 
 `report` 只接受 `{ output: string }`，也只返回 `{ messageId: string }`。它不接受 child id、接收方 id 或投递模式。`exec.agent` 将工具调用绑定到发送报告的 child；服务从持久化 `parentSession` 中推导唯一接收方，调度则由部署配置决定。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 工具描述会明确报告操作是显式、可重复、仅限直接 parent 且不会结束轮次的。它还会警告：发送被接受后，后续 `tools/post-execute` 失败可能替换工具结果，因此工具结果失败时内容仍可能已经送达。没有幂等键时，更强的表述会诱导调用方在结果不明确的失败后重复重试。
 
-该工具使用不带 location 的通用渲染，其确认中包含 `messageId`。作用域局部注册使呈现与执行保持一致：root、one-shot child、远程提供方、同级作用域和无 agent 执行既不能看到，也不能执行 `report`。它会在 child 的全局 `toolFilter` 之后安装，因此委派 allow-list 不会意外移除这条结构性返回通道；不需要返回通道的部署不安装该包。
+该工具使用不带 location 的通用渲染，其确认中包含 `messageId`。作用域局部注册使呈现与执行保持一致：root、one-shot child、远程提供方、同级作用域和无 agent（智能体）执行既不能看到，也不能执行 `report`。它会在 child 的全局 `toolFilter` 之后安装，因此委派 allow-list 不会意外移除这条结构性返回通道；不需要返回通道的部署不安装该包。
 
 ### 服务权限
 
@@ -40,7 +40,7 @@ root、one-shot child、伪造对象、陈旧 Agent 和同 id 替换对象都以
 
 静默投递调用 `parent.inject()`。它会添加模型可见上下文，但不启动 parent 模型请求：若 parent 空闲，则在调用返回前追加消息；若 parent 正在准入或运行，则暂存报告，留到下一个安全日志位置。该模式不创建 inbox 条目实例，因此也不会产生虚构的继续执行管理器接受记录。
 
-唤醒投递调用 `parent.followup()`。它会创建一个普通的 FIFO parent 轮次，唤醒已驻留的 parent driver，且绝不 steering 已开始的轮次。当该 parent 本身也是可继续 Activation 时，发送会使用管理器现有的准入计数，防止 parent 在同步入队与准入微任务之间结算。
+唤醒投递调用 `parent.followup()`。它会创建一个普通的 FIFO parent 轮次，唤醒已停驻的 parent driver，且绝不 steering（中途引导）已开始的轮次。当该 parent 本身也是可继续 Activation 时，发送会使用管理器现有的准入计数，防止 parent 在同步入队与准入微任务之间结算。
 
 两种模式都会将一条用户角色消息封装为 `Background subagent <child-id> reported:`，后面跟随完全原样的 `output`。持久化来源信息为 `{ kind: 'subagent-report', senderSessionId: child.id }`。并发发送的顺序由 Agent 的常规规则决定；subagent 层不会创建第二条队列。
 
@@ -48,13 +48,13 @@ root、one-shot child、伪造对象、陈旧 Agent 和同 id 替换对象都以
 
 成功表示确切的在线 parent 已同步接受该消息。空闲 parent 在接受静默注入时已经完成追加，而暂存的静默上下文只有到达正常日志边界后才可重建。唤醒投递包含一个 inbox 条目实例，其 id 与返回的稳定消息 id 保持分离。
 
-首个版本不提供持久化邮箱、幂等键、投递回执、重试协议或恰好一次保证。进程故障可能让调用方无法确定结果，在结果未知时重试则可能重复报告。parent 不可用时，持久化 child transcript 仍是恢复来源。
+首个版本不提供持久化邮箱、幂等键、投递回执、重试协议或恰好一次保证。进程故障可能让调用方无法确定结果，在结果未知时重试则可能重复报告。parent 不可用时，持久化 child transcript（文本记录）仍是恢复来源。
 
 ### 组合与生命周期
 
 subagent seam 新增 `registerContinuableSetup(contribution): () => void`，由 `SubagentActivationSetupRegistry` 支撑。每个同步贡献都会接收尚未发布的 child 上下文，并返回其安装的 disposer。继续执行管理器首先应用基础 child 组合，然后通过同一个用于首次创建与冷恢复的设置闭包，按注册顺序应用当前贡献。
 
-注册表负责注册、每个 child 的安装记录、设置回滚、child 作用域清理和立即撤销。应用一个批次会返回 Agent setup 提交对象，用于在所有 setup 的 await 均结算后、紧邻 Agent 发布前重新校验配置状态。因此，某项贡献抛出异常或被并发撤销时，会在 Agent 与 Session 发布前拒绝操作并回滚该批次。新注册项只会在驻留 child 的下一个 Activation 生效；移除注册项时，会先将它对新设置关闭，再立即撤销为正在配置或驻留的每个 child 安装的实例。注册 dispose 与 child 上下文 dispose 都是幂等的，两者都会先尝试每项释放，再聚合失败。
+注册表负责注册、每个 child 的安装记录、设置回滚、child 作用域清理和立即撤销。应用一个批次会返回 Agent setup 提交对象，用于在所有 setup 的 await 均结算后、紧邻 Agent 发布前重新校验配置状态。因此，某项贡献抛出异常或被并发撤销时，会在 Agent 与会话发布前拒绝操作并回滚该批次。新注册项只会在驻留 child 的下一个 Activation 生效；移除注册项时，会先将它对新设置关闭，再立即撤销为正在配置或驻留的每个 child 安装的实例。注册 dispose（资源释放）与 child 上下文 dispose 都是幂等的，两者都会先尝试每项释放，再聚合失败。
 
 该 seam 使继续执行管理器无需知道工具名。report 包只安装 `report`；`@deepseek-ai/dsh-tool-subagent-control` 则独立安装 parent 侧的 `send_message` 和 `list_agents`。部署时可安装任一方向、同时安装两者或两者均不安装。提供方仍只负责数据，持久化描述符不会对 report 可用性或投递模式建立快照，冷恢复则使用部署当前的贡献与策略。
 
@@ -96,7 +96,7 @@ ACP（Agent Client Protocol）快照 harness 新增 `waitForSubagentTurnEnd`，
 
 ### 在 Agent 创建后校验 setup
 
-创建完成后的撤销检查只能在 Agent 与 Session 均已发布后拒绝 Activation。对返回的 handle 执行 dispose 会移除实时对象，但当前 seam 无法删除持久化内容，因此会留下一个仍可恢复的 child，而继续执行管理器却判定它从未建立。改为返回 `AgentSetupCommit`，Agent 工厂便可在自身的发布边界同步执行同一项可变状态检查。
+创建完成后的撤销检查只能在 Agent 与会话均已发布后拒绝 Activation。对返回的 handle 执行 dispose 会移除实时对象，但当前 seam 无法删除持久化内容，因此会留下一个仍可恢复的 child，而继续执行管理器却判定它从未建立。改为返回 `AgentSetupCommit`，Agent 工厂便可在自身的发布边界同步执行同一项可变状态检查。
 
 ## 影响
 
@@ -115,4 +115,4 @@ ACP（Agent Client Protocol）快照 harness 新增 `waitForSubagentTurnEnd`，
 
 wakeup 模式可能在嵌套 child 频繁报告时放大模型工作量。由部署所有者控制并默认静默，可以限制该风险，但无法完全消除。
 
-注册表中的存在性就是 parent 在线信号。宿主拥有的 parent 如果已开始 `AgentHandle.dispose()` 但尚未展开其作用域，仍可能接受并追加一条本进程不会再处理的报告。要弥合这个缺口，需要 Agent 层面的 dispose 开始信号，不能由 subagent 层推断。
+注册表中的存在性就是 parent 在线信号。宿主拥有的 parent 如果已开始 `AgentHandle.dispose()` 但尚未完成其作用域清理，仍可能接受并追加一条本进程不会再处理的报告。要弥合这个缺口，需要 Agent 层面的 dispose 开始信号，不能由 subagent 层推断。
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
index 9e267e82a0..9ae0827be2 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
 2026-07-30-current-sandbox-policy-context.md: 093f9a8a0b58256bb4f2301cc62fa83629de4fbd
-2026-07-30-current-sandbox-policy-context.zh.md: 729ea9d50c7dbbfa027e1cad11929ae1c2b379b1
+2026-07-30-current-sandbox-policy-context.zh.md: ce7ff2d0cff0fc1068995fde174a4eb1df5343b7
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
index 729ea9d50c..ce7ff2d0cf 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 现有 `dsh-system-prompt` 组装在稳定系统段与工具 schema 之外，还包含有序的动态上下文。组装一个步骤后，agent loop（智能体循环）会将所有活动上下文渲染成一份带显式取代声明的完整快照。仅当不存在保留快照、字节发生变化、压缩（compaction）移除了保留消息，或最后一项贡献消失而需要一份清除快照时，它才会追加一条带来源的 `user/message`。快照追加在现有历史之后、`step/start` 之前，因此策略变化时仍会保留此前的系统与对话缓存前缀。会话事件本身可以重建确切的模型输入；只有策略上下文变化时，`request/header` 仍逐字节相同。
 
-归属范围保持收敛。批准策略会将其完整的当前 `ask` 或 `never` 事实贡献给同一份完整快照；只迁移沙箱无法保留缓存，因为 `/permission` 会同时改变两方。计划模式仍由 `plan:policy` 负责，工具插件也继续负责各自的 schema，以及尝试、拒绝与升级引导。上下文负责说明常驻策略；文件系统、一次性 bash 与终端后端仍是强制执行边界。
+归属范围仍然有限。批准策略会将其完整的当前 `ask` 或 `never` 事实贡献给同一份完整快照；只迁移沙箱无法保留缓存，因为 `/permission` 会同时改变两方。计划模式仍由 `plan:policy` 负责，工具插件也继续负责各自的 schema，以及尝试、拒绝与升权引导。上下文负责说明常驻策略；文件系统、一次性 bash 与终端后端仍是强制执行边界。
 
 缓存决策依据当前源码，而不只依靠类比。Codex 将权限建模为 developer 角色的 `WorldState` 段并保存其指纹；只有状态变化或保留的历史丢失该片段时才发出它，同时记录快照转换。Hermes 在会话期间保持系统提示词不变，并明确将不断变化的 skill（技能）、模型与语音通知前置到下一条用户消息，以免提示词缓存失效。Pi 没有可比的内置沙箱状态，Claude Code 当前的原生实现也无法公开检视；不过，Anthropic 的公开缓存指南仍将不断变化的逐请求上下文放在稳定缓存前缀之后。
 
@@ -26,7 +26,7 @@ Status: implemented
 
 ## 措辞证据
 
-措辞实验预先登记「预防性拒绝」为主要终点，并要求旧常驻句子在十二个 fresh session 中至少产生一次拒绝，之后才能评判任何替代措辞。2026-07-30，commit `2bf41990401b194bd8637f07bbd90c67a9eeac75` 通过已交付的 Web 组合运行 `deepseek-v4-flash`，使用精确的阳性对照句子 `Bash commands run under the "read-only" file sandbox.` 与当前工具归属方的尝试引导。对照组产生零次预防性拒绝和零次推测性升级；十二个会话全部先发起普通 bash 调用、观察到拒绝、在同一轮次升级、获得批准，并让所请求文件实际落盘。没有样本被排除。
+措辞实验预先登记「预防性拒绝」为主要终点，并要求旧常驻句子在十二个 fresh session 中至少产生一次拒绝，之后才能评判任何替代措辞。2026-07-30，commit `2bf41990401b194bd8637f07bbd90c67a9eeac75` 通过已交付的 Web 组合运行 `deepseek-v4-flash`，使用精确的阳性对照句子 `Bash commands run under the "read-only" file sandbox.` 与当前工具归属方的尝试引导。对照组产生零次预防性拒绝和零次推测性升权；十二个会话全部先发起普通 bash 调用、观察到拒绝、在同一轮次升权、获得批准，并让所请求文件实际落盘。没有样本被排除。
 
 缓存安全交付变更后，commit `10d4e0ff7b68d38fc4403403b644aac442b97a00` 通过新的尾部上下文通道重复了同一项十二会话阳性对照。结果再次为零次预防性拒绝和零次推测性升权；十二个会话的首次调用均为普通调用，随后观察到拒绝、在同一轮次升权并获得批准。其中八个会话让所请求文件按确切要求落盘，没有样本被排除。
 
@@ -42,7 +42,7 @@ Status: implemented
 
 **把当前策略放入动态系统段。** 不予采用，因为真实提供方证据显示，首次权限切换后缓存读取降至 256 个 token，而约 14.7k 个输入 token 未命中缓存。DeepSeek 匹配完整前缀；改变第一条 wire 消息会阻止复用更长的系统与历史前缀。
 
-**由每个策略归属方独立调用 `agent.inject()`。** 不予采用，因为同级监听器的顺序会决定模型所见顺序，分开的消息可能暴露不匹配的中间快照，并且每个归属方都需要各自扫描压缩后的保留状态。现有组装归属方可以对贡献排序，并具体化一份原子化的完整快照。
+**由每个策略归属方独立调用 `agent.inject()`。** 不予采用，因为同级监听器的顺序会决定模型所见顺序，分开的消息可能暴露不匹配的中间快照，并且每个归属方都需要各自扫描压缩后的保留状态。现有组装归属方可以对贡献排序，并生成一份原子化的完整快照。
 
 **通用运行时事实包。** 不予采用，因为现有系统提示词组装已经拥有段、schema、变量、作用域和权威的逐步骤 waterfall（瀑布式事件）。为该归属方增加有序上下文，无需新增包或第二个注册表服务。
 
@@ -50,7 +50,7 @@ Status: implemented
 
 **缓存安全迁移后仍保留 Candidate A。** 不予采用，因为中性的真实提供方任务中，尽管已有 bash 尝试引导，模型仍以纯文本拒绝，且没有调用工具。保留下来的反预防性拒绝原则本身不说明任何升权机制；它告诉模型不要从常驻标签推断操作不可能完成，然后把拒绝与升权行为交还给可用工具。
 
-**继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具契约下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
+**继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具约定下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
 
 **独立的模型上下文包。** 不予采用，因为策略归属方可以直接解析当前会话状态，现有组装服务也可以对其排序。新包只会围绕同一个请求边界引入浅层组合 seam 和额外的文档／门禁表面。
 
@@ -60,4 +60,4 @@ Status: implemented
 
 模型在试探工具前就会收到常驻文件策略，且 `/permission` 后的下一个请求会反映已提交的模式。稳定的系统提示词不再随沙箱或批准状态变化；变化后的完整上下文快照会在保留的历史之后仅追加，状态不变时不增加消息。较旧的快照仍保留在历史中，但最新的完整快照会明确取代它们。该声明是引导，而不是强制执行护栏：运行时安全仍来自文件系统、一次性 bash 与终端后端消费同一项解析完成的策略。
 
-聚焦测试固定了所有模式、规范化根目录、切换时机、服务释放、上下文顺序、清除、稳定的请求 header、恢复，以及不同 `TMPDIR` 值下的字节稳定性。无密钥的组装快照通过真实 Loader 组合固定持久上下文消息。无密钥回放负责固定中性的拒绝到升级轨迹；它是结构回归证明，而不是措辞选型证据。
+聚焦测试固定了所有模式、规范化根目录、切换时机、服务释放、上下文顺序、清除、稳定的请求 header、恢复，以及不同 `TMPDIR` 值下的字节稳定性。无密钥的组装快照通过真实 Loader 组合固定持久上下文消息。无密钥回放负责固定中性的拒绝到升权轨迹；它是结构回归证明，而不是措辞选型证据。
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
index 418c81f17d..9a60eff44c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
 2026-07-30-deepseek-onboarding-credential-setup.md: 419ea0aea56e82e301189d90d5ca78495da2da71
-2026-07-30-deepseek-onboarding-credential-setup.zh.md: 936402c9ed83eccc3d5e78a57247f06347522c0f
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: 46d23d40bc689a2827721e8b5cef47825355266f
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
index 936402c9ed..46d23d40bc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
@@ -12,15 +12,15 @@ Status: implemented
 
 **Models 与首次使用引导共享同一个就绪状态投影。**`ui-models` 维护一个 store，把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取由 `llm-deepseek` namespace 与空 settings path 持有的 `deepseek-official` 可配置提供方条目，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。同 provider id 但没有匹配可配置提供方声明的存活路由，在首次使用引导中视为适配器缺失。通过进程环境提供的凭据若已配置，则判定为就绪并保持只读。
 
-**设置外壳只贡献排序与导航，不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 通过 `slots.inject()` 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为契约；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
+**设置外壳只贡献排序与导航，不持有提供方策略。**`ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 通过 `slots.inject()` 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为约定；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
 
-**首次使用页面只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用页面绝不持有或提交 secret。
+**首次使用页面只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用页面绝不持有或提交 secret。设置或凭据能力不可用时，界面会保留相应的部署诊断，并将用户引导至同一页面；适配器缺失时则仍跳过该步骤，因为导航无法挂载 Cordis 插件。
 
-**不可用状态不会占住产品。** 可配置提供方条目缺失、路由不活跃、初始联接失败、部署只读或设置／凭据能力无法解析时，都会直接完成而不渲染该步骤，因为首次使用引导无法修复这些状态。Models 页仍是部署诊断与重试界面。「稍后配置」只会完成协调器当前这一次缺少凭据的步骤，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可完成已打开的步骤。
+**不可用状态不会占住产品。**可配置提供方条目缺失、路由不活跃、初始联接失败、部署只读或设置／凭据能力无法解析时，都会直接完成而不渲染该步骤，因为首次使用引导无法修复这些状态。Models 页仍是部署诊断与重试界面。「稍后配置」只会完成协调器当前这一次缺少凭据的步骤，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可完成已打开的步骤。
 
 ## 曾考虑的替代方案
 
-**为首次使用引导单设 store 与就绪状态 RPC 调用序列**：不予采用，因为这会在 Models 页之外，再建立一套客户端解释，用于判定提供方身份、设置路径、secret 槽位的伴随信息、凭据引用及失效事件顺序。
+**为首次使用引导单设 store 与就绪状态 RPC 调用序列**：不予采用，因为这会在 Models 页之外，再建立一套客户端解释，用于判定提供方身份、设置路径、secret 伴随文件、凭据引用及失效事件顺序。
 
 **在首次使用引导中增设第二个 API key 编辑器**：不予采用，因为 Models 页已为这一状态渲染 DeepSeek 设置卡片。复制其中的 secret 草稿、写入错误处理和已配置状态收敛会增加第二个安全敏感的 UI，却不会带来新的用户能力。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
index 1ceb5a5213..a23468b591 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
 2026-07-30-queued-manual-compaction.md: 5100808ada4b7b284228113584e577d46ff91101
-2026-07-30-queued-manual-compaction.zh.md: 29c3b921d0d59527aa1d8af1c91d085b52045377
+2026-07-30-queued-manual-compaction.zh.md: c995fc59fda83de639b6e1a603448243ba12c505
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
index 29c3b921d0..c995fc59fd 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 维护阶段不会创建第二个队列。之后发送的项保留其 `MessageId`、位置、FIFO 顺序与唤醒信息。会唤醒的输入会保持排队，直至维护任务结算，再启动既有驱动器路径；`inject()` 仍然不会唤醒驱动器。
 
-`whenIdle()` 会把维护任务及其结算后释放的所有唤醒工作视为尚未完成的活动。取消会中止 agent 自有的维护信号，生命周期 teardown 则会在 dispose（资源释放）完成前排空同一个活动边界。
+`whenIdle()` 会把维护任务及其结算后释放的所有唤醒工作视为尚未完成的活动。取消会中止 agent（智能体）自有的维护信号，生命周期 teardown 则会在 dispose（资源释放）完成前排空同一个活动边界。
 
 ### 一个参数化事务拥有每一对标记
 
@@ -89,7 +89,7 @@ DSH 有意在调用摘要器前记录 `compact/start`。缓慢或崩溃的尝试
 
 **同时使用持久标记与进程本地 mutex。** 不予采用，因为两项权威在回放后可能产生分歧，还会要求用包装层分支处理标记对已经表达的状态。
 
-**与唤醒提示词一起阻塞注入。** 不予采用，因为按契约，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。
+**与唤醒提示词一起阻塞注入。** 不予采用，因为按约定，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。
 
 **要求标记区间只包含压缩事件。** 不予采用，因为标记表示锁的时间点。溯源信息会精确指明所选 seq 与被遮蔽 seq；排他性不会增加正确性，只会拒绝有效注入。
 
@@ -97,9 +97,9 @@ DSH 有意在调用摘要器前记录 `compact/start`。缓慢或崩溃的尝试
 
 ## 验证
 
-Agent loop 测试覆盖同一 tick 内的优先权、保留 ID 与 FIFO 生命周期、会唤醒和静默的排队工作、幂等释放、`whenIdle()`、取消与 teardown。压缩测试覆盖独立与数字形式的不变量 owner、end-seed 回放、活动与陈旧未匹配标记、listener 重入、所选 span 漂移、commit 与闭合失败、flush 顺序、原始取消原因、raw output 与 usage 保留，以及自动／手动互斥。
+agent loop（智能体循环）测试覆盖同一 tick 内的优先权、保留 ID 与 FIFO 生命周期、会唤醒和静默的排队工作、幂等释放、`whenIdle()`、取消与 teardown。压缩测试覆盖独立与数字形式的不变量 owner、end-seed 回放、活动与陈旧未匹配标记、listener 重入、所选 span 漂移、commit 与闭合失败、flush 顺序、原始取消原因、raw output 与 usage 保留，以及自动／手动互斥。
 
-命令包固定注册行为、Loader 组合、参数拒绝、精确的成功／失败文本、取消、不进入模型历史的保证，以及处置操作在中止使执行器停止等待处理器后，仍会跨越相互独立的闭合与 flush 边界等待该处理器结算。客户端运行时投影测试固定 end-seed 中断，以及随后一次独立尝试的完成。`queued-manual-compact` 终端快照通过已组装 TUI 驱动真实按键：`/help` 可发现该命令；被暂停的摘要会接纳一个排队提示词和即时注入；`turn: null` 标记与 flush 先于排队提示词轮次；命令生命周期保持纯日志；派生顺序固定为检查点 → 注入 → 排队提示词。
+命令包固定注册行为、Loader 组合、参数拒绝、精确的成功／失败文本、取消、不进入模型历史的保证，以及 dispose 在中止使执行器停止等待处理器后，仍会跨越相互独立的闭合与 flush 边界等待该处理器结算。客户端运行时投影测试固定 end-seed 中断，以及随后一次独立尝试的完成。`queued-manual-compact` 终端快照通过已组装 TUI 驱动真实按键：`/help` 可发现该命令；被暂停的摘要会接纳一个排队提示词和即时注入；`turn: null` 标记与 flush 先于排队提示词轮次；命令生命周期保持纯日志；派生顺序固定为检查点 → 注入 → 排队提示词。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
index f26524cdc3..9f2a4c87ab 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-search-render-card.md
 2026-07-30-search-render-card.md: 29544cb703f3ab048f4e7702935887ecf05179bf
-2026-07-30-search-render-card.zh.md: e0ae21924e82152ba629ab628476113ad9afe3d8
+2026-07-30-search-render-card.zh.md: e4cb39f562ea54b03e2b502ec19a90571c22e5e3
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
index e0ae21924e..e4cb39f562 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：搜索渲染意图 —— grep 与 glob 产出结构化搜索卡片
+# Agent Note: 搜索渲染意图 —— grep 与 glob 产出结构化搜索卡片
 
 Status: implemented
 
@@ -8,7 +8,7 @@ Status: implemented
 
 `grep` 与 `glob` 返回结构化的 canonical 值 —— `grep` 是扁平的 `{ matches: [{ path, lineNumber, line }] }`，`glob` 是 `{ paths: string[] }` —— 但每个 UI 只见过它们面向模型的渲染文本：`grep` 把匹配按文件头分组、每行 `Line N:`，`glob` 打印换行连接的路径列表，两者在内联上限（`grepMaxMatches`，默认 250；`globMaxResults`，默认 100）把后续结果落到 spill 文件时都追加一个 spill 脚注。想把搜索结果渲染成可展开的按文件匹配组、或可选择的路径列表的 web 前端，只能去重新解析那段文本。两个工具都已声明调用时的[渲染意图](../architecture/2026-07-02-tool-render-intent-union.md)（`GenericCallView`，`kind: 'search'`），但没有结果时视图，所以已完成的调用回退到渲染原始文本的 generic 卡片。
 
-结构化 canonical 值不跨线传输：只有面向模型的渲染文本、以及当工具声明了 `output.presentationMeta` 时的一份 JSON 元数据，会经 `tool/result` 事件到达客户端（[canonical-output 契约](../architecture/2026-07-20-canonical-tool-output-contract.md)）。因此携带结构化数据的结果时视图必须把数据投影进 `presentationMeta`，再在 `presentResult` 里读回 —— 与 `write`/`edit` 的 diff 卡片走同一条路。
+结构化 canonical 值不跨线传输：只有面向模型的渲染文本、以及当工具声明了 `output.presentationMeta` 时的一份 JSON 元数据，会经 `tool/result` 事件到达客户端（[canonical-output 约定](../architecture/2026-07-20-canonical-tool-output-contract.md)）。因此携带结构化数据的结果时视图必须把数据投影进 `presentationMeta`，再在 `presentResult` 里读回 —— 与 `write`/`edit` 的 diff 卡片走同一条路。
 
 ## 决定
 
@@ -30,7 +30,7 @@ Status: implemented
 
 `SearchMeta` 的成员形状是对象字面量 `type` 别名，而非视图暴露的 `SearchFileMatches`/`SearchLineMatch` 接口，因为只有 type 别名可赋给 `presentationMeta` 返回的 `JsonValue` 索引签名；两者结构等价，所以投影值仍读回为 `SearchResultView`。
 
-没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而本 PR 之前 grep/glob 返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端契约及其两个生产者。
+没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而本 PR（Pull Request）之前 grep/glob 返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端约定及其两个生产者。
 
 ## 考虑过的备选
 
@@ -40,7 +40,7 @@ Status: implemented
 
 **把面向模型的文本作为视图的 `content` 附上。** 否决：对每个当前消费方是 no-op，且把整段搜索文本第二次序列化进持久化视图。视图是结构化形状；文本回退读原始结果内容。
 
-**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决：它为一个工具的载荷改动核心工具决策契约与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
+**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决：它为一个工具的载荷改动核心工具决策约定与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
 
 **镜像 terminal 卡片双侧对称的调用时 `SearchCallView`。** 否决：搜索调用在 `execute` 前没有匹配或路径，视图只会携带 `GenericCallView` 已有的标题。
 
@@ -57,5 +57,5 @@ Status: implemented
 ## 相关
 
 - [工具调用呈现的带标签渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 PR 用 `search` 结果标签扩展的 `card` 标签词汇。
-- [Canonical 工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所乘的 value/render/`presentationMeta` 划分；结构化值留在执行本地，卡片乘 `meta`。
+- [Canonical 工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所依托的 value/render/`presentationMeta` 划分；结构化值留在执行本地，卡片通过 `meta` 传输。
 - [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— 本 PR 在后端镜像的先例：工具把结果投影进 `presentationMeta` 与一个 `presentResult` 视图；搜索卡片的 web 消费方是与之类比的后续。
diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml
index 10de05ea42..0762a4d131 100644
--- a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.md
 2026-07-30-versioned-gui-welcome-onboarding.md: 4707769d4fa9fbf184e09a2e73087dfd326070be
-2026-07-30-versioned-gui-welcome-onboarding.zh.md: c9d2e6274c476c59abc077aa3255ffe57a8a48bc
+2026-07-30-versioned-gui-welcome-onboarding.zh.md: 002a04b1fc6acc4fc7cfee053bdbbb2abaef047e
diff --git a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md
index c9d2e6274c..002a04b1fc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-versioned-gui-welcome-onboarding.zh.md
@@ -14,11 +14,11 @@ GUI 的凭据引导从 DeepSeek 专用的就绪状态检查开始，但内部测
 
 **不属于单一功能的产品引导由 `ui-settings-general` 持有。** `src/onboarding-copy.ts` 是完整通知、「继续」按钮文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源；GUI 支持的两种 locale 都有意渲染同一份中文所有者文案。运行时 locale 字典从该文件派生欢迎文案，测试也导入同一个所有者，而不重复段落文本。该通知只存在于浏览器 UI：它不会创建会话事件，也不会贡献任何模型可见内容。通知明确以 `DSH_TELEMETRY_DISABLED=1` 作为遥测关闭方式。
 
-**loopback 确认状态按 Harness profile 持久化。** 宿主端在 user-settings seam 中注册 `ui-onboarding` 分节，并存入当前 `$DSH_HOME/settings.yaml`。connection 插件通过 `ctx.connection.isLoopback` 统一发布当前页面是否使用 loopback authority；hostname 判定函数留在 connection 包内，其他客户端插件只消费服务状态，不跨插件导入实现函数。除非 `welcomeNoticeVersion` 与文案所有者文件中的常量精确相等，否则 loopback 浏览器会显示通知。「继续」会以当前版本执行一次路径变更，并且仅在宿主端提交成功后调用 `complete()`；写入失败时通知保持打开，关闭页面或进程则不会写入任何内容。提升该常量会有意要求每个 profile 对修订后的文案重新确认一次。非 loopback 浏览器不能调用仅限 loopback 的 settings API；它仍显示同一通知，但显式点击「继续」只会在当前浏览器进程中完成该步骤，重新加载或新进程会再次显示通知。
+**loopback 确认状态按 Harness profile 持久化。** 宿主端在 user-settings seam 中注册 `ui-onboarding` 分节，并存入当前 `$DSH_HOME/settings.yaml`。connection 插件通过 `ctx.connection.isLoopback` 统一发布当前页面是否使用 loopback authority；hostname 判定留在 connection 包内，其他客户端插件只消费服务状态，而不导入其实现。除非 `welcomeNoticeVersion` 与文案所有者文件中的常量精确相等，否则 loopback 浏览器会显示通知。「继续」会以当前版本执行一次路径变更，并且仅在宿主端提交成功后调用 `complete()`；写入失败时通知保持打开，关闭页面或进程则不会写入任何内容。更新该常量会有意要求每个 profile 对修订后的文案重新确认一次。非 loopback 浏览器不能调用仅限 loopback 的 settings API；它仍显示同一通知，但显式点击「继续」只会在当前浏览器进程中完成该步骤，重新加载或新进程会再次显示通知。
 
-**并发 loopback 视图无需陈旧的整体替换即可收敛。** 确认写入有意省略 `expectedRevision`：每个 loopback 标签页都向同一路径写入相同版本，因此该操作是幂等的，并会保留同级字段，而不是重建整个分节。`settings/document-updated` 会转为 `host/settings-changed`；另一个标签页或外部编辑器提交当前版本后，已挂载的 loopback 标签页会重新拉取状态并推进。API 网关在可配置提供方 namespace 之外，通过封闭的允许列表暴露这一个产品 namespace，同时不会把它的变更视为模型目录失效事件。
+**并发 loopback 视图无需陈旧的整体替换即可收敛。** 确认写入有意省略 `expectedRevision`：每个 loopback 标签页都向同一路径写入相同版本，因此该操作是幂等的，并会保留同级字段，而不是重建整个分节。`settings/document-updated` 会转为 `host/settings-changed`；另一个标签页或外部编辑器提交当前版本后，已挂载的 loopback 标签页会重新拉取状态并推进。API Proxy（`@deepseek-ai/dsh-host-apiproxy`）在可配置提供方 namespace 之外，通过封闭的允许列表暴露这一个产品 namespace，同时不会把它的变更视为模型目录失效事件。
 
-**引导流程会暂时接管视口，形成一个连续阶段。** 纯色产品界面通过挂载到 `body` 的 portal 取代完整的应用视图，并将底层应用根节点标记为 inert；严格符合要求的遮罩仍挂载在该界面后方，并保留 `position:absolute`、left/right/bottom 偏移量为零、`top:80px`、`rgba(0, 0, 0, 0.24)` 和 `backdrop-filter: blur(2px)`。欢迎页和按条件显示的凭据设置页在这一阶段中依次呈现，而不是各自作为独立的模态窗口。两个页面都复用 Web UI 的黑色 `BrandWordmark`。欢迎页在 `内测声明` 标题下逐字保留既定的四段文案；所有段落统一采用 16/28 的正文字号与行高，只有最后一段中指定的行动语句使用较为克制的 500 字重。短暂的错落式透明度与纵向位移动画营造出舒缓节奏，但不会阻碍交互，并会在用户启用减少动态效果时禁用。初始焦点落在标题上，「继续」是唯一按钮，且不存在关闭、Escape 或点击遮罩的退出路径。
+**引导流程会暂时接管视口，形成一个连续阶段。** 纯色产品界面通过挂载到 `body` 的 portal 取代完整的应用视图，并将底层应用根节点标记为 inert；严格符合要求的遮罩仍挂载在该界面后方，并保留 `position:absolute`、left/right/bottom 偏移量为零、`top:80px`、`rgba(0, 0, 0, 0.24)` 和 `backdrop-filter: blur(2px)`。欢迎页和按条件显示的凭据设置页在这一阶段中依次呈现，而不是各自作为独立的模态窗口。两个页面都复用 Web UI 的黑色 `BrandWordmark`。欢迎页在 `内测声明` 标题下逐字保留既定的四段文案；所有段落统一采用 16/28 的正文字号与行高，只有最后一段中指定的行动语句使用较为克制的 500 字重。短暂的错落式透明度与纵向位移动画营造出节奏感，但不会阻碍交互，并会在用户启用减少动态效果时禁用。初始焦点落在标题上，「继续」是唯一按钮，且不存在关闭、Escape 或点击遮罩的退出路径。
 
 ## 曾考虑的替代方案
 
@@ -28,7 +28,7 @@ GUI 的凭据引导从 DeepSeek 专用的就绪状态检查开始，但内部测
 
 **在渲染或窗口关闭时持久化**：不予采用，因为看见通知不等于确认，窗口关闭事件也无法可靠送达。只有显式提交「继续」才能阻止通知在下次启动时再次显示。
 
-**通用的公开设置暴露标志**：不予采用，因为一个产品 namespace 不足以证明应当扩大每个 settings 注册方的公开配置面。网关保留显式的封闭允许列表。
+**通用的公开设置暴露标志**：不予采用，因为一个产品 namespace 不足以证明应当扩大每个 settings 注册方的公开配置面。该 API Proxy 保留显式的封闭允许列表。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index d78733bb33..c848bc3822 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-diff-card.md
 2026-07-30-web-diff-card.md: b078da8d0e688d705683599467bd98b5c6a0be48
-2026-07-30-web-diff-card.zh.md: a9c710df99c1060bbf50b591b2f62120dc7dcbef
+2026-07-30-web-diff-card.zh.md: bf9424a9baff7ec6d49949016be3e30d400f2dd1
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index a9c710df99..bf9424a9ba 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -6,15 +6,15 @@ Status: implemented
 
 ## Problem
 
-`write` 和 `edit` 工具为其 call 和 result 都声明了 `card: 'diff'`（[render-intent union](../architecture/2026-07-02-tool-render-intent-union.md)）：call view 携带从参数推导的预期改动，result view 携带已应用的上下文 hunk（`FileDiff[]`，由 `packages/fs/tool-fs/src/diff.ts` 计算，并持久化在 result `meta` 中以便回放重建）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `callView`/`resultView` 投递到 `ConversationSnapshot` —— TUI 也已将其渲染为按文件分组的 `+`/`-` 块加 `+A -R · N file(s)` 页脚。
+`write` 和 `edit` 工具为其 call 和 result 都声明了 `card: 'diff'`（[render-intent union](../architecture/2026-07-02-tool-render-intent-union.md)）：call view 携带从参数推导的预期改动，result view 携带已应用的上下文 hunk（`FileDiff[]`，由 `packages/fs/tool-fs/src/diff.ts` 计算，并持久化在 result `meta` 中以便回放重建该视图）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `callView`/`resultView` 投递到 `ConversationSnapshot` —— TUI 也已将其渲染为按文件分组的 `+`/`-` 块加 `+A -R · N file(s)` 页脚。
 
-Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行从原始工具参数推导，详情面板把 result 的 content block 摊平进一个 `<pre>`。`diffs` 载荷 —— result 的全部意义 —— 被丢弃，于是一次文件改动读起来只是一行确认、看不到任何改动。
+Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行从原始工具参数推导，详情面板把 result 的 content block 摊平进一个 `<pre>`。`diffs` 载荷 —— result 的关键所在 —— 被丢弃，于是一次文件改动读起来只是一行确认、看不到任何改动。
 
-这是把 [terminal 卡片](2026-07-28-web-terminal-card.md) 对 `diff` 这一支重做一遍：那次改动让 Web 客户端成为 `terminal` 渲染意图的消费者；这次让它成为 `diff` 渲染意图的消费者，复用同一套四层结构。
+这是把 [terminal 卡片](2026-07-28-web-terminal-card.md) 对 `diff` 这一支重做一遍：那次改动让 Web 客户端成为 `terminal` 渲染意图的消费方；这次让它成为 `diff` 渲染意图的消费方，复用同一套四层结构。
 
 ## Decision
 
-`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-tool/src/client/tool/models/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
+`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-tool/src/client/tool/models/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时（包括 `card` 值为本客户端版本所不认识的值），以及已结算调用的 result view 是 generic 时，它返回 null——走通用路径；write/edit 的执行错误正是这样留在通用路径上的。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
 
 该组件与 TUI 共用单栏框架、行终止符规则和去重路径计数。两者的行分类不同：Web 渲染完整的变更前后两侧，而 TUI 会在有界比较完成时派生中性上下文和精确变更行，并把整侧回退标记为近似结果。
 
@@ -24,23 +24,23 @@ Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行
 - **行终止符。** 每一侧的内容按 `TerminalBlock` 与 TUI 共用的终止符规则在 `\n` 上切分：空文本是零行（整文件删除的 `newText`、新建缺失的 `oldText` 侧），单个结尾换行终止其最后一行而非新增一条幻影空行，内部空行保留。
 - **页脚与复制。** 暗色 `└ +A -R · N file(s)` 页脚报告 Web 卡片完整新侧与旧侧的行数。TUI 页脚则在可用时报告精确变更行数，并把有界整侧回退标记为近似结果；两者使用相同的去重路径计数。复制控件复制带前缀的 Web diff 文本（路径头、`- `/`+ ` 行、`⋯` gap），使多文件复制保持可辨别归属。
 
-几何、圆角、字体镜像 `CodeBlock`/`TerminalBlock`，使 diff 卡片、terminal 卡片、代码块读起来是一家；`white-space: pre` 加横向滚动是刻意的分歧。复制控件浮在卡片右上角，而非占据自己的 banner 行，因为只放一个复制按钮的 banner 会在第一行 diff 上方画出一条空带 —— TUI 的 diff 卡片也没有 banner，只有页脚。
+几何、圆角、字体与 `CodeBlock`/`TerminalBlock` 保持一致，使 diff 卡片、terminal 卡片、代码块读起来是一家；`white-space: pre` 加横向滚动是刻意的分歧。复制控件浮在卡片右上角，而非占据自己的 banner 行，因为只放一个复制按钮的 banner 会在第一行 diff 上方画出一条空带 —— TUI 的 diff 卡片也没有 banner，只有页脚。
 
-chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX_LINES`（8），对应面板的 16 —— 与 [terminal 卡片](2026-07-28-web-terminal-card.md#inline-output-in-the-chat-row-reverses-a-stated-convention)记录的内联输出决策、以及流内表面对单调阅读表面的同一划分一致。write/edit 行是单文件的，所以它的摘要既是可打开的路径链接，其 diff 卡片又展开；两者共存，因为卡片不是路径的参数体。
+chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX_LINES`（8），对应面板的 16 —— 与 [terminal 卡片](2026-07-28-web-terminal-card.md#inline-output-in-the-chat-row-reverses-a-stated-convention)记录的内联输出决策、以及流内表面与阅读表面的同一划分一致。write/edit 行是单文件的，所以它的摘要既是可打开的路径链接，其 diff 卡片又展开；两者共存，因为卡片不是路径的参数体。
 
 ## Alternatives considered
 
 **并排（双栏）diff。** owner 目前拒绝：它更密但不适合狭窄的 chat 行，目标是与 TUI 单栏统一形式对齐。详情面板里的双栏模式是后续的 props 改动，不是重设计。
 
-**git 式行号槽。** `FileDiff` 契约只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端契约改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR（Pull Request）保持为对既有契约的纯 Web 消费。
+**git 式行号栏。** `FileDiff` 约定只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号栏需要后端约定改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR（Pull Request）保持为对既有约定的纯 Web 消费。
 
 **复用 `CodeBlock`。** 因与 terminal 卡片相同的理由拒绝：`CodeBlock` 会折行，且没有每行 `+`/`-` 角色、没有路径头、没有页脚。两者共享几何与字体 token，那是唯一一处一个实现对两者都正确的部分。
 
 ## Consequences
 
-`DiffBlock` 只读 diff view 的字段，因此它是渲染意图所携带内容的纯函数 —— 与产出该视图的 presenter 一样回放安全。没有 diff 能力的 UI 仍得到 bridge 的通用回退；工具的 result 形状没有任何改变。无新增运行时依赖：不同于 terminal 卡片的 `anser`，diff 不需要解析器。
+`DiffBlock` 只读 diff view 的字段，因此它是渲染意图所携带内容的纯函数 —— 与产出该视图的 presenter 一样回放安全。没有 diff 能力的 UI 仍得到 bridge 的通用回退；工具结果的形状没有任何改变。无新增运行时依赖：不同于 terminal 卡片的 `anser`，diff 不需要解析器。
 
-`DiffBlock` 的多文件支路（一张卡、多个路径头）今天没有生产者：`write`/`edit` 每次调用各改一个文件，所以真实卡片显示一个文件带一个或多个 hunk。该支路为将来的多文件改动工具而构建并测试，不是为当前消费者。
+`DiffBlock` 的多文件支路（一张卡、多个路径头）今天没有生产者：`write`/`edit` 每次调用各改一个文件，所以真实卡片显示一个文件带一个或多个 hunk。该支路为将来的多文件改动工具而构建并测试，不是为当前消费方。
 
 ## Testing
 
@@ -48,10 +48,10 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX
 
 `packages/client/ui-tool/tests/diff-card.spec.tsx` 钉住每个渲染点的接线：`diffCardModel` 的派生及其每个 null 支路、result hunk 替换 call 时 diff、窗口截断的 call 仍从 result 渲染、chat 行的 diff 体、`FileMutationRow` 的常驻卡片及其路径链接经 host 以 cwd 解析打开、其在 `write` 与 `edit` 下的注册、以及面板的 Output 区。
 
-fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot snapshot（`apps/web/tests/built-boot.snapshot.ts`）是启动装配 smoke，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身契约它不带 diff 行为断言，那由接线套件负责。
+fixture（测试前置数据）（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot 快照（`apps/web/tests/built-boot.snapshot.ts`）是启动装配冒烟测试，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身约定它不带 diff 行为断言，那由接线套件负责。
 
 ## Related
 
-- [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— `terminal` 支路的同一套四层结构；本 note 复用其内联输出决策与头尾上限算术。
-- [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— 本改动消费的 `card` 标签词汇；Web 客户端现在也是 `diff` 支路的消费者。
+- [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— `terminal` 支路的同一套四层结构；本文复用其内联输出决策与头尾上限算术。
+- [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— 本改动消费的 `card` 标签词汇；Web 客户端现在也是 `diff` 支路的消费方。
 - [Web 客户端架构](../architecture/2026-07-19-gui-web-client-architecture.md) —— 两个渲染点所处的 slot 与快照分层。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
index 624da25dc2..d55bdac61c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.md
 2026-07-30-web-queue-steer-action.md: b04095b81f499982c8680a2d3627d8e98a70d8ac
-2026-07-30-web-queue-steer-action.zh.md: b04902b8a8a0d727b01aa6ba5562e12cc5d36c92
+2026-07-30-web-queue-steer-action.zh.md: 1b46ec90a27fbc3c8f3660a7cbdccb78a21a2cfa
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
index b04902b8a8..1b46ec90a2 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
@@ -1,4 +1,4 @@
-# Agent Note（agent 决策记录）：将 Web 已排队消息转为活动轮次的 steering（中途引导）
+# Agent Note: 将 Web 已排队消息转为活动轮次的 steering（中途引导）
 
 Status: implemented
 
@@ -6,21 +6,21 @@ Status: implemented
 
 ## 问题
 
-Web composer 原本会在 agent 运行期间把所有 Enter 提交作为 Queue 入队。QueueDock 已经为每条待处理消息提供可寻址的行，持久 transcript（文本记录）也已能把消费后的 steer 事件渲染为用户样式气泡，但 Web 既没有连接这两个界面的操作，也没有让用户从 composer 直接选择当前轮次 steering 的手势。
+Web composer 原本会在 agent（智能体）运行期间把所有 Enter 提交作为 Queue 入队。QueueDock 已经为每条待处理消息提供可寻址的行，持久 transcript（文本记录）也已能把消费后的 steer 事件渲染为用户样式气泡，但 Web 既没有连接这两个界面的操作，也没有让用户从 composer 直接选择当前轮次 steering 的手势。
 
 如果 Web 先在客户端删除该行，再调用 `session.prompt(mode: 'steer')`，就会把用户的一次意图拆分到两个 RPC 中。驱动器可能在两次调用之间先认领该项，steering 投递也可能在删除后失败；现有尽力而为的 `agent.steer()` 回退还可能在原单次入队项被移除后，静默追加一个新的 Queue 项。因此，立即发送操作必须区分当前轮次 steering 与 Queue 前移，并在 steering 已不可用时保留原行。
 
 ## 决策
 
-### 产品契约
+### 产品约定
 
-普通会话中每个非编辑态的 QueueDock 行都会提供名为“插话发送”的向上箭头操作。仅当会话报告 agent 正在运行时，该操作才会启用；包含混合内容的消息仍可使用，因为 steering 会转发完整且不可变的 `UserMessage`，而非该行的文本投影。已寻址 subagent 的 Queue 投影保持只读，因为其继续执行传输不提供 Queue 变更。
+普通会话中每个非编辑态的 QueueDock 行都会提供名为「插话发送」的向上箭头操作。仅当会话报告 agent 正在运行时，该操作才会启用；包含混合内容的消息仍可使用，因为 steering 会转发完整且不可变的 `UserMessage`，而非该行的文本投影。已寻址 subagent 的 Queue 投影保持只读，因为其继续执行传输不提供 Queue 变更。
 
 触发该操作会针对对应的 `InboxItemId` 请求严格的当前轮次 steering。操作成功后，权威 Host 快照会移除 Queue 行，并在 `Deep diving...` 运行状态行之后立即投影同一条待处理 steering；该气泡提供复制，但消息尚无持久事件序号，因此不提供 fork。AgentLoop 排空该项后，现有持久 `user/message` 事件会接管同一个用户样式气泡，并恢复时钟、复制和 fork，无需另建持久展示路径。
 
 running 标志位只用于提示交互状态。在同步变更边界上，AgentLoop 的 `acceptsNextStep` 值才是权威依据。如果该窗口已经关闭，操作会保持 Queue 单次入队项不变并返回类型化的 `steer-unavailable` 错误，随后原唤醒单次入队项会经 Queue 继续执行。如果驱动器已经认领该项，则返回现有的 `queue-item-not-found` 错误，且独立轮次投递已经开始。UI 会把两种竞态都视为已收敛的 Queue 投递，不显示失败通知；传输和未知错误仍会显示。
 
-Composer 对新输入采用另一套尽力而为契约。所寻址会话空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，General Settings 偏好会把普通 Enter 分配为 Queue（默认值）或 Steer，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 用于换行。已寻址 subagent 会让这两个手势都使用其仅支持 Queue 的继续执行传输。浏览器会持久化该偏好，并且它只影响支持 steering 的繁忙态手势对。如果 composer 直接发出的 Steer 错过当前 next-step 窗口，AgentLoop 会自动将其接纳为下一条唤醒 Queue 轮次，Web 不显示失败。
+Composer 对新输入采用另一套尽力而为约定。所寻址会话空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，General Settings 偏好会把普通 Enter 分配为 Queue（默认值）或 Steer，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 用于换行。已寻址 subagent 会让这两个手势都使用其仅支持 Queue 的继续执行传输。浏览器会持久化该偏好，并且它只影响支持 steering 的繁忙态手势对。如果 composer 直接发出的 Steer 错过当前 next-step 窗口，AgentLoop 会自动将其接纳为下一条唤醒 Queue 轮次，Web 不显示失败。
 
 ### Agent 与生命周期边界
 
@@ -34,15 +34,15 @@ Composer 对新输入采用另一套尽力而为契约。所寻址会话空闲
 
 `session.updateQueue` 会携带 `steer` 操作，并把两种负面结果映射为类型化 RPC 错误。这项转换是一次同步 Agent 操作；Host 绝不会通过组合移除和提示词调用来重建它。
 
-Host 仍以现有 `queuedMirror` 作为唯一的瞬态 inbox 权威。`session/queue` 快照会携带所有存活单次入队项及其 `placement: 'queued' | 'steering'`：QueueDock 只渲染 queued 行，ChatView 则在会话流末尾、`Deep diving...` 运行状态行之后渲染待处理 steering，提供复制操作，但不提供 fork、编辑或删除操作。重连会重放同一份快照，因此这项可见性既不依赖客户端乐观展示，也不需要第二个 registry。
+Host 仍以现有 `queuedMirror` 作为唯一的瞬态 inbox 权威。`session/queue` 快照会携带所有存活单次入队项及其 `placement: 'queued' | 'steering'`：QueueDock 只渲染 queued 行，ChatView 则在会话流末尾、`Deep diving...` 运行状态行之后渲染待处理 steering，提供复制操作，但不提供 fork、编辑或删除操作。重连会重放同一份快照，因此这项可见性既不依赖客户端乐观展示，也不需要第二个注册表。
 
-AgentLoop 认领待处理 steering 时，会在同步追加持久 `user/message` 之前立即发出 `agent/inbox/dequeue`。Host 会等到下一个微任务才退役该 steering 行，让持久 session 事件先进入线性 mux 流。客户端 Session 接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史回放不会消费后来复用同一 `MessageId` 的单次入队项。因此，ChatView 无需扫描持久历史就能每次只渲染一份权威，持久投影则会根据已记录的事件时间与序号恢复时钟、复制与 fork 操作。追加失败时，已认领行仍会退役。
+AgentLoop 认领待处理 steering 时，会在同步追加持久 `user/message` 之前立即发出 `agent/inbox/dequeue`。Host 会等到下一个微任务才退役该 steering 行，让持久会话事件先进入线性 mux 流。客户端 Session 接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史回放不会消费后来复用同一 `MessageId` 的单次入队项。因此，ChatView 无需扫描持久历史就能每次只渲染一份权威，持久投影则会根据已记录的事件时间与序号恢复时钟、复制与 fork 操作。追加失败时，已认领行仍会退役。
 
-现有 `session.prompt(mode: 'steer')` 对主会话新输入仍采用尽力而为的契约：在 next-step 窗口之外，它会变为唤醒 agent 的后续轮次。Composer 会让显式 `queue | steer` 模式经过 slash 裁决与引用序列化，再调用该契约。浏览器本地的提交策略拥有持久化的繁忙态 Enter 偏好，并且只为支持 steering 的会话把普通 Enter 与加速 Enter 解析为互补手势；Settings 行和 InputBar 共享该策略，不重复实现存储或投递窗口权威。只有 Queue 行操作采用严格语义，因为任一种负面结果都会经原 Queue 单次入队项收敛。
+现有 `session.prompt(mode: 'steer')` 对主会话新输入仍采用尽力而为的约定：在 next-step 窗口之外，它会变为唤醒 agent 的后续轮次。Composer 会让显式 `queue | steer` 模式经过 slash 裁决与引用序列化，再调用该约定。浏览器本地的提交策略拥有持久化的繁忙态 Enter 偏好，并且只为支持 steering 的会话把普通 Enter 与加速 Enter 解析为互补手势；Settings 行和 InputBar 共享该策略，不重复实现存储或投递窗口权威。只有 Queue 行操作采用严格语义，因为任一种负面结果都会经原 Queue 单次入队项收敛。
 
 ### 验证
 
-AgentLoop 契约覆盖保持提示词接纳窗口打开，转换一个精确的 queued 单次入队项，并证明替代它的 steering 单次入队项保留消息值和投递回执、以 `user/message` 的形式排空，且绝不启动原本的独立轮次。该覆盖还钉住窗口不可用时保留原项、拒绝已被认领的地址，以及可重入取消下的生命周期守恒。
+AgentLoop 约定覆盖保持提示词接纳窗口打开，转换一个精确的 queued 单次入队项，并证明替代它的 steering 单次入队项保留消息值和投递回执、以 `user/message` 的形式排空，且绝不启动原本的独立轮次。该覆盖还钉住窗口不可用时保留原项、拒绝已被认领的地址，以及可重入取消下的生命周期守恒。
 
 Host schema 和代理测试覆盖新操作、两种类型化错误、带 placement 的快照与重连重放，以及先持久化再退役的顺序。客户端测试覆盖两种语义竞态的静默收敛、真实错误报告、只读 subagent 行和仅支持 Queue 的 subagent 手势。运行时与 ChatView 测试覆盖按单次入队项完成的待处理到持久交接，包括重复的 `MessageId` 值；Web ARIA 快照则覆盖位于运行状态行之后且仅有复制的待处理 steering，以及带时钟、复制和 fork 的持久节点。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
index 9bde6a14c7..66e7d02fab 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-read-card.md
 2026-07-30-web-read-card.md: 26d1634b6be86666980e65f842de51c868c26efd
-2026-07-30-web-read-card.zh.md: 749177e93e8e3b2e34aed46d1fe99226395a6686
+2026-07-30-web-read-card.zh.md: f8d63cb8be8dc9e469aa6a29bdb7611634cbb861
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
index 749177e93e..f8d63cb8be 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-`read` 工具返回规范化输出对象 `{ path, offset, lines: [{ number, text }], totalLines }`，但它的展示层把这个结构压平了。`presentCall` 声明为 `GenericCallView`（`kind: 'read'`，一个跟随定位），`presentResult` 返回 `GenericResultView`，其唯一内容是剥掉 `<path>…</path><type>file</type><content>…</content>` 信封后的面向模型文本。收到该视图的 UI 只看到一个压平的文本块：行号以 `N: ` 前缀烘焙进文本、文件语言未知、`totalLines` 丢失。capable 客户端无法像渲染 diff 那样渲染一次 read——即带行号、语法高亮、行号槽与内容分离的代码视图。
+`read` 工具返回规范化输出对象 `{ path, offset, lines: [{ number, text }], totalLines }`，但它的展示层把这个结构压平了。`presentCall` 声明为 `GenericCallView`（`kind: 'read'`，一个跟随定位），`presentResult` 返回 `GenericResultView`，其唯一内容是剥掉 `<path>…</path><type>file</type><content>…</content>` 信封后的面向模型文本。收到该视图的 UI 只看到一个压平的文本块：行号以 `N: ` 前缀烘焙进文本、文件语言未知、`totalLines` 丢失。具备相应能力的客户端无法像渲染 diff 那样渲染一次 read——即带行号、语法高亮、行号槽与内容分离的代码视图。
 
 结构化数据在下游无法恢复。线上（wire）的工具结果只携带面向模型的 `ContentBlock[]`（已渲染文本）加上一个不透明的 `meta`；规范化输出对象留在工具内，从不到达客户端或会话日志。因此想要行数组、总数和语言提示的客户端无法从 `N: text` 文本里解析回它们——工具必须把它们投影到一个会持久化的通道上。
 
@@ -14,13 +14,13 @@ Status: implemented
 
 给[渲染意图 union](../architecture/2026-07-02-tool-render-intent-union.md) 新增第四个 `card` 标签 `read`——仅在结果侧。`ToolResultView` 增加 `ReadResultView { card: 'read'; title?; path; lines: ReadFileLine[]; totalLines; lang?; content? }`；`ReadFileLine { number; text }` 是共享的行单元。`ToolCallView` 不动：待定状态仍是 `GenericCallView`（`kind: 'read'`），因为一次调用在 `execute` 返回前不携带文件内容，调用时没有可展示的结构。这与 bash 终端 card 不同——终端 card 两侧都打标签，因为终端调用在调用时已携带命令和 cwd，而 read 调用既无内容也无总数，给调用侧打标签只会新增一个空变体。
 
-read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write/edit 用来投影其应用 diff hunk 的持久化通道相同（[规范化工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)）。`presentationMeta` 对一次顶层 surface 调用运行一次，返回 `{ path, offset, lines, totalLines, lang? }` 作为会话校验并存储在结果 `meta` 上的 JSON，`presentResult` 在 live 和回放路径上都把该 meta 收窄回 `ReadResultView`。`offset`（窗口请求的 1-based 起始行）一并携带，是因为当字节上限低于首个选中行时，窗口会返回空的 `lines` 数组而 `totalLines` 为正；没有持久化的 `offset`，这类窗口的回放 card 就无法报告它从哪行开始、或续读应从哪行继续，而末行推断与文本重解析两种兜底都有损。没有这个通道，行数组和总数就无法触及：原始输出对象不在线上，而重新解析 `N: text` 文本既有损又对截断脚注脆弱。
+read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write/edit 用来投影其应用 diff hunk 的持久化通道相同（[规范化工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)）。`presentationMeta` 对一次顶层 surface 调用运行一次，返回 `{ path, offset, lines, totalLines, lang? }` 作为会话校验并存储在结果 `meta` 上的 JSON，`presentResult` 在 live 和回放路径上都把该 meta 收窄回 `ReadResultView`。`offset`（窗口请求的 1-based 起始行）一并携带，是因为当字节上限低于首个选中行时，窗口会返回空的 `lines` 数组而 `totalLines` 为正；没有持久化的 `offset`，这类窗口的回放 card 就无法报告它从哪行开始、或续读应从哪行继续，而末行推断与文本重解析两种兜底都有损。没有这个通道，行数组和总数就无法触及：原始输出对象不在线上，而重新解析 `N: text` 文本既有损又对截断脚注脆弱。
 
-`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本 PR 已重录全部已发布 fixtures，且 session 格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图契约的一部分。
+`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本 PR（Pull Request）已重录全部已发布的 fixture（测试前置数据），且会话格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图约定的一部分。
 
 ### 语言提示推导
 
-`langFromPath`（在 `read-render.ts` 中）通过一张固定小表（`LANG_BY_EXTENSION`，覆盖常见源码、配置、标记扩展名）把文件扩展名映射到语法高亮语言 id。它读取最后一个路径段与最后一个点之后的扩展名，大小写不敏感，并对以下情况返回 `undefined`：dotfile（`.gitignore`）、无扩展名（`/etc/hosts`）、结尾的点、以及任何未知扩展名——此时 card 省略 `lang`，UI 渲染纯文本。该表不是可调项（tunable）：它是 UI 可忽略的展示提示，而非随部署变化的选择，未知扩展名降级为纯文本而非失败。它有意保持小规模而非穷尽的语言注册表；扩展它是一行表项新增。
+`langFromPath`（在 `read-render.ts` 中）通过一张固定小表（`LANG_BY_EXTENSION`，覆盖常见源码、配置、标记扩展名）把文件扩展名映射到语法高亮语言 id。它读取最后一个路径段与最后一个点之后的扩展名，大小写不敏感，并对以下情况返回 `undefined`：dotfile（`.gitignore`）、无扩展名（`/etc/hosts`）、结尾的点、以及任何未知扩展名——此时 card 省略 `lang`，UI 渲染纯文本。该表不是可调项（tunable）：它是 UI 可忽略的展示提示，而非随部署变化的选择，未知扩展名降级为纯文本而非失败。它有意保持小规模而非穷尽的语言注册表；扩展它只需新增一行表项。
 
 ## Alternatives considered
 
@@ -30,7 +30,7 @@ read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write
 
 **把结构化窗口放进新服务或旁路通道而非 `meta`。** 已否决：`meta` 是既有的持久化展示通道（write/edit 的应用 diff 就搭它），它随会话日志免费回放，无需新接线。服务会重新发明事件日志已提供的持久化与回放。
 
-**用 merge-extensible union 而非封闭标签。** 出于[渲染意图 union](../architecture/2026-07-02-tool-render-intent-union.md) 封闭的相同理由否决：新 card 需要消费代码来渲染它，因此被消费者静默丢弃的变体比编译错误更糟。把 `read` 加入封闭 union 是扩展它的许可方式——每个在 `card` 上 switch 的消费者都继续编译，因为新成员落入其 generic default，而想要富视图的消费者新增自己的分支。
+**用 merge-extensible union 而非封闭标签。** 出于[渲染意图 union](../architecture/2026-07-02-tool-render-intent-union.md) 封闭的相同理由否决：新 card 需要消费代码来渲染它，因此被消费方静默丢弃的变体比编译错误更糟。把 `read` 加入封闭 union 是扩展它的许可方式——每个在 `card` 上 switch 的消费方都继续编译，因为新成员落入其 generic default，而想要富视图的消费方新增自己的分支。
 
 ## Consequences
 
@@ -40,10 +40,10 @@ read 工具现在为每次顶层 read 计算 `presentationMeta`，这是对已
 
 ## Testing
 
-`packages/fs/tool-fs/tests/read-render.spec.ts` 单测 `langFromPath`（已知扩展名的大小写不敏感、扩展名在最后一段与最后一个点之后读取、以及 `undefined` 各情况：dotfile、无扩展名、结尾的点、未知）与 `readMetaFromMeta`（含与不含 `lang` 的良构收窄，以及每种拒绝：非对象、数组、缺失或类型错误的 `path`/`totalLines`/`lines`、畸形行项、非字符串 `lang`，以及——因为该函数收窄持久化的 opaque `meta` 边界——良构类型的回放 JSON 仍可能携带的语义无效路径：不是 1-based 整数的 `offset`、小于 `offset` 的首行 `number`、不是 1-based 整数的行 `number`（`0`、`1.5`、`NaN`、`Infinity`）、不是非负整数的 `totalLines`（`-1`、`1.5`、`NaN`）、以及行号重复、递减或超过 `totalLines` 的情况；并且收窄正 `offset` 处的空窗口（字节上限低于首个选中行））。`packages/fs/tool-fs/tests/tools.spec.ts` 固定工具接线：`execute` 把结构化窗口（含与不含 `lang` 提示）作为 `meta` 附上、`presentResult` 把它收窄为携带剥信封 `content` 的 `card: 'read'` 视图、以及各拒绝路径（错误结果、非单文本内容、meta 有效但信封畸形、信封有效但 meta 缺失或畸形）都回退到 `undefined`。两个改动的源文件保持逐文件 100% 覆盖率。本 PR 携带的是持久化 meta 与扩展后联合类型的快照证据，而非新渲染视图的证据：重录的 ACP session fixtures（`fs-read`、`fs-read-window`、`fs-edit`、`fs-policy-reject`、`fs-write-overwrite`、`parallel-tool-calls`、`workspace-context`、`workspace-edit`）钉住持久化的读取 `meta`（含 `{{cwd}}` 令牌化路径），`cordis-inspect-jsdoc` 钉住四成员的 `ToolResultView` 联合类型。当时的终端快照还钉住了消费方的 generic dim-Markdown 回退保持逐字节一致；结构化卡片自身的组装应用 transcript 则属于消费它的前端变更。
+`packages/fs/tool-fs/tests/read-render.spec.ts` 单测 `langFromPath`（已知扩展名（不区分大小写）、扩展名在最后一段与最后一个点之后读取、以及 `undefined` 各情况：dotfile、无扩展名、结尾的点、未知）与 `readMetaFromMeta`（含与不含 `lang` 的良构收窄，以及每种拒绝：非对象、数组、缺失或类型错误的 `path`/`totalLines`/`lines`、畸形行项、非字符串 `lang`，以及——因为该函数收窄持久化的不透明 `meta` 边界——类型正确的回放 JSON 仍可能携带的语义无效情况：不是 1-based 整数的 `offset`、小于 `offset` 的首行 `number`、不是 1-based 整数的行 `number`（`0`、`1.5`、`NaN`、`Infinity`）、不是非负整数的 `totalLines`（`-1`、`1.5`、`NaN`）、以及行号重复、递减或超过 `totalLines` 的情况；并且收窄正 `offset` 处的空窗口（字节上限低于首个选中行））。`packages/fs/tool-fs/tests/tools.spec.ts` 固定工具接线：`execute` 把结构化窗口（含与不含 `lang` 提示）作为 `meta` 附上、`presentResult` 把它收窄为携带剥信封 `content` 的 `card: 'read'` 视图、以及各拒绝路径（错误结果、非单文本内容、meta 有效但信封畸形、信封有效但 meta 缺失或畸形）都回退到 `undefined`。两个改动的源文件保持逐文件 100% 覆盖率。本 PR 携带的是持久化 meta 与扩展后联合类型的快照证据，而非新渲染视图的证据：重录的 ACP（Agent Client Protocol）会话 fixture（`fs-read`、`fs-read-window`、`fs-edit`、`fs-policy-reject`、`fs-write-overwrite`、`parallel-tool-calls`、`workspace-context`、`workspace-edit`）钉住持久化的读取 `meta`（含 `{{cwd}}` 令牌化路径），`cordis-inspect-jsdoc` 钉住四成员的 `ToolResultView` 联合类型。当时的终端快照还钉住了消费方的 generic dim-Markdown 回退保持逐字节一致；结构化卡片自身的组装应用 transcript（文本记录） 则属于消费它的前端变更。
 
 ## Related
 
-- [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 Note 以 `read` 结果分支扩展的 `card` 标签词汇。
-- [Canonical tool output contract](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 拥有本 Note 用来投影 read 窗口的 `presentationMeta` 持久化通道。
-- [Web terminal card](2026-07-28-web-terminal-card.md) —— 客户端消费结构化 card 的先例；read card 遵循相同的生产者模式，仅结果侧。
+- [工具调用展示的带标签渲染意图 union](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 Note 以 `read` 结果分支扩展的 `card` 标签词汇。
+- [规范化工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 拥有本 Note 用来投影 read 窗口的 `presentationMeta` 持久化通道。
+- [Web 终端 card](2026-07-28-web-terminal-card.md) —— 客户端消费结构化 card 的先例；read card 遵循相同的生产者模式，仅结果侧。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index 6f3a5d895b..04c1201f16 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
 2026-07-30-web-result-card-frontend.md: c7e63220d824cf0bd3ac3536c528707d0db379bc
-2026-07-30-web-result-card-frontend.zh.md: 4cec11371e8d0848f2f03ded0b093d80cc25a7a5
+2026-07-30-web-result-card-frontend.zh.md: 6bb31797a7658adae267d034d0a6d9fa49dfe09f
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index 4cec11371e..6bb31797a7 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Web result 卡片前端 —— 在浏览器渲染 web 渲染意图
+# Agent Note: Web result 卡片前端——在浏览器渲染 web 渲染意图
 
 Status: implemented
 
@@ -6,31 +6,31 @@ Status: implemented
 
 ## Problem
 
-`web_search` 和 `web_fetch` 工具声明了 `card: 'web'` result view（[web result card](2026-07-30-web-result-card.md)）：一个 `kind` 标签联合,携带结构化的被引用 sources 加可选的 provider answer（`kind: 'search'`),或抓取的 URL 及其 HTTP 状态（`kind: 'fetch'`）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `resultView` 投递到 `ConversationSnapshot` —— 但 Web 客户端忽略了它:一次已完成的 web 调用只渲染为摊平的模型可见文本,正是契约笔记所解释的、结构化视图要替代的那种有损渲染。`web_search` 到达读者时是每个 source 一行自由文本 markdown,而非可点击 source 的引用列表;`web_fetch` 是它的 markdown 正文,没有检索摘要。
+`web_search` 和 `web_fetch` 工具声明了 `card: 'web'` result view（[web result card](2026-07-30-web-result-card.md)）：一个以 `kind` 为标签的联合类型,携带结构化的被引用 sources 加可选的 provider answer（`kind: 'search'`),或抓取的 URL 及其 HTTP 状态（`kind: 'fetch'`）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `resultView` 投递到 `ConversationSnapshot` —— 但 Web 客户端忽略了它:一次已完成的 web 调用只渲染为摊平的模型可见文本,正是约定笔记所解释的、结构化视图要替代的那种有损渲染。`web_search` 到达读者时是每个 source 一行自由文本 markdown,而非可点击 source 的引用列表;`web_fetch` 是它的 markdown 正文,没有检索摘要。
 
 ## Decision
 
-`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/tool/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
+`WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/tool/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它会在以下情况下返回 null，从而走通用路径：调用仍在运行（web 卡片是 result-only 的，因为工具保留 generic pending 视图）；调用已结算，但其 result view 不是 web 卡片，包括本客户端版本不认识的 `card` 值（它经 wire 抵达，因而不能被信任为已编译的变体）；result view 是 generic result view（web 工具的错误路径返回 generic 卡片，其文本由通用路径保留）；web 卡片的 `kind` 是本客户端版本不认识的值（更新的 host 经 wire 发来的值，读作 fetch 会画出空 URL 和 `HTTP undefined`）。
 
-一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是契约把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
+一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是约定把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
 
-**链接的安全性沿用 MarkdownText 对不受信任的 assistant 链接所用 allowlist 的 http(s) 子集。** MarkdownText 还允许 `mailto:`，此处刻意排除，因为检索 URL 绝不会是邮件地址。一个 source 或 fetch URL 仅当其协议为 `http:` 或 `https:` 时才成为可导航锚点，带 `target="_blank"` 和 `rel="noopener noreferrer"`；`javascript:`/`data:`/`file:`/`mailto:` URL 或无法解析的字符串渲染为纯文本、无 href。web 工具返回的 result content 是模型创作的,未经验证抵达本组件,因此像 assistant markdown 一样被当作不受信任处理。标签从标题回退到主机名再回退到原始 URL,因此即便标题缺失且 URL 无法解析,source 也总能读作某个东西。
+**链接的安全性沿用 MarkdownText 对不受信任的 assistant 链接所用 allowlist 的 http(s) 子集**。MarkdownText 还允许 `mailto:`，此处刻意排除，因为检索 URL 绝不会是邮件地址。一个 source 或 fetch URL 仅当其协议为 `http:` 或 `https:` 时才成为可导航锚点，带 `target="_blank"` 和 `rel="noopener noreferrer"`；`javascript:`/`data:`/`file:`/`mailto:` URL 或无法解析的字符串渲染为纯文本、无 href。web 工具返回的 result content 是模型创作的,未经验证抵达本组件,因此像 assistant markdown 一样被当作不受信任处理。标签从标题回退到主机名再回退到原始 URL,因此即便标题缺失且 URL 无法解析,source 也总能读作某个东西。
 
-**几何镜像 CodeBlock/TerminalBlock**（12px 圆角、code-block 表面、16px 垂直外边距）,使 web 卡片与它们读作一家。整份 source 列表渲染在单个 `<ol>` 里,由 `max-height: 320px` 与 `overflow-y: auto` 约束,因此高于该值的列表在原地纵向滚动,而不是把卡片撑高（[来源滚动](2026-08-03-web-search-source-scroll.md)）。source 列表是散文而非按列对齐的输出,所以它正常换行,而不像终端卡片的输出那样横向滚动 —— 这是与 TerminalBlock 唯一刻意的分歧。
+**几何镜像 CodeBlock/TerminalBlock**（12px 圆角、code-block 表面、16px 垂直外边距）,使 web 卡片看起来与它们属于同一类。整份 source 列表渲染在单个 `<ol>` 里,由 `max-height: 320px` 与 `overflow-y: auto` 约束,因此高于该值的列表在原地纵向滚动,而不是把卡片撑高（[来源滚动](2026-08-03-web-search-source-scroll.md)）。source 列表是散文而非按列对齐的输出,所以它正常换行,而不像终端卡片的输出那样横向滚动 —— 这是与 TerminalBlock 唯一刻意的分歧。
 
 卡片在 chat 行中**常驻**于摘要行之下,与 `BashRow` 所用的同一常驻姿态。两个渲染点展示同一份完整的 source 列表,仅由卡片自身的滚动高度约束,而没有行与面板两级的 source 上限。键控行把一个 `WebRow` 组件注册在 `web_search` 与 `web_fetch` 两个键下;行仅根据工具名判别以选取其图标（search 对 browse）与标题（`Search`/`Fetch`）。没有自己键控行的 web 声明工具落到 `GenericToolCard`,它长出同一张常驻卡片。详情面板渲染该卡片,并在其下方渲染摊平的模型可见结果内容:`web_fetch` 卡片只携带 URL 与状态,因此其抓取正文只在此处可读。
 
 ## Consequences
 
-`WebBlock` 只读 web view 的字段,因此它是渲染意图所携带内容的纯函数 —— 无会话查找,与产出该视图的 presenter 一样回放安全,且不同于终端卡片它不需要 cwd 解析,因为 web view 不携带路径。没有 `web` 能力的 UI（TUI）仍得到契约的回退 `content`;工具的 result 形状没有任何改变。answer 复用 `MarkdownText`,因此 answer 自身的不受信任链接处理与 GFM 渲染免费获得。
+`WebBlock` 只读 web view 的字段,因此它是渲染意图所携带内容的纯函数 —— 无会话查找,与产出该视图的 presenter 一样回放安全,且不同于终端卡片它不需要 cwd 解析,因为 web view 不携带路径。没有 `web` 能力的 UI（TUI）仍得到约定的回退 `content`;工具的 result 形状没有任何改变。answer 复用 `MarkdownText`,因此 answer 自身的不受信任链接处理与 GFM 渲染免费获得。
 
 一条独立的后续 PR 会统一整行折叠/展开交互,并把每张常驻卡片（terminal、diff、web）一次性翻成 expand-gated;本卡片遵循当前的常驻约定,而非抢先做那次改动。
 
 ## Alternatives considered
 
-**两个组件,每种 kind 一个。** 拒绝:两种形状共享卡片外框、安全链接处理、截断提示,而契约已经把它们的差异表达为一个 `card` 标签下的 `kind` 判别;两个组件会重复共享表面并拆分安全链接逻辑。
+**两个组件,每种 kind 一个。** 拒绝:两种形状共享卡片外框、安全链接处理、截断提示,而约定已经把它们的差异表达为一个 `card` 标签下的 `kind` 判别;两个组件会重复共享表面并拆分安全链接逻辑。
 
-**重解析模型可见的渲染文本,而非消费结构化视图。** 因契约笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
+**重解析模型可见的渲染文本,而非消费结构化视图。** 因约定笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
 
 **不加协议 allowlist 直接渲染裸锚点。** 拒绝:URL 在此接缝处是模型创作、未经验证的,所以未过滤的 href 会让 `javascript:` URL 在点击时执行。该 allowlist 是 MarkdownText allowlist（它还允许 `mailto:`）的 http(s) 子集,因此不受信任的检索链接无论在何处渲染都行为相同。
 
@@ -40,11 +40,11 @@ Status: implemented
 
 `packages/client/ui-tool/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-tool/src/*`）,因此覆盖率运行不度量它。
 
-fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配契约的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
+fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配约定的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:当前计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
 
 ## Related
 
-- [Web result card](2026-07-30-web-result-card.md) —— 添加 `card: 'web'` result 支路并让两个工具发出它的后端 PR;本条是它推迟的前端消费者。
+- [Web result card](2026-07-30-web-result-card.md) —— 添加 `card: 'web'` result 支路并让两个工具发出它的后端 PR;本条是它推迟的前端消费方。
 - [Web search 来源卡片改为滚动而非折叠](2026-08-03-web-search-source-scroll.md) —— 用定高滚动容器替换本笔记的 source 列表头/尾折叠,并移除 `CHAT_WEB_MAX_SOURCES` 与原语自身的 source 上限;本笔记的其余决策依然成立。
 - [Web terminal card](2026-07-28-web-terminal-card.md) —— 本条所镜像的先例:一个 `ui-primitives` block、一处 card-model 派生、键控与兜底 chat 行、以及一个详情面板支路,用于 `terminal` 渲染意图。
-- [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— `card` 标签词汇;Web 客户端现在是 `web` 支路的完整消费者。
+- [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— `card` 标签词汇;Web 客户端现在是 `web` 支路的完整消费方。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
index 0badfa2a55..9fb81dc9c3 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-result-card.md
 2026-07-30-web-result-card.md: 838b13a7f3240c753e5cd1af6909389055c6352d
-2026-07-30-web-result-card.zh.md: 6e5170fcad82d709b050fb05e8efcfe955f20391
+2026-07-30-web-result-card.zh.md: 9b0ad72aa6f152c8f7f4594dbe80532bf9722016
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
index 6e5170fcad..9b0ad72aa6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: Web result card — a structured render intent for web_search and web_fetch
+# Agent Note: Web 结果卡片——用于 web_search 和 web_fetch 的结构化渲染意图
 
 Status: implemented
 
@@ -6,15 +6,15 @@ Status: implemented
 
 ## Problem
 
-`web_search` 与 `web_fetch` 工具各自声明了一个 generic 待定卡片（`presentCall`，`kind: 'search'`/`'fetch'`），但没有 `presentResult`，因此一个已完成的 web 调用抵达 UI 时只剩下面向模型的 render 文本。对于想渲染引用列表或抓取摘要的 web 前端而言，该文本是有损的：`web_search` 的 render 把每个来源的 `title`、`snippet`、`publishedAt` 压进一行以 title 或 hostname 标注的自由文本 markdown（`packages/web/tool-web/src/search.ts` 中的 `formatSearchOutput`），因此重新解析 render 无法恢复各来源字段；`web_fetch` 的 render 也仅在一行 header 里携带 `url` 与 `statusCode`。渲染意图契约（[标签联合类型](../architecture/2026-07-02-tool-render-intent-union.md)）此前没有一个可供 web 工具声明、用以携带结构化结果的分支。
+`web_search` 与 `web_fetch` 工具各自声明了一个 generic 等待中卡片（`presentCall`，`kind: 'search'`/`'fetch'`），但没有 `presentResult`，因此一个已完成的 web 调用抵达 UI 时只剩下面向模型的 render 文本。对于想渲染引用列表或抓取摘要的 web 前端而言，该文本是有损的：`web_search` 的 render 把每个来源的 `title`、`snippet`、`publishedAt` 压进一行以 title 或 hostname 标注的自由文本 markdown（`packages/web/tool-web/src/search.ts` 中的 `formatSearchOutput`），因此重新解析 render 无法恢复各来源字段；`web_fetch` 的 render 也仅在一行 header 里携带 `url` 与 `statusCode`。渲染意图约定（[标签联合类型](../architecture/2026-07-02-tool-render-intent-union.md)）此前没有一个可供 web 工具声明、用以携带结构化结果的分支。
 
 ## Decision
 
 向 `ToolResultView`（`packages/core/tools/src/presentation.ts`）新增一个 `card: 'web'` 结果分支，它是以 `kind: 'search' | 'fetch'` 字段作判别的联合 `WebResultView = WebSearchResultView | WebFetchResultView`，并附一个表示单个可引用来源的 `WebSource` 形状。两个工具现在都声明 `presentResult`。
 
-采用一个标签加 `kind` 判别，而非两个标签。两个调用都是 web 检索，web 前端会用同一族组件渲染它们（一个检索卡片，正文按 kind 不同），因此共用一个 `card` 让每个 card 消费者的 switch 只需新增一个分支，并让前端在其内部按 `kind` 分岔。两个标签会迫使当前及未来每个消费者为本属同一视觉族的东西添加两个分支。这两个 `kind` 取值与两个工具既有的 generic 调用视图 `kind` 一致，因此一个调用与它的结果读起来是同一类别。
+采用一个标签加 `kind` 判别，而非两个标签。两个调用都是 web 检索，web 前端会用同一族组件渲染它们（一个检索卡片，正文按 kind 不同），因此共用一个 `card` 让每个 card 消费方的 switch 只需新增一个分支，并让前端在其内部按 `kind` 分岔。两个标签会迫使当前及未来每个消费方为本属同一视觉族的东西添加两个分支。这两个 `kind` 取值与两个工具既有的 generic 调用视图 `kind` 一致，因此一个调用与它的结果读起来是同一类别。
 
-`presentationMeta` 携带 render 文本无法携带的东西。工具从 `execute` 返回的结构化结果对象**不会**经由 wire 抵达客户端——只有面向模型的 `render` 文本，以及（声明时）投影到 `tool/result` 事件 `meta` 上的 `output.presentationMeta` JSON 会。对 `web_search`，meta 是得到 `{url, title?, snippet?, publishedAt?}` 的**唯一**忠实途径：render 把这些字段压进一行有损的自由文本，消费者无法重新解析。对 `web_fetch`，meta 是更小但真实的收益：`url`/`statusCode` 可从确定格式的 `Fetched <url> (HTTP <n>)` header 行还原，但 `truncated` 是有效截断——provider cap、转换前源截断，或部署的 `fetchMaxOutputChars` 输出上限——客户端无法重算，因为它不知道那个上限。抓取卡片与面向模型的文本都从同一个 `renderFetchOutput(result, maxOutputChars)` helper 派生 `truncated`，因此卡片绝不会与模型看到的脚注分叉。这照搬 write/edit 的 diff 模板（`packages/fs/tool-fs/src/diff.ts`）：一个 `*MetaFromValue` 投影器喂给 `output.presentationMeta`，一个 `*MetaFromResult` 收窄器读回 `result.meta`，并在失败时防御性回退到 generic 卡片。`web_fetch` 的正文已是结果内容中的 markdown，因此不重复写入 meta。
+`presentationMeta` 携带 render 文本无法携带的东西。工具从 `execute` 返回的结构化结果对象**不会**经由 wire 抵达客户端——只有面向模型的 `render` 文本，以及（声明时）投影到 `tool/result` 事件 `meta` 上的 `output.presentationMeta` JSON 会抵达客户端。对 `web_search`，meta 是得到 `{url, title?, snippet?, publishedAt?}` 的**唯一**忠实途径：render 把这些字段压进一行有损的自由文本，消费方无法重新解析。对 `web_fetch`，meta 是更小但真实的收益：`url`/`statusCode` 可从确定格式的 `Fetched <url> (HTTP <n>)` header 行还原，但 `truncated` 是有效截断——提供方上限、转换前源截断，或部署的 `fetchMaxOutputChars` 输出上限——客户端无法重算，因为它不知道那个上限。抓取卡片与面向模型的文本都从同一个 `renderFetchOutput(result, maxOutputChars)` helper 派生 `truncated`，因此卡片绝不会与模型看到的脚注不一致。这照搬 write/edit 的 diff 模板（`packages/fs/tool-fs/src/diff.ts`）：一个 `*MetaFromValue` 投影器喂给 `output.presentationMeta`，一个 `*MetaFromResult` 收窄器读回 `result.meta`，并在失败时防御性回退到 generic 卡片。`web_fetch` 的正文已是结果内容中的 markdown，因此不重复写入 meta。
 
 两个结果视图都不携带 `content` 副本。不渲染结构化 `web` 卡片的 UI 回退到原始 `tool/result` 内容，这也是 generic 卡片消费的输入。把结果内容复制进视图会在同一投递帧上重复最多 `fetchMaxOutputChars` 个字符却毫无收益（与 meta 一节对抓取正文的否决同理），因此视图省略它，回退路径渲染完全相同的文本。每个视图从调用参数设置其结果期 `title`（`args.query`／`args.url`），因此丢掉了调用头的窗口截断重放仍有标题，与 write/edit 在结果期重设 title 的做法一致。
 
@@ -22,13 +22,13 @@ Status: implemented
 
 ## Consequences
 
-前端消费方由后续独立 PR 交付：本次生产者变更新增契约分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript 快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
+前端消费方由后续独立 PR 交付：本次生产者变更新增约定分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript（文本记录）快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
 
 未来想用此卡片的 web 工具，声明一个返回带自有 `kind` 的 `card: 'web'` 视图的 `presentResult`；新增第三个 `kind` 是一次联合类型编辑加前端的分岔，而非一个新的 card 标签。
 
 ## Alternatives considered
 
-**两个 card 标签（`web-search`、`web-fetch`）。** 否决：它在每个 card 消费者处为一个视觉族翻倍分支数，而两个形状已共享得够多（一个带回退内容的带标题检索卡片），`kind` 判别无需第二个标签即可表达差异。
+**两个 card 标签（`web-search`、`web-fetch`）。** 否决：它在每个 card 消费方处为一个视觉族翻倍分支数，而两个形状已共享得够多（一个带回退内容的带标题检索卡片），`kind` 判别无需第二个标签即可表达差异。
 
 **在 `presentResult` 里重新解析 render 文本，而非投影 meta。** 对 `web_search` 否决：render 的来源列表是有损的（title 或 hostname 标签，snippet 与日期拼进自由文本），因此重新解析无法忠实恢复结构化字段。`presentationMeta` 是唯一保留它们的途径。
 
@@ -36,9 +36,9 @@ Status: implemented
 
 ## Testing
 
-`packages/web/tool-web/tests/tool-web.spec.ts` 覆盖以下内容，满足按文件 100% 的门禁：`searchMetaFromValue`/`fetchMetaFromValue` 投影，含对缺席可选字段的省略，以及抓取 `truncated` 投影在仅输出上限截断正文时、以及在毫无截断时都与 render 脚注一致；`searchMetaFromResult`/`fetchMetaFromResult` 收窄，含一次往返与每种畸形形状的拒绝（非对象、字段类型错误、畸形来源条目）以及空来源列表的接受；`presentSearchResult`/`presentFetchResult` 类型化视图，含从参数派生的 title、无 `content` 副本、truncated 信号、错误结果回退与畸形 meta 回退；以及两次真实注册表执行，断言工具把 meta 投影到 `result.meta` 上，其注册的 `presentResult` 推导出 `card: 'web'` 视图。
+`packages/web/tool-web/tests/tool-web.spec.ts` 覆盖以下内容，满足按文件 100% 的门禁：`searchMetaFromValue`/`fetchMetaFromValue` 投影，含省略不存在的可选字段，以及抓取 `truncated` 投影在仅输出上限截断正文时以及在毫无截断时都与 render 脚注一致；`searchMetaFromResult`/`fetchMetaFromResult` 收窄，含一次往返与每种畸形形状的拒绝（非对象、字段类型错误、畸形来源条目）以及空来源列表的接受；`presentSearchResult`/`presentFetchResult` 类型化视图，含从参数派生的 title、无 `content` 副本、truncated 信号、错误结果回退与畸形 meta 回退；以及两次真实注册表执行，断言工具把 meta 投影到 `result.meta` 上，其注册的 `presentResult` 推导出 `card: 'web'` 视图。
 
 ## Related
 
 - [标签化的工具调用渲染意图联合类型](../architecture/2026-07-02-tool-render-intent-union.md) —— 本卡片以 `web` 分支扩展的 `card` 标签词汇表。
-- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；本分支的 web 前端消费者是它的对应物，推迟到后续 PR。
+- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；本分支的 web 前端消费方是它的对应实现，推迟到后续 PR。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
index 255dd08832..b0f3852fa8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
 2026-07-30-web-tool-row-unified-expand-and-inspect.md: 4fcf1e9a567b73cd04f1bbed170c391aaedd9e73
-2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: 92d70f5aa6bd09e6f9e54015dafc38d8d3690a9e
+2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: 765cd058c99e53e5dea81f83c203a6d75d56f104
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
index 92d70f5aa6..765cd058c9 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
@@ -1,29 +1,29 @@
-# Agent Note：Web 工具行统一展开交互与 trajectory Inspect
+# Agent Note: Web 工具行统一展开交互与 trajectory Inspect
 
-状态：已实现
+Status: implemented
 
 [English](2026-07-30-web-tool-row-unified-expand-and-inspect.md) | 中文
 
 ## 问题
 
-聊天视图的工具行交互已经分裂成多种方言：ToolRow 通过前导图标切换展开、且仅限有 args body 的调用，bash 示例有自己的一套展开方式，todo / ask-question 行只能展开原始 args，单文件工具完全不可展开，而调用的 OUTPUT 只能通过右侧详情面板查看。失败的 bash 命令（exit≠0 但结算为 `isError:false`）在折叠行上没有任何失败信号。此外聊天行没有跳转到 trajectory 记录的入口，且 chat → trajectory → chat 切换会丢失阅读位置（标签环会卸载非活跃视图）。
+聊天视图的工具行交互已经分裂成多种方言：ToolRow 通过前导图标切换展开、且仅限有 args body 的调用，bash 示例有自己的一套展开方式，todo / ask-question 行只能展开原始 args，单文件工具完全不可展开，而调用的 OUTPUT 只能通过详情面板查看。失败的 bash 命令（exit≠0 但结算为 `isError:false`）在折叠行上没有任何失败信号。此外聊天行没有跳转到 trajectory 记录的入口，且 chat → trajectory → chat 切换会丢失阅读位置（标签环会卸载非活跃视图）。
 
 ## 决定
 
 **所有可展开工具行共享同一交互——整行即开关（点击 / Enter / 空格），图标 hover 时渐变为 chevron 预览——以及同一展开体：带 IN/OUT 侧栏标签的卡片，各分区独立滚动上限；hover 显示的 Inspect 胶囊通过 store 的一次性交接跳到该调用的 trajectory 记录；聊天视图用内存态的按会话 Map 在视图切换间保留语义阅读位置。**
 
-- `toolRowModel` 在 args 之外同时派生结果材料：`output`（`resultText` 拍平逻辑从 DetailsPanel 移入 contract）和 `errorSummary`（失败首行，以错误色作为折叠摘要）。有 body、output 或 terminal 材料的行即可展开；行本身是开关（`role="button"`、`aria-expanded`），文件路径摘要通过 `stopPropagation` 保持独立链接。
+- `toolRowModel` 在 args 之外同时派生结果材料：`output`（`resultText` 拍平逻辑从 DetailsPanel 移入 contract）和 `errorSummary`（失败首行，作为折叠摘要并以错误色显示）。有 body、output 或 terminal 材料的行即可展开；行本身是开关（`role="button"`、`aria-expanded`），文件路径摘要通过 `stopPropagation` 保持独立链接。
 - 展开卡片（figma 1249:35657）是 IN/OUT 分区列：每个分区是独立滚动区（max-height 150px），侧栏标签 sticky 固定，l2 分割线横贯整卡宽度。Think 的推理文本和 run_code 的 CodeBlock 保持非卡片体；上下文注入复用此行并以无标签的 `plainBody` 卡片展开。
 - `terminalFailed` 读取已结算 terminal 卡片的退出状态，让 BashRow 和 GenericToolCard 把失败命令显示为行的红色状态点——这是折叠行唯一的失败信号，因为调用本身结算为 `isError:false`。
 - TerminalBlock 的横幅并入同一阅读模型：与卡片共用同一表面（不再用 banner token），与正文之间是 l2 细线，命令列上限 150px 内部滚动，复制/状态控件 sticky 且顶对齐第一行提示符。
-- Inspect：`ToolCallOwnerProps.inspect`（无调用身份的行不提供）在展开体左下角以真实布局位置渲染胶囊，hover 整个 tool call 任意位置显示。点击将 `{ callId }` 写入 chat store 的一次性 `inspect` 字段并切换到 trajectory 视图；TrajectoryTable 找到记录、打开其摘要，并通过清空字段确认。
-- 滚动保留：每次非贴底滚动时，聊天视图把 `{ anchorKey, anchorTop, scrollTop }` 保存到 apply 作用域的按会话 Map，并经注入 props 的 `chatScroll` 暴露；重挂载时先用 `scrollTop` 到达近似窗口，再按稳定 node／call 锚点的矩形差值校正，因此宽度重排后仍把同一阅读行保持在原位。包括「回到底部」在内的每条贴底路径都会在切换 tab 或会话前同步清除该项。Map 仍刻意不持久化——新页面加载保持打开即贴底的默认行为。
+- Inspect：`ToolCallOwnerProps.inspect`（无调用身份的行不提供）在展开体左下角的正常布局流中渲染胶囊，hover 到工具调用的任意位置时显示。点击将 `{ callId }` 写入 chat store 的一次性 `inspect` 字段并切换到 trajectory 视图；TrajectoryTable 找到记录、打开其摘要，并通过清空字段确认。
+- 滚动保留：每次非贴底滚动时，聊天视图把 `{ anchorKey, anchorTop, scrollTop }` 保存到 apply 作用域的按会话 Map，并以 `chatScroll` 暴露；重挂载时先用 `scrollTop` 到达近似窗口，再按稳定 node／call 锚点的矩形差值校正，因此宽度重排后仍把同一阅读行保持在原位。包括「回到底部」在内的每条贴底路径都会在切换 tab 或会话前同步清除该项。Map 仍刻意不持久化——新页面加载保持打开即贴底的默认行为。
 
 ## 曾考虑的替代方案
 
-**保留前导图标开关和各注册方自有的展开方式。** 否决：三个表面已经分化；注册方姿态（bash 示例本地复刻 CSS）意味着除非交互契约本身统一且足够小——整行开关加 hover 预览——否则漂移会永久存在。
+**保留前导图标开关和各注册方自有的展开方式。** 否决：三个表面已经分化；注册方姿态（bash 示例本地复刻 CSS）意味着除非交互约定本身统一且足够小——整行开关加 hover 预览——否则漂移会永久存在。
 
-**通过 URL 或 trajectory 视图 prop 传递 Inspect。** 否决：视图环经由 slot 注册表渲染，两个视图没有可携带 prop 的共同父级；chat store 本就跨越该边界，一次性字段让交接可安全重放（字段出现之前的持久化快照以 `?? null` 复水）。
+**通过 URL 或 trajectory 视图 prop 传递 Inspect。** 否决：视图环经由 slot 注册表渲染，两个视图没有可携带 prop 的共同父级；chat store 本就跨越该边界，一次性字段让交接具备回放安全性（字段出现之前的持久化快照以 `?? null` 复水）。
 
 **持久化聊天滚动偏移。** 否决：把几天前的偏移恢复到已经增长的会话里读起来像 bug；内存 Map 把记忆精确限定在会丢位置的视图切换场景。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.i18n.yaml
index d1fb6cb6c7..89af3af66d 100644
--- a/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.md
 2026-07-31-browser-derived-initial-locale.md: 0c49a6bbfec0ab33a5aa3ce53dde0cac747f3816
-2026-07-31-browser-derived-initial-locale.zh.md: c013d24dcd3bb49d176eaddd42ff41dde320ff1f
+2026-07-31-browser-derived-initial-locale.zh.md: ca8eeceae58e25836bb42f7c1cec0e61a232d921
diff --git a/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.zh.md b/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.zh.md
index c013d24dcd..ca8eeceae5 100644
--- a/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-browser-derived-initial-locale.zh.md
@@ -16,21 +16,21 @@ Status: implemented
 
 **判定浏览器用的是 `window` 而非 `navigator`。** Node ≥ 21 暴露全局 `navigator` 并报告机器自身语言（CI runner 上是 `en-US`），因此以 `navigator` 把关会让 node 启动客户端树时解析成 `en`，而非文档约定的回落值。以 `window` 把关可使所有非浏览器运行都停留在 `FALLBACK_LOCALE`。
 
-**显式选择是永久的。** `setLocale` 的持久化未作改动，且持久化值最先被查询，因此选过语言的用户即便在不同浏览器配置或系统语言之间辗转也保留原选择。没有任何代码把探测到的 locale 写回存储：探测在每次启动时重新推导，对"用户是否做过选择"这一问题始终不可见。
+**显式选择是永久的。** `setLocale` 的持久化未作改动，且持久化值最先被查询，因此选过语言的用户即便在不同浏览器配置文件或系统语言之间辗转也保留原选择。没有任何代码把探测到的 locale 写回存储：探测在每次启动时重新推导，对「用户是否做过选择」这一问题始终不可见。
 
 **浏览器 e2e 车道现在钉住浏览器语言，而不只是存储项。** 断言中文文案的场景（`access-confirmation`、`models-settings`、`onboarding-deepseek-config`、`settings-chrome`）以 `apps/web/tests/support.ts` 的 `locale: ZH_BROWSER_LOCALE` 打开页面；`newEnglishPage` 仍然钉 `dsh.locale=en`，它依旧压过任何浏览器语言。`settings-chrome.e2e.ts` 新增一个场景：另开一个存储项为空的 `en-US` 页面，断言设置界面以英文呈现——这是本功能在组装后应用中的证据。
 
 ## Alternatives considered
 
 - **`Intl.DateTimeFormat().resolvedOptions().locale` 或单读 `navigator.language`**：两者都把用户的有序偏好列表塌缩成一个标签，于是 `['de', 'en', 'zh']` 的读者拿到的是 zh 而非 en。列表恰恰是浏览器这份声明里最值得读的部分。
-- **首次启动即持久化探测结果**：那会把探测变成一次性事件，让一次陈旧的首访凌驾于此后改变的浏览器语言之上，也摧毁了整个解析顺序所依赖的区分——存储值将不再意味着"用户选了它"。
+- **首次启动即持久化探测结果**：那会把探测变成一次性事件，让一次陈旧的首访凌驾于此后改变的浏览器语言之上，也摧毁了整个解析顺序所依赖的区分——存储值将不再意味着「用户选了它」。
 - **完整的 BCP 47 协商（`Intl.LocaleMatcher` 式查找、地区与文字权重）**：在只提供两个语言互异的 locale 时，主子标签匹配就是正确答案的全部；协商层只会带来无行为支撑、也无从测试的表面积。
-- **为默认 locale 增加一个 cordis config key**：此处部署之间并无差异——回落值是产品对"完全没有信号"给出的答案，不是旋钮。仓库策略把 `Config` 字段留给有当前消费者、且随部署变化的选择。
+- **为默认 locale 增加一个 Cordis 配置键**：此处部署之间并无差异——回落值是产品对「完全没有信号」给出的答案，不是旋钮。仓库策略把 `Config` 字段留给有当前消费方、且随部署变化的选择。
 - **让 e2e 车道的中文场景继续钉存储项（`dsh.locale=zh`）**：那会让套件保持绿色，却抹掉浏览器推导路径在组装后应用中唯一的运行处；改钉浏览器语言才能端到端地演练新的解析过程。
 
 ## Consequences
 
 - 来自英文浏览器的首访落在英文界面，而语言行依然呈现同样两个以自身语言自述的选项，两个方向的脱身通道都未改变。
-- `FALLBACK_LOCALE` 收窄回它真正的职责——字典回落与无信号时的答案——不再兼职充当"用户尚未选择"。
+- `FALLBACK_LOCALE` 收窄回它真正的职责——字典回落与无信号时的答案——不再兼职充当「用户尚未选择」。
 - 在 jsdom 下构造 `LocaleService` 的测试现在依赖环境的 `navigator`：断言本地化文案的用例以一行套件级 `usePinnedBrowserLanguages('zh-CN')`（dsh-client-test-runtime）声明其浏览器，今后任何断言默认值的用例同样如此。本包自己的用例直接给全局打桩，因为它们需要该 helper 刻意不表达的形状（`languages` 缺失、列表与 `language` 解耦、完全没有 `window`）。
 - 探测的代价是每次服务构造遍历一次数组，且不写存储，因此启动行为与持久化状态面均无变化。
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
index e6ca4048fd..358d7b2a7a 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
 2026-07-31-code-mode-language-dispatch.md: 71e4fd5a30e90ac66132dbdcea16917bacc80b68
-2026-07-31-code-mode-language-dispatch.zh.md: 1dbb3d889d28669575980d3a667e4f168a5d72db
+2026-07-31-code-mode-language-dispatch.zh.md: 3cbd587b52eb650b071fc072acd73780435dc91a
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
index 1dbb3d889d..3cbd587b52 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
@@ -23,24 +23,24 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 ### Python SDK 渲染器
 
-`py-types.ts` 渲染 `jsonSchemaToTs` 所覆盖的同一套统一工具 schema 词汇，目标为 Python：`jsonSchemaToPy` 为每个 JSON-schema 节点发出一个类型表达式，`renderToolsSdkPy` 为每个可见工具的参数与规范输出装配具名 `TypedDict`，再加一个带用法说明的 `tools` 对象，与 TypeScript 形态等价。不支持的原始构造在装配时降级而非抛错，与 TypeScript 渲染器的契约一致。输出是确定性的——工具按字典序排列，工具集不变时文本逐字节相同——因此 prompt 保持 prefix-cache 友好。字典序意味着单一有序的成员流：名字不是合法属性的工具以 `tools[name]` 注释出现在它排序后的位置上，而不是被分拣到末尾，与 TypeScript 形态就地为异常键加引号的做法一致。这个成员流直接决定了一件事：注释行不是语句，所以一个不发出任何方法的工具集仍需显式 `pass`。另有三条规则并非源自排序，而是 Python 特有。其一，用法约定声明这些声明只是静态存根、参数为普通 `dict`/`list` 值：`TypedDict` 读起来像一个可构造的类，模型若写 `FooArgs(field=1)` 会得到 `NameError`——TypeScript 的 `interface` 一眼就是类型，且 TS 形态的「runs type-stripped」一句已经覆盖了它。其二，描述会成为方法的 docstring，且必须作为方法体的**第一条语句**发出：放在 `async def` 之上，第一条会变成 `Tools` 的类文档、其余都是无效果表达式，导致每个方法都没有文档。其三，`list[…]` 链超过 `MAX_LIST_NESTING` 后降级为 `Any`，因为 CPython 的 tokenizer 拒绝一行中超过 200 个同时未闭合的括号，而这个块必须是可解析的 Python——与 `docLines` 转义引号和反斜杠是同一个理由。`ts-types` 两者都不需要：TypeScript 会把前置的 `/** … */` 附着到其后的成员上，其语法也不对嵌套设限。
+`py-types.ts` 渲染 `jsonSchemaToTs` 所覆盖的同一套统一工具 schema 词汇，目标为 Python：`jsonSchemaToPy` 为每个 JSON Schema 节点发出一个类型表达式，`renderToolsSdkPy` 为每个可见工具的参数与规范输出装配具名 `TypedDict`，再加一个带用法说明的 `tools` 对象，与 TypeScript 形态等价。不支持的原始构造在装配时降级而非抛错，与 TypeScript 渲染器的约定一致。输出是确定性的——工具按字典序排列，工具集不变时文本逐字节相同——因此 prompt 保持 prefix-cache 友好。字典序意味着单一有序的成员流：名字不是合法属性的工具以 `tools[name]` 注释出现在它排序后的位置上，而不是被分拣到末尾，与 TypeScript 形态就地为异常键加引号的做法一致。这个成员流直接决定了一件事：注释行不是语句，所以一个不发出任何方法的工具集仍需显式 `pass`。另有三条规则并非源自排序，而是 Python 特有。其一，用法约定声明这些声明只是静态存根、参数为普通 `dict`/`list` 值：`TypedDict` 读起来像一个可构造的类，模型若写 `FooArgs(field=1)` 会得到 `NameError`——TypeScript 的 `interface` 一眼就是类型，且 TS 形态的「runs type-stripped」一句已经覆盖了它。其二，描述会成为方法的 docstring，且必须作为方法体的**第一条语句**发出：放在 `async def` 之上，第一条会变成 `Tools` 的类文档、其余都是无效果表达式，导致每个方法都没有文档。其三，`list[…]` 链超过 `MAX_LIST_NESTING` 后降级为 `Any`，因为 CPython 的 tokenizer 拒绝一行中超过 200 个同时未闭合的括号，而这个块必须是可解析的 Python——与 `docLines` 转义引号和反斜杠是同一个理由。`ts-types` 两者都不需要：TypeScript 会把前置的 `/** … */` 附着到其后的成员上，其语法也不对嵌套设限。
 
 该上限服务的标准是**语法合法性**，这条边界是有意划定的：长的 `A | B | …` union 在任何长度下都是合法 Python，故不设上限——尽管 CPython 的 `compile()` 在沿左嵌套 `BinOp` 脊柱下降时会耗尽 C 递归（在 3.9 上实测：1,000 个分支可编译，5,000 个抛 `RecursionError`）。没有任何东西会编译这个块——它是提示词文本——所以那条限制在这里没有代价；而给 union 长度封顶会作废那几个钉住 walk 线性时间与类名传播上限的深链测试。将来若有渲染器确实需要可编译的输出，应当把 union 拍平，而不是截断。
 
-`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程 seam 上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process seams](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的契约是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
+`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程 seam 上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process seams](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的约定是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-- **在 `ToolRegistry` 上加一个 `language` 配置字段。** 那样部署方就会有两处命名语言（所加载的运行时与 tools 配置）且可能相互矛盾；所加载的运行时是唯一真相来源，故注册表读取它而不复制它。
+- **在 `ToolRegistry` 上加一个 `language` 配置字段。** 那样部署方就会有两处命名语言（所加载的运行时与 tools 配置）且可能相互矛盾；所加载的运行时是真源，故注册表读取它而不复制它。
 - **把 Python 后端 import 进 `code-mode.ts` 来检测它。** 那会把工具层耦合到具体后端，并迫使协议/后端 PR 先落地。按 `language` 运行时分发使该层保持后端无关、可独立发布。
 - **为未知语言提供默认渲染器。** 静默回退会在比如 Ruby 运行时上发出 TypeScript SDK——模型会看到错误语言的指令。在装配处 fail loud 是本仓库对错误配置的立场。
 
-## Consequences
+## 后果
 
 新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在消费方的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：接口包不得 import 其消费方的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 seam 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
 
-代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
+代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture（测试前置数据）运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript（文本记录）。
 
-Python SDK 文本断言的两条运行时契约同样归属那个 backend PR。其一，说明文字告诉模型运行时恰好绑定 `tools` 与 `ToolCallError` 两个名字、所声明的 `TypedDict` 类不绑定，因此后端必须注入这两个名字（并按 seam 的 `errorClass` 契约填充 `ToolCallError.toolName`），且**不得**把所声明的类名绑进程序全局——「好心」注入会使这段 SDK 文本变成假话。其二，语言必须绑定到请求上：`requireCodeRuntime` 在组装时与 `run_code` 执行时分别解析 `ctx.codeRuntime`，若在这两点之间发生重载并换掉运行时，就会把针对一种形态写成的程序交给另一种形态执行。分裂比这两点更细——`run_code` 的 `description` 与 `parameters` 两个 getter 各自调用 `resolveFlavor(peekRuntime())`，而 `schemaOf` 会解构这两个字段，因此一次投影读两次运行时；两次都属于 `run_code` 自己的 schema，因为这两个 getter 只装在那一个 definition 上，其余 definition 携带的都是普通数据属性。在这两次读取之间重载会产出单个 schema 的两半分属不同语言。两者在此处都不可达——只有一个已发布后端意味着两次读取返回同一形态，且没有任何程序会针对本渲染器的输出运行——而跨语言拒绝在第二门语言存在之前也无法测试。
+Python SDK 文本断言的两条运行时约定同样归属那个后端 PR。其一，说明文字告诉模型运行时恰好绑定 `tools` 与 `ToolCallError` 两个名字、所声明的 `TypedDict` 类不绑定，因此后端必须注入这两个名字（并按 seam 的 `errorClass` 约定填充 `ToolCallError.toolName`），且**不得**把所声明的类名绑进程序全局——「好心」注入会使这段 SDK 文本变成假话。其二，语言必须绑定到请求上：`requireCodeRuntime` 在组装时与 `run_code` 执行时分别解析 `ctx.codeRuntime`，若在这两点之间发生重载并换掉运行时，就会把针对一种形态写成的程序交给另一种形态执行。分裂比这两点更细——`run_code` 的 `description` 与 `parameters` 两个 getter 各自调用 `resolveFlavor(peekRuntime())`，而 `schemaOf` 会解构这两个字段，因此一次投影读两次运行时；两次都属于 `run_code` 自己的 schema，因为这两个 getter 只装在那一个 definition 上，其余 definition 携带的都是普通数据属性。在这两次读取之间重载会产出单个 schema 的两半分属不同语言。两者在此处都不可达——只有一个已发布后端意味着两次读取返回同一形态，且没有任何程序会针对本渲染器的输出运行——而跨语言拒绝在第二门语言存在之前也无法测试。
 
 其三，那个 PR 拥有 CPython 版本下限，连带拥有本渲染器的 Unicode 表偏斜。有四处表达式读所运行引擎的表（Node 22.23.1：Unicode 17.0），而解释器用它自己的表（CPython 3.9.6：13.0.0）：`isBareIdentifier` 的 `IDENTIFIER`，以及 `camelCase` 的切分集、头部测试与 `toUpperCase()`。解释器旧于引擎是会失败的那个方向——引擎发出的字符被其 tokenizer 拒收，整个块随之不可解析——而它经三条独立路径抵达。经判据抵达的是裸发的方法名或字段名，其中带有一个在两个版本之间新增的字符——首位加进 `XID_Start`，或尾部任意位置（含名字中部）加进 `XID_Continue`。经 `camelCase` 的 XID 读取抵达的是类名：只要工具 schema 中有任一对象形态声明 `TypedDict`，该类名就进入发出的文本，且判据对工具名的裁决并不对它设闸——工具名 `zz-` 加 U+1E4D0 因 `-` 被判据直接拒绝、从不触及那里的偏斜，却照样声明 `class Zz𞓐xArgs`。经大写映射抵达的是由判据已接受的工具派生出的类名——这是另一张表，窗口也比 XID 归属更宽：U+019B 既是 XID_Start 又 NFKC 稳定，故 `async def ƛ` 在 3.9.6 上可编译，但 Node 将其大写为 U+A7DC（在那里未分配；CPython 自己的 `.upper()` 在此是恒等），于是 `class ꟜArgs` 以 `invalid non-printable character U+A7DC` 失败。暴露窗口是两个版本之间发生变化的那些字符与映射，所以宣布支持某个 CPython 范围的那个 PR 必须在「接受该暴露」与「按该下限的表钉住全部四个读取点」之间显式作出决定——只钉判据会同时留下两条类名路径。此处无法决定：下限尚不存在，而按猜测钉死一张表会成为一个随部署而变、却没有可配置性支撑的常量。还有第二条轴随该下限一同确定，且不属于那四个读取点：本块在定义期会被求值的那些名字与语法。`TypedDict` 需要 3.8，PEP 585 的内建泛型 `dict[str, Any]` 与 `list[…]` 需要 3.9，`A | B` 形式的注解需要 3.10，`NotRequired` 需要 3.11。这些不是解析失败——本块在任何版本上都能解析，这正是 `MAX_LIST_NESTING` 上限所服务的标准——而是定义期求值失败，且产品中没有任何东西会求值这段文本。把它们与那四个读取点记在一起，可避免把「在所支持范围上可解析」读成「在其上可执行」。
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
index d1cef43cc1..151d74e3dc 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
 2026-07-31-even-out-shipped-tool-rosters.md: 0195620055da5e570d2f54792d950a88bab8d652
-2026-07-31-even-out-shipped-tool-rosters.zh.md: cc67f24720f650283daa4ee85a0a1af5358756a8
+2026-07-31-even-out-shipped-tool-rosters.zh.md: ab6982e33c4a0a25cbc2fde386456840ce99d9c5
diff --git a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
index cc67f24720..ab6982e33c 100644
--- a/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md
@@ -6,19 +6,19 @@ Status: implemented
 
 ## 问题
 
-两个交付的 `dsh` surface 提供着不同的工具,而没有任何记录说明为什么。会话检查点、工具结果裁剪、goal 工具和 Ralph 在 `tui.cordis.yml`;`tool-todo` 以及后来的 web 搜索在 `web.cordis.yml`。两个 surface 都没有会话搜索、字符串替换编辑器和重复工具守卫,尽管这三者都已成包存在,且没有一个是 surface 专属的。
+两个交付的 `dsh` surface 提供着不同的工具，而没有任何记录说明为什么。会话检查点、工具结果裁剪、goal 工具和 Ralph 在 `tui.cordis.yml`；`tool-todo` 以及后来的 web 搜索在 `web.cordis.yml`。两个 surface 都没有会话搜索、字符串替换编辑器和重复工具守卫，尽管这三者都已成包存在，且没有一个是 surface 专属的。
 
-结果是一处没人做过决定的用户可见差异:同一个模型、同一个请求,在终端上能定目标而在浏览器里不能,在浏览器里能搜网页而在终端上不能。
+结果是一处没人做过决定的用户可见差异：同一个模型、同一个请求，在终端上能定目标而在浏览器里不能，在浏览器里能搜网页而在终端上不能。
 
 ## 决策
 
-那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml),另有三行加入:`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 组装同一份清单：每台宿主上都有二十二个工具——二十个共享行加上 `glob` 和 `grep`，它们成为固定成员，因为 `dsh-tool-fs-search` 直接 spawn [打包的 ripgrep 二进制](../architecture/2026-08-01-packaged-ripgrep-search.md)。`tool-session-query` 加入后又退出了——[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)让面向模型的消费方保持需显式启用——而这份清单的其余部分保持不变。
+那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml)，另有三行加入：`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 组装同一份清单：每台宿主上都有二十二个工具——二十个共享行加上 `glob` 和 `grep`，它们成为固定成员，因为 `dsh-tool-fs-search` 直接 spawn [打包的 ripgrep 二进制](../architecture/2026-08-01-packaged-ripgrep-search.md)。`tool-session-query` 加入后又退出了——[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)让面向模型的消费方保持需显式启用——而这份清单的其余部分保持不变。
 
-有两行仍是 surface 专属。`tmux-context` 只在 TUI,因为浏览器 surface 没有终端复用器可描述。`session-reference` 只在 TUI,因为它以 launcher 的进程本地路径驱动共享的 session-query 索引,而浏览器侧边栏会在自己的首次搜索里重建该索引。
+有两行仍是 surface 专属。`tmux-context` 只在 TUI，因为浏览器 surface 没有终端复用器可描述。`session-reference` 只在 TUI，因为它以 launcher 的进程本地路径驱动共享的 session-query 索引，而浏览器侧边栏会在自己的首次搜索里重建该索引。
 
 **本次工具清单决策当时只做加法。** 落地时两个 surface 均未移除任何工具行，目录对比只发现了新增，别无其他。这些新增中的一项 `tool-session-query` 随后被[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)移除。共享执行器、沙箱组合与访问默认值独立归属[workspace-write 默认值决策](2026-07-31-workspace-write-surface-default.md)。
 
-### 什么保持不挂,以及为什么
+### 什么保持不挂，以及为什么
 
 有三项能力基于其自身包所记录的证据保持在外,列在这里是为了让「我们忘了」和「我们决定不要」保持可区分。
 
@@ -26,13 +26,13 @@ Status: implemented
 
 **`dsh-web-fetch-local`** 保持不挂,`dsh-tool-web` 保持 `fetch: false`。SSRF 防护在实现中是 deferred 状态([`policy.ts`](../../../../packages/web/web-fetch-local/src/policy.ts) 只校验协议、凭据与长度),包里也直说了:「this provider is an SSRF primitive and **must not be enabled** in a deployment that can reach sensitive internal network targets」([README](../../../../packages/web/web-fetch-local/README.md))。目标由模型选择,其中包括 harness 自己跑在环回地址上的网关、内网段和云元数据端点。
 
-弃用它收窄的是接触面而非可达性:`bash` 是挂着的,`curl` 照样能拿到同一个页面——一次真实运行确认了这点。这个缺席买到的是去掉一个无需 shell、以参数成形的请求原语,以及随之而来的那条意外路径:一次「帮我总结这个页面」悄悄打到环回地址。真要收住出站流量的部署需要的是网络层管控。
+不挂载它收窄的是接触面而非可达性：`bash` 是挂着的,`curl` 照样能拿到同一个页面——一次真实运行确认了这点。这个缺席买到的是去掉一个无需 shell、以参数成形的请求原语,以及随之而来的那条意外路径:一次「帮我总结这个页面」悄悄打到环回地址。真要收住出站流量的部署需要的是网络层管控。
 
 **LSP 三件套**留在外面是运维原因而非安全原因:`command` 在插件加载时从 `PATH` 解析,因此缺少语言服务器会让整次启动失败,而不只是失去一个工具。等到「缺失」退化为「跳过注册」之后,它就可以挂了。
 
 ### MCP 是依赖,不是配置行
 
-`@deepseek-ai/dsh-mcp-client` 成为本 CLI 的运行时依赖,但在任何交付配置里都没有对应的行。该插件每个实例只挂载一台服务器,且 `command` 是必填,因此一个默认值必须点名一台第三方服务器,并在每次启动时把它作为子进程 spawn——不经 `ctx.bash`,因而也在 Web surface 所组合的沙箱策略之外。
+`@deepseek-ai/dsh-mcp-client` 成为本 CLI（命令行界面）的运行时依赖,但在任何交付配置里都没有对应的行。该插件每个实例只挂载一台服务器,且 `command` 是必填,因此一个默认值必须点名一台第三方服务器,并在每次启动时把它作为子进程 spawn——不经 `ctx.bash`,因而也在 Web surface 所组合的沙箱策略之外。
 
 真正能让 MCP 成为默认的那一层,恰恰是本仓库尚未拥有的:一个读取用户服务器清单、按条目逐台挂载客户端的桥接,形态与 [`dsh-hooks-claude`](../../../../packages/hooks/hooks-claude/README.md) 读取 Claude Code 的 `hooks.json` 完全相同。交付这个依赖意味着已安装的 `dsh` 今天就能从 `$DSH_HOME/config.yaml` 挂载服务器;CLI README 里给了那段 YAML。
 
@@ -54,11 +54,11 @@ Status: implemented
 
 **把共享的行复制进两份 overlay,而不是提升到 base。** 基于「一处归属」原则否决:新增行里有三行会存在两份,而这些副本没有任何理由发生分歧,下一次改工具清单还得记着改两处。
 
-**在同一次改动里给 TUI 加沙箱。** 不予采纳，因为这是一个不属于工具清单改动的独立决定：TUI 挂的是不受限执行器，替换它们会改变一个既有 surface 做什么，而非它提供什么。这个决定需要自己的证据——尤其因为 TUI 没有 `approval/request` 的应答方，升级请求在那里会 fail-closed，而不是弹出提示。
+**在同一次改动里给 TUI 加沙箱。** 不予采纳，因为这是一个不属于工具清单改动的独立决定：TUI 挂的是不受限执行器，替换它们会改变一个既有 surface 做什么，而非它提供什么。这个决定需要自己的证据——尤其因为 TUI 没有 `approval/request` 的应答方，升权请求在那里会 fail-closed，而不是弹出提示。
 
 **开启 Code Mode。** 它的信任立场按设计与 bash 同级,工具调用要过与 bash 相同的 `tools/pre-execute` 闸门,所以它与上面那些模型写码工具不是同一个判断。在这里仍被否决:`both` 会改变两个 surface 上每一个模型可见请求,而 `code` 是把线路替换而非加一个——两者都是呈现方式的决定,不是工具清单的决定。
 
-**默认挂一台 MCP 服务器。** 否决,因为交付默认值必须点名一台,而任何选择都会在每个用户的机器上、在沙箱之外 spawn 一个第三方子进程。改为交付依赖。
+**默认挂一台 MCP 服务器。**否决，因为交付默认值必须点名一台，而任何选择都会在每个用户的机器上、在沙箱之外 spawn 一个第三方子进程。改为交付依赖。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
index 99ea335b59..fa5ea6f634 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.md
 2026-07-31-gui-full-access-confirmation.md: ca89ed23fb1b5c6ea438dd22fdf20d2b82af754c
-2026-07-31-gui-full-access-confirmation.zh.md: 0f487e41b544718bdf38de611a1ab2d59c44b063
+2026-07-31-gui-full-access-confirmation.zh.md: a31c1ee744b111dd6917f0d2ed7ba9988c2aee47
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
index 0f487e41b5..a31c1ee744 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
@@ -4,28 +4,28 @@ Status: implemented
 
 [English](2026-07-31-gui-full-access-confirmation.md) | 中文
 
-## Problem
+## 问题
 
-在 Web 客户端的权限选择器中切换到 `danger-full-access` 只需一次点击，且预设以 Title Case 机器名 `Danger Full Access` 展示。Full access 会减少确认步骤，允许智能体执行敏感操作、修改文件或运行外部命令，误点即在毫无刻意确认环节的情况下启用了最危险的预设。
+在 Web 客户端的权限选择器中切换到 `danger-full-access` 只需一次点击，且预设以 Title Case 机器名 `Danger Full Access` 展示。Full access 会减少确认步骤，允许 agent（智能体）执行敏感操作、修改文件或运行外部命令，误点即在毫无刻意确认环节的情况下启用了最危险的预设。
 
-## Decision
+## 决策
 
 **每个权限选择器都把 `danger-full-access` 关进共享的页面内 `RiskConfirmation` 对话框：启用按钮在用户勾选明确的风险确认复选框前保持禁用；预设以产品标签 `Full access` 展示；所有取消路径都不作任何提交。**
 
-- `RiskConfirmation`（ui-primitives）是受控的 Modal 组合：标题、说明、确认复选框、取消，以及 `acknowledged` 勾选前禁用的确认按钮。它始终是页面内对话框——Modal portal 到本文档 body，绝不打开可能落在另一块显示器上的原生或独立浏览器窗口。`Modal` 新增 `contentClassName` 座位，令警示正文在受限的移动端／横屏视口内滚动，动作行保持固定。
-- 编辑器 chip（ui-conversation 的 `PermissionSelect`）在 `/permission` 提交前拦截 Full-access 选择：`confirmation`/`acknowledged` 组件状态打开对话框，确认后经与其他选择完全相同的注入 `command` 通道提交 `/permission danger-full-access`；取消、Escape、关闭与遮罩点击均保持当前预设不变并重置复选框。会话锁定时确认自行撤销（`locked`／值缺席 effect），切换任务时随 `key={sessionId}` 重挂载而重置。文案经标准 `conversation` locale 座位以 `access.confirm.*` 键供给。
-- `/permission` popup（ui-permission 骑在 ui-command 外壳上）以数据而非第二套对话框实现完成把关：`SelectOption` 新增可选的 `confirmation` 载荷，popup 控制器拥有 `confirming`/`acknowledged` 状态迁移，`PopupSelectView` 在门控选项未决期间把选择卡换成同一个 `RiskConfirmation`。
+- `RiskConfirmation`（ui-primitives）是受控的 Modal 组合：标题、说明、确认复选框、取消，以及 `acknowledged` 勾选前禁用的确认按钮。它始终是页面内对话框——Modal portal 到本文档 body，绝不打开可能落在另一块显示器上的原生或独立浏览器窗口。`Modal` 新增 `contentClassName` slot，令警示正文在受限的移动端／横屏视口内滚动，动作行保持固定。
+- composer chip（ui-conversation 的 `PermissionSelect`）在 `/permission` 提交前拦截 Full-access 选择：`confirmation`/`acknowledged` 组件状态打开对话框，确认后经与其他选择完全相同的注入 `command` 通道提交 `/permission danger-full-access`；取消、Escape、关闭与遮罩点击均保持当前预设不变并重置复选框。会话锁定时确认自行撤销（`locked`／值缺席 effect），切换任务时随 `key={sessionId}` 重挂载而重置。文案经标准 `conversation` locale slot以 `access.confirm.*` 键供给。
+- `/permission` popup（ui-permission 构建于 ui-command 外壳之上）以数据而非第二套对话框实现完成把关：`SelectOption` 新增可选的 `confirmation` 载荷，popup 控制器拥有 `confirming`/`acknowledged` 状态迁移，`PopupSelectView` 在门控选项未决期间把选择卡换成同一个 `RiskConfirmation`。
 - 「通用」设置中的「权限」行在把 Full access 持久化为后续会话的默认值前，也使用同一个受控 `RiskConfirmation`。警示会明确说明该设置只影响后续会话；取消、Escape、关闭与点击遮罩均不会改动已存默认值。
 - `Full access` 在每个选择器中都有意覆盖 kebab 转 Title Case 的显示变换；命令与 Settings 写入在 wire 上保留机器名，每份警示正文都保持中英文 locale 感知。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **原生／操作系统或独立窗口确认。** 已拒：对话框必须留在当前 WebUI 窗口内；第二个窗口可能出现在另一块显示器上，使决策脱离其守护的页面状态。
 
-**每个面的安全文案共享一个 locale namespace。** 已拒：ui-permission bundle 与 ui-conversation 可独立加载，而 Settings 警示说明的是另一种只影响后续会话的生效周期。每个 bundle 各自拥有文案，ui-permission 也将 popup 与 Settings 词典分开，而非跨 bundle 边界 import。
+**每个界面的安全文案共享一个 locale namespace。**不予采用：ui-permission bundle 与 ui-conversation 可独立加载，而 Settings 警示说明的是另一种只影响后续会话的生效周期。每个 bundle 各自拥有文案，ui-permission 也将 popup 与 Settings 词典分开，而非跨 bundle 边界 import。
 
 **在 host／权限后端把关。** 设计上即出界：本变更只涉浏览器客户端确认流；后端权限语义、默认值与更安全预设的一键行为均不变。
 
-## Consequences
+## 后果
 
-进入 Full access 的每条可见 GUI 路径现在都要求刻意且知情的确认，代价是真想启用该预设的用户多一步对话框。新的选择器通过各自拥有的状态机复用共享对话框，或在 popup 路径挂 `confirmation` 载荷。验收：`input-bar.spec.tsx` 中编辑器流的门控用例、`popup-view.spec.tsx` 与 `popup.spec.ts` 的 popup 门、`permission-row.spec.tsx` 的默认设置门控、`atoms.spec.tsx` 的 Modal/RiskConfirmation 契约，以及组装态 Web 回放。
+进入 Full access 的每条可见 GUI 路径现在都要求刻意且知情的确认，代价是真想启用该预设的用户多一步对话框。新的选择器通过各自拥有的状态机复用共享对话框，或在 popup 路径挂 `confirmation` 载荷。验收：`input-bar.spec.tsx` 中编辑器流的门控用例、`popup-view.spec.tsx` 与 `popup.spec.ts` 的 popup 门、`permission-row.spec.tsx` 的默认设置门控、`atoms.spec.tsx` 的 Modal/RiskConfirmation 约定，以及组装态 Web 回放。
diff --git a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
index 3227fac451..4970aa2c7d 100644
--- a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.md
 2026-07-31-permission-default-for-new-sessions.md: ffa4c8a07bdd08ca52edbc14fe10372ad76e8cf8
-2026-07-31-permission-default-for-new-sessions.zh.md: 5fc42724754acc1653ed93b48644794a38f52ba7
+2026-07-31-permission-default-for-new-sessions.zh.md: c70d431ec9bbe8cdeabfdc8a0052a9c436844f02
diff --git a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
index 5fc4272475..c70d431ec9 100644
--- a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Web「通用」设置页将「权限」显示为禁用的骨架控件，尽管 `dsh-permission` 已经拥有 preset 表和当前会话的切换路径。Settings seam 可以持久化由插件拥有的值，但 Web Settings API 只暴露可配置 LLM 提供方的 namespace。更重要的是，如果把用户偏好当成实时生效的全局权限，现有会话的执行策略就会在其持久日志之外发生变化。
+Web「通用」设置页将「权限」显示为禁用的骨架控件，尽管 `dsh-permission` 已经拥有 preset 表和当前会话的切换路径。Settings seam 可以持久化由插件拥有的值，但 Web Settings API 只暴露可配置 LLM（大语言模型）提供方的 namespace。更重要的是，如果把用户偏好当成实时生效的全局权限，现有会话的执行策略就会在其持久日志之外发生变化。
 
 ## 决策
 
@@ -26,10 +26,10 @@ ApiProxy 在可配置提供方 namespace 之外，将 `permission` 显式加入
 
 ## 曾考虑的替代方案
 
-**将 Settings 值实时应用于每个会话。** 不予采纳，因为执行策略会在没有会话事件的情况下改变，重放也无法重建先前工具调用采用了哪种权限。
+**将 Settings 值实时应用于每个会话。** 不予采纳，因为执行策略会在没有会话事件的情况下改变，回放也无法重建先前工具调用采用了哪种权限。
 
 **创建时只记录 `permission/preset`。** 不予采纳，因为沙箱和审批是由不同组件独立拥有的全量值调节项；固定全部三个事实，可以让其消费方不依赖未来的组合默认值变化。
 
-**暴露所有 Settings 注册，或增加通用的 `local-client` 声明。** 本次变更不予采纳，因为这会扩大安全边界，并使 Settings 契约超出所请求的单项偏好。显式加入 `permission` allowlist 已足够，未来的 namespace 可以各自决定是否暴露。
+**暴露所有 Settings 注册，或增加通用的 `local-client` 声明。** 本次变更不予采纳，因为这会扩大安全边界，并使 Settings 约定超出所请求的单项偏好。显式加入 `permission` allowlist 已足够，未来的 namespace 可以各自决定是否暴露。
 
 **恢复带 seed 的会话时应用最新默认值。** 不予采纳，因为恢复操作必须保留会话先前的有效执行策略；缺失的旧版事实应从该策略中补齐。
diff --git a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
index cca8f8a597..5565ea70b1 100644
--- a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-session-archive-global-set.md
 2026-07-31-session-archive-global-set.md: fab99a405a6f8264c36453473327e32905bac9c8
-2026-07-31-session-archive-global-set.zh.md: e33f3b5272a6d8fc90cfad247ba21d4d10afb045
+2026-07-31-session-archive-global-set.zh.md: b10440039f1c6a8ea2f89d9239a0285dd70cf9a2
diff --git a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
index e33f3b5272..b10440039f 100644
--- a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
@@ -1,26 +1,26 @@
-# Agent Note: Session 归档（注册表级全局集合）
+# Agent Note: 会话归档（注册表级全局集合）
 
-状态：implemented
+Status: implemented
 
 [English](2026-07-31-session-archive-global-set.md) | 中文
 
 ## 问题
 
-Sidebar workspace 浏览区的 session 行菜单里，「Delete session」一直是纯视觉占位（无 handler）。产品口径定为**归档**而非删除：session 日志与 workspace 记账都不动，只把该 session 从所有分组视图（workspace 分组、Ungrouped、搜索、平铺列表）里隐藏。归档记录需要一个落点：Ungrouped 的 session 不属于任何 workspace 实体，per-workspace 字段放不下它。
+Sidebar workspace 浏览区的会话行菜单里，「Delete session」一直是纯视觉占位（无 handler）。产品口径定为**归档**而非删除：会话日志与 workspace 记账都不动，只把该会话从所有分组视图（workspace 分组、Ungrouped、搜索、平铺列表）里隐藏。归档记录需要一个落点：Ungrouped 的会话不属于任何 workspace 实体，per-workspace 字段放不下它。
 
 ## 决策
 
 **归档集合是 workspace domain 全局单例（`workspaceDomainState.archivedSessionIds`）上的一个新字段，覆盖在 workspace 记账之上；显示过滤全部收敛在 client 的 `tree.ts` 派生层；wire 面走全快照姿态。**
 
-- 存储：`archivedSessionIds: z.array(sessionId).default([])`，domain version 保持 2——纯增量字段，旧介质经 schema default 解析为空集合，无迁移代码。被归档的 session 保留其 `sessionIds` 席位（未来取消归档恢复原位置），因此与「一个 session 只被一个 workspace 记账」不变式零纠缠。
-- Registry：`ctx.workspace.archiveSession(id)` 走 `enqueueOperation` 与 create/delete 串行；未知 session（实时与持久化都查不到）抛 `WorkspaceUnknownSessionError`；已归档 id 不写盘不发事件。`archivedSessionIds` getter 暴露只读集合。
-- RPC：`workspace.archiveSession({sessionId}) → {archivedSessionIds}`（应答完整更新后集合）；`workspace.list` 响应携带集合作为重连基线；新 host 帧 `host/archived-sessions-changed` 在每次持久变更后推完整快照（与 `host/workspace-changed` 同姿态，从 `domain/changed` 的 global put 分支比对推帧）。未知 session 复用错误码 `session-not-found`。
-- client runtime：`WorkspaceListState.archivedSessionIds`（按 Host 顺序的 `readonly SessionId[]`，成员不变不换引用——公有快照状态保持 store 引擎的纯数据词汇：immer draft 不开 MapSet 插件就不接受 Set；membership 查询在派生函数内自建临时 Set，与 expandedProjects 同款）；list 基线、unary 回声、changed 帧三路都整体替换安装。投影层在当前 selection 落入归档集合时统一清空回 New Session 视图（用户拍板：归档当前打开的 session 主视图回 hero）——一条规则同时覆盖本地 unary 回声、其他标签页的 changed 帧、以及重连基线恢复出一个离线期间被归档的 selection；帧/回声落在 in-flight `workspace.list` 期间时还会屏蔽旧基线对新集合的回滚。
+- 存储：`archivedSessionIds: z.array(sessionId).default([])`，domain version 保持 2——纯新增字段，旧介质经 schema default 解析为空集合，无迁移代码。被归档的会话保留其 `sessionIds` slot（未来取消归档恢复原位置），因此与「一个会话只被一个 workspace 记账」不变式零纠缠。
+- 注册表：`ctx.workspace.archiveSession(id)` 走 `enqueueOperation` 与 create/delete 串行；未知会话（实时与持久化都查不到）抛 `WorkspaceUnknownSessionError`；已归档 id 不写盘不发事件。`archivedSessionIds` getter 暴露只读集合。
+- RPC：`workspace.archiveSession({sessionId}) → {archivedSessionIds}`（应答更新后的完整集合）；`workspace.list` 响应携带集合作为重连基线；新 host 帧 `host/archived-sessions-changed` 在每次持久变更后推完整快照（与 `host/workspace-changed` 同姿态，从 `domain/changed` 的 global put 分支比对推帧）。未知会话复用错误码 `session-not-found`。
+- client 运行时：`WorkspaceListState.archivedSessionIds`（按 Host 顺序的 `readonly SessionId[]`，成员不变不换引用——公有快照状态保持 store 引擎的纯数据词汇：immer draft 不开 MapSet 插件就不接受 Set；membership 查询在派生函数内自建临时 Set，与 expandedProjects 同款）；list 基线、unary 回声、changed 帧三路都会用完整集合整体替换现有值。投影层在当前 selection 落入归档集合时统一清空回 New Session 视图（用户拍板：归档当前打开的会话会使主视图回到 hero）——一条规则同时覆盖本地 unary 回声、其他标签页的 changed 帧、以及重连基线发现当前 selection 已在此 client 离线期间被归档的情形；帧/回声落在 in-flight `workspace.list` 期间时还会屏蔽旧基线对新集合的回滚。
 - UI：菜单项 `delete`（visual-only）改为 `archive`（label「Archive session」，非 danger 样式，无确认对话框——非破坏性操作，误触后果只是列表隐藏）；过滤实现为 `tree.ts` 的 `sessionVisible` 判据加一档，`deriveGroups`/`deriveFlat` 增加 `archived` 集合入参，四个视图（分组循环、stray 兜底、搜索、平铺）同源生效。
 
 ## 已考虑的替代方案
 
-**per-workspace archivedSessionIds（最初表述）。** 否决：Ungrouped session 无落点；用户改口全局。
+**per-workspace archivedSessionIds（最初表述）。** 否决：Ungrouped 会话无落点；用户改口全局。
 
 **SessionSummary 打 archived 标（session.list 层）。** 否决：要把 workspace domain 事实 join 进 sessions domain 投影，summary 无增量帧还得另发通知，跨域耦合大于收益。
 
@@ -30,4 +30,4 @@ Sidebar workspace 浏览区的 session 行菜单里，「Delete session」一直
 
 ## 后果
 
-归档后 UI 无查看/取消归档入口（本期口径，README Known Limitation 记账）；数据与席位完好，后续加恢复面只是 UI + 一个逆向 RPC。`workspace.list` 响应形状变化是 pre-release 直改（无兼容层）。e2e（workspace-management）钉住了「归档→行消失→reload 后仍隐藏、日志仍在」的全链路；domain 层测试钉住幂等、未知 id 拒绝、跨重启恢复与旧介质默认升级。
+归档后 UI 无查看/取消归档入口（本期口径，记录在 README 的 Known Limitation 中）；数据与slot完好，后续加恢复面只是 UI + 一个逆向 RPC。`workspace.list` 响应形状变化是 pre-release 直改（无兼容层）。e2e（workspace-management）钉住了「归档→行消失→reload 后仍隐藏、日志仍在」的全链路；domain 层测试钉住幂等、未知 id 拒绝、跨重启恢复与旧介质默认升级。
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
index 7bcfa9f599..e17ee5343c 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
 2026-07-31-telemetry-anonymous-user-id.md: 3c8e3324cb418eac48cb5ae780c55bbcbaf3caa1
-2026-07-31-telemetry-anonymous-user-id.zh.md: 9ff6cf35a90d4087b4ab75987dc9244210e3d46a
+2026-07-31-telemetry-anonymous-user-id.zh.md: b8b90bbad64abc409d743f89fb156bb94d7f6a7f
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
index 9ff6cf35a9..b8b90bbad6 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
@@ -10,19 +10,19 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 
 ## Decision
 
-`session-telemetry-otel` 包内模块 `src/user-id.ts` 是 OTel 回流用户身份的属主：`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；backend 构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。该身份只属于 OTel 回流；dsh-sdk launcher telemetry 保留自己的匿名 id 存储（`telemetry.json`），两者不共享（初版曾做公用 util 包统一两条回流，用户复议后收回：在有第二个真实消费者之前不抽公共包，回流关联需求出现时再议）。
+`session-telemetry-otel` 包内模块 `src/user-id.ts` 是 OTel 回流用户身份的属主：`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；backend 构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。该身份只属于 OTel 回流；dsh-sdk launcher telemetry 保留自己的匿名 id 存储（`telemetry.json`），两者不共享（初版曾做公用 util 包统一两条回流，用户复议后收回：在有第二个真实消费方之前不抽公共包，回流关联需求出现时再议）。
 
 | 裁定 | 取值 | 理由 |
 |---|---|---|
 | id 来源 | 随机 UUID v4，绝不从 hostname/网络地址/git remote 派生 | 派生 id 可反查，「匿名」名不副实 |
 | 存储形态 | `.userid` 裸 UUID 行 + 换行，无 JSON 包装 | 身份是独立事实，不挂在某条 telemetry 链路的文件命名/格式下 |
 | 读写形态 | 同步 IO + 进程内按解析后文件路径 memo | `TelemetryOtel` 构造函数是同步的（async 迫使插件装载改形）；一进程一次盘 IO，运行中删文件不影响本进程 |
-| 并发首启 | `wx` 独占写裁决，落败方重读胜者 id | 覆盖常见并发（重读撞进胜者建档-写入微秒窗仍可能各持一 id 一次运行，下次启动收敛到落盘值——telemetry 级后果，接受） |
+| 并发首启 | `wx` 独占写裁决，落败方重读胜者 id | 覆盖常见并发（若重读恰好落在胜者创建文件至写入内容之间的微秒窗口内，该次运行中仍可能每个进程各持一个 id；下次启动时会收敛到已落盘的值——这是 telemetry 级后果，可以接受） |
 | 丢失语义 | 文件被删 → 下次启动换新 id，接受丢失 | 匿名身份无恢复价值；可恢复性要求派生材料，与匿名冲突 |
 | 写失败 | best-effort 返回内存 id | telemetry 永不因 home 只读被阻塞 |
-| 上报位置 | Resource 属性，非逐条 attributes | 每批一次即够接收端按 Resource 维度聚合；逐条注入要动 seam 契约且涨 wire 体积 |
+| 上报位置 | Resource 属性，非逐条 attributes | 每批一次即够接收端按 Resource 维度聚合；逐条注入要动 seam 约定且涨 wire 体积 |
 | semconv 依赖 | 不引 `@opentelemetry/semantic-conventions` 包 | 一个字符串常量不值一个依赖 |
-| 落点 | `session-telemetry-otel` 包内模块，非公共 util 包 | 仓规「有第二个真实消费者才拆包」；sdk launcher 回流保留自有存储，无现实关联需求 |
+| 落点 | `session-telemetry-otel` 包内模块，非公共 util 包 | 仓规「有第二个真实消费方才拆包」；sdk launcher 回流保留自有存储，无现实关联需求 |
 | 单独开关 | 无 | 身份跟随 telemetry 整体开关（`DSH_TELEMETRY_DISABLED`）；关 telemetry 即整体不报 |
 
 ## Alternatives considered
@@ -30,10 +30,10 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 | 被拒 | 一句话理由 |
 |---|---|
 | hostname/IP 哈希派生 id（此前口径） | 可反查即非匿名；随机 UUID 语义干净，用户裁决取代 |
-| user.id 放每条 record 的 attributes（Claude Code 形态） | 要动 session-telemetry seam 契约或逐条注入，wire 体积涨；Resource 每批一次已满足聚合 |
-| 公用 util 包统一两条回流（初版实现） | 唯一现实消费者是 OTel backend；sdk launcher 换用它只是为统一而统一——用户复议收回，回流关联需求出现时再抽包 |
+| user.id 放每条 record 的 attributes（Claude Code 形态） | 要动 session-telemetry seam 约定或逐条注入，wire 体积涨；Resource 每批一次已满足聚合 |
+| 公用 util 包统一两条回流（初版实现） | 唯一现实消费方是 OTel backend；sdk launcher 换用它只是为统一而统一——用户复议收回，回流关联需求出现时再抽包 |
 | 复用 telemetry.json 不新建文件 | 文件名/JSON 格式把身份挂在 launcher 链路命名下；OTel 回流身份是独立事实 |
-| AppCLIEntry 读好 id 经 config patch 注入 | 每个 surface 入口都要接线；config 里传运行时事实与部署配置混淆 |
+| AppCLIEntry 读好 id 经 config patch 注入 | 每个 surface 入口都要接线；在 config 里传运行时事实，会混淆运行时事实与部署配置 |
 | 挂进 `@deepseek-ai/dsh-paths` | paths 是纯路径计算零 IO；带持久化的身份能力会污染包边界 |
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
index 1c04bc1d55..7c42b6c7dc 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-default-search.md
 2026-07-31-web-default-search.md: 8f2cc6f5d1a9ec9f33279ae8e5c992bdc660e7fa
-2026-07-31-web-default-search.zh.md: 7d528617143cb9756d0a4532bb1ed6a3a3e70ca8
+2026-07-31-web-default-search.zh.md: 46db167b84f8c1a10686a941b174008ebafc720d
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
index 7d52861714..46db167b84 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
@@ -16,7 +16,7 @@ DeepSeek 搜索使用与官方会话适配器相同的 `DEEPSEEK_API_KEY` 凭据
 
 搜索端点与 chat completions 保持独立：`DEEPSEEK_SEARCH_BASE_URL` 覆盖 Anthropic 兼容基址，`DEEPSEEK_BASE_URL` 则继续配置会话请求。每次 `web_search` 都会发起一次辅助 DeepSeek Messages 调用，并携带原生搜索服务器工具。发出请求前一刻，提供方会向发起请求的 agent（智能体）会话追加仅用于日志的 LLM（大语言模型）请求事件 `web/deepseek-search-llm-request`，其中包含已解析端点、API 版本，以及不含密钥的精确 JSON 请求体。凭据预检仍留在提供方内部，并与调用方取消存在竞态；这两项关注点都不会扩展通用 Web seam 或凭据 seam。
 
-默认挂载不会创建 Web 专用权限策略。`web_search` 在 bash／文件系统沙箱及审批预设之外执行，并遵循 `dsh-tool-web` 的现有契约。组合不挂载 `web_fetch` 或本地抓取提供方，因此默认配置不会允许模型自行选择任意 URL 进行抓取。已交付的 `workspace-write` 默认值只管辖文件修改；若产品采取受限网络策略，就需要添加 `tools/pre-execute` 策略或按能力限制网络访问，而不能暗示文件系统访问模式会管辖 Web 调用。
+默认挂载不会创建 Web 专用权限策略。`web_search` 在 bash／文件系统沙箱及审批预设之外执行，并遵循 `dsh-tool-web` 的现有约定。组合不挂载 `web_fetch` 或本地抓取提供方，因此默认配置不会允许模型自行选择任意 URL 进行抓取。已交付的 `workspace-write` 默认值只管辖文件修改；若产品采取受限网络策略，就需要添加 `tools/pre-execute` 策略或按能力限制网络访问，而不能暗示文件系统访问模式会管辖 Web 调用。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml
index 743362fae1..5866d98309 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md
 2026-07-31-web-telemetry-default-mount.md: c1525a44196991d5059969ea70af34501b199323
-2026-07-31-web-telemetry-default-mount.zh.md: f203ea1943387beda445bd81ac78fa2cc0471d45
+2026-07-31-web-telemetry-default-mount.zh.md: ef5f7e4500a1776e049ac27e0e64756e78725a61
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
index f203ea1943..ef5f7e4500 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-07-31-web-telemetry-default-mount.md) | 中文
 
-## Problem
+## 问题
 
-遥测 seam 与 OTel backend（[revival Note](2026-07-23-session-telemetry-otel-revival.md)）自完成以来从未接入任何部署组合：没有 roster 行、没有开关、没有节奏口径，内部部署对用户会话零可观测。需要一个部署决策：哪些 surface 上报、报到哪、什么节奏、怎么关、CI 怎么隔离。
+遥测 seam 与 OTel 后端（[revival Note](2026-07-23-session-telemetry-otel-revival.md)）自完成以来从未接入任何部署组合：没有 roster 行、没有开关、没有节奏口径，内部部署对用户会话的可观测性为零。需要一个部署决策：哪些 surface 上报、报到哪、什么节奏、怎么关、CI 怎么隔离。
 
-## Decision
+## 决策
 
 `dsh` 共享 base（`apps/cli/config/base.cordis.yml`）默认挂载 `telemetry-otel` 行，内置生产 endpoint，因此 Web 与 headless 都会上报；原始配置命令也会先挂载该行，再应用其必需的部署 overlay。这是**内部测试期的部署立场**——有 endpoint 就上报，用户可通过环境变量退出。Web 与 headless 在 SIGINT/SIGTERM 时使用[有界、可升级的进程关闭控制器](../bug-fix/2026-08-03-cli-signal-shutdown-escalation.md)，在启动器 5 秒上限到期前，先给后端 3 秒关闭截止时间完成排空。
 
@@ -17,23 +17,23 @@ Status: implemented
 | 挂载面 | base.cordis.yml（原始配置 + Web + headless） | 所有加载共享 base 的配置树采用同一个部署立场；原始配置 overlay 决定该部署是否创建会话 |
 | endpoint | `DSH_TELEMETRY_OTLP_URL`，缺省 `https://harness-telemetry.deepseeksvc.com/v1/logs` | 内部 collector；env 覆盖供本地/联调 |
 | 退出开关 | `DSH_TELEMETRY_DISABLED` 非空（含 `0`/`false`）即关 | 隐私向开关取「宁关勿误开」；行级 disable 只能在 AppCLIEntry 的 patch 层做（config 无 disable 语义，且必须先于 `exporter.url` 的加载期校验生效） |
-| 上报节奏 | `processor.scheduledDelayMillis: 10000`（10s/批） | 流式回流，非退出才报；崩溃至多丢最后一个未导出间隔 |
-| 退出 drain 上界 | `exporter.timeoutMillis: 1000` + `maxExportBatchSize: 2048（== maxQueueSize）` + `exportTimeoutMillis: 1500` + `shutdownTimeoutMillis: 3000` | collector 不可达的常规故障会在约 1s 内放行：timeoutMillis 是单次 socket 超时与重试 deadline，使用与队列等大的单批可避免依次排空导致耗时倍增。由 DSH 管理的 3s 外层上限覆盖 SDK 先执行的无界 `forceFlush()` 等待，即传输 Promise 始终无法取得 socket 的情况。 |
+| 上报节奏 | `processor.scheduledDelayMillis: 10000`（10s/批） | 流式回流，非退出才报；崩溃至多丢失最后一个尚未导出间隔内的数据 |
+| 退出 drain 上界 | `exporter.timeoutMillis: 1000` + `maxExportBatchSize: 2048`（与 maxQueueSize 相等） + `exportTimeoutMillis: 1500` + `shutdownTimeoutMillis: 3000` | collector 不可达的常规故障会在约 1s 内放行：timeoutMillis 是单次 socket 超时与重试 deadline，使用与队列等大的单批可避免依次排空导致耗时倍增。由 DSH 管理的 3s 外层上限覆盖 SDK 先执行的无界 `forceFlush()` 等待，即传输 Promise 始终无法取得 socket 的情况。 |
 | 压缩 | `compression: gzip` | 事件 body 含全文，跨机房带宽 |
-| CI 隔离 | 全部 8 个 GitHub workflow 顶层 `env: DSH_TELEMETRY_DISABLED: '1'` | CI 启动 web 组合的所有通道（e2e/snapshot/built smoke）不得向生产 endpoint 泄测试会话 |
+| CI 隔离 | 全部 8 个 GitHub 工作流顶层 `env: DSH_TELEMETRY_DISABLED: '1'` | CI 启动 web 组合的所有通道（e2e/快照/已构建版本的冒烟测试）不得向生产 endpoint 泄测试会话 |
 
-集成测试 `apps/cli/tests/telemetry-web.e2e.ts`（keyless）钉住部署级行为：测试内 OTLP collector + mock LLM，真启动 `dsh web`，断言 ledger 覆盖、seq 单调、chunk 首条投影、以及 SIGINT drain 后 ops `shutdown` 标记到达。
+集成测试 `apps/cli/tests/telemetry-web.e2e.ts`（keyless）钉住部署级行为：测试内 OTLP collector + mock LLM（大语言模型）服务器，真启动 `dsh web`，断言 ledger 覆盖、seq 单调、步骤首个分片投影、以及 SIGINT drain 后 ops `shutdown` 标记到达。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-**默认不挂载，部署方自行加行（SDK 立场的延续）。** 否决于当前阶段：本仓的 web/headless 组合就是内部部署本身，「上报默认开」是这个部署的产品要求；SDK 立场仍由 seam 包保持（不挂 = 零外发）。
+**默认不挂载，部署方自行加行（SDK 立场的延续）。** 当前阶段不采用：本仓的 web/headless 组合就是内部部署本身，「上报默认开」是这个部署的产品要求；SDK 立场仍由 seam 包保持（不挂 = 零外发）。
 
 **开关做成 config 字段而非 env patch。** 不可行：cordis 行没有 config 层的 disable 语义，且 `exporter.url` 校验在插件构造期 fail-loud，开关必须在 Loader 之前生效——AppCLIEntry patch 层是唯一落点。
 
 **退出时 `Promise.race` 兜底超时。** 最初暂缓，是因为 SDK 参数看似已经将后端排空耗时限制在约 1.5-3s（通常 <100ms），实测 SIGINT 到退出耗时 110ms-1.1s。后来在 Linux 沙箱中复现并证明，`BatchLogRecordProcessor.shutdown()` 可能在 `exporter.forceFlush()` 中永久等待，无法进入受 `exportTimeoutMillis` 限制的完成 Promise。因此，[CLI 关闭修复](../bug-fix/2026-08-03-cli-signal-shutdown-escalation.md) 既为这一特定缺口增加 3 秒后端上限，也为整棵插件树增加 5 秒进程级上限和重复信号退出途径。
 
-## Consequences
+## 后果
 
 - 无本地 collector 的开发者跑 `dsh web` 会对生产 endpoint 每 10s 发一次 POST（联不通则静默失败，OTel diag logger 未注册）；本地开发设 `DSH_TELEMETRY_DISABLED=1` 或 `DSH_TELEMETRY_OTLP_URL` 指本地。
-- **当前零脱敏规则挂载**：导出即原始捕获副本（用户/助手消息全文、工具参数与结果、system prompt、`session.cwd` 本地路径）。跨信任边界前必须挂 `telemetry/record` 规则——脱敏规则、其余身份 Resource 维度（hostname/surface；匿名 user id 已由[匿名用户 id Note](2026-07-31-telemetry-anonymous-user-id.md)落地）、使用数据 metrics 轨是本决策明确的后续工作。
-- 复用这棵树的测试载具（如 `apps/web/tests/scaffold.ts`）须显式关停该行，否则 fixture 会话会流向 env 里碰巧存在的 collector。
+- **当前尚未挂载任何脱敏规则**：导出即原始捕获副本（用户/助手消息全文、工具参数与工具结果、系统提示词、`session.cwd` 本地路径）。跨信任边界前必须挂 `telemetry/record` 规则——脱敏规则、其余身份 Resource 属性（hostname/surface；匿名 user id 已由[匿名用户 id Note](2026-07-31-telemetry-anonymous-user-id.md)落地）、使用数据 metrics 轨是本决策明确的后续工作。
+- 复用这棵树的测试载具（如 `apps/web/tests/scaffold.ts`）须显式关停该行，否则 fixture（测试前置数据）会话会流向 env 里碰巧存在的 collector。
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index c1cc57b233..5cd3bd7aca 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
 2026-07-31-web-workspace-file-links.md: fe71a2d8caa4dc9cc732a250d7e388d1a3b44182
-2026-07-31-web-workspace-file-links.zh.md: 0f8c87822087169aad9ac4283f706fd8a8748be9
+2026-07-31-web-workspace-file-links.zh.md: a59ca5c6ba3a2c4aee9129deedfbb486cec082b2
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index 0f8c878220..a59ca5c6ba 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -1,30 +1,30 @@
-# Agent Note：从 web UI 打开产出的文件
+# Agent Note: 从 web UI 打开产出的文件
 
 Status: implemented
 
 [English](2026-07-31-web-workspace-file-links.md) | 中文
 
-> 范围：完成的一轮以其产出文件收尾的那一行、读得出是链接的文件路径链接，以及 Host 打开器对浏览器可渲染文档优先选用默认浏览器。经决定不在范围内：以 HTTP 提供工作区文件，以及为不在 Host 机器上的客户端提供预览。
+> 范围：完成的轮次以其产出文件收尾的那一行、读得出是链接的文件路径链接，以及 Host 打开器对浏览器可渲染文档优先选用默认浏览器。经决定不在范围内：以 HTTP 提供工作区文件，以及为不在 Host 机器上的客户端提供预览。
 
 ## 问题
 
-一个产出了文件的 web 会话，没有办法看到那个文件。agent 写出了 `deepseek-homepage.html` 并如实告知，而用户唯一的办法是把 `/private/tmp/dsh-client-hotplug.ygPvsm/workspaces/plugin-hotplug/deepseek-homepage.html` 这样的绝对路径复制进终端。
+一个产出了文件的 web 会话，没有办法看到那个文件。agent（智能体）写出了 `deepseek-homepage.html` 并如实告知，而用户唯一的办法是把 `/private/tmp/dsh-client-hotplug.ygPvsm/workspaces/plugin-hotplug/deepseek-homepage.html` 这样的绝对路径复制进终端。
 
-这背后是两个不同的缺陷。转录从不说明一轮产出了什么：`ToolCallView.locations`——文件工具早已填好的跟随文件词汇——在客户端没有任何消费方，因此读者对产出的唯一交代，就是收尾消息恰好拼出来的那点内容。而已经存在的那个交互是隐形的：`ToolRow` 早已把改写行或读取行的路径渲染成一个接到 `host.openPath` 的真按钮，但它的样式与周围正文一模一样、只有悬停才有下划线，于是没人发现。所报告的“做完了打不开”，是一个可发现性失败叠在一项本就可用的能力之上。
+这背后是两个不同的缺陷。transcript（文本记录）从不说明一个轮次产出了什么：`ToolCallView.locations`——文件工具早已填好的跟随文件词汇——在客户端没有任何消费方，因此读者对产出的唯一交代，就是收尾消息恰好拼出来的那点内容。而已经存在的那个交互是隐形的：`ToolRow` 早已把变更行或读取行的路径渲染成一个接到 `host.openPath` 的真按钮，但它的样式与周围正文一模一样、只有悬停才有下划线，于是没人发现。所报告的“做完了打不开”，是一个可发现性失败叠在一项本就可用的能力之上。
 
 ## 决定
 
-**完成的一轮以它产出的文件收尾。** 该行是独立插件 `@deepseek-ai/dsh-client-ui-deliverables`，注册进 chat 视图在收尾消息正文与其 IconActions 之间渲染的 `conversation.chat.turnTail` 空位——ui-conversation 拥有空位与 owner 通货（节点、收尾 seq、`openFile`），插件拥有全部策略。`producedForClosing` 从改写工具自身的跟随文件 `locations` 中读出路径——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，这一轮的产出都会被列出；新的改写工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。cordis.yml 中的一行即可把该交互面组合进来或去掉；未注册的空位什么也不渲染。
+**完成的轮次以它产出的文件收尾。** 该行是独立插件 `@deepseek-ai/dsh-client-ui-deliverables`，注册进 chat 视图在收尾消息正文与其 IconActions 之间渲染的 `conversation.chat.turnTail` 空位——ui-conversation 拥有该空位及其 owner 参数约定（节点、收尾 seq、`openFile`），插件拥有全部策略。`producedForClosing` 从变更工具自身的跟随文件 `locations` 中读出路径——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此无论收尾消息是否点名，该轮次的产出都会被列出；新的变更工具靠声明自己做了什么加入，而不是靠被加进某张名单。read、删除与失败的调用不贡献任何条目；同一路径在一个轮次内按首见顺序只出现一次；累积在轮次边界重置，因此一个轮次若先变更文件、随后没有正文内容就结束，不会溢进下一轮的行里。cordis.yml 中的一行即可把该交互面组合进来或去掉；未注册的空位什么也不渲染。
 
 **路径链接读得出是链接。** 静止状态下就带下划线，而不只在悬停时。这是本次改动中更小的那一半，却是修复中更大的那一半。
 
-**打开仍然是 Host 的职责，并且优先选用默认浏览器。** `host.openPath` 把路径交给操作系统，得到的是真实浏览器里的一份 `file://` 文档：页面能力完整，且够不到 `/api`——因为 `file://` 文档与它并不同源。在所报告的那份产物上实测：`localStorage` 可用、主题切换生效、tabs 可切换，而对 API 的 `fetch` 失败。对浏览器能渲染的文档——`.html`、`.htm`、`.xhtml`、`.svg`——平台能够确定默认浏览器时，打开器解析的是默认**浏览器**而非该类型的默认应用，因为把 `.html` 绑给编辑器的开发者，否则点开一个产出的页面得到的会是源码。macOS 读取 LaunchServices 的 `https` 处理程序，桌面 Linux 读取 `$BROWSER`；无法确定浏览器时，两者都会回退到默认应用。Windows 使用其注册的文件关联，WSL 则先转换路径，再使用同一 Windows 交接。
+**打开仍然是 Host 的职责，并且优先选用默认浏览器。** `host.openPath` 把路径交给操作系统，得到的是真实浏览器里的一份 `file://` 文档：页面能力完整，且够不到 `/api`——因为 `file://` 文档与它并不同源。在所报告的那份产物上实测：`localStorage` 可用、主题切换生效、tabs 可切换，而对 API 的 `fetch` 失败。对浏览器能渲染的文档——`.html`、`.htm`、`.xhtml`、`.svg`——平台能够确定默认浏览器时，打开器解析的是默认**浏览器**而非该类型的默认应用，否则，把 `.html` 绑给编辑器的开发者点开一个产出的页面，得到的会是源码。macOS 读取 LaunchServices 的 `https` 处理程序，桌面 Linux 读取 `$BROWSER`；无法确定浏览器时，两者都会回退到默认应用。Windows 使用其注册的文件关联，WSL 则先转换路径，再使用同一 Windows 交接。
 
 **以 HTTP 提供工作区文件不在范围内，非本机客户端亦然。** 更早的一版由 harness 自己提供文件——先是与 `/api` 同源，随后加上 `CSP: sandbox`，再后来交给一个以自身端口给所服务文档独立源的第二监听器。每一步都在回答一个真实问题，而整条线在产品范围定下之后被整体退役：不为“浏览器不在 Host 机器上”的场景提供预览。这一点定下之后，Host 打开器完整回答了受支持的场景，而那套 HTTP 机制回答的只是不受支持的那个。
 
 ## 考虑过的替代方案
 
-- **由 harness 提供 `/f/<sessionId>/<segments…>`**——已经实现并可用，包含双 `realpath` 收敛、浏览器信任 fence、流式读取，以及一个以自身端口给所服务文档独立源的监听器。它是唯一能把预览呈现给另一台机器上客户端的设计，而那恰恰是被判出范围的场景。因此退役，而不是因为它失败了；它的代价是一个带自身生命周期的第二 socket、一个注入页面的端口，以及一份跨两个包共享的 URL 形状契约。
+- **由 harness 提供 `/f/<sessionId>/<segments…>`**——已经实现并可用，包含通过双重 `realpath` 实现的路径约束、浏览器信任 fence、流式读取，以及一个以自身端口给所服务文档独立源的监听器。它是唯一能把预览呈现给另一台机器上客户端的设计，而那恰恰是被判出范围的场景。因此退役，而不是因为它失败了；它的代价是一个带自身生命周期的第二 socket、一个注入页面的端口，以及一份跨两个包共享的 URL 形状约定。
 - **同源 HTTP 提供且不加隔离**——经实测不安全，记录在此以免有人重试：与 `/api` 并排提供的文档把 `settings.describe` 打到 `200` 并拿到完整数据，把 `session.list` 打到 35 KB 的全部会话转录，而这个页面根本不必由 agent 撰写（一条 read 行就让 clone 下来的仓库里任何文件变得可打开）。
 - **在那套同源提供之上加 `Content-Security-Policy: sandbox`**——它以剥夺文档的源来堵住这个洞，而这经实测会破坏本功能存在的意义所在的那类页面：所报告的产物在加载时抛 `SecurityError`，又因为未捕获异常会中止其 `<script>` 的其余部分，该行之后声明的所有监听器——主题切换、移动端菜单、模型 tabs——统统不会绑定。报告者工作区里四份产物有两份在它之下是死页面，而且它们渲染得完美无缺，所以这种破坏是看不见的。
 - **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带，产出文件行消费的正是它。
@@ -32,4 +32,4 @@ Status: implemented
 
 ## 影响
 
-现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接可见性修复与浏览器优先策略无需逐行改动即适用于全部。无密钥 web 通道（`apps/web/tests/produced-files.e2e.ts`）冷播种一段录制的 write 轮次，在组装后的应用中钉住该行；它刻意不点击，因为点击会把路径交给 Host 打开器，从而在跑测试的机器上启动一个真实应用。产出的文件以 `file://` 文档打开，它无法 `fetch` 自己的同级文件（一个加载 `./data.json` 的多文件产物会坏，而 `<script src>`、`<img>` 与 CSS `@import` 不受影响）——这是 HTTP 提供曾有、而此处没有的那一项能力。经网络访问的客户端点击后看不到任何东西：`host.openPath` 在 Host 上运行，且被 `/api` 信任 fence 钉在回环。那是范围决定的显现，不是缺陷，也正因如此该行把完整路径保留在 `title` 中，供只能复制它的读者使用。markdown 会由平台交给 `.md` 的默认处理程序打开，通常是编辑器而非渲染器；在产品内渲染它是另一个被推迟的交互面。
+现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接可见性修复与浏览器优先策略无需逐行改动即适用于全部。无密钥 web 通道（`apps/web/tests/produced-files.e2e.ts`）冷播种一段录制的 write 轮次，在组装后的应用中钉住该行；它刻意不点击，因为点击会把路径交给 Host 打开器，从而在跑测试的机器上启动一个真实应用。产出的文件以 `file://` 文档打开，它无法 `fetch` 自己的同级文件（一个加载 `./data.json` 的多文件产物会坏，而 `<script src>`、`<img>` 与 CSS `@import` 不受影响）——这是 HTTP 提供曾有、而此处没有的那一项能力。经网络访问的客户端点击后看不到任何东西：`host.openPath` 在 Host 上运行，且被 `/api` 信任 fence 钉在回环。那是范围决定的显现，不是缺陷，也正因如此该行把完整路径保留在 `title` 中，供只能复制它的读者使用。Markdown 会由平台交给 `.md` 的默认处理程序打开，通常是编辑器而非渲染器；在产品内渲染它是另一个被推迟的交互面。
diff --git a/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.i18n.yaml
index 1104d3f1d7..4f102704e0 100644
--- a/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.md
 2026-07-31-workspace-write-surface-default.md: e6a36ad4ee7179cabf958114681728c3ac7340b4
-2026-07-31-workspace-write-surface-default.zh.md: 5ced928b167892d9abe1f4423da72a0243590735
+2026-07-31-workspace-write-surface-default.zh.md: fd18f2b69eb40df8392afb50892c7740d0e30af0
diff --git a/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.zh.md b/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.zh.md
index 5ced928b16..fd18f2b69e 100644
--- a/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 真正的新会话会在执行前固定 `permission/preset: workspace-write`、`sandbox/mode: workspace-write` 和 `approval/policy: ask`。现有会话和恢复的会话保留日志中记录的权限，更改「通用」设置中的默认值只影响之后创建的会话。浏览器保留 Access 选择器、可应答的审批卡片，以及选择 Full access 时的风险确认。共享 Permission 服务在 TUI 中激活其命令子件，因此 TUI 会获得现有的 `/permission` 命令。
 
-该模式只管辖文件效果。受沙箱约束的 bash 与文件系统修改只允许写入会话工作区和平台临时根目录；读取、网络访问与进程可见性仍不受该策略约束。若没有平台 runner 能强制执行受限的 bash 调用，执行会以拒绝方式关闭，不会退回不受限命令。
+该模式只管辖文件效果。受沙箱约束的 bash 与文件系统修改只允许写入会话工作区和平台临时根目录；读取、网络访问与进程可见性仍不受该策略约束。若没有平台 runner 能强制执行受限的 bash 调用，执行会以拒绝告终，不会退回不受限命令。
 
 ## 测试
 
@@ -26,10 +26,10 @@ Status: implemented
 
 **保留不受限的 TUI，只更改浏览器回退值。** 不予采纳，因为这会保留无法解释的界面差异，并让全新的终端会话继续拥有本决策要移除的权限。
 
-**在同一次变更中添加终端审批对话框。** 不予采纳，因为这是另一个交互与生命周期决策。TUI 没有 `approval/request` 应答者，因此一次性自动升权当前会落定为不可用并以拒绝方式关闭；需要更宽权限的用户可以通过 `/permission` 主动选择其他 preset。
+**在同一次变更中添加终端审批对话框。** 不予采纳，因为这是另一个交互与生命周期决策。TUI 没有 `approval/request` 应答者，因此一次性自动升权当前会落定为不可用并以拒绝告终；需要更宽权限的用户可以通过 `/permission` 主动选择其他 preset。
 
 ## 后果
 
 全新的会话无需额外提示即可修改当前工作区与临时根目录，尝试修改其他位置则会在触及目标前被拒绝。Full access 仍可通过显式选择获得，浏览器选择时也仍会显示确认对话框。系统不会重写已存储的用户默认值和会话日志中记录的权限。
 
-由浏览器支撑的无头入口继承 Web 组合，因此默认值相同。TUI 缺少审批应答者是本次变更的明确限制：自动请求更宽权限的重试会在那里以拒绝方式关闭，而不会显示权限询问。
+由浏览器支撑的无头入口继承 Web 组合，因此默认值相同。TUI 缺少审批应答者是本次变更的明确限制：自动请求更宽权限的重试会在那里以拒绝告终，而不会显示权限询问。
diff --git a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
index d4ec255235..a8bdc5b1d3 100644
--- a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.md
 2026-08-01-pwsh-tool-and-executor.md: 7206f8ffe6640f8499f8453c40ab5846b23112c6
-2026-08-01-pwsh-tool-and-executor.zh.md: 5a48adb79fed209d2d2ecb9514fd51538491f04c
+2026-08-01-pwsh-tool-and-executor.zh.md: bdc2563000a917cc1672a378c9e390354411c41c
diff --git a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
index 5a48adb79f..bdc2563000 100644
--- a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
@@ -6,30 +6,30 @@ Status: implemented
 
 ## 问题
 
-harness 在每个平台只说一种 shell 方言：`bash`。Windows 主机只能通过 WSL 或 Git-Bash 垫片运行它，而交付的 `dsh-bash-local` 执行器仅限 POSIX（硬编码 `bash`，进程组语义是 POSIX 的）。Windows 路线图——让主机默认 `pwsh`，之后再做 pwsh TUI/GUI 渲染——没有执行基础：既没有 bash 执行器 seam 的 PowerShell 实现，也没有教模型 PowerShell 方言的面向模型工具。bash 工具本身也远大于 Windows 优先画像所需：后台任务、沙箱升级与持久 PTY 孪生都是 bash 形状的表面，最小化的 `pwsh` 工具不该背负。
+harness 在每个平台只说一种 shell 方言：`bash`。Windows 主机只能通过 WSL 或 Git-Bash 垫片运行它，而交付的 `dsh-bash-local` 执行器仅限 POSIX（硬编码 `bash`，进程组语义是 POSIX 的）。Windows 路线图——让主机默认 `pwsh`，之后再做 pwsh TUI/GUI 渲染——没有执行基础：既没有 bash 执行器 seam 的 PowerShell 实现，也没有教模型 PowerShell 方言的面向模型工具。bash 工具本身也远大于 Windows 优先配置所需：后台任务、沙箱升级与持久 PTY 对应工具都是针对 bash 设计的功能面，最小化的 `pwsh` 工具不该背负。
 
 ## 决策
 
 在 `packages/bash/` 下新增两个包：
 
-- **`@deepseek-ai/dsh-pwsh-local`** —— `ctx.bash` 执行器 seam 的本地实现，基于 `ctx.subprocess`，逐调用镜像 `dsh-bash-local`：`resolve()` 从配置默认化并设上限，`run()` 通过一个 deadline 融合配置夹取的超时与调用方信号，`start()` 返回消费式后台句柄，其进程归属于 subprocess 服务。命令字符串作为 ONE argv 元素传给 `pwsh -NoLogo -NoProfile -NonInteractive -Command`，由 PowerShell 解析，不存在 shell 引号层。可执行文件解析（`resolvePwshPath`）是 `(configured, env, platform)` 的纯函数：先显式配置，再在 Windows 上探测 PowerShell 7 安装位置、PATH 条目（剥离引号）与 Windows PowerShell 5.1，否则经 PATH 解析裸 `pwsh`。
-- **`@deepseek-ai/dsh-tool-pwsh`** —— 基于 `ctx.bash` 的面向模型工具，契约是 PowerShell 方言，逐调用镜像 `dsh-tool-bash`、减去 sandbox 面：经通用任务运行时执行前台与 `run_in_background`，经共享 [`dsh-bash-env`](../feature/2026-08-02-pwsh-tool-bash-parity.md) 注册表管理 `DSH_*` 环境，以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。parity 决策取代了本 note 的最小画像工具描述。
+- **`@deepseek-ai/dsh-pwsh-local`** —— `ctx.bash` 执行器 seam 的本地实现，基于 `ctx.subprocess`，逐调用镜像 `dsh-bash-local`：`resolve()` 根据配置设置默认值和上限，`run()` 通过一个 deadline 融合受配置上限约束的超时与调用方信号，`start()` 返回消费式后台句柄，其进程归属于 subprocess 服务。命令字符串作为单个 argv 元素传给 `pwsh -NoLogo -NoProfile -NonInteractive -Command`，由 PowerShell 解析，不存在 shell 引号层。可执行文件解析（`resolvePwshPath`）是 `(configured, env, platform)` 的纯函数：先显式配置，再在 Windows 上探测 PowerShell 7 安装位置、PATH 条目（剥离引号）与 Windows PowerShell 5.1，否则经 PATH 解析裸 `pwsh`。
+- **`@deepseek-ai/dsh-tool-pwsh`** —— 基于 `ctx.bash` 的面向模型工具，约定是 PowerShell 方言，逐调用镜像 `dsh-tool-bash`、不含沙箱功能面：经通用任务运行时执行前台与 `run_in_background`，经共享 [`dsh-bash-env`](../feature/2026-08-02-pwsh-tool-bash-parity.md) 注册表管理 `DSH_*` 环境，以及 bash 的 marker/截断渲染机制（正常退出不产生 marker）。parity 决策取代了本 Agent Note 的最小配置工具描述。
 
-Windows vitest 覆盖率刻意不属本次改动：仓库的 Windows CI 通道负责构建/静态门禁，单元覆盖在 Linux 上运行，两个包的套件在那里以真实 `pwsh` 运行（GitHub 托管 runner 预装）或缺失时自行跳过。vitest 的 `windowsUnsupportedPackages` 排除从 `packages/bash/*` 收窄为真正需要 bash 的包，使 pwsh 套件也能在 Windows 开发机上原生运行。
+Windows vitest 测试覆盖刻意不纳入本次改动：仓库的 Windows CI 通道负责构建/静态门禁，单元覆盖在 Linux 上运行，两个包的套件在那里以真实 `pwsh` 运行（GitHub 托管 runner 预装）或缺失时自行跳过。vitest 的 `windowsUnsupportedPackages` 排除从 `packages/bash/*` 收窄为真正需要 bash 的包，使 pwsh 套件也能在 Windows 开发机上原生运行。
 
 本决策之后的路线图——让 Windows 主机默认 `pwsh`（关闭 bash）与 pwsh TUI/GUI 渲染——另行记录为[提案](../../proposed/feature/2026-08-01-windows-pwsh-default.md)。
 
 ## 备选方案
 
-**给 `dsh-bash-local` 增加 pwsh 模式。** 否决：执行器的身份就是它 spawn 的 shell；在一个包内塞第二种方言会翻倍配置面（`shell` 开关）与测试矩阵，且两种方言的怪癖（Windows 上的信号实情、引号域）应各自归入自己包的文档。
+**给 `dsh-bash-local` 增加 pwsh 模式。** 否决：执行器的身份就是它 spawn 的 shell；在一个包内塞第二种方言会翻倍配置面（`shell` 开关）与测试矩阵，且两种方言的怪癖（Windows 上的信号信息、引号域）应各自归入自己包的文档。
 
-**给 `dsh-tool-bash` 增加方言参数。** 否决：bash 工具的后台/沙箱表面是 bash 形状的；`pwsh` 模式要么隐藏它（条件 schema 翻动），要么继承它（把最小画像明确拒绝的表面带进来）。最小孪生让模型契约保持诚实。
+**给 `dsh-tool-bash` 增加方言参数。** 否决：bash 工具的后台任务与沙箱功能面都是针对 bash 设计的；`pwsh` 模式要么隐藏它（条件 schema 反复变动），要么继承它（把最小配置明确拒绝的功能面带进来）。精简版对应工具能让模型约定如实反映实际功能。
 
-**现在就接入交付的 CLI 组合。** 否决：在 Windows 默认决策落地前把 `tool-pwsh` + `pwsh-local` 挂进 `base.cordis.yml` 会改变交付清单；本改动交付能力与接线点（`apps/cli` 依赖、tsconfig 工程），不切换任何默认。
+**现在就接入交付的 CLI（命令行界面）组合。** 否决：在 Windows 默认决策落地前把 `tool-pwsh` + `pwsh-local` 挂进 `base.cordis.yml` 会改变交付清单；本改动交付能力与接入点（`apps/cli` 依赖、tsconfig 工程），不切换任何默认。
 
 ## 后果
 
-- bash 执行器 seam 有了第二个、Windows 原生的实现，请求/规范契约一致，因此 `tool-pwsh` 之外的面向模型消费方（hooks 桥、进程内插件）无需方言垫片即可运行 PowerShell。
-- `tool-pwsh` 是模型可见的 Windows 优先 shell 工具：在前台与后台工作（减 sandbox）上与 bash 工具行为可互换，提示词指导精确陈述 marker 契约。
-- Windows 语义在平台差异处不同：强制终止报告退出码 1 且无信号（因此 `signal`/`killed` 状态实情仅限 POSIX），PowerShell 输出 CRLF，测试做归一化。
-- CLI 增加两个 workspace 依赖与两个 tsconfig 工程，但不挂载任一插件——组合决策留给 Windows 默认提案。
+- bash 执行器 seam 有了第二个、Windows 原生的实现，请求/规范约定一致，因此 `tool-pwsh` 之外的面向模型消费方（钩子桥、进程内插件）无需方言垫片即可运行 PowerShell。
+- `tool-pwsh` 是模型可见的 Windows 优先 shell 工具：在前台与后台工作（不含沙箱功能）上与 bash 工具行为可互换，提示词指导精确陈述 marker 约定。
+- Windows 语义在平台差异处不同：强制终止报告退出码 1 且无信号（因此 `signal`/`killed` 状态信息仅限 POSIX），PowerShell 输出 CRLF，测试做归一化。
+- CLI 增加两个工作区依赖与两个 tsconfig 工程，但不挂载任一插件——组合决策留给 Windows 默认提案。
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
index 40e24e9ac2..174f5b98d1 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
 2026-08-02-pwsh-tool-bash-parity.md: e35a903892d5d50a0d3ca12b23daa53f26d6aade
-2026-08-02-pwsh-tool-bash-parity.zh.md: d7a68f0cab5281b25c3321e7ffff61c358b21a0a
+2026-08-02-pwsh-tool-bash-parity.zh.md: f4ee10484b6e49ebbaeb0b8ed4b0b30c5ac17e5c
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
index d7a68f0cab..f4ee10484b 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
@@ -6,31 +6,31 @@ Status: implemented
 
 ## 问题
 
-首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。对该变更的 review 发现模型可见契约与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
+首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台（每次调用启动一个新进程；无持久 PTY 会话）、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（「恒打 `[exit code: N]`」）。对该变更的 review 发现模型可见约定与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
 
 ## 决策
 
-`dsh-tool-pwsh` 现在逐调用镜像 `dsh-tool-bash`，减去 sandbox 面，其模型可见文本精确描述这一行为：
+`dsh-tool-pwsh` 现在逐调用镜像 `dsh-tool-bash`，沙箱相关接口除外，其模型可见文本精确描述这一行为：
 
-- **渲染完全采用 bash 故事**：stdout、带标记的 `[stderr]` 段、带 spill 路径的截断通知、空体渲染 `(no output)`、退出 marker 仅限非零退出——干净退出不产生 marker。描述与 `tool:pwsh` prompt section 精确陈述这一点（"Non-zero exits are reported as `[exit code: N]` markers"），刻意不复制 bash prompt 中与其自身渲染矛盾的 "every result" 措辞。
+- **渲染完全采用 bash 故事**：stdout、带标记的 `[stderr]` 段、带 spill 路径的截断通知、空体渲染 `(no output)`、退出 marker 仅限非零退出——干净退出不产生 marker。描述与 `tool:pwsh` 提示词 section 精确陈述这一点（"Non-zero exits are reported as `[exit code: N]` markers"），刻意不复制 bash 提示词中与其自身渲染矛盾的 "every result" 措辞。
 - **`run_in_background` 经通用任务运行时接线**，与 bash 工具完全一致：预检、owner 注册、`task_output`/`task_kill` 控制与相同的结果映射。其背后是 `pwsh-local` 早已镜像好的 `start()` 句柄。
 - **`DSH_*` 环境共享而非复制**：`BashEnvRegistry` 从 `dsh-tool-bash` 迁入新的工具无关包 `@deepseek-ai/dsh-bash-env`（`ctx.bashEnv` + 内置事实 + session-persistence contributor），两个 shell 工具都注入它。contributor 对 pwsh 调用与 bash 调用一视同仁；因此，共享环境的所有权不属于任何一个面向模型的 shell 工具。
-- **Windows 现实在 bash 无对应处钉死**：每条命令都在 UTF-8 输出 preamble 下运行，使 Windows PowerShell 5.1 兜底无法经 UTF-8 解码的 collector 破坏非 ASCII 输出；prompt 教授 Windows 强制终止以无 signal 的 exit 1 结算。
-- **范围外，不变**：sandbox 升级（等待 Windows-confining 执行器）与持久 PTY shell（后端仅限 Linux/macOS；ConPTY 属路线图）。带退出 pill 的 pwsh 专属 terminal 卡已随 [pwsh UI 呈现与 bash 对齐](2026-08-05-pwsh-ui-bash-parity.md) 决策另行交付。
+- **Windows 现实在 bash 无对应处钉死**：每条命令都在 UTF-8 输出 preamble 下运行，使 Windows PowerShell 5.1 兜底无法经 UTF-8 解码的 collector 破坏非 ASCII 输出；提示词说明：Windows 强制终止以 exit 1 结算，且不带 signal marker。
+- **范围外，不变**：沙箱升级（等待 Windows-confining 执行器）与持久 PTY shell（后端仅限 Linux/macOS；ConPTY 属路线图）。带退出 pill 的 pwsh 专属 terminal 卡已随 [pwsh UI 呈现与 bash 对齐](2026-08-05-pwsh-ui-bash-parity.md) 决策另行交付。
 
 ## 备选方案
 
-**保留最小画像，只修声明。** 否决：review 的核心发现是"从 bash 复制的文本契约在缺少对应实现时会漂移"；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
+**保留最小画像，只修声明。** 否决：review 的核心发现是「从 bash 复制的文本约定在缺少对应实现时会漂移」；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
 
-**在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对契约改由各工具 README 记录。
+**在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对约定改由各工具 README 记录。
 
 **提取完全共享的工具实现基座（抽象 shell 方言，两个薄叶子）。** 考虑后推迟：bash-env 提取与结构镜像（`render.ts`/`background.ts` 孪生）是它要立足的基础；在出现第三种方言或持久 PTY 孪生、让抽象的形态可观察之前，不做完整基座。
 
 ## 后果
 
-- bash 与 pwsh 工具在前台与后台 shell 工作（减 sandbox）上行为可互换，pwsh 的 prompt/描述句每句都有渲染器背书——reviewer 的“拿代码 grep 对证”检查通过。
-- 对齐也反向发生过一次：pwsh 工具的结构化前台中止（`HarnessError('tool call aborted', TOOL_ABORTED)`，name 为 `AbortError`）被回移到 bash 工具，取代其无码的 `Error('command aborted')`——这是模型可见/入日志的变更，由两侧的精确形状测试与 cancel-tool-calls fixture 钉住。
-- `@deepseek-ai/dsh-bash-env` 成为新的交付包；`dsh-tool-bash` 的 `dshHome` 配置迁往那里，因此挂载 shell 工具的组合也必须挂载 `bash-env`（spine bundle 已如此）。
+- bash 与 pwsh 工具在前台与后台 shell 工作（沙箱除外）上行为可互换，pwsh 的提示词/描述句每句都有渲染器背书——reviewer 的「拿代码 grep 对证」检查通过。
+- 对齐也反向发生过一次：pwsh 工具的结构化前台中止（`HarnessError('tool call aborted', TOOL_ABORTED)`，name 为 `AbortError`）被回移到 bash 工具，取代其无码的 `Error('command aborted')`——这是模型可见/入日志的变更，由两侧的精确形状测试与 cancel-tool-calls fixture（测试前置数据）钉住。
+- `@deepseek-ai/dsh-bash-env` 成为新的交付包；`dsh-tool-bash` 的 `dshHome` 配置迁往那里，因此挂载 shell 工具的组合也必须挂载 `bash-env`（主干组合包已如此）。
 - Windows 专属语义（CRLF 归一化、强制终止 exit-1/signal-null、仅 POSIX 的自信号）一如既往由测试钉住。
 - pwsh 工具的 per-file 覆盖门禁由可脚本化的 fake-executor 套件（`tests/tools.spec.ts`）承担；真实 pwsh 的集成与 Loader 组合套件在无 `pwsh` 的宿主自跳过，与 bash 套件的分工一致。
 - 路线图提案的 parity 阶段已交付；terminal 卡呈现阶段随 [pwsh UI 呈现与 bash 对齐](2026-08-05-pwsh-ui-bash-parity.md) 决策交付（TUI 本身已移除），剩余阶段是 Windows 默认组合。
diff --git a/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.i18n.yaml
index d191e3926d..fd479c217e 100644
--- a/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.md
 2026-08-02-session-search-not-shipped-default.md: 65bd72fff76210b726e7562fb8e88e5f8802434a
-2026-08-02-session-search-not-shipped-default.zh.md: 5e42a2c2323904117f9322b5c4a53c43c6ed3f2a
+2026-08-02-session-search-not-shipped-default.zh.md: 4eb0851c1e584b84847b6bb5118c8bb2f3156845
diff --git a/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.zh.md b/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.zh.md
index 5e42a2c232..4eb0851c1e 100644
--- a/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.zh.md
@@ -6,20 +6,20 @@ Status: implemented
 
 ## 问题
 
-[交付清单决策](2026-07-31-even-out-shipped-tool-rosters.md)把 `tool-session-query` 设为共享 [`cordis.patch.yml`](../../../../packages/bundle/base/cordis.patch.yml) 的默认行,于是交付的 TUI 与 Web surface 把这五个会话搜索工具(`session_search`、`session_event_search`、`session_trace`、`session_event_trace`、`session_event_read`)呈现给了模型。这与[面向模型的会话查询工具决策](2026-07-24-model-facing-session-query-tools.md)相抵触,该决策持需显式启用的立场,包 README 将其记录为「shipped host compositions do not mount it by default」。这份默认还交付了一个提示词段,向模型讲授一套既往工作搜索工作流,而没有任何用户要求过。
+[交付清单决策](2026-07-31-even-out-shipped-tool-rosters.md)把 `tool-session-query` 设为共享 [`cordis.patch.yml`](../../../../packages/bundle/base/cordis.patch.yml) 的默认行，于是交付的 TUI 与 Web surface 把这五个会话搜索工具（`session_search`、`session_event_search`、`session_trace`、`session_event_trace`、`session_event_read`）呈现给了模型。这与[面向模型的会话查询工具决策](2026-07-24-model-facing-session-query-tools.md)相抵触，该决策持需显式启用的立场，包 README 将其记录为「shipped host compositions do not mount it by default」。这项默认设置还交付了一个提示词段，向模型讲授一套既往工作搜索工作流，而没有任何用户要求过。
 
 ## 决策
 
-交付的 TUI、Web 与无头 surface 不再挂载 `@deepseek-ai/dsh-tool-session-query`:该行从共享的 `cordis.patch.yml` 移除,opt-in 的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) profile 中那条已悬空的 `disabled` patch 也随之删除,workspace 依赖也从 `apps/cli/package.json` 中移除。该消费方仍保持 opt-in,与面向模型的会话查询工具决策所述完全一致:ACP 示例的 [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) 及其快照对侧文件仍是挂载参考,自定义组合也可以连同超时与 spill 策略一起挂载该包。
+交付的 TUI、Web 与无头 surface 不再挂载 `@deepseek-ai/dsh-tool-session-query`：该行从共享的 `cordis.patch.yml` 移除，opt-in 的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) profile 中那条已悬空的 `disabled` patch 也随之删除，workspace 依赖也从 `apps/cli/package.json` 中移除。该消费方仍保持 opt-in，与面向模型的会话查询工具决策所述完全一致：ACP（Agent Client Protocol）示例的 [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) 及其快照对侧文件仍是挂载参考，自定义组合也可以连同超时与 spill 策略一起挂载该包。
 
-`ctx.sessionQuery` 服务本身保持挂载。`session-query-sqlite` 仍是 base 的一行,TUI 的 `session-reference` 消费它来实现 `/resume`,Web overlay 也继续把它 patch 成内存索引,供浏览器内容搜索使用。被移除的只有面向模型的消费方。
+`ctx.sessionQuery` 服务本身保持挂载。`session-query-sqlite` 仍是 base 的一行，TUI 的 `session-reference` 消费它来实现 `/resume`，Web overlay 也继续把它 patch 成内存索引，供浏览器内容搜索使用。被移除的只有面向模型的消费方。
 
 ## 曾考虑的替代方案
 
-- **把 `session-query-sqlite` 索引也一并移除**——否决,因为 `/resume` 和 Web 内容搜索框直接消费 `ctx.sessionQuery`;它们是宿主功能,不是模型工具,移除提供方会破坏它们。
-- **保留该行,但在每个 overlay 中禁用它**——否决,因为一条被禁用的 base 行仍会交付依赖,而且一行就能轻易重新启用;已记录的 opt-in 立场要求消费方不出现在交付的 surface 上,以 ACP 示例作为挂载参考。
-- **只在 TUI 上挂载**——否决,因为共享 base 是所有 surface 共用的一组行;surface 专属挂载会重新引入交付清单决策所消除的清单分裂。
+- **把 `session-query-sqlite` 索引也一并移除**——否决，因为 `/resume` 和 Web 内容搜索框直接消费 `ctx.sessionQuery`；它们是宿主功能，不是模型工具，移除提供方会破坏它们。
+- **保留该行，但在每个 overlay 中禁用它**——否决，因为一条被禁用的 base 行仍会交付依赖，而且一行就能轻易重新启用；已记录的 opt-in 立场要求消费方不出现在交付的 surface 上，以 ACP 示例作为挂载参考。
+- **只在 TUI 上挂载**——否决，因为共享 base 是所有 surface 共用的一组行；surface 专属挂载会重新引入交付清单决策所消除的清单分裂。
 
 ## 后果
 
-两个 surface 都回到同样的二十个无条件工具(ripgrep 可用时再加上 `glob`/`grep`),五个会话搜索 schema 及其提示词段也一并退出默认请求。两个 surface 上的交付组合测试都固定这份更小的目录,因此把会话搜索重新作为默认加回会触及同样的测试。想要会话搜索的用户从个人 overlay 或 ACP 示例挂载该消费方,并在挂载处添加依赖。
+两个 surface 都回到同样的二十个无条件工具（ripgrep 可用时再加上 `glob`/`grep`），五个会话搜索 schema 及其提示词段也一并退出默认请求。两个 surface 上的交付组合测试都固定这份更小的目录，因此把会话搜索重新作为默认加回会触及同样的测试。想要会话搜索的用户从个人 overlay 或 ACP 示例挂载该消费方，并在挂载处添加依赖。
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
index c12de68dc8..09ca7ae1aa 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
 2026-08-02-web-thinking-tail-scroll.md: 18e94b2e0075bf7099b9b48177de2e274896942a
-2026-08-02-web-thinking-tail-scroll.zh.md: 9b1428af7d3ab3c25509696619de75adc1cd7b7f
+2026-08-02-web-thinking-tail-scroll.zh.md: 494fc10c5a05e989fd5ea868bf6f2fd1e17c0add
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
index 9b1428af7d..494fc10c5a 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：Web 思考尾部滚动 —— 折叠态 reasoning 跟随实时输出
+# Agent Note: Web 思考尾部滚动——折叠态推理跟随实时输出
 
 Status: implemented
 
@@ -6,26 +6,26 @@ Status: implemented
 
 ## 问题
 
-Web Think 行在结算与流式 block 中都把 reasoning 首行渲染成折叠摘要。首行一旦出现，之后每个 reasoning delta 只会改变隐藏的正文。于是快速模型在思考时看起来静止，用户必须展开完整思维链才能确认输出仍在推进。产品事项表已经要求“thinking：滚动展示思维链更新、可展开”；当前行只满足了后半项。
+Web Think 行在已结算块和流式块中都把推理（reasoning）首行渲染成折叠摘要。首行一旦出现，之后每个推理 delta 只会改变隐藏的正文。于是快速模型在思考时看起来静止，用户必须展开完整思维链才能确认输出仍在推进。产品事项表已经要求“thinking：滚动展示思维链更新、可展开”；当前行只满足了后半项。
 
 ## 决策
 
-只有 reasoning block 是当前流式尾部、且仍处于折叠态的 Think 行会跟随实时输出。其摘要使用最新的非空行，而不是结算后的首行；已有单行摘要元素成为程序化横向滚动区，每次文本更新后钉到 `scrollWidth - clientWidth`。这里刻意直接赋值 `scrollLeft`，通过真实 delta 推进而不虚构独立的跑马灯速度：token 快则移动快，模型停顿则停止，短文本因滚动范围为零而保持静止。
+只有推理块是当前流式尾部、且仍处于折叠态的 Think 行会跟随实时输出。其摘要使用最新的非空行，而不是结算后的首行；已有单行摘要元素成为程序化横向滚动区，每次文本更新后钉到 `scrollWidth - clientWidth`。这里刻意直接赋值 `scrollLeft`，通过真实 delta 推进而不虚构独立的跑马灯速度：token 快则移动快，模型停顿则停止，短文本因滚动范围为零而保持静止。
 
-该行为由已有呈现组件拥有。`AssistantMarkdown` 只在 Think 行运行时选择最新行；`ToolRow` 已经拥有折叠／展开状态，因此由它决定摘要是否追随行内末端。不改变 session、wire、持久事件或模型可见契约。展开会移除折叠摘要，并让完整 reasoning 正文进入普通页面流。该行结算后恢复稳定首行，同时把摘要重置到左端。其他工具摘要与已结算 Think 行保留已有省略号行为。
+该行为由已有呈现组件负责。`AssistantMarkdown` 只在 Think 行运行时选择最新行；`ToolRow` 已经负责管理折叠、展开状态，因此由它决定摘要是否追随行内末端。不改变会话、协议格式（wire format）、持久事件或模型可见约定。展开会移除折叠摘要，并让完整推理正文进入普通页面流。该行结算后恢复稳定首行，同时把摘要重置到左端。其他工具摘要与已结算 Think 行保留已有省略号行为。
 
 ## 曾考虑的替代方案
 
 **播放与流式输出无关的 CSS 跑马灯。** 否决：它会在 provider 停顿时继续移动，让慢模型显得很快，破坏该交互本应暴露的吞吐信号。
 
-**始终显示完整 reasoning 字符串的固定后缀。** 否决：按字符切片可能截断单词或字素，在内容真正溢出前就丢掉当前行的开头，而且只会跳变，无法随每个 delta 移动。
+**始终显示完整推理字符串的固定后缀。** 否决：按字符切片可能截断单词或字素，在内容真正溢出前就丢掉当前行的开头，而且只会跳变，无法随每个 delta 移动。
 
-**自动滚动展开的 reasoning 正文或会话页面。** 否决：展开内容是阅读界面，强制跟随会与向上回看的用户争夺滚动；跟随器只属于折叠的单行摘要。
+**自动滚动展开的推理正文或会话页面。** 否决：展开内容是阅读界面，强制跟随会与向上回看的用户争夺滚动；跟随器只属于折叠的单行摘要。
 
 ## 后果
 
-折叠行现在会同时通过内容移动和已有扫光传达 provider 节奏，而结算后的 transcript 保持逐字节稳定。滚动更新只发生在流式累加器本就会触发的 React 渲染中；不会增加计时器、动画循环、订阅、持久状态或传输流量。较长的当前 reasoning 行仍会把完整文本留在 DOM 中，只以编程方式裁掉已经溢出的前缀，因此展开仍能显示完整 block，辅助技术读到的也仍是同一份当前摘要文本。
+折叠行现在会同时通过内容移动和已有扫光传达提供方节奏，而结算后的 transcript（文本记录）保持逐字节稳定。滚动更新只发生在流式累加器本就会触发的 React 渲染中；不会增加计时器、动画循环、订阅、持久状态或传输流量。较长的当前推理行仍会把完整文本留在 DOM 中，只以编程方式裁掉已经溢出的前缀，因此展开仍能显示完整 block，辅助技术读到的也仍是同一份当前摘要文本。
 
 ## 测试
 
-`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的 keyless 完整 Chromium 场景以可观察节奏回放真实录制的 reasoning chunks，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态 replay golden 保持不变，证明历史摘要契约仍然稳定。
+`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的无密钥场景会在 Chromium 中运行组装后的 Web 应用，以可观察的节奏回放真实录制的推理分片，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态回放的预期输出保持不变，证明历史摘要约定仍然稳定。
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
index b98c2bee56..97a03bb17b 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
 2026-08-02-win32-in-process-folder-dialog.md: 5389293605169ce5ca269a127de5f609b8b7dd11
-2026-08-02-win32-in-process-folder-dialog.zh.md: ef81bc1f65b2859de1eb60f74f79e4869da4746b
+2026-08-02-win32-in-process-folder-dialog.zh.md: db4a6503f37f4b9cc95ce79ab8f476aeedfe5a60
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
index ef81bc1f65..db4a6503f3 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：Win32 文件夹选择器迁至 koffi 子进程
+# Agent Note: Win32 文件夹选择器迁至 koffi 子进程
 
 Status: implemented
 
@@ -6,22 +6,22 @@ Status: implemented
 
 ## 问题
 
-Windows 目录选择器的主层此前是围绕 WinForms `FolderBrowserDialog` 的外部 PowerShell 脚本：只有恰好安装了 PowerShell 7 的机器才有现代对话框；review 指出的回归——PowerShell 6 可解析却没有 WinForms（退出码 1 而非 `ENOENT`，5.1 回退永远不会触发）；`SetProcessDPIAware` 只有系统 DPI 的上限；选择器的行为取决于机器装了哪些 shell，而不是取决于 Windows 本身。
+Windows 目录选择器的主层此前是围绕 WinForms `FolderBrowserDialog` spawn 出的 PowerShell 脚本：只有恰好安装了 PowerShell 7 的机器才有现代对话框；review 指出的回归——PowerShell 6 可解析却没有 WinForms（退出码 1 而非 `ENOENT`，5.1 回退永远不会触发）；`SetProcessDPIAware` 只有系统 DPI 的上限；选择器的行为取决于机器装了哪些 shell，而不是取决于 Windows 本身。
 
 ## 决策
 
-`packages/host/directory-picker-native` 现在经 koffi——它已是仓库其他 `win32.ts` 面的工作区依赖——在进程内打开 `IFileOpenDialog`（`FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_NOCHANGEDIR`），作为 win32 主层。COM 会话运行在 spawn 出的子进程中，模态 `Show` 永不阻塞宿主事件循环；子进程在阻塞前上报其原生线程 id，driver 通过向该线程的窗口反复投递 `WM_CLOSE`（`EnumThreadWindows`）来服务中止，关闭预算耗尽时 kill 子进程。对话框是子进程的第一个窗口，Windows 会自动激活它，无需手动前台调用。子进程线程启用宿主接受的最佳线程 DPI 感知（`SetThreadDpiAwarenessContext`，按 per-monitor-v2 → per-monitor → system-aware 级联并检查返回值），严格优于脚本的系统 DPI 上限；DPI 保持为纯外观的 best-effort——全部不被接受的宿主仍得到现代对话框，而不会降级。模块切分让覆盖率在任何主机上都诚实：`win32-dialog-logic.ts`（纯时序）与 `win32-dialog.ts`（driver）在任何平台对假件测试；`win32-dialog-bindings.ts` 对 mock 的 `koffi` COM 世界测试（`dsh-session-persistence-jsonl` 的技法）；POSIX 主机把真实 spawn 管道跑到 koffi 加载失败的拒绝；win32 主机跑真实的"打开并中止关闭"冒烟。先于本层存在的 PowerShell 链已被删除（见[链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）：该层无回退。
+`packages/host/directory-picker-native` 现在经 koffi——它已是仓库其他 `win32.ts` 代码的工作区依赖——在进程内打开 `IFileOpenDialog`（`FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_NOCHANGEDIR`），作为 win32 主层。COM 会话运行在 spawn 出的子进程中，模态 `Show` 永不阻塞宿主事件循环；子进程在阻塞前上报其原生线程 id，driver 通过向该线程的窗口反复投递 `WM_CLOSE`（`EnumThreadWindows`）来处理中止请求，关闭预算耗尽时 kill 子进程。对话框是子进程的第一个窗口，Windows 会自动激活它，无需手动前台调用。子进程线程启用宿主接受的最佳线程 DPI 感知（`SetThreadDpiAwarenessContext`，按 per-monitor-v2 → per-monitor → system-aware 级联并检查返回值），严格优于脚本的系统 DPI 上限；DPI 保持为纯外观的 best-effort——不接受其中任何一种的宿主仍得到现代对话框，而不会降级。模块切分让覆盖率在任何主机上都诚实：`win32-dialog-logic.ts`（纯时序）与 `win32-dialog.ts`（driver）在任何平台对假件测试；`win32-dialog-bindings.ts` 对 mock 的 `koffi` COM 世界测试（`dsh-session-persistence-jsonl` 的技法）；POSIX 主机运行真实的 spawn 管道，并验证其因 koffi 加载失败而拒绝；win32 主机跑真实的「打开并中止关闭」冒烟测试。先于本层存在的 PowerShell 链已被删除（见[链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）：该层无回退。
 
 ## 考虑过的替代方案
 
-- **预编译原生助手（`native/` 家族，如 `@deepseek-ai/node-addon-landlock-run`）。** 否决：再增加一个 npm 包家族、MSVC 供给和 Windows 构建／发布通道——只为交付约 150 行目前无法在 CI 中执行的 C（现有 CI 没有真 Windows 通道）；koffi 以零新增供应链提供同一 COM 面。
-- **N-API 进程内插件。** 否决：同样的 CI／工具链原因，另加需要自有 C++ 处理 STA 线程与消息泵，而子进程 + koffi 用 TypeScript 就能表达。
-- **保留 PowerShell 为主层并探测版本。** 否决：选择器仍被 shell 打包形态挟持（6 与 7、Store 别名、profile），且没有 pwsh 的机器地板仍是 5.1 的旧版对话框；仅把回退触发条件的拓宽吸收进回退层。
+- **预编译原生辅助程序（`native/` 家族，如 `@deepseek-ai/node-addon-landlock-run`）。** 否决：再增加一个 npm 包家族、MSVC 环境配置和 Windows 构建／发布通道——只为交付约 150 行仓库目前无法通过 CI 检验的 C 代码（现有 CI 没有真 Windows 通道）；koffi 以零新增供应链提供同一 COM 接口。
+- **N-API 进程内插件。** 否决：同样的 CI／工具链原因，还需自行维护处理 STA 线程与消息泵的 C++ 代码，而子进程 + koffi 用 TypeScript 就能表达。
+- **保留 PowerShell 为主层并探测版本。** 否决：选择器仍被 shell 打包形态挟持（6 与 7、Store 别名、profile），且没有 pwsh 的机器仍只能使用 5.1 的旧版对话框；只有拓宽回退触发条件这一项改动被纳入了回退层。
 - **在主线程上阻塞模态调用。** 直接否决：对话框打开期间 web 宿主必须继续服务 RPC。
 
 ## 后果
 
 - 每台 Windows 机器都得到带其所支持的最佳 DPI 感知（1703+ 为 per-monitor-v2）的现代对话框，无论是否安装 PowerShell。
-- 真实对话框渲染与选中路径仍是手动 Windows 检查（自动关闭冒烟证明打开／中止／收尾）。
-- 所用 COM vtable 槽位与 GUID 是冻结的 Windows ABI（Vista 起）；koffi 签名错误可能引发原生访问冲突，但被限制在对话框子进程内——宿主 Node 进程存活，失败原样上报（无回退层；见[链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）。mocked-koffi 的 ABI 钉与真实 win32 冒烟正是为了在交付前捕获这类错误。
-- 打包二进制的臂——打包后的可执行文件以对话框入口形式自我 spawn——不受任何自动化测试覆盖：源码平面与普通 node 下构建出的 `lib/worker.cjs` 已被覆盖，打包 spawn 推迟到 Windows CI 路线图。
+- 真实对话框渲染与选中路径仍是手动 Windows 检查（自动关闭冒烟测试证明打开／中止／收尾）。
+- 所用 COM vtable 槽位与 GUID 是冻结的 Windows ABI（Vista 起）；koffi 签名错误可能引发原生访问冲突，但被限制在对话框子进程内——宿主 Node 进程存活，失败原样上报（无回退层；见[链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）。mocked-koffi 的 ABI 钉与真实 win32 冒烟测试正是为了在交付前捕获这类错误。
+- 打包二进制路径——打包后的可执行文件以对话框入口形式自我 spawn——不受任何自动化测试覆盖：源码侧与普通 node 下构建出的 `lib/worker.cjs` 已被覆盖，打包 spawn 推迟到 Windows CI 路线图。
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
index 98500c284e..f0dba56167 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
 2026-08-03-fs-tool-error-remedy.md: f227c31365725652b130e097d70c79d3daab3684
-2026-08-03-fs-tool-error-remedy.zh.md: 11acd0cf48924833ced91591d5ea1424735969cd
+2026-08-03-fs-tool-error-remedy.zh.md: ed3cbcf9c262db44321036fc1afcc829a5696b2f
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
index 11acd0cf48..ed3cbcf9c2 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
@@ -1,32 +1,32 @@
-# Agent Note: Guarded-mutation errors append the recovery instruction at the model boundary
+# Agent Note: 受防护变更错误在模型边界追加恢复指令
 
 Status: implemented
 
 [English](2026-08-03-fs-tool-error-remedy.md) | 中文
 
-## Problem
+## 问题
 
-受防护的 `write` 与 `edit` 失败以只陈述条件、不给出唯一正确恢复方式的消息到达模型：`FS_STALE_VERSION`（"file changed since it was read"）与 `FS_NOT_OBSERVED`（"edit requires reading … first"）。模型必须自行猜测恢复方式是重新读取（或首次读取）后重试，而基于结构化错误码路由的重试/权限/UI 层看到的也是同一段消息文本。提供方拥有的消息属于存储接缝的面向机器词汇（[filesystem capability seam](../architecture/2026-06-17-filesystem-capability-seam.md)），因此恢复指令不能放在那里，否则会把面向模型的措辞泄漏给 `FsError` 的每个消费者。
+受防护的 `write` 与 `edit` 失败以只陈述条件、不给出唯一正确恢复方式的消息到达模型：`FS_STALE_VERSION`（"file changed since it was read"）与 `FS_NOT_OBSERVED`（"edit requires reading … first"）。模型必须自行猜测恢复方式是重新读取（或首次读取）后重试，而基于结构化错误码路由的重试/权限/UI 层看到的也是同一段消息文本。提供方拥有的消息属于存储 seam 的面向机器词汇（[文件系统能力 seam](../architecture/2026-06-17-filesystem-capability-seam.md)），因此恢复指令不能放在那里，否则会把面向模型的措辞泄漏给 `FsError` 的每个消费方。
 
-## Decision
+## 决策
 
-`dsh-tool-fs` 拥有一个面向模型的错误包装 `remediateFsError`（位于 `src/error.ts`），在 `write.ts` 与 `edit.ts` 中于沙箱拒绝映射之后应用。它为两个受防护变更错误码追加恢复指令，其余错误原样透传：
+`dsh-tool-fs` 拥有一个面向模型的错误包装层 `remediateFsError`（位于 `src/error.ts`），在 `write.ts` 与 `edit.ts` 中于沙箱拒绝映射之后应用。它为两个受防护变更错误码追加恢复指令，其余错误原样透传：
 
 - `FS_STALE_VERSION`（包括缺失的编辑目标——它与陈旧错误共用同一错误码）追加 `— re-read the file, then retry`。
 - `FS_NOT_OBSERVED` 追加 `— read the file, then retry`。
 
 结构化 `FsError` 错误码保持不变，使重试/权限/UI 层继续基于它路由；原始错误作为 `cause` 链入。提供方消息保持面向机器且不变。
 
-在 `edit.ts` 中，`fs/edit-intent` waterfall 现在与提供方变更位于同一个 `try` 内，因此策略插件从 intent 槽抛出的 `FS_NOT_OBSERVED` 拒绝也会获得恢复指令——两条拒绝路径都以相同的恢复措辞到达模型。
+在 `edit.ts` 中，`fs/edit-intent` waterfall（瀑布式事件）现在与提供方变更位于同一个 `try` 内，因此策略插件从 intent slot抛出的 `FS_NOT_OBSERVED` 拒绝也会获得恢复指令——两条拒绝路径都以相同的恢复措辞到达模型。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-- **在 `dsh-fs` / `dsh-fs-local` 的提供方消息中追加恢复指令。** 被拒绝：这些消息是面向机器的接缝词汇，除模型表面外还被重试、权限与 UI 层消费；面向模型的措辞应位于模型边界，即 `dsh-tool-fs` 已经拥有结果格式化之处（[filesystem capability seam](../architecture/2026-06-17-filesystem-capability-seam.md)）。
+- **在 `dsh-fs` / `dsh-fs-local` 的提供方消息中追加恢复指令。** 被拒绝：这些消息是面向机器的 seam 词汇，除面向模型的接口外还被重试、权限与 UI 层消费；面向模型的措辞应位于模型边界，即 `dsh-tool-fs` 已经拥有结果格式化之处（[文件系统能力 seam](../architecture/2026-06-17-filesystem-capability-seam.md)）。
 - **改为在提示词引导中加入恢复方式。** 被拒绝：失败发生在任务中途；静态指令无法可靠地影响重试决策，而错误消息恰好在模型必须行动时出现。
-- **用新的 `FsError` 错误码表达恢复指令。** 被拒绝：这两种失败本就是重试层已处理的相同条件；拆分错误码会让语义相同的路由分叉。
+- **用新的 `FsError` 错误码表达恢复指令。** 被拒绝：这两种失败对应的条件，重试层本就已经处理；拆分错误码会使相同语义采用不同路由。
 
-## Consequences
+## 后果
 
-两个错误码的模型可见文本发生变化；`fs-policy-reject` 无密钥快照被重新录制，`dsh-tool-fs` 与 `dsh-fs-policy` 的 README 逐字固定追加后的文本。单元测试直接覆盖包装器（恢复指令文本、错误码保留、cause 链、其他错误码与非 `FsError` 值的透传），组装后的工具路径断言两个错误码的恢复指令都到达模型。
+两个错误码的模型可见文本发生变化；`fs-policy-reject` 无密钥快照被重新录制，`dsh-tool-fs` 与 `dsh-fs-policy` 的 README 逐字固定追加后的文本。单元测试直接覆盖包装层（恢复指令文本、错误码保留、cause 链、其他错误码与非 `FsError` 值的透传），组装后的工具路径断言两个错误码的恢复指令都到达模型。
 
-恢复指令不是承诺：已删除的观察目标无法被解除阻塞，因为重新读取缺失文件会以 `FS_NOT_FOUND` 失败且不记录观察。这一死胡同在集成测试中以 fail-closed 方式固定——在目标重新存在并被新鲜观察之前，重试的变更以相同方式失败。
+恢复指令不是承诺：已观察但被删除的目标无法被解除阻塞，因为重新读取缺失文件会以 `FS_NOT_FOUND` 失败且不记录观察。这一死胡同在集成测试中以 fail-closed 方式固定——在目标重新存在并被重新观察之前，重试的变更以相同方式失败。
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
index 2ba0af23c4..35628efcfe 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
 2026-08-03-web-search-source-scroll.md: 3215302b2f6c7a4e6d6cd7440a0c7f5048b72a80
-2026-08-03-web-search-source-scroll.zh.md: cf75a5e34632872d09a13e1667ecac5f01428e18
+2026-08-03-web-search-source-scroll.zh.md: 7d644b9e3950906b97d382e997eb3b204a577326
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
index cf75a5e346..7d644b9e39 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
@@ -4,43 +4,43 @@ Status: implemented
 
 [English](2026-08-03-web-search-source-scroll.md) | 中文
 
-## Problem
+## 问题
 
-`web_search` 结果卡片（`WebBlock`，`packages/client/ui-primitives/src/WebBlock.tsx`）此前用首尾折叠渲染它的来源列表：超过 `maxSources` 数量（详情面板为 16，聊天行经由 `CHAT_WEB_MAX_SOURCES` 为 8）时，它画出前 `ceil(max/2)` 条来源、一个 `… 其余 N 条来源` 展开按钮，再画出末尾 `max - ceil(max/2)` 条，与 `TerminalBlock` 的输出上限一致。用户阅读该卡片时看到 `来源列表已截断`，会以为前端丢弃了它正持有的来源。
+`web_search` 结果卡片（`WebBlock`，`packages/client/ui-primitives/src/WebBlock.tsx`）此前用首尾折叠渲染它的来源列表：超过 `maxSources` 数量（详情面板为 16，聊天行经由 `CHAT_WEB_MAX_SOURCES` 为 8）时，它画出前 `ceil(max/2)` 条来源、一个 `… 其余 N 条来源` 展开按钮，再画出末尾 `max - ceil(max/2)` 条，仿照 `TerminalBlock` 的输出上限机制。用户阅读该卡片时看到 `来源列表已截断`，会以为前端丢弃了它正持有的来源。
 
 其实并没有。seam（`capSources`，`packages/web/web/src/index.ts`）把 provider 的来源裁剪到工具的 `searchMaxResults` 上限（默认 8）并置位 `truncated`，而这一份被裁剪过一次的列表同时喂给面向模型的 render 文本与卡片的 `presentationMeta`。卡片持有的来源绝不会多于这一次裁剪的产物。因此这个折叠隐藏的正是用户本有权完整查看的来源——并且在默认上限为 8、面板上限为 16 时，它几乎从不触发，只留下 `truncated` 提示，却无从展开任何内容。
 
-## Decision
+## 决策
 
 `WebBlock` 的 search 分支把它收到的每一条来源都渲染进单个 `<ol className={css.sources}>`，不做首尾切片、不设展开按钮、也不带 `maxSources` prop。`.sources`（`WebBlock.module.css`）获得一个固定的 `max-height` 与 `overflow-y: auto`，因此长于卡片高度的列表在原地滚动，而非撑大卡片或隐藏行。该高度是卡片几何形状的一个设计常量，因此放在 CSS 里，而非插件配置字段。
 
 模型侧不变：seam 仍在 `searchMaxResults` 处封顶来源，面向模型的 render 文本未动，`truncated` 标志及其 `来源列表已截断` 指示保留。卡片完整且可滚动地画出 seam 产出的这份列表，而非折叠其中段。
 
-只要工具下游没有单独改写结果 content，这份列表就是模型读到的那份。挂载了 `dsh-spill-policy` 的部署会对超限结果打破这一对应：`tools/post-execute` 把面向模型的 `content` 替换为预览加 spill 定位符，而 `presentationMeta` 原样保留，因此卡片仍画出全部来源，模型读到的却是一段有界摘录。所以卡片的契约是它收到的 view，不是模型的上下文。
+只要工具下游没有单独改写结果 content，这份列表就是模型读到的那份。挂载了 `dsh-spill-policy` 的部署会对超限结果打破这一对应：`tools/post-execute` 把面向模型的 `content` 替换为预览加 spill 定位符，而 `presentationMeta` 原样保留，因此卡片仍画出全部来源，模型读到的却是一段有界摘录。所以卡片的约定是它收到的 view，不是模型的上下文。
 
 `CHAT_WEB_MAX_SOURCES` 与该 primitive 的 `DEFAULT_WEB_MAX_SOURCES` 被移除：有了滚动，聊天行与详情面板展示同一份完整列表，仅以各自的容器高度区分。`<li value={ordinal}>` 仍钉住每条来源从 1 起算的引用序号；没有了折叠造成的间断，这些序号如今就是连续的。
 
 把列表变成滚动容器，也把它的 `padding-left` 从间距变成了正确性约束。滚动容器裁掉 inline-start 方向的溢出且无从滚回，而 `::marker` 右对齐到内容边缘，因此宽于 padding 的序号会静默丢掉前导数字——在列表原本的 20px 下，两位数序号被画成 `0.` 与 `1.`，而本该是 `10.` 与 `11.`。`searchMaxResults` 是无上界的正整数，因此该 padding 以 `em` 计量——相对列表自身的字体，也就是序号所继承的那个——装得下三位数序号（`999. ` 在应用字体栈下量得 2.35em），并保留一位数情形原有的间隙。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **提高 `searchMaxResults`（或让它无上限），使更多来源同时抵达模型与卡片。** 被用户否决：它改变了模型侧行为（每个请求的上下文纳入更多来源、更多 token），并拉大模型读到的内容与卡片画出的内容之间的差距。指令很明确——保留上限与截断，加一个滚动条。
 
-**保留首尾折叠，仅对展开区域加滚动。** 否决：一个关注点上两套重叠机制。一旦整份列表始终渲染，折叠的算术、展开/折叠状态与那个按钮都是死重；仅靠滚动即可约束高度。
+**保留首尾折叠，仅对展开区域加滚动。** 否决：一个关注点上两套重叠机制。一旦整份列表始终渲染，折叠的算术、展开/折叠状态与那个按钮都是累赘；仅靠滚动即可约束高度。
 
 **把滚动高度做成插件配置字段。** 否决：该高度约束的是卡片在屏幕上的几何形状，而非部署策略，因此它属于 `WebBlock.module.css`，与 [Web result 卡片前端笔记](2026-07-30-web-result-card-frontend.md) 已作为本卡片几何固定在那里的圆角、表面与外边距并列。
 
-## Consequences
+## 后果
 
-工具返回的每一条来源始终存在于 DOM 中，因此 view 携带的来源没有一条被藏在交互之后。无论来源数量多少，卡片高度都受限；高于容器的列表在原地滚动。代价是滚动提示依赖平台的滚动条渲染：overlay 滚动条系统（macOS 默认）在指针离开时不显示常驻滚动条，因此被裁剪的列表依靠 `来源列表已截断` 提示加上被裁切的最后一行来表明还有更多内容。`WebSearchBlockProps`/`WebFetchBlockProps` 失去 `maxSources` prop，primitive 失去 `DEFAULT_WEB_MAX_SOURCES`，因此未来任何调用方都从构造上渲染完整列表，而不是靠传入一个很大的上限值。
+工具返回的每一条来源始终存在于 DOM 中，因此 view 携带的来源没有一条被藏在交互之后。无论来源数量多少，卡片高度都受限；高于容器的列表在原地滚动。代价是滚动提示依赖平台的滚动条渲染：overlay 滚动条系统（macOS 默认）在指针离开时不显示常驻滚动条，因此受高度限制的列表依靠 `来源列表已截断` 提示加上被裁切的最后一行来表明还有更多内容。`WebSearchBlockProps`/`WebFetchBlockProps` 失去 `maxSources` prop，primitive 失去 `DEFAULT_WEB_MAX_SOURCES`，因此未来任何调用方都从构造上渲染完整列表，而不是靠传入一个很大的上限值。
 
-## Testing
+## 测试
 
-`packages/client/ui-primitives/tests/web-block.spec.tsx` 删去折叠相关用例（首尾切片、点击展开、折叠尾部编号、展开器不计入编号、仅首部、默认上限），并新增：一个 30 条来源的卡片渲染出全部 30 个 `<li>`，无 `[aria-expanded]`、无 `<button>`，每个 `<ol>` 子元素都是一条来源 `<li>`，且 `<li value>` 从 1 到 N 连续编号。`packages/client/ui-tool/tests/web-card.spec.tsx` 删去 `CHAT_WEB_MAX_SOURCES` 上限断言；WebRow 展开测试仍断言卡片展示每一个来源字段。`packages/web/tool-web` 的测试不变——模型侧未曾移动。
+`packages/client/ui-primitives/tests/web-block.spec.tsx` 删去折叠相关用例（首尾切片、点击展开、折叠尾部编号、展开器不计入编号、仅首部、默认上限），并新增：一张含 30 条来源的卡片渲染出全部 30 个 `<li>`，无 `[aria-expanded]`、无 `<button>`，每个 `<ol>` 子元素都是一条来源 `<li>`，且 `<li value>` 从 1 到 N 连续编号。`packages/client/ui-tool/tests/web-card.spec.tsx` 删去 `CHAT_WEB_MAX_SOURCES` 上限断言；WebRow 展开测试仍断言卡片展示每一个来源字段。`packages/web/tool-web` 的测试不变——模型侧没有改动。
 
-jsdom 不解析 CSS Modules 布局，对任何元素都报 `scrollHeight === clientHeight`，因此它根本无从见证这次滚动。几何改由组装态浏览器钉住，位于 `apps/web/tests/web-search-round.e2e.ts`：其确定性 search double 返回 12 条 provider 结果，每条带标题、引用摘录与日期。这首先在真实组合里端到端钉住 seam 的裁剪——出厂 `searchMaxResults` 保留 8 条，面向模型的 render 文本含这 8 条标题、不含被丢弃的 4 条 URL，并含 `(Showing the first 8 sources. Refine the query for more.)`，`meta.truncated` 为 true。随后位于 aria golden 之后的一个用例展开 `web_search` 行，对卡片的 `<ol>` 断言：8 个 `<li>`、卡片内任何位置都没有 `<button>`、`来源列表已截断` 指示可见，以及计算样式 `max-height: 320px` 与 `overflow-y: auto`，`scrollHeight` 为 574、`clientHeight` 为 320。再后一个用例在列表自身继承的字体下量出 `999. ` 序号的宽度，要求计算后的 `padding-left` 不小于该宽度，从而把滚动容器无从滚回的那段序号空间钉在最宽序号上，而非钉在某一份 fixture 的来源条数上。录制的模型流与 aria golden 都未变动：replay 是对 fixture 中 `assistant/chunk` 条目的位置游标，而 search double 是 provider 经 `fetch` 抵达的另一个本地端点；捕获时卡片处于折叠状态，其 `<ol>` 不在 DOM 中，摘要行也不携带来源数量。
+jsdom 不解析 CSS Modules 布局，对任何元素都报 `scrollHeight === clientHeight`，因此它根本无从见证这次滚动。几何改由组装态浏览器钉住，位于 `apps/web/tests/web-search-round.e2e.ts`：其确定性 search double 返回 12 条提供方结果，每条带标题、引用摘录与日期。这首先在真实组合里端到端钉住 seam 的裁剪——出厂 `searchMaxResults` 保留 8 条，面向模型的 render 文本含这 8 条标题、不含被丢弃的 4 条 URL，并含 `(Showing the first 8 sources. Refine the query for more.)`，`meta.truncated` 为 true。随后位于 aria golden 之后的一个用例展开 `web_search` 行，对卡片的 `<ol>` 断言：8 个 `<li>`、卡片内任何位置都没有 `<button>`、`来源列表已截断` 指示可见，以及计算样式 `max-height: 320px` 与 `overflow-y: auto`，`scrollHeight` 为 574、`clientHeight` 为 320。再后一个用例在列表自身继承的字体下量出 `999. ` 序号的宽度，要求计算后的 `padding-left` 不小于该宽度，从而把滚动容器无从滚回的那段序号空间钉在最宽序号上，而非钉在某一份 fixture（测试前置数据）的来源条数上。录制的模型流与 aria golden 都未变动：回放是对 fixture 中 `assistant/chunk` 条目的位置游标，而 search double 是提供方经 `fetch` 抵达的另一个本地端点；捕获时卡片处于折叠状态，其 `<ol>` 不在 DOM 中，摘要行也不携带来源数量。
 
-## Related
+## 相关文档
 
 - [Web result card](2026-07-30-web-result-card.md) —— 本卡片消费的 `card: 'web'` 渲染意图分支与 `presentationMeta` 路由；那份裁剪过一次的列表的来源。
 - [Web result 卡片前端](2026-07-30-web-result-card-frontend.md) —— `WebBlock`、唯一的 `web-card-model` 派生，以及绘制该卡片的各渲染点由它拥有；本笔记替换掉它所规定的来源列表折叠，它的其余决策（一个组件绘制两种 kind、http(s) 链接 allowlist、单一派生、常驻姿态）依然成立。
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
index 4673ffaab7..7100fc33fc 100644
--- a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md
 2026-08-04-claude-code-and-codex-subagent-backends.md: e81d1fb14f719331c503dba539d6a5ec0f1eed4f
-2026-08-04-claude-code-and-codex-subagent-backends.zh.md: 3c78e8d5a4ca1a86942971721ad05c631901f231
+2026-08-04-claude-code-and-codex-subagent-backends.zh.md: aa6d80e38c12a2808a27e93bde8aec5d71e6a509
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
index 3c78e8d5a4..aa6d80e38c 100644
--- a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 命名的 [`ctx.subagents`](2026-06-21-subagent-capability-seam.md) 注册表让父 agent（智能体）无需了解子级的运行方式即可委派工作，但 harness 需要通往真实 Codex 与 Claude Code 产品的第一方路径。每条路径都必须向产品交付一项自包含任务，让它在父会话的工作区中执行，返回最终回答或明确的失败或取消结果，并且不留下任何受管的产品进程。
 
-产品集成不得成为任务文本、cwd、取消、结果结算或进程树的第二责任方。因此，所需证据要区分三个事实：无密钥真实产品测试证明官方集成、原生身份验证形态、确定性答案与资源清理；Loader 组合测试证明公开包（package）和文档所示的工具配置无需启动产品即可加载；带密钥 e2e 证明生产提供方与真实产品能够从真实 DeepSeek 服务取得唯一答案。直接发起模型 HTTP 请求或使用产品替身无法取代上述任一产品运行层级；手工挂载插件无法取代 Loader 层级。
+产品集成不得成为任务文本、cwd、取消、结果结算或进程树的第二责任方。因此，所需证据要区分三个事实：无密钥真实产品测试证明官方集成、原生身份验证形态、确定性答案与资源清理；Loader 组合测试证明公开包和文档所示的工具配置无需启动产品即可加载；带密钥 e2e 证明生产提供方与真实产品能够从真实 DeepSeek 服务取得唯一答案。直接发起模型 HTTP 请求或使用产品替身无法取代上述任一产品运行层级；手工挂载插件无法取代 Loader 层级。
 
 ## 决策
 
@@ -55,7 +55,7 @@ Codex 0.146.0 使用 Responses 协议，而 DeepSeek 的公开 OpenAI 兼容端
 
 启动回滚和已发布运行的资源释放都会关闭 SDK query、中止该次运行的控制器、调用共享的进程树终止机制，并等待整棵进程树退出。`Query.close()` 表达优雅的协议关闭意图，但不能取代子进程责任方的退出证明。Query 关闭失败、进程失败和清理失败仍可彼此独立地观察。
 
-带密钥 Claude Code e2e 直接使用官方 DeepSeek Claude Code 契约：仅在运行时提供的 DeepSeek 密钥会映射为 `ANTHROPIC_AUTH_TOKEN`，固定的官方基础 URL 会追加 `/anthropic`，主模型与 subagent 模型变量会选择文档所示的 DeepSeek 模型。该测试会启动生产提供方与真实 SDK 和 CLI，要求一个随机数作为完整答案，不会把任何凭据持久化到设置中，并等待所有受管句柄退出。
+带密钥 Claude Code e2e 直接使用官方 DeepSeek Claude Code 约定：仅在运行时提供的 DeepSeek 密钥会映射为 `ANTHROPIC_AUTH_TOKEN`，固定的官方基础 URL 会追加 `/anthropic`，主模型与 subagent 模型变量会选择文档所示的 DeepSeek 模型。该测试会启动生产提供方与真实 SDK 和 CLI，要求一个随机数作为完整答案，不会把任何凭据持久化到设置中，并等待所有受管句柄退出。
 
 ## 分发与证据
 
@@ -83,11 +83,11 @@ Claude Code 证据锁定 Agent SDK 0.3.220 及其平台分发的 Claude Code 2.1
 
 **由插件管理登录、产品主目录、模型、设置或权限。** 这些选择会在每个产品的原生配置之外建立另一套权威来源，并将一次性提供方扩张为账户管理功能。提供方只公开显式环境覆盖项和清理宽限期；无人值守交互会以默认拒绝方式失败。
 
-**续接、进度、后台收集和共享父级上下文。** 已交付的用户结果是一项自包含任务和一个最终回答。产品会话、恢复、后续交互、中间消息、父级 transcript（文本记录）传递、结构化输出和后台收集都需要独立的用户契约，当前实现不会预先构建这些功能。
+**续接、进度、后台收集和共享父级上下文。** 已交付的用户结果是一项自包含任务和一个最终回答。产品会话、恢复、后续交互、中间消息、父级 transcript（文本记录）传递、结构化输出和后台收集都需要独立的用户约定，当前实现不会预先构建这些功能。
 
 ## 后果
 
-用户可以安装任一或两个产品提供方，在自己的 Cordis 配置中绑定稳定的前台工具，并通过现有 subagent 契约委派一项自包含任务。官方产品集成会保留原生设置与行为，而共享服务继续独占任务结算与进程树完全停稳的责任。
+用户可以安装任一或两个产品提供方，在自己的 Cordis 配置中绑定稳定的前台工具，并通过现有 subagent 约定委派一项自包含任务。官方产品集成会保留原生设置与行为，而共享服务继续独占任务结算与进程树完全停稳的责任。
 
 每次委派都要承担新建产品进程和独立模型上下文的开销，且只有最终文本会到达父级。产品原生配置使行为取决于部署环境中安装的产品、账户状态和工作区设置。带密钥 e2e 运行还会消耗外部 API 配额，并依赖 DeepSeek 官方端点；对协议、失败、取消与审批的确定性覆盖仍由无密钥层级承担。提供方不会恢复会话、以流式方式传送进度、接受新的人工交互、回滚工具或文件副作用，也不会施加按实际经过时间触发的超时。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
index 86c05dc9bd..fa352e395b 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
 2026-08-04-pointer-revealed-sidebar-scrollbars.md: eb86f710e44cd8f1fb2cef41db99504af42413bb
-2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: 598c10dc2373eeb821d05f349a662156b194c71b
+2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: f3a92d6645c7f98a60fd3c4431cdfb84babfd51b
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
index 598c10dc23..f3a92d6645 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
@@ -1,38 +1,38 @@
-# Agent Note：侧边栏的滚动条跟随指针
+# Agent Note: 侧边栏的滚动条跟随指针
 
 Status: implemented
 
 [English](2026-08-04-pointer-revealed-sidebar-scrollbars.md) | 中文
 
-## Problem
+## 问题
 
-侧边栏的会话列表只要有十来个会话就会溢出，从那一刻起它的滚动条就一直画在那里——所处的这一列大部分时间都是静止的，而列表行自己的操作按钮只在悬停时才出现。它是侧边栏里唯一始终常驻的构件，而在有人真的伸手去拖它之前，它不提供任何可操作性。产品诉求（2026-08-04）是只在指针位于侧边栏内时才绘制它，并留一小段拖尾，避免指针路过时它一闪而灭。
+侧边栏的会话列表只要有几个会话就会溢出，从那一刻起它的滚动条就一直画在那里——所处的这一列大部分时间都是静止的，而列表行自己的操作按钮只在悬停时才出现。它是侧边栏里唯一始终常驻的构件，而在有人真的伸手去操作它之前，它不提供任何可操作性。产品诉求（2026-08-04）是只在指针位于侧边栏内时才绘制它，并留一小段拖尾，避免指针路过时它一闪而灭。
 
-## Decision
+## 决策
 
 `SidebarRoot` 跟踪整列上的指针，只要指针不在列内就给根元素挂上 `quietBars` 类。该类选中的规则把 ui-theme 的那组间接变量——`--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`——重新绑定为 `transparent`，于是嵌套在这一列下的每个滚动区域都不绘制滑块。今天这样的区域只有会话列表；将来新增的区域会直接继承这一行为，而不需要逐个接入。
 
 拖尾是 `SCROLLBAR_LINGER_MS = 2000`：离开会启动一个定时器，进入会取消尚未触发的定时器，只有定时器真正触发才会把类加回去。指针越过列边界又折返时——绕过一个 portal 菜单，或是奔向某一行时冲过了头——不会看到滑块闪动。
 
-进入用的是列自身的 `pointerenter`；离开则按列的盒子判定，由一个只在滚动条可见期间存在的 `pointermove` 监听完成。DOM 包含关系无法判定离开：ui-settings 把整屏的设置面板渲染为这一列的 fixed 定位**后代**，指针移到该面板上——或在面板关闭后移到对话区——都不会在这里触发 `pointerleave`，滚动条就会继续画在一个没人指向的列上。元素自身的 leave 仍然保留，用于几何判定看不到的那一种情况：指针移出窗口后不再产生任何移动事件。
+进入用的是列自身的 `pointerenter`；离开则按列的盒子判定，由一个只在滚动条可见期间存在的 `pointermove` 监听完成。DOM 包含关系无法判定离开：ui-settings 把整屏的设置面板渲染为这一列的 fixed 定位*后代*，指针移到该面板上——或在面板关闭后移到对话区——都不会在这里触发 `pointerleave`，滚动条就会继续画在一个没人指向的列上。元素自身的 leave 仍然保留，用于几何判定看不到的那一种情况：指针移出窗口后不再产生任何移动事件。
 
 承载指针的是整列，而不是列表。奔向滚动条的指针会先经过 logo 行、New Session 胶囊和搜索框，所以只在列表上显示，会让滚动条等到指针已经落在行中间时才出现。
 
-`transparent` 正是让这次显示不触发任何布局的原因。列表上的 `scrollbar-gutter: stable` 存在的意义就是让行永不移动（见[空槽 Agent Note（agent 决策记录）](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)）；重新绑定的只是颜色，那份预留始终有效，所以滑块出现在列表本就为它留出的空间里。
+`transparent` 正是让这次显示不触发任何布局的原因。列表上的 `scrollbar-gutter: stable` 存在的意义就是让行永不移动（见[空槽 Agent Note](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)）；重新绑定的只是颜色，那份预留始终有效，所以滑块出现在列表本就为它留出的空间里。
 
-选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定接缝：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
+选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定 seam：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
 
-这拓宽了重新绑定契约，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
+这拓宽了重新绑定约定，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
 
-隐藏不再算作抬升：只有 l2 重绑才能让一张样式表免于「任何既滚动又绘制抬升表面的样式表都必须重新绑定」。既隐藏滚动条又在抬升表面上滚动的样式表，仍然欠着那里真正绘制滑块时所需的 l2。
+隐藏不再算作抬升：只有 l2 重绑才能让一张样式表免于「任何在抬升表面上滚动的样式表都必须重新绑定」。既隐藏滚动条又在抬升表面上滚动的样式表，仍然欠着那里真正绘制滑块时所需的 l2。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **只用列上的 CSS `:hover`，不引入 JavaScript 状态。** 整套机制只需一条规则，但它表达不出拖尾：指针越过边界的那一帧滑块就会消失，而那恰好是指针正奔向对话区或绕行 portal 菜单的时刻。诉求本身点名了拖尾，只有 hover 的版本读起来就是闪烁。
 
 **留在 CSS 里、用过渡拿到这段延迟**，即通过 `@property` 注册 `--dsh-scrollbar-thumb` 让该自定义属性可动画，再用 `transition-delay` 把颜色按住。因代价与作用范围被否决：这项注册对每个读取这组变量的表面都是全局的，却只为一列的时序服务；而且这套调色板实际渲染所走的 WebKit 滚动条伪元素并不可靠地支持过渡——延迟会被声明在观察不到它的地方。
 
-**直接把滚动条藏掉**——`scrollbar-width: none`，或对 `::-webkit-scrollbar` 用 `display: none`。被否决，因为这会连带取消那段预留：滚动条重新出现时要重新占走 8px，会把每一行都在显示它的那个指针底下横向推移，而这正是当初加入空槽预留所修掉的回归。
+**直接把滚动条藏掉**——`scrollbar-width: none`，或对 `::-webkit-scrollbar` 用 `display: none`。被否决，因为这会连带取消那段预留：滚动条重新出现时会重新占走 8px，使每一行都在触发其显示的指针下方横向移动，而这正是当初加入空槽预留所修掉的回归。
 
 **在应用内自绘一个覆盖式滑块**，并彻底隐藏原生滚动条，这是完全自定义淡入淡出所需要的做法。它换来任意样式，代价是命中测试、拖拽、滚轮、惯性以及两套调色板下的 hover 状态——在一个滚动条已由 token 统一主题化的客户端里，为观感付出的是一大片自持表面。
 
@@ -40,7 +40,7 @@ Status: implemented
 
 **滚动事件也触发显示**，让键盘或触摸驱动的滚动同样显示滚动条。被否决，因为那是在为触发它的输入方式画一个它用不上的可供性；行本身已经说明列表移动过了。
 
-## Consequences
+## 后果
 
 - 用键盘或触摸拖动滚动的列表，在拖尾结束后不显示滑块，因为这两种方式都不会把指针留在列上。e2e 会钉住这一点，而不只是把它写下来。
 - 拖动滑块本身移出列不会在拖动中途把它隐藏：滚动条会接管指针捕获，按住按键期间页面收不到 `pointermove`。已在 Chromium 实测——指针拖到列右侧 900px 处、超过拖尾窗口后，滚动条依然绘制并继续滚动。
@@ -48,15 +48,15 @@ Status: implemented
 - 嵌套在列内、为自身抬升层级把这组变量重新绑定到 l2 的抬升表面，会覆盖静默状态并继续绘制自己的滚动条。今天侧边栏内没有这样的表面。
 - 外壳的 DOM 现在带有一个状态类，因此 ui-sidebar 的外壳快照会钉住 `quietBars`，默认状态出现回归时表现为快照 diff，而不是需要有人从截图里看出来的东西。
 
-## Testing
+## 测试
 
 `packages/client/ui-sidebar/tests/pointer-scrollbars.spec.tsx` 用假定时器把这个类走过各次跃迁：进入时显示，拖尾结束前 1 毫秒仍然显示，结束后 1 毫秒转为静默，以及窗口内折返会取消隐藏。另有两条覆盖几何判定的离开：落在列盒子之外的 `pointermove` 会在没有任何 DOM leave 的情况下隐藏滚动条（即设置面板那种形态），落回盒子之内的则取消待触发的隐藏。它还在拖尾进行中卸载组件并断言没有定时器存活——待触发的隐藏落到已销毁的组件上，正是这种写法容易犯的错。事件用的是带 `relatedTarget` 的 `pointerover`／`pointerout`，因为 React 由它们合成 enter 与 leave，而会忽略原生的那两个事件。
 
 `packages/client/ui-sidebar/tests/scrollbar-quiet-styles.spec.ts` 直接读样式表：该规则必须写出这组变量的两半——只重新绑定静止态滑块，会让指针一碰到滚动条就露出 hover 颜色——并且不得出现 `scrollbar-gutter`，那属于滚动区域自己。
 
-`apps/web/tests/sidebar-scrollbar.e2e.ts` 是两半在真实引擎里汇合的地方。它在每次读取颜色前先把指针停在列表上，因为一个从不移动鼠标的场景全程测到的都是静默状态，会变成空洞的绿。随后它自己的用例把指针移开，断言在 leave 当下滑块仍在绘制，轮询直到它解析为 `rgba(0, 0, 0, 0)`，在该状态下重新测量几何以证明滚动条隐藏期间那份预留依然生效，并以编程方式滚动列表——键盘或触摸拖动所做的事——来钉住无指针滚动不绘制任何滑块。提交的 golden 记录了两套调色板下、两个指针位置上的滑块颜色。
+`apps/web/tests/sidebar-scrollbar.e2e.ts` 是两半在真实引擎里汇合的地方。它在每次读取颜色前先把指针停在列表上，因为一个从不移动鼠标的场景全程测到的都是静默状态，会在未实际验证目标行为的情况下通过。随后它自己的用例把指针移开，断言在 leave 当下滑块仍在绘制，轮询直到它解析为 `rgba(0, 0, 0, 0)`，在该状态下重新测量几何以证明滚动条隐藏期间那份预留依然生效，并以编程方式滚动列表——键盘或触摸拖动所做的事——来钉住无指针滚动不绘制任何滑块。提交的 golden 记录了两套调色板下、两个指针位置上的滑块颜色。
 
-这条 e2e 的对照是一次 mutation，而它需要插件自己的产物：把 `quietBars` 从外壳中去掉，先重新构建 `@deepseek-ai/dsh-client-ui-sidebar`、之后再跑 `build:web`，该用例会因为滑块解析为 `rgb(229, 229, 229)`、而期望 `rgba(0, 0, 0, 0)` 而变红。只重跑 `build:web` 用的是过期产物，即使改动已被删除也照样通过，这正是[空槽 Agent Note（agent 决策记录）](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)记录过的陷阱。
+这条 e2e 的对照是一次 mutation，而它需要插件自己的产物：把 `quietBars` 从外壳中去掉，先重新构建 `@deepseek-ai/dsh-client-ui-sidebar`、之后再跑 `build:web`，该用例会因为滑块解析为 `rgb(229, 229, 229)`、而期望 `rgba(0, 0, 0, 0)` 而变红。只重跑 `build:web` 用的是陈旧产物，即使改动已被删除也照样通过，这正是[空槽 Agent Note](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)记录过的陷阱。
 
 拓宽后的门禁也有自己的对照，每个都是对真实样式表的一处声明改动：把 `transparent` 与 l2 的 hover 混用，以及把 l2 token 包进 `color-mix(…)`，都会让这条成对断言变红。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml
index b35cca4b38..17d590a110 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md
 2026-08-04-web-composer-shared-width-axis.md: 96cddda25bf79e9f2df7a0298039c27f316befca
-2026-08-04-web-composer-shared-width-axis.zh.md: 9a9f5a513bbce8f3e97698d58ab48b0abdefb142
+2026-08-04-web-composer-shared-width-axis.zh.md: b5a455f9e8c561ae89faa9baf526fdbb263bc89a
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
index 9a9f5a513b..b5a455f9e8 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
@@ -4,19 +4,19 @@ Status: implemented
 
 [English](2026-08-04-web-composer-shared-width-axis.md) | 中文
 
-## Problem
+## 问题
 
-Web 会话列的各个界面各自独立设定尺寸：转录列、输入卡片、todo/goal/queue 停靠卡片、ask-question/approval/plan-review 接管卡片各自硬编码 max-width（736/752/776/800px 等变体）与各自的侧边内边距。这些界面在全宽下彼此漂移几个像素，在窄视口下偏差更大——有的面板保留了到屏幕边缘的间隙，有的却贴边。另外，输入卡片的控制行没有自适应行为——窄卡片下权限触发器的文字标签会挤压整行；锚定在卡片上的浮层菜单也可能渲染得比卡片更宽，越过其右边缘。
+Web 会话列的各个界面各自独立设定尺寸：transcript（文本记录）列、输入卡片、todo/goal/queue 停靠卡片、ask-question/approval/plan-review 接管卡片各自硬编码 max-width（736/752/776/800px 等变体）与各自的侧边内边距。这些界面在全宽下彼此漂移几个像素，在窄视口下偏差更大——有的面板保留了到屏幕边缘的间隙，有的却贴边。另外，输入卡片的控制行没有自适应行为——窄卡片下权限触发器的文字标签会挤压整行；锚定在卡片上的浮层菜单也可能渲染得比卡片更宽，越过其右边缘。
 
-## Decision
+## 决策
 
-一个内容宽度变量拥有整列。`--dsh-chat-content-width`（748px）声明在 ConversationRoot 的 `.root` 上——转录与 composer 座位是兄弟子树，声明必须放在共同祖先上，CSS 自定义属性才能通过继承同时到达两者。其他几何全部由它推导：输入卡片上限为 `content + 32px`（`--dsh-composer-card-max-width`），停靠卡片从卡片宽度中减去四个停靠 inset（4 × 8px）正好回到内容宽度，接管卡片直接使用内容宽度。窄视口不变式以结构而非数值表达：内容宽度的界面每侧 pad `calc(var(--dsh-composer-side-clearance) + 16px)`，而输入卡片只留裸 clearance（16px），因此"输入卡片 = 内容 + 32px"在任意视口宽度下都成立，而不只是在上限处。
+一个内容宽度变量控制整列。`--dsh-chat-content-width`（748px）声明在 ConversationRoot 的 `.root` 上——transcript 与 composer 座位是兄弟子树，声明必须放在共同祖先上，CSS 自定义属性才能通过继承同时到达两者。其他几何全部由它推导：输入卡片上限为 `content + 32px`（`--dsh-composer-card-max-width`），停靠卡片从卡片宽度中减去四个停靠 inset（4 × 8px）正好回到内容宽度，接管卡片直接使用内容宽度。窄视口不变式以结构而非数值表达：内容宽度的界面每侧 pad `calc(var(--dsh-composer-side-clearance) + 16px)`，而输入卡片只留裸 clearance（16px），因此「输入卡片 = 内容 + 32px」在任意视口宽度下都成立，而不只是在上限处。
 
 卡片内的控制行是一个 `container-type: inline-size` 容器，权限触发器在 460px 容器查询下收起文字标签（保留图标 + 下拉箭头）。查询刻意匿名：CSS modules 按模块哈希 `container-name`，InputBar 样式表里声明的名字永远无法匹配 PermissionSelect 样式表里写的查询——两个哈希后的名字悄然不同，查询永不触发。只有带模式图标的触发器才收起（`:has(.triggerIcon)`）；没有图标的宿主自定义模式保留文字作为其唯一标识。
 
-锚定在卡片上的浮层菜单（slash 菜单、command popupSelect）钳制到锚点宽度（`max-width: min(<设计上限>, 100%)`），过长的行以省略号截断而不是溢出卡片。Tooltip 气泡在钳制中保留 12px 的视口边缘安全距离（ui-primitives Tooltip）。
+锚定在卡片上的浮层菜单（slash 菜单、command popupSelect）钳制到锚点宽度（`max-width: min(<design cap>, 100%)`），过长的行以省略号截断而不是溢出卡片。Tooltip 气泡在钳制中保留 12px 的视口边缘安全距离（ui-primitives Tooltip）。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **保留各界面独立宽度，手工对齐数值。** 否决：本次改动消除的漂移正是手工对齐常量的残留；未来任何宽度调整都需要五处协同编辑，且没有任何机制强制这组关系。
 
@@ -26,6 +26,6 @@ Web 会话列的各个界面各自独立设定尺寸：转录列、输入卡片
 
 **用 JS ResizeObserver 实现标签收起。** 否决：容器查询是声明式的，无需监听器生命周期，而 460px 阈值无论哪种方案都是设计选择。
 
-## Consequences
+## 后果
 
 修改列宽现在是一行编辑，比例关系由构造保证——评审期间 736 → 748 的重调已经验证了这一点。代价是间接性：五个界面的宽度不再能从各自的样式表直接读出，需要沿变量链追到 ConversationRoot。容器查询收起增加了一个约束：InputBar 的行必须保持为尺寸容器；删掉那条声明会静默禁用权限触发器的自适应行为。匿名查询也意味着未来若在行与触发器之间出现第二个容器，它会截获该查询——届时查询必须迁移，或避免中间容器。
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
index abb67be310..788e0c44fd 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
 2026-08-04-web-context-source-and-steer-marks.md: ca44702cf637c4250d141396ac22d206a16acc15
-2026-08-04-web-context-source-and-steer-marks.zh.md: 09cefd07e3b417b63f05ce430cfed7b30597452f
+2026-08-04-web-context-source-and-steer-marks.zh.md: da8b629da262ed462f84083030c4fdfb1083eb77
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
index 09cefd07e3..da8b629da2 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
@@ -1,16 +1,16 @@
-# Agent Note：Web transcript 标出上下文来源、召回与 steering
+# Agent Note: Web transcript 标出上下文来源、召回与 steering
 
 Status: implemented
 
 [English](2026-08-04-web-context-source-and-steer-marks.md) | 中文
 
-## Problem
+## 问题
 
-生产方向模型侧对话补充的一切内容，进入 Web transcript（文本记录）后只剩两种匿名形态。每一条已记录的非用户 `user/message`——skill 目录、运行时快照、经过对账的 `AGENTS.md` 指令、guard 提示、子 agent 汇报、跨会话快照——都塌缩成同一行 `上下文注入`，读者不逐行展开去读原始 JSON 就无从知道究竟注入了什么。steering（中途引导）的情况更糟：它渲染成与开轮提示完全相同的气泡，于是 transcript 无法说明哪一条消息打断了正在运行的轮次。
+生产方向模型侧对话补充的一切内容，进入 Web transcript（文本记录）后只剩两种匿名形态。每一条已记录的非用户 `user/message`——skill（技能）目录、运行时快照、经过对账的 `AGENTS.md` 指令、guard 提示、subagent 汇报、跨会话快照——都塌缩成同一行 `上下文注入`，读者不逐行展开去读原始 JSON 就无从知道究竟注入了什么。steering（中途引导）的情况更糟：它渲染成与开轮提示完全相同的气泡，于是 transcript 无法说明哪一条消息打断了正在运行的轮次。
 
 这些区分本来就是持久事实。`user/message.source` 是每个生产方都必须提供的可合并扩展来源，`agent/inbox/spliced` 则记录有身份的消息是从 `next-turn` 还是 `next-step` 进入和离开；把这些事实丢掉的只有呈现层。被这套 Web UI 取代的终端 transcript 本来会写出每张卡片的生产者，因此面对同一份日志，Web 侧是一次倒退。
 
-## Decision
+## 决策
 
 transcript 为非提示消息可能承担的三种角色分别命名：注入上下文、召回会话、steering。
 
@@ -22,7 +22,7 @@ transcript 为非提示消息可能承担的三种角色分别命名：注入上
 
 `MessageItem` 为持久与待处理的 steering 气泡加上 `插话` 标注。runtime 会重放持久 `agent/inbox/spliced` 事件；如果一条用户来源的消息以相同身份从 `next-step` 被领取，后续 `user/message` 就投影为 `SteeringMessageNode`。从排队轮次领取的消息仍是 `UserMessageNode`，非用户来源的 next-step 消息仍是上下文。这推翻了[已归档的取消 steer 入口与插话装饰决策](../../archived/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md)中的一条结论。当时移除徽章，是因为 composer 无法 steer，标签指向了用户做不到的动作。此后 composer 获得了 Steer 手势，却没有同步修订那份 note；本决策提供了它在「重新引入」条款中要求的产品决策，并订正了其中留下的过时事实。标注是这里唯一的 steering 装饰：composer 模式、Queue dock 的严格 steer 操作、待处理 steering 的生命周期仍归各自的所有者。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **在客户端本地化生产者名称。** 以插件 id 为键的字典读起来确实比 `@deepseek-ai/dsh-system-prompt` 好，但它会在每次重命名时悄悄失准，每新增一个生产者都要改客户端，而且对来自外部的日志根本无法命名。日志已经承载的来源，比客户端自己编出来的措辞更有价值。
 
@@ -34,13 +34,13 @@ transcript 为非提示消息可能承担的三种角色分别命名：注入上
 
 **把同一套名称扩展到 trajectory 表格。** 不在本次范围内：该表格的上下文单元格有自己的文本推导，而 issue 要求的是对话面。
 
-## Testing
+## 测试
 
 - `packages/client/runtime` 单元覆盖钉住每个来源分支、名称字段缺失／为空／类型不符时的回退、来源没有可读 kind 时的无名降级，以及 reset 和实时 append 路径上的 steering 重建。
 - `packages/client/ui-conversation` 的 jsdom 覆盖钉住角色标题、标题旁的生产者名称、展开后该名称的留存、无名时的标题形态，以及持久与待处理气泡上的 steering 标注。
 - 无密钥的组装 Web 黄金基线携带带名称的标题栏与 steering 标注，因此证明这些标识的是组装后的 transcript，而不只是组件测试。
 
-## Consequences
+## 后果
 
 - 读者一眼即可归因 transcript 中每一条非提示消息；即便面对本客户端版本从未见过其生产者的日志，标题栏依然如实。
 - 只要来源仅携带插件 id，UI 中的生产者名称就呈现为包名形态（`dsh-tool-skill`、`@deepseek-ai/dsh-system-prompt`）。这是拒绝客户端名称表的代价；想要更好名称的生产者应当记录更好的来源。
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml
index 16ccf1cff3..54df52a8e9 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.md
 2026-08-04-web-latency-throughput-metrics.md: 4d7627a9a38127259f1ba07121cea7282f794f2e
-2026-08-04-web-latency-throughput-metrics.zh.md: 09e59242b799a3f4d03b9e0259f1a5a0d85f6a53
+2026-08-04-web-latency-throughput-metrics.zh.md: f0089cb45775f2dc9701a7256119f04e4709dd76
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md
index 09e59242b7..f0089cb457 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-latency-throughput-metrics.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-Web 聊天已经记录了逐步骤的 LLM 计时（`stepStartTime`／`firstTokenTime`／`completedTime`）和逐步骤 usage，trajectory 视图也按步骤展示它们，但聊天界面既回答不了「这一轮响应有多快」，也回答不了「这个会话跑得有多快」：assistant 页脚只显示轮次实际耗时，统计行也只折算墙钟时间总量。
+Web 聊天已经记录了逐步骤的 LLM（大语言模型）计时（`stepStartTime`／`firstTokenTime`／`completedTime`）和逐步骤 usage，trajectory 视图也按步骤展示它们，但聊天界面既回答不了「这一轮响应有多快」，也回答不了「这个会话跑得有多快」：assistant 页脚只显示轮次实际耗时，统计行也只折算墙钟时间总量。
 
 ## 决策
 
-包内折算 `ui-conversation` 的 `chat/turn-metrics.ts` 是从 assistant 节点推导延迟/吞吐读数的唯一位置。`assistantStepReading` 把一个节点转成一次步骤读数：TTFT（首 token 延迟）需要 `stepStartTime` 与 `firstTokenTime` 同时存在，解码时长需要 `firstTokenTime`，负时长收敛为零，输出 token 数只在不可信的 `usage` 值有限且非负时才采纳。`deriveTurnMetrics` 按轮次折算读数：编号最小的步骤拥有该轮次的 TTFT 槽位，吞吐用「同时携带两者的那些步骤」的输出 token 总和除以解码时长总和，因此缺采样的步骤直接退出而不是让比值失真；两个数字都没有的轮次不产生条目。
+`ui-conversation` 包内的折算逻辑 `chat/turn-metrics.ts` 是从 assistant 节点推导延迟/吞吐读数的唯一位置。`assistantStepReading` 把一个节点转成一次步骤读数：TTFT（首 token 延迟）需要 `stepStartTime` 与 `firstTokenTime` 同时存在，解码时长需要 `firstTokenTime`，负时长钳制为零，输出 token 数只在不可信的 `usage` 值有限且非负时才采纳。`deriveTurnMetrics` 按轮次折算读数：编号最小的步骤拥有该轮次的 TTFT 槽位，吞吐用「同时携带两者的那些步骤」的输出 token 总和除以解码时长总和，因此缺采样的步骤直接退出而不是让比值失真；两个数字都没有的轮次不产生条目。
 
 assistant 页脚把读数追加到既有 hover 显示的时间附属元素中、`用时` 之后，形如 `首 token {s}秒 · {tps} tok/s`，未记录的数字各自省略。ChatView 仅在该轮次的 `turnTimings` 条目带有 `endTime` 时才显示读数：已加载窗口是日志的连续后缀，因此窗口内已结算的轮次必然带着它的全部步骤，首步 TTFT 是真实值而非窗口截断的产物。`formatLatencySeconds` 不带单位，各语言模板各自拥有秒后缀（`TTFT {seconds}s`／`首 token {seconds}秒`）。
 
@@ -18,7 +18,7 @@ assistant 页脚把读数追加到既有 hover 显示的时间附属元素中、
 
 ## 考虑过的替代方案
 
-**持久的会话投影（token-meter 形态）。** 在 host 侧用 `ProjectionDefinition` 折算步骤计时可以跨越压缩与窗口分页、覆盖整个日志。是暂缓而非否决：投影状态必须保持 O(1)（只能均值，不能分位数），它需要 host 改动加 schema，而聊天统计行的耗时事实本就被记录为窗口作用域——新分组沿用该作用域。后续 PR 可以在不挪动这些读数的情况下补上持久投影。
+**持久的会话投影（token-meter 形态）。** 在 host 侧用 `ProjectionDefinition` 折算步骤计时可以跨越压缩（compaction）与窗口分页、覆盖整个日志。是暂缓而非否决：投影状态必须保持 O(1)（只能均值，不能分位数），它需要 host 改动加 schema，而聊天统计行的耗时事实本就被记录为窗口作用域——新分组沿用该作用域。后续 PR（Pull Request）可以在不挪动这些读数的情况下补上持久投影。
 
 **逐步骤页脚附属元素。** 让每条 assistant 消息显示自己的 TTFT，会给轮次中段的叙述节点挂上附属元素，而页脚设计刻意让它们保持无 chrome；trajectory 视图已经暴露逐步骤计时细节。
 
@@ -28,4 +28,4 @@ assistant 页脚把读数追加到既有 hover 显示的时间附属元素中、
 
 窗口内已结算轮次的页脚在 hover 时于实际耗时之后显示 `首 token`／`tok/s`，统计行在墙钟时间旁以本地化标签显示窗口平均延迟与吞吐，全程不新增会话事件、不改 host。指标以省略的方式退化：没有计时或 usage 采样的提供方或步骤只是丢掉对应数字，而不会渲染成零。已加载窗口之外的更早历史仍不计入，已记录在包 README 的统计行限制中。
 
-两个读数都以实测墙钟时间作分母，因此都不可复现：同一个回放场景在本机连续两次跑出 69 与 70 tok/s，而一段 3 毫秒的回放流会读成 26333 tok/s。因此 Web aria golden 在既有的 `{{duration}}` 之外，把吞吐归一化为 `{{throughput}}`；页脚的装饰性分隔符也补上了两侧空格——没有它们，这些读数会连成一整串无障碍文本（`Ran for 13sTTFT 0.2s12 tok/s`），既让屏幕阅读器失去读数之间的边界，也让 `{{duration}}` 失去它赖以匹配的词边界。
+两个读数都来自实测墙钟时间，因此都不可复现：TTFT 是 `firstTokenTime - stepStartTime` 的时间差，吞吐则以 `completedTime - firstTokenTime` 的解码墙钟时长为分母。同一个回放场景在本机连续两次跑出 69 与 70 tok/s，而一段 3 毫秒的回放流会读成 26333 tok/s。因此 Web aria golden 在既有的 `{{duration}}` 之外，把吞吐归一化为 `{{throughput}}`；页脚的装饰性分隔符也补上了两侧空格——没有它们，这些读数会连成一整串无障碍文本（`Ran for 13sTTFT 0.2s12 tok/s`），既让屏幕阅读器失去读数之间的边界，也让 `{{duration}}` 失去它赖以匹配的词边界。
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.i18n.yaml
index 900bc3562d..1e3ada6894 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.md
 2026-08-04-web-slash-command-fuzzy-discovery.md: 8d7fe88f8d19a6edc7b51e63578c468df085c238
-2026-08-04-web-slash-command-fuzzy-discovery.zh.md: d3efdc23351a1b50853ee76fb731aee046004750
+2026-08-04-web-slash-command-fuzzy-discovery.zh.md: a96f9c984e32dd777950b9f9d8594b3a9c8b7c17
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md
index d3efdc2335..a96f9c984e 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md
@@ -4,17 +4,17 @@ Status: implemented
 
 [English](2026-08-04-web-slash-command-fuzzy-discovery.md) | 中文
 
-## Problem
+## 问题
 
 Web 命令菜单要求按命令名前缀匹配，因此用户只记得关键字母却不记得其准确位置时，就无法发现命令。扩大菜单的匹配范围可使命令更易发现，但命令执行仍必须保持精确匹配和确定性：近似输入行绝不能执行相近命令。
 
-## Decision
+## 决策
 
 `/` 命令 source 将键入的查询作为不区分大小写的有序子序列，与命令名进行模糊匹配。精确前缀构成排名最高的一类匹配。在每类匹配中，对齐分数越高越优先：分隔符边界和相邻字符会提高分数，前导字符和间隔会降低分数；分数相同则保持 host 目录和 client contribution 的顺序。位置过滤仍会在排名前从行内菜单中移除接收参数的命令。
 
-评分器对每个候选项使用动态规划，时间复杂度为 `O(query length × name length)`，空间复杂度为 `O(name length)`。候选项评分只在客户端进行且只检查命令名；命令描述不影响匹配。菜单选择仍派发所选的精确名称，而 space 与 Enter 裁决继续要求命令 token 精确匹配。
+评分器对每个候选项使用动态规划，时间复杂度为 `O(query length × name length)`，空间复杂度为 `O(name length)`。候选项评分只在客户端进行且只检查命令名；命令描述不影响匹配。菜单选择仍派发所选的精确名称，而空格键和 Enter 键的判定逻辑仍要求命令 token 精确匹配。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **保留仅前缀匹配。** 否决，因为本功能要解决的用户无法准确回忆前缀的问题依然存在：`/cpt` 无法发现 `/compact`。
 
@@ -22,6 +22,6 @@ Web 命令菜单要求按命令名前缀匹配，因此用户只记得关键字
 
 **使用通用模糊搜索依赖。** 否决，因为该界面只需对小型命令目录使用一种受限的子序列规则；可配置搜索索引会增加 bundle 体积，并引入产品未使用的排名行为。
 
-## Consequences
+## 后果
 
-用户可以凭按顺序记得的字母发现命令；只要目录相同，排名就保持稳定。评分刻意采用启发式规则：与分隔符对齐的匹配可能排在原始跨度更短的匹配之前。包（package）测试固定各项排名因素以及同分时的稳定顺序，组装后的 Web 回放快照固定 `/cpt` 解析为 `/compact` 的行为。精确执行语义保持不变。
+用户可以凭按顺序记得的字母发现命令；只要目录相同，排名就保持稳定。评分刻意采用启发式规则：与分隔符对齐的匹配可能排在原始跨度更短的匹配之前。包测试固定各项排名因素以及同分时的稳定顺序，组装后的 Web 回放快照固定 `/cpt` 解析为 `/compact` 的行为。精确执行语义保持不变。
diff --git a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml
index 059f6d2a0e..7858bc5077 100644
--- a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.md
 2026-08-05-composer-context-meter-breakdown.md: a757bcbc8bc57f4c3a16f663a9c922155b8bb575
-2026-08-05-composer-context-meter-breakdown.zh.md: 441fd3013f2db721527838955b5ce227865615f1
+2026-08-05-composer-context-meter-breakdown.zh.md: a6db86b437dedb848cb9bc9bf3bd1be23f2f355c
diff --git a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md
index 441fd3013f..a6db86b437 100644
--- a/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-composer-context-meter-breakdown.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Web 聊天的统计行把上下文占用率作为一个行内数字（`Context N% of X`）挤在计费分组之间。它回答了「有多满」，却回答不了「被什么占满」：没有任何地方展示窗口在系统提示词、工具 schema 与对话之间如何分配，而单行统计行也容纳不下这种明细。可用的数字还分属两套口径——来自 `contextPressure` 的提供方精确计费 prompt 规模，与 token-meter 的固定字符启发式——没有任何既有界面能在不混淆两者的前提下展示组成。
+Web 聊天的统计行把上下文占用率作为一个行内数字（`Context N% of X`）挤在计费分组之间。它回答了「有多满」，却回答不了「被什么占满」：没有任何地方展示窗口在系统提示词、工具 schema 与对话之间如何分配，而单行统计行也容纳不下这种明细。可用的数字还分属两套口径——来自 `contextPressure` 的提供方精确计费的提示词规模，与 token-meter 的固定字符启发式——没有任何既有界面能在不混淆两者的前提下展示组成。
 
 ## 决定
 
@@ -14,17 +14,17 @@ Web 聊天的统计行把上下文占用率作为一个行内数字（`Context N
 
 `dsh-session` 导出纯函数 `deriveEventMessage(event)`（此前只能通过 `Session` 方法访问，该方法现在委托给它），使 host 侧 fold 无需 `Session` 实例即可为表层节点计价。
 
-`dsh-token-meter` 把计价启发式抽取到 `src/estimate.ts`、把位置表层折叠抽取到 `src/surface-fold.ts`（两者都与测量服务逐字共享），并注册第三个会话投影 `contextBreakdown`，携带 `systemTokens` / `toolsTokens` / `messageTokens`。envelope 数字在每条 `request/header` 上经 `canonicalHeader` 按后者胜重新计价；消息数字在逐节点 `{seq, tokens}` 列表上重放 `foldSurfaceTokens`，因此它在每个事件边界上按构造等于 `measure().surfaceTokens`，压缩会像缩小下一个请求那样缩小它。这份共享折叠是全函数且总是新建数组——返回下一个表层而不是原地改写——从而保留了服务侧「先校验再提交」的重放事务：抛出时重放游标不前进，同一条畸形事件在重试时报同样的错。折叠表层中不存在的替换范围会直接抛出：已提交日志在追加时就经过表层校验，无法解析的范围是日志损坏，而不是可跳过的事件。
+`dsh-token-meter` 把计价启发式抽取到 `src/estimate.ts`、把位置表层折叠抽取到 `src/surface-fold.ts`（两者都与测量服务逐字共享），并注册第三个会话投影 `contextBreakdown`，携带 `systemTokens` / `toolsTokens` / `messageTokens`。envelope 数字在每条 `request/header` 上经 `canonicalHeader` 按后者胜重新计价；消息数字在逐节点 `{seq, tokens}` 列表上重放 `foldSurfaceTokens`，因此它在每个事件边界上按构造等于 `measure().surfaceTokens`，压缩（compaction）会像缩小下一个请求那样缩小它。这份共享折叠是全函数且总是新建数组——返回下一个表层而不是原地改写——从而保留了服务侧「先校验再提交」的重放事务：抛出时重放游标不前进，同一条畸形事件在重试时报同样的错。折叠表层中不存在的替换范围会直接抛出：已提交日志在追加时就经过表层校验，无法解析的范围是日志损坏，而不是可跳过的事件。
 
-`ui-conversation` 把上下文占用率从统计行移走（一个事实一个家），放到 composer 尾部的 `ContextMeter`：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，点击弹出的面板把提供方精确的百分比与 `~已用 / 容量` 标题，与 4px 分色分段进度条及带 `~` 前缀的组成明细行并列。两套口径刻意永不对账——启发式占比只用于切分进度条的彩色分段与明细行，且每个启发式数字都标 `~`，因为固定的「4 字符≈1 token」启发式会系统性低估 CJK 文本与代码。（本记录落地时，圆环、标题与进度条总长取的是提供方精确值；它们现在改读锚定在提供方读数上的 `projectedTokens`，因为裸样本看不见压缩——见[仪表对压缩的失明](../bug-fix/2026-08-05-context-meter-blind-to-compaction.md)。）标题是一整句本地化文案（`context.aria`，与圆环的无障碍名共用），在 `{percent}` 槽位处切开渲染，于是读数的位置由各语言自己决定——英文在前、中文在后——同时读数保留自己的字重；宽度算出为零的分段直接不渲染，否则 `.segment` 的 min-width 会在 0% 占用时画出一段填充色。
+`ui-conversation` 把上下文占用率从统计行移走（一个事实一个家），放到 composer 尾部的 `ContextMeter`：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，点击弹出的面板把提供方精确的百分比与 `~已用 / 容量` 标题与 4px 分色分段进度条及带 `~` 前缀的组成明细行并列。两套口径刻意永不对账——启发式数字只决定进度条各彩色分段之间的相对比例，并原样显示在明细行中；每个数字都标有 `~`，因为固定的「4 字符≈1 token」启发式会系统性低估 CJK 文本与代码。（本记录落地时，圆环、标题与进度条总长取的是提供方精确值；它们现在改读锚定在提供方读数上的 `projectedTokens`，因为裸样本看不见压缩——见[仪表对压缩的失明](../bug-fix/2026-08-05-context-meter-blind-to-compaction.md)。）标题是一整句本地化文案（`context.aria`，与圆环的无障碍名共用），在 `{percent}` 槽位处切开渲染，于是读数的位置由各语言自己决定——英文在前、中文在后——同时读数保留自身独立的强调样式；宽度算出为零的分段直接不渲染，否则 `.segment` 的 min-width 会在 0% 占用时画出一段填充色。
 
 ## 备选方案
 
 **在客户端从已加载窗口推导组成。** 窗口是日志的连续后缀：携带系统提示词与工具 schema 的 `request/header` 事件可能在窗口之外，翻页还会让数字悄悄变化。只有持久的 host 侧投影能在翻页与压缩后幸存，这正是数据以第三个投影而非聊天窗口 fold 的形式过线的原因。
 
-**把启发式明细行按比例缩放到与 `pressureTokens` 相加一致。** 强行对账是在捏造精度：压力滞后一个请求，还包含估算器从不建模的提供方封装开销，会让明细行在组成毫无变化时也跟着变动。最终选择以显式 `~` 展示估算器的真实口径。
+**把启发式明细行按比例缩放，使其总和等于 `pressureTokens`。** 强行对账是在捏造精度：压力滞后一个请求，还包含估算器从不建模的提供方封装开销，会让明细行在组成毫无变化时也跟着变动。最终选择以显式 `~` 展示估算器的真实口径。
 
-**更细的类别（rules、skills、MCP 工具，如 Claude Code 的 `/context`）。** 在这里不可分：harness 在请求标头存在之前就把这些贡献折入系统文本与工具列表，因此三个类别是诚实的分辨率。
+**更细的类别（rules、skill（技能）、MCP 工具，如 Claude Code 的 `/context`）。** 在这里不可分：harness 在请求标头存在之前就把这些贡献折入系统文本与工具列表，因此三个类别是诚实的分辨率。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
index 65d14e9aa4..2ce390fda0 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
 2026-08-05-context-form-vocabulary.md: 618c11b925208d09a62d10101656e3358e327ddb
-2026-08-05-context-form-vocabulary.zh.md: 66278b261f23601461c96f08e87ea58766b2bfc2
+2026-08-05-context-form-vocabulary.zh.md: b68672cd3338a11ea7b924198ce81380f99296fa
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
index 66278b261f..b68672cd33 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
@@ -1,41 +1,41 @@
-# Agent Note：由生产方声明的上下文形态
+# Agent Note: 由生产方声明的上下文形态
 
 Status: implemented
 
 [English](2026-08-05-context-form-vocabulary.md) | 中文
 
-## Problem
+## 问题
 
 每一条已记录的非用户 `user/message` 都通过同一个内容区渲染：把整条消息序列化成内联 JSON。读者展开一行，看到的是 `{ "content": [ { "type": "text", "text": "…\n\n…" } ], "source": { … } }`——转义把唯一值得读的东西（面向模型的散文）压成了一行，而来源信息又和它挤在同一坨里。
 
-在标题栏写出生产者（[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)）解决了「这是谁加的」。它解决不了「加进来的是什么东西」，因为日志里根本没有这句话。注入上下文不是一种形状：对账后的 `AGENTS.md`、可用 skill 的目录、运行时策略快照、子 agent 的汇报，彼此之间的差别不亚于终端卡片与 diff 卡片，然而这四者呈现出来是同一堵转义 JSON 的墙。
+在标题栏写出生产者（[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)）解决了「这是谁加的」。它解决不了「加进来的是什么东西」，因为日志里根本没有这句话。注入上下文不是一种形状：对账后的 `AGENTS.md`、可用 skill（技能）的目录、运行时策略快照、subagent 的汇报，彼此之间的差别不亚于终端卡片与 diff 卡片，然而这四者呈现出来是同一堵转义 JSON 的墙。
 
 工具面早就解决过同一个形状问题。`ToolCallView` 只有三种卡片，而不是每个工具一种，由工具自己声明本次调用属于哪一种。上下文没有对应物：既没有形状词汇表，生产方也无从声明自己发出的是哪一种。
 
-## Decision
+## 决策
 
 `MessageSource` 新增一个可选、由生产方声明的 `form: ContextForm`——一份关于信息**形状**的小型 tagged 词汇表，与 `kind` 相互独立：
 
 - `kind` 回答**由谁产生**，保持纯粹的溯源语义。
 - `form` 回答**这是何种形态的信息**。多个生产方可以共用一种形态，一个生产方在一次会话中也可以发出多种。
 
-该词汇表是语义的，绝不涉及视觉。取值只陈述「内容是某个文件的指令」或「是一份可用项目录」；颜色、图标、排序、默认折叠状态归消费方管，不得进入这个联合类型。它随生产方补齐各自形态所需的结构化字段而逐个增长。本次声明两个：
+该词汇表是语义的，绝不涉及视觉。取值只陈述「内容是某个文件的指令」或「是一份可用项目录」；颜色、图标、排序、默认折叠状态归消费方管，不得进入这个联合类型。它随生产方补齐各自形态所需的结构化字段而逐个增长。当前词汇表声明六种形态：
 
 **`instructions`**——从工作区文件中读出的指令。`workspace-context` 在启动基线与后续增量上都声明它；其既有的 `changes[]` 已经携带了呈现所需的路径、动作与 digest，因此没有新增字段。内容区在正文之上列出对账过的文件，并原样保留 `<system-reminder>` 包装：那层包装本就是模型读到的一部分，隐藏它会歪曲这次请求。
 
-**`catalog`**——本会话可用项的目录，随变化重新发布。`dsh-tool-skill` 从共享的 `plugin` kind 迁到自有的 `skill-catalog` 来源，携带 `entries`（本次发布的 `name`／`description` 对）与替换目录上的 `update`，后者由内容区渲染成替换提示。内容区直接列出这些条目，不再从散文里反解 `<available_skills>` 块。
+**`catalog`**——本会话可用项的目录，随变化重新发布。`dsh-tool-skill` 从共享的 `plugin` kind 迁到自有的 `skill-catalog` 来源，携带 `entries`（本次发布的 `name`／`description` 对）以及替换时的 `update`，后者由内容区渲染成替换提示。内容区直接列出这些条目，不再从散文里反解 `<available_skills>` 块。
 
 条目记录的是**未转义**的发布事实。伪 XML 转义属于 `<available_skills>` 这层为模型而设的框架，因此只在渲染该框架时施加、从不存储；否则消费方要正确展示含 `<` 的描述就得知道框架的编码方式，本决策刚移除的框架知识会换一种形式泄漏回来。`escapeText` 确定且单射，故对未转义条目取 digest 与此前完全等价，重新发布语义不变，面向模型的文本逐字节不变。
 
-这次迁移同时挪动了目录的**身份**：重新发布用的 digest 现在覆盖持久条目而非渲染文本，于是面向模型的包装再也无法左右是否需要重新发布，那段从已记录消息里切出条目的文本切分逻辑也随之删除。若恢复的会话中最新目录早于本次改动，会重新发布一次——发布前阶段的姿态允许这样做。有一种情形不会自愈：当那份旧格式目录是唯一的一份、且当前视图没有任何 skill 时，插件看不到已发布目录，也就不会发出 tombstone，模型手里会留着一份无人替换的过期目录。发布前阶段的姿态（「后端拒绝旧的磁盘格式」）允许这一点；此处如实记录，而不是只写乐观路径。
+这次迁移同时挪动了目录的**身份**：重新发布用的 digest 现在覆盖持久条目而非渲染文本，于是面向模型的包装再也无法左右是否需要重新发布，那段从已记录消息里切出条目的文本切分逻辑也随之删除。若恢复的会话中最新目录早于本次改动，会重新发布一次——发布前阶段的姿态允许这样做。有一种情形不会自愈：当那份旧格式目录是唯一的一份、且当前视图没有任何 skill 时，插件看不到已发布目录，也就不会发出 tombstone，模型手里会留着一份无人替换的陈旧目录。发布前阶段的姿态（「后端拒绝旧的磁盘格式」）允许这一点；此处如实记录，而不是只写乐观路径。
 
 **`snapshot`**——会被同一生产方后续快照取代的当前状态。运行时快照、`time-context`、`tmux-context` 声明它。`renderContextSections()` 暴露出装配时的具名贡献——`renderContextSnapshot()` 本来就是把它们拼给模型的——因此内容区能把每一段归属到产生它的子系统，而不必去切分已经拼好的散文。两个单贡献生产方各记录一段。运行时快照的「已清空」标记没有任何贡献可归属，因此不声明形态。
 
 **`notice`**——刚刚发生了什么的一次性说明。`tool-tasks`、`tool-goal` 收尾、`plan-mode` 切换与 `repeat-tool-guard` 提醒都带 `summary` 声明它，而该摘要出现在**折叠态**行上：notice 的全部意义就是不展开也能读完。摘要在其输入是调用方文本时自行封顶（任务的 label 与状态 detail 本身没有长度约束）。Goal 状态变更仍是由领域层持有的 `goal/change` 事件，而非模型上下文，因此不声明 form。
 
-**`relay`**——另一个 agent 发给本 agent 的消息。两个子 agent 定向来源都声明它；发送方以来源已记录的不透明会话 id 呈现，因为本客户端无法把它解析成标题。
+**`relay`**——另一个 agent（智能体）发给本 agent 的消息。两个 subagent 定向来源都声明它；发送方以来源已记录的不透明会话 id 呈现，因为本客户端无法把它解析成标题。
 
-**`recall`**——从另一个会话日志搬来的材料。`session-reference` 声明它，且不需要新增字段：其 references 已经记录了标题、保留与省略条数、截断标记，内容区把这些放在最前面——召回上下文在进入时是有界的，隐藏省略条数的卡片会夸大模型实际收到的内容。
+**`recall`**——从另一个会话日志搬来的材料。`session-reference` 声明它，且不需要新增字段：其 references 已经记录了标签、保留与省略条数、截断标记，内容区把这些放在最前面——召回上下文在进入时是有界的，隐藏省略条数的卡片会夸大模型实际收到的内容。
 
 两个读取器都是**全有或全无**：一条不可读的条目即判定整条记录不可用，而不是把它丢掉——会替换掉面向模型文本的内容区，不得给出自信但残缺的「模型读到了什么」。行上的形态标记报告的是实际渲染出的形态，而非声明的形态。
 
@@ -45,9 +45,9 @@ Status: implemented
 
 ## 为什么不做 presenter 注册表
 
-工具接缝把它的词汇表与 `presentCall(args)` 配对，那是每个工具在 host 侧实现的纯函数。上下文刻意不设对应物，因为输入的归属不同：工具的 `args` 由**模型**按面向模型的 schema 生成，翻译步骤无法回避；而上下文的 `source` 由**生产方插件**自己构造，不受任何外部约束，完全可以直接记录呈现所需的事实。加一层注册表买到的是一次没人需要的翻译，代价却是一个 host 计算点、每条上下文消息一个 wire 字段、以及每个生产方包都要出浏览器 bundle（客户端纯度门禁禁止 host 包贡献组件）。
+工具 seam 把它的词汇表与 `presentCall(args)` 配对，那是每个工具在 host 侧实现的纯函数。上下文刻意不设对应物，因为输入的归属不同：工具的 `args` 由**模型**按面向模型的 schema 生成，翻译步骤无法回避；而上下文的 `source` 由**生产方插件**自己构造，不受任何外部约束，完全可以直接记录呈现所需的事实。加一层注册表买到的是一次没人需要的翻译，代价却是一个 host 计算点、每条上下文消息一个 wire 字段、以及每个生产方包都要出浏览器 bundle（客户端纯度门禁禁止 host 包贡献组件）。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **在客户端把来源 kind 映射到渲染器。** 写起来最省，也不用改格式，但它把生产方知识放回了客户端：此后每新增一个 kind 都要客户端发版才能渲染成 opaque 以外的东西，而外部日志根本无法分类。它还会重新引入[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)刚为名称去掉的那种耦合。
 
@@ -57,17 +57,17 @@ Status: implemented
 
 **把 instructions 渲染成 Markdown。** 正文本来就是 Markdown 文件，渲染出来更好读。但文本同时携带 `<system-reminder>` 包装，Markdown 渲染器会把它当原始 HTML 丢弃，于是 Markdown 内容区会悄悄隐藏模型读到的一部分。推迟到生产方按文件结构化记录内容之后再做。
 
-## Testing
+## 测试
 
 - `packages/client/runtime` 钉住形态投影，包括必须降级为 opaque 的未知值、空值、类型不符与缺失。
 - `packages/client/ui-conversation` 逐个钉住内容区：opaque 的换行留存与来源字段、instructions 的文件列表与原样包装、catalog 的条目列表，以及条目不可用的 catalog 回落到 opaque。
 - `packages/skill/tool-skill` 钉住首次发布与替换时的新来源、由持久条目驱动的重新发布行为，以及畸形持久目录不打断步骤观察。
 - 无密钥的组装 Web seeded-history 场景在 Chromium 中展开一条真实的 `instructions` 上下文，断言其文件列表、原样包装与未改动的展开项几何。`catalog` 没有组装态覆盖：隔离脚手架不发布任何 skill，因此没有目录能进入浏览器场景。
 
-## Consequences
+## 后果
 
 - 读者不展开就能知道加进来的是什么，展开之后读到的也不再是转义 JSON。
 - 持久 `MessageSource` 现在在溯源之外还承载一个语义分类。这条边界是承重的：只放事实与形状，绝不放呈现。想要更好卡片的生产方应当记录更好的事实。
 - 目录身份不再依赖面向模型的散文，删掉了那条可能把「改了措辞」误判为「改了内容」的文本切分路径。
-- 除两个 hook 桥接外，每个已发布的生产方现在都声明了形态。桥接按设计保持 opaque：其内容是外部程序打印出来的任意文本，无法承诺任何形状。未知 kind 与不可读记录同样落在这里。
+- 除两个钩子桥接外，每个已发布的生产方现在都声明了形态。桥接按设计保持 opaque：其内容是外部程序打印出来的任意文本，无法承诺任何形状。未知 kind 与不可读记录同样落在这里。
 - `ContextFormed` 按 `form` 判别，因此生产方无法在缺少该形态所需事实的情况下声明它——没有 summary 的 `notice`、没有 sections 的 `snapshot`，都会编译失败。
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
index 4255886987..63b0efa3aa 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md
 2026-08-05-feedback-gated-session-telemetry.md: 7d923a7e4cf61e8d1119187564b87e4cbb2065b7
-2026-08-05-feedback-gated-session-telemetry.zh.md: 2862162c0c36e5194846c7e1c7bbc24230ce90aa
+2026-08-05-feedback-gated-session-telemetry.zh.md: e2fa6f9561de6e7295cbf860527c7d7915fec0bf
diff --git a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
index 2862162c0c..e2fa6f9561 100644
--- a/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：反馈门控的会话遥测
+# Agent Note: 反馈门控的会话遥测
 
 Status: implemented
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
index 51401adfdc..451f1aa092 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
 2026-08-05-pwsh-ui-bash-parity.md: 815b448b894e9c53b4c4a2076f6b94fdd316dd35
-2026-08-05-pwsh-ui-bash-parity.zh.md: 967c5a9e1409028043dc5028fdca640ddfeb1acc
+2026-08-05-pwsh-ui-bash-parity.zh.md: 9ab4bc18f3f9d564e0f63ef326a6b11974322765
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
index 967c5a9e14..9ab4bc18f3 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
@@ -6,23 +6,23 @@ Status: implemented
 
 ## Problem
 
-[pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 让 `dsh-tool-pwsh` 在执行、marker 与后台任务上行为可互换，但明确推迟了面向人类的一半：完成的 pwsh 前台调用呈现为通用 `console` 围栏卡片，而 bash 工具的完成调用呈现为带解析退出状态 pill 的 terminal 卡。拥有此缺口的路线图（[Windows 默认改用 pwsh](../../proposed/feature/2026-08-01-windows-pwsh-default.md)）把 "pwsh TUI/GUI 渲染" 列为阶段 2，但 TUI 包已被移除，使 Web 表面成为该缺口唯一影响的 UI。
+[pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 让 `dsh-tool-pwsh` 在执行、marker 与后台任务上行为可互换，但明确推迟了面向人类的一半：完成的 pwsh 前台调用呈现为通用 `console` 围栏卡片，而 bash 工具的完成调用呈现为带解析退出状态 pill 的 terminal 卡。拥有此缺口的路线图（[Windows 默认改用 pwsh](../../proposed/feature/2026-08-01-windows-pwsh-default.md)）把「pwsh TUI/GUI 渲染」列为阶段 2，但 TUI 包已被移除，使 Web 表面成为该缺口唯一影响的 UI。
 
 ## Decision
 
 `dsh-tool-pwsh` 的 `presentResult` 现在逐调用镜像 `dsh-tool-bash`：完成的前台结果是 `terminal` 卡，输出正文为去 marker 的渲染文本，退出状态 pill 为解析出的 `exitCode`/`signal`；后台 ack 与 `isError` 结果保持通用 `console` 围栏卡片；非单一文本块结果保持不变（`undefined`）。
 
-解析是共享而非复制：`parseExitStatus`/`ParsedExitStatus` 从 `dsh-tool-bash` 的私有 render 模块迁入 `@deepseek-ai/dsh-bash` seam 包（由其 index 导出），`dsh-tool-bash` 的 `render.ts` 再导出它，使源平面消费方保持单一导入根。两个工具的渲染器发出相同的 `[exit code: N]` / `[killed by signal: X]` marker，因此一个由 seam 拥有的逆解析永远不会在孪生之间漂移——与 [bash-env 抽取](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 处理 `DSH_*` 注册表时相同的 "共享而非复制" 形态。
+解析是共享而非复制：`parseExitStatus`/`ParsedExitStatus` 从 `dsh-tool-bash` 的私有 render 模块迁入 `@deepseek-ai/dsh-bash` seam 包（由其 index 导出），`dsh-tool-bash` 的 `render.ts` 再导出它，使源平面消费方保持单一导入根。两个工具的渲染器发出相同的 `[exit code: N]` / `[killed by signal: X]` marker，因此一个由 seam 拥有的逆解析永远不会在孪生之间漂移——与 [bash-env 抽取](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 处理 `DSH_*` 注册表时相同的「共享而非复制」形态。
 
-Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 terminal 卡桥接（`dsh-client-ui-conversation` 的 `terminal-card-model`）映射任意 `card: 'terminal'` 结果视图，因此 pwsh presenter 变更直接流经 bash 已有的同一渲染路径。折叠的工具行有一处客户端分类条目：`classifyTool('pwsh')` 现在归入 shell 家族行（`bash` variant，自有 `Pwsh` 标题），而非通用的 `others` "Tool call" 行。一条 keyless 浏览器通道（`apps/web/tests/pwsh-terminal.e2e.ts`）播种一个会话，其 pwsh 调用/结果在回放时由真实工具呈现（api-proxy 从已记录的 args/result 内容重新计算视图），并钉住 terminal 卡 golden，包括退出 pill 与运行状态点。
+Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 terminal 卡桥接（`dsh-client-ui-conversation` 的 `terminal-card-model`）映射任意 `card: 'terminal'` 结果视图，因此 pwsh presenter 变更直接流经 bash 已有的同一渲染路径。折叠的工具行有一处客户端分类条目：`classifyTool('pwsh')` 现在归入 shell 家族行（`bash` variant，自有 `Pwsh` 标题），而非通用的 `others`「Tool call」行。一条 keyless 浏览器通道（`apps/web/tests/pwsh-terminal.e2e.ts`）播种一个会话，其 pwsh 调用/结果在回放时由真实工具呈现（api-proxy 从已记录的 args/result 内容重新计算视图），并钉住 terminal 卡 golden，包括退出 pill 与运行状态点。
 
 ## Alternatives considered
 
-**从 `@deepseek-ai/dsh-tool-bash/src/render.ts` 导入 `parseExitStatus`。** 否决：workspace 导入在构建产物中保持外部引用，因此 `tool-pwsh` 会在每个消费方闭包中新增对 `tool-bash` 的硬运行时依赖（包括刻意只挂 pwsh 孪生、不挂 bash 的组合），且兄弟工具为其单个函数依赖孪生会颠倒包间关系。seam 迁移把共享契约放在两个工具本就依赖的包上。
+**从 `@deepseek-ai/dsh-tool-bash/src/render.ts` 导入 `parseExitStatus`。** 否决：workspace 导入在构建产物中保持外部引用，因此 `tool-pwsh` 会在每个消费方闭包中新增对 `tool-bash` 的硬运行时依赖（包括刻意只挂 pwsh 孪生、不挂 bash 的组合），且兄弟工具为其单个函数依赖孪生会颠倒包间关系。seam 迁移把共享约定放在两个工具本就依赖的包上。
 
 **新建专用呈现包（如 `@deepseek-ai/dsh-shell-present`）。** 否决：为一个纯函数新建包要付出 manifest、module-graph/目录再生成与 README 面的成本；`@deepseek-ai/dsh-bash` 已在两个工具的闭包中，且已拥有该解析重建的 `BashRunResult` 事实。
 
-**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：parity 评审的核心发现正是"复制的文本契约缺少共享实现就会漂移"；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的契约。
+**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：parity 评审的核心发现正是「复制的文本约定缺少共享实现就会漂移」；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的约定。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.i18n.yaml
index 90d3d8e1f5..bd7c5a1cd6 100644
--- a/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.md
 2026-08-05-web-preview-product-badge.md: c20dedf8caa497d17a577cf46261c6a24c09a1ce
-2026-08-05-web-preview-product-badge.zh.md: c428dabf2a9a2ece2f90b0c3a527835a494c7cb7
+2026-08-05-web-preview-product-badge.zh.md: 415a7cb3eb02030ef5481f4eba9110b56547ce64
diff --git a/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.zh.md b/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.zh.md
index c428dabf2a..415a7cb3eb 100644
--- a/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-web-preview-product-badge.zh.md
@@ -1,6 +1,6 @@
-# Agent Note：Web 预览版产品徽标
+# Agent Note: Web 预览版产品徽标
 
-状态：已实现
+Status: implemented
 
 [English](2026-08-05-web-preview-product-badge.md) | 中文
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
index 222ed1ebbe..d89233e8eb 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
 2026-08-06-bundled-dsh-badge-skill.md: 512f67ca347ca311a1f80fef932f6af8c91b0fe9
-2026-08-06-bundled-dsh-badge-skill.zh.md: 88fcadf66944cb91419441be3916ae04968be663
+2026-08-06-bundled-dsh-badge-skill.zh.md: cedb03325f3e963c3fa217b72dcfce31eb44bfe7
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
index 88fcadf669..cedb03325f 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 交付的 CLI 组合将 `skill-badge` 声明为禁用。启用这个现有配置行就是显式选择加入；禁用它的安装实例不会公开任何徽章 skill（技能），也不会获得任何模型可见内容。
 
-该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank，因此用户自有的 `dsh-badge` 定义可通过注册表的常规优先级契约覆盖它。提供方释放时，注册表拥有的 effect 会移除该贡献。
+该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank，因此用户自有的 `dsh-badge` 定义可通过注册表的常规优先级约定覆盖它。提供方释放时，注册表拥有的 effect 会移除该贡献。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
index 7550af746a..9b0e536dad 100644
--- a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.md
 2026-08-06-resolved-theme-color-metadata.md: 2f7a6f0bde5e75aeb6769939cae54d5319aa5bae
-2026-08-06-resolved-theme-color-metadata.zh.md: a6d530f841d5c744fc88831f9cb685d1ab5027b6
+2026-08-06-resolved-theme-color-metadata.zh.md: 30d5aa3c68db090ff33f8dde0e70804d0d699459
diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
index a6d530f841..30d5aa3c68 100644
--- a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
@@ -10,13 +10,13 @@ Web 客户端可以独立于操作系统偏好解析主题，因此 manifest（
 
 ## 决策
 
-ui-layout 的 `ThemePresenter` 拥有一个 `<meta name="theme-color">`，与根元素上的 `color-scheme`、深色调色板属性和内联 token 写入并列。在应用解析后快照的调色板与 token 覆盖值之后，呈现器读取 body 计算样式中的 `background-color`，写入该元数据元素，再将该节点插入 document head。后续快照会更新同一节点，资源释放时则移除它。
+ui-layout 的 `ThemePresenter` 拥有一个 `<meta name="theme-color">`，与根元素上的 `color-scheme`、深色调色板属性和内联 token 写入并列。在应用解析后快照的调色板与 token 覆盖值之后，呈现器读取 body 计算样式中的 `background-color`，写入该元数据元素，再将该节点插入 document head。后续快照会更新同一节点，dispose（资源释放）时则移除它。
 
 渲染后的 body 背景仍是颜色真源。PWA manifest 不包含静态 `theme_color` 或 `background_color`，`ThemeDefinition` 也不新增可能与 token 调色板偏离的第二个颜色字段。这样一来，注册主题的基础背景 token 也能通过页面界面使用的同一条应用路径作用于浏览器界面。
 
 ## 验证
 
-呈现器的单元测试契约覆盖浅色和深色模式下的计算颜色、节点复用及资源释放。ui-layout 组合测试覆盖初始插入、事件驱动的复用和 fiber 清理。Web 浏览器设置场景通过实际交付的组合依次驱动 Light、Dark、System、操作系统偏好变化和重新加载，并断言页面始终只有一个元数据元素，其内容等于计算后的 body 背景且控制台无错误。这项元数据变更不会出现在渲染后的无障碍树输出中，因此场景现有的预期输出保持不变。
+呈现器的单元测试约定覆盖浅色和深色模式下的计算颜色、节点复用及 dispose。ui-layout 组合测试覆盖初始插入、事件驱动的复用和 fiber 清理。Web 浏览器设置场景通过实际交付的组合依次驱动 Light、Dark、System、操作系统偏好变化和重新加载，并断言页面始终只有一个元数据元素，其内容等于计算后的 body 背景且控制台无错误。这项元数据变更不会出现在渲染后的无障碍树输出中，因此场景现有的预期输出保持不变。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.i18n.yaml
index eb0a37d991..6db5825af2 100644
--- a/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.md
 2026-08-06-session-completed-done-dot.md: bd6911ce137f1272090c86c029710c9f4054ee6d
-2026-08-06-session-completed-done-dot.zh.md: 9ec2199a29d1307c3ebd0238e84d5f90d36fe21c
+2026-08-06-session-completed-done-dot.zh.md: 41da7d126a29a5f9341ca8b87da343fdbff7601c
diff --git a/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.zh.md b/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.zh.md
index 9ec2199a29..41da7d126a 100644
--- a/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.zh.md
@@ -6,20 +6,20 @@ Status: implemented
 
 ## Problem
 
-操作者派发任务后切换到其他会话，原会话完成时没有任何信号。运行指示停止后，该行与普通空闲会话看起来完全一样，操作者只能反复查看列表或很晚才发现工作已完成。等待交互的琥珀点只覆盖需要操作者输入的会话，不覆盖"只是干完了活"的会话。
+操作者派发任务后切换到其他会话，原会话完成时没有任何信号。运行指示停止后，该行与普通空闲会话看起来完全一样，操作者只能反复查看列表或很晚才发现工作已完成。等待交互的琥珀点只覆盖需要操作者输入的会话，不覆盖「只是干完了活」的会话。
 
 ## Decision
 
-`SessionManager` 持有客户端侧的完成提醒集合，与待交互位并列：非当前会话发生 running→idle 边沿时点亮其提醒；`select()`/`selectSubagent()` 消费掉提醒；重新开始一轮运行会熄灭提醒并在再次完成时重新点亮；会话被移除时清理提醒。该位经 `SessionListEntry` → `SessionSummary`（可选字段，缺省 = 无提醒）进入工作区浏览区，其会话行与搜索结果行渲染现有的 `StateDot` `done` 状态——运行中仍显示转圈，无提醒的空闲会话不显示任何点——悬停卡片将该提醒标注为"已完成 / Completed"。
+`SessionManager` 持有客户端侧的完成提醒集合，与待交互位并列：非当前会话发生 running→idle 边沿时点亮其提醒；`select()`/`selectSubagent()` 消费掉提醒；重新开始一轮运行会熄灭提醒并在再次完成时重新点亮；会话被移除时清理提醒。该位经 `SessionListEntry` → `SessionSummary`（可选字段，缺省 = 无提醒）进入工作区浏览区，其会话行与搜索结果行渲染现有的 `StateDot` `done` 状态——运行中仍显示转圈，无提醒的空闲会话不显示任何点——悬停卡片将该提醒标注为「已完成 / Completed」。
 
-提醒仅存在于内存中且按浏览器实例隔离。它跨连接代存活——传输抖动不会使"你还没回来看"失效——但页面刷新后重置。
+提醒仅存在于内存中且按浏览器实例隔离。它跨连接代存活——传输抖动不会使「你还没回来看」失效——但页面刷新后重置。
 
 ## Consequences
 
-侧边栏行状态成为三个互斥信号：绿 = 已完成且未查看，琥珀 = 等待操作者输入，蓝 = 运行中。无 wire、磁盘或配置格式变更：`SessionSummary.completed` 为可选字段，现有消费者与测试 fixture 保持有效，只有工作区浏览区读取它。完成边沿在每次列表变更与拉取时即时检测（仅在建快照时检测会把连续两个状态帧折叠为一次观察，从而漏掉完成事件）。
+侧边栏行状态成为三个互斥信号：绿 = 已完成且未查看，琥珀 = 等待操作者输入，蓝 = 运行中。协议格式（wire format）、磁盘格式或配置格式均无变更：`SessionSummary.completed` 为可选字段，现有消费方与 fixture（测试前置数据） 保持有效，只有工作区浏览区读取它。完成边沿在每次列表变更与拉取时即时检测（仅在建快照时检测会把连续两个状态帧折叠为一次观察，从而漏掉完成事件）。
 
 ## Alternatives considered
 
-- **组件本地 UI 状态。** 已拒绝：侧边栏折叠时会卸载，且多个界面（分组树、单列表、搜索）需要同一状态位；manager 本就持有运行状态迁移与选中状态，manager 持有的集合是所有界面都能投影的唯一事实源。
+- **组件本地 UI 状态。** 已拒绝：侧边栏折叠时会卸载，且多个界面（分组树、扁平列表、搜索）需要同一状态位；manager 本就持有运行状态迁移与选中状态，manager 持有的集合是所有界面都能投影的唯一真源。
 - **仅从状态帧做事件驱动点亮。** 已拒绝：列表拉取本身也可能携带 running→idle 迁移（刷新在途时会话已完成）；提醒需对每次变更与拉取做对账。
-- **持久化提醒。** 已拒绝：提醒的含义是"此浏览器里你还没查看该会话"；刷新会恢复选中状态且用户正看着列表，持久化位只会过期。
+- **持久化提醒。** 已拒绝：提醒的含义是「此浏览器里你还没查看该会话」；刷新会恢复选中状态且用户正看着列表，持久化位只会变得陈旧。
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
index d13ede02d2..000c72f6ed 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-web-install-manifest.md
 2026-08-06-web-install-manifest.md: d400c6e586f4b735fa8e3dcc4899c97e45ac89c1
-2026-08-06-web-install-manifest.zh.md: a7fee0248261e8d0597bb773d4f390973147337b
+2026-08-06-web-install-manifest.zh.md: d32ccf25c7b0e13a4094af4364a97385032462b7
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
index a7fee02482..d32ccf25c7 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Web 构建产物已有文档标题和 favicon，却没有可供浏览器发现稳定安装身份、启动边界或安装后呈现方式的 manifest（元数据清单）。添加这类元数据也可能暗示应用并不具备的能力：service worker 会让人以为应用提供离线契约，而单一语言或调色板取值会错误描述这个能够解析浅色与深色主题的双语 UI。
+Web 构建产物已有文档标题和 favicon，却没有可供浏览器发现稳定安装身份、启动边界或安装后呈现方式的 manifest（元数据清单）。添加这类元数据也可能暗示应用并不具备的能力：service worker 会让人以为应用提供离线约定，而单一语言或调色板取值会错误描述这个能够解析浅色与深色主题的双语 UI。
 
 ## 决策
 
@@ -24,7 +24,7 @@ Web 构建产物测试解析输出的 manifest，并固定完整的元数据对
 
 ## 曾考虑的替代方案
 
-**添加 service worker，并宣称应用支持离线。** 不予采纳，因为只缓存应用外壳，却不定义会话传输、失效策略、失败行为和升级语义，会形成具有误导性的不完整离线契约。
+**添加 service worker，并宣称应用支持离线。** 不予采纳，因为只缓存应用外壳，却不定义会话传输、失效策略、失败行为和升级语义，会形成具有误导性的不完整离线约定。
 
 **声明单一的 `lang`。** 不予采纳，因为没有任何一种语言足以描述双语产品界面；省略该字段可避免声称安装后的体验由某一种区域设置独占。
 
@@ -36,4 +36,4 @@ Web 构建产物测试解析输出的 manifest，并固定完整的元数据对
 
 ## 后果
 
-支持这一机制的浏览器可以发现以根路径为作用域的稳定安装身份和全屏偏好，而应用无需承诺离线行为。在路径前缀下部署该构建产物时，必须同时重新审视绝对路径的 manifest 链接，以及身份、启动、作用域和图标 URL。日后可能因浏览器特有的图标要求而新增变体；每一项有意的元数据变更都会同步更新精确的构建产物契约。
+支持这一机制的浏览器可以发现以根路径为作用域的稳定安装身份和全屏偏好，而应用无需承诺离线行为。在路径前缀下部署该构建产物时，必须同时重新审视绝对路径的 manifest 链接，以及身份、启动、作用域和图标 URL。日后可能因浏览器特有的图标要求而新增变体；每一项有意的元数据变更都会同步更新精确的构建产物约定。
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
index 7ea7b3b14f..5c5c945102 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
 2026-08-06-web-skill-tool-row.md: 04e8ffcd6e506142b569e60458af144233810bbd
-2026-08-06-web-skill-tool-row.zh.md: b96b3879f989f4f1934cdffaec83a283d74aa220
+2026-08-06-web-skill-tool-row.zh.md: ff1f068c87b8466609980a997b31e7ac666bcf47
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
index b96b3879f9..ff1f068c87 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
@@ -10,20 +10,20 @@ Web transcript（文本记录）通过通用后备行渲染 `skill` 调用，使
 
 ## 决策
 
-`ui-skill` 在 ui-tool 的 `tool.call.toolview` keyed slot 下注册 key 为 `skill` 的组件。该组件消费公开的 `ToolCallViewProps` owner 契约，并自行实现行 chrome，不导入 ui-tool 的展示内部实现。
+`ui-skill` 在 ui-tool 的 `tool.call.toolview` keyed slot 下注册 key 为 `skill` 的组件。该组件消费公开的 `ToolCallViewProps` owner 约定，并自行实现行 chrome，不导入 ui-tool 的展示内部实现。
 
 收起的行使用 14 像素的文档与闪光组合图标，并沿用 Bash 行的中性色层级：图标采用三级色，`Skill` 标题采用二级色，分隔符采用 caption 色，skill 名称采用三级色。运行、失败和中断调用分别沿用 transcript 的扫光、错误状态点加首行摘要，以及警告状态点语义。已结算调用可以通过整个摘要行展开一个高度上限为 260 像素的 `Instructions` 卡片，其中原样呈现持久化结果文本；用于跳转至 trajectory 的现有 `Inspect` 入口仍保留在卡片下方。
 
-该行的所有可见值均派生自当前 runtime 窗口中已配对的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。如果分页将调用留在窗口外，结果便没有工具身份，并继续使用通用后备路径，而不是扩展 history 协议契约。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
+该行的所有可见值均派生自当前 runtime 窗口中已配对的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。如果分页将调用留在窗口外，结果便没有工具身份，并继续使用通用后备路径，而不是扩展 history 协议格式约定。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
 
 ## 考虑过的替代方案
 
 - 保留通用工具行，只添加一个 `skill` 颜色选择器，并将其放在 `ui-conversation` 中。该方案仍会保留多余的输入外层结构和通用展开体，也会让 conversation 包拥有特定领域的视觉规则。
-- 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 在调用位于 runtime 窗口内时已经能够识别该工具，因此新的跨边界呈现值只会增加协议和快照表层，却不会支持其他消费方。
+- 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 在调用位于 runtime 窗口内时已经能够识别该工具，因此新的跨边界呈现值只会扩大协议和快照的变更面，却不会支持其他消费方。
 - 导出 conversation 包的私有 `ToolRow` 组件供复用。客户端包刻意对外暴露契约而非跨包组件；导出该组件会使独立功能包耦合到 conversation 的实现细节。
 
 ## 后果
 
-除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 契约、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
+除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 约定、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
 
 即使已安装的 skill 目录发生变化，冷回放仍保持确定性；在用户显式展开指令前，transcript 保持紧凑。仅含结果的 history 页有意使用通用后备路径；让这个边缘情况保持通用呈现，可以保留现有 history 协议，并将该功能限定在客户端呈现层。专用卡片有意显示工具完整封装的输出，而不是只提取 `<skill_instructions>`，从而原样保留模型实际收到的内容，也避免为 skill 结果格式再引入一个解析器。
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
index f513e90666..b6c1d59a6f 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
 2026-08-07-default-model-follows-the-picker.md: d20f0ab8b8c8bd19f596e6ef73f0a58d96c24d38
-2026-08-07-default-model-follows-the-picker.zh.md: 0d2821cb63407fe766e6fe3d36de31d9fc6f1c13
+2026-08-07-default-model-follows-the-picker.zh.md: fd27a0ce67a8e7f41d1a6b397039014f0ddb4854
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
index 0d2821cb63..fd27a0ce67 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
@@ -10,13 +10,13 @@ Status: implemented
 
 ## 决定
 
-`ApiProxyService` 把自己的 `{provider, model, reasoningEffort?}` 切片注册为 `api-gateway` 设置段：组合条目是 `base` 层，`settings.yaml` 把用户的选择叠加其上。`workspaceRoot` 留在段外——它是启动器事实，不是偏好。`reasoningEffort` 则是镜像的一例：它在段里、但**不在**插件配置里，因为 seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键。组合层设的推理等级因此会在此后每一次切到不支持推理的模型时继续存活——正是整段 `replace` 想要杜绝的那种滞留。何况推理等级本就是按模型的事实，它的部署级默认值属于适配器 profile，那里是按模型解析的。
+`ApiProxyService` 把自己的 `{provider, model, reasoningEffort?}` 切片注册为 `api-gateway` 设置段：组合条目是 `base` 层，`settings.yaml` 把用户的选择叠加其上。`workspaceRoot` 留在段外——它是启动器事实，不是偏好。`reasoningEffort` 则是相反的情形：它在段里、但**不在**插件配置里，因为 seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键。组合层设的推理等级因此会在此后每一次切到不支持推理的模型时继续存活——正是整段 `replace` 想要杜绝的那种滞留。何况推理等级本就是按模型的事实，它的部署级默认值属于适配器 profile，那里是按模型解析的。
 
 `session.selectModel` 把被接受的切换记录为新的默认值。没有另一个单独的手势：在输入框切模型**就是**选定默认值的方式。写入用 `replace` 而非 `update`——切到一个不支持推理的模型必须清掉已存的等级，而合并补丁会把它滞留下来，让下一个会话在它上面失败。存储失败只记日志，不撤销这次切换（它对自己所在的会话已经生效）；没有设置提供方的部署保留组合条目，切换只停留在进程内。
 
-`ApiProxyDefaults` 改为携带 `defaultTarget()` 与 `persistDefaultTarget()` 两个闭包，而不是扁平的 `provider`／`model` 字段，这样 `createApiProxy` 不需要知道设置这条缝的存在。
+`ApiProxyDefaults` 改为携带 `defaultTarget()` 与 `persistDefaultTarget()` 两个闭包，而不是扁平的 `provider`／`model` 字段，这样 `createApiProxy` 不需要知道设置 seam 的存在。
 
-`targetFor` 在**每一次**读取时解析各级，而不是只在创建时种一次 ref：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是活的默认值。两个方向都依赖这次重新读取。已经跑过一轮的会话此后永远从自己的日志推导，改默认值不会重定向它；而仍然空白的会话会用上它创建之后才保存的默认值——这一点很关键，因为新建会话是复用空白会话而不是再开一个，创建时种下的值恰好会在这个功能存在的意义所在的流程里显示已被取代的模型。
+`targetFor` 在**每一次**读取时解析各级，而不是只在创建时种一次 ref：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是活的默认值。两个方向都依赖这次重新读取。已经跑过一个轮次的会话此后永远从自己的日志推导，改默认值不会重定向它；而仍然空白的会话会用上它创建之后才保存的默认值——这一点很关键，因为新建会话是复用空白会话而不是再开一个，创建时种下的值恰好会在这个功能存在的意义所在的流程里显示已被取代的模型。
 
 存下来的路由不做注册表校验。默认值指向一条模型页已经删除的路由时，它照样作为 `current` 送到 `session.models`，匹配不到任何已公布的分组——而这正是让输入框选择器已有的回退提示重新选择、而不是显示一个部署根本够不着的模型的原因。
 
@@ -26,18 +26,18 @@ Status: implemented
 
 ## 后续：让发不出消息的会话禁止输入
 
-默认值指向一条模型页已删除的路由时，编辑器显示「选择模型」，输入框却仍接受消息，然后这一轮在适配器内部失败。两处改动关掉这个口子。
+默认值指向一条模型页已删除的路由时，编辑器显示「选择模型」，输入框却仍接受消息，然后该轮次会在适配器内部进行到一半时失败。两处改动关掉这个口子。
 
 宿主拒绝。`session.prompt` 检查是否有适配器服务该会话的路由，在开启轮次之前就以 `model-unavailable` 应答。这是执行边界：客户端禁用编辑器只是提示性设计，这个方法始终可被调用。
 
-编辑器变惰性。`session.models` 报告 `routable`，ui-model 经新的 `ctx.conversation.blocks` 注册表推送一个 block；输入栏渲染的仍是它在没有 Workspace 时就会渲染的那个禁用 textarea，只是把抬起方自己的本地化理由作为 placeholder——唯独模型 seat 被 block 刻意保留可用，因为用户正是靠选模型来解除它。推送方向是被迫的——ui-model 本就依赖 ui-conversation，因此 ui-conversation 读不回去。
+编辑器停止接受消息。`session.models` 报告 `routable`，ui-model 经新的 `ctx.conversation.blocks` 注册表推送一个块；输入栏渲染的仍是它在没有工作区时就会渲染的那个禁用 textarea，只是把阻断方自己的本地化理由作为 placeholder——唯独模型 seat 被块刻意保留可用，因为用户正是靠选模型来解除它。推送方向是被迫的——ui-model 本就依赖 ui-conversation，因此 ui-conversation 读不回去。
 
-闸门是 `routable`，**不是**「当前目标匹配不到任何已公布分组」。目录成员关系按设计是咨询性的：一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用，在那里阻断会破坏一种受支持的配置（对一条活着的路由收窄 `models` 列表）。`routable` 在客户端还是三值的——首次加载之前或加载失败之后的 `null` 绝不阻断，因此慢的或够不着的宿主锁不死一个本来能用的编辑器。
+闸门是 `routable`，**不是**「当前目标匹配不到任何已公布分组」。目录成员关系按设计只作参考：一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用，在那里阻断会破坏一种受支持的配置（对一条活着的路由收窄 `models` 列表）。`routable` 在客户端还是三值的——首次加载之前或加载失败之后的 `null` 绝不阻断，因此慢的或够不着的宿主锁不死一个本来能用的编辑器。
 
 ## 考虑过的替代方案
 
 - **存下来的路由未注册时回落到组合条目。** 否决：那样输入框会显示出厂的 DeepSeek 模型而不是提示选择，既是静默切到用户没选的提供方，也与要求的行为正好相反。
-- **校验并清空失效的默认值。** 否决：目录成员关系按设计是咨询性的（`buildModelCatalog` 有注释说明），适配器可以服务一个自己目录已不再公布的模型；自动修复会破坏这个刻意保留的情形。
+- **校验并清空陈旧的默认值。** 否决：目录成员关系按设计只作参考（`buildModelCatalog` 有注释说明），适配器可以服务一个自己目录已不再公布的模型；自动修复会破坏这个刻意保留的情形。
 - **用 `settings.update` 合并补丁。** 否决：它清不掉 `reasoningEffort`，于是从推理模型切到普通模型会留下一个等级，让下一个会话在它上面失败。
 - **只在空白会话里持久化。** 否决：最有信息量的切换恰恰是对话到一半发现模型不行时做的那一次，而它永远存不下来。
 - **单独做一个「设为默认」的入口。** 目前否决：同类产品都从切换本身推断的事情，它却要多一个手势。代价是在老会话里的临时切换也会移动默认值。
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
index bc2d1575ee..145c1cf619 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
 2026-08-08-dsh-run-headless-command.md: d1cc0573d1d94bb7b30e98aa685d2b7d89878a99
-2026-08-08-dsh-run-headless-command.zh.md: 7b48dfd708efb197babcfcbeaf4f8a4ca76cde3f
+2026-08-08-dsh-run-headless-command.zh.md: afb18fea6ac46064b6720d3bb68d7bc53a81d3f2
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
index 7b48dfd708..afb18fea6a 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
@@ -26,7 +26,7 @@ dsh run [--profile <name>] [--patch <path>...] <task...>
 
 `run` 动词只负责一次性任务执行。应用文件启动必须选择其他命令名；如果让两个顶层含义由位置参数形态决定，就会重新引入本命令消除的歧义。
 
-运行器面向用户的契约保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 契约。
+运行器面向用户的约定保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 约定。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
index 3774ba6e69..51b05b277e 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
 2026-08-08-user-explicit-skill-invocation.md: d925938279923282170dc99934f4fa44d8ecf2b4
-2026-08-08-user-explicit-skill-invocation.zh.md: 64e23be0b42519fb9681adefcd0f05074d3aa35e
+2026-08-08-user-explicit-skill-invocation.zh.md: 2d6d7130a1e80e3e9dba2681815668b3510356ba
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
index 64e23be0b4..2d6d7130a1 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
@@ -12,16 +12,16 @@ Status: implemented
 
 用户显式调用是一次宿主侧的 pre-step 注入，对每一个用户可调用的 skill 和每一种前端一致：
 
-- `dsh-tool-skill` 注册第二个 `agent/pre-step` 监听器（与其目录监听器并列，也是 `workspace-instructions` 与运行时上下文快照搭乘的同一 seam）：它在该步骤已认领的消息中扫描以空白为界的 `/name` token——文本中任意位置均可，与 transcript（文本记录）chip 装饰所用的词边界形状相同——收集按首见去重的名称，逐个经 `ctx.skills.get` 加载，在已加载定义上检查 `isUserInvocable`（产生注入内容的正是这同一次查找），用共享的 `renderSkillContent` 渲染，并把注入追加在该步骤所有其他注入之后：背景在前（工作区规则、运行时策略、目录），模型必须着手处理的材料在最后、最贴近它的回答。注册顺序钉住了这一位置——手势监听器先于目录监听器注册，因此 waterfall 会把携带目录的列表交给它来扩展。
+- `dsh-tool-skill` 注册第二个 `agent/pre-step` 监听器（与其目录监听器并列，也是 `workspace-instructions` 与运行时上下文快照搭乘的同一 seam）：它在该步骤已认领的消息中扫描以空白为界的 `/name` token——文本中任意位置均可，与 transcript（文本记录）chip 装饰所用的词边界形状相同——收集按首见去重的名称，逐个经 `ctx.skills.get` 加载，在已加载定义上检查 `isUserInvocable`（产生注入内容的正是这同一次查找），用共享的 `renderSkillContent` 渲染，并把注入追加在该步骤所有其他注入之后：背景在前（工作区规则、运行时策略、目录），模型必须着手处理的材料在最后、最贴近它的回答。注册顺序钉住了这一位置——手势监听器先于目录监听器注册，因此 waterfall（瀑布式事件）会把携带目录的列表交给它来扩展。
 - 精确性来自封闭集合匹配，与斜杠命令完全一致：`/goal` 对照命令注册表解析，`/name` 对照工作区的用户可调用 skill 目录解析；未命中即保持为普通行文，因此绝不猜测。只扫描 `source.kind === 'user'` 的消息——外部文本无法伪造手势。路径（`/usr/bin`）、分数（`5/8`）与带前缀的 token（`foo/name`）都会破坏该边界。
-- 客户端停留在决策 21：菜单 pick 落下字面文本 `/name `，提示词将其原样发出；ui-skill 不实现任何裁决钩子，也没有引用 codec。`skill.list`（现在是该领域唯一的 RPC）提供每一个用户可调用的 skill 并携带 `modelInvocable`，供菜单标出仅限用户的条目。与宿主命令同名的名称解析为命令——裁决在客户端把该行认领走，它尚未成为提示词。
-- 注入是一条携带 `skill-invocation` 来源（`{ name, form: 'instructions' }`）的 `user` 角色消息，因此 `user/message` 落账、上下文注入的 transcript 行（以 skill 名称标注）与回放全部免费获得；`renderSkillContent` 位于 `dsh-skill` seam，与 `skill` 工具结果逐字共享，目录的结尾一句会告诉模型遵循注入块而不是重新加载。
+- 客户端停留在决策 21：菜单 pick 落下字面文本 `/name `，该文本随提示词原样提交；ui-skill 不实现任何裁决钩子，也没有引用 codec。`skill.list`（现在是该领域唯一的 RPC）提供每一个用户可调用的 skill 并携带 `modelInvocable`，供菜单标出仅限用户的条目。与宿主命令同名的名称解析为命令——客户端会在该行成为提示词之前完成裁决并将其认领。
+- 注入是一条携带 `skill-invocation` 来源（`{ name, form: 'instructions' }`）的 `user` 角色消息，因此 `user/message` 落账、上下文注入的 transcript 行（以 skill 名称标注）与回放全部免费获得；`renderSkillContent` 位于 `dsh-skill` seam，由注入和 `skill` 工具结果共用，二者内容逐字相同，目录的结尾一句会告诉模型遵循注入块而不是重新加载。
 
 同类产品调研（Pi、OpenCode、Claude Code、Kimi Code、Codex、DeepSeek-Reasonix——本地检出）一致表明：用户显式触发都是模型零参与的程序化注入；最终形态最接近 Codex 核心侧的 `$name` mention 扫描——它同样让每一种前端免于自行实现识别。
 
 ## 考虑过的替代方案
 
-- **`skill.invoke` RPC（宿主注入、客户端认领）**——最先实现，共两轮迭代：先是单条混合消息（用户文本折进正文），后是经 inbox 原语投递的手势提示词加注入两条消息。经真实会话测试后否决：混合消息让用户行文污染了注入；两条消息的形态依赖唤醒顺序的微妙之处（`followup` 在第一个唤醒调用内同步认领整个 next-turn 队列，把之后的消息滞留到下一轮次——已实际复现），而专设 RPC 复制了 `session.prompt` 已提供的路径，还让 TUI/ACP 不得不各自重新实现识别。pre-step seam 把 RPC、认领机制与顺序隐患一并干净移除。
+- **`skill.invoke` RPC（宿主注入、客户端认领）**——最先实现，共两轮迭代：先是单条混合消息（用户文本折进正文），后是经 inbox 原语投递的手势提示词加注入两条消息。经真实会话测试后否决：混合消息让用户行文污染了注入；两条消息的形态依赖唤醒顺序的微妙之处（`followup` 在第一个唤醒调用内同步认领整个 next-turn 队列，把之后的消息滞留到下一轮次——已实际复现），而专设 RPC 复制了 `session.prompt` 已提供的路径，还让 TUI/ACP（Agent Client Protocol）不得不各自重新实现识别。pre-step seam 把 RPC、认领机制与顺序隐患一并干净移除。
 - **从 RPC 处理器调用 `agent.inject()`**——inject 队列（`next-step`，不唤醒）会在 next-turn 提示词之前被认领，使注入在日志中排到手势之上；而与会唤醒的 `followup` 搭配又会重新引入同样的顺序耦合。pre-step 监听器在步骤组装内部注入，那里的顺序是显式的。
 - **宿主 `/skill <name>` 命令**（命令注册表，plan 模式先例）——两 token 的 UX、没有名称补全、仅限用户的 skill 在菜单里仍不可发现；按 cwd 的 skill 目录也与静态命令注册表格格不入。否决。
 - **客户端展开**（拉取正文、拼进提示词）——授权沦为可被绕过的客户端善意，日志失去调用语义，而且 Codex 已删除其等价机制（custom prompts）转向核心注入。否决。
@@ -30,7 +30,7 @@ Status: implemented
 
 ## 后果
 
-- 决策 21 的纯文本引用如今就是客户端的全部故事：草稿承载纯文本，chip 视觉由 lexicon 派生，发出的文本由宿主边界评判——手动键入的手势、菜单 pick 与 TUI 提示词无从区分，也同等确定。
+- 决策 21 的纯文本引用如今就是客户端的全部故事：草稿承载纯文本，chip 视觉由 lexicon 派生，发出的文本由宿主边界评判——手动键入的手势、菜单 pick 与 TUI 提示词无从区分，也同样具有确定性。
 - 每一次用户可调用 skill 的调用都无条件付出其完整渲染正文的成本——这是确定性的代价，同类调研表明所有产品都在支付。在句子中间提到一个已知 skill 名称也会加载它；这就是 Codex 的 mention 语义，属于有意接受。
 - `skill-invocation` 来源搭乘 `user/message`，因此「模型可见 ⟺ 已记录」在不新增事件类型的情况下继续成立，回放与 UI 读取的是元数据而非文本标记。
-- 放弃逐次注入前导语后被接受的残余：no-reload framing 只搭乘目录，而 skill 全部为仅用户的工作区永远不会发布首个目录——注入可能在完全没有 framing 的情况下到达，模型可能多余地调用一次 `skill` 工具（替换目录的空臂携带该句；从未发布的情形没有）。仅为 framing 而发布目录被判定比这一次可恢复的错误更糟。
+- 放弃逐次注入前导语后被接受的残余：no-reload framing 只搭乘目录，而 skill 全部为仅用户的工作区永远不会发布首个目录——注入可能在完全没有 framing 的情况下到达，模型可能多余地调用一次 `skill` 工具（替换目录的空分支携带该句；从未发布的情形没有）。仅为 framing 而发布目录被判定比这一次可恢复的错误更糟。
diff --git a/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.i18n.yaml b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.i18n.yaml
index 93cf9ec401..b75b7f8ac5 100644
--- a/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.md
 2026-06-11-vendor-cordis-as-source.md: ccc1289c8a0feadc08d80a3b6e8dc674c1b87bc4
-2026-06-11-vendor-cordis-as-source.zh.md: 9abea504d677ab71c62d24e2e4d9dfde4315802c
+2026-06-11-vendor-cordis-as-source.zh.md: 4b30ba7684c75bf5eadc0d7c58990ced5355e8f0
diff --git a/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.zh.md b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.zh.md
index 9abea504d6..4b30ba7684 100644
--- a/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.zh.md
+++ b/.agents/notes/implemented/process/2026-06-11-vendor-cordis-as-source.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 将 Cordis 以源码形式收录，而非作为 npm 依赖
+# Agent Note: 将 Cordis 以源码形式收录，而非作为 NPM 依赖
 
 Status: implemented
 
@@ -12,7 +12,7 @@ DeepSeek Harness SDK 构建于 Cordis 框架之上。本仓库启动时，Cordis
 
 将所需的 Cordis 包（core、loader、include、group、timer、hmr、logger-console）与 cordiverse 基础库（cosmokit、schemastery）以源码形式复制到 `vendor/`，扁平化放置，保留其原始 npm 包名以实现透明的 workspace 解析。`pnpm-workspace.yaml` 设置 `linkWorkspacePackages: true`，所以只要上游 semver 范围匹配，无论以源码执行还是以构建产物执行，依赖都会解析到这些固定版本的 workspace。真正的第三方依赖（js-yaml、chokidar、@standard-schema/spec 等）仍从 npm 获取。
 
-`vendor/README.md` 是 manifest（元数据清单）：记录每个包（package）的上游仓库 + commit SHA，以及一份详尽的本地修改日志。pre-commit 守卫（`scripts/check-vendor-manifest.sh`）会拒绝未在同一次提交中更新 manifest 的 vendor 源码变更。
+`vendor/README.md` 是 manifest（元数据清单）：记录每个包的上游仓库和 commit SHA，以及一份详尽的本地修改日志。pre-commit 守卫（`scripts/check-vendor-manifest.sh`）会拒绝未在同一次提交中更新 manifest 的 vendor 源码变更。
 
 ## 曾考虑的替代方案
 
@@ -21,7 +21,7 @@ DeepSeek Harness SDK 构建于 Cordis 框架之上。本仓库启动时，Cordis
 
 ## 后果
 
-- harness 完全持有其框架层：可审计、可打补丁、版本锁定。上游 RC 无法影响我们，框架 bug 可以在仓库内直接修复。
+- harness 完全持有其框架层：可审计、可打补丁、版本锁定。上游 RC 无法导致本项目故障，框架 bug 可以在仓库内直接修复。
 - 构建后的包与源码测试执行的是同一版收录的 Cordis；移除 workspace 链接后，构建后的包会在包名不变的情况下静默改用 npm 副本。
 - 上游同步是手动操作（流程记录在 manifest 中）。修改日志使 diff 范围始终可知。
 - 收录的包保留上游代码风格；lint 与严格性门禁将其排除（它们的 tsconfig 在本地放宽了我们较新的编译器选项）。
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
index a126f8c0d0..8d5e491e49 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-17-ts-build-config.md
 2026-06-17-ts-build-config.md: f25731921aaa6da7a4c9760244f73dc0670dc1d3
-2026-06-17-ts-build-config.zh.md: 41791129647b6a5bfeb966e05ee2c5b9132c45ef
+2026-06-17-ts-build-config.zh.md: f96187291ab89744d83908cfbe09d4f03f56577e
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
index 4179112964..f96187291a 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
@@ -4,14 +4,14 @@ Status: implemented
 
 [English](2026-06-17-ts-build-config.md) | 中文
 
-> 根项目拓扑由一个 solution 根文件统辖两个 aggregate program；见 [solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。Host 生成 Remote 契约后再编译 Client 的当前命令顺序见 [API Remotes 构建 Agent Note](2026-08-08-api-remotes-generated-contract-build.md)。本文确定的 tsc-first 职责保持不变。
+> 根项目拓扑由一个 solution 根文件统辖两个 aggregate program；见 [solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。Host 生成 Remote 约定后再编译 Client 的当前命令顺序见 [API Remotes 构建 Agent Note](2026-08-08-api-remotes-generated-contract-build.md)。本文确定的 tsc-first 职责保持不变。
 
 ## 问题
 
 此前的 TypeScript 构建与类型检查配置存在以下问题：
 
 - `build` 使用 `tsc` 将 `packages/<group>/<pkg>` 和 `vendor/*` 下的 `.ts` 转换为 `.d.ts` 文件，然后使用 `tsdown` 将 `.ts` 转换为打包后的 `.js` 文件。这导致两个工具各自执行 TypeScript 转换。
-- `typecheck` 倾向于通过一个根目录的类型检查配置来校验包（package）、vendor 源码、示例、测试和脚本。
+- `typecheck` 倾向于通过一个根目录的类型检查配置来校验包、vendor 源码、示例、测试和脚本。
 
 目标是让构建与类型检查使用一致的 tsconfig 边界和 TypeScript 解析/转换行为。构建应通过单一编译器和配置生成 `.js`、`.d.ts`、`.js.map` 和 `.d.ts.map`，使发布产物与类型校验保持一致。
 
@@ -76,14 +76,14 @@ tsx scripts/clean.ts
 
 构建职责更加清晰：
 
-- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个普通模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。`api/remotes` 因生成契约顺序使用一个 solution 和两个互斥的 emitting project，是唯一例外。
-- `build` 命令按 Host 与 Client Project Reference 图执行。每个阶段都由 `tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责发布 runtime bundle。
+- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个普通模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。`api/remotes` 因生成约定的顺序使用一个 solution 和两个互斥的 emitting project，是唯一例外。
+- `build` 命令按 Host 与 Client Project Reference 图执行。每个阶段都由 `tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责发布用的运行时 bundle。
     - `lib/types/*.d.ts` 是发布用的声明输出；`.d.ts.map` 只作为本地编译产物保留。
     - `lib/types/*.d.ts` 使用显式 `.ts` 相对说明符，TypeScript 的 NodeNext/Node16 解析器会将其映射到同级的 `.d.ts` 文件。
     - `lib/types/*.js` 通常仅作为打包器输入。只有显式运行时 export 指向该输出树时，才会发布这些文件。
     - `lib/index.*` 是发布用的运行时输出，由打包器（当前为 `tsdown`）生成。
 - `pnpm run verify-node-next-types` 扫描构建出的声明文件，检查是否存在缺少文件扩展名的相对说明符，然后以 `moduleResolution: "NodeNext"` 对构建出的 `types`/`exports` 接口进行临时外部 ESM 消费方的类型检查，确保声明说明符的回归在发布前被捕获。
 - `typecheck` 命令使用 `tsconfig.json`。示例、测试和脚本由根 no-emit 项目检查，包和 vendor 模块保持与 `build` 相同的输出行为。包和 vendor 源码始终处于 project-reference 边界之后。
-- 切换分支或更新工作副本后，如果其中删除了包，贡献者可在重新构建前运行 `pnpm run clean`，删除残留的包目录。不含 `package.json` 的包目录如果存在未知文件，必须手动判定其类别，不能直接删除。
+- 切换分支或更新工作副本后，如果其中删除了包，贡献者可在重新构建前运行 `pnpm run clean`，删除陈旧的包目录。不含 `package.json` 的包目录如果存在未知文件，必须手动判定其类别，不能直接删除。
 
 Cordis 的 vendor 副本现在与上游多了一处类型结构差异。在上游同步时，该差异必须被重新应用或明确废弃。
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 9e69041e2e..812256d0ae 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.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 .agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
-2026-07-02-bilingual-docs-and-pairing-gate.md: 8e9d0ab8653528517346b198c97814d8d8979440
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: e8f18ebb0d1620830116f6d5d9ffef29664a578e
+2026-07-02-bilingual-docs-and-pairing-gate.md: b462efd99c008a1e8254b6754a408e9e94e787d6
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 409177996d7ffc63a36c865cc00002a33fe538f1
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
index 8e9d0ab865..b462efd99c 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
@@ -39,6 +39,6 @@ Paired sibling files with locale suffixes are the dominant Chinese big-tech conv
 - Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.
 - Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, "who confirmed these consistent, and when" is answerable from git blame on the yaml.
 - When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.
-- Generated docs (`cordis-catalog/`, `tool-catalog/`, `module-graph.md`) are excluded for now; the planned follow-up is to teach their generators to emit Chinese alongside English, at which point they leave the exclusion list.
+- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.
 - The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.
 - The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index e8f18ebb0d..409177996d 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -39,6 +39,6 @@ Status: implemented
 - 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。
 - 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。
 - 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。
-- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。
+- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。
 - 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。
 - 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
index 2a6cdcc2d0..4ff70e11e9 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md
 2026-07-22-tsconfig-solution-root-two-aggregates.md: 6e8d192b5fea1c7045ade6935fd0e2dc8434c502
-2026-07-22-tsconfig-solution-root-two-aggregates.zh.md: 60581e3de55227a393e2528ce7d3c8fa1bf9c570
+2026-07-22-tsconfig-solution-root-two-aggregates.zh.md: 052f3fb92b7cc8e49eeb2e0b1133bb7bf201f26b
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
index 60581e3de5..052f3fb92b 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
@@ -27,7 +27,7 @@ GUI 拆分引入了第二个聚合 program（`tsconfig.client.json`，见[分层
 
 整个方案立足的原则：**cordis `Context` 的声明合并冲突只存在于同一个 `ts.Program` 内部，从不发生在模块解析中。** solution 文件不构成 program，因此从一个根文件同时引用两个聚合不会让两侧的声明合并相撞；vite-tsconfig-paths 只读取 `paths` 与 `include`、丢弃全部类型信息，因此一个门面可以横跨两侧。唯一会爆炸的做法是把两侧压平进同一个 program，由此推出两条派生纪律：`tsconfig.base.json` 永远不得添加 `include`/`files`（否则会泄漏进每个继承它的包，并收窄门面范围）；每个全仓级 `ts.Program` 消费方（`scripts/ts-project.ts`、doc-typecheck 独立模式）都显式以 `tsconfig.host.json` 或 `tsconfig.client.json` 为种子，绝不使用根 solution。基于 program 的生成器与语义门禁有意只留在宿主侧；客户端侧只有在真实需求出现时才引入基于 program 的门禁。
 
-根 `tsconfig.json` 仍是显式执行完整 Project Reference 图的 solution 入口，lefthook pre-push 通过 `tsc -b tsconfig.json --pretty false` 增量覆盖两侧。仓库的 `build` 与 `typecheck` 命令因 Client 依赖 Host tsdown 生成的 Remote 契约而按 Host、Client 顺序运行，具体编排由 [API Remotes 构建 Note](2026-08-08-api-remotes-generated-contract-build.md)负责。`tsconfig.build.json` 与 `tsconfig.vitest.json` 已删除；所有 vitest 配置都把 vite-tsconfig-paths 指向 `tsconfig.base.json`。
+根 `tsconfig.json` 仍是显式执行完整 Project Reference 图的 solution 入口，lefthook pre-push 通过 `tsc -b tsconfig.json --pretty false` 增量覆盖两侧。仓库的 `build` 与 `typecheck` 命令因 Client 依赖 Host tsdown 生成的 Remote 约定而按 Host、Client 顺序运行，具体编排由 [API Remotes 构建 Note](2026-08-08-api-remotes-generated-contract-build.md) 负责。`tsconfig.build.json` 与 `tsconfig.vitest.json` 已删除；所有 vitest 配置都把 vite-tsconfig-paths 指向 `tsconfig.base.json`。
 
 solution 根文件刻意 `extends` base：`examples/` 与 `scripts/` 没有更近的 tsconfig，tsx（get-tsconfig）通过根文件解析它们的 workspace 导入。`extends` 把 `paths` 映射带回根文件，`files: []` 则让它始终不构成 program。这不影响两者的*类型检查*：examples、scripts 与 website 的文件由宿主聚合纳入。
 
@@ -41,5 +41,5 @@ solution 根文件刻意 `extends` base：`examples/` 与 `scripts/` 没有更
 
 - `docs/development.md#typescript-project-layout` 是权威描述；根 `AGENTS.md` 以约定形式收录上述两条纪律。
 - [ts-build-config Agent Note](2026-06-17-ts-build-config.md) 继续拥有 tsc 先行的构建流水线（tsc 负责输出，tsdown 负责打包，`.ts` 说明符配合 `rewriteRelativeImportExtensions`）；其原先「单一根类型检查项目」的形态由本文取代。
-- 新增一个普通 package 只登记进恰好一个 aggregate 的 references（Host package 进 `tsconfig.host.json`，Client package 进 `tsconfig.client.json`）。`api/remotes` 因 Host 生成契约与 Client 消费契约的顺序关系成为唯一显式拆分例外；其两个具体 project 分别登记，包根 solution 不进入任一 aggregate。
-- Host 与 Client 构建阶段必须串行：Host tsdown 生成契约后 Client tsc 才能开始。各阶段复用各 project 的增量状态，不通过并发重复处理同一张图。
+- 新增一个普通 package 只登记进恰好一个 aggregate 的 references（Host package 进 `tsconfig.host.json`，Client package 进 `tsconfig.client.json`）。`api/remotes` 因 Host 生成约定与 Client 消费约定的顺序关系成为唯一显式拆分例外；其两个具体 project 分别登记，包根 solution 不进入任一 aggregate。
+- Host 与 Client 构建阶段必须串行：Host tsdown 生成约定后 Client tsc 才能开始。各阶段复用各 project 的增量状态，不通过并发重复处理同一张图。
diff --git a/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.i18n.yaml
index 8bb5febd69..4551666419 100644
--- a/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md
 2026-07-26-incremental-pr-base-retargeting.md: b2e644d99877b4214b5a6edb2775b3962e6b7da2
-2026-07-26-incremental-pr-base-retargeting.zh.md: 5014fef644f9907c4d16a9a2a3767d6f55633688
+2026-07-26-incremental-pr-base-retargeting.zh.md: b97a0abe655e9f4e8ed911ae921bd2a6e5223379
diff --git a/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.zh.md b/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.zh.md
index 5014fef644..b97a0abe65 100644
--- a/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-选择 merge-forward 时，每次观察到的 base 分支顶端提交都保留为独立的合并检查点。如果处理期间 base 分支继续前移，先完成并验证正在进行的合并，再将其提交；任务授权推送时，还要完成推送。完成这些步骤后，才能拉取较新的 base，并通过单独的合并提交将其合入。在这条 merge-forward 序列中，不得放弃或重写任何检查点。
+选择 merge-forward 时，每次观察到的 base 分支顶端提交都保留为独立的合并检查点。如果处理期间 base 分支继续前移，先完成并验证正在进行的合并，再将其提交；任务授权推送时，还要完成推送。完成这些步骤后，才能获取较新的 base，并通过单独的合并提交将其合入。在这条 merge-forward 序列中，不得放弃或重写任何检查点。
 
 [原生堆叠与可选 rebase 决策](2026-08-02-native-github-stacks-and-optional-rebases.md)也允许独立或堆叠 PR 使用受 lease 保护的 rebase，评审后同样如此。本文只负责 merge-forward 路径。[堆叠 PR 落地 skill（技能）](../../../skills/dsh-merging-stacked-prs/SKILL.md)根据根 [AGENTS.md](../../../../AGENTS.md) 选择其中一种历史更新方式，[堆叠评审指南](../../../../docs/cookbook/responding-to-pr-review-on-a-stack.md)则负责说明如何在依赖层之间传播修复。
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
index 2589170fc0..907669edb8 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
 2026-07-30-generated-third-party-notices.md: f2591c8d0c7d4b83ecc96bf237ded667e322d55c
-2026-07-30-generated-third-party-notices.zh.md: 74c95cc4349e9d1288d6635b0ae8617e7b929115
+2026-07-30-generated-third-party-notices.zh.md: eef1e1f46bd9086ad0ccb1cf164330b3bbf601bb
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
index 74c95cc434..eef1e1f46b 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
@@ -8,41 +8,41 @@ Status: implemented
 
 本仓库开源需要披露所依赖的第三方软件及各自的许可证。这份披露必须完整，必须随依赖变化保持为真，还必须给出读者用得上的信息：哪些包最终会进到用户机器上，哪些只用于构建和测试。
 
-手写清单无法长期满足其中任何一条。约一百行从各清单文件推导出来的包名与许可证标识，只要有依赖新增、移除或换用许可证就会悄悄失真，而没有任何检查会察觉。
+手写清单无法长期满足其中任何一条。约一百行从各 manifest（元数据清单）推导出来的包名与许可证标识，只要有依赖新增、移除或换用许可证就会悄悄失真，而没有任何检查会察觉。
 
 ## Decision
 
-[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区清单、`vendor/README.md`、`pyproject.toml` 与 `pnpm-workspace.yaml` 生成。根 README 双语两侧都从「许可证」一节链到该文件。
+[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区 manifest、`vendor/README.md`、`pyproject.toml` 与 `pnpm-workspace.yaml` 生成。根 README 双语两侧都从「许可证」一节链到该文件。
 
-**新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何清单文件、工作区声明、根锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成并一并入库，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。
+**新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何 manifest、工作区声明、根锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成该文件并将其暂存，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。
 
-有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除**清单文件不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
+有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
 
 文件默认只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。唯一明确披露的传递依赖，是 `@anthropic-ai/claude-agent-sdk` 通过 `optionalDependencies` 声明的官方 Claude 平台载荷集合，因为这些包承载随产品分发的 Claude Code 可执行文件，而非普通的库实现细节。
 
-**分层依据是声明方所在区域，而非清单字段名。** 只要 `DEV_ONLY_AREAS` 之外的任一清单——即根清单、`packages/support/`、`packages/client/test-runtime/`、`website/`、`examples/`、`native/` 之外——在 `dependencies` 或 `optionalDependencies` 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 `vitest` 写在 `dependencies` 里却并不交付它；而 `bin/dsh` 启动器 exec 经过的 `tsx`，根本没有任何清单把它声明为运行时依赖，只能由生成器显式标记。
+**分层依据是声明方所在区域，而非manifest 字段名。** 只要 `DEV_ONLY_AREAS` 之外的任一 manifest——即根 manifest、`packages/support/`、`packages/client/test-runtime/`、`website/`、`examples/`、`native/` 之外——在 `dependencies` 或 `optionalDependencies` 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 `vitest` 写在 `dependencies` 里却并不交付它；而 `bin/dsh` 启动器通过 `tsx` 执行，根本没有任何 manifest 把它声明为运行时依赖，只能由生成器显式标记。
 
 运行时层刻意覆盖**所有可挂载的插件**，而不止 CLI、Web UI 与 Python 运行时默认加载的那些。`scripts/install.sh` 安装的就是仓库本身，用户的 `cordis.yml` 可以挂载任何插件包；`@modelcontextprotocol/sdk` 与 OpenTelemetry 系列即使没有任何默认装配引入，也会触达真实用户。对法务披露而言，披露不足才是代价更高的那个方向。
 
-清单集合由根 `pnpm-workspace.yaml` 声明的 `packages:` 成员派生，其中包括 Landlock 工作区及其公开包，因此新增成员区域在声明当天就会被读取，而不必等谁想起来去补一份列表。许可证与仓库地址取自根工作区已安装的 pnpm store 和包本地链接场；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布清单答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。运行时依赖的许可证若不在宽松清单内即为硬失败：交付 copyleft 是一项分发决策，不该被一次重新生成悄悄吸收。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列在运行时表格之后，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。
+manifest 集合由根 `pnpm-workspace.yaml` 声明的 `packages:` 成员派生，其中包括 Landlock 工作区及其公开包，因此新增成员区域在声明当天就会被读取，而不必等谁想起来去补一份列表。许可证与仓库地址取自根工作区已安装的 pnpm store 和包本地链接场；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布 manifest 答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。运行时依赖的许可证若不在宽松清单内即为硬失败：交付 copyleft 是一项分发决策，不该被一次重新生成悄悄吸收。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列入运行时表格，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。
 
-项目所有者另行授权分发每个官方 `@anthropic-ai/claude-agent-sdk` 版本，以及该版本通过 `optionalDependencies` 声明的官方 Claude Code CLI 与平台载荷。生成器将其表示为一项精确匹配直接包身份的例外，而非宽松许可证覆盖项：`SEE LICENSE IN README.md` 与 `SEE LICENSE IN LICENSE.md` 仍归类为非宽松，所有无关的非宽松运行时依赖仍以默认拒绝方式失败。存在该 SDK 时，生成器会读取其已安装清单，拒绝不符合官方 SDK 载荷前缀的可选包身份，推导当前 SDK、CLI 与载荷版本，核验已安装宿主载荷的身份、版本和声明许可证字段，并在单独的声明章节中渲染 SDK 声明的完整载荷集合。版本、声明许可证和载荷集合发生变化时无需新的身份授权，但仍须经过常规的依赖、锁文件、兼容性、条款和声明评审。
+项目所有者另行授权分发每个官方 `@anthropic-ai/claude-agent-sdk` 版本，以及该版本通过 `optionalDependencies` 声明的官方 Claude Code CLI 与平台载荷。生成器将其表示为一项精确匹配直接包身份的例外，而非宽松许可证覆盖项：`SEE LICENSE IN README.md` 与 `SEE LICENSE IN LICENSE.md` 仍归类为非宽松，所有无关的非宽松运行时依赖仍以默认拒绝方式失败。存在该 SDK 时，生成器会读取其已安装 manifest，拒绝不符合官方 SDK 载荷前缀的可选包身份，推导当前 SDK、CLI 与载荷版本，核验已安装宿主载荷的身份、版本和声明许可证字段，并在单独的声明章节中渲染 SDK 声明的完整载荷集合。版本、声明许可证和载荷集合发生变化时无需新的身份授权，但仍须经过常规的依赖、锁文件、兼容性、条款和声明评审。
 
 ## Testing
 
-断言新鲜度的同一个 spec 也用夹具清单钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它还把各解析器钉在那些原本会让某个包无声消失的形态上：不再覆盖全部收编目录的 `vendor/README.md` 表、含 extras 的依赖数组（`"httpx[http2]"`）、完全不带版本的依赖、作者自取名字的 `[dependency-groups]` 表，以及任何硬编码列表都不含的工作区成员区域。这些都是静默漏报路径——正是披露文件最担不起的失败方式。
+断言新鲜度的同一个 spec 也用fixture（测试前置数据）manifest钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它还把各解析器钉在那些原本会让某个包无声消失的形态上：不再覆盖全部收编目录的 `vendor/README.md` 表、含 extras 的依赖数组（`"httpx[http2]"`）、完全不带版本的依赖、作者自取名字的 `[dependency-groups]` 表，以及任何硬编码列表都不含的工作区成员区域。这些都是静默漏报路径——正是披露文件最担不起的失败方式。
 
-Claude 分发测试证明：只有精确匹配的直接 SDK 身份会绕过通常的非宽松运行时拒绝；该绕过不会改变许可证分类；载荷集合来自 SDK 清单，而非版本或平台允许列表。SDK 身份错误、载荷缺失或存在无关的可选包身份时，测试都会失败。
+Claude 分发测试证明：只有精确匹配的直接 SDK 身份会绕过通常的非宽松运行时拒绝；该绕过不会改变许可证分类；载荷集合来自 SDK manifest，而非版本或平台允许列表。SDK 身份错误、载荷缺失或存在无关的可选包身份时，测试都会失败。
 
 ## Alternatives considered
 
 **保留手写文件，发版时人工过一遍。** 用肉眼审阅上百行推导数据，恰恰是生成器能做对的活；而且在两次发版之间，文件自称「列出全部直接依赖」这句话无人验证。
 
-**用专门的 `doc-sync` 门禁校验。** 仓库里其他生成产物都是这么把关的，本次改动最初也是这个形态。但它要在本已冗长的矩阵里再占一个门禁进程和一个调度位；更糟的是，它唯一的失败方式，就是在别人推完一个无关的依赖升级几分钟后，通知对方回去重跑一次生成器。改为提交时重新生成消除了这次打断，而把断言放进测试 lane 本就会跑的 spec 里，则以零额外 CI 成本保住了这项保证。
+**用专门的 `doc-sync`（文档同步门禁）校验。** 仓库里其他生成产物都是这么把关的，本次改动最初也是这个形态。但它要在本已冗长的矩阵里再占一个门禁进程和一个调度位；更糟的是，它唯一的失败方式，就是在别人推完一个无关的依赖升级几分钟后，通知对方回去重跑一次生成器。改为提交时重新生成消除了这次打断，而把断言放进测试 lane 本就会跑的 spec 里，则以零额外 CI 成本保住了这项保证。
 
 **列出完整传递闭包。** 闭包有数千个包，锁文件里已带精确版本，铺开只会淹没读者真正要评估的直接依赖。文件转而指向锁文件与 `pnpm licenses list`。
 
-**按清单字段分层（`dependencies` 与 `devDependencies`）。** 机械上最省事，但在真实数据上两个方向都会出错，理由见上文分层段落。
+**按 manifest 字段分层（`dependencies` 与 `devDependencies`）。** 机械上最省事，但在真实数据上两个方向都会出错，理由见上文分层段落。
 
 **只按已交付装配的可达性分层**（`apps/*` 加 `python/sdk-runtime`）。这样得到的运行时层更紧凑，但会把 MCP 客户端与 OpenTelemetry 导出器判为仅开发用途——而运行已安装仓库的用户完全可以挂载它们。这会低估披露，对法务通告来说错在了更危险的一侧。
 
@@ -52,9 +52,9 @@ Claude 分发测试证明：只有精确匹配的直接 SDK 身份会绕过通
 
 ## Consequences
 
-此后改动依赖时，重新生成的披露文件会随同一个提交入库。触及清单文件的提交多付一次生成器运行——约一秒；其余提交不受影响。若禁用钩子提交，代价推迟为一次测试 lane 失败，其报错会指明补救命令。
+此后改动依赖时，重新生成的披露文件会随同一个提交入库。触及 manifest 的提交多付一次生成器运行——约一秒；其余提交不受影响。若禁用钩子提交，代价推迟为一次测试 lane 失败，其报错会指明补救命令。
 
-生成器需要已安装的工作树，因此比纯源码生成器更重；发布元数据不可用的新包需要补一条 `OVERRIDES`，而不是默默渲染出空白许可证。这两类失败都会明确报错并指出补救方式。
+生成器需要已安装的依赖树，因此比纯源码生成器更重；发布元数据不可用的新包需要补一条 `OVERRIDES`，而不是默默渲染出空白许可证。这两类失败都会明确报错并指出补救方式。
 
 分层规则是编码在一个常量里的政策。若新增了不参与交付的工作区区域——第二层测试基础设施、另一个站点——就要同步扩展 `DEV_ONLY_AREAS`，否则其依赖会被当作运行时依赖披露出去。
 
diff --git a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml
index 663b074d59..bc066b13ef 100644
--- a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.md
 2026-07-30-independent-ci-consumer-build.md: ea87d8051a30c282bdf57ddc3226072be8cb7f24
-2026-07-30-independent-ci-consumer-build.zh.md: 1b5faf73711bd522ddf0ae04f870e0401a481c0e
+2026-07-30-independent-ci-consumer-build.zh.md: b0aa6c453573e089d0352beaa74a6eab769453ae
diff --git a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md
index 1b5faf7371..b0aa6c4535 100644
--- a/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-independent-ci-consumer-build.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 消费方独立构建
+# Agent Note: CI 消费方独立构建
 
 Status: implemented
 
diff --git a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
index 9d3ac28ed2..6c4645c72f 100644
--- a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.md
 2026-07-31-coverage-exempt-heavy-suites.md: 7235a5193554947ecf71f62d522d09f4e21cb1da
-2026-07-31-coverage-exempt-heavy-suites.zh.md: b739e4494ae8d240b0e35109920a49876ebd222d
+2026-07-31-coverage-exempt-heavy-suites.zh.md: e3d6e335ecb069dadeebb06d760cf70c9b0c1fd4
diff --git a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
index b739e4494a..e3d6e335ec 100644
--- a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试文件钉死：本地 6-worker 全量剖析中，555 个测试文件聚合 1595 秒，其中 `packages/typert/generator/tests/type-model.spec.ts` 一个文件占 885 秒，前 10 个文件占聚合时长的 84%。这类套件的共同点是每个用例都做全工作区编译器分析或真实子进程 fixture，v8 插桩把这类代码的运行时间放大数倍。
+CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试文件钉死：本地 6-worker 全量剖析中，555 个测试文件聚合 1595 秒，其中 `packages/typert/generator/tests/type-model.spec.ts` 一个文件占 885 秒，前 10 个文件占聚合时长的 84%。这类套件的共同点是每个用例都做全工作区编译器分析或真实子进程 fixture（测试前置数据），v8 插桩把这类代码的运行时间放大数倍。
 
 关键的浪费在于：这些套件缴纳的插桩税对 per-file 100% 阈值**没有任何贡献**——它们进程内执行的被度量代码，要么本来就不在阈值口径内，要么已由其他套件独立满覆盖。继续在插桩下运行它们，纯粹是用 lane 时长换零信息。
 
@@ -17,7 +17,7 @@ CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试
 - **插桩 gate**（`test:coverage`）：设 `DSH_COVERAGE_EXEMPT_HEAVY=1`，`vitest.config.ts` 据此从两个 project 的 exclude 中剔除豁免套件，其余全部文件照旧插桩并承担全部阈值证明。经 gate 自带 env 注入（既有 `Gate.env` 机制），不进 workflow 全局环境，因此并排的无插桩 gate 和本地直跑 `vitest run` 都看不到该变量、行为不变。
 - **无插桩 gate**（`test:coverage-exempt-heavy`）：用配对的 positional filter 恰好运行豁免套件，保证正确性信号不缩水。
 
-`scripts/coverage-exempt.ts` 是唯一名单点，集中持有成员资格契约与 filter/exclude 配对，防止两侧漂移。
+`scripts/coverage-exempt.ts` 是唯一名单点，集中持有成员资格约定与 filter/exclude 配对，防止两侧漂移。
 
 ### 豁免名单与逐项对账
 
@@ -29,18 +29,18 @@ CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试
 | 其中 tools-catalog.spec 额外 import | `typert-registry`、`tool-cordis` 的 src | 两包各自的测试独立满覆盖（focused coverage 实测无阈值错误） |
 | `scripts/install-lefthook.spec.ts`、`scripts/oxlint-contract.spec.ts`、`scripts/change-scope.spec.ts` | 无——被测对象是 `scripts/` 源码（从不在 coverage.include），执行方式是 spawn 子进程 | 无需接 |
 
-### 成员资格契约
+### 成员资格约定
 
-新增豁免必须同时满足：套件进程内执行的每个被度量文件都已由其他套件满覆盖（或在阈值排除名单内）；filter 与 exclude 选中完全相同的文件集。契约文本随名单同文件维护。
+新增豁免必须同时满足：套件进程内执行的每个被度量文件都已由其他套件满覆盖（或在阈值排除名单内）；filter 与 exclude 选中完全相同的文件集。约定文本随名单同文件维护。
 
 ### 门禁自动守卫名单正确性
 
 per-file 100% 阈值本身就是豁免名单的守卫，名单错误无法静默通过：
 
 - 若未来某个豁免套件实际独家覆盖着某个被度量文件，插桩 gate 当场红（该文件跌破 100%）；
-- 反向同理：出现"只有豁免套件才覆盖"的新代码，同样立刻红。
+- 反向同理：出现「只有豁免套件才覆盖」的新代码，同样立刻红。
 
-因此覆盖率结果的不变性不依赖人工维护名单，符合"misconfiguration fails loud"约定。唯一失去的是豁免套件自身的执行不再产出覆盖数据——由上表可知这些数据全部冗余，最终报告在阈值意义上逐文件相同。
+因此覆盖率结果的不变性不依赖人工维护名单，符合「misconfiguration fails loud」约定。唯一失去的是豁免套件自身的执行不再产出覆盖数据——由上表可知这些数据全部冗余，最终报告在阈值意义上逐文件相同。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
index 77003539ac..0f350867a7 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
 2026-07-31-installer-adopts-existing-checkout.md: 3a213a6232e57f305910240505983421dcd288ad
-2026-07-31-installer-adopts-existing-checkout.zh.md: 7cdcd5549fb2bca2a6cb11f0cf2867687565ae79
+2026-07-31-installer-adopts-existing-checkout.zh.md: a5f1c07e41ecb4e8d5b9a250ebd28d03e85b62be
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
index 7cdcd5549f..a5f1c07e41 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
@@ -6,39 +6,39 @@ Status: implemented
 
 ## Problem
 
-`scripts/install.sh`会产生两种互不兼容的安装形态。`curl … | sh`安装会构建受管布局——`~/.dsh/source/master`处的 master 克隆、位于`dsh-staging/<时间戳>`分支上的 staging worktree，以及 PATH 启动器据以解析的稳定`current`符号链接。而从检出中运行同一脚本时，则依据此前的[检出内跳过克隆决策](../../archived/process/2026-07-22-installer-in-repo-skip-clone.md)，把`dsh`直接链接到该检出的`bin/dsh`。
+`scripts/install.sh` 会产生两种互不兼容的安装形态。`curl … | sh` 安装会构建受管布局——`~/.dsh/source/master` 处的 master 克隆、位于 `dsh-staging/<时间戳>` 分支上的 staging worktree，以及 PATH 启动器据以解析的稳定 `current` 符号链接。而从检出中运行同一脚本时，则依据此前的[检出内跳过克隆决策](../../archived/process/2026-07-22-installer-in-repo-skip-clone.md)，把 `dsh` 直接链接到该检出的 `bin/dsh`。
 
-这种直接链接是一种终态。升级重指的正是`current`，因此缺少它的安装无法通过[`dsh-upgrade`](../../../../skills/dsh-upgrade/SKILL.md)升级；检出一旦移动，PATH 符号链接就会失效；而且启动器会解析到贡献者恰好检出的任意分支，这正是升级契约禁止作为启动器目标的情形。升级技能早已把这种形态描述为需要一次性迁移的旧式安装，于是两种布局在安装时就已分叉，并且要到很久以后才会被调和——甚至永远不会。
+这种直接链接是一种终态。升级重指的正是`current`，因此缺少它的安装无法通过[`dsh-upgrade`](../../../../skills/dsh-upgrade/SKILL.md)升级；检出一旦移动，PATH 符号链接就会失效；而且启动器会解析到贡献者恰好检出的任意分支，这正是升级约定禁止作为启动器目标的情形。升级 skill（技能）早已把这种形态描述为需要一次性迁移的旧式安装，于是两种布局在安装时就已分叉，并且要到很久以后才会被调和——甚至永远不会。
 
 ## Decision
 
 检出内模式仍然绝不克隆、绝不修改工作树，但现在它会无条件地把该检出**接管**进受管布局。不存在退出选项：一套布局服务于所有安装。
 
-容器拥有 staging worktree 和`current`；仓库是被*发现*的，而非被拥有的。`git rev-parse --git-common-dir`会解析出该检出背后的共享 git 目录——对于 linked worktree，那是真正的克隆而非 worktree 自身——其父目录即是充当升级基础的仓库。随后以该检出的`HEAD`为起点，在`$DSH_SOURCE`下创建 staging worktree，并让`current`指向它。因此，磁盘上任意位置的克隆都会收敛到与`curl`安装相同的布局，且两条路径共用同一套 worktree/exclude/lock/link 流程：二者的唯一差别，只在于仓库是由`git clone`发现的，还是由`git rev-parse`发现的。
+容器拥有 staging worktree 和`current`；仓库是被*发现*的，而非被拥有的。`git rev-parse --git-common-dir`会解析出该检出背后的共享 git 目录——对于 linked worktree，那是真正的克隆而非 worktree 自身——其父目录即是充当升级基础的仓库。随后以该检出的 `HEAD` 为起点，在`$DSH_SOURCE`下创建 staging worktree，并让`current`指向它。因此，磁盘上任意位置的克隆都会收敛到与`curl`安装相同的布局，且两条路径共用同一套 worktree/exclude/lock/link 流程：二者的唯一差别，只在于仓库是由`git clone`发现的，还是由`git rev-parse`发现的。
 
 安装器不会记录该仓库位于何处。仓库位于容器之外时，容器就不是自包含的——每个 staging worktree 都持有指向该克隆的绝对 gitdir 指针，删除该克隆就会破坏它们——但这一事实本就由 git 自己掌握：worktree 的`.git`文件写明了该路径，而在该克隆中执行`git worktree list`会列出依赖于它的每一个 worktree。
 
-接管以`HEAD`为分支起点，因此运行的是已提交的内容，未提交的更改仍留在检出中。这一点既不提示也不警告：安装器构建好布局后便不再打扰。把`DSH_SOURCE`设为其他目录，仍是唯一有文档记载的、回到克隆另一棵树的方式。
+接管以`HEAD`为分支起点，因此运行的是已提交的内容，未提交的更改仍留在检出中。这一点既不提示也不警告：安装器构建好布局后便不再打扰。把`DSH_SOURCE`设为其他目录，仍是唯一有文档记载的、重新选择克隆一棵独立代码树的方式。
 
-所有路径比较都通过`resolve_dir`辅助函数在物理路径上进行，且每个参与比较的值都在赋值时解析，而非在比较时解析。git 报告的始终是已解析的路径，因此只要检出之上任意一层存在符号链接，拿它与未解析的路径相比较就会不相等——家目录本身是符号链接即已足够，而 macOS 通过`/var` -> `private/var`使每个`mktemp`路径都如此。这种不匹配会把已有的受管安装误判为外来克隆，并在真正的容器旁再建一个容器。同一缺陷在评审过程中又出现了两次，两次都是比较的一侧未经解析：一次是 curl 安装的`REPO_ROOT`，一次是与之比较的容器路径。因此`resolve_dir`在路径不存在时原样回显该路径而非失败，这样尚未创建的容器无需在每个调用点单独兜底，也就没有调用点会因遗漏兜底而与空路径比较；需要判断"不存在"的调用方则显式检测该目录。`git rev-parse --path-format=absolute`能完成同样的工作，但要求 git 2.31 及以上版本。
+所有路径比较都通过 `resolve_dir` 辅助函数在物理路径上进行，且每个参与比较的值都在赋值时解析，而非在比较时解析。git 报告的始终是已解析的路径，因此只要检出之上任意一层存在符号链接，拿它与未解析的路径相比较就会不相等——家目录本身是符号链接即已足够，而 macOS 通过`/var` -> `private/var`使每个`mktemp`路径都如此。这种不匹配会把已有的受管安装误判为外来克隆，并在真正的容器旁再建一个容器。同一缺陷在评审过程中又出现了两次，两次都是比较的一侧未经解析：一次是 curl 安装的`REPO_ROOT`，一次是与之比较的容器路径。因此`resolve_dir`在路径不存在时原样回显该路径而非失败，这样尚未创建的容器无需在每个调用点单独兜底，也就没有调用点会因遗漏兜底而与空路径比较；需要判断「不存在」的调用方则显式检测该目录。`git rev-parse --path-format=absolute`能完成同样的工作，但要求 git 2.31 及以上版本。
 
-在重指`current`之前，安装器会拒绝解析结果等于仓库自身的 staging 路径，以此落实"启动器绝不解析到 master 克隆"这一升级契约。
+在重指`current`之前，安装器会拒绝解析结果等于仓库自身的 staging 路径，以此落实"启动器绝不解析到 master 克隆"这一升级约定。
 
 ## Alternatives considered
 
-**把`~/.dsh/source/master`做成指向该任意克隆的符号链接。** 已否决。Git 会解析该符号链接并记录*真实*路径：经由它创建的 worktree 会存储`gitdir: …/<克隆>/.git/worktrees/<名称>`，而`git worktree list`报告的是该克隆。因此这个符号链接纯属装饰——没有任何代码读取它——却又暗示容器拥有该仓库。它还会静默失效：移动克隆后，`master`看似仍在却已悬空，而每个 staging worktree 都会以`fatal: not a git repository`失败。最糟的是，它把两个名称别名到同一棵树上，于是"current 绝不能是 master 克隆"这项检查会在字符串比较下通过，实则为假。`~/.dsh/source/master`是位置而非名称，且只有位置具有权威性。
+**把`~/.dsh/source/master`做成指向该任意克隆的符号链接。** 已否决。Git 会解析该符号链接并记录*真实*路径：经由它创建的 worktree 会存储`gitdir: …/<克隆>/.git/worktrees/<名称>`，而`git worktree list`报告的是该克隆。因此这个符号链接纯属装饰——没有任何代码读取它——却又暗示容器拥有该仓库。它还会静默失效：移动克隆后，`master`看似仍在却已悬空，而每个 staging worktree 都会以`fatal: not a git repository`失败。最糟的是，它把两个名称别名到同一棵树上，于是「current 绝不能是 master 克隆」这项检查会在字符串比较下通过，实则为假。`~/.dsh/source/master`是位置而非名称，且只有位置具有权威性。
 
-**把检出自身提升为`current`的目标。** 已否决：升级契约要求`current`必须是位于 staging 分支上的干净 staging worktree，绝不能是 feature、review 或 detached 检出。这还会使每次升级都改写贡献者正在编辑的那棵树。
+**把检出自身提升为`current`的目标。** 已否决：升级约定要求`current`必须是位于 staging 分支上的干净 staging worktree，绝不能是 feature、review 或 detached 检出。这还会使每次升级都改写贡献者正在编辑的那棵树。
 
 **把就地链接保留在提示或`DSH_ADOPT`开关之后。** 已否决；本次变更的早期修订版本正是如此实现，之后被移除。分叉的形态本身就是缺陷，因此把它保留为一个选项等于保留了问题，并使此后每次改动需要推敲的状态翻倍——提示、开关、工作树不干净的警告，以及第二条链接路径，全都只为维持一种本不该产生的形态而存在。就地链接最初的动机——让脚本能针对本地源码进行测试——在接管方案下依然成立：以检出的`HEAD`为起点创建的 staging worktree 运行的是同一份代码。`DSH_SOURCE`仍是安装另一棵树的退路。
 
-**在工作树不干净时发出警告或提示。** 已否决：以`HEAD`为起点的`worktree add`本就无法带上未提交的内容，因此该行为是确定的，提示只会增加一个用户无法做出不同选择的决策点。改为在文档中说明该契约。
+**在工作树不干净时发出警告或提示。** 已否决：以 `HEAD` 为起点的`worktree add`本就无法带上未提交的内容，因此该行为是确定的，提示只会增加一个用户无法做出不同选择的决策点。改为在文档中说明该约定。
 
 **把被接管克隆的 staging worktree 放在该克隆旁边**（`~/src/staging-*`），而非放进`~/.dsh/source`。已否决：`current`和 PATH 启动器都是每用户唯一的，因此把 worktree 散落到各个克隆的父目录中，会重新引入 source 容器本就为之而设、意在杜绝的同级克隆蔓延问题。
 
 ## Consequences
 
-现在一套布局服务于所有安装，因此被接管的克隆无需该技能所述的一次性迁移，即可由`dsh-upgrade`升级，而且安装器不再有任何一条分支会产生无法升级的形态。检出内运行仍然绝不改动工作树。
+现在一套布局服务于所有安装，因此被接管的克隆无需该 skill 所述的一次性迁移，即可由`dsh-upgrade`升级，而且安装器不再有任何一条分支会产生无法升级的形态。检出内运行仍然绝不改动工作树。
 
 代价是：贡献者不能再把 PATH 指向某个检出、并让`dsh`随其切换分支而跟随该工作树；启动器现在解析到的是一个固定在安装时所接管`HEAD`上的 staging worktree。重新运行安装器会再次接管当前的`HEAD`。
 
@@ -48,4 +48,4 @@ Status: implemented
 
 `scripts/install.sh` 现有一套位于 `apps/cli/tests/install-script.spec.ts` 的真实 shell PTY 回归测试，使用 stub 依赖覆盖接管路径和 curl 风格路径。curl 风格安装默认使用公开的 `deepseek-ai/deepseek-harness-sdk` 源，而以 pnpm/npx 替换安装器仍是另一项工作。
 
-验证是手工完成的，通过一个一次性测试装置以打桩的`pnpm`驱动真实脚本：接管独立克隆；从 linked worktree 接管进其已有容器；显式`DSH_SOURCE`仍回到克隆路径；工作树不干净时静默接管、既不提示也不警告，且其未提交文件留在原处；非 git 检出失败并给出指引；以及`curl`式克隆安装断言所构建的布局——正是这项回归测试捕获了`REPO_ROOT`未解析的缺陷。交互路径在 tmux 下从一个不干净的检出走通，确认整个过程不出现接管提示即可到达启动器，最终`dsh`从新的 staging worktree 运行，而原检出保持其分支不变、未提交文件仍在。
+验证是手工完成的，通过一个一次性 harness以打桩的 `pnpm` 驱动真实脚本：接管独立克隆；从 linked worktree 接管进其已有容器；显式设置 `DSH_SOURCE` 仍会重新选择克隆一棵独立代码树；工作树不干净时静默接管、既不提示也不警告，且其未提交文件留在原处；非 git 检出失败并给出指引；以及`curl`式克隆安装断言所构建的布局——正是这项回归测试捕获了`REPO_ROOT`未解析的缺陷。交互路径在 tmux 下从一个不干净的检出走通，确认整个过程不出现接管提示即可到达启动器，最终`dsh`从新的 staging worktree 运行，而原检出保持其分支不变、未提交文件仍在。
diff --git a/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.i18n.yaml b/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.i18n.yaml
index 96754a36f3..0970b95acd 100644
--- a/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md
 2026-08-02-native-github-stacks-and-optional-rebases.md: a349ed18a27ab006384310e4318f057dbf8873b1
-2026-08-02-native-github-stacks-and-optional-rebases.zh.md: 0205eb475bfe951f8382d61bf19df988027afb13
+2026-08-02-native-github-stacks-and-optional-rebases.zh.md: 21964e3c59719d63214cabeaa5339de9933c87b5
diff --git a/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.zh.md b/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.zh.md
index 0205eb475b..21964e3c59 100644
--- a/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.zh.md
+++ b/.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 「落地堆叠」通过 `gh stack merge <stack-number> --yes --merge` 合并整个官方堆叠。部分落地需要明确指定边界 PR，并合并从底部到该 PR 的前缀。工作流绝不回退到逐个执行 `gh pr merge` 和手动调整 base。原生直接合并要么全部成功，要么全部不合并；合并队列可能分组处理所选 PR，因此只有每个所选 PR 都分别达到 `MERGED`，落地才算完成。
 
-merge-forward 和 rebase 都可以作为独立 PR 与官方堆叠 PR 的历史刷新方式，包括评审后。改写远端历史时，必须使用精确 lease 或受 lease 保护的 `gh stack` 推送路径；如果远端已经前移，操作必须中止。禁止直接使用 `--force`。[增量更新 base 的决策](2026-07-26-incremental-pr-base-retargeting.md)仍负责 merge-forward 选项。
+merge-forward 和 rebase 都可以作为独立 PR 与官方堆叠 PR 的历史刷新方式，包括评审后。改写远端历史时，必须使用精确 lease 或受 lease 保护的 `gh stack` 推送路径；如果远端已经发生变化，操作必须中止。禁止直接使用 `--force`。[增量更新 base 的决策](2026-07-26-incremental-pr-base-retargeting.md)仍负责 merge-forward 选项。
 
 相关检查通常在发布前运行。`gh stack sync` 是明确的例外，因为它在一次操作中完成获取、级联 rebase 和推送：随后立即验证每个已改写的层；这些验证通过前，不得合并任何受影响的 PR。每次改写推送后，都要重新审计当前 head、未解决的评审线程、批准状态、可合并性和检查结果，因为先前的 commit OID 和内联锚点可能已经过时。
 
diff --git a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml
index 1b704da8f1..b8e885d109 100644
--- a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.md
 2026-08-04-forward-only-pr-issue-status.md: dd567707bc7fccd0a631943ab3ffd2838a7f2f76
-2026-08-04-forward-only-pr-issue-status.zh.md: f19cceafbde074d298a7c7f27829c8ab919f00b6
+2026-08-04-forward-only-pr-issue-status.zh.md: f7fee58d6afb812f97569ae4d86c3d6504f35752
diff --git a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md
index f19cceafbd..f7fee58d6a 100644
--- a/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md
+++ b/.agents/notes/implemented/process/2026-08-04-forward-only-pr-issue-status.zh.md
@@ -10,7 +10,7 @@ Issue Project 状态表示工作所处阶段，同仓库内精确匹配的解决
 
 ## 决策
 
-PR 事件和 PR 评审事件会把当前 PR 阶段投射到同仓库内被精确引用的每个解决型 Issue。草稿 PR，或既没有评审请求也没有已提交评审的非草稿 PR，目标状态为 `In progress`。具备上述任一类评审活动的非草稿 PR，目标状态为 `In review`。
+PR 事件和 PR 评审事件会把当前 PR 阶段投射到同仓库内由解决型关键字精确引用的每个 Issue。草稿 PR，或既没有评审请求也没有已提交评审的非草稿 PR，目标状态为 `In progress`。具备上述任一类评审活动的非草稿 PR，目标状态为 `In review`。
 
 活跃状态依次为 `Inbox`、`Backlog`、`Ready`、`In progress` 和 `In review`。只有目标状态在该顺序中位于当前状态之后时，投射才会写入。投射不会把 Issue 状态向后移动，不会改动 `Done` 或 `No action`，也不会把没有 Project 状态的 Issue 加入 Project。生命周期路径独立于 PR 元数据校验；另行执行的必需 PR 政策检查继续强制落实标签、引用和优先级一致性。
 
@@ -32,7 +32,7 @@ PR 事件和 PR 评审事件会把当前 PR 阶段投射到同仓库内被精确
 
 ## 后果
 
-- PR 事件会自动纠正停留在 `Inbox`、`Backlog` 或 `Ready` 的解决型 Issue。
+- PR 事件会自动纠正由该 PR 解决但仍停留在 `Inbox`、`Backlog` 或 `Ready` 的 Issue。
 - 若 Issue 创建于最后一个相关 PR 事件之后，则必须等待后续 PR 事件或人工更新状态，因为系统不会反向查找或定时扫描。
 - 即使存在历史评审活动，草稿 PR 仍保持 `In progress`；只有非草稿 PR 才会以 `In review` 为目标状态。
 - 终态以及顺序中更靠后的活跃状态不会倒退。
diff --git a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml
index 7f9a5eee29..f742579d36 100644
--- a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md
 2026-08-06-coverage-uncovered-locations.md: 27c466e7ae505a2d318f8b21d442c31619610f59
-2026-08-06-coverage-uncovered-locations.zh.md: 93eeb863e51679c60d9e0ccfc742156c098aeca4
+2026-08-06-coverage-uncovered-locations.zh.md: 482b17227c4198ee27411da16b047288b331af9c
diff --git a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
index 93eeb863e5..482b17227c 100644
--- a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
@@ -4,13 +4,13 @@ Status: implemented
 
 [English](2026-08-06-coverage-uncovered-locations.md) | 中文
 
-## Problem
+## 问题
 
-per-file 100% 覆盖率门禁失败时，vitest 只输出文件级错误行（`ERROR: Coverage for lines (…) does not meet global threshold (100%) for <file>`）——知道哪个文件没达标，不知道差在哪几行。内置 `text` 报表虽有 Uncovered Line #s 列，但它是全仓几百个文件的大表：该列按表宽截断、只有行号没有列号、不区分语句/分支/函数，且达标文件同样占行。结果是 CI 上的覆盖率红报不可直接行动，定位具体缺口只能本地重跑一遍 html 报表。
+per-file 100% 覆盖率门禁失败时，vitest 只输出文件级错误行（`ERROR: Coverage for lines (…) does not meet global threshold (100%) for <file>`）——知道哪个文件没达标，不知道差在哪几行。内置 `text` 报表虽有 Uncovered Line #s 列，但它是全仓几百个文件的大表：该列按表宽截断、只有行号没有列号、不区分语句/分支/函数，且达标文件同样占行。结果是 CI 上的覆盖率红报无法直接据此处理，定位具体缺口只能本地重跑一遍 html 报表。
 
-## Decision
+## 决策
 
-`scripts/coverage-uncovered-locations.cjs` 是一个自定义 istanbul reporter（`ReportBase` 子类）：对每个低于 100% 的文件，按未覆盖语句、未走的分支路径、未调用函数各输出一条自含的单行记录 `<path>:<line>:<col> uncovered <kind> …`——terminal 与 CI 日志中可直接点击跳转，也便于 grep。全部文件达标时零输出。istanbul 报表生成先于 threshold 校验，因此记录恰好落在既有 ERROR 行上方。
+`scripts/coverage-uncovered-locations.cjs` 是一个自定义 istanbul reporter（`ReportBase` 子类）：对每个低于 100% 的文件，为每个未覆盖语句、每条未走的分支路径和每个未调用函数各输出一条自含的单行记录 `<path>:<line>:<col> uncovered <kind> …`——terminal 与 CI 日志中可直接点击跳转，也便于 grep。全部文件达标时零输出。istanbul 报表生成先于 threshold 校验，因此记录恰好落在既有 ERROR 行上方。
 
 接线是单点的：根 `vitest.config.ts` 的 coverage 块是全仓唯一覆盖率配置，CI lane（`run-gates ci-coverage`）、本地 `test:coverage` 与聚焦跑（`--coverage.include`）共用它。该 reporter 以绝对路径（`fileURLToPath`）加入 CI 与本地两个 reporter 数组——istanbul-reports 的 `create()` 对非内置名回退为裸 `require(name)`，相对路径会按 istanbul 自己的包目录解析。
 
@@ -18,24 +18,24 @@ per-file 100% 覆盖率门禁失败时，vitest 只输出文件级错误行（`E
 
 - istanbul 的 0 基列号转为 1 基（编辑器与终端链接的约定）。
 - v8 对整行语句给出 `end.column = Infinity`：跨行时降级为只带行号的 `(to <line>)` 后缀，单行时省略后缀。
-- 隐式分支臂（如缺省 else）可能不带位置，回退到分支自身的 span，保证记录仍可点击；分支记录标注类型与 `path k/n`。
+- 隐式分支臂（如缺省 else）可能不带位置，reporter 会回退到分支自身的 span，保证记录仍可点击；分支记录标注类型与 `path k/n`。
 - 同文件内记录按行、列排序；不设条数上限。
 
 配套两处：根 `package.json` 增补 devDependency `istanbul-lib-report`（pnpm 严格布局下 `scripts/` 摸不到嵌套依赖）；`knip.json` 根 workspace 的 entry/project 通配增加 `scripts/**/*.cjs`，使该文件及其依赖对 hygiene 门禁可见。
 
 CJS 是被迫的形态，也是 ESM-everywhere 纪律的一个有据例外：istanbul 在 tsx/Vite 管线之外用裸 `require()` 装载自定义 reporter，TypeScript 无法参与；`require(esm)` 返回的命名空间对象也过不了它的 `new Cons(cfg)` 构造，CommonJS 是唯一可靠形态。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-- **依赖内置 `text` 报表的 Uncovered Line #s 列。** 正是问题现状：全仓大表、列宽截断、只有行号、不分种类、达标文件同列——CI 日志里不可行动。
-- **加 `json` reporter，另写 wrapper 脚本失败后读 `coverage-final.json` 后处理。** 纯 ESM/TS 可行，但 wrapper 必须同时包住 `package.json` 的 `test:coverage` 与 run-gates 的 gate 两个入口，命令形状随之改变；自定义 reporter 路线只动一处配置，两个入口自动生效。
-- **用 TypeScript/ESM 写 reporter。** istanbul 的装载机制（管线外裸 `require`）决定了不可行，见上；为一个报表文件把装载机制换掉不成比例。
+- **依赖内置 `text` 报表的 Uncovered Line #s 列。** 正是问题现状：全仓大表、列宽截断、只有行号、不分种类、达标文件同列——无法直接根据 CI 日志处理。
+- **加 `json` reporter，另写包装脚本失败后读 `coverage-final.json` 后处理。** 纯 ESM/TS 可行，但包装脚本必须同时包住 `package.json` 的 `test:coverage` 与 run-gates 的 gate 两个入口，命令形状随之改变；自定义 reporter 路线只动一处配置，两个入口自动生效。
+- **用 TypeScript/ESM 写 reporter。** istanbul 的装载机制（管线外裸 `require`）决定了不可行，见上；为一个报表文件把装载机制换掉，代价不成比例。
 
-## Verification
+## 验证
 
-本地矩阵：故意制造未达标时三类记录齐全、位置与埋点一致；混合现场只输出未达标文件（同跑内 100% 的文件静默）；全绿跑零输出、退出码 0。CI 实证：临时在 `clampTimeout` 埋入一处不可达语句/分支/函数后，coverage lane 在全部测试通过（632 文件 / 10326 用例）、仅 threshold 失败的隔离条件下，把 4 条记录打印在 ERROR 行上方（证据链接见 PR #1716 描述）；演示提交在合并前已从分支撤除。
+本地矩阵：故意制造未达标时三类记录齐全、位置与埋点一致；混合运行只输出未达标文件（同跑内 100% 的文件静默）；全绿跑零输出、退出码 0。CI 实证：临时在 `clampTimeout` 埋入一处不可达语句/分支/函数后，coverage lane 在全部测试通过（632 文件 / 10326 用例）、仅 threshold 失败的隔离条件下，把 4 条记录打印在 ERROR 行上方（证据链接见 PR #1716 描述）；演示提交在合并前已从分支撤除。
 
-## Consequences
+## 后果
 
 - 覆盖率红报自足：日志直接给出精确行列号与缺口种类，不再需要本地重跑 html 报表定位。
 - 代价是一个 CJS 文件的纪律例外与一个根 devDependency；全绿运行零输出，不增加日志噪音。
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
index 8ba8380bf1..15045d2590 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
 2026-08-06-doc-site-carries-its-images.md: 4078a9b6251cf67456590ae25602a9f288c88dc1
-2026-08-06-doc-site-carries-its-images.zh.md: a9afb138d45d1ab991963b997e408477cf88110b
+2026-08-06-doc-site-carries-its-images.zh.md: 134bd20e628322dc9c6d95cb261648618fbdf7a7
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
index a9afb138d4..134bd20e62 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
@@ -4,17 +4,17 @@ Status: implemented
 
 [English](2026-08-06-doc-site-carries-its-images.md) | 中文
 
-## Problem
+## 问题
 
-`scripts/project-doc-site.ts` 会把发布清单未收录的仓库相对目标一律改写成 GitHub 地址，对图片而言就是 `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`。站点构建不拷贝任何文件：`srcDir` 是用完即弃的 `.generated` 树，VitePress 没有设置 `publicDir`（其默认值 `<srcDir>/public` 恰好位于投影每次运行时删除的那棵树里），而写进去的只有 Markdown。
+`scripts/project-doc-site.ts` 会把发布 manifest（元数据清单）未收录的仓库相对目标一律改写成 GitHub 地址，对图片而言就是 `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`。站点构建不拷贝任何文件：`srcDir` 是用完即弃的 `.generated` 树，VitePress 没有设置 `publicDir`（其默认值 `<srcDir>/public` 恰好位于投影每次运行时删除的那棵树里），而写进去的只有 Markdown。
 
 这只对公开仓库成立。本仓库是私有的，而 `raw.githubusercontent.com` 对未认证请求一律回 404——github.com 上的登录会话也不能认证它，因为 GitHub 自家界面是用另一套单独签名的地址提供私有 blob 的。于是站点上的每一张图片对每一位读者都是坏的，却没有任何门禁能说出来：`verify-md-links` 与投影校验的是目标文件**在仓库里是否存在**，那与站点读者能否取到它是两个问题。
 
-## Decision
+## 决策
 
-`rewriteMarkdown` 新增可选的 `placeImage(absPath): string`。当页面引用了一张清单未作为页面发布的图片时，投影把该文件复制进生成树中该页面的旁边，并把引用改写为 `./<basename>`；随后 Vite 会像处理其他站点资源一样打包它。仓库可见性再也影响不到已发布页面。
+`rewriteMarkdown` 新增可选的 `placeImage(absPath): string`。当页面引用了一张manifest 未作为页面发布的图片时，投影把该文件复制进生成树中该页面的旁边，并把引用改写为 `./<basename>`；随后 Vite 会像处理其他站点资源一样打包它。仓库可见性再也影响不到已发布页面。
 
-副本落在页面旁边，而不是某个共享资源目录。每个 locale 的路由树各持一份副本，因此同一个相对 URL 在 `guide/` 与 `en/guide/` 下都正确，无需按 locale 计算前缀；清单撤下某页时，它的资源也随之消失。一张表登记所有被投影的路径——页面与图片一视同仁——同一路径出现第二个来源就抛错，与既有的重复路由检查同一个立场，而不是让最后写入的那个静默胜出。
+副本落在页面旁边，而不是某个共享资源目录。每个 locale 的路由树各持一份副本，因此同一个相对 URL 在 `guide/` 与 `en/guide/` 下都正确，无需按 locale 计算前缀；manifest 撤下某页时，它的资源也随之消失。一张表登记所有被投影的路径——页面与图片一视同仁——同一路径出现第二个来源就抛错，与既有的重复路由检查同一个立场，而不是让最后写入的那个静默胜出。
 
 只有真实路径位于仓库内的普通文件才会被拷贝，其余一律让投影失败并点名页面与目标。链接改写只需要知道目标**存在**，但发布是把它的字节拷上站点，因此一个逃出仓库的引用——经由 `../..` 或指向树外的符号链接——会把构建机上的文件放到已发布页面上。引用自带的 `?query` 或 `#fragment` 会随安置后的 URL 一同保留，与 GitHub 分支一贯的做法一致；文件名做百分号编码，因为目标位于 Markdown 内联目标的位置。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 正本 Markdown 照旧写普通的仓库相对图片路径，因此同一份文件在 GitHub 上和站点上都能正常显示。没有任何文档为了迁就 VitePress 而写站内绝对 URL。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **把 `publicDir` 设到 `.generated` 之外，并使用站内绝对 URL。** 投影这边的活动部件更少，但同一份 Markdown 在仓库中阅读时，每一处图片引用都会是坏的，而正本文档是两种方式都要读的。
 
@@ -32,12 +32,12 @@ Status: implemented
 
 **等仓库转为公开。** 那只是消除症状，不会让站点自给自足，而且每一张图片都会让站点隐式依赖 GitHub 的可用性与限流。
 
-## Consequences
+## 后果
 
-已发布文档中的图片，现在无论谁在阅读、无论仓库是否公开都能显示，站点构建也不再为图片依赖 GitHub 的运行时可达性。生成树会为每个 locale 各增加一份被引用图片的副本——配置模型指南里的四张截图，每个 locale 约 270 KB。
+已发布文档中的图片，现在无论谁在阅读、无论仓库是否公开都能显示，站点构建也不再为图片依赖 GitHub 的运行时可达性。生成树会为每个 locale 各增加一份被引用图片的副本——模型提供方指南里的四张截图，每个 locale 约 270 KB。
 
 **未发布**文档引用的图片不受影响。纯文本投影会相对于公开源主页解析它们；不在站点上的文档没有站点构建可以承载其资源。
 
-## Testing
+## 测试
 
-`scripts/project-doc-site.spec.ts` 覆盖：placer 收到解析后的绝对路径且其返回的 URL 落进 Markdown、被安置的引用保留其 fragment、存在 placer 时已发布页面的链接仍解析到自己的路由、以及不传 placer 时不变的 GitHub raw 回退。`publishableImage` 另有直接覆盖：仓库内的普通文件被接受，而目标逃出仓库的符号链接、仓库外的路径与目录一律拒绝。`pnpm docs:check` 会带着配置模型指南的截图构建站点，并在来源缺失时失败；被拷贝的文件及其 `./<basename>` 引用已在 `website/.generated` 与运行中的 `docs:dev` 里核实（两个 locale 均 `naturalWidth > 0`）。
+`scripts/project-doc-site.spec.ts` 覆盖：placer 收到解析后的绝对路径且其返回的 URL 落进 Markdown、被安置的引用保留其 fragment、存在 placer 时已发布页面的链接仍解析到自己的路由、以及不传 placer 时不变的 GitHub raw 回退。`publishableImage` 另有直接覆盖：仓库内的普通文件被接受，而目标逃出仓库的符号链接、仓库外的路径与目录一律拒绝。`pnpm docs:check` 会带着模型提供方指南的截图构建站点，并在来源缺失时失败；被拷贝的文件及其 `./<basename>` 引用已在 `website/.generated` 与运行中的 `docs:dev` 里核实（两个 locale 均 `naturalWidth > 0`）。
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
index 2a4a389174..e42cc4e74a 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
 2026-08-06-in-repository-landlock-release.md: 3ae9e9c3c50a1d0202a345e419cb2b7079e29ffa
-2026-08-06-in-repository-landlock-release.zh.md: 9f2233f6ae95620d7221f83648b5dc9b4cf8c7d2
+2026-08-06-in-repository-landlock-release.zh.md: b890346e861469eac9b7a08c14912be1a4f99ece
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
index 9f2233f6ae..b890346e86 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器契约及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
+`@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器约定及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
 
 发布镜像还造成重复的发布协调工作：导出源码、更新另一份锁文件、运行另一套发布工作流、发布原生包家族，然后回到本仓库更新注册表依赖。npm 用户的实际需求并未改变，这种拆分却增加了从源码到二进制的溯源、回滚和安全修复协调难度。
 
@@ -33,7 +33,7 @@ Status: implemented
 
 ## 后果
 
-同一个 PR 可以同时修改启动器协议、TypeScript 入口代码、原生源码、harness 消费方式和发布路径测试，并从同一份锁文件解析这些内容。发布 tag 现在标识源码、消费方集成、构建指令，以及主仓库测试过的 tarball。第一次成功从本仓库发布后，独立镜像便不再属于发布路径，可以归档。
+同一个 PR 可以同时修改启动器协议、TypeScript 入口代码、原生源码、harness 消费方式和发布路径测试，并从同一份锁文件解析这些内容。发布 tag 现在标识源码、消费方集成、构建指令，以及主仓库测试过的 tarball。独立镜像已不再属于发布路径，可以在第一次成功从本仓库发布后归档。
 
 npm 消费方改为安装 `@deepseek-ai/node-addon-landlock-run`；原先的非 scoped 包名不会被静默重定向。受支持的 Linux 主机会下载 scoped 入口包及与其架构匹配的包，并跳过另一架构的包。不受支持的主机不会收到平台二进制文件，并继续沿用现有的确定性失败闭合探测路径。
 
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
index dec1b79d6a..4cb53f0740 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
 2026-08-08-api-remotes-generated-contract-build.md: 947465b19a7c399038ae8a3106f7563592365a8d
-2026-08-08-api-remotes-generated-contract-build.zh.md: 7b559cd966c4acc055d41379c15f46fdfc649a00
+2026-08-08-api-remotes-generated-contract-build.zh.md: 2aea51a72509dd486c557c9a322a1e8604b877c3
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
index 7b559cd966..2aea51a725 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
@@ -6,9 +6,9 @@ Status: implemented
 
 ## 问题
 
-Host 的 `@Remote` 方法需要先由 TypeRT 生成 `/remote` 声明和运行时贡献，Client 的 `api-remotes/src/client/index.ts` 才能通过类型检查并打包这些贡献。若根构建先把 Host 与 Client 两张 Project Reference 图一起交给 tsc，Client 会在生成产物存在之前编译；若增加独立 contracts 预处理，又会让 generator 脱离正常 Host 图重复编译，并允许陈旧产物掩盖错误依赖。
+Host 的 `@Remote` 方法需要先由 TypeRT 生成 `/remote` 声明和运行时贡献，Client 的 `api-remotes/src/client/index.ts` 才能通过类型检查并打包这些贡献。若根构建先把 Host 与 Client 两张 Project Reference 图一起交给 tsc，Client 会在生成产物存在之前编译；若增加独立契约生成预处理，又会让 generator 脱离正常 Host 图重复编译，并允许陈旧产物掩盖错误依赖。
 
-该顺序依赖不能改变仓库的普通 package 规则。正常 package 只属于一个 TypeScript face：Host package 登记在 `tsconfig.host.json`，Client package 登记在 `tsconfig.client.json`。一个 Client plugin 同时具有 Node loader 入口与 browser 入口，只是打包产物形态，不是拆分 TypeScript project 的理由。
+该顺序依赖不能改变仓库的普通包规则。正常包只属于一个 TypeScript face：Host 包登记在 `tsconfig.host.json`，Client 包登记在 `tsconfig.client.json`。一个 Client 插件同时具有 Node loader 入口与 browser 入口，只是打包产物形态，不是拆分 TypeScript project 的理由。
 
 ## 决策
 
@@ -26,9 +26,9 @@ Vite Web build
 
 每个 tsc 阶段都是唯一的 TypeScript 编译器路径，负责向 `lib/types` 发射 JavaScript、声明和增量状态。tsdown 只读取这些 JavaScript 并生成发布 bundle，不读取源码，也不生成声明。
 
-## 唯一的 package 特例
+## 唯一的包特例
 
-`api/remotes` 是唯一同时拥有 Host 与 Client composite project 的 package。Host project 包含 Agent/Session lookup 策略、Host 插件入口和 invariant；Client project 只包含需要等待生成契约的 `src/client/index.ts`：
+`api/remotes` 是唯一同时拥有 Host 与 Client composite project 的包。Host project 包含 Agent/Session lookup 策略、Host 插件入口和 invariant；Client project 只包含需要等待生成契约的 `src/client/index.ts`：
 
 ~~~text
 packages/api/remotes/
@@ -45,27 +45,27 @@ packages/api/remotes/
 
 包根 `tsconfig.json` 是只引用两个具体 project 的 solution，不进入任何 aggregate 或直接消费方的依赖图。根 Host aggregate 与 `host/apiproxy` 引用 `api/remotes/tsconfig.host.json`；根 Client aggregate 与 `client/ui-goal` 引用 `api/remotes/tsconfig.client.json`。`ui-goal` 本身仍是普通的单一 Client project。workspace constraints 门禁遍历可达的 Project Reference 图；凡已声明 face 的 project 引用了拆分包的 solution 根或另一侧 leaf，门禁都会拒绝，而只有 `tsconfig.json` 的目标仍可由任一 face 引用。
 
-两个 project 使用互不重叠的 `files` 和不同的 `.tsbuildinfo`，因此可以共享 `lib/types` 而不重复发射任何源码。若未来需要两侧共用一份实现，应把实现移入中立 package，不能把同一源码同时交给两个 emitting project。
+两个 project 使用互不重叠的 `files` 和不同的 `.tsbuildinfo`，因此可以共享 `lib/types` 而不重复发射任何源码。若未来需要两侧共用一份实现，应把实现移入中立包，不能把同一源码同时交给两个 emitting project。
 
-这个例外由生成契约的真实先后关系决定，不是可供普通 package 选择的模板。新增 package 仍只能登记进一个 aggregate；只有修改本决策并证明存在另一条不可消除的生成依赖，才能增加例外。
+这个例外由生成契约的真实先后关系决定，不是可供普通包选择的模板。新增包仍只能登记进一个 aggregate；只有修改本决策并证明存在另一条不可消除的生成依赖，才能增加例外。
 
 ## TypeRT 与 tsdown
 
 Host tsdown 在普通根配置中启用 `typertPlugin({ mode: 'workspace', faces: ['host'] })`。generator 只以 `tsconfig.host.json` 为 program 种子，生成 `typert.host.*` 以及 Host 契约投影出的 `typert.remote-client.*`；Client tsdown 不启动 TypeRT，也不分析 Client aggregate。
 
-TypeScript compiler face 与 TypeRT 运行时产物 face 是两层概念。普通 `dshClient` package 即使只有一个 compiler project，也可以按公开 subpath 同时贡献 Host 与 Client 运行时模型；aggregate 显式引用 `tsconfig.host.json` 或 `tsconfig.client.json` 时，analyzer 才把该 project 限定到对应 face。因此 `api-remotes` 的 Host 分析不会顺带注册其 Client 入口，普通双入口 package 的 Host 模型也不会丢失。
+TypeScript compiler face 与 TypeRT 运行时产物 face 是两层概念。普通 `dshClient` 包即使只有一个 compiler project，也可以按公开 subpath 同时贡献 Host 与 Client 运行时模型；aggregate 显式引用 `tsconfig.host.json` 或 `tsconfig.client.json` 时，analyzer 才把该 project 限定到对应 face。因此 `api-remotes` 的 Host 分析不会顺带注册其 Client 入口，普通双入口包的 Host 模型也不会丢失。
 
-Host 与 Client 两次 tsdown 都接收 `vendor/*`、`packages/*/*` 和 `apps/cli` 这组完整 workspace。根配置不扫描 `lib/types/client/index.js`，不维护 package 分类表，也不使用 tsdown filter；包内配置根据 `DSH_BUILD_FACE` 返回本阶段入口。
+Host 与 Client 两次 tsdown 都接收 `vendor/*`、`packages/*/*` 和 `apps/cli` 这组完整 workspace。根配置不扫描 `lib/types/client/index.js`，不维护包分类表，也不使用 tsdown filter；包内配置根据 `DSH_BUILD_FACE` 返回本阶段入口。
 
-普通 Client plugin 在 Host pass 返回空配置，在 Client pass 同时生成 Node loader 入口与 browser bundle。`api-remotes` 的 `clientBundle(..., { hostPhase: true })` 是唯一阶段例外：Host pass 生成其 Host 入口，Client pass 只生成 browser bundle。未指定 `DSH_BUILD_FACE` 的 package-local tsdown 仍同时返回该 package 的正常入口，供本地单包开发使用。
+普通 Client 插件在 Host pass 返回空配置，在 Client pass 同时生成 Node loader 入口与 browser bundle。`api-remotes` 的 `clientBundle(..., { hostPhase: true })` 是唯一阶段例外：Host pass 生成其 Host 入口，Client pass 只生成 browser bundle。未指定 `DSH_BUILD_FACE` 的包内 tsdown 仍同时返回该包的正常入口，供本地单包开发使用。
 
 ## 考虑过的替代方案
 
-**保留独立 contracts 预处理。** 这会在正常 Host Project Reference 图之外额外编译 generator，并让残留生成物掩盖 Client 过早进入 Host 图的问题。
+**保留独立契约生成预处理。** 这会在正常 Host Project Reference 图之外额外编译 generator，并让残留生成物掩盖 Client 过早进入 Host 图的问题。
 
 **一次执行根 `tsc -b tsconfig.json` 后再运行 tsdown。** Client tsc 在 Host tsdown 之前发生，无法从干净工作树获得 `/remote` 声明。
 
-**拆分所有包含 `src/client/index.ts` 的 package。** Node 与 browser 双入口是普通 Client plugin 的打包约定，不形成编译顺序依赖；普遍拆分只会增加 references 和增量状态的维护成本。
+**拆分所有包含 `src/client/index.ts` 的包。** Node 与 browser 双入口是普通 Client 插件的打包约定，不形成编译顺序依赖；普遍拆分只会增加 references 和增量状态的维护成本。
 
 **扫描 Client 编译产物或维护两份 workspace 清单。** 产物扫描会让 package 是否参与构建取决于残留文件，手工清单和 package 名过滤则会随目录调整产生漂移。完整 workspace 加包内 face 选择已经提供确定行为。
 
@@ -75,6 +75,6 @@ Host 与 Client 两次 tsdown 都接收 `vendor/*`、`packages/*/*` 和 `apps/cl
 
 干净构建成为顺序正确性的权威验证：没有任何既存 `/remote` 产物时，Host tsc 必须先成功，Host tsdown 必须生成契约，随后 Client tsc、Client tsdown 与 Web build 必须成功。任何阶段都不得把产物写进 `src`。
 
-[TypeScript 构建配置 Note](2026-06-17-ts-build-config.md)确定的 tsc-first 职责保持不变，但其单次全图 tsc 后再打包的命令形态由本文的有序阶段取代。[双 aggregate solution Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)确定的普通 package 单 aggregate 规则保持不变，本文只为 `api/remotes` 建立一个显式例外。
+[TypeScript 构建配置 Note](2026-06-17-ts-build-config.md)确定的 tsc-first 职责保持不变，但其单次全图 tsc 后再打包的命令形态由本文的有序阶段取代。[双 aggregate solution Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)确定的普通包单 aggregate 规则保持不变，本文只为 `api/remotes` 建立一个显式例外。
 
-Client 的独立构建不再是干净工作树上的自足入口；仓库命令、CI 和发布流程必须先运行 Host lib 阶段。普通 package 的开发者无需理解或复制该例外，仍按所属运行环境选择一个 aggregate。
+Client 的独立构建不再是干净工作树上的自足入口；仓库命令、CI 和发布流程必须先运行 Host lib 阶段。普通包的开发者无需理解或复制该例外，仍按所属运行环境选择一个 aggregate。
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
index 21006b51db..bd7ec32f75 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
 2026-08-08-browser-gif-evidence-chain.md: 93dfad76b3c4d0934120a164ab22dd4b898e2e01
-2026-08-08-browser-gif-evidence-chain.zh.md: 8aafc842e55775bade8885a792ce7b92dfc8df4e
+2026-08-08-browser-gif-evidence-chain.zh.md: 7b21abb23b5cb3a7b5dd8fd2accc561974008ad9
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
index 8aafc842e5..7b21abb23b 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求工作树干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器 context 时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
+[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求worktree 干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器上下文时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
 
 浏览器自动化会等待唯一且精确的语义状态。如果需要证明工具调用、拒绝或恢复，分镜就必须包含详情帧或轨迹帧：标明工具、显示其状态或稳定错误码，并展示后续结果。最终编码出的 GIF 始终是验证对象；如果查看器无法播放动画，应从该 GIF 中解码出代表性帧，而不能将源截图视为等效证据。
 
@@ -22,16 +22,16 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**只要可见状态看起来等价，就允许使用不同运行的画面。**视觉相似不能证明各画面共享同一状态、具有因果顺序或来自同一次场景执行。重新录制需要再执行一次真实模型场景，但能维持整套分镜所表达的主张。
+**只要可见状态看起来等价，就允许使用不同运行的画面。**视觉相似不能证明各画面共享同一状态、具有因果顺序或来自同一次场景执行。重新录制需要再执行一次真实模型轮次，但能维持整套分镜所表达的主张。
 
 **将聊天 transcript 视为工具恢复的充分证据。**最终答案能证明任务已经完成，却可能隐藏调用了哪个工具、失败是否为结构化失败，以及模型是否从该失败中恢复。轨迹帧或详情帧可以直接承载这些事实。
 
 **使用 fixture 或测试钩子替换无法访问的原生 UI。**这种做法通过改变被观察的产品路径来简化自动化。通过正常配置选用官方生产后端，既能保持受测实现真实，也能明确表述所采用的较窄运行模式。
 
-**相信资产分支推送成功或匿名请求成功。**推送只能证明 git 接受了相应字节，而私有仓库会有意拒绝未经身份验证的原始内容请求。经身份验证的字节校验与 GitHub Markdown 渲染验证，覆盖了评审者实际使用的两道发布边界。
+**相信资产分支推送成功，或依赖匿名请求。**推送只能证明 git 接受了相应字节，而私有仓库会有意拒绝未经身份验证的原始内容请求。经身份验证的字节校验与 GitHub Markdown 渲染验证，覆盖了评审者实际使用的两道发布边界。
 
 ## 后果
 
-GUI 证据现在能证明一次具有因果关系的执行，而不是将若干可信状态拼成集合；评审者既可以检查结构化的工具失败，也可以检查最终完成的结果。在 PR 正文被视为完成之前，发布验证可以发现陈旧的 PR head、损坏或位置错误的媒体文件，以及无效的图片 Markdown。
+GUI 证据现在能证明一次具有因果关系的执行，而不是若干可信状态的拼贴；评审者既可以检查结构化的工具失败，也可以检查最终完成的结果。在 PR 正文被视为完成之前，发布验证可以发现陈旧的 PR head、损坏或位置错误的媒体文件，以及无效的图片 Markdown。
 
-该工作流会占用额外的临时状态；录制失败后，可能需要重新执行一次由真实模型驱动的场景；通常还会增加一张详情帧和经身份验证的发布检查。相比交互式桌面，无头录制可使用的生产后端更少；每次选择这类后端时，都必须将其写入证据来源说明。
+该工作流会占用额外的临时状态；录制失败后，可能需要重新执行一次真实模型轮次；通常还会增加一张详情帧和经身份验证的发布检查。相比交互式桌面，无头录制可使用的生产后端更少；每次选择这类后端时，都必须将其写入证据来源说明。
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
index a21ac5cfe9..ced8e532bb 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
 2026-07-20-remove-stdio-and-echo-agents.md: 256e626f4ff41016d0227eef7cc3e4e51e15058b
-2026-07-20-remove-stdio-and-echo-agents.zh.md: bb7a2abd8be73ac3ea089121592b3f26162bf619
+2026-07-20-remove-stdio-and-echo-agents.zh.md: 317f3f6f0910c963e22f2a2f7e33ba8666cf512d
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
index bb7a2abd8b..317f3f6f09 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-DeepSeek Harness 在 TUI 和 Headless coding agent 之外，还提供了两个重复的产品 agent（智能体）。面向行的 stdio agent 使用混合的提示符/输出协议，同时重复实现终端交互与非交互执行。Echo 则以无需联网的 mock 模型加一个教学工具重复实现 Headless，把测试 fixture（测试前置数据）变成面向用户的 agent 和默认快速上手路径。
+DeepSeek Harness 在 TUI 和 Headless coding agent（智能体）之外，还提供了两个重复的产品 agent。面向行的 stdio agent 使用混合的提示符/输出协议，同时重复实现终端交互与非交互执行。Echo 则以无需联网的 mock 模型加一个教学工具重复实现 Headless，把测试 fixture（测试前置数据）变成面向用户的 agent 和默认快速上手路径。
 
-两个 agent 的配套实现都不止叶节点配置。stdio 拥有 UI 插件、app 包（package）、SDK 接口、REPL 叶节点、提示符协议和 Loader 测试。Echo 拥有可运行命令、mock 适配器、工具、CI 演示门禁、图谱条目、教学引用和共享测试 fixture。保留其中任何产品路径，都会间接保留这个重复的 agent。
+两个 agent 的配套实现都不止叶节点配置。stdio 拥有 UI 插件、app 包、SDK 接口、REPL 叶节点、提示符协议和 Loader 测试。Echo 拥有可运行命令、mock 适配器、工具、CI 演示门禁、图谱条目、教学引用和共享测试 fixture。保留其中任何产品路径，都会间接保留这个重复的 agent。
 
-标准输入输出仍是 ACP、JSON-RPC、MCP 和子进程的协议边界。确定性模型适配器也仍可用于测试。这些机制不足以成为保留面向行或仅使用 mock 的产品 agent 的理由。
+标准输入输出仍是 ACP（Agent Client Protocol）、JSON-RPC、MCP 和子进程的协议边界。确定性模型适配器也仍可用于测试。这些机制不足以成为保留面向行或仅使用 mock 的产品 agent 的理由。
 
 ## 决策
 
@@ -22,20 +22,20 @@ DeepSeek Harness 在 TUI 和 Headless coding agent 之外，还提供了两个
 - [`dsh run`](../../../../apps/cli/README.md) 负责非交互式执行。其 `headless` profile 是产品组装；`examples/headless-agent` 负责回放快照、通用真实 agent 测试套件和未导出的无密钥 Loader driver。
 - [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) 和 `@deepseek-ai/dsh-jsonrpc` 负责各自的分帧协议集成。
 
-SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换为 `tui`；生成的 TUI 工程组合 `@deepseek-ai/dsh-tui`，并创建或恢复一个确切会话。仓库中的演示文档要求 DeepSeek API key，并优先引导到真实的 Headless 或 TUI agent。
+SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换为 `tui`；生成的 TUI 工程组合 `@deepseek-ai/dsh-tui`，并创建或恢复恰好一个会话。仓库中的演示文档要求 DeepSeek API key，并优先引导到真实的 Headless 或 TUI agent。
 
 无密钥验证由测试负责。Headless Loader 冒烟测试使用 fixture 适配器验证真实工具往返；`dsh` built-bin 测试套件固定已发布的一次性入口和输出；产品 Headless 快照固定持久化；Headless PTY 关闭 e2e 固定信号升级。各包专属的 Loader 测试则将确定性适配器放在对应场景旁。其中任何一项都不会作为可运行的 mock agent 对外暴露。
 
 ## 验证
 
-TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果契约和工具调用契约。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
+TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果约定和工具调用约定。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
 
-构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口，包括输出和无效参数。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）契约。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
+构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口、输出和无效参数行为。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）约定。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
 
 ## 曾考虑的替代方案
 
-- **仅为 pipe 保留面向行 agent**：不予采纳，因为 Headless 已提供有界任务契约、格式纯净的 stdout、持久完成边界和进程退出状态。
-- **将 readline helper 作为包保留、折叠或提升**：不予采纳，因为它只有一个 app 消费方，并不存在可独立替换的契约。将它折叠进 stdio app 虽然移除了没有正当理由的支撑包边界，却仍保留了重复产品；将来要重新引入这个包，独立的面向行 UI 必须先有真正的第二个消费方。
+- **仅为 pipe 保留面向行 agent**：不予采纳，因为 Headless 已提供有界任务约定、格式纯净的 stdout、持久完成边界和进程退出状态。
+- **将 readline helper 作为包保留、折叠或提升**：不予采纳，因为它只有一个 app 消费方，并不存在可独立替换的约定。将它折叠进 stdio app 虽然移除了没有正当理由的支撑包边界，却仍保留了重复产品；将来要重新引入这个包，独立的面向行 UI 必须先有真正的第二个消费方。
 - **保留 Echo 作为无密钥快速上手路径**：不予采纳，因为首次产品体验应使用真实模型和受支持的 coding agent，而不是带专用工具的脚本化适配器。
 - **只为 CI 演示命令保留 Echo**：不予采纳，因为由测试持有的 Headless fixture 可以覆盖相同的 Loader 和构建产物边界，无需保留 mock 产品叶节点。
 - **移除所有 stdio 或 mock 机制**：不予采纳，因为分帧协议、进程 I/O 和确定性测试适配器是独立基础设施，并不是被移除的 agent。
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
index 2fb2e4cf9b..30b1700c63 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
 2026-07-26-merge-subagent-control-service.md: ae7214f7c8c28f8a4b7d754839acbc938270f125
-2026-07-26-merge-subagent-control-service.zh.md: dc05e03c5d38df0317291aee2ffc1395dab8e362
+2026-07-26-merge-subagent-control-service.zh.md: f1fe90e4d8f289d30a7d1c8623ea95931c029bf3
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
index dc05e03c5d..f1fe90e4d8 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
@@ -8,17 +8,17 @@ Status: implemented
 
 ## 问题
 
-可继续 child 的编排最初位于原始 `ctx.subagents` 提供方 seam 之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排契约。实践中，两个服务属于同一组功能，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
+可继续 child 的编排最初位于原始 `ctx.subagents` 提供方 seam 之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排约定。实践中，两个服务属于同一组能力，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
 
 ## 决策
 
-`SubagentService` 是唯一的公开服务。它公开普通的 `start(name, request)`、由 Task 支撑的 `startContinuable(spec)`，以及按意图命名的 `followup(...)`；提供方的 resume 分发仍封装在其继续执行管理器内部。独立的 `@deepseek-ai/dsh-subagent-control` 包（package）和 `ctx.subagentControl` 键均不存在；可选的 `@deepseek-ai/dsh-tool-subagent-control` 包则直接注入 `ctx.subagents`。
+`SubagentService` 是唯一的公开服务。它公开普通的 `start(name, request)`、由 Task 支撑的 `startContinuable(spec)`，以及按意图命名的 `followup(...)`；提供方的 resume 分发仍封装在其继续执行管理器内部。独立的 `@deepseek-ai/dsh-subagent-control` 包和 `ctx.subagentControl` 键均不存在；可选的 `@deepseek-ai/dsh-tool-subagent-control` 包则直接注入 `ctx.subagents`。
 
-合并后的服务及其提供方公开一套 `SubagentError` 分类体系。稳定错误码把提供方查找失败和功能检查失败，与继续执行路由、鉴权、取消、持久化和送达失败区分开来；已移除的服务不保留单独的错误类。
+合并后的服务及其提供方公开一套 `SubagentError` 分类体系。稳定错误码把提供方查找失败和能力检查失败，与继续执行路由、鉴权、取消、持久化和送达失败区分开来；已移除的服务不保留单独的错误类。
 
 继续执行的实现仍是内部管理器，不会扩展提供方注册表的核心状态。`SubagentService` 通过 `ctx.inject(['tasks', 'agents'], ...)` 创建该管理器，因此注入的 Cordis child fiber 拥有自身的 Task 完成监听器和拆卸 effect。加载提供方注册表不要求 Task 或持久化。只有 Task 和 Agent 可用时，该管理器才会存在；每项继续执行操作都在需要持久性时解析会话持久化服务。dispose（资源释放）该 fiber 会先取消并结算活跃的继续执行，再释放其关联。
 
-`startContinuable` 与底层 `start` 保持分离，因为二者的所有权与时序契约不同：前者分配持久化 child id、创建 Task，并同步返回两个 id，而启动过程继续在 Task 内运行；底层 `start` 则等待提供方发布，并移交一个由持有方负责的 run。若通过标志或返回值联合类型将该方法并入 `start`，会扩大底层契约，改动反而多于保留现有的显式入口。
+`startContinuable` 与底层 `start` 保持分离，因为二者的所有权与时序约定不同：前者分配持久化 child id、创建 Task，并同步返回两个 id，而启动过程继续在 Task 内运行；底层 `start` 则等待提供方发布，并移交一个由持有方负责的 run。若通过标志或返回值联合类型将该方法并入 `start`，会扩大底层约定，改动反而多于保留现有的显式入口。
 
 每个 `@deepseek-ai/dsh-tool-subagent` 实例都会选择 `backgroundMode: 'one-shot' | 'continuable'`，默认值为 `one-shot`。这项配置表示策略；`provider.resume` 只用于检查所配置的可继续模式是否受提供方支持。因此，可恢复的提供方仍可执行一次性后台工作。`send_message` 工具是独立适配器：加载或省略该工具既不会启用也不会禁用 `startContinuable`。
 
@@ -26,11 +26,11 @@ Status: implemented
 
 **保留独立服务。** 这样能保持最严格的依赖分离，但每条生产环境中的可继续路径都要组合两个服务，而额外的公开键会暴露调用方并不需要的架构差异。内部管理器无需第二个服务，也能保留可选的 Task 和持久化依赖。
 
-**根据 `provider.resume` 推断可继续模式。** 方法是否存在可以准确表示从持久化存储恢复的功能，却不能表示部署策略。这会迫使每个可恢复的提供方都采用可继续后台语义，并使配套插件缺失成为运行时错误。显式的工具配置将选择与功能分离。
+**根据 `provider.resume` 推断可继续模式。** 方法是否存在可以准确表示从持久化存储恢复的能力，却不能表示部署策略。这会迫使每个可恢复的提供方都采用可继续后台语义，并使配套插件缺失成为运行时错误。显式的工具配置将选择与能力分离。
 
 **注册继续执行访问入口，或检查后续操作工具。** 注册表可以告诉委派工具继续执行接口是否存在，但启动具备持久性的工作不需要任何后续操作适配器。这样的注册表会把 UI 组合编码进执行策略，并以另一个名称重新建立插件间依赖关系。
 
-**将底层启动与可继续启动合并为一个方法。** `start` 上的标志会使该方法返回已发布的一次性 run，或立即返回 Task 和 child 标识，从而削弱简单的所有权边界。保留 `startContinuable` 改动更小，也能明确保留两项契约。
+**将底层启动与可继续启动合并为一个方法。** `start` 上的标志会使该方法返回已发布的一次性 run，或立即返回 Task 和 child 标识，从而削弱简单的所有权边界。保留 `startContinuable` 改动更小，也能明确保留两项约定。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.i18n.yaml
index f0587a9b39..c251d969e1 100644
--- a/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-intent-named-subagent-continuation-operations.md
 2026-07-27-intent-named-subagent-continuation-operations.md: e74d62b7582e92f8e5ce68327a677259c8453d24
-2026-07-27-intent-named-subagent-continuation-operations.zh.md: dae4dd37fa9950f0b8d1ba6ec5c46b99977a7201
+2026-07-27-intent-named-subagent-continuation-operations.zh.md: ae7b370441d8e0ee045f4d0fcf851d28d055b295
diff --git a/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.zh.md b/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.zh.md
index dae4dd37fa..ae7b370441 100644
--- a/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-`SubagentService` 分离四种执行意图：`start(name, request)` 返回普通的、由持有方负责的 one-shot run；`startContinuable(spec)` 建立持久化 child，并返回其 id 与已接受的初始 `MessageId`；`followup(parent, childId, content, { source, signal })` 发送后续 parent 内容；`reportFrom(child, content, { delivery, signal })` 将选定的 child 内容发送给其直接 parent。`followup` 与 `Agent.followup()` 一致，而 `SubagentRun.steer()` 仍是范围更窄的能力，仅向已确认仍在运行的 run 提供 steering。面向模型的工具保留稳定的 `send_message` 与 `report` 名称，并将路由委托给对应的意图方法。
+`SubagentService` 分离四种执行意图：`start(name, request)` 返回普通的、由持有方负责的 one-shot run；`startContinuable(spec)` 建立持久化 child，并返回其 id 与已接受的初始 `MessageId`；`followup(parent, childId, content, { source, signal })` 发送后续 parent 内容；`reportFrom(child, content, { delivery, signal })` 将选定的 child 内容发送给其直接 parent。`followup` 与 `Agent.followup()` 一致，而 `SubagentRun.steer()` 仍是范围更窄的能力，仅向已确认仍在运行的 run 提供 steering（中途引导）。面向模型的工具保留稳定的 `send_message` 与 `report` 名称，并将路由委托给对应的意图方法。
 
 调用方请求与提供方请求相互分离。`SubagentStartRequest` 包含调用方提供的 one-shot 数据；`ResolvedSubagentStartRequest` 会在调用 `SubagentProvider.start()` 前加入由服务解析的描述符。创建可继续 child 时，管理器将 `ContinuableCreateRequest` 传给可选的 `SubagentProvider.prepareContinuable()`，且只接收分离的创建数据。`SubagentService.resume()` 与提供方恢复分发均不存在：继续执行管理器加载描述符、对 parent 进行鉴权，并负责 Agent 实体化、提示词投递、冷恢复与 teardown。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
index 7b65dc0445..9d3eb4677f 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
 2026-07-28-remove-synthetic-log-only-turns.md: 61c1aa4b1599fe020e0cd96c32daea01d419e95a
-2026-07-28-remove-synthetic-log-only-turns.zh.md: 1661045ca9fb340ebffc9b749263262cb178eae4
+2026-07-28-remove-synthetic-log-only-turns.zh.md: 65281d8342997165b465a744bb08dd2d815e014e
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
index 1661045ca9..65281d8342 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
@@ -16,9 +16,9 @@ Status: implemented
 
 `SessionStore.appendOutOfBand()`、`OutOfBandSessionEventMap` 和 `OutOfBandSessionEventType` 均不再存在。拥有纯日志事件的插件通过 `Session` 追加该事件；当操作承诺持久性时，插件会显式等待 `ctx.sessions.flush(session)`。系统不会仅为获得该检查点而打开轮次。
 
-核心会话不变量继续强制核心所属的执行关系：轮次与步骤编号、steering、助手、工具、待办和请求头事件的封闭，以及同一步骤内的工具调用／结果配对。核心允许可合并扩展事件位于轮次之间，因为只有声明它们的插件知道这些事件受执行作用域约束，还是可以独立存在。插件的不变量配套组件仍负责其自身的事件关系。
+核心会话不变量继续强制核心所属的执行关系：轮次与步骤编号、steering（中途引导）、助手、工具、待办和请求头事件的封闭，以及同一步骤内的工具调用／结果配对。核心允许可合并扩展事件位于轮次之间，因为只有声明它们的插件知道这些事件受执行作用域约束，还是可以独立存在。插件的不变量配套组件仍负责其自身的事件关系。
 
-标题服务会在完成既有的服务状态、修订、取消和实时会话检查后，直接追加 `session/title`。随附模型辅助函数会在发起调用前追加其字面量 `session/title-llm-request` 记录。持久化通过有界 `session/event` 路径接纳两者，并在常规检查点与生命周期 teardown 时排空；二者都不会仅因为位于轮次之间就强制 flush。因此，回退标题、辅助请求记录或已接受的提供方标题可以出现在 `turn/end` 之后、下一个 `turn/start` 之前。手动压缩（compaction）利用同一项轮次间能力记录 `compact/* { turn: null }` 标记对，但会显式 flush 已闭合的尝试，因为 `/compact` 承诺在释放排队提示词接纳预留前完成持久化。
+标题服务会在完成既有的服务状态、修订、取消和活跃会话检查后，直接追加 `session/title`。随附模型辅助函数会在发起调用前追加其字面量 `session/title-llm-request` 记录。持久化通过有界 `session/event` 路径接纳两者，并在常规检查点与生命周期 teardown 时排空；二者都不会仅因为位于轮次之间就强制 flush。因此，回退标题、辅助请求记录或已接受的提供方标题可以出现在 `turn/end` 之后、下一个 `turn/start` 之前。手动压缩（compaction）利用同一项轮次间能力记录 `compact/* { turn: null }` 标记对，但会显式 flush 已闭合的尝试，因为 `/compact` 承诺在放行排队中的提示词前完成持久化。
 
 会话 fork 可以结束于开放轮次之外的任意稳定事件位置，而不限于 `turn/end`。这样，默认 fork 会保留独立标题和其他插件所属的纯日志记录，同时仍拒绝在活跃执行过程中截断前缀。
 
@@ -36,7 +36,7 @@ Status: implemented
 
 ## 验证
 
-核心不变量测试会接受轮次之间的未知插件事件，同时继续拒绝位于该处的内置执行事件。钩子、plan-mode、Code Mode 分发和审批的不变量配套组件会在没有开放轮次时拒绝其执行作用域事件；压缩配套组件则另外接受轮次之间平衡的 `turn: null` 手动标记对，并要求数字 owner 匹配一个开放轮次。会话标题服务测试会在并发刷新、会话脱离拒绝和最新修订接受场景下，固定一个直接追加的回退事件。JSONL 和 SQLite 往返测试会通过持久化生命周期排空保留追加在 `turn/end` 之后的标题；fork 测试会保留独立纯日志尾部，同时拒绝位于开放轮次内的边界。一个无密钥、经完整组装的 ACP（Agent Client Protocol）快照会将模型生成的标题延迟到 `turn/end` 之后，并固定一个不含合成轮次的独立提供方标题。生成的 API 和类型等价性目录不含任何已移除符号。
+核心不变量测试会接受轮次之间的未知插件事件，同时继续拒绝位于该处的内置执行事件。钩子、plan-mode、Code Mode 分发和审批的不变量配套组件会在没有开放轮次时拒绝其执行作用域事件；压缩配套组件则另外接受轮次之间平衡的 `turn: null` 手动标记对，并要求数字 owner 匹配一个开放轮次。会话标题服务测试会在并发刷新、拒绝已脱离会话和接受最新修订的场景下，固定一个直接追加的回退事件。JSONL 和 SQLite 往返测试会通过持久化生命周期排空保留追加在 `turn/end` 之后的标题；fork 测试会保留独立纯日志尾部，同时拒绝位于开放轮次内的边界。一个无密钥、经完整组装的 ACP（Agent Client Protocol）快照会将模型生成的标题延迟到 `turn/end` 之后，并固定一个不含合成轮次的独立提供方标题。生成的 API 和类型等价性目录不含任何已移除符号。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
index 4396748bc7..7c4e1fac3d 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.md
 2026-07-29-shared-base-config-overlays.md: b2ca5cc8d3a160dd09550827d5f8148c14048ea4
-2026-07-29-shared-base-config-overlays.zh.md: e14aa87bdd6ed3bd711bb9786220b5baf0566e8e
+2026-07-29-shared-base-config-overlays.zh.md: adec7c793839e84edb14173d71735d264cf2ec28
diff --git a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
index e14aa87bdd..adec7c7938 100644
--- a/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-29-shared-base-config-overlays.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`dsh` 交付了两棵完整的配置树，其中 43 个配置项完全相同。`apps/cli/cordis.yml` 以 74 个平铺配置项组合 web surface，而 TUI 启动的是 `examples/tui-agent/cordis.yml`——其中单独一行 `@deepseek-ai/dsh-tui-demo` 挂载了十二个插件，并把它们的配置重新声明为自己那份二十个键、仅作透传的 `Config`。
+`dsh` 交付了两棵完整的配置树，其中有 43 个共享配置项。`apps/cli/cordis.yml` 以 74 个平铺配置项组合 web surface，而 TUI 启动的是 `examples/tui-agent/cordis.yml`——其中单独一行 `@deepseek-ai/dsh-tui-demo` 挂载了十二个插件，并把它们的配置重新声明为自己那份二十个键、仅作透传的 `Config`。
 
 这两份文件都名不副实。`examples/tui-agent` 并不是示例：`apps/cli/src/tui.ts` 把它硬编码为产品的默认配置；它还拥有 TUI 的 PTY 冒烟测试、八个终端快照场景，以及被 `cordis-agent` 叶节点 import 的 PTY harness。`dsh-tui-demo` 也不是 demo——它就是应用本身，由交付的二进制从 `packages/examples/` 中挂载。
 
@@ -20,11 +20,11 @@ Status: implemented
 
 优先级即列表顺序，逐配置项后写者胜：base，然后是 surface overlay，接着是 `--config` overlay 或个人 `~/.dsh/config.yaml`，最后是启动器自身的 flag 与 profile patch。
 
-`--config <path>` 现在应用一个 overlay 来**取代**个人 overlay，因此 demo 或测试用的树绝不会继承用户的 provider 与 model。`--config-replace <path>` 则把某个文件作为整棵树启动，同时绕过 base、surface overlay 与个人 overlay；这正是旧 `--config` 的行为，所以像 `examples/web-cordis` 这样的树改用了新 flag。两个 flag 都会在 `/resume` 的 execve 交接中保留，否则 resume 会静默更换 agent。
+`--config <path>` 现在应用一个 overlay 来**取代**个人 overlay，因此 demo 或测试用的树绝不会继承用户的提供方与 model。`--config-replace <path>` 则把某个文件作为整棵树启动，同时绕过 base、surface overlay 与个人 overlay；这正是旧 `--config` 的行为，所以像 `examples/web-cordis` 这样的树改用了新 flag。两个 flag 都会在 `/resume` 的 execve 交接中保留，否则恢复时会静默更换 agent（智能体）。
 
 patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆分方式：取值因 surface 而异的配置项住在 overlay 中，绝不住在 base 里，从而没有任何配置项会被三层同时 patch。因此会话身份根本不能经由配置键传递——它迁移到了 `dsh-agent-loop` 的 `CONFIGURED_AGENT_IDENTITIES_KEY`，正如启动器持有身份的记录所述。
 
-`examples/tui-agent`、`examples/cordis-agent`、`examples/code-mode` 与 `packages/examples/tui-demo` 均被删除。TUI 测试迁往 `apps/cli/tests/`，cordis 工具集的 e2e 迁入 `packages/self-modification/tool-cordis/tests/`，受支持的 Code Mode demo 则保留为 `examples/acp-agent/code-mode.cordis.yml` 中的 ACP overlay。
+`examples/tui-agent`、`examples/cordis-agent`、`examples/code-mode` 与 `packages/examples/tui-demo` 均被删除。TUI 测试迁往 `apps/cli/tests/`，cordis 工具集的 e2e 迁入 `packages/self-modification/tool-cordis/tests/`，受支持的 Code Mode demo 则保留为 `examples/acp-agent/code-mode.cordis.yml` 中的 ACP（Agent Client Protocol）overlay。
 
 ## 备选方案
 
@@ -38,16 +38,16 @@ patch 会整体替换目标配置项的 `config` 而不合并，这决定了拆
 
 ## 影响
 
-指名 `@deepseek-ai/dsh-tui-demo`、或 patch `tui-agent` 配置项的 overlay 与 `--config` 树将不再可解析。overlay 现在要 patch 拥有对应键的那一行：模型路由在 `agent-loop`，人设在 `system-prompt`，呈现设置在 `tui`。
+指名 `@deepseek-ai/dsh-tui-demo` 或 patch `tui-agent` 配置项的 overlay 或 `--config` 树将不再可解析。overlay 现在要 patch 拥有对应键的那一行：模型路由在 `agent-loop`，人设在 `system-prompt`，呈现设置在 `tui`。
 
 若某个 patch 的 `id` 不匹配任何配置项，Loader 仍只告警而不报错。这是有意为之：同一份个人 overlay 会跨 surface 共用，而 `insert` 配置项按设计本就不匹配任何目标，因此仅在 `web` 下存在的配置项不能让 TUI 启动失败。
 
-`dsh web` 新增 `--config`，作为一份额外 overlay 传入 `AppCLIEntry`。Web 保留沙箱化 Bash 与文件系统提供方，以及审批、权限预设、目录选择和浏览器权限界面；覆盖层会禁用共享的本地提供方，因为补丁可以禁用条目但不能删除条目。TUI 查询索引使用进程唯一的临时数据库，因为 SQLite 后端要求单写入者所有权。该索引是每个进程重新构建的可丢弃派生数据；`/resume` 直接列出底层语料，不依赖索引复用。`AppCLIEntry` 在为自身 patch 合并恢复配置项默认值时会同时读取 base 与其 surface overlay，因为 flag 覆盖必须保留同一配置项上 overlay 的其他字段。
+`dsh web` 新增 `--config`，作为一份额外 overlay 传入 `AppCLIEntry`。Web 保留沙箱化 Bash 与文件系统提供方，以及审批、权限预设、目录选择和浏览器权限界面；覆盖层会禁用共享的本地提供方，因为补丁可以禁用条目但不能删除条目。TUI 查询索引使用每个进程独有的临时数据库，因为 SQLite 后端要求单写入者所有权。该索引是每个进程重新构建的可丢弃派生数据；`/resume` 直接列出底层语料，不依赖索引复用。`AppCLIEntry` 在为自身 patch 合并恢复配置项默认值时会同时读取 base 与其 surface overlay，因为 flag 覆盖必须保留同一配置项上 overlay 的其他字段。
 
 ## 验证
 
-组合的正确性通过用真实 Loader 启动每棵树并检查已就绪的条目来核对，而不是靠阅读 YAML：两个界面都能稳定完成且没有未加载项；Web 会以沙箱化 Bash 与文件系统提供方启动 `httpServer`。Code Mode 继续由 ACP overlay 与程序化 TUI 快照覆盖，而不再维护独立交付的 TUI 应用。
+组合的正确性通过用真实 Loader 启动每棵树并检查已就绪的条目来核对，而不是靠阅读 YAML：两个界面都能完全就绪，且没有未加载项；Web 会以沙箱化 Bash 与文件系统提供方启动 `httpServer`。Code Mode 继续由 ACP overlay 与程序化 TUI 快照覆盖，而不再维护独立交付的 TUI 应用。
 
 全部八个终端快照场景在迁移后逐字节重放一致，14 个用例的 PTY 冒烟测试全部通过，其中两个用例断言个人 overlay 能触达一个 **insert 进来的**配置项——这正是 vendored `plugin-include` 修复所启用的行为（[`vendor/README.md`](../../../../vendor/README.md) 本地修改第 8 条，由 `packages/boot/app-boot/tests/config-reload.spec.ts` 覆盖）。
 
-平铺过程暴露出三处潜伏缺陷，均在此一并修复：TUI 曾在构造时一次性捕获可选的 `sessionQuery` 服务，因此在挂载竞争中胜出时会永久禁用 `/resume`；交付的会话存储根目录曾静默退回项目本地的 `./.sessions`；`--config-replace` 曾在 resume 交接中被丢弃。
+平铺过程暴露出三处潜伏缺陷，均在此一并修复：TUI 曾在构造时一次性捕获可选的 `sessionQuery` 服务，因此在挂载竞争中胜出时会永久禁用 `/resume`；交付的会话存储根目录曾静默退回项目本地的 `./.sessions`；`--config-replace` 曾在恢复交接中被丢弃。
diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
index 3245b307e5..8547475c03 100644
--- a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-30-private-agent-send.md
 2026-07-30-private-agent-send.md: 43353c309f98eab1bff91b8fbe0c9cfaa2bbc69b
-2026-07-30-private-agent-send.zh.md: 49f7c999ec60c7305bdca570a4d59039c7c1923b
+2026-07-30-private-agent-send.zh.md: a475c39fc378bca609f747795e185d25accf4489
diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
index 49f7c999ec..a475c39fc3 100644
--- a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-公开的 `Agent.send()` 方法暴露了实体循环的路由矩阵，但生产调用方只使用语义明确的 `followup()`、`steer()` 和 `inject()` 操作。第四种组合，即 `next-turn` 配合 `wakeup: false`，除测试外没有消费方。将这项潜在能力保留为公开接口，还会迫使其他 `Agent` 实现和测试替身接受实现层的路由策略。
+公开的 `Agent.send()` 方法暴露了具体循环实现的路由矩阵，但生产调用方只使用语义明确的 `followup()`、`steer()` 和 `inject()` 操作。第四种组合，即 `next-turn` 配合 `wakeup: false`，除测试外没有消费方。将这项潜在能力保留为公开接口，还会迫使其他 `Agent` 实现和测试替身接受实现层的路由策略。
 
 ## 决策
 
-`Agent` 将 `followup()`、`steer()` 和 `inject()` 作为完整的交付契约公开。`ReactLoopAgent` 保留私有的 `send()` 辅助方法，供这三个方法共用路由机制；`dsh-agent` 不再导出 `SendTarget` 和 `SendOptions`。
+`Agent` 将 `followup()`、`steer()` 和 `inject()` 作为完整的交付约定公开。`ReactLoopAgent` 保留私有的 `send()` 辅助方法，供这三个方法共用路由机制；`dsh-agent` 不再导出 `SendTarget` 和 `SendOptions`。
 
 公开接口无法在不唤醒驱动器的情况下让一个轮次入队。`followup()` 始终请求执行，`steer()` 请求最近的步骤，`inject()` 则提供面向模型的上下文而不请求执行。本决策部分取代[统一交付决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)中关于公开接口的内容，同时保留其内部路由与统一的 `user/message` 表示。
 
@@ -22,6 +22,6 @@ Status: implemented
 
 ## 后果
 
-插件从三种语义操作中选择，不再自行构造路由选项。其他驱动器和结构型测试替身只需实现更小的契约，Cordis API 目录也不再列出 `send`、`SendTarget` 或 `SendOptions`。
+插件从三种语义操作中选择，不再自行构造路由选项。其他驱动器和结构型测试替身只需实现更小的约定，Cordis API 目录也不再列出 `send`、`SendTarget` 或 `SendOptions`。
 
 只有出现明确的消费方并定义显式的生命周期语义后，才能恢复已移除的无唤醒排队能力。`cancel({ keepInbox: true })` 仍会保留已通过受支持交付路径进入待处理状态的工作。
diff --git a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
index f690cc7a95..86f1fc7bb4 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.md
 2026-07-31-capability-neutral-sandbox-policy-context.md: d45c6c652fb7a061c2f92b7e03c41cce39da2a30
-2026-07-31-capability-neutral-sandbox-policy-context.zh.md: 9a1bb7a13d934826dddf89b409b25ba892a31ea3
+2026-07-31-capability-neutral-sandbox-policy-context.zh.md: fb030e8cd77ceb9935dd9d8f9bd9de2ce2c0fdbc
diff --git a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
index 9a1bb7a13d..fb030e8cd7 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 当前策略上下文最初通过受强制执行家族与可升权家族两个独立注册表来映射运行时组合。后端、工具与示例中的六个调用点会贡献 `filesystem`、`bash` 或 `terminal`；策略服务保留 token 集合，以便独立释放各项注册，对两个注册表的内容求交集并排序，在每次生命周期变化时使提示词组装失效，并且需要测试覆盖所有家族组合。
 
-这份清单既不是说明文件策略所必需的，也不能作为模型可见能力的权威依据。后端贡献可能声明某个家族，而该家族面向模型的工具并不存在，或被请求作用域隐藏；工具 schema 已经向模型准确说明哪些操作可用。因此，为了维护一句近似的英文说明，注册表扩大了公开服务与生命周期契约。
+这份清单既不是说明文件策略所必需的，也不能作为模型可见能力的权威依据。后端贡献可能声明某个家族，而该家族面向模型的工具并不存在，或被请求作用域隐藏；工具 schema 已经向模型准确说明哪些操作可用。因此，为了维护一句近似的英文说明，注册表扩大了公开服务与生命周期约定。
 
 ## 决策
 
@@ -18,7 +18,7 @@ Status: implemented
 
 哪些操作可用仍以工具 schema 为准。针对具体操作的拒绝以及获批后的更宽松模式重试，仍以工具结果为准。文件系统、一次性 bash 与终端实现继续解析并强制执行相同的逐调用策略；移除的只有面向模型的冗余能力清单。
 
-本决策取代了[当前沙箱策略上下文决策](../feature/2026-07-30-current-sandbox-policy-context.md)中关于家族注册与按组合条件化措辞的部分内容。缓存安全的上下文交付、持久快照具体化、措辞证据，以及引导与强制执行之间的边界，仍以该 Agent Note 为归属文档。
+本决策取代了[当前沙箱策略上下文决策](../feature/2026-07-30-current-sandbox-policy-context.md)中关于家族注册与按组合条件化措辞的部分内容。缓存安全的上下文交付、持久快照物化、措辞证据，以及引导与强制执行之间的边界，仍以该 Agent Note 为归属文档。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.i18n.yaml
index 8cfbcd08c3..e23f925416 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.md
 2026-07-31-drop-user-message-edit-stub.md: 5a34be1dd285f4aced9e6cfb2e324b20ec734bed
-2026-07-31-drop-user-message-edit-stub.zh.md: 768cb4618b4a85f61e6348f8c6fb6a93d686e7d3
+2026-07-31-drop-user-message-edit-stub.zh.md: 288f2bda5d41cf0a331f69f134c8cf1e61a801ef
diff --git a/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.zh.md b/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.zh.md
index 768cb4618b..288f2bda5d 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-drop-user-message-edit-stub.zh.md
@@ -10,7 +10,7 @@ user 气泡的 IconActions 行在复制和分支旁边还有一个编辑按钮
 
 ## 决策
 
-`MessageIconActions` 只渲染时钟／复制／分支，其 `edit` prop 随按钮一并删除；`MessageItem` 不再传入该 prop。现在 user 气泡与 assistant chrome 只在时钟位置上不同。包 README 在 Known Limitations 中记录这项缺失的能力，web 的 message-actions 金样固定了不含该控件的动作行。
+`MessageIconActions` 只渲染时钟／复制／分支，其 `edit` prop 随按钮一并删除；`MessageItem` 不再传入该 prop。现在 user 气泡与 assistant chrome 只在时钟位置上不同。包 README 在 Known Limitations 中记录这项缺失的能力，web 的 message-actions 预期输出固定了不含该控件的动作行。
 
 公共 locale 保留通用的 `edit` 词条：它是共享词汇，而非本组件的文案。
 
@@ -20,8 +20,8 @@ user 气泡的 IconActions 行在复制和分支旁边还有一个编辑按钮
 
 **把按钮置灰并加提示。** 一个可见但无效的控件仍在宣告可以编辑，解释成本相同；直接移除才是诚实的状态。
 
-**接到队列编辑器上。** 队列编辑的是尚未发送的消息。已定稿的 user 消息已经进入转录和模型上下文，复用该编辑器会让同一个动作悄悄变成另一件事。
+**接到队列编辑器上。** 队列编辑的是尚未发送的消息。已定稿的 user 消息已经进入 transcript（文本记录）和模型上下文，复用该编辑器会让同一个动作悄悄变成另一件事。
 
 ## 后果
 
-Web 没有任何途径修正已发送的消息；从该消息分支是最接近的现有手势。由于动作行的内容完全由 props 组合而来，能力就绪后重新引入只是一次纯 UI 改动。
+Web 没有任何途径修正已发送的消息；从该消息分支是最接近的现有手势。由于动作行的内容完全由 props 组合而来，client 变更就绪后重新引入只是一次纯 UI 改动。
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
index 1c0cc5644d..7f9f5d6665 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
 2026-07-31-one-route-to-add-a-workspace.md: 5d002265b5eb1178bb1dbc7bd17f8b364d9b9856
-2026-07-31-one-route-to-add-a-workspace.zh.md: 0a59d3a505eb921b4ec980abaefedfcad8a3c294
+2026-07-31-one-route-to-add-a-workspace.zh.md: 6f2d41ca51c544e484c711e8488456b04d206528
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
index 0a59d3a505..6f2d41ca51 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
@@ -1,18 +1,18 @@
-# Agent Note: One route to add a Workspace
+# Agent Note: 一条添加 Workspace 的路径
 
 Status: implemented
 
 [English](2026-07-31-one-route-to-add-a-workspace.md) | 中文
 
-## Problem
+## 问题
 
-两处 Workspace 表层——侧边栏区头的 `+` 与会话主视觉区的 chip——都提供了两条获得 Workspace 的路径：**打开本地文件夹…** 拉起组合的目录流程，**新建工作区** 接收一个名称并创建 `<workspaceRoot>/<name>`。两者重叠：浏览占用者自带 **新建文件夹** 能力，因此"选一个目录"本就覆盖了"建一个目录"。两个入口意味着同一结果有两套词汇、一个自带重名规则的名称对话框，以及一个操作者既看不到也选不了的创建位置。
+两处 Workspace 表层——侧边栏区头的 `+` 与会话主视觉区的 chip——都提供了两条获得 Workspace 的路径：**打开本地文件夹…** 拉起组合的目录流程，**新建工作区** 接收一个名称并创建 `<workspaceRoot>/<name>`。两者重叠：浏览占用者自带 **新建文件夹** 能力，因此「选一个目录」本就覆盖了「建一个目录」。两个入口意味着同一结果有两套词汇、一个自带重名规则的名称对话框，以及一个操作者既看不到也选不了的创建位置。
 
 删掉较弱的那个入口后，侧边栏区头只剩一个动作，于是引出了本 Note 一并裁定的展示问题：只有一行的浮层应该长什么样。
 
-## Decision
+## 决策
 
-添加 Workspace 只有一条路径：通过组合的目录流程选一个宿主机目录，新建的或已存在的都可以。入口是 `menu.addWorkspace`（"添加工作区…" / "Add workspace…"）；按名称创建的对话框及其 `create.*`／`menu.createWorkspace`／`workspace.new` 文案全部删除。标签命名的是结果而非机制，因为它现在是通往该结果的唯一一扇门——找"新建"的用户必须能找到它。
+添加 Workspace 只有一条路径：通过组合的目录流程选一个宿主机目录，新建的或已存在的都可以。入口是 `menu.addWorkspace`（「添加工作区…」/「Add workspace…」）；按名称创建的对话框及其 `create.*`／`menu.createWorkspace`／`workspace.new` 文案全部删除。标签命名的是结果而非机制，因为它现在是通往该结果的唯一一扇门——找「新建」的用户必须能找到它。
 
 **菜单的存在是为了在多个目标之间消歧。** 当只剩添加这一个入口时——仅添加的侧边栏表层，或列表为空的主视觉区——锚点手势*就是*该动作：直接拉起流程，不渲染浮层。只有一行的浮层多花一次点击，却没有任何可选项。这条规则是一个谓词（`addIsTheOnlyEntry`）覆盖两处表层，而不是逐表层特判。
 
@@ -21,37 +21,37 @@ Status: implemented
 - **列表为空只有在基线落地后才算最终结果。** `phase` 仍为 `pending` 时，主视觉区保留菜单与加载状态，而不是跳进一个即将到达的 workspace 会使其变得多余的流程。仅添加表层不列任何东西，因此从不等待。
 - **目录流程的洞没有占用者时，就没有任何可添加的手段。** 此时侧边栏区头干脆不渲染按钮，而不是留下一个点了没反应的按钮；主视觉区的菜单则继续作为选择器工作，列出已有内容——而当同样没有内容可列时，它什么也不弹：空浮层会宣称一个并不存在的选择。这是 seam 文档化的无流程默认行为走到它的结论：占用者不在，唯一的创建能力也就不在。主视觉区的锚点 chip 归 ui-conversation 所有，因此本包能压掉浮层，却无法隐藏该 chip。
 
-直接拉起的这条路径同样遵守菜单项声明的 busy 规则：某次选取仍在接纳中（`flowBusy`）时，锚点手势会被按住，正如该菜单项会被禁用，从而使迟到的结果无法抢开第二个流程。
+直接拉起的这条路径同样遵守菜单项声明的 busy 规则：某次选取仍在接纳中（`flowBusy`）时，锚点手势会被拦住，正如该菜单项会被禁用，从而使迟到的结果无法抢开第二个流程。
 
 `WorkspaceCreateFlow` 现更名为 `WorkspacePickFlow`，其 `createOnly` prop 更名为 `addOnly`；注入的 `createWorkspace` 从 `{ name } | { path }` 收窄为 `{ path }`。
 
-## Wire and CLI residue
+## Wire 与 CLI（命令行界面）残留
 
-Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端一段同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一契约。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端 seam 与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
+Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端 seam 同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中「workspaceRoot 下的 name」这一约定。`apps/cli/README.md` 及其中文对侧文件也仍把 `--workspace-root` 记为「创建具名 Workspace」。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨后端、客户端 seam 与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、运行时 workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
 
-## Testing
+## 测试
 
-`connectFreshWorkspace`——所有 web e2e 场景启动时都会走的辅助函数——会预先备好 `<root>/workspace`，再经对话框的路径编辑器接纳它，因此产出的会话 cwd 与按名称创建时完全一致，场景 golden 保持有效。选择预先备好而不是在对话框内新建，是为了让该辅助函数在一个场景可能发生的多次连接之间保持幂等（第二次创建同名文件夹会失败，而创建对话框会在失败时把流程停在原地）。在选择器内新建文件夹——同一条路径的另一半——由 `workspace-management.e2e.ts` 覆盖，它承担针对性覆盖：在对话框自己创建的文件夹上添加两个 workspace、接纳 basename 相同的不同目录并保持彼此独立、在另一个目录上复用已删除的标题、以及浏览对话框的 aria golden。
+`connectFreshWorkspace`——所有 web e2e 场景启动时都会走的辅助函数——会预先备好 `<root>/workspace`，再经对话框的路径编辑器接纳它，因此产出的会话 cwd 与按名称创建时完全一致，场景预期输出保持有效。选择预先备好而不是在对话框内新建，是为了让该辅助函数在一个场景可能发生的多次连接之间保持幂等（第二次创建同名文件夹会失败，而创建对话框会在失败时把流程停在原地）。在选择器内新建文件夹——同一条路径的另一半——由 `workspace-management.e2e.ts` 覆盖，它承担针对性覆盖：在对话框自己创建的文件夹上添加两个 workspace、接纳 basename 相同的不同目录并保持彼此独立、在另一个目录上复用已删除的标题、以及浏览对话框的 aria 预期输出。
 
 `smoke-real.e2e.ts` 是唯一启动未打补丁的出厂配置树的场景，其中 `-auto` 行会按宿主机解析；它现在通过 `--config` overlay 钉死 `-browse`，使开发机的显示环境无法决定选择器是否可被驱动。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-**保留 `打开本地文件夹…` 作为标签。** 否决：合并后该入口既能打开也能创建，用机制命名会恰好对那些入口被我们删掉的用户隐藏创建这一半。反方理由——"本地"二字有效区分了浏览器所在机器与 harness 所在机器——在下一步就由对话框自身的标题和面包屑回答了。
+**保留 `打开本地文件夹…` 作为标签。** 否决：合并后该入口既能打开也能创建，用机制命名会恰好对那些入口被我们删掉的用户隐藏创建这一半。反方理由——「本地」二字有效区分了浏览器所在机器与 harness 所在机器——在下一步就由对话框自身的标题和面包屑回答了。
 
 **保留双入口菜单，让 `新建工作区` 也打开同一个流程。** 否决：同一动作两个标签正是我们被要求消除的混淆，而不是它的缩小版。
 
 **为了与主视觉区菜单保持一致而保留只有一行的浮层。** 否决：不提供选择的浮层是一次浪费的点击，读起来像半成品。这里要一致的是*规则*（有菜单 ⇔ 存在选择），不是控件。
 
-**为将来可能新增的入口（克隆仓库、远程目录）保留菜单壳。** 否决，依据"require a current owner and need"：这样的入口目前并不存在，而等它到来时再恢复菜单，比现在就发一个空壳的改动更小。
+**为将来可能新增的入口（克隆仓库、远程目录）保留菜单壳。** 否决，依据「require a current owner and need」：这样的入口目前并不存在，而等它到来时再恢复菜单，比现在就发一个空壳的改动更小。
 
-**在同一改动中删除 wire 的按名称创建分支。** 本 PR 否决：那是 backend/CLI 面，reviewer 不同、测试波及面更广，而紧急的决定是 UI。见 residue 一节——它是被标记了，不是被遗忘了。
+**在同一改动中删除 wire 的按名称创建分支。** 本 PR（Pull Request）不采纳：那是后端/CLI 面，reviewer 不同、测试波及面更广，而紧急的决定是 UI。见 residue 一节——它是被标记了，不是被遗忘了。
 
-**在 e2e scaffold 中经 host 注册 workspace，而不驱动对话框。** 否决：那会让全部 15 个场景与选择器解耦，整条 lane 将无法证明幸存的这条路径能走到可用的 composer。现在每个场景都会走真实对话框来接纳自己的目录；只有"新建文件夹"那一半集中在一个场景里，因为处处重复只会让共享辅助函数失去幂等性，却换不来额外信号。
+**在 e2e scaffold 中经 host 注册 workspace，而不驱动对话框。** 否决：那会让全部 15 个场景与选择器解耦，整条 lane 将无法证明幸存的这条路径能走到可用的 composer。现在每个场景都会走真实对话框来接纳自己的目录；只有「新建文件夹」那一半集中在一个场景里，因为处处重复只会让共享辅助函数失去幂等性，却换不来额外信号。
 
-## Consequences
+## 后果
 
 - 从 UI 已无法在操作者选定目录之外创建 Workspace；服务端控制的 `--workspace-root` 目标曾是约束新 workspace 文件夹落点的唯一手段，现在没有替代品。需要该约束的部署必须有意识地重新引入它。
-- 仅存的这条路径会浏览宿主机文件系统，因此选择器的可达范围现在是整台宿主机，而非一个配置好的父目录。这本就是浏览占用者的契约，本改动使它成为唯一的契约。
+- 仅存的这条路径会浏览宿主机文件系统，因此选择器的可达范围现在是整台宿主机，而非一个配置好的父目录。这本就是浏览占用者的约定，本改动使它成为唯一的约定。
 - 挂载了 `ui-workspace` 但未挂任何 directory-picker 包的组合，已完全无法添加 Workspace；现在它通过不渲染按钮来说明这一点，而不是提供一个按名称创建的兜底。
-- 主视觉区的 chip 仍声明 `aria-haspopup="menu"`，而直接拉起的路径实际弹出的是对话框。要让它如实，需要把流程的展示方式经 `conversation.hero.workspace` 的 owner 契约上报——决定权在流程，播报权在 chip，两者分属不同的包——因此这被列为一项具名的后续工作，而不是一处无声的不一致。本次新增的侧边栏按钮完全不作任何 popup 声明。
+- 主视觉区的 chip 仍声明 `aria-haspopup="menu"`，而直接拉起的路径实际弹出的是对话框。要让该声明与实际相符，需要把流程的展示方式经 `conversation.hero.workspace` 的 owner 约定上报——决定权在流程，播报权在 chip，两者分属不同的包——因此这被列为一项具名的后续工作，而不是一处无声的不一致。本次新增的侧边栏按钮完全不作任何 popup 声明。
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
index 91b9e6a0c0..11967309d5 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
 2026-08-03-omit-invariants-from-shipped-config.md: ff9a3b0ab2b4797ca4e96bea9e6b961b2e38501f
-2026-08-03-omit-invariants-from-shipped-config.zh.md: 526ce0756e69b36b6f54b46b23e1814322d6a1fd
+2026-08-03-omit-invariants-from-shipped-config.zh.md: 26835d0ad8cd380c13aea21f3090d284330820d6
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
index 526ce0756e..26835d0ad8 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`@deepseek-ai/dsh-invariants` 与各包（package）拥有的 `./invariant` 伴随插件是可选的开发诊断。交付的 TUI 挂载了该服务和四个有状态伴随插件，而交付的 Web 配置树省略了这些条目，导致两个产品 surface 的诊断成本和失败行为不同。即使始终启用的产品边界仍负责会话验证与不可变历史，关系断言失败也可能终止普通的 TUI 运行。
+`@deepseek-ai/dsh-invariants` 与各包拥有的 `./invariant` 伴随插件是可选的开发诊断。交付的 TUI 挂载了该服务和四个有状态伴随插件，而交付的 Web 配置树省略了这些条目，导致两个产品 surface 的诊断成本和失败行为不同。即使始终启用的产品边界仍负责会话验证与不可变历史，关系断言失败也可能终止普通的 TUI 运行。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.i18n.yaml
index 344dd2bf6c..e17f8c3824 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.md
 2026-08-04-drop-windows-powershell-picker-fallback.md: 619afd31d9ec78cdb8565e29fa942b7db8749365
-2026-08-04-drop-windows-powershell-picker-fallback.zh.md: e14904db46a955d4cf40da195a39bf62cbef96ff
+2026-08-04-drop-windows-powershell-picker-fallback.zh.md: 14716f405e98385b7277ce0814adf32190be36b7
diff --git a/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.zh.md b/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.zh.md
index e14904db46..14716f405e 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.zh.md
@@ -1,38 +1,38 @@
-# Agent Note：删除 Windows PowerShell 选择器回退
+# Agent Note: 删除 Windows PowerShell 选择器回退
 
 Status: implemented
 
 [English](2026-08-04-drop-windows-powershell-picker-fallback.md) | 中文
 
-## Problem
+## 问题
 
-原生目录选择器的 win32 分支在 koffi `IFileOpenDialog` 子进程之下保留了一条两级 PowerShell 回退：先 `pwsh.exe`，再 `powershell.exe`（Windows PowerShell 5.1），两者运行同一个带 `SetProcessDPIAware` 开关的 WinForms 脚本。该链的存在是为了在 koffi 层"不可用"时仍能给出一个可用的选择器，但它可能保护的每一个触发条件都是我们自己打包或部署的失败，而不是操作系统的：
+原生目录选择器的 win32 分支在 koffi `IFileOpenDialog` 子进程之下保留了一条两级 PowerShell 回退：先 `pwsh.exe`，再 `powershell.exe`（Windows PowerShell 5.1），两者运行同一个主动启用 `SetProcessDPIAware` 的 WinForms 脚本。该链的存在是为了在 koffi 层「不可用」时仍能给出一个可用的选择器，但它可能保护的每一个触发条件都是我们自己打包或部署的失败，而不是操作系统的：
 
-- koffi 的原生二进制作为普通 optional 依赖（`@koromix/koffi-win32-x64`，无 install script）分发；能装上该包的宿主就一定有二进制，装不上的宿主会在安装期大声失败——回退代码同样不会加载。
-- "上古 Windows"不可能出现：本仓库支持的 Node 版本运行在远比 Vista 时代 `IFileOpenDialog` ABI 新的 Windows 世代上。
+- koffi 的原生二进制作为普通的可选 NPM 依赖（`@koromix/koffi-win32-x64`，无 install script）分发；能装上该包的宿主就一定有二进制，装不上的宿主会在安装期明确报错——回退代码也根本不会得到加载。
+- 「上古 Windows」不可能出现：本仓库支持的 Node 版本运行在远比 Vista 时代 `IFileOpenDialog` ABI 新的 Windows 世代上。
 - koffi/COM 缺陷只崩对话框子进程（crash isolation）；对我们自己 bug 的正确反应是上报失败，而不是静默降级到旧版对话框。
 
-这条链还付出了真实的复杂度：两个 spawn 层运行同一脚本、把回退触发从 `ENOENT` 拓宽为 pwsh 的任何失败以关闭 PowerShell 6（无 WinForms）回归、携带全部三个原因的三连败 `AggregateError`，以及每层的 abort 重检。seam 早已拥有唯一重要的回退——组合层面的 `browse` 后端，由 `directory-picker-auto` 在启动时选择一次。
+这条链还付出了真实的复杂度：两个 spawn 层运行同一脚本、把回退触发从 `ENOENT` 拓宽为 pwsh 的任何失败以修复 PowerShell 6（无 WinForms）回归问题、携带全部三个原因的三连败 `AggregateError`，以及每层的 abort 重检。seam 早已拥有唯一重要的回退——组合层面的 `browse` 后端，由 `directory-picker-auto` 在启动时选择一次。
 
-## Decision
+## 决策
 
 win32 层恰好就是 koffi `IFileOpenDialog` 子进程；任何失败原样上报，无回退。PowerShell 链——`pwsh` → Windows PowerShell 5.1 级联、DPI 修正的 WinForms 脚本、`AggregateError` 聚合——被删除，`pickNativeDirectory` 的 win32 分支成为单次调用。`dsh-native-command` 仍为 POSIX 层保留依赖。
 
-本包其余部分早已遵循的回退判据现在统一适用：回退层只存在于操作系统/桌面环境提供且可能缺失的工具（Linux 的 `zenity` → `kdialog`，启动探针同样采样它们）；我们自己打包的工具（`koffi`）失败即大声报错。macOS `osascript` 与之前一样保持无回退。
+本包其余部分早已遵循的回退判据现在统一适用：回退层只存在于操作系统/桌面环境提供且可能缺失的工具（Linux 的 `zenity` → `kdialog`，启动探针同样采样它们）；我们自己打包的工具（`koffi`）失败即明确报错。macOS `osascript` 与之前一样保持无回退。
 
-本次变更合并并删除了 pwsh 优先的 DPI 选择器修复 Note：其决策在此被完全反转，其保留的 rationale 对只含 koffi 的层不再指导未来工作。其中真实的部分：PowerShell 7 呈现基于 `IFileDialog` 的现代文件夹选择器，而 5.1 的 `FolderBrowserDialog` 被硬连到旧版 `SHBrowseForFolder` 树；脚本的 `SetProcessDPIAware` 修正了 spawn 的系统 DPI 上限；pwsh→5.1 的跳转存在是因为可解析的 PowerShell 6 没有 WinForms（退出码 1，而非 `ENOENT`）。其被拒绝的替代方案（要求 PowerShell 7、导入 `resolvePwshPath`、在 harness 进程设置 DPI 感知）随链删除而失去意义。
+本次变更合并并删除了 pwsh 优先的 DPI 选择器修复 Agent Note：其决策在此被完全反转，其保留的理由对只含 koffi 的层不再指导未来工作。其中真实的部分：PowerShell 7 呈现基于 `IFileDialog` 的现代文件夹选择器，而 5.1 的 `FolderBrowserDialog` 被硬连到旧版 `SHBrowseForFolder` 树；脚本的 `SetProcessDPIAware` 修正了 spawn 的系统 DPI 上限；pwsh→5.1 的跳转存在是因为可解析的 PowerShell 6 没有 WinForms（退出码 1，而非 `ENOENT`）。其被拒绝的替代方案（要求 PowerShell 7、导入 `resolvePwshPath`、在 harness 进程设置 DPI 感知）随链删除而失去意义。
 
-## Alternatives considered
+## 考虑过的替代方案
 
-**保留链但去掉 pwsh 质量层（`koffi` → Windows PowerShell 5.1）。** 拒绝：剩下的层仍在为我们自己打包的依赖辩护，仍要付出脚本、拓宽的触发与聚合的代价，仍会把我们自己的 vtable/COM 缺陷藏到旧版对话框后面。"仅对外部提供的工具回退"的判据不接受任何 Windows 层。
+**保留链但去掉 pwsh 质量层（`koffi` → Windows PowerShell 5.1）。**拒绝：剩下的层仍在防范我们自己打包的依赖发生故障，仍要付出脚本、拓宽的触发与聚合的代价，仍会把我们自己的 vtable/COM 缺陷藏到旧版对话框后面。「仅对外部提供的工具回退」的判据不接受任何 Windows 层。
 
-**原样保留链。** 拒绝：它是选择器面上唯一的二级运行时回退，其触发条件是本就大声失败的部署侧失败，并且它把失败的 pick 降级成一个最具可操作性的条目是 PowerShell 宿主的 `AggregateError`。
+**原样保留链。**拒绝：它是选择器中唯一的二级运行时回退，其触发条件是本就会明确报错的部署侧失败，并且它把一次失败的选择操作降级为 `AggregateError`，其中最具可操作性的条目却指向 PowerShell 宿主。
 
-**原生 pick 失败时在运行时回退到 `browse`。** 拒绝：seam 的流程洞是 `single` kind，`-auto` 组合已在启动时选择一个后端；运行时跨 kind 跳转会双挂两个后端并模糊能力边界。
+**原生 pick 失败时在运行时回退到 `browse`。**拒绝：seam 的流程洞属于 `single` 类型，`-auto` 组合已在启动时选择一个后端；运行时跨类型跳转会同时挂载两个后端并模糊能力边界。
 
-## Consequences
+## 后果
 
 - win32 选择器的失败面是来自单一层的一个错误；调用方看到真实原因（koffi 加载失败、COM 拒绝、对话框崩溃），而不是链式聚合的错误。
 - 本包不再调用 `pwsh`/`powershell.exe`；WinForms 脚本、其 `SetProcessDPIAware` 修正与 `-STA` 标志随之消失。
-- 测试相应缩减：pwsh/5.1 级联与三连败用例被一个"失败原样上报、无回退"用例取代；默认适配器测试改驱动 Linux 层。
+- 测试相应缩减：pwsh/5.1 级联与三连败用例被一个「失败原样上报、无回退」用例取代；默认适配器测试改驱动 Linux 层。
 - 重新引入条件：未来出现在我们打包链之外的 win32 机制（我们不随包分发的系统提供的对话框宿主）才值得在同一判据下保留一层回退。
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
index e71be9bcf0..b688f011de 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
 2026-08-04-remove-tui-package.md: 1057243c70f6f2775a5d0c5f5eddcb72cbad699e
-2026-08-04-remove-tui-package.zh.md: 0e03d6913aafaa3ce01c0f5732935d2c304c8e0e
+2026-08-04-remove-tui-package.zh.md: 17a75921f3e8f227772133243bc0ea5b8ba927a7
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
index 0e03d6913a..17a75921f3 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 移除 TUI 包（package）
+# Agent Note: 移除 TUI 包
 
 Status: implemented
 
@@ -12,17 +12,17 @@ Status: implemented
 
 ## 决策
 
-删除 `packages/ui/tui` 包，不提供兼容包或别名。其源码、包测试、终端快照、依赖声明、已打补丁的 `pi-tui` 产物、workspace 引用、生成的服务目录条目和文档会一并移除。通用宿主能力与 agent-loop 能力保持不变。
+删除 `packages/ui/tui` 包，不提供兼容包或别名。其源码、包测试、终端快照、依赖声明、已打补丁的 `pi-tui` 产物、workspace 引用、生成的服务目录条目和文档会一并移除。通用宿主能力与 agent loop（智能体循环）能力保持不变。
 
 SDK 的运行接口联合类型现在只包含 `acp` 与 `embed`。`create-sdk` 默认使用 ACP，生成的模板不再包含终端启动、恢复、会话环境或模型参数分支；内置的 `ask-user` 功能也被移除，因为剩余两个生成接口都不提供 `UserInteractionProvider`。宿主应用仍可直接挂载提供方无关的 `dsh-user-interaction`、`dsh-commands` 和呈现 seam。
 
 本决策取代[显式配置 `dsh` 入口决策](../../archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md)中保留可复用包的决定，也使已归档 TUI 实现记录不再适用于当前状态。这些历史记录继续保持冻结，但不再作为受支持包或应用清单的依据。
 
-本记录汇总了删除后无法继续保持当前状态的仅限包记录。终端 UI 曾在长对话期间保持会话身份可见、移除重复模型标签、为消息附加耗时与阶段状态、在提示词旁显示 workspace 与分支上下文，并保守地解析完整 XML 包装层，以生成人类可读的回退输出。这些选择改善了一个终端前端，但没有部署时不足以证明应保留它。未来的 XML 回退仍必须使用真实解析器而非正则表达式。
+本记录汇总了因移除该包而无法继续保持现行有效、现已删除的仅涉及该包的记录。终端 UI 曾在长对话期间保持会话身份可见、移除重复模型标签、为消息附加耗时与阶段状态、在提示词旁显示 workspace 与分支上下文，并保守地解析完整 XML 包装层，以生成人类可读的回退输出。这些选择改善了一个终端前端，但在没有部署的情况下，并不足以证明应保留它。未来的 XML 回退仍必须使用真正的解析器而非正则表达式。
 
 ## 验证
 
-仓库搜索结果与生成目录中不再包含 TUI 包、依赖补丁、SDK 接口选项、服务键或包链接。聚焦的 SDK 测试覆盖 ACP 与嵌入式创建、配置、模板和快照。常规源码构建、类型检查、lint、hygiene、文档门禁以及其余组装快照测试套件均可在没有已删除 workspace 的情况下运行。
+仓库搜索结果与生成的服务目录中不再包含 TUI 包、依赖补丁、SDK 接口选项、服务键或包链接。专项 SDK 测试覆盖 ACP 和嵌入式两种模式的创建、配置、模板与快照。常规源码构建、类型检查、lint、hygiene、文档门禁以及其余组装快照测试套件均可在没有已删除 workspace 的情况下运行。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.i18n.yaml
index 36404ebcdd..b34924d341 100644
--- a/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.md
 2026-08-06-user-bubbles-drop-the-branch-action.md: 817b5e72b7e18b03ddb3a160e6f7a86b04f02764
-2026-08-06-user-bubbles-drop-the-branch-action.zh.md: dab3890818d872d7bbb3ac9bcab014ce9b829a61
+2026-08-06-user-bubbles-drop-the-branch-action.zh.md: a80f723242383cc9a35b9933dcc9c63ebeacd9d8
diff --git a/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.zh.md b/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.zh.md
index dab3890818..a80f723242 100644
--- a/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：user 与 steering 气泡移除分支操作
+# Agent Note: user 与 steering 气泡移除分支操作
 
 Status: implemented
 
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-每个 user 气泡和已消费的 steering（中途引导）气泡都渲染分支控件，受[已完成轮次尾部决策](../bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)的门禁约束。在这些气泡上，该门禁实际上是永久性的：开轮的 user 消息后面必然跟着本轮自己的节点，已消费的 steering 消息按构造就处在轮次中间，因此只有当轮次结束时该消息之后一个节点都没有——即在第一个模型事件之前就取消——控件才可能启用。读者因此看到一个永远不会启用的控件，tooltip 许诺的是这个按钮到达不了的状态。这个操作入口本身也有误导：在消息 seq 处 fork 会切在所在轮次的 `turn/end`，"在我的消息处分支"实际会把下方的回答一并带走，与在自己气泡上看到分支时"分叉重问"的直觉预期恰好相反。
+每个 user 气泡和已消费的 steering（中途引导）气泡都渲染分支控件，受[已完成轮次尾部决策](../bug-fix/2026-08-02-message-fork-actions-require-completed-turn-tail.md)的门禁约束。在这些气泡上，该门禁实际上是永久性的：开轮的 user 消息后面必然跟着本轮自己的节点，已消费的 steering 消息按构造就处在轮次中间，因此只有当轮次结束时该消息之后一个节点都没有——即在第一个模型事件之前就取消——控件才可能启用。读者因此看到一个永远不会启用的控件，tooltip 许诺的是这个按钮到达不了的状态。这个操作入口本身也有误导：在消息 seq 处 fork 会切在所在轮次的 `turn/end`，「在我的消息处分支」实际会把下方的回答一并带走，与在自己气泡上看到分支时「分叉重问」的直觉预期恰好相反。
 
 ## 决策
 
-user 与 steering 气泡不再渲染分支操作。`MessageItem` 移除其 fork props，`PendingSteeringBubble` 移除其 `showBranch` 特例，`messageBranchSeqs` 收窄为 `assistantBranchSeqs`：只有已完成轮次的 transcript 尾部、且该尾部是本轮自己的带 text 内容 assistant 节点才可 fork。分支入口只存在于已定稿的回答之下。
+user 与 steering 气泡不再渲染分支操作。`MessageItem` 移除其 fork props，`PendingSteeringBubble` 移除其 `showBranch` 特例，`messageBranchSeqs` 收窄为 `assistantBranchSeqs`：只有已完成轮次的 transcript（文本记录）尾部、且该尾部是本轮自己的带 text 内容 assistant 节点才可 fork。分支入口只存在于已定稿的回答之下。
 
 含有 steer 的轮次的 fork 点保持不变：fork 是切在 `turn/end` 上的日志前缀，steer 是子会话必须继承的模型可见历史，因此被引导过的轮次的已定稿回答与其他轮次一样可以 fork。assistant 侧的门禁及其可见但不可用的呈现也保持不变——在回答之下，不可用是一个短暂且可到达的状态（当前尾部被后续工具行或错误行占据），这正是 tooltip 的用武之地。
 
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
index cd43c3a27b..9a88d14722 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
 2026-08-08-remove-cli-demo.md: c1153f5e9fcc89585e926f8f088829c849d1f6c1
-2026-08-08-remove-cli-demo.zh.md: 1f9719b176c05009900a268a5bb2d2d7fcc79df3
+2026-08-08-remove-cli-demo.zh.md: 7f11e0c17a15454b99b32d14ea6eda177f4b01f6
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
index 1f9719b176..7f11e0c17a 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
@@ -6,9 +6,9 @@ Status: implemented
 
 ## 问题
 
-在 [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出契约、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
+在 [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出约定、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
 
-回放套件仍需要规范会话事件来固定组装后的后端行为。这一测试需求不需要已发布命令或兼容性契约。
+回放套件仍需要规范会话事件来固定组装后的后端行为。这一测试需求不需要已发布命令或兼容性约定。
 
 ## 决策
 
@@ -19,7 +19,7 @@ Status: implemented
 ## 考虑过的替代方案
 
 - **保留 `dsh-cli-demo` 作为 `dsh run` 的别名或包装层。** 不予采纳：第二个 bin 和包会让同一功能继续存在两个可发现的归属方，却没有增加任何能力。
-- **把 JSON 和 stream-JSON 标志移到 `dsh run`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）契约。
+- **把 JSON 和 stream-JSON 标志移到 `dsh run`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）约定。
 - **随包一并删除规范事件快照。** 不予采纳：这些快照固定了模型可见的组装行为，而只检查最终文本的产品验收无法观察这些行为。
 - **保留应用插件，只删除它的 bin。** 不予采纳：隐藏的组装仍会重复显式的 headless profile，并掩盖测试叶节点挂载了哪些服务。
 
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
index 5f9a220dc5..882684d786 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
 2026-07-24-web-gui-browser-e2e-lane.md: 095ad9055c8462ecec67609ed9af55df2a2d7adb
-2026-07-24-web-gui-browser-e2e-lane.zh.md: eb20ee378eb5154bafcb7a448202c66dacda9199
+2026-07-24-web-gui-browser-e2e-lane.zh.md: 7c9b97da1810a81a0b7574c50b819892f9686695
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
index eb20ee378e..7c9b97da18 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
@@ -6,29 +6,29 @@ Status: implemented
 
 ## 问题
 
-Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bundle → HTTP 单次 RPC + 两条 SSE（Server-Sent Events）流 → `toFetchHandler`/apiproxy → host 端的 agent loop（智能体循环）、工具与 JSONL 持久化——却没有任何测试无密钥且确定性地检验这条链。[GUI 测试体系](../process/2026-07-20-gui-testing-system.md)覆盖第 1 层（Node 中的协议同构）、第 2 层（对象层状态机）与第 3 层冒烟测试，但无密钥冒烟驱动的是 `FixtureApiClient`——没有 host、没有 wire、没有 agent loop——而全链路冒烟需要 `DEEPSEEK_API_KEY` 和真实模型，因此不确定、在无密钥 CI 中自行跳过。[docs/testing.md](../../../../docs/testing.md) 的快照哲学——带密钥录制一次、永久无密钥回放、格式变动时刷新——已覆盖 ACP（Agent Client Protocol）、headless `stream-json` 与 TUI 三个文本记录（transcript）表面；web 表面是唯一没有这层保障的组装形态。而缺口恰恰是两起已实证 GUI P0 藏身之处：fixture（测试前置数据）客户端短路掉的 wire 承载链。
+Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bundle → HTTP 单次 RPC + 两条 SSE（Server-Sent Events）流 → `toFetchHandler`/apiproxy → host 端的 agent loop（智能体循环）、工具与 JSONL 持久化——却没有任何测试无密钥且确定性地检验这条链。[GUI 测试体系](../process/2026-07-20-gui-testing-system.md)覆盖第 1 层（Node 中的协议同构）、第 2 层（对象层状态机）与第 3 层冒烟测试，但无密钥冒烟驱动的是 `FixtureApiClient`——没有 host、没有 wire、没有 agent loop——而全链路冒烟需要 `DEEPSEEK_API_KEY` 和真实模型，因此不确定、在无密钥 CI 中自行跳过。[docs/testing.md](../../../../docs/testing.md) 的快照哲学——带密钥录制一次、永久无密钥回放、格式变动时刷新——已覆盖 ACP（Agent Client Protocol）、headless `stream-json` 与 TUI 三个 transcript（文本记录）表面；web 表面是唯一没有这层保障的组装形态。而缺口恰恰是两起已实证 GUI P0 藏身之处：fixture（测试前置数据）客户端短路掉的 wire 承载链。
 
 ## 决策
 
-`pnpm run test:web` 携带 `apps/web/tests/` 下的无密钥、确定性浏览器 e2e 车道：录制的会话日志 fixture 经 `@deepseek-ai/dsh-llm-replay` 对真实进程内 web 组合回放；用户可见状态使用规范化的 aria 预期输出，持久世界状态则使用进程内断言。配套的产品契约包括 `dsh-llm-replay` 的节奏控制、消费检查与已校验的索引式覆写 patch；跨包的 `dsh-llm` 失败通过自有数据属性保留经校验的提供方信息；已交付的 web 组合挂载 `llm-retry`，以处理瞬态模型失败。
+`pnpm run test:web` 携带 `apps/web/tests/` 下的无密钥、确定性浏览器 e2e 车道：录制的会话日志 fixture 经 `@deepseek-ai/dsh-llm-replay` 对真实进程内 web 组合回放；用户可见状态使用规范化的 aria 预期输出，持久世界状态则使用进程内断言。配套的产品约定包括 `dsh-llm-replay` 的节奏控制、消费检查与已校验的索引式覆写 patch；跨包的 `dsh-llm` 失败通过自有数据属性保留经校验的提供方信息；已交付的 web 组合挂载 `llm-retry`，以处理瞬态模型失败。
 
 ### Scaffold：`apps/web/tests/scaffold.ts`
 
 一个普通的共享 fixture 模块（[测试政策认可的形态](../../../../docs/testing.md)），不是包：值得门禁把守的逻辑——回放推导、会话解析、日志脱敏、持久化——都在已受门禁的包 `dsh-llm-replay`、`dsh-acp-snapshot`、`dsh-session-persistence-jsonl` 中；剩下的只是启动接线和浏览器胶水，而驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100% 覆盖率。
 
-`launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；每个主机级 `skill-local` 根目录（`dshHome`、`agentsHome` 和 `bundledSkillDir`）都钉在临时工作区下并禁用监听，因为环境 skill（技能）目录是模型可见输入；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI 冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。
+`launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；每个主机级 `skill-local` 根目录（`dshHome`、`agentsHome` 和 `bundledSkillDir`）都钉在临时工作区下并禁用监听，因为环境 skill（技能）目录是模型可见输入；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI（命令行界面）冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。
 
-无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充开放的 seam——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步后压力检查将步步告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让 seam 保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。
+无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充开放的 seam——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步骤后的压力检查会在每个步骤都告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让 seam 保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。
 
-`seedSession()` 通过真实持久化 API 播种冷会话——一次性 `Context` 挂载 `SessionStore` + `SessionPersistenceJsonl` 指向 host 的根目录，`create()` + `append()`，一次 `utimes` 回拨保证侧栏顺序确定（`semantic-checkpoint.snapshot.ts` 先例）——绝不裸写文件，因此播种器对桶哈希、文件名编码、压缩一无所知，host 的 zstd 默认值也无需任何启动开关。种子在播种时即校验（可解析、以 `turn/end` 结尾——未闭合的最终轮次会被恢复（resume）的崩溃修复改写）。
+`seedSession()` 通过真实持久化 API 播种冷会话——一次性 `Context` 挂载 `SessionStore` + `SessionPersistenceJsonl` 指向 host 的根目录，`create()` + `append()`，一次 `utimes` 回拨保证侧栏顺序确定（`semantic-checkpoint.snapshot.ts` 先例）——绝不裸写文件，因此播种器对桶哈希、文件名编码、压缩一无所知，host 的 zstd 默认值也无需任何启动开关。种子在播种时即校验（可解析、以 `turn/end` 结尾——未闭合的最终轮次会被恢复的崩溃修复改写）。
 
 ### 确定性规则
 
-回放模式下浏览器断言的屏障栈，按序：（1）host 侧 `await agent.whenIdle()` 加超时，以进程内 `turn/end` 为锚——空闲翻转发生在持久化落盘之后，一次等待同时覆盖轮次完成与持久性；（2）浏览器安定轮询（流式输出节点已卸载、最终文本可见）。录制模式下，日志采收在 `whenIdle()` 之后、scaffold 释放之前进行，此时运行中的会话仍然可用。单独监听进程内 `turn/end` 是错误屏障（它先于 SSE 帧到达浏览器、先于 fsync 触发）；禁止轮询持久化文件来充当轮次完成或持久性屏障（NFS 上慢，且被 `whenIdle` 取代），但工具控制的临时就绪标记可以仅作为该完成屏障之前的交互门控进行轮询；`networkidle` 被彻底禁止（SSE 流保持打开时它永不解析）。导航断言会在页面加载前同时监听 `session.list` 和 `workspace.list` 的初始响应，随后等待播种数据投影到 DOM；仅凭 shell 已挂载不能判定就绪，因为较晚完成的 bootstrap 可能替换受控状态。
+回放模式下浏览器断言的屏障栈，按序：（1）host 侧 `await agent.whenIdle()` 加超时，以进程内 `turn/end` 为锚——空闲翻转发生在持久化落盘之后，一次等待同时覆盖轮次完成与持久性；（2）浏览器安定轮询（流式输出节点已卸载、最终文本可见）。录制模式下，日志采收在 `whenIdle()` 之后、scaffold 释放之前进行，此时运行中的会话仍然可用。单独监听进程内 `turn/end` 是错误屏障（它先于 SSE 帧到达浏览器、先于 fsync 触发）；禁止轮询持久化文件来充当轮次完成或持久性屏障（NFS 上慢，且被 `whenIdle` 取代），但工具控制的临时就绪标记可以仅作为该完成屏障之前的交互门控进行轮询；`networkidle` 被彻底禁止（SSE 流保持打开时永远不会达到该状态）。导航断言会在页面加载前同时监听 `session.list` 和 `workspace.list` 的初始响应，随后等待播种数据投影到 DOM；仅凭 shell 已挂载不能判定就绪，因为较晚完成的 bootstrap 可能替换受控状态。
 
 不做单次瞬态 DOM 断言：从回放产出到 React 提交的每一跳都可能合并分片，采样 `[data-streaming]` 天然就是竞态。流式输出的增量性由持久化的 `assistant/chunk` 事件断言（模型可见 ⟺ 已记录，使日志成为权威证据）。`dsh-llm-replay` 的可选 `paceMs`（默认缺省 = 突发）只是让浏览器观察到真正增量 SSE 的真实感旋钮；正确性绝不依赖它，且节奏等待期间中止会即时取消。
 
-每个场景都会因任何 pageerror 或客户端的连接丢失/间隙修复控制台警告而失败：否则重连机制加历史重同步会把一条死掉的 SSE 通路自愈掉，套件反而认证了坏 wire。Scaffold 的 `close()` 调用 `ReplayHandle.assertConsumed()` 收尾检查（每个已录脚本都被绑定、每个游标都耗尽），把静默的少放与错绑变成清晰诊断。车道不设 vitest 重试；每文件一个 chromium、每场景一个新 context、每场景一个 host；视口固定；交互选择器锚定 role、`data-*` 属性和可见文本，而 frame 与会话区采集则使用既有的 CSS 模块局部类名锚点。常规场景在客户端启动前设置 `dsh.locale=en`，使本地化的 role 定位器和预期输出统一采用明确指定的语言；断言中文文案的场景则不预设该存储项，改为开启 `zh-CN` 浏览器，因为客户端的初始 locale 由 `navigator` 推导（[由浏览器推导初始 locale](../feature/2026-07-31-browser-derived-initial-locale.md)），而 `settings-chrome.e2e.ts` 还额外覆盖双向切换与英文浏览器默认态。
+每个场景都会因任何 pageerror 或客户端的连接丢失/间隙修复控制台警告而失败：否则重连机制加历史重同步会把一条死掉的 SSE 通路自愈掉，套件反而认证了坏 wire。Scaffold 的 `close()` 调用 `ReplayHandle.assertConsumed()` 收尾检查（每个已录脚本都被绑定、每个游标都耗尽），把静默的消费不足与错绑变成清晰诊断。车道不设 vitest 重试；每文件一个 chromium、每场景一个新 context、每场景一个 host；视口固定；交互选择器锚定 role、`data-*` 属性和可见文本，而 frame 与会话区采集则使用既有的 CSS 模块局部类名锚点。常规场景在客户端启动前设置 `dsh.locale=en`，使本地化的 role 定位器和预期输出统一采用明确指定的语言；断言中文文案的场景则不预设该存储项，改为开启 `zh-CN` 浏览器，因为客户端的初始 locale 由 `navigator` 推导（[由浏览器推导初始 locale](../feature/2026-07-31-browser-derived-initial-locale.md)），而 `settings-chrome.e2e.ts` 还额外覆盖双向切换与英文浏览器默认态。
 
 ### 预期输出
 
@@ -40,19 +40,19 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 `DSH_SNAPSHOT` 选择 replay（默认，无密钥）、record（带密钥）或 refresh（无密钥）。发起提示的 spec 将所有模式共用的驱动步骤与仅供 replay/refresh 使用的断言分开；record 模式驱动真实输入框，采收内存中的会话 header 与事件，脱敏请求头，并 token 化当次运行的会话、cwd 与 RPC 标识。随后一次无密钥 refresh 重新生成 aria 预期输出。每条提示词都会与 fixture 中录制的 `user/message` 核对；每个场景目录都采用封闭清单，其中每个 JSONL 都是脱敏不动点。Web fixture 全部脱敏请求头且不钉任何 header 类别；见「暂缓」。
 
-### 覆盖契约
+### 覆盖约定
 
-该车道覆盖三类行为。实时轮次场景钉住普通工具执行、取消、不可重试失败、瞬态重试、常驻提问与轮次中途 steering；同步依赖持久事件、`whenIdle()` 或显式回放标记，而不使用延时。冷历史场景通过真实持久化 API 播种，在不调用模型的情况下覆盖历史渲染、侧栏搜索、Trajectory 与 Waterfall 视图及工具详情。浏览器生命周期场景覆盖首次发送时物化工作区、重新加载恢复、布局重置、主题与语言偏好，以及工作区的创建、重命名和视图操作。每类场景都断言浏览器表面和权威的 host 状态；离群的模型调用或未耗尽的 fixture 会使拆卸失败。必需车道还包含一份合成的 88 轮 Chat 滚动契约，其中混合了换行 Markdown、围栏代码以及成对的 bash 调用/结果。真实 wheel、输入框、工具、tab、会话与 viewport 交互会在并发历史前插加带节奏流式输出、贴底/离底流式输出、工具 disclosure 离屏循环、扩展历史后的视图/会话重新挂载、宽度重排、贴底后立即重新挂载、输入框尺寸变化以及 textarea wheel 链场景中，断言一个具名已结算行相对 transcript scrollport 的顶部位置和到真实底部的距离；真实键盘翻页与触摸式惯性滑动模拟额外钉住不依赖 wheel 的贴底跟随所有权（[读者滚动归因笔记](../bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md)）；它刻意不钉 DOM 基数或绝对 `scrollTop`，因此同一契约可以验收虚拟化实现。另一份基于同一 fixture 的交互契约钉住异构行顺序、相邻工具 disclosure 的独立状态、用户消息剪贴板内容的精确值、以轮次为边界的消息 fork、源会话/子会话隔离，以及子会话中的一次真实追问轮次；wheel 输入只用于导航到语义目标，不承载几何预期。一份简短的实时历史契约从空白工作区开始，连续驱动输入框轮次，其中包括真实的 bash 调用/结果轮次和一段带节奏的长篇最终响应；它钉住单一会话身份、每轮事件的精确归属、浏览器回显唯一性与输入框恢复，不设置时间阈值。
+该车道覆盖三类行为。实时轮次场景钉住普通工具执行、取消、不可重试失败、瞬态重试、常驻提问与轮次中途 steering（中途引导）；同步依赖持久事件、`whenIdle()` 或显式回放标记，而不使用延时。冷历史场景通过真实持久化 API 播种，在不调用模型的情况下覆盖历史渲染、侧栏搜索、Trajectory 与 waterfall（瀑布式事件）视图及工具详情。浏览器生命周期场景覆盖首次发送时物化工作区、重新加载恢复、布局重置、主题与语言偏好，以及工作区的创建、重命名和视图操作。每类场景都断言浏览器表面和权威的 host 状态；离群的模型调用或未耗尽的 fixture 会使拆卸失败。必需车道还包含一份合成的 88 个轮次的 Chat 滚动约定，其中混合了换行 Markdown、围栏代码以及成对的 bash 调用/结果。真实 wheel、输入框、工具、tab、会话与 viewport 交互会在并发历史前插加带节奏流式输出、贴底/离底流式输出、工具 disclosure 离屏循环、扩展历史后的视图/会话重新挂载、宽度重排、贴底后立即重新挂载、输入框尺寸变化以及 textarea wheel 链场景中，断言一个具名已结算行相对 transcript scrollport 的顶部位置和到真实底部的距离；真实键盘翻页与触摸式惯性滑动模拟额外钉住不依赖 wheel 的贴底跟随所有权（[读者滚动归因笔记](../bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md)）；它刻意不钉 DOM 基数或绝对 `scrollTop`，因此同一约定可以验收虚拟化实现。另一份基于同一 fixture 的交互约定钉住异构行顺序、相邻工具 disclosure 的独立状态、用户消息剪贴板内容的精确值、以轮次为边界的消息 fork、源会话/子会话隔离，以及子会话中的一次真实追问轮次；wheel 输入只用于导航到语义目标，不承载几何预期。一份简短的实时历史约定从空白工作区开始，连续驱动输入框轮次，其中包括真实的 bash 调用/结果轮次和一段带节奏的长篇最终响应；它钉住单一会话身份、每个轮次的事件精确归属、浏览器回显唯一性与输入框恢复，不设置时间阈值。
 
 ### CI 立场
 
-根据[浏览器快照 CI 决策](2026-07-30-web-browser-snapshot-ci-gate.md)，该车道是 Linux 拉取请求必需的只比较门禁。`node 24 / snapshots and artifacts` 消费方任务在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，安装锁文件选定的 Chromium，恢复以操作系统和锁文件为键的缓存，并用 `DSH_SNAPSHOT=replay` 运行该车道。这是有意的平面切分：host 与 spec 使用 [tsx 源码启动契约](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)，浏览器则消费 `apps/web/dist` 和包的 `lib/client.js` 产物，因此门禁依赖 `built-package-invariants` 提供这些客户端产物。托管和自托管的默认分支 Linux 串行任务运行同一门禁；托管任务生成供 PR 消费的浏览器缓存，持久化自托管池则不需要托管侧缓存。CI 从不录制或刷新预期输出。场景仍面向 POSIX，并继续置于 Windows 和 macOS 矩阵之外。
+根据[浏览器快照 CI 决策](2026-07-30-web-browser-snapshot-ci-gate.md)，该车道是 Linux PR（Pull Request）必需的只比较门禁。`node 24 / snapshots and artifacts` 消费方任务在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，安装锁文件选定的 Chromium，恢复以操作系统和锁文件为键的缓存，并用 `DSH_SNAPSHOT=replay` 运行该车道。这是有意的平面切分：host 与 spec 使用 [tsx 源码启动约定](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)，浏览器则消费 `apps/web/dist` 和包的 `lib/client.js` 产物，因此门禁依赖 `built-package-invariants` 提供这些客户端产物。托管和自托管的默认分支 Linux 串行任务运行同一门禁；托管任务生成供 PR 消费的浏览器缓存，常驻自托管池则不需要托管侧缓存。CI 从不录制或刷新预期输出。场景仍面向 POSIX，并继续置于 Windows 和 macOS 矩阵之外。
 
-高基数性能诊断使用单独按需启用的 `apps/web/tests/**/*.perf.ts` 清单，并且只由 `vitest.web.perf.config.ts` 选中。`complex-history.perf.ts` 的隔离用例复用真实 scaffold：工作区用例播种 1,000 个紧凑会话以及一份包含 500 次工具调用的 500 轮次历史，在 Chat 中穷尽并重新挂载该历史，并报告 Chromium 主线程、DOM、监听器、堆内存、分页、搜索和 Trajectory 测量结果。两个续聊用例播种同一份长历史，但比较默认的 24 轮次 Chat 窗口与展开全部 500 轮次的状态，然后各自通过真实输入框、agent loop、SSE wire、工具和持久化继续进行 8 个相同轮次；其中两轮执行真实 `bash` 调用并断言其持久化结果，最后一轮则填入一条包含 8,232 个字符的混合语言提示词，并回放 120 个带节奏的文本增量。一个单独的 soak 用例从空白会话开始，通过真实输入框连续驱动 100 轮，每第 10 轮执行一次 `bash` 调用并产生结果，每 10 轮强制执行一次 GC，并报告每 10 轮的延迟窗口及保留的浏览器状态。随后它通过受信任的浏览器点击提交第 101 个纯文本轮次，并使用浏览器时钟分别测量发送到 transcript DOM 和发送到绘制后的延迟，排除输入框的草稿镜像，并与完整轮次完成时间分开。逐轮诊断涵盖输入框填入、点击到用户消息回显、点击到首个分片、完成、浏览器变更、持久化分片和工具事件；合成回放模型拥有足够的上下文容量，可使 fixture 基数保持稳定，而不会因压缩（compaction）消耗脚本化调用。结构性断言钉住预期的负载、流和工具形状，但时间仍不设阈值，因为机器速度不属于正确性契约。必需的 `vitest.web.config.ts` 清单仍仅限 `*.e2e.ts` 和 `*.snapshot.ts`，因此 `test:web:built` 及其 CI 门禁都不会收集性能用例。
+高基数性能诊断使用单独按需启用的 `apps/web/tests/**/*.perf.ts` 清单，并且只由 `vitest.web.perf.config.ts` 选中。`complex-history.perf.ts` 的隔离用例复用真实 scaffold：工作区用例播种 1,000 个紧凑会话以及一份包含 500 次工具调用的 500 轮次历史，在 Chat 中穷尽并重新挂载该历史，并报告 Chromium 主线程、DOM、监听器、堆内存、分页、搜索和 Trajectory 测量结果。两个续聊用例播种同一份长历史，但比较默认的 24 轮次 Chat 窗口与展开全部 500 轮次的状态，然后各自通过真实输入框、agent loop、SSE wire、工具和持久化继续进行 8 个相同轮次；其中两个轮次执行真实 `bash` 调用并断言其持久化结果，最后一个轮次则填入一条包含 8,232 个字符的混合语言提示词，并回放 120 个带节奏的文本增量。一个单独的 soak 用例从空白会话开始，通过真实输入框连续驱动 100 个轮次，每 10 个轮次执行一次 `bash` 调用并产生结果，每 10 个轮次强制执行一次 GC，并报告每 10 个轮次的延迟窗口及保留的浏览器状态。随后它通过受信任的浏览器点击提交第 101 个纯文本轮次，并使用浏览器时钟分别测量发送到 transcript DOM 和发送到绘制后的延迟，排除输入框的草稿镜像，并与完整轮次完成时间分开。各轮次诊断涵盖输入框填入、点击到用户消息回显、点击到首个分片、完成、浏览器变更、持久化分片和工具事件；合成回放模型拥有足够的上下文容量，可使 fixture 基数保持稳定，而不会因压缩（compaction）消耗脚本化调用。结构性断言钉住预期的负载、流和工具形状，但时间仍不设阈值，因为机器速度不属于正确性约定。必需的 `vitest.web.config.ts` 清单仍仅限 `*.e2e.ts` 和 `*.snapshot.ts`，因此 `test:web:built` 及其 CI 门禁都不会收集性能用例。
 
 ## 业界先例
 
-调研了 AI 聊天/agent web UI 与 mock 层（LibreChat、vercel/ai-chatbot + AI SDK、lobe-chat、open-webui、OpenHands、Chainlit、continue、cline、langfuse、gradio/streamlit；Playwright HAR/route、MSW、Polly/nock、WireMock、aimock）。自有后端的应用的主流成熟架构是：真实后端 seam 后放一个进程内伪造/回放模型，下游全部真实（LibreChat 的 `LIBRECHAT_TEST_RUN_HOOK` 伪模型；ai-chatbot 的 `MockLanguageModelV3` + `simulateReadableStream`；continue 的脚本化 mock 提供方类）——这正是 `dsh-llm-replay` 已然所是。浏览器层 SSE 拦截无法检验增量渲染（`route.fulfill` 一次性交付整个响应体；playwright#33564），且服务端 SSE 栈完全失测，因此各项目只把它用于边缘用例。分片节奏作为 fixture 参数反复出现（LibreChat 默认 10ms 附慢速档；ai-chatbot 500ms）；CI 里的真实模型会腐烂（open-webui 的套件长出 120 秒超时，先被禁用后被删除）；会话在持久化层以受控时间戳播种（LibreChat 直插回拨时间的 Mongo 文档；langfuse 播种其数据库）。没有任何被调研项目为 UI 测试把录制的 agent 事件日志经真实后端回放——最接近的是提供方层录制 fixture（aimock）与前端层 socket 历史发射（OpenHands MSW）——因此会话日志即 fixture 的设计沿着本仓库「模型可见 ⟺ 已记录」不变式所指的方向比业界先例多走了一步。
+调研了 AI（人工智能）聊天/agent web UI 与 mock 层（LibreChat、vercel/ai-chatbot + AI SDK、lobe-chat、open-webui、OpenHands、Chainlit、continue、cline、langfuse、gradio/streamlit；Playwright HAR/route、MSW、Polly/nock、WireMock、aimock）。自有后端的应用的主流成熟架构是：真实后端 seam 后放一个进程内伪造/回放模型，下游全部真实（LibreChat 的 `LIBRECHAT_TEST_RUN_HOOK` 伪模型；ai-chatbot 的 `MockLanguageModelV3` + `simulateReadableStream`；continue 的脚本化 mock 提供方类）——这正是 `dsh-llm-replay` 已然所是。浏览器层 SSE 拦截无法检验增量渲染（`route.fulfill` 一次性交付整个响应体；playwright#33564），且服务端 SSE 栈完全失测，因此各项目只把它用于边缘用例。分片节奏作为 fixture 参数反复出现（LibreChat 默认 10ms 附慢速档；ai-chatbot 500ms）；CI 里的真实模型会腐烂（open-webui 的套件长出 120 秒超时，先被禁用后被删除）；会话在持久化层以受控时间戳播种（LibreChat 直插回拨时间的 Mongo 文档；langfuse 播种其数据库）。没有任何被调研项目为 UI 测试把录制的 agent 事件日志经真实后端回放——最接近的是提供方层录制 fixture（aimock）与前端层 socket 历史发射（OpenHands MSW）——因此会话日志即 fixture 的设计沿着本仓库「模型可见 ⟺ 已记录」不变式所指的方向比业界先例多走了一步。
 
 ## 曾考虑的替代方案
 
@@ -62,15 +62,15 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **扩展 `?fixture` 客户端。** 已否决：分层纪律——`FixtureApiClient` 的存在意义就是脱离服务器测试客户端 shell；client API seam 以下按构造即失测。
 
-**用占位 `DEEPSEEK_API_KEY` + 回放拦截替代禁用适配器行。** 尽管零组合改动且树内有两处先例仍被否决：它用谎言满足 `llm-deepseek` 的快速失败密钥检查，还留下一个挂载却被拦截的死适配器；禁用行（ACP overlay 的同款做法）是诚实的无密钥，并在最早可解析点快速失败。
+**用占位 `DEEPSEEK_API_KEY` + 回放拦截替代禁用适配器行。** 尽管零组合改动且树内有两处先例仍被否决：它以谎言绕过 `llm-deepseek` 会明确报错的密钥检查，还留下一个挂载却被拦截的死适配器；禁用行（ACP overlay 的同款做法）才是真正的无密钥方案，并会在最早可判定点明确失败。
 
-**`packages/support/web-snapshot` 包 + `defineWebSnapshotSuite` 工厂。** 已否决：驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100%，且除受门禁的包已导出的辅助工具与本地 scaffold 外，这些场景专用交互尚未形成稳定的无浏览器契约。出现第二个 web 形态消费方，或被证实重复的生命周期代码确立该契约后，再重新考虑。
+**`packages/support/web-snapshot` 包 + `defineWebSnapshotSuite` 工厂。** 已否决：驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100%，且除受门禁的包已导出的辅助工具与本地 scaffold 外，这些场景专用交互尚未形成稳定的无浏览器约定。出现第二个 web 形态消费方，或被证实重复的生命周期代码确立该约定后，再重新考虑。
 
 **第二份提交的规范化会话日志预期输出。** 已否决：日志表面已由 ACP/headless/TUI 套件经同一循环与持久化钉住；在此只会翻倍刷新成本并重复测试下层。内联在根上下文事件上的世界状态断言保住了验证世界的义务。
 
 **以 `DSH_SNAPSHOT` 回放分支拉起 `dsh web` bin。** 已否决：它需要在交付的 CLI 中增加测试专用回放分支和环境变量管道。进程内 scaffold 已加载同一份 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml`；只剩 argv、profile JSON 和 `AppCLIEntry` 胶水不在其覆盖范围内，而这些路径已由无密钥 CLI 冒烟覆盖。
 
-**为可测试性改 wire 协议。** 已否决：契约已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
+**为可测试性改 wire 协议。** 已否决：约定已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
 
 **以真实模型浏览器测试充当无密钥车道。** 已否决：按构造即不确定；被调研的前车之鉴（open-webui）长出无界超时后被删除。带密钥的 W5 冒烟仍是真实模型侧的补充。
 
@@ -78,18 +78,18 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **客户端 `data-dsh-busy` 安定信号。** 暂缓：host 侧 `whenIdle` 屏障配合稳定 DOM 轮询，足以覆盖当前场景。第一次安定轮询抖动，或必要状态在 DOM 中不可观察时，再重新考虑。
 
-## Testing
+## 测试
 
-`pnpm run test:web` 构建并无密钥运行该车道；`test:web:built` 基于现有构建产物运行。`pnpm run test:web:perf` 构建并运行手动性能清单；`test:web:perf:built` 复用现有产物。`DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/<spec>` 对真实模型录制一个发起提示的场景，`DSH_SNAPSHOT=refresh pnpm run test:web` 则无密钥重写 aria 预期输出。CI 显式选择回放模式。live-interactions AUTH 场景会把不可重试的终态失败钉为 Chat 内联状态，其中携带适合展示的消息与错误码，并验证提供方回显的凭据片段不会出现在 Chat 或 Trajectory 中；该场景同时覆盖输入框恢复与 `turn/end` 错误。scaffold 环境隔离场景会在全部 3 个环境 skill 根目录中分别填入不同条目，并要求这些条目都不得进入组装后的目录。`dsh-llm-replay` 单元覆盖率钉住节奏控制、取消、消费诊断、sidecar 校验、按索引替换与唯一的追加位置。
+`pnpm run test:web` 构建并无密钥运行该车道；`test:web:built` 基于现有构建产物运行。`pnpm run test:web:perf` 构建并运行手动性能清单；`test:web:perf:built` 复用现有产物。`DSH_SNAPSHOT=record pnpm exec vitest run --config vitest.web.config.ts apps/web/tests/<spec>` 对真实模型录制一个发起提示的场景，`DSH_SNAPSHOT=refresh pnpm run test:web` 则无密钥重写 aria 预期输出。CI 显式选择回放模式。live-interactions AUTH 场景会把不可重试的终态失败钉为 Chat 内联状态，其中携带适合展示的消息与错误码，并验证提供方回显的凭据片段不会出现在 Chat 或 Trajectory 中；该场景同时覆盖输入框恢复与 `turn/end` 错误。scaffold 环境隔离场景会在全部 3 个环境 skill 根目录中分别填入不同条目，并要求这些条目都不得进入组装后的目录。`dsh-llm-replay` 单元覆盖率钉住节奏控制、取消、消费诊断、伴随文件校验、按索引替换与唯一的追加位置。
 
 ## 暂缓
 
-- **Web 头类别钉住**：web fixture 处处 token 化 `{{system}}`/`{{tools}}`，没有场景钉住 web 组合的提示词/工具 schema（`TODO(web-header-pin)`——scaffold 的 `recordFixture` JSDoc 有标记）。沿用 TUI 处处脱敏先例；当 web 组装的请求头与其镜像的 repl 组合进一步分叉时重审。
+- **Web 头类别钉住**：web fixture 处处 token 化 `{{system}}`/`{{tools}}`，没有场景钉住 web 组合的提示词/工具 schema（`TODO(web-header-pin)`——scaffold 的 `recordFixture` JSDoc 有标记）。沿用 TUI 处处脱敏先例；当 web 组装的请求头与其镜像的 repl 组合发生分叉时重审。
 - **恢复后追问场景**：真实 wire 上的历史/实时缝合路径；当该代码变更或回归时作为独立场景补充。
 - **输入框 steering 手势**：输入在运行期间锁定（只能停止或等待），因此 steering 场景从页面走 wire 做 steer；`TODO(web-steer-composer)` 待产品长出真实的输入框手势后，把驱动步骤升级为该手势。
 - **拖拽会话重排**：`workspace.insertSessionBefore` 尚无浏览器场景；它需要在同一个工作区里物化两个会话，并合成 HTML5 拖拽事件。当该表面变更或回归时再补充。无行为的会话 Rename/Fork/Delete 和工作区 Delete 菜单行待获得行为后再补充场景。
-- **长历史 Chat 到 Trajectory 的 Inspect**：独立的检查数据源会在视图打开后穷尽历史，而所选记录由一个派生的表格索引定位；随着较早页面前插，该索引可能移动。短历史 Inspect 仍有覆盖；在选中项具有稳定的语义身份之前，长历史交互契约不包含这项交接。
+- **长历史 Chat 到 Trajectory 的 Inspect**：独立的检查数据源会在视图打开后穷尽历史，而所选记录由一个派生的表格索引定位；随着较早页面前插，该索引可能移动。短历史 Inspect 仍有覆盖；在选中项具有稳定的语义身份之前，长历史交互约定不包含这项交接。
 
 ## 后果
 
-Web 表面获得了录制一次/永久回放的层级：真实 chromium → SSE → apiproxy → 循环 → 工具 → 持久化的链路以约 10-30 秒无密钥运行，重复运行结果确定，fixture 由车道自身持有并可重录。接受的成本：每次有意的会话 UI 变更都以一次无密钥 `DSH_SNAPSHOT=refresh` 收尾（预期输出变动是受评审的 diff，锚断言保住语义绿色）；aria 格式归 Playwright 所有——仓库唯一不受自己控制的提交快照格式——因此 playwright 版本升级必须是刻意的升级加刷新提交（依赖在 `apps/web/package.json` 中浮动为 `^1.49.0`；若变动伤人则改为精确锁定）；回放的首次调用顺序绑定把每个场景限制为至多一个发起提示的会话，消费断言是绊线；`compact-basic` 与会话共享回放游标，仅在发布的 128k 目录窗口下保持闲置；必需的消费方任务承担 Chromium 供给与一次浏览器运行的成本，使改动组装后 UI 的 PR（Pull Request）持有相应的预期输出 diff。按需启用的性能车道保留了可重复的诊断工作负载，又不会向 CI 添加受 host 差异影响的时长或内存预期；在仓库拥有经校准的基准测试环境之前，性能回归仍是需要人工解读的信号。
+Web 表面获得了录制一次/永久回放的层级：真实 chromium → SSE → apiproxy → 循环 → 工具 → 持久化的链路以约 10-30 秒无密钥运行，重复运行结果确定，fixture 由车道自身持有并可重录。接受的成本：每次有意的会话 UI 变更都以一次无密钥 `DSH_SNAPSHOT=refresh` 收尾（预期输出变动是受评审的 diff，锚断言保住语义绿色）；aria 格式归 Playwright 所有——仓库唯一不受自己控制的提交快照格式——因此 playwright 版本升级必须是刻意的升级加刷新提交（依赖在 `apps/web/package.json` 中浮动为 `^1.49.0`；若变动伤人则改为精确锁定）；回放的首次调用顺序绑定把每个场景限制为至多一个发起提示的会话，消费断言是绊线；`compact-basic` 与会话共享回放游标，仅在目录中公布的 128k 窗口下保持闲置；必需的消费方任务承担 Chromium 供给与一次浏览器运行的成本，使改动组装后 UI 的 PR 持有相应的预期输出 diff。按需启用的性能车道保留了可重复的诊断工作负载，又不会向 CI 添加受 host 差异影响的时长或内存预期；在仓库拥有经校准的基准测试环境之前，性能回归仍是需要人工解读的信号。
diff --git a/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.i18n.yaml b/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.i18n.yaml
index e829874e9d..697b8abe36 100644
--- a/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.md
 2026-07-30-vitest-jsdom-webstorage-ownership.md: 3956a7566fa1c79a767636bce9a19f16588126e2
-2026-07-30-vitest-jsdom-webstorage-ownership.zh.md: 9080ee2762b74bf2efdaccd7a5905672001bc0e8
+2026-07-30-vitest-jsdom-webstorage-ownership.zh.md: bd01ffdc68a45802ae403bdf44533d39126b021a
diff --git a/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.zh.md b/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.zh.md
index 9080ee2762..bd01ffdc68 100644
--- a/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-30-vitest-jsdom-webstorage-ownership.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-受支持的 Node 版本范围包含会预留进程级 `globalThis.localStorage` 的版本。未设置 `--localstorage-file` 时，Node 26 将该属性暴露为 `undefined`；Vitest 检测到这个预留键后，不会用 jsdom 的隔离 `Storage` 对象覆盖该属性。因此，组件测试套件尚未验证产品行为便会失败，而主要的 Node 24 覆盖率分支仍能通过，因为该运行时默认不会预留此键。
+受支持的 Node 版本范围包含会预留进程级 `globalThis.localStorage` 的版本。未设置 `--localstorage-file` 时，Node 26 将该属性暴露为 `undefined`；Vitest 检测到这个预留键后，不会用 jsdom 的隔离 `Storage` 对象覆盖该属性。因此，组件测试套件尚未验证产品行为便会失败，而主要的 Node 24 覆盖率通道仍能通过，因为该运行时默认不会预留此键。
 
 ## 决策
 
@@ -23,4 +23,4 @@ Node 兼容性汇总任务会在每条声明支持的兼容版本线上运行专
 
 ## 后果
 
-同一条 `pnpm test` 命令在有无内置 Web Storage 的 Node 版本上均可运行。测试 worker 被有意禁止使用 Node 的进程级 Web Storage；未来若产品需要该 API，必须使用独立且显式的测试配置，而不能削弱 jsdom 隔离。兼容性分支只增加一个专项 Vitest 进程，无需在每个 Node 版本上重复整套单元测试。
+同一条 `pnpm test` 命令在有无内置 Web Storage 的 Node 版本上均可运行。测试 worker 被有意禁止使用 Node 的进程级 Web Storage；未来若产品需要该 API，必须使用独立且显式的测试配置，而不能削弱 jsdom 隔离。兼容性通道只增加一个专项 Vitest 进程，无需在每个 Node 版本上重复整套单元测试。
diff --git a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml
index 2e8e53fdd7..227135714f 100644
--- a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md
 2026-07-30-web-browser-snapshot-ci-gate.md: 14402485034cd85ec5781477ce67481165d47e62
-2026-07-30-web-browser-snapshot-ci-gate.zh.md: f214c524253d2ad8a43e8543dc65ddfcfd7c065c
+2026-07-30-web-browser-snapshot-ci-gate.zh.md: 28a7ef9a7046516a853b3e18a44163c01d43a318
diff --git a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md
index f214c52425..28a7ef9a70 100644
--- a/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md
@@ -14,22 +14,22 @@ Linux PR 的 `node 24 / snapshots and artifacts` 必须运行完整 Web 浏览
 
 消费方 job 在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，因此 `apps/web/dist` 和包的 `lib/` 目录会保留在其工作区中，供浏览器套件使用。在托管运行器上，CI 按锁文件中的 Playwright 版本安装 Chromium 及其系统依赖。在持久化故障切换 VM 上，镜像负责预装 Linux 系统软件包，CI 只安装 Chromium，避免每次运行都通过 `apt` 改动系统。托管的默认分支 Linux 串行 job 运行该套件，并生成以操作系统和锁文件为键的浏览器缓存；PR 恢复该缓存，使必需路径无需承担压缩和上传开销，并可在锁文件变化时按操作系统前缀回退。自托管热备运行相同的比较，但不执行托管缓存操作。
 
-本地 `pnpm run test:web` 仍先构建再运行浏览器全集；`test:web:built` 是已有构建产物的执行入口。开发者只在确认用户可见输出有意变化后显式运行 `DSH_SNAPSHOT=refresh pnpm run test:web`，评审每一处 expected diff，再以 replay 模式复验不再写文件。
+本地 `pnpm run test:web` 仍先构建再运行完整的浏览器套件；`test:web:built` 是已有构建产物的执行入口。开发者只在确认用户可见输出有意变化后显式运行 `DSH_SNAPSHOT=refresh pnpm run test:web`，评审每一处预期输出 diff，再以 replay 模式复验不再写文件。
 
-对 PR 而言，门禁仅在 Linux 消费方 job 中运行：这些场景面向 POSIX，其他 PR job 不供给 Chromium。托管和自托管的默认分支 Linux 串行聚合作业也包含该比较，而 macOS 和 Windows 串行 job 仍不使用浏览器。PR 的 `all checks passed` 已依赖消费方 job，因此浏览器比较失败会阻止合并，无需新增 branch-protection check 名称。
+对 PR 而言，门禁仅在 Linux 消费方 job 中运行：这些场景面向 POSIX，其他 PR job 不安装 Chromium。托管和自托管的默认分支 Linux 串行聚合作业也包含该比较，而 macOS 和 Windows 串行 job 仍不使用浏览器。PR 的 `all checks passed` 已依赖消费方 job，因此浏览器比较失败会阻止合并，无需新增 branch-protection check 名称。
 
 一次自托管消费方运行中，`web-snapshot` 实测耗时 112.15 秒，完整消费方聚合实测耗时 114.97 秒。gate 调度器会在 `built-package-invariants` 成功后立即启动它，并发运行彼此独立的 gate，因此既不需要专用 job 超时，也不需要手动制定 YAML 顺序规则。
 
 ## 曾考虑的替代方案
 
-**继续只要求本地运行。** 已否决：执行依赖开发者记忆，正是旧 golden 跨 PR 漂移的原因，不能保证产生行为变化的 PR 自己携带 expected diff。
+**继续只要求本地运行。** 已否决：执行依赖开发者记忆，正是陈旧 golden 跨 PR 漂移的原因，不能保证产生行为变化的 PR 自己携带预期输出 diff。
 
-**让 CI 以 `refresh` 模式运行后检查工作树。** 已否决：写后比较把断言机制变成生成器，若工作树检查接线失效就会把回归更新成绿色；replay 直接比较已有 golden，失败面更小。
+**让 CI 以 `refresh` 模式运行后检查工作树。** 已否决：写后比较把断言机制变成生成器，若工作树检查接入有误，就可能把回归变成能够通过的预期输出更新；replay 直接比较已有 golden，失败面更小。
 
 **新建独立 browser job 并重新构建全仓。** 已否决：它会重复依赖安装和发布构建。现有 Linux 消费方 job 已负责该构建，并已被统一的 required verdict 聚合。
 
-**用 jsdom 快照代替真实 Chromium。** 已否决：jsdom 不覆盖浏览器、HTTP/SSE 承载及真实 client plugin bundle 组合；它保留为快速的下层反馈，不能替代 assembled browser chain。
+**用 jsdom 快照代替真实 Chromium。** 已否决：jsdom 不覆盖浏览器、HTTP/SSE 承载及真实客户端插件包的组合；它仍可用于快速的下层反馈，但不能替代组装后的浏览器链路。
 
 ## 后果
 
-每个 PR 都在合并前证明当前 Web 组装与所有已提交的浏览器 expected 一致，漏刷从“后续 PR 的无关变化”变成引入 PR 自己的失败。成本是消费方 job 需要供给 Chromium，并串行运行一轮浏览器场景；消费方独立构建与浏览器缓存避免重跑时重复构建和下载。门禁仍不声称跨平台浏览器一致性，Playwright/Chromium 升级若改变 aria 格式，升级 PR 必须显式 refresh 并评审 churn。
+每个 PR 都在合并前证明当前 Web 组装与所有已提交的浏览器预期输出一致，漏刷从“后续 PR 的无关变化”变成引入 PR 自己的失败。成本是消费方 job 需要安装 Chromium，并串行运行一轮浏览器场景；消费方独立构建与浏览器缓存避免重跑时重复构建和下载。门禁仍不声称跨平台浏览器一致性，Playwright/Chromium 升级若改变 ARIA 格式，升级 PR 必须显式 refresh 并评审 churn。
diff --git a/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.i18n.yaml b/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.i18n.yaml
index 052d177aad..5f5facd8d7 100644
--- a/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.md
 2026-08-03-opt-in-reasoning-chunk-browser-stress.md: 70c200c7ade6ef995c68b68ddc21e4c85edf0da8
-2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md: aa1d29bffd3dcba54925b43eab13ef4d9a4f7cff
+2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md: 9fb4be27369d4489fc90a6151fcbd0861ef83f2c
diff --git a/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md b/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md
index aa1d29bffd..9fb4be2736 100644
--- a/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md
+++ b/.agents/notes/implemented/testing/2026-08-03-opt-in-reasoning-chunk-browser-stress.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 推理分片的逐帧累计发布与浏览器压力验证
+# Agent Note: 推理（reasoning）分片的逐帧累计发布与浏览器压力验证
 
 Status: implemented
 
@@ -12,15 +12,15 @@ Status: implemented
 
 ## 决策
 
-`Session.acceptLiveEvent()` 立即追加每个原始事件，并同步更新 transcript、`PartialAccumulator` 及其他会话派生状态。可见的 `block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta` 和 `block-end` 分片通过 `Notifier.markFrameDirty()` 发布：第一项变化调度一次 `requestAnimationFrame`，后续分片只继续更新累积器；帧回调从最新状态重建一个累计快照并通知订阅者一次。`usage`、`finish` 及未知的不可见分片保留在事件窗口中，但不触发无效的 React 通知。会话与历史检查共用同一可见分片分类。
+`Session.acceptLiveEvent()` 立即追加每个原始事件，并同步更新 transcript（文本记录）、`PartialAccumulator` 及其他会话派生状态。可见的 `block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta` 和 `block-end` 分片通过 `Notifier.markFrameDirty()` 发布：第一项变化调度一次 `requestAnimationFrame`，后续分片只继续更新累积器；帧回调从最新状态重建一个累计快照并通知订阅者一次。`usage`、`finish` 及未知的不可见分片保留在事件窗口中，但不触发无效的 React 通知。会话与历史检查共用同一可见分片分类。
 
-`Notifier` 用调度种类和代际标记管理待发布工作。普通结构事件继续通过 `markDirty()` 在微任务发布；如果定稿消息、工具事件或错误到达时仍有待执行的帧发布，微任务会取代它，旧帧回调因代际不匹配而失效。`notifyNow()` 同样使旧调度失效，以保留受控输入的同步回响。没有 `requestAnimationFrame` 的环境退回微任务合批。定稿事件可以跳过一次尚未显示的中间 partial，但发布的定稿内容和原始事件序列保持完整。
+`Notifier` 用调度种类和代际标记管理待发布工作。普通结构事件继续通过 `markDirty()` 在微任务中发布；如果定稿消息、工具事件或错误到达时仍有待执行的帧发布，微任务会取代它，旧帧回调因代际不匹配而失效。`notifyNow()` 同样使旧调度失效，以保留受控输入的同步回响。没有 `requestAnimationFrame` 的环境退回微任务合批。定稿事件可以跳过一次尚未显示的中间 partial，但发布的定稿内容和原始事件序列保持完整。
 
 实时 Think 行对累计文本的横向跟尾属于纯视觉对齐，不需要在每次 React 提交中同步读取布局。组件内调度器将连续请求合并为每三帧一次，从最新 DOM 读取 `scrollWidth` 和 `clientWidth` 并将 `scrollLeft` 直接更新到最新位置；固定的视觉节奏让摘要变化可读，又不会积压浏览器平滑滚动动画。该节流只作用于 Think 的横向摘要，不延迟 Chat 正文滚动、历史 prepend 锚定或用户触发的 `scrollIntoView`。
 
-`pnpm run test:web:stress` 保留为无密钥、需显式启用的浏览器性能证据。确定性的 `?fixture` 会话以独立于绘制的节奏发出 100,000 个 `reasoning-delta`，结尾标记证明事件经过生产会话归并并到达实时 Think 行；50 毫秒心跳和预先调度的 DOM 事件分别测量主线程停顿与交互延迟，250 毫秒预算用于识别明显回归。`DSH_WEB_STRESS_HEADFUL=1` 允许开发者在可见浏览器中使用 Performance 面板分析同一场景。该压力车道是手动性能诊断与修复验收证据，不是默认 CI 门禁，也不替代确定性的调度单元测试。
+`pnpm run test:web:stress` 保留为无密钥、需显式启用的浏览器性能证据。确定性的 `?fixture` 会话以独立于绘制的节奏发出 100,000 个 `reasoning-delta`，结尾标记证明事件经过生产会话归并并到达实时 Think 行；50 毫秒心跳和预先调度的 DOM 事件分别测量主线程停顿与交互延迟，250 毫秒预算用于识别明显回归。`DSH_WEB_STRESS_HEADFUL=1` 允许开发者在可见浏览器中使用 Performance 面板分析同一场景。该压力车道是手动性能诊断与修复验收的证据，不是默认 CI 门禁，也不替代确定性的调度单元测试。
 
-聚焦测试固定 `Notifier` 的逐帧合并、结构事件抢占、失效回调和无 rAF 回退，并在 `Session` 层证明一帧只发布一次最新累计文本且定稿不会被旧帧回调重复通知。fixture 的小型单元测试继续固定输入校验、外部到达节奏、并发拒绝、精确事件数和结尾标记交付，无需把 100,000 分片工作负载带入默认测试套件。
+聚焦测试固定 `Notifier` 的逐帧合并、结构事件抢占、失效回调和无 rAF 回退，并在 `Session` 层证明一帧只发布一次最新累计文本且定稿不会被旧帧回调重复通知。fixture（测试前置数据）的小型单元测试继续固定输入校验、外部到达节奏、并发拒绝、精确事件数和结尾标记交付，无需把 100,000 分片工作负载带入默认测试套件。
 
 ## 曾考虑的替代方案
 
@@ -28,7 +28,7 @@ Status: implemented
 
 **在接收或日志层丢弃、抽样或拼接原始分片。** 不予采纳：原始 `assistant/chunk` 是可重放的会话事实，改变它会损失诊断与 UI 保真度，并把展示频率策略混入数据权威层。
 
-**只使用微任务合批。** 不予采纳：连续异步 `yield` 会在相邻分片间排空微任务队列，使一个微任务调度近似退化为一次分片一次通知。
+**只使用微任务合批。** 不予采纳：连续异步 `yield` 会在相邻分片间排空微任务队列，使微任务合批近似退化为每个分片通知一次。
 
 **按动画帧控制测试生产方节奏。** 不予采纳：生产方会在渲染变慢时同步减速，使页面获得真实网络流不存在的隐式背压，并掩盖主线程饥饿。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
index e4acea8bc5..ba673b6d6d 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md
 2026-07-29-durable-last-activity-index.md: 0e441f54a719b29a1a450c133e08cdf7d2c82e9e
-2026-07-29-durable-last-activity-index.zh.md: 9557da0a186084499dfb0f3e8d36016d5b216ae7
+2026-07-29-durable-last-activity-index.zh.md: d66fc9a53700988976acea2f040f1aa886ea9e4f
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
index 9557da0a18..d66fc9a537 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
@@ -8,38 +8,38 @@ Status: proposed
 
 一个冷会话（已持久化、未附加）对「上次是什么时候在这里面工作过」没有任何已存储的答案。因此 `dsh-host-apiproxy` 的 `summarizeCold()` 在存在日志文件时用它的 mtime 来近似它——`locate()` 为 JSONL 解析出一个逐会话产物，为 SQLite 解析出 `undefined`，而 SQLite 的冷会话会回退到 `createdAt`——而 web 客户端就按由此得到的 `updatedAt` 为自己的会话树排序。这两个后端错的方向正好相反：JSONL 读出来偏新，SQLite 偏旧。
 
-mtime 回答的是另一个问题：这份产物上次是什么时候被写入的。每一次持久写入都会刷新它，包括那些并不是活动的写入：一次对撕裂尾部的截断修复、用来平衡被中断的轮次的那些合成 closer，以及带种子的会话会追加的 [`session/end-seed` 边界](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)。（没有待处理内容的 `flush` 不在其中：协调器在到达后端之前就返回了。）用户可见的后果是稳定的，而且只朝一个方向错：一个被触碰过却没有在里面工作过的会话，会把自己排到用户此后真正工作过的那些会话之前，而且每次触碰都会重新把它排上去一次。`dsh-host-apiproxy` 让 `session.history` 保持只执行检查，但任何绑定到 Agent 的普通会话控件都会通过 `agentFor()` 恢复会话，足以把冷态产物排到前面。
+mtime 回答的是另一个问题：这份产物上次是什么时候被写入的。每一次持久写入都会刷新它，包括那些并不是活动的写入：一次对撕裂尾部的截断修复、用来平衡被中断的轮次的那些合成 closer，以及带种子的会话会追加的 [`session/end-seed` 边界](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)。（没有待处理内容的 `flush` 不在其中：协调器在到达后端之前就返回了。）用户可见的后果是稳定的，而且只朝一个方向错：一个被触碰过却没有在里面工作过的会话，会把自己排到用户此后真正工作过的那些会话之前，而且每次触碰都会重新把它排上去一次。`dsh-host-apiproxy` 让 `session.history` 保持只用于检查，但任何绑定到 agent（智能体）的普通会话控件都会通过 `agentFor()` 恢复会话，足以把冷态产物排到前面。
 
-已附加会话的那个投影有真正的修复办法（`lastActivityTime()` 会跳过边界），但它需要事件日志，而冷路径有意不去读日志。为计算 `updatedAt` 而读取日志，会让只读 header 的列举失去意义，而正是它让 `list()` 的开销随会话数量而非日志体量增长。
+已附加会话的那个投影有真正的修复办法（`lastActivityTime()` 会跳过边界），但它需要事件日志，而冷路径有意不去读日志。为计算 `updatedAt` 而读取日志，会让仅读取 header 的列举失去意义，而正是它让 `list()` 的开销随会话数量而非日志体量增长。
 
 [边界那次变更](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)提高了这个缺陷的出现频率，因为一次拾起如今会在此前完全无写入的路径上产生写入；`dsh-host-apiproxy` 的 README 已在 Known Limitations 中记录该项。它并没有引入这套近似做法，而移除这套近似是一项持久格式决策，因此它的范围划在本文，而不是那里。
 
 ## 提案
 
-把最后活动时间存到列举本就会读取的地方，也就是会话索引，这样 `summarizeCold()` 无需打开日志就能给出答案。该值由协调器计算，因为它看得到每一次追加，而且本就拥有每 id 状态；由后端负责持久化。这样它就成为 `PersistenceBackend` 契约中新增的一个要素，而不是各后端本地的账目，同时让「活动」只保留一个定义，与日志内的 `lastActivityTime()` 共用。
+把最后活动时间存到列举本就会读取的地方，也就是会话索引，这样 `summarizeCold()` 无需打开日志就能给出答案。该值由协调器计算，因为它看得到每一次追加，而且本就拥有每个 id 的状态；由后端负责持久化。这样它就成为 `PersistenceBackend` 约定中新增的一个要素，而不是各后端本地的账目，同时让「活动」只保留一个定义，与日志内的 `lastActivityTime()` 共用。
 
 两个已交付的后端受到的约束正好相反，本提案对它们有意采取不对称的处理：
 
 - **SQLite** 在 `sessions` 表上得到一列，与 `appendBatch` 在同一个事务中写入，代价是一次单调的 `SCHEMA_VERSION` 递增。
-- **JSONL 无法承载一个可变的 header 字段。** header 就是第 1 行，在物化时一次写就，此后这份日志永远以追加方式打开；`jsonl.spec.ts` 钉住了「已提交的字节绝不重写」。一个每次追加都要改的 header 字段，违反的是一条被断言的持久性不变式，而不只是让写入方变复杂。要与「让 JSONL 保持近似」相比较的形态，是每会话一个伴随文件。
+- **JSONL 无法承载一个可变的 header 字段。**header 就是第 1 行，在物化时一次写就，此后这份日志永远以追加方式打开；`jsonl.spec.ts` 钉住了「已提交的字节绝不重写」。一个每次追加都要改的 header 字段，违反的是一条被断言的持久性不变式，而不只是让写入方变复杂。要与「让 JSONL 保持近似」相比较的形态，是每会话一个伴随文件。
 
 实现之前必须回答三个问题，本文对它们都没有定论：
 
-**哪些事件算作活动？** 对日志而言，`lastActivityTime()` 通过排除 `session/end-seed` 回答了这个问题。一个已存储字段是在写入时编码这条规则的，而写入方在那里只看到一个批次，不是整份日志。两者不得发生漂移，否则已附加表层与冷表层会对同一个会话给出彼此矛盾的答案。
+**哪些事件算作活动？**对日志而言，`lastActivityTime()` 通过排除 `session/end-seed` 回答了这个问题。一个已存储字段是在写入时编码这条规则的，而写入方在那里只看到一个批次，不是整份日志。两者不得发生漂移，否则已附加表层与冷表层会对同一个会话给出彼此矛盾的答案。
 
-**该字段引入之前的日志表现如何？** 既有产物里没有这个值。回退到 mtime 能让它们保持今天的准确度；回退到 `createdAt` 是诚实的，但会把选择器和会话树里每一个既有会话都重新排一次序。
+**该字段引入之前的日志表现如何？**既有产物里没有这个值。回退到 mtime 能让它们保持当前的准确度；回退到 `createdAt` 是诚实的，但会把选择器和会话树里每一个既有会话都重新排一次序。
 
-**对 JSONL 来说伴随文件可以接受吗？** 它重新引入了每会话第二个文件，而该文件可能与日志不一致，这正是单产物设计所避开的。
+**对 JSONL 来说伴随文件可以接受吗？**它重新引入了每会话第二个文件，而该文件可能与日志不一致，这正是单产物设计所避开的。
 
 ## 考虑过的替代方案
 
-**在冷路径上读取日志。** 它按构造就是正确的，也不需要改动格式，但会让只读 header 的列举失去意义：`list()` 的开销将随日志总体量增长，而 web 会话树会扇出到存储中的每一个会话。mtime 近似的存在，正是为了避开这个选项。
+**在冷路径上读取日志。**它按构造就是正确的，也不需要改动格式，但会让仅读取 header 的列举失去意义：`list()` 的开销将随日志总体量增长，而 web 会话树会扇出到存储中的每一个会话。mtime 近似的存在，正是为了避开这个选项。
 
-**保留 mtime，但把边界的写入排除在它之外。** 否决的理由是做不到，而不是不合意：mtime 属于文件系统，不属于后端。除了在每次边界写入之后把时间戳复原，没有别的办法能保住它，而那样做会与任何并发读取方产生竞态，也会对这份产物撒谎。
+**保留 mtime，但把边界的写入排除在它之外。**否决的理由是做不到，而不是不合意：mtime 属于文件系统，不属于后端。除了在每次边界写入之后把时间戳复原，没有别的办法能保住它，而那样做会与任何并发读取方产生竞态，也会对这份产物撒谎。
 
-**仅在确实发生了修复时才写入边界。** 这能降低出现频率，而[边界 Agent Note](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)已经否决过它：谓词对有序重启同样必须成立。用一条正确性不变式去换时间戳的准确度，方向是错的。
+**仅在确实发生了修复时才写入边界。**这能降低出现频率，而[边界 Agent Note](../../implemented/architecture/2026-07-30-session-end-seed-log-boundary.md)已经否决过它：谓词对有序重启同样必须成立。用一条正确性不变式去换时间戳的准确度，方向是错的。
 
-**从投影缓存派生活动时间。** `session-projection-cache` 本就会折叠水位线之后的尾部，因此一个最后活动单元可以搭乘既有机制。它作为主形态被否决，因为该缓存是一个可选的组合项；只有挂载了缓存插件才提供的列举，会让排序取决于如何组合。
+**从投影缓存派生活动时间。**`session-projection-cache` 本就会折叠水位线之后的尾部，因此一个最后活动单元可以搭乘既有机制。它作为主形态被否决，因为该缓存是一个可选的组合项；只有挂载了缓存插件才提供的列举，会让排序取决于如何组合。
 
 ## 验收标准
 
@@ -47,17 +47,17 @@ mtime 回答的是另一个问题：这份产物上次是什么时候被写入
 - 在 web 会话树和 TUI 恢复选择器中，一个恢复后即被弃置的会话不会排到此后工作过的会话之前；由一份组装后的快照钉住，而不是只靠单元测试。
 - 活动规则只有一个定义：一个测试证明，在一份同时包含边界、closer 和一个普通轮次的日志上，已存储字段与 `lastActivityTime()` 的结果一致。
 - 在选定的回退方案下，该字段引入之前的产物能够无错误地加载和列举，并且该回退在排序上的后果有断言覆盖。
-- 按本仓库不做迁移的立场，SQLite 的 `SCHEMA_VERSION` 递增会拒绝旧的磁盘版本。
+- 按本仓库不做迁移的立场，SQLite 的 `SCHEMA_VERSION` 递增会拒绝磁盘上的旧版本。
 
 ## 风险
 
-**「活动」的两个定义发生漂移。** 已存储字段按批次计算，而投影在整份日志上计算。一种新事件类型若在写入时按一种方式归类、在读取时按另一种方式归类，就会产生一个冷排序与已附加排序彼此矛盾的会话；这个缺陷只在重启之后才显现，而那正是最难被注意到的地方。
+**「活动」的两个定义发生漂移。**已存储字段按批次计算，而投影在整份日志上计算。一种新事件类型若在写入时按一种方式归类、在读取时按另一种方式归类，就会产生一个冷排序与已附加排序彼此矛盾的会话；这个缺陷只在重启之后才显现，而那正是最难被注意到的地方。
 
-**JSONL 的伴随文件可能与它的日志不一致。** 在日志追加与伴随文件写入之间发生崩溃，会留下一个陈旧的值，而且没有撕裂尾部标记可用来修复它。每个消费方都得把伴随文件当作一条提示来对待，而这与 mtime 今天的地位已经很接近了。
+**JSONL 的伴随文件可能与它的日志不一致。**在日志追加与伴随文件写入之间发生崩溃，会留下一个陈旧的值，而且没有撕裂尾部标记可用来修复它。每个消费方都得把伴随文件当作一条提示来对待，而这与 mtime 目前的地位已经很接近了。
 
-**回退方案会让既有会话重新排序。** 无论选定哪种回退，持有既有日志的用户都会在升级时看到自己的选择器和会话树重新排一次序。选 `createdAt` 会让这次重排的幅度很大。
+**回退方案会让既有会话重新排序。**无论选定哪种回退，持有既有日志的用户都会在升级时看到自己的选择器和会话树重新排一次序。选 `createdAt` 会让这次重排的幅度很大。
 
-**代价可能超过这个缺陷本身。** 该缺陷是被弃置会话的排序出错。如果对 JSONL 来说诚实的答案是「保留这套近似」，那么本文的结局可能是记录下这个决定，而不是实现一个字段，而这也是一个可以接受的结局。
+**代价可能超过这个缺陷本身。**该缺陷是被弃置会话的排序出错。如果对 JSONL 来说诚实的答案是「保留这套近似」，那么本文的结局可能是记录下这个决定，而不是实现一个字段，而这也是一个可以接受的结局。
 
 ## 相关
 
diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
index c70cbb870b..cac60421b6 100644
--- a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.md
 2026-08-08-semantic-composer-chain-phases.md: 7d85518e9d5e5aa3e44e443cb1b90b325b0ffc6a
-2026-08-08-semantic-composer-chain-phases.zh.md: a202b9bfeb9276cdccaa7b438036cd1236a33317
+2026-08-08-semantic-composer-chain-phases.zh.md: 860676a0c83d76e2bd4b8f8f63ca7d025b91c3ff
diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
index a202b9bfeb..860676a0c8 100644
--- a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
@@ -18,7 +18,7 @@ Status: proposed
 
 阶段词汇归声明该 slot 的领域所有，而不属于全局 slot 框架。`SlotMap` 携带确切的阶段元组，用于编译期注册；运行时 `SlotSpec` 重复该元组，作为排序依据。其他链不会获得任何 composer 术语，也无需迁移，除非它们主动声明阶段。
 
-本提案扩展 [Web subagent 对话](../../implemented/feature/2026-07-27-web-subagent-conversations.md)、[Web 权限与审批](../../implemented/feature/2026-07-23-web-permission-and-approval.md)和[计划审阅呈现](../../implemented/feature/2026-07-30-plan-review-presentation-intent.md)契约，但不取代其中任何一项。[运行时所有权子级守卫](../../implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md)仍然是防止子级新建自己负责的人类等待的权威机制。本提案落地时，不应归档任何活跃 Agent Note。
+本提案扩展 [Web subagent 对话](../../implemented/feature/2026-07-27-web-subagent-conversations.md)、[Web 权限与审批](../../implemented/feature/2026-07-23-web-permission-and-approval.md)和[计划审阅呈现](../../implemented/feature/2026-07-30-plan-review-presentation-intent.md)约定，但不取代其中任何一项。[运行时负责的子级守卫](../../implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md)仍然是防止子级新建自己负责的人类等待的权威机制。本提案落地时，不应归档任何活跃 Agent Note。
 
 ## 备选方案
 
@@ -26,7 +26,7 @@ Status: proposed
 
 **当 `interactions` 非空时，让只读选择器拒绝匹配。** 这可以修复当前这一对组件，但会迫使限制插件理解每个可操作领域，并在各选择器中重复选举策略。每新增一种交互类型，都需要修改与其无关的限制项。
 
-**只依赖运行时子级守卫。** 该守卫可以修复新的模型调用，但无法定义浏览器对已有待处理等待、滚动升级中的版本重叠或审批等其他交互类型的排序。运行时权限与呈现选举是两项独立的不变量。
+**只依赖运行时子级守卫。** 该守卫可以修复新的模型调用，但无法定义浏览器对已有待处理等待、滚动升级中的版本重叠或审批等其他交互类型的排序。运行时权威机制与呈现选举是两项独立的不变量。
 
 **把所有匹配的接管界面渲染成一个栈。** composer 只有一个操作席位。同时堆叠问题、审批和只读界面，会使键盘焦点与回答所有权含混不清，而不是选出一个当前操作。
 
@@ -36,11 +36,11 @@ Status: proposed
 - Composer 测试覆盖问题加只读项、审批加只读项、问题加审批加只读项、解决后回到只读项，以及所有选择器均拒绝匹配时回退到 InputBar。问题在 `interaction` 内仍排在审批之前。
 - dispose（资源释放）、HMR（热模块替换）重新注册和重新连接回放均不能留下陈旧的当选阶段；选举仍是当前所有者 props 与当前注册项的纯函数。
 - 一项无密钥组装 Web 快照固定已寻址的 one-shot 对话及其待处理交互：交互界面胜出，解决该交互后，只读界面再次出现。
-- slot、conversation、question、permission 和 subagent 的 README／JSDoc 契约共同描述阶段所有权以及交互先于限制的规则。
+- slot、conversation、question、permission 和 subagent 的 README／JSDoc 约定共同描述阶段所有权以及交互先于限制的规则。
 - 该变更不修改任何模型可见的工具定义、系统提示词章节、请求路由或会话事件。因此，浏览器选举既不产生 token 开销，也不会使 KV Cache 失效；测试会比较仅在客户端发生状态转换前后的模型请求 header。
 
 ## 风险
 
 阶段名称可能沦为含混的设计替代品。因此，每个分阶段 slot 都要拥有一条简短的排序规则，并拒绝无法说明自身归属哪一侧的注册项。未来如有必须优先于回答操作的硬性安全界面，不应将其误标为 `restriction`；它需要一个显式排在更前的阶段，或位于该 composer 链以外的边界。
 
-通用 slot 类型与已存储条目形态会增加一个条件字段，因此迁移不完整时，代码可能在一个 face 中通过编译，却在运行时失败。之所以在运行时声明中重复确切元组，正是为了让系统能以机械方式拒绝这种漂移。并发问题与审批仍采用单界面策略；本提案保留其当前顺序，不解决多交互排队问题。
+通用 slot 类型与已存储条目形态会增加一个条件字段，因此迁移不完整时，代码可能在一个 compiler face 中通过编译，却在运行时失败。之所以在运行时声明中重复确切元组，正是为了让系统能以机械方式拒绝这种漂移。并发问题与审批仍采用单界面策略；本提案保留其当前顺序，不解决多交互排队问题。
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
index fab3ecc2b1..494cdc8ec9 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
 2026-07-17-sdk-follow-up-capabilities.md: 88d5d2f9bd1ce01c20177bcaee5bbe6b434bb978
-2026-07-17-sdk-follow-up-capabilities.zh.md: 998b7ec3cfddafe40537908fb61aa6d7e6f90418
+2026-07-17-sdk-follow-up-capabilities.zh.md: 083890a88fbb580aafe2e71bef9202f037089d1f
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
index 998b7ec3cf..083890a88f 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: SDK 后续功能
+# Agent Note: SDK 后续能力
 
 Status: proposed
 
@@ -8,13 +8,13 @@ Status: proposed
 
 首个 SDK 版本通过[开发者工程 Agent Note](2026-07-14-sdk-developer-projects.md) 和 [SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md)定义的共享模型创建和编辑开发者拥有的 Cordis 工程。create 和 config 工作流仅支持交互调用，接入外部 Cordis 插件需要手工修改依赖和配置，命令行遥测没有明确的所属边界，交互分支也缺少稳定的测试策略。
 
-这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession`；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml`。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品契约。
+这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession`；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml`。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品约定。
 
 ## 提案
 
 SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非交互式 `PromptPort` 实现和结构化功能计划驱动 create 与 config；`dsh-sdk create <source>` 先把依赖解析交给工程的包管理器，再通过 `ProjectEditSession` 挂载解析所得的包；启动器侧遥测包住 `create-sdk` 和每个 `dsh-sdk` 命令；交互测试主要通过注入的提示词输入输出流完成。
 
-| 功能 | 产品入口 | 所属机制 | 必须达到的结果 |
+| 能力 | 产品入口 | 所属机制 | 必须达到的结果 |
 |---|---|---|---|
 | Headless 工程创建 | `create-sdk --config <file>` 或 `--config-json <json>`，可搭配 `--json` | `HeadlessPromptPort`、结构化工程答案和完整功能计划 | 不阻塞等待终端；明确报告缺失的必答输入 |
 | 外部 Cordis 插件安装 | `dsh-sdk create <source>` | 包管理器原生 `add` 加 `ProjectEditSession` | 依赖和 `cordis.yml` 配置项指向包管理器解析出的包 |
@@ -27,25 +27,25 @@ SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非
 
 Headless create 通过 `--config-json` 接收内联 JSON 对象，或通过 `--config` 从文件读取。标量字段提供普通 create 答案，`features` 提供完整的已选功能、功能选项、secret（密钥）和专用值。只有所属问题明确声明的默认值才有效；headless 路径绝不为必答问题臆造答案。
 
-使用 `--json` 时，stdout 是 NDJSON 事件流。`done` 表示创建及要求执行的安装和构建均已完成，`action-required` 指明一个尚未回答的必答问题，`error` 报告其他失败。面向人的进度信息和包管理器输出写入 stderr，确保 stdout 每一行都能解析成一个事件。调用方收到 `action-required` 后补充缺失值，再次运行命令。
+使用 `--json` 时，stdout 是 NDJSON 事件流。`done` 表示创建及任何请求的设置均已完成，`action-required` 指明一个尚未回答的必答问题，`error` 报告其他失败。面向人的进度信息和包管理器输出写入 stderr，确保 stdout 每一行都能解析成一个事件。调用方收到 `action-required` 后补充缺失值，再次运行命令。
 
 Create 和 config 使用相同的功能计划形状。create 通过上述命令行输入公开该形状；config 在共享工作流边界使用同一形状，使后续自动化入口无需另建功能选择模型。
 
-### Prompt 与工程编辑边界
+### 提示词与工程编辑边界
 
-`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题契约公开的默认值，否则通过未回答问题快速失败；预填值通常会让流程根本不调用该 port。
+`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题约定公开的默认值，否则会因问题未回答而失败；预填值通常会让流程根本不调用该 port。
 
 两条路径使用相同的 `Question` 对象、`FeatureConfigurator`、`SdkProject` 和 `ProjectEditSession`。因此，headless 路径只改变答案的到达方式，不改变功能解释或文件提交方式。
 
-### Agent skill
+### agent skill（智能体技能）
 
-仓库提供一份轻量 `SKILL.md`，指导 agent skill（智能体技能）构造结构化输入、请求 NDJSON、补充 `action-required` 指明的值并重试。该 skill 调用公开 CLI，不导入 SDK 内部 API，也不引入另一套工程规格。
+仓库提供一份轻量 `SKILL.md`，指导 agent skill 构造结构化输入、请求 NDJSON、补充 `action-required` 指明的值并重试。该 skill 调用公开 CLI（命令行界面），不导入 SDK 内部 API，也不引入另一套工程规格。
 
 ## 外部 Cordis 插件安装
 
 `dsh-sdk create <source>` 接受包管理器原生的 npm package specifier，例如 `pkg@version`，也接受 `github:owner/repo#ref` 等 GitHub package specifier。用户确认后，命令要求工程包管理器添加来源，对比操作前后的直接依赖名，重新打开工程，再通过 `ProjectEditSession` 把每个新增且已解析的包挂载进 `cordis.yml`。
 
-包管理器负责来源解析、版本或 commit 解析、`integrity` 数据、lockfile 更新和构建策略。SDK 不再通过 giget 或 pacote 下载、解压第二份副本。外部插件是 `node_modules` 下的依赖；本地插件脚手架仍属于独立的工程创建问题。
+包管理器负责来源解析、版本或 commit 解析、`integrity` 数据、lockfile 更新和构建策略。SDK 不会通过 giget 或 pacote 下载、解压第二份副本。外部插件是 `node_modules` 下的依赖；本地插件脚手架仍属于独立的工程创建问题。
 
 本提案只涉及开发者自有 SDK 工程的依赖。独立应用的仓库缓存、随应用捆绑 pnpm 的政策和显式的准备流程信任边界，均由[包管理器原生仓库缓存](../../implemented/architecture/2026-07-30-package-manager-native-repository-cache.md)负责。
 
@@ -78,43 +78,43 @@ Create 和 config 测试向现有工作流注入 `PromptPort` 和脚本化输入
 
 ## 曾考虑的替代方案
 
-**另建 headless 创建引擎。** 该方案会复制问题、功能依赖、配置行为和工程编辑规则。复用提示词与编辑会话边界，可以保证工程语义只有一份实现。
+**另建 headless 创建引擎。**该方案会复制问题、功能依赖、配置行为和工程编辑规则。复用提示词与编辑会话边界，可以保证工程语义只有一份实现。
 
-**把规格文件作为主要自动化接口。** Agent 可以内联传入相同的类型化 JSON 对象，人和 CI 仍可选用文件。文件专用协议会增加持久化与清理工作，却不增加语义。
+**把规格文件作为主要自动化接口。**Agent 可以内联传入相同的类型化 JSON 对象，人和 CI 仍可选用文件。文件专用协议会增加持久化与清理工作，却不增加语义。
 
-**使用 `npx skills add` 创建工程。** Skills CLI 只安装 Markdown skill，不创建 SDK 工程，也不安装 npm 包。因此，agent skill 驱动 SDK 初始化命令，而不是取代它。
+**使用 `npx skills add` 创建工程。**Skills CLI 只安装 Markdown skill，不创建 SDK 工程，也不安装 npm 包。因此，agent skill 驱动 SDK 初始化命令，而不是取代它。
 
-**通过 giget 或 pacote 获取 GitHub 与 npm 来源。** 第二套获取层会复制包管理器的解析、完整性、lockfile 和生命周期策略。原生 package specifier 让这些决策留在所选包管理器中。
+**通过 giget 或 pacote 获取 GitHub 与 npm 来源。**第二套获取层会复制包管理器的解析、完整性、lockfile 和生命周期策略。原生 package specifier 让这些决策留在所选包管理器中。
 
-**把遥测实现成 Cordis 运行时插件。** Create 和 build 不一定启动 Cordis，因此运行时插件无法观察完整的开发命令周期。Launcher 是这些命令共用的边界。
+**把遥测实现成 Cordis 运行时插件。**Create 和 build 不一定启动 Cordis，因此运行时插件无法观察完整的开发命令周期。Launcher 是这些命令共用的边界。
 
-**从 git 元数据派生匿名标识符。** 仓库的 git remote 可能识别工程或组织。随机的用户级标识符能够支持聚合，同时不编码仓库身份。
+**从 git 元数据派生匿名标识符。**仓库的 git remote 可能识别工程或组织。随机的用户级标识符能够支持聚合，同时不编码仓库身份。
 
-**只采集聚合计数。** 仅聚合事件可以降低暴露，但无法回答开发者实际使用哪些插件、依赖和配置形状。本提案接受采集脱敏后的工程文本，并明确记录这项暴露。
+**只采集聚合计数。**仅聚合事件可以降低暴露，但无法回答开发者实际使用哪些插件、依赖和配置形状。本提案接受采集脱敏后的工程文本，并明确记录这项暴露。
 
-**把真实 PTY 和 transcript（文本记录）快照作为主要测试策略。** 原生 PTY 依赖与终端重绘序列会带来平台和渲染不稳定性，而且主要是在测试 clack。注入交互并断言生成文件，可以直接测试 SDK 拥有的行为。
+**把真实 PTY 和 transcript（文本记录）快照作为主要测试策略。**原生 PTY 依赖与终端重绘序列会带来平台和渲染不稳定性，而且主要是在测试 clack。注入交互并断言生成文件，可以直接测试 SDK 拥有的行为。
 
 ## 验收标准
 
 - Create 能依据完整结构化输入在没有 TTY 时运行；使用 `--json` 时 stdout 只输出 NDJSON；缺少必答输入时通过 `action-required` 报告，且不写入部分工程。
-- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划契约。
-- `dsh-sdk create <source>` 使用工程选定的包管理器，挂载该操作实际新增的依赖名；无法识别新增依赖时快速失败。
+- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划约定。
+- `dsh-sdk create <source>` 使用工程选定的包管理器，挂载该操作实际新增的依赖名；无法识别新增依赖时明确报错。
 - 初始化命令与每个 `dsh-sdk` 命令都进入同一条尽力而为的遥测收尾路径；明确禁用的配置项、`DO_NOT_TRACK` 或 CI 会阻止传输，遥测失败绝不改变命令结果。
 - 遥测绝不读取 `.env`；没有 `cordis.yml` 时不发送无关的 `package.json` 内容；两个符合条件的文本都经过脱敏；匿名标识符与 git 元数据无关。
 - 交互测试通过注入交互覆盖 create 和 config 决策，并断言已提交的工程文件；真实 PTY 覆盖只作为窄范围冒烟层。
-- Agent skill 说明公开的结构化输入与事件契约，不依赖包的私有导出。
+- Agent skill 说明公开的结构化输入与事件约定，不依赖包的私有导出。
 
 ## 风险
 
 - 即使经过脱敏，完整的 `cordis.yml` 与 `package.json` 文本仍会向 endpoint 运营方暴露插件名、依赖名、URL、路径和配置值；启发式脱敏也可能漏掉 secret。
 - 没有遥测配置项时默认上报可能让开发者意外；发布前 CLI 必须让关闭方法易于发现。
-- 在 `ProjectEditSession` 挂载插件前，包管理器的 add 操作已经可能修改 `package.json`、lockfile 和安装文件；后续挂载失败会留下需要手工恢复的依赖改动。
+- 在 `ProjectEditSession` 挂载插件前，包管理器的 add 操作已经可能修改 `package.json`、lockfile 和安装文件；后续挂载失败可能留下需要手工恢复的依赖改动。
 - GitHub 依赖可能按包管理器策略执行 preparation 或 lifecycle script；尚未解决的构建策略会带来供应链与可复现性风险。
-- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余契约。
+- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余约定。
 
 ## 参考资料
 
 - [Vercel Eve](https://github.com/vercel/eve) 与 [Vercel Labs Skills](https://github.com/vercel-labs/skills) 用于区分 headless 初始化命令与 skill 分发。
-- [npm package specifications](https://docs.npmjs.com/cli/v11/using-npm/package-spec)、[pnpm add](https://pnpm.io/cli/add)和 [Yarn add](https://yarnpkg.com/cli/add)说明包管理器原生来源。
-- [`DO_NOT_TRACK`](https://donottrack.sh/)定义环境级关闭约定。
+- [npm package specifications](https://docs.npmjs.com/cli/v11/using-npm/package-spec)、[pnpm add](https://pnpm.io/cli/add) 和 [Yarn add](https://yarnpkg.com/cli/add)说明包管理器原生来源。
+- [`DO_NOT_TRACK`](https://donottrack.sh/) 定义环境级关闭约定。
 - [Clack](https://github.com/bombshell-dev/clack) 和 [Vitest snapshots](https://vitest.dev/guide/snapshot) 说明注入提示词交互与生成文件断言。
diff --git a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml
index fa7ea8e141..f364456257 100644
--- a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md
 2026-08-01-windows-pwsh-default.md: 1c3ccef23bb5cd9bc37237bd69aac2e2c56649a8
-2026-08-01-windows-pwsh-default.zh.md: 3958d21eb8a9d306009b11d6e9806a1654a8958e
+2026-08-01-windows-pwsh-default.zh.md: d9fcc50a36a86b356fdf8507f53226d87dddc7bc
diff --git a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
index 3958d21eb8..d9fcc50a36 100644
--- a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
+++ b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
@@ -6,14 +6,14 @@ Status: proposed
 
 ## 问题
 
-harness 交付的执行画像在每个平台都是 bash 优先。Windows 主机必须安装 bash 垫片（WSL 或 Git-Bash），或退回到仅 POSIX 的 `dsh-bash-local` 行为；面向模型的 bash 工具教的是 bash 方言，TUI/Web 表面以 bash 形状的预期渲染终端输出。第一块 Windows 原生基础已随 [pwsh 执行器与工具决策](../../implemented/feature/2026-08-01-pwsh-tool-and-executor.md) 交付：`ctx.bash` seam 的 PowerShell 实现与对等的 `pwsh` 工具——但还没有任何东西让 Windows 主机默认使用它们。
+harness 交付的执行配置在每个平台都是 bash 优先。Windows 主机必须安装 bash 垫片（WSL 或 Git-Bash），或退回到仅 POSIX 的 `dsh-bash-local` 行为；面向模型的 bash 工具教的是 bash 方言，TUI/Web 界面按照 bash 风格的预期渲染终端输出。第一块 Windows 原生基础已随 [pwsh 执行器与工具决策](../../implemented/feature/2026-08-01-pwsh-tool-and-executor.md) 交付：`ctx.bash` seam 的 PowerShell 实现与对等的 `pwsh` 工具——但还没有任何东西让 Windows 主机默认使用它们。
 
 ## 提案
 
-两个阶段，各自可独立交付。原阶段 2（bash 工具对等孪生）已随 [pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 交付：`tool-pwsh` 现在在前台与后台工作（减 sandbox 面）上镜像 `tool-bash`，通过 `dsh-bash-env` 共享 `DSH_*` 环境，并携带其组装表面的 keyless 应用快照。
+两个阶段，各自可独立交付。原阶段 2（bash 工具对等孪生）已随 [pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 交付：`tool-pwsh` 现在除 sandbox 接口外，在前台与后台工作方面均与 `tool-bash` 对齐，通过 `dsh-bash-env` 共享 `DSH_*` 环境，并携带其组装后形态的 keyless 应用快照。
 
-1. **Windows 默认组合**——交付的 CLI 组合在 Windows 主机上挂载 `dsh-pwsh-local` 作为 `ctx.bash` 执行器、`dsh-tool-pwsh` 作为面向模型的 shell 工具（那里不挂载 bash），POSIX 主机保持 bash 栈。这是 `base.cordis.yml` 与 surface 覆盖层里按平台门控的组合/清单决策；它让交付的 Windows 体验端到端 PowerShell 原生。
-2. **pwsh GUI 渲染**——Web 表面以 bash 形状的终端呈现渲染 pwsh 调用（带退出状态 pill 的 terminal 卡），即 bash 终端卡片的对应物。已随 [pwsh UI 呈现与 bash 对齐决策](../../implemented/feature/2026-08-05-pwsh-ui-bash-parity.md) 及 keyless web 通道交付；TUI 已移除，不再有终端孪生。超出 bash 对齐的 PowerShell 感知呈现（原生路径显示、`$env:` 实情）仍无人认领。
+1. **Windows 默认组合**——交付的 CLI（命令行界面）组合在 Windows 主机上挂载 `dsh-pwsh-local` 作为 `ctx.bash` 执行器、`dsh-tool-pwsh` 作为面向模型的 shell 工具（那里不挂载 bash），POSIX 主机保持 bash 栈。这是 `base.cordis.yml` 与 surface 覆盖层里按平台门控的组合/清单决策；它让交付的 Windows 体验端到端 PowerShell 原生。
+2. **pwsh GUI 渲染**——Web 界面使用 bash 风格的终端呈现来渲染 pwsh 调用（带胶囊状退出状态标签的终端卡片），与 bash 终端卡片相对应。已随 [pwsh UI 呈现与 bash 对齐决策](../../implemented/feature/2026-08-05-pwsh-ui-bash-parity.md) 及 keyless web 通道交付；TUI 已移除，不再有对应的终端界面。超出 bash 对齐的 PowerShell 感知呈现（原生路径显示、`$env:` 信息）仍无人认领。
 
 各阶段仅在有依赖关系时排序：渲染阶段已随 [pwsh UI 呈现与 bash 对齐决策](../../implemented/feature/2026-08-05-pwsh-ui-bash-parity.md) 先行交付（平台无关，其 keyless web 通道可在任意宿主运行），而 Windows 默认组合仍是唯一未交付的阶段。本提案不改变任何 POSIX 行为。
 
@@ -21,7 +21,7 @@ harness 交付的执行画像在每个平台都是 bash 优先。Windows 主机
 
 **在 `dsh-bash-local` 内部让 Windows 默认 pwsh（一个执行器，方言开关）。** 否决，理由与执行器决策否决模式开关相同：执行器的身份就是它 spawn 的 shell，而按平台门控的组合是部署选择，不是执行器配置。
 
-**把 Windows 默认与执行器/工具一起交付。** 否决：清单变更需要自己的证据（交付的 Windows 树停挂 bash 后什么会坏、哪些工具依赖 bash 语义），并且它属于带批准/PTY 表面可见的组合决策。
+**把 Windows 默认与执行器/工具一起交付。** 否决：清单变更需要自己的证据（交付的 Windows 树停挂 bash 后什么会坏、哪些工具依赖 bash 语义），并且它属于会在审批／PTY 界面上显现的组合决策。
 
 **用垫片在 Windows 上保留 bash，跳过 PowerShell 默认。** 否决：这延续了安装税与路线图要消除的方言错配；垫片是部署要求，不是产品行为。
 
@@ -30,10 +30,10 @@ harness 交付的执行画像在每个平台都是 bash 优先。Windows 主机
 - 运行交付版 `dsh` TUI/Web 的 Windows 主机无需配置即获得 `pwsh` 作为其 shell 工具、PowerShell 作为 `ctx.bash` 执行器，且那里的模型可见清单中没有 `bash`。
 - POSIX 主机逐字节不受影响（清单相同，执行器相同）。
 - 交付组合 e2e 在两个平台族上断言按平台门控的清单。
-- 阶段 1 落地时，parity 变更带来的 keyless pwsh 工具快照已经就位；阶段 2 已随 web `pwsh-terminal` 渲染通道落地（TUI 的移除让终端表面无快照可做）。
+- 阶段 1 落地时，parity 变更带来的 keyless pwsh 工具快照已经就位；阶段 2 已随 web `pwsh-terminal` 渲染通道落地（TUI 的移除意味着不再有可供快照测试的终端界面）。
 
 ## 风险
 
-- **依赖 bash 的组合行**——任何假设 bash 语义的交付插件（执行 shell hooks 的 hooks 桥、工作区工具）必须按阶段审计；审计可能迫使分阶段推出而非一次切换。
-- **Windows CI 覆盖缺口**——单元覆盖在 Linux 上运行；pwsh 栈里仅 Windows 的回归通过 Windows 构建/静态通道与 e2e 浮出，必须按阶段扩展而不是想当然。
-- **渲染约定**——bash 形状的终端孪生已随 web 通道交付；超出 bash 对齐的 PowerShell 感知呈现（原生路径显示、`$env:` 实情）仍是带快照表面的 UI 设计决策，随阶段 1 一起延期。
+- **依赖 bash 的组合行**——任何假设 bash 语义的交付插件（执行 shell 钩子的钩子桥接、工作区工具）必须按阶段审计；审计可能迫使分阶段推出而非一次切换。
+- **Windows CI 覆盖缺口**——单元覆盖在 Linux 上运行；pwsh 栈里仅 Windows 的回归通过 Windows 构建/静态通道与 e2e 暴露出来；这些覆盖必须按阶段扩展，不能想当然地认为已经具备。
+- **渲染约定**——与 bash 风格一致的终端呈现已随 web 通道交付；超出 bash 对齐的 PowerShell 感知呈现（原生路径显示、`$env:` 信息）仍是一项需要快照覆盖的 UI 设计决策，随阶段 1 一起延期。
diff --git a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
index 5418a920e5..c0a2063391 100644
--- a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.md
 2026-08-04-artifact-first-npm-baseline-publication.md: e79a988531ac266d72f7d2c036bdd10f3e4520a9
-2026-08-04-artifact-first-npm-baseline-publication.zh.md: d7322547c665700aeffce77ea0bb39f622220fe3
+2026-08-04-artifact-first-npm-baseline-publication.zh.md: e071704741fed58e83325bbc2765fe248ef113c7
diff --git a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
index d7322547c6..e071704741 100644
--- a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
+++ b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
@@ -23,7 +23,7 @@ monorepo 中可运行的源码并不能证明发布后的包可运行。workspac
 pack 阶段按以下顺序执行：
 
 1. 将 ref 解析成不可变 commit，采集 UTC 时间戳，从该 commit 的根 manifest 派生版本，并显示 commit、时间戳、版本、tag、注册表和输出路径。`pack` 与 `release` 此时都会在昂贵操作开始前等待 Enter；自动化可用 `--yes` 跳过该确认。
-2. 在隔离的 detached worktree 中安装 frozen lockfile，并在暂存发布 manifest 之前运行源码 manifest 发布约束；调用方工作树中的未提交文件和旧构建输出不得参与发布。
+2. 在隔离的 detached worktree 中安装 frozen lockfile，并在暂存前运行源码 manifest 发布约束；调用方工作树中的未提交文件和旧构建输出不得参与发布。
 3. 将所有目标 manifest 暂存为派生版本，移除发布时的 `private` 标记，并把 `dependencies`、`devDependencies`、`optionalDependencies` 与 `peerDependencies` 中的内部 workspace 依赖全部改写为同一精确版本。
 4. 完整构建目标 commit，再运行 publint 和已构建包不变式。
 5. 为目标集合中的每个包执行 pack，但不执行任何注册表写入。
@@ -38,13 +38,13 @@ pack 阶段按以下顺序执行：
 
 已提交的 pack 命令实现了固定 commit 暂存、内部依赖精确固化、静态与 tarball payload 检查、不可变 manifest，以及把每个发布 tarball 都作为本地顶层依赖的隔离 npm 安装。它在输出 publish 命令前，用普通 Node 运行安装后的 `dsh --version` 与 `dsh --dump-default-config` 入口，再在 POSIX PTY 中启动安装后的默认 TUI，等待其 `main-session-` 就绪信号，并通过 `/exit` 退出。Publish 支持按 integrity 恢复，将只读注册表验证与认证身份检查分离，并以完整的远端 integrity 和 dist-tag 验证结束。
 
-拉取请求 CI 不会调用 pack 命令；安装态入口探测属于本地发布检查，而不是合并门禁。免凭据 CI 执行、其他每个 bin 与公开运行时入口的包自有探测、workflow artifact 传递及受保护 publish job 仍属于提案范围。
+PR（Pull Request） CI 不会调用 pack 命令；安装态入口探测属于本地发布检查，而不是合并门禁。免凭据 CI 执行、其他每个 bin 与公开运行时入口的包自有探测、workflow artifact 传递及受保护 publish job 仍属于提案范围。
 
-## 发布 payload 契约
+## 发布 payload 约定
 
 发布包只携带消费方需要的构建产物。`package.json#files` 禁止包含 `src` 和 `lib/types/**/*.d.ts.map`；tarball 内容门禁还要独立确认不存在任何 `package/src/**` 与 `package/**/*.d.ts.map`，避免 manifest pattern 或 pack 行为绕过静态约束。运行时 JS、声明文件 `.d.ts`、配置、资源、worker 文件和 bundle 动态 chunk 必须按实际入口闭包收齐。
 
-源码 manifest 可以保留 `exports["./src/*"]`，供本仓库的源码平面解析使用；该 export 不代表源码会进入发布 payload，也不属于已发布包的消费方契约。静态门禁必须分别检查源码平面与发布 payload，不能通过删除 source export 来掩盖错误的 workspace 解析，也不能通过发布 `src` 来修补缺失的构建产物。
+源码 manifest 可以保留 `exports["./src/*"]`，供本仓库的源码平面解析使用；该 export 不代表源码会进入发布 payload，也不属于已发布包的消费方约定。静态门禁必须分别检查源码平面与发布 payload，不能通过删除 source export 来掩盖错误的 workspace 解析，也不能通过发布 `src` 来修补缺失的构建产物。
 
 每个 tarball 必须不含 `workspace:` specifier，并且所有指向本次发布集合的内部依赖与对等依赖（peer dependency）都必须精确等于本次派生版本，禁止使用 `^`、`~` 或其他 semver 范围跨越 commit 基线。除了明确仅供源码平面使用的 `exports["./src/*"]`，package manifest 中声明的每个消费方入口都必须指向 tarball 内存在的文件；动态 import、运行时拼接路径和非 export 资源不能只靠 manifest 检查，必须由安装后执行覆盖。
 
@@ -52,7 +52,7 @@ pack 阶段按以下顺序执行：
 
 集成测试在全部 tarball 生成后、任何 publish 之前运行。它在 monorepo 外创建一个全新临时项目，通过本次 release manifest 中的本地 `.tgz` 文件安装声明依赖闭包，并从安装目录执行。测试必须使用普通 Node 与包管理器生成的 `node_modules`；禁止 tsx、tsconfig paths、workspace link、仓库源码路径、工作树 `lib/` 和已发布注册表中的同版本包参与解析。测试还要断言关键模块与 bin 的真实路径位于临时消费方内。
 
-安装使用本次发布选择的客户端行为。注册表上传必须使用 `npm` CLI，以满足私有注册表只接受 npm 客户端的策略；构建编排仍可使用 pnpm。tarball 测试不得先把这些包发布到真实注册表，也不得在测试后重新 pack。
+安装使用本次发布选择的客户端行为。注册表上传必须使用 `npm` CLI（命令行界面），以满足私有注册表只接受 npm 客户端的策略；构建编排仍可使用 pnpm。tarball 测试不得先把这些包发布到真实注册表，也不得在测试后重新 pack。
 
 测试至少覆盖以下执行面：
 
@@ -73,13 +73,13 @@ npm 不提供多包原子事务，上传仍会逐包发生。编排器通过幂
 
 ## GitHub Actions 集成
 
-GitHub Actions 分为无凭据的 pack-and-test job 与受保护的 publish job。前者检出精确 commit，调用与本地相同的 pack 入口，运行 tarball 消费方测试，并上传完整 release bundle 作为 workflow artifact。后者依赖前者成功，从 workflow artifact 下载 bundle、重新校验 manifest 和校验和，再调用同一个 publish 入口；它不能检出后重新构建。
+GitHub Actions 分为无凭据的 pack-and-test job 与受保护的 publish job。前者检出精确 commit，调用与本地相同的 pack 入口，运行 tarball 消费方测试，并上传完整 release bundle 作为工作流产物。后者依赖前者成功，从工作流产物下载 bundle、重新校验 manifest 和校验和，再调用同一个 publish 入口；它不能检出后重新构建。
 
 PR 与普通 push 可以运行无凭据的 pack-and-test 信号，从而在合并前发现 payload 回归。实际私有注册表发布先通过 `workflow_dispatch` 提供，输入只包括目标 ref；UTC 时间戳由 pack job 生成，基础版本、短 SHA、tag、注册表和包清单都由仓库状态或受版本控制的配置派生。稳定发布触发方式不在本基线提案范围内。
 
-注册表 token 只注入 publish job，并由受保护 GitHub Environment 控制人工批准、允许的分支或 tag 以及并发。pack-and-test job 不得读取发布凭据。workflow artifact 的保留期可以较短，但 publish job 必须使用同一 workflow run 生成的 bundle，不能按版本号从不受信任的位置寻找 tarball。
+注册表 token 只注入 publish job，并由受保护 GitHub Environment 控制人工批准、允许的分支或 tag 以及并发。pack-and-test job 不得读取发布凭据。工作流产物的保留期可以较短，但 publish job 必须使用同一 workflow run 生成的 bundle，不能按版本号从不受信任的位置寻找 tarball。
 
-## Alternatives considered
+## 考虑过的替代方案
 
 **从 workspace 直接递归 publish。** 不采用，因为命令会把 pack 与注册表写入交错，无法在第一次写入前证明整个集合完整，也容易让 workspace 解析与调用方工作树状态影响发布结果。
 
@@ -87,13 +87,13 @@ PR 与普通 push 可以运行无凭据的 pack-and-test 信号，从而在合
 
 **只运行 `dsh --help`。** 不采用，因为 Commander 可以在加载 TUI、Web 或 headless 动态入口之前输出帮助并退出。它无法证明默认生产启动路径完整。
 
-**把 `src` 和声明映射一起发布以降低漏文件风险。** 不采用，因为源码平面不是生产运行时的后备路径；扩大 payload 会掩盖 bundle 闭包错误，并把本地调试产物变成无意的发布契约。
+**把 `src` 和声明映射一起发布以降低漏文件风险。** 不采用，因为源码平面不是生产运行时的后备路径；扩大 payload 会掩盖 bundle 闭包错误，并把本地调试产物变成无意的发布约定。
 
 **要求真正的跨包原子发布。** 不采用，因为 npm 注册表没有相应事务。不可变 release bundle、发布前全量验证、integrity 比对与幂等恢复提供可实现的边界，同时明确保留部分上传短暂可见的限制。
 
-**在批准后由发布 job 重新构建。** 不采用，因为测试通过的 tarball 与实际上传的 tarball 将不再具有内容身份。workflow artifact 与校验和必须把测试输入直接传给发布步骤。
+**在批准后由发布 job 重新构建。** 不采用，因为测试通过的 tarball 与实际上传的 tarball 将不再具有内容身份。工作流产物与校验和必须把测试输入直接传给发布步骤。
 
-## Acceptance criteria
+## 验收标准
 
 - 一个 pack 入口从确定 commit 发现 `packages/*/*` 和 `apps/*` 的全部目标包，以 UTC 秒级时间戳与短 commit 生成并显示版本，再等待 Enter；它在任何注册表写入前生成完整 release bundle，并输出一个可复制的 publish 命令；`release` 在 pack 后再次等待，`--yes` 跳过两次确认。
 - 静态 manifest 门禁和 tarball 内容门禁都拒绝发布 `src` 与 `.d.ts.map`，同时保留源码 manifest 中的 `exports["./src/*"]`。
@@ -103,9 +103,9 @@ PR 与普通 push 可以运行无凭据的 pack-and-test 信号，从而在合
 - publish 可在部分成功后用同一 manifest 安全重跑；相同 integrity 被跳过，不同 integrity 被拒绝，最终验证要求所有版本与 tag 一致。
 - GitHub Actions 的无凭据 job 生成并测试 bundle，受保护 job 上传完全相同的 bundle，发布 token 只存在于后者。
 
-## Risks
+## 风险
 
-全量 pack、安装和启动会增加 CI 时间与 workflow artifact 体积。实现应缓存外部依赖和 pnpm store，但不得缓存或复用目标包的已安装 workspace 输出；并行执行安全的消费方 probe 可以降低时延。
+全量 pack、安装和启动会增加 CI 时间与工作流产物体积。实现应缓存外部依赖和 pnpm store，但不得缓存或复用目标包的已安装 workspace 输出；并行执行安全的消费方 probe 可以降低时延。
 
 把所有 tarball 都安装为临时项目的顶层依赖可能掩盖未声明的内部依赖。测试生成器应按被测应用的声明式递归闭包安装，并结合现有依赖门禁；对依赖面接近全集的 `@deepseek-ai/dsh`，仍需依靠 package manifest 与静态图检查发现未声明边。
 
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
index 0f5dedddd2..4a13087f8e 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
 2026-07-26-dependency-swaps-rejected-by-nih-audit.md: 538f6a41b4d2db72f867e98810e8e9382cbdac98
-2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: b3f7a1d9717397ee9ed50890bc024fba7d79fa9a
+2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: a625c6eb2253098da3f20cd07523c926add4b32d
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
index b3f7a1d971..a625c6eb22 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
@@ -6,7 +6,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 
 ## 问题
 
-一次仓库级的「Not Invented Here（非我发明）」审计（2026-07-26，十路并行普查，覆盖每个包（package）分组、scripts/、native/、vendor/ 边界、python/、测试基础设施与 CI）对每一处手写接口面追问同一个问题：在[依赖政策](../../implemented/process/2026-07-26-dependencies-over-hand-rolling.md)之下，是否有持续维护的外部包或 Node 内置能力能以净收益把它删除？得出肯定结论的发现已各自写成独立的提案 Agent Note（agent 决策记录）。否定裁定的价值不相上下——每一条都点名了一个看似可行、实则手写形态在承重的替换——但否则它们只会留存在某个 PR（Pull Request）正文里。本 note 将它们固化在案。
+一次仓库级的「Not Invented Here（非我发明）」审计（2026-07-26，十路并行普查，覆盖每个包分组、scripts/、native/、vendor/ 边界、python/、测试基础设施与 CI）对每一处手写接口面追问同一个问题：在[依赖政策](../../implemented/process/2026-07-26-dependencies-over-hand-rolling.md)之下，是否有持续维护的外部包或 Node 内置能力能以净收益把它删除？得出肯定结论的发现已各自写成独立的提案 Agent Note。否定裁定的价值不相上下——每一条都点名了一个看似可行、实则手写形态在承重的替换——但否则它们只会留存在某个 PR（Pull Request）正文里。本 Agent Note 将它们固化在案。
 
 ## 提案
 
@@ -24,7 +24,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 
 - **以 `p-retry`/`exponential-backoff` 替换 `llm-retry`**：执行模型不对——该插件是一个返回决策的 waterfall（瀑布式事件）监听器，重新执行由 agent loop（智能体循环）依据持久日志负责；根本不存在可供重新调用的函数，而那恰是这些库的全部 API。提供方 `Retry-After` 覆写、依据先前失败代码计算预算、持久化的 `llm/retry` 事件、HMR（热模块替换）完全停稳式中止，全都无从覆盖。[LLM（大语言模型）请求受限恢复决策](../../implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)已经否决了由 SDK 持有的重试。
 - **以 `p-timeout`/`AbortSignal.timeout` 替换 `dsh-timeout`**：内置能力无法提前解除，抛出的是通用 `TimeoutError`，而不是能区分嵌套截止时限、按能力编码的 `TimeoutReason`；`idleWatchdog` 按需逐次重新装定的能力没有等价物。设计归[超时库决策](../../implemented/architecture/2026-07-06-timeout-deadline-library.md)所有。
-- **以 `p-limit`/`p-queue` 替换 agent-loop 的工具调用池**：池的簿记只有约 25 行；实质部分（按模型顺序提交、组中途重新分类、排他屏障、带合成持久结果的中止排空）根本不是并发限制器的形状。
+- **以 `p-limit`/`p-queue` 替换 agent loop 的工具调用池**：池的簿记只有约 25 行；实质部分（按模型顺序提交、组中途重新分类、排他屏障、带合成持久结果的中止排空）根本不是并发限制器的形状。
 - **以 `p-queue`/`async-mutex` 替换按 key 的 promise 链串行器**（`fs-local`、`storage-domain`）：串行器只有 8–14 行；这些包严格大于它们所能删除的代码。
 - **以 `events.once` + `AbortSignal.timeout` 替换 subagent-subprocess 的 `exitsWithin`**：`error` 先触发时 `events.once` 会 reject，而手写实现有意忽略 `error`（由 spawn 失败路径单独捕获）；这次替换恰恰会在语义本身就是拆除竞态的那段代码里改变拆除竞态行为。
 
@@ -35,7 +35,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `fast-deep-equal` 替换会话接口面的 `isDeepEqualJson`**、**以 `safe-stable-stringify` 承担 repeat-tool-guard 的规范化**：两项替换在机械层面都可行，但每一项都是拿约 17–20 行带注释、有测试的代码，去换一个核心包的第一个外部运行时依赖——在这个体量上是净亏损。
 - **以 zod/valibot 承担持久事件的严格解码器**（goal fold、tool-ralph、session）：它们是位于持久化边界、键集精确匹配、失败即大声报错、带事件专属报错信息的解码器；在仓库标准 schemastery 之外再放一个 schema 库是政策变更，不是删除。
 - **以 `gpt-tokenizer`/tiktoken 替换 token-meter**：[回放 token 计量决策](../../implemented/architecture/2026-07-15-replay-token-meter-service.md)已明确否决分词器后端；GPT 的 BPE 对 DeepSeek 模型来说也是错误的分词器，而且这个包约 350 行是回放折叠簿记，任何分词器都覆盖不了。
-- **以 `partial-json` 处理流式工具调用参数**：无可替换——按已记录的契约，参数端到端保持为原始 JSON 字符串；`JSON.parse` 只在完整载荷上运行。
+- **以 `partial-json` 处理流式工具调用参数**：无可替换——按已记录的约定，参数端到端保持为原始 JSON 字符串；`JSON.parse` 只在完整载荷上运行。
 
 **文件系统、子进程与终端：**
 
@@ -46,14 +46,14 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `shell-quote` 承担 POSIX 单引号包裹**：两个各 1 行、测试详尽的引号辅助函数，对上一个处于维护模式、有 CVE 历史、转义输出还不一样的包——安全边界不是省一行代码的地方。
 - **以 `strip-ansi` 承担 pty 净化**：pty 净化器是一台流式状态机，带跨分片的断裂序列续接和 OSC `133;D` 提示符标记提取（shell 就绪信号）；无状态的剥离器只能替掉约 20 行内层代码，全部状态机构件原样保留。`stripVTControlCharacters` 还被实证会泄漏未终止的 OSC 载荷，会话标题归一化器必须剥除它们（反欺骗）。
 - **以 `pidtree`/`ps-tree` 承担 pty 进程巡检器**：它们只给裸 PID 树；这段代码需要对抗 PID 复用的启动时间身份校验，加上 `/proc` stdin 等待检测，没有包做这些。
-- **以 `execa` 承担 subagent-subprocess 的 dispose（资源释放）阶梯**：`forceKillAfterDelay` 覆盖 SIGTERM→SIGKILL，但覆盖不了先发 stdin EOF 的协作层级，也覆盖不了「无退出沿即 reject」契约；在这里采用它意味着重写各 spawn 调用点、同时阶梯照旧保留。（测试基础设施的 spawn 管线是另一回事——见[已归档的 execa 测试基础设施决策](../../archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md)。）
+- **以 `execa` 承担 subagent-subprocess 的 dispose（资源释放）阶梯**：`forceKillAfterDelay` 覆盖 SIGTERM→SIGKILL，但覆盖不了先发 stdin EOF 的协作层级，也覆盖不了「无退出沿即 reject」约定；在这里采用它意味着重写各 spawn 调用点、同时阶梯照旧保留。（测试基础设施的 spawn 管线是另一回事——见[已归档的 execa 测试基础设施决策](../../archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md)。）
 - **以 `tree-kill` 承担 acp-snapshot 拆除与 lsp 进程终止**：那些代码行做的是排空顺序与错误传播，不是进程树遍历；lsp/bash 已经使用分离的进程组加 taskkill。
 - **在 TUI 测试驱动器上到处使用 node-pty**：已归档的 [Windows TUI 决策](../../archived/feature/2026-07-20-windows-tui-support.md)明确否决了在每个宿主上都使用 node-pty；它当时已经是 Windows 那一条腿。
 
 **服务器与 HTTP：**
 
 - **以 `msw` 替换 llm-mock-server**：这个服务器的存在意义就是在线路上制造故障——socket 销毁、SSE（Server-Sent Events）中途断连、停滞、监听前拒绝——服务对象是真实的 HTTP 适配器和子进程；进程内拦截一样都表达不了。设计归[线路故障服务器决策](../../implemented/testing/2026-07-25-scriptable-llm-wire-fault-server.md)所有。
-- **以 `hono`/`sirv` 承担 host/webserver**：核心是基于 disposer 的动态路由注册表（「注册即效果」契约、HMR 反注册）加 index HTML 变换挂点；hono 的路由器只增不减，静态中间件也无法伺服变换后的 index。总共约 244 行，确实很小。
+- **以 `hono`/`sirv` 承担 host/webserver**：核心是基于 disposer 的动态路由注册表（「注册即效果」约定、HMR 反注册）加 index HTML 变换挂点；hono 的路由器只增不减，静态中间件也无法伺服变换后的 index。总共约 244 行，确实很小。
 - **以 `@mozilla/readability`/`iconv-lite` 承担 web-fetch-local**：该提供方返回原始 HTML；字符集处理已经是内置的 `TextDecoder`；MIME 解析约 11 行；重定向跟随是同源安全策略。
 
 **SQLite 与存储：**
@@ -74,5 +74,5 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 ## 曾考虑的替代方案
 
 - **什么都不记录，让 PR 正文承载这些裁定。** 不予采纳：PR 正文不属于受维护的记录，而普查的全部意义就在于下一次审计从这些裁定出发，而不是重新推导。
-- **每一项各写一份 rejected note。** 不予采纳：为共享同一套证据标准、同一种命运的裁定制造约 30 个文件的仪式感；只有当某一项带着新证据被重新提出时，逐项 note 才有必要。
-- **把每条裁定并入拥有该 seam 的 implemented note。** 部分已做——凡是持有方 note 已经否决过该替代方案的（重试、token 计量、schema DSL、zstd、沙箱、node-pty），本 note 一律援引而不重复。其余各项没有持有方 note，这正是它们记录于此的原因。
+- **每一项各写一份 rejected note。** 不予采纳：为共享同一套证据标准、同一种命运的裁定制造约 30 个文件的仪式感；只有当某一项带着新证据被重新提出时，逐项 Agent Note 才有必要。
+- **把每条裁定并入拥有该 seam 的 implemented note。** 部分已做——凡是持有方 Agent Note 已经否决过该替代方案的（重试、token 计量、schema DSL、zstd、沙箱、node-pty），本 note 一律援引而不重复。其余各项没有持有方 note，这正是它们记录于此的原因。
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 077f5fa7f2..695f81e459 100644
--- a/README.i18n.yaml
+++ b/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write README.md
 README.md: ff4cf661a060772973629844d43758d26ac1be02
-README.zh.md: 977de7f22244ff49579393edcce66d02c5782de4
+README.zh.md: a11834c590a3930e881447d79bbfeb7a10ee3a92
diff --git a/README.zh.md b/README.zh.md
index 977de7f222..a11834c590 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-DeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。
+DeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（智能体）。
 
 它采用了**一切皆插件**的架构。
 
@@ -49,7 +49,7 @@ dsh plugin --profile tui add <package>  # install a plugin into a custom profile
 dsh --profile tui                       # boot it
 ```
 
-profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。
+profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）约定](apps/cli/README.md#profiles)。
 
 ### Headless
 
@@ -73,7 +73,7 @@ pnpm run demo:acp
 
 内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。
 
-- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。
+- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均为可组合的 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。
 - **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。
 - **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。
 - **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。
diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index 801560e7d7..162ea534b7 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/README.md
 README.md: 12108fcbff4e649d0bcb3e01e688fa334ab91b14
-README.zh.md: 9518feed1d5d40c3e5ec2d346b929118ccc08810
+README.zh.md: 37967973ed40143db0bc747875dbb6dad11d73b4
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 9518feed1d..37967973ed 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -23,4 +23,4 @@ profile 目录包含一个 `package.json`（树外插件依赖，加上 profile
 
 ## 开发
 
-生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析契约。
+生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析约定。
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 325de8db4e..12dbcaaa86 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/reference/README.md
 README.md: e616b420d60e0fa372bf38950207245cb60ced98
-README.zh.md: a65140e6dc9374e21bdd3018bce45432794a7b10
+README.zh.md: 74fa00cbf4dc31f29e0113be500a825520abb553
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index a65140e6dc..74fa00cbf4 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -31,7 +31,7 @@ dsh --profile web --patch ./extra.yml --dump-config
 
 ## 插件管理
 
-`dsh plugin --profile <name> <args...>` 在 profile 缺失时先初始化它（有随附模板的用模板，其他名称只装 `@deepseek-ai/dsh-base`），然后以 profile 目录为工作目录，把 `<args...>` 转发给 `pnpm`：`add`、`remove`、`why`、`update` 及其他所有 pnpm 子命令都照常可用；pnpm 必须在 PATH 上。相对路径 spec（`.`、`../plugin` 及其 `file:`/`link:` 形式）会先锚定到调用目录，因此在插件 checkout 中执行 `add .` 安装的是该 checkout，而不是 profile。每次成功运行后，`dsh.profile.bundles` 都会与已安装状态对齐：每个解析到 manifest 中声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的包的依赖加入层栈（因此让包获得该声明的 `update` 会将其激活），没有组合包声明的依赖保持为普通依赖并给出一次性警告，已移除的依赖则退出层栈。
+`dsh plugin --profile <name> <args...>` 在 profile 缺失时先初始化它（有随附模板的用模板，其他名称只装 `@deepseek-ai/dsh-base`），然后以 profile 目录为工作目录，把 `<args...>` 转发给 `pnpm`：`add`、`remove`、`why`、`update` 及其他所有 pnpm 子命令都照常可用；pnpm 必须在 PATH 上。相对路径 spec（`.`、`../plugin` 及其 `file:`/`link:` 形式）会先锚定到调用目录，因此在插件 checkout 中执行 `add .` 安装的是该 checkout，而不是 profile。每次成功运行后，`dsh.profile.bundles` 都会与已安装状态对齐：解析结果为某个包、且该包的 manifest 中声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的每个依赖都会加入层栈（因此让包获得该声明的 `update` 会将其激活），没有组合包声明的依赖保持为普通依赖并给出一次性警告，已移除的依赖则退出层栈。
 
 ```sh
 dsh plugin --profile tui add github:deepseek-harness/turtle-ui
@@ -51,7 +51,7 @@ dsh web --patch ./extra.cordis.yml
 dsh web --dump-config
 ```
 
-生产 Web 运行器需要已构建的包和前端产物（`pnpm run build`）。默认服务地址是 `http://127.0.0.1:3080`。绑定所有接口时，还会信任机器自动发现的 LAN IP 字面量；`--trusted-host` 可添加 `/api` 浏览器信任围栏接受的具名 authority。
+生产 Web 运行器需要已构建的包和前端产物（`pnpm run build`）。默认服务地址是 `http://127.0.0.1:3080`。绑定所有网络接口时，还会信任机器自动发现的 LAN IP 字面量；`--trusted-host` 可添加 `/api` 浏览器信任围栏接受的具名 authority。
 
 进程关闭时会给插件树最多 5 秒完成 dispose。第一次 `SIGINT`/`SIGTERM` 启动该优雅排空；第二次信号强制立即退出。如果一次性运行正常结束时已经卡在 dispose 中，第一次 `Ctrl+C` 就会升格并立即退出，而不会被吞掉。
 
@@ -61,15 +61,15 @@ dsh web --dump-config
 
 `DSH_TOOLS_MODE` 为进程选择 `native`、`code` 或 `both`；其他值会导致启动失败。[`config/core-web.cordis.yml`](../config/core-web.cordis.yml) 是可选的 RL 兼容 `--patch` overlay：它固定使用 `native` 模式，仅将 `DSH_SYSTEM_PROMPT` 或 `You are a helpful software engineer assistant.` 渲染为系统提示词，禁用 Workspace 指令与所有 Web 运行时提示词贡献，并且在保留随附宿主、浏览器、workspace、持久化和权限组合的同时，仅暴露持久 `bash` 和 `str_replace_editor`。
 
-`DSH_SYSTEM_PROMPT` 会传给系统提示词的 [`persona`](../../../packages/core/system-prompt/README.md#config)：完整的 `{{…}}` 分组遵循该契约的严格变量插值规则，且无法转义为字面花括号；任何已设置的值（包括空字符串）都具有权威性，因此空值会移除系统提示词，只有未设置该变量时才会选择后备值。
+`DSH_SYSTEM_PROMPT` 会传给系统提示词的 [`persona`](../../../packages/core/system-prompt/README.md#config)：完整的 `{{…}}` 分组遵循该约定的严格变量插值规则，且无法转义为字面花括号；任何已设置的值（包括空字符串）都具有权威性，因此空值会移除系统提示词，只有未设置该变量时才会选择后备值。
 
 ## 共享部署行为
 
-基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search`、repository Plugin 支持和会话遥测。提供方凭据依次从继承环境、`$DSH_HOME/.credentials.yaml`、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析；受管文档从不物化进 `process.env`，而两个 `.env` 文件都是普通启动环境层。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`；只有 patch 层插入提供方并启用 `web_fetch` 后，该工具才可用。
+基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search`、repository 插件支持和会话遥测。提供方凭据依次从继承环境、`$DSH_HOME/.credentials.yaml`、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析；受管文档从不物化进 `process.env`，而两个 `.env` 文件都是普通启动环境层。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`；只有 patch 层插入提供方并启用 `web_fetch` 后，该工具才可用。
 
-会话事件默认作为 OTLP/HTTP 日志流式发送。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。任何非空 `DSH_TELEMETRY_DISABLED` 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由[遥测 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)负责。
+会话事件默认作为 OTLP/HTTP 日志流式发送。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。任何非空 `DSH_TELEMETRY_DISABLED` 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由[遥测 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md) 负责。
 
-空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 契约](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
+空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository 插件 generation。参见 [repository 插件约定](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
 
 ## 源码启动器
 
diff --git a/docs/agent-lifecycle.i18n.yaml b/docs/agent-lifecycle.i18n.yaml
new file mode 100644
index 0000000000..c299e9c728
--- /dev/null
+++ b/docs/agent-lifecycle.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 docs/agent-lifecycle.md
+agent-lifecycle.md: 5bf2c4454ce2fac31dfd35218f2bc3c3318b18b6
+agent-lifecycle.zh.md: b7cf8a0e36ee08d52e71e5bc439bcf1815b0a467
diff --git a/docs/agent-lifecycle.zh.md b/docs/agent-lifecycle.zh.md
new file mode 100644
index 0000000000..b7cf8a0e36
--- /dev/null
+++ b/docs/agent-lifecycle.zh.md
@@ -0,0 +1,84 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/agent-lifecycle.md` 重新记录配对。 -->
+
+# Agent 轮次与步骤生命周期
+
+[English](agent-lifecycle.md) | 中文
+
+此时序图是 [architecture.md](architecture.md#loop-lifecycle-session--turn--step) 的配套图示。持久的回放事实保存在 `session/event` 中，实时控制与状态则保存在 `agent/*` 中。
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Driver
+  participant Hooks as hook listeners
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant SDK as UI or SDK listener
+  User->>Agent: followup(content)
+  Agent-->>SDK: <code>agent/inbox/spliced</code>
+  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
+  Agent->>Driver: queued work wakes driver
+  Driver-->>SDK: <code>agent/status</code> running
+  Note over Agent,Driver: claim pending next-step input plus one queued prompt
+  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
+  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+  Driver->>Hooks: <code>agent/pre-step</code> waterfall
+  Hooks-->>Driver: authoritative reject or enter(messages)
+  alt proposed step rejected or pre-step failed
+    Driver-->>Driver: claimed batch stays removed, no turn opens
+  else enter proposed step
+  Driver->>Session: <code>turn/start</code>
+  Driver->>Session: <code>step/start</code>
+  Driver->>Session: <code>user/message</code> per entered message
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
+  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
+  LLM-->>Driver: StreamChunk*
+  Driver->>Session: <code>assistant/chunk</code>*
+  Session-->>SDK: <code>session/event</code> <code>assistant/chunk</code>*
+  alt final adapter or terminal in-band request failure
+    Driver->>Session: <code>step/end</code>
+    Driver->>Hooks: <code>agent/request-error</code> waterfall
+    Hooks-->>Driver: return retry action or preserve the original error
+  else model request succeeded
+  Driver->>Session: <code>assistant/message</code>
+  Driver->>Tools: classify pending call by executionMode
+  loop barriers and bounded rolling pool, reclassify before start
+    opt call starts
+      Driver->>Session: <code>tool/call</code>
+      Driver->>Tools: ordered pre, concurrent execute
+      Tools-->>Session: tool-owned events when applicable
+    end
+    opt next model-order result ready
+      Driver->>Tools: ordered post
+      Driver->>Session: <code>tool/result</code>
+    end
+  end
+  Driver->>Session: <code>step/end</code>
+  opt natural stop and next-step inbox empty
+    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
+  end
+  opt next-step input is pending
+    Driver-->>Driver: claim pending next-step input
+    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+    Driver->>Hooks: <code>agent/pre-step</code> waterfall
+    Hooks-->>Driver: authoritative reject or enter(messages)
+  end
+  end
+  Driver->>Session: <code>turn/end</code>
+  end
+  Driver-->>SDK: <code>agent/status</code> idle
+```
+
+`assistant/message` 这条边会记录每次成功的提供方调用，包括无内容的调用和以 `max-tokens` 结束的调用。空内容不会进入派生历史记录，但持久锚点仍会保留 token 用量以及各分片的确切来源信息，其中包括显式的空来源集合。
+
+`dsh-compact-basic` 在派生请求之前通过 `agent/pre-step` 处理压力，而 `agent/request-error` 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在失败步骤结束之后、失败轮次结束之前；只有当剪枝或摘要生成推进了 surface replacement generation 时，系统才会开启一个全新的重试轮次，否则仍以原始请求错误为准。
+
+以返回的 `agent/pre-step` 决策为准；通过包装 `next()` 的监听器会保留下游消息，除非有意替换这些消息。steering（中途引导）和注入的上下文在后续边界认领其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。
+
+需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 `session/event`；`agent/*` 是用于队列与状态、提示词拦截、请求整形、steering、继续执行和错误处理的实时协调接口。
+
+维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index 360e4b32e4..b1f78b85e4 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/api-gateway.md
 api-gateway.md: e8aafc173dced3c4ead07421d92401411565ece6
-api-gateway.zh.md: 92681b72ffc573cde834cece19568ec3f1d515ce
+api-gateway.zh.md: f77a3e2675cc8ee6d27a8f6c9cbeb39609a9c282
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 92681b72ff..f77a3e2675 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -2,17 +2,17 @@
 
 [English](api-gateway.md) | 中文
 
-本文是 TypeRT API Gateway 的当前状态参考。它描述业务 Service 如何声明一元 Remote 方法、构建如何生成 Host 与 Client 契约，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
+本文是 TypeRT API Gateway 的当前状态参考。它描述业务服务如何声明一元 Remote 方法、构建如何生成 Host 与 Client 约定产物，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
 
 ## 编程模型
 
-业务 Service 通过 `@Remote` 或 `@RemoteScope` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.remote` 调用。
+业务服务通过 `@Remote` 或 `@RemoteScope` 选择对 Client 开放的方法。未标记的方法不会进入生成的 Client 类型或运行时贡献，也不能通过 `ctx.remote` 调用。
 
-`@Remote` 表示调用根 Host Context 中注册的 Cordis Service。复杂的 Host 对象不能直接跨 wire 传输；业务包必须通过 `TypeRTLookupMap` 声明它与 wire identity 的关联，并在运行时向 `ctx.typert.lookups` 注册默认解析提供方。例如 `Agent` 参数在 Host 签名中名为 `agent`，生成的 wire 字段为 `agentId`，Gateway 在调用业务方法前将 id 解析为 Host 对象。Host 组合可以用 `ctx.typert.lookups.configure()` 覆盖某个 lookup key 的解析策略，而不改变业务包拥有的参数名、wire 字段或规范类型 symbol。
+`@Remote` 表示调用根 Host 上下文中注册的 Cordis 服务。复杂的 Host 对象不能直接跨 wire 传输；业务包必须通过 `TypeRTLookupMap` 声明它与 wire identity 的关联，并在运行时向 `ctx.typert.lookups` 注册默认解析提供方。例如 `Agent` 参数在 Host 签名中名为 `agent`，生成的 wire 字段为 `agentId`，Gateway 在调用业务方法前将 id 解析为 Host 对象。Host 组合可以用 `ctx.typert.lookups.configure()` 覆盖某个 lookup key 的解析策略，而不改变业务包拥有的参数名、wire 字段或规范类型 symbol。
 
-`@RemoteScope(key)` 表示先通过 `ctx.typert.contexts` 把 identity 解析为一个作用域 Context，再从该 Context 取得 Service 并调用方法。它适用于方法本身依赖作用域组合、而不需要显式接收 `Agent` 等对象的情形。
+`@RemoteScope(key)` 表示先通过 `ctx.typert.contexts` 把 identity 解析为一个作用域上下文，再从该上下文取得服务并调用方法。它适用于方法本身依赖作用域组合、而不需要显式接收 `Agent` 等对象的情形。
 
-Service 通常继承 `GatewayService`，让 Cordis service key 与默认 Remote namespace 在构造器中显式绑定。已有其他基类的 Service 可以改为声明 `readonly typertGateway = bindTypeRTGateway(this, serviceKey)`；两种方式都会留下可检查的公开 binding，不依赖编译器向构造函数注入 symbol。
+服务通常继承 `GatewayService`，让 Cordis 服务键与默认 Remote namespace 在构造器中显式绑定。已有其他基类的服务可以改为声明 `readonly typertGateway = bindTypeRTGateway(this, serviceKey)`；两种方式都会留下可检查的公开 binding，不依赖编译器向构造函数注入 symbol。
 
 ```ts
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -55,7 +55,7 @@ export class GoalService extends GatewayService {
 
 Remote 方法可以同步返回或返回 Promise。若需要协作式取消，Host 签名的最后一个参数必须是全局类型的 `signal: AbortSignal`；它记录在描述符中而不是进入 `args`，Client 生成的方法则接受最后一个可选的 `AbortSignal`。
 
-Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子 Service；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，最后一个方法撤回后该 namespace 随即卸载。依赖声明归实际调用方所有：只有读取 `ctx.remote.<namespace>` 或 `agentCtx.remote.<namespace>` 的业务包才在自己的 `inject` 中同时声明 `remote` 与 `remote.<namespace>`；只负责挂载 contribution 的 assembly，以及不调用该 namespace 的上层 runtime，不代业务包声明 namespace 依赖。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用界面。
+Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子服务；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，最后一个方法撤回后该 namespace 随即卸载。依赖声明归实际调用方所有：只有读取 `ctx.remote.<namespace>` 或 `agentCtx.remote.<namespace>` 的业务包才在自己的 `inject` 中同时声明 `remote` 与 `remote.<namespace>`；只负责挂载 contribution 的 assembly，以及不调用该 namespace 的上层运行时，不代业务包声明 namespace 依赖。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypeRTContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用接口。
 
 ```ts ignore-check
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -75,28 +75,28 @@ await agentCtx.remote.goals.create({ objective: 'ship it' })
 
 Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，通过 `ctx.remote.$mount()` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 TypeRT Gateway 或业务包的 Remote JS。
 
-未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 契约，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
+未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 约定，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
 
 ## 组件职责
 
 | 位置 | 包或入口 | 职责 |
 |---|---|---|
-| 共享 | `@deepseek-ai/dsh-type-meta` | 声明 decorator、Gateway binding、可合并协议映射、调用描述符及提供方类型；不启动 TypeScript 分析，也不注册 Cordis 服务 |
-| 构建 | `@deepseek-ai/dsh-typert-generator` | 从 Host `ts.Program` 严格分析 Remote 签名、类型图、lookup、Context 与源码位置，并生成 Host 和 Host-for-Client 产物 |
-| Host | `@deepseek-ai/dsh-typert-registry` 与 Loader | 把生成的 Host 描述符、schema 及业务包注册项放入 `ctx.typert`，并持有 lookup 与 Context 提供方 |
+| 共享 | `@deepseek-ai/dsh-type-meta` | 声明 decorator、Gateway binding、可通过合并扩展的协议映射、调用描述符及提供方类型；不启动 TypeScript 分析，也不注册 Cordis 服务 |
+| 构建 | `@deepseek-ai/dsh-typert-generator` | 从 Host `ts.Program` 严格分析 Remote 签名、类型图、lookup、上下文与源码位置，并生成 Host 和 Host-for-Client 产物 |
+| Host | `@deepseek-ai/dsh-typert-registry` 与 Loader | 把生成的 Host 描述符、schema 及业务包注册项放入 `ctx.typert`，并持有 lookup 与上下文提供方 |
 | Host | `@deepseek-ai/dsh-api-remotes` | 负责应用的 Agent/Session 身份策略，并配置对应的 TypeRT lookup |
-| Host | `@deepseek-ai/dsh-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或 Context，调用实时 Cordis Service 并校验边界 |
-| Client | `@deepseek-ai/dsh-api-gateway/client` | 提供 `ctx.remote` 与 `remote.<namespace>` 子 Service，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
+| Host | `@deepseek-ai/dsh-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或上下文，调用当前有效的 Cordis 服务并校验边界 |
+| Client | `@deepseek-ai/dsh-api-gateway/client` | 提供 `ctx.remote` 与 `remote.<namespace>` 子服务，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
 | Client | `@deepseek-ai/dsh-api-remotes/client` | 显式选择并挂载本应用允许使用的 `/remote` 贡献，向业务代码带入对应的声明合并 |
 | 双侧 | `@deepseek-ai/dsh-client-connection` | 提供 RPC carrier、请求关联、信任边界、取消、响应 envelope 与当前 `/api` HTTP bridge |
 
 API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对等入口，但两侧构建不会进入同一个 `ts.Program`。Host 入口不导入 Client 的 Cordis `Context` 合并，Client 入口也不导入 Host Gateway 服务。
 
-## 严格生成链路
+## 严格生成流水线
 
 根构建依次执行 `build:lib:host`、`build:lib:client` 与 `build:web`。Host lib 阶段先运行 `tsc -b tsconfig.host.json`，再运行 `tsdown --env.DSH_BUILD_FACE host`；TypeRT generator 由正常 Host Project Reference 图编译，并在这次 tsdown 中以 Host aggregate 为唯一 `ts.Program` 种子运行。Client lib 阶段随后运行 `tsc -b tsconfig.client.json` 与 `tsdown --env.DSH_BUILD_FACE client`，使用刚生成的 Remote Client 声明和运行时贡献，但不再次启动 TypeRT。
 
-两次 tsdown 都接收完整 workspace，且都只打包 `lib/types` 中由对应 tsc 阶段发射的 JavaScript。根配置不扫描 Client 产物、不按 package 名分类，也不向 tsdown 传维护式 filter；各包的本地配置根据 `DSH_BUILD_FACE` 返回当前阶段的入口。普通 Client plugin 在 Client 阶段一起生成 Node loader 入口与 browser bundle。
+两次 tsdown 都接收完整 workspace，且都只打包 `lib/types` 中由对应 tsc 阶段发射的 JavaScript。根配置不扫描 Client 产物、不按包名分类，也不向 tsdown 传维护式 filter；各包的本地配置根据 `DSH_BUILD_FACE` 返回当前阶段的入口。普通 Client 插件在 Client 阶段一起生成 Node loader 入口与 browser bundle。
 
 `api-remotes` 是唯一拆分 TypeScript face 的 package 特例。它的 Host project 负责 Agent/Session lookup 策略，Client project 则依赖业务包在 Host tsdown 中生成的 `/remote` 声明；根 aggregate 与直接消费方必须分别引用 `api/remotes/tsconfig.host.json` 或 `api/remotes/tsconfig.client.json`。包内 `clientBundle(..., { hostPhase: true })` 让 Host 入口在 Host tsdown 中生成，让 Client tsdown 只生成 browser 入口。其他 package 仍只登记在一个 aggregate 中。
 
@@ -114,31 +114,31 @@ API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对
 
 Remote Client 声明中的参数名来自 wire 字段，参数和返回类型则引用原业务包导出的 Client-safe 类型。声明 map 把 `ctx.remote.goals.create` 最终解析到的生成属性映射到带 `@Remote` 的 Host 源方法，因此支持 declaration-map 的编辑器可以从 Client 调用跳到真实实现，而不是停在生成的 `.d.ts`。
 
-严格分析要求 Remote 是公开、非静态、有具体实现的实例方法。方法不能是泛型；参数必须是具名且必填的简单标识符，不能使用解构、默认值、rest 或可选参数。可 JSON 表示的普通类型由 TypeRT 生成严格 schema；工作区 class 等复杂对象必须具有唯一的 `TypeRTLookupMap` 声明。lookup 与 Context 包同时负责静态声明合并和运行时提供方注册，缺少任一侧都会在构建或最早可解析的运行时边界报错。
+严格分析要求 Remote 是公开、非静态、有具体实现的实例方法。方法不能是泛型；参数必须是具名且必填的简单标识符，不能使用解构、默认值、rest 或可选参数。可 JSON 表示的普通类型由 TypeRT 生成严格 schema；工作区 class 等复杂对象必须具有唯一的 `TypeRTLookupMap` 声明。lookup 与上下文包同时负责静态声明合并和运行时提供方注册，缺少任一侧都会在构建或最早可解析的运行时边界报错。
 
 ## 运行时调用
 
 当前 Remote 与 API Proxy 共用 Connection 的 `/api` 路由，不存在独立 `/api2` server 或第二套 Connection。Client Remote 调用 `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`；当前 HTTP carrier 对应 `POST /api/<namespace>/<method>`，payload 只包含一个具名 `args` 对象。
 
-Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内按 interceptor 顺序分发。TypeRT Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；未认领的请求回退到既有 API Proxy。Connection 拥有传输、RPC id、响应 envelope 和 request cancellation，Gateway 只拥有 Remote 数据协议和业务分发。未来替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程界面。
+Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内按 interceptor 顺序分发。TypeRT Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；未认领的请求回退到既有 API Proxy。Connection 拥有传输、RPC id、响应 envelope 和请求取消，Gateway 只拥有 Remote 数据协议和业务分发。未来替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程接口。
 
-Gateway 每次调用都从当前注册表解析描述符和实时 Service，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或 Context provider 解析对象或接收者，最后调用 binding 指向的 Service 方法并校验返回值。缺少 provider、identity 未命中、binding 不一致、参数多缺、schema 失败和方法不存在都在进入或离开业务边界时失败。
+Gateway 每次调用都从当前注册表解析描述符和当前有效的服务，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或上下文提供方解析对象或接收者，最后调用 binding 指向的服务方法并校验返回值。缺少提供方、identity 未命中、binding 不一致、参数多缺、schema 失败或方法不存在时，都会在边界处失败：要么发生在进入业务代码之前，要么发生在离开业务代码之后。
 
-lookup provider 的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于 provider 挂载；没有 provider 时调用仍以 `lookup-unavailable` 失败，配置卸载后则恢复 provider 默认策略。API Remotes 负责 `agent` 与 `session` 的标准 `agentFor()` 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。Web API Proxy 提供 Agent 默认值与 scope 设置，再让旧方法使用同一个 resolver。恢复失败和 ownership fence 通过既有 RPC error 原样返回，不折叠为 Gateway 的 `internal` 错误。
+lookup 提供方的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于 provider 挂载；没有提供方时调用仍以 `lookup-unavailable` 失败，配置卸载后则恢复提供方默认策略。API Remotes 负责 `agent` 与 `session` 的标准 `agentFor()` 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。Web API Proxy 提供 Agent 默认值与 scope 设置，再让旧方法使用同一个 resolver。恢复失败和 ownership fence 通过既有 RPC error 原样返回，不折叠为 Gateway 的 `internal` 错误。
 
-Client 卸载一个贡献时会一起移除描述符和具体方法，中止其进行中的调用，并使外部仍持有的旧方法句柄拒绝继续调用。Host 上已经注册过的严格 endpoint 被撤回后也不会降级到 SRC 推断，以免热卸载悄然降低校验强度。
+Client 卸载一个贡献时会一起移除描述符和具体方法，中止其进行中的调用，并使外部仍持有的陈旧方法句柄拒绝继续调用。Host 上已经注册过的严格 endpoint 被撤回后也不会降级到 SRC 推断，以免热卸载悄然降低校验强度。
 
 ## SRC 开发回退
 
 Host 通过 `node --import tsx/esm` 从源码启动时不会执行 TypeRT 编译插件。标准 decorator 初始化器仍会把方法名和调用模式记录到模块私有 `WeakMap`，`GatewayService` 或 `bindTypeRTGateway()` 则提供显式 service binding；Gateway 因而可以在不启动 `ts.Program` 的情况下构造一个较弱的临时描述符。
 
-SRC 回退从运行中函数解析简单参数名。参数名与某个已注册 lookup 的 `parameter` 相同，例如 `agent` 或 `session`，就使用其 `agentId` 或 `sessionId` wire 字段并在 Host 解析对象；其他参数只检查值是否为无循环、无特殊 prototype 的 JSON-safe 数据。`@RemoteScope` 直接使用已注册 Host Context provider 的 wire 字段。SRC 不读取 TypeScript 类型，不生成 Zod schema，不推断可选参数，也不支持解构、默认值、rest 或重复参数名。
+SRC 回退从运行中函数解析简单参数名。参数名与某个已注册 lookup 的 `parameter` 相同，例如 `agent` 或 `session`，就使用其 `agentId` 或 `sessionId` wire 字段并在 Host 解析对象；其他参数只检查值是否为无循环、无特殊 prototype 的 JSON-safe 数据。`@RemoteScope` 直接使用已注册 Host 上下文提供方的 wire 字段。SRC 不读取 TypeScript 类型，不生成 Zod schema，不推断可选参数，也不支持解构、默认值、rest 或重复参数名。
 
 SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Host 发现 decorator，Client Remote 也拒绝挂载缺少严格 codec 的 SRC 描述符；其类型、codec 和 Remote 注册值始终来自最近一次生成的 `lib/typert.remote-client.*`。
 
 ## 开发模式
 
-完整构建会先生成 Host 契约，再编译 Host、Client 与 Web，因此是建立或刷新所有产物的确定性入口：
+完整构建会先生成 Host 约定产物，再编译 Host、Client 与 Web，因此是建立或刷新所有产物的确定性入口：
 
 ```sh
 pnpm run build
@@ -153,18 +153,18 @@ pnpm run dev:web
 
 `dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 只监听带 `dshClient` 声明的 Client plugin 并重写其 `lib/client.js`，它不会分析 Host decorator，也不会生成 Remote Client DTS。
 
-只修改 Remote 方法实现体而不改变契约时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格契约，再让 Client 编译并打包新的贡献：
+只修改 Remote 方法实现体而不改变约定时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、上下文或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格约定产物，再让 Client 编译并打包新的贡献：
 
 ```sh
 pnpm run build:lib
 ```
 
-运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 契约，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净工作树不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
+运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定产物，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净的 worktree不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
 
 ## 边界
 
-Remote 只处理有单个请求与单个结果的一元方法调用。Session event stream、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
+Remote 只处理有单个请求与单个结果的一元方法调用。会话事件流、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
 
-API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务契约允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
+API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务约定允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
 
 当前 lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。某个 Remote endpoint 若必须只接受 live 对象，需要后续增加显式的逐参数或逐 endpoint 策略，不能通过业务方法内部猜测恢复来源。
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 2436ff9027..c9279c45a8 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/architecture.md
 architecture.md: f593ee5c54e5bd2cbdaa5da9f2de54b7b08ec14b
-architecture.zh.md: 5780d54aad6085ef7811dfa94377a4c2478bfb99
+architecture.zh.md: 9a4fb8ec88ad93fa2d3f474ec4f2eb59b678216f
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 5780d54aad..9a4fb8ec88 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -6,7 +6,7 @@
 
 ## 概览
 
-每个 harness 都是 [Cordis](cordis-primer.md) 上下文；各包（package）贡献服务、类型化事件和可释放的注册项。`packages/core/` 汇集默认流程；各项功能仍以插件形式存在。
+每个 harness 都是 [Cordis](cordis-primer.md) 上下文；各包贡献服务、类型化事件和可释放的注册项。`packages/core/` 汇集默认流程；各项能力仍以插件形式存在。
 
 ### 默认服务
 
@@ -17,18 +17,18 @@
 | `ctx.systemPrompt` | `dsh-system-prompt` | 有序的提示词片段、工具 schema 和变量 |
 | `ctx.tools` | `dsh-tools` | 工具注册表和[执行流水线](tool-execution-pipeline.md) |
 | `ctx.agents` | `dsh-agent` | 活跃 agent（智能体）、委托创建、`agent/*` 事件、进程内发起方作用域 |
-| `ctx.agentLoop` | `dsh-agent-loop` | 实体 `Agent` 驱动器 |
+| `ctx.agentLoop` | `dsh-agent-loop` | 具体 `Agent` 驱动器 |
 
-### 功能服务
+### 能力服务
 
 | ctx 键 | 包族 | 职责 |
 |---|---|---|
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | 适配器注册表和模型流式调用 |
-| `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的单实例请求压力与表面压力 |
+| `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | 感知回放的请求压力与表面压力 |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | 前台和后台命令执行 |
 | `ctx.subprocess` | [`subprocess/`](../packages/subprocess/README.md) | 可执行文件查找、受管进程树、终端 |
 | `ctx.pty` | [`pty/`](../packages/pty/README.md) | 按 owner 隔离的持久化终端会话 |
-| `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | 通过 argv 包装和逐调用策略限制同一执行环境内的进程 |
+| `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | 通过 argv 包装和逐调用策略限制与宿主共享文件系统和内核的进程 |
 | `ctx.sandboxPolicy` | [`sandbox/`](../packages/sandbox/README.md) | 共享沙箱策略归属点 |
 | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | 执行模型编写的程序 |
 | `ctx.fs` | [`fs/`](../packages/fs/README.md) | 执行世界路径、有界 I/O 和策略事件 |
@@ -59,7 +59,7 @@
 
 - **会话事件**是通过 `session/event` 发出的持久日志事实。
 - **Agent 事件**携带活跃 `Agent`，用于 inbox、步骤、状态、请求、验证和续跑。
-- **功能事件**无需导入循环即可附加策略和适配器。
+- **能力事件**无需导入循环即可附加策略和适配器。
 
 ### 拦截语义
 
@@ -115,19 +115,19 @@ idle inject:
 
 `inject()` 将不会唤醒驱动器的上下文排入 `next-step`；空闲驱动器会让它保持待处理，直至 `followup()` 或 `steer()` 唤醒。工具执行后的 `additionalContexts` 使用同一个 inbox。`agent/pre-step` 的 payload 携带独占的已领取批次，以及即将使用的轮次、步骤和信号。拒绝则不进入步骤；进入则提供在 `step/start` 后追加的完整批次。空的工具续跑仍会经过 waterfall，其最终值一次性结算所有改写。
 
-裁剪先于摘要；溢出重试必须取得持久进展。`agent/request-error` 可以授权使用冻结提示词进行同步骤重试；取消优先。适配器的 `retryPolicy` 使 normal mode 保持有界，always mode 则在专门恢复后重试（[压缩](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)、[重试基础](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)、[提供方策略](../.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md)）。精确事件顺序由生成的 [agent 生命周期](agent-lifecycle.md)定义；队列、steering、重试与取消机制由 [agent-loop README](../packages/core/agent-loop/README.md)定义。
+裁剪先于摘要；溢出重试必须取得持久进展。`agent/request-error` 可以授权使用冻结提示词进行同步骤重试；取消优先。适配器的 `retryPolicy` 使 normal mode 保持有界，always mode 则在专门恢复后重试（[压缩](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)、[重试基础](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)、[提供方策略](../.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md)）。精确事件顺序由生成的 [agent 生命周期](agent-lifecycle.md)定义；队列、steering（中途引导）、重试与取消机制由 [agent-loop README](../packages/core/agent-loop/README.md)定义。
 
 ### 失败边界
 
 适配器选择、分发与迭代失败会成为 error 或 aborted 类型的终止 `finish` 分片。`agent/request-error` 接收请求坐标、标准化 `LlmFailure`、可用的重试策略和信号；middleware 与消费方错误仍在恢复之外。失败分片既不提交消息，也不提交工具调用。
 
-其他故障使用 `agent/error`；取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消功能准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。abort 触发后、收敛前到达的唤醒输入会在 driver 的收敛边界执行，而 `disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。持久化层以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
+其他故障使用 `agent/error`；取消和 dispose（资源释放）优先于恢复。在提交请求头之前，轮次信号会取消能力准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。abort 触发后、收敛前到达的唤醒输入会在 driver 的收敛边界执行，而 `disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。持久性以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
 
 轮次和步骤事件均位于轮次边界内；loop 只会在轮次内从进入步骤的批次追加 `user/message`。轮次会在首次领取与 pre-step 之前打开，因此拒绝、空输入、取消或失败会关闭一个不包含任何步骤事件的持久轮次。独立的 `compact/* { turn: null }` 事件不占用轮次，其锁定时刻标记可以与 inbox splice 交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](subsystems/session.md#why-a-turn-ended-turnendreasonmap)。
 
 ### Agent 句柄
 
-`ctx.agents` 拥有 agent 并返回 `AgentHandle { agent, dispose() }`。插件使用 `send()`，或使用其 `followup()`、`steer()` 和 `inject()` 预设。`cancel()` 与 `whenIdle()` 控制生命周期，需等待完成的资源释放则负责拆卸。后续消息的 `MessageId` 跟踪持久 inbox 的插入、领取与丢弃通知，而不标识提示词输出或轮次结束；只有完整活动区间的所有方才能将其概括为一次运行结果（[决策](../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。
+`ctx.agents` 拥有 agent 并返回 `AgentHandle { agent, dispose() }`。插件使用 `send()`，或使用其 `followup()`、`steer()` 和 `inject()` 预设。`cancel()` 与 `whenIdle()` 控制生命周期，拆卸由需等待完成的 dispose 负责。后续消息的 `MessageId` 跟踪持久 inbox 的插入、领取与丢弃通知，而不标识提示词输出或轮次结束；只有完整活动区间的所有者才能将其概括为一次运行结果（[决策](../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。
 
 ### Agent 作用域
 
@@ -141,23 +141,23 @@ idle inject:
 
 **模型可见 ⟺ 已记录**：在 `step/start` 进入的消息加上折叠后的 `request/header` 可以重建每个请求。该 header 会标记适配器默认值，使后续提议丢弃这些值并重新解析路由，同时不丢失显式设置。`request/context` 会在路由变化时另行记录与注册项绑定的提供方、模型及容量元数据；它不参与请求重建或 header 相等性判断。`dsh-agent-loop/invariant` 通过 `ctx.invariants` 断言可重建性（[可重建性](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)）。
 
-持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一契约（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
+持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一约定（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
 
-在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
+在轮次之间，事件所有者通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
 
 ### 模型内容
 
 消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](subsystems/token-meter.md)。
 
-流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[契约](subsystems/llm-streaming.md)）。
+流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[约定](subsystems/llm-streaming.md)）。
 
 ## 扩展与组合
 
-### 功能模式
+### 能力模式
 
-能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[功能图](capability-seams.md)。
+能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[能力图](capability-seams.md)。
 
-例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。
+例外情况包括 LLM（大语言模型）接口／消费方合并、文件系统策略、web 注册表，以及具名 skill/subagent 提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。
 
 `dsh-workspace-context` 在第一次 `agent/pre-step` 组合基线并将它折入最终进入的批次、紧随已领取的直接提示词之后，使其与直接提示词一同抵达第一次请求；reject 则将它留在 next-step inbox。当压缩从可见表层移除该基线时，下一次进入步骤的 pre-step 会组合当前基线，并在同一请求中携带它。工具执行后投影的文件系统变更也会折入下一次进入步骤的 pre-step，而不会另外创建稍后的纯上下文步骤（[决策](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)）。`dsh-paths` 负责共享路径。
 
@@ -172,13 +172,13 @@ idle inject:
 | 目标 | 机制 |
 |---|---|
 | 添加模型提供方 | 在 `ctx.llm` 上注册其适配器 |
-| 添加面向模型的功能 | 在 `ctx.tools` 上注册；schema 加入提示词组装 |
-| 添加 shell 执行 | 实现并注册 `ctx.bash` 后端；本地后端通过 `ctx.subprocess` 生成进程 |
+| 添加面向模型的能力 | 在 `ctx.tools` 上注册；schema 加入提示词组装 |
+| 添加 shell 执行 | 实现并注册 `ctx.bash` 后端；本地后端通过 `ctx.subprocess` spawn 进程 |
 | 添加持久化终端执行 | 注册 `ctx.pty` 后端和 `dsh-tool-pty` |
 | 添加用户命令 | 在 `ctx.commands` 上注册；适配器无需模型轮次即可发现并分派 |
 | 添加后台工作 | 在 `ctx.tasks` 上注册；通用 `task_*` 工具负责收集或停止 |
 | 添加文件系统访问或策略 | 实现 `ctx.fs` 提供方，或监听 `fs/*` 策略事件 |
-| 限制生成的进程 | 使用 `ctx.sandbox` 后端；消费方在生成前包装 argv |
+| 限制 spawn 出的进程 | 使用 `ctx.sandbox` 后端；消费方在 spawn 前包装 argv |
 | 拦截请求、工具或轮次 | 使用相应的 `agent/*` 或 `tools/*` 事件；`agent/turn-stopping` 是停止边界 |
 | 添加模型可见上下文 | 调用 `agent.inject()`，将带来源的上下文排入下一次获准请求 |
 | 添加 UI 或编辑器集成 | 驱动 `ctx.agents` 并从 `session/event` 渲染 |
@@ -188,4 +188,4 @@ idle inject:
 | fork 活跃会话 | 调用 `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | 将注册项限定到单个 agent | 使用其 `agent.ctx`（参见 Agent 作用域） |
 
-[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)提供插件骨架和功能到服务边界的映射；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
+[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)提供插件骨架和功能到 seam 的映射；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml
new file mode 100644
index 0000000000..ca5caccff2
--- /dev/null
+++ b/docs/capability-seams.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 docs/capability-seams.md
+capability-seams.md: 4b46a6566ba795d89d6fdf7261c42574af286faf
+capability-seams.zh.md: 23f270c7463a45b5892ead8e34260b375a9fe3e5
diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md
new file mode 100644
index 0000000000..23f270c746
--- /dev/null
+++ b/docs/capability-seams.zh.md
@@ -0,0 +1,425 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/capability-seams.md` 重新记录配对。 -->
+
+# 能力 Seams 与核心服务
+
+[English](capability-seams.md) | 中文
+
+服务可以是核心主干服务、可替换的能力 seam，也可以是组合包／组合点。下图展示了拥有服务声明的包、已知实现包，以及直接消费该服务的包。
+
+```mermaid
+flowchart LR
+  pkg_llm["llm"]
+  svc_llm["ctx.llm<br/>LLM adapter registry"]
+  pkg_llm_deepseek["llm-deepseek"]
+  pkg_llm_pi_ai["llm-pi-ai"]
+  pkg_llm_replay["llm-replay"]
+  pkg_agent_loop["agent-loop"]
+  pkg_compact_basic["compact-basic"]
+  pkg_token_meter["token-meter"]
+  svc_tokenMeter["ctx.tokenMeter<br/>Replay token measurement"]
+  pkg_compact_tool_result_prune["compact-tool-result-prune"]
+  svc_toolResultPrune["ctx.toolResultPrune<br/>Model-free tool-result pruning"]
+  pkg_session["session"]
+  svc_sessions["ctx.sessions<br/>In-memory session store"]
+  pkg_agent["agent"]
+  pkg_session_persistence["session-persistence"]
+  pkg_session_query["session-query"]
+  pkg_session_query_sqlite["session-query-sqlite"]
+  pkg_subagent_inprocess["subagent-inprocess"]
+  pkg_invariants["invariants"]
+  svc_invariants["ctx.invariants<br/>Package-owned invariant registry"]
+  pkg_scope["scope"]
+  pkg_typert_registry["typert-registry"]
+  svc_typert["ctx.typert<br/>Runtime type registry"]
+  pkg_typert_loader["typert-loader"]
+  pkg_api_gateway["api-gateway"]
+  svc_typertGateway["ctx.typertGateway<br/>TypeRT Host invocation gateway"]
+  svc_sessionPersistence["ctx.sessionPersistence<br/>Durable session persistence seam"]
+  pkg_session_persistence_jsonl["session-persistence-jsonl"]
+  pkg_session_persistence_sqlite["session-persistence-sqlite"]
+  pkg_tool_bash["tool-bash"]
+  pkg_hooks_claude["hooks-claude"]
+  pkg_hooks_codex["hooks-codex"]
+  pkg_settings["settings"]
+  svc_settings["ctx.settings<br/>User-settings seam"]
+  pkg_settings_local["settings-local"]
+  pkg_apiproxy["apiproxy"]
+  pkg_credentials["credentials"]
+  svc_credentials["ctx.credentials<br/>Credential seam"]
+  pkg_credentials_local["credentials-local"]
+  pkg_session_telemetry["session-telemetry"]
+  svc_telemetry["ctx.telemetry<br/>Session telemetry seam"]
+  pkg_session_telemetry_otel["session-telemetry-otel"]
+  pkg_storage["storage"]
+  svc_storage["ctx.storage<br/>Non-session storage hub"]
+  pkg_storage_json["storage-json"]
+  pkg_storage_sqlite["storage-sqlite"]
+  pkg_storage_domain["storage-domain"]
+  svc_storageDomain["ctx.storageDomain<br/>Domain data facility"]
+  pkg_workspace["workspace"]
+  svc_workspace["ctx.workspace<br/>Workspace entity registry"]
+  svc_sessionQuery["ctx.sessionQuery<br/>Session reads, traces, filters, and search"]
+  pkg_session_reference["session-reference"]
+  pkg_tool_session_query["tool-session-query"]
+  svc_sessionReferences["ctx.sessionReferences<br/>Cross-session snapshot preparation"]
+  pkg_session_title["session-title"]
+  svc_sessionTitle["ctx.sessionTitle<br/>Log-backed session titles"]
+  pkg_session_title_first_message_llm["session-title-first-message-llm"]
+  pkg_session_title_all_messages_llm["session-title-all-messages-llm"]
+  pkg_system_prompt["system-prompt"]
+  svc_systemPrompt["ctx.systemPrompt<br/>System prompt assembly registry"]
+  pkg_tools["tools"]
+  pkg_tool_fs["tool-fs"]
+  pkg_tool_pty["tool-pty"]
+  pkg_tool_web["tool-web"]
+  svc_tools["ctx.tools<br/>Tool registry and guarded execution pipeline"]
+  pkg_tool_ask_user["tool-ask-user"]
+  pkg_tool_cordis["tool-cordis"]
+  pkg_tool_skill["tool-skill"]
+  pkg_tool_subagent["tool-subagent"]
+  pkg_tool_todo["tool-todo"]
+  pkg_user_interaction["user-interaction"]
+  svc_userInteraction["ctx.userInteraction<br/>Human question/answer seam"]
+  pkg_plan_mode["plan-mode"]
+  svc_planMode["ctx.planMode<br/>Plan collaboration state"]
+  pkg_commands["commands"]
+  svc_commands["ctx.commands<br/>Human command registry"]
+  pkg_session_projection["session-projection"]
+  svc_sessionProjections["ctx.sessionProjections<br/>Session projection units"]
+  pkg_host_apiproxy["host-apiproxy"]
+  pkg_session_projection_cache["session-projection-cache"]
+  svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"]
+  pkg_skill["skill"]
+  svc_skills["ctx.skills<br/>Skill provider registry"]
+  pkg_skill_badge["skill-badge"]
+  pkg_skill_local["skill-local"]
+  svc_agents["ctx.agents<br/>Agent service"]
+  pkg_acp["acp"]
+  svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
+  pkg_agent_spine_demo["agent-spine-demo"]
+  pkg_goal["goal"]
+  svc_goals["ctx.goals<br/>Same-session goal domain"]
+  pkg_e2b["e2b"]
+  svc_e2b["ctx.e2b<br/>E2B sandbox lifecycle owner"]
+  pkg_fs_e2b["fs-e2b"]
+  pkg_subprocess_e2b["subprocess-e2b"]
+  pkg_subprocess["subprocess"]
+  svc_subprocess["ctx.subprocess<br/>Subprocess seam"]
+  pkg_subprocess_local["subprocess-local"]
+  pkg_bash_local["bash-local"]
+  pkg_bash_sandbox["bash-sandbox"]
+  pkg_pty_local["pty-local"]
+  pkg_lsp_local["lsp-local"]
+  pkg_subagent_acp["subagent-acp"]
+  pkg_subagent_codex["subagent-codex"]
+  pkg_subagent_claude_code["subagent-claude-code"]
+  pkg_bash["bash"]
+  svc_bash["ctx.bash<br/>Bash executor seam"]
+  pkg_pwsh_local["pwsh-local"]
+  pkg_tool_pwsh["tool-pwsh"]
+  pkg_bash_env["bash-env"]
+  svc_bashEnv["ctx.bashEnv<br/>Managed bash environment registry"]
+  pkg_pty["pty"]
+  svc_pty["ctx.pty<br/>Persistent PTY session registry"]
+  pkg_sandbox["sandbox"]
+  svc_sandbox["ctx.sandbox<br/>Process-sandbox seam"]
+  pkg_sandbox_local["sandbox-local"]
+  pkg_sandbox_policy["sandbox-policy"]
+  svc_sandboxPolicy["ctx.sandboxPolicy<br/>Sandbox policy home"]
+  pkg_fs_sandbox["fs-sandbox"]
+  pkg_approval["approval"]
+  svc_approval["ctx.approval<br/>Approval seam"]
+  pkg_permission["permission"]
+  svc_permission["ctx.permission<br/>Permission presets"]
+  pkg_code_runtime["code-runtime"]
+  svc_codeRuntime["ctx.codeRuntime<br/>Code-execution seam"]
+  pkg_code_runtime_worker["code-runtime-worker"]
+  pkg_fs["fs"]
+  svc_fs["ctx.fs<br/>Filesystem provider seam"]
+  pkg_fs_local["fs-local"]
+  pkg_fs_policy["fs-policy"]
+  pkg_compact["compact"]
+  svc_compact["ctx.compact<br/>Compaction seam"]
+  pkg_subagent["subagent"]
+  svc_subagents["ctx.subagents<br/>Subagent provider and continuation service"]
+  pkg_subagent_spawn["subagent-spawn"]
+  pkg_subagent_fork["subagent-fork"]
+  pkg_subagent_dsh_sdk["subagent-dsh-sdk"]
+  pkg_tool_subagent_control["tool-subagent-control"]
+  pkg_tool_ralph["tool-ralph"]
+  pkg_tasks["tasks"]
+  svc_tasks["ctx.tasks<br/>Background task registry"]
+  pkg_tasks_local["tasks-local"]
+  pkg_tool_tasks["tool-tasks"]
+  pkg_web["web"]
+  svc_web["ctx.web<br/>Web access provider registry"]
+  pkg_web_search_exa["web-search-exa"]
+  pkg_web_search_perplexity["web-search-perplexity"]
+  pkg_web_search_deepseek["web-search-deepseek"]
+  pkg_web_fetch_local["web-fetch-local"]
+  pkg_spill["spill"]
+  svc_spillStore["ctx.spillStore<br/>Spill storage seam"]
+  pkg_spill_local["spill-local"]
+  pkg_spill_policy["spill-policy"]
+  pkg_directory_picker["directory-picker"]
+  svc_directoryPicker["ctx.directoryPicker<br/>Workspace-directory picking seam"]
+  pkg_directory_picker_native["directory-picker-native"]
+  pkg_directory_picker_browse["directory-picker-browse"]
+  pkg_webserver["webserver"]
+  svc_httpServer["ctx.httpServer<br/>HTTP route registration"]
+  pkg_connection["connection"]
+  pkg_modules["modules"]
+  pkg_hmr["hmr"]
+  svc_clientModuleHost["ctx.clientModuleHost<br/>Client plugin graph host"]
+  pkg_workflow["workflow"]
+  svc_workflows["ctx.workflows<br/>Workflow script engine"]
+  pkg_workflow_workerthread["workflow-workerthread"]
+  pkg_tool_workflow["tool-workflow"]
+  pkg_acp --> svc_approval
+  pkg_agent --> svc_agents
+  pkg_agent_loop --> svc_agentLoop
+  pkg_api_gateway --> svc_typertGateway
+  pkg_approval --> svc_approval
+  pkg_bash --> svc_bash
+  pkg_bash_env --> svc_bashEnv
+  pkg_bash_local --> svc_bash
+  pkg_bash_sandbox --> svc_bash
+  pkg_code_runtime --> svc_codeRuntime
+  pkg_code_runtime_worker --> svc_codeRuntime
+  pkg_commands --> svc_commands
+  pkg_compact --> svc_compact
+  pkg_compact_basic --> svc_compact
+  pkg_compact_tool_result_prune --> svc_toolResultPrune
+  pkg_credentials --> svc_credentials
+  pkg_credentials_local --> svc_credentials
+  pkg_directory_picker --> svc_directoryPicker
+  pkg_directory_picker_browse --> svc_directoryPicker
+  pkg_directory_picker_native --> svc_directoryPicker
+  pkg_e2b --> svc_e2b
+  pkg_fs --> svc_fs
+  pkg_fs_e2b --> svc_fs
+  pkg_fs_local --> svc_fs
+  pkg_fs_sandbox --> svc_fs
+  pkg_goal --> svc_goals
+  pkg_invariants --> svc_invariants
+  pkg_llm --> svc_llm
+  pkg_llm_deepseek --> svc_llm
+  pkg_llm_pi_ai --> svc_llm
+  pkg_llm_replay --> svc_llm
+  pkg_modules --> svc_clientModuleHost
+  pkg_permission --> svc_permission
+  pkg_plan_mode --> svc_planMode
+  pkg_pty --> svc_pty
+  pkg_pty_local --> svc_pty
+  pkg_pwsh_local --> svc_bash
+  pkg_sandbox --> svc_sandbox
+  pkg_sandbox_local --> svc_sandbox
+  pkg_sandbox_policy --> svc_sandboxPolicy
+  pkg_session --> svc_sessions
+  pkg_session_persistence --> svc_sessionPersistence
+  pkg_session_persistence_jsonl --> svc_sessionPersistence
+  pkg_session_persistence_sqlite --> svc_sessionPersistence
+  pkg_session_projection --> svc_sessionProjections
+  pkg_session_projection_cache --> svc_sessionProjectionCache
+  pkg_session_query --> svc_sessionQuery
+  pkg_session_query_sqlite --> svc_sessionQuery
+  pkg_session_reference --> svc_sessionReferences
+  pkg_session_telemetry --> svc_telemetry
+  pkg_session_telemetry_otel --> svc_telemetry
+  pkg_session_title --> svc_sessionTitle
+  pkg_session_title_all_messages_llm --> svc_sessionTitle
+  pkg_session_title_first_message_llm --> svc_sessionTitle
+  pkg_settings --> svc_settings
+  pkg_settings_local --> svc_settings
+  pkg_skill --> svc_skills
+  pkg_skill_badge --> svc_skills
+  pkg_skill_local --> svc_skills
+  pkg_spill --> svc_spillStore
+  pkg_spill_local --> svc_spillStore
+  pkg_storage --> svc_storage
+  pkg_storage_domain --> svc_storageDomain
+  pkg_storage_json --> svc_storage
+  pkg_storage_sqlite --> svc_storage
+  pkg_subagent --> svc_subagents
+  pkg_subagent_acp --> svc_subagents
+  pkg_subagent_claude_code --> svc_subagents
+  pkg_subagent_codex --> svc_subagents
+  pkg_subagent_dsh_sdk --> svc_subagents
+  pkg_subagent_fork --> svc_subagents
+  pkg_subagent_spawn --> svc_subagents
+  pkg_subprocess --> svc_subprocess
+  pkg_subprocess_e2b --> svc_subprocess
+  pkg_subprocess_local --> svc_subprocess
+  pkg_system_prompt --> svc_systemPrompt
+  pkg_tasks --> svc_tasks
+  pkg_tasks_local --> svc_tasks
+  pkg_token_meter --> svc_tokenMeter
+  pkg_tools --> svc_tools
+  pkg_typert_registry --> svc_typert
+  pkg_user_interaction --> svc_userInteraction
+  pkg_web --> svc_web
+  pkg_web_fetch_local --> svc_web
+  pkg_web_search_deepseek --> svc_web
+  pkg_web_search_exa --> svc_web
+  pkg_web_search_perplexity --> svc_web
+  pkg_webserver --> svc_httpServer
+  pkg_workflow --> svc_workflows
+  pkg_workflow_workerthread --> svc_workflows
+  pkg_workspace --> svc_workspace
+  svc_agentLoop --> pkg_agent_spine_demo
+  svc_agents --> pkg_acp
+  svc_agents --> pkg_agent_loop
+  svc_agents --> pkg_subagent_inprocess
+  svc_approval --> pkg_tool_bash
+  svc_approval --> pkg_tools
+  svc_bash --> pkg_hooks_claude
+  svc_bash --> pkg_hooks_codex
+  svc_bash --> pkg_tool_bash
+  svc_bash --> pkg_tool_pwsh
+  svc_bashEnv --> pkg_tool_bash
+  svc_bashEnv --> pkg_tool_pwsh
+  svc_clientModuleHost --> pkg_hmr
+  svc_codeRuntime --> pkg_tools
+  svc_compact --> pkg_compact_basic
+  svc_credentials --> pkg_apiproxy
+  svc_credentials --> pkg_llm_deepseek
+  svc_credentials --> pkg_llm_pi_ai
+  svc_directoryPicker --> pkg_apiproxy
+  svc_e2b --> pkg_fs_e2b
+  svc_e2b --> pkg_subprocess_e2b
+  svc_fs --> pkg_tool_fs
+  svc_httpServer --> pkg_connection
+  svc_httpServer --> pkg_hmr
+  svc_httpServer --> pkg_modules
+  svc_invariants --> pkg_agent
+  svc_invariants --> pkg_agent_loop
+  svc_invariants --> pkg_scope
+  svc_invariants --> pkg_session
+  svc_llm --> pkg_agent_loop
+  svc_llm --> pkg_compact_basic
+  svc_pty --> pkg_tool_pty
+  svc_sandbox --> pkg_bash_sandbox
+  svc_sandbox --> pkg_pty_local
+  svc_sandboxPolicy --> pkg_bash_sandbox
+  svc_sandboxPolicy --> pkg_fs_sandbox
+  svc_sandboxPolicy --> pkg_pty_local
+  svc_sessionPersistence --> pkg_agent_loop
+  svc_sessionPersistence --> pkg_hooks_claude
+  svc_sessionPersistence --> pkg_hooks_codex
+  svc_sessionPersistence --> pkg_session_query
+  svc_sessionPersistence --> pkg_session_query_sqlite
+  svc_sessionPersistence --> pkg_tool_bash
+  svc_sessionProjectionCache --> pkg_host_apiproxy
+  svc_sessionProjections --> pkg_host_apiproxy
+  svc_sessionProjections --> pkg_session_title
+  svc_sessionProjections --> pkg_tool_todo
+  svc_sessionQuery --> pkg_session_reference
+  svc_sessionQuery --> pkg_tool_session_query
+  svc_sessions --> pkg_agent
+  svc_sessions --> pkg_agent_loop
+  svc_sessions --> pkg_invariants
+  svc_sessions --> pkg_session_persistence
+  svc_sessions --> pkg_session_query
+  svc_sessions --> pkg_session_query_sqlite
+  svc_sessions --> pkg_subagent_inprocess
+  svc_settings --> pkg_apiproxy
+  svc_settings --> pkg_llm_deepseek
+  svc_settings --> pkg_llm_pi_ai
+  svc_skills --> pkg_tool_skill
+  svc_spillStore --> pkg_spill_policy
+  svc_storage --> pkg_storage_domain
+  svc_storageDomain --> pkg_workspace
+  svc_subagents --> pkg_tool_ralph
+  svc_subagents --> pkg_tool_subagent
+  svc_subagents --> pkg_tool_subagent_control
+  svc_subprocess --> pkg_bash_local
+  svc_subprocess --> pkg_bash_sandbox
+  svc_subprocess --> pkg_lsp_local
+  svc_subprocess --> pkg_pty_local
+  svc_subprocess --> pkg_subagent_acp
+  svc_subprocess --> pkg_subagent_claude_code
+  svc_subprocess --> pkg_subagent_codex
+  svc_systemPrompt --> pkg_agent_loop
+  svc_systemPrompt --> pkg_tool_fs
+  svc_systemPrompt --> pkg_tool_pty
+  svc_systemPrompt --> pkg_tool_web
+  svc_systemPrompt --> pkg_tools
+  svc_tasks --> pkg_tool_bash
+  svc_tasks --> pkg_tool_pty
+  svc_tasks --> pkg_tool_subagent
+  svc_tasks --> pkg_tool_tasks
+  svc_tokenMeter --> pkg_compact_basic
+  svc_toolResultPrune --> pkg_compact_basic
+  svc_tools --> pkg_agent_loop
+  svc_tools --> pkg_tool_ask_user
+  svc_tools --> pkg_tool_bash
+  svc_tools --> pkg_tool_cordis
+  svc_tools --> pkg_tool_fs
+  svc_tools --> pkg_tool_pty
+  svc_tools --> pkg_tool_skill
+  svc_tools --> pkg_tool_subagent
+  svc_tools --> pkg_tool_todo
+  svc_tools --> pkg_tool_web
+  svc_typert --> pkg_api_gateway
+  svc_typert --> pkg_typert_loader
+  svc_userInteraction --> pkg_tool_ask_user
+  svc_web --> pkg_tool_web
+  svc_workflows --> pkg_tool_ralph
+  svc_workflows --> pkg_tool_workflow
+  svc_workspace --> pkg_apiproxy
+  svc_fs -. event gate .-> pkg_fs_policy
+```
+
+| ctx 键 | 角色 | 所属包 | 实现 | 直接消费方 | 配套插件 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek)、[`llm-pi-ai`](../packages/llm/llm-pi-ai)、[`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop)、[`compact-basic`](../packages/compact/compact-basic) | - | 适配器注册提供方实现；agent loop（智能体循环）与压缩功能调用提供方无关的流服务。 |
+| `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | 拥有按会话隔离的回放折叠区；压力消费方共享不可变且带修订版本的测量结果。 |
+| `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | 在摘要压缩前，通过可回放的单节点表层替换来改写过大的当前工具结果。 |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop)、[`agent`](../packages/core/agent)、[`session-persistence`](../packages/session/session-persistence)、[`session-query`](../packages/session-query/session-query)、[`session-query-sqlite`](../packages/session-query/session-query-sqlite)、[`subagent-inprocess`](../packages/subagent/subagent-inprocess)、[`invariants`](../packages/support/invariants) | - | 拥有仅追加的 Session 实例，并发出持久的会话事件流。 |
+| `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session)、[`agent`](../packages/core/agent)、[`scope`](../packages/core/scope)、[`agent-loop`](../packages/core/agent-loop) | - | 配套子路径注册所属包本地的检查；该服务负责选择、唯一性、子 fiber，以及标明所属包的失败。 |
+| `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader)、[`api-gateway`](../packages/api/gateway) | - | 插件直接或通过 dsh-typert-loader 注册实时 zod 贡献；API 网关消费调用描述符和提供方，其他运行时消费方则在各自边界查询 schema 与反射元数据。 |
+| `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | 将生成的 Remote 描述符与实时 Cordis 服务关联，解析已注册的身份，并通过共享的 Connection RPC 载体提供一元调用。 |
+| `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session/session-persistence) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl)、[`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop)、[`tool-bash`](../packages/bash/tool-bash)、[`hooks-claude`](../packages/hooks/hooks-claude)、[`hooks-codex`](../packages/hooks/hooks-codex)、[`session-query`](../packages/session-query/session-query)、[`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | 各后端持久化同一套 SessionEvent 词汇；应用在组合时选择后端。 |
+| `ctx.settings` | `seam` | [`settings`](../packages/settings/settings) | [`settings-local`](../packages/settings/settings-local) | [`llm-deepseek`](../packages/llm/llm-deepseek)、[`llm-pi-ai`](../packages/llm/llm-pi-ai)、`apiproxy` | - | 插件注册命名空间 schema 并解析分层值；提供方存储原始文档。LLM（大语言模型）适配器在用户分区下将其入口配置注册为组合基础；Web 网关提供经过脱敏的分层描述符，并写入用户层。 |
+| `ctx.credentials` | `seam` | [`credentials`](../packages/credentials/credentials) | [`credentials-local`](../packages/credentials/credentials-local) | [`llm-deepseek`](../packages/llm/llm-deepseek)、[`llm-pi-ai`](../packages/llm/llm-pi-ai)、`apiproxy` | - | 配置携带对机密信息的引用；提供方拥有实际值。消费方按操作解析，因此轮换后的凭据会在紧接着的下一次请求中生效；Web 网关提供不含实际值的视图和只写存储。 |
+| `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/session/session-telemetry) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | - | - | 该 seam 捕获会话记录、进行脱敏并交给一个后端；没有其他组件消费该服务，其输出会离开当前进程。 |
+| `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json)、[`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | 各后端以不同名称并列注册；数据形态（领域优先）挂载到枢纽上，并将类型化操作转换为不透明的 KV 单元原语。 |
+| `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | 等待所有已配置后端就绪，然后将领域形态发布为一个受生命周期约束的服务，用于类型化持久状态。 |
+| `ctx.workspace` | `core` | [`workspace`](../packages/workspace/workspace) | - | `apiproxy` | - | 通过领域设施拥有带 WorkspaceId 品牌类型的记录；稳定的 sessionIds 账户驱动 Host RPC 与 GUI 投影。 |
+| `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference)、[`tool-session-query`](../packages/session-query/tool-session-query) | - | 该接口提供精确读取、过滤和追踪；具体后端还提供全文协调、排序、摘要片段和游标世代，而模型消费方负责工作区权限与不含游标的渲染。 |
+| `ctx.sessionReferences` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | 将当前表层中有界的对话快照投影为持久但不可信的消息上下文；Host 适配器负责提及语法。 |
+| `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm)、[`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | - | - | 负责确定性回退、最新标题折叠区，以及唯一的可选异步提供方注册。 |
+| `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop)、[`tools`](../packages/core/tools)、[`tool-fs`](../packages/fs/tool-fs)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-web`](../packages/web/tool-web) | - | 为每个步骤收集提示词各部分和面向模型的工具 schema。 |
+| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop)、[`tool-ask-user`](../packages/interaction/tool-ask-user)、[`tool-bash`](../packages/bash/tool-bash)、[`tool-cordis`](../packages/self-modification/tool-cordis)、[`tool-fs`](../packages/fs/tool-fs)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-skill`](../packages/skill/tool-skill)、[`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-todo`](../packages/todo/tool-todo)、[`tool-web`](../packages/web/tool-web) | - | 注册能力，负责 Code Mode 传输，并让调用依次经过策略前处理、单调守卫、环绕分派、策略后处理和最终结果观测。 |
+| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/interaction/user-interaction) | - | [`tool-ask-user`](../packages/interaction/tool-ask-user) | - | UI 入口提供当前生效的人工回答提供方；tool-ask-user 在提供方无关的 ask() promise 上暂停工具调用。 |
+| `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | 折叠已记录的计划／模式状态，在轮次边界刷新用户选择，渲染由部署方拥有的指导信息，注册 /plan，并在状态转换期间保持计划退出 schema 稳定。 |
+| `ctx.commands` | `core` | [`commands`](../packages/interaction/commands) | - | - | - | 插件注册直接面向人的命令，而不会把调用发送给模型。 |
+| `ctx.sessionProjections` | `core` | [`session-projection`](../packages/session/session-projection) | - | [`tool-todo`](../packages/todo/tool-todo)、[`session-title`](../packages/session/session-title)、[`host-apiproxy`](../packages/host/apiproxy) | - | 各领域注册由状态驱动的折叠单元；主动驱动过程维护每个会话的水位状态，api-proxy 提供基线并推送发生变化的值。 |
+| `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | 按会话持久保存投影单元状态的检查点（节流检查点，以及轮次／结束／分离时的必选检查点），并提供冷读取阶梯：缓存行加持久化尾部回放，因此列表读取永远不需要加载完整日志。 |
+| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge)、[`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | 合并提供方的 skill（技能）目录；tool-skill 渲染会话前缀目录，并加载完整的 skill 正文。 |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop)、[`acp`](../packages/acp/acp)、[`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | 拥有实时 Agent 句柄、创建／恢复工厂 seam，以及进程本地的发起方传播。 |
+| `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | 唯一的具体循环插件；扩展包依赖 dsh-agent 的事件和服务，而不依赖此包。 |
+| `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | 从会话日志折叠带修订版本的目标状态，并将实时延续激活保留在进程本地。 |
+| `ctx.e2b` | `core` | [`e2b`](../packages/e2b/e2b) | - | [`fs-e2b`](../packages/e2b/fs-e2b)、[`subprocess-e2b`](../packages/e2b/subprocess-e2b) | - | 拥有一个共享的 E2B SDK 句柄、远程工作目录和最终沙箱处置，使两个基础 E2B 提供方处于同一个 Linux 运行时中。 |
+| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local)、[`subprocess-e2b`](../packages/e2b/subprocess-e2b) | [`bash-local`](../packages/bash/bash-local)、[`bash-sandbox`](../packages/bash/bash-sandbox)、[`pty-local`](../packages/pty/pty-local)、[`lsp-local`](../packages/lsp/lsp-local)、[`subagent-acp`](../packages/subagent/subagent-acp)、[`subagent-codex`](../packages/subagent/subagent-codex)、[`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | Bash 执行器、PTY shell 后端、LSP Host，以及进程外 ACP、Codex 和 Claude Code subagent 后端都通过 ctx.subprocess 执行 spawn；该服务负责进程坐标、进程树／会话生命周期、stdio 处置、终端机制和 kill 升级。 |
+| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local)、[`bash-sandbox`](../packages/bash/bash-sandbox)、[`pwsh-local`](../packages/bash/pwsh-local) | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pwsh`](../packages/bash/tool-pwsh)、[`hooks-claude`](../packages/hooks/hooks-claude)、[`hooks-codex`](../packages/hooks/hooks-codex) | - | 面向模型的 shell 工具和钩子桥接消费此 seam；沙箱、远程或 PowerShell 执行器可以替换 bash-local，而无需改动这些消费方。 |
+| `ctx.bashEnv` | `core` | [`bash-env`](../packages/bash/bash-env) | - | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pwsh`](../packages/bash/tool-pwsh) | - | 插件声明限定于 effect 作用域的 DSH_* 事实；每个 shell 工具在每次执行时收集一份可信快照，其执行器据此重建命名空间。 |
+| `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | 注册表负责精确到 Agent 的会话身份和清理；后端负责终端机制，tool-pty 则提供限定于所有者作用域的模型接口。 |
+| `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox)、[`pty-local`](../packages/pty/pty-local) | - | 消费方交出即将执行 spawn 的确切 argv；与宿主共享文件系统和内核的后端按每次调用的策略包装该 argv，并报告强制执行情况。 |
+| `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/bash/bash-sandbox)、[`fs-sandbox`](../packages/fs/fs-sandbox)、[`pty-local`](../packages/pty/pty-local) | - | 统一保存部署默认模式和工作区根目录；只有沙箱执行器和提供方读取该服务（工具层使用它同时导出的纯 `sandbox/mode` 折叠区）。两类强制执行组件都读取该服务，因此 bash 与 fs 不会限制到不同的根目录。 |
+| `ctx.approval` | `seam` | `approval` | [`acp`](../packages/acp/acp) | [`tools`](../packages/core/tools)、[`tool-bash`](../packages/bash/tool-bash) | - | 一次性权限决策通过 `approval/request` waterfall（瀑布式事件）分派；回答方是监听器（即 ACP 为自身 agent 提供的桥接），没有回答方时以 `unavailable` 关闭失败。 |
+| `ctx.permission` | `core` | [`permission`](../packages/interaction/permission) | - | - | - | 面向用户的预设表（`workspace-write`／`danger-full-access`），将沙箱模式与审批策略选项组合在一起；一次切换会写入一个 `permission/preset` 事件，并贯通到两个选项事件。 |
+| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | 使用 Host 提供的异步绑定运行一段由模型编写的程序；各后端采用不同的基础环境和语言（工具注册表在 Code Mode 下消费该服务）。 |
+| `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local)、[`fs-sandbox`](../packages/fs/fs-sandbox)、[`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs 通过 ctx.fs 执行读取／写入／编辑；fs-sandbox 按共享沙箱模式限制变更；fs-policy 通过 fs/* 事件门禁贡献基于观测状态的检查。 |
+| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；面向模型的压缩工具仍处于暂缓状态。 |
+| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn)、[`subagent-fork`](../packages/subagent/subagent-fork)、[`subagent-acp`](../packages/subagent/subagent-acp)、[`subagent-codex`](../packages/subagent/subagent-codex)、[`subagent-claude-code`](../packages/subagent/subagent-claude-code)、[`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-subagent-control`](../packages/subagent/tool-subagent-control)、[`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输；该服务还负责可选的、基于 Activation 的延续编排，tool-subagent 选择一次性或可延续委派，tool-subagent-control 传递后续消息，而 tool-ralph 要求一条全新的结构化输出路由。 |
+| `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-tasks`](../packages/tasks/tool-tasks) | - | 生产方（后台 bash、PTY 发送和 subagent 委派）登记正在运行的工作；tool-tasks 是面向模型的控制接口，用于读取、列出和终止这些工作；tasks-local 是进程本地注册表。 |
+| `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa)、[`web-search-perplexity`](../packages/web/web-search-perplexity)、[`web-search-deepseek`](../packages/web/web-search-deepseek)、[`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | 搜索和抓取提供方注册到同一个 ctx.web seam；tool-web 负责稳定的面向模型名称。 |
+| `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | 后端保存过大的工具文本，并返回面向模型的定位信息和取回提示；spill-policy 是 tools/post-execute 消费方，负责决定何时 spill。 |
+| `ctx.directoryPicker` | `seam` | `directory-picker` | `directory-picker-native`、`directory-picker-browse` | `apiproxy` | - | 带判别标记的交互能力：原生后端在 Host 显示设备上打开一个操作系统选择器，浏览后端为应用内浏览器提供列表与创建原语；双端后端通过其浏览器侧填充 ui-workspace 目录流程的 slot（不通过协议发布）。 |
+| `ctx.httpServer` | `core` | `webserver` | - | `connection`、`modules`、`hmr` | - | 普通的 node:http 载体：具名路由注册表、索引转换 tap，以及静态 dist 回退；Web 传输插件注册自己的路由。 |
+| `ctx.clientModuleHost` | `core` | `modules` | - | `hmr` | - | 通过增量 dshClient 扫描组合 __DSH_BOOT__ 入口图，提供插件组合包，并通知重建／图变更订阅方。 |
+| `ctx.workflows` | `seam` | [`workflow`](../packages/workflow/workflow) | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | [`tool-workflow`](../packages/workflow/tool-workflow)、[`tool-ralph`](../packages/workflow/tool-ralph) | - | 每个上下文使用一个引擎（bash 形态，无具名提供方注册表）；通用工作流与固定 Ralph 消费方启动运行，其中的 agent() 调用通过 ctx.subagents 扇出。 |
+
+维护模式：混合模式。服务从 Cordis 声明中发现；接口、实现和消费方角色在 `scripts/gen-doc-graphs.ts` 中分类，并设有完整性守卫。
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
new file mode 100644
index 0000000000..bff77bc092
--- /dev/null
+++ b/docs/config-catalog.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 docs/config-catalog.md
+config-catalog.md: eb4472d629e41f154384549245ecce1c8ec266e2
+config-catalog.zh.md: 42c1f6e85c416c68f18b8b2976300dec7e32dbc4
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
new file mode 100644
index 0000000000..42c1f6e85c
--- /dev/null
+++ b/docs/config-catalog.zh.md
@@ -0,0 +1,2684 @@
+<!-- 英文源文件由 scripts/gen-config-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-config-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/config-catalog.md` 重新记录配对。 -->
+
+# 插件配置目录
+
+[English](config-catalog.md) | 中文
+
+`cordis.yml` 条目可以设置的每个 `config:` 块：针对每个可加载的运行框架包，原样列出其 `apply` 函数或服务构造函数接收的配置声明（包括 JSDoc），并附上所有引用类型——包内类型直接粘贴，其他类型则提供链接。粘贴的内容是插件声明的完整配置类型——运行时 schema 有意排除的字段是仅供运行时使用的 seam（其自身的 JSDoc 会如此说明），不能通过 `cordis.yml` 设置。这是以**部署**为轴的参考文档——插件作者所依据的连接方式请参阅各[子系统页面](subsystems/core.md)中的生成 `cordis-surface` 区域，面向模型的工具 schema 请参阅[工具目录](tool-catalog.md)，而 [subsystems/](subsystems/core.md) 则记录了这些声明所引用的类型。
+
+英文源文件由源代码（`scripts/gen-config-catalog.ts`）生成，并通过 `pnpm run verify-config-catalog`（`doc-sync` 的一部分）验证为最新；本中文文件作为经评审对侧通过双语配对维护。声明块使用 `ts config-catalog` 围栏（doc-typecheck 会跳过它，因为单独引用导入项的声明无法独立编译）。英文生成器还会将运行时 schemastery schema 与粘贴的声明进行交叉核对——每个经 schema 验证的键（包括嵌套键）都必须能在声明的配置类型中找到——因此，粘贴内容无法隐藏加载器接受的字段。
+
+`Requires:` 行列出插件通过 `inject` 注入的服务键：其 `cordis.yml` 树还必须加载这些服务的提供者。范围限定为运行框架层级（`packages/`）；配置树还可能加载的 vendored cordis 插件（`hmr`、控制台日志记录器等）固定为上游源代码（参见 [vendoring policy](../vendor/README.md)），未收录于此目录。
+
+## `@deepseek-ai/dsh-acp`
+
+需要：`agents`
+
+```ts config-catalog
+/** Plugin config: the provider/model target used for each ACP-created agent. */
+export interface AcpConfig {
+  /** Provider route for created agents. */
+  provider?: string
+  /** Model name for created agents. */
+  model?: string
+  /** Runtime-only transport override; production uses stdio. */
+  stream?: Stream
+}
+```
+
+依赖：`Stream`（`@agentclientprotocol/sdk`）
+
+来源：[`packages/acp/acp/src/index.ts:70`](../packages/acp/acp/src/index.ts)
+
+## `@deepseek-ai/dsh-acp-demo`
+
+```ts config-catalog
+/**
+ * App config: the swappable per-deployment values. `provider` and `model` configure
+ * each agent the ACP bridge creates at `session/new`; `persona` is the
+ * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is
+ * the explicit model-facing tool order (forwarded to the system-prompt plugin);
+ * `tools` is the tool registry's config (its presentation `mode`, forwarded
+ * through agent-spine-demo); `persistenceRoot` is the JSONL backend's directory.
+ */
+export interface Config {
+  /** Provider route for ACP-created agents. */
+  provider: string
+  /** Model name for ACP-created agents (must have a registered adapter). */
+  model: string
+  /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */
+  maxParallelToolCalls?: number
+  /** Deployment persona (the system-prompt plugin's `persona` config). */
+  persona?: string
+  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
+  toolOrder?: string[]
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo; see dsh-tools). */
+  tools?: ToolsConfig
+  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
+  dshHome?: string
+  /** Fallback session-title limits forwarded through agent-spine-demo. */
+  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
+  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
+  persistenceRoot?: string
+  /** Write delta-chunk runs as packed storage rows (the JSONL backend's `packChunks`). Defaults to `true`. */
+  packChunks?: boolean
+  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
+  persistenceCompression?: JsonlCompression
+  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
+  workspaceContext: agentCore.Config['workspaceContext']
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
+  skills?: agentCore.SkillConfig
+  /** Model-facing bash tool config forwarded through agent-core. */
+  toolBash?: NonNullable<agentCore.Config['toolBash']>
+  /** Generic background-task controls forwarded through agent-core; set false to omit their tool surface. */
+  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
+  /** Persisted same-session goals; owner defaults enable them, or false disables the stack and tools. */
+  goals?: agentCore.GoalConfig | false
+}
+```
+
+依赖：[`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`JsonlCompression`](../packages/session/session-persistence-jsonl/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
+
+来源：[`packages/examples/acp-demo/src/index.ts:39`](../packages/examples/acp-demo/src/index.ts)
+
+## `@deepseek-ai/dsh-agent-loop`
+
+需要：`agents` · `sessions` · `llm` · `tools` · `systemPrompt`
+
+```ts config-catalog
+/** Agent-loop plugin configuration. */
+export interface Config {
+  /**
+   * Maximum parallel-safe calls in flight per agent step. `1` is serial;
+   * omission defaults to {@link DEFAULT_MAX_PARALLEL_TOOL_CALLS}.
+   */
+  maxParallelToolCalls?: number
+  /** Agents created or resumed at plugin startup. */
+  agents: (AgentOptions & {
+    /** Stable config label used in logs and as the fresh combined-id prefix. */
+    id: string
+    /** Optional stable identity; remounts resume its materialized history, while first use creates it fresh. */
+    sessionId?: SessionId
+    /** Optional workspace for a fresh session. */
+    cwd?: string
+    /** Persisted session to resume instead of creating a fresh session. */
+    resumeSessionId?: SessionId
+  })[]
+}
+```
+
+依赖：[`AgentOptions`](subsystems/core.md) · [`SessionId`](subsystems/core.md)
+
+来源：[`packages/core/agent-loop/src/index.ts:236`](../packages/core/agent-loop/src/index.ts)
+
+## `@deepseek-ai/dsh-agent-spine-demo`
+
+```ts config-catalog
+/**
+ * Bundle config: each field forwarded verbatim to the child that owns it —
+ * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
+ * bridge, simply omits it), `includeHarnessIdentity`, `persona`, and `toolOrder`
+ * to the system-prompt plugin (the fixed opener, deployment persona, and explicit
+ * model-facing tool order), the `tools` object to the tool registry (its presentation `mode`),
+ * `dshHome` to bash environment and local skill discovery, `sessionTitle` to
+ * the fallback title service, `skills` to the
+ * skill registry/local provider/tool consumer, `workspaceContext` to the
+ * workspace-context loader, and `toolBash`/`toolTasks` to the model-facing tool
+ * plugins this bundle owns. Provider adapters own their `retryPolicy`; this
+ * bundle always mounts its executor.
+ * `goals` opts into and configures the persisted goal domain plus its model tool
+ * and same-session driver; `invariants` configures global and package-filtered
+ * relational checks. Owner schemas supply defaults for optional input;
+ * workspace context instead requires an explicit byte budget or `false` because
+ * it changes model-visible input. Producer opt-in stays producer-local:
+ * `toolBash` configures bash only; independently composed producers keep their
+ * own config. Set `toolBash: false` when another plugin owns the model-facing
+ * `bash` name.
+ */
+export interface Config {
+  /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
+  agents?: AgentLoopConfig['agents']
+  /** Agent-loop concurrency cap; `1` is serial. */
+  maxParallelToolCalls?: AgentLoopConfig['maxParallelToolCalls']
+  /** Whether the system prompt includes the fixed Harness identity (default true). */
+  includeHarnessIdentity?: SystemPromptConfig['includeHarnessIdentity']
+  /** The deployment persona (see dsh-system-prompt's `Config`). */
+  persona?: SystemPromptConfig['persona']
+  /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */
+  toolOrder?: SystemPromptConfig['toolOrder']
+  /** The tool registry's config — its presentation `mode` (see dsh-tools' `Config`). */
+  tools?: ToolsConfig
+  /** DeepSeek Harness home directory shared by shell context and local skill discovery. */
+  dshHome?: string
+  /** Deterministic fallback and accepted-title limits; omission uses the bundle's example policy. */
+  sessionTitle?: SessionTitleConfig
+  /** Workspace-context loader controls with an explicit byte budget; set `false` for hermetic prompts. */
+  workspaceContext: workspaceContext.Config | false
+  /**
+   * Skill registry, local provider, and model-facing consumer config.
+   * Skills use `enabled` because one nested config controls a provider stack;
+   * single model-tool plugins use `Config | false` to disable that one consumer.
+   */
+  skills?: SkillConfig
+  /** Model-facing bash tool config, or false when another plugin owns `bash`. */
+  toolBash?: toolBash.Config | false
+  /** Generic background-task controls; set false to keep the task service without model-facing task tools. */
+  toolTasks?: toolTasks.Config | false
+  /** Global enablement and package-name filters for invariant companions. */
+  invariants?: InvariantConfig
+  /** Opt-in persisted same-session goal stack; set false or omit to leave it unmounted. */
+  goals?: GoalConfig | false
+}
+
+/** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */
+export interface SkillConfig {
+  /** Mount the bundled local skill provider and model-facing skill tool (default true). */
+  enabled?: boolean
+  /** Registry-level discovery cache settings. */
+  registry?: SkillRegistryConfig
+  /** Local filesystem skill provider settings. */
+  local?: SkillLocal.Config
+  /** Model-facing skill catalog and tool settings. */
+  tool?: toolSkill.Config
+}
+
+/** Persisted goal domain, model-tool policy, and same-session driver config. */
+export interface GoalConfig {
+  /** Goal-domain creation defaults. */
+  domain?: GoalDomainConfig
+  /** Model-facing goal-tool authority policy. */
+  tool?: toolGoal.Config
+}
+```
+
+依赖：[`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`GoalDomainConfig`](#deepseek-aidsh-goal) · [`InvariantConfig`](#deepseek-aidsh-invariants) · [`SessionTitleConfig`](#deepseek-aidsh-session-title) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`toolBash`](../packages/bash/tool-bash/src/index.ts) · [`toolGoal`](../packages/goal/tool-goal/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) · [`toolTasks`](../packages/tasks/tool-tasks/src/index.ts) · [`workspaceContext`](../packages/context/workspace-context/src/index.ts)
+
+来源：[`packages/examples/agent-spine-demo/src/index.ts:90`](../packages/examples/agent-spine-demo/src/index.ts)
+
+## `@deepseek-ai/dsh-bash-env`
+
+```ts config-catalog
+/** Plugin config (all optional — the built-in facts resolve without defaults). */
+export interface Config {
+  /** DeepSeek Harness home directory exposed as `DSH_HOME`; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+}
+```
+
+来源：[`packages/bash/bash-env/src/index.ts:29`](../packages/bash/bash-env/src/index.ts)
+
+## `@deepseek-ai/dsh-bash-local`
+
+需要：`subprocess`
+
+```ts config-catalog
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+  /** Default working directory for commands (default: process.cwd()). */
+  cwd?: string
+  /** Default foreground timeout in milliseconds. */
+  timeoutMs?: number
+  /** Upper bound for per-call timeout overrides. */
+  maxTimeoutMs?: number
+  /** Per-stream in-memory output cap; overflow spills to a temp file. */
+  maxOutputBytes?: number
+  /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
+  maxSpillBytes?: number
+  /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
+  graceMs?: number
+}
+```
+
+来源：[`packages/bash/bash-local/src/index.ts:40`](../packages/bash/bash-local/src/index.ts)
+
+## `@deepseek-ai/dsh-bash-sandbox`
+
+需要：`subprocess` · `sandbox` · `sandboxPolicy`
+
+```ts config-catalog
+/**
+ * Plugin config: the local executor's knobs, verbatim. The sandbox policy —
+ * the default mode and fallback `workspace-write` root — is NOT here: it lives
+ * on `ctx.sandboxPolicy` (`@deepseek-ai/dsh-sandbox-policy`), which resolves
+ * each calling session's mode and cwd for every enforcing capability. The runner
+ * choice is likewise the `ctx.sandbox` provider's config, not this executor's.
+ */
+export type Config = LocalConfig
+```
+
+依赖：[`LocalConfig`](#deepseek-aidsh-bash-local)
+
+来源：[`packages/bash/bash-sandbox/src/index.ts:35`](../packages/bash/bash-sandbox/src/index.ts)
+
+## `@deepseek-ai/dsh-client-connection`
+
+需要：`httpServer`
+
+```ts config-catalog
+/** Plugin config: the deployment's non-loopback serving authorities. */
+export interface ConnectionConfig {
+  /**
+   * Authorities this deployment serves beyond loopback: exact `host:port`, or
+   * port-less `host` matching any port. The /api trust fence refuses any
+   * request whose Host is neither loopback nor listed here, so a
+   * non-loopback (`0.0.0.0`) deployment must declare the names it is reached
+   * by (the dsh CLI derives the machine's LAN IP literals itself). An entry
+   * that is not a bare, canonical authority fails the plugin load.
+   */
+  trustedHosts?: string[]
+}
+```
+
+来源：[`packages/client/connection/src/index.ts:32`](../packages/client/connection/src/index.ts)
+
+## `@deepseek-ai/dsh-client-hmr`
+
+需要：`clientModuleHost` · `httpServer`
+
+```ts config-catalog
+/** Plugin config, validated by the same-named schemastery schema. */
+export interface Config {
+  /** Bundle stat-poll interval in milliseconds (default 500, the build-side watcher's polling default). */
+  pollIntervalMs?: number
+}
+```
+
+来源：[`packages/client/hmr/src/index.ts:29`](../packages/client/hmr/src/index.ts)
+
+## `@deepseek-ai/dsh-code-runtime-worker`
+
+```ts config-catalog
+/** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */
+export interface Config {
+  /**
+   * Busy-time budget in milliseconds: the run fails with kind `'timeout'`
+   * once the worker's MEASURED event-loop active time
+   * (`worker.performance.eventLoopUtilization()`) exceeds this. Metering
+   * measured busy time — not wall time, not host-side pending-call
+   * bookkeeping — is what makes the budget both fair (a program awaiting a
+   * slow tool accrues nothing) and ungameable (a hot loop accrues whether
+   * or not a decoy dispatch is in flight).
+   */
+  computeMs?: number
+  /**
+   * Wall-clock ceiling in milliseconds; never pauses for anything. The
+   * backstop for what busy-time cannot see (a program awaiting a promise
+   * nobody will resolve). At most `2_147_483_647` (Node's maximum
+   * `setTimeout` delay, about 24.9 days): a longer value is rejected at load
+   * because `setTimeout` would clamp it to 1 ms.
+   */
+  maxWallMs?: number
+  /**
+   * Hard cap for serialized log-array, completion-value, and failure-message payloads;
+   * fixed result-envelope syntax is excluded.
+   */
+  maxOutputBytes?: number
+  /** The worker's max old-generation heap in MiB (`resourceLimits`); overflow kills the worker, surfacing as kind `'worker-exit'`. */
+  maxOldGenerationSizeMb?: number
+}
+```
+
+来源：[`packages/code-runtime/code-runtime-worker/src/index.ts:25`](../packages/code-runtime/code-runtime-worker/src/index.ts)
+
+## `@deepseek-ai/dsh-compact-basic`
+
+需要：`llm` · `tokenMeter` · `sessions`
+
+```ts config-catalog
+/** Basic compaction configuration with an optional exact-target policy table. */
+export interface BasicCompactConfig extends CompactPolicyConfig {
+  /** Exact provider/model overrides; duplicate targets fail plugin load. */
+  modelPolicies?: ModelCompactPolicyConfig[]
+  /** Enable automatic step-boundary pressure and overflow-recovery listeners. Defaults to `true`. */
+  auto?: boolean
+}
+
+/** Policy fields shared by the default policy and exact model overrides. */
+export interface CompactPolicyConfig {
+  /** Compact at this fraction of the model's context window. Defaults to `0.8`. */
+  thresholdRatio?: number
+  /** Recent context retained as a fraction of the model's window. Defaults to `0.16`. */
+  retainRatio?: number
+  /** Absolute recent-context budget; mutually exclusive with `retainRatio`. */
+  retainTokens?: number
+  /** Summary provider; set together with `summarizationModel`, or inherit the conversation target. */
+  summarizationProvider?: string
+  /** Summary model; set together with `summarizationProvider`, or inherit the conversation target. */
+  summarizationModel?: string
+  /** Provider generation cap for summarization. Defaults to `8192`. */
+  maxTokens?: number
+  /** Extra attempts after the first compaction when pressure remains above threshold. Defaults to `1`. */
+  compactionRetries?: number
+  /** Maximum retries after canonical context overflow; `0` disables recovery. Defaults to `1`. */
+  maxOverflowRetries?: number
+}
+
+/** Exact provider/model override merged over the default compaction policy. */
+export interface ModelCompactPolicyConfig extends CompactPolicyConfig {
+  /** Registered provider route to match. */
+  provider: string
+  /** Exact routed model id to match within `provider`. */
+  model: string
+}
+```
+
+来源：[`packages/compact/compact-basic/src/types.ts:38`](../packages/compact/compact-basic/src/types.ts)
+
+## `@deepseek-ai/dsh-compact-tool-result-prune`
+
+需要：`tokenMeter`
+
+```ts config-catalog
+/** Character-budget policy for deterministic tool-result pruning. */
+export interface ToolResultPruneConfig {
+  /** Prune when total text exceeds this many Unicode code points. Defaults to `8192`. */
+  thresholdChars?: number
+  /** Maximum leading Unicode code points retained. Defaults to `4096`. */
+  headChars?: number
+  /** Maximum trailing Unicode code points retained. Defaults to `1024`. */
+  tailChars?: number
+}
+```
+
+来源：[`packages/compact/compact-tool-result-prune/src/types.ts:4`](../packages/compact/compact-tool-result-prune/src/types.ts)
+
+## `@deepseek-ai/dsh-credentials-local`
+
+```ts config-catalog
+/** Plugin config: file location and hot-reload behavior. */
+export interface Config {
+  /** Credentials document path; defaults to `.credentials.yaml` under the harness home. */
+  path?: string
+  /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Watch the document and hot-publish external edits; defaults to true. */
+  watch?: boolean
+  /** Watcher write-settle window in milliseconds; defaults to 100. */
+  debounceMs?: number
+}
+```
+
+来源：[`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
+
+## `@deepseek-ai/dsh-e2b`
+
+```ts config-catalog
+/** Configuration for the shared E2B sandbox owner. */
+export interface Config {
+  /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */
+  apiKey?: string
+  /** Shared remote working directory, created before adapters receive the sandbox. */
+  cwd?: string
+  /** E2B sandbox lifetime in milliseconds; expiry always deletes the sandbox. */
+  timeoutMs?: number
+}
+```
+
+来源：[`packages/e2b/e2b/src/index.ts:43`](../packages/e2b/e2b/src/index.ts)
+
+## `@deepseek-ai/dsh-frontend-static`
+
+需要：`httpServer`
+
+```ts config-catalog
+/** Plugin config: the dist anchor. */
+export interface Config {
+  /** Absolute path of index.html inside the dist root. */
+  distIndex: string
+}
+```
+
+来源：[`packages/host/frontend-static/src/index.ts:28`](../packages/host/frontend-static/src/index.ts)
+
+## `@deepseek-ai/dsh-fs-local`
+
+```ts config-catalog
+/** Configuration for the local filesystem backend. */
+export interface Config {
+  /** Base directory for relative paths. Defaults to `process.cwd()`. */
+  cwd?: string
+}
+```
+
+来源：[`packages/fs/fs-local/src/index.ts:39`](../packages/fs/fs-local/src/index.ts)
+
+## `@deepseek-ai/dsh-fs-sandbox`
+
+需要：`sandboxPolicy`
+
+```ts config-catalog
+/**
+ * Plugin config: the local backend's knobs, verbatim (only `cwd`, the resolve
+ * base for relative paths). The sandbox default (mode + `workspace-write`
+ * fallback root) is NOT here — `ctx.sandboxPolicy` resolves each calling
+ * session for every enforcing capability.
+ */
+export type Config = LocalConfig
+```
+
+依赖：[`LocalConfig`](#deepseek-aidsh-fs-local)
+
+来源：[`packages/fs/fs-sandbox/src/index.ts:49`](../packages/fs/fs-sandbox/src/index.ts)
+
+## `@deepseek-ai/dsh-goal`
+
+需要：`agents`
+
+```ts config-catalog
+/** Deployment defaults for goal creation. */
+export interface Config {
+  /** Total rounds used when a create request omits its own cap. */
+  defaultMaxGoalRounds?: number
+}
+```
+
+来源：[`packages/goal/goal/src/index.ts:116`](../packages/goal/goal/src/index.ts)
+
+## `@deepseek-ai/dsh-headless`
+
+需要：`apiProxy` · `httpServer`
+
+```ts config-catalog
+/** Plugin config: the task, patched in by the launcher. */
+export interface Config {
+  /** The prompt text for the single turn. */
+  task: string
+}
+```
+
+来源：[`packages/bundle/headless/src/index.ts:32`](../packages/bundle/headless/src/index.ts)
+
+## `@deepseek-ai/dsh-hooks-claude`
+
+需要：`bash`
+
+```ts config-catalog
+/** Plugin config: where the CC hook config lives + substitution roots. */
+export interface Config {
+  /**
+   * Path to a `hooks.json` or a settings file whose `hooks` key holds the config.
+   * Process-level: read once at load, a relative path resolves against the process
+   * launch cwd, so one config applies to the whole process.
+   * TODO(per-session-hook-config): per-session discovery of a project-local
+   * `hooks.json` from each `session/new.cwd` is not yet implemented.
+   */
+  configPath: string
+  /**
+   * Replaces `${CLAUDE_PLUGIN_ROOT}` in command strings (the plugin's root dir).
+   */
+  pluginRoot?: string
+  /**
+   * Replaces `${CLAUDE_PROJECT_DIR}` in command strings AND is exported as the
+   * `CLAUDE_PROJECT_DIR` env var for hook processes. When omitted, the env var
+   * defaults per-run to the agent's session workspace (`session.header.cwd`, the
+   * same dir the hook runs in) — Claude Code always exports this var, and common
+   * unmodified hooks reference `$CLAUDE_PROJECT_DIR` for project-relative paths.
+   */
+  projectDir?: string
+  /** Default per-hook timeout in ms when a hook sets none (CC default: 600000). */
+  defaultTimeoutMs?: number
+  /** Character cap for the `hook/result` event's persisted stderr summary. */
+  stderrSummaryMaxChars?: number
+}
+```
+
+来源：[`packages/hooks/hooks-claude/src/index.ts:45`](../packages/hooks/hooks-claude/src/index.ts)
+
+## `@deepseek-ai/dsh-hooks-codex`
+
+需要：`bash`
+
+```ts config-catalog
+/** Plugin config: where the Codex hooks.json lives + the model name for payloads. */
+export interface Config {
+  /**
+   * Path to a Codex `hooks.json`. Process-level: read once at load, a relative
+   * path resolves against the process launch cwd.
+   * TODO(per-session-hook-config): per-session project-local discovery from each
+   * `session/new.cwd` is not yet implemented.
+   */
+  configPath: string
+  /** The model name stamped on every payload (Codex includes `model` on each event). */
+  model?: string
+  /** Default per-hook timeout in ms when a hook sets none (Codex default: 600000). */
+  defaultTimeoutMs?: number
+  /** Character cap for the `hook/result` event's persisted stderr summary. */
+  stderrSummaryMaxChars?: number
+}
+```
+
+来源：[`packages/hooks/hooks-codex/src/index.ts:44`](../packages/hooks/hooks-codex/src/index.ts)
+
+## `@deepseek-ai/dsh-host-apiproxy`
+
+需要：`agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
+
+```ts config-catalog
+/**
+ * Gateway plugin config: host-level agent routing and Workspace creation root.
+ *
+ * `reasoningEffort` is deliberately absent, so the section carries one field
+ * the composition cannot. The seam resolves a section by MERGING the user
+ * layer over the composition entry per field, and an absent key cannot
+ * override a present one — so a composition-set effort would survive every
+ * later switch to a model that has none, and strand it for the next session
+ * to fail on. Effort is a per-model fact anyway: a deployment default belongs
+ * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
+ * which resolves per model rather than per gateway.
+ */
+export interface Config {
+  /** Default provider route for created agents. */
+  provider: string
+  /** Default model id. */
+  model: string
+  /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
+  workspaceRoot?: string
+}
+```
+
+来源：[`packages/host/apiproxy/src/index.ts:67`](../packages/host/apiproxy/src/index.ts)
+
+## `@deepseek-ai/dsh-host-directory-picker-browse`
+
+```ts config-catalog
+/** Validated plugin configuration. */
+export interface Config {
+  /** Complete-result bound of one listing level; see {@link BrowseDirectoryPicker.Config}. */
+  maxEntries: number
+}
+```
+
+来源：[`packages/host/directory-picker-browse/src/index.ts:181`](../packages/host/directory-picker-browse/src/index.ts)
+
+## `@deepseek-ai/dsh-host-webserver`
+
+```ts config-catalog
+/** Gateway config: the listen address. */
+export interface Config {
+  /** Listen host; the two supported values are loopback and all-interfaces. */
+  host: '127.0.0.1' | '0.0.0.0'
+  /** Listen port; zero requests an OS-assigned port. */
+  port: number
+}
+```
+
+来源：[`packages/host/webserver/src/index.ts:45`](../packages/host/webserver/src/index.ts)
+
+## `@deepseek-ai/dsh-invariants`
+
+```ts config-catalog
+/** Runtime invariant selection configured on the service plugin. */
+export interface Config {
+  /** Global switch; defaults to `true`. */
+  readonly enabled?: boolean
+  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
+  readonly package_allowlist?: string[]
+  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
+  readonly package_blocklist?: string[]
+}
+```
+
+来源：[`packages/support/invariants/src/index.ts:15`](../packages/support/invariants/src/index.ts)
+
+## `@deepseek-ai/dsh-jsonrpc`
+
+需要：`agents`
+
+```ts config-catalog
+/** JSON-RPC deployment config plus runtime-only test seams. */
+export interface JsonRpcConfig {
+  /** Report max-token turn/subagent termination as a successful SDK result. */
+  maxTokensAsSuccess?: boolean
+  /** Transport input override; production uses `process.stdin`. */
+  input?: Readable
+  /** Transport output override; production uses `process.stdout`. */
+  output?: Writable
+  /** Process-exit override; production uses `process.exit`. */
+  exit?: (code: number) => void
+}
+```
+
+依赖：`Readable`（`node:stream`）· `Writable`（`node:stream`）
+
+来源：[`packages/scaffold/server/src/index.ts:25`](../packages/scaffold/server/src/index.ts)
+
+## `@deepseek-ai/dsh-llm-deepseek`
+
+需要：`llm`
+
+```ts config-catalog
+/**
+ * Plugin config, validated by the same-named schemastery schema and doubling
+ * as the `llm-deepseek` settings-section shape. Every field is optional in
+ * yml: a missing API key resolves through {@link Config.apiKeyEnv} at each
+ * request (a request without any key fails with `MISSING_CREDENTIAL`, not at
+ * plugin load), omitted thinking mode uses the provider default, and omitted
+ * reasoning effort resolves to `high`.
+ */
+export interface Config {
+  /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
+  apiKeyEnv?: string
+  /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */
+  baseURL?: string
+  /** Deployment thinking policy; `disabled` limits every conversation request to `off`. */
+  thinking?: 'enabled' | 'disabled'
+  /** Default thinking effort (default `high`); `off` disables thinking per request. */
+  reasoningEffort?: 'off' | 'high' | 'max'
+  /** Default per-request output cap (default 256,000); a model's own cap and explicit request values win. */
+  maxTokens?: number
+  /** Positive context capacity used when the selected model has no exact value (default 1,000,000). */
+  defaultContextWindow?: number
+  /** Advisory models shown by discovery consumers; defaults to V4 Flash and V4 Pro. */
+  models?: DeepSeekCatalogModel[]
+  /** Maximum provider idle time while one stream read is outstanding (default five minutes). */
+  streamIdleTimeoutMs?: number
+  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  retryPolicy?: RetryPolicyConfig
+}
+
+/** One optional model entry advertised by the direct-fetch adapter. */
+export interface DeepSeekCatalogModel {
+  /** Wire model id accepted by the configured endpoint. */
+  id: string
+  /** Selector label; defaults to {@link id}. */
+  name?: string
+  /** Optional selector detail for deployments with similar model variants. */
+  description?: string
+  /** Known combined request/response context capacity; omitted when deployment metadata is unavailable. */
+  contextWindow?: number
+  /** Per-request output cap for this model; omission falls back to the profile's {@link DeepSeekConnectionOptions.maxTokens}. */
+  maxTokens?: number
+}
+```
+
+依赖：[`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
+
+来源：[`packages/llm/llm-deepseek/src/index.ts:61`](../packages/llm/llm-deepseek/src/index.ts)
+
+## `@deepseek-ai/dsh-llm-pi-ai`
+
+需要：`llm`
+
+```ts config-catalog
+/** Plugin configuration: the provider routes this instance owns. */
+export interface Config {
+  /**
+   * pi-ai provider routes, keyed by provider. An empty (or omitted) dict is
+   * the dormant settings-driven posture: the adapter mounts with no routes
+   * and registers them the moment a settings section supplies profiles.
+   */
+  providers?: Record<string, PiAiProviderProfile>
+}
+
+/** Configuration for one pi-ai provider route; the `providers` dict key IS the route. */
+export interface PiAiProviderProfile {
+  /** Credential reference (environment-variable name) resolved per request through `ctx.credentials`. */
+  apiKeyEnv?: string
+  /** Name shown by configuration surfaces; defaults to the route key. */
+  displayName?: string
+  /**
+   * Wire protocol every model on this route speaks. Omission keeps each
+   * installed catalog model's own protocol, which is why a catalog route needs
+   * no protocol at all; a route the catalog does not ship must name one.
+   */
+  api?: string
+  /** Endpoint for this route's models; defaults to the installed catalog's endpoint. */
+  baseURL?: string
+  /**
+   * This route's model catalog. Omission serves the installed catalog for the
+   * route unchanged; an explicit list replaces it, each entry defaulting its
+   * unset fields from the installed model of the same id.
+   */
+  models?: PiAiModelProfile[]
+  /**
+   * Installed-catalog customizations by model id: each entry reshapes that
+   * one model with the same fields a {@link models} entry takes, while the
+   * rest of the catalog keeps serving untouched. Only meaningful on a catalog
+   * route with no `models` list — `models` already replaces the catalog, so
+   * an override beside it, on a route the catalog does not ship, or naming a
+   * model the catalog does not describe is refused rather than skipped.
+   */
+  modelOverrides?: Record<string, PiAiModelOverride>
+  /**
+   * Reasoning-dispatch switches for every `openai-completions` model on this
+   * route; each model's own `compat` overrides per field. What neither sets
+   * keeps the installed catalog entry's value, then pi-ai's baseURL-derived
+   * detection.
+   */
+  compat?: PiAiCompatProfile
+  /**
+   * Context capacity for a model this route lists that neither the entry nor
+   * the installed catalog sizes (default 262,144). A guess by construction, so
+   * a deployment whose gateway serves smaller models corrects it here.
+   */
+  defaultContextWindow?: number
+  /**
+   * Output capability for a model this route lists that neither the entry nor
+   * the installed catalog sizes (default 32,768). This sizes the model; it
+   * never becomes a per-request cap on its own.
+   */
+  defaultMaxTokens?: number
+  /** Provider request headers; Harness attribution wins reserved names. */
+  headers?: Record<string, string>
+  /** Provider-neutral pi-ai reasoning level. */
+  reasoning?: ModelThinkingLevel
+  /** Token budgets used by reasoning providers that support them. */
+  thinkingBudgets?: ThinkingBudgets
+  /** Prompt-cache retention preference. */
+  cacheRetention?: CacheRetention
+  /** Streaming transport preference. */
+  transport?: Transport
+  /** HTTP/provider SDK timeout in milliseconds. */
+  timeoutMs?: number
+  /** WebSocket connection timeout in milliseconds. */
+  websocketConnectTimeoutMs?: number
+  /** Maximum provider idle time while one stream read is outstanding. */
+  streamIdleTimeoutMs?: number
+  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  retryPolicy?: RetryPolicyConfig
+}
+
+/** One configured model entry: an id plus the catalog fields it overrides. */
+export interface PiAiModelProfile {
+  /** Model id sent to the provider and accepted by {@link GenerateOptions.model}. */
+  id: string
+  /** Display name for selectors; defaults to the catalog name, then the id. */
+  name?: string
+  /** Maximum combined request and response context in tokens. */
+  contextWindow?: number
+  /**
+   * Maximum output tokens. Configuring one also makes it this model's
+   * per-request default; a value inherited from the installed catalog, or the
+   * route's fallback, is the model's capability and never becomes a request
+   * default on its own.
+   */
+  maxTokens?: number
+  /**
+   * Selectable reasoning efforts. Absent inherits the installed catalog
+   * entry's capability (a hand-declared model has none and does not reason);
+   * `false` declares a non-reasoning model, which is how a profile strips
+   * reasoning from a catalog model its gateway cannot serve; a non-empty dict
+   * declares the offered levels and their wire spellings.
+   */
+  reasoningEfforts?: false | PiAiReasoningEfforts
+  /** Reasoning-dispatch switches for this model, winning over the route's. */
+  compat?: PiAiCompatProfile
+}
+
+/**
+ * Customization of one installed catalog model, keyed by its id in the
+ * route's `modelOverrides` dict — the same fields a `models` entry may set,
+ * with the id living in the key. Unlike a `models` list, overrides leave the
+ * rest of the catalog serving untouched, which is what makes "correct one
+ * model, keep the other thirty-seven" a three-line edit.
+ */
+export type PiAiModelOverride = Omit<PiAiModelProfile, 'id'>
+
+/**
+ * Reasoning-dispatch compatibility switches, set on the route (its models'
+ * default) or per model (winning over the route). Only the switches pi-ai's
+ * reasoning dispatch reads are offered; the rest of pi-ai's compat surface
+ * keeps its baseURL-derived auto-detection. pi-ai types both fields only on
+ * `OpenAICompletionsCompat` — the other wire protocols carry their reasoning
+ * shape in the protocol itself — so resolution rejects a model-level switch
+ * anywhere else, while a route-level default skips past models it cannot fit.
+ */
+export interface PiAiCompatProfile {
+  /** Reasoning parameter shape the endpoint expects; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+  thinkingFormat?: PiAiThinkingFormat
+  /** Whether the endpoint accepts `reasoning_effort`; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+  supportsReasoningEffort?: boolean
+}
+
+/**
+ * Selectable reasoning efforts for one model: each key is a level the model
+ * offers (and selectors show), and its value is the wire spelling dispatch
+ * sends for it. `off` alone may leave its value empty — "supported, send
+ * nothing" — because for most providers not thinking is the parameter's
+ * absence; every other declared level must name a wire value. A level absent
+ * from the dict is not offered.
+ */
+export type PiAiReasoningEfforts = Partial<Record<ModelThinkingLevel, string | null>>
+
+/** One reasoning-dispatch wire format a profile may name. */
+export type PiAiThinkingFormat = Exclude<PiThinkingFormat, WithheldThinkingFormat>
+
+/** The `compat.thinkingFormat` spellings pi-ai accepts on an `openai-completions` model. */
+type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>
+
+/**
+ * pi-ai thinking formats a profile cannot name: both drive the request through
+ * `chatTemplateKwargs`, which this configuration does not expose, so offering
+ * them would hand back a format with nothing to say.
+ */
+type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
+```
+
+依赖：`CacheRetention`（`@earendil-works/pi-ai`）· `ModelThinkingLevel`（`@earendil-works/pi-ai`）· `OpenAICompletionsCompat`（`@earendil-works/pi-ai`）· [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts) · `ThinkingBudgets`（`@earendil-works/pi-ai`）· `Transport`（`@earendil-works/pi-ai`）
+
+来源：[`packages/llm/llm-pi-ai/src/config.ts:142`](../packages/llm/llm-pi-ai/src/config.ts)
+
+## `@deepseek-ai/dsh-llm-replay`
+
+需要：`llm`
+
+```ts config-catalog
+/** Plugin config: the {@link ReplayConfig} inputs, each defaulting to its `DSH_SNAPSHOT_*` env var in `apply`. */
+export interface Config {
+  /** Override the fixture path; defaults to `$DSH_SNAPSHOT_FILE`. */
+  file?: string
+  /** Override the sidecar path; defaults to `$DSH_SNAPSHOT_OVERRIDE`. */
+  overrideFile?: string
+  /**
+   * Override the child-log paths; defaults to `$DSH_SNAPSHOT_CHILD_FILES` (a
+   * path-separator-delimited list). Each is a recorded subagent session log for
+   * a nested-agent scenario; absent/empty for a single-session scenario.
+   */
+  childFiles?: string[]
+  /** Optional replay-only provider catalog; absent or empty selects catch-all waterfall replay. */
+  providers?: ReplayProviderConfig[]
+  /** Optional per-chunk pacing delay in ms (see {@link ReplayConfig.paceMs}); absent keeps burst yield. */
+  paceMs?: number
+}
+
+/** One provider route exposed by the replay adapter. */
+export interface ReplayProviderConfig {
+  /** Provider route used for replay requests. */
+  id: string
+  /** Selector label; defaults to {@link id}. */
+  name?: string
+  /** Advisory models exposed to replay scenarios that exercise discovery. */
+  models?: ReplayModelConfig[]
+  /** Optional provider-owned retry policy used by assembled recovery snapshots. */
+  retryPolicy?: RetryPolicyConfig
+}
+
+/** One model exposed by a replay-only provider catalog. */
+export interface ReplayModelConfig {
+  /** Model id used for replay requests. */
+  id: string
+  /** Selector label; defaults to {@link id}. */
+  name?: string
+  /** Optional selector description. */
+  description?: string
+  /** Optional positive integer context capacity published by the replay adapter. */
+  contextWindow?: number
+}
+```
+
+依赖：[`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
+
+来源：[`packages/support/llm-replay/src/index.ts:744`](../packages/support/llm-replay/src/index.ts)
+
+## `@deepseek-ai/dsh-llm-retry`
+
+需要：`agents`
+
+```ts config-catalog
+/** This policy executor has no config; providers own `retryPolicy`. */
+export type Config = Readonly<Record<string, never>>
+```
+
+来源：[`packages/llm/llm-retry/src/index.ts:46`](../packages/llm/llm-retry/src/index.ts)
+
+## `@deepseek-ai/dsh-lsp-local`
+
+需要：`fs` · `lsp` · `subprocess`
+
+```ts config-catalog
+/** Plugin configuration: provider id → local language-server configuration. */
+export interface Config {
+  /** Non-empty table of stable provider ids to independent local server configurations. */
+  servers: Record<string, LspLocalServerConfig>
+}
+
+/** One configured local language server and its host bounds. */
+export interface LspLocalServerConfig {
+  /** Executable to spawn (absolute, or resolved on PATH at load). */
+  command: string
+  /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
+  extensionToLanguage: Record<string, string>
+  /** Arguments passed to the executable (no shell). Default `[]`. */
+  args?: string[]
+  /** Extra env vars merged on top of the scrubbed ambient env. Default `{}`. */
+  env?: Record<string, string>
+  /** Static `initialize` options forwarded to the server. Default `null`. */
+  initializationOptions?: unknown
+  /** Static answer to every `workspace/configuration` item. Default `null`. */
+  configuration?: unknown
+  /** Largest single framed message accepted from the server (bytes). Default 16000000. */
+  maxMessageBytes?: number
+  /** Largest stderr tail retained for diagnostics (bytes). Default 1000000. */
+  maxStderrBytes?: number
+  /** Largest source file this host will open (bytes). Default 4000000. */
+  maxDocumentBytes?: number
+  /** Graceful `shutdown`/`exit` budget before escalation (ms). Default 5000. */
+  shutdownTimeoutMs?: number
+  /** Request-cancel and SIGTERM→SIGKILL grace (ms). Default 2000. */
+  killGraceMs?: number
+}
+```
+
+来源：[`packages/lsp/lsp-local/src/index.ts:82`](../packages/lsp/lsp-local/src/index.ts)
+
+## `@deepseek-ai/dsh-mcp-client`
+
+需要：`tools`
+
+```ts config-catalog
+/** Configuration for one stdio or Streamable HTTP MCP server. */
+export type Config = StdioConfig | StreamableHttpConfig
+
+/** Config for connecting to an MCP server via a spawned child process over stdio. */
+export interface StdioConfig {
+  /** Selects child-process stdio transport. */
+  transport: 'stdio'
+  /**
+   * Stable local namespace for this server's model-facing tool names
+   * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+   * unique across live mcp-client instances.
+   */
+  serverName: string
+  /** Executable used to start the server. */
+  command: string
+  /** Arguments passed directly, without shell interpolation. */
+  args: string[]
+  /** Extra env vars merged on top of scrubbed ambient env. */
+  env: Record<string, string>
+  /** Working directory for the child process. */
+  cwd: string
+  /** Per-tool-call timeout in milliseconds. */
+  toolCallTimeoutMs: number
+}
+
+/** Config for connecting to an MCP server over Streamable HTTP (SSE). */
+export interface StreamableHttpConfig {
+  /** Selects Streamable HTTP transport. */
+  transport: 'streamable-http'
+  /**
+   * Stable local namespace for this server's model-facing tool names
+   * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+   * unique across live mcp-client instances.
+   */
+  serverName: string
+  /** MCP endpoint URL. */
+  url: string
+  /** Additional headers attached to MCP requests. */
+  headers: Record<string, string>
+  /** Per-tool-call timeout in milliseconds. */
+  toolCallTimeoutMs: number
+}
+```
+
+来源：[`packages/mcp/mcp-client/src/index.ts:96`](../packages/mcp/mcp-client/src/index.ts)
+
+## `@deepseek-ai/dsh-permission`
+
+需要：`bash` · `approval` · `sessions`
+
+```ts config-catalog
+/** The {@link PermissionService} config: preset table and composition default. */
+export interface Config {
+  /**
+   * The preset table: name → knob bundle. Defaults to `workspace-write`
+   * (workspace-write + ask) and `danger-full-access` (danger-full-access +
+   * never). The name `custom` is reserved for the derived not-a-preset state.
+   */
+  presets?: Record<string, PresetSpec>
+  /**
+   * Default for new sessions. When omitted, the preset matching the composed
+   * sandbox and approval defaults is used.
+   */
+  defaultPreset?: string
+}
+
+/** One preset's sandbox/approval bundle and optional client presentation. */
+export interface PresetSpec {
+  /** The `sandbox/mode` value the preset writes through. */
+  sandbox: SandboxMode
+  /** The `approval/policy` value the preset writes through. */
+  approval: ApprovalPolicy
+  /** The display label a client shows for this preset; the raw table key when omitted. */
+  name?: string
+  /** One user-facing sentence on what the preset means; omitted when not configured. */
+  description?: string
+}
+```
+
+依赖：[`ApprovalPolicy`](subsystems/approval.md) · [`SandboxMode`](subsystems/sandbox.md)
+
+来源：[`packages/interaction/permission/src/index.ts:140`](../packages/interaction/permission/src/index.ts)
+
+## `@deepseek-ai/dsh-plan-mode`
+
+需要：`tools` · `systemPrompt`
+
+```ts config-catalog
+/** Deployment-owned plan guidance. */
+export interface PlanModeConfig {
+  /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
+  section: string
+}
+```
+
+来源：[`packages/plan/plan-mode/src/index.ts:69`](../packages/plan/plan-mode/src/index.ts)
+
+## `@deepseek-ai/dsh-pty-local`
+
+需要：`pty` · `sandboxPolicy` · `subprocess`
+
+```ts config-catalog
+/** Public plugin configuration. */
+export interface Config {
+  /** Backend registry type (default: `shell`). */
+  backendType?: string
+  /** Interactive shell executable (default: `/bin/bash`). */
+  shellPath?: string
+  /** Shell arguments (default: `--noprofile --norc -i`). */
+  shellArgs?: string[]
+  /** Terminal rows. */
+  rows?: number
+  /** Terminal columns. */
+  cols?: number
+  /** Maximum retained logical lines. */
+  scrollbackLines?: number
+  /** Maximum retained UTF-8 bytes. */
+  scrollbackMaxBytes?: number
+  /** Maximum bytes returned by one read or settled viewport. */
+  maxReadBytes?: number
+  /** Readiness polling interval. */
+  pollIntervalMs?: number
+  /** Delay before Linux exact syscall probes. */
+  exactProbeAfterMs?: number
+  /** Silence duration that yields `inferred_idle`. */
+  idleSilenceMs?: number
+  /**
+   * Extra wait beyond `idleSilenceMs`, once a prompt marker was seen, for the shell to
+   * regain the foreground before `inferred_idle` settles; at least one `pollIntervalMs`.
+   */
+  handoffGraceMs?: number
+  /** Absolute send wait bound. */
+  timeoutMs?: number
+  /** Grace before teardown escalates to `SIGKILL`. */
+  disposeGraceMs?: number
+}
+```
+
+来源：[`packages/pty/pty-local/src/config.ts:6`](../packages/pty/pty-local/src/config.ts)
+
+## `@deepseek-ai/dsh-pwsh-local`
+
+需要：`subprocess`
+
+```ts config-catalog
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+  /** Default working directory for commands (default: process.cwd()). */
+  cwd?: string
+  /** Default foreground timeout in milliseconds. */
+  timeoutMs?: number
+  /** Upper bound for per-call timeout overrides. */
+  maxTimeoutMs?: number
+  /** Per-stream in-memory output cap; overflow spills to a temp file. */
+  maxOutputBytes?: number
+  /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
+  maxSpillBytes?: number
+  /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
+  graceMs?: number
+  /**
+   * Explicit pwsh executable. When omitted, well-known Windows install
+   * locations and PATH entries are probed in order (PowerShell 7 install,
+   * PATH entries such as the Microsoft Store install, then Windows
+   * PowerShell 5.1), falling back to a bare `pwsh` resolved through PATH.
+   */
+  pwshPath?: string
+}
+```
+
+来源：[`packages/bash/pwsh-local/src/index.ts:54`](../packages/bash/pwsh-local/src/index.ts)
+
+## `@deepseek-ai/dsh-repeat-tool-guard`
+
+```ts config-catalog
+/**
+ * Plugin config, validated by the same-named schemastery schema plus the
+ * load-time checks in `apply` (misconfiguration fails loud: an empty
+ * `thresholds` list, a non-integer, a value below 2, or a duplicate throws at
+ * plugin load, never a silent fall-back). `include`/`exclude` entries are
+ * `*`-wildcard predicates over tool names at call time, not references to
+ * registry entries — a pattern matching no currently registered tool is valid
+ * (`exclude: [mcp_*]` must stay legal in a deployment that loads no MCP tools).
+ */
+export interface Config {
+  /** Consecutive-repeat counts that trigger a reminder (default `[3, 5, 8]`). */
+  thresholds?: number[]
+  /** Tool-name patterns to track; empty means every tool is tracked. */
+  include?: string[]
+  /** Tool-name patterns transparent to the chain (neither count nor reset). */
+  exclude?: string[]
+  /**
+   * Maximum characters of canonical arguments quoted in the DETAILED reminder
+   * (default 500). Large payloads (a `write` body, a long command) would
+   * otherwise ride into the next request unbounded — precisely in a loop
+   * scenario; the cap bounds the reminder, never the detection (the chain key
+   * always compares the FULL canonical string).
+   */
+  argumentsPreviewChars?: number
+}
+```
+
+来源：[`packages/guard/repeat-tool-guard/src/index.ts:28`](../packages/guard/repeat-tool-guard/src/index.ts)
+
+## `@deepseek-ai/dsh-repository-plugin`
+
+需要：`loader`
+
+```ts config-catalog
+/** Repository Plugin runtime and source-list configuration. */
+export interface Config {
+  /** GitHub repository sources with explicit refs and optional `.dsh-plugin` subpaths. */
+  repositories?: string[]
+  /** Persistent generation cache; defaults to `$DSH_HOME/cache/repository-plugins`. */
+  cacheDir?: string
+}
+```
+
+来源：[`packages/self-modification/repository-plugin/src/index.ts:42`](../packages/self-modification/repository-plugin/src/index.ts)
+
+## `@deepseek-ai/dsh-sandbox-local`
+
+```ts config-catalog
+/** Plugin config. All optional — `static Config` supplies the defaults. */
+export interface Config {
+  /**
+   * Override the runner argv; bwrap-shaped profile arguments are appended. A
+   * non-empty override asserts full enforcement and skips built-in selection and
+   * probing. A runner that starts but refuses its profile must be identifiable by
+   * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
+   * attributable `ENOENT` or `EACCES` with runner argv[0] provenance becomes an
+   * infrastructure failure.
+   */
+  runnerCommand?: string[]
+  /**
+   * Case-insensitive stderr substrings emitted when a configured
+   * {@link runnerCommand} refuses its profile before executing the wrapped
+   * command. Required and non-empty with `runnerCommand`; rejected without
+   * it. Each entry is a non-empty, single-line, case-insensitive substring
+   * covering the executable runner's own failure dialect.
+   */
+  runnerFailureSignatures?: string[]
+  /** Positive timeout for each functional probe; zero would mean unbounded to Node. */
+  probeTimeoutMs?: number
+}
+```
+
+来源：[`packages/sandbox/sandbox-local/src/index.ts:24`](../packages/sandbox/sandbox-local/src/index.ts)
+
+## `@deepseek-ai/dsh-sandbox-policy`
+
+```ts config-catalog
+/**
+ * Plugin config: the deployment's sandbox default. All optional — `Config`
+ * supplies the defaults (`mode: 'read-only'` is the fail-safe default; a
+ * deployment that wants a workspace-writable agent opts in explicitly). The
+ * runner choice is NOT here (it is the `ctx.sandbox` provider's config), nor
+ * is any per-family knob: this is the one shared policy home.
+ */
+export interface Config {
+  /** File-sandbox mode a session starts from (default: `read-only`). */
+  mode?: SandboxMode
+  /**
+   * Fallback root for agentless calls and sessions without a cwd (default:
+   * `process.cwd()`). Normal agent calls use their session cwd instead.
+   */
+  workspaceRoot?: string
+}
+```
+
+依赖：[`SandboxMode`](subsystems/sandbox.md)
+
+来源：[`packages/sandbox/sandbox-policy/src/index.ts:67`](../packages/sandbox/sandbox-policy/src/index.ts)
+
+## `@deepseek-ai/dsh-session-persistence-jsonl`
+
+需要：`sessions`
+
+```ts config-catalog
+/** Plugin config: where the JSONL backend keeps its session logs, and the packed-row write switch. */
+export interface Config {
+  /**
+   * Root directory for all session files. Required (no default): a default of
+   * `process.cwd()` would scatter session files as the process's cwd changes
+   * (bash calls, subprocesses). Sessions group under human-readable project
+   * directories, then per-session directories. An existing root must be a
+   * readable directory; an absent root is created on first materialization.
+   */
+  root: string
+  /**
+   * Write runs of consecutive `assistant/chunk` delta events as packed
+   * `text-chunks`/`reasoning-chunks`/`tool-call-chunks` rows (lossless,
+   * ~60% smaller logs measured on a real session). Defaults to true; false
+   * keeps one `SessionEvent` per line for diagnostics. Reading packed rows is
+   * unconditional: a log's layout never depends on this switch.
+   */
+  packChunks?: boolean
+  /** Physical encoding; defaults to checksummed Zstandard frames. */
+  compression?: JsonlCompression
+  /** Maximum cold Session preparations retained for history-to-resume reuse. */
+  preparedSessionCacheSize?: number
+  /** Fixed live-event coalescing window; not a backend completion deadline. */
+  writeBatchMaxDelayMs?: number
+}
+
+/** Physical encoding selected for JSONL session artifacts. */
+export type JsonlCompression = 'zstd' | 'none'
+```
+
+来源：[`packages/session/session-persistence-jsonl/src/index.ts:59`](../packages/session/session-persistence-jsonl/src/index.ts)
+
+## `@deepseek-ai/dsh-session-persistence-sqlite`
+
+需要：`sessions`
+
+```ts config-catalog
+/** Plugin configuration. */
+export interface Config {
+  /**
+   * Filesystem path to the SQLite database file. The special value `:memory:`
+   * opens an in-process database (tests). On filesystems with POSIX modes,
+   * missing directories and databases are created owner-only; existing path
+   * modes are preserved. Filesystem setup errors other than an existing database
+   * fail initialization. The backend does not protect confidentiality or
+   * integrity when another principal can replace the database entry in its
+   * parent directory.
+   */
+  path: string
+  /**
+   * SQLite `journal_mode` pragma. `wal` (the default) is the recorded
+   * durability model; pick a rollback-journal mode (`delete`/`truncate`/
+   * `persist`) on filesystems where WAL's shared-memory files do not work
+   * (network mounts). See {@link JournalMode}.
+   */
+  journalMode?: JournalMode
+  /** Maximum cold Session preparations retained for history-to-resume reuse. */
+  preparedSessionCacheSize?: number
+  /** Fixed live-event coalescing window; not a backend completion deadline. */
+  writeBatchMaxDelayMs?: number
+}
+
+/**
+ * Journal modes the backend will run under. `wal` is the default and the
+ * durability model the persistence ADR records; the rollback-journal modes
+ * (`delete`/`truncate`/`persist`) exist for filesystems where WAL's
+ * shared-memory files do not work (network mounts). `memory`/`off` are
+ * excluded: dropping journal durability silently contradicts what this
+ * backend promises.
+ */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+```
+
+来源：[`packages/session/session-persistence-sqlite/src/index.ts:67`](../packages/session/session-persistence-sqlite/src/index.ts)
+
+## `@deepseek-ai/dsh-session-projection-cache`
+
+需要：`storageDomain` · `sessionProjections` · `sessionPersistence` · `sessions`
+
+```ts config-catalog
+/**
+ * Plugin config. Both throttle triggers are deployment choices with no
+ * universally correct value, so the composition states them explicitly
+ * (cordis.yml); the two mandatory write points (`turn/end` and session
+ * disposal) are policy, not tunables, and always fire.
+ */
+export interface Config {
+  /** Committed events per session that force a durable checkpoint write between mandatory points. */
+  writeEveryEvents: number
+  /** Longest time (milliseconds) a dirty checkpoint may stay unwritten between mandatory points. */
+  writeIntervalMs: number
+}
+```
+
+来源：[`packages/session/session-projection-cache/src/index.ts:42`](../packages/session/session-projection-cache/src/index.ts)
+
+## `@deepseek-ai/dsh-session-query-sqlite`
+
+需要：`sessions`
+
+```ts config-catalog
+/** Combined session-query configuration backed by SQLite full-text search. */
+export interface Config extends SessionQueryConfig {
+  /**
+   * Dedicated derived-index path; `:memory:` is supported for ephemeral
+   * indexes. Missing directories and database files are created owner-only on
+   * POSIX filesystems; existing modes are preserved.
+   */
+  path: string
+  /** Open the SQLite module and handle at service activation or the first search. Defaults to `startup`. */
+  openAt?: OpenAt
+  /** SQLite journal mode. Defaults to `wal`. */
+  journalMode?: JournalMode
+  /** Page size when a request omits `limit`. At most `Number.MAX_SAFE_INTEGER - 1`; defaults to 20. */
+  defaultLimit?: number
+  /** Largest accepted page size. At most `Number.MAX_SAFE_INTEGER - 1`; defaults to 100. */
+  maxLimit?: number
+  /** Maximum snippet length in Unicode code points. Defaults to 240. */
+  snippetChars?: number
+  /** Maximum concurrent persisted-log inspections in one inherited batch read. Defaults to 4. */
+  persistedInspectConcurrency?: number
+}
+
+/** SQLite module/handle opening phase. */
+export type OpenAt = 'startup' | 'first-search'
+
+/** Supported SQLite journal modes. */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+```
+
+依赖：[`SessionQueryConfig`](../packages/session-query/session-query/src/index.ts)
+
+来源：[`packages/session-query/session-query-sqlite/src/index.ts:89`](../packages/session-query/session-query-sqlite/src/index.ts)
+
+## `@deepseek-ai/dsh-session-reference`
+
+需要：`sessionQuery`
+
+```ts config-catalog
+/** Session-reference service configuration. */
+export interface Config {
+  /** Maximum distinct source sessions referenced by one message, from one to three. */
+  maxReferences?: number
+  /** Default host candidate-list limit. */
+  candidateLimit?: number
+  /** Maximum rendered UTF-8 bytes for one source snapshot. */
+  maxReferenceBytes?: number
+}
+```
+
+来源：[`packages/context/session-reference/src/config.ts:11`](../packages/context/session-reference/src/config.ts)
+
+## `@deepseek-ai/dsh-session-telemetry-otel`
+
+需要：`sessions`
+
+```ts config-catalog
+/**
+ * Plugin configuration: one sharing policy, two verbatim SDK option shapes,
+ * and one DSH-owned shutdown bound. Uploading modes validate their endpoint
+ * and shutdown deadline at plugin load; `DISABLED` reads neither.
+ */
+export interface Config {
+  /** Sharing policy; defaults to immediate `FULL` delivery. */
+  mode?: TelemetryMode
+  /**
+   * Passed verbatim to the SDK's OTLP/HTTP log exporter — the complete
+   * `OTLPExporterNodeConfigBase` shape (`headers`, `timeoutMillis`,
+   * `compression`, `keepAlive`, …), owned and documented by the SDK. `url`
+   * is the one field this package requires and validates itself.
+   */
+  exporter?: OTLPExporterNodeConfigBase & {
+    /** Full logs endpoint (e.g. `https://collector.example.com/v1/logs`). Required outside `DISABLED`; validated at load. */
+    url?: string
+  }
+  /**
+   * Passed verbatim to `BatchLogRecordProcessor` (minus the exporter slot,
+   * which this plugin fills); the SDK owns and documents these knobs.
+   */
+  processor?: Omit<BatchLogRecordProcessorOptions, 'exporter'>
+  /** Maximum time spent awaiting the SDK provider's complete shutdown path. */
+  shutdownTimeoutMillis?: number
+}
+
+/** Session-sharing policy selected by {@link Config.mode}. */
+export enum TelemetryMode {
+  FULL = 'FULL',
+  FEEDBACK_ONLY = 'FEEDBACK_ONLY',
+  DISABLED = 'DISABLED',
+}
+```
+
+依赖：`BatchLogRecordProcessorOptions`（`@opentelemetry/sdk-logs`）· `OTLPExporterNodeConfigBase`（`@opentelemetry/otlp-exporter-base`）
+
+来源：[`packages/session/session-telemetry-otel/src/index.ts:80`](../packages/session/session-telemetry-otel/src/index.ts)
+
+## `@deepseek-ai/dsh-session-title`
+
+需要：`sessions`
+
+```ts config-catalog
+/** Required deterministic fallback and accepted-title limits. */
+export interface Config {
+  /** Maximum whitespace-delimited words in the built-in fallback. */
+  readonly fallbackMaxWords: number
+  /** Maximum UTF-8 bytes in the built-in fallback. */
+  readonly fallbackMaxBytes: number
+  /** Maximum UTF-8 bytes in any accepted title. */
+  readonly maxTitleBytes: number
+}
+```
+
+来源：[`packages/session/session-title/src/index.ts:79`](../packages/session/session-title/src/index.ts)
+
+## `@deepseek-ai/dsh-session-title-all-messages-llm`
+
+需要：`sessionTitle` · `llm` · `sessions`
+
+```ts config-catalog
+/** Required LLM policy; this plugin adds no defaults. */
+export type Config = SessionTitleLlmConfig
+```
+
+依赖：[`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/index.ts)
+
+来源：[`packages/session/session-title-all-messages-llm/src/index.ts:15`](../packages/session/session-title-all-messages-llm/src/index.ts)
+
+## `@deepseek-ai/dsh-session-title-first-message-llm`
+
+需要：`sessionTitle` · `llm` · `sessions`
+
+```ts config-catalog
+/** Required LLM policy; this plugin adds no defaults. */
+export type Config = SessionTitleLlmConfig
+```
+
+依赖：[`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/index.ts)
+
+来源：[`packages/session/session-title-first-message-llm/src/index.ts:15`](../packages/session/session-title-first-message-llm/src/index.ts)
+
+## `@deepseek-ai/dsh-settings-local`
+
+```ts config-catalog
+/** Plugin config: file location and hot-reload behavior. */
+export interface Config {
+  /** Settings document path; defaults to `settings.yaml` under the harness home. */
+  path?: string
+  /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Watch the document and hot-publish external edits; defaults to true. */
+  watch?: boolean
+  /** Watcher write-settle window in milliseconds; defaults to 100. */
+  debounceMs?: number
+}
+```
+
+来源：[`packages/settings/settings-local/src/index.ts:21`](../packages/settings/settings-local/src/index.ts)
+
+## `@deepseek-ai/dsh-skill`
+
+```ts config-catalog
+/** Skill registry configuration. */
+export interface Config {
+  /** Maximum number of completed cwd/provider catalogs kept in memory. */
+  readonly collectCacheMaxEntries?: number
+}
+```
+
+来源：[`packages/skill/skill/src/index.ts:265`](../packages/skill/skill/src/index.ts)
+
+## `@deepseek-ai/dsh-skill-local`
+
+需要：`skills`
+
+```ts config-catalog
+/** Local filesystem skill provider configuration. */
+export interface Config {
+  /** Unique provider name. Defaults to `local`. */
+  providerName?: string
+  /** Whether project and user roots are included around custom roots. */
+  includeDefaultRoots?: boolean
+  /** DeepSeek Harness config root. Defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Shared agent config root. Defaults to `$DSH_AGENTS_HOME` or `~/.agents`. */
+  agentsHome?: string
+  /** Additional skill roots scanned after project roots and before user roots. */
+  customSkillDirs?: string[]
+  /** Whether host-local skill roots are watched for catalog changes. */
+  watch?: boolean
+  /** Whether Chokidar uses polling instead of native filesystem events. */
+  watchUsePolling?: boolean
+  /** Milliseconds a changed skill entry must remain stable before it is observed. */
+  watchStabilityThresholdMs?: number
+  /** Milliseconds between Chokidar stability or polling probes. */
+  watchPollIntervalMs?: number
+  /** Maximum distinct project roots whose skill directories remain watched. */
+  watchMaxProjects?: number
+  /** Whether watched symbolic links follow their target files. */
+  watchFollowSymlinks?: boolean
+  /** Bundled skill root; defaults to `$DSH_BUNDLED_SKILL_DIR` when default roots are included, otherwise mounts none. */
+  bundledSkillDir?: string
+}
+```
+
+来源：[`packages/skill/skill-local/src/index.ts:49`](../packages/skill/skill-local/src/index.ts)
+
+## `@deepseek-ai/dsh-spill-local`
+
+```ts config-catalog
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+  /**
+   * Root directory for spill files. Omitted uses a lazily-created private
+   * (0700) per-process directory under the OS temp dir — the safe default for
+   * a local deployment. Set it to keep spill files under a known location.
+   */
+  root?: string
+}
+```
+
+来源：[`packages/spill/spill-local/src/index.ts:22`](../packages/spill/spill-local/src/index.ts)
+
+## `@deepseek-ai/dsh-spill-policy`
+
+需要：`tools`
+
+```ts config-catalog
+/** Plugin config. */
+export interface Config {
+  /**
+   * The model-facing context cap for a plain-text tool result, in UTF-8 bytes.
+   * Omitted disables the policy entirely (no-op). When set, a result larger than
+   * this is spilled and replaced with a preview derived from this same budget.
+   */
+  maxInlineBytes?: number
+}
+```
+
+来源：[`packages/spill/spill-policy/src/index.ts:60`](../packages/spill/spill-policy/src/index.ts)
+
+## `@deepseek-ai/dsh-storage-domain`
+
+需要：`storage`
+
+```ts config-catalog
+/**
+ * Plugin config. Which backend serves which domain is decided here, not
+ * globally on the hub: `backend` is the default route and `routes` overrides
+ * it per domain name. A route naming an unregistered backend fails loud at
+ * `open` with `backend-not-found`.
+ */
+export interface Config {
+  /** Default backend name for every domain without an explicit route. Required: there is no universally correct medium. */
+  backend: string
+  /** Per-domain overrides: domain name → backend name. */
+  routes?: Record<string, string>
+}
+```
+
+来源：[`packages/storage/storage-domain/src/index.ts:52`](../packages/storage/storage-domain/src/index.ts)
+
+## `@deepseek-ai/dsh-storage-json`
+
+需要：`storage`
+
+```ts config-catalog
+/**
+ * Plugin configuration.
+ * `root` has NO default on purpose: a `process.cwd()` fallback would scatter
+ * unit files wherever the process happens to start; assemblies state the
+ * location explicitly.
+ */
+export interface Config {
+  /** Directory holding one `<unit>.json` file per unit. */
+  root: string
+}
+```
+
+来源：[`packages/storage/storage-json/src/index.ts:27`](../packages/storage/storage-json/src/index.ts)
+
+## `@deepseek-ai/dsh-storage-sqlite`
+
+需要：`storage`
+
+```ts config-catalog
+/** Plugin configuration. */
+export interface Config {
+  /**
+   * Filesystem path to the SQLite database file. The special value `:memory:`
+   * opens an in-process database (tests). On filesystems with POSIX modes,
+   * missing directories and databases are created owner-only; existing path
+   * modes are preserved. Filesystem setup errors other than an existing
+   * database fail the open. The backend does not protect confidentiality or
+   * integrity when another principal can replace the database entry in its
+   * parent directory.
+   */
+  path: string
+  /**
+   * SQLite `journal_mode` pragma. `wal` (the default) suits local disks; pick
+   * a rollback-journal mode (`delete`/`truncate`/`persist`) on filesystems
+   * where WAL's shared-memory files do not work (network mounts). See
+   * {@link JournalMode}.
+   */
+  journalMode?: JournalMode
+}
+
+/**
+ * Journal modes the backend will run under. `wal` is the default; the
+ * rollback-journal modes (`delete`/`truncate`/`persist`) exist for
+ * filesystems where WAL's shared-memory files do not work (network mounts).
+ * `memory`/`off` are excluded: dropping journal durability silently
+ * contradicts the durability clause of the KV backend contract.
+ */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+```
+
+来源：[`packages/storage/storage-sqlite/src/index.ts:24`](../packages/storage/storage-sqlite/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-acp`
+
+需要：`subagents` · `subprocess`
+
+```ts config-catalog
+/** Config: how to spawn and drive the child ACP agent process. */
+export interface Config {
+  /** Provider name on `ctx.subagents` (default `acp`). */
+  providerName: string
+  /** The executable to spawn for each run (the child ACP agent). */
+  command: string
+  /** Arguments passed to {@link command}. */
+  args: string[]
+  /**
+   * Working directory override for the child process and its ACP session.
+   * Must be non-empty; a relative path resolves against the harness launch
+   * directory at load, and the result must be an existing directory. When
+   * omitted, each child inherits its delegating parent session's cwd — and
+   * starting one from a parent session that has no cwd fails.
+   */
+  cwd?: string
+  /**
+   * How to auto-answer the child's `session/request_permission` prompts:
+   * `reject` (default — decline every prompt) or `allow` (approve via the first
+   * allow-shaped option). The first cut surfaces no prompt to a human.
+   */
+  permission: PermissionPolicy
+  /**
+   * Extra environment variables for the child process — e.g. the child
+   * harness's own `DEEPSEEK_API_KEY`. Forwarded on top of a credential-scrubbed
+   * copy of the parent env, so an explicit key here reaches the child while
+   * ambient secrets do not leak implicitly.
+   */
+  env: Record<string, string>
+  /**
+   * Grace period (ms) for the child's EOF-driven quiesce on dispose — its
+   * window to flush persistence and tear down its own nested subprocesses
+   * before the parent escalates to a signal. Must not exceed
+   * `MAX_TIMER_DELAY_MS`.
+   */
+  disposeEofGraceMs?: number
+  /** Termination-escalation grace (ms); must not exceed `MAX_TIMER_DELAY_MS`. */
+  disposeGraceMs?: number
+}
+
+/** Fixed response to child permission requests: reject by default, or select the first allow option. */
+export type PermissionPolicy = 'allow' | 'reject'
+```
+
+来源：[`packages/subagent/subagent-acp/src/index.ts:27`](../packages/subagent/subagent-acp/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-claude-code`
+
+需要：`subagents` · `subprocess`
+
+```ts config-catalog
+/** Deployment-owned environment and process-release bound. */
+export interface Config {
+  /**
+   * Explicit environment entries layered over the subprocess seam's
+   * credential-scrubbed parent environment.
+   */
+  env?: Record<string, string>
+  /** Grace in milliseconds for Claude Code process-tree termination. */
+  disposeGraceMs?: number
+}
+```
+
+来源：[`packages/subagent/subagent-claude-code/src/index.ts:32`](../packages/subagent/subagent-claude-code/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-codex`
+
+需要：`subagents` · `subprocess`
+
+```ts config-catalog
+/** Deployment-owned environment and process-release bound. */
+export interface Config {
+  /**
+   * Explicit environment entries layered over the subprocess seam's
+   * credential-scrubbed parent environment.
+   */
+  env?: Record<string, string>
+  /** Grace in milliseconds for app-server process-tree termination. */
+  disposeGraceMs?: number
+}
+```
+
+来源：[`packages/subagent/subagent-codex/src/index.ts:30`](../packages/subagent/subagent-codex/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-dsh-sdk`
+
+需要：`subagents`
+
+```ts config-catalog
+/** Config: how to spawn and drive the child SDK runtime process. */
+export interface Config {
+  /** Provider name on `ctx.subagents` (default `dsh-sdk`). */
+  providerName: string
+  /** The executable to spawn for each run (the child runtime bin or packaged exe). */
+  command: string
+  /** Arguments passed to {@link command} (typically the child's `cordis.yml` path). */
+  args: string[]
+  /**
+   * Working directory override for the child process and its SDK session
+   * workspace. Must be non-empty; a relative path resolves against the
+   * harness launch directory at load, and the result must be an existing
+   * directory. When omitted, each child inherits its delegating parent
+   * session's cwd — and starting one from a parent session that has no cwd
+   * fails.
+   */
+  cwd?: string
+  /** Provider route the child runtime initializes with (default `deepseek-official`). */
+  provider: string
+  /** Model the child runtime initializes with (default `deepseek-v4-flash`). */
+  model: string
+  /** Optional per-request output-token cap for the child runtime. */
+  maxTokens?: number
+  /**
+   * Extra environment variables for the child process — e.g. the child
+   * runtime's own `DEEPSEEK_API_KEY`, or `DSH_CORDIS_CONFIG` naming its
+   * config. Forwarded on top of a credential-scrubbed copy of the parent
+   * env, so an explicit key here reaches the child while ambient secrets do
+   * not leak implicitly.
+   */
+  env: Record<string, string>
+  /** Bound (ms) on the protocol `shutdown` exchange during dispose. */
+  shutdownTimeoutMs?: number
+  /**
+   * Grace period (ms) for the child's EOF-driven quiesce on dispose — its
+   * window to flush persistence and tear down its own nested subprocesses
+   * before the parent escalates to a signal.
+   */
+  disposeEofGraceMs?: number
+  /** Termination confirmation window (ms), including forced exit on every platform. */
+  disposeGraceMs?: number
+}
+```
+
+来源：[`packages/subagent/subagent-dsh-sdk/src/index.ts:29`](../packages/subagent/subagent-dsh-sdk/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-fork`
+
+需要：`subagents`
+
+```ts config-catalog
+/** Config: the registry name to register the provider under. */
+export interface Config {
+  /** Provider name on `ctx.subagents` (default `fork`). */
+  providerName: string
+}
+```
+
+来源：[`packages/subagent/subagent-fork/src/index.ts:31`](../packages/subagent/subagent-fork/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-spawn`
+
+需要：`subagents`
+
+```ts config-catalog
+/** Config: the registry name to register the provider under. */
+export interface Config {
+  /** Provider name on `ctx.subagents` (default `spawn`). */
+  providerName: string
+}
+```
+
+来源：[`packages/subagent/subagent-spawn/src/index.ts:25`](../packages/subagent/subagent-spawn/src/index.ts)
+
+## `@deepseek-ai/dsh-subprocess-e2b`
+
+需要：`e2b`
+
+```ts config-catalog
+/** Configuration for the E2B subprocess adapter. */
+export interface Config {
+  /** Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request. */
+  pollMs?: number
+}
+```
+
+来源：[`packages/e2b/subprocess-e2b/src/index.ts:25`](../packages/e2b/subprocess-e2b/src/index.ts)
+
+## `@deepseek-ai/dsh-system-prompt`
+
+```ts config-catalog
+/** Plugin config: the deployment-authored fragment of the system prompt (see {@link Config.persona} for its contract). */
+export interface Config {
+  /** Include the fixed DeepSeek Harness identity before the deployment persona (default true). */
+  includeHarnessIdentity?: boolean
+  /**
+   * Deployment-wide order-0 persona template. A scoped section named
+   * `deployment:persona` shadows it; `{{variable}}` references are strict.
+   */
+  persona?: string
+  /**
+   * Model-facing tool names in order, with {@link TOOL_ORDER_REST} exactly once.
+   * Shape errors fail at load and unknown names fail at assembly; known names
+   * hidden in one scope may be absent there. Omitted means lexicographic order.
+   */
+  toolOrder?: string[]
+}
+```
+
+来源：[`packages/core/system-prompt/src/index.ts:166`](../packages/core/system-prompt/src/index.ts)
+
+## `@deepseek-ai/dsh-time-context`
+
+需要：`agents`
+
+```ts config-catalog
+/** Request-preparation clock formatting and append scheduling. Invalid values fail plugin load. */
+export interface Config {
+  /** IANA time zone used for the rendered timestamp. Omit to resolve the Node process's system zone at plugin load. */
+  timeZone?: string
+  /** Minimum milliseconds between durable injections in one session. Omit or set to 0 to inject at every eligible step. */
+  refreshIntervalMs?: number
+}
+```
+
+来源：[`packages/context/time-context/src/index.ts:20`](../packages/context/time-context/src/index.ts)
+
+## `@deepseek-ai/dsh-tmux-context`
+
+需要：`agents`
+
+```ts config-catalog
+/** Per-turn tmux-location scheduling. Invalid values fail plugin load. */
+export interface Config {
+  /** Minimum milliseconds between durable injections in one session. Omit or set to 0 to inject on every eligible change. */
+  refreshIntervalMs?: number
+}
+```
+
+来源：[`packages/context/tmux-context/src/index.ts:34`](../packages/context/tmux-context/src/index.ts)
+
+## `@deepseek-ai/dsh-token-meter`
+
+```ts config-catalog
+/** Token-meter plugin configuration; the fixed estimator has no settings. */
+export type TokenMeterConfig = Record<string, never>
+```
+
+来源：[`packages/llm/token-meter/src/types.ts:12`](../packages/llm/token-meter/src/types.ts)
+
+## `@deepseek-ai/dsh-tool-bash`
+
+需要：`tools` · `bash` · `systemPrompt` · `bashEnv`
+
+```ts config-catalog
+/** Configuration for the bash tool. */
+export interface Config {
+  /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+  enableRunInBackground?: boolean
+}
+```
+
+来源：[`packages/bash/tool-bash/src/index.ts:34`](../packages/bash/tool-bash/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-bash-persistent`
+
+需要：`tools` · `pty`
+
+```ts config-catalog
+/** Configuration for the persistent Bash tool. */
+export interface Config {
+  /** PTY backend used for each owner-isolated persistent shell (default `shell`). */
+  backendType?: string
+  /** Wall-clock limit for one command (default 300000). */
+  timeoutMs?: number
+  /** Maximum returned command-output characters before clipping (default 16000). */
+  maxOutputChars?: number
+  /** Model-facing tool description; deployments may describe their environment. */
+  description?: string
+}
+```
+
+来源：[`packages/pty/tool-bash-persistent/src/index.ts:405`](../packages/pty/tool-bash-persistent/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-cordis`
+
+需要：`tools`
+
+```ts config-catalog
+/** Config for the tool-cordis plugin: the sandbox evaluation bound. */
+export interface Config {
+  /**
+   * Milliseconds the SYNCHRONOUS portion of mount code may run in the vm
+   * before evaluation is aborted (default 5000). An async body escapes this
+   * bound — see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md for the trust stance.
+   */
+  vmTimeoutMs?: number
+}
+```
+
+来源：[`packages/self-modification/tool-cordis/src/index.ts:25`](../packages/self-modification/tool-cordis/src/index.ts)
+## `@deepseek-ai/dsh-tool-fs`
+
+需要：`tools` · `fs` · `systemPrompt`
+
+```ts config-catalog
+/** Plugin config (all optional — `Config` supplies the defaults). */
+export interface Config {
+  /** Default and maximum number of lines returned by one `read` call. */
+  readLimit?: number
+  /** Maximum characters returned for a single line before truncation. */
+  readMaxLineLength?: number
+  /** Maximum bytes returned for the selected lines of one `read` call. */
+  readMaxBytes?: number
+  /** Files at or above this size stream instead of loading whole into memory. */
+  readStreamMinSize?: number
+}
+```
+
+来源：[`packages/fs/tool-fs/src/index.ts:24`](../packages/fs/tool-fs/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-fs-search`
+
+需要：`tools` · `systemPrompt` · `subprocess`
+
+```ts config-catalog
+/** Plugin config; over-cap glob sampling is an explicit deployment choice and the remaining fields have defaults. */
+export interface Config {
+  /** Whether an over-cap `glob` page is sampled across top-level entries instead of taking the modification-time head. */
+  sampleOverCapGlobResults: boolean
+  /** Max paths one `glob` call retains inline; later paths go to the formatted spill file. */
+  globMaxResults?: number
+  /** Max flat matches one `grep` call retains inline; later matches go to the formatted spill file. */
+  grepMaxMatches?: number
+  /** Max bytes retained for one matched-line preview (the cut preserves UTF-8 boundaries). */
+  grepMaxLineBytes?: number
+  /** Max bytes of one search's serialized `presentationMeta`; trailing groups/paths drop past it so the persisted card stays bounded. */
+  searchMetaMaxBytes?: number
+  /** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */
+  rawOutputMaxBytes?: number
+  /** Terminate-escalation grace (ms), handed to the subprocess seam and bounded by `MAX_TIMER_DELAY_MS`. */
+  graceMs?: number
+  /** Max bytes retained for one search's stderr tail; the excerpt is embedded in `SEARCH_*` error messages, never shown on success. */
+  stderrMaxBytes?: number
+  /** Cooperative tool-call timeout budget (ms) on both tools, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`. */
+  timeoutMs?: number
+}
+```
+
+来源：[`packages/fs/tool-fs-search/src/index.ts:73`](../packages/fs/tool-fs-search/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-goal`
+
+需要：`agents` · `goals` · `tools` · `systemPrompt`
+
+```ts config-catalog
+/** Model policy and hard lower bounds for goal-state updates. */
+export interface Config {
+  /** Minimum admitted goal rounds before the model may self-report `blocked`. */
+  blockedAfterConsecutiveRounds?: number
+}
+```
+
+来源：[`packages/goal/tool-goal/src/index.ts:26`](../packages/goal/tool-goal/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-lsp`
+
+需要：`tools` · `lsp` · `systemPrompt`
+
+```ts config-catalog
+/** Plugin configuration: result caps and the timeout budget. */
+export interface Config {
+  /** Largest number of rendered locations before an omission marker (default 100). */
+  maxLocations?: number
+  /** Largest complete rendered result in characters, including truncation metadata (default 16000). */
+  maxResultChars?: number
+  /** Tool-call timeout budget in ms (default 60000). */
+  timeoutMs?: number
+}
+```
+
+来源：[`packages/lsp/tool-lsp/src/index.ts:58`](../packages/lsp/tool-lsp/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-pty`
+
+需要：`pty` · `tools` · `systemPrompt`
+
+```ts config-catalog
+/** Model-facing terminal tool configuration. */
+export interface Config {
+  /** Expose `run_in_background` and accept background sends (default true). */
+  enableRunInBackground?: boolean
+  /** Maximum UTF-8 bytes in one complete terminal or task-output result. */
+  maxResultBytes?: number
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts:35`](../packages/pty/tool-pty/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-pwsh`
+
+需要：`tools` · `bash` · `systemPrompt` · `bashEnv`
+
+```ts config-catalog
+/** Configuration for the pwsh tool. */
+export interface Config {
+  /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+  enableRunInBackground?: boolean
+}
+```
+
+来源：[`packages/bash/tool-pwsh/src/index.ts:43`](../packages/bash/tool-pwsh/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-ralph`
+
+需要：`tools` · `workflows` · `subagents` · `systemPrompt`
+
+```ts config-catalog
+/** Deployment policy for the fixed Ralph workflow. */
+export interface Config {
+  /** Fresh structured-output provider used for every round (default `spawn`). */
+  subagentProvider?: string
+  /** Default and deployment ceiling for one call's round count (default 256). */
+  maxRounds?: number
+  /** Maximum serialized characters in one structured handoff (default 16384). */
+  maxHandoffChars?: number
+  /** Maximum characters in a successful parent-facing terminal text (default 16384). */
+  maxResultChars?: number
+}
+```
+
+来源：[`packages/workflow/tool-ralph/src/index.ts:23`](../packages/workflow/tool-ralph/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-session-query`
+
+需要：`tools` · `systemPrompt` · `sessionQuery`
+
+```ts config-catalog
+/** Deployment-owned search count and timeout bounds. */
+export interface Config {
+  /** Maximum authorized hits returned by one search call. Defaults to 100. */
+  maxSearchResults?: number
+  /** Cooperative full-text search deadline in milliseconds. Defaults to 30000. */
+  searchTimeoutMs?: number
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts:29`](../packages/session-query/tool-session-query/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-skill`
+
+需要：`agents` · `tools` · `skills`
+
+```ts config-catalog
+/** Model-facing skill catalog configuration. */
+export interface Config {
+  /** Maximum normalized description length rendered in the session catalog; minimum 3. */
+  catalogDescriptionMaxLength?: number
+}
+```
+
+来源：[`packages/skill/tool-skill/src/index.ts:61`](../packages/skill/tool-skill/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-str-replace-editor`
+
+需要：`tools` · `fs`
+
+```ts config-catalog
+/** Configuration for the string-replacement editor tool. */
+export interface Config {
+  /** Maximum returned view characters before clipping (default 16000). */
+  maxOutputChars?: number
+  /** Model-facing tool description. */
+  description?: string
+}
+```
+
+来源：[`packages/fs/tool-str-replace-editor/src/index.ts:496`](../packages/fs/tool-str-replace-editor/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-subagent`
+
+需要：`tools` · `subagents`
+
+```ts config-catalog
+/** Config: which registered provider this tool delegates to, plus child defaults. */
+export interface Config {
+  /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */
+  provider: string
+  /**
+   * Model-facing tool name (default `subagent`). Each loaded instance must use
+   * a distinct name.
+   */
+  toolName?: string
+  /**
+   * Expose `run_in_background` (default true). Disabled instances omit the
+   * parameter and reject forced background calls.
+   */
+  enableRunInBackground?: boolean
+  /**
+   * Background execution policy (default `one-shot`). `continuable` requires a
+   * provider with the `prepareContinuable` capability and returns the durable
+   * child id; follow-up adapters remain independently optional.
+   */
+  backgroundMode?: 'one-shot' | 'continuable'
+  /**
+   * Agent options applied to every child; omitted fields use child-loop defaults.
+   */
+  agentOptions?: AgentOptions
+  /**
+   * Per-child persona that shadows `deployment:persona`. Requires the
+   * provider's `persona` capability; omission preserves the deployment persona.
+   */
+  persona?: string
+  /**
+   * Tool filter applied to every child. Filtered tools disappear from its
+   * prompt and reject execution. Requires the provider's `toolFilter`
+   * capability; unknown names fail startup.
+   */
+  toolFilter?: {
+    /** Global tool names the child keeps; everything else is removed. */
+    allow?: string[]
+    /** Global tool names removed from the child. */
+    deny?: string[]
+  }
+  /**
+   * Maximum child depth: a non-negative safe integer (default `3`; `0` forbids
+   * delegation entirely), or `'provider-managed'` to send no cap. A numeric cap
+   * requires the provider's `depthLimit` capability (mount fails loud
+   * otherwise). The provider checks the calling agent's current depth at every
+   * start; the tool remains model-visible so runtime policy owns rejection.
+   * `'provider-managed'` is for an out-of-process provider whose recursion
+   * budget belongs to the child runtime or its own deployment.
+   */
+  maxDepth?: number | 'provider-managed'
+}
+```
+
+依赖：[`AgentOptions`](subsystems/core.md)
+
+来源：[`packages/subagent/tool-subagent/src/index.ts:25`](../packages/subagent/tool-subagent/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-subagent-report`
+
+需要：`subagents` · `tools`
+
+```ts config-catalog
+/** Config: how accepted reports are scheduled on the parent. */
+export interface Config {
+  /**
+   * Parent scheduling (default `quiet`). `quiet` adds context without waking;
+   * `wakeup` creates one ordinary later parent turn.
+   */
+  reportDelivery?: SubagentReportDelivery
+}
+```
+
+依赖：[`SubagentReportDelivery`](subsystems/subagent.md)
+
+来源：[`packages/subagent/tool-subagent-report/src/index.ts:22`](../packages/subagent/tool-subagent-report/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-tasks`
+
+需要：`tools` · `tasks` · `systemPrompt`
+
+```ts config-catalog
+/** Configures bounded `task_output` waits. */
+export interface Config {
+  /** Wait duration applied when `task_output` sets `wait` without `timeout_ms` (default 30s). */
+  waitTimeoutMs?: number
+  /** Hard cap on any single wait; a larger model-supplied `timeout_ms` is clamped down to it (default 10min). */
+  maxWaitTimeoutMs?: number
+}
+```
+
+来源：[`packages/tasks/tool-tasks/src/index.ts:23`](../packages/tasks/tool-tasks/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-todo`
+
+需要：`tools`
+
+```ts config-catalog
+/** Model-facing todo tool configuration. */
+export interface Config {
+  /**
+   * Required deployment choice for whether several todos may be `in_progress` at once. True suits
+   * agents that run work concurrently — subagents, background commands, workflow fan-out — and the
+   * description then instructs the model to mark every actively worked task. False restores the
+   * single-active discipline: the description asks for exactly one, and a call marking more is
+   * rejected.
+   */
+  allowParallelInProgress: boolean
+}
+```
+
+来源：[`packages/todo/tool-todo/src/index.ts:29`](../packages/todo/tool-todo/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-web`
+
+需要：`tools` · `web` · `systemPrompt`
+
+```ts config-catalog
+/** Plugin config: which web tools to register, the source cap, per-tool budgets, and the fetch output cap. */
+export interface Config {
+  /** Register `web_search`. Defaults to true. */
+  search?: boolean
+  /** Register `web_fetch`. Defaults to true. */
+  fetch?: boolean
+  /** Upper bound on sources returned by one `web_search` call. */
+  searchMaxResults?: number
+  /** Cooperative timeout budget (ms) for `web_fetch`. Defaults to 30000. */
+  fetchTimeoutMs?: number
+  /** Cooperative timeout budget (ms) for `web_search`. Defaults to 30000. */
+  searchTimeoutMs?: number
+  /** Cap on source characters converted and complete `web_fetch` output characters. Defaults to 200000. */
+  fetchMaxOutputChars?: number
+}
+```
+
+来源：[`packages/web/tool-web/src/index.ts:37`](../packages/web/tool-web/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-workflow`
+
+需要：`tools` · `workflows` · `systemPrompt`
+
+```ts config-catalog
+/** Config: the model-facing tool name plus result rendering caps. */
+export interface Config {
+  /** The model-facing tool name to register (default `workflow`). */
+  toolName?: string
+  /** Rendered-result ceiling, in characters: a longer JSON value is truncated with a notice (default 50000). */
+  maxResultChars?: number
+}
+```
+
+来源：[`packages/workflow/tool-workflow/src/index.ts:27`](../packages/workflow/tool-workflow/src/index.ts)
+
+## `@deepseek-ai/dsh-tools`
+
+需要：`systemPrompt`
+
+```ts config-catalog
+/** Plugin config: how the registered tools are presented to the model. */
+export interface Config {
+  /**
+   * Model presentation. `native` (default) sends every visible schema; `code`
+   * sends only `run_code` plus a generated SDK prompt; `both` sends both forms.
+   * Code modes require a `ctx.codeRuntime` whose `language` has a registered
+   * SDK renderer (TypeScript or Python) and fail prompt assembly when it is
+   * absent or has no renderer. Under `code`, native names in `toolOrder` are invalid.
+   */
+  mode?: ToolPresentationMode
+  /**
+   * Concurrency cap for a `run_code` program's overlapping sub-calls
+   * (default 10, the loop scheduler's own default). Sub-calls follow the
+   * native scheduling contract — only calls whose tools classify
+   * concurrency-safe overlap; exclusive calls form barriers — so `1`
+   * restores strictly serial dispatch. Must be a positive integer.
+   */
+  maxParallelSubCalls?: number
+}
+
+/** How the registry presents its tools to the model (see {@link Config.mode}). */
+export type ToolPresentationMode = 'native' | 'code' | 'both'
+```
+
+来源：[`packages/core/tools/src/index.ts:616`](../packages/core/tools/src/index.ts)
+
+## `@deepseek-ai/dsh-typert-loader`
+
+需要：`typert` · `loader`
+
+```ts config-catalog
+/** Additional package artifacts whose owning plugins are nested behind another Loader entry. */
+export interface Config {
+  /** Exact npm package names that must resolve and export `./typert`. */
+  packages?: string[]
+}
+```
+
+来源：[`packages/typert/loader/src/index.ts:47`](../packages/typert/loader/src/index.ts)
+
+## `@deepseek-ai/dsh-user-approval`
+
+```ts config-catalog
+/** Plugin config. All optional — `static Config` supplies the defaults. */
+export interface Config {
+  /**
+   * The deployment's default {@link ApprovalPolicy} for sessions without an
+   * `approval/policy` override — `'ask'` delegates to the composed answerers
+   * (fail-closed with none); `'never'` auto-rejects every ask without
+   * prompting (the deterministic CI/unattended stance).
+   */
+  readonly policy?: ApprovalPolicy
+}
+
+/**
+ * A session's approval policy — what happens to an {@link ApprovalService}
+ * ask BEFORE any interactive answerer sees it:
+ *
+ * - `'ask'` (the default) — delegate to the composed answerers; with none
+ *   composed the chain falls through to the fail-closed `'unavailable'`
+ *   (exactly today's behavior).
+ * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
+ *   deterministically. The strict headless stance (CI, unattended runs) and
+ *   the policy whose outcome is knowable without asking.
+ */
+export type ApprovalPolicy = 'ask' | 'never'
+```
+
+来源：[`packages/interaction/user-approval/src/index.ts:178`](../packages/interaction/user-approval/src/index.ts)
+
+## `@deepseek-ai/dsh-web`
+
+```ts config-catalog
+/**
+ * Config for the web seam. `searchProvider` / `fetchProvider` pin which provider
+ * wins for each capability; both are optional (a single registered usable
+ * provider auto-selects). Operational overrides such as environment variables
+ * must feed these same fields rather than introduce a hidden priority chain.
+ */
+export interface WebServiceConfig {
+  /** Explicit search provider id. Omitted = auto-select when exactly one usable. */
+  readonly searchProvider?: string
+  /** Explicit fetch provider id. Omitted = auto-select when exactly one usable. */
+  readonly fetchProvider?: string
+}
+```
+
+来源：[`packages/web/web/src/index.ts:55`](../packages/web/web/src/index.ts)
+
+## `@deepseek-ai/dsh-web-app`
+
+需要：`httpServer`
+
+```ts config-catalog
+/** Plugin config: the surface facts the launcher patches over this bundle's defaults. */
+export interface Config {
+  /** Whether this process mounted the client-plugin HMR receiver (`dsh web --dev`). */
+  mode: WebMode
+  /** Print the URL line on activation; a headless layer over this bundle turns it off. */
+  printUrl: boolean
+  /**
+   * Register the model-visible surface context (the `app:web-surface` prompt
+   * section and the `DSH_WEB_URL`/`DSH_WEB_MODE` bash variables). A one-shot
+   * layer turns it off: its user is not interacting through the GUI, so the
+   * orientation text would be false.
+   */
+  surfaceContext: boolean
+  /**
+   * LAN IPv4 addresses sampled once by the launcher when the effective bind
+   * is all-interfaces — the exact snapshot the /api trust fence was
+   * configured with, so the printed LAN URL can never name an address the
+   * fence rejects. Empty on a loopback bind.
+   */
+  lanAddresses: string[]
+}
+
+/** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
+export type WebMode = 'production' | 'development'
+```
+
+来源：[`packages/bundle/web-app/src/index.ts:32`](../packages/bundle/web-app/src/index.ts)
+
+## `@deepseek-ai/dsh-web-fetch-local`
+
+需要：`web`
+
+```ts config-catalog
+/** Plugin config: the provider's transport and size limits plus its `User-Agent` (all defaulted). */
+export interface Config {
+  /** Maximum accepted request URL length. */
+  maxUrlLength?: number
+  /** Maximum response body size in bytes. */
+  maxResponseBytes?: number
+  /** Maximum decoded body length in characters. */
+  maxBodyChars?: number
+  /** Default fetch timeout in milliseconds, within Node's timer range. */
+  timeoutMs?: number
+  /** Maximum number of same-origin redirect hops to follow. */
+  maxRedirects?: number
+  /** `User-Agent` header sent on every request. */
+  userAgent?: string
+}
+```
+
+来源：[`packages/web/web-fetch-local/src/index.ts:34`](../packages/web/web-fetch-local/src/index.ts)
+
+## `@deepseek-ai/dsh-web-search-deepseek`
+
+需要：`web`
+
+```ts config-catalog
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
+export interface Config {
+  /** Literal DeepSeek API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
+  apiKey?: string
+  /** Credential reference resolved for each search; defaults to `DEEPSEEK_API_KEY`. */
+  apiKeyEnv?: string
+  /** Anthropic-compatible endpoint base; `/messages` is appended. */
+  baseURL?: string
+  /** Anthropic-format model name. Defaults to `deepseek-v4-flash`. */
+  model?: string
+  /** `anthropic-version` header value. Defaults to `2023-06-01`. */
+  apiVersion?: string
+  /** Upper bound on generated tokens for the Messages request. Defaults to 4096. */
+  maxTokens?: number
+  /** Maximum `web_search` server-tool uses per request. Defaults to 5. */
+  maxUses?: number
+}
+```
+
+来源：[`packages/web/web-search-deepseek/src/index.ts:44`](../packages/web/web-search-deepseek/src/index.ts)
+
+## `@deepseek-ai/dsh-web-search-exa`
+
+需要：`web`
+
+```ts config-catalog
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
+export interface Config {
+  /** Exa API key. Falls back to `$EXA_API_KEY`. Empty → provider unavailable. */
+  apiKey?: string
+  /** Endpoint base; `/search` is appended. Defaults to the public API. */
+  baseURL?: string
+  /** Retrieval mode sent as Exa's `type`. Defaults to `auto`. */
+  searchType?: 'auto' | 'keyword' | 'neural'
+  /** Default result count when a request carries no `maxResults`. Omitted = none. */
+  numResults?: number
+  /** Highlight sentences requested per result. Defaults to 1. */
+  highlightsPerResult?: number
+}
+```
+
+来源：[`packages/web/web-search-exa/src/index.ts:38`](../packages/web/web-search-exa/src/index.ts)
+
+## `@deepseek-ai/dsh-web-search-perplexity`
+
+需要：`web`
+
+```ts config-catalog
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
+export interface Config {
+  /** Perplexity API key. Falls back to `$PERPLEXITY_API_KEY`. Empty → unavailable. */
+  apiKey?: string
+  /** Endpoint base; `/chat/completions` is appended. Defaults to the public API. */
+  baseURL?: string
+  /** Search model name. Defaults to `sonar`. */
+  model?: string
+  /** Upper bound on generated answer tokens. Defaults to 1024. */
+  maxTokens?: number
+  /** Recency window sent as `search_recency_filter`. Omitted = no filter. */
+  searchRecency?: 'day' | 'week' | 'month' | 'year'
+}
+```
+
+来源：[`packages/web/web-search-perplexity/src/index.ts:32`](../packages/web/web-search-perplexity/src/index.ts)
+
+## `@deepseek-ai/dsh-workflow-workerthread`
+
+需要：`subagents`
+
+```ts config-catalog
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+  /** The `ctx.subagents` provider children run on (default `spawn`). */
+  provider?: string
+  /** Concurrent `agent()` ceiling; `0` (the default) auto-resolves to `min(16, max(1, cores - 2))`. */
+  maxConcurrentAgents?: number
+  /** Total `agent()` calls one run may start — the runaway-loop backstop (default 1000). */
+  maxTotalAgents?: number
+  /** Items accepted by a single `parallel()`/`pipeline()` call (default 4096). */
+  maxItemsPerCall?: number
+  /** vm timeout for the script's initial synchronous slice, inside the worker (default 5000 ms). */
+  syncTimeoutMs?: number
+  /**
+   * How long after a cancellation an unsettled script may keep running before
+   * the run force-settles `cancelled` and its worker is TERMINATED (default
+   * 5000 ms); also bounds `dispose()`.
+   */
+  disposeGraceMs?: number
+}
+```
+
+来源：[`packages/workflow/workflow-workerthread/src/index.ts:32`](../packages/workflow/workflow-workerthread/src/index.ts)
+
+## `@deepseek-ai/dsh-workspace-context`
+
+```ts config-catalog
+/** User-facing workspace instruction loader configuration. */
+export interface Config {
+  /** Harness home containing the fixed user-global `AGENTS.md`; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Directory entries that identify the project root while walking upward from the session cwd. */
+  projectRootMarkers?: string[]
+  /** UTF-8 byte cap for one rendered baseline or dynamic batch; non-positive or non-finite disables loading. */
+  maxBytes: number
+  /** Maximum UTF-8 bytes read from one instruction file; larger files are ignored. */
+  maxSourceBytes?: number
+  /**
+   * Ordered same-directory project candidates; every existing file loads, with
+   * per-directory trimmed-content duplicates collapsed to the earliest candidate.
+   */
+  instructionFileCandidates?: string[]
+  /**
+   * Ordered same-directory local-overlay candidates loaded after the base files
+   * under the same per-directory trimmed-content dedup; empty disables the overlay.
+   */
+  localInstructionFileCandidates?: string[]
+}
+```
+
+来源：[`packages/context/workspace-context/src/config.ts:18`](../packages/context/workspace-context/src/config.ts)
+
+## 无配置的可加载插件
+
+这些插件通过不含 `config:` 块的 `cordis.yml` 条目加载；它们未声明任何配置接口。
+
+- `@deepseek-ai/dsh-agent`（[`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts)）
+- `@deepseek-ai/dsh-api-gateway` — 需要 `typert`（[`packages/api/gateway/src/index.ts`](../packages/api/gateway/src/index.ts)）
+- `@deepseek-ai/dsh-api-remotes`（[`packages/api/remotes/src/index.ts`](../packages/api/remotes/src/index.ts)）
+- `@deepseek-ai/dsh-client-locale`（[`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts)）
+- `@deepseek-ai/dsh-client-modules` — 需要 `httpServer` · `loader`（[`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts)）
+- `@deepseek-ai/dsh-client-runtime`（[`packages/client/runtime/src/index.ts`](../packages/client/runtime/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-command`（[`packages/client/ui-command/src/index.ts`](../packages/client/ui-command/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-conversation`（[`packages/client/ui-conversation/src/index.ts`](../packages/client/ui-conversation/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-deliverables`（[`packages/client/ui-deliverables/src/index.ts`](../packages/client/ui-deliverables/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-goal`（[`packages/client/ui-goal/src/index.ts`](../packages/client/ui-goal/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-layout`（[`packages/client/ui-layout/src/index.ts`](../packages/client/ui-layout/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-model`（[`packages/client/ui-model/src/index.ts`](../packages/client/ui-model/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-models`（[`packages/client/ui-models/src/index.ts`](../packages/client/ui-models/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-permission`（[`packages/client/ui-permission/src/index.ts`](../packages/client/ui-permission/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-plan`（[`packages/client/ui-plan/src/index.ts`](../packages/client/ui-plan/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-question` — 需要 `tools` · `userInteraction`（[`packages/client/ui-question/src/index.ts`](../packages/client/ui-question/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-settings`（[`packages/client/ui-settings/src/index.ts`](../packages/client/ui-settings/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-settings-general`（[`packages/client/ui-settings-general/src/index.ts`](../packages/client/ui-settings-general/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-sidebar`（[`packages/client/ui-sidebar/src/index.ts`](../packages/client/ui-sidebar/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-skill`（[`packages/client/ui-skill/src/index.ts`](../packages/client/ui-skill/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-slash`（[`packages/client/ui-slash/src/index.ts`](../packages/client/ui-slash/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-subagent`（[`packages/client/ui-subagent/src/index.ts`](../packages/client/ui-subagent/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-theme`（[`packages/client/ui-theme/src/index.ts`](../packages/client/ui-theme/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-tool`（[`packages/client/ui-tool/src/index.ts`](../packages/client/ui-tool/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-trajectory`（[`packages/client/ui-trajectory/src/index.ts`](../packages/client/ui-trajectory/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-workspace`（[`packages/client/ui-workspace/src/index.ts`](../packages/client/ui-workspace/src/index.ts)）
+- `@deepseek-ai/dsh-command-compact` — 需要 `commands` · `compact`（[`packages/compact/command-compact/src/index.ts`](../packages/compact/command-compact/src/index.ts)）
+- `@deepseek-ai/dsh-command-feedback` — 需要 `commands`（[`packages/feedback/command-feedback/src/index.ts`](../packages/feedback/command-feedback/src/index.ts)）
+- `@deepseek-ai/dsh-command-goal` — 需要 `commands` · `goals`（[`packages/goal/command-goal/src/index.ts`](../packages/goal/command-goal/src/index.ts)）
+- `@deepseek-ai/dsh-commands`（[`packages/interaction/commands/src/index.ts`](../packages/interaction/commands/src/index.ts)）
+- `@deepseek-ai/dsh-fs-e2b` — 需要 `e2b`（[`packages/e2b/fs-e2b/src/index.ts`](../packages/e2b/fs-e2b/src/index.ts)）
+- `@deepseek-ai/dsh-fs-policy`（[`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts)）
+- `@deepseek-ai/dsh-goal-session` — 需要 `agents` · `goals` · `sessions`（[`packages/goal/goal-session/src/index.ts`](../packages/goal/goal-session/src/index.ts)）
+- `@deepseek-ai/dsh-host-directory-picker-auto` — 需要 `httpServer` · `loader`（[`packages/host/directory-picker-auto/src/index.ts`](../packages/host/directory-picker-auto/src/index.ts)）
+- `@deepseek-ai/dsh-host-directory-picker-native`（[`packages/host/directory-picker-native/src/index.ts`](../packages/host/directory-picker-native/src/index.ts)）
+- `@deepseek-ai/dsh-llm`（[`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts)）
+- `@deepseek-ai/dsh-lsp`（[`packages/lsp/lsp/src/index.ts`](../packages/lsp/lsp/src/index.ts)）
+- `@deepseek-ai/dsh-pty`（[`packages/pty/pty/src/index.ts`](../packages/pty/pty/src/index.ts)）
+- `@deepseek-ai/dsh-session`（[`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts)）
+- `@deepseek-ai/dsh-session-checkpoint-policy` — 需要 `llm` · `sessionPersistence` · `sessions` · `tools`（[`packages/session/session-checkpoint-policy/src/index.ts`](../packages/session/session-checkpoint-policy/src/index.ts)）
+- `@deepseek-ai/dsh-session-projection`（[`packages/session/session-projection/src/index.ts`](../packages/session/session-projection/src/index.ts)）
+- `@deepseek-ai/dsh-skill-badge` — 需要 `skills`（[`packages/skill/skill-badge/src/index.ts`](../packages/skill/skill-badge/src/index.ts)）
+- `@deepseek-ai/dsh-storage`（[`packages/storage/storage/src/index.ts`](../packages/storage/storage/src/index.ts)）
+- `@deepseek-ai/dsh-subagent`（[`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts)）
+- `@deepseek-ai/dsh-subprocess-local`（[`packages/subprocess/subprocess-local/src/index.ts`](../packages/subprocess/subprocess-local/src/index.ts)）
+- `@deepseek-ai/dsh-tasks-local`（[`packages/tasks/tasks-local/src/index.ts`](../packages/tasks/tasks-local/src/index.ts)）
+- `@deepseek-ai/dsh-timeout-policy` — 需要 `tools`（[`packages/guard/timeout-policy/src/index.ts`](../packages/guard/timeout-policy/src/index.ts)）
+- `@deepseek-ai/dsh-tool-ask-user` — 需要 `tools` · `userInteraction`（[`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts)）
+- `@deepseek-ai/dsh-tool-subagent-control` — 需要 `tools` · `subagents`（[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)）
+- `@deepseek-ai/dsh-user-interaction`（[`packages/interaction/user-interaction/src/index.ts`](../packages/interaction/user-interaction/src/index.ts)）
+- `@deepseek-ai/dsh-workspace` — 需要 `storageDomain` · `sessionPersistence`（[`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts)）
+
+## Seam 包（不可直接加载）
+
+抽象服务类——部署时应改为加载具体的实现包（参见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）。
+
+- `@deepseek-ai/dsh-bash` — 抽象 `BashExecutor`（[`packages/bash/bash/src/index.ts`](../packages/bash/bash/src/index.ts)）
+- `@deepseek-ai/dsh-code-runtime` — 抽象 `CodeRuntime`（[`packages/code-runtime/code-runtime/src/index.ts`](../packages/code-runtime/code-runtime/src/index.ts)）
+- `@deepseek-ai/dsh-compact` — 抽象 `CompactService`（[`packages/compact/compact/src/index.ts`](../packages/compact/compact/src/index.ts)）
+- `@deepseek-ai/dsh-credentials` — 抽象 `Credentials`（[`packages/credentials/credentials/src/index.ts`](../packages/credentials/credentials/src/index.ts)）
+- `@deepseek-ai/dsh-fs` — 抽象 `FileSystem`（[`packages/fs/fs/src/index.ts`](../packages/fs/fs/src/index.ts)）
+- `@deepseek-ai/dsh-host-directory-picker` — 抽象 `DirectoryPicker`（[`packages/host/directory-picker/src/index.ts`](../packages/host/directory-picker/src/index.ts)）
+- `@deepseek-ai/dsh-sandbox` — 抽象 `SandboxProvider`（[`packages/sandbox/sandbox/src/index.ts`](../packages/sandbox/sandbox/src/index.ts)）
+- `@deepseek-ai/dsh-session-persistence` — 抽象 `SessionPersistence`（[`packages/session/session-persistence/src/index.ts`](../packages/session/session-persistence/src/index.ts)）
+- `@deepseek-ai/dsh-session-query` — 抽象 `SessionQueryService`（[`packages/session-query/session-query/src/index.ts`](../packages/session-query/session-query/src/index.ts)）
+- `@deepseek-ai/dsh-settings` — 抽象 `Settings`（[`packages/settings/settings/src/index.ts`](../packages/settings/settings/src/index.ts)）
+- `@deepseek-ai/dsh-spill` — 抽象 `SpillStore`（[`packages/spill/spill/src/index.ts`](../packages/spill/spill/src/index.ts)）
+- `@deepseek-ai/dsh-subprocess` — 抽象 `SubprocessService`（[`packages/subprocess/subprocess/src/index.ts`](../packages/subprocess/subprocess/src/index.ts)）
+- `@deepseek-ai/dsh-tasks` — 抽象 `TaskService`（[`packages/tasks/tasks/src/index.ts`](../packages/tasks/tasks/src/index.ts)）
+- `@deepseek-ai/dsh-workflow` — 抽象 `WorkflowService`（[`packages/workflow/workflow/src/index.ts`](../packages/workflow/workflow/src/index.ts)）
+## 库包（无插件入口）
+
+由其他包作为库导入；`cordis.yml` 无法加载它们。
+
+- `@deepseek-ai/create-sdk`（[`packages/scaffold/create-sdk/src/index.ts`](../packages/scaffold/create-sdk/src/index.ts)）
+- `@deepseek-ai/dsh-acp-snapshot`（[`packages/support/acp-snapshot/src/index.ts`](../packages/support/acp-snapshot/src/index.ts)）
+- `@deepseek-ai/dsh-agent-loop-testkit`（[`packages/support/agent-loop-testkit/src/index.ts`](../packages/support/agent-loop-testkit/src/index.ts)）
+- `@deepseek-ai/dsh-app-boot`（[`packages/boot/app-boot/src/index.ts`](../packages/boot/app-boot/src/index.ts)）
+- `@deepseek-ai/dsh-atomic-write`（[`packages/util/atomic-write/src/index.ts`](../packages/util/atomic-write/src/index.ts)）
+- `@deepseek-ai/dsh-base`（[`packages/bundle/base/src/index.ts`](../packages/bundle/base/src/index.ts)）
+- `@deepseek-ai/dsh-brand`（[`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts)）
+- `@deepseek-ai/dsh-client-schema-form`（[`packages/client/schema-form/src/index.ts`](../packages/client/schema-form/src/index.ts)）
+- `@deepseek-ai/dsh-client-test-runtime`（[`packages/client/test-runtime/src/index.ts`](../packages/client/test-runtime/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-primitives`（[`packages/client/ui-primitives/src/index.ts`](../packages/client/ui-primitives/src/index.ts)）
+- `@deepseek-ai/dsh-client-ui-slots`（[`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts)）
+- `@deepseek-ai/dsh-client-web`（[`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts)）
+- `@deepseek-ai/dsh-client-web-react`（[`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts)）
+- `@deepseek-ai/dsh-environment`（[`packages/util/environment/src/index.ts`](../packages/util/environment/src/index.ts)）
+- `@deepseek-ai/dsh-helper`（[`packages/scaffold/helper/src/index.ts`](../packages/scaffold/helper/src/index.ts)）
+- `@deepseek-ai/dsh-hook-protocol`（[`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts)）
+- `@deepseek-ai/dsh-jsonrpc-demo`（[`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts)）
+- `@deepseek-ai/dsh-llm-mock-server`（[`packages/support/llm-mock-server/src/index.ts`](../packages/support/llm-mock-server/src/index.ts)）
+- `@deepseek-ai/dsh-loader-smoke`（[`packages/support/loader-smoke/src/index.ts`](../packages/support/loader-smoke/src/index.ts)）
+- `@deepseek-ai/dsh-native-command`（[`packages/util/native-command/src/index.ts`](../packages/util/native-command/src/index.ts)）
+- `@deepseek-ai/dsh-paths`（[`packages/util/paths/src/index.ts`](../packages/util/paths/src/index.ts)）
+- `@deepseek-ai/dsh-retention`（[`packages/util/retention/src/index.ts`](../packages/util/retention/src/index.ts)）
+- `@deepseek-ai/dsh-scope`（[`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts)）
+- `@deepseek-ai/dsh-scripts`（[`packages/scaffold/scripts/src/index.ts`](../packages/scaffold/scripts/src/index.ts)）
+- `@deepseek-ai/dsh-sdk-client`（[`packages/scaffold/client/src/index.ts`](../packages/scaffold/client/src/index.ts)）
+- `@deepseek-ai/dsh-sdk-protocol`（[`packages/scaffold/protocol/src/index.ts`](../packages/scaffold/protocol/src/index.ts)）
+- `@deepseek-ai/dsh-session-telemetry`（[`packages/session/session-telemetry/src/index.ts`](../packages/session/session-telemetry/src/index.ts)）
+- `@deepseek-ai/dsh-session-title-llm`（[`packages/session/session-title-llm/src/index.ts`](../packages/session/session-title-llm/src/index.ts)）
+- `@deepseek-ai/dsh-subagent-inprocess`（[`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts)）
+- `@deepseek-ai/dsh-telemetry`（[`packages/scaffold/telemetry/src/index.ts`](../packages/scaffold/telemetry/src/index.ts)）
+- `@deepseek-ai/dsh-timeout`（[`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts)）
+- `@deepseek-ai/dsh-type-meta`（[`packages/typert/type-meta/src/index.ts`](../packages/typert/type-meta/src/index.ts)）
+- `@deepseek-ai/dsh-typert-generator`（[`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts)）
+- `@deepseek-ai/dsh-typert-registry`（[`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts)）
diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml
index 0c26b8be17..53970e8479 100644
--- a/docs/cookbook/adding-a-package.i18n.yaml
+++ b/docs/cookbook/adding-a-package.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-package.md
 adding-a-package.md: 8ab603ea7b235bd2a582c9232afaca281a969448
-adding-a-package.zh.md: 8c0bc9dbd02b18a388f8e6ce91af10753c0210a2
+adding-a-package.zh.md: c076a58280aef8b218bc16af33eab233724bd57f
diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md
index 8c0bc9dbd0..c076a58280 100644
--- a/docs/cookbook/adding-a-package.zh.md
+++ b/docs/cookbook/adding-a-package.zh.md
@@ -1,8 +1,8 @@
-# 实操手册：添加 workspace 包（package）
+# 实操手册：添加 workspace 包
 
 [English](adding-a-package.md) | 中文
 
-为新建 `@deepseek-ai/dsh-<name>` 包提供的逐文件清单。本清单以 bash 和 adapter 这两个包为模板进行验证；如果清单与模板有出入，请在此修正。
+为新建 `@deepseek-ai/dsh-<name>` 包提供的逐文件清单。本清单以 bash 和适配器这两个包为模板进行验证；如果清单与模板有出入，请在此修正。
 
 ## 1. 创建包
 
@@ -22,7 +22,7 @@ packages/<group>/<pkg>/
 
 当已有分组与包的角色匹配时，选择该分组（`core`、`llm`、`bash`、`compact`、`subagent`、`todo`、`session-persistence`、`ui`、`util` 或 `support`）。允许新建分组，但分组只是纯容器：没有 `package.json`，没有源文件，包仍然恰好位于其下一层。
 
-package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-constraints.ts` 强制执行）：`private: true`，`version` 与根 `package.json` 一致，`type: module`，`main: "lib/index.js"`，`types: "lib/types/index.d.ts"`，`exports["."].types: "./lib/types/index.d.ts"`，`exports["."].default: "./lib/index.js"`，`cordis` 同时出现在 peerDependencies 和 devDependencies 中（相同范围）。每个 dsh 对等依赖（peer dependency）都要在 devDependencies 中镜像。`schemastery` 放在 `dependencies` 中（它是运行时校验器），与 agent-loop 保持一致。`files` 列表精确包含 `lib/index.js`、`lib/invariant.js`、`lib/types/**/*.d.ts` 以及门禁认可的包专用运行时产物；如果包的运行时 export 指向输出树，还要包含 `lib/types/**/*.js`。不要发布 `src`、声明映射、JS map 或陈旧的根声明文件。带有 `bin` 的 CLI 应用包在 `files` 中将 `lib/bin.js` 紧跟在 `lib/index.js` 之后。
+package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-constraints.ts` 强制执行）：`private: true`，`version` 与根 `package.json` 一致，`type: module`，`main: "lib/index.js"`，`types: "lib/types/index.d.ts"`，`exports["."].types: "./lib/types/index.d.ts"`，`exports["."].default: "./lib/index.js"`，`cordis` 同时出现在 peerDependencies 和 devDependencies 中（相同范围）。每个 dsh 对等依赖（peer dependency）都要在 devDependencies 中镜像。`schemastery` 放在 `dependencies` 中（它是运行时校验器），与 agent-loop 保持一致。`files` 列表精确包含 `lib/index.js`、`lib/invariant.js`、`lib/types/**/*.d.ts` 以及门禁认可的包专用运行时产物；如果包的运行时 export 指向输出树，还要包含 `lib/types/**/*.js`。不要发布 `src`、声明映射、JS map 或陈旧的根声明文件。带有 `bin` 的 CLI（命令行界面）应用包在 `files` 中将 `lib/bin.js` 紧跟在 `lib/index.js` 之后。
 
 包内的相对导入在源码中使用显式 `.ts` 后缀（例如 `export * from './types.ts'`）。编译器在输出的 JS 中将其重写为 `.js`，在声明文件中保留显式 `.ts` 后缀；标准的 NodeNext/Node16 TypeScript 消费方会将其解析到同目录的 `.d.ts` 文件。
 
@@ -31,16 +31,16 @@ package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-c
 | 文件 | 变更 |
 |---|---|
 | `tsconfig.base.json` | 已有分组无需编辑；新分组需为 `@deepseek-ai/dsh-*` 通配符添加 `./packages/<group>/*/src` 候选路径 |
-| `tsconfig.host.json`（Host 包）或 `tsconfig.client.json`（Client 包） | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }`——普通包恰好属于一个 aggregate，绝不两个都加。`api/remotes` 因 Host 生成契约与 Client 消费契约之间存在顺序依赖而使用仓库专属拆分，新增包不得仿照（[布局](../development.md#typescript-project-layout)） |
+| `tsconfig.host.json`（Host 包）或 `tsconfig.client.json`（Client 包） | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }`——普通包恰好属于一个 aggregate，绝不两个都加。`api/remotes` 因 Host 生成的契约产物要到后续阶段才由 Client 消费而使用仓库专属拆分，新增包不得仿照（[布局](../development.md#typescript-project-layout)） |
 | `knip.json` | 仅当包有仓库发现机制尚未覆盖的入口时需要 |
 
-`packages/client/*` 包改为 extends `tsconfig.base.client.json`（而非 `tsconfig.base.json`）；client 插件包还需在 package.json 声明 `dshClient`、导出 `./client`、调用共享 tsdown preset（`packages/client/tsdown.client.ts`）——client 侧见 [packages/client/AGENTS.md](../../packages/client/AGENTS.md)。
+`packages/client/*` 包改为 extends `tsconfig.base.client.json`（而非 `tsconfig.base.json`）；client 插件包还需在 package.json 声明 `dshClient`、导出 `./client`、调用共享 tsdown preset（`packages/client/tsdown.client.ts`）——client 侧约定见 [packages/client/AGENTS.md](../../packages/client/AGENTS.md)。
 
-以下内容由 glob 或包 manifest 发现机制自动覆盖，无需手动编辑：根 `package.json` workspaces、`scripts/publint-all.ts`、`tsdown.config.ts`、`.oxlintrc.json`、`scripts/check-workspace-constraints.ts`。
+以下内容由 glob 或包 manifest（元数据清单）发现机制自动覆盖，无需手动编辑：根 `package.json` workspaces、`scripts/publint-all.ts`、`tsdown.config.ts`、`.oxlintrc.json`、`scripts/check-workspace-constraints.ts`。
 
 ## 3. 确定包拓扑
 
-对于可替换的能力，将接口、实现、消费方拆分为独立的包（见 docs/architecture.md § "Capability seams"——bash 三组件是模板）。单一用途的插件保持为一个包。
+对于可替换的能力，将接口、实现、消费方拆分为独立的包（见 docs/architecture.md §「能力 seam」——bash 三组件是模板）。单一用途的插件保持为一个包。
 
 ## 4. 编写包 README
 
@@ -74,9 +74,9 @@ Append-only, prefix-stable, replacing, or independent behavior, including the ex
 - **Consumer-visible gap** — exact boundary, consequence, or maintainer constraint.
 ````
 
-根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述三个有序 H4 字段，每个字段下有一个正文段落。引用包拥有的稳定文本：系统提示词放在引出它的字段下，用带标题的 H5 加 `markdown` 围栏表示，通常归入 `What the model sees`；其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。tool-schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。填写 `KV Cache effect` 时，应区分仅追加增长、稳定重复的前缀、替换既有请求 token 和独立模型请求，并列出会使缓存复用失效、且由本包拥有的变化。“不使缓存失效”仅表示本包保留了已有的可复用前缀；缓存是否可用以及何时淘汰不属于本包契约。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。
+根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述三个有序 H4 字段，每个字段下有一个正文段落。引用包拥有的稳定文本：系统提示词放在引出它的字段下，用带标题的 H5 加 `markdown` 围栏表示，通常归入 `What the model sees`；其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。工具 schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏提示词或 schema 其中之一而不影响另一个时，将二者分开。填写 `KV Cache effect` 时，应区分仅追加增长、稳定重复的前缀、替换既有请求 token 和独立模型请求，并列出会使缓存复用失效、且由本包拥有的变化。「不使缓存失效」仅表示本包保留了已有的可复用前缀；提供方缓存是否可用以及何时淘汰不属于本包约定。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。
 
-没有上下文效果或仅有消费方拥有路径的包使用 [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) 中经过审计的 `None, as ` 或 `Indirectly, through ` 语句，随后添加 `KV Cache effect` H4 和一个非空正文段落；与模型无关的通用包可以改为加入 `NO_MODEL_EXPERIENCE_SECTION`。两种情况都不要展开为对另一个包工作的描述。limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) 独立管理。[Model Experience Agent Note](../../.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md) 记录了设计动机。
+没有上下文效果或仅有一条由消费方拥有的路径的包使用 [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) 中经过审计的 `None, as ` 或 `Indirectly, through ` 语句，随后添加 `KV Cache effect` H4 和一个非空正文段落；与模型无关的通用包可以改为加入 `NO_MODEL_EXPERIENCE_SECTION`。两种情况都不要展开为对另一个包工作的描述。limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) 独立管理。[Model Experience Agent Note](../../.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md) 记录了设计动机。
 
 ## 5. 验证
 
@@ -87,4 +87,4 @@ pnpm run constraints && pnpm run typecheck && pnpm run lint
 pnpm run build && pnpm run hygiene
 ```
 
-请遵循[仓库测试政策](../testing.md)，为新包运行行为所需的专项检查并达到相应覆盖率。
+请遵循[仓库测试政策](../testing.md)，执行新包所需的针对具体行为的检查，并达到相应覆盖率。
diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml
index ca64363bd6..018f97fc45 100644
--- a/docs/cookbook/adding-a-tool.i18n.yaml
+++ b/docs/cookbook/adding-a-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-tool.md
 adding-a-tool.md: cb418a9118901cc6572fb17125351bdda922434b
-adding-a-tool.zh.md: d8b73a51d1dde8647e7a032648f8a6344fcc83eb
+adding-a-tool.zh.md: adf4422688498341343e3317cb36aa23ece72734
diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md
index d8b73a51d1..adf4422688 100644
--- a/docs/cookbook/adding-a-tool.zh.md
+++ b/docs/cookbook/adding-a-tool.zh.md
@@ -2,7 +2,7 @@
 
 [English](adding-a-tool.md) | 中文
 
-面向模型的工具必须满足哪些契约，均以本文为准。如需按步骤构建第一个工具，请阅读[构建工具](../user/develop/basic/tool.md)。`packages/bash/tool-bash` 是生产级的三包示例。
+面向模型的工具必须满足哪些约定，均以本文为准。如需按步骤构建第一个工具，请阅读[构建工具](../user/develop/basic/tool.md)。`packages/bash/tool-bash` 是生产级的三包示例。
 
 ## 最小形态
 
@@ -37,7 +37,7 @@ export function apply(ctx: Context) {
 
 注册基于副作用：dispose（资源释放）插件 fiber 即注销该工具。schema 会自动流入系统提示词的组装过程。
 
-## execute() 契约的规则
+## execute() 约定的规则
 
 - **参数已为你校验。** `defineTool` 在 `execute` 运行前，会根据统一的 `ParameterSchemaSpec` 校验模型生成的 `arguments`（类型、必填键、字面量约束、恰好匹配一个分支的联合以及嵌套值——见[运行时参数校验](../../.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md)），因此 `execute` 内的 args 会匹配 `InferArgs`。显式对象节点必须声明 `additionalProperties: true | false`；隐式参数根对象保持开放。你仍需手动检查 schema DSL 无法表达的约束，例如非空字符串、正数或跨字段规则。直接注册的原始 JSON Schema 工具自行负责输入校验。
 - **注册借用你的只读定义。** 类型化的同进程贡献不是序列化边界；注册后不要修改其 schema 或替换回调。`schemas()` 只物化显式的模型可见投影。如需热替换工具，请 dispose 其所属副作用并注册替代品；回调闭包内的可变状态仍是普通的插件状态。
@@ -52,17 +52,17 @@ export function apply(ctx: Context) {
 
 通过 producer 配置控制 `run_in_background`，然后使用 `ctx.tasks.start({ kind, label, owner: exec.agent, run })` 注册任务。注册表会在进入 producer 主体前将已预先中止的调用判为失败；运行时会在 `run()` 启动工作前校验 owner 和控制面是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。成功的后台分支会返回类型化的规范句柄，如 `{ kind: 'background', taskId }`；其 Native 渲染器可以保留 `started background task bash-1` 这类供人阅读的自然语言，但 Code Mode 绝不能通过解析该文本取得 id。
 
-producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.tasks.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `task_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整契约见[后台 task 运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
+producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.tasks.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `task_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整约定见[后台任务运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
 
 ## 执行策略与观测
 
-尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许／拒绝／询问策略（见[权限门禁示例](extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝，后续监听器无法撤销；使用 `tools/execute` 为规范分发包装截止时间／重试／指标作用域；使用 `tools/post-execute` 替换展示内容或规范值、阻止调用，或附加模型可见上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。替换内容不会阻止程序化访问 `value`；保密策略必须阻止调用或替换值。沙箱实现也可以位于工具执行器的能力 seam 之后；确切契约见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。
+尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许／拒绝／询问策略（见[权限门禁示例](extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝，后续监听器无法撤销；使用 `tools/execute` 为规范分发包装截止时间／重试／指标作用域；使用 `tools/post-execute` 替换展示内容或规范值、阻止调用，或附加模型可见上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。替换内容不会阻止程序化访问 `value`；保密策略必须阻止调用或替换值。沙箱实现也可以位于工具执行器的能力 seam 之后；确切约定见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。
 
 ## Code Mode 自动触达你的工具
 
 在 [Code Mode](../../packages/core/tools/README.md) 中，每个可见的已注册工具都可通过 `await tools.<name>(args)` 调用，无需额外集成。生成的 `ToolArgsMap` 和 `ToolOutputMap` 会根据同一组 schema 分别派生精确的参数类型与规范返回类型，调用则重新进入正常的执行流水线。成功调用会解析为策略处理后的最终规范 JSON 值，而不是渲染后的 Native 内容。失败调用会以真正的 `ToolCallError` reject；程序只能检查其 `name`、`toolName` 和可供人阅读的 `message`，无法取得内部错误代码或失败联合。
 
-请把 `output.schema` 设计为实用的程序化 API：直接返回句柄与字段；当标量、数组或 null 确实就是结果时，允许采用相应的根类型；将面向人类的解释放入 `output.render`。中间值只存在于执行期间，不会被持久化或按提示词上限截断，也不设字节上限，因此生产方如实声明的采集边界和进程内存仍然重要。只有外层 `run_code` 日志／结果会受到可配置输出上限和面向模型的输出落盘流水线约束。
+请把 `output.schema` 设计为实用的程序化 API：直接返回句柄与字段；当标量、数组或 null 确实就是结果时，允许采用相应的根类型；将面向人类的解释放入 `output.render`。中间值只存在于执行期间，不会被持久化或按提示词上限截断，也不设字节上限，因此生产方如实声明的采集边界和进程内存仍然重要。只有外层 `run_code` 日志／结果会受到可配置输出上限和面向模型的 spill 流水线约束。
 
 ## 工具在 UI 中的渲染方式
 
@@ -71,19 +71,19 @@ producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的
 两个方法都返回一个 **`card` 标签的渲染意图**——选择与你的工具行为匹配的卡片类型：
 
 - `presentCall(args)` → 一个 `ToolCallView`（PENDING 卡片）：
-  - `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`——默认。设置 `kind` 获取图标（`read`/`search`/…）；设置 `locations: [{ path, line? }]` 标注工具涉及的文件，使有能力的编辑器跟随/跳转。
+  - `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`——默认。设置 `kind` 获取图标（`read`／`search`／…）；设置 `locations: [{ path, line? }]` 标注工具涉及的文件，使有能力的编辑器跟随／跳转。
   - `{ card: 'terminal', title, description?, cwd? }`——你的调用本身就是 shell 命令。`title` 是命令，`description` 渲染在终端卡片上方。（tool-bash。）
-  - `{ card: 'diff', title, diffs, locations? }`——你的调用创建或修改文件。`diffs: [{ path, oldText, newText }]`（新文件时 `oldText: null`）渲染为内联 diff 卡片。（tool-fs `write`/`edit`。）
+  - `{ card: 'diff', title, diffs, locations? }`——你的调用创建或修改文件。`diffs: [{ path, oldText, newText }]`（新文件时 `oldText: null`）渲染为内联 diff 卡片。（tool-fs `write`／`edit`。）
 - `presentResult(args, { content, isError, meta? })` 返回完成后的卡片：
   - `generic` 提供可选的标题和内容。
   - `terminal` 提供原始输出和可选的退出元数据；各 UI 根据自身能力渲染对应视图或回退视图。
   - `diff` 提供已应用的 hunk，通常由 `output.presentationMeta` 派生并通过持久化的 `result.meta` 携带，使回放能重现它们。变更类工具保留 diff 结果，因为完成后的视图会替换 pending 卡片。
-  - `search` 提供从持久化 `result.meta` 重建的发现型结果：按文件分组的匹配（`shape: 'matches'`，grep）或扁平路径列表（`shape: 'paths'`，glob），外加 `truncated`/`total` 使 UI 永不把被截断的结果当作完整结果呈现。该视图不携带结果文本（无 search 卡片的 UI 回退到原始结果内容），也没有 `search` 调用视图——发现型调用的 pending 状态保持为 generic 卡片，因为匹配只在 `execute` 之后才存在。（tool-fs-search 的 `grep`/`glob`。）
+  - `search` 提供从持久化 `result.meta` 重建的发现型结果：按文件分组的匹配（`shape: 'matches'`，grep）或扁平路径列表（`shape: 'paths'`，glob），外加 `truncated`／`total` 使 UI 永不把被截断的结果当作完整结果呈现。该视图不携带结果文本（无 search 卡片的 UI 回退到原始结果内容），也没有 `search` 调用视图——发现型调用的 pending 状态保持为 generic 卡片，因为匹配只在 `execute` 之后才存在。（tool-fs-search 的 `grep`／`glob`。）
   - `web` 提供已完成的 web 检索，以 `kind: 'search' | 'fetch'` 区分（结构化的搜索来源或抓取摘要），由 `result.meta` 派生；它不携带正文副本，因此不具备 `web` 能力的 UI 回退到原始结果内容。（tool-web `web_search`／`web_fetch`。）
 
 硬性规则（违反会出问题）：
 
-- **纯函数。** 这些方法在实时流式输出和会话日志回放时都会运行，因此必须是 `args`（加 result）的纯函数——不做 I/O、不读会话状态、不用时钟/随机数。diff 从 args 派生（`write` 使用 `oldText: null`，因为调用时的展示器没有文件先前内容）；会话上下文由 UI 适配器而非工具提供。如果你发现自己想在 `presentCall` 内获取文件旧内容或工作目录，请停下：那属于持久结果元数据或适配器，不属于展示器。
+- **纯函数。** 这些方法在实时流式输出和会话日志回放时都会运行，因此必须是 `args`（加 result）的纯函数——不做 I/O、不读会话状态、不用时钟／随机数。diff 从 args 派生（`write` 使用 `oldText: null`，因为调用时的展示器没有文件先前内容）；会话上下文由 UI 适配器而非工具提供。如果你发现自己想在 `presentCall` 内获取文件旧内容或工作目录，请停下：那属于持久结果元数据或适配器，不属于展示器。
 - **UI 格式不进入模型结果。** 围栏 ` ```console ` 块、diff、相对化路径均不应仅为服务 UI 而进入规范值或 Native 内容。`output.render` 负责模型可见的自然语言；`presentationMeta` 和卡片展示器负责可回放的 UI 状态。`terminal` 结果视图携带原始输出，由适配器按需添加回退格式。
 - **`defineTool` 对展示路径做软校验。** 格式错误或旧版日志中的 arg 形态会使包装器返回 `undefined`（通用回退）而非抛异常——展示绝不能导致回放崩溃。
 
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index e341244f40..c053132c54 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/extension-cookbook.md
 extension-cookbook.md: e04f6ffcf9a32ba3ee7344db18cad113b347c667
-extension-cookbook.zh.md: c2fa2f83c39ca0eb93397f39c88265c028224c7a
+extension-cookbook.zh.md: 83521cd348c68ba6f20f5beecfbcde51b0f2fb02
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index c2fa2f83c3..83521cd348 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -6,7 +6,7 @@ harness 扩展表面的参考形态。代码片段省略了 import 和辅助实
 
 ## 工具插件
 
-工具在 `ctx.tools` 上注册。带注解的 `defineTool` 示例（类型化的 `execute` 参数、结果塑形、`run_in_background` 模式）见 [adding-a-tool.md](adding-a-tool.md)——该指南是工具形态的真源。`ctx.tools.register()` 也直接接受原始 JSON-Schema `ToolDefinition`（MCP 来源的工具就是这样到达的）；`defineTool` 是为第一方工具提供的类型化语法糖。
+工具在 `ctx.tools` 上注册。带注解的 `defineTool` 示例（类型化的 `execute` 参数、结果塑形、`run_in_background` 模式）见 [adding-a-tool.md](adding-a-tool.md)——该指南是工具形态的真源。`ctx.tools.register()` 也直接接受原始 JSON Schema `ToolDefinition`（MCP 来源的工具就是这样到达的）；`defineTool` 是为第一方工具提供的类型化语法糖。
 
 ## 钩子插件（以权限门禁为例）
 
@@ -64,7 +64,7 @@ export function apply(ctx: Context) {
 
 *协议驱动*将协议对端接入 `ctx.agents`；它可以服务于 UI 或自动化客户端。stdio 驱动拥有 stdout，通过工厂创建或恢复 agent（智能体），并将协议请求映射为 `followup()` 或 `cancel()`。底层提示词请求返回其持久入队回执；它不会通过关联 `MessageId` 与 `turn/end` 获得结果。整个 agent 的状态应单独发布。自动化方法可以从回执等待到下一次 idle，并概括这一显式拥有的区间；UI 通常则会持续观察开放式事件流。通过 `AgentHandle.dispose()` 拆除 agent，以使 dispose（资源释放）达到完全停稳。
 
-[`packages/acp/acp`](../../packages/acp/acp) 是仅面向自动化的完整示例：它通过 ACP（Agent Client Protocol）JSON-RPC stdio 提供全新文本会话，发出已提交的助手文本，并为其拥有的 agent 注册一次性机器权限应答器。其 [README](../../packages/acp/acp/README.md) 拥有精确的方法和生命周期契约。
+[`packages/acp/acp`](../../packages/acp/acp) 是仅面向自动化的完整示例：它通过 ACP（Agent Client Protocol）JSON-RPC stdio 提供全新文本会话，发出已提交的助手文本，并为其拥有的 agent 注册一次性机器权限应答器。其 [README](../../packages/acp/acp/README.md) 拥有精确的方法和生命周期约定。
 
 ```ts
 import type { Context } from 'cordis'
@@ -100,29 +100,29 @@ export function apply(ctx: Context) {
 
 | 产品功能 | 插件机制 |
 |---|---|
-| 钩子系统（用户级 + 项目级） | `agent/session-start`、`agent/pre-step`、`agent/request`、`tools/pre-execute`、`tools/post-execute` 和 `agent/turn-stopping` 上的监听器；waterfall seam 返回类型化决策，`agent/turn-stopping` 则可通过 steering 触发下一步；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些 seam 上 |
-| `/goal` | `ctx.goals` 管理持久状态，`dsh-goal-session` 通过公共 `Agent` 调度同会话回合，独立的命令/工具生产方分别提供人类/模型控制 |
+| 钩子系统（用户级 + 项目级） | `agent/session-start`、`agent/pre-step`、`agent/request`、`tools/pre-execute`、`tools/post-execute` 和 `agent/turn-stopping` 上的监听器；waterfall seam 返回类型化决策，`agent/turn-stopping` 则可通过 steering（中途引导）触发下一步；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些 seam 上 |
+| `/goal` | `ctx.goals` 管理持久状态，`dsh-goal-session` 通过公共 `Agent` 调度同会话 Round，独立的命令/工具生产方分别提供人类/模型控制 |
 | `/loop` | 在 `turn/end` 会话事件上 `followup()` 下一次迭代；或强制继续 |
-| 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的 prompt/工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code`）和结构化输出执行的单调 `concludeTurn()` 标记来强制输出 |
-| 排队消息 + steering（中途引导） | 核心 `Agent.followup()` / `Agent.steer()` |
+| 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的提示词/工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code`）和结构化输出执行的单调 `concludeTurn()` 标记来强制输出 |
+| 排队消息 + steering | 核心 `Agent.followup()` / `Agent.steer()` |
 | 上下文压缩（context compaction）（自动 + 手动） | `ctx.compact` seam + `dsh-compact-basic`；自动压力检查运行在串行 `agent/pre-step`，规范化溢出恢复运行在 `agent/request-error`，手动调用方使用同一个压缩服务（[压缩 Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)——面向模型的 `/compact` 消费方工具已推迟） |
 | 系统提示词可配置性 | `ctx.systemPrompt.section()`，支持排序与作用域局部覆盖 |
-| AGENTS.md（根目录） | 一个读取该文件的 section provider |
-| AGENTS.md（子目录，按需触发）+ 文件变更通知 | 从 watcher / tool-result 监听器调用 `agent.inject()` |
+| AGENTS.md（根目录） | 一个读取该文件的 section 提供方 |
+| AGENTS.md（子目录，按需触发）+ 文件变更通知 | 从 watcher / 工具结果监听器调用 `agent.inject()` |
 | 内置工具 | `ctx.tools.register()`；schema 自动流入装配——`dsh-tool-*` 系列（bash、fs、web、subagent、todo）是已交付的示例 |
 | ToolSearch / 渐进式披露 | 当可见集变化时替换一个作用域化的 `ctx.tools.restrict()` 注册；注册表保持展示、查找和执行三者对齐 |
-| 工具截止时间 / 重试 / 指标 | 用 `tools/execute` 包裹核心分发；包装器可替换 `exec.signal`、委托执行，并在同一词法生命周期内检视规范化结果 |
+| 工具截止时间 / 重试 / 指标 | 用 `tools/execute` 包裹核心分发；包装层可替换 `exec.signal`、委托执行，并在同一词法生命周期内检视规范化结果 |
 | 最终工具结果指标 / 审计 / 捕获 | 用 `tools/result` 观察不可变的权威结果；仅当插件需要变换结果或附加上下文时才使用 `tools/post-execute` |
 | 单调终端轮次策略 | 从成功的终端工具调用 `ToolExecution.concludeTurn()`；同一响应中后续工具调用仍可由守卫阻止，循环在该步骤后停止 |
 | 子进程沙箱（landlock / sandbox-exec） | 通过 `dsh-bash-sandbox` 使用 `ctx.sandbox` 后端；能力级别的拒绝使用 `tools/pre-execute` |
 | 权限系统 / AskUserQuestion | 从 `tools/pre-execute` 返回 `ask` 并通过 `ctx.approval` 应答；为普通用户提问注册一个独立的面向模型的 ask 工具 |
-| Plan mode | 已交付：[`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md) — 落日志的 `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
-| 子 agent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn`/`-fork`/`-acp`/`-codex`/`-claude-code`/`-dsh-sdk`）+ `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
+| Plan mode | 已交付：[`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md)：落日志的 `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
+| subagent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn`/`-fork`/`-acp`/`-codex`/`-claude-code`/`-dsh-sdk`）+ `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
 | MCP | 每个服务器一个插件：发现工具 → `ctx.tools.register()` |
-| Skill（技能） | section + 工具注册；调用时通过 `inject()` 注入 skill 内容 |
-| 记忆 | section provider + 工具 |
+| skill（技能） | section + 工具注册；调用时通过 `inject()` 注入 skill 内容 |
+| 记忆 | section 提供方 + 工具 |
 | 定时任务（cron） | 插件注册面向模型的调度工具；定时器触发 → 空闲时 `followup(…, {source: {kind: 'cron', …}})`／忙碌时 `inject()` 通知 |
 | UI（GUI；CLI（命令行界面）输出 JSONL） | 监听 `session/event`（助手分片、边界、工具活动）；输入 → `followup()` |
 | 遥测 / 可回放 trace | `session/event` → JSONL；回放 = `sessions.create(id, { seed })` |
 | 模型适配器 | 通过 `registerAdapter` 注册 `LlmAdapter` 子类（`dsh-llm-deepseek`、`dsh-llm-pi-ai`） |
-| 插件热重载 | 每个注册都是一个 `ctx.effect` → vendor 的 HMR（热模块替换）直接生效 |
+| 插件热重载 | 每个注册都是一个 `ctx.effect` → 随仓库提供的 HMR（热模块替换）直接生效 |
diff --git a/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml b/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
index 86a72161b2..7757b8419d 100644
--- a/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
+++ b/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/responding-to-pr-review-on-a-stack.md
 responding-to-pr-review-on-a-stack.md: 6bb7be3daf8613666f02f21e96bf7b1ac8cb3606
-responding-to-pr-review-on-a-stack.zh.md: 94c2bd2cdd03b9eeca1e180b09bb71471db91c0a
+responding-to-pr-review-on-a-stack.zh.md: 7567220096bb9dd6f3f68c16c08493ffb7529de7
diff --git a/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md b/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
index 94c2bd2cdd..7567220096 100644
--- a/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
+++ b/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
@@ -15,11 +15,11 @@
 ## 沿堆叠解决评审意见
 
 1. 在行动之前先就事论事地审视每条评论：对照代码验证其论断——评审者指出了正确的症状，但仍可能误诊原因。
-2. 将每个被接受的发现映射到其发起 PR，并在那里修复。
+2. 将每个被接受的发现映射到引入该问题的 PR，并在那里修复。
 3. 将修复后的层按顺序传播到每个受影响的子 PR：
    - **Merge-forward：** 将修复后的父分支合并到其子分支，验证子分支，然后继续沿堆叠向上传播。依照[增量更新 base 的决策](../../.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)，保留每个正在处理的检查点。
    - **原生级联 rebase：** 使用 `gh stack rebase`，验证所有已改写的层，然后通过 `gh stack push` 发布；也可以使用 `gh stack sync`，该命令可能先发布，因此必须按照 [dsh-pre-push-checks](../../.agents/skills/dsh-pre-push-checks/SKILL.md) 在同步后立即验证。
-4. 委派的修复需要信任但验证：子 agent（智能体）的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。子 agent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
+4. 委派的修复需要信任但验证：subagent的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。subagent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
 5. 在评审线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），而非发顶层评论；说明修复内容及当前承载修复的 commit 或 head。
 6. 每次改写推送后，都要重新读取未解决线程、批准状态、可合并性和检查结果。经 force-push 改写的 commit OID 或已过时的内联锚点，都不足以证明该发现当前仍处于已解决状态。
 7. 仅可通过官方堆叠流程落地。如果这些 PR 尚未关联，落地 skill 会自动关联作者相同的链；如果作者不同，则先询问用户；如果原生堆叠支持不可用，则硬性停止流程。
diff --git a/docs/cordis-api/context.i18n.yaml b/docs/cordis-api/context.i18n.yaml
new file mode 100644
index 0000000000..618b112792
--- /dev/null
+++ b/docs/cordis-api/context.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 docs/cordis-api/context.md
+context.md: 320b23de1c8d19e2dacdf0ec9f2361037bcf8048
+context.zh.md: 2e4cdc1d2822d6cc19bf1907a44cc31c429016ea
diff --git a/docs/cordis-api/context.zh.md b/docs/cordis-api/context.zh.md
new file mode 100644
index 0000000000..2e4cdc1d28
--- /dev/null
+++ b/docs/cordis-api/context.zh.md
@@ -0,0 +1,366 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/context.md` 重新记录配对。 -->
+
+# 上下文
+
+[English](context.md) | 中文
+
+上下文是 Cordis 的核心对象：所有服务、事件和生命周期 API 都通过 `ctx` 访问。事件方法见[事件](events.md)，副作用与当前 fiber 见 [Fiber](fiber.md)，插件加载见[注册表](registry.md)。
+
+Cordis 插件的根依赖容器和子依赖容器。
+
+上下文是一个代理：普通属性读取通过服务解析器进行，而 `extend()`、`isolate()` 和 `intercept()` 会创建有作用域的子上下文，且不修改其父上下文。
+
+[源码](../../vendor/cordis/src/context.ts#L42)
+
+### ctx.extend(meta?)
+
+```ts cordis-catalog
+/**
+ * Create a child context with extra metadata on top of the current scope.
+ *
+ * The child prototypally inherits every property of this context; own
+ * properties of `meta` shadow the inherited ones. The parent is not mutated.
+ *
+ * @param meta — own properties (including symbol keys) to define on the child.
+ * @returns a child context inheriting from this one.
+ */
+extend(meta = {}): this
+```
+
+在当前作用域之上创建一个带有额外元数据的子上下文。
+
+子上下文通过原型继承当前上下文的所有属性；`meta` 的自有属性会遮蔽继承的同名属性。父上下文不会被修改。
+
+- `meta`：要在子上下文上定义的自有属性，包括以 symbol 为键的属性。
+
+**返回**继承自当前上下文的子上下文。
+
+[源码](../../vendor/cordis/src/context.ts#L99)
+
+### ctx.isolate(name, label?)
+
+```ts cordis-catalog
+/**
+ * Create a child context with an independent service scope for `name`.
+ *
+ * Below the returned context, reads and writes of the service `name`
+ * resolve against the new label instead of the parent's, so a different
+ * implementation can be provided without affecting the parent scope.
+ * Passing the same `label` to two `isolate()` calls joins their scopes.
+ *
+ * @param name — the service name to isolate.
+ * @param label — scope label to join; defaults to a fresh unique symbol.
+ * @returns a child context whose `name` service resolves in the new scope.
+ */
+isolate(name: string, label?: symbol)
+```
+
+创建一个子上下文，使 `name` 拥有独立的服务作用域。
+
+在返回的上下文之下，对服务 `name` 的读写会根据新标签解析，而不再根据父上下文的标签解析，因此可以提供不同的实现而不影响父作用域。向两次 `isolate()` 调用传入相同的 `label`，可使二者加入同一作用域。
+
+- `name`：要隔离的服务名称。
+- `label`：要加入的作用域标签；默认为一个新建的唯一 symbol。
+
+**返回**一个子上下文，其 `name` 服务在新作用域中解析。
+
+[源码](../../vendor/cordis/src/context.ts#L121)
+
+### ctx.intercept(name, config)
+
+```ts cordis-catalog
+/**
+ * Add service-specific intercept config for plugins started below this
+ * context.
+ *
+ * Plugins loaded under the returned context see `config` merged into the
+ * service's resolved config (ancestor entries first; see
+ * `Service[symbols.resolveConfig]`). The parent context is not affected.
+ *
+ * @param name — the service name whose config to intercept.
+ * @param config — the intercept config to merge for that service.
+ * @returns a child context carrying the additional intercept entry.
+ */
+intercept<K extends InjectKey>(name: K, config: Context[K] extends { [symbols.config]: infer T } ? T : never): this
+intercept(name: string, config: any): this
+```
+
+为在此上下文之下启动的插件添加服务专属的拦截配置。
+
+在返回的上下文下加载的插件会看到 `config` 已合并到服务解析后的配置中（祖先条目在前；见 `Service[symbols.resolveConfig]`）。父上下文不受影响。
+
+- `name`：要拦截其配置的服务名称。
+- `config`：要为该服务合并的拦截配置。
+
+**返回**一个携带额外拦截条目的子上下文。
+
+[源码](../../vendor/cordis/src/context.ts#L139)
+
+### ctx.root
+
+```ts cordis-catalog
+/** The root context of the application (every child context shares it). @experimental */
+root: this
+```
+
+应用的根上下文，所有子上下文均共享它。@experimental
+
+[源码](../../vendor/cordis/src/context.ts#L22)
+
+### ctx.baseUrl
+
+```ts cordis-catalog
+/** Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. */
+baseUrl?: string
+```
+
+用于解析相对插件／模块说明符的基础 URL，前提是运行时设置了该值。
+
+[源码](../../vendor/cordis/src/context.ts#L24)
+
+### ctx.events
+
+```ts cordis-catalog
+/** The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...). */
+events: EventsService
+```
+
+事件总线。它的方法也会混入 `ctx`（`ctx.on`、`ctx.emit` 等）。
+
+[源码](../../vendor/cordis/src/context.ts#L26)
+
+### ctx.logger
+
+```ts cordis-catalog
+/** The logging service. Call `ctx.logger(name)` for a named logger. */
+logger: LoggerService
+```
+
+日志服务。调用 `ctx.logger(name)` 可获取具名 logger。
+
+[源码](../../vendor/cordis/src/context.ts#L28)
+
+### ctx.reflect
+
+```ts cordis-catalog
+/** The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...). */
+reflect: ReflectService
+```
+
+为上下文代理提供支持的反射层（`ctx.get`、`ctx.provide` 等）。
+
+[源码](../../vendor/cordis/src/context.ts#L30)
+
+### ctx.registry
+
+```ts cordis-catalog
+/** The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`). */
+registry: RegistryService
+```
+
+插件注册表。它的方法会混入 `ctx`（`ctx.plugin`、`ctx.inject`）。
+
+[源码](../../vendor/cordis/src/context.ts#L32)
+
+## 静态成员
+
+### Context.effect
+
+```ts cordis-catalog
+/** Symbol key under which a disposer exposes its {@link EffectMeta} diagnostics tree. */
+static readonly effect: unique symbol
+```
+
+资源释放函数用于公开其 EffectMeta 诊断树的 symbol 键。
+
+[源码](../../vendor/cordis/src/context.ts#L44)
+
+### Context.filter
+
+```ts cordis-catalog
+/** Symbol key for a context's listener filter, consulted on every event dispatch. */
+static readonly filter: unique symbol
+```
+
+上下文监听器过滤器的 symbol 键，每次分派事件时都会查询该过滤器。
+
+[源码](../../vendor/cordis/src/context.ts#L46)
+
+### Context.isolate
+
+```ts cordis-catalog
+/** Symbol key of the isolation map (see the `Context[symbols.isolate]` property). */
+static readonly isolate: unique symbol
+```
+
+隔离映射的 symbol 键（见 `Context[symbols.isolate]` 属性）。
+
+[源码](../../vendor/cordis/src/context.ts#L48)
+
+### Context.intercept
+
+```ts cordis-catalog
+/** Symbol key of the intercept map (see the `Context[symbols.intercept]` property). */
+static readonly intercept: unique symbol
+```
+
+拦截映射的 symbol 键（见 `Context[symbols.intercept]` 属性）。
+
+[源码](../../vendor/cordis/src/context.ts#L50)
+
+### Context.is(value)
+
+```ts cordis-catalog
+/**
+ * Returns true for Cordis context proxies and context prototypes.
+ *
+ * Works across realms and across multiple copies of cordis, because the
+ * brand is keyed by a global symbol rather than by `instanceof`.
+ *
+ * @param value — the value to test.
+ * @returns `true` if `value` is a Cordis context, narrowing its type.
+ */
+static is(value: any): value is Context
+```
+
+对于 Cordis 上下文代理和上下文原型，返回 true。
+
+此方法可跨 realm 和多个 cordis 副本工作，因为其品牌标识以全局 symbol 为键，而不是通过 `instanceof` 判断。
+
+- `value`：要测试的值。
+
+如果 `value` 是 Cordis 上下文，**返回** `true`，并收窄其类型。
+
+[源码](../../vendor/cordis/src/context.ts#L61)
+
+## 服务存储与混入
+
+### ctx.get(name, strict?)
+
+```ts cordis-catalog
+/**
+ * Read a service from the store without the inject requirement.
+ *
+ * @param name — the service name.
+ * @param strict — when `true` (default), only return implementations
+ * whose providing fiber is currently active.
+ * @returns the service value, or `undefined` when not (yet) provided.
+ */
+get<K extends string & keyof this>(name: K, strict?: boolean): undefined | this[K]
+get(name: string, strict?: boolean): any
+```
+
+从存储中读取服务，无需满足注入要求。
+
+- `name`：服务名称。
+- `strict`：设为 `true`（默认值）时，仅返回其提供方 fiber 当前处于活动状态的实现。
+
+**返回**服务值；如果尚未提供，则返回 `undefined`。
+
+[源码](../../vendor/cordis/src/reflect.ts#L17)
+
+### ctx.set(name, value)
+
+```ts cordis-catalog
+/**
+ * Overwrite a provided service's value.
+ *
+ * Only the fiber that provided the service may set it; setting an
+ * unprovided name throws.
+ *
+ * @param name — the service name.
+ * @param value — the new service value.
+ */
+set<K extends string & keyof this>(name: K, value: undefined | this[K]): void
+set(name: string, value: any): void
+```
+
+覆盖已提供服务的值。
+
+只有提供该服务的 fiber 才能设置它；设置尚未提供的名称会抛出异常。
+
+- `name`：服务名称。
+- `value`：新的服务值。
+
+[源码](../../vendor/cordis/src/reflect.ts#L29)
+
+### ctx.provide(name, value)
+
+```ts cordis-catalog
+/**
+ * Register a service implementation owned by the current fiber.
+ *
+ * The service becomes visible to dependents in the same isolation scope
+ * once the fiber is active; it is unregistered (waking dependents) when
+ * the returned disposer runs or the fiber unloads. Throws if the name is
+ * already provided in this scope or declared as an accessor.
+ *
+ * @param name — the service name.
+ * @param value — the service value.
+ * @returns a disposer that unregisters the service.
+ */
+provide<K extends string & keyof this>(name: K, value: undefined | this[K]): () => void
+provide(name: string, value?: any): () => void
+```
+
+注册一个归当前 fiber 所有的服务实现。
+
+fiber 激活后，该服务对同一隔离作用域内的依赖方可见；当返回的资源释放函数运行或 fiber 卸载时，该服务会被取消注册，并唤醒依赖方。如果该名称已在此作用域中被提供，或已声明为访问器，则抛出异常。
+
+- `name`：服务名称。
+- `value`：服务值。
+
+**返回**一个用于取消注册该服务的资源释放函数。
+
+[源码](../../vendor/cordis/src/reflect.ts#L44)
+
+### ctx.accessor(name, options)
+
+```ts cordis-catalog
+/**
+ * Define a computed context property backed by get/set hooks.
+ *
+ * The accessor is removed when the current fiber unloads. Throws if the
+ * name is already declared.
+ *
+ * @param name — the context property name.
+ * @param options — the `get` hook and optional `set` hook.
+ */
+accessor(name: string, options: Omit<Property.Accessor, 'type'>): void
+```
+
+定义一个由 get/set 钩子支持的计算型上下文属性。
+
+当前 fiber 卸载时会移除该访问器。如果该名称已被声明，则抛出异常。
+
+- `name`：上下文属性名称。
+- `options`：`get` 钩子和可选的 `set` 钩子。
+
+[源码](../../vendor/cordis/src/reflect.ts#L56)
+
+### ctx.mixin(name, mixins)
+
+```ts cordis-catalog
+/**
+ * Expose selected members of a service directly on `ctx`.
+ *
+ * Each mixed-in key becomes an accessor that forwards to the service
+ * (binding methods to it), so e.g. `ctx.on` forwards to `ctx.events.on`.
+ * Mixins are removed when the current fiber unloads.
+ *
+ * @param name — the context property holding the source service.
+ * @param mixins — keys to forward, or a source-key → ctx-key map.
+ */
+mixin<K extends string & keyof this>(name: K, mixins: (keyof this & keyof this[K])[] | Dict<string>): void
+mixin<T extends {}>(source: T, mixins: (keyof this & keyof T)[] | Dict<string>): void
+```
+
+直接在 `ctx` 上公开服务的指定成员。
+
+每个混入的键都会成为一个转发到该服务的访问器，并将方法绑定到该服务。例如，`ctx.on` 会转发到 `ctx.events.on`。当前 fiber 卸载时会移除这些混入。
+
+- `name`：存放源服务的上下文属性。
+- `mixins`：要转发的键，或从源键到 ctx 键的映射。
+
+[源码](../../vendor/cordis/src/reflect.ts#L67)
diff --git a/docs/cordis-api/events.i18n.yaml b/docs/cordis-api/events.i18n.yaml
new file mode 100644
index 0000000000..bcdc34be76
--- /dev/null
+++ b/docs/cordis-api/events.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 docs/cordis-api/events.md
+events.md: 8b8eb2358e10a250f581aecc725ba32360d338d3
+events.zh.md: 366f78fbe5d9bb5ff6f95c79c307237aaa97967a
diff --git a/docs/cordis-api/events.zh.md b/docs/cordis-api/events.zh.md
new file mode 100644
index 0000000000..366f78fbe5
--- /dev/null
+++ b/docs/cordis-api/events.zh.md
@@ -0,0 +1,209 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/events.md` 重新记录配对。 -->
+
+# 事件
+
+[English](events.md) | 中文
+
+每个上下文中都混入了事件分发 API。Harness 事件声明及其分发模式会生成到各自所属的[子系统页面](../subsystems/core.md)。
+
+### ctx.parallel(name, ...args)
+
+```ts cordis-catalog
+/**
+ * Dispatch an event, running all listeners concurrently.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to every listener.
+ * @returns a promise resolving once every listener has settled.
+ */
+parallel<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promise<void>
+parallel<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promise<void>
+```
+
+分发一个事件，并发运行所有监听器。
+
+- `name`：事件名称。
+- `args`：传递给每个监听器的参数。
+
+**返回值**：一个 Promise，在所有监听器均已完成后兑现。
+
+[源码](../../vendor/cordis/src/events.ts#L44)
+
+### ctx.emit(name, ...args)
+
+```ts cordis-catalog
+/**
+ * Dispatch an event synchronously, ignoring listener return values.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to every listener.
+ */
+emit<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void
+emit<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): void
+```
+
+同步分发一个事件，忽略监听器的返回值。
+
+- `name`：事件名称。
+- `args`：传递给每个监听器的参数。
+
+[源码](../../vendor/cordis/src/events.ts#L53)
+
+### ctx.serial(name, ...args)
+
+```ts cordis-catalog
+/**
+ * Dispatch an event, awaiting listeners in order until one bails.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to each listener.
+ * @returns the first bail value (non-null, non-false, non-undefined), if any.
+ */
+serial<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
+serial<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
+```
+
+分发一个事件，依次等待各监听器，直到其中一个提前终止分发。
+
+- `name`：事件名称。
+- `args`：传递给每个监听器的参数。
+
+**返回值**：第一个提前终止值（非 null、非 false 且非 undefined）；如果没有，则不返回此类值。
+
+[源码](../../vendor/cordis/src/events.ts#L63)
+
+### ctx.bail(name, ...args)
+
+```ts cordis-catalog
+/**
+ * Dispatch an event, calling listeners in order until one bails.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to each listener.
+ * @returns the first bail value (non-null, non-false, non-undefined), if any.
+ */
+bail<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+bail<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+```
+
+分发一个事件，依次调用各监听器，直到其中一个提前终止分发。
+
+- `name`：事件名称。
+- `args`：传递给每个监听器的参数。
+
+**返回值**：第一个提前终止值（非 null、非 false 且非 undefined）；如果没有，则不返回此类值。
+
+[源码](../../vendor/cordis/src/events.ts#L73)
+
+### ctx.waterfall(name, ...args)
+
+```ts cordis-catalog
+/**
+ * Dispatch an event whose last argument is a `next` continuation.
+ *
+ * Each listener wraps the rest of the chain: calling `next()` invokes the
+ * next listener (finally the built-in behavior); not calling it vetoes.
+ *
+ * @param name — the event name.
+ * @param args — listener arguments; the final one is the innermost `next`.
+ * @returns the outermost listener's return value.
+ */
+waterfall<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+waterfall<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
+```
+
+分发一个事件，其最后一个参数是续接执行的 `next` 回调。
+
+每个监听器都会包装调用链的其余部分：调用 `next()` 会执行下一个监听器，最终执行内置行为；不调用则会否决后续执行。
+
+- `name`：事件名称。
+- `args`：监听器参数；最后一个参数是最内层的 `next`。
+
+**返回值**：最外层监听器的返回值。
+
+[源码](../../vendor/cordis/src/events.ts#L86)
+
+### ctx.on(name, listener, options?)
+
+```ts cordis-catalog
+/**
+ * Register an event listener owned by the current fiber.
+ *
+ * @param name — the event name to listen for.
+ * @param listener — called with the dispatch arguments.
+ * @param options — listener options; a boolean is shorthand for `prepend`.
+ * @returns a disposer removing the listener; `true` if it was still registered.
+ */
+on<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean
+```
+
+注册一个归当前 fiber 所有的事件监听器。
+
+- `name`：要监听的事件名称。
+- `listener`：使用分发参数调用的监听器。
+- `options`：监听器选项；布尔值可作为 `prepend` 的简写。
+
+**返回值**：一个用于移除监听器的资源释放函数；如果调用该函数时监听器仍处于注册状态，则返回 `true`。
+
+[源码](../../vendor/cordis/src/events.ts#L97)
+
+### ctx.once(name, listener, options?)
+
+```ts cordis-catalog
+/**
+ * Same as `on()`, but the listener disposes itself after its first call.
+ *
+ * @param name — the event name to listen for.
+ * @param listener — called at most once with the dispatch arguments.
+ * @param options — listener options; a boolean is shorthand for `prepend`.
+ * @returns a disposer removing the listener; `true` if it was still registered.
+ */
+once<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean
+```
+
+与 `on()` 相同，但监听器在首次调用后会自行注销。
+
+- `name`：要监听的事件名称。
+- `listener`：使用分发参数调用，最多调用一次。
+- `options`：监听器选项；布尔值可作为 `prepend` 的简写。
+
+**返回值**：一个用于移除监听器的资源释放函数；如果调用该函数时监听器仍处于注册状态，则返回 `true`。
+
+[源码](../../vendor/cordis/src/events.ts#L106)
+
+## EventOptions
+
+`ctx.on()` 和 `ctx.once()` 接受的选项。
+
+```ts cordis-catalog
+/** Options accepted by `ctx.on()` and `ctx.once()`. */
+interface EventOptions {
+  /** Add the listener before existing listeners for the same event. */
+  prepend?: boolean
+  /** Receive the event regardless of context filter checks. */
+  global?: boolean
+}
+```
+
+[源码](../../vendor/cordis/src/events.ts#L112)
+
+## DispatchMode
+
+事件服务使用的事件分发策略。
+
+`emit` 运行同步监听器但不等待它们，`parallel` 同时等待所有监听器，`serial` 依次等待监听器直至其中一个提前终止分发，`bail` 遇到第一个同步提前终止值时停止，`waterfall` 则围绕最终的 `next` 回调组合监听器。
+
+```ts cordis-catalog
+/**
+ * Event dispatch strategy used by the event service.
+ *
+ * `emit` runs synchronous listeners without awaiting them, `parallel` awaits
+ * all listeners together, `serial` awaits them in order until one bails,
+ * `bail` stops on the first synchronous bail value, and `waterfall` composes
+ * listeners around a final `next` callback.
+ */
+type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'
+```
+
+[源码](../../vendor/cordis/src/events.ts#L32)
diff --git a/docs/cordis-api/fiber.i18n.yaml b/docs/cordis-api/fiber.i18n.yaml
new file mode 100644
index 0000000000..0c45c03f5f
--- /dev/null
+++ b/docs/cordis-api/fiber.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 docs/cordis-api/fiber.md
+fiber.md: 36d2861ac6a53e8186a92d86c65ba228d4b59ee5
+fiber.zh.md: 8fbc10c9870106f3fc7dfabe9725581898d9ef22
diff --git a/docs/cordis-api/fiber.zh.md b/docs/cordis-api/fiber.zh.md
new file mode 100644
index 0000000000..8fbc10c987
--- /dev/null
+++ b/docs/cordis-api/fiber.zh.md
@@ -0,0 +1,377 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/fiber.md` 重新记录配对。 -->
+
+# Fiber
+
+[English](fiber.md) | 中文
+
+fiber 是一个已加载的插件实例，包含其生命周期状态、经过校验的配置以及已注册的作用。`ctx.fiber` 是当前 fiber，`ctx.effect()` 会将调用委托给它。
+
+### ctx.effect(execute, label?)
+
+```ts cordis-catalog
+/**
+ * Register a cleanup-aware effect on this fiber.
+ *
+ * `execute` runs immediately; the disposers it produces are collected and
+ * run (in reverse order) either when the returned disposer is called or
+ * when the fiber unloads, whichever comes first. Calling the disposer twice
+ * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
+ * already disposed, and `TypeError` if `execute` returns an invalid shape.
+ *
+ * @param execute — the effect body; see {@link Effect} for accepted shapes.
+ * @param label — effect label shown in `getEffects()` diagnostics.
+ * @returns a disposer that tears the effect down and settles once done.
+ */
+effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
+effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
+```
+
+在此 fiber 上注册一个支持清理的作用。
+
+`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose（资源释放），则抛出 `CordisError('INACTIVE_EFFECT')`；如果 `execute` 返回的结构无效，则抛出 `TypeError`。
+
+- `execute`：作用主体；可接受的结构见 `Effect`。
+- `label`：在 `getEffects()` 诊断信息中显示的作用标签。
+
+**返回**一个用于撤销该作用的清理函数，并在清理完成后结算。
+
+[源码](../../vendor/cordis/src/fiber.ts#L420)
+
+### ctx.fiber
+
+```ts cordis-catalog
+/** The fiber (plugin runtime instance) that owns this context. */
+fiber: Fiber
+```
+
+拥有此上下文的 fiber（插件运行时实例）。
+
+[源码](../../vendor/cordis/src/fiber.ts#L12)
+
+## Fiber 类
+
+单次插件应用的运行时实例。
+
+fiber 会跟踪 `ctx.plugin()` 返回的插件上下文所对应的依赖状态、经过校验的配置、生命周期作用和清理操作。
+
+[源码](../../vendor/cordis/src/fiber.ts#L184)
+
+### fiber.uid
+
+```ts cordis-catalog
+/** Unique id within the registry; 0 for the root fiber, `null` once disposed. */
+public uid: number | null
+```
+
+在注册表中的唯一 id；根 fiber 的 id 为 0，dispose 后为 `null`。
+
+[源码](../../vendor/cordis/src/fiber.ts#L186)
+
+### fiber.ctx
+
+```ts cordis-catalog
+/** The context this fiber's plugin runs in (extends the parent context). */
+public readonly ctx: Context
+```
+
+此 fiber 的插件运行所在的上下文（扩展自父上下文）。
+
+[源码](../../vendor/cordis/src/fiber.ts#L188)
+
+### fiber.config
+
+```ts cordis-catalog
+/** The validated plugin config (updated by `update()`). */
+public config: any
+```
+
+经过校验的插件配置（由 `update()` 更新）。
+
+[源码](../../vendor/cordis/src/fiber.ts#L190)
+
+### fiber.state
+
+```ts cordis-catalog
+/** Current lifecycle state; transitions emit `internal/status`. */
+public state
+```
+
+当前生命周期状态；状态转换会发出 `internal/status`。
+
+[源码](../../vendor/cordis/src/fiber.ts#L192)
+
+### fiber.dispose
+
+```ts cordis-catalog
+/** Dispose this fiber: unload the plugin, then settle once cleanup finished. */
+public readonly dispose: () => Promise<void>
+```
+
+dispose 此 fiber：卸载插件，并在清理完成后结算。
+
+[源码](../../vendor/cordis/src/fiber.ts#L194)
+
+### fiber.store
+
+```ts cordis-catalog
+/** Snapshot of required service implementations while loaded; `undefined` otherwise. */
+public store: Dict<Impl> | undefined
+```
+
+加载期间所需服务实现的快照；其他情况下为 `undefined`。
+
+[源码](../../vendor/cordis/src/fiber.ts#L196)
+
+### fiber.inertia
+
+```ts cordis-catalog
+/** The in-flight load/unload transition, if one is currently running. */
+public inertia: Promise<void> | undefined
+```
+
+当前正在进行的加载或卸载转换；如果没有此类转换，则为 `undefined`。
+
+[源码](../../vendor/cordis/src/fiber.ts#L198)
+
+### fiber.name
+
+```ts cordis-catalog
+/** The plugin's display name, inherited from the nearest named ancestor, else `'root'`. */
+get name()
+```
+
+插件的显示名称，继承自最近的具名祖先；如果不存在，则为 `'root'`。
+
+[源码](../../vendor/cordis/src/fiber.ts#L341)
+
+### fiber.assertActive()
+
+```ts cordis-catalog
+/**
+ * Throw if the fiber has already been disposed.
+ *
+ * @returns nothing when the fiber is still active.
+ * @throws {CordisError} `INACTIVE_EFFECT` when the fiber's uid has been cleared.
+ */
+assertActive()
+```
+
+如果 fiber 已经 dispose，则抛出异常。
+
+**返回**：fiber 仍处于活动状态时不返回任何内容。
+
+[源码](../../vendor/cordis/src/fiber.ts#L356)
+
+### fiber.effect(execute, label?)
+
+```ts cordis-catalog
+/**
+ * Register a cleanup-aware effect on this fiber.
+ *
+ * `execute` runs immediately; the disposers it produces are collected and
+ * run (in reverse order) either when the returned disposer is called or
+ * when the fiber unloads, whichever comes first. Calling the disposer twice
+ * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
+ * already disposed, and `TypeError` if `execute` returns an invalid shape.
+ *
+ * @param execute — the effect body; see {@link Effect} for accepted shapes.
+ * @param label — effect label shown in `getEffects()` diagnostics.
+ * @returns a disposer that tears the effect down and settles once done.
+ */
+effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
+effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
+```
+
+在此 fiber 上注册一个支持清理的作用。
+
+`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose，则抛出 `CordisError('INACTIVE_EFFECT')`；如果 `execute` 返回的结构无效，则抛出 `TypeError`。
+
+- `execute`：作用主体；可接受的结构见 `Effect`。
+- `label`：在 `getEffects()` 诊断信息中显示的作用标签。
+
+**返回**一个用于撤销该作用的清理函数，并在清理完成后结算。
+
+[源码](../../vendor/cordis/src/fiber.ts#L420)
+
+### fiber.getEffects()
+
+```ts cordis-catalog
+/**
+ * Return metadata for currently registered effects.
+ *
+ * @returns one {@link EffectMeta} tree per labeled live effect.
+ */
+getEffects()
+```
+
+返回当前已注册作用的元数据。
+
+**返回**：每个带标签的活动作用对应一棵 `EffectMeta` 树。
+
+[源码](../../vendor/cordis/src/fiber.ts#L573)
+
+### fiber.await()
+
+```ts cordis-catalog
+/**
+ * Wait for current lifecycle work and rethrow startup errors.
+ *
+ * @returns this fiber, once it has settled into a stable state.
+ * @throws the config-validation or plugin-startup error, if any.
+ */
+async await()
+```
+
+等待当前生命周期工作完成，并重新抛出启动错误。
+
+**返回**：进入稳定状态后的此 fiber。
+
+[源码](../../vendor/cordis/src/fiber.ts#L702)
+
+### fiber.restart()
+
+```ts cordis-catalog
+/**
+ * Dispose and immediately reload this plugin with its current config.
+ *
+ * @returns a promise resolving once the reload settled.
+ * @throws {CordisError} `INACTIVE_EFFECT` when the fiber is already disposed.
+ */
+async restart()
+```
+
+dispose 此插件，并立即使用其当前配置重新加载。
+
+**返回**一个在重新加载完成后兑现的 promise。
+
+[源码](../../vendor/cordis/src/fiber.ts#L716)
+
+### fiber.update(config, noSave?)
+
+```ts cordis-catalog
+/**
+ * Validate and apply new config, then restart the plugin.
+ *
+ * Runs the `internal/update` waterfall first, so update hooks (and HMR)
+ * can veto or replace the restart.
+ *
+ * @param config — the new raw config; validated before anything restarts.
+ * @param noSave — hint for persistence hooks not to write the change back.
+ * @returns the update waterfall result; the default restart returns a promise.
+ * @throws when validation, an update listener, or the restarted plugin fails.
+ */
+update(config: any, noSave = false)
+```
+
+校验并应用新配置，然后重新启动插件。
+
+首先运行 `internal/update` waterfall（瀑布式事件），因此更新钩子（以及 HMR（热模块替换））可以否决或取代重新启动操作。
+
+- `config`：新的原始配置；在任何内容重新启动前进行校验。
+- `noSave`：提示持久化钩子不要写回此变更。
+
+**返回**更新 waterfall 的结果；默认的重新启动操作返回一个 promise。
+
+[源码](../../vendor/cordis/src/fiber.ts#L734)
+
+## Effect
+
+`ctx.effect()` 和插件启动所接受的作用主体结果。
+
+可以是单个清理函数、兑现为清理函数的 promise，或生成多个清理函数的（可能为异步的）可迭代对象。生成器作用会在每个清理函数产生时将其注册。
+
+```ts cordis-catalog
+/**
+ * Effect body result accepted by `ctx.effect()` and plugin startup.
+ *
+ * Either a single disposer, a promise of one, or a (possibly async) iterable
+ * yielding several — generator effects register each yielded disposer as it
+ * is produced.
+ */
+type Effect<T = any> =
+  | SyncEffect<T>
+  | AsyncEffect<T>
+```
+
+[源码](../../vendor/cordis/src/fiber.ts#L83)
+
+## Disposable
+
+作用返回的函数，用于在资源释放期间释放资源。
+
+拥有该函数的 fiber 卸载时，清理函数会按注册的相反顺序运行；清理函数可以是异步的，此时卸载过程会等待其完成。
+
+```ts cordis-catalog
+/**
+ * Function returned by an effect to release resources during disposal.
+ *
+ * Disposers run in reverse registration order when the owning fiber unloads;
+ * they may be async, in which case unloading awaits them.
+ */
+type Disposable<T = any> = () => T
+```
+
+[源码](../../vendor/cordis/src/fiber.ts#L74)
+
+## EffectMeta
+
+用于在诊断信息中公开嵌套作用标签的树节点。
+
+```ts cordis-catalog
+/** Tree node used to expose nested effect labels for diagnostics. */
+interface EffectMeta {
+  /** Human-readable effect label, e.g. `ctx.on("event")` or `ctx.provide("name")`. */
+  label: string
+  /** Metadata of nested effects registered while this effect ran. */
+  children: EffectMeta[]
+}
+```
+
+[源码](../../vendor/cordis/src/fiber.ts#L96)
+
+## CordisError
+
+具有稳定机器可读错误码的框架错误。
+
+```ts cordis-catalog
+/** Framework error with a stable machine-readable code. */
+class CordisError extends Error {
+  /**
+   * @param code — the stable error code; also the default message.
+   * @param message — optional human-readable override.
+   */
+  constructor(public code: CordisError.Code, message?: string)
+}
+
+/** Cordis error code definitions. */
+namespace CordisError {
+  export type Code = keyof typeof Code
+
+  export const Code = {
+    INACTIVE_EFFECT: 'cannot create effect on inactive context',
+  } as const
+}
+```
+
+[源码](../../vendor/cordis/src/fiber.ts#L157)
+
+## ValidationError
+
+插件配置未通过 standard-schema 校验时抛出的错误。
+
+```ts cordis-catalog
+/** Error raised when plugin configuration fails standard-schema validation. */
+class ValidationError extends TypeError {
+  name = 'ValidationError'
+
+  /**
+   * Build the aggregated message from schema issues.
+   *
+   * @param issues — the standard-schema issues, one message line each.
+   */
+  constructor(issues: readonly StandardSchemaV1.Issue[])
+}
+```
+
+[源码](../../vendor/cordis/src/fiber.ts#L19)
diff --git a/docs/cordis-api/registry.i18n.yaml b/docs/cordis-api/registry.i18n.yaml
new file mode 100644
index 0000000000..31cafb4ace
--- /dev/null
+++ b/docs/cordis-api/registry.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 docs/cordis-api/registry.md
+registry.md: e6ddce5700ab071c2a4fedae19d99e2cb6e994ec
+registry.zh.md: c10509f569adfe65b4dbee4ca5b7139085dce1f7
diff --git a/docs/cordis-api/registry.zh.md b/docs/cordis-api/registry.zh.md
new file mode 100644
index 0000000000..c10509f569
--- /dev/null
+++ b/docs/cordis-api/registry.zh.md
@@ -0,0 +1,154 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/registry.md` 重新记录配对。 -->
+
+# 注册表
+
+[English](registry.md) | 中文
+
+插件加载与依赖注入。
+
+### ctx.inject(deps, callback)
+
+```ts cordis-catalog
+/**
+ * Run a callback once the requested services are available.
+ *
+ * Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback
+ * is unloaded and re-run whenever a required service changes.
+ *
+ * @param deps — required services, as an array or a name → config map.
+ * @param callback — plugin body called with `(ctx, config)`.
+ * @returns the fiber; awaiting it settles once loading finished.
+ */
+inject(deps: Inject, callback: Plugin.Function<void>): Fiber & PromiseLike<Fiber>
+```
+
+当请求的服务可用后，运行一次回调。
+
+这是 `ctx.plugin({ inject, apply: callback })` 的简写形式：每当某个必需服务发生变化时，系统都会卸载并重新运行该回调。
+
+- `deps`：必需服务，形式可以是数组，也可以是从名称到配置的映射。
+- `callback`：以 `(ctx, config)` 调用的插件主体。
+
+**返回** fiber；对其执行 await 会在加载完成后结束等待。
+
+[源码](../../vendor/cordis/src/registry.ts#L176)
+
+### ctx.plugin(plugin, ...args)
+
+```ts cordis-catalog
+/**
+ * Load a plugin in the current context.
+ *
+ * @param plugin — a function, class, or `{ apply }` object plugin.
+ * @param args — the plugin config, validated against its `Config` schema.
+ * @returns the fiber; awaiting it settles once loading finished
+ * (rejecting on config or startup errors).
+ */
+plugin<P extends Plugin>(plugin: P, ...args: Spread<GetPluginConfig<P>>): Fiber & PromiseLike<Fiber>
+```
+
+在当前上下文中加载插件。
+
+- `plugin`：函数、类或 `{ apply }` 对象形式的插件。
+- `args`：插件配置，会根据其 `Config` schema 进行校验。
+
+**返回** fiber；对其执行 await 会在加载完成后结束等待（如果发生配置错误或启动错误，则会被拒绝）。
+
+[源码](../../vendor/cordis/src/registry.ts#L185)
+
+## Plugin
+
+支持的插件入口点形式。
+
+```ts cordis-catalog
+/** Supported plugin entrypoint shapes. */
+type Plugin<T = any> =
+  | Plugin.Function<T>
+  | Plugin.Constructor<T>
+  | Plugin.Object<T>
+
+/** Types associated with plugin entrypoints and runtime records. */
+namespace Plugin {
+  /** Shared metadata understood by the plugin registry and related tooling. */
+  export interface Base<T = any> {
+    /** Display name used for fiber diagnostics and logger names. */
+    name?: string
+    /** Standard-schema validator applied to config before the plugin starts. */
+    Config?: StandardSchemaV1<any, T>
+    /** Services the plugin requires; it only loads while all are available. */
+    inject?: Inject
+    /** Service name(s) the plugin provides (read by `Service` and by loaders). */
+    provide?: string | string[]
+    /** Service names whose intercept config the plugin declares it consumes. */
+    intercept?: Dict<boolean>
+  }
+
+  export interface Transform<S, T> {
+    /** Marks the transform object as a schema/config transform. */
+    schema?: true
+    /** Convert user-facing config to runtime config. */
+    Config: (config: S) => T
+  }
+
+  /** Function plugin called with `(ctx, config)`. */
+  export interface Function<T = any> extends Base<T> {
+    (ctx: Context, config: T): any
+  }
+
+  /** Class plugin constructed with `(ctx, config)`. */
+  export interface Constructor<T = any> extends Base<T> {
+    new (ctx: Context, config: T): any
+  }
+
+  /** Object plugin with an `apply(ctx, config)` method. */
+  export interface Object<T = any> extends Base<T> {
+    apply(ctx: Context, config: T): any
+  }
+
+  /** Mutable registry record shared by all fibers of one plugin callback. */
+  export interface Runtime {
+    /** Display name copied from the first registered plugin shape. */
+    name?: string
+    /** Every live fiber of this plugin (one per `ctx.plugin()` call). */
+    fibers: DisposableList<Fiber>
+    /** The executable entrypoint all fibers share (registry identity key). */
+    callback: globalThis.Function
+    /** Standard-schema validator applied to each fiber's config. */
+    Config?: StandardSchemaV1
+  }
+}
+```
+
+[源码](../../vendor/cordis/src/registry.ts#L92)
+
+## Inject
+
+插件和 `@Inject` 装饰器接受的服务依赖声明。
+
+数组形式请求不带拦截配置的服务。对象形式将每个服务名称映射到插件上下文中可选的拦截配置。
+
+```ts cordis-catalog
+/**
+ * Service dependency declaration accepted by plugins and the `@Inject`
+ * decorator.
+ *
+ * Array form requests services without intercept config. Object form maps each
+ * service name to optional intercept config for the plugin context.
+ */
+type Inject<M = Dict> = (keyof M)[] | { [K in keyof M]?: M[K] }
+
+/** Utilities for normalizing plugin dependency declarations. */
+namespace Inject {
+  /**
+   * Convert array/object/class-inherited inject metadata into a plain map.
+   *
+   * @param inject — the declaration to normalize; `null`/`undefined` add nothing.
+   * @param result — the map to fill (service name → intercept config or `null`).
+   * @returns `result`.
+   */
+  export function resolve(inject: Inject | null | undefined, result: Dict = Object.create(null))
+}
+```
+
+[源码](../../vendor/cordis/src/registry.ts#L19)
diff --git a/docs/cordis-api/service.i18n.yaml b/docs/cordis-api/service.i18n.yaml
new file mode 100644
index 0000000000..7779d5fef6
--- /dev/null
+++ b/docs/cordis-api/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 docs/cordis-api/service.md
+service.md: d4b0f06da16decf31e0d348a88e0360b46ee9d35
+service.zh.md: ec0b443a0eae2787e0a3db919583d8092414c52d
diff --git a/docs/cordis-api/service.zh.md b/docs/cordis-api/service.zh.md
new file mode 100644
index 0000000000..ec0b443a0e
--- /dev/null
+++ b/docs/cordis-api/service.zh.md
@@ -0,0 +1,104 @@
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/service.md` 重新记录配对。 -->
+
+# Service
+
+[English](service.md) | 中文
+
+上下文服务的基类。以插件形式加载的子类会将自身注册为 `ctx.<name>`。
+
+用于在 `ctx` 上公开具名 API 的服务基类。
+
+子类在构造函数中调用 `super(ctx, name)`。服务会立即注册，并随所属 fiber 自动移除。
+
+[源码](../../vendor/cordis/src/service.ts#L11)
+
+### service.name
+
+```ts cordis-catalog
+/** The service name this instance is registered under. */
+public name!: string
+```
+
+此实例注册时使用的服务名称。
+
+[源码](../../vendor/cordis/src/service.ts#L30)
+
+## 静态成员
+
+### Service.init
+
+```ts cordis-catalog
+/** Symbol key of an instance method run after construction (class plugins). */
+static readonly init: unique symbol
+```
+
+构造完成后运行的实例方法所使用的符号键（类插件）。
+
+[源码](../../vendor/cordis/src/service.ts#L13)
+
+### Service.check
+
+```ts cordis-catalog
+/** Symbol key of the availability predicate passed to `ctx.provide()`. */
+static readonly check: unique symbol
+```
+
+传给 `ctx.provide()` 的可用性谓词所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L15)
+
+### Service.config
+
+```ts cordis-catalog
+/** Symbol key of the phantom intercept-config type parameter. */
+static readonly config: unique symbol
+```
+
+虚设拦截配置类型参数所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L17)
+
+### Service.invoke
+
+```ts cordis-catalog
+/** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
+static readonly invoke: unique symbol
+```
+
+使服务可被调用的调用体所使用的符号键（例如 `ctx.logger()`）。
+
+[源码](../../vendor/cordis/src/service.ts#L19)
+
+### Service.extend
+
+```ts cordis-catalog
+/** Symbol key of the helper deriving an extended service instance. */
+static readonly extend: unique symbol
+```
+
+用于派生扩展服务实例的辅助方法所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L21)
+
+### Service.tracker
+
+```ts cordis-catalog
+/** Symbol key of the tracker metadata used for context tracing. */
+static readonly tracker: unique symbol
+```
+
+上下文追踪所用跟踪器元数据的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L23)
+
+### Service.resolveConfig
+
+```ts cordis-catalog
+/** Symbol key of the intercept-config resolution helper below. */
+static readonly resolveConfig: unique symbol
+```
+
+下述拦截配置解析辅助方法所使用的符号键。
+
+[源码](../../vendor/cordis/src/service.ts#L25)
diff --git a/docs/cordis-tutorial/01-first-plugin.i18n.yaml b/docs/cordis-tutorial/01-first-plugin.i18n.yaml
index 29e0266689..1fe3585ba1 100644
--- a/docs/cordis-tutorial/01-first-plugin.i18n.yaml
+++ b/docs/cordis-tutorial/01-first-plugin.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/01-first-plugin.md
 01-first-plugin.md: 4359dfe4883f12e9cb242cf3009827fd7864768c
-01-first-plugin.zh.md: 62ccb7e5d37beb5b9636439e563cea6eaa1044a0
+01-first-plugin.zh.md: 9965f4ddb75fa338ba7fd9d564bd4a32fced7b93
diff --git a/docs/cordis-tutorial/01-first-plugin.zh.md b/docs/cordis-tutorial/01-first-plugin.zh.md
index 62ccb7e5d3..9965f4ddb7 100644
--- a/docs/cordis-tutorial/01-first-plugin.zh.md
+++ b/docs/cordis-tutorial/01-first-plugin.zh.md
@@ -28,7 +28,7 @@ export function apply(ctx: Context) {
 - name: './hello.ts'
 ```
 
-该文件是一组 Cordis 配置项的列表。`name` 是模块指定符，可以是相对路径或 NPM 包（package）名；loader 会挂载每个配置项。各项会并发启动，因此它们在列表中的位置不保证插件的加载先后；顺序由服务依赖（`inject`，参见[第 3 章](03-services.md)）决定，而非文件中的位置。
+该文件是一组 Cordis 配置项的列表。`name` 是模块指定符，可以是相对路径或 NPM 包名；loader 会挂载每个配置项。各项会并发启动，因此它们在列表中的位置不保证插件的加载先后；顺序由服务依赖（`inject`，参见[第 3 章](03-services.md)）决定，而非文件中的位置。
 
 ## 运行
 
@@ -86,7 +86,7 @@ export function apply(ctx: Context) {
 }
 ```
 
-再次运行：进程会因该错误而终止。插件加载失败必须明确报错，不会仅跳过该配置项。
+再次运行：进程会因该错误而终止。插件加载失败会明确报错，不会仅跳过该配置项。
 
 还需要尽早了解一个例外：如果某个配置项的模块无法被 **解析**，例如路径或包名拼写错误，Cordis 会通过 logger 服务报告错误，而不会使进程崩溃。在启动阶段，这条报告可能在 console 导出器开始观察之前丢失。如果新增配置项似乎没有任何效果，请先检查拼写。
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 00673a9415..d6d5d3dcc3 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
 development.md: f7084403b30e8a6d12c4ef2b886f8fb61ed39b26
-development.zh.md: 9d3606cf741f25318c630e08e8ac84ad5ee8d345
+development.zh.md: 60a4660f5d6be48fd4d0d8f30777ae37495d6296
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 9d3606cf74..60a4660f5d 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -43,21 +43,21 @@ pnpm run typecheck
 
 ### TypeScript 项目布局
 
-仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。
+仓库使用相互隔离的 Host 与 Client aggregate。普通包只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。
 
 | 文件 | 角色 | 是否构成 program？ |
 |---|---|---|
 | `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |
-| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |
-| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |
+| `tsconfig.host.json` | Host aggregate：Host 包、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |
+| `tsconfig.client.json` | Client aggregate：`packages/client/*` 包及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |
 | `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |
-| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |
+| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` 包 extends。 | 否 |
 
 Host 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：
 
 - `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。
 - 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。
-- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。
+- 新包只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client 插件的两份运行时产物都在 Client 构建阶段生成。
 
 `api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。
 
@@ -71,13 +71,13 @@ tsdown --env.DSH_BUILD_FACE client
 pnpm run build:web
 ```
 
-两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。
+两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client 包，也不维护 Host/Client 包过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client 插件在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。
 
-TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
+TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 契约产物生成构建 Agent Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
 
-静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
+静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约产物生成 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Agent Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Agent Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
 
-业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
+业务服务在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
 
 如果相关的本地检查需要使用构建后的包产物，请先构建一次：
 
@@ -85,7 +85,7 @@ TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分
 pnpm run build
 ```
 
-`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。
+`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验包入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。
 
 ### 环境变量
 
@@ -108,7 +108,7 @@ lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
 - `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
 - `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；
-- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
+- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约产物生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
 
@@ -122,7 +122,7 @@ keyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若
 
 ### 日常命令
 
-根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。
+根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；包的公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。
 
 ### 演示
 
@@ -156,10 +156,10 @@ pnpm run demo:acp
 
 ### 逐字记录类型（`ts type-equiv`）
 
-[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
 { "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
-`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。
+`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
new file mode 100644
index 0000000000..ee00d76a88
--- /dev/null
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
+event-producer-consumer.md: f5ea3eba36f46b87d9a8f5fc9537c40622da8cc9
+event-producer-consumer.zh.md: e2bb889d5a4319fc31c1ed0b3e06b68e320081f5
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
new file mode 100644
index 0000000000..e2bb889d5a
--- /dev/null
+++ b/docs/event-producer-consumer.zh.md
@@ -0,0 +1,83 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/event-producer-consumer.md` 重新记录配对。 -->
+
+# 事件生产方与消费方矩阵
+
+[English](event-producer-consumer.md) | 中文
+
+本矩阵展示哪些包会派发各个 harness 自有事件，以及哪些包会监听这些事件。这里特意采用表格而非一张大型关系图：事件之间存在多对多关系，以表格逐行呈现密集的关系数据更便于评审。接收方和事件名称类型还涵盖有意绕过 `ctx.emit` 的内含派发位置，例如 subagent 生命周期封装。
+
+| 事件 | 模式 | 声明位置 | 派发方 | 监听方 |
+| --- | --- | --- | --- | --- |
+| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
+| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:185`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
+| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), `server` |
+| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
+| `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
+| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:64`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:73`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
+| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:56`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
+| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/support/loader-smoke), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workspace-context`](../packages/context/workspace-context) |
+| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
+| `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
+| `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
+| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:283`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), `server`, [`subagent`](../packages/subagent/subagent) |
+| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:136`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
+| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
+| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
+| `telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
+| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
+| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:173`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
+| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:160`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:137`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
+| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
+| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:81`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
+| `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
+| `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:91`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
+| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:60`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
+| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:53`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
+| `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:45`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
+
+## 包源码中出现的非 harness 或未声明事件字符串
+
+| 事件字符串 | 派发方 | 监听方 |
+| --- | --- | --- |
+| `commands/changed` | `runtime` (`emit`) | `ui-command` |
+| `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-permission`, `ui-settings-general` |
+| `credentials/changed` | `runtime` (`emit`) | `ui-models` |
+| `internal/dispatch` | - | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workflow`](../packages/workflow/workflow) |
+| `internal/plugin` | - | `hmr`, `loader`, [`lsp-local`](../packages/lsp/lsp-local), `modules`, `webserver` |
+| `internal/service` | - | `gateway` |
+| `internal/status` | - | [`agent`](../packages/core/agent) |
+| `locale/change` | `locale` (`emit`) | `locale` |
+| `models/changed` | `runtime` (`emit`) | `ui-models` |
+| `settings/changed` | `runtime` (`emit`) | `ui-models`, `ui-permission`, `ui-settings-general` |
+| `slash/input-begin-command` | - | `ui-conversation` |
+| `slash/input-consume-token` | - | `ui-conversation` |
+| `slash/input-insert-reference` | - | `ui-conversation` |
+| `slash/input-insert-text` | - | `ui-conversation` |
+| `slots/changed` | `runtime` (`emit`) | - |
+| `theme/change` | `ui-theme` (`emit`) | `ui-layout`, `ui-theme` |
+
+维护模式：英文源文件是生成内容，Cordis 事件声明及生产方／监听方的关系边由仓库的 TypeScript Program 解析；本中文文件作为经评审对侧通过双语配对维护。
diff --git a/docs/graph-atlas.i18n.yaml b/docs/graph-atlas.i18n.yaml
new file mode 100644
index 0000000000..0cd73d4f39
--- /dev/null
+++ b/docs/graph-atlas.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 docs/graph-atlas.md
+graph-atlas.md: 5b831520fb4e1c5d49d83738ba979ce04ce4f69f
+graph-atlas.zh.md: 1f9a30124284549248bbb21f926772d5cdc2598a
diff --git a/docs/graph-atlas.zh.md b/docs/graph-atlas.zh.md
new file mode 100644
index 0000000000..1f9a301242
--- /dev/null
+++ b/docs/graph-atlas.zh.md
@@ -0,0 +1,26 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/graph-atlas.md` 重新记录配对。 -->
+
+# 文档图索引
+
+[English](graph-atlas.md) | 中文
+
+这些图构成生成目录之上的关系层。你可以借助它们了解包拓扑、能力 seam、事件流、面向模型的工具、应用组合以及运行时生命周期路径。精确签名和类型结构仍以[子系统页面](subsystems/core.md)（类型和生成的 `cordis-surface` 区域）及[工具目录](tool-catalog.md)为准。
+
+本索引背后的流程决策记录在[文档图 Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md)中。
+
+| 图 | 模式 |
+| --- | --- |
+| [模块依赖图](module-graph.md) | `generated` |
+| [工具 schema 目录与包映射](tool-catalog.md) | `generated` |
+| [能力 seam 与核心服务](capability-seams.md) | `hybrid generated` |
+| [dsh 共享基础组合](../apps/cli/composition.md) | `hybrid generated` |
+| [headless-agent 应用组合](../examples/headless-agent/composition.md) | `hybrid generated` |
+| [acp-agent 应用组合](../examples/acp-agent/composition.md) | `hybrid generated` |
+| [事件生产方／消费方矩阵](event-producer-consumer.md) | `hybrid generated` |
+| [agent（智能体）轮次与步骤生命周期](agent-lifecycle.md) | `curated` |
+| [工具执行流水线](tool-execution-pipeline.md) | `curated` |
+
+运行 `pnpm run gen-doc-graphs` 可重新生成英文源文件；运行 `pnpm run verify-doc-graphs` 可验证英文源的新鲜度，中文对侧则通过双语配对维护。
+
+英文源文件的维护模式为混合。每个链接页面都会声明其英文源模式为生成、混合或人工编写；本中文文件是通过双语配对维护的经评审对侧。
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index c62de565e7..c10cab36cb 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/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 docs/i18n/README.md
-README.md: 30f56eeebf15a3edec559e3080247dab9ab14178
-README.zh.md: 91d5b35a00994beea70f2bbd674cfb557d6f834d
+README.md: b6190e7dd84ae5f159fd452f093bf37f24edfda9
+README.zh.md: f1c808442efe3ca7da87c30ba22d3560bcf125e9
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index 30f56eeebf..b6190e7dd8 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -43,9 +43,11 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co
 
 **Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.
 
+Generated English references and graphs participate in pairing when a reviewed Chinese counterpart is available. Their generators remain the English source of truth and their freshness gates run before pairing; regeneration that changes English leaves the pair out of sync until the reviewed Chinese counterpart is updated and re-recorded. Generated English sources omit the language switcher that ordinary authored sources carry, because adding it would make the generator stale; their Chinese counterparts still link back to the English source.
+
 **Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):
 
-- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.
+- [cordis-api/inherited.md](../cordis-api/inherited.md) — generated without a reviewed Chinese counterpart, so both website locales project the English source.
 - `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.
 - `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.
 - [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index 91d5b35a00..f1c808442e 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
+本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
 
-## 配对契约
+## 配对约定
 
 - **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。
 - **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。
@@ -23,7 +23,7 @@
 
 ## 门禁：verify-translation-pairing
 
-`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：
+`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：
 
 1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。
 2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
@@ -37,15 +37,17 @@
 
 这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。
 
-把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
+把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
 
 ## 范围与排除
 
 **范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。
 
+有经评审中文对侧的生成英文参考文档和图文档遵循配对规则。生成器仍是英文真源，新鲜度门禁先于配对运行；重新生成导致英文变化后，配对会保持失去同步状态，直至经评审的中文对侧完成更新并重新记录。生成的英文源文件不含普通撰写文档所带的语言切换行，因为添加该行会使生成器报告陈旧；中文对侧仍链接回英文源。
+
 **排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：
 
-- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。
+- [cordis-api/inherited.md](../cordis-api/inherited.md)：该生成文档没有经评审的中文对侧，因此网站的两个 locale 都投影英文源文件。
 - `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。
 - `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。
 - [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。
@@ -55,4 +57,4 @@
 
 ## 分工
 
-这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
+这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 299f7db46f..846ade98b9 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -74,7 +74,7 @@
 | English | 中文 | 首次出现 | 不要译作 | 备注 |
 |---|---|---|---|---|
 | adapter | 适配器 | | | |
-| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | |
+| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |
 | append-only | 仅追加 | | | |
 | artifact | 产物 | | 制品 | |
 | backend | 后端 | | | |
@@ -101,7 +101,7 @@
 | counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指"另一侧"时可写「另一侧」 |
 | configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |
 | context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |
-| contract | 契约 | | | 如：`pairing contract` →`配对契约` |
+| contract | 约定 | | | 如：`pairing contract` →`配对约定` |
 | Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |
 | Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |
 | crash recovery | 崩溃恢复 | | | |
diff --git a/docs/i18n/translation-rules.i18n.yaml b/docs/i18n/translation-rules.i18n.yaml
index dea0883a4b..e8e4d8f801 100644
--- a/docs/i18n/translation-rules.i18n.yaml
+++ b/docs/i18n/translation-rules.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
+#   pnpm run verify-translation-pairing --write docs/i18n/translation-rules.md
 translation-rules.md: fb6aa9ac05bebe68ff9213af99f64457bdb1ad6f
 translation-rules.zh.md: 04dd0a704e19502c676ea0966437870c5af0624f
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
new file mode 100644
index 0000000000..212b107093
--- /dev/null
+++ b/docs/module-graph.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 docs/module-graph.md
+module-graph.md: 6f47c36e970009838e1ab921f4abe013eaeded5f
+module-graph.zh.md: 5da7bc962e1c38e3febfbca59e6bb11b014ecc7f
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
new file mode 100644
index 0000000000..5da7bc962e
--- /dev/null
+++ b/docs/module-graph.zh.md
@@ -0,0 +1,1370 @@
+<!-- 英文源文件由 scripts/gen-module-graph.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-module-graph` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/module-graph.md` 重新记录配对。 -->
+
+# 模块依赖关系图
+
+[English](module-graph.md) | 中文
+
+`@deepseek-ai/dsh-*` harness 包之间的依赖关系。该关系图根据各包的 `peerDependencies`（规范的运行时依赖信号）生成，并按 `packages/<group>/<pkg>` 层级分组。边 `a --> b` 表示包 `a` 依赖包 `b`。名称中的 `@deepseek-ai/dsh-` 前缀已移除。
+
+```mermaid
+flowchart TD
+  subgraph group_util["packages/util"]
+    pkg_atomic_write["atomic-write"]
+    pkg_brand["brand"]
+    pkg_environment["environment"]
+    pkg_native_command["native-command"]
+    pkg_paths["paths"]
+    pkg_retention["retention"]
+    pkg_timeout["timeout"]
+  end
+  subgraph group_llm["packages/llm"]
+    pkg_llm["llm"]
+    pkg_llm_deepseek["llm-deepseek"]
+    pkg_llm_pi_ai["llm-pi-ai"]
+    pkg_llm_retry["llm-retry"]
+    pkg_token_meter["token-meter"]
+  end
+  subgraph group_core["packages/core"]
+    pkg_agent["agent"]
+    pkg_agent_loop["agent-loop"]
+    pkg_scope["scope"]
+    pkg_session["session"]
+    pkg_system_prompt["system-prompt"]
+    pkg_tools["tools"]
+  end
+  subgraph group_goal["packages/goal"]
+    pkg_command_goal["command-goal"]
+    pkg_goal["goal"]
+    pkg_goal_session["goal-session"]
+    pkg_tool_goal["tool-goal"]
+  end
+  subgraph group_bash["packages/bash"]
+    pkg_bash["bash"]
+    pkg_bash_env["bash-env"]
+    pkg_bash_local["bash-local"]
+    pkg_bash_sandbox["bash-sandbox"]
+    pkg_pwsh_local["pwsh-local"]
+    pkg_tool_bash["tool-bash"]
+    pkg_tool_pwsh["tool-pwsh"]
+  end
+  subgraph group_fs["packages/fs"]
+    pkg_fs["fs"]
+    pkg_fs_local["fs-local"]
+    pkg_fs_policy["fs-policy"]
+    pkg_fs_sandbox["fs-sandbox"]
+    pkg_tool_fs["tool-fs"]
+    pkg_tool_fs_search["tool-fs-search"]
+    pkg_tool_str_replace_editor["tool-str-replace-editor"]
+  end
+  subgraph group_skill["packages/skill"]
+    pkg_skill["skill"]
+    pkg_skill_badge["skill-badge"]
+    pkg_skill_local["skill-local"]
+    pkg_tool_skill["tool-skill"]
+  end
+  subgraph group_compact["packages/compact"]
+    pkg_command_compact["command-compact"]
+    pkg_compact["compact"]
+    pkg_compact_basic["compact-basic"]
+    pkg_compact_tool_result_prune["compact-tool-result-prune"]
+  end
+  subgraph group_subagent["packages/subagent"]
+    pkg_subagent["subagent"]
+    pkg_subagent_acp["subagent-acp"]
+    pkg_subagent_claude_code["subagent-claude-code"]
+    pkg_subagent_codex["subagent-codex"]
+    pkg_subagent_dsh_sdk["subagent-dsh-sdk"]
+    pkg_subagent_fork["subagent-fork"]
+    pkg_subagent_inprocess["subagent-inprocess"]
+    pkg_subagent_spawn["subagent-spawn"]
+    pkg_tool_subagent["tool-subagent"]
+    pkg_tool_subagent_control["tool-subagent-control"]
+    pkg_tool_subagent_report["tool-subagent-report"]
+  end
+  subgraph group_web["packages/web"]
+    pkg_tool_web["tool-web"]
+    pkg_web["web"]
+    pkg_web_fetch_local["web-fetch-local"]
+    pkg_web_search_deepseek["web-search-deepseek"]
+    pkg_web_search_exa["web-search-exa"]
+    pkg_web_search_perplexity["web-search-perplexity"]
+  end
+  subgraph group_spill["packages/spill"]
+    pkg_spill["spill"]
+    pkg_spill_local["spill-local"]
+    pkg_spill_policy["spill-policy"]
+  end
+  subgraph group_todo["packages/todo"]
+    pkg_tool_todo["tool-todo"]
+  end
+  subgraph group_plan["packages/plan"]
+    pkg_plan_mode["plan-mode"]
+  end
+  subgraph group_hooks["packages/hooks"]
+    pkg_hook_protocol["hook-protocol"]
+    pkg_hooks_claude["hooks-claude"]
+    pkg_hooks_codex["hooks-codex"]
+  end
+  subgraph group_session_query["packages/session-query"]
+    pkg_session_query["session-query"]
+    pkg_session_query_sqlite["session-query-sqlite"]
+    pkg_tool_session_query["tool-session-query"]
+  end
+  subgraph group_support["packages/support"]
+    pkg_acp_snapshot["acp-snapshot"]
+    pkg_agent_loop_testkit["agent-loop-testkit"]
+    pkg_invariants["invariants"]
+    pkg_llm_mock_server["llm-mock-server"]
+    pkg_llm_replay["llm-replay"]
+    pkg_loader_smoke["loader-smoke"]
+  end
+  subgraph group_acp["packages/acp"]
+    pkg_acp["acp"]
+  end
+  subgraph group_api["packages/api"]
+    pkg_api_gateway["api-gateway"]
+    pkg_api_remotes["api-remotes"]
+  end
+  subgraph group_boot["packages/boot"]
+    pkg_app_boot["app-boot"]
+  end
+  subgraph group_bundle["packages/bundle"]
+    pkg_base["base"]
+    pkg_headless["headless"]
+    pkg_web_app["web-app"]
+  end
+  subgraph group_client["packages/client"]
+    pkg_client_connection["client-connection"]
+    pkg_client_hmr["client-hmr"]
+    pkg_client_locale["client-locale"]
+    pkg_client_modules["client-modules"]
+    pkg_client_runtime["client-runtime"]
+    pkg_client_schema_form["client-schema-form"]
+    pkg_client_test_runtime["client-test-runtime"]
+    pkg_client_ui_command["client-ui-command"]
+    pkg_client_ui_conversation["client-ui-conversation"]
+    pkg_client_ui_deliverables["client-ui-deliverables"]
+    pkg_client_ui_goal["client-ui-goal"]
+    pkg_client_ui_layout["client-ui-layout"]
+    pkg_client_ui_model["client-ui-model"]
+    pkg_client_ui_models["client-ui-models"]
+    pkg_client_ui_permission["client-ui-permission"]
+    pkg_client_ui_plan["client-ui-plan"]
+    pkg_client_ui_primitives["client-ui-primitives"]
+    pkg_client_ui_question["client-ui-question"]
+    pkg_client_ui_settings["client-ui-settings"]
+    pkg_client_ui_settings_general["client-ui-settings-general"]
+    pkg_client_ui_sidebar["client-ui-sidebar"]
+    pkg_client_ui_skill["client-ui-skill"]
+    pkg_client_ui_slash["client-ui-slash"]
+    pkg_client_ui_slots["client-ui-slots"]
+    pkg_client_ui_subagent["client-ui-subagent"]
+    pkg_client_ui_theme["client-ui-theme"]
+    pkg_client_ui_tool["client-ui-tool"]
+    pkg_client_ui_trajectory["client-ui-trajectory"]
+    pkg_client_ui_workspace["client-ui-workspace"]
+    pkg_client_web["client-web"]
+    pkg_client_web_react["client-web-react"]
+  end
+  subgraph group_code_runtime["packages/code-runtime"]
+    pkg_code_runtime["code-runtime"]
+    pkg_code_runtime_worker["code-runtime-worker"]
+  end
+  subgraph group_context["packages/context"]
+    pkg_session_reference["session-reference"]
+    pkg_time_context["time-context"]
+    pkg_tmux_context["tmux-context"]
+    pkg_workspace_context["workspace-context"]
+  end
+  subgraph group_credentials["packages/credentials"]
+    pkg_credentials["credentials"]
+    pkg_credentials_local["credentials-local"]
+  end
+  subgraph group_e2b["packages/e2b"]
+    pkg_e2b["e2b"]
+    pkg_fs_e2b["fs-e2b"]
+    pkg_subprocess_e2b["subprocess-e2b"]
+  end
+  subgraph group_examples["packages/examples"]
+    pkg_acp_demo["acp-demo"]
+    pkg_agent_spine_demo["agent-spine-demo"]
+    pkg_jsonrpc_demo["jsonrpc-demo"]
+  end
+  subgraph group_feedback["packages/feedback"]
+    pkg_command_feedback["command-feedback"]
+  end
+  subgraph group_guard["packages/guard"]
+    pkg_repeat_tool_guard["repeat-tool-guard"]
+    pkg_timeout_policy["timeout-policy"]
+  end
+  subgraph group_host["packages/host"]
+    pkg_frontend_static["frontend-static"]
+    pkg_host_apiproxy["host-apiproxy"]
+    pkg_host_directory_picker["host-directory-picker"]
+    pkg_host_directory_picker_auto["host-directory-picker-auto"]
+    pkg_host_directory_picker_browse["host-directory-picker-browse"]
+    pkg_host_directory_picker_native["host-directory-picker-native"]
+    pkg_host_webserver["host-webserver"]
+  end
+  subgraph group_interaction["packages/interaction"]
+    pkg_commands["commands"]
+    pkg_permission["permission"]
+    pkg_tool_ask_user["tool-ask-user"]
+    pkg_user_approval["user-approval"]
+    pkg_user_interaction["user-interaction"]
+  end
+  subgraph group_lsp["packages/lsp"]
+    pkg_lsp["lsp"]
+    pkg_lsp_local["lsp-local"]
+    pkg_tool_lsp["tool-lsp"]
+  end
+  subgraph group_mcp["packages/mcp"]
+    pkg_mcp_client["mcp-client"]
+  end
+  subgraph group_pty["packages/pty"]
+    pkg_pty["pty"]
+    pkg_pty_local["pty-local"]
+    pkg_tool_bash_persistent["tool-bash-persistent"]
+    pkg_tool_pty["tool-pty"]
+  end
+  subgraph group_sandbox["packages/sandbox"]
+    pkg_sandbox["sandbox"]
+    pkg_sandbox_local["sandbox-local"]
+    pkg_sandbox_policy["sandbox-policy"]
+  end
+  subgraph group_scaffold["packages/scaffold"]
+    pkg_helper["helper"]
+    pkg_jsonrpc["jsonrpc"]
+    pkg_scripts["scripts"]
+    pkg_sdk_client["sdk-client"]
+    pkg_sdk_protocol["sdk-protocol"]
+    pkg_telemetry["telemetry"]
+  end
+  subgraph group_self_modification["packages/self-modification"]
+    pkg_repository_plugin["repository-plugin"]
+    pkg_tool_cordis["tool-cordis"]
+  end
+  subgraph group_session["packages/session"]
+    pkg_session_checkpoint_policy["session-checkpoint-policy"]
+    pkg_session_persistence["session-persistence"]
+    pkg_session_persistence_jsonl["session-persistence-jsonl"]
+    pkg_session_persistence_sqlite["session-persistence-sqlite"]
+    pkg_session_projection["session-projection"]
+    pkg_session_projection_cache["session-projection-cache"]
+    pkg_session_telemetry["session-telemetry"]
+    pkg_session_telemetry_otel["session-telemetry-otel"]
+    pkg_session_title["session-title"]
+    pkg_session_title_all_messages_llm["session-title-all-messages-llm"]
+    pkg_session_title_first_message_llm["session-title-first-message-llm"]
+    pkg_session_title_llm["session-title-llm"]
+  end
+  subgraph group_settings["packages/settings"]
+    pkg_settings["settings"]
+    pkg_settings_local["settings-local"]
+  end
+  subgraph group_storage["packages/storage"]
+    pkg_storage["storage"]
+    pkg_storage_domain["storage-domain"]
+    pkg_storage_json["storage-json"]
+    pkg_storage_sqlite["storage-sqlite"]
+  end
+  subgraph group_subprocess["packages/subprocess"]
+    pkg_subprocess["subprocess"]
+    pkg_subprocess_local["subprocess-local"]
+  end
+  subgraph group_tasks["packages/tasks"]
+    pkg_tasks["tasks"]
+    pkg_tasks_local["tasks-local"]
+    pkg_tool_tasks["tool-tasks"]
+  end
+  subgraph group_typert["packages/typert"]
+    pkg_type_meta["type-meta"]
+    pkg_typert_generator["typert-generator"]
+    pkg_typert_loader["typert-loader"]
+    pkg_typert_registry["typert-registry"]
+  end
+  subgraph group_workflow["packages/workflow"]
+    pkg_tool_ralph["tool-ralph"]
+    pkg_tool_workflow["tool-workflow"]
+    pkg_workflow["workflow"]
+    pkg_workflow_workerthread["workflow-workerthread"]
+  end
+  subgraph group_workspace["packages/workspace"]
+    pkg_workspace["workspace"]
+  end
+  pkg_atomic_write --> pkg_invariants
+  pkg_brand --> pkg_invariants
+  pkg_environment --> pkg_invariants
+  pkg_native_command --> pkg_invariants
+  pkg_paths --> pkg_invariants
+  pkg_retention --> pkg_invariants
+  pkg_timeout --> pkg_invariants
+  pkg_scope --> pkg_invariants
+  pkg_llm_mock_server --> pkg_invariants
+  pkg_base --> pkg_invariants
+  pkg_client_modules --> pkg_invariants
+  pkg_client_schema_form --> pkg_invariants
+  pkg_client_ui_primitives --> pkg_invariants
+  pkg_client_ui_slots --> pkg_invariants
+  pkg_client_web --> pkg_invariants
+  pkg_client_web_react --> pkg_invariants
+  pkg_code_runtime --> pkg_invariants
+  pkg_e2b --> pkg_invariants
+  pkg_jsonrpc_demo --> pkg_invariants
+  pkg_host_apiproxy --> pkg_invariants
+  pkg_host_directory_picker --> pkg_invariants
+  pkg_host_webserver --> pkg_invariants
+  pkg_storage --> pkg_invariants
+  pkg_subprocess --> pkg_invariants
+  pkg_type_meta --> pkg_invariants
+  pkg_typert_generator --> pkg_invariants
+  pkg_typert_registry --> pkg_invariants
+  pkg_llm --> pkg_brand
+  pkg_llm --> pkg_invariants
+  pkg_llm --> pkg_timeout
+  pkg_client_connection --> pkg_host_webserver
+  pkg_client_connection --> pkg_invariants
+  pkg_client_hmr --> pkg_client_modules
+  pkg_client_hmr --> pkg_host_webserver
+  pkg_client_hmr --> pkg_invariants
+  pkg_client_runtime --> pkg_invariants
+  pkg_client_runtime --> pkg_type_meta
+  pkg_client_runtime --> pkg_typert_registry
+  pkg_credentials --> pkg_brand
+  pkg_credentials --> pkg_invariants
+  pkg_subprocess_e2b --> pkg_e2b
+  pkg_subprocess_e2b --> pkg_invariants
+  pkg_subprocess_e2b --> pkg_subprocess
+  pkg_subprocess_e2b --> pkg_timeout
+  pkg_frontend_static --> pkg_host_webserver
+  pkg_frontend_static --> pkg_invariants
+  pkg_helper --> pkg_brand
+  pkg_helper --> pkg_invariants
+  pkg_helper --> pkg_subprocess
+  pkg_telemetry --> pkg_brand
+  pkg_telemetry --> pkg_invariants
+  pkg_telemetry --> pkg_paths
+  pkg_settings --> pkg_brand
+  pkg_settings --> pkg_invariants
+  pkg_storage_domain --> pkg_invariants
+  pkg_storage_domain --> pkg_storage
+  pkg_storage_json --> pkg_invariants
+  pkg_storage_json --> pkg_storage
+  pkg_storage_sqlite --> pkg_invariants
+  pkg_storage_sqlite --> pkg_storage
+  pkg_subprocess_local --> pkg_invariants
+  pkg_subprocess_local --> pkg_subprocess
+  pkg_subprocess_local --> pkg_timeout
+  pkg_typert_loader --> pkg_invariants
+  pkg_typert_loader --> pkg_typert_registry
+  pkg_llm_deepseek --> pkg_credentials
+  pkg_llm_deepseek --> pkg_environment
+  pkg_llm_deepseek --> pkg_invariants
+  pkg_llm_deepseek --> pkg_llm
+  pkg_llm_deepseek --> pkg_settings
+  pkg_llm_deepseek --> pkg_timeout
+  pkg_llm_pi_ai --> pkg_credentials
+  pkg_llm_pi_ai --> pkg_environment
+  pkg_llm_pi_ai --> pkg_invariants
+  pkg_llm_pi_ai --> pkg_llm
+  pkg_llm_pi_ai --> pkg_settings
+  pkg_llm_pi_ai --> pkg_timeout
+  pkg_session --> pkg_brand
+  pkg_session --> pkg_invariants
+  pkg_session --> pkg_llm
+  pkg_session --> pkg_scope
+  pkg_session --> pkg_type_meta
+  pkg_system_prompt --> pkg_invariants
+  pkg_system_prompt --> pkg_llm
+  pkg_system_prompt --> pkg_scope
+  pkg_skill --> pkg_invariants
+  pkg_skill --> pkg_llm
+  pkg_web --> pkg_invariants
+  pkg_web --> pkg_llm
+  pkg_api_gateway --> pkg_client_connection
+  pkg_api_gateway --> pkg_invariants
+  pkg_api_gateway --> pkg_typert_registry
+  pkg_client_locale --> pkg_client_runtime
+  pkg_client_locale --> pkg_client_ui_primitives
+  pkg_client_locale --> pkg_client_ui_slots
+  pkg_client_locale --> pkg_invariants
+  pkg_client_test_runtime --> pkg_client_runtime
+  pkg_client_test_runtime --> pkg_client_ui_slots
+  pkg_client_test_runtime --> pkg_client_web_react
+  pkg_client_test_runtime --> pkg_host_apiproxy
+  pkg_client_test_runtime --> pkg_invariants
+  pkg_client_ui_models --> pkg_client_connection
+  pkg_client_ui_models --> pkg_client_runtime
+  pkg_client_ui_models --> pkg_client_schema_form
+  pkg_client_ui_models --> pkg_client_ui_primitives
+  pkg_client_ui_models --> pkg_client_ui_slots
+  pkg_client_ui_models --> pkg_client_web_react
+  pkg_client_ui_models --> pkg_invariants
+  pkg_client_ui_settings --> pkg_client_runtime
+  pkg_client_ui_settings --> pkg_client_ui_primitives
+  pkg_client_ui_settings --> pkg_client_ui_slots
+  pkg_client_ui_settings --> pkg_invariants
+  pkg_client_ui_trajectory --> pkg_client_runtime
+  pkg_client_ui_trajectory --> pkg_client_ui_primitives
+  pkg_client_ui_trajectory --> pkg_invariants
+  pkg_credentials_local --> pkg_atomic_write
+  pkg_credentials_local --> pkg_credentials
+  pkg_credentials_local --> pkg_environment
+  pkg_credentials_local --> pkg_invariants
+  pkg_credentials_local --> pkg_paths
+  pkg_lsp --> pkg_brand
+  pkg_lsp --> pkg_invariants
+  pkg_lsp --> pkg_llm
+  pkg_sandbox --> pkg_invariants
+  pkg_sandbox --> pkg_llm
+  pkg_settings_local --> pkg_atomic_write
+  pkg_settings_local --> pkg_invariants
+  pkg_settings_local --> pkg_paths
+  pkg_settings_local --> pkg_settings
+  pkg_agent --> pkg_invariants
+  pkg_agent --> pkg_llm
+  pkg_agent --> pkg_scope
+  pkg_agent --> pkg_session
+  pkg_agent --> pkg_system_prompt
+  pkg_agent --> pkg_type_meta
+  pkg_bash --> pkg_invariants
+  pkg_bash --> pkg_sandbox
+  pkg_bash --> pkg_subprocess
+  pkg_fs --> pkg_brand
+  pkg_fs --> pkg_invariants
+  pkg_fs --> pkg_llm
+  pkg_fs --> pkg_sandbox
+  pkg_skill_badge --> pkg_invariants
+  pkg_skill_badge --> pkg_skill
+  pkg_compact --> pkg_invariants
+  pkg_compact --> pkg_llm
+  pkg_compact --> pkg_session
+  pkg_web_fetch_local --> pkg_invariants
+  pkg_web_fetch_local --> pkg_timeout
+  pkg_web_fetch_local --> pkg_web
+  pkg_web_search_exa --> pkg_environment
+  pkg_web_search_exa --> pkg_invariants
+  pkg_web_search_exa --> pkg_web
+  pkg_web_search_perplexity --> pkg_environment
+  pkg_web_search_perplexity --> pkg_invariants
+  pkg_web_search_perplexity --> pkg_web
+  pkg_spill --> pkg_brand
+  pkg_spill --> pkg_invariants
+  pkg_spill --> pkg_llm
+  pkg_spill --> pkg_session
+  pkg_acp_snapshot --> pkg_invariants
+  pkg_acp_snapshot --> pkg_session
+  pkg_app_boot --> pkg_environment
+  pkg_app_boot --> pkg_invariants
+  pkg_app_boot --> pkg_paths
+  pkg_app_boot --> pkg_system_prompt
+  pkg_client_ui_question --> pkg_client_locale
+  pkg_client_ui_question --> pkg_invariants
+  pkg_client_ui_settings_general --> pkg_client_connection
+  pkg_client_ui_settings_general --> pkg_client_locale
+  pkg_client_ui_settings_general --> pkg_client_runtime
+  pkg_client_ui_settings_general --> pkg_client_ui_primitives
+  pkg_client_ui_settings_general --> pkg_client_ui_settings
+  pkg_client_ui_settings_general --> pkg_client_ui_slots
+  pkg_client_ui_settings_general --> pkg_client_web_react
+  pkg_client_ui_settings_general --> pkg_invariants
+  pkg_client_ui_sidebar --> pkg_client_locale
+  pkg_client_ui_sidebar --> pkg_client_runtime
+  pkg_client_ui_sidebar --> pkg_client_ui_primitives
+  pkg_client_ui_sidebar --> pkg_client_ui_slots
+  pkg_client_ui_sidebar --> pkg_invariants
+  pkg_client_ui_slash --> pkg_client_locale
+  pkg_client_ui_slash --> pkg_client_runtime
+  pkg_client_ui_slash --> pkg_client_ui_primitives
+  pkg_client_ui_slash --> pkg_client_ui_slots
+  pkg_client_ui_slash --> pkg_invariants
+  pkg_client_ui_theme --> pkg_client_locale
+  pkg_client_ui_theme --> pkg_client_runtime
+  pkg_client_ui_theme --> pkg_client_ui_primitives
+  pkg_client_ui_theme --> pkg_client_ui_slots
+  pkg_client_ui_theme --> pkg_invariants
+  pkg_client_ui_workspace --> pkg_client_locale
+  pkg_client_ui_workspace --> pkg_client_runtime
+  pkg_client_ui_workspace --> pkg_client_ui_primitives
+  pkg_client_ui_workspace --> pkg_client_ui_slots
+  pkg_client_ui_workspace --> pkg_invariants
+  pkg_code_runtime_worker --> pkg_code_runtime
+  pkg_code_runtime_worker --> pkg_invariants
+  pkg_code_runtime_worker --> pkg_session
+  pkg_code_runtime_worker --> pkg_timeout
+  pkg_sandbox_local --> pkg_invariants
+  pkg_sandbox_local --> pkg_llm
+  pkg_sandbox_local --> pkg_sandbox
+  pkg_session_persistence --> pkg_brand
+  pkg_session_persistence --> pkg_invariants
+  pkg_session_persistence --> pkg_session
+  pkg_session_persistence --> pkg_timeout
+  pkg_session_projection --> pkg_invariants
+  pkg_session_projection --> pkg_session
+  pkg_llm_retry --> pkg_agent
+  pkg_llm_retry --> pkg_invariants
+  pkg_llm_retry --> pkg_llm
+  pkg_llm_retry --> pkg_session
+  pkg_llm_retry --> pkg_timeout
+  pkg_token_meter --> pkg_compact
+  pkg_token_meter --> pkg_invariants
+  pkg_token_meter --> pkg_llm
+  pkg_token_meter --> pkg_session
+  pkg_token_meter --> pkg_session_projection
+  pkg_goal --> pkg_agent
+  pkg_goal --> pkg_brand
+  pkg_goal --> pkg_invariants
+  pkg_goal --> pkg_llm
+  pkg_goal --> pkg_scope
+  pkg_goal --> pkg_session
+  pkg_goal --> pkg_session_projection
+  pkg_goal --> pkg_type_meta
+  pkg_bash_local --> pkg_bash
+  pkg_bash_local --> pkg_invariants
+  pkg_bash_local --> pkg_subprocess
+  pkg_bash_local --> pkg_timeout
+  pkg_pwsh_local --> pkg_bash
+  pkg_pwsh_local --> pkg_invariants
+  pkg_pwsh_local --> pkg_subprocess
+  pkg_pwsh_local --> pkg_timeout
+  pkg_fs_local --> pkg_fs
+  pkg_fs_local --> pkg_invariants
+  pkg_fs_policy --> pkg_fs
+  pkg_fs_policy --> pkg_invariants
+  pkg_skill_local --> pkg_fs
+  pkg_skill_local --> pkg_invariants
+  pkg_skill_local --> pkg_paths
+  pkg_skill_local --> pkg_skill
+  pkg_web_search_deepseek --> pkg_agent
+  pkg_web_search_deepseek --> pkg_credentials
+  pkg_web_search_deepseek --> pkg_environment
+  pkg_web_search_deepseek --> pkg_invariants
+  pkg_web_search_deepseek --> pkg_session
+  pkg_web_search_deepseek --> pkg_web
+  pkg_spill_local --> pkg_invariants
+  pkg_spill_local --> pkg_spill
+  pkg_hook_protocol --> pkg_bash
+  pkg_hook_protocol --> pkg_invariants
+  pkg_hook_protocol --> pkg_session
+  pkg_llm_replay --> pkg_compact
+  pkg_llm_replay --> pkg_invariants
+  pkg_llm_replay --> pkg_llm
+  pkg_llm_replay --> pkg_session
+  pkg_loader_smoke --> pkg_agent
+  pkg_loader_smoke --> pkg_invariants
+  pkg_loader_smoke --> pkg_llm
+  pkg_loader_smoke --> pkg_session
+  pkg_headless --> pkg_agent
+  pkg_headless --> pkg_host_apiproxy
+  pkg_headless --> pkg_host_webserver
+  pkg_headless --> pkg_invariants
+  pkg_headless --> pkg_session
+  pkg_client_ui_layout --> pkg_client_runtime
+  pkg_client_ui_layout --> pkg_client_ui_slots
+  pkg_client_ui_layout --> pkg_client_ui_theme
+  pkg_client_ui_layout --> pkg_invariants
+  pkg_time_context --> pkg_agent
+  pkg_time_context --> pkg_invariants
+  pkg_time_context --> pkg_session
+  pkg_tmux_context --> pkg_agent
+  pkg_tmux_context --> pkg_bash
+  pkg_tmux_context --> pkg_invariants
+  pkg_tmux_context --> pkg_session
+  pkg_fs_e2b --> pkg_e2b
+  pkg_fs_e2b --> pkg_fs
+  pkg_fs_e2b --> pkg_invariants
+  pkg_host_directory_picker_browse --> pkg_client_locale
+  pkg_host_directory_picker_browse --> pkg_client_runtime
+  pkg_host_directory_picker_browse --> pkg_client_ui_primitives
+  pkg_host_directory_picker_browse --> pkg_client_ui_slots
+  pkg_host_directory_picker_browse --> pkg_client_ui_workspace
+  pkg_host_directory_picker_browse --> pkg_invariants
+  pkg_host_directory_picker_native --> pkg_client_runtime
+  pkg_host_directory_picker_native --> pkg_client_ui_slots
+  pkg_host_directory_picker_native --> pkg_client_ui_workspace
+  pkg_host_directory_picker_native --> pkg_invariants
+  pkg_commands --> pkg_agent
+  pkg_commands --> pkg_brand
+  pkg_commands --> pkg_invariants
+  pkg_commands --> pkg_scope
+  pkg_commands --> pkg_session
+  pkg_user_approval --> pkg_agent
+  pkg_user_approval --> pkg_brand
+  pkg_user_approval --> pkg_invariants
+  pkg_user_approval --> pkg_llm
+  pkg_user_approval --> pkg_scope
+  pkg_user_approval --> pkg_session
+  pkg_user_approval --> pkg_system_prompt
+  pkg_user_interaction --> pkg_agent
+  pkg_user_interaction --> pkg_invariants
+  pkg_user_interaction --> pkg_llm
+  pkg_lsp_local --> pkg_brand
+  pkg_lsp_local --> pkg_fs
+  pkg_lsp_local --> pkg_invariants
+  pkg_lsp_local --> pkg_llm
+  pkg_lsp_local --> pkg_lsp
+  pkg_lsp_local --> pkg_subprocess
+  pkg_lsp_local --> pkg_timeout
+  pkg_pty --> pkg_agent
+  pkg_pty --> pkg_brand
+  pkg_pty --> pkg_invariants
+  pkg_sandbox_policy --> pkg_agent
+  pkg_sandbox_policy --> pkg_invariants
+  pkg_sandbox_policy --> pkg_sandbox
+  pkg_sandbox_policy --> pkg_session
+  pkg_sandbox_policy --> pkg_system_prompt
+  pkg_scripts --> pkg_app_boot
+  pkg_scripts --> pkg_invariants
+  pkg_session_persistence_jsonl --> pkg_invariants
+  pkg_session_persistence_jsonl --> pkg_session
+  pkg_session_persistence_jsonl --> pkg_session_persistence
+  pkg_session_persistence_sqlite --> pkg_invariants
+  pkg_session_persistence_sqlite --> pkg_session
+  pkg_session_persistence_sqlite --> pkg_session_persistence
+  pkg_session_projection_cache --> pkg_invariants
+  pkg_session_projection_cache --> pkg_session
+  pkg_session_projection_cache --> pkg_session_persistence
+  pkg_session_projection_cache --> pkg_session_projection
+  pkg_session_projection_cache --> pkg_storage_domain
+  pkg_session_telemetry --> pkg_agent
+  pkg_session_telemetry --> pkg_invariants
+  pkg_session_telemetry --> pkg_session
+  pkg_session_title --> pkg_brand
+  pkg_session_title --> pkg_invariants
+  pkg_session_title --> pkg_llm
+  pkg_session_title --> pkg_session
+  pkg_session_title --> pkg_session_projection
+  pkg_tasks --> pkg_agent
+  pkg_tasks --> pkg_brand
+  pkg_tasks --> pkg_invariants
+  pkg_tasks --> pkg_session
+  pkg_workflow --> pkg_agent
+  pkg_workflow --> pkg_brand
+  pkg_workflow --> pkg_invariants
+  pkg_workflow --> pkg_llm
+  pkg_workflow --> pkg_session
+  pkg_workspace --> pkg_brand
+  pkg_workspace --> pkg_invariants
+  pkg_workspace --> pkg_session
+  pkg_workspace --> pkg_session_persistence
+  pkg_workspace --> pkg_storage
+  pkg_workspace --> pkg_storage_domain
+  pkg_tools --> pkg_agent
+  pkg_tools --> pkg_code_runtime
+  pkg_tools --> pkg_invariants
+  pkg_tools --> pkg_llm
+  pkg_tools --> pkg_scope
+  pkg_tools --> pkg_session
+  pkg_tools --> pkg_system_prompt
+  pkg_tools --> pkg_user_approval
+  pkg_command_goal --> pkg_commands
+  pkg_command_goal --> pkg_goal
+  pkg_command_goal --> pkg_invariants
+  pkg_goal_session --> pkg_agent
+  pkg_goal_session --> pkg_goal
+  pkg_goal_session --> pkg_invariants
+  pkg_goal_session --> pkg_llm
+  pkg_goal_session --> pkg_session
+  pkg_bash_sandbox --> pkg_bash
+  pkg_bash_sandbox --> pkg_bash_local
+  pkg_bash_sandbox --> pkg_invariants
+  pkg_bash_sandbox --> pkg_sandbox
+  pkg_bash_sandbox --> pkg_sandbox_policy
+  pkg_fs_sandbox --> pkg_fs
+  pkg_fs_sandbox --> pkg_fs_local
+  pkg_fs_sandbox --> pkg_invariants
+  pkg_fs_sandbox --> pkg_sandbox
+  pkg_fs_sandbox --> pkg_sandbox_policy
+  pkg_command_compact --> pkg_commands
+  pkg_command_compact --> pkg_compact
+  pkg_command_compact --> pkg_invariants
+  pkg_compact_tool_result_prune --> pkg_compact
+  pkg_compact_tool_result_prune --> pkg_invariants
+  pkg_compact_tool_result_prune --> pkg_llm
+  pkg_compact_tool_result_prune --> pkg_session
+  pkg_compact_tool_result_prune --> pkg_token_meter
+  pkg_session_query --> pkg_brand
+  pkg_session_query --> pkg_invariants
+  pkg_session_query --> pkg_llm
+  pkg_session_query --> pkg_session
+  pkg_session_query --> pkg_session_persistence
+  pkg_session_query --> pkg_session_title
+  pkg_acp --> pkg_agent
+  pkg_acp --> pkg_invariants
+  pkg_acp --> pkg_session
+  pkg_acp --> pkg_user_approval
+  pkg_api_remotes --> pkg_agent
+  pkg_api_remotes --> pkg_goal
+  pkg_api_remotes --> pkg_invariants
+  pkg_api_remotes --> pkg_session
+  pkg_api_remotes --> pkg_session_persistence
+  pkg_api_remotes --> pkg_typert_registry
+  pkg_client_ui_conversation --> pkg_client_locale
+  pkg_client_ui_conversation --> pkg_client_runtime
+  pkg_client_ui_conversation --> pkg_client_ui_primitives
+  pkg_client_ui_conversation --> pkg_client_ui_slash
+  pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_token_meter
+  pkg_command_feedback --> pkg_commands
+  pkg_command_feedback --> pkg_invariants
+  pkg_command_feedback --> pkg_session
+  pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse
+  pkg_host_directory_picker_auto --> pkg_host_directory_picker_native
+  pkg_host_directory_picker_auto --> pkg_host_webserver
+  pkg_host_directory_picker_auto --> pkg_invariants
+  pkg_permission --> pkg_bash
+  pkg_permission --> pkg_commands
+  pkg_permission --> pkg_invariants
+  pkg_permission --> pkg_sandbox
+  pkg_permission --> pkg_sandbox_policy
+  pkg_permission --> pkg_session
+  pkg_permission --> pkg_session_projection
+  pkg_permission --> pkg_settings
+  pkg_permission --> pkg_user_approval
+  pkg_pty_local --> pkg_agent
+  pkg_pty_local --> pkg_invariants
+  pkg_pty_local --> pkg_pty
+  pkg_pty_local --> pkg_sandbox
+  pkg_pty_local --> pkg_sandbox_policy
+  pkg_pty_local --> pkg_session
+  pkg_pty_local --> pkg_subprocess
+  pkg_session_title_llm --> pkg_invariants
+  pkg_session_title_llm --> pkg_llm
+  pkg_session_title_llm --> pkg_session
+  pkg_session_title_llm --> pkg_session_title
+  pkg_session_title_llm --> pkg_timeout
+  pkg_tasks_local --> pkg_agent
+  pkg_tasks_local --> pkg_invariants
+  pkg_tasks_local --> pkg_tasks
+  pkg_tasks_local --> pkg_timeout
+  pkg_agent_loop --> pkg_agent
+  pkg_agent_loop --> pkg_invariants
+  pkg_agent_loop --> pkg_llm
+  pkg_agent_loop --> pkg_scope
+  pkg_agent_loop --> pkg_session
+  pkg_agent_loop --> pkg_session_persistence
+  pkg_agent_loop --> pkg_system_prompt
+  pkg_agent_loop --> pkg_tools
+  pkg_tool_goal --> pkg_agent
+  pkg_tool_goal --> pkg_goal
+  pkg_tool_goal --> pkg_invariants
+  pkg_tool_goal --> pkg_llm
+  pkg_tool_goal --> pkg_session
+  pkg_tool_goal --> pkg_system_prompt
+  pkg_tool_goal --> pkg_tools
+  pkg_bash_env --> pkg_bash
+  pkg_bash_env --> pkg_invariants
+  pkg_bash_env --> pkg_paths
+  pkg_bash_env --> pkg_session_persistence
+  pkg_bash_env --> pkg_tools
+  pkg_tool_fs --> pkg_fs
+  pkg_tool_fs --> pkg_invariants
+  pkg_tool_fs --> pkg_llm
+  pkg_tool_fs --> pkg_sandbox
+  pkg_tool_fs --> pkg_sandbox_policy
+  pkg_tool_fs --> pkg_session
+  pkg_tool_fs --> pkg_system_prompt
+  pkg_tool_fs --> pkg_tools
+  pkg_tool_fs --> pkg_user_approval
+  pkg_tool_fs_search --> pkg_invariants
+  pkg_tool_fs_search --> pkg_llm
+  pkg_tool_fs_search --> pkg_retention
+  pkg_tool_fs_search --> pkg_session
+  pkg_tool_fs_search --> pkg_spill
+  pkg_tool_fs_search --> pkg_subprocess
+  pkg_tool_fs_search --> pkg_system_prompt
+  pkg_tool_fs_search --> pkg_timeout
+  pkg_tool_fs_search --> pkg_tools
+  pkg_tool_str_replace_editor --> pkg_fs
+  pkg_tool_str_replace_editor --> pkg_invariants
+  pkg_tool_str_replace_editor --> pkg_sandbox
+  pkg_tool_str_replace_editor --> pkg_sandbox_policy
+  pkg_tool_str_replace_editor --> pkg_tools
+  pkg_tool_skill --> pkg_agent
+  pkg_tool_skill --> pkg_invariants
+  pkg_tool_skill --> pkg_llm
+  pkg_tool_skill --> pkg_skill
+  pkg_tool_skill --> pkg_tools
+  pkg_compact_basic --> pkg_agent
+  pkg_compact_basic --> pkg_compact
+  pkg_compact_basic --> pkg_compact_tool_result_prune
+  pkg_compact_basic --> pkg_invariants
+  pkg_compact_basic --> pkg_llm
+  pkg_compact_basic --> pkg_session
+  pkg_compact_basic --> pkg_token_meter
+  pkg_subagent --> pkg_agent
+  pkg_subagent --> pkg_brand
+  pkg_subagent --> pkg_invariants
+  pkg_subagent --> pkg_llm
+  pkg_subagent --> pkg_scope
+  pkg_subagent --> pkg_session
+  pkg_subagent --> pkg_session_persistence
+  pkg_subagent --> pkg_session_projection
+  pkg_subagent --> pkg_session_projection_cache
+  pkg_subagent --> pkg_tasks
+  pkg_subagent --> pkg_tools
+  pkg_tool_web --> pkg_invariants
+  pkg_tool_web --> pkg_llm
+  pkg_tool_web --> pkg_system_prompt
+  pkg_tool_web --> pkg_tools
+  pkg_tool_web --> pkg_web
+  pkg_spill_policy --> pkg_invariants
+  pkg_spill_policy --> pkg_llm
+  pkg_spill_policy --> pkg_retention
+  pkg_spill_policy --> pkg_session
+  pkg_spill_policy --> pkg_spill
+  pkg_spill_policy --> pkg_tools
+  pkg_tool_todo --> pkg_agent
+  pkg_tool_todo --> pkg_invariants
+  pkg_tool_todo --> pkg_session
+  pkg_tool_todo --> pkg_session_projection
+  pkg_tool_todo --> pkg_tools
+  pkg_plan_mode --> pkg_agent
+  pkg_plan_mode --> pkg_commands
+  pkg_plan_mode --> pkg_invariants
+  pkg_plan_mode --> pkg_llm
+  pkg_plan_mode --> pkg_session
+  pkg_plan_mode --> pkg_session_projection
+  pkg_plan_mode --> pkg_system_prompt
+  pkg_plan_mode --> pkg_tools
+  pkg_plan_mode --> pkg_user_interaction
+  pkg_hooks_codex --> pkg_agent
+  pkg_hooks_codex --> pkg_hook_protocol
+  pkg_hooks_codex --> pkg_invariants
+  pkg_hooks_codex --> pkg_llm
+  pkg_hooks_codex --> pkg_session
+  pkg_hooks_codex --> pkg_session_persistence
+  pkg_hooks_codex --> pkg_tools
+  pkg_session_query_sqlite --> pkg_invariants
+  pkg_session_query_sqlite --> pkg_session
+  pkg_session_query_sqlite --> pkg_session_persistence
+  pkg_session_query_sqlite --> pkg_session_query
+  pkg_tool_session_query --> pkg_invariants
+  pkg_tool_session_query --> pkg_llm
+  pkg_tool_session_query --> pkg_session
+  pkg_tool_session_query --> pkg_session_query
+  pkg_tool_session_query --> pkg_system_prompt
+  pkg_tool_session_query --> pkg_timeout
+  pkg_tool_session_query --> pkg_tools
+  pkg_agent_loop_testkit --> pkg_agent
+  pkg_agent_loop_testkit --> pkg_invariants
+  pkg_agent_loop_testkit --> pkg_llm
+  pkg_agent_loop_testkit --> pkg_session
+  pkg_agent_loop_testkit --> pkg_system_prompt
+  pkg_agent_loop_testkit --> pkg_tools
+  pkg_client_ui_command --> pkg_client_connection
+  pkg_client_ui_command --> pkg_client_locale
+  pkg_client_ui_command --> pkg_client_runtime
+  pkg_client_ui_command --> pkg_client_ui_conversation
+  pkg_client_ui_command --> pkg_client_ui_primitives
+  pkg_client_ui_command --> pkg_client_ui_slash
+  pkg_client_ui_command --> pkg_client_ui_slots
+  pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_deliverables --> pkg_client_locale
+  pkg_client_ui_deliverables --> pkg_client_runtime
+  pkg_client_ui_deliverables --> pkg_client_ui_conversation
+  pkg_client_ui_deliverables --> pkg_client_ui_slots
+  pkg_client_ui_deliverables --> pkg_invariants
+  pkg_client_ui_goal --> pkg_api_remotes
+  pkg_client_ui_goal --> pkg_client_locale
+  pkg_client_ui_goal --> pkg_client_runtime
+  pkg_client_ui_goal --> pkg_client_ui_conversation
+  pkg_client_ui_goal --> pkg_client_ui_primitives
+  pkg_client_ui_goal --> pkg_client_ui_slots
+  pkg_client_ui_goal --> pkg_goal
+  pkg_client_ui_goal --> pkg_invariants
+  pkg_client_ui_tool --> pkg_client_locale
+  pkg_client_ui_tool --> pkg_client_runtime
+  pkg_client_ui_tool --> pkg_client_ui_conversation
+  pkg_client_ui_tool --> pkg_client_ui_primitives
+  pkg_client_ui_tool --> pkg_client_ui_slots
+  pkg_client_ui_tool --> pkg_invariants
+  pkg_session_reference --> pkg_agent
+  pkg_session_reference --> pkg_compact
+  pkg_session_reference --> pkg_invariants
+  pkg_session_reference --> pkg_llm
+  pkg_session_reference --> pkg_retention
+  pkg_session_reference --> pkg_session
+  pkg_session_reference --> pkg_session_query
+  pkg_workspace_context --> pkg_agent
+  pkg_workspace_context --> pkg_fs
+  pkg_workspace_context --> pkg_invariants
+  pkg_workspace_context --> pkg_llm
+  pkg_workspace_context --> pkg_paths
+  pkg_workspace_context --> pkg_session
+  pkg_workspace_context --> pkg_tools
+  pkg_repeat_tool_guard --> pkg_agent
+  pkg_repeat_tool_guard --> pkg_invariants
+  pkg_repeat_tool_guard --> pkg_tools
+  pkg_timeout_policy --> pkg_invariants
+  pkg_timeout_policy --> pkg_llm
+  pkg_timeout_policy --> pkg_timeout
+  pkg_timeout_policy --> pkg_tools
+  pkg_tool_ask_user --> pkg_agent
+  pkg_tool_ask_user --> pkg_invariants
+  pkg_tool_ask_user --> pkg_tools
+  pkg_tool_ask_user --> pkg_user_interaction
+  pkg_tool_lsp --> pkg_invariants
+  pkg_tool_lsp --> pkg_llm
+  pkg_tool_lsp --> pkg_lsp
+  pkg_tool_lsp --> pkg_system_prompt
+  pkg_tool_lsp --> pkg_timeout
+  pkg_tool_lsp --> pkg_tools
+  pkg_mcp_client --> pkg_invariants
+  pkg_mcp_client --> pkg_llm
+  pkg_mcp_client --> pkg_subprocess
+  pkg_mcp_client --> pkg_tools
+  pkg_tool_bash_persistent --> pkg_agent
+  pkg_tool_bash_persistent --> pkg_invariants
+  pkg_tool_bash_persistent --> pkg_pty
+  pkg_tool_bash_persistent --> pkg_timeout
+  pkg_tool_bash_persistent --> pkg_tools
+  pkg_tool_pty --> pkg_agent
+  pkg_tool_pty --> pkg_invariants
+  pkg_tool_pty --> pkg_llm
+  pkg_tool_pty --> pkg_pty
+  pkg_tool_pty --> pkg_retention
+  pkg_tool_pty --> pkg_system_prompt
+  pkg_tool_pty --> pkg_tasks
+  pkg_tool_pty --> pkg_tools
+  pkg_tool_cordis --> pkg_invariants
+  pkg_tool_cordis --> pkg_scope
+  pkg_tool_cordis --> pkg_tools
+  pkg_session_checkpoint_policy --> pkg_agent
+  pkg_session_checkpoint_policy --> pkg_invariants
+  pkg_session_checkpoint_policy --> pkg_llm
+  pkg_session_checkpoint_policy --> pkg_session
+  pkg_session_checkpoint_policy --> pkg_session_persistence
+  pkg_session_checkpoint_policy --> pkg_tools
+  pkg_session_telemetry_otel --> pkg_brand
+  pkg_session_telemetry_otel --> pkg_command_feedback
+  pkg_session_telemetry_otel --> pkg_invariants
+  pkg_session_telemetry_otel --> pkg_llm
+  pkg_session_telemetry_otel --> pkg_paths
+  pkg_session_telemetry_otel --> pkg_session
+  pkg_session_telemetry_otel --> pkg_session_telemetry
+  pkg_session_title_all_messages_llm --> pkg_invariants
+  pkg_session_title_all_messages_llm --> pkg_llm
+  pkg_session_title_all_messages_llm --> pkg_session
+  pkg_session_title_all_messages_llm --> pkg_session_title
+  pkg_session_title_all_messages_llm --> pkg_session_title_llm
+  pkg_session_title_first_message_llm --> pkg_invariants
+  pkg_session_title_first_message_llm --> pkg_llm
+  pkg_session_title_first_message_llm --> pkg_session
+  pkg_session_title_first_message_llm --> pkg_session_title
+  pkg_session_title_first_message_llm --> pkg_session_title_llm
+  pkg_tool_tasks --> pkg_agent
+  pkg_tool_tasks --> pkg_invariants
+  pkg_tool_tasks --> pkg_llm
+  pkg_tool_tasks --> pkg_retention
+  pkg_tool_tasks --> pkg_system_prompt
+  pkg_tool_tasks --> pkg_tasks
+  pkg_tool_tasks --> pkg_tools
+  pkg_tool_workflow --> pkg_agent
+  pkg_tool_workflow --> pkg_invariants
+  pkg_tool_workflow --> pkg_llm
+  pkg_tool_workflow --> pkg_system_prompt
+  pkg_tool_workflow --> pkg_tools
+  pkg_tool_workflow --> pkg_workflow
+  pkg_tool_bash --> pkg_agent
+  pkg_tool_bash --> pkg_bash
+  pkg_tool_bash --> pkg_bash_env
+  pkg_tool_bash --> pkg_invariants
+  pkg_tool_bash --> pkg_llm
+  pkg_tool_bash --> pkg_sandbox
+  pkg_tool_bash --> pkg_sandbox_policy
+  pkg_tool_bash --> pkg_system_prompt
+  pkg_tool_bash --> pkg_tasks
+  pkg_tool_bash --> pkg_tools
+  pkg_tool_bash --> pkg_user_approval
+  pkg_tool_pwsh --> pkg_agent
+  pkg_tool_pwsh --> pkg_bash
+  pkg_tool_pwsh --> pkg_bash_env
+  pkg_tool_pwsh --> pkg_invariants
+  pkg_tool_pwsh --> pkg_llm
+  pkg_tool_pwsh --> pkg_system_prompt
+  pkg_tool_pwsh --> pkg_tasks
+  pkg_tool_pwsh --> pkg_tools
+  pkg_subagent_acp --> pkg_agent
+  pkg_subagent_acp --> pkg_invariants
+  pkg_subagent_acp --> pkg_llm
+  pkg_subagent_acp --> pkg_session
+  pkg_subagent_acp --> pkg_subagent
+  pkg_subagent_acp --> pkg_subprocess
+  pkg_subagent_acp --> pkg_timeout
+  pkg_subagent_claude_code --> pkg_invariants
+  pkg_subagent_claude_code --> pkg_llm
+  pkg_subagent_claude_code --> pkg_session
+  pkg_subagent_claude_code --> pkg_subagent
+  pkg_subagent_claude_code --> pkg_subprocess
+  pkg_subagent_claude_code --> pkg_timeout
+  pkg_subagent_inprocess --> pkg_agent
+  pkg_subagent_inprocess --> pkg_invariants
+  pkg_subagent_inprocess --> pkg_llm
+  pkg_subagent_inprocess --> pkg_sandbox_policy
+  pkg_subagent_inprocess --> pkg_session
+  pkg_subagent_inprocess --> pkg_subagent
+  pkg_subagent_inprocess --> pkg_system_prompt
+  pkg_subagent_inprocess --> pkg_tools
+  pkg_subagent_inprocess --> pkg_user_approval
+  pkg_tool_subagent --> pkg_agent
+  pkg_tool_subagent --> pkg_invariants
+  pkg_tool_subagent --> pkg_llm
+  pkg_tool_subagent --> pkg_subagent
+  pkg_tool_subagent --> pkg_tasks
+  pkg_tool_subagent --> pkg_tools
+  pkg_tool_subagent_control --> pkg_invariants
+  pkg_tool_subagent_control --> pkg_llm
+  pkg_tool_subagent_control --> pkg_session
+  pkg_tool_subagent_control --> pkg_subagent
+  pkg_tool_subagent_control --> pkg_tools
+  pkg_tool_subagent_report --> pkg_invariants
+  pkg_tool_subagent_report --> pkg_llm
+  pkg_tool_subagent_report --> pkg_subagent
+  pkg_tool_subagent_report --> pkg_tools
+  pkg_hooks_claude --> pkg_agent
+  pkg_hooks_claude --> pkg_hook_protocol
+  pkg_hooks_claude --> pkg_invariants
+  pkg_hooks_claude --> pkg_llm
+  pkg_hooks_claude --> pkg_session
+  pkg_hooks_claude --> pkg_session_persistence
+  pkg_hooks_claude --> pkg_subagent
+  pkg_hooks_claude --> pkg_tools
+  pkg_web_app --> pkg_bash_env
+  pkg_web_app --> pkg_invariants
+  pkg_web_app --> pkg_system_prompt
+  pkg_client_ui_model --> pkg_client_connection
+  pkg_client_ui_model --> pkg_client_locale
+  pkg_client_ui_model --> pkg_client_runtime
+  pkg_client_ui_model --> pkg_client_ui_command
+  pkg_client_ui_model --> pkg_client_ui_conversation
+  pkg_client_ui_model --> pkg_client_ui_primitives
+  pkg_client_ui_model --> pkg_client_ui_slash
+  pkg_client_ui_model --> pkg_client_ui_slots
+  pkg_client_ui_model --> pkg_invariants
+  pkg_client_ui_permission --> pkg_client_connection
+  pkg_client_ui_permission --> pkg_client_locale
+  pkg_client_ui_permission --> pkg_client_runtime
+  pkg_client_ui_permission --> pkg_client_schema_form
+  pkg_client_ui_permission --> pkg_client_ui_command
+  pkg_client_ui_permission --> pkg_client_ui_primitives
+  pkg_client_ui_permission --> pkg_client_ui_slash
+  pkg_client_ui_permission --> pkg_client_ui_slots
+  pkg_client_ui_permission --> pkg_invariants
+  pkg_client_ui_permission --> pkg_permission
+  pkg_client_ui_plan --> pkg_client_connection
+  pkg_client_ui_plan --> pkg_client_locale
+  pkg_client_ui_plan --> pkg_client_runtime
+  pkg_client_ui_plan --> pkg_client_ui_conversation
+  pkg_client_ui_plan --> pkg_client_ui_primitives
+  pkg_client_ui_plan --> pkg_client_ui_slots
+  pkg_client_ui_plan --> pkg_invariants
+  pkg_client_ui_plan --> pkg_plan_mode
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_locale
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_primitives
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_client_ui_tool
+  pkg_client_ui_skill --> pkg_invariants
+  pkg_client_ui_subagent --> pkg_client_locale
+  pkg_client_ui_subagent --> pkg_client_runtime
+  pkg_client_ui_subagent --> pkg_client_ui_conversation
+  pkg_client_ui_subagent --> pkg_client_ui_primitives
+  pkg_client_ui_subagent --> pkg_client_ui_slash
+  pkg_client_ui_subagent --> pkg_client_ui_slots
+  pkg_client_ui_subagent --> pkg_invariants
+  pkg_client_ui_subagent --> pkg_subagent
+  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_sdk_protocol --> pkg_invariants
+  pkg_sdk_protocol --> pkg_llm
+  pkg_sdk_protocol --> pkg_session
+  pkg_sdk_protocol --> pkg_subagent
+  pkg_repository_plugin --> pkg_invariants
+  pkg_repository_plugin --> pkg_mcp_client
+  pkg_repository_plugin --> pkg_paths
+  pkg_repository_plugin --> pkg_skill_local
+  pkg_tool_ralph --> pkg_agent
+  pkg_tool_ralph --> pkg_invariants
+  pkg_tool_ralph --> pkg_llm
+  pkg_tool_ralph --> pkg_subagent
+  pkg_tool_ralph --> pkg_system_prompt
+  pkg_tool_ralph --> pkg_tools
+  pkg_tool_ralph --> pkg_workflow
+  pkg_workflow_workerthread --> pkg_agent
+  pkg_workflow_workerthread --> pkg_brand
+  pkg_workflow_workerthread --> pkg_invariants
+  pkg_workflow_workerthread --> pkg_llm
+  pkg_workflow_workerthread --> pkg_session
+  pkg_workflow_workerthread --> pkg_subagent
+  pkg_workflow_workerthread --> pkg_tools
+  pkg_workflow_workerthread --> pkg_workflow
+  pkg_subagent_codex --> pkg_invariants
+  pkg_subagent_codex --> pkg_llm
+  pkg_subagent_codex --> pkg_sdk_protocol
+  pkg_subagent_codex --> pkg_session
+  pkg_subagent_codex --> pkg_subagent
+  pkg_subagent_codex --> pkg_subprocess
+  pkg_subagent_codex --> pkg_timeout
+  pkg_subagent_fork --> pkg_agent
+  pkg_subagent_fork --> pkg_invariants
+  pkg_subagent_fork --> pkg_session
+  pkg_subagent_fork --> pkg_subagent
+  pkg_subagent_fork --> pkg_subagent_inprocess
+  pkg_subagent_spawn --> pkg_invariants
+  pkg_subagent_spawn --> pkg_subagent
+  pkg_subagent_spawn --> pkg_subagent_inprocess
+  pkg_agent_spine_demo --> pkg_agent
+  pkg_agent_spine_demo --> pkg_agent_loop
+  pkg_agent_spine_demo --> pkg_bash_env
+  pkg_agent_spine_demo --> pkg_goal
+  pkg_agent_spine_demo --> pkg_goal_session
+  pkg_agent_spine_demo --> pkg_invariants
+  pkg_agent_spine_demo --> pkg_llm
+  pkg_agent_spine_demo --> pkg_llm_retry
+  pkg_agent_spine_demo --> pkg_paths
+  pkg_agent_spine_demo --> pkg_scope
+  pkg_agent_spine_demo --> pkg_session
+  pkg_agent_spine_demo --> pkg_session_title
+  pkg_agent_spine_demo --> pkg_skill
+  pkg_agent_spine_demo --> pkg_skill_local
+  pkg_agent_spine_demo --> pkg_system_prompt
+  pkg_agent_spine_demo --> pkg_tasks_local
+  pkg_agent_spine_demo --> pkg_tool_bash
+  pkg_agent_spine_demo --> pkg_tool_goal
+  pkg_agent_spine_demo --> pkg_tool_skill
+  pkg_agent_spine_demo --> pkg_tool_tasks
+  pkg_agent_spine_demo --> pkg_tools
+  pkg_agent_spine_demo --> pkg_workspace_context
+  pkg_jsonrpc --> pkg_agent
+  pkg_jsonrpc --> pkg_invariants
+  pkg_jsonrpc --> pkg_llm
+  pkg_jsonrpc --> pkg_llm_deepseek
+  pkg_jsonrpc --> pkg_scope
+  pkg_jsonrpc --> pkg_sdk_protocol
+  pkg_jsonrpc --> pkg_session
+  pkg_jsonrpc --> pkg_subagent
+  pkg_sdk_client --> pkg_invariants
+  pkg_sdk_client --> pkg_llm
+  pkg_sdk_client --> pkg_sdk_protocol
+  pkg_sdk_client --> pkg_session
+  pkg_subagent_dsh_sdk --> pkg_agent
+  pkg_subagent_dsh_sdk --> pkg_invariants
+  pkg_subagent_dsh_sdk --> pkg_llm
+  pkg_subagent_dsh_sdk --> pkg_sdk_client
+  pkg_subagent_dsh_sdk --> pkg_session
+  pkg_subagent_dsh_sdk --> pkg_subagent
+  pkg_subagent_dsh_sdk --> pkg_subprocess
+  pkg_acp_demo --> pkg_acp
+  pkg_acp_demo --> pkg_agent_spine_demo
+  pkg_acp_demo --> pkg_app_boot
+  pkg_acp_demo --> pkg_invariants
+  pkg_acp_demo --> pkg_session_checkpoint_policy
+  pkg_acp_demo --> pkg_session_persistence_jsonl
+  pkg_acp_demo --> pkg_session_query
+  pkg_acp_demo --> pkg_session_query_sqlite
+  pkg_acp_demo --> pkg_tools
+  pkg_acp_demo --> pkg_workspace_context
+```
+
+| 包 | 分组 | 依赖项 |
+| --- | --- | --- |
+| [`invariants`](../packages/support/invariants) | `support` | — |
+| [`atomic-write`](../packages/util/atomic-write) | `util` | [`invariants`](../packages/support/invariants) |
+| [`brand`](../packages/util/brand) | `util` | [`invariants`](../packages/support/invariants) |
+| [`environment`](../packages/util/environment) | `util` | [`invariants`](../packages/support/invariants) |
+| [`native-command`](../packages/util/native-command) | `util` | [`invariants`](../packages/support/invariants) |
+| [`paths`](../packages/util/paths) | `util` | [`invariants`](../packages/support/invariants) |
+| [`retention`](../packages/util/retention) | `util` | [`invariants`](../packages/support/invariants) |
+| [`timeout`](../packages/util/timeout) | `util` | [`invariants`](../packages/support/invariants) |
+| [`scope`](../packages/core/scope) | `core` | [`invariants`](../packages/support/invariants) |
+| [`llm-mock-server`](../packages/support/llm-mock-server) | `support` | [`invariants`](../packages/support/invariants) |
+| [`base`](../packages/bundle/base) | `bundle` | [`invariants`](../packages/support/invariants) |
+| [`client-modules`](../packages/client/modules) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-schema-form`](../packages/client/schema-form) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-primitives`](../packages/client/ui-primitives) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-ui-slots`](../packages/client/ui-slots) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-web`](../packages/client/web) | `client` | [`invariants`](../packages/support/invariants) |
+| [`client-web-react`](../packages/client/web-react) | `client` | [`invariants`](../packages/support/invariants) |
+| [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | [`invariants`](../packages/support/invariants) |
+| [`e2b`](../packages/e2b/e2b) | `e2b` | [`invariants`](../packages/support/invariants) |
+| [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | [`invariants`](../packages/support/invariants) |
+| [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`invariants`](../packages/support/invariants) |
+| [`host-directory-picker`](../packages/host/directory-picker) | `host` | [`invariants`](../packages/support/invariants) |
+| [`host-webserver`](../packages/host/webserver) | `host` | [`invariants`](../packages/support/invariants) |
+| [`storage`](../packages/storage/storage) | `storage` | [`invariants`](../packages/support/invariants) |
+| [`subprocess`](../packages/subprocess/subprocess) | `subprocess` | [`invariants`](../packages/support/invariants) |
+| [`type-meta`](../packages/typert/type-meta) | `typert` | [`invariants`](../packages/support/invariants) |
+| [`typert-generator`](../packages/typert/generator) | `typert` | [`invariants`](../packages/support/invariants) |
+| [`typert-registry`](../packages/typert/registry) | `typert` | [`invariants`](../packages/support/invariants) |
+| [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout) |
+| [`client-connection`](../packages/client/connection) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`client-runtime`](../packages/client/runtime) | `client` | [`invariants`](../packages/support/invariants), [`type-meta`](../packages/typert/type-meta), [`typert-registry`](../packages/typert/registry) |
+| [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`helper`](../packages/scaffold/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
+| [`telemetry`](../packages/scaffold/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`settings`](../packages/settings/settings) | `settings` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
+| [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
+| [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
+| [`subprocess-local`](../packages/subprocess/subprocess-local) | `subprocess` | [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
+| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
+| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`type-meta`](../packages/typert/type-meta) |
+| [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
+| [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection), [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
+| [`client-locale`](../packages/client/locale) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-test-runtime`](../packages/client/test-runtime) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/support/invariants) |
+| [`client-ui-models`](../packages/client/ui-models) | `client` | [`client-connection`](../packages/client/connection), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
+| [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`invariants`](../packages/support/invariants) |
+| [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`settings-local`](../packages/settings/settings-local) | `settings` | [`atomic-write`](../packages/util/atomic-write), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`settings`](../packages/settings/settings) |
+| [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`type-meta`](../packages/typert/type-meta) |
+| [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`subprocess`](../packages/subprocess/subprocess) |
+| [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
+| [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/support/invariants), [`skill`](../packages/skill/skill) |
+| [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
+| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`session-persistence`](../packages/support/acp-snapshot) | `session-persistence` | [`brand`](../packages/support/invariants), [`invariants`](../packages/core/session), [`session`](../packages/boot/app-boot), [`timeout`](../packages/util/environment) |
+| [`acp-snapshot`](../packages/support/invariants) | `support` | [`invariants`](../packages/util/paths), [`session`](../packages/core/system-prompt) |
+| [`app-boot`](../packages/client/ui-question) | `ui` | [`environment`](../packages/client/locale), [`invariants`](../packages/support/invariants), [`paths`](../packages/client/ui-settings-general), [`system-prompt`](../packages/client/connection) |
+| [`client-ui-question`](../packages/client/locale) | `client` | [`client-locale`](../packages/client/runtime), [`invariants`](../packages/client/ui-primitives) |
+| [`client-ui-settings-general`](../packages/client/ui-settings) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/client/web-react), [`client-runtime`](../packages/support/invariants), [`client-ui-primitives`](../packages/client/ui-sidebar), [`client-ui-settings`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`client-web-react`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
+| [`client-ui-sidebar`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
+| [`client-ui-slash`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-theme), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
+| [`client-ui-theme`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-workspace), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
+| [`client-ui-workspace`](../packages/support/invariants) | `client` | [`client-locale`](../packages/code-runtime/code-runtime-worker), [`client-runtime`](../packages/code-runtime/code-runtime), [`client-ui-primitives`](../packages/support/invariants), [`client-ui-slots`](../packages/core/session), [`invariants`](../packages/util/timeout) |
+| [`code-runtime-worker`](../packages/sandbox/sandbox-local) | `code-runtime` | [`code-runtime`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`session`](../packages/sandbox/sandbox), [`timeout`](../packages/session/session-persistence) |
+| [`sandbox-local`](../packages/util/brand) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/core/session), [`sandbox`](../packages/util/timeout) |
+| [`session-projection`](../packages/session/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
+| [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`pwsh-local`](../packages/bash/pwsh-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
+| [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
+| [`skill-local`](../packages/skill/skill-local) | `skill` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`skill`](../packages/skill/skill) |
+| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
+| [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
+| [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`session-persistence-jsonl`](../packages/support/llm-replay) | `session-persistence` | [`invariants`](../packages/compact/compact), [`session`](../packages/support/invariants), [`session-persistence`](../packages/llm/llm) |
+| [`session-persistence-sqlite`](../packages/core/session) | `session-persistence` | [`invariants`](../packages/support/loader-smoke), [`session`](../packages/core/agent), [`session-persistence`](../packages/support/invariants) |
+| [`session-title`](../packages/llm/llm) | `session-title` | [`brand`](../packages/core/session), [`invariants`](../packages/bundle/headless), [`llm`](../packages/core/agent), [`session`](../packages/host/apiproxy), [`session-projection`](../packages/host/webserver) |
+| [`llm-replay`](../packages/support/invariants) | `support` | [`compact`](../packages/core/session), [`invariants`](../packages/client/ui-layout), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-slots) |
+| [`loader-smoke`](../packages/client/ui-theme) | `support` | [`agent`](../packages/support/invariants), [`invariants`](../packages/context/time-context), [`llm`](../packages/core/agent), [`session`](../packages/support/invariants) |
+| [`commands`](../packages/core/session) | `ui` | [`agent`](../packages/context/tmux-context), [`brand`](../packages/core/agent), [`invariants`](../packages/bash/bash), [`scope`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`user-approval`](../packages/e2b/fs-e2b) | `ui` | [`agent`](../packages/e2b/e2b), [`brand`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/host/directory-picker-browse), [`scope`](../packages/client/locale), [`session`](../packages/client/runtime), [`system-prompt`](../packages/client/ui-primitives) |
+| [`user-interaction`](../packages/client/ui-slots) | `ui` | [`agent`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants), [`llm`](../packages/host/directory-picker-native) |
+| [`headless`](../packages/client/runtime) | `bundle` | [`agent`](../packages/client/ui-slots), [`host-apiproxy`](../packages/client/ui-workspace), [`host-webserver`](../packages/support/invariants), [`invariants`](../packages/interaction/commands), [`session`](../packages/core/agent) |
+| [`client-ui-layout`](../packages/util/brand) | `client` | [`client-runtime`](../packages/support/invariants), [`client-ui-slots`](../packages/core/scope), [`client-ui-theme`](../packages/core/session), [`invariants`](../packages/interaction/user-approval) |
+| [`time-context`](../packages/core/agent) | `context` | [`agent`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/llm/llm) |
+| [`tmux-context`](../packages/core/scope) | `context` | [`agent`](../packages/core/session), [`bash`](../packages/core/system-prompt), [`invariants`](../packages/interaction/user-interaction), [`session`](../packages/core/agent) |
+| [`fs-e2b`](../packages/support/invariants) | `e2b` | [`e2b`](../packages/llm/llm), [`fs`](../packages/lsp/lsp-local), [`invariants`](../packages/util/brand) |
+| [`host-directory-picker-browse`](../packages/fs/fs) | `host` | [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/llm/llm), [`client-ui-primitives`](../packages/lsp/lsp), [`client-ui-slots`](../packages/subprocess/subprocess), [`client-ui-workspace`](../packages/util/timeout), [`invariants`](../packages/pty/pty) |
+| [`host-directory-picker-native`](../packages/core/agent) | `host` | [`client-runtime`](../packages/util/brand), [`client-ui-slots`](../packages/support/invariants), [`client-ui-workspace`](../packages/sandbox/sandbox-policy), [`invariants`](../packages/core/agent) |
+| [`lsp-local`](../packages/support/invariants) | `lsp` | [`brand`](../packages/sandbox/sandbox), [`fs`](../packages/core/session), [`invariants`](../packages/core/system-prompt), [`llm`](../packages/scaffold/scripts), [`lsp`](../packages/boot/app-boot), [`subprocess`](../packages/support/invariants), [`timeout`](../packages/session/session-persistence-jsonl) |
+| [`pty`](../packages/support/invariants) | `pty` | [`agent`](../packages/core/session), [`brand`](../packages/session/session-persistence), [`invariants`](../packages/session/session-persistence-sqlite) |
+| [`sandbox-policy`](../packages/support/invariants) | `sandbox` | [`agent`](../packages/core/session), [`invariants`](../packages/session/session-persistence), [`sandbox`](../packages/session/session-projection-cache), [`session`](../packages/support/invariants), [`system-prompt`](../packages/core/session) |
+| [`scripts`](../packages/session/session-persistence) | `sdk` | [`app-boot`](../packages/session/session-projection), [`invariants`](../packages/storage/storage-domain) |
+| [`session-projection-cache`](../packages/session/session-telemetry) | `session-projection` | [`invariants`](../packages/core/agent), [`session`](../packages/support/invariants), [`session-persistence`](../packages/core/session), [`session-projection`](../packages/session/session-title), [`storage-domain`](../packages/util/brand) |
+| [`tasks`](../packages/support/invariants) | `tasks` | [`agent`](../packages/llm/llm), [`brand`](../packages/core/session), [`invariants`](../packages/session/session-projection), [`session`](../packages/tasks/tasks) |
+| [`session-telemetry`](../packages/core/agent) | `telemetry` | [`agent`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`workspace`](../packages/workspace/workspace) | `workspace` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage`](../packages/storage/storage), [`storage-domain`](../packages/storage/storage-domain) |
+| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval) |
+| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
+| [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
+| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
+| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
+| [`session-title-llm`](../packages/acp/acp) | `session-title` | [`invariants`](../packages/core/agent), [`llm`](../packages/support/invariants), [`session`](../packages/core/session), [`session-title`](../packages/interaction/user-approval), [`timeout`](../packages/api/remotes) |
+| [`acp`](../packages/core/agent) | `acp` | [`agent`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/session/session-persistence) |
+| [`permission`](../packages/typert/registry) | `ui` | [`bash`](../packages/client/ui-conversation), [`commands`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`sandbox`](../packages/client/ui-primitives), [`sandbox-policy`](../packages/client/ui-slash), [`session`](../packages/client/ui-slots), [`session-projection`](../packages/support/invariants), [`settings`](../packages/llm/token-meter), [`user-approval`](../packages/feedback/command-feedback) |
+| [`api-remotes`](../packages/interaction/commands) | `api` | [`agent`](../packages/support/invariants), [`goal`](../packages/core/session), [`invariants`](../packages/host/directory-picker-auto), [`session`](../packages/host/directory-picker-browse), [`session-persistence`](../packages/host/directory-picker-native), [`typert-registry`](../packages/host/webserver) |
+| [`client-ui-conversation`](../packages/support/invariants) | `client` | [`client-locale`](../packages/interaction/permission), [`client-runtime`](../packages/bash/bash), [`client-ui-primitives`](../packages/interaction/commands), [`client-ui-slash`](../packages/support/invariants), [`client-ui-slots`](../packages/sandbox/sandbox), [`invariants`](../packages/sandbox/sandbox-policy), [`token-meter`](../packages/core/session) |
+| [`command-feedback`](../packages/session/session-projection) | `feedback` | [`commands`](../packages/settings/settings), [`invariants`](../packages/interaction/user-approval), [`session`](../packages/pty/pty-local) |
+| [`host-directory-picker-auto`](../packages/core/agent) | `host` | [`host-directory-picker-browse`](../packages/support/invariants), [`host-directory-picker-native`](../packages/pty/pty), [`host-webserver`](../packages/sandbox/sandbox), [`invariants`](../packages/sandbox/sandbox-policy) |
+| [`pty-local`](../packages/core/session) | `pty` | [`agent`](../packages/subprocess/subprocess), [`invariants`](../packages/session/session-title-llm), [`pty`](../packages/support/invariants), [`sandbox`](../packages/llm/llm), [`sandbox-policy`](../packages/core/session), [`session`](../packages/session/session-title), [`subprocess`](../packages/util/timeout) |
+| [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
+| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
+| [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
+| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
+| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
+| [`timeout-policy`](../packages/todo/tool-todo) | `timeout` | [`invariants`](../packages/core/agent), [`llm`](../packages/support/invariants), [`timeout`](../packages/core/session), [`tools`](../packages/session/session-projection) |
+| [`tool-todo`](../packages/core/tools) | `todo` | [`agent`](../packages/plan/plan-mode), [`invariants`](../packages/core/agent), [`session`](../packages/interaction/commands), [`session-projection`](../packages/support/invariants), [`tools`](../packages/llm/llm) |
+| [`plan-mode`](../packages/core/session) | `plan` | [`agent`](../packages/session/session-projection), [`commands`](../packages/core/system-prompt), [`invariants`](../packages/core/tools), [`llm`](../packages/interaction/user-interaction), [`session`](../packages/hooks/hooks-codex), [`session-projection`](../packages/core/agent), [`system-prompt`](../packages/hooks/hook-protocol), [`tools`](../packages/support/invariants), [`user-interaction`](../packages/llm/llm) |
+| [`tool-cordis`](../packages/core/session) | `cordis` | [`invariants`](../packages/session/session-persistence), [`scope`](../packages/core/tools), [`tools`](../packages/session-query/session-query-sqlite) |
+| [`hooks-codex`](../packages/support/invariants) | `hooks` | [`agent`](../packages/core/session), [`hook-protocol`](../packages/session/session-persistence), [`invariants`](../packages/session-query/session-query), [`llm`](../packages/session-query/tool-session-query), [`session`](../packages/support/invariants), [`session-persistence`](../packages/llm/llm), [`tools`](../packages/core/session) |
+| [`session-checkpoint-policy`](../packages/session-query/session-query) | `session-persistence` | [`agent`](../packages/core/system-prompt), [`invariants`](../packages/util/timeout), [`llm`](../packages/core/tools), [`session`](../packages/support/agent-loop-testkit), [`session-persistence`](../packages/core/agent), [`tools`](../packages/support/invariants) |
+| [`session-query-sqlite`](../packages/llm/llm) | `session-query` | [`invariants`](../packages/core/session), [`session`](../packages/core/system-prompt), [`session-persistence`](../packages/core/tools), [`session-query`](../packages/client/ui-command) |
+| [`tool-session-query`](../packages/client/connection) | `session-query` | [`invariants`](../packages/client/locale), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-conversation), [`session-query`](../packages/client/ui-primitives), [`system-prompt`](../packages/client/ui-slash), [`timeout`](../packages/client/ui-slots), [`tools`](../packages/support/invariants) |
+| [`session-title-all-messages-llm`](../packages/client/ui-deliverables) | `session-title` | [`invariants`](../packages/client/locale), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-conversation), [`session-title`](../packages/client/ui-slots), [`session-title-llm`](../packages/support/invariants) |
+| [`session-title-first-message-llm`](../packages/client/ui-goal) | `session-title` | [`invariants`](../packages/api/remotes), [`llm`](../packages/client/locale), [`session`](../packages/client/runtime), [`session-title`](../packages/client/ui-conversation), [`session-title-llm`](../packages/client/ui-primitives) |
+| [`agent-loop-testkit`](../packages/client/ui-slots) | `support` | [`agent`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/client/ui-tool), [`session`](../packages/client/locale), [`system-prompt`](../packages/client/runtime), [`tools`](../packages/client/ui-conversation) |
+| [`tool-ask-user`](../packages/client/ui-primitives) | `ui` | [`agent`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`tools`](../packages/context/session-reference), [`user-interaction`](../packages/core/agent) |
+| [`client-ui-command`](../packages/compact/compact) | `client` | [`client-connection`](../packages/support/invariants), [`client-locale`](../packages/llm/llm), [`client-runtime`](../packages/util/retention), [`client-ui-conversation`](../packages/core/session), [`client-ui-primitives`](../packages/session-query/session-query), [`client-ui-slash`](../packages/context/workspace-context), [`client-ui-slots`](../packages/core/agent), [`invariants`](../packages/fs/fs) |
+| [`client-ui-deliverables`](../packages/support/invariants) | `client` | [`client-locale`](../packages/llm/llm), [`client-runtime`](../packages/util/paths), [`client-ui-conversation`](../packages/core/session), [`client-ui-slots`](../packages/core/tools), [`invariants`](../packages/guard/repeat-tool-guard) |
+| [`client-ui-goal`](../packages/core/agent) | `client` | [`api-remotes`](../packages/support/invariants), [`client-locale`](../packages/core/tools), [`client-runtime`](../packages/guard/timeout-policy), [`client-ui-conversation`](../packages/support/invariants), [`client-ui-primitives`](../packages/llm/llm), [`client-ui-slots`](../packages/util/timeout), [`goal`](../packages/core/tools), [`invariants`](../packages/interaction/tool-ask-user) |
+| [`client-ui-tool`](../packages/core/agent) | `client` | [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/core/tools), [`client-ui-conversation`](../packages/interaction/user-interaction), [`client-ui-primitives`](../packages/lsp/tool-lsp), [`client-ui-slots`](../packages/support/invariants), [`invariants`](../packages/llm/llm) |
+| [`session-reference`](../packages/lsp/lsp) | `context` | [`agent`](../packages/core/system-prompt), [`compact`](../packages/util/timeout), [`invariants`](../packages/core/tools), [`llm`](../packages/mcp/mcp-client), [`retention`](../packages/support/invariants), [`session`](../packages/llm/llm), [`session-query`](../packages/subprocess/subprocess) |
+| [`workspace-context`](../packages/core/tools) | `context` | [`agent`](../packages/pty/tool-bash-persistent), [`fs`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/pty/pty), [`paths`](../packages/util/timeout), [`session`](../packages/core/tools), [`tools`](../packages/pty/tool-pty) |
+| [`repeat-tool-guard`](../packages/core/agent) | `guard` | [`agent`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`tools`](../packages/pty/pty) |
+| [`tool-lsp`](../packages/util/retention) | `lsp` | [`invariants`](../packages/core/system-prompt), [`llm`](../packages/tasks/tasks), [`lsp`](../packages/core/tools), [`system-prompt`](../packages/self-modification/tool-cordis), [`timeout`](../packages/support/invariants), [`tools`](../packages/core/scope) |
+| [`mcp-client`](../packages/core/tools) | `mcp` | [`invariants`](../packages/session/session-checkpoint-policy), [`llm`](../packages/core/agent), [`subprocess`](../packages/support/invariants), [`tools`](../packages/llm/llm) |
+| [`tool-bash-persistent`](../packages/core/session) | `pty` | [`agent`](../packages/session/session-persistence), [`invariants`](../packages/core/tools), [`pty`](../packages/session/session-telemetry-otel), [`timeout`](../packages/util/brand), [`tools`](../packages/feedback/command-feedback) |
+| [`tool-pty`](../packages/support/invariants) | `pty` | [`agent`](../packages/llm/llm), [`invariants`](../packages/util/paths), [`llm`](../packages/core/session), [`pty`](../packages/session/session-telemetry), [`retention`](../packages/session/session-title-all-messages-llm), [`system-prompt`](../packages/support/invariants), [`tasks`](../packages/llm/llm), [`tools`](../packages/core/session) |
+| [`tool-tasks`](../packages/session/session-title) | `tasks` | [`agent`](../packages/session/session-title-llm), [`invariants`](../packages/session/session-title-first-message-llm), [`llm`](../packages/support/invariants), [`retention`](../packages/llm/llm), [`system-prompt`](../packages/core/session), [`tasks`](../packages/session/session-title), [`tools`](../packages/session/session-title-llm) |
+| [`session-telemetry-otel`](../packages/tasks/tool-tasks) | `telemetry` | [`brand`](../packages/core/agent), [`command-feedback`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`llm`](../packages/util/retention), [`paths`](../packages/core/system-prompt), [`session`](../packages/tasks/tasks), [`session-telemetry`](../packages/core/tools) |
+| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
+| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`repository-plugin`](../packages/hooks/hooks-claude) | `cordis` | [`invariants`](../packages/core/agent), [`mcp-client`](../packages/hooks/hook-protocol), [`paths`](../packages/support/invariants), [`skill-local`](../packages/llm/llm) |
+| [`hooks-claude`](../packages/core/session) | `hooks` | [`agent`](../packages/session/session-persistence), [`hook-protocol`](../packages/subagent/subagent), [`invariants`](../packages/core/tools), [`llm`](../packages/bundle/web-app), [`session`](../packages/bash/bash-env), [`session-persistence`](../packages/support/invariants), [`subagent`](../packages/core/system-prompt), [`tools`](../packages/client/ui-model) |
+| [`web-app`](../packages/client/connection) | `bundle` | [`bash-env`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`system-prompt`](../packages/client/ui-command) |
+| [`client-ui-model`](../packages/client/ui-conversation) | `client` | [`client-connection`](../packages/client/ui-primitives), [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/ui-slots), [`client-ui-command`](../packages/support/invariants), [`client-ui-conversation`](../packages/client/ui-permission), [`client-ui-primitives`](../packages/client/connection), [`client-ui-slash`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`invariants`](../packages/client/schema-form) |
+| [`client-ui-permission`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/ui-primitives), [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/ui-slots), [`client-schema-form`](../packages/support/invariants), [`client-ui-command`](../packages/interaction/permission), [`client-ui-primitives`](../packages/client/ui-plan), [`client-ui-slash`](../packages/client/connection), [`client-ui-slots`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`permission`](../packages/client/ui-conversation) |
+| [`client-ui-plan`](../packages/client/ui-primitives) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/plan/plan-mode), [`client-ui-conversation`](../packages/client/ui-skill), [`client-ui-primitives`](../packages/client/connection), [`client-ui-slots`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`plan-mode`](../packages/client/ui-primitives) |
+| [`client-ui-skill`](../packages/client/ui-slash) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/client/ui-tool), [`client-runtime`](../packages/support/invariants), [`client-ui-primitives`](../packages/client/ui-subagent), [`client-ui-slash`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`client-ui-tool`](../packages/client/ui-conversation), [`invariants`](../packages/client/ui-primitives) |
+| [`client-ui-subagent`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/ui-slots), [`client-runtime`](../packages/support/invariants), [`client-ui-conversation`](../packages/subagent/subagent), [`client-ui-primitives`](../packages/llm/token-meter), [`client-ui-slash`](../packages/scaffold/protocol), [`client-ui-slots`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`subagent`](../packages/core/session), [`token-meter`](../packages/subagent/subagent) |
+| [`sdk-protocol`](../packages/self-modification/repository-plugin) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/mcp/mcp-client), [`session`](../packages/util/paths), [`subagent`](../packages/skill/skill-local) |
+| [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`jsonrpc`](../packages/examples/agent-spine-demo) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/core/agent-loop), [`llm`](../packages/bash/bash-env), [`llm-deepseek`](../packages/goal/goal), [`scope`](../packages/goal/goal-session), [`sdk-protocol`](../packages/support/invariants), [`session`](../packages/llm/llm), [`subagent`](../packages/llm/llm-retry) |
+| [`agent-spine-demo`](../packages/util/paths) | `examples` | [`agent`](../packages/core/scope), [`agent-loop`](../packages/core/session), [`bash-env`](../packages/session/session-title), [`goal`](../packages/skill/skill), [`goal-session`](../packages/skill/skill-local), [`invariants`](../packages/core/system-prompt), [`llm`](../packages/tasks/tasks-local), [`llm-retry`](../packages/bash/tool-bash), [`paths`](../packages/goal/tool-goal), [`scope`](../packages/skill/tool-skill), [`session`](../packages/tasks/tool-tasks), [`session-title`](../packages/core/tools), [`skill`](../packages/context/workspace-context), [`skill-local`](../packages/scaffold/server), [`system-prompt`](../packages/core/agent), [`tasks-local`](../packages/support/invariants), [`tool-bash`](../packages/llm/llm), [`tool-goal`](../packages/llm/llm-deepseek), [`tool-skill`](../packages/core/scope), [`tool-tasks`](../packages/scaffold/protocol), [`tools`](../packages/core/session), [`workspace-context`](../packages/subagent/subagent) |
+| [`sdk-client`](../packages/scaffold/client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
+| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
new file mode 100644
index 0000000000..49f2c2a45e
--- /dev/null
+++ b/docs/persistence-catalog.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 docs/persistence-catalog.md
+persistence-catalog.md: 04c3a492fe837f7acc102901a289bf74f0cecf3f
+persistence-catalog.zh.md: 3f75cb55e2771b27e494aca9ea81ffeba3e69064
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
new file mode 100644
index 0000000000..3f75cb55e2
--- /dev/null
+++ b/docs/persistence-catalog.zh.md
@@ -0,0 +1,775 @@
+<!-- 英文源文件由 scripts/gen-persistence-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-persistence-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/persistence-catalog.md` 重新记录配对。 -->
+
+# 会话持久化事件目录
+
+[English](persistence-catalog.md) | 中文
+
+会话持久事件日志中可能出现的所有事件类型：完整持久化的 `SessionEvent` 信封，以及可通过合并扩展的 `SessionEventMap` 中的每个成员，包括 `@deepseek-ai/dsh-session` 所属的词汇和本仓库中每个插件的声明合并，并附有源 JSDoc、完整 payload 声明、surface 标记和声明位置。本文档是 [session.md](subsystems/session.md)（surface 排序与 `deriveMessages()` 投影）、[persistence.md](subsystems/persistence.md)（如何让日志持久化）和 [session.md](subsystems/session.md#cordis-surface) 中生成区域（实时总线接线；日志事件**不是** cordis 事件，它通过唯一一次 `session/event` emit 到达监听器）的补充。
+
+英文源文件根据源码生成（`scripts/gen-persistence-catalog.ts`），并由 `pnpm run verify-persistence-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc，只移除其所在接口／模块带来的缩进，并使用 `ts persistence-catalog` 围栏（`doc-typecheck` 会跳过这些围栏，因为声明引用了其所属模块中的类型）。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。
+
+以下信封声明组合了每个事件的 `type`、单调递增的 `seq`、以 epoch 毫秒表示的 `time`、`data`，以及条件字段 `surfaceOp`／`sourceEventSeqs`。**surface** 表示 `SurfaceEventType` 成员：它会生成一条 LLM（大语言模型）消息，并声明该事件如何加入 surface 列表。**log-only** 表示其他所有事件：这类记录可持久化、可回放，但不参与派生历史。每个 payload 均可进行 JSON 序列化（在 `Session.append` 处强制执行），整个格式固定为 `SESSION_FORMAT_VERSION = 0`：这是预发布格式，不暗示任何兼容性（参见[版本立场](subsystems/persistence.md)）。范围仅限本仓库中的包；下游插件可以继续合并其他事件类型，而这些类型按设计不属于本目录。
+
+## 事件信封
+
+```ts persistence-catalog
+/** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */
+export type SessionEventType = keyof SessionEventMap
+
+/**
+ * The subset of {@link SessionEventType} values whose events produce LLM
+ * messages and are eligible to appear on the ordered surface. Only these
+ * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}.
+ */
+export type SurfaceEventType =
+  | 'user/message'
+  | 'assistant/message'
+  | 'tool/result'
+
+/**
+ * How a session event entered the ordered surface. Only valid on
+ * {@link SurfaceEventType} events.
+ *
+ * - `'append'`: added to the tail — normal path for user/assistant/tool
+ *   messages.
+ * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
+ *   (inclusive) through `end` (inclusive) with this node. Both must exist as
+ *   surface nodes in the current surface. `start === end` replaces a single
+ *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
+ *   shadowed surface node. Used by compaction and possible other manipulations.
+ */
+export type SurfaceOp =
+  | 'append'
+  | { op: 'replace'; start: number; end: number }
+
+/**
+ * One immutable entry in the session log.
+ *
+ * A proper discriminated union over `type` (not independent `type`/`data`
+ * unions), so `switch (event.type)` narrows `event.data` without casts.
+ *
+ * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
+ * they only exist on {@link SurfaceEventType} variants (`user/message`,
+ * `assistant/message`, `tool/result`).
+ * Non-surface events (boundary markers, chunks, usage, errors) never carry
+ * surface metadata — the compiler enforces this at `Session.append()`
+ * call sites.
+ */
+export type SessionEvent<T extends SessionEventType = SessionEventType> = {
+  [K in SessionEventType]: {
+    type: K
+    /** Monotonic sequence number within the session. */
+    seq: number
+    /** Unix epoch milliseconds. */
+    time: number
+    data: SessionEventMap[K]
+  } & (K extends SurfaceEventType ? {
+    /**
+     * Seq numbers of events that are provenance sources of this event
+     * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
+     * or the surface nodes shadowed by a compaction replace node). An
+     * `assistant/message` may carry a present empty array for a known empty
+     * provider stream; omission means unrecorded provenance.
+     */
+    sourceEventSeqs?: number[]
+    /** How this event entered the surface; absent for non-surface events. */
+    surfaceOp?: SurfaceOp
+  } : object)
+}[T]
+```
+
+来源：[`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:343`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:375`](../packages/core/session/src/types.ts)
+
+## 事件
+
+### `agent/*`
+
+#### `agent/inbox/spliced` — log-only
+
+```ts persistence-catalog
+/**
+ * One normalized mutation of an agent's durable pending-message lists.
+ * Live dispatch precedes projection mutation, so synchronous observers may
+ * read the pre-splice inbox to recover the removed messages.
+ */
+'agent/inbox/spliced': {
+  target: InboxTarget
+  start: number
+  removedCount?: number
+  inserted: UserMessage[]
+  outcome?: 'canceled'
+}
+```
+
+来源：[`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/types.ts)
+
+### `approval/*`
+
+#### `approval/asked` — log-only
+
+```ts persistence-catalog
+/**
+ * An approval question was put to the answerer chain — log-only audit
+ * (like `hook/*`; NOT a surface event, carries no `surfaceOp`). `id` pairs
+ * it with the `approval/decided` that always follows; `toolName` is the
+ * tool the question is about, `callId` the exact tool call when the asker
+ * had one, `reason` the asker's human-readable explanation (e.g. a hook's
+ * permission-decision reason).
+ */
+'approval/asked': {
+  id: ApprovalRequestId
+  toolName: string
+  callId?: CallId
+  reason?: string
+}
+```
+
+类型：[CallId](subsystems/core.md)
+
+来源：[`packages/interaction/user-approval/src/index.ts:44`](../packages/interaction/user-approval/src/index.ts)
+
+#### `approval/decided` — log-only
+
+```ts persistence-catalog
+/**
+ * The outcome of a prior `approval/asked` (same `id`) — log-only audit.
+ * Exactly one per ask, appended when the outcome is known: a decision, a
+ * cancellation, or the fail-closed `'unavailable'`.
+ */
+'approval/decided': {
+  id: ApprovalRequestId
+  outcome: ApprovalOutcome
+}
+```
+
+来源：[`packages/interaction/user-approval/src/index.ts:55`](../packages/interaction/user-approval/src/index.ts)
+
+#### `approval/policy` — log-only
+
+```ts persistence-catalog
+/**
+ * The session's approval policy was switched — log-only, durable,
+ * replayable, never in the model transcript (the model learns the policy
+ * from the runtime-context snapshot and live switch notices). The LAST
+ * such event is the session's override ({@link effectiveApprovalPolicy}).
+ * `source: 'delegation'` marks an override seeded into a child; an absent
+ * source is a runtime switch.
+ */
+'approval/policy': {
+  policy: ApprovalPolicy
+  /** Marks an override seeded into a child at delegation. */
+  source?: 'delegation'
+}
+```
+
+来源：[`packages/interaction/user-approval/src/index.ts:67`](../packages/interaction/user-approval/src/index.ts)
+
+### `assistant/*`
+
+#### `assistant/chunk` — log-only
+
+```ts persistence-catalog
+/** Raw stream chunk — token-level replay fidelity. */
+'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
+```
+
+类型：[StreamChunk](subsystems/llm-streaming.md)
+
+来源：[`packages/core/session/src/types.ts:238`](../packages/core/session/src/types.ts)
+
+#### `assistant/message` — surface
+
+```ts persistence-catalog
+/**
+ * Assembled assistant message for one step (derived history uses this).
+ * Carries the step's `usage` when the adapter reported token accounting, so
+ * the model output and its accounting travel together (there is no separate
+ * usage record). `usage` is absent when the adapter reported none.
+ */
+'assistant/message': { turn: number; step: number; message: AssistantMessage; usage?: TokenUsage }
+```
+
+类型：[TokenUsage](subsystems/llm-streaming.md)
+
+来源：[`packages/core/session/src/types.ts:245`](../packages/core/session/src/types.ts)
+
+### `command/*`
+
+#### `command/done` — log-only
+
+```ts persistence-catalog
+/**
+ * The paired command settled. `kind`/`text` carry the handler's verbatim
+ * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
+ * rendered failure). A successful command may identify the earlier
+ * authoritative domain event for a richer client-computed presentation.
+ */
+'command/done': {
+  commandId: CommandId
+  kind: 'success' | 'error'
+  text?: string
+  sourceEventSeq?: number
+}
+```
+
+来源：[`packages/interaction/commands/src/index.ts:151`](../packages/interaction/commands/src/index.ts)
+
+#### `command/run` — log-only
+
+```ts persistence-catalog
+/**
+ * A resolved slash command entered its handler. Log-only (never model
+ * surface); paired with `command/done` by `commandId`, mirroring the
+ * `tool/call`↔`tool/result` pairing. The payload is structured — `name`
+ * and `args` are `parseCommand`'s own split (name and verbatim rawInput,
+ * separator whitespace included), so a consumer (a projection unit
+ * folding its own command records, a rich command card) never re-parses
+ * a line. `args` is absent when the definition sets `recordInput: false`
+ * because an authoritative domain event owns the input payload.
+ */
+'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
+```
+
+来源：[`packages/interaction/commands/src/index.ts:144`](../packages/interaction/commands/src/index.ts)
+
+### `compact/*`
+
+#### `compact/end` — log-only
+
+```ts persistence-catalog
+/**
+ * Marks the end of a compaction — log-only, releases the lock. Its owner
+ * matches `compact/start`; `error` records an unsuccessful attempt.
+ */
+'compact/end': { turn: number | null; error?: string }
+```
+
+来源：[`packages/compact/compact/src/types.ts:65`](../packages/compact/compact/src/types.ts)
+
+#### `compact/prune` — log-only
+
+```ts persistence-catalog
+/**
+ * Shadow price of one model-free prune replacement — log-only, no
+ * surfaceOp. The shared shadow-price protocol: a surface `replace` event
+ * is priced by the metering event immediately before it (`compact/summary`
+ * for a summarizing compaction, this event for a prune), which states the
+ * heuristic token price of the exact replaced range so a pure consumer
+ * can subtract it without retaining per-node prices. The replacement MUST
+ * be appended synchronously right after this event.
+ */
+'compact/prune': {
+  /** The replaced range's first and last surface-node seqs (a surface-position span, like {@link CompactionResult.shadowedRange}). */
+  shadowedRange: { start: number; end: number }
+  /** The seqs of all shadowed surface nodes, in surface order. */
+  shadowedSeqs: number[]
+  /** Heuristic price of the shadowed content under the token-meter's fixed estimator. */
+  shadowedTokenCount: number
+}
+```
+
+来源：[`packages/compact/compact/src/types.ts:75`](../packages/compact/compact/src/types.ts)
+
+#### `compact/start` — log-only
+
+```ts persistence-catalog
+/**
+ * Marks the start of a compaction — log-only, holds the lock until
+ * `compact/end`. A numbered owner is strictly enclosed by that open turn;
+ * `null` identifies a standalone manual transaction between turns.
+ */
+'compact/start': { turn: number | null }
+```
+
+来源：[`packages/compact/compact/src/types.ts:19`](../packages/compact/compact/src/types.ts)
+
+#### `compact/summary` — log-only
+
+```ts persistence-catalog
+/**
+ * Provenance record of a completed summarization — log-only, no surfaceOp.
+ * The summary content is in `data.summary`; the actual surface replacement
+ * is performed by the immediately following `user/message` event that
+ * shadows the compacted range. That adjacency is contractual — the
+ * shadowed pricing fields are the replacement's shadow price, so a
+ * consumer may pair a replacement with the metering event directly
+ * before it (`compact/prune` documents the shared protocol).
+ */
+'compact/summary': {
+  summary: ContentBlock[]
+  shadowedRange: { start: number; end: number }
+  shadowedSeqs: number[]
+  shadowedTokenCount: number
+  /** The provider route that wrote the summary. */
+  provider: string
+  /**
+   * The model that wrote the summary — the summarize call's envelope,
+   * reported by the backend that made the call, logged so the one-shot
+   * request is reconstructable from log + code and "which model wrote
+   * this summary" has a durable answer (the reconstructability Agent Note).
+   */
+  model: string
+  /** The generation cap the summarize call sent, when one applied. */
+  maxTokens?: number
+  /** Provider-reported token usage for the summarization request, when emitted. */
+  usage?: TokenUsage
+} & (
+  | {
+    /** Complete provider output before the backend's safe summary projection. */
+    rawOutput: ContentBlock[]
+    /** Identifies exactly one call through this context's `ctx.llm.stream()`. */
+    llmStreamCall: true
+  }
+  | {
+    /** Optional complete output from an unmarked template, remote, or other summarizer. */
+    rawOutput?: ContentBlock[]
+    /** An unmarked summary does not identify a call through this context's LLM seam. */
+    llmStreamCall?: never
+  }
+)
+```
+
+类型：[ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
+
+来源：[`packages/compact/compact/src/types.ts:29`](../packages/compact/compact/src/types.ts)
+
+### `feedback/*`
+
+#### `feedback/record` — log-only
+
+```ts persistence-catalog
+/**
+ * One recorded human remark about this session. Log-only and independent
+ * of its trigger; it never enters the model surface or derived history.
+ */
+'feedback/record': { text: string }
+```
+
+来源：[`packages/feedback/command-feedback/src/index.ts:24`](../packages/feedback/command-feedback/src/index.ts)
+
+### `goal/*`
+
+#### `goal/change` — log-only
+
+```ts persistence-catalog
+/**
+ * Complete post-mutation goal state or clear tombstone.
+ */
+'goal/change': GoalChangeMeta
+```
+
+来源：[`packages/goal/goal/src/domain.ts:66`](../packages/goal/goal/src/domain.ts)
+
+### `hook/*`
+
+#### `hook/invoked` — log-only
+
+```ts persistence-catalog
+/**
+ * A hook command was invoked at a hook point — log-only provenance (like
+ * `compact/*`; NOT a {@link SurfaceEventType}, carries no `surfaceOp`).
+ * `dialect` is the bridge that ran it (`claude`/`codex`), `point`
+ * the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group
+ * pattern that selected it (absent for match-all), `handlerId` a stable id
+ * for the command (so an invoked/result pair correlates). `turn` is the open
+ * turn the invocation lives inside.
+ */
+'hook/invoked': {
+  turn: number
+  point: string
+  dialect: HookDialect
+  matcher?: string
+  handlerId: string
+}
+```
+
+来源：[`packages/hooks/hook-protocol/src/types.ts:19`](../packages/hooks/hook-protocol/src/types.ts)
+
+#### `hook/result` — log-only
+
+```ts persistence-catalog
+/**
+ * Log-only outcome paired to `hook/invoked` by `handlerId`. Decision is the
+ * parsed permission result, `stop` for `continue:false`, or `pass`; exit code
+ * may be absent, stderr is bounded, and duration is wall-clock runtime.
+ */
+'hook/result': {
+  turn: number
+  point: string
+  handlerId: string
+  decision: string
+  exitCode?: number
+  stderrSummary?: string
+  durationMs: number
+}
+```
+
+来源：[`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook-protocol/src/types.ts)
+
+### `llm/*`
+
+#### `llm/retry` — log-only
+
+```ts persistence-catalog
+/** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
+'llm/retry': {
+  turn: number
+  step: number
+  provider: string
+  mode: 'normal'
+  policyKey: string
+  retry: number
+  maxRetries: number
+  delayMs: number
+  failure: LlmFailure
+} | {
+  turn: number
+  step: number
+  provider: string
+  mode: 'always'
+  policyKey: string
+  retry: number
+  delayMs: number
+  failure: LlmFailure
+}
+```
+
+来源：[`packages/llm/llm-retry/src/index.ts:17`](../packages/llm/llm-retry/src/index.ts)
+
+### `permission/*`
+
+#### `permission/preset` — log-only
+
+```ts persistence-catalog
+/**
+ * Records the selected preset as durable, log-only user intent. The knob
+ * events follow in the same turn and control execution; this event stays
+ * out of the model transcript and lets {@link effectivePermissionPreset}
+ * preserve a selection when bundles match.
+ */
+'permission/preset': { preset: string }
+```
+
+来源：[`packages/interaction/permission/src/index.ts:50`](../packages/interaction/permission/src/index.ts)
+
+### `plan/*`
+
+#### `plan/mode` — log-only
+
+```ts persistence-catalog
+/**
+ * Whether plan mode is in force from this point on: log-only, non-surface,
+ * whole-value replace. The last `plan/mode` wins; a log with none folds to
+ * inactive through {@link foldPlanMode}.
+ */
+'plan/mode': { active: boolean }
+```
+
+来源：[`packages/plan/plan-mode/src/index.ts:52`](../packages/plan/plan-mode/src/index.ts)
+
+### `request/*`
+
+#### `request/context` — log-only
+
+```ts persistence-catalog
+/**
+ * Route metadata for the next request, logged only when the route or capacity
+ * changes. It does not participate in request reconstruction or header equality.
+ */
+'request/context': RequestContext
+```
+
+来源：[`packages/core/session/src/types.ts:281`](../packages/core/session/src/types.ts)
+
+#### `request/header` — log-only
+
+```ts persistence-catalog
+/**
+ * Full header for the next request, appended inside its step before dispatch.
+ * It is log-only; the latest snapshot reconstructs the request header.
+ */
+'request/header': { header: EpochHeader; reason: RequestHeaderReason }
+```
+
+来源：[`packages/core/session/src/types.ts:276`](../packages/core/session/src/types.ts)
+
+### `sandbox/*`
+
+#### `sandbox/mode` — log-only
+
+```ts persistence-catalog
+/**
+ * The session's sandbox mode was switched — log-only (like `approval/*`;
+ * NOT a surface event, carries no `surfaceOp`): durable and replayable,
+ * never in the model transcript. The LAST such event is the session's
+ * override ({@link effectiveSandboxMode}). `source: 'delegation'` marks
+ * an override seeded into a child; an absent source is a runtime switch.
+ */
+'sandbox/mode': {
+  mode: SandboxMode
+  /** Marks an override seeded into a child at delegation. */
+  source?: 'delegation'
+}
+```
+
+来源：[`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
+
+### `session/*`
+
+#### `session/end-seed` — log-only
+
+```ts persistence-catalog
+/**
+ * Marks the end of a constructor seed. Events before it have smaller seq
+ * values and came from the seed (resume, fork, or replay); this lifecycle
+ * produced none of them. This log-only event is the durable projection of
+ * {@link Session.firstLiveSeq}. Its payload is empty — position and `time`
+ * carry the meaning.
+ *
+ * Locate the LAST one in stored history. A seed already ending in one is not
+ * re-marked, so reopening an untouched session does not grow its log per
+ * pickup and the event need not be at the current `firstLiveSeq`.
+ *
+ * `Session`'s constructor is the only legitimate writer. The invariant
+ * companion deliberately constrains nothing here, so a plugin appending one
+ * would silently classify every live bracket before it as seed history.
+ *
+ * An owner of a standalone open/close bracket (`compact/start` …
+ * `compact/end`) reads it because seed history and live work are otherwise
+ * byte-identical: an unmatched opening marker before this event belongs to
+ * an ended lifecycle, whatever ended it. NOT a liveness signal about other
+ * writers — a concurrently live session holds its own boundary elsewhere,
+ * so tolerating concurrent writers needs a signal beyond the log.
+ */
+'session/end-seed': Record<string, never>
+```
+
+来源：[`packages/core/session/src/types.ts:304`](../packages/core/session/src/types.ts)
+
+#### `session/title` — log-only
+
+```ts persistence-catalog
+/**
+ * Latest-wins session title snapshot. Log-only: it never enters the model
+ * surface or derived history.
+ */
+'session/title': SessionTitleEventData
+```
+
+类型：[SessionTitleEventData](subsystems/session-title.md)
+
+来源：[`packages/session/session-title/src/index.ts:100`](../packages/session/session-title/src/index.ts)
+
+#### `session/title-llm-request` — log-only
+
+```ts persistence-catalog
+/** Log-only pre-dispatch record of one session-title model request. */
+'session/title-llm-request': SessionTitleLlmRequestEventData
+```
+
+类型：[SessionTitleLlmRequestEventData](subsystems/session-title.md)
+
+来源：[`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts)
+
+### `step/*`
+
+#### `step/end` — log-only
+
+```ts persistence-catalog
+/** Closes step `step` of turn `turn`. */
+'step/end': { turn: number; step: number }
+```
+
+来源：[`packages/core/session/src/types.ts:228`](../packages/core/session/src/types.ts)
+
+#### `step/start` — log-only
+
+```ts persistence-catalog
+/** Opens step `step` of turn `turn` — one model call plus the tool executions it requested. */
+'step/start': { turn: number; step: number }
+```
+
+来源：[`packages/core/session/src/types.ts:226`](../packages/core/session/src/types.ts)
+
+### `subagent/*`
+
+#### `subagent/descriptor` — log-only
+
+```ts persistence-catalog
+/**
+ * Durable identity and lifecycle mode of a session-backed subagent child,
+ * appended once by the establishing provider inside the child's initial
+ * turn, before its first request. Continuable records also carry their
+ * resumable composition. Log-only: it carries no `surfaceOp`, never enters
+ * model history, and survives compaction.
+ */
+'subagent/descriptor': SubagentDescriptorData
+```
+
+来源：[`packages/subagent/subagent/src/descriptor.ts:37`](../packages/subagent/subagent/src/descriptor.ts)
+
+### `todo/*`
+
+#### `todo/write` — log-only
+
+```ts persistence-catalog
+/** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
+'todo/write': { todos: TodoItem[] }
+```
+
+类型：[TodoItem](subsystems/session.md)
+
+来源：[`packages/core/session/src/types.ts:271`](../packages/core/session/src/types.ts)
+
+### `tool/*`
+
+#### `tool/call` — log-only
+
+```ts persistence-catalog
+/**
+ * The model requested one tool invocation: `name` with the raw `arguments`
+ * JSON string exactly as the model produced it (unparsed). `callId` pairs the
+ * call with its `tool/result`.
+ */
+'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
+```
+
+类型：[CallId](subsystems/core.md)
+
+来源：[`packages/core/session/src/types.ts:251`](../packages/core/session/src/types.ts)
+
+#### `tool/code-dispatch` — log-only
+
+```ts persistence-catalog
+/**
+ * One bridged sub-dispatch SETTLING: the pairing ids (matching the
+ * `tool/code-dispatch-start` with the same `subCallId`), the tool `name`
+ * with the same JSON-normalized `arguments`, and the sub-call's complete
+ * model-facing outcome in `tool/result`'s own vocabulary
+ * (`content` + `isError`), so UIs render a sub-call through the exact
+ * code path that renders a native call. Every started sub-call settles
+ * with exactly one of these (abort included: the aborted pipeline result
+ * is an `isError` outcome).
+ * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
+ * model context; persistence and UIs get every call. Appended inside the
+ * parent `run_code`'s execution (the bridge drains in-flight dispatches
+ * before returning), so its execution-enclosure relation holds by
+ * construction.
+ */
+'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
+```
+
+类型：[CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md)
+
+来源：[`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/code-mode.ts)
+
+#### `tool/code-dispatch-start` — log-only
+
+```ts persistence-catalog
+/**
+ * One sub-dispatch STARTING inside a `run_code` program: the parent
+ * `run_code` call id, the deterministic sub-call id (`<parent>:code:<n>`,
+ * numbered in submission order), and the tool `name` with its
+ * JSON-normalized `arguments` — the exact value dispatched, normalized
+ * BEFORE dispatch, so this append can never fail on payload shape.
+ * Appended when the scheduler actually starts the call (not at
+ * submission), so a start means the tool body pipeline was entered; a
+ * call abandoned in the queue logs nothing. Log-only: `deriveMessages()`
+ * ignores it; UIs use it for live per-sub-call running state and pair it
+ * with `tool/code-dispatch` by `subCallId` (timing = the two events'
+ * `time` fields).
+ */
+'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
+```
+
+类型：[CallId](subsystems/core.md)
+
+来源：[`packages/core/tools/src/code-mode.ts:33`](../packages/core/tools/src/code-mode.ts)
+
+#### `tool/result` — surface
+
+```ts persistence-catalog
+/**
+ * A completed tool call's model-facing result, optional internal failure
+ * identity, and optional tool-private `meta` presentation payload. `meta` is
+ * opaque to the core (the producing tool owns its shape and reads it back in
+ * `presentResult`) but MUST be JSON-serializable: `Session.append`
+ * runtime-validates all event data with `isJsonValue`, so a non-serializable
+ * `meta` is rejected at the source, and the durable log reproduces the
+ * identical card on replay. Absent
+ * unless the tool attaches one (e.g. `dsh-tool-fs` carries its result-time
+ * contextual diff here).
+ */
+'tool/result': {
+  turn: number
+  step: number
+  message: ToolResultMessage
+  error?: { name: string; code: string }
+  meta?: JsonValue
+}
+```
+
+来源：[`packages/core/session/src/types.ts:263`](../packages/core/session/src/types.ts)
+
+### `turn/*`
+
+#### `turn/end` — log-only
+
+```ts persistence-catalog
+/**
+ * Closes turn `turn` with the {@link TurnEndReason} that ended it. A turn
+ * with no entered step has no `step/start` or `step/end`. The loop does not await a
+ * flush at turn boundaries: `dsh-session-checkpoint-policy` owns the
+ * per-request durability checkpoint, and consumers that read storage after
+ * `whenIdle()` flush themselves. Success commits the turn; rejection is
+ * reported live and does not prevent later work.
+ */
+'turn/end': { turn: number; reason: TurnEndReason }
+```
+
+类型：[TurnEndReason](subsystems/session.md)
+
+来源：[`packages/core/session/src/types.ts:224`](../packages/core/session/src/types.ts)
+
+#### `turn/start` — log-only
+
+```ts persistence-catalog
+/**
+ * Opens turn `turn` before the loop claims queued input or runs pre-step.
+ * Rejection, empty input, cancellation, or failure may close it with no
+ * step; otherwise the following identified `user/message` event or batch
+ * records the messages entering the step.
+ */
+'turn/start': { turn: number }
+```
+
+来源：[`packages/core/session/src/types.ts:215`](../packages/core/session/src/types.ts)
+
+### `user/*`
+
+#### `user/message` — surface
+
+```ts persistence-catalog
+/**
+ * A user-role message on the model-visible surface: a direct human prompt
+ * (the queued message claimed for this turn), a synthetic `agent.inject()`
+ * context (file-change notices, subdir AGENTS.md, skill content, cron
+ * notifications, …), or an entered goal continuation round. All three
+ * project their `content` verbatim; `source` tells them apart.
+ */
+'user/message': UserMessage
+```
+
+来源：[`packages/core/session/src/types.ts:236`](../packages/core/session/src/types.ts)
+
+### `web/*`
+
+#### `web/deepseek-search-llm-request` — log-only
+
+```ts persistence-catalog
+/** Secret-free auxiliary DeepSeek search request recorded before dispatch. */
+'web/deepseek-search-llm-request': DeepSeekSearchLlmRequest
+```
+
+来源：[`packages/web/web-search-deepseek/src/provider.ts:83`](../packages/web/web-search-deepseek/src/provider.ts)
diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml b/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
index a32bb0e3e6..ed77fc2f2e 100644
--- a/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
+++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/postmortem/0003-web-agent-gui-feedback-loop.md
 0003-web-agent-gui-feedback-loop.md: 13d13a607babfe7f5ddfdb6773c94f973bbef0db
-0003-web-agent-gui-feedback-loop.zh.md: f80530605ef9274638c6848bf5a256f76057915c
+0003-web-agent-gui-feedback-loop.zh.md: 44d4febc30344135932aad2394b3054587feca1d
diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md b/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
index f80530605e..44d4febc30 100644
--- a/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
+++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
@@ -18,20 +18,20 @@ Web agent 修改了 GUI 源码，却不知道由哪个 URL 和进程承载当前
 
 ## 影响
 
-用户不得不连续指出三个错误：agent 把验收交还给用户；建议预览的页面一片空白；报告成功的 URL 并不是用户正在使用的页面。一个不受管理的替代服务器还持续运行到下一轮，直到用户提出质疑。
+用户不得不连续指出三个错误：agent 把验收交还给用户；建议预览的页面一片空白；报告成功的 URL 并不是用户正在使用的页面。一个不受管理的替代服务器还持续运行到下一个轮次，直到用户提出质疑。
 
 本次调查没有重启或修改只读的 3081 和 3082 试验服务。
 
 ## 时间线
 
-- 在第 2 轮中，agent 修改主题后，在序列 30939 的消息中让用户运行 `pnpm run demo:tui` 或打开一个未明确指定的 Web 应用。它没有对组装后的 Web 应用执行任何验收。
-- 在第 3 轮中，agent 读取 `apps/web/package.json`，在序列 31865 于端口 5173 上启动裸 Vite，观察到 HTTP 200 后便宣布成功。浏览器却抛出 `client-modules: window.__DSH_BOOT__ is missing or not an object`，并显示白屏。
-- 在第 4 轮中，agent 找到了完整的 `dsh web` 启动路径，重新构建 shell，在序列 34309 于端口 3334 上启动一个不受管理的进程，并且只在序列 34441 检查了这个替代服务是否返回 200 和启动 manifest。它从未探测端口 3081。
-- 在第 5 轮中，用户在序列 34556 报告 3081 已经显示新主题。直到序列 34681，agent 才检查既有进程并移除冗余服务器。
+- 在第 2 个轮次中，agent 修改主题后，在序列 30939 的消息中让用户运行 `pnpm run demo:tui` 或打开一个未明确指定的 Web 应用。它没有对组装后的 Web 应用执行任何验收。
+- 在第 3 个轮次中，agent 读取 `apps/web/package.json`，在序列 31865 于端口 5173 上启动裸 Vite，观察到 HTTP 200 后便宣布成功。浏览器却抛出 `client-modules: window.__DSH_BOOT__ is missing or not an object`，并显示白屏。
+- 在第 4 个轮次中，agent 找到了完整的 `dsh web` 启动路径，重新构建 shell，在序列 34309 于端口 3334 上启动一个不受管理的进程，并且只在序列 34441 检查了这个替代服务是否返回 200 和启动 manifest。它从未探测端口 3081。
+- 在第 5 个轮次中，用户在序列 34556 报告 3081 已经显示新主题。直到序列 34681，agent 才检查既有进程并移除冗余服务器。
 
 ## 根因
 
-Web 组合没有向模型提供当前 GUI、规范 URL 或运行模式的身份信息。会话 cwd 正确表示了用户选择的 Workspace，但模型误把这个项目边界当成了应用边界。系统也没有持久契约将 GUI 源码检出目录、构建产物、服务进程、目标 origin 和浏览器验收关联起来。
+Web 组合没有向模型提供当前 GUI、规范 URL 或运行模式的身份信息。会话 cwd 正确表示了用户选择的 Workspace，但模型误把这个项目边界当成了应用边界。系统也没有持久约定将 GUI 源码检出目录、构建产物、服务进程、目标 origin 和浏览器验收关联起来。
 
 裸 Vite 返回 HTTP 200，使错误的启动路径看似合理。`window.__DSH_BOOT__` 只由完整宿主注入，因此传输层就绪不代表应用已就绪。首个回归测试以另一种方式重复了同样的错误：超时机制终止 Vite 后，非零退出断言仍会通过。真实复现暴露了这一误报。
 
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
index b54453f3c4..8c66e9464c 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
 0004-landlock-partial-notice-misclassified-child-failures.md: ed59fa9d2b04623220a9bcd984fe6becdc619198
-0004-landlock-partial-notice-misclassified-child-failures.zh.md: 5cf3e4422a5b888553e12dfb97b8a26aad65e231
+0004-landlock-partial-notice-misclassified-child-failures.zh.md: 55b462a4fe90b5d5c98bf846cad55e1fe4d6a4b0
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
index 5cf3e4422a..55b462a4fe 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
@@ -10,7 +10,7 @@ Status: resolved
 
 ## 概述
 
-原生 launcher 契约区分两类 stderr 行。内核只能部分强制执行时，会精确打印 `landlock-run: partial enforcement (older Landlock ABI)`，然后继续执行子进程。launcher 失败则打印另一行 `landlock-run:` 诊断，在不执行子进程的情况下以 125 退出。
+原生 launcher 约定区分两类 stderr 行。内核只能部分强制执行时，会精确打印 `landlock-run: partial enforcement (older Landlock ABI)`，然后继续执行子进程。launcher 失败则打印另一行 `landlock-run:` 诊断，在不执行子进程的情况下以 125 退出。
 
 harness 用一个不区分大小写的 `landlock-run: ` 子串表示这两种情况。消费方只要发现非零退出同时携带该子串，就会归类为 runner 失败。因此，子进程的退出状态被错误地关联到 launcher 的信息性行：`false`、ripgrep 无匹配时的退出码 1、无效 pattern 的退出码 2，乃至由子进程自行选择的退出码 125，都可能在约束与执行均成功的情况下被错误归因为沙箱故障。
 
@@ -24,8 +24,8 @@ harness 用一个不区分大小写的 `landlock-run: ` 子串表示这两种情
 
 ## 时间线
 
-- 原生 launcher 契约规定：launcher 失败使用退出码 125，每次此类失败都会打印一行致命的 `landlock-run:` 诊断；成功执行子进程时则打印精确的部分强制执行通知。
-- 沙箱提供方把该契约简化为 `runnerFailureSignatures: ['landlock-run: ']`；bash 消费方将此前缀与任意非零退出组合，并报告 stderr 的第一行。
+- 原生 launcher 约定规定：launcher 失败使用退出码 125，每次此类失败都会打印一行致命的 `landlock-run:` 诊断；成功执行子进程时则打印精确的部分强制执行通知。
+- 沙箱提供方把该约定简化为 `runnerFailureSignatures: ['landlock-run: ']`；bash 消费方将此前缀与任意非零退出组合，并报告 stderr 的第一行。
 - 单元测试覆盖了无诊断的成功、拒绝诊断和致命 runner 前缀。真实 runner 测试在没有可用内核时会自行跳过，也没有强制构造「部分强制执行通知后跟非零子进程退出」的情况。
 - 一个最小 POSIX 包装脚本会打印该通知并 `exec` 其负载；它通过 `false` 与 ripgrep 无匹配场景复现了故障。
 - 结构化规则、前台与后台共享的分类逻辑和组装后的回放覆盖共同弥补了仍然存在的沙箱归因缺口。文件系统搜索通过 `ctx.subprocess` 运行打包的 ripgrep；本修复让该路径继续位于沙箱化 bash 之外。
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index caf9356ee9..e1ab1ef65b 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/core.md
 core.md: cc9cc30677b0b657492d8a5118489e8b801f3fd3
-core.zh.md: 6878300dc2cbd82d220e17d2d6f5e1009f41c48f
+core.zh.md: 60d363f9421b846ccc8096ef38861a8fdea255c0
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 6878300dc2..60d363f942 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -2,7 +2,7 @@
 
 [English](core.md) | 中文
 
-**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有 `agent`/`agent-loop` 这对包所声明的内容——agent 如何被创建与拥有，以及 `Agent` 句柄及其投递、取消与拦截契约——外加每个子系统都遵循的两个类型模式；该组的专属页面与目录其余部分见[子系统 README](README.md)。
+**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有 `agent`/`agent-loop` 这对包所声明的内容——agent 如何被创建与拥有，以及 `Agent` 句柄及其投递、取消与拦截约定——外加每个子系统都遵循的两个类型模式；该组的专属页面与目录其余部分见[子系统 README](README.md)。
 
 ## 主干逐包速览
 
@@ -14,7 +14,7 @@
 | `system-prompt/` | 提示词段落与工具 schema 组装（`ctx.systemPrompt`） | [system-prompt.md](system-prompt.md) |
 | `tools/` | 带作用域的工具注册表与受保护的执行流水线（`ctx.tools`） | [tools.md](tools.md) |
 | `agent/` | `Agent` 接口、实时注册表、发起者作用域与 `agent/*` 事件词汇（`ctx.agents`） | 本页 |
-| `agent-loop/` | 实现公开 `Agent` 契约的具体 driver（`ctx.agentLoop`） | 本页 |
+| `agent-loop/` | 实现公开 `Agent` 约定的具体 driver（`ctx.agentLoop`） | 本页 |
 | `scope/` | 注册表与循环用于构建按 agent 作用域的注册原语 | [scope.md](scope.md) |
 
 `scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是 `agent` seam 的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
@@ -50,7 +50,7 @@ interface AgentHandle {
 
 `CreateAgentOptions` 携带共享标识以及新 agent 发布前所需的一切：会话元数据（`meta`——已校验的 `cwd`、fork 谱系、seed 边界、来源分类、委派深度）、fork 用的可选 `seed` 回放前缀、按 agent 的 `AgentOptions`、仅创建期有效的取消 `signal`，以及 `setup`。`ResumeAgentOptions` 是持久标识的对应物：`resumeSessionId`、`agentOptions`、`signal` 与 `setup`。`setup` 回调（`AgentSetup`）在两个 id 都尚未发布时组装 agent 的作用域世界——凡经 `agentCtx` 注册的内容都先于 `agent/created` 与第一次提示词组装存在——并可返回一个在发布前一刻调用的同步 commit；setup 拒绝、commit 抛出或所有者 dispose 都会回滚事务，两个 id 均不发布。
 
-`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚契约见下方[生成区块](#ctxagents--agentregistry)。
+`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚约定见下方[生成区块](#ctxagents--agentregistry)。
 
 <a id="the-agent-handle"></a>
 
@@ -206,7 +206,7 @@ type AgentCancelCause =
 
 cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
 
-[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。
+[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）约定。轮次和步骤边界是持久会话事件，而不是 agent emit。
 
 <a id="initiating-agent"></a>
 
@@ -255,7 +255,7 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ## `ToolDefinition`
 
-唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
+唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的约定。
 
 其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
 
@@ -265,7 +265,7 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ### `…Map → derived-union` 模式
 
-harness 中几乎所有可扩展的和类型都遵循同一形状：一个以判别标签为键的接口（`…Map`），联合类型由 `keyof` 派生。插件通过**声明合并**添加变体——无需修改拥有该类型的包（package）。
+harness 中几乎所有可扩展的和类型都遵循同一形状：一个以判别标签为键的接口（`…Map`），联合类型由 `keyof` 派生。插件通过**声明合并**添加变体——无需修改拥有该类型的包。
 
 ```ts ignore-check
 // The pattern, schematically:
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index 7028d71f8d..7e9e057c75 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/credentials.md
 credentials.md: 0bc2224ac039addc795d3806e8c85004f2bb84a7
-credentials.zh.md: 6f5ccd1572885434257d39eb0f659fcc7371ad1d
+credentials.zh.md: f236b0b2daef85784308f10dbcfc67db84c42234
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index 6f5ccd1572..f236b0b2da 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -2,9 +2,9 @@
 
 [English](credentials.md) | 中文
 
-[dsh-credentials](../../packages/credentials/credentials) 的凭据 seam 把机密挡在配置之外：settings 分节与 `cordis.yml` 条目携带的是*引用*（环境变量名），值归 [dsh-credentials-local](../../packages/credentials/credentials-local) 这类 provider 所有，消费方每个操作解析一次引用——LLM 适配器每次模型请求解析一次，因此轮换后的凭据无需任何重启即可作用于紧随其后的下一次请求。一条 seam 级规则约束每个 provider：空的存储值在任何地方都视为不存在。
+[dsh-credentials](../../packages/credentials/credentials) 的凭据 seam 把机密挡在配置之外：settings 分节与 `cordis.yml` 条目携带的是*引用*（环境变量名），值归 [dsh-credentials-local](../../packages/credentials/credentials-local) 这类提供方所有，消费方每个操作解析一次引用——LLM（大语言模型）适配器每次模型请求解析一次，因此轮换后的凭据无需任何重启即可作用于紧随其后的下一次请求。一条 seam 级规则约束每个提供方：空的存储值在任何地方都视为不存在。
 
-Source: [`packages/credentials/credentials/src/index.ts`](../../packages/credentials/credentials/src/index.ts)
+来源：[`packages/credentials/credentials/src/index.ts`](../../packages/credentials/credentials/src/index.ts)
 
 ## 标识
 
@@ -17,7 +17,7 @@ type CredentialRef = Branded<'CredentialRef'>
 
 ## 解析
 
-`resolve(ref)` 返回值，连同供出该值、由 provider 定义的来源层；未配置期间返回 `undefined`。消费方在每个操作中重新解析，绝不跨操作缓存——这次按操作进行的读取正是热更新机制。
+`resolve(ref)` 返回值，连同提供该值、由提供方定义的来源层；未配置期间返回 `undefined`。消费方在每个操作中重新解析，绝不跨操作缓存——这种按操作进行的读取正是热更新机制。
 
 ```ts type-equiv
 /** One resolved credential value and the source layer that supplied it. */
@@ -31,7 +31,7 @@ interface ResolvedCredential {
 
 ## 描述
 
-`describe(ref)` 在绝不暴露值的前提下回应配置界面：引用当前是否可解析、来自哪一层、`set` 当前能否成功。本地 provider 把由活跃进程环境供值的引用报告为 `writable: false`——那样的写入会表面成功而解析持续返回遮蔽值，因此 seam 直接拒绝，界面也得以提前把该引用渲染为只读。
+`describe(ref)` 在绝不暴露值的前提下回应配置界面：引用当前是否可解析、来自哪一层、`set` 当前能否成功。本地提供方把由当前进程环境供值的引用报告为 `writable: false`——那样的写入会表面成功而解析持续返回遮蔽值，因此 seam 直接拒绝，界面也得以提前把该引用渲染为只读。
 
 ```ts type-equiv
 /** Source and writability facts for one reference, safe for configuration UIs — never the value. */
@@ -47,7 +47,7 @@ interface CredentialInfo {
 
 ## 变更提交
 
-`credentials/updated (ref)` 在 provider 管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+`credentials/updated (ref)` 在提供方管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境自身的变化不可观测，永不发出事件。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/lsp.i18n.yaml b/docs/subsystems/lsp.i18n.yaml
index 25b54df775..eb3a5e36ba 100644
--- a/docs/subsystems/lsp.i18n.yaml
+++ b/docs/subsystems/lsp.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 docs/core-data-structures/lsp.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/lsp.md
 lsp.md: 03d0ce2dbe246aadb6f6c9a702fa50e3e792eb09
 lsp.zh.md: d428f2b5f9568b231b0b50a13bd4a41f7ea81346
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 295e5392ca..ae2ef3a216 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/persistence.md
 persistence.md: 580ec250ebad3f2b51982f98a611268f26487321
-persistence.zh.md: 6676bf26e6eb0fb8f7dd9a94d17d4d70d1d1b271
+persistence.zh.md: 8785ca9c7dad562e6b27261920ab48c72c607121
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 6676bf26e6..8785ca9c7d 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -4,7 +4,7 @@
 
 事件日志的**持久性 seam**。[session.md](session.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.md)中逐项列举。
 
-该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一契约的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
+该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一约定的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
 
 ## flush 检查点
 
@@ -16,7 +16,7 @@
 
 修复仅适用于冷会话。对于活跃 id，`SessionPersistence.load(id)` 会等待权威内存快照完成持久化，并且只在日志平衡时返回；若活跃轮次仍未闭合，则拒绝操作，而不是添加合成的中断边界。HMR 会接管活跃前缀，而不会关闭其中正在进行的轮次。
 
-`SessionPersistence.inspect(id)` 会构造一个不可变的逻辑 Session，但不发布它，也不写入恢复内容。冷检查会在内存中配平中断的 turn，同时保持撕裂的物理尾部不变；检查已经实时存在的 Session 则借用其当前不可变快照，因此可能包含打开的 turn。使用协调器的实现会在有界 LRU 中保留这个精确的冷未发布 Session，因此重复历史读取与后续 `prepare(id)` 可复用同一次读取、解压、验证、冻结及 Session 构造。`prepare(id)` 会预留该 Session、提交待处理修复并返回可 dispose 的发布句柄；`load(id)` 使用相同机制提交修复，但不会发布 Session。该生命周期由 [Session 准备阶段决策](../../.agents/notes/implemented/architecture/2026-08-05-session-preparation.md)定义。
+`SessionPersistence.inspect(id)` 会构造一个不可变的逻辑 Session，但不发布它，也不写入恢复内容。冷检查会在内存中配平中断的轮次，同时保持撕裂的物理尾部不变；检查已经实时存在的 Session 则借用其当前不可变快照，因此可能包含打开的 turn。使用协调器的实现会在有界 LRU 中保留这个精确的冷未发布 Session，因此重复历史读取与后续 `prepare(id)` 可复用同一次读取、解压、验证、冻结及 Session 构造。`prepare(id)` 会预留该 Session、提交待处理修复并返回可 dispose 的发布句柄；`load(id)` 使用相同机制提交修复，但不会发布 Session。该生命周期由 [Session 准备阶段决策](../../.agents/notes/implemented/architecture/2026-08-05-session-preparation.md)定义。
 
 ## `SessionLocation`——可选的逐会话产物目标
 
diff --git a/docs/subsystems/scope.i18n.yaml b/docs/subsystems/scope.i18n.yaml
index aef528553d..db073233b5 100644
--- a/docs/subsystems/scope.i18n.yaml
+++ b/docs/subsystems/scope.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 docs/core-data-structures/scope.md
+#   pnpm run verify-translation-pairing --write docs/subsystems/scope.md
 scope.md: 73a697f2843293daffff85dabf4656346f7dcd04
 scope.zh.md: 06e2528eca958102110caa3a7d370e0778c0f7b2
diff --git a/docs/subsystems/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
index 5c40419366..a257e0e33e 100644
--- a/docs/subsystems/settings.i18n.yaml
+++ b/docs/subsystems/settings.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/settings.md
 settings.md: 9256bf9436d2e77093fc8c6a3728b62fc4e8d67f
-settings.zh.md: f6d662ebaf35eeb9d046353ea1087b0eb86e7068
+settings.zh.md: 720eb9c2718c1fa14a148cced806c224634dba69
diff --git a/docs/subsystems/settings.zh.md b/docs/subsystems/settings.zh.md
index f6d662ebaf..720eb9c271 100644
--- a/docs/subsystems/settings.zh.md
+++ b/docs/subsystems/settings.zh.md
@@ -2,13 +2,13 @@
 
 [English](settings.md) | 中文
 
-[dsh-settings](../../packages/settings/settings) 的用户设置 seam 持有一份按 namespace 分节的用户文档，并把每个已注册 namespace 解析为：schema 默认值，然后注册方的组合 `base`，最后用户分节。[dsh-settings-local](../../packages/settings/settings-local) 这类 provider 存储原始文档并推送外部编辑；消费插件注册 schema 后读取或观察解析值。组合配置仍留在 `cordis.yml`——namespace 只承载用户可编辑子集。
+[dsh-settings](../../packages/settings/settings) 的用户设置 seam 持有一份按 namespace 分节的用户文档，并把每个已注册 namespace 解析为：schema 默认值，然后注册方的组合 `base`，最后用户分节。[dsh-settings-local](../../packages/settings/settings-local) 这类提供方存储原始文档并推送外部编辑；消费方插件注册 schema 后读取或观察解析值。组合配置仍留在 `cordis.yml`——namespace 只承载用户可编辑子集。
 
-Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
+来源：[`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
 
 ## 标识
 
-namespace 命名用户文档中一个插件所有的分节。brand 使其不与其他跨边界 id 混用；构造时校验小写 kebab-case 形态。
+namespace 命名用户文档中一个归插件所有的分节。brand 使其不与其他跨边界 id 混用；构造时校验小写 kebab-case 形态。
 
 ```ts type-equiv
 /** Nominal id of one registered settings namespace. */
@@ -17,7 +17,7 @@ type SettingsNamespace = Branded<'SettingsNamespace'>
 
 ## 注册
 
-注册把 schemastery schema 绑定到调用方插件 fiber 上的 namespace——dispose 该 fiber 即移除 namespace 及其观察者。options 携带组合层、owner 的生效时机，以及一个可选的、用于校验 schema 表达不了的约束的钩子。
+注册把 schemastery schema 绑定到调用方插件 fiber 上的 namespace——dispose（资源释放）该 fiber 即移除 namespace 及其观察者。options 携带组合层、owner 的生效时机，以及一个可选的、用于校验 schema 表达不了的约束的钩子。
 
 ```ts type-equiv
 /** Registration options beyond the namespace schema. */
@@ -49,7 +49,7 @@ interface SettingsRegisterOptions<T> {
 }
 ```
 
-`validate` 在 schema 接纳该值之后运行，因此它看到的默认值与组合 base 与 owner 将看到的完全一致。`dsh-llm-pi-ai` 用它在写入处拒绝自己无法服务的提供方 profile，而不是先存下来、再让该 namespace 下每条路由失效。
+`validate` 在 schema 接纳该值之后运行，因此它看到的默认值和组合 base 与 owner 实际看到的完全一致。`dsh-llm-pi-ai` 用它在写入处拒绝自己无法服务的提供方 profile，而不是先存下来、再让该 namespace 下每条路由失效。
 
 `applies` 是 UI 提示而非机制：`restart` 的 owner 只是从不 watch，其值在构造期读取一次，配置界面可为待生效变更加标。
 
@@ -95,7 +95,7 @@ interface SettingsScope<T> {
 
 ## 描述符
 
-`describe()` 为配置界面序列化每个已注册 namespace：schemastery 的 `toJSON()` 信封驱动 schema 渲染的表单，解析值填充表单，分离出的 `base`/`user` 层让表单按字段是否出现在 user 层标注「用户已覆盖」。`describe({ redactSecrets: true })`——每个 wire 面都必须传入——从三层剥离 `role('secret')` 字段并枚举其 `{path, set}` 槽位，页面因此能渲染只写输入框而永远收不到机密值。
+`describe()` 为配置界面序列化每个已注册 namespace：schemastery 的 `toJSON()` 封装结构驱动 schema 渲染的表单，解析值填充表单，分离出的 `base`/`user` 层让表单按字段是否出现在 user 层标注「用户已覆盖」。`describe({ redactSecrets: true })`——每个对外传输接口都必须传入——从三层剥离 `role('secret')` 字段并枚举其 `{path, set}` slot，页面因此能渲染只写输入框而永远收不到机密值。
 
 ```ts type-equiv
 /** One registered namespace as surfaced to configuration UIs. */
@@ -154,7 +154,7 @@ interface SettingsDescribeOptions {
 
 ## 变更提交
 
-每次提交的变更——进程内写入或 provider 观察到的外部编辑——在新值成为权威值之后发出 `settings/updated (ns, next, prev, source)`，解析值深相等时绝不发出。source 标记区分两条入口路径。
+每次提交的变更——进程内写入或提供方观察到的外部编辑——在新值成为权威值之后发出 `settings/updated (ns, next, prev, source)`，解析值深相等时绝不发出。source 标记区分两条入口路径。
 
 ```ts type-equiv
 /** Origin of one committed settings change. */
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 994c04eaa5..f080915228 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/subagent.md
 subagent.md: 3bf3ac7c48bfa08be86314bb43263d4ee6198654
-subagent.zh.md: ddc3a715fbb6589dffc38f0e0c8b23bf35dddf6e
+subagent.zh.md: 65ea762fcddb0f7b4ef5ec977cc14f13c8bf4589
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index ddc3a715fb..65ea762fcd 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -4,13 +4,13 @@
 
 subagent seam：一个 agent（智能体）将工作委派给子 agent。与 [bash](bash.md) 一样，它是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。但它在一个维度上与其他所有 seam 不同：**同一上下文中可共存多个提供方实现**，按名称注册（`ctx.subagents`），而 bash 只允许一个执行器。注册表的形状参照 [LLM（大语言模型）适配器注册表](llm-streaming.md)，而非单服务的 bash 执行器。
 
-接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包（package）：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接从会话存储与可选的会话持久化负责只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
+接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接基于会话存储和可选的会话持久化提供只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
 
 源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)、[`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)和 [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
 ## 两类能力，两种发现方式
 
-提供方通过一个静态描述符公布其**启动时**特性，服务会在单次 run 存在之前即行检查；如果请求依赖提供方不具备的特性，会被大声拒绝（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不会被接受后静默忽略。这些 flag 仅描述单次 [`start()`](#the-provider-seam-subagentprovider) 路径，即由提供方组合子 agent 的路径。**可继续**子 agent 由继续执行管理器自行组合，因此它们由唯一一个可选方法把关，方法存在即为能力，并以 TypeScript 的类型收窄作为发现机制：[`SubagentProvider.prepareContinuable`](#the-provider-seam-subagentprovider)。
+提供方通过一个静态描述符公布其**启动时**功能，服务会在单次 run 存在之前即行检查；如果请求依赖提供方不具备的功能，会被明确拒绝（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不会被接受后静默忽略。这些 flag 仅描述单次 [`start()`](#the-provider-seam-subagentprovider) 路径，即由提供方组合子 agent 的路径。**可继续**子 agent 由继续执行管理器自行组合，因此它们由唯一一个可选方法把关，方法存在即为能力，并以 TypeScript 的类型收窄作为发现机制：[`SubagentProvider.prepareContinuable`](#the-provider-seam-subagentprovider)。
 
 ```ts type-equiv
 /**
@@ -98,7 +98,7 @@ interface SubagentStartRequest {
 
 `signal` 是就绪前后唯一的取消通道。[subagent 组合控制 Agent Note](../../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)规定 persona、live 全局工具过滤、绝对深度以及「可见性而非权限」的设计理由。
 
-面向调用方的请求不携带目录格式细节或继续执行状态。`SubagentService.start()` 会在功能检查后解析分离的一次性描述符，再将以下面向提供方的请求传给所选传输；可继续子 agent 绝不会到达 `SubagentProvider.start()`：
+面向调用方的请求不携带目录格式细节或继续执行状态。`SubagentService.start()` 会在能力检查后解析分离的一次性描述符，再将以下面向提供方的请求传给所选传输；可继续子 agent 绝不会到达 `SubagentProvider.start()`：
 
 ```ts type-equiv
 /**
@@ -123,7 +123,7 @@ persisted Session
        -> zero or more owned child Activations
 ```
 
-`SubagentService.startContinuable()` 会预留稳定的子 agent id，对版本化的 `subagent/descriptor` payload 建立快照，向指定提供方索取其分离的 `ContinuableCreateSpec`，通过私有的 activation-owner 作用域创建子 Agent，建立任何可继续父级的所有权，并提交初始 prompt。当收件箱（inbox）准入产出消息 id 时，它以 `{ childId, messageId }` resolve——无需等待轮次开始，也无需等待消息进入会话日志。在该准入之前的任何失败都会以两个 id 都不返回的方式 reject，并 dispose 任何已创建的 handle，回滚 Activation 与父级所有权。
+`SubagentService.startContinuable()` 会预留稳定的子 agent id，对版本化的 `subagent/descriptor` payload 建立快照，向指定提供方索取其分离的 `ContinuableCreateSpec`，通过私有的 activation-owner 作用域创建子 Agent，建立任何可继续父级的所有权，并提交初始提示词。当收件箱（inbox）准入产出消息 id 时，它以 `{ childId, messageId }` resolve——无需等待轮次开始，也无需等待消息进入会话日志。在该准入之前的任何失败都会以两个 id 都不返回的方式 reject，并 dispose（资源释放）任何已创建的 handle，回滚 Activation 与父级所有权。
 
 `SubagentService.followup()` 是唯一的继续执行消息操作，其路由仅取决于 Activation 的驻留状态：
 
@@ -133,15 +133,15 @@ persisted Session
 | `waiting` | 唤醒同一 Activation |
 | 无 Activation | 冷恢复一个新的 Activation |
 
-`running` 表示 Agent 拥有活跃的准入或轮次，或正在唤醒收件箱工作；`waiting` 表示它已停稳，但仍拥有至少一个尚未完成 dispose 的子 Activation；`settled` 表示已停稳且其拥有的每个子级都已 dispose，此时管理器会 dispose [`AgentHandle`](core.md#creation-and-ownership) 并移除该 Activation。管理器根据 Agent 的完全停稳状态与其拥有的子级集合推导这些内部条件，而非维护第二套执行状态机。
+`running` 表示 Agent 拥有活跃的准入或轮次，或正在唤醒收件箱工作；`waiting` 表示它已完全停稳，但仍拥有至少一个尚未完成 dispose 的子 Activation；`settled` 表示已完全停稳且其拥有的每个子级都已 dispose，此时管理器会 dispose [`AgentHandle`](core.md#creation-and-ownership) 并移除该 Activation。管理器根据 Agent 的完全停稳状态与其拥有的子级集合推导这些内部条件，而非维护第二套执行状态机。
 
-Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `Agent.followup()` FIFO 轮次，因此已接受的消息共享同一个可观测顺序，且后续消息无法改变已在进行中的轮次。投递成功会返回被接受的 `MessageId`；既有的 `agent/inbox/enqueue`、`agent/inbox/dequeue` 与 `agent/inbox/discard` 事件仍是消息生命周期的观测点，继续执行层不定义任何 subagent 专属的投递路由。
+Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `Agent.followup()` FIFO 轮次，因此已接受的消息共享同一个可观测顺序，且后续消息无法改变已在进行中的轮次。投递成功会返回被接受的 `MessageId`；既有的 `agent/inbox/inserted`、`agent/inbox/claimed` 与 `agent/inbox/discarded` 事件仍是消息生命周期的观测点，继续执行层不定义任何 subagent 专属的投递路由。
 
 后续操作的权限来自确切的在线 Agent 工具上下文。已认证的 Agent 必须是持久化子 agent 在 `SessionHeader.parentSession` 中记录的直接父级。`MessageSource` 与 `senderSessionId` 在准入之后是持久的来源凭据，不授予任何权限；可选的面向模型工具使用 `CoordinatorMessageSource`。
 
 对于这两种操作，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent，并且该 seam 不对外暴露任何 steering（中途引导）操作。
 
-`SubagentService.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待静止即返回。Activation、其尚未领取的待处理 inbox 工作与已发布的后代均不受影响；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；过期的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。
+`SubagentService.interrupt(targetSessionId, authority)` 是唯一的公开停止操作：它同步完成鉴权，对在线目标发出 `Agent.cancel(cause, { keepInbox: true })`，然后不等待完全停稳即返回。Activation、其尚未领取的待处理 inbox 工作与已发布的后代均不受影响；已被领取进入中断轮次的工作不会重新入队。被中断的 driver 进入 idle 后，一次唤醒发送会恢复被暂停的 FIFO 队列。不存在的目标——未知、一次性或已结算——以及未绑定管理器的组合是被接受的 no-op。对在线目标，错误的 parent 地址或不在其在线祖先链中的调用方会以 `UNAUTHORIZED` 拒绝；陈旧的 ancestor 对象和指向自身的 ancestor 请求会在查找目标前拒绝。
 
 ```ts type-equiv
 /**
@@ -154,7 +154,7 @@ type SubagentInterruptAuthority =
   | { readonly kind: 'ancestor'; readonly agent: Agent }
 ```
 
-每个 Activation 都拥有自己的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`；由于一份会话至多有一个存活 Activation，子会话 id 无需另一个运行时化身引用即可标识存活的子 agent。启动子 agent 或提交源自 parent 的工作，会在子 agent 能够运行之前将其注册到受继续执行管理的父级集合中；只要该集合非空，该父级就无法 settle。顶层或其他非继续执行的 Agent 没有 Activation，处于 waiting 图之外。只有当子 Agent 已停稳、该子 agent 的每个子级都已 dispose、best-effort 的最终会话 flush 结算完毕，且子 agent 的 `AgentHandle` 完成 dispose 之后，才会释放子 agent。
+每个 Activation 都拥有自己的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`；由于一份会话至多有一个存活 Activation，子会话 id 无需另一个运行时化身引用即可标识存活的子 agent。启动子 agent 或提交源自 parent 的工作，会在子 agent 能够运行之前将其注册到受继续执行管理的父级集合中；只要该集合非空，该父级就无法 settle。顶层或其他非继续执行的 Agent 没有 Activation，处于 waiting 图之外。只有当子 Agent 已完全停稳、该子 agent 的每个子级都已 dispose、best-effort 的最终会话 flush 结算完毕，且子 agent 的 `AgentHandle` 完成 dispose 之后，才会释放子 agent。
 
 最终结算会等待 `ctx.sessions.flush(session)`，但会忽略其参与布尔值，因为任意 listener 都无法证明某个持久化后端已存储该状态。rejection 会被记录，但不会使 Activation 失败；管理器仍会 dispose 该 handle 并释放所有权，此后持久化的子 agent 状态在后续恢复时可能缺失或陈旧。管理器卸载会调用内部的管理器全局 drain，关闭准入并 dispose 每片在线森林；`drainContinuableDescendants(parents)` 只关闭由 host 确切拥有的在线 Agent 之下的准入，并 dispose 其可继续后代，而无关森林保持在线。两者都会等待各自作用域内已获准的物化过程，自顶向下传播取消，按 child-first 顺序释放 handle，并且即使个别分支失败也会等待所有选中分支。持久化子会话不受该进程内拆卸的影响。
 
@@ -219,7 +219,7 @@ interface SubagentReportOptions {
 }
 ```
 
-提供方只参与准备初始创建 spec，`spawn` 与 `fork` 在此有所不同。其返回的 spec 只携带分离的、提供方专属的创建输入——目前是可选的父级历史种子——不含 Agent、`AgentHandle`、prompt 投递、结果、dispose 或 resume 操作。冷恢复根本不经由提供方分发：管理器折叠通用描述符，通过同一个 activation-owner 作用域调用 `ctx.agents.resume()`，并提交等待中的轮次。
+提供方只参与准备初始创建 spec，`spawn` 与 `fork` 在此有所不同。其返回的 spec 只携带分离的、提供方专属的创建输入——目前是可选的父级历史种子——不含 Agent、`AgentHandle`、提示词投递、结果、dispose 或恢复操作。冷恢复根本不经由提供方分发：管理器折叠通用描述符，通过同一个 activation-owner 作用域调用 `ctx.agents.resume()`，并提交等待中的轮次。
 
 ```ts type-equiv
 /**
@@ -259,13 +259,13 @@ interface ContinuableCreateSpec {
 }
 ```
 
-描述符（[descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts) 中的 `SubagentDescriptorData`）是每个由会话支撑的 subagent 所使用、按模式判别的持久化身份。两种模式都携带提供方名称。`one-shot` 描述符可以携带调用方拥有的可选显示 `label`；`continuable` 描述符要求以委派 `description` 作为持久化创建标签，并另外对已解析的子 agent `agentOptions.provider`／`model` 与可选的 `persona`／`toolFilter` 建立快照，用于冷恢复。它绝不会对可合并扩展的 `AgentOptions` 对象建立快照，因此无关的扩展值不会破坏继续执行，后续新增组合配置输入则是一次有意的版本更改。描述符省略 `subagentDepth`（冷恢复以持久化 header 中的 `delegationDepth` 作为单调下界）和 `outputSchema`（单次运行或 Activation 的结果契约，而非持久化身份）。
+描述符（[descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts) 中的 `SubagentDescriptorData`）是每个由会话支撑的 subagent 所使用、按模式判别的持久化身份。两种模式都携带提供方名称。`one-shot` 描述符可以携带调用方拥有的可选显示 `label`；`continuable` 描述符要求以委派 `description` 作为持久化创建标签，并另外对已解析的子 agent `agentOptions.provider`／`model` 与可选的 `persona`／`toolFilter` 建立快照，用于冷恢复。它绝不会对可合并扩展的 `AgentOptions` 对象建立快照，因此无关的扩展值不会破坏继续执行，后续新增组合配置输入则是一次有意的版本更改。描述符省略 `subagentDepth`（冷恢复以持久化 header 中的 `delegationDepth` 作为单调下界）和 `outputSchema`（单次运行或 Activation 的结果约定，而非持久化身份）。
 
-本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始 prompt 获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
+本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始提示词获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
 
 ## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
 
-`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 契约负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 `SubagentService.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
@@ -333,7 +333,7 @@ interface SubagentStopReasonMap {
 
 ## 单次 run：`SubagentRun`
 
-`SubagentRun` 是消费方持有的、指向一个已发布单次子 agent 的句柄——一次可 dispose 的前台委派，只有一个结果，绝不是持久化子 agent handle。发布后的提示词提交、轮次工作与基础设施故障归 `result` 所有。消费方 await 该结果并始终 dispose 该 run，直至完全停稳。子 agent 失败时以非 completed 的 stop reason resolve；只有无法表示的基础设施故障才会 reject。run 没有 steering，也没有 resume：可继续对话根本没有 run，因为继续执行管理器直接持有它们的 `AgentHandle`，并通过子 agent 自己的收件箱为每个轮次排序。
+`SubagentRun` 是消费方持有的、指向一个已发布单次子 agent 的句柄——一次可 dispose 的前台委派，只有一个结果，绝不是持久化子 agent handle。发布后的提示词提交、轮次工作与基础设施故障归 `result` 所有。消费方 await 该结果并始终 dispose 该 run，直至完全停稳。子 agent 失败时以非 completed 的 stop reason resolve；只有无法表示的基础设施故障才会 reject。run 没有 steering，也没有恢复：可继续对话根本没有 run，因为继续执行管理器直接持有它们的 `AgentHandle`，并通过子 agent 自己的收件箱为每个轮次排序。
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 21003bb796..b12daefe88 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/tools.md
 tools.md: 0551ee1c9dfa12b415c1f4575b5225f771cb53bc
-tools.zh.md: 50843b07f1d98b1c9d9222288b1273b34bee1e4a
+tools.zh.md: acdf10a0140e81dada9104653dee92dc9cb6f50d
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index 50843b07f1..acdf10a014 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -148,7 +148,7 @@ type InferArgs<S> = InferProperties<S, []>
 
 `defineTool({ name, description, parameters, output, execute, … })` 将参数推导与 `parameterSchemaSpecToJsonSchema()` 和 `validateArgs()` 绑定，并将 `execute`/`render`/`presentationMeta` 与 `InferValue<OutputSchema>` 绑定。Schema 记录只包含自有且可枚举的字符串键，schema 数组是稠密的内建数组，因此推导、编译与校验观察到的是同一份声明。精确推导保持到 16 层容器，之后放宽为 `JsonValue`；运行时校验仍会继续遍历完整 schema。`valueSchemaSpecToJsonSchema()` 通过同一套已强制执行的原始子集编译输出声明。参数不匹配时抛出 `ToolArgsError`（`INVALID_ARGS`）；函数体或后置策略产生的值无效时抛出 `ToolOutputError`（`INVALID_TOOL_OUTPUT`）。两者都经由常规工具错误路径处理。原始 JSON Schema 默认保持开放；不支持的关键字会被拒绝，而不会在未强制执行的情况下获准进入。
 
-注册是一个受信任的同进程契约。注册表以 readonly 输入借用类型化定义，要求它声明 `output`，校验其原始 schema，并检查 `timeoutMs` 必须为正有限值等语义要求；`schemas()` 在模型边界处物化显式的面向模型投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。
+注册是一个受信任的同进程约定。注册表以 readonly 输入借用类型化定义，要求它声明 `output`，校验其原始 schema，并检查 `timeoutMs` 必须为正有限值等语义要求；`schemas()` 在模型边界处物化显式的面向模型投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。
 
 ## `ToolRestriction` — 单个作用域的实时全局过滤器
 
@@ -243,7 +243,7 @@ type ToolExecutionMode =
   | { kind: 'exclusive' }
 ```
 
-Code Mode 的桥接层还会把每个已结算的子分派暴露给 `tools/code-dispatch-log` waterfall，该 waterfall 可以改写持久事件所存的内容副本（程序取得的值与模型契约均不受影响）：
+Code Mode 的桥接层还会把每个已结算的子分派暴露给 `tools/code-dispatch-log` waterfall，该 waterfall 可以改写持久事件所存的内容副本（程序取得的值与模型约定均不受影响）：
 
 ```ts type-equiv
 /**
@@ -452,7 +452,7 @@ type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
 - `ToolCallView`（待执行）：`{ card: 'generic', title, kind?, rawInput?, content?, locations? }`（默认卡片；`locations` 是 `{ path, line? }[]`，表示调用读取/修改的文件，供编辑器跟随）、`{ card: 'terminal', title, description?, cwd? }`（shell 命令→终端卡片）、或 `{ card: 'diff', title, diffs, locations? }`（文件创建/修改→行内 diff 卡片；`diffs` 是 `{ path, oldText, newText }[]`，新文件时 `oldText: null`）。
 - `ToolResultView`（已完成）：`{ card: 'generic', title?, content? }`、`{ card: 'terminal', title?, output?, exitCode?, signal? }`（捕获的运行输出 + 退出状态；有能力的 UI 显示退出状态标签，其他 UI 可以派生围栏 ` ```console ` 回退）、`{ card: 'diff', title?, diffs }`（已完成的文件变更→要展示的变更，通常是从变更前后内容计算出带上下文行的已应用 hunk，或在没有前像时的整文件 diff）、`{ card: 'search', shape, title?, truncated, total, … }`（已完成的发现型搜索→`shape: 'matches'`（grep）为按文件分组的匹配，`shape: 'paths'`（glob）为扁平路径列表；`truncated`/`total` 报告内联结果是否被截断，使 UI 永不把部分结果当作完整结果呈现；该视图不携带结果文本——无 search 卡片的 UI 回退到原始结果内容）、`{ card: 'read', title?, path, offset, lines, totalLines, lang?, content? }`（已完成的文件读取→带行号、可选语法高亮的代码视图；`offset` 是窗口请求的 1-based 起始行，即使 `lines` 为空也保留；`lang` 是从扩展名推得的语言提示，`content` 是无读取能力的 UI 回退时使用的去信封文本）、或 `{ card: 'web', kind: 'search' | 'fetch', title?, … }`（已完成的 web 检索；`kind: 'search'` 携带结构化的 `sources`/`answer?`/`truncated`，`kind: 'fetch'` 携带 `url`/`statusCode`/`truncated`，不具备 `web` 能力的 UI 回退到原始结果内容——正文不会重复进视图）。已完成视图会替换待执行视图，因此变更工具即使与调用时的片段重复也要返回 diff 结果；搜索和 web 检索都没有 `card` 的调用时对应视图（其 pending 状态保持为 generic 卡片，因为结构化结果只在 `execute` 之后才存在）。
 
-`ToolCallKind`（`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`）用于为通用卡片选择图标。`FileLocation`（`{ path, line? }`）、`FileDiff`（`{ path, oldText, newText }`）与 `ReadFileLine`（`{ number, text }`，读取窗口中一行带 1-based 行号的内容）是共享的文件卡片词汇。该设计由[渲染意图联合类型 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md)固定；host/client 运行时将这套中性词汇投影为各自的视图。
+`ToolCallKind`（`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`）用于为通用卡片选择图标。`FileLocation`（`{ path, line? }`）、`FileDiff`（`{ path, oldText, newText }`）与 `ReadFileLine`（`{ number, text }`，读取窗口中一行带 1-based 行号的内容）是共享的文件卡片词汇。该设计由[渲染意图联合类型 Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md)固定；host/client 运行时将这套中性词汇投影为各自的视图。
 
 完整的展示字段文档见 [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)。`bash` schema 与执行器见 [bash.md](bash.md)；通用后台控制见 [tasks.md](tasks.md)。
 
diff --git a/docs/subsystems/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml
index b8fdb092f2..d58e6036ab 100644
--- a/docs/subsystems/typert.i18n.yaml
+++ b/docs/subsystems/typert.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/typert.md
 typert.md: 8ce52837ceee8e9c8c4a61de28f972912faa2cf0
-typert.zh.md: ff6b45a517c75392ee87fa348d72bfae6cdf1efb
+typert.zh.md: a025716dad9a9279a45530a0a9109a13a2c34b0c
diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md
index ff6b45a517..a025716dad 100644
--- a/docs/subsystems/typert.zh.md
+++ b/docs/subsystems/typert.zh.md
@@ -2,11 +2,11 @@
 
 [English](typert.md) | 中文
 
-以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts) 中公共契约的字面定义。
+以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts) 中公共约定的字面定义。
 
-## Lookup 与 Context 声明
+## Lookup 与上下文声明
 
-业务对象包通过声明合并扩展两个空 map。lookup 将一种 Host 对象类型与其 wire identity 关联；Context 声明将一种 scoped Context 类别与其 wire identity 关联。生成的 descriptor 引用这些 key，运行时提供方则提供活对象解析行为。
+业务对象包通过声明合并扩展两个空 map。lookup 将一种 Host 对象类型与其 wire identity 关联；上下文声明将一种作用域上下文类别与其 wire identity 关联。生成的 descriptor 引用这些 key，运行时提供方则提供活对象解析行为。
 
 ```ts type-equiv
 /** Merge-extensible Host object lookup declarations. */
@@ -114,7 +114,7 @@ interface InvocationDescriptor {
 
 ## TypeRT 注册表
 
-`ctx.typert` 分开保存当前环境的 descriptor、显式选择的 Remote contribution、lookup 提供方与 scoped Context 提供方。lookup 提供方拥有稳定 wire 声明和默认 resolver；Host 组合可以为同一个 key 配置 effect-scoped 同步或异步 resolver，配置卸载后恢复默认策略。各项注册都是由 Cordis 持有的 effect，并返回可等待的 disposer。
+`ctx.typert` 分开保存当前环境的 descriptor、显式选择的 Remote contribution、lookup 提供方与作用域上下文提供方。lookup 提供方拥有稳定 wire 声明和默认 resolver；Host 组合可以为同一个 key 配置 effect-scoped 同步或异步 resolver，配置卸载后恢复默认策略。各项注册都是由 Cordis 持有的 effect，并返回可等待的 disposer。
 
 ```ts type-equiv
 /** Minimal TypeRT runtime consumed through dependency inversion. */
@@ -135,7 +135,7 @@ interface TypeRTRemoteNamespaceMap {}
 
 ## Host Gateway
 
-Connection 会先解码 carrier envelope，再调用 `ctx.typertGateway`。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带；基础设施与边界失败使用 Gateway 的进程内错误分类体系，普通异常由 RPC 适配器折叠为传输层的 `internal` 错误码，lookup 策略通过 `TypeRTLookupFailure` 携带的既有 RPC error 则原样返回。
+Connection 会先解码 carrier envelope，再调用 `ctx.typertGateway`。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带；基础设施与边界失败使用 Gateway 的进程内错误分类体系，普通异常由 RPC 适配器归并为传输层的 `internal` 错误码，lookup 策略通过 `TypeRTLookupFailure` 携带的既有 RPC error 则原样返回。
 
 ```ts type-equiv
 /** One Remote method request after a carrier has decoded its envelope. */
@@ -188,7 +188,7 @@ interface TypertGateway {
 
 ## 消费方 Remote
 
-`ctx.remote` 只暴露由已导入 `/remote` 产物贡献的 namespace。`$mount()` 会把生成的 descriptor 与具体方法作为一项由 fiber 持有的操作统一注册。每个 namespace 都是可追踪的 `remote.<namespace>` Cordis 子 Service，其生命周期覆盖已挂载的方法；JavaScript Proxy 与 Host 业务 Service 类型都不会进入消费方。
+`ctx.remote` 只暴露由已导入 `/remote` 产物贡献的 namespace。`$mount()` 会把生成的 descriptor 与具体方法作为一项由 fiber 持有的操作统一注册。每个 namespace 都是可追踪的 `remote.<namespace>` Cordis 子服务，其生命周期覆盖已挂载的方法；JavaScript Proxy 与 Host 业务服务类型都不会进入消费方。
 
 ```ts type-equiv
 /** Client Remote capability implemented by the Gateway and consumed by Remote assemblies. */
diff --git a/docs/subsystems/user-interaction.i18n.yaml b/docs/subsystems/user-interaction.i18n.yaml
index 342cf9b9f7..296bc8b766 100644
--- a/docs/subsystems/user-interaction.i18n.yaml
+++ b/docs/subsystems/user-interaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/user-interaction.md
 user-interaction.md: a19155ae06af0133ae468c004b2e3b66f1de3fb8
-user-interaction.zh.md: dc5845a976068981b2761e26502eaf7dd95dcb01
+user-interaction.zh.md: c7aa9cafc9865191cda4089ad2beb214a33b00ef
diff --git a/docs/subsystems/user-interaction.zh.md b/docs/subsystems/user-interaction.zh.md
index dc5845a976..c7aa9cafc9 100644
--- a/docs/subsystems/user-interaction.zh.md
+++ b/docs/subsystems/user-interaction.zh.md
@@ -2,7 +2,7 @@
 
 [English](user-interaction.md) | 中文
 
-[dsh-user-interaction](../../packages/interaction/user-interaction) 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。UI surface 提供活跃的 `UserInteractionProvider`；host 运行时把请求转发给它连接的客户端。
+[dsh-user-interaction](../../packages/interaction/user-interaction) 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。UI 界面提供活跃的 `UserInteractionProvider`；host 运行时把请求转发给其连接的客户端。
 
 源码：[`packages/interaction/user-interaction/src/index.ts`](../../packages/interaction/user-interaction/src/index.ts)
 
@@ -70,7 +70,7 @@ interface AskUserQuestionItem {
 
 ## 提问请求
 
-`AskUserQuestionRequest` 是跨包（package）的请求。`questions` 是数组，这样 UI 可以在一个流程中呈现相关提示，同时保持每个回答有稳定的 id。如提供 `agent`，它必须与存活调用方是同一实例；只有当当前注册表将该实例识别为运行时根时，交互 seam 才会接纳该 agent。
+`AskUserQuestionRequest` 是跨包请求。`questions` 是数组，这样 UI 可以在一个流程中呈现相关提示，同时保持每个回答有稳定的 id。如提供 `agent`，它必须与存活调用方是同一实例；只有当当前注册表将该实例识别为运行时根时，交互 seam 才会接纳该 agent。
 
 ```ts type-equiv
 /** Request for a human answer. */
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
index 0b7cdfdc76..4e9f1cb635 100644
--- a/docs/testing.i18n.yaml
+++ b/docs/testing.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/testing.md
 testing.md: 296dd769118cc5498ddb1bb9c41e2c060b2a5bce
-testing.zh.md: e9182495fbdbb1458c9ff5b30a9591f8b70f27c5
+testing.zh.md: 1d87309872d31a2779f3a411ce09e60db2416efd
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
index e9182495fb..1d87309872 100644
--- a/docs/testing.zh.md
+++ b/docs/testing.zh.md
@@ -2,15 +2,15 @@
 
 [English](testing.md) | 中文
 
-本文说明本仓库的分层测试方式，以及保持绿色测试套件有意义的规则。命令见根目录 [AGENTS.md](../AGENTS.md)；相关 Agent Note（agent 决策记录）承载设计动机。
+本文说明本仓库的分层测试方式，以及保持绿色测试套件有意义的规则。命令见根目录 [AGENTS.md](../AGENTS.md)；相关 Agent Note承载设计动机。
 
 ## 层级
 
-- **单元测试**（`pnpm run test`）：vitest 运行包（package）和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及永久性契约回归（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。
+- **单元测试**（`pnpm run test`）：vitest 运行包和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及永久性约定回归（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。
 - **覆盖率门禁**（`pnpm run test:coverage`）：门禁级运行，对 `packages/*/*/src` 按文件 100% 覆盖。未覆盖的行往往是门禁正确标记出的死代码（应删除），而非需要补写的测试。行覆盖率是必要条件，但永远不是充分条件：它证明行被执行过，不证明功能按交付预期工作。`packages/bash/pwsh-local/src` 的按文件 100% 覆盖需要真实的 `pwsh`：缺少它时其 executor 套件会自动跳过，`vitest.config.ts` 会豁免该文件以使无 pwsh 的主机保持绿色，而 CI runner 自带 pwsh，仍按完整标准执行门禁。
 - **真实 API e2e**（`pnpm run test:e2e`）：带密钥测试调用真实提供方 API，包括 DeepSeek 模型以及各提供方特有的冒烟测试；这些测试各自由自己的密钥控制（`EXA_API_KEY`、`PERPLEXITY_API_KEY` 等），缺少密钥时套件会自动跳过，使 keyless CI 保持绿色（[真实 API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md)）。
-- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输契约与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
-- **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 将回放后的浏览器输出与 `apps/web/tests/snapshots/` 比较。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 车道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)以交付插件 CSS。
+- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输约定与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
+- **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 将回放后的浏览器输出与 `apps/web/tests/snapshots/` 比较。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 通道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)以交付插件 CSS。
 
 签入仓库的会话格式 JSONL 使用规范打包行布局，无密钥快照门禁会通过 `session` header 发现每一份此类 fixture。仍携带旧版 fixture 改动的在途分支应合并当前 `master`，并通过 `pnpm run migrate:packed-session-fixtures` 运行[临时迁移器](../scripts/migrate-packed-session-fixtures.ts)；待所有受影响分支收敛后，[移除提案](../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)会移除该命令及这些链接。
 
@@ -42,8 +42,8 @@ e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身
 
 - CI 与已有构建产物的测试通道通过共享双模式启动器，从构建后的 `lib/` 运行每个示例或 Cordis 配置子进程。不要为这些子进程手写 `--import tsx`。
 - 不加载 Cordis 的协议与操作系统 fixture 直接通过 Node 运行使用可擦除语法的 `.ts` 文件，不经过 tsx 或根路径映射。
-- 只有测试对象本身是源码路径解析时，才可以选择 `src`；在测试中写明这一契约。
+- 只有测试对象本身是源码路径解析时，才可以选择 `src`；在测试中写明这一约定。
 
 ## 何时需要快照测试
 
-每项非平凡的模型可见、协议可见或人类可见变更，都必须在同一 PR 中，通过可运行示例所属的快照套件添加或更新无密钥场景。包测试、e2e 断言、mock 与仅测试组合、PR 理由都不能取代组装后的 transcript；必要时应扩展 harness。ACP 自动化场景使用 `examples/<name>/tests/snapshots/`，即基于 [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) 套件工厂的场景表（`examples/acp-agent` 为主套件）；`examples/headless-agent` 拥有内部规范事件 JSONL 快照与回放 fixture。`pwsh-tool-turn` ACP 场景启动真实 `pwsh`，在无 `pwsh` 的主机上跳过。已完成的交互式终端旅程使用 `apps/cli/tests/snapshots/` 下由 JSONL 驱动的场景；瞬态呈现使用包内语义矩阵，输入、Loader 选择或终端清理发生变化时还要添加 PTY 用例。新的能力 seam、生命周期形态或 transcript 呈现接口在计划阶段就要列出每个覆盖层级，并在实现前验证 harness 能够表达它们。
+每项非平凡的模型可见、协议可见或人类可见变更，都必须在同一 PR 中，通过可运行示例所属的快照套件添加或更新无密钥场景。包测试、e2e 断言、mock 与仅测试组合、PR 理由都不能取代组装后的 transcript；必要时应扩展 harness。ACP 自动化场景使用 `examples/<name>/tests/snapshots/`，即基于 [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) 套件工厂的场景表（`examples/acp-agent` 为主套件）；`examples/headless-agent` 拥有内部规范事件 JSONL 快照与回放 fixture。`pwsh-tool-turn` ACP 场景启动真实 `pwsh`，在无 `pwsh` 的主机上跳过。已完成的交互式终端旅程使用 `apps/cli/tests/snapshots/` 下由 JSONL 驱动的场景；浏览器渲染的 Web GUI 旅程使用 `apps/web/tests/snapshots/`；瞬态呈现使用包内语义矩阵，输入、Loader 选择或终端清理发生变化时还要添加 PTY 用例。新的能力 seam、生命周期形态或 transcript 呈现接口在计划阶段就要列出每个覆盖层级，并在实现前验证 harness 能够表达它们。
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
new file mode 100644
index 0000000000..8eecc6cc4a
--- /dev/null
+++ b/docs/tool-catalog.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 docs/tool-catalog.md
+tool-catalog.md: 8986847d1ed2fe9d64ada0c71f34700ff95fb364
+tool-catalog.zh.md: ed78883f74a7d245de97bc45d7125e6245e140ce
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
new file mode 100644
index 0000000000..ed78883f74
--- /dev/null
+++ b/docs/tool-catalog.zh.md
@@ -0,0 +1,1553 @@
+<!-- 英文源文件由 scripts/gen-tool-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-tool-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/tool-catalog.md` 重新记录配对。 -->
+
+# 工具 Schema 目录
+
+[English](tool-catalog.md) | 中文
+
+已发布插件向 `ctx.tools` 提供的所有面向模型的工具：模型通过系统提示词组装获得的 `name`、`description` 和 JSON Schema `parameters`。本目录是[子系统页面](subsystems/core.md)（类型及每页生成的 `cordis-surface` 接线区域）的补充；本页列出的是向 agent（智能体）提供的*工具*。
+
+英文源文件由系统**生成**，并通过 `pnpm run verify-tool-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。与 Cordis 目录（纯源码 AST 处理）不同，英文生成器会在真实上下文中**启动**每个工具插件并读取 `ctx.tools.schemas()`，因为工具 schema 无法通过静态分析完全确定，例如运行时展开的枚举、拼接的描述、由配置决定的名称以及使用原始 JSON Schema 的 MCP 工具。完整性守卫会 glob 匹配 `packages/*/tool-*`；如果生成器的启动 manifest（元数据清单）遗漏任何包，检查就会失败，因此新工具不会在无人察觉的情况下缺少文档。参见[工具 schema 目录 Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)。
+
+范围：`packages/*/tool-*` 下已发布的产品工具，每个工具均使用其**默认**配置启动；但如果某个 Config 字段是**必填项**且没有默认值，生成器就必须作出选择，对应包的说明会记录本页展示的是哪个分支。注册的工具**名称**可以是加载时配置，例如 `tool-subagent` 的 `toolName`，因此部署可能以不同名称或额外名称提供某个包；如果存在随产品发布的别名，对应包的说明会予以记录。`examples/` 中的演示工具（例如 `echo`）不在范围内，这与 Cordis 目录仅涵盖包的范围一致。
+
+## 工具包映射
+
+下表将模型可见的工具名称与其背后的插件包和服务 seam 对应起来。各包章节随后给出确切的 JSON Schema。
+
+| 工具包 | 模型可见名称 | 依赖 | 写入／影响 | 随产品发布的别名 | 部署说明 |
+| --- | --- | --- | --- | --- | --- |
+| `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`、`ctx.userInteraction` | `tool/call`、`UI/provider 回答问题后的 tool/result` | - | ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。 |
+| `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`、`ctx.codeRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`每个桥接子调用对应的一组 tool/code-dispatch-start + tool/code-dispatch`、`tool/result` | - | 在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 |
+| `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userInteraction (execution time, opportunistic)` | `tool/call`、`获批评审后的 plan/mode inactive`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 |
+| `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `@deepseek-ai/dsh-tool-tasks` 的 `task_*` 工具收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 |
+| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
+| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`进程本地临时 Plugin 生命周期` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 `.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md`。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
+| `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`成功完成文件操作后的 fs/observed`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
+| `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`变更对应的 fs/write-intent 或 fs/edit-intent`、`成功完成文件操作后的 fs/observed`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
+| `@deepseek-ai/dsh-tool-fs-search` | `glob`、`grep` | `ctx.tools`、`ctx.subprocess`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 |
+| `@deepseek-ai/dsh-tool-pty` | `terminal_close`、`terminal_list`、`terminal_open`、`terminal_read`、`terminal_send`、`terminal_signal` | `ctx.tools`、`ctx.pty`、`ctx.systemPrompt`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 |
+| `@deepseek-ai/dsh-tool-goal` | `create_goal`、`get_goal`、`update_goal` | `ctx.tools`、`ctx.agents`、`ctx.goals`、`ctx.systemPrompt`、`a calling Agent in an authorized open turn` | `tool/call`、`变更对应的 goal/change`、`tool/result` | - | create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 |
+| `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`、`ctx.lsp`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，因此其模型可见 schema 在更换提供方时保持稳定。运行时要求已注册提供方，例如 `@deepseek-ai/dsh-lsp-local`；如果没有提供方，查询会返回结构化 `LSP_UNAVAILABLE` 错误，而不会改变 schema。 |
+| `@deepseek-ai/dsh-tool-ralph` | `ralph` | `ctx.tools`、`ctx.workflows`、`ctx.subagents`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents every fresh round)` | `tool/call`、`tool/result`、`执行期间的工作流与子会话事件` | - | 固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。 |
+| `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`、`ctx.agents`、`ctx.skills` | `tool/call`、`tool/result`、`通过 agent.inject() 注入的 user/message 替换目录` | - | - |
+| `@deepseek-ai/dsh-tool-session-query` | `session_event_read`、`session_event_search`、`session_event_trace`、`session_search`、`session_trace` | `ctx.tools`、`ctx.systemPrompt`、`ctx.sessionQuery`、`a calling Agent for workspace authority` | `tool/call`、`tool/result` | - | 这 5 个只读工具会隐藏提供方游标，并根据不可变的调用 agent 会话为每个结果授权。该包需要选择启用；需要强制截止时间或限制行内输出的组合还会挂载通用超时或 spill 策略。 |
+| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`、`ctx.subagents` | `tool/call`、`tool/result`、`经所选提供方产生的子会话事件` | `subagent`、`subagent_fork` | 注册的工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述 schema 对应默认值。随产品发布的示例 agent 会为每个 subagent 后端加载一次该包，因此模型还会看到 schema 相同、绑定到 fork 后端的 `subagent_fork`；见 `packages/bundle/base/cordis.patch.yml` 和 `examples/acp-agent/cordis.yml`。 |
+| `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`、`list_agents`、`send_message` | `ctx.tools`、`ctx.subagents`、`ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`、`tool/result`、`经 ctx.subagents 产生的子会话事件` | - | 这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，并通过单独加载的 `/list-agents` 插件提供 `list_agents`，其目录行使用 sessionProjections 和实时 Agent 注册表。 |
+| `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`、`a live continuable in-process child Agent` | `tool/call`、`tool/result`、`直接父会话中的 user 角色消息` | - | 按可继续的进程内子级注册，而非全局注册，因此该 schema 仅在这种子级内部可见，并且不受其全局 `toolFilter` 影响。面向父级的 `send_message` 工具单独安装。 |
+| `@deepseek-ai/dsh-tool-tasks` | `task_kill`、`task_list`、`task_output` | `ctx.tools`、`ctx.tasks`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`通过 agent.inject() 发送后台完成通知的 user/message` | - | 与任务种类无关的后台任务控制接口：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制接口，从而启用生产方的 `ctx.tasks.start()`。 |
+| `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`、`owning Agent session` | `tool/call`、`todo/write`、`tool/result` | - | todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项，因此本目录明确选择 `true`，对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具，但描述会要求只能有 1 个活动任务。 |
+| `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`、`ctx.workflows`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents the script children)` | `tool/call`、`tool/result` | - | - |
+| `@deepseek-ai/dsh-tool-web` | `web_fetch`、`web_search` | `ctx.tools`、`ctx.web`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | web_search 和 web_fetch 将提供方选择置于 ctx.web 之后，使模型可见 schema 在更换后端时保持稳定。 |
+
+## `@deepseek-ai/dsh-tool-ask-user`
+
+### `ask_user_question`
+
+继续操作前，如果需要确认、选择或缺失的信息，请向用户提出简明问题。发送一个或多个问题，每个问题都带一个稳定 id，该 id 会在答案中原样返回。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "questions": {
+      "type": "array",
+      "description": "Questions to ask the user before continuing.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable id for this question; echoed in the answer."
+          },
+          "question": {
+            "type": "string",
+            "description": "The specific question to ask the user."
+          },
+          "header": {
+            "type": "string",
+            "description": "Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."
+          },
+          "options": {
+            "type": "array",
+            "description": "Optional choices to show the user. If you recommend one, put it first and append \"(Recommended)\" to that label.",
+            "items": {
+              "type": "object",
+              "additionalProperties": true,
+              "properties": {
+                "label": {
+                  "type": "string",
+                  "description": "Short user-facing option label."
+                },
+                "description": {
+                  "type": "string",
+                  "description": "One sentence explaining the tradeoff or impact."
+                }
+              },
+              "required": [
+                "label"
+              ]
+            }
+          },
+          "multi_select": {
+            "type": "boolean",
+            "description": "Whether the user may select more than one option. Defaults to false."
+          }
+        },
+        "required": [
+          "id",
+          "question"
+        ]
+      }
+    }
+  },
+  "required": [
+    "questions"
+  ]
+}
+```
+
+来源：[`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts)
+
+ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。
+
+## `@deepseek-ai/dsh-tools`
+
+### `run_code`
+
+针对可用工具执行 TypeScript 程序。请编写异步函数的**函数体**（仅使用可擦除语法；支持顶层 `await` 和 `return`），并根据系统提示词中的声明，以 `await tools.name(args)` 形式调用工具。只有打印或返回的内容会传回，请谨慎筛选。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "The program: the body of an async TypeScript function."
+    },
+    "description": {
+      "type": "string",
+      "description": "Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."
+    }
+  },
+  "required": [
+    "code",
+    "description"
+  ]
+}
+```
+
+来源：[`packages/core/tools/src/code-mode.ts`](../packages/core/tools/src/code-mode.ts)
+
+在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。
+
+## `@deepseek-ai/dsh-plan-mode`
+
+### `exit_plan_mode`
+
+仅在规划模式下使用。提交计划供用户评审，并在获批后退出规划模式。发送**完整的** Markdown 计划，以一个为计划命名的 `#` 标题开头。用户可以批准（从你的下一步骤起执行计划），也可以要求继续规划；其反馈会通过工具结果返回，请修改后再次提交。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "plan": {
+      "type": "string",
+      "description": "The complete plan, as markdown, starting with a # heading that names it."
+    }
+  },
+  "required": [
+    "plan"
+  ]
+}
+```
+
+来源：[`packages/plan/plan-mode/src/index.ts`](../packages/plan/plan-mode/src/index.ts)
+
+规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。
+
+## `@deepseek-ai/dsh-tool-bash`
+
+### `bash`
+
+执行 bash 命令（`bash -c`）并返回 stdout/stderr。每次调用都在新 shell 中运行：调用之间不保留任何状态（cwd、变量、函数），请传入 `workdir`，不要使用 `cd`。非零退出会报告为 `[exit code: N]`。当前 harness 环境信息通过托管的 `$DSH_*` 变量公开，需要时请检查这些变量。命令可能在文件沙箱中运行；被阻止的文件操作报告为 `[sandbox: file access denied under <mode> mode]`，这是策略拒绝，而不是命令缺陷，请勿换一种方式重试。较长的输出会截断，只保留尾部；如可用，完整输出会保存到文件并报告其路径。对于长时间运行的命令，请设置 `run_in_background: true`：调用会立即返回 task id；使用 `task_output` 读取输出，使用 `task_kill` 停止任务。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "command": {
+      "type": "string",
+      "description": "The bash command to execute."
+    },
+    "description": {
+      "type": "string",
+      "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."
+    },
+    "timeoutMs": {
+      "type": "number",
+      "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+    },
+    "workdir": {
+      "type": "string",
+      "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+    },
+    "run_in_background": {
+      "type": "boolean",
+      "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
+    }
+  },
+  "required": [
+    "command",
+    "description"
+  ]
+}
+```
+
+来源：[`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)
+
+bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `@deepseek-ai/dsh-tool-tasks` 的 `task_*` 工具收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。
+
+## `@deepseek-ai/dsh-tool-pwsh`
+
+### `pwsh`
+
+执行 PowerShell 命令（`pwsh -Command`）并返回 stdout/stderr。每次调用都在新的 pwsh 进程中运行：调用之间不保留任何状态（cwd、变量、函数），请传入 `workdir`，不要使用 `cd`。路径采用 Windows 原生形式（`C:\...`）；使用 `$env:NAME` 读取环境变量。非零退出会报告为 `[exit code: N]`。当前 harness 环境信息通过托管的 `$env:DSH_*` 变量公开，需要时请检查这些变量。较长的输出会截断，只保留尾部；如可用，完整输出会保存到文件并报告其路径。在 Windows 上，被强制终止的命令会以 `[exit code: 1]` 结算且不带信号标记，请将其视为中断，而不是命令失败。对于长时间运行的命令，请设置 `run_in_background: true`：调用会立即返回 task id；使用 `task_output` 读取输出，使用 `task_kill` 停止任务。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "command": {
+      "type": "string",
+      "description": "The PowerShell command to execute."
+    },
+    "description": {
+      "type": "string",
+      "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"Get-Process\" → \"List running processes\"."
+    },
+    "timeoutMs": {
+      "type": "number",
+      "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+    },
+    "workdir": {
+      "type": "string",
+      "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+    },
+    "run_in_background": {
+      "type": "boolean",
+      "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
+    }
+  },
+  "required": [
+    "command",
+    "description"
+  ]
+}
+```
+
+来源：[`packages/bash/tool-pwsh/src/index.ts`](../packages/bash/tool-pwsh/src/index.ts)
+
+pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。
+
+## `@deepseek-ai/dsh-tool-cordis`
+
+### `cordis_inspect`
+
+检查当前 DSH 进程中的实时 Cordis 运行时。只读。章节包括：`services`（所有已提供的 ctx 服务及拥有它的插件 fiber）、`plugins`（所有实时插件 fiber 及其生命周期状态）、`tools`（当前注册的模型可见工具，即你可以调用的工具）、`temporary`（仅由 cordis_mount 创建的临时 Plugin：id、名称、状态、提供的服务、等待的服务和存续期）、`api`（每个**实时**服务的方法签名以及参数／返回值类型形状；编写调用服务的插件代码前请先阅读）、`events`（每个 harness 事件的分派模式和确切签名；在此选择监听目标）。临时 Plugin 仅存在于内存中，会在后续轮次中保持活动，并在 cordis_unmount、工具集卸载或 DSH 重启后消失；不会自动恢复。`temporary` 是 `plugins` 的子集。省略 `what` 可获取全部 6 个章节。使用 `what:"api"` 或 `what:"events"` 时，可传入确切的 `name`，将范围缩小到一个服务／事件，并包含其原始源码 JSDoc。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "what": {
+      "type": "string",
+      "description": "Limit the report to one section. Omit for all sections.",
+      "enum": [
+        "services",
+        "plugins",
+        "tools",
+        "temporary",
+        "api",
+        "events"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "description": "Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."
+    }
+  }
+}
+```
+
+来源：[`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
+
+### `cordis_mount`
+
+在当前 DSH 进程中挂载临时 Cordis Plugin。它创建的是内存中的运行时 Plugin，而不是已安装或已配置的 Plugin。该插件会在后续轮次中保持活动，直到执行 cordis_unmount、工具集卸载或 DSH 重启。它不会创建文件、安装包、修改 cordis.yml 或个人／项目配置、在重启后保留，也不会自动转为永久插件。若要保留，请让 Agent 通过常规开发工作流实现普通的本地、项目或仓库 Plugin。它可能影响同一进程中的其他会话；沙箱不是安全边界，注入的服务会访问真实运行时。`code` 会立即作为异步 JavaScript 函数的函数体在隔离沙箱中运行，并且**必须** `return` 一个插件。支持两种形式：函数形式 `return (ctx) => { … }`，它不声明 inject，因此可以注册工具、监听事件和提供服务，但访问**任何**服务（例如 ctx.bash）都会抛出异常；仅在不需要服务时使用。对象形式 `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }`，它声明依赖，Cordis 只在服务存在后激活插件；**优先使用**这种形式。你只能访问 inject 中列出的服务：即使未声明的服务存在，访问它也会抛出异常，因为如果提供方被卸载，未声明的依赖将无法清理。代码调用服务**之前**，请读取 cordis_inspect 的 what:"api"；它会列出方法签名以及参数／返回值的类型形状，不要猜测字段类型，例如 bash 运行的 stdout 是对象而非字符串。在 `apply` 内，请使用标准 Cordis API：通过 `ctx.on(event, listener)` 观察事件（见 cordis_inspect 的 what:"events"），或调用 `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` 为自己提供新工具；该工具会在你的**下一步骤**可调用。工具参数：每个键**就是**一个属性，即 { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }；每个直接 DSL 对象都声明 additionalProperties: true|false，而 oneOf: [schema, schema, ...] 会取代 type，表示恰好匹配一个成员的联合。也接受原始 JSON Schema { type: 'object', properties, required?: […] } 包装层，其中对象默认开放。工具的 `execute` **必须**返回 `output.schema` 声明的无损 JSON 值；`output.render(args, value)` 单独返回 Native／模型内容块。临时 Plugin 可以**组合**：一个 Plugin 可以通过 `ctx.provide('name', value)` 提供服务，另一个则可声明 `inject: ['name']` 来消费它；消费方会在提供方出现前保持等待，提供方卸载后重新回到等待状态。在 `apply` 中注册的一切都会由 cordis_unmount 自动清理。沙箱全局对象：`console`（带 `[cordis:<id>]` 标签，写入 harness 终端）、`harness.defineTool`、`harness.registerTool`、`btoa`、`atob`、`TextEncoder`、`TextDecoder`。Node API 已**禁用**：文件系统／网络／定时工作必须通过 Cordis 服务完成，绝不能使用 Node 内置能力；`require`、`setTimeout`／`setInterval` 和 `fetch` 会抛出重定向错误，`process` 和 `Buffer` 未定义。应改用 inject: ['fs'] + ctx.fs 处理文件、inject: ['web'] + ctx.web 处理 HTTP、inject: ['bash'] + ctx.bash 处理进程、inject: ['timer'] + ctx.setTimeout/ctx.setInterval 处理定时（这些是 fiber effect，卸载时自动清理）；cordis_inspect 的 what:"api" 会展示**当前**运行时提供的能力。请编写**纯** JavaScript，不要使用 TypeScript（不得使用 `as` 或类型注解）。注意事项：(1) waterfall（瀑布式事件）事件（例如 tools/pre-execute）会向监听器传入最后一个 `next` 回调，该回调**必须**被调用；不调用 `next()` 就返回会**否决**此次调用。除非你有意拦截，否则请优先使用普通通知事件。(2) 切勿等待只能在当前轮次之后解析的内容；你的代码运行在该轮次的工具调用**内部**，否则会死锁。(3) 你的 `ctx` 是受限门面：可以注册工具、观察事件、提供／消费服务和使用定时器，但不会提供框架内部能力（ctx.root、ctx.fiber、ctx.extend、ctx.plugin 等）。不过，它并非安全边界：你注入的服务（例如 ctx.bash）会访问真实运行时。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."
+    }
+  },
+  "required": [
+    "code"
+  ]
+}
+```
+
+来源：[`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
+
+### `cordis_unmount`
+
+卸载当前进程中由 cordis_mount 创建的临时 Plugin。它会等待该插件的工具、监听器、服务、定时器及其他自有效果全部清理完成。只接受 `dyn-N` 临时 id；无法移除 Loader、已配置或已安装的 Plugin。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."
+    }
+  },
+  "required": [
+    "id"
+  ]
+}
+```
+
+来源：[`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
+
+不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 `.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md`。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。
+
+## `@deepseek-ai/dsh-tool-bash-persistent`
+
+### `bash`
+
+在持久 bash shell 中运行命令。包括当前目录和已导出环境变量在内的状态会在此 agent 的多次调用之间保留。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "command": {
+      "type": "string",
+      "description": "The bash command to run. Relative path is preferred in the command."
+    }
+  },
+  "required": [
+    "command"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-bash-persistent/src/index.ts`](../packages/pty/tool-bash-persistent/src/index.ts)
+
+一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。
+
+## `@deepseek-ai/dsh-tool-str-replace-editor`
+
+### `str_replace_editor`
+
+用于查看、创建和编辑文件的自定义编辑工具：
+
+* 状态会在命令调用以及与用户的讨论之间持久保留
+* 如果 `path` 是文件，`view` 会显示应用 `cat -n` 后的结果。如果 `path` 是目录，`view` 会列出最多向下 2 层的非隐藏文件和目录
+* 如果指定的 `path` 已作为文件存在，则不能使用 `create` 命令
+* 如果 `command` 产生较长输出，输出会被截断并标记为 `<response clipped>`
+
+使用 `str_replace` 命令时请注意：
+
+* `old_str` 参数应与原文件中一行或多行连续内容**完全**匹配。请留意空白字符！
+* 如果 `old_str` 参数在文件中不唯一，则不会执行替换。请确保在 `old_str` 中包含足够的上下文，使其唯一
+* `new_str` 参数应包含用于替换 `old_str` 的已编辑行
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "command": {
+      "type": "string",
+      "description": "The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`.",
+      "enum": [
+        "view",
+        "create",
+        "str_replace",
+        "insert"
+      ]
+    },
+    "path": {
+      "type": "string",
+      "description": "Absolute path to file or directory, e.g. `/repo/file.py` or `/repo`."
+    },
+    "file_text": {
+      "type": "string",
+      "description": "Required parameter of `create` command, with the content of the file to be created."
+    },
+    "insert_line": {
+      "type": "integer",
+      "description": "Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`."
+    },
+    "new_str": {
+      "type": "string",
+      "description": "Optional parameter of `str_replace` command containing the new string (if not given, no string will be added). Required parameter of `insert` command containing the string to insert."
+    },
+    "old_str": {
+      "type": "string",
+      "description": "Required parameter of `str_replace` command containing the string in `path` to replace."
+    },
+    "view_range": {
+      "type": "array",
+      "description": "Optional parameter of `view` command when `path` points to a file. If none is given, the full file is shown. If provided, the file will be shown in the indicated line number range, e.g. [11, 12] will show lines 11 and 12. Indexing at 1 to start. Setting `[start_line, -1]` shows all lines from `start_line` to the end of the file.",
+      "items": {
+        "type": "integer"
+      }
+    }
+  },
+  "required": [
+    "command",
+    "path"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-str-replace-editor/src/index.ts`](../packages/fs/tool-str-replace-editor/src/index.ts)
+
+基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。
+
+## `@deepseek-ai/dsh-tool-fs`
+
+### `edit`
+
+通过替换字面量文本来编辑现有 UTF-8 文本文件。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file_path": {
+      "type": "string",
+      "description": "Path to edit, resolved by the filesystem backend."
+    },
+    "old_string": {
+      "type": "string",
+      "description": "Literal text to replace. Must match exactly."
+    },
+    "new_string": {
+      "type": "string",
+      "description": "Literal replacement text. Use an empty string to delete the match."
+    },
+    "replace_all": {
+      "type": "boolean",
+      "description": "Replace all matches. Defaults to false; when false, old_string must appear exactly once."
+    }
+  },
+  "required": [
+    "file_path",
+    "old_string",
+    "new_string"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts)
+
+### `read`
+
+读取 UTF-8 文本文件，并返回带行号的内容。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file_path": {
+      "type": "string",
+      "description": "Path to read, resolved by the filesystem backend."
+    },
+    "offset": {
+      "type": "number",
+      "description": "1-based first line to return. Defaults to 1."
+    },
+    "limit": {
+      "type": "number",
+      "description": "Maximum number of lines to return. Defaults to 2000."
+    }
+  },
+  "required": [
+    "file_path"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts)
+
+### `write`
+
+创建或完全替换 UTF-8 文本文件。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "file_path": {
+      "type": "string",
+      "description": "Path to write, resolved by the filesystem backend."
+    },
+    "content": {
+      "type": "string",
+      "description": "Full UTF-8 text content to write."
+    }
+  },
+  "required": [
+    "file_path",
+    "content"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts)
+
+先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。
+
+## `@deepseek-ai/dsh-tool-fs-search`
+
+### `glob`
+
+查找路径匹配 glob 模式的文件。只返回匹配的文件路径，绝不返回目录；包括隐藏文件和被忽略的文件，但排除 VCS 元数据目录。最多按修改时间顺序返回 100 条路径；如果结果更多，则改为返回从顶层条目中抽样的 100 条路径，说明已抽样，并报告完整排序列表的保存位置。该工具不枚举目录条目。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "pattern": {
+      "type": "string",
+      "description": "Glob pattern to match file paths against (e.g. \"**/*.ts\", \"src/**/*.test.js\"). A pattern with no \"/\" matches the basename at any depth, so \"*\" and \"*.ts\" both search the whole tree; include a separator to anchor the depth."
+    },
+    "path": {
+      "type": "string",
+      "description": "Directory to search in. Defaults to the session workspace; a relative path resolves against it."
+    }
+  },
+  "required": [
+    "pattern"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-search/src/index.ts)
+
+### `grep`
+
+使用 ripgrep 正则表达式搜索文件内容。返回带行号的匹配行，并按文件分组。前 250 条匹配会直接返回；结果达到上限时会报告完整匹配列表的保存位置。如需周边上下文，请对匹配的文件使用 read。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "pattern": {
+      "type": "string",
+      "description": "Regular expression to search for (ripgrep syntax)."
+    },
+    "path": {
+      "type": "string",
+      "description": "File or directory to search. Defaults to the session workspace; a relative path resolves against it."
+    },
+    "include": {
+      "type": "string",
+      "description": "One glob filter for which files to search (e.g. \"*.ts\", \"*.{js,jsx}\"). Not a list; negation is not supported."
+    }
+  },
+  "required": [
+    "pattern"
+  ]
+}
+```
+
+来源：[`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-search/src/index.ts)
+
+glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。
+
+## `@deepseek-ai/dsh-tool-pty`
+
+### `terminal_close`
+
+关闭一个持久终端，并等待其捕获且所有的进程树完全退出。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "description": "Terminal session id."
+    }
+  },
+  "required": [
+    "sessionId"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+### `terminal_list`
+
+列出当前 agent 所有的持久终端会话。
+
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+### `terminal_open`
+
+通过已注册的后端类型创建按所有者隔离的持久终端会话。需要在多次工具调用之间保留 shell 或 REPL 状态时，请使用此工具。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "Registered terminal backend type, usually \"shell\"."
+    },
+    "name": {
+      "type": "string",
+      "description": "Optional owner-local display name such as \"main\" or \"gdb\"."
+    },
+    "cwd": {
+      "type": "string",
+      "description": "Initial working directory. Defaults to the deployment workspace root."
+    }
+  },
+  "required": [
+    "type"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+### `terminal_read`
+
+从持久终端读取一页有界的保留输出，不发送输入。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "description": "Terminal session id."
+    },
+    "offset": {
+      "type": "number",
+      "description": "Newest-relative line offset (default 0)."
+    },
+    "count": {
+      "type": "number",
+      "description": "Requested line count (default 500; backend caps apply)."
+    }
+  },
+  "required": [
+    "sessionId"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+### `terminal_send`
+
+向持久终端发送文本。默认会提交 Enter，并等待提示符、stdin 等待、输出静默、超时或会话退出。后台模式会返回供 task_output／task_kill 使用的 task id。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "description": "Terminal session id returned by terminal_open or terminal_list."
+    },
+    "text": {
+      "type": "string",
+      "description": "UTF-8 text to write to the terminal."
+    },
+    "submit": {
+      "type": "boolean",
+      "description": "Submit Enter after text (default true). Set false for control characters or incomplete REPL input."
+    },
+    "run_in_background": {
+      "type": "boolean",
+      "description": "Return a task id immediately; collect with task_output or stop with task_kill."
+    }
+  },
+  "required": [
+    "sessionId",
+    "text"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+### `terminal_signal`
+
+向持久终端当前的前台进程组发送允许的信号。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "description": "Terminal session id."
+    },
+    "signal": {
+      "type": "string",
+      "description": "Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.",
+      "enum": [
+        "SIGINT",
+        "SIGTERM",
+        "SIGKILL",
+        "SIGTSTP",
+        "SIGHUP"
+      ]
+    }
+  },
+  "required": [
+    "sessionId",
+    "signal"
+  ]
+}
+```
+
+来源：[`packages/pty/tool-pty/src/index.ts`](../packages/pty/tool-pty/src/index.ts)
+
+这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。
+
+## `@deepseek-ai/dsh-tool-goal`
+
+### `create_goal`
+
+当当前直接人类请求是需要跨自主 Goal Round 持续推进的长期目标时，创建一个持久化的同会话完成目标。即使用户没有明确说「创建目标」，你也可以推断其意图。不要用于简单的单轮工作。执行时会拒绝非人类权限和 subagent 权限。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "objective": {
+      "type": "string",
+      "description": "The concrete completion objective inferred from the direct human request."
+    },
+    "max_goal_rounds": {
+      "type": "number",
+      "description": "Optional positive safe-integer limit on automatic continuation rounds."
+    }
+  },
+  "required": [
+    "objective"
+  ]
+}
+```
+
+来源：[`packages/goal/tool-goal/src/index.ts`](../packages/goal/tool-goal/src/index.ts)
+
+### `get_goal`
+
+读取当前的同会话目标，包括确切的 id／revision、目标、阶段、已完成的延续 Round 数、Round 上限、存在时的阻塞原因，以及是否已准备下一次延续。更新目标前请先调用此工具。
+
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+来源：[`packages/goal/tool-goal/src/index.ts`](../packages/goal/tool-goal/src/index.ts)
+
+### `update_goal`
+
+更新确切的当前目标 revision。edit、pause 和 resume 要求直接的顶层人类请求。在自动延续当前目标期间，也允许 complete 和 blocked。在达到配置的最小 Round 数之前会拒绝 blocked；模型仍须判断相同条件是否在这些 Round 中持续存在，并在 blocked_reason 中予以说明。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "goal_id": {
+      "type": "string",
+      "description": "Exact id returned by get_goal."
+    },
+    "revision": {
+      "type": "number",
+      "description": "Exact positive revision returned by get_goal."
+    },
+    "action": {
+      "type": "string",
+      "description": "edit | pause | resume | complete | blocked",
+      "enum": [
+        "edit",
+        "pause",
+        "resume",
+        "complete",
+        "blocked"
+      ]
+    },
+    "objective": {
+      "type": "string",
+      "description": "Replacement objective; valid only with action edit."
+    },
+    "max_goal_rounds": {
+      "type": "number",
+      "description": "Replacement cap; valid only with action edit."
+    },
+    "blocked_reason": {
+      "type": "string",
+      "description": "Concrete blocking condition; required only with action blocked."
+    }
+  },
+  "required": [
+    "goal_id",
+    "revision",
+    "action"
+  ]
+}
+```
+
+来源：[`packages/goal/tool-goal/src/index.ts`](../packages/goal/tool-goal/src/index.ts)
+
+create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。
+
+## `@deepseek-ai/dsh-tool-lsp`
+
+### `lsp`
+
+查询语言服务器，以精确导航代码。operation 可取 goToDefinition、findReferences、goToImplementation 或 hover。line 和 character 是从 1 开始的 UTF-16 光标坐标。findReferences 包含声明。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "operation": {
+      "type": "string",
+      "description": "goToDefinition, findReferences, goToImplementation, or hover.",
+      "enum": [
+        "goToDefinition",
+        "findReferences",
+        "goToImplementation",
+        "hover"
+      ]
+    },
+    "file_path": {
+      "type": "string",
+      "description": "The source file to query, relative to the workspace or absolute."
+    },
+    "line": {
+      "type": "number",
+      "description": "One-based line of the cursor."
+    },
+    "character": {
+      "type": "number",
+      "description": "One-based UTF-16 column of the cursor."
+    }
+  },
+  "required": [
+    "operation",
+    "file_path",
+    "line",
+    "character"
+  ]
+}
+```
+
+来源：[`packages/lsp/tool-lsp/src/index.ts`](../packages/lsp/tool-lsp/src/index.ts)
+
+lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，因此其模型可见 schema 在更换提供方时保持稳定。运行时要求已注册提供方，例如 `@deepseek-ai/dsh-lsp-local`；如果没有提供方，查询会返回结构化 `LSP_UNAVAILABLE` 错误，而不会改变 schema。
+
+## `@deepseek-ai/dsh-tool-ralph`
+
+### `ralph`
+
+围绕一个不可变目标运行使用全新 agent 的前台 Ralph 循环。仅当直接人类明确要求 Ralph 或使用全新 agent 迭代时使用。每个 Round 都会启动一个全新子级，该子级看不到父级对话或先前子会话；共享工作区充当长期记忆，Round 之间只传递有界的结构化报告。当工作进程报告完成、报告具体阻塞项或达到 Round 上限时，调用返回。普通的长期同会话工作应使用 goal 工具。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "objective": {
+      "type": "string",
+      "description": "The immutable completion objective for every fresh Ralph round."
+    },
+    "maxRounds": {
+      "type": "number",
+      "description": "Optional positive safe-integer round cap, bounded by the deployment ceiling."
+    }
+  },
+  "required": [
+    "objective"
+  ]
+}
+```
+
+来源：[`packages/workflow/tool-ralph/src/index.ts`](../packages/workflow/tool-ralph/src/index.ts)
+
+固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。
+
+## `@deepseek-ai/dsh-tool-skill`
+
+### `skill`
+
+加载可用 skill（技能）的完整说明。在执行点名某项 skill 或与其明确匹配的任务前，请使用会话 skill 目录中的确切名称调用此工具。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The exact skill name from the available skills list."
+    }
+  },
+  "required": [
+    "name"
+  ]
+}
+```
+
+来源：[`packages/skill/tool-skill/src/index.ts`](../packages/skill/tool-skill/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-session-query`
+
+### `session_event_read`
+
+从一个已获授权的会话中读取一个完整且未删节的事件，以及可选的相邻原始事件概述。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "description": "Target session id. Omit for the current session."
+    },
+    "seq": {
+      "type": "integer",
+      "description": "Target event sequence number."
+    },
+    "before": {
+      "type": "integer",
+      "description": "Number of preceding raw events to summarize. Omit for none."
+    },
+    "after": {
+      "type": "integer",
+      "description": "Number of following raw events to summarize. Omit for none."
+    }
+  },
+  "required": [
+    "seq"
+  ]
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts)
+
+### `session_event_search`
+
+在一个已获授权的会话中搜索先前事件；如果搜索当前会话，则排除执行此次调用的步骤。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "description": "Target session id. Omit for the current session."
+    },
+    "query": {
+      "type": "string",
+      "description": "Literal full-text query over the target session."
+    },
+    "seq_from": {
+      "type": "integer",
+      "description": "Inclusive event sequence lower bound."
+    },
+    "seq_to": {
+      "type": "integer",
+      "description": "Inclusive event sequence upper bound."
+    },
+    "time_from": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 event-time lower bound."
+    },
+    "time_to": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 event-time upper bound."
+    },
+    "event_types": {
+      "type": "array",
+      "description": "Event types to include.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "surfaces": {
+      "type": "array",
+      "description": "Event surfaces to include.",
+      "items": {
+        "type": "string",
+        "enum": [
+          "current",
+          "shadowed",
+          "log-only"
+        ]
+      }
+    }
+  },
+  "required": [
+    "query"
+  ]
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts)
+
+### `session_event_trace`
+
+读取一个已获授权会话中某个事件的每项直接替换关系和来源关系。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "description": "Target session id. Omit for the current session."
+    },
+    "seq": {
+      "type": "integer",
+      "description": "Target event sequence number."
+    }
+  },
+  "required": [
+    "seq"
+  ]
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts)
+
+### `session_search`
+
+搜索调用方工作区中的先前会话，并从每个会话返回匹配度最高的事件。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "query": {
+      "type": "string",
+      "description": "Literal full-text query over prior session history."
+    },
+    "session_ids": {
+      "type": "array",
+      "description": "Optional session ids to include.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "created_at_from": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 creation-time lower bound."
+    },
+    "created_at_to": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 creation-time upper bound."
+    },
+    "parent_session_ids": {
+      "type": "array",
+      "description": "Optional direct parent session ids.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "include_root_sessions": {
+      "type": "boolean",
+      "description": "Include sessions with no parent in the parent filter."
+    },
+    "availability": {
+      "type": "array",
+      "description": "Require at least one selected source availability.",
+      "items": {
+        "type": "string",
+        "enum": [
+          "live",
+          "persisted"
+        ]
+      }
+    },
+    "event_seq_from": {
+      "type": "integer",
+      "description": "Inclusive event sequence lower bound."
+    },
+    "event_seq_to": {
+      "type": "integer",
+      "description": "Inclusive event sequence upper bound."
+    },
+    "event_time_from": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 event-time lower bound."
+    },
+    "event_time_to": {
+      "type": "string",
+      "description": "Inclusive timezone-qualified ISO 8601 event-time upper bound."
+    },
+    "event_types": {
+      "type": "array",
+      "description": "Event types to include.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "event_surfaces": {
+      "type": "array",
+      "description": "Event surfaces to include.",
+      "items": {
+        "type": "string",
+        "enum": [
+          "current",
+          "shadowed",
+          "log-only"
+        ]
+      }
+    }
+  },
+  "required": [
+    "query"
+  ]
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts)
+
+### `session_trace`
+
+读取围绕一个会话的已授权会话谱系，包括完整可见的祖先和后代关系。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "description": "Target session id. Omit for the current session."
+    }
+  }
+}
+```
+
+来源：[`packages/session-query/tool-session-query/src/index.ts`](../packages/session-query/tool-session-query/src/index.ts)
+
+这 5 个只读工具会隐藏提供方游标，并根据不可变的调用 agent 会话为每个结果授权。该包需要选择启用；需要强制截止时间或限制行内输出的组合还会挂载通用超时或 spill 策略。
+
+## `@deepseek-ai/dsh-tool-subagent`
+
+### `subagent`
+
+将一项自包含任务委派给 subagent（在自身上下文中工作的独立 agent），并返回其最终结果。可用它卸载聚焦且独立的工作，例如研究、限定范围的实现或分析，以免消耗当前对话的上下文。subagent 会运行到完成；你只会收到最终答案，而看不到中间步骤。请提供完整、独立的提示词，因为它看不到当前对话。设置 `run_in_background: true` 可返回 task id；使用 `task_output` 收集结果，使用 `task_kill` 停止任务。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "description": {
+      "type": "string",
+      "description": "A short (3-5 word) description of the delegated task, for display."
+    },
+    "prompt": {
+      "type": "string",
+      "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+    },
+    "run_in_background": {
+      "type": "boolean",
+      "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
+    }
+  },
+  "required": [
+    "description",
+    "prompt"
+  ]
+}
+```
+
+来源：[`packages/subagent/tool-subagent/src/index.ts`](../packages/subagent/tool-subagent/src/index.ts)
+
+注册的工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述 schema 对应默认值。随产品发布的示例 agent 会为每个 subagent 后端加载一次该包，因此模型还会看到 schema 相同、绑定到 fork 后端的 `subagent_fork`；见 `packages/bundle/base/cordis.patch.yml` 和 `examples/acp-agent/cordis.yml`。
+
+## `@deepseek-ai/dsh-tool-subagent-control`
+
+### `interrupt_agent`
+
+根据 agent id 请求取消后台 agent 的当前轮次。目标可以是你的直接子级，也可以是在你下方创建的更深层 agent。只有当前轮次会停止：已经排队发给该 agent 的消息会一直搁置到后续的 send_message；它启动的 agent 会继续运行；该 agent 本身仍可接受后续操作。停止请求被接受后，此调用立即返回，因此目标可能还会短暂运行；中断一个已经完成的 agent 是可接受的空操作。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "agent_id": {
+      "type": "string",
+      "description": "The agent id of the running agent to interrupt."
+    }
+  },
+  "required": [
+    "agent_id"
+  ]
+}
+```
+
+来源：[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
+
+### `list_agents`
+
+按持久 id 和标签列出你的可继续后台 subagent。状态来自实时注册表：running 表示 agent 此刻正在工作；idle 表示已加载但处于轮次之间，可能正在等待它启动的 agent；complete 表示它只存在于存储中。无论处于哪种状态，直接子级都仍可作为 `send_message` 的目标。该快照并非投递承诺；`send_message` 会执行权威检查，仍可能失败。无法读取的子级会作为诊断信息报告，而不会被静默丢弃。`descendants` 作用域会按稳定的前序顺序遍历你下方的整棵树，并为每个条目标注其持久的直接父会话 id 和深度。只有深度为 1 的条目可以使用 `send_message`；更深的条目只能作为 `interrupt_agent` 的候选目标。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "scope": {
+      "type": "string",
+      "description": "children (default) lists direct children only; descendants walks the complete tree below you.",
+      "enum": [
+        "children",
+        "descendants"
+      ]
+    }
+  }
+}
+```
+
+来源：[`packages/subagent/tool-subagent-control/src/list-agents.ts`](../packages/subagent/tool-subagent-control/src/list-agents.ts)
+
+### `send_message`
+
+根据 subagent id 向后台 subagent 发送消息，继续同一段对话。该消息会成为 subagent 的下一轮次：如果它仍在工作，消息会等待当前轮次结束，因此无法改变已经开始的工作方向。此调用不会返回 subagent 的答案，只会确认消息已投递，因此请用它分派更多工作。调用失败表示消息**未**投递。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "subagent_id": {
+      "type": "string",
+      "description": "The subagent id returned when the background subagent was started."
+    },
+    "message": {
+      "type": "string",
+      "description": "The message to deliver to the subagent."
+    }
+  },
+  "required": [
+    "subagent_id",
+    "message"
+  ]
+}
+```
+
+来源：[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
+
+这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，并通过单独加载的 `/list-agents` 插件提供 `list_agents`，其目录行使用 sessionProjections 和实时 Agent 注册表。
+
+## `@deepseek-ai/dsh-tool-subagent-report`
+
+### `report`
+
+向启动你的 agent 报告选定内容。你可以调用 0 次或多次，以报告进度、发现或最终答案。报告不会结束你的轮次或完成你的工作，且只有直接父级会收到。失败的调用仍可能已经送达，因此不要盲目重复。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "output": {
+      "type": "string",
+      "description": "Self-contained content for your parent; it does not see your private work."
+    }
+  },
+  "required": [
+    "output"
+  ]
+}
+```
+
+来源：[`packages/subagent/tool-subagent-report/src/index.ts`](../packages/subagent/tool-subagent-report/src/index.ts)
+
+按可继续的进程内子级注册，而非全局注册，因此该 schema 仅在这种子级内部可见，并且不受其全局 `toolFilter` 影响。面向父级的 `send_message` 工具单独安装。
+
+## `@deepseek-ai/dsh-tool-tasks`
+
+### `task_kill`
+
+根据 task id 请求取消正在运行的后台任务。此调用立即返回；任务的工作真正停止后，会以 killed 状态结算。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "Task id returned by the tool that started the background work."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Optional short reason, recorded in the log and forwarded to the task."
+    }
+  },
+  "required": [
+    "task_id"
+  ]
+}
+```
+
+来源：[`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+### `task_list`
+
+列出你的后台任务（包括正在运行和已完成的任务）及其 id、种类和状态。
+
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+来源：[`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+### `task_output`
+
+读取后台任务。流式任务只返回自上次读取以来的输出；最终输出任务会在结算后返回结果。每个响应都以 `[status: ...]` 结尾。读取默认不阻塞；设置 `wait: true` 后，最长等待到配置的上限。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "Task id returned by the tool that started the background work."
+    },
+    "wait": {
+      "type": "boolean",
+      "description": "Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."
+    },
+    "timeout_ms": {
+      "type": "number",
+      "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+    }
+  },
+  "required": [
+    "task_id"
+  ]
+}
+```
+
+来源：[`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+与任务种类无关的后台任务控制接口：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制接口，从而启用生产方的 `ctx.tasks.start()`。
+
+## `@deepseek-ai/dsh-tool-todo`
+
+### `todo_write`
+
+记录并更新当前工作的结构化任务列表。每次调用都要发送**完整列表**，它会**替换**之前的列表，不支持局部更新或逐项编辑。请用它规划多步骤工作并展示进度：开始前为每个具体步骤添加一项 todo。将当前正在处理的每项 todo 标记为 `in_progress`；确实并行运行时（例如并发 subagent 或后台命令）可同时标记多项，顺序工作则标记 1 项。只要工作尚未完成，就应至少有一项任务为 `in_progress`。某项 todo 完成后立即标记为 `completed`，不要批量标记完成；只有全部工作完成后，才可以没有 `in_progress` 项。简单的单步骤任务无需使用列表。状态：`pending`（未开始）、`in_progress`（正在处理）、`completed`（已完成）。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "todos": {
+      "type": "array",
+      "description": "The COMPLETE task list, replacing any previous list.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "content": {
+            "type": "string",
+            "description": "What the task is — a short imperative line."
+          },
+          "status": {
+            "type": "string",
+            "description": "pending (not started) | in_progress (now) | completed (done).",
+            "enum": [
+              "pending",
+              "in_progress",
+              "completed"
+            ]
+          }
+        },
+        "required": [
+          "content",
+          "status"
+        ]
+      }
+    }
+  },
+  "required": [
+    "todos"
+  ]
+}
+```
+
+来源：[`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts)
+
+todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项，因此本目录明确选择 `true`，对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具，但描述会要求只能有 1 个活动任务。
+
+## `@deepseek-ai/dsh-tool-workflow`
+
+### `workflow`
+
+运行用于大规模编排 subagent 的 JavaScript 工作流脚本。当工作会分散到许多相互独立的部分时，请使用此工具，例如审查大量文件、执行迁移、开展多角度研究或对发现进行对抗式验证；此时应将编排写成脚本，而不是逐轮委派。
+
+工作流的身份通过 `meta` 参数以 JSON 形式传入：必填的 `name`（简短 kebab-case）和 `description` 字符串，以及可选的 `whenToUse` 字符串和 `phases` 数组（`{title, detail?, provider?, model?}`）。`script` 参数只能是纯 JavaScript **函数体**，不能是 TypeScript，也不能包含 `export const meta` 语句；meta 是参数而非代码。脚本支持顶层 await；请以 `return <value>` 结尾，该值必须可以 JSON 序列化，并作为此工具的结果。
+
+脚本函数体提供以下钩子：
+
+- `agent(prompt, opts?): Promise<any>`：运行一个 subagent 直至完成。不提供 `opts.schema` 时，解析为子级最终文本；提供 `opts.schema` 时，它必须是以对象为根、且**只能**使用 type/properties/required/additionalProperties/items/enum/const/oneOf 的 JSON Schema，不支持 pattern/format/数值边界，此时解析为通过校验的对象。子级失败时解析为 `null`，可使用 `.filter(Boolean)` 过滤。其他选项包括 `label`（显示名称）、`phase`（进度组），以及相互独立的 `provider`／`model` LLM（大语言模型）目标覆盖项，两者可单独提供。其他任何选项（`effort`／`isolation`／`agentType`）都会明确报错。
+- `pipeline(items, ...stages): Promise<any[]>`：让每个条目分别经过各阶段，阶段之间**没有**屏障；多阶段工作优先使用它。每个阶段接收 `(prev, item, index)`。普通的阶段异常会将该**条目**变为 `null`，并跳过它的剩余阶段。
+- `parallel(thunks): Promise<any[]>`：并发运行零参数函数并等待**全部**完成。它会形成屏障，仅当某个阶段确实需要汇总全部先前结果时使用。抛出异常的 thunk 解析为 `null`。
+- `phase(title)`：开始一个进度阶段；`log(message)`：说明进度；`args`：工具调用的 `args` 输入，原样提供。
+
+如果误用钩子（参数错误、未知选项、不受支持的 schema、触发上限），抛出的错误**总会**终止脚本，绝不会退化为单个条目的 `null`。
+
+约束：并发上限和 agent 总数上限均会生效；不提供文件系统、网络、定时器或 Node.js API。具体工作由 agent 完成，脚本只负责编排。该运行在前台执行：整个脚本完成后，调用才会返回。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "script": {
+      "type": "string",
+      "description": "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."
+    },
+    "meta": {
+      "type": "object",
+      "description": "The workflow identity block (plain JSON — never code).",
+      "additionalProperties": true,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Short kebab-case workflow name."
+        },
+        "description": {
+          "type": "string",
+          "description": "One-line description of what the workflow does."
+        },
+        "whenToUse": {
+          "type": "string",
+          "description": "Optional guidance on when this workflow applies."
+        },
+        "phases": {
+          "type": "array",
+          "description": "Optional phase declarations matched by phase() calls.",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "The phase title phase() calls match by exact string."
+              },
+              "detail": {
+                "type": "string",
+                "description": "Optional one-line description of the phase."
+              },
+              "provider": {
+                "type": "string",
+                "description": "Optional provider override this phase is expected to use."
+              },
+              "model": {
+                "type": "string",
+                "description": "Optional model override this phase is expected to use."
+              }
+            },
+            "required": [
+              "title"
+            ]
+          }
+        }
+      },
+      "required": [
+        "name",
+        "description"
+      ]
+    },
+    "args": {
+      "type": "object",
+      "description": "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).",
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "script",
+    "meta"
+  ]
+}
+```
+
+来源：[`packages/workflow/tool-workflow/src/index.ts`](../packages/workflow/tool-workflow/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-web`
+
+### `web_fetch`
+
+获取指定 HTTP(S) URL 的内容，并将其解码为文本后返回。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "url": {
+      "type": "string",
+      "description": "The HTTP(S) URL to fetch."
+    }
+  },
+  "required": [
+    "url"
+  ]
+}
+```
+
+来源：[`packages/web/tool-web/src/index.ts`](../packages/web/tool-web/src/index.ts)
+
+### `web_search`
+
+在 Web 上搜索最新信息。返回可选的摘要答案和源 URL 列表。
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "query": {
+      "type": "string",
+      "description": "The search query."
+    }
+  },
+  "required": [
+    "query"
+  ]
+}
+```
+
+来源：[`packages/web/tool-web/src/index.ts`](../packages/web/tool-web/src/index.ts)
+
+web_search 和 web_fetch 将提供方选择置于 ctx.web 之后，使模型可见 schema 在更换后端时保持稳定。
diff --git a/docs/tool-execution-pipeline.i18n.yaml b/docs/tool-execution-pipeline.i18n.yaml
new file mode 100644
index 0000000000..037e063125
--- /dev/null
+++ b/docs/tool-execution-pipeline.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 docs/tool-execution-pipeline.md
+tool-execution-pipeline.md: 16a4461b6c995f666882635dddb25e1a6cf79c73
+tool-execution-pipeline.zh.md: 3b5226c5ea8038c0fc5154cd37a77d92f6e3d0e1
diff --git a/docs/tool-execution-pipeline.zh.md b/docs/tool-execution-pipeline.zh.md
new file mode 100644
index 0000000000..3b5226c5ea
--- /dev/null
+++ b/docs/tool-execution-pipeline.zh.md
@@ -0,0 +1,64 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/tool-execution-pipeline.md` 重新记录配对。 -->
+
+# 工具执行流水线
+
+[English](tool-execution-pipeline.md) | 中文
+
+此图展示了策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染如何在不改变循环的前提下各就其位。可转换的扩展点是 `tools/pre-execute`、`tools/execute` 和 `tools/post-execute` waterfall（瀑布式事件）；围绕这些扩展点的边界则由所有者强制执行，包括单调守卫、由定义自身控制的 `finalizeContent`，以及 `tools/result`。
+
+```mermaid
+flowchart TD
+  model["Assistant message contains tool-call block"]
+  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
+  presentCall["UI pending card<br/>presentCall(args)"]
+  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
+  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
+  denied["denied or approval refused<br/>tool body skipped"]
+  approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
+  around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
+  toolBody["Registered tool execute() body"]
+  fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
+  owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/code-dispatch</code>"]
+  post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
+  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
+  finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
+  final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
+  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
+  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
+  allResults["Tool batch settled<br/>recorded tool/result events complete"]
+  presentResult["UI completed card<br/>presentResult(args, result)"]
+  model --> toolCall
+  toolCall --> presentCall
+  toolCall --> pre
+  pre -->|allow| guards
+  guards -->|allow| around
+  guards -->|deny| denied
+  guards -.->|throw| normalized
+  around --> toolBody
+  pre -->|deny| denied
+  pre -->|ask| approval
+  approval -->|allowed-once| guards
+  approval -->|rejected, cancelled, unavailable| denied
+  approval -.->|throw| normalized
+  denied --> post
+  pre -.->|throw| normalized
+  toolBody --> fsGate
+  fsGate --> toolBody
+  toolBody --> owned
+  toolBody --> around
+  around --> post
+  around -.->|wrapper throws| normalized
+  post -.->|throw| normalized
+  post --> finalize
+  normalized --> finalize
+  finalize --> final
+  final --> toolResult
+  toolResult --> presentResult
+  toolResult --> allResults
+  allResults --> context
+```
+
+文件系统的先读后编辑检查位于 `tool-fs` 之下，通过 `fs/*` 事件实现。通用的前置／后置 waterfall 承载钩子与审批策略；`ctx.approval` 在单调守卫之前处理询问，而不得重新排序的所有者策略仍作为已注册的守卫。超时等环绕分发关注点对 `tools/execute` 进行包装。注册表会对候选结果进行无损快照；如果快照失败，则会先将失败规范化，之后再由可见定义中已随快照固定的 `finalizeContent` 回调强制执行其同步且仅限内容的不变式。随后，`tools/result` 会观察不可变、可由 JSON 无损表示的结果。这样一来，钩子便可跨越不同工具系列，而无需让工具与某个策略服务耦合。Code Mode 会将保留的 `run_code` 传输及其序列化子调用都送入流水线；子调用携带父级 token、记录 `tool/code-dispatch`、将拒绝呈现为具有约束力的驳回，并省略 `additionalContexts`，以保持调用与结果相邻。
+
+维护模式：英文源文件包含人工维护的 Mermaid 流程图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的工具 schema 与事件签名位于生成的目录中。
diff --git a/docs/user/develop/basic/publish.i18n.yaml b/docs/user/develop/basic/publish.i18n.yaml
index da74ce8d7c..b387f7a0b6 100644
--- a/docs/user/develop/basic/publish.i18n.yaml
+++ b/docs/user/develop/basic/publish.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/publish.md
 publish.md: 1d1179a78c4d3a7e9e7055e3f5ee41381e28147e
-publish.zh.md: 26d1c2b737a3498bce0757d5b2d14e254fc13527
+publish.zh.md: d683762b78920dc754b6871ed7bd0caf3ee9afd4
diff --git a/docs/user/develop/basic/publish.zh.md b/docs/user/develop/basic/publish.zh.md
index 26d1c2b737..d683762b78 100644
--- a/docs/user/develop/basic/publish.zh.md
+++ b/docs/user/develop/basic/publish.zh.md
@@ -2,14 +2,14 @@
 
 [English](publish.md) | 中文
 
-前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**（bundle），用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。请先完成[插件配置](./config.md)。
+前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**，用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。请先完成[插件配置](./config.md)。
 
-## 两个概念，两种 manifest
+## 两个概念，两种 manifest（元数据清单）
 
-安装机制建立在两个概念之上。二者都由一份 `package.json` 描述，但它们在 `dsh` 键下携带的 manifest（元数据清单）种类不同，回答的问题也不同：
+安装机制建立在两个概念之上。二者都由一份 `package.json` 描述，但它们在 `dsh` 键下携带的 manifest 种类不同，回答的问题也不同：
 
-- **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是"这个包贡献什么？"：一个插入或覆盖插件行的 patch 文件。
-- **profile** 是位于 `$DSH_HOME/profiles/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是"这套配置由哪些组合包按什么顺序组成？"。
+- **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是「这个包贡献什么？」：一个插入或覆盖插件行的 patch 文件。
+- **profile** 是位于 `$DSH_HOME/profiles/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是「这套配置由哪些组合包按什么顺序组成？」。
 
 组合包是你编写并分发的东西；profile 是用户用 `dsh --profile <name>` 启动的东西。没有东西同时是两者。
 
@@ -41,7 +41,7 @@ patch 文件的形状与你一直在写的 `--patch` overlay 相同——一个
       name: dsh-hello-plugin
 ```
 
-没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。这正是"供插件包 import 的库"应有的形状，区别于"供用户启用的插件"。
+没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。这正是「供插件包 import 的库」应有的形状，区别于「供用户启用的插件」。
 
 ### profile manifest
 
@@ -127,7 +127,7 @@ dsh plugin --profile demo add github:you/hello-plugin
 
   然后重新执行 `add`。
 
-请如实看待这项授权：**允许该包的代码在安装时于你的机器上执行**，且不在 agent 运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
+请如实看待这项授权：**允许该包的代码在安装时于你的机器上执行**，且不在 agent（智能体）运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
 
 如果不想让用户做这项授权，就改为分发构建产物——以下两种形式都不需要任何构建权限：
 
diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml
index 954eab633d..10e4f2429b 100644
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/config.md
 config.md: 34ab38c60cc7a9b6026f5be2be47f440eb6cb08d
-config.zh.md: ce965dfc67c759ffcbad7b044b74abb2025851c2
+config.zh.md: 621b5a75a98ab4b8d8517f4ec8894db0472e994c
diff --git a/docs/user/guide/config.zh.md b/docs/user/guide/config.zh.md
index ce965dfc67..621b5a75a9 100644
--- a/docs/user/guide/config.zh.md
+++ b/docs/user/guide/config.zh.md
@@ -47,7 +47,7 @@ Cordis 会并发启动同级配置项。插件通过 `inject` 声明必需服务
 
 ## CLI 补丁层
 
-`dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、每个 `--patch <path>` overlay，最后是 CLI（命令行界面）标志补丁。同一行以较后的层为准。
+`dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、home 级 `$DSH_HOME/cordis.patch.yml`、每个 `--patch <path>` overlay，最后是 CLI（命令行界面）标志补丁。同一行以较后的层为准。
 
 补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKeyEnv` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
 
@@ -64,4 +64,4 @@ config:
 
 ## 精确配置参考
 
-每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力接口](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。
+每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力 seam](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。
diff --git a/docs/user/guide/index.i18n.yaml b/docs/user/guide/index.i18n.yaml
index a48c5bf842..056122d1fb 100644
--- a/docs/user/guide/index.i18n.yaml
+++ b/docs/user/guide/index.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/index.md
 index.md: a04698e29755d4a08b012f8b61accb79c470dcb0
-index.zh.md: 85990f49c7b3cdf7518237c6b558375b7a636243
+index.zh.md: 3808d9506fa9cb3a3e455ed478e4f02c18fc09ab
diff --git a/docs/user/guide/index.zh.md b/docs/user/guide/index.zh.md
index 85990f49c7..3808d9506f 100644
--- a/docs/user/guide/index.zh.md
+++ b/docs/user/guide/index.zh.md
@@ -2,11 +2,11 @@
 
 [English](index.md) | 中文
 
-DeepSeek Harness 是一个**插件化的 Agent 开发框架**，基于 [Cordis](https://github.com/cordiverse/cordis) 微内核构建。它的核心理念是：**一切皆插件**。
+DeepSeek Harness 是一个**插件化的 agent（智能体）开发框架**，基于 [Cordis](https://github.com/cordiverse/cordis) 微内核构建。它的核心理念是：**一切皆插件**。
 
 ## 它是什么
 
-Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调用、工具执行、会话管理、子任务分配——全部构建为可组合的插件。你通过一个 `cordis.yml` 配置文件来声明加载哪些插件、使用什么参数，就能组装出一个完整的 Agent。
+Harness 将 AI（人工智能） agent 所需的所有能力——LLM（大语言模型）调用、工具执行、会话管理、子任务分配——全部构建为可组合的插件。你通过一个 `cordis.yml` 配置文件来声明加载哪些插件、使用什么参数，就能组装出一个完整的 agent。
 
 ```yaml
 # Select the LLM backend
@@ -27,26 +27,26 @@ Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调
 
 ### 应用使用者
 
-如果你只是想用一个现成的 Agent 应用（如编程助手、对话代理），你需要的全部操作就是：
+如果你只是想用一个现成的 agent 应用（如编程助手、对话代理），你需要的全部操作就是：
 
-1. 复制一个 example 模板
-2. 填写 API key
-3. 运行
+1. 复制一个示例模板。
+2. 填写 API 密钥。
+3. 运行。
 
 不需要写任何代码。详见 [快速开始](./quickstart.md)。
 
 ### 插件开发者
 
-如果你想为 Agent 添加新能力——一个自定义 tool、一个新的 LLM 适配器、一个新的执行后端——你需要编写一个插件。Harness 提供了清晰的扩展接口和类型安全的开发体验。详见 [开发](../develop/basic/)。
+如果你想为 agent 添加新能力——一个自定义工具、一个新的 LLM 适配器、一个新的执行后端——你需要编写一个插件。Harness 提供了清晰的扩展接口和类型安全的开发体验。详见 [开发](../develop/basic/)。
 
-## 核心特性
+## 核心功能
 
 - **只需要配置** — `cordis.yml` 决定能力集合，换模型、加工具只需改一行
-- **随时替换 (HMR)** — 开发时修改插件代码，无需重启进程
+- **HMR（热模块替换）** — 开发时修改插件代码，无需重启进程
 
 ## 技术栈
 
-- **运行时**: Node.js ^22.19 或 >= 24
-- **语言**: TypeScript (ESM)
-- **框架**: Cordis
-- **包管理**: pnpm workspaces（仓库固定使用 pnpm 11）
+- **运行时**：Node.js ^22.19 或 >= 24
+- **语言**：TypeScript（ESM）
+- **框架**：Cordis
+- **包管理**：pnpm workspaces（仓库固定使用 pnpm 11）
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 38df7fb986..3795c8dcec 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/providers.md
 providers.md: 8b52044e64411e3081d56c1ee1849d0b24cd1cda
-providers.zh.md: f4a42a4093d253b4b230e4a838ba275a0ce58ac9
+providers.zh.md: 0e48c31c7006a5c9c0b014e46bc7915d625389db
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index f4a42a4093..0e48c31c70 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -2,14 +2,14 @@
 
 [English](providers.md) | 中文
 
-Harness 出厂自带 DeepSeek，同时预装了一个通用的多提供方适配器，用来接入 Anthropic、OpenAI 这类内置目录里的提供方，或任何 OpenAI 兼容的网关与自建服务。你有两个入口：Web 界面的**模型**页，以及 `$DSH_HOME/settings.yaml`。两者写的是同一份文档，改完下一次请求即生效，不用重启。
+Harness 出厂自带 DeepSeek，同时预装了一个通用的多提供方适配器，用来接入 pi-ai 已安装目录中的 Anthropic、OpenAI 等提供方，或任何 OpenAI 兼容的网关与自建服务。你有两个入口：Web 界面的**模型**页，以及 `$DSH_HOME/settings.yaml`。两者写的是同一份文档，改完下一次请求即生效，不用重启。
 
 ## 提供方从哪里来
 
 `cordis.yml` 决定装了哪些**适配器**，settings 文档决定跑哪些**提供方**。出厂组合里有两个 LLM 适配器：
 
 - `llm-deepseek` 提供 `deepseek-official` 路由，是默认可用的那个。
-- `llm-pi-ai` 以**休眠**状态挂载：零路由，模型选择器里也不会多出条目，直到 settings 里的 `llm-pi-ai:` 段落给出 provider profile，路由才注册上来；段落清空则一并撤下。
+- `llm-pi-ai` 以**休眠**状态挂载：零路由，模型选择器里也不会多出条目，直到 settings 里的 `llm-pi-ai:` 段落给出提供方 profile，路由才注册上来；段落清空则一并撤下。
 
 因此新增一个提供方通常不需要改 `cordis.yml`，写 settings 就够了——而模型页做的正是这件事。
 
@@ -120,7 +120,7 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 在 `dsh` 下，引用依次从继承环境、模型页的 `$DSH_HOME/.credentials.yaml` 存储、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析。未挂载凭据服务时，引用只读取同名环境变量。一份凭据供该路由上的所有模型使用。
 
-## 让 agent 用上新提供方
+## 让 agent（智能体）用上新提供方
 
 配好的路由会出现在 Web 的模型选择器里，随时可切，这也是最常用的方式。
 
@@ -133,7 +133,7 @@ api-gateway:
   reasoningEffort: high   # optional
 ```
 
-已经跑过一轮的会话不会被它重定向——那个会话从自己的日志推导路由，因此改默认值只影响还没开始的会话。这个段落之下的出厂兜底是 `api-gateway` 组合条目（`deepseek-official` / `deepseek-v4-flash`），自行组装的 `cordis.yml` 可以覆盖它；自行组装的组合（例如 headless）改的则是 `agent-loop` 的 `agents`。
+已经跑过一个轮次的会话不会被它重定向——那个会话从自己的日志推导路由，因此改默认值只影响还没开始的会话。这个段落之下的出厂兜底是 `api-gateway` 组合条目（`deepseek-official` / `deepseek-v4-flash`），自行组装的 `cordis.yml` 可以覆盖它；自行组装的组合（例如 headless）改的则是 `agent-loop` 的 `agents`。
 
 如果某个已存默认值指向的提供方后来被删掉了，输入框会显示**选择模型**并拒绝输入，而不是把消息发给一个没人服务的路由。
 
diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml
index dfdba88bec..a2e09bd132 100644
--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/quickstart.md
 quickstart.md: 9d1a04f0a094919bb008a7e94564a6612e10732d
-quickstart.zh.md: 7182f63586f4f08524c643a7c6c1ad599b2de098
+quickstart.zh.md: 4c62b0a9deda3559f29ad214903ca55aea8b970e
diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md
index 7182f63586..4c62b0a9de 100644
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -2,13 +2,13 @@
 
 [English](quickstart.md) | 中文
 
-本指南带你在 5 分钟内跑起一个 Agent。
+本指南带你在 5 分钟内跑起一个 agent（智能体）。
 
 ## 环境准备
 
 - [Node.js](https://nodejs.org/) ^22.19 或 >= 24
 - 通过 Corepack 使用 [pnpm](https://pnpm.io/) 11
-- [DeepSeek Platform](https://platform.deepseek.com/) API key
+- [DeepSeek Platform](https://platform.deepseek.com/) API 密钥
 
 ```sh
 node -v
@@ -16,7 +16,7 @@ corepack enable
 pnpm -v
 ```
 
-## 第一步：安装并配置 API key
+## 第一步：安装并配置 API 密钥
 
 ```sh
 git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
@@ -39,7 +39,7 @@ DEEPSEEK_API_KEY=sk-your-key-here
 pnpm run dsh run "summarize the architecture of this workspace"
 ```
 
-`dsh run` 创建并持久化一个新会话，打印最终 assistant 回答，然后退出。运行期间，stderr 会打印可用于观察该会话的本地浏览器 URL。
+`dsh run` 创建并持久化一个新会话，打印最终助手回答，然后退出。运行期间，stderr 会打印可用于观察该会话的本地浏览器 URL。
 
 ## 第三步：使用 Web UI
 
@@ -51,12 +51,12 @@ pnpm run dsh web
 
 打开 `http://127.0.0.1:3080`。agent 可以读写文件、运行命令、分配子任务和跟踪计划。可以尝试：`Create hello.js in the current directory, print "Hello from Harness!", and run it`。
 
-## 回头看
+## 运行原理
 
-`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml)、[`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合。`dsh web` 使用前两层，不包含一次性 runner。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
+`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml)、[`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合。`dsh web` 使用前两层，不包含一次性运行器。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
 
 ## 下一步
 
 - [配置模型](./providers.md) — 接入 DeepSeek 之外的提供方与自定义网关
 - [配置文件](./config.md) — 了解 `cordis.yml` 的格式
-- [开发插件](../develop/basic/) — 编写自己的 tool 或后端
+- [开发插件](../develop/basic/) — 编写自己的工具或后端
diff --git a/docs/web-styling.i18n.yaml b/docs/web-styling.i18n.yaml
index 0cbbafeec9..55277809ef 100644
--- a/docs/web-styling.i18n.yaml
+++ b/docs/web-styling.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/web-styling.md
 web-styling.md: 5296cc7f83f712532262eadda6da098ae9f63ec7
-web-styling.zh.md: 6beec368f2f7fd5eb7606acfaae315d56899c739
+web-styling.zh.md: bec623911269cbd7020c26d5574ee88ca074b5d8
diff --git a/docs/web-styling.zh.md b/docs/web-styling.zh.md
index 6beec368f2..bec6239112 100644
--- a/docs/web-styling.zh.md
+++ b/docs/web-styling.zh.md
@@ -8,7 +8,7 @@
 
 [`ui-theme`](../packages/client/ui-theme/README.md) 负责 `--dsw-*` 静态色阶、语义别名、排版、动效、渐变、阴影、滚动条样式以及明暗主题偏好。[`ui-layout`](../packages/client/ui-layout/README.md) 将解析后的主题快照应用到文档。功能包使用语义别名，不得另行定义全局主题。
 
-全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于组件自身的布局或呈现契约时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
+全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于组件自身的布局或呈现约定时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
 
 ## 组件规则
 
@@ -16,10 +16,10 @@
 - 功能组件使用 `--dsw-alias-*` 语义 token。不得复制静态色板值或在其中写入颜色字面量。
 - 功能组件 CSS 不得包含主题选择器。明暗主题覆盖属于主题所有方。
 - 字体大小必须与行高配对；已有角色匹配时使用主题排版变量。
-- 当组件契约要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
+- 当组件约定要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
 - 呈现规则写在 CSS 中。React 内联样式可以传递组件局部自定义属性值，但不得编码主题分支。
 - 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
 
 ## 变更系统
 
-在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式契约发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 记录框架依据。
+在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 记录框架依据。
diff --git a/examples/web-cordis/README.i18n.yaml b/examples/web-cordis/README.i18n.yaml
index 86cc276a4e..e515bf5f71 100644
--- a/examples/web-cordis/README.i18n.yaml
+++ b/examples/web-cordis/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write examples/web-cordis/README.md
 README.md: 21fe0a210b2e591a96dc254014a0f91ed9afa2ba
-README.zh.md: 35158affd5cbdd6f8fa7f5910500f21c2b241309
+README.zh.md: 660ff5f8db5d7d4e3eb8a10d842818ce9ce30e17
diff --git a/examples/web-cordis/README.zh.md b/examples/web-cordis/README.zh.md
index 35158affd5..660ff5f8db 100644
--- a/examples/web-cordis/README.zh.md
+++ b/examples/web-cordis/README.zh.md
@@ -18,4 +18,4 @@ pnpm run demo:cordis
 pnpm run demo:cordis acp
 ```
 
-这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全契约由 [Cordis 工具参考](../../packages/self-modification/tool-cordis/README.md)定义。
+这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全约定由 [Cordis 工具参考](../../packages/self-modification/tool-cordis/README.md) 定义。
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 039e8bb78d..25b3709d91 100644
--- a/packages/README.i18n.yaml
+++ b/packages/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/README.md
 README.md: 7589f37b174b94558bff9f74f860bb4b42705fb8
-README.zh.md: 4e99dd9313cca89e84ae0bfaf4a2179d726da864
+README.zh.md: e7b8b0ab2b5bb5bd38d7068091bc675e1d27f84a
diff --git a/packages/README.zh.md b/packages/README.zh.md
index 4e99dd9313..e7b8b0ab2b 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -10,46 +10,46 @@
 
 | 组 | 职责 | 发布预期 |
 |---|---|---|
-| [`core/`](core/README.md) | 产品 API 主干：会话、提示词、工具、agent（智能体）服务与具体循环 | 产品：稳定表面 |
-| [`api/`](api/README.md) | Remote BFF 装配与 TypeRT RPC Gateway | 产品：稳定表面 |
-| [`typert/`](typert/README.md) | 类型图生成、产物加载与运行时注册表 | 产品：稳定表面 |
-| [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
-| [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |
-| [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
+| [`core/`](core/README.md) | 产品 API 主干：会话、提示词、工具、agent（智能体）服务与具体循环 | 产品：稳定接口 |
+| [`api/`](api/README.md) | Remote BFF 装配与 TypeRT RPC Gateway | 产品：稳定接口 |
+| [`typert/`](typert/README.md) | 类型图生成、产物加载与运行时注册表 | 产品：稳定接口 |
+| [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定接口 |
+| [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定接口 |
+| [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定接口 |
 | [`e2b/`](e2b/README.md) | E2B 提供方 | POC |
-| [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
-| [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
-| [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定表面 |
-| [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定表面 |
-| [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定表面 |
-| [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定表面 |
-| [`skill/`](skill/README.md) | Skill（技能）能力系列：提供方注册表、本地提供方和面向模型的目录／加载器 | 产品：稳定表面 |
-| [`compact/`](compact/README.md) | 压缩（compaction）能力系列：抽象 seam + 基础后端（工具延后） | 产品：稳定表面 |
-| [`context/`](context/README.md) | 模型可见请求上下文，包括 workspace 指令和时间上下文 | 产品：稳定表面 |
-| [`subagent/`](subagent/README.md) | Subagent 能力系列：提供方注册表 seam 和面向模型的委托工具 | 产品：稳定表面 |
-| [`tasks/`](tasks/README.md) | 通用后台任务运行时和面向模型的 `task_*` 控制工具 | 产品：稳定表面 |
-| [`workflow/`](workflow/README.md) | 脚本 seam、worker 线程引擎和面向模型的 `workflow`/`ralph` 工具 | 产品：稳定表面 |
-| [`web/`](web/README.md) | Web 能力系列：seam、搜索／获取提供方实现和面向模型的 Web 工具 | 产品：稳定表面 |
-| [`spill/`](spill/README.md) | 溢出能力系列：存储 seam、本地实现、工具结果溢出策略 | 产品：稳定表面 |
-| [`todo/`](todo/README.md) | 面向模型的 `todo_write` 工具 | 产品：稳定表面 |
-| [`plan/`](plan/README.md) | Plan 协作状态，提供直接进入命令与经评审的退出 | 产品：稳定表面 |
-| [`guard/`](guard/README.md) | 循环卫生守卫：建议性重复调用提醒 + `tools/execute` 截止时间强制执行器 | 产品：稳定表面 |
-| [`bundle/`](bundle/README.md) | 可安装的 `dsh --profile` 补丁层 | 产品：稳定表面 |
-| [`self-modification/`](self-modification/README.md) | agent 修改自身运行时：检查实时运行时的插件与服务，挂载／卸载模型所写插件（[设计](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)），以及受限 repository Plugin 加载 | 产品：稳定表面 |
-| [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定表面 |
-| [`session/`](session/README.md) | 持久会话数据平面：持久化 seam + JSONL/SQLite 后端、投影 seam、日志支持的标题、会话上报 | 产品：稳定表面 |
-| [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 |
-| [`settings/`](settings/README.md) | 用户设置 seam + 文件 provider | 产品：稳定表面 |
-| [`credentials/`](credentials/README.md) | 凭据引用 seam + 环境叠加 `.env` provider | 产品：稳定表面 |
-| [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 |
-| [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定表面 |
-| [`scaffold/`](scaffold/README.md) | 创建／启动／驱动项目的工具：helper、启动器、初始化器、带两端的通信协议、启动器 telemetry | 产品：稳定表面 |
-| [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定表面 |
-| [`interaction/`](interaction/README.md) | 人机协作平面：批准／交互 seam、权限预设、命令、用户问答工具 | 产品：稳定表面 |
-| [`boot/`](boot/README.md) | 共享的 app bin 启动粘合层 | 产品：稳定表面 |
-| [`host/`](host/README.md) | web GUI 宿主半侧：API 网关 + HTTP 路由服务器 | 产品：稳定表面 |
-| [`client/`](client/README.md) | web GUI 浏览器半侧：shell、协议层、对象服务、slot、`ui-*` 插件 | 产品：稳定表面 |
+| [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定接口 |
+| [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定接口 |
+| [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定接口 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定接口 |
+| [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定接口 |
+| [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定接口 |
+| [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定接口 |
+| [`skill/`](skill/README.md) | skill（技能）能力系列：提供方注册表、本地提供方和面向模型的目录／加载器 | 产品：稳定接口 |
+| [`compact/`](compact/README.md) | 压缩（compaction）能力系列：抽象 seam + 基础后端（工具延后） | 产品：稳定接口 |
+| [`context/`](context/README.md) | 模型可见请求上下文，包括 workspace 指令和时间上下文 | 产品：稳定接口 |
+| [`subagent/`](subagent/README.md) | subagent 能力系列：提供方注册表 seam 和面向模型的委托工具 | 产品：稳定接口 |
+| [`tasks/`](tasks/README.md) | 通用后台任务运行时和面向模型的 `task_*` 控制工具 | 产品：稳定接口 |
+| [`workflow/`](workflow/README.md) | 脚本 seam、worker 线程引擎和面向模型的 `workflow`/`ralph` 工具 | 产品：稳定接口 |
+| [`web/`](web/README.md) | Web 能力系列：seam、搜索／获取提供方实现和面向模型的 Web 工具 | 产品：稳定接口 |
+| [`spill/`](spill/README.md) | spill 能力系列：存储 seam、本地实现、工具结果 spill 策略 | 产品：稳定接口 |
+| [`todo/`](todo/README.md) | 面向模型的 `todo_write` 工具 | 产品：稳定接口 |
+| [`plan/`](plan/README.md) | Plan 协作状态，提供直接进入命令与经评审的退出 | 产品：稳定接口 |
+| [`guard/`](guard/README.md) | 循环卫生守卫：建议性重复调用提醒 + `tools/execute` 截止时间强制执行器 | 产品：稳定接口 |
+| [`bundle/`](bundle/README.md) | 可安装的 `dsh --profile` 补丁层 | 产品：稳定接口 |
+| [`self-modification/`](self-modification/README.md) | agent 修改自身运行时：检查实时运行时的插件与服务，挂载／卸载模型所写插件（[设计](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)），以及受限仓库插件加载 | 产品：稳定接口 |
+| [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定接口 |
+| [`session/`](session/README.md) | 持久会话数据平面：持久化 seam + JSONL/SQLite 后端、投影 seam、日志支持的标题、会话上报 | 产品：稳定接口 |
+| [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定接口 |
+| [`settings/`](settings/README.md) | 用户设置 seam + 文件提供方 | 产品：稳定接口 |
+| [`credentials/`](credentials/README.md) | 凭据引用 seam + 环境叠加 `.env` 提供方 | 产品：稳定接口 |
+| [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定接口 |
+| [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定接口 |
+| [`scaffold/`](scaffold/README.md) | 创建／启动／驱动项目的工具：helper、启动器、初始化器、带两端的通信协议、启动器 telemetry | 产品：稳定接口 |
+| [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定接口 |
+| [`interaction/`](interaction/README.md) | 人机协作平面：批准／交互 seam、权限预设、命令、用户问答工具 | 产品：稳定接口 |
+| [`boot/`](boot/README.md) | 共享的 app bin 启动粘合层 | 产品：稳定接口 |
+| [`host/`](host/README.md) | web GUI 宿主半侧：API 网关 + HTTP 路由服务器 | 产品：稳定接口 |
+| [`client/`](client/README.md) | web GUI 浏览器半侧：shell、协议层、对象服务、slot、`ui-*` 插件 | 产品：稳定接口 |
 | [`experimental/`](experimental/README.md) | 原型和内部插件 | 未发布 |
 | [`examples/`](examples/README.md) | 演示组合包（agent-spine + CLI/ACP/JSON-RPC bin），由叶节点加载 | 支持：示例基础设施 |
 | [`support/`](support/README.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | 支持：兼容性预期较低 |
diff --git a/packages/api/README.i18n.yaml b/packages/api/README.i18n.yaml
index 6a834cdf4d..e44c33641a 100644
--- a/packages/api/README.i18n.yaml
+++ b/packages/api/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/README.md
 README.md: 7c75e8012459266e0ce09c97416d140e5ac777e1
-README.zh.md: 87bd15fc4e5ad23ef785f7c9ee805a4aa1a35e46
+README.zh.md: f4e882570d2dc929cca466e0bdb05bb2943f2c93
diff --git a/packages/api/README.zh.md b/packages/api/README.zh.md
index 87bd15fc4e..f4e882570d 100644
--- a/packages/api/README.zh.md
+++ b/packages/api/README.zh.md
@@ -9,9 +9,9 @@
 | [`remotes/`](remotes/README.md) | Host Agent/Session lookup 策略与 Client Remote contribution 装配 | 无服务；配置 `ctx.typert` 并消费 `ctx.remote` |
 | [`gateway/`](gateway/README.md) | Host TypeRT 分发器与 Client Remote endpoint | `ctx.typertGateway` / `ctx.remote` |
 
-运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientRemote` 契约，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
+运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientRemote` 约定，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
 
 ## 已知限制与延期工作
 
-- Connection 与 WebServer 仍位于 [`client/connection`](../client/connection/README.md) 和 [`host/webserver`](../host/webserver/README.md)；后续可以只移动包，将它们放到 `api/connection` 和 `api/webserver` 下，而无需改变服务契约。
+- Connection 与 WebServer 仍位于 [`client/connection`](../client/connection/README.md) 和 [`host/webserver`](../host/webserver/README.md)；后续可以只移动包，将它们放到 `api/connection` 和 `api/webserver` 下，而无需改变服务约定。
 - 旧 API Proxy 仍位于 [`host/apiproxy`](../host/apiproxy/README.md)，作为尚未迁移到 Remote 的方法的回退路径。它使用由 `api-remotes` 持有的 Host resolver，使已迁移与旧方法共用同一套 Agent/Session 身份策略。
diff --git a/packages/api/gateway/README.i18n.yaml b/packages/api/gateway/README.i18n.yaml
index 3f4cd32e4d..67b8b39ec1 100644
--- a/packages/api/gateway/README.i18n.yaml
+++ b/packages/api/gateway/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/gateway/README.md
 README.md: 0e1a03d2016b8cfbe165dbf1b0a9802290b29502
-README.zh.md: 6b5ccff2340405cc0045147239c5bd4f3eead7da
+README.zh.md: 3de685c18574172c8de8f2d4e94640a4b3ba193b
diff --git a/packages/api/gateway/README.zh.md b/packages/api/gateway/README.zh.md
index 6b5ccff234..3de685c185 100644
--- a/packages/api/gateway/README.zh.md
+++ b/packages/api/gateway/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
+为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 契约产物，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
 
 ## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
 
@@ -20,7 +20,7 @@ Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandle
 
 每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api', endpoint, ...)` 发送。生成的支持取消的方法接受最后一个可选 `AbortSignal`；Client 会在调用 Connection 前将它与贡献项的挂载生命周期合并。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
 
-生成的声明合并通过共享的 `TypeRTClientRemote` 契约提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
+生成的声明合并通过共享的 `TypeRTClientRemote` 约定提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
 
 ## 模型体验
 
diff --git a/packages/api/remotes/README.i18n.yaml b/packages/api/remotes/README.i18n.yaml
index f8f7a6400b..68dbf6263f 100644
--- a/packages/api/remotes/README.i18n.yaml
+++ b/packages/api/remotes/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/remotes/README.md
 README.md: 3d9de0955faefe37c95ff8bb792d57c4fa1f1a3a
-README.zh.md: 7490d68781d3a7b0002b73fe06056ec86c144575
+README.zh.md: 12add6f8efc5b6af3e9b74b26a1abb2bb3936e0a
diff --git a/packages/api/remotes/README.zh.md b/packages/api/remotes/README.zh.md
index 7490d68781..12add6f8ef 100644
--- a/packages/api/remotes/README.zh.md
+++ b/packages/api/remotes/README.zh.md
@@ -8,7 +8,7 @@
 
 当前 Client 组合仅挂载 Goal Remote 贡献。该组合卸载时，Cordis effect 的所有权机制会撤回所有贡献；`@deepseek-ai/dsh-api-gateway/client` 负责描述符校验、可追踪 namespace Service、直接与作用域方法、调用与取消。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 接口，不导入具体 Gateway。
 
-本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 契约，均可复用其 Client face。
+本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 约定，均可复用其 Client face。
 
 ## 构建边界
 
diff --git a/packages/bash/bash-env/README.i18n.yaml b/packages/bash/bash-env/README.i18n.yaml
index 47f4cf01cc..151e4898b0 100644
--- a/packages/bash/bash-env/README.i18n.yaml
+++ b/packages/bash/bash-env/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/bash-env/README.md
 README.md: 7b939326d4effd14fc83ef0ad4e133f019f1011f
-README.zh.md: b6f3aca41771f1ca990a4b708cd53119b8e8ad78
+README.zh.md: a67351fbc3c5aae7604f390fc9e3edd492d69fc1
diff --git a/packages/bash/bash-env/README.zh.md b/packages/bash/bash-env/README.zh.md
index b6f3aca417..a67351fbc3 100644
--- a/packages/bash/bash-env/README.zh.md
+++ b/packages/bash/bash-env/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-工具无关的 shell 环境插件：拥有 `ctx.bashEnv` 注册表，管理受信任的、每次执行收集的 `DSH_*` 变量，供模型可见的 shell 工具（`dsh-tool-bash`、`dsh-tool-pwsh`）收集进每次 shell 调用的环境。内置 shell 事实（`DSH_HOME`、`DSH_SHELL=1`、`DSH_SESSION_ID`）归注册表自身所有；其他插件可以注册额外的可枚举事实，注册随插件纤维（fiber）释放，重复所有权或未声明的运行时键会响亮失败。
+工具无关的 shell 环境插件：拥有 `ctx.bashEnv` 注册表，管理受信任的、每次执行收集的 `DSH_*` 变量，供模型可见的 shell 工具（`dsh-tool-bash`、`dsh-tool-pwsh`）收集进每次 shell 调用的环境。内置 shell 事实（`DSH_HOME`、`DSH_SHELL=1`、`DSH_SESSION_ID`）归注册表自身所有；其他插件可以注册额外的可枚举事实，注册随插件纤维（fiber）释放，重复所有权或未声明的运行时键会明确报错。
 
-包根导出 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）以及 `BashEnvRegistry` 服务类及其 contributor 类型；消费者在加载本插件后使用 `ctx.bashEnv`。
+包根导出 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）以及 `BashEnvRegistry` 服务类及其 contributor 类型；消费者在加载本插件后使用 `ctx.bashEnv`。
 
-## Config
+## 配置
 
 ```yaml
 - id: bash-env
@@ -15,11 +15,11 @@
     dshHome: C:\Users\me\.dsh   # default: $DSH_HOME, then ~/.dsh
 ```
 
-## Managed environment
+## 受管环境
 
-每次前台与后台模型 shell 调用都会收到一份新收集的受信任 `DSH_*` 环境。`DSH_HOME` 是由 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 解析的 Harness 主目录绝对路径（`dshHome` 配置，然后环境变量 `$DSH_HOME`，然后 `~/.dsh`），`DSH_SHELL=1` 标识受管理的子进程。带 agent（智能体）的调用额外收到 `DSH_SESSION_ID=agent.session.header.id`；当活动的持久化 seam 定位到 JSONL 工件时，它们还会收到 `DSH_SESSION_JSONL=<绝对目标路径>`。JSONL 路径只是位置提示：首次 flush 之前它可能不存在，也不一定包含当前缓冲中的轮次，并且它不是授权凭据。
+每次前台与后台模型 shell 调用都会收到一份新收集的受信任 `DSH_*` 环境。`DSH_HOME` 是由 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 解析的 Harness 主目录绝对路径（`dshHome` 配置，然后环境变量 `$DSH_HOME`，然后 `~/.dsh`），`DSH_SHELL=1` 标识受管理的子进程。带 agent（智能体）的调用额外收到 `DSH_SESSION_ID=agent.session.header.id`；当活动的持久化 seam 定位到 JSONL 产物时，它们还会收到 `DSH_SESSION_JSONL=<绝对目标路径>`。JSONL 路径只是位置提示：首次 flush 之前它可能不存在，也不一定包含当前缓冲中的轮次，并且它不是授权凭据。
 
-`ctx.bashEnv` 负责收集。其他插件可以注册一个受 effect 作用域约束的 contributor，带有稳定名称、已声明的键/描述以及 `resolve(execution: ToolExecution)`；重复所有权与未声明的运行时键会响亮失败，而 `list()` 只枚举声明、不执行 provider。Harness 内置键保留 `DSH_HOME`、`DSH_SHELL` 与 `DSH_SESSION_ID`；本插件的持久化翻译器通过读取与后端无关的 `sessionPersistence.locate()` seam 拥有 `DSH_SESSION_JSONL`。
+`ctx.bashEnv` 负责收集。其他插件可以注册一个受 effect 作用域约束的 contributor，带有稳定名称、已声明的键/描述以及 `resolve(execution: ToolExecution)`；重复所有权与未声明的运行时键会明确报错，而 `list()` 只枚举声明、不执行提供方。Harness 内置键保留 `DSH_HOME`、`DSH_SHELL` 与 `DSH_SESSION_ID`；本插件的持久化翻译器通过读取与后端无关的 `sessionPersistence.locate()` seam 拥有 `DSH_SESSION_JSONL`。
 
 ```ts
 import type { Context } from 'cordis'
@@ -36,16 +36,16 @@ export function apply(ctx: Context): void {
 }
 ```
 
-覆盖层根据当前 `ToolExecution` 计算，并通过专用的 `BashExecRequest.dshEnv` 通道传递。本地执行器在合并该快照前移除所有继承的 `DSH_*`，因此嵌套 harness 与并发的父子 agent 无法泄漏过期的身份。`process.env` 永不被修改。shell 工具的描述只教授通用的 `$DSH_*` 约定，而不是点名持久化相关的变量或添加常驻的 system-prompt 段落。
+覆盖层根据当前 `ToolExecution` 计算，并通过专用的 `BashExecRequest.dshEnv` 通道传递。本地执行器在合并该快照前移除所有继承的 `DSH_*`，因此嵌套 harness 与并发的父子 agent 无法泄漏陈旧身份。`process.env` 永不被修改。shell 工具的描述只教授通用的 `$DSH_*` 约定，而不是点名持久化相关的变量或添加常驻的系统提示词段落。
 
-## Model Experience
+## 模型体验
 
-Indirectly, through the shell tools (`dsh-tool-bash`, `dsh-tool-pwsh`), which collect this registry's managed `DSH_*` snapshot into every shell-tool call.
+通过 shell 工具（`dsh-tool-bash`、`dsh-tool-pwsh`）间接产生影响；这些工具会把该注册表的受管 `DSH_*` 快照收集进每次 shell 工具调用。
 
 #### KV Cache effect
 
-No direct invalidation; the named consumers own any request-prefix changes.
+不会直接导致缓存失效；任何请求前缀变更均由上述消费方负责。
 
-## Known Limitations and Deferred Work
+## 已知限制与延期工作
 
-- **`list()` 只枚举 contributor 声明的变量** — 注册表自有的内置键（`DSH_HOME`、`DSH_SHELL`、`DSH_SESSION_ID`）不包含在内，因此诊断、prompt 或 UI 代码不得把 `list()` 当作完整的环境目录。
+- **`list()` 只枚举 contributor 声明的变量** — 注册表自有的内置键（`DSH_HOME`、`DSH_SHELL`、`DSH_SESSION_ID`）不包含在内，因此诊断、提示词或 UI 代码不得把 `list()` 当作完整的环境目录。
diff --git a/packages/bash/pwsh-local/README.i18n.yaml b/packages/bash/pwsh-local/README.i18n.yaml
index 9a0690b5c8..a3b4ec3597 100644
--- a/packages/bash/pwsh-local/README.i18n.yaml
+++ b/packages/bash/pwsh-local/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/pwsh-local/README.md
 README.md: 3e38ea3830cb651a80eaee744a42f68891767358
-README.zh.md: 8d32ce865d299bac37704e3e8730a7faa63ee108
+README.zh.md: d84a4ef4c94cd266bbb8f19bd21d7517016c50d5
diff --git a/packages/bash/pwsh-local/README.zh.md b/packages/bash/pwsh-local/README.zh.md
index 8d32ce865d..d84a4ef4c9 100644
--- a/packages/bash/pwsh-local/README.zh.md
+++ b/packages/bash/pwsh-local/README.zh.md
@@ -4,7 +4,7 @@
 
 `@deepseek-ai/dsh-bash` 执行器 seam 的本地 PowerShell 实现，基于 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务：`PwshLocalExecutor` 每次调用以受管进程的方式通过 `ctx.subprocess` spawn `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>`，并拥有所有 PowerShell 形状的职责——可执行文件解析、命令默认化与上限、超时/取消分类、面向模型的终端环境，以及后台读取的 stdout/stderr 合并。进程组机制（有界 spill 输出、凭据清理、终止升级、销毁）属于 subprocess 服务。
 
-命令字符串作为 ONE argv 元素传给 `-Command`：由 PowerShell 自己解析文本，不存在中间 shell，因此没有需要转义的 shell 引号层（`bash -c` 字符串域在这里没有对应物）。原生 Win32 路径（`C:\...`）原样通过。
+命令字符串作为 ONE argv 元素传给 `-Command`：由 PowerShell 自己解析文本，不存在中间 shell，因此没有需要转义的 shell 引号层（这里不存在与 `bash -c` 字符串域对应的层）。原生 Win32 路径（`C:\...`）原样通过。
 
 包根导出默认与具名 `PwshLocalExecutor` 插件、其 `Config`、纯函数 `resolvePwshPath`/`candidatePwshPaths` 辅助函数，以及执行器注入每次 spawn 的 `ENV_OVERRIDES`/`ENCODING_PREAMBLE` 常量。
 
@@ -31,7 +31,7 @@
 - **UTF-8 输出固定**——每条命令都先以 UTF-8 设置 `[Console]::OutputEncoding` 与 `$OutputEncoding`，因此 Windows PowerShell 5.1 兜底（或任何控制台代码页非 UTF-8 的主机）不会破坏非 ASCII 输出：subprocess collector 以 UTF-8 解码字节。输入编码保持宿主默认；pwsh 7 默认为 UTF-8，不受影响。
 - **可执行文件解析**——`resolvePwshPath` 优先显式 `pwshPath`，然后在 Windows 上依次探测 PowerShell 7 安装位置、每个 PATH 条目（Microsoft Store 安装；剥离两端引号）以及作为遗留兜底的 Windows PowerShell 5.1，逐一检查 `existsSync`；其他平台回退为通过 PATH 解析的裸 `pwsh`。解析是 `(configured, env, platform)` 的纯函数，在构造时执行一次。
 - **受管进程组之上的配置预算**——`resolve()` 从配置填充 `workdir`/`timeoutMs`/`stdoutMaxBytes`，每次 spawn 都向服务提供显式字节上限、spill 上限与 `graceMs`。该宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样 Node 就能用一个定时器表示它。进程树终止（Windows 用 taskkill，POSIX 用进程组信号）、退出后管道排空宽限、保尾截断与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为单个受信调用方提高 stdout 捕获预算；stderr 与后台运行仍使用 `maxOutputBytes`。
-- **超时与取消分类**——`run()` 通过一个 deadline 融合配置夹取的超时与调用方信号；只有执行器自身超时报告 `timedOut`，上游取消报告 `aborted`，自我终止的命令两者都不报告（见 [timeout 库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。Windows 将强制终止报告为退出码 1 且无信号，因此基于信号的实情（`signal`、`killed` 状态）在那里仅限 POSIX；超时/取消分类与平台无关。
+- **超时与取消分类**——`run()` 通过一个 deadline 融合按配置上限截取的超时与调用方信号；只有执行器自身超时报告 `timedOut`，上游取消报告 `aborted`，自我终止的命令两者都不报告（见 [timeout 库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。Windows 将强制终止报告为退出码 1 且无信号，因此带信号标记的事实（`signal`、`killed` 状态）在那里仅限 POSIX；超时/取消分类与平台无关。
 - **面向模型的终端环境**——`NO_COLOR=1 PAGER=cat GIT_PAGER=cat`（没有 `TERM=dumb`：那是 POSIX 概念；现代 PowerShell 渲染器遵循 `NO_COLOR`），作为普通 env 在服务的凭据清理与 `DSH_*` 通道规则之下合并；显式调用方条目仍然优先。
 - **后台进程**——`start()` 立即返回存活的 `BashProcess` 句柄，不设超时；句柄的 `readOutput()` 把服务基于偏移的 stdout/stderr 读取合并为带标记分段的增量与消费游标。仍在运行的进程属于 subprocess 服务，因此它跨执行器重载存活，并随服务销毁（被终止并 join）。一切任务形状的职责（id、所有权、轮询、通知）都在通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md) 中，由工具层把句柄注册进去——本执行器从不接触会话或注册表。
 
diff --git a/packages/bash/tool-bash/README.i18n.yaml b/packages/bash/tool-bash/README.i18n.yaml
index 43ff188d8d..e57f74b754 100644
--- a/packages/bash/tool-bash/README.i18n.yaml
+++ b/packages/bash/tool-bash/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/tool-bash/README.md
 README.md: 47101e1198d13518c3d82877df8726c1fbf26b82
-README.zh.md: d60ac4b3826838e875f7d43bc314f62e1453c1d9
+README.zh.md: b8a0232c5b9af9ff47c17f552ca0ee606946698b
diff --git a/packages/bash/tool-bash/README.zh.md b/packages/bash/tool-bash/README.zh.md
index d60ac4b382..b8a0232c5b 100644
--- a/packages/bash/tool-bash/README.zh.md
+++ b/packages/bash/tool-bash/README.zh.md
@@ -4,9 +4,9 @@
 
 模型侧 `bash` 工具，注册在 `ctx.bash` 执行器 seam 上。前台执行始终位于该 seam 之后；后台进程句柄会注册到通用 `ctx.tasks` 运行时，并通过 `task_output`、`task_list` 和 `task_kill` 控制；这些工具由 `@deepseek-ai/dsh-tool-tasks` 提供。
 
-需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具契约是 bash 方言——请挂载能解析 bash 的执行器。
+需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具约定使用 bash 方言——请挂载能解析 bash 的执行器。
 
-包（package）根只公开 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍保留在包内部。
+包根只公开 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍保留在包内部。
 
 插件还会提供 `tool:bash` 提示词段落（顺序 105）：检查每个结果中的 `[exit code: N]` 标记，发现失败时先调查原因再继续。
 
@@ -28,7 +28,7 @@
 
 ### 托管 shell 环境
 
-每次模型发起的前台或后台 bash 调用都会通过共享的 [`dsh-bash-env`](../bash-env/README.md) 注册表收到新收集的一组可信 `DSH_*` 环境变量：`DSH_HOME`（Harness home 绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及当活跃持久化后端能定位时的 `DSH_SESSION_JSONL`。注册表契约——贡献方注册、重复／未声明键的响亮失败、内置项保留与贡献方示例——住在该包的 README 里。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；本地执行器会先删除继承的所有 `DSH_*` 再合并，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧身份，且绝不修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
+每次模型发起的前台或后台 bash 调用都会通过共享的 [`dsh-bash-env`](../bash-env/README.md) 注册表收到新收集的一组可信 `DSH_*` 环境变量：`DSH_HOME`（Harness home 绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及当活跃持久化后端能定位时的 `DSH_SESSION_JSONL`。注册表约定——贡献方注册、重复键／未声明键的明确报错、内置项保留与贡献方示例——住在该包的 README 里。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；本地执行器会先删除继承的所有 `DSH_*` 再合并，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧的身份信息，且绝不修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
 
 结果文本依次包含 stdout、可选的 `[stderr]` 段落和适用的沙箱拒绝、超时、信号、退出代码及截断标记。超时与最终退出状态分别报告；非零退出仍是由模型解释的结果，不会成为 `isError`。截断结果会链接安全的完整 spill 文件，或报告文件不可用。只有 spawn 错误和中止等基础设施故障才会产生 `isError`。
 
@@ -52,7 +52,7 @@
 
 ## 逐会话模式切换
 
-对于启用沙箱的执行器，每次调用依次按单次升权、会话覆盖、执行器默认值解析模式。未启用沙箱以及没有 agent 的调用不携带会话覆盖。策略归属方贡献当前且不区分具体能力的常驻模式；拒绝结果仍负责操作特定的有效模式与重试引导。参见 [`dsh-bash` 整合](../bash/README.md)和[沙箱切换契约](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
+对于启用沙箱的执行器，每次调用依次按单次升权、会话覆盖、执行器默认值解析模式。未启用沙箱以及没有 agent 的调用不携带会话覆盖。策略归属方贡献当前且不区分具体能力的常驻模式；拒绝结果仍负责操作特定的有效模式与重试引导。参见 [`dsh-bash` 整合](../bash/README.md)和[沙箱切换约定](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
 
 ## 模型体验
 
@@ -80,7 +80,7 @@ Check the [exit code: N] marker on every bash result; investigate failures befor
 
 #### 模型看到的内容
 
-模型会看到生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash)。仅当此生产方启用 `run_in_background` 时，该字段才会出现；仅当已挂载执行器声明支持沙箱时，`sandbox_permissions` 和 `justification` 才会出现。Agent 作用域的工具限制可以移除该 agent 的定义。
+模型会看到生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash)。仅当此生产方启用 `run_in_background` 时，该字段才会出现；仅当已挂载执行器声明支持沙箱时，`sandbox_permissions` 和 `justification` 才会出现。agent 作用域的工具限制可以移除该 agent 的定义。
 
 #### Token 影响
 
diff --git a/packages/bash/tool-pwsh/README.i18n.yaml b/packages/bash/tool-pwsh/README.i18n.yaml
index 39325f5987..59e7a4991a 100644
--- a/packages/bash/tool-pwsh/README.i18n.yaml
+++ b/packages/bash/tool-pwsh/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/tool-pwsh/README.md
 README.md: 78eb161f77b9524bc577b273abe59db6b931727c
-README.zh.md: 17696fe6d908838aaaca12e8179f2ad9cb780210
+README.zh.md: 9b9dc2ff4feead06d5e592b5d0f79dc2874c8ff3
diff --git a/packages/bash/tool-pwsh/README.zh.md b/packages/bash/tool-pwsh/README.zh.md
index 17696fe6d9..9b9dc2ff4f 100644
--- a/packages/bash/tool-pwsh/README.zh.md
+++ b/packages/bash/tool-pwsh/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-注册在 `ctx.bash` 执行器 seam 之上的模型可见 `pwsh` 工具。面向由 PowerShell 执行器（如 `@deepseek-ai/dsh-pwsh-local`）支撑 `ctx.bash` 的 Windows 组合；工具契约是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量。行为与 `dsh-tool-bash` 逐调用对齐、减去 sandbox 面——通过通用任务运行时执行前台与 `run_in_background`、通过共享 `bash-env` 注册表管理 `DSH_*` 环境、以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。
+注册在 `ctx.bash` 执行器 seam 之上的模型可见 `pwsh` 工具。面向由 PowerShell 执行器（如 `@deepseek-ai/dsh-pwsh-local`）支撑 `ctx.bash` 的 Windows 组合；工具约定使用 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量。行为与 `dsh-tool-bash` 逐调用对齐、减去 sandbox 面——通过通用任务运行时执行前台与 `run_in_background`、通过共享 `bash-env` 注册表管理 `DSH_*` 环境、以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。
 
 需要已加载的执行器实现与 `bash-env` 插件；两者都存在前工具保持 pending（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。
 
-包根只导出 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染（`src/render.ts`）与后台任务适配（`src/background.ts`）镜像 bash 工具的结构，并可通过包的 `./src/*` 导出访问。
+包根只导出 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）；结果渲染（`src/render.ts`）与后台任务适配（`src/background.ts`）镜像 bash 工具的结构，并可通过包的 `./src/*` 导出访问。
 
 插件还贡献 `tool:pwsh` prompt section（order 105）：非零退出以 `[exit code: N]` marker 报告，Windows 上的中断以无 signal 的 exit 1 结算。
 
@@ -24,7 +24,7 @@
 
 `command`、`workdir` 与 `timeoutMs` 在执行前经 `ctx.bash.resolve()` 按执行器配置默认值解析。workdir 默认值在工具层于 `resolve()` 之前从调用 agent 的 `session.header.cwd` 取得——每次会话的 cwd 必须来自 `exec.agent`，因为 N 个会话共享一个执行器；仅当没有会话 cwd 时执行器才回退到自己的配置 / `process.cwd()`。
 
-### Managed shell environment
+### 受管 shell 环境
 
 每次前台与后台模型 pwsh 调用都会通过共享的 [`dsh-bash-env`](../bash-env/) 注册表收到一份新收集的受信任 `DSH_*` 环境：`DSH_HOME`（Harness 主目录绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及活跃持久化后端定位到 JSONL 时的 `DSH_SESSION_JSONL`。向 `ctx.bashEnv` 贡献 `DSH_*` 事实的插件对 pwsh 调用与 bash 调用一视同仁。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；`process.env` 永不被修改。描述只教授通用的 `$env:DSH_*` 约定，而不是点名持久化相关的变量。
 
@@ -34,15 +34,15 @@
 
 当 `run_in_background` 为 true 时，本插件在 spawn 前预检 `ctx.tasks.start()`，把调用 agent 注册为 owner，并将返回的 `BashProcess` 句柄适配为通用的 cancel/done/增量输出钩子。任务运行时拥有 id、跨会话隔离、完成通知、等待与清理；本插件只把 pwsh 退出事实映射进任务输出与结果明细。`enableRunInBackground: false` 会移除参数并在执行时拒绝强制的后台调用。
 
-## UI presentation
+## UI 展示
 
 工具拥有自己的 `presentCall`/`presentResult` 呈现意图。前台调用是携带命令、描述与可选 cwd 的 `terminal` 卡；`run_in_background` 调用是携带原始命令的 `generic` 卡，镜像 bash 工具的后台呈现。完成的前台结果同样是 `terminal` 卡：退出 marker 变成卡片的退出状态 pill（`exitCode`/`signal`），去 marker 的正文成为卡片输出——与 bash 工具的 terminal 卡故事完全一致，经由 `@deepseek-ai/dsh-bash` 的共享退出状态解析。后台 ack 与执行错误保持 `generic` 卡，以 `console` 围栏包裹渲染输出。这些 presenter 是纯函数且可重放。
 
-## Model Experience
+## 模型体验
 
-### System prompt
+### 系统提示词
 
-#### What the model sees
+#### 模型看到的内容
 
 本插件注册作用域内的每个请求都包含下面的 pwsh 指引。作用域工具限制可以隐藏 schema，但不会移除这个独立注册的段落。
 
@@ -52,7 +52,7 @@
 Non-zero exits are reported as `[exit code: N]` markers; investigate failures before moving on. On Windows a killed process settles as `[exit code: 1]` without a signal marker; treat a bare exit 1 after an interruption as a termination, not a command failure.
 ```
 
-#### Token effect
+#### Token 影响
 
 插件激活期间每次请求的固定小额输入成本。
 
@@ -60,13 +60,13 @@ Non-zero exits are reported as `[exit code: N]` markers; investigate failures be
 
 注册作用域与 prompt 文本不变时前缀稳定。插件激活或释放可能使该 prompt 段落的复用失效。
 
-### Tool schemas
+### 工具 schema
 
-#### What the model sees
+#### 模型看到的内容
 
-模型看到生成的 [`pwsh` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-pwsh)。按 agent 作用域的工具限制可以移除该 agent 的定义。
+模型看到生成的 [`pwsh` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-pwsh)。agent 作用域的工具限制可以移除该 agent 的定义。
 
-#### Token effect
+#### Token 影响
 
 工具可见的每个请求上的固定 schema 成本。
 
@@ -74,13 +74,13 @@ Non-zero exits are reported as `[exit code: N]` markers; investigate failures be
 
 可见性与工具定义不变时前缀稳定。限制或配置变更可能从首个变化 token 起使复用失效。
 
-### Foreground result
+### 前台结果
 
-#### What the model sees
+#### 模型看到的内容
 
 渲染器输出数据相关的 stdout 尾部，然后是可选的 `[stderr]` 与 stderr 尾部。条件行精确为 `[output truncated; full output: <path>]`、`[timed out after <timeoutMs>ms]`、`[killed by signal: <signal>]` 与 `[exit code: <exitCode>]`（仅非零退出）；空体渲染为 `(no output)`。
 
-#### Token effect
+#### Token 影响
 
 调用前零结果 token。每个流的输出有界，而每条已发出的行保留在历史中直到压缩。
 
@@ -88,13 +88,13 @@ Non-zero exits are reported as `[exit code: N]` markers; investigate failures be
 
 仅追加；新出现的内容跟随可复用的请求前缀，不会使既有 KV-cache 条目失效。
 
-### Background result
+### 后台结果
 
-#### What the model sees
+#### 模型看到的内容
 
 后台启动精确渲染为 `started background task <id>`；随后的读取与状态通过通用 `task_output`/`task_kill` 工具流转，包括内存截断丢弃未读字节时的 lossy 读取 spill 通知。
 
-#### Token effect
+#### Token 影响
 
 ack 是固定短行；任务输出按读取有界。
 
@@ -102,13 +102,13 @@ ack 是固定短行；任务输出按读取有界。
 
 仅追加；新出现的内容跟随可复用的请求前缀，不会使既有 KV-cache 条目失效。
 
-### Tool errors
+### 工具错误
 
-#### What the model sees
+#### 模型看到的内容
 
 校验与基础设施失败规范化为 `Error: <message>`。本包的稳定消息包括 `invalid command: expected a non-empty string`、`invalid description: expected a non-empty string`、`invalid timeoutMs: expected a positive number, got <value>`、`run_in_background is disabled for this deployment (enableRunInBackground: false)`、`background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks` 与 `tool call aborted`。
 
-#### Token effect
+#### Token 影响
 
 只有失败的调用会新增这些保留 token；被中止的调用不产生命令输出。
 
@@ -116,9 +116,9 @@ ack 是固定短行；任务输出按读取有界。
 
 仅追加；新出现的内容跟随可复用的请求前缀，不会使既有 KV-cache 条目失效。
 
-## Known Limitations and Deferred Work
+## 已知限制与延期工作
 
 - **无 sandbox 升级** — 没有 `sandbox_permissions`/`justification`；升级等待 Windows-confining 执行器（bash 工具的 sandbox 面不被镜像）。
 - **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端目前仅限 Linux/macOS，Windows ConPTY 持久 shell 属于路线图工作。
-- **PowerShell 方言契约** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
+- **PowerShell 方言约定** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
 - **会话 cwd 身份不做规范化** — workdir 基座直接取会话头 cwd 原值，不同于 bash 工具经 sandbox-root 规范化的身份；此处只涉及无 sandbox 场景。
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index 3ae6f5427c..7885dd3280 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
 README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
-README.zh.md: 88d1c4ad0ced2f5a6440a1b64e34e738a842f938
+README.zh.md: a0a437437f3bb562f0a0d2bb52b1cba1df681606
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 88d1c4ad0c..a0a437437f 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -2,45 +2,45 @@
 
 [English](README.md) | 中文
 
-供 app bin（[`dsh`](../../../apps/cli/README.md) 与 [`dsh-acp-demo`](../../examples/acp-demo/README.md)）共用的启动粘合层：每个 bin 都是在这些 helper 上构建的精简自执行组合，并以自身诊断前缀参数化。这样，Loader 故障行为只由一处负责，不会在已发布产物之间逐渐分化。
+供 app bin（[`dsh`](../../../apps/cli/README.md) 与 [`dsh-acp-demo`](../../examples/acp-demo/README.md)）共用的启动粘合层：每个 bin 都是在这些辅助函数之上构建的精简自执行组合，并以自身诊断前缀参数化。这样，Loader 故障行为只由一处负责，不会在已发布产物之间逐渐分化。
 
 | 导出 | 职责 |
 |---|---|
 | `resolveConfigPath(path, snapshotMode, cwd?)` | 生成绝对配置路径；当 `snapshotMode === 'replay'` 时，把 basename 为 `cordis.yml`/`.yaml` 的文件替换为同级 `cordis.snapshot.yml` |
 | `loadEnv(binName, dir?, warn?)` | 加载已被 git 忽略的 `.env`（Node `process.loadEnvFile`）；文件不存在不影响启动，文件无法加载时输出一行带标签的警告（默认写入 stderr） |
 | `loadLayeredEnv(binName, cwd?, warn?)` | 构建产品 CLI（命令行界面）冻结的「继承环境 > 项目 `.env` > 用户 `.env`」快照，拒绝文件中的 bootstrap-only 变量，并在不替换继承值的前提下物化其余文件值 |
-| `installFailLoud(binName, proc?, release?)` | 将启动期或后续未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 `exit(1)`；两者之间会等待可选的 `release` 拆卸回调（以 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 为上限），使持有终端的界面能在退出前恢复终端；返回卸载函数 |
-| `FAIL_LOUD_RELEASE_TIMEOUT_MS` | `installFailLoud` 等待其 `release` 回调的时长；卡住的 disposer 只会延迟致命退出，而不会取消它 |
+| `installFailLoud(binName, proc?, release?)` | 将启动期或后续未处理的 Loader 拒绝转换为一行带标签的 stderr 消息并执行 `exit(1)`；两者之间会等待可选的 `release` 拆卸回调（以 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 为上限），使持有终端的界面能在退出前恢复终端；返回卸载函数 |
+| `FAIL_LOUD_RELEASE_TIMEOUT_MS` | `installFailLoud` 等待其 `release` 回调的时长；卡住的清理函数只会延迟致命退出，而不会取消它 |
 | `assertEntriesLoaded(ctx, binName)` | 树结算后，如果其中存在已启用但没有 fiber 的条目，则抛出异常，并以 Cordis 启动故障的形式报告每个未解析插件的名称 |
 | `assertEntriesActivated(ctx, binName)` | 先执行 `assertEntriesLoaded` 检查，再在 Loader 结算后等待每个已启用配置项；抛出的错误包含每个失败插件的原始错误堆栈，或每个等待中插件尚未解析的服务 |
 | `loadOptionalPatches(binName, file)` | 解析一份可选的 patch 列表文件（即 profile 的 `cordis.patch.yml`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
 | `loadOverlayPatches(binName, file)` | 解析一份形状相同的必需 patch 列表文件；文件缺失同样抛出异常，因为该文件是调用方指名的 |
 | `mountRootInclude(ctx, absoluteConfigPath, patches?)` | 挂载静态导入的 Include builtin，并保留用户 patch 层 HMR（热模块替换）使用的确切根配置项 |
-| `watchUserPatches(ctx, options)` | 向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步 disposer |
+| `watchUserPatches(ctx, options)` | 向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步清理函数 |
 | `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile 机制（见 [Profile](#profiles)） |
-| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时释放部分构造的上下文，并返回带标签的拒绝结果 |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |
 
-Loader 结算会在导入或生命周期失败时 reject，并携带失败的配置项与阶段；`boot()` 会 dispose 部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：`assertEntriesLoaded` 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；`assertEntriesActivated` 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
+Loader 结算会在导入或生命周期失败时返回拒绝结果，并携带失败的配置项与阶段；`boot()` 会释放部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：`assertEntriesLoaded` 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；`assertEntriesActivated` 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
 
-Loader 并发挂载各个条目，因此当其他环节失败时，某个界面可能已经持有终端：此时不经过整棵树自身的拆卸就退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。配置树失败会经 `boot()` 结算：它先释放部分构建的上下文（从而执行该界面自身的 shutdown），再抛出带标签的 rejection。对于 `boot()` 看不到的 rejection（插件游离的异步工作在挂载期间或挂载完成后失败），持有终端的 bin 会传入 `release`，在提交退出前释放整棵树；`dsh` 在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值，使该回调覆盖整个挂载窗口。release 执行期间处理函数保持注册并加闩：被报告的始终是第一个 rejection，后续 rejection（包括拆卸自身的）会被吞掉，而不会变成未捕获错误、在拆卸中途杀死进程。
+Loader 并发挂载各个条目，因此当其他环节失败时，某个界面可能已经持有终端：此时不经过整棵树自身的拆卸就退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。配置树失败会经 `boot()` 结算：它先释放部分构建的上下文（从而执行该界面自身的 shutdown），再抛出带标签的 rejection。对于 `boot()` 看不到的 rejection（插件游离的异步工作在挂载期间或挂载完成后失败），持有终端的 bin 会传入 `release`，在提交退出前释放整棵树；`dsh` 在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值，使该回调覆盖整个挂载窗口。release 执行期间，处理函数保持注册并处于锁定状态：被报告的始终是第一个 rejection，后续拒绝（包括拆卸自身产生的拒绝）会被忽略，而不会变成未捕获错误、在拆卸中途杀死进程。
 
-配置中的裸插件 specifier（`@deepseek-ai/dsh-*`、npm 包（package））通过 Cordis Loader 的内部模块 loader 解析。仓库 bin 会安装 Loader 的可选 peer `node-addon-require-builtin`；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。相对 specifier 无需原生 helper，并以配置目录为基准解析。构建后的 `dsh-app-boot` 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与 host 会绑定到同一个 Loader peer。`dsh` 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个已交付的原始／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。
+配置中的裸插件 specifier（`@deepseek-ai/dsh-*`、npm 包）通过 Cordis Loader 的内部模块 loader 解析。仓库 bin 会安装 Loader 的可选 peer `node-addon-require-builtin`；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。相对 specifier 无需原生 helper，并以配置目录为基准解析。构建后的 `dsh-app-boot` 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与宿主会绑定到同一个 Loader peer。`dsh` 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个随附的原始／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。
 
-此包不包含 loader 钩子，也不提供开发模式接口。[`dsh` 应用](../../../apps/cli/README.md)持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。
+此包不包含 loader 钩子，也不提供开发模式接口。[`dsh` 应用](../../../apps/cli/README.md) 持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。
 
-## Profile
+## Profiles
 
-profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则大声失败。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会大声失败（即 `dsh plugin` 路径）。
+profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则明确报错。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会明确报错（即 `dsh plugin` 路径）。
 
 用户级的机器本地偏好同样位于 Harness home 中：
 
 - **`.env`**：产品 CLI 的普通环境层；调用目录的文件优先于 Harness home 的文件，两者都低于继承环境。`loadLayeredEnv` 记录每个值的来源，按不区分大小写的方式拒绝 [bootstrap-only 文件变量](../../../.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md#decision)，并把其余值物化进 `process.env`，供 Loader 表达式和第三方库使用。受管凭据另存于 [`.credentials.yaml`](../../credentials/credentials-local/README.md)；留在任一 `.env` 中的凭据仍是低优先级后备值。
 - **`cordis.patch.yml`**（home 级）与 **`profiles/<name>/cordis.patch.yml`**：用户 patch 层，应用在所有组合包层之后（先应用逐 profile 的文件，再应用 home 级文件，因此后者优先级更高）：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在组合后的树中，则输出一条 stderr 警告。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用该层，请使用 `[]`。
 
-长期运行的 surface 会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay／标志 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
+长期运行的界面会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，监视器仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay／标志 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离观察方的失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
 
 ## 模型体验
 
@@ -48,11 +48,11 @@ profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`
 
 #### KV Cache 影响
 
-`boot()` 不会直接使缓存失效；消费方调用 `addHarnessSourceSection` 时，会在系统提示词靠前位置、逐请求内容之前添加一行短文本，因此不会使跨轮次缓存失效。请求前缀的其他任何变化均由相应的具名消费方持有。
+`boot()` 不会直接使缓存失效；消费方调用 `addHarnessSourceSection` 时，会在系统提示词靠前位置、逐请求内容之前添加一行短文本，因此不会使跨轮次缓存失效。请求前缀的其他任何变化均由相应的具名消费方负责。
 
-## 已知限制与延期工作
+## 已知限制与暂缓事项
 
-- **裸包 specifier 依赖 Loader 内部机制**：生产 bin 需要 Loader 的可选原生 helper；没有该 helper 的进程内调用方必须使用可解析的相对／file specifier，或提供自己的模块解析钩子。
+- **裸包 specifier 依赖 Loader 内部机制**：生产 bin 需要 Loader 的可选原生辅助组件；没有该辅助组件的进程内调用方必须使用可解析的相对／file specifier，或提供自己的模块解析钩子。
 - **快照回放替换仅识别特定 basename**：只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
 - **环境发现以启动为界**：`loadLayeredEnv` 只读取一次调用目录与 Harness home 中的 `.env`；它不搜索父目录，也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。
 - **用户 patch 层采用 patch 形式**：按 id 定位的 patch 会替换条目的整个 `config`，而不是深度合并，因此 profile 覆盖必须重述需要保留的组合包字段。
diff --git a/packages/bundle/README.i18n.yaml b/packages/bundle/README.i18n.yaml
index 98df59d988..860390d722 100644
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/README.md
 README.md: af06fe921a66378894a4ab0174ef403499f5f68c
-README.zh.md: ef2027e347b79e14574ba1164aa9fddd364327e9
+README.zh.md: b9656649782a638a3b39b4e1e6d330476b0732ba
diff --git a/packages/bundle/README.zh.md b/packages/bundle/README.zh.md
index ef2027e347..b965664978 100644
--- a/packages/bundle/README.zh.md
+++ b/packages/bundle/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 契约](../boot/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
+Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 约定](../boot/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/bundle/headless/README.i18n.yaml b/packages/bundle/headless/README.i18n.yaml
index f1a9d53be8..bc15c88a24 100644
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/headless/README.md
 README.md: 661b377817482d22f58f22b573075722646729a2
-README.zh.md: a6b91a8e60fdcc06ba23e07dcb2f4208ea1020f7
+README.zh.md: 8d3ed1c0f99b9245d27c68887aa7b2301368a17b
diff --git a/packages/bundle/headless/README.zh.md b/packages/bundle/headless/README.zh.md
index a6b91a8e60..8d3ed1c0f9 100644
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -15,4 +15,4 @@ dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 ## 已知限制与延期工作
 
 - **只运行一个轮次**：runner 锚定第一个由消息触发的轮次，并在其结束时退出；排队的后续消息与多轮任务不在范围内。
-- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时大声失败，直到宿主提供该 seam。
+- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该 seam。
diff --git a/packages/bundle/web-app/README.i18n.yaml b/packages/bundle/web-app/README.i18n.yaml
index 7662182df0..0130cf36e5 100644
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/web-app/README.md
 README.md: dc35cb4b596b265b70cea81aa5d6784fc1eff65b
-README.zh.md: 0ffc5cdaf1a98e5df11ef042c7d15a994515c170
+README.zh.md: c9fc86522da9c6b2ea79d1d079c71e5b26007f0a
diff --git a/packages/bundle/web-app/README.zh.md b/packages/bundle/web-app/README.zh.md
index 0ffc5cdaf1..c9fc86522d 100644
--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -10,7 +10,7 @@ dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 #### 模型看到的内容
 
-当 `surfaceContext` 为 true 时，全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新契约，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，该提示词段和这些变量都不会注册。
+当 `surfaceContext` 为 true 时，全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新约定，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，该提示词段和这些变量都不会注册。
 
 #### Token 影响
 
@@ -22,5 +22,5 @@ dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 ## 已知限制与延期工作
 
-- **前端 dist 必须已构建**：对 dist 的 `require.resolve` 在激活时大声失败并给出构建提示；没有从源码直接服务的回退路径。
+- **前端 dist 必须已构建**：对 dist 的 `require.resolve` 在激活时明确报错并给出构建提示；没有从源码直接服务的回退路径。
 - **`lanAddresses` 是启动期快照**：启动后的网卡变化不会重新公告；打印的 LAN URL 始终与配置的信任栅栏一致。
diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml
index 2ce3e44fa7..997063b3bb 100644
--- a/packages/client/README.i18n.yaml
+++ b/packages/client/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/README.md
 README.md: 56b9363cc724515ecbd11127ea4c13aba84283df
-README.zh.md: edd378bf80b63e9ab2481ab555320ed18de85139
+README.zh.md: a3fe1a978de7ab5935ec527d115278703cbebcd4
diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md
index edd378bf80..a3fe1a978d 100644
--- a/packages/client/README.zh.md
+++ b/packages/client/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 UI 服务和特性插件。编写规则见 [AGENTS.md](AGENTS.md)；宿主半侧是 [`host/`](../host/README.md)。除 `test-runtime` 外，均为命名成 `@deepseek-ai/dsh-client-<name>` 的**产品**包。
+dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 UI 服务和功能插件。编写规则见 [AGENTS.md](AGENTS.md)；宿主半侧是 [`host/`](../host/README.md)。除 `test-runtime` 外，均为命名成 `@deepseek-ai/dsh-client-<name>` 的**产品**包。
 
 | 包 | 目的 |
 |---|---|
@@ -14,15 +14,15 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
 | [`hmr/`](hmr/README.md) | 在开发期间刷新客户端插件。 |
 | [`locale/`](locale/README.md) | 提供本地化偏好与消息词典。 |
 | [`schema-form/`](schema-form/README.md) | 为设置编辑器提供 schema 驱动的草稿处理。 |
-| [`test-runtime/`](test-runtime/README.md) | 为客户端特性包提供共享的仓库测试支持。 |
-| [`ui-slots/`](ui-slots/README.md) | 定义 UI 特性注册和组合扩展 slot 的方式。 |
+| [`test-runtime/`](test-runtime/README.md) | 为客户端功能包提供共享的仓库测试支持。 |
+| [`ui-slots/`](ui-slots/README.md) | 定义 UI 功能注册和组合扩展 slot 的方式。 |
 | [`ui-theme/`](ui-theme/README.md) | 应用所选颜色主题。 |
 | [`ui-primitives/`](ui-primitives/README.md) | 提供共享 React 控件、图标和内容渲染器。 |
 | [`ui-layout/`](ui-layout/README.md) | 排列应用的主要区域。 |
 | [`ui-sidebar/`](ui-sidebar/README.md) | 展示 Workspace 与会话导航。 |
 | [`ui-workspace/`](ui-workspace/README.md) | 提供 Workspace 选择与创建界面。 |
 | [`ui-conversation/`](ui-conversation/README.md) | 展示当前会话及其输入界面。 |
-| [`ui-tool/`](ui-tool/README.md) | 编排 Tool 调用树和按 Tool 键控的视图。 |
+| [`ui-tool/`](ui-tool/README.md) | 编排工具调用树和按工具键控的视图。 |
 | [`ui-goal/`](ui-goal/README.md) | 展示和管理当前目标。 |
 | [`ui-trajectory/`](ui-trajectory/README.md) | 提供 agent（智能体）活动的其他视图。 |
 | [`ui-command/`](ui-command/README.md) | 提供会话感知的命令发现与分发。 |
@@ -37,6 +37,6 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
 | [`ui-settings-general/`](ui-settings-general/README.md) | 提供常规设置分区。 |
 | [`ui-models/`](ui-models/README.md) | 提供模型提供方配置与 DeepSeek 配置引导。 |
 
-每个子文档负责自身的契约和详细行为。[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)与 [Web 客户端架构 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)负责跨包组合与加载决策。
+每个子文档负责自身的约定和详细行为。[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)与 [Web 客户端架构 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)负责跨包组合与加载决策。
 
 子系统参考是 [client-modules.md](../../docs/subsystems/client-modules.md)；[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)是权威 slot 模型，[web 客户端架构说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)拥有加载链与对象层。
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index ddfda12f4e..57d4c4c75c 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/connection/README.md
 README.md: 161e34c4b6018625fb690e178eb9a9f8ac0ef21b
-README.zh.md: d17012cc89c02a1b11f16d126b7c0cafe67fb2a0
+README.zh.md: 731daa15c8944febae1712788a9ae017d4756960
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index d17012cc89..731daa15c8 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议契约见 api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议约定见 api-contracts v3 §3。
 
 ## /api 浏览器信任栅栏
 
-node 半侧在桥接或 upgrade 前守卫 `/api` 下的每个入口（`src/api-request-trust.ts`）。每个请求——无论是否带浏览器标记——`Host` 都必须是回环地址权威，或与某个 `trustedHosts` 条目匹配：带端口的 `host:port` 条目精确匹配，不带端口的条目匹配任意端口，两侧均经 WHATWG 归一化后比较（DNS rebinding 防御）。刻意不为无浏览器标记的 HTTP 请求开捷径：明文 HTTP 下浏览器的图片与导航读取既不带 `Origin` 也不带 Fetch-Metadata，因此无标记请求仍可能是被重绑页面发起的、响应可被读走的读取，而 Host 是重绑唯一伪造不了的请求头；WebSocket 浏览器握手会带 `Origin` 并通过同一道比较。非浏览器客户端经由回环地址、CLI 推导的 LAN IP 字面量或已声明的权威通过同一道栅栏。当标记存在时，`Origin` 必须与 Host 权威完全一致；显式的 `sec-fetch-site: cross-site` 标记一律拒绝。不是纯的、规范形 `host[:port]` 权威的 `trustedHosts` 条目——即 WHATWG 解析读回后与原文不完全一致的——会让插件加载大声失败：否则解析会悄悄授权 `harness.internal/path` 这类笔误里的 hostname，或把悬空冒号、补零端口放大成任意端口授权。HTTP 失败在任何 RPC 分发之前以纯 403 应答，upgrade 失败在启动任何 event stream 前拒绝握手。因此非回环（`--host 0.0.0.0`）部署需要让自己的服务权威被信任：dsh CLI 会自行推导本机的 LAN IP 字面量，其 `--trusted-host` flag 用于声明具名权威，所以 cordis.yml 中的 `trustedHosts` 面向 CLI 不参与引导的组合。这道栅栏是可达性策略，而不是认证；Web 载体不提供认证层。决策记录：[api 浏览器信任边界 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md)。
+node 半侧在桥接或 upgrade 前守卫 `/api` 下的每个入口（`src/api-request-trust.ts`）。每个请求——无论是否带浏览器标记——`Host` 都必须是回环地址权威，或与某个 `trustedHosts` 条目匹配：带端口的 `host:port` 条目精确匹配，不带端口的条目匹配任意端口，两侧均经 WHATWG 归一化后比较（DNS rebinding 防御）。刻意不为无浏览器标记的 HTTP 请求开捷径：明文 HTTP 下浏览器的图片与导航读取既不带 `Origin` 也不带 Fetch-Metadata，因此无标记请求仍可能是被重绑页面发起的、响应可被读走的读取，而 Host 是重绑唯一伪造不了的请求头；WebSocket 浏览器握手会带 `Origin` 并通过同一道比较。非浏览器客户端经由回环地址、CLI 推导的 LAN IP 字面量或已声明的权威通过同一道栅栏。当标记存在时，`Origin` 必须与 Host 权威完全一致；显式的 `sec-fetch-site: cross-site` 标记一律拒绝。不是纯的、规范形 `host[:port]` 权威的 `trustedHosts` 条目——即 WHATWG 解析读回后与原文不完全一致的——会让插件加载明确报错：否则解析会悄悄授权 `harness.internal/path` 这类笔误里的 hostname，或把悬空冒号、补零端口放大成任意端口授权。HTTP 失败在任何 RPC 分发之前以纯 403 应答，upgrade 失败在启动任何 event stream 前拒绝握手。因此非回环（`--host 0.0.0.0`）部署需要让自己的服务权威被信任：dsh CLI 会自行推导本机的 LAN IP 字面量，其 `--trusted-host` flag 用于声明具名权威，所以 cordis.yml 中的 `trustedHosts` 面向 CLI 不参与引导的组合。这道栅栏是可达性策略，而不是认证；Web 载体不提供认证层。决策记录：[api 浏览器信任边界 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md)。
 
 ## `/api` WebSocket 下行
 
diff --git a/packages/client/test-runtime/README.i18n.yaml b/packages/client/test-runtime/README.i18n.yaml
index 26845c1d5c..7c67e91f5d 100644
--- a/packages/client/test-runtime/README.i18n.yaml
+++ b/packages/client/test-runtime/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/test-runtime/README.md
 README.md: 74da8fde7fd9cc3733d2d1ae03dd3d213e4d553e
-README.zh.md: a86b9e469a5632886891628267002a14588afeaa
+README.zh.md: 1df28f7b25c35333e91476e10480c22a728cdab3
diff --git a/packages/client/test-runtime/README.zh.md b/packages/client/test-runtime/README.zh.md
index a86b9e469a..1df28f7b25 100644
--- a/packages/client/test-runtime/README.zh.md
+++ b/packages/client/test-runtime/README.zh.md
@@ -2,23 +2,23 @@
 
 [English](README.md) | 中文
 
-面向 client feature 测试的 jsdom slot 测试运行时：真实 Cordis `Context`、生产 `SlotsService` 与 web-react 渲染器，围绕带类型的 session/workspace 测试替身组装。feature 套件无需逐套件手搭机器即可测遍声明、注册、scope、store、inject、渲染、更新与销毁——且不存在任何生产逻辑的第二份实现。
+面向客户端功能测试的 jsdom slot 测试运行时：真实 Cordis `Context`、生产 `SlotsService` 与 web-react 渲染器，围绕带类型的 session/workspace 测试替身组装。功能套件无需逐套件手搭机器即可测遍声明、注册、scope、store、inject、渲染、更新与销毁——且不存在任何生产逻辑的第二份实现。
 
-替身实现的正是 feature 经 ctx 拿到的对外面（`TestSessions implements ISessions`、`TestWorkspaces implements IWorkspaces`；每个 fixture session 是 `FixtureSession implements SessionFace`），生产面一旦改形，测试台在编译期即断，而非静默漂移。provide bundle 材料化直接运行生产 `SessionProvideChannel`——与 `SessionsService` 共用同一份实现。fixture 灌入的是普通数据：列表行、会话快照（经 `updateSnapshot` 以 immer 补丁改写）、projection 值，以及按 `ISession` 取型的行为桩——spec 调用未打桩的动词时报错自明。带类型的 `provide()` 将已声明服务名的 fake 约束为该服务对外面的 `Partial` 子集。
+替身实现的正是功能通过 ctx 获得的对外接口（`TestSessions implements ISessions`、`TestWorkspaces implements IWorkspaces`；每个 fixture session 是 `FixtureSession implements SessionFace`），生产面一旦改形，测试台在编译期即断，而非静默漂移。provide bundle 材料化直接运行生产 `SessionProvideChannel`——与 `SessionsService` 共用同一份实现。fixture 灌入的是普通数据：列表行、会话快照（经 `updateSnapshot` 以 immer 补丁改写）、projection 值，以及按 `ISession` 取型的行为桩——spec 调用未打桩的动词时报错自明。带类型的 `provide()` 将已声明服务名的 fake 约束为该服务对外面的 `Partial` 子集。
 
 局部 DOM 快照：`declare(children)` 注册自动 frame，逐 key 的 `<div data-slot>` 包裹层即快照根；`renderSlot(key, owner)` 返回该 slot 的局部视图（container、限定范围的 Testing Library 查询、原位 `update(owner)`）；注册的快照序列化器把 CSS-module 哈希类名折回语义名（`_frame_a1b2c3` → `frame`）保持 `.snap` 只含结构，并把 `<svg>` 内部折叠为 `data-content` 指纹。需要自定义页面 frame 的套件改用 `root.declare(children, Frame)`；`mount(plugin)` 在真实 fiber 上运行并对缺失服务先行报错；`dispose()` 沿单一轴拆除视图、feature fiber、已铸 scope 与持久化 store 状态。
 
 不属于产品插件图（无 `dshClient`）；feature 包仅以 `devDependencies` 依赖之。
 
-## Model Experience
+## 模型体验
 
 无；本包是浏览器侧测试基础设施，无一物到达模型请求。
 
 #### KV Cache effect
 
-无；本包既不组装也不发送 provider 请求。
+无；本包既不组装也不发送提供方请求。
 
-## Known Limitations and Deferred Work
+## 已知限制与延期工作
 
 - **仅可经仓内源码别名消费。** spec 通过 tsconfig `paths` 解析到 `src`；构建产物 `lib/` 再导出 `@deepseek-ai/dsh-client-runtime/client`，而该 bundle 是无 Node ESM 导出的浏览器 loader 脚本，故 `lib/index.js` 在纯 Node 下不可导入。所有消费方都是仓内 Vitest 套件；不存在 Node 兼容的运行时入口。
 - **会话快照是 fixture 数据，不是重放历史。** `updateSnapshot` 直写快照 store；wire 到快照的运算仍由 runtime 包自身测试与 replay e2e 把守。因此 fixture 可以表达生产投影永不产出的状态。
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 822a02d321..a8c91a28b7 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
 README.md: f5cf9b72b4f8f4ce7b1a07c0c1e30f5213edf678
-README.zh.md: 90c4dc4cc169b2cbcd7e94275a692e3d062cfe98
+README.zh.md: 74b2c0d47e8ab103363881535df00831adbed89a
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 90c4dc4cc1..74b2c0d47e 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离与轮次状态）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（队列行加 todo 计划条）、详情壳层，以及按 scope 寻址的 ConversationService。Tool 展示属于 [`ui-tool`](../ui-tool/README.md)。
+会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离与轮次状态）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（队列行加 todo 计划条）、详情壳层，以及按 scope 寻址的 ConversationService。工具展示属于 [`ui-tool`](../ui-tool/README.md)。
 
 压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。每个具备结构化摘要溯源的完成标记都会显示被替换条目数量和估算 token 数量，并可点击展开摘要。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
-别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份契约里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的 prompt。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
+别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份约定里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的提示词。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
 
 视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
@@ -18,19 +18,19 @@
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 
-聊天视图保留 Tool 的消息流位置，但委托其展示。它通过 `conversation.chat.tool` 传递每个已排序的 root call；详情壳层则通过 `conversation.details.tool` 传递当前选中的调用。组装后的 Web bundle 由 [`ui-tool`](../ui-tool/README.md) 填充整体 Tool 席位，并由后者选择 Runtime 已投影的 Code Dispatch 子调用，负责 root/child 编排、按名称分发、通用展示和 render-intent 卡片；只有详情席位会在该 renderer 缺席时保留 raw-result fallback。
+聊天视图保留工具的消息流位置，但委托其展示。它通过 `conversation.chat.tool` 传递每个已排序的 root call；详情壳层则通过 `conversation.details.tool` 传递当前选中的调用。组装后的 Web bundle 由 [`ui-tool`](../ui-tool/README.md) 填充整体工具席位，并由后者选择 Runtime 已投影的 Code Dispatch 子调用，负责 root/child 编排、按名称分发、通用展示和 render-intent 卡片；只有详情席位会在该 renderer 缺席时保留 raw-result fallback。
 
 聊天流会将跨重试轮次连续出现的模型重试节点投影为一个稳定的弱化状态行，并用最新一次尝试更新该行；每个重试事件仍保留在运行时快照与会话日志中。前端倒计时以客户端收到事件的时刻为计划延迟的起点，避免 Host 与浏览器的时钟偏差；剩余时间向上取整到秒，且下限为 1 秒。最近一次尚未完成的重试会显示从左到右的文字渐变动画。后续轮次事实用于区分已开始的尝试与在退避期间取消的尝试，Host 的 running 位只控制实时动画；随后该行会显示静态的已完成或已取消标签。normal 策略行显示有限重试上限；always 策略行显示 `∞`。激活该行会显示最近一次重试的精确延迟和失败消息。客户端运行时会在相应重试节点到达前移除每个失败步骤的流式输出尾部；后续某次尝试成功后，该状态仍保持可见。未进入重试的终态失败会在其轮次边界渲染为持久的内联状态，展示适合显示的持久消息与可选错误码，但不会提供 Host 无法兑现的操作；AUTH 文案绝不会回显提供方给出的凭据片段。
 
 审批经由本包声明的链接管编辑器：`ApprovalPanel` 注册为按选择器路由的 `'conversation.composer'` 配置项（ui-question 模式），在审批等待未决期间取代 InputBar 占据编辑器（琥珀色条、理由标题、来自运行中调用参数的配对命令行、一次性的拒绝／允许）。`contract/slots.ts` 中的 `PendingApproval` 领域面在运行时 `PendingWait` 载体之上拥有 wire 编码——带审计关联的 `ApprovalResponsePayload` 值；广播的 `approval/resolved` 帧使等待落定并恢复编辑器。运行时 manager 会将所有审批或问题等待通过 `SessionSummary.pendingInteraction` 投影出来，未实例化的 Session 也不例外；`ui-workspace` 负责其侧边栏呈现。未决等待完全离开消息流：问题（ui-question）与审批（ApprovalPanel）都经编辑器接管作答，不再保留只读占位卡。编辑器底行的 Access 席位挂载 `PermissionSelect`，由 host 计算的 `permissions` 投影经标准工具包 `useProjection` 供数（key 缺席即隐藏 chip）；chip 打开 Menu 原语下拉，其中 kebab-case 预设名渲染为 Title Case 标签；普通安全预设会立即经输入栏注入的 `command` 回调提交 `/permission <preset>`，而 `danger-full-access` 在界面中显示为 `Full access`，选择后先打开页面内的 Modal 风险确认。用户勾选确认项前启用按钮始终不可用；取消、Escape、关闭按钮与点击遮罩都不会提交命令。
 
-`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），作为计划条读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`。面板接收纯列表，列表为空时自我隐藏；列表非空时默认折叠，表头显示标题及以 `·` 连接的各状态计数（如 `1 已完成 · 2 进行中 · 1 待处理`，省略零计数）。dock adapter 拥有 selection，因此面板保持为 props 的纯函数。输入区 composer 链隐藏的一切也会隐藏整个 dock。`todo_write` Tool 行属于 [`ui-tool`](../ui-tool/README.md)。
+`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），作为计划条读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`。面板接收纯列表，列表为空时自我隐藏；列表非空时默认折叠，表头显示标题及以 `·` 连接的各状态计数（如 `1 已完成 · 2 进行中 · 1 待处理`，省略零计数）。dock adapter 拥有 selection，因此面板保持为 props 的纯函数。输入区 composer 链隐藏的一切也会隐藏整个 dock。`todo_write` 工具行属于 [`ui-tool`](../ui-tool/README.md)。
 
 `QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `"<n> 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。普通会话中的每条可见行仍是单行预览，并提供针对精确单次入队项的编辑、删除和严格 steering 操作；已寻址 subagent 则保留只读行，因为其继续执行传输不提供 Queue 变更。如果严格 steering 输给已关闭的窗口，原单次入队项会留在 Queue 中正常投递；如果驱动器已经认领该项，正常投递就已开始。这两种已收敛的竞态都不显示失败，传输和未知错误仍会显示。
 
 Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。QueueDock 会将其过滤掉，ChatView 则把它投影为会话流末尾带复制操作的用户样式气泡；非用户来源的 next-step 项（注入上下文）改以 `context` placement 广播，领取前不在任何界面渲染。与所有用户样式气泡一样，这里不显示 fork。Host 会等携带该 steering 的持久 `user/message` 进入 mux 流之后再退役 steering。客户端运行时接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史事件无法隐藏后来复用同一 `MessageId` 的单次入队项。气泡交接时因而不会产生空档或重复，会立即从持久节点恢复复制操作与时钟——steering 气泡与 user 气泡一样不带分支操作（[决策](../../../.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.md)）——并能在重连后从同一权威恢复。
 
-键盘消息提交会根据所寻址会话的运行状态和 steering 能力解析投递方式。空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，浏览器持久化的 General Settings 偏好会把普通 Enter 分配为 `Queue`（默认值）或 `Steer`，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 仍然换行。已寻址 subagent 即使正在运行，也会让这两个手势都使用其仅支持 Queue 的继续执行传输。该偏好只影响支持 steering 的繁忙态手势对，发送按钮与非键盘提交操作仍使用 Queue。Composer Steer 复用现有尽力而为的 `session.prompt(mode: 'steer')` 契约：如果当前 next-step 窗口在接纳前关闭，AgentLoop 会把消息接纳为下一条唤醒 Queue 轮次，不显示失败，也不会丢失草稿事务。
+键盘消息提交会根据所寻址会话的运行状态和 steering 能力解析投递方式。空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，浏览器持久化的 General Settings 偏好会把普通 Enter 分配为 `Queue`（默认值）或 `Steer`，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 仍然换行。已寻址 subagent 即使正在运行，也会让这两个手势都使用其仅支持 Queue 的继续执行传输。该偏好只影响支持 steering 的繁忙态手势对，发送按钮与非键盘提交操作仍使用 Queue。Composer Steer 复用现有尽力而为的 `session.prompt(mode: 'steer')` 约定：如果当前 next-step 窗口在接纳前关闭，AgentLoop 会把消息接纳为下一条唤醒 Queue 轮次，不显示失败，也不会丢失草稿事务。
 
 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。
 
@@ -60,4 +60,4 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 - **审批面板的「始终允许此类」暂缓**：持久授权需要授权存储设计；今天只能回答允许一次／拒绝。
 - **TodoPanel 将过长条目截成单行省略号**：figma 条没有换行或展开入口，完整文本无法在行内读完。
 - **Queue 编辑仅支持文本**：包含非文本块的行仍显示扁平化预览，但由于内联编辑器无法保留这些块，其编辑控件会被禁用。文本行进入编辑模式后，删除和严格 steering（中途引导）操作会被保存和取消取代；Enter 保存，Escape 取消。
-- **Queue 严格 steering 会保留完整消息**：Agent 运行期间，steering 操作会以原子方式把所寻址的 Queue 单次入队项转移到当前 next-step 窗口。包含混合内容的行仍可使用此操作，因为它会转发不可变消息，而非文本投影。带 placement 的 Host 快照会在会话流末尾渲染待处理 steering，直到已消费的 `user/message` 折叠进持久 transcript（文本记录），因此立即展示、重连和回放共享同一个线性权威。
+- **Queue 严格 steering 会保留完整消息**：agent 运行期间，steering 操作会以原子方式把所寻址的 Queue 单次入队项转移到当前 next-step 窗口。包含混合内容的行仍可使用此操作，因为它会转发不可变消息，而非文本投影。带 placement 的 Host 快照会在会话流末尾渲染待处理 steering，直到已消费的 `user/message` 折叠进持久 transcript，因此立即展示、重连和回放共享同一个线性权威。
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index 7c2cb356ec..e9810d98da 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-deliverables/README.md
 README.md: 189dedd88fed6914012204118ccdf9bdd0cd3bb2
-README.zh.md: bfcec3c54602533028942ed167b9526eaf3ca959
+README.zh.md: ba493549bd0bc3f8a2adbda5989448e497f0af93
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index bfcec3c546..ba493549bd 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-产物文件的功能属主：把"完成的一轮以其产出文件收尾"的产物行注册进 chat 视图的 `conversation.chat.turnTail` 空位。全部策略都在本包内；从 cordis.yml 中删去本插件那一行即可整体移除该交互面，属主视图以零成本渲染一个空的空位。
+产出文件功能的属主：把已完成轮次末尾的产出文件行注册到 chat 视图的 `conversation.chat.turnTail` slot 中。全部策略都在本包内；从 cordis.yml 中删去本插件那一行即可整体移除该界面，属主视图无需额外开销即可渲染空 slot。
 
-`producedForClosing` 从 tail 空位的 owner 通货——定稿的快照节点与收尾 assistant 的 seq——推导一轮产出的文件。词表是改写工具自身的跟随 `locations`，绝不是收尾正文：无论模型是否记得点名，产出文件都会被列出。改写按渲染意图识别而非工具名——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此新的改写工具靠声明自己做了什么加入。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。
+`producedForClosing` 根据 tail slot 属主提供的当前数据，即定稿快照节点和收尾助手的 seq，推导一个轮次产出的文件。依据的是修改工具自身附带的 `locations`，而不是收尾正文：无论模型是否记得点名，产出文件都会被列出。修改操作按渲染意图而非工具名识别：diff 卡片，或 `kind` 为 `edit` 的通用卡片（即 `str_replace_editor` 的 insert 操作所呈现的形态）；因此新的修改工具只需声明自身行为即可加入。读取、删除和失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在轮次边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。
 
-`ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个安静的标签、至多六枚 chip（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每枚 chip 经由 owner 提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
+`ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个低调的标签、至多六个标签项（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每个标签项经由属主提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
 
-收尾正文承载同一份词表。本插件提供 chat 视图按收尾消息查询的 `chatFileMentions` service：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析——两条路径共享的 basename 保持死文本而不猜测，因此提及链接永远不会打开错误的文件或 404。解析成功的提及保留 code 胶囊并采用 markdown 样式表的链接语言——静止为链接蓝、悬停出下划线，与 URL 提升的行内代码完全一致——完整路径作为其 `title`；提及绝不会渲染在锚点内部或流式文本里。决策记录：[行内文件提及 Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md)。
+收尾正文承载同一份词表。本插件提供供 chat 视图按收尾消息查询的 `chatFileMentions` 服务：`producedFileMentions` 按精确路径解析行内代码 token，或当 token 恰好是且仅是一条产出路径的 basename 时解析——两条路径共享同一 basename 时，文本保持不可点击而不作猜测，因此提及链接永远不会打开错误的文件或 404。解析成功的提及保留代码标签，并采用 Markdown 样式表的链接样式：静止时为链接蓝色，悬停时显示下划线，与 URL 提升的行内代码完全一致——完整路径作为其 `title`；提及绝不会渲染在链接内部或流式文本中。决策记录：[行内文件提及 Agent Note](../../../.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md)。
 
 ## 模型体验
 
@@ -20,4 +20,4 @@
 
 ## 已知限制与暂缓事项
 
-- **提及匹配只认精确路径或唯一 basename。**后缀式提及（`out/index.html` 写作 `index.html` 可解析；`deep/out/index.html` 写作 `out/index.html` 则不行）保持死文本；放宽匹配器等真实的收尾消息形态需要时再做。
+- **提及匹配只认精确路径或唯一 basename。**后缀式提及（`out/index.html` 写作 `index.html` 可解析；`deep/out/index.html` 写作 `out/index.html` 则不行）保持不可点击；等真实的收尾消息形态产生需求后再放宽匹配规则。
diff --git a/packages/client/ui-settings-general/README.i18n.yaml b/packages/client/ui-settings-general/README.i18n.yaml
index 9c61e62c48..8d7a5f1d4b 100644
--- a/packages/client/ui-settings-general/README.i18n.yaml
+++ b/packages/client/ui-settings-general/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-settings-general/README.md
 README.md: ab27e073dc76335efc619f56365d1705007f7ef2
-README.zh.md: 18bbecf67f51ae63bfacd4ba78437bea95b50bee
+README.zh.md: 16ff5604bee5425569b783e27a29699344f630e3
diff --git a/packages/client/ui-settings-general/README.zh.md b/packages/client/ui-settings-general/README.zh.md
index 18bbecf67f..16ff5604be 100644
--- a/packages/client/ui-settings-general/README.zh.md
+++ b/packages/client/ui-settings-general/README.zh.md
@@ -4,9 +4,9 @@
 
 设置界面无特定功能归属的文案与产品引导插件：在设置界面注册所有不属于单一功能的内容，包括外壳的触发器、标题栏与关闭控件内容、本地配置文件操作，「通用」分区及其 `settings.general.item` slot、`settings` 字典，以及第一个有序欢迎步骤。归具体功能所有的行（「权限」、「语言」、「外观」）、分区（「模型」）和条件式首次使用引导步骤仍由各自的功能包提供。
 
-回环浏览器通过 `settings.describe` 加载提供方的 `hasDocument` 能力，且只有在 Host 确认可准备好一份由提供方持有的本地文档时才渲染**打开配置文件**。该操作发送无路径参数且仅限回环访问的 `settings.openDocument` 请求；Host 会再次解析提供方路径、在文档缺失时将其创建出来，并交给原生文本编辑器（macOS 上使用 `open -t`，绕过浏览器文件关联；Linux 和 Windows 上使用桌面文件关联；WSL 上经 `wslpath -w` 转换后使用 Windows 文件关联）。打开失败时该操作仍可使用，并渲染本地化错误。临时读取失败或 Host 拓扑变化后，重新打开对话框或重新连接会刷新可用性。远程浏览器从不注册该操作，也从不发起这项特权 settings 读取。
+回环浏览器通过 `settings.describe` 加载提供方的 `hasDocument` 能力，且只有在 Host 确认可准备好一份由提供方持有的本地文档时才渲染**打开配置文件**。该操作发送无路径参数且仅限回环访问的 `settings.openDocument` 请求；Host 会再次解析提供方路径、在文档缺失时将其创建出来，并交给原生文本编辑器（macOS 上使用 `open -t`，绕过浏览器文件关联；Linux 和 Windows 上使用桌面文件关联；WSL 上经 `wslpath -w` 转换后使用 Windows 文件关联）。打开失败时该操作仍可使用，并渲染本地化错误。临时读取失败或 Host 拓扑变化后，重新打开对话框或重新连接会刷新可用性。远程浏览器从不注册该操作，也从不发起这项特权设置读取。
 
-`src/onboarding-copy.ts` 是完整通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源；GUI 支持的两种 locale 都有意渲染同一份中文文案。宿主端在 user-settings seam 中注册 `ui-onboarding`。loopback 浏览器会比较 `welcomeNoticeVersion` 是否精确相等，仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等，并会保留同级设置；`host/settings-changed` 则让页面在通知被外部确认后，无需重新加载即可推进。非 loopback 浏览器不能访问受保护的 settings API：它仍会显示通知，但「继续」只推进当前浏览器进程，重新加载后会再次显示通知。版本不同时，系统也会有意重新显示通知。欢迎页保留原文的每个段落，仅强调最后一段中指定的句段，初始焦点落在标题上，并且没有关闭操作、Escape、点击遮罩或次要操作路径。其文案和确认状态均不会进入会话日志或模型请求。通知明确以 `DSH_TELEMETRY_DISABLED=1` 作为遥测关闭方式。
+`src/onboarding-copy.ts` 是完整通知文案和 `WELCOME_NOTICE_VERSION` 的唯一可编辑来源；GUI 支持的两种 locale 都有意渲染同一份中文文案。宿主端在用户设置 seam 中注册 `ui-onboarding`。回环浏览器会比较 `welcomeNoticeVersion` 是否精确相等，仅在「继续」操作成功后写入当前值。该路径变更在不同标签页间幂等，并会保留同级设置；`host/settings-changed` 则让页面在通知被外部确认后，无需重新加载即可推进。非回环浏览器不能访问受保护的设置 API：它仍会显示通知，但「继续」只推进当前浏览器进程，重新加载后会再次显示通知。版本不同时，系统也会有意重新显示通知。欢迎页保留原文的每个段落，仅强调最后一段中指定的句段，初始焦点落在标题上，并且没有关闭操作、Escape、点击遮罩或次要操作路径。其文案和确认状态均不会进入会话日志或模型请求。通知明确以 `DSH_TELEMETRY_DISABLED=1` 作为遥测关闭方式。
 
 ## 模型体验
 
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 97008e3e0c..edc17bb0f8 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-tool/README.md
 README.md: d6bc0f248cffaf4c65ecf6d97c7a4afb17fc8941
-README.zh.md: f4e8044fe6e10e1fbdfb70987efe07c884fa9ac8
+README.zh.md: 2e6674480fda93a8e3f83fdbddb798880a546335
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index f4e8044fe6..2e6674480f 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -2,23 +2,23 @@
 
 [English](README.md) | 中文
 
-Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交付一个已经排好位置的 root call；本包渲染该 root 及其 Code Dispatch 子调用，并把每个原子调用通过 keyed slot `tool.call.toolview` 分发。没有注册的 Tool 名称使用通用卡片。
+客户端工具展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交付一个已经排好位置的根调用；本包渲染该根调用及其 Code Dispatch 子调用，并通过键控 slot `tool.call.toolview` 分发每个原子调用。未注册的工具名称使用通用卡片。
 
-业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和递归 `subCalls` 投影；conversation view 继续负责 ChatFlow 位置。
+业务 UI 包只注册协议中的工具名称和原子视图，不配对会话事件、不重建 transcript，也不负责根调用与子调用的拓扑。运行时继续负责调用与结果的配对、生命周期和递归 `subCalls` 投影；对话视图继续负责在 ChatFlow 中的位置。
 
-## 渲染契约
+## 渲染约定
 
-`ToolCallTree` 接收一个已经包含递归 `subCalls` 的 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准 call block，让 root 与任意深度的 child 经过同一条原子分发路径，不再订阅独立的 parent-to-children map。
+`ToolCallTree` 接收一个已经包含递归 `subCalls` 的根 `ToolCallBlock`、选中状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准调用块，让根调用与任意深度的子调用经过同一条原子分发路径，不再订阅独立的父子映射。
 
-每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 契约，供分页和 selection 使用。
+每个根调用和子调用的包装层都保留 `conversation.chat.tool` 的调用锚点 DOM 约定，供分页和 selection 使用。
 
-本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 为 `terminal`、`read`、`diff`、`search` 和 `web` render intent 共用同一组纯 card model。本版本不认识的 intent 标签和格式错误的 wire card 数据都会回退为压平的 Tool result 文本。
+本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行渲染器与详情渲染器为 `terminal`、`read`、`diff`、`search` 和 `web` 渲染意图共用同一组纯卡片模型。未知的意图标签和格式错误的协议卡片数据都会回退为展平的工具结果文本。
 
-通用行把已知 Tool 名称归类为 search、read、shell、write、edit、code 或 generic 变体。运行中、成功、失败和中断状态只来自冻结的 call/result slice。只有用户调用 Host 打开文件回调时，文件路径才相对会话 `cwd` 解析；展示代码不读取 Session service。
+通用行把已知工具名称归类为搜索、读取、shell、写入、编辑、代码或通用变体。运行中、成功、失败和中断状态只来自冻结的调用／结果切片。只有用户调用 Host 打开文件回调时，文件路径才相对会话 `cwd` 解析；展示代码不读取会话服务。
 
-## 原子 Tool 视图
+## 原子工具视图
 
-业务所有方把自己的 wire Tool 名称注册进 `tool.call.toolview`：
+业务属主把自己的协议工具名称注册到 `tool.call.toolview`：
 
 ```ts ignore-check
 ctx.slots.inject('tool.call.toolview', () =>
@@ -28,22 +28,22 @@ ctx.slots.inject('tool.call.toolview', () =>
   }, BusinessToolRow))
 ```
 
-owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`、可选 `cwd`，以及普通的 `openFile`／`inspect` 回调。注册项会收到正常的 Session slot runtime share，但不会收到 React node、Runtime service 或 root/subcall 知识。
+属主载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`、可选 `cwd`，以及普通的 `openFile`／`inspect` 回调。注册项会收到标准的会话 slot 运行时共享数据，但不会收到 React 节点、运行时服务或根调用／子调用拓扑信息。
 
-本包当前拥有 generic fallback，以及 bash/pwsh、read、write/edit、grep/glob、web、todo、question 和 Code Dispatch 的内置展示。`ui-skill` 展示了业务包如何拥有 `skill` 注册。
+本包当前负责通用回退，以及 bash/pwsh、读取、写入／编辑、grep/glob、web、todo、question 和 Code Dispatch 的内置展示。`ui-skill` 展示了业务包如何拥有 `skill` 注册。
 
-各类卡片的上限与 fallback 规则仍由对应的 [terminal](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)、[diff](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)、[read](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)、[search](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md) 和 [web](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) Note 负责。
+各类卡片的上限与回退规则仍由对应的 [terminal](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)、[diff](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)、[read](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)、[search](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md) 和 [web](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) Note 负责。
 
 ## 模型体验
 
-无，因为本包只渲染已经记录的 Tool 调用和结果，不改变模型请求、Tool 执行或 Session Event。
+无，因为本包只渲染已经记录的工具调用和结果，不改变模型请求、工具执行或会话事件。
 
 #### KV Cache 影响
 
-无。本包只负责 Client 展示。
+无。本包只负责客户端展示。
 
 ## 已知限制与后续工作
 
-- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时/UI 契约已为未来的嵌套生产者做好准备。
-- 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
+- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时／UI 约定已为未来的嵌套生产方做好准备。
+- 现有第一方 Tool 视图初期仍集中在本包，之后可以通过键控 slot 独立迁回各自业务包。
 - Tool 文案暂时复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml
index 047513c346..1a1dd057f0 100644
--- a/packages/client/ui-workspace/README.i18n.yaml
+++ b/packages/client/ui-workspace/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-workspace/README.md
 README.md: 1ec07bd41e72bb5a26b2cfc3bf90e57e7d92db08
-README.zh.md: 18d9e356a9e5deb38624f377d41b2fc8bc677294
+README.zh.md: 8edd0fed6d3bdefd9df339a8b3d0588533264538
diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md
index 18d9e356a9..8edd0fed6d 100644
--- a/packages/client/ui-workspace/README.zh.md
+++ b/packages/client/ui-workspace/README.zh.md
@@ -2,25 +2,25 @@
 
 [English](README.md) | 中文
 
-共享 Workspace 浏览器与选择器插件。`WorkspaceBrowser` 填充侧边栏的 `sidebar.workspaces` slot，`WorkspacePicker` 则填充页面局部 Session Intent 主视觉区的 `conversation.hero.workspace` slot；两个表层使用同一套 Workspace 菜单和添加流程。
+共享 Workspace 浏览器与选择器插件。`WorkspaceBrowser` 填充侧边栏的 `sidebar.workspaces` slot，`WorkspacePicker` 则填充页面局部 Session Intent 主视觉区的 `conversation.hero.workspace` slot；两个界面使用同一套 Workspace 菜单和添加流程。
 
-该浏览器通过全局运行时钩子将 Session 行渲染为分组或扁平形式，并负责 Workspace 添加／重命名和 Workspace 内的重排序流程。非空白查询会以单一扁平结果列表替代任一浏览模式：不区分大小写的标题和 Workspace 子串匹配项会立即显示，经 250 ms 防抖的 Host 请求则会加入经过排序的当前对话内容匹配项及其摘要片段。英文搜索输入框及其防御性请求路径会移除 NUL，将查询限制在传输 schema 规定的 500 个 UTF-16 code unit 内且不会拆分 surrogate pair，并保留现有的防抖与取消行为。每次新查询都会中止前一个请求；内容搜索失败时，元数据匹配项仍会显示，同时给出警告。列表最多显示 20 条结果，并会在查询过宽时提示用户缩小范围；打开所选 Session 时既不会清除查询，也不会跳转至特定事件。
+该浏览器通过全局运行时钩子将 Session 行渲染为分组或扁平形式，并负责 Workspace 添加／重命名和 Workspace 内的重排序流程。非空白查询会以单一扁平结果列表替代任一浏览模式：不区分大小写的标题和 Workspace 子串匹配项会立即显示，经 250 ms 防抖的 Host 请求则会加入经过排序的当前对话内容匹配项及其摘要片段。英文搜索输入框及其防御性请求路径会移除 NUL，将查询限制在传输 schema 规定的 500 个 UTF-16 代码单元内且不会拆分代理项对，并保留现有的防抖与取消行为。每次新查询都会中止前一个请求；内容搜索失败时，元数据匹配项仍会显示，同时给出警告。列表最多显示 20 条结果，并会在查询过宽时提示用户缩小范围；打开所选 Session 时既不会清除查询，也不会跳转至特定事件。
 
-该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。不同的规范路径即使 basename 和显示标题相同，仍会作为由 id 区分的独立 Workspace；侧边栏的悬停详情会显示完整路径。每个注册各自声明一个**目录流子洞**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **添加工作区…** 操作仅在本表层的洞被占用时渲染（每次菜单渲染读取占用状态；洞为空意味着该组合没有选目录能力——seam 文档化的无流程默认行为，此时侧边栏区头直接不渲染添加按钮，而非留下一个点了没反应的按钮）。本包持有触发与接纳：占用者经洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。添加只有一条路径：占用者自带的新建文件夹能力已经覆盖了全新目录，因此不再单设按名称创建的对话框。菜单只在确有多个目标可选时出现——没有 Workspace 可列时，锚点手势直接拉起流程，而不是弹出只有一行的浮层；在列表基线落地前，空列表不算最终结果。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。Session 行内的 Archive 操作不经确认对话框直接提交（非破坏性：日志和 workspace 记账席位保持不变），通过 `ctx.workspaces.archiveSession` 归档；归档集合回声落地后，该行从所有分组视图——workspace 分组、Ungrouped、内容搜索和平铺列表——中消失，失败只作为控制台诊断输出，树保持不变。blank「新会话」行是纯占位：不渲染行菜单和时间标签（其中还没有发生任何事），rename/fork/归档都从首条 prompt 落地后才可用。
+该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。不同的规范化路径即使 basename 和显示标题相同，仍会作为由 id 区分的独立 Workspace；侧边栏的悬停详情会显示完整路径。每个注册各自声明一个**目录流子 slot**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **添加工作区…** 操作仅在当前界面的 slot 被占用时渲染（每次菜单渲染读取占用状态；slot 为空意味着该组合没有目录选择能力——seam 文档化的无流程默认行为，此时侧边栏区头直接不渲染添加按钮，而非留下一个点了没反应的按钮）。本包持有触发与接纳：占用方通过 slot 的属主交互约定（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。添加只有一条路径：占用者自带的新建文件夹能力已经覆盖了全新目录，因此不再单设按名称创建的对话框。菜单只在确有多个目标可选时出现——没有 Workspace 可列时，锚点手势直接拉起流程，而不是弹出只有一行的浮层；在列表基线落地前，空列表不算最终结果。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。Session 行内的 Archive 操作不经确认对话框直接提交（非破坏性：日志和 workspace 记账席位保持不变），通过 `ctx.workspaces.archiveSession` 归档；归档集合回声落地后，该行从所有分组视图——workspace 分组、Ungrouped、内容搜索和平铺列表——中消失，失败只作为控制台诊断输出，树保持不变。空白的「新会话」行只是占位符：不渲染行菜单和时间标签（其中还没有发生任何事），重命名、fork 和归档都从首条提示词落地后才可用。
 
 Workspace 和 Session 悬浮卡片会复制对应行被截断的值：激活 Workspace 卡片会写入其完整目录路径，激活非空白 Session 卡片则会写入其完整显示标题。临时的空白「新会话」卡片保持只读，因为其本地化标签是占位文案，并非会话内容。只有浏览器接受剪贴板写入后，卡片才会显示由字典提供的已复制状态。
 
-Session 行内的 Fork 操作在源会话最后一个已完成轮次处 fork，在 client 端递增继承的持久化标题后再打开子会话；尾部半角或全角括号编号会原样式递增，无编号标题追加 ` (1)`。源会话与子会话在 workspace 组内始终作为同级行展示，谱系只保留为 session 数据。Fork 或改名失败都不会改变当前选中项，改名失败时已创建的子会话仍会留在列表中。
+Session 行内的 fork 操作在源会话最后一个已完成轮次处 fork，在客户端递增继承的持久化标题后再打开子会话；尾部半角或全角括号编号会原样式递增，无编号标题追加 ` (1)`。源会话与子会话在 workspace 组内始终作为同级行展示，谱系只保留为 session 数据。Fork 或改名失败都不会改变当前选中项，改名失败时已创建的子会话仍会留在列表中。
 
 Session 行渲染运行时的实时 `pendingInteraction` 分类：审批显示**等待审批**，计划审阅显示**计划待审**，普通问题显示**等待回答**。每个待处理交互都使用一枚琥珀色警告点，优先级高于运行指示器；普通行的悬浮卡片重复显示本地化状态，普通行和搜索结果行则都以相同文本提供面向辅助技术的视觉隐藏标签。运行状态使用蓝色指示器及其隐藏标签；空闲行会保留空的状态槽位。
 
 两个目标 slot 都由其他插件声明，因此 `apply` 使用 `slots.inject()` 在各自的声明生命周期内完成注册，并在目标 slot 的声明恢复后重新注册。
 
-共享侧边栏投影会隐藏持久化 Session 摘要中带有 `origin: 'subagent'` 的行；用户从所选 parent 的 subagent 页头目录进入这些对话。每个可见的普通行都会在经不间断的 subagent 谱系可达的任一后代运行时继承蓝色活动指示器；其悬停与无障碍文本会报告确切的运行中后代数量，同时不会把空闲 parent 描述为正在运行。普通 fork 仍然可见，并会终止此聚合，因为仅有谱系不会设置该 origin。待处理的用户交互优先于会话自身的运行中状态，二者无论哪一项存在都会保持为行的主要状态，而后代活动仍作为独立的悬停与无障碍状态保留。两者均不存在时，后代活动优先于绿色的未查看完成提醒；最后一个运行中的后代停止后，该提醒会重新出现。运行时仍保留隐藏行，供对话、标题与已寻址传输状态使用。
+共享侧边栏投影会隐藏持久化 Session 摘要中带有 `origin: 'subagent'` 的行；用户从所选父级的 subagent 页头目录进入这些对话。每个可见的普通行都会在经不间断的 subagent 谱系可达的任一后代运行时继承蓝色活动指示器；其悬停与无障碍文本会报告确切的运行中后代数量，同时不会把空闲 parent 描述为正在运行。普通 fork 仍然可见，并会终止此聚合，因为仅有谱系不会设置该 origin。待处理的用户交互优先于会话自身的运行中状态，二者无论哪一项存在都会保持为行的主要状态，而后代活动仍作为独立的悬停与无障碍状态保留。两者均不存在时，后代活动优先于绿色的未查看完成提醒；最后一个运行中的后代停止后，该提醒会重新出现。运行时仍保留隐藏行，供对话、标题与已寻址传输状态使用。
 
 ## 模型体验
 
-无。选择器属于浏览器 chrome；这里没有任何内容进入模型请求。
+无。选择器属于浏览器界面；这里没有任何内容进入模型请求。
 
 #### KV Cache 影响
 
diff --git a/packages/credentials/credentials/README.i18n.yaml b/packages/credentials/credentials/README.i18n.yaml
index beeeef0ffd..34c5ffc794 100644
--- a/packages/credentials/credentials/README.i18n.yaml
+++ b/packages/credentials/credentials/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/credentials/credentials/README.md
 README.md: 95ef76d145727340d8135bf1d48babd6d8adb882
-README.zh.md: b3404858025d4ec53a76548c78c1808d2c858844
+README.zh.md: dce426fde734e3368317ccd2fa6848ca1e00048e
diff --git a/packages/credentials/credentials/README.zh.md b/packages/credentials/credentials/README.zh.md
index b340485802..dce426fde7 100644
--- a/packages/credentials/credentials/README.zh.md
+++ b/packages/credentials/credentials/README.zh.md
@@ -4,13 +4,13 @@
 
 抽象凭据 seam（`ctx.credentials`）。一条准则，三个推论：
 
-**配置只携带对机密的引用，绝不携带机密本身。** settings 分节或 `cordis.yml` 条目写 `apiKeyEnv: DEEPSEEK_API_KEY`，引用背后的值归凭据 provider 所有。于是设置文档可以放心同步、放心渲染进配置界面；`describe()` 无需持有值就能回答「配置了吗、来自哪层、能否写入」；轮换机密不触碰任何配置文件。
+**配置只携带对机密的引用，绝不携带机密本身。** settings 分节或 `cordis.yml` 条目写 `apiKeyEnv: DEEPSEEK_API_KEY`，引用背后的值归凭据提供方所有。于是设置文档可以放心同步、放心渲染进配置界面；`describe()` 无需持有值就能回答「配置了吗、来自哪层、能否写入」；轮换机密不触碰任何配置文件。
 
 **消费方按操作解析。** `resolve(ref)` 在每个操作开始时调用（LLM 适配器每次模型请求解析一次），绝不跨操作缓存——正是这次读取让改过的凭据无需重启任何插件就作用于下一次请求。
 
 **空的存储值等于不存在。**处处如此：`resolve` 跳过它，`describe` 报告未配置。空白永远不会伪装成已配置的机密。
 
-## 接口面
+## 接口
 
 ```ts
 import type { Context } from 'cordis'
@@ -25,24 +25,24 @@ await ctx.credentials.set(ref, 'sk-…')                   // rejects while a re
 await ctx.credentials.unset(ref)                         // no-op when absent; same shadowing rule
 ```
 
-`credentials/updated (ref)` 在 provider 管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测，永不触发。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+`credentials/updated (ref)` 在提供方管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测，永不触发。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
 
-`set`/`unset` 的遮蔽规则是刻意的响亮失败：当只读来源（本地 provider 中即活跃进程环境）正在提供该引用时，写入会表面成功而解析仍返回遮蔽值——seam 选择直接拒绝，并通过 `describe().writable` 让界面提前把该引用渲染为只读。
+`set`/`unset` 的遮蔽规则是刻意设计为明确报错：当只读来源（本地提供方中即当前进程环境）正在提供该引用时，写入会表面成功而解析仍返回遮蔽值——seam 选择直接拒绝，并通过 `describe().writable` 让界面提前把该引用渲染为只读。
 
-## Providers
+## 提供方
 
-[`dsh-credentials-local`](../credentials-local/README.md) 把继承的进程环境叠加在其受管 `$DSH_HOME/.credentials.yaml` 文档之上，并以启动器的项目和用户 `.env` 层作为后备。seam 形状为 keyring、辅助命令、KMS 后端的 provider 留好了位置；远端 settings provider 永远不必携带机密。
+[`dsh-credentials-local`](../credentials-local/README.md) 把继承的进程环境叠加在其受管 `$DSH_HOME/.credentials.yaml` 文档之上，并以启动器的项目和用户 `.env` 层作为后备。seam 形状为 keyring、辅助命令、为 KMS 后端提供方留好了位置；远端设置提供方永远不必携带机密。
 
-## Model Experience
+## 模型体验
 
-经由消费它的 LLM 适配器间接生效：解析出的值为适配器的提供方请求授权，每个模型可见面都归适配器所有。
+经由消费它的 LLM 适配器间接生效：解析出的值为适配器的提供方请求授权，所有模型可见接口都由适配器负责。
 
 #### KV Cache effect
 
 无直接失效；凭据绝不进入请求前缀。
 
-## Known Limitations and Deferred Work
+## 已知限制与暂缓事项
 
 - **不提供枚举**——seam 只回答被问到的引用；配置界面从 settings schema 得知引用集合，`list()` 没有当前消费方。
-- **引用限定为环境变量形状**——在有 provider 需要更丰富寻址前，保持单一扁平的 POSIX 标识符命名空间。
+- **引用限定为环境变量形状**——在有提供方需要更丰富的寻址方式前，保持单一扁平的 POSIX 标识符命名空间。
 - **进程环境变化不可见**——不可能为其发事件；界面只能在自身导航时重新读取 `describe()`。
diff --git a/packages/feedback/README.i18n.yaml b/packages/feedback/README.i18n.yaml
index d0fe492135..fce2946cff 100644
--- a/packages/feedback/README.i18n.yaml
+++ b/packages/feedback/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/feedback/README.md
 README.md: af8e9d5c4903594299284d09f880aa8929f5e051
-README.zh.md: 01a26798d0b7dc8b376929252a60a99fff11b640
+README.zh.md: 9156ff1c8da8ed1128488fcacaf454425468163a
diff --git a/packages/feedback/README.zh.md b/packages/feedback/README.zh.md
index 01a26798d0..9156ff1c8d 100644
--- a/packages/feedback/README.zh.md
+++ b/packages/feedback/README.zh.md
@@ -2,10 +2,10 @@
 
 [English](README.md) | 中文
 
-feedback 家族让人类记录对会话的评价，但不据此采取任何动作。反馈属于持久的会话日志内容，与模型对话以及后续可能读取它的任何策略相互独立。
+反馈家族让人类记录对会话的评价，但不据此采取任何动作。反馈属于持久的会话日志内容，与模型对话以及后续可能读取它的任何策略相互独立。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | `command-feedback/` | 与触发方式无关的 `feedback/record` 事件，以及面向用户的 `/feedback` 生产方 | 无 |
 
-被记录的评价仅写入日志：它绝不会进入模型 surface 或派生历史。挂载后，[`dsh-session-telemetry-otel`](../session/session-telemetry-otel) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
+被记录的评价仅写入日志：它绝不会进入模型接口或派生历史。挂载后，[`dsh-session-telemetry-otel`](../session/session-telemetry-otel) 会观察 `feedback/record`，以释放待处理的遥测前缀，或在遥测已禁用时警告反馈将留在本地；采集本身与该策略相互独立。
diff --git a/packages/feedback/command-feedback/README.i18n.yaml b/packages/feedback/command-feedback/README.i18n.yaml
index 20eb2741d6..3267e4e515 100644
--- a/packages/feedback/command-feedback/README.i18n.yaml
+++ b/packages/feedback/command-feedback/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/feedback/command-feedback/README.md
 README.md: e2eb6d4cf2b40e83efad1fa158edd72578658f56
-README.zh.md: f87067d67cf9dcb8f4da97afe3a9d59eb828faf7
+README.zh.md: 607a117a00cd0abd49c3a338256b65a2b958e73e
diff --git a/packages/feedback/command-feedback/README.zh.md b/packages/feedback/command-feedback/README.zh.md
index f87067d67c..607a117a00 100644
--- a/packages/feedback/command-feedback/README.zh.md
+++ b/packages/feedback/command-feedback/README.zh.md
@@ -4,7 +4,7 @@
 
 与触发方式无关的会话反馈，以及面向用户的 `/feedback` 采集。本包导出 `recordFeedback(session, text)`，后者追加一个仅写入日志的 `feedback/record` 事件。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附的 Web 客户端无需模型轮次即可执行。
 
-## 命令契约
+## 命令约定
 
 | 输入 | 结果 |
 |---|---|
@@ -15,9 +15,9 @@
 
 ## 本插件做什么、不做什么
 
-`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集契约。
+`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或宿主集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集约定。
 
-反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../interaction/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
+反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../interaction/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序接口、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
 
 权威记录是该事件，而不是命令记录，因为反馈可能来自 `/feedback` 之外的触发方式。让载荷不进入 `command/run`，可避免两条记录携带相同文本。
 
@@ -32,7 +32,7 @@
   name: '@deepseek-ai/dsh-command-feedback'
 ```
 
-随附的 `dsh` 基础组合无条件挂载此命令；它没有配置，也不依赖持久 goal 栈。Web 客户端通过命令适配器暴露该命令。无头模式、ACP 自动化和 JSON-RPC 不提供命令适配器，因此不会暴露它。
+随附的 `dsh` 基础组合无条件挂载此命令；它没有配置，也不依赖持久目标栈。Web 客户端通过命令适配器暴露该命令。无头模式、ACP 自动化和 JSON-RPC 不提供命令适配器，因此不会暴露它。
 
 ## 模型体验
 
@@ -40,7 +40,7 @@
 
 #### 模型看到的内容
 
-无。斜杠输入、`feedback/record` 以及确认文本都不出现在模型请求中。反馈事件和注册表生命周期记录仅写入日志且不携带 `surfaceOp`，因此它们绝不会进入有序 surface、`deriveMessages()` 或系统提示词。在某个轮次中记录反馈不会改变该轮次剩余的请求。
+无。斜杠输入、`feedback/record` 以及确认文本都不出现在模型请求中。反馈事件和注册表生命周期记录仅写入日志，且不携带 `surfaceOp`，因此它们绝不会进入有序接口、`deriveMessages()` 或系统提示词。在某个轮次中记录反馈不会改变该轮次剩余的请求。
 
 #### Token 影响
 
@@ -50,10 +50,10 @@
 
 与模型请求路径无关。记录只追加到会话日志，不触碰已经可复用的请求前缀。本包贡献的任何内容都不会使缓存复用失效。
 
-## 已知限制与暂缓工作
+## 已知限制与暂缓事项
 
 - **没有反馈检索或管理 surface**：可选的 OTel 插件仅将该事件用作共享触发器。本包不为 `feedback/record` 提供检索、聚合、分类或面向模型的工具。
 - **没有结构化字段**：一条条目就是一个自由文本字符串，没有类别、严重程度或关联事件链接，因此无法在不重读文本的情况下按主题过滤反馈。
-- **不支持修改或撤回**：会话日志是仅追加的，本包也不新增 tombstone，因此错误的条目会一直保留在记录中，只能由后续条目取代。
+- **不支持修改或撤回**：会话日志是仅追加的，本包也不新增删除标记，因此错误的条目会一直保留在记录中，只能由后续条目取代。
 - **没有显式持久化屏障**：确认文本紧随追加而非 flush，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。为反馈强制同步写盘并不值得；需要该保证的消费方可自行等待 `ctx.sessions.flush(session)`。
 - **随附的产品入口中只有 Web 使用此命令**：无头模式、ACP 自动化和 JSON-RPC 不提供命令适配器，因此 `/feedback` 在那里不可用。
diff --git a/packages/fs/tool-str-replace-editor/README.i18n.yaml b/packages/fs/tool-str-replace-editor/README.i18n.yaml
index 7d08a33f9a..b6733eb3b8 100644
--- a/packages/fs/tool-str-replace-editor/README.i18n.yaml
+++ b/packages/fs/tool-str-replace-editor/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/tool-str-replace-editor/README.md
 README.md: 97e9e0ab9ade7c7241c1aac3e2489e055d01ff8f
-README.zh.md: 48358eb3c9d81ddad6a83c4ff3ef0cf6542096b1
+README.zh.md: a71f040f3b1383604fa1f151f797906dd343c49a
diff --git a/packages/fs/tool-str-replace-editor/README.zh.md b/packages/fs/tool-str-replace-editor/README.zh.md
index 48358eb3c9..a71f040f3b 100644
--- a/packages/fs/tool-str-replace-editor/README.zh.md
+++ b/packages/fs/tool-str-replace-editor/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-基于 `ctx.fs` 的独立模型可见 `str_replace_editor`。它可与持久 Bash、一次性 Bash、沙箱 Bash 或其他终端表面组合。
+基于 `ctx.fs` 的独立模型可见 `str_replace_editor`。它可与持久 Bash、一次性 Bash、沙箱 Bash 或其他终端接口组合。
 
 ## 配置
 
@@ -13,13 +13,13 @@
 
 ## 工具
 
-Schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从一开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
+schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从 1 开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
 
 ## 模型体验
 
 ### 工具 schema
 
-#### 模型所见
+#### 模型看到的内容
 
 生成的 [`str_replace_editor` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-str-replace-editor)，其中包含配置的 `description`。本插件不贡献独立系统提示词段。
 
@@ -33,7 +33,7 @@ Schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert
 
 ### 工具结果
 
-#### 模型所见
+#### 模型看到的内容
 
 查看操作返回带行号文本或浅层目录列表。调用会向展示层提供文件位置，创建/替换还会提供 diff 卡片。修改操作返回简洁确认。长查看结果保留前缀并追加截断提示。
 
@@ -49,4 +49,4 @@ Schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert
 
 - 操作面向 UTF-8 文本，不支持二进制文件。
 - `str_replace` 刻意拒绝零匹配或多匹配，且没有 `replace_all` 参数。
-- 每个修改操作都会经过 `fs/write-intent` 或 `fs/edit-intent`，解析当前 session 的沙箱策略，并交由挂载的文件系统与策略插件执行。
+- 每个修改操作都会经过 `fs/write-intent` 或 `fs/edit-intent`，解析当前会话的沙箱策略，并交由挂载的文件系统与策略插件执行。
diff --git a/packages/host/directory-picker-native/README.i18n.yaml b/packages/host/directory-picker-native/README.i18n.yaml
index 9e4a432c5e..9f2c323183 100644
--- a/packages/host/directory-picker-native/README.i18n.yaml
+++ b/packages/host/directory-picker-native/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/directory-picker-native/README.md
 README.md: 4dd0c79d080fe097d063cfd2200e30aafc2d2d42
-README.zh.md: 8ebf2a6e978ad042e522e7e2831a508501d3eca5
+README.zh.md: bbf6d361f48792a9f385a83032546f6d95fd3fc8
diff --git a/packages/host/directory-picker-native/README.zh.md b/packages/host/directory-picker-native/README.zh.md
index 8ebf2a6e97..bbf6d361f4 100644
--- a/packages/host/directory-picker-native/README.zh.md
+++ b/packages/host/directory-picker-native/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-[目录选择 seam](../directory-picker/README.md) 的**原生 OS 选择器后端**：`NativeDirectoryPicker` 以 `native` 能力注册 `ctx.directoryPicker`，其 `pick(signal)` 每次调用打开一个原生选择器并解析出所选绝对路径（取消时为 `null`）。平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在 spawn 的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。只有操作者坐在宿主屏幕前时才可用——远程部署应组合 [`-browse`](../directory-picker-browse/README.md)。命令边界（`DirectoryPickerRunner`）与平台事实可注入。共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.md)。
+[目录选择 seam](../directory-picker/README.md) 的**原生 OS 选择器后端**：`NativeDirectoryPicker` 以 `native` 能力注册 `ctx.directoryPicker`，其 `pick(signal)` 每次调用打开一个原生选择器并解析出所选绝对路径（取消时为 `null`）。平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在派生的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。只有操作者坐在宿主屏幕前时才可用——远程部署应组合 [`-browse`](../directory-picker-browse/README.md)。命令边界（`DirectoryPickerRunner`）与平台事实可注入。共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.md)。
 
-**双面包**：browser half（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并经洞的 owner 会话上报唯一结果（所选路径／取消／失败）。两个目录流程声明必须同时处于 live 状态，任一贡献才会安装。因此一行 cordis.yml 同时组合原生交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。
+**双面包**：浏览器端（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流 slot注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并通过 slot 的属主交互约定上报唯一结果（所选路径／取消／失败）。两个目录流程声明必须同时处于有效状态，任一贡献才会安装。因此一行 cordis.yml 同时组合原生交互的两侧；客户端不包含任何按能力类型进行的分支，挂载第二个流程包会在加载期失败（slot 的 kind 为 `single`）。
 
 ## 模型体验
 
 无。该后端服务于 GUI 宿主的目录选择；这里没有任何内容进入模型请求。
 
-#### KV 缓存影响
+#### KV Cache 影响
 
 无；该包既不组装也不发送提供方请求。
 
diff --git a/packages/host/frontend-static/README.i18n.yaml b/packages/host/frontend-static/README.i18n.yaml
index 9d757aaf6c..d894667745 100644
--- a/packages/host/frontend-static/README.i18n.yaml
+++ b/packages/host/frontend-static/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/frontend-static/README.md
 README.md: 82ba5a2cd0937e2c24505648aa1e3daec6bf2ece
-README.zh.md: 1130aa7cc241ee5245fceaba0ef66fcf95871e67
+README.zh.md: 205c44838e40697cf1429a198d313391ea7acbae
diff --git a/packages/host/frontend-static/README.zh.md b/packages/host/frontend-static/README.zh.md
index 1130aa7cc2..205c44838e 100644
--- a/packages/host/frontend-static/README.zh.md
+++ b/packages/host/frontend-static/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`），占据 [webserver](../webserver/README.md) 的唯一回退席位，并按壳层锁定的语义服务已构建的前端目录——越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 `application/octet-stream` 提供，GET／HEAD 之外的方法在没有匹配的具名 route 时返回 405。每个 index 响应都会经过 webserver 已注册的 index 转换（`applyIndexTaps`），启动 manifest（元数据清单）就是经这条路径送达页面的。`distIndex` 是组合应用的组装事实：[`dsh-web-app`](../../bundle/web-app/README.md) 通过前端包的 exports 解析它并挂载本插件；部署绝不硬编码它。
+Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`），占据 [webserver](../webserver/README.md) 的唯一回退席位，并按壳层锁定的语义服务已构建的前端目录——越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 `application/octet-stream` 提供，GET／HEAD 之外的方法在没有匹配的具名路由时返回 405。每个 index 响应都会经过 webserver 已注册的 index 转换器（`applyIndexTaps`），启动 manifest（元数据清单）就是经这条路径送达页面的。`distIndex` 是组合应用的组装事实：[`dsh-web-app`](../../bundle/web-app/README.md) 通过前端包的 exports 解析它并挂载本插件；部署绝不硬编码它。
 
 回退席位只有单一所有者（第二次占据会抛错），并受 effect 作用域约束：dispose（资源释放）插件的 fiber 会释放席位，此后无人占据的 webserver 回答 404。
 
diff --git a/packages/host/webserver/README.i18n.yaml b/packages/host/webserver/README.i18n.yaml
index bd80f27f3e..63ced787c1 100644
--- a/packages/host/webserver/README.i18n.yaml
+++ b/packages/host/webserver/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/webserver/README.md
 README.md: 569c3f0c19db2c308beaef35baaf915fd39768cd
-README.zh.md: b311ebffa3fb067e684e9e443c2ac02dab917d61
+README.zh.md: 92b4bcad252eb8a2e29100333a8ae19b9e30e994
diff --git a/packages/host/webserver/README.zh.md b/packages/host/webserver/README.zh.md
index b311ebffa3..92b4bcad25 100644
--- a/packages/host/webserver/README.zh.md
+++ b/packages/host/webserver/README.zh.md
@@ -2,17 +2,17 @@
 
 [English](README.md) | 中文
 
-Web HTTP 与 upgrade route 注册插件（默认导出 `HttpServerService`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层契约，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 认领唯一的回退席位，应答所有未被具名 route 命中的请求：只允许一个持有者（第二次认领会抛错；随附的持有者是 SPA dist 服务器 [`dsh-frontend-static`](../frontend-static/README.md)），席位未被认领时返回 404。`tapIndex(transform)` 添加一个 index.html 转换，`applyIndexTaps(html)` 按注册顺序对一段响应体运行已注册的转换：fallback 持有者在每次 index 响应时调用它。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给回退席位。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不承载任何面向请求的语义。
+Web HTTP 与 upgrade route 注册插件（默认导出 `HttpServerService`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为路由模式是组合层约定，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 认领唯一的回退席位，应答所有未被具名 route 命中的请求：只允许一个持有者（第二次认领会抛错；随附的持有者是 SPA dist 服务器 [`dsh-frontend-static`](../frontend-static/README.md)），席位未被认领时返回 404。`tapIndex(transform)` 添加一个 index.html 转换，`applyIndexTaps(html)` 按注册顺序对一段响应体运行已注册的转换：fallback 持有者在每次 index 响应时调用它。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给回退席位。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不承载任何面向请求的语义。
 
-该包不了解任何 harness 概念，也不提供任何文件服务：`/api` HTTP 桥接与下行 WebSocket 是 connection 插件的 route，插件 bundle 与 HMR（热模块替换）事件流是 modules／hmr 插件的 route，dist 服务则属于 fallback 持有者。upgrade handler 拥有协议握手与连接内容；webserver 只交付原始 socket 与 request。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）。该服务器只服务 Web（浏览器）形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。
+该包不了解任何 harness 概念，也不提供任何文件服务：`/api` HTTP 桥接与下行 WebSocket 是 connection 插件的 route，插件 bundle 与 HMR（热模块替换）事件流是 modules／hmr 插件的 route，dist 服务则属于 fallback 持有者。upgrade handler 拥有协议握手与连接内容；webserver 只交付原始 socket 与 request。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）。该服务器只服务 Web 浏览器形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。
 
-监听失败（EADDRINUSE……）会从激活过程抛出，以 bind 诊断使 Loader 组合 reject；失败的候选 fiber 会被 dispose（资源释放）。处理 HTTP 请求时抛错（例如 fallback 持有者的 `decodeURIComponent` 收到格式错误的百分号转义，或客户端在请求体传输中途断开）时，服务器会响应 400；若响应头已经发出，则销毁 socket，并记录 warning，但绝不会退出进程。upgrade handler 抛错或升级 socket 出现传输错误时，会记录 warning 并销毁对应 socket。资源释放会启动 `close()` 与 `closeAllConnections()`，销毁所有受跟踪的升级 socket，并仅在 HTTP server 与这些 socket 均已关闭后返回。
+监听失败（EADDRINUSE……）会从激活过程抛出，以 bind 诊断使 Loader 组合被拒绝；失败的候选 fiber 会被 dispose（资源释放）。处理 HTTP 请求时抛错（例如 fallback 持有者的 `decodeURIComponent` 收到格式错误的百分号转义，或客户端在请求体传输中途断开）时，服务器会响应 400；若响应头已经发出，则销毁 socket，并记录警告，但绝不会退出进程。upgrade handler 抛错或升级 socket 出现传输错误时，会记录 warning 并销毁对应 socket。资源释放会启动 `close()` 与 `closeAllConnections()`，销毁所有受跟踪的升级 socket，并仅在 HTTP server 与这些 socket 均已关闭后返回。
 
 ## 模型体验
 
 无。该包只是浏览器与其他插件所注册 HTTP／upgrade route 之间的 Web 载体，其中没有任何内容会进入模型请求。
 
-#### KV 缓存影响
+#### KV Cache 影响
 
 无；该包既不组装也不发送提供方请求。
 
diff --git a/packages/pty/tool-bash-persistent/README.i18n.yaml b/packages/pty/tool-bash-persistent/README.i18n.yaml
index aec30c2b4a..9f9e3e2cc2 100644
--- a/packages/pty/tool-bash-persistent/README.i18n.yaml
+++ b/packages/pty/tool-bash-persistent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/pty/tool-bash-persistent/README.md
 README.md: cfb3acf41803f5b06ecb3f56ee8ffc29ce9147b1
-README.zh.md: a525485933344a8f9bc218456c099efdef572902
+README.zh.md: 9689c42d4252dc804fb4100c41c6ead9dadb910c
diff --git a/packages/pty/tool-bash-persistent/README.zh.md b/packages/pty/tool-bash-persistent/README.zh.md
index a525485933..9689c42d42 100644
--- a/packages/pty/tool-bash-persistent/README.zh.md
+++ b/packages/pty/tool-bash-persistent/README.zh.md
@@ -2,16 +2,16 @@
 
 [English](README.md) | 中文
 
-模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包拥有工具契约和 shell 复用；PTY 后端与沙箱策略由部署选择。
+模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包负责工具约定和 shell 复用；PTY 后端与沙箱策略由部署选择。
 
 ## 配置
 
 | 键 | 默认值 | 含义 |
 |---|---:|---|
-| `backendType` | `shell` | 每个 Agent shell 使用的已注册 PTY 后端。 |
+| `backendType` | `shell` | 每个 agent（智能体）的 shell 使用的已注册 PTY 后端。 |
 | `timeoutMs` | `300000` | 单条命令的墙钟时间上限；超时会关闭 shell。 |
 | `maxOutputChars` | `16000` | 命令输出最多保留的字符数；固定诊断会在此后追加。 |
-| `description` | 持久 shell 描述 | 面向模型的环境契约。 |
+| `description` | 持久 shell 描述 | 面向模型的环境约定。 |
 
 ## 模型体验
 
@@ -19,7 +19,7 @@
 
 #### 模型所见
 
-生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash-persistent)，其中包含配置的 `description`。本插件不贡献独立系统提示词段；persona 与环境指导由部署负责。
+生成的 [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash-persistent)，其中包含配置的 `description`。本插件不贡献独立系统提示词段；角色设定与环境指导由部署负责。
 
 #### Token 影响
 
@@ -33,7 +33,7 @@
 
 #### 模型所见
 
-每个 Agent 的命令共享一个 shell，因此 cwd、导出的环境变量、已激活环境、函数和后台任务会跨调用保留。结果不包含私有完成标记和 shell 提示符。经封装的命令以非零状态结束时，结果会追加 `[exit code: N]`；若 shell 在报告该状态前退出，则改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]`，或在后端既未提供退出码也未提供信号时追加 `[shell exited]`；随后重置 shell，并告知模型下次调用从新 shell 开始。长输出保留仍可读取的最早前缀并追加截断提示；若 PTY 已丢弃真正的开头，结果会明确说明，而不是把尾部伪装成完整输出。超时返回有界的部分输出、关闭状态不确定的 shell，并报告该重置。
+每个 agent 的命令共享一个 shell，因此 cwd、导出的环境变量、已激活环境、函数和后台任务会跨调用保留。结果不包含私有完成标记和 shell 提示符。经封装的命令以非零状态结束时，结果会追加 `[exit code: N]`；若 shell 在报告该状态前退出，则改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]`，或在后端既未提供退出码也未提供信号时追加 `[shell exited]`；随后重置 shell，并告知模型下次调用从新 shell 开始。长输出保留仍可读取的最早前缀并追加截断提示；若 PTY 已丢弃真正的开头，结果会明确说明，而不是把尾部伪装成完整输出。超时返回有界的部分输出、关闭状态不确定的 shell，并报告该重置。
 
 #### Token 影响
 
@@ -45,6 +45,6 @@
 
 ## 已知限制与延后工作
 
-- 工具需要拥有它的 Agent 和真实 PTY 后端。
+- 工具需要拥有它的 agent 和真实 PTY 后端。
 - 显式 `exit` 与超时会丢弃 shell 状态。取消同样会重置 shell 并丢弃结果，即使已经能观察到完整状态标记也是如此；下次调用创建新 shell。
-- 网络访问、软件包镜像等环境事实应写入配置的 `description`，而非包默认描述。
+- 网络访问、包镜像等环境事实应写入配置的 `description`，而非包默认描述。
diff --git a/packages/session/session-checkpoint-policy/README.i18n.yaml b/packages/session/session-checkpoint-policy/README.i18n.yaml
index e435cf36d3..939a2b0a5f 100644
--- a/packages/session/session-checkpoint-policy/README.i18n.yaml
+++ b/packages/session/session-checkpoint-policy/README.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 packages/session-persistence/session-checkpoint-policy/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-checkpoint-policy/README.md
 README.md: 01ed3c694967b1a86245d01b9d9f7eecd1193348
 README.zh.md: e2c197c0cc1d942a045c1ea22c1fb257f6e4059d
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 2ab76b4da9..fb28edd00c 100644
--- a/packages/session/session-persistence-jsonl/README.i18n.yaml
+++ b/packages/session/session-persistence-jsonl/README.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 packages/session-persistence/session-persistence-jsonl/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence-jsonl/README.md
 README.md: b7fa8fc2918711dd24eeba67132a267452d401f9
 README.zh.md: 59d21c6171e857849c4ab48940d66962fffbfdeb
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index f6d2d2926b..a0a2787e08 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/README.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 packages/session-persistence/session-persistence-sqlite/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence-sqlite/README.md
 README.md: 4961f62bf6854c343d35b8406c9d721590274534
 README.zh.md: 8610ef56f737bac8781536ea26a5b48dbf67ed48
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index 5b131371b8..d6ca806d49 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/README.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 packages/session-persistence/session-persistence/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence/README.md
 README.md: 89c7cd5ebaff6f9ce9df9b60a50121dff4ddeeb5
 README.zh.md: 1ef7eb6c6c507167f61bb5df7c4ce8183aac5d0d
diff --git a/packages/session/session-projection-cache/README.i18n.yaml b/packages/session/session-projection-cache/README.i18n.yaml
index 37c8d986f9..db570ff22a 100644
--- a/packages/session/session-projection-cache/README.i18n.yaml
+++ b/packages/session/session-projection-cache/README.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 packages/session-projection/session-projection-cache/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-projection-cache/README.md
 README.md: 5d4ad07fab6648acdb40c6aa86d32cc78b4c016e
 README.zh.md: 827480658b8c69647380a782c1a983b390380108
diff --git a/packages/session/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
index 34c1910b16..4ca60337ff 100644
--- a/packages/session/session-projection/README.i18n.yaml
+++ b/packages/session/session-projection/README.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 packages/session-projection/session-projection/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-projection/README.md
 README.md: a42e88c262915fc5e53cd72205079cbc8029a8df
 README.zh.md: f60a48bd41f0c33edb85a495ada9b6818ec46ee5
diff --git a/packages/session/session-telemetry-otel/README.i18n.yaml b/packages/session/session-telemetry-otel/README.i18n.yaml
index 0424414fac..d3fe513463 100644
--- a/packages/session/session-telemetry-otel/README.i18n.yaml
+++ b/packages/session/session-telemetry-otel/README.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 packages/telemetry/session-telemetry-otel/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-telemetry-otel/README.md
 README.md: 585995ce409255df9608bc33b76625374bc67669
 README.zh.md: 6d2cfa4d492cee7f90d557c83f5c1ab3c730c6e5
diff --git a/packages/session/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml
index ee9c7288b1..0532902287 100644
--- a/packages/session/session-telemetry/README.i18n.yaml
+++ b/packages/session/session-telemetry/README.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 packages/telemetry/session-telemetry/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-telemetry/README.md
 README.md: 67d95bcc62bbf6783f8dcd11f0236d8c926b557b
 README.zh.md: 1ee0e0eb14bb06c8ac669cd417f2ee2ce46ca430
diff --git a/packages/session/session-title-all-messages-llm/README.i18n.yaml b/packages/session/session-title-all-messages-llm/README.i18n.yaml
index 54909b457e..e364ffc0a7 100644
--- a/packages/session/session-title-all-messages-llm/README.i18n.yaml
+++ b/packages/session/session-title-all-messages-llm/README.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 packages/session-title/session-title-all-messages-llm/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-title-all-messages-llm/README.md
 README.md: 25ec92432b5c2d18624f2f4d851552ee2b3bf5d0
 README.zh.md: 947aa614741b2b0bd50e70f1d273a625a5624cc6
diff --git a/packages/session/session-title-first-message-llm/README.i18n.yaml b/packages/session/session-title-first-message-llm/README.i18n.yaml
index 1353b0b4e6..523ebc0bee 100644
--- a/packages/session/session-title-first-message-llm/README.i18n.yaml
+++ b/packages/session/session-title-first-message-llm/README.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 packages/session-title/session-title-first-message-llm/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-title-first-message-llm/README.md
 README.md: c24d4de1fa945d11b5a868cad88a94ed14ad3891
 README.zh.md: 1f864b16c473654d0a52716cddbe26fe087860dc
diff --git a/packages/session/session-title-llm/README.i18n.yaml b/packages/session/session-title-llm/README.i18n.yaml
index 4ae7cd4aa7..8709d2c3db 100644
--- a/packages/session/session-title-llm/README.i18n.yaml
+++ b/packages/session/session-title-llm/README.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 packages/session-title/session-title-llm/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-title-llm/README.md
 README.md: 342687b5aa0cd35a70abf8cc66b3fe80342bce0b
 README.zh.md: f6f39e07d300dbe53faa51514c29699ca1d6a3d2
diff --git a/packages/settings/README.i18n.yaml b/packages/settings/README.i18n.yaml
index 146f0ad32e..08a6c15dfd 100644
--- a/packages/settings/README.i18n.yaml
+++ b/packages/settings/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/settings/README.md
 README.md: 6f3719c58564a90fec3bd9f305cfaeb2b7bf0bf4
-README.zh.md: 0efb16dd4e5d5faa5f16814b94d55a20dc4c06c3
+README.zh.md: 41a640e3bbb8b297f08e354e8bdcf56e524ea3bd
diff --git a/packages/settings/README.zh.md b/packages/settings/README.zh.md
index 0efb16dd4e..41a640e3bb 100644
--- a/packages/settings/README.zh.md
+++ b/packages/settings/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-该包族通过注册的命名空间与可替换存储 provider 解析用户可编辑配置。
+该包族通过注册的命名空间与可替换存储提供方解析用户可编辑配置。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/settings/settings-local/README.i18n.yaml b/packages/settings/settings-local/README.i18n.yaml
index ec26e4241f..83a2d75b38 100644
--- a/packages/settings/settings-local/README.i18n.yaml
+++ b/packages/settings/settings-local/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/settings/settings-local/README.md
 README.md: d1f3d755f9073acdf6fcfc5d1de883d74cc023c4
-README.zh.md: 03c7ef7c35312d9e1e4a86b0df71412875af7d6c
+README.zh.md: 2fe97435d56774351343b92fcbd5f80ee2680fd1
diff --git a/packages/settings/settings-local/README.zh.md b/packages/settings/settings-local/README.zh.md
index 03c7ef7c35..2fe97435d5 100644
--- a/packages/settings/settings-local/README.zh.md
+++ b/packages/settings/settings-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-文件 settings provider。一个 YAML 或 JSON 文档承载全部 namespace 分节；外部编辑经 `ctx.settings` 热发布，`update()` 在写锁下先重读文档再原子写回，保留用户的 YAML 注释、当前未加载插件所拥有的分节，以及任何本进程尚未观察到的磁盘变更。
+基于文件的设置提供方。一个 YAML 或 JSON 文档承载全部 namespace 分节；外部编辑经 `ctx.settings` 热发布，`update()` 在写锁下先重读文档再原子写回，保留用户的 YAML 注释、当前未加载插件所拥有的分节，以及任何本进程尚未观察到的磁盘变更。
 
 ## 配置
 
@@ -17,28 +17,28 @@
 
 ## 行为
 
-- **启动报错响亮，重载保留最后可用值。** 存在但非法的文档使插件加载失败；运行中不可读或不可解析的编辑只告警并保留最后可用分节。文档缺失时所有 namespace 按默认值与 `base` 解析；删除文档发布同样的空状态。
-- **每次写入都是一次读-改-写。** persist 先重读文档并把任何差异发布进 seam——无论是仍在 watcher 防抖窗口内的外部编辑、watcher 漏掉的变更，还是另一个进程的写入——再基于这份新鲜文本渲染，因此写入绝不会复活陈旧文档，也不会丢掉未观察到的同级分节。若磁盘上的文档已变为非法，写入响亮拒绝，而不是覆盖用户的手工编辑。
-- **写入持有跨进程写锁。** 读-渲染-rename 流程在 `wx` 创建的 `<file>.lock` 同级文件下运行，带指数退避与 2 s 的获取期限。竞争者会超时，但不会移除现有锁，因为锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方；遗留锁恢复须由操作者执行。读取方从不取锁：rename 提交是原子的，重载因此始终一致。
-- **写回原子、仅属主可读、抗符号链接。** 渲染以 `0600` 权限独占创建随机后缀临时同级文件（`wx` 拒绝跟随预埋符号链接）后 rename 覆盖目标，失败时清理临时文件。
+- **启动失败并明确报错，重载保留最后可用值。** 存在但非法的文档使插件加载失败；运行中不可读或不可解析的编辑只告警并保留最后可用分节。文档缺失时所有 namespace 按默认值与 `base` 解析；删除文档发布同样的空状态。
+- **每次写入都是一次读-改-写。** persist 先重读文档并把任何差异发布进 seam——无论是仍在 watcher 防抖窗口内的外部编辑、watcher 漏掉的变更，还是另一个进程的写入——再基于这份新鲜文本渲染，因此写入绝不会复活陈旧文档，也不会丢掉未观察到的同级分节。若磁盘上的文档已变为非法，写入会明确报错并拒绝执行，而不是覆盖用户的手工编辑。
+- **写入持有跨进程写锁。** 读-渲染-rename 流程在以 `wx` 创建的同级锁文件 `<file>.lock` 保护下运行，带指数退避与 2 s 的获取期限。竞争者会超时，但不会移除现有锁，因为锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方；遗留锁恢复须由操作者执行。读取方从不取锁：rename 提交是原子的，重载因此始终一致。
+- **写回原子、仅属主可访问、抗符号链接。** 渲染以 `0600` 权限独占创建随机后缀临时同级文件（`wx` 拒绝跟随预埋符号链接）后 rename 覆盖目标，失败时清理临时文件。
 - **YAML 编辑是叶子级 diff。** 写入只设置发生变化的值、只删除被移除的键，因此注释、锚点与排版在每个未触碰的节点上以及每个被改键值对的键上都得以保留；被改的数组（或其他非 map 值）整体替换，其中的注释随之一同被换掉。JSON 重新序列化，无注释。
 - **重载与写入共享一条操作链。** watcher 刷新与来自各 namespace 队列的 persist 按队列顺序逐个执行；每次渲染都基于上一次操作提交后的文本。
 - **watcher 的 ready 信号做一次对账。** 初始加载与 watcher 自身的建立存在竞态，因此其间写入的变更绝不会触发事件；ready 时的对账补上这个启动缺口。
-- **Dispose 在每种 watch 模式下都保证静止。** 卸载先把提供方标记为已关闭，在 watcher 存在时将其关闭，再等待所有已排队或进行中的文档操作完成，之后不再有任何发布。
-- **按内容抑制自写。** provider 缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。
+- **dispose（资源释放）在每种 watch 模式下都保证完全停稳。** 卸载先把提供方标记为已关闭，在 watcher 存在时将其关闭，再等待所有已排队或进行中的文档操作完成，之后不再有任何发布。
+- **按内容抑制自写。** 提供方缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。
 - **Host 配置适配器会收到解析后的路径。** `ctx.settings.documentPath` 是 `resolveSpec()` 得出的绝对文件名，包括自定义 YAML/JSON 路径；`prepareDocument()` 会保留现有文件，或在 Host 打开文档前，以仅属主可访问的权限独占创建缺失的空文件。浏览器只收到可用性标志，绝不重建 `$DSH_HOME`，也绝不提交文件系统目标。
 
 ## 模型体验
 
-间接生效：本 provider 只存储并发布 namespace 分节，模型效果经由 `ctx.settings` 的消费插件产生，由各消费者自己的文档描述。
+间接生效：本提供方只存储并发布 namespace 分节，任何模型效果都经由 `ctx.settings` 的消费方产生，并由各消费方自己的接口文档说明。
 
 #### KV Cache 影响
 
-无直接失效；请求前缀的变更由消费插件拥有。
+无直接失效；请求前缀的任何变更均由消费方插件负责。
 
 ## 已知限制与暂缓事项
 
 - **同 namespace 冲突仍是后写胜出** — 写锁加读-改-写让并发写入者不会丢掉彼此的 namespace，但两个写入者编辑同一个 namespace 时仍以较后的写入为准；没有按值合并，也没有修订检查。
 - **漏掉的 watcher 事件在下一个信号前保持不可见** — 读取从不重新 stat 文件，因此 watcher 漏报的变更只会在下一个事件、下一次写入或重启时被并入。
 - **注释保留仅限 YAML 且仅限 map 形状** — JSON 文档重新序列化，无注释（JSON 本身没有），且被改数组内部的注释（或行内附着在被改标量值上的注释）随其所描述的值一同被换掉。
-- **无值间接引用** — 分节存字面值；面向密钥的 `${env:VAR}` 式引用是 seam 层的延后特性。
+- **无值间接引用** — 分节存字面值；面向密钥的 `${env:VAR}` 式引用是暂缓实现的 seam 层功能。
diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml
index b2549e6be1..51c39bf1d0 100644
--- a/packages/settings/settings/README.i18n.yaml
+++ b/packages/settings/settings/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/settings/settings/README.md
 README.md: 0841624e553364fa03f7a1f1209aa72ab13d97e4
-README.zh.md: e8fe4485c2cf6cb6b8710347ebb8dcd1e8424b38
+README.zh.md: a23826bd5e3a19ab491970f3b4dc230d8b750b6a
diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md
index e8fe4485c2..a23826bd5e 100644
--- a/packages/settings/settings/README.zh.md
+++ b/packages/settings/settings/README.zh.md
@@ -2,23 +2,23 @@
 
 [English](README.md) | 中文
 
-抽象用户设置 seam（`ctx.settings`）。一个 provider 持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载 provider 时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
+抽象用户设置 seam（`ctx.settings`）。一个提供方持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载提供方时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
 
 ## 服务 API
 
 - `documentPath` — 提供方拥有用户可编辑文件时，该字段是文件的绝对路径；非文件提供方保留 `undefined`。Host 配置适配器据此派生可用性，而浏览器协议只暴露一个布尔能力，绝不暴露文件系统目标。
 - `prepareDocument()` — 让文档做好供原生编辑器打开的准备后返回该路径。基类实现返回 `documentPath`；文件提供方可先创建缺失的文档。
 - `register(ns, schema, { base?, applies? })` — 返回 owner 的 `SettingsScope`（`get`/`watch`/`update`）。注册是调用方插件 fiber 上的 effect：dispose 该 fiber 即移除 namespace 及其观察者。schema 拒绝的存量分节会使注册本身失败；重复 namespace 立即报错。
-- `describe(options?)` — 每个 namespace 一条描述（`schema.toJSON()` 信封、解析值、分离出的 `base`/`user` 层、`applies`），供配置界面使用；字段出现在 `user` 中即标记其被用户覆盖。`describe({ redactSecrets: true })` 从每一层剥离 `role('secret')` 字段，并附加 `secrets` 槽位列表（`{ path, set }`）；每个 wire 面都必须传入它，纯遍历器 `redactSecrets(schema, value)` 已导出，供其他 wire 使用。
+- `describe(options?)` — 每个 namespace 一条描述（`schema.toJSON()` 封装、解析值、分离出的 `base`/`user` 层、`applies`），供配置界面使用；字段出现在 `user` 中即标记其被用户覆盖。`describe({ redactSecrets: true })` 从每一层剥离 `role('secret')` 字段，并附加 `secrets` 槽位列表（`{ path, set }`）；每个协议接口都必须传入它，纯遍历器 `redactSecrets(schema, value)` 已导出，供其他 wire 使用。
 - `get(ns)` — 解析值；未注册时为 `undefined`。
-- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经 provider 持久化后提交。patch 必须是 JSON 形状的数据：Date、Map、BigInt、非有限数或循环引用会在任何内容持久化前带着以 `$` 为根的路径拒绝（YAML/JSON 存储在重载时会静默扭曲这类值）。校验失败在持久化前拒绝；只读 provider（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。
+- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经提供方持久化后提交。patch 必须是 JSON 形状的数据：Date、Map、BigInt、非有限数或循环引用会在任何内容持久化前带着以 `$` 为根的路径拒绝（YAML/JSON 存储在重载时会静默扭曲这类值）。校验失败在持久化前拒绝；只读提供方（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。
 - `replace(ns, section)` — 整体替换用户分节：这是刻意的重置（`replace({})` 重新继承 `base` 与 schema 默认值）。
 - `mutate(ns, ops)` — 在写入排到队首那一刻的分节上，按序施加 `{ op: 'set' | 'unset', path }` 编辑。这是任何持有**不完整**视图的调用方的删除路径：配置 UI 读到的是脱敏后的 descriptor，据此重建分节再整体替换，会把 wire 从未回传的每个机密都删掉，而一条 op 只点名它真正要改的那个字段。
-- 每次写入都可携带可选的 `expectedRevision`。每个 descriptor 都带有该 namespace 的 `revision`——一个针对其**原始**分节的单调计数器；期望值不再匹配的写入会以 `SettingsConflictError`（`code: 'SETTINGS_CONFLICT'`，并附上两个 revision）被拒绝，而不是覆盖先落地的那个写方。写队列只保证写入的先后次序，它本身分辨不出一个新写方与一个持有过期快照的写方。
-- 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。watch 的 disposer 返回后不再启动新的调用（已排队的那一次会被跳过）；已启动的调用仍会结算。`settings/updated` 事件逐 listener 扇出，一个抛错的 listener 不会饿死其余 listener；异步 listener 的拒绝会被隔离并记入日志，这正是 `INVARIANT` 编码的失败只从同步 listener 重新抛出的原因。
+- 每次写入都可携带可选的 `expectedRevision`。每个 descriptor 都带有该 namespace 的 `revision`——一个针对其**原始**分节的单调计数器；期望值不再匹配的写入会以 `SettingsConflictError`（`code: 'SETTINGS_CONFLICT'`，并附上两个 revision）被拒绝，而不是覆盖先完成写入的写入方。写队列只保证写入的先后次序，它本身分辨不出新的写入方与持有陈旧快照的写入方。
+- 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。watch 的 disposer 返回后不再启动新的调用（已排队的那一次会被跳过）；已启动的调用仍会结算。`settings/updated` 事件逐监听器扇出，一个抛错的 listener 不会饿死其余 listener；异步 listener 的拒绝会被隔离并记入日志，这正是 `INVARIANT` 编码的失败只从同步 listener 重新抛出的原因。
 - 服务卸载先拒绝新写入与观察者调用的启动，再排干全部排队写入与已启动的观察者调用后才完成；registrant fiber 在写入途中被 dispose 时，该写入仍到达存储，但不向任何人提交或通知。
 
-## 提供方契约
+## 提供方约定
 
 子类实现 `writable`、`load()`、`persist(ns, section)`，可选择为一个本地用户可编辑文件重写 `documentPath` 与 `prepareDocument()`，并通过受保护的 `publish(doc)` 推入外部观察到的文档。基类 service init 在服务可注入前加载并发布一次文档；自有 init（watcher、连接）的 provider 先经 `yield* super[Service.init]()` 委托。publish 时每个已注册 namespace 独立重解析：非法分节保留该 namespace 的最后可用值并告警——热重载绝不拖垮进程；启动期与注册期校验则立即报错。
 
@@ -34,10 +34,10 @@
 
 #### KV Cache 影响
 
-无直接失效；把设置值折叠进请求前缀的消费者拥有该变更。
+无直接失效；把设置值折叠进请求前缀的消费方负责该变更。
 
 ## 已知限制与暂缓事项
 
 - **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；尚无 project/managed 分层或按值溯源。
 - **`redactSecrets` 并非一条可被证明的协议边界**：walker 只跟随 `object`/`dict`/`array`，因此只能经由 union、intersection 或 transform 抵达的 `role('secret')` 会被**原样**返回，且 `secrets` 列表为空；而 `schema.toJSON()` 会把 secret 字段的 `.default(...)` 一并带给每个客户端。这两种情况都不会被拒绝；机密无法经由被遍历的容器抵达的 schema，绝不可注册到暴露于协议的 namespace 上。真正的答案是一个 fail-closed 的 `describeForWire()`——它拒绝自己无法证明安全的 schema，并对序列化信封与错误文本做净化——此项暂缓。
-- **跨进程并发由 provider 定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按 provider 行为收敛（本地文件 provider 在写锁下读-改-写，因此 namespace 在并发写入者下不会丢失，同 namespace 冲突按后写胜出解决）。
+- **跨进程并发由提供方定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按提供方行为收敛（本地文件提供方在写锁下读-改-写，因此 namespace 在并发写入者下不会丢失，同 namespace 冲突按后写胜出解决）。
diff --git a/packages/skill/skill-badge/README.i18n.yaml b/packages/skill/skill-badge/README.i18n.yaml
index 4dda53481c..80bfa13b34 100644
--- a/packages/skill/skill-badge/README.i18n.yaml
+++ b/packages/skill/skill-badge/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/skill/skill-badge/README.md
 README.md: 49b38023a7c110bb52bb351668905c702e251216
-README.zh.md: bf7eb0d7d4c0552c07f9cdf5665f8a20df829483
+README.zh.md: f22afd0d957f202eb7b2b5953015f7c0a4c5b571
diff --git a/packages/skill/skill-badge/README.zh.md b/packages/skill/skill-badge/README.zh.md
index bf7eb0d7d4..f22afd0d95 100644
--- a/packages/skill/skill-badge/README.zh.md
+++ b/packages/skill/skill-badge/README.zh.md
@@ -4,7 +4,7 @@
 
 可选的内置 skill（技能）提供方，向 `ctx.skills` 贡献 `dsh-badge`。该 skill 提供官方「powered by dsh」Markdown 片段和随包分发的 PNG，供无法可靠导入远程图片的系统使用。
 
-挂载该插件即可启用提供方。它没有配置。交付的 CLI（命令行界面）组合以 `disabled: true` 包含该插件；用户必须显式启用其 `skill-badge` 配置行，该 skill 才会进入目录。
+挂载该插件即可启用提供方。它没有配置。随附的 CLI（命令行界面）组合以 `disabled: true` 包含该插件；用户必须显式启用其 `skill-badge` 配置行，该 skill 才会进入目录。
 
 该提供方将随包分发的 `assets/` 目录作为 skill 资源基底公开。`dsh-badge.png` 是尺寸为 726×120 的源图资源，消费方以 121×20 的尺寸渲染。
 
diff --git a/packages/subagent/subagent-claude-code/README.i18n.yaml b/packages/subagent/subagent-claude-code/README.i18n.yaml
index 6bc638bdc4..bcbfb4e6de 100644
--- a/packages/subagent/subagent-claude-code/README.i18n.yaml
+++ b/packages/subagent/subagent-claude-code/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-claude-code/README.md
 README.md: e62f60fceea16749296a91377785b81d94d751ca
-README.zh.md: e171524157b2b1696df31753816210d41637a911
+README.zh.md: 79c515e557ef9f576b2b71bf175c64b0eb828d93
diff --git a/packages/subagent/subagent-claude-code/README.zh.md b/packages/subagent/subagent-claude-code/README.zh.md
index e171524157..79c515e557 100644
--- a/packages/subagent/subagent-claude-code/README.zh.md
+++ b/packages/subagent/subagent-claude-code/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本包（package）注册固定的 `claude-code` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中调用官方 Claude Agent SDK，通过共享子进程服务启动 SDK 分发的 Claude Code CLI，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果契约仅返回最终答案。
+本包注册固定的 `claude-code` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中调用官方 Claude Agent SDK，通过共享子进程服务启动 SDK 分发的 Claude Code CLI，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果约定仅返回最终答案。
 
 ## 启动与所有权
 
@@ -20,7 +20,7 @@ SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 
 
 ## 能力与上下文
 
-本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Claude Code 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出契约。每次运行都拥有独立的 SDK query、取消控制器、CLI 进程和不持久化的产品会话。
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Claude Code 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出约定。每次运行都拥有独立的 SDK query、取消控制器、CLI 进程和不持久化的产品会话。
 
 ## 配置
 
@@ -31,7 +31,7 @@ SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 
 
 生产环境使用 `@anthropic-ai/claude-agent-sdk` 提供的 Claude Code CLI，以及宿主机原生设置与身份验证。本插件不安装另一份 CLI、不选择模型、不创建产品主目录、不执行登录，也不探测账户。具有凭证特征的环境变量会在显式 `env` 覆盖生效前被清除，因此供子进程使用的 API 密钥或 token 必须在该配置中显式提供。除非被覆盖，`ANTHROPIC_BASE_URL` 等非凭证端点变量以及 `PATH` 和 `HOME` 等普通环境变量仍会被继承。
 
-请安装此包，并将以下配置项添加到你自己的 `cordis.yml`。正式 CLI 配置默认不会加载此提供方，也不会暴露 `subagent_claude_code`。
+请安装此包，并将以下配置项添加到你自己的 `cordis.yml`。随附的 CLI 配置默认不会加载此提供方，也不会暴露 `subagent_claude_code`。
 
 ```yaml
 - id: subagent-claude-code
@@ -51,7 +51,7 @@ SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 
 
 ## 产品兼容性与证据
 
-运行时依赖精确锁定为 `@anthropic-ai/claude-agent-sdk@0.3.220`，其平台可选依赖提供 Claude Code 2.1.220。强制证据会通过无密钥回环产品路径与带密钥 DeepSeek 路径运行该官方发行版，而 Loader 组合则证明两个选择启用的产品包能够共存，且不会启动任一产品。
+运行时依赖精确锁定为 `@anthropic-ai/claude-agent-sdk@0.3.220`，其平台可选依赖提供 Claude Code 2.1.220。所需证据会通过无密钥回环产品路径与带密钥 DeepSeek 路径运行该官方发行版，而 Loader 组合则证明两个选择性启用的产品包能够共存，且不会启动任一产品。
 
 项目所有者按身份范围授权分发官方 SDK 及每个 SDK 版本声明的官方 CLI／平台载荷。[`THIRD_PARTY_NOTICES.md`](../../../THIRD_PARTY_NOTICES.md) 会披露当前可选载荷闭包，但不会把其声明条款归类为宽松许可证；其他无关的非宽松运行时依赖仍会使第三方声明门禁失败。
 
@@ -75,7 +75,7 @@ Claude Code 子任务会在一个全新的 SDK query 中接收独立文本任务
 
 #### 模型看到的内容
 
-通过 `dsh-tool-subagent`，父级模型只会看到符合严格成功条件的 Claude Code 最终答案，或者在结果未完成时看到消费方给出的原样错误。Claude Code 的推理、工具活动、中间消息、stderr、工作区差异、用量信息和产品标识符均不会复制到父会话。
+通过 `dsh-tool-subagent`，父级模型只会看到符合严格成功条件的 Claude Code 最终答案，或者在结果未完成时看到消费方给出的确切错误。Claude Code 的推理、工具活动、中间消息、stderr、工作区差异、用量信息和产品标识符均不会复制到父会话。
 
 #### 对 token 的影响
 
diff --git a/packages/subagent/subagent-codex/README.i18n.yaml b/packages/subagent/subagent-codex/README.i18n.yaml
index 97c2b9f705..5c0c4a8851 100644
--- a/packages/subagent/subagent-codex/README.i18n.yaml
+++ b/packages/subagent/subagent-codex/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-codex/README.md
 README.md: c25ee90edf8972da66448fe84cb659b0aec79e6f
-README.zh.md: 10c8fcc47a9ab04bca983857bd44ede265c23435
+README.zh.md: 61b6760feeaeae2b3f9ab179d10b7f84e8ac82bf
diff --git a/packages/subagent/subagent-codex/README.zh.md b/packages/subagent/subagent-codex/README.zh.md
index 10c8fcc47a..61b6760fee 100644
--- a/packages/subagent/subagent-codex/README.zh.md
+++ b/packages/subagent/subagent-codex/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-本包（package）注册固定的 `codex` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中启动官方 `codex app-server --stdio` 命令，创建一个临时 Codex 线程，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果契约仅返回最终答案。
+本包注册固定的 `codex` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中启动官方 `codex app-server --stdio` 命令，创建一个临时 Codex 线程，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果约定仅返回最终答案。
 
 ## 启动与所有权
 
-`start(request)` 只接受非空的文本块序列，并根据父会话确定子级 cwd。随后，它通过 [`dsh-subprocess`](../../subprocess/subprocess/README.md) spawn 固定命令，依次执行 `initialize` → `initialized` → `thread/start { cwd, ephemeral: true }`，且仅在 Codex 返回有效的临时线程后才发布此次运行。若在发布前发生失败或取消，它会关闭通信链路、终止受管进程树并等待其退出，然后拒绝 `start()` 调用。
+`start(request)` 只接受非空的文本块序列，并根据父会话确定子级 cwd。随后，它通过 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 派生固定命令，依次执行 `initialize` → `initialized` → `thread/start { cwd, ephemeral: true }`，且仅在 Codex 返回有效的临时线程后才发布此次运行。若在发布前发生失败或取消，它会关闭通信链路、终止受管进程树并等待其退出，然后拒绝 `start()` 调用。
 
 已发布的 `run.result` 恰好启动一个轮次。它只接受与此次运行的线程和轮次匹配的通知，随后等待权威的终止通知 `turn/completed`。以最后一条 `phase: "final_answer"` 的 `agentMessage` 为准；若 Codex 没有发出明确的最终阶段，则以最后一条 `phase: null` 的消息作为兼容性回退。过程说明绝不会取代上述任一答案；成功完成的轮次若没有非空白答案，结果也会判为错误。
 
@@ -16,7 +16,7 @@
 
 ## 能力与上下文
 
-本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Codex 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出契约。临时 Codex 线程 ID 与轮次 ID 仅在此次运行内部可见，绝不会持久化到父会话。
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Codex 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出约定。临时 Codex 线程 ID 与轮次 ID 仅在此次运行内部可见，绝不会持久化到父会话。
 
 ## 配置
 
@@ -27,7 +27,7 @@
 
 生产环境会从 `PATH` 中解析 `codex`，并使用宿主机原生的 Codex 配置与身份验证。本插件不安装 Codex、不选择模型、不创建 `CODEX_HOME`、不执行登录，也不探测版本。子进程 seam 会移除具有凭证特征的环境变量，因此供子进程使用的 API 密钥必须在 `env` 中显式提供；除非被覆盖，`PATH` 和 `HOME` 等普通环境变量值仍然可用。
 
-请安装此包，并将以下配置项添加到你自己的 `cordis.yml`。正式 CLI 配置默认不会加载此提供方，也不会暴露 `subagent_codex`。
+请安装此包，并将以下配置项添加到你自己的 `cordis.yml`。随附的 CLI（命令行界面）配置默认不会加载此提供方，也不会暴露 `subagent_codex`。
 
 ```yaml
 - id: subagent-codex
@@ -47,7 +47,7 @@
 
 ## 产品兼容性与证据
 
-生产环境的协议层有意只实现这一单次执行契约所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 NPM 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
+生产环境的协议层有意只实现这一单次执行约定所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 npm 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
 
 ## 模型体验
 
@@ -69,7 +69,7 @@ Codex 子任务会在一个全新的临时线程中，以单个轮次接收这
 
 #### 模型看到的内容
 
-通过 `dsh-tool-subagent`，父级模型只会看到选定的 Codex 最终答案，或者在结果未完成时看到消费方给出的原样错误。Codex 的过程说明、推理（reasoning）、工具活动、stderr、工作区差异和产品标识符均不会复制到父会话。
+通过 `dsh-tool-subagent`，父级模型只会看到选定的 Codex 最终答案，或者在结果未完成时看到消费方给出的确切错误。Codex 的过程说明、推理（reasoning）、工具活动、stderr、工作区差异和产品标识符均不会复制到父会话。
 
 #### 对 token 的影响
 
@@ -83,7 +83,7 @@ Codex 子任务会在一个全新的临时线程中，以单个轮次接收这
 
 - **每次运行均新建一个进程、一个线程和一个轮次**：不支持续接、恢复、池化、进度流或产品会话持久化。
 - **产品安装和账户状态由宿主管理**：`codex` 缺失或不兼容、配置错误或身份验证失败，都会呈现为启动错误或运行错误；本插件不提供安装程序、登录流程或运行时版本门禁。
-- **兼容性由开发证据锁定**：若要从已验证的 0.146.0 协议基线升级，必须重新生成上游 schema 证据，并重新运行握手、答案选择、审批、取消、无密钥真实产品以及带密钥的 DeepSeek 随机数测试。
+- **兼容性由开发证据锁定**：若要从已验证的 0.146.0 协议基线升级，必须重新生成上游 schema 证据，并重新运行握手、答案选择、审批、取消、无密钥真实产品以及带密钥的 DeepSeek 唯一值测试。
 - **没有人工审批路径**：已知的无人值守审批请求会被拒绝，未知服务器请求会以默认拒绝方式使运行失败；部署方无法通过本包配置允许策略。
 - **仅返回最终文本**：推理、过程说明、中间消息、工具通信、用量信息、stderr 和工作区差异仍只保留在产品内部。
 - **没有可选的共享能力**：对于本提供方，共享服务会拒绝输出 schema、子任务角色设定、工具筛选和 harness 深度强制约束。
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index 25b54630b2..a3d9b5f357 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/support/acp-snapshot/README.md
 README.md: 0b935ef60c33fd24660d8ecf2497f5506157c724
-README.zh.md: 91be3c97bcb67ce10c61513113f683e741bc762f
+README.zh.md: e4e034c1060ea7b0040c75039200611702e05017
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index 91be3c97bc..e4e034c106 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -6,10 +6,10 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 
 四层可单独导入：
 
-- **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动过程中公开异步 spawn 失败，对未处理权限请求快速失败，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才解析或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
-- **`runScenario`（harness）**：通过启动器从确定性 `input.json` 脚本驱动 ACP JSON-RPC stdio，将原始 stdout tee 给预期输出和纯度检查，并在优雅 stdin EOF 后收集每个持久化原始 JSONL 会话日志（父级和 subagent 子级，主级优先）。`AgentUnderTest` 提供绝对 `binScript`、可选 `libBinScript`、`configPath` 和 `tsconfigPath` 路径，因为子进程 cwd 位于仓库外。当生成子级 cwd 自身位于待测授权中时，`workspaceParent` 可以将它从平台临时目录移出。启动失败会在拒绝诊断中保留已捕获 agent stderr。
-- **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每个原生/JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
-- **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件是有序主级/子级清单；场景表不重复其数量。必须在 vitest 收集时调用。
+- **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动阶段报告异步派生失败，并默认拒绝未处理的权限请求，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才完成关闭或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
+- **`runScenario`（harness）**：通过启动器从确定性 `input.json` 脚本驱动 ACP JSON-RPC stdio，将原始 stdout tee 给预期输出和纯度检查，并在优雅 stdin EOF 后收集每个持久化原始 JSONL 会话日志（父会话和 subagent 子会话，主会话优先）。`AgentUnderTest` 提供绝对 `binScript`、可选 `libBinScript`、`configPath` 和 `tsconfigPath` 路径，因为子进程 cwd 位于仓库外。当生成子级 cwd 自身位于待测授权中时，`workspaceParent` 可以将它从平台临时目录移出。启动失败会在拒绝诊断中保留已捕获 agent stderr。
+- **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每种原生／JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已进行 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
+- **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新模式写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件构成有序的主会话／子会话清单；场景表不重复其数量。必须在 vitest 收集时调用。
 
 签入仓库的会话 fixture 使用规范打包行。合并此契约的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
 
@@ -65,11 +65,11 @@ defineAcpSnapshotSuite({
 
 无。该测试专用 harness 记录、规范化并比较 ACP transcript，不会改变 agent 组装的模型请求。
 
-#### KV 缓存影响
+#### KV Cache 影响
 
 无；该包既不组装也不发送提供方请求。
 
-## 已知限制与待完成工作
+## 已知限制与暂缓事项
 
 - **会话收集需要原始 JSONL mode**：`runScenario` 收集持久化 `.jsonl` 日志，因此快照配置使用 `persistenceCompression: 'none'`；压缩 JSONL 和 SQLite 组合没有快照收集路径。
 - **构建 mode 需要当前产物**：先运行 `pnpm run build`，再选择 `DSH_EXAMPLE_MODE=lib`；源 mode 仍是零构建路径。
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
index a61602c07b..90b4ac9a65 100644
--- a/packages/typert/type-meta/README.i18n.yaml
+++ b/packages/typert/type-meta/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/type-meta/README.md
 README.md: 9bd475f8973ec54756fe0e63d5b7fa485381697d
-README.zh.md: 10a6309bc47001d572abb3dd3f794ebfcf6252e8
+README.zh.md: a37efbf2e7da64cad243a7f93515b7e18904bc81
diff --git a/packages/typert/type-meta/README.zh.md b/packages/typert/type-meta/README.zh.md
index 10a6309bc4..a37efbf2e7 100644
--- a/packages/typert/type-meta/README.zh.md
+++ b/packages/typert/type-meta/README.zh.md
@@ -2,25 +2,25 @@
 
 [English](README.md) | 中文
 
-该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、Host Gateway 和 Client API 共享。它负责 Remote Service 基类、装饰器、显式 binding 回退、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方契约；它不执行 TypeScript 分析，也不注册具体 Cordis 服务。
+该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、宿主网关和客户端 API 共享。它负责 Remote 服务基类、装饰器、显式绑定回退、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方约定；它不执行 TypeScript 分析，也不注册具体 Cordis 服务。
 
 ## Remote 声明
 
 - `@Remote` 将公开实例方法标记为可在其注册的 Cordis 服务上直接调用。
 - `@RemoteScope(key)` 标记接收者选自合并声明的作用域 Context 类型的方法。
-- `GatewayService` 将 `super(ctx, serviceKey, options?)` 接收的 Cordis key 同时绑定为默认 wire namespace。
-- `bindTypeRTGateway(this, serviceKey, options?)` 为无法继承 `GatewayService` 的 Service 提供同样可见且冻结的绑定。
+- `GatewayService` 将传给 `super(ctx, serviceKey, options?)` 的 Cordis 键绑定到同一默认协议命名空间。
+- `bindTypeRTGateway(this, serviceKey, options?)` 为无法继承 `GatewayService` 的服务提供同样可见且冻结的绑定。
 - `remoteMethods(service)` 返回按声明顺序排列、与内部状态分离的快照，供 Gateway 的 SRC 回退路径使用。
 
-Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用协作式取消。`InvocationDescriptor.cancellation` 记录这个保留的注入点；signal 绝不会成为 JSON 参数或 lookup 字段。SRC 识别末位参数名，严格生成还会校验它是否具有全局 `AbortSignal` 类型。
+宿主方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用协作式取消。`InvocationDescriptor.cancellation` 记录这个保留的注入点；该信号绝不会成为 JSON 参数或查找字段。SRC 识别末位参数名，严格生成还会校验它是否具有全局 `AbortSignal` 类型。
 
-装饰器初始化器将标记保存在以服务 prototype 为键的模块私有 `WeakMap` 中。它们不会在构造函数上添加 symbol，也不会添加 prototype 属性、参数元数据或运行时反射字段。`GatewayService` 会暴露与显式 helper 相同的 public readonly `typertGateway` 绑定。
+装饰器初始化器将标记保存在以服务原型为键的模块私有 `WeakMap` 中。它们不会在构造函数上添加符号，也不会添加原型属性、参数元数据或运行时反射字段。`GatewayService` 会暴露与显式辅助函数相同的公开只读 `typertGateway` 绑定。
 
 ## TypeRT 协议
 
-业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联 Host 对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteScopeMap` 和 `TypeRTRemoteNamespaceMap`，使 Client 导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、Gateway 和 Client Remote 使用的共享运行时形式。
+业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联宿主对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteScopeMap` 和 `TypeRTRemoteNamespaceMap`，使客户端导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、网关和客户端 Remote 使用的共享运行时形式。
 
-查找包与 Context 包同时负责其契约的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。lookup 或 Host Context provider 提供稳定声明与默认 resolver，Host 组合可以另行配置同步或异步 resolver；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
+查找包与 Context 包同时负责该约定的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。查找提供方或宿主 Context 提供方提供稳定声明与默认解析器，宿主组合可以另行配置同步或异步解析器；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
 
 ## 模型体验
 
@@ -30,7 +30,7 @@ Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用
 
 无直接影响。
 
-## 已知限制与延期工作
+## 已知限制与暂缓事项
 
 - 装饰器标记仅包含方法名，以及直接调用或 Context 调用模式。参数、结果、查找和 schema 反射需要 TypeRT 构建流水线。
 - Remote 装饰器只接受具有字符串名称的公开、非静态实例方法。SRC 执行无法表示重载签名，以及包含解构参数、默认参数或剩余参数的方法签名。
diff --git a/packages/util/atomic-write/README.i18n.yaml b/packages/util/atomic-write/README.i18n.yaml
index 33e1f6014b..5c6b6ac63d 100644
--- a/packages/util/atomic-write/README.i18n.yaml
+++ b/packages/util/atomic-write/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/atomic-write/README.md
 README.md: 2ff4abb6ac10d8b592ccd2056b4f1f92cc8518b0
-README.zh.md: 4284d06422564268bb9e31d1a1ed06ab5271e562
+README.zh.md: 799f01be6f27e00b740c7e0a2c68218f99317451
diff --git a/packages/util/atomic-write/README.zh.md b/packages/util/atomic-write/README.zh.md
index 4284d06422..799f01be6f 100644
--- a/packages/util/atomic-write/README.zh.md
+++ b/packages/util/atomic-write/README.zh.md
@@ -4,7 +4,7 @@
 
 零依赖的原子文件替换，供绝不允许在磁盘上留下不完整、被符号链接劫持或权限过宽内容的文件型存储共用：用户设置文档（`dsh-settings-local`）与凭据存储（`dsh-credentials-local`）。
 
-## 接口面
+## 接口
 
 ```ts
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
@@ -20,15 +20,15 @@ await withFileLock('/home/u/.dsh/settings.yaml', async () => {
 })
 ```
 
-`writeFileAtomic` 提交一份已经渲染好的字符串。契约按故障利用它的先后顺序列出：
+`writeFileAtomic` 提交一份已经渲染好的字符串。约定按故障可能利用各项机制的先后顺序列出：
 
 - **独占创建临时文件**（`wx` + 随机后缀）：open 拒绝跟随预先埋在可猜测临时路径上的符号链接。
 - **全新 inode 携带 `mode` 走完 rename**：替换权限过宽的旧文件时直接收窄，不存在 chmod 竞态。`mode` 为必填，让权限决策始终可见于每个调用点（与所有新建 inode 一样受进程 umask 影响）。
-- **`rename` 替换的是符号链接目标本身**，绝不写穿到其指向的文件。
+- **`rename` 替换的是符号链接本身**，绝不写穿到其指向的文件。
 - **同目录兄弟文件**保证 rename 落在同一文件系统上，交换保持原子。
 - 自动创建父目录；任何失败都会移除临时文件并重新抛出该失败；读取方只会观察到旧内容或完整的新内容。
 
-`withFileLock` 跨进程串行化同一文件的写入方，服务于单靠原子提交无法保证安全的读-渲染-提交循环。锁是以 `wx` 创建的同目录 `<filename>.lock`，因此读取方从不参与竞争；等待方按指数退避，超时即失败而非无限阻塞。竞争者绝不移除现有锁：锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方。
+`withFileLock` 跨进程串行化同一文件的写入方，服务于单靠原子提交无法保证安全的读-渲染-提交循环。锁是以 `wx` 创建的同目录同级文件 `<filename>.lock`，因此读取方从不参与竞争；等待方按指数退避，超时即失败而非无限阻塞。竞争者绝不移除现有锁：锁文件的存在时长无法区分已经崩溃的属主与被暂停但仍存活的写入方。
 
 ## 模型体验
 
diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index 633064ae4c..c8e36d8a5e 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/environment/README.md
 README.md: 599a9ba747905b66452b57717dabcc6f4678a3dd
-README.zh.md: 69f9c670bbb3ea1b2fbddaa7508a19dfb47fad12
+README.zh.md: d728f835b1ece44d2848a618e504951f26fec7e2
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index 69f9c670bb..d728f835b1 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -7,7 +7,7 @@
 | 层 | 来源 id | 它是什么 |
 |---|---|---|
 | 继承的进程环境 | `process` | 启动 shell、CI 任务或容器传入的东西——本次运行的明确意图 |
-| `<invocation cwd>/.env` | `project-env` | harness 被启动于其中的项目；产品信任它配置自己的 agent |
+| `<invocation cwd>/.env` | `project-env` | harness 被启动于其中的项目；产品信任它配置自己的 agent（智能体） |
 | `$DSH_HOME/.env` | `user-env` | 用户自己的机器级默认值 |
 
 这些值同样会进入 `process.env`——用户自己的 `--config` 树和第三方库要读它——但那份压平的视图不是 harness 解析任何值的依据。
@@ -16,7 +16,7 @@
 
 `get(name)` 按可信度从高到低搜索所有层。`getFrom(name, sources)` 只搜索指定的层，不改变这一可信顺序。
 
-**省略某一层是拒绝，不是降级**——绝不能接受某一层的调用方直接不把它列进去，后续任何重新排序都无法让它回来。provider 适配器三层全列，因为产品信任它所运行的项目；该机制是为那些「并非如此」的决策准备的。
+**省略某一层是拒绝，不是降级**——绝不能接受某一层的调用方直接不把它列进去，后续任何重新排序都无法让它回来。提供方适配器三层全列，因为产品信任它所运行的项目；该机制是为那些「并非如此」的决策准备的。
 
 变量名按平台自身的规则匹配：POSIX 上精确匹配，Windows 上不区分大小写。在 Windows 上做大小写敏感的查找会选错层——shell 里的 `deepseek_api_key` 与项目 `.env` 里的 `DEEPSEEK_API_KEY` 对操作系统而言是同一个变量，把它们当成两个就会让项目胜出。
 
@@ -30,7 +30,7 @@ const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 
 当产品 CLI（命令行界面）启动了这棵树时，`environmentOf(ctx)` 返回启动器的快照；否则返回只含继承环境的那一层。该回退并不削弱规则：SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，因此它拥有的一切确实就是它被启动时的环境。
 
-## Known Limitations and Deferred Work
+## 已知限制与暂缓事项
 
-- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 契约](../../boot/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
+- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 约定](../../boot/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
 - **没有按工作区划分的层**：项目层是*调用*目录，在启动时固定。之后在 Web UI 中选择的工作区不贡献任何内容，这是刻意的：跟随它等于让模型自己的工作区在会话中途改变 harness 的环境。
diff --git a/python/development.i18n.yaml b/python/development.i18n.yaml
index b7792acf27..1a7b57f86d 100644
--- a/python/development.i18n.yaml
+++ b/python/development.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write python/development.md
 development.md: b0d4875f0d5b7c8fd2b4b480ac67793741640710
-development.zh.md: 4fda7efbeaa0359bd4999aca148ca21a63c4fd70
+development.zh.md: 053cd1d022ef5fc7d8cff98b9fc3234df6ff4cd1
diff --git a/python/development.zh.md b/python/development.zh.md
index 4fda7efbea..053cd1d022 100644
--- a/python/development.zh.md
+++ b/python/development.zh.md
@@ -2,7 +2,7 @@
 
 [English](development.md) | 中文
 
-根据所需的贡献者成果选择工作流：构建运行时产物、验证 SDK、从源码运行或构建分发包。包行为分别见 [SDK 参考](sdk/README.md)和[运行时载体参考](sdk-runtime/README.md)。
+根据所需的贡献者成果选择工作流：构建运行时产物、验证 SDK、从源码运行或构建分发包。包行为分别见 [SDK 参考](sdk/README.md) 和[运行时载体参考](sdk-runtime/README.md)。
 
 ## 构建运行时产物
 
@@ -13,7 +13,7 @@ pnpm install
 pnpm exec tsx scripts/build-exe-for-python-sdk.ts
 ```
 
-所需 `lib/` 产物已存在时使用 `--skip-build`；如需选择平台，请使用 `--targets=node24-linux-x64,node24-linux-arm64,node24-macos-arm64`。产物写入 `dist-exe/`，脚本会将所选载体同步到 `python/sdk-runtime/`。macOS 构建还会同步 `node-pty` 所需的配套 spawn helper。
+所需 `lib/` 产物已存在时使用 `--skip-build`；如需选择平台，请使用 `--targets=node24-linux-x64,node24-linux-arm64,node24-macos-arm64`。产物写入 `dist-exe/`，脚本会将所选载体同步到 `python/sdk-runtime/`。macOS 构建还会同步 `node-pty` 所需的配套 spawn 辅助程序。
 
 ## 验证 SDK
 
@@ -25,7 +25,7 @@ uv sync --project python/sdk --group test
 uv run --project python/sdk pytest
 ```
 
-`python/sdk/tests/test_bundled_runtime.py` 会运行可用的内置载体；某个载体的产物尚未构建时，会跳过该载体。仓库级测试政策见[测试](../docs/testing.md)。
+`python/sdk/tests/test_bundled_runtime.py` 会运行可用的内置载体；某个载体的产物尚未构建时，会跳过该载体。仓库级测试政策见 [测试](../docs/testing.md)。
 
 交互式冒烟测试需要环境变量或仓库根目录 `.env` 中存在 `DEEPSEEK_API_KEY`：
 
@@ -45,9 +45,9 @@ with DeepSeekHarness() as harness:
 
 完整的源码模式调用见 `python/sdk/tests/manual_sdk_agent_smoke.py`。
 
-## 构建分发物
+## 构建分发包
 
-根目录 `package.json` 的版本是两个 Python 分发物的权威版本。暂存脚本会将该版本注入两个 wheel 包，并将 SDK 固定到同版本的 `deepseek-harness-runtime-bin`。
+根目录 `package.json` 的版本是两个 Python 分发包的权威版本。暂存脚本会将该版本注入两个 wheel 包，并将 SDK 固定到同版本的 `deepseek-harness-runtime-bin`。
 
 纯 SDK wheel 包只需构建一次；每个原生平台分别构建一个运行时 wheel 包：
 
@@ -58,4 +58,4 @@ python scripts/build-python-release.py --package runtime --platform macos-arm64
 pip install --find-links dist-python deepseek-harness=="$version"
 ```
 
-运行时分发物仅提供 wheel 包。发布流水线会连同纯 SDK wheel 包一起发布三个平台 wheel 包：Linux x64、Linux arm64 和 macOS arm64。只有与仓库版本匹配时，才接受 `python-vX.Y.Z` 标签。
+运行时分发包仅提供 wheel 包。发布流水线会连同纯 SDK wheel 包一起发布三个平台 wheel 包：Linux x64、Linux arm64 和 macOS arm64。只有与仓库版本匹配时，才接受 `python-vX.Y.Z` 标签。
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 5d8f68f4cd..2385b3c24c 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -299,22 +299,54 @@ describe('docsPages locale routes', () => {
   })
 
   it('publishes the Cordis core API under matching locale structures', () => {
-    const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md', 'inherited.md']
+    const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md']
     for (const file of files) {
       const root = docsPages.find(page => page.route === `reference/cordis-api/${file}`)
       const english = docsPages.find(page => page.route === `en/reference/cordis-api/${file}`)
-      expect(root?.source).toBe(`docs/cordis-api/${file}`)
+      expect(root?.source).toBe(`docs/cordis-api/${file.replace(/\.md$/, '.zh.md')}`)
+      expect(root?.contentLocale).toBe('zh-CN')
       expect(root?.section).toBe('Cordis API')
-      expect(english?.source).toBe(root?.source)
+      expect(english?.source).toBe(`docs/cordis-api/${file}`)
+      expect(english?.contentLocale).toBe('en-US')
       expect(english?.section).toBe('Cordis Core API')
     }
   })
 
-  it('includes persistence event headings in both locale outlines', () => {
-    const pages = docsPages.filter(page => page.source === 'docs/persistence-catalog.md')
+  it('keeps Cordis inherited on the English fallback in both locales', () => {
+    const pages = docsPages.filter(page => page.route.endsWith('reference/cordis-api/inherited.md'))
     expect(pages).toHaveLength(2)
+    expect(pages.every(page => page.source === 'docs/cordis-api/inherited.md')).toBe(true)
+    expect(pages.every(page => page.contentLocale === 'en-US')).toBe(true)
+  })
+
+  it('includes persistence event headings in both locale outlines', () => {
+    const pages = docsPages.filter(page => page.route.endsWith('reference/persistence-catalog.md'))
+    expect(pages).toHaveLength(2)
+    expect(pages.map(page => page.source).sort()).toEqual([
+      'docs/persistence-catalog.md',
+      'docs/persistence-catalog.zh.md',
+    ])
     expect(pages.map(page => page.outline)).toEqual(['deep', 'deep'])
   })
+
+  it('projects reviewed generated counterparts into root locale routes', () => {
+    const routes = [
+      'reference/capability-seams.md',
+      'reference/agent-lifecycle.md',
+      'reference/tool-execution-pipeline.md',
+      'reference/config-catalog.md',
+      'reference/tool-catalog.md',
+      'reference/persistence-catalog.md',
+      'reference/cordis-api/context.md',
+      'reference/cordis-api/events.md',
+      'reference/cordis-api/fiber.md',
+      'reference/cordis-api/registry.md',
+      'reference/cordis-api/service.md',
+    ]
+    const pages = routes.map(route => docsPages.find(page => page.route === route))
+    expect(pages.every(page => page?.contentLocale === 'zh-CN')).toBe(true)
+    expect(pages.every(page => page?.source.endsWith('.zh.md'))).toBe(true)
+  })
 })
 
 describe('addProjectionFrontmatter', () => {
diff --git a/scripts/translation-pairing.manifest.json b/scripts/translation-pairing.manifest.json
index 112cd3ae4d..acc2a10c14 100644
--- a/scripts/translation-pairing.manifest.json
+++ b/scripts/translation-pairing.manifest.json
@@ -4,18 +4,9 @@
     ".agents/notes/implemented/AGENTS.md",
     ".agents/notes/implemented/CLAUDE.md",
     "docs/AGENTS.md",
-    "docs/agent-lifecycle.md",
-    "docs/capability-seams.md",
-    "docs/config-catalog.md",
-    "docs/cordis-api/",
-    "docs/event-producer-consumer.md",
-    "docs/graph-atlas.md",
+    "docs/cordis-api/inherited.md",
     "docs/i18n/style-samples.md",
     "docs/i18n/terminology.md",
-    "docs/i18n/translation-prompt.md",
-    "docs/module-graph.md",
-    "docs/persistence-catalog.md",
-    "docs/tool-catalog.md",
-    "docs/tool-execution-pipeline.md"
+    "docs/i18n/translation-prompt.md"
   ]
 }
diff --git a/scripts/translation-pairing.spec.ts b/scripts/translation-pairing.spec.ts
index b89df38f52..b5b2a1d5a7 100644
--- a/scripts/translation-pairing.spec.ts
+++ b/scripts/translation-pairing.spec.ts
@@ -19,6 +19,7 @@ import {
   parseTranslationPairingCliArgs,
   parseTranslationPairingManifest,
   partitionGeneratedRegions,
+  requiresSourceLanguageSwitcher,
   translationStructureDiff,
   translationStructureSignature,
 } from './translation-pairing.ts'
@@ -142,6 +143,16 @@ describe('translation pairing manifest', () => {
   })
 })
 
+describe('translation pairing switchers', () => {
+  it('exempts only paired generated English sources from reciprocal switchers', () => {
+    expect(requiresSourceLanguageSwitcher('docs/config-catalog.md')).toBe(false)
+    expect(requiresSourceLanguageSwitcher('docs/cordis-api/context.md')).toBe(false)
+    expect(requiresSourceLanguageSwitcher('docs/cordis-api/inherited.md')).toBe(false)
+    expect(requiresSourceLanguageSwitcher('docs/architecture.md')).toBe(true)
+    expect(requiresSourceLanguageSwitcher('packages/core/session/README.md')).toBe(true)
+  })
+})
+
 describe('translation pairing records', () => {
   const paths = translationPairPaths('docs/foo.md')
   const record = {
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
index 417e836578..87e31199a4 100644
--- a/scripts/translation-pairing.ts
+++ b/scripts/translation-pairing.ts
@@ -311,6 +311,27 @@ export function linksTo(tree: Nodes, target: string): boolean {
   return found
 }
 
+/** Generated English sources cannot carry a switcher without making their generator stale. */
+export function requiresSourceLanguageSwitcher(source: string): boolean {
+  return ![
+    'docs/agent-lifecycle.md',
+    'docs/capability-seams.md',
+    'docs/config-catalog.md',
+    'docs/cordis-api/context.md',
+    'docs/cordis-api/events.md',
+    'docs/cordis-api/fiber.md',
+    'docs/cordis-api/inherited.md',
+    'docs/cordis-api/registry.md',
+    'docs/cordis-api/service.md',
+    'docs/event-producer-consumer.md',
+    'docs/graph-atlas.md',
+    'docs/module-graph.md',
+    'docs/persistence-catalog.md',
+    'docs/tool-catalog.md',
+    'docs/tool-execution-pipeline.md',
+  ].includes(source)
+}
+
 /** Collect the ordered structural signature, skipping one switcher target. */
 export function translationStructureSignature(tree: Nodes, switcherTarget: string): TranslationStructureSignature {
   const sig: TranslationStructureSignature = { headings: [], code: [], tables: [], lists: [], links: [] }
diff --git a/scripts/verify-translation-pairing.ts b/scripts/verify-translation-pairing.ts
index be5c1816ae..95a2fe9747 100644
--- a/scripts/verify-translation-pairing.ts
+++ b/scripts/verify-translation-pairing.ts
@@ -24,6 +24,7 @@ import {
   parseTranslationPairingCliArgs,
   parseTranslationPairingManifest,
   partitionGeneratedRegions,
+  requiresSourceLanguageSwitcher,
   isTranslationScopeFile,
   TRANSLATION_SCOPE_GLOB_EXCLUDES,
   translationStructureDiff,
@@ -254,7 +255,7 @@ for (const source of [...pairAnchors].sort()) {
   if (!linksTo(zhTree, basename(source))) {
     errors.push(`${zh}: missing language switcher — no link to ${basename(source)}`)
   }
-  if (!linksTo(sourceTree, basename(zh))) {
+  if (requiresSourceLanguageSwitcher(source) && !linksTo(sourceTree, basename(zh))) {
     errors.push(`${source}: missing language switcher — no link back to ${basename(zh)}`)
   }
   for (const divergence of translationStructureDiff(
diff --git a/website/docs.ts b/website/docs.ts
index 3a31bf4baf..1e97d88e24 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -307,12 +307,9 @@ const subsystemsReference = pairedPages(([
   ...(file === 'README.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
 })))
 
-const reference = mirroredPages([
-  ...([
+const reference = [
+  ...mirroredPages(([
     ['docs/architecture.md', 'reference/index.md', '架构', 'Architecture', 0],
-    ['docs/capability-seams.md', 'reference/capability-seams.md', '能力服务', 'Capability services', 2],
-    ['docs/agent-lifecycle.md', 'reference/agent-lifecycle.md', 'Agent 生命周期', 'Agent lifecycle', 3],
-    ['docs/tool-execution-pipeline.md', 'reference/tool-execution-pipeline.md', 'Tool 执行', 'Tool execution', 4],
   ] as const).map(([source, route, rootLabel, enLabel, order]): MirroredPage => ({
     source,
     route,
@@ -321,27 +318,47 @@ const reference = mirroredPages([
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '概念', en: 'Concepts' },
     order,
-  })),
-  ...([
+  }))),
+  ...pairedPages(([
+    ['docs/capability-seams.md', 'reference/capability-seams.md', '能力服务', 'Capability services', 2],
+    ['docs/agent-lifecycle.md', 'reference/agent-lifecycle.md', 'Agent 生命周期', 'Agent lifecycle', 3],
+    ['docs/tool-execution-pipeline.md', 'reference/tool-execution-pipeline.md', 'Tool 执行', 'Tool execution', 4],
+  ] as const).map(([source, route, rootLabel, enLabel, order]): PairedPage => ({
+    source,
+    route,
+    label: { root: rootLabel, en: enLabel },
+    sidebar: { root: 'zh-reference', en: 'en-reference' },
+    section: { root: '概念', en: 'Concepts' },
+    order,
+  }))),
+  ...pairedPages(([
     ['docs/config-catalog.md', 'reference/config-catalog.md', '插件配置', 'Plugin configuration'],
     ['docs/tool-catalog.md', 'reference/tool-catalog.md', 'Tool Schema', 'Tool schemas'],
     ['docs/persistence-catalog.md', 'reference/persistence-catalog.md', '持久化事件', 'Persistence events', 'deep'],
-  ] as const).map(([source, route, rootLabel, enLabel, outline], order): MirroredPage => ({
+  ] as const).map(([source, route, rootLabel, enLabel, outline], order): PairedPage => ({
     source,
     route,
-    contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '生成参考', en: 'Generated reference' },
     order,
     ...(outline === undefined ? {} : { outline }),
-  })),
-  ...([
+  }))),
+  ...pairedPages(([
     ['context.md', 'Context', 'Context'],
     ['events.md', 'Events', 'Events'],
     ['fiber.md', 'Fiber', 'Fiber'],
     ['registry.md', 'Plugin Registry', 'Plugin Registry'],
     ['service.md', 'Service', 'Service'],
+  ] as const).map(([file, rootLabel, enLabel], order): PairedPage => ({
+    source: `docs/cordis-api/${file}`,
+    route: `reference/cordis-api/${file}`,
+    label: { root: rootLabel, en: enLabel },
+    sidebar: { root: 'zh-reference', en: 'en-reference' },
+    section: { root: 'Cordis API', en: 'Cordis Core API' },
+    order,
+  }))),
+  ...mirroredPages(([
     ['inherited.md', '继承接口面', 'Inherited surface'],
   ] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
     source: `docs/cordis-api/${file}`,
@@ -350,9 +367,9 @@ const reference = mirroredPages([
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: 'Cordis API', en: 'Cordis Core API' },
-    order,
-  })),
-  ...([
+    order: order + 5,
+  }))),
+  ...mirroredPages(([
     ['goal.md', '目标', 'Goals', 14],
     ['pty.md', 'PTY 会话', 'PTY sessions', 26],
     ['commands.md', '命令', 'Human commands', 38],
@@ -364,8 +381,8 @@ const reference = mirroredPages([
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '子系统', en: 'Subsystems' },
     order,
-  })),
-  ...([
+  }))),
+  ...mirroredPages(([
     ['adding-a-package.md', '新增 Package', 'Adding a package'],
     ['adding-a-tool.md', '新增 Tool', 'Adding a tool'],
     ['adding-an-llm-adapter.md', '新增 LLM Adapter', 'Adding an LLM adapter'],
@@ -378,8 +395,8 @@ const reference = mirroredPages([
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '开发手册', en: 'Cookbook' },
     order,
-  })),
-])
+  }))),
+]
 
 /** Every canonical page published by the documentation website. */
 export const docsPages: DocsPage[] = [

From 90a876cbad9b54cfad30c1b2153291bb44a5e7f9 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 11:21:20 +0800
Subject: [PATCH 430/516] test: refresh translation prompt snapshot

---
 .../request-response.expected.json                 | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 137315cf39..57fa7ebc3f 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 契约 | | | 如：`pairing contract` →`配对契约` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",
@@ -12,7 +12,7 @@
       },
       {
         "role": "assistant",
-        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
+        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）约定](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均为可组合的 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
       },
       {
         "role": "user",
@@ -20,15 +20,15 @@
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通包只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host 包、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` 包及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` 包 extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新包只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client 插件的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client 包，也不维护 Host/Client 包过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client 插件在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 契约产物生成构建 Agent Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约产物生成 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Agent Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Agent Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务服务在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验包入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约产物生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；包的公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
-        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
+        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\nGenerated English references and graphs participate in pairing when a reviewed Chinese counterpart is available. Their generators remain the English source of truth and their freshness gates run before pairing; regeneration that changes English leaves the pair out of sync until the reviewed Chinese counterpart is updated and re-recorded. Generated English sources omit the language switcher that ordinary authored sources carry, because adding it would make the generator stale; their Chinese counterparts still link back to the English source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md) — generated without a reviewed Chinese counterpart, so both website locales project the English source.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对约定\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n有经评审中文对侧的生成英文参考文档和图文档遵循配对规则。生成器仍是英文真源，新鲜度门禁先于配对运行；重新生成导致英文变化后，配对会保持失去同步状态，直至经评审的中文对侧完成更新并重新记录。生成的英文源文件不含普通撰写文档所带的语言切换行，因为添加该行会使生成器报告陈旧；中文对侧仍链接回英文源。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md)：该生成文档没有经评审的中文对侧，因此网站的两个 locale 都投影英文源文件。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
       },
       {
         "role": "user",
@@ -40,11 +40,11 @@
       },
       {
         "role": "user",
-        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated docs (`cordis-catalog/`, `tool-catalog/`, `module-graph.md`) are excluded for now; the planned follow-up is to teach their generators to emit Chinese alongside English, at which point they leave the exclusion list.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
+        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
       },
       {
         "role": "user",

From a7af54a8d34247b9c4f5c6ec0b289be5e06b6cce Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 11:33:14 +0800
Subject: [PATCH 431/516] docs(i18n): standardize contract terminology

---
 .agents/notes/README.i18n.yaml                |  2 +-
 .agents/notes/README.zh.md                    | 14 +++----
 ...ev-invariants-over-deep-readonly.i18n.yaml |  2 +-
 ...11-dev-invariants-over-deep-readonly.zh.md |  2 +-
 .../2026-06-13-capability-seams.i18n.yaml     |  2 +-
 .../2026-06-13-capability-seams.zh.md         |  4 +-
 .../2026-06-13-twin-llm-adapters.i18n.yaml    |  2 +-
 .../2026-06-13-twin-llm-adapters.zh.md        |  4 +-
 .../2026-06-14-session-persistence.i18n.yaml  |  2 +-
 .../2026-06-14-session-persistence.zh.md      |  2 +-
 ...06-17-filesystem-capability-seam.i18n.yaml |  2 +-
 ...026-06-17-filesystem-capability-seam.zh.md | 16 ++++----
 ...nt-lifecycle-and-ownership-seams.i18n.yaml |  2 +-
 ...-agent-lifecycle-and-ownership-seams.zh.md |  2 +-
 .../2026-06-18-session-surface.i18n.yaml      |  2 +-
 .../2026-06-18-session-surface.zh.md          |  2 +-
 ...ed-persistence-write-coordinator.i18n.yaml |  2 +-
 ...shared-persistence-write-coordinator.zh.md |  2 +-
 ...eneric-long-running-tool-runtime.i18n.yaml |  2 +-
 ...20-generic-long-running-tool-runtime.zh.md | 14 +++----
 ...-21-bounded-llm-request-recovery.i18n.yaml |  2 +-
 ...6-06-21-bounded-llm-request-recovery.zh.md |  6 +--
 ...andatory-app-attribution-headers.i18n.yaml |  2 +-
 ...21-mandatory-app-attribution-headers.zh.md | 14 +++----
 .../2026-06-24-web-capability-seam.i18n.yaml  |  2 +-
 .../2026-06-24-web-capability-seam.zh.md      | 12 +++---
 ...06-26-file-context-as-event-gate.i18n.yaml |  2 +-
 ...026-06-26-file-context-as-event-gate.zh.md | 12 +++---
 ...6-07-02-tool-render-intent-union.i18n.yaml |  2 +-
 .../2026-07-02-tool-render-intent-union.zh.md |  4 +-
 ...bles-and-tool-guidance-ownership.i18n.yaml |  2 +-
 ...ariables-and-tool-guidance-ownership.zh.md |  2 +-
 ...05-windows-jsonl-durable-publish.i18n.yaml |  2 +-
 ...-07-05-windows-jsonl-durable-publish.zh.md |  8 ++--
 ...6-07-06-timeout-deadline-library.i18n.yaml |  2 +-
 .../2026-07-06-timeout-deadline-library.zh.md |  6 +--
 ...06-tool-result-retention-library.i18n.yaml |  2 +-
 ...-07-06-tool-result-retention-library.zh.md |  4 +-
 ...6-07-07-tool-call-timeout-policy.i18n.yaml |  2 +-
 .../2026-07-07-tool-call-timeout-policy.zh.md |  8 ++--
 .../2026-07-08-agent-scope-contexts.i18n.yaml |  2 +-
 .../2026-07-08-agent-scope-contexts.zh.md     |  8 ++--
 ...26-07-08-tool-output-spill-files.i18n.yaml |  2 +-
 .../2026-07-08-tool-output-spill-files.zh.md  |  4 +-
 ...07-12-agent-scope-runtime-design.i18n.yaml |  2 +-
 ...026-07-12-agent-scope-runtime-design.zh.md | 40 +++++++++----------
 .../2026-07-12-scoped-layers-store.i18n.yaml  |  2 +-
 .../2026-07-12-scoped-layers-store.zh.md      | 12 +++---
 ...2026-07-15-agent-initiator-scope.i18n.yaml |  2 +-
 .../2026-07-15-agent-initiator-scope.zh.md    | 10 ++---
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |  2 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |  8 ++--
 ...07-16-explicit-turn-cancellation.i18n.yaml |  2 +-
 ...026-07-16-explicit-turn-cancellation.zh.md |  2 +-
 ...19-cooperative-tool-cancellation.i18n.yaml |  2 +-
 ...-07-19-cooperative-tool-cancellation.zh.md |  6 +--
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |  2 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md | 18 ++++-----
 ...7-19-gui-web-client-architecture.i18n.yaml |  2 +-
 ...26-07-19-gui-web-client-architecture.zh.md | 10 ++---
 ...kage-invariant-runtime-contracts.i18n.yaml |  2 +-
 ...-package-invariant-runtime-contracts.zh.md |  8 ++--
 ...-package-owned-invariant-service.i18n.yaml |  2 +-
 ...7-19-package-owned-invariant-service.zh.md | 10 ++---
 ...-19-zstandard-jsonl-session-logs.i18n.yaml |  2 +-
 ...6-07-19-zstandard-jsonl-session-logs.zh.md |  2 +-
 ...0-canonical-tool-output-contract.i18n.yaml |  2 +-
 ...07-20-canonical-tool-output-contract.zh.md |  8 ++--
 ...20-unified-json-value-schema-dsl.i18n.yaml |  2 +-
 ...-07-20-unified-json-value-schema-dsl.zh.md |  4 +-
 ...2-slot-type-chain-implementation.i18n.yaml |  2 +-
 ...07-22-slot-type-chain-implementation.zh.md |  4 +-
 ...send-and-coalesced-user-messages.i18n.yaml |  2 +-
 ...ied-send-and-coalesced-user-messages.zh.md |  2 +-
 ...7-23-client-plugin-loading-model.i18n.yaml |  2 +-
 ...26-07-23-client-plugin-loading-model.zh.md |  2 +-
 ...xt-injection-from-turn-execution.i18n.yaml |  2 +-
 ...ontext-injection-from-turn-execution.zh.md |  2 +-
 ...-24-single-harness-home-resolver.i18n.yaml |  2 +-
 ...6-07-24-single-harness-home-resolver.zh.md |  2 +-
 ...ession-scope-and-provide-channel.i18n.yaml |  2 +-
 ...nt-session-scope-and-provide-channel.zh.md |  6 +--
 ...eb-command-surfaces-and-assembly.i18n.yaml |  2 +-
 ...25-web-command-surfaces-and-assembly.zh.md |  2 +-
 ...input-machine-and-slash-pipeline.i18n.yaml |  2 +-
 ...web-input-machine-and-slash-pipeline.zh.md | 10 ++---
 ...-26-packed-chunk-rows-by-default.i18n.yaml |  2 +-
 ...6-07-26-packed-chunk-rows-by-default.zh.md |  6 +--
 .../2026-07-26-task-registry-seam.i18n.yaml   |  2 +-
 .../2026-07-26-task-registry-seam.zh.md       | 12 +++---
 ...ompiler-independent-typert-model.i18n.yaml |  2 +-
 ...27-compiler-independent-typert-model.zh.md |  4 +-
 ...07-27-dispose-ladder-to-consumer.i18n.yaml |  2 +-
 ...026-07-27-dispose-ladder-to-consumer.zh.md |  2 +-
 ...directory-picker-capability-seam.i18n.yaml |  2 +-
 ...-28-directory-picker-capability-seam.zh.md |  8 ++--
 ...xperimental-plugin-package-group.i18n.yaml |  2 +-
 ...28-experimental-plugin-package-group.zh.md |  6 +--
 ...ntified-immutable-message-values.i18n.yaml |  2 +-
 ...-identified-immutable-message-values.zh.md |  2 +-
 ...rtable-execution-world-consumers.i18n.yaml |  2 +-
 ...8-portable-execution-world-consumers.zh.md |  8 ++--
 .../2026-07-28-user-settings-seam.i18n.yaml   |  2 +-
 .../2026-07-28-user-settings-seam.zh.md       |  4 +-
 ...-token-usage-and-request-context.i18n.yaml |  2 +-
 ...cted-token-usage-and-request-context.zh.md |  2 +-
 ...est-level-llm-config-credentials.i18n.yaml |  2 +-
 ...request-level-llm-config-credentials.zh.md |  2 +-
 ...-manager-native-repository-cache.i18n.yaml |  2 +-
 ...kage-manager-native-repository-cache.zh.md |  2 +-
 ...30-settings-write-path-integrity.i18n.yaml |  2 +-
 ...-07-30-settings-write-path-integrity.zh.md |  6 +--
 ...-static-repository-plugin-format.i18n.yaml |  2 +-
 ...7-30-static-repository-plugin-format.zh.md |  6 +--
 ...claimed-pre-step-inbox-lifecycle.i18n.yaml |  2 +-
 ...-31-claimed-pre-step-inbox-lifecycle.zh.md |  2 +-
 ...runtime-portable-identifier-seam.i18n.yaml |  2 +-
 ...ode-runtime-portable-identifier-seam.zh.md | 12 +++---
 ...26-08-01-packaged-ripgrep-search.i18n.yaml |  2 +-
 .../2026-08-01-packaged-ripgrep-search.zh.md  |  2 +-
 ...08-02-typert-remote-method-calls.i18n.yaml |  2 +-
 ...026-08-02-typert-remote-method-calls.zh.md | 28 ++++++-------
 ...-pi-ai-declared-provider-catalog.i18n.yaml |  2 +-
 ...8-03-pi-ai-declared-provider-catalog.zh.md |  2 +-
 ...08-04-websocket-downlink-carrier.i18n.yaml |  2 +-
 ...026-08-04-websocket-downlink-carrier.zh.md |  2 +-
 ...e-session-jsonl-restore-pipeline.i18n.yaml |  2 +-
 ...large-session-jsonl-restore-pipeline.zh.md |  4 +-
 .../2026-08-05-session-preparation.i18n.yaml  |  2 +-
 .../2026-08-05-session-preparation.zh.md      |  2 +-
 ...08-05-slot-declaration-injection.i18n.yaml |  2 +-
 ...026-08-05-slot-declaration-injection.zh.md |  2 +-
 ...8-06-agent-event-payload-objects.i18n.yaml |  2 +-
 ...26-08-06-agent-event-payload-objects.zh.md |  4 +-
 ...ubagent-list-identity-projection.i18n.yaml |  2 +-
 ...06-subagent-list-identity-projection.zh.md | 28 ++++++-------
 ...arkdown-incremental-ast-renderer.i18n.yaml |  2 +-
 ...eb-markdown-incremental-ast-renderer.zh.md |  4 +-
 ...ssion-persistence-write-batching.i18n.yaml |  2 +-
 ...d-session-persistence-write-batching.zh.md |  6 +--
 ...ient-tool-presentation-ownership.i18n.yaml |  2 +-
 ...8-client-tool-presentation-ownership.zh.md |  8 ++--
 ...s-atomic-write-dacl-preservation.i18n.yaml |  2 +-
 ...ndows-atomic-write-dacl-preservation.zh.md |  4 +-
 ...-21-semantic-session-checkpoints.i18n.yaml |  2 +-
 ...6-07-21-semantic-session-checkpoints.zh.md |  2 +-
 .../2026-07-27-glob-sampling.i18n.yaml        |  2 +-
 .../bug-fix/2026-07-27-glob-sampling.zh.md    |  8 ++--
 ...table-snapshot-refresh-volatiles.i18n.yaml |  2 +-
 ...27-stable-snapshot-refresh-volatiles.zh.md |  2 +-
 ...ad-pre-identity-session-messages.i18n.yaml |  2 +-
 ...8-load-pre-identity-session-messages.zh.md |  6 +--
 ...d-scrollbars-and-reserved-gutter.i18n.yaml |  2 +-
 ...hemed-scrollbars-and-reserved-gutter.zh.md |  8 ++--
 ...-07-28-web-agent-runtime-context.i18n.yaml |  2 +-
 ...2026-07-28-web-agent-runtime-context.zh.md |  4 +-
 ...2026-07-28-web-gui-feedback-loop.i18n.yaml |  2 +-
 .../2026-07-28-web-gui-feedback-loop.zh.md    |  8 ++--
 ...9-human-transcript-append-origin.i18n.yaml |  2 +-
 ...07-29-human-transcript-append-origin.zh.md |  4 +-
 ...29-web-details-session-lifecycle.i18n.yaml |  2 +-
 ...-07-29-web-details-session-lifecycle.zh.md |  4 +-
 ...-30-composer-context-stack-order.i18n.yaml |  2 +-
 ...6-07-30-composer-context-stack-order.zh.md |  4 +-
 ...ranscript-log-ordered-projection.i18n.yaml |  2 +-
 ...eb-transcript-log-ordered-projection.zh.md |  8 ++--
 ...1-english-compaction-checkpoints.i18n.yaml |  2 +-
 ...07-31-english-compaction-checkpoints.zh.md |  2 +-
 ...-fail-loud-releases-the-terminal.i18n.yaml |  2 +-
 ...7-31-fail-loud-releases-the-terminal.zh.md |  2 +-
 ...-fork-anchor-floors-to-event-seq.i18n.yaml |  2 +-
 ...7-31-fork-anchor-floors-to-event-seq.zh.md |  4 +-
 ...resume-selector-batch-projection.i18n.yaml |  2 +-
 ...-31-resume-selector-batch-projection.zh.md |  4 +-
 ...6-07-31-web-stop-preserves-queue.i18n.yaml |  2 +-
 .../2026-07-31-web-stop-preserves-queue.zh.md |  2 +-
 ...-ask-user-delegated-caller-guard.i18n.yaml |  2 +-
 ...8-01-ask-user-delegated-caller-guard.zh.md |  2 +-
 ...-08-02-goal-round-wrapup-message.i18n.yaml |  2 +-
 ...2026-08-02-goal-round-wrapup-message.zh.md |  4 +-
 ...odo-first-composer-context-order.i18n.yaml |  2 +-
 ...02-todo-first-composer-context-order.zh.md |  2 +-
 ...3-cli-signal-shutdown-escalation.i18n.yaml |  2 +-
 ...08-03-cli-signal-shutdown-escalation.zh.md |  2 +-
 ...3-hmr-initial-scan-boot-deadlock.i18n.yaml |  2 +-
 ...08-03-hmr-initial-scan-boot-deadlock.zh.md |  2 +-
 ...-04-load-pre-react-loop-sessions.i18n.yaml |  2 +-
 ...6-08-04-load-pre-react-loop-sessions.zh.md |  4 +-
 ...rding-step-owned-takeover-chrome.i18n.yaml |  2 +-
 ...nboarding-step-owned-takeover-chrome.zh.md |  8 ++--
 ...06-provider-credential-lifecycle.i18n.yaml |  2 +-
 ...-08-06-provider-credential-lifecycle.zh.md |  2 +-
 ...-attribution-observed-top-ledger.i18n.yaml |  2 +-
 ...roll-attribution-observed-top-ledger.zh.md |  8 ++--
 ...e-unpriced-replace-compatibility.i18n.yaml |  2 +-
 ...rface-unpriced-replace-compatibility.zh.md |  6 +--
 ...07-cancel-convergence-wake-latch.i18n.yaml |  2 +-
 ...-08-07-cancel-convergence-wake-latch.zh.md |  4 +-
 .../2026-06-14-acp-multi-session.i18n.yaml    |  2 +-
 .../2026-06-14-acp-multi-session.zh.md        |  4 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |  2 +-
 .../feature/2026-06-15-code-mode.zh.md        |  6 +--
 ...26-06-17-filesystem-tool-schemas.i18n.yaml |  2 +-
 .../2026-06-17-filesystem-tool-schemas.zh.md  |  8 ++--
 ...06-18-compaction-capability-seam.i18n.yaml |  2 +-
 ...026-06-18-compaction-capability-seam.zh.md | 16 ++++----
 .../2026-06-22-acp-subagent-backend.i18n.yaml |  2 +-
 .../2026-06-22-acp-subagent-backend.zh.md     |  2 +-
 .../2026-06-24-workspace-context.i18n.yaml    |  2 +-
 .../2026-06-24-workspace-context.zh.md        |  2 +-
 .../2026-06-29-todo-write-tool.i18n.yaml      |  2 +-
 .../feature/2026-06-29-todo-write-tool.zh.md  |  2 +-
 .../2026-06-30-hook-protocol-lib.i18n.yaml    |  2 +-
 .../2026-06-30-hook-protocol-lib.zh.md        |  4 +-
 .../2026-06-30-interception-seams.i18n.yaml   |  2 +-
 .../2026-06-30-interception-seams.zh.md       |  6 +--
 ...026-06-30-session-store-fork-api.i18n.yaml |  2 +-
 .../2026-06-30-session-store-fork-api.zh.md   |  2 +-
 .../2026-07-05-dynamic-workflows.i18n.yaml    |  2 +-
 .../2026-07-05-dynamic-workflows.zh.md        |  6 +--
 .../feature/2026-07-05-skill-system.i18n.yaml |  2 +-
 .../feature/2026-07-05-skill-system.zh.md     |  6 +--
 .../2026-07-06-approval-seam.i18n.yaml        |  2 +-
 .../feature/2026-07-06-approval-seam.zh.md    | 10 ++---
 .../2026-07-06-explicit-tool-order.i18n.yaml  |  2 +-
 .../2026-07-06-explicit-tool-order.zh.md      |  4 +-
 .../feature/2026-07-06-sandbox.i18n.yaml      |  2 +-
 .../feature/2026-07-06-sandbox.zh.md          |  6 +--
 .../2026-07-07-mcp-client-plugin.i18n.yaml    |  2 +-
 .../2026-07-07-mcp-client-plugin.zh.md        |  6 +--
 ...-07-08-background-subagent-tasks.i18n.yaml |  2 +-
 ...2026-07-08-background-subagent-tasks.zh.md |  4 +-
 ...-self-referential-cordis-toolset.i18n.yaml |  2 +-
 ...7-08-self-referential-cordis-toolset.zh.md |  8 ++--
 ...ession-identity-and-log-location.i18n.yaml |  2 +-
 ...nt-session-identity-and-log-location.zh.md |  4 +-
 ...-10-parallel-tool-call-execution.i18n.yaml |  2 +-
 ...6-07-10-parallel-tool-call-execution.zh.md |  8 ++--
 ...10-sqlite-session-query-provider.i18n.yaml |  2 +-
 ...-07-10-sqlite-session-query-provider.zh.md |  6 +--
 ...nt-persona-tool-filter-and-depth.i18n.yaml |  2 +-
 ...bagent-persona-tool-filter-and-depth.zh.md |  2 +-
 ...2026-07-13-session-query-tracing.i18n.yaml |  2 +-
 .../2026-07-13-session-query-tracing.zh.md    |  4 +-
 ...26-07-14-cross-family-fs-sandbox.i18n.yaml |  2 +-
 .../2026-07-14-cross-family-fs-sandbox.zh.md  |  2 +-
 ...16-durable-per-step-time-context.i18n.yaml |  2 +-
 ...-07-16-durable-per-step-time-context.zh.md |  2 +-
 .../2026-07-16-harness-level-loop.i18n.yaml   |  2 +-
 .../2026-07-16-harness-level-loop.zh.md       |  6 +--
 ...26-07-16-persistent-pty-sessions.i18n.yaml |  2 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  | 18 ++++-----
 ...-fresh-agent-ralph-workflow-tool.i18n.yaml |  2 +-
 ...7-19-fresh-agent-ralph-workflow-tool.zh.md |  2 +-
 .../2026-07-19-human-goal-command.i18n.yaml   |  2 +-
 .../2026-07-19-human-goal-command.zh.md       | 12 +++---
 ...26-07-19-model-facing-goal-tools.i18n.yaml |  2 +-
 .../2026-07-19-model-facing-goal-tools.zh.md  |  2 +-
 ...7-19-plugin-command-registration.i18n.yaml |  2 +-
 ...26-07-19-plugin-command-registration.zh.md |  6 +--
 ...-20-code-mode-typed-tool-returns.i18n.yaml |  2 +-
 ...6-07-20-code-mode-typed-tool-returns.zh.md | 12 +++---
 ...26-07-20-dsh-cli-personal-config.i18n.yaml |  2 +-
 .../2026-07-20-dsh-cli-personal-config.zh.md  |  4 +-
 ...continuable-background-subagents.i18n.yaml |  2 +-
 ...-21-continuable-background-subagents.zh.md | 14 +++----
 ...6-07-21-cross-session-references.i18n.yaml |  2 +-
 .../2026-07-21-cross-session-references.zh.md |  4 +-
 ...-07-21-log-backed-session-titles.i18n.yaml |  2 +-
 ...2026-07-21-log-backed-session-titles.zh.md |  2 +-
 ...subagent-catalog-and-list-agents.i18n.yaml |  2 +-
 ...ble-subagent-catalog-and-list-agents.zh.md | 18 ++++-----
 .../2026-07-22-web-bind-address.i18n.yaml     |  2 +-
 .../feature/2026-07-22-web-bind-address.zh.md |  4 +-
 ...3-session-telemetry-otel-revival.i18n.yaml |  2 +-
 ...07-23-session-telemetry-otel-revival.zh.md |  4 +-
 ...026-07-23-web-assistant-markdown.i18n.yaml |  2 +-
 .../2026-07-23-web-assistant-markdown.zh.md   |  4 +-
 ...7-23-web-permission-and-approval.i18n.yaml |  2 +-
 ...26-07-23-web-permission-and-approval.zh.md |  8 ++--
 .../2026-07-23-web-todo-display.i18n.yaml     |  2 +-
 .../feature/2026-07-23-web-todo-display.zh.md |  2 +-
 ...model-facing-session-query-tools.i18n.yaml |  2 +-
 ...-24-model-facing-session-query-tools.zh.md |  2 +-
 ...26-07-24-provider-retry-policies.i18n.yaml |  2 +-
 .../2026-07-24-provider-retry-policies.zh.md  |  4 +-
 ...n-list-browsing-and-manual-order.i18n.yaml |  2 +-
 ...ssion-list-browsing-and-manual-order.zh.md |  6 +--
 ...-07-25-workspace-ui-product-flow.i18n.yaml |  2 +-
 ...2026-07-25-workspace-ui-product-flow.zh.md |  2 +-
 ...7-26-code-dispatch-ui-foundation.i18n.yaml |  2 +-
 ...26-07-26-code-dispatch-ui-foundation.zh.md |  6 +--
 ...code-mode-live-parallel-dispatch.i18n.yaml |  2 +-
 ...-26-code-mode-live-parallel-dispatch.zh.md | 12 +++---
 ...-07-26-todo-parallel-in-progress.i18n.yaml |  2 +-
 ...2026-07-26-todo-parallel-in-progress.zh.md |  2 +-
 ...ative-workspace-directory-picker.i18n.yaml |  2 +-
 ...27-native-workspace-directory-picker.zh.md |  2 +-
 ...-07-27-skill-catalog-hot-refresh.i18n.yaml |  2 +-
 ...2026-07-27-skill-catalog-hot-refresh.zh.md |  4 +-
 ...-27-trajectory-inspection-ledger.i18n.yaml |  2 +-
 ...6-07-27-trajectory-inspection-ledger.zh.md |  2 +-
 ...ipt-sdk-and-sdk-subagent-backend.i18n.yaml |  2 +-
 ...escript-sdk-and-sdk-subagent-backend.zh.md |  2 +-
 ...6-07-27-web-session-fork-actions.i18n.yaml |  2 +-
 .../2026-07-27-web-session-fork-actions.zh.md |  2 +-
 .../2026-07-27-web-session-search.i18n.yaml   |  2 +-
 .../2026-07-27-web-session-search.zh.md       | 10 ++---
 ...07-27-web-subagent-conversations.i18n.yaml |  2 +-
 ...026-07-27-web-subagent-conversations.zh.md | 18 ++++-----
 ...ntinuable-subagent-conversations.i18n.yaml |  2 +-
 ...8-continuable-subagent-conversations.zh.md |  8 ++--
 ...2026-07-28-sdk-max-output-tokens.i18n.yaml |  2 +-
 .../2026-07-28-sdk-max-output-tokens.zh.md    |  2 +-
 ...26-07-28-skill-invocation-policy.i18n.yaml |  2 +-
 .../2026-07-28-skill-invocation-policy.zh.md  |  8 ++--
 .../2026-07-28-web-terminal-card.i18n.yaml    |  2 +-
 .../2026-07-28-web-terminal-card.zh.md        |  4 +-
 ...29-ask-question-web-presentation.i18n.yaml |  2 +-
 ...-07-29-ask-question-web-presentation.zh.md |  2 +-
 ...irectory-picker-adaptive-default.i18n.yaml |  2 +-
 ...29-directory-picker-adaptive-default.zh.md |  2 +-
 ...rsistent-bash-str-replace-editor.i18n.yaml |  2 +-
 ...9-persistent-bash-str-replace-editor.zh.md |  2 +-
 ...0-config-only-repository-plugins.i18n.yaml |  2 +-
 ...07-30-config-only-repository-plugins.zh.md |  4 +-
 ...continuable-subagent-report-tool.i18n.yaml |  2 +-
 ...-30-continuable-subagent-report-tool.zh.md |  4 +-
 ...0-current-sandbox-policy-context.i18n.yaml |  2 +-
 ...07-30-current-sandbox-policy-context.zh.md |  2 +-
 ...seek-onboarding-credential-setup.i18n.yaml |  2 +-
 ...deepseek-onboarding-credential-setup.zh.md |  2 +-
 ...6-07-30-queued-manual-compaction.i18n.yaml |  2 +-
 .../2026-07-30-queued-manual-compaction.zh.md |  2 +-
 .../2026-07-30-search-render-card.i18n.yaml   |  2 +-
 .../2026-07-30-search-render-card.zh.md       |  8 ++--
 .../2026-07-30-web-diff-card.i18n.yaml        |  2 +-
 .../feature/2026-07-30-web-diff-card.zh.md    |  4 +-
 ...026-07-30-web-queue-steer-action.i18n.yaml |  2 +-
 .../2026-07-30-web-queue-steer-action.zh.md   |  8 ++--
 ...026-07-30-web-read-card-frontend.i18n.yaml |  2 +-
 .../2026-07-30-web-read-card-frontend.zh.md   |  2 +-
 .../2026-07-30-web-read-card.i18n.yaml        |  2 +-
 .../feature/2026-07-30-web-read-card.zh.md    |  4 +-
 ...6-07-30-web-result-card-frontend.i18n.yaml |  2 +-
 .../2026-07-30-web-result-card-frontend.zh.md | 12 +++---
 .../2026-07-30-web-result-card.i18n.yaml      |  2 +-
 .../feature/2026-07-30-web-result-card.zh.md  |  4 +-
 .../2026-07-30-web-search-card.i18n.yaml      |  2 +-
 .../feature/2026-07-30-web-search-card.zh.md  | 12 +++---
 ...l-row-unified-expand-and-inspect.i18n.yaml |  2 +-
 ...-tool-row-unified-expand-and-inspect.zh.md |  2 +-
 ...7-31-code-mode-language-dispatch.i18n.yaml |  2 +-
 ...26-07-31-code-mode-language-dispatch.zh.md |  6 +--
 ...-31-gui-full-access-confirmation.i18n.yaml |  2 +-
 ...6-07-31-gui-full-access-confirmation.zh.md |  2 +-
 ...mission-default-for-new-sessions.i18n.yaml |  2 +-
 ...-permission-default-for-new-sessions.zh.md |  2 +-
 ...7-31-telemetry-anonymous-user-id.i18n.yaml |  2 +-
 ...26-07-31-telemetry-anonymous-user-id.zh.md |  4 +-
 ...-third-party-memory-mcp-examples.i18n.yaml |  2 +-
 ...7-31-third-party-memory-mcp-examples.zh.md |  4 +-
 .../2026-07-31-web-default-search.i18n.yaml   |  2 +-
 .../2026-07-31-web-default-search.zh.md       |  2 +-
 ...6-07-31-web-workspace-file-links.i18n.yaml |  2 +-
 .../2026-07-31-web-workspace-file-links.zh.md |  2 +-
 ...026-08-01-pwsh-tool-and-executor.i18n.yaml |  2 +-
 .../2026-08-01-pwsh-tool-and-executor.zh.md   |  8 ++--
 ...2026-08-02-pwsh-tool-bash-parity.i18n.yaml |  2 +-
 .../2026-08-02-pwsh-tool-bash-parity.zh.md    |  6 +--
 ...6-08-02-web-thinking-tail-scroll.i18n.yaml |  2 +-
 .../2026-08-02-web-thinking-tail-scroll.zh.md |  4 +-
 ...6-08-03-web-search-source-scroll.i18n.yaml |  2 +-
 .../2026-08-03-web-search-source-scroll.zh.md |  2 +-
 ...code-and-codex-subagent-backends.i18n.yaml |  2 +-
 ...ude-code-and-codex-subagent-backends.zh.md |  6 +--
 ...nter-revealed-sidebar-scrollbars.i18n.yaml |  2 +-
 ...-pointer-revealed-sidebar-scrollbars.zh.md |  2 +-
 .../2026-08-05-pwsh-ui-bash-parity.i18n.yaml  |  2 +-
 .../2026-08-05-pwsh-ui-bash-parity.zh.md      |  4 +-
 ...26-08-06-bundled-dsh-badge-skill.i18n.yaml |  2 +-
 .../2026-08-06-bundled-dsh-badge-skill.zh.md  |  2 +-
 ...6-continuable-subagent-interrupt.i18n.yaml |  2 +-
 ...08-06-continuable-subagent-interrupt.zh.md |  4 +-
 ...06-resolved-theme-color-metadata.i18n.yaml |  2 +-
 ...-08-06-resolved-theme-color-metadata.zh.md |  2 +-
 .../2026-08-06-web-install-manifest.i18n.yaml |  2 +-
 .../2026-08-06-web-install-manifest.zh.md     |  6 +--
 .../2026-08-06-web-skill-tool-row.i18n.yaml   |  2 +-
 .../2026-08-06-web-skill-tool-row.zh.md       |  8 ++--
 ...6-08-08-dsh-run-headless-command.i18n.yaml |  2 +-
 .../2026-08-08-dsh-run-headless-command.zh.md |  2 +-
 .../2026-06-17-ts-build-config.i18n.yaml      |  2 +-
 .../process/2026-06-17-ts-build-config.zh.md  |  4 +-
 ...-20-core-data-structures-catalog.i18n.yaml |  2 +-
 ...6-06-20-core-data-structures-catalog.zh.md |  4 +-
 ...-bilingual-docs-and-pairing-gate.i18n.yaml |  2 +-
 ...7-02-bilingual-docs-and-pairing-gate.zh.md |  2 +-
 ...2026-07-04-doc-tiers-and-budgets.i18n.yaml |  2 +-
 .../2026-07-04-doc-tiers-and-budgets.zh.md    |  4 +-
 ...-07-05-uniform-agent-note-format.i18n.yaml |  2 +-
 ...2026-07-05-uniform-agent-note-format.zh.md | 10 ++---
 ...-07-06-export-surface-jsdoc-gate.i18n.yaml |  2 +-
 ...2026-07-06-export-surface-jsdoc-gate.zh.md | 14 +++----
 .../2026-07-06-node-engine-floor.i18n.yaml    |  2 +-
 .../2026-07-06-node-engine-floor.zh.md        |  2 +-
 ...ackage-model-experience-contract.i18n.yaml |  2 +-
 ...12-package-model-experience-contract.zh.md | 12 +++---
 ...13-documentation-site-projection.i18n.yaml |  2 +-
 ...-07-13-documentation-site-projection.zh.md |  2 +-
 ...pt-program-backed-semantic-gates.i18n.yaml |  2 +-
 ...script-program-backed-semantic-gates.zh.md |  6 +--
 ...emove-generated-agent-note-index.i18n.yaml |  2 +-
 ...19-remove-generated-agent-note-index.zh.md |  2 +-
 ...nt-notes-for-non-trivial-changes.i18n.yaml |  2 +-
 ...-agent-notes-for-non-trivial-changes.zh.md | 12 +++---
 .../2026-07-20-gui-testing-system.i18n.yaml   |  2 +-
 .../2026-07-20-gui-testing-system.zh.md       |  2 +-
 ...rial-cross-platform-ci-reference.i18n.yaml |  2 +-
 ...1-serial-cross-platform-ci-reference.zh.md |  6 +--
 ...ence-based-larger-hosted-runners.i18n.yaml |  2 +-
 ...evidence-based-larger-hosted-runners.zh.md | 12 +++---
 ...-07-22-product-first-root-readme.i18n.yaml |  2 +-
 ...2026-07-22-product-first-root-readme.zh.md |  2 +-
 ...fig-solution-root-two-aggregates.i18n.yaml |  2 +-
 ...sconfig-solution-root-two-aggregates.zh.md |  6 +--
 ...sonal-staging-maintenance-skills.i18n.yaml |  2 +-
 ...-personal-staging-maintenance-skills.zh.md |  2 +-
 ...ortable-required-pull-request-ci.i18n.yaml |  2 +-
 ...23-portable-required-pull-request-ci.zh.md |  6 +--
 ...3-translation-prompt-v4-contract.i18n.yaml |  2 +-
 ...07-23-translation-prompt-v4-contract.zh.md | 12 +++---
 ...efed-minimal-translation-updates.i18n.yaml |  2 +-
 ...-briefed-minimal-translation-updates.zh.md | 10 ++---
 ...6-dependencies-over-hand-rolling.i18n.yaml |  2 +-
 ...07-26-dependencies-over-hand-rolling.zh.md |  4 +-
 ...-07-26-frozen-agent-note-archive.i18n.yaml |  2 +-
 ...2026-07-26-frozen-agent-note-archive.zh.md |  2 +-
 ...26-web-syntax-highlighting-shiki.i18n.yaml |  2 +-
 ...-07-26-web-syntax-highlighting-shiki.zh.md |  2 +-
 .../2026-07-29-oxlint-linter.i18n.yaml        |  2 +-
 .../process/2026-07-29-oxlint-linter.zh.md    |  6 +--
 ...-31-coverage-exempt-heavy-suites.i18n.yaml |  2 +-
 ...6-07-31-coverage-exempt-heavy-suites.zh.md |  6 +--
 ...staller-adopts-existing-checkout.i18n.yaml |  2 +-
 ...1-installer-adopts-existing-checkout.zh.md |  8 ++--
 ...package-anchored-subsystem-pages.i18n.yaml |  2 +-
 ...-03-package-anchored-subsystem-pages.zh.md |  4 +-
 ...6-in-repository-landlock-release.i18n.yaml |  2 +-
 ...08-06-in-repository-landlock-release.zh.md |  2 +-
 ...remotes-generated-contract-build.i18n.yaml |  2 +-
 ...api-remotes-generated-contract-build.zh.md | 14 +++----
 ...matic-translation-pairing-merges.i18n.yaml |  2 +-
 ...automatic-translation-pairing-merges.zh.md |  2 +-
 ...08-unified-github-label-taxonomy.i18n.yaml |  2 +-
 ...-08-08-unified-github-label-taxonomy.zh.md | 10 ++---
 ...-19-drop-mutable-session-summary.i18n.yaml |  2 +-
 ...6-06-19-drop-mutable-session-summary.zh.md |  6 +--
 ...-06-20-public-agent-stop-surface.i18n.yaml |  2 +-
 ...2026-06-20-public-agent-stop-surface.zh.md |  6 +--
 .../2026-06-26-fsspec-style-fs-seam.i18n.yaml |  2 +-
 .../2026-06-26-fsspec-style-fs-seam.zh.md     | 14 +++----
 ...4-tighten-hook-protocol-contract.i18n.yaml |  2 +-
 ...07-04-tighten-hook-protocol-contract.zh.md |  4 +-
 ...plify-session-log-representation.i18n.yaml |  2 +-
 ...-simplify-session-log-representation.zh.md |  2 +-
 .../2026-07-17-one-send-one-turn.i18n.yaml    |  2 +-
 .../2026-07-17-one-send-one-turn.zh.md        |  4 +-
 ...-20-remove-stdio-and-echo-agents.i18n.yaml |  2 +-
 ...6-07-20-remove-stdio-and-echo-agents.zh.md |  8 ++--
 ...nwrap-injected-content-envelopes.i18n.yaml |  2 +-
 ...20-unwrap-injected-content-envelopes.zh.md |  2 +-
 ...lan-specific-collaboration-state.i18n.yaml |  2 +-
 ...22-plan-specific-collaboration-state.zh.md |  4 +-
 ...-23-acp-automation-only-protocol.i18n.yaml |  2 +-
 ...6-07-23-acp-automation-only-protocol.zh.md |  6 +--
 ...collapse-persistence-flush-state.i18n.yaml |  2 +-
 ...-23-collapse-persistence-flush-state.zh.md |  6 +--
 ...nt-loop-observable-state-machine.i18n.yaml |  2 +-
 ...-agent-loop-observable-state-machine.zh.md |  4 +-
 ...6-merge-subagent-control-service.i18n.yaml |  2 +-
 ...07-26-merge-subagent-control-service.zh.md |  6 +--
 ...6-07-28-local-json-tree-renderer.i18n.yaml |  2 +-
 .../2026-07-28-local-json-tree-renderer.zh.md |  6 +--
 .../2026-07-30-private-agent-send.i18n.yaml   |  2 +-
 .../2026-07-30-private-agent-send.zh.md       |  4 +-
 ...y-neutral-sandbox-policy-context.i18n.yaml |  2 +-
 ...ility-neutral-sandbox-policy-context.zh.md |  2 +-
 ...-31-one-route-to-add-a-workspace.i18n.yaml |  2 +-
 ...6-07-31-one-route-to-add-a-workspace.zh.md |  6 +--
 .../2026-08-08-remove-cli-demo.i18n.yaml      |  2 +-
 .../2026-08-08-remove-cli-demo.zh.md          |  6 +--
 .../2026-06-19-acp-snapshot-tests.i18n.yaml   |  2 +-
 .../2026-06-19-acp-snapshot-tests.zh.md       |  4 +-
 ...-fork-child-replay-seed-boundary.i18n.yaml |  2 +-
 ...6-22-fork-child-replay-seed-boundary.zh.md |  2 +-
 ...-22-cross-platform-test-fixtures.i18n.yaml |  2 +-
 ...6-07-22-cross-platform-test-fixtures.zh.md |  6 +--
 ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml |  2 +-
 .../2026-07-24-web-gui-browser-e2e-lane.zh.md | 16 ++++----
 .../2026-06-16-typed-event-schemas.i18n.yaml  |  2 +-
 .../2026-06-16-typed-event-schemas.zh.md      |  4 +-
 ...sdk-project-editing-architecture.i18n.yaml |  2 +-
 ...-15-sdk-project-editing-architecture.zh.md |  6 +--
 ...on-through-tool-capability-seams.i18n.yaml |  2 +-
 ...lation-through-tool-capability-seams.zh.md | 10 ++---
 ...-domain-kv-storage-and-workspace.i18n.yaml |  2 +-
 ...7-24-domain-kv-storage-and-workspace.zh.md | 10 ++---
 ...-25-client-settings-locale-theme.i18n.yaml |  2 +-
 ...6-07-25-client-settings-locale-theme.zh.md |  4 +-
 ...ssion-projection-and-command-log.i18n.yaml |  2 +-
 ...7-session-projection-and-command-log.zh.md | 20 +++++-----
 ...root-and-derived-medium-recovery.i18n.yaml |  2 +-
 ...age-root-and-derived-medium-recovery.zh.md |  2 +-
 ...7-29-durable-last-activity-index.i18n.yaml |  2 +-
 ...26-07-29-durable-last-activity-index.zh.md |  2 +-
 ...8-semantic-composer-chain-phases.i18n.yaml |  2 +-
 ...08-08-semantic-composer-chain-phases.zh.md |  4 +-
 ...2026-07-06-recallable-compaction.i18n.yaml |  2 +-
 .../2026-07-06-recallable-compaction.zh.md    |  2 +-
 ...026-07-14-sdk-developer-projects.i18n.yaml |  2 +-
 .../2026-07-14-sdk-developer-projects.zh.md   |  2 +-
 ...07-17-sdk-follow-up-capabilities.i18n.yaml |  2 +-
 ...026-07-17-sdk-follow-up-capabilities.zh.md | 10 ++---
 .../feature/2026-08-04-task-surface.i18n.yaml |  2 +-
 .../feature/2026-08-04-task-surface.zh.md     | 18 ++++-----
 ...-06-11-architectural-conformance.i18n.yaml |  2 +-
 ...2026-06-11-architectural-conformance.zh.md |  2 +-
 ...3-human-review-skill-maintenance.i18n.yaml |  2 +-
 ...07-13-human-review-skill-maintenance.zh.md | 14 +++----
 ...t-first-npm-baseline-publication.i18n.yaml |  2 +-
 ...ifact-first-npm-baseline-publication.zh.md |  6 +--
 ...04-prune-dead-core-spine-surface.i18n.yaml |  2 +-
 ...-07-04-prune-dead-core-spine-surface.zh.md | 22 +++++-----
 ...ndstrip-for-windows-sandbox-rung.i18n.yaml |  2 +-
 ...e-landstrip-for-windows-sandbox-rung.zh.md |  2 +-
 ...ssembled-assistant-messages-only.i18n.yaml |  2 +-
 ...20-assembled-assistant-messages-only.zh.md |  2 +-
 ...-20-drop-durable-step-boundaries.i18n.yaml |  2 +-
 ...6-06-20-drop-durable-step-boundaries.zh.md |  2 +-
 ...ld-session-persistence-interface.i18n.yaml |  2 +-
 ...0-fold-session-persistence-interface.zh.md |  6 +--
 ...06-20-truncate-interrupted-turns.i18n.yaml |  2 +-
 ...026-06-20-truncate-interrupted-turns.zh.md |  4 +-
 ...apse-workflow-to-foreground-core.i18n.yaml |  2 +-
 ...collapse-workflow-to-foreground-core.zh.md |  4 +-
 ...ne-unused-skill-registry-surface.i18n.yaml |  2 +-
 ...-prune-unused-skill-registry-surface.zh.md |  6 +--
 ...ency-swaps-rejected-by-nih-audit.i18n.yaml |  2 +-
 ...pendency-swaps-rejected-by-nih-audit.zh.md |  6 +--
 README.i18n.yaml                              |  2 +-
 README.zh.md                                  |  2 +-
 apps/cli/README.i18n.yaml                     |  2 +-
 apps/cli/README.zh.md                         |  2 +-
 apps/cli/reference/README.i18n.yaml           |  2 +-
 apps/cli/reference/README.zh.md               |  4 +-
 docs/api-gateway.i18n.yaml                    |  2 +-
 docs/api-gateway.zh.md                        | 12 +++---
 docs/architecture.i18n.yaml                   |  2 +-
 docs/architecture.zh.md                       |  4 +-
 docs/cookbook/adding-a-package.i18n.yaml      |  2 +-
 docs/cookbook/adding-a-package.zh.md          |  4 +-
 docs/cookbook/adding-a-tool.i18n.yaml         |  2 +-
 docs/cookbook/adding-a-tool.zh.md             |  8 ++--
 docs/cookbook/adding-an-llm-adapter.i18n.yaml |  2 +-
 docs/cookbook/adding-an-llm-adapter.zh.md     |  2 +-
 docs/cookbook/extension-cookbook.i18n.yaml    |  2 +-
 docs/cookbook/extension-cookbook.zh.md        |  2 +-
 .../maintaining-dsh-code-review.i18n.yaml     |  2 +-
 .../maintaining-dsh-code-review.zh.md         |  2 +-
 docs/cordis-primer.i18n.yaml                  |  2 +-
 docs/cordis-primer.zh.md                      |  2 +-
 docs/cordis-tutorial/04-events.i18n.yaml      |  2 +-
 docs/cordis-tutorial/04-events.zh.md          |  2 +-
 docs/defensive-patterns.i18n.yaml             |  2 +-
 docs/defensive-patterns.zh.md                 |  2 +-
 docs/development.i18n.yaml                    |  2 +-
 docs/development.zh.md                        | 14 +++----
 docs/glossary.i18n.yaml                       |  2 +-
 docs/glossary.zh.md                           |  2 +-
 docs/i18n/README.i18n.yaml                    |  2 +-
 docs/i18n/README.zh.md                        | 10 ++---
 docs/i18n/terminology.md                      |  4 +-
 ...0003-web-agent-gui-feedback-loop.i18n.yaml |  2 +-
 .../0003-web-agent-gui-feedback-loop.zh.md    |  2 +-
 ...ice-misclassified-child-failures.i18n.yaml |  2 +-
 ...-notice-misclassified-child-failures.zh.md |  6 +--
 docs/subsystems/README.i18n.yaml              |  2 +-
 docs/subsystems/README.zh.md                  | 16 ++++----
 docs/subsystems/bash.i18n.yaml                |  2 +-
 docs/subsystems/bash.zh.md                    |  2 +-
 docs/subsystems/code-runtime.i18n.yaml        |  2 +-
 docs/subsystems/code-runtime.zh.md            |  4 +-
 docs/subsystems/compaction.i18n.yaml          |  2 +-
 docs/subsystems/compaction.zh.md              |  2 +-
 docs/subsystems/core.i18n.yaml                |  2 +-
 docs/subsystems/core.zh.md                    | 10 ++---
 docs/subsystems/goal.i18n.yaml                |  2 +-
 docs/subsystems/goal.zh.md                    |  2 +-
 docs/subsystems/http-server.i18n.yaml         |  2 +-
 docs/subsystems/http-server.zh.md             |  2 +-
 docs/subsystems/invariants.i18n.yaml          |  2 +-
 docs/subsystems/invariants.zh.md              |  4 +-
 docs/subsystems/llm-streaming.i18n.yaml       |  2 +-
 docs/subsystems/llm-streaming.zh.md           | 10 ++---
 docs/subsystems/persistence.i18n.yaml         |  2 +-
 docs/subsystems/persistence.zh.md             |  2 +-
 docs/subsystems/sandbox.i18n.yaml             |  2 +-
 docs/subsystems/sandbox.zh.md                 |  2 +-
 docs/subsystems/session-projection.i18n.yaml  |  2 +-
 docs/subsystems/session-projection.zh.md      |  2 +-
 docs/subsystems/session-reference.i18n.yaml   |  2 +-
 docs/subsystems/session-reference.zh.md       |  2 +-
 docs/subsystems/session.i18n.yaml             |  2 +-
 docs/subsystems/session.zh.md                 |  8 ++--
 docs/subsystems/skills.i18n.yaml              |  2 +-
 docs/subsystems/skills.zh.md                  |  2 +-
 docs/subsystems/storage.i18n.yaml             |  2 +-
 docs/subsystems/storage.zh.md                 |  2 +-
 docs/subsystems/subagent.i18n.yaml            |  2 +-
 docs/subsystems/subagent.zh.md                |  4 +-
 docs/subsystems/subprocess.i18n.yaml          |  2 +-
 docs/subsystems/subprocess.zh.md              |  2 +-
 docs/subsystems/system-prompt.i18n.yaml       |  2 +-
 docs/subsystems/system-prompt.zh.md           |  2 +-
 docs/subsystems/tasks.i18n.yaml               |  2 +-
 docs/subsystems/tasks.zh.md                   |  4 +-
 docs/subsystems/telemetry.i18n.yaml           |  2 +-
 docs/subsystems/telemetry.zh.md               |  6 +--
 docs/subsystems/tools.i18n.yaml               |  2 +-
 docs/subsystems/tools.zh.md                   |  4 +-
 docs/subsystems/typert.i18n.yaml              |  2 +-
 docs/subsystems/typert.zh.md                  |  2 +-
 docs/subsystems/web.i18n.yaml                 |  2 +-
 docs/subsystems/web.zh.md                     |  2 +-
 docs/testing.i18n.yaml                        |  2 +-
 docs/testing.zh.md                            |  6 +--
 docs/user/develop/framework/events.i18n.yaml  |  2 +-
 docs/user/develop/framework/events.zh.md      |  2 +-
 .../develop/practice/llm-adapter.i18n.yaml    |  2 +-
 docs/user/develop/practice/llm-adapter.zh.md  |  2 +-
 docs/web-styling.i18n.yaml                    |  2 +-
 docs/web-styling.zh.md                        |  6 +--
 examples/acp-agent/README.i18n.yaml           |  2 +-
 examples/acp-agent/README.zh.md               |  4 +-
 examples/web-cordis/README.i18n.yaml          |  2 +-
 examples/web-cordis/README.zh.md              |  2 +-
 native/landlock-run/README.i18n.yaml          |  2 +-
 native/landlock-run/README.zh.md              |  4 +-
 .../packages/entry/README.i18n.yaml           |  2 +-
 .../landlock-run/packages/entry/README.zh.md  |  2 +-
 packages/acp/acp/README.i18n.yaml             |  2 +-
 packages/acp/acp/README.zh.md                 |  2 +-
 packages/api/README.i18n.yaml                 |  2 +-
 packages/api/README.zh.md                     |  4 +-
 packages/api/gateway/README.i18n.yaml         |  2 +-
 packages/api/gateway/README.zh.md             |  4 +-
 packages/api/remotes/README.i18n.yaml         |  2 +-
 packages/api/remotes/README.zh.md             |  2 +-
 packages/bash/bash-env/README.i18n.yaml       |  2 +-
 packages/bash/bash-env/README.zh.md           |  2 +-
 packages/bash/tool-bash/README.i18n.yaml      |  2 +-
 packages/bash/tool-bash/README.zh.md          |  8 ++--
 packages/bash/tool-pwsh/README.i18n.yaml      |  2 +-
 packages/bash/tool-pwsh/README.zh.md          |  6 +--
 packages/boot/README.i18n.yaml                |  2 +-
 packages/boot/README.zh.md                    |  2 +-
 packages/bundle/README.i18n.yaml              |  2 +-
 packages/bundle/README.zh.md                  |  2 +-
 packages/bundle/web-app/README.i18n.yaml      |  2 +-
 packages/bundle/web-app/README.zh.md          |  2 +-
 packages/client/README.i18n.yaml              |  2 +-
 packages/client/README.zh.md                  |  2 +-
 packages/client/connection/README.i18n.yaml   |  2 +-
 packages/client/connection/README.zh.md       |  2 +-
 packages/client/runtime/README.i18n.yaml      |  2 +-
 packages/client/runtime/README.zh.md          |  2 +-
 packages/client/schema-form/README.i18n.yaml  |  2 +-
 packages/client/schema-form/README.zh.md      |  2 +-
 packages/client/ui-command/README.i18n.yaml   |  2 +-
 packages/client/ui-command/README.zh.md       |  4 +-
 .../client/ui-conversation/README.i18n.yaml   |  2 +-
 packages/client/ui-conversation/README.zh.md  |  4 +-
 packages/client/ui-layout/README.i18n.yaml    |  2 +-
 packages/client/ui-layout/README.zh.md        |  2 +-
 packages/client/ui-model/README.i18n.yaml     |  2 +-
 packages/client/ui-model/README.zh.md         |  2 +-
 packages/client/ui-sidebar/README.i18n.yaml   |  2 +-
 packages/client/ui-sidebar/README.zh.md       |  2 +-
 packages/client/ui-slash/README.i18n.yaml     |  2 +-
 packages/client/ui-slash/README.zh.md         |  4 +-
 packages/client/ui-slots/README.i18n.yaml     |  2 +-
 packages/client/ui-slots/README.zh.md         |  4 +-
 packages/client/ui-theme/README.i18n.yaml     |  2 +-
 packages/client/ui-theme/README.zh.md         |  2 +-
 packages/client/ui-tool/README.i18n.yaml      |  2 +-
 packages/client/ui-tool/README.zh.md          |  6 +--
 .../client/ui-trajectory/README.i18n.yaml     |  2 +-
 packages/client/ui-trajectory/README.zh.md    |  2 +-
 .../code-runtime/README.i18n.yaml             |  2 +-
 .../code-runtime/code-runtime/README.zh.md    |  6 +--
 packages/compact/README.i18n.yaml             |  2 +-
 packages/compact/README.zh.md                 |  2 +-
 .../compact/command-compact/README.i18n.yaml  |  2 +-
 packages/compact/command-compact/README.zh.md |  2 +-
 packages/compact/compact/README.i18n.yaml     |  2 +-
 packages/compact/compact/README.zh.md         |  6 +--
 .../session-reference/README.i18n.yaml        |  2 +-
 .../context/session-reference/README.zh.md    |  4 +-
 packages/core/agent-loop/README.i18n.yaml     |  2 +-
 packages/core/agent-loop/README.zh.md         |  2 +-
 packages/core/agent/README.i18n.yaml          |  2 +-
 packages/core/agent/README.zh.md              |  8 ++--
 packages/core/scope/README.i18n.yaml          |  2 +-
 packages/core/scope/README.zh.md              |  4 +-
 packages/core/system-prompt/README.i18n.yaml  |  2 +-
 packages/core/system-prompt/README.zh.md      |  2 +-
 packages/core/tools/README.i18n.yaml          |  2 +-
 packages/core/tools/README.zh.md              | 10 ++---
 .../examples/jsonrpc-demo/README.i18n.yaml    |  2 +-
 packages/examples/jsonrpc-demo/README.zh.md   |  2 +-
 .../command-feedback/README.i18n.yaml         |  2 +-
 .../feedback/command-feedback/README.zh.md    |  4 +-
 packages/fs/fs/README.i18n.yaml               |  2 +-
 packages/fs/fs/README.zh.md                   |  4 +-
 packages/fs/tool-fs-search/README.i18n.yaml   |  2 +-
 packages/fs/tool-fs-search/README.zh.md       |  4 +-
 packages/fs/tool-fs/README.i18n.yaml          |  2 +-
 packages/fs/tool-fs/README.zh.md              |  4 +-
 packages/goal/command-goal/README.i18n.yaml   |  2 +-
 packages/goal/command-goal/README.zh.md       |  2 +-
 packages/goal/goal-session/README.i18n.yaml   |  2 +-
 packages/goal/goal-session/README.zh.md       |  2 +-
 packages/goal/goal/README.i18n.yaml           |  2 +-
 packages/goal/goal/README.zh.md               |  4 +-
 packages/hooks/hook-protocol/README.i18n.yaml |  2 +-
 packages/hooks/hook-protocol/README.zh.md     |  4 +-
 packages/host/apiproxy/README.i18n.yaml       |  2 +-
 packages/host/apiproxy/README.zh.md           |  4 +-
 .../host/directory-picker/README.i18n.yaml    |  2 +-
 packages/host/directory-picker/README.zh.md   |  4 +-
 packages/host/webserver/README.i18n.yaml      |  2 +-
 packages/host/webserver/README.zh.md          |  2 +-
 packages/interaction/README.i18n.yaml         |  2 +-
 packages/interaction/README.zh.md             |  2 +-
 .../interaction/commands/README.i18n.yaml     |  2 +-
 packages/interaction/commands/README.zh.md    |  6 +--
 packages/llm/llm-deepseek/README.i18n.yaml    |  2 +-
 packages/llm/llm-deepseek/README.zh.md        |  4 +-
 packages/llm/token-meter/README.i18n.yaml     |  2 +-
 packages/llm/token-meter/README.zh.md         |  2 +-
 packages/lsp/lsp/README.i18n.yaml             |  2 +-
 packages/lsp/lsp/README.zh.md                 |  4 +-
 packages/mcp/mcp-client/README.i18n.yaml      |  2 +-
 packages/mcp/mcp-client/README.zh.md          |  2 +-
 packages/pty/pty/README.i18n.yaml             |  2 +-
 packages/pty/pty/README.zh.md                 |  4 +-
 .../pty/tool-bash-persistent/README.i18n.yaml |  2 +-
 .../pty/tool-bash-persistent/README.zh.md     |  4 +-
 packages/sandbox/sandbox/README.i18n.yaml     |  2 +-
 packages/sandbox/sandbox/README.zh.md         |  2 +-
 packages/scaffold/protocol/README.i18n.yaml   |  2 +-
 packages/scaffold/protocol/README.zh.md       |  2 +-
 .../session-query-sqlite/README.i18n.yaml     |  2 +-
 .../session-query-sqlite/README.zh.md         |  4 +-
 .../session-query/README.i18n.yaml            |  2 +-
 .../session-query/session-query/README.zh.md  |  4 +-
 .../README.i18n.yaml                          |  2 +-
 .../session-persistence-jsonl/README.zh.md    |  2 +-
 .../README.i18n.yaml                          |  2 +-
 .../session-persistence-sqlite/README.zh.md   | 10 ++---
 .../session-projection-cache/README.i18n.yaml |  4 +-
 .../session-projection-cache/README.zh.md     |  2 +-
 .../session-projection/README.i18n.yaml       |  2 +-
 .../session/session-projection/README.zh.md   |  4 +-
 .../session-telemetry-otel/README.i18n.yaml   |  2 +-
 .../session-telemetry-otel/README.zh.md       |  2 +-
 .../session-telemetry/README.i18n.yaml        |  2 +-
 .../session/session-telemetry/README.zh.md    |  2 +-
 .../session-title-llm/README.i18n.yaml        |  4 +-
 .../session/session-title-llm/README.zh.md    |  4 +-
 .../session/session-title/README.i18n.yaml    |  2 +-
 packages/session/session-title/README.zh.md   |  4 +-
 packages/settings/settings/README.i18n.yaml   |  2 +-
 packages/settings/settings/README.zh.md       |  2 +-
 packages/skill/skill/README.i18n.yaml         |  2 +-
 packages/skill/skill/README.zh.md             |  6 +--
 packages/spill/spill/README.i18n.yaml         |  2 +-
 packages/spill/spill/README.zh.md             |  2 +-
 .../storage/storage-sqlite/README.i18n.yaml   |  2 +-
 packages/storage/storage-sqlite/README.zh.md  |  2 +-
 .../subagent-claude-code/README.i18n.yaml     |  2 +-
 .../subagent-claude-code/README.zh.md         |  4 +-
 .../subagent/subagent-codex/README.i18n.yaml  |  2 +-
 packages/subagent/subagent-codex/README.zh.md |  6 +--
 .../subagent-dsh-sdk/README.i18n.yaml         |  2 +-
 .../subagent/subagent-dsh-sdk/README.zh.md    |  2 +-
 .../subagent/subagent-fork/README.i18n.yaml   |  2 +-
 packages/subagent/subagent-fork/README.zh.md  |  2 +-
 .../subagent-inprocess/README.i18n.yaml       |  2 +-
 .../subagent/subagent-inprocess/README.zh.md  |  2 +-
 packages/subagent/subagent/README.i18n.yaml   |  2 +-
 packages/subagent/subagent/README.zh.md       |  6 +--
 .../subagent/tool-subagent/README.i18n.yaml   |  2 +-
 packages/subagent/tool-subagent/README.zh.md  |  2 +-
 .../subprocess/subprocess/README.i18n.yaml    |  2 +-
 packages/subprocess/subprocess/README.zh.md   |  2 +-
 packages/support/README.i18n.yaml             |  2 +-
 packages/support/README.zh.md                 |  6 +--
 .../support/acp-snapshot/README.i18n.yaml     |  2 +-
 packages/support/acp-snapshot/README.zh.md    |  2 +-
 packages/support/invariants/README.i18n.yaml  |  2 +-
 packages/support/invariants/README.zh.md      |  6 +--
 packages/tasks/tasks/README.i18n.yaml         |  2 +-
 packages/tasks/tasks/README.zh.md             |  8 ++--
 packages/typert/registry/README.i18n.yaml     |  2 +-
 packages/typert/registry/README.zh.md         |  2 +-
 packages/typert/type-meta/README.i18n.yaml    |  2 +-
 packages/typert/type-meta/README.zh.md        |  4 +-
 packages/util/README.i18n.yaml                |  2 +-
 packages/util/README.zh.md                    |  2 +-
 packages/util/atomic-write/README.i18n.yaml   |  2 +-
 packages/util/atomic-write/README.zh.md       |  2 +-
 packages/util/environment/README.i18n.yaml    |  2 +-
 packages/util/environment/README.zh.md        |  2 +-
 packages/util/native-command/README.i18n.yaml |  2 +-
 packages/util/native-command/README.zh.md     |  2 +-
 packages/web/README.i18n.yaml                 |  2 +-
 packages/web/README.zh.md                     |  2 +-
 packages/web/tool-web/README.i18n.yaml        |  2 +-
 packages/web/tool-web/README.zh.md            |  2 +-
 .../web/web-search-deepseek/README.i18n.yaml  |  2 +-
 packages/web/web-search-deepseek/README.zh.md |  2 +-
 packages/web/web/README.i18n.yaml             |  2 +-
 packages/web/web/README.zh.md                 |  4 +-
 packages/workflow/README.i18n.yaml            |  2 +-
 packages/workflow/README.zh.md                |  6 +--
 packages/workflow/tool-ralph/README.i18n.yaml |  2 +-
 packages/workflow/tool-ralph/README.zh.md     |  4 +-
 .../workflow/tool-workflow/README.i18n.yaml   |  2 +-
 packages/workflow/tool-workflow/README.zh.md  |  4 +-
 .../workflow-workerthread/README.i18n.yaml    |  2 +-
 .../workflow-workerthread/README.zh.md        |  2 +-
 packages/workflow/workflow/README.i18n.yaml   |  2 +-
 packages/workflow/workflow/README.zh.md       |  6 +--
 packages/workspace/README.i18n.yaml           |  2 +-
 packages/workspace/README.zh.md               |  2 +-
 .../request-response.expected.json            | 10 ++---
 848 files changed, 1506 insertions(+), 1506 deletions(-)

diff --git a/.agents/notes/README.i18n.yaml b/.agents/notes/README.i18n.yaml
index 6eac4fbcce..b33a36665d 100644
--- a/.agents/notes/README.i18n.yaml
+++ b/.agents/notes/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/README.md
 README.md: 3cfbb5154713046846a3bfcb2ccea62c0e4cb6c0
-README.zh.md: 61887320e9e54b35154c79e33e9a9525aceeef50
+README.zh.md: 4b3a1ee57ea61a8e8ba4d01cf7c719bbf8440e30
diff --git a/.agents/notes/README.zh.md b/.agents/notes/README.zh.md
index 61887320e9..4b3a1ee57e 100644
--- a/.agents/notes/README.zh.md
+++ b/.agents/notes/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这里存放一类设计文档。**Agent Note** 记录塑造本代码库的决策或提案：代码和文档无法承载的*为什么*以及*放弃了什么*。本文件是入口和契约：Agent Note 存放在哪里、何时需要写一份，以及[文件内格式](#the-file-format)。
+这里存放一类设计文档。**Agent Note** 记录塑造本代码库的决策或提案：代码和文档无法承载的*为什么*以及*放弃了什么*。本文件是入口和约定：Agent Note 存放在哪里、何时需要写一份，以及[文件内格式](#the-file-format)。
 
 ## 布局与命名
 
@@ -45,13 +45,13 @@
 
 ## 何时需要写一份
 
-每个非平凡变更都必须在同一 PR（Pull Request）中新增或更新至少一份 Agent Note。如果变更修改了行为、架构、跨文件或跨包契约、流程或工具、测试策略、磁盘存储格式、协议格式（wire format）或配置格式，或者其他维护者可能合理重新审视的决策，就属于非平凡变更。对未来重大工作的提案从 `proposed/` 开始；已经做出的决策从 `implemented/` 开始。选择与决策匹配的类别文件夹（见[分类](#classification)）。
+每个非平凡变更都必须在同一 PR（Pull Request）中新增或更新至少一份 Agent Note。如果变更修改了行为、架构、跨文件或跨包约定、流程或工具、测试策略、磁盘存储格式、协议格式（wire format）或配置格式，或者其他维护者可能合理重新审视的决策，就属于非平凡变更。对未来重大工作的提案从 `proposed/` 开始；已经做出的决策从 `implemented/` 开始。选择与决策匹配的类别文件夹（见[分类](#classification)）。
 
-更新已经拥有该决策的 Agent Note 即可满足规则；不要创建重复记录。只有不涉及行为、契约、结构、流程或理由变化的纯机械性或局部编辑才可豁免。Agent Note 永远不会被编辑为一个*不同的决策*：用新 Agent Note 取代旧记录，并让两个记录保持互相链接，除非后续依据下方规则完全合并旧记录。编辑 `implemented/` Agent Note 以跟踪其现有决策的所在位置是必需的，而非禁止的；见 [implemented/AGENTS.md](implemented/AGENTS.md)。
+更新已经拥有该决策的 Agent Note 即可满足规则；不要创建重复记录。只有不涉及行为、约定、结构、流程或理由变化的纯机械性或局部编辑才可豁免。Agent Note 永远不会被编辑为一个*不同的决策*：用新 Agent Note 取代旧记录，并让两个记录保持互相链接，除非后续依据下方规则完全合并旧记录。编辑 `implemented/` Agent Note 以跟踪其现有决策的所在位置是必需的，而非禁止的；见 [implemented/AGENTS.md](implemented/AGENTS.md)。
 
-被完全取代的 implemented Agent Note 可以合并到当前持有该决策的记录中，并删除原文件。删除前，当前记录必须保存所有独有的决策依据、备选方案、影响、验证契约和明确指出的覆盖缺口；修复所有入站链接；并在同一变更中删除中文对侧文件和一致性记录。仅部分被取代的记录不符合此条件：保留两个记录并让它们互相链接，同时更新所有仍然适用的事实。合并不得将旧文件改写成与其相反的决策，也不得让 git 历史成为决策依据的唯一副本。
+被完全取代的 implemented Agent Note 可以合并到当前持有该决策的记录中，并删除原文件。删除前，当前记录必须保存所有独有的决策依据、备选方案、影响、验证约定和明确指出的覆盖缺口；修复所有入站链接；并在同一变更中删除中文对侧文件和一致性记录。仅部分被取代的记录不符合此条件：保留两个记录并让它们互相链接，同时更新所有仍然适用的事实。合并不得将旧文件改写成与其相反的决策，也不得让 git 历史成为决策依据的唯一副本。
 
-只有当一项功能已从生产代码、配置、schema、持久化格式或协议格式、迁移和兼容行为中完全消失，当前文档不再将其描述为可用，且没有测试把它作为受支持行为来执行时，新增该功能的 Agent Note 才可合并进后续的移除记录。移除决策的依据和验证该功能已不存在的测试可以保留。移除决策的持有记录必须保留最初动机、为什么该动机已不足以证明保留该功能的合理性、完全移除之外的备选方案、放弃的能力、重新引入的条件，以及证明已彻底移除的验证。过时的实现清单和只验证已删除行为的测试不属于当前验证契约。仅移除一种传输、默认值、实现或展示属于部分取代；仍有任何持久数据或兼容处理也同样如此。
+只有当一项功能已从生产代码、配置、schema、持久化格式或协议格式、迁移和兼容行为中完全消失，当前文档不再将其描述为可用，且没有测试把它作为受支持行为来执行时，新增该功能的 Agent Note 才可合并进后续的移除记录。移除决策的依据和验证该功能已不存在的测试可以保留。移除决策的持有记录必须保留最初动机、为什么该动机已不足以证明保留该功能的合理性、完全移除之外的备选方案、放弃的能力、重新引入的条件，以及证明已彻底移除的验证。过时的实现清单和只验证已删除行为的测试不属于当前验证约定。仅移除一种传输、默认值、实现或展示属于部分取代；仍有任何持久数据或兼容处理也同样如此。
 
 <a id="the-file-format"></a>
 
@@ -79,7 +79,7 @@ Status: <status>
 
 ### 正文骨架
 
-每份 Agent Note 的正文以 `## Problem` 开头：动机，写法上不依赖解决方案即可独立成文。后续内容取决于生命周期；固定章节使用以下规范名称且仅限这些名称，而真正独特的技术章节（包拓扑、协议契约、schema 等）在必需章节之间可自由组织。
+每份 Agent Note 的正文以 `## Problem` 开头：动机，写法上不依赖解决方案即可独立成文。后续内容取决于生命周期；固定章节使用以下规范名称且仅限这些名称，而真正独特的技术章节（包拓扑、协议约定、schema 等）在必需章节之间可自由组织。
 
 #### `proposed/`
 
@@ -126,4 +126,4 @@ Status: <status>
 
 ### 中文对侧文件
 
-`.zh.md` 对侧文件按 [i18n 契约](../../docs/i18n/README.md)逐章节镜像其英文对侧文件的结构；机器检查的头部标记（`# Agent Note: ` 和 `Status:` 行）保持英文原样不翻译。格式门禁跳过 `.zh.md` 文件——配对门禁负责它们的一致性。
+`.zh.md` 对侧文件按 [i18n 约定](../../docs/i18n/README.md)逐章节镜像其英文对侧文件的结构；机器检查的头部标记（`# Agent Note: ` 和 `Status:` 行）保持英文原样不翻译。格式门禁跳过 `.zh.md` 文件——配对门禁负责它们的一致性。
diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
index 49a169445e..f89d1da013 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
 2026-06-11-dev-invariants-over-deep-readonly.md: f1a741927cf63b43b1aaf558efc148ff80d2d881
-2026-06-11-dev-invariants-over-deep-readonly.zh.md: 9aadde4f4452a53acce8a3bcf58560ee9722ecfb
+2026-06-11-dev-invariants-over-deep-readonly.zh.md: ade3e20adb8f5301adb87130d42c2bd7a37f8a47
diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
index 9aadde4f44..ade3e20adb 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 会话日志是回放、请求重建、持久化与用户可见历史的持久真源。会话包外部的代码必须能检视历史，但不能保留一个可在之后改写历史的引用；从调用方接受的输入也不能继续连接到调用方拥有的可变对象。
 
-单个值的不可变性只是契约的一半。一份日志可以包含完全不可变的记录，但其序列、轮次/步骤嵌套、工具调用配对、作用域分发或重建的模型请求是错误的。这些规则涉及多条记录或多个服务，无法通过冻结单个对象来建立。
+单个值的不可变性只是约定的一半。一份日志可以包含完全不可变的记录，但其序列、轮次/步骤嵌套、工具调用配对、作用域分发或重建的模型请求是错误的。这些规则涉及多条记录或多个服务，无法通过冻结单个对象来建立。
 
 TypeScript readonly 类型不是充分的运行时边界。它们在程序运行时消失，类型转换可以绕过它们，而递归的 `DeepReadonly<T>` 会扩散到每个日志和消息消费方，尽管某些下游请求处理 API 有意使用可变值。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
index 03d64c4d4d..2a310c8172 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-13-capability-seams.md
 2026-06-13-capability-seams.md: 7c755dced7825d2831acc0901f6412b8e5afe95a
-2026-06-13-capability-seams.zh.md: 3d0fe2b842766838d247aca75972509bf6c7b951
+2026-06-13-capability-seams.zh.md: 31d20bb15f91533ab3c09d337a3cb11f812dbeb4
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
index 3d0fe2b842..31d20bb15f 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化／远程执行器和替代模型提供方。一项能力涉及三个关注点，它们以不同速率、因不同原因变化：*契约*（这项能力是什么）、*实现*（它如何运行）、*消费方接口*（模型和其他插件面向什么编程）。将三者捆绑在一个包中会耦合这些变化速率——把本地执行器换成沙箱化执行器时，模型看到的工具 schema 也会被搅动，尽管面向模型的契约从未改变。
+harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化／远程执行器和替代模型提供方。一项能力涉及三个关注点，它们以不同速率、因不同原因变化：*约定*（这项能力是什么）、*实现*（它如何运行）、*消费方接口*（模型和其他插件面向什么编程）。将三者捆绑在一个包中会耦合这些变化速率——把本地执行器换成沙箱化执行器时，模型看到的工具 schema 也会被搅动，尽管面向模型的约定从未改变。
 
 这与「谁在运行时提供、谁需要一项能力」是不同的问题，后者 Cordis 已通过服务 + `inject` 解决（提供方注册 `ctx.bash`；消费方声明 `inject: ['bash']`，其 fiber 挂起直到服务存在）。该机制是必要的，但不决定包的边界；本 Agent Note 决定的是包的边界。
 
@@ -29,4 +29,4 @@ harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化
 
 ## 后果
 
-每项能力需要更多包和更多样板代码（一组 `package.json`/`tsconfig`/README，加上 inject 接线）。换来的是：实现与消费方独立发布和版本管理，新后端永远不会波及面向模型的契约。该规则记录在 [AGENTS.md](../../../../AGENTS.md) § Conventions（「Capability seams are three packages」）和 [architecture.md](../../../../docs/architecture.md) §「Capability seams」中；bash 三件套是参考模板。何时合并、何时拆分是一个判断问题，架构文档对此有详细说明——本 Agent Note 记录的是*为什么*默认选择拆分。
+每项能力需要更多包和更多样板代码（一组 `package.json`/`tsconfig`/README，加上 inject 接线）。换来的是：实现与消费方独立发布和版本管理，新后端永远不会波及面向模型的约定。该规则记录在 [AGENTS.md](../../../../AGENTS.md) § Conventions（「Capability seams are three packages」）和 [architecture.md](../../../../docs/architecture.md) §「Capability seams」中；bash 三件套是参考模板。何时合并、何时拆分是一个判断问题，架构文档对此有详细说明——本 Agent Note 记录的是*为什么*默认选择拆分。
diff --git a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml
index 6fbbd961a2..d44279eb42 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md
 2026-06-13-twin-llm-adapters.md: a4c87325a0b0d1ebe6cf8f95672e5de74ef37d57
-2026-06-13-twin-llm-adapters.zh.md: 753d7900f23c0d3388be0488c291145fdccf5a95
+2026-06-13-twin-llm-adapters.zh.md: 2af7e7cca4d4c40e18cece1a4dd5c9cdb11901c8
diff --git a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md
index 753d7900f2..2af7e7cca4 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-`dsh-llm` 拥有一套提供方无关的流式词汇：`StreamChunk` 协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）以及内容块类型（[内容块词汇](2026-06-11-content-block-vocabulary.md)）。如果词汇仅针对单个适配器定义，就有可能将该适配器的特异行为固化到「中立」契约中：唯一实现碰巧做了什么，什么就成为事实上的规范；在第二个提供方到来之前，抽象层未经验证——而届时修复这种泄漏的代价已经很高。
+`dsh-llm` 拥有一套提供方无关的流式词汇：`StreamChunk` 协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）以及内容块类型（[内容块词汇](2026-06-11-content-block-vocabulary.md)）。如果词汇仅针对单个适配器定义，就有可能将该适配器的特异行为固化到「中立」约定中：唯一实现碰巧做了什么，什么就成为事实上的规范；在第二个提供方到来之前，抽象层未经验证——而届时修复这种泄漏的代价已经很高。
 
 ## 决策
 
-从一开始就针对同一份契约交付**两个**适配器，刻意基于不同的内部实现构建：
+从一开始就针对同一份约定交付**两个**适配器，刻意基于不同的内部实现构建：
 
 - `dsh-llm-deepseek`：直接 `fetch` + 仓库内翻译逻辑对接 DeepSeek API；SSE（Server-Sent Events）分帧委托给 `eventsource-parser`（[已归档的 SSE 解析器替换](../../archived/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md)）。孪生身份在于自行持有 fetch/translate 内部实现而非委托给完整的提供方 SDK，不在于手写传输层管道。
 - `dsh-llm-pi-ai`：通过 `@earendil-works/pi-ai` 库访问同一端点（该库有自己的事件词汇）。
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
index 6737b3f490..bead51ff09 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-14-session-persistence.md
 2026-06-14-session-persistence.md: 00e129e57c7144fd62eec26f5854ee21dec4e964
-2026-06-14-session-persistence.zh.md: 6e4e9ece56332ce74b01d60a111617c70e2a874a
+2026-06-14-session-persistence.zh.md: df03dce6bd978f10deb64b8d75ae0685dabab7cd
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
index 6e4e9ece56..df03dce6bd 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
@@ -27,7 +27,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-上述每个关键选择都在陈述处记录了被否决的替代方案：**过滤分片的规范日志**（Codex 的 `policy.rs` 形式）破坏连续 seq 契约；**截断崩溃的轮次**会静默销毁长时间自主运行中的真实工作；**日志内 `session/meta` 事件作为第 0 行**——元数据不是可回放状态；**有限的非整数 `createdAt` 值**没有生产方，且与整数 Unix 毫秒存储及查询列不一致；**接受非全新的未版本化 SQLite 文件**可能覆盖无关对象或应用标识；**将 `sessionPersistence` 硬注入循环**会让非持久化的演示永远挂起。
+上述每个关键选择都在陈述处记录了被否决的替代方案：**过滤分片的规范日志**（Codex 的 `policy.rs` 形式）破坏连续 seq 约定；**截断崩溃的轮次**会静默销毁长时间自主运行中的真实工作；**日志内 `session/meta` 事件作为第 0 行**——元数据不是可回放状态；**有限的非整数 `createdAt` 值**没有生产方，且与整数 Unix 毫秒存储及查询列不一致；**接受非全新的未版本化 SQLite 文件**可能覆盖无关对象或应用标识；**将 `sessionPersistence` 硬注入循环**会让非持久化的演示永远挂起。
 
 格式版本控制：header 携带一个 `version`；冷读取拒绝任何非当前版本。预发布阶段的会话格式仍固定为 `SESSION_FORMAT_VERSION = 0`，不承诺广泛兼容；当持久化用户数据确有需要时，协调器可以负责显式且范围受限的导入升级（[消息标识机制引入前的消息恢复](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。坦率地说：仅追加 + 刷写对部分尾部写入是健壮的（冷准备时容忍），但对行写入中途的无 fsync 断电不健壮；数据库/WAL 后端是后续更强的选项。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index ddb215be9f..4511cefb31 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
 2026-06-17-filesystem-capability-seam.md: 7436d2a9402c76f17c7d6571eb489a86e550ebfb
-2026-06-17-filesystem-capability-seam.zh.md: fdeafba387b562352b377321327c526a67669ef6
+2026-06-17-filesystem-capability-seam.zh.md: a96d513d7f4fa793ebb3427e3f7b290862d0d5e9
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
index fdeafba387..a96d513d7f 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -10,11 +10,11 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 这把三个独立变化的关注点耦合在了一起：
 
-1. 文件系统契约：插件可以请求哪些操作。
+1. 文件系统约定：插件可以请求哪些操作。
 2. 后端：当前是本地磁盘，未来可能是沙箱/远程/项目作用域的文件系统。
 3. 消费方接口：面向模型的 `read` / `write` / `edit` schema 与结果格式化。
 
-如果没有 `ctx.fs` 接口，将本地文件系统访问替换为沙箱或远程后端时，即使面向模型的契约应当保持稳定，工具 schema、演示和提示词引导也会被迫变动。这还使权限/沙箱边界更难推理：一个 `cwd` 选项看起来像沙箱，但除非有显式的后端或 `tools/execute` 策略强制隔离，否则它只是一个基础路径。
+如果没有 `ctx.fs` 接口，将本地文件系统访问替换为沙箱或远程后端时，即使面向模型的约定应当保持稳定，工具 schema、演示和提示词引导也会被迫变动。这还使权限/沙箱边界更难推理：一个 `cwd` 选项看起来像沙箱，但除非有显式的后端或 `tools/execute` 策略强制隔离，否则它只是一个基础路径。
 
 我们需要文件系统工具在成为公开包（package）接口之前，以与 bash 相同的能力 seam 形态落地。
 
@@ -55,7 +55,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 根 `tool-fs` 插件通过组合各工具的注册辅助函数来注册完整的文件系统工具套件（`read`、`write` 和 `edit`）。它注入 `fs`，从不导入实现包。
 
-## `ctx.fs` 契约
+## `ctx.fs` 约定
 
 `@deepseek-ai/dsh-fs` 拥有一个语义文件系统服务。它比 `readFile` / `writeFile` 更高层，这样 `tool-fs` 就不必重新实现路径解析、版本管理、文本解码、二进制拒绝、分页、原子替换、符号链接行为或字面编辑语义。
 
@@ -98,7 +98,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 策略插件（而非 `ctx.fs`）对先前观测进行门控：`edit` 要求 owner 有先前观测（否则报 `FS_NOT_OBSERVED`），记录的版本作为 CAS 基础传给 `editText`。在策略插件缺席时，`ctx.fs` 本身是一个完整的无约束 seam（无条件写入/编辑）；工具从不与策略方法耦合。
 
-文件系统契约失败以 `FsError extends HarnessError` 抛出，工具注册表将其转换为带结构化 `{ name, code }` 元数据的 `isError` 工具结果。`dsh-fs` 拥有此词汇，而非由每个工具各自发明消息。错误码包括 `FS_NOT_FOUND`、`FS_NOT_TEXT`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_NOT_REGULAR_FILE`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND` 和 `FS_ABORTED`。（早期草案包含 `FS_PARTIAL_OBSERVATION`；基于新鲜度的授权没有 partial/full 区分，因此已删除。目录列表相关的错误码后来由[为文件系统 seam 添加直接目录列举能力](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)添加。）
+文件系统约定失败以 `FsError extends HarnessError` 抛出，工具注册表将其转换为带结构化 `{ name, code }` 元数据的 `isError` 工具结果。`dsh-fs` 拥有此词汇，而非由每个工具各自发明消息。错误码包括 `FS_NOT_FOUND`、`FS_NOT_TEXT`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_NOT_REGULAR_FILE`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND` 和 `FS_ABORTED`。（早期草案包含 `FS_PARTIAL_OBSERVATION`；基于新鲜度的授权没有 partial/full 区分，因此已删除。目录列表相关的错误码后来由[为文件系统 seam 添加直接目录列举能力](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)添加。）
 
 ## 工具消费方行为
 
@@ -119,7 +119,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 该包通过 `ctx.systemPrompt.section(...)` 注册提示词引导，通过 `ctx.tools.register(...)` 注册 schema。工具 schema 仍通过 `SystemPrompt.assemble()` 和 `ToolRegistry.schemas()` 流入正常的提示词组装路径；无需改动 agent loop（智能体循环）。
 
-工具包在后端变化时保持面向模型的契约稳定：本地后端和远程后端内部可能以不同方式解析路径，但 `read` / `write` / `edit` schema 不会仅因后端变化而改变。
+工具包在后端变化时保持面向模型的约定稳定：本地后端和远程后端内部可能以不同方式解析路径，但 `read` / `write` / `edit` schema 不会仅因后端变化而改变。
 
 默认部署要求在用 `write` 或 `edit` 更新已有文件之前先 `read`。`tool-fs` 不通过检查是否运行过名为 `read` 的工具来实现这一点：它分发 `fs/write-intent`/`fs/edit-intent` 事件（将执行上下文作为不透明 actor 传递），`dsh-fs-policy` 插件推导 owner、对先前观测进行门控并提供版本期望。任何窗口化读取都能授权后续的写入/编辑，只要文件未变。用 `write` 创建新文件不要求先前观测。
 
@@ -144,9 +144,9 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 ## 后果
 
-**`cwd` 可能被误认为沙箱。** 本地后端的基目录是解析默认值，而非自动的隔离边界。如果需要隔离，必须由后端契约或 `tools/execute` 上的权限/沙箱插件强制执行。
+**`cwd` 可能被误认为沙箱。** 本地后端的基目录是解析默认值，而非自动的隔离边界。如果需要隔离，必须由后端约定或 `tools/execute` 上的权限/沙箱插件强制执行。
 
-**接口可能变得过于本地化。** 如果 `ctx.fs` 返回 `absolutePath` 之类的字段，远程、沙箱或虚拟后端会变得尴尬。契约应暴露显示元数据，而不要求消费方理解宿主路径。
+**接口可能变得过于本地化。** 如果 `ctx.fs` 返回 `absolutePath` 之类的字段，远程、沙箱或虚拟后端会变得尴尬。约定应暴露显示元数据，而不要求消费方理解宿主路径。
 
 **接口可能变得过于薄。** 如果 `ctx.fs` 只镜像 `node:fs` 原语，`tool-fs` 将重新实现二进制检测、分页、原子写入和编辑语义，重新制造本 Agent Note 试图避免的耦合。
 
@@ -154,7 +154,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 **观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本 Agent Note 最初将其放在文件系统 seam 内部；拆分文件系统 seam Agent Note 随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方 seam 只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
 
-**`resolve` 然后操作的形态每次调用多一次往返。** 每个工具可能先将路径解析为 `FsTarget`，再以单独的 `ctx.fs` 调用发起读取/写入/编辑。对本地后端来说这可以忽略（解析是内存中的路径规范化），但远程/沙箱后端可能将每步变成独立请求，使单次 `read` 变为两次网络往返。往返开销重要的后端可以在内部缓存或折叠解析，同时保持可观测契约不变。
+**`resolve` 然后操作的形态每次调用多一次往返。** 每个工具可能先将路径解析为 `FsTarget`，再以单独的 `ctx.fs` 调用发起读取/写入/编辑。对本地后端来说这可以忽略（解析是内存中的路径规范化），但远程/沙箱后端可能将每步变成独立请求，使单次 `read` 变为两次网络往返。往返开销重要的后端可以在内部缓存或折叠解析，同时保持可观测约定不变。
 
 **观测状态持久化被推迟。** 观测状态存在于内存中（`dsh-fs-policy` 内部的 `WeakMap`），因此恢复的会话保守地要求文件在写入/编辑前重新读取，直到未来的会话事件或持久化机制使观测可回放。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml
index 853db24cf1..70c9f791f4 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md
 2026-06-18-agent-lifecycle-and-ownership-seams.md: 93247a6da7446a5a67db33423d2b766ce4cf3308
-2026-06-18-agent-lifecycle-and-ownership-seams.zh.md: 7c0f27e1e6ddeec91a8031ef7b1d9fd965a4463a
+2026-06-18-agent-lifecycle-and-ownership-seams.zh.md: e17650c7789764dfb4240132f5903795e6f86381
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
index 7c0f27e1e6..e17650c778 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
@@ -14,7 +14,7 @@ ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个缺失 se
 
 ### 1. 队列感知的 `Agent.cancel(cause?)`
 
-`Agent` 接口新增 `cancel()` 动词——唯一的公开停止原语。（它最初与范围更窄、仅作用于步骤的 `abort()` 一同交付；后者后来因无人使用而移除，使 `cancel()` 成为唯一公开的停止工作方式。）它清空 inbox 的 queued + steering FIFO，在存在活跃轮次时中止它，并保留一个不带 cause 的 pre-run 标记，使在被领取前被取消的提示词永不运行，而后来的提示词仍保持独立。有效调用会在清空或中止前发出 `agent/cancel-requested`，携带类型化的 `user | parent` cause；空闲取消不发出任何事件，也不会使下一条提示词搁浅。`whenIdle()` 会在取消后达到完全停稳，ACP 的 `session/cancel` 映射到 `user`。[显式轮次取消决策](2026-07-16-explicit-turn-cancellation.md)规定了当前的 cause、signal 生命周期与协作式结算契约。
+`Agent` 接口新增 `cancel()` 动词——唯一的公开停止原语。（它最初与范围更窄、仅作用于步骤的 `abort()` 一同交付；后者后来因无人使用而移除，使 `cancel()` 成为唯一公开的停止工作方式。）它清空 inbox 的 queued + steering FIFO，在存在活跃轮次时中止它，并保留一个不带 cause 的 pre-run 标记，使在被领取前被取消的提示词永不运行，而后来的提示词仍保持独立。有效调用会在清空或中止前发出 `agent/cancel-requested`，携带类型化的 `user | parent` cause；空闲取消不发出任何事件，也不会使下一条提示词搁浅。`whenIdle()` 会在取消后达到完全停稳，ACP 的 `session/cancel` 映射到 `user`。[显式轮次取消决策](2026-07-16-explicit-turn-cancellation.md)规定了当前的 cause、signal 生命周期与协作式结算约定。
 
 ### 2. `AgentHandle` 异步释放器
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
index 911d0709f1..ce26042716 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-session-surface.md
 2026-06-18-session-surface.md: 1bb3baac5e9bea3f657cbd3be2623223bda78ce2
-2026-06-18-session-surface.zh.md: bfbfd097ffeca59dec163dff911315d0ed94d028
+2026-06-18-session-surface.zh.md: b967ad467e58ed4f4b4009fe4746f1b8b6b22f25
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
index bfbfd097ff..b967ad467e 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -33,7 +33,7 @@ export type SurfaceOp =
 
 ### SurfaceManager：基于增量，而非全量重建
 
-一个 `Session` 拥有一个 `SurfaceManager`，后者维护事件 seq 的有序 `number[]`。管理器会在提交前校验每个种子或追加候选项而不应用它，然后只处理上次同步之后已经提交的事件，而不重新扫描整个日志。`Session.surface` 通过只读的 `SessionSurface` 契约暴露同一个管理器，因此接纳、派生历史、压缩与工作区上下文共享同一份增量状态。Replace 按数组位置定位两个端点（均包含在范围内），并把替换 seq splice 到该范围；不会用第二个管理器、链接对象或 seq 到节点的 map 来重复表达顺序。
+一个 `Session` 拥有一个 `SurfaceManager`，后者维护事件 seq 的有序 `number[]`。管理器会在提交前校验每个种子或追加候选项而不应用它，然后只处理上次同步之后已经提交的事件，而不重新扫描整个日志。`Session.surface` 通过只读的 `SessionSurface` 约定暴露同一个管理器，因此接纳、派生历史、压缩与工作区上下文共享同一份增量状态。Replace 按数组位置定位两个端点（均包含在范围内），并把替换 seq splice 到该范围；不会用第二个管理器、链接对象或 seq 到节点的 map 来重复表达顺序。
 
 无新事件时增量处理为 O(1)，有新事件到达时为 O(新事件数)。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index 77c706518c..84edacb9dc 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
 2026-06-18-shared-persistence-write-coordinator.md: 12131ebf8380fb8ba816618f0cbaf72cb004623a
-2026-06-18-shared-persistence-write-coordinator.zh.md: 7c04ee921c9b3f965ef6bd6d2d203cf4cbd50ea2
+2026-06-18-shared-persistence-write-coordinator.zh.md: 0a7fbf351171d305b3b6245832a0b35a283c7c1d
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
index 7c04ee921c..0a7fbf3511 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`dsh-session-persistence-jsonl` 与 `dsh-session-persistence-sqlite` 有意在不同存储介质上证明同一份 `SessionPersistence` 契约，但它们重复实现了写入路径编排：每会话状态、`session/created` 接管、后端特定的前缀读取、write-behind 控制、按 id 串行执行操作、HMR（热模块替换）种子注入与 dispose（资源释放）排空。纯粹的种子前缀碰撞检查与可序列化守卫已迁入 seam 包；剩余的编排仍然对正确性要求很高，且同样的修复被应用了两次。唯一的差异在于存储原语（写字节 vs. INSERT 行）。
+`dsh-session-persistence-jsonl` 与 `dsh-session-persistence-sqlite` 有意在不同存储介质上证明同一份 `SessionPersistence` 约定，但它们重复实现了写入路径编排：每会话状态、`session/created` 接管、后端特定的前缀读取、write-behind 控制、按 id 串行执行操作、HMR（热模块替换）种子注入与 dispose（资源释放）排空。纯粹的种子前缀碰撞检查与可序列化守卫已迁入 seam 包；剩余的编排仍然对正确性要求很高，且同样的修复被应用了两次。唯一的差异在于存储原语（写字节 vs. INSERT 行）。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
index 863045f2ce..ebabaccdbb 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
 2026-06-20-generic-long-running-tool-runtime.md: 8cf6a34c3e4fc042bd73c147d83838734dfc9585
-2026-06-20-generic-long-running-tool-runtime.zh.md: 5af06b78e97980822687cdc82d9b0672a42b6fc2
+2026-06-20-generic-long-running-tool-runtime.zh.md: 44241321f6e4da428fe3a6402440af344fd69f10
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
index 5af06b78e9..44241321f6 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-后台 bash 原本兼有两项职责：bash 执行器既运行进程，又管理 task id、所有权、增量读取、取消、完成监听器和面向模型的控制工具。新增后台 subagent 需要相同的生命周期与交互契约。如果每种长时间运行能力都独立实现该契约，就会重复隔离、清理、通知和提示词行为，还会让模型为每种生产方学习不同的收集与停止协议。
+后台 bash 原本兼有两项职责：bash 执行器既运行进程，又管理 task id、所有权、增量读取、取消、完成监听器和面向模型的控制工具。新增后台 subagent 需要相同的生命周期与交互约定。如果每种长时间运行能力都独立实现该约定，就会重复隔离、清理、通知和提示词行为，还会让模型为每种生产方学习不同的收集与停止协议。
 
 任务注册表、控制工具与完成通知共同构成一项 harness 功能。bash 和 subagent 只提供执行专属的钩子，不拥有通用任务行为。
 
@@ -21,7 +21,7 @@ Status: implemented
 
 `TaskService` 是 `@deepseek-ai/dsh-tasks` 中的抽象 seam；进程内注册表是 `@deepseek-ai/dsh-tasks-local` 中的 `LocalTaskService`（该拆分记录在[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.md)中）。
 
-## 运行时契约
+## 运行时约定
 
 字面类型见[任务子系统页面](../../../../docs/subsystems/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。
 
@@ -39,7 +39,7 @@ Status: implemented
 
 运行时为 `done` 附加一个 continuation，记录第一个终止结果、解决等待方，并逐个调用完成监听器，同时隔离每个监听器的错误。首次结果优先的结算在资源销毁期间至关重要：如果 `cancel` 抛出，运行时会强制将记录标为失败，并警告工作可能遗留，而不是永远等待一个可能永不完成的 promise。后续生产方结果不能覆盖该诊断，也不能重复通知。`cancel` 返回后如果最终未使 `done` 完成，仍会阻塞资源销毁，因为运行时无法区分这种情况与缓慢但有效的停止。
 
-任务注册不是生产方工具 fiber 的 effect。因此，重新加载工具或控制接口插件不会终止由 agent（智能体）和后端拥有的工作。任务服务自身释放时会取消所有实时任务，并等待遵守契约的生产方。
+任务注册不是生产方工具 fiber 的 effect。因此，重新加载工具或控制接口插件不会终止由 agent（智能体）和后端拥有的工作。任务服务自身释放时会取消所有实时任务，并等待遵守约定的生产方。
 
 ## 授权与所有者生命周期
 
@@ -49,7 +49,7 @@ task id 在运行时全局可见且可预测，因此注册表会授权每次访
 
 某个所有者的第一个任务会向 `owner.ctx` 附加一个异步 effect。agent 作用域释放时会取消该所有者的实时任务、等待其终止记录，并移除其快照。该 effect 可跨生产方重载存续，并加入 agent 现有的完全停稳边界。任务服务保留 effect disposer，使服务重载可以在全局资源销毁后，从仍然存活的 agent 作用域中分离回调。
 
-对于遵守契约的生产方，`AgentHandle.dispose()` 只在所属后台工作停止后解决。需要比 agent 存活更久的工作必须以无所有者方式启动；要跨运行时重启存续，则需另行设计持久任务。
+对于遵守约定的生产方，`AgentHandle.dispose()` 只在所属后台工作停止后解决。需要比 agent 存活更久的工作必须以无所有者方式启动；要跨运行时重启存续，则需另行设计持久任务。
 
 ## 服务接口
 
@@ -103,7 +103,7 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `Bas
 
 ### 立即抽象任务运行时后端
 
-当前 `TaskStart.run()` 契约传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.md)后来在不改变这些进程内语义的前提下，将契约与进程内实现分离。
+当前 `TaskStart.run()` 约定传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.md)后来在不改变这些进程内语义的前提下，将约定与进程内实现分离。
 
 ### 由消费方负责授权或清理事件
 
@@ -121,7 +121,7 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `Bas
 
 ### 随机 id、提升或生命周期会话事件
 
-授权而非不可猜测性才是访问边界，并且 id 不用于派生文件系统路径；顺序生成的品牌化 id 可保持 transcript（文本记录）易读。将前台任务提升为后台任务需要 SDK 并未规定的用户交互契约。启动、读取和通知已作为工具与上下文事件记录，因此专用任务会话事件会重复面向模型的事实。
+授权而非不可猜测性才是访问边界，并且 id 不用于派生文件系统路径；顺序生成的品牌化 id 可保持 transcript（文本记录）易读。将前台任务提升为后台任务需要 SDK 并未规定的用户交互约定。启动、读取和通知已作为工具与上下文事件记录，因此专用任务会话事件会重复面向模型的事实。
 
 ## 测试
 
@@ -129,6 +129,6 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `Bas
 
 ## 后果
 
-bash 命令与 subagent 共享一套 id 词汇、列表、通知格式、提示词习惯和控制工具。新的长时间运行生产方只需实现执行钩子，而不必再实现一套注册表与工具族。[工具实操手册](../../../../docs/cookbook/adding-a-tool.md)将生产方指向本契约。
+bash 命令与 subagent 共享一套 id 词汇、列表、通知格式、提示词习惯和控制工具。新的长时间运行生产方只需实现执行钩子，而不必再实现一套注册表与工具族。[工具实操手册](../../../../docs/cookbook/adding-a-tool.md)将生产方指向本约定。
 
 有所属后台 bash 会随其 agent 一起停止，不再比 agent 存活更久。后台进程没有执行器超时；调用方必须终止无关工作，或依赖所有者/服务释放。流式读取只支持一个消费方，完成通知不会唤醒空闲 agent；生产方的 `cancel` 返回后如果未使 `done` 完成，仍可能阻塞资源销毁。持久任务、独立观察游标和前台提升仍属于单独设计。
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
index b038b0e02d..b8540c3319 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
 2026-06-21-bounded-llm-request-recovery.md: 587f2d26eee922e91c8797018964f983890eb8ec
-2026-06-21-bounded-llm-request-recovery.zh.md: 4efe4f946dac90f65f5b8af4a7c36037413616b6
+2026-06-21-bounded-llm-request-recovery.zh.md: dfc5e3ab67b62042c37f05199ed39bf47ded0c5d
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
index 4efe4f946d..dfc5e3ab67 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
@@ -78,11 +78,11 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 
 `@deepseek-ai/dsh-timeout` 公开一个可重新布防的空闲看门狗原语。一个稳定的局部 `AbortController` 会与调用方信号融合，并在整个适配器调用期间传给传输层；每个尚未完成的 `next()` 都会布防看门狗，该调用完成时解除布防，下一次请求数据时再重新布防。超时会使用能力自身拥有的 `TimeoutReason` 中止这个稳定控制器，`finally` 则会清除定时器。适配器将自身看门狗归类为 `TIMEOUT`，将更早发生的上游中止归类为 `ABORTED`。现有的一次性 `deadline()` 不会被描述为滑动计时器。
 
-边界测试证明两个实际传输层都能终止。手写适配器会中止其 fetch／reader，pi-ai 适配器会把稳定信号映射到 SDK，并证明 SDK 会关闭响应。如果定时器只拒绝消费方 promise，却让请求继续运行，就不满足此契约。
+边界测试证明两个实际传输层都能终止。手写适配器会中止其 fetch／reader，pi-ai 适配器会把稳定信号映射到 SDK，并证明 SDK 会关闭响应。如果定时器只拒绝消费方 promise，却让请求继续运行，就不满足此约定。
 
 ### 在现有日志中分隔尝试
 
-一次失败尝试可以在已关闭的步骤中留下 `assistant/chunk` 事件，但绝不会追加 `assistant/message`，也不会分发工具。重试会关闭失败轮次，开启下一个编号轮次，从持久表层重建请求，并生成自己的分片。步骤仍处于打开状态时，UI 可以渲染实时分片；当 `llm/retry` 标识失败步骤，或 `turn/end` 记录失败时，UI 再标记或清除这份暂时视图。Web 会验证完整的重试载荷契约，在 `llm/retry` 到达时清除失败的部分输出，将连续重试轮次的事件投影为稳定的一行，并用最新一次尝试更新该行，再从后续轮次事实派生 scheduled、started 或 cancelled 状态。倒计时以浏览器收到事件的时刻为计划延迟的起点，而不是使用 Host 事件时钟；它按向上取整且不低于 1 秒的秒数显示，仅在重试尚未结束时显示动画，并把最近一次失败的准确详情折叠在该行之后。即使失败尝试没有 assistant 节点，重试节点也会锚定自身的轨迹轮次。消息派生仍会忽略失败分片；Web 在重建历史时也会应用同一投影，因此刷新页面不会让已丢弃的部分输出重新出现，也不会生成重复的重试行。
+一次失败尝试可以在已关闭的步骤中留下 `assistant/chunk` 事件，但绝不会追加 `assistant/message`，也不会分发工具。重试会关闭失败轮次，开启下一个编号轮次，从持久表层重建请求，并生成自己的分片。步骤仍处于打开状态时，UI 可以渲染实时分片；当 `llm/retry` 标识失败步骤，或 `turn/end` 记录失败时，UI 再标记或清除这份暂时视图。Web 会验证完整的重试载荷约定，在 `llm/retry` 到达时清除失败的部分输出，将连续重试轮次的事件投影为稳定的一行，并用最新一次尝试更新该行，再从后续轮次事实派生 scheduled、started 或 cancelled 状态。倒计时以浏览器收到事件的时刻为计划延迟的起点，而不是使用 Host 事件时钟；它按向上取整且不低于 1 秒的秒数显示，仅在重试尚未结束时显示动画，并把最近一次失败的准确详情折叠在该行之后。即使失败尝试没有 assistant 节点，重试节点也会锚定自身的轨迹轮次。消息派生仍会忽略失败分片；Web 在重建历史时也会应用同一投影，因此刷新页面不会让已丢弃的部分输出重新出现，也不会生成重复的重试行。
 
 如果恢复预算耗尽，最终失败会连同结构化事实在 `turn/end.reason` 中存储一次。Web 会在该序列位置派生一个 `turn-error` 节点，并内联渲染适合展示的消息与可选错误码；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。实时事件和历史回放使用同一套折叠逻辑。如果暂时性恢复继续，`llm/retry` 就是该次尝试的失败与延迟的持久归属位置，因此该失败轮次不会再获得终态错误行。本决策不增加独立的最终错误事件或响应 id 词汇。
 
@@ -126,7 +126,7 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 - 提供方 SDK 可能隐藏状态或重试标头。适配器会保留 SDK 公开的稳定事实，否则使用粗粒度 code，而不会让恢复策略解析脆弱的文本。
 - 持久重试事件扩展了会话协议和 UI 状态机。事件与其消费方一同交付，可避免产生无人使用的遥测词汇；但以后更改 schema 仍需要同步完成持久化和回放工作。
 - 清除失败步骤的实时分片可能会明显撤回输出。与把丢弃的文本或不完整工具 JSON 呈现为已提交历史相比，这是更好的选择；快照固定这一转换。
-- 适配器局部的空闲强制机制可以终止停滞的传输，而不会计入消费方思考时间。每个传输边界的契约测试会防止 SDK 漂移。
+- 适配器局部的空闲强制机制可以终止停滞的传输，而不会计入消费方思考时间。每个传输边界的约定测试会防止 SDK 漂移。
 - 多个 normal 恢复插件会叠加各自的有限预算。always mode 会先委托，再提供无界回退；重叠的分类器仍会形成依赖注册顺序的策略，必须由引入它们的插件记录并测试。
 
 ## 相关资料
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index b3db1ae497..43c2f227df 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
 2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a
-2026-06-21-mandatory-app-attribution-headers.zh.md: a10abff8d6e2addf196bf48e2634110aa5e13b3b
+2026-06-21-mandatory-app-attribution-headers.zh.md: d2f7300467790c0a67cfa0ab6222c40c9ee10311
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index a10abff8d6..d2f7300467 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -12,15 +12,15 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 ## 调研
 
-- **OpenRouter 的机制是提供方特有的。** 其当前文档说明应用归属通过 `HTTP-Referer`（必需）、`X-OpenRouter-Title` 和 `X-OpenRouter-Categories` 来追踪；`X-Title` 仅为向后兼容而接受。其 API 参考称这些头部为可选，并说它们使应用在 OpenRouter 上可被发现。这是一份具体的 OpenRouter 契约，而非 IETF 或 OpenAI 兼容 API 标准。
+- **OpenRouter 的机制是提供方特有的。** 其当前文档说明应用归属通过 `HTTP-Referer`（必需）、`X-OpenRouter-Title` 和 `X-OpenRouter-Categories` 来追踪；`X-Title` 仅为向后兼容而接受。其 API 参考称这些头部为可选，并说它们使应用在 OpenRouter 上可被发现。这是一份具体的 OpenRouter 约定，而非 IETF 或 OpenAI 兼容 API 标准。
 - **在 agent 工具生态中，`HTTP-Referer` 是一种 OpenRouter 感知的约定，而非通用 agent 约定。** 它足够常见，以至于 OpenRouter SDK 和示例直接暴露它，面向 OpenRouter 的框架通常需要一种方式来透传它。但 ACP（Agent Client Protocol）等 agent 协议在自己的 initialize 消息中协商名称、版本和能力，而模型提供方请求仍需 HTTP 层面的身份标识。因此「在 agent 世界中被接受」意味着「被 OpenRouter 集成所识别」，而非「可跨 agent 运行时或提供方移植」。
-- **编程 agent 在 `User-Agent` 中标识产品和版本。** 公开实现在环境细节和提供方特有的附加头部上各有不同，但产品身份是共同契约；不存在通用的精确格式。
+- **编程 agent 在 `User-Agent` 中标识产品和版本。** 公开实现在环境细节和提供方特有的附加头部上各有不同，但产品身份是共同约定；不存在通用的精确格式。
 - **标准化的通用客户端身份头部是 `User-Agent`。** RFC 9110 第 10.1.5 节将 `User-Agent` 定义为用户代理软件身份，说明它用于互操作性报告和分析，并说用户代理应当在每个请求中发送它（除非被配置为不发送）。这是唯一直接对应「哪个产品在发出此 HTTP 请求」的标准头部。
 - **`Referer` 是标准的，但 OpenRouter 的 `HTTP-Referer` 不是标准字段。** RFC 9110 第 10.1.3 节将 `Referer` 定义为获取目标 URI 的来源 URI，并用大量篇幅讨论隐私限制。OpenRouter 则要求 `HTTP-Referer`，将其用作应用 URL 标识符。该名称和含义是 OpenRouter 特有的，尽管它形似标准 `Referer` 头部的 CGI 环境变量形式。
 - **`From` 是标准的，但不适合作为强制默认值。** RFC 9110 第 10.1.2 节将 `From` 定义为负责用户代理的人的电子邮件地址。机器人代理应当发送它以便服务器联系运营者，但非机器人代理出于隐私和安全策略考虑不应在未经用户显式配置的情况下发送。harness 可以后续支持运营者联系方式，但不得凭空捏造或全局强制要求。
 - **请求体中的 `user` 或 `metadata` 字段不是应用归属。** 部分模型 API 暴露稳定的终端用户标识符、请求元数据、标签或项目/账户头部。这些对滥用监控、内部计费、仪表盘或链路追踪有用，但它们要么标识的是终端用户而非产品，要么是提供方特有的 body schema，要么不保证能通过 OpenAI 兼容网关透传。它们不能替代静态的应用身份头部。
 - **SDK 遥测头部标识的是 SDK，而非应用。** 官方和第三方 SDK 常发送库/版本头部。这些帮助 SDK 维护者调试其客户端，但除非应用显式提供产品归属层，否则它们不能标识 harness 作为应用。
-- **pi-ai 有原生支持的头部钩子。** `@earendil-works/pi-ai` 的 `StreamOptions.headers` 将调用方头部最后合并（覆盖提供方默认值），因此基于库的适配器无需包装或上游改动即可满足与手写适配器相同的线路契约。mock 服务器测试套件对两个适配器都断言头部到达了线路。
+- **pi-ai 有原生支持的头部钩子。** `@earendil-works/pi-ai` 的 `StreamOptions.headers` 将调用方头部最后合并（覆盖提供方默认值），因此基于库的适配器无需包装或上游改动即可满足与手写适配器相同的线路约定。mock 服务器测试套件对两个适配器都断言头部到达了线路。
 
 ## 决策
 
@@ -41,7 +41,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 | 目标 | 映射 |
 |---|---|
 | 所有基于 HTTP 的适配器 | `User-Agent: {product}/{version} (+{url})`——括号中的 `+url` 注释符合 RFC 9110 保守的 product/comment 语法。 |
-| 直连 DeepSeek 端点 | `User-Agent`；除非 DeepSeek 文档化了等效契约，否则不发送 OpenRouter 特有头部。 |
+| 直连 DeepSeek 端点 | `User-Agent`；除非 DeepSeek 文档化了等效约定，否则不发送 OpenRouter 特有头部。 |
 | OpenRouter 端点 | 目前仅 `User-Agent`。本 Agent Note 下不发送 `HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 或 `X-OpenRouter-Categories`。 |
 | 未来提供方 | 仅 `User-Agent`，除非后续提供方特有的 Agent Note 接受额外头部。不要类比复用 `HTTP-Referer`。 |
 
@@ -51,7 +51,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 已落地的约定：
 
-- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器约定章节）。
+- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属约定（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器约定章节）。
 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。
 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。
 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。
@@ -63,7 +63,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 **现在就实现 OpenRouter 应用归属。** 本 Agent Note 否决。发送 `HTTP-Referer` 加 `X-OpenRouter-Title` 可以满足 OpenRouter 排名，但这些头部是提供方特有的产品功能，不是本 Agent Note 试图标准化的提供方无关的模型请求归属。支持它们应当是后续显式的 OpenRouter 适配器/模式决策，而非隐藏在首个共享归属辅助函数中。
 
-**向所有提供方发送 OpenRouter 头部。** 否决。这会把一份自定义的 OpenRouter 契约当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
+**向所有提供方发送 OpenRouter 头部。** 否决。这会把一份自定义的 OpenRouter 约定当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
 
 **仅使用提供方账户/项目身份。** 否决。组织/项目头部、API key、云账户和计费项目标识的是谁付费或谁拥有请求，而非哪个应用在发送流量。它们也不暴露公开的应用标题/类别，无法帮助 OpenRouter 等网关构建应用排名。
 
@@ -79,6 +79,6 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 **应用 URL 指向一个尚不存在的仓库。** `deepseek-ai/deepseek-harness-sdk` 是计划中的公开主页；在它创建之前，该 URL 是一个阻塞发布的悬空承诺。
 
-**不同客户端库的头部支持有差异。** 手写适配器直接设置头部；基于 pi-ai 的适配器依赖 pi-ai 继续尊重 `StreamOptions.headers`（最后合并覆盖提供方默认值）。线路级 mock 服务器测试是守卫：如果 pi-ai 升级后不再投递该头部，套件会变红。这对抽象施加了有益的压力：一个无法设置强制头部的提供方适配器不能完整实现 harness 的 LLM 契约。
+**不同客户端库的头部支持有差异。** 手写适配器直接设置头部；基于 pi-ai 的适配器依赖 pi-ai 继续尊重 `StreamOptions.headers`（最后合并覆盖提供方默认值）。线路级 mock 服务器测试是守卫：如果 pi-ai 升级后不再投递该头部，套件会变红。这对抽象施加了有益的压力：一个无法设置强制头部的提供方适配器不能完整实现 harness 的 LLM 约定。
 
 **OpenRouter 排名尚未受益。** `User-Agent` 是提供方无关的 HTTP 身份的正确基线，但它不会创建 OpenRouter 应用页面或排名，因为 OpenRouter 要求 `HTTP-Referer` 来实现该产品功能。这是有意为之：公开应用市场参与是一个独立的产品决策，不是强制请求归属的前提。
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
index fc370429b6..870afbe428 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
 2026-06-24-web-capability-seam.md: b705236690859961ed69b307dbb59ebefcbd65ac
-2026-06-24-web-capability-seam.zh.md: e3dc836004bf785c6811e4c4014e105266dbaade
+2026-06-24-web-capability-seam.zh.md: 987640dd5c8ee428a181ffd31d1e8e3803fe03a8
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
index e3dc836004..987640dd5c 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-harness 需要面向模型的 web 工具，但不能将模型契约绑定到某一家厂商的 API 形状上。搜索是当前的压力点：从一开始就同时支持 Exa 搜索和 Perplexity 搜索——两种刻意不同的提供方形状（Exa 返回扁平的 `results[]`，每项包含 `{title, url, highlights, publishedDate}`；Perplexity 返回一段生成式回答加引用列表）——正是用来证明归一化的 seam 并非只是镜像某一家厂商。Fetch 是另一项独立能力：匿名公开 HTTP(S) fetch 后端涉及传输、安全、重定向、解码和大小限制等关注点，与提供方支撑的搜索并不相同。
+harness 需要面向模型的 web 工具，但不能将模型约定绑定到某一家厂商的 API 形状上。搜索是当前的压力点：从一开始就同时支持 Exa 搜索和 Perplexity 搜索——两种刻意不同的提供方形状（Exa 返回扁平的 `results[]`，每项包含 `{title, url, highlights, publishedDate}`；Perplexity 返回一段生成式回答加引用列表）——正是用来证明归一化的 seam 并非只是镜像某一家厂商。Fetch 是另一项独立能力：匿名公开 HTTP(S) fetch 后端涉及传输、安全、重定向、解码和大小限制等关注点，与提供方支撑的搜索并不相同。
 
 面向模型的接口必须保持稳定，而后端可以更换。更换搜索提供方不应改变模型发起查询的方式；更换 fetch 实现不应改变模型请求 URL 的方式。反过来，提供方包也不应仅仅因为自己有额外的提供方特有旋钮就暴露自己的面向模型工具 schema。
 
-如果把搜索和 fetch 直接放进 `dsh-tool-web`，面向模型的工具就要同时承担提供方选择、后端请求映射、传输策略、结果归一化、提示词引导、展示和 schema 注册。让每个提供方注册自己的工具则有相反的问题：工具的可用性、名称、描述和参数将取决于恰好加载了哪些提供方包，提供方特有字段会泄漏到模型契约中。
+如果把搜索和 fetch 直接放进 `dsh-tool-web`，面向模型的工具就要同时承担提供方选择、后端请求映射、传输策略、结果归一化、提示词引导、展示和 schema 注册。让每个提供方注册自己的工具则有相反的问题：工具的可用性、名称、描述和参数将取决于恰好加载了哪些提供方包，提供方特有字段会泄漏到模型约定中。
 
 还有一个提供方选择的问题。现有的 `tool-bash` 和 `tool-fs` 可以依赖 Cordis 的 `inject`，因为只有一个后端服务键。Web 有两项独立能力（`search` 和 `fetch`），每项能力可能有多个提供方。`inject: ['web']` 能证明 seam 存在，但不能证明存在可用的搜索或 fetch 提供方，也无法定义多个提供方注册时谁胜出。
 
@@ -32,7 +32,7 @@ Web 访问是一个一等能力 seam，遵循[能力 seam Agent Note](2026-06-13
 - 工具绝不会仅仅因为其选定的提供方缺失、配置错误、缺少凭证、存在歧义或暂时不可用就被注销。
 - 提供方在执行时解析，当选定的能力无法运行时返回结构化的 `WebError`。
 
-这使模型 schema 保持稳定，而不将插件加载顺序、凭证状态或 HMR（热模块替换）时序纳入面向模型的契约。如果 web 搜索已启用但不存在可用的搜索提供方，`web_search` 仍然可见，执行时以结构化的 `WebError`（如 `WEB_PROVIDER_UNAVAILABLE` 或 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`）失败。如果某个提供方在 `dsh-tool-web` 之后出现，下一次执行即可使用它而无需更改 schema。如果某个提供方在调用过程中消失，执行以结构化的 `WebError` 失败，而不是静默选择另一个提供方或回退到 `UNKNOWN_TOOL`。
+这使模型 schema 保持稳定，而不将插件加载顺序、凭证状态或 HMR（热模块替换）时序纳入面向模型的约定。如果 web 搜索已启用但不存在可用的搜索提供方，`web_search` 仍然可见，执行时以结构化的 `WebError`（如 `WEB_PROVIDER_UNAVAILABLE` 或 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`）失败。如果某个提供方在 `dsh-tool-web` 之后出现，下一次执行即可使用它而无需更改 schema。如果某个提供方在调用过程中消失，执行以结构化的 `WebError` 失败，而不是静默选择另一个提供方或回退到 `UNKNOWN_TOOL`。
 
 该 seam 刻意不暴露任何观察面——没有注册表变更事件，也没有聚合的能力状态查询。不可用性是调用方通过执行观察到的事实：`search()`/`fetch()` 在调用时解析提供方，并抛出命名了失败原因的结构化 `WebError`。[观察面 Agent Note](../../archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md) 记录了这一判断：基于调用的派生选择与基于启用的注册使得没有消费方需要变更信号或独立于执行和错误路由的可用性探测；未来的提供方状态面板会重新引入它实际消费的最小信号或查询。
 
@@ -66,13 +66,13 @@ flowchart LR
   toolWeb -->|ctx.tools.register| webFetch["tool: web_fetch"]
 ```
 
-`@deepseek-ai/dsh-web` 仅依赖 Cordis 和底层 harness 支持。它声明 `ctx.web`、提供方接口、请求/结果类型、提供方可用性契约和错误码。它不导入工具、agent、会话、LLM 或提供方包。
+`@deepseek-ai/dsh-web` 仅依赖 Cordis 和底层 harness 支持。它声明 `ctx.web`、提供方接口、请求/结果类型、提供方可用性约定和错误码。它不导入工具、agent、会话、LLM 或提供方包。
 
 提供方包仅依赖 `dsh-web` 和 Cordis。它们拥有凭证、端点、协议格式映射、解析和 `WebError` 转换，使用平台 `fetch`。每个提供方注入共享服务并注册后端；只有 `dsh-web` 拥有 `ctx.web` 键。提供方私有的协议形状不会产生对 `ctx.llm` 或 Cordis HTTP 服务的依赖。
 
 `@deepseek-ai/dsh-tool-web` 依赖 `@deepseek-ai/dsh-web`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-system-prompt` 和 Cordis。它从不导入具体的提供方包。
 
-## `ctx.web` 契约
+## `ctx.web` 约定
 
 `ctx.web` 是一个提供方注册表加上一个带提供方选择的执行面。注册表部分与 `LlmService` 保持接近：每种能力类别一个 `Map<id, provider>`，`registerSearchProvider`/`registerFetchProvider` 方法返回 disposer，重复 id 抛出 `WebError`，执行时解析在选定提供方缺失或不可用时抛出异常。权威签名见 `packages/web/web/src/types.ts`；seam 的形状：
 
@@ -280,7 +280,7 @@ SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他
 
 ## 测试
 
-每一层在自己的 seam 处固定：`dsh-web` 中的注册/选择/截断/abort 契约与 `WebError` 码；每个提供方基于录制的 fixture（测试前置数据）的请求/响应映射（Perplexity fixture 包含纯 URL 引用，以保持可选 source 字段的诚实性），加上每个真实提供方的自跳过带密钥冒烟测试；`web-fetch-local` 中的真实本地 HTTP 行为；`dsh-tool-web` 中通过真实工具注册表的启用驱动注册、结构化执行错误和结果格式化。一个真实 Loader 冒烟测试守护两种导出形状（[事故复盘（postmortem） 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）：`dsh-web` 是默认导出的服务，而提供方和 `tool-web` 是命名空间插件，误加 `export default` 会丢失 `inject`。
+每一层在自己的 seam 处固定：`dsh-web` 中的注册/选择/截断/abort 约定与 `WebError` 码；每个提供方基于录制的 fixture（测试前置数据）的请求/响应映射（Perplexity fixture 包含纯 URL 引用，以保持可选 source 字段的诚实性），加上每个真实提供方的自跳过带密钥冒烟测试；`web-fetch-local` 中的真实本地 HTTP 行为；`dsh-tool-web` 中通过真实工具注册表的启用驱动注册、结构化执行错误和结果格式化。一个真实 Loader 冒烟测试守护两种导出形状（[事故复盘（postmortem） 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）：`dsh-web` 是默认导出的服务，而提供方和 `tool-web` 是命名空间插件，误加 `export default` 会丢失 `inject`。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
index 3463e0d6b1..726ab7374d 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
 2026-06-26-file-context-as-event-gate.md: 4700222aa2e0f91d9f355495c228e2eb92825f55
-2026-06-26-file-context-as-event-gate.zh.md: e0a3619859c2ab4eb99f7cbf69375f9fe40d10b7
+2026-06-26-file-context-as-event-gate.zh.md: dff5c3e9ea99e73d3d1a86c4012da1e4232021bb
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
index e0a3619859..dff5c3e9ea 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
@@ -44,7 +44,7 @@ provider      dsh-fs-local      local implementation of ctx.fs
 
 这是有意为之的。如果 `dsh-fs-policy` 在其 waterfall（瀑布式事件）处理器中 stat 并比较版本，该检查与工具实际写入之间会存在 TOCTOU 间隙——文件可能在此期间变化，因此该检查只是一个虚假保证，提供方的锁无论如何都要兜底。将版本检查放在提供方的临界区中既无竞态又无额外 `stat`。所以 `dsh-fs-policy` **不做**任何文件系统 I/O；「必须基于最近一次读取」的保证由 CAS *实现*，`dsh-fs-policy` 只负责选择基准（`vObserved`）并对先前观测进行门控。
 
-## 提供方契约变更：版本守卫变为可选
+## 提供方约定变更：版本守卫变为可选
 
 为使裸提供方不受约束，其两个 mutation 上的版本守卫变为**可选**——传入则守卫，省略则无条件执行：
 
@@ -66,7 +66,7 @@ editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion
 
 ## 事件词汇（由 `dsh-fs` 拥有）
 
-事件定义在 `@deepseek-ai/dsh-fs` 中，而非 `dsh-fs-policy` 中。这是解耦契约所迫：`dsh-tool-fs` 是发射方，因此它必须引用事件类型，且即使 `dsh-fs-policy` 不再提供方法服务，它也必须能编译通过。`dsh-fs` 是 `dsh-tool-fs` 和 `dsh-fs-policy` 都已依赖的包，因此它是唯一能让发射方和策略监听方共享词汇而不让发射方依赖策略插件的归属地。
+事件定义在 `@deepseek-ai/dsh-fs` 中，而非 `dsh-fs-policy` 中。这是解耦约定所迫：`dsh-tool-fs` 是发射方，因此它必须引用事件类型，且即使 `dsh-fs-policy` 不再提供方法服务，它也必须能编译通过。`dsh-fs` 是 `dsh-tool-fs` 和 `dsh-fs-policy` 都已依赖的包，因此它是唯一能让发射方和策略监听方共享词汇而不让发射方依赖策略插件的归属地。
 
 这些事件携带既有的 `dsh-fs` 词汇（`FsTarget`、`FsVersion`、`FsWriteIntent`）加一个不透明的 actor——不携带面向模型的概念（行窗口、行号或渲染后的页脚不会泄漏到此层）。
 
@@ -108,7 +108,7 @@ interface Events {
 
 `fs/*` 决策事件是**由工具分发的无绑定 waterfall**（类似 `agent/request`，由循环分发且无 `this`），而非服务绑定的 waterfall（如 `llm/stream`）。分发者是 `dsh-tool-fs` 插件，它不是一个服务。
 
-## 工具契约（`dsh-tool-fs`）
+## 工具约定（`dsh-tool-fs`）
 
 工具保留其面向模型的 schema（`read`/`write`/`edit`，逐字节不变）和提示词段落。提示词引导仍以策略优先，因为加载 fs 工具的部署预期也会加载 `dsh-fs-policy`：模型仍被告知在覆写或编辑前先读取，任何声称「后端」要求如此的措辞应修正为 fs-policy 插件要求如此。裸提供方回退不改变提示词立场。
 
@@ -124,9 +124,9 @@ interface Events {
 
 工具在每次分发时将 `exec`（工具执行上下文）作为 `actor` 参数传入，以便 `dsh-fs-policy` 推导其观测状态的 owner。工具不知道策略插件是否存在：它始终在 `next` thunk 中提供裸默认行为，而 `dsh-fs-policy` 在默认部署中会在 thunk 运行前短路它。
 
-**`fs/observed` 在操作成功后触发。** 其监听器必须是同步、不抛异常的记录器；工具不对 plain emit 做保护，因此抛异常的监听器会在 mutation 已成功后报告失败。异步或可失败的观测需要另一份事件契约。
+**`fs/observed` 在操作成功后触发。** 其监听器必须是同步、不抛异常的记录器；工具不对 plain emit 做保护，因此抛异常的监听器会在 mutation 已成功后报告失败。异步或可失败的观测需要另一份事件约定。
 
-## 策略插件契约（`dsh-fs-policy`）
+## 策略插件约定（`dsh-fs-policy`）
 
 `dsh-fs-policy` 是插件，不是服务。它不注册 `ctx.fileContext`，没有公开方法面，不暴露 `read`/`write`/`edit`/`resolve` 方法。它通过 `ctx.on()` 注册三个监听器（每个返回一个 disposer 用于 HMR）。它维护观测状态 `WeakMap<owner, Map<targetKey, { version }>>`，以及结构化的 owner 推导（将事件中不透明的 `object` actor 收窄为自己的 `{ agent?: { session? } }` 形状），但不注入 `fs`——每个处理器只操作自己的 `WeakMap`，从不操作 `ctx.fs`。
 
@@ -150,7 +150,7 @@ interface Events {
 
 ## 取代关系
 
-本 Agent Note 修正——而非推翻——[拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md)。四层拆分、提供方契约和新鲜度*策略*均保留。变更的是**工具与策略层之间的耦合方式**：强制性方法服务变为插件拥有的事件门控，fs I/O + 读取窗口从 `fileContext` 上移至 `dsh-tool-fs`。拆分文件系统 seam Agent Note 中关于 `dsh-tool-fs` 注入 `fileContext` 以及 `fileContext` 拥有 `read`/`write`/`edit` 的描述已在同一变更中更新。
+本 Agent Note 修正——而非推翻——[拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md)。四层拆分、提供方约定和新鲜度*策略*均保留。变更的是**工具与策略层之间的耦合方式**：强制性方法服务变为插件拥有的事件门控，fs I/O + 读取窗口从 `fileContext` 上移至 `dsh-tool-fs`。拆分文件系统 seam Agent Note 中关于 `dsh-tool-fs` 注入 `fileContext` 以及 `fileContext` 拥有 `read`/`write`/`edit` 的描述已在同一变更中更新。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml
index 072823d0dc..d467684e40 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md
 2026-07-02-tool-render-intent-union.md: 67607b2848305439513503d7e03ad5e2a2e4020a
-2026-07-02-tool-render-intent-union.zh.md: 9cbab75ce87f6d313ca4b6ac8dda043733361f0d
+2026-07-02-tool-render-intent-union.zh.md: f69442cc1cf226a5dd949fc3890029a69a639953
diff --git a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md
index 9cbab75ce8..f69442cc1c 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md
@@ -63,7 +63,7 @@ terminal 意图只用于展示。harness 仍通过自身的 bash 服务执行命
 ## 曾考虑的替代方案
 
 - **完全删除工具自有的展示**：即本 Agent Note 所取代的那个被否决的 collapse 提案；其自身的结论正是推迟到两个真实工具和两个真实消费方存在后再做此联合类型，该条件现已满足。
-- **让 UI 执行 terminal 意图**：否决。这样会绕过 harness 的 bash 策略与归属契约，并把命令执行分裂到不同后端。terminal 卡片描述的是 harness 拥有的执行，绝不授权客户端侧执行。
+- **让 UI 执行 terminal 意图**：否决。这样会绕过 harness 的 bash 策略与归属约定，并把命令执行分裂到不同后端。terminal 卡片描述的是 harness 拥有的执行，绝不授权客户端侧执行。
 - **可合并扩展的联合类型**（`ContentBlockMap` 模式）：否决。新的渲染意图无论如何需要新的 bridge 代码来渲染，因此一个被 bridge 静默丢弃的插件添加变体，比封闭联合类型在 bridge 的 `assertNever` switch 处引发的编译错误更糟糕。
 - **保留可选字段集合**：即「问题」一节所剖析的现状：无效状态可表达、字段交互无文档、且完全无法请求 diff 卡片。
 
@@ -78,5 +78,5 @@ terminal 意图只用于展示。harness 仍通过自身的 bash 服务执行命
 ## 相关
 
 - 取代早先被否决的折叠工具自有呈现提案（已否决——「等两个真实工具和两个真实消费方，然后做带标签 render-intent 联合类型」）中的推迟决定。该条件现已满足；本 Agent Note 即为那个联合类型。
-- 被[结果时已应用 hunk 差异](../../archived/architecture/2026-07-02-result-time-applied-hunk-diffs.md)（已归档）扩展：后者添加了一个持久化的 `meta` 通道，使 write/edit 在结果时输出 `DiffResultView`（应用后的变更：带上下文行的 contextual hunk / 每个 `replace_all` 位点一个，或创建时的整文件 diff）——值/呈现拆分与持久化的 `presentationMeta` 通道现由[规范工具输出契约](2026-07-20-canonical-tool-output-contract.md)拥有。
+- 被[结果时已应用 hunk 差异](../../archived/architecture/2026-07-02-result-time-applied-hunk-diffs.md)（已归档）扩展：后者添加了一个持久化的 `meta` 通道，使 write/edit 在结果时输出 `DiffResultView`（应用后的变更：带上下文行的 contextual hunk / 每个 `replace_all` 位点一个，或创建时的整文件 diff）——值/呈现拆分与持久化的 `presentationMeta` 通道现由[规范工具输出约定](2026-07-20-canonical-tool-output-contract.md)拥有。
 - 将 `ToolTerminal` 折入当前 UI 传输层使用的带标签 `terminal` 视图。
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
index 26354042d7..f80e5c3c77 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
 2026-07-05-prompt-variables-and-tool-guidance-ownership.md: a3b5021daf323971308760bde4f97651db8edbda
-2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 490d41302ea4f4e14e11e301acbf47170f95cace
+2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 0b84f188e6637d8b1b42ed2e6df3cd7e4061d75d
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
index 490d41302e..0b84f188e6 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
@@ -36,7 +36,7 @@ Status: implemented
 
 ### 工具指导归属
 
-每个工具的语义和选择指导放在工具 description 中。提示词 section 只承载跨调用习惯，例如检查 bash 退出标记或优先使用文件系统工具而非 shell 命令。`todo_write` 和 subagent 工具不需要 section，因为它们的 description 包含完整契约。部署 persona 只包含角色和行为。
+每个工具的语义和选择指导放在工具 description 中。提示词 section 只承载跨调用习惯，例如检查 bash 退出标记或优先使用文件系统工具而非 shell 命令。`todo_write` 和 subagent 工具不需要 section，因为它们的 description 包含完整约定。部署 persona 只包含角色和行为。
 
 ### Subagent 对话历史描述符
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml
index 46aebedb0a..951017ba47 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md
 2026-07-05-windows-jsonl-durable-publish.md: 38c4adc7a4f85d45e53e70fcac84073ab4e50775
-2026-07-05-windows-jsonl-durable-publish.zh.md: 3a91b7dab0751ad1b7ac1a425371ccf62d23e89c
+2026-07-05-windows-jsonl-durable-publish.zh.md: 205460bcd374bd351cfdf541eb4041c09461229d
diff --git a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.zh.md b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.zh.md
index 3a91b7dab0..205460bcd3 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.zh.md
@@ -6,9 +6,9 @@ Status: implemented
 
 ## 问题
 
-`dsh-session-persistence-jsonl` 在首次追加时延迟发布会话日志。POSIX 协议会写入临时文件，对其执行 fsync，将其链接至最终名称，对父目录执行 fsync，然后移除临时链接。对父目录执行 fsync 是持久性契约的一部分：命名空间变更后发生崩溃时，已经提交的最终名称不能丢失，否则调用方会误以为会话日志已经物化。
+`dsh-session-persistence-jsonl` 在首次追加时延迟发布会话日志。POSIX 协议会写入临时文件，对其执行 fsync，将其链接至最终名称，对父目录执行 fsync，然后移除临时链接。对父目录执行 fsync 是持久性约定的一部分：命名空间变更后发生崩溃时，已经提交的最终名称不能丢失，否则调用方会误以为会话日志已经物化。
 
-Windows 具备原子命名空间操作，但 Node 没有暴露与 POSIX 等价的父目录 fsync 契约。如果把 Windows 目录同步失败视为成功，就会在无提示的情况下削弱持久化后端。因此，Windows 路径需要采用不同的发布原语，而不是在 POSIX 的 `syncDir` 辅助函数中添加条件分支。
+Windows 具备原子命名空间操作，但 Node 没有暴露与 POSIX 等价的父目录 fsync 约定。如果把 Windows 目录同步失败视为成功，就会在无提示的情况下削弱持久化后端。因此，Windows 路径需要采用不同的发布原语，而不是在 POSIX 的 `syncDir` 辅助函数中添加条件分支。
 
 ## 决策
 
@@ -28,8 +28,8 @@ Windows 通过持久的暂存发布来创建缺失目录：创建一个以固定
 
 ## 影响
 
-该后端在各平台上维持同一项外部契约：首次追加要么把完整日志发布到最终名称，要么失败且不覆盖已有日志。平台分流只是实现细节；`SessionPersistence` API 和 JSONL 逻辑记录格式均不改变。后续的 [Zstandard 编码决策](2026-07-19-zstandard-jsonl-session-logs.md)会先作用于不透明字节，然后才由任一平台执行发布。
+该后端在各平台上维持同一项外部约定：首次追加要么把完整日志发布到最终名称，要么失败且不覆盖已有日志。平台分流只是实现细节；`SessionPersistence` API 和 JSONL 逻辑记录格式均不改变。后续的 [Zstandard 编码决策](2026-07-19-zstandard-jsonl-session-logs.md)会先作用于不透明字节，然后才由任一平台执行发布。
 
-Windows 测试会在原生 Windows 上执行真实的 Win32 发布路径。断电行为属于 API 契约属性，单元测试无法证明；可测试的不变量包括：Windows 物化不会调用目录 fsync、最终路径冲突会失败、达到最大长度的目标路径组件仍可物化、临时日志在发布前已经执行 fsync，并且生成的日志可以正常加载。
+Windows 测试会在原生 Windows 上执行真实的 Win32 发布路径。断电行为属于 API 约定属性，单元测试无法证明；可测试的不变量包括：Windows 物化不会调用目录 fsync、最终路径冲突会失败、达到最大长度的目标路径组件仍可物化、临时日志在发布前已经执行 fsync，并且生成的日志可以正常加载。
 
 两个平台的追加和修复仍使用普通文件句柄 fsync。追加失败后，系统会关闭仅追加句柄，以读写模式重新打开日志，将文件截断到追加前的大小，并对回滚结果执行 fsync，因为 Windows 不允许在仅追加句柄上调用 `ftruncate`。
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
index c43bfd8960..24a047b540 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
 2026-07-06-timeout-deadline-library.md: 63463a76a65743436d4e78479800c19e257a42de
-2026-07-06-timeout-deadline-library.zh.md: 16f1a7eba902e6d7b3e2f730cb5df702a37bd429
+2026-07-06-timeout-deadline-library.zh.md: c47e6d4e6ed0bec368fca8857e5bd4d7229b6b0e
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
index 16f1a7eba9..c47e6d4e6e 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
@@ -77,7 +77,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 
 | 关注点 | 负责方 |
 |---|---|
-| 校验请求提示并钳位默认值/最大值 | `dsh-timeout`（`clampTimeout`）：纯算术加共享的正有限请求契约 |
+| 校验请求提示并钳位默认值/最大值 | `dsh-timeout`（`clampTimeout`）：纯算术加共享的正有限请求约定 |
 | 启动一次性定时器、到期中止、携带 reason、与上游取消融合 | `dsh-timeout`（`deadline`） |
 | 仅围绕未结算的迭代器 demand 启动和重启 | `dsh-timeout`（`idleWatchdog`） |
 | 清除定时器 | `dsh-timeout`（任一原语的 `[Symbol.dispose]`） |
@@ -90,7 +90,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 
 ### 各能力如何消费该库
 
-- **web_fetch**：工具层保持校验并转发；提供方手写的 controller + `setTimeout` + 手动监听器 + `finally` + `signal.reason` 恢复被替换为提供方自有的 `deadline`/`timeoutOf`。已预先中止的上游信号仍然立即抛出 `WEB_ABORTED`；否则 `fetch` 使用融合后的 `d.signal` 运行，`translateAbortOrNetwork` 根据信号分类抛出的错误（`timeoutOf` → `WEB_FETCH_TIMEOUT`，否则已中止 → `WEB_ABORTED`，否则网络错误 → `WEB_PROVIDER_ERROR`）。公开的错误码契约不变，`TimeoutReason` 永远不会作为公开错误跨越 web seam。
+- **web_fetch**：工具层保持校验并转发；提供方手写的 controller + `setTimeout` + 手动监听器 + `finally` + `signal.reason` 恢复被替换为提供方自有的 `deadline`/`timeoutOf`。已预先中止的上游信号仍然立即抛出 `WEB_ABORTED`；否则 `fetch` 使用融合后的 `d.signal` 运行，`translateAbortOrNetwork` 根据信号分类抛出的错误（`timeoutOf` → `WEB_FETCH_TIMEOUT`，否则已中止 → `WEB_ABORTED`，否则网络错误 → `WEB_PROVIDER_ERROR`）。公开的错误码约定不变，`TimeoutReason` 永远不会作为公开错误跨越 web seam。
 - **bash**：`resolve()` 将请求钳位为显式规格。前台 `run()` 创建 deadline 并将其信号传给进程执行，后者既有的 abort 监听器执行进程组 kill。执行器将首个 abort 分类为超时或取消。后台启动保持无超时，仅转发上游取消。
 - **LLM（大语言模型）适配器**：`dsh-llm-deepseek` 和 `dsh-llm-pi-ai` 用 `idleWatchdog` 包装实际的传输迭代。配置的五分钟间隔只覆盖尚未结算的提供方 demand，不包括下游消费方在分片之间花费的时间。稳定信号在整个调用期间传给 `fetch` 或 SDK，因此超时会关闭底层请求并映射为 `TIMEOUT`，而更早的调用方中止映射为 `ABORTED`。
 
@@ -100,7 +100,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 - `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。这是与字面提案形状（向 `runBash` 传入 `timeoutMs: 0`）的唯一偏差；一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
 - web_fetch 去除了其定制的 controller/timer/listener/reason-recovery；分类器现在基于 deadline 信号（`timeoutOf` + `aborted`）而非抛出错误的形状来判断，这在请求阶段的 reject-with-reason 和读取阶段的裸 `AbortError` 两种情况下都是健壮的。
 - `AbortSignal.any` 和 `using`/`Symbol.dispose` 在此首次进入本仓库（Node ≥ 24 基线，已满足）。
-- 模型流现在共享一个可重启的定时器契约，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
+- 模型流现在共享一个可重启的定时器约定，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
 
 以下内容不在本次范围内，列出以标明边界：`web_search` 可以在其工具 schema 和快照覆盖规划完成后获得可选的面向模型的 `timeout_ms`；未来基于 ripgrep 的文件系统发现工具可以在实现后消费同样的提供方自有 deadline 形状；`tools/execute` waterfall（瀑布式事件）中间件可以通过驱动 `exec.signal` 为每次工具调用设置默认 deadline——那将是一个*消费*本库的插件，仍然只做通知，硬终止仍是各能力自己的事。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml
index 17381d7269..29c7c13813 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.md
 2026-07-06-tool-result-retention-library.md: 5e42660360e5a23b419c75b9c8006bec459bc322
-2026-07-06-tool-result-retention-library.zh.md: 422c301ba5f1aab33a54e1deffe42f390bcb662d
+2026-07-06-tool-result-retention-library.zh.md: 2a523e2eff36daf9100ac10bf5ae569eca30f830
diff --git a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.zh.md
index 422c301ba5..2a523e2eff 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-tool-result-retention-library.zh.md
@@ -95,7 +95,7 @@ type TextRetentionStrategy =
 
 ### 工具映射
 
-`read` 被有意排除在 v1 保留库之外。它的 `read-render` 辅助函数拥有文件专用的分页契约：`offset`／`limit`、行号、`totalLines`、offset 越界错误、逐行预览截断，以及能够在窗口中途停止扫描的所选输出字节上限。这是行窗口渲染器，不是通用保留原语。它未来可以共享中性的提示辅助函数，但不应把已经选定的窗口再传入 `ItemRetainer`。
+`read` 被有意排除在 v1 保留库之外。它的 `read-render` 辅助函数拥有文件专用的分页约定：`offset`／`limit`、行号、`totalLines`、offset 越界错误、逐行预览截断，以及能够在窗口中途停止扫描的所选输出字节上限。这是行窗口渲染器，不是通用保留原语。它未来可以共享中性的提示辅助函数，但不应把已经选定的窗口再传入 `ItemRetainer`。
 
 下文的 `FsGlobEntry` 与 `FlatGrepMatch` 是预期由发现工具使用的条目形态，不是现有保留库的导出。`FsGlobEntry` 是一个由后端派生的路径；`FlatGrepMatch` 是后端将保留匹配项按文件分组之前的一条未分组 grep 匹配。
 
@@ -138,7 +138,7 @@ const formatGrepNotice = (notice: RetentionNotice): string =>
 
 **已交付内容。** `@deepseek-ai/dsh-retention` 导出 `ItemRetainer`、`TextRetainer`、结果类型（`RetainedItems`、`RetainedText`）、策略类型（`ItemRetentionStrategy`、`TextRetentionStrategy`）、`Omitted`、`PushDecision`、`RetentionNotice`，以及中性的提示辅助函数 `describeOmitted`／`formatRetentionNotice`，且不依赖 Cordis 或任何工具包。单元测试覆盖具有精确省略计数的条目头部保留、文本头部保留、文本尾部保留、首尾字节保留、零预算、UTF-8 边界处理（2、3、4 字节码位，以及每个裁切位置上的无效起始字节）和未知省略量的措辞。
 
-**已记录但尚未迁移的内容。** `glob`、`grep`、`bash`、`web_fetch` 与 `web_search` 的映射已记录在[包 README](../../../../packages/util/retention/README.md) 中，但本次改动并未把每个工具都迁移到该库；迁移工作刻意留作独立的后续任务。`read` 被明确记录为不在范围内：其 `read-render` 行窗口契约（`offset`／`limit`、`totalLines`、offset 范围错误、逐行预览截断，以及针对所选窗口的字节上限）不属于通用保留，而一个 `Omitted` 计数也无法同时表达行窗口两侧。
+**已记录但尚未迁移的内容。** `glob`、`grep`、`bash`、`web_fetch` 与 `web_search` 的映射已记录在[包 README](../../../../packages/util/retention/README.md) 中，但本次改动并未把每个工具都迁移到该库；迁移工作刻意留作独立的后续任务。`read` 被明确记录为不在范围内：其 `read-render` 行窗口约定（`offset`／`limit`、`totalLines`、offset 范围错误、逐行预览截断，以及针对所选窗口的字节上限）不属于通用保留，而一个 `Omitted` 计数也无法同时表达行窗口两侧。
 
 **该库维持的边界。** `truncated` 表示 retainer 因预算省略了原本可用的内容，绝不表示上游不完整。工具专用状态，包括 `incomplete`、权限失败、提供方局部失败、跳过二进制文件、bash 落盘路径恢复和无效 UTF-8，均留在工具领域字段中、位于 retainer 之外。未来改动迁移某项工具时，该包的 README 与测试必须证明，除了有意改变的提示措辞外，模型可见的结果文本没有变化。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
index e400692950..6e7aa8291a 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
 2026-07-07-tool-call-timeout-policy.md: b85a4d2d60ef60d9f75bd47d4d405aa55c132af6
-2026-07-07-tool-call-timeout-policy.zh.md: e67b9e4223f486208061f3944369cf3ec06fe72d
+2026-07-07-tool-call-timeout-policy.zh.md: f6a85c13a66689c48b10f160890ce3825125aec1
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
index e67b9e4223..f6a85c13a6 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
@@ -52,7 +52,7 @@ catch 是基础 `next`（而非 waterfall 之外的东西）这一点至关重
     searchTimeoutMs: 30000
 ```
 
-超时放在工具定义上而非自由文本名称映射中，消除了拼错名称导致策略不生效的问题。`defineTool` 校验预算为正有限数。分发期间，执行器派生截止信号并将其赋给 `exec.signal`；注册表依据[工具取消契约](2026-07-19-cooperative-tool-cancellation.md)，在执行工具体之前将该截止信号与调用方的原始信号融合。执行器随后恢复调用方信号，并将自身的超时转换为 `TOOL_TIMEOUT`；没有预算的工具原样通过。
+超时放在工具定义上而非自由文本名称映射中，消除了拼错名称导致策略不生效的问题。`defineTool` 校验预算为正有限数。分发期间，执行器派生截止信号并将其赋给 `exec.signal`；注册表依据[工具取消约定](2026-07-19-cooperative-tool-cancellation.md)，在执行工具体之前将该截止信号与调用方的原始信号融合。执行器随后恢复调用方信号，并将自身的超时转换为 `TOOL_TIMEOUT`；没有预算的工具原样通过。
 
 信号替换采用**就地修改 `exec.signal`** 的方式，而非向 `next()` 传递新对象。Cordis 的 waterfall `next()` 忽略传入的任何参数，并以共享的 payload 数组重新调用下游监听器（`vendor/cordis/src/events.ts`），因此修改共享对象是包装器向注册表提供截止信号的方式。注册表会在进入工具体前再次融合已捕获的调用方信号；插件则在 `finally` 中将 `exec.signal` 恢复为调用方的原始值，使 `tools/post-execute` 永远不会看到本插件的截止信号。
 
@@ -71,7 +71,7 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 }
 ```
 
-这是一个协作式截止。它不会通过竞争工具 promise 来杀死任意工作；工具或其调用的能力必须遵循 `exec.signal` 并达到完全停稳。因此声明 `timeoutMs` 意味着「此工具与 `exec.signal` 协作」，插件 README 将此作为其契约。
+这是一个协作式截止。它不会通过竞争工具 promise 来杀死任意工作；工具或其调用的能力必须遵循 `exec.signal` 并达到完全停稳。因此声明 `timeoutMs` 意味着「此工具与 `exec.signal` 协作」，插件 README 将此作为其约定。
 
 无需新的会话事件来保证可重建性：`TOOL_TIMEOUT` 是该调用的最终面向模型的 `tool/result`，因此现有会话日志已经记录了下一次模型请求所见的内容和结构化 `{ name, code }` 错误。
 
@@ -107,8 +107,8 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 
 ## 后果
 
-- `@deepseek-ai/dsh-tools` 在有意拆分 pre/post 工具钩子的拦截 seam 之后，获得了一个环绕分发接口。其契约是狭窄的——包装注册表分发，而非替代 pre 门禁或 post 结果策略——且基础 `next()` 是带规范化的分发，因此包装器永远不会看到未经处理的工具异常。
+- `@deepseek-ai/dsh-tools` 在有意拆分 pre/post 工具钩子的拦截 seam 之后，获得了一个环绕分发接口。其约定是狭窄的——包装注册表分发，而非替代 pre 门禁或 post 结果策略——且基础 `next()` 是带规范化的分发，因此包装器永远不会看到未经处理的工具异常。
 - 多个 `tools/execute` 监听器按普通 Cordis waterfall 顺序组合：调用 `next()` 的监听器包装下游监听器加分发；不调用 `next()` 直接返回的监听器短路它们。一个同时组合超时与未来重试/沙箱/指标包装器的部署通过注册顺序选择语义（「超时覆盖整个重试」vs「超时覆盖每次尝试」）。
-- 按声明加入是一个有意的误配置风险：工具可以声明 `timeoutMs` 但不遵循 `exec.signal`，这样的工具在超时时不会停止。注册表会等待这个尚未完全停稳的工具体结束，而不是与它竞速；同时插件契约声明：声明预算意味着协作；web 工具在已转发信号的工具上验证了这一模式。
+- 按声明加入是一个有意的误配置风险：工具可以声明 `timeoutMs` 但不遵循 `exec.signal`，这样的工具在超时时不会停止。注册表会等待这个尚未完全停稳的工具体结束，而不是与它竞速；同时插件约定声明：声明预算意味着协作；web 工具在已转发信号的工具上验证了这一模式。
 - 过渡期间 `bash` 和已迁移的 web 工具有意使用不同的超时路径：`TOOL_TIMEOUT` 是面向模型的工具调用预算，而 `BASH_TIMEOUT` 仍是 bash 和钩子使用的 bash 后端超时。
 - 与字面提案的偏差，按 implemented-Agent Note 规则记录：插件包为 `@deepseek-ai/dsh-timeout-policy`（而非 `tool-timeout`）；信号替换是在 `next()` 之前就地修改 `exec.signal`（而非 `next({ ...exec, signal })`，Cordis 会忽略后者）；逐工具预算声明在 `ToolDefinition` 上（`timeoutMs`，由拥有该工具的插件从其配置中设置），而非在本插件配置中按工具名映射——因此执行器是零配置的，拼错工具名不可能发生。以上三点均在上文 `## Decision` 中描述。
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
index 215f612f5e..8f9fb5e270 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md
 2026-07-08-agent-scope-contexts.md: eb3f6f247bac1a1d81aa2644132c7b9cc04d602c
-2026-07-08-agent-scope-contexts.zh.md: 673dd8578bf545b1f14f3b7e7b89874d804e4ae9
+2026-07-08-agent-scope-contexts.zh.md: a6dcd421cb2e8a64cdbe6393253355ad8554303e
diff --git a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
index 673dd8578b..a6dcd421cb 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 Cordis 是 SDK 底层的插件框架。Cordis **上下文**是插件用来访问服务和注册效果的对象，效果的清理跟随该上下文。[Cordis 入门](../../../../docs/cordis-primer.md)对该框架有更详细的说明。
 
-对大多数贡献者而言，完整契约是四条规则：
+对大多数贡献者而言，完整约定是四条规则：
 
 | 问题 | 规则 |
 |---|---|
@@ -56,7 +56,7 @@ flowchart LR
 | 普通插件上下文 | 每个符合条件的 agent 视图 | 注册插件 |
 | `agent.ctx` | 仅该 agent 的视图 | agent 作用域 |
 
-工具、提示词段落与变量、工具限制、守卫以及作用域事件监听器都遵循此契约。命名的本地值通常对该 agent 遮蔽同名全局值；各所属服务文档会说明例外与合并行为。
+工具、提示词段落与变量、工具限制、守卫以及作用域事件监听器都遵循此约定。命名的本地值通常对该 agent 遮蔽同名全局值；各所属服务文档会说明例外与合并行为。
 
 普通贡献者的模式是在 agent setup 期间注册完整的本地世界：
 
@@ -88,7 +88,7 @@ await handle.dispose()
 ctx.tools.get('review_summary', handle.agent)  // undefined: scope is gone
 ```
 
-setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插件和服务。其契约仅限组合：不支持通过 cast 或内部注册表调用来驱动或发布正在构建中的 agent。
+setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插件和服务。其约定仅限组合：不支持通过 cast 或内部注册表调用来驱动或发布正在构建中的 agent。
 
 ### 操作选择视图
 
@@ -96,7 +96,7 @@ setup 接收一个完整的受信 Cordis 上下文，因此可以组合普通插
 
 工具查找与执行接收其所服务的 agent。提示词组装接收正在构建请求的 agent 的组装上下文。事件分发接收其领域主体。这使共享服务实例可在多个 agent 间复用，同时让每个操作的视图保持显式。
 
-只有采纳了作用域契约的服务才会解析 agent 层。`agent.ctx` 不会自动改变任意 Cordis 服务调用的行为。
+只有采纳了作用域约定的服务才会解析 agent 层。`agent.ctx` 不会自动改变任意 Cordis 服务调用的行为。
 
 ### 作用域事件将路由与事件数据分离
 
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
index 2145468f1f..dbac0c0688 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
 2026-07-08-tool-output-spill-files.md: 7c0ca90452645d251559be25108d12883210d00e
-2026-07-08-tool-output-spill-files.zh.md: a1bde1131374cd11215006b822dfc19aea707747
+2026-07-08-tool-output-spill-files.zh.md: 628023a9d12fec17d32749f9d17a3b701ca3a475
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
index a1bde11313..628023a9d1 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 这项改动之前的行为并不一致。`dsh-bash-local` 已经会在内存尾部溢出时，把完整 stdout／stderr 流写入私有的临时落盘文件；普通文本工具结果则仍以内联形式返回，除非工具自行实现上限。[工具结果保留库](2026-07-06-tool-result-retention-library.md)负责预览机制，但不负责存储，也不负责把这些机制应用于最终工具结果的执行流水线策略。
 
-其形态与超时策略设计一致：工具作者声明规范值与 Native renderer（原生渲染器），由策略插件在渲染后的内容上执行部署默认的上下文预算。工具仍可在提供方采集上限处提前落盘；由工具负责的展示落盘可以保留已完整采集的规范值，而只替换展示内容。[规范工具输出契约](2026-07-20-canonical-tool-output-contract.md)规定了这项区分。
+其形态与超时策略设计一致：工具作者声明规范值与 Native renderer（原生渲染器），由策略插件在渲染后的内容上执行部署默认的上下文预算。工具仍可在提供方采集上限处提前落盘；由工具负责的展示落盘可以保留已完整采集的规范值，而只替换展示内容。[规范工具输出约定](2026-07-20-canonical-tool-output-contract.md)规定了这项区分。
 
 ## 决策
 
@@ -164,7 +164,7 @@ ctx.tools.register(defineTool({
 
 ## 测试
 
-- `dsh-spill` 单元测试锁定 seam 契约：注册为 `ctx.spillStore`、每个上下文只允许一种实现，并在 dispose（资源释放）时释放。
+- `dsh-spill` 单元测试锁定 seam 约定：注册为 `ctx.spillStore`、每个上下文只允许一种实现，并在 dispose（资源释放）时释放。
 - `dsh-spill-local` 单元测试覆盖 `saveText`、`encodeSegment` 清理（分隔符／波浪号／完整路径段的点／空值）、会话哈希目录、仅所有者权限、每次保存生成不同路径、配置根目录／私有根目录，以及存储失败时的拒绝。
 - `dsh-spill-policy` 单元测试通过 `ctx.tools.execute` 驱动真实工具：禁用模式下无操作、替换超大文本、小结果／非文本结果保持不变、跳过 `read`、尽力回退（保存失败／无后端／无所有者），以及下游组合（限制已替换结果、保留 `additionalContexts`）。
 - `dsh-tool-web` 集成测试驱动 `web_fetch`，其实际执行路径经过 `ctx.tools.execute`，并使用真实的 `spill-local` 后端与策略；测试证明只有刻意加入的落盘提示会改变模型可见文本，而落盘文件保存完整的格式化结果。
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index dbdc4347f6..380171ab17 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
 2026-07-12-agent-scope-runtime-design.md: b93c291957fab98ab9d0d04eb816bb01a15a0b51
-2026-07-12-agent-scope-runtime-design.zh.md: 8b1332c23ce3b6c0332fcde40b4f4ac8dd20aa45
+2026-07-12-agent-scope-runtime-design.zh.md: e0c01f31eb2664608139f95dc60025a5b33e4618
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
index 8b1332c23c..e0c01f31eb 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-[agent 作用域契约](2026-07-08-agent-scope-contexts.md)对贡献者而言很简单：通过 `agent.ctx` 注册，解析出一个全局加单 agent 的视图，仅在 setup 完成后发布，并保持作用域直到工作停止。运行时必须在协作式插件框架、异步创建、可重入监听器、持久化会话提交以及 worker 或进程故障等场景下维护这份契约。
+[agent 作用域约定](2026-07-08-agent-scope-contexts.md)对贡献者而言很简单：通过 `agent.ctx` 注册，解析出一个全局加单 agent 的视图，仅在 setup 完成后发布，并保持作用域直到工作停止。运行时必须在协作式插件框架、异步创建、可重入监听器、持久化会话提交以及 worker 或进程故障等场景下维护这份约定。
 
 主要的设计风险是为每个竞态条件引入第二套机制。独立的预留、就绪哨兵、取消中继、快照层和保护注册表可能镜像同一个事实，直到没有读者能分辨哪个才是权威的。这些机制还会诱使运行时把可信的类型化调用当作敌对的序列化边界来处理。
 
@@ -24,13 +24,13 @@ Status: implemented
 | 拥有一个活跃的 agent 或会话 | 由其 disposer 捕获的单条注册表条目 |
 | 协调创建/恢复 | 单个 `AgentCreationTransaction` |
 | 保护持久化、队列、模型或协议格式数据 | 在该边界处一次性物化 |
-| 在同一进程内传递类型化值 | Readonly 借用契约 |
+| 在同一进程内传递类型化值 | Readonly 借用约定 |
 | 组合模型可见的提示词与工具表面 | 单个共享工具视图加权威的 assembly-waterfall 结果 |
 | 协调 subagent、worker 和进程关闭 | 单个取消信号加该边界独立的终止态/完全停稳态事实 |
 
 本 Agent Note 余下部分按依赖顺序展开这些选择：Cordis 机制、作用域路由、创建与会话提交、工具与提示词、subagent 与工作流，最后是可执行检查。
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md)仍然是贡献者契约。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md)仍然是贡献者约定。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
 
 ## Cordis 模型：上下文、fiber、effect、receiver 与 waterfall
 
@@ -104,7 +104,7 @@ detach 闭包捕获其确切注册表条目。它仅在映射仍指向该注册
 
 ### Setup 是私有世界内的可信组合
 
-Setup 接收完整的子上下文，可以等待插件激活。它可以注册工具、提示词段、限制、监听器和其他 effect，但公开契约不支持通过强制转换或内部注册表调用来驱动或发布正在创建中的 agent。
+Setup 接收完整的子上下文，可以等待插件激活。它可以注册工具、提示词段、限制、监听器和其他 effect，但公开约定不支持通过强制转换或内部注册表调用来驱动或发布正在创建中的 agent。
 
 事务将异步加载和 setup 与停用进行竞争，而非无限等待外部代码拥有的 promise。如果取消或所有者卸载获胜，即使外部 promise 永不结算，公开创建也会在事务拥有的清理之后拒绝。
 
@@ -185,7 +185,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 ## 信任边界：仅在所有权真正变更时复制
 
-运行时区分类型化的进程内契约与序列化及持久化边界。这是值和回调的主要简化规则。
+运行时区分类型化的进程内约定与序列化及持久化边界。这是值和回调的主要简化规则。
 
 | 边界 | 所有权规则 |
 |---|---|
@@ -196,9 +196,9 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 | 持久化会话或持久化数据 | 在提交前物化并验证 |
 | Worker、进程或协议格式消息 | 序列化、验证并拥有解码后的值 |
 
-测试中构造恶意 getter、在交接后替换类型化回调、或强制转换伪造服务对象的做法本身不定义生产契约。运行时在数据跨越解析器、队列、模型、持久化、文件、worker、进程或协议格式（wire format）边界时保留检查，并在可信进程内依赖 readonly 类型加插件纪律。
+测试中构造恶意 getter、在交接后替换类型化回调、或强制转换伪造服务对象的做法本身不定义生产约定。运行时在数据跨越解析器、队列、模型、持久化、文件、worker、进程或协议格式（wire format）边界时保留检查，并在可信进程内依赖 readonly 类型加插件纪律。
 
-回调隔离与数据所有权是分开的。监听器是任意扩展代码，即使其参数是可信的也可能抛出异常；发布和提交后路径仍按其事件契约隔离失败。
+回调隔离与数据所有权是分开的。监听器是任意扩展代码，即使其参数是可信的也可能抛出异常；发布和提交后路径仍按其事件约定隔离失败。
 
 ## 工具与提示词：单一视图、权威组装、已提交的结果
 
@@ -216,7 +216,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 注册表为每次执行分配一个新的带品牌的 `Symbol` token。嵌套的 Code Mode 调用将外层 token 作为 `parent` 携带，因此结构化输出可以通过标识将内层捕获与其外层 `run_code` 结果关联。
 
-注册表分配的新 Symbol 提供无碰撞的执行标识，无需 WeakSet 成员注册表。调用方无法通过 `ToolExecutionInput` 提供执行自身的 token；它们仅在注册表创建后接收流水线拥有的 `ToolExecution`。这是一个可信的类型化契约，而非针对任意强制转换或 JavaScript 调用方的运行时防御。
+注册表分配的新 Symbol 提供无碰撞的执行标识，无需 WeakSet 成员注册表。调用方无法通过 `ToolExecutionInput` 提供执行自身的 token；它们仅在注册表创建后接收流水线拥有的 `ToolExecution`。这是一个可信的类型化约定，而非针对任意强制转换或 JavaScript 调用方的运行时防御。
 
 参数在模型/工具 JSON 进入流水线时一次性物化。Pre-、around- 和 post-execute 监听器操作类型化的 execution 和决策。Call ID 关联、审批、单调守卫和 Code Mode 嵌套仍然是显式的关系检查。
 
@@ -256,7 +256,7 @@ Scope 直接解决了真正的隔离问题。结构化输出贡献注册在子
 
 ### Skill 和 approval 服务信任类型化调用方
 
-Skill 注册表定义和 approval 策略是 readonly 的同进程契约。它们的服务不克隆回调对象，也不防御交接后的回调替换。
+Skill 注册表定义和 approval 策略是 readonly 的同进程约定。它们的服务不克隆回调对象，也不防御交接后的回调替换。
 
 Skill 仍然验证外部 skill 文件和解析的提供方输出，通过调用 agent 的工具视图路由目录，并精确 dispose 注册。Approval 仍然解析策略、观察取消、按 `request.agent` 路由 `approval/request`、记录持久化审计对，并隔离应答者和提交后观察者的失败。
 
@@ -264,9 +264,9 @@ Skill 仍然验证外部 skill 文件和解析的提供方输出，通过调用
 
 Subagent 启动有一次所有权转移。提供方拥有未发布资源，直到其 start promise 以一个已发布 run 兑现；调用方拥有返回的 run 并必须 dispose 它。
 
-### 服务契约有一个取消通道
+### 服务约定有一个取消通道
 
-`SubagentProvider.start()` 和 `SubagentService.start()` 返回 `Promise<SubagentRun>`。Promise 会在后端跨过发布边界后兑现，因此调用方和 `subagent/start` 观察者从不需要第二个 `run.started` promise。提供方工作如果在发布前失败，`start()` 就会被拒绝；发布后的提示词、轮次、取消与基础设施结果会通过 `SubagentRun.result` 结算，且不会隐藏 child id，这也是[持久化目录决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)所要求的契约。
+`SubagentProvider.start()` 和 `SubagentService.start()` 返回 `Promise<SubagentRun>`。Promise 会在后端跨过发布边界后兑现，因此调用方和 `subagent/start` 观察者从不需要第二个 `run.started` promise。提供方工作如果在发布前失败，`start()` 就会被拒绝；发布后的提示词、轮次、取消与基础设施结果会通过 `SubagentRun.result` 结算，且不会隐藏 child id，这也是[持久化目录决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)所要求的约定。
 
 `SubagentStartRequest.signal` 是必需的。中止它会在启动期间，以及已发布 run 的剩余就绪或轮次工作中请求取消。`SubagentRun.dispose()` 也请求取消并等待完全停稳。没有单独的公开 `run.cancel()` 通道。
 
@@ -314,11 +314,11 @@ Worker 边界仍然序列化请求和结果。宿主保留首个终端结果仲
 
 ## 正确性强制
 
-该设计通过类型、运行时逃逸点、生成的契约和行为测试来强制执行。没有哪一层被要求证明它无法观察到的东西。
+该设计通过类型、运行时逃逸点、生成的约定和行为测试来强制执行。没有哪一层被要求证明它无法观察到的东西。
 
 ### 类型使常规路径难以误用
 
-Readonly 契约描述借用的同进程值。`Scoped<T>` 标记事件接收器，`agentEvents()` 融合载体和主体，工具输入省略注册表拥有的 token，subagent 异步返回类型直接暴露发布与结算。
+Readonly 约定描述借用的同进程值。`Scoped<T>` 标记事件接收器，`agentEvents()` 融合载体和主体，工具输入省略注册表拥有的 token，subagent 异步返回类型直接暴露发布与结算。
 
 TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进程消息或持久化文件，因此运行时强制保留在这些逃逸点。
 
@@ -326,9 +326,9 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 `dsh-scope/invariant` 配套插件在被选用时验证每个声明的作用域事件使用带标记的载体，以及暴露主体的事件族使用匹配的键。独立的 `dsh-session/invariant` 贡献在追加提交前暂存 trace 验证，并在同一事件提交后推进；二者都通过 `ctx.invariants` 注册。
 
-该插件不通过扫描注册表来管控可信 setup，也不拒绝通过强制转换构造的提示词 assembly 对象。这些检查会将组合契约变成推测性的运行时机制，却不保护真实的外部边界。
+该插件不通过扫描注册表来管控可信 setup，也不拒绝通过强制转换构造的提示词 assembly 对象。这些检查会将组合约定变成推测性的运行时机制，却不保护真实的外部边界。
 
-### 生成的产物使公开契约保持对齐
+### 生成的产物使公开约定保持对齐
 
 事件目录、服务目录、生产者/消费方矩阵、配置目录、模块图、工具目录、type-equiv 块和作用域事件解析器映射都是从源码生成或受新鲜度门禁约束的。[TypeScript 语义门禁 Agent Note](../process/2026-07-14-typescript-program-backed-semantic-gates.md)拥有 Program 构造、语义事件发现和解析器生成规则。
 
@@ -336,7 +336,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ## 曾考虑的替代方案
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered)拥有公开扁平作用域契约的替代方案。此处的替代方案关注实现形态。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered)拥有公开扁平作用域约定的替代方案。此处的替代方案关注实现形态。
 
 ### 使用透明代理作为作用域载体
 
@@ -348,7 +348,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ### 对每个类型化的同进程参数做快照
 
-通用复制防御有状态 getter 和违反 readonly 契约的调用方，但增加分配、重复验证器和可能遗忘复制的路径。物化属于解析器、队列、模型、持久化、worker、进程和协议格式边界——即所有权真正变更的地方。
+通用复制防御有状态 getter 和违反 readonly 约定的调用方，但增加分配、重复验证器和可能遗忘复制的路径。物化属于解析器、队列、模型、持久化、worker、进程和协议格式边界——即所有权真正变更的地方。
 
 ### 为就绪、取消和 dispose 提供独立控制器
 
@@ -375,10 +375,10 @@ Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化
 - 作用域贡献仅在其精确的 agent 视图中可见，并随该作用域一起 dispose。
 - 创建和恢复不暴露部分配置的句柄；最终写入注册表时的失败者和发布失败清理每个已准备的资源。
 - Dispose 在 driver 排空和最终会话工作期间保留作用域监听器和持久化，然后撤销作用域。
-- 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 契约。
+- 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 约定。
 - ToolRegistry 的展示、查找和执行在专家 assembly 变换之前解析相同的活跃视图，已提交的结果有一个不可变的观察点。
 - 注册表贡献是确定性输入，而可信的 assembly waterfall 拥有最终的模型可见组合。
-- Subagent start 仅返回已发布的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的完全停稳契约。
+- Subagent start 仅返回已发布的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的完全停稳约定。
 - Worker/进程结果优先级和清理在死亡、迟到消息和有界拆除下保持正确。
 
 ### 代价与局限
@@ -387,6 +387,6 @@ Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化
 
 可信的 `system-prompt/assemble` 监听器可以移除或替换 Code Mode 和结构化输出协议片段。这是有意为之：监听器拥有最终组合，必须保持部署期望仍可用的任何协议。
 
-该设计信任同进程中的类型化插件。它不防御任意强制转换、有状态 getter、违反 readonly 契约的修改，或插件有意在支持的组合 API 之外使用环境服务访问。
+该设计信任同进程中的类型化插件。它不防御任意强制转换、有状态 getter、违反 readonly 约定的修改，或插件有意在支持的组合 API 之外使用环境服务访问。
 
 [安全与权限非目标](2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)仍然是根本性的。这些机制证明注册组合、发布和生命期所有权；它们不证明隔离或父到子的非升权。
diff --git a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
index 460495cbeb..d4886965ad 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md
 2026-07-12-scoped-layers-store.md: c5186d1652bca617eed62ec02937f2d055ea727c
-2026-07-12-scoped-layers-store.zh.md: fbe95ab6c7b3391a70e34b83889bf9f8adeb6ba1
+2026-07-12-scoped-layers-store.zh.md: f5084426beef836d71e55c0898ec1edbdc7725f3
diff --git a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
index fbe95ab6c7..f5084426be 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.zh.md
@@ -16,7 +16,7 @@ agent（智能体）作用域机制（[决策](2026-07-08-agent-scope-contexts.m
 - change 回调运行前必须收集 undo，抛错的回调才能回滚变更。
 - 公开 disposer 必须就是 `ctx.effect()` 返回的那个函数；包装它会破坏 Cordis 基于身份的有序拆除。
 
-共享的是生命周期与保持插入顺序的存储，而不是注册表策略。工具限制、保留传输处理、提示词求值时机、命令规范化、精确诊断和回调异常隔离，仍分别属于不同的领域契约。
+共享的是生命周期与保持插入顺序的存储，而不是注册表策略。工具限制、保留传输处理、提示词求值时机、命令规范化、精确诊断和回调异常隔离，仍分别属于不同的领域约定。
 
 ## 决策
 
@@ -70,7 +70,7 @@ export class AnonymousEntries<V> {
 }
 ```
 
-## 存储契约
+## 存储约定
 
 - 构造器只创建一次 `global`，调用的是 `createLayer(undefined)`。只有 `effect()` 会创建专属层；`peek()` 和 `merge()` 从不创建专属层，而 `peek(undefined)` 返回 `undefined`，因为全局层已经显式存在。
 - `merge()` 是唯一会物化结果的通用读取接口。它按插入顺序复制全局命名条目，再按专属条目的插入顺序应用这些条目；同名条目完成遮蔽，但不会移动无关名称。
@@ -111,11 +111,11 @@ export class AnonymousEntries<V> {
 ## 后果
 
 - 支持作用域的注册表各自通过一个聚合层表达状态，并复用相同的构造、属主、回滚、通知和回收编排。各注册表仍各自保有领域特有的校验、诊断、过滤、求值和观察者策略。
-- 公开读取接口保持狭窄：直接遍历条目表可保留显式的活语义，`merge()` 是唯一共享的物化遮蔽操作。异构的 `ScopeLayer` 不具备整层 `values()` 契约。
-- helper 刻意保持同步。未来的登记若需要异步 setup 或多份分别拥有属主的 undo，必须先明确属主与 settlement 边界，再拓宽这项契约。
-- action 必须在保留贡献前抛错，或者为自己保留的一切返回 undo；helper 无法修复超出这项契约的变更。提供的条目操作是原子的，迁移后的注册表会在插入前执行可能失败的校验。
+- 公开读取接口保持狭窄：直接遍历条目表可保留显式的活语义，`merge()` 是唯一共享的物化遮蔽操作。异构的 `ScopeLayer` 不具备整层 `values()` 约定。
+- helper 刻意保持同步。未来的登记若需要异步 setup 或多份分别拥有属主的 undo，必须先明确属主与 settlement 边界，再拓宽这项约定。
+- action 必须在保留贡献前抛错，或者为自己保留的一切返回 undo；helper 无法修复超出这项约定的变更。提供的条目操作是原子的，迁移后的注册表会在插入前执行可能失败的校验。
 - 专属层会一直保持已分配状态，直到其聚合内的所有表都为空。因此，销毁一个门面不会丢弃同一 scope 拥有的其他贡献。
-- 四个公开符号构成一项可复用的包契约。将 `EntryValues` 保持为内部接口，并把消费方策略留在 helper 之外，可以限制兼容性范围。
+- 四个公开符号构成一项可复用的包约定。将 `EntryValues` 保持为内部接口，并把消费方策略留在 helper 之外，可以限制兼容性范围。
 - 迁移不改变任何公开注册表行为，也不改变模型、人类、协议、持久化、配置或依赖图层面的任何输出。
 
 ## 验证
diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
index c85bb100aa..7f295cd363 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md
 2026-07-15-agent-initiator-scope.md: 2f388ae1de3dd6583686e129a03f0cd76701e18d
-2026-07-15-agent-initiator-scope.zh.md: 64f70a4d1c3368d5621edb7251d0b567505affc0
+2026-07-15-agent-initiator-scope.zh.md: a0e3638081d875adc2412191829ab84c8dcd697c
diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
index 64f70a4d1c..a0e3638081 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
@@ -20,21 +20,21 @@ harness 中存在两种有用但不同的上下文概念。Cordis `Context` 负
 
 因此，并发驱动使用彼此独立的存储。子驱动的异步延续携带子 Agent；`withInitiator()` 返回后，调用方立即恢复之前的存储，而活动运行计数仍持续跟踪返回的 Promise，直到其结束。创建、持久化加载和尚未发布的 `setup(agentCtx)` 位于子驱动边界之外：由父 Agent 发起的创建使用父身份，而 `agentCtx.agent` 显式标识子 Agent。
 
-隐式身份不会取代显式契约。`ToolExecution.agent`、`AssembleContext.agent`、`GenerateOptions.sessionId`、任务归属、父子请求、`ctx.agent`、`agentCtx.agent`、审批与 hook 主体、`cwd` 选择、取消、worker 和进程消息、持久化记录及协议身份都保持显式传递。远程边界会把所需身份写入类型化请求，因为 ALS 只在进程内有效。
+隐式身份不会取代显式约定。`ToolExecution.agent`、`AssembleContext.agent`、`GenerateOptions.sessionId`、任务归属、父子请求、`ctx.agent`、`agentCtx.agent`、审批与 hook 主体、`cwd` 选择、取消、worker 和进程消息、持久化记录及协议身份都保持显式传递。远程边界会把所需身份写入类型化请求，因为 ALS 只在进程内有效。
 
 `AgentRegistry` 管理一个有序的发起方生命周期。teardown 会先拒绝新边界；移除 `ctx.agents` 后，AgentLoop 等注入方开始排空，注册表随后等待活动的返回 Promise 边界，最后调用 `AsyncLocalStorage.disable()`。如果某个边界继承的异步调用链启动所属 Cordis fiber 的卸载，私有运行标记谱系会从排空范围中释放该嵌套边界链，从而避免 teardown 等待自身完成，同时继续排空无关边界。在普通排空期间，进行中代码可通过保留的服务引用继续调用 `currentInitiator()` 和 `requireInitiator()`；dispose（资源释放）后，发起方方法会抛出 `agent initiator scope is disposed`。根 Context dispose 可能并发启动同级 fiber 的 teardown，因此除 Cordis 依赖顺序外仍必须统计活动边界。
 
-发起方作用域不负责管理脱离返回链的工作：注册表排空只跟踪 `withInitiator()` 或 `withoutInitiator()` 返回的 Promise。边界内创建的异步资源会继承其存储，直到自身结束或 ALS 被禁用；所属 seam 必须显式停止未纳入返回 Promise 的工作。Agent 所属的前台工作会把完整生命周期纳入返回值，并保留显式取消契约。无关的定时器、队列和部署基础设施在 `withoutInitiator(operation)` 下启动；队列、worker、进程和协议边界必须序列化身份，不能期待 ALS 传播。
+发起方作用域不负责管理脱离返回链的工作：注册表排空只跟踪 `withInitiator()` 或 `withoutInitiator()` 返回的 Promise。边界内创建的异步资源会继承其存储，直到自身结束或 ALS 被禁用；所属 seam 必须显式停止未纳入返回 Promise 的工作。Agent 所属的前台工作会把完整生命周期纳入返回值，并保留显式取消约定。无关的定时器、队列和部署基础设施在 `withoutInitiator(operation)` 下启动；队列、worker、进程和协议边界必须序列化身份，不能期待 ALS 传播。
 
 宿主感知的传输层可以从 `ctx.agents.requireInitiator().session.id` 推导由部署方拥有的 `X-Harness-Session-Id` 等请求头；模型可见 schema 和参数中不包含该请求头。本决策不让现有生产 MCP 或 Web 传输层采用此请求头。测试替身传输层用于证明可信边界，而不会把宿主路由策略分配给现有的提供方无关 seam。
 
-本决策扩展 [Agent 注册作用域契约](2026-07-08-agent-scope-contexts.md)及其[运行时设计](2026-07-12-agent-scope-runtime-design.md)，不会改变其中 `agent.ctx` 的静态含义。
+本决策扩展 [Agent 注册作用域约定](2026-07-08-agent-scope-contexts.md)及其[运行时设计](2026-07-12-agent-scope-runtime-design.md)，不会改变其中 `agent.ctx` 的静态含义。
 
 ## 验证
 
 Agent 服务测试锁定可选与必需读取、同步值及跨 realm Promise 的精确身份、内建 Promise 结束状态观察、并发、嵌套及清空边界、同步抛错或 Promise 拒绝后的恢复、普通与重入排空顺序及保留引用的错误。AgentLoop 集成测试锁定并发与嵌套驱动、无 Agent 调用、AgentRegistry 重启、根 Context 销毁，以及包内私有的循环和工具调度通过隐式查找完成。组合、模块图、构建及运行时闭包检查确保默认组合包、SDK 主干、Python 运行时闭包及直接 AgentLoop harness 通过 `ctx.agents` 完成接线，无需其他提供方。
 
-测试替身形式的宿主感知传输层在内部推导 `X-Harness-Session-Id`，并验证工具 schema 与日志中记录的参数都不包含身份字段。服务有意不排空边界操作所返回 Promise 之外的异步工作；这类工作仍由所属方的显式停止契约管理。
+测试替身形式的宿主感知传输层在内部推导 `X-Harness-Session-Id`，并验证工具 schema 与日志中记录的参数都不包含身份字段。服务有意不排空边界操作所返回 Promise 之外的异步工作；这类工作仍由所属方的显式停止约定管理。
 
 ## 考虑过的替代方案
 
@@ -46,7 +46,7 @@ Agent 服务测试锁定可选与必需读取、同步值及跨 realm Promise 
 
 **保存命名帧或完整运行时帧。** 只有一个字段的 `{ agent }` 帧只是包装该值，而 Agent、会话、inbox、取消、轮次、步骤、工具执行和持久化已经有各自的真源。增加更多字段会产生陈旧快照和另一套生命周期；直接携带 `Agent`，由方法名标识边界，无需重复保存状态。
 
-**包含步骤级 `AbortSignal`、`cwd`、沙箱或授权。** 它们的生命周期及权限范围与驱动边界不一致，而且现有 seam 已经显式传递这些值。新增控制能力需要独立决策和嵌套生命周期契约。
+**包含步骤级 `AbortSignal`、`cwd`、沙箱或授权。** 它们的生命周期及权限范围与驱动边界不一致，而且现有 seam 已经显式传递这些值。新增控制能力需要独立决策和嵌套生命周期约定。
 
 **使用进程级 `currentAgent`。** 并发 Agent 和 subagent 会在异步延续执行之间相互覆盖，因此可变全局值只在 harness 不具备的串行保证下才正确。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index aac1c86e11..ebf474f78b 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
 2026-07-15-lsp-capability-seam.md: 63cec0a4e349ffc5be27a84e955b15e9168f898b
-2026-07-15-lsp-capability-seam.zh.md: cdb1289f6956d8a4e46ed92847ddd8a58e588afa
+2026-07-15-lsp-capability-seam.zh.md: fa82e29e0252b612ae38357c363478f1cbad9ead
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index cdb1289f69..fa82e29e02 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 harness 已具备文本搜索与文件读取能力，但二者都无法识别程序符号。文本匹配无法可靠地区分同名函数、跟踪导入别名、关联接口与具体实现，也无法报告推断类型。因此，agent（智能体）在修改代码前缺少人类通过编辑器语言服务器获得的语义导航能力。
 
-语言服务器协议（Language Server Protocol，LSP）支持分属三个职责方：模型需要稳定的查询 schema，harness 需要提供方选择与规范化结果，本地实现则负责进程、JSON-RPC、工作区、同步与文件系统行为。将三者合并会使模型契约绑定本地子进程，并阻碍远程或沙箱原生提供方。
+语言服务器协议（Language Server Protocol，LSP）支持分属三个职责方：模型需要稳定的查询 schema，harness 需要提供方选择与规范化结果，本地实现则负责进程、JSON-RPC、工作区、同步与文件系统行为。将三者合并会使模型约定绑定本地子进程，并阻碍远程或沙箱原生提供方。
 
 许多语言服务器在查询文档已按当前文本打开时表现最佳。兼容的 agent 客户端必须限制这项状态、定义内部读取是否算作模型观察，并确保文档快照与服务器工作区索引位于同一文件系统命名空间。
 
@@ -32,7 +32,7 @@ harness 已具备文本搜索与文件读取能力，但二者都无法识别程
 
 服务边界只公开 `query(request, signal?)`，因为没有字段需要实现层填充默认值：`workspaceRoot` 是必填项，`languageId` 来自注册映射，超时与结果限制由消费方负责。`query()` 执行选择与推导时不使用隐藏的 `??` 后备逻辑，因此没有需要 resolve 的可执行 spec。`dsh-tool-lsp` 校验模型参数，并只把 `exec.signal` 作为裸 `AbortSignal` 传递，与 web 一致，并使 `dsh-lsp` 不依赖 `dsh-tools`。提供方在选择前被移除时按不可用失败；之后的释放遵循已选提供方的取消生命周期，不改路由。
 
-预期契约如下：
+预期约定如下：
 
 ```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
@@ -81,7 +81,7 @@ interface LspService {
 
 `dsh-lsp-local` 负责服务器配置、JSON-RPC、进程与临时文档状态和协议转换。它通过 `ctx.fs` 读取，通过 `ctx.subprocess` 启动，只依赖二者的接口包而非具体提供方；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)负责定义这种配对。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
 
-## 面向模型的契约
+## 面向模型的约定
 
 单一 `lsp` 工具接受以下参数：
 
@@ -149,7 +149,7 @@ interface LspToolInput {
 
 **照搬 Claude Code 的统一 schema。** 它的光标操作验证了核心场景，但符号与调用层级需要不同参数。照搬九种操作会固化尚未验证的接口，因此本提案只对齐四种语义查询。
 
-**允许提供方注册工具。** 已加载服务器会控制模型 schema 和提示词，无法在本地与远程提供方之间维持统一契约。
+**允许提供方注册工具。** 已加载服务器会控制模型 schema 和提示词，无法在本地与远程提供方之间维持统一约定。
 
 **公开任意 LSP 方法。** JSON-RPC 逃生口会泄露协议载荷，并允许未经评审的变更或命令执行；操作联合保持封闭。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
index d7f1670f34..f683189f93 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
 2026-07-16-explicit-turn-cancellation.md: 2b7cb8cc77184edf1331764d28aefe748c1614a1
-2026-07-16-explicit-turn-cancellation.zh.md: 729997d48df79bad9fa52cd76ec7fa1fab281ae3
+2026-07-16-explicit-turn-cancellation.zh.md: 0b9a06c0ae340a41eab9d6bff6126996bfc63bcf
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
index 729997d48d..0b9a06c0ae 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`；`agent.cancel()` 默认使用 `user`。TypeScript 在这个类型化的同进程 seam 中强制执行该词汇，不提供运行时校验器、后备行为，也不为无类型调用方提供特殊兼容性契约。活跃的 `TurnCancellation` 会把类型化判别字段复制为一个全新且已冻结的 signal 原因；空闲状态下没有可修改的持有者，也不会让后续工作预先进入取消状态。
+Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`；`agent.cancel()` 默认使用 `user`。TypeScript 在这个类型化的同进程 seam 中强制执行该词汇，不提供运行时校验器、后备行为，也不为无类型调用方提供特殊兼容性约定。活跃的 `TurnCancellation` 会把类型化判别字段复制为一个全新且已冻结的 signal 原因；空闲状态下没有可修改的持有者，也不会让后续工作预先进入取消状态。
 
 正在运行的轮次被中断后，以粗粒度的持久化结果 `{ kind: 'aborted' }` 结束。终态事件记录轮次发生了什么，运行时 signal 标识谁请求了取消；回放不会重复保存 `user` 或 `parent`。会话 seed/load 会拒绝携带取消原因或任何其他额外字段的旧式中止记录，因此回放无法重新引入由调用方持有的取消细节。仅限进程内的 `agent/cancel-requested` 通知不会持久化；未来若有审计需求，应使用独立的持久化控制请求事件，让请求与最终结果保持为两项事实。持久化事件不包含调用栈、signal、错误对象、自由文本取消原因或后端私有细节。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
index 82d87580f8..a0956af598 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
 2026-07-19-cooperative-tool-cancellation.md: 4e82452cd6883593d4693766bea803c97fa4c977
-2026-07-19-cooperative-tool-cancellation.zh.md: 1d9fd3dcc8fa65e6f06050be749eec6ac9e996c2
+2026-07-19-cooperative-tool-cancellation.zh.md: aa94fd9f3d32167dc7d6b906ff14a6afd36ccb32
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
index 1d9fd3dcc8..aa94fd9f3d 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 `ToolDefinition.execute(args, exec)` 保持现有签名。`defineTool()` 会把 `exec.signal` 上下文推断为必填的 `AbortSignal`，因此每个已注册的 TypeScript 工具都能在无需类型断言的情况下观察或转发取消。所有第一方直接调用方和 Code Mode 嵌套调度都会显式传入当前操作的信号。
 
-注册表信任这份类型化同进程契约。它不在运行时校验 `AbortSignal`，也不为缺失或畸形信号添加敌意输入测试。校验仍位于解析器与配置、模型与工具 JSON、持久化与文件、worker、进程和协议边界；违反 TypeScript 接口的无类型 JavaScript 不享有兼容性契约。
+注册表信任这份类型化同进程约定。它不在运行时校验 `AbortSignal`，也不为缺失或畸形信号添加敌意输入测试。校验仍位于解析器与配置、模型与工具 JSON、持久化与文件、worker、进程和协议边界；违反 TypeScript 接口的无类型 JavaScript 不享有兼容性约定。
 
 ### 可变性由流水线阶段决定
 
@@ -54,9 +54,9 @@ Status: implemented
 
 **保留可选信号并生成后备值。** 不予采纳，因为注册表持有的后备信号不代表任何调用方生命周期，也会保留类型系统本应阻止的缺失情况。
 
-**在运行时校验 `AbortSignal`。** 不予采纳，因为这是类型化同进程 seam，不是序列化边界。运行时检查只会重复静态契约，仍无法强制实现协作式使用信号。
+**在运行时校验 `AbortSignal`。** 不予采纳，因为这是类型化同进程 seam，不是序列化边界。运行时检查只会重复静态约定，仍无法强制实现协作式使用信号。
 
-**添加 `supportsCancellation` 元数据、回调参数数量检查或信号使用 lint。** 不予采纳，因为这些方法都无法证明异步工作会观察或正确转发取消。信号可用性属于类型契约；具体行为仍由工具和能力负责。
+**添加 `supportsCancellation` 元数据、回调参数数量检查或信号使用 lint。** 不予采纳，因为这些方法都无法证明异步工作会观察或正确转发取消。信号可用性属于类型约定；具体行为仍由工具和能力负责。
 
 **向所有阶段公开同一个可变执行类型。** 不予采纳，因为观察者和工具实现只需要借用信号。按阶段划分类型可以把替换权限限制在流水线拥有该操作的位置。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 65cbe478ae..4578e9e268 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
 2026-07-19-gui-layering-and-rpc-protocol.md: 8e020e4fe9b60100671c0cf0e98e28532d850f94
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 55fa8084083aa83fbb4a38f8e41d2e5624b6e58e
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 49ebd642264c663377f16b8669fedc112d3bb6c7
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 55fa808408..49ebd64226 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 那么当前的工程代码需要稳定的分层职责模型，便于以后接入各类 client 形态。
 
-同时各消费端的物理通道不同（浏览器 HTTP／WebSocket、进程内 fetch/SSE、将来 IPC），还需要一个通道无关的消息模型和单一契约事实源，让「加一个方法」「换一种载体」互不牵连，且 wire 上的每条消息可类型校验、可观测、可对账。
+同时各消费端的物理通道不同（浏览器 HTTP／WebSocket、进程内 fetch/SSE、将来 IPC），还需要一个通道无关的消息模型和单一约定事实源，让「加一个方法」「换一种载体」互不牵连，且 wire 上的每条消息可类型校验、可观测、可对账。
 
 ## Decision
 
@@ -151,7 +151,7 @@ export type ResponseValue<K> =
 - **锚定**：schema 统一 `satisfies z.ZodType<Wire<T>>`（`api/rpc.schema.ts`）。`Wire<T>` 是深度「| undefined」宽化——仓库开 `exactOptionalPropertyTypes` 而 zod `.optional()` 输出 `T | undefined`，直接锚原类型全线不可用；JSON wire 上缺席与 undefined 同形，宽化不损失校验语义。透传宽分支（`SessionEvent`/`ContentBlock`/帧 union/`RpcError`）与 brand id schema 用显式 cast + 注释。
 - brand cast 单点：每个 schema 文件的 id cast 收口一处（`rpcIdSchema` 是 rpc.schema.ts 唯一 cast 点）。
 
-## 契约面（ApiProxy）
+## 约定面（ApiProxy）
 
 根接口 `ApiProxy = { sessions, host, events, respond }`（`api/index.ts`）。新 client-request 域 = 新的一对文件（`<域>.ts` + `<域>.schema.ts`）+ 根接口一个字段 + map 加行。
 
@@ -183,7 +183,7 @@ export type ResponseValue<K> =
 - **prompt 关联**：prompt 的 rpcId 经 MessageSource（`'user-rpc'`）透传进 `user/message` 事件，client 以此把乐观回显转正。
 - **重连 = 重建**：不做续传 cursor（`mux` 的 `since` 签名留座、传了忽略）；断线重开流 + 重拉 history；`subscribed.lastSeq` 与 history 尾 seq 比对，有缝再补拉一次。
 - **冷会话处理遵循所有权**：`session.history` 与 `session.fork` 的源端读取会在不获取 Agent 的情况下检查持久化存储，而绑定到 Agent 的普通会话方法（如 `prompt`）则通过在途表去重后恢复会话。由会话支撑的 subagent 会拒绝这条通用恢复路径，且附加状态不对客户端暴露（`running` 已经覆盖）。
-- **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：契约与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
+- **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：约定与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
 - **不设协议版本**：client 与 host 绑定发布，`host.describe` 无 protocolVersion 字段；出现独立发布的 client 时再引入。
 - **预留接缝纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。（`session.rename` 已从本清单毕业：追加 user 来源的 `session/title` 事件。）
 
@@ -193,7 +193,7 @@ export type ResponseValue<K> =
 
 ### IApiClient：caller 视图
 
-与 `ApiProxy` 同域树，但 unary 方法**收业务 payload 直传**——载体 mint rpcId 并包信封，业务代码永不 mint；需要本次调用 rpcId 的从返回的 `RpcResponse` 回显里读。`ApiProxy` 是 impl 侧实现的窄形签名契约，`IApiClient` 是 client 侧消费的 payload 直传视图，`AbstractApiClient` 桥接两者。方法逐 key 从 `RpcMethodMap` 派生——map 加行即机械更新。
+与 `ApiProxy` 同域树，但 unary 方法**收业务 payload 直传**——载体 mint rpcId 并包信封，业务代码永不 mint；需要本次调用 rpcId 的从返回的 `RpcResponse` 回显里读。`ApiProxy` 是 impl 侧实现的窄形签名约定，`IApiClient` 是 client 侧消费的 payload 直传视图，`AbstractApiClient` 桥接两者。方法逐 key 从 `RpcMethodMap` 派生——map 加行即机械更新。
 
 ### 基类持有的协议路径
 
@@ -216,7 +216,7 @@ export type ResponseValue<K> =
 | `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh run` headless 即协议第二真实消费者 |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
-| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，契约/基类零改 |
+| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
 
 ## 怎么扩展（操作清单）
 
@@ -226,13 +226,13 @@ export type ResponseValue<K> =
 
 **加一个错误码（2 步）**：①`RpcErrorDetailsMap` 加一行（details 必填）；②`rpcErrorSchema` discriminatedUnion 加一支。
 
-**接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。契约与基类零改。
+**接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。约定与基类零改。
 
 **升格一个预留接缝**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
 
 ## Consequences
 
-所有 client 形态消费同一契约：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
+所有 client 形态消费同一约定：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
 
 ## Alternatives considered
 
@@ -240,10 +240,10 @@ export type ResponseValue<K> =
 |---|---|
 | 按「产品形态」分包（web 一族、electron 一族） | 形态间共享的是 host/client 两侧能力而非形态本身；能力支持方分层让新形态零新包 |
 | 混合体建包（如 headless 独立包） | 混合体只有一个消费者（它自己的 app），建包是无主抽象；拼装写在 app 里可读可弃 |
-| 消费型 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开契约，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
+| 消费型 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开约定，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
 | webserver 依赖 runtime（省 handler 注入） | 结构 typing 注入让 webserver 可被 sidecar/测试复用且零 workspace 依赖；包依赖会把装配知识拖进承载层 |
 | 包名不带组前缀（沿用 dsh-<尾段>） | `dsh-runtime`/`dsh-web-ui` 在扁平 npm 命名空间里失去归属信息；代价只是每包一条显式 paths |
-| 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、契约双份人肉对齐、命名无 convention 自然漂移 |
+| 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、约定双份人肉对齐、命名无 convention 自然漂移 |
 | 三信封模型（Request/Response/Frame 各一信封，签名不感知方向） | rpcId 是逻辑层关联，帧与应答的方向语义靠通道推断在换载体时即失效 |
 | 具名 Request/Response 类型对为事实源（map 登记类型对） | 平铺具名类型是同一事实的第二个名字；签名 infer 反推让加方法只改一处 |
 | REST 风格路径 | 消费者是自家 client，无第三方 REST 体验诉求；RPC 直映方法表更机械 |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index d3bbc7da9d..5523e6d3b2 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
 2026-07-19-gui-web-client-architecture.md: e25d002b92df2016faf4073108aa905b65a1b115
-2026-07-19-gui-web-client-architecture.zh.md: cf31220aad61e4845f7fe90b73bf5da4432e53de
+2026-07-19-gui-web-client-architecture.zh.md: 10779107a9dc6dc7335b2c5932c8c4877b531b50
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index cf31220aad..10779107a9 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-19-gui-web-client-architecture.md) | 中文
 
-> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/契约面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
+> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/约定面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
 
 ## Problem
 
@@ -69,7 +69,7 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 ```
 
 - **Session**（session.ts）：懒建、常驻——建成后在后台持续吃帧，切走切回秒显。操作面：`prompt`/`cancel`（RPC 透传；失败落进快照的 `promptError`）、`open`（拉尾页 history，幂等）、`loadOlder`（向上翻页，防重入）、`resync`（重连 = 清窗口重跑 open）。订阅面：`subscribe`/`getSnapshot`（恒返缓存引用）——`implements ObservableSnapshot<ConversationSnapshot>`，构造时挂 `useSelector = bindSnapshotSelector(this)`，Session 本身就是 uSES 源。帧分发是一个 switch：`session/event` 帧按 seq 去重（唯一去重键），open 在途时缓冲，否则追加 + 增量投影；open/缝合按 seq 合并 live 缓冲并去重，`subscribed.lastSeq` 超出窗口尾则回补一次。
-- **ConversationSnapshot**（conversation.ts）：不可变快照契约——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。
+- **ConversationSnapshot**（conversation.ts）：不可变快照约定——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。
 - **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。
 - **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。
 - **TranscriptAdapter / PartialAccumulator**：对话记录是按日志顺序投影的 append 来源 surface（`@deepseek-ai/dsh-session/surface` 的 `isAppendSurfaceEvent`），外加每次落地的压缩检查点一个标记——绝不用模型 surface，后者遮蔽被替换的范围，会抹掉读者已经看过的对话。节点顺序天然按 seq 单调，因此既无核心 `seq === index` 断言需要满足，也没有降级分支。分片不贡献任何节点（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。
@@ -79,8 +79,8 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 
 胶水包就是整条 ctx↔React 边界；组件保持零框架依赖。
 
-- 快照 store 引擎**住 runtime 包**（zustand vanilla + 草稿式更新，缺省 `flush: 'sync'`，帧驱动 store 可选 `'raf'` 合批，可选整值 localStorage 持久化，dev 深冻结——全部从 `runtime` 的 `./client` 主出口导出，无子路径）：store 产物是裸的可观察源，不带任何 hook 成员。插件只经 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 的 `defineStore` 声明触及引擎。web-react 在绑定处（`bindSnapshotSelector`，按源缓存）从 React 消费的唯一数据契约合成每个 hook：`ObservableSnapshot<T>`（`getSnapshot`/`subscribe`）——Session 对象与快照 store 同构满足它。业务插件包只依赖 runtime 与 ui-slots；web-react 是仅壳可用的胶水。
-- `bindSnapshotSelector(source)`：把一个源绑定为经 uSES-with-selector 的带类型 selector hook。uSES 契约四条按构造成立：getSnapshot 恒返缓存引用；subscribe 是绑定期闭包（引用永稳）；纯 CSR 不传 server snapshot；相等性缺省 `Object.is`，按调用可选 `shallowEqual`。
+- 快照 store 引擎**住 runtime 包**（zustand vanilla + 草稿式更新，缺省 `flush: 'sync'`，帧驱动 store 可选 `'raf'` 合批，可选整值 localStorage 持久化，dev 深冻结——全部从 `runtime` 的 `./client` 主出口导出，无子路径）：store 产物是裸的可观察源，不带任何 hook 成员。插件只经 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 的 `defineStore` 声明触及引擎。web-react 在绑定处（`bindSnapshotSelector`，按源缓存）从 React 消费的唯一数据约定合成每个 hook：`ObservableSnapshot<T>`（`getSnapshot`/`subscribe`）——Session 对象与快照 store 同构满足它。业务插件包只依赖 runtime 与 ui-slots；web-react 是仅壳可用的胶水。
+- `bindSnapshotSelector(source)`：把一个源绑定为经 uSES-with-selector 的带类型 selector hook。uSES 约定四条按构造成立：getSnapshot 恒返缓存引用；subscribe 是绑定期闭包（引用永稳）；纯 CSR 不传 server snapshot；相等性缺省 `Object.is`，按调用可选 `shallowEqual`。
 - `useInvoke(fn)`：把异步动作包成引用恒定的触发器加 pending 标志；pending 走 per-hook 外部 store 经 uSES 读出（渲染路径零 setState），并发调用计数，invoke 引用永不变。
 - 相等性协议，全链一致：生产端结构共享；消费端以 `Object.is` 或 `shallowEqual` 短路；`React.memo` 浅比较。深比较全链禁止。
 
@@ -108,7 +108,7 @@ src/client/
 ## 怎么开发
 
 - **新 UI 功能** = 新插件包：package.json 声明 `dshClient`（+ `inject` 拓扑），浏览器半边写在 `src/client/`（apply 挂服务/建 store、注册 slot），无 host 逻辑时 node 半边保持空 apply，用共享预设构建。把插件加进 host 配置；manifest 与装载随之自动跟上。
-- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——契约合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
+- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——约定合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
 - **消费新帧类型**：带 sessionId → Session 分发 switch 加一个分支；host 级 → Manager 路由表；UI 需要时给 `ConversationSnapshot` 加字段并守住引用纪律。
 - **状态住哪**：业务数据（事件、流式、待答）→ 永远对象层；父知道的 → renderSlot 现场的 owner props；单组件私有（滚动、搜索词、展开集）→ 组件状态；跨 entry 共享或跨重挂载存活（选中、草稿、面板宽）→ entry 声明的 store（[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)）。
 - **通知通道**：帧驱动/异步 = `markDirty` 合批；受控输入需要同 tick 的用户手势直接回响 = `notifyNow`。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
index e292482740..6af30fd423 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
 2026-07-19-package-invariant-runtime-contracts.md: 86d86f69b606c348e85d1ae654b6b35c4326985a
-2026-07-19-package-invariant-runtime-contracts.zh.md: 386a294b577561d08493a3b2925910ee5ba971b4
+2026-07-19-package-invariant-runtime-contracts.zh.md: 94d332a34c1d6e681c10832ea4deb559d88b21a6
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
index 386a294b57..94d332a34c 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 有意义的包不变量契约
+# Agent Note: 有意义的包不变量约定
 
 Status: implemented
 
@@ -10,7 +10,7 @@ Status: implemented
 
 有用的运行时不变量会关联时间上的多个观测，或关联可变数据结构中的多个部分。例如：终止事件没有对应的开始事件、LLM（大语言模型）delta 指向未打开的块，或持久化结果的身份与请求不同。仅确认声明的方法存在、插件名称符合预期，或常量示例仍返回已知值，都不属于这种关系。
 
-有些包确实没有可持续观测的关系。纯工具、仅负责组合的包、薄适配器、可执行入口和测试支持包可能仍有重要契约，但类型检查、加载检查、聚焦单元测试或集成测试更适合执行这些契约。强迫这些包添加合成运行时断言，只会让实现围绕通过门禁优化，而不是检测损坏。
+有些包确实没有可持续观测的关系。纯工具、仅负责组合的包、薄适配器、可执行入口和测试支持包可能仍有重要约定，但类型检查、加载检查、聚焦单元测试或集成测试更适合执行这些约定。强迫这些包添加合成运行时断言，只会让实现围绕通过门禁优化，而不是检测损坏。
 
 ## 决策
 
@@ -64,7 +64,7 @@ Vitest 为每个包测试拓扑使用 `{ enabled: true }` 挂载 `InvariantServi
 ## 考虑过的替代方案
 
 - **保留生成的空 companion。** 拒绝，因为包获得有意义的运行时关系后，没有解释的占位符仍可能继续存在。
-- **要求每个包都执行断言。** 拒绝，因为方法存在性、插件形状和固定示例断言会重复更强的类型、加载和单元测试契约，却没有检查运行时一致性。
+- **要求每个包都执行断言。** 拒绝，因为方法存在性、插件形状和固定示例断言会重复更强的类型、加载和单元测试约定，却没有检查运行时一致性。
 - **在服务中保留通用形状 helper。** 拒绝，因为这会混淆编译期 API 验证和运行时不变量，并鼓励在中央定义产品假设。
 - **把产品检查移入服务。** 拒绝，因为产品词汇、依赖、测试和变更所有权应归属于产生这些数据的包。
 - **从根入口隐式注册 companion。** 拒绝，因为组合顺序和可选服务存在性会产生隐藏 effect。
@@ -75,4 +75,4 @@ Vitest 为每个包测试拓扑使用 `{ enabled: true }` 挂载 `InvariantServi
 - 空 companion 是带包专属说明、可评审的决策；删除说明后门禁会失败。
 - 类型声明、Cordis 可加载性、插件 metadata、服务方法形状和纯代数继续由所属的编译、加载、单元或集成门禁覆盖。
 - 运行时失败会标明所属 npm 包，并指出不一致的观测，而不是复述必要的 API 形状。
-- 原有 selection、blocklist 优先级、重复所有权、回滚、dispose 和 HMR（热模块替换）服务契约保持不变。
+- 原有 selection、blocklist 优先级、重复所有权、回滚、dispose 和 HMR（热模块替换）服务约定保持不变。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
index 544e7415ce..291a3f3ce1 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
 2026-07-19-package-owned-invariant-service.md: e32efe9f6b3ce6b782c61db56d928e87c160dc9a
-2026-07-19-package-owned-invariant-service.zh.md: f134541c78f849fa085bebef527b57f911af0748
+2026-07-19-package-owned-invariant-service.zh.md: abb77cfc2dc4c15510baf0b205cefdbf3c890041
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
index f134541c78..abb77cfc2d 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 `@deepseek-ai/dsh-invariants` 是与产品无关的 Cordis 服务插件，注册 `ctx.invariants`。它只负责配置、注册唯一性、子 fiber 生命周期和带包归属的失败；不导入 session、agent、scope 或 agent-loop 包，也不包含这些包的检查。
 
-工作区内的每个包都发布 `./invariant` 伴随插件，注册自己完整且准确的 npm 包名。如果所有者具备有意义的事件或可变数据关系，companion 就检查该关系；否则空 installer 必须携带该所有者专属的说明。后续的[运行时契约 Agent Note](2026-07-19-package-invariant-runtime-contracts.md) 禁止生成的所有权占位符和合成 API 形状断言。包的根入口不会隐式导入或注册诊断，因此加载根包不会改变运行时检查，也不要求不变式服务存在。
+工作区内的每个包都发布 `./invariant` 伴随插件，注册自己完整且准确的 npm 包名。如果所有者具备有意义的事件或可变数据关系，companion 就检查该关系；否则空 installer 必须携带该所有者专属的说明。后续的[运行时约定 Agent Note](2026-07-19-package-invariant-runtime-contracts.md) 禁止生成的所有权占位符和合成 API 形状断言。包的根入口不会隐式导入或注册诊断，因此加载根包不会改变运行时检查，也不要求不变式服务存在。
 
 ### 配置与选择
 
@@ -64,13 +64,13 @@ blocklist 匹配优先于 allowlist 匹配。每个条目都是区分大小写
 | `@deepseek-ai/dsh-scope/invariant` | `@deepseek-ai/dsh-scope` | scoped event carrier 存在性与主体一致性 |
 | `@deepseek-ai/dsh-agent-loop/invariant` | `@deepseek-ai/dsh-agent-loop` | 模型请求重建 |
 
-这四个所有者提供了首批有状态检查。后续运行时契约决策为另外十七个确有事件或可变数据关系的所有者增加检查，并为其余包记录有理由的空 companion。每个伴随入口都是单独打包的 `./invariant` export，具有独立声明和对 Loader 安全的命名空间插件形态；服务包自身的伴随插件导入本地服务类型，避免形成自依赖。
+这四个所有者提供了首批有状态检查。后续运行时约定决策为另外十七个确有事件或可变数据关系的所有者增加检查，并为其余包记录有理由的空 companion。每个伴随入口都是单独打包的 `./invariant` export，具有独立声明和对 Loader 安全的命名空间插件形态；服务包自身的伴随插件导入本地服务类型，避免形成自依赖。
 
 `verify-package-invariants` 会发现每个工作区包，并拒绝缺失的伴随插件源码、生成标记、没有解释的空 installer、缺少或不使用失败报告器的非空 installer、外部或无法解析的注册名、缺失的 `./invariant` export 或发布文件、缺失的不变式对等依赖（peer dependency）、开发依赖及项目引用，以及遗漏伴随入口的自定义构建配置。
 
 ### Scoped event 语义映射
 
-生成的 scoped event 主体解析表位于 `dsh-scope`，与消费它的契约和不变式相邻。`gen-scoped-events` 使用根 TypeScript Program 枚举 `this: Scoped<Base>` 声明，从真实 `scopeTarget(base, key)` 调用推断路由键类型，并要求唯一、无歧义的 payload 主体或显式 unsupported 标记。提交的运行时映射不导入事件所有者包，因此语义完整性不会扩大服务包或 scope 包的运行时依赖闭包。
+生成的 scoped event 主体解析表位于 `dsh-scope`，与消费它的约定和不变式相邻。`gen-scoped-events` 使用根 TypeScript Program 枚举 `this: Scoped<Base>` 声明，从真实 `scopeTarget(base, key)` 调用推断路由键类型，并要求唯一、无歧义的 payload 主体或显式 unsupported 标记。提交的运行时映射不导入事件所有者包，因此语义完整性不会扩大服务包或 scope 包的运行时依赖闭包。
 
 ### 示例组合与 SDK 输出
 
@@ -88,9 +88,9 @@ Workspace 约束识别独立的不变式 bundle；包 exports、项目引用、
 
 ## 考虑过的替代方案
 
-- **把所有检查保留在 `dsh-invariants`。** 不予采纳，因为注册包仍要导入所有被检查的产品领域，所有者变更仍需中央编辑，测试也继续远离被保护的契约。
+- **把所有检查保留在 `dsh-invariants`。** 不予采纳，因为注册包仍要导入所有被检查的产品领域，所有者变更仍需中央编辑，测试也继续远离被保护的约定。
 - **当 `ctx.invariants` 恰好存在时，让根包入口隐式注册检查。** 不予采纳，因为根入口行为会依赖组合顺序与可选服务是否存在，诊断无法独立选择，而且包加载会隐藏一个不在显式伴随插件中的注册 effect。
-- **在运行时自动发现所有 `invariant.ts` 文件。** 不予采纳，因为文件系统或包发现不是运行时所有权契约，会让 bundle 发布含义不清，也无法表达显式 Cordis 加载顺序或依赖安装。构建期生成与校验以及测试 host 可以枚举源码树，因为它们验证的是仓库完整性，而不是组合已发布的部署。
+- **在运行时自动发现所有 `invariant.ts` 文件。** 不予采纳，因为文件系统或包发现不是运行时所有权约定，会让 bundle 发布含义不清，也无法表达显式 Cordis 加载顺序或依赖安装。构建期生成与校验以及测试 host 可以枚举源码树，因为它们验证的是仓库完整性，而不是组合已发布的部署。
 - **根据当前已加载包集合验证 allow/block 条目。** 不予采纳，因为零匹配模式可能有意指向稍后加载或 HMR 加载的贡献；当前加载顺序不能决定配置有效性。
 
 ## 后果
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
index acb9d72ef1..be9d15968f 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md
 2026-07-19-zstandard-jsonl-session-logs.md: 93fc20f931c75552352834b9340e7d38680d4254
-2026-07-19-zstandard-jsonl-session-logs.zh.md: 061d7fcb55c775eed10e99bae47777d32cc8eee1
+2026-07-19-zstandard-jsonl-session-logs.zh.md: e5495f2f5ae356d49bd2321e442c19ca834c2ab7
diff --git a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
index 061d7fcb55..e5495f2f5a 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md
@@ -38,7 +38,7 @@ JSONL 持久化后端会逐字保留每个 `SessionEvent`，其中包括数量
 
 CLI、ACP 与 stdio 应用包公开对称的 `persistenceCompression` 透传配置。web 宿主装配与普通应用组合省略该选项并使用压缩默认值。快照录制与回放组合显式选择 `'none'`，因为提交的 fixture 是回放与规范化过程使用的原始 JSONL 输入。
 
-共享持久化契约与协调器契约会针对两种编码运行。后端测试覆盖标准帧与校验和互操作性、仅头部列举、追加回滚、编码不匹配拒绝、完整帧损坏，以及横跨头部、块和校验和尾部的最终帧撕裂。默认运行时、构建后二进制、headless、ACP 与 Python 冒烟测试会断言压缩后缀与 Zstandard 魔数，或解码头部；读取原始内容的测试则显式退出压缩。
+共享持久化约定与协调器约定会针对两种编码运行。后端测试覆盖标准帧与校验和互操作性、仅头部列举、追加回滚、编码不匹配拒绝、完整帧损坏，以及横跨头部、块和校验和尾部的最终帧撕裂。默认运行时、构建后二进制、headless、ACP 与 Python 冒烟测试会断言压缩后缀与 Zstandard 魔数，或解码头部；读取原始内容的测试则显式退出压缩。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
index 680d2dd94a..75c2b53cef 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
 2026-07-20-canonical-tool-output-contract.md: 2429e1c141ad8c8ee932c6d654a6ba74bc4f7618
-2026-07-20-canonical-tool-output-contract.zh.md: 26653ea769b8a642b70c4d3dd2f5ab907a70bd85
+2026-07-20-canonical-tool-output-contract.zh.md: 534aa2ed7ad65719b280f64f73a412bf5b17a1de
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
index 26653ea769..534aa2ed7a 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 规范工具输出契约
+# Agent Note: 规范工具输出约定
 
 Status: implemented
 
@@ -8,7 +8,7 @@ Status: implemented
 
 工具主体过去直接编写面向模型的 `ContentBlock[]`，并可选择将其与不透明的 `meta` 包装在一起。因此，Native 模式的 Function Calling（函数调用）虽然拥有可供人阅读的投影，但程序化调用方没有稳定的领域值：Code Mode 会将内容块重新展平为字符串，动态工具会重复定义内容形态，策略也可以替换展示内容，却无法区分这项变更究竟是替换展示，还是替换操作结果。多个能力 seam 已经返回了信息更丰富的提供方值，却又在面向模型的工具边界丢弃这些值。
 
-持久会话契约将这份展示内容视为回放时的权威来源，但如果持久化每一个信息丰富的中间值，就会扩大日志、使实现数据进入压缩（compaction）和迁移流程，还会错误地把执行期本地 API 变成会话格式的一部分。因此，系统底层需要在执行期间保留一个类型化值，并显式将其投影为现有的持久化内容和模型可见内容。
+持久会话约定将这份展示内容视为回放时的权威来源，但如果持久化每一个信息丰富的中间值，就会扩大日志、使实现数据进入压缩（compaction）和迁移流程，还会错误地把执行期本地 API 变成会话格式的一部分。因此，系统底层需要在执行期间保留一个类型化值，并显式将其投影为现有的持久化内容和模型可见内容。
 
 ## 决策
 
@@ -74,6 +74,6 @@ MCP 桥接层通过 `McpResult<{...}> = { content: JsonValue[]; structuredConten
 
 ## 影响
 
-Native 和回放行为仍以内容为先，并保持逐字节兼容；执行期调用方则无需解析内容，即可使用经过校验的领域值。失败结果必须包含消息，并可选择附加内部类名／代码信息；成功与失败结果由判别字段区分，失败结果绝不会承诺存在值。工具作者必须一并设计值及其 Native 投影；增加这项声明是有意为之，因为它避免从自然语言内容意外推导出程序化契约。
+Native 和回放行为仍以内容为先，并保持逐字节兼容；执行期调用方则无需解析内容，即可使用经过校验的领域值。失败结果必须包含消息，并可选择附加内部类名／代码信息；成功与失败结果由判别字段区分，失败结果绝不会承诺存在值。工具作者必须一并设计值及其 Native 投影；增加这项声明是有意为之，因为它避免从自然语言内容意外推导出程序化约定。
 
-中间值只受产生它们的能力和进程内存限制。日志不包含这些值，因此回放无法恢复；仅处理内容的 post 策略也无法隐藏这些值。这些都是执行期本地契约的明确属性，并非意外缺口。
+中间值只受产生它们的能力和进程内存限制。日志不包含这些值，因此回放无法恢复；仅处理内容的 post 策略也无法隐藏这些值。这些都是执行期本地约定的明确属性，并非意外缺口。
diff --git a/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.i18n.yaml
index 42b61e04c1..152bae16ac 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.md
 2026-07-20-unified-json-value-schema-dsl.md: 5de3523eab15a91ea32dc09e2e239146fadea6f1
-2026-07-20-unified-json-value-schema-dsl.zh.md: 8521e03beb7398ebfdf5e5cddae7a99471aa38d7
+2026-07-20-unified-json-value-schema-dsl.zh.md: 0dc38dc289a32269c0f9e545ae53a8098ba02189
diff --git a/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.zh.md b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.zh.md
index 8521e03beb..0dc38dc289 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-unified-json-value-schema-dsl.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-工具参数使用一套精简的作者侧 schema DSL，subagent／工作流的结构化输出则使用另一套原始 JSON Schema 子集和校验器。两套词汇在根类型、标量约束和校验方式上并不一致；如果继续沿用这种划分，类型化的规范工具输出契约要么还需重复实现两条路径，要么只能接受部分投影无法强制执行的 schema。
+工具参数使用一套精简的作者侧 schema DSL，subagent／工作流的结构化输出则使用另一套原始 JSON Schema 子集和校验器。两套词汇在根类型、标量约束和校验方式上并不一致；如果继续沿用这种划分，类型化的规范工具输出约定要么还需重复实现两条路径，要么只能接受部分投影无法强制执行的 schema。
 
 ## 决策
 
@@ -33,5 +33,5 @@ Status: implemented
 - 显式的对象开放方式和类型正确的字面量约束会让格式错误的声明在编写或注册阶段快速失败，而不是拖到后续模型调用时才失败。
 - 有界类型推导会为常规声明保留有用的精确类型，并将异常深的尾部结构退化为 `JsonValue`；运行时 schema 强制执行在任意深度仍保持精确。
 - 原始工具仍可直接注册范围更广的 JSON Schema，但统一代码生成会把不受支持的 schema 视为未知类型，不会假装自己能够强制执行。
-- 每个属性的 `required: true` 仍是工具作者契约；原有推导路径暴露可选性缺陷后，类型级回归覆盖会锁定必填键不得为可选。
+- 每个属性的 `required: true` 仍是工具作者约定；原有推导路径暴露可选性缺陷后，类型级回归覆盖会锁定必填键不得为可选。
 - 运行时测试和编译期测试覆盖所有根类型、恰好匹配一个分支时的重叠／无匹配行为、原始 schema 的默认开放语义、显式开放方式、有损 JSON 值、类型推导、核心投影和动态投影中的深层嵌套、动态注册中 JSON 不可见的键，以及非普通 schema 数组。
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
index 46ec2eb556..7c13de5842 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
 2026-07-22-slot-type-chain-implementation.md: 2f0ec32766100e492c68c474f8798be3df0a3d15
-2026-07-22-slot-type-chain-implementation.zh.md: 75e89d3f57b96a1699981123e8361c775db2b8a7
+2026-07-22-slot-type-chain-implementation.zh.md: 6ef7eaa7614b88b33f0fa2aa6089e97eb3a45c25
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
index 75e89d3f57..6ef7eaa761 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
@@ -55,7 +55,7 @@ ctx.slots.register({
 
 第四种 `SlotKind`——`'chain'`——把路由权相对 `keyed` 反转：keyed 的分派现场以 `entryKey` 点选占用 slot 的 entry，chain 则由 entry 自荐——owner 只分派一套格式统一的 owner props，永远不知道谁来接管，新的接管包注册进来 owner 零改动。chain 注册携带一个 `select` 纯选择器（`ChainSelect<O, M>`：`(owner) => matched | null`）与可选的 `priority`（升序；同值保持注册序 = 装配序——部署可控的 inject 拓扑——复用 list `order` 的同一稳定排序）；注册缺 `select` 即上文装载即炸情形之一。渲染时 outlet 按链序依次执行各 select：首个非 null 返回值当选，该值以 `matched` 并入组件 props（组件绝不自行重新推导匹配）；返回 `null` 则轮到下一个 entry；全 null 则渲染 owner 的 fallback 体（`ChainRenderOpts`）。
 
-「不接」的判定住在 `select` 里，绝不在挂载后的组件里自探 props：组件为了渲染 null 也得先挂载，其 hook 与 effect 全部白跑，随之而来的挂载/卸载抖动还会破坏 memo 化与 React key 语义；而选择器是纯函数——可单测、零挂载副作用——与「presentation methods are pure functions of `args`」是同一条纪律。纯，就是选择器的契约：不读外部可变状态、不产副作用，路由判定因此完全是 owner props 的函数，每次分派都可安全执行。选择器只做路由，绝不创建新对象——按分派逐次构造对象会让引用每次渲染都换新；把匹配值包成更丰富的面这件事，发生在当选组件内部（以 `matched` 为依赖的 `useMemo`）。
+「不接」的判定住在 `select` 里，绝不在挂载后的组件里自探 props：组件为了渲染 null 也得先挂载，其 hook 与 effect 全部白跑，随之而来的挂载/卸载抖动还会破坏 memo 化与 React key 语义；而选择器是纯函数——可单测、零挂载副作用——与「presentation methods are pure functions of `args`」是同一条纪律。纯，就是选择器的约定：不读外部可变状态、不产副作用，路由判定因此完全是 owner props 的函数，每次分派都可安全执行。选择器只做路由，绝不创建新对象——按分派逐次构造对象会让引用每次渲染都换新；把匹配值包成更丰富的面这件事，发生在当选组件内部（以 `matched` 为依赖的 `useMemo`）。
 
 类型链上，chain entry 的 SlotMap 形状是 `{ kind: 'chain'; scope; owner }`，`owner` 即链的货币；`M`——`matched` prop 的类型——从 select 返回值推导（选择器收窄 union 成员时，`matched` 类型自动随之收窄），且组件位不参与 `M` 的推断，与钉住 inject 份额的 NoInfer 裁定同源（见下文裁定）。owner 侧，`renderSlotChain(key, owner, { fallback })` 与 `renderSlot` 同住 `PropsRenderSlots` 份额，其键域静态收窄到本 entry children 声明中 chain kind 的键（`ChainKeysOf`）；分派现场只有一行，不含任何自有的派生或路由逻辑。
 
@@ -117,5 +117,5 @@ register 签名里的两条硬化裁定之所以存在，是因为显然的替
 | 模块级 store 句柄 | 模块级句柄是跨插件重载与跨测试用例的单例；工厂形把身份圈定在单次 apply/测试调用内 |
 | 组件直收 store 实例 | 渲染代码里能用 `update`/`set`，变更面就无从审计；声明的 actions 让「什么能变」保持为 register 现场的事实 |
 | 注册位用 `FC` / 从组件推断 `I` | FC 静态位产生协变噪音、拒绝合法组件；组件侧推断静默吸收 props 漂移（见上文裁定） |
-| 接管 slot 用 keyed 分派 + owner 侧路由 | owner 会不断攒下逐 entry 契约与硬编码路由表（每种接管一份 `find` + `entryKey`）；chain 货币让新增接管注册保持 owner 零改动 |
+| 接管 slot 用 keyed 分派 + owner 侧路由 | owner 会不断攒下逐 entry 约定与硬编码路由表（每种接管一份 `find` + `entryKey`）；chain 货币让新增接管注册保持 owner 零改动 |
 | 组件靠渲染 null 表示不接 | 不接也得先挂载——hook 与 effect 白跑，挂载/卸载抖动破坏 memo 化与 key 语义；纯选择器无需组件实例即可裁决 |
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
index 831d3c790f..0575e85c1c 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
 2026-07-22-unified-send-and-coalesced-user-messages.md: f32d6ca65d5236e1fabdd177cdf54e36929c853f
-2026-07-22-unified-send-and-coalesced-user-messages.zh.md: af829714276b1a77b8147d89a9be1c9ff6a007a5
+2026-07-22-unified-send-and-coalesced-user-messages.zh.md: 6148cf4e0dda9032fca0ced5b466787877b89fa0
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
index af82971427..6148cf4e0d 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
@@ -50,4 +50,4 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send`
 - [one-send-one-turn](../simplification/2026-07-17-one-send-one-turn.md)——本决策所依托的“每轮次只认领一条消息”规则。
 - [remove-agent-steering-mirror](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md)——折叠镜像实时事件的先例。
 - [explicit-turn-cancellation](2026-07-16-explicit-turn-cancellation.md)——`keepInbox` 所扩展的取消原因信号。
-- [带标识的不可变消息值](2026-07-28-identified-immutable-message-values.md)——本路由决策现在所依托的消息标识与表示契约。
+- [带标识的不可变消息值](2026-07-28-identified-immutable-message-values.md)——本路由决策现在所依托的消息标识与表示约定。
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
index f8a9c8c260..021857e30b 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
 2026-07-23-client-plugin-loading-model.md: 2dc0c68e5f20bd790c2362f92c16dece171babf5
-2026-07-23-client-plugin-loading-model.zh.md: ce7850e37b9ae2735565a35ce3de28f4f290ed04
+2026-07-23-client-plugin-loading-model.zh.md: 8cb8fb5523475fd0cc03fa20fc04422c6b7397e3
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
index ce7850e37b..8cb8fb5523 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -31,7 +31,7 @@ host 侧，cordis 插件装载站在 Node 的模块机制之上——require cac
 - **普通包**是模块系统自身所需的绝对基座，加上尚未转成 DI 的库：react 家族、cordis、`@deepseek-ai/dsh-client-modules`（模块系统本身——它永远不可能是插件，因为模块先于一切模块）、web 壳内核，以及——暂时——ui-slots、web-react、ui-primitives。普通包打进壳 bundle、播种进模块表、对 host 图不可见。
 - **插件包**是其余一切。每个都携带 `dshClient` manifest（元数据清单）声明（`{ platform, inject, immediately? }`）和同一种统一形态：共享 tsdown 预设产出 `lib/client.js`，`exports["./client"]` 指向该 bundle。每个都是 host 独家撰写的图里受治理的 entry。当前包括：connection、runtime、ui-theme、i18n、hmr（仅进 dev 图）、ui-layout、ui-sidebar、ui-conversation、ui-model-selector、ui-question、ui-trajectory。
 
-manifest 拥有包的装载契约：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册与 `--dev` 开关。
+manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `immediately` 预取标记（缺省即 lazy）。负责组合的 app 只拥有名册与 `--dev` 开关。
 
 新增一个插件包：声明 `dshClient`，经共享预设产出 `./client` bundle，把包名加进负责组合的 app 的名册。除此之外无需任何交接。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
index 4be81330b6..d328c8a065 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
 2026-07-24-separate-context-injection-from-turn-execution.md: bb28d96cf1494d94ad7a7d4a4714e536c7072d2f
-2026-07-24-separate-context-injection-from-turn-execution.zh.md: 6debc6cf5e8fb7358ca8697fa64f175fb700d991
+2026-07-24-separate-context-injection-from-turn-execution.zh.md: 0edf3f4e8a062fe82462e263da383e27d79034c5
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
index 6debc6cf5e..0edf3f4e8a 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
@@ -71,4 +71,4 @@ enter 分支的 `PreStepDecision.messages` 是拟议步骤的完整批次。wate
 - idle 注入只有在后续 pre-step 接纳它后才会对模型可见，并可能被取消或 dispose 丢弃，而其持久 inbox 生命周期仍会保留记录。
 - 两条连续的 user-role 消息会取代一条烘焙后的提示词消息；提供方适配器会保留这一顺序。
 - 必须影响当前请求的上下文要从 `agent/pre-step` 返回；普通注入只支持在最近的后续边界交付。
-- 公共投递契约和收件箱记录保持精简：没有上下文附件、上下文放置元数据、提示词封套或重复的持久事件类型。
+- 公共投递约定和收件箱记录保持精简：没有上下文附件、上下文放置元数据、提示词封套或重复的持久事件类型。
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
index 19176b7654..cf3169bccf 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
 2026-07-24-single-harness-home-resolver.md: 159ba88b7b4a8d50f1be2cbe5d9162a654014e16
-2026-07-24-single-harness-home-resolver.zh.md: 89069c8e98e80be387fbc6b1630219b451be7bd6
+2026-07-24-single-harness-home-resolver.zh.md: ed4701bbd4e37ec5c9fba02767efabfbef8d065d
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
index 89069c8e98..ed4701bbd4 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
@@ -32,7 +32,7 @@ explicit configured path  >  $DSH_HOME  >  ~/.dsh
 
 **采用 XDG（遵从 `$XDG_CONFIG_HOME`，或把 config/data/cache 拆分到各自的目录树）。** 经过考虑后放弃，转而采用一个显而易见的根目录。单一的 `$DSH_HOME || ~/.dsh` 基准事实与 `~/.claude` / `~/.aws` 一致，无需对每个 `~/.dsh` 消费方按类别重新归类，也不留下任何需要协调的解析器不对称。telemetry 对齐到同一根目录——而不是保留自己的 XDG 路径——正是本决策所要消除的那种分歧。
 
-**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。代价是匿名 id 的作用域从机器变成了 `$DSH_HOME`：若某个项目把 `DSH_HOME` 指向仓库本地路径（或某条命令在 telemetry 之前加载了项目的 `.env`），得到的就是 home 本地的 id，因此该 id 统计的是 harness home，而非机器。这被接受为单一根目录的应有含义——重定位 `$DSH_HOME` 会移动*全部* harness 状态，telemetry 身份也在其中——模块契约据此表述为 per-harness-home 而非 per-machine。一个忽略 `$DSH_HOME` 的机器级全局身份，恰恰会重新引入本 Note 所要消除的那第二套 home 策略。
+**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。代价是匿名 id 的作用域从机器变成了 `$DSH_HOME`：若某个项目把 `DSH_HOME` 指向仓库本地路径（或某条命令在 telemetry 之前加载了项目的 `.env`），得到的就是 home 本地的 id，因此该 id 统计的是 harness home，而非机器。这被接受为单一根目录的应有含义——重定位 `$DSH_HOME` 会移动*全部* harness 状态，telemetry 身份也在其中——模块约定据此表述为 per-harness-home 而非 per-machine。一个忽略 `$DSH_HOME` 的机器级全局身份，恰恰会重新引入本 Note 所要消除的那第二套 home 策略。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
index 7e3c02691b..06bfd11c4f 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
 2026-07-25-web-client-session-scope-and-provide-channel.md: 3c51f06fca23a495f0fbc0cc4f1c289edea07b3b
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 1319a0d5a4eba4d70b0268605a0957c9a2eca7a9
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: cccc0b6d8f7309c5344e042d9cc2171587a18cb5
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
index 1319a0d5a4..cccc0b6d8f 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
@@ -61,7 +61,7 @@ Session 实例与 scope 同生命周期，存活资格 = host listed（一个判
 
 「实体化但无首讯」的会话经 summary 派生位 `blank` 治理（派生列而非 header 字段，SessionHeader 保持不可变）：
 
-- host 判据：`session.events.length === 0`（零日志事件 = 尚无用户消息）。live 会话 `summarize()` 内存直读；cold 会话恒 `false`——lazy-create 契约保证 never-appended 会话根本不进 `persistence.list()`（JSONL/SQLite 两后端均已实证真 lazy），blank 从不落盘。
+- host 判据：`session.events.length === 0`（零日志事件 = 尚无用户消息）。live 会话 `summarize()` 内存直读；cold 会话恒 `false`——lazy-create 约定保证 never-appended 会话根本不进 `persistence.list()`（JSONL/SQLite 两后端均已实证真 lazy），blank 从不落盘。
 - wire 承载两处：`SessionSummary.blank` 必填列；`host/session-added` 帧必填 `blank` 字段（创建时恒 true，供别的 tab 按同一空会话状态入镜像）。
 - client 镜像只降不升（单调），三来源翻转，全部复用既有 wire 信号：
   - 发送方本地：首次 `prompt()` 的**成功响应**翻 false（受理即证明 user/message 已入 host 日志——此点翻转是确证而非乐观；`onEngaged` 同步更新列表镜像，当前 `New Session` 行原地转为普通标题，不新增列表行）。首讯被拒则会话保持 blank：与 host 权威对齐、继续显示为 `New Session`、在仍为该工作区成员时保持 connectWorkspace 复用资格。
@@ -77,7 +77,7 @@ Session 实例与 scope 同生命周期，存活资格 = host listed（一个判
 - 复用臂：list mirror 中找 `blank && cwd == workspace.path && sessionIds.includes(id)`——host 自己的成员规则，绝不只按 cwd。没有账户槽位的 cwd 匹配（CLI（命令行界面）/TUI 在 host cwd 创建的会话，或已删除/重建的注册）会打开一个任何分组表面都无法显示在该工作区下的会话，因此落到新建臂（见[成员复用修复](../bug-fix/2026-08-05-workspace-blank-session-reuse-membership.md)）；命中直接返回该 id，不新建。
 - 新建臂：未命中则 `session.create({workspaceId})`，返回新 id。
 - 未知 workspaceId fail loud（不静默创建到别处）。
-- 解析保证（两臂同契约）：promise resolve 时返回的 id 已在 list store 且 `sessions.binding(id)` 同步可解析——`SessionsService.create` 在 RPC 成功后同步投影列表再 resolve，使 draft 搬运方可以在 open 之前往新 scope 的 machine 写文本，不等 notifier flush。
+- 解析保证（两臂同约定）：promise resolve 时返回的 id 已在 list store 且 `sessions.binding(id)` 同步可解析——`SessionsService.create` 在 RPC 成功后同步投影列表再 resolve，使 draft 搬运方可以在 open 之前往新 scope 的 machine 写文本，不等 notifier flush。
 - 调用方拿 id 自行 `sessions.open`；首讯发送就是普通 `session.prompt`——会话本来就在，失败即普通 prompt 失败，draft 文本还在 machine 里，重试即再次发送。
 - 全局 New Session 按钮默认取 `recentWorkspaceId`：先比较各 Workspace 内 Session 的最新 `updatedAt`，无 Session 时回退 Workspace `createdAt`，同值保持 Host 顺序；只有完全没有 Workspace 时才 `sessions.clear()` 进入无会话视图。Workspace 分组内的创建动作仍显式命中该 Workspace。
 - 运行时启动时订阅首次完整基线：若已有恢复成功的 current 会话则保持不动，否则自动 `connectWorkspace(recentWorkspaceId)` 并 open 返回的 blank 会话。该策略只结算一次；之后用户主动 clear 不会再次被自动选择覆盖，连接失败则等下一次基线投影重试。
@@ -131,6 +131,6 @@ slot scope 是闭集 `root | session-maybe | session`：
 
 - 插件获得与 host 同构的会话上下文：逐会话状态挂 actx、随 scope fiber 一次拆装，泄漏结构性不可能；双会话隔离由 scope filter 结构性保证。
 - client 对象层收敛为 wire 镜像：会话身份、生命周期、能力判别全部以 host 实体为准——输入体系（下一层）面对的永远是「有真 Agent 的会话」，slash/skill 等提供方一律以 sessionId 直接寻址。
-- 空会话治理零专用机制：状态靠一个派生位，可见性靠统一列表投影（仅 current blank 以 `New Session` 展示），回收靠 lazy persistence 的既有契约（重启蒸发），常规上限靠同 Workspace 复用。
+- 空会话治理零专用机制：状态靠一个派生位，可见性靠统一列表投影（仅 current blank 以 `New Session` 展示），回收靠 lazy persistence 的既有约定（重启蒸发），常规上限靠同 Workspace 复用。
 - 代价：id→ctx 换乘纪律、provide 的 Concurrent 纪律都是约定而非类型强制，靠 review 与测试钉住；「未选 workspace」期间输入全禁是产品面接受的体验代价（单一状态轴换来的）。
 - 已知欠账：approval/question 跨 prune 恢复（TODO）；模型选择以 live-mutation 形状回归（host `selectModel` 三件套现成，等独立分支）。
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml
index 1742b6587e..f53930928f 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md
 2026-07-25-web-command-surfaces-and-assembly.md: 4c4a400abab940baebc1699fc15b709419865f0c
-2026-07-25-web-command-surfaces-and-assembly.zh.md: 092401751aa16c1a0ec4446d85a9f2591ee18425
+2026-07-25-web-command-surfaces-and-assembly.zh.md: f0d460199dcd947776924380d51fa6ceb65c9fe2
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
index 092401751a..f0d460199d 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 
 ### ui-command：`CommandService` + 按会话键控的 `CommandDirectory` + 逐会话 `PopupSelectController`
 
-- 投影 `ClientSessionContext { sessionId }` 自持于 ui-slash 契约（types.ts）：会话恒 agent-backed，会话身份即命令能力的全部投影；wire 以 `{sessionId}` 寻址（`command.list` / `command.execute` 均是；host 从会话 header 解析 Agent）。
+- 投影 `ClientSessionContext { sessionId }` 自持于 ui-slash 约定（types.ts）：会话恒 agent-backed，会话身份即命令能力的全部投影；wire 以 `{sessionId}` 寻址（`command.list` / `command.execute` 均是；host 从会话 header 解析 Agent）。
 - 目录按 `SessionId` 分区，per-key single-flight + epoch guard（旧拉取永不覆盖新态），`commands/changed` 全 key 软失效（旧快照继续服务、后台重拉）、`connection/reset` 全 key 硬失效并预热，Enter 必须等待当前 key 就绪、失败留草稿不降级。预热挂 source 的 `warm` 钩子——scope 出生时对全 roster 一次，即覆盖整个会话生命周期（会话能力自出生恒定）。
 - `register(contribution)` 注册 client 命令（descriptor + `available(projection)` + popupSelect spec）；候选合成 = host 目录 + contribution 可用性过滤，再过 query/position，host/contribution 重名 fail loud。
 - 命令三型按注册面派生，开发者不声明位置：host descriptor 带 `input` = **leadingInput**（回填 `/name ␣` + claim，继续打参数，仅限行首）；client 注册 popupSelect spec = **popupSelect**（官方选择框壳，业务零组件）；两者皆无 = **execute**（选中即执行，零 UI）。
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
index f22f2340ac..5605f1681e 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
 2026-07-25-web-input-machine-and-slash-pipeline.md: 39ef214a94fcd019f535fb60136d5dcc09b54e60
-2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 9b0ca0cadbc5e0212048b165f0d60d567a5639ad
+2026-07-25-web-input-machine-and-slash-pipeline.zh.md: dbd1aebff58c12f33dfe146d5cf4895801035bce
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
index 9b0ca0cadb..dbd1aebff5 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
@@ -50,7 +50,7 @@ occurrence 表与 chip 三投影：
 
 ### 跨插件输入改写：三个 scoped bail 事件
 
-契约声明在 ui-slash（依赖最底层），生产者经 `sctx.bail(sctx, ...)` 派发，唯一消费侧是 hub 建 shell 时挂在 sctx 上的三个 listener；返回 `true` ⟺ 机器过 phase + CAS 守卫并实际改写（发出事件 ≠ 修改成功，Space 是否 `preventDefault` 以返回值为准）：
+约定声明在 ui-slash（依赖最底层），生产者经 `sctx.bail(sctx, ...)` 派发，唯一消费侧是 hub 建 shell 时挂在 sctx 上的三个 listener；返回 `true` ⟺ 机器过 phase + CAS 守卫并实际改写（发出事件 ≠ 修改成功，Space 是否 `preventDefault` 以返回值为准）：
 
 - `slash/input-begin-command` `{claim, span}`——菜单 pick / Space 裁决出的命令 claim 回填（SlashController 派发）。
 - `slash/input-insert-reference` `{reference, span}`——引用 chip 插入（SlashController 派发）。
@@ -74,13 +74,13 @@ occurrence 表与 chip 三投影：
 - ConversationRoot 的 Hero 判据是 `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || summaryBlank === true))`：summary 已证实为空的 Session 在任何 open state 下都保持 Hero，未经证实的 Session 则在 loading 期间进入 settling。首次 submit 同步进入 engaging，失败也保留 composer 与错误上下文，不退回 blank Hero；sidebar 的 blank 位只在 prompt 成功受理后翻 false。
 - 发送统一在 hub defaultSink：乐观清稿后只走 `session.prompt` 且固定 `mode:'queue'`（Web UI 无 steer 入口；host 线缆上的 `mode:'steer'` 不经此 machine）；失败且 live draft 仍为空才回填，用户已经继续输入则不覆盖。不存在 Draft materialize 或 attach 事务。
 - blank Hero 改选 Workspace 时，外壳调用 `connectWorkspace`；目标 session 不同时把非空 draft 从当前 shell 搬到目标 shell，再 open 新 id，旧 blank session 留存但不再 current。
-- Notifier 双位契约：`dirty`（快照新鲜度，`ensureFresh` 拉取可清）与 `notifyPending`（通知欠账，只有 flush 清）各自独立——拉取不得吞推送，对象层推订阅者（watchTransaction）依赖这一保证。
+- Notifier 双位约定：`dirty`（快照新鲜度，`ensureFresh` 拉取可清）与 `notifyPending`（通知欠账，只有 flush 清）各自独立——拉取不得吞推送，对象层推订阅者（watchTransaction）依赖这一保证。
 
 ### 纯文本引用（决策 21）：text outcome 与 lexicon 装饰
 
 skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把 `/name ` `@name ` 原文插进 draft，chip 视觉纯派生：
 
-- PickOutcome 增 `{text}` arm；新 scoped bail 事件 `slash/input-insert-text` `{text, span}`（与另三个同契约：draftRev CAS、返回 true ⟺ 实际改写）；facade.insertText 走 setDraft 拼接，机器零改动。
+- PickOutcome 增 `{text}` arm；新 scoped bail 事件 `slash/input-insert-text` `{text, span}`（与另三个同约定：draftRev CAS、返回 true ⟺ 实际改写）；facade.insertText 走 setDraft 拼接，机器零改动。
 - source 可选 `lexicon?(session)` 钩子：同步热快照名录，`undefined` = 数据未热——零装饰、永不触发 fetch（渲染路径保持同步无副作用）；配对的可选 `subscribeLexicon?(session, listener)` 钩子是名录在 warm 之后仍会变化（目录 settle、子代生灭）时的失效通道。controller 把各名录聚合进自己的 `lexicon` snapshot store（每次 source 通知重拉）；scope 出生后才注册的 source 由 service 广播给活 controller，补 warm 并并入名录。
 - `decorations.scanTextRefs`：词边界扫描 draft（行首/空白后的 `/name`、`@name`，`x/name` 永不命中）对照名录，命中即 `.textRef` mark（backdrop 纯 range 高亮，同 hlToken）；编辑破坏匹配形状下次扫描自然消失。
 - 发送即原文（不再 `<skill>` 序列化）；气泡侧 MessageItem 双形状装饰（legacy `<skill>` 标签 + 纯文本 token）。
@@ -116,7 +116,7 @@ skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把
 | ActiveCommand 中间态 / registerMode 模式注册表 / 从 draft 推导命令态 | claim 由 pick 路径显式建立——无表、无推导 |
 | bindTarget/bindDraft 对象直连 | 反向耦合 + root 单例跨会话误配；scoped bail 事件保依赖倒置且路由结构性正确 |
 | 统一 slash/input-apply 或全事件化 | 三个独立 payload 覆盖跨插件改写；异步链路保持 registry 显式调用 |
-| contenteditable / 富文本树 | 兼容性差；textarea + U+FFFC + occurrence 表覆盖全部交互契约 |
+| contenteditable / 富文本树 | 兼容性差；textarea + U+FFFC + occurrence 表覆盖全部交互约定 |
 | draft 双持久化 {text, occurrences} | mirror 写剪贴板投影零新概念；chip 跨刷新降级可接受 |
 | 原生 textarea undo 栈 | 受控 + 程序化写入下不可靠；粘贴两段 undo 语义只能自管 |
 | InputBar 收 16 员 wiring 回调包 | 消费矩阵实证 11 员 InputBar 独占、1 员死成员；标准件通道让组件自取，键盘面包内私递 |
@@ -130,6 +130,6 @@ skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把
 ## 后果
 
 - 一个常驻 conversation 外壳承接 no-session/blank/active：无 session → blank 保持 ConversationRoot、Hero、root scope Workspace picker、scrollport、composer seat、InputBar 与 textarea；只有严格 session header 和 body outlet 开始承载内容。同一 blank session → engaging/active 也保持 InputBar 与 textarea。EmptyState 与受控 intent 链（`sessions.updateIntent`/`updatePendingPrompt`/`workspaces.sendSession`）随最后消费者一并删除。
-- 输入面对命令零知识 + 可选依赖：无命令包时纯输入可用；`@` 引用与 skill 引用免费复用同一菜单/pick 管线。代价是空格/回车裁决是逐 source 轮询协议，其应答语义（同步/异步、undefined 含义）为冻结契约。
+- 输入面对命令零知识 + 可选依赖：无命令包时纯输入可用；`@` 引用与 skill 引用免费复用同一菜单/pick 管线。代价是空格/回车裁决是逐 source 轮询协议，其应答语义（同步/异步、undefined 含义）为冻结约定。
 - 提交事务化（attempt seq + 漂移守卫）使晚到结果回灌、会话切换、concurrent 重放三类缺陷结构性不可能，由矩阵测试钉住。
 - 已知欠账：chip 跨刷新保真（可复用粘贴匹配）未立项；subagent 引用的模型表示待业务立项。
diff --git a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml
index 881981631c..938d86ef4b 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md
 2026-07-26-packed-chunk-rows-by-default.md: d6a044676604e4a4512a7a6674edb80e120b2f3c
-2026-07-26-packed-chunk-rows-by-default.zh.md: 2488ab1d972b89b1248733482e8e4239b83797e2
+2026-07-26-packed-chunk-rows-by-default.zh.md: 0e3e06e0d4185603cd21939589855a51797560a4
diff --git a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
index 2488ab1d97..0e3e06e0d4 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
@@ -26,7 +26,7 @@ JSONL 后端会打包每个持久追加批次。原始模式 `compression: 'none
 
 每个签入仓库的会话格式 JSONL fixture 都使用规范打包表示。`scripts/session-fixture-layout.snapshot.ts` 会在整个仓库中发现已跟踪的 `*.jsonl` 文件，以及未被忽略的新增未跟踪 JSONL 文件，选择首条记录为 `session` header 的文件，解码所有正文记录，并拒绝与 `packChunkRuns()` 输出不同的内容。因此，该清单无需维护路径列表即可覆盖 ACP、headless、TUI、`apps/web`、父会话、子会话以及未来的 fixture 名称。
 
-ACP 和 headless 快照运行会采集默认 JSONL 后端的输出。TUI 和 web 的记录模式写入器会在写入 fixture 前，对内存事件应用 `packChunkRuns()`。人工编写的 `packed-chunks` ACP 场景在普通配置下运行，并保留全部 3 种打包行类型；其契约先解码独立的源 fixture 和目标 fixture，再断言二者逐事件相等。
+ACP 和 headless 快照运行会采集默认 JSONL 后端的输出。TUI 和 web 的记录模式写入器会在写入 fixture 前，对内存事件应用 `packChunkRuns()`。人工编写的 `packed-chunks` ACP 场景在普通配置下运行，并保留全部 3 种打包行类型；其约定先解码独立的源 fixture 和目标 fixture，再断言二者逐事件相等。
 
 聚焦的包测试保留非打包和混合布局输入，以验证读取器兼容性。这些测试不会让默认快照语料库豁免规范布局要求。
 
@@ -36,9 +36,9 @@ ACP 和 headless 快照运行会采集默认 JSONL 后端的输出。TUI 和 web
 
 只要较旧分支仍可能携带 fixture 改动，测试政策和 ACP 快照 README 就会继续链接该命令。最新的开放 PR（Pull Request）清单确认每个受影响分支均已合并、关闭或符合规范后，[移除提案](../../proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)会删除该 CLI、包命令、本过渡章节和文档链接，并替换永久门禁中仅适用于该命令的修复指引。共享规范布局转换器与快照门禁保持永久存在。
 
-### 验证契约
+### 验证约定
 
-JSONL 持久化测试证明：省略选项时会写入打包行，显式传入 `false` 时会按每个事件一行的形式写入，两种形式都会加载为完全相同的事件。规范布局转换器单元测试覆盖 header 保留、非打包转换、非会话 JSONL、已打包输入的幂等性和畸形输入。无密钥快照门禁覆盖每个签入仓库的 fixture 和组装后的回放路径；文档门禁则确保配置默认值与双语契约保持一致。
+JSONL 持久化测试证明：省略选项时会写入打包行，显式传入 `false` 时会按每个事件一行的形式写入，两种形式都会加载为完全相同的事件。规范布局转换器单元测试覆盖 header 保留、非打包转换、非会话 JSONL、已打包输入的幂等性和畸形输入。无密钥快照门禁覆盖每个签入仓库的 fixture 和组装后的回放路径；文档门禁则确保配置默认值与双语约定保持一致。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
index 9b9fd5aad6..6b969a2c03 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
 2026-07-26-task-registry-seam.md: 57ac176cf6d2b0a50fcbcfacd77f6a26b462b582
-2026-07-26-task-registry-seam.zh.md: d32de0cc62e1d7a2b5e5d70187e742aa0392fe29
+2026-07-26-task-registry-seam.zh.md: b81940a8f778f1ed9a65bf96e3a66c047fd234c2
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
index d32de0cc62..b81940a8f7 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
@@ -6,30 +6,30 @@ Status: implemented
 
 ## 问题
 
-[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包：`@deepseek-ai/dsh-tasks` 既拥有每个生产方和控制接口面向编程的 `ctx.tasks` 契约，也拥有进程内实现（内存存储、结算簿记、所有者清理 effect、拆除）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制接口（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` 接口。harness 中其余每项可替换能力——bash、pty、fs、skill（技能）、subagent、web、会话持久化——都已具备接口／实现／消费方三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
+[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包：`@deepseek-ai/dsh-tasks` 既拥有每个生产方和控制接口面向编程的 `ctx.tasks` 约定，也拥有进程内实现（内存存储、结算簿记、所有者清理 effect、拆除）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制接口（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` 接口。harness 中其余每项可替换能力——bash、pty、fs、skill（技能）、subagent、web、会话持久化——都已具备接口／实现／消费方三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
 
 ## 决策
 
 `tasks/` 如今是一个 bash 三件套形态的三包能力家族：
 
-- **`@deepseek-ai/dsh-tasks`（接口）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的契约（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachSurface`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个实现都必须兑现的语义：注册的存续期长于生产方与控制接口的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且在没有附加任何控制接口时 `start` 拒绝启动工作。
+- **`@deepseek-ai/dsh-tasks`（接口）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的约定（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachSurface`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个实现都必须兑现的语义：注册的存续期长于生产方与控制接口的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且在没有附加任何控制接口时 `start` 拒绝启动工作。
 - **`@deepseek-ai/dsh-tasks-local`（实现）**——`LocalTaskService`，即原样迁移的进程内注册表：内存存储、按 kind 划分的计数器、等待方簿记、`TASK_WAIT_TIMEOUT` deadline 代码、所有者清理 effect，以及强制失败的拆除。`dsh-timeout` 依赖随之迁入此包；seam 包不含任何实现依赖。
 - **`@deepseek-ai/dsh-tool-tasks`（消费方）**——保持不变；它注入 `'tasks'`，从不导入实现类型。
 
 各组合在原先加载 `dsh-tasks` 的位置改为加载 `dsh-tasks-local`：CLI（命令行界面）的 cordis.yml 配置项、`agent-spine-demo`、各测试 harness，以及工具目录生成器的启动流程。生产方的配置错误诊断信息（「background tasks unavailable: load …」）点名 `dsh-tasks`——即定义缺失的 `ctx.tasks` 服务的 seam 包；seam 自身的对外呈现（其 README 与直接挂载防线）会指向各实现，因此当另一个后端日后成为推荐默认时，生产方的消息依旧正确。生产方、`TaskKindMap` 声明合并和控制接口仍然只导入 `@deepseek-ai/dsh-tasks`。
 
-该 seam 保持进程内契约语义不变：`TaskStart.run()` 仍然传入回调和确切的 `Agent` 对象，因此持久化或跨进程后端在能实现此接口之前仍有设计工作要做（身份、重启、所有权、观察）。这次拆分把该项未来工作移出了每个消费方的依赖图；它并不预先设计后端。
+该 seam 保持进程内约定语义不变：`TaskStart.run()` 仍然传入回调和确切的 `Agent` 对象，因此持久化或跨进程后端在能实现此接口之前仍有设计工作要做（身份、重启、所有权、观察）。这次拆分把该项未来工作移出了每个消费方的依赖图；它并不预先设计后端。
 
 ## 曾考虑的替代方案
 
-**在第二个后端出现之前保持具体服务（维持现状）。**这正是运行时 Agent Note 当初的立场：在第二种实现出现前抽取接口，可能固化错误的边界。该方案落选，因为这条边界已不再是臆测：八个服务方法及其语义自引入以来在每一次生产方集成中都保持稳定，它们正是 `dsh-tool-tasks` 与各生产方已经面向编程的那套接口，而且仓库约定默认将可替换能力拆成三个包。剩余风险（持久化后端可能需要变更契约）不因这次拆分而改变：无论拆分与否，这类变更都会落在 seam 包里；而若维持现状，它们今天还会连带搅动每个消费方的实现依赖。
+**在第二个后端出现之前保持具体服务（维持现状）。**这正是运行时 Agent Note 当初的立场：在第二种实现出现前抽取接口，可能固化错误的边界。该方案落选，因为这条边界已不再是臆测：八个服务方法及其语义自引入以来在每一次生产方集成中都保持稳定，它们正是 `dsh-tool-tasks` 与各生产方已经面向编程的那套接口，而且仓库约定默认将可替换能力拆成三个包。剩余风险（持久化后端可能需要变更约定）不因这次拆分而改变：无论拆分与否，这类变更都会落在 seam 包里；而若维持现状，它们今天还会连带搅动每个消费方的实现依赖。
 
 **在单个包内仅抽取接口（在具体类旁导出一个抽象类）。**否决，因为它在运作层面并未分离任何东西：消费方依然依赖携带实现及其依赖项的那个包，而替换后端若不把本地实现纳入自身依赖图，就仍然无法发布。在这里，包边界才是独立演进的单位。
 
-**拆出 `types.ts` 但让服务保持具体。**基于同样的理由否决：类型并不是 seam，`ctx.tasks` 及其方法契约才是。生产方需要的是服务键和语义，而不只是类型形状。
+**拆出 `types.ts` 但让服务保持具体。**基于同样的理由否决：类型并不是 seam，`ctx.tasks` 及其方法约定才是。生产方需要的是服务键和语义，而不只是类型形状。
 
 ## 后果
 
-换来的是：任务注册表如今与全仓库通行的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的同级包，这样的注册表落地时，任何生产方、控制接口或 `TaskKindMap` 扩展方都无需改动。seam 包的 README 陈述契约；生命周期簿记方面的事实归实现包的 README 所有。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；seam 包保留一个桩子类（stub subclass）测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
+换来的是：任务注册表如今与全仓库通行的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的同级包，这样的注册表落地时，任何生产方、控制接口或 `TaskKindMap` 扩展方都无需改动。seam 包的 README 陈述约定；生命周期簿记方面的事实归实现包的 README 所有。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；seam 包保留一个桩子类（stub subclass）测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
 
 代价是：多出一个包，即多一份 manifest（元数据清单）、tsconfig、README 与不变式配套插件；同时各组合必须点名实现包。`abstract` 在运行时会被擦除，而这个包名过去正是可挂载的具体注册表，因此直接挂载 seam 时，其构造函数会明确报错——一条陈旧的组合配置行会在加载时得到「load an implementation such as @deepseek-ai/dsh-tasks-local」，而不是一个未完整注册的 `ctx.tasks` 在远离错误配置处才失败。
diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
index 1c6a23eec8..132c12bbf7 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.md
 2026-07-27-compiler-independent-typert-model.md: 15641e5f785c5d2daecbfc2d5cffedd64d8384a7
-2026-07-27-compiler-independent-typert-model.zh.md: 7bddd3ffde343346c163f55ef493c32bad1e8314
+2026-07-27-compiler-independent-typert-model.zh.md: 409dbc7eb20cc746c2ebb2a891384d65d7da1bc6
diff --git a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
index 7bddd3ffde..409dbc7eb2 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md
@@ -22,7 +22,7 @@ PackageModel 识别 Cordis service、event、`@typert object` 引用对象和 `@
 
 [`dsh-typert-registry`](../../../../packages/typert/registry/README.md) 提供 `ctx.typert`，且只负责运行时注册：一个 contribution 原子携带 package-face reflection 与可选 Zod schema，并随 Cordis effect 撤销。注册表不分析 TypeScript，也不合并两个 face。JSON Schema 是对已注册 Zod schema 的按需投影。
 
-包产物发布仍通过 package exports 采用显式 opt-in。`WorkspaceTypertGenerator` 仅在被调用时校验所请求 face 的根目录产物协议：host face 必须通过面向用户的 subpath `package/typert` 暴露 `package/lib/typert.host.{js,d.ts}`，client face 必须通过 `package/client/typert` 暴露 `package/lib/typert.client.{js,d.ts}`；它不会修改这些 exports。后续的 [TypeRT Remote 设计](2026-08-02-typert-remote-method-calls.md) 为根目录 build、typecheck、lint 与文档类型检查增加了全仓 Host 契约 pass。对于已 opt-in 的 Host 包，该 pass 会在消费方解析两者之前生成本地反射产物与严格的 Host-for-Client `/remote` 契约。生成的本地声明将 `TYPERT` 类型保持为 `unknown`，因此业务包不依赖注册表。
+包产物发布仍通过 package exports 采用显式 opt-in。`WorkspaceTypertGenerator` 仅在被调用时校验所请求 face 的根目录产物协议：host face 必须通过面向用户的 subpath `package/typert` 暴露 `package/lib/typert.host.{js,d.ts}`，client face 必须通过 `package/client/typert` 暴露 `package/lib/typert.client.{js,d.ts}`；它不会修改这些 exports。后续的 [TypeRT Remote 设计](2026-08-02-typert-remote-method-calls.md) 为根目录 build、typecheck、lint 与文档类型检查增加了全仓 Host 约定 pass。对于已 opt-in 的 Host 包，该 pass 会在消费方解析两者之前生成本地反射产物与严格的 Host-for-Client `/remote` 约定。生成的本地声明将 `TYPERT` 类型保持为 `unknown`，因此业务包不依赖注册表。
 
 构建期的 `CordisCatalogProjector` 一次消费分析后的 `FaceModel` 与 `TypeGraph`，生成 `docs/cordis-catalog/events.md`、`docs/cordis-catalog/services.md`，以及为 `tool-cordis` 提交的静态 `SERVICE_API`、`EVENT_API` 和 `TYPE_API` catalog。`tool-cordis` 读取该静态 catalog，运行时不依赖 `ctx.typert`。[`dsh-typert-loader`](../../../../packages/typert/loader/README.md) 与注册表仍是独立的运行时路径：loader 监听 Cordis Loader 配置项生命周期事件，导入显式发布的 `./typert` host 产物，并通过 `ctx.typert` 注册；两者都不是当前 `cordis_inspect` catalog 的数据源。
 
@@ -50,4 +50,4 @@ Zod emitter 对支持的节点和各类 literal 逐类执行成功与失败 pars
 
 新增生成目标或静态检查可复用同一 TypeGraph，业务类目也可在 PackageModel 上扩展，而无需再次解析 AST。保留计算前类型和独立 face 的代价是模型比打平后的 schema 更复杂，emitter 必须显式声明支持范围并对缺失能力失败。
 
-包级显式 opt-in 使产物发布与 exports 由各包自行管理。仓库编排仍可为每个已 opt-in 的包运行全仓 Host 契约 pass；该 pass 仍由后续 Remote Gateway Agent Note 负责说明。静态 Cordis catalog 可从标准模型复现，同时不把 `tool-cordis` 与运行时注册表状态耦合。`ctx.typert` 只反映当前运行时中已挂载的产物；对于消费方直接导入后仍持有的 Zod 实例，卸载流程无法控制。
+包级显式 opt-in 使产物发布与 exports 由各包自行管理。仓库编排仍可为每个已 opt-in 的包运行全仓 Host 约定 pass；该 pass 仍由后续 Remote Gateway Agent Note 负责说明。静态 Cordis catalog 可从标准模型复现，同时不把 `tool-cordis` 与运行时注册表状态耦合。`ctx.typert` 只反映当前运行时中已挂载的产物；对于消费方直接导入后仍持有的 Zod 实例，卸载流程无法控制。
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
index 1f44d8b4b7..cf0c363672 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
 2026-07-27-dispose-ladder-to-consumer.md: e9af88e8e7ef962213a74e96a249241cbe8d5994
-2026-07-27-dispose-ladder-to-consumer.zh.md: 74cbc624e9153637dcdceb521c04af811799fdb0
+2026-07-27-dispose-ladder-to-consumer.zh.md: afa385120d6ac33e6084a56585d8d610622e604c
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
index 74cbc624e9..afa385120d 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**把阶梯作为便利方法留在句柄上。**否决：一个每个实现都必须提供的 seam 方法不是便利，而是契约表面——而这一个把某一消费方的配合形状（stdin EOF 打头）当作进程词汇来编码。seam 自己的 README 早已不得不加注「依赖其他信号才能完全停稳的子进程需要自己的第一阶」，这本身就是承认该阶梯是策略。
+**把阶梯作为便利方法留在句柄上。**否决：一个每个实现都必须提供的 seam 方法不是便利，而是约定表面——而这一个把某一消费方的配合形状（stdin EOF 打头）当作进程词汇来编码。seam 自己的 README 早已不得不加注「依赖其他信号才能完全停稳的子进程需要自己的第一阶」，这本身就是承认该阶梯是策略。
 
 **把阶梯移到共享辅助包。**否决：只有一个消费方。当第二个具有相同 stdin EOF 配合形状的进程外后端出现时，可以再把 `disposeAcpChild` 提升为共享代码；现在抽取只会重造 `dsh-subagent-subprocess`——这组堆叠变更刚刚删掉的那个单一用途库。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
index 048536527a..018c4812b1 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
 2026-07-28-directory-picker-capability-seam.md: 01968990db81852dbf965a90fc151bab357ecb55
-2026-07-28-directory-picker-capability-seam.zh.md: ffbb939eabcca3e16711a4cadcadad50660a9e04
+2026-07-28-directory-picker-capability-seam.zh.md: f96f835c5f68d0ef6eff5410a7db18dc24eb8c2c
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
index ffbb939eab..f96f835c5f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
@@ -6,13 +6,13 @@
 
 ## 问题
 
-web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入缝）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互契约**，不是同一契约的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
+web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入缝）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互约定**，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
 
 ## 决策
 
-在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一契约方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。
+在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一约定方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。
 
-**client 侧靠 slot 组合，而非按广播分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 契约相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 广播与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的 wire 事实不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。
+**client 侧靠 slot 组合，而非按广播分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 约定相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 广播与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的 wire 事实不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。
 
 并入本决策的位置与策略裁决：
 
@@ -29,7 +29,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick
 
 ## 曾考虑的替代方案
 
-- **给 `ctx.fs` 增加浏览方法。** 否决：上述权限域耦合；且面向展示的列举契约（hidden 标志、面包屑、home 锚点）不属于存储 seam。
+- **给 `ctx.fs` 增加浏览方法。** 否决：上述权限域耦合；且面向展示的列举约定（hidden 标志、面包屑、home 锚点）不属于存储 seam。
 - **统一方法集的 seam（`pick(): path`）。** 否决：应用内浏览器无法藏在一次宿主侧调用后面——浏览循环在客户端，需要协议上的原语；而对话框实现不了原语。交互差异不可约，故用判别标签。
 - **apiproxy 里直接调标准库（不建 seam）。** 否决：换装点仍是改网关源码，失去 fixture／测试后端，与促成这项工作的插件教义相悖。
 - **引入文件管理器／盘符枚举依赖。** 按上文调研否决；依赖政策要求记录于此。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml
index 187db47b0d..43e4b3d605 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.md
 2026-07-28-experimental-plugin-package-group.md: 1ebae5dbb16d4c966f94ffde69fb0cb9bc163d80
-2026-07-28-experimental-plugin-package-group.zh.md: 633549bd47386de3eeb972052ecfdd164878e2f1
+2026-07-28-experimental-plugin-package-group.zh.md: 2d09451c5069a775906e5bc8748c334c29008164
diff --git a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md b/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md
index 633549bd47..2d09451c50 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md
@@ -10,15 +10,15 @@ Status: implemented
 
 ## 决策
 
-[`packages/experimental/AGENTS.md`](../../../../packages/experimental/AGENTS.md) 中的子树规则要求所有公开契约整体处于实验状态或仅限内部使用的 Cordis 插件包位于 `packages/experimental/<pkg>/`。包名仍为 `@deepseek-ai/dsh-<pkg>`。
+[`packages/experimental/AGENTS.md`](../../../../packages/experimental/AGENTS.md) 中的子树规则要求所有公开约定整体处于实验状态或仅限内部使用的 Cordis 插件包位于 `packages/experimental/<pkg>/`。包名仍为 `@deepseek-ai/dsh-<pkg>`。
 
 该分组供团队在仓库内共享工程人员和产品经理制作的原型：成员可以基于真实插件图发现、运行、评审并扩展彼此的原型，但这不代表产品会提供支持。
 
 官方发布版本不包含此目录。包只有移入对应的产品角色分组后才会纳入发布版本；发布包不得在运行时依赖此处的包。示例可以使用这些包；其他任何运行时依赖方也必须位于此处。测试可以将它们用作开发依赖。
 
-实验性包不提供稳定性、兼容性、迁移或支持保证：其 API、配置或数据可以变更，包也可以移除，均不提供弃用期或迁移路径。内部专用包可以定义范围更窄的内部契约，但不作公开发布承诺。无论哪种状态，都不降低仓库对工程、安全、文档、生命周期、测试或快照的要求。
+实验性包不提供稳定性、兼容性、迁移或支持保证：其 API、配置或数据可以变更，包也可以移除，均不提供弃用期或迁移路径。内部专用包可以定义范围更窄的内部约定，但不作公开发布承诺。无论哪种状态，都不降低仓库对工程、安全、文档、生命周期、测试或快照的要求。
 
-尚待完成的 `@deepseek-ai/dsh-tui-session-changes` `/diff` 查看器和 `/btw` 插件都受这项规则约束。将包提升为稳定包并纳入官方发布版本，需要明确评审其公开契约、限制和测试证据，并指定一名愿意承担稳定包义务的负责人。
+尚待完成的 `@deepseek-ai/dsh-tui-session-changes` `/diff` 查看器和 `/btw` 插件都受这项规则约束。将包提升为稳定包并纳入官方发布版本，需要明确评审其公开约定、限制和测试证据，并指定一名愿意承担稳定包义务的负责人。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml
index 34bdadf75b..307dc12518 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md
 2026-07-28-identified-immutable-message-values.md: 472de8b133ba323c3e1ff5e53c8dacb3d66525c5
-2026-07-28-identified-immutable-message-values.zh.md: 6082fd5fb65f4acd0759a6c4b49be8110a559a73
+2026-07-28-identified-immutable-message-values.zh.md: d322ff93765294478d2adce41a5903f3a7fdd67d
diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
index 6082fd5fb6..d322ff9376 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
@@ -16,7 +16,7 @@ harness 曾存在多种形似消息的表示，各自采用不同的标识规则
 
 `createMessage(input)` 是角色通用的规范创建边界。它会生成 `MessageId`，将传入的角色、内容和来源与调用方对象解除引用关系，并在返回完整值前将其深度冻结。`createUserMessage({ content, source })` 为提示词和上下文生产方固定 user 角色。`createAssistantMessage({ content, source })` 同时固定 assistant 角色与模型来源类别，因此模型输出生产方只需提供内容和模型溯源信息。所有创建辅助函数的输入都不包含 id，因此调用方不会意外地把新消息的创建伪装成已有消息的导入。`freezeMessage(message)` 是独立的导入或转换边界：它会将已有标识的消息与调用方对象解除引用关系并深度冻结，不会生成替代标识。
 
-这些辅助函数位于基础消息词汇旁的 `dsh-llm` 中，因为它们的完整契约只依赖该词汇。`createToolResultMessage()` 与其他创建辅助函数同属此处：它使用同一个工具调用 id，将工具来源与确切的 user-role 工具结果块耦合起来，不依赖会话状态或事件。`dsh-session` 只消费完整消息，不负责构造它们。
+这些辅助函数位于基础消息词汇旁的 `dsh-llm` 中，因为它们的完整约定只依赖该词汇。`createToolResultMessage()` 与其他创建辅助函数同属此处：它使用同一个工具调用 id，将工具来源与确切的 user-role 工具结果块耦合起来，不依赖会话状态或事件。`dsh-session` 只消费完整消息，不负责构造它们。
 
 `Agent` 接口通过 `followup`、`steer` 和 `inject` 接收完整的 `UserMessage`。这些操作绝不会分配或返回标识；它们会冻结导入的值，而调用方已经持有该值的 id。inbox 领取和 `agent/pre-step` 会直接接收该消息。改写内容时会创建具有相同 id 的冻结替代值，而每个附加上下文都是单独创建的 `UserMessage`，拥有自己的 id。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
index 8cd6ad419a..3964ed6d04 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md
 2026-07-28-portable-execution-world-consumers.md: 2cfdf08ac369048994ebc64d498caaa0847b77de
-2026-07-28-portable-execution-world-consumers.zh.md: ce6650a284e7d64fb1277c758bb77c2394e942c8
+2026-07-28-portable-execution-world-consumers.zh.md: 7e33c77d7ed901c955eb9a7b30f3e8c681e41940
diff --git a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
index ce6650a284..7e33c77d7e 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 只有文件操作、命令、终端和语言服务器共享同一个沙箱身份时，远程编码世界才有用。若把完整 harness 移入该沙箱，还会把提供方实验与插件加载、凭据、模型传输、会话持久性、监督和部署纠缠在一起。
 
-普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期契约。
+普通管道无法满足其中一项要求。持久终端需要分配 PTY、检查前台进程组并发送信号，以及清理完整的终端会话。如果假设可以在 `dsh-pty-local` 中基于普通 `spawn()` 句柄重建这些操作，最终不是泄漏提供方内部细节，就是削弱其生命周期约定。
 
 ## 决策
 
@@ -46,7 +46,7 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 **为每项能力或工具创建独立沙箱。** 不予采纳，因为文件与进程操作将无法共享身份或状态，从而破坏编码用例，并增加生命周期所有者的数量。
 
-**把终端建模为普通的管道子进程。** 不予采纳，因为管道无法分配控制终端、确定当前前台进程组或证明完整终端会话已清理。一项终端原语比公开特定于执行基底的逃生口更小，也更能如实表达契约。
+**把终端建模为普通的管道子进程。** 不予采纳，因为管道无法分配控制终端、确定当前前台进程组或证明完整终端会话已清理。一项终端原语比公开特定于执行基底的逃生口更小，也更能如实表达约定。
 
 **把 PTY 就绪判断与会话策略移入进程管理服务。** 不予采纳，因为这些属于持久终端消费方的语义，而非 OS 进程机制。进程管理提供方负责只有其执行基底才能完成的操作；`dsh-pty-local` 负责 Harness 终端的语义。
 
@@ -56,11 +56,11 @@ E2B 负责可变文件系统、受管命令与 Bash 进程、终端分配与终
 
 **在远程环境中运行整个 harness。** 不予采纳，因为这是另一种部署模型。让执行能力可移植，并不意味着移动模型调用、会话状态、插件状态或 agent loop。
 
-**把所有提供方操作都放进一个共享所有者包。** 不予采纳，因为沙箱身份与生命周期是所有者唯一的关注点。文件系统与进程管理保留各自独立的契约、测试和消费方，同时避免把所有者变成无边界的能力集合。
+**把所有提供方操作都放进一个共享所有者包。** 不予采纳，因为沙箱身份与生命周期是所有者唯一的关注点。文件系统与进程管理保留各自独立的约定、测试和消费方，同时避免把所有者变成无边界的能力集合。
 
 **只通过 shell 命令实现远程文件系统操作。** 不予采纳，因为这会丢弃现有文件工具已消费的结构化文件系统身份、错误、流式输出、版本保护和原子变更语义。
 
-**新增通用分布式运行时抽象，或重新连接活跃句柄。** 不予采纳，因为现有能力 seam 已承载经证实的契约，而仅凭远程身份无法重建回调、待处理 promise、权限、协议状态或输出游标。新增一层只会推测 POC 边界之外的持久化与同步问题。
+**新增通用分布式运行时抽象，或重新连接活跃句柄。** 不予采纳，因为现有能力 seam 已承载经证实的约定，而仅凭远程身份无法重建回调、待处理 promise、权限、协议状态或输出游标。新增一层只会推测 POC 边界之外的持久化与同步问题。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
index 83f5bbef02..e876d151ab 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
 2026-07-28-user-settings-seam.md: bf93f95168b1b6d0dec5a9fc2c9aac5531f0564a
-2026-07-28-user-settings-seam.zh.md: e75cee19b600c3feca2475e609ca87d7e9a3ad7f
+2026-07-28-user-settings-seam.zh.md: 42e1196cfd8a4cc2ad1a4e2e2fee77bbd5ebbcd2
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
index e75cee19b6..42e1196cfd 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-**两个面，一条判定。**`cordis.yml`（+ Include patches）仍是组合面：有哪些插件、接线、部署配置，归 orchestrator 所有并随产品升级。settings namespace 只承载用户可编辑子集；判定是"个人配置页应该能改它吗？"值可同时存在于两个面而不歧义，因为分层就是契约：schema 默认值，然后注册方的组合 `base`（其 entry 配置子集），最后用户文档分节。
+**两个面，一条判定。**`cordis.yml`（+ Include patches）仍是组合面：有哪些插件、接线、部署配置，归 orchestrator 所有并随产品升级。settings namespace 只承载用户可编辑子集；判定是"个人配置页应该能改它吗？"值可同时存在于两个面而不歧义，因为分层就是约定：schema 默认值，然后注册方的组合 `base`（其 entry 配置子集），最后用户文档分节。
 
 **镜像 `session-persistence/` 的三包 seam。**`dsh-settings` 拥有抽象 `Settings` 服务：namespace 注册表、分层解析、schema 校验、按 namespace 深相等变更检测，以及 `settings/updated` 提交事件。provider 只实现 `writable`/`load()`/`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档——因此热更新语义对所有 provider 一致，网络配置中心后端（nacos 类，可能只读）只是一个平级包的距离。`dsh-settings-local` 是文件 provider：`resolveSpec` 显式默认到 `<DSH_HOME>/settings.yaml` 的 YAML/JSON、chokidar 监听、跨进程写锁下以 `0600` tmp+rename 原子提交的读-改-写 persist、对被写 namespace 的叶子级 diff 修补（未触碰节点的注释得以保留）、按内容相等抑制自写（[write-path integrity note](2026-07-30-settings-write-path-integrity.md)）。
 
@@ -25,7 +25,7 @@ Status: implemented
 ## Alternatives considered
 
 - **以 Include 写回为用户层**（cordis-webui 式的按插件配置页写 loader entry 文件）：写回目标是按组合的文件，会把用户偏好绑死在某个 `cordis.yml` 上；用户层必须在模板升级中存活，并以同一文档服务 TUI 与 web。
-- **以 Loader reactive `fiber.update` 为传导通道**：构造期读取毫无感知；seam 的显式 `watch()` 把热更新变成消费者契约而非框架魔法。
+- **以 Loader reactive `fiber.update` 为传导通道**：构造期读取毫无感知；seam 的显式 `watch()` 把热更新变成消费者约定而非框架魔法。
 - **领域化的 settings 服务**（按产品域的 getter）：设计评审中的耦合反对成立；服务只做存储、校验、发布——领域含义留给拥有 schema 的注册方。
 - **现在就做多层优先级**（Codex/Claude Code 式 system/managed/project 层级）：延后到真实第二层出现；resolve 步骤是分层未来唯一的扩展点。
 - **现在就上跨进程锁**（Pi 的 proper-lockfile）：最初以"原子替换加 watcher 收敛，真实冲突出现再说"为由延后——评审发现收敛会丢失未观察到的同级 namespace，因此该延后已被 [write-path integrity note](2026-07-30-settings-write-path-integrity.md) 的手写写锁取代。
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
index 9a0f384e0e..ca03afde36 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
 2026-07-29-projected-token-usage-and-request-context.md: 1e2c5ff067928620dee3d0937c247bec245e34f2
-2026-07-29-projected-token-usage-and-request-context.zh.md: fc885982ba45df68d456e153093005747ea74984
+2026-07-29-projected-token-usage-and-request-context.zh.md: 176e4929ac47dd2e83bf8361501b57058a3021f2
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
index fc885982ba..176e4929ac 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
@@ -20,7 +20,7 @@ Web 统计行原先从当前已加载的会话节点推导 token 总量。该窗
 
 `request/context` 是新增的仅入日志会话事件，记录请求所解析到的路由的、绑定注册项的元数据。AgentLoop 在步骤内紧随 `request/header` 追加它，数据取自 `prepareCall()` 现在与已解析配置一并返回的上下文元数据：正是那次已经校验过推理的、绑定注册项的查询，因此不会发生第二次解析。当提供方、模型和容量都与上一条记录相同时会跳过。适配器不公布容量的路由会以缺失 `contextWindow` 的形式记录，从而清除较早路由的分母。
 
-容量刻意不进入 `EpochHeader`。该类型是重建契约，即请求由什么构建而成，而 `headerEquals` 会逐字段比较它，以判定某个快照是否真的是一次 `change`。容量是描述路由的适配器元数据，把它放进去会让容量变化伪装成请求封装的变化，还会把它拖进 AgentLoop 的重建不变式。
+容量刻意不进入 `EpochHeader`。该类型是重建约定，即请求由什么构建而成，而 `headerEquals` 会逐字段比较它，以判定某个快照是否真的是一次 `change`。容量是描述路由的适配器元数据，把它放进去会让容量变化伪装成请求封装的变化，还会把它拖进 AgentLoop 的重建不变式。
 
 两个单元都沿用标准投影生命周期：历史尾页基线、`session/projection` 实时帧、seq 高者胜的客户端存储、JSON 检查点、缓存恢复和单元卸载。系统没有任何 token 专用的历史字段、mux 帧、投影器、修订计数器或客户端栅栏。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
index ae2347a7be..3111ab36ae 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
 2026-07-29-request-level-llm-config-credentials.md: 238400ea41f25a716729d1721c113645c2c8ba72
-2026-07-29-request-level-llm-config-credentials.zh.md: b2075798c9eb77d8fd8baecbbea77993ccda328f
+2026-07-29-request-level-llm-config-credentials.zh.md: 67a608293923291450ec3c226ac95ab4ff9f4af4
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
index b2075798c9..67a6082939 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 - **由桥接插件（`dsh-llm-models`）持有统一的 `models` 字典**——有了按插件划分的 namespace，就没有什么可桥接的了；它所需的适配器映射规则纯属凭空发明的间接层。
 - **把机密放进 settings.yaml 并靠 `role('secret')` 脱敏**——删除问题本身（引用）胜过缓解问题（脱敏 + 回填 + 同步告警）；编码 agent 同类产品在这一点上口径一致。
-- **注册表级的实时重试策略**——让 `providerRetryPolicy` 每次调用都重读，会静默改变所有注册都依赖的 `ctx.llm` 捕获契约；原地重新注册路由既保住该契约，又保持可观察。
+- **注册表级的实时重试策略**——让 `providerRetryPolicy` 每次调用都重读，会静默改变所有注册都依赖的 `ctx.llm` 捕获约定；原地重新注册路由既保住该约定，又保持可观察。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
index e556108299..6c6a13bc33 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
 2026-07-30-package-manager-native-repository-cache.md: 0ea145f20a58e4e3e9feb7ba5574818c0352e2c4
-2026-07-30-package-manager-native-repository-cache.zh.md: ac72e5dc4ffa764e1dc430764a6f52fc083d32a4
+2026-07-30-package-manager-native-repository-cache.zh.md: 2dd10f756d0b26a7af89e74be034be83d95fcb0e
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
index ac72e5dc4f..2dd10f756d 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
@@ -16,7 +16,7 @@ vendor 中的 `@cordisjs/plugin-loader/repository` 导出 `RepositoryCache`：
 
 Loader 将 `pnpm@11.7.0` 作为固定版本的运行时依赖，并使用当前 Node 可执行文件调用该包的 JavaScript 入口。它绝不探测全局可执行文件，也不经 Corepack 调用。每次缓存未命中都会创建一个隔离工程，其中只有一个名为 `repository` 的依赖；Git 与 GitHub 来源的解析和获取、pnpm 自身的内容寻址 store、依赖安装，以及仓库依赖图中的生命周期脚本均由 pnpm 负责。
 
-隔离工作区设置 `dangerouslyAllowAllBuilds: true`。用户配置的仓库及其依赖图都属于受信任的可执行代码：DSH 读取任何已声明资产之前，生命周期脚本就可能运行。子进程会收到 Git 与 pnpm 所需的常规宿主进程状态，但会移除环境中名称形似凭据（`KEY`、`PASSWORD`、`SECRET`、`TOKEN`）的变量。该机制不新增 OAuth、token 转发或私有仓库认证契约。
+隔离工作区设置 `dangerouslyAllowAllBuilds: true`。用户配置的仓库及其依赖图都属于受信任的可执行代码：DSH 读取任何已声明资产之前，生命周期脚本就可能运行。子进程会收到 Git 与 pnpm 所需的常规宿主进程状态，但会移除环境中名称形似凭据（`KEY`、`PASSWORD`、`SECRET`、`TOKEN`）的变量。该机制不新增 OAuth、token 转发或私有仓库认证约定。
 
 缓存项以精确 specifier 的 SHA-256 命名。同一进程内针对相同 specifier 的并发请求共享一项任务。安装在同级临时目录中进行；只有安装成功且存在包目录和标记时，系统才会把暂存目录原子重命名为最终键对应的目录。失败的暂存目录会被删除；如果另一进程已发布有效项，则以该项为准。后续进程会先校验标记与包目录，再返回稳定的 `node_modules/repository` 路径。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
index ab893fbb26..b8dcd32d8e 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
 2026-07-30-settings-write-path-integrity.md: 7bd50adc8a812759c3ae3f80a50978d75baa712a
-2026-07-30-settings-write-path-integrity.zh.md: 600a3c7269510673433969c92d322fd1186d38f3
+2026-07-30-settings-write-path-integrity.zh.md: 155fb55b886ab41d11d947ee09194a367ac8a90f
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
index 600a3c7269..155fb55b88 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
@@ -20,9 +20,9 @@ YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删
 
 **写入持有以 `wx` 创建的同目录 `<file>.lock`。**读-渲染-rename 循环在一把跨进程写锁下运行，采用指数退避与 2 s 获取期限。竞争者会超时，但不会移除现有锁，因为锁龄无法区分已经崩溃的所有者与被暂停但仍存活的写入方；遗留锁恢复须由操作者执行。读方从不加锁——rename 提交是原子的——因此竞争只发生在写方之间。重试与期限常量是协议不变式，而非部署配置。
 
-**观察者 dispose 达到完全停稳。**watcher 携带一个 `active` 标志，排队的调用即将启动时先检查它，因此在调用等待期间已经运行过的释放器能让这次启动彻底不发生；已启动的调用会登记进服务级的 `pendingTails` 集合，dispose 排空除了等待各写队列，还会等待该集合。`settings/updated` 扇出会把监听器返回的 thenable 的 rejection 收容进与同步抛错相同的监听器诊断；事件契约现已写明 `INVARIANT` 重抛只服务同步监听器——不变式配套插件必须保持同步，而已交付的那个配套插件本就是同步的。
+**观察者 dispose 达到完全停稳。**watcher 携带一个 `active` 标志，排队的调用即将启动时先检查它，因此在调用等待期间已经运行过的释放器能让这次启动彻底不发生；已启动的调用会登记进服务级的 `pendingTails` 集合，dispose 排空除了等待各写队列，还会等待该集合。`settings/updated` 扇出会把监听器返回的 thenable 的 rejection 收容进与同步抛错相同的监听器诊断；事件约定现已写明 `INVARIANT` 重抛只服务同步监听器——不变式配套插件必须保持同步，而已交付的那个配套插件本就是同步的。
 
-**写入边界只放行 JSON 数据。**调用时刻的快照就是一次 `cloneJsonShaped` 遍历：它把 patch 从调用方分离出来，并在任何内容持久化之前拒绝一切非 JSON 值——Date、Map、BigInt、非有限数值、函数、symbol、类实例、值为 `undefined` 的数组元素、循环引用——拒绝时附带该值以 `$` 为根的路径。显式为 `undefined` 的对象条目仍会跳过（稀疏 patch 契约），这一契约如今在边界处强制执行，而不再放在 `mergeLayers` 内部。
+**写入边界只放行 JSON 数据。**调用时刻的快照就是一次 `cloneJsonShaped` 遍历：它把 patch 从调用方分离出来，并在任何内容持久化之前拒绝一切非 JSON 值——Date、Map、BigInt、非有限数值、函数、symbol、类实例、值为 `undefined` 的数组元素、循环引用——拒绝时附带该值以 `$` 为根的路径。显式为 `undefined` 的对象条目仍会跳过（稀疏 patch 约定），这一约定如今在边界处强制执行，而不再放在 `mergeLayers` 内部。
 
 **YAML 编辑是叶子级 diff。**`renderYaml` 对比已存储分节与下一份分节，只对变化的值应用 `setIn`、对移除的键应用 `deleteIn`，并沿 map 递归。注释、锚点与格式在每个未触碰节点上、以及每个被改键值对的键节点上全部保留；数组等非 map 值在不相等时整体替换（`deepEqualJson` 是共享的判定谓词），其内部注释随之一并被带走。
 
@@ -31,7 +31,7 @@ YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删
 - **用 `proper-lockfile` 取代手写锁**——按“依赖优先于手写”政策做过权衡：该库几乎无人维护，其所有权与重试策略比这个单文件协议所需的更宽泛，而已交付的锁只是一个小型独占创建循环，带确定性的竞争测试。该政策偏向能删除自有代码的依赖；这个依赖只会把一个窄协议换成不透明的等价物。
 - **用修订号/CAS 取代锁**——rename 表达不了 compare-and-swap，因此 CAS 需要一个版本伴随文件或内容重哈希，外加每个写方里的一个重试循环；锁用一个原语实现同样的串行化，还让读方完全免锁。
 - **把外部编辑合并进正在进行的写入自身的分节**——seam 是在调用时刻可见的状态之上合并 patch 的，因此与写入竞态的同 namespace 外部编辑仍按后写胜出解决；要把外部编辑并进来，需要三方合并语义，而没有任何消费方提出过这种需求。写入会先发布外部状态，落败一方至少在被取代之前被观察到。
-- **宣布不支持异步 `settings/updated` 监听器**——类型签名是 `void`，lint 也会标记误用的 promise，但未经 lint 的 JS 插件仍能注册异步监听器；契约里的一句说明无法收回已经抛出的 unhandled rejection，收容是唯一在运行时守得住的防线。
+- **宣布不支持异步 `settings/updated` 监听器**——类型签名是 `void`，lint 也会标记误用的 promise，但未经 lint 的 JS 插件仍能注册异步监听器；约定里的一句说明无法收回已经抛出的 unhandled rejection，收容是唯一在运行时守得住的防线。
 - **保留 `structuredClone`、在提供方里做校验**——seam 才是持久化边界的所有者（每个提供方存储的都是 JSON 形态文档），而且在调用时刻拒绝能把违规值的路径给到调用方；提供方侧的检查要到合并之后才拒绝，归咎的是合并后的分节，而不是调用方传入的值。
 
 ## 后果
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 6319b99fb2..6ee8b4bc32 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
 2026-07-30-static-repository-plugin-format.md: c9d755b925a6ea05eed71e75803397d2672df9f4
-2026-07-30-static-repository-plugin-format.zh.md: 361de64d2e98b9fb4ac42963e4ae48e77fbc7016
+2026-07-30-static-repository-plugin-format.zh.md: 70bcb09d989ae3a434e56847d9b628c5194ef56f
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index 361de64d2e..70bcb09d98 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -22,19 +22,19 @@
 
 `.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配层接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。严格的 `${NAME}` 进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。因此 MCP 连接失败会继续沿用“Plugin 成功但不注册工具”的既有行为，不会被重新分类为 repository 准备或 Loader 失败。
 
-未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容契约。Hooks、commands、agents、apps、任意 Cordis 代码、marketplace 和发现同样不受支持。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本格式 package。
+未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容约定。Hooks、commands、agents、apps、任意 Cordis 代码、marketplace 和发现同样不受支持。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本格式 package。
 
 ## 考虑过的替代方案
 
 **加载仓库自己的 Cordis 入口。** 拒绝，因为这会把宣传为静态的格式变成无限制代码加载 API，要求仓库作者依赖 Harness 内部实现，并重复普通 SDK／Plugin dependency 路径。
 
-**让生成包装模块直接实现 skills 和 MCP。** 拒绝，因为复制的运行时代码会与 `dsh-skill-local` 和 `dsh-mcp-client` 漂移，尤其是提供方失效、工具同步、失败和 teardown 契约。
+**让生成包装模块直接实现 skills 和 MCP。** 拒绝，因为复制的运行时代码会与 `dsh-skill-local` 和 `dsh-mcp-client` 漂移，尤其是提供方失效、工具同步、失败和 teardown 约定。
 
 **让每个生成包装模块 import Harness package。** 拒绝，因为 repository package 不应解析或锁定应用的内部依赖图。Loader builtin 提供一份由 app 所有的实现，并让生成包装模块保持无 import。
 
 **监视已准备 repository 资源。** 拒绝，因为一个精确 repository cache generation 是不可变的。Ref、子目录或配置变化会选择新 generation；第二套 watcher 会创造一套没有所有者的刷新身份。
 
-**把 MCP 连接失败当作 Loader 更新失败。** 拒绝，因为现有 MCP client 有意收束连接失败并不暴露工具。只对 repository source 改变该语义，会让同一 server 配置拥有两套失败契约。
+**把 MCP 连接失败当作 Loader 更新失败。** 拒绝，因为现有 MCP client 有意收束连接失败并不暴露工具。只对 repository source 改变该语义，会让同一 server 配置拥有两套失败约定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
index 3128996f1e..a6be2d99e5 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
 2026-07-31-claimed-pre-step-inbox-lifecycle.md: 5184c00335b3084a8eb6d58fa33a0af8d3a16ed6
-2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 4966ccc8a3a7535022c04f9445ca75102ccca71e
+2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 4718b1b519051f0ae82b4c7f9d0599f45a800f1d
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
index 4966ccc8a3..4718b1b519 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 **reject 时把已领取批次重新入队。** 这看似保留重试行为，却会让否决隐式修改队列；若不为每个竞态加围栏，还会复制后续工作，并使 claim 无法成为原子所有权转移。
 
-**在每个实时事件上携带 placement 与 outcome。** 持久 splice 已经拥有这些事实。实时通知重复它们会建立可能漂移的第二份契约，而持有确切消息标识的消费方并不需要这些字段。
+**在每个实时事件上携带 placement 与 outcome。** 持久 splice 已经拥有这些事实。实时通知重复它们会建立可能漂移的第二份约定，而持有确切消息标识的消费方并不需要这些字段。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
index 45436c96e6..58470f9780 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
 2026-07-31-code-runtime-portable-identifier-seam.md: 9e9df50235b3505458e3645e2c6ff6e9bd439183
-2026-07-31-code-runtime-portable-identifier-seam.zh.md: 31d2410ee4809d0693f2e7897e61c50163bb0758
+2026-07-31-code-runtime-portable-identifier-seam.zh.md: 215024467f6f76a79a1f48f33e9d3c5b216df08d
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
index 31d2410ee4..215024467f 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## Problem
 
-code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性契约。
+code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性约定。
 
 一个针对不同语言（CPython，将在本 stack 后续 PR 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使 seam 的一个实现伸手进入另一个兄弟实现。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
 
 ## Decision
 
-seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除契约，每个后端导入它们而非重新声明：
+seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除约定，每个后端导入它们而非重新声明：
 
 - `PORTABLE_RESERVED_WORDS`——ECMAScript 与 Python 保留字的联集。任何命名空间 global 或 error-class 名称匹配其中之一，都在所有后端上被拒绝，因此 `lambda` 即便是合法的 JS 参数名也被拒绝。新增一门语言即扩宽此联集，这是对现有绑定名称的一次有意的破坏性复审。
 - `RESERVED_BINDING_GLOBALS`——某个后端在程序命名空间中拥有的 global：`console`（worker 的日志捕获）、`__dsh_main__`/`__builtins__`/`__name__`（Python bootstrap 的包装器与预置模块 global），以及 `__debug__`（不是 seed 的槽位，而是 CPython 编译期常量，赋值会被拒，故以该名注入的 global 不可达——同一种可移植性分裂，只是机制不同）。在所有后端上被拒绝，使命名空间列表无法选到一个在某后端能用、在另一后端冲突的名称。
@@ -21,24 +21,24 @@ seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移
 
 seam 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记录在 `CodeBindingNamespace.global` 与 `CodeBindingErrorClass` 上），去掉 JS 专有的 `$`。worker 直接以 seam 名消费这些共享常量——binding-global 与 error-class 名称用 `PORTABLE_RESERVED_WORDS`、后端拥有槽位用 `RESERVED_BINDING_GLOBALS`、error member 用 `RESERVED_ERROR_MEMBERS` 加 `DUNDER_MEMBER`——不再本地起别名；其 `IDENTIFIER` 正则去掉 `$`。
 
-尽管本 PR 只交付一个后端，这些常量仍置于 seam：要点正是该契约与语言无关，且拥有权在任何单一语言之上。违反它的后端才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
+尽管本 PR 只交付一个后端，这些常量仍置于 seam：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的后端才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
 
 ## Scope
 
 本 PR 只交付 seam 扩展与 worker 对它的采用。这里不交付任何 Python 后端、`py-types` 渲染器或 Code Mode 的语言分发——它们是本 stack 中依赖这些导出的后续 PR。seam README 中仅描述 worker 的措辞保持不变，理由相同：链接到一个尚不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
 
-`RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本契约要防止的可移植性分裂。
+`RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本约定要防止的可移植性分裂。
 
 ## Alternatives considered
 
 **每个后端声明自己的排除集。** 拒绝：这让可移植承诺变成逐后端成立。调用方在 worker 上测过的绑定列表可能被 Python 拒绝，而这正是 seam 存在要防止的分裂。
 
-**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的实现会为一个二者都不拥有的契约伸手进入兄弟实现。契约属于二者之上，即 seam。
+**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的实现会为一个二者都不拥有的约定伸手进入兄弟实现。约定属于二者之上，即 seam。
 
 **在可移植标识符子集中保留 `$`。** 拒绝：`$` 是 JS 专有拼写。允许它会让 `$tools` 通过 worker 却在每个非 JS 后端上失败，为纯粹表面的好处破坏可移植性。
 
 ## Consequences
 
-获得：一个地方——seam 包——定义什么是可移植绑定名称，每个后端通过导入执行同一契约。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
+获得：一个地方——seam 包——定义什么是可移植绑定名称，每个后端通过导入执行同一约定。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
 
 代价：现有使用含 `$` global 的 worker 调用方现在会在标识符校验时失败。在预发布立场下这是一次被纠正的地基，而非需要 shim 的兼容性破坏。worker 的 seam-misuse 测试新增了 `$tools`、Python 异常成员（`args`）、dunder（`__dict__`）与一个 Python 拥有的 global（`__dsh_main__`）等用例，从 worker 侧证明共享集合被执行。
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
index f63372c8b4..b8f2e4d7d7 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
 2026-08-01-packaged-ripgrep-search.md: 7c515618a18b61bd90177a6fdf19bbd52e564209
-2026-08-01-packaged-ripgrep-search.zh.md: f2b1a12c737f772bff6a6c91c17f7453dbc89748
+2026-08-01-packaged-ripgrep-search.zh.md: d06841b220603d832048d1c76784f0e1d283679c
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
index f2b1a12c73..d06841b220 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 **让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试 seam 会消费的公开部署面，而真实二进制本身足够确定——通过 fixture mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
 
-**改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于"不存在 glob 引擎"的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具契约。
+**改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于"不存在 glob 引擎"的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具约定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index d3f73c3b5c..38adb776d6 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
 2026-08-02-typert-remote-method-calls.md: f3db8b9eec5eb8fb610fc58edad9313e4f715326
-2026-08-02-typert-remote-method-calls.zh.md: da4459432e8c9e08821bcded2921cbd33fc5e8c8
+2026-08-02-typert-remote-method-calls.zh.md: 76c390487fcf224179c85b8aeaa8de9507757e65
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index da4459432e..76c390487f 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -10,7 +10,7 @@ Host API Proxy 同时承担直接方法调用、带状态交互和 Session 事
 
 本决策只涵盖一次请求对应一次结果的定向方法调用。Permission、Approval 等带状态交互以及 Session 事件流仍采用独立设计。
 
-直接方法调用的契约属于实现该行为的业务 Service。业务开发者只需声明哪些方法可以远程调用，无需再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
+直接方法调用的约定属于实现该行为的业务 Service。业务开发者只需声明哪些方法可以远程调用，无需再同步维护中央 API 接口、路由表、参数转换表、客户端 stub 和 Zod schema。
 
 Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以不同类型合并同名 Cordis `Context`。Remote 投影不能把完整 Host 声明导入消费端，也不能依赖 Browser 专属类型；未来 TUI 若复用这套编程界面，也只能看到 Remote 标记的方法。本期不实现 TUI 接入，但实现边界不得阻断这种同构复用。
 
@@ -18,11 +18,11 @@ Host 与 Browser Client 使用独立的 TypeScript Program，因为两边会以
 
 业务 Service 继承 `GatewayService`，并通过 `@Remote` 或 `@RemoteScope()` 声明可调用方法；已有其他基类的 Service 可以改用 `bindTypeRTGateway()` 暴露同一绑定。TypeRT 从 Host Program 生成 Host 本地反射产物和平台无关的 Remote 消费端投影；Client Program 继续独立生成自己的本地反射产物。
 
-Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一契约的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client Remote Service；该投影和 Remote 抽象保持平台无关，以便未来 TUI 复用。
+Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只暴露被 Remote decorator 标记的方法，并引用业务包唯一的公共类型符号；`.d.ts.map` 把消费端 API 方法导航回 Host 业务方法实现；`.js` 携带同一约定的 endpoint、参数、Context 和 Zod 信息。Browser Client 在 assembly 层把需要的 Remote JS 贡献集中挂到 Client Remote Service；该投影和 Remote 抽象保持平台无关，以便未来 TUI 复用。
 
 `@deepseek-ai/dsh-api-gateway` 位于 `packages/api/gateway`，提供对称的两个 face：默认入口提供 Host `ctx.typertGateway`，`/client` 入口提供消费端 `ctx.remote`。两边各自在本地消费由同一模型生成的 `InvocationDescriptor`，descriptor 不通过 wire 发送。Remote 数据协议运行在 Connection 共享的 `/api` RPC channel 上；业务调用界面不随 Connection 从 HTTP 迁移到 WebSocket 而改变。
 
-`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 契约，而不导入具体 Gateway 实现。
+`@deepseek-ai/dsh-api-remotes` 位于 `packages/api/remotes`，是 Gateway 上层的 BFF 层。其 Host 入口负责 Agent/Session 身份解析与 TypeRT lookup 配置；`/client` 入口选择应用对外暴露的生成 Remote contribution。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 约定，而不导入具体 Gateway 实现。
 
 ## 组件和 Cordis 服务
 
@@ -42,7 +42,7 @@ Host Gateway 不依赖 `ctx.agents`、`ctx.sessions`、`ctx.goals` 或 `ctx.http
 
 ## 业务声明
 
-普通直接调用使用 `@Remote`。现有方法的参数和结果已经是预期的 Remote 契约时，直接装饰该方法，不为此重命名。只有 wire 契约需要不同的请求或结果形态时，才新增 `remoteExport*` 适配器，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
+普通直接调用使用 `@Remote`。现有方法的参数和结果已经是预期的 Remote 约定时，直接装饰该方法，不为此重命名。只有 wire 约定需要不同的请求或结果形态时，才新增 `remoteExport*` 适配器，并由 decorator 参数声明短 API 名。方法需要哪个业务对象，就在顶层参数位置显式声明该对象：
 
 ```text
 export class GoalService extends GatewayService {
@@ -87,7 +87,7 @@ export class ScopedGoalService extends GatewayService {
 
 ## Decorator 与显式 Gateway facet
 
-Decorator 只表达“该方法参与 Remote 契约”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteScope('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
+Decorator 只表达“该方法参与 Remote 约定”，不负责运行时类型反射，也不向 Service constructor 注入隐藏 symbol。`@Remote('create')` 和 `@RemoteScope('agent', 'create')` 的参数是外部方法名；被装饰成员既可以是业务方法本身，也可以是 `remoteExportCreate` 这样的适配器。未给别名时才使用成员名作为外部方法名。继承 `GatewayService` 是 Service 加入 Gateway 的常规显式声明；其 public readonly `typertGateway` 字段使运行时实例上的绑定保持可见。
 
 SRC 运行时允许 decorator 在 `dsh-type-meta` 内部的 `WeakMap` 记录 prototype、方法名和调用模式。它不向 Service 实例、prototype、constructor 或方法函数写入自定义属性。
 
@@ -217,7 +217,7 @@ Host lib build
 
 现有顶层 `build` 仍表现为先 `build:lib`、再 `build:web`，但 `build:lib` 内部必须先完成 Host 与 Remote artifact，再启动 Client TypeScript 编译。一次干净构建不能依赖上次残留的 `.d.ts`。
 
-即使主要输入是源文件，需要通过编译器解析消费方 surface 的仓库门禁也有相同的前置条件。公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先执行 Host 契约 pass。门禁调度器仅可在显式的 TypeRT 契约依赖或完整构建依赖完成后使用对应的 `*:contracts-ready` 变体，使并行 lane 既不会读取缺失的声明，也不会针对同一输出并发运行多个生成器。
+即使主要输入是源文件，需要通过编译器解析消费方 surface 的仓库门禁也有相同的前置条件。公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先执行 Host 约定 pass。门禁调度器仅可在显式的 TypeRT 约定依赖或完整构建依赖完成后使用对应的 `*:contracts-ready` 变体，使并行 lane 既不会读取缺失的声明，也不会针对同一输出并发运行多个生成器。
 
 ## `/remote` 包入口
 
@@ -236,7 +236,7 @@ Host lib build
 import goalsRemote from '@deepseek-ai/dsh-goal/remote'
 ```
 
-该 import 让 `.d.ts` 的 map augmentation 进入当前 TypeScript project，同时把同一契约的 JS descriptor 作为值交给运行时。未 import 的业务包不会扩展当前 project 的 Remote API 类型。
+该 import 让 `.d.ts` 的 map augmentation 进入当前 TypeScript project，同时把同一约定的 JS descriptor 作为值交给运行时。未 import 的业务包不会扩展当前 project 的 Remote API 类型。
 
 业务 package 的发布文件必须同时包含 `lib/typert.remote-client.d.ts.map` 和 map 指向的 `src` 文件。生成 DTS 以 `//# sourceMappingURL=typert.remote-client.d.ts.map` 引用相邻 map；map 中的 source 从 `lib` 相对指向业务源码，例如 `../src/index.ts`。`/remote` export 不单独列出 map，package `files` 负责把它与源码一起发布。
 
@@ -309,7 +309,7 @@ await ctx.remote.$mount(goalsRemote)
 await ctx.remote.$mount(sessionsRemote)
 ```
 
-Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientRemote` 契约和 Cordis `ctx.remote` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
+Client 业务包只引用 `@deepseek-ai/dsh-api-remotes/client`，不直接依赖 API Gateway 或各业务 `/remote` 运行时入口。API Remotes 消费共享的 `TypeRTClientRemote` 约定和 Cordis `ctx.remote` 服务，再重新导出声明，使所选 Remote map 进入业务编译；新增或移除整套 Client 能力只修改这一处 assembly。
 
 `ctx.remote.$mount()` 把 contribution 注册到 `TypeRT.remotes`，安装它的 namespace Service 和具体方法，并在它们就绪后才 resolve。调用该方法的 Cordis fiber 持有 disposer。endpoint 重复、同一 namespace/method 模式冲突或 descriptor 与现有类型身份冲突时直接失败。
 
@@ -343,7 +343,7 @@ Remote DTS、Remote JS、`TypeRTClientRemote`、`InvocationDescriptor`、Remote
 
 TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均不属于本期实现。
 
-Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 契约变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
+Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 约定变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
 
 ## SRC 与 LIB 运行模式
 
@@ -454,7 +454,7 @@ Gateway 只向 Connection 注册 ownership matcher 和 RPC handler，不注册 H
 - TypeRT generator：分析 Host/Client Program，生成本地 face 和 Remote 消费端投影，并生成规范 symbol/Zod 信息。
 - TypeRT runtime：分别保存当前环境的 local reflection 与导入的 Remote contribution。
 - `@deepseek-ai/dsh-api-gateway`：默认入口关联 Host definition 与 Service，认领 Remote endpoint，执行 lookup、Context receiver 解析、调用和结果编码，并向 Connection 注册 `/api` interceptor；`/client` 入口挂载 Remote contribution，创建严格 Remote namespace Service 和方法，并把调用交给 `ctx.connection.rpc`。两个入口共享 Remote 协议，但不互相导入各自的 Cordis interface merge。
-- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientRemote` 契约向业务包暴露合并后的 Remote 类型。
+- `@deepseek-ai/dsh-api-remotes`：BFF 层；负责 Host Agent/Session resolver，选择 Client `/remote` contribution，并通过共享的 `TypeRTClientRemote` 约定向业务包暴露合并后的 Remote 类型。
 - Connection：拥有唯一 HTTP Server/未来 WebSocket carrier、共享 `/api` route 与复合 FetchHandler、API Proxy 回退、RPC envelope、rpcId、序列化、trust 和错误传输。
 - Agent/Session 等业务对象包：拥有 lookup、Context provider、唯一 ID 类型和纯类型公共出口。
 - API Proxy Host 组合：向 API Remotes 提供 Web Agent 默认值和 scope 设置，并让旧方法使用同一个 `agentFor()`。
@@ -490,9 +490,9 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 ## 验证
 
-- Goal Service 直接装饰业务签名已经符合 Remote 契约的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
+- Goal Service 直接装饰业务签名已经符合 Remote 约定的变更类方法，仅保留 `remoteExportCreate(...)` 把 `GoalView` 适配为 `CreateGoalResult`，无需第二条路由、第二份 codec 或 Client 方法清单。
 - 一次干净的 `build:lib` 会在 Client 编译前生成 Host 与消费方 Remote 产物，包括业务包 `/remote` 下的 JS、DTS 和 declaration map。
-- `clean` 后，单独运行 `typecheck`、`lint` 或 `doc-typecheck` 都会重新生成 Remote 契约；pre-push 钩子使用同一个已包含契约准备步骤的 typecheck，CI 中的源码消费方则等待一次共享的契约 pass。
+- `clean` 后，单独运行 `typecheck`、`lint` 或 `doc-typecheck` 都会重新生成 Remote 约定；pre-push 钩子使用同一个已包含约定准备步骤的 typecheck，CI 中的源码消费方则等待一次共享的约定 pass。
 - 导入 `@deepseek-ai/dsh-goal/remote` 会加入严格的 `ctx.remote.goals.create(...)` 类型，并可通过 declaration 导航到 `remoteExportCreate`；不导入时不会出现该 namespace。
 - 挂载同一次 import 得到的 JS contribution 会提供 endpoint、参数、结果、lookup、Context 和 Zod 反射，并在无需手写 stub 的情况下实体化调用。
 - Root 与 Agent-scoped 调用会经过真实的共享 `/api` carrier，将 `agentId` 解析为活 Agent，调用原始 Goal receiver，并通过既有 RPC envelope 返回。
@@ -504,9 +504,9 @@ Connection 提供共享 channel interceptor 与当前 HTTP carrier 映射。WebS
 
 ## 后果
 
-Remote API 类型依赖生成的 `lib` 声明，构建与门禁编排必须在对 Host 和 Client 消费方进行编译或语义分析之前完成 Host 契约 pass；顺序错误会使干净环境中的命令依赖陈旧产物。
+Remote API 类型依赖生成的 `lib` 声明，构建与门禁编排必须在对 Host 和 Client 消费方进行编译或语义分析之前完成 Host 约定 pass；顺序错误会使干净环境中的命令依赖陈旧产物。
 
-源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布契约。
+源码导航依赖 Remote package 同时发布 declaration map 和 map 指向的 `src`。package `files` 漏掉任一侧时类型仍可编译，但消费端跳转会停在生成 DTS，因此 workspace manifest 校验必须把两者作为同一发布约定。
 
 SRC 弱 descriptor 不验证普通 JSON 内部结构。Host Remote 签名变化后，Web 和严格类型消费方必须重新执行 lib build，因为系统没有增量 contract watcher。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
index 2969995da6..9414852f9c 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
 2026-08-03-pi-ai-declared-provider-catalog.md: f908eb6293b77680193fcd8f7be7a9089477855a
-2026-08-03-pi-ai-declared-provider-catalog.zh.md: ce91abd6dc71f790c72766cd3f819096d596182c
+2026-08-03-pi-ai-declared-provider-catalog.zh.md: e487bd68c65f38332d09f661292c797a746b68d1
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
index ce91abd6dc..e487bd68c6 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
@@ -64,4 +64,4 @@ pi-ai 的 `Models` 自带一套凭据概念——按提供方 id 索引的 `Cred
 
 ## Testing
 
-`tests/catalog.spec.ts` 针对本地 mock 服务器端到端覆盖该契约：手工声明的路由带着自己的凭据流向自己的端点、它在可配置提供方目录中的出现、每模型覆盖从已安装 catalog 继承默认值、向 catalog 路由添加模型、带与不带端点覆盖的协议改指、catalog 独有元数据在覆盖后存活、无密钥姿态及其 `Authorization` 标头变通、只走 OAuth 的 catalog 路由用 profile 点名的密钥完成认证而无密钥者保持未配置、改指协议的路由保留其 catalog auth，以及每一种点名路由或模型的解析失败。`tests/catalog.spec.ts` 还钉住了快照与目录两项契约：在途请求即便其路由集在 credential await 期间改变，仍抵达它解析时对应的端点；下一个请求取用新配置；冲突的声明路由让目录保持完好；声明路由的条目随其 profile 出现与离开。`packages/llm/llm/tests/topology.spec.ts` 覆盖 `replace`——拒绝他人已拥有的候选同时保住当前集合、接受对自身条目的替换、允许空集合，以及 dispose 之后失败。`tests/sdk-options.spec.ts` 把 SDK 边界从已移除的 `/compat` 导入改指到协议表的 lazy api 模块，同时钉住「setup 失败以终止性错误分片而非抛出的形式抵达」。twin 的[设计验证角色](2026-06-13-twin-llm-adapters.md)不变。
+`tests/catalog.spec.ts` 针对本地 mock 服务器端到端覆盖该约定：手工声明的路由带着自己的凭据流向自己的端点、它在可配置提供方目录中的出现、每模型覆盖从已安装 catalog 继承默认值、向 catalog 路由添加模型、带与不带端点覆盖的协议改指、catalog 独有元数据在覆盖后存活、无密钥姿态及其 `Authorization` 标头变通、只走 OAuth 的 catalog 路由用 profile 点名的密钥完成认证而无密钥者保持未配置、改指协议的路由保留其 catalog auth，以及每一种点名路由或模型的解析失败。`tests/catalog.spec.ts` 还钉住了快照与目录两项约定：在途请求即便其路由集在 credential await 期间改变，仍抵达它解析时对应的端点；下一个请求取用新配置；冲突的声明路由让目录保持完好；声明路由的条目随其 profile 出现与离开。`packages/llm/llm/tests/topology.spec.ts` 覆盖 `replace`——拒绝他人已拥有的候选同时保住当前集合、接受对自身条目的替换、允许空集合，以及 dispose 之后失败。`tests/sdk-options.spec.ts` 把 SDK 边界从已移除的 `/compat` 导入改指到协议表的 lazy api 模块，同时钉住「setup 失败以终止性错误分片而非抛出的形式抵达」。twin 的[设计验证角色](2026-06-13-twin-llm-adapters.md)不变。
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
index 2a4879b6aa..d6c40df351 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
 2026-08-04-websocket-downlink-carrier.md: b41ad687725c55acb8517fe7e93d645f007a0453
-2026-08-04-websocket-downlink-carrier.zh.md: 568240ec14592fba8444e5cc0a3bae2b35c45b94
+2026-08-04-websocket-downlink-carrier.zh.md: c8c8c34c7b7365bc3099cb33a5861051e015b226
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
index 568240ec14..c8c8c34c7b 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
@@ -22,7 +22,7 @@ WebSocket 只承担 host→browser 下行。所有 client→host unary 调用和
 
 ## Verification
 
-webserver 契约测试钉住 upgrade pathname 分发、重复注册拒绝、disposer 与 teardown；connection 的真实网络测试钉住两条 WebSocket 各自的信任检查、open、schema 信封、frame 顺序、stream error 与 close cancellation；客户端测试同时证明下行创建 `ws:`／`wss:` URL，而 unary 与 `respond` 仍调用 HTTP `fetch`。组装后的 keyless browser replay 继续覆盖 Chromium、真实 host、HTTP 上行与 WebSocket 下行整链。
+webserver 约定测试钉住 upgrade pathname 分发、重复注册拒绝、disposer 与 teardown；connection 的真实网络测试钉住两条 WebSocket 各自的信任检查、open、schema 信封、frame 顺序、stream error 与 close cancellation；客户端测试同时证明下行创建 `ws:`／`wss:` URL，而 unary 与 `respond` 仍调用 HTTP `fetch`。组装后的 keyless browser replay 继续覆盖 Chromium、真实 host、HTTP 上行与 WebSocket 下行整链。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
index 8a4b3606a8..6f00f147f3 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.md
 2026-08-05-large-session-jsonl-restore-pipeline.md: eab53c683880ef7095233ed8122e532eb5add547
-2026-08-05-large-session-jsonl-restore-pipeline.zh.md: 039e0c193179677b57e742d55f4c7df6bdff852f
+2026-08-05-large-session-jsonl-restore-pipeline.zh.md: 2cd0d2ca20074d6adb0735db08071638ae2ced88
diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
index 039e0c1931..2cd0d2ca20 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解码专用首帧并将其解析为会话头部，后续明文帧则按顺序产出并送入 JSONL 扫描器。
 
-`ZstdFrameDecoder` 为可互换的同步实现提供统一生命周期。首选实现会探测受支持 Node 22、24 与 26 的流结构，在所有完整帧之间复用一个私有原生解码上下文和临时缓冲区，最后只关闭一次。如果私有结构不可用，工厂会选择使用公共 `zstdDecompressSync` 的实现，并保持相同的迭代器和校验和错误契约。迭代器产出的临时视图会在进入下一次迭代前被消费。
+`ZstdFrameDecoder` 为可互换的同步实现提供统一生命周期。首选实现会探测受支持 Node 22、24 与 26 的流结构，在所有完整帧之间复用一个私有原生解码上下文和临时缓冲区，最后只关闭一次。如果私有结构不可用，工厂会选择使用公共 `zstdDecompressSync` 的实现，并保持相同的迭代器和校验和错误约定。迭代器产出的临时视图会在进入下一次迭代前被消费。
 
 累计帧处理时间约达 500 ms 后，异步读取器会在下一帧边界让出事件循环，并在继续前观察取消信号。单个帧仍是不可分割的同步操作。完整帧必须通过帧结束与校验和验证；只有结构上不完整的最终帧才使用既有前缀解码器进行恢复。
 
@@ -49,4 +49,4 @@ Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解
 
 快速解码器依赖运行时探测的 Node 内部接口，但接口不兼容时会改用公共实现，不会改变正确性。系统会在协作式帧边界让出点观察取消信号；截止时间并不是单个帧内部严格的挂钟时间上限。完整事件数组仍会驻留内存，因为它是活跃会话的权威日志；该流水线移除的是重复表示，并未对这份状态做分页。
 
-测试会强制执行两种解码器实现，比对帧顺序和损坏处理行为，覆盖协作式取消与撕裂尾部恢复，并保留既有会话信封、`surface` 与不可变性契约。
+测试会强制执行两种解码器实现，比对帧顺序和损坏处理行为，覆盖协作式取消与撕裂尾部恢复，并保留既有会话信封、`surface` 与不可变性约定。
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
index 09e63a6a1c..2fd0f4bd8e 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-session-preparation.md
 2026-08-05-session-preparation.md: 69d39f552ed3041403a24b5aefb435e4e721b09c
-2026-08-05-session-preparation.zh.md: a0ca27eb63552566c918c299bd5fba976687812c
+2026-08-05-session-preparation.zh.md: ec5b73e67c8ab9303f8840e16e4b4f2d928e7657
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
index a0ca27eb63..ec5b73e67c 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
@@ -47,7 +47,7 @@ agent loop（智能体循环）通过同一条设置与发布流水线消费这
 
 ## 验证
 
-共享持久化契约覆盖无变更且已配平的冷检查与后续修复。`persistence.spec.ts` 与 `preparations.spec.ts` 覆盖同 id 进行中读取共享、检查与准备之间的精确 Session 复用、在历史读取与恢复前由 revision 触发刷新、修复只提交一次、独占预留、设置失败后释放、就绪项 LRU 淘汰、预留期间拒绝 append，以及只允许发布预留 Session。后端测试覆盖完整读取与轻量读取使用同一 revision 身份。agent loop 与 continuable subagent 测试覆盖统一发布流水线，以及取消和拆卸期间从检查到恢复的路径。
+共享持久化约定覆盖无变更且已配平的冷检查与后续修复。`persistence.spec.ts` 与 `preparations.spec.ts` 覆盖同 id 进行中读取共享、检查与准备之间的精确 Session 复用、在历史读取与恢复前由 revision 触发刷新、修复只提交一次、独占预留、设置失败后释放、就绪项 LRU 淘汰、预留期间拒绝 append，以及只允许发布预留 Session。后端测试覆盖完整读取与轻量读取使用同一 revision 身份。agent loop 与 continuable subagent 测试覆盖统一发布流水线，以及取消和拆卸期间从检查到恢复的路径。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
index 43c5433343..9da3c3890f 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md
 2026-08-05-slot-declaration-injection.md: cb15125977c060144553d7cf75e3c2c26fb1b23b
-2026-08-05-slot-declaration-injection.zh.md: 385cab875bb445ba1ca324fc9b45363b8daf50b6
+2026-08-05-slot-declaration-injection.zh.md: 4b1fd40c26c6f055bb296807df4c888138ce7a64
diff --git a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
index 385cab875b..4b1fd40c26 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.zh.md
@@ -20,7 +20,7 @@ slot 级热替换还要求两个相互独立的所有者。移除声明方插件
 
 动态重载代码使用普通 Cordis 插件 fiber 作为替换单元：通过 `ctx.plugin()` 激活新模块；挂载替换模块之前，先 dispose 并等待旧 fiber；该 fiber 的 `slots.inject` 与 `slots.register` effect 会随之退出。renderer 订阅会观察到账本移除并卸载组件；无需建立 slot 自有的 fiber 树。
 
-## 失败与生命周期契约
+## 失败与生命周期约定
 
 如果注入创建时声明已经存在，回调 setup 失败会同步上报。延迟声明出现后发生的回调失败，会先取消订阅并回滚已收集的 effect，再在 slot 通知刷新之外上报，避免一个注册方使其他 listener 得不到执行机会。直接调用 `slots.register()` 向未声明 slot 注册仍会抛出异常：注入是显式机制，不会削弱加载时验证。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
index b6e58aabc7..bd036ba86e 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.md
 2026-08-06-agent-event-payload-objects.md: 470c8fb3f9282005829846307778d3d1088c3888
-2026-08-06-agent-event-payload-objects.zh.md: ff201a7c3134c0ef809c9a798d65412541f9f1e7
+2026-08-06-agent-event-payload-objects.zh.md: 861a1b9c12c4ff050a9825212b02bc6c4e1c662d
diff --git a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
index ff201a7c31..861a1b9c12 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Agent 作用域事件历来采用位置参数：开头的 `agent` 主体、事件专属字段，以及末尾用于 waterfall（瀑布式事件）/serial 事件的 `next`。新增字段或退役上下文类型（如 `PreStepContext` 与 `RequestFailureContext`）都会迫使跨包重写每个监听器和 emitter，契约也一直分散在参数列表中，而不是集中在一个具名 payload 中。
+Agent 作用域事件历来采用位置参数：开头的 `agent` 主体、事件专属字段，以及末尾用于 waterfall（瀑布式事件）/serial 事件的 `next`。新增字段或退役上下文类型（如 `PreStepContext` 与 `RequestFailureContext`）都会迫使跨包重写每个监听器和 emitter，约定也一直分散在参数列表中，而不是集中在一个具名 payload 中。
 
 ## 决策
 
@@ -18,7 +18,7 @@ dispatch 是融合的：`agentEvents(ctx, agent)`（以及一次性 `emitAgentEv
 
 ## 考虑过的替代方案
 
-**保留位置签名。** 新增字段或退役上下文类型依旧会重写每个监听器和 emitter，契约也会继续分散在参数列表中，而不是集中在一个具名 payload 中。
+**保留位置签名。** 新增字段或退役上下文类型依旧会重写每个监听器和 emitter，约定也会继续分散在参数列表中，而不是集中在一个具名 payload 中。
 
 **在每个 dispatch 位置手工构造主体。** loop 的中间设计调用 `ctx.waterfall(this.carrier, …)`，传入手工构造的 `{ agent: this, … }` payload；它避免了每次 dispatch 的分配，却重复了主体注入，并让作用域键与 payload 主体分叉。融合的 dispatcher 是每种 dispatch 模式的唯一注入点。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
index 0168528557..3bf5339f3e 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
 2026-08-06-subagent-list-identity-projection.md: ba023d04805ff3335c8f243510aa8ddc15fe13d6
-2026-08-06-subagent-list-identity-projection.zh.md: 368a70f5b3e5a27e4e1c648e8819476d40a57709
+2026-08-06-subagent-list-identity-projection.zh.md: 78aec8f4d0c47178bc033cc74f0314762f49cf7d
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
index 368a70f5b3..78aec8f4d0 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
@@ -27,8 +27,8 @@ mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠
 
 与既有记录的关系：
 
-- 本记录取代 [durable-subagent-catalog](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md) 中列表读路径的两项设计：经 `sessionQuery.traceSession` 枚举，与逐 child 读取描述符事件（`listEvents` 加精确 `readEvent` 双读、就地诊断分类）。diagnostic 行语义保留，分类改由列表按投影值缺席与 activity 派生；描述符事件仍是 mode/label 的唯一持久权威与折叠输入，恢复鉴权与激活契约不动。属部分取代，两记录保持交叉链接。
-- [session-projection RFC](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md) 的 registry 契约（`ProjectionDefinition`、`snapshot`、`restore`）零改动，本记录只为其新增 `subagent` 身份 unit 一个注册项，并成为 snapshot（live）与 restore（cold）两处既有读法的又一消费实例——GUI history 的冷读已是同款。折叠规则只在 registry 注册一份；任何消费面都经 registry 计算，不存在第二份折叠逻辑。
+- 本记录取代 [durable-subagent-catalog](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md) 中列表读路径的两项设计：经 `sessionQuery.traceSession` 枚举，与逐 child 读取描述符事件（`listEvents` 加精确 `readEvent` 双读、就地诊断分类）。diagnostic 行语义保留，分类改由列表按投影值缺席与 activity 派生；描述符事件仍是 mode/label 的唯一持久权威与折叠输入，恢复鉴权与激活约定不动。属部分取代，两记录保持交叉链接。
+- [session-projection RFC](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md) 的 registry 约定（`ProjectionDefinition`、`snapshot`、`restore`）零改动，本记录只为其新增 `subagent` 身份 unit 一个注册项，并成为 snapshot（live）与 restore（cold）两处既有读法的又一消费实例——GUI history 的冷读已是同款。折叠规则只在 registry 注册一份；任何消费面都经 registry 计算，不存在第二份折叠逻辑。
 
 ### `subagent` projection unit
 
@@ -47,8 +47,8 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 ```
 
 - 投影是纯身份，**projection 体系不做失败通道**：unit 永不抛错；载荷损坏、版本不认识与整日志没有描述符一样，折叠结果是**可序列化的 null 哨兵**——map 条目为 `SubagentIdentityProjection | null`，非可选、非 undefined/缺 key。理由：registry 的 onChanged 推送经 JSON 序列化，undefined 字段被 stringify 丢弃，客户端帧校验拒收，消费方存储的旧身份将永不更新；null 完好过帧，消费方以哨兵替换旧身份。判定纪律：消费面把 null 与 undefined（仅 JSON 边界丢 key 可产生）一律视为无值。"算出来没有"如何呈现是消费方自己的事（见下文 `listChildren` 四态映射）。
-- label 强度由描述符 schema 决定：continuable 的 label 解析强制必有，one-shot 的本就可选；mode/label 判别与下文 child 行的强契约完全一致（行不携带 `seq`——它是投影内部的 own-suffix 证明）。
-- 身份携带 `seq`：折出该身份的 `subagent/descriptor` 事件 seq，两臂必有、null 哨兵无——`seq >= header.seedLength ?? 0` 证明身份折叠自 child 自身后缀，而非 fork 种子回放的祖先描述符。state 增 `seq` 使 unit `stateVersion` 升至 2，既存 checkpoint 行按 registry 契约版本失配失效、落权威重折。
+- label 强度由描述符 schema 决定：continuable 的 label 解析强制必有，one-shot 的本就可选；mode/label 判别与下文 child 行的强约定完全一致（行不携带 `seq`——它是投影内部的 own-suffix 证明）。
+- 身份携带 `seq`：折出该身份的 `subagent/descriptor` 事件 seq，两臂必有、null 哨兵无——`seq >= header.seedLength ?? 0` 证明身份折叠自 child 自身后缀，而非 fork 种子回放的祖先描述符。state 增 `seq` 使 unit `stateVersion` 升至 2，既存 checkpoint 行按 registry 约定版本失配失效、落权威重折。
 - 折叠规则：`subagent/descriptor` last-wins，与 `subagentTiming` 同一条 descriptor-reset 纪律——fork 前缀里的祖先描述符被自身描述符覆盖。损坏或版本不认识的载荷同样 last-wins：重置为 null 哨兵而非保留先前身份，健康祖先的 fork 不会继承自身描述符立不住的身份。
 
 ### 枚举：subagent 自管 live-preferred 合并
@@ -58,7 +58,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 - 过滤：`header.origin === 'subagent' && header.parentSession === parentSessionId`。
 - `hasChildren`：同一份合并材料向下看一层——存在 `origin === 'subagent'` 且 `parentSession` 为该 child 的直接后代。
 - `activity`：live 记录为 `running`，仅存在于持久化的为 `inactive`。
-- 排序：`createdAt` 升序、再按 child id 升序（与旧契约一致）。
+- 排序：`createdAt` 升序、再按 child id 升序（与旧约定一致）。
 - **persistence 缺席退为 live-only 枚举，不报错**：没有 persistence 的部署，cold child 本就无法 resume，列出 live child 仍然有意义。（对照：旧实现在 sessionQuery 缺失时整体拒绝。）
 - persistence 列表失败使整次枚举失败；per-child 隔离只作用于逐 child 的冷读。
 
@@ -72,8 +72,8 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 | 2：cold child，cache 命中 | 可选 `sessionProjectionCache.cachedSnapshot(header)`，values 含非 null 的 `subagent` 身份且 `identity.seq >= header.seedLength ?? 0` 才直接用——own descriptor 一经追加不可变，seq 门证明该值折叠自 child 自身后缀，无视行水位 | 零日志读 |
 | 3：cold child，兜底 | `persistence.inspect(id)` 整读 + `registry.restore({}, events, 0).snapshot.values.subagent` | 每次列表一次整读现算 |
 
-- 错误契约：`ctx.sessionProjections` 未挂载是配置错误，`listChildren` 在枚举前无条件检查并以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败——零 children 的部署同样确定失败，不因列表恰好为空而掩盖配置问题。会话存储同理：`ctx.get('sessions')`（严格全局读取，不走调用方作用域的属性代理）缺席以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 失败。两码的 wire 映射有别：apiproxy 只为 `PROJECTIONS_UNAVAILABLE` 设专门 wire 脸，`SESSION_STORE_UNAVAILABLE` 走通用 internal 兜底——apiproxy 组合自身就 inject `sessions`，该错误在其部署不可达，专门映射违反 need 原则。`SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 已随 session-query 依赖删除。
-- cache 是纯可选加速层：服务缺席判空跳过——无错误码、不进配置校验（与 `sessionProjections` 的响亮契约相对）。第二级任何抛错（包括缓存内任一 unit 行中毒使 `viewCheckpoint` 引爆）静默落第三级——缓存是派生数据，其故障不产生 `corrupt` 判决，终审归权威重折；checkpoint 切面早于描述符的行，`subagent` key 天然缺席，自动落底，无特判；行里的 null 哨兵同样不作数——一律落第三级，由权威重折裁决。创建窗口内的 count/interval checkpoint 可能把 fork 种子回放的祖先身份落进行——祖先 seq 落在 seed 区间，被 seq 门拒绝，同样落第三级裁决。
+- 错误约定：`ctx.sessionProjections` 未挂载是配置错误，`listChildren` 在枚举前无条件检查并以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败——零 children 的部署同样确定失败，不因列表恰好为空而掩盖配置问题。会话存储同理：`ctx.get('sessions')`（严格全局读取，不走调用方作用域的属性代理）缺席以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 失败。两码的 wire 映射有别：apiproxy 只为 `PROJECTIONS_UNAVAILABLE` 设专门 wire 脸，`SESSION_STORE_UNAVAILABLE` 走通用 internal 兜底——apiproxy 组合自身就 inject `sessions`，该错误在其部署不可达，专门映射违反 need 原则。`SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 已随 session-query 依赖删除。
+- cache 是纯可选加速层：服务缺席判空跳过——无错误码、不进配置校验（与 `sessionProjections` 的响亮约定相对）。第二级任何抛错（包括缓存内任一 unit 行中毒使 `viewCheckpoint` 引爆）静默落第三级——缓存是派生数据，其故障不产生 `corrupt` 判决，终审归权威重折；checkpoint 切面早于描述符的行，`subagent` key 天然缺席，自动落底，无特判；行里的 null 哨兵同样不作数——一律落第三级，由权威重折裁决。创建窗口内的 count/interval checkpoint 可能把 fork 种子回放的祖先身份落进行——祖先 seq 落在 seed 区间，被 seq 门拒绝，同样落第三级裁决。
 - per-child 隔离：单 child 的 cold 整读失败只使该行成为 `unavailable` diagnostic，下次列表自然重试，不影响 sibling（见四态映射）。
 - 冷路径的生命周期见证：preparation 的结果必须仍指向枚举时的那个生命周期——见证字段集与旧 SOURCE_CONFLICT 检查同款七字段（version、id、createdAt、cwd、parentSession、seedLength、delegationDepth）；同 id 删除后重新发布的会话对旧 parent 的目录降级为 `corrupt` 行，不外漏新 owner 的 child。
 - 冷读并发以常数 4 有界——它约束的是本地介质的一次只读扫描而非部署行为；出现联网 persistence backend 时提升为验证过的 `Config` 字段。
@@ -88,7 +88,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 
 ### `listChildren` 行形状与消费面
 
-`SubagentListEntry` **数据结构与重写前完全一致**——child 与 diagnostic 两臂、`kind` 判别、reason 三值、child 臂的 mode/label 强契约全部保留；变化只在诊断的信息来源：投影体系没有失败通道，diagnostic 由列表按投影值缺席与 activity 派生，列表本身零事件解析。"没有就等待硬读取"保证阶梯对健康数据必然算得出 mode/label。
+`SubagentListEntry` **数据结构与重写前完全一致**——child 与 diagnostic 两臂、`kind` 判别、reason 三值、child 臂的 mode/label 强约定全部保留；变化只在诊断的信息来源：投影体系没有失败通道，diagnostic 由列表按投影值缺席与 activity 派生，列表本身零事件解析。"没有就等待硬读取"保证阶梯对健康数据必然算得出 mode/label。
 
 ```ts ignore-check
 export type SubagentListEntry =
@@ -124,11 +124,11 @@ export type SubagentListEntry =
 已知边界偏差（有意接受，随本记录留档）：
 
 - 死于发布窗口的 fork child，seed 里若有祖先描述符，last-wins 会给出祖先身份，误现为 child 行；恢复仍按 own-suffix 折叠权威失败（`NOT_RESUMABLE`）。旧实现靠 `seedLength` 过滤将其 omit；projection unit 看不到 header，接受此残骸级偏差（`subagentTiming` 有同类既有暴露）。
-- own suffix 出现多个描述符，旧实现判 corrupt，现 last-wins 取末者（provider 契约本就保证恰一）。
+- own suffix 出现多个描述符，旧实现判 corrupt，现 last-wins 取末者（provider 约定本就保证恰一）。
 - live/persisted header 冲突，旧实现是 per-child corrupt；现枚举 live 优先、不做一致性校验，冲突不再被察觉，以 live 记录成行。
 - 损坏存储的源读失败（如坏 surface 被冷读整读拒收），旧实现映射 per-child `corrupt`，现统一成 `unavailable` 行（读侧无从区分成因）。
 - 未知 parent，旧实现经 session-query 抛 not-found（'parent session … was not found'）；现自管合并对不存在的 parent 得到空子集，枚举返回空列表，wire 上后续操作落到 child 级 subagent-not-found——语义与文案的静默变化，显式接受。
-- rung 2 的更晚事件窗口：cache 行恰在首个自有描述符之后落盘，日志随后追加第二个自有描述符（或 malformed 载荷置 null 哨兵），且进程在下一次 checkpoint 前崩溃——此后冷列表的 rung 2 凭 seq≥seedLength 门持续供出行内旧身份（第一个自有描述符的值），与权威重折（last-wins 第二个）分歧，且 rung 2 命中期间不触发重折、无从察觉。边界三条：①前提是同一 child 出现第二个自有描述符，违反 establishing provider"恰追加一次"契约，属损坏类数据，与多描述符偏差同族同源；②需"损坏 + 崩溃错过 checkpoint（turn/end 与 disposal 两个 mandatory 点及 count/interval 节流点全部未及）"双条件同时成立；③健康 child（恰一自有描述符）不受影响——seq 门放行的正是唯一真身份。自愈条件：该 child 任一次 live 运行（turn/end mandatory checkpoint）或任何触发 cache.write 的时点，都会以新 fold 整行覆写（whole-record replace），rung 2 随即供正；权威路径（rung 3 重折、live snapshot、resume 折叠）自始正确，分歧只存在于持续冷、行未再更新期间的列表读。机制修法不采：gate 对账需知日志末端 seq，冷路径零读不可得；cache 行携 revision 是 opaque token，无法比较且跨域改 schema——按"cache 永不为权威"总纲归档为接受项。
+- rung 2 的更晚事件窗口：cache 行恰在首个自有描述符之后落盘，日志随后追加第二个自有描述符（或 malformed 载荷置 null 哨兵），且进程在下一次 checkpoint 前崩溃——此后冷列表的 rung 2 凭 seq≥seedLength 门持续供出行内旧身份（第一个自有描述符的值），与权威重折（last-wins 第二个）分歧，且 rung 2 命中期间不触发重折、无从察觉。边界三条：①前提是同一 child 出现第二个自有描述符，违反 establishing provider"恰追加一次"约定，属损坏类数据，与多描述符偏差同族同源；②需"损坏 + 崩溃错过 checkpoint（turn/end 与 disposal 两个 mandatory 点及 count/interval 节流点全部未及）"双条件同时成立；③健康 child（恰一自有描述符）不受影响——seq 门放行的正是唯一真身份。自愈条件：该 child 任一次 live 运行（turn/end mandatory checkpoint）或任何触发 cache.write 的时点，都会以新 fold 整行覆写（whole-record replace），rung 2 随即供正；权威路径（rung 3 重折、live snapshot、resume 折叠）自始正确，分歧只存在于持续冷、行未再更新期间的列表读。机制修法不采：gate 对账需知日志末端 seq，冷路径零读不可得；cache 行携 revision 是 opaque token，无法比较且跨域改 schema——按"cache 永不为权威"总纲归档为接受项。
 
 消费面：wire、tool、GUI 的 diagnostic 处理**全部保持原状零改动**（`list_agents` 的 description 与 output schema 未动；该插件仅加载要求收窄——inject 去掉 `sessionQuery`）。行为上动的只有 apiproxy：路由段的 `hasSubagentDescriptor()` 扫描已删除，`hasSubagentOwner` 只看 `header.origin`——pre-#1569 的无 `origin` 存量不再被认作 subagent 属主，其本就不进目录，pre-release 立场接受；`subagents.history` 与 `session.history` 同源对齐——live child 用内存事件与注册表水位快照，cold child 用 `inspectServable` 直读持久化并 detached 折叠，不经查询服务，SESSION_QUERY_* 错误臂随之退役，wire 形状不变（`history` 的 JSDoc 措辞改为 live 内存快照／cold 持久日志双臂）。
 
@@ -151,9 +151,9 @@ export type SubagentListEntry =
 
 **给 persistence 加有界读原语抢救存量。** 为一次性问题新开 seam 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
 
-**list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强契约加算不出即 omit 更干净。
+**list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强约定加算不出即 omit 更干净。
 
-**彻底删除 diagnostic 行（v5 一稿）。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担契约与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
+**彻底删除 diagnostic 行（v5 一稿）。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担约定与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
 
 **registry 计算失败通道（per-unit 容错加 `failures` 附加字段）。** 为把损坏、版本不认识报告给消费方，曾考虑让 registry 捕获 unit 异常并在 snapshot 旁附 per-key 失败态。被否：failure 不是值，也不必是通道——unit 永不抛错，缺席本身就是信号，"大不了算出来没有"，如何呈现是消费方要考虑的事。该路线讨论顺带留下一个独立观察：vendor cordis 的 `emit`（[vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)）对 listener 抛错零捕获，投影驱动挂在 `session/event` 上时 unit 异常会沿 emit 逃逸——这加重了"unit 永不抛错"纪律的分量，但 emit 容错的修复不属于本记录范围。
 
@@ -165,7 +165,7 @@ export type SubagentListEntry =
 
 ## 验证
 
-`packages/subagent/subagent/tests/list-children.spec.ts` 重写为本契约：无 persistence、query 服务与继续运行时的 live-only 列表；registry 缺席时零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`；live child 全程零 `inspect`、cold child 每次列表恰一次；多描述符 last-wins 取末者；损坏载荷与未知版本折为 `corrupt`；冷读失败映射 `unavailable` 且下次列表重试；fork seed 里的祖先描述符按该身份成行（偏差一钉住）；普通 fork 与无 subagent origin 的后代不入列也不计入 `hasChildren`；`createdAt`→id 排序；provider 未挂载不影响列表；压缩与未压缩孪生一致；预中止、持久化列表与冷读取消三例归一 `CANCELLED`；空列表与稳定错误码。敌意 unit 双路探针（`apply` 惰性置毒、`view` 引爆）证明任一注册 unit 在该 child 日志上的 fold/schema 抛错，在 live 与 cold 两条取值路径上都收纳为该 child 的 `corrupt` 行，sibling 与列表本身不受影响。第二级例：own-seq 身份直用零 `inspect`、fork 种子祖先身份（seq 落在 seed 区间）被门拒绝落底、行内无身份（null 哨兵或 key 缺席）落底、cache 服务缺席落底、缓存行中毒静默落底重折；冷路径 lifecycle 篡改按见证七字段逐一（`it.each`）降级为 `corrupt`。`tool-subagent-control` 的 list-agents 测试随加载要求收窄更新；`optional-session-query.spec.ts` 随依赖消失删除；既有无密钥快照（`subagent-list-agents` 等）零变化，钉住健康路径的 wire 与 model-visible 面不变；新增无密钥快照 `subagent-diagnostic`（examples/headless-agent）钉住四态映射的诊断分类——descriptor-less 定局残骸成 `corrupt` 行等模型可见变化。
+`packages/subagent/subagent/tests/list-children.spec.ts` 重写为本约定：无 persistence、query 服务与继续运行时的 live-only 列表；registry 缺席时零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`；live child 全程零 `inspect`、cold child 每次列表恰一次；多描述符 last-wins 取末者；损坏载荷与未知版本折为 `corrupt`；冷读失败映射 `unavailable` 且下次列表重试；fork seed 里的祖先描述符按该身份成行（偏差一钉住）；普通 fork 与无 subagent origin 的后代不入列也不计入 `hasChildren`；`createdAt`→id 排序；provider 未挂载不影响列表；压缩与未压缩孪生一致；预中止、持久化列表与冷读取消三例归一 `CANCELLED`；空列表与稳定错误码。敌意 unit 双路探针（`apply` 惰性置毒、`view` 引爆）证明任一注册 unit 在该 child 日志上的 fold/schema 抛错，在 live 与 cold 两条取值路径上都收纳为该 child 的 `corrupt` 行，sibling 与列表本身不受影响。第二级例：own-seq 身份直用零 `inspect`、fork 种子祖先身份（seq 落在 seed 区间）被门拒绝落底、行内无身份（null 哨兵或 key 缺席）落底、cache 服务缺席落底、缓存行中毒静默落底重折；冷路径 lifecycle 篡改按见证七字段逐一（`it.each`）降级为 `corrupt`。`tool-subagent-control` 的 list-agents 测试随加载要求收窄更新；`optional-session-query.spec.ts` 随依赖消失删除；既有无密钥快照（`subagent-list-agents` 等）零变化，钉住健康路径的 wire 与 model-visible 面不变；新增无密钥快照 `subagent-diagnostic`（examples/headless-agent）钉住四态映射的诊断分类——descriptor-less 定局残骸成 `corrupt` 行等模型可见变化。
 
 ## 后果
 
@@ -179,6 +179,6 @@ export type SubagentListEntry =
 ## 相关
 
 - [durable-subagent-catalog 与 list_agents](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)——被本记录部分取代：描述符仍是 mode/label 的持久权威与折叠输入，列表的枚举与取值改为自管合并加投影阶梯。
-- [session projections 与命令生命周期日志](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md)——registry 契约的权威；本记录为其新增 `subagent` 身份 unit，并成为 snapshot/restore 两处既有读法的消费实例。
+- [session projections 与命令生命周期日志](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md)——registry 约定的权威；本记录为其新增 `subagent` 身份 unit，并成为 snapshot/restore 两处既有读法的消费实例。
 - [web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)——`SessionHeader.origin` 的出处（#1569），身份判定去日志化的前半步；其 history 冷读（inspect 前缀加 registry 折叠）是本记录取值阶梯的同款先例。
 - [发布前可复用的 Session 准备阶段](2026-08-05-session-preparation.md)——`inspect()` 冷读与 LRU 复用；cold child 整读的成本模型建立其上。
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
index 20d21565b5..087513c174 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.md
 2026-08-06-web-markdown-incremental-ast-renderer.md: 3599bfcc78dc4eefe5e82f461a469bdba15f3aae
-2026-08-06-web-markdown-incremental-ast-renderer.zh.md: 2e00977da58ef29a77c45abcecf0f3bb62737929
+2026-08-06-web-markdown-incremental-ast-renderer.zh.md: c3a1134a478ee4c67a581fce63f20bc6ea1d6c33
diff --git a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
index 2e00977da5..c3a1134a47 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 - **语法**([parse.ts](../../../../packages/client/ui-primitives/src/markdown/parse.ts)):`parseGfm`(流式臂与 `extractMarkdownPlainText`)和 `parseGfmWithMath`(定稿臂)以被替换的 remark 插件所包装的同一组 micromark 扩展调用 `mdast-util-from-markdown`,因此各处块边界完全一致。`mathCompatibility`(原 `remarkMathCompatibility`)现在直接导出其 micromark 扩展。
 - **增量解析**([incremental.ts](../../../../packages/client/ui-primitives/src/markdown/incremental.ts)):CommonMark 块解析按行推进,追加文本只会重塑解析前沿。`IncrementalMarkdownParser` 保留末尾两个块不稳定(最后一块是前沿;倒数第二块是安全裕量),冻结其前的所有块,只从最后一个冻结块的 `position.end.offset` 起重新解析源尾部——用的是解析器自己的偏移量,没有任何自制源扫描。每个源区间在整个流中解析 O(1) 次而非每 chunk 一次;单个巨型块(未闭合围栏)退化为旧的全量重解析成本,不会更差。非追加输入在递增的 generation 下重置状态。
-- **渲染**([render.tsx](../../../../packages/client/ui-primitives/src/markdown/render.tsx)、[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)):一个对 mdast 节点类型的 switch 取代 remark-rehype + react-markdown,逐字节复刻被替换管线的 DOM——表格对齐渲染为 `text-align` 样式、紧凑列表段落解包、任务列表类名与复选框空格、脚注区(其页内锚点本就被协议白名单降为纯文本)、字面 raw HTML、会与字面 HTML 文本相邻显形的分隔换行,以及 rehype-katex 的三臂容错链,KaTeX HTML 经浏览器自带的 `DOMParser` 映射为 React(无包裹元素,首/末子元素的 margin 规则仍能作用于 `.katex-display`;React 18 会把 `.katex-mathml` 子树放进 HTML 命名空间,与被替换管线完全一致——既有限制,不在本对等性契约范围内,对承担视觉渲染的 `.katex-html` 臂不可见)。冻结块缓存其 React 元素并保持源偏移 key,跨过冻结边界时走 reconcile 而非重挂载;`MarkdownText` 已 memo 化。
+- **渲染**([render.tsx](../../../../packages/client/ui-primitives/src/markdown/render.tsx)、[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)):一个对 mdast 节点类型的 switch 取代 remark-rehype + react-markdown,逐字节复刻被替换管线的 DOM——表格对齐渲染为 `text-align` 样式、紧凑列表段落解包、任务列表类名与复选框空格、脚注区(其页内锚点本就被协议白名单降为纯文本)、字面 raw HTML、会与字面 HTML 文本相邻显形的分隔换行,以及 rehype-katex 的三臂容错链,KaTeX HTML 经浏览器自带的 `DOMParser` 映射为 React(无包裹元素,首/末子元素的 margin 规则仍能作用于 `.katex-display`;React 18 会把 `.katex-mathml` 子树放进 HTML 命名空间,与被替换管线完全一致——既有限制,不在本对等性约定范围内,对承担视觉渲染的 `.katex-html` 臂不可见)。冻结块缓存其 React 元素并保持源偏移 key,跨过冻结边界时走 reconcile 而非重挂载;`MarkdownText` 已 memo 化。
 
 DOM 由 `tests/fixtures/markdown-dom` 钉死:fixture 录制自替换前的 react-markdown 实现,新渲染器必须在空白规整序列化器下复现。fixture 差异即用户可见的 markdown 样式变更,必须按此评审,绝不能为重构而重录。`tests/markdown-incremental.spec.tsx` 承载等价性性质——以 1/3/7/16 字节分块,在每个追加前缀处,常驻组件的 DOM 都等于全新挂载——外加冻结边界的 DOM 节点同一性与重置行为。
 
@@ -30,4 +30,4 @@ DOM 由 `tests/fixtures/markdown-dom` 钉死:fixture 录制自替换前的 react
 
 ## Consequences
 
-流式的每 chunk 工作量现在跟随不稳定尾部而非整个回复,react-markdown、remark-gfm、remark-math、rehype-katex、unified 及 hast 链退出浏览器 bundle(`mdast-util-math` 与 `micromark-util-sanitize-uri` 成为直接依赖;两者原本就是传递依赖)。包自有约 25 个节点映射、其测试以及 KaTeX DOM 转换——代价由冻结其输出的 fixture 契约对冲。两个行为偏差,均在定稿的全量解析处自愈:定义落在冻结边界另一侧的引用式链接或脚注在流式期间渲染为字面文本;当脚注定义先冻结而引用块仍不稳定时,脚注引用可能闪回字面文本。本模块与 KaTeX 转换假定浏览器 DOM(`DOMParser`),这个 client-only 包本就如此。
+流式的每 chunk 工作量现在跟随不稳定尾部而非整个回复,react-markdown、remark-gfm、remark-math、rehype-katex、unified 及 hast 链退出浏览器 bundle(`mdast-util-math` 与 `micromark-util-sanitize-uri` 成为直接依赖;两者原本就是传递依赖)。包自有约 25 个节点映射、其测试以及 KaTeX DOM 转换——代价由冻结其输出的 fixture 约定对冲。两个行为偏差,均在定稿的全量解析处自愈:定义落在冻结边界另一侧的引用式链接或脚注在流式期间渲染为字面文本;当脚注定义先冻结而引用块仍不稳定时,脚注引用可能闪回字面文本。本模块与 KaTeX 转换假定浏览器 DOM(`DOMParser`),这个 client-only 包本就如此。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
index 05c9a1fdd2..df37c8aa83 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
 2026-08-08-bounded-session-persistence-write-batching.md: 46dc612492fa1bfa805f77f865f14b168f52776f
-2026-08-08-bounded-session-persistence-write-batching.zh.md: 4aafdd652aad87cfe74a449428cdbbf13312d260
+2026-08-08-bounded-session-persistence-write-batching.zh.md: fe1227f7706ba67a12bd7f19db5c0c57cfcfca4f
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
index 4aafdd652a..fe1227f770 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
@@ -38,7 +38,7 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 **不持久化流式分片事件。** 这里不采纳：这会改变事件日志作为真源的地位及恢复语义，而不只是改变物理写入节奏。在无信息损失的替代方案独立定义回放、fork、来源信息、序列和崩溃行为之前，现有的[拒绝仅保留组装消息的决策](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)仍是防护规则。[打包行决策](2026-07-26-packed-chunk-rows-by-default.md)仍是配套的 JSONL 存储体积优化。
 
-**仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序契约。
+**仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序约定。
 
 **按最新事件重置防抖窗口。** 不采纳：持续不断的流式响应可能无限期推迟首次写入。由第一个待处理事件启动的固定窗口，为主动合并等待提供了真正的上界。
 
@@ -46,13 +46,13 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 ## 验证
 
-控制器测试使用假时钟证明固定且不会重置的 200 ms 窗口、即时且可共享的 flush 屏障、屏障运行期间接纳的事件、在活跃写入之后已超过窗口时限的尾部批次、有序保留失败批次、暂停自动重试，以及显式 flush 会重试与其重叠发生的后台失败。协调器测试会在 Session 通知、退役、冲突回收和 teardown 路径中验证该控制器。JSONL 与 SQLite 测试套件继续覆盖存储格式、事务、恢复和共享持久化契约。
+控制器测试使用假时钟证明固定且不会重置的 200 ms 窗口、即时且可共享的 flush 屏障、屏障运行期间接纳的事件、在活跃写入之后已超过窗口时限的尾部批次、有序保留失败批次、暂停自动重试，以及显式 flush 会重试与其重叠发生的后台失败。协调器测试会在 Session 通知、退役、冲突回收和 teardown 路径中验证该控制器。JSONL 与 SQLite 测试套件继续覆盖存储格式、事务、恢复和共享持久化约定。
 
 ## 后果
 
 高频事件突发通常会减少持久化追加操作，同时保持逻辑事件数量完全不变。减少幅度取决于事件到达速率和后端延迟：位于同一 200 ms 窗口内的突发事件会成为一个批次，而强制 flush 与稀疏事件仍可能产生小批次。
 
-本决策不会限制因后端缓慢而积压的待处理事件数量或字节数，也不会减少 SQLite 行数或解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放契约，而不是再引入一条隐式计时器规则。
+本决策不会限制因后端缓慢而积压的待处理事件数量或字节数，也不会减少 SQLite 行数或解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放约定，而不是再引入一条隐式计时器规则。
 
 接纳后的事件在配置窗口内可能只存在于内存中，此后在等待调度或后端工作完成期间也可能如此。部署可以选择较小的值以缩短普通丢失窗口，也可以选择较大的值以加强批处理。显式持久性边界保持不变，并会绕过等待。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index e1beb13c2c..81e53d0e26 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
 2026-08-08-client-tool-presentation-ownership.md: 9ea7d7dfc5e18e541550569795c5e1db84d6ad91
-2026-08-08-client-tool-presentation-ownership.zh.md: 11a42ad69e4374afa6dccd3af74b8bd1b5e5c6f1
+2026-08-08-client-tool-presentation-ownership.zh.md: 010907144dea256fa97cc6bd49bbcf493ad64c78
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index 11a42ad69e..010907144d 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 Client Runtime 已经把 Tool 调用投影成稳定的生命周期：它按 `callId` 配对 call/result 事件，保留 running 与 settled 两种形态，并按 root call 索引 Code Dispatch 子调用。但 chat view 仍拥有整套展示链路：它在 ChatFlow 中放置 root call，把每个 root 与 subcall 编排在一起，按 Tool 名称分发每个原子调用，携带通用 fallback 与 card model，注册第一方 Tool view，并在 details panel 中复用这些 model。
 
-这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的 Tool 专属编排契约。增加 Tool 专属 Session projection 会重复 Runtime 已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
+这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的 Tool 专属编排约定。增加 Tool 专属 Session projection 会重复 Runtime 已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
 
 ## Decision
 
@@ -60,13 +60,13 @@ Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sess
 | 业务 Tool 插件 | [`ui-skill` 注册例](../../../../packages/client/ui-skill/src/client/index.ts) | 一个或多个 wire Tool name 的原子 view | root/subcall 位置与生命周期配对 |
 | details 路径 | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx)、[`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected call 定位、card-aware output 与 raw fallback | chat 调用树编排 |
 
-## Slot 与 owner 契约
+## Slot 与 owner 约定
 
 slot 声明同时限定渲染所有权。conversation chat entry 通过 `children` 声明 `'conversation.chat.tool'`，因此只有 `ChatView` 放置整体 Tool 席位；`ui-tool` 注册该席位时再通过 `children` 声明 `'tool.call.toolview'`，因此只有 `ToolCallTree` 渲染原子 Tool 席位。业务插件只注册 keyed entry，不参与 root/subcall 编排，也不建立与 slot 平行的 registry。
 
 整体席位的 `ToolTreeOwnerProps` 携带 root `callId`、`toolName`、`ToolCallBlock`、`selectedCallId`、session `cwd`、`openFile(path)` 与 `inspectCall(callId)`。`ToolCallTree` 把 root 或 child 转成相同的 `ToolCallOwnerProps`，并把 inspect 收窄成当前 call 的回调。原子 owner 不携带 `ReactNode`、Cordis `Context`、Session service 或 projector；业务 view 只消费一个标准调用块和宿主动作。
 
-席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 契约：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
+席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 约定：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
 
 业务插件遵循同一个注册形态：
 
@@ -86,7 +86,7 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 ## Verification
 
-测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主契约；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
+测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主约定；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
index 6214a34d9c..a46aade24d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-19-windows-atomic-write-dacl-preservation.md
 2026-07-19-windows-atomic-write-dacl-preservation.md: be9f82174300a7d605c6a6e63878728f08cb37be
-2026-07-19-windows-atomic-write-dacl-preservation.zh.md: d31b52b0a99240a1e4449427438e1e187b1b98da
+2026-07-19-windows-atomic-write-dacl-preservation.zh.md: ed52773b0314e06ecdc470f9d569685c47a7aec3
diff --git a/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md b/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
index d31b52b0a9..ed52773b03 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## 决策
 
-`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的访问策略及其他替换元数据。其 ACL 合并过程可能重新序列化自动继承状态或复制等价 ACE，因此不能把自相对安全描述符缓冲区的逐字节相等作为稳定契约。新的 Windows 文件没有既有描述符需要保留，因此仍继承目标目录的 DACL；其暂存目录也因此位于目标文件旁。POSIX 继续使用仅所有者可访问的暂存 mode，并保留现有目标文件的 mode。
+`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的访问策略及其他替换元数据。其 ACL 合并过程可能重新序列化自动继承状态或复制等价 ACE，因此不能把自相对安全描述符缓冲区的逐字节相等作为稳定约定。新的 Windows 文件没有既有描述符需要保留，因此仍继承目标目录的 DACL；其暂存目录也因此位于目标文件旁。POSIX 继续使用仅所有者可访问的暂存 mode，并保留现有目标文件的 mode。
 
-Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件中保持顺序且去重后的 ACE 策略。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。mode 位断言仍仅适用于 POSIX；新文件的 DACL 继承由操作系统契约规定，不应通过特定机器的账户允许列表来断言。
+Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件中保持顺序且去重后的 ACE 策略。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。mode 位断言仍仅适用于 POSIX；新文件的 DACL 继承由操作系统约定规定，不应通过特定机器的账户允许列表来断言。
 
 ## 备选方案
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
index 05d9cfd033..032ba43584 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-21-semantic-session-checkpoints.md
 2026-07-21-semantic-session-checkpoints.md: 697d878dccbfab1ded9f73e134d594ba6f0665e1
-2026-07-21-semantic-session-checkpoints.zh.md: e4d432cfa4655fcf6b010ab944dc12095eca009c
+2026-07-21-semantic-session-checkpoints.zh.md: c72f2bbad33967f54013f05568b9d1082d549357
diff --git a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
index e4d432cfa4..c72f2bbad3 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md
@@ -26,4 +26,4 @@ ACP（Agent Client Protocol）应用在一个有序 Cordis effect 中统一持
 
 ## 后果
 
-发生硬崩溃时，崩溃恢复会在最近的语义边界保留完整的模型请求、持久化的工具意图与完整且已结束的步骤，但允许上一个边界之后的部分流式分片仍可能丢失。默认的 CLI（命令行界面）、TUI、ACP、Python SDK 运行时、headless 持久化测试与 JSON-RPC 组合都会在持久化后端旁加载该策略。单元测试覆盖顺序、检查点期间的取消、失败关闭行为、嵌套分发、dispose（资源释放）与 Loader 形状，以及最终检查点的顺序与故障隔离；一个被 `SIGKILL` 终止的真实子进程通过 JSONL 证明系统可以恢复请求与工具意图，共享持久化契约则证明各后端都支持这两种恢复分类。崩溃 harness 会等待预期的标记内容，而不是仅等待路径存在，因此文件在写入前因打开而可见时，不会导致该 harness 提前终止子进程。无密钥 ACP 与 SDK 快照证明重试风险指引会进入恢复后的历史记录与下一个模型轮次，取消流程正常收尾时系统会持久化由循环实际生成的闭合边界，且 SDK 关闭流程会观察到已完整持久化的轮次。
+发生硬崩溃时，崩溃恢复会在最近的语义边界保留完整的模型请求、持久化的工具意图与完整且已结束的步骤，但允许上一个边界之后的部分流式分片仍可能丢失。默认的 CLI（命令行界面）、TUI、ACP、Python SDK 运行时、headless 持久化测试与 JSON-RPC 组合都会在持久化后端旁加载该策略。单元测试覆盖顺序、检查点期间的取消、失败关闭行为、嵌套分发、dispose（资源释放）与 Loader 形状，以及最终检查点的顺序与故障隔离；一个被 `SIGKILL` 终止的真实子进程通过 JSONL 证明系统可以恢复请求与工具意图，共享持久化约定则证明各后端都支持这两种恢复分类。崩溃 harness 会等待预期的标记内容，而不是仅等待路径存在，因此文件在写入前因打开而可见时，不会导致该 harness 提前终止子进程。无密钥 ACP 与 SDK 快照证明重试风险指引会进入恢复后的历史记录与下一个模型轮次，取消流程正常收尾时系统会持久化由循环实际生成的闭合边界，且 SDK 关闭流程会观察到已完整持久化的轮次。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
index 6a898fa0a4..3e97fb3f06 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-glob-sampling.md
 2026-07-27-glob-sampling.md: 67912cf290b127a96819d57f30387197af68323d
-2026-07-27-glob-sampling.zh.md: e339a5f87b483849df60feb726b061fe85074300
+2026-07-27-glob-sampling.zh.md: b8d7bbe1bc70e94cc4239867244be554eaf33e63
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
index e339a5f87b..b8d7bbe1bc 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md
@@ -22,17 +22,17 @@ Status: implemented
 
 **只保留按修改时间排序的前部。** 测量实际故障形态后否决。某些部署需要这种稳定排序；但重视工作区定位的部署可以显式选择具有代表性的数据，而不必要求模型怀疑自己拿到的唯一一批路径。
 
-**为采样选项提供默认值。** 否决。没有全产品范围的证据支持把任一排序作为隐式契约，因此每个组合都必须选择一种，配置错误则在加载时失败。
+**为采样选项提供默认值。** 否决。没有全产品范围的证据支持把任一排序作为隐式约定，因此每个组合都必须选择一种，配置错误则在加载时失败。
 
 **对所有结果采样。** 否决。完整结果没有因截断损失任何信息，因此按修改时间排序仍有助于回答关注新旧时间的问题。只有当截取前部已经无法描述整体时，才开始采样。
 
-**改为最新优先排序。** 否决。这只会改变哪一棵结果集中的子树可能占据主导；既取消了现有的最旧优先契约，也没有让受限页面更具代表性。
+**改为最新优先排序。** 否决。这只会改变哪一棵结果集中的子树可能占据主导；既取消了现有的最旧优先约定，也没有让受限页面更具代表性。
 
-**仅在偏斜超过阈值时采样。** 否决。目前没有证据支持适用于所有部署的统一阈值，模型也无法判断当前采用的是哪一种排序契约。现有上限是可以清楚解释的切换点。
+**仅在偏斜超过阈值时采样。** 否决。目前没有证据支持适用于所有部署的统一阈值，模型也无法判断当前采用的是哪一种排序约定。现有上限是可以清楚解释的切换点。
 
 **在顶层以下递归平衡。** 暂缓。按第一路径段做平衡已经修复观测到的故障；更深层的平衡需要一套尚无依据的深度与广度取舍策略。
 
-**新增面向模型的 `list` 工具。** 实现评审后否决。默认编程组合已经提供通用 bash，模型也理解 `ls`；重复工具会永久增加 schema 与提示词所占的 token，并引入排序、分页、符号链接、转义、UI 与快照契约，却没有独立的安全或策略收益。不向模型提供 bash 工具的精简部署也不会因本次改动获得目录定位能力。
+**新增面向模型的 `list` 工具。** 实现评审后否决。默认编程组合已经提供通用 bash，模型也理解 `ls`；重复工具会永久增加 schema 与提示词所占的 token，并引入排序、分页、符号链接、转义、UI 与快照约定，却没有独立的安全或策略收益。不向模型提供 bash 工具的精简部署也不会因本次改动获得目录定位能力。
 
 **拒绝 `*`，或在不含分隔符的模式前静默加上根目录锚点。** 否决。同样的「在任意深度匹配文件名」行为使 `*.ts` 可以有效地跨目录树搜索。记录这条规则能够保留正常工作的 Ripgrep 语义。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
index 0820c01b7f..d17de641b9 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-stable-snapshot-refresh-volatiles.md
 2026-07-27-stable-snapshot-refresh-volatiles.md: c3eeeca01a7820b5f410bd895de998e944e58eb2
-2026-07-27-stable-snapshot-refresh-volatiles.zh.md: 388b67c67052074fa7423eae294e00b4122b2fe8
+2026-07-27-stable-snapshot-refresh-volatiles.zh.md: 79a2758e7a7353c983f4e8a9d2531830dec311e4
diff --git a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
index 388b67c670..79a2758e7a 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-27-stable-snapshot-refresh-volatiles.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别名、spill locator、嵌入的事件时间和省略字节数，但刷新写回会持久化本次生成的原始值。因此，即使比较契约将两份日志视为相等，一次行为未发生变化的刷新仍会用新的随机值或宿主特有的路径写法改写 fixture（测试前置数据）。
+ACP（Agent Client Protocol）快照比较会归一化生成的 UUID、cwd 别名、spill locator、嵌入的事件时间和省略字节数，但刷新写回会持久化本次生成的原始值。因此，即使比较约定将两份日志视为相等，一次行为未发生变化的刷新仍会用新的随机值或宿主特有的路径写法改写 fixture（测试前置数据）。
 
 消息身份所需的结构前提比记录对齐更弱：无关的日志事件可能破坏记录对齐，但继承而来的消息去除身份后的值在父级和子级日志之间仍保持不变。录制模式在替换现有 fixture 时也会从新生成的消息 UUID 开始。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
index 8c8b97c103..616caa6f68 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-28-load-pre-identity-session-messages.md
 2026-07-28-load-pre-identity-session-messages.md: 2901527658421b37576bdf5b49e66829104a3b41
-2026-07-28-load-pre-identity-session-messages.zh.md: 210064f6e7c1ea239da89c4542346e164c48e274
+2026-07-28-load-pre-identity-session-messages.zh.md: bf6e58d8a895f41012449a1212533902e1211e99
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
index 210064f6e7..bf6e58d8a8 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 **按照预发布兼容性立场拒绝这些日志。** 这是处理其他 v0 形状变动的默认方式，但即使每个旧字段都能明确映射到当前消息表示，它仍会导致真实的第一方会话无法恢复。
 
-**就地重写完整的存储日志。** 这会使产物规范化，但违反仅追加存储契约，还需要为 JSONL 和 SQLite 分别实现原子替换机制，并将一次读取兼容性修复扩大为迁移系统。
+**就地重写完整的存储日志。** 这会使产物规范化，但违反仅追加存储约定，还需要为 JSONL 和 SQLite 分别实现原子替换机制，并将一次读取兼容性修复扩大为迁移系统。
 
 **每次加载时随机生成 id。** 这些消息会满足类型形状，却无法在检查、恢复、重启以及新旧形状混合追加之间保持稳定标识。
 
@@ -30,9 +30,9 @@ Status: implemented
 
 消息标识机制引入前的 JSONL 和 SQLite 会话可以恢复，并保留原始的消息内容、来源、提供方溯源信息、工具调用关联、错误、元数据和 surface 替换。除此之外，返回事件与当前导入的消息快照无法区分，并且仍然经过深度冻结。
 
-这是一个显式的同版本导入例外，而非通用的 v0 兼容层。若要增加另一个例外，必须在持久化边界提供另一套完整且无歧义的映射；当前数据若格式错误，系统仍会拒绝，而不会猜测如何将其变成有效数据。共享的协调器契约会在内存参考实现、JSONL 和 SQLite 后端上验证这项升级，包括重新加载时的确定性，以及工具结果替换时的标识继承。
+这是一个显式的同版本导入例外，而非通用的 v0 兼容层。若要增加另一个例外，必须在持久化边界提供另一套完整且无歧义的映射；当前数据若格式错误，系统仍会拒绝，而不会猜测如何将其变成有效数据。共享的协调器约定会在内存参考实现、JSONL 和 SQLite 后端上验证这项升级，包括重新加载时的确定性，以及工具结果替换时的标识继承。
 
 ## 相关
 
-- [将每条消息创建为带标识的不可变值](../architecture/2026-07-28-identified-immutable-message-values.md)：该记录负责当前的消息标识与不可变性契约。
+- [将每条消息创建为带标识的不可变值](../architecture/2026-07-28-identified-immutable-message-values.md)：该记录负责当前的消息标识与不可变性约定。
 - [会话持久化作为抽象服务](../architecture/2026-06-14-session-persistence.md)：该记录负责仅追加后端与恢复边界。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
index 7950dc88f3..082158c75c 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-28-themed-scrollbars-and-reserved-gutter.md
 2026-07-28-themed-scrollbars-and-reserved-gutter.md: ba3d9d3c94cf9a775c43c14e292187b3a43935fe
-2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 51d668f584ee254183d5d1cf709140df2556e8d0
+2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 1cf505e96122a66705fe42fc79757ac390ebf0ef
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
index 51d668f584..1cf505e961 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
@@ -20,9 +20,9 @@ Status: implemented
 
 两种渲染互斥，而这种互斥是被强制的，不是假定的。`scrollbar-width` 或 `scrollbar-color` 只要取非 `auto` 值，Chromium 与 Safari 就会丢弃该元素上的全部 `::-webkit-scrollbar*` 规则，`::-webkit-scrollbar-thumb:hover` 也在其中。因此无条件地同时声明会让 hover token 在任何地方都得不到渲染：实现了 hover 伪元素的引擎，恰恰就是被标准属性静音的那些，而 Firefox 没有 hover 伪元素可作退路。于是标准属性写在 `@supports not selector(::-webkit-scrollbar)` 之内，该条件只在伪元素未被实现处为真，因此 Firefox 走标准属性路径，WebKit 系引擎走伪元素路径。WebKit 规则不再反向加门禁：不实现这些伪元素的引擎会把它们当作未知选择器丢弃，因此加门禁只是重述选择器匹配本身已经做的事。对于旧到不支持 `selector()` 函数的引擎，该条件无效，从而求值为假并选中伪元素路径——对于这条判断下现实存在的 16.4 之前的 Safari，这正是正确的一侧。
 
-两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
+两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定约定，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
 
-`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定契约由机械检查而非人工审阅把关。
+`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定约定由机械检查而非人工审阅把关。
 
 抬升表面集合是从调色板自身的暗色抬升阶梯解析出来的——暗色取值落在 `bg-layer-2` 或 `bg-layer-3` 上的那些表面 token，而这一档正是 l1/l2 之分所编码的层级差。最初的做法是从已经做了重新绑定的样式表反向推导，那是不成立的：这样得到的集合只能确认别人已经记得的部分，而尚无人重新绑定的表面——恰恰就是这项检查存在的理由——会把自己定义成「非抬升」。`--dsw-specific-tip` 证明了这一点：它解析到与菜单表面相同的那一档，待办面板在它上面滚动却没有重新绑定，而推导式的检查依然是绿的。
 
@@ -42,7 +42,7 @@ Status: implemented
 
 **把这两个属性绑定在 `html` 上。** 这是文档级皮肤最自然的落点，而它的失败是可测量的：规则挂在 `html` 上时，chromium 中滚动容器计算出的 `scrollbar-color` 为 `auto`，因为别名 token 在那个作用域内不存在。
 
-**只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定契约——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
+**只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定约定——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
 
 **不加 `@supports` 门禁，无条件同时声明标准属性与伪元素。** 这正是本次变更最初提交的形态，被评审发现。在 chromium 中于带 `scrollbar-gutter: stable`（使条带可观测）的探针元素上实测：单独一条 8px 的 `::-webkit-scrollbar` 预留出 30px 条带（样式表指定的宽度加上浏览器自带的按钮），而给同一元素加上 `scrollbar-width: thin` 后降到 `thin` 所预留的 10px——说明伪元素规则是被丢弃，而不是被合并。全部 `::-webkit-scrollbar-thumb:hover` 规则随之失效，因此两个 hover token 与四处抬升表面的 hover 重新绑定，在多数用户实际使用的引擎上都是死代码。
 
@@ -57,7 +57,7 @@ Status: implemented
 - 客户端的每个滚动容器都绘制带主题的滑块：亮色基础表面为 `rgb(229, 229, 229)`，暗色基础表面为 `rgb(60, 60, 61)`，重新绑定到 l2 的暗色抬升表面为 `rgb(84, 85, 87)`。侧边栏内的滚动区域经由同一组间接变量，只在指针到达时才绘制滑块。
 - 两种渲染分别指定，因此改动滑块的几何或 hover 行为需要改两处：一处在 `scrollbar-width`／`scrollbar-color`，一处在伪元素。让两者都经由这组间接变量，把这份重复限制在 Firefox 与 WebKit 不共用的那些属性上。
 - hover token（`--dsw-alias-scrollbar-hover-l1`／`-l2`）只在伪元素路径上渲染。Firefox 通过 `scrollbar-color` 只表述一个滑块颜色，其 hover 表现由引擎自行推导，因此对 hover 颜色的设计改动在 Chromium 与 Safari 上可见，在 Firefox 上不可见。这是 `scrollbar-color` 本身的限制，不是这张样式表的限制。
-- `body *` 匹配所有元素，涉及的两个属性其效果本就被浏览器限制在实际会滚动的元素上。代价是一个覆盖面很宽的选择器；另一种选择是一个不生效的重新绑定契约。
+- `body *` 匹配所有元素，涉及的两个属性其效果本就被浏览器限制在实际会滚动的元素上。代价是一个覆盖面很宽的选择器；另一种选择是一个不生效的重新绑定约定。
 - 工作区列表在任何列表长度下都永久少了预留空位那一条宽度。这正是该修复换来的代价：以稳定的行几何，换掉只在列表较短时才可读的时间戳。
 - 调色板中没有轨道 token，因此日后若设计需要不透明轨道，要新增一个别名 token，而不是在这张样式表里写字面颜色。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
index 967a0ebcf4..1868a4ba02 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-28-web-agent-runtime-context.md
 2026-07-28-web-agent-runtime-context.md: 6c2bb8faf0db56d2a29b47726ab295c3501cce2d
-2026-07-28-web-agent-runtime-context.zh.md: 09cbbdeabc244c265381b1ad67c3629b4c0763f5
+2026-07-28-web-agent-runtime-context.zh.md: ced6e767fd7463edae43b67025f35f77a631f150
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
index 09cbbdeabc..ced6e767fd 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
@@ -20,13 +20,13 @@ Web 运行时单元测试会固定启用和禁用 `surfaceContext` 时的行为
 
 ## 考虑过的替代方案
 
-**每次提示词都发送 URL、DOM 或截图。** 本次故障只需要稳定的产品定位；当前根 URL 无法标识所选组件，消息契约中也不存在视觉捕获内容。添加动态页面状态需要另行设计可记录的模型输入，不属于本次修复的隐含范围。
+**每次提示词都发送 URL、DOM 或截图。** 本次故障只需要稳定的产品定位；当前根 URL 无法标识所选组件，消息约定中也不存在视觉捕获内容。添加动态页面状态需要另行设计可记录的模型输入，不属于本次修复的隐含范围。
 
 **要求会话 Workspace 必须是 harness checkout。** Workspace cwd 是用户任务的目标，可以合理地指向空项目或其他仓库。将其与应用源码位置混为一谈会破坏这一边界，并且仍无法消除已安装版本或外部启动会话中的歧义。
 
 **把 Web 文案放入全局 harness 身份。** `dsh-system-prompt` 还服务于 TUI、ACP、SDK 和不在浏览器中运行的自定义部署。该界面事实应由组装 Web 应用负责。
 
-**为所有 CLI 界面修改现有源码位置提示词段。** TUI 也复用源码位置提示词段，而该段只陈述 checkout 事实。单独保留 Web 界面定位可以维持这份可复用契约，避免错误地告诉无头或终端 agent 它们正处于浏览器中。
+**为所有 CLI 界面修改现有源码位置提示词段。** TUI 也复用源码位置提示词段，而该段只陈述 checkout 事实。单独保留 Web 界面定位可以维持这份可复用约定，避免错误地告诉无头或终端 agent 它们正处于浏览器中。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
index 0e8b50db1a..c119ecf984 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-28-web-gui-feedback-loop.md
 2026-07-28-web-gui-feedback-loop.md: aa488e1df087722c072d98c67d47cdf63a42f6b8
-2026-07-28-web-gui-feedback-loop.zh.md: d9de988e5a2cc57794ff628b65eb050dee610747
+2026-07-28-web-gui-feedback-loop.zh.md: 9b6954092b737920ed18bc412037e917512e40dc
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
index d9de988e5a..9b6954092b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
@@ -14,15 +14,15 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 常规 `dsh web` 组合会挂载 Web 组合包的 `web-runtime` 插件，由它发布一个规范的回环 URL 及其实际运行时模式，同时将二者作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 和 `DSH_WEB_MODE=production|development` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。拥有完整提示词的 profile 会把该配置行的 `surfaceContext` 设为 false，并且不会收到该提示词段和这些受管变量中的任何一个；Web 启动器也会使用同一项设置来抑制其源码 checkout 提示词段。
 
-按模式区分的提示词让 agent 而非用户负责隐藏的启动契约。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
+按模式区分的提示词让 agent 而非用户负责隐藏的启动约定。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
 
 `apps/web` 开发脚本和 Vite 配置都会在打开端口前拒绝服务模式。诊断信息会指出 `apps/web` 只是一个仅供构建的外壳，说明只有 `dsh web` 才会注入 `window.__DSH_BOOT__`，并给出生产入口与 HMR 入口路径。Vite 构建模式保持不变。
 
-静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务契约负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。
+静态产物发生变化时，不需要仅为此重启或替换服务器。宿主会在每次请求时读取 `index.html` 和静态资源，客户端 bundle 也会从当前文件提供，并设置 `no-cache`；因此，重新构建相关外壳与插件 bundle 后，刷新现有 URL 就是验收路径。启动另一个服务器只能证明另一个服务器可用。如果用户明确要求再启动一个长期运行的服务器，则现有受管后台任务约定负责其生命周期和完成通知；shell `&` 不能替代这套生命周期机制。
 
 ## 验证
 
-无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI 冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发契约。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
+无密钥的 fresh-round-trip 浏览器场景会启动已交付的生产 Web 组合，驱动真实的回放会话，对包含 URL 和模式的系统提示词前缀生成快照，并调用组装后的 bash 工具，证明 `$DSH_WEB_URL` 和 `$DSH_WEB_MODE` 与实际绑定的运行时一致。真实 CLI 冒烟测试会启动 `dsh web --dev` 并捕获模型提供方请求，从而固定完整的双命令开发约定。`dev:web` watcher 测试会在源码发生变化后重新构建隔离的客户端 bundle；浏览器 HMR 场景会启动 `dsh web --dev`，修改生产初始 roster 中的 bundle，并在页面 identity 不变的情况下观察新 DOM。真实 Vite 子进程测试要求服务模式在给出改用完整宿主的纠正信息后自然退出，并通过插桩 `Server.listen()` 证明它从未被调用。真实 loader Web 服务器测试会在进程完成绑定后改写静态资源，并证明同一端口返回新的字节。这些断言检查提示词状态、进程退出状态、shell 输出、DOM identity 和 HTTP 字节，而不是 agent 的成功声明。
 
 ## 考虑过的替代方案
 
@@ -36,4 +36,4 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 ## 影响
 
-常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式契约会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
+常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式约定会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
index cbc9924c07..69359852c2 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-29-human-transcript-append-origin.md
 2026-07-29-human-transcript-append-origin.md: 9804d3d8d67a4ad00c3d395c2081fd47e03c254a
-2026-07-29-human-transcript-append-origin.zh.md: 909f0756dd29c9deddb840a188eb19a773f92d29
+2026-07-29-human-transcript-append-origin.zh.md: 030be076bec9c64ffc97957bbc0fc2b6084d2030
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
index 909f0756dd..030be076be 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 终端从追加来源的 surface 事件回放记录，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且两条路径都按同一个标记对 surface 事件分类，因此实时到达的压缩与恢复后回放同一份日志会产生相同的记录。只有回放会重新推导 `tool/call` 的配对关系：调用事件自身不携带标记，其归属继承自公布它的 `assistant/message`，而实时监听器必然刚刚渲染过后者。
 
-检查点通过压缩接缝自身的契约来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
+检查点通过压缩接缝自身的约定来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
 
 `session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。
 
@@ -30,7 +30,7 @@ Status: implemented
 
 ## Alternatives considered
 
-**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的契约，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。接缝已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
+**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的约定，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。接缝已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
 
 **继续把检查点渲染为注入上下文卡片。** 被否决：带框的检查点是为模型撰写的指令信封，不是人类对话内容。展示它却隐藏它替换掉的历史，正好颠倒了读者的需要。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
index f314df3e08..96491ff288 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-29-web-details-session-lifecycle.md
 2026-07-29-web-details-session-lifecycle.md: 41b89fc059a02e56f53b27e5a5b48fb9488b93d7
-2026-07-29-web-details-session-lifecycle.zh.md: 82fb5e0c2608cccbb786a21971a74958417b4f10
+2026-07-29-web-details-session-lifecycle.zh.md: b6d7ecdf19382b4742dad6e032be930ae10c5f1e
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
index 82fb5e0c26..b6d7ecdf19 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 **在 New Session 点击处理器中关闭详情栏。** 之所以否决：未选中表面没有会话作用域的详情，不得修改几何信息。详情栏是否关闭，应由随后对两个已定义会话 owner 的比较决定。
 
-**按会话持久化面板几何信息。** 之所以否决：产品契约需要移除陈旧上下文，而不是新增一张保存各宽度的映射。按会话保存几何信息还会在用户返回时重新打开详情栏，与选定的离开即关闭行为相悖。
+**按会话持久化面板几何信息。** 之所以否决：产品约定需要移除陈旧上下文，而不是新增一张保存各宽度的映射。按会话保存几何信息还会在用户返回时重新打开详情栏，与选定的离开即关闭行为相悖。
 
 **在会话基线就绪后保留持久化布局。** 之所以否决：这会仅为验证陈旧的查看状态，在呈现组件中重复实现启动生命周期。瞬时默认值无需就绪标志即可使重新加载具有确定性。
 
@@ -26,4 +26,4 @@ Status: implemented
 
 ## 后果
 
-详情栏在启动时保持关闭，首次会话物化时亦然。显式打开操作会使用契约默认宽度。切换到不同会话会忘记拖动后的详情宽度，因为关闭操作会写入零值，重新打开时则使用该默认值。未选中状态会将轨道的渲染宽度派生为零，同时保持首选几何信息不变；经由这些状态返回同一会话时，会恢复其宽度。重新加载会忘记侧边栏几何信息，并使详情栏恢复关闭状态。布局行为测试覆盖初始默认值、首次物化、直接及经 hero 中转的会话切换、返回同一会话，以及不存在布局存储的情况；无密钥浏览器 e2e 则通过已交付的组合驱动相同的 owner 过渡，同时检查完整网格轨道和浏览器错误。
+详情栏在启动时保持关闭，首次会话物化时亦然。显式打开操作会使用约定默认宽度。切换到不同会话会忘记拖动后的详情宽度，因为关闭操作会写入零值，重新打开时则使用该默认值。未选中状态会将轨道的渲染宽度派生为零，同时保持首选几何信息不变；经由这些状态返回同一会话时，会恢复其宽度。重新加载会忘记侧边栏几何信息，并使详情栏恢复关闭状态。布局行为测试覆盖初始默认值、首次物化、直接及经 hero 中转的会话切换、返回同一会话，以及不存在布局存储的情况；无密钥浏览器 e2e 则通过已交付的组合驱动相同的 owner 过渡，同时检查完整网格轨道和浏览器错误。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
index fa83836e46..3393051e53 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-30-composer-context-stack-order.md
 2026-07-30-composer-context-stack-order.md: 150225ce27fa8459703170622cef754b7694e2fc
-2026-07-30-composer-context-stack-order.zh.md: f13ffc3c1136707a86ba5636a5b69304a132df01
+2026-07-30-composer-context-stack-order.zh.md: 12704a76db35c32590f75ecebcfd99116422afe6
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
index f13ffc3c11..12704a76db 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-composer-context-stack-order.zh.md
@@ -10,11 +10,11 @@ Goal、Todo 与 Queue 独立注册到同一个 `conversation.input.dock` 列表
 
 ## 决策
 
-[Todo 优先的对齐决策](2026-08-02-todo-first-composer-context-order.md)规定当前的升序排列。本记录保留围绕该顺序的堆栈契约：数值间隔使未来条目可以声明预期位置，不必依赖插件激活顺序；composer bar 位于列表之后。
+[Todo 优先的对齐决策](2026-08-02-todo-first-composer-context-order.md)规定当前的升序排列。本记录保留围绕该顺序的堆栈约定：数值间隔使未来条目可以声明预期位置，不必依赖插件激活顺序；composer bar 位于列表之后。
 
 `ConversationRoot` 负责独立上下文卡片之间的 6px 间距。Goal 是一张独立的 752×36px 卡片，折叠后的 Todo 是一张独立的 752×44px 卡片。Queue 是末端 dock 条目：其 776px 包装层包含相同的 752px 面板列，并减去共享间距与具名的 5px 布局重叠量，因此后渲染的 composer 卡片只覆盖 Queue 边缘。空条目渲染为 null，不占用间距。
 
-顺序与重叠是两项独立契约。注册顺序定义语义层级，stack 上的 CSS 变量定义共享几何。系统不能仅因 Queue 是最后一个可见条目，就推断它可以与 composer 重叠，因为没有 Queue 时，Goal 或 Todo 可能成为最后一个可见上下文卡片，而它们必须与 composer 保持间隔。
+顺序与重叠是两项独立约定。注册顺序定义语义层级，stack 上的 CSS 变量定义共享几何。系统不能仅因 Queue 是最后一个可见条目，就推断它可以与 composer 重叠，因为没有 Queue 时，Goal 或 Todo 可能成为最后一个可见上下文卡片，而它们必须与 composer 保持间隔。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index cede7ea5d9..17c4315966 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-30-web-transcript-log-ordered-projection.md
 2026-07-30-web-transcript-log-ordered-projection.md: 3b7aaeb1178ff79e38a1b9646a9dc78efaeae48b
-2026-07-30-web-transcript-log-ordered-projection.zh.md: acd198b6d3f3c5d57e233e09ee66f5d151e4f8f1
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 024d7dba7db7f06a684f5656abf7421e65cd4536
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index acd198b6d3..024d7dba7d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -53,15 +53,15 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 **一条纯形状规则**——任何 replacement `user/message` 都是压缩。已拒绝：它今天正确只因为压缩是 replacement `user/message` 的唯一生产者，一旦这点改变便无任何机制能捕获。那个 pin 测试只花一个文件，就精确消除了这一风险。
 
-**在宿主侧给检查点打标**，经投影或线协议。已拒绝：这最贴合“经 cordis 服务协作”的规则，但客户端今天折叠的是原始 `SessionEvent`，因此这意味着一次线协议契约变更——为一个纯谓词付出的代价不成比例。
+**在宿主侧给检查点打标**，经投影或线协议。已拒绝：这最贴合“经 cordis 服务协作”的规则，但客户端今天折叠的是原始 `SessionEvent`，因此这意味着一次线协议约定变更——为一个纯谓词付出的代价不成比例。
 
 **把冻结节点的归属移进适配器**（`nodes(extraNodes)`），像那个未合并分支所做的那样。已拒绝：被打断的节点来自 `Session` 已经在窗口上运行的 `turn/end` 清扫，而在按 seq 单调的记录之上，简单形态就是正确的——适配器返回节点，会话按 seq 归并冻结节点。加宽适配器签名什么也换不到，还会把清扫与它的产物拆开。
 
-**把 `foldDegraded` 留作一个防御性标志。** 已拒绝：它描述的是一个已不再运行的 fold 的特定失败。一个消费方无法据以行动、只能通过 `console.error` 到达的标志，是一份虚假契约。
+**把 `foldDegraded` 留作一个防御性标志。** 已拒绝：它描述的是一个已不再运行的 fold 的特定失败。一个消费方无法据以行动、只能通过 `console.error` 到达的标志，是一份虚假约定。
 
 **把最近的 `/compact` 行与下一个检查点配对。** 已拒绝：两者之间可能落入上下文注入，并发或格式异常的生命周期记录也必须降级而不误取其他检查点。命令结果则指明权威摘要事件；引用存在歧义时不配对任何内容。
 
-**解析英文结算文本中的条目数量和 token 数量。** 已拒绝：处理器文案是呈现文本，而非稳定的数据契约。标记读取本已持有这两个值的结构化 `compact/summary` 载荷。
+**解析英文结算文本中的条目数量和 token 数量。** 已拒绝：处理器文案是呈现文本，而非稳定的数据约定。标记读取本已持有这两个值的结构化 `compact/summary` 载荷。
 
 ## Consequences
 
@@ -69,7 +69,7 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 `ConversationNode` 增加第八个分支，因此每个穷尽消费方都多一个分支：`MessageItem` 通过新的 `CompactionItem` 渲染标记，trajectory 布局加宽它的“无单元格”分支，使标记不贡献单元格但仍推进耗时游标。
 
-性能契约未变，且现在更易表述：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用——因此分片风暴零成本、`nodes()` 甚至不会重算——未变化的节点保持其对象标识。窗口仍随会话长度而非随 surface 增长，这正是本修复存在所要做的交换；一次压缩过去恰好为压缩所服务的长会话限制了投影规模。
+性能约定未变，且现在更易表述：一次追加物化一个节点，不改变任何节点的事件保持上一次的数组引用——因此分片风暴零成本、`nodes()` 甚至不会重算——未变化的节点保持其对象标识。窗口仍随会话长度而非随 surface 增长，这正是本修复存在所要做的交换；一次压缩过去恰好为压缩所服务的长会话限制了投影规模。
 
 Web e2e 场景现在围绕它录制的那一轮上的压缩事务播种一次真实的手动命令生命周期，因此 aria 基准经真实宿主与真实浏览器钉住完整行为：录制的提问与完整工具输出仍在屏幕上，其后恰好一条 `compact` 行报告规模，展开后会显示确切摘要。录制本身未被触碰、保持模型真实——回放从录制自身的 surface 派生出手动压缩。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
index 7d68e52c82..4701560508 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-english-compaction-checkpoints.md
 2026-07-31-english-compaction-checkpoints.md: dc95ed187a6ba5b86800f06ebefb2776995f9421
-2026-07-31-english-compaction-checkpoints.zh.md: 7cd4179430ed775f3807af5a02e81838e495c81e
+2026-07-31-english-compaction-checkpoints.zh.md: 54247dcfeffc8a0d94fd64b0bbd5cb2dee9b669f
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
index 7cd4179430..54247dcfef 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-english-compaction-checkpoints.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 - **让回放的对话决定检查点语言**——不采纳：检查点是持久的提示词前缀，保留短暂的对话文体可能在后续压缩中放大这种影响。
 - **约束对话模型的语言**——不采纳：该策略针对内部检查点，而不是用户可见的对话；对整个对话施加规则会不必要地改变正常交互。
 - **要求仅输出 ASCII**——不采纳：ASCII 是字符集约束，而非工程文体约束，并会不必要地扭曲合法的字面量和技术材料。
-- **在末尾追加一句独立的仅限英语要求**——不采纳：在指令开头的输出契约中说明该要求更简洁，也直接将其与所请求的检查点绑定。
+- **在末尾追加一句独立的仅限英语要求**——不采纳：在指令开头的输出约定中说明该要求更简洁，也直接将其与所请求的检查点绑定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
index fda3830670..f090dceaaf 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-fail-loud-releases-the-terminal.md
 2026-07-31-fail-loud-releases-the-terminal.md: 5fe812e5fe64a1fab8ba9808d87f3581b6f5b206
-2026-07-31-fail-loud-releases-the-terminal.zh.md: 64459614dc3376a1c773de72cd36aa455894a03c
+2026-07-31-fail-loud-releases-the-terminal.zh.md: 3e4d2ce40c2196919aace410d86a2ea26b6001f8
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
index 64459614dc..3e4d2ce40c 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
@@ -52,7 +52,7 @@ Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动
 
 ## Testing
 
-`packages/boot/app-boot/tests/app-boot.spec.ts` 覆盖 release 契约：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
+`packages/boot/app-boot/tests/app-boot.spec.ts` 覆盖 release 约定：退出提交前会等待该回调；回调 rejection 时仍退出 1；永不结算的回调会在 `FAIL_LOUD_RELEASE_TIMEOUT_MS` 后退出；以及一连串 rejection 只报告第一个，同时 release 仍能跑完。
 
 这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态被残留的 [HMR 初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
index c4a5595fea..9ca3df22a0 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-fork-anchor-floors-to-event-seq.md
 2026-07-31-fork-anchor-floors-to-event-seq.md: 2cc8d66942442aca69c930be880cc41d56bced13
-2026-07-31-fork-anchor-floors-to-event-seq.zh.md: 9f443f3d5165c01c6585d33bd6a37e90e9b3bf95
+2026-07-31-fork-anchor-floors-to-event-seq.zh.md: 75fc1885f344e88c9ded575bc4aea58562e55673
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
index 9f443f3d51..75fc1885f3 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md
@@ -18,11 +18,11 @@ host 的切分规则从来不是障碍。被中止的轮次会记录一条 reaso
 
 向下取整落在锚点自身所在的轮次内，不会回退：每一轮都以 `turn/start` 开头，所以 `turnEnd.seq - 1` 不可能是上一轮的 `turn/end`。host 随后按「首个位于锚点或其之后的 `turn/end`」收口，命中的正是读者点击的那一轮，与消息级 fork 按钮在已完成轮次上一贯承诺的整轮语义一致。
 
-apiproxy 的 fork 用例固定了 host 这一侧的契约：落在被中止轮次内的取整锚点会切穿该轮，并把它种进子会话。
+apiproxy 的 fork 用例固定了 host 这一侧的约定：落在被中止轮次内的取整锚点会切穿该轮，并把它种进子会话。
 
 ## 备选方案
 
-**让 wire 接受分数 `atSeq`。** 否决：host 契约要的是事件 seq，而不是连续坐标上的某个位置；分数形式只是某一个客户端的渲染约定，一旦放行，`atSeq` 会成为所有携带 seq 的载荷中唯一容忍非整数的字段。
+**让 wire 接受分数 `atSeq`。** 否决：host 约定要的是事件 seq，而不是连续坐标上的某个位置；分数形式只是某一个客户端的渲染约定，一旦放行，`atSeq` 会成为所有携带 seq 的载荷中唯一容忍非整数的字段。
 
 **在已中断的消息上隐藏 fork 按钮。** 否决：从读者主动叫停的那一轮分叉，恰恰是最需要 fork 的场景之一，而 host 侧这个能力一直是好的。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
index 3df507fc7c..7832e30b52 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-resume-selector-batch-projection.md
 2026-07-31-resume-selector-batch-projection.md: 39146527f13b20813bb6f5d5f1349ecab5724662
-2026-07-31-resume-selector-batch-projection.zh.md: 3f824a3063849306e5c1c21699f6a19eefcfefe5
+2026-07-31-resume-selector-batch-projection.zh.md: 19bea7211cc61fa7db80370ee3092e5c88bf931b
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
index 3f824a3063..19bea7211c 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
@@ -26,9 +26,9 @@ session-query 与 session-persistence 的任何表面都未改变。随附的 TU
 
 **只修复 `SessionCorpus.load()` 内部的 O(N²) 列表查询。** 作为主要修复被否决：在大日志上，按候选行执行的完整解压、回放验证和三重克隆才是主要开销。`load()` 中的冗余预列表查询仍是一个候选清理项，但涉及错误语义。
 
-**通过 `listSnapshots`/`SessionRecord` 暴露最后修改时间。** 从 seam 角度最干净，但要触碰持久化契约、两个后端和查询记录形状，而 TUI 已能用 `locate()` 加一次 stat 得到同样的信息。若出现第二个需要元数据活动时间的消费者再引入。
+**通过 `listSnapshots`/`SessionRecord` 暴露最后修改时间。** 从 seam 角度最干净，但要触碰持久化约定、两个后端和查询记录形状，而 TUI 已能用 `locate()` 加一次 stat 得到同样的信息。若出现第二个需要元数据活动时间的消费者再引入。
 
-**专门的持久化标题索引或 TUI 本地标题缓存。** 否决：session-projection 缓存本身就是自有的持久 checkpoint 系统，并已带失效契约（`stateVersion`、身份绑定、日志收缩锚定）；挂载它优于再造一套并行缓存。
+**专门的持久化标题索引或 TUI 本地标题缓存。** 否决：session-projection 缓存本身就是自有的持久 checkpoint 系统，并已带失效约定（`stateVersion`、身份绑定、日志收缩锚定）；挂载它优于再造一套并行缓存。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
index c78049cc8d..a9eade53c1 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-web-stop-preserves-queue.md
 2026-07-31-web-stop-preserves-queue.md: b8bba45009c126495a8b03ee36d6eb2cccac9a93
-2026-07-31-web-stop-preserves-queue.zh.md: 0e1fffae8819bea81b91fae10c76dbadc78474fe
+2026-07-31-web-stop-preserves-queue.zh.md: af9c114fd06452e58322f2554a0f2ccd861c81c9
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
index 0e1fffae88..af9c114fd0 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md
@@ -16,7 +16,7 @@ Web 停止按钮调用 `session.cancel`，后者映射到广义 `agent.cancel({
 
 AgentLoop 不会启动并发的替代轮次。它会关闭并 flush 被中断的轮次，达到取消的完全停稳，然后通过现有 FIFO 驱动器认领下一个可唤醒的 queued 入队项。该认领会发出 `agent/inbox/dequeue`，因此 Host 的权威 `session/queue` 快照会退役已认领行，并使剩余队尾保持可见。浏览器既不重发，也不提升任何行。忽略取消的工作会延迟这一交接，直到该工作结算。
 
-该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认契约仍为广义取消，ACP 和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。
+该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认约定仍为广义取消，ACP 和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
index 39bf79e628..090d230891 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
 2026-08-01-ask-user-delegated-caller-guard.md: 0350a7383f7ace6ecd742c98db18f8b977720cf9
-2026-08-01-ask-user-delegated-caller-guard.zh.md: 9c19722feb4586e07845fd20279574301267542d
+2026-08-01-ask-user-delegated-caller-guard.zh.md: afabe4fb742dac2696b88bf64515aba68424b4de
diff --git a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
index 9c19722feb..afabe4fb74 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 以运行时所有权为权限依据。携带谱系的会话在无所有者的情况下恢复时就是运行时根，可以提问；存活子级即使持久化 `delegationDepth` 为零，仍无资格提问。不带 agent 的程序化调用继续沿用现有提供方路径。
 
-共享失败文本与具体消费方无关，并给出可执行指引：子级把尚未解决的问题或决策写入最终结果。委托契约本就会把该结果传给父级，父级可据此决定是否询问人类。服务和子级都不会宣称存在实际上并不存在的向上消息传递或回答转发能力。
+共享失败文本与具体消费方无关，并给出可执行指引：子级把尚未解决的问题或决策写入最终结果。委托约定本就会把该结果传给父级，父级可据此决定是否询问人类。服务和子级都不会宣称存在实际上并不存在的向上消息传递或回答转发能力。
 
 该安全边界与浏览器的 composer 选举相互独立。提议的[语义 composer 阶段](../../proposed/architecture/2026-08-08-semantic-composer-chain-phases.md)解决已有待处理交互与只读 subagent 界面的排序方式；它不会削弱此运行时守卫。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
index c8784f5991..c37b234616 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.md
 2026-08-02-goal-round-wrapup-message.md: c6bc3d5912b0789efde55880c2be892e98e34a5b
-2026-08-02-goal-round-wrapup-message.zh.md: 0a504b4dcc61feb932775b3d9ffd8424f3b0597d
+2026-08-02-goal-round-wrapup-message.zh.md: f223516e1255f2dafe026a48d1faafa838af6cb8
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
index 0a504b4dcc..f223516e12 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md
@@ -18,13 +18,13 @@ Goal Round 的 `complete` 或 `blocked` 成功不再调用 `concludeTurn()`。
 
 ## 验证
 
-`tool-goal` 包测试钉住两个终态 action 注入的上下文（source、标签、objective、禁止再调工具条款）与不存在的 `concludesTurn`，以及人类直接 pause 与 complete 的不注入路径，文件覆盖率 100%。`llm-replay` 单元测试钉住占位符契约：最后一次匹配取胜的捕获、无捕获组时整体匹配回退，以及未匹配、非法、未闭合模式的明确报错。新增 keyless ACP 快照 `goal-wrapup` 驱动成品应用走完 create → 第一轮 → 自主 complete，并在持久会话日志与 ACP stdout 流中同时断言 plugin 来源的收尾注入、同轮内的收尾 assistant 消息与 `completed` 轮次结束。
+`tool-goal` 包测试钉住两个终态 action 注入的上下文（source、标签、objective、禁止再调工具条款）与不存在的 `concludesTurn`，以及人类直接 pause 与 complete 的不注入路径，文件覆盖率 100%。`llm-replay` 单元测试钉住占位符约定：最后一次匹配取胜的捕获、无捕获组时整体匹配回退，以及未匹配、非法、未闭合模式的明确报错。新增 keyless ACP 快照 `goal-wrapup` 驱动成品应用走完 create → 第一轮 → 自主 complete，并在持久会话日志与 ACP stdout 流中同时断言 plugin 来源的收尾注入、同轮内的收尾 assistant 消息与 `completed` 轮次结束。
 
 ## 曾考虑的替代方案
 
 - **在 `update_goal` 的 UI 卡片上展示完成文本** — 拒绝：`complete` 如今不携带任何自由文本；新增 `summary` 参数会让面向用户的汇报走工具参数通道，而且依然砍掉了模型在结果之后的自然发言。
 - **保留 `concludeTurn()` 并新增“再多一步纯文本”的 loop 原语** — 拒绝：为常规停止路径已经能提供的行为（只要没有结果终结轮次）增加新的 `agent-loop` 机制。
-- **把指令写进工具结果内容** — 拒绝：goal 工具的规范输出是被程序化消费的紧凑 JSON；在其中混入散文指令会把模型侧契约和工具的可回放值搅在一起。
+- **把指令写进工具结果内容** — 拒绝：goal 工具的规范输出是被程序化消费的紧凑 JSON；在其中混入散文指令会把模型侧约定和工具的可回放值搅在一起。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
index eeac8a251c..c68279a2b4 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.md
 2026-08-02-todo-first-composer-context-order.md: 26962426c763c6911fc61acab09cdb96725922b1
-2026-08-02-todo-first-composer-context-order.zh.md: a81401ffeb8df5855b584a5727e24067d9fb1e70
+2026-08-02-todo-first-composer-context-order.zh.md: 2bd09a95832b22afc919a6f2d18bef94d4209c40
diff --git a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
index a81401ffeb..2bd09a9583 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-02-todo-first-composer-context-order.zh.md
@@ -14,7 +14,7 @@ composer 上下文堆栈将 Goal 渲染在 Todo 之前，但 Harness 设计稿
 
 Todo、Goal 与可见的 Queue 面板共用 800px composer 宽度上限内的 752px 卡片列。Queue 保留 776px 包装层，并在两侧各留 12px 透明内缩，因为该包装层负责与 composer 重叠。Todo 是独立卡片，而非包装层，因此其响应式宽度和最大宽度都会直接扣除两层内缩。Goal 使用相同的响应式卡片列，并将内层横条的宽度上限设为 752px，从而在低于桌面宽度上限时也保持边缘对齐。
 
-[composer 堆栈契约](2026-07-30-composer-context-stack-order.md)继续规定卡片间距，以及仅限 Queue 与 composer 重叠。本决策只取代该记录中 Goal 优先的顺序。
+[composer 堆栈约定](2026-07-30-composer-context-stack-order.md)继续规定卡片间距，以及仅限 Queue 与 composer 重叠。本决策只取代该记录中 Goal 优先的顺序。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
index 36c7895ac2..524915cee7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
 2026-08-03-cli-signal-shutdown-escalation.md: c8aac6e2be927bd1f4a445c00e0aaa870b10a465
-2026-08-03-cli-signal-shutdown-escalation.zh.md: 66fe7062ea35a6cc91dbdd6644088cb086a15439
+2026-08-03-cli-signal-shutdown-escalation.zh.md: bfe0b9c28e10b055888ba4850d1a1feacc5f8390
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
index 66fe7062ea..bfe0b9c28e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md
@@ -39,7 +39,7 @@ headless 对完成的轮次仍以 0 退出，对其他轮次结束原因或 API
 
 ## 后果
 
-健康的退出流程仍会对整棵 Cordis 插件树执行 dispose。已知的遥测等待最多会在 3 秒后解除；其他退出流程卡死时，如无进一步输入，最多等待 5 秒，再次收到信号则立即结束进程。强制退出或受截止时间限制的退出可能中断遥测导出或尚未完成的清理工作；只有优雅关闭契约已经失败，或用户明确要求强制退出时，才会有意接受这一结果。
+健康的退出流程仍会对整棵 Cordis 插件树执行 dispose。已知的遥测等待最多会在 3 秒后解除；其他退出流程卡死时，如无进一步输入，最多等待 5 秒，再次收到信号则立即结束进程。强制退出或受截止时间限制的退出可能中断遥测导出或尚未完成的清理工作；只有优雅关闭约定已经失败，或用户明确要求强制退出时，才会有意接受这一结果。
 
 该控制器属于启动器基础设施，而不是 Cordis 插件：它不会声称 dispose 已经完成，也不会削弱普通 disposer 必须达到完全停稳状态的生命周期规则。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
index 51fbed7ba9..1ca6de64cd 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
 2026-08-03-hmr-initial-scan-boot-deadlock.md: 1a70fbafc74a1bf7024c675ddad82acefc995b72
-2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: 5f8d50c4c0103eb2209eafb89cf34233c4c1bc35
+2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: a023420182971a62f125808f777f877bafe3e9e2
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
index 5f8d50c4c0..a023420182 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
@@ -38,4 +38,4 @@
 
 ## 测试
 
-`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端契约：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/boot/app-boot/tests/config-reload.spec.ts` 与 `packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖。
+`apps/cli/tests/tui-keyless-smoke.e2e.ts` 中 `dsh` 无效 provider 的 PTY 用例钉住了端到端约定：以 1 退出、带标签的 `dsh: plugin tree failed to load:` 诊断指明 `$.providers`、以及证明整棵树已被释放的 bracketed-paste 复位序列。此修复之前，同一用例观察到的是无诊断的 exit 13。重载行为仍由 `packages/boot/app-boot/tests/config-reload.spec.ts` 与 `packages/boot/app-boot/tests/hmr-config.spec.ts` 覆盖。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
index 02ea7ca431..8aab23d8a2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
 2026-08-04-load-pre-react-loop-sessions.md: b7dcad1ff7fe0aa8239ac03f52b50dfa55417515
-2026-08-04-load-pre-react-loop-sessions.zh.md: 14c6dcc7b4da016ebef424a66fae0b96fb469cd4
+2026-08-04-load-pre-react-loop-sessions.zh.md: 9dc8666d301b3baf454079498bf3ad7e1f510c96
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
index 14c6dcc7b4..9dc8666d30 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
@@ -26,11 +26,11 @@ react-loop 简化在保持 `SESSION_FORMAT_VERSION` 为 0 的同时更改了持
 
 **将粗粒度中止记录归因于现有调用方。** 将其映射到 `user`、`parent` 或 `hook` 会虚构来源。专用的 `legacy` 原因既能保留停止分类，也不会产生虚假的审计事实。
 
-**重写已存储的 JSONL 和 SQLite 记录。** 重写会违反仅追加契约，并要求为读取兼容边界建立后端专用的原子迁移机制。
+**重写已存储的 JSONL 和 SQLite 记录。** 重写会违反仅追加约定，并要求为读取兼容边界建立后端专用的原子迁移机制。
 
 ## 后果
 
-以重构基线格式写入的会话可以通过当前 AgentLoop 恢复，并完整保留 steering 内容、轮次边界、错误事实和停止分类。共享协调器契约覆盖内存、JSONL 和 SQLite 的 `load`／`inspect`／`readFrom`，包括 SQLite 后缀回退；组装后的 JSONL agent 恢复用例会验证历史 transcript（文本记录）可见，同时两个新 inbox 列表都从空状态开始。
+以重构基线格式写入的会话可以通过当前 AgentLoop 恢复，并完整保留 steering 内容、轮次边界、错误事实和停止分类。共享协调器约定覆盖内存、JSONL 和 SQLite 的 `load`／`inspect`／`readFrom`，包括 SQLite 后缀回退；组装后的 JSONL agent 恢复用例会验证历史 transcript（文本记录）可见，同时两个新 inbox 列表都从空状态开始。
 
 此例外支持基线格式，不支持重构开发期间产生的中间格式。具体而言，它没有为更早的实验性 `agent/inbox/spliced` 载荷定义迁移。通过确切形状识别，当前格式外观相似但结构错误的记录仍会走拒绝路径，不会被猜测性地转换为有效记录。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
index a08d6323dd..874c0c0d34 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.md
 2026-08-06-onboarding-step-owned-takeover-chrome.md: 4b3bbbc03c4494359297ae6e54bcc9a74c387e80
-2026-08-06-onboarding-step-owned-takeover-chrome.zh.md: 548285d285939325a26df3b8d70c43fe952813a9
+2026-08-06-onboarding-step-owned-takeover-chrome.zh.md: ba4f503f7bc318fcb16f4413465a86609fa1bc61
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
index 548285d285..ba4f503f7b 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
@@ -14,13 +14,13 @@
 
 接管界面框架属于步骤，不属于外壳。新增零 cordis 原语 `OnboardingSurface`（ui-primitives）：渲染 portal 到 body 的浮层／遮罩／展示层——CSS 类名与几何从 `SettingsRoot.module.css` 逐字迁移——并在自身挂载生命周期内保持 `#root` 为 `inert`。两个步骤组件只把各自的**可见**分支包进该原语；既有的 `null` 分支由此在构造上不绘制、不阻塞任何内容，因为界面框架已是同一次渲染决策的一部分。
 
-`SettingsRoot` 的协调器原样保留（有序账本投影、每次挂载一个步骤、本地完成集合、`stepId`／`complete`／`openSection` currency），但对当选步骤裸渲染——不再有 portal、展示层和 inert 效果。`settings.onboarding` 的 slot 契约现在写明：注册方持有外层包裹，且在私有事实未决时必须渲染 `null`。
+`SettingsRoot` 的协调器原样保留（有序账本投影、每次挂载一个步骤、本地完成集合、`stepId`／`complete`／`openSection` currency），但对当选步骤裸渲染——不再有 portal、展示层和 inert 效果。`settings.onboarding` 的 slot 约定现在写明：注册方持有外层包裹，且在私有事实未决时必须渲染 `null`。
 
 ## 曾考虑的替代方案
 
 **条件注册（账本即有内容信号）。** 私有 join 解析出「需要介入」后才注册条目。架构上干净（在 commit point 发布），但改动更大：join 的加载必须从对话框上移到各插件的 apply，注册／销毁在两个包里都变成响应式接线。对本缺陷而言过重，否决。
 
-**把 `settings.onboarding` 改成 chain 并把完成集合外置为 store。** composer takeover 的版型；做过原型后回退。selector 只能判定 owner props，私有就绪事实仍然只能在组件内部解析——chain 买来的是当前两个步骤并不需要的路由通用性，代价却是跨三个包的契约变更。
+**把 `settings.onboarding` 改成 chain 并把完成集合外置为 store。** composer takeover 的版型；做过原型后回退。selector 只能判定 owner props，私有就绪事实仍然只能在组件内部解析——chain 买来的是当前两个步骤并不需要的路由通用性，代价却是跨三个包的约定变更。
 
 **在渲染点探测 slot 输出为空。** `renderSlot` 无条件返回 outlet 元素，owner 无法据步骤的 `null` 分支；探测已渲染 DOM 是否为空需要先提交再撤回的手法，其动态翻转会失去 paint 前的保证。
 
@@ -28,8 +28,8 @@
 
 步骤已挂载但尚未判定期间，应用保持可见且可交互：判定窗口内 `#root` 不再是 `inert`（此前是在不透明图层背后被置灰）。对真正未配置的用户，接管层比从前晚一个 join 往返出现——但一出现就带着内容，而不是先露出空白展示层再填充。
 
-未来若有步骤注册后不把可见内容包进 `OnboardingSurface`，会无遮罩地裸渲染在应用之上；slot 契约的 JSDoc 已把包裹写为注册方的义务。
+未来若有步骤注册后不把可见内容包进 `OnboardingSurface`，会无遮罩地裸渲染在应用之上；slot 约定的 JSDoc 已把包裹写为注册方的义务。
 
 ## 测试
 
-`packages/client/ui-primitives/tests/onboarding-surface.spec.tsx` 钉住原语行为：内容外的 body portal、遮罩／展示层类名存在、`#root` 的 `inert` 恰好持续挂载生命周期，以及无 `#root` 的组合。`packages/client/ui-settings/tests/settings-root.spec.tsx` 钉住反转后的外壳契约：已挂载步骤什么都不渲染时，无接管界面框架、无 inert。`apps/web/tests/onboarding-deepseek-config.e2e.ts` 新增本缺陷的整装回归钉：已配置世界刷新页面，同时在浏览器网络边界扣住所有 `settings.describe` 响应——把步骤的判定窗口从 loopback 下不可见拉宽到数百毫秒，这正是断言保持非空洞的关键——页内 8ms 采样器证明接管界面框架从未挂载、`#root` 从未变为 inert。该文件的既有场景与步骤 spec（`ui-settings-general`、`ui-models`）原样通过——样式表逐字迁移，遮罩选择器与几何钉子得以幸存。
+`packages/client/ui-primitives/tests/onboarding-surface.spec.tsx` 钉住原语行为：内容外的 body portal、遮罩／展示层类名存在、`#root` 的 `inert` 恰好持续挂载生命周期，以及无 `#root` 的组合。`packages/client/ui-settings/tests/settings-root.spec.tsx` 钉住反转后的外壳约定：已挂载步骤什么都不渲染时，无接管界面框架、无 inert。`apps/web/tests/onboarding-deepseek-config.e2e.ts` 新增本缺陷的整装回归钉：已配置世界刷新页面，同时在浏览器网络边界扣住所有 `settings.describe` 响应——把步骤的判定窗口从 loopback 下不可见拉宽到数百毫秒，这正是断言保持非空洞的关键——页内 8ms 采样器证明接管界面框架从未挂载、`#root` 从未变为 inert。该文件的既有场景与步骤 spec（`ui-settings-general`、`ui-models`）原样通过——样式表逐字迁移，遮罩选择器与几何钉子得以幸存。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
index de0b20d867..2d0579a4d1 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.md
 2026-08-06-provider-credential-lifecycle.md: c28788921e8f1b233b44e19b29ad4d4acaa25022
-2026-08-06-provider-credential-lifecycle.zh.md: 2ea3b21fb6ceb4fa38a0cad0daf47c3b6a98a664
+2026-08-06-provider-credential-lifecycle.zh.md: 2791baa7761b243cbdd34251d1dc11678b8a9a65
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
index 2ea3b21fb6..2791baa776 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md
@@ -16,7 +16,7 @@ Models 编辑器横跨互相独立的 settings 与凭据 RPC 领域。之前它
 
 ## 曾考虑的替代方案
 
-**添加跨领域事务 RPC。**settings 与凭据分属不同的主管服务与持久存储；引入新的 Host 事务会扩大公开 wire 面，而且仍需要补偿提供方特定的持久化失败。UI 检查点让当前的有序阶段变得可恢复，无需添加第四项配置契约。
+**添加跨领域事务 RPC。**settings 与凭据分属不同的主管服务与持久存储；引入新的 Host 事务会扩大公开 wire 面，而且仍需要补偿提供方特定的持久化失败。UI 检查点让当前的有序阶段变得可恢复，无需添加第四项配置约定。
 
 **删除被移除 profile 所指定的每一个凭据引用。**自定义引用可能被共享、由外部管理，或有意在 profile 反复增删时存留。与该页面派生目标精确相等，再加上已配置且可写的状态，是页面所能获得的最小范围证据；比这更弱的判定都有可能删除不属于它的凭据。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
index 1c861833cf..2982e05c65 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
 2026-08-06-reader-scroll-attribution-observed-top-ledger.md: 2dcd0178e4216d4d3e2edcd3bfcc05b63606c333
-2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: ffb03fdb68c9cb040e311077dd698b310a033fdd
+2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: 7a1142cdd793cfce46bfd3908ab28345701aec7a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
index ffb03fdb68..7a1142cdd7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md
@@ -12,13 +12,13 @@ ChatView 的贴底跟随此前只把滚轮／触控板手势识别为读者输
 
 读者输入不再依据设备来识别。ChatView 维护一份 observed-top ledger（`observedTopRef`）：即最近一次由主线程交付、或由组件自身写入的 `scrollTop`，并在每一个程序化写入点（贴底跟随、打开时恢复、前置锚定、尺寸变化跟随以及滚动交付本身）同步记录。滚动事件到达时，偏离 `min(ledger, floor)` 超过半像素的位置即为读者输入；落在 ledger 上的位置（迟到的程序化交付），或恰好落在收缩后底部上的位置（内容收缩后的浏览器钳制），则维持当前的所有权状态。此后所有权只经由读者输入、按既有阈值规则变化：位置距底部在 `FOLLOW_THRESHOLD` 以内则重新贴底，超出则释放跟随并显示「回到底部」。滚轮监听器及其 epoch 簿记已删除；组件只监听 `scroll`，因此滚轮、触控、滚动条、键盘以及未来任何输入来源都由同一条规则覆盖。
 
-## 契约变更：收缩与重新增长被合并的钳制
+## 约定变更：收缩与重新增长被合并的钳制
 
-如果一次收缩钳制的布局在同一次渲染更新内、赶在该钳制的滚动事件交付之前重新增长，那么这个事件在几何上与读者输入无法区分，因此它现在会被判读为读者并释放跟随（可经「回到底部」恢复）。现实中由 React 提交（commit）驱动的收缩与重新增长仍会被吸收：layout effect 中的跟随会在每次提交后重新贴底并重新记录 ledger，而仅收缩的钳制会恰好落在 `min(ledger, floor)` 上。只有在同一次更新内先收缩再重新增长的非 React 重排会被误归因。旧的滚轮模型在这种竞态情形下会保持跟随；单元测试契约已在同一变更中改写为只吸收纯收缩的保证。
+如果一次收缩钳制的布局在同一次渲染更新内、赶在该钳制的滚动事件交付之前重新增长，那么这个事件在几何上与读者输入无法区分，因此它现在会被判读为读者并释放跟随（可经「回到底部」恢复）。现实中由 React 提交（commit）驱动的收缩与重新增长仍会被吸收：layout effect 中的跟随会在每次提交后重新贴底并重新记录 ledger，而仅收缩的钳制会恰好落在 `min(ledger, floor)` 上。只有在同一次更新内先收缩再重新增长的非 React 重排会被误归因。旧的滚轮模型在这种竞态情形下会保持跟随；单元测试约定已在同一变更中改写为只吸收纯收缩的保证。
 
 ## 测试
 
-`packages/client/ui-conversation/tests/chat-view.spec.tsx` 中的单元测试直接钉住 ledger 契约：`readerScroll` 辅助函数交付一个组件从未写入过的位置，程序化交付落在 ledger 上，流收尾阶段的收缩钳制保持跟随。`apps/web/tests/chat-scroll-contract.e2e.ts` 中的两个场景扩展了[浏览器 e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)：在已停稳的 transcript 上做键盘翻页，以及对着按节奏推进的流式输出做一次触控式惯性快滑（momentum fling）；两者在仅认滚轮的实现下均为红、在 ledger 下均为绿。
+`packages/client/ui-conversation/tests/chat-view.spec.tsx` 中的单元测试直接钉住 ledger 约定：`readerScroll` 辅助函数交付一个组件从未写入过的位置，程序化交付落在 ledger 上，流收尾阶段的收缩钳制保持跟随。`apps/web/tests/chat-scroll-contract.e2e.ts` 中的两个场景扩展了[浏览器 e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)：在已停稳的 transcript 上做键盘翻页，以及对着按节奏推进的流式输出做一次触控式惯性快滑（momentum fling）；两者在仅认滚轮的实现下均为红、在 ledger 下均为绿。
 
 该车道的 Chromium 无法合成任何非滚轮的设备滚动，这限定了 e2e 能真实驱动的范围：触控来源的 `Input.synthesizeScrollGesture` 与手工构造的 `Input.dispatchTouchEvent` 序列都能交付 DOM 事件，却从不移动滚动容器（无头模式与 Xvfb 下的有头模式皆然）；`default` 手势来源合成的是滚轮事件；合成器滚动条则完全无视合成的鼠标输入，且只有移除 `--hide-scrollbars` 后才能看到滚动条槽。键盘是唯一可用的非滚轮原语，因此由它承担真实输入流水线的证明；快滑场景则把触控的特征（组件从未写入过的逐帧衰减位移）直接回放进滚动容器。
 
@@ -34,4 +34,4 @@ ChatView 的贴底跟随此前只把滚轮／触控板手势识别为读者输
 
 ## 后果
 
-每种读者输入现在都以同一方式拥有贴底跟随，而代码更少：滚轮监听器、它的 epoch 计数器以及输入前基线簿记均已移除，归因搭载在组件本就维护的状态之上。sticky-composer 笔记中的布局、滚轮链式处理与前置锚定决策原样保留，仍为权威；其窄范围的输入来源规则由本笔记取代。代价就是上文的契约变更：一次收缩与重新增长被合并的非 React 钳制现在会暂停跟随，直到读者回到底部或按下「回到底部」；以此换来流式输出期间触控、滚动条与键盘的正确性。e2e 车道获得的非滚轮覆盖仅限其浏览器能够合成的范围；若手势合成在未来某个 Chromium 版本中开始可用，可以在不改变所断言契约的前提下，把快滑模拟替换为真实的触控划动。
+每种读者输入现在都以同一方式拥有贴底跟随，而代码更少：滚轮监听器、它的 epoch 计数器以及输入前基线簿记均已移除，归因搭载在组件本就维护的状态之上。sticky-composer 笔记中的布局、滚轮链式处理与前置锚定决策原样保留，仍为权威；其窄范围的输入来源规则由本笔记取代。代价就是上文的约定变更：一次收缩与重新增长被合并的非 React 钳制现在会暂停跟随，直到读者回到底部或按下「回到底部」；以此换来流式输出期间触控、滚动条与键盘的正确性。e2e 车道获得的非滚轮覆盖仅限其浏览器能够合成的范围；若手势合成在未来某个 Chromium 版本中开始可用，可以在不改变所断言约定的前提下，把快滑模拟替换为真实的触控划动。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
index bb344c5afe..eb99fee949 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.md
 2026-08-06-token-surface-unpriced-replace-compatibility.md: 77b778fba695f560eb68af6da2f416e61ccff181
-2026-08-06-token-surface-unpriced-replace-compatibility.zh.md: dd4c5883c4c6d37809c2f8100f266655d8ba600c
+2026-08-06-token-surface-unpriced-replace-compatibility.zh.md: 0aff9db9b95e8670d85c8239dc2313b4e20f321c
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
index dd4c5883c4..0aff9db9b9 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md
@@ -8,19 +8,19 @@ Status: implemented
 
 `contextPressure` 与 `contextBreakdown` 两个投影只维护一份滚动累计的表层 token 总量，外加至多一条待结算的影子价格（shadow price）声明，因此其持久化检查点在会话整个生命周期内保持 O(1)。当前的替换生产方会紧贴在替换之前追加一条 `compact/summary` 或 `compact/prune` 计量事件；其 `shadowedTokenCount` 对被替换区间精确计价，`foldSurfaceProjection` 再把它换算成有符号增量。
 
-影子价格协议引入之前录制的会话，其日志中的替换没有相邻的计量事件。O(1) 状态无法重建被替换区间的价格，而折叠此前把每一次未计价替换都当作契约违规并抛出异常，于是回放这类会话会在第一处替换就中断（`token surface: replace at seq … has no adjacent shadow price`），会话从此永远无法打开。
+影子价格协议引入之前录制的会话，其日志中的替换没有相邻的计量事件。O(1) 状态无法重建被替换区间的价格，而折叠此前把每一次未计价替换都当作约定违规并抛出异常，于是回放这类会话会在第一处替换就中断（`token surface: replace at seq … has no adjacent shadow price`），会话从此永远无法打开。
 
 ## 决策
 
 到达时没有已就位声明的替换以价格中性的方式折叠：`foldSurfaceProjection` 返回 `deltaTokens: 0`，相当于把被替换区间计价为恰好等于其替换内容的成本，回放随即继续。因中间插入的事件而过期的声明也走同一条中性路径，因为折叠无法把它与从未计量过的日志区分开。
 
-已就位但指向**另一个**区间的声明仍会抛出异常。此时计量事件确实相邻，说明生产方写入了互相矛盾的相邻事件：这是现行影子价格契约的违规，不是历史数据，必须响亮失败，而不能任由总量悄然漂移。
+已就位但指向**另一个**区间的声明仍会抛出异常。此时计量事件确实相邻，说明生产方写入了互相矛盾的相邻事件：这是现行影子价格约定的违规，不是历史数据，必须响亮失败，而不能任由总量悄然漂移。
 
 两个投影共用同一个折叠，因此二者都不新增状态字段，也不提升 `stateVersion`。`surface-fold.ts` 与 `ctx.tokenMeter.measure()` 不受影响：它们持有逐节点的已计价表层，本来就不需要声明协议。
 
 ## 备选方案
 
-**维持抛出异常。**保住了严格的生产方契约，但协议之前的每个会话都将永远无法回放，而投影本就是为服务回放而存在的。
+**维持抛出异常。**保住了严格的生产方约定，但协议之前的每个会话都将永远无法回放，而投影本就是为服务回放而存在的。
 
 **在投影状态中持久化完整的已计价表层。**可以对任意被替换区间精确计价，但检查点会随每条模型可见消息各增加一个节点、无上限地增长，恰恰破坏了影子价格协议所要守住的 O(1) 约束（见[上下文仪表的 Agent Note](2026-08-05-context-meter-blind-to-compaction.md)）。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
index d31f344c27..e6758b23d2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
 2026-08-07-cancel-convergence-wake-latch.md: fe00c78bdfadac0cc6c9c173fd04256f77a22051
-2026-08-07-cancel-convergence-wake-latch.zh.md: f76ad360e2d8b70f76c6baf53e2fde963a80b6c4
+2026-08-07-cancel-convergence-wake-latch.zh.md: 736c5eb39809811363ed93529d90878ea9acdc89
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
index f76ad360e2..736c5eb398 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-`Agent.cancel(cause, { keepInbox: true })` 在触发 abort 信号后立即返回，但活动 driver 可能尚未收敛到 `idle`：LLM 流拆除、工具取消与 `turn/end` 落盘都会在 `abort()` 返回后异步展开。在该窗口内到达的唤醒 send 被放入 `next-turn`，而 `wakeDriver()` 对仍处于 `running` 的 phase 直接返回，退出的 driver 也从不重放这次唤醒——消息会一直停放到下一条唤醒 send 到达。被中止的 `runMaintenance` 活动周围也存在同样的唤醒丢失窗口。多个测试固化了停放行为（「等待下一次唤醒」）；该缺陷同时破坏了 `session.cancel` 与 `subagent.interrupt` 组合路径（issue #1838）。拥有取消与发送契约的既有决策是[显式轮次取消](../architecture/2026-07-16-explicit-turn-cancellation.md)与[统一发送](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)；生产环境中的 `keepInbox` 消费方是[Web 停止保留队列](2026-07-31-web-stop-preserves-queue.md)。
+`Agent.cancel(cause, { keepInbox: true })` 在触发 abort 信号后立即返回，但活动 driver 可能尚未收敛到 `idle`：LLM 流拆除、工具取消与 `turn/end` 落盘都会在 `abort()` 返回后异步展开。在该窗口内到达的唤醒 send 被放入 `next-turn`，而 `wakeDriver()` 对仍处于 `running` 的 phase 直接返回，退出的 driver 也从不重放这次唤醒——消息会一直停放到下一条唤醒 send 到达。被中止的 `runMaintenance` 活动周围也存在同样的唤醒丢失窗口。多个测试固化了停放行为（「等待下一次唤醒」）；该缺陷同时破坏了 `session.cancel` 与 `subagent.interrupt` 组合路径（issue #1838）。拥有取消与发送约定的既有决策是[显式轮次取消](../architecture/2026-07-16-explicit-turn-cancellation.md)与[统一发送](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)；生产环境中的 `keepInbox` 消费方是[Web 停止保留队列](2026-07-31-web-stop-preserves-queue.md)。
 
 ## 决策
 
-`running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察契约：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 后该边界被抑制，CI 发现了这一点）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
+`running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察约定：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 后该边界被抑制，CI 发现了这一点）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
 
 `signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（验收条件 1）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
 
diff --git a/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.i18n.yaml b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.i18n.yaml
index 369f69973d..2d4b3c0ad0 100644
--- a/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-14-acp-multi-session.md
 2026-06-14-acp-multi-session.md: 088fe984fbc94fe0d8654702d5fce9eb0581cd3b
-2026-06-14-acp-multi-session.zh.md: 083b160aa51e669b74931654cd08acaa3d2aa221
+2026-06-14-acp-multi-session.zh.md: ffa849d4baf742734df3ac4694cc9413d317ed1b
diff --git a/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md
index 083b160aa5..ffa849d4ba 100644
--- a/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-06-14-acp-multi-session.md) | 中文
 
-> 本 Agent Note 写于 ACP 还是编辑器桥接层的时期，动机来自 Zed 的多会话客户端模型。[ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)移除了编辑器接口；多路复用决策本身不变，本 Agent Note 现依照自动化契约陈述它。
+> 本 Agent Note 写于 ACP 还是编辑器桥接层的时期，动机来自 Zed 的多会话客户端模型。[ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)移除了编辑器接口；多路复用决策本身不变，本 Agent Note 现依照自动化约定陈述它。
 
 ## 问题
 
@@ -26,7 +26,7 @@ ACP 桥接层将活跃会话存储在 `Map<SessionId, SessionRecord>` 中。agen
 
 [ACP v1 明确允许一个连接上存在多个并发会话](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/get-started/architecture.mdx#L16-L24)，每个新会话都携带自己的主 `cwd`。本桥实现该会话级多路复用，其中包括[按会话 cwd 决策](../architecture/2026-07-02-fs-per-session-cwd.md)所记录的不同主工作区；它不会为每个会话创建一个 agent 子进程。
 
-一个会话内部的多根项目是另一项可选能力：ACP 把[有效根目录定义为主 `cwd` 加 `additionalDirectories`](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/protocol/v1/session-setup.mdx#L313-L367)。自动化桥接层不公布任何多根能力，并拒绝非空的 `additionalDirectories`；如[包契约](../../../../packages/acp/acp/README.md#protocol-contract)所记录，每个全新会话恰好有一个工作区。
+一个会话内部的多根项目是另一项可选能力：ACP 把[有效根目录定义为主 `cwd` 加 `additionalDirectories`](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/protocol/v1/session-setup.mdx#L313-L367)。自动化桥接层不公布任何多根能力，并拒绝非空的 `additionalDirectories`；如[包约定](../../../../packages/acp/acp/README.md#protocol-contract)所记录，每个全新会话恰好有一个工作区。
 
 [标准传输是每个 stdio 连接一个 agent 子进程](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/protocol/v1/transports.mdx#L17-L42)；多个连接因此需要多个子进程或自定义传输，而本决策保证的是一个连接内部存在多个会话。在该连接内，`ctx.sandboxPolicy` 把每个会话的 `cwd` 解析为其自己的 `workspace-write` 根目录，因此共享的 bash 和文件系统服务可以服务并发项目而不授予跨项目写入。这不会添加 ACP `additionalDirectories`；它只是从已经支持的「每会话一个主根目录」路径中移除了进程级根目录限制。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 684b2510f0..97e5ee763f 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-15-code-mode.md
 2026-06-15-code-mode.md: 99bbed3edab32512f88ece9694d6519a1f89c2dd
-2026-06-15-code-mode.zh.md: d6f0887f421296818b6bba7a26fc662c246cc28a
+2026-06-15-code-mode.zh.md: 87e39d7b68dd1dc2ebdee57f731be30d396a907b
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index d6f0887f42..87e39d7b68 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -42,7 +42,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调性守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
 
-1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，进入原生契约的分发池（调度设计由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责），以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `tool/code-dispatch-start`/`tool/code-dispatch` 事件对，其中结算侧携带完整渲染后的结果内容。成功时返回工具最终的规范 JSON 值；失败则变为程序可见的 `ToolCallError`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。
+1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，进入原生约定的分发池（调度设计由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责），以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `tool/code-dispatch-start`/`tool/code-dispatch` 事件对，其中结算侧携带完整渲染后的结果内容。成功时返回工具最终的规范 JSON 值；失败则变为程序可见的 `ToolCallError`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。
 2. **运行程序**：`ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`。运行时接收的是 run 级别的 signal 而非仅调用方的外层 signal，因此外层 run 以任何方式结算都会同时 abort 运行时内部的工作。
 3. **完全停稳后结算。** 运行时结算后，桥 abort 未完成的工作并排空分发队列后再返回。成功时返回捕获的日志和完成值，将其作为规范输出；注册表再把该值渲染为持久化的 `tool/result.content`，供结果卡片直接读取。运行时失败变为 `CodeRunFailedError`；后端拒绝使用注册表的正常错误边界。两者都产生结构化的错误结果，且 `run_code` 结算后不允许子调用追加。
 
@@ -120,7 +120,7 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 **Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，约束能力强于它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
 
-**`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的契约线，错误路径是一个可工作的反馈循环，而非死胡同。
+**`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的约定线，错误路径是一个可工作的反馈循环，而非死胡同。
 
 **SDK 的提示词成本，尤其在 `'both'` 下。** `.d.ts` 可能与它补充的原生 schema 体量相当；`'both'` 携带两种表示。前缀稳定性 + 提供方缓存摊销了每会话成本；mode 是每部署的；本 Agent Note 不做无条件节省的声明。何时优先使用哪种模式的量化指导明确属于上线后学习。
 
@@ -128,6 +128,6 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 **大型无损 JSON 值可能耗尽内存。** 工具绑定会在分发前对无损 JSON 创建快照，并完整返回规范 JSON 返回值。运行时会校验 worker 端口两侧，但不对单次绑定设置字节数上限；结构化克隆成本以及进程或 worker 内存构成实际边界。只有包含日志、完成值和失败诊断的组合外层输出账本受字节数上限约束。
 
-**子分发的重叠由工具自身的安全声明限定，而非由调用方决定。** 程序里的 `Promise.all` 或 `asyncio.gather` 只在工具自己分类为并发安全的调用之间换来挂钟并行性；一串 exclusive 调用仍要按顺序付出各自的往返开销，模型可能过度期望。两种 flavor 的 SDK 说明都陈述了真实契约。本 note 交付的是使该风险绝对化的序列化占位实现；调度器及其重叠上限由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
+**子分发的重叠由工具自身的安全声明限定，而非由调用方决定。** 程序里的 `Promise.all` 或 `asyncio.gather` 只在工具自己分类为并发安全的调用之间换来挂钟并行性；一串 exclusive 调用仍要按顺序付出各自的往返开销，模型可能过度期望。两种 flavor 的 SDK 说明都陈述了真实约定。本 note 交付的是使该风险绝对化的序列化占位实现；调度器及其重叠上限由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责。
 
 **预算计量读取事件循环，而非 flag。** 忙碌时间轮询（`eventLoopUtilization()`）比精确 CPU 计量更粗糙——预算到期最多延迟一个轮询间隔——且其正确性声明（「pending 的分发不能暂停它」）是抵御恶意程序的关键。两种情况均有单元测试（带 pending 诱饵分发的热循环会在耗尽 `computeMs` 预算时终止；等待慢速绑定的空闲程序则会持续运行至 `maxWallMs`），轮询间隔是内部常量而非配置——部署无法将其误调为绕过手段。`maxWallMs` 是配置项，且会传入 `setTimeout`，后者会把超过 `MAX_TIMER_DELAY_MS`（2^31-1 ms）的延迟夹到 1 ms；因此仅有正数校验会放行一个 25 天的上限，它在第一个 tick 就到期，使每次运行都超时。worker 运行时正因如此在加载时对该字段做范围校验。`computeMs` 不需要上界，因为它对照的是实测占用率，而不是交给定时器。
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
index 27336b9c4b..586cab797e 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
 2026-06-17-filesystem-tool-schemas.md: 9941b3916b361a916c8148eb099eb8cfd46371c8
-2026-06-17-filesystem-tool-schemas.zh.md: 4de0fe000a5524a3c5e76c6fa67f8a8b7e37ac6d
+2026-06-17-filesystem-tool-schemas.zh.md: 8ba3c18629863ca9f04548d5993e9d200ecd4912
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
index 4de0fe000a..8ba3c18629 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
@@ -66,11 +66,11 @@ schema 不将 `expected_hash`、`expected_version` 或 `create_only` 作为面
 
 `edit` 要求同一执行上下文先前观测过该文件（任何窗口化的 read 都算——授权取决于观测到的版本是否仍为最新，而不要求查看全文），或该上下文先前对该文件执行过 write/edit。`dsh-fs-policy` 策略插件推导所有者，并将记录的版本作为陈旧版本防护提供；提供方的变更锁会强制执行该防护。
 
-首次实现拒绝 Codex 风格的 patch 语法和多模式 edit API。它使用一种严格的字面替换模式，使面向模型的契约保持简单，并让后端掌控精确匹配、重复匹配、行尾和陈旧版本的语义。
+首次实现拒绝 Codex 风格的 patch 语法和多模式 edit API。它使用一种严格的字面替换模式，使面向模型的约定保持简单，并让后端掌控精确匹配、重复匹配、行尾和陈旧版本的语义。
 
 ## 结果形状
 
-首次实现曾将 `ContentBlock[]` 格式化逻辑放在 `execute` 中。[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)如今将 `ctx.fs` 的结果事实保留为工具经校验的值，并通过 `output.render` 派生相同的模型文本；文件状态的记录/刷新仍归 `ctx.fs` 所有。
+首次实现曾将 `ContentBlock[]` 格式化逻辑放在 `execute` 中。[规范工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)如今将 `ctx.fs` 的结果事实保留为工具经校验的值，并通过 `output.render` 派生相同的模型文本；文件状态的记录/刷新仍归 `ctx.fs` 所有。
 
 默认原生投影：
 
@@ -99,7 +99,7 @@ schema 测试固定每个工具的必填/可选参数集、空 `old_string` 拒
 
 ## 曾考虑的替代方案
 
-- **Codex 风格的 patch 语法或多模式 edit API**：否决。一种严格的字面替换模式使面向模型的契约保持简单，并让后端掌控精确匹配、重复匹配、行尾和陈旧版本的语义。
+- **Codex 风格的 patch 语法或多模式 edit API**：否决。一种严格的字面替换模式使面向模型的约定保持简单，并让后端掌控精确匹配、重复匹配、行尾和陈旧版本的语义。
 - **camelCase 参数名（OpenCode 风格）**：snake_case 与 Claude Code 及现有 harness 工具 schema 示例一致，且命名一旦发布即成为公开接口。
 - **面向模型的 `expected_hash` / `expected_version` / `create_only` 参数**：否决。陈旧检查由后端产生的版本和策略插件的观测状态驱动，从不依赖模型复制的脆弱令牌。
 
@@ -109,4 +109,4 @@ schema 测试固定每个工具的必填/可选参数集、空 `old_string` 拒
 
 **v1 中没有显式的面向模型的陈旧版本防护。** schema 不要求模型提供 expected hash/version。这是有意为之：陈旧检查来自后端产生的版本和 `dsh-fs-policy` 插件的观测状态，而非模型复制的脆弱令牌。文件系统安全失败通过 `dsh-fs` 拥有的结构化 `FsError` 代码浮现，而非模型提供的版本字段。
 
-**命名成为公开接口。** 一旦发布，将 `file_path` 改为 `filePath` 或 `old_string` 改为 `oldString` 会导致提示词、示例和下游客户端随之改动。本 Agent Note 预先选择 snake_case，并将其视为稳定的面向模型的契约。
+**命名成为公开接口。** 一旦发布，将 `file_path` 改为 `filePath` 或 `old_string` 改为 `oldString` 会导致提示词、示例和下游客户端随之改动。本 Agent Note 预先选择 snake_case，并将其视为稳定的面向模型的约定。
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index 230bcb69f5..60a89e6fab 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
 2026-06-18-compaction-capability-seam.md: 390d091fd6e6f7fa1694ba78b90522b70948fe92
-2026-06-18-compaction-capability-seam.zh.md: 59eb899acae0352a019cfc5252365e0116f84597
+2026-06-18-compaction-capability-seam.zh.md: 297b9adda4f13f6fd4da9e73bf2bcf3d8d6ead0c
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index 59eb899aca..297b9adda4 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 压缩作为能力 seam（抽象契约 + 基础后端）
+# Agent Note: 压缩作为能力 seam（抽象约定 + 基础后端）
 
 Status: implemented
 
@@ -16,22 +16,22 @@ Status: implemented
 
 ### 压缩是一个能力 seam，接口与实现分离
 
-遵循[能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)，压缩以独立包发布，使契约、算法和（后续的）消费方 surface 各自独立演进：
+遵循[能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)，压缩以独立包发布，使约定、算法和（后续的）消费方 surface 各自独立演进：
 
-1. **接口** — `@deepseek-ai/dsh-compact`：抽象 `CompactService`，拥有 `ctx.compact` 键、`CompactionResult` 词汇、`compact/*` 会话事件、手动失败分类体系以及规范的检查点消息来源。它将 `compactIfNeeded()`、`compactNow()` 和 `compactRegion()` 声明为**抽象方法**——契约说明压缩*做什么*，而非*怎么做*。
+1. **接口** — `@deepseek-ai/dsh-compact`：抽象 `CompactService`，拥有 `ctx.compact` 键、`CompactionResult` 词汇、`compact/*` 会话事件、手动失败分类体系以及规范的检查点消息来源。它将 `compactIfNeeded()`、`compactNow()` 和 `compactRegion()` 声明为**抽象方法**——约定说明压缩*做什么*，而非*怎么做*。
 2. **实现** — `@deepseek-ai/dsh-compact-basic`：具体的 `BasicCompactService`，消费 `ctx.tokenMeter`，并拥有尾→头保留遍历、通过 `ctx.llm.stream()` 生成摘要、surface 替换、锁、步骤前压力处理和规范的上下文溢出恢复。`summarize()` 是其唯一的子类钩子；计价与回放仍归 meter 所有。
 3. **无模型配套服务** — `@deepseek-ai/dsh-compact-tool-result-prune`：一个具体的可选服务，在后端选择摘要范围之前，重写当前过大的 `tool/result` 节点。它不是第二种压缩实现，也不实现 `CompactService`。
 4. **面向用户的消费方** — `@deepseek-ai/dsh-command-compact` 通过 `ctx.commands` 注册无参数 `/compact`，并调用后端无关的 `compactNow()` 操作。它是供用户直接控制的命令，不是面向模型的工具。
 
-### 契约依赖 `dsh-session` 和 `dsh-llm`——有意为之的偏离
+### 约定依赖 `dsh-session` 和 `dsh-llm`——有意为之的偏离
 
-能力 seam Agent Note 规定接口包「仅依赖 cordis」（对 `dsh-bash` 成立，因为其词汇是自包含的）。压缩**无法**遵守这一点：它的动词作用于 agent 所有的 `Session`（`compactRegion(start, end, agent)`），其输出使用内容词汇（`CompactionResult.summary: ContentBlock[]`）。不引用 `Session`/`SessionEvent`（来自 `dsh-session`）和 `ContentBlock`（来自 `dsh-llm`），契约就无法表达。
+能力 seam Agent Note 规定接口包「仅依赖 cordis」（对 `dsh-bash` 成立，因为其词汇是自包含的）。压缩**无法**遵守这一点：它的动词作用于 agent 所有的 `Session`（`compactRegion(start, end, agent)`），其输出使用内容词汇（`CompactionResult.summary: ContentBlock[]`）。不引用 `Session`/`SessionEvent`（来自 `dsh-session`）和 `ContentBlock`（来自 `dsh-llm`），约定就无法表达。
 
-这不是耦合异味，而是契约的领域所在。「仅 cordis」的指导原则一直是「接口仅依赖契约真正需要命名的东西，绝不依赖实现」的简写。`dsh-session` 和 `dsh-llm` 本身是接口/词汇包，不是实现；`dsh-compact` 仍然不导入任何后端。seam 的真正不变式——*消费方和实现在抽象服务背后独立演进*——完好无损。
+这不是耦合异味，而是约定的领域所在。「仅 cordis」的指导原则一直是「接口仅依赖约定真正需要命名的东西，绝不依赖实现」的简写。`dsh-session` 和 `dsh-llm` 本身是接口/词汇包，不是实现；`dsh-compact` 仍然不导入任何后端。seam 的真正不变式——*消费方和实现在抽象服务背后独立演进*——完好无损。
 
 ### 三个抽象操作，算法在后端
 
-早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将契约重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
+早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将约定重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
 
 `compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV Cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
 
@@ -110,7 +110,7 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 
 ## 曾考虑的替代方案
 
-- **完整算法作为接口的具体方法**——否决，因为它将契约重新耦合到一种保留策略。三个操作都是抽象的；可复用测量属于单独的 LLM 系列服务，`summarize()` 是 basic 唯一的钩子。
+- **完整算法作为接口的具体方法**——否决，因为它将约定重新耦合到一种保留策略。三个操作都是抽象的；可复用测量属于单独的 LLM 系列服务，`summarize()` 是 basic 唯一的钩子。
 - **在 `agent/request` 或压缩专属的 loop 回调上执行压缩**——否决，因为前者观察的是临时请求，后者会将通用生命周期耦合到压缩策略。对先前持久请求进行 pre-step 回放，再加上规范溢出恢复，即可覆盖成功和被拒绝的调用。
 - **`compact` 布尔值或无类型的请求元数据 map**——否决，因为多个辅助调用种类会变成互斥标志，而开放 map 会丢弃由编译器检查的词汇。一个类型化的 `purpose` 判别字段可以扩展其他调用种类，而无需再为 `GenerateOptions` 添加字段。
 - **单独的 `compact/error` 事件**——否决：`compact/end` 保留 `error?` 字段，与 `tool/result` 的自包含错误一致——一个事件即可区分成功与失败，无需关联兄弟事件。
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
index 9540bb6f0e..e55d06834c 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
 2026-06-22-acp-subagent-backend.md: c994ebfa69649bb9e79d3aa389a0e13c178131c7
-2026-06-22-acp-subagent-backend.zh.md: 62d631e95b5d1f299bed1fd00353b5ac9349b9a0
+2026-06-22-acp-subagent-backend.zh.md: 79be03dfc8310f6fc759d620c36d0d279c703073
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
index 62d631e95b..79be03dfc8 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
@@ -30,7 +30,7 @@ subagent seam（[seam Agent Note](2026-06-21-subagent-capability-seam.md)）的
 
 ### StopReason 映射
 
-ACP `StopReason` → harness `SubagentStopReason`：`end_turn`→`completed`、`max_tokens`→`max-tokens`、`refusal`→`refusal`、`cancelled`→`aborted`、`max_turn_requests`→`error`（无对等语义，任务未完成）、未知→`error`。spawn/传输/RPC 失败时，结果为 `error`（如果已请求取消则为 `aborted`）；按 seam 契约，`result` 在子 agent 级别失败时从不 reject。
+ACP `StopReason` → harness `SubagentStopReason`：`end_turn`→`completed`、`max_tokens`→`max-tokens`、`refusal`→`refusal`、`cancelled`→`aborted`、`max_turn_requests`→`error`（无对等语义，任务未完成）、未知→`error`。spawn/传输/RPC 失败时，结果为 `error`（如果已请求取消则为 `aborted`）；按 seam 约定，`result` 在子 agent 级别失败时从不 reject。
 
 ### 安全：清洗子进程环境
 
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
index f17347689c..32c80847bb 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-24-workspace-context.md
 2026-06-24-workspace-context.md: 53a580aee50752b7c6daeff5caa42ba6409c8885
-2026-06-24-workspace-context.zh.md: 79e5b0014801878595d3a5d71b8c4b23c5aad996
+2026-06-24-workspace-context.zh.md: 39c3f52da10b7299301d10bd8b78330cbae8e19c
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
index 79e5b00148..39c3f52da1 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 默认的逐目录候选列表是 `['AGENTS.md', 'CLAUDE.md']`。该列表可通过 `instructionFileCandidates` 配置；`AGENTS.md` 是普通的第一候选项，而不是隐藏优先级。一个目录中只加载第一个存在的普通文件候选项。使用默认值时，`AGENTS.md` 是原生文件，`CLAUDE.md` 是兼容性回退。第二个列表 `localInstructionFileCandidates`（默认为 `['AGENTS.local.md', 'CLAUDE.local.md']`）会在同一目录的基础文件后加载叠加式本地覆盖层；[默认本地覆盖层记录](2026-07-21-local-instruction-overlay.md)负责说明该决策。
 
-候选条目必须是同一目录中的文件名。空条目、`.`／`..`，以及包含 `/` 或 `\` 的条目会被忽略。其他同目录名称可以显式选择加入；规则目录和导入语义不属于本契约。
+候选条目必须是同一目录中的文件名。空条目、`.`／`..`，以及包含 `/` 或 `\` 的条目会被忽略。其他同目录名称可以显式选择加入；规则目录和导入语义不属于本约定。
 
 用户全局文件固定为 `$DSH_HOME/AGENTS.md`，不受任一候选列表影响，也没有本地覆盖层。`$DSH_HOME` 默认为 `~/.dsh`，与 `~/.codex` 或 `~/.claude` 在 harness 层的 home 角色一致，而不会引入插件专用 home。波浪号展开与默认值位于 `dsh-paths` 中，以便未来的 harness 功能共享同一约定。
 
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
index fa5b21ccac..2cb98d1258 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
 2026-06-29-todo-write-tool.md: c4cf64b7876bd8b80df80fe6fc27005715f96b5e
-2026-06-29-todo-write-tool.zh.md: 5efcaf1f6e7ea69b1dd8cd0fd31b9cbd931666db
+2026-06-29-todo-write-tool.zh.md: 2e95cfc4b085b03a70a651c622ca87ad7efa1538
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
index 5efcaf1f6e..2e95cfc4b0 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
@@ -14,7 +14,7 @@ harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结
 
 ### 整列表替换，三态 status
 
-模型每次调用发送完整列表；新列表替换旧列表（回放时 last-write-wins）。这是 claude-code V1、opencode 和 codex `update_plan` 共同采用的形状，也是模型训练最多的形状——没有逐项 id，没有 delta 协议。`status` 恰好是 `pending | in_progress | completed`，与 codex `update_plan` 相同的三元组；在 bridge 还把 todo 列表投影为 `plan` 更新时，它也与 ACP `PlanEntryStatus` 1:1 对应，该映射已随[仅面向自动化的 ACP 契约](../simplification/2026-07-23-acp-automation-only-protocol.md)退役。
+模型每次调用发送完整列表；新列表替换旧列表（回放时 last-write-wins）。这是 claude-code V1、opencode 和 codex `update_plan` 共同采用的形状，也是模型训练最多的形状——没有逐项 id，没有 delta 协议。`status` 恰好是 `pending | in_progress | completed`，与 codex `update_plan` 相同的三元组；在 bridge 还把 todo 列表投影为 `plan` 更新时，它也与 ACP `PlanEntryStatus` 1:1 对应，该映射已随[仅面向自动化的 ACP 约定](../simplification/2026-07-23-acp-automation-only-protocol.md)退役。
 
 ### 状态在会话日志上，而非服务
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
index 9a76a6024c..b5b5ea3b97 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
 2026-06-30-hook-protocol-lib.md: 2edff0d501cd7695873c68054eeb3a1e9942eced
-2026-06-30-hook-protocol-lib.zh.md: e9ae51f5d7697017ecc153866bbb8c3f6fd34eb6
+2026-06-30-hook-protocol-lib.zh.md: 90648c535e8bccd264ef9ae1ffd5f66590b1ac6d
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
index e9ae51f5d7..90648c535e 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-钩子子系统提供两个桥接插件：一个运行用户既有的 Claude Code（CC）钩子，另一个运行 Codex 钩子。研究参考实现（`~/repos/refs/claude-code`、`~/repos/refs/codex`）后发现一个决定性事实：**Codex 有意重新实现了 CC 钩子协议的一个子集。** 它的引擎读取相同的 `hooks.json`，使用相同的 matcher-group 形状、相同的 exit-code/structured-stdout 输出契约，以及相同的命令钩子执行模型。Codex 的源码甚至以 Claude 的引擎命名，并在注释中标注了「有意偏离」之处。因此，如果不做抽取，两个桥接插件将大量重复协议逻辑。
+钩子子系统提供两个桥接插件：一个运行用户既有的 Claude Code（CC）钩子，另一个运行 Codex 钩子。研究参考实现（`~/repos/refs/claude-code`、`~/repos/refs/codex`）后发现一个决定性事实：**Codex 有意重新实现了 CC 钩子协议的一个子集。** 它的引擎读取相同的 `hooks.json`，使用相同的 matcher-group 形状、相同的 exit-code/structured-stdout 输出约定，以及相同的命令钩子执行模型。Codex 的源码甚至以 Claude 的引擎命名，并在注释中标注了「有意偏离」之处。因此，如果不做抽取，两个桥接插件将大量重复协议逻辑。
 
 本 Agent Note 引入 `@deepseek-ai/dsh-hook-protocol`，一个**库**（不是插件——它不注册也不注入任何东西），持有两个桥接插件共同依赖的真正相同的原语。共享与方言专属之间的分界是本设计的重心。
 
@@ -17,7 +17,7 @@ Status: implemented
 **共享（本库）：**
 - **Matcher** — `matcherDiagnostic(pattern, mode)` 与 `matchesMatcher(pattern, query, mode)`。两种方言的唯一差异收敛到 `mode` 参数：`claude` 将纯 `[A-Za-z0-9_|]+` pattern 视为字面量（管道符表示多个精确匹配备选项），其他 pattern 视为正则；`codex` 始终使用未锚定正则。缺省/`''`/`'*'` 匹配一切。每个桥接插件会在解析 group 前忽略不支持的事件，丢弃受支持但没有 matcher 匹配对象的事件所带字段，校验其余可运行 group；其中任何无效正则都会导致整份配置加载失败，并给出包含方言／pattern／事件的稳定诊断，不会注册任何钩子监听器。运行时匹配仍会将无效正则隔离为不匹配，因此直接调用本库绝不向 agent loop（智能体循环）抛异常。
 - **执行** — `runHook(bash, hook, options)`。通过 `ctx.bash` seam 而非自建 `spawn` 运行命令钩子：执行器已提供清洗但可覆盖的 env、进程组 kill 和超时，正是协议所需的能力；`dsh-bash` 的 `stdin`/`env` 字段（正是为此添加的）是进程内桥接插件被允许使用的受信插件接口。它将桥接插件构建的 payload 序列化到 stdin（仅 CC 时追加尾部换行），遵守钩子的 `timeoutSec`（否则使用 `DEFAULT_HOOK_TIMEOUT_MS`，即两种方言共享的 10 分钟参考默认值），且从不抛异常（执行器拒绝变为 non-blocking-error 的 `HookOutput`）。
-- **解码** — `parseHookOutput(exit, stdout, stderr)`，exit-code + structured-stdout 编解码器，产出方言无关的 `HookOutput`。Exit `0` → 宽松 JSON 解析 stdout；exit `2` → blocking error，`stderr` 为原因（以 `decision: 'block'` 呈现，调用方无需单独处理 exit-code 分支）；其他 → non-blocking error。解析 CC structured-stdout 中在某条路径上有消费方的字段（`continue`/`stopReason`/`decision`/`hookSpecificOutput.{permissionDecision,additionalContext,updatedInput}`/`systemMessage`）；桥接插件只采纳对其方言有意义的子集。在任何路径上都没有消费方的字段不予解析（CC 的 `suppressOutput`——钩子 stdout 在此处从不进入 transcript（文本记录），因此无需抑制；见 [收紧钩子协议契约 Agent Note](../simplification/2026-07-04-tighten-hook-protocol-contract.md)）。
+- **解码** — `parseHookOutput(exit, stdout, stderr)`，exit-code + structured-stdout 编解码器，产出方言无关的 `HookOutput`。Exit `0` → 宽松 JSON 解析 stdout；exit `2` → blocking error，`stderr` 为原因（以 `decision: 'block'` 呈现，调用方无需单独处理 exit-code 分支）；其他 → non-blocking error。解析 CC structured-stdout 中在某条路径上有消费方的字段（`continue`/`stopReason`/`decision`/`hookSpecificOutput.{permissionDecision,additionalContext,updatedInput}`/`systemMessage`）；桥接插件只采纳对其方言有意义的子集。在任何路径上都没有消费方的字段不予解析（CC 的 `suppressOutput`——钩子 stdout 在此处从不进入 transcript（文本记录），因此无需抑制；见 [收紧钩子协议约定 Agent Note](../simplification/2026-07-04-tighten-hook-protocol-contract.md)）。
 - **合并** — `mergeHookOutputs(outputs)`，将多个匹配钩子的输出折叠为一个最严格的 `MergedHookOutcome`：权限优先级 **deny > ask > allow**，halt 在首个 `continue:false` 时粘滞，阻止原因以 `\n\n` 拼接，context/system-messages 按序累积。
 - **`hook/*` 会话事件** — `hook/invoked` / `hook/result`，通过声明合并进入 `SessionEventMap`（仅日志，如 `compact/*`——不是 `SurfaceEventType`），配有 `appendHookInvoked`/`appendHookResult` 辅助函数，确保 invoked/result 配对与由所有者定义的执行关系在各桥接插件间保持一致。`appendHookResult` 还负责定义持久化记录的语义：decision 字符串（钩子解析出的 decision，否则 `continue:false` 时为 `'stop'`，否则为 `'pass'`）和 500 字符的 `stderrSummary` 截断均从本库的 `HookOutput` 派生，而非各桥接插件各自实现。
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
index 3adc8a826f..b436887b7a 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-interception-seams.md
 2026-06-30-interception-seams.md: 3b2c62cd4413f6d93cef247c51304a8d46753218
-2026-06-30-interception-seams.zh.md: 40989aa6bd6f2c103312c01fb4efbab21487adea
+2026-06-30-interception-seams.zh.md: 110b28d48a342b50f8e5c1024ed2f2df704e4099
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
index 40989aa6bd..110b28d48a 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那样在生命周期节点扩展或管控 agent（智能体）。驱动本设计的关键视角转换是：**「原生钩子」不是一个包**——原生钩子只是一个普通的 Cordis 插件，订阅规范的生命周期事件。因此真正的产品是一个*强大、类型完备的规范事件表面*；CC/Codex 桥接（`dsh-hooks-claude` / `dsh-hooks-codex` 包）只是将外部 shell 钩子协议映射到同一表面的翻译层。桥接能做的事，普通插件可以直接做——而且更强大（无序列化边界、完整 `ctx`、类型化返回值）。
 
-该表面需要为以下场景提供各自独立的契约：逐提示词策略（CC 的 `UserPromptSubmit`）、会话启动观测（CC 的 `SessionStart`）、工具执行前策略、环绕调度控制、工具执行后变换、最终结果观测，以及携带面向模型的原因的继续执行。如果把这些阶段混为一谈，插件就会获得不需要的 mutation 通道，而终结性将依赖监听器的注册顺序。[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 提供了三域规则与类型化 Decision 惯用法；本 Agent Note 将其应用于生命周期 seam。
+该表面需要为以下场景提供各自独立的约定：逐提示词策略（CC 的 `UserPromptSubmit`）、会话启动观测（CC 的 `SessionStart`）、工具执行前策略、环绕调度控制、工具执行后变换、最终结果观测，以及携带面向模型的原因的继续执行。如果把这些阶段混为一谈，插件就会获得不需要的 mutation 通道，而终结性将依赖监听器的注册顺序。[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 提供了三域规则与类型化 Decision 惯用法；本 Agent Note 将其应用于生命周期 seam。
 
 ## 决策
 
@@ -31,7 +31,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 - **`ToolDefinition.finalizeContent`** 是一个可选、同步、对所有输入都有定义且仅能处理内容的边界，在调用创建时随可见定义一起被快照。注册表将候选结果规范化并创建无损快照后，它恰好运行一次；候选结果包括绕过后续 waterfall 的 pre、around 或 post 监听器失败，以及为另一个结果字段创建快照时发现的错误。它可以替换 `content`，也可返回 `undefined` 保留原内容，但不能重写 `isError`、结构化错误身份、上下文或呈现元数据。工具在此执行自身最后一道内容不变式，而无需将策略失败转换为更弱的阻止 decision。
 - **`tools/result`** 是在所有变换、无损 JSON 实体化和外层错误边界之后的同步且故障受控的通知。它接收相同的冻结执行身份和权威结果的不可变快照；观测者的失败按监听器隔离，无法改变或拒绝 `ToolRegistry.execute()` 返回的结果。
 
-核心调度与工具体位于规范化边界内部，因此工具、监听器、无效规范值、渲染器／投影器、非 JSON 呈现和身份形状错误均解析为 JSON 安全的 `isError` 结果，而非逃逸出轮次。post-execute 监听器因此可以检查一个抛出异常的工具；由工具定义负责的最终内容不变式也会覆盖外层流水线与候选结果实体化失败；最终观测者会同时看到执行期间的规范值，以及会话日志能够持久化的确切呈现字段。[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)定义值／投影与持久性规则。
+核心调度与工具体位于规范化边界内部，因此工具、监听器、无效规范值、渲染器／投影器、非 JSON 呈现和身份形状错误均解析为 JSON 安全的 `isError` 结果，而非逃逸出轮次。post-execute 监听器因此可以检查一个抛出异常的工具；由工具定义负责的最终内容不变式也会覆盖外层流水线与候选结果实体化失败；最终观测者会同时看到执行期间的规范值，以及会话日志能够持久化的确切呈现字段。[规范工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)定义值／投影与持久性规则。
 
 ### 三个承重的循环决策
 
@@ -43,7 +43,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 
 ### 工具执行前输入重写是一个独立的一致性决策
 
-`PreToolDecision` 不能重写参数。历史和审计调用在执行前记录，UI 展示读取相同的输入，因此注册表在策略之前封存参数。有效的重写必须在身份创建之前同时更新历史、审计、展示和执行；该契约属于[输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)。
+`PreToolDecision` 不能重写参数。历史和审计调用在执行前记录，UI 展示读取相同的输入，因此注册表在策略之前封存参数。有效的重写必须在身份创建之前同时更新历史、审计、展示和执行；该约定属于[输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)。
 
 ### 边界
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
index 3e46be0e44..3e5d68bb7e 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
 2026-06-30-session-store-fork-api.md: 69ff85e1f137f4f263bf951af0a3f655411c606a
-2026-06-30-session-store-fork-api.zh.md: 75262c8ceca40745feba1d4384cb949b95f3c677
+2026-06-30-session-store-fork-api.zh.md: f354aaefbc16c6c3251da20de507602105a32296
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
index 75262c8cec..f354aaefbc 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
@@ -46,4 +46,4 @@ Host 通过 agent（智能体）注册表，以选定的种子和谱系创建子
 
 公开接口保持精简且易于发现：活跃会话分支是 `ctx.sessions` 的一部分，紧邻 `create({ seed })`，而非一个独立服务或一对两步辅助函数。持久化继续通过现有的 `session/created` 和 `session/flush` 行为运作：fork 出的子会话创建时便带有种子事件，因此现有后端只需持久化该种子一次，并在 header 中保存 `parentSession`／`seedLength`。
 
-v1 范围仍然排除 ACP（Agent Client Protocol） `session/fork`、对未加载的已持久化会话的 fork、面向模型的工具，以及 subagent 重构。如果未来添加 ACP 方法，应在具备协议与快照覆盖后才声明支持该能力；本 Agent Note 不添加任何 ACP 协议行为，因此不需要 ACP 快照。fork 子会话的回放仍由现有的[种子边界测试 Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md) 覆盖；store、Host、载体与客户端的专项测试固定边界和对账契约，真实 Chromium 场景则固定组装后的消息操作与谱系树。
+v1 范围仍然排除 ACP（Agent Client Protocol） `session/fork`、对未加载的已持久化会话的 fork、面向模型的工具，以及 subagent 重构。如果未来添加 ACP 方法，应在具备协议与快照覆盖后才声明支持该能力；本 Agent Note 不添加任何 ACP 协议行为，因此不需要 ACP 快照。fork 子会话的回放仍由现有的[种子边界测试 Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md) 覆盖；store、Host、载体与客户端的专项测试固定边界和对账约定，真实 Chromium 场景则固定组装后的消息操作与谱系树。
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
index 394af669cd..52c64ec86d 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
 2026-07-05-dynamic-workflows.md: b0fb2349e64093beab8220ea75715b55903772e3
-2026-07-05-dynamic-workflows.zh.md: 246727649be8acc17dac1335d353e9b1591e3890
+2026-07-05-dynamic-workflows.zh.md: b66e767090e29f7e0cceb35b59eedb2ea60d12eb
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
index 246727649b..b66e767090 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
@@ -12,7 +12,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 在 `packages/workflow/` 下以 bash seam 的形态（接口／实现／消费方）提供一组工作流能力，以及它在 subagent seam 上所需的结构化输出基础。
 
-### 脚本契约（兼容 Claude Code）
+### 脚本约定（兼容 Claude Code）
 
 一次工作流调用包含 JSON `meta`（`name`、`description`，以及可选的 `whenToUse`/`phases`）和一段支持顶层 `await` 并返回 JSON 值的 JavaScript `script` 正文。元数据作为数据校验，从不被执行。正文接收 `agent(prompt, options)`、`parallel(thunks)`、`pipeline(items, ...stages)`、`phase(title)`、`log(message)` 和 `args`。流水线各阶段接收 `(prev, item, index)`，阶段之间无屏障；失败的子 agent 和普通阶段错误将受影响的 item 结算为 `null` 并跳过其剩余阶段。Claude Code 的确定性限制随日志机制一并延后实现，因此兼容的脚本正文在将 meta 头移入参数后可以使用时钟和随机数。
 
@@ -28,7 +28,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 **为何选择 `node:worker_threads`**：每次运行获得一个非池化的 worker。vm 上下文限定了文档中说明的脚本接口范围，而消息端口 RPC 将 `agent()` 桥接到宿主侧的子循环。worker 防止脚本的同步工作阻塞宿主，提供序列化边界，并允许取消后强制终止。`isolated-vm` 因其维护状态和部署要求被否决。
 
-宿主在发布前校验元数据并解析正文。私有枚举键 payload 映射定义协议格式；待启动记录、已发布子记录、单一取消信号、worker 死亡回收、结果优先级与 dispose 完全停稳，在此协议上保持 subagent run 契约。这些竞态算法由 [agent 作用域运行时设计 Agent Note](../architecture/2026-07-12-agent-scope-runtime-design.md#workflow-children-are-pending-starts-or-published-records) 定义。
+宿主在发布前校验元数据并解析正文。私有枚举键 payload 映射定义协议格式；待启动记录、已发布子记录、单一取消信号、worker 死亡回收、结果优先级与 dispose 完全停稳，在此协议上保持 subagent run 约定。这些竞态算法由 [agent 作用域运行时设计 Agent Note](../architecture/2026-07-12-agent-scope-runtime-design.md#workflow-children-are-pending-starts-or-published-records) 定义。
 
 引擎暴露一条进程内 `MessageChannel` 测试路径，因为主进程 V8 覆盖率无法观测 worker 执行。
 
@@ -55,7 +55,7 @@ worker 侧逻辑通过进程内 `MessageChannel` 运行，使 V8 覆盖率能够
 ## 延迟（本轮明确的非目标）
 
 - **后台收集**（启动工具 → run id → 完成通知 → 收集），与 bash/subagent 后台统一一起设计。
-- **日志化 + 恢复**（`resumeFromRunId`、缓存的 agent() 前缀）：实现它会以脚本契约收紧的形式重新引入 CC 的确定性禁令（脚本目前可以读取时钟）。
+- **日志化 + 恢复**（`resumeFromRunId`、缓存的 agent() 前缀）：实现它会以脚本约定收紧的形式重新引入 CC 的确定性禁令（脚本目前可以读取时钟）。
 - **保存/打包的工作流**（`.deepseek/workflows/` 注册表、斜杠命令界面）和**脚本持久化到运行目录**（工具调用事件已经持久记录了脚本）。
 - **嵌套 `workflow()`**、**token `budget`**，以及 `effort`/`isolation`/`agentType` agent 选项（每个都会明确拒绝，并在消息中注明其已延迟实现）。
 - **整体运行的挂钟超时**：取消总能释放调用方（result 在宽限期内 settle），因此总运行时间上限是后台重设计的策略旋钮，不是此处的正确性需求。
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index e0f79bacb0..05b3a3700f 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-05-skill-system.md
 2026-07-05-skill-system.md: 5961c535a1397c487b0255f8a27d60929c2eeace
-2026-07-05-skill-system.zh.md: 05bd880ecbd46f2b472eb2cc5442f11c07f89b4e
+2026-07-05-skill-system.zh.md: 42ae08e603411bee6212f6f321eb766c9b9d1859
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 05bd880ecb..42ae08e603 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -22,13 +22,13 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 每个 skill 是 `<name>/SKILL.md` 或带 YAML frontmatter 的 `<name>.md`。`name` 和 `description` 为必填；`whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable` 为可选。名称采用 kebab-case。调用字段会投影到类型化的嵌套策略中，具体由[模型与用户独立调用决策](2026-07-28-skill-invocation-policy.md)定义；解析器会拒绝旧的驼峰拼写。YAML frontmatter 使用 `yaml` 包（package）解析，而非 `js-yaml` 或手写解析器：`yaml` 是本包有限 frontmatter 需求已声明的现代解析器，窄解析器要么拒绝用户预期可用的合法 YAML，要么膨胀为一个未经评审的 YAML 子集。
 
-本地 skill 的文件系统 I/O 在加载了文件系统服务时通过 `ctx.fs` 进行：项目根目录查找使用 `resolve` 和 `stat` 探测 `.git`，根目录发现使用 `listDir`，skill 读取使用 `readText`。Node 文件系统作为后备，供在不挂载 fs seam 的最小上下文中加载 `dsh-skill-local` 时使用。缺失的根目录、不可读或格式错误的 skill 文件、以及提供方 `list()` 的瞬态失败均降级为警告并跳过，使一个坏源不会导致所有 agent 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方契约。
+本地 skill 的文件系统 I/O 在加载了文件系统服务时通过 `ctx.fs` 进行：项目根目录查找使用 `resolve` 和 `stat` 探测 `.git`，根目录发现使用 `listDir`，skill 读取使用 `readText`。Node 文件系统作为后备，供在不挂载 fs seam 的最小上下文中加载 `dsh-skill-local` 时使用。缺失的根目录、不可读或格式错误的 skill 文件、以及提供方 `list()` 的瞬态失败均降级为警告并跳过，使一个坏源不会导致所有 agent 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方约定。
 
 `dsh-tool-skill` 在会话的第一个 `agent/pre-step` 注入一个持久化的 user-role `<system-reminder>` 目录，作为带来源的 `user/message`，且仅当该 agent 的工具视图解析到本插件精确的 `skill` 注册时才注入。该目录仅包含排序后的 skill 名称与描述；不包含正文、路径、来源、提供方和路由提示。描述经过空白规范化、XML 转义，并受 `catalogDescriptionMaxLength` 上限约束，其默认值为 `500`，最小值为 `3`。完整的 skill 正文从不包含在目录中。（目录最初通过仅请求的[会话前缀 seam](../../archived/feature/2026-07-07-session-prefix.md)（已归档）传递；[统一带来源消息的决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)将其移入持久化历史。）
 
 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
 
-数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/subsystems/skills.md#cordis-surface)。
+数据结构与目录/工具约定记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/subsystems/skills.md#cordis-surface)。
 
 ## 曾考虑的替代方案
 
@@ -54,4 +54,4 @@ agent-core 主干包含一个目录贡献者、一个本地提供方和一个面
 
 ## 延后
 
-Fork 的 skill 上下文（`context: fork`）、参数声明与提示（`arguments` 和 `argument-hint`）、以及逐 skill 的工具约束（`allowed-tools` 和 `disallowed-tools`）不在已交付的契约范围内。注册表、本地提供方和面向模型的工具不解析、不广播、也不执行这些字段。直接用户调用曾作为 TUI 功能交付，基于共享调用策略和受信的 `get()` 原语；见[已归档的 TUI skill 斜杠命令](../../archived/feature/2026-07-21-tui-skill-slash-command.md)。
+Fork 的 skill 上下文（`context: fork`）、参数声明与提示（`arguments` 和 `argument-hint`）、以及逐 skill 的工具约束（`allowed-tools` 和 `disallowed-tools`）不在已交付的约定范围内。注册表、本地提供方和面向模型的工具不解析、不广播、也不执行这些字段。直接用户调用曾作为 TUI 功能交付，基于共享调用策略和受信的 `get()` 原语；见[已归档的 TUI skill 斜杠命令](../../archived/feature/2026-07-21-tui-skill-slash-command.md)。
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
index b5c6343382..46f1ed0675 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-approval-seam.md
 2026-07-06-approval-seam.md: a286e07d51a70232f9aab0af5d8a19622cd222d4
-2026-07-06-approval-seam.zh.md: 6656cfe46de663f0e89eacc78dcfb3425812f9e0
+2026-07-06-approval-seam.zh.md: b15fcb2f6ed52ee591082770d68e265b5a703ff8
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
index 6656cfe46d..b15fcb2f6e 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
@@ -77,7 +77,7 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 #### 实体与依赖
 
-`dsh-user-approval` 依赖 Cordis，以及会话、agent 和带 brand 的调用契约；`dsh-tools` 与 `dsh-acp` 消费它。沙箱执行器保持独立，因为升级请求归 `dsh-tool-bash` 所有。固定的派发与审计服务仍是一个包；可替换的应答者留在各自的通道所有者中。静态能力授权和 `subagent-acp` 子侧权限应答仍是独立关注点。
+`dsh-user-approval` 依赖 Cordis，以及会话、agent 和带 brand 的调用约定；`dsh-tools` 与 `dsh-acp` 消费它。沙箱执行器保持独立，因为升级请求归 `dsh-tool-bash` 所有。固定的派发与审计服务仍是一个包；可替换的应答者留在各自的通道所有者中。静态能力授权和 `subagent-acp` 子侧权限应答仍是独立关注点。
 
 ### 测试
 
@@ -95,14 +95,14 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 - **单一注册提供方而非 waterfall 监听器**：否决。`registerProvider()` 接口迫使所有组合问题——允许列表预过滤、外部钩子决策者、脚本化测试应答、人类前面的策略门禁——都塞进一个提供方实现。waterfall 直接复用运行时已有的组合能力、缺失时默认拒绝行为和 HMR（热模块替换）资源释放机制；seam 的 JSDoc 以约定固定单决策槽语义，而非发明一个提供方注册表。
 - **在 ACP 桥中内联 `tools/pre-execute` 权限门禁**：否决。对桥拥有的每次调用都弹出提示，会将请求策略硬编码进传输层，无法服务第二个发起方（沙箱升级发生在执行开始之后，没有 pre-execute 时刻），且钩子产生的 `ask` 决策没有共享机制。
-- **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的契约在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/interaction/user-interaction` / `ask_user_question` 信息征集路径——信息征集表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
+- **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的约定在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/interaction/user-interaction` / `ask_user_question` 信息征集路径——信息征集表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
 - **`dsh-tools` 中的静态可选注入**：否决。vendor 的 Cordis `Inject` 类型没有 optional 标志——对象形式将服务名映射到拦截配置，声明的 inject 会阻塞 fiber。`ctx.get('approval')` 是文档化的机会性消费模式（`tool-bash` 的 owner-token 查找、loop 的持久化探测），按调用读取存在性，跨 HMR 正确降级，无需额外机制。
 - **能力 seam 的三包拆分**：否决。接口/实现/消费方适合实现可替换的 seam（bash-local vs bash-sandbox）。此处服务体是固定机制，可变部分是留在各自通道拥有者插件中的监听器——拆分只会制造一个空的实现包（「不要预防性拆分」）。
 - **现在就提供 `allow_always`**：否决。协议能表达它，但兑现它意味着设计授权存储、作用域标识和撤销（§ 延后）。展示 harness 无法兑现的选项只会制造注定失败的授权。
 
 ## 后果
 
-实现后的契约由「测试」一节所列套件固定：
+实现后的约定由「测试」一节所列套件固定：
 
 - `allowed-once` 派发一次操作；其他所有结果都以不同原因拒绝，而 `'never'` 会在提示前拒绝。
 - 缺失、外部、无 agent、抛异常、无效或断开连接的应答路径都会失败关闭。
@@ -113,7 +113,7 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 - **两个都会直接作出决策的应答者会竞争同一槽位。** 兄弟插件的监听器顺序不确定，seam 无法仲裁竞争的终端应答者。通过约定缓解（每个部署一个终端应答者；仅对「先决策或委派」门禁使用 `prepend`），而非事件总线不具备的优先级机制。
 - **生产路径仅在一种组合下得到验证。** `ask` 有两个生产者家族——钩子桥通过 `tools/pre-execute`，沙箱升级通过自己的门禁——协议格式录制在沙箱示例的快照套件中；因此在更多部署组合它之前，seam 的真实覆盖面就是这一种组合。
-- **归属以 `Agent` 对象标识为键。** 应答者先在 `agent.session.id` 处解析会话映射记录，再要求该记录拥有精确的 agent 对象；当前所有路径在 loop 和各 seam 之间传递同一对象，但未来如果某个边界克隆或代理了 agent，桥会委派并失败关闭，届时需要另一种归属契约。
+- **归属以 `Agent` 对象标识为键。** 应答者先在 `agent.session.id` 处解析会话映射记录，再要求该记录拥有精确的 agent 对象；当前所有路径在 loop 和各 seam 之间传递同一对象，但未来如果某个边界克隆或代理了 agent，桥会委派并失败关闭，届时需要另一种归属约定。
 
 ## FAQ
 
@@ -132,7 +132,7 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 本设计复用或对照的仓库内先例：
 
-- `fs/write-intent` 门禁（`packages/fs/fs/`）——文档化的单占用决策槽 waterfall 语义（先到先得，通过 `next()` 委派），应答者契约复用了它。
+- `fs/write-intent` 门禁（`packages/fs/fs/`）——文档化的单占用决策槽 waterfall 语义（先到先得，通过 `next()` 委派），应答者约定复用了它。
 - `hook/invoked`/`hook/result`——仅日志审计对先例，`approval/asked`/`approval/decided` 沿用了它；[钩子桥 Agent Note](2026-06-30-hook-bridges.md) 交付了 `permissionDecision: ask`，即第一个生产者。
 - [拦截 seam Agent Note](2026-06-30-interception-seams.md)——`tools/pre-execute` 的 `allow`/`deny`/`ask` 词汇，本 seam 服务其中的 `ask`。
 - [仅面向自动化的 ACP Agent Note](../simplification/2026-07-23-acp-automation-only-protocol.md)——应答者路由时对会话映射执行的精确 agent 归属检查；[多会话 Agent Note](2026-06-14-acp-multi-session.md)——本设计实现的每会话权限归属阻塞项。
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
index c01e419b7d..3ede7af472 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
 2026-07-06-explicit-tool-order.md: bd6d0a04aa470ca33e618957ae1f08c1ef15fcfe
-2026-07-06-explicit-tool-order.zh.md: 88955aaaa55b18ac94153b34d4e514ecc1fa1100
+2026-07-06-explicit-tool-order.zh.md: 69365151f2c20cfa782ecc5560a6c600c8dec6a2
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
index 88955aaaa5..69365151f2 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 
 `assemble()` 在 `system-prompt/assemble` waterfall（瀑布式事件）之前将提供方工具归一为权威顺序，从源头消除注册顺序的差异。waterfall 从这个确定性列表开始；不变的顺序随后流入请求头、冻结的请求和重建检查，无需 loop 特有的排序逻辑。
 
-范围刻意收窄：本 Agent Note 修复的是注册顺序竞态，而非插件行为。`system-prompt/assemble` 的监听器仍然可以添加、移除或重排工具——正如它可以在 section 排序之后编辑 section——并对自身输出的确定性负责；waterfall 契约已经要求监听器是确定性的（可重建性不变式会捕获在构建与回放之间行为不一致的监听器）。
+范围刻意收窄：本 Agent Note 修复的是注册顺序竞态，而非插件行为。`system-prompt/assemble` 的监听器仍然可以添加、移除或重排工具——正如它可以在 section 排序之后编辑 section——并对自身输出的确定性负责；waterfall 约定已经要求监听器是确定性的（可重建性不变式会捕获在构建与回放之间行为不一致的监听器）。
 
 配置传递沿用 `persona` 的先例，`toolOrder` 与之并列：TUI、Headless 和 ACP 应用配置接受该键，并通过 `dsh-agent-spine-demo`（其 schema 是各所有者 schema 的交集）转发给 `SystemPrompt` 子服务。有一个 schemastery 细节至关重要：schemastery 数组默认为 `[]`，但省略的 `toolOrder` 必须保持 ABSENT（= 字典序），而不是变成一个显式配置的空列表（无效——缺少 rest 条目），因此链路上每个 schema 都将默认值强制为 `undefined`。
 
@@ -44,7 +44,7 @@ Status: implemented
 - 步骤之间的纯工具重排与其他 header 变更一样记录：一份原因是 `'change'` 的完整 `request/header` 快照。稳定的权威顺序会防止注册时序在普通路径上制造这类变化。
 - `toolOrder` 键沿 app → `agent-core` → `SystemPrompt` 的转发链传递，因此部署时将其放在 app 配置中 `persona` 旁边即可；`dsh-llm` 和 agent loop 无需改动。
 - `toolOrder` 中拼错或未加载的工具名称在提示词组装时使轮次失败，而非启动时：loop 在轮次内部组装（`turn/start` 之后、`step/start` 之前），因此拒绝到达轮次的外层 catch——轮次以 `error` 原因完整结束并携带错误消息，`agent/error` 复现该消息，不打开步骤，不记录 `request/header`，不向适配器发出请求，agent 回到空闲状态。每个轮次都以相同方式失败，直到配置被修正；进程本身保持运行（符合仓库规则：显式配置引用不得被静默忽略——执行点是组装，因为不存在更早的通用时刻）。
-- 工具提供方返回保留的 rest 条目名称时，其提示词组装失败形态与未知的已列名称相同。这防止哨兵值变成一个歧义的真实工具，并保持「从不丢弃工具」的排序契约。
+- 工具提供方返回保留的 rest 条目名称时，其提示词组装失败形态与未知的已列名称相同。这防止哨兵值变成一个歧义的真实工具，并保持「从不丢弃工具」的排序约定。
 
 ## 测试
 
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 755c076bca..5002872c0b 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-sandbox.md
 2026-07-06-sandbox.md: 06c5590454a6947030d828f087b92f44207dad6e
-2026-07-06-sandbox.zh.md: 9f55626a8fd12782249284c83f1e76e1d2f89724
+2026-07-06-sandbox.zh.md: 85b9b6a65b6468b19c6044b4837abc4fab1cee1a
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index 9f55626a8f..85b9b6a65b 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -50,7 +50,7 @@ OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还
 
 #### seam：`ctx.sandbox`
 
-`dsh-sandbox` 负责定义词汇和 `SandboxProvider` 契约：`confine(argv, policy)` 返回调用方应当 spawn 的替代 argv（经过包装，使进程及其所有子进程在约束下运行），加上所选后端达到的 `enforcement` 完整度、其拒绝方言（`denialSignatures`，该后端内核在拒绝文件操作时打印到 stderr 的子串），以及其结构化 runner 失败证据（`runnerFailureRules`，可选的允许退出码加上排除整行精确信息性行后按行匹配的致命签名）；没有可用后端时抛出失败关闭的 `SANDBOX_UNAVAILABLE` 错误，绝不静默放行。词汇：`SandboxMode`（`read-only` / `workspace-write` / `danger-full-access`，仅限文件操作——不声称覆盖网络和进程可见性）、`SandboxEnforcement`（`full` / `partial`）、`SandboxExecutionPolicy`（每次能力调用的完整 mode + 工作区根目录）以及 `SandboxPolicy`（提供给约束后端的子集）。
+`dsh-sandbox` 负责定义词汇和 `SandboxProvider` 约定：`confine(argv, policy)` 返回调用方应当 spawn 的替代 argv（经过包装，使进程及其所有子进程在约束下运行），加上所选后端达到的 `enforcement` 完整度、其拒绝方言（`denialSignatures`，该后端内核在拒绝文件操作时打印到 stderr 的子串），以及其结构化 runner 失败证据（`runnerFailureRules`，可选的允许退出码加上排除整行精确信息性行后按行匹配的致命签名）；没有可用后端时抛出失败关闭的 `SANDBOX_UNAVAILABLE` 错误，绝不静默放行。词汇：`SandboxMode`（`read-only` / `workspace-write` / `danger-full-access`，仅限文件操作——不声称覆盖网络和进程可见性）、`SandboxEnforcement`（`full` / `partial`）、`SandboxExecutionPolicy`（每次能力调用的完整 mode + 工作区根目录）以及 `SandboxPolicy`（提供给约束后端的子集）。
 
 策略随每次调用而非提供方携带：两个消费方可以在同一时刻以不同策略约束（bash 在 `read-only` 下运行，而一个受约束的子 agent 保持其状态目录可写），且经批准的升级重试是一次带有更宽策略的新调用——在配置固定的提供方模式下无法表达。
 
@@ -66,7 +66,7 @@ launcher 是一个约 300 行的 C 程序（纯 C11，直接使用 Landlock UAPI
 
 Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 消费方同仓，并属于根 pnpm workspace。[仓库内 Landlock 发布决策](../process/2026-08-06-in-repository-landlock-release.md)负责共享锁文件、原生构建、打包演练和 npm 发布边界。平台二进制由 npm 选择，入口包拥有路径解析、探测、CLI 参数、致命前缀和部分强制执行通知，而 harness 将沙箱模式映射为授权。将入口点与其二进制一起版本化，使探测解析和启动语法保持对齐。
 
-后端 profile 共享模式契约但在必要的主机授权上有所不同。Landlock 和 Seatbelt 在 read-only 模式下仅允许 `/dev/null`；workspace-write 还允许各自所需的主机临时目录根。每次包装携带后端特定的拒绝签名。Landlock 在较旧的 ABI 无法管控所有操作时报告 partial enforcement，而成功的 bwrap 和 Seatbelt profile 报告 full enforcement。
+后端 profile 共享模式约定但在必要的主机授权上有所不同。Landlock 和 Seatbelt 在 read-only 模式下仅允许 `/dev/null`；workspace-write 还允许各自所需的主机临时目录根。每次包装携带后端特定的拒绝签名。Landlock 在较旧的 ABI 无法管控所有操作时报告 partial enforcement，而成功的 bwrap 和 Seatbelt profile 报告 full enforcement。
 
 #### bash 消费方
 
@@ -146,7 +146,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 - **同一工具调用内自动重试**：否决。日志无法重建的隐藏重入：一个 `tool/call` 会产生两次具有不同策略的执行——重试是一次新的带有自身参数和结果事实的已记录调用。
 - **无条件公布升级字段**：否决。在 `dsh-bash-local` 下它们是死杠杆——公布 harness 无法兑现的选项会制造注定失败的授权；能力门控仅需注册时一次读取。
 - **默认值相对的升级阶梯（仅公布比执行器注册时默认值更宽的模式）**：否决。按会话覆盖使默认值成为错误的基线——切换到比默认值更窄的会话恰恰失去它需要的杠杆，而在 `danger-full-access` 默认值下字段完全消失，同时一个被覆盖为 `read-only` 的会话仍处于约束中却没有升级路径。枚举固定封闭的目标词汇；严格放宽是针对会话有效模式的按调用执行检查。
-- **按会话动态工具 schema**：否决。schema 设计上是注册表全局的（一套 assembly 词汇、固定 header 快照契约），按会话重新注册只能买到执行时严格放宽检查已保证的东西，代价是按会话的 schema 表面和每次切换的 header 变动。
+- **按会话动态工具 schema**：否决。schema 设计上是注册表全局的（一套 assembly 词汇、固定 header 快照约定），按会话重新注册只能买到执行时严格放宽检查已保证的东西，代价是按会话的 schema 表面和每次切换的 header 变动。
 - **将重试硬匹配到先前的拒绝**：否决。命令字符串同一性脆弱（引号、`workdir`、env 前缀、作为失败阶段重试的管道）——要么误拒诚实的重试，要么被轻易满足；真正的边界是人看到命令 + 理由。仅在 `allow_always` 授权存储需要机器可检查的范围时才重新考虑。
 - **通用 `env/state` facts map 加拥有者服务**：否决。approval 和沙箱独立组合，因此任何一方的状态都不应拖入第三个包；单键 fold 各自是一个 `findLast`，拥有者服务自然消解；没有跨旋钮的不变式，因此原子多键补丁无收益。
 - **通过 `agent.inject()` 加总线事件逐次叙述切换**：否决。独立通知会暴露归属方顺序和中间组合，而一次 pre-step 组合可以原子排队完整的当前状态。
diff --git a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
index 8ac4cd01ef..ca61a3783c 100644
--- a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.md
 2026-07-07-mcp-client-plugin.md: 756a5c4dc9f1152ecb1955d93b8dc47fcf07c661
-2026-07-07-mcp-client-plugin.zh.md: 88401ad63bce0b690561acf3bb820b3b758779fa
+2026-07-07-mcp-client-plugin.zh.md: 9f45203c479379087c5a19eccce3ab7a339d4ed0
diff --git a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.zh.md b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.zh.md
index 88401ad63b..9f45203c47 100644
--- a/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.zh.md
@@ -104,7 +104,7 @@ type Config = StdioConfig | StreamableHttpConfig
 
 ### 公开名称规范化
 
-MCP 允许工具名最长 128 字符且可包含 `.`；DeepSeek 的函数名契约允许 `[A-Za-z0-9_-]` 且最多 64 字符。公开名称按确定性规则规范化：非法字符替换为 `_`，当替换或截断改变了名称时，追加 `(serverName, rawName)` 标识的 12 位十六进制 SHA-256 hash，确保不同的 MCP 标识永远不会坍缩为同一个公开名称：
+MCP 允许工具名最长 128 字符且可包含 `.`；DeepSeek 的函数名约定允许 `[A-Za-z0-9_-]` 且最多 64 字符。公开名称按确定性规则规范化：非法字符替换为 `_`，当替换或截断改变了名称时，追加 `(serverName, rawName)` 标识的 12 位十六进制 SHA-256 hash，确保不同的 MCP 标识永远不会坍缩为同一个公开名称：
 
 ```typescript
 function publicToolName(serverName: string, rawName: string): string {
@@ -131,7 +131,7 @@ MCP 仅保证工具名在[单个服务器内](https://modelcontextprotocol.io/sp
 ### 命名不变式
 
 1. 每个 MCP 工具拥有稳定标识 `(serverName, rawName)`；每个活跃标识恰好对应一个公开名称。
-2. 公开名称是确定性的、全局唯一的，且满足 DeepSeek 64 字符 `[A-Za-z0-9_-]` 契约。
+2. 公开名称是确定性的、全局唯一的，且满足 DeepSeek 64 字符 `[A-Za-z0-9_-]` 约定。
 3. MCP `tools/call` 始终接收原始的 raw name。
 4. 连接、断开或重新同步不相关的服务器永远不会重命名已有工具。
 5. 注册顺序永远不决定哪个工具可用。
@@ -206,7 +206,7 @@ v1 否决。它能防止跨服务器冲突，但无法将 MCP 注册与原生 ha
 ## 后果
 
 - 每个 MCP 服务器只需 `cordis.yml` 中的一条配置即完成集成：`serverName: filesystem` 加一条 stdio 命令（或一个 Streamable HTTP URL），就能将 `mcp__filesystem__read_file` 放入模型的工具列表，可调用，协议上使用原始的 `read_file`。
-- 公开名称是会话历史和权限/配置表面的一部分；命名算法是由测试固定的 v1 契约，发布后变更即为破坏性变更。
+- 公开名称是会话历史和权限/配置表面的一部分；命名算法是由测试固定的 v1 约定，发布后变更即为破坏性变更。
 - `mcp__<serverName>__` 限定符在每个名称上消耗 token。已接受：描述和 JSON Schema 在工具定义 token 中占主导，而限定符换来了稳定标识、冲突隔离和 MCP 全局策略匹配模式（`mcp__*`、`mcp__github__*`）。
 - **MCP SDK 稳定性**：`@modelcontextprotocol/sdk` 仍在演进中；破坏性变更需要更新桥接。版本已固定，且该 SDK 被广泛采用（Claude Desktop、Cursor、VS Code），因此破坏性变更不太可能悄然发生。
 - **工具 schema 质量**：MCP 服务器可能暴露描述不佳的工具（模糊的描述、不完整的 JSON Schema）。harness 原样透传——垃圾进垃圾出；这是服务器作者的责任，不是桥接的。
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
index d50b2323e3..e3b225948a 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md
 2026-07-08-background-subagent-tasks.md: 679c57c3173a32b8cfccc6611b4ba74487e7f7e3
-2026-07-08-background-subagent-tasks.zh.md: 487943ab5cfe78226cde912854099fc56a5833a6
+2026-07-08-background-subagent-tasks.zh.md: c46f3925bc3334ff4cee79e4d9c95589e5361eaf
diff --git a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
index 487943ab5c..c46f3925bc 100644
--- a/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 [subagent seam](2026-06-21-subagent-capability-seam.md) 会返回 `SubagentRun`，但原先面向模型的工具会同步收集每一次运行。因此，各自独立的慢速委派要么一直占用父调用，要么按串行方式运行。
 
-subagent 需要与其他长时间运行的工具相同的启动、收集、列出、停止、归属、通知和清理行为，但不应采用进程流语义。子会话仍是详细记录；父级只需最终答案和任务状态。后台子级的存活时间还会超过启动它的工具调用，因此必须明确其取消和拥有者资源释放契约。
+subagent 需要与其他长时间运行的工具相同的启动、收集、列出、停止、归属、通知和清理行为，但不应采用进程流语义。子会话仍是详细记录；父级只需最终答案和任务状态。后台子级的存活时间还会超过启动它的工具调用，因此必须明确其取消和拥有者资源释放约定。
 
 ## 决策
 
@@ -16,7 +16,7 @@ subagent 需要与其他长时间运行的工具相同的启动、收集、列
 
 后台 subagent 使用[通用后台任务运行时](../architecture/2026-06-20-generic-long-running-tool-runtime.md)。`task_output`、`task_list` 和 `task_kill` 负责收集、列出、取消、完成通知和提示词引导；系统不提供 subagent 专用的配套工具。
 
-前台调用保留其同步契约：等待提供方启动和 `run.result`；仅当状态为 `completed` 时返回最终文本；将其他终止原因映射为出错的工具结果；并且始终在返回前释放该运行。
+前台调用保留其同步约定：等待提供方启动和 `run.result`；仅当状态为 `completed` 时返回最终文本；将其他终止原因映射为出错的工具结果；并且始终在返回前释放该运行。
 
 对于后台调用，工具会验证父级，并在调用 `ctx.tasks.start()` 前拒绝已中止的执行信号。任务运行时会在调用生产者启动器前，预检控制接口和拥有者清理。该启动器创建独立的 `AbortController` 并启动 `ctx.subagents.start()`；返回 id 之后，工具调用的信号不再拥有该子级。
 
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
index 105a9d3cfd..900fc9c374 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
 2026-07-08-self-referential-cordis-toolset.md: 29d331008d4111ae00147f2ddd19a628135339ac
-2026-07-08-self-referential-cordis-toolset.zh.md: 55013b774b4b6b371d9cbe6ac492b4e95500a7ff
+2026-07-08-self-referential-cordis-toolset.zh.md: d61ba794781226437a5d7499c20e5cd33119fe78
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
index 55013b774b..d61ba79478 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
@@ -18,13 +18,13 @@ vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节
 
 ### 三个工具
 
-| 工具 | 契约 |
+| 工具 | 约定 |
 |---|---|
 | `cordis_inspect` | 当前进程活跃运行时的只读报告，每个 `what` 值对应一个 Markdown 段落（省略 `what` 则输出全部段落）。`plugins` 列出全部存活 fiber，`temporary` 只列 `cordis_mount` 创建的临时 Plugin。精确 `name` 搭配 `what: "api"` 或 `what: "events"` 可收窄到一个带源码文档的目标。 |
 | `cordis_mount` | 立即在 `node:vm` 沙箱中把 `code` 作为异步 JavaScript 函数体求值，且不保存到任何位置。返回的 Plugin 挂在内部 `cordis-dynamic` 分组下，并用新的进程内 id（`dyn-1`、`dyn-2`……）跟踪。 |
 | `cordis_unmount` | 按 id 卸载一个 `cordis_mount` 临时 Plugin，并只在其自有工具、监听器、服务、定时器和其他 effect 完全停稳后返回。它不能删除 Loader、配置或已安装的 Plugin。 |
 
-`cordis_inspect` 的段落是 `services`（每个已提供的 ctx 服务及所属 fiber）、`plugins`（全部存活 Plugin fiber）、`tools`（模型可调用的工具）、`temporary`（`cordis_mount` 子集，包含 id、running／pending 状态、提供与等待的服务和生命周期）、`api`（活跃服务签名及其引用类型）和 `events`（harness 事件及分发模式和签名）。临时 Plugin 可跨后续 turn 保持活跃，并在 `cordis_unmount`、工具集卸载或 DSH 重启后消失；系统绝不会自动恢复它们。宽泛的 `api` 和 `events` 报告省略完整 JSDoc；精确 `name` 返回一个服务或事件及其原始 JSDoc。其他段落不能搭配 name，未知目标会失败，而 API 目标必须处于活跃状态。[生成的工具目录](../../../../docs/tool-catalog.md)完整呈现面向模型的调用契约。
+`cordis_inspect` 的段落是 `services`（每个已提供的 ctx 服务及所属 fiber）、`plugins`（全部存活 Plugin fiber）、`tools`（模型可调用的工具）、`temporary`（`cordis_mount` 子集，包含 id、running／pending 状态、提供与等待的服务和生命周期）、`api`（活跃服务签名及其引用类型）和 `events`（harness 事件及分发模式和签名）。临时 Plugin 可跨后续 turn 保持活跃，并在 `cordis_unmount`、工具集卸载或 DSH 重启后消失；系统绝不会自动恢复它们。宽泛的 `api` 和 `events` 报告省略完整 JSDoc；精确 `name` 返回一个服务或事件及其原始 JSDoc。其他段落不能搭配 name，未知目标会失败，而 API 目标必须处于活跃状态。[生成的工具目录](../../../../docs/tool-catalog.md)完整呈现面向模型的调用约定。
 
 ### 沙箱语义
 
@@ -32,9 +32,9 @@ vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节
 
 沙箱全局变量刻意精简：一个带标签的直写 `console`（在宿主 stdout/stderr 上输出 `[cordis:<id>] …`，这样在挂载调用之后很久才触发的监听器输出仍能落到用户可见的地方）、`harness.defineTool` / `harness.registerTool` 注册对、新 vm 上下文缺少的编码原语（`btoa`/`atob` 作为基于 `Buffer` 的宿主闭包——这是一个经过审批的例外，`Buffer` 本身从不暴露——加上 `TextEncoder`/`TextDecoder`），以及对被扣留的 Node API 的可调用陷阱（`require`、`setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`、`fetch`），这些陷阱会抛出一条重定向消息指明 cordis 替代方案。只有函数形态的全局变量才设陷阱；`process` 和 `Buffer` 保持 `undefined`，这样 `typeof` 特性探测保持惰性而不会引爆一个抛异常的访问器。
 
-挂载代码通过三道控制跨越 vm 边界。双 realm `instanceof` 同时识别宿主和 vm 对象。`harness.defineTool` 在宿主 realm 中重建输出 schema／投影器，将工具体返回值快照为宿主自有的 JSON，并让注册表在观测前强制执行[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)。挂载的插件接收的是一个白名单上下文门面，而非原始或透传的 `Context`；框架管道和以 context 为值的返回会被拒绝。服务读取需要声明 `inject`，保留 Cordis 的激活与卸载语义。`ctx.tools.get` 仅暴露 schema 视图，因此挂载代码无法绕过 `ToolRegistry.execute` 直接调用定义。
+挂载代码通过三道控制跨越 vm 边界。双 realm `instanceof` 同时识别宿主和 vm 对象。`harness.defineTool` 在宿主 realm 中重建输出 schema／投影器，将工具体返回值快照为宿主自有的 JSON，并让注册表在观测前强制执行[规范工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)。挂载的插件接收的是一个白名单上下文门面，而非原始或透传的 `Context`；框架管道和以 context 为值的返回会被拒绝。服务读取需要声明 `inject`，保留 Cordis 的激活与卸载语义。`ctx.tools.get` 仅暴露 schema 视图，因此挂载代码无法绕过 `ToolRegistry.execute` 直接调用定义。
 
-边界将无歧义的 JSON-Schema 形式规范化为 `ParameterSchemaSpec`，同时保留 `integer`、原始对象开放性和 required 数组。直接使用 DSL 的对象节点必须声明 `additionalProperties`；无效词汇会报错并给出可接受的替代方案。解析错误、TypeScript 错误、缺少 return、Node API 误用和重复工具名等错误信息包含相关源码行或纠正性契约，不叙述实现内部细节。
+边界将无歧义的 JSON-Schema 形式规范化为 `ParameterSchemaSpec`，同时保留 `integer`、原始对象开放性和 required 数组。直接使用 DSL 的对象节点必须声明 `additionalProperties`；无效词汇会报错并给出可接受的替代方案。解析错误、TypeScript 错误、缺少 return、Node API 误用和重复工具名等错误信息包含相关源码行或纠正性约定，不叙述实现内部细节。
 
 ### 内部分组与临时 Plugin 生命周期
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
index ece6f1a094..41a400987b 100644
--- a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md
 2026-07-10-agent-session-identity-and-log-location.md: 7b51ae41ac00c12a496940c891092580003646fa
-2026-07-10-agent-session-identity-and-log-location.zh.md: 46c7c1ce429d66741cffbdd87eb415b90cf32fb3
+2026-07-10-agent-session-identity-and-log-location.zh.md: b310db258f781cb5326e4bfe9e9daf3a6c1793e7
diff --git a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md
index 46c7c1ce42..b310db258f 100644
--- a/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md
@@ -60,9 +60,9 @@ bash 工具说明只讲解持久约定：当前 harness 环境事实通过受管
 
 ## 测试
 
-单元测试覆盖注册表声明校验、effect 释放、逐次执行收集、`dshHome` 优先级，以及本地执行器清理并重建 `DSH_*` 的顺序。请求录制测试覆盖前台／后台快照、无 agent 调用、持久化不存在或为 JSONL、忽略模型 `env`，以及父子隔离。JSONL／SQLite 定位器契约测试与两套钩子桥接测试均锁定 transcript 可用和不可用两种方言。
+单元测试覆盖注册表声明校验、effect 释放、逐次执行收集、`dshHome` 优先级，以及本地执行器清理并重建 `DSH_*` 的顺序。请求录制测试覆盖前台／后台快照、无 agent 调用、持久化不存在或为 JSONL、忽略模型 `env`，以及父子隔离。JSONL／SQLite 定位器约定测试与两套钩子桥接测试均锁定 transcript 可用和不可用两种方言。
 
-一项无密钥的完整循环集成测试会在第一个轮次驱动真实的 agent loop、JSONL 持久化、tool-bash 与 bash-local。子进程打印 `DSH_HOME`、`DSH_SHELL`、会话 id、JSONL 目标和继承的陈旧哨兵值；测试校验当前值、陈旧变量不存在、刷写前文件不存在，并最终检查持久化 header。快照测试会固定录制请求 header 中的通用 bash 说明。该契约属于确定性的本地执行，不涉及模型选择，因此无需带密钥测试。
+一项无密钥的完整循环集成测试会在第一个轮次驱动真实的 agent loop、JSONL 持久化、tool-bash 与 bash-local。子进程打印 `DSH_HOME`、`DSH_SHELL`、会话 id、JSONL 目标和继承的陈旧哨兵值；测试校验当前值、陈旧变量不存在、刷写前文件不存在，并最终检查持久化 header。快照测试会固定录制请求 header 中的通用 bash 说明。该约定属于确定性的本地执行，不涉及模型选择，因此无需带密钥测试。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
index 6462a2c873..9566e667f2 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
 2026-07-10-parallel-tool-call-execution.md: 7fd540539fd358b3254470f420a0cc11f2927d45
-2026-07-10-parallel-tool-call-execution.zh.md: 985557974c79d4080c4e35ccbb9740439988261a
+2026-07-10-parallel-tool-call-execution.zh.md: 278996fedb8c9dcc86916a1544535b1444b6e9f5
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
index 985557974c..278996fedb 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-每个工具都可以提供可选的 `isConcurrencySafe(args)` 分类器。该分类器必须是同步纯函数：它只检查当前调用已解析的参数，不执行 I/O 或任何变更。只有显式返回 `true` 才表示选择并行；分类器缺失、参数无效、分类器抛错或返回任何其他值，都会使该调用按独占方式执行。规范类型契约见[工具数据结构](../../../../docs/subsystems/tools.md)。
+每个工具都可以提供可选的 `isConcurrencySafe(args)` 分类器。该分类器必须是同步纯函数：它只检查当前调用已解析的参数，不执行 I/O 或任何变更。只有显式返回 `true` 才表示选择并行；分类器缺失、参数无效、分类器抛错或返回任何其他值，都会使该调用按独占方式执行。规范类型约定见[工具数据结构](../../../../docs/subsystems/tools.md)。
 
 分类器有意设计为一元函数。返回 `true` 表示工具承诺：此调用可以与任何同样返回 `true` 的并列调用重叠执行。调度器不会比较调用，也不会证明它们的资源访问相容。
 
@@ -22,7 +22,7 @@ Status: implemented
 
 `defineTool()` 先验证参数，再调用类型化分类器。无效参数会被归为独占，且只有该调用真正执行时才会产生常规参数错误。`ctx.tools.executionMode(exec)` 会解析当前有效的工具定义，并返回带标签的 `parallel` 或 `exclusive` 模式；未知工具将按安全侧原则归为独占。
 
-使用带标签的模式，而不是公开布尔型调度器 API，使得以后可以表达感知资源的变体，无需改变分类器契约。
+使用带标签的模式，而不是公开布尔型调度器 API，使得以后可以表达感知资源的变体，无需改变分类器约定。
 
 ## 调度与顺序
 
@@ -50,7 +50,7 @@ Status: implemented
 
 Code Mode 仍不使用此调度器，因为模型只会发出一个原生 `run_code` 调用。`run_code` 及其内部派发队列仍按串行方式执行；`mode: 'both'` 中的原生并列调用使用常规调度器。
 
-## 安全契约
+## 安全约定
 
 工具返回 `true` 即承诺：其主体可以与其他并行调用同时运行。它不得直接变更父会话或其他由父级拥有的状态；它将输出返回给循环，由循环按模型顺序提交。
 
@@ -78,7 +78,7 @@ Code Mode 仍不使用此调度器，因为模型只会发出一个原生 `run_c
 
 **使用有状态的分类。** 向分类器提供实时 agent、注册表或 I/O 访问，会使决策依赖分类器的运行时机，并在分类与派发之间留下缺口。可变授权和陈旧状态检查仍属于执行时职责。
 
-**使用感知并列调用或感知资源的分类。** 调度器可以成对比较调用，或让每个调用声明资源读写要求。这样可以并行化不冲突的写入，却要求不相关工具共享资源标识和冲突语义。一元契约选择放弃这部分并发性，并在安全性取决于调用间关系时按安全侧原则处理。
+**使用感知并列调用或感知资源的分类。** 调度器可以成对比较调用，或让每个调用声明资源读写要求。这样可以并行化不冲突的写入，却要求不相关工具共享资源标识和冲突语义。一元约定选择放弃这部分并发性，并在安全性取决于调用间关系时按安全侧原则处理。
 
 **并行执行完整的工具流水线。** 这样可以让循环继续使用公开的单调用 API，但会并发运行 pre-execute 和 post-execute 中间件。现有防护和钩子桥可能承载有序状态，因此只允许派发重叠。
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
index 8f5de6df71..55a4439855 100644
--- a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
 2026-07-10-sqlite-session-query-provider.md: 372c21241f9ae5d7300165f016db9b36e6b52855
-2026-07-10-sqlite-session-query-provider.zh.md: b0789f18f5f334b14fe603ee36924666705136f1
+2026-07-10-sqlite-session-query-provider.zh.md: f5f2d22a209350975a4ccff9a538a55dfc8ff71e
diff --git a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
index b0789f18f5..f5f2d22a20 100644
--- a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 精确读取的 `ctx.sessionQuery` 服务有意不维护派生索引。大规模持久化的历史记录需要全文搜索，而不是每次查询都扫描全部事件；当前的活跃会话则需要一个包含上次持久化检查点之后更新的覆盖层。搜索还需要具体的排序、摘要片段、过滤器、分页、取消以及重建行为。
 
-如果把这些关注点拆分到提供方协调器和数据库实现之间，就会产生两个耦合的对齐状态机。第一个实现既要暴露精简的提供方无关调用契约，也要在同一个生命周期内管理源观察、提取、SQLite 事务、代际与查询执行。
+如果把这些关注点拆分到提供方协调器和数据库实现之间，就会产生两个耦合的对齐状态机。第一个实现既要暴露精简的提供方无关调用约定，也要在同一个生命周期内管理源观察、提取、SQLite 事务、代际与查询执行。
 
 ## 决策
 
@@ -38,7 +38,7 @@ Status: implemented
 
 持久化文档在重启后仍然存在。实时会话使用连接本地的 TEMP 表，遮蔽相同 id 的持久化基础行，并在实时所有者分离时重新显露该基础行。关闭数据库会删除实时行。卸载持久化服务会隐藏持久化行，但不会把缺失视为权威删除；重新挂载后，系统会再次观察并对齐后端。实时会话头与持久化会话头的不可变字段发生冲突时，系统会失败，而不会合并两个来源。
 
-派生 schema 拥有独立的 application id 与单调递增的 schema 版本。持久化与 TEMP 会话元数据均遵循 `SessionHeader.createdAt` 的整数契约，将其存入严格的 `INTEGER` 列。系统识别到不兼容版本时，只会重置该派生数据库。如果数据库具有不属于本应用的 application id 或无法识别的用户表，系统会在修改日志模式前拒绝该数据库，防止意外配置的规范会话数据库遭到修改。在 POSIX 文件系统上，缺失的目录与数据库文件会以仅所有者可访问的权限创建，使新的 SQLite 伴随文件沿用该模式；现有权限模式保持不变。一个进程中的一个服务独占一条派生索引路径；代际与实时 TEMP 遮蔽状态都归连接所有，因此不支持跨进程写入方。
+派生 schema 拥有独立的 application id 与单调递增的 schema 版本。持久化与 TEMP 会话元数据均遵循 `SessionHeader.createdAt` 的整数约定，将其存入严格的 `INTEGER` 列。系统识别到不兼容版本时，只会重置该派生数据库。如果数据库具有不属于本应用的 application id 或无法识别的用户表，系统会在修改日志模式前拒绝该数据库，防止意外配置的规范会话数据库遭到修改。在 POSIX 文件系统上，缺失的目录与数据库文件会以仅所有者可访问的权限创建，使新的 SQLite 伴随文件沿用该模式；现有权限模式保持不变。一个进程中的一个服务独占一条派生索引路径；代际与实时 TEMP 遮蔽状态都归连接所有，因此不支持跨进程写入方。
 
 取消会使排队中的操作及时被拒绝。异步源观察一旦开始，调用方必须等待该后端 Promise 结算后才会收到拒绝；系统不会提交已中止的观察结果，也不会启动更多源观察或索引工作。Node 的同步 `DatabaseSync` 元数据与 MATCH 调用一旦开始在 JavaScript 线程上执行就无法中断，因此服务会在这些调用前后检查信号，但不承诺在语句执行期间抢占。
 
@@ -56,4 +56,4 @@ Status: implemented
 
 选定的分词器以较小的索引体积支持短 token，但不承诺子串召回。字面短语使查询语法安全且可预测，代价是不支持布尔表达式或完整 MATCH 表达式。取消在操作排队或等待数据源期间有效，但同步 SQLite 执行仍是不可抢占区段。
 
-单元测试将以下行为固化为契约：提取、过滤器、两种搜索范围、所有默认 surface、先过滤元数据再排序、摘要片段、字面量转义、确定性平局处理、完整分页、按范围的游标失效、动态挂载/卸载持久化服务、重启对齐、实时遮蔽、显露与重新打开、schema 安全、回滚重试，以及排队中或进行中的数据源等待取消。一个无需密钥的真实 Loader 路径测试会将该包与真实的 SQLite 持久化后端组合使用。
+单元测试将以下行为固化为约定：提取、过滤器、两种搜索范围、所有默认 surface、先过滤元数据再排序、摘要片段、字面量转义、确定性平局处理、完整分页、按范围的游标失效、动态挂载/卸载持久化服务、重启对齐、实时遮蔽、显露与重新打开、schema 安全、回滚重试，以及排队中或进行中的数据源等待取消。一个无需密钥的真实 Loader 路径测试会将该包与真实的 SQLite 持久化后端组合使用。
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
index b2e1785796..17cee6fc65 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md
 2026-07-12-subagent-persona-tool-filter-and-depth.md: 2c5eaf8829e01536a2de34cc190573ff35e4ab77
-2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: 355db26ecaf57137420798474561d6a7032757cb
+2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: ae64e26d95e42ca6c933892348e22d3cbf0dc722
diff --git a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
index 355db26eca..ae64e26d95 100644
--- a/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.zh.md
@@ -81,7 +81,7 @@ subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `ma
 
 **为每种人设或工具集创建一个提供方。** 这会使共享相同传输和生命周期实现的提供方成倍增加，使动态部署配置变得笨拙，且仍需要递归机制。提供方的职责是执行传输；请求承载每个子 agent 的组合。
 
-**复制父级的完整工具视图。** 注册作用域设计上是扁平的，生命周期所有权不意味着可见性继承。复制已解析视图还会冻结动态全局注册，并在未完整定义任一契约的情况下混淆组合与授权。
+**复制父级的完整工具视图。** 注册作用域设计上是扁平的，生命周期所有权不意味着可见性继承。复制已解析视图还会冻结动态全局注册，并在未完整定义任一约定的情况下混淆组合与授权。
 
 **在子 agent 创建时快照允许的全局工具。** 冻结的 allow 集合使未来注册统一不可用，但它改变了热注册语义并开启了授权设计。已实现的过滤器保持为活跃的注册表谓词，并直接记录 allow 与 deny 的行为。
 
diff --git a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml
index 80a1952578..f2d337c93c 100644
--- a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-13-session-query-tracing.md
 2026-07-13-session-query-tracing.md: 47c12824a331546676d3bc79920f861afe648431
-2026-07-13-session-query-tracing.zh.md: 88ff93048db0e763888ce6f7fee60918be3675a7
+2026-07-13-session-query-tracing.zh.md: f578a69a3004722395d5b731f82482b8ebd548e5
diff --git a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
index 88ff93048d..f578a69a30 100644
--- a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 ## 校验边界
 
-事件追踪会在分析表面之前检查目标是否存在。随后，事件列表与追踪都会使用 `dsh-session` 的单遍表面折叠，对加载的日志整体进行接受或拒绝：事件 seq 从零开始且连续；表面标记符合事件类型的适用范围；只有表面事件类型可以携带来源；存在的数组必须非空且没有重复项；每个来源必须是更早的 seq；每次位置替换必须指明并引用它所移除的全部表面节点。任何契约违例都使用 `SESSION_QUERY_INVALID_SURFACE`；系统不存在只用于分类、要求更弱的表面标准。
+事件追踪会在分析表面之前检查目标是否存在。随后，事件列表与追踪都会使用 `dsh-session` 的单遍表面折叠，对加载的日志整体进行接受或拒绝：事件 seq 从零开始且连续；表面标记符合事件类型的适用范围；只有表面事件类型可以携带来源；存在的数组必须非空且没有重复项；每个来源必须是更早的 seq；每次位置替换必须指明并引用它所移除的全部表面节点。任何约定违例都使用 `SESSION_QUERY_INVALID_SURFACE`；系统不存在只用于分类、要求更弱的表面标准。
 
 所有返回的记录与数组都与内部状态分离。已知的实时事件追踪绝不查询持久化；持久化事件追踪保留精确读取所要求的列表／加载一致性检查。会话谱系必然属于跨语料操作，因此也保留跨语料的持久化失败语义。
 
@@ -27,7 +27,7 @@ Status: implemented
 - **公开独立的追踪辅助函数**：不予采纳，因为源优先级与状态分离边界属于 `ctx.sessionQuery`；公开辅助函数会诱使调用方绕过该边界。
 - **合并替换边与来源边**：不予采纳，因为位置替换可以遮蔽表面节点，同时引用不在表面上的构造输入，而消费方需要区分这两种含义。
 - **返回传递来源闭包**：不予采纳，因为这会掩盖日志中直接记录的证据、增大结果，并让一条遥远的格式错误边改变原本局部的输出。
-- **在格式错误的来源关系上返回尽力而为的追踪结果**：不予采纳，因为结构上看似合理的局部图会显得具有权威性。当规范的关系契约损坏时，精确检查会明确报错。
+- **在格式错误的来源关系上返回尽力而为的追踪结果**：不予采纳，因为结构上看似合理的局部图会显得具有权威性。当规范的关系约定损坏时，精确检查会明确报错。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
index 9697abde6f..eac4c74cdc 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
 2026-07-14-cross-family-fs-sandbox.md: e8a59be345b52f7684c574134b37f48bc49843fc
-2026-07-14-cross-family-fs-sandbox.zh.md: f816bc88db3d7624892fb057e63dd5f24381275e
+2026-07-14-cross-family-fs-sandbox.zh.md: 228e156688ce23c10ac42b2c96b3737f796d4524
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
index f816bc88db..228e156688 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
@@ -49,7 +49,7 @@ Status: implemented
 
 ### 强制执行点：提供方，而非 intent gate
 
-沙箱 Agent Note 最初的跨家族草图把 fs 强制执行放在 `fs/write-intent`/`fs/edit-intent` 事件上。本 Agent Note 改为在提供方中强制执行，基于两个机制性事实:intent 槽是单决策、先到先得(已被 `dsh-fs-policy` 占据,其契约称第二个决策者为配置错误),且 intent 事件只由 `dsh-tool-fs` 派发——一个直连 `ctx.fs` 的调用方(一个 cordis 挂载插件、一个自定义工具)会绕过它们,而提供方级强制执行按构造覆盖每一个调用方。沙箱 Agent Note 的暂缓阶段措辞在同一变更中被更新以匹配。
+沙箱 Agent Note 最初的跨家族草图把 fs 强制执行放在 `fs/write-intent`/`fs/edit-intent` 事件上。本 Agent Note 改为在提供方中强制执行，基于两个机制性事实:intent 槽是单决策、先到先得(已被 `dsh-fs-policy` 占据,其约定称第二个决策者为配置错误),且 intent 事件只由 `dsh-tool-fs` 派发——一个直连 `ctx.fs` 的调用方(一个 cordis 挂载插件、一个自定义工具)会绕过它们,而提供方级强制执行按构造覆盖每一个调用方。沙箱 Agent Note 的暂缓阶段措辞在同一变更中被更新以匹配。
 
 ### 范围之外
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
index 3975b65602..d01c01c55a 100644
--- a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md
 2026-07-16-durable-per-step-time-context.md: e1a5c65894913ad93f46db8ae45e5ef5ead215f3
-2026-07-16-durable-per-step-time-context.zh.md: d353d2b4535cd2f6153adad084b4ca056f68dc8c
+2026-07-16-durable-per-step-time-context.zh.md: 129920a02dc21a91ddc92de3d920ddad24968656
diff --git a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
index d353d2b453..129920a02d 100644
--- a/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md
@@ -66,4 +66,4 @@ Elapsed since the preceding step context: <duration-or-unavailable>.
 - 省略 `refreshIntervalMs` 或设为 `0` 时，每次符合条件的准备尝试都会留下记录；正数间隔会减少追加频率和历史增长，同时使持久调度在恢复后继续生效。
 - 时间上下文仅追加并保留到压缩隐藏旧表层节点为止，其中也包括后续取消或失败所留下的准备读数。
 - 第一个步骤的时长通常从开启轮次的提示词起算，后续步骤的时长则反映自上一条步骤上下文以来的模型与工具处理时间。
-- 省略 `timeZone` 时仍采用部署进程而非远程用户的时区，时长仍采用 harness 的持久追加边界而非客户端来源时间戳。若要支持客户端来源的时间，需要另行建立持久输入契约。
+- 省略 `timeZone` 时仍采用部署进程而非远程用户的时区，时长仍采用 harness 的持久追加边界而非客户端来源时间戳。若要支持客户端来源的时间，需要另行建立持久输入约定。
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index 15d82777e1..3893ff403f 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
 2026-07-16-harness-level-loop.md: f37bea0842b3f40bf07c6660ad758d84ece23f1b
-2026-07-16-harness-level-loop.zh.md: 10f4cd2ac4991361261dd652d5d99dcb15d459be
+2026-07-16-harness-level-loop.zh.md: 8d61c36915c7a3b5e0fde94c4c0ba52ec48eddd1
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index 10f4cd2ac4..8d61c36915 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -88,7 +88,7 @@ Ralph 是位于自有插件中的一等模型工具，展示了复杂固定执
 
 Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天的持久目标，以及设置、查看、编辑、暂停、恢复与清除控制。本实现采用这种可发现性，但使用本仓库的事件溯源目标记录、插件作用域与运行时权限检查。
 
-当前 [Claude Code goals](https://code.claude.com/docs/en/goal) 进一步验证了“前一 Turn 后启动另一 Turn 的目标”和定时 `/loop` 之间的区别。Claude Code 还会在每个 Turn 后使用独立小模型评估器。本实现采用策略区分，但有意不复制该评估器：评估器输入、工具访问、确定性检查、provider 选择、隔离与权限需要单独设计的插件契约，而不是隐式自我认证层。
+当前 [Claude Code goals](https://code.claude.com/docs/en/goal) 进一步验证了“前一 Turn 后启动另一 Turn 的目标”和定时 `/loop` 之间的区别。Claude Code 还会在每个 Turn 后使用独立小模型评估器。本实现采用策略区分，但有意不复制该评估器：评估器输入、工具访问、确定性检查、provider 选择、隔离与权限需要单独设计的插件约定，而不是隐式自我认证层。
 
 外部产品只是比较对象，不是兼容目标。本地源码研究帮助确定边界，而交付接口遵循本仓库“一切皆插件”、模型可见内容均记入日志、显式解析默认值与完全停稳后拆卸规则。
 
@@ -109,7 +109,7 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 
 ## 后果
 
-- 目标式执行在没有单个过载「loop」对象的情况下交付：同会话续行与全新 agent 迭代拥有显式、可独立测试的契约。
+- 目标式执行在没有单个过载「loop」对象的情况下交付：同会话续行与全新 agent 迭代拥有显式、可独立测试的约定。
 - 持久目标历史可以重放和 fork，而进程本地激活态会防止恢复时意外开始工作。
 - 人类获得小型 Codex 形态 UX；模型获得紧凑、带来源检查的工具表面；部署可以独立移除任一能力。
 - Ralph 展示了非平凡固定策略可以完全作为现有 workflow 与 subagent 原语之上的插件实现。
@@ -118,7 +118,7 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 
 ## 已知限制与暂缓事项
 
-- **独立评估**——同会话完成/阻塞和 Ralph 终止状态都是模型或工作者声明。独立评估器、评估器驱动反馈 Round、完成证书、确定性检查器、对抗式 verifier 与 criteria/executor/isolation 契约均予以延期。
+- **独立评估**——同会话完成/阻塞和 Ralph 终止状态都是模型或工作者声明。独立评估器、评估器驱动反馈 Round、完成证书、确定性检查器、对抗式 verifier 与 criteria/executor/isolation 约定均予以延期。
 - **聚合预算**——`maxGoalRounds` 与 Ralph `maxRounds` 是唯一聚合工作量限制。token、货币、耗时、provider 用量与逐 Round 价格准入策略均不存在。
 - **没有持久自治运行器**——同会话目标事实会持久化，但激活与调度只存在于进程内，并且有意在恢复后等待人类输入。Ralph 位于前台，进程丢失后无法恢复。后台收集、重启恢复与无人值守常驻执行均予以延期。
 - **没有时间调度器**——间隔 `/loop`、cron、主动维护以及云端或桌面调度不在本决策范围内。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 7756f7803c..f41c42e700 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
 2026-07-16-persistent-pty-sessions.md: 219f48235d527cffbf66020ceb22e80ca473093d
-2026-07-16-persistent-pty-sessions.zh.md: 18b81cd6a8d3f9cdbaa8566e1b166c3877ae8742
+2026-07-16-persistent-pty-sessions.zh.md: c3842936248fb2d1705708dfd694be563ce2adf9
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index 18b81cd6a8..c384293624 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -22,7 +22,7 @@ harness 可以运行前台与后台命令、编辑文件和委派工作，但无
 
 | 包 | 角色 | ctx key |
 |---|---|---|
-| `dsh-pty` | `PtyService`、branded `PtySessionId`、后端注册表、按 owner 隔离的会话契约和结果类型 | `ctx.pty` |
+| `dsh-pty` | `PtyService`、branded `PtySessionId`、后端注册表、按 owner 隔离的会话约定和结果类型 | `ctx.pty` |
 | `dsh-pty-local` | 基于 `ctx.subprocess.spawnTerminal()` 的持久 shell 后端：就绪状态、有界终端缓冲、沙箱解析和感知 owner 的会话生命周期 | 在 `ctx.pty` 上注册后端 |
 | `dsh-tool-pty` | 6 个面向模型的工具、后台发送的 task 运行时集成、使用指引和 UI 渲染意图 | 注册到 `ctx.tools` |
 
@@ -58,7 +58,7 @@ agent scope dispose 时先关闭注册，再等待全部所属 PTY 静默退出
 | `terminal_close` | 关闭一个会话并等待进程树静默退出 | `{ killed }` |
 | `terminal_list` | 列出调用方的活会话 | 按 owner 隔离的会话摘要 |
 
-UI 渲染契约精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
+UI 渲染约定精确且不携带位置信息。`terminal_send` 只为前台发送使用 terminal 调用卡片和结果卡片；后台形式使用通用 `execute` 卡片。`terminal_open`、`terminal_read`、`terminal_signal`、`terminal_close` 和 `terminal_list` 分别使用通用 `execute`、`read`、`execute`、`delete` 和 `read` 卡片。所有 PTY 工具都不发出 `locations`。
 
 `terminal_send({ sessionId, text, submit?, run_in_background? })` 将 `text` 视为 UTF-8 字节，并由工具实现在解析阶段把 `submit` 默认成 `true`。`submit` 为 true 时先写入文本，再写入平台 Enter 序列；为 false 时只写文本，使控制字符和 REPL 片段无需隐藏的内容启发式即可发送。取消会在向真实前台进程组发送信号前将排队输入标记为已取消，因此即使异步的写入前检查随后才结算，该输入也无法执行。被取消的发送会保留其预留，直至异步前台信号发送结算，因此后续发送不会成为该信号的目标。`enableRunInBackground` 默认为 true；设为 false 时，schema 中会移除 `run_in_background`，调用方即使强行把这个未声明参数传入执行流程，也会被拒绝。
 
@@ -88,7 +88,7 @@ Tier 2 在持续 `idleSilenceMs` 没有输出后返回 `inferred_idle`，因此
 
 现有持久化 `tool/call` 与 `tool/result` 事件是模型发送文本和返回给模型的渲染输出的真源。`terminal_open` 通过已记录的工具结果返回 MOTD；前台 `send`/`read`/`list`/`signal`/`close` 结果走同一路径记录。PTY 包不会把原始字节流重复写入自定义会话事件。
 
-后台发送复用现有后台任务完成通知和 `task_output` 结果路径，因此进入后续模型请求的任何输出同样持久化。原始终端字节只作为有界的进程内状态存在，既不持久化也不可恢复。未来的 opt-in transcript sink 必须拥有独立的保留、凭证和隐私契约。
+后台发送复用现有后台任务完成通知和 `task_output` 结果路径，因此进入后续模型请求的任何输出同样持久化。原始终端字节只作为有界的进程内状态存在，既不持久化也不可恢复。未来的 opt-in transcript sink 必须拥有独立的保留、凭证和隐私约定。
 
 ### 进程树 teardown
 
@@ -130,7 +130,7 @@ plugins:
 
 ### 推迟的工作
 
-- 全屏 TUI 支持、命名按键序列、BEL 中断、终端 resize 工具和 alternate-screen 快照需要另行验证面向模型的契约。
+- 全屏 TUI 支持、命名按键序列、BEL 中断、终端 resize 工具和 alternate-screen 快照需要另行验证面向模型的约定。
 - 声明式 per-agent 启动需要 agent-setup 组合点；仍然禁止插件加载期全局会话。
 - harness 进程丢失后的会话恢复需要进程外 owner 和版本化协议。
 - 网络出口策略与外部副作用回滚超出 PTY 范围，继续作为独立安全工作。
@@ -138,9 +138,9 @@ plugins:
 
 ## 备选方案
 
-**用 PTY 替换 `bash`、文件系统工具或 task 工具。**拒绝。一次性工具拥有更强的校验、审批、沙箱、输出上限和回放契约。PTY 只服务交互式状态。
+**用 PTY 替换 `bash`、文件系统工具或 task 工具。**拒绝。一次性工具拥有更强的校验、审批、沙箱、输出上限和回放约定。PTY 只服务交互式状态。
 
-**给 `bash` 增加持久模式。**拒绝。按就绪而不是进程退出返回、跨调用保留进程树、暴露交互式 stdin 会形成不同的所有权和失败契约。
+**给 `bash` 增加持久模式。**拒绝。按就绪而不是进程退出返回、跨调用保留进程树、暴露交互式 stdin 会形成不同的所有权和失败约定。
 
 **要求从 `node-pty` 获取原生 master fd。**拒绝。它的公共 API 不暴露 master fd。本地子进程终端适配器改为从受支持的 OS 进程元数据推导前台组与子孙进程，并把不可读元数据视为 detector miss。
 
@@ -148,7 +148,7 @@ plugins:
 
 **发布可替换注册表 `PtyIdleDetector`。**拒绝。基底专用的前台事实来自挂载的终端进程原语，提示符／静默就绪判定则仍是 `dsh-pty-local` 内部的一项私有策略。替换文件系统／子进程执行环境就是所需扩展点。
 
-**新增 PTY 专用 `sleep` 工具。**拒绝。`ctx.tasks` 已经拥有有界等待、取消、完成通知和面向模型的收集。第二套通用唤醒机制会跨越 agent loop（智能体循环）边界并重复该契约。
+**新增 PTY 专用 `sleep` 工具。**拒绝。`ctx.tasks` 已经拥有有界等待、取消、完成通知和面向模型的收集。第二套通用唤醒机制会跨越 agent loop（智能体循环）边界并重复该约定。
 
 **包含 TUI sequence 与 BEL 处理。**拒绝。源 prototype 将这些路径视为 timing-sensitive，且仍记录未解决的 alternate-screen 和交互失败。行式 PTY 已能证明核心价值，无需把未经验证的行为放进基础层。
 
@@ -160,12 +160,12 @@ plugins:
 - 子进程 fixture 覆盖非 leader 与非主线程的 stdin 等待、僵尸进程完全停稳、不可读进程状态、受支持的 syscall 表、不支持的架构和误报拒绝；同一单元测试套件通过注入覆盖 macOS 检查器逻辑。
 - 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合。ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。
-- 包契约、架构图、子系统页面、生成目录和 website API 描述同一个已发布接口。
+- 包约定、架构图、子系统页面、生成目录和 website API 描述同一个已发布接口。
 - 仓库 CI 等价序列负责类型、lint、覆盖率、快照、文档、构建、hygiene、demo 和 built-entry 验证。
 
 ## 后果
 
-**无需削弱一次性工具即可获得持久终端状态。**Shell 与 REPL 状态可以跨工具调用保留，而 `bash`、`read`、`write` 和 `edit` 继续拥有更窄的校验、审批与回放契约。
+**无需削弱一次性工具即可获得持久终端状态。**Shell 与 REPL 状态可以跨工具调用保留，而 `bash`、`read`、`write` 和 `edit` 继续拥有更窄的校验、审批与回放约定。
 
 **Linux Tier 1 之外的 idle 都是启发式结果。**输出静默无法区分 prompt、sleep 和网络 I/O。类型化结果保留不确定性，有界 timeout、task 等待与信号让模型仍能掌握控制权。
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
index 26b8332442..2e02bddec1 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
 2026-07-19-fresh-agent-ralph-workflow-tool.md: 6fe96587c49ef0316d1618fda2ee26b015b1ce87
-2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 03e5e4a705674b49c14cbb456b06d82fbd38f013
+2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 7cd3cf388f9d1e03390dd08ed045562bcfeb1f4d
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
index 03e5e4a705..7cd3cf388f 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
@@ -52,7 +52,7 @@ Ralph 插件的 `subagentProvider` 默认为 `spawn`。每次调用前，它要
 
 - **把 Ralph 放进同会话目标驱动器** — 拒绝，因为 Goal Round 有意保留同一段对话，而 Ralph 的定义性属性是每个 Round 使用全新上下文；合并两者会让目标生命周期与子 agent 编排无法分离。
 - **在通用工作流工具上暴露 `fresh` 或循环标志** — 拒绝，因为模型编写的脚本表面应保持通用且与提供方无关；Ralph 的固定报告协议和停止策略值得拥有一个可评审消费方。
-- **为了方便重放而使用 `subagent_fork`** — 拒绝，因为继承的已完成轮次是隐式、不断增长的交接状态，并违反全新上下文契约。工作区加一份结构化报告即可重放，无需插入人为取消记录。
+- **为了方便重放而使用 `subagent_fork`** — 拒绝，因为继承的已完成轮次是隐式、不断增长的交接状态，并违反全新上下文约定。工作区加一份结构化报告即可重放，无需插入人为取消记录。
 - **让工具直接调用 subagent seam** — 拒绝，因为现有工作流引擎已经拥有前台编排、结构化子 agent、取消传播、工作线程终止、事件和完全停稳后的 dispose。复用它可以展示插件组合，而不是构建第二个循环运行时。
 - **静默截断大型报告** — 拒绝，因为截断可能删除状态证据或下一步，却仍看似权威交接。生产者必须在配置边界内发出有效报告。
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
index 689b04ef55..5b39ad725e 100644
--- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-human-goal-command.md
 2026-07-19-human-goal-command.md: 5fdd80f7423b80e84e58f7379130ee59a2e8a723
-2026-07-19-human-goal-command.zh.md: 841e7195454b2e0cfc6f74fb28369022b84c5780
+2026-07-19-human-goal-command.zh.md: 89d29497abfc758ff8373d272aa8620ca1bcfcc2
diff --git a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
index 841e719545..89d29497ab 100644
--- a/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-human-goal-command.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 `/goal <objective>` 创建活跃且已激活的目标。已完成目标可以被替换，此时通过现有领域规则创建新的目标身份。任何未完成目标都会让命令直接失败，并提示用户使用行内编辑或明确清除。通用命令服务有意不提供模态确认 API；若静默执行清除再创建两条持久记录，就等于凭空制造破坏性同意，并暴露一个非原子的失败窗口。
 
-`/goal edit <objective>` 编辑当前未完成目标，但不改变其阶段或激活态。若目标已经完成，则创建一个新的活跃目标，因为领域不允许恢复已完成状态，而新的目标描述应拥有新的目标身份。单独使用 `edit` 会返回错误而不是启动编辑器，因为可移植的非结构化命令契约没有模态编辑器。
+`/goal edit <objective>` 编辑当前未完成目标，但不改变其阶段或激活态。若目标已经完成，则创建一个新的活跃目标，因为领域不允许恢复已完成状态，而新的目标描述应拥有新的目标身份。单独使用 `edit` 会返回错误而不是启动编辑器，因为可移植的非结构化命令约定没有模态编辑器。
 
 `/goal pause`、`/goal resume` 与 `/goal clear` 使用当前视图调用相应的比较并交换领域动词。恢复既适用于停止的持久阶段，也适用于会话恢复、fork 或驱动器替换后处于活跃但未激活状态的目标。领域规则仍会拒绝已耗尽的 Round 上限、对已活跃且已激活目标的重复恢复、非法阶段转换与陈旧身份。清除会移除当前指针，而会话日志保留带修订号的墓碑和此前快照。
 
@@ -50,10 +50,10 @@ TUI 应用包作出相反的产品选择。它默认让 `goals` 使用所有者
 
 - **让模型把 `/goal` 当作普通文本处理**——不予采纳，因为状态与直接生命周期操作会消耗模型轮次、可能被重新解释，也无法提供确定性的命令发现。
 - **在各 UI 中分别实现处理器**——不予采纳，因为语法、错误行为与目标状态格式会发生偏差，可选部署也无法把该功能作为一个 effect 统一增删。
-- **为 `ctx.commands` 添加模态编辑与替换确认**——不予采纳，因为现有跨界面契约是非结构化输入加直接输出；通用交互协议所需的设计远超这一个生产方。
+- **为 `ctx.commands` 添加模态编辑与替换确认**——不予采纳，因为现有跨界面约定是非结构化输入加直接输出；通用交互协议所需的设计远超这一个生产方。
 - **静默替换未完成目标**——不予采纳，因为这会在没有原子性或明确破坏性意图的情况下组合清除与创建。
 - **在人类状态中暴露目标 id 与修订号**——不予采纳，因为人类操作始终在一个同步处理器内针对确切的当前视图；这些字段只会增加实现噪声，无法避免另一处竞态。
-- **在无 UI 主干中无条件启用目标**——不予采纳，因为单次 SDK/CLI 的结束契约是物理轮次 API，而不是目标操作 API。
+- **在无 UI 主干中无条件启用目标**——不予采纳，因为单次 SDK/CLI 的结束约定是物理轮次 API，而不是目标操作 API。
 
 ## 后果
 
@@ -61,12 +61,12 @@ TUI 应用包作出相反的产品选择。它默认让 `goals` 使用所有者
 - 人类状态会区分持久阶段与实时激活态，并报告准确的目标 Round 上限。
 - 直接暂停、恢复、清除、创建与编辑不消耗模型轮次，而其已接受变更仍可从会话日志重建。
 - 恢复后的会话等待人类决策；`/goal resume` 是字面命令路径，任何语言的普通提示词则可以授权模型工具路径。
-- 无头组合保持单轮行为，除非明确选择加入目标并定义自己的长时间运行结束契约。
+- 无头组合保持单轮行为，除非明确选择加入目标并定义自己的长时间运行结束约定。
 
 ## 已知限制与暂缓事项
 
-- 可移植命令契约没有模态编辑器或确认交互；在出现通用跨界面交互原语之前，行内编辑与明确清除是有意选择。
+- 可移植命令约定没有模态编辑器或确认交互；在出现通用跨界面交互原语之前，行内编辑与明确清除是有意选择。
 - `/goal` 不接受逐命令 Round 上限。部署配置拥有默认值；得到直接人类指示后，已授权模型工具可以编辑上限。
 - TUI 渲染可移植纯文本，而不是持续更新的目标状态组件。可重连命令输出和适配器专用状态指示器予以延期。
 - ACP 自动化服务器、无头 CLI 与 JSON-RPC 前端不消费命令注册表。
-- 该命令观察并改变状态，但不认证完成或阻塞。基于评估器的认证延期到具有明确权限与隔离契约的独立策略层。
+- 该命令观察并改变状态，但不认证完成或阻塞。基于评估器的认证延期到具有明确权限与隔离约定的独立策略层。
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
index debd2094e0..730de18a5a 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
 2026-07-19-model-facing-goal-tools.md: 0271194a38503711de77290c915010c26a9de74b
-2026-07-19-model-facing-goal-tools.zh.md: 235c3c5369871a8cdf731eee822abc4a3e6b58d1
+2026-07-19-model-facing-goal-tools.zh.md: 097aaa3b160a394ff3d13681be04dd19c7856ebc
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
index 235c3c5369..097aaa3b16 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 位于 `packages/goal/tool-goal/` 的 `@deepseek-ai/dsh-tool-goal` 在 `ctx.goals` 之上贡献三个独占工具和一个系统提示词策略段：`get_goal`、`create_goal` 与 `update_goal`。工具名称和读取—创建—更新形态遵循 Codex 的紧凑目标工具表面，而权限规则使用本仓库公共的 agent（智能体）、会话、工具与目标 seam。
 
-### 工具与模型契约
+### 工具与模型约定
 
 `get_goal()` 返回当前目标或 `null`。非空结果包含用于比较并交换的 id 与修订号、目标描述、持久阶段、已接纳和最大 Goal Round 数、可能存在的阻塞原因，以及进程本地激活态观察。`create_goal(objective, max_goal_rounds?)` 创建一个长时间运行的同会话目标。`update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` 支持 `edit`、`pause`、`resume`、`complete` 和 `blocked`；替换字段仅对 `edit` 有效，非空的 `blocked_reason` 仅在 `blocked` 时必填，并以稳定代码 `model-reported` 持久化。执行器把值恰好为空字符串的可选字段和值为 0 的 `max_goal_rounds` 视为严格 schema 占位值：这些值等同于省略；编辑时仍必须提供至少一个有实际意义的替换字段；所有非占位值仍受对应操作的限制。
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
index e58d618cf3..26dde53462 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md
 2026-07-19-plugin-command-registration.md: c8f0f2772a41948e9eb257a16f40194518c568f9
-2026-07-19-plugin-command-registration.zh.md: 94853393f5f71b29cfbd8da5443b3d73ded20e92
+2026-07-19-plugin-command-registration.zh.md: a8f7a3d1e7947aeb41344a72106cee55d249010c
diff --git a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
index 94853393f5..a8f7a3d1e7 100644
--- a/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.zh.md
@@ -14,7 +14,7 @@ TUI 拥有斜杠命令。如果命令名、帮助文本、自动补全、分派
 
 位于 `packages/interaction/commands/` 的 `@deepseek-ai/dsh-commands` 是产品命令注册表。TUI 应用 bundle（组合包）把它挂载在消费该服务的入口旁；[仅面向自动化的 ACP（Agent Client Protocol）应用](../simplification/2026-07-23-acp-automation-only-protocol.md)和无执行器、无 UI 的智能体 spine（主干）都省略该服务。TUI 注入该服务，命令生产者只依赖注册表及其操作的领域。
 
-### 注册表契约
+### 注册表约定
 
 `CommandDefinition` 包含不带 `/` 的小写名称、非空描述、可选的非结构化输入提示，以及可取消处理器。注册会校验元数据并复制一份与调用方脱离的副本、冻结最终生效的定义，并返回对应 Cordis effect 的精确 disposer（资源释放器）。同一层中的重复名称会失败。每个消费方都能看到所有有效定义；若命令插件无法在某种部署中运行，它就不在该部署中注册，而不是把消费方身份编码进共享领域。
 
@@ -30,7 +30,7 @@ TUI 拥有斜杠命令。如果命令名、帮助文本、自动补全、分派
 
 ### 直接分派与取消
 
-命令在仅面向人类的命令平面中运行。注册表不会把输入转成 `user/message`，输出不会成为会话事件，两者都不会隐式发送给模型。处理器接收对应的同一个目标 agent、原始输入和本次请求持有的 `AbortSignal`；生产者可以通过该智能体显式调度单独的模型可见工作，随后由生产者负责其日志记录和生命周期契约。信号中止时，注册表不再等待不合作的处理器；处理器仍负责停止已经启动的外部副作用。
+命令在仅面向人类的命令平面中运行。注册表不会把输入转成 `user/message`，输出不会成为会话事件，两者都不会隐式发送给模型。处理器接收对应的同一个目标 agent、原始输入和本次请求持有的 `AbortSignal`；生产者可以通过该智能体显式调度单独的模型可见工作，随后由生产者负责其日志记录和生命周期约定。信号中止时，注册表不再等待不合作的处理器；处理器仍负责停止已经启动的外部副作用。
 
 预期的处理器失败返回 `CommandResult.error`。抛出的异常或格式错误的结果仍是适配器可见的命令失败，而不是模型消息。该边界有意分离 UI 输出与持久领域变更：例如目标命令可以改变 `ctx.goals`，但持久状态由目标服务拥有。
 
@@ -58,7 +58,7 @@ TUI 测试覆盖全部迁移后的内置命令、实时插件发现、帮助与
 
 ## 后果
 
-- 命令生产者是普通的可移除插件，TUI 消费其经过校验的目录与分派契约。
+- 命令生产者是普通的可移除插件，TUI 消费其经过校验的目录与分派约定。
 - 智能体特定定义保留现有扁平作用域与遮蔽语义，不引入核心到 UI 的依赖。
 - 未知斜杠输入与命令输出是确定性 UI 行为，直接模型 token 成本为零。
 - 直接命令取消与模型轮次取消彼此隔离。
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
index 0af24062f6..900165a080 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
 2026-07-20-code-mode-typed-tool-returns.md: 2081d8161f0ee14493a09762b18ec7d9d07ea3c4
-2026-07-20-code-mode-typed-tool-returns.zh.md: 49d7a73f7f37d562fcbec2923d98ffa5ced97f68
+2026-07-20-code-mode-typed-tool-returns.zh.md: 808f8f96dbb1655dc00d1ccd9bb7f7ac93c9550f
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
index 49d7a73f7f..808f8f96db 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
@@ -10,13 +10,13 @@ Code Mode 过去会把每个嵌套工具的结果从 `ContentBlock[]` 重新投
 
 运行时还把绑定值和程序最终返回值当作展示数据。日志和完成值分别设置上限，导致过大或无法克隆的完成值可能被替换为检查后生成的文本，而中间值本来就不会进入模型上下文。这种设计使程序化组合产生信息损失，也混淆了内存边界与提示词边界。
 
-[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)确立了单一、经过校验的执行期值，并将 Native 渲染器与之分离。Code Mode 应直接消费该值，在跨越 worker 边界时完整保留它，并且只限制程序有意返回给模型的最终输出。
+[规范工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)确立了单一、经过校验的执行期值，并将 Native 渲染器与之分离。Code Mode 应直接消费该值，在跨越 worker 边界时完整保留它，并且只限制程序有意返回给模型的最终输出。
 
 ## 决策
 
 Code Mode 是可见工具注册表的类型化投影。每个成功的绑定调用都会解析为 post-execute 策略处理后的最终规范 `JsonValue`，失败的绑定调用则会以真正的 `ToolCallError` 拒绝 Promise。中间值只存在于本次运行中，并完整跨越 worker 边界。只有外层 `run_code` 的日志、完成值或失败诊断会进入可配置的输出账本以及面向模型的输出落盘流水线。
 
-本文档定义叠加在原始 [Code Mode 基础](2026-06-15-code-mode.md)之上的返回值与失败契约。统一 schema 词汇由 [JSON 值 schema DSL Agent Note](../architecture/2026-07-20-unified-json-value-schema-dsl.md)负责定义；Native 渲染与策略投影仍由规范输出 Agent Note 负责定义。
+本文档定义叠加在原始 [Code Mode 基础](2026-06-15-code-mode.md)之上的返回值与失败约定。统一 schema 词汇由 [JSON 值 schema DSL Agent Note](../architecture/2026-07-20-unified-json-value-schema-dsl.md)负责定义；Native 渲染与策略投影仍由规范输出 Agent Note 负责定义。
 
 ### 生成的 SDK
 
@@ -51,7 +51,7 @@ declare const tools: {
 
 分发前，桥接层会把绑定参数快照为无损 JSON，再对分离后的值生成一次快照，供独立的持久摘要事件使用。宿主侧的值分离、执行数据的不可变处理与输出 schema 投影均采用迭代遍历，而不使用嵌套结构化克隆或递归冻结。`undefined`、非有限数、`-0`、稀疏数组、循环引用、函数和非普通对象都会使该调用在工具运行前被拒绝。成功分发会返回 `ToolExecutionResult.value`；Native `content`、元数据和内部错误信息不会传入程序。
 
-Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProperty: "toolName" }` 声明其以异常拒绝 Promise 的能力。运行时 seam 只把这些名称视为数据：worker 会动态生成并注入真正用于 `tools` 绑定失败的构造函数，因此无需让通用运行时了解工具，`error instanceof ToolCallError` 也能成立。worker 使用模块初始化时捕获的 Error 构造函数与属性定义内建方法，配合原型为 null 的属性描述符，构造失败对象并定义其公开字段，因此模型代码的修改不会把契约承诺的 reject 变成 worker 失败。该错误包含标准的 `Error` 消息和确切的 `toolName`，并有意省略 `ToolFailure.info`、错误代码与 Native 内容。这是一项用于控制流的异常契约，而不是供程序分类的失败联合。
+Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProperty: "toolName" }` 声明其以异常拒绝 Promise 的能力。运行时 seam 只把这些名称视为数据：worker 会动态生成并注入真正用于 `tools` 绑定失败的构造函数，因此无需让通用运行时了解工具，`error instanceof ToolCallError` 也能成立。worker 使用模块初始化时捕获的 Error 构造函数与属性定义内建方法，配合原型为 null 的属性描述符，构造失败对象并定义其公开字段，因此模型代码的修改不会把约定承诺的 reject 变成 worker 失败。该错误包含标准的 `Error` 消息和确切的 `toolName`，并有意省略 `ToolFailure.info`、错误代码与 Native 内容。这是一项用于控制流的异常约定，而不是供程序分类的失败联合。
 
 绑定参数与绑定返回值会在不可信 worker 协议的两端重新校验为无损 JSON，且不设字节上限。每个分离后的值在通过结构化克隆跨越边界前，都会编码为扁平的前序 token 流，其传输结构的嵌套深度有界；接收方再以迭代方式重建该值。因此，有效应用数据的嵌套深度既不受 JavaScript 调用栈深度上限限制，也不受特定平台对嵌套结构化克隆施加的上限限制。模块初始化时，worker 会捕获自身 JavaScript 运行域中 `Array.prototype` 和 `Object.prototype` 的引用、仅用于识别其他运行域普通容器原型、可获取原生函数源码的内建函数，以及 JSON 边界用于结构处理和计量的全部内建方法。属性写入使用原型为 null 的属性描述符；内部的数组与集合操作直接调用捕获的方法，不会访问可变的全局或原型槽位。因此，即使模型代码替换 `Object.keys`、`Array.isArray`、集合方法、字符串方法或 `Buffer.byteLength` 等辅助方法，重写内建原型的构造函数槽位，或向 `Object.prototype` 添加形如属性描述符的字段，也不会改变校验、协议传输或字节计量。面向其他运行域的原生函数源码检查仍会拒绝由用户编写、冒充 `Object` 或 `Array` 的构造函数。为保持依赖轻量，运行时 seam 将结构等价类型命名为 `CodeJsonValue`，从而无需依赖会话侧拥有的规范类型；生成的 SDK 和工具 API 则使用 `JsonValue`。这些值不会经过提示词截断、上下文输出落盘或持久化。因此，程序可以完整筛选已经采集的搜索、工作流、任务、文件系统与 MCP 值，同时提供方和执行器的采集上限仍会实际生效。
 
@@ -67,7 +67,7 @@ Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProper
 
 ### 类型化句柄与生命周期
 
-后台 producer 返回类型化的规范句柄，例如 `{ kind: 'background', taskId }`，同时保留既有的 Native 语句。已预先中止的后台调用仍是失败，因为成功输出承诺返回 id，而此时并未创建任务。`ctx.tasks.start()` 发布 id 后，工作由任务自有的取消机制控制：外围 `run_code` 调用完成，或随后被取消，都不会终止该任务。后续程序可以把返回的 id 传给 `task_output`；任务取消则由 `task_kill`、所有者的 dispose（资源释放）或服务 teardown（拆卸）流程负责。前台执行仍与本次调用的信号耦合。任务生命周期契约由[后台任务运行时 Agent Note](../architecture/2026-06-20-generic-long-running-tool-runtime.md)定义。
+后台 producer 返回类型化的规范句柄，例如 `{ kind: 'background', taskId }`，同时保留既有的 Native 语句。已预先中止的后台调用仍是失败，因为成功输出承诺返回 id，而此时并未创建任务。`ctx.tasks.start()` 发布 id 后，工作由任务自有的取消机制控制：外围 `run_code` 调用完成，或随后被取消，都不会终止该任务。后续程序可以把返回的 id 传给 `task_output`；任务取消则由 `task_kill`、所有者的 dispose（资源释放）或服务 teardown（拆卸）流程负责。前台执行仍与本次调用的信号耦合。任务生命周期约定由[后台任务运行时 Agent Note](../architecture/2026-06-20-generic-long-running-tool-runtime.md)定义。
 
 临时 Cordis Plugin 遵循同一规则：`cordis_mount` 返回 `{ id, pluginName, state, provides, waitingFor }`，因此程序可以直接读取 `mounted.id`，检查 active 或 pending 状态，并把该 id 传给 `cordis_unmount`，无需解析稳定的 Native 语句。
 
@@ -85,11 +85,11 @@ Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProper
 
 ## 考虑过的替代方案
 
-**返回 Native 文本并附加可选 JSON：**不予采纳。程序会面对两套相互竞争的成功契约；可选值不存在时，仍需使用工具专属的解析规则。规范值才是 API；Native 内容只是它的展示。
+**返回 Native 文本并附加可选 JSON：**不予采纳。程序会面对两套相互竞争的成功约定；可选值不存在时，仍需使用工具专属的解析规则。规范值才是 API；Native 内容只是它的展示。
 
 **让每个绑定返回成功／失败联合：**不予采纳。失败没有稳定的程序化分类体系。reject 保留普通的 `try`／`catch` 控制流，并且只暴露工具名与可供人阅读的消息。
 
-**限制每个中间绑定值：**不予采纳。中间值不会进入模型上下文，任意截断会破坏程序化组合。明确的边界仍是生产方的采集契约与进程内存。
+**限制每个中间绑定值：**不予采纳。中间值不会进入模型上下文，任意截断会破坏程序化组合。明确的边界仍是生产方的采集约定与进程内存。
 
 **静默检查格式化或截断过大的完成值：**不予采纳。把 JSON 值改成字符串既有损又违反类型。显式的 `output-limit` 失败让模型可以选择返回更小的结果，而保留的日志和诊断仍可使用普通的外层输出落盘机制。
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index 0cf926921b..50196335f2 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
 2026-07-20-dsh-cli-personal-config.md: c00432ba2b75cc42caf23e405c24acb33d839e7a
-2026-07-20-dsh-cli-personal-config.zh.md: b33a7fa321ca04f41e47386544ffc0f268a8b1b6
+2026-07-20-dsh-cli-personal-config.zh.md: 91d2c938b345a7f2233da1566ac6db5b934c3148
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index b33a7fa321..91d2c938b3 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 两个耦合的部分，与 `dsh web` PR（#443）提出的 `apps/` 装配层对齐：
 
-**`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 是位于 `packages/*` 库之上的产品组装层。一个 bin 负责分发默认交互式 TUI、`-p`/`--prompt` 无头轮次和 `web` 界面。TUI 以调用目录为 workspace，启动 `examples/tui-agent/cordis.yml`（或 `--config` 指定的配置）。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，并使用 tsx 的 ESM hook 运行应用；该契约由[源码启动决策](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)维护。`pnpm run demo:tui` 运行同一入口。
+**`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 是位于 `packages/*` 库之上的产品组装层。一个 bin 负责分发默认交互式 TUI、`-p`/`--prompt` 无头轮次和 `web` 界面。TUI 以调用目录为 workspace，启动 `examples/tui-agent/cordis.yml`（或 `--config` 指定的配置）。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，并使用 tsx 的 ESM hook 运行应用；该约定由[源码启动决策](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)维护。`pnpm run demo:tui` 运行同一入口。
 
 **个人配置（`dsh-app-boot`）。** 个人 overlay 存放在 Harness home——`$DSH_HOME`，否则 `~/.dsh`——由共享的 [`resolveDshHome`](../architecture/2026-07-24-single-harness-home-resolver.md)（`@deepseek-ai/dsh-paths`）解析，与 skills、AGENTS.md 解析所依据的单一根目录相同。dsh 的 TUI、Web 和无头界面使用其中两个可选文件；各示例 bin 仍然逐字节按已提交的配置树启动：
 
@@ -34,7 +34,7 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 
 **个人完整 `cordis.yml` 去 include 请求的配置。** 否决：个人文件将不得不写死叶子配置的路径，而该路径随 checkout 变化；补丁反转了依赖方向，bin 仍然选择配置树，个人层只做修正。
 
-**把个人补丁深合并进配置项配置。** 否决：会使补丁语义与已提交 overlay 和 vendor 的 include 分叉；整个 `config` 替换已是成文契约。
+**把个人补丁深合并进配置项配置。** 否决：会使补丁语义与已提交 overlay 和 vendor 的 include 分叉；整个 `config` 替换已是成文约定。
 
 **用环境变量开关代替存在性判断。** 否决：默认关闭的个人配置永远不会被用起来；存在即生效加上每个测试的显式隔离，让实际运行获得 overlay、测试获得封闭性。
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
index 1d93b7f440..03d812f73b 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md
 2026-07-21-continuable-background-subagents.md: e37abdd798242bc1086754e86a85ef46c08e59a3
-2026-07-21-continuable-background-subagents.zh.md: 799e1914bdeb571dc697652081be6b0170768655
+2026-07-21-continuable-background-subagents.zh.md: 729ec62d9d3511661638144cdef6e31bf98ecdb7
diff --git a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
index 799e1914bd..729ec62d9d 100644
--- a/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md
@@ -33,7 +33,7 @@ durable child Session
 
 初始后台委派请求 `ctx.subagents` 启动 child 并注册其 Task。可继续提供方只有在确认本次激活的最终会话状态已持久化后，才会返回成功的 run 结果。Task 结算流程等待该结果，通过继续执行管理器的结算路径调用 `run.dispose()`，然后才记录 `TaskOutcome`；`task_kill` 中止活跃 run，其结算路径仍会 dispose 该 run。因此，终态 Task 会留下持久化 child 会话，但不会留下存活的 child agent。必需的持久性检查点若没有已安装的监听器或任一监听器失败，run 会以稳定错误码 `DURABILITY_FAILED` 拒绝，并将检查点失败保留为失败原因；管理器会记录失败的 Task，其详情说明最新状态未确认已持久化，因此恢复时可能不可用或已陈旧。
 
-后续每个轮次都会创建另一个 Task。该轮 producer 持有的执行资源仅服务于这次激活，不属于 child 会话。它只会到达一次终态、只产生一个结果，也不会重新打开。Task 注册表中当前注册的那个存活 parent agent 实例仍是其 owner：dispose 该实例会取消、等待并移除其 Task。Task API 会授权 session id 与该 owner 匹配的调用方，但 id 相同的替代实例不会成为通知或资源清理目标。这一设计保留 `settleRun()` 契约，并使 Task 所拥有的存活 child 数量受并发工作量限制，而不是随历史会话数量增长。
+后续每个轮次都会创建另一个 Task。该轮 producer 持有的执行资源仅服务于这次激活，不属于 child 会话。它只会到达一次终态、只产生一个结果，也不会重新打开。Task 注册表中当前注册的那个存活 parent agent 实例仍是其 owner：dispose 该实例会取消、等待并移除其 Task。Task API 会授权 session id 与该 owner 匹配的调用方，但 id 相同的替代实例不会成为通知或资源清理目标。这一设计保留 `settleRun()` 约定，并使 Task 所拥有的存活 child 数量受并发工作量限制，而不是随历史会话数量增长。
 
 用户界面适配器打开 child 会话时，只读取持久化 transcript，不会仅为展示而恢复 agent。用户输入通过继续执行管理器，启动或加入与 parent 输入相同的 Task 激活。由用户启动的 Task 会保留当前加载的精确 parent Agent 作为通知目标，`task_output` 仍是唯一结果路径。只要 Task 尚未标记为已报告，现有完成监听器最多注入一条主动通知；`kill`、终态读取或终态等待都可能将其标记为已报告，并抑制这条通知。因此，仅允许在该 parent 实例保持存活时进行用户交互。可以比 parent 存活更久、并将结论显式合并回去的用户自有会话属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)，不属于这一由 Task 持有的生命周期。
 
@@ -67,13 +67,13 @@ durable child Session
 
 发送到现有 run 的消息没有独立结果，其效果体现在当前 Task 的最终结果中。启动的后续轮次具有新 Task 的结果，并使用现有 `task_output` 读取路径。subagent 层不会再注入第二份完成通知。
 
-用户输入使用同一个 `followup` 操作。UI 可以展示 child transcript 和当前 Task 状态，取消操作则以已加载 parent 作为调用方访问 Task 服务。工具 schema 与 UI 适配器消费同一个服务契约，不建立彼此独立的执行路径。
+用户输入使用同一个 `followup` 操作。UI 可以展示 child transcript 和当前 Task 状态，取消操作则以已加载 parent 作为调用方访问 Task 服务。工具 schema 与 UI 适配器消费同一个服务约定，不建立彼此独立的执行路径。
 
 ### 持久化 child handle 与从持久化存储恢复
 
 继续执行管理器在创建 Task 前，通过 seam 的 `snapshotSubagentDescriptor()`（基于 [`snapshotJsonValue`](../../../../packages/core/session/src/json.ts) 构建）对每项描述符输入建立快照；这一边界与 Agent 消息现有的分离式无损 JSON 边界一致。作用于 child 作用域的 setup contribution——由进程内驱动前置安装的一次性 `agent/prompt-submit` 监听器——会在下游 prompt admission 能够阻止请求或抛出异常之前追加一个对模型隐藏的 `subagent/descriptor` 事件。admission 获准后才会开启 child 的初始轮次；admission 被拒绝时，描述符会作为轮次前的仅日志事实保留，并由该 activation 最终的必需检查点持久化。该事件不携带 `surfaceOp`，不进入模型历史，并在压缩替换 surface 历史时继续保留。只有在加载已知 child id 对应的 child 会话后，能在该 child 自身的后缀中（`seedLength` 之后，因此 fork seed 不会泄露祖先的描述符）得到受支持的描述符，且会话 header 将调用方标识为直接 parent 时，该 id 才可恢复。
 
-版本化描述符的可继续分支（[descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts) 中的 `SUBAGENT_DESCRIPTOR_VERSION`）携带 `mode: 'continuable'`、subagent 提供方名称、已解析的 child `agentOptions.provider` 和 `agentOptions.model`，以及可选的 `persona` 与 `toolFilter`。它不会对可通过声明合并扩展的 `AgentOptions` 对象建立快照：与此无关的扩展值不会仅因无法表示为 JSON 而导致继续执行失败。描述符会特意省略 `subagentDepth`；从持久化存储恢复时，系统依赖持久化 header 中的 `delegationDepth`，而不根据描述符重建深度。`outputSchema` 属于单次激活的结果契约，不属于持久化 child 组合配置。child header 仍是 child id、`cwd`、`parentSession`、`seedLength` 和 `delegationDepth` 的权威信息，持久化 child transcript 则负责保存 fork seed 和后续历史。[`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) 会在 header 值和运行时值中取最大值，因此重建后的运行时选项可以加深持久化值，但绝不能降低它，恢复后的 child 无法重新获得顶层委派预算。
+版本化描述符的可继续分支（[descriptor.ts](../../../../packages/subagent/subagent/src/descriptor.ts) 中的 `SUBAGENT_DESCRIPTOR_VERSION`）携带 `mode: 'continuable'`、subagent 提供方名称、已解析的 child `agentOptions.provider` 和 `agentOptions.model`，以及可选的 `persona` 与 `toolFilter`。它不会对可通过声明合并扩展的 `AgentOptions` 对象建立快照：与此无关的扩展值不会仅因无法表示为 JSON 而导致继续执行失败。描述符会特意省略 `subagentDepth`；从持久化存储恢复时，系统依赖持久化 header 中的 `delegationDepth`，而不根据描述符重建深度。`outputSchema` 属于单次激活的结果约定，不属于持久化 child 组合配置。child header 仍是 child id、`cwd`、`parentSession`、`seedLength` 和 `delegationDepth` 的权威信息，持久化 child transcript 则负责保存 fork seed 和后续历史。[`delegationDepthOf()`](../../../../packages/subagent/subagent/src/index.ts) 会在 header 值和运行时值中取最大值，因此重建后的运行时选项可以加深持久化值，但绝不能降低它，恢复后的 child 无法重新获得顶层委派预算。
 
 从持久化存储恢复不能依赖 `SubagentRun` 的可选方法，因为该 run 已被 dispose，并且进程重启后不会保留。run 表示一次可 dispose 的激活，只暴露作用于当前激活的操作。`SubagentRun.steer?()` 这一名称明确指代提供确认语义且仅适用于在线消息的功能，以免该功能与服务编排或面向模型的工具混淆。
 
@@ -85,7 +85,7 @@ TODO（ACP 继续执行）：将远端 ACP session id 作为提供方专用描
 
 ### 结果与通知所有权
 
-每次可继续 child 激活都恰好拥有一个 Task 和一个 `TaskOutcome`，无论第一条消息由 parent 还是用户提供。只要 Task 尚未标记为已报告，通用 Task 报告契约最多会向保留的 parent owner 注入一条主动完成通知；读取、等待和取消都可能抑制该通知。发送到运行中激活的消息会加入该激活，不会创建第二个 Task 或第二份结果。child transcript 是面向用户的详细记录；Task 输出是面向 parent 的最终结果。
+每次可继续 child 激活都恰好拥有一个 Task 和一个 `TaskOutcome`，无论第一条消息由 parent 还是用户提供。只要 Task 尚未标记为已报告，通用 Task 报告约定最多会向保留的 parent owner 注入一条主动完成通知；读取、等待和取消都可能抑制该通知。发送到运行中激活的消息会加入该激活，不会创建第二个 Task 或第二份结果。child transcript 是面向用户的详细记录；Task 输出是面向 parent 的最终结果。
 
 Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可在重启后恢复，但不会恢复中断的 Task、其结果或通知。持久化 Task 恢复属于另一个问题。
 
@@ -95,7 +95,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 
 **允许用户轮次不使用 Task。** parent 消息加入此类轮次后，没有对应的 Task 结果或完成通知；UI 取消对 parent 所发消息的影响也不明确。让每次激活都拥有一个 Task，可使完成与取消成为 child 轮次的属性，而不是初始调用方的属性。
 
-**在 child 会话整个生命周期内复用一个 Task。** 终态 Task 无法自然地再次进入运行状态，一个结果也无法表示多个轮次。每次激活创建新 Task 可以保留通用 Task 契约。
+**在 child 会话整个生命周期内复用一个 Task。** 终态 Task 无法自然地再次进入运行状态，一个结果也无法表示多个轮次。每次激活创建新 Task 可以保留通用 Task 约定。
 
 **为每条消息创建 Task。** 发送到现有 run 的消息会加入已有轮次，不产生独立的最终结果；为这类消息创建 Task，会重复当前 Task，或报告一个它并不拥有的结果。只有启动新激活的消息才会创建 Task。
 
@@ -109,7 +109,7 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 
 ## 测试
 
-- `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述契约。
+- `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 固定可继续执行的持久性边界：缺少 flush 监听器、flush 监听器已脱离或监听器持续失败时，均会以 `DURABILITY_FAILED` 拒绝；循环检查点的瞬时失败可在最终确认成功后继续完成，发生取消时最终检查点无论成功还是失败都由取消优先决定结果，resume 同样会确认持久性，而前台运行仍采用尽力而为策略。`packages/subagent/subagent/tests/continuation.spec.ts` 以无密钥方式驱动真实栈（agent loop、JSONL 持久化、spawn／fork 提供方、Task 服务和 `ctx.subagents`）：初始及恢复后的激活都会创建新 Task，并在进入终态前 dispose 各自的 run；描述符事件位于轮次前、对模型隐藏、带版本、在服务分配的 child id 下持久化，并在初始 prompt admission 阻止请求或抛出异常时仍保留；取消、steering、cold follow-up、授权、所有权冲突与 resume 竞态保留上述约定。
 - `packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts` 固定 `send_message` 的 schema、coordinator 来源标记、两种路由渲染、未送达失败、无 agent 时的拒绝，以及 HMR（热模块替换）dispose。
 - `packages/subagent/tool-subagent/tests/tool-subagent.spec.ts` 覆盖配置的后台路由：可继续模式要求提供方可恢复，并在不要求 `send_message` 的情况下返回两个 id；即使提供方可以恢复，一次性模式仍保持普通的 Task 确认消息。
 - `packages/scaffold/helper/tests/project.spec.ts` 固定生成的 spawn 与 fork 组合中的 Task 服务及面向模型的 Task 控制工具。
@@ -123,5 +123,5 @@ Task 记录和活跃 run 关联都位于进程内。持久化使 child 会话可
 - 活跃 run 关联只能协调一个运行时。多个进程同时恢复时不会串行化；此类部署需要持久化层的租约或 compare-and-set 操作。
 - 用户交互要求作为 owner 的那个精确 parent Agent 实例保持存活，因为 dispose owner 会取消并移除其 Task。用户交互还要求附加 Task 控制面。若要单独与 child 交互，后续必须将 Task 访问所有权与持久化通知目标分离。
 - 后台工具会在 child 发布和描述符持久化之前返回 child id 和 Task id。启动失败、最终持久性确认失败，或进程在 child 首次 flush 之前退出，都会使 Task 失败，并可能留下 unmaterialized 或陈旧的 child id；按 id 的控制操作会将缺失状态报告为不可用，而不会追溯修改工具确认消息。
-- 将显式组合字段持久化到 child 日志后，其无损 JSON 与兼容性契约便成为恢复契约的一部分。后续如需支持其他组合配置输入，必须明确更改描述符版本，不能隐式持久化可通过声明合并扩展的 `AgentOptions` 字段。
+- 将显式组合字段持久化到 child 日志后，其无损 JSON 与兼容性约定便成为恢复约定的一部分。后续如需支持其他组合配置输入，必须明确更改描述符版本，不能隐式持久化可通过声明合并扩展的 `AgentOptions` 字段。
 - Task 记录和活跃 run 关联位于进程内，而 child 会话具有持久性。重启会恢复会话，但不会恢复进行中的工作或其 Task 通知。
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
index c5d0cab7a1..e330fbd089 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-cross-session-references.md
 2026-07-21-cross-session-references.md: b2d428e0937fdd881720720401948a1c3e7ef1f6
-2026-07-21-cross-session-references.zh.md: e242e159329a5f1446b08547cd0f176b6c1af3f7
+2026-07-21-cross-session-references.zh.md: ef89fd76c864c430f7b730d250e6511c2709f97e
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
index e242e15932..ef89fd76c8 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-TUI 用户需要把另一场对话中的相关工作带入一条新消息，但不恢复、不 fork，也不让源 transcript（文本记录）对当前会话拥有权威性。harness 已经提供准确的会话枚举与原始事件检查，但若每个宿主都独立解析日志，就会重复实现压缩（compaction）折叠、来源过滤、大小限制、错误行为和持久化。把宿主标记直接编码进 agent（智能体）消息契约，还会让核心循环绑定某一种 UI 语法。
+TUI 用户需要把另一场对话中的相关工作带入一条新消息，但不恢复、不 fork，也不让源 transcript（文本记录）对当前会话拥有权威性。harness 已经提供准确的会话枚举与原始事件检查，但若每个宿主都独立解析日志，就会重复实现压缩（compaction）折叠、来源过滤、大小限制、错误行为和持久化。把宿主标记直接编码进 agent（智能体）消息约定，还会让核心循环绑定某一种 UI 语法。
 
 ## 决策
 
@@ -20,7 +20,7 @@ TUI 用户需要把另一场对话中的相关工作带入一条新消息，但
 
 准备过程按首次出现的顺序去重、拒绝目标会话自身的 id，并且执行可配置的数量限制，但引用硬上限为三个，所有读取均并行执行。该过程不会返回部分完成的上下文：任何读取、取消、校验或预算错误都会在调用 `followup()` 或 `steer()` 前拒绝本次操作。取消会与进行中的候选发现和精确读取竞速，因此即使持久化后端无法中断待处理操作，宿主也能及时结束等待；后端迟到的完成结果仍会被观察，但不能让消息入队。源会话在入队前完成读取，因此源会话后续新增消息、执行压缩、被删除或替换持久化内容，都无法改变目标会话中的快照。
 
-投影会保留直接用户消息与 steering（中途引导）、已完成的 assistant 文本，以及携带由 `dsh-compact` 导出的规范来源标记的检查点用户消息。该标记属于压缩能力契约的一部分，而非某个后端包名称。当源提示词已包含合并写入的前缀上下文时，投影只读取其模型不可见的显示内容，因此后续引用该目标不会递归传播先前的快照。投影会排除压缩前已被遮蔽的节点、工具及其结果、推理（reasoning）、注入的上下文、其他插件用户消息、仅用于日志的记录，以及尚未完成的 assistant 分片。因此，重复压缩只会暴露当前表层仍保留的最新折叠检查点谱系及其尾部消息；系统不提供 raw/current 开关，也不恢复被遮蔽的内容。
+投影会保留直接用户消息与 steering（中途引导）、已完成的 assistant 文本，以及携带由 `dsh-compact` 导出的规范来源标记的检查点用户消息。该标记属于压缩能力约定的一部分，而非某个后端包名称。当源提示词已包含合并写入的前缀上下文时，投影只读取其模型不可见的显示内容，因此后续引用该目标不会递归传播先前的快照。投影会排除压缩前已被遮蔽的节点、工具及其结果、推理（reasoning）、注入的上下文、其他插件用户消息、仅用于日志的记录，以及尚未完成的 assistant 分片。因此，重复压缩只会暴露当前表层仍保留的最新折叠检查点谱系及其尾部消息；系统不提供 raw/current 开关，也不恢复被遮蔽的内容。
 
 系统把一个聚合上下文序列化为 JSON，并置于固定的不可信背景警告之后。该警告要求模型不要遵循被引用会话中的指令、权限声明或工具请求，除非当前用户再次提出这些内容。标签安全序列化会把数据中的每个 `<` 无损转义为 JSON `\u003c`；因此源字符串无法拼出外围类似 XML 的标签，也无法逃逸数据区域。同一个序列化器会独立核算每个源的字节数。AgentLoop 会把快照持久化为一条带来源信息的 `user/message`，紧接在直接 `user/message` 之前。因此，目标回放无需新增事件类型、放置模式或提示词封套，也能满足「模型可见／日志可重建」不变量。
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
index e109560a2f..3ea46677ab 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
 2026-07-21-log-backed-session-titles.md: 89e6e67fb9ece4c087ba7b1bc52e61b78b94586c
-2026-07-21-log-backed-session-titles.zh.md: 4df21be565f57db056f506df477f665908d1fdfa
+2026-07-21-log-backed-session-titles.zh.md: 21a0ec5dc9cc90726dda502ba46a52d717c39df5
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
index 4df21be565..21a0ec5dc9 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
@@ -53,7 +53,7 @@ Status: implemented
 - **将标题放入派生历史记录或请求前缀**：不予采纳，因为 UI 元数据会消耗 token、改变缓存标识，并让主模型观察到自己的标签。纯日志事件既保持可重建，又不会变得对模型可见。
 - **允许注册多个提供方，并在完成后解析优先级**：不予采纳，因为完成顺序并不等于产品优先级，而且会让重试、HMR 和来源信息变得不确定。需要组合策略的部署可以注册一个自行负责该策略的提供方。
 - **静默截断过大的辅助输入**：不予采纳，因为提供方结果会声明准确的源消息来源信息，实际却只接收了部分文本。保留原有标题并发出警告，可以保持归因真实。
-- **立即在 `listSessions()` 中索引标题**：不予采纳，因为现有的轻量元数据列表将需要逐后端同步派生索引。精确的 `readTitle()` 建立了读取契约，而没有提前锁定搜索或索引策略。
+- **立即在 `listSessions()` 中索引标题**：不予采纳，因为现有的轻量元数据列表将需要逐后端同步派生索引。精确的 `readTitle()` 建立了读取约定，而没有提前锁定搜索或索引策略。
 - **让 Web host 只使用回退标题**：不予采纳，因为 UI 虽会显示持久标题，却始终无法将第一条提示词的前缀改进为更好的标题。首消息提供方在主响应路径之外运行，并让模型摘要成为 Web 的默认结果。
 
 ## 后果
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
index e4df6863da..538e89e047 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
 2026-07-22-durable-subagent-catalog-and-list-agents.md: 61bda2a52f2ea5db0a582fe668643a13b967f091
-2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: a2bc36200d8c67b8da9dd3d55ea4179baa72e691
+2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: 6b5bff468349df4226aaf76dd7ed7d9ce5c3f33c
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
index a2bc36200d..6b5bff4683 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 可继续的后台 subagent 会公开稳定的 child id，并将重建数据持久化在该 child 的会话中，因此 `send_message` 无需任何列表查询操作即可恢复已知 child。发现功能有两类需求不同的消费方：UI 可以同时展示一次性工作和可继续对话，而模型只应收到适合使用 `send_message` 的 child。[可继续 subagent](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)负责持久化 Session 与 Activation 设计；本记录负责共享的持久化清单及面向模型的投影。
 
-枚举必须交叉核对不可变的会话谱系、描述符有效性与实时优先的会话语料，而不能仅为展示就加载或恢复 Agent。追踪谱系可以提供候选项，却无法区分普通会话 fork 与 subagent，因此 child 日志需要持久化分类。契约还必须定义生命周期模式、缺失或损坏的记录、删除、不受支持的版本，以及反复加载大量 child 日志会如何影响服务与工具消费方。
+枚举必须交叉核对不可变的会话谱系、描述符有效性与实时优先的会话语料，而不能仅为展示就加载或恢复 Agent。追踪谱系可以提供候选项，却无法区分普通会话 fork 与 subagent，因此 child 日志需要持久化分类。约定还必须定义生命周期模式、缺失或损坏的记录、删除、不受支持的版本，以及反复加载大量 child 日志会如何影响服务与工具消费方。
 
 ## 决策
 
@@ -23,19 +23,19 @@ parent 到 child 的枚举是一项带消费方专用投影的服务功能。`Su
 - 将语料活动状态单独报告为 `running` 或 `inactive`，但不暗示已完成或可恢复；
 - 按 `createdAt` 升序、再按 child id 升序稳定返回所有结果 child。
 
-每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`）；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 契约负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
+每次普通的本地启动都会收到带可选、由调用方拥有之显示标签的 `one-shot` 描述符，而继续执行管理器会持久化带标签、包含附加重建字段的 `continuable` 描述符。面向模型的委派工具已经拥有简短 `description`，会将其用于一次性显示；workflow 等底层调用方无需凭空构造展示元数据。面向模型的 `list_agents` 适配器会将服务结果过滤为可继续 child，并通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`）；UI 可以消费两种模式，并为无标签的一次性历史选择基于 id 的回退展示。描述符持久化、按 id 查找、直接 parent 鉴权和不依赖提供方的冷恢复仍归已实现的 Activation 约定负责。列表查询消费这些事实，但不能削弱它们，也不能另行发明第二种描述符表示。
 
 ### 枚举决策
 
 第一版消费 `ctx.sessionQuery.traceSession(parentSessionId)`，并且只考虑追踪结果的第一层后代。目标可以存活，也可以只存在于持久化存储中；追踪逻辑语料不会加载或恢复 Agent。会话查询已经使用实时优先规则合并 `ctx.sessions` 与 `ctx.sessionPersistence`，保持不可变 header 一致性，根据 `SessionHeader.parentSession` 推导直接 child 谱系，并按 `createdAt` 升序、child id 升序排列 sibling。`listChildren()` 不会重复实现这套语料逻辑，也不会检查继续执行管理器的进程内 Activation map。
 
-语料构建先于逐 child 描述符检查。构建初始追踪时如果发生持久化列表查询失败、所观测语料中任意位置的存活／持久化 header 冲突或目标谱系无效，整个 `list_agents` 调用都会失败，因为此时不存在可信的候选集。只有初始追踪成功后的失败才会被隔离到单个候选；因此，这项逐 child 契约中的“损坏 child”是指已加载的事件 surface 或描述符数据损坏，而不是语料级 header 冲突。
+语料构建先于逐 child 描述符检查。构建初始追踪时如果发生持久化列表查询失败、所观测语料中任意位置的存活／持久化 header 冲突或目标谱系无效，整个 `list_agents` 调用都会失败，因为此时不存在可信的候选集。只有初始追踪成功后的失败才会被隔离到单个候选；因此，这项逐 child 约定中的“损坏 child”是指已加载的事件 surface 或描述符数据损坏，而不是语料级 header 冲突。
 
 会话谱系涵盖的范围比 subagent 身份更广：普通 `ctx.sessions.fork()` 也会创建直接 child。会话 header 不新增 `kind` 判别字段；每个候选必须改为在自身后缀中恰好包含一个有效的 `subagent/descriptor` 事件。`SubagentService.start()` 会在普通提供方分发前解析 `{ mode: 'one-shot', provider, label? }`，而继续执行管理器会在初始创建 child 时为 `{ mode: 'continuable', ...composition }` 建立快照并将其作为 seed。本地进程内的一次性驱动只在初始创建期间追加已解析的描述符，从持久化存储冷恢复时不会追加其他描述符；第二个事件属于损坏，而不是另一次 Activation 的证据。Agent 创建是一次性运行的发布边界：拒绝表示没有发布 child，而发布后的提示词、轮次、取消与基础设施结果会通过返回的 run 结算，且不会隐藏其 id。描述符事件是已追踪 child 属于由会话支撑的 subagent 的唯一证据。缺少该事件的候选属于普通 fork、没有本地会话记录的远端 child 或其他非 subagent 会话，系统会将其排除且不产生 diagnostic。
 
 已发布的逻辑记录同时也是活动状态来源：`SessionRecord.live` 表示 `running`，而 `live: false, persisted: true` 表示 `inactive`。活动状态直接来自追踪结果，不会导致额外加载 child 日志。`inactive` 既不表示执行成功，也不表示可恢复：它可能表示已结算的一次性历史，也可能表示 `send_message` 可以为其物化另一次 Activation 的可继续 child。反过来，`running` 只表示会话存活：位于继续执行管理器对应 Activation 之外的存活可继续 Agent 仍会显示为 `running`，但 `send_message` 会将其作为所有权冲突拒绝。child 会话发布前不可见，也不会添加进程内 Activation 条目作为第二个候选来源或活动状态来源。列表查询是一份快照，可能与发布、dispose 或后续消息发生竞态；`send_message` 仍是消息送达时的权威操作。
 
-subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法只在被调用时才会解析这个可选服务，并动态加载可选的会话查询运行时；因此，普通 subagent 导入、start 和 follow-up 都不会触发该包求值。列表查询直接由 `SubagentService` 负责：它解释查询返回的谱系、事件和存活状态，无需解析基于 Activation 的继续执行管理器，也不会查询 Agent 注册信息、Activation 或提供方；因此，仅包含会话、`subagents` 和 `sessionQuery` 的部署即使缺少 `agents` 也能执行列表查询。如果查询服务缺失，该方法会在加载运行时或执行查询工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在既不安装也不加载会话查询的情况下使用 `send_message`；列表工具 fiber 会在必需服务可用前保持未激活状态，而其他直接服务消费方会收到同一项明确的调用时契约。这一段的依赖姿态——可选 `sessionQuery`、其错误码与列表工具的加载要求——同属被取代的读路径：现行错误码（`SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`、`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`）与收窄后的加载要求以[取代记录](../architecture/2026-08-06-subagent-list-identity-projection.md)为准。
+subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法只在被调用时才会解析这个可选服务，并动态加载可选的会话查询运行时；因此，普通 subagent 导入、start 和 follow-up 都不会触发该包求值。列表查询直接由 `SubagentService` 负责：它解释查询返回的谱系、事件和存活状态，无需解析基于 Activation 的继续执行管理器，也不会查询 Agent 注册信息、Activation 或提供方；因此，仅包含会话、`subagents` 和 `sessionQuery` 的部署即使缺少 `agents` 也能执行列表查询。如果查询服务缺失，该方法会在加载运行时或执行查询工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在既不安装也不加载会话查询的情况下使用 `send_message`；列表工具 fiber 会在必需服务可用前保持未激活状态，而其他直接服务消费方会收到同一项明确的调用时约定。这一段的依赖姿态——可选 `sessionQuery`、其错误码与列表工具的加载要求——同属被取代的读路径：现行错误码（`SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`、`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`）与收窄后的加载要求以[取代记录](../architecture/2026-08-06-subagent-list-identity-projection.md)为准。
 
 `listChildren(parentSessionId, signal?)` 会把调用方的取消信号转发给 `traceSession()` 和条件性精确 `readEvent()` 操作。`listEvents()` 不接受取消参数，因此列表查询路径会在等待该操作的前后，以及每个候选处理完成后检查信号。如果取消信号触发后有查询操作以拒绝结算，服务会将结果归一化为 `SubagentError`，并携带稳定错误码 `CANCELLED`；后端中止错误或可映射为 diagnostic 的查询错误均不会逃逸，也不会使调用以成功的部分列表返回。
 
@@ -43,7 +43,7 @@ subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务
 
 如果实测规模日后需要索引，该索引属于派生状态：会话 header 和 child 描述符仍是权威信息，重建或损坏回退必须复现相同结果。索引不能成为第二个鉴权来源，也不能让尚未发布的 child 变得可见。
 
-### `list_agents` 契约
+### `list_agents` 约定
 
 `SubagentService.listChildren(parentSessionId: SessionId)` 返回 `Promise<SubagentListEntry[]>`，其中的单个数组不会将 child 与 diagnostic 分开，而是保留追踪结果中的候选顺序。`SubagentListEntry` 是一个由只读 `kind` 判别的封闭联合类型：
 
@@ -52,7 +52,7 @@ subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务
 
 有效描述符产生一个 child 条目，逐 child 检查失败产生一个 diagnostic 条目，缺少描述符的候选不产生条目。`mode` 是持久化创建策略；`activity` 是进程本地语料快照。活动状态既不是 `AgentStatus`、管理器内部的 Activation 状态，也不是持久化结果，结果不公开内部 `createdAt` 排序键。成功完成、失败、取消和停止原因等精确 Activation 状态与持久化结果需要单独的持久化激活记录，不在本功能范围内。
 
-面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并在执行或渲染前通过显式的 request-to-spec 步骤解析请求（`undefined` → `children`）。解析后的 `children` scope 调用 `SubagentService.listChildren(rootSessionId)`，`descendants` scope 则调用 `SubagentService.listDescendants(rootSessionId)`。其内部输出投影中的 `id` 与 `parent` 会一直保持为品牌化的 `SessionId` 值，直到工具 JSON 边界。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
+面向模型的 `list_agents` 工具接受一个可选的 `scope: 'children' | 'descendants'` 参数，从当前执行 Agent 推导根 id，并在执行或渲染前通过显式的 request-to-spec 步骤解析请求（`undefined` → `children`）。解析后的 `children` scope 调用 `SubagentService.listChildren(rootSessionId)`，`descendants` scope 则调用 `SubagentService.listDescendants(rootSessionId)`。其内部输出投影中的 `id` 与 `parent` 会一直保持为品牌化的 `SessionId` 值，直到工具 JSON 边界。它保留 diagnostic，丢弃 `one-shot` child 条目，状态取自在线 Agent 注册表——driver 活跃为 `running`，驻留但处于轮次之间为 `idle`，没有在线 Agent 时为 `complete`——然后按稳定目录顺序渲染 `<id> [<status>] — <label>` 或 `<id> [diagnostic: <reason>]`。`descendants` scope 从一份实时优先语料按稳定 pre-order 展平完整树，遍历普通与一次性中间节点以发现更深的可继续 agent，依据枚举生命周期重新校验每个冷候选，并为每个条目附加 `parentId`／`depth`。工具会在 label 之前插入 ` parent=<id> depth=<n>`；`parent` 是持久化直接 parent 会话 id，可能指向被省略的普通会话。对于当前调用方，只有 depth-1 child 条目可作为 `send_message` 候选，更深的 child 条目则可供 `interrupt_agent` 选择（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）。发现结果只是提示——follow-up 权限仍仅属于确切直接 parent，中断权限仍由服务的在线 lineage 检查决定。空投影渲染为 `(no subagents)`。
 
 在已被取代的追踪读路径中，diagnostic 使用三种固定原因。格式错误的事件 surface、精确加载 child 时发现的 header 冲突、读取结果中的不可变 header 与追踪到的候选不一致或不再指向请求的直接 parent、读取目标不再是先前定位的描述符事件、格式错误的描述符内容和多个描述符事件映射为 `corrupt`。未知描述符版本映射为 `unsupported`。逐 child 读取产生的 `SESSION_QUERY_SESSION_NOT_FOUND`、`SESSION_QUERY_EVENT_NOT_FOUND` 和 `SESSION_QUERY_PERSISTENCE_FAILED` 映射为 `unavailable`。这项阶段边界是有意为之：初始追踪期间发生持久化故障会让操作失败，而同一故障如果始于候选读取期间，可能会让每个受影响的 child 分别产生一条相同的 `unavailable` diagnostic；第一版既不合并这些 diagnostic，也不会把它们提升为全局失败。缺少描述符则作为非 subagent 排除，且不产生 diagnostic。配置错误、窗口错误和未识别的失败不属于 child diagnostic，会作为操作失败继续向上传播。每条 diagnostic 都标识 child id 及原因，不暴露对模型隐藏的描述符内容；系统会排除该候选，而其他健康的 sibling 仍然可见。系统绝不会读取不属于追踪结果直接后代的会话，也不会为它们产生 diagnostic。
 
@@ -80,13 +80,13 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 
 **持久化 parent 会话目录事件。** 直接 child header 已经提供持久化枚举种子，child 描述符则是重建的权威信息。第二份 parent 日志会重复状态，并造成跨会话顺序和陈旧条目行为，却无助于按 id 恢复。
 
-**要求每次底层启动都提供显示标签。** 这会保证 UI 文本一致，却会把展示关注点引入 workflow、传输、测试和程序化启动契约。底层请求保持标签可选；高层委派与继续执行 API 在本就拥有该概念时提供标签，UI 消费方则为无标签的一次性 child 选择回退展示。
+**要求每次底层启动都提供显示标签。** 这会保证 UI 文本一致，却会把展示关注点引入 workflow、传输、测试和程序化启动约定。底层请求保持标签可选；高层委派与继续执行 API 在本就拥有该概念时提供标签，UI 消费方则为无标签的一次性 child 选择回退展示。
 
 **某个 child 无法加载时让整次列表查询失败。** 这种做法不会让损坏问题被忽略，但一个损坏的 sibling 会让每个健康 child 都不再可见。逐 child diagnostic 在保持每次排除明确可见的同时，也保留了发现能力。
 
 **分别返回 child 和 diagnostic 数组。** 分离的数组会引入两个排序域，或者要求公开另一个排序键才能重建候选顺序。一个带判别字段的条目数组既能保留追踪顺序，也能保证 child 与 diagnostic 字段的类型安全。
 
-**通过会触发修复的 `load()` 路径读取候选。** 复用恢复路径的 `load()` 语义可以让发现提前持久化地关闭中断尾部，但会把列表查询变成变更操作，并使其失败模式与写协调耦合。会话查询的语料读取本就使用非变更的 `inspect()` 契约，因此列表查询保持存储只读，尾部修复留给真正需要它的恢复路径。
+**通过会触发修复的 `load()` 路径读取候选。** 复用恢复路径的 `load()` 语义可以让发现提前持久化地关闭中断尾部，但会把列表查询变成变更操作，并使其失败模式与写协调耦合。会话查询的语料读取本就使用非变更的 `inspect()` 约定，因此列表查询保持存储只读，尾部修复留给真正需要它的恢复路径。
 
 **立即为查询分页或设置上限（暂缓）。** 这可以限制一次结果的大小，但会使模型发现成为有状态操作，而且除非模型继续跟随 cursor，否则可能隐藏更早的 child。第一版没有 cursor、分页参数或候选数量上限配置，而是返回经稳定排序的完整集合；如果实测规模需要限制，服务级限制仍留待后续决策。
 
@@ -94,7 +94,7 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 
 - `packages/subagent/subagent/tests/service.spec.ts` 固定两种模式下的描述符 v2 解析，并证明无标签的底层启动会在分发给提供方之前解析出一次性描述符。`packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 证明本地驱动会在初始轮次内追加该描述符，在取消落入工厂到 run 的交接窗口时返回已发布 id，并让结果与句柄释放失败保留在独立通道中。委派工具测试固定其现有显示说明的传递，并保留相互独立的结果与 dispose diagnostic。
 - `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；带类型的稳定错误码；以及后代列表的迭代式稳定 pre-order、穿过普通与一次性中间节点、带位置 diagnostic、生命周期复验与取消。一个伴随规格(已随查询式读取路径一起退役)曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
-- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（一个可选 `scope` 枚举）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、由注册表推导的 child／diagnostic／空结果文本形式、带持久化 label 的已结束 child 端到端列表、descendants scope 在在线 waiting 分支上的 pre-order parent/depth 注释、两个 scope 的取消信号转发、无调用 agent 时的拒绝、要求 `agents` 但不再注入 `sessionQuery` 的加载契约，以及 HMR dispose。
+- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（一个可选 `scope` 枚举）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、由注册表推导的 child／diagnostic／空结果文本形式、带持久化 label 的已结束 child 端到端列表、descendants scope 在在线 waiting 分支上的 pre-order parent/depth 注释、两个 scope 的取消信号转发、无调用 agent 时的拒绝、要求 `agents` 但不再注入 `sessionQuery` 的加载约定，以及 HMR dispose。
 - 无密钥 ACP 快照场景 `subagent-list-agents`（examples/acp-agent）使用仅限快照的 `subagent/end` 标记为第二个 parent 轮次设置边界，随后针对 subagent 服务、投影注册表和 JSONL 持久化真实执行 `list_agents`，渲染 `<id> [complete] — <label>`。
 - 无密钥快照场景 `subagent-diagnostic`（examples/headless-agent）钉住现行列表的模型可见诊断分类，包括无描述符的定局 child 以 `corrupt` diagnostic 出现。
 - 无密钥 ACP 快照场景 `subagent-published-run-failure` 会发布一个真实的一次性 child，注入相互独立的 run result 与 handle dispose 失败，并在 parent 工具结果中保留两项 diagnostic。
diff --git a/.agents/notes/implemented/feature/2026-07-22-web-bind-address.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-web-bind-address.i18n.yaml
index f5a469377b..ac5e4cb4c6 100644
--- a/.agents/notes/implemented/feature/2026-07-22-web-bind-address.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-web-bind-address.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-22-web-bind-address.md
 2026-07-22-web-bind-address.md: 3332176c0cee940648ad334a44edd30879225503
-2026-07-22-web-bind-address.zh.md: 5a8c49461b90abfd2476a56d7d148cdaaacd01e3
+2026-07-22-web-bind-address.zh.md: 5ad73b8916d9cedce1073f4a2d025f40197b7d65
diff --git a/.agents/notes/implemented/feature/2026-07-22-web-bind-address.zh.md b/.agents/notes/implemented/feature/2026-07-22-web-bind-address.zh.md
index 5a8c49461b..5ad73b8916 100644
--- a/.agents/notes/implemented/feature/2026-07-22-web-bind-address.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-web-bind-address.zh.md
@@ -12,7 +12,7 @@ HTTP 承载层还把绑定地址隐藏在 `startWebServer()` 内部，导致其
 
 ## 决策
 
-`dsh web` 默认绑定 `127.0.0.1`。CLI（命令行界面）接受 `--host 0.0.0.0` 作为显式启用的全接口模式，并拒绝其他取值，使网络模式保持为一份规模小、经过审慎限定的契约。全接口模式仍然输出本机环回 URL，并在可用时输出第一个外部 IPv4 URL。
+`dsh web` 默认绑定 `127.0.0.1`。CLI（命令行界面）接受 `--host 0.0.0.0` 作为显式启用的全接口模式，并拒绝其他取值，使网络模式保持为一份规模小、经过审慎限定的约定。全接口模式仍然输出本机环回 URL，并在可用时输出第一个外部 IPv4 URL。
 
 `WebServerOptions.host` 为必填项。HTTP 承载层将该值直接传给 `node:http`，不提供回退值，因此每个壳层负责制定自己的绑定策略。以编程方式使用承载层的消费方可以直接选择其他主机名或地址。
 
@@ -26,4 +26,4 @@ HTTP 承载层还把绑定地址隐藏在 `startWebServer()` 内部，导致其
 
 ## 后果
 
-`dsh web` 的本地启动仍可通过 `http://127.0.0.1:3080` 访问；其他机器上的浏览器必须使用 `dsh web --host 0.0.0.0` 显式启用。CLI 尚未开放自定义接口地址或 IPv6 模式，而以编程方式使用承载层的消费方仍保留这种灵活性。服务器测试将环回模式和全接口模式向 Node 监听边界的传递固定为契约，Web 冒烟测试继续覆盖默认 CLI 路径。
+`dsh web` 的本地启动仍可通过 `http://127.0.0.1:3080` 访问；其他机器上的浏览器必须使用 `dsh web --host 0.0.0.0` 显式启用。CLI 尚未开放自定义接口地址或 IPv6 模式，而以编程方式使用承载层的消费方仍保留这种灵活性。服务器测试将环回模式和全接口模式向 Node 监听边界的传递固定为约定，Web 冒烟测试继续覆盖默认 CLI 路径。
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index be9c014650..ee8d4ca6af 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
 2026-07-23-session-telemetry-otel-revival.md: e6a213af65451a2ae26a5eb685c1a0f6ab220869
-2026-07-23-session-telemetry-otel-revival.zh.md: 1d607ce9a3b77ae96664af72599beacb34fd9b47
+2026-07-23-session-telemetry-otel-revival.zh.md: b97840405bbde35f3b6b7f417b0615774fe43061
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index 1d607ce9a3..b97840405b 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-每个想把 harness 会话接入可观测性体系的部署方都得手写一套会话日志消费方：订阅、生命周期交接、以及最难的脱敏——原始日志携带文件内容与命令输出，可能内嵌凭据。遥测 seam 和 OTel 后端曾在 `session-telemetry-otlp-rfc` 分支（PR #222/#231）上完成过一版，但从未进入 master：该提案将原始会话事件原样导出，法务评审未予通过。捕获侧设计（后端契约、coordinator、handoff 游标、分片投影）本身合理且经过评审；导出侧的立场才是阻塞点。
+每个想把 harness 会话接入可观测性体系的部署方都得手写一套会话日志消费方：订阅、生命周期交接、以及最难的脱敏——原始日志携带文件内容与命令输出，可能内嵌凭据。遥测 seam 和 OTel 后端曾在 `session-telemetry-otlp-rfc` 分支（PR #222/#231）上完成过一版，但从未进入 master：该提案将原始会话事件原样导出，法务评审未予通过。捕获侧设计（后端约定、coordinator、handoff 游标、分片投影）本身合理且经过评审；导出侧的立场才是阻塞点。
 
 ## 决策
 
@@ -20,7 +20,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-**实现 runtime-telemetry RFC 的 outbox（落盘 spool、每 sink 游标、at-least-once、持久化 seam 的 `readCommitted` 方法）。** 推迟而非否决：SDK 立场使投递语义归属 reporting SDK，OTel SDK 自身的批处理流水线是诚实的默认。outbox 是纯增量层（`emit()` 契约不动）；待某个部署提出遥测必须满足的崩溃丢失要求时再复活。
+**实现 runtime-telemetry RFC 的 outbox（落盘 spool、每 sink 游标、at-least-once、持久化 seam 的 `readCommitted` 方法）。** 推迟而非否决：SDK 立场使投递语义归属 reporting SDK，OTel SDK 自身的批处理流水线是诚实的默认。outbox 是纯增量层（`emit()` 约定不动）；待某个部署提出遥测必须满足的崩溃丢失要求时再复活。
 
 **不设进程内脱敏点，交给接收端 collector processor。** 否决——接收端脱敏是先把秘密发出去再擦除。waterfall 在字节离开进程前提供一个可审计、可堆叠的擦除点；分支版本（PR #222 交付的形态）完全没有脱敏点，如今每条记录都必经该脱敏点。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
index e78ab9abbd..544870a5da 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.md
 2026-07-23-web-assistant-markdown.md: ad86559e3b5294b6bd67d69ff5c6ce37a5172008
-2026-07-23-web-assistant-markdown.zh.md: b47375db843ea1c81b913e3f7ac8cd1bbc278830
+2026-07-23-web-assistant-markdown.zh.md: e7544b2c731581e29b026026a2bb627defb91ca7
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
index b47375db84..e7544b2c73 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md
@@ -12,7 +12,7 @@ Web 对话通过会话事件、历史回放与流式累积保留 assistant Markd
 
 `@deepseek-ai/dsh-client-ui-primitives` 导出 `MarkdownText`，用作不受信任的 assistant 文本渲染器；`ui-conversation` 仅为 assistant `text` 块选择该渲染器。已完成的历史消息、流式输出尾部与被中断的部分输出已经共用 `AssistantMarkdown`，因此无需更改事件或快照，它们便会采用同一渲染器。用户消息与 steering 消息继续使用 `MessageText`，并保持按字面渲染。
 
-`MarkdownText` 以 `mdast-util-from-markdown` 加 GFM micromark 扩展解析，并经包内自有渲染器渲染 mdast 树，轮次流式输出期间增量解析（[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有该机制及其 DOM 一致性契约）。它覆盖 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，且不解析原始 HTML。一个 micromark attention 扩展复用 CommonMark resolver，同时允许至少两个星号组成的连续序列在 Unicode 标点后闭合，前提是其后紧邻 CJK 文本。这一例外涵盖流式输出期间与完成后无空格 CJK 文本中以标点结尾的粗体；单星号强调、紧邻非 CJK 文本的情况、已转义源文本、代码与数学公式仍沿用上游解析行为。围栏代码经共享的 `CodeBlock` 路由；该组件用客户端的 shiki 单例（`--shiki-*` token）高亮已注册语法，否则回退为纯等宽文本。轮次流式输出期间，围栏停留在纯文本分支，以免每收到一个分片就对增长中的围栏重新分词。
+`MarkdownText` 以 `mdast-util-from-markdown` 加 GFM micromark 扩展解析，并经包内自有渲染器渲染 mdast 树，轮次流式输出期间增量解析（[增量 AST 渲染器 Note](../architecture/2026-08-06-web-markdown-incremental-ast-renderer.md) 拥有该机制及其 DOM 一致性约定）。它覆盖 CommonMark 块，以及 GFM 表格、任务列表、删除线与自动链接，且不解析原始 HTML。一个 micromark attention 扩展复用 CommonMark resolver，同时允许至少两个星号组成的连续序列在 Unicode 标点后闭合，前提是其后紧邻 CJK 文本。这一例外涵盖流式输出期间与完成后无空格 CJK 文本中以标点结尾的粗体；单星号强调、紧邻非 CJK 文本的情况、已转义源文本、代码与数学公式仍沿用上游解析行为。围栏代码经共享的 `CodeBlock` 路由；该组件用客户端的 shiki 单例（`--shiki-*` token）高亮已注册语法，否则回退为纯等宽文本。轮次流式输出期间，围栏停留在纯文本分支，以免每收到一个分片就对增长中的围栏重新分词。
 
 视觉间距、表格、链接、引用块、行内代码与代码块外框遵循 deepsuite `@deepseek/md`（`markdown.css` / `code-block.css`），并使用同一套 `--dsw-alias-markdown-*`、`--dsw-font-markdown-*`、`--dsw-alias-border-l*` 与 `--dsw-alias-label-*` token。链接使用 `--dsw-alias-state-business-primary`（deepsuite 的样式表使用 `--dsw-alias-brand-text`，仅在 newDesign 下为蓝色；design-platform 将 brand-text 保持为近黑色，此处不做重新调色）。当单个行内代码 token 完全由绝对 HTTP(S) URL 构成时，其代码外框会包含一个与普通链接相同、可通过键盘聚焦的安全外链锚点；端口、路径与查询文本保持不变，而命令、非完整 URL、其他 scheme 与围栏代码仍不会成为链接。`CodeBlock` 提供语言横幅与复制控件（`复制` / `复制成功`）。已完成的文本通过定稿语法的数学扩展渲染 KaTeX；`mathCompatibility` 将 `\(...\)`、`\[...\]` 和块级同一行 `$$...$$` 映射为同一套标准数学 AST 节点。这是一层小范围的解析器兼容层，不是正则重写，也不修复格式错误的模型输出。流式输出在完成前保持按字面渲染，避免不完整公式闪现错误。引用胶囊、标题锚点、thinking-small markdown 变体，以及自定义 □/☑ 任务标记仍不在范围内；GFM 任务列表继续使用原生复选框。
 
@@ -34,7 +34,7 @@ assistant 生成的链接目标地址仅限绝对 HTTP、HTTPS 与 mailto URL。
 
 **通过净化启用原始 HTML。** 原始 HTML 当前没有产品需求，并且会扩大可执行内容边界，因此保持禁用，无需增加净化器依赖。远程图片由后续的[图片策略](2026-07-30-web-remote-markdown-images.md)约束。
 
-**移植 deepsuite 的 Prism `highlight.css` 与 mdast 管线。**外观一致性由 CSS Modules 与共享的 `--dsw-*` token 负责；高亮仍走现有的 shiki 允许列表，使客户端不必引入第二套高亮器或 Prism class 契约。
+**移植 deepsuite 的 Prism `highlight.css` 与 mdast 管线。**外观一致性由 CSS Modules 与共享的 `--dsw-*` token 负责；高亮仍走现有的 shiki 允许列表，使客户端不必引入第二套高亮器或 Prism class 约定。
 
 **为处理 CJK 标点边界而预处理 Markdown 源文本，或在解析后修复文本节点。**源文本重写必须在解析器掌握这些区别之前复现转义、代码、数学公式与定界符规则；文本节点修复则已经丢失部分源文本意图，也无法与已解析的行内节点组合。在分词器边界扩展 attention 可保留上游 resolver，并将差异限制在定界符的适用条件上。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
index 3c006bc9f1..01b96211a7 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.md
 2026-07-23-web-permission-and-approval.md: 06e184fe32ac684e3d8b0820d915ca7c372a5760
-2026-07-23-web-permission-and-approval.zh.md: b74e93006cb95c398eb464a9bd9a59e8c9cc57be
+2026-07-23-web-permission-and-approval.zh.md: c662f126c41b2e581bc39319f0e5569d364d7aec
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
index b74e93006c..c662f126c4 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md
@@ -6,21 +6,21 @@ Status: implemented
 
 ## 问题
 
-Web 承载层启动的是一个不受限的 agent（智能体）：`bootHost` 组合了 `dsh-bash-local` 与 `dsh-fs-local`，因此每个 Web 会话都以完整文件访问权限运行，既无审批通道，也无权限管控——而 ACP 组合早在数月前就已交付完整的沙箱化产品路径（沙箱提供方 + 策略归属 + 受限的 bash/fs + 审批 + 预设）。Web 协议契约其实早已预留了对应位置——`approval/requested`/`approval/resolved` 的 mux 帧、携带 `ApprovalResponsePayload` 的 `POST /api/respond`、client 侧的 `pendingBuffers`——但 host 的 `respond` 只是一个 stub，没有应答者把 `ctx.approval` 桥接到流上，没有 RPC 暴露权限选择，PendingCard 把审批渲染成可见却无法应答的样子。
+Web 承载层启动的是一个不受限的 agent（智能体）：`bootHost` 组合了 `dsh-bash-local` 与 `dsh-fs-local`，因此每个 Web 会话都以完整文件访问权限运行，既无审批通道，也无权限管控——而 ACP 组合早在数月前就已交付完整的沙箱化产品路径（沙箱提供方 + 策略归属 + 受限的 bash/fs + 审批 + 预设）。Web 协议约定其实早已预留了对应位置——`approval/requested`/`approval/resolved` 的 mux 帧、携带 `ApprovalResponsePayload` 的 `POST /api/respond`、client 侧的 `pendingBuffers`——但 host 的 `respond` 只是一个 stub，没有应答者把 `ctx.approval` 桥接到流上，没有 RPC 暴露权限选择，PendingCard 把审批渲染成可见却无法应答的样子。
 
 ## 决策
 
 Web 承载层组合与 acp-agent 相同的沙箱化产品路径：`dsh-sandbox-local`、`dsh-sandbox-policy`、`dsh-bash-sandbox`、`dsh-fs-sandbox`、`dsh-user-approval` 与 `dsh-permission`，由 `BootHostOptions.sandbox` 提供部署默认值（`mode`，默认 `workspace-write`；`approvalPolicy`，默认 `ask`）。
 
-`createApiProxy` 拥有审批 pending 注册表。它的 `approval/request` waterfall（瀑布式事件）应答者从会话刚追加的 `approval/asked` 审计事件中读取审批 id（没有审计事件的 ask 属于外部通道，予以委托），为每个问题 mint 一个稳定的 rpcId，向每个打开的 mux 流广播可应答的 `approval/requested` 帧，并在每次 mux 打开时原样重放仍处于 pending 的帧——这正是契约早已承诺的刷新恢复基线。`respond` 按回显的 rpcId 路由，用既有的 zod schema 校验 `ApprovalResponsePayload`，将载荷的审计关联与所路由的条目交叉核对，解析应答者，并广播 `approval/resolved`；ask 的中断信号会以 `cancelled` 撤回该问题。
+`createApiProxy` 拥有审批 pending 注册表。它的 `approval/request` waterfall（瀑布式事件）应答者从会话刚追加的 `approval/asked` 审计事件中读取审批 id（没有审计事件的 ask 属于外部通道，予以委托），为每个问题 mint 一个稳定的 rpcId，向每个打开的 mux 流广播可应答的 `approval/requested` 帧，并在每次 mux 打开时原样重放仍处于 pending 的帧——这正是约定早已承诺的刷新恢复基线。`respond` 按回显的 rpcId 路由，用既有的 zod schema 校验 `ApprovalResponsePayload`，将载荷的审计关联与所路由的条目交叉核对，解析应答者，并广播 `approval/resolved`；ask 的中断信号会以 `cancelled` 撤回该问题。
 
 权限选择依托两个新的一元 RPC，`session.permissions` 与 `session.setPermission`，把 `ctx.permission` 投影为一个由协议拥有的 `PermissionOption` DTO（沿用 ACP bridge 的先例：每个协议拥有自己的呈现形状）。无权限的组合提供空的选择项，client 隐藏该控件。空闲期的切换以后写胜出（last-write-wins）的方式保存在 proxy 侧的 pending map 中，并在 `agent/pre-step` 时冲刷，因为旋钮事件必须保持轮次内闭合以支持持久回放；共享的 `hasOpenTurn` 折叠迁入 `dsh-session`，取代了 `dsh-user-approval`、ACP bridge 与 proxy 中各自的私有副本。
 
-在 client 侧，`Session` 新增了 `permissions` 与 `setPermission`，审批应答则依托运行时的 `PendingWait` 载体。按照设计师草稿，处于 pending 的审批会接管 composer：`ApprovalPanel` 注册为由会话声明的 `conversation.composer` 链中一个按选择器路由的条目（即 ui-question 模式），以理由标题、配对的命令与一次性的拒绝／允许按钮取代 InputBar；ui-conversation 契约中的 `PendingApproval` 领域面拥有 `ApprovalResponsePayload` 在该载体上的协议编码（wire encoding），广播的 resolved 帧使该等待落定并恢复 composer。pending 问题通过 ui-question 接管 composer，包括 `plan-review` 决策形状。侧边栏用一枚优先级高于运行中圆环的琥珀色警示圆点，同步呈现每个被阻塞的交互，搜索期间也不例外：manager 跟踪每个会话的审批与问题请求标识，而非读取 Session 实例；它只把满足 plan-review composer 二元呈现约束的请求分类为计划审查，并在问题与审批并发时优先呈现第一个 pending 问题，以匹配 composer 路由。实例化前的缓冲会保留每个仍有效的请求标识，替换回放产生的重复项，并移除已解决的请求，因此侧边栏状态绝不会比可应答的 `PendingWait` 存续得更久；跟踪以连接代次为单位清除，以保证重开后的回放才是权威依据。从未实例化过的会话仍会点亮该圆点。composer 底行的 chip 经会话注入面挂载 `PermissionSelect` 控件。连接 fixture（测试前置数据）与 host 保持一致：它的常驻审批可应答一次，其权限选择项按会话持久保存。
+在 client 侧，`Session` 新增了 `permissions` 与 `setPermission`，审批应答则依托运行时的 `PendingWait` 载体。按照设计师草稿，处于 pending 的审批会接管 composer：`ApprovalPanel` 注册为由会话声明的 `conversation.composer` 链中一个按选择器路由的条目（即 ui-question 模式），以理由标题、配对的命令与一次性的拒绝／允许按钮取代 InputBar；ui-conversation 约定中的 `PendingApproval` 领域面拥有 `ApprovalResponsePayload` 在该载体上的协议编码（wire encoding），广播的 resolved 帧使该等待落定并恢复 composer。pending 问题通过 ui-question 接管 composer，包括 `plan-review` 决策形状。侧边栏用一枚优先级高于运行中圆环的琥珀色警示圆点，同步呈现每个被阻塞的交互，搜索期间也不例外：manager 跟踪每个会话的审批与问题请求标识，而非读取 Session 实例；它只把满足 plan-review composer 二元呈现约束的请求分类为计划审查，并在问题与审批并发时优先呈现第一个 pending 问题，以匹配 composer 路由。实例化前的缓冲会保留每个仍有效的请求标识，替换回放产生的重复项，并移除已解决的请求，因此侧边栏状态绝不会比可应答的 `PendingWait` 存续得更久；跟踪以连接代次为单位清除，以保证重开后的回放才是权威依据。从未实例化过的会话仍会点亮该圆点。composer 底行的 chip 经会话注入面挂载 `PermissionSelect` 控件。连接 fixture（测试前置数据）与 host 保持一致：它的常驻审批可应答一次，其权限选择项按会话持久保存。
 
 ## 曾考虑的替代方案
 
-**在 Web 协议上复用 ACP 的 `session/set_config_option` 形状。** 不予采纳：Web 契约的一元方法注册表（`RpcMethodMap` + 逐方法的 zod schema）是它自成一体的方言；一个通用的 config-option 接口会为一个选择项绕开编译期锁定的 schema 表。一对专用方法让两侧都能从签名推导得出。
+**在 Web 协议上复用 ACP 的 `session/set_config_option` 形状。** 不予采纳：Web 约定的一元方法注册表（`RpcMethodMap` + 逐方法的 zod schema）是它自成一体的方言；一个通用的 config-option 接口会为一个选择项绕开编译期锁定的 schema 表。一对专用方法让两侧都能从签名推导得出。
 
 **用一个会话事件承载 pending 交互，而非实时注册表。** 不予采纳：可应答请求是瞬态的交互状态，而非持久的会话数据——审批的 `approval/asked`/`decided` 审计对已经记录了持久的那一半。持久化 requested 帧会在回放时重新问出已经作废的问题。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml
index f90cfe79db..5c05f0b86d 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-23-web-todo-display.md
 2026-07-23-web-todo-display.md: bb66ef8512badea090b3b22030eef3f43f3b1119
-2026-07-23-web-todo-display.zh.md: 7270874d1e96bb0a553d57ba24b3bc2bb38a7a71
+2026-07-23-web-todo-display.zh.md: 5b3534e20956a4412814a782532d1337c08ff027
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
index 7270874d1e..5b3534e209 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ### 副作用通道，与窗口回放收敛
 
-`applyEventSideEffects` 新增一个 `todo/write` 分支（整份列表，后写覆盖先写），并在 `turn/start` 清空（[按轮次界定的计划生命周期](2026-07-28-todo-plan-clears-on-next-turn.md)）。`rebuildDerivedFromWindow` 从空计划扫过窗口，仅当窗口从未判定计划（无 `todo/write` 且无 `turn/start`）时恢复尾页种子；否则以窗口内写入／`turn/start` 折叠为准。`installWindow` 的每个调用方都是尾页请求（`doOpen`、其补洞重拉、`repairGap`；`loadOlder` 只往前拼接、不再播种），而 host 对尾页请求要么带上投影、要么在没有当前有效的计划时省略——因此字段缺失就是权威的空列表，直接照此赋值。这个区分在回滚场景上要紧：若 host 在持久化实时写入前崩溃，log 里就是空的，此时保留旧值会让已回滚的计划永远留在屏幕上。`ConversationSnapshot.todos` 是读取面。这遵循事件自身的契约（「仅存在于日志中的 UI 状态；绝不纳入派生历史」）：把每次写入作为对话节点呈现，会让已被取代的列表看起来仍然有效。
+`applyEventSideEffects` 新增一个 `todo/write` 分支（整份列表，后写覆盖先写），并在 `turn/start` 清空（[按轮次界定的计划生命周期](2026-07-28-todo-plan-clears-on-next-turn.md)）。`rebuildDerivedFromWindow` 从空计划扫过窗口，仅当窗口从未判定计划（无 `todo/write` 且无 `turn/start`）时恢复尾页种子；否则以窗口内写入／`turn/start` 折叠为准。`installWindow` 的每个调用方都是尾页请求（`doOpen`、其补洞重拉、`repairGap`；`loadOlder` 只往前拼接、不再播种），而 host 对尾页请求要么带上投影、要么在没有当前有效的计划时省略——因此字段缺失就是权威的空列表，直接照此赋值。这个区分在回滚场景上要紧：若 host 在持久化实时写入前崩溃，log 里就是空的，此时保留旧值会让已回滚的计划永远留在屏幕上。`ConversationSnapshot.todos` 是读取面。这遵循事件自身的约定（「仅存在于日志中的 UI 状态；绝不纳入派生历史」）：把每次写入作为对话节点呈现，会让已被取代的列表看起来仍然有效。
 
 ### TodoPanel：持久化列表作为一条常驻横条
 
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
index b11dc50cd6..e90a23fd2e 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-model-facing-session-query-tools.md
 2026-07-24-model-facing-session-query-tools.md: 863f557f11f89ff8dfc121b7da0b653852528394
-2026-07-24-model-facing-session-query-tools.zh.md: d8deaba15f111537a16deafe73ed6dd708ea044a
+2026-07-24-model-facing-session-query-tools.zh.md: 2acbf44b42aafd2eac37903e1acbefc5ba098377
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
index d8deaba15f..2acbf44b42 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 `@deepseek-ai/dsh-tool-session-query` 是 `ctx.sessionQuery` 面向模型的消费者。它注册五个职责单一的只读工具：`session_search`、`session_event_search`、`session_trace`、`session_event_trace` 和 `session_event_read`。该包依赖接口而非 SQLite 实现，负责模型参数校验与易读文本渲染，并贡献一个精简的提示词段，说明历史搜索以及从搜索转向追踪／读取的工作流。
 
-该包入口仅作为配置、提示词注册与工具注册的公开组合根。内部模块沿执行边界划分：`input.ts` 负责模型 schema、规范化与过滤条件构造；`service-boundary.ts` 包含提供方调用与面向模型的安全错误转换；`workspace-access.ts` 负责调用者身份、工作区授权、标题访问与谱系投影；`operations.ts` 编排五个服务工作流；`presentation.ts` 渲染工具结果与调用卡片。这样可让策略留在其所属层，同时不改变包契约。
+该包入口仅作为配置、提示词注册与工具注册的公开组合根。内部模块沿执行边界划分：`input.ts` 负责模型 schema、规范化与过滤条件构造；`service-boundary.ts` 包含提供方调用与面向模型的安全错误转换；`workspace-access.ts` 负责调用者身份、工作区授权、标题访问与谱系投影；`operations.ts` 编排五个服务工作流；`presentation.ts` 渲染工具结果与调用卡片。这样可让策略留在其所属层，同时不改变包约定。
 
 `session_search` 按会话聚合全文匹配，并公开带类型的会话与事件元数据过滤条件。`session_event_search` 搜索一个会话，默认目标为调用者的当前会话。`session_trace` 返回完整的已授权祖先链与递归后代树。`session_event_trace` 返回一个事件所有已知的位置替换关系与直接来源关系。`session_event_read` 以未删节 JSON 返回准确的目标事件，并可选择汇总一个有界的原始事件窗口；省略 `before` 与 `after` 时只返回目标。
 
diff --git a/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.i18n.yaml
index 7718957ab6..c70efe3121 100644
--- a/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-provider-retry-policies.md
 2026-07-24-provider-retry-policies.md: 1831ce6b96178d11e7c9927ceccbe07ea578cd2c
-2026-07-24-provider-retry-policies.zh.md: d44f954d75a09a40988655ef486733dc2ac6f58c
+2026-07-24-provider-retry-policies.zh.md: 22f18badcb47e4ce086ff2c68c7011612b2eabba
diff --git a/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.zh.md b/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.zh.md
index d44f954d75..22f18badcb 100644
--- a/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.zh.md
@@ -48,7 +48,7 @@ always 模式先请求下游恢复，使上下文溢出压缩（compaction）之
 
 **在 `dsh-llm-retry` 上维护单独的指定提供方列表**：不予采纳，因为它会在所属适配器配置之外重复提供方路由名称，并让提供方注册与恢复策略发生偏差。
 
-**设置很大的有限重试次数**：不予采纳，因为它最终仍会违反持续重试的契约，并把任意选取的运维上限序列化成看似有意义的数值。
+**设置很大的有限重试次数**：不予采纳，因为它最终仍会违反持续重试的约定，并把任意选取的运维上限序列化成看似有意义的数值。
 
 **使用提供方 SDK 重试**：不予采纳，因为隐藏尝试会叠加 agent 层预算，无法利用已关闭步骤的持久性边界，还可能在没有可重建重试记录的情况下拼接或丢弃流式输出。
 
@@ -60,6 +60,6 @@ always 模式先请求下游恢复，使上下文溢出压缩（compaction）之
 
 ## 后果
 
-normal 模式仍是有限的默认策略；显式的 always 策略可能在永久性的身份验证、配额、无效请求、协议或上下文错误上耗费无限次请求和无限时间。运维方必须为 always 模式配备可取消的调用方和针对提供方的成本控制。重试状态保持可观察且会持久化，但不会对模型可见；捕获实际提供服务的注册项，也能防止适配器生命周期变化反过来改变进行中请求的恢复契约。
+normal 模式仍是有限的默认策略；显式的 always 策略可能在永久性的身份验证、配额、无效请求、协议或上下文错误上耗费无限次请求和无限时间。运维方必须为 always 模式配备可取消的调用方和针对提供方的成本控制。重试状态保持可观察且会持久化，但不会对模型可见；捕获实际提供服务的注册项，也能防止适配器生命周期变化反过来改变进行中请求的恢复约定。
 
 本决策扩展了[瞬态 LLM（大语言模型）请求失败的有界恢复](../architecture/2026-06-21-bounded-llm-request-recovery.md)中确定的已关闭步骤恢复、单次可见适配器尝试、结构化失败与持久化状态设计。
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
index fe955d125d..cad70622c8 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
 2026-07-25-session-list-browsing-and-manual-order.md: bd04e7f74c8a4540d68e60ad68965e05de76bce9
-2026-07-25-session-list-browsing-and-manual-order.zh.md: 8ec5f71943a68a70f46fbd4c7702e4556b1892ec
+2026-07-25-session-list-browsing-and-manual-order.zh.md: 2bf778284aa551c75f1206ed08ca073e47b7a15d
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
index 8ec5f71943..2bf778284a 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
@@ -34,7 +34,7 @@ UI 为组内 session 行的 HTML5 拖拽(仅 workspace 分组、非搜索态；f
 
 ### 壳/区域切分
 
-ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settings,以及一个 `sidebar.workspaces` 洞;壳与区域的契约只有两个事实 `{ wide, expandSidebar }`。ui-workspace 全权拥有浏览区域(section header、搜索、分组树与平铺、全部 workspace 对话框、拖拽)及其 groupBy store;rail 态的搜索/添加工作区图标也归区域,经 `expandSidebar()` 请求壳展开。picker 拆为核心件 `WorkspacePickFlow`(区域内直接组件组合;在[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)之前名为 `WorkspaceCreateFlow`)与薄包装 `WorkspacePicker`(继续填 ui-conversation 的 hero 坑);原 `sidebar.workspace` picker 坑与声明感知延迟注册随之删除。
+ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settings,以及一个 `sidebar.workspaces` 洞;壳与区域的约定只有两个事实 `{ wide, expandSidebar }`。ui-workspace 全权拥有浏览区域(section header、搜索、分组树与平铺、全部 workspace 对话框、拖拽)及其 groupBy store;rail 态的搜索/添加工作区图标也归区域,经 `expandSidebar()` 请求壳展开。picker 拆为核心件 `WorkspacePickFlow`(区域内直接组件组合;在[单一路径 Note](../simplification/2026-07-31-one-route-to-add-a-workspace.md)之前名为 `WorkspaceCreateFlow`)与薄包装 `WorkspacePicker`(继续填 ui-conversation 的 hero 坑);原 `sidebar.workspace` picker 坑与声明感知延迟注册随之删除。
 
 ## Alternatives considered
 
@@ -50,8 +50,8 @@ ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settin
 
 ## Consequences
 
-- 手动序是唯一的 workspace 账本序权威:用户排好的顺序不再被活动打乱;代价是「最近活跃浮到最上」的行为消失,活跃感知转由行内状态点与时间标签承担。`WorkspaceView.sessionIds` 的 wire 契约随之改为手动序措辞。
-- 壳/区域两事实契约把 workspace 域的后续功能(Delete 确认、跨组移动、Ungrouped 收编)全部收进 ui-workspace 单包;ui-sidebar 不再随 session 列表功能演进。
+- 手动序是唯一的 workspace 账本序权威:用户排好的顺序不再被活动打乱;代价是「最近活跃浮到最上」的行为消失,活跃感知转由行内状态点与时间标签承担。`WorkspaceView.sessionIds` 的 wire 约定随之改为手动序措辞。
+- 壳/区域两事实约定把 workspace 域的后续功能(Delete 确认、跨组移动、Ungrouped 收编)全部收进 ui-workspace 单包;ui-sidebar 不再随 session 列表功能演进。
 - 平铺模式不支持排序与分组入口(建到指定 workspace 需切回分组视图),是拍板接受的范围收窄。
 - session Delete 的功能接线与状态枚举扩 wire,留待后续迭代。
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
index d8232afa44..6c4d70b005 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
 2026-07-25-workspace-ui-product-flow.md: 7a6a41e19d2930fbcbf7ba5fc9e6809d96e23166
-2026-07-25-workspace-ui-product-flow.zh.md: a40f374fd794b11bff0de72cbc822fd638cd267c
+2026-07-25-workspace-ui-product-flow.zh.md: 372339331bdf2ee5f7c63abd1cc056ae37b16f78
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
index a40f374fd7..372339331b 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
@@ -116,6 +116,6 @@ Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSe
 
 - SessionHeader 不记录最后活跃时间，历史 bootstrap 只能按 `createdAt` 初始化；此后由真实 Session 活跃事件逐项前移。
 - 历史 cwd 缺失、目录无效或 realpath 失败的 Session 留在 Ungrouped；本期没有手动收编入口。
-- 页面刷新会丢弃未 materialize 的 Workspace/Session Intent 和尚未被 Host 接受的输入，这是 page-local 契约。
+- 页面刷新会丢弃未 materialize 的 Workspace/Session Intent 和尚未被 Host 接受的输入，这是 page-local 约定。
 - 显式 Create Workspace 立即落盘，用户不发送就离开也会留下空 Workspace。
 - Host Session 在首个事件前仍遵循现有懒持久化语义；前端 Intent 不改变 Host 重启后的空 Session 行为。
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
index d2ffd775a4..f8ccab3362 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
 2026-07-26-code-dispatch-ui-foundation.md: a1629c77304bc7ef744f7a09241bcdfc81e461ae
-2026-07-26-code-dispatch-ui-foundation.zh.md: d49b6956f75356511ca3b0f9f2e88b42629230f6
+2026-07-26-code-dispatch-ui-foundation.zh.md: 8f40281454e78d3d1baaf0dce3635bdf01d0a658
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
index d49b6956f7..8f40281454 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-26-code-dispatch-ui-foundation.md) | 中文
 
-> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧契约变更，即 Code Mode Web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用 seam，归本篇所有。
+> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧约定变更，即 Code Mode Web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用 seam，归本篇所有。
 
 ## 问题
 
@@ -14,7 +14,7 @@ Status: implemented
 
 三项变更，每项对应一个障碍：
 
-1. **`run_code` 新增必填的 `description` 参数**（与 bash 完全相同的契约：主动语态、5-10 个词、展示在 UI 中；仅含空白的取值在执行时被拒绝）。`presentCall` 现在以该 description 作为卡片标题，并把程序文本移入 `rawInput`。提示词侧的成本是每次调用多出几个 token；换来的是每个表面——TUI 卡片、ACP（Agent Client Protocol）标题、Web 行——都无需解析 TypeScript 就能获得可供人阅读的标签。
+1. **`run_code` 新增必填的 `description` 参数**（与 bash 完全相同的约定：主动语态、5-10 个词、展示在 UI 中；仅含空白的取值在执行时被拒绝）。`presentCall` 现在以该 description 作为卡片标题，并把程序文本移入 `rawInput`。提示词侧的成本是每次调用多出几个 token；换来的是每个表面——TUI 卡片、ACP（Agent Client Protocol）标题、Web 行——都无需解析 TypeScript 就能获得可供人阅读的标签。
 2. **`tool/code-dispatch` 记录子调用面向模型的完整结果**（`content: ContentBlock[]` 加 `isError`，即 `tool/result` 的词汇），取代 `resultSummary`，并把摘要与 cwd 归一化机制彻底删除。UI 渲染子调用走的代码路径与渲染原生结果完全相同，包括错误文本和非文本块。该事件保持仅日志（`deriveMessages()` 忽略它）：模型上下文没有任何变化。
 3. **`dsh` 配置树上的 `DSH_TOOLS_MODE` 环境变量**（`native`|`code`|`both`；未设置时保持 schema 默认值）：`tools` 行通过 `!!js` 读取它，worker 代码运行时则无条件挂载（loader 元数据是静态的，因此不存在条件行；native 启动只是注册该服务，worker 要到每次运行时才 spawn）。这是一个明确标注为临时的 seam：设计目标是让 Web UI 拥有按会话的工具模式选择，该目标落地后，这个环境变量随即退役。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 **一个 `--tools-mode` CLI（命令行界面）标志或 profile 配置键。** 推迟，而非否决：标志语法暗示永久性，profile JSON 又是用户配置；两者都会固化这个 seam，而按会话选择的设计本就打算移除它。环境变量则如实呈现了它权宜之计的本质。
 
-**记录规范 `value`，而非渲染后的 `content`。** 否决：`tool/result` 持久化的是内容而非值（见[规范输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)），与原生同等保真意味着与之精确对齐；值始终仅存在于执行期本地。
+**记录规范 `value`，而非渲染后的 `content`。** 否决：`tool/result` 持久化的是内容而非值（见[规范输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)），与原生同等保真意味着与之精确对齐；值始终仅存在于执行期本地。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
index ed15fd5c36..2b12308db9 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
 2026-07-26-code-mode-live-parallel-dispatch.md: e85d1f99f58f1aae28091cd8875ee87a6df5a1e7
-2026-07-26-code-mode-live-parallel-dispatch.zh.md: 39da98d9c3630d549f13df0ea555687614f3065a
+2026-07-26-code-mode-live-parallel-dispatch.zh.md: c7f91f570e20e27aade0e8f47606d31b1d8ae7eb
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
index 39da98d9c3..c7f91f570e 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
@@ -1,10 +1,10 @@
-# Agent Note: Code Mode 的实时分发生命周期，以及复用原生契约的并行执行
+# Agent Note: Code Mode 的实时分发生命周期，以及复用原生约定的并行执行
 
 Status: implemented
 
 [English](2026-07-26-code-mode-live-parallel-dispatch.md) | 中文
 
-> 范围：Code Mode UI 堆叠 PR（Pull Request）链的第三个 PR，涵盖 `tool/code-dispatch-start` 事件、Web chat 中每个子调用的运行状态，以及桥接层调度器对原生并发契约的复用。构建在[宿主侧基础](2026-07-26-code-dispatch-ui-foundation.md)与 [chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)之上；原生契约本身归[并行工具调用 Agent Note](2026-07-10-parallel-tool-call-execution.md) 所有。
+> 范围：Code Mode UI 堆叠 PR（Pull Request）链的第三个 PR，涵盖 `tool/code-dispatch-start` 事件、Web chat 中每个子调用的运行状态，以及桥接层调度器对原生并发约定的复用。构建在[宿主侧基础](2026-07-26-code-dispatch-ui-foundation.md)与 [chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)之上；原生约定本身归[并行工具调用 Agent Note](2026-07-10-parallel-tool-call-execution.md) 所有。
 
 ## 问题
 
@@ -12,12 +12,12 @@ Status: implemented
 
 ## 决策
 
-**一对生命周期事件，一份调度契约，与原生共用。**
+**一对生命周期事件，一份调度约定，与原生共用。**
 
 - **事件对**：`tool/code-dispatch-start`（父/子 id、名称、规范化参数）在调度器真正启动某个调用时才追加，而非在提交时，因此因 run 结算而被放弃的排队调用不会留下任何日志。既有的 `tool/code-dispatch` 结算该事件对（`subCallId` 相同）；每个已启动的调用恰好结算一次（中止也会作为 `isError` 结果经由流水线结算）。计时即这两个事件的 `time` 字段。两个事件都保持仅日志；模型上下文不受影响；格式保持 v0。
-- **桥接层调度器**：已提交的调用在启动那一刻经 `registry.executionMode` 分类（与 loop 所用完全相同、故障时默认判为不安全的 `isConcurrencySafe` 契约），并严格按提交顺序启动。所有有序阶段——start 事件追加、`prepare`（pre-execute/守卫）、队首 `finalize`/`finish` 提交（post-execute + 上下文延迟提交 + settle 事件追加）——由单通道驱动器独占执行，因此有序策略阶段彼此绝不重叠，只有 around-dispatch/工具体阶段并发运行，与原生 loop 的时序完全一致（`fillPool` 先 await `startCall` 再 `commitReady`）。连续被分类为可并行的调用可以重叠执行，上限为 `maxParallelSubCalls`（`Config` 字段，Loader schema 校验之外直接构造时也重新校验，默认值 10，即 loop 调度器自身的默认值；设为 `1` 即恢复串行分发）；独占调用则先排空池、独自运行，且其屏障保持到自身提交（含 post-execute）完成为止，与原生独占分组一致。run 结算时会中止仍在运行的分发，并放弃已排队未启动的分发（绑定调用被拒绝，不产生事件），随后排空到完全停稳——包括程序返回时已在途的提交——之后外层结果才结束该轮次。
+- **桥接层调度器**：已提交的调用在启动那一刻经 `registry.executionMode` 分类（与 loop 所用完全相同、故障时默认判为不安全的 `isConcurrencySafe` 约定），并严格按提交顺序启动。所有有序阶段——start 事件追加、`prepare`（pre-execute/守卫）、队首 `finalize`/`finish` 提交（post-execute + 上下文延迟提交 + settle 事件追加）——由单通道驱动器独占执行，因此有序策略阶段彼此绝不重叠，只有 around-dispatch/工具体阶段并发运行，与原生 loop 的时序完全一致（`fillPool` 先 await `startCall` 再 `commitReady`）。连续被分类为可并行的调用可以重叠执行，上限为 `maxParallelSubCalls`（`Config` 字段，Loader schema 校验之外直接构造时也重新校验，默认值 10，即 loop 调度器自身的默认值；设为 `1` 即恢复串行分发）；独占调用则先排空池、独自运行，且其屏障保持到自身提交（含 post-execute）完成为止，与原生独占分组一致。run 结算时会中止仍在运行的分发，并放弃已排队未启动的分发（绑定调用被拒绝，不产生事件），随后排空到完全停稳——包括程序返回时已在途的提交——之后外层结果才结束该轮次。
 - **客户端侧**：运行时的 `ToolCallTree` 把 start 事件存为 `RunningToolCall` 子级，并通过父级递归的 `subCalls` 投影出来（行组件从该形状推导出运行指示环，与原生运行中的调用处理完全一致）。其结算事件会原位替换私有索引中的条目，即使并行完成也保持启动顺序不变，并把 start 事件的 `time` 作为 `callTime`（时长来源）带入。未观察到对应 start 的结算事件（窗口切在事件对中间，或日志录制于 start 事件引入之前）会直接追加，因此旧日志仍能照常渲染。
-- **SDK 提示词**：面向模型的「调用按顺序执行」一句替换为真实契约（相互独立的安全调用可以在 `Promise.all` 下重叠执行；相互依赖的工作以 `await` 顺序衔接）；这是模型可见的变更，每一份 Code Mode 快照都已重新录制。
+- **SDK 提示词**：面向模型的「调用按顺序执行」一句替换为真实约定（相互独立的安全调用可以在 `Promise.all` 下重叠执行；相互依赖的工作以 `await` 顺序衔接）；这是模型可见的变更，每一份 Code Mode 快照都已重新录制。
 
 ## 曾考虑的替代方案
 
@@ -25,7 +25,7 @@ Status: implemented
 
 **在提交时而非入池时发出 start 事件。** 否决：提交即发 start 会把排了队却从未运行的调用显示成「运行中」，还得强行引入第三种「已放弃」终态事件才能使日志自洽。入池才发 start 保住了*已启动 ⇔ 恰好结算一次*这一不变式，且不需要第三种事件。
 
-**直接复用 loop 调度器的实现。** 否决：loop 调度的是一个已完整解析的批次，并按模型顺序提交结果；桥接层调度的则是一条开放式的提交流，其结果返回给程序，而不是进入 transcript（文本记录）。因此两者共享的只是*契约*（分类、池、屏障），而不是实现机制。
+**直接复用 loop 调度器的实现。** 否决：loop 调度的是一个已完整解析的批次，并按模型顺序提交结果；桥接层调度的则是一条开放式的提交流，其结果返回给程序，而不是进入 transcript（文本记录）。因此两者共享的只是*约定*（分类、池、屏障），而不是实现机制。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
index 8a92dd2fd1..451447736a 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
 2026-07-26-todo-parallel-in-progress.md: 8d047f33ab1aebd8c0de2a0a5e90e7efb1b28154
-2026-07-26-todo-parallel-in-progress.zh.md: 26b7081e7b4e3688a46a2857da91ba45328532a9
+2026-07-26-todo-parallel-in-progress.zh.md: 3d86a32fbd0d17d802a9f6d69ab49176a808c72f
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
index 26b7081e7b..3d86a32fbd 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
@@ -47,7 +47,7 @@ Status: implemented
 
 ## 暂缓项
 
-两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试契约的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
+两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试约定的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
index dade9b5d90..e433908f1f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-native-workspace-directory-picker.md
 2026-07-27-native-workspace-directory-picker.md: a36f7b239a9115fe5eb33472ec5084818a66e9f2
-2026-07-27-native-workspace-directory-picker.zh.md: bb3e2fc6f7c77c8ace97e53435297326f937e4e8
+2026-07-27-native-workspace-directory-picker.zh.md: cf30b4810fe5dc4d0ecfe30cd5eaf4b75ce3c23c
diff --git a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
index bb3e2fc6f7..cf30b4810f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-native-workspace-directory-picker.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 工作区管理器必须在选择回调运行前插入或更新返回的工作区。因此，新纳入的目录会立即显示其 basename。再次打开已注册的路径时，则保留该工作区现有的标题。
 
-## 交互契约
+## 交互约定
 
 - 在 macOS、Windows 和 Linux 上，选择器一次只允许选择一个目录。
 - 取消系统对话框不会显示提示，并返回 `null`。
diff --git a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
index b0e6012183..f65d3be4a5 100644
--- a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-skill-catalog-hot-refresh.md
 2026-07-27-skill-catalog-hot-refresh.md: 43c2da75aeb0031dffb5f47d7e76805baa2920e5
-2026-07-27-skill-catalog-hot-refresh.zh.md: 04d39dd767e5438c57d3eb29523a8ff26592465c
+2026-07-27-skill-catalog-hot-refresh.zh.md: e33e4adafcc664a22560dd2d5da1d9b7a890479a
diff --git a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
index 04d39dd767..e33e4adafc 100644
--- a/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md
@@ -36,7 +36,7 @@ TUI 将同一失效通知作为界面状态而非会话历史来消费。`skills
 - **监视每个 bundle 资源**：不予采纳，因为参考资料、脚本和产物都是按需加载的，不影响类别列表。宽泛的递归监视会增加失效、描述符压力和平台差异，却不能改善路由。
 - **将部分发现或失败发现发布为新目录**：不予采纳，因为暂时读取失败不能证明文件已删除。完整性位让面向模型的消费方保留最后一次完整目录，直到完整观察成功。
 - **保留公开的 `invalidateProvider(provider)`**：不予采纳，因为这会公开一项注册表变更方法，并要求调用方重复提供注册表已经持有的身份。发给工厂的闭包会将失效绑定到单个注册，并在释放后失去作用，因此观察方既不需要访问注册表，也不需要提供方身份。
-- **现在提取通用 Cordis 文件监视服务**：暂缓，直到另一个消费方确立可复用的服务契约。本地提供方标出了其 Chokidar 和缺失根目录观测边界，以便后续提取；skill 路径过滤以及对提供方失效闭包的调用仍属于 skill 专用逻辑。
+- **现在提取通用 Cordis 文件监视服务**：暂缓，直到另一个消费方确立可复用的服务约定。本地提供方标出了其 Chokidar 和缺失根目录观测边界，以便后续提取；skill 路径过滤以及对提供方失效闭包的调用仍属于 skill 专用逻辑。
 
 ## 影响
 
@@ -44,5 +44,5 @@ TUI 将同一失效通知作为界面状态而非会话历史来消费。`skills
 - TUI 的 `/skill:` 补全会收敛到同一份完整目录，而不会让每次按键都阻塞于发现；打开的斜杠命令名称草稿会在目录到达时刷新。
 - 目录消息采用仅追加、日志记录和全量列表快照。它们会保留较早的可重用 token；替换目录会显式停用陈旧名称，每次 digest 实际变化时，token 成本与当前目录大小成正比。
 - 仅修改正文不会产生目录消息。后续工具调用会看到当前内容，而先前工具结果仍准确记录模型之前加载的内容。
-- 缺失根目录轮询和 Chokidar 引入一个有人维护的运行时依赖、宿主 watcher 资源、有界检测延迟和部署可调参数。有界项目集合与资源销毁契约会限制这些成本。
+- 缺失根目录轮询和 Chokidar 引入一个有人维护的运行时依赖、宿主 watcher 资源、有界检测延迟和部署可调参数。有界项目集合与资源销毁约定会限制这些成本。
 - 远程或未来的可变提供方会保留各自注册作用域内的失效闭包，并通过自身观察机制调用它；注册表不会强制采用通用 watcher 或 TTL。
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
index 71c2325bb3..37c876275c 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-trajectory-inspection-ledger.md
 2026-07-27-trajectory-inspection-ledger.md: e3fc22234c1df449c99eac90af27de7da0b6f202
-2026-07-27-trajectory-inspection-ledger.zh.md: abf8fd3bcaeabba6061bd415acbe8ddefef7ac79
+2026-07-27-trajectory-inspection-ledger.zh.md: f167d818281c39a06e658c294f45e47d3ba40642
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
index abf8fd3bca..f167d81828 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
@@ -53,4 +53,4 @@ Status: implemented
 
 ## 后果
 
-轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、来源、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表契约锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
+轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、来源、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表约定锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
index 38dc165e7f..e3e6e045f8 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-typescript-sdk-and-sdk-subagent-backend.md
 2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: c5c6c4eac053e9a3adfa2a2a441ac492ba3391ac
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: 643ec36134a1ebe940da5de5b373fa0c25afcd42
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: fe0e93cd13d0decb8d6a95abb0c5feb141dcb78b
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
index 643ec36134..fe0e93cd13 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
@@ -34,7 +34,7 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 **让 `subagent-dsh-sdk` 直说裸 JSON-RPC、绕开客户端 SDK。** 会复制 SDK 存在意义所在的请求/通知配对、订阅扇出、超时与拆除逻辑；用户的要求明确是一个*使用* SDK 的后端，分层的回报是后端成为可复用客户端之上约 200 行的纯策略。
 
-**把 SDK 后端折进 `subagent-acp`、用传输开关区分。** 两个后端共享子进程生命周期，但线协议（ACP SDK 连接 vs harness JSON-RPC）、子进程契约（任意 ACP 代理 vs harness 运行时）、结果提取（`agent_message_chunk` 累积 vs 会话事件读取）毫无共享。配置判别子会把两个协议埋进一个包；真正共享的 provider 侧部分移入 subagent seam 的 `out-of-process.ts`，进程机制则住在 `dsh-subprocess` seam。
+**把 SDK 后端折进 `subagent-acp`、用传输开关区分。** 两个后端共享子进程生命周期，但线协议（ACP SDK 连接 vs harness JSON-RPC）、子进程约定（任意 ACP 代理 vs harness 运行时）、结果提取（`agent_message_chunk` 累积 vs 会话事件读取）毫无共享。配置判别子会把两个协议埋进一个包；真正共享的 provider 侧部分移入 subagent seam 的 `out-of-process.ts`，进程机制则住在 `dsh-subprocess` seam。
 
 **给 TS SDK 与 Python 对等的捆绑运行时解析。** Python 的载体解析是为了给没有 Node 的用户发 wheel。TypeScript 消费方按定义就有 Node，且仓库内消费方还有工作区；为尚不存在的消费方编造发行方案违反「只实现当前需求」的规则。推迟到真实的 npm 发行消费方出现时再处理。
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
index 5268ea62f9..077613e488 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-web-session-fork-actions.md
 2026-07-27-web-session-fork-actions.md: 578e59ec92e003fe5c8cdfe951a595f3a7371ecf
-2026-07-27-web-session-fork-actions.zh.md: d90124f6e6e164b0a1e0fce734f52976630cd848
+2026-07-27-web-session-fork-actions.zh.md: eb29b4358aefeb32c0ec291e1fac1948e2b0ec9d
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
index d90124f6e6..eb29b4358a 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-Session store 已提供按完成轮前缀创建子会话的 fork 原语，但 Web 端没有一份统一的交互契约。Session 行菜单只能表达「从最新完成轮分支」，消息 IconActions 还需要表达「从这条消息所在轮分支」；如果两处各自解释边界、切换与失败行为，同一个用户动作会形成两套语义。把 fork 子会话嵌套在源会话下还会让新选中的子会话依赖祖先展开态才能看见，并削弱 workspace 的手动排序模型。
+Session store 已提供按完成轮前缀创建子会话的 fork 原语，但 Web 端没有一份统一的交互约定。Session 行菜单只能表达「从最新完成轮分支」，消息 IconActions 还需要表达「从这条消息所在轮分支」；如果两处各自解释边界、切换与失败行为，同一个用户动作会形成两套语义。把 fork 子会话嵌套在源会话下还会让新选中的子会话依赖祖先展开态才能看见，并削弱 workspace 的手动排序模型。
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
index 7701e5fcc7..de5df14b25 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-web-session-search.md
 2026-07-27-web-session-search.md: 4c49c0e61ca1b15181e767e4f65353312f8a3e3f
-2026-07-27-web-session-search.zh.md: e9aa00656443e544bad623540d07ff785b1285ef
+2026-07-27-web-session-search.zh.md: d4b06ec306ab8a4f6759f007cc133622e4cb63ee
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
index e9aa006564..d4b06ec306 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md
@@ -10,7 +10,7 @@ Web 侧边栏会展示会话标题及其 Workspace 归属，但无法根据只
 
 ## 决策
 
-Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据库挂载 [`@deepseek-ai/dsh-session-query-sqlite`](../../../../packages/session-query/session-query-sqlite/README.md)。服务启动时处于 ACTIVE 状态，而其 `node:sqlite` 模块与连接私有句柄分别要到首次内容查询才会导入和打开。这让 Node 22 的启动输出在使用搜索前不会出现 SQLite 实验性警告，但并不承诺在首次搜索导入该模块时抑制警告。每个服务实例都独占自己的索引，因此并行 CLI 或 Web 调用可维持 SQLite 后端的单一所有者契约，又不会留下进程级派生文件。数据库从空状态启动，并在该首次查询时惰性对齐实时会话与持久化会话。它仍是与规范 JSONL 持久化相互独立的可丢弃派生索引。
+Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据库挂载 [`@deepseek-ai/dsh-session-query-sqlite`](../../../../packages/session-query/session-query-sqlite/README.md)。服务启动时处于 ACTIVE 状态，而其 `node:sqlite` 模块与连接私有句柄分别要到首次内容查询才会导入和打开。这让 Node 22 的启动输出在使用搜索前不会出现 SQLite 实验性警告，但并不承诺在首次搜索导入该模块时抑制警告。每个服务实例都独占自己的索引，因此并行 CLI 或 Web 调用可维持 SQLite 后端的单一所有者约定，又不会留下进程级派生文件。数据库从空状态启动，并在该首次查询时惰性对齐实时会话与持久化会话。它仍是与规范 JSONL 持久化相互独立的可丢弃派生索引。
 
 宿主网关通过现有的类型化 RPC 栈公开 `session.search`。它根据 `session.list` 使用的同一组可见摘要推导授权集合，向 `ctx.sessionQuery.searchSessions` 请求全局排序后的当前 surface `user/message` 和 `assistant/message` 匹配项，并持续消费提供方分页，直到获得 20 个已授权会话及一个前瞻项，或结果流耗尽。首个提供方页面请求 20 个命中；如果第一页返回 `SESSION_QUERY_INVALID_LIMIT`，页面大小会依次折半为 10、5、2、1，并在续传和陈旧世代重启中沿用探测所得的大小。每个命中的会话 id、最佳匹配会话 id、surface 和事件类型都会经过重新校验，其 snippet 才能离开宿主。发出的 snippet 最多包含 240 个 Unicode 码点；宿主与传输 schema 共用协议边界及码点安全的截断辅助函数，而传输 schema 会在客户端解析时独立强制执行 snippet 上限。将可能很大的授权集合排除在 SQLite 绑定之外，可避开可移植变量上限，同时保持全局排序。响应仍只有一个有界页面；`hasMore` 会指示 UI 提示用户缩小查询范围，而不是公开分页能力。陈旧的续传会丢弃当前尝试的部分结果、去重条目和游标，然后依据原始可见性快照从第一页重新开始。上限探测与陈旧重试共用 100 次提供方调用的限制（因此最多检查 2,000 个命中）；如果某页命中数超过其请求的上限、续传游标重复，或用尽该调用预算后结果流仍未耗尽，都会直接返回 `internal` 业务错误，不返回部分结果。载体信号会取消已被取代的工作，包括持久化列表枚举、分批受限执行的冷会话元数据 stat，以及每一次提供方调用；即使同时收到上限拒绝或陈旧拒绝，也以取消为准。查询服务缺失或索引／查询故障无法恢复时，仍作为业务错误处理，不会修改规范会话存储。
 
@@ -20,7 +20,7 @@ Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据
 
 内容匹配沿用 SQLite 后端经过规范化的字面 token／短语语义。共享语义投影会排除推理（reasoning）块，因此 UI 搜索绝不会将模型的私有推理作为命中或 snippet 返回；派生索引的 schema 版本会随之前进，使现有持久化索引重建并移除先前的这些文档。FTS5 运算符只作为数据处理，此搜索界面不提供拼写错误纠正、模糊匹配、前缀匹配或任意子串扩展。特别是，`unicode61` 分词器可能将一段连续中文视作单个 token，因此不保证 `搜索` 之类的较短查询能匹配 `会话搜索功能` 的内部片段。标题与 Workspace 匹配仍采用普通的客户端子串匹配。
 
-## 故障与可见性契约
+## 故障与可见性约定
 
 搜索绝不会扩大会话可见范围：没有可供服务的 cwd 的冷会话会被排除，原因与它们不出现在 `session.list` 中相同；只有 id 位于这条基线中的提供方命中才能离开宿主。被遮蔽事件和纯日志事件、消息内容之外的工具事件、错误、待办事项及其他追踪记录都不会产生 UI 命中结果。
 
@@ -29,8 +29,8 @@ Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据
 ## 曾考虑的替代方案
 
 - **在浏览器中扫描每个会话的历史记录**：不予采纳，因为这会让 UI 承担传输与折叠开销；除非加载冷态日志，否则还会漏掉这些日志；并会重复实现已经由 `ctx.sessionQuery` 负责的语义提取与源对齐。
-- **首版即加入 trigram 或模糊搜索**：不予采纳，因为这会改变索引大小、排序、短查询行为与产品预期。trigram 本身也无法解决双字查询。首版沿用现有后端契约，将召回扩展留作另一项基于度量结果的决策。
-- **返回事件地址并跳转至确切匹配位置**：本版不予采纳，因为对话虚拟化与稳定的事件导航需要单独的 UI 契约。会话级导航本身已有价值，无需让搜索与这项工作耦合。
+- **首版即加入 trigram 或模糊搜索**：不予采纳，因为这会改变索引大小、排序、短查询行为与产品预期。trigram 本身也无法解决双字查询。首版沿用现有后端约定，将召回扩展留作另一项基于度量结果的决策。
+- **返回事件地址并跳转至确切匹配位置**：本版不予采纳，因为对话虚拟化与稳定的事件导航需要单独的 UI 约定。会话级导航本身已有价值，无需让搜索与这项工作耦合。
 - **在侧边栏公开游标分页**：不予采纳，改为固定显示前 20 条结果并提示缩小查询范围；这样可使交互与取消状态保持有界。
 
 ## 后果
@@ -41,4 +41,4 @@ Web 与 headless 共用的组合会使用 `openAt: first-search` 和内存数据
 
 ## 测试
 
-宿主测试将请求与响应校验、可见会话过滤、事件和 surface 过滤、结果与 snippet 边界、共享调用预算内的自适应提供方上限、沿用探测所得上限的陈旧世代重启、游标与跨页去重行为、取消优先级及故障映射固定为契约。SQLite 生命周期测试将启动时激活、首次搜索时的打开与失败、共享就绪状态以及未打开状态下的处置固定为契约；语义提取测试与 SQLite／fixture 搜索测试将排除仅存在于推理中的文本固定为契约。Node 22 兼容性门禁会构建 CLI 与 Web 产物，在移除环境级警告抑制并采用隔离的临时 home／提供方环境后，以普通 Node 启动随产品交付的 `dsh web`／`AppCLIEntry` 组合，等待启动完成并稳定，再沿随产品交付的信号路径对其执行 dispose（资源释放）。fixture（测试前置数据）、运行时与 UI 测试将以匹配位置为中心的有界 snippet、无状态委托、500 个 code unit 的查询边界、防抖／中止／陈旧响应行为、本地回退、合并顺序、去重、英文文案、ARIA 树成员关系、行渲染与导航语义固定为契约。无密钥的组装层 Web 测试会在保留惰性打开配置的同时，播种一段尚未打开的持久化对话，通过 SQLite 索引按可见消息内容找到它，捕获侧边栏结果，打开该会话，并验证查询条件仍然保留。
+宿主测试将请求与响应校验、可见会话过滤、事件和 surface 过滤、结果与 snippet 边界、共享调用预算内的自适应提供方上限、沿用探测所得上限的陈旧世代重启、游标与跨页去重行为、取消优先级及故障映射固定为约定。SQLite 生命周期测试将启动时激活、首次搜索时的打开与失败、共享就绪状态以及未打开状态下的处置固定为约定；语义提取测试与 SQLite／fixture 搜索测试将排除仅存在于推理中的文本固定为约定。Node 22 兼容性门禁会构建 CLI 与 Web 产物，在移除环境级警告抑制并采用隔离的临时 home／提供方环境后，以普通 Node 启动随产品交付的 `dsh web`／`AppCLIEntry` 组合，等待启动完成并稳定，再沿随产品交付的信号路径对其执行 dispose（资源释放）。fixture（测试前置数据）、运行时与 UI 测试将以匹配位置为中心的有界 snippet、无状态委托、500 个 code unit 的查询边界、防抖／中止／陈旧响应行为、本地回退、合并顺序、去重、英文文案、ARIA 树成员关系、行渲染与导航语义固定为约定。无密钥的组装层 Web 测试会在保留惰性打开配置的同时，播种一段尚未打开的持久化对话，通过 SQLite 索引按可见消息内容找到它，捕获侧边栏结果，打开该会话，并验证查询条件仍然保留。
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index 4453cca8eb..e6cb63c10d 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-web-subagent-conversations.md
 2026-07-27-web-subagent-conversations.md: 46c4949c56ebffe78e5ffda126a5784a1c648421
-2026-07-27-web-subagent-conversations.zh.md: 6b2d7bbec1133cdeb2d0cd31a6f9a43b068d21f5
+2026-07-27-web-subagent-conversations.zh.md: f06e5f38ba49d35ac28582f1ad3ff5eebc8ace15
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index 6b2d7bbec1..f06e5f38ba 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 由会话支撑的 subagent 具有持久化身份、持久化 transcript（文本记录）与直接 child 目录，但普通会话谱系无法将它们与 fork 区分开，也无法证明其描述符 mode 与继续执行授权。否则，绑定到 agent（智能体）的通用 Host 操作可能在其直接 parent 继续执行 owner 之外恢复或驱动 child。
 
-浏览器必须遵守[可继续 subagent 契约](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)：一个可继续 child 在进程内最多只能有一项 Activation，只能通过确切的存活直接 parent 接受后续工作，并将 agent inbox 用作唯一的 FIFO。查看历史不得创建 Activation。inbox 消息一经接受，HTTP 调用方既不拥有其执行过程，也不会获得取消句柄。
+浏览器必须遵守[可继续 subagent 约定](../../implemented/feature/2026-07-28-continuable-subagent-conversations.md)：一个可继续 child 在进程内最多只能有一项 Activation，只能通过确切的存活直接 parent 接受后续工作，并将 agent inbox 用作唯一的 FIFO。查看历史不得创建 Activation。inbox 消息一经接受，HTTP 调用方既不拥有其执行过程，也不会获得取消句柄。
 
 UI 还必须保留[持久化目录](../../implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)的成员、mode 与 diagnostic。共享服务报告采用实时优先规则的语料活动状态，而 Web 投影会将其替换为确切 child Agent driver 的 `running` 或 `inactive` 状态。这两种活动状态都不是持久化结果，也不承诺继续执行会成功。
 
@@ -20,7 +20,7 @@ Web 产品通过页头操作公开选中会话中由会话支撑的直接 subage
 
 通用 Host 领域遵守同一所有权边界。`session.history` 与 `session.fork` 的源端会读取已附加 Session 或检查持久化存储，而不获取 Agent；history 从所检查的确切前缀归并冷态投影值，fork 则发布一个普通的独立会话。绑定到 Agent 的通用会话、命令与目标路由会对由会话支撑的 subagent 返回 `agent-busy`；显式 id 的 `session.create` 接纳与仅针对已附加会话的队列控件亦然。拒绝分类器接受粗粒度 `origin` 标记、会话自身后缀中的 `subagent/descriptor`，或 parent 对其确切的存活运行时所有权；这些信号只会阻止通用路径取得所有权，绝不取代目录 mode 或直接 parent 授权。
 
-停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)，该契约会暂停而非丢弃待处理工作。one-shot child 在 Web 端仍不可取消。
+停止一个已寻址 child 绝不回退到 `session.cancel`。`SubagentService.followup()` 只负责消息被 inbox 接受前的准入，不授予取消句柄；正在运行的可继续 child 通过专用的 `subagent.interrupt` 路由停止，遵循[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)，该约定会暂停而非丢弃待处理工作。one-shot child 在 Web 端仍不可取消。
 
 本决策涵盖 Web 端发现、transcript 查看与经 parent 授权的用户继续交互。它不会让 subagent 成为用户独立所有的对象；这类产品仍然属于[交互式 side session](../../proposed/feature/2026-07-08-interactive-side-sessions.md)。
 
@@ -28,14 +28,14 @@ Web 产品通过页头操作公开选中会话中由会话支撑的直接 subage
 
 Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-14602&p=f)、[层级展开](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=383-15917&p=f)与 [child 对话](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Harness?node-id=388-18584&p=f)画框是非规范性的交互与视觉参考。本记录负责生命周期、协议与失败语义。
 
-| 设计意图 | 已交付契约 |
+| 设计意图 | 已交付约定 |
 | --- | --- |
 | 会话页头可打开紧凑的 child 列表。 | 触发器会汇总仅含 subagent 的完整后代谱系；树按服务顺序显示每个直接目录条目，包括已禁用的 diagnostic。 |
 | 选择一行会复用对话 UI。 | 已寻址历史绝不激活 child；只有 parent 存活的可继续行才保留普通输入框。 |
 | 嵌套 agent 会逐层展开。 | 每行携带一层 `hasChildren` 快照；展开时会立即预留已知直接后代行，随后仍只加载该行的直接目录，并保留其自身的 parent 地址。 |
 | 条目显示 label、状态、token 用量与活跃耗时，同时避免侧边栏条目重复。 | mode 与 `running`／`inactive` 活动状态会同时以文字和视觉呈现；可选 title、持久化 token 用量与活跃轮次耗时来自列表保留的投影值。紧凑耗时从一天起省略更小的单位，而悬停和无障碍名称仍保留精确的整秒数。`SessionHeader.origin` 会移除重复的导航条目，但不授予任何功能权限。 |
 
-## 产品契约
+## 产品约定
 
 只有当完整的直接目录空响应与会话摘要投影相符，二者均表明没有已知的 subagent 后代时，才不显示页头操作。其触发器会统计经不间断的 `origin: 'subagent'` 谱系可达的每个已知会话摘要后代，在普通 fork 处停止，并在任一计入统计的后代处于 `running` 时显示活动仍在进行。由于普通侧边栏行会隐藏 origin 为 subagent 的会话，Workspace 浏览器会在每个可见的普通行上索引同一条不间断谱系：任何运行中的后代都会让该行显示蓝色活动指示器，并在悬停与无障碍文本中给出确切数量，同时不会把空闲 parent 描述为正在运行。普通 fork 会开启单独的聚合子树。待处理交互优先于 parent 的运行中状态；二者无论哪一项存在都会保持为主要状态，而后代活动则成为悬停与无障碍状态中的第二项。两者均不存在时，后代活动优先于未查看的完成提醒；最后一个运行中的后代停止后，该提醒会恢复。每个健康的直接目录行都携带读取时的 `hasChildren` 提示，该值只根据持久化 `origin: 'subagent'` 的直接谱系 header 派生；正常的健康与 diagnostic subagent 候选都会携带该标记，而普通 fork 不会。该预查不读取任何后代事件日志，展开后仍以描述符支撑的目录为权威依据。当摘要在该目录尚不存在时或在一次陈旧的空响应后确认已有后代时，该操作会保持可见，并且在打开它以刷新目录之前仅显示禁用的加载行；仅由摘要支撑的行绝不会提供导航能力。UI 会在交互前就省略已知叶子节点的展开控件；该提示不承诺 child 会一直是叶子。已展开的直接目录加载期间，已知谱系会为每个直接后代预留一行禁用的加载行，而不会递归获取后代目录。随后树会呈现可继续与 one-shot 行；one-shot 的可选 label 缺失时，回退到其会话 id。损坏、不受支持或不可用的候选仍以禁用的 diagnostic 行显示。
 
@@ -45,11 +45,11 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 选择一行后，系统会先记录其确切地址，再打开常驻客户端 `Session`。历史分页、事件 fold、工具渲染意图、title 与实时 mux 归并都会复用普通对话机制。面包屑导航使用目录 label，只会沿 `origin: 'subagent'` 行的父链接逐级回溯，包含第一个普通 owner，并让普通 fork 保持单层。从已寻址 subagent 创建 fork 时，会生成具有直接源谱系的普通 fork，并将其附加到最近拥有 Workspace 的祖先。目录是一棵 ARIA 树，支持懒加载式 ArrowRight／ArrowLeft 展开与折叠、线性 ArrowUp／ArrowDown 导航、Home／End、Escape 以及焦点恢复。
 
-one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
+one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
 
 已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行 seam 之外激活持久化 child 历史。
 
-## 宿主适配器与协议契约
+## 宿主适配器与协议约定
 
 `@deepseek-ai/dsh-host-apiproxy` 拥有浏览器安全的 `subagents` 域：
 
@@ -63,7 +63,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 普通 `session.history` 路由对于普通会话和 subagent 会话同样只执行观察，但它既不携带目录地址，也不授予继续执行权限。每条需要 Agent 的普通路由都会在恢复冷会话前经过共享所有权栅栏；`session.cancel` 与 `session.updateQueue` 会直接执行同一检查，因为它们有意只查询已附加的 Agent。
 
-适配器仍位于 `dsh-host-apiproxy`；`dsh-host-webserver` 仍作为载体。浏览器代码通过现有连接包（package）导入契约，绝不直接访问宿主 `ctx`，从而保持 [GUI RPC 分层](../../implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)。
+适配器仍位于 `dsh-host-apiproxy`；`dsh-host-webserver` 仍作为载体。浏览器代码通过现有连接包（package）导入约定，绝不直接访问宿主 `ctx`，从而保持 [GUI RPC 分层](../../implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)。
 
 ## 客户端对象层与呈现
 
@@ -89,7 +89,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 **自动恢复缺失的 parent。** 不予采纳，因为继续执行要求确切的存活直接 parent。child 导航不得改变 parent 生命周期。
 
-**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断契约](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
+**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
 
 **只显示可继续 child。** 不予采纳，因为持久化目录有意描述由会话支撑的两种 mode。one-shot transcript 即使绝不接受后续消息，仍然有用。
 
@@ -114,4 +114,4 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 - parent 可用性、child 活动状态与 `hasChildren` 都是快照。列出之后，发布、dispose、其他发送方或其他进程都可能抢先改变状态；类型化提示词失败仍属预期行为。
 - child 可能在历史获取与 mux 订阅之间发布，因此现有序号归并也涵盖从冷态转为存活的已寻址路径。
 - 持久化 origin 会为 child header 与列表投影添加一个有意保持弱约束的产品分类字段；它不能变成授权捷径。
-- 除对正在运行的可继续 child 的当前轮次 Stop（[中断契约](2026-08-06-continuable-subagent-interrupt.md)）之外，UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
+- 除对正在运行的可继续 child 的当前轮次 Stop（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）之外，UI 不提供 child 取消、持久化结果、Activation 身份、删除或可独立交互的离线 mode，其文案不得暗示这些功能已经存在。活跃轮次耗时度量的是已记录工作，而非 Activation 驻留时间。
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index 82639d4aa8..cf0c2038cb 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
 2026-07-28-continuable-subagent-conversations.md: 56d9abb2b09577b2fba14b9a655a941417e0c493
-2026-07-28-continuable-subagent-conversations.zh.md: 77f497ceeef35dcc519242dca30c81759cc3b907
+2026-07-28-continuable-subagent-conversations.zh.md: cd73d9a3b5ff1b9671a7b08ed1482fa1ad45f48e
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index 77f497ceee..cd73d9a3b5 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -54,7 +54,7 @@ inbox 接受消息前发生任何失败，操作都会在不返回任何 id 的
 
 空闲的历史会话没有 `AgentHandle`。第一条通过鉴权的 `next-turn` 投递会根据持久化会话恢复激活，并将消息提交到其 inbox。冷恢复使用经过身份认证的确切在线 parent Agent 执行鉴权；当该 parent 有激活时，还使用它建立所有权，但绝不使用 parent 执行重建。
 
-激活作为消费方会直接持有已发布的 `AgentHandle` 直至结算，而管理器的私有 activation-owner 作用域则是其 Cordis 结构化所有者。可继续 subagent 路径不创建任何中间的带结果执行包装层，包括 `SubagentRun`；一次性委派保持不变，且不属于该生命周期。远程提供方不在此处的范围内，引入时需要单独的激活所有权契约。激活 dispose 后，历史会话不消耗运行时内存。
+激活作为消费方会直接持有已发布的 `AgentHandle` 直至结算，而管理器的私有 activation-owner 作用域则是其 Cordis 结构化所有者。可继续 subagent 路径不创建任何中间的带结果执行包装层，包括 `SubagentRun`；一次性委派保持不变，且不属于该生命周期。远程提供方不在此处的范围内，引入时需要单独的激活所有权约定。激活 dispose 后，历史会话不消耗运行时内存。
 
 ### 激活生命周期
 
@@ -113,7 +113,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ### 报告投递扩展
 
-可选的 child 作用域 `report(output)` 工具不会改变 Activation 驻留状态，也不会增加另一条队列。它每轮可调用零次或多次，不允许指定接收方，而是推导在线的直接 parent；投递采用静默注入还是唤醒 parent follow-up，由部署配置选择。[report 工具 Agent Note](2026-07-30-continuable-subagent-report-tool.md)规定其权限、确认、设置贡献和投递契约。
+可选的 child 作用域 `report(output)` 工具不会改变 Activation 驻留状态，也不会增加另一条队列。它每轮可调用零次或多次，不允许指定接收方，而是推导在线的直接 parent；投递采用静默注入还是唤醒 parent follow-up，由部署配置选择。[report 工具 Agent Note](2026-07-30-continuable-subagent-report-tool.md)规定其权限、确认、设置贡献和投递约定。
 
 ### 延后的 steering（中途引导）
 
@@ -143,7 +143,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ### 范围
 
-本版本覆盖可继续的进程内 child，一次性委派保持不变。远程提供方必须具备单独的激活 handle，以及等价的认证控制与 child-first 完全停稳契约，才能支持同样的行为。
+本版本覆盖可继续的进程内 child，一次性委派保持不变。远程提供方必须具备单独的激活 handle，以及等价的认证控制与 child-first 完全停稳约定，才能支持同样的行为。
 
 它不新增 host-user 继续执行、subagent steering 操作、持久化邮箱、跨进程 lease、中断 inbox 工作的自动回放、团队权限、工作流权限、公开驻留查询、新的在线激活数量或后代总数限制，以及运行时缓存；后来的[当前轮次中断](2026-08-06-continuable-subagent-interrupt.md)在此生命周期之上补充了唯一的公开停止操作。现有委派深度策略保持不变。可选的 child 到 parent 报告是后续消费该生命周期的功能，不属于基础可继续能力。
 
@@ -169,7 +169,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 **在没有 host 消费方的情况下暴露 host-user follow-up。** 公开的权限铸造方法和用户分支可以在没有历史 parent 的情况下实现冷恢复，但没有生产 host 适配器调用该操作。在具体的经认证宿主交互能够收到私有能力之前，该 seam 只接受确切的在线 parent。
 
-**返回 subagent 专属的投递路由。** `started`、`queued` 和 `resumed` 等标签重复了激活与 inbox 状态，却没有给调用方提供独立结果。复用 `MessageId` 和现有 inbox 事件，可以让投递关联继续由其所属的 Agent 契约承载。
+**返回 subagent 专属的投递路由。** `started`、`queued` 和 `resumed` 等标签重复了激活与 inbox 状态，却没有给调用方提供独立结果。复用 `MessageId` 和现有 inbox 事件，可以让投递关联继续由其所属的 Agent 约定承载。
 
 **使用 child 引用计数。** 计数无法识别哪个 child 仍持有拆卸工作，也允许重复递减错误。身份集合会显式保留取消和 dispose 义务。
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.i18n.yaml
index 89acd445d8..a5c375dc02 100644
--- a/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.md
 2026-07-28-sdk-max-output-tokens.md: 3ba3e226d64b7d3d192d67bd88af463d2b0d9dc5
-2026-07-28-sdk-max-output-tokens.zh.md: 805c34f33946638bf5b9073f8bdbce156f7a36d3
+2026-07-28-sdk-max-output-tokens.zh.md: c472c640eb0bb3d8b732b2653f94889626ba6dcd
diff --git a/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.zh.md b/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.zh.md
index 805c34f339..c472c640eb 100644
--- a/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-sdk-max-output-tokens.zh.md
@@ -28,6 +28,6 @@ Python 与 TypeScript SDK 可以选择提供方和模型，却无法限制对话
 
 ## 后果
 
-SDK 调用方无需修改 Cordis 组合即可限制模型输出，直接创建 Agent 也使用同一套经过校验的 `AgentOptions` 契约。该上限在持久化请求 header 中可见，并以 `GenerateOptions.maxTokens` 到达提供方适配器；DeepSeek 序列化会将其映射为 `max_tokens`。
+SDK 调用方无需修改 Cordis 组合即可限制模型输出，直接创建 Agent 也使用同一套经过校验的 `AgentOptions` 约定。该上限在持久化请求 header 中可见，并以 `GenerateOptions.maxTokens` 到达提供方适配器；DeepSeek 序列化会将其映射为 `max_tokens`。
 
 一个 SDK 运行时只有一个默认上限。需要不同上限的调用方应运行独立的运行时实例，或通过 agent options 显式覆盖某个进程内子级。达到上限时仍产生现有的 `max-tokens` 停止原因；将其映射为 `ok` 还是 `error` 仍由部署策略决定。
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
index ea1b12edeb..1d67db187c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
 2026-07-28-skill-invocation-policy.md: 9d34bcb77ab7933ef9bf4e9b5227dade39903667
-2026-07-28-skill-invocation-policy.zh.md: 4b190dbd095306d41837bd9734049f5e3d85da72
+2026-07-28-skill-invocation-policy.zh.md: 687bd582ce3f4c74e50d36640afc6b683e289c90
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
index 4b190dbd09..687bd582ce 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
@@ -8,11 +8,11 @@ Status: implemented
 
 skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会移除禁止模型调用的 skill，而 `ctx.skills.get()` 仍是不过滤内容的可信 loader。该设计足以支持由模型发起的加载，却无法表示与 Claude 兼容的四类 skill：仅向用户公开、仅向模型公开、同时向两者公开，或者两者均不公开。TUI 从面向模型过滤后的列表中生成用户自动补全，并允许通过 `get()` 加载任意精确名称，这进一步放大了两类调用策略不匹配的问题。
 
-本地解析器还将一种内部驼峰式拼写暴露为 frontmatter。若要支持既有的负向字段 `disable-model-invocation` 和正向字段 `user-invocable`，需要建立持久且对称的领域表示，同时避免把所有可能出现的 YAML 键都变成跨包的无类型契约。
+本地解析器还将一种内部驼峰式拼写暴露为 frontmatter。若要支持既有的负向字段 `disable-model-invocation` 和正向字段 `user-invocable`，需要建立持久且对称的领域表示，同时避免把所有可能出现的 YAML 键都变成跨包的无类型约定。
 
 ## 决策
 
-`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入 seam 可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行契约后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
+`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入 seam 可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行约定后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
 
 `ctx.skills.list()` 返回所有胜出的摘要，不再替任何调用接口选择策略。`isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 保持策略无关，因为可信内部调用方可能需要任意定义；对外消费方则必须在展示或加载 skill 之前执行自身对应的判定函数。模型工具和 TUI 会在调用 `get()` 前检查与调用策略无关的摘要，随后再次检查已加载的定义：被拒绝的名称绝不会进入定义加载流程，发现与加载之间发生策略变更也无法暴露该 skill 的正文。
 
@@ -39,12 +39,12 @@ skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会
 
 **在 `ctx.skills.get()` 内执行调用策略。** 不予采纳，因为 `get()` 无法判断调用方是模型工具、人类命令还是可信编排逻辑。在此处过滤还会使两个接口均禁止调用的组合无法被检查或管理。
 
-**将驼峰式 frontmatter 作为别名处理。** 不予采纳，因为外部格式遵循采用 kebab-case 的 Claude skills 契约，而本仓库尚未发布，无需承担兼容义务。快速失败可以避免暗中保留不符合标准的拼写。
+**将驼峰式 frontmatter 作为别名处理。** 不予采纳，因为外部格式遵循采用 kebab-case 的 Claude skills 约定，而本仓库尚未发布，无需承担兼容义务。快速失败可以避免暗中保留不符合标准的拼写。
 
 **增加由浏览器端直接调用 skill 的 RPC。** 本次改动不予采纳，因为现有浏览器流程插入的是模型引用，而非已经加载的指令正文。因此，该流程应当取模型与用户调用策略的交集；直接由用户加载的接口需要单独设计协议与日志记录方式。
 
 ## 后果
 
-提供方与运行时注册对外提供小而类型明确的调用契约，同时本地 YAML 仍可扩展。每个新的发现消费方都必须明确选择模型判定函数、用户判定函数、两者的交集，或可信且不过滤的访问方式；如果遗漏这项选择，评审时可以直接看出问题，而不会再被注册表行为掩盖。
+提供方与运行时注册对外提供小而类型明确的调用约定，同时本地 YAML 仍可扩展。每个新的发现消费方都必须明确选择模型判定函数、用户判定函数、两者的交集，或可信且不过滤的访问方式；如果遗漏这项选择，评审时可以直接看出问题，而不会再被注册表行为掩盖。
 
 无密钥 ACP（Agent Client Protocol）快照固定了模型目录的变更：其中包含仅允许模型调用的 skill，并排除仅允许用户调用的 skill。组装后的无密钥 TUI 快照按精确名称发现并加载一个仅允许用户调用的 skill，随后在加载正文前拒绝一个仅允许模型调用的 skill；真实 Loader/PTY 冒烟测试通过随产品交付的终端进程证明了同一条仅允许用户调用的路径。真实宿主上的 Chromium 快照固定了浏览器在全部四种策略组合下的交集行为。TUI 单元测试覆盖这些组合以及资源释放竞态；注册表、本地解析器、模型工具和 API 代理测试则覆盖默认值、支持的布尔写法、格式错误的值、旧键拒绝、精确名称加载时的策略执行，以及浏览器侧的策略交集。
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
index 53dba67c61..77df231e1c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
 2026-07-28-web-terminal-card.md: 026b32fed2c79533abfadc58314e2844ff556414
-2026-07-28-web-terminal-card.zh.md: 4c74d880c5795cf85f32391b27e6ffd2c5074870
+2026-07-28-web-terminal-card.zh.md: 3a9025b3f2dee546253d923c121df0e04da73414
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index 4c74d880c5..3a9025b3f2 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -12,9 +12,9 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 ## Decision
 
-`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图契约交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为契约把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
+`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图约定交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为约定把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
 
-该组件的契约：
+该组件的约定：
 
 - **提示符行，每条命令行一行。** 命令的每一行各占一行：标签，其后原样跟随该行。因此一个在两行上承载两条 shell 命令的 `command` 就读作它本身的两条命令，而不是被压成一行并省略号截断。标签取 cwd 的最后一段路径，当 cwd 等于 `home` prop 时取 `~`——浏览器没有 `$HOME`，因此由调用方提供绝对家目录，不提供时该折叠不生效。视图不带 cwd 时渲染一个纯 `$`。末尾换行是终止符，不是一条空的末命令。只有**第一行**携带该标签：视图只知道一个工作目录——调用开始处的那个——而后面的行完全可能在别处运行，命令里一个 `cd` 就足以改变它。把标签在各行重复，等于陈述一个此处无人知晓的逐行目录，这与运行状态点只出现一次是同一个理由。其余行保留一个裸 `$`，因此它们仍读作提示符。
 - **整次调用一枚运行状态点，位于第一行。** 它是 `StateDot` 四种状态中的三种：运行期间为追逐动画，与渲染状态徽章相同的退出状态为红色，干净落定为绿色——与工具行行首图标使用同一个指示器，因此一行与其自身的卡片不可能对同一条命令产生分歧。该状态点存在的理由是：读者对一条 shell 命令的第一个问题就是它是否仍在运行；没有它时，这一点只能从「没有输出」推断，而一条落定后无输出的命令看起来也一样。它以脱离文档流的方式落在卡片以**自身左内边距**预留的落区里，因此既不会缩进其命令，也不依赖命令自身的文本度量来与之对齐。该预留用 padding 而非 margin，是因为每个渲染点都会整条重写 `margin` 来设定自己的缩进——那会静默取消基于 margin 的落区，并让容器把状态点裁掉。无论有多少行，都只有一枚：视图携带的退出状态属于整次调用，而 bash 不报告逐条命令的状态，因此每行一枚状态点就等于在断言——一条在失败调用中其实成功了的命令行自身失败了。那一处视觉隐藏的文本标签具有相同的作用域，因为 `StateDot` 是 `aria-hidden`，而每行一个标签会被辅助技术读成好几个各自独立的结果。
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
index 35c6e070a6..ade585187c 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
 2026-07-29-ask-question-web-presentation.md: 11471bba08b723620b83af0e14e64a759d11c520
-2026-07-29-ask-question-web-presentation.zh.md: 50f0dffa1a1f9cbd29b676cc1f21ba0298f6bf23
+2026-07-29-ask-question-web-presentation.zh.md: 6957d34fa5d3769340be9798998e59496e4b7f44
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
index 50f0dffa1a..6957d34fa5 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
@@ -38,7 +38,7 @@ Web GUI 已经可以通过 `QuestionComposer` 的输入区接管收集回答，
 
 行内裁决字符串是问题流程仅剩的硬编码英文面；将其本地化是推迟的后续工作。在审批输入区接管交付之前，`PendingCard` 仍是可见但不可操作的审批占位。
 
-`ui-question` 新增 `dsh-client-locale` 依赖和此前没有的 inject face；其契约（`QuestionComposerInjected`）与消费者一起放在 `contract/slots.ts`。
+`ui-question` 新增 `dsh-client-locale` 依赖和此前没有的 inject face；其约定（`QuestionComposerInjected`）与消费者一起放在 `contract/slots.ts`。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml
index 8df627311b..327f20a740 100644
--- a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.md
 2026-07-29-directory-picker-adaptive-default.md: 7ff6529bb8e445f63343b1019ac520f56b19d5e4
-2026-07-29-directory-picker-adaptive-default.zh.md: fd3f1473beabdc14b4eea84efdb3fe25116f759d
+2026-07-29-directory-picker-adaptive-default.zh.md: 17cb912df472105ec3b34faa8baa36cf527d6173
diff --git a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md
index fd3f1473be..17cb912df4 100644
--- a/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-directory-picker-adaptive-default.zh.md
@@ -25,6 +25,6 @@ Status: implemented
 
 - 随附的 web GUI 开箱即自适应：有人值守的本地宿主 → OS 选择器；SSH 启动、全网卡绑定、无头宿主、不支持的平台，或没有选择器二进制的 Linux → 应用内浏览器。探测是从启动上下文推断操作者位置，而任何启动侧信号都无法证明这一点：脱离的 tmux 会话会丢失 `SSH_*`；非 Aqua 的 darwin 进程仍被算作有显示；而 `ssh -L` 形态（在工作站本地启动、之后经转发端口访问，从 `127.0.0.1` 到达）会判定 `native`，把选择器弹在无人值守的工作站上——即便按连接自适应也修不了最后这一情形。错误的 `native` 选择会退化为后端既有的可重试失败对话框；处于这些形态的部署直接组合 `-browse`。
 - 选择器按运行时字符串（已导出的 `BACKEND_PACKAGES`）挂载后端，yml 行扫描看不到这一点；因此 `verify-cordis-config` 要求每个挂载 `-auto` 的组合把两个后端都声明为依赖，使无密钥的 Linux CI（它永远只会判定出 `browse`）无法掩盖被丢掉的 `-native` 依赖。随附树的 web e2e／快照通道（`apps/web/tests/scaffold.ts`）以 disable+insert 补丁固定 `-browse`——其 golden 是交互特定的，绝不能依赖运行该套件的宿主。
-- 每次启动只判定一次，维持 seam 的能力稳定性契约；按连接的形态在有部署提出需求前仍不在范围内。
+- 每次启动只判定一次，维持 seam 的能力稳定性约定；按连接的形态在有部署提出需求前仍不在范围内。
 - 同时挂载选择器**和**某个后端行会大声失败（重复的 `directoryPicker` 服务；`single` 洞中的重复流程）。
 - host 类型检查聚合现在引用两个后端项目（仅声明，node 入口不携带 client 合并），使选择器的 REAL-composition 测试能挂载它们——与 client 聚合对 `webserver` 的引用互为镜像。
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
index 243eed83f8..42a8e3e6bd 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md
 2026-07-29-persistent-bash-str-replace-editor.md: c4750e30370bfd253064c39cb1adc0f5b2baa60d
-2026-07-29-persistent-bash-str-replace-editor.zh.md: 14c52fc90d8619d63ca3acab2d85447fab5eb735
+2026-07-29-persistent-bash-str-replace-editor.zh.md: 83159d9792fd9fadaaa342cc289300b35da34e4a
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
index 14c52fc90d..83159d9792 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 **暴露终端管理工具。** 被拒绝，因为 open/send/read/close 与单个持久 `bash` 调用是不同的模型动作空间。
 
-**修改原生 read/write/edit。** 被拒绝，因为这会扭曲其通用契约，而不是增加一个可独立组合的编辑器。
+**修改原生 read/write/edit。** 被拒绝，因为这会扭曲其通用约定，而不是增加一个可独立组合的编辑器。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
index 1491968f15..0c996c69fd 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
 2026-07-30-config-only-repository-plugins.md: 2057125fc78596dd4e5eb153f77b828f83d9ceff
-2026-07-30-config-only-repository-plugins.zh.md: 6e741b46be716e21a11c2f508fb5e6d0505c76d0
+2026-07-30-config-only-repository-plugins.zh.md: 89d8bd518f2a744c58b042059d2d7787caefe38c
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
index 6e741b46be..89d8bd518f 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 已交付的 TUI 和 Web／无头 `cordis.yml` 配置树包含一个空的 `repository-plugins` 配置项。用户只需修改 `$DSH_HOME/config.yaml`，用 `repositories` 列表替换该配置项的配置。每一项采用 `github:owner/repository#<ref>`，并可追加 `&path:/.../.dsh-plugin`；省略时选择 `/.dsh-plugin`。必须显式指定 ref；路径是仓库内的绝对路径，并以 `.dsh-plugin` 结尾；重复的规范化说明符在安装前即被拒绝。不提供插件市场、发现索引、HTTPS URL 词汇或隐式的最新版本。
 
-`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择配置的仓库子包（package），运行包括 `prepare` 在内的普通生命周期，并原子发布该精确说明符。DSH 宿主只导入生成的 `dsh-plugin.mjs` 包装模块并将其挂载为子 fiber，因此 skill（技能）与 MCP 仍沿用格式包定义的所有者、失败契约和清理行为。
+`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择配置的仓库子包（package），运行包括 `prepare` 在内的普通生命周期，并原子发布该精确说明符。DSH 宿主只导入生成的 `dsh-plugin.mjs` 包装模块并将其挂载为子 fiber，因此 skill（技能）与 MCP 仍沿用格式包定义的所有者、失败约定和清理行为。
 
 ## 实时更新与失败
 
@@ -36,7 +36,7 @@ Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader
 
 **监视缓存内容，或自动刷新相同 ref。** 否决，因为一个配置值必须标识一个不可变的已准备版本。后台远端解析会在没有配置差异的情况下改变可执行代码，并使回滚依赖可变的远端状态。
 
-**广播 `unknown` 失败载荷。** 在 HMR 边界否决。JavaScript 内部可以抛出任意值，但公开事件始终接收规范化的 `Error`，从而为观察者提供稳定契约，并在需要时把原始值保留为错误原因。
+**广播 `unknown` 失败载荷。** 在 HMR 边界否决。JavaScript 内部可以抛出任意值，但公开事件始终接收规范化的 `Error`，从而为观察者提供稳定约定，并在需要时把原始值保留为错误原因。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
index 54966549ba..8e7e02fe37 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
 2026-07-30-continuable-subagent-report-tool.md: 8324f1fa08f7dace6153712575e7e70a07ee9344
-2026-07-30-continuable-subagent-report-tool.zh.md: e7599c1d85328e83c7773718101b59e763a1e37f
+2026-07-30-continuable-subagent-report-tool.zh.md: 6b7472717e724af9bf598fada6d7e82070d06f3c
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
index e7599c1d85..6b7472717e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 可继续的进程内 subagent 能够接收 parent 后续发来的消息、保留后代、结算并冷恢复，但基础生命周期无法让它们将选中内容发送给直接 parent。child 的完整输出已可从持久化会话中重建，因此缺失的能力是显式投递，而非结果存储。
 
-如果将每条 assistant 最终消息都视为隐式结果，就会混淆轮次完成与报告。长期运行的 child 可能在某个轮次中无内容可报告，也可能在另一个轮次多次报告进展，而且报告后必须仍可继续工作。因此，接收方权限、静默投递与唤醒投递、确认、持久性和重试行为都需要一份显式契约。
+如果将每条 assistant 最终消息都视为隐式结果，就会混淆轮次完成与报告。长期运行的 child 可能在某个轮次中无内容可报告，也可能在另一个轮次多次报告进展，而且报告后必须仍可继续工作。因此，接收方权限、静默投递与唤醒投递、确认、持久性和重试行为都需要一份显式约定。
 
 ## 决策
 
@@ -16,7 +16,7 @@ Status: implemented
 
 该功能是协作控制，不是承载结果的执行包装层。它不新增 Task、`SubagentRun`、结果 promise、Activation 状态、投递队列或回放路径。
 
-### 面向模型的契约
+### 面向模型的约定
 
 `report` 只接受 `{ output: string }`，也只返回 `{ messageId: string }`。它不接受 child id、接收方 id 或投递模式。`exec.agent` 将工具调用绑定到发送报告的 child；服务从持久化 `parentSession` 中推导唯一接收方，调度则由部署配置决定。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
index 9e267e82a0..a9dec720a8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
 2026-07-30-current-sandbox-policy-context.md: 093f9a8a0b58256bb4f2301cc62fa83629de4fbd
-2026-07-30-current-sandbox-policy-context.zh.md: 729ea9d50c7dbbfa027e1cad11929ae1c2b379b1
+2026-07-30-current-sandbox-policy-context.zh.md: 6189df12ae2cd9c9a040cd40636596cda23548c9
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
index 729ea9d50c..6189df12ae 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
@@ -50,7 +50,7 @@ Status: implemented
 
 **缓存安全迁移后仍保留 Candidate A。** 不予采用，因为中性的真实提供方任务中，尽管已有 bash 尝试引导，模型仍以纯文本拒绝，且没有调用工具。保留下来的反预防性拒绝原则本身不说明任何升权机制；它告诉模型不要从常驻标签推断操作不可能完成，然后把拒绝与升权行为交还给可用工具。
 
-**继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具契约下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
+**继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具约定下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
 
 **独立的模型上下文包。** 不予采用，因为策略归属方可以直接解析当前会话状态，现有组装服务也可以对其排序。新包只会围绕同一个请求边界引入浅层组合 seam 和额外的文档／门禁表面。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
index 418c81f17d..67de206735 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
 2026-07-30-deepseek-onboarding-credential-setup.md: 419ea0aea56e82e301189d90d5ca78495da2da71
-2026-07-30-deepseek-onboarding-credential-setup.zh.md: 936402c9ed83eccc3d5e78a57247f06347522c0f
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: ba31dc1141eecddc24e178841fefb96858ca4d8c
diff --git a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
index 936402c9ed..ba31dc1141 100644
--- a/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 **Models 与首次使用引导共享同一个就绪状态投影。**`ui-models` 维护一个 store，把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取由 `llm-deepseek` namespace 与空 settings path 持有的 `deepseek-official` 可配置提供方条目，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。同 provider id 但没有匹配可配置提供方声明的存活路由，在首次使用引导中视为适配器缺失。通过进程环境提供的凭据若已配置，则判定为就绪并保持只读。
 
-**设置外壳只贡献排序与导航，不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 通过 `slots.inject()` 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为契约；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
+**设置外壳只贡献排序与导航，不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 通过 `slots.inject()` 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为约定；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
 
 **首次使用页面只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、`credentials.set({ref, value})`、写入失败处理和写入后刷新；首次使用页面绝不持有或提交 secret。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
index 1ceb5a5213..f9944e3ed8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
 2026-07-30-queued-manual-compaction.md: 5100808ada4b7b284228113584e577d46ff91101
-2026-07-30-queued-manual-compaction.zh.md: 29c3b921d0d59527aa1d8af1c91d085b52045377
+2026-07-30-queued-manual-compaction.zh.md: fe3b0ff5e6b8cab7cb332f958adc6ab8d94f23b8
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
index 29c3b921d0..fe3b0ff5e6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
@@ -89,7 +89,7 @@ DSH 有意在调用摘要器前记录 `compact/start`。缓慢或崩溃的尝试
 
 **同时使用持久标记与进程本地 mutex。** 不予采用，因为两项权威在回放后可能产生分歧，还会要求用包装层分支处理标记对已经表达的状态。
 
-**与唤醒提示词一起阻塞注入。** 不予采用，因为按契约，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。
+**与唤醒提示词一起阻塞注入。** 不予采用，因为按约定，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。
 
 **要求标记区间只包含压缩事件。** 不予采用，因为标记表示锁的时间点。溯源信息会精确指明所选 seq 与被遮蔽 seq；排他性不会增加正确性，只会拒绝有效注入。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
index f26524cdc3..cee07159d1 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-search-render-card.md
 2026-07-30-search-render-card.md: 29544cb703f3ab048f4e7702935887ecf05179bf
-2026-07-30-search-render-card.zh.md: e0ae21924e82152ba629ab628476113ad9afe3d8
+2026-07-30-search-render-card.zh.md: 01ffe25522c462a26e781f9bd455711331e58445
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
index e0ae21924e..01ffe25522 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `grep` 与 `glob` 返回结构化的 canonical 值 —— `grep` 是扁平的 `{ matches: [{ path, lineNumber, line }] }`，`glob` 是 `{ paths: string[] }` —— 但每个 UI 只见过它们面向模型的渲染文本：`grep` 把匹配按文件头分组、每行 `Line N:`，`glob` 打印换行连接的路径列表，两者在内联上限（`grepMaxMatches`，默认 250；`globMaxResults`，默认 100）把后续结果落到 spill 文件时都追加一个 spill 脚注。想把搜索结果渲染成可展开的按文件匹配组、或可选择的路径列表的 web 前端，只能去重新解析那段文本。两个工具都已声明调用时的[渲染意图](../architecture/2026-07-02-tool-render-intent-union.md)（`GenericCallView`，`kind: 'search'`），但没有结果时视图，所以已完成的调用回退到渲染原始文本的 generic 卡片。
 
-结构化 canonical 值不跨线传输：只有面向模型的渲染文本、以及当工具声明了 `output.presentationMeta` 时的一份 JSON 元数据，会经 `tool/result` 事件到达客户端（[canonical-output 契约](../architecture/2026-07-20-canonical-tool-output-contract.md)）。因此携带结构化数据的结果时视图必须把数据投影进 `presentationMeta`，再在 `presentResult` 里读回 —— 与 `write`/`edit` 的 diff 卡片走同一条路。
+结构化 canonical 值不跨线传输：只有面向模型的渲染文本、以及当工具声明了 `output.presentationMeta` 时的一份 JSON 元数据，会经 `tool/result` 事件到达客户端（[canonical-output 约定](../architecture/2026-07-20-canonical-tool-output-contract.md)）。因此携带结构化数据的结果时视图必须把数据投影进 `presentationMeta`，再在 `presentResult` 里读回 —— 与 `write`/`edit` 的 diff 卡片走同一条路。
 
 ## 决定
 
@@ -30,7 +30,7 @@ Status: implemented
 
 `SearchMeta` 的成员形状是对象字面量 `type` 别名，而非视图暴露的 `SearchFileMatches`/`SearchLineMatch` 接口，因为只有 type 别名可赋给 `presentationMeta` 返回的 `JsonValue` 索引签名；两者结构等价，所以投影值仍读回为 `SearchResultView`。
 
-没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而本 PR 之前 grep/glob 返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端契约及其两个生产者。
+没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而本 PR 之前 grep/glob 返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端约定及其两个生产者。
 
 ## 考虑过的备选
 
@@ -40,7 +40,7 @@ Status: implemented
 
 **把面向模型的文本作为视图的 `content` 附上。** 否决：对每个当前消费方是 no-op，且把整段搜索文本第二次序列化进持久化视图。视图是结构化形状；文本回退读原始结果内容。
 
-**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决：它为一个工具的载荷改动核心工具决策契约与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
+**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决：它为一个工具的载荷改动核心工具决策约定与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
 
 **镜像 terminal 卡片双侧对称的调用时 `SearchCallView`。** 否决：搜索调用在 `execute` 前没有匹配或路径，视图只会携带 `GenericCallView` 已有的标题。
 
@@ -57,5 +57,5 @@ Status: implemented
 ## 相关
 
 - [工具调用呈现的带标签渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 PR 用 `search` 结果标签扩展的 `card` 标签词汇。
-- [Canonical 工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所乘的 value/render/`presentationMeta` 划分；结构化值留在执行本地，卡片乘 `meta`。
+- [Canonical 工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所乘的 value/render/`presentationMeta` 划分；结构化值留在执行本地，卡片乘 `meta`。
 - [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— 本 PR 在后端镜像的先例：工具把结果投影进 `presentationMeta` 与一个 `presentResult` 视图；搜索卡片的 web 消费方是与之类比的后续。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index d78733bb33..2e01db1284 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-diff-card.md
 2026-07-30-web-diff-card.md: b078da8d0e688d705683599467bd98b5c6a0be48
-2026-07-30-web-diff-card.zh.md: a9c710df99c1060bbf50b591b2f62120dc7dcbef
+2026-07-30-web-diff-card.zh.md: 901331907ed9052541aaee0d4fe70531b030d0f9
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index a9c710df99..901331907e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -32,7 +32,7 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX
 
 **并排（双栏）diff。** owner 目前拒绝：它更密但不适合狭窄的 chat 行，目标是与 TUI 单栏统一形式对齐。详情面板里的双栏模式是后续的 props 改动，不是重设计。
 
-**git 式行号槽。** `FileDiff` 契约只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端契约改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR（Pull Request）保持为对既有契约的纯 Web 消费。
+**git 式行号槽。** `FileDiff` 约定只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端约定改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR（Pull Request）保持为对既有约定的纯 Web 消费。
 
 **复用 `CodeBlock`。** 因与 terminal 卡片相同的理由拒绝：`CodeBlock` 会折行，且没有每行 `+`/`-` 角色、没有路径头、没有页脚。两者共享几何与字体 token，那是唯一一处一个实现对两者都正确的部分。
 
@@ -48,7 +48,7 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX
 
 `packages/client/ui-tool/tests/diff-card.spec.tsx` 钉住每个渲染点的接线：`diffCardModel` 的派生及其每个 null 支路、result hunk 替换 call 时 diff、窗口截断的 call 仍从 result 渲染、chat 行的 diff 体、`FileMutationRow` 的常驻卡片及其路径链接经 host 以 cwd 解析打开、其在 `write` 与 `edit` 下的注册、以及面板的 Output 区。
 
-fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot snapshot（`apps/web/tests/built-boot.snapshot.ts`）是启动装配 smoke，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身契约它不带 diff 行为断言，那由接线套件负责。
+fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot snapshot（`apps/web/tests/built-boot.snapshot.ts`）是启动装配 smoke，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身约定它不带 diff 行为断言，那由接线套件负责。
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
index 624da25dc2..6a6683265e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.md
 2026-07-30-web-queue-steer-action.md: b04095b81f499982c8680a2d3627d8e98a70d8ac
-2026-07-30-web-queue-steer-action.zh.md: b04902b8a8a0d727b01aa6ba5562e12cc5d36c92
+2026-07-30-web-queue-steer-action.zh.md: af13292574b7f130fe858369c746ff2b8911984e
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
index b04902b8a8..af13292574 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.zh.md
@@ -12,7 +12,7 @@ Web composer 原本会在 agent 运行期间把所有 Enter 提交作为 Queue 
 
 ## 决策
 
-### 产品契约
+### 产品约定
 
 普通会话中每个非编辑态的 QueueDock 行都会提供名为“插话发送”的向上箭头操作。仅当会话报告 agent 正在运行时，该操作才会启用；包含混合内容的消息仍可使用，因为 steering 会转发完整且不可变的 `UserMessage`，而非该行的文本投影。已寻址 subagent 的 Queue 投影保持只读，因为其继续执行传输不提供 Queue 变更。
 
@@ -20,7 +20,7 @@ Web composer 原本会在 agent 运行期间把所有 Enter 提交作为 Queue 
 
 running 标志位只用于提示交互状态。在同步变更边界上，AgentLoop 的 `acceptsNextStep` 值才是权威依据。如果该窗口已经关闭，操作会保持 Queue 单次入队项不变并返回类型化的 `steer-unavailable` 错误，随后原唤醒单次入队项会经 Queue 继续执行。如果驱动器已经认领该项，则返回现有的 `queue-item-not-found` 错误，且独立轮次投递已经开始。UI 会把两种竞态都视为已收敛的 Queue 投递，不显示失败通知；传输和未知错误仍会显示。
 
-Composer 对新输入采用另一套尽力而为契约。所寻址会话空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，General Settings 偏好会把普通 Enter 分配为 Queue（默认值）或 Steer，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 用于换行。已寻址 subagent 会让这两个手势都使用其仅支持 Queue 的继续执行传输。浏览器会持久化该偏好，并且它只影响支持 steering 的繁忙态手势对。如果 composer 直接发出的 Steer 错过当前 next-step 窗口，AgentLoop 会自动将其接纳为下一条唤醒 Queue 轮次，Web 不显示失败。
+Composer 对新输入采用另一套尽力而为约定。所寻址会话空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，General Settings 偏好会把普通 Enter 分配为 Queue（默认值）或 Steer，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 用于换行。已寻址 subagent 会让这两个手势都使用其仅支持 Queue 的继续执行传输。浏览器会持久化该偏好，并且它只影响支持 steering 的繁忙态手势对。如果 composer 直接发出的 Steer 错过当前 next-step 窗口，AgentLoop 会自动将其接纳为下一条唤醒 Queue 轮次，Web 不显示失败。
 
 ### Agent 与生命周期边界
 
@@ -38,11 +38,11 @@ Host 仍以现有 `queuedMirror` 作为唯一的瞬态 inbox 权威。`session/q
 
 AgentLoop 认领待处理 steering 时，会在同步追加持久 `user/message` 之前立即发出 `agent/inbox/dequeue`。Host 会等到下一个微任务才退役该 steering 行，让持久 session 事件先进入线性 mux 流。客户端 Session 接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史回放不会消费后来复用同一 `MessageId` 的单次入队项。因此，ChatView 无需扫描持久历史就能每次只渲染一份权威，持久投影则会根据已记录的事件时间与序号恢复时钟、复制与 fork 操作。追加失败时，已认领行仍会退役。
 
-现有 `session.prompt(mode: 'steer')` 对主会话新输入仍采用尽力而为的契约：在 next-step 窗口之外，它会变为唤醒 agent 的后续轮次。Composer 会让显式 `queue | steer` 模式经过 slash 裁决与引用序列化，再调用该契约。浏览器本地的提交策略拥有持久化的繁忙态 Enter 偏好，并且只为支持 steering 的会话把普通 Enter 与加速 Enter 解析为互补手势；Settings 行和 InputBar 共享该策略，不重复实现存储或投递窗口权威。只有 Queue 行操作采用严格语义，因为任一种负面结果都会经原 Queue 单次入队项收敛。
+现有 `session.prompt(mode: 'steer')` 对主会话新输入仍采用尽力而为的约定：在 next-step 窗口之外，它会变为唤醒 agent 的后续轮次。Composer 会让显式 `queue | steer` 模式经过 slash 裁决与引用序列化，再调用该约定。浏览器本地的提交策略拥有持久化的繁忙态 Enter 偏好，并且只为支持 steering 的会话把普通 Enter 与加速 Enter 解析为互补手势；Settings 行和 InputBar 共享该策略，不重复实现存储或投递窗口权威。只有 Queue 行操作采用严格语义，因为任一种负面结果都会经原 Queue 单次入队项收敛。
 
 ### 验证
 
-AgentLoop 契约覆盖保持提示词接纳窗口打开，转换一个精确的 queued 单次入队项，并证明替代它的 steering 单次入队项保留消息值和投递回执、以 `user/message` 的形式排空，且绝不启动原本的独立轮次。该覆盖还钉住窗口不可用时保留原项、拒绝已被认领的地址，以及可重入取消下的生命周期守恒。
+AgentLoop 约定覆盖保持提示词接纳窗口打开，转换一个精确的 queued 单次入队项，并证明替代它的 steering 单次入队项保留消息值和投递回执、以 `user/message` 的形式排空，且绝不启动原本的独立轮次。该覆盖还钉住窗口不可用时保留原项、拒绝已被认领的地址，以及可重入取消下的生命周期守恒。
 
 Host schema 和代理测试覆盖新操作、两种类型化错误、带 placement 的快照与重连重放，以及先持久化再退役的顺序。客户端测试覆盖两种语义竞态的静默收敛、真实错误报告、只读 subagent 行和仅支持 Queue 的 subagent 手势。运行时与 ChatView 测试覆盖按单次入队项完成的待处理到持久交接，包括重复的 `MessageId` 值；Web ARIA 快照则覆盖位于运行状态行之后且仅有复制的待处理 steering，以及带时钟、复制和 fork 的持久节点。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
index 3415ace63b..b4992a15c3 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
 2026-07-30-web-read-card-frontend.md: e659645066b706f35709fead4c11023eb4fe9554
-2026-07-30-web-read-card-frontend.zh.md: 4fc02e23b45399c01b5c99d388f5ae1726b026c0
+2026-07-30-web-read-card-frontend.zh.md: ac3972ace7458b8a751b4cc342bbdb3e2b0a7a9e
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
index 4fc02e23b4..ac3972ace7 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 **新建一个 `ReadBlock` primitive，而不是扩展 `CodeBlock`。** `CodeBlock` 已经带语言横幅和复制控件做 shiki 高亮，但读取视图需要一个每行带该行自身文件行号的行号栏，而 `CodeBlock` 把内容渲染为单个 `<pre>` 树、没有逐行结构。给 `CodeBlock` 加一个可选行号栏会把读取专属的关切（窗口行号、"显示 N / M"提示、高度上限）强加给共享该组件的每个 markdown 代码围栏和每个 `run_code` 程序体。`ReadBlock` 转而复用真正共享的部分：`markdown/highlight.ts` 里的 shiki 语法单例。那里新增的 `highlightLines(code, lang)` 把代码切成 shiki 自己的逐行 token 数组（`codeToTokens`），而不是 `highlightToHtml` 产出的单 `<pre>` HTML，于是该 block 能每行放一个行号、同时用同一套 `--shiki-*` 自定义属性、同一份语法白名单给内容上色。高度上限及其头/尾展开算法照抄自 `TerminalBlock`（`ceil(max/2)` 行头部加剩余的尾部），因此长读取和长命令输出在同一处折叠。复制控件写入窗口的原始文本（各行以换行拼接），绝不含行号栏或横幅。
 
-`readCardModel` 只在结果侧，与后端对称：一次读取调用在 `execute` 返回前不带任何内容，因此挂起中的调用保持为 `GenericCallView`（`kind: 'read'`），本函数对运行中的读取返回 null —— 该行保持其从参数派生的摘要，直到结果到达。它对结果视图不是读取卡片的已结算调用也返回 null，包括本 UI 版本不认识的 `card` 值（它从线路到来、不能被信任为一个已编译的变体）以及读取工具对错误结果自己的通用回退。卡片横幅标签在工具提供 `title` 时取它（契约的替换标题规则），否则取相对于会话工作区化简后的文件路径，使工作区根下的绝对路径显示为与行摘要相同的短形式。该 model 把冻结的行数组复制进 primitive 自己的行形状，因此卡片绝不持有指向运行时快照缓存的引用。
+`readCardModel` 只在结果侧，与后端对称：一次读取调用在 `execute` 返回前不带任何内容，因此挂起中的调用保持为 `GenericCallView`（`kind: 'read'`），本函数对运行中的读取返回 null —— 该行保持其从参数派生的摘要，直到结果到达。它对结果视图不是读取卡片的已结算调用也返回 null，包括本 UI 版本不认识的 `card` 值（它从线路到来、不能被信任为一个已编译的变体）以及读取工具对错误结果自己的通用回退。卡片横幅标签在工具提供 `title` 时取它（约定的替换标题规则），否则取相对于会话工作区化简后的文件路径，使工作区根下的绝对路径显示为与行摘要相同的短形式。该 model 把冻结的行数组复制进 primitive 自己的行形状，因此卡片绝不持有指向运行时快照缓存的引用。
 
 聊天行把卡片**常驻**渲染在摘要行之下，上限 `CHAT_READ_MAX_LINES`（8，是 primitive 默认值的一半），与 `BashRow` 对终端卡片的姿态相同 —— block 的内部展开器让长读取不会占据整个消息流。两个渲染点承载它：keyed `ReadRow`（经 `ctx.slots.inject` 以 `read` 键注册，与 bash 样例完全一致），其摘要是作为可打开的宿主链接的文件路径；以及 `GenericToolCard` 对没有自己 keyed 行的读取声明工具（例如归到 `read` 变体的 `web_fetch`）的回退。详情面板以 primitive 自己的全高上限（16）渲染同一张卡片，因为面板是单次调用的阅读界面。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
index 9bde6a14c7..a58a19000a 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-read-card.md
 2026-07-30-web-read-card.md: 26d1634b6be86666980e65f842de51c868c26efd
-2026-07-30-web-read-card.zh.md: 749177e93e8e3b2e34aed46d1fe99226395a6686
+2026-07-30-web-read-card.zh.md: c48cd56b7f919d5ceb702f890ee18a2a735da347
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
index 749177e93e..c48cd56b7f 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
@@ -14,9 +14,9 @@ Status: implemented
 
 给[渲染意图 union](../architecture/2026-07-02-tool-render-intent-union.md) 新增第四个 `card` 标签 `read`——仅在结果侧。`ToolResultView` 增加 `ReadResultView { card: 'read'; title?; path; lines: ReadFileLine[]; totalLines; lang?; content? }`；`ReadFileLine { number; text }` 是共享的行单元。`ToolCallView` 不动：待定状态仍是 `GenericCallView`（`kind: 'read'`），因为一次调用在 `execute` 返回前不携带文件内容，调用时没有可展示的结构。这与 bash 终端 card 不同——终端 card 两侧都打标签，因为终端调用在调用时已携带命令和 cwd，而 read 调用既无内容也无总数，给调用侧打标签只会新增一个空变体。
 
-read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write/edit 用来投影其应用 diff hunk 的持久化通道相同（[规范化工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)）。`presentationMeta` 对一次顶层 surface 调用运行一次，返回 `{ path, offset, lines, totalLines, lang? }` 作为会话校验并存储在结果 `meta` 上的 JSON，`presentResult` 在 live 和回放路径上都把该 meta 收窄回 `ReadResultView`。`offset`（窗口请求的 1-based 起始行）一并携带，是因为当字节上限低于首个选中行时，窗口会返回空的 `lines` 数组而 `totalLines` 为正；没有持久化的 `offset`，这类窗口的回放 card 就无法报告它从哪行开始、或续读应从哪行继续，而末行推断与文本重解析两种兜底都有损。没有这个通道，行数组和总数就无法触及：原始输出对象不在线上，而重新解析 `N: text` 文本既有损又对截断脚注脆弱。
+read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write/edit 用来投影其应用 diff hunk 的持久化通道相同（[规范化工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)）。`presentationMeta` 对一次顶层 surface 调用运行一次，返回 `{ path, offset, lines, totalLines, lang? }` 作为会话校验并存储在结果 `meta` 上的 JSON，`presentResult` 在 live 和回放路径上都把该 meta 收窄回 `ReadResultView`。`offset`（窗口请求的 1-based 起始行）一并携带，是因为当字节上限低于首个选中行时，窗口会返回空的 `lines` 数组而 `totalLines` 为正；没有持久化的 `offset`，这类窗口的回放 card 就无法报告它从哪行开始、或续读应从哪行继续，而末行推断与文本重解析两种兜底都有损。没有这个通道，行数组和总数就无法触及：原始输出对象不在线上，而重新解析 `N: text` 文本既有损又对截断脚注脆弱。
 
-`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本 PR 已重录全部已发布 fixtures，且 session 格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图契约的一部分。
+`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本 PR 已重录全部已发布 fixtures，且 session 格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图约定的一部分。
 
 ### 语言提示推导
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index 6f3a5d895b..b844594397 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
 2026-07-30-web-result-card-frontend.md: c7e63220d824cf0bd3ac3536c528707d0db379bc
-2026-07-30-web-result-card-frontend.zh.md: 4cec11371e8d0848f2f03ded0b093d80cc25a7a5
+2026-07-30-web-result-card-frontend.zh.md: e40d103c295b4699cde3327252c8bca3719e7962
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index 4cec11371e..e40d103c29 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## Problem
 
-`web_search` 和 `web_fetch` 工具声明了 `card: 'web'` result view（[web result card](2026-07-30-web-result-card.md)）：一个 `kind` 标签联合,携带结构化的被引用 sources 加可选的 provider answer（`kind: 'search'`),或抓取的 URL 及其 HTTP 状态（`kind: 'fetch'`）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `resultView` 投递到 `ConversationSnapshot` —— 但 Web 客户端忽略了它:一次已完成的 web 调用只渲染为摊平的模型可见文本,正是契约笔记所解释的、结构化视图要替代的那种有损渲染。`web_search` 到达读者时是每个 source 一行自由文本 markdown,而非可点击 source 的引用列表;`web_fetch` 是它的 markdown 正文,没有检索摘要。
+`web_search` 和 `web_fetch` 工具声明了 `card: 'web'` result view（[web result card](2026-07-30-web-result-card.md)）：一个 `kind` 标签联合,携带结构化的被引用 sources 加可选的 provider answer（`kind: 'search'`),或抓取的 URL 及其 HTTP 状态（`kind: 'fetch'`）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `resultView` 投递到 `ConversationSnapshot` —— 但 Web 客户端忽略了它:一次已完成的 web 调用只渲染为摊平的模型可见文本,正是约定笔记所解释的、结构化视图要替代的那种有损渲染。`web_search` 到达读者时是每个 source 一行自由文本 markdown,而非可点击 source 的引用列表;`web_fetch` 是它的 markdown 正文,没有检索摘要。
 
 ## Decision
 
 `WebBlock` 是一个 `ui-primitives` 组件,渲染一次已完成的 web 检索,web 调用的每个 Web 渲染点都通过它消费 `web` 渲染意图:键控的 chat 工具行（`web_search`/`web_fetch`）、`GenericToolCard` 渲染点兜底,以及详情面板的 Output 区。`ui-tool/src/client/tool/models/web-card-model.ts` 是唯一把快照的 `resultView` 转成组件 props 的地方,镜像 `terminal-card-model.ts`,因此没有两个渲染点会对一次 web 调用的显示产生分歧。它返回 null —— 走通用路径 —— 对运行中的调用（web 卡片是 result-only 的,因为工具保留 generic pending 视图）、对 result view 不是 web 卡片的已结算调用（包括本客户端版本不认识的 `card` 值,它经 wire 抵达因而不能被信任为已编译的变体）、对 generic result view（web 工具的错误路径返回 generic 卡片,其文本由通用路径保留）、以及对本客户端版本不认识 `kind` 的 web 卡片（更新的 host 经 wire 发来的值,读作 fetch 会画出空 URL 和 `HTTP undefined`）。
 
-一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是契约把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
+一个组件绘制两种 kind,由 `kind` 判别。`search` 把 answer 作为 markdown 显示在引用列表上方;每个 source 是一个安全外链,以其标题为标签,provider 未给标题时以其主机名为标签,下方是 snippet 与发布日期,工具截断列表时显示 `来源列表已截断` 提示。`fetch` 显示一个紧凑摘要:带链接的最终 URL、其 HTTP 状态、以及 `内容已截断` 提示。用一个组件而非两个,因为两者都是渲染为同一卡片族的 web 检索 —— 这正是约定把它们放在一个 `card` 标签下、用 `kind` 判别的原因。
 
 **链接的安全性沿用 MarkdownText 对不受信任的 assistant 链接所用 allowlist 的 http(s) 子集。** MarkdownText 还允许 `mailto:`，此处刻意排除，因为检索 URL 绝不会是邮件地址。一个 source 或 fetch URL 仅当其协议为 `http:` 或 `https:` 时才成为可导航锚点，带 `target="_blank"` 和 `rel="noopener noreferrer"`；`javascript:`/`data:`/`file:`/`mailto:` URL 或无法解析的字符串渲染为纯文本、无 href。web 工具返回的 result content 是模型创作的,未经验证抵达本组件,因此像 assistant markdown 一样被当作不受信任处理。标签从标题回退到主机名再回退到原始 URL,因此即便标题缺失且 URL 无法解析,source 也总能读作某个东西。
 
@@ -22,15 +22,15 @@ Status: implemented
 
 ## Consequences
 
-`WebBlock` 只读 web view 的字段,因此它是渲染意图所携带内容的纯函数 —— 无会话查找,与产出该视图的 presenter 一样回放安全,且不同于终端卡片它不需要 cwd 解析,因为 web view 不携带路径。没有 `web` 能力的 UI（TUI）仍得到契约的回退 `content`;工具的 result 形状没有任何改变。answer 复用 `MarkdownText`,因此 answer 自身的不受信任链接处理与 GFM 渲染免费获得。
+`WebBlock` 只读 web view 的字段,因此它是渲染意图所携带内容的纯函数 —— 无会话查找,与产出该视图的 presenter 一样回放安全,且不同于终端卡片它不需要 cwd 解析,因为 web view 不携带路径。没有 `web` 能力的 UI（TUI）仍得到约定的回退 `content`;工具的 result 形状没有任何改变。answer 复用 `MarkdownText`,因此 answer 自身的不受信任链接处理与 GFM 渲染免费获得。
 
 一条独立的后续 PR 会统一整行折叠/展开交互,并把每张常驻卡片（terminal、diff、web）一次性翻成 expand-gated;本卡片遵循当前的常驻约定,而非抢先做那次改动。
 
 ## Alternatives considered
 
-**两个组件,每种 kind 一个。** 拒绝:两种形状共享卡片外框、安全链接处理、截断提示,而契约已经把它们的差异表达为一个 `card` 标签下的 `kind` 判别;两个组件会重复共享表面并拆分安全链接逻辑。
+**两个组件,每种 kind 一个。** 拒绝:两种形状共享卡片外框、安全链接处理、截断提示,而约定已经把它们的差异表达为一个 `card` 标签下的 `kind` 判别;两个组件会重复共享表面并拆分安全链接逻辑。
 
-**重解析模型可见的渲染文本,而非消费结构化视图。** 因契约笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
+**重解析模型可见的渲染文本,而非消费结构化视图。** 因约定笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
 
 **不加协议 allowlist 直接渲染裸锚点。** 拒绝:URL 在此接缝处是模型创作、未经验证的,所以未过滤的 href 会让 `javascript:` URL 在点击时执行。该 allowlist 是 MarkdownText allowlist（它还允许 `mailto:`）的 http(s) 子集,因此不受信任的检索链接无论在何处渲染都行为相同。
 
@@ -40,7 +40,7 @@ Status: implemented
 
 `packages/client/ui-tool/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-tool/src/*`）,因此覆盖率运行不度量它。
 
-fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配契约的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
+fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配约定的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
index 0badfa2a55..9eba8730a4 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-result-card.md
 2026-07-30-web-result-card.md: 838b13a7f3240c753e5cd1af6909389055c6352d
-2026-07-30-web-result-card.zh.md: 6e5170fcad82d709b050fb05e8efcfe955f20391
+2026-07-30-web-result-card.zh.md: 36ab372864e5cd848b999ee759e73658271b8f90
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
index 6e5170fcad..36ab372864 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-`web_search` 与 `web_fetch` 工具各自声明了一个 generic 待定卡片（`presentCall`，`kind: 'search'`/`'fetch'`），但没有 `presentResult`，因此一个已完成的 web 调用抵达 UI 时只剩下面向模型的 render 文本。对于想渲染引用列表或抓取摘要的 web 前端而言，该文本是有损的：`web_search` 的 render 把每个来源的 `title`、`snippet`、`publishedAt` 压进一行以 title 或 hostname 标注的自由文本 markdown（`packages/web/tool-web/src/search.ts` 中的 `formatSearchOutput`），因此重新解析 render 无法恢复各来源字段；`web_fetch` 的 render 也仅在一行 header 里携带 `url` 与 `statusCode`。渲染意图契约（[标签联合类型](../architecture/2026-07-02-tool-render-intent-union.md)）此前没有一个可供 web 工具声明、用以携带结构化结果的分支。
+`web_search` 与 `web_fetch` 工具各自声明了一个 generic 待定卡片（`presentCall`，`kind: 'search'`/`'fetch'`），但没有 `presentResult`，因此一个已完成的 web 调用抵达 UI 时只剩下面向模型的 render 文本。对于想渲染引用列表或抓取摘要的 web 前端而言，该文本是有损的：`web_search` 的 render 把每个来源的 `title`、`snippet`、`publishedAt` 压进一行以 title 或 hostname 标注的自由文本 markdown（`packages/web/tool-web/src/search.ts` 中的 `formatSearchOutput`），因此重新解析 render 无法恢复各来源字段；`web_fetch` 的 render 也仅在一行 header 里携带 `url` 与 `statusCode`。渲染意图约定（[标签联合类型](../architecture/2026-07-02-tool-render-intent-union.md)）此前没有一个可供 web 工具声明、用以携带结构化结果的分支。
 
 ## Decision
 
@@ -22,7 +22,7 @@ Status: implemented
 
 ## Consequences
 
-前端消费方由后续独立 PR 交付：本次生产者变更新增契约分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript 快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
+前端消费方由后续独立 PR 交付：本次生产者变更新增约定分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript 快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
 
 未来想用此卡片的 web 工具，声明一个返回带自有 `kind` 的 `card: 'web'` 视图的 `presentResult`；新增第三个 `kind` 是一次联合类型编辑加前端的分岔，而非一个新的 card 标签。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
index 0cfb6b01bd..461492312b 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-search-card.md
 2026-07-30-web-search-card.md: e0be857df69dfd46b6e936c775c6bae1476c26dc
-2026-07-30-web-search-card.zh.md: 1704b8f04c519511d5afa32ae6683c1e48ce7992
+2026-07-30-web-search-card.zh.md: 784afb0dd36f20c3a0e203d5595c46c8040d82ff
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
index 1704b8f04c..784afb0dd3 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
@@ -8,17 +8,17 @@ Status: implemented
 
 `grep` 与 `glob` 工具声明了一个仅在结果阶段存在的 `card: 'search'` render intent（[search render card](2026-07-30-search-render-card.md)）：`SearchMatchesResultView`（`shape: 'matches'`）携带 grep 按文件分组的匹配，或 `SearchPathsResultView`（`shape: 'paths'`）携带 glob 的扁平路径列表，两者都带 `truncated`/`total` 截断信号。该视图已经到达浏览器 —— host、connection、runtime 把它作为 `resultView` 投递到 `ConversationSnapshot` 上 —— 但 Web 客户端忽略了它：每个非终端、非 diff 的工具结果都落到 generic 卡片，渲染面向模型的文本。想把搜索结果渲染成可展开的按文件匹配分组、或可扫读的路径列表的 web 前端，只有那段预格式化文本。
 
-这正是 search render card note 指名的后续：那个 PR 是后端契约和它的两个生产者，本 PR 是 web 消费者。
+这正是 search render card note 指名的后续：那个 PR 是后端约定和它的两个生产者，本 PR 是 web 消费者。
 
 ## Decision
 
 `SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-tool/src/client/tool/models/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
 
-与终端卡片的不对称是刻意的，继承自后端契约：`terminalCardModel` 同时读 `callView` 和 `resultView`，因为命令、cwd、description 在调用时就存在；`searchCardModel` 只读 `resultView`，因为搜索的匹配或路径只在执行后存在。因此运行中的搜索行只显示摘要，没有卡片。
+与终端卡片的不对称是刻意的，继承自后端约定：`terminalCardModel` 同时读 `callView` 和 `resultView`，因为命令、cwd、description 在调用时就存在；`searchCardModel` 只读 `resultView`，因为搜索的匹配或路径只在执行后存在。因此运行中的搜索行只显示摘要，没有卡片。
 
 一个组件绘制两种形态，用 `kind` 区分，因为 `grep` 和 `glob` 是同一个视觉对象 —— 一个搜索结果。`SearchMatchesBlockProps`（`kind: 'matches'`）和 `SearchPathsBlockProps`（`kind: 'paths'`）让每种形态的字段保持必填，而不是所有字段都可选的单一接口。组件把它持有的形态压平成一个渲染行列表 —— matches 形态是一个文件头行加它的匹配行，paths 形态是每个路径一行 —— 于是高度上限把一个文件头当作一行来计，与一条匹配行或一个路径相同，头/尾切片算术就是 `TerminalBlock` 的（`ceil(max/2)` 头，其余为尾），因此一个长搜索结果和一段长命令输出在两张卡片间在同一处截断。
 
-组件契约：
+组件约定：
 
 - **按文件分组的匹配，逐文件可折叠。** 每个文件是一个头行（加粗路径加它的匹配计数，整行即折叠控件），后面跟它的 `lineNumber: line` 行。折叠一个组会把它的匹配行从压平列表和高度上限的算术里去掉，但绝不从复制文本里去掉。
 - **扁平路径列表。** paths 形态每行一个路径，无头行。
@@ -44,7 +44,7 @@ Status: implemented
 
 **两个卡片组件，每个工具一个。** 否决：`grep` 与 `glob` 是仅由 `kind` 区分的同一视觉对象，两个组件会重复横幅、高度上限、复制控件与不换行几何。一个按 `kind` 分支的组件正是后端那个单一 `card: 'search'` 视图的用途。
 
-**加一个 `SearchCallView`，让行在搜索运行时就渲染卡片。** 否决：后端契约刻意没有调用阶段的搜索视图 —— 搜索在 `execute` 前没有匹配或路径。运行中的行只显示摘要，`searchCardModel` 对运行块返回 null，忠实于实际存在的东西。
+**加一个 `SearchCallView`，让行在搜索运行时就渲染卡片。** 否决：后端约定刻意没有调用阶段的搜索视图 —— 搜索在 `execute` 前没有匹配或路径。运行中的行只显示摘要，`searchCardModel` 对运行块返回 null，忠实于实际存在的东西。
 
 **复用 `TerminalBlock` 或 `CodeBlock`。** 否决：两者都不建模逐文件可折叠的组或折叠式截断摘要，都需要把按文件分组的形态硬塞进去。三个块转而共享几何与字体 token，那是唯一一处一个实现对三者都正确的部分。
 
@@ -56,10 +56,10 @@ Status: implemented
 
 `packages/client/ui-primitives/tests/search-block.spec.tsx` 以 per-file 100% 覆盖固定组件：两种 kind、折入摘要的截断前总数、空结果分支、逐文件折叠/再展开且不影响邻居、一个文件头与其匹配一起计为一个被截断行、切口落在文件中间时尾部切片恢复其所属文件头、跨两种形态的头/尾上限及其展开控件（含无尾与默认上限的边界），以及复制控件在接受与拒绝的剪贴板路径上写入整个结构化结果。
 
-`packages/client/ui-tool/tests/search-card.spec.tsx` 固定每个渲染点的接线：`searchCardModel` 对两种 kind 的推导、截断信号、替换标题、仅在截断时暴露的恢复文本，以及每个 null 分支（运行中、无视图、generic、terminal、未知卡片、本版本无法编译的 `kind`、以及一个形态缺失/错误的已知 kind）；通过 `GenericToolCard` 的展开门控 matches 与 paths body（含恢复脚注），对照非搜索的 args-JSON body；`SearchRow` 对两种 kind 的常驻卡片、它的恢复脚注、它对出错搜索与已结算无卡片结果两者的 fallback body、它与摘要行运行状态的一致、替换标题优先级，以及一个组件在 `grep` 与 `glob` 两个键下的 keyed 注册；以及 details panel 的 Output 段对两种 kind（含恢复脚注），对照非搜索的压平形态。`packages/client/ui-tool/src/*` 在覆盖排除清单上，因此该文件不受 gate 压力。`packages/client/connection/src/client/fixture.ts` 新增一个发出 `kind: 'matches'` 的 `grep` turn（三个文件、十二行超过行内上限、`truncated` 且带溢出恢复脚注，因此在组装快照里同时演练头/尾上限与恢复脚注）与一个发出 `kind: 'paths'` 的 `glob` turn，两者都驱动 built-boot snapshot 与实时 `?fixture` 服务。`apps/web/tests/search-card.snapshot.ts` 是仓库契约要求的组装输出检查：它通过 keyless fixture 传输启动真实构建的 `client.js` bundle，打开 fixture 会话，并把 grep 卡片的组装形态——kind、截断摘要、头/尾切片及其展开控件——固定在 `apps/web/tests/snapshots/search-card/` 下，因此一个损坏的 SearchRow 注册或被丢弃的卡片会让一个 golden 失败，而 built-boot smoke（按契约只测启动）无法捕获它。
+`packages/client/ui-tool/tests/search-card.spec.tsx` 固定每个渲染点的接线：`searchCardModel` 对两种 kind 的推导、截断信号、替换标题、仅在截断时暴露的恢复文本，以及每个 null 分支（运行中、无视图、generic、terminal、未知卡片、本版本无法编译的 `kind`、以及一个形态缺失/错误的已知 kind）；通过 `GenericToolCard` 的展开门控 matches 与 paths body（含恢复脚注），对照非搜索的 args-JSON body；`SearchRow` 对两种 kind 的常驻卡片、它的恢复脚注、它对出错搜索与已结算无卡片结果两者的 fallback body、它与摘要行运行状态的一致、替换标题优先级，以及一个组件在 `grep` 与 `glob` 两个键下的 keyed 注册；以及 details panel 的 Output 段对两种 kind（含恢复脚注），对照非搜索的压平形态。`packages/client/ui-tool/src/*` 在覆盖排除清单上，因此该文件不受 gate 压力。`packages/client/connection/src/client/fixture.ts` 新增一个发出 `kind: 'matches'` 的 `grep` turn（三个文件、十二行超过行内上限、`truncated` 且带溢出恢复脚注，因此在组装快照里同时演练头/尾上限与恢复脚注）与一个发出 `kind: 'paths'` 的 `glob` turn，两者都驱动 built-boot snapshot 与实时 `?fixture` 服务。`apps/web/tests/search-card.snapshot.ts` 是仓库约定要求的组装输出检查：它通过 keyless fixture 传输启动真实构建的 `client.js` bundle，打开 fixture 会话，并把 grep 卡片的组装形态——kind、截断摘要、头/尾切片及其展开控件——固定在 `apps/web/tests/snapshots/search-card/` 下，因此一个损坏的 SearchRow 注册或被丢弃的卡片会让一个 golden 失败，而 built-boot smoke（按约定只测启动）无法捕获它。
 
 ## Related
 
-- [Search render intent —— grep 与 glob 发出结构化搜索卡片](2026-07-30-search-render-card.md) —— 后端契约与它的两个生产者；本 note 是它指名的 web 消费者后续。
+- [Search render intent —— grep 与 glob 发出结构化搜索卡片](2026-07-30-search-render-card.md) —— 后端约定与它的两个生产者；本 note 是它指名的 web 消费者后续。
 - [Web 终端卡片](2026-07-28-web-terminal-card.md) —— 本 note 镜像的先例：工具的 render intent 通过一个 `ui-primitives` 块、一个 `contract/*-card-model.ts` 推导、以及同样的三个渲染点到达浏览器。
 - [工具调用呈现的标签化 render-intent 联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 两张卡片都消费的 `card` 标签词汇。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
index 255dd08832..0943fb008c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.md
 2026-07-30-web-tool-row-unified-expand-and-inspect.md: 4fcf1e9a567b73cd04f1bbed170c391aaedd9e73
-2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: 92d70f5aa6bd09e6f9e54015dafc38d8d3690a9e
+2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md: aa81bb584cb794110454cf97520f82c1421e3e41
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
index 92d70f5aa6..aa81bb584c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-tool-row-unified-expand-and-inspect.zh.md
@@ -21,7 +21,7 @@
 
 ## 曾考虑的替代方案
 
-**保留前导图标开关和各注册方自有的展开方式。** 否决：三个表面已经分化；注册方姿态（bash 示例本地复刻 CSS）意味着除非交互契约本身统一且足够小——整行开关加 hover 预览——否则漂移会永久存在。
+**保留前导图标开关和各注册方自有的展开方式。** 否决：三个表面已经分化；注册方姿态（bash 示例本地复刻 CSS）意味着除非交互约定本身统一且足够小——整行开关加 hover 预览——否则漂移会永久存在。
 
 **通过 URL 或 trajectory 视图 prop 传递 Inspect。** 否决：视图环经由 slot 注册表渲染，两个视图没有可携带 prop 的共同父级；chat store 本就跨越该边界，一次性字段让交接可安全重放（字段出现之前的持久化快照以 `?? null` 复水）。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
index e6ca4048fd..ee89a37a8b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
 2026-07-31-code-mode-language-dispatch.md: 71e4fd5a30e90ac66132dbdcea16917bacc80b68
-2026-07-31-code-mode-language-dispatch.zh.md: 1dbb3d889d28669575980d3a667e4f168a5d72db
+2026-07-31-code-mode-language-dispatch.zh.md: c8ab776dfb01265fa79b5f2b1001ca8109a96d7f
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
index 1dbb3d889d..c8ab776dfb 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
@@ -23,11 +23,11 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 ### Python SDK 渲染器
 
-`py-types.ts` 渲染 `jsonSchemaToTs` 所覆盖的同一套统一工具 schema 词汇，目标为 Python：`jsonSchemaToPy` 为每个 JSON-schema 节点发出一个类型表达式，`renderToolsSdkPy` 为每个可见工具的参数与规范输出装配具名 `TypedDict`，再加一个带用法说明的 `tools` 对象，与 TypeScript 形态等价。不支持的原始构造在装配时降级而非抛错，与 TypeScript 渲染器的契约一致。输出是确定性的——工具按字典序排列，工具集不变时文本逐字节相同——因此 prompt 保持 prefix-cache 友好。字典序意味着单一有序的成员流：名字不是合法属性的工具以 `tools[name]` 注释出现在它排序后的位置上，而不是被分拣到末尾，与 TypeScript 形态就地为异常键加引号的做法一致。这个成员流直接决定了一件事：注释行不是语句，所以一个不发出任何方法的工具集仍需显式 `pass`。另有三条规则并非源自排序，而是 Python 特有。其一，用法约定声明这些声明只是静态存根、参数为普通 `dict`/`list` 值：`TypedDict` 读起来像一个可构造的类，模型若写 `FooArgs(field=1)` 会得到 `NameError`——TypeScript 的 `interface` 一眼就是类型，且 TS 形态的「runs type-stripped」一句已经覆盖了它。其二，描述会成为方法的 docstring，且必须作为方法体的**第一条语句**发出：放在 `async def` 之上，第一条会变成 `Tools` 的类文档、其余都是无效果表达式，导致每个方法都没有文档。其三，`list[…]` 链超过 `MAX_LIST_NESTING` 后降级为 `Any`，因为 CPython 的 tokenizer 拒绝一行中超过 200 个同时未闭合的括号，而这个块必须是可解析的 Python——与 `docLines` 转义引号和反斜杠是同一个理由。`ts-types` 两者都不需要：TypeScript 会把前置的 `/** … */` 附着到其后的成员上，其语法也不对嵌套设限。
+`py-types.ts` 渲染 `jsonSchemaToTs` 所覆盖的同一套统一工具 schema 词汇，目标为 Python：`jsonSchemaToPy` 为每个 JSON-schema 节点发出一个类型表达式，`renderToolsSdkPy` 为每个可见工具的参数与规范输出装配具名 `TypedDict`，再加一个带用法说明的 `tools` 对象，与 TypeScript 形态等价。不支持的原始构造在装配时降级而非抛错，与 TypeScript 渲染器的约定一致。输出是确定性的——工具按字典序排列，工具集不变时文本逐字节相同——因此 prompt 保持 prefix-cache 友好。字典序意味着单一有序的成员流：名字不是合法属性的工具以 `tools[name]` 注释出现在它排序后的位置上，而不是被分拣到末尾，与 TypeScript 形态就地为异常键加引号的做法一致。这个成员流直接决定了一件事：注释行不是语句，所以一个不发出任何方法的工具集仍需显式 `pass`。另有三条规则并非源自排序，而是 Python 特有。其一，用法约定声明这些声明只是静态存根、参数为普通 `dict`/`list` 值：`TypedDict` 读起来像一个可构造的类，模型若写 `FooArgs(field=1)` 会得到 `NameError`——TypeScript 的 `interface` 一眼就是类型，且 TS 形态的「runs type-stripped」一句已经覆盖了它。其二，描述会成为方法的 docstring，且必须作为方法体的**第一条语句**发出：放在 `async def` 之上，第一条会变成 `Tools` 的类文档、其余都是无效果表达式，导致每个方法都没有文档。其三，`list[…]` 链超过 `MAX_LIST_NESTING` 后降级为 `Any`，因为 CPython 的 tokenizer 拒绝一行中超过 200 个同时未闭合的括号，而这个块必须是可解析的 Python——与 `docLines` 转义引号和反斜杠是同一个理由。`ts-types` 两者都不需要：TypeScript 会把前置的 `/** … */` 附着到其后的成员上，其语法也不对嵌套设限。
 
 该上限服务的标准是**语法合法性**，这条边界是有意划定的：长的 `A | B | …` union 在任何长度下都是合法 Python，故不设上限——尽管 CPython 的 `compile()` 在沿左嵌套 `BinOp` 脊柱下降时会耗尽 C 递归（在 3.9 上实测：1,000 个分支可编译，5,000 个抛 `RecursionError`）。没有任何东西会编译这个块——它是提示词文本——所以那条限制在这里没有代价；而给 union 长度封顶会作废那几个钉住 walk 线性时间与类名传播上限的深链测试。将来若有渲染器确实需要可编译的输出，应当把 union 拍平，而不是截断。
 
-`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程 seam 上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process seams](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的契约是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
+`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程 seam 上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process seams](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的约定是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
 
 ## Alternatives considered
 
@@ -41,6 +41,6 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
 
-Python SDK 文本断言的两条运行时契约同样归属那个 backend PR。其一，说明文字告诉模型运行时恰好绑定 `tools` 与 `ToolCallError` 两个名字、所声明的 `TypedDict` 类不绑定，因此后端必须注入这两个名字（并按 seam 的 `errorClass` 契约填充 `ToolCallError.toolName`），且**不得**把所声明的类名绑进程序全局——「好心」注入会使这段 SDK 文本变成假话。其二，语言必须绑定到请求上：`requireCodeRuntime` 在组装时与 `run_code` 执行时分别解析 `ctx.codeRuntime`，若在这两点之间发生重载并换掉运行时，就会把针对一种形态写成的程序交给另一种形态执行。分裂比这两点更细——`run_code` 的 `description` 与 `parameters` 两个 getter 各自调用 `resolveFlavor(peekRuntime())`，而 `schemaOf` 会解构这两个字段，因此一次投影读两次运行时；两次都属于 `run_code` 自己的 schema，因为这两个 getter 只装在那一个 definition 上，其余 definition 携带的都是普通数据属性。在这两次读取之间重载会产出单个 schema 的两半分属不同语言。两者在此处都不可达——只有一个已发布后端意味着两次读取返回同一形态，且没有任何程序会针对本渲染器的输出运行——而跨语言拒绝在第二门语言存在之前也无法测试。
+Python SDK 文本断言的两条运行时约定同样归属那个 backend PR。其一，说明文字告诉模型运行时恰好绑定 `tools` 与 `ToolCallError` 两个名字、所声明的 `TypedDict` 类不绑定，因此后端必须注入这两个名字（并按 seam 的 `errorClass` 约定填充 `ToolCallError.toolName`），且**不得**把所声明的类名绑进程序全局——「好心」注入会使这段 SDK 文本变成假话。其二，语言必须绑定到请求上：`requireCodeRuntime` 在组装时与 `run_code` 执行时分别解析 `ctx.codeRuntime`，若在这两点之间发生重载并换掉运行时，就会把针对一种形态写成的程序交给另一种形态执行。分裂比这两点更细——`run_code` 的 `description` 与 `parameters` 两个 getter 各自调用 `resolveFlavor(peekRuntime())`，而 `schemaOf` 会解构这两个字段，因此一次投影读两次运行时；两次都属于 `run_code` 自己的 schema，因为这两个 getter 只装在那一个 definition 上，其余 definition 携带的都是普通数据属性。在这两次读取之间重载会产出单个 schema 的两半分属不同语言。两者在此处都不可达——只有一个已发布后端意味着两次读取返回同一形态，且没有任何程序会针对本渲染器的输出运行——而跨语言拒绝在第二门语言存在之前也无法测试。
 
 其三，那个 PR 拥有 CPython 版本下限，连带拥有本渲染器的 Unicode 表偏斜。有四处表达式读所运行引擎的表（Node 22.23.1：Unicode 17.0），而解释器用它自己的表（CPython 3.9.6：13.0.0）：`isBareIdentifier` 的 `IDENTIFIER`，以及 `camelCase` 的切分集、头部测试与 `toUpperCase()`。解释器旧于引擎是会失败的那个方向——引擎发出的字符被其 tokenizer 拒收，整个块随之不可解析——而它经三条独立路径抵达。经判据抵达的是裸发的方法名或字段名，其中带有一个在两个版本之间新增的字符——首位加进 `XID_Start`，或尾部任意位置（含名字中部）加进 `XID_Continue`。经 `camelCase` 的 XID 读取抵达的是类名：只要工具 schema 中有任一对象形态声明 `TypedDict`，该类名就进入发出的文本，且判据对工具名的裁决并不对它设闸——工具名 `zz-` 加 U+1E4D0 因 `-` 被判据直接拒绝、从不触及那里的偏斜，却照样声明 `class Zz𞓐xArgs`。经大写映射抵达的是由判据已接受的工具派生出的类名——这是另一张表，窗口也比 XID 归属更宽：U+019B 既是 XID_Start 又 NFKC 稳定，故 `async def ƛ` 在 3.9.6 上可编译，但 Node 将其大写为 U+A7DC（在那里未分配；CPython 自己的 `.upper()` 在此是恒等），于是 `class ꟜArgs` 以 `invalid non-printable character U+A7DC` 失败。暴露窗口是两个版本之间发生变化的那些字符与映射，所以宣布支持某个 CPython 范围的那个 PR 必须在「接受该暴露」与「按该下限的表钉住全部四个读取点」之间显式作出决定——只钉判据会同时留下两条类名路径。此处无法决定：下限尚不存在，而按猜测钉死一张表会成为一个随部署而变、却没有可配置性支撑的常量。还有第二条轴随该下限一同确定，且不属于那四个读取点：本块在定义期会被求值的那些名字与语法。`TypedDict` 需要 3.8，PEP 585 的内建泛型 `dict[str, Any]` 与 `list[…]` 需要 3.9，`A | B` 形式的注解需要 3.10，`NotRequired` 需要 3.11。这些不是解析失败——本块在任何版本上都能解析，这正是 `MAX_LIST_NESTING` 上限所服务的标准——而是定义期求值失败，且产品中没有任何东西会求值这段文本。把它们与那四个读取点记在一起，可避免把「在所支持范围上可解析」读成「在其上可执行」。
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
index 99ea335b59..3a409f4c4b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.md
 2026-07-31-gui-full-access-confirmation.md: ca89ed23fb1b5c6ea438dd22fdf20d2b82af754c
-2026-07-31-gui-full-access-confirmation.zh.md: 0f487e41b544718bdf38de611a1ab2d59c44b063
+2026-07-31-gui-full-access-confirmation.zh.md: db5f4bc58e05e2441bcaa3da160de3bc9e707a6a
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
index 0f487e41b5..db5f4bc58e 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
@@ -28,4 +28,4 @@ Status: implemented
 
 ## Consequences
 
-进入 Full access 的每条可见 GUI 路径现在都要求刻意且知情的确认，代价是真想启用该预设的用户多一步对话框。新的选择器通过各自拥有的状态机复用共享对话框，或在 popup 路径挂 `confirmation` 载荷。验收：`input-bar.spec.tsx` 中编辑器流的门控用例、`popup-view.spec.tsx` 与 `popup.spec.ts` 的 popup 门、`permission-row.spec.tsx` 的默认设置门控、`atoms.spec.tsx` 的 Modal/RiskConfirmation 契约，以及组装态 Web 回放。
+进入 Full access 的每条可见 GUI 路径现在都要求刻意且知情的确认，代价是真想启用该预设的用户多一步对话框。新的选择器通过各自拥有的状态机复用共享对话框，或在 popup 路径挂 `confirmation` 载荷。验收：`input-bar.spec.tsx` 中编辑器流的门控用例、`popup-view.spec.tsx` 与 `popup.spec.ts` 的 popup 门、`permission-row.spec.tsx` 的默认设置门控、`atoms.spec.tsx` 的 Modal/RiskConfirmation 约定，以及组装态 Web 回放。
diff --git a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
index 3227fac451..7e4d85c66c 100644
--- a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.md
 2026-07-31-permission-default-for-new-sessions.md: ffa4c8a07bdd08ca52edbc14fe10372ad76e8cf8
-2026-07-31-permission-default-for-new-sessions.zh.md: 5fc42724754acc1653ed93b48644794a38f52ba7
+2026-07-31-permission-default-for-new-sessions.zh.md: 0b994a3bf35d02ecc581c82591df624e50c00b2e
diff --git a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
index 5fc4272475..0b994a3bf3 100644
--- a/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.zh.md
@@ -30,6 +30,6 @@ ApiProxy 在可配置提供方 namespace 之外，将 `permission` 显式加入
 
 **创建时只记录 `permission/preset`。** 不予采纳，因为沙箱和审批是由不同组件独立拥有的全量值调节项；固定全部三个事实，可以让其消费方不依赖未来的组合默认值变化。
 
-**暴露所有 Settings 注册，或增加通用的 `local-client` 声明。** 本次变更不予采纳，因为这会扩大安全边界，并使 Settings 契约超出所请求的单项偏好。显式加入 `permission` allowlist 已足够，未来的 namespace 可以各自决定是否暴露。
+**暴露所有 Settings 注册，或增加通用的 `local-client` 声明。** 本次变更不予采纳，因为这会扩大安全边界，并使 Settings 约定超出所请求的单项偏好。显式加入 `permission` allowlist 已足够，未来的 namespace 可以各自决定是否暴露。
 
 **恢复带 seed 的会话时应用最新默认值。** 不予采纳，因为恢复操作必须保留会话先前的有效执行策略；缺失的旧版事实应从该策略中补齐。
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
index 7bcfa9f599..2d393ff905 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
 2026-07-31-telemetry-anonymous-user-id.md: 3c8e3324cb418eac48cb5ae780c55bbcbaf3caa1
-2026-07-31-telemetry-anonymous-user-id.zh.md: 9ff6cf35a90d4087b4ab75987dc9244210e3d46a
+2026-07-31-telemetry-anonymous-user-id.zh.md: 6ba1b7abe0f253fc91e7f8856d9dc9d1d961550b
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
index 9ff6cf35a9..6ba1b7abe0 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
@@ -20,7 +20,7 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 | 并发首启 | `wx` 独占写裁决，落败方重读胜者 id | 覆盖常见并发（重读撞进胜者建档-写入微秒窗仍可能各持一 id 一次运行，下次启动收敛到落盘值——telemetry 级后果，接受） |
 | 丢失语义 | 文件被删 → 下次启动换新 id，接受丢失 | 匿名身份无恢复价值；可恢复性要求派生材料，与匿名冲突 |
 | 写失败 | best-effort 返回内存 id | telemetry 永不因 home 只读被阻塞 |
-| 上报位置 | Resource 属性，非逐条 attributes | 每批一次即够接收端按 Resource 维度聚合；逐条注入要动 seam 契约且涨 wire 体积 |
+| 上报位置 | Resource 属性，非逐条 attributes | 每批一次即够接收端按 Resource 维度聚合；逐条注入要动 seam 约定且涨 wire 体积 |
 | semconv 依赖 | 不引 `@opentelemetry/semantic-conventions` 包 | 一个字符串常量不值一个依赖 |
 | 落点 | `session-telemetry-otel` 包内模块，非公共 util 包 | 仓规「有第二个真实消费者才拆包」；sdk launcher 回流保留自有存储，无现实关联需求 |
 | 单独开关 | 无 | 身份跟随 telemetry 整体开关（`DSH_TELEMETRY_DISABLED`）；关 telemetry 即整体不报 |
@@ -30,7 +30,7 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 | 被拒 | 一句话理由 |
 |---|---|
 | hostname/IP 哈希派生 id（此前口径） | 可反查即非匿名；随机 UUID 语义干净，用户裁决取代 |
-| user.id 放每条 record 的 attributes（Claude Code 形态） | 要动 session-telemetry seam 契约或逐条注入，wire 体积涨；Resource 每批一次已满足聚合 |
+| user.id 放每条 record 的 attributes（Claude Code 形态） | 要动 session-telemetry seam 约定或逐条注入，wire 体积涨；Resource 每批一次已满足聚合 |
 | 公用 util 包统一两条回流（初版实现） | 唯一现实消费者是 OTel backend；sdk launcher 换用它只是为统一而统一——用户复议收回，回流关联需求出现时再抽包 |
 | 复用 telemetry.json 不新建文件 | 文件名/JSON 格式把身份挂在 launcher 链路命名下；OTel 回流身份是独立事实 |
 | AppCLIEntry 读好 id 经 config patch 注入 | 每个 surface 入口都要接线；config 里传运行时事实与部署配置混淆 |
diff --git a/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.i18n.yaml
index 025c838a7d..1346111448 100644
--- a/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.md
 2026-07-31-third-party-memory-mcp-examples.md: e82d65a3a5a60cafcc47df5a6873cf5768cd8b8f
-2026-07-31-third-party-memory-mcp-examples.zh.md: 18502f0c30fdbd62ffe49e34c587785d123046d2
+2026-07-31-third-party-memory-mcp-examples.zh.md: 512018b05bac6d175077d9dd82ebf8c328fc5a89
diff --git a/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.zh.md b/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.zh.md
index 18502f0c30..512018b05b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-third-party-memory-mcp-examples.zh.md
@@ -31,7 +31,7 @@ Status: implemented
 
 ## 版本固定、存储与身份
 
-| 提供方 | 已测试契约 |
+| 提供方 | 已测试约定 |
 |---|---|
 | Memorix | npm `1.3.0`，tag commit `500792cad3144142293bfbb20acb4841c9f7fcfa` |
 | MCP Reference Memory | npm `2026.7.4`，package commit `6dd0a683e198783e30feabf7abaf42f925bd18b1` |
@@ -49,7 +49,7 @@ Status: implemented
 
 提供方的工具描述仍然是权威定义。
 
-## 验证契约
+## 验证约定
 
 远程 CI 不会访问第三方服务或消耗密钥。无密钥套件解析全部三份 overlay 文件，检查其通用桥接器和密钥边界，将上游端点替换为包自带的 MCP fixture（测试前置数据）服务器，通过真实 Cordis Loader 启动，并验证工具发现。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
index 1c04bc1d55..7c42b6c7dc 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-default-search.md
 2026-07-31-web-default-search.md: 8f2cc6f5d1a9ec9f33279ae8e5c992bdc660e7fa
-2026-07-31-web-default-search.zh.md: 7d528617143cb9756d0a4532bb1ed6a3a3e70ca8
+2026-07-31-web-default-search.zh.md: 46db167b84f8c1a10686a941b174008ebafc720d
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
index 7d52861714..46db167b84 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-default-search.zh.md
@@ -16,7 +16,7 @@ DeepSeek 搜索使用与官方会话适配器相同的 `DEEPSEEK_API_KEY` 凭据
 
 搜索端点与 chat completions 保持独立：`DEEPSEEK_SEARCH_BASE_URL` 覆盖 Anthropic 兼容基址，`DEEPSEEK_BASE_URL` 则继续配置会话请求。每次 `web_search` 都会发起一次辅助 DeepSeek Messages 调用，并携带原生搜索服务器工具。发出请求前一刻，提供方会向发起请求的 agent（智能体）会话追加仅用于日志的 LLM（大语言模型）请求事件 `web/deepseek-search-llm-request`，其中包含已解析端点、API 版本，以及不含密钥的精确 JSON 请求体。凭据预检仍留在提供方内部，并与调用方取消存在竞态；这两项关注点都不会扩展通用 Web seam 或凭据 seam。
 
-默认挂载不会创建 Web 专用权限策略。`web_search` 在 bash／文件系统沙箱及审批预设之外执行，并遵循 `dsh-tool-web` 的现有契约。组合不挂载 `web_fetch` 或本地抓取提供方，因此默认配置不会允许模型自行选择任意 URL 进行抓取。已交付的 `workspace-write` 默认值只管辖文件修改；若产品采取受限网络策略，就需要添加 `tools/pre-execute` 策略或按能力限制网络访问，而不能暗示文件系统访问模式会管辖 Web 调用。
+默认挂载不会创建 Web 专用权限策略。`web_search` 在 bash／文件系统沙箱及审批预设之外执行，并遵循 `dsh-tool-web` 的现有约定。组合不挂载 `web_fetch` 或本地抓取提供方，因此默认配置不会允许模型自行选择任意 URL 进行抓取。已交付的 `workspace-write` 默认值只管辖文件修改；若产品采取受限网络策略，就需要添加 `tools/pre-execute` 策略或按能力限制网络访问，而不能暗示文件系统访问模式会管辖 Web 调用。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index c1cc57b233..dc6aad3b11 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
 2026-07-31-web-workspace-file-links.md: fe71a2d8caa4dc9cc732a250d7e388d1a3b44182
-2026-07-31-web-workspace-file-links.zh.md: 0f8c87822087169aad9ac4283f706fd8a8748be9
+2026-07-31-web-workspace-file-links.zh.md: d2e49f4816a014dd5ec700b4d6f8fa0bede03e67
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index 0f8c878220..d2e49f4816 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-- **由 harness 提供 `/f/<sessionId>/<segments…>`**——已经实现并可用，包含双 `realpath` 收敛、浏览器信任 fence、流式读取，以及一个以自身端口给所服务文档独立源的监听器。它是唯一能把预览呈现给另一台机器上客户端的设计，而那恰恰是被判出范围的场景。因此退役，而不是因为它失败了；它的代价是一个带自身生命周期的第二 socket、一个注入页面的端口，以及一份跨两个包共享的 URL 形状契约。
+- **由 harness 提供 `/f/<sessionId>/<segments…>`**——已经实现并可用，包含双 `realpath` 收敛、浏览器信任 fence、流式读取，以及一个以自身端口给所服务文档独立源的监听器。它是唯一能把预览呈现给另一台机器上客户端的设计，而那恰恰是被判出范围的场景。因此退役，而不是因为它失败了；它的代价是一个带自身生命周期的第二 socket、一个注入页面的端口，以及一份跨两个包共享的 URL 形状约定。
 - **同源 HTTP 提供且不加隔离**——经实测不安全，记录在此以免有人重试：与 `/api` 并排提供的文档把 `settings.describe` 打到 `200` 并拿到完整数据，把 `session.list` 打到 35 KB 的全部会话转录，而这个页面根本不必由 agent 撰写（一条 read 行就让 clone 下来的仓库里任何文件变得可打开）。
 - **在那套同源提供之上加 `Content-Security-Policy: sandbox`**——它以剥夺文档的源来堵住这个洞，而这经实测会破坏本功能存在的意义所在的那类页面：所报告的产物在加载时抛 `SecurityError`，又因为未捕获异常会中止其 `<script>` 的其余部分，该行之后声明的所有监听器——主题切换、移动端菜单、模型 tabs——统统不会绑定。报告者工作区里四份产物有两份在它之下是死页面，而且它们渲染得完美无缺，所以这种破坏是看不见的。
 - **把路径在助手的收尾消息里链接化**——这是用户开口要的形状（“在结尾附上链接”），但它让渲染取决于模型是否把路径拼写得可识别。工具调用已经把 `locations` 作为结构化事实携带，产出文件行消费的正是它。
diff --git a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
index d4ec255235..fb9f46c641 100644
--- a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.md
 2026-08-01-pwsh-tool-and-executor.md: 7206f8ffe6640f8499f8453c40ab5846b23112c6
-2026-08-01-pwsh-tool-and-executor.zh.md: 5a48adb79fed209d2d2ecb9514fd51538491f04c
+2026-08-01-pwsh-tool-and-executor.zh.md: c59ba8e3e6c68d48d310861325c74dc6cec8e5c3
diff --git a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
index 5a48adb79f..c59ba8e3e6 100644
--- a/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md
@@ -13,7 +13,7 @@ harness 在每个平台只说一种 shell 方言：`bash`。Windows 主机只能
 在 `packages/bash/` 下新增两个包：
 
 - **`@deepseek-ai/dsh-pwsh-local`** —— `ctx.bash` 执行器 seam 的本地实现，基于 `ctx.subprocess`，逐调用镜像 `dsh-bash-local`：`resolve()` 从配置默认化并设上限，`run()` 通过一个 deadline 融合配置夹取的超时与调用方信号，`start()` 返回消费式后台句柄，其进程归属于 subprocess 服务。命令字符串作为 ONE argv 元素传给 `pwsh -NoLogo -NoProfile -NonInteractive -Command`，由 PowerShell 解析，不存在 shell 引号层。可执行文件解析（`resolvePwshPath`）是 `(configured, env, platform)` 的纯函数：先显式配置，再在 Windows 上探测 PowerShell 7 安装位置、PATH 条目（剥离引号）与 Windows PowerShell 5.1，否则经 PATH 解析裸 `pwsh`。
-- **`@deepseek-ai/dsh-tool-pwsh`** —— 基于 `ctx.bash` 的面向模型工具，契约是 PowerShell 方言，逐调用镜像 `dsh-tool-bash`、减去 sandbox 面：经通用任务运行时执行前台与 `run_in_background`，经共享 [`dsh-bash-env`](../feature/2026-08-02-pwsh-tool-bash-parity.md) 注册表管理 `DSH_*` 环境，以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。parity 决策取代了本 note 的最小画像工具描述。
+- **`@deepseek-ai/dsh-tool-pwsh`** —— 基于 `ctx.bash` 的面向模型工具，约定是 PowerShell 方言，逐调用镜像 `dsh-tool-bash`、减去 sandbox 面：经通用任务运行时执行前台与 `run_in_background`，经共享 [`dsh-bash-env`](../feature/2026-08-02-pwsh-tool-bash-parity.md) 注册表管理 `DSH_*` 环境，以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。parity 决策取代了本 note 的最小画像工具描述。
 
 Windows vitest 覆盖率刻意不属本次改动：仓库的 Windows CI 通道负责构建/静态门禁，单元覆盖在 Linux 上运行，两个包的套件在那里以真实 `pwsh` 运行（GitHub 托管 runner 预装）或缺失时自行跳过。vitest 的 `windowsUnsupportedPackages` 排除从 `packages/bash/*` 收窄为真正需要 bash 的包，使 pwsh 套件也能在 Windows 开发机上原生运行。
 
@@ -23,13 +23,13 @@ Windows vitest 覆盖率刻意不属本次改动：仓库的 Windows CI 通道
 
 **给 `dsh-bash-local` 增加 pwsh 模式。** 否决：执行器的身份就是它 spawn 的 shell；在一个包内塞第二种方言会翻倍配置面（`shell` 开关）与测试矩阵，且两种方言的怪癖（Windows 上的信号实情、引号域）应各自归入自己包的文档。
 
-**给 `dsh-tool-bash` 增加方言参数。** 否决：bash 工具的后台/沙箱表面是 bash 形状的；`pwsh` 模式要么隐藏它（条件 schema 翻动），要么继承它（把最小画像明确拒绝的表面带进来）。最小孪生让模型契约保持诚实。
+**给 `dsh-tool-bash` 增加方言参数。** 否决：bash 工具的后台/沙箱表面是 bash 形状的；`pwsh` 模式要么隐藏它（条件 schema 翻动），要么继承它（把最小画像明确拒绝的表面带进来）。最小孪生让模型约定保持诚实。
 
 **现在就接入交付的 CLI 组合。** 否决：在 Windows 默认决策落地前把 `tool-pwsh` + `pwsh-local` 挂进 `base.cordis.yml` 会改变交付清单；本改动交付能力与接线点（`apps/cli` 依赖、tsconfig 工程），不切换任何默认。
 
 ## 后果
 
-- bash 执行器 seam 有了第二个、Windows 原生的实现，请求/规范契约一致，因此 `tool-pwsh` 之外的面向模型消费方（hooks 桥、进程内插件）无需方言垫片即可运行 PowerShell。
-- `tool-pwsh` 是模型可见的 Windows 优先 shell 工具：在前台与后台工作（减 sandbox）上与 bash 工具行为可互换，提示词指导精确陈述 marker 契约。
+- bash 执行器 seam 有了第二个、Windows 原生的实现，请求/规范约定一致，因此 `tool-pwsh` 之外的面向模型消费方（hooks 桥、进程内插件）无需方言垫片即可运行 PowerShell。
+- `tool-pwsh` 是模型可见的 Windows 优先 shell 工具：在前台与后台工作（减 sandbox）上与 bash 工具行为可互换，提示词指导精确陈述 marker 约定。
 - Windows 语义在平台差异处不同：强制终止报告退出码 1 且无信号（因此 `signal`/`killed` 状态实情仅限 POSIX），PowerShell 输出 CRLF，测试做归一化。
 - CLI 增加两个 workspace 依赖与两个 tsconfig 工程，但不挂载任一插件——组合决策留给 Windows 默认提案。
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
index 40e24e9ac2..602d272b0b 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
 2026-08-02-pwsh-tool-bash-parity.md: e35a903892d5d50a0d3ca12b23daa53f26d6aade
-2026-08-02-pwsh-tool-bash-parity.zh.md: d7a68f0cab5281b25c3321e7ffff61c358b21a0a
+2026-08-02-pwsh-tool-bash-parity.zh.md: c6e1d69bd061f0794b125e225d8f976bd82224e7
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
index d7a68f0cab..c6e1d69bd0 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。对该变更的 review 发现模型可见契约与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
+首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。对该变更的 review 发现模型可见约定与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
 
 ## 决策
 
@@ -20,9 +20,9 @@ Status: implemented
 
 ## 备选方案
 
-**保留最小画像，只修声明。** 否决：review 的核心发现是"从 bash 复制的文本契约在缺少对应实现时会漂移"；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
+**保留最小画像，只修声明。** 否决：review 的核心发现是"从 bash 复制的文本约定在缺少对应实现时会漂移"；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
 
-**在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对契约改由各工具 README 记录。
+**在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对约定改由各工具 README 记录。
 
 **提取完全共享的工具实现基座（抽象 shell 方言，两个薄叶子）。** 考虑后推迟：bash-env 提取与结构镜像（`render.ts`/`background.ts` 孪生）是它要立足的基础；在出现第三种方言或持久 PTY 孪生、让抽象的形态可观察之前，不做完整基座。
 
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
index c12de68dc8..484df46a31 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md
 2026-08-02-web-thinking-tail-scroll.md: 18e94b2e0075bf7099b9b48177de2e274896942a
-2026-08-02-web-thinking-tail-scroll.zh.md: 9b1428af7d3ab3c25509696619de75adc1cd7b7f
+2026-08-02-web-thinking-tail-scroll.zh.md: 7bafeb0f64f05a41c502aba8f479e391c8b395f0
diff --git a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
index 9b1428af7d..7bafeb0f64 100644
--- a/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md
@@ -12,7 +12,7 @@ Web Think 行在结算与流式 block 中都把 reasoning 首行渲染成折叠
 
 只有 reasoning block 是当前流式尾部、且仍处于折叠态的 Think 行会跟随实时输出。其摘要使用最新的非空行，而不是结算后的首行；已有单行摘要元素成为程序化横向滚动区，每次文本更新后钉到 `scrollWidth - clientWidth`。这里刻意直接赋值 `scrollLeft`，通过真实 delta 推进而不虚构独立的跑马灯速度：token 快则移动快，模型停顿则停止，短文本因滚动范围为零而保持静止。
 
-该行为由已有呈现组件拥有。`AssistantMarkdown` 只在 Think 行运行时选择最新行；`ToolRow` 已经拥有折叠／展开状态，因此由它决定摘要是否追随行内末端。不改变 session、wire、持久事件或模型可见契约。展开会移除折叠摘要，并让完整 reasoning 正文进入普通页面流。该行结算后恢复稳定首行，同时把摘要重置到左端。其他工具摘要与已结算 Think 行保留已有省略号行为。
+该行为由已有呈现组件拥有。`AssistantMarkdown` 只在 Think 行运行时选择最新行；`ToolRow` 已经拥有折叠／展开状态，因此由它决定摘要是否追随行内末端。不改变 session、wire、持久事件或模型可见约定。展开会移除折叠摘要，并让完整 reasoning 正文进入普通页面流。该行结算后恢复稳定首行，同时把摘要重置到左端。其他工具摘要与已结算 Think 行保留已有省略号行为。
 
 ## 曾考虑的替代方案
 
@@ -28,4 +28,4 @@ Web Think 行在结算与流式 block 中都把 reasoning 首行渲染成折叠
 
 ## 测试
 
-`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的 keyless 完整 Chromium 场景以可观察节奏回放真实录制的 reasoning chunks，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态 replay golden 保持不变，证明历史摘要契约仍然稳定。
+`packages/client/ui-conversation/tests/reasoning-row.spec.tsx` 固定最新行选择、算出的右端滚动位置，以及结算后恢复首行和 `scrollLeft = 0`。`apps/web/tests/lifecycle-chrome.e2e.ts` 中的 keyless 完整 Chromium 场景以可观察节奏回放真实录制的 reasoning chunks，把视口收窄到摘要溢出，并断言实时折叠 Think 行到达真实浏览器的滚动边界。其结算态 replay golden 保持不变，证明历史摘要约定仍然稳定。
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
index 2ba0af23c4..7d6edc23db 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
 2026-08-03-web-search-source-scroll.md: 3215302b2f6c7a4e6d6cd7440a0c7f5048b72a80
-2026-08-03-web-search-source-scroll.zh.md: cf75a5e34632872d09a13e1667ecac5f01428e18
+2026-08-03-web-search-source-scroll.zh.md: 88f2ef9869ef5de7483eb0d7e2a76f8c14e8356b
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
index cf75a5e346..88f2ef9869 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 模型侧不变：seam 仍在 `searchMaxResults` 处封顶来源，面向模型的 render 文本未动，`truncated` 标志及其 `来源列表已截断` 指示保留。卡片完整且可滚动地画出 seam 产出的这份列表，而非折叠其中段。
 
-只要工具下游没有单独改写结果 content，这份列表就是模型读到的那份。挂载了 `dsh-spill-policy` 的部署会对超限结果打破这一对应：`tools/post-execute` 把面向模型的 `content` 替换为预览加 spill 定位符，而 `presentationMeta` 原样保留，因此卡片仍画出全部来源，模型读到的却是一段有界摘录。所以卡片的契约是它收到的 view，不是模型的上下文。
+只要工具下游没有单独改写结果 content，这份列表就是模型读到的那份。挂载了 `dsh-spill-policy` 的部署会对超限结果打破这一对应：`tools/post-execute` 把面向模型的 `content` 替换为预览加 spill 定位符，而 `presentationMeta` 原样保留，因此卡片仍画出全部来源，模型读到的却是一段有界摘录。所以卡片的约定是它收到的 view，不是模型的上下文。
 
 `CHAT_WEB_MAX_SOURCES` 与该 primitive 的 `DEFAULT_WEB_MAX_SOURCES` 被移除：有了滚动，聊天行与详情面板展示同一份完整列表，仅以各自的容器高度区分。`<li value={ordinal}>` 仍钉住每条来源从 1 起算的引用序号；没有了折叠造成的间断，这些序号如今就是连续的。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
index 4673ffaab7..a15dbc2234 100644
--- a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md
 2026-08-04-claude-code-and-codex-subagent-backends.md: e81d1fb14f719331c503dba539d6a5ec0f1eed4f
-2026-08-04-claude-code-and-codex-subagent-backends.zh.md: 3c78e8d5a4ca1a86942971721ad05c631901f231
+2026-08-04-claude-code-and-codex-subagent-backends.zh.md: ae5bb9f93dc027e7e6e59912b7e2ef00095a2162
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
index 3c78e8d5a4..ae5bb9f93d 100644
--- a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
@@ -55,7 +55,7 @@ Codex 0.146.0 使用 Responses 协议，而 DeepSeek 的公开 OpenAI 兼容端
 
 启动回滚和已发布运行的资源释放都会关闭 SDK query、中止该次运行的控制器、调用共享的进程树终止机制，并等待整棵进程树退出。`Query.close()` 表达优雅的协议关闭意图，但不能取代子进程责任方的退出证明。Query 关闭失败、进程失败和清理失败仍可彼此独立地观察。
 
-带密钥 Claude Code e2e 直接使用官方 DeepSeek Claude Code 契约：仅在运行时提供的 DeepSeek 密钥会映射为 `ANTHROPIC_AUTH_TOKEN`，固定的官方基础 URL 会追加 `/anthropic`，主模型与 subagent 模型变量会选择文档所示的 DeepSeek 模型。该测试会启动生产提供方与真实 SDK 和 CLI，要求一个随机数作为完整答案，不会把任何凭据持久化到设置中，并等待所有受管句柄退出。
+带密钥 Claude Code e2e 直接使用官方 DeepSeek Claude Code 约定：仅在运行时提供的 DeepSeek 密钥会映射为 `ANTHROPIC_AUTH_TOKEN`，固定的官方基础 URL 会追加 `/anthropic`，主模型与 subagent 模型变量会选择文档所示的 DeepSeek 模型。该测试会启动生产提供方与真实 SDK 和 CLI，要求一个随机数作为完整答案，不会把任何凭据持久化到设置中，并等待所有受管句柄退出。
 
 ## 分发与证据
 
@@ -83,11 +83,11 @@ Claude Code 证据锁定 Agent SDK 0.3.220 及其平台分发的 Claude Code 2.1
 
 **由插件管理登录、产品主目录、模型、设置或权限。** 这些选择会在每个产品的原生配置之外建立另一套权威来源，并将一次性提供方扩张为账户管理功能。提供方只公开显式环境覆盖项和清理宽限期；无人值守交互会以默认拒绝方式失败。
 
-**续接、进度、后台收集和共享父级上下文。** 已交付的用户结果是一项自包含任务和一个最终回答。产品会话、恢复、后续交互、中间消息、父级 transcript（文本记录）传递、结构化输出和后台收集都需要独立的用户契约，当前实现不会预先构建这些功能。
+**续接、进度、后台收集和共享父级上下文。** 已交付的用户结果是一项自包含任务和一个最终回答。产品会话、恢复、后续交互、中间消息、父级 transcript（文本记录）传递、结构化输出和后台收集都需要独立的用户约定，当前实现不会预先构建这些功能。
 
 ## 后果
 
-用户可以安装任一或两个产品提供方，在自己的 Cordis 配置中绑定稳定的前台工具，并通过现有 subagent 契约委派一项自包含任务。官方产品集成会保留原生设置与行为，而共享服务继续独占任务结算与进程树完全停稳的责任。
+用户可以安装任一或两个产品提供方，在自己的 Cordis 配置中绑定稳定的前台工具，并通过现有 subagent 约定委派一项自包含任务。官方产品集成会保留原生设置与行为，而共享服务继续独占任务结算与进程树完全停稳的责任。
 
 每次委派都要承担新建产品进程和独立模型上下文的开销，且只有最终文本会到达父级。产品原生配置使行为取决于部署环境中安装的产品、账户状态和工作区设置。带密钥 e2e 运行还会消耗外部 API 配额，并依赖 DeepSeek 官方端点；对协议、失败、取消与审批的确定性覆盖仍由无密钥层级承担。提供方不会恢复会话、以流式方式传送进度、接受新的人工交互、回滚工具或文件副作用，也不会施加按实际经过时间触发的超时。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
index 86c05dc9bd..4710d92679 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
 2026-08-04-pointer-revealed-sidebar-scrollbars.md: eb86f710e44cd8f1fb2cef41db99504af42413bb
-2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: 598c10dc2373eeb821d05f349a662156b194c71b
+2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: 4f871a70298396b8ed75b39c2a4d199b69061472
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
index 598c10dc23..4f871a7029 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定接缝：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
 
-这拓宽了重新绑定契约，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
+这拓宽了重新绑定约定，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
 
 隐藏不再算作抬升：只有 l2 重绑才能让一张样式表免于「任何既滚动又绘制抬升表面的样式表都必须重新绑定」。既隐藏滚动条又在抬升表面上滚动的样式表，仍然欠着那里真正绘制滑块时所需的 l2。
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
index 51401adfdc..439826ee6c 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
 2026-08-05-pwsh-ui-bash-parity.md: 815b448b894e9c53b4c4a2076f6b94fdd316dd35
-2026-08-05-pwsh-ui-bash-parity.zh.md: 967c5a9e1409028043dc5028fdca640ddfeb1acc
+2026-08-05-pwsh-ui-bash-parity.zh.md: 40109a32ed146a31a2424feb53a7cf0f41d87106
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
index 967c5a9e14..40109a32ed 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
@@ -18,11 +18,11 @@ Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 ter
 
 ## Alternatives considered
 
-**从 `@deepseek-ai/dsh-tool-bash/src/render.ts` 导入 `parseExitStatus`。** 否决：workspace 导入在构建产物中保持外部引用，因此 `tool-pwsh` 会在每个消费方闭包中新增对 `tool-bash` 的硬运行时依赖（包括刻意只挂 pwsh 孪生、不挂 bash 的组合），且兄弟工具为其单个函数依赖孪生会颠倒包间关系。seam 迁移把共享契约放在两个工具本就依赖的包上。
+**从 `@deepseek-ai/dsh-tool-bash/src/render.ts` 导入 `parseExitStatus`。** 否决：workspace 导入在构建产物中保持外部引用，因此 `tool-pwsh` 会在每个消费方闭包中新增对 `tool-bash` 的硬运行时依赖（包括刻意只挂 pwsh 孪生、不挂 bash 的组合），且兄弟工具为其单个函数依赖孪生会颠倒包间关系。seam 迁移把共享约定放在两个工具本就依赖的包上。
 
 **新建专用呈现包（如 `@deepseek-ai/dsh-shell-present`）。** 否决：为一个纯函数新建包要付出 manifest、module-graph/目录再生成与 README 面的成本；`@deepseek-ai/dsh-bash` 已在两个工具的闭包中，且已拥有该解析重建的 `BashRunResult` 事实。
 
-**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：parity 评审的核心发现正是"复制的文本契约缺少共享实现就会漂移"；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的契约。
+**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：parity 评审的核心发现正是"复制的文本约定缺少共享实现就会漂移"；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的约定。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
index 222ed1ebbe..d89233e8eb 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.md
 2026-08-06-bundled-dsh-badge-skill.md: 512f67ca347ca311a1f80fef932f6af8c91b0fe9
-2026-08-06-bundled-dsh-badge-skill.zh.md: 88fcadf66944cb91419441be3916ae04968be663
+2026-08-06-bundled-dsh-badge-skill.zh.md: cedb03325f3e963c3fa217b72dcfce31eb44bfe7
diff --git a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
index 88fcadf669..cedb03325f 100644
--- a/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-bundled-dsh-badge-skill.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 交付的 CLI 组合将 `skill-badge` 声明为禁用。启用这个现有配置行就是显式选择加入；禁用它的安装实例不会公开任何徽章 skill（技能），也不会获得任何模型可见内容。
 
-该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank，因此用户自有的 `dsh-badge` 定义可通过注册表的常规优先级契约覆盖它。提供方释放时，注册表拥有的 effect 会移除该贡献。
+该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank，因此用户自有的 `dsh-badge` 定义可通过注册表的常规优先级约定覆盖它。提供方释放时，注册表拥有的 effect 会移除该贡献。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
index 3fccf77cc4..fc6a76df8b 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md
 2026-08-06-continuable-subagent-interrupt.md: cb97a77434b43ee71fa30deee9811f7a45c53f1a
-2026-08-06-continuable-subagent-interrupt.zh.md: ee05afd963584331def8c7d6acfa26830b7c1d0f
+2026-08-06-continuable-subagent-interrupt.zh.md: e311cae0d5eecce508aba5351b1766282b294abb
diff --git a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
index ee05afd963..e311cae0d5 100644
--- a/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md
@@ -39,9 +39,9 @@ Host RPC `subagent.interrupt` 接收 continuable 的 `SubagentAddress` 并返回
 
 仅凭地址的 RPC 会暴露一位在线驻留信息：不存在的目标会被接受，而 parent 不匹配的在线目标会返回 `subagent-unauthorized`。单用户本地 Host 的信任模型接受这种可观察性；未来的多主体 Host 必须重新审视权限和响应不可区分性。
 
-在 Web 侧，正在运行的 continuable child 使用相互独立的 Send 与 Stop 操作：客户端 `Session.cancel()` 将 Stop 路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍通过 `session.cancel` 保留既有的 primary Send/Stop 切换），同时 Send 继续将后续消息加入队列。parent 离线但仍在运行的 continuable child 保留默认 composer，禁用输入区与 Send，但 Stop 仍然可达；停止后恢复只读替代（周边目录与 composer 契约由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。
+在 Web 侧，正在运行的 continuable child 使用相互独立的 Send 与 Stop 操作：客户端 `Session.cancel()` 将 Stop 路由到 `subagent.interrupt`（one-shot 地址保持不可取消，普通会话仍通过 `session.cancel` 保留既有的 primary Send/Stop 切换），同时 Send 继续将后续消息加入队列。parent 离线但仍在运行的 continuable child 保留默认 composer，禁用输入区与 Send，但 Stop 仍然可达；停止后恢复只读替代（周边目录与 composer 约定由 [Web subagent 对话](2026-07-27-web-subagent-conversations.md)拥有）。
 
-`dsh-tool-subagent-control` 中面向模型的 `interrupt_agent(agent_id)` 工具把 `exec.agent` 作为 `ancestor` 授权传入，自身不增加任何权限：核心原语校验在线注册表身份与记录的 lineage，因此该工具可以用同一个通用 `agent_id` 参数指定直接 child 或更深的后代——刻意不用会暗示仅限直接 child 的 `subagent_id`。发现依赖 `list_agents({ scope: 'descendants' })`，其底层是新的 `SubagentService.listDescendants()` 单次追踪 pre-order 遍历，每个条目带经校验的 `parentId`／`depth`（列表契约由[持久化目录 note](2026-07-22-durable-subagent-catalog-and-list-agents.md)拥有）；发现只是提示，绝非权限。`send_message` 保持其确切直接 parent 权限——只有中断是 ancestor 级的。
+`dsh-tool-subagent-control` 中面向模型的 `interrupt_agent(agent_id)` 工具把 `exec.agent` 作为 `ancestor` 授权传入，自身不增加任何权限：核心原语校验在线注册表身份与记录的 lineage，因此该工具可以用同一个通用 `agent_id` 参数指定直接 child 或更深的后代——刻意不用会暗示仅限直接 child 的 `subagent_id`。发现依赖 `list_agents({ scope: 'descendants' })`，其底层是新的 `SubagentService.listDescendants()` 单次追踪 pre-order 遍历，每个条目带经校验的 `parentId`／`depth`（列表约定由[持久化目录 note](2026-07-22-durable-subagent-catalog-and-list-agents.md)拥有）；发现只是提示，绝非权限。`send_message` 保持其确切直接 parent 权限——只有中断是 ancestor 级的。
 
 ## Testing
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
index 7550af746a..8f72736ce9 100644
--- a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.md
 2026-08-06-resolved-theme-color-metadata.md: 2f7a6f0bde5e75aeb6769939cae54d5319aa5bae
-2026-08-06-resolved-theme-color-metadata.zh.md: a6d530f841d5c744fc88831f9cb685d1ab5027b6
+2026-08-06-resolved-theme-color-metadata.zh.md: 0312794c607b59f4772d498e1533e0af70b9fbbe
diff --git a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
index a6d530f841..0312794c60 100644
--- a/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md
@@ -16,7 +16,7 @@ ui-layout 的 `ThemePresenter` 拥有一个 `<meta name="theme-color">`，与根
 
 ## 验证
 
-呈现器的单元测试契约覆盖浅色和深色模式下的计算颜色、节点复用及资源释放。ui-layout 组合测试覆盖初始插入、事件驱动的复用和 fiber 清理。Web 浏览器设置场景通过实际交付的组合依次驱动 Light、Dark、System、操作系统偏好变化和重新加载，并断言页面始终只有一个元数据元素，其内容等于计算后的 body 背景且控制台无错误。这项元数据变更不会出现在渲染后的无障碍树输出中，因此场景现有的预期输出保持不变。
+呈现器的单元测试约定覆盖浅色和深色模式下的计算颜色、节点复用及资源释放。ui-layout 组合测试覆盖初始插入、事件驱动的复用和 fiber 清理。Web 浏览器设置场景通过实际交付的组合依次驱动 Light、Dark、System、操作系统偏好变化和重新加载，并断言页面始终只有一个元数据元素，其内容等于计算后的 body 背景且控制台无错误。这项元数据变更不会出现在渲染后的无障碍树输出中，因此场景现有的预期输出保持不变。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
index d13ede02d2..000c72f6ed 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-web-install-manifest.md
 2026-08-06-web-install-manifest.md: d400c6e586f4b735fa8e3dcc4899c97e45ac89c1
-2026-08-06-web-install-manifest.zh.md: a7fee0248261e8d0597bb773d4f390973147337b
+2026-08-06-web-install-manifest.zh.md: d32ccf25c7b0e13a4094af4364a97385032462b7
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
index a7fee02482..d32ccf25c7 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-install-manifest.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Web 构建产物已有文档标题和 favicon，却没有可供浏览器发现稳定安装身份、启动边界或安装后呈现方式的 manifest（元数据清单）。添加这类元数据也可能暗示应用并不具备的能力：service worker 会让人以为应用提供离线契约，而单一语言或调色板取值会错误描述这个能够解析浅色与深色主题的双语 UI。
+Web 构建产物已有文档标题和 favicon，却没有可供浏览器发现稳定安装身份、启动边界或安装后呈现方式的 manifest（元数据清单）。添加这类元数据也可能暗示应用并不具备的能力：service worker 会让人以为应用提供离线约定，而单一语言或调色板取值会错误描述这个能够解析浅色与深色主题的双语 UI。
 
 ## 决策
 
@@ -24,7 +24,7 @@ Web 构建产物测试解析输出的 manifest，并固定完整的元数据对
 
 ## 曾考虑的替代方案
 
-**添加 service worker，并宣称应用支持离线。** 不予采纳，因为只缓存应用外壳，却不定义会话传输、失效策略、失败行为和升级语义，会形成具有误导性的不完整离线契约。
+**添加 service worker，并宣称应用支持离线。** 不予采纳，因为只缓存应用外壳，却不定义会话传输、失效策略、失败行为和升级语义，会形成具有误导性的不完整离线约定。
 
 **声明单一的 `lang`。** 不予采纳，因为没有任何一种语言足以描述双语产品界面；省略该字段可避免声称安装后的体验由某一种区域设置独占。
 
@@ -36,4 +36,4 @@ Web 构建产物测试解析输出的 manifest，并固定完整的元数据对
 
 ## 后果
 
-支持这一机制的浏览器可以发现以根路径为作用域的稳定安装身份和全屏偏好，而应用无需承诺离线行为。在路径前缀下部署该构建产物时，必须同时重新审视绝对路径的 manifest 链接，以及身份、启动、作用域和图标 URL。日后可能因浏览器特有的图标要求而新增变体；每一项有意的元数据变更都会同步更新精确的构建产物契约。
+支持这一机制的浏览器可以发现以根路径为作用域的稳定安装身份和全屏偏好，而应用无需承诺离线行为。在路径前缀下部署该构建产物时，必须同时重新审视绝对路径的 manifest 链接，以及身份、启动、作用域和图标 URL。日后可能因浏览器特有的图标要求而新增变体；每一项有意的元数据变更都会同步更新精确的构建产物约定。
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
index 7ea7b3b14f..55ce6ceeb9 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.md
 2026-08-06-web-skill-tool-row.md: 04e8ffcd6e506142b569e60458af144233810bbd
-2026-08-06-web-skill-tool-row.zh.md: b96b3879f989f4f1934cdffaec83a283d74aa220
+2026-08-06-web-skill-tool-row.zh.md: c68ddea1d44e3b071deafc9450f6a2d09023cd80
diff --git a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
index b96b3879f9..c68ddea1d4 100644
--- a/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md
@@ -10,20 +10,20 @@ Web transcript（文本记录）通过通用后备行渲染 `skill` 调用，使
 
 ## 决策
 
-`ui-skill` 在 ui-tool 的 `tool.call.toolview` keyed slot 下注册 key 为 `skill` 的组件。该组件消费公开的 `ToolCallViewProps` owner 契约，并自行实现行 chrome，不导入 ui-tool 的展示内部实现。
+`ui-skill` 在 ui-tool 的 `tool.call.toolview` keyed slot 下注册 key 为 `skill` 的组件。该组件消费公开的 `ToolCallViewProps` owner 约定，并自行实现行 chrome，不导入 ui-tool 的展示内部实现。
 
 收起的行使用 14 像素的文档与闪光组合图标，并沿用 Bash 行的中性色层级：图标采用三级色，`Skill` 标题采用二级色，分隔符采用 caption 色，skill 名称采用三级色。运行、失败和中断调用分别沿用 transcript 的扫光、错误状态点加首行摘要，以及警告状态点语义。已结算调用可以通过整个摘要行展开一个高度上限为 260 像素的 `Instructions` 卡片，其中原样呈现持久化结果文本；用于跳转至 trajectory 的现有 `Inspect` 入口仍保留在卡片下方。
 
-该行的所有可见值均派生自当前 runtime 窗口中已配对的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。如果分页将调用留在窗口外，结果便没有工具身份，并继续使用通用后备路径，而不是扩展 history 协议契约。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
+该行的所有可见值均派生自当前 runtime 窗口中已配对的调用／结果片段。skill 名称来自已记录的 `name` 参数，指令来自持久化的结果内容；该行绝不关联当前 skill 目录来读取描述或提供方元数据。如果分页将调用留在窗口外，结果便没有工具身份，并继续使用通用后备路径，而不是扩展 history 协议约定。现有的 ACP（Agent Client Protocol）`skill-load` 记录经由真实的 Web 持久化与组合路径写入，用于无需密钥的交互和无障碍快照。
 
 ## 考虑过的替代方案
 
 - 保留通用工具行，只添加一个 `skill` 颜色选择器，并将其放在 `ui-conversation` 中。该方案仍会保留多余的输入外层结构和通用展开体，也会让 conversation 包拥有特定领域的视觉规则。
 - 在宿主工具渲染意图联合类型中添加新的 `skill` 值。键控客户端 slot 在调用位于 runtime 窗口内时已经能够识别该工具，因此新的跨边界呈现值只会增加协议和快照表层，却不会支持其他消费方。
-- 导出 conversation 包的私有 `ToolRow` 组件供复用。客户端包刻意对外暴露契约而非跨包组件；导出该组件会使独立功能包耦合到 conversation 的实现细节。
+- 导出 conversation 包的私有 `ToolRow` 组件供复用。客户端包刻意对外暴露约定而非跨包组件；导出该组件会使独立功能包耦合到 conversation 的实现细节。
 
 ## 后果
 
-除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 契约、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
+除了引用 source 的依赖外，`ui-skill` 现在还依赖公开的 conversation toolview 约定、locale 包、原语包和 React。它自行保留了一小份折叠展开行 chrome，因此未来的全局交互变更必须与 Bash 示例和 conversation 行同步更新这个注册方。
 
 即使已安装的 skill 目录发生变化，冷回放仍保持确定性；在用户显式展开指令前，transcript 保持紧凑。仅含结果的 history 页有意使用通用后备路径；让这个边缘情况保持通用呈现，可以保留现有 history 协议，并将该功能限定在客户端呈现层。专用卡片有意显示工具完整封装的输出，而不是只提取 `<skill_instructions>`，从而原样保留模型实际收到的内容，也避免为 skill 结果格式再引入一个解析器。
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
index bc2d1575ee..145c1cf619 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
 2026-08-08-dsh-run-headless-command.md: d1cc0573d1d94bb7b30e98aa685d2b7d89878a99
-2026-08-08-dsh-run-headless-command.zh.md: 7b48dfd708efb197babcfcbeaf4f8a4ca76cde3f
+2026-08-08-dsh-run-headless-command.zh.md: afb18fea6ac46064b6720d3bb68d7bc53a81d3f2
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
index 7b48dfd708..afb18fea6a 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
@@ -26,7 +26,7 @@ dsh run [--profile <name>] [--patch <path>...] <task...>
 
 `run` 动词只负责一次性任务执行。应用文件启动必须选择其他命令名；如果让两个顶层含义由位置参数形态决定，就会重新引入本命令消除的歧义。
 
-运行器面向用户的契约保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 契约。
+运行器面向用户的约定保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 约定。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
index a126f8c0d0..4b85d13e3d 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-17-ts-build-config.md
 2026-06-17-ts-build-config.md: f25731921aaa6da7a4c9760244f73dc0670dc1d3
-2026-06-17-ts-build-config.zh.md: 41791129647b6a5bfeb966e05ee2c5b9132c45ef
+2026-06-17-ts-build-config.zh.md: 80b051cd5fb76672d4c056d1b6321029897225e8
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
index 4179112964..80b051cd5f 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-06-17-ts-build-config.md) | 中文
 
-> 根项目拓扑由一个 solution 根文件统辖两个 aggregate program；见 [solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。Host 生成 Remote 契约后再编译 Client 的当前命令顺序见 [API Remotes 构建 Agent Note](2026-08-08-api-remotes-generated-contract-build.md)。本文确定的 tsc-first 职责保持不变。
+> 根项目拓扑由一个 solution 根文件统辖两个 aggregate program；见 [solution 根文件 Agent Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)。Host 生成 Remote 约定后再编译 Client 的当前命令顺序见 [API Remotes 构建 Agent Note](2026-08-08-api-remotes-generated-contract-build.md)。本文确定的 tsc-first 职责保持不变。
 
 ## 问题
 
@@ -76,7 +76,7 @@ tsx scripts/clean.ts
 
 构建职责更加清晰：
 
-- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个普通模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。`api/remotes` 因生成契约顺序使用一个 solution 和两个互斥的 emitting project，是唯一例外。
+- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个普通模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。`api/remotes` 因生成约定顺序使用一个 solution 和两个互斥的 emitting project，是唯一例外。
 - `build` 命令按 Host 与 Client Project Reference 图执行。每个阶段都由 `tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责发布 runtime bundle。
     - `lib/types/*.d.ts` 是发布用的声明输出；`.d.ts.map` 只作为本地编译产物保留。
     - `lib/types/*.d.ts` 使用显式 `.ts` 相对说明符，TypeScript 的 NodeNext/Node16 解析器会将其映射到同级的 `.d.ts` 文件。
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 6f51f73b00..483a429f97 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
 2026-06-20-core-data-structures-catalog.md: 9a3f80df592f28adc365d5e64cc15516d92b47b5
-2026-06-20-core-data-structures-catalog.zh.md: 895f639446bc6c4e0fecbf1085197ba8b1810282
+2026-06-20-core-data-structures-catalog.zh.md: a1184cb25823c10949713271434628c3650678dd
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 895f639446..a1184cb258 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -31,7 +31,7 @@ Status: implemented
 
 ### `ts type-equiv` 机制——既逐字又防漂移
 
-持久性要求很具体：文档展示当前类型声明与原始 JSDoc 的**逐字**内容（让读者看到真实形状和源码契约，而非复述），**并且**以机械方式保证其与源码匹配。仓库已经会编译 ` ```ts ` 围栏块（`doc-typecheck`），但真正接受类型检查的块需要导入噪音，而且只能证明*可赋值性*——字段改名或 JSDoc 变化仍可能通过。因此：
+持久性要求很具体：文档展示当前类型声明与原始 JSDoc 的**逐字**内容（让读者看到真实形状和源码约定，而非复述），**并且**以机械方式保证其与源码匹配。仓库已经会编译 ` ```ts ` 围栏块（`doc-typecheck`），但真正接受类型检查的块需要导入噪音，而且只能证明*可赋值性*——字段改名或 JSDoc 变化仍可能通过。因此：
 
 - 完整的类型声明及其 JSDoc 会逐字粘贴到专用的 ` ```ts type-equiv ` 围栏中。简洁的 ` ```ts public-api ` 围栏承载类的源码等价环境声明投影，用于实现体不应进入目录的类。`doc-typecheck` 会识别并跳过这两种围栏（裸声明无法独立编译），并且**将它们排除在 opt-out 比例之外**——它们是单独受检的类别，而不是未经检查的草图。
 - 新增的 `scripts/verify-type-equiv.ts` 通过 TypeScript 解析器提取每个块，并断言其声明结构和每条 JSDoc 注释都与所声明的符号匹配，只忽略格式空白和非 JSDoc 注释。普通块保留完整声明。`public-api` 投影保留类的公共字段、构造函数、访问器和方法及其原始 JSDoc，同时移除实现体以及私有或受保护成员。之所以选择它而非编译式 `_Check` 断言，是因为目录所保留的是源码名称与文档一致性，而不是可赋值性。
@@ -45,7 +45,7 @@ Status: implemented
 ## 曾考虑的替代方案
 
 - **平铺罗列所有跨包词汇**：`BashExecRequest` 测试案例否决了它。如果 seam 词汇算「核心」，目录对谁都没帮助；分层的主干与 seam 结构胜出。
-- **用编译式 `_Check` 可赋值性断言**代替源码匹配：否决。可赋值性不会保留名称或 JSDoc；同类型字段改名或契约注释变化仍会通过。
+- **用编译式 `_Check` 可赋值性断言**代替源码匹配：否决。可赋值性不会保留名称或 JSDoc；同类型字段改名或约定注释变化仍会通过。
 - **来源信息作为行文中的指令注释**：否决，改用集中 manifest；其强制的 1:1 对应确保一个块永远不会被静默漏检，一条条目也永远不会腐烂。
 
 ## 验证教训
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 9e69041e2e..ce56c983fd 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
 2026-07-02-bilingual-docs-and-pairing-gate.md: 8e9d0ab8653528517346b198c97814d8d8979440
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: e8f18ebb0d1620830116f6d5d9ffef29664a578e
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: dbcf453d49237029d28cfc6f6651ffd14752a4f3
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index e8f18ebb0d..dbcf453d49 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 
 ## 验证
 
-验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。
+验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
index dec5dcfafd..ba3b6a970d 100644
--- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md
 2026-07-04-doc-tiers-and-budgets.md: e7b3421d09a1ae5ab9a9373e8040832c1b0d4b97
-2026-07-04-doc-tiers-and-budgets.zh.md: 157ad13f521d2a497180e25b70e3537a4afbc099
+2026-07-04-doc-tiers-and-budgets.zh.md: 3bc04ae73a4d8c9c005e154a236772fc1845389e
diff --git a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
index 157ad13f52..3bc04ae73a 100644
--- a/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
+++ b/.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.zh.md
@@ -14,13 +14,13 @@ Status: implemented
 - **每项事实只归属一处的层级分类。**文档标准为每种 Markdown 层级分配单一职责，禁止在事实归属层级之外重复陈述，并包含编写或评审任何文档时使用的赘余检查清单。
 - **范围窄且严格的预算门禁。**[scripts/verify-doc-budgets.ts](../../../../scripts/verify-doc-budgets.ts) 接入 `doc-sync`：[scripts/doc-budgets.manifest.json](../../../../scripts/doc-budgets.manifest.json) 列出的每份文档都必须低于其词数上限（采用 `wc -w` 语义，统计整个文件）；预算内文件缺失也会使门禁失败，使重命名无法悄然遗落其预算。范围刻意只涵盖容易膨胀的常设文档——根目录和子树中的 `AGENTS.md` 文件、`architecture.md`、`packages/README.md`，以及它们将内容移入的常设策略文档（`docs/testing.md`、`docs/defensive-patterns.md`）。参考文档、Agent Note 和包 README 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。
 - **上限是只进不退的执行红线。** 达到或低于目标的文档在上限逐步下调时保留至少 5% 的余量；高于目标的文档则维持冻结的上限，在达到目标之前不得增长（根 `AGENTS.md` ≤ 1,600 词；`architecture.md` ≤ 1,800；子树 `AGENTS.md` ≤ 600，但 `packages/AGENTS.md` ≤ 650、`docs/AGENTS.md` ≤ 1,250；`packages/README.md` ≤ 600）。门禁变红时，迁移或压缩内容；只有在 PR（Pull Request）描述中给出明确理由时才提高上限。
-- **精简的工作流 skill（技能），契约归文档。**[.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) 承载文档放置、审计和门禁失败处理工作流，并以文档标准为真源，与 [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 和 i18n 契约之间的分工相同。
+- **精简的工作流 skill（技能），约定归文档。**[.agents/skills/dsh-doc-standards](../../../skills/dsh-doc-standards/SKILL.md) 承载文档放置、审计和门禁失败处理工作流，并以文档标准为真源，与 [dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md) 和 i18n 约定之间的分工相同。
 
 ## 曾考虑的替代方案
 
 - **仅靠 skill 和评审纪律，不设门禁**：否决。上述膨胀正是在现行规则和评审注意力已经存在的情况下发生的；一条没有自动化保障的行文规则在此处已被证明无法维持，而本仓库自身的[质量门禁立场](2026-06-11-quality-gates.md)认为值得保持的不变式就值得编码。
 - **对所有文档层级全面设限**：否决。一刀切的上限恰好惩罚了那些正当的长文档（如功能矩阵或类型目录，每一行都是事实），并产生逐文件的例外变更，训练贡献者机械地批准提限。
-- **将标准放在 skill 内部**：否决。契约归文档，工作流归 skill；如果标准被塞进 SKILL.md，那些不调用该 skill 而直接编辑文档的 agent（智能体）就看不到它，而 `docs/AGENTS.md` 已经作为子树指令被任何在 `docs/` 下工作的人加载。
+- **将标准放在 skill 内部**：否决。约定归文档，工作流归 skill；如果标准被塞进 SKILL.md，那些不调用该 skill 而直接编辑文档的 agent（智能体）就看不到它，而 `docs/AGENTS.md` 已经作为子树指令被任何在 `docs/` 下工作的人加载。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
index 040772a879..3b2ed0f39d 100644
--- a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md
 2026-07-05-uniform-agent-note-format.md: 06082251c1b96c90ed470d84224662e00e29791b
-2026-07-05-uniform-agent-note-format.zh.md: 8f874f26c43a88ec3d2f1185c7b4d6f2f39ba1bb
+2026-07-05-uniform-agent-note-format.zh.md: a13c436a3fa157a0bfe551a7ed0594d052a4de90
diff --git a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
index 8f874f26c4..a13c436a3f 100644
--- a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
@@ -6,24 +6,24 @@ Status: implemented
 
 ## 问题
 
-Agent Note 的路径编码了生命周期和类别，但文件内容仍混杂着不同标题、状态格式、ADR 与提案模板，以及已实现记录中的提案阶段章节。作者会复制随手找到的相邻文件，而生命周期迁移可能跳过必要的改写，因为没有门禁强制执行文件内契约。
+Agent Note 的路径编码了生命周期和类别，但文件内容仍混杂着不同标题、状态格式、ADR 与提案模板，以及已实现记录中的提案阶段章节。作者会复制随手找到的相邻文件，而生命周期迁移可能跳过必要的改写，因为没有门禁强制执行文件内约定。
 
 ## 决策
 
-[README.md § 文件格式](../../README.md#the-file-format)是文件内契约——头部块（`# Agent Note: <title>`，加上无日期且与文件夹一致的 `Status:` 枚举，其中只有拒绝原因可作为额外内容）、各生命周期的正文骨架（所有文件均以 `Problem` 开篇；`proposed/` 使用 `Proposal`/`Acceptance criteria`/`Risks`；`implemented/` 使用现在时的 `Decision`/`Consequences`，并禁止提案阶段标题；`rejected/` 冻结提案结构）、强制的 `Alternatives considered` 章节，以及规范章节词汇；定制技术章节可在这些规范章节之间保持自由形式。`pnpm run verify-agent-note-format`（[scripts/verify-agent-note-format.ts](../../../../scripts/verify-agent-note-format.ts)）作为 `doc-sync` 的一部分强制执行每项机械规则，因此跳过改写的生命周期迁移现在会使 CI 失败，而不再依赖评审者记忆。
+[README.md § 文件格式](../../README.md#the-file-format)是文件内约定——头部块（`# Agent Note: <title>`，加上无日期且与文件夹一致的 `Status:` 枚举，其中只有拒绝原因可作为额外内容）、各生命周期的正文骨架（所有文件均以 `Problem` 开篇；`proposed/` 使用 `Proposal`/`Acceptance criteria`/`Risks`；`implemented/` 使用现在时的 `Decision`/`Consequences`，并禁止提案阶段标题；`rejected/` 冻结提案结构）、强制的 `Alternatives considered` 章节，以及规范章节词汇；定制技术章节可在这些规范章节之间保持自由形式。`pnpm run verify-agent-note-format`（[scripts/verify-agent-note-format.ts](../../../../scripts/verify-agent-note-format.ts)）作为 `doc-sync` 的一部分强制执行每项机械规则，因此跳过改写的生命周期迁移现在会使 CI 失败，而不再依赖评审者记忆。
 
 定义该格式的同一变更规范化了整个语料库——遵循预发布立场：不设过渡期，不容忍双格式。唯一适用既有内容豁免的是内容，而非格式：替代方案只能记录、不能杜撰，因此若某份格式制定前的 Agent Note 无法从记录中还原替代方案，就会带有内容完全匹配 `agent-note-format: alternatives-not-recorded` 的注释；门禁只对日期早于本文的文件接受该注释。
 
 ## 曾考虑的替代方案
 
-- **完整的刚性模板**（每个生命周期使用固定章节顺序，重构每份 Agent Note 以适配）：否决。大型设计 Agent Note 包含八到十五个定制技术章节（包拓扑、协议契约、schema），它们是承载设计的内容，而非漂移；刚性顺序会迫使我们现在进行破坏性改写，并永远与模板较劲。
+- **完整的刚性模板**（每个生命周期使用固定章节顺序，重构每份 Agent Note 以适配）：否决。大型设计 Agent Note 包含八到十五个定制技术章节（包拓扑、协议约定、schema），它们是承载设计的内容，而非漂移；刚性顺序会迫使我们现在进行破坏性改写，并永远与模板较劲。
 - **仅规范化头部**（H1 和 Status，正文不动）：否决。债务标记指出的是*正文*的体裁分裂，让 `Context`/`Decision` 与 `Problem`/`Proposal` 无限期并存什么也解决不了。
 - **不设 Status 行**（文件夹已经表示状态；格式制定前最新的三份 Agent Note 及其中一份的中文对应文件省略了该行）：否决，保留文件的自描述性。通过门禁校验该行与文件夹一致，消除了原本促使我们删除它的漂移风险。
 - **带日期的 Status**（`Status: implemented (accepted YYYY-MM-DD)`）：否决。接受日期属于叙述性历史，写作规则将其排除在文档之外；文件名承载首次提出日期，git 承载其余信息；门禁能检查日期格式，但永远无法检查其真实性。
 - **裸 `# <title>` H1**：否决。文件脱离目录树单独阅读时，`Agent Note: ` 前缀能自描述其体裁，而格式门禁可防止它漂移。
 - **以 `## What we give up` 作为已实现记录的结尾**（README 对 Agent Note 所记录内容的原有表述）：否决。它只点出成本，而诚实的后果章节也会记录取舍换来了什么。
-- **只有约定没有门禁**（写下契约，靠评审强制执行）：否决。slop checklist 已经通过约定禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠约定在此处能达到什么效果。
-- **独立的 `FORMAT.md` 契约文件**：否决。由一个入口同时承载布局、分类和格式，比维护两个契约文件更易发现和维护。
+- **只有约定没有门禁**（写下约定，靠评审强制执行）：否决。slop checklist 已经通过约定禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠约定在此处能达到什么效果。
+- **独立的 `FORMAT.md` 约定文件**：否决。由一个入口同时承载布局、分类和格式，比维护两个约定文件更易发现和维护。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml
index 8c2e77710e..d9660ac47d 100644
--- a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
 2026-07-06-export-surface-jsdoc-gate.md: 821f68ebe60eba44cade223b3bc8286e09740956
-2026-07-06-export-surface-jsdoc-gate.zh.md: 5f5f7b70a486b0aa5e8e7fd07810dfbcfb719a50
+2026-07-06-export-surface-jsdoc-gate.zh.md: ec5bf67ccbfe9fcc1996aa47177c2d9b1145cd67
diff --git a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md
index 5f5f7b70a4..ec5bf67ccb 100644
--- a/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-06-export-surface-jsdoc-gate.zh.md
@@ -12,14 +12,14 @@ Status: implemented
 
 新增门禁 `scripts/verify-export-jsdoc.ts`（`pnpm run verify-export-jsdoc`，接入 `doc-sync`（文档同步门禁），与 `verify-cordis-catalog` 并列），遍历每个 `packages/<group>/<pkg>/src/` 目录树下的所有模块级导出名称。解析与检查辅助函数从 `gen-cordis-catalog.ts` 移入共享的 `scripts/jsdoc.ts`，使得「已文档化」在两类接口上含义一致：描述性文字在第一个块标签处截止、每个可检查参数需要非空 `@param`、非 void 且有显式标注的返回值需要非空 `@returns`、过时的 `@param` 报错，违规项汇总为一份报告。
 
-按声明类型划分的契约：
+按声明类型划分的约定：
 
 - 每个导出名称都需要带有非空描述文字的 JSDoc。
-- 函数类导出（函数声明；初始化器为函数或带有内联可调用标注的 const；非标识符的函数默认导出）遵循完整的函数契约，分类前会剥离包装表达式（括号、`as`/`satisfies` 类型断言、非空断言）。如果 const 声明器标注了一个具名类型（`export const f: Handler = …`），签名契约推迟到该类型自身的声明处，`@returns` 保持可选；内联的 `(x: T) => U` 标注或单调用签名字面量本身就是对外签名，适用完整契约；而混合了调用/构造签名与其他成员的字面量则直接拒绝（没有单一签名可供标签对照——请提取具名类型）。
-- 导出类需要类级别的描述文字；公开方法（包括静态方法——可通过导出名称访问）遵循函数契约；公开属性和访问器需要描述文字（get/set 对由 getter 覆盖）。重载实现体免检——签名承载文档。
-- 导出接口、类型别名和枚举需要声明级别的描述文字；成员级别的强制有意推迟（承载关键成员契约的 seam 服务类已在 Cordis 门禁之下）。
+- 函数类导出（函数声明；初始化器为函数或带有内联可调用标注的 const；非标识符的函数默认导出）遵循完整的函数约定，分类前会剥离包装表达式（括号、`as`/`satisfies` 类型断言、非空断言）。如果 const 声明器标注了一个具名类型（`export const f: Handler = …`），签名约定推迟到该类型自身的声明处，`@returns` 保持可选；内联的 `(x: T) => U` 标注或单调用签名字面量本身就是对外签名，适用完整约定；而混合了调用/构造签名与其他成员的字面量则直接拒绝（没有单一签名可供标签对照——请提取具名类型）。
+- 导出类需要类级别的描述文字；公开方法（包括静态方法——可通过导出名称访问）遵循函数约定；公开属性和访问器需要描述文字（get/set 对由 getter 覆盖）。重载实现体免检——签名承载文档。
+- 导出接口、类型别名和枚举需要声明级别的描述文字；成员级别的强制有意推迟（承载关键成员约定的 seam 服务类已在 Cordis 门禁之下）。
 - 导出命名空间递归检查（在 ambient `declare` 命名空间内，每个成员隐式导出）；命名空间本身仅在不与同名的已文档化声明合并时才需要描述文字（Config-namespace 惯用法只需文档化插件一次）。
-- `declare module`/`declare global` 体和 `export … from` 重导出语句被跳过：augmentation 不是包的导出，重导出的定义在其定义处检查。`export import X = N.member` 别名需要文档化自身——其目标可能是遍历不会访问的非导出命名空间成员——且门禁仅支持纯描述文字的目标类型：可调用、类或命名空间目标携带别名描述文字无法承载的签名/成员契约，门禁会拒绝并要求直接导出该声明。
+- `declare module`/`declare global` 体和 `export … from` 重导出语句被跳过：augmentation 不是包的导出，重导出的定义在其定义处检查。`export import X = N.member` 别名需要文档化自身——其目标可能是遍历不会访问的非导出命名空间成员——且门禁仅支持纯描述文字的目标类型：可调用、类或命名空间目标携带别名描述文字无法承载的签名/成员约定，门禁会拒绝并要求直接导出该声明。
 - 其余情况一律默认拒绝：`export =` 直接拒绝；即使参数使用绑定模式，只要基类未为其命名，仍需 `@param`；dispatch 不识别的导出语句类型本身就是违规——没有任何导出形式能因遗漏而免检。
 
 三类豁免避免门禁要求样板代码，精神与 Cordis 门禁的 `this`/`next` 豁免一致（为已豁免的名称编写文档是允许的；只有缺失才不被检查）：
@@ -32,9 +32,9 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-- **eslint-plugin-jsdoc**（`require-jsdoc`/`require-param`/`require-returns`）：覆盖了机械核心，但无法表达本仓库的契约。继承成员豁免需要跨包的类型解析，协议槽位和命名空间合并惯用法是 Cordis 特有的，而完整性语义（标签前描述文字、过时标签报错、汇总报告）已在 `scripts/jsdoc.ts` 中与 catalog 生成器共享。两套微妙不同的「已文档化」定义，正是本仓库「单一归属」规则所要防止的失败模式。
+- **eslint-plugin-jsdoc**（`require-jsdoc`/`require-param`/`require-returns`）：覆盖了机械核心，但无法表达本仓库的约定。继承成员豁免需要跨包的类型解析，协议槽位和命名空间合并惯用法是 Cordis 特有的，而完整性语义（标签前描述文字、过时标签报错、汇总报告）已在 `scripts/jsdoc.ts` 中与 catalog 生成器共享。两套微妙不同的「已文档化」定义，正是本仓库「单一归属」规则所要防止的失败模式。
 - **扩展 `gen-cordis-catalog.ts`**：catalog 生成器渲染一个精选表面并守卫其新鲜度；仓库级遍历没有 catalog 可渲染。共享辅助函数、保持遍历独立，使每个门禁的职责清晰可读。
-- **强制接口/类型别名的成员文档**：推迟。这会使检查表面成倍增长，而检查对象大多只是含义直观的字段；承载关键成员契约的 seam 服务类已有门禁。如果评审中出现成员文档漂移再重新考虑。
+- **强制接口/类型别名的成员文档**：推迟。这会使检查表面成倍增长，而检查对象大多只是含义直观的字段；承载关键成员约定的 seam 服务类已有门禁。如果评审中出现成员文档漂移再重新考虑。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
index ddca590dea..2a4cdaedae 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-06-node-engine-floor.md
 2026-07-06-node-engine-floor.md: ad21fbfe034cbf4bb7b75aaac4113f3139a1832d
-2026-07-06-node-engine-floor.zh.md: 0d1c31ed74565f9b20116cd0e666246baad9bf79
+2026-07-06-node-engine-floor.zh.md: e2ef7a99a8c3045b00f4980953f0adbe4a788cfb
diff --git a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
index 0d1c31ed74..e2ef7a99a8 100644
--- a/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
+++ b/.agents/notes/implemented/process/2026-07-06-node-engine-floor.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-根 `engines.node` 范围中的 Node 22 分支是对安装后工作区的契约，而不仅仅是 harness 源码直接调用的运行时 API 的契约。它不得低于工作区在该分支上安装的依赖包所声明的 `engines.node`；否则 `pnpm install --engine-strict` 会在一个已宣传的 LTS 版本上失败，而非严格模式下的安装结果则会在依赖所支持的运行时范围之外运行。
+根 `engines.node` 范围中的 Node 22 分支是对安装后工作区的约定，而不仅仅是 harness 源码直接调用的运行时 API 的约定。它不得低于工作区在该分支上安装的依赖包所声明的 `engines.node`；否则 `pnpm install --engine-strict` 会在一个已宣传的 LTS 版本上失败，而非严格模式下的安装结果则会在依赖所支持的运行时范围之外运行。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
index 2bfcddbf3b..091a912f94 100644
--- a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
 2026-07-12-package-model-experience-contract.md: 92a8e5a1a81d00dae085e4af89456896373058e6
-2026-07-12-package-model-experience-contract.zh.md: 34dd909adc6a3a5f4c9113df675d31012b836370
+2026-07-12-package-model-experience-contract.zh.md: 9fb6e36e75dcca43fd3ed450c364c57ae7fb7ca4
diff --git a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
index 34dd909adc..9fb6e36e75 100644
--- a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 包的模型体验契约
+# Agent Note: 包的模型体验约定
 
 Status: implemented
 
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-每个具有面向模型或邻近模型契约的 workspace 包 README 都以规范的[模型体验章节](../../../../docs/cookbook/adding-a-package.md#4-write-the-package-readme)收尾，位置紧邻 `## Known Limitations and Deferred Work` 之前；位于“无已知限制”允许列表中的包则以模型体验章节本身结尾。经审计确认与模型无关的通用包通过 `NO_MODEL_EXPERIENCE_SECTION` 省略该章节。
+每个具有面向模型或邻近模型约定的 workspace 包 README 都以规范的[模型体验章节](../../../../docs/cookbook/adding-a-package.md#4-write-the-package-readme)收尾，位置紧邻 `## Known Limitations and Deferred Work` 之前；位于“无已知限制”允许列表中的包则以模型体验章节本身结尾。经审计确认与模型无关的通用包通过 `NO_MODEL_EXPERIENCE_SECTION` 省略该章节。
 
 具有直接、条件式、有上限、生命周期、多表面或辅助模型效应的包，为每个上下文表面使用一个 H3。每个表面包含三个有序 H4 字段——`What the model sees`、`Token effect` 和 `KV Cache effect`——每个字段都以一个正文段落开头。缓存字段区分仅追加增长、稳定重复前缀、替换先前 token，以及独立模型请求；它点明由包拥有、且能在新内容追加前改变请求的每项配置、作用域、生命周期、压缩或路由变化。“Does not invalidate”表示该包保留一个已经可复用的前缀，并非承诺提供方一定能命中缓存或将其保留特定时长。由包拥有的稳定文本按原文精确引用：系统提示词正文和其他长字面量在引入它们的字段下使用带标题的 H5 加 `markdown` 围栏，通常位于 `What the model sees`；短字面量则以内联形式保留，并点名插值占位符。工具 schema 表面链接生成的[工具目录](../../../../docs/tool-catalog.md)中带锚点的章节，并且只陈述组合或配置增量；仅运行时定义解释目录为何省略它们。依赖数据和由提供方拥有的文本采用摘要。agent 范围的可见性须显式说明；当范围可隐藏提示词与 schema 中的一者而不影响另一者时，两种表面保持分离。
 
@@ -21,13 +21,13 @@ Status: implemented
 ## 曾考虑的替代方案
 
 - **只记录注册提示词或工具的包**：否决。后端、策略插件、适配器、持久化、作用域和压缩都会改变 token 的内容或生命周期，却不拥有面向模型的 schema。
-- **从源码生成一份集中式上下文成本目录**：否决。AST 能找到注册点，但无法推断语义条件，如历史保留、输出截断、父子可见性或辅助模型边界。包 README 是实现本地的契约；集中副本会增加又一个漂移面。
-- **要求给出精确 token 数**：否决。精确数量取决于所选模型的 tokenizer、适配器序列化方式、配置和运行时数据。稳定的契约是增长形状：每请求固定、每调用条件性、保留、替换、有上限或零直接影响。
+- **从源码生成一份集中式上下文成本目录**：否决。AST 能找到注册点，但无法推断语义条件，如历史保留、输出截断、父子可见性或辅助模型边界。包 README 是实现本地的约定；集中副本会增加又一个漂移面。
+- **要求给出精确 token 数**：否决。精确数量取决于所选模型的 tokenizer、适配器序列化方式、配置和运行时数据。稳定的约定是增长形状：每请求固定、每调用条件性、保留、替换、有上限或零直接影响。
 - **使用表格**：否决。精确源码文本和条件式结果形状会使单元格密集而难以扫读。重复的小节在保留相同字段的同时，为每个上下文表面提供易读的纵向空间。
 - **允许所有零影响包省略该章节**：否决。无约束的缺失在「经审计的零影响」和「忘记写文档」之间有歧义。省略仅限于在验证器中以理由命名的模型无关通用包；模型相邻的零影响包保留一句显式说明。
 - **要求经审计的零效应包或简单间接包使用完整结构化格式**：否决。它会围绕一个事实重复标签。受门禁约束的句子加 cache 字段既保留显式覆盖，又没有多余仪式。
-- **只有约定而无门禁**：否决。仓库级契约必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
+- **只有约定而无门禁**：否决。仓库级约定必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
 
 ## 后果
 
-评审者可以从任何面向模型或邻近模型的包开始，看到它对对话模型、子模型和辅助调用的贡献，无需重建完整插件图。token 预算工作可以区分重复请求开销和依赖数据的历史，而 cache 敏感工作可以识别仅追加路径，以及最早由包引起请求前缀变化的位置。agent 范围变更有明确的文档检查点。每当模型可见行为发生变化时，包作者都要维护一个或多个紧凑的上下文表面块，或一种已分类的短格式；经审计的通用包不携带无关的模型样板。结构化字段不承诺由提供方给出的精确 token 数或 cache 命中；测量仍取决于具体模型、提供方和工作负载，而所记录的增长、可见性和前缀稳定性契约保持稳定。
+评审者可以从任何面向模型或邻近模型的包开始，看到它对对话模型、子模型和辅助调用的贡献，无需重建完整插件图。token 预算工作可以区分重复请求开销和依赖数据的历史，而 cache 敏感工作可以识别仅追加路径，以及最早由包引起请求前缀变化的位置。agent 范围变更有明确的文档检查点。每当模型可见行为发生变化时，包作者都要维护一个或多个紧凑的上下文表面块，或一种已分类的短格式；经审计的通用包不携带无关的模型样板。结构化字段不承诺由提供方给出的精确 token 数或 cache 命中；测量仍取决于具体模型、提供方和工作负载，而所记录的增长、可见性和前缀稳定性约定保持稳定。
diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml
index 07e0a89d0f..36f6181c46 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
 2026-07-13-documentation-site-projection.md: d9af915754fa6a1df51a27d18d412597472aaa73
-2026-07-13-documentation-site-projection.zh.md: 5b6de4b3425b6d20335a0f8055468ced414d4034
+2026-07-13-documentation-site-projection.zh.md: 7d7b4752b8f27d55aae8426a7dc001ce4340e661
diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
index 5b6de4b342..7d7b4752b8 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md
@@ -40,7 +40,7 @@ Mermaid 渲染权威图表。网站工作区显式声明 `vitepress-plugin-merma
 
 **只在部署工作流中构建。** 部署作业可以在合并后发现渲染故障。把生产构建纳入 `doc-sync`，则无论是否存在公开部署，同一个故障都能在本地和常规 CI 中暴露。
 
-**硬编码公开项目路径。** 固定的 `/deepseek-harness/` base 适用于公开项目 URL，却不适用于私有 Pages 站点分配的唯一源站，也不适用于未来的自定义域名。使用 Pages 元数据可让这些目标位置共享同一份构建契约。
+**硬编码公开项目路径。** 固定的 `/deepseek-harness/` base 适用于公开项目 URL，却不适用于私有 Pages 站点分配的唯一源站，也不适用于未来的自定义域名。使用 Pages 元数据可让这些目标位置共享同一份构建约定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml
index 6c243f94db..b6d2cad8df 100644
--- a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md
 2026-07-14-typescript-program-backed-semantic-gates.md: 91639d53b660c68ae52c7ddcef6b3f594e82273e
-2026-07-14-typescript-program-backed-semantic-gates.zh.md: 65e19ba2bd34c2411a2e5ca64dfc85f9bf18cfb3
+2026-07-14-typescript-program-backed-semantic-gates.zh.md: 2ccb6a95185e1f666359b8b864f6ad655070a47f
diff --git a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md
index 65e19ba2bd..2ccb6a9518 100644
--- a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md
@@ -40,7 +40,7 @@ Context 与 AgentEventDispatch 调用只贡献由字符串字面量构成的有
 
 恰好一个匹配项会生成解析函数。存在多个匹配项时，含义不明确，生成器会失败。没有匹配项时，事件必须标记 `@dshScopeScan unsupported`；该标记只用于路由键有意留在事件参数之外的情况，例如按所属 agent（智能体）路由的会话事件和按父 agent 路由的 subagent 生命周期事件。此标记只表示扫描不受支持，不编码事件名、参数下标、属性路径或替代类型。
 
-提交到仓库的 [`scoped-events.generated.ts`](../../../../packages/core/scope/src/scoped-events.generated.ts) 是位于 scoped dispatch 所属包中的纯运行时映射，不导入任何事件声明方包。语义完整性由生成器自身保证：根 Program 枚举所有 scoped `Events` 声明与真实 `scopeTarget` 契约，通过 checker 解析唯一的 payload 路径，并在渲染 `unknown[]` 运行时边界前拒绝缺失、陈旧或含义不明确的条目。
+提交到仓库的 [`scoped-events.generated.ts`](../../../../packages/core/scope/src/scoped-events.generated.ts) 是位于 scoped dispatch 所属包中的纯运行时映射，不导入任何事件声明方包。语义完整性由生成器自身保证：根 Program 枚举所有 scoped `Events` 声明与真实 `scopeTarget` 约定，通过 checker 解析唯一的 payload 路径，并在渲染 `unknown[]` 运行时边界前拒绝缺失、陈旧或含义不明确的条目。
 
 `dsh-scope/invariant` companion 消费这份映射，不再维护手写事件表。Program 分析发生在仓库门禁内，而不是依赖生成的类型导入，因此 `dsh-scope` 和 `dsh-invariants` 都不需要依赖所有事件声明方。
 
@@ -59,7 +59,7 @@ Context 与 AgentEventDispatch 调用只贡献由字符串字面量构成的有
 ## 后果
 
 - 事件关系生成依据语义接收者身份和封闭事件值，不再依赖局部命名约定；
-- 带作用域的事件成员关系、主体提取和运行时不变式覆盖来自事件声明与真实 dispatch 契约，不再来自手写表；
-- 修改事件名、参数位置、主体属性或路由键类型时，会在其所属契约处触发生成失败；
+- 带作用域的事件成员关系、主体提取和运行时不变式覆盖来自事件声明与真实 dispatch 约定，不再来自手写表；
+- 修改事件名、参数位置、主体属性或路由键类型时，会在其所属约定处触发生成失败；
 - 构建扁平化 Program 比解析孤立文件消耗更多启动时间和内存，语义门禁也依赖有效的根项目图；
 - 生成的 TypeScript 仍属于提交到仓库的源码：事件声明方或 dispatch 形态发生变化后，必须重新生成该文件和受影响的文档。
diff --git a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml
index 8297b3675e..ce16a025cc 100644
--- a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.md
 2026-07-19-remove-generated-agent-note-index.md: ee85ec0757d5924f5784c43a50003eb96e0a9531
-2026-07-19-remove-generated-agent-note-index.zh.md: 7ace1c4f03d5ff3d1137fe611a5ec0ec2ae21b2f
+2026-07-19-remove-generated-agent-note-index.zh.md: 6e1967fbde0c6ac59bbc3a184dad68c989efadbc
diff --git a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.zh.md b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.zh.md
index 7ace1c4f03..6e1967fbde 100644
--- a/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.zh.md
+++ b/.agents/notes/implemented/process/2026-07-19-remove-generated-agent-note-index.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-按生命周期／类别组织的文件系统目录树就是 Agent Note 清单。[README.md](../../README.md) 继续作为人工维护的入口和契约，普通的目录树浏览与仓库搜索负责内容发现。
+按生命周期／类别组织的文件系统目录树就是 Agent Note 清单。[README.md](../../README.md) 继续作为人工维护的入口和约定，普通的目录树浏览与仓库搜索负责内容发现。
 
 `scripts/agent-note-tree.ts` 持有封闭的生命周期／类别集合与结构遍历器。`verify-agent-note-classification` 校验该目录树，并拒绝旧目录和根目录中的 `INDEX.md`，但不会渲染集中式清单或检查其新鲜度。
 
diff --git a/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.i18n.yaml b/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.i18n.yaml
index fa3294857a..38c49d2a4f 100644
--- a/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.md
 2026-07-19-require-agent-notes-for-non-trivial-changes.md: 162ae61affb4c1b0ad526fa0da41f84ebbb02089
-2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md: 1578312ba43bfc79fe50841aaf651da6f0771fb9
+2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md: f1bf434f78bf10f020089d2e1990874f72a1c082
diff --git a/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md b/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md
index 1578312ba4..f1bf434f78 100644
--- a/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md
+++ b/.agents/notes/implemented/process/2026-07-19-require-agent-notes-for-non-trivial-changes.zh.md
@@ -10,13 +10,13 @@ Status: implemented
 
 ## 决策
 
-每项实质性变更都在同一个 PR（Pull Request）中新增或更新至少一份 Agent Note。实质性变更包括行为、架构、跨文件或跨包契约、流程或工具、测试策略、磁盘格式、协议格式（wire format）或配置格式，以及维护者可能合理重审的其他决策。
+每项实质性变更都在同一个 PR（Pull Request）中新增或更新至少一份 Agent Note。实质性变更包括行为、架构、跨文件或跨包约定、流程或工具、测试策略、磁盘格式、协议格式（wire format）或配置格式，以及维护者可能合理重审的其他决策。
 
-更新已经持有该决策的 Agent Note 即满足规则；仅当没有 Agent Note 持有该决策时才新增记录。完全机械或局部、且不改变行为、契约、结构、流程或决策依据的编辑可豁免。[Agent Notes README](../../README.md#when-to-write-one) 持有这条边界，根目录 `AGENTS.md` 则携带常驻指令。
+更新已经持有该决策的 Agent Note 即满足规则；仅当没有 Agent Note 持有该决策时才新增记录。完全机械或局部、且不改变行为、约定、结构、流程或决策依据的编辑可豁免。[Agent Notes README](../../README.md#when-to-write-one) 持有这条边界，根目录 `AGENTS.md` 则携带常驻指令。
 
-只有在当前持有该决策的记录保存了所有独有的决策依据、备选方案、影响、验证契约和明确指出的覆盖缺口后，才可将被完全取代的 implemented Agent Note 合并到该记录中并删除。同一变更还要修复入站链接，并删除中文对侧文件和伴随记录。仅部分被取代时，两个记录仍需互相链接并保持与现状一致；合并既不将旧决策改写成与其相反的决策，也不让 git 历史成为决策依据的唯一副本。
+只有在当前持有该决策的记录保存了所有独有的决策依据、备选方案、影响、验证约定和明确指出的覆盖缺口后，才可将被完全取代的 implemented Agent Note 合并到该记录中并删除。同一变更还要修复入站链接，并删除中文对侧文件和伴随记录。仅部分被取代时，两个记录仍需互相链接并保持与现状一致；合并既不将旧决策改写成与其相反的决策，也不让 git 历史成为决策依据的唯一副本。
 
-后续决策完全移除较早的功能时，只有该功能已从生产代码、配置、schema、持久化格式或协议格式、迁移和兼容行为中消失，当前文档不再将其描述为可用，且没有测试把它作为受支持行为来执行，移除记录才会成为当前持有记录。移除决策的依据和验证该功能已不存在的测试可以保留。它必须保留该功能的最初动机、为什么该动机已不足以证明继续保留该功能、完全移除之外的备选方案、放弃的能力、重新引入的条件，以及证明已彻底移除的验证。只描述已删除行为的实现清单和测试已经过时，不属于当前验证契约。仅移除一种传输、默认值、实现或展示仍属于部分取代。
+后续决策完全移除较早的功能时，只有该功能已从生产代码、配置、schema、持久化格式或协议格式、迁移和兼容行为中消失，当前文档不再将其描述为可用，且没有测试把它作为受支持行为来执行，移除记录才会成为当前持有记录。移除决策的依据和验证该功能已不存在的测试可以保留。它必须保留该功能的最初动机、为什么该动机已不足以证明继续保留该功能、完全移除之外的备选方案、放弃的能力、重新引入的条件，以及证明已彻底移除的验证。只描述已删除行为的实现清单和测试已经过时，不属于当前验证约定。仅移除一种传输、默认值、实现或展示仍属于部分取代。
 
 评审负责执行这条语义边界。自动化门禁不尝试把差异分类为平凡或实质性变更，因此这项政策不会增加门禁阶段或运行时间。
 
@@ -26,7 +26,7 @@ Status: implemented
 
 **每项变更都必须新增 Agent Note。** 当现有 Agent Note 已经持有该决策时，这会产生重复记录，也会让纯机械编辑承担空洞的流程负担。
 
-**永久保留每份被完全取代的 Agent Note。** 只要旧决策仍有部分适用，就需要保留互相链接的记录；但完全失效的 implemented Agent Note 与记录当前状态的契约相矛盾，并重复保存本可由一个记录持有的决策依据。
+**永久保留每份被完全取代的 Agent Note。** 只要旧决策仍有部分适用，就需要保留互相链接的记录；但完全失效的 implemented Agent Note 与记录当前状态的约定相矛盾，并重复保存本可由一个记录持有的决策依据。
 
 **新增 `superseded/` 生命周期。** 新增生命周期仍会保留过时记录并扩张目录树、格式门禁和维护规则，却无法减少重复内容。
 
@@ -40,7 +40,7 @@ Status: implemented
 
 - 每项实质性变更都会在实现旁保留其决策依据和被放弃的备选方案。
 - 贡献者维护现有的决策持有记录，而不是创建重复记录。
-- 被完全取代的记录可以归并到一个当前持有记录中，同时不丢失其独有的决策依据或验证契约。
+- 被完全取代的记录可以归并到一个当前持有记录中，同时不丢失其独有的决策依据或验证约定。
 - 后来被移除的功能可以只有一个当前持有记录，而无需继续保留过时的实现与测试清单。
 - 仅部分被取代的情况仍需明确记录并互相链接；删除记录则必须在同一变更中清理链接和双语配对。
 - 机械编辑仍保持轻量，门禁拓扑和运行时间也保持不变。
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
index 6189729de0..bafe5adfdf 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-20-gui-testing-system.md
 2026-07-20-gui-testing-system.md: 4a1600bbef7ef795677a446228fcc279a4b53f39
-2026-07-20-gui-testing-system.zh.md: af4736ced6195dfc8d40ab276149490e8af94975
+2026-07-20-gui-testing-system.zh.md: bd617f39a7cd5fd49e5c3a8a992b7dff35a800bf
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
index af4736ced6..bd617f39a7 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
@@ -43,7 +43,7 @@ GUI 栈需要考虑多种应用形态，同应用形态内的不同运行环境
 
 - **修一个 bug 钉一条断言**：浏览器可见的 bug 钉进所属浏览器 spec（smoke 或 e2e 场景）；数据层 bug 钉进对应 spec（先例：res-close 误判钉在 webserver 桥 suite——纯 Node 秒级复现，不再需要 12s 浏览器哨兵作唯一防线）。
 - **fixture 全绿不算完，真 wire 也要过**：fixture 短路的恰是 wire 承载链（node:http 桥 close 语义、真网络时序），两次实证 bug 都藏在那里。改动触及连接/桥/handler/SSE 的，浏览器车道（`pnpm run test:web`）必跑——其无密钥 e2e 场景驱动真实 HTTP/SSE 承载，带密钥的真 host smoke 仍是真模型侧的补充。
-- 落盘代码即答案的对表工作流：行为改动落盘打红既有用例时，当场对表校准（改测试还是改代码以 RFC/契约为裁），不留悬红。
+- 落盘代码即答案的对表工作流：行为改动落盘打红既有用例时，当场对表校准（改测试还是改代码以 RFC/约定为裁），不留悬红。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
index a1c49fdcae..02daf774f7 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
 2026-07-21-serial-cross-platform-ci-reference.md: 71b364f72a094f7899a0929eec29f3a16ccc8a93
-2026-07-21-serial-cross-platform-ci-reference.zh.md: 4f5920ffc150ce16d5567ca05128f7524c2a2b21
+2026-07-21-serial-cross-platform-ci-reference.zh.md: bc8b210e4f32c4e2fe3154bb7ffe9d89210d5087
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
index 4f5920ffc1..bc8b210e4f 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
@@ -16,11 +16,11 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和 Windows 作业，以及 Node 兼容性与 Python 契约。向 `master` 推送时会跳过这些作业，改为运行四个显式参考作业：在标准托管运行器上的 `serial / linux`、`serial / macos` 和 `serial / windows`，以及在公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——后者是热备演练，持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。
+[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和 Windows 作业，以及 Node 兼容性与 Python 约定。向 `master` 推送时会跳过这些作业，改为运行四个显式参考作业：在标准托管运行器上的 `serial / linux`、`serial / macos` 和 `serial / windows`，以及在公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——后者是热备演练，持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。
 
 每个参考作业均在不设置任何分片选择器的情况下运行 `pnpm run check:ci`。`DSH_GATE_CONCURRENCY=1` 使顶层聚合每次只执行一个已经就绪的门禁；覆盖率、快照回放、built-bin 冒烟测试和发布验证的 worker 数量也设为 1。各参考作业可以彼此并行，但每台主机上的仓库门禁都串行运行且完整执行。Linux 在回放快照前安装 bubblewrap，Windows 则在安装采用符号链接的工作区前启用开发人员模式。
 
-该完整聚合流程仍明确划分平台归属。`pty-local` 支持 Linux 与 macOS，因此其单元测试和逐文件覆盖率契约由 POSIX 平台负责，而不会在 Windows 上加载一个明确拒绝 `win32` 的后端；Windows 仍会执行所有可移植包。可移植 fixture（测试前置数据）通过 `node:path` 派生原生路径，使用与生产代码相同的原生 realpath 实现比较规范化后的路径标识，并采用所有宿主机均允许的文件名。ACP（Agent Client Protocol）快照运行还会把生成的 cwd 分别通过 realpath 的 JavaScript 实现与原生实现得到的两种表示一并传给规范化器；规范化器按长度从长到短替换这些别名，避免 Windows 的短路径与长路径表示差异导致共享 fixture 反复变化。
+该完整聚合流程仍明确划分平台归属。`pty-local` 支持 Linux 与 macOS，因此其单元测试和逐文件覆盖率约定由 POSIX 平台负责，而不会在 Windows 上加载一个明确拒绝 `win32` 的后端；Windows 仍会执行所有可移植包。可移植 fixture（测试前置数据）通过 `node:path` 派生原生路径，使用与生产代码相同的原生 realpath 实现比较规范化后的路径标识，并采用所有宿主机均允许的文件名。ACP（Agent Client Protocol）快照运行还会把生成的 cwd 分别通过 realpath 的 JavaScript 实现与原生实现得到的两种表示一并传给规范化器；规范化器按长度从长到短替换这些别名，避免 Windows 的短路径与长路径表示差异导致共享 fixture 反复变化。
 
 macOS 参考流程使用 fork 进程运行常规 Vitest 项目。macOS arm64 上的 Node 24 曾在工作线程中执行 CJS 词法分析器时异常终止；进程边界能够隔离这一外部运行时故障，且无需从聚合流程中删除任何测试，而 Linux 与 Windows 仍使用开销更低的线程池。仓库自身引入的竞态均在相应的观测边界修复：开发构建产物的轮询逻辑每次发布重新扫描结果前，都会先暂存候选表、候选图和候选监视基线映射；构建产物缺失后会一直保持脏状态，直到成功计算内容哈希。PTY 就绪检测会在轮询检查前台进程组归属期间保留提示符候选项；常规静默时限也适用于交互式子进程继承提示符标记的情况。真实 PTY fixture 会在运行时拼接同步标记，使就绪等待逻辑不会把交互式 shell 的输入回显误判为子进程已就绪。实时链接场景下的包管理器 e2e 会保留由工作流预先准备的 Corepack 主目录、pnpm 元数据缓存和 store 缓存，同时隔离其他包管理器的可变缓存，因此不会在安装前丢弃可复用的包管理器状态。
 
@@ -34,7 +34,7 @@ master 分支的参考作业仅用于诊断，不参与拉取请求所要求的
 
 - **将每个超时值设为相应延迟目标**：不予采纳，因为调度波动会中止原本正确的执行，并使诊断回归所需的证据无法产生。
 - **仅信任并发执行的主门禁清单**：不予采纳，因为调度逻辑与校验逻辑共享实现假设；串行聚合流程是一项独立的完整性检查。
-- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业会重复完整的跨平台聚合流程，并为每项改动增加 macOS 工作；必需作业已经执行阻塞性的 Linux 和 Windows 契约。
+- **在每个拉取请求上运行串行参考作业**：不予采纳，因为这些作业会重复完整的跨平台聚合流程，并为每项改动增加 macOS 工作；必需作业已经执行阻塞性的 Linux 和 Windows 约定。
 - **在每个拉取请求上运行真实内核 Sandbox 矩阵**：不予采纳，因为它的四个状态不参与分支保护，而重复安装、Landlock 构建以及为保持平台一致而运行的 macOS 单元测试会消耗运行器容量，却不会改变合并裁决。master 上的运行保留平台与已安装 launcher 的信号。
 - **使用一个操作系统矩阵**：不予采纳，因为三个具名作业无需另一套选择机制，就能让参考流程的构成清晰可见。
 - **在大型运行器上运行串行参考流程**：不予采纳，因为当组织自有运行器池无法分配作业时，必需 CI 及其独立参考流程都必须仍可运行。
diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml
index 1dc5d79676..d8d79cbf9a 100644
--- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.md
 2026-07-22-evidence-based-larger-hosted-runners.md: 53cc86efce9061c8f9836a17cb35ebb128085b7a
-2026-07-22-evidence-based-larger-hosted-runners.zh.md: 0484548c76cb7eed11dc4235ef024a700499ef6a
+2026-07-22-evidence-based-larger-hosted-runners.zh.md: c9daf5273e190d3828e80ebe81369e72f5d7a74d
diff --git a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md
index 0484548c76..c9daf5273e 100644
--- a/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-企业保留仅限本仓库使用的 Ubuntu 和 Windows x64 大型运行器池。普通拉取请求直接指定 3 个 32 核运行器池：Ubuntu 24.04 用于完整覆盖率，Ubuntu latest 用于其余主 Node 24 清单，Windows 2025 用于阻塞性 Windows 契约。公网 IP 已禁用；工作流并发仍设有边界，因为自动扩缩容上限既不会分配闲置机器，也不意味着仓库工作可以无限扩展。
+企业保留仅限本仓库使用的 Ubuntu 和 Windows x64 大型运行器池。普通拉取请求直接指定 3 个 32 核运行器池：Ubuntu 24.04 用于完整覆盖率，Ubuntu latest 用于其余主 Node 24 清单，Windows 2025 用于阻塞性 Windows 约定。公网 IP 已禁用；工作流并发仍设有边界，因为自动扩缩容上限既不会分配闲置机器，也不意味着仓库工作可以无限扩展。
 
-必需主路径依赖这些企业级运行器池。GitHub 标准托管作业保留 Node 22.19、Node 26 和 Python SDK 兼容性契约，而[可移植恢复边界](2026-07-23-portable-required-pull-request-ci.md)与[串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)则在 `master` 上持续提供完整的标准运行器证据。`suite=larger-runner-benchmark` 比较已预配规格上相互独立的关键通道，`suite=consolidated-runner-benchmark` 则比较完整聚合流程。每项基准测试都会先报告实测的处理器和内存容量，再运行仓库工作。
+必需主路径依赖这些企业级运行器池。GitHub 标准托管作业保留 Node 22.19、Node 26 和 Python SDK 兼容性约定，而[可移植恢复边界](2026-07-23-portable-required-pull-request-ci.md)与[串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)则在 `master` 上持续提供完整的标准运行器证据。`suite=larger-runner-benchmark` 比较已预配规格上相互独立的关键通道，`suite=consolidated-runner-benchmark` 则比较完整聚合流程。每项基准测试都会先报告实测的处理器和内存容量，再运行仓库工作。
 
 原有的门禁级和粗粒度主流程分片作业已从工作流中移除。相应的静态、lint、覆盖率、快照和场景分片选择器也已从仓库中移除，因此未使用的诊断路径无法继续维系第二套 CI 架构。
 
@@ -22,9 +22,9 @@ Linux 主流程使用 3 个相互独立的 32 核作业。覆盖率单独运行
 
 门禁依赖关系保持显式。覆盖率消费源码，不等待构建。文档类型检查以消费方通道的完整 project-reference 输出为输入。快照回放和发布消费方等待生成的输出，而 Node 版本兼容性作业会验证对运行时敏感的源码加载，且不重复主源码项目图的类型检查。PTY 和子进程套件继续使用自身有界的内部并发，不继承运行器的核心数。
 
-产物边界保持显式。`scripts/publint-all.ts` 对内存中的发布视图调用 publint 支持的 API；该视图由每个 manifest（元数据清单）声明的文件和 npm 强制要求的元数据组成，从而避免为每个包启动一次包管理器 pack 进程。`scripts/verify-built-package-invariants.mjs` 将已声明的 `lib/` 文件暂存到真实包下，并通过普通 Node 和 Cordis Loader 规范化导入其已编译的自身引用；发布契约只要遗漏一个运行时分片，检查仍会失败。
+产物边界保持显式。`scripts/publint-all.ts` 对内存中的发布视图调用 publint 支持的 API；该视图由每个 manifest（元数据清单）声明的文件和 npm 强制要求的元数据组成，从而避免为每个包启动一次包管理器 pack 进程。`scripts/verify-built-package-invariants.mjs` 将已声明的 `lib/` 文件暂存到真实包下，并通过普通 Node 和 Cordis Loader 规范化导入其已编译的自身引用；发布约定只要遗漏一个运行时分片，检查仍会失败。
 
-Windows 以一次 32 核环境设置同时承载阻塞性构建、生产网站和观测性的构建产物契约。重复的 lint、覆盖率和快照清单由 Linux 承担，因为在 Windows 上运行这些观测性副本会延长付费关键路径，却不会新增任何阻塞性平台契约。
+Windows 以一次 32 核环境设置同时承载阻塞性构建、生产网站和观测性的构建产物约定。重复的 lint、覆盖率和快照清单由 Linux 承担，因为在 Windows 上运行这些观测性副本会延长付费关键路径，却不会新增任何阻塞性平台约定。
 
 一次分支头精确的全规格基准测试在修正构建尽早启动逻辑前，对每种 Linux 池都运行了完整且未分片的主 Node 聚合流程：
 
@@ -60,7 +60,7 @@ Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完
 
 **将原有的门禁级分片拓扑保留为手动参考。** 一套闲置的第二拓扑会让数百行工作流、选择器模块和场景分区行为继续存活。全规格和串行套件无需保留任何必需作业都不执行的生产代码，也能提供计时与完整性对照。
 
-**在每个发布校验器中恢复使用包管理器打包。** 不予采用，因为这会为每个包重复启动一个包管理器子进程。根据 manifest 构建的发布视图和已暂存的编译后自身引用，只需一份进程内清单即可保留发布文件契约。
+**在每个发布校验器中恢复使用包管理器打包。** 不予采用，因为这会为每个包重复启动一个包管理器子进程。根据 manifest 构建的发布视图和已暂存的编译后自身引用，只需一份进程内清单即可保留发布文件约定。
 
 **在每个 Node 版本上先构建，再运行覆盖率或类型检查。** 不予采用，因为覆盖率只消费源码，编译器分析也不依赖运行时。依赖构建产物的消费方仍等待生成的输出，兼容性作业则在每个已声明支持的 Node 版本上验证对运行时敏感的路径。
 
@@ -74,7 +74,7 @@ Windows 仓库工作在超过 16 核后收益很小，但 32 核池可以让完
 
 **将必需的 Windows 检查和观测性 Windows 检查保留在不同作业中。** 这种拆分在工作流层保留状态语义，却需要支付两次设置开销。`run-gates` 在一个进程内保留了相同的必需与非阻塞区别。
 
-**通过系统包管理器安装 Bubblewrap。** 此方案会使用主机的包数据库，即使包内容很小，也可能主导整个作业耗时。固定版本的解压方式配合隔离探针，无需修改托管映像即可保留运行时契约。
+**通过系统包管理器安装 Bubblewrap。** 此方案会使用主机的包数据库，即使包内容很小，也可能主导整个作业耗时。固定版本的解压方式配合隔离探针，无需修改托管映像即可保留运行时约定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.i18n.yaml
index 1382e073c1..d85aa1fe0c 100644
--- a/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-product-first-root-readme.md
 2026-07-22-product-first-root-readme.md: 32542a45019d64ed1826d4eb21e68c67c3c3d52e
-2026-07-22-product-first-root-readme.zh.md: 994228d89154a041757685f526cad63c9455cfc8
+2026-07-22-product-first-root-readme.zh.md: 8ef6f4b99ca2c935183a225b6357d2d128edb3b0
diff --git a/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.zh.md b/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.zh.md
index 994228d891..8ef6f4b99c 100644
--- a/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-product-first-root-readme.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 **将仓库呈现为 SDK 和包清单。** 这样能立即展现实现广度，却会迫使新读者从包名反推出产品。包索引与生成的能力图仍是权威清单。
 
-**使用包含截图、徽章和重复教程的长篇营销页面。** 富媒体能够展示稳定的产品使用路径，但其内容会独立于命令和源码契约而逐渐陈旧。根 README 保持紧凑，并链接到可运行示例和各自维护的指南。
+**使用包含截图、徽章和重复教程的长篇营销页面。** 富媒体能够展示稳定的产品使用路径，但其内容会独立于命令和源码约定而逐渐陈旧。根 README 保持紧凑，并链接到可运行示例和各自维护的指南。
 
 **将根 README 投影为文档网站首页。** 使用同一个首页可以避免两套叙事，但文档网站的用户指南与仓库面向产品和开发者的入口在导航和维护需求上并不相同。
 
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
index 2a6cdcc2d0..45f0ba8ce1 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md
 2026-07-22-tsconfig-solution-root-two-aggregates.md: 6e8d192b5fea1c7045ade6935fd0e2dc8434c502
-2026-07-22-tsconfig-solution-root-two-aggregates.zh.md: 60581e3de55227a393e2528ce7d3c8fa1bf9c570
+2026-07-22-tsconfig-solution-root-two-aggregates.zh.md: 827b56288fd832a65af6a948651b7e70127a1882
diff --git a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
index 60581e3de5..827b56288f 100644
--- a/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md
@@ -27,7 +27,7 @@ GUI 拆分引入了第二个聚合 program（`tsconfig.client.json`，见[分层
 
 整个方案立足的原则：**cordis `Context` 的声明合并冲突只存在于同一个 `ts.Program` 内部，从不发生在模块解析中。** solution 文件不构成 program，因此从一个根文件同时引用两个聚合不会让两侧的声明合并相撞；vite-tsconfig-paths 只读取 `paths` 与 `include`、丢弃全部类型信息，因此一个门面可以横跨两侧。唯一会爆炸的做法是把两侧压平进同一个 program，由此推出两条派生纪律：`tsconfig.base.json` 永远不得添加 `include`/`files`（否则会泄漏进每个继承它的包，并收窄门面范围）；每个全仓级 `ts.Program` 消费方（`scripts/ts-project.ts`、doc-typecheck 独立模式）都显式以 `tsconfig.host.json` 或 `tsconfig.client.json` 为种子，绝不使用根 solution。基于 program 的生成器与语义门禁有意只留在宿主侧；客户端侧只有在真实需求出现时才引入基于 program 的门禁。
 
-根 `tsconfig.json` 仍是显式执行完整 Project Reference 图的 solution 入口，lefthook pre-push 通过 `tsc -b tsconfig.json --pretty false` 增量覆盖两侧。仓库的 `build` 与 `typecheck` 命令因 Client 依赖 Host tsdown 生成的 Remote 契约而按 Host、Client 顺序运行，具体编排由 [API Remotes 构建 Note](2026-08-08-api-remotes-generated-contract-build.md)负责。`tsconfig.build.json` 与 `tsconfig.vitest.json` 已删除；所有 vitest 配置都把 vite-tsconfig-paths 指向 `tsconfig.base.json`。
+根 `tsconfig.json` 仍是显式执行完整 Project Reference 图的 solution 入口，lefthook pre-push 通过 `tsc -b tsconfig.json --pretty false` 增量覆盖两侧。仓库的 `build` 与 `typecheck` 命令因 Client 依赖 Host tsdown 生成的 Remote 约定而按 Host、Client 顺序运行，具体编排由 [API Remotes 构建 Note](2026-08-08-api-remotes-generated-contract-build.md)负责。`tsconfig.build.json` 与 `tsconfig.vitest.json` 已删除；所有 vitest 配置都把 vite-tsconfig-paths 指向 `tsconfig.base.json`。
 
 solution 根文件刻意 `extends` base：`examples/` 与 `scripts/` 没有更近的 tsconfig，tsx（get-tsconfig）通过根文件解析它们的 workspace 导入。`extends` 把 `paths` 映射带回根文件，`files: []` 则让它始终不构成 program。这不影响两者的*类型检查*：examples、scripts 与 website 的文件由宿主聚合纳入。
 
@@ -41,5 +41,5 @@ solution 根文件刻意 `extends` base：`examples/` 与 `scripts/` 没有更
 
 - `docs/development.md#typescript-project-layout` 是权威描述；根 `AGENTS.md` 以约定形式收录上述两条纪律。
 - [ts-build-config Agent Note](2026-06-17-ts-build-config.md) 继续拥有 tsc 先行的构建流水线（tsc 负责输出，tsdown 负责打包，`.ts` 说明符配合 `rewriteRelativeImportExtensions`）；其原先「单一根类型检查项目」的形态由本文取代。
-- 新增一个普通 package 只登记进恰好一个 aggregate 的 references（Host package 进 `tsconfig.host.json`，Client package 进 `tsconfig.client.json`）。`api/remotes` 因 Host 生成契约与 Client 消费契约的顺序关系成为唯一显式拆分例外；其两个具体 project 分别登记，包根 solution 不进入任一 aggregate。
-- Host 与 Client 构建阶段必须串行：Host tsdown 生成契约后 Client tsc 才能开始。各阶段复用各 project 的增量状态，不通过并发重复处理同一张图。
+- 新增一个普通 package 只登记进恰好一个 aggregate 的 references（Host package 进 `tsconfig.host.json`，Client package 进 `tsconfig.client.json`）。`api/remotes` 因 Host 生成约定与 Client 消费约定的顺序关系成为唯一显式拆分例外；其两个具体 project 分别登记，包根 solution 不进入任一 aggregate。
+- Host 与 Client 构建阶段必须串行：Host tsdown 生成约定后 Client tsc 才能开始。各阶段复用各 project 的增量状态，不通过并发重复处理同一张图。
diff --git a/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.i18n.yaml
index e5d8f11c3c..eb11cc1b92 100644
--- a/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.md
 2026-07-23-personal-staging-maintenance-skills.md: a7ccc5b1e0f13e880c58a93d2e4c2cd4f06e2a93
-2026-07-23-personal-staging-maintenance-skills.zh.md: d988eae0b4746f14b893b8f1f32f8396e6548232
+2026-07-23-personal-staging-maintenance-skills.zh.md: 8593291f510352429cbb29679e7d033589312e41
diff --git a/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.zh.md b/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.zh.md
index d988eae0b4..8593291f51 100644
--- a/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.zh.md
+++ b/.agents/notes/implemented/process/2026-07-23-personal-staging-maintenance-skills.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 仓库从其根 `skills/` 目录分发 [`dsh-customize`](../../../../skills/dsh-customize/SKILL.md)、[`dsh-upgrade`](../../../../skills/dsh-upgrade/SKILL.md) 和 [`dsh-upstream-customization`](../../../../skills/dsh-upstream-customization/SKILL.md)。它们的描述同时说明操作内容和选择该 skill（技能）的用户请求。分发的 TUI 在启动时将该目录提供给本地 skill 提供方，在发现优先级上位于项目根目录和用户根目录之后。这些 skill 根据已安装的启动器而非个人路径或分支名称定位当前生效的检出和集成分支，遵从仓库内指令，要求使用任务 worktree，并利用集成分支所在 worktree 的既有 `.agents/merge.lock`，串行执行每一次个人集成分支修改。
 
-升级流程在变基前检查 Git 日志和提交范围，以识别将进入升级的上游变更、个人提交、重复内容和可能发生冲突的区域。它会丢弃上游已经提供的定制；如果这类定制在本地只剩文档差异，也会一并丢弃，除非该说明包含上游缺失且可独立使用的当前契约。每次升级尝试使用同一个 UTC 基本格式时间戳，用于其独立的 `dsh-staging-<timestamp>` 同级克隆、本地 `dsh-upgrade/prepare-<timestamp>` 分支、新的 `dsh-staging/<timestamp>` 分支、私有的上游引用与恢复引用，以及启动器备份。同级克隆的名称不派生自当前目录名，名称冲突会直接失败，而不是追加临时后缀。流程根据进程命令和运行时环境而非 shell 工作目录推导当前 DSH 进程的源码位置，随后将已安装启动器所指向的仓库和检出视为不可变，唯一例外是持有其既有合并锁。
+升级流程在变基前检查 Git 日志和提交范围，以识别将进入升级的上游变更、个人提交、重复内容和可能发生冲突的区域。它会丢弃上游已经提供的定制；如果这类定制在本地只剩文档差异，也会一并丢弃，除非该说明包含上游缺失且可独立使用的当前约定。每次升级尝试使用同一个 UTC 基本格式时间戳，用于其独立的 `dsh-staging-<timestamp>` 同级克隆、本地 `dsh-upgrade/prepare-<timestamp>` 分支、新的 `dsh-staging/<timestamp>` 分支、私有的上游引用与恢复引用，以及启动器备份。同级克隆的名称不派生自当前目录名，名称冲突会直接失败，而不是追加临时后缀。流程根据进程命令和运行时环境而非 shell 工作目录推导当前 DSH 进程的源码位置，随后将已安装启动器所指向的仓库和检出视为不可变，唯一例外是持有其既有合并锁。
 
 在独立克隆中验证通过后，工作流会创建并验证带时间戳的集成分支，然后以原子方式将启动器从保持不变的旧集成分支检出一次性切换到新集成分支检出。启动器绝不会指向准备、功能、评审、发布或处于分离状态的检出。切换前的失败会让已安装的检出和启动器保持不变；切换后的失败则恢复并验证启动器备份。旧的集成分支检出、其分支、恢复引用和启动器备份会一直保留，直到重启后的进程证明 DSH 运行于新的集成分支，且用户明确批准回滚清理为止。
 
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
index 440691d218..0f80587749 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.md
 2026-07-23-portable-required-pull-request-ci.md: 1a6939e8386e381cba114a7be71993a644457a45
-2026-07-23-portable-required-pull-request-ci.zh.md: f7a95ced2353ca7aaee9a586cc4f0bb297cbf7d4
+2026-07-23-portable-required-pull-request-ci.zh.md: 83737b61bc72e3c1ee6afb805d30256d572211a2
diff --git a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
index f7a95ced23..83737b61bc 100644
--- a/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md
@@ -12,9 +12,9 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `ubuntu-latest` 上通过 Wine 运行 Windows Node 以覆盖阻断性检查范围（[Wine 通道决策](2026-07-27-wine-windows-gates-experiment.md)），使拉取请求的 Windows 契约不依赖任何 Windows 运行器分配；完整的原生内核 Windows 清单位于 master 串行参考流程中。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，`master` 则运行完整的 Linux、macOS 和 Windows 串行参考流程。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
+[CI](../../../../.github/workflows/ci.yml) 在仅限本仓库使用的企业级 32 核运行器池上运行必需的主 Node 24 作业，以及稳定的 `all checks passed` 聚合流程。该聚合流程不执行代码检出或仓库门禁；但让它与所依赖的实质性作业共用企业级运行器池，可以避免这些作业已经成功后，必需判定结果又引入一项单独的标准托管计费依赖。必需的 Windows 作业在标准 `ubuntu-latest` 上通过 Wine 运行 Windows Node 以覆盖阻断性检查范围（[Wine 通道决策](2026-07-27-wine-windows-gates-experiment.md)），使拉取请求的 Windows 约定不依赖任何 Windows 运行器分配；完整的原生内核 Windows 清单位于 master 串行参考流程中。标准 `ubuntu-latest` 作业保留 Node 22.19、Node 26 和 Python SDK 兼容性，`master` 则运行完整的 Linux、macOS 和 Windows 串行参考流程。这些标准托管作业让可移植执行边界保持可观测，而不必在每个拉取请求中重复主清单。
 
-两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / wine blocking` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的契约，但无法产出缺失的必需结果。
+两项 Linux 主作业、Node 兼容性、Python SDK 和 `windows node 24 / wine blocking` 继续作为 `all checks passed` 的依赖项；分支保护继续要求 `e2e` 和 `all checks passed`。剩余的企业级 Linux 运行器标签无法分配运行器时没有自动后备机制：标准作业会继续报告各自的约定，但无法产出缺失的必需结果。
 
 当前主拓扑及其测量结果由[大型运行器决策](2026-07-22-evidence-based-larger-hosted-runners.md)记录。[跨平台串行参考流程](2026-07-21-serial-cross-platform-ci-reference.md)继续作为独立的标准托管完整性检查，手动大型运行器套件则保留规格比较，同时不扩大普通必需矩阵。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 **根据标称核心数选择企业规格。** 基准测试表明扩展效果不呈单调变化，设置耗时也存在波动，因此必需运行器池改由完整作业的精确测量结果选定。
 
-**在容量不可用时跳过检查或降低其级别。** 这种方式通过丢弃证据而非执行仓库的必需契约来使状态变绿。
+**在容量不可用时跳过检查或降低其级别。** 这种方式通过丢弃证据而非执行仓库的必需约定来使状态变绿。
 
 **在每台主机上使用同一工作线程策略。** 外层门禁并发与内层工具工作线程在 Linux、Windows 和标准运行器上的争用方式不同；按主机实测的上限可以避免新增核心反而拖慢执行。
 
diff --git a/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.i18n.yaml b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.i18n.yaml
index 3d471fc9f3..b768fb0abc 100644
--- a/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md
 2026-07-23-translation-prompt-v4-contract.md: adeb63e0f4bf03ec0b94a371f596bb84138d81ed
-2026-07-23-translation-prompt-v4-contract.zh.md: 5bd7bbf0d2d02222ca8038afb0f5a156fffea1b0
+2026-07-23-translation-prompt-v4-contract.zh.md: bd9a18788cbc04f733f52270ec486923c552459e
diff --git a/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.zh.md b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.zh.md
index 5bd7bbf0d2..bd9a18788c 100644
--- a/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.zh.md
+++ b/.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 经校准的翻译提示词 v4 契约
+# Agent Note: 经校准的翻译提示词 v4 约定
 
 Status: implemented
 
@@ -10,9 +10,9 @@ Status: implemented
 
 ## 决策
 
-提交入库的[翻译提示词](../../../../docs/i18n/translation-prompt.md)是经过校准的流水线资源。其渲染器仅注入源语言、目标语言和当前[术语表](../../../../docs/i18n/terminology.md)，并在组装请求前拒绝未知、缺失或语法格式错误的占位符。请求组装器在模型可见的提示词之外保留源文件基本名，并在真正的源文档之前，将每组经评审的整篇文档对编排为一个纯文本 user/assistant 示例轮次。模板可以包含针对特定模型的校准规则，但这些规则必须服从仓库中具约束力的配对、术语、结构与强调格式契约。
+提交入库的[翻译提示词](../../../../docs/i18n/translation-prompt.md)是经过校准的流水线资源。其渲染器仅注入源语言、目标语言和当前[术语表](../../../../docs/i18n/terminology.md)，并在组装请求前拒绝未知、缺失或语法格式错误的占位符。请求组装器在模型可见的提示词之外保留源文件基本名，并在真正的源文档之前，将每组经评审的整篇文档对编排为一个纯文本 user/assistant 示例轮次。模板可以包含针对特定模型的校准规则，但这些规则必须服从仓库中具约束力的配对、术语、结构与强调格式约定。
 
-v7 校准保留这套 v4 协议，并明确指令优先级：先保持源文含义与受保护结构，再遵循术语表，然后以整篇金标校准语体，最后应用一般指导与内嵌示例。模型先以母语技术作者的方式起草，再逐项对照源文，保留执行主体、条件、否定、情态、生命周期条件、方向、结果通道、所有权和数量。文体指导不得虚构执行主体，也不得仅为丰富措辞而改换术语表词形、已定义概念或契约动词。无法裁定的术语在译文中保持不变，只在评审段标为待人工确认。
+v7 校准保留这套 v4 协议，并明确指令优先级：先保持源文含义与受保护结构，再遵循术语表，然后以整篇金标校准语体，最后应用一般指导与内嵌示例。模型先以母语技术作者的方式起草，再逐项对照源文，保留执行主体、条件、否定、情态、生命周期条件、方向、结果通道、所有权和数量。文体指导不得虚构执行主体，也不得仅为丰富措辞而改换术语表词形、已定义概念或约定动词。无法裁定的术语在译文中保持不变，只在评审段标为待人工确认。
 
 响应包含三个有序的顶层分段：`translation`、`review` 和 `final`。响应消费方根据保留的源文件上下文推导目标文件基本名，保留文件开头可选的 YAML frontmatter，并以机械方式在 `final` 中第一个 H1 之后插入或校正语言切换行。解析器要求每个分段恰好出现一次，拒绝封套之外的内容，并允许响应最外层有一层 `xml` Markdown 围栏，因为模型有时会照抄提示词中的示例围栏。
 
@@ -20,13 +20,13 @@ v7 校准保留这套 v4 协议，并明确指令优先级：先保持源文含
 
 分段定界行由协议格式（wire format）保留。当 Markdown 正文中的某一行仅包含定界标签（前面可以带反斜杠）时，序列化器和模型会在行首再添加一个反斜杠；解析器则只移除一个。这种保留计数的转义方式让字面量定界标签与已转义的定界标签都能无损往返，同时不会改动行内提及的标签。
 
-可执行契约由[渲染器、请求组装器、解析器和响应消费方](../../../../scripts/translation-prompt.ts)实现。单元测试覆盖两个翻译方向、请求顺序、占位符校验、目标路径校验、严格的分段顺序与数量约束、带围栏的响应、行内提及标签、Markdown 正文中的定界行，以及保留 YAML frontmatter 的新配对语言切换行校正。一个无密钥子进程快照锁定组装后的提示词、五个经评审的示例轮次，以及带 YAML frontmatter 的录制响应经目标路径校正后的消费结果。
+可执行约定由[渲染器、请求组装器、解析器和响应消费方](../../../../scripts/translation-prompt.ts)实现。单元测试覆盖两个翻译方向、请求顺序、占位符校验、目标路径校验、严格的分段顺序与数量约束、带围栏的响应、行内提及标签、Markdown 正文中的定界行，以及保留 YAML frontmatter 的新配对语言切换行校正。一个无密钥子进程快照锁定组装后的提示词、五个经评审的示例轮次，以及带 YAML frontmatter 的录制响应经目标路径校正后的消费结果。
 
 ## 考虑过的替代方案
 
 **在每个请求中注入 `translation-rules.md`。** 该文档既约束人类与 agent，也约束自动翻译流水线。注入它会让编辑规范的每次澄清都与模型行为耦合，并挤占经过人工校准的提示词约束；因此流水线仅注入具约束力的术语表，并直接校验自身资源。
 
-**使用严格的 CDATA XML 文档。** CDATA 提供通用的 XML 封装，但会引入一层嵌套协议、额外的 `]]>` 转义规则，以及三段式契约原本不需要的 XML 解析器行为。预留并转义六种定界行，既能维持经校准的响应形态，也能保留任意 Markdown 内容不变。
+**使用严格的 CDATA XML 文档。** CDATA 提供通用的 XML 封装，但会引入一层嵌套协议、额外的 `]]>` 转义规则，以及三段式约定原本不需要的 XML 解析器行为。预留并转义六种定界行，既能维持经校准的响应形态，也能保留任意 Markdown 内容不变。
 
 **只返回最终译文。** 单一正文更易解析，却会丢弃显式修正步骤；这个步骤用于在发布前发现语气、结构、术语和标点缺陷。
 
@@ -36,4 +36,4 @@ v7 校准保留这套 v4 协议，并明确指令优先级：先保持源文含
 
 ## 影响
 
-提示词措辞属于可执行行为，因此需要经过代码评审、翻译提示词校验器校验及可运行的请求/响应快照验证。聚焦测试固定保留的 v4 示例与选定的 v7 保护规则。`translation-prompt-v4` 快照目录命名的是稳定的渲染器／解析器协议谱系，而不是当前校准修订号。经校准的资源与通用翻译规则可以针对各自的受众分别演进，但评审必须拒绝任何与仓库约束性契约冲突的改动。只有当源文档中的封装标签独占一行时，行转义才会显现；解析器测试锁定这一无损行为。
+提示词措辞属于可执行行为，因此需要经过代码评审、翻译提示词校验器校验及可运行的请求/响应快照验证。聚焦测试固定保留的 v4 示例与选定的 v7 保护规则。`translation-prompt-v4` 快照目录命名的是稳定的渲染器／解析器协议谱系，而不是当前校准修订号。经校准的资源与通用翻译规则可以针对各自的受众分别演进，但评审必须拒绝任何与仓库约束性约定冲突的改动。只有当源文档中的封装标签独占一行时，行转义才会显现；解析器测试锁定这一无损行为。
diff --git a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml
index ac859f10dd..7f4bc40463 100644
--- a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md
 2026-07-26-briefed-minimal-translation-updates.md: afd990b7b63adfd0e66a4726975b678d044e7cad
-2026-07-26-briefed-minimal-translation-updates.zh.md: dcdb253746041a7928ab7a544ae427293bc3f2de
+2026-07-26-briefed-minimal-translation-updates.zh.md: a6559667f0f1140d8a26cd5ebc4bb64b7b95fe45
diff --git a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md
index dcdb253746..a6559667f0 100644
--- a/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-[双语配对契约](2026-07-02-bilingual-docs-and-pairing-gate.md)早已规定对侧文件按最小幅度更新：把被改的一侧与其上次确认状态做 diff，据此修补对侧文件，绝不整篇重译；但仓库内置的工作流让每次更新都付出整篇文档级别的开销。负责翻译的 subagent 在动手处理一个两行的 diff 之前，要先加载完整的指导语料（guidance corpus），即 skill（技能）、配对契约、翻译规则、192 行的术语表、语体样例与行文标准；要通过 `git cat-file` 手工重新推导上次确认状态以来的 diff；每轮迭代还要重跑全语料配对门禁，而该门禁为校验一个配对要解析整棵树里的每一个配对。一次小的英文行文修改，动辄花掉数十倍于其应得份额的 token 用量与分钟数，被惩罚的恰恰是契约想要的行为：在同一个 PR（Pull Request）里把对侧文件一并带上。
+[双语配对约定](2026-07-02-bilingual-docs-and-pairing-gate.md)早已规定对侧文件按最小幅度更新：把被改的一侧与其上次确认状态做 diff，据此修补对侧文件，绝不整篇重译；但仓库内置的工作流让每次更新都付出整篇文档级别的开销。负责翻译的 subagent 在动手处理一个两行的 diff 之前，要先加载完整的指导语料（guidance corpus），即 skill（技能）、配对约定、翻译规则、192 行的术语表、语体样例与行文标准；要通过 `git cat-file` 手工重新推导上次确认状态以来的 diff；每轮迭代还要重跑全语料配对门禁，而该门禁为校验一个配对要解析整棵树里的每一个配对。一次小的英文行文修改，动辄花掉数十倍于其应得份额的 token 用量与分钟数，被惩罚的恰恰是约定想要的行为：在同一个 PR（Pull Request）里把对侧文件一并带上。
 
 ## 决策
 
@@ -31,10 +31,10 @@ Status: implemented
 ## 曾考虑的替代方案
 
 - **保留原工作流，只让门禁支持按对检查**：门禁扫描本是较小的开销，大头在语料加载与翻查历史。只收窄检查范围，约 3 倍的开销仍会原地保留。
-- **把整篇重译作为更新路径**（朴素流水线的做法）：依据基准测试证据否决，理由是保留度崩塌、术语漂移、成本最高。契约的最小更新规则得以延续，且从此有数据支撑。
+- **把整篇重译作为更新路径**（朴素流水线的做法）：依据基准测试证据否决，理由是保留度崩塌、术语漂移、成本最高。约定的最小更新规则得以延续，且从此有数据支撑。
 - **每个 subagent 批量处理多对文档**：否决。没有实测出节省（简报本身已对固定内容做了去重），而且一对文档停滞或陷入混乱会把其余配对一并拖住。
 - **在伴随记录中保存逐段的翻译记忆条目**（用分段 hash 取代整文件 hash）：否决。配对两侧的段落边界可以合理地不同，任一侧都可能先撰写，这类条目还会不断膨胀并在合并时产生冲突。基于现有整文件 hash 按需计算的区间映射，在对齐可信时能恢复同样的对齐关系，不可信时会明确说明。
-- **给自动提示词流水线加一个更新模式（prompt-v5）**：推迟，本文不做设计。今天没有任何调用方在驱动 [scripts/translation-prompt.ts](../../../../scripts/translation-prompt.ts)，实际的成本中心是 agent 路径。流水线在拥有消费方之前，维持其整篇文档的 v4 契约。
+- **给自动提示词流水线加一个更新模式（prompt-v5）**：推迟，本文不做设计。今天没有任何调用方在驱动 [scripts/translation-prompt.ts](../../../../scripts/translation-prompt.ts)，实际的成本中心是 agent 路径。流水线在拥有消费方之前，维持其整篇文档的 v4 约定。
 
 ## 后果
 
@@ -44,8 +44,8 @@ Status: implemented
 - 不带参数的 `--write` 不再可用；靠肌肉记忆的调用者必须点名配对或传 `--all`。这正是目的所在：批量背书如今是一个可见的、有意为之的动作。
 - 按对检查意味着一个更新循环可以在别处某个无关配对处于红灯时自己保持绿灯；`doc-sync`/CI 中的全语料检查仍然承载树级不变式。
 - 区间映射只在上次确认源文、当前源文与当前对侧文本三方的种类序列一致时才信任一处对齐；映射失败时粒度确定性地逐级放宽（单元 → 章节 → 整篇文档）而不是靠猜，因此被重构过的文档拿到的是一份明确写着「请自行定位相关区域」的简报，绝不会是一张错误的地图。
-- 「首次出现」的一次移位可能让简报扩大到直接改动块之外；这一成本是「首次出现」契约的明确后果，而非对齐启发式。
+- 「首次出现」的一次移位可能让简报扩大到直接改动块之外；这一成本是「首次出现」约定的明确后果，而非对齐启发式。
 
 ## 测试
 
-[scripts/translation-brief.spec.ts](../../../../scripts/translation-brief.spec.ts) 固定单元与章节的区间提取（以容器为作用域的种类、只按深度对齐章节从而让已翻译的标题文字仍能映射、首个标题前的序言）、对齐与改动索引检测、机械代码拼接及其每一个拒绝条件、带词边界与复数变形约束的双向术语行匹配、首次出现移位跟踪、围栏升级，以及渲染后简报的契约（带三方上下文的单元条目、机械／章节／整篇文档三种范围、分方向的规则摘要、按对的收尾命令）。[scripts/translation-pairing.spec.ts](../../../../scripts/translation-pairing.spec.ts) 固定未提交快照的精确字节持久化与取回、在不可用对象进入伴随记录前失败、参数归一化（配对的任一文件或裸词干都归一到锚点），以及 CLI（命令行界面）用例矩阵：按对检查、裸 `--write` 拒绝执行、`--write <pair>`、`--write --all`、`--list` 的互斥性、未知标志。
+[scripts/translation-brief.spec.ts](../../../../scripts/translation-brief.spec.ts) 固定单元与章节的区间提取（以容器为作用域的种类、只按深度对齐章节从而让已翻译的标题文字仍能映射、首个标题前的序言）、对齐与改动索引检测、机械代码拼接及其每一个拒绝条件、带词边界与复数变形约束的双向术语行匹配、首次出现移位跟踪、围栏升级，以及渲染后简报的约定（带三方上下文的单元条目、机械／章节／整篇文档三种范围、分方向的规则摘要、按对的收尾命令）。[scripts/translation-pairing.spec.ts](../../../../scripts/translation-pairing.spec.ts) 固定未提交快照的精确字节持久化与取回、在不可用对象进入伴随记录前失败、参数归一化（配对的任一文件或裸词干都归一到锚点），以及 CLI（命令行界面）用例矩阵：按对检查、裸 `--write` 拒绝执行、`--write <pair>`、`--write --all`、`--list` 的互斥性、未知标志。
diff --git a/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.i18n.yaml
index a15aaff72e..c69d808669 100644
--- a/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md
 2026-07-26-dependencies-over-hand-rolling.md: 22720c483c1c9e8145497b3e83cbc9f17570b161
-2026-07-26-dependencies-over-hand-rolling.zh.md: 4c3aee489cd8a8269b2b083ea2fb7978d01f4e26
+2026-07-26-dependencies-over-hand-rolling.zh.md: 7c155c5ca208153d697a930698a02b0c61966034
diff --git a/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.zh.md b/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.zh.md
index 4c3aee489c..7c155c5ca2 100644
--- a/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.zh.md
@@ -10,13 +10,13 @@ harness 手写了大量基础设施，而成熟的外部包早已提供同等能
 
 ## 决策
 
-引入外部依赖是一种正当的简化，而不是政策特例。当一个维护良好的包（或我们引擎下限即已提供的 Node 内置能力）覆盖了某块手写接口面时，替换手写代码就是优先方向，并遵循与其他任何简化相同的证据标准：这次替换必须切实缩减我们负责维护的内容（代码、测试和契约面），而不是仅仅把复杂度挪到一个包装层后面。
+引入外部依赖是一种正当的简化，而不是政策特例。当一个维护良好的包（或我们引擎下限即已提供的 Node 内置能力）覆盖了某块手写接口面时，替换手写代码就是优先方向，并遵循与其他任何简化相同的证据标准：这次替换必须切实缩减我们负责维护的内容（代码、测试和约定面），而不是仅仅把复杂度挪到一个包装层后面。
 
 新依赖的准入门槛：
 
 - **净删除。** 该依赖替换的是实际由我们维护的代码（实现 + 专属测试 + 文档），而不是假想中的未来代码。只增加能力的依赖属于功能决策，不属于简化。
 - **健康度。** 持续维护、广泛使用、传递依赖足迹合理。一个无人维护的小包，只是拿我们的代码换来别人废弃的代码。
-- **边界契合。** 该包的语义要覆盖我们的实际契约；仍需围绕它手写补齐的残留语义，要计入这次替换的减分项。
+- **边界契合。** 该包的语义要覆盖我们的实际约定；仍需围绕它手写补齐的残留语义，要计入这次替换的减分项。
 - **不触碰已定案的 seam。** schemastery（配置 schema）、源码收录的 Cordis、`@earendil-works` 孪生适配器，以及其他记录在已实现 Agent Note 中的决策，不因本政策而重开；一次会瓦解已记录设计的替换，必须胜过所记录的论证理由，而不能只援引本 Agent Note。
 
 `packages/util/` 的「零依赖」章程描述的是该分组的*导出*纪律（util 包不携带 harness 依赖，从而任何分组都能依赖它们），并不禁止在能带来简化时使用外部包；如果一个 util 包的全部职责有维护良好的外部包做得更好，就应当用该依赖替换它，而不是为了章程而保留它。
diff --git a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml
index b5e11d7a71..1ae66cc1b7 100644
--- a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md
 2026-07-26-frozen-agent-note-archive.md: 52b43088b276c0c8e263fc8a81a2df1408cc8059
-2026-07-26-frozen-agent-note-archive.zh.md: ac87935fff1b3942d0bc8eade49237aa3c90d21e
+2026-07-26-frozen-agent-note-archive.zh.md: a37e06e7cbc19b5000d4849cc3ee2ddc9b451ee3
diff --git a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md
index ac87935fff..a37e06e7cb 100644
--- a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md
@@ -14,7 +14,7 @@ implemented Agent Note 作为当前决策记录持续维护，因此活跃记录
 
 归档路径为 `.agents/notes/archived/{kind}/yyyy-mm-dd-topic.md`，其中省略了冗余的 `implemented` 层级。归档变更会移动完整的英文、中文和一致性伴随记录三个文件，保留 `Status: implemented`，并在两种语言的文件中紧接该状态行插入 `Archived: YYYY-MM-DD`。归档时只允许做文件迁移、添加该元数据行、相应地重新记录伴随记录，以及机械修复入站链接。
 
-归档后，这三个文件永久冻结，只作为历史背景，不再是当前权威依据。不得因为包重命名、行为变化、翻译标准、格式规则、出站链接失效或后续文档契约而更新归档文件。活跃文档可以有意链接到归档 Agent Note，也可以把该链接重定向到当前权威依据，或直接删除。仓库门禁因此会校验指向归档文件的链接，但绝不把归档文件作为链接源来校验。
+归档后，这三个文件永久冻结，只作为历史背景，不再是当前权威依据。不得因为包重命名、行为变化、翻译标准、格式规则、出站链接失效或后续文档约定而更新归档文件。活跃文档可以有意链接到归档 Agent Note，也可以把该链接重定向到当前权威依据，或直接删除。仓库门禁因此会校验指向归档文件的链接，但绝不把归档文件作为链接源来校验。
 
 [`verify-archived-agent-notes`](../../../../scripts/verify-archived-agent-notes.ts) 负责维护冻结边界。它只接受封闭集合中的 Agent Note 类别，要求三个配对文件完整、状态为 implemented，且归档日期有效并互相匹配；它还会用双方当前的 Git blob hash 校验伴随记录，并在仅追加的 manifest（元数据清单） 中按路径和 SHA-256 内容 hash 封存每项产物。其 `--write` 模式会先证明每条现有封存记录对应的内容都未改变，再仅追加新归档的产物。拉取请求 CI 会提供可信的基准 SHA，并在运行校验器前检出完整历史，因此复用运行器上的浅克隆检出无法漏掉基线 manifest。普通的 Agent Note 格式、翻译配对、换行、Markdown 链接、包路径、Mermaid、文档 TypeScript 和类型等价门禁都排除归档源文件，因此这些门禁持续演进的标准不会产生修改历史记录的压力。
 
diff --git a/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.i18n.yaml
index 1aab8e5bad..d7a09d388f 100644
--- a/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.md
 2026-07-26-web-syntax-highlighting-shiki.md: 48a1e4c43f19693f90906f210f0ed85db3f31687
-2026-07-26-web-syntax-highlighting-shiki.zh.md: 31fb3d916c7cb1e928bc37eca86fb11e21374b16
+2026-07-26-web-syntax-highlighting-shiki.zh.md: 7998f7811c8b396538c0d6d06951814e7d4b8e39
diff --git a/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.zh.md b/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.zh.md
index 31fb3d916c..7998f7811c 100644
--- a/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-web-syntax-highlighting-shiki.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-26-web-syntax-highlighting-shiki.md) | 中文
 
-> 范围：web client 唯一的一套语法高亮体系——依赖裁决、单例形态、token 表契约与各消费表面。本篇是 Code Mode UI 堆叠 PR（Pull Request）链的第五个 PR；[chat 子调用行 Agent Note](../feature/2026-07-26-code-mode-chat-subcall-rows.md)交付了 `run_code` 程序正文，而本体系存在的意义正是让它可读。样式的基本规则由 [Web 样式体系裁决](2026-07-19-web-styling-system.md)规定。
+> 范围：web client 唯一的一套语法高亮体系——依赖裁决、单例形态、token 表约定与各消费表面。本篇是 Code Mode UI 堆叠 PR（Pull Request）链的第五个 PR；[chat 子调用行 Agent Note](../feature/2026-07-26-code-mode-chat-subcall-rows.md)交付了 `run_code` 程序正文，而本体系存在的意义正是让它可读。样式的基本规则由 [Web 样式体系裁决](2026-07-19-web-styling-system.md)规定。
 
 ## 问题
 
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
index 4aec3f6a4f..9115979c19 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-29-oxlint-linter.md
 2026-07-29-oxlint-linter.md: 3e3de24be33b8f9461cea2967b0fa18f59ddb52a
-2026-07-29-oxlint-linter.zh.md: 5388416b54a5ff44b9ab9551d726705a84a8b1a1
+2026-07-29-oxlint-linter.zh.md: dae8c7451bd3fbe9296508491aaa51f1118abe92
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
index 5388416b54..dae8c7451b 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
@@ -24,15 +24,15 @@ CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行
 
 解决两处分析器差异后，迁移后的配置报告与迁移前一致的自有源码无问题基线：移除了一项冗余测试断言，而 `tsc` 要求的一处结构性类型转换使用了窄范围的 Oxlint 抑制指令。以已删除 ESLint 配置的精确 blob 为基准进行的一次性审核在完成规则名映射后确认：源码为 88 项对 88 项，示例为 87 项对 87 项，测试为 83 项对 83 项。已提交的指纹锁定这些经审核的 Oxlint 规则配置及完整的覆盖结构；它既不执行已删除的配置，也不纳入后续的上游预设变更。对 `typescript-eslint@8.61.0` 的评估还确认，`strictTypeChecked` 并未启用 `@typescript-eslint/no-empty-function`；已删除、仅用于测试的 `off` 条目不起作用。
 
-可执行契约测试要求包、host 和 client 项目产生类型感知诊断，断言 client 专用脚本所用的项目，拒绝未匹配的回退分析，并检验 Stylistic、SonarJS 和 nursery 兼容路径。它们还锁定暂存配置不加载项目的继承行为、未使用抑制指令的报告行为、仅选择已忽略暂存文件的情况、格式化器与验证器之间的规则一致性，以及最终格式化后的字节。运行器测试锁定两项工作线程控制，类型检查则确认迁移引发的源码改动没有破坏 TypeScript 程序。
+可执行约定测试要求包、host 和 client 项目产生类型感知诊断，断言 client 专用脚本所用的项目，拒绝未匹配的回退分析，并检验 Stylistic、SonarJS 和 nursery 兼容路径。它们还锁定暂存配置不加载项目的继承行为、未使用抑制指令的报告行为、仅选择已忽略暂存文件的情况、格式化器与验证器之间的规则一致性，以及最终格式化后的字节。运行器测试锁定两项工作线程控制，类型检查则确认迁移引发的源码改动没有破坏 TypeScript 程序。
 
 ## 考虑过的替代方案
 
 **在全仓库范围内同时运行两个 linter。** 所有正确性规则均可通过 Oxlint 原生规则、nursery 规则或 JavaScript 插件兼容层获得。在全仓库范围启用 ESLint 回退会保留较慢的项目服务初始化和两套正确性配置，却不会增加任何检查；保留的 ESLint 流程被刻意限制为不加载项目的暂存文件格式化。
 
-**依赖兼容层修复。** 兼容层会报告既有的 `@stylistic` 规则，但在 Oxlint 的两种修复模式下都不会应用这些规则的修复。保留窄范围的暂存文件格式化器，可以在不将 ESLint 扩张回仓库 linter 的情况下维持贡献者契约。
+**依赖兼容层修复。** 兼容层会报告既有的 `@stylistic` 规则，但在 Oxlint 的两种修复模式下都不会应用这些规则的修复。保留窄范围的暂存文件格式化器，可以在不将 ESLint 扩张回仓库 linter 的情况下维持贡献者约定。
 
-**移除尚无原生实现的 @stylistic 或 SonarJS 规则。** 这会移除依赖，但也会削弱机械质量契约。兼容层会保留这些规则，直到能够通过单独决策评估原生替代规则。
+**移除尚无原生实现的 @stylistic 或 SonarJS 规则。** 这会移除依赖，但也会削弱机械质量约定。兼容层会保留这些规则，直到能够通过单独决策评估原生替代规则。
 
 **迁移期间用 Oxfmt 替换 @stylistic。** 格式化器迁移会产生超出 lint 引擎边界的输出变化，并带来全仓库格式 diff。保留既有规则可使本次变更便于评审，并让格式化器选择保持独立。
 
diff --git a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
index 9d3ac28ed2..8e9fb88179 100644
--- a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.md
 2026-07-31-coverage-exempt-heavy-suites.md: 7235a5193554947ecf71f62d522d09f4e21cb1da
-2026-07-31-coverage-exempt-heavy-suites.zh.md: b739e4494ae8d240b0e35109920a49876ebd222d
+2026-07-31-coverage-exempt-heavy-suites.zh.md: 7d622cd7db927f8ccbc12b22a563c5228c56b981
diff --git a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
index b739e4494a..7d622cd7db 100644
--- a/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-coverage-exempt-heavy-suites.zh.md
@@ -17,7 +17,7 @@ CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试
 - **插桩 gate**（`test:coverage`）：设 `DSH_COVERAGE_EXEMPT_HEAVY=1`，`vitest.config.ts` 据此从两个 project 的 exclude 中剔除豁免套件，其余全部文件照旧插桩并承担全部阈值证明。经 gate 自带 env 注入（既有 `Gate.env` 机制），不进 workflow 全局环境，因此并排的无插桩 gate 和本地直跑 `vitest run` 都看不到该变量、行为不变。
 - **无插桩 gate**（`test:coverage-exempt-heavy`）：用配对的 positional filter 恰好运行豁免套件，保证正确性信号不缩水。
 
-`scripts/coverage-exempt.ts` 是唯一名单点，集中持有成员资格契约与 filter/exclude 配对，防止两侧漂移。
+`scripts/coverage-exempt.ts` 是唯一名单点，集中持有成员资格约定与 filter/exclude 配对，防止两侧漂移。
 
 ### 豁免名单与逐项对账
 
@@ -29,9 +29,9 @@ CI 覆盖率 lane（`check:ci:coverage`）的墙钟被少数几个重型测试
 | 其中 tools-catalog.spec 额外 import | `typert-registry`、`tool-cordis` 的 src | 两包各自的测试独立满覆盖（focused coverage 实测无阈值错误） |
 | `scripts/install-lefthook.spec.ts`、`scripts/oxlint-contract.spec.ts`、`scripts/change-scope.spec.ts` | 无——被测对象是 `scripts/` 源码（从不在 coverage.include），执行方式是 spawn 子进程 | 无需接 |
 
-### 成员资格契约
+### 成员资格约定
 
-新增豁免必须同时满足：套件进程内执行的每个被度量文件都已由其他套件满覆盖（或在阈值排除名单内）；filter 与 exclude 选中完全相同的文件集。契约文本随名单同文件维护。
+新增豁免必须同时满足：套件进程内执行的每个被度量文件都已由其他套件满覆盖（或在阈值排除名单内）；filter 与 exclude 选中完全相同的文件集。约定文本随名单同文件维护。
 
 ### 门禁自动守卫名单正确性
 
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
index 77003539ac..a2e19d3493 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
 2026-07-31-installer-adopts-existing-checkout.md: 3a213a6232e57f305910240505983421dcd288ad
-2026-07-31-installer-adopts-existing-checkout.zh.md: 7cdcd5549fb2bca2a6cb11f0cf2867687565ae79
+2026-07-31-installer-adopts-existing-checkout.zh.md: e19baa0b1ee8ce71c1b8f3ee520322fb6557a720
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
index 7cdcd5549f..e19baa0b1e 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `scripts/install.sh`会产生两种互不兼容的安装形态。`curl … | sh`安装会构建受管布局——`~/.dsh/source/master`处的 master 克隆、位于`dsh-staging/<时间戳>`分支上的 staging worktree，以及 PATH 启动器据以解析的稳定`current`符号链接。而从检出中运行同一脚本时，则依据此前的[检出内跳过克隆决策](../../archived/process/2026-07-22-installer-in-repo-skip-clone.md)，把`dsh`直接链接到该检出的`bin/dsh`。
 
-这种直接链接是一种终态。升级重指的正是`current`，因此缺少它的安装无法通过[`dsh-upgrade`](../../../../skills/dsh-upgrade/SKILL.md)升级；检出一旦移动，PATH 符号链接就会失效；而且启动器会解析到贡献者恰好检出的任意分支，这正是升级契约禁止作为启动器目标的情形。升级技能早已把这种形态描述为需要一次性迁移的旧式安装，于是两种布局在安装时就已分叉，并且要到很久以后才会被调和——甚至永远不会。
+这种直接链接是一种终态。升级重指的正是`current`，因此缺少它的安装无法通过[`dsh-upgrade`](../../../../skills/dsh-upgrade/SKILL.md)升级；检出一旦移动，PATH 符号链接就会失效；而且启动器会解析到贡献者恰好检出的任意分支，这正是升级约定禁止作为启动器目标的情形。升级技能早已把这种形态描述为需要一次性迁移的旧式安装，于是两种布局在安装时就已分叉，并且要到很久以后才会被调和——甚至永远不会。
 
 ## Decision
 
@@ -22,17 +22,17 @@ Status: implemented
 
 所有路径比较都通过`resolve_dir`辅助函数在物理路径上进行，且每个参与比较的值都在赋值时解析，而非在比较时解析。git 报告的始终是已解析的路径，因此只要检出之上任意一层存在符号链接，拿它与未解析的路径相比较就会不相等——家目录本身是符号链接即已足够，而 macOS 通过`/var` -> `private/var`使每个`mktemp`路径都如此。这种不匹配会把已有的受管安装误判为外来克隆，并在真正的容器旁再建一个容器。同一缺陷在评审过程中又出现了两次，两次都是比较的一侧未经解析：一次是 curl 安装的`REPO_ROOT`，一次是与之比较的容器路径。因此`resolve_dir`在路径不存在时原样回显该路径而非失败，这样尚未创建的容器无需在每个调用点单独兜底，也就没有调用点会因遗漏兜底而与空路径比较；需要判断"不存在"的调用方则显式检测该目录。`git rev-parse --path-format=absolute`能完成同样的工作，但要求 git 2.31 及以上版本。
 
-在重指`current`之前，安装器会拒绝解析结果等于仓库自身的 staging 路径，以此落实"启动器绝不解析到 master 克隆"这一升级契约。
+在重指`current`之前，安装器会拒绝解析结果等于仓库自身的 staging 路径，以此落实"启动器绝不解析到 master 克隆"这一升级约定。
 
 ## Alternatives considered
 
 **把`~/.dsh/source/master`做成指向该任意克隆的符号链接。** 已否决。Git 会解析该符号链接并记录*真实*路径：经由它创建的 worktree 会存储`gitdir: …/<克隆>/.git/worktrees/<名称>`，而`git worktree list`报告的是该克隆。因此这个符号链接纯属装饰——没有任何代码读取它——却又暗示容器拥有该仓库。它还会静默失效：移动克隆后，`master`看似仍在却已悬空，而每个 staging worktree 都会以`fatal: not a git repository`失败。最糟的是，它把两个名称别名到同一棵树上，于是"current 绝不能是 master 克隆"这项检查会在字符串比较下通过，实则为假。`~/.dsh/source/master`是位置而非名称，且只有位置具有权威性。
 
-**把检出自身提升为`current`的目标。** 已否决：升级契约要求`current`必须是位于 staging 分支上的干净 staging worktree，绝不能是 feature、review 或 detached 检出。这还会使每次升级都改写贡献者正在编辑的那棵树。
+**把检出自身提升为`current`的目标。** 已否决：升级约定要求`current`必须是位于 staging 分支上的干净 staging worktree，绝不能是 feature、review 或 detached 检出。这还会使每次升级都改写贡献者正在编辑的那棵树。
 
 **把就地链接保留在提示或`DSH_ADOPT`开关之后。** 已否决；本次变更的早期修订版本正是如此实现，之后被移除。分叉的形态本身就是缺陷，因此把它保留为一个选项等于保留了问题，并使此后每次改动需要推敲的状态翻倍——提示、开关、工作树不干净的警告，以及第二条链接路径，全都只为维持一种本不该产生的形态而存在。就地链接最初的动机——让脚本能针对本地源码进行测试——在接管方案下依然成立：以检出的`HEAD`为起点创建的 staging worktree 运行的是同一份代码。`DSH_SOURCE`仍是安装另一棵树的退路。
 
-**在工作树不干净时发出警告或提示。** 已否决：以`HEAD`为起点的`worktree add`本就无法带上未提交的内容，因此该行为是确定的，提示只会增加一个用户无法做出不同选择的决策点。改为在文档中说明该契约。
+**在工作树不干净时发出警告或提示。** 已否决：以`HEAD`为起点的`worktree add`本就无法带上未提交的内容，因此该行为是确定的，提示只会增加一个用户无法做出不同选择的决策点。改为在文档中说明该约定。
 
 **把被接管克隆的 staging worktree 放在该克隆旁边**（`~/src/staging-*`），而非放进`~/.dsh/source`。已否决：`current`和 PATH 启动器都是每用户唯一的，因此把 worktree 散落到各个克隆的父目录中，会重新引入 source 容器本就为之而设、意在杜绝的同级克隆蔓延问题。
 
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
index 7bc08eb82d..19dd1f9ab3 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
 2026-08-03-package-anchored-subsystem-pages.md: 5ba7937f0c142727d343a107a3ff87f5f337931e
-2026-08-03-package-anchored-subsystem-pages.zh.md: 27d56158a69a8144b0915054032fb3b54493bd0b
+2026-08-03-package-anchored-subsystem-pages.zh.md: 9166843cbfbbd065eca06e8716098581433ba41d
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
index 27d56158a6..9166843cbf 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## Problem
 
-[子系统目录](2026-06-20-core-data-structures-catalog.md)最初用主干-vs-seam 规则界定首页范围：如果循环在每个轮次都持有、派生、流式传输或记录某个类型，它就是「核心」。该规则选择的是类型而非包，因此当目录增长到四十多页后，首页变成了跨包大杂烩：LLM 对话词汇排在 agent 契约之前，创建/所有权词汇（`AgentHandle`、`CreateAgentOptions`、`ResumeAgentOptions`、`AgentFactory`）在目录中无处记录（生成器把它们豁免给了某个包 README），读者无法根据类型所在位置预测哪一页记录它。与此同时，各包分组 README 没有统一形状——有的带分节表格、游离的设计短文，或本应属于子系统页面的尾部段落。
+[子系统目录](2026-06-20-core-data-structures-catalog.md)最初用主干-vs-seam 规则界定首页范围：如果循环在每个轮次都持有、派生、流式传输或记录某个类型，它就是「核心」。该规则选择的是类型而非包，因此当目录增长到四十多页后，首页变成了跨包大杂烩：LLM 对话词汇排在 agent 约定之前，创建/所有权词汇（`AgentHandle`、`CreateAgentOptions`、`ResumeAgentOptions`、`AgentFactory`）在目录中无处记录（生成器把它们豁免给了某个包 README），读者无法根据类型所在位置预测哪一页记录它。与此同时，各包分组 README 没有统一形状——有的带分节表格、游离的设计短文，或本应属于子系统页面的尾部段落。
 
 ## Decision
 
-每个 `docs/subsystems/` 页面锚定到声明其词汇的包或包分组，页面归属跟随仓库布局：[core.md](../../../../docs/subsystems/core.md) 是 `packages/core` 的页面（创建与所有权、`Agent` 句柄及其投递/取消/拦截契约、指向该组专属页面的指针），[llm-streaming.md](../../../../docs/subsystems/llm-streaming.md) 端到端拥有 `packages/llm`，依此类推。全仓通用类型模式（`…Map → 派生联合`、品牌化 id）保留在 core.md 一个明确标注的收尾小节中，而不是与包内容交错。这在*页面范围界定规则*的意义上取代了主干-vs-seam 规则；存活下来的放置启发式更简单：类型记录在其声明包对应的页面，机制仍与其机制放在一起。
+每个 `docs/subsystems/` 页面锚定到声明其词汇的包或包分组，页面归属跟随仓库布局：[core.md](../../../../docs/subsystems/core.md) 是 `packages/core` 的页面（创建与所有权、`Agent` 句柄及其投递/取消/拦截约定、指向该组专属页面的指针），[llm-streaming.md](../../../../docs/subsystems/llm-streaming.md) 端到端拥有 `packages/llm`，依此类推。全仓通用类型模式（`…Map → 派生联合`、品牌化 id）保留在 core.md 一个明确标注的收尾小节中，而不是与包内容交错。这在*页面范围界定规则*的意义上取代了主干-vs-seam 规则；存活下来的放置启发式更简单：类型记录在其声明包对应的页面，机制仍与其机制放在一起。
 
 生成签名引用的每个类型都必须能在目录中某处解析：agent 所有权词汇从生成器的 `TYPE_LINK_EXEMPTIONS` 移入 `LINK_MAP → core.md`，因此豁免只留给真正服务本地或 vendored 的形状。每个粘贴的声明只有一个家（`SessionEvent` 位于 [session.md](../../../../docs/subsystems/session.md)；core.md 概括并链接）。
 
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
index 2a4a389174..9cef49fa0a 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
 2026-08-06-in-repository-landlock-release.md: 3ae9e9c3c50a1d0202a345e419cb2b7079e29ffa
-2026-08-06-in-repository-landlock-release.zh.md: 9f2233f6ae95620d7221f83648b5dc9b4cf8c7d2
+2026-08-06-in-repository-landlock-release.zh.md: ffebe45c537ee192ef855296b3334937485e2a89
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
index 9f2233f6ae..ffebe45c53 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器契约及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
+`@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器约定及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
 
 发布镜像还造成重复的发布协调工作：导出源码、更新另一份锁文件、运行另一套发布工作流、发布原生包家族，然后回到本仓库更新注册表依赖。npm 用户的实际需求并未改变，这种拆分却增加了从源码到二进制的溯源、回滚和安全修复协调难度。
 
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
index dec1b79d6a..189815bc8d 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md
 2026-08-08-api-remotes-generated-contract-build.md: 947465b19a7c399038ae8a3106f7563592365a8d
-2026-08-08-api-remotes-generated-contract-build.zh.md: 7b559cd966c4acc055d41379c15f46fdfc649a00
+2026-08-08-api-remotes-generated-contract-build.zh.md: 26108bc840f701cb02db4a41138024a1be3c549f
diff --git a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
index 7b559cd966..26108bc840 100644
--- a/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: API Remotes 生成契约的有序构建
+# Agent Note: API Remotes 生成约定的有序构建
 
 Status: implemented
 
@@ -12,7 +12,7 @@ Host 的 `@Remote` 方法需要先由 TypeRT 生成 `/remote` 声明和运行时
 
 ## 决策
 
-根构建先完成 Host tsc 和 Host tsdown，由 Host tsdown 运行 TypeRT 并生成 Remote Client 契约；随后完成 Client tsc、Client tsdown 和 Web 构建：
+根构建先完成 Host tsc 和 Host tsdown，由 Host tsdown 运行 TypeRT 并生成 Remote Client 约定；随后完成 Client tsc、Client tsdown 和 Web 构建：
 
 ~~~text
 tsc -b tsconfig.host.json
@@ -28,7 +28,7 @@ Vite Web build
 
 ## 唯一的 package 特例
 
-`api/remotes` 是唯一同时拥有 Host 与 Client composite project 的 package。Host project 包含 Agent/Session lookup 策略、Host 插件入口和 invariant；Client project 只包含需要等待生成契约的 `src/client/index.ts`：
+`api/remotes` 是唯一同时拥有 Host 与 Client composite project 的 package。Host project 包含 Agent/Session lookup 策略、Host 插件入口和 invariant；Client project 只包含需要等待生成约定的 `src/client/index.ts`：
 
 ~~~text
 packages/api/remotes/
@@ -47,11 +47,11 @@ packages/api/remotes/
 
 两个 project 使用互不重叠的 `files` 和不同的 `.tsbuildinfo`，因此可以共享 `lib/types` 而不重复发射任何源码。若未来需要两侧共用一份实现，应把实现移入中立 package，不能把同一源码同时交给两个 emitting project。
 
-这个例外由生成契约的真实先后关系决定，不是可供普通 package 选择的模板。新增 package 仍只能登记进一个 aggregate；只有修改本决策并证明存在另一条不可消除的生成依赖，才能增加例外。
+这个例外由生成约定的真实先后关系决定，不是可供普通 package 选择的模板。新增 package 仍只能登记进一个 aggregate；只有修改本决策并证明存在另一条不可消除的生成依赖，才能增加例外。
 
 ## TypeRT 与 tsdown
 
-Host tsdown 在普通根配置中启用 `typertPlugin({ mode: 'workspace', faces: ['host'] })`。generator 只以 `tsconfig.host.json` 为 program 种子，生成 `typert.host.*` 以及 Host 契约投影出的 `typert.remote-client.*`；Client tsdown 不启动 TypeRT，也不分析 Client aggregate。
+Host tsdown 在普通根配置中启用 `typertPlugin({ mode: 'workspace', faces: ['host'] })`。generator 只以 `tsconfig.host.json` 为 program 种子，生成 `typert.host.*` 以及 Host 约定投影出的 `typert.remote-client.*`；Client tsdown 不启动 TypeRT，也不分析 Client aggregate。
 
 TypeScript compiler face 与 TypeRT 运行时产物 face 是两层概念。普通 `dshClient` package 即使只有一个 compiler project，也可以按公开 subpath 同时贡献 Host 与 Client 运行时模型；aggregate 显式引用 `tsconfig.host.json` 或 `tsconfig.client.json` 时，analyzer 才把该 project 限定到对应 face。因此 `api-remotes` 的 Host 分析不会顺带注册其 Client 入口，普通双入口 package 的 Host 模型也不会丢失。
 
@@ -69,11 +69,11 @@ Host 与 Client 两次 tsdown 都接收 `vendor/*`、`packages/*/*` 和 `apps/cl
 
 **扫描 Client 编译产物或维护两份 workspace 清单。** 产物扫描会让 package 是否参与构建取决于残留文件，手工清单和 package 名过滤则会随目录调整产生漂移。完整 workspace 加包内 face 选择已经提供确定行为。
 
-**在 Client pass 再运行 TypeRT。** Remote Client 是 Host 契约的投影，没有独立 Client 反射源；第二个 TypeRT program 只会重复工作并增加两侧声明混入同一分析的风险。
+**在 Client pass 再运行 TypeRT。** Remote Client 是 Host 约定的投影，没有独立 Client 反射源；第二个 TypeRT program 只会重复工作并增加两侧声明混入同一分析的风险。
 
 ## 后果
 
-干净构建成为顺序正确性的权威验证：没有任何既存 `/remote` 产物时，Host tsc 必须先成功，Host tsdown 必须生成契约，随后 Client tsc、Client tsdown 与 Web build 必须成功。任何阶段都不得把产物写进 `src`。
+干净构建成为顺序正确性的权威验证：没有任何既存 `/remote` 产物时，Host tsc 必须先成功，Host tsdown 必须生成约定，随后 Client tsc、Client tsdown 与 Web build 必须成功。任何阶段都不得把产物写进 `src`。
 
 [TypeScript 构建配置 Note](2026-06-17-ts-build-config.md)确定的 tsc-first 职责保持不变，但其单次全图 tsc 后再打包的命令形态由本文的有序阶段取代。[双 aggregate solution Note](2026-07-22-tsconfig-solution-root-two-aggregates.md)确定的普通 package 单 aggregate 规则保持不变，本文只为 `api/remotes` 建立一个显式例外。
 
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
index 0c44f790b7..9e1fcce244 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md
 2026-08-08-automatic-translation-pairing-merges.md: ac4e0c11290abfd48d0f3caf037062aa2fe36c4d
-2026-08-08-automatic-translation-pairing-merges.zh.md: 38e8c0a5613a6bd0b3e76143a93c93653430d0c2
+2026-08-08-automatic-translation-pairing-merges.zh.md: 149f37ec61689e01fa713dabe0ded5506dff4fed
diff --git a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
index 38e8c0a561..149f37ec61 100644
--- a/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 `pre-merge-commit` 与 `pre-commit` 通过限定范围的配对检查，对照两侧文档在索引中的精确字节校验暂存的 `.i18n.yaml` 文件。这些钩子会验证驱动输出，但不会重新生成记录，因此绕过钩子也无法默默确认发生漂移的译文；CI 中全语料的 `doc-sync`（文档同步门禁）仍是权威检查。
 
-## 失败契约
+## 失败约定
 
 | 普通 `git merge` 期间的失败 | 可观察状态 | 恢复 |
 |---|---|---|
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
index 5ee57b914f..2e33d34157 100644
--- a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
 2026-08-08-unified-github-label-taxonomy.md: fddda6c99053e55d3e31a2f6e5c55add09772117
-2026-08-08-unified-github-label-taxonomy.zh.md: c8d727c9a56d6c7c25f73eacde42e0bef1c779b7
+2026-08-08-unified-github-label-taxonomy.zh.md: 75333e3823d6e96ef41b1359a81d53f4bd872f87
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
index c8d727c9a5..75333e3823 100644
--- a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
@@ -27,18 +27,18 @@ Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对
 | `kind/cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
 | `kind/dependency` | 在没有其他主导意图时更新依赖。 |
 
-类型记录主导意图。配套测试、文档、清理或依赖调整不会盖过功能变更或缺陷修复这一主导意图。新增类型会改变这项分类契约，因此必须明确修改分类体系和政策。
+类型记录主导意图。配套测试、文档、清理或依赖调整不会盖过功能变更或缺陷修复这一主导意图。新增类型会改变这项分类约定，因此必须明确修改分类体系和政策。
 
 仓库政策会拒绝不支持的 `kind/*` 值，并将统一过程中移除的所有别名列为保留名称：`kind/bug`、`kind/documentation`、`feature`、`bug-fix`、`doc`、`cleanup`、`testing`、`dependencies`、`ci`、`cli`、`llm` 和 `web-search`。精确保留这组已迁移的名称，可以防止过时的同义名称被重新创建成看似无关的管理用途标签。
 
 ### 领域
 
-领域表示持久的语义领域，而不是临时专项、归属关系或偶然触及的每条路径。一项 PR 修改不同契约时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项契约。GitHub 上现行的 `area/*` 名称和说明定义当前清单；本记录定义选择规则，以及简短标签说明无法可靠容纳的非显然边界。
+领域表示持久的语义领域，而不是临时专项、归属关系或偶然触及的每条路径。一项 PR 修改不同约定时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项约定。GitHub 上现行的 `area/*` 名称和说明定义当前清单；本记录定义选择规则，以及简短标签说明无法可靠容纳的非显然边界。
 
 - `area/web` 覆盖浏览器与 Electron 图形界面，`area/vscode` 覆盖编辑器扩展，`area/api` 覆盖跨界面协议与各语言 SDK。
 - `area/planning` 覆盖目标、计划、待办和调度，`area/workflow` 则覆盖可执行工作流与后台任务运行时。
 - `area/artifact` 有意合并产物、附件与多模态交付。只有当这些关注点再次需要独立评审或查询时，才有理由拆分标签。
-- `area/tools` 适用于通用注册表、schema 与执行契约。具体能力使用自身的领域标签，除非它还修改了这项通用契约。
+- `area/tools` 适用于通用注册表、schema 与执行约定。具体能力使用自身的领域标签，除非它还修改了这项通用约定。
 - `area/hooks` 表示 Claude Code 与 Codex 桥接，`area/infra` 覆盖构建、发布、CI、仓库门禁、生成器、依赖与开发者工具，`area/windows` 覆盖原生 Windows 产品支持，而不是 CI runner 的选型。
 
 领域集合有意保持可扩展。当现有说明都无法如实涵盖一个持久且可复用的领域时，agent（智能体）无需另行批准，即可创建一个简洁的 `area/<lowercase-kebab-case>` 标签。agent 不得为单个 PR、偶然涉及的路径、临时项目、状态、个人或团队创建领域，并且必须在应用新标签后向请求者报告该标签及理由。仅为避免新增一个确有必要的领域标签而复用不准确的领域，不可接受。
@@ -61,11 +61,11 @@ Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然
 
 **为每种交付载体或媒体生命周期单设标签。** 浏览器与 Electron 交付共用一个图形界面领域，产物、附件与多模态交付目前也共用一个评审／查询领域。只有当拆分能恢复有用的独立分类时，才应在后续分类体系变更中进行。
 
-**用宽泛的实现标签取代语义领域。** 一项具体能力并不只是其工具、接口、文件系统或进程实现。通用实现领域只在其自身契约变化时适用。
+**用宽泛的实现标签取代语义领域。** 一项具体能力并不只是其工具、接口、文件系统或进程实现。通用实现领域只在其自身约定变化时适用。
 
 **在 Issue 上使用类型标签。** 原生 Issue Type 已负责这项分类；再用标签复制会造成漂移。
 
-**每个 PR 恰好一个领域。** 内聚的变更可能对多个独立契约产生实质影响，丢弃次要领域会隐藏受影响范围。
+**每个 PR 恰好一个领域。** 内聚的变更可能对多个独立约定产生实质影响，丢弃次要领域会隐藏受影响范围。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
index ee84bcf366..2233dcadde 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
 2026-06-19-drop-mutable-session-summary.md: f87378a1c3737950eb536be8e3f6776586eb8a01
-2026-06-19-drop-mutable-session-summary.zh.md: 41dab3fa0b487b057d33335a21cee92cf211560f
+2026-06-19-drop-mutable-session-summary.zh.md: f15dcc038154a9170ac41fd5733712164728f518
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
index 41dab3fa0b..f15dcc0381 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 - `firstPrompt` 在生产代码中**从未被读取**。
 - 会话标题来自持久的 `session/title` 事件，工具卡片标题来自工具 presenter；二者都不读取可变的会话元数据。
 - 持久化列表的消费方使用不可变 header 中的标识、创建时间、谱系和 cwd 字段。近期排序和预览派生自日志，而非某个 `updatedAt` 摘要。
-- 决定性的一点：活跃的 `Session.header` 类型本来就是 `SessionHeader` 而非 `SessionMeta`——摘要从未存在于活跃会话对象上；它只存在于持久化层，除了自身的契约测试外无人写入、无人读取。
+- 决定性的一点：活跃的 `Session.header` 类型本来就是 `SessionHeader` 而非 `SessionMeta`——摘要从未存在于活跃会话对象上；它只存在于持久化层，除了自身的约定测试外无人写入、无人读取。
 
 ## 决策
 
@@ -22,7 +22,7 @@ Status: implemented
 
 摘要原本要提供的一切，在消费方真正需要时都**可从仅追加日志中派生**（`firstPrompt` = 第一条 `user/message`；近期度 = 最后一个事件的 `time` 或文件 mtime），或者已经存在于不可变 header 中（`createdAt`、`cwd`）。唯一*不可*派生的是用户*手动编辑*的标题，但它从未实现，纯属 YAGNI；如果未来真有功能需要，它可以作为独立的日志事件或 header 字段回归。
 
-这被记录为一项决策，因为它具有**持久性**（它同时收窄两个后端的公开服务契约和磁盘格式）、**争议性**（summary 是有意为未来设计的结果，而非意外），也具有**反直觉性**（未来读者在原 Agent Note 描述 `SessionMeta` 的位置发现 `SessionHeader` 时，若无此记录便会追问 summary 为何消失）。它还为[共享持久化写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.md)扫清障碍：不再有可变 summary 后，协调器的钩子接口不需要 `updateSummary` 钩子，JSONL sidecar 与 SQLite 列之间的持久性分歧也随之消失，使两个后端的写入路径趋于一致。
+这被记录为一项决策，因为它具有**持久性**（它同时收窄两个后端的公开服务约定和磁盘格式）、**争议性**（summary 是有意为未来设计的结果，而非意外），也具有**反直觉性**（未来读者在原 Agent Note 描述 `SessionMeta` 的位置发现 `SessionHeader` 时，若无此记录便会追问 summary 为何消失）。它还为[共享持久化写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.md)扫清障碍：不再有可变 summary 后，协调器的钩子接口不需要 `updateSummary` 钩子，JSONL sidecar 与 SQLite 列之间的持久性分歧也随之消失，使两个后端的写入路径趋于一致。
 
 ## 无需迁移
 
@@ -30,6 +30,6 @@ Status: implemented
 
 ## 后果
 
-未来的会话选择器现在必须从日志派生预览/排序信息（或重新引入一个类型化字段），而不能直接读取现成的摘要行。这是正确的代价：为一个尚不存在的功能维护缓存，是每个后端都要承担维护成本、每个契约测试都要承担断言成本的无谓负担。这一原则——**通过的测试固定的是当前行为，不一定是正确行为；行为可能是过去妥协的产物**——现已作为独立约定记录在[根 AGENTS.md](../../../../AGENTS.md) 中，本次变更即为其实例。
+未来的会话选择器现在必须从日志派生预览/排序信息（或重新引入一个类型化字段），而不能直接读取现成的摘要行。这是正确的代价：为一个尚不存在的功能维护缓存，是每个后端都要承担维护成本、每个约定测试都要承担断言成本的无谓负担。这一原则——**通过的测试固定的是当前行为，不一定是正确行为；行为可能是过去妥协的产物**——现已作为独立约定记录在[根 AGENTS.md](../../../../AGENTS.md) 中，本次变更即为其实例。
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
index 3b50695584..77b76293e3 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
 2026-06-20-public-agent-stop-surface.md: e9c713c7ba8c784d3d66fe8f391e1b197f7394d2
-2026-06-20-public-agent-stop-surface.zh.md: 217c898eec6b9e232f2cf3982b2bec411e8d91ab
+2026-06-20-public-agent-stop-surface.zh.md: c57bb32643344c237dd68479e3ab8f8a7404a594
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
index 217c898eec..c57bb32643 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
@@ -10,13 +10,13 @@ Status: implemented
 
 公共 `Agent` handle 暴露了两种相互重叠的在途工作停止方式：仅针对步骤的 `abort()` 和感知队列的 `cancel()`。前者保留已排队输入，后者原本只暴露广义默认行为，该行为会清除已排队和 steering（中途引导）工作，同时中止活动轮次。`cancel(cause, { keepInbox: true })` 现在无需暴露私有轮次 holder 即可覆盖生产环境的 Web 停止策略；ACP 保留广义取消，生命周期拥有者则通过 `AgentHandle.dispose()` 拆除 agent（智能体）。没有生产调用方需要一个裸的、仅针对步骤的 abort。
 
-行为差异确实存在，但已发布代码不需要独立的更窄动词。AgentLoop 为整个轮次拥有一个私有取消 holder。`cancel(cause, options?)` 携带显式且类型化的 `user` 或 `parent` 原因；其广义默认行为丢弃待处理输入，`keepInbox` 则为后续轮次保留待处理工作。资源释放仍是单独的生命周期中断。完整的归属与传播契约位于[显式轮次取消 Agent Note](../architecture/2026-07-16-explicit-turn-cancellation.md)。
+行为差异确实存在，但已发布代码不需要独立的更窄动词。AgentLoop 为整个轮次拥有一个私有取消 holder。`cancel(cause, options?)` 携带显式且类型化的 `user` 或 `parent` 原因；其广义默认行为丢弃待处理输入，`keepInbox` 则为后续轮次保留待处理工作。资源释放仍是单独的生命周期中断。完整的归属与传播约定位于[显式轮次取消 Agent Note](../architecture/2026-07-16-explicit-turn-cancellation.md)。
 
 多余的公开接口使循环承载了一个本质上属于内部拆卸的公开动词。带选项的 `cancel()` 可以表达调用方策略，而无需暴露第二个 holder 形态的操作。
 
 ## 决策
 
-`cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用广义 `cancel()` 放弃当前和已排队工作，或使用 `keepInbox` 中止活动轮次并保留待处理工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 契约。[Web 停止决策](../bug-fix/2026-07-31-web-stop-preserves-queue.md)是生产环境中的 `keepInbox` 消费方。
+`cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用广义 `cancel()` 放弃当前和已排队工作，或使用 `keepInbox` 中止活动轮次并保留待处理工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 约定。[Web 停止决策](../bug-fix/2026-07-31-web-stop-preserves-queue.md)是生产环境中的 `keepInbox` 消费方。
 
 `whenIdle()` **保留**为公开的完全停稳观测原语（agent 从 `running` 状态稳定后 resolve，已处于 idle 时立即 resolve，dispose 后等待循环退出）。它不是停止动词；它是非所有者在不 dispose agent 的前提下观测停止*完成*的方式。它的活跃消费方是 ACP 和通过此公开 seam 等待结算的 agent 测试（`packages/acp/acp/tests`、`packages/core/agent-loop/tests`）；生产环境的 ACP 桥接层拥有其 agent 并通过 `AgentHandle.dispose()` 销毁它们，因此 `packages/acp/acp/src` 本身没有 `whenIdle()` 调用。
 
@@ -32,7 +32,7 @@ Status: implemented
 
 ## 后果
 
-插件可以通过 `keepInbox` 在保留已排队提示词的同时中止活动轮次，但不能只中止某一个模型／工具步骤而让该轮次继续运行。仅步骤用例需要具名消费方和更窄契约；暴露私有循环机制仍缺乏正当理由。
+插件可以通过 `keepInbox` 在保留已排队提示词的同时中止活动轮次，但不能只中止某一个模型／工具步骤而让该轮次继续运行。仅步骤用例需要具名消费方和更窄约定；暴露私有循环机制仍缺乏正当理由。
 
 ## 相关
 
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
index f0e7bb8fb9..7aab9c96af 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
 2026-06-26-fsspec-style-fs-seam.md: b5c201fb192782f130d3609978d16f0fc6d4d55e
-2026-06-26-fsspec-style-fs-seam.zh.md: 8346ba76d099a458236e200f304c4921553584d3
+2026-06-26-fsspec-style-fs-seam.zh.md: 2ed74af594296f2853f4d97474c4ee07ef83dbd5
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
index 8346ba76d0..2ed74af594 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
@@ -30,9 +30,9 @@ provider      dsh-fs-local      local implementation of ctx.fs
 
 `dsh-tool-fs` 保持相同的面向模型的 `read`/`write`/`edit` schema。它是执行器：注入 `fs`（不是策略服务）并直接访问 `ctx.fs`，拥有读取窗口化逻辑，并分发 `fs/*` 事件以便 `dsh-fs-policy` 进行门控和记录。
 
-本 Agent Note 决定了四层拆分、提供方契约和新鲜度策略。随后，[事件门禁 Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) 细化了工具↔策略耦合：`dsh-fs-policy` 是通过 `fs/*` 事件参与的门禁插件，而非 `ctx.fileContext` 方法服务，因此工具不会在方法层与其耦合；读取窗口和 fs I/O 位于 `dsh-tool-fs`。本文描述已经落地的事件门禁形状；提供方的版本守卫可选（省略即无条件裸提供方）。
+本 Agent Note 决定了四层拆分、提供方约定和新鲜度策略。随后，[事件门禁 Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) 细化了工具↔策略耦合：`dsh-fs-policy` 是通过 `fs/*` 事件参与的门禁插件，而非 `ctx.fileContext` 方法服务，因此工具不会在方法层与其耦合；读取窗口和 fs I/O 位于 `dsh-tool-fs`。本文描述已经落地的事件门禁形状；提供方的版本守卫可选（省略即无条件裸提供方）。
 
-## 提供方契约
+## 提供方约定
 
 `@deepseek-ai/dsh-fs` 收缩为提供方文本 IO 加受保护的文本变更：
 
@@ -65,9 +65,9 @@ type FsWriteIntent =
 
 这是一个*文本存储* seam，刻意比字节级 fsspec（`cat`/`open` 返回原始字节）高半个层次。UTF-8 解码、二进制/NUL 拒绝、受保护的全文件写入和受保护的字面文本编辑都在提供方内完成，因此策略层从不接触原始字节、不重新实现跨分片解码、也不将陈旧检查与变更临界区分离。面向模型的概念仍然不下沉到提供方：行窗口、带行号的行、渲染的页脚、观测状态存储都不会泄漏下去。
 
-从 `dsh-fs` 删除：`readPage`、`FsExpectation`、`FsView`、`FsStateSource`、`FsReadRequest`、`FsTextLine`、行/窗口常量、`formatReadBody` 和 observed-state `WeakMap`。`applyEdit` 由更窄的提供方原语 `editText` 取代，其契约是带版本守卫的字面文本变更，而非策略层读取授权。`FS_PARTIAL_OBSERVATION` 错误码也从 `FsErrorCode` 分类体系中移除：新鲜度授权没有部分/完整之分，因此没有任何路径会抛出它。`FsTargetKey` 和 `FsVersion` 按现有[品牌化 id Agent Note](../architecture/2026-06-20-branded-ids.md) 成为品牌化不透明 id。
+从 `dsh-fs` 删除：`readPage`、`FsExpectation`、`FsView`、`FsStateSource`、`FsReadRequest`、`FsTextLine`、行/窗口常量、`formatReadBody` 和 observed-state `WeakMap`。`applyEdit` 由更窄的提供方原语 `editText` 取代，其约定是带版本守卫的字面文本变更，而非策略层读取授权。`FS_PARTIAL_OBSERVATION` 错误码也从 `FsErrorCode` 分类体系中移除：新鲜度授权没有部分/完整之分，因此没有任何路径会抛出它。`FsTargetKey` 和 `FsVersion` 按现有[品牌化 id Agent Note](../architecture/2026-06-20-branded-ids.md) 成为品牌化不透明 id。
 
-## 策略契约
+## 策略约定
 
 `@deepseek-ai/dsh-fs-policy` 是插件，而非服务：它不注册任何 `ctx.*` 键，也不注入任何内容。它拥有不应位于 `FileSystem` 提供方基类上的写入/编辑新鲜度策略和 observed state（否则沙箱/远程后端会继承不该由其承载的面向模型观察策略）。它通过执行器分派的 `fs/*` 事件门禁贡献该策略。（本 Agent Note 最初提议带有 `read`/`write`/`edit` 方法的具体 `ctx.fileContext` 服务；[事件门禁 Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) 将其细化为本文所述插件，使工具永远不会在方法层与策略耦合。）
 
@@ -81,7 +81,7 @@ type FsWriteIntent =
 
 该插件不做任何文件系统 I/O：「你是否观测过此文件？」是一次 `WeakMap` 查找，而「你读取的版本是否仍然是当前版本？」在 `ctx.fs.editText`/`writeText` 内部、与执行变更相同的原子锁中决定——插件只提供 `vObserved` 作为基础。
 
-## 工具契约
+## 工具约定
 
 `dsh-tool-fs` 保持相同的 schema 和提示词表面。`read` 仍然暴露 `file_path`、`offset` 和 `limit`；`write` 和 `edit` 不变。它是执行器：验证模型参数，通过 `ctx.fs` 直接读取/写入/编辑，拥有行窗口化和结果渲染（`N: text`、页脚、`<path>/<content>` 封装），并分发 `fs/*` 事件。
 
@@ -109,7 +109,7 @@ type FsWriteIntent =
 
 ## 验证
 
-`dsh-fs` 精确暴露 `resolve`/`stat`/`readText`/`streamText`/`writeText`/`editText`（`stat` 返回 `FsInfo | undefined`，`writeText` 接受 `FsWriteIntent`），已删除的类型/原语不再存在；`dsh-fs-local` 不包含行、视图或 `formatReadBody` 逻辑；面向模型的 schema 保持逐字节不变。测试固定了以下行为：窗口化读取授权对未变文件的后续编辑；基于陈旧读取的编辑在尝试字面匹配之前报告 `FS_STALE_VERSION`；版本 CAS 行为得以保留；观测契约成立（`read` 工具的读取记录观测状态；直接 `ctx.fs` 读取不记录）；`dsh-fs-policy` 具有 HMR（热模块替换）/dispose（资源释放）测试覆盖。
+`dsh-fs` 精确暴露 `resolve`/`stat`/`readText`/`streamText`/`writeText`/`editText`（`stat` 返回 `FsInfo | undefined`，`writeText` 接受 `FsWriteIntent`），已删除的类型/原语不再存在；`dsh-fs-local` 不包含行、视图或 `formatReadBody` 逻辑；面向模型的 schema 保持逐字节不变。测试固定了以下行为：窗口化读取授权对未变文件的后续编辑；基于陈旧读取的编辑在尝试字面匹配之前报告 `FS_STALE_VERSION`；版本 CAS 行为得以保留；观测约定成立（`read` 工具的读取记录观测状态；直接 `ctx.fs` 读取不记录）；`dsh-fs-policy` 具有 HMR（热模块替换）/dispose（资源释放）测试覆盖。
 
 ## 后续扩展
 
@@ -126,5 +126,5 @@ type FsWriteIntent =
 - 新增第四个 fs 包和一个新的插件层。这是有意为之：它是此前推迟的策略层，而非第二个抽象后端 seam。
 - 直接使用 `ctx.fs` 会绕过策略：直接 `ctx.fs.readText` 不发出 `fs/observed`，因此在默认策略下，后续 `edit` 会以 `FS_NOT_OBSERVED` 拒绝，直到通过 `read` 工具读取该文件。这一失败是显式且有文档记录的。
 - 大文件行窗口化从后端移至 `dsh-tool-fs` 中的 `read` 工具；文本解码和二进制拒绝留在 `ctx.fs.streamText` 中，因此这只是窗口化逻辑的迁移，而非第二套文本 IO 实现。
-- 将 `editText` 保留在提供方 seam 上意味着每个后端都必须实现字面替换契约。这是有意为之：该操作不是纯存储，但陈旧守卫 + 字面匹配 + 原子重写是必须保持在一起的单元，以确保正确的错误归因和并发行为。该契约应保持窄且仅限文本，以便未来后端可以原生实现或通过全文件重写实现。
+- 将 `editText` 保留在提供方 seam 上意味着每个后端都必须实现字面替换约定。这是有意为之：该操作不是纯存储，但陈旧守卫 + 字面匹配 + 原子重写是必须保持在一起的单元，以确保正确的错误归因和并发行为。该约定应保持窄且仅限文本，以便未来后端可以原生实现或通过全文件重写实现。
 - 新鲜度允许在窗口化读取后进行全文件 `write`。这比旧的视图检查更弱，但避免了大文件无法编辑的问题；提示词引导仍然不鼓励盲目的全文件替换。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
index be9546102e..6a77e7a95a 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
 2026-07-04-tighten-hook-protocol-contract.md: a67d0e8447e36516006e57051581c03877c1ba12
-2026-07-04-tighten-hook-protocol-contract.zh.md: 638455d89923d0636483c8e8f39fb0613daa1376
+2026-07-04-tighten-hook-protocol-contract.zh.md: b57a8da8d9f0f921b69d0b63ad5c655eb47f5967
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
index 638455d899..b57a8da8d9 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 收紧 hook-protocol 契约——dialect、被丢弃的字段、双重默认值与 lib 拥有的 `hook/result` 语义
+# Agent Note: 收紧 hook-protocol 约定——dialect、被丢弃的字段、双重默认值与 lib 拥有的 `hook/result` 语义
 
 Status: implemented
 
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`dsh-hook-protocol`/bridge 契约中有四部分没有遵守 [subagent observe/enrich Agent Note](../../archived/feature/2026-06-30-subagent-observe-enrich.md)记下的准则——后者因缺少消费方而删除 `agentType` 生命周期字段，以下各项没有通过同一检验：
+`dsh-hook-protocol`/bridge 约定中有四部分没有遵守 [subagent observe/enrich Agent Note](../../archived/feature/2026-06-30-subagent-observe-enrich.md)记下的准则——后者因缺少消费方而删除 `agentType` 生命周期字段，以下各项没有通过同一检验：
 
 1. **`HookDialect` 的 `'native'` 变体**（`packages/hooks/hook-protocol/src/types.ts`）没有生产者——bridge 会标记 `'claude'` 和 `'codex'`；所有位置中唯一构造 `'native'` 的是该库自己的单元测试。字段自身的 JSDoc 将 `dialect` 定义为“运行它的 bridge”，而 native 不是 bridge：[拦截 seam Agent Note](../feature/2026-06-30-interception-seams.md) 记载 native 钩子不是一个包，并且“native 插件无需持久钩子日志即可使用类型化 Decision”；旗舰 native 插件实践示例恰好断言了这一点（完全没有 `hook/*` 事件）。
 2. **`HookOutput.suppressOutput`**（同一文件）被 codec 解析后在所有路径上均被丢弃：没有 bridge 分支处理它、没有合并 fold、没有 warn、没有 deferred-list 行——在所有「被解析但未兑现」的同类字段中它是唯一没有明确延期声明的（`updatedInput` → 一条 warn 日志加 [pre-tool-input-rewrite 提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)；`systemMessage` → 一条 warn 日志加 README deferred 行；`continue`/`stopReason` → 一个 `TODO(hook-continue-false)` 锚点加 `'stop'` decision 记录）。从结构上看根本无物可抑制：钩子 stdout 从不进入任何 transcript（文本记录）；上下文仅通过 `additionalContext` 流入，日志也只记录 `decision`/`stderrSummary`。因此，钩子作者设置 `suppressOutput: true` 得到的是无声的空操作，且无任何警告。
diff --git a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
index 1a4259e08c..4edba8fd79 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md
 2026-07-12-simplify-session-log-representation.md: a40f4013a97a9c940012dbb37d59beb2faf8fb22
-2026-07-12-simplify-session-log-representation.zh.md: 30808a4eff83b32bd0c47cc6e6cb211f2222b363
+2026-07-12-simplify-session-log-representation.zh.md: c4393511e1a78edacf60bc54a764721ad50e4d9d
diff --git a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
index 30808a4eff..c4393511e1 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 `SurfaceManager` 同时在数组、seq map 和可变 `prev`/`next` 链接中存储相同顺序。生产代码从不读取任一链接：compact 的工具配对 balance 根据按 surface 顺序缓存的每个切点 balance 作答。替换已经使用 `indexOf`，因此链接并未使其主导操作成为常数时间。使用线性替换查找的 seq 数组具有相同的渐近替换成本，却只有一种表示需要验证。
 
-请求头子系统实现了一套自定义的系统/工具增量编解码器和传输决策层，尽管其契约声明增量只是编码优化，而非可重建性要求。在每个 agent loop（智能体循环）实例边界保留初始/恢复的完整快照，然后在该实例的组装头发生变化时写入一条规范的完整 `request/header`，即可保留回放能力，同时删除 `SystemDelta`、`ToolsDelta`、往返回退逻辑以及持久化的 `request/header-delta` 变体。编解码器专属的词汇随编解码器一起消失，并非因为其各分支本身无效。
+请求头子系统实现了一套自定义的系统/工具增量编解码器和传输决策层，尽管其约定声明增量只是编码优化，而非可重建性要求。在每个 agent loop（智能体循环）实例边界保留初始/恢复的完整快照，然后在该实例的组装头发生变化时写入一条规范的完整 `request/header`，即可保留回放能力，同时删除 `SystemDelta`、`ToolsDelta`、往返回退逻辑以及持久化的 `request/header-delta` 变体。编解码器专属的词汇随编解码器一起消失，并非因为其各分支本身无效。
 
 实现保留追加与替换操作的 `sourceEventSeqs`、崩溃修复的溯源信息，以及所有 `SessionStartSource` 变体，因为这些字段承担审计/拦截职责，当前没有读取方并不能推翻这一点。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
index af534f7b4b..dc75549250 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
 2026-07-17-one-send-one-turn.md: 834eb2b3aace0a0aa5f86f483e7b7d7aabbe467e
-2026-07-17-one-send-one-turn.zh.md: d05ce63c404ce4d10ac098e3a3c9617443cc278b
+2026-07-17-one-send-one-turn.zh.md: 5bd2ed0e70766c43b0a0a5d5d4038b39094d5099
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
index d05ce63c40..5bd2ed0e70 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**保留普通 send 的自动批处理，以减少模型调用。** 当消息进入队列的速度超过驱动器的处理速度时，这种做法可以提高吞吐量，但会让轮次边界取决于调度，并让后一条消息在前一轮关闭且到达检查点之前运行。本决策保留可预测的边界，并接受额外调用。未来若要加入批处理功能，必须提供调用方可见的显式契约，并有测量结果作为依据。
+**保留普通 send 的自动批处理，以减少模型调用。** 当消息进入队列的速度超过驱动器的处理速度时，这种做法可以提高吞吐量，但会让轮次边界取决于调度，并让后一条消息在前一轮关闭且到达检查点之前运行。本决策保留可预测的边界，并接受额外调用。未来若要加入批处理功能，必须提供调用方可见的显式约定，并有测量结果作为依据。
 
 ## 验证
 
@@ -42,4 +42,4 @@ Status: implemented
 
 普通轮次的边界可预测：消息 A、B 始终分开，B 只能在 A 关闭并到达检查点后运行。调用方仍然拿不到逐次 send 的完成句柄；待处理消息可通过其 `MessageId` 移除，面向整个 agent 的取消可以丢弃整个尚未启动的队尾，而状态与完全停稳仍是面向整个 agent 的观察。
 
-代价是模型请求和检查点都会增加。繁忙队列可能需要更长时间才能清空；如果生产方持续提交消息，队列也可能增长。只有建立显式且经过测量的契约后，才能重新引入普通 send 批处理。
+代价是模型请求和检查点都会增加。繁忙队列可能需要更长时间才能清空；如果生产方持续提交消息，队列也可能增长。只有建立显式且经过测量的约定后，才能重新引入普通 send 批处理。
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
index a21ac5cfe9..dcef1b190f 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md
 2026-07-20-remove-stdio-and-echo-agents.md: 256e626f4ff41016d0227eef7cc3e4e51e15058b
-2026-07-20-remove-stdio-and-echo-agents.zh.md: bb7a2abd8be73ac3ea089121592b3f26162bf619
+2026-07-20-remove-stdio-and-echo-agents.zh.md: 013135eff5d1dbbc570561e70c751ff4de289989
diff --git a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
index bb7a2abd8b..013135eff5 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md
@@ -28,14 +28,14 @@ SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换
 
 ## 验证
 
-TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果契约和工具调用契约。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
+TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果约定和工具调用约定。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
 
-构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口，包括输出和无效参数。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）契约。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
+构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口，包括输出和无效参数。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）约定。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
 
 ## 曾考虑的替代方案
 
-- **仅为 pipe 保留面向行 agent**：不予采纳，因为 Headless 已提供有界任务契约、格式纯净的 stdout、持久完成边界和进程退出状态。
-- **将 readline helper 作为包保留、折叠或提升**：不予采纳，因为它只有一个 app 消费方，并不存在可独立替换的契约。将它折叠进 stdio app 虽然移除了没有正当理由的支撑包边界，却仍保留了重复产品；将来要重新引入这个包，独立的面向行 UI 必须先有真正的第二个消费方。
+- **仅为 pipe 保留面向行 agent**：不予采纳，因为 Headless 已提供有界任务约定、格式纯净的 stdout、持久完成边界和进程退出状态。
+- **将 readline helper 作为包保留、折叠或提升**：不予采纳，因为它只有一个 app 消费方，并不存在可独立替换的约定。将它折叠进 stdio app 虽然移除了没有正当理由的支撑包边界，却仍保留了重复产品；将来要重新引入这个包，独立的面向行 UI 必须先有真正的第二个消费方。
 - **保留 Echo 作为无密钥快速上手路径**：不予采纳，因为首次产品体验应使用真实模型和受支持的 coding agent，而不是带专用工具的脚本化适配器。
 - **只为 CI 演示命令保留 Echo**：不予采纳，因为由测试持有的 Headless fixture 可以覆盖相同的 Loader 和构建产物边界，无需保留 mock 产品叶节点。
 - **移除所有 stdio 或 mock 机制**：不予采纳，因为分帧协议、进程 I/O 和确定性测试适配器是独立基础设施，并不是被移除的 agent。
diff --git a/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.i18n.yaml
index d6fa35a75d..b6c8b3dc89 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md
 2026-07-20-unwrap-injected-content-envelopes.md: aff458d76027bf5518497328ee1bd852869793b9
-2026-07-20-unwrap-injected-content-envelopes.zh.md: 59cbd823da3305185a05c79207fbd7b702a11fba
+2026-07-20-unwrap-injected-content-envelopes.zh.md: 727ce5e490b6115ad0b3ce383059aabcffd4c7b0
diff --git a/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.zh.md b/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.zh.md
index 59cbd823da..727ce5e490 100644
--- a/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.zh.md
@@ -25,7 +25,7 @@ Status: implemented
 
 - **保留 `<context>` 封套，只对 steering（中途引导）去封套** —— 会为一个没有模型会读的框架位保留 `ContextEnvelope`/`envelope` 机制，并保留主要生产方本就退出的那种不一致。
 - **仅对插件来源的内容保留 envelope 字段** —— 会按 `source.kind` 把一条投影拆成两条，却没有观察到任何收益；插件引导 agent 时（钩子桥接器的轮次续行原因）同样希望指令被遵从，而不是被贴标签。
-- **把去封套的逻辑移入适配器** —— 规范投影就是模型可见契约（「模型可见 ⟺ 已记录」）；让各适配器在框架上各行其是，会使派生的 transcript 依赖于适配器。调用方确实想要的框架应放进调用方自己的内容里，而不是适配器。
+- **把去封套的逻辑移入适配器** —— 规范投影就是模型可见约定（「模型可见 ⟺ 已记录」）；让各适配器在框架上各行其是，会使派生的 transcript 依赖于适配器。调用方确实想要的框架应放进调用方自己的内容里，而不是适配器。
 
 ## 结果
 
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
index b6ef95a950..9c7359d8d6 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
 2026-07-22-plan-specific-collaboration-state.md: d139f3d861244c80acfb604d17172461bbf0cd57
-2026-07-22-plan-specific-collaboration-state.zh.md: dbf90357e4c4967d9665533c9abd2b4e1838da27
+2026-07-22-plan-specific-collaboration-state.zh.md: 3d51b8fc31196efca49693050258c323ff3af843
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
index dbf90357e4..3d51b8fc31 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
@@ -22,7 +22,7 @@ Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/`
 
 沙箱模式与审批策略仍是彼此独立的强制约束轴。Plan mode 既不读取也不写入二者；此次简化也没有为这些概念引入共享基类型、注册表或预设抽象。
 
-### 边界与模型契约
+### 边界与模型约定
 
 `plan/mode` 仅记录到日志且不进入表层，因此恢复、fork 和压缩（compaction）都能恢复该状态，无需实时镜像。spawn 出的 agent（智能体）初始处于未激活状态，因为创建时没有 plan 选项。待生效的用户选择会在初始或续步 pre-step 时，或在请求恢复重试时，于受影响的请求组装前写入日志；持久追加失败会让意图保持待定，留到后续边界处理。
 
@@ -55,7 +55,7 @@ Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/`
 
 **按 plan 专用名称允许列表或全局策略栈筛选工具。** 不予采纳，因为可变性是每个工具自身的属性，包括未来工具和 MCP 工具，而不应由每个 plan 部署维护一份列表。只有出现具体消费方后，effects 元数据才能建立共享策略；在此之前，plan mode 是引导机制，不是安全边界。
 
-**通过审批 seam 或普通文本完成评审。** 不予采纳，因为计划评审不是权限决策，需要原样的计划产物和纠正性自由文本，而且必须以已记录的工具调用作为结构化转换。用户交互 seam 提供了这项契约。
+**通过审批 seam 或普通文本完成评审。** 不予采纳，因为计划评审不是权限决策，需要原样的计划产物和纠正性自由文本，而且必须以已记录的工具调用作为结构化转换。用户交互 seam 提供了这项约定。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
index 3889001fe3..736a9aee5f 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
 2026-07-23-acp-automation-only-protocol.md: 0fe2fc27a963d21e8a24c1682359ab3bc9e7af48
-2026-07-23-acp-automation-only-protocol.zh.md: bd21696c40811adeb8b8883ef57c30f9321f4ea4
+2026-07-23-acp-automation-only-protocol.zh.md: d161f22672b1c1a1db131a58b4b8da531930ab97
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
index bd21696c40..d161f22672 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
@@ -34,9 +34,9 @@ ACP 快照套件仍会启动组装后的 ACP 示例，并保留用于锁定后
 
 ## 考虑过的替代方案
 
-**在 Web 达到同等能力前，继续将 ACP 作为编辑器 UI。** 不予采用，因为这会留下两套需要演进的交互契约，并使编辑器约定继续存在于自动化边界中。
+**在 Web 达到同等能力前，继续将 ACP 作为编辑器 UI。** 不予采用，因为这会留下两套需要演进的交互约定，并使编辑器约定继续存在于自动化边界中。
 
-**通过严格的 seam 保留早期编辑器桥接层。** 不予采用，尽管该桥接层正确使用了接口服务、工具自有的 render intent、审批与用户交互应答者、harness 自有执行，以及保持 stdout 纯净的组装。其终端卡片是经过能力门控、仅用于展示的 Zed `_meta` 投影，并提供文本回退，而非使用 ACP `terminal/create`，因此 shell 执行从未离开 harness。该投影从稳定的逐调用 id 派生每个展示用终端 id，以避免冲突；由于纯结果展示器接收的是内容块，而不是结构化退出信息，它会从渲染后的状态标记中恢复退出码或信号。标记往返测试和显式的无能力 `console` 回退测试锁定了这两项契约。这些边界保持一致，却无法让编辑器卡片、会话导航、配置选择器和面向人类的询问成为自动化协议应有的职责。
+**通过严格的 seam 保留早期编辑器桥接层。** 不予采用，尽管该桥接层正确使用了接口服务、工具自有的 render intent、审批与用户交互应答者、harness 自有执行，以及保持 stdout 纯净的组装。其终端卡片是经过能力门控、仅用于展示的 Zed `_meta` 投影，并提供文本回退，而非使用 ACP `terminal/create`，因此 shell 执行从未离开 harness。该投影从稳定的逐调用 id 派生每个展示用终端 id，以避免冲突；由于纯结果展示器接收的是内容块，而不是结构化退出信息，它会从渲染后的状态标记中恢复退出码或信号。标记往返测试和显式的无能力 `console` 回退测试锁定了这两项约定。这些边界保持一致，却无法让编辑器卡片、会话导航、配置选择器和面向人类的询问成为自动化协议应有的职责。
 
 **用私有 subagent RPC 替换 ACP。** 不予采用，因为 ACP 已经提供类型化、可互操作的进程协议，并由跨进程 subagent 后端使用。
 
@@ -46,7 +46,7 @@ ACP 快照套件仍会启动组装后的 ACP 示例，并保留用于锁定后
 
 ## 结果
 
-ACP 具有适合 agent 与自动化的精简契约，而 TUI 和 Web 拥有面向人类的交互与展示。该包注入的服务、依赖、协议分支和生命周期状态更少，也不再将自身定位为通用编辑器入口。
+ACP 具有适合 agent 与自动化的精简约定，而 TUI 和 Web 拥有面向人类的交互与展示。该包注入的服务、依赖、协议分支和生命周期状态更少，也不再将自身定位为通用编辑器入口。
 
 自动化客户端收到完整的已提交文本，而不是 token 增量或结构化工具 UI。当它们需要推理、工具跟踪信息、标题或更丰富的状态时，需要查看持久日志或其他 API。只支持全新会话也意味着，需要浏览持久会话或恢复会话的调用方必须使用 host API，而不是 ACP。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
index 1bd3e02df3..33051c7a3d 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
 2026-07-23-collapse-persistence-flush-state.md: 2801079e5b322d076eced3a0113e7958d9b4c3b9
-2026-07-23-collapse-persistence-flush-state.zh.md: d5b02ebc545a32fbdb44feed04ec2afbbafeff4b
+2026-07-23-collapse-persistence-flush-state.zh.md: 48896c7080ae28174e259318869c65b48b13418e
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
index d5b02ebc54..48896c7080 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
@@ -35,12 +35,12 @@ Status: implemented
 ## 验证
 
 - 针对控制器的测试使用假时钟证明固定窗口不会重置，随后阻塞第一次追加，在该次写入期间接纳另一个事件，并在不调用 `session/flush` 的情况下观测到自动执行的第二个持久批次。
-- 共享协调器契约仍覆盖内存、JSONL 和 SQLite 后端上的活跃会话接管、冲突、崩溃修复，以及会话和后端的资源释放。
+- 共享协调器约定仍覆盖内存、JSONL 和 SQLite 后端上的活跃会话接管、冲突、崩溃修复，以及会话和后端的资源释放。
 - 失败和资源销毁测试会让写入失败的批次保持待处理，在关闭前重试这些批次，并证明尚在执行的控制器会延迟后端关闭。
-- 共享后端契约会持久化一个仍打开的活跃轮次，证明 `load` 会拒绝且不会写入合成闭合事件，随后完成该轮次并让其所有者退役，最后重新加载完全相同的已完成轮次。
+- 共享后端约定会持久化一个仍打开的活跃轮次，证明 `load` 会拒绝且不会写入合成闭合事件，随后完成该轮次并让其所有者退役，最后重新加载完全相同的已完成轮次。
 - AgentLoop 回归测试让 `resume()` 与一个仍打开的活跃轮次发生竞态，并证明原有的 agent（智能体）仍能完成该轮次并将其持久化，其间不会注入 `interrupted` 边界。
 - 一个受控后端会阻塞 `loadStored`，在修复操作持有标识占用期间尝试发布同 id 会话，并证明回滚不会留下残留控制器，之后可以成功恢复一个闭合会话。
-- 无所有者认领契约会为活跃 `Session` 设置不同的 `createdAt`，并证明活跃加载和之后的冷态加载均返回最初存储的标头。
+- 无所有者认领约定会为活跃 `Session` 设置不同的 `createdAt`，并证明活跃加载和之后的冷态加载均返回最初存储的标头。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
index 5067b15402..611d20bfe2 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
 2026-07-24-agent-loop-observable-state-machine.md: b1773fdf7fd3bcbea9c6b9a4a0ce37c715bce4ca
-2026-07-24-agent-loop-observable-state-machine.zh.md: f47e5901ec97a44efa00cf79ef8ce52fdcac9878
+2026-07-24-agent-loop-observable-state-machine.zh.md: ef44e9c058d165bfbbe226e9d0fca1e6f8072f53
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
index f47e5901ec..ef44e9c058 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
@@ -14,7 +14,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 
 ## 决策
 
-公开契约暴露四个正交的状态维度：
+公开约定暴露四个正交的状态维度：
 
 - 注册生命周期是从 `agent/created` 到 `agent/disposed` 的区间。dispose（资源释放）是注册表的终止边界，而不是一种 `AgentStatus`。
 - agent 整体活动状态为 `AgentStatus = 'idle' | 'running'`。连续多个轮次可以共用同一个 `running` 区间。
@@ -31,7 +31,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 
 ## 考虑过的替代方案
 
-**保留细粒度事件序列。** 这样可以为每个内部阶段保留专用拦截点，包括仅用于请求的前缀、助手消息改写、步骤后处理、轮次内请求恢复以及终止覆盖。但这也会使循环的私有执行顺序成为永久的公开契约，并允许相互重叠的 seam 表达彼此冲突的决策。当前决策接受这些拦截点的缺失，以换取每项受支持的扩展职责仅对应一个边界。
+**保留细粒度事件序列。** 这样可以为每个内部阶段保留专用拦截点，包括仅用于请求的前缀、助手消息改写、步骤后处理、轮次内请求恢复以及终止覆盖。但这也会使循环的私有执行顺序成为永久的公开约定，并允许相互重叠的 seam 表达彼此冲突的决策。当前决策接受这些拦截点的缺失，以换取每项受支持的扩展职责仅对应一个边界。
 
 **将 dispose 表示为第三种 `AgentStatus`。** 这样会让仍被持有的句柄得到一个终止状态值，但也会重复表达 `agent/disposed` 已经体现的注册表生命周期。当前决策让 `AgentStatus` 只表示 agent 存续期间的活动状态，并将注册生命周期作为独立维度。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
index 2fb2e4cf9b..c9735b903f 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
 2026-07-26-merge-subagent-control-service.md: ae7214f7c8c28f8a4b7d754839acbc938270f125
-2026-07-26-merge-subagent-control-service.zh.md: dc05e03c5d38df0317291aee2ffc1395dab8e362
+2026-07-26-merge-subagent-control-service.zh.md: 85a7f62ce789d80dc38ca52017554aa2c2921599
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
index dc05e03c5d..85a7f62ce7 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 ## 问题
 
-可继续 child 的编排最初位于原始 `ctx.subagents` 提供方 seam 之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排契约。实践中，两个服务属于同一组功能，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
+可继续 child 的编排最初位于原始 `ctx.subagents` 提供方 seam 之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排约定。实践中，两个服务属于同一组功能，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
 
 ## 决策
 
@@ -18,7 +18,7 @@ Status: implemented
 
 继续执行的实现仍是内部管理器，不会扩展提供方注册表的核心状态。`SubagentService` 通过 `ctx.inject(['tasks', 'agents'], ...)` 创建该管理器，因此注入的 Cordis child fiber 拥有自身的 Task 完成监听器和拆卸 effect。加载提供方注册表不要求 Task 或持久化。只有 Task 和 Agent 可用时，该管理器才会存在；每项继续执行操作都在需要持久性时解析会话持久化服务。dispose（资源释放）该 fiber 会先取消并结算活跃的继续执行，再释放其关联。
 
-`startContinuable` 与底层 `start` 保持分离，因为二者的所有权与时序契约不同：前者分配持久化 child id、创建 Task，并同步返回两个 id，而启动过程继续在 Task 内运行；底层 `start` 则等待提供方发布，并移交一个由持有方负责的 run。若通过标志或返回值联合类型将该方法并入 `start`，会扩大底层契约，改动反而多于保留现有的显式入口。
+`startContinuable` 与底层 `start` 保持分离，因为二者的所有权与时序约定不同：前者分配持久化 child id、创建 Task，并同步返回两个 id，而启动过程继续在 Task 内运行；底层 `start` 则等待提供方发布，并移交一个由持有方负责的 run。若通过标志或返回值联合类型将该方法并入 `start`，会扩大底层约定，改动反而多于保留现有的显式入口。
 
 每个 `@deepseek-ai/dsh-tool-subagent` 实例都会选择 `backgroundMode: 'one-shot' | 'continuable'`，默认值为 `one-shot`。这项配置表示策略；`provider.resume` 只用于检查所配置的可继续模式是否受提供方支持。因此，可恢复的提供方仍可执行一次性后台工作。`send_message` 工具是独立适配器：加载或省略该工具既不会启用也不会禁用 `startContinuable`。
 
@@ -30,7 +30,7 @@ Status: implemented
 
 **注册继续执行访问入口，或检查后续操作工具。** 注册表可以告诉委派工具继续执行接口是否存在，但启动具备持久性的工作不需要任何后续操作适配器。这样的注册表会把 UI 组合编码进执行策略，并以另一个名称重新建立插件间依赖关系。
 
-**将底层启动与可继续启动合并为一个方法。** `start` 上的标志会使该方法返回已发布的一次性 run，或立即返回 Task 和 child 标识，从而削弱简单的所有权边界。保留 `startContinuable` 改动更小，也能明确保留两项契约。
+**将底层启动与可继续启动合并为一个方法。** `start` 上的标志会使该方法返回已发布的一次性 run，或立即返回 Task 和 child 标识，从而削弱简单的所有权边界。保留 `startContinuable` 改动更小，也能明确保留两项约定。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.i18n.yaml
index 6c6ead17b7..e386775842 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.md
 2026-07-28-local-json-tree-renderer.md: 5e8e6d6968319ada53e65a48e9e03b297dc0141c
-2026-07-28-local-json-tree-renderer.zh.md: f3a9faa5f9de264d0b7eadac631f7f4afff166b2
+2026-07-28-local-json-tree-renderer.zh.md: 1d491af9a76f1be1c89859e26c058d9460580095
diff --git a/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.zh.md b/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.zh.md
index f3a9faa5f9..1d491af9a7 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-28-local-json-tree-renderer.zh.md
@@ -13,19 +13,19 @@ Status: implemented
 `dsh-client-ui-primitives` 中的 `JsonTree` 自行负责递归呈现。
 
 - 每个渲染行都直接接收自身的值和属性路径。递归时，对象键和数组索引会附加到路径末尾，因此复制操作无需再从 DOM 渲染文本中反向还原应用数据。
-- 可展开行在本地渲染紧凑预览，仅在展开时挂载子行。`expandTopLevel` 可选择固定展开的括号框架或可折叠根节点，而不改变组件的公开契约。
+- 可展开行在本地渲染紧凑预览，仅在展开时挂载子行。`expandTopLevel` 可选择固定展开的括号框架或可折叠根节点，而不改变组件的公开约定。
 - 树中所有可见节点仅保留一个可通过 Tab 键聚焦的展开控件。使用指针激活控件后，该控件会成为 Tab 键焦点位置；上、下方向键循环移动焦点，左、右方向键折叠或展开当前焦点所在节点。
 - `react-json-view-lite` 不在 `dsh-client-ui-primitives` 的依赖项中，也没有 pnpm 补丁。针对性组件测试锁定预览、展开、键盘焦点和数组复制路径。
 
 ## 曾考虑的替代方案
 
-**保留发布文件补丁。** 不予采纳：应用专用的渲染逻辑和数组标识契约仍会隐藏在生成的第三方文件中；每次更新依赖，都必须评审一个没有配套源码映射的 fork。
+**保留发布文件补丁。** 不予采纳：应用专用的渲染逻辑和数组标识约定仍会隐藏在生成的第三方文件中；每次更新依赖，都必须评审一个没有配套源码映射的 fork。
 
 **直接使用不提供预览的上游渲染器。** 不予采纳：`{…}` 和 `[…]` 会丢失轨迹检查器扫读时所需的紧凑载荷上下文。
 
 **渲染后注入预览和行元数据。** 不予采纳：Effect 或 MutationObserver 仍会依赖同一套私有 DOM 结构，同时使 React 和命令式变更机制分别负责同一行的不同部分。
 
-**采用更大型的 JSON 查看器。** 不予采纳：编辑、搜索与主题系统不在当前只读契约范围内；扩大依赖范围也无法去除检查器专用的复制和布局代码。
+**采用更大型的 JSON 查看器。** 不予采纳：编辑、搜索与主题系统不在当前只读约定范围内；扩大依赖范围也无法去除检查器专用的复制和布局代码。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
index 3245b307e5..53c32d5278 100644
--- a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-30-private-agent-send.md
 2026-07-30-private-agent-send.md: 43353c309f98eab1bff91b8fbe0c9cfaa2bbc69b
-2026-07-30-private-agent-send.zh.md: 49f7c999ec60c7305bdca570a4d59039c7c1923b
+2026-07-30-private-agent-send.zh.md: 52ead82bb4e39a39e6c578ddb4311d1bae4afe69
diff --git a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
index 49f7c999ec..52ead82bb4 100644
--- a/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-30-private-agent-send.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-`Agent` 将 `followup()`、`steer()` 和 `inject()` 作为完整的交付契约公开。`ReactLoopAgent` 保留私有的 `send()` 辅助方法，供这三个方法共用路由机制；`dsh-agent` 不再导出 `SendTarget` 和 `SendOptions`。
+`Agent` 将 `followup()`、`steer()` 和 `inject()` 作为完整的交付约定公开。`ReactLoopAgent` 保留私有的 `send()` 辅助方法，供这三个方法共用路由机制；`dsh-agent` 不再导出 `SendTarget` 和 `SendOptions`。
 
 公开接口无法在不唤醒驱动器的情况下让一个轮次入队。`followup()` 始终请求执行，`steer()` 请求最近的步骤，`inject()` 则提供面向模型的上下文而不请求执行。本决策部分取代[统一交付决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)中关于公开接口的内容，同时保留其内部路由与统一的 `user/message` 表示。
 
@@ -22,6 +22,6 @@ Status: implemented
 
 ## 后果
 
-插件从三种语义操作中选择，不再自行构造路由选项。其他驱动器和结构型测试替身只需实现更小的契约，Cordis API 目录也不再列出 `send`、`SendTarget` 或 `SendOptions`。
+插件从三种语义操作中选择，不再自行构造路由选项。其他驱动器和结构型测试替身只需实现更小的约定，Cordis API 目录也不再列出 `send`、`SendTarget` 或 `SendOptions`。
 
 只有出现明确的消费方并定义显式的生命周期语义后，才能恢复已移除的无唤醒排队能力。`cancel({ keepInbox: true })` 仍会保留已通过受支持交付路径进入待处理状态的工作。
diff --git a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
index f690cc7a95..1b40493eae 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.md
 2026-07-31-capability-neutral-sandbox-policy-context.md: d45c6c652fb7a061c2f92b7e03c41cce39da2a30
-2026-07-31-capability-neutral-sandbox-policy-context.zh.md: 9a1bb7a13d934826dddf89b409b25ba892a31ea3
+2026-07-31-capability-neutral-sandbox-policy-context.zh.md: c5aa9cc1f03fa83a3b6d9606afc30f6135681ae0
diff --git a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
index 9a1bb7a13d..c5aa9cc1f0 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-capability-neutral-sandbox-policy-context.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 当前策略上下文最初通过受强制执行家族与可升权家族两个独立注册表来映射运行时组合。后端、工具与示例中的六个调用点会贡献 `filesystem`、`bash` 或 `terminal`；策略服务保留 token 集合，以便独立释放各项注册，对两个注册表的内容求交集并排序，在每次生命周期变化时使提示词组装失效，并且需要测试覆盖所有家族组合。
 
-这份清单既不是说明文件策略所必需的，也不能作为模型可见能力的权威依据。后端贡献可能声明某个家族，而该家族面向模型的工具并不存在，或被请求作用域隐藏；工具 schema 已经向模型准确说明哪些操作可用。因此，为了维护一句近似的英文说明，注册表扩大了公开服务与生命周期契约。
+这份清单既不是说明文件策略所必需的，也不能作为模型可见能力的权威依据。后端贡献可能声明某个家族，而该家族面向模型的工具并不存在，或被请求作用域隐藏；工具 schema 已经向模型准确说明哪些操作可用。因此，为了维护一句近似的英文说明，注册表扩大了公开服务与生命周期约定。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
index 1c0cc5644d..77f0bb98ae 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
 2026-07-31-one-route-to-add-a-workspace.md: 5d002265b5eb1178bb1dbc7bd17f8b364d9b9856
-2026-07-31-one-route-to-add-a-workspace.zh.md: 0a59d3a505eb921b4ec980abaefedfcad8a3c294
+2026-07-31-one-route-to-add-a-workspace.zh.md: 9e0940e2a59fac907f023d6433f0056b99c41a60
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
index 0a59d3a505..9e0940e2a5 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
@@ -27,7 +27,7 @@ Status: implemented
 
 ## Wire and CLI residue
 
-Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端一段同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一契约。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端 seam 与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
+Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端一段同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一约定。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端 seam 与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
 
 ## Testing
 
@@ -52,6 +52,6 @@ Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root`
 ## Consequences
 
 - 从 UI 已无法在操作者选定目录之外创建 Workspace；服务端控制的 `--workspace-root` 目标曾是约束新 workspace 文件夹落点的唯一手段，现在没有替代品。需要该约束的部署必须有意识地重新引入它。
-- 仅存的这条路径会浏览宿主机文件系统，因此选择器的可达范围现在是整台宿主机，而非一个配置好的父目录。这本就是浏览占用者的契约，本改动使它成为唯一的契约。
+- 仅存的这条路径会浏览宿主机文件系统，因此选择器的可达范围现在是整台宿主机，而非一个配置好的父目录。这本就是浏览占用者的约定，本改动使它成为唯一的约定。
 - 挂载了 `ui-workspace` 但未挂任何 directory-picker 包的组合，已完全无法添加 Workspace；现在它通过不渲染按钮来说明这一点，而不是提供一个按名称创建的兜底。
-- 主视觉区的 chip 仍声明 `aria-haspopup="menu"`，而直接拉起的路径实际弹出的是对话框。要让它如实，需要把流程的展示方式经 `conversation.hero.workspace` 的 owner 契约上报——决定权在流程，播报权在 chip，两者分属不同的包——因此这被列为一项具名的后续工作，而不是一处无声的不一致。本次新增的侧边栏按钮完全不作任何 popup 声明。
+- 主视觉区的 chip 仍声明 `aria-haspopup="menu"`，而直接拉起的路径实际弹出的是对话框。要让它如实，需要把流程的展示方式经 `conversation.hero.workspace` 的 owner 约定上报——决定权在流程，播报权在 chip，两者分属不同的包——因此这被列为一项具名的后续工作，而不是一处无声的不一致。本次新增的侧边栏按钮完全不作任何 popup 声明。
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
index cd43c3a27b..9a88d14722 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md
 2026-08-08-remove-cli-demo.md: c1153f5e9fcc89585e926f8f088829c849d1f6c1
-2026-08-08-remove-cli-demo.zh.md: 1f9719b176c05009900a268a5bb2d2d7fcc79df3
+2026-08-08-remove-cli-demo.zh.md: 7f11e0c17a15454b99b32d14ea6eda177f4b01f6
diff --git a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
index 1f9719b176..7f11e0c17a 100644
--- a/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md
@@ -6,9 +6,9 @@ Status: implemented
 
 ## 问题
 
-在 [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出契约、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
+在 [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出约定、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
 
-回放套件仍需要规范会话事件来固定组装后的后端行为。这一测试需求不需要已发布命令或兼容性契约。
+回放套件仍需要规范会话事件来固定组装后的后端行为。这一测试需求不需要已发布命令或兼容性约定。
 
 ## 决策
 
@@ -19,7 +19,7 @@ Status: implemented
 ## 考虑过的替代方案
 
 - **保留 `dsh-cli-demo` 作为 `dsh run` 的别名或包装层。** 不予采纳：第二个 bin 和包会让同一功能继续存在两个可发现的归属方，却没有增加任何能力。
-- **把 JSON 和 stream-JSON 标志移到 `dsh run`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）契约。
+- **把 JSON 和 stream-JSON 标志移到 `dsh run`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）约定。
 - **随包一并删除规范事件快照。** 不予采纳：这些快照固定了模型可见的组装行为，而只检查最终文本的产品验收无法观察这些行为。
 - **保留应用插件，只删除它的 bin。** 不予采纳：隐藏的组装仍会重复显式的 headless profile，并掩盖测试叶节点挂载了哪些服务。
 
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
index e5e6b3d67e..5dc542589f 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
 2026-06-19-acp-snapshot-tests.md: c6e81dc4a51083ed37ad6f837fe7dbb08c212e23
-2026-06-19-acp-snapshot-tests.zh.md: 5a579c3373442dc4cfc7d661ea2f2f398b804dc7
+2026-06-19-acp-snapshot-tests.zh.md: 729e5645b097f8db5b23594e16e48dc5b4cf211f
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
index 5a579c3373..729e5645b0 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 
 `llm-replay` 短路了提供方无关的 `llm/stream` waterfall（瀑布式事件）。`deriveReplayScript()` 在终止的 `finish` 分片处切分已记录的 `assistant/chunk` 事件，并用 `(turn, step)` 变化拒绝前一条未终止的调用。携带 `llmStreamCall: true` 的 `compact/summary` 会在其持久日志位置贡献一次调用：回放根据 `rawOutput` 重建规范块边界，保留已记录的 usage（如有），并提供终止的 `stop`。该标记将这次本地调用与模板摘要或远程摘要区分开；后两者即使保留了 `rawOutput`，也未使用此上下文的适配器。
 
-### 内存中的回放条目遵守完整的 LLM 契约
+### 内存中的回放条目遵守完整的 LLM 约定
 
 `deriveReplayScript` 产出一组 `ReplayEntry`，即回放监听器按位置服务的内存单元：
 
@@ -52,7 +52,7 @@ Status: implemented
 
 快照运行断言**两个**归一化后的表面，因为 harness 的外部表面是不同的：
 
-1. **stdout transcript**——自动化客户端收到的、分帧后的 ACP JSON-RPC 响应与已提交的消息更新。它捕获传输契约的回归，与已提交的 `stdout.expected.jsonl` 比较。
+1. **stdout transcript**——自动化客户端收到的、分帧后的 ACP JSON-RPC 响应与已提交的消息更新。它捕获传输约定的回归，与已提交的 `stdout.expected.jsonl` 比较。
 2. **重新持久化的会话 JSONL**，经过规范化后与 `session.jsonl` 比较。同一 fixture 同时作为回放来源和预期日志。提示词与工具的主体内容会被清理；每种请求头类别由一个场景固定余下的请求头序列。该 pin 默认拥有可读的提示词与工具 schema 伴随文件；当完整的对应序列相同时，也可将另一个 pin 指定为其中任一来源，因此每个不同的伴随文件版本只提交一次。fixture 保护会拒绝重复的伴随文件内容，录制/刷新会拒绝生成不同字节的共享引用方。最初的请求头固定理由保留在[请求头固定 Agent Note](../../archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)中。Override 场景仅从其伴随文件派生模型行为。
 
 两个表面互补：stdout 覆盖精简的自动化协议格式，JSONL 覆盖协议格式有意省略的 loop、工具和 boundary 结构。
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
index 5ef82c77de..36c58755cc 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
 2026-06-22-fork-child-replay-seed-boundary.md: 27db3b768f2503121b0bc8912f9bc0fecb00a10d
-2026-06-22-fork-child-replay-seed-boundary.zh.md: f64fc55fc63e2caa4b50112407b645e6e7f12b0f
+2026-06-22-fork-child-replay-seed-boundary.zh.md: 9e3f7e59394a5160f5ca5db1c9798b2e05f9d2dc
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
index f64fc55fc6..9e3f7e5939 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
@@ -46,4 +46,4 @@ subagent 脚本由 [`deriveReplayScript`](../../../../packages/support/llm-repla
 
 - core 与两个后端新增一个持久化 header 字段；子系统目录（`persistence.md`）在同一变更中更新（其 `SessionHeader` / `CreateSessionOptions` 的 `type-equiv` 块）。
 - 既有的 schema v2 SQLite 数据库在打开时被拒绝（预发布阶段无用户数据）。
-- spawn 回放不变（`seedLength` 为 0）。fork 回放现在将子会话路由到自身的脚本；由 `llm-replay` 测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的分片——推导出的子会话脚本必须排除它，不做 slice 时该用例为红）以及一个持久化往返测试（两个后端，通过共享的 coordinator 契约）。
+- spawn 回放不变（`seedLength` 为 0）。fork 回放现在将子会话路由到自身的脚本；由 `llm-replay` 测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的分片——推导出的子会话脚本必须排除它，不做 slice 时该用例为红）以及一个持久化往返测试（两个后端，通过共享的 coordinator 约定）。
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
index bb1ed0b43b..80395b6359 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
 2026-07-22-cross-platform-test-fixtures.md: 6217aabfdbe8f14f869004c8dafb7e19f4b7443a
-2026-07-22-cross-platform-test-fixtures.zh.md: ce9c65106b904b4c16360c9cb2545b0316bd7120
+2026-07-22-cross-platform-test-fixtures.zh.md: bb6649a19766967e0c2f70272433c1fa2e93f72a
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
index ce9c65106b..bb6649a197 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-测试平台无关行为时，使用宿主的 `node:path` 和 `node:url` API 构造绝对路径与 `file:` URI，再根据契约要求断言原生绝对输出或稳定的工作区相对输出。无效 URI fixture 使用一种在所有受支持平台上都会被 `fileURLToPath()` 拒绝的编码形式。
+测试平台无关行为时，使用宿主的 `node:path` 和 `node:url` API 构造绝对路径与 `file:` URI，再根据约定要求断言原生绝对输出或稳定的工作区相对输出。无效 URI fixture 使用一种在所有受支持平台上都会被 `fileURLToPath()` 拒绝的编码形式。
 
 传输故障测试会注入连接的消息写入器，并传入与真实 Node 流相同的异步写入回调错误。生产写入器仍会把分帧消息写入子进程 stdin。这种方式让真实子进程保持存活，使测试无需触及平台特有的管道句柄，也能确定性地区分传输故障与进程退出。
 
@@ -24,9 +24,9 @@ Status: implemented
 
 **将所有路径和 URI 归一化为 POSIX 字符串。**这会使断言保持一致，但也会改变正确的 Windows 行为：外部路径是原生绝对路径，UNC 文件 URI 有效，而且已配置的主目录会按照宿主路径规则解析。
 
-**操纵子进程管道内部状态，直至写入失败。**CRT 描述符与 libuv 句柄在不同宿主和 Node 版本上的所有权不同，因此这种做法测试的是未文档化的 fixture 机制，而非连接的写入失败契约。
+**操纵子进程管道内部状态，直至写入失败。**CRT 描述符与 libuv 句柄在不同宿主和 Node 版本上的所有权不同，因此这种做法测试的是未文档化的 fixture 机制，而非连接的写入失败约定。
 
-**在 Windows 上跳过整个测试文件或包。**过宽的排除会隐藏受支持的行为。只排除无法在 Windows 上构造相应状态的单项 fixture；相关契约仍保持覆盖。
+**在 Windows 上跳过整个测试文件或包。**过宽的排除会隐藏受支持的行为。只排除无法在 Windows 上构造相应状态的单项 fixture；相关约定仍保持覆盖。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
index 5f9a220dc5..b41a72fb3c 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
 2026-07-24-web-gui-browser-e2e-lane.md: 095ad9055c8462ecec67609ed9af55df2a2d7adb
-2026-07-24-web-gui-browser-e2e-lane.zh.md: eb20ee378eb5154bafcb7a448202c66dacda9199
+2026-07-24-web-gui-browser-e2e-lane.zh.md: d32837d0e320df0dd53ef49a50092503328d0d73
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
index eb20ee378e..d32837d0e3 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
@@ -10,7 +10,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 ## 决策
 
-`pnpm run test:web` 携带 `apps/web/tests/` 下的无密钥、确定性浏览器 e2e 车道：录制的会话日志 fixture 经 `@deepseek-ai/dsh-llm-replay` 对真实进程内 web 组合回放；用户可见状态使用规范化的 aria 预期输出，持久世界状态则使用进程内断言。配套的产品契约包括 `dsh-llm-replay` 的节奏控制、消费检查与已校验的索引式覆写 patch；跨包的 `dsh-llm` 失败通过自有数据属性保留经校验的提供方信息；已交付的 web 组合挂载 `llm-retry`，以处理瞬态模型失败。
+`pnpm run test:web` 携带 `apps/web/tests/` 下的无密钥、确定性浏览器 e2e 车道：录制的会话日志 fixture 经 `@deepseek-ai/dsh-llm-replay` 对真实进程内 web 组合回放；用户可见状态使用规范化的 aria 预期输出，持久世界状态则使用进程内断言。配套的产品约定包括 `dsh-llm-replay` 的节奏控制、消费检查与已校验的索引式覆写 patch；跨包的 `dsh-llm` 失败通过自有数据属性保留经校验的提供方信息；已交付的 web 组合挂载 `llm-retry`，以处理瞬态模型失败。
 
 ### Scaffold：`apps/web/tests/scaffold.ts`
 
@@ -40,15 +40,15 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 `DSH_SNAPSHOT` 选择 replay（默认，无密钥）、record（带密钥）或 refresh（无密钥）。发起提示的 spec 将所有模式共用的驱动步骤与仅供 replay/refresh 使用的断言分开；record 模式驱动真实输入框，采收内存中的会话 header 与事件，脱敏请求头，并 token 化当次运行的会话、cwd 与 RPC 标识。随后一次无密钥 refresh 重新生成 aria 预期输出。每条提示词都会与 fixture 中录制的 `user/message` 核对；每个场景目录都采用封闭清单，其中每个 JSONL 都是脱敏不动点。Web fixture 全部脱敏请求头且不钉任何 header 类别；见「暂缓」。
 
-### 覆盖契约
+### 覆盖约定
 
-该车道覆盖三类行为。实时轮次场景钉住普通工具执行、取消、不可重试失败、瞬态重试、常驻提问与轮次中途 steering；同步依赖持久事件、`whenIdle()` 或显式回放标记，而不使用延时。冷历史场景通过真实持久化 API 播种，在不调用模型的情况下覆盖历史渲染、侧栏搜索、Trajectory 与 Waterfall 视图及工具详情。浏览器生命周期场景覆盖首次发送时物化工作区、重新加载恢复、布局重置、主题与语言偏好，以及工作区的创建、重命名和视图操作。每类场景都断言浏览器表面和权威的 host 状态；离群的模型调用或未耗尽的 fixture 会使拆卸失败。必需车道还包含一份合成的 88 轮 Chat 滚动契约，其中混合了换行 Markdown、围栏代码以及成对的 bash 调用/结果。真实 wheel、输入框、工具、tab、会话与 viewport 交互会在并发历史前插加带节奏流式输出、贴底/离底流式输出、工具 disclosure 离屏循环、扩展历史后的视图/会话重新挂载、宽度重排、贴底后立即重新挂载、输入框尺寸变化以及 textarea wheel 链场景中，断言一个具名已结算行相对 transcript scrollport 的顶部位置和到真实底部的距离；真实键盘翻页与触摸式惯性滑动模拟额外钉住不依赖 wheel 的贴底跟随所有权（[读者滚动归因笔记](../bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md)）；它刻意不钉 DOM 基数或绝对 `scrollTop`，因此同一契约可以验收虚拟化实现。另一份基于同一 fixture 的交互契约钉住异构行顺序、相邻工具 disclosure 的独立状态、用户消息剪贴板内容的精确值、以轮次为边界的消息 fork、源会话/子会话隔离，以及子会话中的一次真实追问轮次；wheel 输入只用于导航到语义目标，不承载几何预期。一份简短的实时历史契约从空白工作区开始，连续驱动输入框轮次，其中包括真实的 bash 调用/结果轮次和一段带节奏的长篇最终响应；它钉住单一会话身份、每轮事件的精确归属、浏览器回显唯一性与输入框恢复，不设置时间阈值。
+该车道覆盖三类行为。实时轮次场景钉住普通工具执行、取消、不可重试失败、瞬态重试、常驻提问与轮次中途 steering；同步依赖持久事件、`whenIdle()` 或显式回放标记，而不使用延时。冷历史场景通过真实持久化 API 播种，在不调用模型的情况下覆盖历史渲染、侧栏搜索、Trajectory 与 Waterfall 视图及工具详情。浏览器生命周期场景覆盖首次发送时物化工作区、重新加载恢复、布局重置、主题与语言偏好，以及工作区的创建、重命名和视图操作。每类场景都断言浏览器表面和权威的 host 状态；离群的模型调用或未耗尽的 fixture 会使拆卸失败。必需车道还包含一份合成的 88 轮 Chat 滚动约定，其中混合了换行 Markdown、围栏代码以及成对的 bash 调用/结果。真实 wheel、输入框、工具、tab、会话与 viewport 交互会在并发历史前插加带节奏流式输出、贴底/离底流式输出、工具 disclosure 离屏循环、扩展历史后的视图/会话重新挂载、宽度重排、贴底后立即重新挂载、输入框尺寸变化以及 textarea wheel 链场景中，断言一个具名已结算行相对 transcript scrollport 的顶部位置和到真实底部的距离；真实键盘翻页与触摸式惯性滑动模拟额外钉住不依赖 wheel 的贴底跟随所有权（[读者滚动归因笔记](../bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md)）；它刻意不钉 DOM 基数或绝对 `scrollTop`，因此同一约定可以验收虚拟化实现。另一份基于同一 fixture 的交互约定钉住异构行顺序、相邻工具 disclosure 的独立状态、用户消息剪贴板内容的精确值、以轮次为边界的消息 fork、源会话/子会话隔离，以及子会话中的一次真实追问轮次；wheel 输入只用于导航到语义目标，不承载几何预期。一份简短的实时历史约定从空白工作区开始，连续驱动输入框轮次，其中包括真实的 bash 调用/结果轮次和一段带节奏的长篇最终响应；它钉住单一会话身份、每轮事件的精确归属、浏览器回显唯一性与输入框恢复，不设置时间阈值。
 
 ### CI 立场
 
-根据[浏览器快照 CI 决策](2026-07-30-web-browser-snapshot-ci-gate.md)，该车道是 Linux 拉取请求必需的只比较门禁。`node 24 / snapshots and artifacts` 消费方任务在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，安装锁文件选定的 Chromium，恢复以操作系统和锁文件为键的缓存，并用 `DSH_SNAPSHOT=replay` 运行该车道。这是有意的平面切分：host 与 spec 使用 [tsx 源码启动契约](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)，浏览器则消费 `apps/web/dist` 和包的 `lib/client.js` 产物，因此门禁依赖 `built-package-invariants` 提供这些客户端产物。托管和自托管的默认分支 Linux 串行任务运行同一门禁；托管任务生成供 PR 消费的浏览器缓存，持久化自托管池则不需要托管侧缓存。CI 从不录制或刷新预期输出。场景仍面向 POSIX，并继续置于 Windows 和 macOS 矩阵之外。
+根据[浏览器快照 CI 决策](2026-07-30-web-browser-snapshot-ci-gate.md)，该车道是 Linux 拉取请求必需的只比较门禁。`node 24 / snapshots and artifacts` 消费方任务在[消费方独立构建](../process/2026-07-30-independent-ci-consumer-build.md)中负责唯一一次 Linux 构建，安装锁文件选定的 Chromium，恢复以操作系统和锁文件为键的缓存，并用 `DSH_SNAPSHOT=replay` 运行该车道。这是有意的平面切分：host 与 spec 使用 [tsx 源码启动约定](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)，浏览器则消费 `apps/web/dist` 和包的 `lib/client.js` 产物，因此门禁依赖 `built-package-invariants` 提供这些客户端产物。托管和自托管的默认分支 Linux 串行任务运行同一门禁；托管任务生成供 PR 消费的浏览器缓存，持久化自托管池则不需要托管侧缓存。CI 从不录制或刷新预期输出。场景仍面向 POSIX，并继续置于 Windows 和 macOS 矩阵之外。
 
-高基数性能诊断使用单独按需启用的 `apps/web/tests/**/*.perf.ts` 清单，并且只由 `vitest.web.perf.config.ts` 选中。`complex-history.perf.ts` 的隔离用例复用真实 scaffold：工作区用例播种 1,000 个紧凑会话以及一份包含 500 次工具调用的 500 轮次历史，在 Chat 中穷尽并重新挂载该历史，并报告 Chromium 主线程、DOM、监听器、堆内存、分页、搜索和 Trajectory 测量结果。两个续聊用例播种同一份长历史，但比较默认的 24 轮次 Chat 窗口与展开全部 500 轮次的状态，然后各自通过真实输入框、agent loop、SSE wire、工具和持久化继续进行 8 个相同轮次；其中两轮执行真实 `bash` 调用并断言其持久化结果，最后一轮则填入一条包含 8,232 个字符的混合语言提示词，并回放 120 个带节奏的文本增量。一个单独的 soak 用例从空白会话开始，通过真实输入框连续驱动 100 轮，每第 10 轮执行一次 `bash` 调用并产生结果，每 10 轮强制执行一次 GC，并报告每 10 轮的延迟窗口及保留的浏览器状态。随后它通过受信任的浏览器点击提交第 101 个纯文本轮次，并使用浏览器时钟分别测量发送到 transcript DOM 和发送到绘制后的延迟，排除输入框的草稿镜像，并与完整轮次完成时间分开。逐轮诊断涵盖输入框填入、点击到用户消息回显、点击到首个分片、完成、浏览器变更、持久化分片和工具事件；合成回放模型拥有足够的上下文容量，可使 fixture 基数保持稳定，而不会因压缩（compaction）消耗脚本化调用。结构性断言钉住预期的负载、流和工具形状，但时间仍不设阈值，因为机器速度不属于正确性契约。必需的 `vitest.web.config.ts` 清单仍仅限 `*.e2e.ts` 和 `*.snapshot.ts`，因此 `test:web:built` 及其 CI 门禁都不会收集性能用例。
+高基数性能诊断使用单独按需启用的 `apps/web/tests/**/*.perf.ts` 清单，并且只由 `vitest.web.perf.config.ts` 选中。`complex-history.perf.ts` 的隔离用例复用真实 scaffold：工作区用例播种 1,000 个紧凑会话以及一份包含 500 次工具调用的 500 轮次历史，在 Chat 中穷尽并重新挂载该历史，并报告 Chromium 主线程、DOM、监听器、堆内存、分页、搜索和 Trajectory 测量结果。两个续聊用例播种同一份长历史，但比较默认的 24 轮次 Chat 窗口与展开全部 500 轮次的状态，然后各自通过真实输入框、agent loop、SSE wire、工具和持久化继续进行 8 个相同轮次；其中两轮执行真实 `bash` 调用并断言其持久化结果，最后一轮则填入一条包含 8,232 个字符的混合语言提示词，并回放 120 个带节奏的文本增量。一个单独的 soak 用例从空白会话开始，通过真实输入框连续驱动 100 轮，每第 10 轮执行一次 `bash` 调用并产生结果，每 10 轮强制执行一次 GC，并报告每 10 轮的延迟窗口及保留的浏览器状态。随后它通过受信任的浏览器点击提交第 101 个纯文本轮次，并使用浏览器时钟分别测量发送到 transcript DOM 和发送到绘制后的延迟，排除输入框的草稿镜像，并与完整轮次完成时间分开。逐轮诊断涵盖输入框填入、点击到用户消息回显、点击到首个分片、完成、浏览器变更、持久化分片和工具事件；合成回放模型拥有足够的上下文容量，可使 fixture 基数保持稳定，而不会因压缩（compaction）消耗脚本化调用。结构性断言钉住预期的负载、流和工具形状，但时间仍不设阈值，因为机器速度不属于正确性约定。必需的 `vitest.web.config.ts` 清单仍仅限 `*.e2e.ts` 和 `*.snapshot.ts`，因此 `test:web:built` 及其 CI 门禁都不会收集性能用例。
 
 ## 业界先例
 
@@ -64,13 +64,13 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **用占位 `DEEPSEEK_API_KEY` + 回放拦截替代禁用适配器行。** 尽管零组合改动且树内有两处先例仍被否决：它用谎言满足 `llm-deepseek` 的快速失败密钥检查，还留下一个挂载却被拦截的死适配器；禁用行（ACP overlay 的同款做法）是诚实的无密钥，并在最早可解析点快速失败。
 
-**`packages/support/web-snapshot` 包 + `defineWebSnapshotSuite` 工厂。** 已否决：驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100%，且除受门禁的包已导出的辅助工具与本地 scaffold 外，这些场景专用交互尚未形成稳定的无浏览器契约。出现第二个 web 形态消费方，或被证实重复的生命周期代码确立该契约后，再重新考虑。
+**`packages/support/web-snapshot` 包 + `defineWebSnapshotSuite` 工厂。** 已否决：驱动 chromium 的源码在无浏览器的覆盖率 runner 上无法诚实保持逐文件 100%，且除受门禁的包已导出的辅助工具与本地 scaffold 外，这些场景专用交互尚未形成稳定的无浏览器约定。出现第二个 web 形态消费方，或被证实重复的生命周期代码确立该约定后，再重新考虑。
 
 **第二份提交的规范化会话日志预期输出。** 已否决：日志表面已由 ACP/headless/TUI 套件经同一循环与持久化钉住；在此只会翻倍刷新成本并重复测试下层。内联在根上下文事件上的世界状态断言保住了验证世界的义务。
 
 **以 `DSH_SNAPSHOT` 回放分支拉起 `dsh web` bin。** 已否决：它需要在交付的 CLI 中增加测试专用回放分支和环境变量管道。进程内 scaffold 已加载同一份 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml`；只剩 argv、profile JSON 和 `AppCLIEntry` 胶水不在其覆盖范围内，而这些路径已由无密钥 CLI 冒烟覆盖。
 
-**为可测试性改 wire 协议。** 已否决：契约已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
+**为可测试性改 wire 协议。** 已否决：约定已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
 
 **以真实模型浏览器测试充当无密钥车道。** 已否决：按构造即不确定；被调研的前车之鉴（open-webui）长出无界超时后被删除。带密钥的 W5 冒烟仍是真实模型侧的补充。
 
@@ -88,7 +88,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 - **恢复后追问场景**：真实 wire 上的历史/实时缝合路径；当该代码变更或回归时作为独立场景补充。
 - **输入框 steering 手势**：输入在运行期间锁定（只能停止或等待），因此 steering 场景从页面走 wire 做 steer；`TODO(web-steer-composer)` 待产品长出真实的输入框手势后，把驱动步骤升级为该手势。
 - **拖拽会话重排**：`workspace.insertSessionBefore` 尚无浏览器场景；它需要在同一个工作区里物化两个会话，并合成 HTML5 拖拽事件。当该表面变更或回归时再补充。无行为的会话 Rename/Fork/Delete 和工作区 Delete 菜单行待获得行为后再补充场景。
-- **长历史 Chat 到 Trajectory 的 Inspect**：独立的检查数据源会在视图打开后穷尽历史，而所选记录由一个派生的表格索引定位；随着较早页面前插，该索引可能移动。短历史 Inspect 仍有覆盖；在选中项具有稳定的语义身份之前，长历史交互契约不包含这项交接。
+- **长历史 Chat 到 Trajectory 的 Inspect**：独立的检查数据源会在视图打开后穷尽历史，而所选记录由一个派生的表格索引定位；随着较早页面前插，该索引可能移动。短历史 Inspect 仍有覆盖；在选中项具有稳定的语义身份之前，长历史交互约定不包含这项交接。
 
 ## 后果
 
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
index ea4966f81e..318262eecb 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
 2026-06-16-typed-event-schemas.md: 97a7d0c3787eb5556696e25a6c8b1bb75642aba9
-2026-06-16-typed-event-schemas.zh.md: d0c9ffb3640cb76f0c656e4ac841dc3817bcb86d
+2026-06-16-typed-event-schemas.zh.md: 6d665151a9c5879b3810ae93af8cc6bf5a21727c
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
index d0c9ffb364..6d665151a9 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
@@ -8,10 +8,10 @@ Status: proposed
 
 harness 将其核心词汇——内容块、消息来源、结束原因、轮次触发器、轮次结束原因与会话事件——建模为 **merge-extensible map**：一个 TypeScript `interface`（如 `SessionEventMap`、`ContentBlockMap`），插件通过声明合并对其扩展，公开联合类型则以 `Map[keyof Map]` 派生。这是本仓库的通用扩展模式，记录在 [docs/architecture.md](../../../../docs/architecture.md) 中（「The same merge-extensible-map pattern is used for `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`」），`defineTool` 的 `InferArgs` DSL 和 `assertNever` 穷举约定都依赖于它。
 
-该模式**仅存在于编译期**。类型在运行时消失：没有 schema 对象可供校验传入值、解析不可信输入或在运行时枚举变体。[会话持久化契约](../../implemented/architecture/2026-06-14-session-persistence.md)暴露了两个后果：
+该模式**仅存在于编译期**。类型在运行时消失：没有 schema 对象可供校验传入值、解析不可信输入或在运行时枚举变体。[会话持久化约定](../../implemented/architecture/2026-06-14-session-persistence.md)暴露了两个后果：
 
 1. **持久化将 `event.data` 视为不透明 JSON。** JSONL/SQLite 后端对每个事件逐字 `JSON.stringify`/`JSON.parse`；唯一的运行时守卫是 `isJsonValue`（往返可序列化性检查：拒绝 BigInt、函数、循环引用、非有限数等），而非结构校验。一个损坏但仍为合法 JSON 的事件数据（字段类型错误、字段缺失）会静默往返，只有在后续消费方的 `switch` 中才可能被捕获。
-2. **插件新增变体没有运行时契约。** 一个通过声明合并添加新 `SessionEventMap` 键的插件，在自身代码中获得了编译期类型，但没有任何机制校验它产出的值是否符合它所声明的形状——无论是在生产者处、持久化边界处还是重新加载时。
+2. **插件新增变体没有运行时约定。** 一个通过声明合并添加新 `SessionEventMap` 键的插件，在自身代码中获得了编译期类型，但没有任何机制校验它产出的值是否符合它所声明的形状——无论是在生产者处、持久化边界处还是重新加载时。
 
 由此引出问题：事件词汇是否应迁移到 **Zod** 或其他运行时 schema 库，使持久化边界和插件边界拥有运行时 schema 而非被擦除的类型。
 
diff --git a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
index e6fc787553..7493384e67 100644
--- a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
 2026-07-15-sdk-project-editing-architecture.md: 8335af516dbaa85f4adb85286f976ce9be2c9da8
-2026-07-15-sdk-project-editing-architecture.zh.md: 51f0c5e7f4f033d8149a7ae01aae7a8c4755b76c
+2026-07-15-sdk-project-editing-architecture.zh.md: 4c59ac8cdedf0c7fdd1a2e7994135bc89653d55e
diff --git a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
index 51f0c5e7f4..4c59ac8cde 100644
--- a/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
@@ -37,7 +37,7 @@ SDK 使用一个共享的面向对象工程模型。`SdkProject` 是只读快照
 
 `@deepseek-ai/create-sdk` 是仓库 `@deepseek-ai/dsh-*` 命名规则的唯一例外；npm scoped initializer 约定要求 `npm create @deepseek-ai/sdk` 对应这个包名。该例外是仓库架构事实，不增加第三个开发者产品入口。
 
-三个包只导出相邻层实际使用的最小入口，不提供 `src/*` 深路径。scripts 的库入口与构建配置子路径服务生成代码和项目构建配置，但开发者产品契约仍由 `dsh-sdk` 命令承担。
+三个包只导出相邻层实际使用的最小入口，不提供 `src/*` 深路径。scripts 的库入口与构建配置子路径服务生成代码和项目构建配置，但开发者产品约定仍由 `dsh-sdk` 命令承担。
 
 ## 工程聚合与编辑会话
 
@@ -99,7 +99,7 @@ create-sdk 保留隐藏的 `--link-workspace` 选项供 Harness 仓库开发和
 ## 后续工作
 
 - **可替换的 required 主干角色。** 当前 `spine` 以一个固定功能选项拥有整组实现，包含 SystemPrompt、LLMService 等。无法让开发者对其进行替换和切换，只能手工修改 Cordis 配置项。
-- **服务契约与包声明。** 替换特定内建服务时，Cordis 插件目前无法通过 `provides` 元数据声明其提供的服务，因此 SDK 无法在开发阶段辅助配置，也无法在运行时检查兼容性。后续需要设计相应协议。
+- **服务约定与包声明。** 替换特定内建服务时，Cordis 插件目前无法通过 `provides` 元数据声明其提供的服务，因此 SDK 无法在开发阶段辅助配置，也无法在运行时检查兼容性。后续需要设计相应协议。
 - **功能参数描述。** 当前功能的专用输入必须手工声明；SDK 无法从任意 Cordis 插件配置或 NPM package.json 信息中自动推导可交互参数。后续可以定义有限的声明式参数元数据，但不把任意 Cordis 插件配置转换成通用表单。
 - **SDK 应用级配置。** 当前项目资源模型只描述 Cordis 配置项及单个 Cordis 插件拥有的配置键，因此所有受 SDK 管理的配置都必须归属某个插件。跨插件或面向整个 SDK 应用的设置没有独立持久化位置；后续需要定义应用级配置文档及其所有权、读取和修改边界。
 
@@ -109,7 +109,7 @@ create-sdk 保留隐藏的 `--link-workspace` 选项供 Harness 仓库开发和
 
 **使用 `wizard.json` 与通用 Questionnaire。** 静态表单无法直接表达功能依赖、选项切换、已有值回填和项目资源变化；类型、门禁和动态选项最终仍要通过字符串注册表与过程式 `run()` 连接，形成新的内部 DSL。
 
-**公开本地链接 flag。** 该模式依赖 Harness monorepo 布局和未发布包，只服务仓库开发；公开后会形成无法对外兑现的项目创建契约，因此保持隐藏。
+**公开本地链接 flag。** 该模式依赖 Harness monorepo 布局和未发布包，只服务仓库开发；公开后会形成无法对外兑现的项目创建约定，因此保持隐藏。
 
 ## 验收标准
 
diff --git a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml
index e0c0fa0ccd..25b4c76ff7 100644
--- a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md
 2026-07-19-required-cancellation-through-tool-capability-seams.md: c2cfb09f27222136965058695e9b6b706ac688a9
-2026-07-19-required-cancellation-through-tool-capability-seams.zh.md: 6aa7340d45e99b9072c28c6a1cfe6a769ff8f795
+2026-07-19-required-cancellation-through-tool-capability-seams.zh.md: 0544a17629c4fb130bed9ec6c7cae1a15d2211a8
diff --git a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
index 6aa7340d45..0544a17629 100644
--- a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-已经实现的[工具注册表取消契约](../../implemented/architecture/2026-07-19-cooperative-tool-cancellation.md)让每个工具主体中的 `exec.signal` 成为必填值，但许多由工具主体调用的异步能力接口仍接受可选信号。因此，工具可以满足自身类型，却在下一次同进程调用时意外丢失取消。
+已经实现的[工具注册表取消约定](../../implemented/architecture/2026-07-19-cooperative-tool-cancellation.md)让每个工具主体中的 `exec.signal` 成为必填值，但许多由工具主体调用的异步能力接口仍接受可选信号。因此，工具可以满足自身类型，却在下一次同进程调用时意外丢失取消。
 
 这项缺口会沿调用链传递。文件系统工具可能调用路径解析和 I/O，Web 工具可能调用提供方，Bash 工具可能调用执行器，组合工具可能启动或等待任务、subagent 或工作流。只要某个控制工具所持有工作的、且会被工具等待的操作允许省略信号，TypeScript 就无法证明取消仍能到达拥有副作用的边界。
 
@@ -16,7 +16,7 @@ Status: proposed
 
 所有能从工具主体到达、且在工具仍持有或等待该操作期间执行的异步同进程能力操作，都必须接收 `AbortSignal`。根据所属 seam 的既有形态，这项要求可以表现为位置参数，也可以表现为必填的只读请求字段，但省略信号必须导致 TypeScript 编译失败。
 
-每个直接调用方提供自己持有的信号，或从自身必填的操作上下文继续传递信号。实现可以派生子截止时间或取消作用域，但派生信号在委托期间仍须与上游信号关联。能力实现不得生成永不中止信号、使用环境式异步本地取消，也不得仅为重复类型化同进程契约而在运行时校验 `AbortSignal`。
+每个直接调用方提供自己持有的信号，或从自身必填的操作上下文继续传递信号。实现可以派生子截止时间或取消作用域，但派生信号在委托期间仍须与上游信号关联。能力实现不得生成永不中止信号、使用环境式异步本地取消，也不得仅为重复类型化同进程约定而在运行时校验 `AbortSignal`。
 
 迁移首先从每个第一方 `ToolDefinition.execute()` 出发，清点其等待的能力调用；随后按内聚的接口／实现／消费方 seam，将测试与生成的 API 文档一并修改。文件系统、Bash 与任务、Web 与提供方、工作流与 subagent、代码运行时等能力族可以通过独立 PR（Pull Request）迁移，以保持每项变更可审查；但根据仓库的预发布原则，已经迁移的接口不得保留可选兼容重载。
 
@@ -32,7 +32,7 @@ Status: proposed
 
 **因为工具主体已经收到信号，所以继续让下游信号保持可选。** 不予采纳，因为外层回调中存在信号并不能让传递过程具备类型安全；每个可选能力调用仍可合法省略它。
 
-**通过 lint 规则或回调检查强制传递。** 不予采纳，因为语法检查无法可靠识别所有权、派生信号、抽象层或正确的完全停稳行为。必填接口参数可以在 TypeScript 能检查每个调用方的位置表达契约。
+**通过 lint 规则或回调检查强制传递。** 不予采纳，因为语法检查无法可靠识别所有权、派生信号、抽象层或正确的完全停稳行为。必填接口参数可以在 TypeScript 能检查每个调用方的位置表达约定。
 
 **把 `ToolRunContext` 传入所有能力。** 不予采纳，因为能力需要的是取消，而不是工具身份、agent（智能体）状态或上下文延后功能。传递更大的上下文会让可复用服务耦合到工具注册表，也会掩盖狭窄的 seam。
 
@@ -45,7 +45,7 @@ Status: proposed
 ## 验收标准
 
 - 清单把每个第一方工具主体映射到所有权交接前可以到达的异步能力操作。
-- 每个范围内的能力接口都要求 `AbortSignal`，并由编译期契约测试证明省略信号会失败。
+- 每个范围内的能力接口都要求 `AbortSignal`，并由编译期约定测试证明省略信号会失败。
 - 接口、实现、直接消费方、测试辅助函数、示例和生成的 API 引用必须一起迁移，不保留兼容重载或生产环境永不中止哨兵。
 - 派生截止时间和包装层作用域仍与调用方信号关联，集成测试证明取消到达副作用所有者，且等待的工作完全停稳。
 - 同步查询和明确交接后的分离工作不受这项要求约束；存在歧义时，需要记录并测试所有权转换。
@@ -62,4 +62,4 @@ Status: proposed
 
 **只有机械合规而没有协作行为。** 必填参数只能证明信号可用，不能证明实现会观察或转发它。进程、worker、套接字、提供方和任务边界仍需集成测试证明实际行为。
 
-**把同步或无关 API 纳入范围。** 在不存在异步工作的地方要求取消只会增加噪声，并削弱契约的辨识度。修改前，清单需要记录每项操作为何可由工具到达并承载其生命周期。
+**把同步或无关 API 纳入范围。** 在不存在异步工作的地方要求取消只会增加噪声，并削弱约定的辨识度。修改前，清单需要记录每项操作为何可由工具到达并承载其生命周期。
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
index 8109eb4854..6b3b6cafb3 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
 2026-07-24-domain-kv-storage-and-workspace.md: 1cb2bc4b29c196dbb33292547c75d01a37f06772
-2026-07-24-domain-kv-storage-and-workspace.zh.md: 2904065a7374803495a9bbf8ff4e044310d9bd02
+2026-07-24-domain-kv-storage-and-workspace.zh.md: ea537e0e5e5b02955d0b279d80822b0220f2b20b
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
index 2904065a73..ea537e0e5e 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
@@ -41,7 +41,7 @@ host 侧唯一的持久化面是 session 事件日志（`packages/session/sessio
 
 一个后端是一个**介质 owner**（一棵文件树 root / 一个 db 文件），通过**数据形状 facet** 暴露原语——本期只有 `kv`；session 迁移期加 `log`（见迁移节）。facet 是可选成员，缺席即该后端不支持该形状，解析时 fail loud。`kv` facet 的原语面：`open(descriptor)`（descriptor = 名字/版本/表名清单/有无 global，名字与表名限 `^[a-z][a-z0-9_]*$` 兼作文件名与 SQL 表名段）返回 unit，unit 提供 `loadAll` / `putRecord` / `deleteRecord`（缺 key 为 no-op）/ `setGlobal` / `close`（幂等）；值对后端是不透明 JSON。规范正文（含逐方法 JSDoc）在 `packages/storage/storage/src/backend.ts`。
 
-后端契约（共享契约测试逐条断言，两后端同套件）：
+后端约定（共享约定测试逐条断言，两后端同套件）：
 
 1. `open` 对不存在的介质创建（懒物化允许：可延迟到首写，但 `loadAll` 立即可用返回空表）；对已存在介质载入。
 2. 介质上版本 ≠ descriptor.version → `StorageError('version-mismatch')`，不迁移不重建。
@@ -256,7 +256,7 @@ export class WorkspaceRegistry extends Service {
 
 ### 复用与 session 后端迁移展望
 
-**长期方向**：session-persistence 的 JSONL/SQLite 后端里"纯介质操作"下沉到 `dsh-storage` 后端（session 包不删，`SessionPersistence` seam 与 coordinator 语义不动；动的只是它们脚下的文件/db 操作层）。复用的动机：介质层全是文件系统操作、数据库调用与跨平台兼容的脏活（Windows 权限与原子发布变体、fsync 语义、独占建文件……），这些只应写一遍；业务语义（session 怎么 append、何时 append、append 什么）留在上层——而"底下这次 append 是否正常完成"（持久性/原子性/平台正确性）是底层的责任，责任界面就是 facet 原语的契约。为此后端接口按**介质 owner + 数据形状 facet** 设计：session 日志是仅追加流，与 KV 形状不同——强行统一进 KV 原语会两头变形，所以按 facet 分开（`kv` 本期、`log` 迁移期），介质与生命周期共享。
+**长期方向**：session-persistence 的 JSONL/SQLite 后端里"纯介质操作"下沉到 `dsh-storage` 后端（session 包不删，`SessionPersistence` seam 与 coordinator 语义不动；动的只是它们脚下的文件/db 操作层）。复用的动机：介质层全是文件系统操作、数据库调用与跨平台兼容的脏活（Windows 权限与原子发布变体、fsync 语义、独占建文件……），这些只应写一遍；业务语义（session 怎么 append、何时 append、append 什么）留在上层——而"底下这次 append 是否正常完成"（持久性/原子性/平台正确性）是底层的责任，责任界面就是 facet 原语的约定。为此后端接口按**介质 owner + 数据形状 facet** 设计：session 日志是仅追加流，与 KV 形状不同——强行统一进 KV 原语会两头变形，所以按 facet 分开（`kv` 本期、`log` 迁移期），介质与生命周期共享。
 
 现状复用审计（迁移前就能看清的账）：
 
@@ -275,11 +275,11 @@ export class WorkspaceRegistry extends Service {
 
 | 套件 | 覆盖 | 后端 |
 | --- | --- | --- |
-| 后端契约（共享套件，一次编写两端跑） | 七条契约 + 版本拒绝 + close 幂等 | json、sqlite（`:memory:` + 临时目录） |
+| 后端约定（共享套件，一次编写两端跑） | 七条约定 + 版本拒绝 + close 幂等 | json、sqlite（`:memory:` + 临时目录） |
 | 注册表/mount | 重复注册、未挂载访问、disposer 摘除 | — |
 | domain 层 | open 六步语义、schema 拒绝、update 串行（并发交错压测）、`domain/changed` 逐条、global 初值懒物化、路由与 `facet-unsupported` | 任一（json） |
 | workspace | create/唯一性/realpath、attach 校验（含 sessionPersistence 缺席拒绝）、一致性口径四情形 | mock domain 或 json |
-| session delete 契约（future work，随实施并入 runPersistenceContract） | 未知 id、已删 id 复用、未物化 intent、与在途 append 串行、deleted 事件 | jsonl、sqlite |
+| session delete 约定（future work，随实施并入 runPersistenceContract） | 未知 id、已删 id 复用、未物化 intent、与在途 append 串行、deleted 事件 | jsonl、sqlite |
 
 快照：本期无模型可见面与组装面，不新增；下期 RPC 接线时随 `workspace.*` 域补。
 
@@ -318,7 +318,7 @@ export class WorkspaceRegistry extends Service {
 
 ## 验收标准
 
-- 测试矩阵本期四套件全绿：后端契约共享套件在 json/sqlite 双端、注册表/mount disposer 语义、domain 层（含 open 六步与路由 fail-loud）、workspace 全语义（create/attach 校验/一致性口径）。
+- 测试矩阵本期四套件全绿：后端约定共享套件在 json/sqlite 双端、注册表/mount disposer 语义、domain 层（含 open 六步与路由 fail-loud）、workspace 全语义（create/attach 校验/一致性口径）。
 - `ctx.workspace` 可在测试组装下完成 create → attach → list → 仅删除元数据的 delete 生命周期。
 - session-persistence 包零 diff（本期不动 session 侧的验收线）。
 - 本期无新快照（无模型可见面与组装面）；下期 RPC 接线时补。
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
index c0bccacb78..1bf84824b2 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
 2026-07-25-client-settings-locale-theme.md: fdcdcff92fa324803d5f2343f3fc3d9dcca069c7
-2026-07-25-client-settings-locale-theme.zh.md: 9cf973aee29cc1072c2fdaf1ce67e0b8395f1d90
+2026-07-25-client-settings-locale-theme.zh.md: efcbbff3727a7a5ce14ba7273c7d0e826a3e5cbd
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
index 9cf973aee2..efcbbff372 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-浏览器端已有的 Settings 直接写在 Sidebar 内，语言和主题也由组件本地状态直接改 DOM。这使 Settings 无法由独立插件扩展，偏好状态没有稳定的跨插件服务契约，主题注册表同时承担状态与呈现职责。
+浏览器端已有的 Settings 直接写在 Sidebar 内，语言和主题也由组件本地状态直接改 DOM。这使 Settings 无法由独立插件扩展，偏好状态没有稳定的跨插件服务约定，主题注册表同时承担状态与呈现职责。
 
 ## 提案
 
@@ -61,7 +61,7 @@ section/item contribution 使用 `ctx.slots.inject()`，不依赖 client manifes
 
 `SlotsService.inject()` 直接等待有类型约束的 ledger key；它不会将声明桥接为合成的 `slot:<name>` Cordis 服务。回调会跟随声明撤销与重新声明，而其控制器仍归贡献方插件 fiber 所有；直接向未声明 slot 注册仍会显式报错。这移除了陈旧 disposer 的在位判定机制和容易因拼写错误出错的平行服务命名空间。完整的生命周期与失败约定见 [slot 声明注入决策](../../implemented/architecture/2026-08-05-slot-declaration-injection.md)。
 
-### 服务契约
+### 服务约定
 
 ```ts
 export type ThemePreference = 'light' | 'dark' | 'system'
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index d4aa713b5c..ce7e7f5f4f 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
 2026-07-27-session-projection-and-command-log.md: 2fc463ab6e65998c19b0a0fce186c7eb17dacbf6
-2026-07-27-session-projection-and-command-log.zh.md: 0cc82d1aa65dc2b99882875d655ddbe17073354a
+2026-07-27-session-projection-and-command-log.zh.md: ef4de5ea924e28c28896558206566639295c4c8e
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index 0cc82d1aa6..ef4de5ea92 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -26,7 +26,7 @@ Status: proposed
 
 一个轻量的接口包：merge-extensible 类型表、注册表服务、边界上的 zod 校验。能力 seam 三方拆分：领域 host 插件负责贡献，载体负责消费，两侧互不相识。
 
-领域注册的是一个**状态驱动计算单元（state-driven computation unit）**——三个纯函数外加若干声明——绝不是一个不透明的 getter。驱动它是框架的职责（订阅、水位线（watermark）、缓存，以及后续的检查点机制），领域只负责数学本身。投影服务于所有业务领域（会话标题、plan、goal、权限、todos）；命令只是其中一条触发路径，在本契约中没有任何特殊地位。
+领域注册的是一个**状态驱动计算单元（state-driven computation unit）**——三个纯函数外加若干声明——绝不是一个不透明的 getter。驱动它是框架的职责（订阅、水位线（watermark）、缓存，以及后续的检查点机制），领域只负责数学本身。投影服务于所有业务领域（会话标题、plan、goal、权限、todos）；命令只是其中一条触发路径，在本约定中没有任何特殊地位。
 
 ```ts ignore-check
 export interface SessionProjectionMap {}   // the single type table for the whole chain
@@ -112,7 +112,7 @@ type UseProjection = {
 
 `undefined` 统一表示能力缺失（host 插件未挂载，或尚无任何基线/帧携带过该 key）。值仓只暴露按 key 的裸 `{subscribe, getSnapshot}` 面；其余交给带逐 key 缓存的 `bindSnapshotSelector`——引用稳定性成立，因为一个 key 的值引用只在帧或基线落地时才变化。写路径不变：变更回调留在 inject 共享面（回调出自 inject，活状态出自 `useProjection`）。
 
-「钩子不得穿过 inject」的唯一既有违例——`DetailsInjected.useSelection`——随本变更一并收编：选中态是住在聊天 store 里的查看状态，因此 details 注册声明共享 store 句柄，组件改读 `props.useStore(s => s.selection)`；`useSelection` 退出 inject 契约。
+「钩子不得穿过 inject」的唯一既有违例——`DetailsInjected.useSelection`——随本变更一并收编：选中态是住在聊天 store 里的查看状态，因此 details 注册声明共享 store 句柄，组件改读 `props.useStore(s => s.selection)`；`useSelection` 退出 inject 约定。
 
 ### 日志中的命令生命周期
 
@@ -133,7 +133,7 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 
 基础设施先行；三个在途 PR（Pull Request）原样不动，待基座落地后重新对接（它们的迁移映射即指南）：
 
-1. **host 基座**：`dsh-session-projection`（单元契约、主动驱动、水位线缓存）+ api-proxy 的 projections 块 + `session/projection` 推送帧。零领域注册也可合入（此时块与帧直接缺席）。
+1. **host 基座**：`dsh-session-projection`（单元约定、主动驱动、水位线缓存）+ api-proxy 的 projections 块 + `session/projection` 推送帧。零领域注册也可合入（此时块与帧直接缺席）。
 2. **客户端基座**：通用值仓 + `useProjection` 席位；下线按领域的 cell 机制，并在标题单元注册后一并下线 `session/title` 帧与标题快照表。帧的形状依赖 1（在此之前 fixture（测试前置数据）喂合成帧）。
 3. **命令通道**：两个事件、执行器落日志、通用节点 + keyed slot、通知通道下线、`{matched, commandId?}` 准入。与 1 并行。
 4. **领域重新对接**（在 1+2 之后）：先 todo（单元进 `tool-todo`，删掉搭载字段），再 plan（双事件单元、RPC 下线、开关改发 `/plan`），最后 goal（`goal/change` 单元，删掉 `goals.get`，把六个 `Session` 方法移入领域插件的 inject）。
@@ -143,11 +143,11 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 
 **专设一个 `session.projections` RPC**——不予采纳：基线刷新时刻与尾页拉取精确重合，单独的一元 RPC 只会换来第二次往返、第二个待调和的 seq，以及一个客户端「何时重取」决策——而搭载设计把这个决策整个删掉了。
 
-**不透明的 `get(agent)` 提供方契约**——曾是第一稿，后被否决：计算模型藏在领域内部时，框架永远无法为状态做检查点、无法服务冷会话（没有 agent、没有已加载的日志——`get` 无处可跑）、也无法从日志中段续算。注册 `(init, apply, view)` 单元把驱动权交给框架，领域只留纯数学；有 host 侧行为需求的领域，其服务订阅照旧自持，与投影单元互不牵连。
+**不透明的 `get(agent)` 提供方约定**——曾是第一稿，后被否决：计算模型藏在领域内部时，框架永远无法为状态做检查点、无法服务冷会话（没有 agent、没有已加载的日志——`get` 无处可跑）、也无法从日志中段续算。注册 `(init, apply, view)` 单元把驱动权交给框架，领域只留纯数学；有 host 侧行为需求的领域，其服务订阅照旧自持，与投影单元互不牵连。
 
-**为 plan 待定意图专设的仅实时叠加钩子（`live?(agent, base)`）**——不予采纳：它存在的唯一理由是用户的 plan *选择*不在日志里。让选择走标准命令通道后，`command/run` 上了账，待定态成为纯回放量，投影契约保持恰好三个纯函数。
+**为 plan 待定意图专设的仅实时叠加钩子（`live?(agent, base)`）**——不予采纳：它存在的唯一理由是用户的 plan *选择*不在日志里。让选择走标准命令通道后，`command/run` 上了账，待定态成为纯回放量，投影约定保持恰好三个纯函数。
 
-**把 seam 命名为 `registerFold`**——已被单元契约取代：注册对象如今确实是一个折叠，但本仓库里 `fold*` 专指纯 `(events) => state` 辅助函数，而该 seam 注册的是带 key、带 schema、带版本的单元。投影仍是事件溯源中指称读模型角色的术语，#587 的 Note 标题与 #497 的评论也都已在使用它。
+**把 seam 命名为 `registerFold`**——已被单元约定取代：注册对象如今确实是一个折叠，但本仓库里 `fold*` 专指纯 `(events) => state` 辅助函数，而该 seam 注册的是带 key、带 schema、带版本的单元。投影仍是事件溯源中指称读模型角色的术语，#587 的 Note 标题与 #497 的评论也都已在使用它。
 
 **客户端侧折叠（带 `fromEvent` 的按领域投影 cell）**——曾是第二稿，后被否决：一旦 plan 的单元要折叠两种事件，客户端 cell 就必须在浏览器里复刻 host 的状态转移逻辑——同一个折叠写两遍、各自演化。推送成品值（标题帧先例的泛化）保住唯一计算地点，并把客户端简化为一个由 seq 把守的通用值仓；领域零客户端代码。
 
@@ -173,15 +173,15 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 - 历史尾页携带 `projections`，其 `asOfSeq` 等于窗口尾部 seq；loadOlder 页永不携带；未装注册表的部署照常返回不带该块的历史，客户端把所有 key 视为缺席。
 - 陈旧的基线不能覆盖更新的 `session/projection` 帧，重放的帧也不能让值仓倒退（两条路径都做 seq 高者胜测试）。
 - 在一个标签页执行的斜杠命令，刷新后、在第二个标签页上、恢复之后都在 flow 中渲染出持久节点；未注册的命令渲染通用卡片；命令结果的 composer 通知路径彻底移除。
-- `useProjection` 经标准 props 套件抵达组件；没有任何钩子穿过 inject 契约（包括 `useSelection`）。
+- `useProjection` 经标准 props 套件抵达组件；没有任何钩子穿过 inject 约定（包括 `useSelection`）。
 - 会话标题搭乘这对通用机制（基线块 + 投影帧）；专设的 `session/title` 帧与客户端标题快照表彻底移除。
 
 ## 风险
 
-- **全量值规则是承重结构**：未来某个领域若只记裸增量，就无法凭其最新事件服务消费方，还会让自己的单元复杂化。缓解：该规则写明在本 Note 与投影包的 README 里；单元契约让完整状态在每次转移处都是显式的。
+- **全量值规则是承重结构**：未来某个领域若只记裸增量，就无法凭其最新事件服务消费方，还会让自己的单元复杂化。缓解：该规则写明在本 Note 与投影包的 README 里；单元约定让完整状态在每次转移处都是显式的。
 - **单元的同步纪律**：`init`/`apply`/`view` 一旦 await 就会撕裂一致性切面。注册表在文档中申明这条纪律，invariant 配套在可行范围内断言同步性；其余由评审把关。
-- **注册表的实时增删不做推送**：会话中途加载或卸载领域插件会改变键集，但不会触发任何会话事件、也不会推任何帧；开着的客户端持有陈旧的 key 直到下次尾页拉取（重连、缺口修补、打开）。接受为仅开发期（HMR）的陈旧时窗——日后可以在变更流上加一个注册表变更推送，契约不受影响。
-- **忙碌会话上的主动驱动开销**：每个已提交事件都要过每个已注册单元的 `apply`。按构造，单元的逐事件开销很低（全量值规则），不匹配的事件返回同一引用，且已注册领域的数量很小；若真出现热点路径，可以加按单元的事件类型预过滤，契约不变。
+- **注册表的实时增删不做推送**：会话中途加载或卸载领域插件会改变键集，但不会触发任何会话事件、也不会推任何帧；开着的客户端持有陈旧的 key 直到下次尾页拉取（重连、缺口修补、打开）。接受为仅开发期（HMR）的陈旧时窗——日后可以在变更流上加一个注册表变更推送，约定不受影响。
+- **忙碌会话上的主动驱动开销**：每个已提交事件都要过每个已注册单元的 `apply`。按构造，单元的逐事件开销很低（全量值规则），不匹配的事件返回同一引用，且已注册领域的数量很小；若真出现热点路径，可以加按单元的事件类型预过滤，约定不变。
 - **投影载荷膨胀**：每个尾页携带每个已注册的 key。载荷是 UI 量级状态的全量值（一张 todo 清单、一份 goal 快照）；将来若某领域的值很大，可以在请求上加逐 key 的 opt-out 或惰性 key，模型本身不用改。
 - **命令日志体量**：每条斜杠命令两个仅日志事件；上限由人敲命令的频率决定，相对分片体量可忽略不计。
 - **重新对接的返工**：三个未合入的 PR 要变基到挪动后的地基上。这是基础设施先行的既定代价；设计台账中的迁移映射一节逐一列出每个 PR 的保留/删除清单。
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
index 040d099f38..2da4662891 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
 2026-07-28-storage-root-and-derived-medium-recovery.md: c7b423770fcca89c54d3866db7701348351cc259
-2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 54a2bbc6496bd8cce594b3ce3a105e4be6e8ff64
+2026-07-28-storage-root-and-derived-medium-recovery.zh.md: e271373662e4decfd0663133fd811ee1b9247507
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
index 54a2bbc649..e271373662 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
@@ -56,4 +56,4 @@ Status: proposed
 
 - **错误分类失误导致自动删除健康文件。** 由封闭的损坏类清单缓解：重置只在三个确定性解析期代码上触发；ENOENT 本来就是「空 unit」，一切 I/O 错误（EACCES、EIO）大声传播。单发重试把爆炸半径限定为每次 open 至多一删。
 - **根迁移改变既有 checkout 的查找位置。** 在 pre-release 立场下接受（后端拒绝旧格式、无外部消费方）；上文为在乎 per-cwd `workspace.json` 内容的人记录了一次性手动搬移。
-- **`destroy` 是存储 seam 上新增的破坏性原语。** 唯一调用方是 facility 的声明重置路径；后端契约将其记档为 facility 专属，任何面向模型或面向用户的路径都触不到它。
+- **`destroy` 是存储 seam 上新增的破坏性原语。** 唯一调用方是 facility 的声明重置路径；后端约定将其记档为 facility 专属，任何面向模型或面向用户的路径都触不到它。
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
index e4acea8bc5..af319b51a7 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.md
 2026-07-29-durable-last-activity-index.md: 0e441f54a719b29a1a450c133e08cdf7d2c82e9e
-2026-07-29-durable-last-activity-index.zh.md: 9557da0a186084499dfb0f3e8d36016d5b216ae7
+2026-07-29-durable-last-activity-index.zh.md: ebc2e2167d7743eafc5a4600fe9a0f687349e1a3
diff --git a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
index 9557da0a18..ebc2e2167d 100644
--- a/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md
@@ -16,7 +16,7 @@ mtime 回答的是另一个问题：这份产物上次是什么时候被写入
 
 ## 提案
 
-把最后活动时间存到列举本就会读取的地方，也就是会话索引，这样 `summarizeCold()` 无需打开日志就能给出答案。该值由协调器计算，因为它看得到每一次追加，而且本就拥有每 id 状态；由后端负责持久化。这样它就成为 `PersistenceBackend` 契约中新增的一个要素，而不是各后端本地的账目，同时让「活动」只保留一个定义，与日志内的 `lastActivityTime()` 共用。
+把最后活动时间存到列举本就会读取的地方，也就是会话索引，这样 `summarizeCold()` 无需打开日志就能给出答案。该值由协调器计算，因为它看得到每一次追加，而且本就拥有每 id 状态；由后端负责持久化。这样它就成为 `PersistenceBackend` 约定中新增的一个要素，而不是各后端本地的账目，同时让「活动」只保留一个定义，与日志内的 `lastActivityTime()` 共用。
 
 两个已交付的后端受到的约束正好相反，本提案对它们有意采取不对称的处理：
 
diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
index c70cbb870b..80ae253198 100644
--- a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.md
 2026-08-08-semantic-composer-chain-phases.md: 7d85518e9d5e5aa3e44e443cb1b90b325b0ffc6a
-2026-08-08-semantic-composer-chain-phases.zh.md: a202b9bfeb9276cdccaa7b438036cd1236a33317
+2026-08-08-semantic-composer-chain-phases.zh.md: c0c0bca32ffcc174929c3cbef4878138e1268e98
diff --git a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
index a202b9bfeb..c0c0bca32f 100644
--- a/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
+++ b/.agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md
@@ -18,7 +18,7 @@ Status: proposed
 
 阶段词汇归声明该 slot 的领域所有，而不属于全局 slot 框架。`SlotMap` 携带确切的阶段元组，用于编译期注册；运行时 `SlotSpec` 重复该元组，作为排序依据。其他链不会获得任何 composer 术语，也无需迁移，除非它们主动声明阶段。
 
-本提案扩展 [Web subagent 对话](../../implemented/feature/2026-07-27-web-subagent-conversations.md)、[Web 权限与审批](../../implemented/feature/2026-07-23-web-permission-and-approval.md)和[计划审阅呈现](../../implemented/feature/2026-07-30-plan-review-presentation-intent.md)契约，但不取代其中任何一项。[运行时所有权子级守卫](../../implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md)仍然是防止子级新建自己负责的人类等待的权威机制。本提案落地时，不应归档任何活跃 Agent Note。
+本提案扩展 [Web subagent 对话](../../implemented/feature/2026-07-27-web-subagent-conversations.md)、[Web 权限与审批](../../implemented/feature/2026-07-23-web-permission-and-approval.md)和[计划审阅呈现](../../implemented/feature/2026-07-30-plan-review-presentation-intent.md)约定，但不取代其中任何一项。[运行时所有权子级守卫](../../implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md)仍然是防止子级新建自己负责的人类等待的权威机制。本提案落地时，不应归档任何活跃 Agent Note。
 
 ## 备选方案
 
@@ -36,7 +36,7 @@ Status: proposed
 - Composer 测试覆盖问题加只读项、审批加只读项、问题加审批加只读项、解决后回到只读项，以及所有选择器均拒绝匹配时回退到 InputBar。问题在 `interaction` 内仍排在审批之前。
 - dispose（资源释放）、HMR（热模块替换）重新注册和重新连接回放均不能留下陈旧的当选阶段；选举仍是当前所有者 props 与当前注册项的纯函数。
 - 一项无密钥组装 Web 快照固定已寻址的 one-shot 对话及其待处理交互：交互界面胜出，解决该交互后，只读界面再次出现。
-- slot、conversation、question、permission 和 subagent 的 README／JSDoc 契约共同描述阶段所有权以及交互先于限制的规则。
+- slot、conversation、question、permission 和 subagent 的 README／JSDoc 约定共同描述阶段所有权以及交互先于限制的规则。
 - 该变更不修改任何模型可见的工具定义、系统提示词章节、请求路由或会话事件。因此，浏览器选举既不产生 token 开销，也不会使 KV Cache 失效；测试会比较仅在客户端发生状态转换前后的模型请求 header。
 
 ## 风险
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
index e6fe2edcf1..ad963d6e81 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
 2026-07-06-recallable-compaction.md: ed5491e642ea7ac99fd9f4ba071a61e655f968d3
-2026-07-06-recallable-compaction.zh.md: ad3cba250973a8c8d9545a31b312cd4d3f23725f
+2026-07-06-recallable-compaction.zh.md: dabc606d0056e91f9ac473de6f166083bcee25e8
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
index ad3cba2509..dabc606d00 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
@@ -107,4 +107,4 @@ Status: proposed
 - **存根目录会占用注意力**：每次请求中包含数十张稳定的索引卡，可能稀释模型关注点；验收标准中的 bench 度量会将其与 `compact-basic` 对比。
 - **成本**：每轮摘要输入大约是当前实现的两倍；短会话的成本和质量接近当前水平，而设计收益随会话长度增长。
 - **状态漂移与职责分工泄漏** 可以通过交接探针和存根评审观察；对应措施已列为后续事项。
-- **两个后端** 会扩大维护范围；seam 契约和共享回溯消费方会限制这一范围，bench 对比则用于逐步决定默认实现。
+- **两个后端** 会扩大维护范围；seam 约定和共享回溯消费方会限制这一范围，bench 对比则用于逐步决定默认实现。
diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
index 8e61990639..be85390433 100644
--- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.md
 2026-07-14-sdk-developer-projects.md: 65d2bf66232993222832eb0f2f4f56cfcf7afd16
-2026-07-14-sdk-developer-projects.zh.md: 07bf898a7ef672a21951afaa9038a86878ae2900
+2026-07-14-sdk-developer-projects.zh.md: fc96d25dbea44d28bbc146b76fc3e81093bec976
diff --git a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
index 07bf898a7e..fc96d25dbe 100644
--- a/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
@@ -129,7 +129,7 @@ Builtin 支持集由 SDK 人工策划，不根据 NPM 依赖名称或目录约
 ## 后续工作
 
 - `dsh-sdk add [package-spec]`：统一本地插件创建与外部 Cordis 插件接入；未指定包或仓库来源时创建本地插件/工具，指定来源时增加 NPM 依赖和 `cordis.yml` 配置项，来源模型为 GitHub 仓库等扩展保留空间
-- 非交互 create/config：本期两个流程都要求 TTY，不提供供自动化调用的完整输入契约
+- 非交互 create/config：本期两个流程都要求 TTY，不提供供自动化调用的完整输入约定
 - 更多功能专用参数输入：本期产品只展示有限功能选项、secret 和少量专用值，不为 Cordis 插件配置提供通用参数界面
 
 ## 曾考虑的替代方案
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
index fab3ecc2b1..f5a16fae7e 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
 2026-07-17-sdk-follow-up-capabilities.md: 88d5d2f9bd1ce01c20177bcaee5bbe6b434bb978
-2026-07-17-sdk-follow-up-capabilities.zh.md: 998b7ec3cfddafe40537908fb61aa6d7e6f90418
+2026-07-17-sdk-follow-up-capabilities.zh.md: d54dc4d0635ef37d7196ff5cecbdd6ed093c98e3
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
index 998b7ec3cf..d54dc4d063 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
@@ -8,7 +8,7 @@ Status: proposed
 
 首个 SDK 版本通过[开发者工程 Agent Note](2026-07-14-sdk-developer-projects.md) 和 [SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md)定义的共享模型创建和编辑开发者拥有的 Cordis 工程。create 和 config 工作流仅支持交互调用，接入外部 Cordis 插件需要手工修改依赖和配置，命令行遥测没有明确的所属边界，交互分支也缺少稳定的测试策略。
 
-这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession`；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml`。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品契约。
+这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession`；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml`。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品约定。
 
 ## 提案
 
@@ -33,7 +33,7 @@ Create 和 config 使用相同的功能计划形状。create 通过上述命令
 
 ### Prompt 与工程编辑边界
 
-`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题契约公开的默认值，否则通过未回答问题快速失败；预填值通常会让流程根本不调用该 port。
+`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题约定公开的默认值，否则通过未回答问题快速失败；预填值通常会让流程根本不调用该 port。
 
 两条路径使用相同的 `Question` 对象、`FeatureConfigurator`、`SdkProject` 和 `ProjectEditSession`。因此，headless 路径只改变答案的到达方式，不改变功能解释或文件提交方式。
 
@@ -97,12 +97,12 @@ Create 和 config 测试向现有工作流注入 `PromptPort` 和脚本化输入
 ## 验收标准
 
 - Create 能依据完整结构化输入在没有 TTY 时运行；使用 `--json` 时 stdout 只输出 NDJSON；缺少必答输入时通过 `action-required` 报告，且不写入部分工程。
-- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划契约。
+- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划约定。
 - `dsh-sdk create <source>` 使用工程选定的包管理器，挂载该操作实际新增的依赖名；无法识别新增依赖时快速失败。
 - 初始化命令与每个 `dsh-sdk` 命令都进入同一条尽力而为的遥测收尾路径；明确禁用的配置项、`DO_NOT_TRACK` 或 CI 会阻止传输，遥测失败绝不改变命令结果。
 - 遥测绝不读取 `.env`；没有 `cordis.yml` 时不发送无关的 `package.json` 内容；两个符合条件的文本都经过脱敏；匿名标识符与 git 元数据无关。
 - 交互测试通过注入交互覆盖 create 和 config 决策，并断言已提交的工程文件；真实 PTY 覆盖只作为窄范围冒烟层。
-- Agent skill 说明公开的结构化输入与事件契约，不依赖包的私有导出。
+- Agent skill 说明公开的结构化输入与事件约定，不依赖包的私有导出。
 
 ## 风险
 
@@ -110,7 +110,7 @@ Create 和 config 测试向现有工作流注入 `PromptPort` 和脚本化输入
 - 没有遥测配置项时默认上报可能让开发者意外；发布前 CLI 必须让关闭方法易于发现。
 - 在 `ProjectEditSession` 挂载插件前，包管理器的 add 操作已经可能修改 `package.json`、lockfile 和安装文件；后续挂载失败会留下需要手工恢复的依赖改动。
 - GitHub 依赖可能按包管理器策略执行 preparation 或 lifecycle script；尚未解决的构建策略会带来供应链与可复现性风险。
-- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余契约。
+- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余约定。
 
 ## 参考资料
 
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml b/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
index 7dc26f8fb7..6dbffc67e2 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-08-04-task-surface.md
 2026-08-04-task-surface.md: 72fc9e12f1a02f66a02d3335ad2e8d0d4c1c3dc2
-2026-08-04-task-surface.zh.md: 087c80195f75e145da93c5557afb43a421e1050d
+2026-08-04-task-surface.zh.md: 32de8167affd48472469083a580e1dd3f98a3c24
diff --git a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
index 087c80195f..32de8167af 100644
--- a/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
+++ b/.agents/notes/proposed/feature/2026-08-04-task-surface.zh.md
@@ -10,7 +10,7 @@ Status: proposed
 
 这两种变通方案的职责归属都不合理。产品专用组件要求每种任务形态都新增触发方式并发布新版本。对于只需一个轮次的表单，生成代码所拥有的权限和生命周期成本都远超实际需要。这样做还会把展示界面而非用户结论变成持久产物。
 
-目前缺少这样一份契约：用有界、可回放的描述来定义临时 UI，并让它只属于一个会话和一次工具调用实例。产品应当负责校验、放置、交互机制和提交；agent 应当负责特定任务的文案、数据，以及从受支持组件中作出选择。
+目前缺少这样一份约定：用有界、可回放的描述来定义临时 UI，并让它只属于一个会话和一次工具调用实例。产品应当负责校验、放置、交互机制和提交；agent 应当负责特定任务的文案、数据，以及从受支持组件中作出选择。
 
 ## 提案
 
@@ -77,13 +77,13 @@ interface TaskSurfaceOption { id: string; label: string; detail?: string }
 
 Task Surface 服务通过受 schema 校验的配置定义限制。初始默认值为：规范化模型不超过 64 KiB、块不超过 64 个、字段不超过 32 个、表格行不超过 200 行、提交内容不超过 32 KiB。模型内的 ID 必须唯一；字段值必须符合其声明；未知字段会被拒绝。这些限制约束日志、DOM 和提示词成本，但不改变协议。
 
-## 工具与呈现契约
+## 工具与呈现约定
 
 `show_task_surface` 接收 `{ model: TaskSurfaceModelV1 }`。Host 解析并规范化完整模型；若该会话已有一个打开的 Task Surface，则拒绝调用；否则生成 `surfaceId`，并返回带规范化模型的规范值 `{ surfaceId, model }`。`presentationMeta` 持久化 `value.model`，使投影器和执行器不会对规范化结果产生分歧。Native 结果会指明该 Surface，并说明客户端无法渲染面板时，可以通过普通消息绕过它。随后工具调用 `exec.concludeTurn()`，防止 agent 越过所要求的人工检查点继续执行。
 
-工具定义省略 `isConcurrencySafe`。根据现有工具注册表契约，省略该字段会将每次调用归类为独占排序屏障，无需新增 `ToolDefinition` 字段。该工具只会组装到同时挂载 Host 服务和 Web 渲染器的 Web profile 中。版本 1 支持 `native` 和 `both` 工具模式；仅支持 `code` 的 profile 不会向模型公布该工具，因为 Code Mode 分发属于嵌套调用，无法把呈现元数据传到外层结果。
+工具定义省略 `isConcurrencySafe`。根据现有工具注册表约定，省略该字段会将每次调用归类为独占排序屏障，无需新增 `ToolDefinition` 字段。该工具只会组装到同时挂载 Host 服务和 Web 渲染器的 Web profile 中。版本 1 支持 `native` 和 `both` 工具模式；仅支持 `code` 的 profile 不会向模型公布该工具，因为 Code Mode 分发属于嵌套调用，无法把呈现元数据传到外层结果。
 
-浏览器安全的领域包从 `@deepseek-ai/dsh-brand` 以仅类型方式导入 `Branded` 原语，并拥有全部三个 Task Surface ID。根据[规范工具输出契约](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
+浏览器安全的领域包从 `@deepseek-ai/dsh-brand` 以仅类型方式导入 `Branded` 原语，并拥有全部三个 Task Surface ID。根据[规范工具输出约定](../../implemented/architecture/2026-07-20-canonical-tool-output-contract.md)，规范值仅存在于本次执行中。因此，回放通过 `output.presentationMeta(args, value)` 将以下带标签的载荷随 `tool/result.meta` 一并持久化：
 
 ```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
@@ -102,13 +102,13 @@ interface TaskSurfacePresentationMeta {
 
 该工具保留通用 [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md)。带 key 的 Web 行读取 `ToolResultNode` 上已经保留的带标签元数据，无需新增 render-intent 分支或呈现注册表。不支持 Task Surface 的客户端会渲染普通结果内容。
 
-Web 插件按照 [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) 和 [slot 注册](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md)契约，提供两个静态的会话作用域注册项。一个以 `show_task_surface` 为 key 的 `conversation.chat.toolview` 条目将持久 transcript（文本记录）调用实例渲染为简洁摘要和只读回放。现有 `conversation.input.dock` 中的一个 `TaskSurfaceDock` 条目是唯一可操作的挂载点：它读取活动投影，针对确切身份调用 `getActive`，并拥有字段、草稿、提交和关闭操作。Dock 与 transcript 分页相互独立，因此即使 `ToolResultNode` 位于已加载历史窗口之外，活动 Surface 仍可操作。
+Web 插件按照 [toolview](../../implemented/architecture/2026-07-23-toolview-dissolution.md) 和 [slot 注册](../../implemented/architecture/2026-07-22-slot-type-chain-implementation.md)约定，提供两个静态的会话作用域注册项。一个以 `show_task_surface` 为 key 的 `conversation.chat.toolview` 条目将持久 transcript（文本记录）调用实例渲染为简洁摘要和只读回放。现有 `conversation.input.dock` 中的一个 `TaskSurfaceDock` 条目是唯一可操作的挂载点：它读取活动投影，针对确切身份调用 `getActive`，并拥有字段、草稿、提交和关闭操作。Dock 与 transcript 分页相互独立，因此即使 `ToolResultNode` 位于已加载历史窗口之外，活动 Surface 仍可操作。
 
 Dock 遵循现有 composer chain 的回退语义。任何 `conversation.composer` 接管都会隐藏包括 `TaskSurfaceDock` 在内的回退 composer 栈，但不会将其卸载；接管结束后，同一个草稿所有者会重新出现。接管方不会获得 Task Surface 操作，也不会创建另一个编辑器。
 
 模型不能选择会话标签页、Dock 顺序、详情栏、模态框、像素位置或 z-index。以后即使改变放置位置，也只是渲染器的决策，不会改变日志中记录的模型。transcript 行绝不会成为第二个编辑器，因此同一个 Surface 不会出现相互竞争的草稿或提交所有者。
 
-## 提交契约
+## 提交约定
 
 Task Surface 领域通过 Host 传输层公开三个操作。只有 `submit` 会接纳用户消息：
 
@@ -227,14 +227,14 @@ Web 插件将未提交值保存在一个有界、按会话持久化的 slot stor
 | 包 | 职责 |
 |---|---|
 | `packages/core/agent` 和 `packages/core/agent-loop` | 为已认领的下一轮 inbox 调用实例提供通用终态结果，让 Host 观察方无需使用 Task Surface 专用类型，即可区分持久接纳和丢弃 |
-| `packages/task-surface/task-surface` | 浏览器安全的模型、带品牌类型的 ID、关联和待处理类型、解析器、限制、提交校验器／格式化器、会话事件扩展、投影单元，以及 Host 服务契约 |
+| `packages/task-surface/task-surface` | 浏览器安全的模型、带品牌类型的 ID、关联和待处理类型、解析器、限制、提交校验器／格式化器、会话事件扩展、投影单元，以及 Host 服务约定 |
 | `packages/task-surface/tool-task-surface` | `show_task_surface`、规范输出、呈现元数据、通用 render intent、活动 Surface 检查和 `concludeTurn()` 行为 |
 | `packages/client/runtime` | 通用排队消息 `source` 投影和会话作用域的活动投影访问 |
 | `packages/client/ui-primitives` | 与 Task Surface 无关的 `MarkdownText.remoteImages` 策略，包括 `alt-only` 图片分支和 URL 策略测试 |
 | `packages/client/ui-task-surface` | 静态且可操作的 `TaskSurfaceDock`、带 key 的只读 transcript 行、消费 Task Surface 模型并以 `alt-only` 模式使用 `MarkdownText` 的声明式 Web 渲染器、按会话划分的草稿 store，以及提交客户端 |
 | `packages/host/apiproxy` | 类型化的活动 Surface 读取／提交／关闭传输、用户消息来源扩展与传递、队列操作限制，以及认领和终态结果的路由；将校验、待处理协调和接纳委托给 Task Surface 服务 |
 
-`ui-task-surface` 依赖浏览器安全的 Task Surface 领域包、客户端连接与运行时、locale、`ui-conversation` 所声明的 slot 契约、用于注册的 `ui-slots`，以及 `ui-primitives`；`ui-primitives` 不反向依赖 Task Surface。ApiProxy 依赖 Task Surface 服务契约和通用 AgentLoop 终态结果。核心 Agent 包不导入 Task Surface 类型。
+`ui-task-surface` 依赖浏览器安全的 Task Surface 领域包、客户端连接与运行时、locale、`ui-conversation` 所声明的 slot 约定、用于注册的 `ui-slots`，以及 `ui-primitives`；`ui-primitives` 不反向依赖 Task Surface。ApiProxy 依赖 Task Surface 服务约定和通用 AgentLoop 终态结果。核心 Agent 包不导入 Task Surface 类型。
 
 该实现依赖现有的消息日志、规范工具输出、带标签的 render intent、会话投影、按会话作用域声明的 slot store 和 slot 生命周期，不依赖在运行时创建客户端插件。Generated Client Plugin 工作流可以使用 Task Surface 展示审阅表单，但两个协议都不拥有或激活另一个协议。
 
@@ -250,7 +250,7 @@ Web 插件将未提交值保存在一个有界、按会话持久化的 slot stor
 
 **从工具调用中渲染任意 HTML、CSS 或 JavaScript。**不予采用，因为这会把临时交互变成可执行的客户端插件代码，却不具备代码所需的构建、预览、评估、批准或回滚生命周期。
 
-**使用大型表单扩展 `userInteraction.ask()`。**本契约不采用这种做法。`ask()` 是一种阻塞式请求／响应操作，适用于正在运行的工具必须先获得简短答案才能继续执行的情况。Task Surface 会结束当前轮次，可以在刷新后继续保持打开，并把结果提交为下一条可见用户消息。
+**使用大型表单扩展 `userInteraction.ask()`。**本约定不采用这种做法。`ask()` 是一种阻塞式请求／响应操作，适用于正在运行的工具必须先获得简短答案才能继续执行的情况。Task Surface 会结束当前轮次，可以在刷新后继续保持打开，并把结果提交为下一条可见用户消息。
 
 **每次调用都注册一个动态 `conversation.view`。**不予采用，因为视图账本是全局的，而其渲染作用域按会话划分；同时，临时任务身份会变成注册身份。一个静态的会话作用域 Dock 负责交互，一个静态带 key 的行概述已记录的调用实例；两个注册项都不使用调用实例身份。
 
diff --git a/.agents/notes/proposed/process/2026-06-11-architectural-conformance.i18n.yaml b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.i18n.yaml
index f301aae614..d0c2fe4c0c 100644
--- a/.agents/notes/proposed/process/2026-06-11-architectural-conformance.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-06-11-architectural-conformance.md
 2026-06-11-architectural-conformance.md: f7cb0d7397d4e03df225f68417da43b1fec8de62
-2026-06-11-architectural-conformance.zh.md: c82297fcbe02feed4cd04bc60730a3494b7faa4d
+2026-06-11-architectural-conformance.zh.md: 16692f765ceaeca585e6563f7dd864ac524adb77
diff --git a/.agents/notes/proposed/process/2026-06-11-architectural-conformance.zh.md b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.zh.md
index c82297fcbe..16692f765c 100644
--- a/.agents/notes/proposed/process/2026-06-11-architectural-conformance.zh.md
+++ b/.agents/notes/proposed/process/2026-06-11-architectural-conformance.zh.md
@@ -18,7 +18,7 @@ Status: proposed
 - `vendor/*` 禁止从 `packages/*` 导入。
 - 分层：dsh-llm 不导入其他 dsh 包；dsh-session 仅导入 dsh-llm；以此类推（packages/README.md 中的依赖表，强制执行）。
 
-**适配器一致性套件**位于 dsh-llm（`@deepseek-ai/dsh-llm/conformance`）：一个以适配器工厂为参数的可复用 vitest 套件，用于断言分片协议契约，包括每个块内的索引单调递增、某个索引出现 `block-end` 后不再接收增量、恰好出现一个 `finish`、用量至多出现一次、每个 `tool-call-delta` 都携带调用 id，并且及时响应 abort。当前先对 mock 运行；DeepSeek V4 适配器从第一天起继承该套件。还可以选择提供开发模式下的 `strictAdapter()` 包装层，在调试标志开启时于运行时强制执行相同规则（与 [开发模式不变式](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md) 配对）。
+**适配器一致性套件**位于 dsh-llm（`@deepseek-ai/dsh-llm/conformance`）：一个以适配器工厂为参数的可复用 vitest 套件，用于断言分片协议约定，包括每个块内的索引单调递增、某个索引出现 `block-end` 后不再接收增量、恰好出现一个 `finish`、用量至多出现一次、每个 `tool-call-delta` 都携带调用 id，并且及时响应 abort。当前先对 mock 运行；DeepSeek V4 适配器从第一天起继承该套件。还可以选择提供开发模式下的 `strictAdapter()` 包装层，在调试标志开启时于运行时强制执行相同规则（与 [开发模式不变式](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md) 配对）。
 
 ## 计划
 
diff --git a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml
index e23ab9913b..5dd07029b3 100644
--- a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md
 2026-07-13-human-review-skill-maintenance.md: 76391bd110b7a86b194a9340ffcf7cc4602d1d2e
-2026-07-13-human-review-skill-maintenance.zh.md: e442a39618a53ffdc130c94874a482315943caff
+2026-07-13-human-review-skill-maintenance.zh.md: 8ebff759cf29fa7773e4b883f83c231f88e153d2
diff --git a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
index e442a39618..8ebff759cf 100644
--- a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
+++ b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
@@ -28,9 +28,9 @@ flowchart TD
   K --> L["Leave a reviewed local working-tree diff"]
 ```
 
-### 采集契约
+### 采集约定
 
-每个选定的 PR 都会在获取任何反馈前接受过滤：其 merge commit 必须是 `origin/master` 的祖先。merge commit 可达性是唯一的资格检查：直接 base 为功能分支的堆叠 PR，只要该 base 随后已经进入 master，就会被纳入，因为无论中间 stack 如何，评审人评论的代码此时已经在 master 上。工具还会解析落地 merge 的目标父级；无法重建的落地形态会记录到 `skipped-pulls.json` 并跳过。单个 PR 在预检、采集或证据收集时失败，只会被跳过，不会中止整次运行。如果时间窗口会超过 GitHub 搜索的 1,000 条结果上限，搜索阶段会明确失败，避免无提示地遗漏已合并 PR。采集阶段会完整读取内联评审评论、评审提交和 PR commit 的分页连接。不采集 PR 对话评论，因为强制推送后，GitHub 当前状态无法证明哪个仍然存在的 commit 位于评论之前，采纳契约因此必然会无条件排除这些评论。只有当 GitHub 报告 actor `type` 为 `User`，并且创建时间与最后编辑时间都严格早于 PR 合并时，工作流才接受已采集反馈；与合并同一时间戳的编辑视为合并后操作。评审提交使用 GraphQL 的 `lastEditedAt`，因为 REST 表示不含编辑时间。
+每个选定的 PR 都会在获取任何反馈前接受过滤：其 merge commit 必须是 `origin/master` 的祖先。merge commit 可达性是唯一的资格检查：直接 base 为功能分支的堆叠 PR，只要该 base 随后已经进入 master，就会被纳入，因为无论中间 stack 如何，评审人评论的代码此时已经在 master 上。工具还会解析落地 merge 的目标父级；无法重建的落地形态会记录到 `skipped-pulls.json` 并跳过。单个 PR 在预检、采集或证据收集时失败，只会被跳过，不会中止整次运行。如果时间窗口会超过 GitHub 搜索的 1,000 条结果上限，搜索阶段会明确失败，避免无提示地遗漏已合并 PR。采集阶段会完整读取内联评审评论、评审提交和 PR commit 的分页连接。不采集 PR 对话评论，因为强制推送后，GitHub 当前状态无法证明哪个仍然存在的 commit 位于评论之前，采纳约定因此必然会无条件排除这些评论。只有当 GitHub 报告 actor `type` 为 `User`，并且创建时间与最后编辑时间都严格早于 PR 合并时，工作流才接受已采集反馈；与合并同一时间戳的编辑视为合并后操作。评审提交使用 GraphQL 的 `lastEditedAt`，因为 REST 表示不含编辑时间。
 
 ### 采纳证据
 
@@ -40,13 +40,13 @@ flowchart TD
 
 两个独立配置的评审适配器，会从来源（`human-authored`、`forwarded-automation` 或 `unclear`）和采纳情况（`adopted`、`rejected` 或 `unclear`）两个维度，对每个符合条件的条目进行分类。只有两个适配器都判定为 `human-authored` 加 `adopted` 的条目才会继续。采纳集合随后会针对当前 skill 接受第二次独立分类：候选项、已经覆盖、实现专用或并非反馈。单个条目即可符合要求，不要求重复出现。意见分歧会得到一次有界的重新评估；如果仍未解决，则继续保留在运行产物中。单个批次的适配器输出如果未通过 schema 或 id 校验，系统会在批次层按不采纳处理：其中的每条反馈都标记为 unclear 并路由到 `excluded`，而不是中止整次运行；有问题的原始输出会保存在该次运行的私有产物中，供调试使用。如果任一适配器在某项操作的任何非空批次中都没有返回有效结果，运行会以非零状态退出并发出失败记录，而不会报告「没有候选项」。
 
-主适配器只根据结构化的共同指引起草，绝不接收原始评审文本。根据适配器作者的契约，它保持无工具且只读：返回完整的候选文件内容，由工具校验后写入唯一目标。两个适配器随后评审同一份完整 skill diff；阻塞性问题会进入有界修订循环，而且两者必须批准同一版修订。工具会在运行文档和 lint 检查前，以及报告成功前，再次拒绝暂存改动和目标 skill 之外的编辑，因此检查或并发进程无法通过添加其他路径混入。失败时，工具使用尽力而为的比较并交换回滚自身写入，以免覆盖维护者的并发编辑。成功时，它保存一份候选资料包，其中包含源 `origin/master` commit、源 skill blob ID、已评审 diff、完整候选文件、源反馈 ID 与 URL、落地证据范围、适配器判定和检查结果；它绝不提交、推送、打开或合并 PR。
+主适配器只根据结构化的共同指引起草，绝不接收原始评审文本。根据适配器作者的约定，它保持无工具且只读：返回完整的候选文件内容，由工具校验后写入唯一目标。两个适配器随后评审同一份完整 skill diff；阻塞性问题会进入有界修订循环，而且两者必须批准同一版修订。工具会在运行文档和 lint 检查前，以及报告成功前，再次拒绝暂存改动和目标 skill 之外的编辑，因此检查或并发进程无法通过添加其他路径混入。失败时，工具使用尽力而为的比较并交换回滚自身写入，以免覆盖维护者的并发编辑。成功时，它保存一份候选资料包，其中包含源 `origin/master` commit、源 skill blob ID、已评审 diff、完整候选文件、源反馈 ID 与 URL、落地证据范围、适配器判定和检查结果；它绝不提交、推送、打开或合并 PR。
 
 ### 评审适配器协议
 
-每个私有可执行文件从 stdin 接收有字节上限、带版本的 JSON 请求，并在 stdout 返回有字节上限且符合 schema 的 JSON。两个评审命令解析为逐字节相同的可执行文件时，工具拒绝运行；这只是最低限度的机械检查；确保主适配器与次适配器由独立提供方或模型驱动，仍是部署运维方的责任。`access` 与 `tools` 字段是适配器作者承担的契约标记，不是 OS 沙箱：评审子进程在清理后的环境中 spawn，其 `cwd` 指向私有运行目录而非仓库根目录；反馈包装在带随机数的 `<untrusted-feedback nonce="…">` 块中，每个提示词都会要求模型把它视为数据；128 位随机数防止不受信任的正文伪造结束标签。每个子进程都采用有界、感知中止的进程树清理。适配器作者把每项操作实现为纯只读推理（inference）；即使 `edit` 操作也只会在 JSON 中返回完整候选内容，由工具校验后写入唯一目标。每个生产 `git`／`gh`／检查命令同样在清理后的环境中 spawn，避免 pre-push 钩子的路由变量无提示地重定向维护工具。候选写入与失败回滚会针对最近一次写入内容使用尽力而为的比较并交换；回滚还会取消暂存目标，避免由适配器或检查暂存的候选项在失败运行后遗留并进入之后的 commit。
+每个私有可执行文件从 stdin 接收有字节上限、带版本的 JSON 请求，并在 stdout 返回有字节上限且符合 schema 的 JSON。两个评审命令解析为逐字节相同的可执行文件时，工具拒绝运行；这只是最低限度的机械检查；确保主适配器与次适配器由独立提供方或模型驱动，仍是部署运维方的责任。`access` 与 `tools` 字段是适配器作者承担的约定标记，不是 OS 沙箱：评审子进程在清理后的环境中 spawn，其 `cwd` 指向私有运行目录而非仓库根目录；反馈包装在带随机数的 `<untrusted-feedback nonce="…">` 块中，每个提示词都会要求模型把它视为数据；128 位随机数防止不受信任的正文伪造结束标签。每个子进程都采用有界、感知中止的进程树清理。适配器作者把每项操作实现为纯只读推理（inference）；即使 `edit` 操作也只会在 JSON 中返回完整候选内容，由工具校验后写入唯一目标。每个生产 `git`／`gh`／检查命令同样在清理后的环境中 spawn，避免 pre-push 钩子的路由变量无提示地重定向维护工具。候选写入与失败回滚会针对最近一次写入内容使用尽力而为的比较并交换；回滚还会取消暂存目标，避免由适配器或检查暂存的候选项在失败运行后遗留并进入之后的 commit。
 
-### 推广契约
+### 推广约定
 
 推广辅助工具从刷新至 `origin/master` 的干净 checkout 开始；当前 skill blob 与资料包中记录的源 blob 不同时，它拒绝应用候选项。运维方随后重新运行维护分析，或手动把 diff 变基后重新评审候选项；辅助工具绝不会用陈旧的完整文件输出替换较新的 `SKILL.md`。应用仍然有效的候选项后，它会打开 draft PR，其正文列出源反馈 URL 或 ID、用作采纳证据的落地 commit 范围、来源运行、检查结果和任何运维方编辑。原始适配器提示词与响应保持私有，但仓库评审人会获得足够的来源信息，以判断每条提议规则是否确实来自已采纳的人类反馈。
 
@@ -62,7 +62,7 @@ flowchart TD
 - **每次新评论都运行**：不予采纳，因为一轮评审会产生许多相关评论，并且缺少判断采纳情况所需的最终产物。
 - **把合并或讨论串解决视为采纳**：不予采纳，因为 PR 可能在反馈被拒绝、被取代或刻意不解决的情况下合并。
 - **自动创建或合并仓库改动**：不予采纳，因为工具首先需要通过有用的定期输出积累可信记录。维护者检查并通过普通仓库评审推广本地 diff。
-- **从已经修复的 bot 问题中学习**：不予采纳，因为来源契约限定为人类评审反馈。系统会在分析前按 actor 类型过滤，并通过来源评审排除转发自动化问题的人类账号。
+- **从已经修复的 bot 问题中学习**：不予采纳，因为来源约定限定为人类评审反馈。系统会在分析前按 actor 类型过滤，并通过来源评审排除转发自动化问题的人类账号。
 - **让同一个评审人既当作者又作最终裁决**：不予采纳，因为独立判定能在不受支持的概括进入 skill 之前暴露问题。
 
 ## 验收标准
@@ -80,6 +80,6 @@ flowchart TD
 
 - **根据 committer 时间戳推断因果关系。** 反馈 commit 基线通过比较 GitHub commit 时间戳与反馈创建时间戳选出；committer 时钟偏差与重写仍会留下误判采纳的残余窗口。与 GitHub 的 PR 事件流交叉比对可以进一步收紧，但需要采集定期工具作用域以外的事件。
 - **两个「非候选项」分类结果会直接路由到 `excluded`，不进入争议轮次。** 两个分类器都判断「不是候选项」，但对非候选原因意见不一时（例如 `covered` 与 `specific`），该条目会被排除而不是重新评估。两个分类器都同意它不会形成新的评审行为，所以争议轮次不会改变结果。
-- **超出字节哈希差异的双评审人独立性属于部署契约。** 两个命令解析为逐字节相同的可执行文件时，工具拒绝运行，但它无法验证两个不同包装层是否由不同提供方或模型驱动。运维方必须配置相互独立的主适配器与次适配器。
+- **超出字节哈希差异的双评审人独立性属于部署约定。** 两个命令解析为逐字节相同的可执行文件时，工具拒绝运行，但它无法验证两个不同包装层是否由不同提供方或模型驱动。运维方必须配置相互独立的主适配器与次适配器。
 - **候选写入与回滚使用尽力而为的比较并交换。** POSIX 上基于文件的比较并交换并不真正原子；窗口持续一个事件循环周期。该工具面向单用户定期维护，不考虑真正并发的编辑器。
 - **单维护者风险。** 由于机制位于单台机器，服务中断后，skill 维护会完全停止，直到运维方恢复服务，或通过一篇后续 Agent Note 把机制移交给新维护者。
diff --git a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
index 5418a920e5..e4cee10cc2 100644
--- a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.md
 2026-08-04-artifact-first-npm-baseline-publication.md: e79a988531ac266d72f7d2c036bdd10f3e4520a9
-2026-08-04-artifact-first-npm-baseline-publication.zh.md: d7322547c665700aeffce77ea0bb39f622220fe3
+2026-08-04-artifact-first-npm-baseline-publication.zh.md: 21581eb0d4ee3fad6217a2b8f2310d2fddded3a4
diff --git a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
index d7322547c6..21581eb0d4 100644
--- a/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
+++ b/.agents/notes/proposed/process/2026-08-04-artifact-first-npm-baseline-publication.zh.md
@@ -40,11 +40,11 @@ pack 阶段按以下顺序执行：
 
 拉取请求 CI 不会调用 pack 命令；安装态入口探测属于本地发布检查，而不是合并门禁。免凭据 CI 执行、其他每个 bin 与公开运行时入口的包自有探测、workflow artifact 传递及受保护 publish job 仍属于提案范围。
 
-## 发布 payload 契约
+## 发布 payload 约定
 
 发布包只携带消费方需要的构建产物。`package.json#files` 禁止包含 `src` 和 `lib/types/**/*.d.ts.map`；tarball 内容门禁还要独立确认不存在任何 `package/src/**` 与 `package/**/*.d.ts.map`，避免 manifest pattern 或 pack 行为绕过静态约束。运行时 JS、声明文件 `.d.ts`、配置、资源、worker 文件和 bundle 动态 chunk 必须按实际入口闭包收齐。
 
-源码 manifest 可以保留 `exports["./src/*"]`，供本仓库的源码平面解析使用；该 export 不代表源码会进入发布 payload，也不属于已发布包的消费方契约。静态门禁必须分别检查源码平面与发布 payload，不能通过删除 source export 来掩盖错误的 workspace 解析，也不能通过发布 `src` 来修补缺失的构建产物。
+源码 manifest 可以保留 `exports["./src/*"]`，供本仓库的源码平面解析使用；该 export 不代表源码会进入发布 payload，也不属于已发布包的消费方约定。静态门禁必须分别检查源码平面与发布 payload，不能通过删除 source export 来掩盖错误的 workspace 解析，也不能通过发布 `src` 来修补缺失的构建产物。
 
 每个 tarball 必须不含 `workspace:` specifier，并且所有指向本次发布集合的内部依赖与对等依赖（peer dependency）都必须精确等于本次派生版本，禁止使用 `^`、`~` 或其他 semver 范围跨越 commit 基线。除了明确仅供源码平面使用的 `exports["./src/*"]`，package manifest 中声明的每个消费方入口都必须指向 tarball 内存在的文件；动态 import、运行时拼接路径和非 export 资源不能只靠 manifest 检查，必须由安装后执行覆盖。
 
@@ -87,7 +87,7 @@ PR 与普通 push 可以运行无凭据的 pack-and-test 信号，从而在合
 
 **只运行 `dsh --help`。** 不采用，因为 Commander 可以在加载 TUI、Web 或 headless 动态入口之前输出帮助并退出。它无法证明默认生产启动路径完整。
 
-**把 `src` 和声明映射一起发布以降低漏文件风险。** 不采用，因为源码平面不是生产运行时的后备路径；扩大 payload 会掩盖 bundle 闭包错误，并把本地调试产物变成无意的发布契约。
+**把 `src` 和声明映射一起发布以降低漏文件风险。** 不采用，因为源码平面不是生产运行时的后备路径；扩大 payload 会掩盖 bundle 闭包错误，并把本地调试产物变成无意的发布约定。
 
 **要求真正的跨包原子发布。** 不采用，因为 npm 注册表没有相应事务。不可变 release bundle、发布前全量验证、integrity 比对与幂等恢复提供可实现的边界，同时明确保留部分上传短暂可见的限制。
 
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
index af8cad7d63..76abf19851 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
 2026-07-04-prune-dead-core-spine-surface.md: 7ee7ffc6e8c0f3672c98be6e23ef45a1abfc2b4e
-2026-07-04-prune-dead-core-spine-surface.zh.md: b65d607c1736545089c7116f8a14ab6e7510a8e1
+2026-07-04-prune-dead-core-spine-surface.zh.md: 69470658683f70ccc7ed71313654b769c3211cc9
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
index b65d607c17..6947065868 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
@@ -6,31 +6,31 @@ Status: proposed
 
 ## 问题
 
-若干包根导出、结果字段和便利方法没有生产消费方。它们之所以存活，要么是因为测试通过公开入口导入了内部实现，要么是因为某个类型预期了一个从未出现的调用者。每一项单独看都很小，但合在一起，它们扩大了 SDK 契约、生成的 catalog、文档和回归矩阵，却没有支撑任何已交付的路径。
+若干包根导出、结果字段和便利方法没有生产消费方。它们之所以存活，要么是因为测试通过公开入口导入了内部实现，要么是因为某个类型预期了一个从未出现的调用者。每一项单独看都很小，但合在一起，它们扩大了 SDK 约定、生成的 catalog、文档和回归矩阵，却没有支撑任何已交付的路径。
 
 生产语料库是 `packages/*/*/src`、示例源码/配置和运行时脚本。测试、包 README 和 Agent Note 行文是发布的证据，但不是固定调用者。`cordis_inspect` 使 `packages/self-modification/tool-cordis/src/api-catalog.ts` 对模型可见，`cordis_mount` 可以通过受保护的真实服务代理调用注入的服务，因此 catalog 中的服务方法和返回形状是真正的动态产品接口。下表因此区分「没有固定的仓库调用者」与「不可达」：涉及 catalog 词汇的行有意收缩模型编写的 mount 能发现和调用的内容，而包根实现辅助函数并不通过该服务门面可达。精确符号搜索得出以下清单：
 
 | 接口 | 生产证据 | 简化方式 |
 | --- | --- | --- |
-| `SurfaceManager.invalidate()` | 只有其单元测试调用它；seeding 在惰性创建的 manager 存在之前就已完成，且会话从不替换其日志引用。 | 删除它及其不可能触发的整体替换契约。 |
+| `SurfaceManager.invalidate()` | 只有其单元测试调用它；seeding 在惰性创建的 manager 存在之前就已完成，且会话从不替换其日志引用。 | 删除它及其不可能触发的整体替换约定。 |
 | `ToolExecutionResult.callId` | 每个钩子已经接收不可变的 `ToolExecution`；循环和 ACP（Agent Client Protocol）通过调用/会话事件关联。没有消费方读取这个重复的结果字段。 | 移除该字段、复制/不匹配守卫，以及证明该重复不可能不一致的测试。 |
 | `ReactLoopAgent` 根导出 | 包外的命名导入都是测试；生产代码面向 `Agent` 编程，通过 `ctx.agents` 创建/恢复。 | 将返回类型和接口类型设为 `Agent`，将具体循环类改为包内部；保留有意设计的同步、仅配置的 `AgentLoop.create()` 路径。 |
-| `workflow-workerthread` 的 protocol/runtime/session 再导出与命名的 `WorkerWorkflowEngine` | 所有通过包名导入的消费方都使用默认引擎；工作流 Agent Note 已将 worker 协议格式（wire format）定义为私有。 | 保留默认插件类/配置契约；移除重复的命名类导出，将协议模块保持为源码私有。 |
-| `code-runtime-worker` 的 protocol/bootstrap 再导出 | 包外的生产/e2e 消费方使用 `WorkerCodeRuntime` 和配置，而非 `BootstrapPort`、`PatchableStream` 或 worker 消息/启动类型。 | 保留运行时类/配置契约，将其协议格式/bootstrap 词汇改为源码私有。 |
+| `workflow-workerthread` 的 protocol/runtime/session 再导出与命名的 `WorkerWorkflowEngine` | 所有通过包名导入的消费方都使用默认引擎；工作流 Agent Note 已将 worker 协议格式（wire format）定义为私有。 | 保留默认插件类/配置约定；移除重复的命名类导出，将协议模块保持为源码私有。 |
+| `code-runtime-worker` 的 protocol/bootstrap 再导出 | 包外的生产/e2e 消费方使用 `WorkerCodeRuntime` 和配置，而非 `BootstrapPort`、`PatchableStream` 或 worker 消息/启动类型。 | 保留运行时类/配置约定，将其协议格式/bootstrap 词汇改为源码私有。 |
 | ACP 的 `agentOptions` 根导出 | 该辅助函数只有同文件和 ACP 测试消费方；唯一的包外生产消费方挂载的是插件命名空间。 | 保留 `name`、`inject`、`Config`、`AcpConfig` 和 `apply`；将 `agentOptions` 改为源码私有，通过桥接层行为测试。 |
 | `providerWording` 与 `completedTurnPrefix` 根导出 | 各有一个同包生产调用者；只有 balanced-prefix 辅助函数有一个同包白盒测试。 | 改为源码私有，测试提供方行为。 |
 | `depthOf`、`SubagentDepthError`、`waitForExit` 与 `exitsWithin` 根导出 | 生产 subagent 后端消费的是进程内 runner 和子进程构造/dispose（资源释放）辅助函数，而非这些强制机制和测试内部实现。`SENSITIVE_ENV_PATTERN` 不在其中，因为 SDK helper 会将它应用于调用方传入的环境。 | 保留深度与退出行为，但将剩余辅助函数和 error 改为源码私有；通过 spawn 和 dispose 测试。保持共享凭据正则公开。 |
-| `PersistenceCoordinator.inits`、后端 `inits` 访问器、`seedCoversPrefix` 与 `assertSerializable` | 访问器为白盒测试而存在；`seedCoversPrefix` 没有包外生产导入者；`assertSerializable` 没有生产调用者，且与 coordinator append 边界的无损快照重复。 | 通过 `session/flush` 观察初始化，将 `seedCoversPrefix` 改为源码私有，删除 `assertSerializable`。保留两个后端、`SessionHeader` 和 SQLite 的版本契约。 |
+| `PersistenceCoordinator.inits`、后端 `inits` 访问器、`seedCoversPrefix` 与 `assertSerializable` | 访问器为白盒测试而存在；`seedCoversPrefix` 没有包外生产导入者；`assertSerializable` 没有生产调用者，且与 coordinator append 边界的无损快照重复。 | 通过 `session/flush` 观察初始化，将 `seedCoversPrefix` 改为源码私有，删除 `assertSerializable`。保留两个后端、`SessionHeader` 和 SQLite 的版本约定。 |
 | `LlmError.status` 与回放 status | 适配器/回放填充它，但生产分支基于稳定的错误码/消息判断，从不读取原始 status。 | 移除未读字段和回放管道，保留错误分类。 |
-| `BlockAssembler.push()` 返回值 | 两个生产调用者都忽略返回的已完成块。 | 返回 `void`；保留有意公开的 `blocks()`/`message()` 契约。 |
+| `BlockAssembler.push()` 返回值 | 两个生产调用者都忽略返回的已完成块。 | 返回 `void`；保留有意公开的 `blocks()`/`message()` 约定。 |
 | `compactRegion` 的独立 `session` 参数 | 固定调用方传入的对象就是 `agent.session` 中已有的对象；模型可见的 mount API 也可以调用该方法，但同时接受两个独立对象，会让挂载的插件传入不一致的组合。 | 保留手动 region seam，同时有意将其收窄为以 `agent.session` 为唯一真源。 |
 | `CompactionResult.startSeq`、`summarySeq`、`endSeq` 与 `summary` | 生产消费方只读取 shadowed range/seq/token 统计；持久日志拥有 summary 和事件标识。 | 移除四个结果回显，保留两个共享的 transcript（文本记录）渲染器。 |
 | `BasicCompactService` 的估算/摘要方法可见性 | 没有包外生产调用者调用这五个方法；已实现的 Agent Note 只将 `estimateContentTokens()` 和 `summarize()` 命名为子类钩子。 | 将这两个方法改为 `protected`，其余三个编排专用的估算器改为 private。 |
 | `CodeLogEntry.source`/`level` 与 `RunCodeMeta.dispatches` | 每个生产消费方都将日志映射为文本；没有 presenter/模型路径读取其他字段或持久化的 dispatch 计数。 | 将 code-runtime 日志改为字符串（或纯文本条目），移除 result-meta 的 dispatch 管道；保留用于生成确定性 dispatch id 的本地计数器。 |
 | `CodeRuntime.language` 与 `CodeRuntime.isolation` | worker 后端提供唯一的生产值，而 Code Mode 及其他所有生产调用方只调用 `run()`。 | 移除未读描述符，同时保留 worker 的语言、隔离、预算、取消与资源释放行为。 |
 | `ToolNotFoundError.toolName`、`SystemPrompt.config` 与 `BashTask.command` | 每个存储的公开值都没有生产读取者。 | 移除未读字段，保留错误消息、已解析的配置行为和任务生命周期。 |
-| 后端包根实现辅助函数 | 下方精确清单仅通过相对路径的同包导入调用。生产命名空间导入挂载的是保留的插件契约，不读取这些属性；命名根消费方都是测试。 | 保留每个适配器/提供方/服务及其配置/错误契约；停止在包根导出所列辅助函数/常量。 |
-| 消费方包根实现辅助函数 | 下方精确清单只有同包生产调用者。生产命名空间导入挂载的是插件契约，不读取辅助属性；命名根消费方都是测试。 | 保留插件契约和稳定的错误码；将测试迁移到包内模块或公开行为，停止在包根导出所列辅助函数。 |
+| 后端包根实现辅助函数 | 下方精确清单仅通过相对路径的同包导入调用。生产命名空间导入挂载的是保留的插件约定，不读取这些属性；命名根消费方都是测试。 | 保留每个适配器/提供方/服务及其配置/错误约定；停止在包根导出所列辅助函数/常量。 |
+| 消费方包根实现辅助函数 | 下方精确清单只有同包生产调用者。生产命名空间导入挂载的是插件约定，不读取辅助属性；命名根消费方都是测试。 | 保留插件约定和稳定的错误码；将测试迁移到包内模块或公开行为，停止在包根导出所列辅助函数。 |
 
 ### 分组辅助导出清单
 
@@ -43,18 +43,18 @@ Status: proposed
 
 ## 提案
 
-以一次有界的、协调的公开接口清理，移除或降级上述每一行。同步更新包 README、JSDoc、生成的 API/事件 catalog、type-equiv 记录、必要的 exports map 以及测试，使测试通过所属的公开 seam 验证行为，而非保留仅为测试而存在的入口。不折叠任何能力 seam、LLM（大语言模型）适配器、持久化后端或生命周期完全停稳契约。
+以一次有界的、协调的公开接口清理，移除或降级上述每一行。同步更新包 README、JSDoc、生成的 API/事件 catalog、type-equiv 记录、必要的 exports map 以及测试，使测试通过所属的公开 seam 验证行为，而非保留仅为测试而存在的入口。不折叠任何能力 seam、LLM（大语言模型）适配器、持久化后端或生命周期完全停稳约定。
 
 ## 曾考虑的替代方案
 
-**保留测试便利函数和自包含的结果字段为公开。** 公开辅助函数可以让白盒测试更方便，自包含的结果字段看起来更易用，未来的嵌入者可能需要具体循环类或枚举方法。这些好处是假设性的；当前它们让每处实现和文档都要解释没有已交付调用者能观察到的状态。真正的消费方可以引入它所需的最小契约，其所有权和失败语义明确。
+**保留测试便利函数和自包含的结果字段为公开。** 公开辅助函数可以让白盒测试更方便，自包含的结果字段看起来更易用，未来的嵌入者可能需要具体循环类或枚举方法。这些好处是假设性的；当前它们让每处实现和文档都要解释没有已交付调用者能观察到的状态。真正的消费方可以引入它所需的最小约定，其所有权和失败语义明确。
 
 **保留所有 catalog 成员以供模型编写的 mount 使用。** 自引用工具集是一条真实的通用消费路径，而非生成文档的噪音。然而，它的价值来自准确、可组合的服务接口，而非无限期保留重复字段或不一致的参数对；上述每一项 catalog 收缩都移除了在同一次执行、同一个 agent（智能体）或同一结果中其他位置已可获得的事实，并在同一变更中更新 API 参考。
 
 ## 验收标准
 
 - 精确符号搜索显示：在本 Agent Note 及任何已实现 Agent Note 修正之外，没有被移除的接口。
-- 本 Agent Note 列出的每个接口均按指定方式缺失或降级；清单之外有意保留的扩展/测试契约不变。
+- 本 Agent Note 列出的每个接口均按指定方式缺失或降级；清单之外有意保留的扩展/测试约定不变。
 - 工具执行、上下文压缩（context compaction）、两个 LLM 适配器、两个持久化后端、工作流隔离以及 agent 创建/恢复保持其已交付行为。
 - 类型检查、覆盖率、快照、doc-sync（文档同步门禁）、module-graph 校验、构建和 hygiene 通过。
 
diff --git a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml
index 34eeca606c..7bea4132ff 100644
--- a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml
+++ b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md
 2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md: 236139f9198f178d44cdf0867cbad2377a127359
-2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md: e636bba5b7d69774b2eb5eccea1f3272211dedf2
+2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md: 650217e936aa65884e8fb4fed0358406c78e9931
diff --git a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
index e636bba5b7..650217e936 100644
--- a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
+++ b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
@@ -14,7 +14,7 @@ Status: rejected — landstrip 未经实战检验（驳回时问世仅数天，
 
 当 Windows 沙箱阶段启动时，在动手编写自研 AppContainer 启动器仓库之前，先评估将 landstrip 的 Windows 后端包装为 `win32` 链运行器。评估必须回答：
 
-- **探测合成。** landstrip 没有 `--probe`；链所要求的功能探测契约必须从一次 trap 运行中合成出来。
+- **探测合成。** landstrip 没有 `--probe`；链所要求的功能探测约定必须从一次 trap 运行中合成出来。
 - **方言映射。** 拒绝与运行器失败两类 stderr 方言，以及失败关闭的退出码分类，都需要显式映射到链的词汇中。
 - **许可证。** 其二进制文件采用 LGPL-2.1-or-later 许可；在进入随产品发布的依赖闭包之前需要先做分发审查。
 - **溯源。** 自研启动器的价值在于一个约 300 行、可完整评审，并由原生 CI 逐字节锁定来源的 C 文件；而 landstrip 是单一维护者手中的一组 Rust 二进制文件。对*既有的 Linux 层级*而言，这笔权衡早有定论——不要替换它（见[沙箱 Agent Note](../../implemented/feature/2026-07-06-sandbox.md)以及该启动器自身移除 Rust 依赖的迁移记录）。而对一个我们尚未构建的层级，在第三方维护与第二个自研原生仓库之间如何取舍，是一个真正悬而未决的问题。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
index d9dd98233e..02d597f3ae 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.md
 2026-06-20-assembled-assistant-messages-only.md: edc756f71271065ec579a2becb8597190b34cdc8
-2026-06-20-assembled-assistant-messages-only.zh.md: e5f4f8a63a35f5f40c482a4a4855937cc8e6d544
+2026-06-20-assembled-assistant-messages-only.zh.md: 6f0611a57550c53a9881e551f24098869c807c3e
diff --git a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
index e5f4f8a63a..6f0611a575 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-assembled-assistant-messages-only.zh.md
@@ -27,7 +27,7 @@ ACP `session/load` 可以将先前的 assistant 消息作为完整内容块回
 
 ## 放弃了什么
 
-规范的用户会话不再能重建旧轮次的精确 token 流。它也会丢失失败或中止流的部分 assistant 输出，除非另有事件或 fixture 记录。对于当前的恢复、加载和快照契约而言，这是过大的信息损失。需要精确确定性流的测试应当直接拥有该 fixture，前提是生产会话日志为用户可见的恢复保留了足够的保真度。
+规范的用户会话不再能重建旧轮次的精确 token 流。它也会丢失失败或中止流的部分 assistant 输出，除非另有事件或 fixture 记录。对于当前的恢复、加载和快照约定而言，这是过大的信息损失。需要精确确定性流的测试应当直接拥有该 fixture，前提是生产会话日志为用户可见的恢复保留了足够的保真度。
 
 ## 相关
 
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.i18n.yaml
index 8a90d8e997..ff7497fc6c 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.md
 2026-06-20-drop-durable-step-boundaries.md: c5c4f269a378e334c4dc509d1288146d77d9a520
-2026-06-20-drop-durable-step-boundaries.zh.md: 66e6d02225eb51bd395e84114d54a0dac8389fe0
+2026-06-20-drop-durable-step-boundaries.zh.md: 32d8255638b9d8b16b24e861eb092bbc906892f8
diff --git a/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.zh.md b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.zh.md
index 66e6d02225..32d8255638 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-drop-durable-step-boundaries.zh.md
@@ -20,7 +20,7 @@ Status: rejected — `step/end` 是模型步骤已完成的持久信号；保留
 
 - `SessionEventMap` 不再包含 `step/start` 或 `step/end`。
 - agent loop 中不再有 `closeStep()` 终结路径。
-- ACP 快照和持久化契约 fixture（测试前置数据）不再期望步骤边界行。
+- ACP 快照和持久化约定 fixture（测试前置数据）不再期望步骤边界行。
 - `deriveMessages()` 和回放从步骤级事件推导出相同的消息历史。
 - [事件分类体系文档](../../../../docs/architecture.md)将轮次描述为持久化边界，将步骤描述为步骤级记录上的一个字段。
 - 会话格式版本和已记录的 fixture 被刷新；按预发布格式策略，非当前版本的已存储日志被拒绝。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
index 4c5b2d04de..6c492ef3ee 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
 2026-06-20-fold-session-persistence-interface.md: c0da160e766cf0bed532f0d11bd52e3a027dbe8b
-2026-06-20-fold-session-persistence-interface.zh.md: 93ab244429600bd15e2d8dadfa7dc218e37c2eff
+2026-06-20-fold-session-persistence-interface.zh.md: 8abdf77d2717cfed7209df72182187f75e32e241
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
index 93ab244429..8abdf77d27 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
@@ -6,20 +6,20 @@ Status: rejected — 独立的持久化接口包是为持久化后端设计的
 
 ## 问题
 
-`dsh-session-persistence` 是一个接口包，其核心概念已经由 `dsh-session` 拥有：`SessionHeader`、`SessionEvent`、`SessionId`、`session/event` 与 `session/flush`。该包额外添加了抽象的 `SessionPersistence` 服务、共享写入协调器和契约辅助工具。后端包依赖它，为实现恢复，`agent-loop`（智能体循环）还需要按需查找这个同级服务。
+`dsh-session-persistence` 是一个接口包，其核心概念已经由 `dsh-session` 拥有：`SessionHeader`、`SessionEvent`、`SessionId`、`session/event` 与 `session/flush`。该包额外添加了抽象的 `SessionPersistence` 服务、共享写入协调器和约定辅助工具。后端包依赖它，为实现恢复，`agent-loop`（智能体循环）还需要按需查找这个同级服务。
 
 当持久化还是一个全新的可替换后端设计时，能力 seam 的拆分是合理的。但在可变摘要被移除之后，这个接口包基本上只是包装了会话日志自身的存储职责。继续保持独立可能带来的仪式感多于清晰度。
 
 ## 提案
 
-将抽象的 `SessionPersistence` 服务、协调器和持久化契约辅助工具移入 `dsh-session`。JSONL 和 SQLite 仍作为独立的后端包，注册由会话包拥有的服务。这样既保留了后端可替换性，又删除了一个支撑包和一条跨包 seam。
+将抽象的 `SessionPersistence` 服务、协调器和持久化约定辅助工具移入 `dsh-session`。JSONL 和 SQLite 仍作为独立的后端包，注册由会话包拥有的服务。这样既保留了后端可替换性，又删除了一个支撑包和一条跨包 seam。
 
 实施 PR（Pull Request）应更新[能力 seam](../../implemented/architecture/2026-06-13-capability-seams.md) 指南，补充此例外：持久化不同于 bash 或 LLM（大语言模型），因为它的词汇和生命周期事件本就属于会话包的核心领域。
 
 ## 验收标准
 
 - `@deepseek-ai/dsh-session-persistence` 作为包被移除。
-- `dsh-session` 导出持久化服务类型、协调器和契约辅助工具。
+- `dsh-session` 导出持久化服务类型、协调器和约定辅助工具。
 - JSONL 和 SQLite 后端包直接依赖 `dsh-session`。
 - `agent-loop` 的恢复功能使用会话包拥有的服务键。
 - [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.md)、[共享持久化写入协调器](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)与[包文档](../../../../packages/session/session-persistence/README.md)说明后端实现为何仍保持独立。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
index 7e9b79fdeb..e92c9adf31 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.md
 2026-06-20-truncate-interrupted-turns.md: c4b0084de537927a27829eb78990c6559bd1df7d
-2026-06-20-truncate-interrupted-turns.zh.md: 2d3eca74416eff360029e3ac77f04662878a0084
+2026-06-20-truncate-interrupted-turns.zh.md: 16277f45a238c4e6cb0b36a6c8651f68cf0494a1
diff --git a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
index 2d3eca7441..16277f45a2 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-truncate-interrupted-turns.zh.md
@@ -6,7 +6,7 @@ Status: rejected — 单个轮次可以包含大量真实工作，包括多个
 
 ## 问题
 
-当前的持久化契约会保留已持久写入但从未关闭的最终轮次。加载时，`interruptedTurnClosers()` 扫描尾部，为未应答的工具调用合成 error `tool/result` 事件，在步骤处于打开状态时追加 `step/end`，追加 `turn/end { kind: 'interrupted' }`，并要求后端持久提交这次修复。协调器、JSONL 后端、SQLite 后端、会话事件词汇、不变式、文档和测试都对这条合成关闭路径进行了建模。
+当前的持久化约定会保留已持久写入但从未关闭的最终轮次。加载时，`interruptedTurnClosers()` 扫描尾部，为未应答的工具调用合成 error `tool/result` 事件，在步骤处于打开状态时追加 `step/end`，追加 `turn/end { kind: 'interrupted' }`，并要求后端持久提交这次修复。协调器、JSONL 后端、SQLite 后端、会话事件词汇、不变式、文档和测试都对这条合成关闭路径进行了建模。
 
 这是一套庞大的机制，只为保留上次崩溃轮次中的部分工作。它还会凭空创造从未发生过的事件。合成的工具结果虽然有用（因为它使提供方历史保持合法），但也意味着恢复后的日志中包含了模型可见、却并非任何工具产出的文本。当前设计在尚无已发布产品、也没有真实恢复 UX 来证明部分轮次恢复确有价值的情况下，就以最大限度保留尾部为优化目标。
 
@@ -22,7 +22,7 @@ Status: rejected — 单个轮次可以包含大量真实工作，包括多个
 - `interruptedTurnClosers()` 及其测试删除。
 - 持久化协调器的修复钩子截断后端特有的撕裂或未关闭的尾部状态，不追加关闭事件。
 - [会话持久化文档](../../../../packages/session/session-persistence/README.md)说明加载返回最后一个已完成的轮次，不包含部分最终轮次。
-- 快照与契约测试随其所固定的行为一同更新。
+- 快照与约定测试随其所固定的行为一同更新。
 - 会话格式版本与记录的 fixture（测试前置数据）刷新；按预发布格式策略，非当前版本的存储日志被拒绝，不提供迁移路径。
 
 ## 放弃的内容
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
index c62b690b4e..820638a9f6 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
 2026-07-12-collapse-workflow-to-foreground-core.md: 629e2140523c3ae7caf533de99821206d05f1b8e
-2026-07-12-collapse-workflow-to-foreground-core.zh.md: 1af80e7ca28eb0e5acf3f642244260034c57d0ab
+2026-07-12-collapse-workflow-to-foreground-core.zh.md: 9683d5a15bc7d201eaff905c440bbdf88bbc9388
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
index 1af80e7ca2..9683d5a15b 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
@@ -20,7 +20,7 @@ Status: rejected — 工作流进度是有意设计的观测接口面；应通
 
 保留已使用的核心：`agent(prompt, { schema, model })`、`parallel`、`pipeline`、`args`、并发/agent 上限、取消、有界 dispose（资源释放）、结构化结果、worker 隔离与前台工具收集。移除所有 `workflow/*` 事件及其仅供事件使用的 info/outcome 类型；移除 `phase()`、`log()`、agent 的 `label`/`phase`、phase 声明、`whenToUse` 及其 worker 消息/host 观测者；将工作流元数据收缩为工具实际使用的 name；移除仅供事件使用的 run id/meta 快照与合成的 agent-end 账本。将 `WorkflowRun` 收缩为 `result`、`cancel()` 和 `dispose()`；工具渲染请求方持有的 name。移除 `WorkflowStartRequest.signal` 及 worker host 的 input-signal listener/disarm 状态，保留调用方从其 abort signal 到 `run.cancel()` 的桥接。将 `WorkflowError` 变为单一的 fatal 错误类，不再有布尔模式或 `isFatalWorkflowError()` 辅助函数。
 
-修订已实施的动态工作流 Agent Note，并更新 seam/工具/worker README、工具 schema、生成的 catalog 与包依赖图、worker type-equiv 记录、单元测试以及工作流快照/header fixture（测试前置数据）。如果进度 UI 工作被立项，应从一份命名了父 agent/会话/工具调用的关联契约出发，而非原样复活这套协议。
+修订已实施的动态工作流 Agent Note，并更新 seam/工具/worker README、工具 schema、生成的 catalog 与包依赖图、worker type-equiv 记录、单元测试以及工作流快照/header fixture（测试前置数据）。如果进度 UI 工作被立项，应从一份命名了父 agent/会话/工具调用的关联约定出发，而非原样复活这套协议。
 
 ## 曾考虑的替代方案
 
@@ -28,7 +28,7 @@ Status: rejected — 工作流进度是有意设计的观测接口面；应通
 
 ## 验收标准
 
-- 工作流公开 seam 仅包含有生产消费方的执行、取消、结果与 dispose 契约。
+- 工作流公开 seam 仅包含有生产消费方的执行、取消、结果与 dispose 约定。
 - 不再保留任何工作流事件、phase/log 协议消息、run-id 生成器、仅供进度使用的元数据、host 配对账本或 fatal 模式分支。
 - run handle 不再有 id/meta 回显，取消在同步 `start()` 返回后只有一条持有者拥有的通道。
 - parallel/pipeline 行为、上限、取消后的完全停稳、worker 隔离、结构化输出与面向模型的工作流场景保持测试覆盖。
diff --git a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
index 306226eb1f..3da21fcadc 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
 2026-07-12-prune-unused-skill-registry-surface.md: 5a13effa04a6cd9954741a0a33ebc6fc3512fab8
-2026-07-12-prune-unused-skill-registry-surface.zh.md: f6010cba4efd3c80cab867dfdf2470ccf1495d6a
+2026-07-12-prune-unused-skill-registry-surface.zh.md: f0cca25cb642eba851b63ce784d8fb9343d1f692
diff --git a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
index f6010cba4e..f0cca25cb6 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
@@ -10,9 +10,9 @@ skill（技能）服务的嵌入式运行时子系统中，`ctx.skills.register(
 
 ## 提案
 
-移除 `SkillService.register()`、`SkillRegistration`、运行时伪提供方及保留名称规则、运行时 revision/缓存分支，以及仅用于运行时的 source/rank 规范化逻辑。需要嵌入式 skill 的测试改为注册一个小型真实提供方。保留 `providerRevision` 作为进行中发现操作的 epoch，但已完成的目录缓存仅以 cwd 为键：每次提供方变更同步清除缓存，await 之后的 revision 比较已能阻止插入陈旧结果。从 skill 契约和本地提供方副本中移除 `whenToUse`、`SkillCandidate.path` 与 `SkillDefinition.path`，同时保留提供方的 locator/root 路径；保留 `metadata`、`disableModelInvocation`、`source`、`provider`、`locator` 和 `resourceBase`，因为它们要么是有意开放的扩展词汇，要么是生产消费的字段。
+移除 `SkillService.register()`、`SkillRegistration`、运行时伪提供方及保留名称规则、运行时 revision/缓存分支，以及仅用于运行时的 source/rank 规范化逻辑。需要嵌入式 skill 的测试改为注册一个小型真实提供方。保留 `providerRevision` 作为进行中发现操作的 epoch，但已完成的目录缓存仅以 cwd 为键：每次提供方变更同步清除缓存，await 之后的 revision 比较已能阻止插入陈旧结果。从 skill 约定和本地提供方副本中移除 `whenToUse`、`SkillCandidate.path` 与 `SkillDefinition.path`，同时保留提供方的 locator/root 路径；保留 `metadata`、`disableModelInvocation`、`source`、`provider`、`locator` 和 `resourceBase`，因为它们要么是有意开放的扩展词汇，要么是生产消费的字段。
 
-同步修订 skill 系统 Agent Note、README、JSDoc、目录文件与测试。agent（智能体）作用域的系统提示词段、工具提供方和变量明确不在本提案范围内：[agent 作用域贡献者契约](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)有意允许在 `setup(agentCtx)` 期间通过 agent 拥有的上下文注册这三者，因此仓库内没有固定的作用域注册并不能证明它们未被使用。
+同步修订 skill 系统 Agent Note、README、JSDoc、目录文件与测试。agent（智能体）作用域的系统提示词段、工具提供方和变量明确不在本提案范围内：[agent 作用域贡献者约定](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)有意允许在 `setup(agentCtx)` 期间通过 agent 拥有的上下文注册这三者，因此仓库内没有固定的作用域注册并不能证明它们未被使用。
 
 ## 曾考虑的替代方案
 
@@ -20,7 +20,7 @@ skill（技能）服务的嵌入式运行时子系统中，`ctx.skills.register(
 
 ## 验收标准
 
-- skill 收集只有一条提供方驱动的路径，已完成缓存仅以 cwd 为键，revision epoch 仅用于使进行中的发现操作失效；保留的 skill 字段要么有生产读取方，要么有记录在案的有意扩展契约。
+- skill 收集只有一条提供方驱动的路径，已完成缓存仅以 cwd 为键，revision epoch 仅用于使进行中的发现操作失效；保留的 skill 字段要么有生产读取方，要么有记录在案的有意扩展约定。
 - agent 作用域的提示词段、变量、工具提供方、工具守卫，以及原生模式和 Code Mode 下的 structured-output 提交行为保持不变。
 - 类型检查、覆盖率、快照、doc-sync（文档同步门禁）、module-graph 校验、构建与 hygiene 全部通过。
 
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
index 0f5dedddd2..af897a186b 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
 2026-07-26-dependency-swaps-rejected-by-nih-audit.md: 538f6a41b4d2db72f867e98810e8e9382cbdac98
-2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: b3f7a1d9717397ee9ed50890bc024fba7d79fa9a
+2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: cc56dd44938cfe6d4c4b0aff1c714d80b8d8f5b6
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
index b3f7a1d971..cc56dd4493 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
@@ -35,7 +35,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `fast-deep-equal` 替换会话接口面的 `isDeepEqualJson`**、**以 `safe-stable-stringify` 承担 repeat-tool-guard 的规范化**：两项替换在机械层面都可行，但每一项都是拿约 17–20 行带注释、有测试的代码，去换一个核心包的第一个外部运行时依赖——在这个体量上是净亏损。
 - **以 zod/valibot 承担持久事件的严格解码器**（goal fold、tool-ralph、session）：它们是位于持久化边界、键集精确匹配、失败即大声报错、带事件专属报错信息的解码器；在仓库标准 schemastery 之外再放一个 schema 库是政策变更，不是删除。
 - **以 `gpt-tokenizer`/tiktoken 替换 token-meter**：[回放 token 计量决策](../../implemented/architecture/2026-07-15-replay-token-meter-service.md)已明确否决分词器后端；GPT 的 BPE 对 DeepSeek 模型来说也是错误的分词器，而且这个包约 350 行是回放折叠簿记，任何分词器都覆盖不了。
-- **以 `partial-json` 处理流式工具调用参数**：无可替换——按已记录的契约，参数端到端保持为原始 JSON 字符串；`JSON.parse` 只在完整载荷上运行。
+- **以 `partial-json` 处理流式工具调用参数**：无可替换——按已记录的约定，参数端到端保持为原始 JSON 字符串；`JSON.parse` 只在完整载荷上运行。
 
 **文件系统、子进程与终端：**
 
@@ -46,14 +46,14 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `shell-quote` 承担 POSIX 单引号包裹**：两个各 1 行、测试详尽的引号辅助函数，对上一个处于维护模式、有 CVE 历史、转义输出还不一样的包——安全边界不是省一行代码的地方。
 - **以 `strip-ansi` 承担 pty 净化**：pty 净化器是一台流式状态机，带跨分片的断裂序列续接和 OSC `133;D` 提示符标记提取（shell 就绪信号）；无状态的剥离器只能替掉约 20 行内层代码，全部状态机构件原样保留。`stripVTControlCharacters` 还被实证会泄漏未终止的 OSC 载荷，会话标题归一化器必须剥除它们（反欺骗）。
 - **以 `pidtree`/`ps-tree` 承担 pty 进程巡检器**：它们只给裸 PID 树；这段代码需要对抗 PID 复用的启动时间身份校验，加上 `/proc` stdin 等待检测，没有包做这些。
-- **以 `execa` 承担 subagent-subprocess 的 dispose（资源释放）阶梯**：`forceKillAfterDelay` 覆盖 SIGTERM→SIGKILL，但覆盖不了先发 stdin EOF 的协作层级，也覆盖不了「无退出沿即 reject」契约；在这里采用它意味着重写各 spawn 调用点、同时阶梯照旧保留。（测试基础设施的 spawn 管线是另一回事——见[已归档的 execa 测试基础设施决策](../../archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md)。）
+- **以 `execa` 承担 subagent-subprocess 的 dispose（资源释放）阶梯**：`forceKillAfterDelay` 覆盖 SIGTERM→SIGKILL，但覆盖不了先发 stdin EOF 的协作层级，也覆盖不了「无退出沿即 reject」约定；在这里采用它意味着重写各 spawn 调用点、同时阶梯照旧保留。（测试基础设施的 spawn 管线是另一回事——见[已归档的 execa 测试基础设施决策](../../archived/testing/2026-07-26-execa-for-test-subprocess-plumbing.md)。）
 - **以 `tree-kill` 承担 acp-snapshot 拆除与 lsp 进程终止**：那些代码行做的是排空顺序与错误传播，不是进程树遍历；lsp/bash 已经使用分离的进程组加 taskkill。
 - **在 TUI 测试驱动器上到处使用 node-pty**：已归档的 [Windows TUI 决策](../../archived/feature/2026-07-20-windows-tui-support.md)明确否决了在每个宿主上都使用 node-pty；它当时已经是 Windows 那一条腿。
 
 **服务器与 HTTP：**
 
 - **以 `msw` 替换 llm-mock-server**：这个服务器的存在意义就是在线路上制造故障——socket 销毁、SSE（Server-Sent Events）中途断连、停滞、监听前拒绝——服务对象是真实的 HTTP 适配器和子进程；进程内拦截一样都表达不了。设计归[线路故障服务器决策](../../implemented/testing/2026-07-25-scriptable-llm-wire-fault-server.md)所有。
-- **以 `hono`/`sirv` 承担 host/webserver**：核心是基于 disposer 的动态路由注册表（「注册即效果」契约、HMR 反注册）加 index HTML 变换挂点；hono 的路由器只增不减，静态中间件也无法伺服变换后的 index。总共约 244 行，确实很小。
+- **以 `hono`/`sirv` 承担 host/webserver**：核心是基于 disposer 的动态路由注册表（「注册即效果」约定、HMR 反注册）加 index HTML 变换挂点；hono 的路由器只增不减，静态中间件也无法伺服变换后的 index。总共约 244 行，确实很小。
 - **以 `@mozilla/readability`/`iconv-lite` 承担 web-fetch-local**：该提供方返回原始 HTML；字符集处理已经是内置的 `TextDecoder`；MIME 解析约 11 行；重定向跟随是同源安全策略。
 
 **SQLite 与存储：**
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 077f5fa7f2..a2196f3212 100644
--- a/README.i18n.yaml
+++ b/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write README.md
 README.md: ff4cf661a060772973629844d43758d26ac1be02
-README.zh.md: 977de7f22244ff49579393edcce66d02c5782de4
+README.zh.md: f066f406df9150355d9b2d4282e882129b7ece1e
diff --git a/README.zh.md b/README.zh.md
index 977de7f222..f066f406df 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -49,7 +49,7 @@ dsh plugin --profile tui add <package>  # install a plugin into a custom profile
 dsh --profile tui                       # boot it
 ```
 
-profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。
+profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）约定](apps/cli/README.md#profiles)。
 
 ### Headless
 
diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index 801560e7d7..162ea534b7 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/README.md
 README.md: 12108fcbff4e649d0bcb3e01e688fa334ab91b14
-README.zh.md: 9518feed1d5d40c3e5ec2d346b929118ccc08810
+README.zh.md: 37967973ed40143db0bc747875dbb6dad11d73b4
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 9518feed1d..37967973ed 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -23,4 +23,4 @@ profile 目录包含一个 `package.json`（树外插件依赖，加上 profile
 
 ## 开发
 
-生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析契约。
+生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析约定。
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 325de8db4e..a478ae60d2 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/reference/README.md
 README.md: e616b420d60e0fa372bf38950207245cb60ced98
-README.zh.md: a65140e6dc9374e21bdd3018bce45432794a7b10
+README.zh.md: 81320ecbd19012123ab7e69967cbadb088356cfe
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index a65140e6dc..81320ecbd1 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -61,7 +61,7 @@ dsh web --dump-config
 
 `DSH_TOOLS_MODE` 为进程选择 `native`、`code` 或 `both`；其他值会导致启动失败。[`config/core-web.cordis.yml`](../config/core-web.cordis.yml) 是可选的 RL 兼容 `--patch` overlay：它固定使用 `native` 模式，仅将 `DSH_SYSTEM_PROMPT` 或 `You are a helpful software engineer assistant.` 渲染为系统提示词，禁用 Workspace 指令与所有 Web 运行时提示词贡献，并且在保留随附宿主、浏览器、workspace、持久化和权限组合的同时，仅暴露持久 `bash` 和 `str_replace_editor`。
 
-`DSH_SYSTEM_PROMPT` 会传给系统提示词的 [`persona`](../../../packages/core/system-prompt/README.md#config)：完整的 `{{…}}` 分组遵循该契约的严格变量插值规则，且无法转义为字面花括号；任何已设置的值（包括空字符串）都具有权威性，因此空值会移除系统提示词，只有未设置该变量时才会选择后备值。
+`DSH_SYSTEM_PROMPT` 会传给系统提示词的 [`persona`](../../../packages/core/system-prompt/README.md#config)：完整的 `{{…}}` 分组遵循该约定的严格变量插值规则，且无法转义为字面花括号；任何已设置的值（包括空字符串）都具有权威性，因此空值会移除系统提示词，只有未设置该变量时才会选择后备值。
 
 ## 共享部署行为
 
@@ -69,7 +69,7 @@ dsh web --dump-config
 
 会话事件默认作为 OTLP/HTTP 日志流式发送。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。任何非空 `DSH_TELEMETRY_DISABLED` 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由[遥测 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)负责。
 
-空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 契约](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
+空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 约定](../../../packages/self-modification/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
 
 ## 源码启动器
 
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index 360e4b32e4..c395f05428 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/api-gateway.md
 api-gateway.md: e8aafc173dced3c4ead07421d92401411565ece6
-api-gateway.zh.md: 92681b72ffc573cde834cece19568ec3f1d515ce
+api-gateway.zh.md: 5c4f306957a65a92abe8f15159ab2d23e61ef501
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 92681b72ff..5c4f306957 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -2,7 +2,7 @@
 
 [English](api-gateway.md) | 中文
 
-本文是 TypeRT API Gateway 的当前状态参考。它描述业务 Service 如何声明一元 Remote 方法、构建如何生成 Host 与 Client 契约，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
+本文是 TypeRT API Gateway 的当前状态参考。它描述业务 Service 如何声明一元 Remote 方法、构建如何生成 Host 与 Client 约定，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
 
 ## 编程模型
 
@@ -75,7 +75,7 @@ await agentCtx.remote.goals.create({ objective: 'ship it' })
 
 Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，通过 `ctx.remote.$mount()` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 TypeRT Gateway 或业务包的 Remote JS。
 
-未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 契约，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
+未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 约定，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
 
 ## 组件职责
 
@@ -138,7 +138,7 @@ SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Ho
 
 ## 开发模式
 
-完整构建会先生成 Host 契约，再编译 Host、Client 与 Web，因此是建立或刷新所有产物的确定性入口：
+完整构建会先生成 Host 约定，再编译 Host、Client 与 Web，因此是建立或刷新所有产物的确定性入口：
 
 ```sh
 pnpm run build
@@ -153,18 +153,18 @@ pnpm run dev:web
 
 `dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 只监听带 `dshClient` 声明的 Client plugin 并重写其 `lib/client.js`，它不会分析 Host decorator，也不会生成 Remote Client DTS。
 
-只修改 Remote 方法实现体而不改变契约时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格契约，再让 Client 编译并打包新的贡献：
+只修改 Remote 方法实现体而不改变约定时，无需重新生成 TypeRT 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格约定，再让 Client 编译并打包新的贡献：
 
 ```sh
 pnpm run build:lib
 ```
 
-运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 契约，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净工作树不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
+运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净工作树不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
 
 ## 边界
 
 Remote 只处理有单个请求与单个结果的一元方法调用。Session event stream、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
 
-API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务契约允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
+API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务约定允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
 
 当前 lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。某个 Remote endpoint 若必须只接受 live 对象，需要后续增加显式的逐参数或逐 endpoint 策略，不能通过业务方法内部猜测恢复来源。
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 2436ff9027..6791ac709d 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/architecture.md
 architecture.md: f593ee5c54e5bd2cbdaa5da9f2de54b7b08ec14b
-architecture.zh.md: 5780d54aad6085ef7811dfa94377a4c2478bfb99
+architecture.zh.md: 80028f33c620b35ffc549b4f4828a23a5f930e93
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 5780d54aad..80028f33c6 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -141,7 +141,7 @@ idle inject:
 
 **模型可见 ⟺ 已记录**：在 `step/start` 进入的消息加上折叠后的 `request/header` 可以重建每个请求。该 header 会标记适配器默认值，使后续提议丢弃这些值并重新解析路由，同时不丢失显式设置。`request/context` 会在路由变化时另行记录与注册项绑定的提供方、模型及容量元数据；它不参与请求重建或 header 相等性判断。`dsh-agent-loop/invariant` 通过 `ctx.invariants` 断言可重建性（[可重建性](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)）。
 
-持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一契约（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
+持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一约定（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
 
 在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
 
@@ -149,7 +149,7 @@ idle inject:
 
 消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](subsystems/token-meter.md)。
 
-流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[契约](subsystems/llm-streaming.md)）。
+流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[约定](subsystems/llm-streaming.md)）。
 
 ## 扩展与组合
 
diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml
index 0c26b8be17..98b5a7fe23 100644
--- a/docs/cookbook/adding-a-package.i18n.yaml
+++ b/docs/cookbook/adding-a-package.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-package.md
 adding-a-package.md: 8ab603ea7b235bd2a582c9232afaca281a969448
-adding-a-package.zh.md: 8c0bc9dbd02b18a388f8e6ce91af10753c0210a2
+adding-a-package.zh.md: 400bd080b04ff5791393b56e67c1e3b9ade987de
diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md
index 8c0bc9dbd0..400bd080b0 100644
--- a/docs/cookbook/adding-a-package.zh.md
+++ b/docs/cookbook/adding-a-package.zh.md
@@ -31,7 +31,7 @@ package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-c
 | 文件 | 变更 |
 |---|---|
 | `tsconfig.base.json` | 已有分组无需编辑；新分组需为 `@deepseek-ai/dsh-*` 通配符添加 `./packages/<group>/*/src` 候选路径 |
-| `tsconfig.host.json`（Host 包）或 `tsconfig.client.json`（Client 包） | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }`——普通包恰好属于一个 aggregate，绝不两个都加。`api/remotes` 因 Host 生成契约与 Client 消费契约之间存在顺序依赖而使用仓库专属拆分，新增包不得仿照（[布局](../development.md#typescript-project-layout)） |
+| `tsconfig.host.json`（Host 包）或 `tsconfig.client.json`（Client 包） | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }`——普通包恰好属于一个 aggregate，绝不两个都加。`api/remotes` 因 Host 生成约定与 Client 消费约定之间存在顺序依赖而使用仓库专属拆分，新增包不得仿照（[布局](../development.md#typescript-project-layout)） |
 | `knip.json` | 仅当包有仓库发现机制尚未覆盖的入口时需要 |
 
 `packages/client/*` 包改为 extends `tsconfig.base.client.json`（而非 `tsconfig.base.json`）；client 插件包还需在 package.json 声明 `dshClient`、导出 `./client`、调用共享 tsdown preset（`packages/client/tsdown.client.ts`）——client 侧见 [packages/client/AGENTS.md](../../packages/client/AGENTS.md)。
@@ -74,7 +74,7 @@ Append-only, prefix-stable, replacing, or independent behavior, including the ex
 - **Consumer-visible gap** — exact boundary, consequence, or maintainer constraint.
 ````
 
-根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述三个有序 H4 字段，每个字段下有一个正文段落。引用包拥有的稳定文本：系统提示词放在引出它的字段下，用带标题的 H5 加 `markdown` 围栏表示，通常归入 `What the model sees`；其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。tool-schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。填写 `KV Cache effect` 时，应区分仅追加增长、稳定重复的前缀、替换既有请求 token 和独立模型请求，并列出会使缓存复用失效、且由本包拥有的变化。“不使缓存失效”仅表示本包保留了已有的可复用前缀；缓存是否可用以及何时淘汰不属于本包契约。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。
+根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述三个有序 H4 字段，每个字段下有一个正文段落。引用包拥有的稳定文本：系统提示词放在引出它的字段下，用带标题的 H5 加 `markdown` 围栏表示，通常归入 `What the model sees`；其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。tool-schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。填写 `KV Cache effect` 时，应区分仅追加增长、稳定重复的前缀、替换既有请求 token 和独立模型请求，并列出会使缓存复用失效、且由本包拥有的变化。“不使缓存失效”仅表示本包保留了已有的可复用前缀；缓存是否可用以及何时淘汰不属于本包约定。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。
 
 没有上下文效果或仅有消费方拥有路径的包使用 [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) 中经过审计的 `None, as ` 或 `Indirectly, through ` 语句，随后添加 `KV Cache effect` H4 和一个非空正文段落；与模型无关的通用包可以改为加入 `NO_MODEL_EXPERIENCE_SECTION`。两种情况都不要展开为对另一个包工作的描述。limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) 独立管理。[Model Experience Agent Note](../../.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md) 记录了设计动机。
 
diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml
index ca64363bd6..16439b1732 100644
--- a/docs/cookbook/adding-a-tool.i18n.yaml
+++ b/docs/cookbook/adding-a-tool.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-tool.md
 adding-a-tool.md: cb418a9118901cc6572fb17125351bdda922434b
-adding-a-tool.zh.md: d8b73a51d1dde8647e7a032648f8a6344fcc83eb
+adding-a-tool.zh.md: 22eccec67a3f941976608dc7fc1cc4120e4e1bd1
diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md
index d8b73a51d1..22eccec67a 100644
--- a/docs/cookbook/adding-a-tool.zh.md
+++ b/docs/cookbook/adding-a-tool.zh.md
@@ -2,7 +2,7 @@
 
 [English](adding-a-tool.md) | 中文
 
-面向模型的工具必须满足哪些契约，均以本文为准。如需按步骤构建第一个工具，请阅读[构建工具](../user/develop/basic/tool.md)。`packages/bash/tool-bash` 是生产级的三包示例。
+面向模型的工具必须满足哪些约定，均以本文为准。如需按步骤构建第一个工具，请阅读[构建工具](../user/develop/basic/tool.md)。`packages/bash/tool-bash` 是生产级的三包示例。
 
 ## 最小形态
 
@@ -37,7 +37,7 @@ export function apply(ctx: Context) {
 
 注册基于副作用：dispose（资源释放）插件 fiber 即注销该工具。schema 会自动流入系统提示词的组装过程。
 
-## execute() 契约的规则
+## execute() 约定的规则
 
 - **参数已为你校验。** `defineTool` 在 `execute` 运行前，会根据统一的 `ParameterSchemaSpec` 校验模型生成的 `arguments`（类型、必填键、字面量约束、恰好匹配一个分支的联合以及嵌套值——见[运行时参数校验](../../.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md)），因此 `execute` 内的 args 会匹配 `InferArgs`。显式对象节点必须声明 `additionalProperties: true | false`；隐式参数根对象保持开放。你仍需手动检查 schema DSL 无法表达的约束，例如非空字符串、正数或跨字段规则。直接注册的原始 JSON Schema 工具自行负责输入校验。
 - **注册借用你的只读定义。** 类型化的同进程贡献不是序列化边界；注册后不要修改其 schema 或替换回调。`schemas()` 只物化显式的模型可见投影。如需热替换工具，请 dispose 其所属副作用并注册替代品；回调闭包内的可变状态仍是普通的插件状态。
@@ -52,11 +52,11 @@ export function apply(ctx: Context) {
 
 通过 producer 配置控制 `run_in_background`，然后使用 `ctx.tasks.start({ kind, label, owner: exec.agent, run })` 注册任务。注册表会在进入 producer 主体前将已预先中止的调用判为失败；运行时会在 `run()` 启动工作前校验 owner 和控制面是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。成功的后台分支会返回类型化的规范句柄，如 `{ kind: 'background', taskId }`；其 Native 渲染器可以保留 `started background task bash-1` 这类供人阅读的自然语言，但 Code Mode 绝不能通过解析该文本取得 id。
 
-producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.tasks.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `task_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整契约见[后台 task 运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
+producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.tasks.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `task_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整约定见[后台 task 运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
 
 ## 执行策略与观测
 
-尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许／拒绝／询问策略（见[权限门禁示例](extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝，后续监听器无法撤销；使用 `tools/execute` 为规范分发包装截止时间／重试／指标作用域；使用 `tools/post-execute` 替换展示内容或规范值、阻止调用，或附加模型可见上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。替换内容不会阻止程序化访问 `value`；保密策略必须阻止调用或替换值。沙箱实现也可以位于工具执行器的能力 seam 之后；确切契约见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。
+尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许／拒绝／询问策略（见[权限门禁示例](extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝，后续监听器无法撤销；使用 `tools/execute` 为规范分发包装截止时间／重试／指标作用域；使用 `tools/post-execute` 替换展示内容或规范值、阻止调用，或附加模型可见上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。替换内容不会阻止程序化访问 `value`；保密策略必须阻止调用或替换值。沙箱实现也可以位于工具执行器的能力 seam 之后；确切约定见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。
 
 ## Code Mode 自动触达你的工具
 
diff --git a/docs/cookbook/adding-an-llm-adapter.i18n.yaml b/docs/cookbook/adding-an-llm-adapter.i18n.yaml
index 199a870ac9..4abdc20223 100644
--- a/docs/cookbook/adding-an-llm-adapter.i18n.yaml
+++ b/docs/cookbook/adding-an-llm-adapter.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-an-llm-adapter.md
 adding-an-llm-adapter.md: 4fcc646ed2eea8a6170027d01761887aa28b0045
-adding-an-llm-adapter.zh.md: eeeb84583fb9951745083b60385547d14f461266
+adding-an-llm-adapter.zh.md: b1dacf77cb94884d9ca8780affc391e5127f0457
diff --git a/docs/cookbook/adding-an-llm-adapter.zh.md b/docs/cookbook/adding-an-llm-adapter.zh.md
index eeeb84583f..b1dacf77cb 100644
--- a/docs/cookbook/adding-an-llm-adapter.zh.md
+++ b/docs/cookbook/adding-an-llm-adapter.zh.md
@@ -22,7 +22,7 @@ export function apply(ctx: Context, config: Config) {
 
 注册基于副作用，可安全支持 HMR（热模块替换）；每个提供方路由仅对应一个适配器，重复注册会抛出异常，多路由注册要么全部成功，要么全部失败。`options.provider` 用于选择适配器，`options.model` 是提供方模型 ID，因此动态模型目录适配器无需重新配置生命周期即可提供新模型。密钥采用 Cordis 原生方式管理：schemastery Config 带环境变量回退，通过 cordis.yml 的 `!!js process.env.MY_KEY` 注入。切勿在代码中读取自行约定的密钥文件。
 
-## 协议义务（两个实现共同验证的契约）
+## 协议义务（两个实现共同验证的约定）
 
 - 在 `finish` **之前**发出 `usage`；`finish` 之后**不再发出任何内容**。稳健做法：缓冲 finish/usage 直到提供方的流结束标记，再统一 flush（可处理提供方在末尾发送仅含 usage 的分片的情况）。
 - 工具调用的 `arguments` 全程为原始 JSON 字符串；流式片段以 `argumentsDelta` 发送。如果你的提供方返回已解析的对象，请在 `block-end` 时重新 stringify。
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index e341244f40..919a9faf5d 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/extension-cookbook.md
 extension-cookbook.md: e04f6ffcf9a32ba3ee7344db18cad113b347c667
-extension-cookbook.zh.md: c2fa2f83c39ca0eb93397f39c88265c028224c7a
+extension-cookbook.zh.md: c3370a519bb09435749d608fe7c63a5330c24f62
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index c2fa2f83c3..c3370a519b 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -64,7 +64,7 @@ export function apply(ctx: Context) {
 
 *协议驱动*将协议对端接入 `ctx.agents`；它可以服务于 UI 或自动化客户端。stdio 驱动拥有 stdout，通过工厂创建或恢复 agent（智能体），并将协议请求映射为 `followup()` 或 `cancel()`。底层提示词请求返回其持久入队回执；它不会通过关联 `MessageId` 与 `turn/end` 获得结果。整个 agent 的状态应单独发布。自动化方法可以从回执等待到下一次 idle，并概括这一显式拥有的区间；UI 通常则会持续观察开放式事件流。通过 `AgentHandle.dispose()` 拆除 agent，以使 dispose（资源释放）达到完全停稳。
 
-[`packages/acp/acp`](../../packages/acp/acp) 是仅面向自动化的完整示例：它通过 ACP（Agent Client Protocol）JSON-RPC stdio 提供全新文本会话，发出已提交的助手文本，并为其拥有的 agent 注册一次性机器权限应答器。其 [README](../../packages/acp/acp/README.md) 拥有精确的方法和生命周期契约。
+[`packages/acp/acp`](../../packages/acp/acp) 是仅面向自动化的完整示例：它通过 ACP（Agent Client Protocol）JSON-RPC stdio 提供全新文本会话，发出已提交的助手文本，并为其拥有的 agent 注册一次性机器权限应答器。其 [README](../../packages/acp/acp/README.md) 拥有精确的方法和生命周期约定。
 
 ```ts
 import type { Context } from 'cordis'
diff --git a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml b/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
index a069b8a4da..cb578de462 100644
--- a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
+++ b/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/maintaining-dsh-code-review.md
 maintaining-dsh-code-review.md: 2b5d0d926ae922f2650daac33cf35991cb71c5e5
-maintaining-dsh-code-review.zh.md: 56d274c080fcd95b6d18219f4bf0e0e7485f624e
+maintaining-dsh-code-review.zh.md: 4466565b294ede89fa34da9e76b88f4ac39748eb
diff --git a/docs/cookbook/maintaining-dsh-code-review.zh.md b/docs/cookbook/maintaining-dsh-code-review.zh.md
index 56d274c080..4466565b29 100644
--- a/docs/cookbook/maintaining-dsh-code-review.zh.md
+++ b/docs/cookbook/maintaining-dsh-code-review.zh.md
@@ -20,7 +20,7 @@
 
 某次运行产出候选版本时，macOS 会发出一条带 `dsh-code-review-promote <timestamp>` 提示的通知。
 
-1. **根据 diff 本身作出判断。** 不要因为「评审者已经批准」就直接接受：维护者契约规定最终判断由操作员作出。检查清单是否膨胀、是否有历史叙述、是否根据单次事件作出无依据的外推，以及是否与现有 skill 或权威文档重复。
+1. **根据 diff 本身作出判断。** 不要因为「评审者已经批准」就直接接受：维护者约定规定最终判断由操作员作出。检查清单是否膨胀、是否有历史叙述、是否根据单次事件作出无依据的外推，以及是否与现有 skill 或权威文档重复。
 
    ```sh
    ls ~/dsh-code-review-outputs/                         # every candidate ever produced
diff --git a/docs/cordis-primer.i18n.yaml b/docs/cordis-primer.i18n.yaml
index ec67982eb5..9e1143231e 100644
--- a/docs/cordis-primer.i18n.yaml
+++ b/docs/cordis-primer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-primer.md
 cordis-primer.md: 4bcb2c9979994ca70f92031cbdc5dd22df9c1977
-cordis-primer.zh.md: d84beac54463ec193f009f506a4c9b1bda02c243
+cordis-primer.zh.md: a18b8b37af19a610b71babbe5e67f96bb09e81b1
diff --git a/docs/cordis-primer.zh.md b/docs/cordis-primer.zh.md
index d84beac544..a18b8b37af 100644
--- a/docs/cordis-primer.zh.md
+++ b/docs/cordis-primer.zh.md
@@ -23,7 +23,7 @@ Cordis 是 DeepSeek Harness SDK 底层以 vendor 方式引入的插件框架。
 | `parallel` | 是 | 所有监听器并行观察事件 | 否 |
 | `serial` | 是 | 监听器按注册顺序观察 | 是 |
 
-分发模式是事件公开契约的一部分。新的 harness 事件通过 `@mode` 标签记录模式，以便生成的目录可以将声明与分发调用点做交叉校验。
+分发模式是事件公开约定的一部分。新的 harness 事件通过 `@mode` 标签记录模式，以便生成的目录可以将声明与分发调用点做交叉校验。
 
 <a id="cordis-waterfall-semantics"></a>
 
diff --git a/docs/cordis-tutorial/04-events.i18n.yaml b/docs/cordis-tutorial/04-events.i18n.yaml
index a78b8f690c..2914e62e30 100644
--- a/docs/cordis-tutorial/04-events.i18n.yaml
+++ b/docs/cordis-tutorial/04-events.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/04-events.md
 04-events.md: b0563c71fada3efc760ff7183bc7a82e7e86934e
-04-events.zh.md: 0999cbf116eca452e54418132fbaefe3622b2c26
+04-events.zh.md: 66b52fcb1d7ec4a81c823a7c8e016c5b17d45993
diff --git a/docs/cordis-tutorial/04-events.zh.md b/docs/cordis-tutorial/04-events.zh.md
index 0999cbf116..66b52fcb1d 100644
--- a/docs/cordis-tutorial/04-events.zh.md
+++ b/docs/cordis-tutorial/04-events.zh.md
@@ -79,7 +79,7 @@ export function apply(ctx: Context) {
 
 ## 分发模式
 
-`emit` 是 5 种分发模式之一。事件采用哪种模式是其契约的一部分，决定了监听器能否返回值、能否并发运行，以及能否彼此短路：
+`emit` 是 5 种分发模式之一。事件采用哪种模式是其约定的一部分，决定了监听器能否返回值、能否并发运行，以及能否彼此短路：
 
 | 模式 | 调用 | 语义 |
 |---|---|---|
diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml
index a00432f1d5..8f27720c45 100644
--- a/docs/defensive-patterns.i18n.yaml
+++ b/docs/defensive-patterns.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/defensive-patterns.md
 defensive-patterns.md: 6dc1708f0b9bbcb00ad4774006d6d60059accf6a
-defensive-patterns.zh.md: 2ff5cba2a94c5149f2b92b37845d23211ee7989d
+defensive-patterns.zh.md: 587d09a812857e6cf61f64bfd0e17e3386d1a772
diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md
index 2ff5cba2a9..587d09a812 100644
--- a/docs/defensive-patterns.zh.md
+++ b/docs/defensive-patterns.zh.md
@@ -8,7 +8,7 @@
 
 一个结果可以同时具有多种性质：进程可能已经超时，却仍以退出码 0 结束，因为它捕获了终止信号。每个独立事实（`timedOut`、`signal`、`exitCode`）都应单独上报；切勿把一个标志的上报嵌套在另一个标志的分支中，否则调用方可能把提前终止的运行误判为正常成功。
 
-## 跨 seam 契约两侧都要遵守
+## 跨 seam 约定两侧都要遵守
 
 当一个实现边界接收到同一结果的多种表示时，应在跨越公共 seam 前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止型 finish 分片暴露模型请求失败；middleware 缺陷与消费方缺陷仍会以异常形式抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化后的约定；通过真实消费方覆盖每种来源形式。
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 00673a9415..5e2895c8ba 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
 development.md: f7084403b30e8a6d12c4ef2b886f8fb61ed39b26
-development.zh.md: 9d3606cf741f25318c630e08e8ac84ad5ee8d345
+development.zh.md: 56df93beddbb128cac8e0bcf2adaa9dcfb72c751
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 9d3606cf74..56df93bedd 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -21,7 +21,7 @@
 pnpm install
 ```
 
-安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。
+安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。
 
 如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：
 
@@ -73,9 +73,9 @@ pnpm run build:web
 
 两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。
 
-TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
+TypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成约定构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。
 
-静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
+静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 约定 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。
 
 业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。
 
@@ -100,7 +100,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 ### Git 集成
 
-当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
+当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。
 
 安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。
 
@@ -108,7 +108,7 @@ lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
 - `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
 - `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；
-- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
+- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
 
@@ -156,10 +156,10 @@ pnpm run demo:acp
 
 ### 逐字记录类型（`ts type-equiv`）
 
-[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
 { "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
-`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。
+`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。
diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml
index 2dfe08c2fd..ab9b5cec1d 100644
--- a/docs/glossary.i18n.yaml
+++ b/docs/glossary.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/glossary.md
 glossary.md: 16409517bff623a80d6e1e00888d95f63b42f780
-glossary.zh.md: fe3138ac81f2681d7fc69cc2aede96edeb7ec176
+glossary.zh.md: a84447dd067a3364033601742c116583661cdf45
diff --git a/docs/glossary.zh.md b/docs/glossary.zh.md
index fe3138ac81..a84447dd06 100644
--- a/docs/glossary.zh.md
+++ b/docs/glossary.zh.md
@@ -8,7 +8,7 @@ DeepSeek Harness SDK 的领域词汇为每个概念规定一个规范术语。
 
 - **scope**：按 agent（智能体）划分的注册单位。一项贡献（工具、提示词片段、变量、限制、监听器）要么是*全局的*（对所有 agent 可见），要么是*带作用域的*（归属于恰好一个 [scope key](#scope-key)）。只有两层，采用扁平结构：带作用域的注册不会向下继承给 subagent；子树行为通过 [lineage](#lineage) 数据表达，从不通过 scope 结构。
 - **scope key**：scope 的不透明标识，按对象同一性比较。harness 约定：一个活跃的 agent 就是其自身 scope 的 key。<a id="scope-key"></a>
-- **agent 上下文（`agent.ctx`）**：agent 的带作用域上下文；通过它进行的注册既具有 scope 可见性，其生命周期也绑定到该 scope（同一事实决定两者），其上的监听器参与该 agent 的 scope 过滤分发。注册表主体事件可以根据各自的事件契约有意保持不过滤。
+- **agent 上下文（`agent.ctx`）**：agent 的带作用域上下文；通过它进行的注册既具有 scope 可见性，其生命周期也绑定到该 scope（同一事实决定两者），其上的监听器参与该 agent 的 scope 过滤分发。注册表主体事件可以根据各自的事件约定有意保持不过滤。
 - **scope carrier**：scope 过滤分发所携带的 `thisArg`（由 `scopeTarget` 构建）；其过滤器放行无标签监听器加上主体自身的监听器。*无主体*的 carrier（没有 key）只放行无标签监听器。
 - **scoped dispatch**：规则是：关于某个 agent 的活动的事件以该 agent 的 carrier 进行分发。关于注册表本身的事件（如「一个工具被添加了」）属于*注册表主体*事件，保持不过滤。
 - **shadowing**：最具体者胜出的名称解析：一个带作用域的工具／片段／变量仅在该 scope 内替换同名的全局对应项。这是按 agent 定制 persona 和按 agent 定制工具变体的机制。
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index c62de565e7..aa299088e1 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/i18n/README.md
 README.md: 30f56eeebf15a3edec559e3080247dab9ab14178
-README.zh.md: 91d5b35a00994beea70f2bbd674cfb557d6f834d
+README.zh.md: 52d0061fc6b7edd6ecbcab0798380f7202fd4981
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index 91d5b35a00..52d0061fc6 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
+本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
 
-## 配对契约
+## 配对约定
 
 - **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。
 - **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。
@@ -23,7 +23,7 @@
 
 ## 门禁：verify-translation-pairing
 
-`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：
+`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：
 
 1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。
 2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
@@ -37,7 +37,7 @@
 
 这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。
 
-把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
+把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。
 
 ## 范围与排除
 
@@ -55,4 +55,4 @@
 
 ## 分工
 
-这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
+这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 299f7db46f..846ade98b9 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -74,7 +74,7 @@
 | English | 中文 | 首次出现 | 不要译作 | 备注 |
 |---|---|---|---|---|
 | adapter | 适配器 | | | |
-| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | |
+| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |
 | append-only | 仅追加 | | | |
 | artifact | 产物 | | 制品 | |
 | backend | 后端 | | | |
@@ -101,7 +101,7 @@
 | counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指"另一侧"时可写「另一侧」 |
 | configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |
 | context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |
-| contract | 契约 | | | 如：`pairing contract` →`配对契约` |
+| contract | 约定 | | | 如：`pairing contract` →`配对约定` |
 | Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |
 | Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |
 | crash recovery | 崩溃恢复 | | | |
diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml b/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
index a32bb0e3e6..225a3f494b 100644
--- a/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
+++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/postmortem/0003-web-agent-gui-feedback-loop.md
 0003-web-agent-gui-feedback-loop.md: 13d13a607babfe7f5ddfdb6773c94f973bbef0db
-0003-web-agent-gui-feedback-loop.zh.md: f80530605ef9274638c6848bf5a256f76057915c
+0003-web-agent-gui-feedback-loop.zh.md: 84c9043ce2e286512483c99c2e23ebdc99cb49b2
diff --git a/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md b/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
index f80530605e..84c9043ce2 100644
--- a/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
+++ b/docs/postmortem/0003-web-agent-gui-feedback-loop.zh.md
@@ -31,7 +31,7 @@ Web agent 修改了 GUI 源码，却不知道由哪个 URL 和进程承载当前
 
 ## 根因
 
-Web 组合没有向模型提供当前 GUI、规范 URL 或运行模式的身份信息。会话 cwd 正确表示了用户选择的 Workspace，但模型误把这个项目边界当成了应用边界。系统也没有持久契约将 GUI 源码检出目录、构建产物、服务进程、目标 origin 和浏览器验收关联起来。
+Web 组合没有向模型提供当前 GUI、规范 URL 或运行模式的身份信息。会话 cwd 正确表示了用户选择的 Workspace，但模型误把这个项目边界当成了应用边界。系统也没有持久约定将 GUI 源码检出目录、构建产物、服务进程、目标 origin 和浏览器验收关联起来。
 
 裸 Vite 返回 HTTP 200，使错误的启动路径看似合理。`window.__DSH_BOOT__` 只由完整宿主注入，因此传输层就绪不代表应用已就绪。首个回归测试以另一种方式重复了同样的错误：超时机制终止 Vite 后，非零退出断言仍会通过。真实复现暴露了这一误报。
 
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
index b54453f3c4..8c66e9464c 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md
 0004-landlock-partial-notice-misclassified-child-failures.md: ed59fa9d2b04623220a9bcd984fe6becdc619198
-0004-landlock-partial-notice-misclassified-child-failures.zh.md: 5cf3e4422a5b888553e12dfb97b8a26aad65e231
+0004-landlock-partial-notice-misclassified-child-failures.zh.md: 55b462a4fe90b5d5c98bf846cad55e1fe4d6a4b0
diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
index 5cf3e4422a..55b462a4fe 100644
--- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
+++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md
@@ -10,7 +10,7 @@ Status: resolved
 
 ## 概述
 
-原生 launcher 契约区分两类 stderr 行。内核只能部分强制执行时，会精确打印 `landlock-run: partial enforcement (older Landlock ABI)`，然后继续执行子进程。launcher 失败则打印另一行 `landlock-run:` 诊断，在不执行子进程的情况下以 125 退出。
+原生 launcher 约定区分两类 stderr 行。内核只能部分强制执行时，会精确打印 `landlock-run: partial enforcement (older Landlock ABI)`，然后继续执行子进程。launcher 失败则打印另一行 `landlock-run:` 诊断，在不执行子进程的情况下以 125 退出。
 
 harness 用一个不区分大小写的 `landlock-run: ` 子串表示这两种情况。消费方只要发现非零退出同时携带该子串，就会归类为 runner 失败。因此，子进程的退出状态被错误地关联到 launcher 的信息性行：`false`、ripgrep 无匹配时的退出码 1、无效 pattern 的退出码 2，乃至由子进程自行选择的退出码 125，都可能在约束与执行均成功的情况下被错误归因为沙箱故障。
 
@@ -24,8 +24,8 @@ harness 用一个不区分大小写的 `landlock-run: ` 子串表示这两种情
 
 ## 时间线
 
-- 原生 launcher 契约规定：launcher 失败使用退出码 125，每次此类失败都会打印一行致命的 `landlock-run:` 诊断；成功执行子进程时则打印精确的部分强制执行通知。
-- 沙箱提供方把该契约简化为 `runnerFailureSignatures: ['landlock-run: ']`；bash 消费方将此前缀与任意非零退出组合，并报告 stderr 的第一行。
+- 原生 launcher 约定规定：launcher 失败使用退出码 125，每次此类失败都会打印一行致命的 `landlock-run:` 诊断；成功执行子进程时则打印精确的部分强制执行通知。
+- 沙箱提供方把该约定简化为 `runnerFailureSignatures: ['landlock-run: ']`；bash 消费方将此前缀与任意非零退出组合，并报告 stderr 的第一行。
 - 单元测试覆盖了无诊断的成功、拒绝诊断和致命 runner 前缀。真实 runner 测试在没有可用内核时会自行跳过，也没有强制构造「部分强制执行通知后跟非零子进程退出」的情况。
 - 一个最小 POSIX 包装脚本会打印该通知并 `exec` 其负载；它通过 `false` 与 ripgrep 无匹配场景复现了故障。
 - 结构化规则、前台与后台共享的分类逻辑和组装后的回放覆盖共同弥补了仍然存在的沙箱归因缺口。文件系统搜索通过 `ctx.subprocess` 运行打包的 ripgrep；本修复让该路径继续位于沙箱化 bash 之外。
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index f1636e0191..b741c1cdf8 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/README.md
 README.md: 1c3d14aeb4fd11cbc45eaadd83f0b84de0dfda52
-README.zh.md: dda61d86c4d00117af851b4a55d16b97c6bc2f10
+README.zh.md: 04e07cc9c8b8b16c69bb09344e8533729525fe5c
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index dda61d86c4..04e07cc9c8 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -6,8 +6,8 @@
 
 | 页面 | 负责内容 |
 |---|---|
-| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截契约，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
-| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
+| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截约定，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
+| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器约定（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
 | [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
@@ -18,15 +18,15 @@
 | [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
 | [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
 | [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
-| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 |
+| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方约定 |
 | [session-reference.md](session-reference.md) | 结构化跨会话引用：`SessionReferenceInput`/`Candidate`、prepared 消息上下文、稳定错误分类 |
 | [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
 | [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
 | [user-interaction.md](user-interaction.md) | UI 支持的人工问答 seam：`AskUserQuestionRequest`、answer/options 词汇、提供方 API、错误分类体系 |
-| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 契约 |
+| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 约定 |
 | [bash.md](bash.md) | bash 执行器 seam：`BashExecRequest`/`Spec`、`BashRunResult`、后台 `BashProcess` 句柄 |
 | [subprocess.md](subprocess.md) | 子进程 seam：完全显式的 `SubprocessSpawnSpec`、基于偏移的输出读取器、不含分类的 `SubprocessOutcome`，以及受管 `DSH_*` 环境词汇 |
-| [pty.md](pty.md) | 持久化终端 ID、后端/会话契约、发送就绪状态、有界读取与 owner 可见快照 |
+| [pty.md](pty.md) | 持久化终端 ID、后端/会话约定、发送就绪状态、有界读取与 owner 可见快照 |
 | [sandbox.md](sandbox.md) | 每会话策略解析与进程约束 seam：文件效果模式、执行/提供方策略、`ConfinedArgv`、强制执行与故障关闭错误 |
 | [code-runtime.md](code-runtime.md) | 代码执行 seam：`CodeRunRequest`/`Result`、绑定命名空间、捕获日志、`CodeRunFailure` 分类体系 |
 | [filesystem.md](filesystem.md) | 文件系统 seam：`FsTarget`、读/写/编辑结果、观测到的文件状态、`FsErrorCode` |
@@ -37,15 +37,15 @@
 | [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
 | [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
 | [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
-| [tasks.md](tasks.md) | 后台任务运行时：品牌化 `TaskId`、producer 契约、consumer 视图、`ctx.tasks` 服务行为 |
+| [tasks.md](tasks.md) | 后台任务运行时：品牌化 `TaskId`、producer 约定、consumer 视图、`ctx.tasks` 服务行为 |
 | [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
 | [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
-| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
+| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件约定 |
 | [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、可认领的回退席位、index 转换 |
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
-| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
+| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 约定、`telemetry/record` 脱敏 waterfall |
 
 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis surface** 小节。
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index f6ed20cace..6f035bdbd5 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/bash.md
 bash.md: dd7649ce46bea5642270fa553eb3d82f2dc33e9b
-bash.zh.md: bba9ece2955cee66e941aa878299cff6c06a97a0
+bash.zh.md: e3c607cb1599da97cb69369a34135abc310387ed
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index bba9ece295..e3c607cb15 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -218,7 +218,7 @@ interface BashProcessRead {
 
 ## 服务
 
-`BashExecutor` 拥有 `resolve`、前台 `run`、后台进程 `start` 以及 `sandboxMode` 能力事实。`dsh-bash-local` 拥有命令默认值补全、超时/中止分类、终端环境以及后台读取合并；进程组、有界收集器、spill 文件、凭据清除与 dispose（资源释放）后完全停稳归[进程管理器](subprocess.md)所有。`dsh-tool-bash` 拥有面向模型的渲染，并将后台句柄适配到[通用任务运行时](tasks.md)。`dsh-bash` 拥有 shell 工具共享的退出状态契约：导出的 `parseExitStatus`/`ParsedExitStatus` 是 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]` / `[killed by signal: X]` 标记的逆解析，两个工具的 `presentResult` 都用它把渲染文本拆分为 terminal 卡的输出正文与退出状态 pill。
+`BashExecutor` 拥有 `resolve`、前台 `run`、后台进程 `start` 以及 `sandboxMode` 能力事实。`dsh-bash-local` 拥有命令默认值补全、超时/中止分类、终端环境以及后台读取合并；进程组、有界收集器、spill 文件、凭据清除与 dispose（资源释放）后完全停稳归[进程管理器](subprocess.md)所有。`dsh-tool-bash` 拥有面向模型的渲染，并将后台句柄适配到[通用任务运行时](tasks.md)。`dsh-bash` 拥有 shell 工具共享的退出状态约定：导出的 `parseExitStatus`/`ParsedExitStatus` 是 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]` / `[killed by signal: X]` 标记的逆解析，两个工具的 `presentResult` 都用它把渲染文本拆分为 terminal 卡的输出正文与退出状态 pill。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index 05e7e67ed1..3caad2c5f7 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/code-runtime.md
 code-runtime.md: 12779f1aafc8930410ae0d695e3f617caafcf607
-code-runtime.zh.md: de563dd3430348f5cf3675d4bf124adeba170559
+code-runtime.zh.md: 0bb18aaafff5a9b390685ee4c93a67f3f15502d5
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index de563dd343..0bb18aaaff 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -2,7 +2,7 @@
 
 [English](code-runtime.md) | 中文
 
-代码执行 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：其接口（[dsh-code-runtime](../../packages/code-runtime/code-runtime)，`ctx.codeRuntime`）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread 后端与工具注册表消费方的契约见 [Code Mode 基础设计](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 和[类型化返回契约](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)。
+代码执行 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：其接口（[dsh-code-runtime](../../packages/code-runtime/code-runtime)，`ctx.codeRuntime`）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread 后端与工具注册表消费方的约定见 [Code Mode 基础设计](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 和[类型化返回约定](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)。
 
 源码：[`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)
 
@@ -36,7 +36,7 @@ interface CodeRunRequest {
 }
 ```
 
-结果将错误报告为一个**字段**，而不是让 `run()` 返回被拒绝的 Promise。报告程序失败是调用方的职责，不走异常路径（与 `BashExecutor.run` 失败时仍正常完成的契约一致）：
+结果将错误报告为一个**字段**，而不是让 `run()` 返回被拒绝的 Promise。报告程序失败是调用方的职责，不走异常路径（与 `BashExecutor.run` 失败时仍正常完成的约定一致）：
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 86348bad3a..ed13dea399 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/compaction.md
 compaction.md: 5aef839192ea6f67bb409622187fe65fed795e73
-compaction.zh.md: 63b28518e68f71cc648d2f4e78a82bc5beafb621
+compaction.zh.md: 20b4b2381f6e638e1d1b4db13ba98d53379b38db
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 63b28518e6..20b4b2381f 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -81,7 +81,7 @@ type ManualCompactionErrorCode =
 
 压力压缩在串行 `agent/pre-step` 中运行，先于请求推导。一旦压力或规范化溢出满足条件，compact-basic 会在选择范围前调用可选的 [`ctx.toolResultPrune`](../../packages/compact/compact-tool-result-prune/README.md)，再通过 `ctx.tokenMeter` 重新测量，并且可以在不生成摘要的情况下推进 surface。失败请求的恢复在失败的步骤关闭后通过 `agent/request-error` 运行；仅当 surface replacement generation 前进时才返回重试动作，即便后续摘要工作在剪枝后抛异常亦如此；取消仍然优先。区域边界保持工具调用/结果配对，但不保持整个轮次，因此一个过大轮次中较早关闭的步骤可以被压缩。`dsh-compact-basic` 拥有阈值、保留尾部策略、溢出上限与失败处理。
 
-该 seam 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于这些边缘检查。两者都会验证当前 surface 成员关系，并拒绝缺失的 seq 与遗留结果；其缓存语义由[包契约](../../packages/compact/compact/README.md#tool-pairing-boundaries)规定。
+该 seam 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于这些边缘检查。两者都会验证当前 surface 成员关系，并拒绝缺失的 seq 与遗留结果；其缓存语义由[包约定](../../packages/compact/compact/README.md#tool-pairing-boundaries)规定。
 
 ## 工具结果剪枝产出
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index caf9356ee9..42f00a896e 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/core.md
 core.md: cc9cc30677b0b657492d8a5118489e8b801f3fd3
-core.zh.md: 6878300dc2cbd82d220e17d2d6f5e1009f41c48f
+core.zh.md: 96854801d684509d4d77b6408a4bb45b93438cdb
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 6878300dc2..96854801d6 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -2,7 +2,7 @@
 
 [English](core.md) | 中文
 
-**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有 `agent`/`agent-loop` 这对包所声明的内容——agent 如何被创建与拥有，以及 `Agent` 句柄及其投递、取消与拦截契约——外加每个子系统都遵循的两个类型模式；该组的专属页面与目录其余部分见[子系统 README](README.md)。
+**核心**子系统即 [`packages/core`](../../packages/core/README.md)——每个组合都会启动的控制主干：事件溯源的会话日志、系统提示词组装、工具注册表、agent 词汇，以及驱动它们的具体循环。本页拥有 `agent`/`agent-loop` 这对包所声明的内容——agent 如何被创建与拥有，以及 `Agent` 句柄及其投递、取消与拦截约定——外加每个子系统都遵循的两个类型模式；该组的专属页面与目录其余部分见[子系统 README](README.md)。
 
 ## 主干逐包速览
 
@@ -14,7 +14,7 @@
 | `system-prompt/` | 提示词段落与工具 schema 组装（`ctx.systemPrompt`） | [system-prompt.md](system-prompt.md) |
 | `tools/` | 带作用域的工具注册表与受保护的执行流水线（`ctx.tools`） | [tools.md](tools.md) |
 | `agent/` | `Agent` 接口、实时注册表、发起者作用域与 `agent/*` 事件词汇（`ctx.agents`） | 本页 |
-| `agent-loop/` | 实现公开 `Agent` 契约的具体 driver（`ctx.agentLoop`） | 本页 |
+| `agent-loop/` | 实现公开 `Agent` 约定的具体 driver（`ctx.agentLoop`） | 本页 |
 | `scope/` | 注册表与循环用于构建按 agent 作用域的注册原语 | [scope.md](scope.md) |
 
 `scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是 `agent` seam 的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
@@ -50,7 +50,7 @@ interface AgentHandle {
 
 `CreateAgentOptions` 携带共享标识以及新 agent 发布前所需的一切：会话元数据（`meta`——已校验的 `cwd`、fork 谱系、seed 边界、来源分类、委派深度）、fork 用的可选 `seed` 回放前缀、按 agent 的 `AgentOptions`、仅创建期有效的取消 `signal`，以及 `setup`。`ResumeAgentOptions` 是持久标识的对应物：`resumeSessionId`、`agentOptions`、`signal` 与 `setup`。`setup` 回调（`AgentSetup`）在两个 id 都尚未发布时组装 agent 的作用域世界——凡经 `agentCtx` 注册的内容都先于 `agent/created` 与第一次提示词组装存在——并可返回一个在发布前一刻调用的同步 commit；setup 拒绝、commit 抛出或所有者 dispose 都会回滚事务，两个 id 均不发布。
 
-`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚契约见下方[生成区块](#ctxagents--agentregistry)。
+`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚约定见下方[生成区块](#ctxagents--agentregistry)。
 
 <a id="the-agent-handle"></a>
 
@@ -206,7 +206,7 @@ type AgentCancelCause =
 
 cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
 
-[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）契约。轮次和步骤边界是持久会话事件，而不是 agent emit。
+[事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）约定。轮次和步骤边界是持久会话事件，而不是 agent emit。
 
 <a id="initiating-agent"></a>
 
@@ -255,7 +255,7 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ## `ToolDefinition`
 
-唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的契约。
+唯一属于核心的流水线编写类型：每个已注册工具*是什么*——一个面向模型的 `ToolSchema` 加上一个 `execute` 函数，以及可选的最终内容回调与 UI 回调。工具作者很少手动构造它（`defineTool` DSL 会用类型化参数构建），但它是注册表持有、循环分发所经过的约定。
 
 其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 形状，以及工具展示 UI 词汇在 **[tools.md](tools.md)** 中。
 
diff --git a/docs/subsystems/goal.i18n.yaml b/docs/subsystems/goal.i18n.yaml
index 945ed658d2..cdd932726e 100644
--- a/docs/subsystems/goal.i18n.yaml
+++ b/docs/subsystems/goal.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/goal.md
 goal.md: 6f54a5261cb44c3fda389e37cb689a00061ab241
-goal.zh.md: 043263f3231b4c727f21ca0b8fc07d8adffa0559
+goal.zh.md: ea5a0fe7923648aead5e6f54ab31162a7abdb954
diff --git a/docs/subsystems/goal.zh.md b/docs/subsystems/goal.zh.md
index 043263f323..ea5a0fe792 100644
--- a/docs/subsystems/goal.zh.md
+++ b/docs/subsystems/goal.zh.md
@@ -142,7 +142,7 @@ interface GoalChanged {
 
 ## 服务行为
 
-[`GoalService`](../../packages/goal/goal/src/index.ts) 解析创建默认值、从持久 `goal/change` 事件执行严格回放折叠、校验确切的活跃 agent 身份、以比较并设置方式执行变更，并发出 `goal/changed` 通知；监听器故障会被隔离。包 [README](../../packages/goal/goal/README.md) 负责记录可调用契约和面向模型的契约。
+[`GoalService`](../../packages/goal/goal/src/index.ts) 解析创建默认值、从持久 `goal/change` 事件执行严格回放折叠、校验确切的活跃 agent 身份、以比较并设置方式执行变更，并发出 `goal/changed` 通知；监听器故障会被隔离。包 [README](../../packages/goal/goal/README.md) 负责记录可调用约定和面向模型的约定。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/http-server.i18n.yaml b/docs/subsystems/http-server.i18n.yaml
index 572039f635..6f61102676 100644
--- a/docs/subsystems/http-server.i18n.yaml
+++ b/docs/subsystems/http-server.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/http-server.md
 http-server.md: b9795fe98b432b6ef5f7d01a4d3e115c809fe642
-http-server.zh.md: b84ea457bcd37eed361fde88fbf680d189aeebfb
+http-server.zh.md: 8d55c48ae2882bd471ca4e64e011c7d79c4ebb40
diff --git a/docs/subsystems/http-server.zh.md b/docs/subsystems/http-server.zh.md
index b84ea457bc..8d55c48ae2 100644
--- a/docs/subsystems/http-server.zh.md
+++ b/docs/subsystems/http-server.zh.md
@@ -42,7 +42,7 @@ interface Config {
 
 ## 服务
 
-`HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动的大声失败 sweep 上报。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层契约，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
+`HttpServerService`（`ctx.httpServer`）在激活时立即监听；监听失败（EADDRINUSE 等）会从 init 抛出，形成一个 FAILED fiber，由启动的大声失败 sweep 上报。`register(route)` 添加一条具名路由并返回其 disposer；重复的 `(kind, path)` 抛出异常，因为路由模式是组合层约定，冲突即配置错误。`tapIndex(transform)` 添加一个纯的 html 到 html 转换，按注册顺序应用于每个 index 响应（`/` 和每次 SPA 回退）；[dsh-client-modules](../../packages/client/modules) 用它注入启动 manifest（元数据清单）。`port` 读取监听端口，`config.port` 为 0 时读到的是操作系统分配的值。
 
 处理过程中抛出异常的请求（畸形的 % 转义撞上 `decodeURIComponent`、客户端在请求体中途断开）会记录为警告并应答 400（响应头已发出时则销毁 socket），绝不导致进程退出。dispose（资源释放）把 `close()` 与 `closeAllConnections()` 配对使用，因为处理器可能像 SSE（Server-Sent Events）那样保持响应打开，而这类连接永远不会自行结束；没有强制关闭，拆卸就会挂起。该包（package）从不打印输出：URL 行归 shell 所有。逐包运维细节（含开发模式的 bundle 监视流水线）留在 [README](../../packages/host/webserver/README.md) 中。
 
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
index 8ef657b3a4..23364aacc1 100644
--- a/docs/subsystems/invariants.i18n.yaml
+++ b/docs/subsystems/invariants.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/invariants.md
 invariants.md: 184d982bb27ab3ff98f715f0751c8bfcc1d08bea
-invariants.zh.md: bd2f83a018642832fe50ba5cca6dd82e2bd7d59b
+invariants.zh.md: e79b1c90a1c6284691404411ad9fa8ce62ef7e5e
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
index bd2f83a018..e79b1c90a1 100644
--- a/docs/subsystems/invariants.zh.md
+++ b/docs/subsystems/invariants.zh.md
@@ -54,9 +54,9 @@ interface InvariantInstaller {
 
 `ctx.invariants.register(packageName, installer)` 为完整 npm 包名保留唯一一个活跃注册，并返回其绑定到 effect 的 disposer。即使过滤器使安装器保持不活跃，保留依然成立，因此两个插件绝不可能静默地认领同一个包名；重复、空白或含空白字符的名称会抛出异常。安装器失败会原子地 dispose（资源释放）子 fiber 并释放保留。服务拥有每个注册 fiber，而返回的 disposer 同时属于配套插件的 fiber：卸载任一侧都会移除监听器、trace 状态和保留项，因此配套插件可以重载并再次注册同一名称，不留残余状态。
 
-## 配套插件契约
+## 配套插件约定
 
-每个工作区包都拥有一个 `./invariant` 配套插件（[包契约](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但刻意不合成断言。只有当包对某个可观察事件或可变数据拥有所有权关系时，配套插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行配套插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
+每个工作区包都拥有一个 `./invariant` 配套插件（[包约定](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但刻意不合成断言。只有当包对某个可观察事件或可变数据拥有所有权关系时，配套插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)）。可执行配套插件的目录与标准组合方式见[包 README](../../packages/support/invariants/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index f807656000..a54224c867 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md
 llm-streaming.md: c65416f449d1783f398cdd81b0d6987de83a6141
-llm-streaming.zh.md: ce79ecca53edf7213853df118489817451baa7b0
+llm-streaming.zh.md: 08b627b41090e99d9a581758a593dc6d4dbf4dd7
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index ce79ecca53..08b627b410 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -2,7 +2,7 @@
 
 [English](llm-streaming.md) | 中文
 
-[`packages/llm`](../../packages/llm/README.md) 的对话与流式输出词汇：每个请求与持久历史共享的 `Message`/`ContentBlock` 形状、完整组装的模型请求、原始 `StreamChunk` 协议、每个适配器必须遵守的适配器契约（adapter contract），以及共享的 assembler。[核心主干](core.md)在每个轮次持有并记录这些值；本页声明它们。
+[`packages/llm`](../../packages/llm/README.md) 的对话与流式输出词汇：每个请求与持久历史共享的 `Message`/`ContentBlock` 形状、完整组装的模型请求、原始 `StreamChunk` 协议、每个适配器必须遵守的适配器约定（adapter contract），以及共享的 assembler。[核心主干](core.md)在每个轮次持有并记录这些值；本页声明它们。
 
 源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 
@@ -202,7 +202,7 @@ interface LlmFailure {
 }
 ```
 
-## 适配器契约
+## 适配器约定
 
 每个适配器必须遵守以下规则，每个消费方可以依赖它们：
 
@@ -216,7 +216,7 @@ interface LlmFailure {
 - **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
 - **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容与 provenance，不会收到私有状态。
 
-该契约由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
+该约定由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
 
 ## `ResolvedRetryPolicy`
 
@@ -224,7 +224,7 @@ interface LlmFailure {
 
 ## `AppIdentity`：应用归属
 
-每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该契约有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包（package） manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
+每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该约定有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包（package） manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
 
 ```ts type-equiv
 /**
@@ -504,7 +504,7 @@ interface GenerateOptions {
 }
 ```
 
-模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式契约的 [`LlmFailure`](#llmfailure)：
+模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式约定的 [`LlmFailure`](#llmfailure)：
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 295e5392ca..e892317427 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/persistence.md
 persistence.md: 580ec250ebad3f2b51982f98a611268f26487321
-persistence.zh.md: 6676bf26e6eb0fb8f7dd9a94d17d4d70d1d1b271
+persistence.zh.md: 4ff9da19e8127c15e73f822b14adb41a5a1658b0
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 6676bf26e6..4ff9da19e8 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -4,7 +4,7 @@
 
 事件日志的**持久性 seam**。[session.md](session.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.md)中逐项列举。
 
-该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一契约的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
+该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一约定的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
 
 ## flush 检查点
 
diff --git a/docs/subsystems/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
index efbd158e18..a6f8fd2609 100644
--- a/docs/subsystems/sandbox.i18n.yaml
+++ b/docs/subsystems/sandbox.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/sandbox.md
 sandbox.md: dd960b3021dcdc87cfd36fd439cbec0a810dd736
-sandbox.zh.md: f526982a782144a0bf58abcde5d883e9dc813369
+sandbox.zh.md: 23644bb43a131a0e3c8595187a6fc11e74682d9e
diff --git a/docs/subsystems/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
index f526982a78..23644bb43a 100644
--- a/docs/subsystems/sandbox.zh.md
+++ b/docs/subsystems/sandbox.zh.md
@@ -143,7 +143,7 @@ interface ConfinedArgv {
 
 ## 提供方与 fail-closed 错误
 
-`ctx.sandbox.confine(argv, policy)` 返回一个 `ConfinedArgv`，或在没有可用后端时抛出 `SandboxUnavailableError`（错误码 `SANDBOX_UNAVAILABLE`）。消费方也可以在 spawn 或观察所返回的 argv 时对失败进行分类；该归因属于消费方契约。对于受限策略，静默的无隔离透传永远不合法。
+`ctx.sandbox.confine(argv, policy)` 返回一个 `ConfinedArgv`，或在没有可用后端时抛出 `SandboxUnavailableError`（错误码 `SANDBOX_UNAVAILABLE`）。消费方也可以在 spawn 或观察所返回的 argv 时对失败进行分类；该归因属于消费方约定。对于受限策略，静默的无隔离透传永远不合法。
 
 提供方选择、探测、缓存和后端专有的强制执行报告归[本地提供方](../../packages/sandbox/sandbox-local/README.md)所有。
 
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index fc603d658d..98efe87541 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session-projection.md
 session-projection.md: 64351195028c62f623b32cbeb80c952795c1e9e6
-session-projection.zh.md: cf9036e6db3f82d84ffa3b8aa809c5617409659a
+session-projection.zh.md: e4a03c6719095cc342d914612faf364fc48e4fa0
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index cf9036e6db..e4a03c6719 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -2,7 +2,7 @@
 
 [English](session-projection.md) | 中文
 
-会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是接口与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流契约：[包（package）README](../../packages/session/session-projection/README.md)。
+会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是接口与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流约定：[包（package）README](../../packages/session/session-projection/README.md)。
 
 源码：[`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 
diff --git a/docs/subsystems/session-reference.i18n.yaml b/docs/subsystems/session-reference.i18n.yaml
index c1466bdcfc..a73c858289 100644
--- a/docs/subsystems/session-reference.i18n.yaml
+++ b/docs/subsystems/session-reference.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session-reference.md
 session-reference.md: f539a59b8d26182aff9746b6d6a39a86ba15cb45
-session-reference.zh.md: 82b6a6c5ec5c91372fc6a43b73ad1572fccf5b3a
+session-reference.zh.md: 1035614141936af1f94bdabe35b3104be319a762
diff --git a/docs/subsystems/session-reference.zh.md b/docs/subsystems/session-reference.zh.md
index 82b6a6c5ec..1035614141 100644
--- a/docs/subsystems/session-reference.zh.md
+++ b/docs/subsystems/session-reference.zh.md
@@ -2,7 +2,7 @@
 
 [English](session-reference.md) | 中文
 
-结构化的跨会话引用请求与准备后的消息上下文。[包契约](../../packages/context/session-reference) 负责规范 URI、当前表层投影、标签安全的 JSON 与字节保留、稳定错误和不可信的模型提示词。宿主适配器使用这些类型，而不会把各自 UI 的提及语法传入 agent（智能体）核心。
+结构化的跨会话引用请求与准备后的消息上下文。[包约定](../../packages/context/session-reference) 负责规范 URI、当前表层投影、标签安全的 JSON 与字节保留、稳定错误和不可信的模型提示词。宿主适配器使用这些类型，而不会把各自 UI 的提及语法传入 agent（智能体）核心。
 
 来源：[`packages/context/session-reference/src/types.ts`](../../packages/context/session-reference/src/types.ts)
 
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 2389cc806c..6f28409864 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session.md
 session.md: 7735e90807f6fce1b3645096437b3e86189dc8ec
-session.zh.md: 09f34ac19c2f685bf5f8e5b11355b4c642c584d0
+session.zh.md: 63eb460f7ef300decf3e32c0ace16b354606c271
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 09f34ac19c..63eb460f7e 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -177,7 +177,7 @@ interface EpochHeader {
 
 ### 路由容量事件：`request/context`
 
-请求所解析到的路由的上下文元数据是独立的已记录状态，在同一步骤内紧随 `request/header` 追加，且仅在提供方、模型或容量与上一条记录不同时追加。它保持在 `EpochHeader` 之外，因为该类型是由 `headerEquals` 逐字段比较的重建契约：容量描述的是路由，不是请求输入，把它折叠进去会让一次容量变化被登记为请求信封的 `change`，也会把适配器元数据拉进 loop 的重建不变式。与 `request/header` 一样，它不是 `SurfaceEventType`，也不产生 LLM 消息。`session.requestContext()` 以增量方式归并最新一条记录。适配器不公布容量的路由会以缺失 `contextWindow` 的形式记录，因此新记录可以清除较早路由的容量。
+请求所解析到的路由的上下文元数据是独立的已记录状态，在同一步骤内紧随 `request/header` 追加，且仅在提供方、模型或容量与上一条记录不同时追加。它保持在 `EpochHeader` 之外，因为该类型是由 `headerEquals` 逐字段比较的重建约定：容量描述的是路由，不是请求输入，把它折叠进去会让一次容量变化被登记为请求信封的 `change`，也会把适配器元数据拉进 loop 的重建不变式。与 `request/header` 一样，它不是 `SurfaceEventType`，也不产生 LLM 消息。`session.requestContext()` 以增量方式归并最新一条记录。适配器不公布容量的路由会以缺失 `contextWindow` 的形式记录，因此新记录可以清除较早路由的容量。
 
 ```ts type-equiv
 /** Registration-bound metadata for one resolved model route. */
@@ -585,11 +585,11 @@ interface TurnEndReasonMap {
 
 钩子桥接层的 `hook/invoked` / `hook/result` 溯源对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次（见[钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)）。
 
-## 持久性契约
+## 持久性约定
 
-持久化后端依赖的契约如下：持久日志无损保存每个事件，**包括** `assistant/chunk`；`seq` 必须连续，因此不能从规范日志中过滤分片。后端可以为事件批次选择自己的存储编码，只要 `load` 返回与追加时完全一致的事件即可（JSONL 后端默认启用的打包分片行就是此类编码；见 [persistence.md](persistence.md)）。所有 `event.data` 都必须可序列化为 JSON；`Session.append` 会从源头强制这一要求（遇到不可序列化数据时抛出），因此错误事件绝不会进入日志，`session.events` 始终与后端可持久化的内容一致。新增会携带不可序列化数据、破坏核心执行嵌套或违反事件所有方声明关系的事件类型，都会构成磁盘格式的破坏性变更。
+持久化后端依赖的约定如下：持久日志无损保存每个事件，**包括** `assistant/chunk`；`seq` 必须连续，因此不能从规范日志中过滤分片。后端可以为事件批次选择自己的存储编码，只要 `load` 返回与追加时完全一致的事件即可（JSONL 后端默认启用的打包分片行就是此类编码；见 [persistence.md](persistence.md)）。所有 `event.data` 都必须可序列化为 JSON；`Session.append` 会从源头强制这一要求（遇到不可序列化数据时抛出），因此错误事件绝不会进入日志，`session.events` 始终与后端可持久化的内容一致。新增会携带不可序列化数据、破坏核心执行嵌套或违反事件所有方声明关系的事件类型，都会构成磁盘格式的破坏性变更。
 
-消费此契约的后端见 [persistence.md](persistence.md)。
+消费此约定的后端见 [persistence.md](persistence.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
index 84628f50b7..570dfe223f 100644
--- a/docs/subsystems/skills.i18n.yaml
+++ b/docs/subsystems/skills.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/skills.md
 skills.md: 78d510fafca0017b9528a215270172a74e9b0de1
-skills.zh.md: e88c9f1ba190eb1e90966d35c7dcc2eb86ecd6cc
+skills.zh.md: 12e51c45a779e3ca0634db62ac9adfe69112d09f
diff --git a/docs/subsystems/skills.zh.md b/docs/subsystems/skills.zh.md
index e88c9f1ba1..12e51c45a7 100644
--- a/docs/subsystems/skills.zh.md
+++ b/docs/subsystems/skills.zh.md
@@ -211,7 +211,7 @@ interface Config {
 }
 ```
 
-## 会话目录与工具契约
+## 会话目录与工具约定
 
 `dsh-tool-skill` 在存活会话中第一个观察到非空完整视图的 `agent/pre-step` 注入初始的持久 user-role `<system-reminder>`。目录只包含已排序的 skill `name` 和规范化、经 XML 转义的 `description`；不包含正文、路径、来源、提供方或路由提示。发现通过 `SkillLookupOptions` 转发该步骤的 abort signal。`catalogDescriptionMaxLength` 是消费方用于 description 上限的配置，默认值为 `500`，整数最小值为 `3`。
 
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 98092af5b3..3d8db33ada 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/storage.md
 storage.md: 52dc84b699921e911276ce5214bc975abfd22fa4
-storage.zh.md: f614b77153e835264e1650515946a9d2acf70e57
+storage.zh.md: 89ff7f69ed43b55101be834c21d11cf74ca2340b
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index f614b77153..89ff7f69ed 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -44,7 +44,7 @@ interface StorageBackend {
 }
 ```
 
-一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并暴露可选的数据形状 facet；目前 `kv` 是唯一的 facet。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、格式版本、表名清单，以及是否存在全局单例槽位——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键是任意字符串，绝不进入文件路径。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的，且 resolve 后即已持久。介质上记录的版本与之不同时拒绝 `version-mismatch`；无法按该 unit 解析的介质拒绝 `malformed-medium`（不做迁移：预发布立场）。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性契约，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件对每个后端断言其中每一条款。[json 后端](../../packages/storage/storage-json/README.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.md)在单个数据库中按一行一文档存储，是高频更新领域的路由选择。
+一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并暴露可选的数据形状 facet；目前 `kv` 是唯一的 facet。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、格式版本、表名清单，以及是否存在全局单例槽位——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键是任意字符串，绝不进入文件路径。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的，且 resolve 后即已持久。介质上记录的版本与之不同时拒绝 `version-mismatch`；无法按该 unit 解析的介质拒绝 `malformed-medium`（不做迁移：预发布立场）。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性约定，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件对每个后端断言其中每一条款。[json 后端](../../packages/storage/storage-json/README.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.md)在单个数据库中按一行一文档存储，是高频更新领域的路由选择。
 
 ## 声明领域
 
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 994c04eaa5..9ecb6e4628 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/subagent.md
 subagent.md: 3bf3ac7c48bfa08be86314bb43263d4ee6198654
-subagent.zh.md: ddc3a715fbb6589dffc38f0e0c8b23bf35dddf6e
+subagent.zh.md: 37b274d7f3ffa5b5aadea773d29f7e6b4e5a833b
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index ddc3a715fb..37b274d7f3 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -259,13 +259,13 @@ interface ContinuableCreateSpec {
 }
 ```
 
-描述符（[descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts) 中的 `SubagentDescriptorData`）是每个由会话支撑的 subagent 所使用、按模式判别的持久化身份。两种模式都携带提供方名称。`one-shot` 描述符可以携带调用方拥有的可选显示 `label`；`continuable` 描述符要求以委派 `description` 作为持久化创建标签，并另外对已解析的子 agent `agentOptions.provider`／`model` 与可选的 `persona`／`toolFilter` 建立快照，用于冷恢复。它绝不会对可合并扩展的 `AgentOptions` 对象建立快照，因此无关的扩展值不会破坏继续执行，后续新增组合配置输入则是一次有意的版本更改。描述符省略 `subagentDepth`（冷恢复以持久化 header 中的 `delegationDepth` 作为单调下界）和 `outputSchema`（单次运行或 Activation 的结果契约，而非持久化身份）。
+描述符（[descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts) 中的 `SubagentDescriptorData`）是每个由会话支撑的 subagent 所使用、按模式判别的持久化身份。两种模式都携带提供方名称。`one-shot` 描述符可以携带调用方拥有的可选显示 `label`；`continuable` 描述符要求以委派 `description` 作为持久化创建标签，并另外对已解析的子 agent `agentOptions.provider`／`model` 与可选的 `persona`／`toolFilter` 建立快照，用于冷恢复。它绝不会对可合并扩展的 `AgentOptions` 对象建立快照，因此无关的扩展值不会破坏继续执行，后续新增组合配置输入则是一次有意的版本更改。描述符省略 `subagentDepth`（冷恢复以持久化 header 中的 `delegationDepth` 作为单调下界）和 `outputSchema`（单次运行或 Activation 的结果约定，而非持久化身份）。
 
 本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始 prompt 获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
 
 ## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
 
-`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 契约负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 `SubagentService.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index a3071e98a9..4c63f77618 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/subprocess.md
 subprocess.md: 0bc2bf86518bcc60bef02554b94471425f2ac433
-subprocess.zh.md: 5d6425707edcf1952c25dbdc91dbf7aab3779350
+subprocess.zh.md: 7e27bf15dfe0cdde09459dbfb239ab25ccde126a
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index 5d6425707e..7e27bf15df 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -246,7 +246,7 @@ interface SubprocessOutcome {
 
 ## 服务行为
 
-抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口约定见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/system-prompt.i18n.yaml b/docs/subsystems/system-prompt.i18n.yaml
index a1e14385f4..a7a5e5a6d0 100644
--- a/docs/subsystems/system-prompt.i18n.yaml
+++ b/docs/subsystems/system-prompt.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/system-prompt.md
 system-prompt.md: 94ce40f8bf98dd4efe3514879c2527c2a7bd3b21
-system-prompt.zh.md: 37d366774089f91756433602a719e99b57747c17
+system-prompt.zh.md: c46ee6e2b70c6603500bd9061ed09b805ed61630
diff --git a/docs/subsystems/system-prompt.zh.md b/docs/subsystems/system-prompt.zh.md
index 37d3667740..c46ee6e2b7 100644
--- a/docs/subsystems/system-prompt.zh.md
+++ b/docs/subsystems/system-prompt.zh.md
@@ -39,7 +39,7 @@ interface ToolProviderResult {
 
 ## 提示词段落
 
-`PromptSection` 是一份只读的同进程注册契约。其文本可以是静态的，也可以从当前组装上下文动态解析。
+`PromptSection` 是一份只读的同进程注册约定。其文本可以是静态的，也可以从当前组装上下文动态解析。
 
 ```ts type-equiv
 /** One contributed section of the system prompt (registry input). */
diff --git a/docs/subsystems/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
index d28dcc2781..d1110928e7 100644
--- a/docs/subsystems/tasks.i18n.yaml
+++ b/docs/subsystems/tasks.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/tasks.md
 tasks.md: 6237607307cbab8511f968ed591e3e3b8b845c6a
-tasks.zh.md: 99a6fcc4f54c1b52e5c6fd393327cc768f064297
+tasks.zh.md: c73765b4d5ad0309f3473890557171af21527682
diff --git a/docs/subsystems/tasks.zh.md b/docs/subsystems/tasks.zh.md
index 99a6fcc4f5..c73765b4d5 100644
--- a/docs/subsystems/tasks.zh.md
+++ b/docs/subsystems/tasks.zh.md
@@ -21,7 +21,7 @@ interface TaskKindMap {
 
 `TaskStatus` 为 `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`；生产方特有的事实归入 `TaskSnapshot.detail`。
 
-## 生产方契约
+## 生产方约定
 
 `TaskStart` 声明身份和启动器。运行时会在调用 `run()` 前完成预检，随后提交注册，不再执行可能失败的步骤。生产方拥有执行资源；运行时拥有身份、访问权限和生命周期状态。
 
@@ -151,7 +151,7 @@ interface TaskRead {
 
 ## 服务行为
 
-抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam 定义原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 监听器，以及 `attachSurface` 可用性防线；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部实现。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。seam 契约见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的接口见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
+抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam 定义原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 监听器，以及 `attachSurface` 可用性防线；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部实现。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。seam 约定见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的接口见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index 19cd6f6851..d520d56dcf 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/telemetry.md
 telemetry.md: 131c5814f29d70c356989e62fda1db5c1c5448d6
-telemetry.zh.md: 5d4a9d9994457bc06a9e4194c4807f88789a3cf0
+telemetry.zh.md: 147418000f240093f356fe9033612967f8e29ffb
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 5d4a9d9994..147418000f 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -2,7 +2,7 @@
 
 [English](telemetry.md) | 中文
 
-对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端契约；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的契约见 [seam README](../../packages/session/session-telemetry/README.md)。
+对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端约定；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的约定见 [seam README](../../packages/session/session-telemetry/README.md)。
 
 源码：[`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
 
@@ -56,7 +56,7 @@ interface TelemetryRecord {
 
 每个 `(turn, step)` 只发出第一条 `assistant/chunk`，即「流已开始」的信号；其余分片在捕获时丢弃，因此导出流中的 `seq` 缺口是常态，绝不是丢失信号。其他所有[会话事件](session.md)类型都会完整透传，包括该 seam 从未听说过、由插件合并进来的事件类型。投递是尽力而为的：游标标记的是「已交接」而非「已送达」，记录可能丢失（崩溃、重载窗口）也可能重复（无游标的重新接管、SDK 重试），因此接收端对 ledger 记录基于 `(session.id, event.seq)` 去重；ops 记录刻意省略这类标识——它们是用于告警的信号，而非用于累加的条目，重复被容忍而非被去重。
 
-## 后端契约
+## 后端约定
 
 ```ts type-equiv
 /**
@@ -105,7 +105,7 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry-abstract-seam)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
+`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry-abstract-seam)）是该约定的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
 
 ## 脱敏 waterfall：`telemetry/record`
 
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 21003bb796..77c413c7ff 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/tools.md
 tools.md: 0551ee1c9dfa12b415c1f4575b5225f771cb53bc
-tools.zh.md: 50843b07f1d98b1c9d9222288b1273b34bee1e4a
+tools.zh.md: b2aa3d2b192f82c08b4a8e7931008a768fd04adf
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index 50843b07f1..b2aa3d2b19 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -148,7 +148,7 @@ type InferArgs<S> = InferProperties<S, []>
 
 `defineTool({ name, description, parameters, output, execute, … })` 将参数推导与 `parameterSchemaSpecToJsonSchema()` 和 `validateArgs()` 绑定，并将 `execute`/`render`/`presentationMeta` 与 `InferValue<OutputSchema>` 绑定。Schema 记录只包含自有且可枚举的字符串键，schema 数组是稠密的内建数组，因此推导、编译与校验观察到的是同一份声明。精确推导保持到 16 层容器，之后放宽为 `JsonValue`；运行时校验仍会继续遍历完整 schema。`valueSchemaSpecToJsonSchema()` 通过同一套已强制执行的原始子集编译输出声明。参数不匹配时抛出 `ToolArgsError`（`INVALID_ARGS`）；函数体或后置策略产生的值无效时抛出 `ToolOutputError`（`INVALID_TOOL_OUTPUT`）。两者都经由常规工具错误路径处理。原始 JSON Schema 默认保持开放；不支持的关键字会被拒绝，而不会在未强制执行的情况下获准进入。
 
-注册是一个受信任的同进程契约。注册表以 readonly 输入借用类型化定义，要求它声明 `output`，校验其原始 schema，并检查 `timeoutMs` 必须为正有限值等语义要求；`schemas()` 在模型边界处物化显式的面向模型投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。
+注册是一个受信任的同进程约定。注册表以 readonly 输入借用类型化定义，要求它声明 `output`，校验其原始 schema，并检查 `timeoutMs` 必须为正有限值等语义要求；`schemas()` 在模型边界处物化显式的面向模型投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。
 
 ## `ToolRestriction` — 单个作用域的实时全局过滤器
 
@@ -243,7 +243,7 @@ type ToolExecutionMode =
   | { kind: 'exclusive' }
 ```
 
-Code Mode 的桥接层还会把每个已结算的子分派暴露给 `tools/code-dispatch-log` waterfall，该 waterfall 可以改写持久事件所存的内容副本（程序取得的值与模型契约均不受影响）：
+Code Mode 的桥接层还会把每个已结算的子分派暴露给 `tools/code-dispatch-log` waterfall，该 waterfall 可以改写持久事件所存的内容副本（程序取得的值与模型约定均不受影响）：
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml
index b8fdb092f2..54d300d028 100644
--- a/docs/subsystems/typert.i18n.yaml
+++ b/docs/subsystems/typert.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/typert.md
 typert.md: 8ce52837ceee8e9c8c4a61de28f972912faa2cf0
-typert.zh.md: ff6b45a517c75392ee87fa348d72bfae6cdf1efb
+typert.zh.md: 49ad64fbcfdee2d18662fe383335f61236258717
diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md
index ff6b45a517..49ad64fbcf 100644
--- a/docs/subsystems/typert.zh.md
+++ b/docs/subsystems/typert.zh.md
@@ -2,7 +2,7 @@
 
 [English](typert.md) | 中文
 
-以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts) 中公共契约的字面定义。
+以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。[TypeRT Gateway Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) 负责架构与传输决策；本页记录 [`dsh-type-meta`](../../packages/typert/type-meta/src/types.ts) 和 [`dsh-api-gateway`](../../packages/api/gateway/src/types.ts) 中公共约定的字面定义。
 
 ## Lookup 与 Context 声明
 
diff --git a/docs/subsystems/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
index f3f0ab9758..b22cd94946 100644
--- a/docs/subsystems/web.i18n.yaml
+++ b/docs/subsystems/web.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/web.md
 web.md: f300bf2daef172fe4a69c00f36c804cf874c189d
-web.zh.md: 0c72e343c1b6ea5de8e7c296014da35b0291a33b
+web.zh.md: 36afee9a964a0ad185242d5ee8f4f91689b1d295
diff --git a/docs/subsystems/web.zh.md b/docs/subsystems/web.zh.md
index 0c72e343c1..36afee9a96 100644
--- a/docs/subsystems/web.zh.md
+++ b/docs/subsystems/web.zh.md
@@ -128,7 +128,7 @@ type WebFetchBody =
 
 ## 错误
 
-`WebError extends HarnessError`（[core.md](core.md) 错误分类体系），带有 `code: string`（开放式，与其他 seam 的错误一致——`LlmError`、`SubagentError`），而非封闭联合类型：提供方可以在不修改 `dsh-web` 的情况下抛出自己的错误代码，消费方必须容忍未知错误代码。错误代码按所有者划分。由 seam 统一定义的错误代码来自 `WebService` 的选择逻辑和共享契约：`WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_CONFIGURED_MISSING`、`WEB_PROVIDER_CONFIGURED_UNAVAILABLE`、`WEB_PROVIDER_AMBIGUOUS`、`WEB_DUPLICATE_PROVIDER`（注册时的编程错误，类似 `LlmService` 的 `DUPLICATE_ADAPTER`）、`WEB_ABORTED`，以及 `WEB_PROVIDER_ERROR`（提供方自身故障经 seam 暴露时使用的兜底代码，包括 DNS、连接被拒绝、TLS 等网络或传输故障）。抓取传输层错误代码由 `dsh-web-fetch-local` 实现拥有，不同的抓取后端无需抛出它们：`WEB_INVALID_URL`、`WEB_BLOCKED_URL`、`WEB_REDIRECT_BLOCKED`、`WEB_FETCH_TOO_LARGE`、`WEB_FETCH_TIMEOUT`、`WEB_UNSUPPORTED_CONTENT_TYPE`。
+`WebError extends HarnessError`（[core.md](core.md) 错误分类体系），带有 `code: string`（开放式，与其他 seam 的错误一致——`LlmError`、`SubagentError`），而非封闭联合类型：提供方可以在不修改 `dsh-web` 的情况下抛出自己的错误代码，消费方必须容忍未知错误代码。错误代码按所有者划分。由 seam 统一定义的错误代码来自 `WebService` 的选择逻辑和共享约定：`WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_CONFIGURED_MISSING`、`WEB_PROVIDER_CONFIGURED_UNAVAILABLE`、`WEB_PROVIDER_AMBIGUOUS`、`WEB_DUPLICATE_PROVIDER`（注册时的编程错误，类似 `LlmService` 的 `DUPLICATE_ADAPTER`）、`WEB_ABORTED`，以及 `WEB_PROVIDER_ERROR`（提供方自身故障经 seam 暴露时使用的兜底代码，包括 DNS、连接被拒绝、TLS 等网络或传输故障）。抓取传输层错误代码由 `dsh-web-fetch-local` 实现拥有，不同的抓取后端无需抛出它们：`WEB_INVALID_URL`、`WEB_BLOCKED_URL`、`WEB_REDIRECT_BLOCKED`、`WEB_FETCH_TOO_LARGE`、`WEB_FETCH_TIMEOUT`、`WEB_UNSUPPORTED_CONTENT_TYPE`。
 
 ## 服务
 
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
index 0b7cdfdc76..fca76bf305 100644
--- a/docs/testing.i18n.yaml
+++ b/docs/testing.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/testing.md
 testing.md: 296dd769118cc5498ddb1bb9c41e2c060b2a5bce
-testing.zh.md: e9182495fbdbb1458c9ff5b30a9591f8b70f27c5
+testing.zh.md: 14b2549c4c3556b6d3bdd5b39d01dee885559dd1
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
index e9182495fb..14b2549c4c 100644
--- a/docs/testing.zh.md
+++ b/docs/testing.zh.md
@@ -6,10 +6,10 @@
 
 ## 层级
 
-- **单元测试**（`pnpm run test`）：vitest 运行包（package）和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及永久性契约回归（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。
+- **单元测试**（`pnpm run test`）：vitest 运行包（package）和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及永久性约定回归（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。
 - **覆盖率门禁**（`pnpm run test:coverage`）：门禁级运行，对 `packages/*/*/src` 按文件 100% 覆盖。未覆盖的行往往是门禁正确标记出的死代码（应删除），而非需要补写的测试。行覆盖率是必要条件，但永远不是充分条件：它证明行被执行过，不证明功能按交付预期工作。`packages/bash/pwsh-local/src` 的按文件 100% 覆盖需要真实的 `pwsh`：缺少它时其 executor 套件会自动跳过，`vitest.config.ts` 会豁免该文件以使无 pwsh 的主机保持绿色，而 CI runner 自带 pwsh，仍按完整标准执行门禁。
 - **真实 API e2e**（`pnpm run test:e2e`）：带密钥测试调用真实提供方 API，包括 DeepSeek 模型以及各提供方特有的冒烟测试；这些测试各自由自己的密钥控制（`EXA_API_KEY`、`PERPLEXITY_API_KEY` 等），缺少密钥时套件会自动跳过，使 keyless CI 保持绿色（[真实 API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md)）。
-- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输契约与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
+- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输约定与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
 - **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 将回放后的浏览器输出与 `apps/web/tests/snapshots/` 比较。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 车道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)以交付插件 CSS。
 
 签入仓库的会话格式 JSONL 使用规范打包行布局，无密钥快照门禁会通过 `session` header 发现每一份此类 fixture。仍携带旧版 fixture 改动的在途分支应合并当前 `master`，并通过 `pnpm run migrate:packed-session-fixtures` 运行[临时迁移器](../scripts/migrate-packed-session-fixtures.ts)；待所有受影响分支收敛后，[移除提案](../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)会移除该命令及这些链接。
@@ -42,7 +42,7 @@ e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身
 
 - CI 与已有构建产物的测试通道通过共享双模式启动器，从构建后的 `lib/` 运行每个示例或 Cordis 配置子进程。不要为这些子进程手写 `--import tsx`。
 - 不加载 Cordis 的协议与操作系统 fixture 直接通过 Node 运行使用可擦除语法的 `.ts` 文件，不经过 tsx 或根路径映射。
-- 只有测试对象本身是源码路径解析时，才可以选择 `src`；在测试中写明这一契约。
+- 只有测试对象本身是源码路径解析时，才可以选择 `src`；在测试中写明这一约定。
 
 ## 何时需要快照测试
 
diff --git a/docs/user/develop/framework/events.i18n.yaml b/docs/user/develop/framework/events.i18n.yaml
index 37dd601646..d6bb924fc7 100644
--- a/docs/user/develop/framework/events.i18n.yaml
+++ b/docs/user/develop/framework/events.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/framework/events.md
 events.md: c70150b4d9070063513021e420f253ff6d4e5de1
-events.zh.md: 813dc3631e0c776ad9c8763db65eebc3f2167578
+events.zh.md: b3b79a86d249eed0df15380e17a1ee71766b1a72
diff --git a/docs/user/develop/framework/events.zh.md b/docs/user/develop/framework/events.zh.md
index 813dc3631e..b3b79a86d2 100644
--- a/docs/user/develop/framework/events.zh.md
+++ b/docs/user/develop/framework/events.zh.md
@@ -22,7 +22,7 @@ ctx.emit('event-name', payload)
 
 ## 事件模式
 
-Cordis 提供多种事件模式，适用于不同的交互契约：
+Cordis 提供多种事件模式，适用于不同的交互约定：
 
 ### emit — 广播
 
diff --git a/docs/user/develop/practice/llm-adapter.i18n.yaml b/docs/user/develop/practice/llm-adapter.i18n.yaml
index 7ea31ce419..a7a745faaf 100644
--- a/docs/user/develop/practice/llm-adapter.i18n.yaml
+++ b/docs/user/develop/practice/llm-adapter.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/practice/llm-adapter.md
 llm-adapter.md: 7445688530c1ba61e5c065f9f5e49db6498da5b1
-llm-adapter.zh.md: e491bc0b6ef633b0b40cb094faf07fc84445c026
+llm-adapter.zh.md: c726735ff2679584d1c061ef8acddc8981dadd26
diff --git a/docs/user/develop/practice/llm-adapter.zh.md b/docs/user/develop/practice/llm-adapter.zh.md
index e491bc0b6e..c726735ff2 100644
--- a/docs/user/develop/practice/llm-adapter.zh.md
+++ b/docs/user/develop/practice/llm-adapter.zh.md
@@ -150,7 +150,7 @@ ctx.llm.registerAdapter(['model-name-1', 'model-name-2'], adapter)
 - `packages/llm/llm-deepseek/` — DeepSeek API 适配器（OpenAI 兼容格式）
 - `packages/llm/llm-pi-ai/` — Pi AI 适配器（不同的 API 格式）
 
-对比这两个已交付的适配器，可以看到同一套 harness 契约如何在不同提供方 SDK 之上实现。
+对比这两个已交付的适配器，可以看到同一套 harness 约定如何在不同提供方 SDK 之上实现。
 
 ## 错误处理
 
diff --git a/docs/web-styling.i18n.yaml b/docs/web-styling.i18n.yaml
index 0cbbafeec9..55277809ef 100644
--- a/docs/web-styling.i18n.yaml
+++ b/docs/web-styling.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/web-styling.md
 web-styling.md: 5296cc7f83f712532262eadda6da098ae9f63ec7
-web-styling.zh.md: 6beec368f2f7fd5eb7606acfaae315d56899c739
+web-styling.zh.md: bec623911269cbd7020c26d5574ee88ca074b5d8
diff --git a/docs/web-styling.zh.md b/docs/web-styling.zh.md
index 6beec368f2..bec6239112 100644
--- a/docs/web-styling.zh.md
+++ b/docs/web-styling.zh.md
@@ -8,7 +8,7 @@
 
 [`ui-theme`](../packages/client/ui-theme/README.md) 负责 `--dsw-*` 静态色阶、语义别名、排版、动效、渐变、阴影、滚动条样式以及明暗主题偏好。[`ui-layout`](../packages/client/ui-layout/README.md) 将解析后的主题快照应用到文档。功能包使用语义别名，不得另行定义全局主题。
 
-全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于组件自身的布局或呈现契约时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
+全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于组件自身的布局或呈现约定时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
 
 ## 组件规则
 
@@ -16,10 +16,10 @@
 - 功能组件使用 `--dsw-alias-*` 语义 token。不得复制静态色板值或在其中写入颜色字面量。
 - 功能组件 CSS 不得包含主题选择器。明暗主题覆盖属于主题所有方。
 - 字体大小必须与行高配对；已有角色匹配时使用主题排版变量。
-- 当组件契约要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
+- 当组件约定要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
 - 呈现规则写在 CSS 中。React 内联样式可以传递组件局部自定义属性值，但不得编码主题分支。
 - 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
 
 ## 变更系统
 
-在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式契约发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 记录框架依据。
+在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) 记录框架依据。
diff --git a/examples/acp-agent/README.i18n.yaml b/examples/acp-agent/README.i18n.yaml
index cf9fee7334..a626a736df 100644
--- a/examples/acp-agent/README.i18n.yaml
+++ b/examples/acp-agent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write examples/acp-agent/README.md
 README.md: 61c6efafe9dde4f91385beebdfd426c57006187b
-README.zh.md: 6eaf9fb5a91c737254e785d8601961b547e4e9ca
+README.zh.md: bd1b0e2200271a71074fbb2475167c25eb309d77
diff --git a/examples/acp-agent/README.zh.md b/examples/acp-agent/README.zh.md
index 6eaf9fb5a9..bd1b0e2200 100644
--- a/examples/acp-agent/README.zh.md
+++ b/examples/acp-agent/README.zh.md
@@ -15,10 +15,10 @@ pnpm run demo:code-mode       # same protocol with the Code Mode tool transport
 
 Stdout 只携带以换行分隔的 ACP JSON-RPC。`@deepseek-ai/dsh-acp-demo` 不安装 stdout logger；该叶节点新增的组件必须使用 stderr 输出诊断信息。
 
-自动化契约（支持的方法、基线提示词内容、已提交文本输出，以及有意缺少的 UI 界面）位于 [`@deepseek-ai/dsh-acp`](../../packages/acp/acp/README.md)。
+自动化约定（支持的方法、基线提示词内容、已提交文本输出，以及有意缺少的 UI 界面）位于 [`@deepseek-ai/dsh-acp`](../../packages/acp/acp/README.md)。
 
 ## 会话 workspace 与权限
 
-每次 `session/new` 都提供一个绝对 `cwd`。受沙箱限制的 bash 和文件系统修改会以该会话 cwd 为基准应用 `workspace-write`，因此并发会话可以使用不同的项目根目录；平台临时根目录仍是共享可写暂存空间（参见[沙箱契约](../../packages/sandbox/sandbox/README.md)）。`DSH_PERMISSION_MODE` 为部署选择 `workspace-write` 或 `danger-full-access`。
+每次 `session/new` 都提供一个绝对 `cwd`。受沙箱限制的 bash 和文件系统修改会以该会话 cwd 为基准应用 `workspace-write`，因此并发会话可以使用不同的项目根目录；平台临时根目录仍是共享可写暂存空间（参见[沙箱约定](../../packages/sandbox/sandbox/README.md)）。`DSH_PERMISSION_MODE` 为部署选择 `workspace-write` 或 `danger-full-access`。
 
 在 `workspace-write` 下，如果模型重试请求更广泛的沙箱访问权限，就会触发 `session/request_permission`，选项为 `allow_once` 和 `reject_once`。客户端以程序方式决策；客户端放弃选择或无法给出答复时，系统会按拒绝处理。选定结果仅适用于该次重试，并通过常规工具结果／审计路径记录。服务器绝不公开权限选择器，也不持久化客户端策略。
diff --git a/examples/web-cordis/README.i18n.yaml b/examples/web-cordis/README.i18n.yaml
index 86cc276a4e..d2004a499c 100644
--- a/examples/web-cordis/README.i18n.yaml
+++ b/examples/web-cordis/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write examples/web-cordis/README.md
 README.md: 21fe0a210b2e591a96dc254014a0f91ed9afa2ba
-README.zh.md: 35158affd5cbdd6f8fa7f5910500f21c2b241309
+README.zh.md: b3fecb4312dbcbaeff460a21f1d2db6b5288f9ad
diff --git a/examples/web-cordis/README.zh.md b/examples/web-cordis/README.zh.md
index 35158affd5..b3fecb4312 100644
--- a/examples/web-cordis/README.zh.md
+++ b/examples/web-cordis/README.zh.md
@@ -18,4 +18,4 @@ pnpm run demo:cordis
 pnpm run demo:cordis acp
 ```
 
-这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全契约由 [Cordis 工具参考](../../packages/self-modification/tool-cordis/README.md)定义。
+这两条命令都需要 `DEEPSEEK_API_KEY`。工具、生命周期和安全约定由 [Cordis 工具参考](../../packages/self-modification/tool-cordis/README.md)定义。
diff --git a/native/landlock-run/README.i18n.yaml b/native/landlock-run/README.i18n.yaml
index 2189d62b3c..58e58a26fe 100644
--- a/native/landlock-run/README.i18n.yaml
+++ b/native/landlock-run/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write native/landlock-run/README.md
 README.md: fcb8e8249e6728d925fd08c938a780b155d3d4ac
-README.zh.md: c994087317be54d522d965de3e120da6fabb7ded
+README.zh.md: 6ae8d7d1d5ae4f2bda90cbf6aa74321a0dab3cb9
diff --git a/native/landlock-run/README.zh.md b/native/landlock-run/README.zh.md
index c994087317..6ae8d7d1d5 100644
--- a/native/landlock-run/README.zh.md
+++ b/native/landlock-run/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个 [Landlock](https://landlock.io/)「先限制自身、再执行」启动器，用于在 Linux 上限制子进程。它以按平台预构建的 npm 包以及一个轻量 JS 入口包的形式发布；入口包负责解析二进制文件并遵循其 CLI（命令行界面）契约。该启动器面向需要让不可信命令在文件系统允许清单约束下运行、同时保持自身不受限制的 agent harness（智能体框架）和其他宿主。
+一个 [Landlock](https://landlock.io/)「先限制自身、再执行」启动器，用于在 Linux 上限制子进程。它以按平台预构建的 npm 包以及一个轻量 JS 入口包的形式发布；入口包负责解析二进制文件并遵循其 CLI（命令行界面）约定。该启动器面向需要让不可信命令在文件系统允许清单约束下运行、同时保持自身不受限制的 agent harness（智能体框架）和其他宿主。
 
 第一个工具是 **`landlock-run`**：一个「先限制自身、再执行」的 [Landlock](https://landlock.io/) 启动器（基于原始内核 UAPI 编写，约 300 行 C11，并与 musl 静态链接）。它在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此命令及其产生的每个进程都在限制下运行，调用进程仍不受限制。它采用失败闭合：如果内核无法强制执行，则不运行命令并直接退出。
 
@@ -41,7 +41,7 @@ if (probe(launcher) !== 'unusable') {
 - `grantArgs({ readOnly?, readWrite? })`：启动器的授权 argv；未授予的一切都被拒绝。
 - `LAUNCHER_BIN` 和 `LAUNCHER_FAILURE_EXIT`（125）：约定常量。成功完成 exec 的子进程也可能返回 125，因此消费方必须同时看到致命诊断和该状态，才能将结果归因为启动器失败。
 
-完整的二进制契约（argv 语法、退出码、报告行）锁定在 [docs/cli-contract.md](docs/cli-contract.md) 中。
+完整的二进制约定（argv 语法、退出码、报告行）锁定在 [docs/cli-contract.md](docs/cli-contract.md) 中。
 
 ## 支持范围
 
diff --git a/native/landlock-run/packages/entry/README.i18n.yaml b/native/landlock-run/packages/entry/README.i18n.yaml
index 7c67f49670..1a701c02bc 100644
--- a/native/landlock-run/packages/entry/README.i18n.yaml
+++ b/native/landlock-run/packages/entry/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write native/landlock-run/packages/entry/README.md
 README.md: fff722428c5d213d9fcce0ee87a1d48cdc189884
-README.zh.md: f462fbe3cb0cb8d1d83b4d6b1d8e2f61e88ff69c
+README.zh.md: cbf867d9dd3551a12b74b19a6ceaf2be3e1c53a6
diff --git a/native/landlock-run/packages/entry/README.zh.md b/native/landlock-run/packages/entry/README.zh.md
index f462fbe3cb..cbf867d9dd 100644
--- a/native/landlock-run/packages/entry/README.zh.md
+++ b/native/landlock-run/packages/entry/README.zh.md
@@ -13,6 +13,6 @@ if (probe(launcher) !== 'unusable') {
 }
 ```
 
-启动器在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此整个进程树都在限制下运行。未授予的一切都被拒绝；启动器失败时以 `125` 退出且不运行命令：采用失败闭合策略，绝不在失败时放行。二进制契约锁定在仓库的 `docs/cli-contract.md` 中；C 源码作为 `src/main.c` 随该 tarball 分发，便于审计。
+启动器在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此整个进程树都在限制下运行。未授予的一切都被拒绝；启动器失败时以 `125` 退出且不运行命令：采用失败闭合策略，绝不在失败时放行。二进制约定锁定在仓库的 `docs/cli-contract.md` 中；C 源码作为 `src/main.c` 随该 tarball 分发，便于审计。
 
 平台包（由 `os`/`cpu` 选择的可选依赖，内部不含 JavaScript）：`@deepseek-ai/node-addon-landlock-run-linux-x64`、`@deepseek-ai/node-addon-landlock-run-linux-arm64`。在缺少对应包的宿主上，`launcherPath()` 返回一个固定但不存在的路径，`probe()` 报告 `'unusable'`；系统有意不提供安装时编译回退。
diff --git a/packages/acp/acp/README.i18n.yaml b/packages/acp/acp/README.i18n.yaml
index 1c8c175eb0..1b303a23a8 100644
--- a/packages/acp/acp/README.i18n.yaml
+++ b/packages/acp/acp/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/acp/acp/README.md
 README.md: 9cc4a5e271c7200f6ad8799a4b8fa9e64b2ca893
-README.zh.md: 4856b44683b5594ad0211af907d1a12ce814d492
+README.zh.md: eafae5602bdeb408ef548a9e706e059bd99bde17
diff --git a/packages/acp/acp/README.zh.md b/packages/acp/acp/README.zh.md
index 4856b44683..eafae5602b 100644
--- a/packages/acp/acp/README.zh.md
+++ b/packages/acp/acp/README.zh.md
@@ -17,7 +17,7 @@
 
 两个字段都是可选的，以便由另一个 agent/request 监听器提供目标。可运行的 ACP 组合同时要求两者。
 
-## 协议契约
+## 协议约定
 
 | 方法 | 行为 |
 |---|---|
diff --git a/packages/api/README.i18n.yaml b/packages/api/README.i18n.yaml
index 6a834cdf4d..e44c33641a 100644
--- a/packages/api/README.i18n.yaml
+++ b/packages/api/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/README.md
 README.md: 7c75e8012459266e0ce09c97416d140e5ac777e1
-README.zh.md: 87bd15fc4e5ad23ef785f7c9ee805a4aa1a35e46
+README.zh.md: f4e882570d2dc929cca466e0bdb05bb2943f2c93
diff --git a/packages/api/README.zh.md b/packages/api/README.zh.md
index 87bd15fc4e..f4e882570d 100644
--- a/packages/api/README.zh.md
+++ b/packages/api/README.zh.md
@@ -9,9 +9,9 @@
 | [`remotes/`](remotes/README.md) | Host Agent/Session lookup 策略与 Client Remote contribution 装配 | 无服务；配置 `ctx.typert` 并消费 `ctx.remote` |
 | [`gateway/`](gateway/README.md) | Host TypeRT 分发器与 Client Remote endpoint | `ctx.typertGateway` / `ctx.remote` |
 
-运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientRemote` 契约，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
+运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientRemote` 约定，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
 
 ## 已知限制与延期工作
 
-- Connection 与 WebServer 仍位于 [`client/connection`](../client/connection/README.md) 和 [`host/webserver`](../host/webserver/README.md)；后续可以只移动包，将它们放到 `api/connection` 和 `api/webserver` 下，而无需改变服务契约。
+- Connection 与 WebServer 仍位于 [`client/connection`](../client/connection/README.md) 和 [`host/webserver`](../host/webserver/README.md)；后续可以只移动包，将它们放到 `api/connection` 和 `api/webserver` 下，而无需改变服务约定。
 - 旧 API Proxy 仍位于 [`host/apiproxy`](../host/apiproxy/README.md)，作为尚未迁移到 Remote 的方法的回退路径。它使用由 `api-remotes` 持有的 Host resolver，使已迁移与旧方法共用同一套 Agent/Session 身份策略。
diff --git a/packages/api/gateway/README.i18n.yaml b/packages/api/gateway/README.i18n.yaml
index 3f4cd32e4d..8e1e98774a 100644
--- a/packages/api/gateway/README.i18n.yaml
+++ b/packages/api/gateway/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/gateway/README.md
 README.md: 0e1a03d2016b8cfbe165dbf1b0a9802290b29502
-README.zh.md: 6b5ccff2340405cc0045147239c5bd4f3eead7da
+README.zh.md: f8c01b489f51fb5e78b608dd9c24a36c7bc64c3a
diff --git a/packages/api/gateway/README.zh.md b/packages/api/gateway/README.zh.md
index 6b5ccff234..f8c01b489f 100644
--- a/packages/api/gateway/README.zh.md
+++ b/packages/api/gateway/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
+为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 约定，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
 
 ## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
 
@@ -20,7 +20,7 @@ Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandle
 
 每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api', endpoint, ...)` 发送。生成的支持取消的方法接受最后一个可选 `AbortSignal`；Client 会在调用 Connection 前将它与贡献项的挂载生命周期合并。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
 
-生成的声明合并通过共享的 `TypeRTClientRemote` 契约提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
+生成的声明合并通过共享的 `TypeRTClientRemote` 约定提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
 
 ## 模型体验
 
diff --git a/packages/api/remotes/README.i18n.yaml b/packages/api/remotes/README.i18n.yaml
index f8f7a6400b..68dbf6263f 100644
--- a/packages/api/remotes/README.i18n.yaml
+++ b/packages/api/remotes/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/remotes/README.md
 README.md: 3d9de0955faefe37c95ff8bb792d57c4fa1f1a3a
-README.zh.md: 7490d68781d3a7b0002b73fe06056ec86c144575
+README.zh.md: 12add6f8efc5b6af3e9b74b26a1abb2bb3936e0a
diff --git a/packages/api/remotes/README.zh.md b/packages/api/remotes/README.zh.md
index 7490d68781..12add6f8ef 100644
--- a/packages/api/remotes/README.zh.md
+++ b/packages/api/remotes/README.zh.md
@@ -8,7 +8,7 @@
 
 当前 Client 组合仅挂载 Goal Remote 贡献。该组合卸载时，Cordis effect 的所有权机制会撤回所有贡献；`@deepseek-ai/dsh-api-gateway/client` 负责描述符校验、可追踪 namespace Service、直接与作用域方法、调用与取消。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 接口，不导入具体 Gateway。
 
-本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 契约，均可复用其 Client face。
+本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 约定，均可复用其 Client face。
 
 ## 构建边界
 
diff --git a/packages/bash/bash-env/README.i18n.yaml b/packages/bash/bash-env/README.i18n.yaml
index 47f4cf01cc..9f73734586 100644
--- a/packages/bash/bash-env/README.i18n.yaml
+++ b/packages/bash/bash-env/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/bash-env/README.md
 README.md: 7b939326d4effd14fc83ef0ad4e133f019f1011f
-README.zh.md: b6f3aca41771f1ca990a4b708cd53119b8e8ad78
+README.zh.md: e3103f32ce1d857267af9589619bed5538d2e6bf
diff --git a/packages/bash/bash-env/README.zh.md b/packages/bash/bash-env/README.zh.md
index b6f3aca417..e3103f32ce 100644
--- a/packages/bash/bash-env/README.zh.md
+++ b/packages/bash/bash-env/README.zh.md
@@ -4,7 +4,7 @@
 
 工具无关的 shell 环境插件：拥有 `ctx.bashEnv` 注册表，管理受信任的、每次执行收集的 `DSH_*` 变量，供模型可见的 shell 工具（`dsh-tool-bash`、`dsh-tool-pwsh`）收集进每次 shell 调用的环境。内置 shell 事实（`DSH_HOME`、`DSH_SHELL=1`、`DSH_SESSION_ID`）归注册表自身所有；其他插件可以注册额外的可枚举事实，注册随插件纤维（fiber）释放，重复所有权或未声明的运行时键会响亮失败。
 
-包根导出 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）以及 `BashEnvRegistry` 服务类及其 contributor 类型；消费者在加载本插件后使用 `ctx.bashEnv`。
+包根导出 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）以及 `BashEnvRegistry` 服务类及其 contributor 类型；消费者在加载本插件后使用 `ctx.bashEnv`。
 
 ## Config
 
diff --git a/packages/bash/tool-bash/README.i18n.yaml b/packages/bash/tool-bash/README.i18n.yaml
index 43ff188d8d..e5eb0dfc41 100644
--- a/packages/bash/tool-bash/README.i18n.yaml
+++ b/packages/bash/tool-bash/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/tool-bash/README.md
 README.md: 47101e1198d13518c3d82877df8726c1fbf26b82
-README.zh.md: d60ac4b3826838e875f7d43bc314f62e1453c1d9
+README.zh.md: c7e0b3ffdc02705bbbd6fd6bd9b8cce2548445f3
diff --git a/packages/bash/tool-bash/README.zh.md b/packages/bash/tool-bash/README.zh.md
index d60ac4b382..c7e0b3ffdc 100644
--- a/packages/bash/tool-bash/README.zh.md
+++ b/packages/bash/tool-bash/README.zh.md
@@ -4,9 +4,9 @@
 
 模型侧 `bash` 工具，注册在 `ctx.bash` 执行器 seam 上。前台执行始终位于该 seam 之后；后台进程句柄会注册到通用 `ctx.tasks` 运行时，并通过 `task_output`、`task_list` 和 `task_kill` 控制；这些工具由 `@deepseek-ai/dsh-tool-tasks` 提供。
 
-需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具契约是 bash 方言——请挂载能解析 bash 的执行器。
+需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具约定是 bash 方言——请挂载能解析 bash 的执行器。
 
-包（package）根只公开 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍保留在包内部。
+包（package）根只公开 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍保留在包内部。
 
 插件还会提供 `tool:bash` 提示词段落（顺序 105）：检查每个结果中的 `[exit code: N]` 标记，发现失败时先调查原因再继续。
 
@@ -28,7 +28,7 @@
 
 ### 托管 shell 环境
 
-每次模型发起的前台或后台 bash 调用都会通过共享的 [`dsh-bash-env`](../bash-env/README.md) 注册表收到新收集的一组可信 `DSH_*` 环境变量：`DSH_HOME`（Harness home 绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及当活跃持久化后端能定位时的 `DSH_SESSION_JSONL`。注册表契约——贡献方注册、重复／未声明键的响亮失败、内置项保留与贡献方示例——住在该包的 README 里。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；本地执行器会先删除继承的所有 `DSH_*` 再合并，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧身份，且绝不修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
+每次模型发起的前台或后台 bash 调用都会通过共享的 [`dsh-bash-env`](../bash-env/README.md) 注册表收到新收集的一组可信 `DSH_*` 环境变量：`DSH_HOME`（Harness home 绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及当活跃持久化后端能定位时的 `DSH_SESSION_JSONL`。注册表约定——贡献方注册、重复／未声明键的响亮失败、内置项保留与贡献方示例——住在该包的 README 里。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；本地执行器会先删除继承的所有 `DSH_*` 再合并，因此嵌套 harness 和并发的父／子 agent 不会泄漏陈旧身份，且绝不修改 `process.env`。工具说明只教授通用 `$DSH_*` 约定，不会点名持久化专用变量，也不会添加永久的系统提示词段落。
 
 结果文本依次包含 stdout、可选的 `[stderr]` 段落和适用的沙箱拒绝、超时、信号、退出代码及截断标记。超时与最终退出状态分别报告；非零退出仍是由模型解释的结果，不会成为 `isError`。截断结果会链接安全的完整 spill 文件，或报告文件不可用。只有 spawn 错误和中止等基础设施故障才会产生 `isError`。
 
@@ -52,7 +52,7 @@
 
 ## 逐会话模式切换
 
-对于启用沙箱的执行器，每次调用依次按单次升权、会话覆盖、执行器默认值解析模式。未启用沙箱以及没有 agent 的调用不携带会话覆盖。策略归属方贡献当前且不区分具体能力的常驻模式；拒绝结果仍负责操作特定的有效模式与重试引导。参见 [`dsh-bash` 整合](../bash/README.md)和[沙箱切换契约](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
+对于启用沙箱的执行器，每次调用依次按单次升权、会话覆盖、执行器默认值解析模式。未启用沙箱以及没有 agent 的调用不携带会话覆盖。策略归属方贡献当前且不区分具体能力的常驻模式；拒绝结果仍负责操作特定的有效模式与重试引导。参见 [`dsh-bash` 整合](../bash/README.md)和[沙箱切换约定](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
 
 ## 模型体验
 
diff --git a/packages/bash/tool-pwsh/README.i18n.yaml b/packages/bash/tool-pwsh/README.i18n.yaml
index 39325f5987..ba4f758814 100644
--- a/packages/bash/tool-pwsh/README.i18n.yaml
+++ b/packages/bash/tool-pwsh/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/tool-pwsh/README.md
 README.md: 78eb161f77b9524bc577b273abe59db6b931727c
-README.zh.md: 17696fe6d908838aaaca12e8179f2ad9cb780210
+README.zh.md: 54614fcfad1cdec5866aa3cc96e52983f4eb1642
diff --git a/packages/bash/tool-pwsh/README.zh.md b/packages/bash/tool-pwsh/README.zh.md
index 17696fe6d9..54614fcfad 100644
--- a/packages/bash/tool-pwsh/README.zh.md
+++ b/packages/bash/tool-pwsh/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-注册在 `ctx.bash` 执行器 seam 之上的模型可见 `pwsh` 工具。面向由 PowerShell 执行器（如 `@deepseek-ai/dsh-pwsh-local`）支撑 `ctx.bash` 的 Windows 组合；工具契约是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量。行为与 `dsh-tool-bash` 逐调用对齐、减去 sandbox 面——通过通用任务运行时执行前台与 `run_in_background`、通过共享 `bash-env` 注册表管理 `DSH_*` 环境、以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。
+注册在 `ctx.bash` 执行器 seam 之上的模型可见 `pwsh` 工具。面向由 PowerShell 执行器（如 `@deepseek-ai/dsh-pwsh-local`）支撑 `ctx.bash` 的 Windows 组合；工具约定是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量。行为与 `dsh-tool-bash` 逐调用对齐、减去 sandbox 面——通过通用任务运行时执行前台与 `run_in_background`、通过共享 `bash-env` 注册表管理 `DSH_*` 环境、以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。
 
 需要已加载的执行器实现与 `bash-env` 插件；两者都存在前工具保持 pending（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。
 
-包根只导出 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染（`src/render.ts`）与后台任务适配（`src/background.ts`）镜像 bash 工具的结构，并可通过包的 `./src/*` 导出访问。
+包根只导出 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）；结果渲染（`src/render.ts`）与后台任务适配（`src/background.ts`）镜像 bash 工具的结构，并可通过包的 `./src/*` 导出访问。
 
 插件还贡献 `tool:pwsh` prompt section（order 105）：非零退出以 `[exit code: N]` marker 报告，Windows 上的中断以无 signal 的 exit 1 结算。
 
@@ -120,5 +120,5 @@ ack 是固定短行；任务输出按读取有界。
 
 - **无 sandbox 升级** — 没有 `sandbox_permissions`/`justification`；升级等待 Windows-confining 执行器（bash 工具的 sandbox 面不被镜像）。
 - **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端目前仅限 Linux/macOS，Windows ConPTY 持久 shell 属于路线图工作。
-- **PowerShell 方言契约** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
+- **PowerShell 方言约定** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
 - **会话 cwd 身份不做规范化** — workdir 基座直接取会话头 cwd 原值，不同于 bash 工具经 sandbox-root 规范化的身份；此处只涉及无 sandbox 场景。
diff --git a/packages/boot/README.i18n.yaml b/packages/boot/README.i18n.yaml
index 8f691dd089..66d3b7b63c 100644
--- a/packages/boot/README.i18n.yaml
+++ b/packages/boot/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/README.md
 README.md: 5e4e483b60adab0b22ddb5279f4cd8fb699b9c35
-README.zh.md: d49afa45b9fb93f6fa83944167057f0c933cd05d
+README.zh.md: 95a3f98129a7d1fdfaffb3cac6fed77bab7cff56
diff --git a/packages/boot/README.zh.md b/packages/boot/README.zh.md
index d49afa45b9..95a3f98129 100644
--- a/packages/boot/README.zh.md
+++ b/packages/boot/README.zh.md
@@ -8,4 +8,4 @@
 |---|---|---|
 | `app-boot/` | app bin 的共享启动粘合层：加载 `.env`、会明确报错的 Loader 保护机制、感知快照的配置解析，以及等待整棵树停稳的启动序列 | （供各 bin 使用的库） |
 
-启动序列与个人配置契约见 [`app-boot/README.md`](app-boot/README.md)。
+启动序列与个人配置约定见 [`app-boot/README.md`](app-boot/README.md)。
diff --git a/packages/bundle/README.i18n.yaml b/packages/bundle/README.i18n.yaml
index 98df59d988..860390d722 100644
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/README.md
 README.md: af06fe921a66378894a4ab0174ef403499f5f68c
-README.zh.md: ef2027e347b79e14574ba1164aa9fddd364327e9
+README.zh.md: b9656649782a638a3b39b4e1e6d330476b0732ba
diff --git a/packages/bundle/README.zh.md b/packages/bundle/README.zh.md
index ef2027e347..b965664978 100644
--- a/packages/bundle/README.zh.md
+++ b/packages/bundle/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 契约](../boot/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
+Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 约定](../boot/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/bundle/web-app/README.i18n.yaml b/packages/bundle/web-app/README.i18n.yaml
index 7662182df0..25bf18dc45 100644
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/web-app/README.md
 README.md: dc35cb4b596b265b70cea81aa5d6784fc1eff65b
-README.zh.md: 0ffc5cdaf1a98e5df11ef042c7d15a994515c170
+README.zh.md: bd14fe03d222f788563df0b562f86446df70b827
diff --git a/packages/bundle/web-app/README.zh.md b/packages/bundle/web-app/README.zh.md
index 0ffc5cdaf1..bd14fe03d2 100644
--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -10,7 +10,7 @@ dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 #### 模型看到的内容
 
-当 `surfaceContext` 为 true 时，全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新契约，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，该提示词段和这些变量都不会注册。
+当 `surfaceContext` 为 true 时，全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新约定，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，该提示词段和这些变量都不会注册。
 
 #### Token 影响
 
diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml
index 2ce3e44fa7..a6474de825 100644
--- a/packages/client/README.i18n.yaml
+++ b/packages/client/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/README.md
 README.md: 56b9363cc724515ecbd11127ea4c13aba84283df
-README.zh.md: edd378bf80b63e9ab2481ab555320ed18de85139
+README.zh.md: 677ebc8158f5b7c63a5bc6ecc94a357e0783c378
diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md
index edd378bf80..677ebc8158 100644
--- a/packages/client/README.zh.md
+++ b/packages/client/README.zh.md
@@ -37,6 +37,6 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
 | [`ui-settings-general/`](ui-settings-general/README.md) | 提供常规设置分区。 |
 | [`ui-models/`](ui-models/README.md) | 提供模型提供方配置与 DeepSeek 配置引导。 |
 
-每个子文档负责自身的契约和详细行为。[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)与 [Web 客户端架构 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)负责跨包组合与加载决策。
+每个子文档负责自身的约定和详细行为。[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)与 [Web 客户端架构 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)负责跨包组合与加载决策。
 
 子系统参考是 [client-modules.md](../../docs/subsystems/client-modules.md)；[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)是权威 slot 模型，[web 客户端架构说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)拥有加载链与对象层。
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index ddfda12f4e..9fca48fb8b 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/connection/README.md
 README.md: 161e34c4b6018625fb690e178eb9a9f8ac0ef21b
-README.zh.md: d17012cc89c02a1b11f16d126b7c0cafe67fb2a0
+README.zh.md: 9bb9405a0e7be5cdbe51b5099e33e2b85225d2fa
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index d17012cc89..9bb9405a0e 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议契约见 api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议约定见 api-contracts v3 §3。
 
 ## /api 浏览器信任栅栏
 
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 92b9e2abfc..f9af3fb8fe 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/runtime/README.md
 README.md: a9b604974595b1b7856f74b72d36093491ec1bd1
-README.zh.md: 8ee06e93b475398750ee74d4900a8c6917cf71f5
+README.zh.md: 41c81532667f445ce1c52e1b84185ef503e82141
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 8ee06e93b4..41c8153266 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象以及 Chat 所需的列表、scope 和事件窗口状态；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本，先加载当前尾部，并仅在消费方请求时向前补入一页更早历史。每份历史快照都会公开原始窗口的绝对基准序号，因此即使该页没有新增任何 surface 可见节点，消费方仍能检测到向前补页。WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager，并把注册表失效帧桥接为类型化 ctx 事件（`commands/changed`、`settings/changed`、`credentials/changed`、`models/changed`），使各表面缓存无需触碰流即可重拉。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。契约：api-contracts v3 §4。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。该 store 还会通过 `SessionSummary.projectionValues` 发布一份引用稳定的完整值映射，使全局列表消费方无需为每个会话创建订阅，即可复用同一组投影。
+客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象以及 Chat 所需的列表、scope 和事件窗口状态；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本，先加载当前尾部，并仅在消费方请求时向前补入一页更早历史。每份历史快照都会公开原始窗口的绝对基准序号，因此即使该页没有新增任何 surface 可见节点，消费方仍能检测到向前补页。WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager，并把注册表失效帧桥接为类型化 ctx 事件（`commands/changed`、`settings/changed`、`credentials/changed`、`models/changed`），使各表面缓存无需触碰流即可重拉。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。约定：api-contracts v3 §4。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。该 store 还会通过 `SessionSummary.projectionValues` 发布一份引用稳定的完整值映射，使全局列表消费方无需为每个会话创建订阅，即可复用同一组投影。
 
 ## Slot 声明注入
 
diff --git a/packages/client/schema-form/README.i18n.yaml b/packages/client/schema-form/README.i18n.yaml
index 73ec057a53..9dfa981a3f 100644
--- a/packages/client/schema-form/README.i18n.yaml
+++ b/packages/client/schema-form/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/schema-form/README.md
 README.md: 716cc7ba3c24f3a4de081e2d26f803b905235fac
-README.zh.md: 61fff15ca6a21e6267da158640e3782422e865c3
+README.zh.md: 9473620da83e73f7a095694b2321f1ebc5f9c53d
diff --git a/packages/client/schema-form/README.zh.md b/packages/client/schema-form/README.zh.md
index 61fff15ca6..9473620da8 100644
--- a/packages/client/schema-form/README.zh.md
+++ b/packages/client/schema-form/README.zh.md
@@ -4,7 +4,7 @@
 
 面向 settings 编辑器的 schema／草稿模型层。wire 侧的 `settings.describe` 携带每个 namespace 的序列化 schemastery schema（`schema.toJSON()` 的 ref 信封）；`rehydrateSchema` 用 `new Schema(json)` 将其还原（rehydrate）为活的校验器——在宿主上校验分节的那份 schema 对象，就是在浏览器里校验草稿的那份对象，因此客户端校验绝不会偏离 seam 侧的校验。编辑器各自渲染自己的控件（Models 页围绕它在此探测到的字段手写自己的卡片）；该包不含任何 React，也不做任何渲染。
 
-## 契约
+## 约定
 
 编辑的单元是**用户分节草稿**：一个以不可变方式编辑的普通对象（`setPath` 会物化中间对象，`deletePath` 即逐字段重置——去掉该键，解析值便回退到组合 base 与 schema 默认值）。字段只要出现在草稿中就被标记为**已覆盖**（`hasPath`）——判定采用存在性语义而非值比较，与 settings seam 的分层方式严格对应。`nodeAtPath` 解析可配置提供方目录 `settingsPath` 所寻址的 schema 节点（object 属性按名称解析，dict 条目经由 `inner`），编辑器因此可以在决定渲染什么之前，先探测某提供方的 profile 携带哪些字段（及其 `meta.role`）；无法解析的路径返回 `undefined`，调用方因此会大声降级，而不是渲染出错误的子树。`validateDraft(schema, draft)` 运行还原出的校验器并返回其失败消息，页面因此可以在写入前拒绝无效草稿。
 
diff --git a/packages/client/ui-command/README.i18n.yaml b/packages/client/ui-command/README.i18n.yaml
index 4d8ace8955..e59b4b2a12 100644
--- a/packages/client/ui-command/README.i18n.yaml
+++ b/packages/client/ui-command/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-command/README.md
 README.md: bc7386c8fca3b5c623473328bee6322fa7295277
-README.zh.md: 478ee4ccee4558c70075baa45ab34ac6e3d71617
+README.zh.md: 54190ac9144b1bfc12ba84a47474311d5a5391ea
diff --git a/packages/client/ui-command/README.zh.md b/packages/client/ui-command/README.zh.md
index 478ee4ccee..54190ac914 100644
--- a/packages/client/ui-command/README.zh.md
+++ b/packages/client/ui-command/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-客户端命令业务面（`ctx.command`）：以会话为 key 的命令目录缓存、带 matchSpace／matchEnter 裁决钩子的 `/` 命令 source、三型派发（execute／popupSelect／leadingInput），以及面向业务包的 popupSelect 注册面。契约：[Web 命令业务面 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md)。
+客户端命令业务面（`ctx.command`）：以会话为 key 的命令目录缓存、带 matchSpace／matchEnter 裁决钩子的 `/` 命令 source、三型派发（execute／popupSelect／leadingInput），以及面向业务包的 popupSelect 注册面。约定：[Web 命令业务面 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md)。
 
 `src/client/contract.ts` 是冻结的业务表层：`CommandServiceContract.register(name, spec)` 与 `decorate(name, spec)` 是业务包消费的全部内容；`CommandUiSpec{options, onSelect}` 让 popup 数据自给自足——壳组件归本包所有，业务永远见不到它。contribution 是 client 自有命令（与 host 同名碰撞即 fail-loud）；decoration（装饰）则把裸调用 popup 挂在**已存在的** host 命令上——host 保留目录行、带参 claim（space / 带参 enter）与生命周期记账，被装饰的名字若在会话目录中无 host 行则装饰永不触发。命令三型按每次派发派生，绝不在注册时定型：带 `input` 的 host descriptor 是 leadingInput，注册了 `CommandUiSpec` 的是 popupSelect，其余全部是 execute。
 
@@ -12,7 +12,7 @@
 
 `PopupSelectController`（`src/client/popup.ts`）是无头的壳状态：`PopupSelectView` 自行注册进 `conversation.input.overlay`（SlotMap key 归 ui-conversation 所有；本包只以 type-only 导入引入该声明——没有运行时依赖边）。壳是打开期间持有焦点的瞬态层；onSelect 之后的 token 片段消费在两条分支上都经 `consumeTokenSegment` 执行（菜单路径做 span CAS，回车路径做裸 token 相等比较），作用于接线层经 `bindDraft` 绑定的草稿表层。
 
-`/client` 导出表层是插件主体（`apply`／`inject`）、`CommandService`、目录类和 popup 类及其状态类型，以及冻结的契约类型；壳组件本身是 overlay 注册的内部实现。
+`/client` 导出表层是插件主体（`apply`／`inject`）、`CommandService`、目录类和 popup 类及其状态类型，以及冻结的约定类型；壳组件本身是 overlay 注册的内部实现。
 
 ## 模型体验
 
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 822a02d321..c03e330672 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
 README.md: f5cf9b72b4f8f4ce7b1a07c0c1e30f5213edf678
-README.zh.md: 90c4dc4cc169b2cbcd7e94275a692e3d062cfe98
+README.zh.md: b3ce1b66308213650505b8838b9b43cb9987c757
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 90c4dc4cc1..b3ce1b6630 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -8,7 +8,7 @@
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
-别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份契约里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的 prompt。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
+别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份约定里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的 prompt。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
 
 视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
@@ -30,7 +30,7 @@ Think 行默认保持折叠，并在不展开思维链的情况下暴露实时
 
 Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。QueueDock 会将其过滤掉，ChatView 则把它投影为会话流末尾带复制操作的用户样式气泡；非用户来源的 next-step 项（注入上下文）改以 `context` placement 广播，领取前不在任何界面渲染。与所有用户样式气泡一样，这里不显示 fork。Host 会等携带该 steering 的持久 `user/message` 进入 mux 流之后再退役 steering。客户端运行时接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史事件无法隐藏后来复用同一 `MessageId` 的单次入队项。气泡交接时因而不会产生空档或重复，会立即从持久节点恢复复制操作与时钟——steering 气泡与 user 气泡一样不带分支操作（[决策](../../../.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.md)）——并能在重连后从同一权威恢复。
 
-键盘消息提交会根据所寻址会话的运行状态和 steering 能力解析投递方式。空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，浏览器持久化的 General Settings 偏好会把普通 Enter 分配为 `Queue`（默认值）或 `Steer`，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 仍然换行。已寻址 subagent 即使正在运行，也会让这两个手势都使用其仅支持 Queue 的继续执行传输。该偏好只影响支持 steering 的繁忙态手势对，发送按钮与非键盘提交操作仍使用 Queue。Composer Steer 复用现有尽力而为的 `session.prompt(mode: 'steer')` 契约：如果当前 next-step 窗口在接纳前关闭，AgentLoop 会把消息接纳为下一条唤醒 Queue 轮次，不显示失败，也不会丢失草稿事务。
+键盘消息提交会根据所寻址会话的运行状态和 steering 能力解析投递方式。空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，浏览器持久化的 General Settings 偏好会把普通 Enter 分配为 `Queue`（默认值）或 `Steer`，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 仍然换行。已寻址 subagent 即使正在运行，也会让这两个手势都使用其仅支持 Queue 的继续执行传输。该偏好只影响支持 steering 的繁忙态手势对，发送按钮与非键盘提交操作仍使用 Queue。Composer Steer 复用现有尽力而为的 `session.prompt(mode: 'steer')` 约定：如果当前 next-step 窗口在接纳前关闭，AgentLoop 会把消息接纳为下一条唤醒 Queue 轮次，不显示失败，也不会丢失草稿事务。
 
 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。
 
diff --git a/packages/client/ui-layout/README.i18n.yaml b/packages/client/ui-layout/README.i18n.yaml
index 613876693a..ee6d490035 100644
--- a/packages/client/ui-layout/README.i18n.yaml
+++ b/packages/client/ui-layout/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-layout/README.md
 README.md: fa60520a20ac8a7f25d494879c68efb06a28998f
-README.zh.md: dd23550cc8f0134ed1231c86d88825dab96e8e79
+README.zh.md: 2ce3d1972d39013d84216596dc57d48ab2d245d9
diff --git a/packages/client/ui-layout/README.zh.md b/packages/client/ui-layout/README.zh.md
index dd23550cc8..2ce3d1972d 100644
--- a/packages/client/ui-layout/README.zh.md
+++ b/packages/client/ui-layout/README.zh.md
@@ -4,7 +4,7 @@
 
 外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏的缩放边界是不可见命中条带，详情栏边界则保留其浮动胶囊；让步期间只有详情栏会收缩并随后自动关闭。关闭的侧边栏仍保留 56px 控制栏，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量，同时拥有一个 `<meta name="theme-color">`，其内容随计算后的 body 背景色更新）。在应用调色板和 token 后进行测量，可确保渲染后的背景成为唯一的颜色依据；呈现器在 dispose（资源释放）时会移除其自有的元数据节点，并一并清除其写入的其他全局状态。
 
-AppFrame 始终挂载会话栏和详情栏；已连接 Session 通过 `SessionProvider` 渲染。布局 store 是瞬时状态，侧边栏以默认宽度启动，详情栏则保持关闭，且该 store 从不读写 `localStorage`。hero 和其他未选中状态也会将详情栏的渲染宽度派生为零，但不会改变存储的宽度偏好。AppFrame 会跨越这些状态保留最后一个非 blank 会话 id：首个会话保持关闭；显式打开详情栏的操作会使用契约默认宽度；返回同一会话时恢复其未改变的宽度；选择不同会话时，详情栏会在绘制前关闭。会话 owner share 为空，侧边栏 owner share 只包含 `collapsed` 和 `width`；注册方通过标准钩子获取业务数据，并从各自的 inject 接口获取操作。
+AppFrame 始终挂载会话栏和详情栏；已连接 Session 通过 `SessionProvider` 渲染。布局 store 是瞬时状态，侧边栏以默认宽度启动，详情栏则保持关闭，且该 store 从不读写 `localStorage`。hero 和其他未选中状态也会将详情栏的渲染宽度派生为零，但不会改变存储的宽度偏好。AppFrame 会跨越这些状态保留最后一个非 blank 会话 id：首个会话保持关闭；显式打开详情栏的操作会使用约定默认宽度；返回同一会话时恢复其未改变的宽度；选择不同会话时，详情栏会在绘制前关闭。会话 owner share 为空，侧边栏 owner share 只包含 `collapsed` 和 `width`；注册方通过标准钩子获取业务数据，并从各自的 inject 接口获取操作。
 
 `/client` 导出表层包含插件主体（`apply`／`inject`）、`LayoutService` 和四个 owner-share 接口。AppFrame、面板 store 与让步求解器仍属于包内部。
 
diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml
index 9f6db24bba..a909395148 100644
--- a/packages/client/ui-model/README.i18n.yaml
+++ b/packages/client/ui-model/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-model/README.md
 README.md: 5a6f998476629566d35af32efa5d8bc5072a872b
-README.zh.md: 09fee7a2cfd22b773be569e37c4c31f8c299d707
+README.zh.md: 55ea296370ffa986c9b11b41f83ef83b12236e88
diff --git a/packages/client/ui-model/README.zh.md b/packages/client/ui-model/README.zh.md
index 09fee7a2cf..55ea296370 100644
--- a/packages/client/ui-model/README.zh.md
+++ b/packages/client/ui-model/README.zh.md
@@ -22,6 +22,6 @@ Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择
 
 ## 已知限制与暂缓事项
 
-- **无创建期或已寻址 subagent 选择**——两个入口都要求既有普通会话的 agent；没有可纳入会话创建的草稿阶段模型选择，subagent 继续执行也有意不公开独立更改模型目标的契约。
+- **无创建期或已寻址 subagent 选择**——两个入口都要求既有普通会话的 agent；没有可纳入会话创建的草稿阶段模型选择，subagent 继续执行也有意不公开独立更改模型目标的约定。
 - **目录名仅供呈现**——选择与持久化使用提供方／模型／推理强度 id；目录查询或确切模型元数据查询失败的提供方以不可选失败行列出，重新加载前保持原样。
 - **不能任意输入推理强度**——composer 仅提供确切模型由适配器公布的推理强度；适配器没有推理元数据时不显示 Effort 行。
diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml
index 9b00e02b2a..92507c838e 100644
--- a/packages/client/ui-sidebar/README.i18n.yaml
+++ b/packages/client/ui-sidebar/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-sidebar/README.md
 README.md: 45ae267d98b17bbc612cf932f5b95b42ba6ff4bf
-README.zh.md: c0bae62de0811874a94810bd18c78378441db8a3
+README.zh.md: a9fb927305d0bab5fb4d27adbfdbec90dfa1dd6d
diff --git a/packages/client/ui-sidebar/README.zh.md b/packages/client/ui-sidebar/README.zh.md
index c0bae62de0..a9fb927305 100644
--- a/packages/client/ui-sidebar/README.zh.md
+++ b/packages/client/ui-sidebar/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-侧边栏插件：真实 Host Workspace 按稳定的 Host 顺序排列；每个 Workspace 按自身顺序包含其 `sessionIds`，并以 `parentId` 嵌套；不属于任何 Workspace 的会话显示在末尾的 `Ungrouped` 分区。搜索、状态点以及折叠到布局拥有的 56px 轨道，都只属于呈现层。契约：[slot 系统标准](../../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)。
+侧边栏插件：真实 Host Workspace 按稳定的 Host 顺序排列；每个 Workspace 按自身顺序包含其 `sessionIds`，并以 `parentId` 嵌套；不属于任何 Workspace 的会话显示在末尾的 `Ungrouped` 分区。搜索、状态点以及折叠到布局拥有的 56px 轨道，都只属于呈现层。约定：[slot 系统标准](../../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)。
 
 New Session 会启动运行时的页面局部前端 Session Intent；真实 Workspace 的「+」会启动一项以该 Workspace 为目标的 Intent。Workspace 标题栏的「+」打开 ui-workspace 的共享选择器，选择结果同样以一个前端会话为目标。Workspace Intent 不会出现在侧边栏中。
 
diff --git a/packages/client/ui-slash/README.i18n.yaml b/packages/client/ui-slash/README.i18n.yaml
index 340f420504..6954134f01 100644
--- a/packages/client/ui-slash/README.i18n.yaml
+++ b/packages/client/ui-slash/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-slash/README.md
 README.md: efb289aaf6b4a442b00e7a0b26ed044b7b061070
-README.zh.md: e2d99514d29b1b5aeeb1d7f42136ec73d961f3e7
+README.zh.md: c6d3236f615642b9efc6fabaa7ec407ad896a8e2
diff --git a/packages/client/ui-slash/README.zh.md b/packages/client/ui-slash/README.zh.md
index e2d99514d2..c6d3236f61 100644
--- a/packages/client/ui-slash/README.zh.md
+++ b/packages/client/ui-slash/README.zh.md
@@ -4,11 +4,11 @@
 
 输入触发流水线插件：光标处的 `/` 与 `@` 检测（词边界 + guard tier 规则）、分组候选菜单，以及把 pick 路由到已注册 source。`ctx.slash` 拥有 source roster，并按会话 scope（`sessionOf`）各解析一个 `SlashController`；对话接线层在 controller 上驱动 `track`／`arbitrate`／`onSpace`／`adjudicate`。同一个 controller 还暴露 `toggleSource`，供 chrome launcher 在一段合成 selection span 上只打开一个已注册 source；所得候选仍走通常的菜单、键盘仲裁、pick callback 与 scoped 输入改写。source 每次调用收到一个 `ClientSessionContext` 投影——会话始终由 agent（智能体）支撑，因此投影只含会话身份。source 在它能触达的每个会话 controller 中都会被预热：scope 出生时在场的 roster 随 controller 构造预热，晚于此注册的 source 由注册动作本身预热进每个活 controller。`lexicon` 名录在预热后仍会变化的 source 实现 `subscribeLexicon(session, listener)`；controller 每收到通知就重拉，并把聚合结果经其 `lexicon` 快照 store 发布。流水线与命令无关：空格／回车裁决按注册序轮询可选的 `matchSpace`／`matchEnter` 钩子，第一个非 undefined 的应答胜出。
 
-分层：`src/core/`（T2）是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包契约（设计 v4 §5.1）；变更需经主线程仲裁。
+分层：`src/core/`（T2）是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包约定（设计 v4 §5.1）；变更需经主线程仲裁。
 
 MenuView 把菜单 store 渲染进 `conversation.input.overlay` slot（列表类，会话 scope），菜单关闭期间渲染 null。键入式 trigger 会 seed 为该 trigger 注册的所有 source；程序化 launcher 只 seed 所请求的 source，并在菜单关闭或重新开始键入式 tracking 前，通过 controller 的 `launcher` 快照 store 发布该 source 名称。分组按可选的 `SlashSource.order` 排序（越小越靠前，默认 0，同值保持注册序），组标题行经 `slash.menu` locale 命名空间本地化（未知 source 显示其原名）；列表高度收敛到 composer 上方的可用空间，指针落在菜单与所在 composer 卡片之外即关闭菜单。该 slot 由 ui-conversation 的组合器条目拥有（锚点、children 声明、生命周期）；其 SlotMap 类型合并放在本包的 `src/client/slots.ts`，因为依赖方向（ui-conversation → ui-slash）不允许反向的类型导入。combobox 模式：焦点始终留在 textarea，行在 mousedown 时完成 pick，高亮由 `aria-activedescendant` 承载。
 
-`/client` 导出表层是插件主体（`apply`／`inject`）、`SlashService`、`MenuViewInjected` 与契约类型。MenuView 本身是内部实现——slot 注册以闭包持有它。
+`/client` 导出表层是插件主体（`apply`／`inject`）、`SlashService`、`MenuViewInjected` 与约定类型。MenuView 本身是内部实现——slot 注册以闭包持有它。
 
 ## 模型体验
 
diff --git a/packages/client/ui-slots/README.i18n.yaml b/packages/client/ui-slots/README.i18n.yaml
index 7b67f66d3b..a3bf047f84 100644
--- a/packages/client/ui-slots/README.i18n.yaml
+++ b/packages/client/ui-slots/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-slots/README.md
 README.md: bb489dea0c3848cf3d501dcf095a65fe1cef9ef6
-README.zh.md: 91e4f817c414e11645aa4d3a1b9bcf94f9678805
+README.zh.md: 8b10ddf2d974c3054b5e086a302cd8f84dca9667
diff --git a/packages/client/ui-slots/README.zh.md b/packages/client/ui-slots/README.zh.md
index 91e4f817c4..8b10ddf2d9 100644
--- a/packages/client/ui-slots/README.zh.md
+++ b/packages/client/ui-slots/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Slot 注册表纯核心、slot 终端设计：SlotMap 声明合并、SlotCore 上唯一的 `register` 组合 API、四 share 组件 props 类型家族、store seat 类型家族，以及 renderer 安装 seam 契约。只使用 React 类型；该包不依赖 React，也不依赖 Cordis。
+Slot 注册表纯核心、slot 终端设计：SlotMap 声明合并、SlotCore 上唯一的 `register` 组合 API、四 share 组件 props 类型家族、store seat 类型家族，以及 renderer 安装 seam 约定。只使用 React 类型；该包不依赖 React，也不依赖 Cordis。
 
 一次 `register({ name, children?, store?, inject?, ...kind }, Component)` 调用会向已声明 slot 贡献一个组件，同时声明子 slot（声明 = 渲染授权 = 运行时规范，三者共用一张表）、store seat 以及注册方的业务表层。组件会在调用点依据 `ComposedProps` 接受检查；该类型是四个 share 的交集，每个 share 都从各自的唯一真源派生：
 
@@ -17,7 +17,7 @@ chain-kind slot 会反转键控路由：条目自行提名，而不是由分发
 
 标准工具包接口（`SessionStandardProps`、`GlobalStandardProps`）在这里声明为空，由 runtime 包合并（与 SlotMap key 相同的 declare-merge 模式）。renderer 会把运行时 Session 和 Workspace observable source 绑定为 selector hook。Inject factory 参数从声明派生（`InjectParams`）：Session slot 获得 `sessionId`；声明 store 时追加 baked `actions`；没有其他参数，数据访问位于 apply 闭包的 ctx 中。
 
-store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 契约。引擎产物与 renderer host 契约携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制这一侧的 seam，只有 props 契约 hook 类型（`SnapshotSelectorHook`）位于这里。
+store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 约定。引擎产物与 renderer host 约定携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制这一侧的 seam，只有 props 约定 hook 类型（`SnapshotSelectorHook`）位于这里。
 
 `SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与移除时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装 seam（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
 
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index 6ca3d905b4..35b576523d 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-theme/README.md
 README.md: 648213b258169b2e8869a93d058fcc65aece175e
-README.zh.md: 02481badc816e0eb42c0d2496c9a096d2dbdbccb
+README.zh.md: ec29b9be999d64eee76342f0a86eb8707807be06
diff --git a/packages/client/ui-theme/README.zh.md b/packages/client/ui-theme/README.zh.md
index 02481badc8..ec29b9be99 100644
--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有主题偏好（`light`／`dark`／`system`，以 `dsh.theme` 为键持久化），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。契约：api-contracts v3 §8。
+主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有主题偏好（`light`／`dark`／`system`，以 `dsh.theme` 为键持久化），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。约定：api-contracts v3 §8。
 
 `src/styles/` 下有五张样式表，全部由 web 壳的 `base.css` 导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
 
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 97008e3e0c..ca5f3cd25c 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-tool/README.md
 README.md: d6bc0f248cffaf4c65ecf6d97c7a4afb17fc8941
-README.zh.md: f4e8044fe6e10e1fbdfb70987efe07c884fa9ac8
+README.zh.md: 6b6e2a153be6a3cad5b57379de6fdc0cd4a58ea4
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index f4e8044fe6..6b6e2a153b 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -6,11 +6,11 @@ Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交
 
 业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和递归 `subCalls` 投影；conversation view 继续负责 ChatFlow 位置。
 
-## 渲染契约
+## 渲染约定
 
 `ToolCallTree` 接收一个已经包含递归 `subCalls` 的 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准 call block，让 root 与任意深度的 child 经过同一条原子分发路径，不再订阅独立的 parent-to-children map。
 
-每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 契约，供分页和 selection 使用。
+每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 约定，供分页和 selection 使用。
 
 本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 为 `terminal`、`read`、`diff`、`search` 和 `web` render intent 共用同一组纯 card model。本版本不认识的 intent 标签和格式错误的 wire card 数据都会回退为压平的 Tool result 文本。
 
@@ -44,6 +44,6 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ## 已知限制与后续工作
 
-- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时/UI 契约已为未来的嵌套生产者做好准备。
+- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时/UI 约定已为未来的嵌套生产者做好准备。
 - 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
 - Tool 文案暂时复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-trajectory/README.i18n.yaml b/packages/client/ui-trajectory/README.i18n.yaml
index 83f0b0b2e5..e0646b2da8 100644
--- a/packages/client/ui-trajectory/README.i18n.yaml
+++ b/packages/client/ui-trajectory/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-trajectory/README.md
 README.md: 2c737fe2d04df518e7d32d07aaede714a7a3566d
-README.zh.md: 738d6cafa0c6d44f05fecec01d565da91ef433e8
+README.zh.md: 1baa5a1a4422731161e6c8a743aa337a0e5cc774
diff --git a/packages/client/ui-trajectory/README.zh.md b/packages/client/ui-trajectory/README.zh.md
index 738d6cafa0..1baa5a1a44 100644
--- a/packages/client/ui-trajectory/README.zh.md
+++ b/packages/client/ui-trajectory/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Trajectory 渲染按轮次组织的事件记录表，其中可选择用户、助手、工具和嵌套子工具记录。较粗的分割线标示轮次边界，紧凑的行内标记标识步骤，主记录表仅保留索引、事件和内容；选择记录则会打开局部检查器，查看 token 用量、耗时、输入、输出和计时。可滚动的概述区域默认保持滚动条滑块透明，直到鼠标悬停该区域或其中包含键盘焦点时才显示，同时不改变滚动条预留的几何空间。独立运行的压缩（compaction）请求会按时间顺序显示在自己的 `Between turns` 区段中，而带编号的压缩仍位于其所属轮次内。长记录表打开时定位于当前尾部，用户到达已加载范围顶部时加载一页更早的历史，并且只挂载可见行窗口和少量额外缓冲行；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键和 ARIA 索引在向前补页后保持不变。选择、时间线导航、折叠、搜索和请求汇总只覆盖当前已加载的窗口。初始尾部完成定位前以及更早页面仍在等待时，记录表会用明确的加载行遮住真实记录。固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；仍有更早记录未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会标识被省略的前缀，并可加载一页更早历史，而不会为未知部分虚构耗时。助手时间条会区分记录到的 TTFT 与解码时间，悬停 500 ms 后可查看精确时刻和耗时详情。拖选一个区间会将记录表聚焦到活动区间与该闭区间有重叠的所有记录，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除所选区间；在已放大的 viewport 上按住右键拖动则只会平移视图，不会改变该区间。初始视图和流式更新都会停留在尾部；向上滚动会暂停跟随，因此新记录不会打断对旧记录的检查。仅含内容更新的流式帧会保持虚拟行的键和高度不变、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复在检查投影中仅保留首个可见 token 和用量分片，未完成及中断的回复则保留所有分片；独立数据源中的原始历史保持不变。Trajectory 要求会话壳将 composer 作为浮层置于全高记录表上方；其响应式纵向滚动容器会预留 composer 的实时高度，确保仍可滚动到最后几行。运行时的独立历史数据源提供原始上下文谱系，并投影因取消而冻结的助手和工具记录，因此 Trajectory 既不读取也不改变 Chat 会话快照。该包保持为纯消费方插件（向会话的 `'conversation.view'` slot 环注册一个视图标签页，不提供服务，也不声明 Context 合并）。契约：api-contracts v3 §8。
+Trajectory 渲染按轮次组织的事件记录表，其中可选择用户、助手、工具和嵌套子工具记录。较粗的分割线标示轮次边界，紧凑的行内标记标识步骤，主记录表仅保留索引、事件和内容；选择记录则会打开局部检查器，查看 token 用量、耗时、输入、输出和计时。可滚动的概述区域默认保持滚动条滑块透明，直到鼠标悬停该区域或其中包含键盘焦点时才显示，同时不改变滚动条预留的几何空间。独立运行的压缩（compaction）请求会按时间顺序显示在自己的 `Between turns` 区段中，而带编号的压缩仍位于其所属轮次内。长记录表打开时定位于当前尾部，用户到达已加载范围顶部时加载一页更早的历史，并且只挂载可见行窗口和少量额外缓冲行；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键和 ARIA 索引在向前补页后保持不变。选择、时间线导航、折叠、搜索和请求汇总只覆盖当前已加载的窗口。初始尾部完成定位前以及更早页面仍在等待时，记录表会用明确的加载行遮住真实记录。固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；仍有更早记录未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会标识被省略的前缀，并可加载一页更早历史，而不会为未知部分虚构耗时。助手时间条会区分记录到的 TTFT 与解码时间，悬停 500 ms 后可查看精确时刻和耗时详情。拖选一个区间会将记录表聚焦到活动区间与该闭区间有重叠的所有记录，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除所选区间；在已放大的 viewport 上按住右键拖动则只会平移视图，不会改变该区间。初始视图和流式更新都会停留在尾部；向上滚动会暂停跟随，因此新记录不会打断对旧记录的检查。仅含内容更新的流式帧会保持虚拟行的键和高度不变、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复在检查投影中仅保留首个可见 token 和用量分片，未完成及中断的回复则保留所有分片；独立数据源中的原始历史保持不变。Trajectory 要求会话壳将 composer 作为浮层置于全高记录表上方；其响应式纵向滚动容器会预留 composer 的实时高度，确保仍可滚动到最后几行。运行时的独立历史数据源提供原始上下文谱系，并投影因取消而冻结的助手和工具记录，因此 Trajectory 既不读取也不改变 Chat 会话快照。该包保持为纯消费方插件（向会话的 `'conversation.view'` slot 环注册一个视图标签页，不提供服务，也不声明 Context 合并）。约定：api-contracts v3 §8。
 
 ## 模型体验
 
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index 3f2ea68116..99d66e084f 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime/README.md
 README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
-README.zh.md: fff62b97b8ef76901e4680fb6c6c8ff4820ba35d
+README.zh.md: 2a68e6f05d12b737bdff530a351aa038628d85fc
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index fff62b97b8..2a68e6f05d 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -14,11 +14,11 @@
 | `language` | 只读描述符：`run` 期望的源语言。已知值为 `'typescript'` 与 `'python'`——`dsh-tools` 能呈现的那些；其中只有 `'typescript'` 有已发布的后端。仅供参考，不作门禁；生成语言专用呈现的消费方会根据该值选择分支，遇到无法呈现的语言时明确失败。 |
 | `isolation` | 只读描述符：执行基底（`'worker-thread'`、`'process'`、`'container'`）。供部署与诊断使用，**不构成安全声明**。 |
 
-每个实现都必须遵守以下语义（完整契约见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为敌对对等方（任意绑定名称都会成为自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；dispose 会终止进行中的运行，并且在完成前等待其退出。
+每个实现都必须遵守以下语义（完整约定见类 JSDoc）：绑定调用会桥接完整的无损 JSON 参数与 resolve 值，seam 层不设字节上限；程序被视为敌对对等方（任意绑定名称都会成为自有属性，格式错误的通信绝不能使宿主崩溃）；不同运行之间不保留任何状态；dispose 会终止进行中的运行，并且在完成前等待其退出。
 
 ## 词汇
 
-`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整契约见 `src/types.ts`。
+`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整约定见 `src/types.ts`。
 
 binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的约定——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
 
@@ -33,6 +33,6 @@ binding-global 与 error-class 名称是**语言可移植**的：必须匹配标
 ## 已知限制与暂缓事项
 
 - **`run()` 是一次性的**：`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供正在运行的程序所产生输出的流式日志或进度接口。
-- **持久 REPL 风格内核已记录为未来工作**：在持久内核后端带来自己的日志方案前，运行之间不保留状态的契约继续有效（参见 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)）。
+- **持久 REPL 风格内核已记录为未来工作**：在持久内核后端带来自己的日志方案前，运行之间不保留状态的约定继续有效（参见 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)）。
 - **目前只提供 worker 线程后端**：`'process'`／`'container'` 是已经声明但没有实现的已知 `isolation` 值；强安全边界需要等待容器后端。
 - **中间绑定值没有字节上限**：实现仍受 structured-clone 成本与进程内存约束，而提供方或执行器可能已经应用自己的获取上限。
diff --git a/packages/compact/README.i18n.yaml b/packages/compact/README.i18n.yaml
index bdbb81127c..7e8ef24260 100644
--- a/packages/compact/README.i18n.yaml
+++ b/packages/compact/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/compact/README.md
 README.md: 0a83b87f57e4c948ee6df9e622f17964aff00f0f
-README.zh.md: 431e84ec645ae08da203e2d68e1f6813dd7ded2d
+README.zh.md: 001ca6f7c079a60cbd432664e4f0b06955aaf487
diff --git a/packages/compact/README.zh.md b/packages/compact/README.zh.md
index 431e84ec64..001ca6f7c0 100644
--- a/packages/compact/README.zh.md
+++ b/packages/compact/README.zh.md
@@ -13,4 +13,4 @@
 
 后端、可选修剪器和用户命令通过该 seam 组合；token 测量仍是独立的 LLM（大语言模型）家族服务。[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 负责说明依赖关系的设计依据。
 
-子系统参考——`compact/*` 事件、`CompactionResult`、服务、修剪结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在 [压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
+子系统参考——`compact/*` 事件、`CompactionResult`、服务、修剪结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
diff --git a/packages/compact/command-compact/README.i18n.yaml b/packages/compact/command-compact/README.i18n.yaml
index 68dfebd1b9..b1329c13db 100644
--- a/packages/compact/command-compact/README.i18n.yaml
+++ b/packages/compact/command-compact/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/compact/command-compact/README.md
 README.md: 5af39e82928d64c11474199b6b30058e9d289f45
-README.zh.md: a582bd5272b2e39ac1ffbf839888a4006b6d44bc
+README.zh.md: 70fac7ba495ae57757fbe73bd5c61951dd0c2fe9
diff --git a/packages/compact/command-compact/README.zh.md b/packages/compact/command-compact/README.zh.md
index a582bd5272..70fac7ba49 100644
--- a/packages/compact/command-compact/README.zh.md
+++ b/packages/compact/command-compact/README.zh.md
@@ -4,7 +4,7 @@
 
 通过 [`ctx.compact`](../compact/README.md) 提供面向用户的 `/compact` 压缩（compaction）控制。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此组合中的每个命令适配器都能发现并执行它，无需模型轮次。[排队手动压缩 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md)拥有接纳、锁与持久性决策。
 
-## 命令契约
+## 命令约定
 
 | 输入 | 结果 |
 |---|---|
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index 1252d99e0f..dc2254d647 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/compact/compact/README.md
 README.md: 2bf39cac91798b1e0fdb679d2a9b674caceffe22
-README.zh.md: 330b5b0cb9d5c2bf3953354112f3488447e71f87
+README.zh.md: d068869f1d9091e9671d8c2fb17df53a48c9916d
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index 330b5b0cb9..d068869f1d 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -12,7 +12,7 @@
 | `@deepseek-ai/dsh-compact-basic` | 后端：`ctx.tokenMeter` 压力 + token 预算保留 + `llm.stream()` 摘要 |
 | `@deepseek-ai/dsh-command-compact` | 面向用户的 `/compact` 命令，基于 `ctx.compact.compactNow()` 实现 |
 
-与 bash seam 不同，该接口依赖 `@deepseek-ai/dsh-session` 和 `@deepseek-ai/dsh-llm`。契约的动词基于 `Session` 定义，其输出使用 `ContentBlock` 词汇，因此无法在不指名这些包的情况下表达。这项对「接口只依赖 cordis」指引的偏离是有意的，并记录在 [压缩能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 中。
+与 bash seam 不同，该接口依赖 `@deepseek-ai/dsh-session` 和 `@deepseek-ai/dsh-llm`。约定的动词基于 `Session` 定义，其输出使用 `ContentBlock` 词汇，因此无法在不指名这些包的情况下表达。这项对「接口只依赖 cordis」指引的偏离是有意的，并记录在 [压缩能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 中。
 
 ## 服务 API（`ctx.compact`）
 
@@ -36,7 +36,7 @@
 
 每个会话的私有 cache 以 `session.surface.replaceGeneration` 和已处理表层条目数为 key。generation 未变时，只需将尚未处理的尾部条目纳入累计结果；仅向日志追加、但未新增表层条目时，不会读取事件。replace generation 变化时则会重建当前成员关系与配对状态。事件 seq 缺失以及 `tool/result` 没有对应的先前未闭合调用，均会被视为表层状态损坏并遭拒绝。
 
-## 表层契约
+## 表层约定
 
 `SurfaceEventType` 是封闭联合：只有 `user/message`、`assistant/message` 和 `tool/result` 可以携带 `surfaceOp`。因此 `compact/*` 事件**不能**出现在表层上。成功压缩改为：
 
@@ -89,5 +89,5 @@
 ## 已知限制与暂缓事项
 
 - **面向用户的命令，而非模型工具**：`@deepseek-ai/dsh-command-compact` 通过 `ctx.commands` 暴露无参数 `/compact`；不会注册面向模型的压缩工具。
-- **部分单元溢出不在契约内**：平衡摘要压缩无法拆分一个不可分单元。当闭合工具对中可移除的主要部分是承载文本的工具结果时，可选剪枝配套服务仍可修复该工具对；无法压缩大型非工具节点，或不可剪枝剩余部分过大的工具单元。
+- **部分单元溢出不在约定内**：平衡摘要压缩无法拆分一个不可分单元。当闭合工具对中可移除的主要部分是承载文本的工具结果时，可选剪枝配套服务仍可修复该工具对；无法压缩大型非工具节点，或不可剪枝剩余部分过大的工具单元。
 - **单独接近窗口大小的 envelope 不属于表层压缩工作**：压缩缩减派生历史，绝不缩减系统提示词、工具或会话前缀。
diff --git a/packages/context/session-reference/README.i18n.yaml b/packages/context/session-reference/README.i18n.yaml
index 24fb2c24dc..18ce315cd5 100644
--- a/packages/context/session-reference/README.i18n.yaml
+++ b/packages/context/session-reference/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/context/session-reference/README.md
 README.md: 145ec112d6b9cce9e9eb1567c60cde41c6d6eb3c
-README.zh.md: 71bab6c94161a37de507482405fb8362e08a89fa
+README.zh.md: 5d528a296ee77dc64b584d0683395cb4df67936a
diff --git a/packages/context/session-reference/README.zh.md b/packages/context/session-reference/README.zh.md
index 71bab6c941..5d528a296e 100644
--- a/packages/context/session-reference/README.zh.md
+++ b/packages/context/session-reference/README.zh.md
@@ -18,7 +18,7 @@
 
 ## 配置
 
-| Key | 默认值 | 契约 |
+| Key | 默认值 | 约定 |
 |---|---:|---|
 | `maxReferences` | `3` | 一条已准备消息中不同源会话的最大数量；必须不大于 `3`。 |
 | `candidateLimit` | `50` | 返回给宿主的默认候选数量。 |
@@ -44,7 +44,7 @@
 
 ## 已知限制与暂缓事项
 
-- **不支持消息正文检索**：候选查询会检查折叠后的标题，但不搜索消息主体。非空查询可能通过 session-query 服务有界、可取消的批处理检查每个可见的持久化会话日志；专用标题索引未来可以替换这条发现路径，而不改变 URI、快照或持久化契约。
+- **不支持消息正文检索**：候选查询会检查折叠后的标题，但不搜索消息主体。非空查询可能通过 session-query 服务有界、可取消的批处理检查每个可见的持久化会话日志；专用标题索引未来可以替换这条发现路径，而不改变 URI、快照或持久化约定。
 - **受信任调用方边界**：该服务假设宿主有权读取 `ctx.sessionQuery` 公开的每个会话；它不是面向模型的搜索工具。
 - **只投影文本**：不会在会话间传播非文本 user 与 assistant 块。
 - **没有实时链接**：引用是快照，不是 fork、恢复、订阅或源会话变更。
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index f80bc0cc79..c8a81c8d13 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent-loop/README.md
 README.md: 81bc4411977f7335defef5af82d4a67a740b2ed5
-README.zh.md: f14810ecf56f80c1f2a768aaf315415159e2c021
+README.zh.md: 22f9655d46c4c9764118f05cc919be26a471c00b
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index f14810ecf5..22f9655d46 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -31,7 +31,7 @@
 
 ### 不变量配套入口
 
-可选的 `@deepseek-ai/dsh-agent-loop/invariant` 配套入口会向 `ctx.invariants` 注册请求重建。循环会把每个确切的冻结请求记录在 `dsh-llm` 拥有的进程本地身份集合中；随后，配套入口要求存在实时会话，并根据日志独立重建消息边界和折叠后的请求 header。即使调用方冻结直接的一次性调用，或为其附加会话 id，这类调用仍不属于该契约。
+可选的 `@deepseek-ai/dsh-agent-loop/invariant` 配套入口会向 `ctx.invariants` 注册请求重建。循环会把每个确切的冻结请求记录在 `dsh-llm` 拥有的进程本地身份集合中；随后，配套入口要求存在实时会话，并根据日志独立重建消息边界和折叠后的请求 header。即使调用方冻结直接的一次性调用，或为其附加会话 id，这类调用仍不属于该约定。
 
 ### 配置（Schemastery）
 
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index b2d54ebc66..53a1a1f650 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent/README.md
 README.md: 3a3bdf6a4b3bdc5bfef250495e84b7d90b003822
-README.zh.md: 4295c15923f6a5c6132369bfe2137e3d34dec6b1
+README.zh.md: e421070a6eec2e6e7e1fc7b45f0a5e29040bf712
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index 4295c15923..e421070a6e 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -32,7 +32,7 @@ Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事
 - `ctx.agents.withInitiator(agent, operation)`：使用一个确切 Agent 运行，并保留操作的确切同步值或 Promise。
 - `ctx.agents.withoutInitiator(operation)`：对无关的进程本地工作隐藏继承的发起方。
 
-该作用域携带 `Agent` 本身，并且只在进程内有效。环境中的身份既不是存活证明，也不是授权；在服务、worker、进程、持久化和 wire 边界，显式 Agent 字段仍是权威来源。Teardown 会拒绝新边界，允许注入的依赖方和返回 Promise 的边界 drain，然后禁用底层 `AsyncLocalStorage`；未返回的工作仍归将其分离的子系统所有。如果某个边界继承的异步链开始卸载一个拥有它的 Cordis fiber，该嵌套边界链会从 drain 中释放，使卸载不会等待自身；其 continuation 会在 teardown 后观察到已 dispose 的服务。详细边界与 teardown 契约由[发起方作用域决策](../../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)拥有。
+该作用域携带 `Agent` 本身，并且只在进程内有效。环境中的身份既不是存活证明，也不是授权；在服务、worker、进程、持久化和 wire 边界，显式 Agent 字段仍是权威来源。Teardown 会拒绝新边界，允许注入的依赖方和返回 Promise 的边界 drain，然后禁用底层 `AsyncLocalStorage`；未返回的工作仍归将其分离的子系统所有。如果某个边界继承的异步链开始卸载一个拥有它的 Cordis fiber，该嵌套边界链会从 drain 中释放，使卸载不会等待自身；其 continuation 会在 teardown 后观察到已 dispose 的服务。详细边界与 teardown 约定由[发起方作用域决策](../../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)拥有。
 
 #### 工厂 seam（创建）
 
@@ -46,9 +46,9 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 ### 实时事件
 
-`dsh-agent` 声明实时 `agent/*` 协调词汇，使插件不必依赖具体循环。确切签名、分发 mode、作用域筛选规则与 payload 契约位于 [core.md](../../../docs/subsystems/core.md#cordis-surface) 的生成区块；[架构轮次流](../../../docs/architecture.md#turn-flow) 展示它们与持久会话事件的相对顺序。
+`dsh-agent` 声明实时 `agent/*` 协调词汇，使插件不必依赖具体循环。确切签名、分发 mode、作用域筛选规则与 payload 约定位于 [core.md](../../../docs/subsystems/core.md#cordis-surface) 的生成区块；[架构轮次流](../../../docs/architecture.md#turn-flow) 展示它们与持久会话事件的相对顺序。
 
-生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序契约。
+生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序约定。
 
 大多数拦截点都是协作式 waterfall（瀑布式事件）。`agent/pre-step` 接收一个 payload，携带主体 `agent`、独占的已领取 `UserMessage[]` 以及拟进入的 `turn`、`step` 与取消 `signal`；当工具已经要求继续请求时，该批次可以为空。agent 作用域轮次 seam 在 payload 中携带显式 `AbortSignal`；其余轮次作用域 seam 通过其请求值接收它。监听器可以配合信号，但不得将它保留为控制另一轮次的权限。`agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域运行时设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
 
@@ -111,7 +111,7 @@ inbox 的实时通知刻意采用逐消息的最小载荷：`agent/inbox/inserte
 ## 已知限制与暂缓事项
 
 - **发起方作用域只存在于进程内**：worker、子进程、HTTP、持久队列和重启必须显式传递所需身份。
-- **环境身份可能比存活状态更久**：消费方在生命周期敏感工作前，仍要检查 `agent.status`、取消状态和所属能力契约。
+- **环境身份可能比存活状态更久**：消费方在生命周期敏感工作前，仍要检查 `agent.status`、取消状态和所属能力约定。
 - **委派以外的 agent 间通道**：共享状态、流式子输出和后台／轮询语义仍在当前同步 `ctx.subagents` seam 之外。
 - **`agent/session-start` 不能为启动设置门禁**：它仍是同步且不可 veto 的通知；必须在发布前完成的异步组合属于工厂的 `setup(agentCtx)` 事务。
 - **`cancel()` 默认清空 inbox**：它会中止正在处理的轮次以及排队和 steering 工作；`cancel(cause, { keepInbox: true })` 只中止轮次并保留待处理项。仍不存在只中止步骤、同时让正在处理的轮次继续运行的操作（[关于停止操作接口的 Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)）。
diff --git a/packages/core/scope/README.i18n.yaml b/packages/core/scope/README.i18n.yaml
index c9212a3998..8b49f4387b 100644
--- a/packages/core/scope/README.i18n.yaml
+++ b/packages/core/scope/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/scope/README.md
 README.md: 4f32573779a15e8c34b4936bfe75549dfc86d9f6
-README.zh.md: 16ec60a5489f909a46fd5f803dbf08490cd07988
+README.zh.md: d046a8a1e559a56a942d0b3da3b213e79af3abd3
diff --git a/packages/core/scope/README.zh.md b/packages/core/scope/README.zh.md
index 16ec60a548..d046a8a1e5 100644
--- a/packages/core/scope/README.zh.md
+++ b/packages/core/scope/README.zh.md
@@ -14,14 +14,14 @@
 - `scopeTarget(base: T, key: ScopeKey | undefined): Scoped<T>`：为按作用域筛选的事件构造不透明分发 `thisArg`。它把 `base` 现有的 `Context.filter` 与作用域谓词组合起来（无标签监听器 ⇒ 放行；有标签监听器 ⇒ 仅当标签 === key 时放行；`key === undefined` ⇒ 仅放行无标签监听器）。载体只包含路由状态；真实主体由事件参数携带。带 `{ global: true }` 的监听器绕过筛选（Cordis 语义）。
 - `Scoped<T>`：编译期不透明载体 brand。按作用域筛选的事件要求它作为 `this` 类型，因此使用裸主体分发会产生编译错误。类型参数记录主体类型，但不公开其属性。
 - `isScopeCarrier(value)`/`carrierKeyOf(value)`：运行时载体标记，开发不变式使用它们断言每次按作用域筛选的分发都携带载体，而且载体键与参数所指名的主体一致。
-- `ScopeLayer`：一个注册表的完整全局贡献或精确作用域贡献的聚合契约；`isEmpty()` 控制带作用域层的回收。
+- `ScopeLayer`：一个注册表的完整全局贡献或精确作用域贡献的聚合约定；`isEmpty()` 控制带作用域层的回收。
 - `ScopedLayers<L>`：拥有一个立即创建的全局层和按需创建的精确作用域层。`peek()` 从不创建；`merge()` 物化按插入顺序排列的具名遮蔽项；`effect()` 从同一上下文推导可见性与所有权，同时返回原样 Cordis disposer。
 - `NamedEntries<V>`：按插入顺序排列的具名存储，调用方拥有重复项诊断、查找，以及一个非空表世代内的实时迭代。表清空后，现有迭代器与后续插入项脱离；`insert()` 返回幂等的精确条目撤销函数。
 - `AnonymousEntries<V>`：按插入顺序排列的匿名存储；唯一内部键使相同值仍作为独立注册存在。它使用相同的清空世代迭代器边界；`append()` 返回幂等的精确条目撤销函数。
 
 可选配套包 `@deepseek-ai/dsh-scope/invariant` 拥有该运行时断言。它使用生成的 `scoped-events.generated.ts` 解析器映射，要求每个已声明的带作用域事件都携带载体；当 payload 公开路由主体时，还要求路由主体与载体键严格相等。基于 Program 的生成器根据事件声明和真实的 `scopeTarget(base, key)` 调用生成该映射。
 
-## 设计契约
+## 设计约定
 
 注册上下文同时决定可见性和所有权，防止注册在一个作用域中可见、却随另一个作用域 dispose（资源释放）。作用域用于路由受信任的同进程插件；它们不是沙箱或权限边界。原理与明确排除的安全目标见 [agent 作用域 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals)。
 
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index e4caa9b815..5a70af1152 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/system-prompt/README.md
 README.md: e98c45a8829a945500ef5282d84e1904b31c68bf
-README.zh.md: 5a838f4ed3cb1f57ecd9f41325e1612afaf5103a
+README.zh.md: 9b390f664decade482ea0386e59623cf317a2093
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index 5a838f4ed3..9b390f664d 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -23,7 +23,7 @@
 
 ### 实时事件
 
-`system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。[system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) 的生成区块拥有签名与分发契约。
+`system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。[system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) 的生成区块拥有签名与分发约定。
 
 ### 关键类型
 
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index b257ecbfa6..daede94370 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/tools/README.md
 README.md: f3f25f908a4ba8016d38f7777fe72691dba4afb1
-README.zh.md: 675d9299037bc5225fcd117148c574eb646cf680
+README.zh.md: e636e1e8e7f4e3830d394224d704ee680eab198b
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 675d929903..e636e1e8e7 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -31,11 +31,11 @@ tools:
 
 ### 取消
 
-取消采用协作方式，并等待完全停稳。每次类型化调用都提供由调用方拥有的 `AbortSignal`；工具主体通过必填的只读 `exec.signal` 接收它，只有 `tools/execute` 包装层可以临时替换这个必填信号。注册表会在替换期间保留调用方取消，并且绝不会在已启动的同进程 Promise 尚未结算时提前返回。调用主体前发生的取消为 `ABORTED_BEFORE_DISPATCH`；调用后的取消只能把成功结果替换为 `ABORTED`。拒绝、包装层失败、工具失败、后置策略失败或由超时机制产生的 `TOOL_TIMEOUT` 仍保留更具体的结果。入口处已中止的调用会实体化并冻结参数，随后跳过所有策略和分发阶段，只发布一个结果。每个异步工具都必须观测或转发该信号，并且只能在自身拥有的工作停止后结算。[工具取消 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md) 规定完整契约和强制终止边界。
+取消采用协作方式，并等待完全停稳。每次类型化调用都提供由调用方拥有的 `AbortSignal`；工具主体通过必填的只读 `exec.signal` 接收它，只有 `tools/execute` 包装层可以临时替换这个必填信号。注册表会在替换期间保留调用方取消，并且绝不会在已启动的同进程 Promise 尚未结算时提前返回。调用主体前发生的取消为 `ABORTED_BEFORE_DISPATCH`；调用后的取消只能把成功结果替换为 `ABORTED`。拒绝、包装层失败、工具失败、后置策略失败或由超时机制产生的 `TOOL_TIMEOUT` 仍保留更具体的结果。入口处已中止的调用会实体化并冻结参数，随后跳过所有策略和分发阶段，只发布一个结果。每个异步工具都必须观测或转发该信号，并且只能在自身拥有的工作停止后结算。[工具取消 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md) 规定完整约定和强制终止边界。
 
 ### 实时事件
 
-实时注册表流水线先经过 3 个可变换的 waterfall，再经过由定义拥有的内容终结器，最后到达仅观测的 `tools/result` 边界；注册表变更有意作为不过滤的共享状态通知。确切签名、分发 mode、作用域筛选和故障收容契约位于 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块，完整顺序则在生成的[工具执行流水线](../../../docs/tool-execution-pipeline.md)中可视化。`tools/result` 是实时事件；名称相近的 `tool/result` 是 agent loop 随后追加的持久会话事件。
+实时注册表流水线先经过 3 个可变换的 waterfall，再经过由定义拥有的内容终结器，最后到达仅观测的 `tools/result` 边界；注册表变更有意作为不过滤的共享状态通知。确切签名、分发 mode、作用域筛选和故障收容约定位于 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块，完整顺序则在生成的[工具执行流水线](../../../docs/tool-execution-pipeline.md)中可视化。`tools/result` 是实时事件；名称相近的 `tool/result` 是 agent loop 随后追加的持久会话事件。
 
 ### 关键类型
 
@@ -97,7 +97,7 @@ ctx.tools.register(defineTool({
 
 可选的 `timeoutMs` 必须为正数且为有限值；它是策略元数据，不是模型可见的 schema。
 
-可选的 `isConcurrencySafe(args)` 接收经过软验证的类型化参数。只有确切的 `true` 才允许并发分发／主体执行；无效输入和所有其他结果仍为独占。选择并发的主体不得改变父级拥有的状态；共享状态竞态必须具有交换性，否则必须安全拒绝。[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md) 规定完整安全契约。
+可选的 `isConcurrencySafe(args)` 接收经过软验证的类型化参数。只有确切的 `true` 才允许并发分发／主体执行；无效输入和所有其他结果仍为独占。选择并发的主体不得改变父级拥有的状态；共享状态竞态必须具有交换性，否则必须安全拒绝。[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md) 规定完整安全约定。
 
 ### 强制执行的原始 JSON Schema 子集
 
@@ -114,10 +114,10 @@ ctx.tools.register(defineTool({
 
 ### Code Mode
 
-在 `code` 或 `both` 模式下，注册表为当前作用域公开保留的 `run_code` 传输和按所加载运行时语言生成的确定性 SDK——注册表按 `ctx.codeRuntime.language` 选择渲染器（`typescript` → 下方的 TypeScript SDK，`python` → Python SDK）。只有程序的外层日志与返回值会重新进入模型上下文。SDK 为每个可见工具声明精确的参数与规范输出类型（TypeScript 为 `ToolArgsMap`/`ToolOutputMap`，Python 为具名 `TypedDict`），每个绑定都会解析为该工具的规范 JSON 值。每个无损 JSON 绑定调用都会在原生调度约定下重新进入完整工具流水线（并发安全的调用最多可重叠 `maxParallelSubCalls` 个；独占调用单独运行并构成排序屏障），并在日志中与外层调用建立关联。拒绝及其他失败结果会以程序实际可见的 `ToolCallError` 形式拒绝，且只携带 `toolName` 和 `message`；Native 内容和内部错误码留在 Code 约定之外。普通副作用不会回滚，子调用的 `additionalContexts` 会通过父结果延迟，以保持调用／结果相邻。运行结算会中止并排空尚未完成的绑定；运行时失败以 `CodeRunFailedError` 形式出现。参见 [Code Mode 基础](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)、[类型化返回契约](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)和[代码运行时 seam](../../code-runtime/README.md)。可以运行 `pnpm run demo:code-mode` 试用。
+在 `code` 或 `both` 模式下，注册表为当前作用域公开保留的 `run_code` 传输和按所加载运行时语言生成的确定性 SDK——注册表按 `ctx.codeRuntime.language` 选择渲染器（`typescript` → 下方的 TypeScript SDK，`python` → Python SDK）。只有程序的外层日志与返回值会重新进入模型上下文。SDK 为每个可见工具声明精确的参数与规范输出类型（TypeScript 为 `ToolArgsMap`/`ToolOutputMap`，Python 为具名 `TypedDict`），每个绑定都会解析为该工具的规范 JSON 值。每个无损 JSON 绑定调用都会在原生调度约定下重新进入完整工具流水线（并发安全的调用最多可重叠 `maxParallelSubCalls` 个；独占调用单独运行并构成排序屏障），并在日志中与外层调用建立关联。拒绝及其他失败结果会以程序实际可见的 `ToolCallError` 形式拒绝，且只携带 `toolName` 和 `message`；Native 内容和内部错误码留在 Code 约定之外。普通副作用不会回滚，子调用的 `additionalContexts` 会通过父结果延迟，以保持调用／结果相邻。运行结算会中止并排空尚未完成的绑定；运行时失败以 `CodeRunFailedError` 形式出现。参见 [Code Mode 基础](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)、[类型化返回约定](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)和[代码运行时 seam](../../code-runtime/README.md)。可以运行 `pnpm run demo:code-mode` 试用。
 
 - **SDK 段**（`tools:sdk`，顺序 150）：一个惰性提示词段，每次组装时都会重新生成与所加载运行时语言相符的 SDK 文本。TypeScript 形态发出 `JsonValue`、精确的 `ToolArgsMap` / `ToolOutputMap`、`ToolName`、`ToolCallError` 声明、面向调用作用域可见最终能力的映射 `tools` 命名空间（特殊名称使用带引号的键），以及固定用法说明；Python 形态（`ctx.codeRuntime.language === 'python'`）发出等价的具名 `TypedDict` 与一个带相同用法说明的 `tools` 对象。其输出具有确定性：工具按字典序排列；工具集合不变时，文本逐字节相同（有利于前缀 cache）。两个代码生成器都已导出，且绝不会在提示词组装期间抛出：`jsonSchemaToTs` 处理统一 schema 的每种构造并将不受支持的原始构造降级为 `unknown`；`jsonSchemaToPy` 同理，降级为 `Any`（当某字段名不是合法的 `TypedDict` 属性时，或在 SDK 渲染之外被调用时——`TypedDict` 声明所需的命名上下文由该渲染提供——整个对象降级为 `dict[str, Any]`）。
-- **分发桥接层**（`run_code` 的 execute）：每个绑定调用都会在分发前快照为无损 JSON（`undefined`、`BigInt`、循环、稀疏数组、`-0` 和特殊对象会使该次调用被拒绝），经由每次运行独有、复用原生并发契约的池调度——调用严格按提交顺序启动，连续的 `isConcurrencySafe` 调用最多可重叠经校验的 `maxParallelSubCalls` 配置个（默认 10；设为 `1` 即恢复串行分发），被分类为独占的调用先排空池、单独运行并阻挡其后的调用——以外层执行的不透明 token 作为 `parent`，并经过完整的 pre-execute → guards → execute → post-execute → result 流水线。成功会返回策略处理后的最终规范值；失败以一条消息到达 worker，并成为 `ToolCallError(toolName, message)`。每个已启动的子调用在进入流水线时记录一条 `tool/code-dispatch-start` 事件（确定性 id `<parent>:code:<n>`，按提交顺序编号），并以一条携带完整模型可见 `content`/`isError` 结果的 `tool/code-dispatch` 事件完结（采用 `tool/result` 词汇，因此 UI 会沿原生路径呈现子调用——这对事件的 `time` 字段承载每个子调用的计时）；因 run 结算而被放弃的排队调用两者都不记录。`deriveMessages()` 既不公开这两个事件，也不持久化规范值。token 关联让以提交为语义的观察器能够把内部成功延迟到最终 `run_code` 结果，而无需公开实时外层执行；普通工具副作用不会回滚。每个子调用的 `additionalContexts` 条目都会按分发顺序通过外层 `ToolRunContext` 延迟；循环只在父级 `run_code` 结果之后追加这些上下文，从而保持相邻关系，并且即使程序后来失败，也会保留各自的来源／元数据。
+- **分发桥接层**（`run_code` 的 execute）：每个绑定调用都会在分发前快照为无损 JSON（`undefined`、`BigInt`、循环、稀疏数组、`-0` 和特殊对象会使该次调用被拒绝），经由每次运行独有、复用原生并发约定的池调度——调用严格按提交顺序启动，连续的 `isConcurrencySafe` 调用最多可重叠经校验的 `maxParallelSubCalls` 配置个（默认 10；设为 `1` 即恢复串行分发），被分类为独占的调用先排空池、单独运行并阻挡其后的调用——以外层执行的不透明 token 作为 `parent`，并经过完整的 pre-execute → guards → execute → post-execute → result 流水线。成功会返回策略处理后的最终规范值；失败以一条消息到达 worker，并成为 `ToolCallError(toolName, message)`。每个已启动的子调用在进入流水线时记录一条 `tool/code-dispatch-start` 事件（确定性 id `<parent>:code:<n>`，按提交顺序编号），并以一条携带完整模型可见 `content`/`isError` 结果的 `tool/code-dispatch` 事件完结（采用 `tool/result` 词汇，因此 UI 会沿原生路径呈现子调用——这对事件的 `time` 字段承载每个子调用的计时）；因 run 结算而被放弃的排队调用两者都不记录。`deriveMessages()` 既不公开这两个事件，也不持久化规范值。token 关联让以提交为语义的观察器能够把内部成功延迟到最终 `run_code` 结果，而无需公开实时外层执行；普通工具副作用不会回滚。每个子调用的 `additionalContexts` 条目都会按分发顺序通过外层 `ToolRunContext` 延迟；循环只在父级 `run_code` 结果之后追加这些上下文，从而保持相邻关系，并且即使程序后来失败，也会保留各自的来源／元数据。
 - **结算纪律**：桥接层拥有一个运行作用域的中止机制；该中止会跟随传入的外层信号，并在运行因任何原因结算时触发，因此预算耗尽会中止正在运行的子工具，而不会将其遗留。桥接层随后会在返回之前排空队列，使每个 `tool/code-dispatch` 都落在仍打开的轮次内。失败的运行会抛出 `CodeRunFailedError`（`code: 'CODE_RUN_FAILED'`，message = 失败类型 + 已捕获日志），流水线会将其转换为模型可据以自我修正的结构化 `isError`。
 - **结果边界**：中间绑定值会完整跨越 worker 边界，且没有逐绑定字节上限。`run_code` 返回规范的 `{ logs: string[], result?: JsonValue }`；字符串原样呈现，其他所有存在的 JSON 根都通过栈安全的美化 JSON 遍历呈现，总缩进最多为 10 个字符（更深的子树保持紧凑），`null` 保持显式，而缺少 `result` 表示程序返回 `undefined`。worker 可配置的 `maxOutputBytes`（默认 64 MiB）只应用于组合序列化后的外层日志数组、完成值或失败消息载荷；固定的结果 envelope 语法和呈现空白不计入该账本。无效和超限的完成会明确失败，只有此外层结果可以使用普通 spill。
 
diff --git a/packages/examples/jsonrpc-demo/README.i18n.yaml b/packages/examples/jsonrpc-demo/README.i18n.yaml
index 5660d73494..c47938ce3b 100644
--- a/packages/examples/jsonrpc-demo/README.i18n.yaml
+++ b/packages/examples/jsonrpc-demo/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/examples/jsonrpc-demo/README.md
 README.md: fff8e78698cd3d6320606084ef5c533be7c52633
-README.zh.md: 207717c27ac7a0f91eaf888d7aed4ded1adef67c
+README.zh.md: 75382b97ea1837cf1415e8a7f5004206596e168c
diff --git a/packages/examples/jsonrpc-demo/README.zh.md b/packages/examples/jsonrpc-demo/README.zh.md
index 207717c27a..75382b97ea 100644
--- a/packages/examples/jsonrpc-demo/README.zh.md
+++ b/packages/examples/jsonrpc-demo/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) 交付。
+只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)交付。
 
 ## 配置发现
 
diff --git a/packages/feedback/command-feedback/README.i18n.yaml b/packages/feedback/command-feedback/README.i18n.yaml
index 20eb2741d6..bc4a93d760 100644
--- a/packages/feedback/command-feedback/README.i18n.yaml
+++ b/packages/feedback/command-feedback/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/feedback/command-feedback/README.md
 README.md: e2eb6d4cf2b40e83efad1fa158edd72578658f56
-README.zh.md: f87067d67cf9dcb8f4da97afe3a9d59eb828faf7
+README.zh.md: c3b7b59d90d924de6042aeac1e7eec39457c6c83
diff --git a/packages/feedback/command-feedback/README.zh.md b/packages/feedback/command-feedback/README.zh.md
index f87067d67c..c3b7b59d90 100644
--- a/packages/feedback/command-feedback/README.zh.md
+++ b/packages/feedback/command-feedback/README.zh.md
@@ -4,7 +4,7 @@
 
 与触发方式无关的会话反馈，以及面向用户的 `/feedback` 采集。本包导出 `recordFeedback(session, text)`，后者追加一个仅写入日志的 `feedback/record` 事件。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现它；随附的 Web 客户端无需模型轮次即可执行。
 
-## 命令契约
+## 命令约定
 
 | 输入 | 结果 |
 |---|---|
@@ -15,7 +15,7 @@
 
 ## 本插件做什么、不做什么
 
-`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集契约。
+`recordFeedback(session, text)` 是不依赖命令的写入路径。它拒绝规范化后为空的文本，并追加 `feedback/record { text }`；其他 UI、钩子或 host 集成无需构造斜杠命令即可调用它。`/feedback` 处理器通过该生产方写入，且不启动任何模型工作。可选的 [`dsh-session-telemetry-otel`](../../session/session-telemetry-otel) 消费方会观察该事件，但不改变它的采集约定。
 
 反馈文本只出现在一个持久载荷中：`feedback/record`。[`dsh-commands`](../../interaction/commands/README.md) 仍会追加通用的 `command/run` / `command/done` 配对，但此定义设置了 `recordInput: false`，因此 `command/run` 会省略 `args`；配对的 `command/done` 只携带结果。三个事件都仅写入日志，不出现在有序 surface、`deriveMessages()` 以及模型请求中。这些追加会启动持久化的常规即时排空，但两个生产方都不会强制 `session/flush`，因此确认文本表示反馈已进入日志，而不表示它已经落盘。被拒绝的空输入只会留下以 `kind: 'error'` 结算的命令配对，不会产生 `feedback/record`。
 
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index 8141819240..e0095d9858 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/fs/README.md
 README.md: 5c58fc476b9b11a83bbe0d6c33ac782d94d6ffbc
-README.zh.md: 32faf67d6ed97914704ea5683f1fd987e2e64a93
+README.zh.md: 8eb2634df2754cdcada4e48046e19eb32b1cf3af
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 32faf67d6e..8eb2634df2 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -41,13 +41,13 @@
 
 ## 提供方 seam，不是策略层
 
-`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
+`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察策略。
 
 `editText` 留在该 seam 上，不由策略层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
 
 ## 词汇
 
-`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整契约见 `src/types.ts`。
+`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整约定见 `src/types.ts`。
 
 ## 模型体验
 
diff --git a/packages/fs/tool-fs-search/README.i18n.yaml b/packages/fs/tool-fs-search/README.i18n.yaml
index fbe6453292..a8fe6a80d7 100644
--- a/packages/fs/tool-fs-search/README.i18n.yaml
+++ b/packages/fs/tool-fs-search/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/tool-fs-search/README.md
 README.md: 32fa61e3bb09b2166499003953a5631a93baf73b
-README.zh.md: bf2eac320bf3dc0811ec8e3747487b4f3ce634b7
+README.zh.md: 34ffcdc9f64daba7350e4581b35e694213f24214
diff --git a/packages/fs/tool-fs-search/README.zh.md b/packages/fs/tool-fs-search/README.zh.md
index bf2eac320b..34ffcdc9f6 100644
--- a/packages/fs/tool-fs-search/README.zh.md
+++ b/packages/fs/tool-fs-search/README.zh.md
@@ -16,11 +16,11 @@ await ctx.plugin(LocalSpillStore)                           // @deepseek-ai/dsh-
 
 ## 部署要求：无需宿主 rg，但工作目录与文件系统需共置
 
-二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。v1 只记录这项共置要求，不执行运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区契约或特定提供方的搜索后端。
+二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。v1 只记录这项共置要求，不执行运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区约定或特定提供方的搜索后端。
 
 ## 配置
 
-`sampleOverCapGlobResults` 是必填项且没有回退值；部署必须显式选择超过上限时的排序契约。其余配置键是可选的搜索上限，默认值如下。
+`sampleOverCapGlobResults` 是必填项且没有回退值；部署必须显式选择超过上限时的排序约定。其余配置键是可选的搜索上限，默认值如下。
 
 | 配置键 | 默认值 | 含义 |
 |---|---|---|
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index e9000e3500..32b85a4257 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/tool-fs/README.md
 README.md: 28880860dc6c89745eb21fbf732d04f596f9b07f
-README.zh.md: 8af0aec51e71681211bbd5a4f582be8b8b0271b8
+README.zh.md: b85fc7d90aaaf0d7e137bf8646bc023d6ca1e60f
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index 8af0aec51e..b85fc7d90a 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -50,11 +50,11 @@ await ctx.plugin(ToolFs)                                  // this package — re
 
 ## `fs/observed` 发后即忘
 
-`fs/observed` 在读取/写入/编辑已经成功之后，通过普通 `ctx.emit` 发出。监听器的契约是同步且只有副作用的记录器（`@deepseek-ai/dsh-fs-policy` 使用 `WeakMap.set`）；工具不保护这次发出，因此监听器抛出会作为工具的 `isError` 结果出现。异步或可能失败的观察不属于该事件。
+`fs/observed` 在读取/写入/编辑已经成功之后，通过普通 `ctx.emit` 发出。监听器的约定是同步且只有副作用的记录器（`@deepseek-ai/dsh-fs-policy` 使用 `WeakMap.set`）；工具不保护这次发出，因此监听器抛出会作为工具的 `isError` 结果出现。异步或可能失败的观察不属于该事件。
 
 `read` 允许并发调度，因为其唯一变更是同步版本记录器。稍后的 `write` 或 `edit` 会在目标锁内重新检查版本，因此记录器竞态会以拒绝方式关闭；两个变更工具仍保持互斥。见[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。
 
-包根目录只导出 Cordis 插件契约（`name`、`inject`、`Config` 和 `apply`）。读取渲染（行窗口与输出格式化）位于 `src/read-render.ts`（不依赖 Cordis，单独进行单元测试）；`src/read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。
+包根目录只导出 Cordis 插件约定（`name`、`inject`、`Config` 和 `apply`）。读取渲染（行窗口与输出格式化）位于 `src/read-render.ts`（不依赖 Cordis，单独进行单元测试）；`src/read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。
 
 ## 模型体验
 
diff --git a/packages/goal/command-goal/README.i18n.yaml b/packages/goal/command-goal/README.i18n.yaml
index 90285c2860..5953c9c6a0 100644
--- a/packages/goal/command-goal/README.i18n.yaml
+++ b/packages/goal/command-goal/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/command-goal/README.md
 README.md: 1ac1b8a0e2cb360708b1759ab5eb9ec3de597821
-README.zh.md: 82750a102784fad7da1038a97478880f60001bdf
+README.zh.md: ee40cd4219c45b6d9650036fda21c56599be6abd
diff --git a/packages/goal/command-goal/README.zh.md b/packages/goal/command-goal/README.zh.md
index 82750a1027..ee40cd4219 100644
--- a/packages/goal/command-goal/README.zh.md
+++ b/packages/goal/command-goal/README.zh.md
@@ -4,7 +4,7 @@
 
 面向用户的 `/goal` 控制，基于 [`ctx.goals`](../goal/README.md) 实现。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。[用户 goal 命令 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-human-goal-command.md) 负责用户体验与组合决策。
 
-## 命令契约
+## 命令约定
 
 | 输入 | 结果 |
 |---|---|
diff --git a/packages/goal/goal-session/README.i18n.yaml b/packages/goal/goal-session/README.i18n.yaml
index 686f8aaa3f..226316dbd7 100644
--- a/packages/goal/goal-session/README.i18n.yaml
+++ b/packages/goal/goal-session/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/goal-session/README.md
 README.md: 89413062de8cbb49d7066ec3ae42769a99c939a2
-README.zh.md: 075592e4e77e3336c1e2c08769ee255569e53360
+README.zh.md: a39a45232e7a2376154bc35182e77cc3b9ba1569
diff --git a/packages/goal/goal-session/README.zh.md b/packages/goal/goal-session/README.zh.md
index 075592e4e7..a39a45232e 100644
--- a/packages/goal/goal-session/README.zh.md
+++ b/packages/goal/goal-session/README.zh.md
@@ -19,7 +19,7 @@
 
 该插件没有可调配置。`maxGoalRounds` 属于目标定义，面向模型的阻塞阈值则属于 [`dsh-tool-goal`](../tool-goal/README.md)；在驱动器中重复任一数值都可能产生分歧策略。
 
-## Round 契约
+## Round 约定
 
 当对应的活跃 agent 实例处于 idle 状态，且目标 phase 为 active、已启用续行并有剩余容量时，驱动器先为待处理 goal 变更创建检查点，再预留 `roundsStarted + 1`，对应当前 `{ goalId, revision }`。它会排入一条 `<goal_round>` 提示词，并携带 `GoalMessageSource`。`agent/pre-step` 监听器会在下游监听器前后验证完整的已领取记录与当前 goal；只有进入步骤的 `user/message` 才会增加 `roundsStarted`。因陈旧而被拒绝的预留不会消耗 Round 编号。
 
diff --git a/packages/goal/goal/README.i18n.yaml b/packages/goal/goal/README.i18n.yaml
index 5593953d89..3fee674e71 100644
--- a/packages/goal/goal/README.i18n.yaml
+++ b/packages/goal/goal/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/goal/goal/README.md
 README.md: 98765a809820bcd4aeba31e1dd4ef6e92eb30760
-README.zh.md: 7f59fc4b538ad68bfcf0686b7651d0ec64470c2e
+README.zh.md: d133cb154523dcf47b8a033cc60411ac6f6e9c9e
diff --git a/packages/goal/goal/README.zh.md b/packages/goal/goal/README.zh.md
index 7f59fc4b53..d133cb1545 100644
--- a/packages/goal/goal/README.zh.md
+++ b/packages/goal/goal/README.zh.md
@@ -15,9 +15,9 @@
 
 `defaultMaxGoalRounds` 必须是正的安全整数。`create()` 会在提交目标前于内部物化这项部署默认值；请求级取值可以覆盖它。
 
-## 服务契约
+## 服务约定
 
-`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回与内部状态脱离的 `GoalView`；变更以 `GoalRef { id, revision }` 作为比较并设置防护，并拒绝陈旧引用。服务通过 [goal.md](../../../docs/subsystems/goal.md#cordis-surface) 的生成区块公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发出变更。
+`ctx.goals` 只接受以对应 id 注册的完全相同的活跃 `Agent` 实例。`get()` 返回与内部状态脱离的 `GoalView`；变更以 `GoalRef { id, revision }` 作为比较并设置防护，并拒绝陈旧引用。服务通过 [goal.md](../../../docs/subsystems/goal.md#cordis-surface) 的生成区块公开 create、edit、pause、resume、complete、block 和 clear 动词。创建默认值在内部解析。`disarm()` 是仅供生命周期使用的例外：它移除进程本地续行权限，不写入新 revision，也不发出变更事件。
 
 最多只有一个当前目标。创建操作会生成 revision 为 1、phase 为 active 的目标并启用续行。未完成的目标必须编辑、转换或清除；已完成目标可以由拥有全局未使用过的 id 的目标替换。编辑会保留 phase、blocker reason 与 activation。暂停、完成、阻塞和清除都会停用续行。阻塞会记录策略自有的 lower-kebab-case 代码和规范化的自由文本说明；提供方限制、配置预算、执行错误与请求人工输入都使用这一种持久 phase，不会扩增生命周期状态。只有配置的 Round 上限仍有剩余容量时，resume 才接受已停止 phase 或 phase 为 active 但已停用续行的目标；它会清除原 blocker reason。phase 为 active 且已启用续行的目标会拒绝冗余操作。
 
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index ae64984c31..f082be00ef 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/hooks/hook-protocol/README.md
 README.md: e807d9597eb5f811195bab9a0ad2b30b545e1205
-README.zh.md: b77c8d658eddf7ce60faaf171e6f41e09b8ef333
+README.zh.md: c206224b45a5b12a7aa85d24de301f3d949f294b
diff --git a/packages/hooks/hook-protocol/README.zh.md b/packages/hooks/hook-protocol/README.zh.md
index b77c8d658e..c206224b45 100644
--- a/packages/hooks/hook-protocol/README.zh.md
+++ b/packages/hooks/hook-protocol/README.zh.md
@@ -4,7 +4,7 @@
 
 Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它不是 Cordis 插件：不注册也不注入任何内容。它是一个**库**，提供两个桥接插件（`@deepseek-ai/dsh-hooks-claude`、`@deepseek-ai/dsh-hooks-codex`）导入的方言无关原语，使两者都无需重复实现协议中相同的部分。
 
-共享 lib 存在的原因是：Codex 有意重新实现了 Claude Code hook 协议的一个*子集*，包括相同的 `hooks.json` matcher group 结构、相同的退出码／stdout 输出契约以及相同的 command hook 执行模式。真正共享的部分位于此处；每个桥接只负责不同的部分。
+共享 lib 存在的原因是：Codex 有意重新实现了 Claude Code hook 协议的一个*子集*，包括相同的 `hooks.json` matcher group 结构、相同的退出码／stdout 输出约定以及相同的 command hook 执行模式。真正共享的部分位于此处；每个桥接只负责不同的部分。
 
 ## 共享内容（此处）与各方言内容（桥接）
 
@@ -41,4 +41,4 @@ Hook 溯源记录必须位于一个尚未结束的轮次内。`UserPromptSubmit`
 
 ## 已知限制与暂缓事项
 
-- **`HookOutput.updatedInput` 会被解析但不会应用**：输入改写是已暂缓的一致性设计问题（见 [pre-tool-input-rewrite Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md)）；当 hook 设置它时，桥接会记录 + 警告。完整契约见 `src/types.ts`。
+- **`HookOutput.updatedInput` 会被解析但不会应用**：输入改写是已暂缓的一致性设计问题（见 [pre-tool-input-rewrite Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md)）；当 hook 设置它时，桥接会记录 + 警告。完整约定见 `src/types.ts`。
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 1f02adea1d..bc7869b361 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
 README.md: a3c9f214690144ec0f39a8690e4fd346f5e315e2
-README.zh.md: 4de15316fe31d75361fd3b8655c7c1f7d5fa4a02
+README.zh.md: 65475351e279f258f4417f2082673382e76a5be3
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index 4de15316fe..65475351e2 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -16,7 +16,7 @@
 
 存下来的路由不做注册表校验，两个方向都不做。默认值指向一个已在模型页删除的路由时，它照样作为会话的 `current` 送到 `session.models`——匹配不到任何已公布的分组，而这恰恰是让选择器提示重新选择、而不是显示一个部署根本够不着的模型的原因。静默修复它还会破坏刻意保留的反面情形：适配器可以服务一个自己目录未公布的模型。
 
-## 契约层（`/api`）
+## 约定层（`/api`）
 
 协议消息组成一个四象限可辨识联合：发起方 × 请求／响应，与物理通道解耦。四种消息分别是 `ClientRequest`（POST `/api/<method>` 的请求体）、`ServerResponse`（该 POST 的响应体）、`ServerRequest`（SSE 帧）和 `ClientResponse`（POST `/api/respond` 的请求体）。响应始终回显对应请求的 `rpcId`，绝不签发新值。方法的参数与返回值结构只存在于领域接口签名（`SessionsApi`、`HostApi`、`EventsApi`）中；`RpcMethodMap` 注册方法，其他所有位置均通过 `RequestPayload<K>`／`ResponseValue<K>` 派生。Zod schema 以 `satisfies z.ZodType<Wire<T>>` 锚定类型，并分两层解析：先解析信封，再解析业务载荷，随后按方法分发。业务错误由 `RpcResult` 的错误分支承载（`RpcErrorDetailsMap` 封闭错误码集合）；HTTP 状态只表达载体层结果。每个 `/api` POST 都必须声明 `application/json` 媒体类型——否则在分发前即以 415 拒绝，因此跨站「简单请求」（浏览器不经 CORS 预检就会发出）永远无法盲目执行有副作用的方法。
 
@@ -56,7 +56,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 ## 模型体验
 
-无。该包定义客户端与宿主间的协议契约和载体，其中没有任何内容会进入模型请求。
+无。该包定义客户端与宿主间的协议约定和载体，其中没有任何内容会进入模型请求。
 
 #### KV Cache 影响
 
diff --git a/packages/host/directory-picker/README.i18n.yaml b/packages/host/directory-picker/README.i18n.yaml
index a37ed552a4..aeb36e44d7 100644
--- a/packages/host/directory-picker/README.i18n.yaml
+++ b/packages/host/directory-picker/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/directory-picker/README.md
 README.md: 3749b238b56578ec68610bc13550760aa084bad6
-README.zh.md: 4f7c20e25a4e64f63c611fc56eeec3f249ad67e3
+README.zh.md: bc77a9c6e1d76e00926774dc518fce42b2860735
diff --git a/packages/host/directory-picker/README.zh.md b/packages/host/directory-picker/README.zh.md
index 4f7c20e25a..bc77a9c6e1 100644
--- a/packages/host/directory-picker/README.zh.md
+++ b/packages/host/directory-picker/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-web GUI 宿主的**工作区目录选择 seam**：抽象服务 `DirectoryPicker`（`ctx.directoryPicker`），唯一契约方法 `capability()` 返回一个可辨识能力对象，描述操作者以何种方式选择目录。后端之间的差异在交互形态而不只是机制，因此 seam 显式建模形态而非统一方法集：`{ kind: 'native', pick(signal) }` 在宿主屏幕上打开一个原生 OS 选择器（[`-native`](../directory-picker-native/README.md)）；`{ kind: 'browse', list(path?), createDirectory(path, name) }` 提供应用内浏览器驱动的列举／创建原语，也能服务于 OS 对话框无法触及的远程客户端（[`-browse`](../directory-picker-browse/README.md)）。消费方按 `capability().kind` 分支；联合类型由可合并扩展的 `DirectoryPickerCapabilities` 映射派生（新后端通过声明合并加入自己的形态），未知 kind 的文档化默认行为是隐藏选择入口而非失败。能力对象在服务生命周期内必须保持稳定。client 侧以镜像方式承接该 seam，无需通过 wire 公布能力：每个后端包都是双面包，其 browser half 把匹配的选取交互注册进 ui-workspace 的目录流 slot——因此一项组合配置会同时切换宿主能力与 client 流程。不应固定某种交互的组合改为挂载 [`-auto`](../directory-picker-auto/README.md) 选择器，它在启动时一次性判定宿主处境，并自行挂载匹配的后端行。
+web GUI 宿主的**工作区目录选择 seam**：抽象服务 `DirectoryPicker`（`ctx.directoryPicker`），唯一约定方法 `capability()` 返回一个可辨识能力对象，描述操作者以何种方式选择目录。后端之间的差异在交互形态而不只是机制，因此 seam 显式建模形态而非统一方法集：`{ kind: 'native', pick(signal) }` 在宿主屏幕上打开一个原生 OS 选择器（[`-native`](../directory-picker-native/README.md)）；`{ kind: 'browse', list(path?), createDirectory(path, name) }` 提供应用内浏览器驱动的列举／创建原语，也能服务于 OS 对话框无法触及的远程客户端（[`-browse`](../directory-picker-browse/README.md)）。消费方按 `capability().kind` 分支；联合类型由可合并扩展的 `DirectoryPickerCapabilities` 映射派生（新后端通过声明合并加入自己的形态），未知 kind 的文档化默认行为是隐藏选择入口而非失败。能力对象在服务生命周期内必须保持稳定。client 侧以镜像方式承接该 seam，无需通过 wire 公布能力：每个后端包都是双面包，其 browser half 把匹配的选取交互注册进 ui-workspace 的目录流 slot——因此一项组合配置会同时切换宿主能力与 client 流程。不应固定某种交互的组合改为挂载 [`-auto`](../directory-picker-auto/README.md) 选择器，它在启动时一次性判定宿主处境，并自行挂载匹配的后端行。
 
 浏览原语失败时会抛出带类型的 `DirectoryPickerError`（`directory-unreadable`／`directory-exists`／`directory-create-failed`，各自携带出错对象的 `path`），消费网关将其 1:1 映射为协议错误码。`DirectoryEntry` 行携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示策略留在客户端；`DirectoryListing.crumbs` 是从文件系统根开始的祖先链，每个 crumb 都是跳转目标。设计依据、与 `ctx.fs` 的切分、策略裁决见[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。
 
@@ -16,4 +16,4 @@ web GUI 宿主的**工作区目录选择 seam**：抽象服务 `DirectoryPicker`
 
 ## 已知限制与暂缓事项
 
-- **契约未定义多根目录词汇**——浏览契约每次列举只暴露一条祖先链；按部署限定可浏览根（以及 Windows 盘符之上的根枚举）等到出现需要它的消费方再做，见 seam Agent Note。
+- **约定未定义多根目录词汇**——浏览约定每次列举只暴露一条祖先链；按部署限定可浏览根（以及 Windows 盘符之上的根枚举）等到出现需要它的消费方再做，见 seam Agent Note。
diff --git a/packages/host/webserver/README.i18n.yaml b/packages/host/webserver/README.i18n.yaml
index bd80f27f3e..a9e5d9e48a 100644
--- a/packages/host/webserver/README.i18n.yaml
+++ b/packages/host/webserver/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/webserver/README.md
 README.md: 569c3f0c19db2c308beaef35baaf915fd39768cd
-README.zh.md: b311ebffa3fb067e684e9e443c2ac02dab917d61
+README.zh.md: 3aee06487743764bf2cb837360bb1ac9f0268508
diff --git a/packages/host/webserver/README.zh.md b/packages/host/webserver/README.zh.md
index b311ebffa3..3aee064877 100644
--- a/packages/host/webserver/README.zh.md
+++ b/packages/host/webserver/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Web HTTP 与 upgrade route 注册插件（默认导出 `HttpServerService`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层契约，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 认领唯一的回退席位，应答所有未被具名 route 命中的请求：只允许一个持有者（第二次认领会抛错；随附的持有者是 SPA dist 服务器 [`dsh-frontend-static`](../frontend-static/README.md)），席位未被认领时返回 404。`tapIndex(transform)` 添加一个 index.html 转换，`applyIndexTaps(html)` 按注册顺序对一段响应体运行已注册的转换：fallback 持有者在每次 index 响应时调用它。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给回退席位。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不承载任何面向请求的语义。
+Web HTTP 与 upgrade route 注册插件（默认导出 `HttpServerService`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.httpServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层约定，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 认领唯一的回退席位，应答所有未被具名 route 命中的请求：只允许一个持有者（第二次认领会抛错；随附的持有者是 SPA dist 服务器 [`dsh-frontend-static`](../frontend-static/README.md)），席位未被认领时返回 404。`tapIndex(transform)` 添加一个 index.html 转换，`applyIndexTaps(html)` 按注册顺序对一段响应体运行已注册的转换：fallback 持有者在每次 index 响应时调用它。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给回退席位。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不承载任何面向请求的语义。
 
 该包不了解任何 harness 概念，也不提供任何文件服务：`/api` HTTP 桥接与下行 WebSocket 是 connection 插件的 route，插件 bundle 与 HMR（热模块替换）事件流是 modules／hmr 插件的 route，dist 服务则属于 fallback 持有者。upgrade handler 拥有协议握手与连接内容；webserver 只交付原始 socket 与 request。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）。该服务器只服务 Web（浏览器）形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。
 
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
index f2321e732a..5c99feeaf3 100644
--- a/packages/interaction/README.i18n.yaml
+++ b/packages/interaction/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/interaction/README.md
 README.md: a72cd48bb1d3ec15b1116d576fac86619df59528
-README.zh.md: 170a557e40befaa0f7073f25e8a2b372958a6ec1
+README.zh.md: 03fab9c4ce4479b3ab82f372f14f4d4208d7de04
diff --git a/packages/interaction/README.zh.md b/packages/interaction/README.zh.md
index 170a557e40..03fab9c4ce 100644
--- a/packages/interaction/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -12,6 +12,6 @@
 | [`user-interaction/`](user-interaction/README.md) | 定义与提供方无关的用户问答 seam。 | `ctx.userInteraction` |
 | [`tool-ask-user/`](tool-ask-user/README.md) | 向模型公开用户问题。 | （注册到 `ctx.tools`） |
 
-这些包通过现有的 agent（智能体）和会话契约集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
+这些包通过现有的 agent（智能体）和会话约定集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
 
 子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)与 [commands.md](../../docs/subsystems/commands.md)。仅自动化的 ACP 传输在 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半在 [`scaffold/server`](../scaffold/README.md)，共享 bin 启动胶水在 [`boot/`](../boot/README.md)。
diff --git a/packages/interaction/commands/README.i18n.yaml b/packages/interaction/commands/README.i18n.yaml
index 967fa0d4ef..f79052085f 100644
--- a/packages/interaction/commands/README.i18n.yaml
+++ b/packages/interaction/commands/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/interaction/commands/README.md
 README.md: 1709bdcdce4e43d98cfea5ff3972ab95bfd3c33b
-README.zh.md: 569f2aa8293793b26d63ee16e3ea7600e04a8397
+README.zh.md: 0f3ce975a015a555e6ad88a5fc872dc0e9e95fa1
diff --git a/packages/interaction/commands/README.zh.md b/packages/interaction/commands/README.zh.md
index 569f2aa829..0f3ce975a0 100644
--- a/packages/interaction/commands/README.zh.md
+++ b/packages/interaction/commands/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-由插件负责、供交互式 UI 适配器使用的面向用户命令注册表。[插件命令注册 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md)定义了其边界与分发契约。
+由插件负责、供交互式 UI 适配器使用的面向用户命令注册表。[插件命令注册 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md)定义了其边界与分发约定。
 
-## 服务契约
+## 服务约定
 
 `ctx.commands.register(definition)` 注册一个小写命令名称、描述、可选的非结构化输入提示、可选的 `recordInput` 策略，以及可中止的处理器。`recordInput` 默认为 true；若载荷由命令的权威领域事件持有，该命令会将 `recordInput` 设为 false，让 `command/run` 省略 `args`，避免重复记录输入。每个已注册命令都可供所有已组合的命令适配器使用；与某项部署不兼容的插件不会在此注册。普通上下文中的注册全局生效。在 `agent.ctx` 下挂载的命令生产插件会声明自身的 `commands` 注入，并创建精确限定到该 agent（智能体）的定义；该定义会遮蔽同名的全局定义。这种子级注入形态保留了 agent 作用域，同时不会让核心 agent loop（智能体循环）依赖 UI 服务。同一层中的名称重复会在注册时失败。每个 disposer 都是 Cordis effect 返回的确切 disposer；注册或移除命令时，系统会通知每个 `commands/change` 观察者，使运行中的适配器能够刷新发现结果。观察者失败会写入日志，既不能否决注册表变更，也不能阻止后续观察者运行。
 
@@ -12,7 +12,7 @@
 
 `parseCommand()` 识别位于第 0 字节的斜杠、由小写字母、数字、`_` 或 `-` 构成的名称，以及名称后紧接输入末尾或空白的形式。它将名称后的每个字节作为 `rawInput` 返回，其中包括分隔空白；消费方负责各命令专用的语法，只能执行该语法允许的规范化。
 
-处理器返回 `success` 或 `error`，并可附带 UI 文本。若更丰富的呈现由一条更早的领域事件持有，成功的处理器还可返回 `sourceEventSeq`；生命周期不变量要求该引用指向同一会话中更早的一条非命令事件。适配器直接渲染结果，结果绝不进入模型历史。注册表绝不会隐式地把 `rawInput` 提交给 agent；命令生产方可以通过接收命令的 `Agent` 显式安排模型可见工作，此时该生产方负责由此产生的消息契约。注册表会同时等待处理器完成和所提供的中止信号，以先发生者为准，但不响应中止的处理器可能在调用方停止等待后继续产生自身的外部副作用。
+处理器返回 `success` 或 `error`，并可附带 UI 文本。若更丰富的呈现由一条更早的领域事件持有，成功的处理器还可返回 `sourceEventSeq`；生命周期不变量要求该引用指向同一会话中更早的一条非命令事件。适配器直接渲染结果，结果绝不进入模型历史。注册表绝不会隐式地把 `rawInput` 提交给 agent；命令生产方可以通过接收命令的 `Agent` 显式安排模型可见工作，此时该生产方负责由此产生的消息约定。注册表会同时等待处理器完成和所提供的中止信号，以先发生者为准，但不响应中止的处理器可能在调用方停止等待后继续产生自身的外部副作用。
 
 ## 组合
 
diff --git a/packages/llm/llm-deepseek/README.i18n.yaml b/packages/llm/llm-deepseek/README.i18n.yaml
index 470dc19e92..e784f2c28b 100644
--- a/packages/llm/llm-deepseek/README.i18n.yaml
+++ b/packages/llm/llm-deepseek/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/llm-deepseek/README.md
 README.md: 6ad674ebdf8da4fd927a9499e80e06462d3c0dfb
-README.zh.md: 02a192e38aa19b24a34e83b3ddb77d786bbace0b
+README.zh.md: ca51a6f56ab2fa3bf47ca4f400a1474440bb39a4
diff --git a/packages/llm/llm-deepseek/README.zh.md b/packages/llm/llm-deepseek/README.zh.md
index 02a192e38a..ca51a6f56a 100644
--- a/packages/llm/llm-deepseek/README.zh.md
+++ b/packages/llm/llm-deepseek/README.zh.md
@@ -6,7 +6,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
 
 同一 seam 的第二个基于库的实现位于 `@deepseek-ai/dsh-llm-pi-ai`。本包拥有 `deepseek-official` 提供方路由——刻意区别于 pi-ai 的 catalog 名称 `deepseek`，因此同一组合可以并排挂载两条 DeepSeek 路径；而为 `deepseek-official` 本身注册另一个适配器仍会抛出 `LlmError('DUPLICATE_ADAPTER')`。
 
-包根入口导出 Cordis 插件契约与 `DeepSeekAdapter`；协议序列化、SSE 解析与分片转换 helper 不属于该根契约。
+包根入口导出 Cordis 插件约定与 `DeepSeekAdapter`；协议序列化、SSE 解析与分片转换 helper 不属于该根约定。
 
 ## 配置
 
@@ -60,7 +60,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
 
 ## 应用归因
 
-每个请求都携带 dsh-llm `attributionHeaders()` 的共享归因标头，即用于识别 harness 的必需 `User-Agent` 基线（见 [dsh-llm § 应用归因](../llm/README.md#app-attribution-attributionts)）。在该适配器契约（adapter contract）下，直接 DeepSeek 请求与 OpenAI 兼容 gateway 请求都不会获得提供方特定应用归因标头；OpenRouter 应用归因暂缓到未来的显式 OpenRouter 适配器或模式。`GenerateOptions.purpose` 为 `compaction` 的请求（dsh-compact-basic 的辅助摘要调用）还会携带 `x-deepseek-harness-compact: 1`，让宿主可以将压缩流量与会话请求分开。
+每个请求都携带 dsh-llm `attributionHeaders()` 的共享归因标头，即用于识别 harness 的必需 `User-Agent` 基线（见 [dsh-llm § 应用归因](../llm/README.md#app-attribution-attributionts)）。在该适配器约定（adapter contract）下，直接 DeepSeek 请求与 OpenAI 兼容 gateway 请求都不会获得提供方特定应用归因标头；OpenRouter 应用归因暂缓到未来的显式 OpenRouter 适配器或模式。`GenerateOptions.purpose` 为 `compaction` 的请求（dsh-compact-basic 的辅助摘要调用）还会携带 `x-deepseek-harness-compact: 1`，让宿主可以将压缩流量与会话请求分开。
 
 ## 协议格式说明
 
diff --git a/packages/llm/token-meter/README.i18n.yaml b/packages/llm/token-meter/README.i18n.yaml
index a174ba4233..5b2d79f7fb 100644
--- a/packages/llm/token-meter/README.i18n.yaml
+++ b/packages/llm/token-meter/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/token-meter/README.md
 README.md: 8f868f25f3c4caf1fdab5b50965aab41efecf5af
-README.zh.md: 8bdf86517abaff79b78346549ff79b2fff93486a
+README.zh.md: e3908ecea17b16669458f89a6359a432f5b24c0c
diff --git a/packages/llm/token-meter/README.zh.md b/packages/llm/token-meter/README.zh.md
index 8bdf86517a..e3908ecea1 100644
--- a/packages/llm/token-meter/README.zh.md
+++ b/packages/llm/token-meter/README.zh.md
@@ -8,7 +8,7 @@
 
 估算器没有配置项。它有意使用一项固定启发式规则：每个 token 按四个字符估算，再加上角色、块与请求 envelope 字段的结构开销。任何配置键都会被拒绝，包括已废弃的全局 `contextWindow`；模型容量属于拥有精确提供方／模型路由的适配器，可通过 `ctx.llm.resolveModelInfo().context` 获取。
 
-## 测量契约
+## 测量约定
 
 `ctx.tokenMeter` 直接公开两个操作：
 
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index 02649a8d39..cceabd1036 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/lsp/lsp/README.md
 README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
-README.zh.md: cc412333e63b9469319240d67269bf0192ad3858
+README.zh.md: a35f870603718ee6b7bcbfdf65f5d689d800447b
diff --git a/packages/lsp/lsp/README.zh.md b/packages/lsp/lsp/README.zh.md
index cc412333e6..a35f870603 100644
--- a/packages/lsp/lsp/README.zh.md
+++ b/packages/lsp/lsp/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**LSP 能力 seam**：抽象 `LspService`（`ctx.lsp`）定义 harness 具备哪些语义代码导航能力（转到定义、查找引用、查找实现、悬停），并通过语言服务器提供方实现，不把模型契约绑定到本地子进程。
+**LSP 能力 seam**：抽象 `LspService`（`ctx.lsp`）定义 harness 具备哪些语义代码导航能力（转到定义、查找引用、查找实现、悬停），并通过语言服务器提供方实现，不把模型约定绑定到本地子进程。
 
 该包是 LSP 能力中负责接口的三分之一：
 
@@ -27,7 +27,7 @@
 
 ## 词汇
 
-`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具拥有从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceUri }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceUri` 是提供方的规范工作区 `file:` URI；调用方相对化位置 URI 时以它为基准，而不是对可能含符号链接的请求根应用宿主平台路径规则。完整契约见 `src/types.ts`；`src/index.ts` 给出 `LspError` code，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
+`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具拥有从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceUri }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceUri` 是提供方的规范工作区 `file:` URI；调用方相对化位置 URI 时以它为基准，而不是对可能含符号链接的请求根应用宿主平台路径规则。完整约定见 `src/types.ts`；`src/index.ts` 给出 `LspError` code，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
 
 ## 模型体验
 
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index ff00f20c67..6a3948bc19 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-client/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/mcp/mcp-client/README.md
 README.md: d7966595c68ff1ec4a288caf5d9fe4b0bf580cc5
-README.zh.md: 6537e52eaaea9193d2d95fd0ddf1b4202e5ace38
+README.zh.md: ced1ada5e4a317e37d8601ffe7beaed0e4056aff
diff --git a/packages/mcp/mcp-client/README.zh.md b/packages/mcp/mcp-client/README.zh.md
index 6537e52eaa..ced1ada5e4 100644
--- a/packages/mcp/mcp-client/README.zh.md
+++ b/packages/mcp/mcp-client/README.zh.md
@@ -47,7 +47,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 工具命名
 
-每个 MCP 工具都有两个名称：通过 `tools/call` 在协议上传送的原始 MCP 名称，以及公开名称 `mcp__<serverName>__<rawName>`，后者注册到 `ctx.tools`。公开名称会规范化为 DeepSeek 函数名称契约（64 个字符、`[A-Za-z0-9_-]`）；如果替换或截断改变名称，就会追加 `(serverName, rawName)` 的确定性 12 位十六进制 hash，确保不同工具绝不会折叠为同一个名称。名称是 `(serverName, rawName)` 的纯函数：连接顺序、重新同步和其他服务器永远不会重命名工具。
+每个 MCP 工具都有两个名称：通过 `tools/call` 在协议上传送的原始 MCP 名称，以及公开名称 `mcp__<serverName>__<rawName>`，后者注册到 `ctx.tools`。公开名称会规范化为 DeepSeek 函数名称约定（64 个字符、`[A-Za-z0-9_-]`）；如果替换或截断改变名称，就会追加 `(serverName, rawName)` 的确定性 12 位十六进制 hash，确保不同工具绝不会折叠为同一个名称。名称是 `(serverName, rawName)` 的纯函数：连接顺序、重新同步和其他服务器永远不会重命名工具。
 
 - 发布相同原始名称（例如 `search`）的两个服务器会在各自 namespace 下共存。
 - 存活实例中的重复 `serverName` 会使后加载的插件实例失败。
diff --git a/packages/pty/pty/README.i18n.yaml b/packages/pty/pty/README.i18n.yaml
index c7e214563d..19ab05fd45 100644
--- a/packages/pty/pty/README.i18n.yaml
+++ b/packages/pty/pty/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/pty/pty/README.md
 README.md: 0f8b8e499dc81ce91e249f44bb38c8cc1af89d3f
-README.zh.md: b0c2e21a2bd5fca1088908bdde76ff1eb2ee8bfd
+README.zh.md: c1062de5f06cfbebbd10200ed5a835b1ab93b8a0
diff --git a/packages/pty/pty/README.zh.md b/packages/pty/pty/README.zh.md
index b0c2e21a2b..c1062de5f0 100644
--- a/packages/pty/pty/README.zh.md
+++ b/packages/pty/pty/README.zh.md
@@ -4,7 +4,7 @@
 
 限定所有者范围的持久 PTY seam。`PtyService` 注册为 `ctx.pty`，生成不透明的会话 id，通过具名后端路由创建操作，将每个操作限制在完全相同的活跃 `Agent` 内，并在该 agent（智能体）或服务 dispose（资源释放）时等待后端完全停稳。
 
-## 契约
+## 约定
 
 - 后端注册一个稳定的 `type`，并返回尚未发布的 `PtyBackendSession`；失败或取消的设置过程必须清理部分资源。若清理失败，则以 `PtyBackendCleanupError` 拒绝，使注册表能在取消后继续保留该清理失败。
 - spawn 取消会保留调用方提供的确切中止原因。后端设置完成后，服务 dispose 与所有者消失仍分别对应可供机器路由的不同失败。
@@ -38,4 +38,4 @@
 ## 已知限制与暂缓事项
 
 - 会话只存在于进程本地，harness 重启后不会恢复。
-- 系统有意不支持跨 agent 共享；未来的共享会话设计需要独立的权限契约。
+- 系统有意不支持跨 agent 共享；未来的共享会话设计需要独立的权限约定。
diff --git a/packages/pty/tool-bash-persistent/README.i18n.yaml b/packages/pty/tool-bash-persistent/README.i18n.yaml
index aec30c2b4a..34376a0701 100644
--- a/packages/pty/tool-bash-persistent/README.i18n.yaml
+++ b/packages/pty/tool-bash-persistent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/pty/tool-bash-persistent/README.md
 README.md: cfb3acf41803f5b06ecb3f56ee8ffc29ce9147b1
-README.zh.md: a525485933344a8f9bc218456c099efdef572902
+README.zh.md: cf35a212159e7d12e1bdaa146b32b397d916a912
diff --git a/packages/pty/tool-bash-persistent/README.zh.md b/packages/pty/tool-bash-persistent/README.zh.md
index a525485933..cf35a21215 100644
--- a/packages/pty/tool-bash-persistent/README.zh.md
+++ b/packages/pty/tool-bash-persistent/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包拥有工具契约和 shell 复用；PTY 后端与沙箱策略由部署选择。
+模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包拥有工具约定和 shell 复用；PTY 后端与沙箱策略由部署选择。
 
 ## 配置
 
@@ -11,7 +11,7 @@
 | `backendType` | `shell` | 每个 Agent shell 使用的已注册 PTY 后端。 |
 | `timeoutMs` | `300000` | 单条命令的墙钟时间上限；超时会关闭 shell。 |
 | `maxOutputChars` | `16000` | 命令输出最多保留的字符数；固定诊断会在此后追加。 |
-| `description` | 持久 shell 描述 | 面向模型的环境契约。 |
+| `description` | 持久 shell 描述 | 面向模型的环境约定。 |
 
 ## 模型体验
 
diff --git a/packages/sandbox/sandbox/README.i18n.yaml b/packages/sandbox/sandbox/README.i18n.yaml
index 72a03cbfdd..3c29efec12 100644
--- a/packages/sandbox/sandbox/README.i18n.yaml
+++ b/packages/sandbox/sandbox/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox/README.md
 README.md: 8c1c747f6c7178f9c8c1a9827675ffa98f29aa6d
-README.zh.md: 1e9ecee967bfc3621d6fb441f405e84896fa7863
+README.zh.md: abc5d387384e3a69e35496d6ce4bc9830185c55d
diff --git a/packages/sandbox/sandbox/README.zh.md b/packages/sandbox/sandbox/README.zh.md
index 1e9ecee967..abc5d38738 100644
--- a/packages/sandbox/sandbox/README.zh.md
+++ b/packages/sandbox/sandbox/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务契约（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。
+抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务约定（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。
 
 用一句话概括约定：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
 
diff --git a/packages/scaffold/protocol/README.i18n.yaml b/packages/scaffold/protocol/README.i18n.yaml
index 719a135b37..f038434410 100644
--- a/packages/scaffold/protocol/README.i18n.yaml
+++ b/packages/scaffold/protocol/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/scaffold/protocol/README.md
 README.md: 88a48957d0d44cec9f776d31eab7d25bd353de5f
-README.zh.md: c662d28ec6eea5fe4829030daf210a91fd70ff0f
+README.zh.md: 6618d8838a00f945c79d7ec24b1e7491df08a3f1
diff --git a/packages/scaffold/protocol/README.zh.md b/packages/scaffold/protocol/README.zh.md
index c662d28ec6..6618d8838a 100644
--- a/packages/scaffold/protocol/README.zh.md
+++ b/packages/scaffold/protocol/README.zh.md
@@ -22,7 +22,7 @@ DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按
 | server→client | `subagent.started` | `SubagentStartedNotification` |
 | server→client | `subagent.finished` | `SubagentFinishedNotification`（仅进程内运行） |
 
-`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。`SessionPromptResult.messageId` 标识已排队的 `UserMessage`；它不标识后续的助手消息、轮次结束或提示词结果。客户端根据自己对活动区间的所有权，组合持续开放的 `session.event` 流与 agent 级的 `session.status`。`InitializeParams.maxTokens` 是可选的正的安全整数，用于限制 SDK 创建的 agent 及其进程内后代的每次对话模型输出；省略时会应用所选适配器的确切模型默认值，否则提供方行为保持不变。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇是协议格式契约的一部分。`serverInfo.name` 的协议值固定为 `deepseek-harness-sdk-runtime`。
+`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。`SessionPromptResult.messageId` 标识已排队的 `UserMessage`；它不标识后续的助手消息、轮次结束或提示词结果。客户端根据自己对活动区间的所有权，组合持续开放的 `session.event` 流与 agent 级的 `session.status`。`InitializeParams.maxTokens` 是可选的正的安全整数，用于限制 SDK 创建的 agent 及其进程内后代的每次对话模型输出；省略时会应用所选适配器的确切模型默认值，否则提供方行为保持不变。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇是协议格式约定的一部分。`serverInfo.name` 的协议值固定为 `deepseek-harness-sdk-runtime`。
 
 ## 模型体验
 
diff --git a/packages/session-query/session-query-sqlite/README.i18n.yaml b/packages/session-query/session-query-sqlite/README.i18n.yaml
index 9c2622086a..75fff04fcd 100644
--- a/packages/session-query/session-query-sqlite/README.i18n.yaml
+++ b/packages/session-query/session-query-sqlite/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session-query/session-query-sqlite/README.md
 README.md: 4bf4d979f2d2954cd6280c80bf7f5988d8121fd1
-README.zh.md: aafd4d0a1873090c2101bafb634c3b0d8dcbc6eb
+README.zh.md: 56f7dfa8bad3a04a6bf17eac08b62a1a11f4d53f
diff --git a/packages/session-query/session-query-sqlite/README.zh.md b/packages/session-query/session-query-sqlite/README.zh.md
index aafd4d0a18..56f7dfa8ba 100644
--- a/packages/session-query/session-query-sqlite/README.zh.md
+++ b/packages/session-query/session-query-sqlite/README.zh.md
@@ -4,7 +4,7 @@
 
 具体 `ctx.sessionQuery` 后端。`SessionQuerySqlite` 从接口包继承精确读取、跟踪和提供方无关的过滤，并使用 SQLite FTS5 实现其两个全文方法。搜索使用实时优先的逻辑会话语料库，并按每个会话中匹配度最高的事件对跨会话结果分组。
 
-## 搜索契约
+## 搜索约定
 
 `searchSessions(request, exec?)` 返回跨语料库的 `SessionSearchHit` 分页结果；`searchEvents(request, exec?)` 返回单个会话内的 `SessionEventSearchHit` 分页结果。查询不得省略，首尾空白会被移除，内部空白会被规范化，并按字面短语处理。引号、`OR`、`NEAR` 和 `*` 等 FTS5 语法被视为数据，而非可执行 MATCH 语法。元数据过滤器是在排名前应用的参数化 SQL 谓词。为使 SQLite FTS5 MATCH 保持在受支持的外层谓词上下文中，跨会话请求最多可编译 14 个组合会话与事件过滤谓词；会话内请求最多可编译 13 个过滤谓词，因为固定目标会话谓词占用一个槽位。每个范围端点编译为一个谓词。请求超过任一谓词预算，或超过 SQLite 可移植的 32,766 总绑定上限（包括固定查询和分页值）时，会在准备语句前以 `SESSION_QUERY_INVALID_FILTER` 失败。
 
@@ -24,7 +24,7 @@
 
 ## 配置
 
-| 键 | 默认值 | 契约 |
+| 键 | 默认值 | 约定 |
 |---|---:|---|
 | `path` | 必填 | 专用派生索引 SQLite 路径；支持 `:memory:`。在 POSIX 文件系统上，缺失的文件系统路径会以仅所有者可访问的方式创建。 |
 | `openAt` | `startup` | `startup` 会在服务激活完成前打开；`first-search` 把 SQLite 模块与句柄推迟到搜索时再加载和打开。 |
diff --git a/packages/session-query/session-query/README.i18n.yaml b/packages/session-query/session-query/README.i18n.yaml
index 6d801d9d23..423d3f2d90 100644
--- a/packages/session-query/session-query/README.i18n.yaml
+++ b/packages/session-query/session-query/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session-query/session-query/README.md
 README.md: b75c1f23264cfa7c9323970b3c1a77ddcfe69be0
-README.zh.md: e1b9727ff892047c56d006e02906f3270fb11293
+README.zh.md: 4f1c4749a847326fd9fbc0ffa627651c052ccd71
diff --git a/packages/session-query/session-query/README.zh.md b/packages/session-query/session-query/README.zh.md
index e1b9727ff8..4f1c4749a8 100644
--- a/packages/session-query/session-query/README.zh.md
+++ b/packages/session-query/session-query/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`SessionQueryService` 是组合式抽象 `ctx.sessionQuery` 契约。它对实时 `ctx.sessions` 和可选的动态挂载 `ctx.sessionPersistence` 实现精确会话历史取回、关系跟踪和与提供方无关的过滤；具体后端实现它的两个全文方法。匹配 id 只产生一条记录：实时事件优先，而 `live` 和 `persisted` 会报告两种来源的可用性。如果不可变 header 存在冲突，则以 `SESSION_QUERY_SOURCE_CONFLICT` 失败。
+`SessionQueryService` 是组合式抽象 `ctx.sessionQuery` 约定。它对实时 `ctx.sessions` 和可选的动态挂载 `ctx.sessionPersistence` 实现精确会话历史取回、关系跟踪和与提供方无关的过滤；具体后端实现它的两个全文方法。匹配 id 只产生一条记录：实时事件优先，而 `live` 和 `persisted` 会报告两种来源的可用性。如果不可变 header 存在冲突，则以 `SESSION_QUERY_SOURCE_CONFLICT` 失败。
 
 ## 读取
 
@@ -37,7 +37,7 @@
 
 ## 配置
 
-| 键 | 默认值 | 契约 |
+| 键 | 默认值 | 约定 |
 |---|---:|---|
 | `readWindowMax` | `50` | `before` 或 `after` 的最大原始事件数。 |
 | `persistedInspectConcurrency` | `4` | 一次批量读取中的最大并发持久化日志检查数；必须是正的安全整数。 |
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 5a4c078a55..1ccd0b5286 100644
--- a/packages/session/session-persistence-jsonl/README.i18n.yaml
+++ b/packages/session/session-persistence-jsonl/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-persistence-jsonl/README.md
 README.md: b7fa8fc2918711dd24eeba67132a267452d401f9
-README.zh.md: e260c7671a1f60eec23852ac27ee5da38425b5fd
+README.zh.md: cf044b937f7ae6d0464603a1b59ad9489423ebe0
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index e260c7671a..cf044b937f 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -42,7 +42,7 @@ JSONL 持久会话存储后端：`SessionPersistence` 的一个具体实现（`d
 - **绑定存储身份。** 查找要求可读项目目录中只有一个匹配会话目录，然后验证 header id 等于请求 id，且 header id/cwd 派生所选 transcript 路径。列表应用同一路径检查，并拒绝重复 id。身份失败发生在修复或 append 前。
 - **延迟实体化。**`create(meta)` 不写入；第一次 `append` 将编码 header 和第一批写入临时文件并执行 `fsync`。POSIX 通过硬链接无覆盖发布，并对父目录 `fsync`。Windows 通过 `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` 无覆盖发布，并通过同一 write-through pattern 创建缺失目录。已创建但从未 append 的会话不留下磁盘内容，不在 `list` 中。
 - **仅追加。** 已 flush 事件绝不重写。后续原始批次 append 行；压缩批次 append 一个 frame。两条路径都执行 `fsync`，并在捕获到写入或同步失败时回滚到之前字节长度。
-- **崩溃恢复：保留有效尾部工作。**`load` 验证每个完整压缩 frame，并扫描解压 JSONL。最后 frame 结构不完整时，读取器保留其完整解码记录，从 frame 开头截断，并使用共享[持久化契约](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md) 需要的合成工具、步骤和轮次 closer 重新编码这些记录。原始 mode 从第一个不完整行截断。完整 frame 中的 checksum/解压失败，或位于最后已提交的 `turn/end` 处或之前的缺陷属于损坏，会被拒绝。
+- **崩溃恢复：保留有效尾部工作。**`load` 验证每个完整压缩 frame，并扫描解压 JSONL。最后 frame 结构不完整时，读取器保留其完整解码记录，从 frame 开头截断，并使用共享[持久化约定](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md) 需要的合成工具、步骤和轮次 closer 重新编码这些记录。原始 mode 从第一个不完整行截断。完整 frame 中的 checksum/解压失败，或位于最后已提交的 `turn/end` 处或之前的缺陷属于损坏，会被拒绝。
 - **非变更检查。**`inspect()` 返回不可变、平衡的逻辑视图，并可在内存中合成恢复 closer，但不会截断不完整尾部或更改轻量修订。
 - **连续 seq。**`append` 拒绝第一个 `seq` 不继续已存储日志的批次，并拒绝非 JSON 可序列化 `event.data`，同时命名违规事件类型。
 - **轻量修订。**`listSnapshots(signal?)` 使用 device、inode、size 和纳秒时间戳标识日志，避免解析完整日志；该标识会在 append、修复、替换或存储变更后改变。完整前缀读取要求读取字节前后的身份一致，`readStoredRevision()` 使用同一身份校验保留的 preparation，而不加载日志。快照列表通过产物发现转发精确信号，并在每个 `stat` 前后检查取消；由于文件系统 `stat` 不可中断，取消会等待活动调用完成，然后在不启动另一次调用的情况下拒绝。
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index bb8335b826..41cd655b31 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-persistence-sqlite/README.md
 README.md: 4961f62bf6854c343d35b8406c9d721590274534
-README.zh.md: 237352d1661f505ec0352dfc3eae48d9b636e44a
+README.zh.md: 0507e0fa99bc553317c34e51f30e4daaceee93fd
diff --git a/packages/session/session-persistence-sqlite/README.zh.md b/packages/session/session-persistence-sqlite/README.zh.md
index 237352d166..0507e0fa99 100644
--- a/packages/session/session-persistence-sqlite/README.zh.md
+++ b/packages/session/session-persistence-sqlite/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证抽象 seam 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的契约（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
+SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证抽象 seam 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的约定（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
 
 `locate(meta)` 返回 `undefined`：所有会话共享一个数据库，因此不存在真实、独立的逐会话 transcript（文本记录）路径。
 
-> **TODO：** 该后端直接调用 `node:sqlite`。如果采用 Cordis 数据库服务（`cordis/db` / `@cordisjs` SQL driver 插件），应改为通过该服务路由，而不在此直接持有 `DatabaseSync`；契约接口（`SessionPersistence`）不会变，只更换存储驱动。
+> **TODO：** 该后端直接调用 `node:sqlite`。如果采用 Cordis 数据库服务（`cordis/db` / `@cordisjs` SQL driver 插件），应改为通过该服务路由，而不在此直接持有 `DatabaseSync`；约定接口（`SessionPersistence`）不会变，只更换存储驱动。
 
 ## 存储模型
 
@@ -16,11 +16,11 @@ SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[
 
 在具有 POSIX mode 的文件系统上，后端为缺失目录请求 mode `0700`，并在 SQLite 打开前以 mode `0600` 排他创建缺失数据库；进程 umask 可进一步限制两者。新 WAL、共享内存和持久 rollback-journal sidecar 获得数据库最终的仅所有者 mode。现有目录、数据库文件和 sidecar 保留原 mode；除已存在数据库外的文件系统设置错误会使初始化失败。这些默认值防止宽松进程 umask 造成的意外暴露，但当其他 principal 能替换父目录中的数据库条目时，不保护数据库机密性或完整性。
 
-## 行上的契约语义
+## 行上的约定语义
 
-- **Append = 事务。**`append` 围绕批次运行 `BEGIN`/`COMMIT`：它实体化 `sessions` 行（如果仍延迟），并 INSERT 每个事件，首先断言连续 seq 契约（第一个事件 `seq` 必须等于已存储 next-seq）。批次中失败（重复 seq 上的 UNIQUE 违规）会完全回滚，使已存储日志和内存游标保持一致。（`load()` 已平衡已存储日志，因此 `append` 不必修复崩溃尾部。）
+- **Append = 事务。**`append` 围绕批次运行 `BEGIN`/`COMMIT`：它实体化 `sessions` 行（如果仍延迟），并 INSERT 每个事件，首先断言连续 seq 约定（第一个事件 `seq` 必须等于已存储 next-seq）。批次中失败（重复 seq 上的 UNIQUE 违规）会完全回滚，使已存储日志和内存游标保持一致。（`load()` 已平衡已存储日志，因此 `append` 不必修复崩溃尾部。）
 - **延迟实体化。**`create()` 只在内存记录意图，第一次 `append` 前不写行。从未 append 的会话没有 `sessions` 行，因此不在 `list()` 中（它精确报告有行的会话）。
-- **在 load 时关闭中断轮次。**`load()` 实现共享[崩溃恢复契约](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)：保留有效中断轮次，在一个事务中追加合成关闭事件，并只移除撕裂尾部行。已提交解析错误或序列缺口使会话无法加载。恢复会变更已存储行，因此下一次 append 从平衡日志和准确游标开始。
+- **在 load 时关闭中断轮次。**`load()` 实现共享[崩溃恢复约定](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)：保留有效中断轮次，在一个事务中追加合成关闭事件，并只移除撕裂尾部行。已提交解析错误或序列缺口使会话无法加载。恢复会变更已存储行，因此下一次 append 从平衡日志和准确游标开始。
 - **非变更检查。**`inspect()` 返回不可变、平衡的逻辑视图，并可在内存中合成恢复 closer，但不会删除撕裂尾部行、追加恢复行或更改轻量修订。
 - **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。完整前缀读取在同一个读事务中捕获该修订及其事件行，`readStoredRevision()` 则只查询会话行来校验保留的准备结果。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
 
diff --git a/packages/session/session-projection-cache/README.i18n.yaml b/packages/session/session-projection-cache/README.i18n.yaml
index 37c8d986f9..df2eadccfb 100644
--- a/packages/session/session-projection-cache/README.i18n.yaml
+++ b/packages/session/session-projection-cache/README.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 packages/session-projection/session-projection-cache/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-projection-cache/README.md
 README.md: 5d4ad07fab6648acdb40c6aa86d32cc78b4c016e
-README.zh.md: 827480658b8c69647380a782c1a983b390380108
+README.zh.md: 9dfcd645097cc8390812be3aef82b9535fa953eb
diff --git a/packages/session/session-projection-cache/README.zh.md b/packages/session/session-projection-cache/README.zh.md
index 827480658b..9dfcd64509 100644
--- a/packages/session/session-projection-cache/README.zh.md
+++ b/packages/session/session-projection-cache/README.zh.md
@@ -8,7 +8,7 @@
 
 - **每次后台写入都 fail-soft。** 持久写失败只记一条警告并保持缓存陈旧；下一次写入或冷读自愈。两次写之间崩溃的代价是更长的尾部回放，绝不是错误的值。
 - **`ver` 与活单元 `stateVersion` 不匹配即丢弃，绝不迁移。** 单元递增版本会在读取时使其行失效；该 key 从日志重新折叠。
-- **整记录写入。** 每次写入替换该会话的完整检查点（注册表切面始终是完整的），并经无损 JSON 边界快照——违反纯 JSON 契约的单元状态会大声失败。
+- **整记录写入。** 每次写入替换该会话的完整检查点（注册表切面始终是完整的），并经无损 JSON 边界快照——违反纯 JSON 约定的单元状态会大声失败。
 - **记录绑定到日志生命周期，而不只是 id。** 每条记录存储其折叠来源的 header 身份（`createdAt`、`cwd`）；每次读取先以活 header 或存储 header 为证验证它，再接受任何行——被删后重建的 id、或缓存幸存而持久化存储被换掉时，无关记录被整体丢弃，绝不播种幻影值。
 - **日志领先，缓存跟随。** 活会话检查点先把缓冲事件持久 flush，缓存行才落地，因此崩溃只会让缓存落后于日志（更长的尾部回放），绝不领先于它。
 
diff --git a/packages/session/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
index 746d64865d..a39e3c8586 100644
--- a/packages/session/session-projection/README.i18n.yaml
+++ b/packages/session/session-projection/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-projection/README.md
 README.md: a42e88c262915fc5e53cd72205079cbc8029a8df
-README.zh.md: 02f1876fc95b5e400f63ae6a0dd1910da4f63c3b
+README.zh.md: 01b23a7152a509efab6e169043a823d49d6d9fde
diff --git a/packages/session/session-projection/README.zh.md b/packages/session/session-projection/README.zh.md
index 02f1876fc9..01b23a7152 100644
--- a/packages/session/session-projection/README.zh.md
+++ b/packages/session/session-projection/README.zh.md
@@ -17,7 +17,7 @@
 - `SessionProjectionMap`——整条链路唯一的 merge-extensible 类型表（host 侧单元、协议块、React 钩子）。值是协议层 JSON 全量值；渲染归 slot 体系管，永远不归本层。
 - `ProjectionDefinition<K, S>`——`{ key, schema, init(), apply(state, event), view(state), stateVersion }`：由三个纯同步函数外加若干声明构成的状态驱动计算单元（state-driven computation unit），绝不是一个不透明的 getter。
 
-## 契约
+## 约定
 
 - **框架负责驱动，领域负责计算。** 注册表只订阅一次 `session/event`；每个已提交事件都会主动经过每个单元的 `apply`。领域不持有任何订阅。cell（每会话每单元一份 `{state, observedSeq}`，以 WeakMap 为键）惰性构建——在事件流过之后才注册的单元，或读取一个早于该注册的会话，都在首次触达时从 `init` 出发在内存日志上折叠。
 - **同引用即无工作。** 对与单元无关的事件，`apply` 必须返回同一个状态引用；驱动以 `Object.is` 把守变更流，因此不匹配的事件只花一次调用，不产生任何下游工作。
@@ -42,6 +42,6 @@
 ## 已知限制与暂缓事项
 
 - **每个尾页携带每个已注册的 key**——尚无逐 key 的 opt-out 或惰性 key 请求形状；在值都是 UI 量级的全量状态（一张 todo 清单、一份 goal 快照）时可以接受，若某领域的值变大再重议。
-- **主动驱动（eager drive）逐事件触达每个单元**——按构造开销很低（全量值规则、同引用闸门），但若出现热点路径，可加按单元的事件类型预过滤，契约不变。
+- **主动驱动（eager drive）逐事件触达每个单元**——按构造开销很低（全量值规则、同引用闸门），但若出现热点路径，可加按单元的事件类型预过滤，约定不变。
 - **注册表 cell 只活在内存里**——重启后首次触达时靠折叠日志重建；挂载了 `dsh-session-projection-cache` 的组合改由持久行播种该折叠。
 - **单元同步纪律只有部分可机械把关**——边界 `schema.parse` 能拒绝返回 Promise 的 `view`，但阻塞的 `apply`、或读取撕裂的非会话状态的 `apply`，只能靠评审把关；invariant 配套记载了为何不存在运行时检查。
diff --git a/packages/session/session-telemetry-otel/README.i18n.yaml b/packages/session/session-telemetry-otel/README.i18n.yaml
index f3a790b362..2897eb7dac 100644
--- a/packages/session/session-telemetry-otel/README.i18n.yaml
+++ b/packages/session/session-telemetry-otel/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-telemetry-otel/README.md
 README.md: 585995ce409255df9608bc33b76625374bc67669
-README.zh.md: 889e46c24785c21cbb19e980291310ad096e761f
+README.zh.md: 7f0b93363fbb4aebb80f0d3cc8108e58ce3f647f
diff --git a/packages/session/session-telemetry-otel/README.zh.md b/packages/session/session-telemetry-otel/README.zh.md
index 889e46c247..7f0b93363f 100644
--- a/packages/session/session-telemetry-otel/README.zh.md
+++ b/packages/session/session-telemetry-otel/README.zh.md
@@ -49,6 +49,6 @@ seam 记录 → SDK 日志记录：`time` → `timestamp`/`observedTimestamp`；
 
 ## 已知限制与暂缓事项
 
-- **上游实验性源码树**：`@opentelemetry/sdk-logs` 仍从上游实验性（experimental）源码树发布；SDK API 的变动只会落在本包，也仅落在本包；seam 契约不动。
+- **上游实验性源码树**：`@opentelemetry/sdk-logs` 仍从上游实验性（experimental）源码树发布；SDK API 的变动只会落在本包，也仅落在本包；seam 约定不动。
 - **真实 collector 行为属于 SDK 导出器**：身份验证、TLS、限流及其他真实 OTLP 部署行为遵循上游 SDK，不由本包自有兼容层处理。
 - **反馈时快照**：`FEEDBACK_ONLY` 在反馈前不保留遥测自有副本。记录反馈时，它读取并脱敏当前的权威日志；反馈前发生崩溃时什么都不上传，而反馈前的策略变更会影响该次回放的导出内容。
diff --git a/packages/session/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml
index 3d7e51ebe9..5fd708de38 100644
--- a/packages/session/session-telemetry/README.i18n.yaml
+++ b/packages/session/session-telemetry/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-telemetry/README.md
 README.md: 67d95bcc62bbf6783f8dcd11f0236d8c926b557b
-README.zh.md: cb251587fc1ce651fe45e1961770a29508f6a1e6
+README.zh.md: 80044ceb57c93f8406398a9239d83cbb6015e98c
diff --git a/packages/session/session-telemetry/README.zh.md b/packages/session/session-telemetry/README.zh.md
index cb251587fc..80044ceb57 100644
--- a/packages/session/session-telemetry/README.zh.md
+++ b/packages/session/session-telemetry/README.zh.md
@@ -4,7 +4,7 @@
 
 遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端约定之后，任何上报 SDK 都无需变形即可满足该约定。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
 
-## 后端契约
+## 后端约定
 
 `TelemetryBackend` 只有三个成员：`emit(record)`（必须是非阻塞入队；它在 `session/event` 热路径或显式权威日志回放期间同步执行）、可选的 `flush()`（轮次边界提示，触发后不等待结果；多数后端不实现它，而由其 SDK 的批处理节奏决定导出时机；并发 flush 与 `shutdown()` 的排空之间的交互由实现方自行负责）、以及 `shutdown()`（生命周期转发点：排空并完全停稳，在 dispose（资源释放）时被等待）。`Telemetry` 是它注册在 `telemetry` 上下文键下的服务形态：每个上下文只允许一个实现，重复加载会抛出异常。后端以 `live` 或 `on-demand` 模式组合 `TelemetryCoordinator`，并在自身所属的触发器中调用 `captureSession(session, throughSeq?)`。
 
diff --git a/packages/session/session-title-llm/README.i18n.yaml b/packages/session/session-title-llm/README.i18n.yaml
index 4ae7cd4aa7..a7744c490b 100644
--- a/packages/session/session-title-llm/README.i18n.yaml
+++ b/packages/session/session-title-llm/README.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 packages/session-title/session-title-llm/README.md
+#   pnpm run verify-translation-pairing --write packages/session/session-title-llm/README.md
 README.md: 342687b5aa0cd35a70abf8cc66b3fe80342bce0b
-README.zh.md: f6f39e07d300dbe53faa51514c29699ca1d6a3d2
+README.zh.md: 10496a727baa8a515f831feb425bc3d66ad91b5f
diff --git a/packages/session/session-title-llm/README.zh.md b/packages/session/session-title-llm/README.zh.md
index f6f39e07d3..10496a727b 100644
--- a/packages/session/session-title-llm/README.zh.md
+++ b/packages/session/session-title-llm/README.zh.md
@@ -6,7 +6,7 @@
 
 此包是普通库，不是 Cordis 插件。提供方插件调用 `registerSessionTitleLlmProvider()`，传入各自节奏与消息选择器；该函数验证共享配置，并将每次修订委派给 `generateSessionTitleWithLlm()`，使各插件的注册、路由、提示词、取消与验证行为不会漂移。
 
-## 路由与失败契约
+## 路由与失败约定
 
 `provider` 和 `model` 覆盖项都是可选的，但必须同时作为非空字符串提供。如果没有这一对取值，辅助模块会使用当前会话已记录 `request/header` 中捕获的确切提供方／模型路由；因此，在任何路由出现前显式刷新时必须提供覆盖项。辅助模块在记录或分发前，依据 `maxInputBytes` 检查最终 JSON 封装用户提示词的大小，包括 seq 字段、包装层与 JSON 转义，而不是将其截断。消费流期间和流完成后都会重新检查超时与调用方取消，因此即使 interceptor 或适配器忽略 abort，也不能接受迟到的成功结果。格式错误或空输出、工具调用和非 stop 结束原因同样会导致调用被拒绝；会话标题服务决定该拒绝属于自动警告还是显式调用方失败。
 
@@ -16,7 +16,7 @@
 
 除成对的路由覆盖项外，每个字段都必填；库不提供默认值。
 
-| 键 | 契约 |
+| 键 | 约定 |
 |---|---|
 | `targetWords` | 非 CJK 标题的正整数目标词数。 |
 | `targetCjkCharacters` | 中文、日文或韩文标题的正整数目标字符数。 |
diff --git a/packages/session/session-title/README.i18n.yaml b/packages/session/session-title/README.i18n.yaml
index f45602ce97..f87ea98542 100644
--- a/packages/session/session-title/README.i18n.yaml
+++ b/packages/session/session-title/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-title/README.md
 README.md: 13a2a1c298c3abb8c8987b9373edc46a071ce9db
-README.zh.md: 9e271c044033ce17b5c8c744fe7a9cf433c7f473
+README.zh.md: 075e9e31fc7acbc76f0e3fd7a2642b4d879569d3
diff --git a/packages/session/session-title/README.zh.md b/packages/session/session-title/README.zh.md
index 9e271c0440..075e9e31fc 100644
--- a/packages/session/session-title/README.zh.md
+++ b/packages/session/session-title/README.zh.md
@@ -21,13 +21,13 @@ Fork 出的会话会原样继承种子中的标题事件。首消息节奏不会
 
 所有上限都是必填项；该库不提供默认值。
 
-| 键 | 契约 |
+| 键 | 约定 |
 |---|---|
 | `fallbackMaxWords` | 确定性回退中以空白分隔的最大正整数词数。 |
 | `fallbackMaxBytes` | 回退允许的最大正整数 UTF-8 字节数；不得超过 `maxTitleBytes`。 |
 | `maxTitleBytes` | 接受任何来源标题的最大正整数 UTF-8 字节数。 |
 
-## 提供方契约
+## 提供方约定
 
 提供方会提供带品牌类型的稳定 id、自动模式（`first-message` 或 `all-user-messages`）和 `generate(request)`。请求携带活跃会话、截至一次固定修订的所有符合条件消息、可用时当前已记录的主请求路由，以及取消信号。结果包含非空标题、该请求中唯一且有序的来源消息 seq，以及可选的模型来源信息。服务会在结果持久保存前进行规范化和验证。
 
diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml
index b2549e6be1..dbbb9ba698 100644
--- a/packages/settings/settings/README.i18n.yaml
+++ b/packages/settings/settings/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/settings/settings/README.md
 README.md: 0841624e553364fa03f7a1f1209aa72ab13d97e4
-README.zh.md: e8fe4485c2cf6cb6b8710347ebb8dcd1e8424b38
+README.zh.md: 3dbe14a7ce6fc002569eb612f355fa0ff7372ae3
diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md
index e8fe4485c2..3dbe14a7ce 100644
--- a/packages/settings/settings/README.zh.md
+++ b/packages/settings/settings/README.zh.md
@@ -18,7 +18,7 @@
 - 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。watch 的 disposer 返回后不再启动新的调用（已排队的那一次会被跳过）；已启动的调用仍会结算。`settings/updated` 事件逐 listener 扇出，一个抛错的 listener 不会饿死其余 listener；异步 listener 的拒绝会被隔离并记入日志，这正是 `INVARIANT` 编码的失败只从同步 listener 重新抛出的原因。
 - 服务卸载先拒绝新写入与观察者调用的启动，再排干全部排队写入与已启动的观察者调用后才完成；registrant fiber 在写入途中被 dispose 时，该写入仍到达存储，但不向任何人提交或通知。
 
-## 提供方契约
+## 提供方约定
 
 子类实现 `writable`、`load()`、`persist(ns, section)`，可选择为一个本地用户可编辑文件重写 `documentPath` 与 `prepareDocument()`，并通过受保护的 `publish(doc)` 推入外部观察到的文档。基类 service init 在服务可注入前加载并发布一次文档；自有 init（watcher、连接）的 provider 先经 `yield* super[Service.init]()` 委托。publish 时每个已注册 namespace 独立重解析：非法分节保留该 namespace 的最后可用值并告警——热重载绝不拖垮进程；启动期与注册期校验则立即报错。
 
diff --git a/packages/skill/skill/README.i18n.yaml b/packages/skill/skill/README.i18n.yaml
index 2ca9cbac01..2c6f84ca3a 100644
--- a/packages/skill/skill/README.i18n.yaml
+++ b/packages/skill/skill/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/skill/skill/README.md
 README.md: 3dc2bcfa5775736717bdebcb92329d5655198234
-README.zh.md: d11f90d5a8356f06df63aa249a1f8b5851f36f5f
+README.zh.md: e57e389f9080cfc763916111cf80ea97980f01e7
diff --git a/packages/skill/skill/README.zh.md b/packages/skill/skill/README.zh.md
index d11f90d5a8..e57e389f90 100644
--- a/packages/skill/skill/README.zh.md
+++ b/packages/skill/skill/README.zh.md
@@ -43,13 +43,13 @@
 
 `isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 仍是受信且与策略无关的加载原语，因此每个面向用户或模型的消费方都必须先执行与自身接口匹配的判定，再暴露或加载 skill。
 
-## 提供方契约
+## 提供方约定
 
 提供方工厂同步运行，并接收一项注册作用域内的控制能力。注册失败或释放时，`control.signal` 会中止；仅当该精确注册仍处于活动状态时，`control.invalidate()` 才会清除已完成目录，因此延迟回调无法影响同名替代项。不可变提供方可以忽略该控制能力。远程设置、身份验证和发现由提供方可等待的 `list(options)` 调用执行。返回数组是完整发现的简写形式；若提供方已收集到可用候选项，却无法建立权威观测，则返回 `{ candidates, complete: false }`。提供方对象、查找选项、候选项和定义都以只读方式借用，而不是克隆或重新绑定。提供方应遵守 `options.signal`；取消后，注册表也会停止等待不协作的发现或加载。
 
-注册表在缓存前验证候选项，在返回前验证定义。胜出提供方会收到同一候选项和不透明 `locator`，两者都是它从 `list()` 返回的内容，从而支持后端专用文件、URL、id 或版本句柄。调用方和提供方必须保持只读契约。
+注册表在缓存前验证候选项，在返回前验证定义。胜出提供方会收到同一候选项和不透明 `locator`，两者都是它从 `list()` 返回的内容，从而支持后端专用文件、URL、id 或版本句柄。调用方和提供方必须保持只读约定。
 
-违反契约时会快速失败。`list()` 返回的 Promise 被拒绝会被视为瞬时来源失败，并省略其结果。显式的不完整观测仍会为 `list()` 和 `get()` 提供其候选项，但会使聚合快照不完整且不可缓存。提供方或运行时修订发生变化时，会丢弃正在进行的结果并重试一次。如果这次重试也被后续修订取代，则返回其候选项，并将结果标为不完整且不予缓存，以免持续触发失效的提供方一直占用调用方。重复名称依次按 rank、提供方注册顺序和提供方本地顺序解决冲突。摘要按 skill 名称排序。
+违反约定时会快速失败。`list()` 返回的 Promise 被拒绝会被视为瞬时来源失败，并省略其结果。显式的不完整观测仍会为 `list()` 和 `get()` 提供其候选项，但会使聚合快照不完整且不可缓存。提供方或运行时修订发生变化时，会丢弃正在进行的结果并重试一次。如果这次重试也被后续修订取代，则返回其候选项，并将结果标为不完整且不予缓存，以免持续触发失效的提供方一直占用调用方。重复名称依次按 rank、提供方注册顺序和提供方本地顺序解决冲突。摘要按 skill 名称排序。
 
 定义仍采用渐进式加载。`get()` 每次调用都会向胜出提供方请求正文，而不是在此注册表中缓存正文。若返回定义的名称不同于所选候选项，系统会拒绝该陈旧选择，并由注册表在内部使该精确提供方失效，以便下一次快照重新发现其目录。
 
diff --git a/packages/spill/spill/README.i18n.yaml b/packages/spill/spill/README.i18n.yaml
index 7e067f4464..4948b880f0 100644
--- a/packages/spill/spill/README.i18n.yaml
+++ b/packages/spill/spill/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/spill/spill/README.md
 README.md: c3434f90a8f7ab30baa6b237beab6dd9763f9bff
-README.zh.md: 627097b6c481b593523de7ed7951605397724a1c
+README.zh.md: fc80f8a5fee713a6cba1a5c8173c489bfc2c14d8
diff --git a/packages/spill/spill/README.zh.md b/packages/spill/spill/README.zh.md
index 627097b6c4..fc80f8a5fe 100644
--- a/packages/spill/spill/README.zh.md
+++ b/packages/spill/spill/README.zh.md
@@ -24,7 +24,7 @@
 
 ## 词汇
 
-`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource`（toolName、callId、label）是供后端命名和检查使用的描述性来源信息，而非访问控制信息。完整契约见 `src/types.ts`。
+`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource`（toolName、callId、label）是供后端命名和检查使用的描述性来源信息，而非访问控制信息。完整约定见 `src/types.ts`。
 
 设计原理见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中说明了为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。
 
diff --git a/packages/storage/storage-sqlite/README.i18n.yaml b/packages/storage/storage-sqlite/README.i18n.yaml
index 468e931933..9a373d4039 100644
--- a/packages/storage/storage-sqlite/README.i18n.yaml
+++ b/packages/storage/storage-sqlite/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/storage/storage-sqlite/README.md
 README.md: efc1b3ca54181a43c067594cc339ccc3a8fea510
-README.zh.md: a2dffe43b8364f203980ac7306c9f3dd64df68d4
+README.zh.md: bcbccf388cda3955fe6cd6501fd9ffb63e4c2a50
diff --git a/packages/storage/storage-sqlite/README.zh.md b/packages/storage/storage-sqlite/README.zh.md
index a2dffe43b8..bcbccf388c 100644
--- a/packages/storage/storage-sqlite/README.zh.md
+++ b/packages/storage/storage-sqlite/README.zh.md
@@ -8,7 +8,7 @@
 
 每行一个文档：每个单元表都会成为一个物理 STRICT 表 `"u_<unit>_<table>" (key TEXT PRIMARY KEY, value TEXT)`，其中 `value` 是记录的 JSON 文本，因此一个 key 只更新一行（高频变更领域路由到这里而非 JSON 后端的原因）。单元标识位于两个元数据表中：`units` 在单元首次打开时标记其格式版本，描述符不同时以 `version-mismatch` 拒绝；`unit_globals` 保存每个单元的全局单例行。物理布局版本位于 `PRAGMA user_version`；其他任何标记值都会被拒绝（未发布格式，不迁移）。单元名和表名在进入 DDL 之前依据中心的 `UNIT_NAME_RE` 进行验证，因此不会把外部输入插值到 SQL 标识符中。
 
-每个写入原语都是一条预处理语句：SQLite 的逐语句原子性无需显式事务即可满足 KV 契约，写入顺序仍由调用方负责（领域层写入链）。缺失目录和数据库文件会以仅所有者可访问的权限创建（`0o700`／`0o600`），与 session-persistence SQLite 后端一致；在计划的介质层提取完成前，该包逐字复用了后者的打开顺序。
+每个写入原语都是一条预处理语句：SQLite 的逐语句原子性无需显式事务即可满足 KV 约定，写入顺序仍由调用方负责（领域层写入链）。缺失目录和数据库文件会以仅所有者可访问的权限创建（`0o700`／`0o600`），与 session-persistence SQLite 后端一致；在计划的介质层提取完成前，该包逐字复用了后者的打开顺序。
 
 ## 配置（schemastery）
 
diff --git a/packages/subagent/subagent-claude-code/README.i18n.yaml b/packages/subagent/subagent-claude-code/README.i18n.yaml
index 6bc638bdc4..2f6508a5e0 100644
--- a/packages/subagent/subagent-claude-code/README.i18n.yaml
+++ b/packages/subagent/subagent-claude-code/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-claude-code/README.md
 README.md: e62f60fceea16749296a91377785b81d94d751ca
-README.zh.md: e171524157b2b1696df31753816210d41637a911
+README.zh.md: d83a53ea502db659e575fdac0843f5318cff2fa3
diff --git a/packages/subagent/subagent-claude-code/README.zh.md b/packages/subagent/subagent-claude-code/README.zh.md
index e171524157..d83a53ea50 100644
--- a/packages/subagent/subagent-claude-code/README.zh.md
+++ b/packages/subagent/subagent-claude-code/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本包（package）注册固定的 `claude-code` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中调用官方 Claude Agent SDK，通过共享子进程服务启动 SDK 分发的 Claude Code CLI，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果契约仅返回最终答案。
+本包（package）注册固定的 `claude-code` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中调用官方 Claude Agent SDK，通过共享子进程服务启动 SDK 分发的 Claude Code CLI，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果约定仅返回最终答案。
 
 ## 启动与所有权
 
@@ -20,7 +20,7 @@ SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 
 
 ## 能力与上下文
 
-本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Claude Code 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出契约。每次运行都拥有独立的 SDK query、取消控制器、CLI 进程和不持久化的产品会话。
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Claude Code 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出约定。每次运行都拥有独立的 SDK query、取消控制器、CLI 进程和不持久化的产品会话。
 
 ## 配置
 
diff --git a/packages/subagent/subagent-codex/README.i18n.yaml b/packages/subagent/subagent-codex/README.i18n.yaml
index 97c2b9f705..d55f3ab937 100644
--- a/packages/subagent/subagent-codex/README.i18n.yaml
+++ b/packages/subagent/subagent-codex/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-codex/README.md
 README.md: c25ee90edf8972da66448fe84cb659b0aec79e6f
-README.zh.md: 10c8fcc47a9ab04bca983857bd44ede265c23435
+README.zh.md: b302b9dd865e7b19d0c74c0d1c342edb660c242a
diff --git a/packages/subagent/subagent-codex/README.zh.md b/packages/subagent/subagent-codex/README.zh.md
index 10c8fcc47a..b302b9dd86 100644
--- a/packages/subagent/subagent-codex/README.zh.md
+++ b/packages/subagent/subagent-codex/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本包（package）注册固定的 `codex` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中启动官方 `codex app-server --stdio` 命令，创建一个临时 Codex 线程，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果契约仅返回最终答案。
+本包（package）注册固定的 `codex` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中启动官方 `codex app-server --stdio` 命令，创建一个临时 Codex 线程，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果约定仅返回最终答案。
 
 ## 启动与所有权
 
@@ -16,7 +16,7 @@
 
 ## 能力与上下文
 
-本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Codex 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出契约。临时 Codex 线程 ID 与轮次 ID 仅在此次运行内部可见，绝不会持久化到父会话。
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Codex 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出约定。临时 Codex 线程 ID 与轮次 ID 仅在此次运行内部可见，绝不会持久化到父会话。
 
 ## 配置
 
@@ -47,7 +47,7 @@
 
 ## 产品兼容性与证据
 
-生产环境的协议层有意只实现这一单次执行契约所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 NPM 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
+生产环境的协议层有意只实现这一单次执行约定所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 NPM 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
 
 ## 模型体验
 
diff --git a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
index 3973b5dd92..b070f9f5d6 100644
--- a/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
+++ b/packages/subagent/subagent-dsh-sdk/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-dsh-sdk/README.md
 README.md: 0bbcfa105ecf024a2492d39d3bf8d28956110050
-README.zh.md: 5b196da8f11d71b065ee8111cec010b62edd896c
+README.zh.md: 8c8551f85951aa8475ab2ce95771e4d54e0ed89a
diff --git a/packages/subagent/subagent-dsh-sdk/README.zh.md b/packages/subagent/subagent-dsh-sdk/README.zh.md
index 5b196da8f1..8c8551f859 100644
--- a/packages/subagent/subagent-dsh-sdk/README.zh.md
+++ b/packages/subagent/subagent-dsh-sdk/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../scaffold/client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程契约：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
+SDK 提供方会在全新的子进程中把每个 subagent 作为完整的 DeepSeek Harness 运行时运行，并经由 [TypeScript SDK 客户端](../../scaffold/client/README.md) 通过 stdio JSON-RPC 驱动。它是 [`subagent-acp`](../subagent-acp/README.md) 之外的第二个进程外后端，差异在协议格式（wire format）和子进程约定：ACP（Agent Client Protocol）后端能驱动任何 Agent Client Protocol agent（智能体）；本后端专门驱动 harness SDK 运行时（`dsh-jsonrpc-agent` bin 或打包后的可执行文件），因此子进程是一个完整的对等 harness，拥有由 `cordis.yml` 决定的组合、会话持久化、模型路由和工具。
 
 ## 启动与所有权
 
diff --git a/packages/subagent/subagent-fork/README.i18n.yaml b/packages/subagent/subagent-fork/README.i18n.yaml
index cdfa061695..e40cf9901f 100644
--- a/packages/subagent/subagent-fork/README.i18n.yaml
+++ b/packages/subagent/subagent-fork/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-fork/README.md
 README.md: 55475aee7841e91960de79887dfe9bf37afdf9da
-README.zh.md: ef9e4b256931450c0b8664dcc640e000f01c01da
+README.zh.md: 379218970c406162309659277a4fcb2da885d9ea
diff --git a/packages/subagent/subagent-fork/README.zh.md b/packages/subagent/subagent-fork/README.zh.md
index ef9e4b2569..379218970c 100644
--- a/packages/subagent/subagent-fork/README.zh.md
+++ b/packages/subagent/subagent-fork/README.zh.md
@@ -31,7 +31,7 @@ fork 声明 `{ outputSchema: true, depthLimit: true, toolFilter: true, persona:
 
 #### 模型看到的内容
 
-子 agent 先接收由父 agent 已配平的已完成轮次构成的表层前缀，再逐字接收新的任务内容。配置的 persona 会在子 agent 的全新作用域中遮蔽提示词文本；工具限制会过滤其全局协议 schema、可执行工具查找和 Code Mode SDK 绑定，但不影响独立的指导内容。父 agent 的工具视图与权限不会被继承。可选的结构化输出请求会添加仅属于子 agent 的契约。父 agent 当前进行中的轮次会被排除。
+子 agent 先接收由父 agent 已配平的已完成轮次构成的表层前缀，再逐字接收新的任务内容。配置的 persona 会在子 agent 的全新作用域中遮蔽提示词文本；工具限制会过滤其全局协议 schema、可执行工具查找和 Code Mode SDK 绑定，但不影响独立的指导内容。父 agent 的工具视图与权限不会被继承。可选的结构化输出请求会添加仅属于子 agent 的约定。父 agent 当前进行中的轮次会被排除。
 
 #### Token 影响
 
diff --git a/packages/subagent/subagent-inprocess/README.i18n.yaml b/packages/subagent/subagent-inprocess/README.i18n.yaml
index 9bfe1023ee..a6a82fb47f 100644
--- a/packages/subagent/subagent-inprocess/README.i18n.yaml
+++ b/packages/subagent/subagent-inprocess/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-inprocess/README.md
 README.md: 67f0cf5dd1ecb18542af56953a0eaa40988aca0d
-README.zh.md: 0cb9008e52088c2a3c554a4ab6a45e2345b34a08
+README.zh.md: 648a160be5f1c3dcbe66a867a273a3df610dbc0a
diff --git a/packages/subagent/subagent-inprocess/README.zh.md b/packages/subagent/subagent-inprocess/README.zh.md
index 0cb9008e52..648a160be5 100644
--- a/packages/subagent/subagent-inprocess/README.zh.md
+++ b/packages/subagent/subagent-inprocess/README.zh.md
@@ -36,7 +36,7 @@
 
 ## 结构化输出
 
-`attachStructuredRuntime(childCtx, schema)` 会在子 agent 作用域中安装完整契约：
+`attachStructuredRuntime(childCtx, schema)` 会在子 agent 作用域中安装完整约定：
 
 - 使用请求 schema 注册的 `structured_output` 工具会校验并暂存模型值。
 - 一个顺序为 190 的系统提示词段会告诉子 agent，该工具调用就是终态答案。
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 23ed818ebb..ca81aa07a6 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
 README.md: cd25bace16c91e8b44331dc8e5eab0987607e83a
-README.zh.md: b385182f032da17e7326ac265f47a2a5046f918a
+README.zh.md: 52971add9646fd45a33661bb33b3f7d8c452219c
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index b385182f03..52971add96 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -44,7 +44,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 持久化描述符
 
-该 seam 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果契约）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩（compaction）保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
+该 seam 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果约定）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩（compaction）保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
 
 ## 委派深度
 
@@ -86,7 +86,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 收集模型
 
-面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`），并在 `descendants` scope 下遍历 `listDescendants()`。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 明确报错，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 明确报错。完整约定见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
+面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running`／`idle`／`complete`），并在 `descendants` scope 下遍历 `listDescendants()`。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整约定见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
 
 可继续 Activation 会等待 best-effort 的最终会话 flush，但不会把 listener 参与视为持久性确认。一次性运行保留尽力执行的会话检查点，因此已完成的一次性 child 只有在其会话确实进入持久化存储时，才可在 dispose 后继续被发现；如果该检查点缺失，服务不会根据 Task 历史虚构目录条目。
 
@@ -100,7 +100,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 已知限制与暂缓事项
 
-- **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，以及逐子 agent 的继续执行能力声明，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权契约，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
+- **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，以及逐子 agent 的继续执行能力声明，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权约定，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
 - **无 host-user 继续执行**：`followup()` 要求确切在线直接父级。只有 `interrupt()` 接受持久化 parent 地址形式的用户授权，因为停止一个轮次是幂等的且不投递任何内容；未来 host 适配器需要具体的经认证交互，才能让该 seam 获得用户投递能力。
 - **不对当前轮次进行 steering**：可继续消息和唤醒式 report 会排入后续轮次，均不会重定向正在进行的轮次。
 - **取消收敛期间存在唤醒缺口**：中断信号发出后、活动 driver 进入 idle 前被接受的唤醒型 follow-up 会保持排队，直到另一条唤醒发送到达。Issue #1838 负责 agent-loop 的唤醒锁存；普通会话取消也受此影响。
diff --git a/packages/subagent/tool-subagent/README.i18n.yaml b/packages/subagent/tool-subagent/README.i18n.yaml
index a3bfacedda..e5f0c43f61 100644
--- a/packages/subagent/tool-subagent/README.i18n.yaml
+++ b/packages/subagent/tool-subagent/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/tool-subagent/README.md
 README.md: 6ec313b3b97f0ffa7488025d4314b1c6231a6f6a
-README.zh.md: 13ff7ee6fddd25c062c08b0b18c94323824f54b9
+README.zh.md: 1fd88363b3ade9d57c194580f81295eed139ac50
diff --git a/packages/subagent/tool-subagent/README.zh.md b/packages/subagent/tool-subagent/README.zh.md
index 13ff7ee6fd..1fd88363b3 100644
--- a/packages/subagent/tool-subagent/README.zh.md
+++ b/packages/subagent/tool-subagent/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-基于一个已配置 `ctx.subagents` 提供方、面向模型的委派工具。更换提供方只会改变传输，不会改变执行契约。
+基于一个已配置 `ctx.subagents` 提供方、面向模型的委派工具。更换提供方只会改变传输，不会改变执行约定。
 
 ## 提供方选择与生命周期
 
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index e81656d84a..6da5dc1939 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subprocess/subprocess/README.md
 README.md: c28361f5e767f81fe8d1ca4757aece83dccfea5c
-README.zh.md: 828e8818ce3366bd955d83f7ccb5dab0f0379c46
+README.zh.md: b5d0aac765e433dbaeb9b6e24638ffa6bea6cc51
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 828e8818ce..b5d0aac765 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -4,7 +4,7 @@
 
 子进程 seam（`ctx.subprocess`）是一个执行世界的进程部分。抽象的 `SubprocessService` 公开可执行文件查找、普通受管 `spawn` 和一项终端进程原语；其词汇涵盖原始／收集式 stdio、进程与终端句柄、退出事实、进程树／会话清理，以及受管的 `DSH_*` 环境命名空间。本地实现位于 [`dsh-subprocess-local`](../subprocess-local/README.md)。
 
-## 契约
+## 约定
 
 - `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
 - spawn 工作目录和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
diff --git a/packages/support/README.i18n.yaml b/packages/support/README.i18n.yaml
index 824f20ae7e..8034ca14c0 100644
--- a/packages/support/README.i18n.yaml
+++ b/packages/support/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/support/README.md
 README.md: bf0bba1ea7d21700a6743195ec966512c20e01bc
-README.zh.md: 47eba4d51c66914f388ba4a5925323173d5ed7e2
+README.zh.md: 0ea9c6fdc015682a9008825b15127b2c940e4779
diff --git a/packages/support/README.zh.md b/packages/support/README.zh.md
index 47eba4d51c..0ea9c6fdc0 100644
--- a/packages/support/README.zh.md
+++ b/packages/support/README.zh.md
@@ -8,11 +8,11 @@
 |---|---|
 | [`acp-snapshot/`](acp-snapshot/README.md) | 提供 ACP（Agent Client Protocol）快照测试工具包 |
 | [`agent-loop-testkit/`](agent-loop-testkit/README.md) | 为 AgentLoop 测试挂载共享先决条件 |
-| [`invariants/`](invariants/README.md) | 运行开发期运行时契约断言 |
+| [`invariants/`](invariants/README.md) | 运行开发期运行时约定断言 |
 | [`loader-smoke/`](loader-smoke/README.md) | 启动由 Loader 组合的应用以执行冒烟测试 |
 | [`llm-mock-server/`](llm-mock-server/README.md) | 提供确定性的 OpenAI 兼容故障服务器 |
 | [`llm-replay/`](llm-replay/README.md) | 为无密钥测试和演示回放已记录的模型响应 |
 
-当一个包获得产品契约和产品消费方时，它会移出 `support/`。
+当一个包获得产品约定和产品消费方时，它会移出 `support/`。
 
-不变式契约记录在 [docs/subsystems/invariants.md](../../docs/subsystems/invariants.md)。
+不变式约定记录在 [docs/subsystems/invariants.md](../../docs/subsystems/invariants.md)。
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index 25b54630b2..c2aabcac4e 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/support/acp-snapshot/README.md
 README.md: 0b935ef60c33fd24660d8ecf2497f5506157c724
-README.zh.md: 91be3c97bcb67ce10c61513113f683e741bc762f
+README.zh.md: a5fbae98c7eddf827e3747999cf9afeacf636caf
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index 91be3c97bc..a5fbae98c7 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -11,7 +11,7 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 - **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每个原生/JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
 - **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件是有序主级/子级清单；场景表不重复其数量。必须在 vitest 收集时调用。
 
-签入仓库的会话 fixture 使用规范打包行。合并此契约的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
+签入仓库的会话 fixture 使用规范打包行。合并此约定的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
 
 消费方 `*.snapshot.ts` 就是场景表加一次工厂调用：
 
diff --git a/packages/support/invariants/README.i18n.yaml b/packages/support/invariants/README.i18n.yaml
index 9d8d8ff16c..44427199b2 100644
--- a/packages/support/invariants/README.i18n.yaml
+++ b/packages/support/invariants/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/support/invariants/README.md
 README.md: 203dbd5ad09f5b1378061fbf9adcff885889eae2
-README.zh.md: fb9d15f3d0cd77f8002c6ff1a909e09e8c6c61fa
+README.zh.md: 10f072e1d49b778944dfc0914eab48c527b21fed
diff --git a/packages/support/invariants/README.zh.md b/packages/support/invariants/README.zh.md
index fb9d15f3d0..10f072e1d4 100644
--- a/packages/support/invariants/README.zh.md
+++ b/packages/support/invariants/README.zh.md
@@ -30,7 +30,7 @@ interface Config {
 
 发布和注册覆盖全部包；但不会为了覆盖全部包而人为编造运行时断言。只有当包拥有可观察事件关系或相关可变数据关系时，配套入口才安装检查。确认必需方法、插件名称、注入、effect 或固定纯函数结果属于类型、加载或单元测试关注点，而非运行时不变量。
 
-如果不存在合理的运行时关系，配套入口使用空 installer，并以包专用的前置 `No runtime invariant:` 注释说明原因。纯工具、行为已通过 seam 观察的薄实现、仅组合包、二进制程序、契约需要崩溃/往返测试的持久化适配器和测试支持包通常属于此类。当 owner 获得可变状态或事件协议时，必须重新审视该说明。
+如果不存在合理的运行时关系，配套入口使用空 installer，并以包专用的前置 `No runtime invariant:` 注释说明原因。纯工具、行为已通过 seam 观察的薄实现、仅组合包、二进制程序、约定需要崩溃/往返测试的持久化适配器和测试支持包通常属于此类。当 owner 获得可变状态或事件协议时，必须重新审视该说明。
 
 当前可执行配套入口保护以下关系：
 
@@ -66,7 +66,7 @@ ctx.plugin(InvariantService, {
 ctx.plugin(SessionInvariant)
 ```
 
-标准 agent 主干挂载服务和 4 个核心有状态配套入口。自定义组合为希望检查其契约的其他已加载包显式添加配套入口；过滤器可以在不改变包入口的情况下禁用或选择注册。
+标准 agent 主干挂载服务和 4 个核心有状态配套入口。自定义组合为希望检查其约定的其他已加载包显式添加配套入口；过滤器可以在不改变包入口的情况下禁用或选择注册。
 
 每个普通 Vitest 拓扑都挂载显式启用的服务和当前测试包的配套入口。聚焦套件覆盖可执行配套入口的合法与违规观测，一个穷尽拓扑则挂载全部配套入口，以证明注册和 dispose 接线。
 
@@ -80,6 +80,6 @@ ctx.plugin(SessionInvariant)
 
 ## 已知限制与暂缓事项
 
-- 请求重建覆盖 loop 在冻结前显式标记的请求；直接一次性 LLM（大语言模型）调用即使由调用方冻结或附加会话 id，仍不在该标记契约内。
+- 请求重建覆盖 loop 在冻结前显式标记的请求；直接一次性 LLM（大语言模型）调用即使由调用方冻结或附加会话 id，仍不在该标记约定内。
 - 仅实时生命周期配套入口无法重建自身重新加载前开始的操作。标准组合和测试组合会在相应操作开始前挂载它们。
 - 正则表达式过滤器在服务生命周期内固定；更改它们需要执行普通 Cordis 插件重新加载。
diff --git a/packages/tasks/tasks/README.i18n.yaml b/packages/tasks/tasks/README.i18n.yaml
index 1d803e486e..e7206370dd 100644
--- a/packages/tasks/tasks/README.i18n.yaml
+++ b/packages/tasks/tasks/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/tasks/README.md
 README.md: b5a7380e0cb7df5dd20baecea8656db2aad3460a
-README.zh.md: f2e4b10d30d81c840f5598141bbe246634bf2884
+README.zh.md: 5cbcfac8d7153616c39642c11860fc88b8495d1f
diff --git a/packages/tasks/tasks/README.zh.md b/packages/tasks/tasks/README.zh.md
index f2e4b10d30..5cbcfac8d7 100644
--- a/packages/tasks/tasks/README.zh.md
+++ b/packages/tasks/tasks/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-后台任务注册表 seam（`ctx.tasks`）。抽象的 `TaskService` 及其词汇类型在同一份契约下为长时间运行的生产方提供共享 id、owner 隔离、读取、取消、等待、通知和清理；进程局部注册表位于 [`dsh-tasks-local`](../tasks-local/README.md)。生产方插件使用其不透明 id namespace 扩展 `TaskKindMap`。
+后台任务注册表 seam（`ctx.tasks`）。抽象的 `TaskService` 及其词汇类型在同一份约定下为长时间运行的生产方提供共享 id、owner 隔离、读取、取消、等待、通知和清理；进程局部注册表位于 [`dsh-tasks-local`](../tasks-local/README.md)。生产方插件使用其不透明 id namespace 扩展 `TaskKindMap`。
 
-## 服务契约
+## 服务约定
 
 - `start(spec): TaskId` 验证控制表层、spec、确切且仍存活的 owner，以及可选的 `outputLimitBytes`（如提供则须为正数），然后只调用生产方的 `run()` 一次。启动方抛出异常时不注册任何内容；成功返回会直接提交，不再执行其他可能失败的步骤。
 - `get(id, caller?)` 和 `list(caller?)` 返回非消费式快照。列表只包含调用方拥有及无 owner 的任务。
@@ -18,7 +18,7 @@
 
 `outputLimitBytes` 是生产方拥有的模型呈现策略，会原样携带到快照中。控制表层在添加状态或通知元数据后应用它；注册表不会重写生产方输出，也不会为省略此字段的生产方虚构默认值。
 
-实现还必须兑现契约的生命周期语义：注册的存续期长于生产方 fiber 与控制表层 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
+实现还必须兑现约定的生命周期语义：注册的存续期长于生产方 fiber 与控制表层 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
 
 参见[任务类型目录](../../../docs/subsystems/tasks.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)。
 
@@ -34,4 +34,4 @@
 
 - **流输出只有一个消费游标**：独立观察者需要游标或快照 API。
 - **前台工作无法转为后台**：生产方在启动前选择前台或后台。
-- **契约是进程内的**：`TaskStart.run()` 传入回调和确切的 `Agent` 对象；持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义，才能实现此 seam。
+- **约定是进程内的**：`TaskStart.run()` 传入回调和确切的 `Agent` 对象；持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义，才能实现此 seam。
diff --git a/packages/typert/registry/README.i18n.yaml b/packages/typert/registry/README.i18n.yaml
index f7193bdd9f..5730472079 100644
--- a/packages/typert/registry/README.i18n.yaml
+++ b/packages/typert/registry/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/registry/README.md
 README.md: fa227b1c8faf1abd5a6492d4b8fe7d0c51ceeef1
-README.zh.md: b3dd820c9a4f23917e85631bedaf68e4fc5803c1
+README.zh.md: b708e536acb7a5c4dc47e8c83180728e2ce150cd
diff --git a/packages/typert/registry/README.zh.md b/packages/typert/registry/README.zh.md
index b3dd820c9a..b708e536ac 100644
--- a/packages/typert/registry/README.zh.md
+++ b/packages/typert/registry/README.zh.md
@@ -17,7 +17,7 @@
 - `toJSONSchema(key, params?)` 使用 `z.toJSONSchema()` 投影当前有效的 schema，且不缓存结果。
 - `typertKey()` 和 `typertPackageKey()` 构造两种稳定的标识形式。
 
-`@deepseek-ai/dsh-typert-registry/types` 子路径包含注册项和记录的纯类型契约。[`dsh-typert-loader`](../loader/README.md) 会在 Loader 组合中发现并注册生成的宿主侧产物；其他组合所有者可以直接调用 `ctx.typert.register()`。
+`@deepseek-ai/dsh-typert-registry/types` 子路径包含注册项和记录的纯类型约定。[`dsh-typert-loader`](../loader/README.md) 会在 Loader 组合中发现并注册生成的宿主侧产物；其他组合所有者可以直接调用 `ctx.typert.register()`。
 
 ## 模型体验
 
diff --git a/packages/typert/type-meta/README.i18n.yaml b/packages/typert/type-meta/README.i18n.yaml
index a61602c07b..c7a3c1c860 100644
--- a/packages/typert/type-meta/README.i18n.yaml
+++ b/packages/typert/type-meta/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/type-meta/README.md
 README.md: 9bd475f8973ec54756fe0e63d5b7fa485381697d
-README.zh.md: 10a6309bc47001d572abb3dd3f794ebfcf6252e8
+README.zh.md: 68b690d2143b4420f2e10efceaca0dfc1149d0ff
diff --git a/packages/typert/type-meta/README.zh.md b/packages/typert/type-meta/README.zh.md
index 10a6309bc4..68b690d214 100644
--- a/packages/typert/type-meta/README.zh.md
+++ b/packages/typert/type-meta/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、Host Gateway 和 Client API 共享。它负责 Remote Service 基类、装饰器、显式 binding 回退、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方契约；它不执行 TypeScript 分析，也不注册具体 Cordis 服务。
+该包提供不依赖编译器的声明，由业务包、生成的 TypeRT 产物、Host Gateway 和 Client API 共享。它负责 Remote Service 基类、装饰器、显式 binding 回退、可通过声明合并扩展的协议映射、调用描述符、编解码器和提供方约定；它不执行 TypeScript 分析，也不注册具体 Cordis 服务。
 
 ## Remote 声明
 
@@ -20,7 +20,7 @@ Host 方法通过将 `signal: AbortSignal` 声明为最后一个参数来启用
 
 业务包扩展 `TypeRTLookupMap` 和 `TypeRTContextMap`，以关联 Host 对象或作用域 Context 与其协议身份。生成的产物扩展 `TypeRTRemoteMap`、`TypeRTRemoteScopeMap` 和 `TypeRTRemoteNamespaceMap`，使 Client 导入后仅暴露选定的 Remote 方法。`InvocationDescriptor` 是供注册表、Gateway 和 Client Remote 使用的共享运行时形式。
 
-查找包与 Context 包同时负责其契约的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。lookup 或 Host Context provider 提供稳定声明与默认 resolver，Host 组合可以另行配置同步或异步 resolver；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
+查找包与 Context 包同时负责其约定的两侧：声明合并提供静态关联，运行时提供方则向 `ctx.typert` 注册身份解析。lookup 或 Host Context provider 提供稳定声明与默认 resolver，Host 组合可以另行配置同步或异步 resolver；策略拒绝可用 `TypeRTLookupFailure` 携带由边界适配器拥有的失败值。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
 
 ## 模型体验
 
diff --git a/packages/util/README.i18n.yaml b/packages/util/README.i18n.yaml
index 69dbd9afbb..fd63d200f9 100644
--- a/packages/util/README.i18n.yaml
+++ b/packages/util/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/README.md
 README.md: b84f2cbb88981aa2edbde65d8a711b28cc5b48e9
-README.zh.md: b1d7ccf14059892d57fb01502f177e0e618058b1
+README.zh.md: 3814dffe1eb8c68f6d38d39aa750c80ce325f9af
diff --git a/packages/util/README.zh.md b/packages/util/README.zh.md
index b1d7ccf140..3814dffe1e 100644
--- a/packages/util/README.zh.md
+++ b/packages/util/README.zh.md
@@ -7,7 +7,7 @@
 | 包 | 职责 |
 |---|---|
 | [`brand/`](brand/README.md) | 提供带名义品牌的类型 |
-| [`paths/`](paths/README.md) | 解析 harness（智能体框架）数据根目录和共享路径 |
+| [`paths/`](paths/README.md) | 解析 Harness 数据根目录和共享路径 |
 | [`timeout/`](timeout/README.md) | 提供截止时间和超时分类原语 |
 | [`retention/`](retention/README.md) | 限制保留文本和项集合的大小 |
 | [`atomic-write/`](atomic-write/README.md) | 以原子方式替换文件 |
diff --git a/packages/util/atomic-write/README.i18n.yaml b/packages/util/atomic-write/README.i18n.yaml
index 33e1f6014b..a56d8ceb56 100644
--- a/packages/util/atomic-write/README.i18n.yaml
+++ b/packages/util/atomic-write/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/atomic-write/README.md
 README.md: 2ff4abb6ac10d8b592ccd2056b4f1f92cc8518b0
-README.zh.md: 4284d06422564268bb9e31d1a1ed06ab5271e562
+README.zh.md: 570a5243aefbe6870c1991786f711adc77faacae
diff --git a/packages/util/atomic-write/README.zh.md b/packages/util/atomic-write/README.zh.md
index 4284d06422..570a5243ae 100644
--- a/packages/util/atomic-write/README.zh.md
+++ b/packages/util/atomic-write/README.zh.md
@@ -20,7 +20,7 @@ await withFileLock('/home/u/.dsh/settings.yaml', async () => {
 })
 ```
 
-`writeFileAtomic` 提交一份已经渲染好的字符串。契约按故障利用它的先后顺序列出：
+`writeFileAtomic` 提交一份已经渲染好的字符串。约定按故障利用它的先后顺序列出：
 
 - **独占创建临时文件**（`wx` + 随机后缀）：open 拒绝跟随预先埋在可猜测临时路径上的符号链接。
 - **全新 inode 携带 `mode` 走完 rename**：替换权限过宽的旧文件时直接收窄，不存在 chmod 竞态。`mode` 为必填，让权限决策始终可见于每个调用点（与所有新建 inode 一样受进程 umask 影响）。
diff --git a/packages/util/environment/README.i18n.yaml b/packages/util/environment/README.i18n.yaml
index 633064ae4c..2064bef6b6 100644
--- a/packages/util/environment/README.i18n.yaml
+++ b/packages/util/environment/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/environment/README.md
 README.md: 599a9ba747905b66452b57717dabcc6f4678a3dd
-README.zh.md: 69f9c670bbb3ea1b2fbddaa7508a19dfb47fad12
+README.zh.md: ca1da309fda28913ee7b90953d50fc0a7172ca87
diff --git a/packages/util/environment/README.zh.md b/packages/util/environment/README.zh.md
index 69f9c670bb..ca1da309fd 100644
--- a/packages/util/environment/README.zh.md
+++ b/packages/util/environment/README.zh.md
@@ -32,5 +32,5 @@ const endpoint = environmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value
 
 ## Known Limitations and Deferred Work
 
-- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 契约](../../boot/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
+- **快照不是子进程边界**：每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 的清洗规则抵达子进程。产品启动器的 [`.env` 约定](../../boot/app-boot/README.md#profiles) 会在物化之前拒绝 bootstrap 变量。
 - **没有按工作区划分的层**：项目层是*调用*目录，在启动时固定。之后在 Web UI 中选择的工作区不贡献任何内容，这是刻意的：跟随它等于让模型自己的工作区在会话中途改变 harness 的环境。
diff --git a/packages/util/native-command/README.i18n.yaml b/packages/util/native-command/README.i18n.yaml
index 50116d2ef0..237ad82299 100644
--- a/packages/util/native-command/README.i18n.yaml
+++ b/packages/util/native-command/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/util/native-command/README.md
 README.md: dd9d1ddaf817b2ff77ec0cd01710053e918b4296
-README.zh.md: 339db7f3adb402193ef14247413b02f80b6f728d
+README.zh.md: 3ff8a392f2c511295adb0bf5f62b6e0527cbaea6
diff --git a/packages/util/native-command/README.zh.md b/packages/util/native-command/README.zh.md
index 339db7f3ad..3ff8a392f2 100644
--- a/packages/util/native-command/README.zh.md
+++ b/packages/util/native-command/README.zh.md
@@ -8,7 +8,7 @@
 
 它是**库，不是服务或插件**：没有 `ctx`、不注册任何东西、不持有状态、不发事件。
 
-## Surface
+## 接口面
 
 ```ts
 import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
diff --git a/packages/web/README.i18n.yaml b/packages/web/README.i18n.yaml
index 0eaedfb018..87177273da 100644
--- a/packages/web/README.i18n.yaml
+++ b/packages/web/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/README.md
 README.md: 811c8b3439a8962116df0e8b3ab4f6e282ecb3d2
-README.zh.md: c7c0546c6a2527ba04bd802945c0dd4ee4353a37
+README.zh.md: e328447d5d026c0abc815b269179ba6c4cd9acfc
diff --git a/packages/web/README.zh.md b/packages/web/README.zh.md
index c7c0546c6a..e328447d5d 100644
--- a/packages/web/README.zh.md
+++ b/packages/web/README.zh.md
@@ -13,6 +13,6 @@
 | [`web-fetch-local/`](web-fetch-local/README.md) | 抓取公共 HTTP 和 HTTPS 资源 | 注册到 `ctx.web` |
 | [`tool-web/`](tool-web/README.md) | 向模型公开 web 搜索和抓取 | 注册到 `ctx.tools` |
 
-[web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) 记录了搜索和抓取共用一项提供方选择服务的原因。
+[web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)记录了搜索和抓取共用一项提供方选择服务的原因。
 
 子系统参考——搜索/抓取请求与结果、可用性、`WebError`——见 [docs/subsystems/web.md](../../docs/subsystems/web.md)；依据（含延后的 SSRF 防护）见 [web 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)。
diff --git a/packages/web/tool-web/README.i18n.yaml b/packages/web/tool-web/README.i18n.yaml
index 4751678c04..4a1d973a1a 100644
--- a/packages/web/tool-web/README.i18n.yaml
+++ b/packages/web/tool-web/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/tool-web/README.md
 README.md: 646601bb5bd6c27876918b7aca49962ae34bae33
-README.zh.md: 192b7020f5fac026f325448630b2e17d7ce6a0c4
+README.zh.md: 135c75831045225a0ac6d4637ff5c8b4105336c0
diff --git a/packages/web/tool-web/README.zh.md b/packages/web/tool-web/README.zh.md
index 192b7020f5..135c758310 100644
--- a/packages/web/tool-web/README.zh.md
+++ b/packages/web/tool-web/README.zh.md
@@ -37,7 +37,7 @@
 
 ## 稳定注册
 
-工具注册遵循产品**启用状态**，而非后端可用性。即使选中的提供方缺失、错误配置、存在歧义或暂时不可用，工具仍保持可见；seam 在执行时解析提供方，执行以结构化 `WebError`（例如 `WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_AMBIGUOUS`）失败，`ToolRegistry.execute()` 会把它转为模型可读、钩子／UI 可路由的错误工具结果。这样无需把插件加载顺序、凭据状态或 HMR（热模块替换）时机纳入面向模型契约，也能保持模型 schema 稳定。要彻底移除 web 工具，请在此处通过配置将其禁用。
+工具注册遵循产品**启用状态**，而非后端可用性。即使选中的提供方缺失、错误配置、存在歧义或暂时不可用，工具仍保持可见；seam 在执行时解析提供方，执行以结构化 `WebError`（例如 `WEB_PROVIDER_UNAVAILABLE`、`WEB_PROVIDER_AMBIGUOUS`）失败，`ToolRegistry.execute()` 会把它转为模型可读、钩子／UI 可路由的错误工具结果。这样无需把插件加载顺序、凭据状态或 HMR（热模块替换）时机纳入面向模型约定，也能保持模型 schema 稳定。要彻底移除 web 工具，请在此处通过配置将其禁用。
 
 工具绝不会调用提供方的 `available()`，也不会枚举提供方；唯一执行路径是 `ctx.web.search()`／`ctx.web.fetch()`，提供方不可用时，选择机制会在执行阶段抛出结构化 `WebError`，其错误码由工具接收。提供方选择完全留在 seam 内，由单一主体负责。
 
diff --git a/packages/web/web-search-deepseek/README.i18n.yaml b/packages/web/web-search-deepseek/README.i18n.yaml
index a552a7c9b2..4d5ac9d768 100644
--- a/packages/web/web-search-deepseek/README.i18n.yaml
+++ b/packages/web/web-search-deepseek/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/web-search-deepseek/README.md
 README.md: 95340314fe08d0963b899f4a1d704a98f85963a5
-README.zh.md: 48d94b64d15e4c0902e5222fe9a737b1e67270fc
+README.zh.md: cf83426f70d6d2a77fd9acf5e927d1b13ec345eb
diff --git a/packages/web/web-search-deepseek/README.zh.md b/packages/web/web-search-deepseek/README.zh.md
index 48d94b64d1..cf83426f70 100644
--- a/packages/web/web-search-deepseek/README.zh.md
+++ b/packages/web/web-search-deepseek/README.zh.md
@@ -79,6 +79,6 @@ DeepSeek 不返回该提供方可作为 `content` 信任的提供方生成答案
 ## 已知限制与暂缓事项
 
 - **一次搜索需要完整的 Messages 模型轮次**：会产生延迟与生成 token，并且最多执行 `maxUses` 次服务器侧搜索；DeepSeek 不公开专用检索端点。
-- **动态凭据的可用性在操作内部解析**：同步的 `available()` 契约可以确认解析器存在，但无法查询异步凭据存储。因此，选中的无密钥提供方会使搜索以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败；稳定的 `web_search` schema 仍保持注册。调用方取消在本地与该预检存在竞态，但无法强制任意凭据后端自行停止工作。
+- **动态凭据的可用性在操作内部解析**：同步的 `available()` 约定可以确认解析器存在，但无法查询异步凭据存储。因此，选中的无密钥提供方会使搜索以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败；稳定的 `web_search` schema 仍保持注册。调用方取消在本地与该预检存在竞态，但无法强制任意凭据后端自行停止工作。
 - **超量返回的源仍消耗 token**：协议没有结果数量旋钮，`maxResults` 只能由 seam 在事后截断。
 - **未引用的结果没有 `snippet`**：只有 `text` 块中的引用（`cited_text`）匹配其 URL 时，源才会获得 snippet。
diff --git a/packages/web/web/README.i18n.yaml b/packages/web/web/README.i18n.yaml
index fe4c307b3b..b6c139d63c 100644
--- a/packages/web/web/README.i18n.yaml
+++ b/packages/web/web/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/web/web/README.md
 README.md: 73765fe060cc0a2b0fa3d69703a670f488a29ac9
-README.zh.md: 3cce0fb528457b566b2c2ab4ffd1f29471255c07
+README.zh.md: bebdb52d6c9bd33db5a982c1f278e71c1882f2de
diff --git a/packages/web/web/README.zh.md b/packages/web/web/README.zh.md
index 3cce0fb528..bebdb52d6c 100644
--- a/packages/web/web/README.zh.md
+++ b/packages/web/web/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**web 访问 seam**：抽象 `WebService`（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型契约绑定到某个厂商的 API 形状。
+**web 访问 seam**：抽象 `WebService`（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型约定绑定到某个厂商的 API 形状。
 
 该包是 web 能力中负责接口的三分之一。与 bash/fs 不同，它在一个 seam 上跨越搜索与抓取两种能力，每种能力都可能有多个提供方：
 
@@ -43,7 +43,7 @@
 
 ## 词汇
 
-`WebSearchRequest`（`query`、`maxResults?`）→ `WebSearchResult`（`content?`、`sources[]`、`truncated`）；每个 `WebSearchSource` 都有必填 `url` 与可选 `title`／`snippet`／`publishedAt`（Perplexity 引用可能只含 URL）。`WebFetchRequest`（`url`）→ `WebFetchResult`（最终 `url`、`statusCode`、`body`、`truncated`）；取消作为可选的直接 `AbortSignal` 参数传给 `search()`／`fetch()`。`WebFetchBody` 是这里拥有的封闭判别联合（`html` | `text`）；消费方使用 `switch` 实现穷尽检查，因此新增类型会导致编译失败，直到处理完毕。完整契约见 `src/types.ts`，其中也包含 `WebError` code 分类体系。
+`WebSearchRequest`（`query`、`maxResults?`）→ `WebSearchResult`（`content?`、`sources[]`、`truncated`）；每个 `WebSearchSource` 都有必填 `url` 与可选 `title`／`snippet`／`publishedAt`（Perplexity 引用可能只含 URL）。`WebFetchRequest`（`url`）→ `WebFetchResult`（最终 `url`、`statusCode`、`body`、`truncated`）；取消作为可选的直接 `AbortSignal` 参数传给 `search()`／`fetch()`。`WebFetchBody` 是这里拥有的封闭判别联合（`html` | `text`）；消费方使用 `switch` 实现穷尽检查，因此新增类型会导致编译失败，直到处理完毕。完整约定见 `src/types.ts`，其中也包含 `WebError` code 分类体系。
 
 ## 模型体验
 
diff --git a/packages/workflow/README.i18n.yaml b/packages/workflow/README.i18n.yaml
index 1d87cec1bf..05ad673c61 100644
--- a/packages/workflow/README.i18n.yaml
+++ b/packages/workflow/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/README.md
 README.md: 7b19cfd37f9b6870825d5e0761aed92908206b3a
-README.zh.md: 8460e22347a6c24b84f12f641479edb78bf1ed1e
+README.zh.md: 33b3f26780da1bf4efcd78242b2cfb212cef4c22
diff --git a/packages/workflow/README.zh.md b/packages/workflow/README.zh.md
index 8460e22347..33b3f26780 100644
--- a/packages/workflow/README.zh.md
+++ b/packages/workflow/README.zh.md
@@ -1,4 +1,4 @@
-# workflow/：动态工作流能力族
+# workflow/：动态工作流能力家族
 
 [English](README.md) | 中文
 
@@ -11,6 +11,6 @@
 | [`tool-workflow/`](tool-workflow/README.md) | 向模型公开通用工作流执行 | 注册到 `ctx.tools` |
 | [`tool-ralph/`](tool-ralph/README.md) | 公开使用全新 agent（智能体）的固定 Ralph 工作流 | 注册到 `ctx.tools` |
 
-worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见 [动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) 和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) 决策。
+worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)决策。
 
-子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见 [动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
+子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
diff --git a/packages/workflow/tool-ralph/README.i18n.yaml b/packages/workflow/tool-ralph/README.i18n.yaml
index 6c560978cb..019495cdfb 100644
--- a/packages/workflow/tool-ralph/README.i18n.yaml
+++ b/packages/workflow/tool-ralph/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/tool-ralph/README.md
 README.md: daf242364d1093cff30cd1dc95823e1ecb89a9c7
-README.zh.md: c855c6b5f42728f67935208b44601b379364aa7f
+README.zh.md: 92c3256188d9b4c38a292ba7697f702dc46db737
diff --git a/packages/workflow/tool-ralph/README.zh.md b/packages/workflow/tool-ralph/README.zh.md
index c855c6b5f4..92c3256188 100644
--- a/packages/workflow/tool-ralph/README.zh.md
+++ b/packages/workflow/tool-ralph/README.zh.md
@@ -4,7 +4,7 @@
 
 面向模型的 `ralph` 工具运行固定的前台工作流，把一个不可变目标依次交给多个全新子 agent（智能体）。它展示如何把专用编排策略实现为基于 [`ctx.workflows`](../workflow/README.md) 和 [`ctx.subagents`](../../subagent/subagent/README.md) 的普通插件：不会向 `agent-loop` 添加 Ralph 模式或全新 agent loop（智能体循环），同会话的[目标领域](../../goal/goal/README.md)也保持独立。策略和暂缓事项由 [Ralph Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)负责。
 
-## 契约
+## 约定
 
 `ralph({ objective, maxRounds? })` 会等待整个运行完成。部署配置中的 `maxRounds` 既是默认值，也是调用覆盖值的上限。每个 Ralph Round 通过 `subagentProvider` 启动一个子 agent；该提供方必须存在、支持结构化输出，并报告 `inheritsParentContext: false`。已配置的提供方以 `WorkflowStartRequest.subagentProvider` 传递，使固定脚本无法检查或更改路由，普通的模型编写 `workflow` 工具也不会因此获得提供方选择器。解析后的 Round 上限还会作为 `WorkflowStartRequest.maxTotalAgents` 传递，使固定循环与引擎的子 agent 总数后备上限协同；Ralph 上限超过引擎部署上限时，引擎会在发布运行前拒绝。
 
@@ -73,7 +73,7 @@ Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop o
 
 #### 模型看到的内容
 
-每个子 agent 都会看到独立的固定 Round 提示词和结构化输出捕获契约。父级只看到原始调用和一个终态结果，其中包含 worker 报告的状态、Round 数量及经过美化打印的最终报告；中间子 agent 消息和报告不会进入父级对话。普通子 agent 失败时会改为产生错误，其中包含对应 Round 编号；从第二个 Round 起，还会包含上一次成功交接。
+每个子 agent 都会看到独立的固定 Round 提示词和结构化输出捕获约定。父级只看到原始调用和一个终态结果，其中包含 worker 报告的状态、Round 数量及经过美化打印的最终报告；中间子 agent 消息和报告不会进入父级对话。普通子 agent 失败时会改为产生错误，其中包含对应 Round 编号；从第二个 Round 起，还会包含上一次成功交接。
 
 #### Token 影响
 
diff --git a/packages/workflow/tool-workflow/README.i18n.yaml b/packages/workflow/tool-workflow/README.i18n.yaml
index 3c104614bc..66212b2fb9 100644
--- a/packages/workflow/tool-workflow/README.i18n.yaml
+++ b/packages/workflow/tool-workflow/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/tool-workflow/README.md
 README.md: 5afa68764bfe339377954f8912b6f9b795435be1
-README.zh.md: 9af11811c9a91562983dcd865a0cb1a626cdac3c
+README.zh.md: 7f18c6f54332e11ea54a927ef2d7b723c2601c05
diff --git a/packages/workflow/tool-workflow/README.zh.md b/packages/workflow/tool-workflow/README.zh.md
index 9af11811c9..7f18c6f543 100644
--- a/packages/workflow/tool-workflow/README.zh.md
+++ b/packages/workflow/tool-workflow/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 模型看到的内容
 
-工具有三个参数：`meta`（必需的身份数据：`name`、`description` 和可选的进度注解）、`script`（必需的纯 JavaScript 脚本体，不含 `export const meta` 语句；工具描述包含完整的编写契约）以及 `args`（可选 JSON 对象，作为全局变量 `args` 向脚本公开；裸列表应包装到字段中，使协议 schema 如实表达形态）。插件还会贡献一个 `tool:<toolName>` 系统提示词段，其中包含使用策略：只有用户明确要求工作流／大型编排时才使用该工具；一两项委派优先使用普通 subagent 调用。这遵循工具指导随工具插件交付、绝不放入部署 persona 的约定。
+工具有三个参数：`meta`（必需的身份数据：`name`、`description` 和可选的进度注解）、`script`（必需的纯 JavaScript 脚本体，不含 `export const meta` 语句；工具描述包含完整的编写约定）以及 `args`（可选 JSON 对象，作为全局变量 `args` 向脚本公开；裸列表应包装到字段中，使协议 schema 如实表达形态）。插件还会贡献一个 `tool:<toolName>` 系统提示词段，其中包含使用策略：只有用户明确要求工作流／大型编排时才使用该工具；一两项委派优先使用普通 subagent 调用。这遵循工具指导随工具插件交付、绝不放入部署 persona 的约定。
 
 ## 生命周期
 
@@ -49,7 +49,7 @@ Use the <toolName> tool ONLY when the user explicitly asks for a workflow or for
 
 #### 模型看到的内容
 
-工具可见时，已生成的默认 [`workflow` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-workflow) 包含完整的 JavaScript 钩子与元数据契约；`toolName` 可以重命名该定义，模型会提交脚本、元数据和可选 args。
+工具可见时，已生成的默认 [`workflow` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-workflow) 包含完整的 JavaScript 钩子与元数据约定；`toolName` 可以重命名该定义，模型会提交脚本、元数据和可选 args。
 
 #### Token 影响
 
diff --git a/packages/workflow/workflow-workerthread/README.i18n.yaml b/packages/workflow/workflow-workerthread/README.i18n.yaml
index b677e2e9e6..c67a1f9630 100644
--- a/packages/workflow/workflow-workerthread/README.i18n.yaml
+++ b/packages/workflow/workflow-workerthread/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/workflow-workerthread/README.md
 README.md: 9da420bdd67ac5b0a4bfffa312c6fe7b2dabf8f5
-README.zh.md: caba1cf5284c1586fe17e00ed4115ff12e3e4ae9
+README.zh.md: dbed654508bf38bd369247c411d3e8d3a1a749a5
diff --git a/packages/workflow/workflow-workerthread/README.zh.md b/packages/workflow/workflow-workerthread/README.zh.md
index caba1cf528..dbed654508 100644
--- a/packages/workflow/workflow-workerthread/README.zh.md
+++ b/packages/workflow/workflow-workerthread/README.zh.md
@@ -21,7 +21,7 @@ worker 仍提供实用的隔离：
 
 真正的不可信脚本沙箱需要在同一工作流 seam 背后采用不同引擎。
 
-## 脚本契约
+## 脚本约定
 
 工作流的 `meta` 是宿主提供的数据，而不是待求值的脚本文本。引擎会校验必需的 `name` 和 `description`、拒绝未知字段，并在返回运行前检查脚本正文能否解析。
 
diff --git a/packages/workflow/workflow/README.i18n.yaml b/packages/workflow/workflow/README.i18n.yaml
index ac1d7c0506..e56067bf2d 100644
--- a/packages/workflow/workflow/README.i18n.yaml
+++ b/packages/workflow/workflow/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/workflow/README.md
 README.md: 0de661423206cc71eb4669bc8ddb2419202bcb4a
-README.zh.md: da11b59aa285ea8f4e0e8c18ceab8922d706491a
+README.zh.md: 62abd00c013d054f4111a2db2ce72c58d3514087
diff --git a/packages/workflow/workflow/README.zh.md b/packages/workflow/workflow/README.zh.md
index da11b59aa2..62abd00c01 100644
--- a/packages/workflow/workflow/README.zh.md
+++ b/packages/workflow/workflow/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-工作流 seam（`ctx.workflows`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件契约；引擎负责决定如何隔离并执行脚本。
+工作流 seam（`ctx.workflows`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件约定；引擎负责决定如何隔离并执行脚本。
 
 `@deepseek-ai/dsh-workflow-workerthread` 是当前引擎，`@deepseek-ai/dsh-tool-workflow` 是面向模型的消费方。未来的进程或沙箱引擎可以替换实现，而无需更改工具。
 
-## 服务与运行契约
+## 服务与运行约定
 
 `WorkflowService.start(request): WorkflowRun` 会同步完成足够多的校验，在运行创建前拒绝格式错误的 meta 块、无法解析的脚本、不可用的提供方路由或不受支持的单次运行限制。返回后，`WorkflowRun.result` 绝不拒绝：执行失败以 `stopReason: 'error'` 兑现，取消则在引擎有限的宽限时间内以 `cancelled` 兑现。
 
@@ -31,7 +31,7 @@
 `WorkflowError` 携带一个代码和 `fatal` 标志。致命错误总会逸出 `parallel()` 和 `pipeline()`，而不会变成普通的逐项 `null`：
 
 - `SCRIPT_PARSE` / `META_INVALID`：工作流无法启动；
-- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎契约；
+- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎约定；
 - `AGENT_CAP` / `ITEM_CAP`：超过已配置的安全上限；
 - `AGENT_START`：提供方的异步启动调用被拒绝；
 - `AGENT_RESULT`：已发布子 agent 的结果因基础设施故障而被拒绝；
diff --git a/packages/workspace/README.i18n.yaml b/packages/workspace/README.i18n.yaml
index 427a7aac69..c7723f6c56 100644
--- a/packages/workspace/README.i18n.yaml
+++ b/packages/workspace/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workspace/README.md
 README.md: 7e30f26a9854031b4907ad3e7edb35da5986d5d9
-README.zh.md: e59f54ad3d22201304a8126e0b0fbcab79fd17a7
+README.zh.md: 6315ccb6b3a8b86161728e8296746efd0c334a29
diff --git a/packages/workspace/README.zh.md b/packages/workspace/README.zh.md
index e59f54ad3d..6315ccb6b3 100644
--- a/packages/workspace/README.zh.md
+++ b/packages/workspace/README.zh.md
@@ -8,6 +8,6 @@
 |---|---|---|
 | [`workspace/`](workspace/README.md) | 注册 workspace 并记录其会话归属 | `ctx.workspace` |
 
-[workspace 包参考](workspace/README.md) 负责生命周期、持久化和删除语义。
+[workspace 包参考](workspace/README.md)负责生命周期、持久化和删除语义。
 
 子系统参考——实体、realpath 规范、注册/解析——见 [docs/subsystems/workspace.md](../../docs/subsystems/workspace.md)；存储设计见 [domain KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 137315cf39..f25007786c 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 契约 | | | 如：`pairing contract` →`配对契约` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",
@@ -12,7 +12,7 @@
       },
       {
         "role": "assistant",
-        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
+        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）约定](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
       },
       {
         "role": "user",
@@ -20,7 +20,7 @@
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成约定构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 约定 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
@@ -28,7 +28,7 @@
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对契约、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对契约\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份契约：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分契约由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对约定\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
       },
       {
         "role": "user",
@@ -44,7 +44,7 @@
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
       },
       {
         "role": "user",

From b995b12261d6825253eef2b18bea87c9ead9c912 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:14:51 +0800
Subject: [PATCH 432/516] test(fixtures): add private GitHub repository Plugin

---
 .../.dsh-plugin/package.json                        | 13 +++++++++++++
 .../skills/github-source-proof/SKILL.md             |  6 ++++++
 2 files changed, 19 insertions(+)
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/skills/github-source-proof/SKILL.md

diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
new file mode 100644
index 0000000000..e8723f671a
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "dsh-github-repository-plugin-e2e-fixture",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "prepare": "dsh-plugin-prepare"
+  },
+  "dsh": {
+    "skills": [
+      "../skills"
+    ]
+  }
+}
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/skills/github-source-proof/SKILL.md b/apps/cli/tests/fixtures/github-repository-plugin/skills/github-source-proof/SKILL.md
new file mode 100644
index 0000000000..eae668a4f9
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/skills/github-source-proof/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: github-source-proof
+description: Proves that dsh installed a private repository Plugin from an exact GitHub source.
+---
+
+This skill exists only in the GitHub repository source fixture.

From da2179dd2b034b28fb0fbed52b95628dff51641a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:24:45 +0800
Subject: [PATCH 433/516] test(fixtures): prepare repository Plugin at prepack

---
 .../fixtures/github-repository-plugin/.dsh-plugin/package.json  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
index e8723f671a..9ce1527d03 100644
--- a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "prepare": "dsh-plugin-prepare"
+    "prepack": "dsh-plugin-prepare"
   },
   "dsh": {
     "skills": [

From b91b1fdefe2baa6f76530f7b90f34307efc53e1f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:46:56 +0800
Subject: [PATCH 434/516] fix(repository-plugin): make GitHub source
 preparation self-contained

---
 ...-static-repository-plugin-format.i18n.yaml |  4 +-
 ...6-07-30-static-repository-plugin-format.md |  4 +-
 ...7-30-static-repository-plugin-format.zh.md |  4 +-
 ...it-repository-plugin-preparation.i18n.yaml |  6 ++
 ...owned-git-repository-plugin-preparation.md | 42 +++++++++
 ...ed-git-repository-plugin-preparation.zh.md | 42 +++++++++
 .github/workflows/ci.yml                      |  2 +
 .../github-repository-plugin.built.e2e.ts     | 89 +++++++++++++++++++
 .../app-boot/tests/repository-cache.spec.ts   | 46 ++++++----
 .../repository-plugin/README.i18n.yaml        |  4 +-
 .../repository-plugin/README.md               |  9 +-
 .../repository-plugin/README.zh.md            |  9 +-
 .../repository-plugin/src/format.ts           |  7 +-
 .../repository-plugin/src/index.ts            | 33 ++++---
 .../repository-plugin/src/source.ts           | 79 +++++++++++++++-
 .../tests/repository-plugin.spec.ts           | 64 ++++++++++++-
 scripts/run-gates.spec.ts                     | 22 ++++-
 scripts/run-gates.ts                          | 15 ++++
 vendor/README.md                              |  2 +-
 vendor/loader/src/repository.ts               | 35 ++++++--
 20 files changed, 454 insertions(+), 64 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
 create mode 100644 apps/cli/tests/github-repository-plugin.built.e2e.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 6319b99fb2..40a0461378 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.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 .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
-2026-07-30-static-repository-plugin-format.md: c9d755b925a6ea05eed71e75803397d2672df9f4
-2026-07-30-static-repository-plugin-format.zh.md: 361de64d2e98b9fb4ac42963e4ae48e77fbc7016
+2026-07-30-static-repository-plugin-format.md: 4823495dabee2101713ac72c8d0cee5bcc6b38d1
+2026-07-30-static-repository-plugin-format.zh.md: e5817ca982a71a609c86c5835b803b12f1317e1a
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
index c9d755b925..4823495dab 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
@@ -14,7 +14,7 @@ The [package-manager-native repository cache](2026-07-30-package-manager-native-
 
 `@deepseek-ai/dsh-repository-plugin` owns a restricted `.dsh-plugin` package format with two contribution kinds only: skill roots and one common `.mcp.json`. Its package metadata uses `package.json#dsh.skills` for relative skill-root paths and `package.json#dsh.mcpServers` for the relative MCP document path. At least one is required. Each path may leave `.dsh-plugin` to reuse repository content but must remain beneath the directory containing that `.dsh-plugin`; a nested selectable Plugin therefore owns the adjacent subtree above its package without gaining access to unrelated host paths.
 
-The `.dsh-plugin` package declares `dsh-plugin-prepare` as its ordinary package-manager `prepare` script. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. The `.mjs` extension avoids imposing `type: module` on repository-authored package metadata. The generated module is a fixed import-free template containing only a normalized manifest, an `inject` list derived from it (`loader`, plus `skills` and/or `tools` per the declared capabilities, so the wrapper fiber gates on the services its children need), and delegation to the `dsh-repository-plugin` Loader builtin. Preparation never discovers, transpiles, bundles, or preserves a custom repository entry point.
+The `.dsh-plugin` package declares exact `scripts.prepack: "dsh-plugin-prepare"` metadata without depending on a DSH npm package. During Git installation, the standalone runtime temporarily supplies that command from its own build on the isolated lifecycle `PATH`; `prepack` runs after dependency installation and before pnpm packs a selected subdirectory, including a Plugin nested inside another package-manager workspace. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`; the source loader revalidates the installed package's exact lifecycle metadata before importing that wrapper. The `.mjs` extension avoids imposing `type: module` on repository-authored package metadata. The generated module is a fixed import-free template containing only a normalized manifest, an `inject` list derived from it (`loader`, plus `skills` and/or `tools` per the declared capabilities, so the wrapper fiber gates on the services its children need), and delegation to the `dsh-repository-plugin` Loader builtin. Preparation never discovers, transpiles, bundles, or preserves a custom repository entry point. The host-owned command rationale is in the [Git source preparation repair](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
 
 Loading the DSH package registers that builtin as an effect. A generated wrapper mounts the builtin as its child with `import.meta.url`, so all contributions belong to the wrapper fiber and disappear on Loader removal or rollback. The builtin revalidates the prepared manifest and path containment before reading assets. It composes the existing implementations rather than registering skills or MCP tools itself.
 
@@ -46,4 +46,4 @@ Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `C
 
 ## Testing
 
-Focused tests prepare skills and MCP metadata, prove the emitted wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The keyless headless example loads a checked-in prepared wrapper through its real `cordis.yml` and snapshots the repository skill's logged model catalog row.
+Focused tests prepare skills and MCP metadata, prove the emitted wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The CI built-entry acceptance invokes `dsh run` with a GitHub source pinned to the pull request head, lets bundled pnpm fetch and prepare a private dependency-free fixture, then observes the copied skill in the real model request and the prepared wrapper in the immutable cache.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index 361de64d2e..e5817ca982 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -14,7 +14,7 @@
 
 `@deepseek-ai/dsh-repository-plugin` 负责一个受限的 `.dsh-plugin` package 格式，且只允许两类贡献：skill 根和一个通用 `.mcp.json`。Package metadata 使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径；两者至少需要一个。路径可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的 Plugin 可以拥有其 package 上方相邻的子树，却不能访问无关宿主路径。
 
-`.dsh-plugin` package 把 `dsh-plugin-prepare` 声明为普通 package-manager `prepare` 脚本。Helper 会校验 metadata 与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。`.mjs` 扩展名避免强迫仓库作者在 package metadata 中设置 `type: module`。生成模块来自固定、无 import 的模板，只包含规范化 manifest、由 manifest 派生的 `inject` 列表（`loader`，加上按声明能力加入的 `skills`／`tools`，使包装 fiber 在其子插件所需服务上门控），以及对 `dsh-repository-plugin` Loader builtin 的委托。准备阶段永远不会发现、转译、打包或保留自定义仓库入口。
+`.dsh-plugin` 包声明精确的 `scripts.prepack: "dsh-plugin-prepare"` 元数据，且不依赖 DSH NPM 包。在 Git 安装期间，独立运行时会从自身构建产物中临时提供该命令，并将其放入隔离的生命周期 `PATH`；`prepack` 会在依赖安装后、pnpm 打包选定子目录前运行，即使插件嵌套在另一个包管理器工作区内也不例外。该辅助程序会校验元数据与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`；源码 loader 会在导入该包装层前重新校验已安装包的精确生命周期元数据。`.mjs` 扩展名避免强迫仓库作者在包元数据中设置 `type: module`。生成模块来自固定、无 import 的模板，只包含规范化 manifest、由 manifest 派生的 `inject` 列表（`loader`，加上按声明能力加入的 `skills`／`tools`，使包装 fiber 在其子插件所需服务上门控），以及对 `dsh-repository-plugin` Loader builtin 的委托。准备阶段永远不会发现、转译、打包或保留自定义仓库入口。宿主自有命令的设计依据见[Git 源准备修复](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
 
 加载 DSH package 会以 effect 方式注册该 builtin。生成的包装模块使用 `import.meta.url` 把 builtin 挂载为自己的子级，因此所有贡献都归属于包装 fiber，并在 Loader 移除或回滚时消失。Builtin 会在读取资源前重新校验已准备 manifest 与路径包含关系。它只组合现有实现，而不自行注册 skills 或 MCP 工具。
 
@@ -46,4 +46,4 @@
 
 ## 测试
 
-聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。Keyless headless 示例通过真实 `cordis.yml` 加载一份签入的已准备包装模块，并快照 repository skill 写入日志的模型目录行。
+聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。CI 的构建入口验收会用锁定到 PR（Pull Request）head 的 GitHub 源调用 `dsh run`，让随附 pnpm 获取并准备一个私有且不含依赖的 fixture（测试前置数据），然后在真实模型请求中观察已复制的 skill，并在不可变缓存中观察已准备的包装模块。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
new file mode 100644
index 0000000000..55d9045506
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.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-08-08-host-owned-git-repository-plugin-preparation.md
+2026-08-08-host-owned-git-repository-plugin-preparation.md: 45e84f9c8a89bb9d1eb7e4521634d16789dea2f0
+2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: ba88d5bb351427118d55c357209b496b39c2eb98
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
new file mode 100644
index 0000000000..45e84f9c8a
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
@@ -0,0 +1,42 @@
+# Agent Note: Host-owned preparation makes GitHub repository Plugins installable
+
+Status: implemented
+
+English | [中文](2026-08-08-host-owned-git-repository-plugin-preparation.zh.md)
+
+## Problem
+
+The repository Plugin authoring contract depended on `scripts.prepare: "dsh-plugin-prepare"` and told source repositories to add `@deepseek-ai/dsh-repository-plugin` as a development dependency. That package is private and not published to npm, so an otherwise valid external GitHub repository could not obtain the helper in a clean install.
+
+The lifecycle choice also failed for a selectable `.dsh-plugin` inside a pnpm workspace. pnpm prepares a Git-hosted package by running the repository's preferred package manager before packing the selected subdirectory. A nested `pnpm install` joins the containing workspace and need not execute the unlisted `.dsh-plugin` package's `prepare` script. The install could therefore succeed and publish a cache generation containing only the source package metadata; real DSH startup failed later because `dsh-plugin.mjs` did not exist.
+
+The checked-in headless fixture did not catch either defect because it mounted an already prepared wrapper. It proved runtime composition, not GitHub acquisition or package preparation.
+
+## Decision
+
+The fixed authoring format now requires exact `scripts.prepack: "dsh-plugin-prepare"` metadata and no DSH dependency. pnpm's Git-hosted package preparation invokes `prepack` explicitly after its dependency-install step and before packlist selects the `.dsh-plugin` subtree, so the helper can still copy sibling repository assets such as `../skills` into the package.
+
+`@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. The command directory exists only for the installation transaction and is removed on success or failure. The repository remains trusted package-manager input: DSH supplies one command, but other lifecycle scripts and dependencies still execute under the existing trust contract.
+
+The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true`, dependency-free GitHub fixture. It requires the run to reach the mock LLM, finds the repository skill description in the actual model request, and verifies the generated wrapper and copied skill under the immutable DSH cache. The test fails if CI omits the exact source instead of silently skipping.
+
+## Alternatives considered
+
+**Publish the prepare helper to npm.** Rejected because the source package would acquire a release/version dependency solely to call code already owned by the running DSH installation, and the existing helper is intentionally private.
+
+**Keep `prepare` and only inject the command.** Rejected because command availability does not make a nested package's `prepare` lifecycle run when the Git repository's package manager treats it as part of another workspace.
+
+**Prepare after RepositoryCache installs the selected package.** Rejected because pnpm's packed subdirectory no longer contains sibling source assets referenced by paths such as `../skills`; preparation must happen before packlist.
+
+**Clone GitHub repositories in DSH and bypass pnpm's Git fetcher.** Rejected because it would duplicate ref resolution, subdirectory selection, dependency installation, packlist behavior, and cache integrity already owned by the pinned package manager.
+
+## Consequences
+
+- A repository author can commit the fixed `.dsh-plugin/package.json` and source assets to GitHub without publishing either the Plugin or its preparation helper to npm.
+- `prepack`, not `prepare`, is part of the pre-release authoring format. Invalid lifecycle metadata fails during source preparation or installed-package validation instead of producing an ambiguous partial format.
+- Exact source strings still identify immutable cache generations; a changed ref or source configuration selects another generation.
+- This repair does not expand the contribution surface: prepared repository Plugins still contribute only declared skills and common MCP definitions, while arbitrary package lifecycle code remains trusted installation code rather than a model-facing Cordis Plugin API.
+
+## Testing
+
+`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins the exact `prepack` metadata and temporary command cleanup. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact live GitHub source, actual built `dsh run`, real headless composition, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
new file mode 100644
index 0000000000..ba88d5bb35
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
@@ -0,0 +1,42 @@
+# Agent Note: 宿主自有的准备机制使 GitHub repository 插件可安装
+
+状态：已实现
+
+[English](2026-08-08-host-owned-git-repository-plugin-preparation.md) | 中文
+
+## 问题
+
+repository 插件的创作契约依赖 `scripts.prepare: "dsh-plugin-prepare"`，并要求源码仓库将 `@deepseek-ai/dsh-repository-plugin` 添加为开发依赖。该包是私有包，且未发布到 NPM，因此即使外部 GitHub 仓库符合其他要求，也无法在全新安装中取得该辅助程序。
+
+这种生命周期选择也无法支持 pnpm 工作区内可选的 `.dsh-plugin`。pnpm 会先运行 Git 托管仓库首选的包管理器，再打包选定的子目录，从而准备 Git 托管包。嵌套执行的 `pnpm install` 会加入外层工作区，而不一定执行未列入其中的 `.dsh-plugin` 包的 `prepare` 脚本。因此，安装可能成功并发布一个仅包含源包元数据的缓存 generation；随后真实 DSH 启动因 `dsh-plugin.mjs` 不存在而失败。
+
+签入仓库的 headless fixture（测试前置数据）没有捕获任一缺陷，因为它挂载的是已准备好的包装层。它证明的是运行时组合，而不是 GitHub 获取或包准备。
+
+## 决策
+
+修复后的创作格式要求元数据中精确包含 `scripts.prepack: "dsh-plugin-prepare"`，且不包含 DSH 依赖。pnpm 针对 Git 托管包的准备流程会在依赖安装步骤之后、打包清单选择 `.dsh-plugin` 子树之前显式调用 `prepack`，因此辅助程序仍可将 `../skills` 等同仓库的相邻资源复制进包内。
+
+`@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。该命令目录仅存在于安装事务期间，无论成功还是失败都会被移除。仓库仍是受信任的包管理器输入：DSH 仅提供这一条命令，其他生命周期脚本和依赖仍会按既有信任契约执行。
+
+Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true`、不含依赖的 GitHub fixture。验收要求该次运行到达 mock LLM（大语言模型），在实际模型请求中找到 repository skill 描述，并验证不可变 DSH 缓存中的生成包装层和已复制 skill。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
+
+## 考虑过的替代方案
+
+**把准备辅助程序发布到 NPM。** 拒绝，因为源包会仅为了调用当前运行的 DSH 安装本就拥有的代码，而增加一个需要发布和管理版本的依赖；现有辅助程序又有意保持私有。
+
+**保留 `prepare`，只注入命令。** 拒绝，因为当 Git 仓库的包管理器把嵌套包当作另一工作区的一部分时，即使命令可用，也不会使嵌套包的 `prepare` 生命周期得以运行。
+
+**在 RepositoryCache 安装选定包后再准备。** 拒绝，因为 pnpm 打包后的子目录不再包含 `../skills` 等路径所引用的同仓库相邻资源；准备必须在生成打包清单前完成。
+
+**在 DSH 中克隆 GitHub 仓库，并绕过 pnpm 的 Git 获取器。** 拒绝，因为这会重复实现已由锁定版本的包管理器负责的 ref 解析、子目录选择、依赖安装、打包清单行为和缓存完整性。
+
+## 后果
+
+- 仓库作者可以把修复后的 `.dsh-plugin/package.json` 和源资源提交到 GitHub，而无需把插件或其准备辅助程序发布到 NPM。
+- 预发布创作格式使用 `prepack` 而不是 `prepare`。无效的生命周期元数据会在源码准备或已安装包校验阶段导致失败，而不会留下状态不明的半成品格式。
+- 精确源字符串仍标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
+- 本次修复不扩大贡献范围：已准备的 repository 插件仍只贡献已声明的 skills 和通用 MCP 定义，而任意包生命周期代码仍是受信任的安装代码，不是面向模型的 Cordis 插件 API。
+
+## 测试
+
+`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定精确的 `prepack` 元数据和临时命令清理行为。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确的真实 GitHub 源、实际构建产物的 `dsh run`、真实 headless 组合、mock LLM 请求观测，以及对已准备缓存的检查。
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 46ab8e892f..5324df431e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -175,6 +175,8 @@ jobs:
       DSH_NODE_COMPAT_SKIP_TYPECHECK: '1'
       DSH_OXLINT_THREADS: '8'
       DSH_PUBLINT_CONCURRENCY: '8'
+      DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE: >-
+        github:${{ github.event.pull_request.head.repo.full_name }}#${{ github.event.pull_request.head.sha }}&path:/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin
       # Failover halves snapshot concurrency for the shared 64-core VM.
       DSH_SNAPSHOT_MAX_CONCURRENCY: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '12' || '32' }}
     steps:
diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
new file mode 100644
index 0000000000..7262ddeb58
--- /dev/null
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -0,0 +1,89 @@
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { startMockLlmServer } from '@deepseek-ai/dsh-llm-mock-server'
+import { execa } from 'execa'
+import { describe, expect, it } from 'vitest'
+
+const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
+const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')
+const source = process.env.DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE
+const required = process.env.DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E === '1'
+const enabled = required || source !== undefined
+
+describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () => {
+  it('installs a private exact GitHub source and exposes its skill to the model', async () => {
+    expect(existsSync(dshBin), 'the repository Plugin acceptance must run the built dsh entry').toBe(true)
+    expect(source, 'DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE is required by this CI lane').toMatch(
+      /^github:[^/\s#&]+\/[^/\s#&]+#[0-9a-f]{40}&path:\/.*\/\.dsh-plugin$/u,
+    )
+
+    const apiKey = 'github-repository-plugin-e2e-key'
+    const server = await startMockLlmServer({
+      sequence: ['success'],
+      apiKey,
+      successText: 'private GitHub repository Plugin reached dsh run',
+    })
+    const home = mkdtempSync(join(tmpdir(), 'dsh-github-repository-plugin-'))
+    const patch = join(home, 'github-repository-plugin.cordis.patch.yml')
+    writeFileSync(patch, [
+      '- id: repository-plugins',
+      '  config:',
+      '    repositories:',
+      `      - ${JSON.stringify(source)}`,
+      '',
+    ].join('\n'))
+
+    try {
+      const result = await execa(process.execPath, [
+        dshBin,
+        'run',
+        '--patch',
+        patch,
+        'prove the private GitHub repository Plugin is active',
+      ], {
+        cwd: repoRoot,
+        input: '',
+        timeout: 120_000,
+        killSignal: 'SIGKILL',
+        reject: false,
+        env: {
+          ...process.env,
+          DSH_HOME: home,
+          DSH_TELEMETRY_DISABLED: '1',
+          DEEPSEEK_API_KEY: apiKey,
+          DEEPSEEK_BASE_URL: server.baseURL,
+        },
+      })
+      if (result.timedOut) {
+        throw new Error(`dsh GitHub repository Plugin run did not exit within 120s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
+      }
+      expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}`).toBe(0)
+      expect(result.stdout).toBe('private GitHub repository Plugin reached dsh run')
+      expect(server.requests.length).toBeGreaterThan(0)
+      expect(JSON.stringify(server.requests.map(request => request.body))).toContain(
+        'Proves that dsh installed a private repository Plugin from an exact GitHub source.',
+      )
+
+      const cacheRoot = join(home, 'cache', 'repository-plugins')
+      const generations = readdirSync(cacheRoot, { withFileTypes: true }).filter(entry => entry.isDirectory())
+      expect(generations).toHaveLength(1)
+      const installed = join(cacheRoot, generations[0]!.name, 'node_modules', 'repository')
+      const manifest = JSON.parse(readFileSync(join(installed, 'package.json'), 'utf8')) as Record<string, unknown>
+      expect(manifest).toMatchObject({
+        name: 'dsh-github-repository-plugin-e2e-fixture',
+        private: true,
+        scripts: { prepack: 'dsh-plugin-prepare' },
+      })
+      expect(manifest).not.toHaveProperty('dependencies')
+      expect(manifest).not.toHaveProperty('devDependencies')
+      expect(readFileSync(join(installed, 'dsh-plugin-assets/skills/0/github-source-proof/SKILL.md'), 'utf8'))
+        .toContain('This skill exists only in the GitHub repository source fixture.')
+      expect(readFileSync(join(installed, 'dsh-plugin.mjs'), 'utf8')).toContain('dsh-repository-plugin')
+    } finally {
+      await server.close()
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, 130_000)
+})
diff --git a/packages/boot/app-boot/tests/repository-cache.spec.ts b/packages/boot/app-boot/tests/repository-cache.spec.ts
index b7d80470b8..186cbe1b43 100644
--- a/packages/boot/app-boot/tests/repository-cache.spec.ts
+++ b/packages/boot/app-boot/tests/repository-cache.spec.ts
@@ -36,14 +36,14 @@ describe('RepositoryCache', () => {
       calls.push(directory)
       await fakePackage(directory)
     }
-    const cache = new RepositoryCache(root, install)
+    const cache = new RepositoryCache(root, { install })
     const specifier = 'github:owner/repository#0123456789abcdef'
 
     const [first, concurrent] = await Promise.all([cache.resolve(specifier), cache.resolve(specifier)])
     expect(concurrent).toBe(first)
     expect(calls).toHaveLength(1)
 
-    const reopened = new RepositoryCache(root, async () => { throw new Error('cache miss') })
+    const reopened = new RepositoryCache(root, { install: async () => { throw new Error('cache miss') } })
     expect(await reopened.resolve(specifier)).toBe(first)
     expect(JSON.parse(await readFile(join(first, '..', '..', 'package.json'), 'utf8'))).toMatchObject({
       packageManager: `pnpm@${BUNDLED_PNPM_VERSION}`,
@@ -68,8 +68,8 @@ describe('RepositoryCache', () => {
     const specifier = 'github:owner/repository#race'
 
     const [first, second] = await Promise.all([
-      new RepositoryCache(root, install).resolve(specifier),
-      new RepositoryCache(root, install).resolve(specifier),
+      new RepositoryCache(root, { install }).resolve(specifier),
+      new RepositoryCache(root, { install }).resolve(specifier),
     ])
 
     expect(second).toBe(first)
@@ -80,11 +80,11 @@ describe('RepositoryCache', () => {
   it('removes a failed staging tree and permits an exact retry', async () => {
     const root = await temporaryRoot('repository-retry')
     let attempts = 0
-    const cache = new RepositoryCache(root, async (directory) => {
+    const cache = new RepositoryCache(root, { install: async (directory) => {
       attempts += 1
       if (attempts === 1) throw new Error('install failed')
       await fakePackage(directory)
-    })
+    } })
 
     await expect(cache.resolve('github:owner/repository#ref')).rejects.toThrow('failed to prepare repository')
     expect(await readdir(root)).toEqual([])
@@ -94,7 +94,7 @@ describe('RepositoryCache', () => {
 
   it('rejects empty or padded specifiers before touching the cache', async () => {
     const root = await temporaryRoot('repository-input')
-    const cache = new RepositoryCache(root, fakePackage)
+    const cache = new RepositoryCache(root, { install: fakePackage })
     expect(() => cache.resolve('')).toThrow('non-empty unpadded string')
     expect(() => cache.resolve(' github:owner/repository#ref')).toThrow('non-empty unpadded string')
     await expect(readdir(root)).resolves.toEqual([])
@@ -107,7 +107,7 @@ describe('RepositoryCache', () => {
     const entry = join(root, key)
     await mkdir(join(entry, 'node_modules', 'repository'), { recursive: true })
     await writeFile(join(entry, '.repository-cache.json'), '{}\n')
-    const cache = new RepositoryCache(root, async () => { throw new Error('must not reinstall') })
+    const cache = new RepositoryCache(root, { install: async () => { throw new Error('must not reinstall') } })
 
     await expect(cache.resolve(specifier)).rejects.toThrow('repository cache marker is invalid')
   })
@@ -115,6 +115,22 @@ describe('RepositoryCache', () => {
   it('selects and prepares a root .dsh-plugin Git subpath through the bundled pnpm', { timeout: 60_000 }, async () => {
     const root = await temporaryRoot('repository-pnpm')
     const repository = join(root, 'source')
+    const executableDirectory = join(root, 'bin')
+    await mkdir(executableDirectory)
+    await writeFile(join(executableDirectory, 'dsh-plugin-prepare'), [
+      '#!/usr/bin/env node',
+      "const { cpSync, mkdirSync, writeFileSync } = require('node:fs')",
+      "mkdirSync('dsh-plugin-assets/skills', { recursive: true })",
+      "cpSync('../skills', 'dsh-plugin-assets/skills/0', { recursive: true })",
+      "writeFileSync('dsh-plugin.mjs', 'export function apply() {}\\n')",
+      "writeFileSync('prepared.txt', `${process.env.REPOSITORY_TEST_VISIBLE ?? 'absent'}|${process.env.REPOSITORY_TEST_TOKEN ?? 'absent'}\\n`)",
+      '',
+    ].join('\n'), { mode: 0o700 })
+    await writeFile(join(executableDirectory, 'dsh-plugin-prepare.cmd'), [
+      '@echo off',
+      'node "%~dp0\\dsh-plugin-prepare" %*',
+      '',
+    ].join('\r\n'))
     await mkdir(join(repository, '.dsh-plugin'), { recursive: true })
     await mkdir(join(repository, 'skills', 'fixture'), { recursive: true })
     await writeFile(join(repository, 'package.json'), `${JSON.stringify({
@@ -125,17 +141,9 @@ describe('RepositoryCache', () => {
     await writeFile(join(repository, '.dsh-plugin', 'package.json'), `${JSON.stringify({
       name: 'repository-plugin-fixture',
       version: '1.0.0',
-      scripts: { prepare: 'node prepare.mjs' },
+      scripts: { prepack: 'dsh-plugin-prepare' },
       dsh: { skills: ['../skills'] },
     })}\n`)
-    await writeFile(join(repository, '.dsh-plugin', 'prepare.mjs'), [
-      "import { cp, mkdir, writeFile } from 'node:fs/promises'",
-      "await mkdir('dsh-plugin-assets/skills', { recursive: true })",
-      "await cp('../skills', 'dsh-plugin-assets/skills/0', { recursive: true })",
-      "await writeFile('dsh-plugin.mjs', 'export function apply() {}\\n')",
-      "await writeFile('prepared.txt', `${process.env.REPOSITORY_TEST_VISIBLE ?? 'absent'}|${process.env.REPOSITORY_TEST_TOKEN ?? 'absent'}\\n`)",
-      '',
-    ].join('\n'))
     await execFileAsync('git', ['init', '--quiet'], { cwd: repository })
     await execFileAsync('git', ['add', '.'], { cwd: repository })
     await execFileAsync('git', [
@@ -148,7 +156,9 @@ describe('RepositoryCache', () => {
     vi.stubEnv('REPOSITORY_TEST_VISIBLE', 'visible')
     vi.stubEnv('REPOSITORY_TEST_TOKEN', 'hidden')
 
-    const installed = await new RepositoryCache(join(root, 'cache')).resolve(specifier)
+    const installed = await new RepositoryCache(join(root, 'cache'), {
+      executableDirectories: [executableDirectory],
+    }).resolve(specifier)
     await expect(readFile(join(installed, 'prepared.txt'), 'utf8')).resolves.toBe('visible|absent\n')
     await expect(readFile(join(installed, 'dsh-plugin.mjs'), 'utf8')).resolves.toContain('export function apply')
     await expect(readFile(join(installed, 'dsh-plugin-assets/skills/0/fixture/SKILL.md'), 'utf8'))
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index e0ce60a641..c75c82dc84 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 33cd763d7dbe21b72f9e604b7b2e313081cf656f
-README.zh.md: 903dfbe601cc76acb0c1e87453dc03ef0321409b
+README.md: e0b45dc5fd40b5d1005598ae100d23ca7d0b6ec9
+README.zh.md: 30f200d2b7188d88e4a5e4e566cf3394f799933a
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 33cd763d7d..e0b45dc5fd 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -14,10 +14,7 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "prepare": "dsh-plugin-prepare"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-repository-plugin": "^0.0.1"
+    "prepack": "dsh-plugin-prepare"
   },
   "dsh": {
     "skills": ["../skills"],
@@ -26,7 +23,7 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
 }
 ```
 
-`dsh.skills` is an optional array of local skill roots. `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one field is required. Paths are relative to `.dsh-plugin`, must stay under its parent source directory, and may therefore refer to existing repository assets such as `../skills`. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
+`scripts.prepack` must be exactly `dsh-plugin-prepare`. DSH supplies that command from its own installed runtime while preparing Git source, so the repository package needs no DSH or npm dependency. `dsh.skills` is an optional array of local skill roots. `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one field is required. Paths are relative to `.dsh-plugin`, must stay under its parent source directory, and may therefore refer to existing repository assets such as `../skills`. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
 
 ## Standalone app configuration
 
@@ -47,7 +44,7 @@ Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A v
 
 ## Preparation
 
-`dsh-plugin-prepare` validates `package.json#dsh`, verifies skill-root types, parses the MCP file, copies assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. The wrapper contains only the normalized static manifest and fixed code that looks up the `dsh-repository-plugin` Loader builtin. It neither discovers nor compiles repository JavaScript, and the runtime never imports another repository entry point.
+During exact Git installation, DSH places a temporary host-owned `dsh-plugin-prepare` command on the isolated package lifecycle `PATH`; the command is not fetched from npm. The required `prepack` lifecycle runs after the Git package's dependency installation and before its selected subdirectory is packed, including when `.dsh-plugin` sits inside another package-manager workspace. The command validates `package.json#dsh`, verifies skill-root types, parses the MCP file, copies assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained the exact `prepack` declaration. The wrapper contains only the normalized static manifest and fixed code that looks up the `dsh-repository-plugin` Loader builtin. It neither discovers nor compiles repository JavaScript, and the runtime never imports another repository entry point. Failure to run or complete preparation fails installation before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
 
 The containing package manager still runs the configured repository package's lifecycle scripts. This restriction defines the supported DSH contribution surface; it is not a security boundary for a repository that the user chose to install as executable package-manager source.
 
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 903dfbe601..30f200d2b7 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -14,10 +14,7 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "prepare": "dsh-plugin-prepare"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-repository-plugin": "^0.0.1"
+    "prepack": "dsh-plugin-prepare"
   },
   "dsh": {
     "skills": ["../skills"],
@@ -26,7 +23,7 @@
 }
 ```
 
-`dsh.skills` 是可选的本地 skill 根数组。`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；两者至少声明一个。路径相对于 `.dsh-plugin`，必须留在其父级源码目录下，因此可以引用 `../skills` 等仓库现有资源。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
+`scripts.prepack` 必须精确设为 `dsh-plugin-prepare`。DSH 会在准备 Git 源时由已安装的运行时提供该命令，因此仓库包无需添加 DSH 或 NPM 依赖。`dsh.skills` 是可选的本地 skill 根数组。`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；两者至少声明一个。路径相对于 `.dsh-plugin`，必须留在其父级源码目录下，因此可以引用 `../skills` 等仓库现有资源。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
 
 ## 独立应用配置
 
@@ -47,7 +44,7 @@
 
 ## 准备阶段
 
-`dsh-plugin-prepare` 校验 `package.json#dsh`、确认 skill 根类型、解析 MCP 文件、把资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。包装模块只包含规范化后的静态 manifest（元数据清单），以及查找 `dsh-repository-plugin` Loader builtin 的固定代码；它不会发现或编译仓库 JavaScript，运行时也不会导入仓库的其他入口。
+安装精确指定的 Git 源时，DSH 会把一个临时的宿主自有 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；该命令不从 NPM 获取。必需的 `prepack` 生命周期在 Git 包完成依赖安装后、选定子目录打包前运行，即使 `.dsh-plugin` 位于另一个包管理器工作区内也不例外。该命令校验 `package.json#dsh`、确认 skill 根类型、解析 MCP 文件、把资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装模块前，DSH 会重新校验已安装包是否仍保留精确的 `prepack` 声明。包装模块只包含规范化后的静态 manifest（元数据清单），以及查找 `dsh-repository-plugin` Loader builtin 的固定代码；它不会发现或编译仓库 JavaScript，运行时也不会导入仓库的其他入口。准备阶段未运行或未完成时，安装会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
 
 外层包管理器仍会运行已配置仓库包的生命周期脚本。这里的限制只定义 DSH 所支持的贡献表面；对于用户选择以可执行包管理器源安装的仓库，它并不是安全边界。
 
diff --git a/packages/self-modification/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
index 9d66321087..654e37c201 100644
--- a/packages/self-modification/repository-plugin/src/format.ts
+++ b/packages/self-modification/repository-plugin/src/format.ts
@@ -14,6 +14,8 @@ export const PREPARED_ENTRY_FILENAME = 'dsh-plugin.mjs'
 export const PREPARED_ASSET_DIRECTORY = 'dsh-plugin-assets'
 /** Loader builtin used by every generated import-free wrapper. */
 export const REPOSITORY_PLUGIN_BUILTIN = 'dsh-repository-plugin'
+/** Exact host-owned command required by the repository package `prepack` lifecycle. */
+export const REPOSITORY_PLUGIN_PREPARE_COMMAND = 'dsh-plugin-prepare'
 
 const sourceMetadataSchema = z.object({
   skills: z.array(z.string().min(1)).default([]),
@@ -23,6 +25,9 @@ const sourceMetadataSchema = z.object({
 })
 const sourcePackageSchema = z.looseObject({
   name: z.string().min(1),
+  scripts: z.looseObject({
+    prepack: z.literal(REPOSITORY_PLUGIN_PREPARE_COMMAND),
+  }),
   dsh: sourceMetadataSchema,
 })
 const preparedManifestSchema = z.object({
@@ -148,7 +153,7 @@ export async function prepareDshPlugin(directory: string = process.cwd()): Promi
     throw new Error(`failed to read DSH plugin package metadata in ${pluginDirectory}`, { cause })
   }
   const parsed = sourcePackageSchema.safeParse(packageValue)
-  if (!parsed.success) throw formatZodError('invalid package.json#dsh', parsed.error)
+  if (!parsed.success) throw formatZodError('invalid DSH plugin package.json', parsed.error)
 
   const sourceRoot = await realpath(dirname(pluginDirectory))
   const skillSources: string[] = []
diff --git a/packages/self-modification/repository-plugin/src/index.ts b/packages/self-modification/repository-plugin/src/index.ts
index 73eb2dc473..d3d287974f 100644
--- a/packages/self-modification/repository-plugin/src/index.ts
+++ b/packages/self-modification/repository-plugin/src/index.ts
@@ -20,6 +20,7 @@ import {
 } from './format.ts'
 import { parseMcpDocument, resolveMcpServers } from './mcp.ts'
 import {
+  createRepositoryPrepareCommand,
   loadPreparedRepository,
   resolveRepositoryCacheDirectory,
   resolveRepositorySpecifier,
@@ -29,6 +30,7 @@ export {
   PREPARED_ASSET_DIRECTORY,
   PREPARED_ENTRY_FILENAME,
   REPOSITORY_PLUGIN_BUILTIN,
+  REPOSITORY_PLUGIN_PREPARE_COMMAND,
   prepareDshPlugin,
   type PreparedPluginManifest,
 } from './format.ts'
@@ -129,17 +131,24 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
   if (new Set(repositories).size !== repositories.length) {
     throw new Error('repository sources must resolve to unique exact specifiers')
   }
-  const cache = new RepositoryCache(resolveRepositoryCacheDirectory(config.cacheDir))
-  await ctx.effect(async function* () {
-    ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] = preparedRuntime
-    yield () => {
-      if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] === preparedRuntime) {
-        Reflect.deleteProperty(ctx.loader.builtins, REPOSITORY_PLUGIN_BUILTIN)
+  const prepareCommand = repositories.length === 0 ? undefined : await createRepositoryPrepareCommand()
+  try {
+    const cache = new RepositoryCache(resolveRepositoryCacheDirectory(config.cacheDir), {
+      executableDirectories: prepareCommand === undefined ? [] : [prepareCommand.directory],
+    })
+    await ctx.effect(async function* () {
+      ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] = preparedRuntime
+      yield () => {
+        if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] === preparedRuntime) {
+          Reflect.deleteProperty(ctx.loader.builtins, REPOSITORY_PLUGIN_BUILTIN)
+        }
       }
-    }
-    for (const repository of repositories) {
-      const plugin = await loadPreparedRepository(ctx, cache, repository)
-      yield plugin.dispose
-    }
-  }, 'repository-plugin runtime and sources')
+      for (const repository of repositories) {
+        const plugin = await loadPreparedRepository(ctx, cache, repository)
+        yield plugin.dispose
+      }
+    }, 'repository-plugin runtime and sources')
+  } finally {
+    await prepareCommand?.dispose()
+  }
 }
diff --git a/packages/self-modification/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
index 0befb82e42..e8a9e9b9cc 100644
--- a/packages/self-modification/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -3,12 +3,18 @@
  * @module
  */
 
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import type { Context, Fiber, FiberState, Plugin } from 'cordis'
 import type { RepositoryCache } from '@cordisjs/plugin-loader/repository'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
-import { PREPARED_ENTRY_FILENAME } from './format.ts'
+import { z } from 'zod'
+import {
+  PREPARED_ENTRY_FILENAME,
+  REPOSITORY_PLUGIN_PREPARE_COMMAND,
+} from './format.ts'
 
 // Value mirror: Cordis's const enum has no runtime object to import. Keep
 // aligned with `packages/self-modification/tool-cordis/src/fiber-state.ts`.
@@ -17,11 +23,66 @@ const FIBER_ACTIVE = 2 as FiberState.ACTIVE
 /** Directory under the Harness home containing immutable repository generations. */
 export const DEFAULT_REPOSITORY_CACHE_DIRECTORY = 'repository-plugins'
 
+/** Temporary host command supplied to repository package lifecycle scripts. */
+export interface RepositoryPrepareCommand {
+  /** Absolute directory to prepend to the isolated install's executable search path. */
+  directory: string
+  /** Remove the temporary command directory. */
+  dispose(): Promise<void>
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+function batchQuote(value: string): string {
+  return `"${value.replaceAll('%', '%%')}"`
+}
+
+/**
+ * Materialize the DSH-owned prepare executable used only while pnpm packs Git source.
+ * @returns a command directory and its idempotent cleanup operation.
+ */
+export async function createRepositoryPrepareCommand(): Promise<RepositoryPrepareCommand> {
+  const directory = await mkdtemp(join(tmpdir(), 'dsh-repository-plugin-bin-'))
+  const target = fileURLToPath(new URL('../lib/bin.js', import.meta.url))
+  try {
+    await Promise.all([
+      writeFile(join(directory, REPOSITORY_PLUGIN_PREPARE_COMMAND), [
+        '#!/bin/sh',
+        `exec ${shellQuote(process.execPath)} ${shellQuote(target)} "$@"`,
+        '',
+      ].join('\n'), { mode: 0o700 }),
+      writeFile(join(directory, `${REPOSITORY_PLUGIN_PREPARE_COMMAND}.cmd`), [
+        '@echo off',
+        `${batchQuote(process.execPath)} ${batchQuote(target)} %*`,
+        '',
+      ].join('\r\n'), { mode: 0o700 }),
+    ])
+  } catch (cause) {
+    /* v8 ignore next -- requires a host filesystem failure after mkdtemp; cleanup semantics are the contract under test. */
+    await rm(directory, { recursive: true, force: true })
+    /* v8 ignore next -- preserves that unstageable host failure after best-effort cleanup. */
+    throw cause
+  }
+  return {
+    directory,
+    async dispose() {
+      await rm(directory, { recursive: true, force: true })
+    },
+  }
+}
+
 // The ref segment excludes `#` so `github:o/r#a#b` fails here — at the config
 // parser, with the syntax the error message promises — instead of inside the
 // cache's pnpm install ('misconfiguration fails loud at the earliest
 // resolvable point').
 const GITHUB_SOURCE_PATTERN = /^github:([^/\s#&]+)\/([^/\s#&]+)#([^\s#&]+)(?:&path:(\/[^\s&]+))?$/
+const installedPackageSchema = z.looseObject({
+  scripts: z.looseObject({
+    prepack: z.literal(REPOSITORY_PLUGIN_PREPARE_COMMAND),
+  }),
+})
 
 function validPluginPath(path: string): boolean {
   const segments = path.split('/').slice(1)
@@ -57,6 +118,19 @@ export function resolveRepositoryCacheDirectory(configured: string | undefined):
   return resolve(configured ?? join(resolveDshHome(), 'cache', DEFAULT_REPOSITORY_CACHE_DIRECTORY))
 }
 
+async function assertInstalledPackageMetadata(directory: string): Promise<void> {
+  let value: unknown
+  try {
+    value = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8')) as unknown
+  } catch (cause) {
+    throw new Error(`failed to read installed DSH plugin package metadata in ${directory}`, { cause })
+  }
+  const result = installedPackageSchema.safeParse(value)
+  if (!result.success) {
+    throw new Error(`installed DSH plugin package must declare scripts.prepack as ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:\n${z.prettifyError(result.error)}`)
+  }
+}
+
 /**
  * Load one exact repository generation's generated wrapper as a child Cordis fiber.
  * @param ctx - repository runtime context that owns the child.
@@ -73,6 +147,7 @@ export async function loadPreparedRepository(
   const directory = await cache.resolve(specifier)
   const filename = join(directory, PREPARED_ENTRY_FILENAME)
   try {
+    await assertInstalledPackageMetadata(directory)
     const plugin = await import(/* @vite-ignore */pathToFileURL(filename).href) as Plugin
     const fiber = ctx.plugin(plugin)
     await fiber
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index 39840fd1f3..d026a4e14c 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -14,6 +14,7 @@ import * as RepositoryPlugin from '@deepseek-ai/dsh-repository-plugin'
 import * as RepositoryPluginInvariant from '@deepseek-ai/dsh-repository-plugin/invariant'
 import { parsePreparedPluginConfig } from '../src/format.ts'
 import {
+  createRepositoryPrepareCommand,
   loadPreparedRepository,
   resolveRepositoryCacheDirectory,
   resolveRepositorySpecifier,
@@ -30,7 +31,12 @@ async function temporaryDirectory(name: string): Promise<string> {
 async function writePlugin(root: string, name: string, dsh: Record<string, unknown>): Promise<string> {
   const directory = join(root, '.dsh-plugin')
   await mkdir(directory, { recursive: true })
-  await writeFile(join(directory, 'package.json'), `${JSON.stringify({ name, version: '0.0.0', dsh }, undefined, 2)}\n`)
+  await writeFile(join(directory, 'package.json'), `${JSON.stringify({
+    name,
+    version: '0.0.0',
+    scripts: { prepack: RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND },
+    dsh,
+  }, undefined, 2)}\n`)
   return directory
 }
 
@@ -102,6 +108,16 @@ describe('dsh-plugin-prepare', () => {
     await writeFile(join(malformed, 'package.json'), '{')
     await expect(RepositoryPlugin.prepareDshPlugin(malformed)).rejects.toThrow('failed to read DSH plugin package metadata')
 
+    const lifecycleRoot = await temporaryDirectory('wrong-lifecycle')
+    const lifecycle = join(lifecycleRoot, '.dsh-plugin')
+    await mkdir(lifecycle)
+    await writeFile(join(lifecycle, 'package.json'), JSON.stringify({
+      name: 'wrong-lifecycle',
+      scripts: { prepare: 'dsh-plugin-prepare' },
+      dsh: { skills: ['../skills'] },
+    }))
+    await expect(RepositoryPlugin.prepareDshPlugin(lifecycle)).rejects.toThrow('prepack')
+
     const emptyRoot = await temporaryDirectory('empty-metadata')
     const empty = await writePlugin(emptyRoot, 'empty', {})
     await expect(RepositoryPlugin.prepareDshPlugin(empty)).rejects.toThrow('declare at least one skill root or mcpServers file')
@@ -272,6 +288,17 @@ describe('prepared repository plugin Loader composition', () => {
 })
 
 describe('configured GitHub repository sources', () => {
+  it('creates host-owned prepare commands and removes them idempotently', async () => {
+    const command = await createRepositoryPrepareCommand()
+    expect(await readFile(join(command.directory, RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND), 'utf8'))
+      .toContain(process.execPath)
+    expect(await readFile(join(command.directory, `${RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND}.cmd`), 'utf8'))
+      .toContain(process.execPath)
+    await command.dispose()
+    await command.dispose()
+    await expect(stat(command.directory)).rejects.toMatchObject({ code: 'ENOENT' })
+  })
+
   it('defaults an omitted source list and rejects unknown configuration fields', () => {
     expect(RepositoryPlugin.Config.parse(undefined)).toEqual({ repositories: [] })
     expect(RepositoryPlugin.Config.safeParse({ repositories: [], unexpected: true }).success).toBe(false)
@@ -439,12 +466,43 @@ describe('configured GitHub repository sources', () => {
 
   it('labels a missing prepared wrapper with its exact source and path', async () => {
     const root = await temporaryDirectory('missing-wrapper')
+    const directory = await writePlugin(root, 'missing-wrapper', { skills: ['../skills'] })
     const ctx = new Context()
     const specifier = 'github:owner/repository#missing&path:/.dsh-plugin'
-    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, specifier))
+    await expect(loadPreparedRepository(ctx, { resolve: async () => directory }, specifier))
       .rejects.toThrow(`failed to load prepared repository Plugin ${JSON.stringify(specifier)}`)
     await ctx.fiber.dispose()
   })
+
+  it('rejects installed source with the obsolete prepare lifecycle', async () => {
+    const root = await temporaryDirectory('installed-lifecycle')
+    await writeFile(join(root, 'package.json'), JSON.stringify({
+      name: 'installed-lifecycle',
+      scripts: { prepare: 'dsh-plugin-prepare' },
+    }))
+    const ctx = new Context()
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, 'github:owner/repository#old&path:/.dsh-plugin'))
+      .rejects.toMatchObject({
+        cause: expect.objectContaining({
+          message: expect.stringContaining('must declare scripts.prepack') as string,
+        }) as Error,
+      })
+    await ctx.fiber.dispose()
+  })
+
+  it('labels missing installed package metadata with its source', async () => {
+    const root = await temporaryDirectory('missing-installed-metadata')
+    const ctx = new Context()
+    const specifier = 'github:owner/repository#damaged&path:/.dsh-plugin'
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, specifier))
+      .rejects.toMatchObject({
+        message: expect.stringContaining(JSON.stringify(specifier)) as string,
+        cause: expect.objectContaining({
+          message: expect.stringContaining('failed to read installed DSH plugin package metadata') as string,
+        }) as Error,
+      })
+    await ctx.fiber.dispose()
+  })
 })
 
 describe('repository plugin invariant companion', () => {
diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts
index c7b8a7d2c9..5c4ba9899a 100644
--- a/scripts/run-gates.spec.ts
+++ b/scripts/run-gates.spec.ts
@@ -218,7 +218,7 @@ describe('Node 24 lane ownership', () => {
     const subject = withPnpmEntrypoint(() => gatesForMode('ci-consumers'))
 
     expect(defaultConcurrency('ci-consumers', subject.length, 4)).toEqual({
-      workers: 10,
+      workers: 11,
       source: 'ci-consumers gate count',
     })
     expect(subject.map(item => item.id)).toEqual([
@@ -232,11 +232,19 @@ describe('Node 24 lane ownership', () => {
       'doc-typecheck',
       'node-next-types',
       'built-bin-smoke',
+      'github-repository-plugin-e2e',
     ])
     expect(subject.find(item => item.id === 'publint')?.needs).toEqual(['build'])
     expect(subject.find(item => item.id === 'built-package-invariants')?.needs).toEqual(['publint'])
     expect(subject.find(item => item.id === 'lint-and-duplication')?.needs).toEqual(['built-package-invariants'])
-    for (const id of ['snapshot', 'web-snapshot', 'doc-typecheck', 'node-next-types', 'built-bin-smoke']) {
+    for (const id of [
+      'snapshot',
+      'web-snapshot',
+      'doc-typecheck',
+      'node-next-types',
+      'built-bin-smoke',
+      'github-repository-plugin-e2e',
+    ]) {
       expect(subject.find(item => item.id === id)?.needs).toEqual(['built-package-invariants'])
     }
     expect(subject.find(item => item.id === 'snapshot')?.env).toEqual({ DSH_EXAMPLE_MODE: 'lib' })
@@ -249,6 +257,16 @@ describe('Node 24 lane ownership', () => {
         'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
       ]),
     )
+    const githubRepositoryPlugin = subject.find(item => item.id === 'github-repository-plugin-e2e')
+    expect(githubRepositoryPlugin).toMatchObject({
+      label: 'GitHub repository Plugin dsh run',
+      env: {
+        DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E: '1',
+      },
+    })
+    expect(githubRepositoryPlugin?.args).toEqual(
+      expect.arrayContaining(['apps/cli/tests/github-repository-plugin.built.e2e.ts']),
+    )
     expect(subject.find(item => item.id === 'web-snapshot')).toMatchObject({
       displayCommand: 'DSH_SNAPSHOT=replay pnpm run test:web:built',
       env: { DSH_SNAPSHOT: 'replay' },
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index d99889d28b..3bd0e11987 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -406,6 +406,7 @@ function ciConsumerGates(): Gate[] {
       needs: validatedBuild,
     }),
     builtBinSmokeGate(validatedBuild),
+    githubRepositoryPluginE2eGate(validatedBuild),
   ]
 }
 
@@ -636,6 +637,20 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
   })
 }
 
+function githubRepositoryPluginE2eGate(needs: string[]): Gate {
+  return pnpmExec('github-repository-plugin-e2e', [
+    'vitest',
+    'run',
+    '--config',
+    'vitest.e2e.config.ts',
+    'apps/cli/tests/github-repository-plugin.built.e2e.ts',
+  ], {
+    label: 'GitHub repository Plugin dsh run',
+    needs,
+    env: { DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E: '1' },
+  })
+}
+
 /**
  * Reject a gate list whose graph cannot be executed unambiguously.
  * @param gates - complete aggregate to validate.
diff --git a/vendor/README.md b/vendor/README.md
index 02e33ea723..3cc2a313d2 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -39,7 +39,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
 9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
-10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git prepare run through the bundled pnpm.
+10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. Callers may prepend host-owned executable directories to the isolated package lifecycle `PATH`; all paths are resolved before the child starts. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` run through the bundled pnpm and an injected command directory.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
 13. **`include/src/index.ts` serialized child-tree mutation and `hmr/src/index.ts` main-watcher initial-scan suppression**: every Include child-tree mutation (initial apply, refresh, `internal/update` patch re-application) runs through one per-Include queue, because the group's transactional `update` is not reentrant — two concurrent applies interleave create and rollback on the same entries and strand the Include fiber without ever settling. The HMR main watcher passes `ignoreInitial: true`: the initial scan re-announced files boot had just consumed, and its `add` for a config file refreshed an Include mid-initial-apply; once serialized, a failing initial apply's rollback disposed HMR, whose teardown drain waited on the queued refresh sitting behind that same apply — a deadlock that exited 13 with no diagnostic. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a user patch layer present at registration must apply once. Covered by the patch-overlay boot-failure built-bin case in `apps/cli/tests/built-bin.e2e.ts`.
diff --git a/vendor/loader/src/repository.ts b/vendor/loader/src/repository.ts
index 94a0c5cf16..c0cd1589aa 100644
--- a/vendor/loader/src/repository.ts
+++ b/vendor/loader/src/repository.ts
@@ -8,7 +8,7 @@ import { spawn } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
-import { dirname, join, resolve } from 'node:path'
+import { delimiter, dirname, join, resolve } from 'node:path'
 
 /** Exact pnpm release shipped with the Loader for repository installation. */
 export const BUNDLED_PNPM_VERSION = '11.7.0'
@@ -21,6 +21,14 @@ const SENSITIVE_ENV_PATTERN = /KEY|PASSWORD|SECRET|TOKEN/i
 /** Injectable isolated-install boundary used by {@link RepositoryCache}. */
 export type RepositoryInstall = (directory: string) => Promise<void>
 
+/** Installation controls for {@link RepositoryCache}. */
+export interface RepositoryCacheOptions {
+  /** Override the isolated package installation boundary. */
+  install?: RepositoryInstall
+  /** Command directories resolved absolutely and prepended to package lifecycle `PATH`. */
+  executableDirectories?: readonly string[]
+}
+
 interface CacheMarker {
   specifier: string
 }
@@ -29,12 +37,26 @@ function scrubEnvironment(environment: NodeJS.ProcessEnv = process.env): NodeJS.
   return Object.fromEntries(Object.entries(environment).filter(([name]) => !SENSITIVE_ENV_PATTERN.test(name)))
 }
 
+function installEnvironment(executableDirectories: readonly string[]): NodeJS.ProcessEnv {
+  const scrubbed = scrubEnvironment()
+  if (executableDirectories.length === 0) return scrubbed
+  const path = Object.entries(scrubbed).find(([name]) => name.toUpperCase() === 'PATH')?.[1]
+  const withoutPath = Object.fromEntries(Object.entries(scrubbed).filter(([name]) => name.toUpperCase() !== 'PATH'))
+  return {
+    ...withoutPath,
+    PATH: [...executableDirectories, ...(path === undefined ? [] : [path])].join(delimiter),
+  }
+}
+
 function appendOutput(current: string, chunk: Uint8Array): string {
   const combined = current + Buffer.from(chunk).toString('utf8')
   return combined.length <= MAX_ERROR_OUTPUT ? combined : combined.slice(-MAX_ERROR_OUTPUT)
 }
 
-async function installWithBundledPnpm(directory: string): Promise<void> {
+async function installWithBundledPnpm(
+  directory: string,
+  executableDirectories: readonly string[],
+): Promise<void> {
   const require = createRequire(import.meta.url)
   const pnpmManifest = require.resolve('pnpm')
   const pnpmBin = join(dirname(pnpmManifest), 'bin', 'pnpm.mjs')
@@ -47,7 +69,7 @@ async function installWithBundledPnpm(directory: string): Promise<void> {
       '--reporter=append-only',
     ], {
       cwd: directory,
-      env: scrubEnvironment(),
+      env: installEnvironment(executableDirectories),
       shell: false,
       stdio: ['ignore', 'pipe', 'pipe'],
     })
@@ -122,13 +144,16 @@ export class RepositoryCache {
   readonly directory: string
 
   private readonly tasks = new Map<string, Promise<string>>()
+  private readonly install: RepositoryInstall
 
   /**
    * @param directory - caller-owned persistent cache root.
-   * @param install - isolated package installation boundary; defaults to the bundled pnpm.
+   * @param options - isolated installer override and lifecycle command directories.
    */
-  constructor(directory: string, private readonly install: RepositoryInstall = installWithBundledPnpm) {
+  constructor(directory: string, options: RepositoryCacheOptions = {}) {
     this.directory = resolve(directory)
+    const executableDirectories = (options.executableDirectories ?? []).map(entry => resolve(entry))
+    this.install = options.install ?? (staging => installWithBundledPnpm(staging, executableDirectories))
   }
 
   /**

From 778b9585d44439fa60a7e80efc90950a0c6c8f5b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:53:40 +0800
Subject: [PATCH 435/516] docs: refresh repository Plugin config source

---
 docs/config-catalog.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index eb4472d629..153ac72cc3 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1182,7 +1182,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/self-modification/repository-plugin/src/index.ts:42`](../packages/self-modification/repository-plugin/src/index.ts)
+Source: [`packages/self-modification/repository-plugin/src/index.ts:44`](../packages/self-modification/repository-plugin/src/index.ts)
 
 ## `@deepseek-ai/dsh-sandbox-local`
 

From a9af1a33f01310c56b60864afd51aceb95f9037a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:02:36 +0800
Subject: [PATCH 436/516] test(repository-plugin): update prepared fixture
 metadata

---
 examples/headless-agent/tests/keyless-smoke.e2e.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/examples/headless-agent/tests/keyless-smoke.e2e.ts b/examples/headless-agent/tests/keyless-smoke.e2e.ts
index 8b69406c53..c737e4ea72 100644
--- a/examples/headless-agent/tests/keyless-smoke.e2e.ts
+++ b/examples/headless-agent/tests/keyless-smoke.e2e.ts
@@ -6,7 +6,11 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
-import { PREPARED_ENTRY_FILENAME, prepareDshPlugin } from '@deepseek-ai/dsh-repository-plugin'
+import {
+  PREPARED_ENTRY_FILENAME,
+  REPOSITORY_PLUGIN_PREPARE_COMMAND,
+  prepareDshPlugin,
+} from '@deepseek-ai/dsh-repository-plugin'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 
 const binScript = fileURLToPath(new URL('./fixtures/headless-driver.ts', import.meta.url))
@@ -72,6 +76,7 @@ describe('headless-agent keyless smoke', () => {
       await writeFile(join(plugin, 'package.json'), `${JSON.stringify({
         name: 'headless-repository-fixture',
         version: '0.0.0',
+        scripts: { prepack: REPOSITORY_PLUGIN_PREPARE_COMMAND },
         dsh: { skills: ['../skills'] },
       }, undefined, 2)}\n`)
       await prepareDshPlugin(plugin)

From a0c64f49068cfa95925f9e056f327a9d18f07c3e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 18:16:59 +0800
Subject: [PATCH 437/516] ci(repository-plugin): authenticate private GitHub
 source

---
 ...26-07-30-static-repository-plugin-format.i18n.yaml |  4 ++--
 .../2026-07-30-static-repository-plugin-format.md     |  2 +-
 .../2026-07-30-static-repository-plugin-format.zh.md  |  2 +-
 ...-owned-git-repository-plugin-preparation.i18n.yaml |  4 ++--
 ...08-host-owned-git-repository-plugin-preparation.md |  5 +++--
 ...host-owned-git-repository-plugin-preparation.zh.md |  5 +++--
 .github/workflows/ci.yml                              | 11 +++++++++++
 .../repository-plugin/README.i18n.yaml                |  4 ++--
 .../self-modification/repository-plugin/README.md     |  2 ++
 .../self-modification/repository-plugin/README.zh.md  |  2 ++
 10 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 40a0461378..b555ad63c0 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.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 .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
-2026-07-30-static-repository-plugin-format.md: 4823495dabee2101713ac72c8d0cee5bcc6b38d1
-2026-07-30-static-repository-plugin-format.zh.md: e5817ca982a71a609c86c5835b803b12f1317e1a
+2026-07-30-static-repository-plugin-format.md: 5b1038f8738868a5838d4b20a6d56399c5f11ab6
+2026-07-30-static-repository-plugin-format.zh.md: c7cbc588c5ce6982c7c7003815151c9d40956972
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
index 4823495dab..5b1038f873 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
@@ -46,4 +46,4 @@ Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `C
 
 ## Testing
 
-Focused tests prepare skills and MCP metadata, prove the emitted wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The CI built-entry acceptance invokes `dsh run` with a GitHub source pinned to the pull request head, lets bundled pnpm fetch and prepare a private dependency-free fixture, then observes the copied skill in the real model request and the prepared wrapper in the immutable cache.
+Focused tests prepare skills and MCP metadata, prove the emitted wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The CI built-entry acceptance invokes `dsh run` with a GitHub source pinned to the pull request head, authenticates to the private pull request repository through job-scoped Git configuration, lets bundled pnpm fetch and prepare its dependency-free fixture, then observes the copied skill in the real model request and the prepared wrapper in the immutable cache.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index e5817ca982..c7cbc588c5 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -46,4 +46,4 @@
 
 ## 测试
 
-聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。CI 的构建入口验收会用锁定到 PR（Pull Request）head 的 GitHub 源调用 `dsh run`，让随附 pnpm 获取并准备一个私有且不含依赖的 fixture（测试前置数据），然后在真实模型请求中观察已复制的 skill，并在不可变缓存中观察已准备的包装模块。
+聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。CI 的构建入口验收会用锁定到 PR（Pull Request）head 的 GitHub 源调用 `dsh run`，通过作业作用域的 Git 配置认证私有 PR 仓库，让随附 pnpm 获取并准备其中不含依赖的 fixture（测试前置数据），然后在真实模型请求中观察已复制的 skill，并在不可变缓存中观察已准备的包装模块。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
index 55d9045506..39a7548d24 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.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 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
-2026-08-08-host-owned-git-repository-plugin-preparation.md: 45e84f9c8a89bb9d1eb7e4521634d16789dea2f0
-2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: ba88d5bb351427118d55c357209b496b39c2eb98
+2026-08-08-host-owned-git-repository-plugin-preparation.md: 47410bf3c55455a971ec347eab4e8b37ea26c6a5
+2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: 64c37543d34147c41fc7a362040c7ada8fde0652
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
index 45e84f9c8a..47410bf3c5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
@@ -18,7 +18,7 @@ The fixed authoring format now requires exact `scripts.prepack: "dsh-plugin-prep
 
 `@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. The command directory exists only for the installation transaction and is removed on success or failure. The repository remains trusted package-manager input: DSH supplies one command, but other lifecycle scripts and dependencies still execute under the existing trust contract.
 
-The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true`, dependency-free GitHub fixture. It requires the run to reach the mock LLM, finds the repository skill description in the actual model request, and verifies the generated wrapper and copied skill under the immutable DSH cache. The test fails if CI omits the exact source instead of silently skipping.
+The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Because that repository is private, the workflow writes a job-scoped Git configuration that uses the read-only job token for GitHub HTTPS and rewrites pnpm's SSH fallback to that authenticated transport. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true`, dependency-free GitHub fixture. It requires the run to reach the mock LLM, finds the repository skill description in the actual model request, and verifies the generated wrapper and copied skill under the immutable DSH cache. The test fails if CI omits the exact source instead of silently skipping.
 
 ## Alternatives considered
 
@@ -33,10 +33,11 @@ The Node 24 consumer lane passes an exact source derived from the pull request h
 ## Consequences
 
 - A repository author can commit the fixed `.dsh-plugin/package.json` and source assets to GitHub without publishing either the Plugin or its preparation helper to npm.
+- Private GitHub sources use the host's standard Git authentication. CI proves that path with a temporary read-only configuration rather than persistent runner credentials.
 - `prepack`, not `prepare`, is part of the pre-release authoring format. Invalid lifecycle metadata fails during source preparation or installed-package validation instead of producing an ambiguous partial format.
 - Exact source strings still identify immutable cache generations; a changed ref or source configuration selects another generation.
 - This repair does not expand the contribution surface: prepared repository Plugins still contribute only declared skills and common MCP definitions, while arbitrary package lifecycle code remains trusted installation code rather than a model-facing Cordis Plugin API.
 
 ## Testing
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins the exact `prepack` metadata and temporary command cleanup. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact live GitHub source, actual built `dsh run`, real headless composition, mock LLM request observation, and prepared cache inspection.
+`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins the exact `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, real headless composition, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
index ba88d5bb35..64c37543d3 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
@@ -18,7 +18,7 @@ repository 插件的创作契约依赖 `scripts.prepare: "dsh-plugin-prepare"`
 
 `@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。该命令目录仅存在于安装事务期间，无论成功还是失败都会被移除。仓库仍是受信任的包管理器输入：DSH 仅提供这一条命令，其他生命周期脚本和依赖仍会按既有信任契约执行。
 
-Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true`、不含依赖的 GitHub fixture。验收要求该次运行到达 mock LLM（大语言模型），在实际模型请求中找到 repository skill 描述，并验证不可变 DSH 缓存中的生成包装层和已复制 skill。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
+Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。由于该仓库为私有仓库，工作流会写入一份作业作用域的 Git 配置，使用该作业的只读 token 对 GitHub HTTPS 连接进行认证，并将 pnpm 的 SSH 回退路径重写为这一已认证的传输方式。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true`、不含依赖的 GitHub fixture。验收要求该次运行到达 mock LLM（大语言模型），在实际模型请求中找到 repository skill 描述，并验证不可变 DSH 缓存中的生成包装层和已复制 skill。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
 
 ## 考虑过的替代方案
 
@@ -33,10 +33,11 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 
 ## 后果
 
 - 仓库作者可以把修复后的 `.dsh-plugin/package.json` 和源资源提交到 GitHub，而无需把插件或其准备辅助程序发布到 NPM。
+- 私有 GitHub 源使用宿主的标准 Git 认证。CI 使用临时的只读配置而非运行器上的持久凭据来验证该路径。
 - 预发布创作格式使用 `prepack` 而不是 `prepare`。无效的生命周期元数据会在源码准备或已安装包校验阶段导致失败，而不会留下状态不明的半成品格式。
 - 精确源字符串仍标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
 - 本次修复不扩大贡献范围：已准备的 repository 插件仍只贡献已声明的 skills 和通用 MCP 定义，而任意包生命周期代码仍是受信任的安装代码，不是面向模型的 Cordis 插件 API。
 
 ## 测试
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定精确的 `prepack` 元数据和临时命令清理行为。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确的真实 GitHub 源、实际构建产物的 `dsh run`、真实 headless 组合、mock LLM 请求观测，以及对已准备缓存的检查。
+`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定精确的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、真实 headless 组合、mock LLM 请求观测，以及对已准备缓存的检查。
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5324df431e..d017fa14fb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -242,6 +242,17 @@ jobs:
         if: vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]'
         run: pnpm --filter @deepseek-ai/dsh-frontend exec playwright install chromium
 
+      - name: Configure private GitHub repository Plugin access
+        env:
+          DSH_GITHUB_SOURCE_TOKEN: ${{ github.token }}
+        run: |
+          source_config="$RUNNER_TEMP/dsh-github-source.gitconfig"
+          basic_auth=$(printf 'x-access-token:%s' "$DSH_GITHUB_SOURCE_TOKEN" | base64 | tr -d '\n')
+          git config --file "$source_config" url.https://github.com/.insteadOf git@github.com:
+          git config --file "$source_config" --add url.https://github.com/.insteadOf ssh://git@github.com/
+          git config --file "$source_config" http.https://github.com/.extraheader "AUTHORIZATION: basic $basic_auth"
+          echo "GIT_CONFIG_GLOBAL=$source_config" >> "$GITHUB_ENV"
+
       - name: Run compatibility, snapshot, and artifact gates
         run: pnpm run check:ci:consumers
 
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index c75c82dc84..9720364496 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: e0b45dc5fd40b5d1005598ae100d23ca7d0b6ec9
-README.zh.md: 30f200d2b7188d88e4a5e4e566cf3394f799933a
+README.md: 23c4cc0dceaf0692b7ef5067f9170b8c6b311cc0
+README.zh.md: db2f3e5a5c8915836d97177f797411e17e70441c
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index e0b45dc5fd..23c4cc0dce 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -40,6 +40,8 @@ The shipped `dsh-base` bundle every profile starts from contains an empty `repos
 
 Each source must use `github:owner/repository#<ref>`. Omitting `&path:` selects `/.dsh-plugin`; an explicit path is absolute within the repository and must end in `.dsh-plugin`. A commit ref gives the clearest immutable identity, while tags and branches remain accepted exact config values. `cacheDir` may override the default `$DSH_HOME/cache/repository-plugins` cache root.
 
+Git transport uses the host's ordinary Git authentication. Public repositories need no credentials; private sources require a read-only credential or SSH agent that can read the selected repository. DSH removes credential-shaped environment variables before package lifecycles, so configure Git itself, such as through a credential helper or job-scoped Git config, instead of expecting an exported token variable to cross that boundary. Repository lifecycle code is trusted and can invoke Git, so use the narrowest repository-scoped credential available.
+
 Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A valid source-list change installs and swaps the complete repository Plugin generation; a failed fetch, prepare, import, or Plugin application keeps the last good tree and broadcasts `hmr/config-update-failed(filename, error)`. One-shot runs read the layers only at startup, and a `--patch` overlay is never watched. An identical source string permanently reuses its prepared cache entry, so selecting changed code requires a ref, path, or other source-config change. App integration rationale: [config-only repository Plugins Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md).
 
 ## Preparation
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 30f200d2b7..db2f3e5a5c 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -40,6 +40,8 @@
 
 每个源都必须采用 `github:owner/repository#<ref>`。省略 `&path:` 时选择 `/.dsh-plugin`；显式路径是仓库内的绝对路径，并且必须以 `.dsh-plugin` 结尾。commit ref 提供最清晰的不可变身份；tag 和 branch 仍可作为精确配置值使用。`cacheDir` 可覆盖默认缓存根 `$DSH_HOME/cache/repository-plugins`。
 
+Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有源需要可读取所选仓库的只读凭据或 SSH agent。DSH 会在包生命周期运行前移除名称符合凭据模式的环境变量，因此请配置 Git 本身，例如使用 Git 凭据辅助工具或作业作用域的 Git 配置，而不要指望已导出的 token 变量跨越该边界。仓库生命周期代码受信任且可以调用 Git，因此请使用作用域最窄且仅限所选仓库的凭据。
+
 长期运行的 surface 通过 Cordis HMR（热模块替换）监视两个 `cordis.patch.yml` 层。有效的源列表变更会安装并替换整套 repository Plugin generation；拉取、准备、导入或插件应用失败时，最后一个可用树保持运行，并广播 `hmr/config-update-failed(filename, error)`。一次性运行只在启动时读取这些层，`--patch` overlay 则从不被监视。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入 repository Plugin 的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
 
 ## 准备阶段

From 033fa4b0b12ac88e2ee89597b059891bc4e12f90 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:25:14 +0800
Subject: [PATCH 438/516] feat(repository-plugin): load trusted package code

---
 ...-static-repository-plugin-format.i18n.yaml |  4 +-
 ...6-07-30-static-repository-plugin-format.md | 16 ++--
 ...7-30-static-repository-plugin-format.zh.md | 18 ++--
 ...-trusted-repository-package-code.i18n.yaml |  6 ++
 ...6-08-08-trusted-repository-package-code.md | 51 ++++++++++
 ...8-08-trusted-repository-package-code.zh.md | 51 ++++++++++
 ...it-repository-plugin-preparation.i18n.yaml |  4 +-
 ...owned-git-repository-plugin-preparation.md | 10 +-
 ...ed-git-repository-plugin-preparation.zh.md | 10 +-
 ...0-config-only-repository-plugins.i18n.yaml |  4 +-
 ...26-07-30-config-only-repository-plugins.md |  8 +-
 ...07-30-config-only-repository-plugins.zh.md |  8 +-
 .../.dsh-plugin/.mcp.json                     | 10 ++
 .../.dsh-plugin/package.json                  | 20 +++-
 .../.dsh-plugin/src/mcp-server.ts             | 19 ++++
 .../.dsh-plugin/src/plugin.ts                 | 59 ++++++++++++
 .../.dsh-plugin/tsconfig.json                 | 13 +++
 .../github-repository-plugin.built.e2e.ts     | 57 ++++++++---
 .../fixtures/repository-plugin/dsh-plugin.mjs | 11 ++-
 knip.json                                     | 11 +++
 packages/mcp/mcp-client/README.i18n.yaml      |  4 +-
 packages/mcp/mcp-client/README.md             |  3 +-
 packages/mcp/mcp-client/README.zh.md          |  3 +-
 packages/mcp/mcp-client/src/index.ts          | 10 +-
 packages/mcp/mcp-client/tests/apply.spec.ts   | 37 +++----
 .../mcp/mcp-client/tests/mcp-client.e2e.ts    | 29 ++----
 .../repository-plugin/README.i18n.yaml        |  4 +-
 .../repository-plugin/README.md               | 43 +++++++--
 .../repository-plugin/README.zh.md            | 43 +++++++--
 .../repository-plugin/package.json            |  2 +-
 .../repository-plugin/src/format.ts           | 65 +++++++++++--
 .../repository-plugin/src/index.ts            |  2 +-
 .../repository-plugin/src/source.ts           |  8 +-
 .../tests/repository-plugin.spec.ts           | 96 +++++++++++++++++--
 34 files changed, 590 insertions(+), 149 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/.mcp.json
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/mcp-server.ts
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/plugin.ts
 create mode 100644 apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json

diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index b555ad63c0..8ffa06ab1a 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.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 .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
-2026-07-30-static-repository-plugin-format.md: 5b1038f8738868a5838d4b20a6d56399c5f11ab6
-2026-07-30-static-repository-plugin-format.zh.md: c7cbc588c5ce6982c7c7003815151c9d40956972
+2026-07-30-static-repository-plugin-format.md: 615529c89d32ed87c73d100b632318500e1ae86c
+2026-07-30-static-repository-plugin-format.zh.md: bb90994defccdaf2044b467cb3c5018c1c94641a
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
index 5b1038f873..615529c89d 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
@@ -6,15 +6,15 @@ English | [中文](2026-07-30-static-repository-plugin-format.zh.md)
 
 ## Problem
 
-A repository that already contains reusable skills or an MCP server declaration should be usable by standalone Harness applications without becoming a Harness SDK project or rewriting its existing layout. Popular repositories must be able to add one `.dsh-plugin` directory while keeping their current skills and `.mcp.json` elsewhere in the tree. At the same time, treating an arbitrary repository entry point as a Cordis Plugin would make every repository a new unrestricted runtime extension surface and would bypass the existing skill and MCP lifecycle owners.
+A repository that already contains reusable skills or an MCP server declaration should be usable by standalone Harness applications without becoming a Harness SDK project or rewriting its existing layout. Popular repositories must be able to add one `.dsh-plugin` directory while keeping their current skills and `.mcp.json` elsewhere in the tree. These portable static contributions still need to reuse the existing skill and MCP lifecycle owners when the same trusted package also carries native Cordis code.
 
 The [package-manager-native repository cache](2026-07-30-package-manager-native-repository-cache.md) prepares an exact package source but intentionally knows nothing about DSH formats. This layer therefore needs a package-manager-compatible authoring format, a deterministic prepared artifact, and a Cordis composition that stays transactional under Loader disposal and replacement.
 
 ## Decision
 
-`@deepseek-ai/dsh-repository-plugin` owns a restricted `.dsh-plugin` package format with two contribution kinds only: skill roots and one common `.mcp.json`. Its package metadata uses `package.json#dsh.skills` for relative skill-root paths and `package.json#dsh.mcpServers` for the relative MCP document path. At least one is required. Each path may leave `.dsh-plugin` to reuse repository content but must remain beneath the directory containing that `.dsh-plugin`; a nested selectable Plugin therefore owns the adjacent subtree above its package without gaining access to unrelated host paths.
+`@deepseek-ai/dsh-repository-plugin` owns the static contribution subformat inside a `.dsh-plugin` package: skill roots and one common `.mcp.json`. Its package metadata uses `package.json#dsh.skills` for relative skill-root paths and `package.json#dsh.mcpServers` for the relative MCP document path. Each path may leave `.dsh-plugin` to reuse repository content but must remain beneath the directory containing that `.dsh-plugin`; a nested selectable Plugin therefore owns the adjacent subtree above its package without gaining access to unrelated host paths. The package may additionally declare the explicit code entry owned by the [trusted repository package decision](2026-08-08-trusted-repository-package-code.md), and at least one code or static contribution is required.
 
-The `.dsh-plugin` package declares exact `scripts.prepack: "dsh-plugin-prepare"` metadata without depending on a DSH npm package. During Git installation, the standalone runtime temporarily supplies that command from its own build on the isolated lifecycle `PATH`; `prepack` runs after dependency installation and before pnpm packs a selected subdirectory, including a Plugin nested inside another package-manager workspace. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`; the source loader revalidates the installed package's exact lifecycle metadata before importing that wrapper. The `.mjs` extension avoids imposing `type: module` on repository-authored package metadata. The generated module is a fixed import-free template containing only a normalized manifest, an `inject` list derived from it (`loader`, plus `skills` and/or `tools` per the declared capabilities, so the wrapper fiber gates on the services its children need), and delegation to the `dsh-repository-plugin` Loader builtin. Preparation never discovers, transpiles, bundles, or preserves a custom repository entry point. The host-owned command rationale is in the [Git source preparation repair](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
+The `.dsh-plugin` package declares a non-empty `scripts.prepack` that invokes `dsh-plugin-prepare` without depending on a DSH npm package. During Git installation, the standalone runtime temporarily supplies that command from its own build on the isolated lifecycle `PATH`; `prepack` runs after dependency installation and before pnpm packs a selected subdirectory, including a Plugin nested inside another package-manager workspace. The package may build its code first. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`; the source loader revalidates the installed package's helper-bearing lifecycle metadata before importing that wrapper. A static-only package still receives an import-free wrapper containing its normalized manifest, service-derived `inject` list, and delegation to the `dsh-repository-plugin` Loader builtin. The host-owned command rationale is in the [Git source preparation repair](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
 
 Loading the DSH package registers that builtin as an effect. A generated wrapper mounts the builtin as its child with `import.meta.url`, so all contributions belong to the wrapper fiber and disappear on Loader removal or rollback. The builtin revalidates the prepared manifest and path containment before reading assets. It composes the existing implementations rather than registering skills or MCP tools itself.
 
@@ -22,11 +22,11 @@ Each prepared skill set mounts `dsh-skill-local` with a unique `repository:<pack
 
 Each `.mcp.json` server becomes one existing `dsh-mcp-client` child. The adapter accepts the common root `{ "mcpServers": ... }`; stdio definitions allow only optional `type: "stdio"`, `command`, `args`, and `env`, while HTTP definitions allow only `type: "http"`, `url`, and `headers`. Exact `${NAME}` process-environment references expand at runtime, after cache preparation; missing names fail Plugin load. HTTP maps to the client's Streamable HTTP transport, and stdio uses the prepared package directory as `cwd`. The existing client alone owns connection attempts, failure logging, remote tool synchronization, tool calls, and disconnects. Consequently an MCP connection failure keeps its established successful-plugin/no-tools behavior and is not reclassified as a repository preparation or Loader failure.
 
-Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `CLAUDE_PLUGIN_ROOT`, and a broader Claude compatibility contract. Hooks, commands, agents, apps, arbitrary Cordis code, marketplaces, and discovery are also unsupported. Repository subdirectory selection and GitHub source configuration belong to the [standalone app integration](../feature/2026-07-30-config-only-repository-plugins.md), not this format package.
+Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `CLAUDE_PLUGIN_ROOT`, and a broader Claude compatibility contract. Commands, hooks, agents, rules, and other foreign manifest conventions are not inferred from static repository layout; DSH-native behavior uses the explicit trusted Cordis entry. Repository subdirectory selection and GitHub source configuration belong to the [standalone app integration](../feature/2026-07-30-config-only-repository-plugins.md), not this static adapter.
 
 ## Alternatives considered
 
-**Load a repository's own Cordis entry point.** Rejected because it makes the advertised static format an unrestricted code-loading API, requires repository authors to depend on Harness internals, and duplicates the ordinary SDK/plugin-dependency path.
+**Discover an entry from `main`, `exports`, or repository layout.** Rejected because static assets do not imply that a package's ordinary entry is a Cordis Plugin. Trusted code loading is explicit through `dsh.entry` and remains outside this static adapter's ownership.
 
 **Teach generated wrappers to implement skills and MCP directly.** Rejected because copied runtime code would drift from `dsh-skill-local` and `dsh-mcp-client`, especially their provider invalidation, tool synchronization, failure, and teardown contracts.
 
@@ -39,11 +39,11 @@ Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `C
 ## Consequences
 
 - Existing skill/MCP repositories can add a small `.dsh-plugin/package.json` without relocating their assets or adopting an SDK project.
-- Prepared output is deterministic static glue, while the configured repository and its dependency lifecycle remain trusted executable package-manager input rather than a sandbox.
+- Prepared static output is deterministic glue, while an optional `dsh.entry` and the configured repository lifecycle remain trusted executable package-manager input rather than a sandbox.
 - Multiple repository Plugins coexist through provider names and ordinary MCP server-name uniqueness; duplicate names fail through their existing registries and participate in Loader rollback.
 - Cached source edits do not appear live. Another exact source/ref/path/config selection is required.
-- Adding another contribution kind requires an explicit format and DSH-owned runtime consumer; it cannot arrive as repository JavaScript by accident.
+- Adding another portable static contribution kind requires an explicit format and DSH-owned runtime consumer; DSH-native behavior uses the separate explicit code entry.
 
 ## Testing
 
-Focused tests prepare skills and MCP metadata, prove the emitted wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The CI built-entry acceptance invokes `dsh run` with a GitHub source pinned to the pull request head, authenticates to the private pull request repository through job-scoped Git configuration, lets bundled pnpm fetch and prepare its dependency-free fixture, then observes the copied skill in the real model request and the prepared wrapper in the immutable cache.
+Focused tests prepare skills and MCP metadata, prove a static-only wrapper contains no imports, reject Work IQ-style OAuth fields, map Expo-style HTTP and DataJunction-style stdio plus environment values, and exercise missing variables. A real Loader test mounts a generated wrapper through the registered builtin, reads its skill through `ctx.skills`, removes the Loader entry, and observes provider cleanup. The CI built-entry acceptance invokes `dsh run` with a GitHub source pinned to the pull request head and observes the copied skill alongside the trusted code and MCP proofs owned by the superseding decision.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index c7cbc588c5..bb90994def 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -1,4 +1,4 @@
-# Agent Note：静态 repository Plugin 格式
+# Agent Note: 静态 repository Plugin 格式
 
 状态：已实现
 
@@ -6,15 +6,15 @@
 
 ## 问题
 
-一个已经包含可复用 skills 或 MCP server 声明的仓库，应当能被独立 Harness 应用使用，而不必先变成 Harness SDK 项目，也不应被迫改写现有布局。常见仓库只需新增一个 `.dsh-plugin` 目录，同时仍可把原有 skills 与 `.mcp.json` 放在仓库其他位置。与此同时，如果把任意仓库入口都当作 Cordis Plugin，就会让每个仓库成为新的无限制运行时扩展表面，并绕过现有的 skill 与 MCP 生命周期所有者。
+一个已经包含可复用 skills 或 MCP server 声明的仓库，应当能被独立 Harness 应用使用，而不必先变成 Harness SDK 项目，也不应被迫改写现有布局。常见仓库只需新增一个 `.dsh-plugin` 目录，同时仍可把原有 skills 与 `.mcp.json` 放在仓库其他位置。当同一个受信任包还携带原生 Cordis 代码时，这些可移植静态贡献仍需复用现有的 skill 与 MCP 生命周期所有者。
 
 [Package-manager-native repository cache](2026-07-30-package-manager-native-repository-cache.md) 会准备一个精确 package source，但有意不了解任何 DSH 格式。因此本层需要一种兼容 package manager 的创作格式、确定性的已准备产物，以及在 Loader dispose 和替换期间仍保持事务性的 Cordis 组合。
 
 ## 决策
 
-`@deepseek-ai/dsh-repository-plugin` 负责一个受限的 `.dsh-plugin` package 格式，且只允许两类贡献：skill 根和一个通用 `.mcp.json`。Package metadata 使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径；两者至少需要一个。路径可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的 Plugin 可以拥有其 package 上方相邻的子树，却不能访问无关宿主路径。
+`@deepseek-ai/dsh-repository-plugin` 负责 `.dsh-plugin` 包内的静态贡献子格式：skill 根和一个通用 `.mcp.json`。其包元数据使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径。每条路径都可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的插件可以拥有其包上方相邻的子树，却不能访问无关宿主路径。该包还可以声明由[受信任 repository 包决策](2026-08-08-trusted-repository-package-code.md)负责的显式代码入口，并且至少需要一种代码或静态贡献。
 
-`.dsh-plugin` 包声明精确的 `scripts.prepack: "dsh-plugin-prepare"` 元数据，且不依赖 DSH NPM 包。在 Git 安装期间，独立运行时会从自身构建产物中临时提供该命令，并将其放入隔离的生命周期 `PATH`；`prepack` 会在依赖安装后、pnpm 打包选定子目录前运行，即使插件嵌套在另一个包管理器工作区内也不例外。该辅助程序会校验元数据与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`；源码 loader 会在导入该包装层前重新校验已安装包的精确生命周期元数据。`.mjs` 扩展名避免强迫仓库作者在包元数据中设置 `type: module`。生成模块来自固定、无 import 的模板，只包含规范化 manifest、由 manifest 派生的 `inject` 列表（`loader`，加上按声明能力加入的 `skills`／`tools`，使包装 fiber 在其子插件所需服务上门控），以及对 `dsh-repository-plugin` Loader builtin 的委托。准备阶段永远不会发现、转译、打包或保留自定义仓库入口。宿主自有命令的设计依据见[Git 源准备修复](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
+`.dsh-plugin` 包声明非空 `scripts.prepack`，调用 `dsh-plugin-prepare` 且不依赖 DSH NPM 包。在 Git 安装期间，独立运行时会从自身构建产物中临时提供该命令，并将其放入隔离的生命周期 `PATH`；`prepack` 会在依赖安装后、pnpm 打包选定子目录前运行，即使插件嵌套在另一个包管理器工作区内也不例外。包可以先构建其代码。该辅助程序会校验元数据与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`；源码 loader 会在导入该包装层前重新校验已安装包的生命周期元数据是否包含辅助命令。仅含静态贡献的包仍会获得无 import 包装层，其中包含规范化 manifest（元数据清单）、由服务派生的 `inject` 列表，以及对 `dsh-repository-plugin` Loader builtin 的委托。宿主自有命令的设计依据见[Git 源准备修复](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
 
 加载 DSH package 会以 effect 方式注册该 builtin。生成的包装模块使用 `import.meta.url` 把 builtin 挂载为自己的子级，因此所有贡献都归属于包装 fiber，并在 Loader 移除或回滚时消失。Builtin 会在读取资源前重新校验已准备 manifest 与路径包含关系。它只组合现有实现，而不自行注册 skills 或 MCP 工具。
 
@@ -22,11 +22,11 @@
 
 `.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配层接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。严格的 `${NAME}` 进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。因此 MCP 连接失败会继续沿用“Plugin 成功但不注册工具”的既有行为，不会被重新分类为 repository 准备或 Loader 失败。
 
-未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容契约。Hooks、commands、agents、apps、任意 Cordis 代码、marketplace 和发现同样不受支持。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本格式 package。
+未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容契约。命令、hook、agent（智能体）、规则和其他外来 manifest 约定不会从静态 repository 布局中推断出来；DSH 原生行为使用显式的受信任 Cordis 入口。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本静态适配器。
 
 ## 考虑过的替代方案
 
-**加载仓库自己的 Cordis 入口。** 拒绝，因为这会把宣传为静态的格式变成无限制代码加载 API，要求仓库作者依赖 Harness 内部实现，并重复普通 SDK／Plugin dependency 路径。
+**从 `main`、`exports` 或 repository 布局中发现入口。** 拒绝，因为静态资源并不表示包的普通入口就是 Cordis 插件。受信任代码通过 `dsh.entry` 显式加载，不属于该静态适配器的职责。
 
 **让生成包装模块直接实现 skills 和 MCP。** 拒绝，因为复制的运行时代码会与 `dsh-skill-local` 和 `dsh-mcp-client` 漂移，尤其是提供方失效、工具同步、失败和 teardown 契约。
 
@@ -39,11 +39,11 @@
 ## 后果
 
 - 现有 skill／MCP 仓库可以新增一个很小的 `.dsh-plugin/package.json`，无需移动资源或采用 SDK 项目。
-- 已准备输出是确定性的静态胶水；已配置仓库及其依赖生命周期仍是受信任的可执行 package-manager 输入，而非 sandbox。
+- 已准备的静态输出是确定性胶水；可选的 `dsh.entry` 和已配置的 repository 生命周期仍是受信任的可执行包管理器输入，而非沙箱。
 - 多个 repository Plugin 通过提供方名称和普通 MCP server-name 唯一性共存；重复名称经现有 registry 失败，并参与 Loader 回滚。
 - Cache 内的源码编辑不会实时出现；必须选择另一个精确 source／ref／path／config。
-- 新增贡献类型必须提供显式格式和 DSH 自有运行时消费方；它不能意外以 repository JavaScript 形式进入。
+- 新增可移植静态贡献类型必须提供显式格式和 DSH 自有运行时消费方；DSH 原生行为使用独立的显式代码入口。
 
 ## 测试
 
-聚焦测试会准备 skills 与 MCP metadata，证明生成包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。CI 的构建入口验收会用锁定到 PR（Pull Request）head 的 GitHub 源调用 `dsh run`，通过作业作用域的 Git 配置认证私有 PR 仓库，让随附 pnpm 获取并准备其中不含依赖的 fixture（测试前置数据），然后在真实模型请求中观察已复制的 skill，并在不可变缓存中观察已准备的包装模块。
+聚焦测试会准备 skill 与 MCP 元数据，证明仅含静态贡献的包装模块不含 import，拒绝 Work IQ 风格的 OAuth 字段，映射 Expo 风格 HTTP 与 DataJunction 风格 stdio 及环境变量，并覆盖缺失变量。真实 Loader 测试通过已注册 builtin 挂载生成包装模块，经 `ctx.skills` 读取其 skill，移除 Loader 条目并观察提供方清理。CI 构建入口验收会使用锁定到 PR（Pull Request）head 的 GitHub 源调用 `dsh run`，并观察已复制的 skill，以及由取代本决策的新决策所负责的受信任代码与 MCP 验证证据。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
new file mode 100644
index 0000000000..eeea186c92
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.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/architecture/2026-08-08-trusted-repository-package-code.md
+2026-08-08-trusted-repository-package-code.md: 4968d29a6da4180a8b016eef9176acb9bc64d8b1
+2026-08-08-trusted-repository-package-code.zh.md: 2e9f59bb1f571bb1bace9623a9e6976e0238a017
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
new file mode 100644
index 0000000000..4968d29a6d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
@@ -0,0 +1,51 @@
+# Agent Note: Trusted repository packages load Cordis code
+
+Status: implemented
+
+English | [中文](2026-08-08-trusted-repository-package-code.zh.md)
+
+## Problem
+
+The standalone repository format already installs a selected Git package and runs its dependency and lifecycle code with host authority, but it exposed only copied skills and MCP metadata to DSH. Forbidding a Cordis entry did not create a security boundary: package installation remained trusted executable code while the restriction prevented the package from contributing the Plugin behavior that the Harness architecture is designed to compose.
+
+A repository author also needs to keep an ordinary TypeScript npm package shape. Requiring publication to npm, pre-generated JavaScript in Git, or a DSH-owned TypeScript compiler would make a Git source less capable than the same package installed through a developer-owned SDK project. The first model request must observe any MCP tools that this package starts; background-only initial discovery makes a successful installation nondeterministic at the application boundary.
+
+## Decision
+
+A configured repository package is trusted code. Its `.dsh-plugin/package.json` may declare `dsh.entry` as a relative path to a compiled ESM Cordis Plugin inside that package, alongside or instead of `dsh.skills` and `dsh.mcpServers`. At least one contribution is required. The entry may use namespace exports or a default export and retains ordinary Cordis semantics for `name`, `inject`, `Config`, registrations, startup failure, and effect-scoped teardown.
+
+The package owns its npm dependencies and build toolchain. `scripts.prepack` is a non-empty package-authored command that must invoke the host-supplied `dsh-plugin-prepare`, but it may first run `tsc`, `tsdown`, or any other build. DSH neither parses the shell program nor compiles repository source. The helper validates the metadata after the preceding build, requires the configured entry to resolve to a file within `.dsh-plugin`, validates and copies declared static assets, and writes the prepared `dsh-plugin.mjs` wrapper. The installed package must retain a `prepack` declaration containing that helper command; missing wrapper or build outputs fail before a cache generation becomes usable.
+
+The generated wrapper first mounts the DSH-owned static runtime for skills and MCP definitions, then dynamically imports and unwraps the explicit entry and mounts it as a child. Both children must reach Cordis `ACTIVE`; an unsatisfied `inject` or startup exception rejects the repository Loader transaction instead of committing an inert generation. Loader removal, failed replacement, and parent disposal unwind the entry, skill providers, MCP clients, and their effects together.
+
+`dsh-mcp-client` resolves its initial connection and tool synchronization promise as part of Plugin application. A valid server's tools therefore exist before its parent repository wrapper activates and before a one-shot application starts its first model request. Initial connection failure keeps the existing contained failure contract: it is logged, the client activates with no tools, and disposal still closes the transport.
+
+## Trust boundary
+
+Exact refs, source containment, credential-shaped environment scrubbing, prepared manifests, and immutable cache keys protect identity and composition integrity; they do not sandbox executable package input. Repository lifecycle scripts, transitive npm dependencies, the compiled entry, and spawned MCP servers can exercise the authority available to the DSH process and the Cordis services they receive. Users must therefore trust the selected repository and should pin immutable refs and grant Git only the narrow read credential needed for acquisition.
+
+Model-visible behavior remains governed by the owning DSH seam. A repository entry may register tools, prompt sections, policies, commands, agents, or other effects, but anything reaching a model request still needs the corresponding logged DSH representation and lifecycle cleanup. The repository format grants code loading; it does not weaken those service contracts.
+
+## Alternatives considered
+
+**Keep code forbidden while allowing arbitrary package lifecycles.** Rejected because installation already executes trusted repository code, so the restriction added no isolation and forced Plugin authors to publish or maintain a second integration path.
+
+**Have DSH compile repository TypeScript.** Rejected because compiler choice, module layout, generated chunks, native dependencies, and package metadata belong to the npm package. Running the package's declared build preserves the same boundary as other Git dependencies.
+
+**Import `main`, `exports`, or another discovered entry implicitly.** Rejected because an npm package may contain utilities or an MCP executable that is not a Cordis Plugin. The explicit `dsh.entry` field makes code activation reviewable and lets preparation validate the packed path.
+
+**Add a closed manifest field for every future DSH contribution.** Rejected as the universal extension mechanism. Skills and common MCP files retain useful portable static adapters, while DSH-native behavior composes through the existing Cordis Plugin and service contracts.
+
+## Consequences
+
+- A TypeScript DSH Plugin can live in a GitHub repository, install ordinary npm dependencies, compile during `prepack`, and run without publishing the Plugin package to npm.
+- Static-only repository packages remain valid and retain import-free wrappers; adding `dsh.entry` opts that package into runtime code import.
+- A package build, dependency install, entry import, unmet service, or Plugin startup failure prevents the candidate generation from replacing the last good configuration.
+- The initial MCP connection can lengthen application startup, while a contained connection failure still yields a running application with no tools from that server.
+- Repository code receives host authority, so source review and immutable pinning are operational security requirements rather than optional hardening.
+
+## Testing
+
+Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication while preserving contained connect failure and teardown.
+
+The Node 24 consumer acceptance uses the actual built `dsh run` command with a fresh DSH home and an authenticated private GitHub source pinned to the pull request's exact head SHA. That repository package installs pinned runtime and development dependencies, type-checks and bundles TypeScript during `prepack`, prepares a skill plus a stdio MCP server and `dsh.entry`, exposes the skill and MCP schema in the first real model request, executes the MCP tool, and lets the compiled Cordis entry append a second marker to the result observed in the following request. Cache assertions require source files to be absent from the packed installation while both built modules, their installed dependency, copied assets, and generated wrapper are present.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
new file mode 100644
index 0000000000..2e9f59bb1f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
@@ -0,0 +1,51 @@
+# Agent Note: 受信任 repository 包加载 Cordis 代码
+
+状态：已实现
+
+[English](2026-08-08-trusted-repository-package-code.md) | 中文
+
+## 问题
+
+独立 repository 格式已经会安装选定的 Git 包，并以宿主权限运行其依赖和生命周期代码，但它向 DSH 暴露的只有复制后的 skill（技能）和 MCP 元数据。禁止 Cordis 入口并未建立安全边界：包安装过程仍会执行受信任代码，而这项限制却阻止包贡献 Harness 架构本就用于组合的插件行为。
+
+仓库作者还需要保持普通 TypeScript NPM 包的结构。如果要求发布到 NPM、把预生成的 JavaScript 签入 Git，或使用 DSH 自有的 TypeScript 编译器，Git 源的能力就会弱于通过开发者自有 SDK 项目安装的同一个包。首个模型请求必须看到该包启动的所有 MCP 工具；仅在后台进行初始发现，会让一次成功安装在应用边界上具有不确定性。
+
+## 决策
+
+已配置的 repository 包是受信任代码。其 `.dsh-plugin/package.json` 可以连同 `dsh.skills` 和 `dsh.mcpServers` 声明 `dsh.entry`，也可以用它取代二者；`dsh.entry` 是指向该包内已编译 ESM Cordis 插件的相对路径。至少需要一种贡献。入口可以使用 namespace 导出或 default export，并沿用 Cordis 对 `name`、`inject`、`Config`、注册、启动失败和 effect 作用域清理的常规语义。
+
+包自行负责其 NPM 依赖和构建工具链。`scripts.prepack` 是由包作者编写的非空命令，必须调用宿主提供的 `dsh-plugin-prepare`，但可以先运行 `tsc`、`tsdown` 或其他任意构建。DSH 既不解析该 shell 程序，也不编译 repository 源码。辅助程序会在前序构建之后校验元数据，要求已配置入口解析到 `.dsh-plugin` 内的文件，校验并复制已声明的静态资源，再写入已准备的 `dsh-plugin.mjs` 包装层。已安装包必须保留包含该辅助命令的 `prepack` 声明；包装层或构建输出缺失会在缓存 generation 可用前导致失败。
+
+生成的包装层先挂载 DSH 自有的静态运行时来处理 skill 和 MCP 定义，再动态导入显式入口、解包其导出并将其挂载为子级。两个子级都必须进入 Cordis `ACTIVE`；无法满足的 `inject` 或启动异常会拒绝 repository Loader 事务，而不会提交未激活的 generation。Loader 移除、替换失败和父级 dispose（资源释放）会一并撤销入口、skill 提供方、MCP client 及其 effect。
+
+`dsh-mcp-client` 会在插件应用期间完成其初始连接和工具同步 promise。因此，有效 server 的工具会在父级 repository 包装层激活前、一次性应用发起首个模型请求前就已存在。初始连接失败沿用既有的收束失败契约：系统会记录日志，client 激活但不注册工具，dispose 仍会关闭 transport。
+
+## 信任边界
+
+精确 ref、源路径包含约束、清除名称符合凭据模式的环境变量、已准备的 manifest（元数据清单）和不可变缓存键，可以保护身份与组合完整性；它们不会为可执行包输入提供沙箱隔离。Repository 生命周期脚本、传递性 NPM 依赖、已编译入口和 spawn 的 MCP server 可以行使 DSH 进程可用的权限，以及它们所获 Cordis 服务授予的权限。因此，用户必须信任所选仓库，应当固定不可变 ref，并只授予 Git 获取源码所需的最小只读凭据。
+
+模型可见行为仍由所属 DSH seam 管理。repository 入口可以注册工具、提示词段落、策略、命令、agent（智能体）或其他 effect，但任何进入模型请求的内容仍须具有对应的 DSH 日志表示和生命周期清理。repository 格式授予代码加载能力；它不会削弱这些服务契约。
+
+## 考虑过的替代方案
+
+**继续禁止代码，但允许任意包生命周期。** 拒绝，因为安装过程本就执行受信任的 repository 代码，所以该限制没有提供隔离，反而迫使插件作者发布或维护第二条集成路径。
+
+**由 DSH 编译 repository TypeScript。** 拒绝，因为编译器选择、模块布局、生成分片、原生依赖和包元数据属于 NPM 包。运行包所声明的构建，可以保持与其他 Git 依赖相同的边界。
+
+**隐式导入 `main`、`exports` 或其他发现的入口。** 拒绝，因为 NPM 包可能包含并非 Cordis 插件的实用工具或 MCP 可执行文件。显式 `dsh.entry` 字段使代码激活可供评审，并让准备阶段校验打包后的路径。
+
+**为未来每种 DSH 贡献添加封闭 manifest 字段。** 不采用它作为通用扩展机制。skill 和通用 MCP 文件仍保留有用的可移植静态适配器；DSH 原生行为则通过现有 Cordis 插件与服务契约组合。
+
+## 后果
+
+- TypeScript DSH 插件可以存放在 GitHub 仓库中，安装普通 NPM 依赖，在 `prepack` 期间完成编译，并在无需把插件包发布到 NPM 的情况下运行。
+- 仅含静态贡献的 repository 包仍然有效，并保留无 import 包装层；添加 `dsh.entry` 会使该包选择启用运行时代码导入。
+- 包构建、依赖安装、入口导入、所需服务未满足或插件启动失败，都会阻止候选 generation 替换最后一个可用配置。
+- 初始 MCP 连接可能延长应用启动时间；连接失败被收束后，仍会得到一个正常运行、但不含该 server 工具的应用。
+- Repository 代码获得宿主权限，因此源码评审和锁定不可变 ref 是运行安全要求，而不是可选加固措施。
+
+## 测试
+
+repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，同时保留收束连接失败与清理覆盖。
+
+Node 24 消费方验收使用实际构建的 `dsh run` 命令、全新 DSH 主目录，以及锁定到 PR（Pull Request）的精确 head SHA 且经过认证的私有 GitHub 源。该 repository 包安装固定版本的运行时依赖与开发依赖，在 `prepack` 期间对 TypeScript 进行类型检查和打包，准备一个 skill、一个 stdio MCP server 及 `dsh.entry`，在首个真实模型请求中暴露 skill 与 MCP schema，执行 MCP 工具，并让已编译 Cordis 入口向结果追加第二个标记，供后续请求观察。缓存断言要求打包安装中不存在源码文件，同时必须存在两个已构建模块、其已安装依赖、复制资源和生成包装层。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
index 39a7548d24..d3f10b5273 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.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 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
-2026-08-08-host-owned-git-repository-plugin-preparation.md: 47410bf3c55455a971ec347eab4e8b37ea26c6a5
-2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: 64c37543d34147c41fc7a362040c7ada8fde0652
+2026-08-08-host-owned-git-repository-plugin-preparation.md: b459184f802981f91f611b0b781651cede0c9efd
+2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: 5e24efa59ce44ffa8214f9c5ef9ff722ac0ca73a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
index 47410bf3c5..b459184f80 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
@@ -14,11 +14,11 @@ The checked-in headless fixture did not catch either defect because it mounted a
 
 ## Decision
 
-The fixed authoring format now requires exact `scripts.prepack: "dsh-plugin-prepare"` metadata and no DSH dependency. pnpm's Git-hosted package preparation invokes `prepack` explicitly after its dependency-install step and before packlist selects the `.dsh-plugin` subtree, so the helper can still copy sibling repository assets such as `../skills` into the package.
+The authoring format requires a non-empty `scripts.prepack` that invokes `dsh-plugin-prepare` and needs no DSH dependency for that helper. The package may declare its own build and runtime dependencies and run compilation before the helper. pnpm's Git-hosted package preparation invokes `prepack` explicitly after its dependency-install step and before packlist selects the `.dsh-plugin` subtree, so the helper can validate built entries and still copy sibling repository assets such as `../skills` into the package.
 
 `@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. The command directory exists only for the installation transaction and is removed on success or failure. The repository remains trusted package-manager input: DSH supplies one command, but other lifecycle scripts and dependencies still execute under the existing trust contract.
 
-The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Because that repository is private, the workflow writes a job-scoped Git configuration that uses the read-only job token for GitHub HTTPS and rewrites pnpm's SSH fallback to that authenticated transport. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true`, dependency-free GitHub fixture. It requires the run to reach the mock LLM, finds the repository skill description in the actual model request, and verifies the generated wrapper and copied skill under the immutable DSH cache. The test fails if CI omits the exact source instead of silently skipping.
+The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Because that repository is private, the workflow writes a job-scoped Git configuration that uses the read-only job token for GitHub HTTPS and rewrites pnpm's SSH fallback to that authenticated transport. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true` GitHub fixture. That fixture installs pinned npm dependencies, type-checks and bundles a TypeScript Cordis entry and MCP server in `prepack`, invokes the host helper, and proves the skill, MCP call, and code entry through real model requests and immutable-cache artifacts. The test fails if CI omits the exact source instead of silently skipping.
 
 ## Alternatives considered
 
@@ -34,10 +34,10 @@ The Node 24 consumer lane passes an exact source derived from the pull request h
 
 - A repository author can commit the fixed `.dsh-plugin/package.json` and source assets to GitHub without publishing either the Plugin or its preparation helper to npm.
 - Private GitHub sources use the host's standard Git authentication. CI proves that path with a temporary read-only configuration rather than persistent runner credentials.
-- `prepack`, not `prepare`, is part of the pre-release authoring format. Invalid lifecycle metadata fails during source preparation or installed-package validation instead of producing an ambiguous partial format.
+- `prepack`, not `prepare`, is part of the pre-release authoring format. It may contain package-owned build steps but must invoke the host helper; missing or empty lifecycle metadata fails installed-package validation instead of producing an ambiguous partial format.
 - Exact source strings still identify immutable cache generations; a changed ref or source configuration selects another generation.
-- This repair does not expand the contribution surface: prepared repository Plugins still contribute only declared skills and common MCP definitions, while arbitrary package lifecycle code remains trusted installation code rather than a model-facing Cordis Plugin API.
+- The host supplies only the preparation executable. Package dependencies, compilation, and the trusted `dsh.entry` contribution remain owned by the repository package and the [trusted-code decision](../architecture/2026-08-08-trusted-repository-package-code.md).
 
 ## Testing
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins the exact `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, real headless composition, mock LLM request observation, and prepared cache inspection.
+`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
index 64c37543d3..5e24efa59c 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
@@ -14,11 +14,11 @@ repository 插件的创作契约依赖 `scripts.prepare: "dsh-plugin-prepare"`
 
 ## 决策
 
-修复后的创作格式要求元数据中精确包含 `scripts.prepack: "dsh-plugin-prepare"`，且不包含 DSH 依赖。pnpm 针对 Git 托管包的准备流程会在依赖安装步骤之后、打包清单选择 `.dsh-plugin` 子树之前显式调用 `prepack`，因此辅助程序仍可将 `../skills` 等同仓库的相邻资源复制进包内。
+创作格式要求 `scripts.prepack` 非空且调用 `dsh-plugin-prepare`，使用该辅助程序无需 DSH 依赖。包可以声明自己的构建依赖与运行时依赖，并在调用辅助程序前完成编译。pnpm 针对 Git 托管包的准备流程会在依赖安装步骤之后、打包清单选择 `.dsh-plugin` 子树之前显式调用 `prepack`，因此辅助程序可以校验构建入口，并继续把 `../skills` 等同仓库的相邻资源复制进包内。
 
 `@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。该命令目录仅存在于安装事务期间，无论成功还是失败都会被移除。仓库仍是受信任的包管理器输入：DSH 仅提供这一条命令，其他生命周期脚本和依赖仍会按既有信任契约执行。
 
-Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。由于该仓库为私有仓库，工作流会写入一份作业作用域的 Git 配置，使用该作业的只读 token 对 GitHub HTTPS 连接进行认证，并将 pnpm 的 SSH 回退路径重写为这一已认证的传输方式。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true`、不含依赖的 GitHub fixture。验收要求该次运行到达 mock LLM（大语言模型），在实际模型请求中找到 repository skill 描述，并验证不可变 DSH 缓存中的生成包装层和已复制 skill。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
+Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。由于该仓库为私有仓库，工作流会写入一份作业作用域的 Git 配置，使用该作业的只读 token 对 GitHub HTTPS 连接进行认证，并将 pnpm 的 SSH 回退路径重写为这一已认证的传输方式。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true` 的 GitHub fixture。该 fixture 安装固定版本的 NPM 依赖，在 `prepack` 中对 TypeScript Cordis 入口和 MCP server 进行类型检查与打包，调用宿主辅助程序，并通过真实模型请求和不可变缓存产物验证 skill（技能）、MCP 调用和代码入口。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
 
 ## 考虑过的替代方案
 
@@ -34,10 +34,10 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 
 
 - 仓库作者可以把修复后的 `.dsh-plugin/package.json` 和源资源提交到 GitHub，而无需把插件或其准备辅助程序发布到 NPM。
 - 私有 GitHub 源使用宿主的标准 Git 认证。CI 使用临时的只读配置而非运行器上的持久凭据来验证该路径。
-- 预发布创作格式使用 `prepack` 而不是 `prepare`。无效的生命周期元数据会在源码准备或已安装包校验阶段导致失败，而不会留下状态不明的半成品格式。
+- 预发布创作格式使用 `prepack` 而不是 `prepare`。其中可以包含包自有构建步骤，但必须调用宿主辅助程序；生命周期元数据缺失或为空会在已安装包校验时失败，而不会留下状态不明的半成品格式。
 - 精确源字符串仍标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
-- 本次修复不扩大贡献范围：已准备的 repository 插件仍只贡献已声明的 skills 和通用 MCP 定义，而任意包生命周期代码仍是受信任的安装代码，不是面向模型的 Cordis 插件 API。
+- 宿主只提供准备阶段可执行文件。包依赖、编译和受信任的 `dsh.entry` 贡献仍由 repository 包和[受信任代码决策](../architecture/2026-08-08-trusted-repository-package-code.md)负责。
 
 ## 测试
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定精确的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、真实 headless 组合、mock LLM 请求观测，以及对已准备缓存的检查。
+`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及对已准备缓存的检查。
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
index 1491968f15..cee151c1ed 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.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 .agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
-2026-07-30-config-only-repository-plugins.md: 2057125fc78596dd4e5eb153f77b828f83d9ceff
-2026-07-30-config-only-repository-plugins.zh.md: 6e741b46be716e21a11c2f508fb5e6d0505c76d0
+2026-07-30-config-only-repository-plugins.md: 1564a847ccef877a6cc91827e195aa04711d09ce
+2026-07-30-config-only-repository-plugins.zh.md: 8e8de1e6edc356c9bb9ab55f01b6cce7608358e7
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
index 2057125fc7..1564a847cc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
@@ -6,13 +6,13 @@ English | [中文](2026-07-30-config-only-repository-plugins.zh.md)
 
 ## Problem
 
-A standalone `dsh` user has no developer-owned SDK project whose `package.json`, lockfile, and `cordis.yml` can carry an external Plugin dependency. Requiring an install command or another state file would make “use this repository” a multi-step workflow, while loading arbitrary repository code would bypass the restricted [static repository Plugin format](../architecture/2026-07-30-static-repository-plugin-format.md). Long-running TUI and Web processes also need a failed edit to preserve their usable Plugin generation and tell observers why the candidate was rejected.
+A standalone `dsh` user has no developer-owned SDK project whose `package.json`, lockfile, and `cordis.yml` can carry an external Plugin dependency. Requiring an install command or another state file would make “use this repository” a multi-step workflow, while trusted repository code still needs an exact-source, transactional lifecycle owned by the [repository package format](../architecture/2026-08-08-trusted-repository-package-code.md). Long-running TUI and Web processes also need a failed edit to preserve their usable Plugin generation and tell observers why the candidate was rejected.
 
 ## Decision
 
 The shipped TUI and Web/headless `cordis.yml` trees contain an empty `repository-plugins` entry. A user changes only `$DSH_HOME/config.yaml`, replacing that entry's config with a `repositories` list. Each item uses `github:owner/repository#<ref>` plus an optional `&path:/.../.dsh-plugin`; omission selects `/.dsh-plugin`. An explicit ref is mandatory, paths are absolute within the repository and end in `.dsh-plugin`, and duplicate normalized specifiers reject before installation. There is no marketplace, discovery index, HTTPS URL vocabulary, or implicit latest generation.
 
-`@deepseek-ai/dsh-repository-plugin` validates and normalizes each source, then resolves it through the generic vendored [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md). The default cache is `$DSH_HOME/cache/repository-plugins`; `cacheDir` is the explicit deployment override. Bundled pnpm selects the configured repository subpackage, runs its ordinary lifecycle including `prepare`, and atomically publishes the exact specifier. The DSH host imports only the generated `dsh-plugin.mjs` wrapper and mounts it as a child fiber, so skills and MCP retain the owners, failure contracts, and teardown defined by the format package.
+`@deepseek-ai/dsh-repository-plugin` validates and normalizes each source, then resolves it through the generic vendored [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md). The default cache is `$DSH_HOME/cache/repository-plugins`; `cacheDir` is the explicit deployment override. Bundled pnpm selects the configured repository subpackage, installs its dependencies, runs its package-authored `prepack` and the host preparation helper, and atomically publishes the exact specifier. The DSH host imports the generated `dsh-plugin.mjs` wrapper and mounts it as a child fiber; that wrapper composes static skill and MCP owners plus an explicit trusted Cordis entry when declared.
 
 ## Live update and failure
 
@@ -24,7 +24,7 @@ An identical specifier permanently reuses its cache generation. HMR watches conf
 
 ## Trust boundary
 
-Configuring a repository authorizes package-manager lifecycle code from that repository and its dependencies to run with the user's filesystem authority. The pnpm child removes ambient environment variables whose names contain `KEY`, `PASSWORD`, `SECRET`, or `TOKEN`, but this is credential-exposure reduction rather than a sandbox. The fixed runtime wrapper prevents repository-authored Cordis entry points from becoming part of the supported Plugin format; it does not make package preparation untrusted-safe.
+Configuring a repository authorizes package-manager lifecycle code, dependencies, the explicit `dsh.entry`, and spawned MCP servers from that repository to run with the user's filesystem authority. The pnpm child removes ambient environment variables whose names contain `KEY`, `PASSWORD`, `SECRET`, or `TOKEN`, but this is credential-exposure reduction rather than a sandbox. The prepared wrapper validates composition boundaries and lifecycle state; it does not make repository code safe to run when the source is untrusted.
 
 ## Alternatives considered
 
@@ -43,7 +43,7 @@ Configuring a repository authorizes package-manager lifecycle code from that rep
 - A repository that adds `.dsh-plugin/package.json` can reach standalone users through one personal-config edit without changing its existing skills or `.mcp.json` layout.
 - Long-running apps can add, replace, or remove configured generations without restart; rejected candidates retain the last good runtime and produce one generic Cordis event.
 - First use may require Git/network access and preparation time. Later starts reuse the exact prepared cache; old generations consume disk until a separate cache-management policy exists.
-- Only skills and common MCP definitions are supported. Hooks, commands, agents, apps, arbitrary Cordis code, compatibility shims, OAuth-bearing MCP definitions, and marketplaces remain intentionally absent.
+- Skills and common MCP definitions retain portable static adapters, while an explicit `dsh.entry` can contribute DSH-native Cordis behavior. Format-specific compatibility shims, OAuth-bearing MCP definitions, and marketplaces remain intentionally absent.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
index 6e741b46be..8e8de1e6ed 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-独立 `dsh` 用户没有开发者自有的 SDK 项目，无法由其 `package.json`、lockfile 和 `cordis.yml` 承载外部插件依赖。若要求运行安装命令或维护另一份状态文件，「使用这个仓库」就会变成多步骤流程；若加载任意仓库代码，又会绕过受限的[静态仓库插件格式](../architecture/2026-07-30-static-repository-plugin-format.md)。长时间运行的 TUI 和 Web 进程还必须在编辑失败时保留仍可使用的插件版本，并向观察者说明候选配置被拒绝的原因。
+独立 `dsh` 用户没有开发者自有的 SDK 项目，无法由其 `package.json`、lockfile 和 `cordis.yml` 承载外部插件依赖。若要求运行安装命令或维护另一份状态文件，「使用这个仓库」就会变成多步骤流程；受信任的 repository 代码仍需要由[repository 包格式](../architecture/2026-08-08-trusted-repository-package-code.md)负责一套锁定精确来源且具事务性的生命周期。长时间运行的 TUI 和 Web 进程还必须在编辑失败时保留仍可使用的插件版本，并向观察者说明候选配置被拒绝的原因。
 
 ## 决策
 
 已交付的 TUI 和 Web／无头 `cordis.yml` 配置树包含一个空的 `repository-plugins` 配置项。用户只需修改 `$DSH_HOME/config.yaml`，用 `repositories` 列表替换该配置项的配置。每一项采用 `github:owner/repository#<ref>`，并可追加 `&path:/.../.dsh-plugin`；省略时选择 `/.dsh-plugin`。必须显式指定 ref；路径是仓库内的绝对路径，并以 `.dsh-plugin` 结尾；重复的规范化说明符在安装前即被拒绝。不提供插件市场、发现索引、HTTPS URL 词汇或隐式的最新版本。
 
-`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择配置的仓库子包（package），运行包括 `prepare` 在内的普通生命周期，并原子发布该精确说明符。DSH 宿主只导入生成的 `dsh-plugin.mjs` 包装模块并将其挂载为子 fiber，因此 skill（技能）与 MCP 仍沿用格式包定义的所有者、失败契约和清理行为。
+`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择已配置的 repository 子包，安装其依赖，运行包所定义的 `prepack` 与宿主准备辅助程序，并原子发布该精确说明符。DSH 宿主会导入生成的 `dsh-plugin.mjs` 包装层并将其挂载为子 fiber；该包装层组合静态 skill（技能）与 MCP 所有者，并在声明时组合显式的受信任 Cordis 入口。
 
 ## 实时更新与失败
 
@@ -24,7 +24,7 @@ Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader
 
 ## 信任边界
 
-配置仓库即授权该仓库及其依赖中的包管理器生命周期代码以用户的文件系统权限运行。pnpm 子进程会移除名称中含有 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN` 的环境变量，但这只会减少凭据暴露，并非沙箱。固定的运行时包装模块会阻止仓库作者提供的 Cordis 入口成为受支持插件格式的一部分；它无法让包准备过程安全执行不受信任的代码。
+配置仓库即授权该仓库中的包管理器生命周期代码、依赖、显式 `dsh.entry` 和 spawn 的 MCP server 以用户的文件系统权限运行。pnpm 子进程会移除名称中含有 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN` 的环境变量，但这只会减少凭据暴露，并非沙箱。已准备的包装层会校验组合边界和生命周期状态；当来源不受信任时，它无法让 repository 代码变得可安全运行。
 
 ## 考虑过的替代方案
 
@@ -43,7 +43,7 @@ Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader
 - 添加 `.dsh-plugin/package.json` 的仓库只需一次个人配置编辑即可供独立用户使用，无需改变现有 skill 或 `.mcp.json` 布局。
 - 长时间运行的应用无需重启即可新增、替换或移除已配置版本；被拒绝的候选配置会保留最后一个可用运行时，并产生一个通用 Cordis 事件。
 - 首次使用可能需要 Git／网络访问和准备时间。后续启动会复用这份精确的已准备缓存；在另行制定缓存管理政策之前，旧版本会持续占用磁盘空间。
-- 仅支持 skill 和通用 MCP 定义。钩子、命令、agent（智能体）、应用、任意 Cordis 代码、兼容 shim、带 OAuth 的 MCP 定义和插件市场均有意不提供。
+- skill 和通用 MCP 定义保留可移植静态适配器，而显式 `dsh.entry` 可以贡献 DSH 原生 Cordis 行为。格式专用的兼容 shim、带 OAuth 的 MCP 定义和插件市场仍有意不提供。
 
 ## 测试
 
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/.mcp.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/.mcp.json
new file mode 100644
index 0000000000..4851f9f1f8
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/.mcp.json
@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "github_repository": {
+      "command": "node",
+      "args": [
+        "lib/mcp-server.mjs"
+      ]
+    }
+  }
+}
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
index 9ce1527d03..b11ea67c41 100644
--- a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
@@ -2,12 +2,28 @@
   "name": "dsh-github-repository-plugin-e2e-fixture",
   "version": "0.0.0",
   "private": true,
+  "type": "module",
+  "files": [
+    "lib",
+    "dsh-plugin.mjs",
+    "dsh-plugin-assets"
+  ],
   "scripts": {
-    "prepack": "dsh-plugin-prepare"
+    "prepack": "tsc --noEmit && tsdown src/plugin.ts src/mcp-server.ts --no-config --tsconfig tsconfig.json --out-dir lib --platform node --target es2024 --clean && dsh-plugin-prepare"
   },
   "dsh": {
     "skills": [
       "../skills"
-    ]
+    ],
+    "mcpServers": "./.mcp.json",
+    "entry": "./lib/plugin.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "devDependencies": {
+    "cordis": "4.0.0-rc.7",
+    "tsdown": "0.22.2",
+    "typescript": "6.0.3"
   }
 }
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/mcp-server.ts b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/mcp-server.ts
new file mode 100644
index 0000000000..78a3e008f4
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/mcp-server.ts
@@ -0,0 +1,19 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+// The repository root's linter cannot resolve this independently installed
+// Git-package dependency; the package's prepack tsc validates the SDK types.
+/* oxlint-disable typescript/no-unsafe-assignment, typescript/no-unsafe-call, typescript/no-unsafe-member-access */
+const server = new McpServer({
+  name: 'github-repository-plugin-e2e',
+  version: '0.0.0',
+})
+
+server.registerTool('proof', {
+  description: 'Proves that an MCP server compiled from the exact GitHub repository package is active.',
+  inputSchema: {},
+}, async () => ({
+  content: [{ type: 'text', text: 'MCP_FROM_GITHUB_REPOSITORY' }],
+}))
+
+await server.connect(new StdioServerTransport())
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/plugin.ts b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/plugin.ts
new file mode 100644
index 0000000000..5106f71b2f
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/src/plugin.ts
@@ -0,0 +1,59 @@
+import type { Context } from 'cordis'
+
+const PROOF_TOOL_NAME = 'mcp__github_repository__proof'
+
+interface TextBlock {
+  readonly type: 'text'
+  readonly text: string
+}
+
+interface ToolExecution {
+  readonly name: string
+}
+
+interface ToolResult {
+  readonly isError: boolean
+  readonly content: readonly TextBlock[]
+}
+
+type PostDecision =
+  | { readonly kind: 'accept'; readonly content?: readonly TextBlock[]; readonly value?: unknown; readonly additionalContexts?: readonly unknown[] }
+  | { readonly kind: 'block'; readonly feedback: readonly TextBlock[] }
+
+type PostListener = (
+  execution: ToolExecution,
+  result: ToolResult,
+  next: () => Promise<PostDecision>,
+) => Promise<PostDecision>
+
+type DshContext = Context & {
+  on(event: 'tools/post-execute', listener: PostListener): () => void
+}
+
+/** Cordis plugin name used by the repository acceptance fixture. */
+export const name = 'github-repository-typescript-proof'
+
+/** DSH tool registry required by the post-execute contribution. */
+export const inject = ['tools']
+
+/**
+ * Append a marker after the repository MCP proof tool succeeds.
+ * @param ctx - trusted DSH Cordis context supplied to the repository package.
+ */
+export function apply(ctx: Context): void {
+  const dsh = ctx as DshContext
+  dsh.on('tools/post-execute', async (execution, result, next): Promise<PostDecision> => {
+    const decision = await next()
+    if (execution.name !== PROOF_TOOL_NAME || result.isError || decision.kind !== 'accept' || Object.hasOwn(decision, 'value')) {
+      return decision
+    }
+    return {
+      kind: 'accept',
+      content: [
+        ...(decision.content ?? result.content),
+        { type: 'text', text: 'TS_PLUGIN_FROM_GITHUB_REPOSITORY' },
+      ],
+      ...decision.additionalContexts === undefined ? {} : { additionalContexts: decision.additionalContexts },
+    }
+  })
+}
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json
new file mode 100644
index 0000000000..632e4db48c
--- /dev/null
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}
diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index 7262ddeb58..0c13a71a02 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -1,4 +1,5 @@
 import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -13,7 +14,7 @@ const required = process.env.DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E === '1'
 const enabled = required || source !== undefined
 
 describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () => {
-  it('installs a private exact GitHub source and exposes its skill to the model', async () => {
+  it('installs, builds, and runs skill, MCP, and TypeScript Plugin contributions from a private exact GitHub source', async () => {
     expect(existsSync(dshBin), 'the repository Plugin acceptance must run the built dsh entry').toBe(true)
     expect(source, 'DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE is required by this CI lane').toMatch(
       /^github:[^/\s#&]+\/[^/\s#&]+#[0-9a-f]{40}&path:\/.*\/\.dsh-plugin$/u,
@@ -21,9 +22,11 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
 
     const apiKey = 'github-repository-plugin-e2e-key'
     const server = await startMockLlmServer({
-      sequence: ['success'],
+      sequence: ['tool_call_success', 'success'],
       apiKey,
-      successText: 'private GitHub repository Plugin reached dsh run',
+      toolName: 'mcp__github_repository__proof',
+      toolArguments: '{}',
+      successText: 'trusted GitHub repository package reached dsh run',
     })
     const home = mkdtempSync(join(tmpdir(), 'dsh-github-repository-plugin-'))
     const patch = join(home, 'github-repository-plugin.cordis.patch.yml')
@@ -45,7 +48,7 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       ], {
         cwd: repoRoot,
         input: '',
-        timeout: 120_000,
+        timeout: 180_000,
         killSignal: 'SIGKILL',
         reject: false,
         env: {
@@ -57,14 +60,20 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
         },
       })
       if (result.timedOut) {
-        throw new Error(`dsh GitHub repository Plugin run did not exit within 120s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
+        throw new Error(`dsh GitHub repository Plugin run did not exit within 180s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
       }
       expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}`).toBe(0)
-      expect(result.stdout).toBe('private GitHub repository Plugin reached dsh run')
-      expect(server.requests.length).toBeGreaterThan(0)
-      expect(JSON.stringify(server.requests.map(request => request.body))).toContain(
+      expect(result.stdout).toBe('trusted GitHub repository package reached dsh run')
+      expect(server.requests).toHaveLength(2)
+      const firstRequest = JSON.stringify(server.requests[0]!.body)
+      const secondRequest = JSON.stringify(server.requests[1]!.body)
+      expect(firstRequest).toContain(
         'Proves that dsh installed a private repository Plugin from an exact GitHub source.',
       )
+      expect(firstRequest).toContain('mcp__github_repository__proof')
+      expect(firstRequest).toContain('Proves that an MCP server compiled from the exact GitHub repository package is active.')
+      expect(secondRequest).toContain('MCP_FROM_GITHUB_REPOSITORY')
+      expect(secondRequest).toContain('TS_PLUGIN_FROM_GITHUB_REPOSITORY')
 
       const cacheRoot = join(home, 'cache', 'repository-plugins')
       const generations = readdirSync(cacheRoot, { withFileTypes: true }).filter(entry => entry.isDirectory())
@@ -74,16 +83,38 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       expect(manifest).toMatchObject({
         name: 'dsh-github-repository-plugin-e2e-fixture',
         private: true,
-        scripts: { prepack: 'dsh-plugin-prepare' },
+        scripts: {
+          prepack: 'tsc --noEmit && tsdown src/plugin.ts src/mcp-server.ts --no-config --tsconfig tsconfig.json --out-dir lib --platform node --target es2024 --clean && dsh-plugin-prepare',
+        },
+        dsh: {
+          skills: ['../skills'],
+          mcpServers: './.mcp.json',
+          entry: './lib/plugin.mjs',
+        },
+        dependencies: {
+          '@modelcontextprotocol/sdk': '1.29.0',
+        },
+        devDependencies: {
+          cordis: '4.0.0-rc.7',
+          tsdown: '0.22.2',
+          typescript: '6.0.3',
+        },
       })
-      expect(manifest).not.toHaveProperty('dependencies')
-      expect(manifest).not.toHaveProperty('devDependencies')
       expect(readFileSync(join(installed, 'dsh-plugin-assets/skills/0/github-source-proof/SKILL.md'), 'utf8'))
         .toContain('This skill exists only in the GitHub repository source fixture.')
-      expect(readFileSync(join(installed, 'dsh-plugin.mjs'), 'utf8')).toContain('dsh-repository-plugin')
+      expect(readFileSync(join(installed, 'dsh-plugin-assets/.mcp.json'), 'utf8')).toContain('lib/mcp-server.mjs')
+      expect(readFileSync(join(installed, 'lib/plugin.mjs'), 'utf8')).toContain('TS_PLUGIN_FROM_GITHUB_REPOSITORY')
+      expect(readFileSync(join(installed, 'lib/mcp-server.mjs'), 'utf8')).toContain('MCP_FROM_GITHUB_REPOSITORY')
+      expect(existsSync(join(installed, 'src'))).toBe(false)
+      const installedRequire = createRequire(join(installed, 'lib/mcp-server.mjs'))
+      expect(existsSync(installedRequire.resolve('@modelcontextprotocol/sdk/server/mcp.js'))).toBe(true)
+      const wrapper = readFileSync(join(installed, 'dsh-plugin.mjs'), 'utf8')
+      expect(wrapper).toContain('dsh-repository-plugin')
+      expect(wrapper).toContain('await import(manifest.entry)')
+      expect(wrapper).toContain('"entry":"./lib/plugin.mjs"')
     } finally {
       await server.close()
       rmSync(home, { recursive: true, force: true })
     }
-  }, 130_000)
+  }, 190_000)
 })
diff --git a/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs b/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
index 5515aa82a2..ce61e58973 100644
--- a/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
+++ b/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
@@ -1,9 +1,18 @@
 // Generated by dsh-plugin-prepare. Do not edit.
 const manifest = {"name":"headless-repository-fixture","skills":["dsh-plugin-assets/skills/0"]}
+const FIBER_ACTIVE = 2
 export const name = "headless-repository-fixture"
 export const inject = ["loader","skills"]
+async function mount(ctx, plugin, label, config) {
+  const fiber = ctx.plugin(plugin, config)
+  await fiber
+  if (fiber.state !== FIBER_ACTIVE) {
+    const missing = Object.keys(fiber.inject).filter(service => fiber.ctx.get(service) === undefined)
+    throw new Error(`${label} did not activate (waiting for services: ${missing.join(', ') || 'unknown'})`)
+  }
+}
 export async function apply(ctx) {
   const runtime = ctx.loader.builtins["dsh-repository-plugin"]
   if (runtime === undefined) throw new Error("missing Cordis builtin dsh-repository-plugin")
-  await ctx.plugin(runtime, { baseUrl: import.meta.url, manifest })
+  await mount(ctx, runtime, 'repository Plugin runtime', { baseUrl: import.meta.url, manifest })
 }
diff --git a/knip.json b/knip.json
index 63db33e51c..0757fe49f8 100644
--- a/knip.json
+++ b/knip.json
@@ -703,6 +703,17 @@
         "@deepseek-ai/.+"
       ]
     },
+    "apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin": {
+      "entry": [
+        "src/*.ts"
+      ],
+      "project": [
+        "src/**/*.ts"
+      ],
+      "ignoreBinaries": [
+        "dsh-plugin-prepare"
+      ]
+    },
     "packages/client/modules": {
       "entry": [
         "tests/**/*.spec.ts"
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index 9fa4504cca..6b6d4d9270 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-client/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/mcp/mcp-client/README.md
-README.md: d7966595c68ff1ec4a288caf5d9fe4b0bf580cc5
-README.zh.md: eb9e0dbdb48423cc4bc698fda355e973e42bc7a3
+README.md: 6bcc195e36d24d7e5ae3462573b30f1b41c963a7
+README.zh.md: 8886c16c3fe66d283ae2191661118729a89f1aeb
diff --git a/packages/mcp/mcp-client/README.md b/packages/mcp/mcp-client/README.md
index d7966595c6..6bcc195e36 100644
--- a/packages/mcp/mcp-client/README.md
+++ b/packages/mcp/mcp-client/README.md
@@ -56,7 +56,7 @@ Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`
 
 ## Behavior
 
-- On connect: `listTools()` → registers each tool via `ctx.tools.register()` under its public name.
+- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection failure is logged and activates with no tools.
 - Listens for `notifications/tools/list_changed` → re-syncs; a failed re-sync keeps the previous generation registered.
 - Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support—the public name is never sent to the server.
 - Canonical success is `{ content: JsonValue[], structuredContent? }`; complete JSON MCP blocks survive for programmatic callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`.
@@ -101,7 +101,6 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **Initial discovery is asynchronous** — plugin load does not wait for connection and `listTools()`, so a turn started immediately after boot or HMR can assemble before the MCP tools are registered.
 - **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumption surface and are deferred.
 - **Crash recovery is manual** — transport closure does not auto-reconnect; registered tools can remain visible but fail against the closed transport until an HMR reload or Host restart.
 - **Native non-text rendering is lossy** — image, audio, and resource payloads become placeholders in model context even though the execution-local canonical value preserves their JSON blocks. Richer Native multimedia projection is deferred.
diff --git a/packages/mcp/mcp-client/README.zh.md b/packages/mcp/mcp-client/README.zh.md
index eb9e0dbdb4..8886c16c3f 100644
--- a/packages/mcp/mcp-client/README.zh.md
+++ b/packages/mcp/mcp-client/README.zh.md
@@ -56,7 +56,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 行为
 
-- 连接时：`listTools()` → 通过 `ctx.tools.register()` 使用各自公开名称注册每个工具。
+- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接失败会记录日志，插件仍会激活但不注册工具。
 - 监听 `notifications/tools/list_changed` → 重新同步；同步失败时保留上一世代的注册。
 - 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
 - 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
@@ -101,7 +101,6 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 已知限制与暂缓事项
 
-- **初始发现是异步的**：插件加载不会等待连接和 `listTools()`，因此在启动或 HMR 后立即开始的轮次可能在 MCP 工具注册前完成组装。
 - **只桥接 MCP 的工具能力**：资源和提示词没有 harness 消费接口，暂缓实现。
 - **崩溃恢复需要手动触发**：传输关闭后不会自动重新连接；已注册工具可能仍然可见，但会因传输已关闭而调用失败，直到 HMR 重载或重启 Host。
 - **Native 非文本渲染有损**：图片、音频与资源载荷在模型上下文中会变成占位符，即使执行局部的规范值保留了其 JSON 块。更丰富的 Native 多媒体投影暂缓实现。
diff --git a/packages/mcp/mcp-client/src/index.ts b/packages/mcp/mcp-client/src/index.ts
index 49609bac9a..9798b4cfcb 100644
--- a/packages/mcp/mcp-client/src/index.ts
+++ b/packages/mcp/mcp-client/src/index.ts
@@ -116,7 +116,13 @@ export const Config = z.union([
 
 // ---- Plugin apply ----
 
-export function apply(ctx: Context, config: Config): void {
+/**
+ * Connect one MCP server and publish its initial tool generation before activation.
+ * @param ctx - plugin context carrying the tool registry.
+ * @param config - resolved transport and server namespace configuration.
+ * @returns startup readiness after connection and initial tool discovery settle.
+ */
+export function apply(ctx: Context, config: Config): Promise<void> {
   // Reserve the namespace first: a duplicate `serverName` fails THIS instance
   // at load with an actionable error and leaves the earlier instance intact.
   ctx.effect(() => {
@@ -179,4 +185,6 @@ export function apply(ctx: Context, config: Config): void {
     for (const dispose of live().values()) dispose()
     try { await client.close() } catch { /* transport already gone */ }
   }, 'mcp-client.connection')
+
+  return ready.then(() => undefined)
 }
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index 5836c74e5a..6bb97a7032 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -141,8 +141,7 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('connects, syncs tools under the namespace, and registers a notification handler', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     expect(mockConnect).toHaveBeenCalled()
     expect(mockListTools).toHaveBeenCalled()
@@ -152,11 +151,10 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('rejects a duplicate serverName at load and leaves the first instance intact', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
-    expect(() => { apply(ctx, stdioConfig) }).toThrow(/serverName "srv" is already in use/)
+    expect(() => { void apply(ctx, stdioConfig) }).toThrow(/serverName "srv" is already in use/)
     // First instance unaffected.
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
   })
@@ -165,8 +163,7 @@ describe('apply (plugin lifecycle)', () => {
     const first = new Context()
     await first.plugin(SystemPrompt)
     await first.plugin(ToolRegistry)
-    apply(first, stdioConfig)
-    await sleep(50)
+    await apply(first, stdioConfig)
 
     await first.fiber.dispose()
     await sleep(50)
@@ -176,16 +173,17 @@ describe('apply (plugin lifecycle)', () => {
     const second = new Context()
     await second.plugin(SystemPrompt)
     await second.plugin(ToolRegistry)
-    expect(() => { apply(second, stdioConfig) }).not.toThrow()
+    await expect(apply(second, stdioConfig)).resolves.toBeUndefined()
+    await second.fiber.dispose()
   })
 
   it('scopes serverName reservations per app root', async () => {
     const other = await mountRegistry()
 
-    apply(ctx, stdioConfig)
+    const first = apply(ctx, stdioConfig)
     // Same serverName on a DIFFERENT root is fine.
-    expect(() => { apply(other, stdioConfig) }).not.toThrow()
-    await sleep(50)
+    const second = apply(other, stdioConfig)
+    await Promise.all([first, second])
 
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
     expect(other.tools.get('mcp__srv__remote')).toBeDefined()
@@ -194,8 +192,7 @@ describe('apply (plugin lifecycle)', () => {
   it('logs error and registers no tools when connect fails; dispose is a no-op', async () => {
     mockConnect.mockRejectedValue(new Error('connection refused'))
 
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     expect(mockListTools).not.toHaveBeenCalled()
     expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
@@ -208,8 +205,7 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('re-syncs tools on ToolListChanged notification', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
@@ -226,8 +222,7 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('keeps the previous generation when a re-sync fails', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
     mockListTools.mockRejectedValue(new Error('flaky server'))
@@ -242,7 +237,7 @@ describe('apply (plugin lifecycle)', () => {
     // Load through ctx.plugin so ONLY the plugin's fiber is disposed — the
     // registry must survive to observe the unregistration.
     const fiber = ctx.plugin({ name: 'mcp-client', inject: ['tools'], apply }, stdioConfig)
-    await sleep(50)
+    await fiber
 
     // Advance to a second generation first.
     mockListTools.mockResolvedValue({
@@ -264,8 +259,7 @@ describe('apply (plugin lifecycle)', () => {
   it('effect disposer handles client.close failure gracefully', async () => {
     mockClose.mockRejectedValue(new Error('already closed'))
 
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     // Should not throw when dispose is triggered.
     await ctx.fiber.dispose()
@@ -283,8 +277,7 @@ describe('apply (plugin lifecycle)', () => {
       toolCallTimeoutMs: 30_000,
     }
 
-    apply(ctx, httpConfig)
-    await sleep(50)
+    await apply(ctx, httpConfig)
 
     expect(mockConnect).toHaveBeenCalled()
     expect(ctx.tools.get('mcp__web__remote')).toBeDefined()
diff --git a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
index 3ce25e9240..6a71ab4007 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
@@ -43,21 +43,6 @@ async function mountRegistry(): Promise<Context> {
   return ctx
 }
 
-/** Apply the MCP client plugin and wait for tools to be registered. */
-async function applyAndWait(ctx: Context, config: Config, timeoutMs = 20_000): Promise<void> {
-  // Annotated bindings (not withResolvers<void>()): the tests lint layer runs
-  // no-invalid-void-type with default options, which rejects the explicit
-  // type argument in call position but accepts the inferred form.
-  const gate: PromiseWithResolvers<void> = Promise.withResolvers()
-  const timer = setTimeout(
-    () => { gate.reject(new Error(`applyAndWait timed out after ${timeoutMs}ms — no tools/change event`)) },
-    timeoutMs,
-  )
-  ctx.on('tools/change', () => { clearTimeout(timer); gate.resolve() })
-  apply(ctx, config)
-  await gate.promise
-}
-
 function sleep(ms: number): Promise<void> {
   const gate: PromiseWithResolvers<void> = Promise.withResolvers()
   setTimeout(gate.resolve, ms)
@@ -94,7 +79,7 @@ describe('fixture server — controlled scenarios', () => {
 
   beforeAll(async () => {
     ctx = await mountRegistry()
-    await applyAndWait(ctx, fixtureConfig)
+    await apply(ctx, fixtureConfig)
   }, 30_000)
 
   afterAll(async () => {
@@ -180,9 +165,9 @@ describe('fixture server — duplicate serverName', () => {
       cwd: packageDir,
       toolCallTimeoutMs: 15_000,
     }
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
 
-    expect(() => { apply(ctx, config) }).toThrow(/serverName "dup" is already in use/)
+    expect(() => { void apply(ctx, config) }).toThrow(/serverName "dup" is already in use/)
 
     await ctx.fiber.dispose()
     await sleep(200)
@@ -192,7 +177,7 @@ describe('fixture server — duplicate serverName', () => {
 describe('fixture server — disposal', () => {
   it('disposes cleanly without error', async () => {
     const ctx = await mountRegistry()
-    await applyAndWait(ctx, {
+    await apply(ctx, {
       transport: 'stdio',
       serverName: 'fixture',
       command: process.execPath,
@@ -229,7 +214,7 @@ describe('server-everything — official test server', () => {
 
   beforeAll(async () => {
     ctx = await mountRegistry()
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
   }, 60_000)
 
   afterAll(async () => {
@@ -293,7 +278,7 @@ describe('server-filesystem — real filesystem operations', () => {
       cwd: '',
       toolCallTimeoutMs: 30_000,
     }
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
   }, 60_000)
 
   afterAll(async () => {
@@ -409,7 +394,7 @@ describe('streamable-http — in-process MCP server', () => {
       headers: { Authorization: 'Bearer e2e-test-token' },
       toolCallTimeoutMs: 15_000,
     }
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
   }, 30_000)
 
   afterAll(async () => {
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index 9720364496..7d7c04cf69 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 23c4cc0dceaf0692b7ef5067f9170b8c6b311cc0
-README.zh.md: db2f3e5a5c8915836d97177f797411e17e70441c
+README.md: 52d04f16684842749e57d1b47db0a95beb22558c
+README.zh.md: 921bf70b8a2e78410510d1efce79ced5f52b4641
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 23c4cc0dce..52d04f1668 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Restricted repository Plugin format for DeepSeek Harness. A repository author declares static skill roots and an optional common `.mcp.json` in `.dsh-plugin/package.json`; the prepare helper copies those assets and emits a fixed import-free Cordis wrapper. The runtime wrapper can only delegate to this DSH-owned package, which composes [`dsh-skill-local`](../../skill/skill-local/README.md) and [`dsh-mcp-client`](../../mcp/mcp-client/README.md). Design rationale: [static repository Plugin format Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md).
+Trusted repository package format for DeepSeek Harness. A `.dsh-plugin` npm package may contribute a compiled Cordis/DSH Plugin entry, skill roots, and a common `.mcp.json`; its ordinary `prepack` lifecycle owns dependency installation and source compilation before the DSH prepare helper validates the outputs and emits the Loader wrapper. Static contributions compose [`dsh-skill-local`](../../skill/skill-local/README.md) and [`dsh-mcp-client`](../../mcp/mcp-client/README.md). Design rationale: [trusted repository package code](../../../.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md) and the [static contribution subformat](../../../.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md).
 
 ## Authoring format
 
@@ -13,17 +13,30 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
   "name": "humanize-dsh-plugin",
   "version": "0.0.0",
   "private": true,
+  "type": "module",
   "scripts": {
-    "prepack": "dsh-plugin-prepare"
+    "build": "tsc",
+    "prepack": "npm run build && dsh-plugin-prepare"
   },
   "dsh": {
+    "entry": "./lib/plugin.js",
     "skills": ["../skills"],
     "mcpServers": "../.mcp.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
   }
 }
 ```
 
-`scripts.prepack` must be exactly `dsh-plugin-prepare`. DSH supplies that command from its own installed runtime while preparing Git source, so the repository package needs no DSH or npm dependency. `dsh.skills` is an optional array of local skill roots. `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one field is required. Paths are relative to `.dsh-plugin`, must stay under its parent source directory, and may therefore refer to existing repository assets such as `../skills`. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
+`scripts.prepack` must be non-empty and invoke `dsh-plugin-prepare`; it may run arbitrary package-owned build steps first. DSH supplies only that helper command from its installed runtime: the package declares and runs its own compiler, runtime dependencies, and other npm lifecycle code. DSH does not transpile TypeScript or infer a package entry.
+
+`dsh.entry` is an optional relative path to a compiled ESM Cordis Plugin inside `.dsh-plugin`. The module may use either namespace exports or a default export and owns its ordinary `name`, `inject`, `Config`, registrations, and effects. `dsh.skills` is an optional array of local skill roots, and `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one of the three fields is required. Skill and MCP paths may reach adjacent repository assets but must remain beneath the directory containing `.dsh-plugin`; the compiled entry must remain inside the package selected and packed by the package manager. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
+
+The repository package and every dependency or lifecycle script it runs are trusted code, just like an npm package selected directly by the user. This format is not a sandbox: install only repositories whose code may access the host process, filesystem, network, and services declared through Cordis. Exact refs and the immutable cache provide identity and reproducibility, not isolation.
 
 ## Standalone app configuration
 
@@ -46,19 +59,17 @@ Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A v
 
 ## Preparation
 
-During exact Git installation, DSH places a temporary host-owned `dsh-plugin-prepare` command on the isolated package lifecycle `PATH`; the command is not fetched from npm. The required `prepack` lifecycle runs after the Git package's dependency installation and before its selected subdirectory is packed, including when `.dsh-plugin` sits inside another package-manager workspace. The command validates `package.json#dsh`, verifies skill-root types, parses the MCP file, copies assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained the exact `prepack` declaration. The wrapper contains only the normalized static manifest and fixed code that looks up the `dsh-repository-plugin` Loader builtin. It neither discovers nor compiles repository JavaScript, and the runtime never imports another repository entry point. Failure to run or complete preparation fails installation before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
-
-The containing package manager still runs the configured repository package's lifecycle scripts. This restriction defines the supported DSH contribution surface; it is not a security boundary for a repository that the user chose to install as executable package-manager source.
+During exact Git installation, DSH places a temporary host-owned `dsh-plugin-prepare` command on the isolated package lifecycle `PATH`; the command is not fetched from npm. The required `prepack` lifecycle runs after the Git package's dependency installation and before its selected subdirectory is packed, including when `.dsh-plugin` sits inside another package-manager workspace. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to build or prepare fails installation before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
 
 ## Runtime composition
 
-Loading this package registers one effect-scoped Loader builtin. Each generated wrapper delegates to that builtin with its own module URL and prepared manifest. The runtime validates every declared skill root as an existing in-package directory before mounting — a package whose generated outputs were dropped (a `files`/`.npmignore` mistake, a damaged cache entry) fails the plugin load instead of silently mounting a skill-less plugin. Repository skill roots mount as a uniquely named `dsh-skill-local` provider with default project/user roots excluded and watching disabled; cached package generations are immutable. Wrapper disposal removes the provider and all composed MCP clients through normal Cordis child-fiber teardown.
+Loading this package registers one effect-scoped Loader builtin. Each generated wrapper delegates its prepared static manifest to that builtin, then imports and mounts `dsh.entry` when declared. The entry is an ordinary Cordis child Plugin: its own `inject` gates activation, startup failures reject the repository generation, and all of its effects disappear on Loader removal or rollback. The runtime likewise validates every declared skill root as an existing in-package directory before mounting — a package whose generated outputs were dropped by `files`/`.npmignore` or damaged in cache fails instead of silently losing contributions. Repository skill roots mount as uniquely named `dsh-skill-local` providers with default project/user roots excluded and watching disabled; cached package generations are immutable.
 
 ## Common MCP format
 
 The `.mcp.json` root is `{ "mcpServers": { ... } }`. A stdio entry accepts only `type: "stdio"` (optional), `command`, `args`, and `env`; an HTTP entry accepts only `type: "http"`, `url`, and `headers`. String values support exact `${NAME}` process-environment expansion at Plugin load, and a missing name fails that load. HTTP URLs become the existing MCP client's `streamable-http` transport; stdio entries use the prepared package directory as `cwd`.
 
-Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle; a network or child-process connection failure retains that client's established log-and-no-tools behavior.
+Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle. Plugin activation waits for the initial connection and tool discovery, so the first model request observes a successful initial tool generation; a network or child-process connection failure is logged and still activates with no tools.
 
 ## Export shape
 
@@ -94,8 +105,22 @@ Conditional on successful connection and the remote tool list; schemas recur on
 
 Stable connected tool lists are prefix-stable. Plugin lifecycle or MCP tool-list changes can change later tool-schema prefixes from the first affected definition.
 
+### Repository code
+
+#### What the model sees
+
+Data-dependent. The trusted Cordis entry may contribute any DSH behavior available through its declared services and events, including tools, prompt sections, policies, commands, and transformations. Every model-visible contribution remains subject to its owning DSH seam's logging and lifecycle contract.
+
+#### Token effect
+
+Defined by the services and registrations the entry contributes; the repository format itself adds no model content.
+
+#### KV Cache effect
+
+Stable registrations preserve the owning surface's normal prefix behavior. Loading, removing, or replacing the exact repository generation can change any prefixes affected by that Plugin.
+
 ## Known Limitations and Deferred Work
 
-- **Skills and MCP only** — commands, hooks, agents, apps, arbitrary Cordis code, marketplaces, and compatibility shims are intentionally outside this format.
+- **No code sandbox** — `dsh.entry`, npm dependencies, and package lifecycle scripts execute with the DSH host's authority; repository trust is mandatory.
 - **No MCP authentication protocol** — static headers may use environment expansion, but OAuth-bearing definitions reject and private-server login flows are not implemented here.
 - **Generated assets are immutable runtime input** — repository cache generations are not watched; source, ref, path, or configuration must select another prepared generation.
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index db2f3e5a5c..921bf70b8a 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这是 DeepSeek Harness 的受限 repository 插件格式。仓库作者在 `.dsh-plugin/package.json` 中声明静态 skill（技能）根和可选的通用 `.mcp.json`；prepare helper 会复制这些资源并生成固定、无 import 的 Cordis 包装模块。运行时包装模块只能委托给这个由 DSH 自有的包，再由它组合 [`dsh-skill-local`](../../skill/skill-local/README.md) 与 [`dsh-mcp-client`](../../mcp/mcp-client/README.md)。设计依据见[静态 repository 插件格式 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md)。
+这是 DeepSeek Harness 的受信任 repository 包格式。`.dsh-plugin` NPM 包可以贡献已编译的 Cordis／DSH 插件入口、skill（技能）根和通用 `.mcp.json`；其常规 `prepack` 生命周期负责安装依赖并编译源码，随后 DSH 准备辅助程序校验输出并生成 Loader 包装层。静态贡献由 [`dsh-skill-local`](../../skill/skill-local/README.md) 与 [`dsh-mcp-client`](../../mcp/mcp-client/README.md) 组合。设计依据见[受信任 repository 包代码](../../../.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md)和[静态贡献子格式](../../../.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md)。
 
 ## 创作格式
 
@@ -13,17 +13,30 @@
   "name": "humanize-dsh-plugin",
   "version": "0.0.0",
   "private": true,
+  "type": "module",
   "scripts": {
-    "prepack": "dsh-plugin-prepare"
+    "build": "tsc",
+    "prepack": "npm run build && dsh-plugin-prepare"
   },
   "dsh": {
+    "entry": "./lib/plugin.js",
     "skills": ["../skills"],
     "mcpServers": "../.mcp.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
   }
 }
 ```
 
-`scripts.prepack` 必须精确设为 `dsh-plugin-prepare`。DSH 会在准备 Git 源时由已安装的运行时提供该命令，因此仓库包无需添加 DSH 或 NPM 依赖。`dsh.skills` 是可选的本地 skill 根数组。`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；两者至少声明一个。路径相对于 `.dsh-plugin`，必须留在其父级源码目录下，因此可以引用 `../skills` 等仓库现有资源。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
+`scripts.prepack` 必须非空并调用 `dsh-plugin-prepare`；可以先运行任意包自有的构建步骤。DSH 已安装的运行时只提供该辅助命令：包自行声明并运行编译器、运行时依赖和其他 NPM 生命周期代码。DSH 不转译 TypeScript，也不推断包入口。
+
+`dsh.entry` 是指向 `.dsh-plugin` 内已编译 ESM Cordis 插件的可选相对路径。该模块可以使用 namespace 导出或 default export，并自行拥有常规的 `name`、`inject`、`Config`、注册和 effect。`dsh.skills` 是可选的本地 skill 根数组，`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；三个字段中至少声明一个。skill 和 MCP 路径可以引用相邻的 repository 资源，但必须留在包含 `.dsh-plugin` 的目录下；已编译入口必须留在由包管理器选中并打包的包内。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
+
+repository 包及其运行的每项依赖或生命周期脚本都是受信任代码，与用户直接选择的 NPM 包相同。本格式不是沙箱：只有在你信任仓库代码并愿意允许其访问宿主进程、文件系统、网络及其通过 Cordis 声明的服务时才应安装。精确 ref 和不可变缓存提供身份与可复现性，而非隔离。
 
 ## 独立应用配置
 
@@ -46,19 +59,17 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 ## 准备阶段
 
-安装精确指定的 Git 源时，DSH 会把一个临时的宿主自有 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；该命令不从 NPM 获取。必需的 `prepack` 生命周期在 Git 包完成依赖安装后、选定子目录打包前运行，即使 `.dsh-plugin` 位于另一个包管理器工作区内也不例外。该命令校验 `package.json#dsh`、确认 skill 根类型、解析 MCP 文件、把资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装模块前，DSH 会重新校验已安装包是否仍保留精确的 `prepack` 声明。包装模块只包含规范化后的静态 manifest（元数据清单），以及查找 `dsh-repository-plugin` Loader builtin 的固定代码；它不会发现或编译仓库 JavaScript，运行时也不会导入仓库的其他入口。准备阶段未运行或未完成时，安装会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
-
-外层包管理器仍会运行已配置仓库包的生命周期脚本。这里的限制只定义 DSH 所支持的贡献表面；对于用户选择以可执行包管理器源安装的仓库，它并不是安全边界。
+安装精确指定的 Git 源时，DSH 会把一个临时的宿主自有 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；该命令不从 NPM 获取。必需的 `prepack` 生命周期在 Git 包完成依赖安装后、选定子目录打包前运行，即使 `.dsh-plugin` 位于另一个包管理器工作区内也不例外。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。构建或准备失败时，安装会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
 
 ## 运行时组合
 
-加载本包会注册一个 effect-scoped Loader builtin。每个生成的包装模块都把自身模块 URL 和已准备的 manifest 委托给该 builtin。运行时在挂载前会校验每个声明的 skill 根都是包内实际存在的目录——生成输出被丢弃的包（`files`／`.npmignore` 配置失误、缓存条目损坏）会使插件加载失败，而不是静默挂载一个没有 skill 的插件。Repository skill 根以唯一命名的 `dsh-skill-local` 提供方挂载，排除默认项目／用户根并禁用监视；缓存包 generation 是不可变的。包装模块 dispose（资源释放）时，会通过正常的 Cordis 子 fiber teardown 移除提供方和所有组合的 MCP client。
+加载本包会注册一个 effect-scoped Loader builtin。每个生成的包装层都把已准备的静态 manifest（元数据清单）委托给该 builtin，再在声明了 `dsh.entry` 时导入并挂载该入口。入口是普通的 Cordis 子插件：其自有 `inject` 会门控激活，启动失败会拒绝 repository generation，Loader 移除或回滚时，其所有 effect 都会消失。运行时同样会在挂载前校验每个声明的 skill 根都是包内实际存在的目录——生成输出因 `files`／`.npmignore` 被丢弃或在缓存中损坏的包会加载失败，而不是静默丢失贡献。Repository skill 根以唯一命名的 `dsh-skill-local` 提供方挂载，排除默认项目／用户根并禁用监视；缓存包 generation 是不可变的。
 
 ## 通用 MCP 格式
 
 `.mcp.json` 根对象是 `{ "mcpServers": { ... } }`。stdio 条目只接受可选的 `type: "stdio"`、`command`、`args` 和 `env`；HTTP 条目只接受 `type: "http"`、`url` 和 `headers`。字符串值在插件加载时支持严格的 `${NAME}` 进程环境变量展开；缺失变量会使该次加载失败。HTTP URL 映射到现有 MCP client 的 `streamable-http` transport；stdio 条目以已准备的包目录作为 `cwd`。
 
-未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期；网络或子进程连接失败沿用该 client 既有的“记录错误且不注册工具”行为。
+未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期。插件激活会等待初始连接与工具发现，因此首个模型请求会看到成功的初始工具 generation；网络或子进程连接失败会记录日志，且插件仍会激活但不注册工具。
 
 ## 导出形状
 
@@ -94,8 +105,22 @@ Namespace 插件：具名导出 `name`／`inject`／`apply`、准备阶段常量
 
 稳定的已连接工具列表保持前缀稳定。插件生命周期或 MCP 工具列表变化可能从首个受影响定义开始改变后续工具 schema 前缀。
 
+### Repository 代码
+
+#### 模型看到什么
+
+取决于数据。受信任的 Cordis 入口可以通过其声明的服务和事件贡献任意可用的 DSH 行为，包括工具、提示词片段、策略、命令和转换。每项模型可见贡献仍受所属 DSH seam 的日志与生命周期契约约束。
+
+#### Token 影响
+
+由入口贡献的服务和注册决定；repository 格式本身不添加模型内容。
+
+#### KV Cache 影响
+
+稳定的注册会保留所属表面的正常前缀行为。加载、移除或替换精确的 repository generation，可能改变受该插件影响的任意前缀。
+
 ## 已知限制与暂缓事项
 
-- **仅支持 skill 与 MCP**：commands、钩子、agent（智能体）、apps、任意 Cordis 代码、marketplace 和兼容 shim 均有意排除在该格式之外。
+- **没有代码沙箱**：`dsh.entry`、NPM 依赖和包生命周期脚本以 DSH 宿主权限执行；必须信任该 repository。
 - **没有 MCP 认证协议**：静态 header 可以使用环境变量展开，但带 OAuth 的定义会被拒绝，私有 server 登录流程不在此实现。
 - **生成资源是不可变运行时输入**：repository cache generation 不受监视；必须改变 source、ref、path 或配置才能选择另一份已准备 generation。
diff --git a/packages/self-modification/repository-plugin/package.json b/packages/self-modification/repository-plugin/package.json
index 87e88122f6..fbf18c0cb1 100644
--- a/packages/self-modification/repository-plugin/package.json
+++ b/packages/self-modification/repository-plugin/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-repository-plugin",
-  "description": "Restricted repository plugin format and Cordis runtime for DeepSeek Harness",
+  "description": "Trusted repository package format and Cordis runtime for DeepSeek Harness",
   "version": "0.0.1",
   "private": true,
   "type": "module",
diff --git a/packages/self-modification/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
index 654e37c201..63ba724108 100644
--- a/packages/self-modification/repository-plugin/src/format.ts
+++ b/packages/self-modification/repository-plugin/src/format.ts
@@ -1,5 +1,5 @@
 /**
- * Static repository-plugin preparation and prepared-manifest validation.
+ * Trusted repository-package preparation and prepared-manifest validation.
  * @module
  */
 
@@ -12,21 +12,36 @@ import { parseMcpDocument } from './mcp.ts'
 export const PREPARED_ENTRY_FILENAME = 'dsh-plugin.mjs'
 /** Fixed directory containing copied static plugin assets. */
 export const PREPARED_ASSET_DIRECTORY = 'dsh-plugin-assets'
-/** Loader builtin used by every generated import-free wrapper. */
+/** Loader builtin used by every generated repository wrapper. */
 export const REPOSITORY_PLUGIN_BUILTIN = 'dsh-repository-plugin'
-/** Exact host-owned command required by the repository package `prepack` lifecycle. */
+/** Host-owned command that repository package `prepack` lifecycles must invoke. */
 export const REPOSITORY_PLUGIN_PREPARE_COMMAND = 'dsh-plugin-prepare'
 
+/**
+ * Whether a package lifecycle declaration names the host preparation helper.
+ * @param script - package-authored lifecycle command.
+ * @returns true when the required helper command is present.
+ */
+export function hasRepositoryPrepareCommand(script: string): boolean {
+  return script.includes(REPOSITORY_PLUGIN_PREPARE_COMMAND)
+}
+
+const prepackSchema = z.string().min(1).refine(
+  hasRepositoryPrepareCommand,
+  { message: `must invoke ${REPOSITORY_PLUGIN_PREPARE_COMMAND}` },
+)
+
 const sourceMetadataSchema = z.object({
   skills: z.array(z.string().min(1)).default([]),
   mcpServers: z.string().min(1).optional(),
-}).strict().refine(value => value.skills.length > 0 || value.mcpServers !== undefined, {
-  message: 'declare at least one skill root or mcpServers file',
+  entry: z.string().min(1).optional(),
+}).strict().refine(value => value.skills.length > 0 || value.mcpServers !== undefined || value.entry !== undefined, {
+  message: 'declare at least one skill root, mcpServers file, or compiled entry',
 })
 const sourcePackageSchema = z.looseObject({
   name: z.string().min(1),
   scripts: z.looseObject({
-    prepack: z.literal(REPOSITORY_PLUGIN_PREPARE_COMMAND),
+    prepack: prepackSchema,
   }),
   dsh: sourceMetadataSchema,
 })
@@ -34,6 +49,7 @@ const preparedManifestSchema = z.object({
   name: z.string().min(1),
   skills: z.array(z.string().min(1)),
   mcpServers: z.string().min(1).optional(),
+  entry: z.string().min(1).optional(),
 }).strict()
 const preparedConfigSchema = z.object({
   // Wrappers pass import.meta.url, which is always file: for an installed
@@ -43,11 +59,12 @@ const preparedConfigSchema = z.object({
   manifest: preparedManifestSchema,
 }).strict()
 
-/** Static manifest embedded in the generated wrapper. */
+/** Prepared manifest embedded in the generated wrapper. */
 export interface PreparedPluginManifest {
   name: string
   skills: string[]
   mcpServers?: string
+  entry?: string
 }
 
 /** Untrusted generated-wrapper config accepted by the DSH-owned runtime builtin. */
@@ -74,6 +91,7 @@ export function parsePreparedPluginConfig(value: unknown): PreparedPluginConfig
       name: result.data.manifest.name,
       skills: result.data.manifest.skills,
       ...result.data.manifest.mcpServers === undefined ? {} : { mcpServers: result.data.manifest.mcpServers },
+      ...result.data.manifest.entry === undefined ? {} : { entry: result.data.manifest.entry },
     },
   }
 }
@@ -121,28 +139,49 @@ function wrapperSource(manifest: PreparedPluginManifest): string {
     ...manifest.skills.length > 0 ? ['skills'] : [],
     ...manifest.mcpServers === undefined ? [] : ['tools'],
   ]
+  const entryHelpers = manifest.entry === undefined ? [] : [
+    'function unwrap(exports) {',
+    '  const value = exports?.default ?? exports',
+    '  return value?.__esModule ? (value.default ?? value) : value',
+    '}',
+  ]
+  const entryApply = manifest.entry === undefined ? [] : [
+    '  const repositoryPlugin = unwrap(await import(manifest.entry))',
+    "  await mount(ctx, repositoryPlugin, 'repository Plugin entry')",
+  ]
   return [
     '// Generated by dsh-plugin-prepare. Do not edit.',
     `const manifest = ${JSON.stringify(manifest)}`,
+    'const FIBER_ACTIVE = 2',
     `export const name = ${JSON.stringify(manifest.name)}`,
     `export const inject = ${JSON.stringify(inject)}`,
+    ...entryHelpers,
+    'async function mount(ctx, plugin, label, config) {',
+    '  const fiber = ctx.plugin(plugin, config)',
+    '  await fiber',
+    '  if (fiber.state !== FIBER_ACTIVE) {',
+    '    const missing = Object.keys(fiber.inject).filter(service => fiber.ctx.get(service) === undefined)',
+    "    throw new Error(`${label} did not activate (waiting for services: ${missing.join(', ') || 'unknown'})`)",
+    '  }',
+    '}',
     'export async function apply(ctx) {',
     `  const runtime = ctx.loader.builtins[${JSON.stringify(REPOSITORY_PLUGIN_BUILTIN)}]`,
     `  if (runtime === undefined) throw new Error(${JSON.stringify(`missing Cordis builtin ${REPOSITORY_PLUGIN_BUILTIN}`)})`,
-    '  await ctx.plugin(runtime, { baseUrl: import.meta.url, manifest })',
+    "  await mount(ctx, runtime, 'repository Plugin runtime', { baseUrl: import.meta.url, manifest })",
+    ...entryApply,
     '}',
     '',
   ].join('\n')
 }
 
 /**
- * Validate and package one `.dsh-plugin` directory into static assets plus a fixed wrapper.
+ * Validate and package one `.dsh-plugin` directory into copied assets plus a generated wrapper.
  * Outputs are staged and committed by rename, but the final publish (remove
  * old outputs, rename assets, rename entry) is not one atomic step: a crash
  * mid-publish can leave assets without an entry or neither. Rerunning prepare
  * repairs the package; partial outputs are never importable as a plugin.
  * @param directory - `.dsh-plugin` package directory; defaults to the prepare process cwd.
- * @returns the generated static manifest.
+ * @returns the generated prepared manifest.
  */
 export async function prepareDshPlugin(directory: string = process.cwd()): Promise<PreparedPluginManifest> {
   const pluginDirectory = await realpath(resolve(directory))
@@ -169,11 +208,17 @@ export async function prepareDshPlugin(directory: string = process.cwd()): Promi
     mcpSource = await sourcePath(pluginDirectory, sourceRoot, parsed.data.dsh.mcpServers, 'file')
     parseMcpDocument(await readFile(mcpSource, 'utf8'))
   }
+  let entry: string | undefined
+  if (parsed.data.dsh.entry !== undefined) {
+    const entrySource = await sourcePath(pluginDirectory, pluginDirectory, parsed.data.dsh.entry, 'file')
+    entry = `./${relative(pluginDirectory, entrySource).split(sep).join('/')}`
+  }
 
   const manifest: PreparedPluginManifest = {
     name: parsed.data.name,
     skills: skillSources.map((_, index) => `${PREPARED_ASSET_DIRECTORY}/skills/${index}`),
     ...mcpSource === undefined ? {} : { mcpServers: `${PREPARED_ASSET_DIRECTORY}/.mcp.json` },
+    ...entry === undefined ? {} : { entry },
   }
   const staging = await mkdtemp(join(pluginDirectory, '.dsh-plugin-prepare-'))
   try {
diff --git a/packages/self-modification/repository-plugin/src/index.ts b/packages/self-modification/repository-plugin/src/index.ts
index d3d287974f..403c2d1ae9 100644
--- a/packages/self-modification/repository-plugin/src/index.ts
+++ b/packages/self-modification/repository-plugin/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Restricted repository-plugin runtime for static skills and common MCP definitions.
+ * Trusted repository-package runtime for code, skills, and common MCP definitions.
  * @module @deepseek-ai/dsh-repository-plugin
  */
 
diff --git a/packages/self-modification/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
index e8a9e9b9cc..51f015e68a 100644
--- a/packages/self-modification/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -14,6 +14,7 @@ import { z } from 'zod'
 import {
   PREPARED_ENTRY_FILENAME,
   REPOSITORY_PLUGIN_PREPARE_COMMAND,
+  hasRepositoryPrepareCommand,
 } from './format.ts'
 
 // Value mirror: Cordis's const enum has no runtime object to import. Keep
@@ -80,7 +81,10 @@ export async function createRepositoryPrepareCommand(): Promise<RepositoryPrepar
 const GITHUB_SOURCE_PATTERN = /^github:([^/\s#&]+)\/([^/\s#&]+)#([^\s#&]+)(?:&path:(\/[^\s&]+))?$/
 const installedPackageSchema = z.looseObject({
   scripts: z.looseObject({
-    prepack: z.literal(REPOSITORY_PLUGIN_PREPARE_COMMAND),
+    prepack: z.string().min(1).refine(
+      hasRepositoryPrepareCommand,
+      { message: `must invoke ${REPOSITORY_PLUGIN_PREPARE_COMMAND}` },
+    ),
   }),
 })
 
@@ -127,7 +131,7 @@ async function assertInstalledPackageMetadata(directory: string): Promise<void>
   }
   const result = installedPackageSchema.safeParse(value)
   if (!result.success) {
-    throw new Error(`installed DSH plugin package must declare scripts.prepack as ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:\n${z.prettifyError(result.error)}`)
+    throw new Error(`installed DSH plugin package must declare a non-empty scripts.prepack that invokes ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:\n${z.prettifyError(result.error)}`)
   }
 }
 
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index d026a4e14c..06cacfd699 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -28,13 +28,18 @@ async function temporaryDirectory(name: string): Promise<string> {
   return directory
 }
 
-async function writePlugin(root: string, name: string, dsh: Record<string, unknown>): Promise<string> {
+async function writePlugin(
+  root: string,
+  name: string,
+  dsh: Record<string, unknown>,
+  prepack = RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND,
+): Promise<string> {
   const directory = join(root, '.dsh-plugin')
   await mkdir(directory, { recursive: true })
   await writeFile(join(directory, 'package.json'), `${JSON.stringify({
     name,
     version: '0.0.0',
-    scripts: { prepack: RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND },
+    scripts: { prepack },
     dsh,
   }, undefined, 2)}\n`)
   return directory
@@ -82,6 +87,24 @@ describe('dsh-plugin-prepare', () => {
       .resolves.toContain('mcp.expo.dev')
   })
 
+  it('preserves a compiled package entry and accepts a build before the host prepare command', async () => {
+    const root = await temporaryDirectory('compiled-entry')
+    const directory = await writePlugin(root, 'compiled-entry-fixture', {
+      entry: './lib/plugin.mjs',
+    }, 'npm run build && dsh-plugin-prepare')
+    await mkdir(join(directory, 'lib'))
+    await writeFile(join(directory, 'lib/plugin.mjs'), 'export default { name: "compiled-entry" }\n')
+
+    await expect(RepositoryPlugin.prepareDshPlugin(directory)).resolves.toEqual({
+      name: 'compiled-entry-fixture',
+      skills: [],
+      entry: './lib/plugin.mjs',
+    })
+    const wrapper = await readFile(join(directory, RepositoryPlugin.PREPARED_ENTRY_FILENAME), 'utf8')
+    expect(wrapper).toContain('await import(manifest.entry)')
+    expect(wrapper).toContain('"entry":"./lib/plugin.mjs"')
+  })
+
   it('rejects unsupported OAuth MCP metadata before publishing outputs', async () => {
     const root = await temporaryDirectory('oauth')
     await writeFile(join(root, '.mcp.json'), JSON.stringify({
@@ -118,9 +141,18 @@ describe('dsh-plugin-prepare', () => {
     }))
     await expect(RepositoryPlugin.prepareDshPlugin(lifecycle)).rejects.toThrow('prepack')
 
+    const skippedPrepareRoot = await temporaryDirectory('skipped-prepare')
+    const skippedPrepare = await writePlugin(
+      skippedPrepareRoot,
+      'skipped-prepare',
+      { skills: ['../skills'] },
+      'npm run build',
+    )
+    await expect(RepositoryPlugin.prepareDshPlugin(skippedPrepare)).rejects.toThrow('must invoke dsh-plugin-prepare')
+
     const emptyRoot = await temporaryDirectory('empty-metadata')
     const empty = await writePlugin(emptyRoot, 'empty', {})
-    await expect(RepositoryPlugin.prepareDshPlugin(empty)).rejects.toThrow('declare at least one skill root or mcpServers file')
+    await expect(RepositoryPlugin.prepareDshPlugin(empty)).rejects.toThrow('declare at least one skill root, mcpServers file, or compiled entry')
 
     const missingRoot = await temporaryDirectory('missing-asset')
     const missing = await writePlugin(missingRoot, 'missing', { skills: ['../missing'] })
@@ -149,16 +181,21 @@ describe('dsh-plugin-prepare', () => {
     await writeSkill(outside, 'outside-skill')
     const escaped = await writePlugin(escapedRoot, 'escaped', { skills: [relative(join(escapedRoot, '.dsh-plugin'), outside)] })
     await expect(RepositoryPlugin.prepareDshPlugin(escaped)).rejects.toThrow('escapes its plugin source root')
+
+    const escapedEntryRoot = await temporaryDirectory('escaped-entry')
+    await writeFile(join(escapedEntryRoot, 'outside.mjs'), 'export default {}\n')
+    const escapedEntry = await writePlugin(escapedEntryRoot, 'escaped-entry', { entry: '../outside.mjs' })
+    await expect(RepositoryPlugin.prepareDshPlugin(escapedEntry)).rejects.toThrow('escapes its plugin source root')
   })
 
-  it('validates prepared wrapper configs with and without MCP assets', () => {
+  it('validates prepared wrapper configs with optional MCP assets and code entries', () => {
     expect(() => parsePreparedPluginConfig({})).toThrow('invalid prepared DSH plugin')
     expect(parsePreparedPluginConfig({
       baseUrl: 'file:///plugin/dsh-plugin.mjs',
-      manifest: { name: 'fixture', skills: [], mcpServers: 'dsh-plugin-assets/.mcp.json' },
+      manifest: { name: 'fixture', skills: [], mcpServers: 'dsh-plugin-assets/.mcp.json', entry: './lib/plugin.js' },
     })).toEqual({
       baseUrl: 'file:///plugin/dsh-plugin.mjs',
-      manifest: { name: 'fixture', skills: [], mcpServers: 'dsh-plugin-assets/.mcp.json' },
+      manifest: { name: 'fixture', skills: [], mcpServers: 'dsh-plugin-assets/.mcp.json', entry: './lib/plugin.js' },
     })
   })
 })
@@ -195,6 +232,35 @@ describe('prepared repository plugin Loader composition', () => {
     await ctx.fiber.dispose()
   })
 
+  it('mounts and removes the repository package code entry through the real Loader', async () => {
+    const root = await temporaryDirectory('code-loader')
+    const directory = await writePlugin(root, 'code-loader-fixture', { entry: './lib/plugin.mjs' })
+    await mkdir(join(directory, 'lib'))
+    await writeFile(join(directory, 'lib/plugin.mjs'), [
+      "export const name = 'repository-code-proof'",
+      'export function apply(ctx) {',
+      "  ctx.provide('repositoryCodeProof', { source: 'compiled-entry' })",
+      '}',
+      '',
+    ].join('\n'))
+    await RepositoryPlugin.prepareDshPlugin(directory)
+
+    const ctx = new Context()
+    ctx.baseUrl = pathToFileURL(directory).href + '/'
+    await ctx.plugin(Loader)
+    await ctx.plugin(RepositoryPlugin)
+    const id = await ctx.loader.create({
+      name: pathToFileURL(join(directory, RepositoryPlugin.PREPARED_ENTRY_FILENAME)).href,
+    })
+    await ctx.loader.await()
+    const getService = (name: string): unknown => (ctx as unknown as { get(name: string): unknown }).get(name)
+    expect(getService('repositoryCodeProof')).toEqual({ source: 'compiled-entry' })
+
+    await ctx.loader.remove(id)
+    expect(getService('repositoryCodeProof')).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
   it('delegates an MCP-only plugin to the existing client without turning connect failure into Loader failure', async () => {
     const root = await temporaryDirectory('mcp-loader')
     await writeFile(join(root, '.mcp.json'), JSON.stringify({
@@ -484,7 +550,23 @@ describe('configured GitHub repository sources', () => {
     await expect(loadPreparedRepository(ctx, { resolve: async () => root }, 'github:owner/repository#old&path:/.dsh-plugin'))
       .rejects.toMatchObject({
         cause: expect.objectContaining({
-          message: expect.stringContaining('must declare scripts.prepack') as string,
+          message: expect.stringContaining('must declare a non-empty scripts.prepack') as string,
+        }) as Error,
+      })
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects an installed source whose prepack omits the host prepare command', async () => {
+    const root = await temporaryDirectory('installed-skipped-prepare')
+    await writeFile(join(root, 'package.json'), JSON.stringify({
+      name: 'installed-skipped-prepare',
+      scripts: { prepack: 'npm run build' },
+    }))
+    const ctx = new Context()
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, 'github:owner/repository#unprepared&path:/.dsh-plugin'))
+      .rejects.toMatchObject({
+        cause: expect.objectContaining({
+          message: expect.stringContaining('must invoke dsh-plugin-prepare') as string,
         }) as Error,
       })
     await ctx.fiber.dispose()

From a7832cbfbfca3de1dd914d1d064ace39eb67eceb Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:59:48 +0800
Subject: [PATCH 439/516] fix(repository-cache): isolate Git package
 dependencies

---
 ...it-repository-plugin-preparation.i18n.yaml |  4 +-
 ...owned-git-repository-plugin-preparation.md |  9 ++-
 ...ed-git-repository-plugin-preparation.zh.md |  9 ++-
 .../app-boot/tests/repository-cache.spec.ts   | 29 +++++++-
 .../repository-plugin/README.i18n.yaml        |  4 +-
 .../repository-plugin/README.md               |  4 +-
 .../repository-plugin/README.zh.md            |  4 +-
 vendor/README.md                              |  2 +-
 vendor/loader/src/repository.ts               | 70 +++++++++++++------
 9 files changed, 98 insertions(+), 37 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
index d3f10b5273..189c3dc5c2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.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 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
-2026-08-08-host-owned-git-repository-plugin-preparation.md: b459184f802981f91f611b0b781651cede0c9efd
-2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: 5e24efa59ce44ffa8214f9c5ef9ff722ac0ca73a
+2026-08-08-host-owned-git-repository-plugin-preparation.md: 3f92c0b2d782735bfb548711bb13a7a8d03a3824
+2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: ef34c99b5d9f31ea13c5fddfee77c30e640d25c9
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
index b459184f80..3f92c0b2d7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
@@ -10,13 +10,15 @@ The repository Plugin authoring contract depended on `scripts.prepare: "dsh-plug
 
 The lifecycle choice also failed for a selectable `.dsh-plugin` inside a pnpm workspace. pnpm prepares a Git-hosted package by running the repository's preferred package manager before packing the selected subdirectory. A nested `pnpm install` joins the containing workspace and need not execute the unlisted `.dsh-plugin` package's `prepare` script. The install could therefore succeed and publish a cache generation containing only the source package metadata; real DSH startup failed later because `dsh-plugin.mjs` did not exist.
 
+The same workspace discovery could suppress package-owned dependencies after the move to `prepack`. When the source repository carried a root pnpm lockfile but did not list the selected `.dsh-plugin` as a workspace importer, pnpm reported a successful workspace install without installing dependencies declared only by that package. Its TypeScript build then failed because Cordis and the MCP SDK were absent.
+
 The checked-in headless fixture did not catch either defect because it mounted an already prepared wrapper. It proved runtime composition, not GitHub acquisition or package preparation.
 
 ## Decision
 
 The authoring format requires a non-empty `scripts.prepack` that invokes `dsh-plugin-prepare` and needs no DSH dependency for that helper. The package may declare its own build and runtime dependencies and run compilation before the helper. pnpm's Git-hosted package preparation invokes `prepack` explicitly after its dependency-install step and before packlist selects the `.dsh-plugin` subtree, so the helper can validate built entries and still copy sibling repository assets such as `../skills` into the package.
 
-`@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. The command directory exists only for the installation transaction and is removed on success or failure. The repository remains trusted package-manager input: DSH supplies one command, but other lifecycle scripts and dependencies still execute under the existing trust contract.
+`@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. It also prepends a transaction-owned `pnpm` wrapper: the outer install still runs the pinned pnpm entry directly, while pnpm's hard-coded Git-package `pnpm install` reinvokes that same entry with `--ignore-workspace`. The selected package therefore owns dependency resolution even beneath another pnpm lockfile. Both command directories are removed after the child settles. The repository remains trusted package-manager input: DSH supplies the two host commands, but all package lifecycle scripts and dependencies still execute under the existing trust contract.
 
 The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Because that repository is private, the workflow writes a job-scoped Git configuration that uses the read-only job token for GitHub HTTPS and rewrites pnpm's SSH fallback to that authenticated transport. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true` GitHub fixture. That fixture installs pinned npm dependencies, type-checks and bundles a TypeScript Cordis entry and MCP server in `prepack`, invokes the host helper, and proves the skill, MCP call, and code entry through real model requests and immutable-cache artifacts. The test fails if CI omits the exact source instead of silently skipping.
 
@@ -30,14 +32,17 @@ The Node 24 consumer lane passes an exact source derived from the pull request h
 
 **Clone GitHub repositories in DSH and bypass pnpm's Git fetcher.** Rejected because it would duplicate ref resolution, subdirectory selection, dependency installation, packlist behavior, and cache integrity already owned by the pinned package manager.
 
+**Add the in-repository CI fixture to this repository's pnpm workspace.** Rejected because that would repair only the proof fixture and leave an arbitrary selected package vulnerable to its containing repository's workspace membership and lockfile.
+
 ## Consequences
 
 - A repository author can commit the fixed `.dsh-plugin/package.json` and source assets to GitHub without publishing either the Plugin or its preparation helper to npm.
 - Private GitHub sources use the host's standard Git authentication. CI proves that path with a temporary read-only configuration rather than persistent runner credentials.
 - `prepack`, not `prepare`, is part of the pre-release authoring format. It may contain package-owned build steps but must invoke the host helper; missing or empty lifecycle metadata fails installed-package validation instead of producing an ambiguous partial format.
+- A selected package in a pnpm repository installs from its own manifest rather than an enclosing workspace. It must declare its dependencies and cannot rely on workspace-only hoisting; ordinary registry and relative `file:` dependencies remain package-owned inputs.
 - Exact source strings still identify immutable cache generations; a changed ref or source configuration selects another generation.
 - The host supplies only the preparation executable. Package dependencies, compilation, and the trusted `dsh.entry` contribution remain owned by the repository package and the [trusted-code decision](../architecture/2026-08-08-trusted-repository-package-code.md).
 
 ## Testing
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a local Git subpath through bundled pnpm with an injected command directory and proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
+`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a package excluded from its source repository's root pnpm lockfile through a local Git subpath and requires a relative `file:` build dependency during `prepack`; it also proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
index 5e24efa59c..ef34c99b5d 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
@@ -10,13 +10,15 @@ repository 插件的创作契约依赖 `scripts.prepare: "dsh-plugin-prepare"`
 
 这种生命周期选择也无法支持 pnpm 工作区内可选的 `.dsh-plugin`。pnpm 会先运行 Git 托管仓库首选的包管理器，再打包选定的子目录，从而准备 Git 托管包。嵌套执行的 `pnpm install` 会加入外层工作区，而不一定执行未列入其中的 `.dsh-plugin` 包的 `prepare` 脚本。因此，安装可能成功并发布一个仅包含源包元数据的缓存 generation；随后真实 DSH 启动因 `dsh-plugin.mjs` 不存在而失败。
 
+迁移到 `prepack` 后，同一项 workspace 发现行为还可能抑制包自有依赖。如果源仓库带有根 pnpm lockfile，却未把所选 `.dsh-plugin` 列为 workspace importer，pnpm 会报告 workspace 安装成功，但不会安装仅由该包声明的依赖。随后其 TypeScript 构建会因缺少 Cordis 和 MCP SDK 而失败。
+
 签入仓库的 headless fixture（测试前置数据）没有捕获任一缺陷，因为它挂载的是已准备好的包装层。它证明的是运行时组合，而不是 GitHub 获取或包准备。
 
 ## 决策
 
 创作格式要求 `scripts.prepack` 非空且调用 `dsh-plugin-prepare`，使用该辅助程序无需 DSH 依赖。包可以声明自己的构建依赖与运行时依赖，并在调用辅助程序前完成编译。pnpm 针对 Git 托管包的准备流程会在依赖安装步骤之后、打包清单选择 `.dsh-plugin` 子树之前显式调用 `prepack`，因此辅助程序可以校验构建入口，并继续把 `../skills` 等同仓库的相邻资源复制进包内。
 
-`@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。该命令目录仅存在于安装事务期间，无论成功还是失败都会被移除。仓库仍是受信任的包管理器输入：DSH 仅提供这一条命令，其他生命周期脚本和依赖仍会按既有信任契约执行。
+`@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。它还会前置一个由安装事务持有的 `pnpm` 包装命令：外层安装仍直接运行锁定的 pnpm 入口，而 pnpm 为 Git 包硬编码的 `pnpm install` 会通过 `--ignore-workspace` 重新调用同一入口。因此，即使位于另一个 pnpm lockfile 之下，所选包仍自行拥有依赖解析。两个命令目录都会在子进程结算后移除。仓库仍是受信任的包管理器输入：DSH 提供这两条宿主命令，但所有包生命周期脚本和依赖仍按既有信任契约执行。
 
 Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。由于该仓库为私有仓库，工作流会写入一份作业作用域的 Git 配置，使用该作业的只读 token 对 GitHub HTTPS 连接进行认证，并将 pnpm 的 SSH 回退路径重写为这一已认证的传输方式。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true` 的 GitHub fixture。该 fixture 安装固定版本的 NPM 依赖，在 `prepack` 中对 TypeScript Cordis 入口和 MCP server 进行类型检查与打包，调用宿主辅助程序，并通过真实模型请求和不可变缓存产物验证 skill（技能）、MCP 调用和代码入口。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
 
@@ -30,14 +32,17 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 
 
 **在 DSH 中克隆 GitHub 仓库，并绕过 pnpm 的 Git 获取器。** 拒绝，因为这会重复实现已由锁定版本的包管理器负责的 ref 解析、子目录选择、依赖安装、打包清单行为和缓存完整性。
 
+**把仓库内的 CI fixture 加入本仓库的 pnpm workspace。** 拒绝，因为这只能修复证明用的 fixture，任意所选包仍会受其所在仓库的 workspace membership 与 lockfile 影响。
+
 ## 后果
 
 - 仓库作者可以把修复后的 `.dsh-plugin/package.json` 和源资源提交到 GitHub，而无需把插件或其准备辅助程序发布到 NPM。
 - 私有 GitHub 源使用宿主的标准 Git 认证。CI 使用临时的只读配置而非运行器上的持久凭据来验证该路径。
 - 预发布创作格式使用 `prepack` 而不是 `prepare`。其中可以包含包自有构建步骤，但必须调用宿主辅助程序；生命周期元数据缺失或为空会在已安装包校验时失败，而不会留下状态不明的半成品格式。
+- pnpm 仓库中的所选包按自身 manifest 安装，而不是按外层 workspace 安装。它必须声明自己的依赖，不能依赖仅由 workspace 提升而可见的包；常规 registry 依赖与相对 `file:` 依赖仍是包自有输入。
 - 精确源字符串仍标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
 - 宿主只提供准备阶段可执行文件。包依赖、编译和受信任的 `dsh.entry` 贡献仍由 repository 包和[受信任代码决策](../architecture/2026-08-08-trusted-repository-package-code.md)负责。
 
 ## 测试
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 会用注入的命令目录通过随附 pnpm 运行本地 Git 子路径，并证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及对已准备缓存的检查。
+`packages/ui/app-boot/tests/repository-cache.spec.ts` 会让一个被源仓库根 pnpm lockfile 排除的包通过本地 Git 子路径运行，并要求 `prepack` 使用相对 `file:` 构建依赖；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及对已准备缓存的检查。
diff --git a/packages/boot/app-boot/tests/repository-cache.spec.ts b/packages/boot/app-boot/tests/repository-cache.spec.ts
index 186cbe1b43..290b9ab2cc 100644
--- a/packages/boot/app-boot/tests/repository-cache.spec.ts
+++ b/packages/boot/app-boot/tests/repository-cache.spec.ts
@@ -112,7 +112,7 @@ describe('RepositoryCache', () => {
     await expect(cache.resolve(specifier)).rejects.toThrow('repository cache marker is invalid')
   })
 
-  it('selects and prepares a root .dsh-plugin Git subpath through the bundled pnpm', { timeout: 60_000 }, async () => {
+  it('isolates and prepares a .dsh-plugin Git subpath from an enclosing pnpm workspace', { timeout: 60_000 }, async () => {
     const root = await temporaryRoot('repository-pnpm')
     const repository = join(root, 'source')
     const executableDirectory = join(root, 'bin')
@@ -132,16 +132,40 @@ describe('RepositoryCache', () => {
       '',
     ].join('\r\n'))
     await mkdir(join(repository, '.dsh-plugin'), { recursive: true })
+    await mkdir(join(repository, 'build-helper'), { recursive: true })
     await mkdir(join(repository, 'skills', 'fixture'), { recursive: true })
     await writeFile(join(repository, 'package.json'), `${JSON.stringify({
       name: 'repository-fixture',
+      private: true,
       version: '1.0.0',
+      packageManager: `pnpm@${BUNDLED_PNPM_VERSION}`,
     })}\n`)
+    await writeFile(join(repository, 'pnpm-workspace.yaml'), 'packages: []\n')
+    await writeFile(join(repository, 'pnpm-lock.yaml'), [
+      "lockfileVersion: '9.0'",
+      'settings:',
+      '  autoInstallPeers: true',
+      '  excludeLinksFromLockfile: false',
+      'importers:',
+      '  .: {}',
+      '',
+    ].join('\n'))
+    await writeFile(join(repository, 'build-helper', 'package.json'), `${JSON.stringify({
+      name: 'repository-build-helper',
+      version: '1.0.0',
+      bin: 'index.js',
+    })}\n`)
+    await writeFile(join(repository, 'build-helper', 'index.js'), [
+      '#!/usr/bin/env node',
+      "require('node:fs').writeFileSync('dependency-built.txt', 'dependency available\\n')",
+      '',
+    ].join('\n'), { mode: 0o700 })
     await writeFile(join(repository, 'skills', 'fixture', 'SKILL.md'), 'repository skill source\n')
     await writeFile(join(repository, '.dsh-plugin', 'package.json'), `${JSON.stringify({
       name: 'repository-plugin-fixture',
       version: '1.0.0',
-      scripts: { prepack: 'dsh-plugin-prepare' },
+      scripts: { prepack: 'repository-build-helper && dsh-plugin-prepare' },
+      devDependencies: { 'repository-build-helper': 'file:../build-helper' },
       dsh: { skills: ['../skills'] },
     })}\n`)
     await execFileAsync('git', ['init', '--quiet'], { cwd: repository })
@@ -159,6 +183,7 @@ describe('RepositoryCache', () => {
     const installed = await new RepositoryCache(join(root, 'cache'), {
       executableDirectories: [executableDirectory],
     }).resolve(specifier)
+    await expect(readFile(join(installed, 'dependency-built.txt'), 'utf8')).resolves.toBe('dependency available\n')
     await expect(readFile(join(installed, 'prepared.txt'), 'utf8')).resolves.toBe('visible|absent\n')
     await expect(readFile(join(installed, 'dsh-plugin.mjs'), 'utf8')).resolves.toContain('export function apply')
     await expect(readFile(join(installed, 'dsh-plugin-assets/skills/0/fixture/SKILL.md'), 'utf8'))
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index 7d7c04cf69..d41f4681a1 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 52d04f16684842749e57d1b47db0a95beb22558c
-README.zh.md: 921bf70b8a2e78410510d1efce79ced5f52b4641
+README.md: 1d858c5adcc208768dcbe99f129b47abb1722431
+README.zh.md: c2d0e6d72baeb0efb25abd8d50fee2922d2e810b
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 52d04f1668..1d858c5adc 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -32,7 +32,7 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
 }
 ```
 
-`scripts.prepack` must be non-empty and invoke `dsh-plugin-prepare`; it may run arbitrary package-owned build steps first. DSH supplies only that helper command from its installed runtime: the package declares and runs its own compiler, runtime dependencies, and other npm lifecycle code. DSH does not transpile TypeScript or infer a package entry.
+`scripts.prepack` must be non-empty and invoke `dsh-plugin-prepare`; it may run arbitrary package-owned build steps first. DSH supplies only that helper command from its installed runtime: the package declares and runs its own compiler, runtime dependencies, and other npm lifecycle code. The selected package is installed from its own manifest instead of inheriting an enclosing pnpm workspace, so declare every dependency it needs and do not depend on workspace-only hoisting. DSH does not transpile TypeScript or infer a package entry.
 
 `dsh.entry` is an optional relative path to a compiled ESM Cordis Plugin inside `.dsh-plugin`. The module may use either namespace exports or a default export and owns its ordinary `name`, `inject`, `Config`, registrations, and effects. `dsh.skills` is an optional array of local skill roots, and `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one of the three fields is required. Skill and MCP paths may reach adjacent repository assets but must remain beneath the directory containing `.dsh-plugin`; the compiled entry must remain inside the package selected and packed by the package manager. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
 
@@ -59,7 +59,7 @@ Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A v
 
 ## Preparation
 
-During exact Git installation, DSH places a temporary host-owned `dsh-plugin-prepare` command on the isolated package lifecycle `PATH`; the command is not fetched from npm. The required `prepack` lifecycle runs after the Git package's dependency installation and before its selected subdirectory is packed, including when `.dsh-plugin` sits inside another package-manager workspace. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to build or prepare fails installation before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
+During exact Git installation, DSH places temporary host-owned `pnpm` and `dsh-plugin-prepare` commands on the isolated package lifecycle `PATH`; neither command is fetched from the repository. The pnpm command reinvokes DSH's pinned pnpm with `--ignore-workspace`, so an enclosing workspace lockfile cannot suppress dependencies declared only by the selected `.dsh-plugin` package. The required `prepack` lifecycle runs after that dependency installation and before the selected subdirectory is packed. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to install, build, or prepare fails before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
 
 ## Runtime composition
 
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 921bf70b8a..c2d0e6d72b 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -32,7 +32,7 @@
 }
 ```
 
-`scripts.prepack` 必须非空并调用 `dsh-plugin-prepare`；可以先运行任意包自有的构建步骤。DSH 已安装的运行时只提供该辅助命令：包自行声明并运行编译器、运行时依赖和其他 NPM 生命周期代码。DSH 不转译 TypeScript，也不推断包入口。
+`scripts.prepack` 必须非空并调用 `dsh-plugin-prepare`；可以先运行任意包自有的构建步骤。DSH 已安装的运行时只提供该辅助命令：包自行声明并运行编译器、运行时依赖和其他 NPM 生命周期代码。所选包按自身 manifest 独立安装，而不继承外层 pnpm workspace，因此必须声明所需的每项依赖，不能依赖仅由 workspace 提升而可见的包。DSH 不转译 TypeScript，也不推断包入口。
 
 `dsh.entry` 是指向 `.dsh-plugin` 内已编译 ESM Cordis 插件的可选相对路径。该模块可以使用 namespace 导出或 default export，并自行拥有常规的 `name`、`inject`、`Config`、注册和 effect。`dsh.skills` 是可选的本地 skill 根数组，`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；三个字段中至少声明一个。skill 和 MCP 路径可以引用相邻的 repository 资源，但必须留在包含 `.dsh-plugin` 的目录下；已编译入口必须留在由包管理器选中并打包的包内。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
 
@@ -59,7 +59,7 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 ## 准备阶段
 
-安装精确指定的 Git 源时，DSH 会把一个临时的宿主自有 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；该命令不从 NPM 获取。必需的 `prepack` 生命周期在 Git 包完成依赖安装后、选定子目录打包前运行，即使 `.dsh-plugin` 位于另一个包管理器工作区内也不例外。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。构建或准备失败时，安装会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
+安装精确指定的 Git 源时，DSH 会把临时的宿主自有 `pnpm` 与 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；两个命令都不从 repository 获取。该 pnpm 命令会以 `--ignore-workspace` 重新调用 DSH 锁定的 pnpm，因此外层 workspace lockfile 无法抑制仅由所选 `.dsh-plugin` 包声明的依赖。必需的 `prepack` 生命周期在该依赖安装完成后、选定子目录打包前运行。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。安装、构建或准备失败时，流程会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
 
 ## 运行时组合
 
diff --git a/vendor/README.md b/vendor/README.md
index 3cc2a313d2..be55f8e77a 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -39,7 +39,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
 9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
-10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. Callers may prepend host-owned executable directories to the isolated package lifecycle `PATH`; all paths are resolved before the child starts. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` run through the bundled pnpm and an injected command directory.
+10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. Callers may prepend host-owned executable directories to the isolated package lifecycle `PATH`; all paths are resolved before the child starts. A transaction-owned `pnpm` wrapper makes pnpm's nested Git-package install reinvoke the same bundled entry with `--ignore-workspace`, so the selected package installs its own manifest dependencies instead of joining an enclosing source workspace. Temporary command directories are removed after the child settles. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` whose package is excluded from an enclosing pnpm lockfile and requires its own build dependency.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
 13. **`include/src/index.ts` serialized child-tree mutation and `hmr/src/index.ts` main-watcher initial-scan suppression**: every Include child-tree mutation (initial apply, refresh, `internal/update` patch re-application) runs through one per-Include queue, because the group's transactional `update` is not reentrant — two concurrent applies interleave create and rollback on the same entries and strand the Include fiber without ever settling. The HMR main watcher passes `ignoreInitial: true`: the initial scan re-announced files boot had just consumed, and its `add` for a config file refreshed an Include mid-initial-apply; once serialized, a failing initial apply's rollback disposed HMR, whose teardown drain waited on the queued refresh sitting behind that same apply — a deadlock that exited 13 with no diagnostic. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a user patch layer present at registration must apply once. Covered by the patch-overlay boot-failure built-bin case in `apps/cli/tests/built-bin.e2e.ts`.
diff --git a/vendor/loader/src/repository.ts b/vendor/loader/src/repository.ts
index c0cd1589aa..91ad9c372a 100644
--- a/vendor/loader/src/repository.ts
+++ b/vendor/loader/src/repository.ts
@@ -8,6 +8,7 @@ import { spawn } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
 import { delimiter, dirname, join, resolve } from 'node:path'
 
 /** Exact pnpm release shipped with the Loader for repository installation. */
@@ -48,6 +49,14 @@ function installEnvironment(executableDirectories: readonly string[]): NodeJS.Pr
   }
 }
 
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+function batchQuote(value: string): string {
+  return `"${value.replaceAll('%', '%%')}"`
+}
+
 function appendOutput(current: string, chunk: Uint8Array): string {
   const combined = current + Buffer.from(chunk).toString('utf8')
   return combined.length <= MAX_ERROR_OUTPUT ? combined : combined.slice(-MAX_ERROR_OUTPUT)
@@ -60,29 +69,46 @@ async function installWithBundledPnpm(
   const require = createRequire(import.meta.url)
   const pnpmManifest = require.resolve('pnpm')
   const pnpmBin = join(dirname(pnpmManifest), 'bin', 'pnpm.mjs')
-  let output = ''
-  const result = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
-    const child = spawn(process.execPath, [
-      pnpmBin,
-      'install',
-      '--no-frozen-lockfile',
-      '--reporter=append-only',
-    ], {
-      cwd: directory,
-      env: installEnvironment(executableDirectories),
-      shell: false,
-      stdio: ['ignore', 'pipe', 'pipe'],
+  const commandDirectory = await mkdtemp(join(tmpdir(), 'cordis-repository-pnpm-'))
+  try {
+    await Promise.all([
+      writeFile(join(commandDirectory, 'pnpm'), [
+        '#!/bin/sh',
+        `exec ${shellQuote(process.execPath)} ${shellQuote(pnpmBin)} --ignore-workspace "$@"`,
+        '',
+      ].join('\n'), { mode: 0o700 }),
+      writeFile(join(commandDirectory, 'pnpm.cmd'), [
+        '@echo off',
+        `${batchQuote(process.execPath)} ${batchQuote(pnpmBin)} --ignore-workspace %*`,
+        '',
+      ].join('\r\n'), { mode: 0o700 }),
+    ])
+    let output = ''
+    const result = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
+      const child = spawn(process.execPath, [
+        pnpmBin,
+        'install',
+        '--no-frozen-lockfile',
+        '--reporter=append-only',
+      ], {
+        cwd: directory,
+        env: installEnvironment([commandDirectory, ...executableDirectories]),
+        shell: false,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      child.stdout.on('data', (chunk: Uint8Array) => { output = appendOutput(output, chunk) })
+      child.stderr.on('data', (chunk: Uint8Array) => { output = appendOutput(output, chunk) })
+      child.once('error', reject)
+      child.once('close', (code, signal) => { resolve({ code, signal }) })
     })
-    child.stdout.on('data', (chunk: Uint8Array) => { output = appendOutput(output, chunk) })
-    child.stderr.on('data', (chunk: Uint8Array) => { output = appendOutput(output, chunk) })
-    child.once('error', reject)
-    child.once('close', (code, signal) => { resolve({ code, signal }) })
-  })
-  if (result.signal !== null) {
-    throw new Error(`bundled pnpm install was killed by ${result.signal}${output ? `\n${output.trimEnd()}` : ''}`)
-  }
-  if (result.code !== 0) {
-    throw new Error(`bundled pnpm install exited with code ${String(result.code)}${output ? `\n${output.trimEnd()}` : ''}`)
+    if (result.signal !== null) {
+      throw new Error(`bundled pnpm install was killed by ${result.signal}${output ? `\n${output.trimEnd()}` : ''}`)
+    }
+    if (result.code !== 0) {
+      throw new Error(`bundled pnpm install exited with code ${String(result.code)}${output ? `\n${output.trimEnd()}` : ''}`)
+    }
+  } finally {
+    await rm(commandDirectory, { recursive: true, force: true })
   }
 }
 

From c750d5a9087532ebb8b207dff266794ed7e7c992 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 20:12:38 +0800
Subject: [PATCH 440/516] test(repository-plugin): resolve published Cordis
 types

---
 .../github-repository-plugin/.dsh-plugin/tsconfig.json        | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json
index 632e4db48c..22d9301cfb 100644
--- a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/tsconfig.json
@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
     "target": "ES2024",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
     "strict": true,
     "skipLibCheck": true,
     "noEmit": true

From 67b9e9b1d6eef219864c8cfa1cfca9c56935daa5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 20:29:21 +0800
Subject: [PATCH 441/516] test(repository-plugin): isolate agent mock sequence

---
 apps/cli/tests/github-repository-plugin.built.e2e.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index 0c13a71a02..2e1ea4a08c 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -35,6 +35,8 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       '  config:',
       '    repositories:',
       `      - ${JSON.stringify(source)}`,
+      '- id: session-title-llm',
+      '  disabled: true',
       '',
     ].join('\n'))
 

From 913ecf5f1dbd7dfabb6ec49754882e2c8e114d6e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:13:20 +0800
Subject: [PATCH 442/516] fix(mcp-client): await Cordis startup discovery

---
 ...-trusted-repository-package-code.i18n.yaml |  4 +--
 ...6-08-08-trusted-repository-package-code.md |  6 ++--
 ...8-08-trusted-repository-package-code.zh.md |  6 ++--
 .../github-repository-plugin.built.e2e.ts     | 11 +++---
 docs/config-catalog.md                        |  6 +++-
 packages/mcp/mcp-client/README.i18n.yaml      |  4 +--
 packages/mcp/mcp-client/README.md             |  3 +-
 packages/mcp/mcp-client/README.zh.md          |  3 +-
 packages/mcp/mcp-client/src/index.ts          | 31 ++++++++++------
 packages/mcp/mcp-client/tests/apply.spec.ts   | 36 ++++++++++++++++++-
 .../mcp/mcp-client/tests/mcp-client.e2e.ts    |  8 ++++-
 .../mcp/mcp-client/tests/mcp-client.spec.ts   |  5 +++
 .../repository-plugin/README.i18n.yaml        |  4 +--
 .../repository-plugin/README.md               |  2 +-
 .../repository-plugin/README.zh.md            |  2 +-
 .../repository-plugin/src/mcp.ts              |  4 +++
 .../tests/mcp-format.spec.ts                  |  4 +++
 .../tests/repository-plugin.spec.ts           |  8 ++---
 18 files changed, 108 insertions(+), 39 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
index eeea186c92..74c4f0eb41 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.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 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
-2026-08-08-trusted-repository-package-code.md: 4968d29a6da4180a8b016eef9176acb9bc64d8b1
-2026-08-08-trusted-repository-package-code.zh.md: 2e9f59bb1f571bb1bace9623a9e6976e0238a017
+2026-08-08-trusted-repository-package-code.md: cf72853836901af9c1c9e9f0d3d23f43997a4e97
+2026-08-08-trusted-repository-package-code.zh.md: cea47d85973a81f904b1596051ac58996459c635
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
index 4968d29a6d..cf72853836 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
@@ -18,7 +18,7 @@ The package owns its npm dependencies and build toolchain. `scripts.prepack` is
 
 The generated wrapper first mounts the DSH-owned static runtime for skills and MCP definitions, then dynamically imports and unwraps the explicit entry and mounts it as a child. Both children must reach Cordis `ACTIVE`; an unsatisfied `inject` or startup exception rejects the repository Loader transaction instead of committing an inert generation. Loader removal, failed replacement, and parent disposal unwind the entry, skill providers, MCP clients, and their effects together.
 
-`dsh-mcp-client` resolves its initial connection and tool synchronization promise as part of Plugin application. A valid server's tools therefore exist before its parent repository wrapper activates and before a one-shot application starts its first model request. Initial connection failure keeps the existing contained failure contract: it is logged, the client activates with no tools, and disposal still closes the transport.
+`dsh-mcp-client` resolves its initial connection and tool synchronization promise as part of Plugin application. Its entry is an `async function`, not an ordinary function returning a Promise: Cordis identifies prototype-bearing ordinary functions as constructors and does not treat a constructor's returned Promise as startup work. A valid server's tools therefore exist before its parent repository wrapper activates and before a one-shot application starts its first model request. Its `failOnStartupError` config preserves optional standalone servers by default while letting repository adapters require their declared servers. Repository-translated MCP clients enable that mode, so initial connection or discovery failure rejects the candidate generation and rollback still closes the transport.
 
 ## Trust boundary
 
@@ -41,11 +41,11 @@ Model-visible behavior remains governed by the owning DSH seam. A repository ent
 - A TypeScript DSH Plugin can live in a GitHub repository, install ordinary npm dependencies, compile during `prepack`, and run without publishing the Plugin package to npm.
 - Static-only repository packages remain valid and retain import-free wrappers; adding `dsh.entry` opts that package into runtime code import.
 - A package build, dependency install, entry import, unmet service, or Plugin startup failure prevents the candidate generation from replacing the last good configuration.
-- The initial MCP connection can lengthen application startup, while a contained connection failure still yields a running application with no tools from that server.
+- The initial MCP connection can lengthen application startup, and a repository-declared server that is unavailable prevents that candidate generation from activating.
 - Repository code receives host authority, so source review and immutable pinning are operational security requirements rather than optional hardening.
 
 ## Testing
 
-Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication while preserving contained connect failure and teardown.
+Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication, preserve opt-in contained connect failure, and prove strict startup rejection still closes the client.
 
 The Node 24 consumer acceptance uses the actual built `dsh run` command with a fresh DSH home and an authenticated private GitHub source pinned to the pull request's exact head SHA. That repository package installs pinned runtime and development dependencies, type-checks and bundles TypeScript during `prepack`, prepares a skill plus a stdio MCP server and `dsh.entry`, exposes the skill and MCP schema in the first real model request, executes the MCP tool, and lets the compiled Cordis entry append a second marker to the result observed in the following request. Cache assertions require source files to be absent from the packed installation while both built modules, their installed dependency, copied assets, and generated wrapper are present.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
index 2e9f59bb1f..cea47d8597 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
@@ -18,7 +18,7 @@
 
 生成的包装层先挂载 DSH 自有的静态运行时来处理 skill 和 MCP 定义，再动态导入显式入口、解包其导出并将其挂载为子级。两个子级都必须进入 Cordis `ACTIVE`；无法满足的 `inject` 或启动异常会拒绝 repository Loader 事务，而不会提交未激活的 generation。Loader 移除、替换失败和父级 dispose（资源释放）会一并撤销入口、skill 提供方、MCP client 及其 effect。
 
-`dsh-mcp-client` 会在插件应用期间完成其初始连接和工具同步 promise。因此，有效 server 的工具会在父级 repository 包装层激活前、一次性应用发起首个模型请求前就已存在。初始连接失败沿用既有的收束失败契约：系统会记录日志，client 激活但不注册工具，dispose 仍会关闭 transport。
+`dsh-mcp-client` 会在插件应用期间完成其初始连接和工具同步 promise。其入口必须是 `async function`，而不是返回 Promise 的普通函数：Cordis 会把带 prototype 的普通函数识别为 constructor，不会把 constructor 返回的 Promise 当作启动工作。因此，有效 server 的工具会在父级 repository 包装层激活前、一次性应用发起首个模型请求前就已存在。其 `failOnStartupError` 配置默认保留独立可选 server 的行为，同时允许 repository adapter 要求已声明 server 必须可用。Repository 转换出的 MCP client 会启用该模式，因此初始连接或发现失败会拒绝候选 generation，回滚仍会关闭 transport。
 
 ## 信任边界
 
@@ -41,11 +41,11 @@
 - TypeScript DSH 插件可以存放在 GitHub 仓库中，安装普通 NPM 依赖，在 `prepack` 期间完成编译，并在无需把插件包发布到 NPM 的情况下运行。
 - 仅含静态贡献的 repository 包仍然有效，并保留无 import 包装层；添加 `dsh.entry` 会使该包选择启用运行时代码导入。
 - 包构建、依赖安装、入口导入、所需服务未满足或插件启动失败，都会阻止候选 generation 替换最后一个可用配置。
-- 初始 MCP 连接可能延长应用启动时间；连接失败被收束后，仍会得到一个正常运行、但不含该 server 工具的应用。
+- 初始 MCP 连接可能延长应用启动时间；repository 声明的 server 不可用时，该候选 generation 无法激活。
 - Repository 代码获得宿主权限，因此源码评审和锁定不可变 ref 是运行安全要求，而不是可选加固措施。
 
 ## 测试
 
-repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，同时保留收束连接失败与清理覆盖。
+repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，保留选择收束连接失败的能力，并证明严格启动拒绝仍会关闭 client。
 
 Node 24 消费方验收使用实际构建的 `dsh run` 命令、全新 DSH 主目录，以及锁定到 PR（Pull Request）的精确 head SHA 且经过认证的私有 GitHub 源。该 repository 包安装固定版本的运行时依赖与开发依赖，在 `prepack` 期间对 TypeScript 进行类型检查和打包，准备一个 skill、一个 stdio MCP server 及 `dsh.entry`，在首个真实模型请求中暴露 skill 与 MCP schema，执行 MCP 工具，并让已编译 Cordis 入口向结果追加第二个标记，供后续请求观察。缓存断言要求打包安装中不存在源码文件，同时必须存在两个已构建模块、其已安装依赖、复制资源和生成包装层。
diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index 2e1ea4a08c..fb0bf2937a 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -67,15 +67,16 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}`).toBe(0)
       expect(result.stdout).toBe('trusted GitHub repository package reached dsh run')
       expect(server.requests).toHaveLength(2)
+      const runtimeDiagnostic = `${result.stderr}\nstdout:\n${result.stdout}`
       const firstRequest = JSON.stringify(server.requests[0]!.body)
       const secondRequest = JSON.stringify(server.requests[1]!.body)
-      expect(firstRequest).toContain(
+      expect(firstRequest, runtimeDiagnostic).toContain(
         'Proves that dsh installed a private repository Plugin from an exact GitHub source.',
       )
-      expect(firstRequest).toContain('mcp__github_repository__proof')
-      expect(firstRequest).toContain('Proves that an MCP server compiled from the exact GitHub repository package is active.')
-      expect(secondRequest).toContain('MCP_FROM_GITHUB_REPOSITORY')
-      expect(secondRequest).toContain('TS_PLUGIN_FROM_GITHUB_REPOSITORY')
+      expect(firstRequest, runtimeDiagnostic).toContain('mcp__github_repository__proof')
+      expect(firstRequest, runtimeDiagnostic).toContain('Proves that an MCP server compiled from the exact GitHub repository package is active.')
+      expect(secondRequest, runtimeDiagnostic).toContain('MCP_FROM_GITHUB_REPOSITORY')
+      expect(secondRequest, runtimeDiagnostic).toContain('TS_PLUGIN_FROM_GITHUB_REPOSITORY')
 
       const cacheRoot = join(home, 'cache', 'repository-plugins')
       const generations = readdirSync(cacheRoot, { withFileTypes: true }).filter(entry => entry.isDirectory())
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 153ac72cc3..9cc95bcaf5 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -988,6 +988,8 @@ export interface StdioConfig {
   cwd: string
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
+  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  failOnStartupError: boolean
 }
 
 /** Config for connecting to an MCP server over Streamable HTTP (SSE). */
@@ -1006,10 +1008,12 @@ export interface StreamableHttpConfig {
   headers: Record<string, string>
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
+  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  failOnStartupError: boolean
 }
 ```
 
-Source: [`packages/mcp/mcp-client/src/index.ts:96`](../packages/mcp/mcp-client/src/index.ts)
+Source: [`packages/mcp/mcp-client/src/index.ts:100`](../packages/mcp/mcp-client/src/index.ts)
 
 ## `@deepseek-ai/dsh-permission`
 
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index 6b6d4d9270..2d47705a0a 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-client/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/mcp/mcp-client/README.md
-README.md: 6bcc195e36d24d7e5ae3462573b30f1b41c963a7
-README.zh.md: 8886c16c3fe66d283ae2191661118729a89f1aeb
+README.md: c87255917a2def0aef938af9f2c910b65d5a96d5
+README.zh.md: 6fd6df39d7c5034795021d41de57f8500cbfd1c5
diff --git a/packages/mcp/mcp-client/README.md b/packages/mcp/mcp-client/README.md
index 6bcc195e36..c87255917a 100644
--- a/packages/mcp/mcp-client/README.md
+++ b/packages/mcp/mcp-client/README.md
@@ -44,6 +44,7 @@ The model sees `mcp__github__create_issue`, `mcp__web__search`, … — the same
 | `url` | http | yes | MCP server URL |
 | `headers` | http | no | Extra headers (e.g. auth tokens) |
 | `toolCallTimeoutMs` | both | no | Timeout per `callTool` invocation (default 60000) |
+| `failOnStartupError` | both | no | Reject plugin activation when the initial connection or tool discovery fails (default `false`) |
 
 ## Tool naming
 
@@ -56,7 +57,7 @@ Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`
 
 ## Behavior
 
-- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection failure is logged and activates with no tools.
+- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection or discovery failure is always logged; it rejects activation when `failOnStartupError` is true and otherwise activates with no tools.
 - Listens for `notifications/tools/list_changed` → re-syncs; a failed re-sync keeps the previous generation registered.
 - Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support—the public name is never sent to the server.
 - Canonical success is `{ content: JsonValue[], structuredContent? }`; complete JSON MCP blocks survive for programmatic callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`.
diff --git a/packages/mcp/mcp-client/README.zh.md b/packages/mcp/mcp-client/README.zh.md
index 8886c16c3f..6fd6df39d7 100644
--- a/packages/mcp/mcp-client/README.zh.md
+++ b/packages/mcp/mcp-client/README.zh.md
@@ -44,6 +44,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 | `url` | http | 是 | MCP 服务器 URL |
 | `headers` | http | 否 | 额外标头（例如认证 token） |
 | `toolCallTimeoutMs` | 两者 | 否 | 每次 `callTool` 调用的超时（默认 60000） |
+| `failOnStartupError` | 两者 | 否 | 初始连接或工具发现失败时拒绝插件激活（默认 `false`） |
 
 ## 工具命名
 
@@ -56,7 +57,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 行为
 
-- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接失败会记录日志，插件仍会激活但不注册工具。
+- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接或发现失败始终会记录日志；`failOnStartupError` 为 true 时拒绝激活，否则插件仍会激活但不注册工具。
 - 监听 `notifications/tools/list_changed` → 重新同步；同步失败时保留上一世代的注册。
 - 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
 - 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
diff --git a/packages/mcp/mcp-client/src/index.ts b/packages/mcp/mcp-client/src/index.ts
index 9798b4cfcb..348003be52 100644
--- a/packages/mcp/mcp-client/src/index.ts
+++ b/packages/mcp/mcp-client/src/index.ts
@@ -72,6 +72,8 @@ export interface StdioConfig {
   cwd: string
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
+  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  failOnStartupError: boolean
 }
 
 /** Config for connecting to an MCP server over Streamable HTTP (SSE). */
@@ -90,6 +92,8 @@ export interface StreamableHttpConfig {
   headers: Record<string, string>
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
+  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  failOnStartupError: boolean
 }
 
 /** Configuration for one stdio or Streamable HTTP MCP server. */
@@ -104,6 +108,7 @@ export const Config = z.union([
     env: z.dict(String).default({}),
     cwd: z.string().default(''),
     toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+    failOnStartupError: z.boolean().default(false),
   }),
   z.object({
     transport: z.const('streamable-http'),
@@ -111,6 +116,7 @@ export const Config = z.union([
     url: z.string().required(),
     headers: z.dict(String).default({}),
     toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+    failOnStartupError: z.boolean().default(false),
   }),
 ]) as unknown as z<Config>
 
@@ -118,11 +124,13 @@ export const Config = z.union([
 
 /**
  * Connect one MCP server and publish its initial tool generation before activation.
+ * This entry remains explicitly `async`: Cordis treats a prototype-bearing
+ * ordinary function as a constructor, whose returned Promise is not startup work.
  * @param ctx - plugin context carrying the tool registry.
  * @param config - resolved transport and server namespace configuration.
  * @returns startup readiness after connection and initial tool discovery settle.
  */
-export function apply(ctx: Context, config: Config): Promise<void> {
+export async function apply(ctx: Context, config: Config): Promise<void> {
   // Reserve the namespace first: a duplicate `serverName` fails THIS instance
   // at load with an actionable error and leaves the earlier instance intact.
   ctx.effect(() => {
@@ -151,10 +159,10 @@ export function apply(ctx: Context, config: Config): Promise<void> {
     toolCallTimeoutMs: config.toolCallTimeoutMs,
   }
 
-  // Connect and set up tools. Errors during connect/first sync are logged,
-  // not thrown (the plugin simply has no tools registered). `ready` resolves
-  // to an accessor for the CURRENT disposer generation, so the effect
-  // disposer below always unregisters the live set, not the first one.
+  // Connect and set up tools. `ready` always settles to an outcome so rollback
+  // can close a partially opened client even when strict startup later rejects.
+  // Its accessor returns the CURRENT disposer generation, so disposal always
+  // unregisters the live set, not the first one.
   const ready = (async () => {
     await client.connect(transport)
 
@@ -174,17 +182,20 @@ export function apply(ctx: Context, config: Config): Promise<void> {
       },
     )
 
-    return () => disposers
+    return { getDisposers: () => disposers }
   })().catch((error: unknown) => {
     ctx.logger.error(`mcp-client(${config.serverName}): failed to connect: ${String(error)}`)
-    return () => new Map<string, () => void>()
+    return { getDisposers: () => new Map<string, () => void>(), error }
   })
 
   ctx.effect(() => async () => {
-    const live = await ready
-    for (const dispose of live().values()) dispose()
+    const outcome = await ready
+    for (const dispose of outcome.getDisposers().values()) dispose()
     try { await client.close() } catch { /* transport already gone */ }
   }, 'mcp-client.connection')
 
-  return ready.then(() => undefined)
+  const outcome = await ready
+  if ('error' in outcome && config.failOnStartupError) {
+    throw new Error(`mcp-client(${config.serverName}): initial connection or tool discovery failed`, { cause: outcome.error })
+  }
 }
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index 6bb97a7032..b2444341f1 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -82,6 +82,7 @@ const stdioConfig: Config = {
   env: {},
   cwd: '',
   toolCallTimeoutMs: 60_000,
+  failOnStartupError: false,
 }
 
 // ---- Tests ----
@@ -150,11 +151,30 @@ describe('apply (plugin lifecycle)', () => {
     expect(ctx.tools.get('remote')).toBeUndefined()
   })
 
+  it('keeps the Cordis plugin loading until initial discovery publishes its tools', async () => {
+    const connection: PromiseWithResolvers<void> = Promise.withResolvers()
+    mockConnect.mockImplementation(async () => {
+      await connection.promise
+    })
+    const fiber = ctx.plugin({ name: 'mcp-client-lifecycle', inject, apply }, stdioConfig)
+    let activated = false
+    const activation = Promise.resolve(fiber).then(() => { activated = true })
+
+    await vi.waitFor(() => { expect(mockConnect).toHaveBeenCalled() })
+    expect(activated).toBe(false)
+    expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
+
+    connection.resolve()
+    await activation
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+    await fiber.dispose()
+  })
+
   it('rejects a duplicate serverName at load and leaves the first instance intact', async () => {
     await apply(ctx, stdioConfig)
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
-    expect(() => { void apply(ctx, stdioConfig) }).toThrow(/serverName "srv" is already in use/)
+    await expect(apply(ctx, stdioConfig)).rejects.toThrow(/serverName "srv" is already in use/)
     // First instance unaffected.
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
   })
@@ -204,6 +224,19 @@ describe('apply (plugin lifecycle)', () => {
     expect(mockClose).toHaveBeenCalled()
   })
 
+  it('rejects activation and still closes the client when startup failure is configured as fatal', async () => {
+    mockConnect.mockRejectedValue(new Error('connection refused'))
+    await expect(apply(ctx, {
+      ...stdioConfig,
+      failOnStartupError: true,
+    })).rejects.toThrow('initial connection or tool discovery failed')
+
+    expect(mockListTools).not.toHaveBeenCalled()
+    expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
+    await ctx.fiber.dispose()
+    expect(mockClose).toHaveBeenCalled()
+  })
+
   it('re-syncs tools on ToolListChanged notification', async () => {
     await apply(ctx, stdioConfig)
 
@@ -275,6 +308,7 @@ describe('apply (plugin lifecycle)', () => {
       url: 'http://localhost:3000/mcp',
       headers: { Authorization: 'Bearer x' },
       toolCallTimeoutMs: 30_000,
+      failOnStartupError: false,
     }
 
     await apply(ctx, httpConfig)
diff --git a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
index 6a71ab4007..e1f51d20e9 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
@@ -75,6 +75,7 @@ describe('fixture server — controlled scenarios', () => {
     env: {},
     cwd: packageDir,
     toolCallTimeoutMs: 15_000,
+    failOnStartupError: false,
   }
 
   beforeAll(async () => {
@@ -164,10 +165,11 @@ describe('fixture server — duplicate serverName', () => {
       env: {},
       cwd: packageDir,
       toolCallTimeoutMs: 15_000,
+      failOnStartupError: false,
     }
     await apply(ctx, config)
 
-    expect(() => { void apply(ctx, config) }).toThrow(/serverName "dup" is already in use/)
+    await expect(apply(ctx, config)).rejects.toThrow(/serverName "dup" is already in use/)
 
     await ctx.fiber.dispose()
     await sleep(200)
@@ -185,6 +187,7 @@ describe('fixture server — disposal', () => {
       env: {},
       cwd: packageDir,
       toolCallTimeoutMs: 15_000,
+      failOnStartupError: false,
     })
 
     // Tools are registered before dispose.
@@ -210,6 +213,7 @@ describe('server-everything — official test server', () => {
     env: {},
     cwd: '',
     toolCallTimeoutMs: 30_000,
+    failOnStartupError: false,
   }
 
   beforeAll(async () => {
@@ -277,6 +281,7 @@ describe('server-filesystem — real filesystem operations', () => {
       env: {},
       cwd: '',
       toolCallTimeoutMs: 30_000,
+      failOnStartupError: false,
     }
     await apply(ctx, config)
   }, 60_000)
@@ -393,6 +398,7 @@ describe('streamable-http — in-process MCP server', () => {
       url: baseUrl,
       headers: { Authorization: 'Bearer e2e-test-token' },
       toolCallTimeoutMs: 15_000,
+      failOnStartupError: false,
     }
     await apply(ctx, config)
   }, 30_000)
diff --git a/packages/mcp/mcp-client/tests/mcp-client.spec.ts b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
index f70f5aa6c1..b95251e7d3 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.spec.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
@@ -713,6 +713,7 @@ describe('createTransport', () => {
       env: {},
       cwd: '/tmp',
       toolCallTimeoutMs: 60_000,
+      failOnStartupError: false,
     }
     const transport = createTransport(config)
     expect(transport).toBeDefined()
@@ -727,6 +728,7 @@ describe('createTransport', () => {
       url: 'http://localhost:3000/mcp',
       headers: {},
       toolCallTimeoutMs: 60_000,
+      failOnStartupError: false,
     }
     const transport = createTransport(config)
     expect(transport).toBeDefined()
@@ -741,6 +743,7 @@ describe('createTransport', () => {
       url: 'http://localhost:3000/mcp',
       headers: { Authorization: 'Bearer token' },
       toolCallTimeoutMs: 60_000,
+      failOnStartupError: false,
     }
     const transport = createTransport(config)
     expect(transport).toBeDefined()
@@ -764,6 +767,7 @@ describe('createTransport', () => {
         env: { EXTRA: 'injected' },
         cwd: '',
         toolCallTimeoutMs: 60_000,
+        failOnStartupError: false,
       }
       // createTransport internally calls buildChildEnv; we verify by inspecting
       // the constructed StdioClientTransport. Since we can't inspect private fields
@@ -791,6 +795,7 @@ describe('createTransport', () => {
       env: { CUSTOM: 'value' },
       cwd: '',
       toolCallTimeoutMs: 60_000,
+      failOnStartupError: false,
     }
     const transport = createTransport(config)
     expect(transport).toBeDefined()
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index d41f4681a1..5c4ad1e929 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 1d858c5adcc208768dcbe99f129b47abb1722431
-README.zh.md: c2d0e6d72baeb0efb25abd8d50fee2922d2e810b
+README.md: e10907408a98cd470ae935b327ae44322f2e54a7
+README.zh.md: b8ba7dccd929574cc5aa1b7a3d68bf4f1e2f80e4
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 1d858c5adc..e10907408a 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -69,7 +69,7 @@ Loading this package registers one effect-scoped Loader builtin. Each generated
 
 The `.mcp.json` root is `{ "mcpServers": { ... } }`. A stdio entry accepts only `type: "stdio"` (optional), `command`, `args`, and `env`; an HTTP entry accepts only `type: "http"`, `url`, and `headers`. String values support exact `${NAME}` process-environment expansion at Plugin load, and a missing name fails that load. HTTP URLs become the existing MCP client's `streamable-http` transport; stdio entries use the prepared package directory as `cwd`.
 
-Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle. Plugin activation waits for the initial connection and tool discovery, so the first model request observes a successful initial tool generation; a network or child-process connection failure is logged and still activates with no tools.
+Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle. Repository-declared servers enable its strict startup mode: Plugin activation waits for the initial connection and tool discovery, so the first model request observes a successful initial tool generation, while a network, child-process, or discovery failure rejects the candidate repository generation instead of silently activating without its declared tools.
 
 ## Export shape
 
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index c2d0e6d72b..b8ba7dccd9 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -69,7 +69,7 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 `.mcp.json` 根对象是 `{ "mcpServers": { ... } }`。stdio 条目只接受可选的 `type: "stdio"`、`command`、`args` 和 `env`；HTTP 条目只接受 `type: "http"`、`url` 和 `headers`。字符串值在插件加载时支持严格的 `${NAME}` 进程环境变量展开；缺失变量会使该次加载失败。HTTP URL 映射到现有 MCP client 的 `streamable-http` transport；stdio 条目以已准备的包目录作为 `cwd`。
 
-未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期。插件激活会等待初始连接与工具发现，因此首个模型请求会看到成功的初始工具 generation；网络或子进程连接失败会记录日志，且插件仍会激活但不注册工具。
+未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期。Repository 声明的 server 会启用其严格启动模式：插件激活会等待初始连接与工具发现，因此首个模型请求会看到成功的初始工具 generation；网络、子进程或发现失败则会拒绝候选 repository generation，而不是在缺少已声明工具的情况下静默激活。
 
 ## 导出形状
 
diff --git a/packages/self-modification/repository-plugin/src/mcp.ts b/packages/self-modification/repository-plugin/src/mcp.ts
index bce8179121..6c1c5ccbf3 100644
--- a/packages/self-modification/repository-plugin/src/mcp.ts
+++ b/packages/self-modification/repository-plugin/src/mcp.ts
@@ -49,12 +49,14 @@ export type ResolvedMcpServer =
     args: string[]
     env: Record<string, string>
     cwd: string
+    failOnStartupError: true
   }
   | {
     transport: 'streamable-http'
     serverName: string
     url: string
     headers: Record<string, string>
+    failOnStartupError: true
   }
 
 function assertTemplate(value: string, location: string): void {
@@ -135,6 +137,7 @@ export function resolveMcpServers(document: McpDocument, environment: NodeJS.Pro
         args: (definition.args ?? []).map((value, index) => expand(value, environment, `mcpServers.${serverName}.args[${index}]`)),
         env: expandMap(definition.env, environment, `mcpServers.${serverName}.env`),
         cwd,
+        failOnStartupError: true,
       }
     }
     const url = expand(definition.url, environment, `mcpServers.${serverName}.url`)
@@ -147,6 +150,7 @@ export function resolveMcpServers(document: McpDocument, environment: NodeJS.Pro
       serverName,
       url,
       headers: expandMap(definition.headers, environment, `mcpServers.${serverName}.headers`),
+      failOnStartupError: true,
     }
   })
 }
diff --git a/packages/self-modification/repository-plugin/tests/mcp-format.spec.ts b/packages/self-modification/repository-plugin/tests/mcp-format.spec.ts
index 5251ccdbc2..709c1a2c4b 100644
--- a/packages/self-modification/repository-plugin/tests/mcp-format.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/mcp-format.spec.ts
@@ -22,6 +22,7 @@ describe('repository plugin common .mcp.json support', () => {
       serverName: 'expo',
       url: 'https://mcp.expo.dev/mcp',
       headers: {},
+      failOnStartupError: true,
     }])
   })
 
@@ -43,6 +44,7 @@ describe('repository plugin common .mcp.json support', () => {
       args: ['--endpoint', 'http://localhost:8000'],
       env: { DJ_API_URL: 'http://localhost:8000' },
       cwd: '/plugin',
+      failOnStartupError: true,
     }])
   })
 
@@ -74,12 +76,14 @@ describe('repository plugin common .mcp.json support', () => {
         args: [],
         env: {},
         cwd: '/plugin',
+        failOnStartupError: true,
       },
       {
         transport: 'streamable-http',
         serverName: 'remote',
         url: 'http://localhost:3000/mcp',
         headers: { Authorization: 'Bearer test-token' },
+        failOnStartupError: true,
       },
     ])
   })
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index 06cacfd699..40ae773e55 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -261,7 +261,7 @@ describe('prepared repository plugin Loader composition', () => {
     await ctx.fiber.dispose()
   })
 
-  it('delegates an MCP-only plugin to the existing client without turning connect failure into Loader failure', async () => {
+  it('fails an MCP repository plugin load when its declared server cannot connect', async () => {
     const root = await temporaryDirectory('mcp-loader')
     await writeFile(join(root, '.mcp.json'), JSON.stringify({
       mcpServers: { offline: { command: join(root, 'missing-mcp-command') } },
@@ -275,12 +275,10 @@ describe('prepared repository plugin Loader composition', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(RepositoryPlugin)
-    const id = await ctx.loader.create({
+    await expect(ctx.loader.create({
       name: pathToFileURL(join(directory, RepositoryPlugin.PREPARED_ENTRY_FILENAME)).href,
-    })
-    await ctx.loader.await()
+    })).rejects.toThrow('initial connection or tool discovery failed')
     expect(ctx.tools.schemas().some(tool => tool.name.startsWith('mcp__offline__'))).toBe(false)
-    await ctx.loader.remove(id)
     await ctx.fiber.dispose()
   })
 

From e91ff6d4995d9ce93ca1446d9d501130c3fcdf9a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 8 Aug 2026 21:19:04 +0800
Subject: [PATCH 443/516] test(repository-plugin): cover MCP activation cleanup

---
 .../tests/repository-plugin.spec.ts           | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index 40ae773e55..26b739677a 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -261,6 +261,60 @@ describe('prepared repository plugin Loader composition', () => {
     await ctx.fiber.dispose()
   })
 
+  it('mounts and removes tools discovered from a repository MCP server', async () => {
+    const root = await temporaryDirectory('mcp-loader-success')
+    const server = join(root, 'mcp-server.mjs')
+    await writeFile(server, [
+      "import { createInterface } from 'node:readline'",
+      'const lines = createInterface({ input: process.stdin })',
+      'for await (const line of lines) {',
+      '  const request = JSON.parse(line)',
+      "  if (!('id' in request)) continue",
+      '  let result',
+      "  if (request.method === 'initialize') {",
+      '    result = {',
+      '      protocolVersion: request.params.protocolVersion,',
+      '      capabilities: { tools: {} },',
+      "      serverInfo: { name: 'repository-fixture', version: '0.0.0' },",
+      '    }',
+      "  } else if (request.method === 'tools/list') {",
+      '    result = {',
+      '      tools: [{',
+      "        name: 'proof',",
+      "        description: 'Repository MCP proof.',",
+      "        inputSchema: { type: 'object', properties: {} },",
+      '      }],',
+      '    }',
+      '  } else {',
+      '    result = {}',
+      '  }',
+      "  process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, result })}\\n`)",
+      '}',
+      '',
+    ].join('\n'))
+    await writeFile(join(root, '.mcp.json'), JSON.stringify({
+      mcpServers: { online: { command: process.execPath, args: [server] } },
+    }))
+    const directory = await writePlugin(root, 'mcp-loader-success-fixture', { mcpServers: '../.mcp.json' })
+    await RepositoryPlugin.prepareDshPlugin(directory)
+
+    const ctx = new Context()
+    ctx.baseUrl = pathToFileURL(directory).href + '/'
+    await ctx.plugin(Loader)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(RepositoryPlugin)
+    const id = await ctx.loader.create({
+      name: pathToFileURL(join(directory, RepositoryPlugin.PREPARED_ENTRY_FILENAME)).href,
+    })
+    await ctx.loader.await()
+    expect(ctx.tools.get('mcp__online__proof')).toBeDefined()
+
+    await ctx.loader.remove(id)
+    expect(ctx.tools.get('mcp__online__proof')).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
   it('fails an MCP repository plugin load when its declared server cannot connect', async () => {
     const root = await temporaryDirectory('mcp-loader')
     await writeFile(join(root, '.mcp.json'), JSON.stringify({

From 29b3e3fa84cdd6a0c2a20ec7615af50eec265301 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:16:14 +0800
Subject: [PATCH 444/516] fix(repository-plugin): require published prepare
 dependency

---
 ...-static-repository-plugin-format.i18n.yaml |   4 +-
 ...6-07-30-static-repository-plugin-format.md |   2 +-
 ...7-30-static-repository-plugin-format.zh.md |   2 +-
 ...-trusted-repository-package-code.i18n.yaml |   4 +-
 ...6-08-08-trusted-repository-package-code.md |   4 +-
 ...8-08-trusted-repository-package-code.zh.md |   4 +-
 ...owned-git-repository-plugin-preparation.md |  48 -------
 ...ed-git-repository-plugin-preparation.zh.md |  48 -------
 ...t-repository-plugin-preparation.i18n.yaml} |   6 +-
 ...acked-git-repository-plugin-preparation.md |  48 +++++++
 ...ed-git-repository-plugin-preparation.zh.md |  48 +++++++
 .../.dsh-plugin/package.json                  |   1 +
 .../github-repository-plugin.built.e2e.ts     | 134 +++++++++++++++++-
 docs/config-catalog.md                        |   2 +-
 knip.json                                     |   3 +
 .../app-boot/tests/repository-cache.spec.ts   |  40 +++---
 .../repository-plugin/README.i18n.yaml        |   4 +-
 .../repository-plugin/README.md               |   5 +-
 .../repository-plugin/README.zh.md            |   5 +-
 .../repository-plugin/package.json            |  20 +++
 .../repository-plugin/src/format.ts           |   4 +-
 .../repository-plugin/src/index.ts            |  32 ++---
 .../repository-plugin/src/source.ts           |  55 +------
 .../tests/repository-plugin.spec.ts           |  18 +--
 vendor/README.md                              |   2 +-
 vendor/loader/src/repository.ts               |  19 +--
 26 files changed, 319 insertions(+), 243 deletions(-)
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
 delete mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
 rename .agents/notes/implemented/bug-fix/{2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml => 2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml} (54%)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 8ffa06ab1a..33e7540bbc 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.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 .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
-2026-07-30-static-repository-plugin-format.md: 615529c89d32ed87c73d100b632318500e1ae86c
-2026-07-30-static-repository-plugin-format.zh.md: bb90994defccdaf2044b467cb3c5018c1c94641a
+2026-07-30-static-repository-plugin-format.md: afc88bb974ccc6ef7843eaf1e98f16b65bb6d4b3
+2026-07-30-static-repository-plugin-format.zh.md: a6dc6ec6ec89c04b79edea279029ae33091ca0af
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
index 615529c89d..afc88bb974 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
@@ -14,7 +14,7 @@ The [package-manager-native repository cache](2026-07-30-package-manager-native-
 
 `@deepseek-ai/dsh-repository-plugin` owns the static contribution subformat inside a `.dsh-plugin` package: skill roots and one common `.mcp.json`. Its package metadata uses `package.json#dsh.skills` for relative skill-root paths and `package.json#dsh.mcpServers` for the relative MCP document path. Each path may leave `.dsh-plugin` to reuse repository content but must remain beneath the directory containing that `.dsh-plugin`; a nested selectable Plugin therefore owns the adjacent subtree above its package without gaining access to unrelated host paths. The package may additionally declare the explicit code entry owned by the [trusted repository package decision](2026-08-08-trusted-repository-package-code.md), and at least one code or static contribution is required.
 
-The `.dsh-plugin` package declares a non-empty `scripts.prepack` that invokes `dsh-plugin-prepare` without depending on a DSH npm package. During Git installation, the standalone runtime temporarily supplies that command from its own build on the isolated lifecycle `PATH`; `prepack` runs after dependency installation and before pnpm packs a selected subdirectory, including a Plugin nested inside another package-manager workspace. The package may build its code first. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`; the source loader revalidates the installed package's helper-bearing lifecycle metadata before importing that wrapper. A static-only package still receives an import-free wrapper containing its normalized manifest, service-derived `inject` list, and delegation to the `dsh-repository-plugin` Loader builtin. The host-owned command rationale is in the [Git source preparation repair](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
+The `.dsh-plugin` package declares the published `@deepseek-ai/dsh-repository-plugin` package as a development dependency and a non-empty `scripts.prepack` that invokes its `dsh-plugin-prepare` executable. During Git installation, pnpm installs that dependency from the selected package's own manifest; `prepack` runs after dependency installation and before pnpm packs a selected subdirectory, including a Plugin nested inside another package-manager workspace. The package may build its code first. The helper validates metadata and source types, strictly parses `.mcp.json`, copies static assets into `dsh-plugin-assets`, and writes `dsh-plugin.mjs`; the source loader revalidates the installed package's helper-bearing lifecycle metadata before importing that wrapper. A static-only package still receives an import-free wrapper containing its normalized manifest, service-derived `inject` list, and delegation to the `dsh-repository-plugin` Loader builtin. The dependency and workspace-isolation rationale is in the [Git source preparation repair](../bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md).
 
 Loading the DSH package registers that builtin as an effect. A generated wrapper mounts the builtin as its child with `import.meta.url`, so all contributions belong to the wrapper fiber and disappear on Loader removal or rollback. The builtin revalidates the prepared manifest and path containment before reading assets. It composes the existing implementations rather than registering skills or MCP tools itself.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index bb90994def..a6dc6ec6ec 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -14,7 +14,7 @@
 
 `@deepseek-ai/dsh-repository-plugin` 负责 `.dsh-plugin` 包内的静态贡献子格式：skill 根和一个通用 `.mcp.json`。其包元数据使用 `package.json#dsh.skills` 声明相对 skill 根路径，使用 `package.json#dsh.mcpServers` 声明相对 MCP 文档路径。每条路径都可以离开 `.dsh-plugin` 以复用仓库内容，但必须留在包含该 `.dsh-plugin` 的目录之下；因此，一个嵌套且可选择的插件可以拥有其包上方相邻的子树，却不能访问无关宿主路径。该包还可以声明由[受信任 repository 包决策](2026-08-08-trusted-repository-package-code.md)负责的显式代码入口，并且至少需要一种代码或静态贡献。
 
-`.dsh-plugin` 包声明非空 `scripts.prepack`，调用 `dsh-plugin-prepare` 且不依赖 DSH NPM 包。在 Git 安装期间，独立运行时会从自身构建产物中临时提供该命令，并将其放入隔离的生命周期 `PATH`；`prepack` 会在依赖安装后、pnpm 打包选定子目录前运行，即使插件嵌套在另一个包管理器工作区内也不例外。包可以先构建其代码。该辅助程序会校验元数据与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`；源码 loader 会在导入该包装层前重新校验已安装包的生命周期元数据是否包含辅助命令。仅含静态贡献的包仍会获得无 import 包装层，其中包含规范化 manifest（元数据清单）、由服务派生的 `inject` 列表，以及对 `dsh-repository-plugin` Loader builtin 的委托。宿主自有命令的设计依据见[Git 源准备修复](../bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
+`.dsh-plugin` 包将已发布的 `@deepseek-ai/dsh-repository-plugin` 包声明为开发依赖，并声明非空 `scripts.prepack` 来调用其 `dsh-plugin-prepare` 可执行文件。在 Git 安装期间，pnpm 会按所选包自身的 manifest（元数据清单）安装该依赖；`prepack` 会在依赖安装后、pnpm 打包选定子目录前运行，即使插件嵌套在另一个包管理器工作区内也不例外。包可以先构建其代码。该辅助程序会校验元数据与源码类型，严格解析 `.mcp.json`，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`；源码 loader 会在导入该包装层前重新校验已安装包的生命周期元数据是否包含辅助命令。仅含静态贡献的包仍会获得无 import 包装层，其中包含规范化 manifest、由服务派生的 `inject` 列表，以及对 `dsh-repository-plugin` Loader builtin 的委托。依赖与 workspace 隔离的设计依据见[Git 源准备修复](../bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md)。
 
 加载 DSH package 会以 effect 方式注册该 builtin。生成的包装模块使用 `import.meta.url` 把 builtin 挂载为自己的子级，因此所有贡献都归属于包装 fiber，并在 Loader 移除或回滚时消失。Builtin 会在读取资源前重新校验已准备 manifest 与路径包含关系。它只组合现有实现，而不自行注册 skills 或 MCP 工具。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
index 74c4f0eb41..16b72afb4e 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.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 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
-2026-08-08-trusted-repository-package-code.md: cf72853836901af9c1c9e9f0d3d23f43997a4e97
-2026-08-08-trusted-repository-package-code.zh.md: cea47d85973a81f904b1596051ac58996459c635
+2026-08-08-trusted-repository-package-code.md: 6c568964c2d4392054107acb1e73ace8f50d5f0b
+2026-08-08-trusted-repository-package-code.zh.md: c2587286379398ab853b71c8b8819d274d06c65b
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
index cf72853836..6c568964c2 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
@@ -14,7 +14,7 @@ A repository author also needs to keep an ordinary TypeScript npm package shape.
 
 A configured repository package is trusted code. Its `.dsh-plugin/package.json` may declare `dsh.entry` as a relative path to a compiled ESM Cordis Plugin inside that package, alongside or instead of `dsh.skills` and `dsh.mcpServers`. At least one contribution is required. The entry may use namespace exports or a default export and retains ordinary Cordis semantics for `name`, `inject`, `Config`, registrations, startup failure, and effect-scoped teardown.
 
-The package owns its npm dependencies and build toolchain. `scripts.prepack` is a non-empty package-authored command that must invoke the host-supplied `dsh-plugin-prepare`, but it may first run `tsc`, `tsdown`, or any other build. DSH neither parses the shell program nor compiles repository source. The helper validates the metadata after the preceding build, requires the configured entry to resolve to a file within `.dsh-plugin`, validates and copies declared static assets, and writes the prepared `dsh-plugin.mjs` wrapper. The installed package must retain a `prepack` declaration containing that helper command; missing wrapper or build outputs fail before a cache generation becomes usable.
+The package owns its npm dependencies and build toolchain. It declares the published `@deepseek-ai/dsh-repository-plugin` package to obtain the `dsh-plugin-prepare` executable. `scripts.prepack` is a non-empty package-authored command that must invoke that dependency-provided helper, but it may first run `tsc`, `tsdown`, or any other build. DSH neither injects the helper, parses the shell program, nor compiles repository source. The helper validates the metadata after the preceding build, requires the configured entry to resolve to a file within `.dsh-plugin`, validates and copies declared static assets, and writes the prepared `dsh-plugin.mjs` wrapper. The installed package must retain a `prepack` declaration containing that helper command; a missing dependency, wrapper, or build output fails before a cache generation becomes usable.
 
 The generated wrapper first mounts the DSH-owned static runtime for skills and MCP definitions, then dynamically imports and unwraps the explicit entry and mounts it as a child. Both children must reach Cordis `ACTIVE`; an unsatisfied `inject` or startup exception rejects the repository Loader transaction instead of committing an inert generation. Loader removal, failed replacement, and parent disposal unwind the entry, skill providers, MCP clients, and their effects together.
 
@@ -48,4 +48,4 @@ Model-visible behavior remains governed by the owning DSH seam. A repository ent
 
 Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication, preserve opt-in contained connect failure, and prove strict startup rejection still closes the client.
 
-The Node 24 consumer acceptance uses the actual built `dsh run` command with a fresh DSH home and an authenticated private GitHub source pinned to the pull request's exact head SHA. That repository package installs pinned runtime and development dependencies, type-checks and bundles TypeScript during `prepack`, prepares a skill plus a stdio MCP server and `dsh.entry`, exposes the skill and MCP schema in the first real model request, executes the MCP tool, and lets the compiled Cordis entry append a second marker to the result observed in the following request. Cache assertions require source files to be absent from the packed installation while both built modules, their installed dependency, copied assets, and generated wrapper are present.
+The Node 24 consumer acceptance uses the actual built `dsh run` command with a fresh DSH home and an authenticated private GitHub source pinned to the pull request's exact head SHA. The test packs the current repository Plugin build with the same private-field removal and workspace-dependency pinning used for publication, serves its packument and tarball from a job-local npm registry, and directs the Git package's ordinary scoped npm resolution there. That repository package obtains `dsh-plugin-prepare` from the simulated published dependency, installs its other pinned runtime and development dependencies, type-checks and bundles TypeScript during `prepack`, prepares a skill plus a stdio MCP server and `dsh.entry`, exposes the skill and MCP schema in the first real model request, executes the MCP tool, and lets the compiled Cordis entry append a second marker to the result observed in the following request. Registry and cache assertions require npm resolution to reach the simulated publication, source files to be absent from the packed installation, and both built modules, their installed dependency, copied assets, and generated wrapper to be present.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
index cea47d8597..c258728637 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
@@ -14,7 +14,7 @@
 
 已配置的 repository 包是受信任代码。其 `.dsh-plugin/package.json` 可以连同 `dsh.skills` 和 `dsh.mcpServers` 声明 `dsh.entry`，也可以用它取代二者；`dsh.entry` 是指向该包内已编译 ESM Cordis 插件的相对路径。至少需要一种贡献。入口可以使用 namespace 导出或 default export，并沿用 Cordis 对 `name`、`inject`、`Config`、注册、启动失败和 effect 作用域清理的常规语义。
 
-包自行负责其 NPM 依赖和构建工具链。`scripts.prepack` 是由包作者编写的非空命令，必须调用宿主提供的 `dsh-plugin-prepare`，但可以先运行 `tsc`、`tsdown` 或其他任意构建。DSH 既不解析该 shell 程序，也不编译 repository 源码。辅助程序会在前序构建之后校验元数据，要求已配置入口解析到 `.dsh-plugin` 内的文件，校验并复制已声明的静态资源，再写入已准备的 `dsh-plugin.mjs` 包装层。已安装包必须保留包含该辅助命令的 `prepack` 声明；包装层或构建输出缺失会在缓存 generation 可用前导致失败。
+包自行负责其 NPM 依赖和构建工具链。它声明已发布的 `@deepseek-ai/dsh-repository-plugin` 包以取得 `dsh-plugin-prepare` 可执行文件。`scripts.prepack` 是由包作者编写的非空命令，必须调用该依赖提供的辅助程序，但可以先运行 `tsc`、`tsdown` 或其他任意构建。DSH 不会注入辅助程序，也不会解析该 shell 程序或编译 repository 源码。辅助程序会在前序构建之后校验元数据，要求已配置入口解析到 `.dsh-plugin` 内的文件，校验并复制已声明的静态资源，再写入已准备的 `dsh-plugin.mjs` 包装层。已安装包必须保留包含该辅助命令的 `prepack` 声明；依赖、包装层或构建输出缺失会在缓存 generation 可用前导致失败。
 
 生成的包装层先挂载 DSH 自有的静态运行时来处理 skill 和 MCP 定义，再动态导入显式入口、解包其导出并将其挂载为子级。两个子级都必须进入 Cordis `ACTIVE`；无法满足的 `inject` 或启动异常会拒绝 repository Loader 事务，而不会提交未激活的 generation。Loader 移除、替换失败和父级 dispose（资源释放）会一并撤销入口、skill 提供方、MCP client 及其 effect。
 
@@ -48,4 +48,4 @@
 
 repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，保留选择收束连接失败的能力，并证明严格启动拒绝仍会关闭 client。
 
-Node 24 消费方验收使用实际构建的 `dsh run` 命令、全新 DSH 主目录，以及锁定到 PR（Pull Request）的精确 head SHA 且经过认证的私有 GitHub 源。该 repository 包安装固定版本的运行时依赖与开发依赖，在 `prepack` 期间对 TypeScript 进行类型检查和打包，准备一个 skill、一个 stdio MCP server 及 `dsh.entry`，在首个真实模型请求中暴露 skill 与 MCP schema，执行 MCP 工具，并让已编译 Cordis 入口向结果追加第二个标记，供后续请求观察。缓存断言要求打包安装中不存在源码文件，同时必须存在两个已构建模块、其已安装依赖、复制资源和生成包装层。
+Node 24 消费方验收使用实际构建的 `dsh run` 命令、全新 DSH 主目录，以及锁定到 PR（Pull Request）的精确 head SHA 且经过认证的私有 GitHub 源。测试会采用发布时相同的移除 `private` 字段和固定 workspace 依赖版本流程，对当前 repository 插件构建进行打包；再由作业本地 NPM 注册表提供其 `packument` 与 tarball，并把 Git 包的常规 scoped NPM 解析指向该注册表。该 repository 包从模拟发布的依赖取得 `dsh-plugin-prepare`，安装其他固定版本的运行时依赖与开发依赖，在 `prepack` 期间对 TypeScript 进行类型检查和打包，准备一个 skill、一个 stdio MCP server 及 `dsh.entry`，在首个真实模型请求中暴露 skill 与 MCP schema，执行 MCP 工具，并让已编译 Cordis 入口向结果追加第二个标记，供后续请求观察。注册表与缓存断言要求 NPM 解析必须命中模拟发布，打包安装中不存在源码文件，同时必须存在两个已构建模块、其已安装依赖、复制资源和生成包装层。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
deleted file mode 100644
index 3f92c0b2d7..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Agent Note: Host-owned preparation makes GitHub repository Plugins installable
-
-Status: implemented
-
-English | [中文](2026-08-08-host-owned-git-repository-plugin-preparation.zh.md)
-
-## Problem
-
-The repository Plugin authoring contract depended on `scripts.prepare: "dsh-plugin-prepare"` and told source repositories to add `@deepseek-ai/dsh-repository-plugin` as a development dependency. That package is private and not published to npm, so an otherwise valid external GitHub repository could not obtain the helper in a clean install.
-
-The lifecycle choice also failed for a selectable `.dsh-plugin` inside a pnpm workspace. pnpm prepares a Git-hosted package by running the repository's preferred package manager before packing the selected subdirectory. A nested `pnpm install` joins the containing workspace and need not execute the unlisted `.dsh-plugin` package's `prepare` script. The install could therefore succeed and publish a cache generation containing only the source package metadata; real DSH startup failed later because `dsh-plugin.mjs` did not exist.
-
-The same workspace discovery could suppress package-owned dependencies after the move to `prepack`. When the source repository carried a root pnpm lockfile but did not list the selected `.dsh-plugin` as a workspace importer, pnpm reported a successful workspace install without installing dependencies declared only by that package. Its TypeScript build then failed because Cordis and the MCP SDK were absent.
-
-The checked-in headless fixture did not catch either defect because it mounted an already prepared wrapper. It proved runtime composition, not GitHub acquisition or package preparation.
-
-## Decision
-
-The authoring format requires a non-empty `scripts.prepack` that invokes `dsh-plugin-prepare` and needs no DSH dependency for that helper. The package may declare its own build and runtime dependencies and run compilation before the helper. pnpm's Git-hosted package preparation invokes `prepack` explicitly after its dependency-install step and before packlist selects the `.dsh-plugin` subtree, so the helper can validate built entries and still copy sibling repository assets such as `../skills` into the package.
-
-`@deepseek-ai/dsh-repository-plugin` materializes short-lived POSIX and Windows command wrappers that invoke its own built `dsh-plugin-prepare` entry. `RepositoryCache` accepts caller-owned executable directories, resolves them absolutely, and prepends them to the credential-scrubbed lifecycle `PATH` passed to bundled pnpm. It also prepends a transaction-owned `pnpm` wrapper: the outer install still runs the pinned pnpm entry directly, while pnpm's hard-coded Git-package `pnpm install` reinvokes that same entry with `--ignore-workspace`. The selected package therefore owns dependency resolution even beneath another pnpm lockfile. Both command directories are removed after the child settles. The repository remains trusted package-manager input: DSH supplies the two host commands, but all package lifecycle scripts and dependencies still execute under the existing trust contract.
-
-The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. Because that repository is private, the workflow writes a job-scoped Git configuration that uses the read-only job token for GitHub HTTPS and rewrites pnpm's SSH fallback to that authenticated transport. Its built-entry acceptance launches the real `apps/cli/lib/bin.js run` command with a one-run patch selecting a `private: true` GitHub fixture. That fixture installs pinned npm dependencies, type-checks and bundles a TypeScript Cordis entry and MCP server in `prepack`, invokes the host helper, and proves the skill, MCP call, and code entry through real model requests and immutable-cache artifacts. The test fails if CI omits the exact source instead of silently skipping.
-
-## Alternatives considered
-
-**Publish the prepare helper to npm.** Rejected because the source package would acquire a release/version dependency solely to call code already owned by the running DSH installation, and the existing helper is intentionally private.
-
-**Keep `prepare` and only inject the command.** Rejected because command availability does not make a nested package's `prepare` lifecycle run when the Git repository's package manager treats it as part of another workspace.
-
-**Prepare after RepositoryCache installs the selected package.** Rejected because pnpm's packed subdirectory no longer contains sibling source assets referenced by paths such as `../skills`; preparation must happen before packlist.
-
-**Clone GitHub repositories in DSH and bypass pnpm's Git fetcher.** Rejected because it would duplicate ref resolution, subdirectory selection, dependency installation, packlist behavior, and cache integrity already owned by the pinned package manager.
-
-**Add the in-repository CI fixture to this repository's pnpm workspace.** Rejected because that would repair only the proof fixture and leave an arbitrary selected package vulnerable to its containing repository's workspace membership and lockfile.
-
-## Consequences
-
-- A repository author can commit the fixed `.dsh-plugin/package.json` and source assets to GitHub without publishing either the Plugin or its preparation helper to npm.
-- Private GitHub sources use the host's standard Git authentication. CI proves that path with a temporary read-only configuration rather than persistent runner credentials.
-- `prepack`, not `prepare`, is part of the pre-release authoring format. It may contain package-owned build steps but must invoke the host helper; missing or empty lifecycle metadata fails installed-package validation instead of producing an ambiguous partial format.
-- A selected package in a pnpm repository installs from its own manifest rather than an enclosing workspace. It must declare its dependencies and cannot rely on workspace-only hoisting; ordinary registry and relative `file:` dependencies remain package-owned inputs.
-- Exact source strings still identify immutable cache generations; a changed ref or source configuration selects another generation.
-- The host supplies only the preparation executable. Package dependencies, compilation, and the trusted `dsh.entry` contribution remain owned by the repository package and the [trusted-code decision](../architecture/2026-08-08-trusted-repository-package-code.md).
-
-## Testing
-
-`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a package excluded from its source repository's root pnpm lockfile through a local Git subpath and requires a relative `file:` build dependency during `prepack`; it also proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and temporary command cleanup. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
deleted file mode 100644
index ef34c99b5d..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.zh.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Agent Note: 宿主自有的准备机制使 GitHub repository 插件可安装
-
-状态：已实现
-
-[English](2026-08-08-host-owned-git-repository-plugin-preparation.md) | 中文
-
-## 问题
-
-repository 插件的创作契约依赖 `scripts.prepare: "dsh-plugin-prepare"`，并要求源码仓库将 `@deepseek-ai/dsh-repository-plugin` 添加为开发依赖。该包是私有包，且未发布到 NPM，因此即使外部 GitHub 仓库符合其他要求，也无法在全新安装中取得该辅助程序。
-
-这种生命周期选择也无法支持 pnpm 工作区内可选的 `.dsh-plugin`。pnpm 会先运行 Git 托管仓库首选的包管理器，再打包选定的子目录，从而准备 Git 托管包。嵌套执行的 `pnpm install` 会加入外层工作区，而不一定执行未列入其中的 `.dsh-plugin` 包的 `prepare` 脚本。因此，安装可能成功并发布一个仅包含源包元数据的缓存 generation；随后真实 DSH 启动因 `dsh-plugin.mjs` 不存在而失败。
-
-迁移到 `prepack` 后，同一项 workspace 发现行为还可能抑制包自有依赖。如果源仓库带有根 pnpm lockfile，却未把所选 `.dsh-plugin` 列为 workspace importer，pnpm 会报告 workspace 安装成功，但不会安装仅由该包声明的依赖。随后其 TypeScript 构建会因缺少 Cordis 和 MCP SDK 而失败。
-
-签入仓库的 headless fixture（测试前置数据）没有捕获任一缺陷，因为它挂载的是已准备好的包装层。它证明的是运行时组合，而不是 GitHub 获取或包准备。
-
-## 决策
-
-创作格式要求 `scripts.prepack` 非空且调用 `dsh-plugin-prepare`，使用该辅助程序无需 DSH 依赖。包可以声明自己的构建依赖与运行时依赖，并在调用辅助程序前完成编译。pnpm 针对 Git 托管包的准备流程会在依赖安装步骤之后、打包清单选择 `.dsh-plugin` 子树之前显式调用 `prepack`，因此辅助程序可以校验构建入口，并继续把 `../skills` 等同仓库的相邻资源复制进包内。
-
-`@deepseek-ai/dsh-repository-plugin` 会生成临时的 POSIX 和 Windows 命令包装脚本，用于调用其自有的已构建 `dsh-plugin-prepare` 入口。`RepositoryCache` 接受由调用方持有的可执行文件目录，将它们解析为绝对路径，再前置到传给随附 pnpm、已清除凭据的包生命周期 `PATH`。它还会前置一个由安装事务持有的 `pnpm` 包装命令：外层安装仍直接运行锁定的 pnpm 入口，而 pnpm 为 Git 包硬编码的 `pnpm install` 会通过 `--ignore-workspace` 重新调用同一入口。因此，即使位于另一个 pnpm lockfile 之下，所选包仍自行拥有依赖解析。两个命令目录都会在子进程结算后移除。仓库仍是受信任的包管理器输入：DSH 提供这两条宿主命令，但所有包生命周期脚本和依赖仍按既有信任契约执行。
-
-Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库和 SHA 派生的精确源。由于该仓库为私有仓库，工作流会写入一份作业作用域的 Git 配置，使用该作业的只读 token 对 GitHub HTTPS 连接进行认证，并将 pnpm 的 SSH 回退路径重写为这一已认证的传输方式。其构建入口验收会启动真实的 `apps/cli/lib/bin.js run` 命令，并通过一个仅作用于当次运行的 patch 选择 `private: true` 的 GitHub fixture。该 fixture 安装固定版本的 NPM 依赖，在 `prepack` 中对 TypeScript Cordis 入口和 MCP server 进行类型检查与打包，调用宿主辅助程序，并通过真实模型请求和不可变缓存产物验证 skill（技能）、MCP 调用和代码入口。如果 CI 遗漏精确源，测试会失败，而不是静默跳过。
-
-## 考虑过的替代方案
-
-**把准备辅助程序发布到 NPM。** 拒绝，因为源包会仅为了调用当前运行的 DSH 安装本就拥有的代码，而增加一个需要发布和管理版本的依赖；现有辅助程序又有意保持私有。
-
-**保留 `prepare`，只注入命令。** 拒绝，因为当 Git 仓库的包管理器把嵌套包当作另一工作区的一部分时，即使命令可用，也不会使嵌套包的 `prepare` 生命周期得以运行。
-
-**在 RepositoryCache 安装选定包后再准备。** 拒绝，因为 pnpm 打包后的子目录不再包含 `../skills` 等路径所引用的同仓库相邻资源；准备必须在生成打包清单前完成。
-
-**在 DSH 中克隆 GitHub 仓库，并绕过 pnpm 的 Git 获取器。** 拒绝，因为这会重复实现已由锁定版本的包管理器负责的 ref 解析、子目录选择、依赖安装、打包清单行为和缓存完整性。
-
-**把仓库内的 CI fixture 加入本仓库的 pnpm workspace。** 拒绝，因为这只能修复证明用的 fixture，任意所选包仍会受其所在仓库的 workspace membership 与 lockfile 影响。
-
-## 后果
-
-- 仓库作者可以把修复后的 `.dsh-plugin/package.json` 和源资源提交到 GitHub，而无需把插件或其准备辅助程序发布到 NPM。
-- 私有 GitHub 源使用宿主的标准 Git 认证。CI 使用临时的只读配置而非运行器上的持久凭据来验证该路径。
-- 预发布创作格式使用 `prepack` 而不是 `prepare`。其中可以包含包自有构建步骤，但必须调用宿主辅助程序；生命周期元数据缺失或为空会在已安装包校验时失败，而不会留下状态不明的半成品格式。
-- pnpm 仓库中的所选包按自身 manifest 安装，而不是按外层 workspace 安装。它必须声明自己的依赖，不能依赖仅由 workspace 提升而可见的包；常规 registry 依赖与相对 `file:` 依赖仍是包自有输入。
-- 精确源字符串仍标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
-- 宿主只提供准备阶段可执行文件。包依赖、编译和受信任的 `dsh.entry` 贡献仍由 repository 包和[受信任代码决策](../architecture/2026-08-08-trusted-repository-package-code.md)负责。
-
-## 测试
-
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 会让一个被源仓库根 pnpm lockfile 排除的包通过本地 Git 子路径运行，并要求 `prepack` 使用相对 `file:` 构建依赖；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据和临时命令清理行为。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：全新的 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建产物的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及对已准备缓存的检查。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
similarity index 54%
rename from .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
rename to .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
index 189c3dc5c2..e1966105a3 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.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 .agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md
-2026-08-08-host-owned-git-repository-plugin-preparation.md: 3f92c0b2d782735bfb548711bb13a7a8d03a3824
-2026-08-08-host-owned-git-repository-plugin-preparation.zh.md: ef34c99b5d9f31ea13c5fddfee77c30e640d25c9
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
+2026-08-08-npm-backed-git-repository-plugin-preparation.md: 9437043d007f5331f36f1c4cff1fe0a3e768b060
+2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md: 1f06f7372dc0d948906ec4441cb161d2d2ed69e5
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
new file mode 100644
index 0000000000..9437043d00
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
@@ -0,0 +1,48 @@
+# Agent Note: npm-backed preparation makes GitHub repository Plugins self-contained
+
+Status: implemented
+
+English | [中文](2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md)
+
+## Problem
+
+The repository Plugin authoring contract requires `scripts.prepack` to invoke `dsh-plugin-prepare`. Supplying that executable from the running DSH installation made a source package appear valid even when its own manifest could not obtain the helper. It therefore did not prove the behavior users need after `@deepseek-ai/dsh-repository-plugin` is published: an ordinary Git-hosted npm package must be installable and preparable from only its declared dependencies.
+
+A selectable `.dsh-plugin` inside a pnpm workspace has a second isolation requirement. pnpm prepares a Git-hosted package by running the repository's preferred package manager before packing the selected subdirectory. A nested `pnpm install` can join the containing workspace; when the root lockfile does not list `.dsh-plugin` as an importer, pnpm can report success without installing dependencies declared only by that package. Its TypeScript build or prepare command then fails, or a pre-generated artifact hides the missing dependency.
+
+The checked-in headless fixture mounts an already prepared wrapper. It proves runtime composition, not GitHub acquisition, npm resolution, or package-owned preparation.
+
+## Decision
+
+The `.dsh-plugin` package declares `@deepseek-ai/dsh-repository-plugin` as an ordinary development dependency and invokes its published `dsh-plugin-prepare` executable from `scripts.prepack`. The package may declare any other build and runtime dependencies and run arbitrary compilation before the helper. The repository Plugin package marks its Cordis and DSH peers optional so a helper-only development install resolves only the helper's actual `zod` runtime dependency; an application composition still supplies the peers used by the package's Cordis entry.
+
+DSH does not materialize or prepend a prepare executable. `RepositoryCache` supplies only a transaction-owned `pnpm` wrapper: the outer install runs the pinned pnpm entry directly, while pnpm's hard-coded Git-package `pnpm install` reinvokes the same entry with `--ignore-workspace`. The selected package therefore owns dependency resolution even beneath another pnpm lockfile, and normal package-manager lifecycle `PATH` construction exposes `node_modules/.bin/dsh-plugin-prepare`. The temporary pnpm wrapper disappears after the child settles. The repository remains trusted package-manager input: all dependency and lifecycle code executes under the existing trust contract.
+
+The Node 24 consumer lane passes an exact source derived from the pull request head repository and SHA. It uses the existing private DeepSeek Harness repository rather than creating another repository per run. A job-scoped Git configuration gives the read-only job token access to that exact private source and rewrites pnpm's SSH fallback to authenticated HTTPS.
+
+The built-entry acceptance also creates an in-process npm registry. It stages the current built `@deepseek-ai/dsh-repository-plugin` as a publication artifact by removing `private`, replacing workspace protocols with the release version, and packing the declared files. The registry serves the resulting packument and tarball, while a job-local npm config directs only the `@deepseek-ai` scope to it. The real built `dsh run` child then fetches the exact Git source; that package resolves the helper through npm, type-checks and bundles a TypeScript Cordis entry and MCP server, prepares the adjacent skill, and loads all three contributions. A deliberately failing host `PATH` command proves the lifecycle selected the dependency-local executable. The acceptance also requires registry resolution and inspects the immutable prepared cache, so restoring a host-injected helper cannot satisfy it.
+
+## Alternatives considered
+
+**Inject `dsh-plugin-prepare` from the running DSH installation.** Rejected because it lets an incomplete repository manifest pass and tests a host-only path that npm consumers cannot reproduce.
+
+**Publish the source fixture itself to npm.** Rejected because the product contract is specifically that the DSH Plugin remains Git-hosted; only the reusable preparation helper is an npm dependency.
+
+**Create a new private GitHub repository in every CI run.** Rejected because the pull request repository at its exact head SHA is already a real authenticated private Git remote. Per-run repository mutation would add credentials, cleanup, and eventual-consistency failure modes without changing the acquisition path.
+
+**Prepare after `RepositoryCache` installs the selected package.** Rejected because pnpm's packed subdirectory no longer contains sibling source assets referenced by paths such as `../skills`; preparation must happen before packlist.
+
+**Clone GitHub repositories in DSH and bypass pnpm's Git fetcher.** Rejected because it would duplicate ref resolution, subdirectory selection, dependency installation, packlist behavior, and cache integrity already owned by the pinned package manager.
+
+## Consequences
+
+- A repository author can commit a `.dsh-plugin` package, TypeScript source, skills, and MCP definitions to GitHub without publishing that Plugin package to npm. The package must declare the published preparation dependency.
+- Private GitHub sources use the host's standard Git authentication. CI proves that path with a temporary read-only configuration rather than persistent runner credentials.
+- `prepack`, not `prepare`, is part of the authoring format. It may contain arbitrary package-owned build steps but must invoke the dependency-provided helper; missing dependency or lifecycle metadata fails before a cache generation is usable.
+- A selected package in a pnpm repository installs from its own manifest rather than an enclosing workspace. It cannot rely on workspace-only hoisting; ordinary registry and relative `file:` dependencies remain package-owned inputs.
+- Exact source strings identify immutable cache generations; a changed ref or source configuration selects another generation.
+- Package dependencies, compilation, preparation, and the trusted `dsh.entry` contribution remain owned by the repository package and the [trusted-code decision](../architecture/2026-08-08-trusted-repository-package-code.md).
+
+## Testing
+
+`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a package excluded from its source repository's root pnpm lockfile through a local Git subpath and requires relative `file:` dependencies to provide both its build command and `dsh-plugin-prepare`; it also proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and preparation output. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: simulated published helper package, job-local npm registry, fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
new file mode 100644
index 0000000000..1f06f7372d
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
@@ -0,0 +1,48 @@
+# Agent Note: 基于 NPM 的准备机制使 GitHub repository 插件自包含
+
+状态：已实现
+
+[English](2026-08-08-npm-backed-git-repository-plugin-preparation.md) | 中文
+
+## 问题
+
+repository 插件创作契约要求 `scripts.prepack` 调用 `dsh-plugin-prepare`。如果由正在运行的 DSH 安装提供该可执行文件，即使源包自身的 manifest（元数据清单）无法取得辅助程序，它也会显得有效。因此，这并未证明 `@deepseek-ai/dsh-repository-plugin` 发布后用户所需的行为：普通 Git 托管 NPM 包必须只依靠自身声明的依赖即可安装和准备。
+
+pnpm workspace 内可选择的 `.dsh-plugin` 还有另一项隔离要求。pnpm 会在打包所选子目录前运行仓库首选的包管理器，以准备 Git 托管包。嵌套的 `pnpm install` 可能加入外层 workspace；当根 lockfile 未把 `.dsh-plugin` 列为 importer 时，pnpm 可能报告成功，却未安装仅由该包声明的依赖。随后，其 TypeScript 构建或准备命令会失败；也可能因为存在预生成产物，依赖缺失被掩盖。
+
+签入仓库的 headless fixture（测试前置数据）挂载的是已准备好的包装层。它证明运行时组合，而不证明 GitHub 获取、NPM 解析或包自有准备。
+
+## 决策
+
+`.dsh-plugin` 包将已发布的 `@deepseek-ai/dsh-repository-plugin` 声明为普通开发依赖，并在 `scripts.prepack` 中调用其已发布的 `dsh-plugin-prepare` 可执行文件。该包可以声明其他任意构建依赖与运行时依赖，并在辅助程序前执行任意编译。repository 插件包把 Cordis 与 DSH 对等依赖（peer dependency）标为可选，因此仅为使用辅助程序而进行的开发安装只会解析辅助程序实际依赖的 `zod` 运行时依赖；应用组合仍会提供该包 Cordis 入口所使用的对等依赖。
+
+DSH 不会生成准备阶段可执行文件，也不会将其前置到 `PATH`。`RepositoryCache` 只提供一个由事务持有的 `pnpm` 包装脚本：外层安装直接运行锁定的 pnpm 入口，而 pnpm 为 Git 包硬编码的 `pnpm install` 会以 `--ignore-workspace` 重新调用同一入口。因此，即使位于另一个 pnpm lockfile 之下，所选包仍自行负责依赖解析，正常的包管理器生命周期 `PATH` 构造会暴露 `node_modules/.bin/dsh-plugin-prepare`。临时 pnpm 包装脚本会在子进程结算后消失。repository 仍是受信任的包管理器输入：所有依赖与生命周期代码都按既有信任契约执行。
+
+Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库与 SHA 派生的精确源。它复用现有私有 DeepSeek Harness 仓库，而不会为每次运行新建仓库。作业作用域的 Git 配置允许只读作业 token 访问该精确私有源，并把 pnpm 的 SSH 回退改写为已认证 HTTPS。
+
+构建入口验收还会创建一个进程内 NPM 注册表。它通过移除 `private`、将 workspace protocol 替换为发布版本并打包声明的文件，把当前已构建的 `@deepseek-ai/dsh-repository-plugin` 暂存为发布产物。注册表会提供由此生成的 `packument` 与 tarball，作业本地 NPM 配置则只把 `@deepseek-ai` scope 指向它。实际构建的 `dsh run` 子进程随后获取精确 Git 源；该包通过 NPM 解析辅助程序，对 TypeScript Cordis 入口和 MCP server 进行类型检查与打包，准备相邻的 skill（技能），并加载全部三类贡献。一个刻意设为失败的宿主 `PATH` 命令可以证明，该生命周期选中的是依赖内的可执行文件。验收还要求经过注册表解析并检查不可变的已准备缓存，因此恢复宿主注入的辅助程序也无法通过。
+
+## 考虑过的替代方案
+
+**从正在运行的 DSH 安装注入 `dsh-plugin-prepare`。** 拒绝，因为这会让 manifest 不完整的 repository 包通过，并测试 NPM 消费方无法复现的纯宿主路径。
+
+**把源 fixture 本身发布到 NPM。** 拒绝，因为产品契约明确要求 DSH 插件仍托管在 Git；只有可复用的准备辅助程序是 NPM 依赖。
+
+**在每次 CI 运行中创建新的私有 GitHub 仓库。** 拒绝，因为 PR 仓库的精确 head SHA 已是经过认证的真实私有 Git remote。每次运行的仓库变更会增加凭据、清理和最终一致性失败模式，却不改变获取路径。
+
+**在 `RepositoryCache` 安装所选包后再准备。** 拒绝，因为 pnpm 打包后的子目录不再包含 `../skills` 等路径所引用的同仓库相邻资源；准备必须在生成 packlist 前完成。
+
+**在 DSH 中克隆 GitHub 仓库并绕过 pnpm 的 Git 获取器。** 拒绝，因为这会重复实现已由锁定包管理器负责的 ref 解析、子目录选择、依赖安装、packlist 行为和缓存完整性。
+
+## 后果
+
+- 仓库作者可以把 `.dsh-plugin` 包、TypeScript 源码、skill 与 MCP 定义提交到 GitHub，而无需把该插件包发布到 NPM。该包必须声明已发布的准备依赖。
+- 私有 GitHub 源使用宿主的标准 Git 认证。CI 使用临时的只读配置而非运行器上的持久凭据来验证该路径。
+- 创作格式使用 `prepack` 而不是 `prepare`。其中可以包含任意包自有构建步骤，但必须调用依赖提供的辅助程序；依赖或生命周期元数据缺失时，会在缓存 generation 可用前失败。
+- pnpm 仓库中的所选包按自身 manifest 安装，而不继承外层 workspace。它不能依赖仅由 workspace 提升而可见的包；普通注册表依赖和相对 `file:` 依赖仍是包自有输入。
+- 精确源字符串标识不可变缓存 generation；改变 ref 或源配置会选择另一个 generation。
+- 包依赖、编译、准备和受信任的 `dsh.entry` 贡献仍由 repository 包和[受信任代码决策](../architecture/2026-08-08-trusted-repository-package-code.md)负责。
+
+## 测试
+
+`packages/ui/app-boot/tests/repository-cache.spec.ts` 会通过本地 Git 子路径运行一个未列入源仓库根 pnpm lockfile 的包，并要求相对 `file:` 依赖同时提供构建命令与 `dsh-plugin-prepare`；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据与准备输出。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：模拟发布的辅助程序包、作业本地 NPM 注册表、全新 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及已准备缓存检查。
diff --git a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
index b11ea67c41..6871a4d053 100644
--- a/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
+++ b/apps/cli/tests/fixtures/github-repository-plugin/.dsh-plugin/package.json
@@ -22,6 +22,7 @@
     "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-repository-plugin": "0.0.1",
     "cordis": "4.0.0-rc.7",
     "tsdown": "0.22.2",
     "typescript": "6.0.3"
diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index fb0bf2937a..e1386e2bfe 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -1,7 +1,9 @@
-import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, globSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { createServer } from 'node:http'
 import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { delimiter, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { startMockLlmServer } from '@deepseek-ai/dsh-llm-mock-server'
 import { execa } from 'execa'
@@ -9,12 +11,121 @@ import { describe, expect, it } from 'vitest'
 
 const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
 const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')
+const repositoryPluginPackage = join(repoRoot, 'packages/cordis/repository-plugin')
+const releasePackageNames = new Set(globSync([
+  'vendor/*/package.json',
+  'packages/*/*/package.json',
+  'apps/*/package.json',
+], { cwd: repoRoot }).map((filename) => {
+  const manifest = JSON.parse(readFileSync(join(repoRoot, filename), 'utf8')) as Record<string, unknown>
+  if (typeof manifest.name !== 'string') throw new Error(`workspace package name is missing: ${filename}`)
+  return manifest.name
+}))
 const source = process.env.DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE
 const required = process.env.DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E === '1'
 const enabled = required || source !== undefined
 
+interface PublishedPackageRegistry {
+  url: string
+  requests: string[]
+  close(): Promise<void>
+}
+
+function publishedManifest(): Record<string, unknown> {
+  const manifest = JSON.parse(readFileSync(join(repositoryPluginPackage, 'package.json'), 'utf8')) as Record<string, unknown>
+  const version = manifest.version
+  if (typeof version !== 'string') throw new Error('repository Plugin package version is missing')
+  Reflect.deleteProperty(manifest, 'private')
+  for (const field of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+    const dependencies = manifest[field]
+    if (typeof dependencies !== 'object' || dependencies === null || Array.isArray(dependencies)) continue
+    const entries = dependencies as Record<string, unknown>
+    for (const name of Object.keys(entries)) {
+      if (releasePackageNames.has(name)) {
+        entries[name] = version
+      }
+    }
+  }
+  return manifest
+}
+
+async function startPublishedPackageRegistry(root: string): Promise<PublishedPackageRegistry> {
+  const staging = join(root, 'published-repository-plugin')
+  const artifacts = join(root, 'npm-registry-artifacts')
+  mkdirSync(staging)
+  mkdirSync(artifacts)
+  cpSync(join(repositoryPluginPackage, 'lib'), join(staging, 'lib'), { recursive: true })
+  for (const filename of ['README.md', 'README.zh.md', 'README.i18n.yaml']) {
+    cpSync(join(repositoryPluginPackage, filename), join(staging, filename))
+  }
+  cpSync(join(repoRoot, 'LICENSE'), join(staging, 'LICENSE'))
+  const manifest = publishedManifest()
+  writeFileSync(join(staging, 'package.json'), `${JSON.stringify(manifest, undefined, 2)}\n`)
+  const packed = await execa('pnpm', ['pack', '--pack-destination', artifacts], {
+    cwd: staging,
+    reject: false,
+  })
+  if (packed.exitCode !== 0) {
+    throw new Error(`failed to pack the simulated published prepare package:\n${packed.stderr}\n${packed.stdout}`)
+  }
+  const tarballs = readdirSync(artifacts).filter(filename => filename.endsWith('.tgz'))
+  if (tarballs.length !== 1) throw new Error(`expected one simulated published tarball, found ${tarballs.length}`)
+  const tarball = readFileSync(join(artifacts, tarballs[0]!))
+  const name = manifest.name as string
+  const version = manifest.version as string
+  const requests: string[] = []
+  let registryUrl = ''
+  const server = createServer((request, response) => {
+    const path = decodeURIComponent(new URL(request.url ?? '/', registryUrl).pathname)
+    requests.push(`${request.method ?? 'GET'} ${path}`)
+    if (path === `/${name}`) {
+      const metadata = {
+        name,
+        'dist-tags': { latest: version },
+        versions: {
+          [version]: {
+            ...manifest,
+            dist: {
+              tarball: `${registryUrl}${name}/-/${name.split('/').at(-1)}-${version}.tgz`,
+              shasum: createHash('sha1').update(tarball).digest('hex'),
+              integrity: `sha512-${createHash('sha512').update(tarball).digest('base64')}`,
+            },
+          },
+        },
+      }
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(JSON.stringify(metadata))
+      return
+    }
+    if (path === `/${name}/-/${name.split('/').at(-1)}-${version}.tgz`) {
+      response.writeHead(200, {
+        'content-type': 'application/octet-stream',
+        'content-length': String(tarball.length),
+      })
+      response.end(tarball)
+      return
+    }
+    response.writeHead(404, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'not found' }))
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', resolve)
+  })
+  const address = server.address()
+  if (address === null || typeof address === 'string') throw new Error('simulated npm registry did not expose a TCP address')
+  registryUrl = `http://127.0.0.1:${address.port}/`
+  return {
+    url: registryUrl,
+    requests,
+    close: () => new Promise<void>((resolve, reject) => {
+      server.close((error) => { if (error === undefined) resolve(); else reject(error) })
+    }),
+  }
+}
+
 describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () => {
-  it('installs, builds, and runs skill, MCP, and TypeScript Plugin contributions from a private exact GitHub source', async () => {
+  it('installs the published prepare dependency, then builds and runs skill, MCP, and TypeScript Plugin contributions from a private exact GitHub source', async () => {
     expect(existsSync(dshBin), 'the repository Plugin acceptance must run the built dsh entry').toBe(true)
     expect(source, 'DSH_GITHUB_REPOSITORY_PLUGIN_SOURCE is required by this CI lane').toMatch(
       /^github:[^/\s#&]+\/[^/\s#&]+#[0-9a-f]{40}&path:\/.*\/\.dsh-plugin$/u,
@@ -29,6 +140,17 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       successText: 'trusted GitHub repository package reached dsh run',
     })
     const home = mkdtempSync(join(tmpdir(), 'dsh-github-repository-plugin-'))
+    const registry = await startPublishedPackageRegistry(home)
+    const npmrc = join(home, 'npmrc')
+    writeFileSync(npmrc, `@deepseek-ai:registry=${registry.url}\n`)
+    const hostBin = join(home, 'host-bin')
+    mkdirSync(hostBin)
+    writeFileSync(join(hostBin, 'dsh-plugin-prepare'), [
+      '#!/bin/sh',
+      'echo "host PATH supplied dsh-plugin-prepare instead of the declared npm dependency" >&2',
+      'exit 91',
+      '',
+    ].join('\n'), { mode: 0o700 })
     const patch = join(home, 'github-repository-plugin.cordis.patch.yml')
     writeFileSync(patch, [
       '- id: repository-plugins',
@@ -59,6 +181,8 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
           DSH_TELEMETRY_DISABLED: '1',
           DEEPSEEK_API_KEY: apiKey,
           DEEPSEEK_BASE_URL: server.baseURL,
+          NPM_CONFIG_USERCONFIG: npmrc,
+          PATH: process.env.PATH === undefined ? hostBin : `${hostBin}${delimiter}${process.env.PATH}`,
         },
       })
       if (result.timedOut) {
@@ -68,6 +192,8 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       expect(result.stdout).toBe('trusted GitHub repository package reached dsh run')
       expect(server.requests).toHaveLength(2)
       const runtimeDiagnostic = `${result.stderr}\nstdout:\n${result.stdout}`
+      expect(registry.requests, runtimeDiagnostic).toContain('GET /@deepseek-ai/dsh-repository-plugin')
+      expect(registry.requests, runtimeDiagnostic).toContain('GET /@deepseek-ai/dsh-repository-plugin/-/dsh-repository-plugin-0.0.1.tgz')
       const firstRequest = JSON.stringify(server.requests[0]!.body)
       const secondRequest = JSON.stringify(server.requests[1]!.body)
       expect(firstRequest, runtimeDiagnostic).toContain(
@@ -98,6 +224,7 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
           '@modelcontextprotocol/sdk': '1.29.0',
         },
         devDependencies: {
+          '@deepseek-ai/dsh-repository-plugin': '0.0.1',
           cordis: '4.0.0-rc.7',
           tsdown: '0.22.2',
           typescript: '6.0.3',
@@ -117,6 +244,7 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
       expect(wrapper).toContain('"entry":"./lib/plugin.mjs"')
     } finally {
       await server.close()
+      await registry.close()
       rmSync(home, { recursive: true, force: true })
     }
   }, 190_000)
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 9cc95bcaf5..82f8534ad2 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1186,7 +1186,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/self-modification/repository-plugin/src/index.ts:44`](../packages/self-modification/repository-plugin/src/index.ts)
+Source: [`packages/self-modification/repository-plugin/src/index.ts:43`](../packages/self-modification/repository-plugin/src/index.ts)
 
 ## `@deepseek-ai/dsh-sandbox-local`
 
diff --git a/knip.json b/knip.json
index 0757fe49f8..9ca15de212 100644
--- a/knip.json
+++ b/knip.json
@@ -710,6 +710,9 @@
       "project": [
         "src/**/*.ts"
       ],
+      "ignoreDependencies": [
+        "@deepseek-ai/dsh-repository-plugin"
+      ],
       "ignoreBinaries": [
         "dsh-plugin-prepare"
       ]
diff --git a/packages/boot/app-boot/tests/repository-cache.spec.ts b/packages/boot/app-boot/tests/repository-cache.spec.ts
index 290b9ab2cc..9689790ffc 100644
--- a/packages/boot/app-boot/tests/repository-cache.spec.ts
+++ b/packages/boot/app-boot/tests/repository-cache.spec.ts
@@ -115,24 +115,9 @@ describe('RepositoryCache', () => {
   it('isolates and prepares a .dsh-plugin Git subpath from an enclosing pnpm workspace', { timeout: 60_000 }, async () => {
     const root = await temporaryRoot('repository-pnpm')
     const repository = join(root, 'source')
-    const executableDirectory = join(root, 'bin')
-    await mkdir(executableDirectory)
-    await writeFile(join(executableDirectory, 'dsh-plugin-prepare'), [
-      '#!/usr/bin/env node',
-      "const { cpSync, mkdirSync, writeFileSync } = require('node:fs')",
-      "mkdirSync('dsh-plugin-assets/skills', { recursive: true })",
-      "cpSync('../skills', 'dsh-plugin-assets/skills/0', { recursive: true })",
-      "writeFileSync('dsh-plugin.mjs', 'export function apply() {}\\n')",
-      "writeFileSync('prepared.txt', `${process.env.REPOSITORY_TEST_VISIBLE ?? 'absent'}|${process.env.REPOSITORY_TEST_TOKEN ?? 'absent'}\\n`)",
-      '',
-    ].join('\n'), { mode: 0o700 })
-    await writeFile(join(executableDirectory, 'dsh-plugin-prepare.cmd'), [
-      '@echo off',
-      'node "%~dp0\\dsh-plugin-prepare" %*',
-      '',
-    ].join('\r\n'))
     await mkdir(join(repository, '.dsh-plugin'), { recursive: true })
     await mkdir(join(repository, 'build-helper'), { recursive: true })
+    await mkdir(join(repository, 'prepare-helper'), { recursive: true })
     await mkdir(join(repository, 'skills', 'fixture'), { recursive: true })
     await writeFile(join(repository, 'package.json'), `${JSON.stringify({
       name: 'repository-fixture',
@@ -160,12 +145,29 @@ describe('RepositoryCache', () => {
       "require('node:fs').writeFileSync('dependency-built.txt', 'dependency available\\n')",
       '',
     ].join('\n'), { mode: 0o700 })
+    await writeFile(join(repository, 'prepare-helper', 'package.json'), `${JSON.stringify({
+      name: 'repository-prepare-helper',
+      version: '1.0.0',
+      bin: { 'dsh-plugin-prepare': 'index.js' },
+    })}\n`)
+    await writeFile(join(repository, 'prepare-helper', 'index.js'), [
+      '#!/usr/bin/env node',
+      "const { cpSync, mkdirSync, writeFileSync } = require('node:fs')",
+      "mkdirSync('dsh-plugin-assets/skills', { recursive: true })",
+      "cpSync('../skills', 'dsh-plugin-assets/skills/0', { recursive: true })",
+      "writeFileSync('dsh-plugin.mjs', 'export function apply() {}\\n')",
+      "writeFileSync('prepared.txt', `${process.env.REPOSITORY_TEST_VISIBLE ?? 'absent'}|${process.env.REPOSITORY_TEST_TOKEN ?? 'absent'}\\n`)",
+      '',
+    ].join('\n'), { mode: 0o700 })
     await writeFile(join(repository, 'skills', 'fixture', 'SKILL.md'), 'repository skill source\n')
     await writeFile(join(repository, '.dsh-plugin', 'package.json'), `${JSON.stringify({
       name: 'repository-plugin-fixture',
       version: '1.0.0',
       scripts: { prepack: 'repository-build-helper && dsh-plugin-prepare' },
-      devDependencies: { 'repository-build-helper': 'file:../build-helper' },
+      devDependencies: {
+        'repository-build-helper': 'file:../build-helper',
+        'repository-prepare-helper': 'file:../prepare-helper',
+      },
       dsh: { skills: ['../skills'] },
     })}\n`)
     await execFileAsync('git', ['init', '--quiet'], { cwd: repository })
@@ -180,9 +182,7 @@ describe('RepositoryCache', () => {
     vi.stubEnv('REPOSITORY_TEST_VISIBLE', 'visible')
     vi.stubEnv('REPOSITORY_TEST_TOKEN', 'hidden')
 
-    const installed = await new RepositoryCache(join(root, 'cache'), {
-      executableDirectories: [executableDirectory],
-    }).resolve(specifier)
+    const installed = await new RepositoryCache(join(root, 'cache')).resolve(specifier)
     await expect(readFile(join(installed, 'dependency-built.txt'), 'utf8')).resolves.toBe('dependency available\n')
     await expect(readFile(join(installed, 'prepared.txt'), 'utf8')).resolves.toBe('visible|absent\n')
     await expect(readFile(join(installed, 'dsh-plugin.mjs'), 'utf8')).resolves.toContain('export function apply')
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index 5c4ad1e929..770cf0fab0 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: e10907408a98cd470ae935b327ae44322f2e54a7
-README.zh.md: b8ba7dccd929574cc5aa1b7a3d68bf4f1e2f80e4
+README.md: 3a6478d5cca05684e80ce0854cb6e0b5d2f88bd4
+README.zh.md: 274d11c96cb61d4d9fa4b837433994248c94bff4
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index e10907408a..3a6478d5cc 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -27,12 +27,13 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
     "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-repository-plugin": "^0.0.1",
     "typescript": "6.0.3"
   }
 }
 ```
 
-`scripts.prepack` must be non-empty and invoke `dsh-plugin-prepare`; it may run arbitrary package-owned build steps first. DSH supplies only that helper command from its installed runtime: the package declares and runs its own compiler, runtime dependencies, and other npm lifecycle code. The selected package is installed from its own manifest instead of inheriting an enclosing pnpm workspace, so declare every dependency it needs and do not depend on workspace-only hoisting. DSH does not transpile TypeScript or infer a package entry.
+`scripts.prepack` must be non-empty and invoke `dsh-plugin-prepare`; it may run arbitrary package-owned build steps first. The package declares `@deepseek-ai/dsh-repository-plugin` as an ordinary development dependency so its published executable is available to that lifecycle. DSH does not inject the helper: the repository package declares and runs its own compiler, runtime dependencies, preparation helper, and other npm lifecycle code. The selected package is installed from its own manifest instead of inheriting an enclosing pnpm workspace, so declare every dependency it needs and do not depend on workspace-only hoisting. DSH does not transpile TypeScript or infer a package entry.
 
 `dsh.entry` is an optional relative path to a compiled ESM Cordis Plugin inside `.dsh-plugin`. The module may use either namespace exports or a default export and owns its ordinary `name`, `inject`, `Config`, registrations, and effects. `dsh.skills` is an optional array of local skill roots, and `dsh.mcpServers` is an optional path to one `.mcp.json`; at least one of the three fields is required. Skill and MCP paths may reach adjacent repository assets but must remain beneath the directory containing `.dsh-plugin`; the compiled entry must remain inside the package selected and packed by the package manager. A repository containing several Plugins gives each one its own `.dsh-plugin` package under a different selectable subdirectory.
 
@@ -59,7 +60,7 @@ Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A v
 
 ## Preparation
 
-During exact Git installation, DSH places temporary host-owned `pnpm` and `dsh-plugin-prepare` commands on the isolated package lifecycle `PATH`; neither command is fetched from the repository. The pnpm command reinvokes DSH's pinned pnpm with `--ignore-workspace`, so an enclosing workspace lockfile cannot suppress dependencies declared only by the selected `.dsh-plugin` package. The required `prepack` lifecycle runs after that dependency installation and before the selected subdirectory is packed. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to install, build, or prepare fails before a cache generation is published. Rationale: [host-owned Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md).
+During exact Git installation, DSH's bundled pnpm installs the selected package from its own manifest. A transaction-owned `pnpm` wrapper reinvokes the same pinned pnpm with `--ignore-workspace`, so an enclosing workspace lockfile cannot suppress dependencies declared only by the selected `.dsh-plugin` package. The required `prepack` lifecycle runs after that dependency installation and before the selected subdirectory is packed; its ordinary `node_modules/.bin` lookup obtains `dsh-plugin-prepare` from the declared `@deepseek-ai/dsh-repository-plugin` dependency. That package marks its Cordis/DSH runtime peers optional so using the executable alone does not install the runtime graph. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to resolve the published helper, install dependencies, build, or prepare fails before a cache generation is published. Rationale: [npm-backed Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md).
 
 ## Runtime composition
 
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index b8ba7dccd9..274d11c96c 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -27,12 +27,13 @@
     "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-repository-plugin": "^0.0.1",
     "typescript": "6.0.3"
   }
 }
 ```
 
-`scripts.prepack` 必须非空并调用 `dsh-plugin-prepare`；可以先运行任意包自有的构建步骤。DSH 已安装的运行时只提供该辅助命令：包自行声明并运行编译器、运行时依赖和其他 NPM 生命周期代码。所选包按自身 manifest 独立安装，而不继承外层 pnpm workspace，因此必须声明所需的每项依赖，不能依赖仅由 workspace 提升而可见的包。DSH 不转译 TypeScript，也不推断包入口。
+`scripts.prepack` 必须非空并调用 `dsh-plugin-prepare`；可以先运行任意包自有的构建步骤。包将 `@deepseek-ai/dsh-repository-plugin` 声明为普通开发依赖，使该生命周期可以使用其已发布的可执行文件。DSH 不会注入辅助程序：repository 包自行声明并运行编译器、运行时依赖、准备辅助程序及其他 NPM 生命周期代码。所选包按自身 manifest 独立安装，而不继承外层 pnpm workspace，因此必须声明所需的每项依赖，不能依赖仅由 workspace 提升而可见的包。DSH 不转译 TypeScript，也不推断包入口。
 
 `dsh.entry` 是指向 `.dsh-plugin` 内已编译 ESM Cordis 插件的可选相对路径。该模块可以使用 namespace 导出或 default export，并自行拥有常规的 `name`、`inject`、`Config`、注册和 effect。`dsh.skills` 是可选的本地 skill 根数组，`dsh.mcpServers` 是指向一个 `.mcp.json` 的可选路径；三个字段中至少声明一个。skill 和 MCP 路径可以引用相邻的 repository 资源，但必须留在包含 `.dsh-plugin` 的目录下；已编译入口必须留在由包管理器选中并打包的包内。一个仓库可以在不同的可选择子目录下放置多个各自独立的 `.dsh-plugin` 包。
 
@@ -59,7 +60,7 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 ## 准备阶段
 
-安装精确指定的 Git 源时，DSH 会把临时的宿主自有 `pnpm` 与 `dsh-plugin-prepare` 命令放入隔离的包生命周期 `PATH`；两个命令都不从 repository 获取。该 pnpm 命令会以 `--ignore-workspace` 重新调用 DSH 锁定的 pnpm，因此外层 workspace lockfile 无法抑制仅由所选 `.dsh-plugin` 包声明的依赖。必需的 `prepack` 生命周期在该依赖安装完成后、选定子目录打包前运行。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。安装、构建或准备失败时，流程会在发布缓存 generation 前失败。设计依据见[宿主自有 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-host-owned-git-repository-plugin-preparation.md)。
+安装精确指定的 Git 源时，DSH 随附的 pnpm 会按所选包自身的 manifest 安装。由事务持有的 `pnpm` 包装脚本会以 `--ignore-workspace` 重新调用同一份锁定的 pnpm，因此外层 workspace lockfile 无法抑制仅由所选 `.dsh-plugin` 包声明的依赖。必需的 `prepack` 生命周期在该依赖安装完成后、选定子目录打包前运行；其常规 `node_modules/.bin` 查找会从已声明的 `@deepseek-ai/dsh-repository-plugin` 依赖取得 `dsh-plugin-prepare`。该包把 Cordis／DSH 运行时对等依赖（peer dependency）标为可选，因此单独使用该可执行文件不会安装运行时依赖图。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。无法解析已发布的辅助程序，或安装依赖、构建或准备失败时，流程会在发布缓存 generation 前失败。设计依据见[基于 NPM 的 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md)。
 
 ## 运行时组合
 
diff --git a/packages/self-modification/repository-plugin/package.json b/packages/self-modification/repository-plugin/package.json
index fbf18c0cb1..f20ec986c2 100644
--- a/packages/self-modification/repository-plugin/package.json
+++ b/packages/self-modification/repository-plugin/package.json
@@ -36,6 +36,26 @@
     "@deepseek-ai/dsh-skill-local": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "peerDependenciesMeta": {
+    "@cordisjs/plugin-loader": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-invariants": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-mcp-client": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-paths": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-skill-local": {
+      "optional": true
+    },
+    "cordis": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "zod": "^4.4.3"
   },
diff --git a/packages/self-modification/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
index 63ba724108..852e57b253 100644
--- a/packages/self-modification/repository-plugin/src/format.ts
+++ b/packages/self-modification/repository-plugin/src/format.ts
@@ -14,11 +14,11 @@ export const PREPARED_ENTRY_FILENAME = 'dsh-plugin.mjs'
 export const PREPARED_ASSET_DIRECTORY = 'dsh-plugin-assets'
 /** Loader builtin used by every generated repository wrapper. */
 export const REPOSITORY_PLUGIN_BUILTIN = 'dsh-repository-plugin'
-/** Host-owned command that repository package `prepack` lifecycles must invoke. */
+/** Dependency-provided command that repository package `prepack` lifecycles must invoke. */
 export const REPOSITORY_PLUGIN_PREPARE_COMMAND = 'dsh-plugin-prepare'
 
 /**
- * Whether a package lifecycle declaration names the host preparation helper.
+ * Whether a package lifecycle declaration names the preparation dependency's helper.
  * @param script - package-authored lifecycle command.
  * @returns true when the required helper command is present.
  */
diff --git a/packages/self-modification/repository-plugin/src/index.ts b/packages/self-modification/repository-plugin/src/index.ts
index 403c2d1ae9..8026199c16 100644
--- a/packages/self-modification/repository-plugin/src/index.ts
+++ b/packages/self-modification/repository-plugin/src/index.ts
@@ -20,7 +20,6 @@ import {
 } from './format.ts'
 import { parseMcpDocument, resolveMcpServers } from './mcp.ts'
 import {
-  createRepositoryPrepareCommand,
   loadPreparedRepository,
   resolveRepositoryCacheDirectory,
   resolveRepositorySpecifier,
@@ -131,24 +130,17 @@ export async function apply(ctx: Context, config: Config = {}): Promise<void> {
   if (new Set(repositories).size !== repositories.length) {
     throw new Error('repository sources must resolve to unique exact specifiers')
   }
-  const prepareCommand = repositories.length === 0 ? undefined : await createRepositoryPrepareCommand()
-  try {
-    const cache = new RepositoryCache(resolveRepositoryCacheDirectory(config.cacheDir), {
-      executableDirectories: prepareCommand === undefined ? [] : [prepareCommand.directory],
-    })
-    await ctx.effect(async function* () {
-      ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] = preparedRuntime
-      yield () => {
-        if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] === preparedRuntime) {
-          Reflect.deleteProperty(ctx.loader.builtins, REPOSITORY_PLUGIN_BUILTIN)
-        }
+  const cache = new RepositoryCache(resolveRepositoryCacheDirectory(config.cacheDir))
+  await ctx.effect(async function* () {
+    ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] = preparedRuntime
+    yield () => {
+      if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] === preparedRuntime) {
+        Reflect.deleteProperty(ctx.loader.builtins, REPOSITORY_PLUGIN_BUILTIN)
       }
-      for (const repository of repositories) {
-        const plugin = await loadPreparedRepository(ctx, cache, repository)
-        yield plugin.dispose
-      }
-    }, 'repository-plugin runtime and sources')
-  } finally {
-    await prepareCommand?.dispose()
-  }
+    }
+    for (const repository of repositories) {
+      const plugin = await loadPreparedRepository(ctx, cache, repository)
+      yield plugin.dispose
+    }
+  }, 'repository-plugin runtime and sources')
 }
diff --git a/packages/self-modification/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
index 51f015e68a..a85bb0467e 100644
--- a/packages/self-modification/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -3,10 +3,9 @@
  * @module
  */
 
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
+import { pathToFileURL } from 'node:url'
 import type { Context, Fiber, FiberState, Plugin } from 'cordis'
 import type { RepositoryCache } from '@cordisjs/plugin-loader/repository'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
@@ -24,56 +23,6 @@ const FIBER_ACTIVE = 2 as FiberState.ACTIVE
 /** Directory under the Harness home containing immutable repository generations. */
 export const DEFAULT_REPOSITORY_CACHE_DIRECTORY = 'repository-plugins'
 
-/** Temporary host command supplied to repository package lifecycle scripts. */
-export interface RepositoryPrepareCommand {
-  /** Absolute directory to prepend to the isolated install's executable search path. */
-  directory: string
-  /** Remove the temporary command directory. */
-  dispose(): Promise<void>
-}
-
-function shellQuote(value: string): string {
-  return `'${value.replaceAll("'", "'\\''")}'`
-}
-
-function batchQuote(value: string): string {
-  return `"${value.replaceAll('%', '%%')}"`
-}
-
-/**
- * Materialize the DSH-owned prepare executable used only while pnpm packs Git source.
- * @returns a command directory and its idempotent cleanup operation.
- */
-export async function createRepositoryPrepareCommand(): Promise<RepositoryPrepareCommand> {
-  const directory = await mkdtemp(join(tmpdir(), 'dsh-repository-plugin-bin-'))
-  const target = fileURLToPath(new URL('../lib/bin.js', import.meta.url))
-  try {
-    await Promise.all([
-      writeFile(join(directory, REPOSITORY_PLUGIN_PREPARE_COMMAND), [
-        '#!/bin/sh',
-        `exec ${shellQuote(process.execPath)} ${shellQuote(target)} "$@"`,
-        '',
-      ].join('\n'), { mode: 0o700 }),
-      writeFile(join(directory, `${REPOSITORY_PLUGIN_PREPARE_COMMAND}.cmd`), [
-        '@echo off',
-        `${batchQuote(process.execPath)} ${batchQuote(target)} %*`,
-        '',
-      ].join('\r\n'), { mode: 0o700 }),
-    ])
-  } catch (cause) {
-    /* v8 ignore next -- requires a host filesystem failure after mkdtemp; cleanup semantics are the contract under test. */
-    await rm(directory, { recursive: true, force: true })
-    /* v8 ignore next -- preserves that unstageable host failure after best-effort cleanup. */
-    throw cause
-  }
-  return {
-    directory,
-    async dispose() {
-      await rm(directory, { recursive: true, force: true })
-    },
-  }
-}
-
 // The ref segment excludes `#` so `github:o/r#a#b` fails here — at the config
 // parser, with the syntax the error message promises — instead of inside the
 // cache's pnpm install ('misconfiguration fails loud at the earliest
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index 26b739677a..b5abf6fbdd 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -14,7 +14,6 @@ import * as RepositoryPlugin from '@deepseek-ai/dsh-repository-plugin'
 import * as RepositoryPluginInvariant from '@deepseek-ai/dsh-repository-plugin/invariant'
 import { parsePreparedPluginConfig } from '../src/format.ts'
 import {
-  createRepositoryPrepareCommand,
   loadPreparedRepository,
   resolveRepositoryCacheDirectory,
   resolveRepositorySpecifier,
@@ -87,7 +86,7 @@ describe('dsh-plugin-prepare', () => {
       .resolves.toContain('mcp.expo.dev')
   })
 
-  it('preserves a compiled package entry and accepts a build before the host prepare command', async () => {
+  it('preserves a compiled package entry and accepts a build before the package prepare command', async () => {
     const root = await temporaryDirectory('compiled-entry')
     const directory = await writePlugin(root, 'compiled-entry-fixture', {
       entry: './lib/plugin.mjs',
@@ -406,17 +405,6 @@ describe('prepared repository plugin Loader composition', () => {
 })
 
 describe('configured GitHub repository sources', () => {
-  it('creates host-owned prepare commands and removes them idempotently', async () => {
-    const command = await createRepositoryPrepareCommand()
-    expect(await readFile(join(command.directory, RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND), 'utf8'))
-      .toContain(process.execPath)
-    expect(await readFile(join(command.directory, `${RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND}.cmd`), 'utf8'))
-      .toContain(process.execPath)
-    await command.dispose()
-    await command.dispose()
-    await expect(stat(command.directory)).rejects.toMatchObject({ code: 'ENOENT' })
-  })
-
   it('defaults an omitted source list and rejects unknown configuration fields', () => {
     expect(RepositoryPlugin.Config.parse(undefined)).toEqual({ repositories: [] })
     expect(RepositoryPlugin.Config.safeParse({ repositories: [], unexpected: true }).success).toBe(false)
@@ -608,7 +596,7 @@ describe('configured GitHub repository sources', () => {
     await ctx.fiber.dispose()
   })
 
-  it('rejects an installed source whose prepack omits the host prepare command', async () => {
+  it('rejects an installed source whose prepack omits the package prepare command', async () => {
     const root = await temporaryDirectory('installed-skipped-prepare')
     await writeFile(join(root, 'package.json'), JSON.stringify({
       name: 'installed-skipped-prepare',
diff --git a/vendor/README.md b/vendor/README.md
index be55f8e77a..684c2c6363 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -39,7 +39,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
 9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
-10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. Callers may prepend host-owned executable directories to the isolated package lifecycle `PATH`; all paths are resolved before the child starts. A transaction-owned `pnpm` wrapper makes pnpm's nested Git-package install reinvoke the same bundled entry with `--ignore-workspace`, so the selected package installs its own manifest dependencies instead of joining an enclosing source workspace. Temporary command directories are removed after the child settles. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` whose package is excluded from an enclosing pnpm lockfile and requires its own build dependency.
+10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. A transaction-owned `pnpm` wrapper makes pnpm's nested Git-package install reinvoke the same bundled entry with `--ignore-workspace`, so the selected package installs its own manifest dependencies instead of joining an enclosing source workspace. The temporary command directory is removed after the child settles. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` whose package is excluded from an enclosing pnpm lockfile and obtains both its build and prepare commands from declared dependencies.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
 13. **`include/src/index.ts` serialized child-tree mutation and `hmr/src/index.ts` main-watcher initial-scan suppression**: every Include child-tree mutation (initial apply, refresh, `internal/update` patch re-application) runs through one per-Include queue, because the group's transactional `update` is not reentrant — two concurrent applies interleave create and rollback on the same entries and strand the Include fiber without ever settling. The HMR main watcher passes `ignoreInitial: true`: the initial scan re-announced files boot had just consumed, and its `add` for a config file refreshed an Include mid-initial-apply; once serialized, a failing initial apply's rollback disposed HMR, whose teardown drain waited on the queued refresh sitting behind that same apply — a deadlock that exited 13 with no diagnostic. `registerConfig()` keeps its own `ignoreInitial: false` watcher because a user patch layer present at registration must apply once. Covered by the patch-overlay boot-failure built-bin case in `apps/cli/tests/built-bin.e2e.ts`.
diff --git a/vendor/loader/src/repository.ts b/vendor/loader/src/repository.ts
index 91ad9c372a..5cb6ec387b 100644
--- a/vendor/loader/src/repository.ts
+++ b/vendor/loader/src/repository.ts
@@ -26,8 +26,6 @@ export type RepositoryInstall = (directory: string) => Promise<void>
 export interface RepositoryCacheOptions {
   /** Override the isolated package installation boundary. */
   install?: RepositoryInstall
-  /** Command directories resolved absolutely and prepended to package lifecycle `PATH`. */
-  executableDirectories?: readonly string[]
 }
 
 interface CacheMarker {
@@ -38,14 +36,13 @@ function scrubEnvironment(environment: NodeJS.ProcessEnv = process.env): NodeJS.
   return Object.fromEntries(Object.entries(environment).filter(([name]) => !SENSITIVE_ENV_PATTERN.test(name)))
 }
 
-function installEnvironment(executableDirectories: readonly string[]): NodeJS.ProcessEnv {
+function installEnvironment(commandDirectory: string): NodeJS.ProcessEnv {
   const scrubbed = scrubEnvironment()
-  if (executableDirectories.length === 0) return scrubbed
   const path = Object.entries(scrubbed).find(([name]) => name.toUpperCase() === 'PATH')?.[1]
   const withoutPath = Object.fromEntries(Object.entries(scrubbed).filter(([name]) => name.toUpperCase() !== 'PATH'))
   return {
     ...withoutPath,
-    PATH: [...executableDirectories, ...(path === undefined ? [] : [path])].join(delimiter),
+    PATH: [commandDirectory, ...(path === undefined ? [] : [path])].join(delimiter),
   }
 }
 
@@ -62,10 +59,7 @@ function appendOutput(current: string, chunk: Uint8Array): string {
   return combined.length <= MAX_ERROR_OUTPUT ? combined : combined.slice(-MAX_ERROR_OUTPUT)
 }
 
-async function installWithBundledPnpm(
-  directory: string,
-  executableDirectories: readonly string[],
-): Promise<void> {
+async function installWithBundledPnpm(directory: string): Promise<void> {
   const require = createRequire(import.meta.url)
   const pnpmManifest = require.resolve('pnpm')
   const pnpmBin = join(dirname(pnpmManifest), 'bin', 'pnpm.mjs')
@@ -92,7 +86,7 @@ async function installWithBundledPnpm(
         '--reporter=append-only',
       ], {
         cwd: directory,
-        env: installEnvironment([commandDirectory, ...executableDirectories]),
+        env: installEnvironment(commandDirectory),
         shell: false,
         stdio: ['ignore', 'pipe', 'pipe'],
       })
@@ -174,12 +168,11 @@ export class RepositoryCache {
 
   /**
    * @param directory - caller-owned persistent cache root.
-   * @param options - isolated installer override and lifecycle command directories.
+   * @param options - isolated installer override.
    */
   constructor(directory: string, options: RepositoryCacheOptions = {}) {
     this.directory = resolve(directory)
-    const executableDirectories = (options.executableDirectories ?? []).map(entry => resolve(entry))
-    this.install = options.install ?? (staging => installWithBundledPnpm(staging, executableDirectories))
+    this.install = options.install ?? installWithBundledPnpm
   }
 
   /**

From cc7bd4948d5059ac96769b6c2abbed6eade438c5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:50:54 +0800
Subject: [PATCH 445/516] fix(repository-plugin): reject incomplete MCP
 publication

---
 ...-static-repository-plugin-format.i18n.yaml |  4 ++--
 ...6-07-30-static-repository-plugin-format.md |  4 ++--
 ...7-30-static-repository-plugin-format.zh.md |  4 ++--
 ...-trusted-repository-package-code.i18n.yaml |  4 ++--
 ...6-08-08-trusted-repository-package-code.md |  8 +++----
 ...8-08-trusted-repository-package-code.zh.md | 10 ++++----
 docs/config-catalog.md                        |  4 ++--
 packages/mcp/mcp-client/README.i18n.yaml      |  4 ++--
 packages/mcp/mcp-client/README.md             |  7 +++---
 packages/mcp/mcp-client/README.zh.md          |  7 +++---
 packages/mcp/mcp-client/src/index.ts          | 14 +++++++----
 packages/mcp/mcp-client/src/tools.ts          |  8 +++++--
 packages/mcp/mcp-client/tests/apply.spec.ts   | 24 ++++++++++++++++++-
 .../mcp/mcp-client/tests/mcp-client.spec.ts   |  1 +
 .../repository-plugin/README.i18n.yaml        |  4 ++--
 .../repository-plugin/README.md               |  5 ++--
 .../repository-plugin/README.zh.md            |  5 ++--
 .../repository-plugin/src/format.ts           |  1 +
 .../repository-plugin/src/source.ts           |  6 ++++-
 .../tests/repository-plugin.spec.ts           |  8 ++++++-
 20 files changed, 89 insertions(+), 43 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
index 33e7540bbc..422b667ebd 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.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 .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
-2026-07-30-static-repository-plugin-format.md: afc88bb974ccc6ef7843eaf1e98f16b65bb6d4b3
-2026-07-30-static-repository-plugin-format.zh.md: a6dc6ec6ec89c04b79edea279029ae33091ca0af
+2026-07-30-static-repository-plugin-format.md: c66ee111eb0cac9e0d6c54581855ffc18efc8611
+2026-07-30-static-repository-plugin-format.zh.md: 969d7eb536158137807826eba2313670a7d37580
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
index afc88bb974..c66ee111eb 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.md
@@ -20,7 +20,7 @@ Loading the DSH package registers that builtin as an effect. A generated wrapper
 
 Each prepared skill set mounts `dsh-skill-local` with a unique `repository:<package-name>` provider name, only the copied custom roots, and watching disabled. `dsh-skill-local` therefore gains two general configuration fields: `providerName` and `includeDefaultRoots`. Their defaults preserve its existing single local provider; repository instances set a distinct name and exclude project/user roots so multiple instances neither collide nor duplicate host-local discovery.
 
-Each `.mcp.json` server becomes one existing `dsh-mcp-client` child. The adapter accepts the common root `{ "mcpServers": ... }`; stdio definitions allow only optional `type: "stdio"`, `command`, `args`, and `env`, while HTTP definitions allow only `type: "http"`, `url`, and `headers`. Exact `${NAME}` process-environment references expand at runtime, after cache preparation; missing names fail Plugin load. HTTP maps to the client's Streamable HTTP transport, and stdio uses the prepared package directory as `cwd`. The existing client alone owns connection attempts, failure logging, remote tool synchronization, tool calls, and disconnects. Consequently an MCP connection failure keeps its established successful-plugin/no-tools behavior and is not reclassified as a repository preparation or Loader failure.
+Each `.mcp.json` server becomes one existing `dsh-mcp-client` child. The adapter accepts the common root `{ "mcpServers": ... }`; stdio definitions allow only optional `type: "stdio"`, `command`, `args`, and `env`, while HTTP definitions allow only `type: "http"`, `url`, and `headers`. Exact `${NAME}` process-environment references expand at runtime, after cache preparation; missing names fail Plugin load. HTTP maps to the client's Streamable HTTP transport, and stdio uses the prepared package directory as `cwd`. The existing client alone owns connection attempts, failure logging, remote tool synchronization, tool calls, and disconnects. Repository instances enable strict startup, so an initial connection, discovery, or tool-registration failure rejects the repository Loader generation; non-strict standalone clients retain the logged successful-plugin/no-tools behavior.
 
 Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `CLAUDE_PLUGIN_ROOT`, and a broader Claude compatibility contract. Commands, hooks, agents, rules, and other foreign manifest conventions are not inferred from static repository layout; DSH-native behavior uses the explicit trusted Cordis entry. Repository subdirectory selection and GitHub source configuration belong to the [standalone app integration](../feature/2026-07-30-config-only-repository-plugins.md), not this static adapter.
 
@@ -34,7 +34,7 @@ Unknown MCP fields reject. This intentionally excludes OAuth, `auth` objects, `C
 
 **Watch prepared repository assets.** Rejected because an exact repository cache generation is immutable. Ref, subdirectory, or configuration changes select a new generation; a second watcher would create an unowned refresh identity.
 
-**Treat MCP connect failures as Loader update failures.** Rejected because the existing MCP client deliberately contains connect failures and exposes no tools. Changing that semantic only for repository sources would create two failure contracts for the same server configuration.
+**Make every MCP connect failure a Loader update failure.** Rejected because optional standalone MCP clients deliberately contain startup failures and expose no tools. The MCP client instead owns an explicit strict-startup option, which repository adapters enable for their declared servers.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
index a6dc6ec6ec..969d7eb536 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md
@@ -20,7 +20,7 @@
 
 每份已准备 skill 集合都会挂载 `dsh-skill-local`，使用唯一的 `repository:<package-name>` 提供方名称、仅包含复制后的自定义根，并禁用监视。因此 `dsh-skill-local` 新增两个通用配置字段：`providerName` 和 `includeDefaultRoots`。默认值保持原有单一本地提供方行为；repository 实例设置不同名称并排除项目／用户根，使多个实例既不冲突，也不会重复宿主本地发现。
 
-`.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配层接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。严格的 `${NAME}` 进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。因此 MCP 连接失败会继续沿用“Plugin 成功但不注册工具”的既有行为，不会被重新分类为 repository 准备或 Loader 失败。
+`.mcp.json` 中的每个 server 都变成一个现有 `dsh-mcp-client` 子级。适配层接受通用根对象 `{ "mcpServers": ... }`；stdio 定义只允许可选的 `type: "stdio"`、`command`、`args` 与 `env`，HTTP 定义只允许 `type: "http"`、`url` 与 `headers`。严格的 `${NAME}` 进程环境变量引用在运行时、cache 准备之后展开；缺失变量会使 Plugin 加载失败。HTTP 映射到 client 的 Streamable HTTP transport，stdio 使用已准备 package 目录作为 `cwd`。只有现有 client 负责连接尝试、失败日志、远端工具同步、工具调用和断开。Repository 实例会启用严格启动，因此初始连接、发现或工具注册失败会拒绝 repository Loader generation；非严格的独立 client 则保留“记录日志、Plugin 成功但不注册工具”的行为。
 
 未知 MCP 字段会被拒绝。这里有意排除 OAuth、`auth` 对象、`CLAUDE_PLUGIN_ROOT` 和更广泛的 Claude 兼容契约。命令、hook、agent（智能体）、规则和其他外来 manifest 约定不会从静态 repository 布局中推断出来；DSH 原生行为使用显式的受信任 Cordis 入口。Repository 子目录选择与 GitHub 源配置属于[独立应用集成](../feature/2026-07-30-config-only-repository-plugins.md)，而不是本静态适配器。
 
@@ -34,7 +34,7 @@
 
 **监视已准备 repository 资源。** 拒绝，因为一个精确 repository cache generation 是不可变的。Ref、子目录或配置变化会选择新 generation；第二套 watcher 会创造一套没有所有者的刷新身份。
 
-**把 MCP 连接失败当作 Loader 更新失败。** 拒绝，因为现有 MCP client 有意收束连接失败并不暴露工具。只对 repository source 改变该语义，会让同一 server 配置拥有两套失败契约。
+**把每次 MCP 连接失败都当作 Loader 更新失败。** 拒绝，因为可选的独立 MCP client 会有意收束启动失败，并且不暴露工具。MCP client 改为自行提供显式的严格启动选项，由 repository 适配器为其声明的 server 启用。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
index 16b72afb4e..af4950b20c 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.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 .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
-2026-08-08-trusted-repository-package-code.md: 6c568964c2d4392054107acb1e73ace8f50d5f0b
-2026-08-08-trusted-repository-package-code.zh.md: c2587286379398ab853b71c8b8819d274d06c65b
+2026-08-08-trusted-repository-package-code.md: 387479b3b36a8bc5e145641ae40802b3090ced70
+2026-08-08-trusted-repository-package-code.zh.md: aff34d4485553f076c5dd1b71f0a3c5b5c62bc8f
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
index 6c568964c2..387479b3b3 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
@@ -16,9 +16,9 @@ A configured repository package is trusted code. Its `.dsh-plugin/package.json`
 
 The package owns its npm dependencies and build toolchain. It declares the published `@deepseek-ai/dsh-repository-plugin` package to obtain the `dsh-plugin-prepare` executable. `scripts.prepack` is a non-empty package-authored command that must invoke that dependency-provided helper, but it may first run `tsc`, `tsdown`, or any other build. DSH neither injects the helper, parses the shell program, nor compiles repository source. The helper validates the metadata after the preceding build, requires the configured entry to resolve to a file within `.dsh-plugin`, validates and copies declared static assets, and writes the prepared `dsh-plugin.mjs` wrapper. The installed package must retain a `prepack` declaration containing that helper command; a missing dependency, wrapper, or build output fails before a cache generation becomes usable.
 
-The generated wrapper first mounts the DSH-owned static runtime for skills and MCP definitions, then dynamically imports and unwraps the explicit entry and mounts it as a child. Both children must reach Cordis `ACTIVE`; an unsatisfied `inject` or startup exception rejects the repository Loader transaction instead of committing an inert generation. Loader removal, failed replacement, and parent disposal unwind the entry, skill providers, MCP clients, and their effects together.
+The generated wrapper first mounts the DSH-owned static runtime for skills and MCP definitions, then dynamically imports and unwraps the explicit entry and mounts it as a child. The wrapper statically declares dependencies implied by the prepared manifest; an entry module's additional `inject` is discovered only when mounted and must already be available in the host composition. Both children must reach Cordis `ACTIVE`; an unsatisfied `inject` or startup exception rejects the repository Loader transaction instead of committing an inert generation. Loader removal, failed replacement, and parent disposal unwind the entry, skill providers, MCP clients, and their effects together.
 
-`dsh-mcp-client` resolves its initial connection and tool synchronization promise as part of Plugin application. Its entry is an `async function`, not an ordinary function returning a Promise: Cordis identifies prototype-bearing ordinary functions as constructors and does not treat a constructor's returned Promise as startup work. A valid server's tools therefore exist before its parent repository wrapper activates and before a one-shot application starts its first model request. Its `failOnStartupError` config preserves optional standalone servers by default while letting repository adapters require their declared servers. Repository-translated MCP clients enable that mode, so initial connection or discovery failure rejects the candidate generation and rollback still closes the transport.
+`dsh-mcp-client` resolves its initial connection and tool synchronization promise as part of Plugin application. Its entry is an `async function`, not an ordinary function returning a Promise: Cordis identifies prototype-bearing ordinary functions as constructors and does not treat a constructor's returned Promise as startup work. A valid server's tools therefore exist before its parent repository wrapper activates and before a one-shot application starts its first model request. Its `failOnStartupError` config preserves optional standalone servers by default while letting repository adapters require their declared servers. Repository-translated MCP clients enable that mode, so initial connection, discovery, or tool-registration failure rejects the candidate generation and rollback still closes the transport.
 
 ## Trust boundary
 
@@ -41,11 +41,11 @@ Model-visible behavior remains governed by the owning DSH seam. A repository ent
 - A TypeScript DSH Plugin can live in a GitHub repository, install ordinary npm dependencies, compile during `prepack`, and run without publishing the Plugin package to npm.
 - Static-only repository packages remain valid and retain import-free wrappers; adding `dsh.entry` opts that package into runtime code import.
 - A package build, dependency install, entry import, unmet service, or Plugin startup failure prevents the candidate generation from replacing the last good configuration.
-- The initial MCP connection can lengthen application startup, and a repository-declared server that is unavailable prevents that candidate generation from activating.
+- Initial MCP synchronization can lengthen application startup by the MCP SDK's per-request timeout, and a repository-declared server that is unavailable or cannot publish its complete tool generation prevents that candidate generation from activating.
 - Repository code receives host authority, so source review and immutable pinning are operational security requirements rather than optional hardening.
 
 ## Testing
 
-Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication, preserve opt-in contained connect failure, and prove strict startup rejection still closes the client.
+Repository-format tests prepare and mount default-export code entries through the real Loader, observe an entry-owned service, remove the Loader row, and observe cleanup; they also retain skill/MCP preparation, containment, damaged-package, pending-service, and rollback coverage. MCP lifecycle tests require `apply` to settle only after initial tool publication, preserve opt-in contained startup failure, and prove strict connection or tool-registration rejection still closes the client.
 
 The Node 24 consumer acceptance uses the actual built `dsh run` command with a fresh DSH home and an authenticated private GitHub source pinned to the pull request's exact head SHA. The test packs the current repository Plugin build with the same private-field removal and workspace-dependency pinning used for publication, serves its packument and tarball from a job-local npm registry, and directs the Git package's ordinary scoped npm resolution there. That repository package obtains `dsh-plugin-prepare` from the simulated published dependency, installs its other pinned runtime and development dependencies, type-checks and bundles TypeScript during `prepack`, prepares a skill plus a stdio MCP server and `dsh.entry`, exposes the skill and MCP schema in the first real model request, executes the MCP tool, and lets the compiled Cordis entry append a second marker to the result observed in the following request. Registry and cache assertions require npm resolution to reach the simulated publication, source files to be absent from the packed installation, and both built modules, their installed dependency, copied assets, and generated wrapper to be present.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
index c258728637..aff34d4485 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
@@ -16,13 +16,13 @@
 
 包自行负责其 NPM 依赖和构建工具链。它声明已发布的 `@deepseek-ai/dsh-repository-plugin` 包以取得 `dsh-plugin-prepare` 可执行文件。`scripts.prepack` 是由包作者编写的非空命令，必须调用该依赖提供的辅助程序，但可以先运行 `tsc`、`tsdown` 或其他任意构建。DSH 不会注入辅助程序，也不会解析该 shell 程序或编译 repository 源码。辅助程序会在前序构建之后校验元数据，要求已配置入口解析到 `.dsh-plugin` 内的文件，校验并复制已声明的静态资源，再写入已准备的 `dsh-plugin.mjs` 包装层。已安装包必须保留包含该辅助命令的 `prepack` 声明；依赖、包装层或构建输出缺失会在缓存 generation 可用前导致失败。
 
-生成的包装层先挂载 DSH 自有的静态运行时来处理 skill 和 MCP 定义，再动态导入显式入口、解包其导出并将其挂载为子级。两个子级都必须进入 Cordis `ACTIVE`；无法满足的 `inject` 或启动异常会拒绝 repository Loader 事务，而不会提交未激活的 generation。Loader 移除、替换失败和父级 dispose（资源释放）会一并撤销入口、skill 提供方、MCP client 及其 effect。
+生成的包装层先挂载 DSH 自有的静态运行时来处理 skill 和 MCP 定义，再动态导入显式入口、解包其导出并将其挂载为子级。包装层会静态声明已准备 manifest（元数据清单）所隐含的依赖；入口模块的额外 `inject` 只有在挂载时才会被发现，并且此时必须已存在于宿主组合中。两个子级都必须进入 Cordis `ACTIVE`；无法满足的 `inject` 或启动异常会拒绝 repository Loader 事务，而不会提交未激活的 generation。Loader 移除、替换失败和父级 dispose（资源释放）会一并撤销入口、skill 提供方、MCP client 及其 effect。
 
-`dsh-mcp-client` 会在插件应用期间完成其初始连接和工具同步 promise。其入口必须是 `async function`，而不是返回 Promise 的普通函数：Cordis 会把带 prototype 的普通函数识别为 constructor，不会把 constructor 返回的 Promise 当作启动工作。因此，有效 server 的工具会在父级 repository 包装层激活前、一次性应用发起首个模型请求前就已存在。其 `failOnStartupError` 配置默认保留独立可选 server 的行为，同时允许 repository adapter 要求已声明 server 必须可用。Repository 转换出的 MCP client 会启用该模式，因此初始连接或发现失败会拒绝候选 generation，回滚仍会关闭 transport。
+`dsh-mcp-client` 会在插件应用期间完成其初始连接和工具同步 promise。其入口必须是 `async function`，而不是返回 Promise 的普通函数：Cordis 会把带 prototype 的普通函数识别为 constructor，不会把 constructor 返回的 Promise 当作启动工作。因此，有效 server 的工具会在父级 repository 包装层激活前、一次性应用发起首个模型请求前就已存在。其 `failOnStartupError` 配置默认保留独立可选 server 的行为，同时允许 repository adapter 要求已声明 server 必须可用。Repository 转换出的 MCP client 会启用该模式，因此初始连接、发现或工具注册失败会拒绝候选 generation，回滚仍会关闭 transport。
 
 ## 信任边界
 
-精确 ref、源路径包含约束、清除名称符合凭据模式的环境变量、已准备的 manifest（元数据清单）和不可变缓存键，可以保护身份与组合完整性；它们不会为可执行包输入提供沙箱隔离。Repository 生命周期脚本、传递性 NPM 依赖、已编译入口和 spawn 的 MCP server 可以行使 DSH 进程可用的权限，以及它们所获 Cordis 服务授予的权限。因此，用户必须信任所选仓库，应当固定不可变 ref，并只授予 Git 获取源码所需的最小只读凭据。
+精确 ref、源路径包含约束、清除名称符合凭据模式的环境变量、已准备的 manifest 和不可变缓存键，可以保护身份与组合完整性；它们不会为可执行包输入提供沙箱隔离。Repository 生命周期脚本、传递性 NPM 依赖、已编译入口和 spawn 的 MCP server 可以行使 DSH 进程可用的权限，以及它们所获 Cordis 服务授予的权限。因此，用户必须信任所选仓库，应当固定不可变 ref，并只授予 Git 获取源码所需的最小只读凭据。
 
 模型可见行为仍由所属 DSH seam 管理。repository 入口可以注册工具、提示词段落、策略、命令、agent（智能体）或其他 effect，但任何进入模型请求的内容仍须具有对应的 DSH 日志表示和生命周期清理。repository 格式授予代码加载能力；它不会削弱这些服务契约。
 
@@ -41,11 +41,11 @@
 - TypeScript DSH 插件可以存放在 GitHub 仓库中，安装普通 NPM 依赖，在 `prepack` 期间完成编译，并在无需把插件包发布到 NPM 的情况下运行。
 - 仅含静态贡献的 repository 包仍然有效，并保留无 import 包装层；添加 `dsh.entry` 会使该包选择启用运行时代码导入。
 - 包构建、依赖安装、入口导入、所需服务未满足或插件启动失败，都会阻止候选 generation 替换最后一个可用配置。
-- 初始 MCP 连接可能延长应用启动时间；repository 声明的 server 不可用时，该候选 generation 无法激活。
+- 初始 MCP 同步可能因 MCP SDK 的单次请求超时而延长应用启动时间；repository 声明的 server 不可用或无法发布完整工具 generation 时，该候选 generation 无法激活。
 - Repository 代码获得宿主权限，因此源码评审和锁定不可变 ref 是运行安全要求，而不是可选加固措施。
 
 ## 测试
 
-repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，保留选择收束连接失败的能力，并证明严格启动拒绝仍会关闭 client。
+repository 格式测试通过真实 Loader 准备并挂载使用 default export 的代码入口，观察入口自有服务，移除 Loader 配置项，再观察清理；测试还保留针对 skill／MCP 准备、路径包含约束、包损坏、等待服务和回滚的覆盖。MCP 生命周期测试要求 `apply` 只在初始工具发布后完成，保留可选择启用的启动失败收束行为，并证明严格连接拒绝或工具注册拒绝仍会关闭 client。
 
 Node 24 消费方验收使用实际构建的 `dsh run` 命令、全新 DSH 主目录，以及锁定到 PR（Pull Request）的精确 head SHA 且经过认证的私有 GitHub 源。测试会采用发布时相同的移除 `private` 字段和固定 workspace 依赖版本流程，对当前 repository 插件构建进行打包；再由作业本地 NPM 注册表提供其 `packument` 与 tarball，并把 Git 包的常规 scoped NPM 解析指向该注册表。该 repository 包从模拟发布的依赖取得 `dsh-plugin-prepare`，安装其他固定版本的运行时依赖与开发依赖，在 `prepack` 期间对 TypeScript 进行类型检查和打包，准备一个 skill、一个 stdio MCP server 及 `dsh.entry`，在首个真实模型请求中暴露 skill 与 MCP schema，执行 MCP 工具，并让已编译 Cordis 入口向结果追加第二个标记，供后续请求观察。注册表与缓存断言要求 NPM 解析必须命中模拟发布，打包安装中不存在源码文件，同时必须存在两个已构建模块、其已安装依赖、复制资源和生成包装层。
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 82f8534ad2..34ea4a7fbd 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -988,7 +988,7 @@ export interface StdioConfig {
   cwd: string
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
-  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  /** Fail plugin activation when the initial connection or tool synchronization fails. */
   failOnStartupError: boolean
 }
 
@@ -1008,7 +1008,7 @@ export interface StreamableHttpConfig {
   headers: Record<string, string>
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
-  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  /** Fail plugin activation when the initial connection or tool synchronization fails. */
   failOnStartupError: boolean
 }
 ```
diff --git a/packages/mcp/mcp-client/README.i18n.yaml b/packages/mcp/mcp-client/README.i18n.yaml
index 2d47705a0a..de8c3e8cd1 100644
--- a/packages/mcp/mcp-client/README.i18n.yaml
+++ b/packages/mcp/mcp-client/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/mcp/mcp-client/README.md
-README.md: c87255917a2def0aef938af9f2c910b65d5a96d5
-README.zh.md: 6fd6df39d7c5034795021d41de57f8500cbfd1c5
+README.md: 76d1271f6f7a3e9c959bdcf5e969906f25563c56
+README.zh.md: 49de996863ab16a46cd7ee82b13624523dbb853f
diff --git a/packages/mcp/mcp-client/README.md b/packages/mcp/mcp-client/README.md
index c87255917a..76d1271f6f 100644
--- a/packages/mcp/mcp-client/README.md
+++ b/packages/mcp/mcp-client/README.md
@@ -44,7 +44,7 @@ The model sees `mcp__github__create_issue`, `mcp__web__search`, … — the same
 | `url` | http | yes | MCP server URL |
 | `headers` | http | no | Extra headers (e.g. auth tokens) |
 | `toolCallTimeoutMs` | both | no | Timeout per `callTool` invocation (default 60000) |
-| `failOnStartupError` | both | no | Reject plugin activation when the initial connection or tool discovery fails (default `false`) |
+| `failOnStartupError` | both | no | Reject plugin activation when initial connection or tool synchronization fails (default `false`) |
 
 ## Tool naming
 
@@ -57,8 +57,8 @@ Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`
 
 ## Behavior
 
-- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection or discovery failure is always logged; it rejects activation when `failOnStartupError` is true and otherwise activates with no tools.
-- Listens for `notifications/tools/list_changed` → re-syncs; a failed re-sync keeps the previous generation registered.
+- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection, discovery, or registration failure is always logged; it rejects activation when `failOnStartupError` is true and otherwise activates with no tools.
+- Listens for `notifications/tools/list_changed` → re-syncs; a fetch-phase failure keeps the previous generation registered, while a registration conflict rolls back the attempted generation and leaves no tools from that server.
 - Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support—the public name is never sent to the server.
 - Canonical success is `{ content: JsonValue[], structuredContent? }`; complete JSON MCP blocks survive for programmatic callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`.
 - Native/model rendering keeps the existing text projection: text blocks join with newlines while image, audio, resource, and unsupported blocks become placeholders.
@@ -103,6 +103,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumption surface and are deferred.
+- **Startup timeout is inherited from the MCP SDK** — DSH does not yet expose a connection/discovery timeout. Each initialize or paginated `tools/list` request uses the SDK's 60-second default, so an unresponsive server or cursor chain can delay both activation and teardown while the initial synchronization settles.
 - **Crash recovery is manual** — transport closure does not auto-reconnect; registered tools can remain visible but fail against the closed transport until an HMR reload or Host restart.
 - **Native non-text rendering is lossy** — image, audio, and resource payloads become placeholders in model context even though the execution-local canonical value preserves their JSON blocks. Richer Native multimedia projection is deferred.
 - **Unsupported MCP output schemas are not enforced** — `structuredContent` falls back to `JsonValue` when the advertised schema uses vocabulary outside the harness subset.
diff --git a/packages/mcp/mcp-client/README.zh.md b/packages/mcp/mcp-client/README.zh.md
index 6fd6df39d7..49de996863 100644
--- a/packages/mcp/mcp-client/README.zh.md
+++ b/packages/mcp/mcp-client/README.zh.md
@@ -44,7 +44,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 | `url` | http | 是 | MCP 服务器 URL |
 | `headers` | http | 否 | 额外标头（例如认证 token） |
 | `toolCallTimeoutMs` | 两者 | 否 | 每次 `callTool` 调用的超时（默认 60000） |
-| `failOnStartupError` | 两者 | 否 | 初始连接或工具发现失败时拒绝插件激活（默认 `false`） |
+| `failOnStartupError` | 两者 | 否 | 初始连接或工具同步失败时拒绝插件激活（默认 `false`） |
 
 ## 工具命名
 
@@ -57,8 +57,8 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 行为
 
-- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接或发现失败始终会记录日志；`failOnStartupError` 为 true 时拒绝激活，否则插件仍会激活但不注册工具。
-- 监听 `notifications/tools/list_changed` → 重新同步；同步失败时保留上一世代的注册。
+- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接、发现或注册失败始终会记录日志；`failOnStartupError` 为 true 时拒绝激活，否则插件仍会激活但不注册工具。
+- 监听 `notifications/tools/list_changed` → 重新同步；获取阶段失败时保留上一世代的注册，注册冲突则会回滚本次尝试的世代，并且不保留该服务器的任何工具。
 - 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
 - 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
 - Native／模型渲染保留现有文本投影：文本块以换行连接，图片、音频、资源和不受支持的块会变成占位符。
@@ -103,6 +103,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 ## 已知限制与暂缓事项
 
 - **只桥接 MCP 的工具能力**：资源和提示词没有 harness 消费接口，暂缓实现。
+- **启动超时继承自 MCP SDK**：DSH 尚未公开连接／发现超时。每次 initialize 请求或分页 `tools/list` 请求都使用 SDK 默认的 60 秒，因此在初始同步完成期间，无响应的 server 或 cursor chain 可能同时延迟激活与 teardown。
 - **崩溃恢复需要手动触发**：传输关闭后不会自动重新连接；已注册工具可能仍然可见，但会因传输已关闭而调用失败，直到 HMR 重载或重启 Host。
 - **Native 非文本渲染有损**：图片、音频与资源载荷在模型上下文中会变成占位符，即使执行局部的规范值保留了其 JSON 块。更丰富的 Native 多媒体投影暂缓实现。
 - **不强制执行不受支持的 MCP 输出 schema**：已声明 schema 使用 harness 子集之外的词汇时，`structuredContent` 会回退到 `JsonValue`。
diff --git a/packages/mcp/mcp-client/src/index.ts b/packages/mcp/mcp-client/src/index.ts
index 348003be52..0fe7dd9de3 100644
--- a/packages/mcp/mcp-client/src/index.ts
+++ b/packages/mcp/mcp-client/src/index.ts
@@ -72,7 +72,7 @@ export interface StdioConfig {
   cwd: string
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
-  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  /** Fail plugin activation when the initial connection or tool synchronization fails. */
   failOnStartupError: boolean
 }
 
@@ -92,7 +92,7 @@ export interface StreamableHttpConfig {
   headers: Record<string, string>
   /** Per-tool-call timeout in milliseconds. */
   toolCallTimeoutMs: number
-  /** Fail plugin activation when the initial connection or tool discovery fails. */
+  /** Fail plugin activation when the initial connection or tool synchronization fails. */
   failOnStartupError: boolean
 }
 
@@ -155,6 +155,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   )
 
   const opts = {
+    registrationFailure: 'contain' as const,
     serverName: config.serverName,
     toolCallTimeoutMs: config.toolCallTimeoutMs,
   }
@@ -166,7 +167,10 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   const ready = (async () => {
     await client.connect(transport)
 
-    let disposers = await syncTools(client, ctx, opts, new Map())
+    let disposers = await syncTools(client, ctx, {
+      ...opts,
+      registrationFailure: config.failOnStartupError ? 'throw' : 'contain',
+    }, new Map())
 
     client.setNotificationHandler(
       ToolListChangedNotificationSchema,
@@ -184,7 +188,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
 
     return { getDisposers: () => disposers }
   })().catch((error: unknown) => {
-    ctx.logger.error(`mcp-client(${config.serverName}): failed to connect: ${String(error)}`)
+    ctx.logger.error(`mcp-client(${config.serverName}): startup failed: ${String(error)}`)
     return { getDisposers: () => new Map<string, () => void>(), error }
   })
 
@@ -196,6 +200,6 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
 
   const outcome = await ready
   if ('error' in outcome && config.failOnStartupError) {
-    throw new Error(`mcp-client(${config.serverName}): initial connection or tool discovery failed`, { cause: outcome.error })
+    throw new Error(`mcp-client(${config.serverName}): initial connection or tool synchronization failed`, { cause: outcome.error })
   }
 }
diff --git a/packages/mcp/mcp-client/src/tools.ts b/packages/mcp/mcp-client/src/tools.ts
index 49e023ca4d..28c2a66319 100644
--- a/packages/mcp/mcp-client/src/tools.ts
+++ b/packages/mcp/mcp-client/src/tools.ts
@@ -23,6 +23,8 @@ import type { JsonSchemaNode, JsonValue } from '@deepseek-ai/dsh-tools'
 
 /** Resolved options relevant to tool bridging. */
 export interface ToolBridgeOptions {
+  /** Whether a registry conflict is contained or rejects this synchronization. */
+  registrationFailure: 'contain' | 'throw'
   serverName: string
   toolCallTimeoutMs: number
 }
@@ -111,8 +113,9 @@ export function publicToolName(serverName: string, rawName: string): string {
  * 2. Swap: dispose the previous generation, register the new one. A registry
  *    conflict here can only mean a foreign registration squats on this
  *    server's `mcp__<serverName>__` namespace — the partial generation is
- *    rolled back (zero tools from this server), the error is logged, and an
- *    empty map is returned.
+ *    rolled back (zero tools from this server) and logged. Initial strict
+ *    synchronization may propagate the conflict so its parent transaction
+ *    rejects; ordinary clients and later re-syncs return an empty map.
  *
  * @param client - Connected MCP Client instance used to list and call tools.
  * @param ctx - Cordis context providing the `tools` service for registration.
@@ -164,6 +167,7 @@ export async function syncTools(
     // sees either the full generation or none of it — never a partial set.
     for (const dispose of disposers.values()) dispose()
     ctx.logger.error(`mcp-client(${opts.serverName}): tool registration failed, no tools registered: ${String(error)}`)
+    if (opts.registrationFailure === 'throw') throw error
     return new Map()
   }
   return disposers
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index b2444341f1..70c88ad660 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -229,7 +229,7 @@ describe('apply (plugin lifecycle)', () => {
     await expect(apply(ctx, {
       ...stdioConfig,
       failOnStartupError: true,
-    })).rejects.toThrow('initial connection or tool discovery failed')
+    })).rejects.toThrow('initial connection or tool synchronization failed')
 
     expect(mockListTools).not.toHaveBeenCalled()
     expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
@@ -237,6 +237,28 @@ describe('apply (plugin lifecycle)', () => {
     expect(mockClose).toHaveBeenCalled()
   })
 
+  it('rejects strict startup when the initial tool generation cannot be registered', async () => {
+    ctx.tools.register({
+      name: 'mcp__srv__remote',
+      description: 'Foreign squatter',
+      parameters: { type: 'object' },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value as string }],
+      },
+      execute: async () => 'foreign',
+    })
+
+    await expect(apply(ctx, {
+      ...stdioConfig,
+      failOnStartupError: true,
+    })).rejects.toThrow('initial connection or tool synchronization failed')
+
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+    await ctx.fiber.dispose()
+    expect(mockClose).toHaveBeenCalled()
+  })
+
   it('re-syncs tools on ToolListChanged notification', async () => {
     await apply(ctx, stdioConfig)
 
diff --git a/packages/mcp/mcp-client/tests/mcp-client.spec.ts b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
index b95251e7d3..d19e30b94b 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.spec.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
@@ -64,6 +64,7 @@ async function mountRegistry(): Promise<Context> {
 }
 
 const defaultOpts: ToolBridgeOptions = {
+  registrationFailure: 'contain',
   serverName: 'srv',
   toolCallTimeoutMs: 60_000,
 }
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index 770cf0fab0..9d7f305263 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 3a6478d5cca05684e80ce0854cb6e0b5d2f88bd4
-README.zh.md: 274d11c96cb61d4d9fa4b837433994248c94bff4
+README.md: 0df0680cef873d9f7078cb63d1c803e5c323f07c
+README.zh.md: 04e5f8f81ba1b3e788775e9deaff6bb0b6dd1a48
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 3a6478d5cc..0df0680cef 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -64,13 +64,13 @@ During exact Git installation, DSH's bundled pnpm installs the selected package
 
 ## Runtime composition
 
-Loading this package registers one effect-scoped Loader builtin. Each generated wrapper delegates its prepared static manifest to that builtin, then imports and mounts `dsh.entry` when declared. The entry is an ordinary Cordis child Plugin: its own `inject` gates activation, startup failures reject the repository generation, and all of its effects disappear on Loader removal or rollback. The runtime likewise validates every declared skill root as an existing in-package directory before mounting — a package whose generated outputs were dropped by `files`/`.npmignore` or damaged in cache fails instead of silently losing contributions. Repository skill roots mount as uniquely named `dsh-skill-local` providers with default project/user roots excluded and watching disabled; cached package generations are immutable.
+Loading this package registers one effect-scoped Loader builtin. Each generated wrapper delegates its prepared static manifest to that builtin, then imports and mounts `dsh.entry` when declared. The wrapper can statically gate only the `loader`, `skills`, and `tools` services implied by the prepared manifest; the entry's own `inject` is discovered when that child is mounted. The entry must reach `ACTIVE`, so a missing entry-only service or startup failure rejects the repository generation instead of committing an inert child, and all effects disappear on Loader removal or rollback. The runtime likewise validates every declared skill root as an existing in-package directory before mounting — a package whose generated outputs were dropped by `files`/`.npmignore` or damaged in cache fails instead of silently losing contributions. Repository skill roots mount as uniquely named `dsh-skill-local` providers with default project/user roots excluded and watching disabled; cached package generations are immutable.
 
 ## Common MCP format
 
 The `.mcp.json` root is `{ "mcpServers": { ... } }`. A stdio entry accepts only `type: "stdio"` (optional), `command`, `args`, and `env`; an HTTP entry accepts only `type: "http"`, `url`, and `headers`. String values support exact `${NAME}` process-environment expansion at Plugin load, and a missing name fails that load. HTTP URLs become the existing MCP client's `streamable-http` transport; stdio entries use the prepared package directory as `cwd`.
 
-Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle. Repository-declared servers enable its strict startup mode: Plugin activation waits for the initial connection and tool discovery, so the first model request observes a successful initial tool generation, while a network, child-process, or discovery failure rejects the candidate repository generation instead of silently activating without its declared tools.
+Unknown fields reject, including OAuth and `auth` objects. There is no `CLAUDE_PLUGIN_ROOT` expansion or compatibility layer. After translation, the existing `dsh-mcp-client` exclusively owns transport creation, connection diagnostics, tool synchronization, calls, and disconnect lifecycle. Repository-declared servers enable its strict startup mode: Plugin activation waits for the initial connection and tool synchronization, so the first model request observes a fully registered initial tool generation, while a network, child-process, discovery, or registration failure rejects the candidate repository generation instead of silently activating without its declared tools.
 
 ## Export shape
 
@@ -123,5 +123,6 @@ Stable registrations preserve the owning surface's normal prefix behavior. Loadi
 ## Known Limitations and Deferred Work
 
 - **No code sandbox** — `dsh.entry`, npm dependencies, and package lifecycle scripts execute with the DSH host's authority; repository trust is mandatory.
+- **Entry-only service dependencies are not pre-gated** — the generated wrapper cannot declare an entry module's `inject` before importing it. Any service beyond those implied by Skills or MCP must already exist when the wrapper mounts the entry, or that repository generation rejects.
 - **No MCP authentication protocol** — static headers may use environment expansion, but OAuth-bearing definitions reject and private-server login flows are not implemented here.
 - **Generated assets are immutable runtime input** — repository cache generations are not watched; source, ref, path, or configuration must select another prepared generation.
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 274d11c96c..04e5f8f81b 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -64,13 +64,13 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 ## 运行时组合
 
-加载本包会注册一个 effect-scoped Loader builtin。每个生成的包装层都把已准备的静态 manifest（元数据清单）委托给该 builtin，再在声明了 `dsh.entry` 时导入并挂载该入口。入口是普通的 Cordis 子插件：其自有 `inject` 会门控激活，启动失败会拒绝 repository generation，Loader 移除或回滚时，其所有 effect 都会消失。运行时同样会在挂载前校验每个声明的 skill 根都是包内实际存在的目录——生成输出因 `files`／`.npmignore` 被丢弃或在缓存中损坏的包会加载失败，而不是静默丢失贡献。Repository skill 根以唯一命名的 `dsh-skill-local` 提供方挂载，排除默认项目／用户根并禁用监视；缓存包 generation 是不可变的。
+加载本包会注册一个 effect-scoped Loader builtin。每个生成的包装层都把已准备的静态 manifest（元数据清单）委托给该 builtin，再在声明了 `dsh.entry` 时导入并挂载该入口。包装层只能静态门控已准备 manifest 所隐含的 `loader`、`skills` 与 `tools` 服务；入口自身的 `inject` 要到挂载该子级时才会发现。入口必须进入 `ACTIVE`，因此缺少入口专用服务或启动失败时，会拒绝 repository generation，而不会提交未激活的子级；Loader 移除或回滚时，所有 effect 都会消失。运行时同样会在挂载前校验每个声明的 skill 根都是包内实际存在的目录——生成输出因 `files`／`.npmignore` 被丢弃或在缓存中损坏的包会加载失败，而不是静默丢失贡献。Repository skill 根以唯一命名的 `dsh-skill-local` 提供方挂载，排除默认项目／用户根并禁用监视；缓存包 generation 是不可变的。
 
 ## 通用 MCP 格式
 
 `.mcp.json` 根对象是 `{ "mcpServers": { ... } }`。stdio 条目只接受可选的 `type: "stdio"`、`command`、`args` 和 `env`；HTTP 条目只接受 `type: "http"`、`url` 和 `headers`。字符串值在插件加载时支持严格的 `${NAME}` 进程环境变量展开；缺失变量会使该次加载失败。HTTP URL 映射到现有 MCP client 的 `streamable-http` transport；stdio 条目以已准备的包目录作为 `cwd`。
 
-未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期。Repository 声明的 server 会启用其严格启动模式：插件激活会等待初始连接与工具发现，因此首个模型请求会看到成功的初始工具 generation；网络、子进程或发现失败则会拒绝候选 repository generation，而不是在缺少已声明工具的情况下静默激活。
+未知字段会被拒绝，包括 OAuth 字段与 `auth` 对象。不提供 `CLAUDE_PLUGIN_ROOT` 展开或兼容层。完成格式转换后，现有 `dsh-mcp-client` 独占 transport 创建、连接诊断、工具同步、调用和断开生命周期。Repository 声明的 server 会启用其严格启动模式：插件激活会等待初始连接与工具同步，因此首个模型请求会看到已完整注册的初始工具 generation；网络、子进程、发现或注册失败则会拒绝候选 repository generation，而不是在缺少已声明工具的情况下静默激活。
 
 ## 导出形状
 
@@ -123,5 +123,6 @@ Namespace 插件：具名导出 `name`／`inject`／`apply`、准备阶段常量
 ## 已知限制与暂缓事项
 
 - **没有代码沙箱**：`dsh.entry`、NPM 依赖和包生命周期脚本以 DSH 宿主权限执行；必须信任该 repository。
+- **入口专用服务依赖不会预先门控**：生成的包装层无法在导入入口模块前声明其 `inject`。除 skill 或 MCP 隐含的服务外，其他任何服务在包装层挂载入口时都必须已经存在，否则该 repository generation 会被拒绝。
 - **没有 MCP 认证协议**：静态 header 可以使用环境变量展开，但带 OAuth 的定义会被拒绝，私有 server 登录流程不在此实现。
 - **生成资源是不可变运行时输入**：repository cache generation 不受监视；必须改变 source、ref、path 或配置才能选择另一份已准备 generation。
diff --git a/packages/self-modification/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
index 852e57b253..743a2fbf39 100644
--- a/packages/self-modification/repository-plugin/src/format.ts
+++ b/packages/self-modification/repository-plugin/src/format.ts
@@ -152,6 +152,7 @@ function wrapperSource(manifest: PreparedPluginManifest): string {
   return [
     '// Generated by dsh-plugin-prepare. Do not edit.',
     `const manifest = ${JSON.stringify(manifest)}`,
+    '// Value mirror: Cordis const enum FiberState.ACTIVE; keep aligned with dsh-repository-plugin source.ts.',
     'const FIBER_ACTIVE = 2',
     `export const name = ${JSON.stringify(manifest.name)}`,
     `export const inject = ${JSON.stringify(inject)}`,
diff --git a/packages/self-modification/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
index a85bb0467e..8460bc800b 100644
--- a/packages/self-modification/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -80,7 +80,11 @@ async function assertInstalledPackageMetadata(directory: string): Promise<void>
   }
   const result = installedPackageSchema.safeParse(value)
   if (!result.success) {
-    throw new Error(`installed DSH plugin package must declare a non-empty scripts.prepack that invokes ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:\n${z.prettifyError(result.error)}`)
+    throw new Error([
+      `installed DSH plugin package must declare a non-empty scripts.prepack that invokes ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:`,
+      z.prettifyError(result.error),
+      'Clear the matching repository cache generation before retrying the same source, or select a different exact source/ref/path after fixing the package.',
+    ].join('\n'))
   }
 }
 
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index b5abf6fbdd..3b8d587dbc 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -330,7 +330,7 @@ describe('prepared repository plugin Loader composition', () => {
     await ctx.plugin(RepositoryPlugin)
     await expect(ctx.loader.create({
       name: pathToFileURL(join(directory, RepositoryPlugin.PREPARED_ENTRY_FILENAME)).href,
-    })).rejects.toThrow('initial connection or tool discovery failed')
+    })).rejects.toThrow('initial connection or tool synchronization failed')
     expect(ctx.tools.schemas().some(tool => tool.name.startsWith('mcp__offline__'))).toBe(false)
     await ctx.fiber.dispose()
   })
@@ -593,6 +593,12 @@ describe('configured GitHub repository sources', () => {
           message: expect.stringContaining('must declare a non-empty scripts.prepack') as string,
         }) as Error,
       })
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, 'github:owner/repository#old&path:/.dsh-plugin'))
+      .rejects.toMatchObject({
+        cause: expect.objectContaining({
+          message: expect.stringContaining('Clear the matching repository cache generation') as string,
+        }) as Error,
+      })
     await ctx.fiber.dispose()
   })
 

From e00ec8e2aa023e58f637a3891c1a8d9f8b2db43c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:57:56 +0800
Subject: [PATCH 446/516] test(repository-plugin): refresh prepared wrapper
 fixture

---
 .../tests/fixtures/repository-plugin/dsh-plugin.mjs              | 1 +
 1 file changed, 1 insertion(+)

diff --git a/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs b/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
index ce61e58973..29aa97c5ec 100644
--- a/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
+++ b/examples/headless-agent/tests/fixtures/repository-plugin/dsh-plugin.mjs
@@ -1,5 +1,6 @@
 // Generated by dsh-plugin-prepare. Do not edit.
 const manifest = {"name":"headless-repository-fixture","skills":["dsh-plugin-assets/skills/0"]}
+// Value mirror: Cordis const enum FiberState.ACTIVE; keep aligned with dsh-repository-plugin source.ts.
 const FIBER_ACTIVE = 2
 export const name = "headless-repository-fixture"
 export const inject = ["loader","skills"]

From 690fc798a516fedaaee8b458619e0ed6f4bdf6d2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 01:14:37 +0800
Subject: [PATCH 447/516] test(repository-plugin): isolate simulated npm
 release

---
 apps/cli/tests/github-repository-plugin.built.e2e.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index e1386e2bfe..139dc8208f 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -182,6 +182,11 @@ describe.skipIf(!enabled)('dsh run GitHub repository Plugin installation', () =>
           DEEPSEEK_API_KEY: apiKey,
           DEEPSEEK_BASE_URL: server.baseURL,
           NPM_CONFIG_USERCONFIG: npmrc,
+          // A warm runner cache could satisfy the exact tarball without
+          // contacting this test's registry, which would stop proving the
+          // unpublished package was installed through the simulated release.
+          PNPM_CONFIG_CACHE_DIR: join(home, 'pnpm-cache'),
+          PNPM_CONFIG_STORE_DIR: join(home, 'pnpm-store'),
           PATH: process.env.PATH === undefined ? hostBin : `${hostBin}${delimiter}${process.env.PATH}`,
         },
       })

From 8d76ddaa6c5f02ce39647f2fb5808d97228b911e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 11:15:36 +0800
Subject: [PATCH 448/516] fix(repository-plugin): enforce published prepare
 dependency

---
 ...0-config-only-repository-plugins.i18n.yaml |  4 +--
 ...26-07-30-config-only-repository-plugins.md |  4 +--
 ...07-30-config-only-repository-plugins.zh.md |  4 +--
 packages/mcp/mcp-client/tests/apply.spec.ts   |  2 +-
 .../repository-plugin/README.i18n.yaml        |  4 +--
 .../repository-plugin/README.md               |  2 +-
 .../repository-plugin/README.zh.md            |  2 +-
 .../repository-plugin/src/format.ts           |  5 +++
 .../repository-plugin/src/index.ts            |  1 +
 .../repository-plugin/src/source.ts           |  6 +++-
 .../tests/repository-plugin.spec.ts           | 33 +++++++++++++++++++
 11 files changed, 55 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
index cee151c1ed..74992551f8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.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 .agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
-2026-07-30-config-only-repository-plugins.md: 1564a847ccef877a6cc91827e195aa04711d09ce
-2026-07-30-config-only-repository-plugins.zh.md: 8e8de1e6edc356c9bb9ab55f01b6cce7608358e7
+2026-07-30-config-only-repository-plugins.md: 35327a30e03c51311f634e05ade209ab93ae0155
+2026-07-30-config-only-repository-plugins.zh.md: e2ef728cadf33f12da0e96a71fd984b694f497b0
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
index 1564a847cc..35327a30e0 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md
@@ -12,13 +12,13 @@ A standalone `dsh` user has no developer-owned SDK project whose `package.json`,
 
 The shipped TUI and Web/headless `cordis.yml` trees contain an empty `repository-plugins` entry. A user changes only `$DSH_HOME/config.yaml`, replacing that entry's config with a `repositories` list. Each item uses `github:owner/repository#<ref>` plus an optional `&path:/.../.dsh-plugin`; omission selects `/.dsh-plugin`. An explicit ref is mandatory, paths are absolute within the repository and end in `.dsh-plugin`, and duplicate normalized specifiers reject before installation. There is no marketplace, discovery index, HTTPS URL vocabulary, or implicit latest generation.
 
-`@deepseek-ai/dsh-repository-plugin` validates and normalizes each source, then resolves it through the generic vendored [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md). The default cache is `$DSH_HOME/cache/repository-plugins`; `cacheDir` is the explicit deployment override. Bundled pnpm selects the configured repository subpackage, installs its dependencies, runs its package-authored `prepack` and the host preparation helper, and atomically publishes the exact specifier. The DSH host imports the generated `dsh-plugin.mjs` wrapper and mounts it as a child fiber; that wrapper composes static skill and MCP owners plus an explicit trusted Cordis entry when declared.
+`@deepseek-ai/dsh-repository-plugin` validates and normalizes each source, then resolves it through the generic vendored [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md). The default cache is `$DSH_HOME/cache/repository-plugins`; `cacheDir` is the explicit deployment override. Bundled pnpm selects the configured repository subpackage, installs its dependencies, runs its package-authored `prepack`, and atomically publishes the exact specifier. The selected package's direct development dependency on `@deepseek-ai/dsh-repository-plugin` supplies `dsh-plugin-prepare` through package-local `node_modules/.bin`; the lifecycle invokes it after any package-owned build. The DSH host imports the generated `dsh-plugin.mjs` wrapper and mounts it as a child fiber; that wrapper composes static skill and MCP owners plus an explicit trusted Cordis entry when declared.
 
 ## Live update and failure
 
 `dsh-app-boot` mounts the root Include through one helper that retains its exact Loader `Entry`. The TUI and Web register `$DSH_HOME/config.yaml` through Cordis HMR; headless reads the same file at startup without retaining a watcher. A watcher update rebuilds the Include patch list as immutable app-owned patches followed by the newly parsed personal patches, so Web-generated port, session-root, trust, and frontend values survive every personal edit unless a later personal patch deliberately replaces that row.
 
-Cordis serializes and coalesces exact-path changes. Include and Loader reconcile a candidate transactionally: success commits the new source list, while fetch, preparation, wrapper import, format, or child-Plugin failure rejects the candidate and retains or restores the last good tree. HMR normalizes the caught value to `Error`, logs it, and broadcasts the parallel `hmr/config-update-failed(filename, error)` event; observer failures cannot break refresh processing. MCP transport connection failure remains the existing MCP client's contained successful-Plugin/no-tools result and therefore is not reclassified as a config-update failure.
+Cordis serializes and coalesces exact-path changes. Include and Loader reconcile a candidate transactionally: success commits the new source list, while fetch, preparation, wrapper import, format, or child-Plugin failure rejects the candidate and retains or restores the last good tree. HMR normalizes the caught value to `Error`, logs it, and broadcasts the parallel `hmr/config-update-failed(filename, error)` event; observer failures cannot break refresh processing. Repository MCP servers use strict startup, so an initial connection, discovery, or tool-registration failure rejects the candidate and becomes a config-update failure; non-strict standalone MCP clients retain their contained successful-Plugin/no-tools behavior.
 
 An identical specifier permanently reuses its cache generation. HMR watches configuration, not cached repository code; the user changes the ref, path, or source list to select another generation.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
index 8e8de1e6ed..e2ef728cad 100644
--- a/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.zh.md
@@ -12,13 +12,13 @@ Status: implemented
 
 已交付的 TUI 和 Web／无头 `cordis.yml` 配置树包含一个空的 `repository-plugins` 配置项。用户只需修改 `$DSH_HOME/config.yaml`，用 `repositories` 列表替换该配置项的配置。每一项采用 `github:owner/repository#<ref>`，并可追加 `&path:/.../.dsh-plugin`；省略时选择 `/.dsh-plugin`。必须显式指定 ref；路径是仓库内的绝对路径，并以 `.dsh-plugin` 结尾；重复的规范化说明符在安装前即被拒绝。不提供插件市场、发现索引、HTTPS URL 词汇或隐式的最新版本。
 
-`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择已配置的 repository 子包，安装其依赖，运行包所定义的 `prepack` 与宿主准备辅助程序，并原子发布该精确说明符。DSH 宿主会导入生成的 `dsh-plugin.mjs` 包装层并将其挂载为子 fiber；该包装层组合静态 skill（技能）与 MCP 所有者，并在声明时组合显式的受信任 Cordis 入口。
+`@deepseek-ai/dsh-repository-plugin` 校验并规范化每个源，再通过 vendor 中的通用 [`RepositoryCache`](../architecture/2026-07-30-package-manager-native-repository-cache.md) 解析。默认缓存位于 `$DSH_HOME/cache/repository-plugins`；`cacheDir` 是显式的部署覆盖项。随应用提供的 pnpm 选择已配置的 repository 子包，安装其依赖，运行包所定义的 `prepack`，并原子发布该精确说明符。所选包对 `@deepseek-ai/dsh-repository-plugin` 的直接开发依赖通过包内 `node_modules/.bin` 提供 `dsh-plugin-prepare`；该生命周期会在任何包自有构建完成后调用它。DSH 宿主会导入生成的 `dsh-plugin.mjs` 包装层并将其挂载为子 fiber；该包装层组合静态 skill（技能）与 MCP 所有者，并在声明时组合显式的受信任 Cordis 入口。
 
 ## 实时更新与失败
 
 `dsh-app-boot` 通过一个辅助函数挂载根 Include，并保留其确切的 Loader `Entry`。TUI 和 Web 通过 Cordis HMR（热模块替换）注册 `$DSH_HOME/config.yaml`；无头界面在启动时读取同一文件，但不保留监视器。监视器更新会重新构建 Include 补丁列表，先放置不可变的应用自有补丁，再放置新解析的个人补丁。因此，Web 生成的端口、会话根目录、信任和前端值会在每次个人编辑后保留，除非后续个人补丁有意替换相应配置项。
 
-Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader 以事务方式协调候选配置：成功时提交新源列表；拉取、准备、包装模块导入、格式或子插件失败时拒绝候选配置，并保留或恢复最后一个可用树。HMR 会把捕获的值规范化为 `Error`，记录错误，并广播并行的 `hmr/config-update-failed(filename, error)` 事件；观察者失败不会中断刷新处理。MCP 传输连接失败仍沿用现有 MCP 客户端所收束的「插件成功加载但无工具」结果，因此不会被重新分类为配置更新失败。
+Cordis 会串行处理并合并该确切路径上的变更。Include 与 Loader 以事务方式协调候选配置：成功时提交新源列表；拉取、准备、包装模块导入、格式或子插件失败时拒绝候选配置，并保留或恢复最后一个可用树。HMR 会把捕获的值规范化为 `Error`，记录错误，并广播并行的 `hmr/config-update-failed(filename, error)` 事件；观察者失败不会中断刷新处理。Repository MCP 服务器采用严格启动，因此初始连接、发现或工具注册失败会拒绝候选配置，并构成配置更新失败；非严格的独立 MCP 客户端仍保留其所收束的「插件成功加载但无工具」行为。
 
 相同说明符会永久复用同一个缓存版本。HMR 监视配置，而非已缓存的仓库代码；用户必须改变 ref、路径或源列表，才能选择另一个版本。
 
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index 70c88ad660..44b3e272f4 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -209,7 +209,7 @@ describe('apply (plugin lifecycle)', () => {
     expect(other.tools.get('mcp__srv__remote')).toBeDefined()
   })
 
-  it('logs error and registers no tools when connect fails; dispose is a no-op', async () => {
+  it('logs error and registers no tools when connect fails; dispose closes the client', async () => {
     mockConnect.mockRejectedValue(new Error('connection refused'))
 
     await apply(ctx, stdioConfig)
diff --git a/packages/self-modification/repository-plugin/README.i18n.yaml b/packages/self-modification/repository-plugin/README.i18n.yaml
index 9d7f305263..e083b8abf3 100644
--- a/packages/self-modification/repository-plugin/README.i18n.yaml
+++ b/packages/self-modification/repository-plugin/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/self-modification/repository-plugin/README.md
-README.md: 0df0680cef873d9f7078cb63d1c803e5c323f07c
-README.zh.md: 04e5f8f81ba1b3e788775e9deaff6bb0b6dd1a48
+README.md: 666f00e02b9ab33bff348df6b4ff90e3f3bfecc7
+README.zh.md: 62f467dd9ccac904ea2a216242f5475c29734a86
diff --git a/packages/self-modification/repository-plugin/README.md b/packages/self-modification/repository-plugin/README.md
index 0df0680cef..666f00e02b 100644
--- a/packages/self-modification/repository-plugin/README.md
+++ b/packages/self-modification/repository-plugin/README.md
@@ -60,7 +60,7 @@ Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A v
 
 ## Preparation
 
-During exact Git installation, DSH's bundled pnpm installs the selected package from its own manifest. A transaction-owned `pnpm` wrapper reinvokes the same pinned pnpm with `--ignore-workspace`, so an enclosing workspace lockfile cannot suppress dependencies declared only by the selected `.dsh-plugin` package. The required `prepack` lifecycle runs after that dependency installation and before the selected subdirectory is packed; its ordinary `node_modules/.bin` lookup obtains `dsh-plugin-prepare` from the declared `@deepseek-ai/dsh-repository-plugin` dependency. That package marks its Cordis/DSH runtime peers optional so using the executable alone does not install the runtime graph. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained a `prepack` declaration containing the helper command. Failure to resolve the published helper, install dependencies, build, or prepare fails before a cache generation is published. Rationale: [npm-backed Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md).
+During exact Git installation, DSH's bundled pnpm installs the selected package from its own manifest. A transaction-owned `pnpm` wrapper reinvokes the same pinned pnpm with `--ignore-workspace`, so an enclosing workspace lockfile cannot suppress dependencies declared only by the selected `.dsh-plugin` package. The required `prepack` lifecycle runs after that dependency installation and before the selected subdirectory is packed; its ordinary `node_modules/.bin` lookup obtains `dsh-plugin-prepare` from the declared direct development dependency on `@deepseek-ai/dsh-repository-plugin`. That package marks its Cordis/DSH runtime peers optional so using the executable alone does not install the runtime graph. Package-owned commands may build TypeScript or other source before invoking the helper. The helper validates `package.json#dsh`, verifies that the compiled entry is an in-package file, validates skill and MCP sources, copies static assets under `dsh-plugin-assets`, and writes `dsh-plugin.mjs`. Before importing that wrapper, DSH revalidates that the installed package retained both the direct development dependency and a `prepack` declaration containing the helper command. Failure to resolve the published helper, install dependencies, build, or prepare fails before a cache generation is published. Rationale: [npm-backed Git source preparation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md).
 
 ## Runtime composition
 
diff --git a/packages/self-modification/repository-plugin/README.zh.md b/packages/self-modification/repository-plugin/README.zh.md
index 04e5f8f81b..62f467dd9c 100644
--- a/packages/self-modification/repository-plugin/README.zh.md
+++ b/packages/self-modification/repository-plugin/README.zh.md
@@ -60,7 +60,7 @@ Git 传输使用宿主的常规 Git 认证。公共仓库无需凭据；私有
 
 ## 准备阶段
 
-安装精确指定的 Git 源时，DSH 随附的 pnpm 会按所选包自身的 manifest 安装。由事务持有的 `pnpm` 包装脚本会以 `--ignore-workspace` 重新调用同一份锁定的 pnpm，因此外层 workspace lockfile 无法抑制仅由所选 `.dsh-plugin` 包声明的依赖。必需的 `prepack` 生命周期在该依赖安装完成后、选定子目录打包前运行；其常规 `node_modules/.bin` 查找会从已声明的 `@deepseek-ai/dsh-repository-plugin` 依赖取得 `dsh-plugin-prepare`。该包把 Cordis／DSH 运行时对等依赖（peer dependency）标为可选，因此单独使用该可执行文件不会安装运行时依赖图。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍保留包含该辅助命令的 `prepack` 声明。无法解析已发布的辅助程序，或安装依赖、构建或准备失败时，流程会在发布缓存 generation 前失败。设计依据见[基于 NPM 的 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md)。
+安装精确指定的 Git 源时，DSH 随附的 pnpm 会按所选包自身的 manifest 安装。由事务持有的 `pnpm` 包装脚本会以 `--ignore-workspace` 重新调用同一份锁定的 pnpm，因此外层 workspace lockfile 无法抑制仅由所选 `.dsh-plugin` 包声明的依赖。必需的 `prepack` 生命周期在该依赖安装完成后、选定子目录打包前运行；其常规 `node_modules/.bin` 查找会从直接声明的 `@deepseek-ai/dsh-repository-plugin` 开发依赖中取得 `dsh-plugin-prepare`。该包把 Cordis／DSH 运行时对等依赖（peer dependency）标为可选，因此单独使用该可执行文件不会安装运行时依赖图。包自有命令可以在调用辅助程序前构建 TypeScript 或其他源码。辅助程序会校验 `package.json#dsh`，确认已编译入口是包内文件，校验 skill 与 MCP 源，把静态资源复制到 `dsh-plugin-assets`，并写入 `dsh-plugin.mjs`。导入该包装层前，DSH 会重新校验已安装包是否仍同时保留该直接开发依赖，以及包含该辅助命令的 `prepack` 声明。无法解析已发布的辅助程序，或安装依赖、构建或准备失败时，流程会在发布缓存 generation 前失败。设计依据见[基于 NPM 的 Git 源准备 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md)。
 
 ## 运行时组合
 
diff --git a/packages/self-modification/repository-plugin/src/format.ts b/packages/self-modification/repository-plugin/src/format.ts
index 743a2fbf39..7af948595d 100644
--- a/packages/self-modification/repository-plugin/src/format.ts
+++ b/packages/self-modification/repository-plugin/src/format.ts
@@ -16,6 +16,8 @@ export const PREPARED_ASSET_DIRECTORY = 'dsh-plugin-assets'
 export const REPOSITORY_PLUGIN_BUILTIN = 'dsh-repository-plugin'
 /** Dependency-provided command that repository package `prepack` lifecycles must invoke. */
 export const REPOSITORY_PLUGIN_PREPARE_COMMAND = 'dsh-plugin-prepare'
+/** Published package whose direct development dependency supplies the prepare command. */
+export const REPOSITORY_PLUGIN_PACKAGE_NAME = '@deepseek-ai/dsh-repository-plugin'
 
 /**
  * Whether a package lifecycle declaration names the preparation dependency's helper.
@@ -40,6 +42,9 @@ const sourceMetadataSchema = z.object({
 })
 const sourcePackageSchema = z.looseObject({
   name: z.string().min(1),
+  devDependencies: z.looseObject({
+    [REPOSITORY_PLUGIN_PACKAGE_NAME]: z.string().min(1),
+  }),
   scripts: z.looseObject({
     prepack: prepackSchema,
   }),
diff --git a/packages/self-modification/repository-plugin/src/index.ts b/packages/self-modification/repository-plugin/src/index.ts
index 8026199c16..1251fe45e2 100644
--- a/packages/self-modification/repository-plugin/src/index.ts
+++ b/packages/self-modification/repository-plugin/src/index.ts
@@ -29,6 +29,7 @@ export {
   PREPARED_ASSET_DIRECTORY,
   PREPARED_ENTRY_FILENAME,
   REPOSITORY_PLUGIN_BUILTIN,
+  REPOSITORY_PLUGIN_PACKAGE_NAME,
   REPOSITORY_PLUGIN_PREPARE_COMMAND,
   prepareDshPlugin,
   type PreparedPluginManifest,
diff --git a/packages/self-modification/repository-plugin/src/source.ts b/packages/self-modification/repository-plugin/src/source.ts
index 8460bc800b..536025d6d7 100644
--- a/packages/self-modification/repository-plugin/src/source.ts
+++ b/packages/self-modification/repository-plugin/src/source.ts
@@ -12,6 +12,7 @@ import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { z } from 'zod'
 import {
   PREPARED_ENTRY_FILENAME,
+  REPOSITORY_PLUGIN_PACKAGE_NAME,
   REPOSITORY_PLUGIN_PREPARE_COMMAND,
   hasRepositoryPrepareCommand,
 } from './format.ts'
@@ -29,6 +30,9 @@ export const DEFAULT_REPOSITORY_CACHE_DIRECTORY = 'repository-plugins'
 // resolvable point').
 const GITHUB_SOURCE_PATTERN = /^github:([^/\s#&]+)\/([^/\s#&]+)#([^\s#&]+)(?:&path:(\/[^\s&]+))?$/
 const installedPackageSchema = z.looseObject({
+  devDependencies: z.looseObject({
+    [REPOSITORY_PLUGIN_PACKAGE_NAME]: z.string().min(1),
+  }),
   scripts: z.looseObject({
     prepack: z.string().min(1).refine(
       hasRepositoryPrepareCommand,
@@ -81,7 +85,7 @@ async function assertInstalledPackageMetadata(directory: string): Promise<void>
   const result = installedPackageSchema.safeParse(value)
   if (!result.success) {
     throw new Error([
-      `installed DSH plugin package must declare a non-empty scripts.prepack that invokes ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}:`,
+      `installed DSH plugin package must declare a non-empty scripts.prepack that invokes ${JSON.stringify(REPOSITORY_PLUGIN_PREPARE_COMMAND)}, and declare ${JSON.stringify(REPOSITORY_PLUGIN_PACKAGE_NAME)} in devDependencies:`,
       z.prettifyError(result.error),
       'Clear the matching repository cache generation before retrying the same source, or select a different exact source/ref/path after fixing the package.',
     ].join('\n'))
diff --git a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
index 3b8d587dbc..086616f2f9 100644
--- a/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
+++ b/packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts
@@ -32,12 +32,16 @@ async function writePlugin(
   name: string,
   dsh: Record<string, unknown>,
   prepack = RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND,
+  devDependencies: Record<string, string> = {
+    [RepositoryPlugin.REPOSITORY_PLUGIN_PACKAGE_NAME]: '0.0.1',
+  },
 ): Promise<string> {
   const directory = join(root, '.dsh-plugin')
   await mkdir(directory, { recursive: true })
   await writeFile(join(directory, 'package.json'), `${JSON.stringify({
     name,
     version: '0.0.0',
+    devDependencies,
     scripts: { prepack },
     dsh,
   }, undefined, 2)}\n`)
@@ -149,6 +153,17 @@ describe('dsh-plugin-prepare', () => {
     )
     await expect(RepositoryPlugin.prepareDshPlugin(skippedPrepare)).rejects.toThrow('must invoke dsh-plugin-prepare')
 
+    const undeclaredPrepareRoot = await temporaryDirectory('undeclared-prepare-dependency')
+    const undeclaredPrepare = await writePlugin(
+      undeclaredPrepareRoot,
+      'undeclared-prepare-dependency',
+      { skills: ['../skills'] },
+      RepositoryPlugin.REPOSITORY_PLUGIN_PREPARE_COMMAND,
+      {},
+    )
+    await expect(RepositoryPlugin.prepareDshPlugin(undeclaredPrepare))
+      .rejects.toThrow(RepositoryPlugin.REPOSITORY_PLUGIN_PACKAGE_NAME)
+
     const emptyRoot = await temporaryDirectory('empty-metadata')
     const empty = await writePlugin(emptyRoot, 'empty', {})
     await expect(RepositoryPlugin.prepareDshPlugin(empty)).rejects.toThrow('declare at least one skill root, mcpServers file, or compiled entry')
@@ -584,6 +599,7 @@ describe('configured GitHub repository sources', () => {
     const root = await temporaryDirectory('installed-lifecycle')
     await writeFile(join(root, 'package.json'), JSON.stringify({
       name: 'installed-lifecycle',
+      devDependencies: { [RepositoryPlugin.REPOSITORY_PLUGIN_PACKAGE_NAME]: '0.0.1' },
       scripts: { prepare: 'dsh-plugin-prepare' },
     }))
     const ctx = new Context()
@@ -606,6 +622,7 @@ describe('configured GitHub repository sources', () => {
     const root = await temporaryDirectory('installed-skipped-prepare')
     await writeFile(join(root, 'package.json'), JSON.stringify({
       name: 'installed-skipped-prepare',
+      devDependencies: { [RepositoryPlugin.REPOSITORY_PLUGIN_PACKAGE_NAME]: '0.0.1' },
       scripts: { prepack: 'npm run build' },
     }))
     const ctx = new Context()
@@ -618,6 +635,22 @@ describe('configured GitHub repository sources', () => {
     await ctx.fiber.dispose()
   })
 
+  it('rejects installed source without the declared prepare dependency', async () => {
+    const root = await temporaryDirectory('installed-missing-prepare-dependency')
+    await writeFile(join(root, 'package.json'), JSON.stringify({
+      name: 'installed-missing-prepare-dependency',
+      scripts: { prepack: 'dsh-plugin-prepare' },
+    }))
+    const ctx = new Context()
+    await expect(loadPreparedRepository(ctx, { resolve: async () => root }, 'github:owner/repository#ambient-helper&path:/.dsh-plugin'))
+      .rejects.toMatchObject({
+        cause: expect.objectContaining({
+          message: expect.stringContaining(`${JSON.stringify(RepositoryPlugin.REPOSITORY_PLUGIN_PACKAGE_NAME)} in devDependencies`) as string,
+        }) as Error,
+      })
+    await ctx.fiber.dispose()
+  })
+
   it('labels missing installed package metadata with its source', async () => {
     const root = await temporaryDirectory('missing-installed-metadata')
     const ctx = new Context()

From fc20194733b1af225567e2342fff84470de077ed Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 11:22:46 +0800
Subject: [PATCH 449/516] fix(repository-plugin): follow package regrouping

---
 ...-08-npm-backed-git-repository-plugin-preparation.i18n.yaml | 4 ++--
 ...2026-08-08-npm-backed-git-repository-plugin-preparation.md | 2 +-
 ...6-08-08-npm-backed-git-repository-plugin-preparation.zh.md | 2 +-
 apps/cli/tests/github-repository-plugin.built.e2e.ts          | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
index e1966105a3..f13bae898a 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.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 .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
-2026-08-08-npm-backed-git-repository-plugin-preparation.md: 9437043d007f5331f36f1c4cff1fe0a3e768b060
-2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md: 1f06f7372dc0d948906ec4441cb161d2d2ed69e5
+2026-08-08-npm-backed-git-repository-plugin-preparation.md: 958b932f82f4da3cf63aa911260411855e514409
+2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md: 4986c55787f291ba9e0d4594854c15eb3c892c72
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
index 9437043d00..958b932f82 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
@@ -45,4 +45,4 @@ The built-entry acceptance also creates an in-process npm registry. It stages th
 
 ## Testing
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` runs a package excluded from its source repository's root pnpm lockfile through a local Git subpath and requires relative `file:` dependencies to provide both its build command and `dsh-plugin-prepare`; it also proves that visible environment survives while credential-shaped variables are scrubbed. `packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and preparation output. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: simulated published helper package, job-local npm registry, fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
+`packages/boot/app-boot/tests/repository-cache.spec.ts` runs a package excluded from its source repository's root pnpm lockfile through a local Git subpath and requires relative `file:` dependencies to provide both its build command and `dsh-plugin-prepare`; it also proves that visible environment survives while credential-shaped variables are scrubbed. `packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts` pins helper-bearing `prepack` metadata and preparation output. `examples/headless-agent/tests/keyless-smoke.e2e.ts` keeps the checked-in prepared fixture on that source contract. `apps/cli/tests/github-repository-plugin.built.e2e.ts` is the product acceptance: simulated published helper package, job-local npm registry, fresh DSH home, exact authenticated private GitHub source, actual built `dsh run`, package-owned TypeScript build, real MCP execution, code-entry transformation, mock LLM request observation, and prepared cache inspection.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
index 1f06f7372d..4986c55787 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
@@ -45,4 +45,4 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库与 SHA 
 
 ## 测试
 
-`packages/ui/app-boot/tests/repository-cache.spec.ts` 会通过本地 Git 子路径运行一个未列入源仓库根 pnpm lockfile 的包，并要求相对 `file:` 依赖同时提供构建命令与 `dsh-plugin-prepare`；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/cordis/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据与准备输出。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：模拟发布的辅助程序包、作业本地 NPM 注册表、全新 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及已准备缓存检查。
+`packages/boot/app-boot/tests/repository-cache.spec.ts` 会通过本地 Git 子路径运行一个未列入源仓库根 pnpm lockfile 的包，并要求相对 `file:` 依赖同时提供构建命令与 `dsh-plugin-prepare`；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据与准备输出。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：模拟发布的辅助程序包、作业本地 NPM 注册表、全新 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及已准备缓存检查。
diff --git a/apps/cli/tests/github-repository-plugin.built.e2e.ts b/apps/cli/tests/github-repository-plugin.built.e2e.ts
index 139dc8208f..7bb4706dd7 100644
--- a/apps/cli/tests/github-repository-plugin.built.e2e.ts
+++ b/apps/cli/tests/github-repository-plugin.built.e2e.ts
@@ -11,7 +11,7 @@ import { describe, expect, it } from 'vitest'
 
 const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
 const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')
-const repositoryPluginPackage = join(repoRoot, 'packages/cordis/repository-plugin')
+const repositoryPluginPackage = join(repoRoot, 'packages/self-modification/repository-plugin')
 const releasePackageNames = new Set(globSync([
   'vendor/*/package.json',
   'packages/*/*/package.json',

From a208bc1a9263291481a1a5719fb583ea02ad354c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 11:28:31 +0800
Subject: [PATCH 450/516] docs(config-catalog): refresh repository source

---
 docs/config-catalog.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 34ea4a7fbd..0a5d0f7519 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1186,7 +1186,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/self-modification/repository-plugin/src/index.ts:43`](../packages/self-modification/repository-plugin/src/index.ts)
+Source: [`packages/self-modification/repository-plugin/src/index.ts:44`](../packages/self-modification/repository-plugin/src/index.ts)
 
 ## `@deepseek-ai/dsh-sandbox-local`
 

From c8e0b0f3a7bae107b332617e9b82cb3531f3fd99 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 11:41:30 +0800
Subject: [PATCH 451/516] test(repository-plugin): update keyless prepare
 fixture

---
 examples/headless-agent/tests/keyless-smoke.e2e.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/examples/headless-agent/tests/keyless-smoke.e2e.ts b/examples/headless-agent/tests/keyless-smoke.e2e.ts
index c737e4ea72..ba75ce9294 100644
--- a/examples/headless-agent/tests/keyless-smoke.e2e.ts
+++ b/examples/headless-agent/tests/keyless-smoke.e2e.ts
@@ -9,6 +9,7 @@ import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-l
 import {
   PREPARED_ENTRY_FILENAME,
   REPOSITORY_PLUGIN_PREPARE_COMMAND,
+  REPOSITORY_PLUGIN_PACKAGE_NAME,
   prepareDshPlugin,
 } from '@deepseek-ai/dsh-repository-plugin'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
@@ -77,6 +78,7 @@ describe('headless-agent keyless smoke', () => {
         name: 'headless-repository-fixture',
         version: '0.0.0',
         scripts: { prepack: REPOSITORY_PLUGIN_PREPARE_COMMAND },
+        devDependencies: { [REPOSITORY_PLUGIN_PACKAGE_NAME]: '0.0.1' },
         dsh: { skills: ['../skills'] },
       }, undefined, 2)}\n`)
       await prepareDshPlugin(plugin)

From 9087be1a2acd6556f7170b810ff0d0fc81f60244 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 12:21:57 +0800
Subject: [PATCH 452/516] fix(docs): address generated translation review
 findings

---
 ...9-human-transcript-append-origin.i18n.yaml |   2 +-
 ...07-29-human-transcript-append-origin.zh.md |  10 +-
 ...-bilingual-docs-and-pairing-gate.i18n.yaml |   2 +-
 ...7-02-bilingual-docs-and-pairing-gate.zh.md |   2 +-
 ...30-generated-third-party-notices.i18n.yaml |   2 +-
 ...-07-30-generated-third-party-notices.zh.md |   6 +-
 docs/api-gateway.i18n.yaml                    |   2 +-
 docs/api-gateway.zh.md                        |   2 +-
 docs/config-catalog.i18n.yaml                 |   2 +-
 docs/config-catalog.zh.md                     |   6 +-
 ...sponding-to-pr-review-on-a-stack.i18n.yaml |   2 +-
 .../responding-to-pr-review-on-a-stack.zh.md  |   2 +-
 docs/cordis-api/context.i18n.yaml             |   2 +-
 docs/cordis-api/context.zh.md                 |   4 +-
 docs/cordis-api/fiber.i18n.yaml               |   2 +-
 docs/cordis-api/fiber.zh.md                   |   6 +-
 docs/development.i18n.yaml                    |   2 +-
 docs/development.zh.md                        |   4 +-
 docs/i18n/README.i18n.yaml                    |   4 +-
 docs/i18n/README.md                           |   8 +-
 docs/i18n/README.zh.md                        |   8 +-
 docs/i18n/style-samples.md                    |   4 +-
 docs/module-graph.i18n.yaml                   |   2 +-
 docs/module-graph.zh.md                       | 162 +++++++++---------
 docs/persistence-catalog.i18n.yaml            |   2 +-
 docs/persistence-catalog.zh.md                |   2 +-
 docs/subsystems/README.i18n.yaml              |   2 +-
 docs/subsystems/README.zh.md                  |  16 +-
 docs/subsystems/llm-streaming.i18n.yaml       |   2 +-
 docs/subsystems/llm-streaming.zh.md           |  10 +-
 docs/subsystems/subagent.i18n.yaml            |   2 +-
 docs/subsystems/subagent.md                   |   2 +-
 docs/tool-catalog.i18n.yaml                   |   2 +-
 docs/tool-catalog.zh.md                       |  40 ++---
 .../request-response.expected.json            |   8 +-
 scripts/translation-pairing-merge.spec.ts     |  60 +++++++
 scripts/translation-pairing-merge.ts          |   3 +-
 37 files changed, 230 insertions(+), 169 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
index 7bce30803e..9c333a1363 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-29-human-transcript-append-origin.md
 2026-07-29-human-transcript-append-origin.md: 9804d3d8d67a4ad00c3d395c2081fd47e03c254a
-2026-07-29-human-transcript-append-origin.zh.md: ad952b697a11bd8f2d72785ec013bcf3e973db04
+2026-07-29-human-transcript-append-origin.zh.md: bfe39384f1f5a8badd4c859c89f450177f53ed62
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
index ad952b697a..bfe39384f1 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 终端从追加来源的 surface 事件回放 transcript，并通过 `transcriptToolCallIds` 让被遮蔽步骤的工具卡片保持配对：该函数读取追加来源的 `assistant/message`，而不是 surface 成员关系。已落地的压缩会在其自身日志位置贡献一行暗色 `… earlier context was compacted …`：这行标记报告模型从何处起不再看到那段历史，而不是把它抹掉。带框的检查点载荷从不渲染，且两条路径都按同一个标记对 surface 事件分类，因此实时到达的压缩与恢复后回放同一份日志会产生相同的 transcript。只有回放会重新推导 `tool/call` 的配对关系：调用事件自身不携带标记，其归属继承自公布它的 `assistant/message`，而实时监听器必然刚刚渲染过后者。
 
-检查点通过压缩seam自身的约定来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
+检查点通过压缩 seam 自身的约定来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
 
 `session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。
 
@@ -24,17 +24,17 @@ Status: implemented
 
 ## 延后事项
 
-浏览器客户端在[Web transcript 投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份追加来源 transcript并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝这个检查点。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，旧规则会把整段被遮蔽的范围一起拉到该页。
+浏览器客户端在[Web transcript 投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份追加来源 transcript 并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝这个检查点。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，旧规则会把整段被遮蔽的范围一起拉到该页。
 
 终端的[已归档实时压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用独立标记对中的事件驱动现有的单格指示器。它既不改变本文所负责的完成标记，也不添加规模信息：检查点的 `sourceEventSeqs` 仍可供经另行论证的计数或区间使用。因此，进度显示既不需要修改标记内容，也不以提取 `renderReplacement(event)` 为前置条件。
 
 ## 考虑过的替代方案
 
-**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的约定，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。seam已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
+**按形态识别检查点（一个替换型 `user/message`）。** 被否决：那读取的是当前生产者的巧合而非已声明的约定，而未来任何用用户消息替换一段范围的生产者都会静默地继承压缩标记。seam 已经发布 `COMPACT_CHECKPOINT_SOURCE`，正是为了让消费方与后端无关地识别检查点。
 
 **继续把检查点渲染为注入上下文卡片。** 被否决：带框的检查点是为模型撰写的指令信封，不是人类对话内容。展示它却隐藏它替换掉的历史，正好颠倒了读者的需要。
 
-**持久化第二份展示用 transcript。** 被否决：仅追加的日志已经包含权威源材料，平行 transcript换不来任何东西，反而增加迁移与一致性工作。
+**持久化第二份展示用 transcript。** 被否决：仅追加的日志已经包含权威源材料，平行 transcript 换不来任何东西，反而增加迁移与一致性工作。
 
 **用 `compact/*` 括号而不是检查点来推导标记。** 就 transcript 而言被否决：括号是围绕一次操作的一对时间点标记，而 transcript 需要的是 surface 真正发生变化的位置。括号适合作为进度与耗时的来源，而本次变更并不渲染这些。
 
@@ -46,7 +46,7 @@ Status: implemented
 
 `rebuildTranscript` 现在会为整份日志中的每个追加来源事件物化一个组件，并在挂载时、终端配色方案变化时以及每次切换推理（reasoning）时运行。压缩此前正好为压缩所服务的那些长会话限制了这项工作量，因此这份开销现在随会话长度增长，而不再随 surface 增长。这正是本次修复要做的取舍——保留历史才是目的——但窗口化或复用策略属于第一个真正测到重建变慢的人，而不属于日后某个疑惑工作量为何增长的性能分析者。
 
-`dsh-tui` 为一个纯谓词新增了对 `dsh-compact` seam的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。
+`dsh-tui` 为一个纯谓词新增了对 `dsh-compact` seam 的依赖，与 `dsh-session-reference` 现有用法一致。终端在运行时仍然不需要任何压缩后端。
 
 两项行为随其测试一起改变。表层替换的终端测试此前钉住的是抹除（「隐藏被遮蔽的工具调用」），现在钉住的是保留加恰好一行标记，其中被裁剪的结果副本、重新生成的 assistant 消息以及来自其他插件的替换都不渲染任何内容。压缩快照场景此前声称钉住压缩，却写入了 `workspace-context` 来源；现在它写入真实的检查点来源，并重新录制三份 fixture（测试前置数据），以显示被保留的提示、完整的工具卡片和那行标记。
 
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 812256d0ae..56ffbc366d 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
 2026-07-02-bilingual-docs-and-pairing-gate.md: b462efd99c008a1e8254b6754a408e9e94e787d6
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 409177996d7ffc63a36c865cc00002a33fe538f1
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 564442ce9bd09a448c030e30f34930673a06727b
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index 409177996d..564442ce9b 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 
 ## 验证
 
-验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。
+验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
index 907669edb8..004c168fe7 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
 2026-07-30-generated-third-party-notices.md: f2591c8d0c7d4b83ecc96bf237ded667e322d55c
-2026-07-30-generated-third-party-notices.zh.md: eef1e1f46bd9086ad0ccb1cf164330b3bbf601bb
+2026-07-30-generated-third-party-notices.zh.md: 97b62223c0f1e5d179e58f27a01251d8af43357b
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
index eef1e1f46b..97b62223c0 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
@@ -16,11 +16,11 @@ Status: implemented
 
 **新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何 manifest、工作区声明、根锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成该文件并将其暂存，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。
 
-有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
+有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest 不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
 
 文件默认只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。唯一明确披露的传递依赖，是 `@anthropic-ai/claude-agent-sdk` 通过 `optionalDependencies` 声明的官方 Claude 平台载荷集合，因为这些包承载随产品分发的 Claude Code 可执行文件，而非普通的库实现细节。
 
-**分层依据是声明方所在区域，而非manifest 字段名。** 只要 `DEV_ONLY_AREAS` 之外的任一 manifest——即根 manifest、`packages/support/`、`packages/client/test-runtime/`、`website/`、`examples/`、`native/` 之外——在 `dependencies` 或 `optionalDependencies` 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 `vitest` 写在 `dependencies` 里却并不交付它；而 `bin/dsh` 启动器通过 `tsx` 执行，根本没有任何 manifest 把它声明为运行时依赖，只能由生成器显式标记。
+**分层依据是声明方所在区域，而非 manifest 字段名。** 只要 `DEV_ONLY_AREAS` 之外的任一 manifest——即根 manifest、`packages/support/`、`packages/client/test-runtime/`、`website/`、`examples/`、`native/` 之外——在 `dependencies` 或 `optionalDependencies` 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 `vitest` 写在 `dependencies` 里却并不交付它；而 `bin/dsh` 启动器通过 `tsx` 执行，根本没有任何 manifest 把它声明为运行时依赖，只能由生成器显式标记。
 
 运行时层刻意覆盖**所有可挂载的插件**，而不止 CLI、Web UI 与 Python 运行时默认加载的那些。`scripts/install.sh` 安装的就是仓库本身，用户的 `cordis.yml` 可以挂载任何插件包；`@modelcontextprotocol/sdk` 与 OpenTelemetry 系列即使没有任何默认装配引入，也会触达真实用户。对法务披露而言，披露不足才是代价更高的那个方向。
 
@@ -30,7 +30,7 @@ manifest 集合由根 `pnpm-workspace.yaml` 声明的 `packages:` 成员派生
 
 ## Testing
 
-断言新鲜度的同一个 spec 也用fixture（测试前置数据）manifest钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它还把各解析器钉在那些原本会让某个包无声消失的形态上：不再覆盖全部收编目录的 `vendor/README.md` 表、含 extras 的依赖数组（`"httpx[http2]"`）、完全不带版本的依赖、作者自取名字的 `[dependency-groups]` 表，以及任何硬编码列表都不含的工作区成员区域。这些都是静默漏报路径——正是披露文件最担不起的失败方式。
+断言新鲜度的同一个 spec 也用 fixture（测试前置数据）manifest 钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它还把各解析器钉在那些原本会让某个包无声消失的形态上：不再覆盖全部收编目录的 `vendor/README.md` 表、含 extras 的依赖数组（`"httpx[http2]"`）、完全不带版本的依赖、作者自取名字的 `[dependency-groups]` 表，以及任何硬编码列表都不含的工作区成员区域。这些都是静默漏报路径——正是披露文件最担不起的失败方式。
 
 Claude 分发测试证明：只有精确匹配的直接 SDK 身份会绕过通常的非宽松运行时拒绝；该绕过不会改变许可证分类；载荷集合来自 SDK manifest，而非版本或平台允许列表。SDK 身份错误、载荷缺失或存在无关的可选包身份时，测试都会失败。
 
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index b1f78b85e4..de205997db 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/api-gateway.md
 api-gateway.md: e8aafc173dced3c4ead07421d92401411565ece6
-api-gateway.zh.md: f77a3e2675cc8ee6d27a8f6c9cbeb39609a9c282
+api-gateway.zh.md: f9fb6cff368bb4c7b75240452e2853c6f24da096
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index f77a3e2675..f9fb6cff36 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -159,7 +159,7 @@ pnpm run dev:web
 pnpm run build:lib
 ```
 
-运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定产物，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净的 worktree不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
+运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定产物，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净的 worktree 不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 会执行 Host lib 阶段后再运行 Client tsc，CI 与发布构建也使用同一顺序。
 
 ## 边界
 
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index bff77bc092..b976d35268 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
 config-catalog.md: eb4472d629e41f154384549245ecce1c8ec266e2
-config-catalog.zh.md: 42c1f6e85c416c68f18b8b2976300dec7e32dbc4
+config-catalog.zh.md: b29c64d9f4382628633639ff338ceb9bc56590ed
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 42c1f6e85c..b29c64d9f4 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -5,7 +5,7 @@
 
 [English](config-catalog.md) | 中文
 
-`cordis.yml` 条目可以设置的每个 `config:` 块：针对每个可加载的运行框架包，原样列出其 `apply` 函数或服务构造函数接收的配置声明（包括 JSDoc），并附上所有引用类型——包内类型直接粘贴，其他类型则提供链接。粘贴的内容是插件声明的完整配置类型——运行时 schema 有意排除的字段是仅供运行时使用的 seam（其自身的 JSDoc 会如此说明），不能通过 `cordis.yml` 设置。这是以**部署**为轴的参考文档——插件作者所依据的连接方式请参阅各[子系统页面](subsystems/core.md)中的生成 `cordis-surface` 区域，面向模型的工具 schema 请参阅[工具目录](tool-catalog.md)，而 [subsystems/](subsystems/core.md) 则记录了这些声明所引用的类型。
+每个 `config:` 块均可由 `cordis.yml` 条目设置：针对每个可加载的运行框架包，原样列出其 `apply` 函数或服务构造函数接收的配置声明（包括 JSDoc），并附上所有引用类型——包内类型直接粘贴，其他类型则提供链接。粘贴的内容是插件声明的完整配置类型——运行时 schema 有意排除的字段是仅供运行时使用的 seam（其自身的 JSDoc 会如此说明），不能通过 `cordis.yml` 设置。这是以**部署**为轴的参考文档——插件作者所依据的连接方式请参阅各[子系统页面](subsystems/core.md)中的生成 `cordis-surface` 区域，面向模型的工具 schema 请参阅[工具目录](tool-catalog.md)，而 [subsystems/](subsystems/core.md) 则记录了这些声明所引用的类型。
 
 英文源文件由源代码（`scripts/gen-config-catalog.ts`）生成，并通过 `pnpm run verify-config-catalog`（`doc-sync` 的一部分）验证为最新；本中文文件作为经评审对侧通过双语配对维护。声明块使用 `ts config-catalog` 围栏（doc-typecheck 会跳过它，因为单独引用导入项的声明无法独立编译）。英文生成器还会将运行时 schemastery schema 与粘贴的声明进行交叉核对——每个经 schema 验证的键（包括嵌套键）都必须能在声明的配置类型中找到——因此，粘贴内容无法隐藏加载器接受的字段。
 
@@ -641,7 +641,7 @@ export interface JsonRpcConfig {
 
 依赖：`Readable`（`node:stream`）· `Writable`（`node:stream`）
 
-来源：[`packages/scaffold/server/src/index.ts:25`](../packages/scaffold/server/src/index.ts)
+来源：[`packages/scaffold/server/src/index.ts:29`](../packages/scaffold/server/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-deepseek`
 
@@ -2572,7 +2572,7 @@ export interface Config {
 
 ## 无配置的可加载插件
 
-这些插件通过不含 `config:` 块的 `cordis.yml` 条目加载；它们未声明任何配置接口。
+这些插件通过 `cordis.yml` 中不含 `config:` 块的条目加载；它们未声明任何配置接口。
 
 - `@deepseek-ai/dsh-agent`（[`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts)）
 - `@deepseek-ai/dsh-api-gateway` — 需要 `typert`（[`packages/api/gateway/src/index.ts`](../packages/api/gateway/src/index.ts)）
diff --git a/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml b/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
index 7757b8419d..7e481af0bc 100644
--- a/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
+++ b/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/responding-to-pr-review-on-a-stack.md
 responding-to-pr-review-on-a-stack.md: 6bb7be3daf8613666f02f21e96bf7b1ac8cb3606
-responding-to-pr-review-on-a-stack.zh.md: 7567220096bb9dd6f3f68c16c08493ffb7529de7
+responding-to-pr-review-on-a-stack.zh.md: cd4984a09a8bdc1ab38fe2bbe54e669bff18230f
diff --git a/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md b/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
index 7567220096..cd4984a09a 100644
--- a/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
+++ b/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
@@ -19,7 +19,7 @@
 3. 将修复后的层按顺序传播到每个受影响的子 PR：
    - **Merge-forward：** 将修复后的父分支合并到其子分支，验证子分支，然后继续沿堆叠向上传播。依照[增量更新 base 的决策](../../.agents/notes/implemented/process/2026-07-26-incremental-pr-base-retargeting.md)，保留每个正在处理的检查点。
    - **原生级联 rebase：** 使用 `gh stack rebase`，验证所有已改写的层，然后通过 `gh stack push` 发布；也可以使用 `gh stack sync`，该命令可能先发布，因此必须按照 [dsh-pre-push-checks](../../.agents/skills/dsh-pre-push-checks/SKILL.md) 在同步后立即验证。
-4. 委派的修复需要信任但验证：subagent的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。subagent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
+4. 委派的修复需要信任但验证：subagent 的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。subagent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
 5. 在评审线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），而非发顶层评论；说明修复内容及当前承载修复的 commit 或 head。
 6. 每次改写推送后，都要重新读取未解决线程、批准状态、可合并性和检查结果。经 force-push 改写的 commit OID 或已过时的内联锚点，都不足以证明该发现当前仍处于已解决状态。
 7. 仅可通过官方堆叠流程落地。如果这些 PR 尚未关联，落地 skill 会自动关联作者相同的链；如果作者不同，则先询问用户；如果原生堆叠支持不可用，则硬性停止流程。
diff --git a/docs/cordis-api/context.i18n.yaml b/docs/cordis-api/context.i18n.yaml
index 618b112792..884e233721 100644
--- a/docs/cordis-api/context.i18n.yaml
+++ b/docs/cordis-api/context.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-api/context.md
 context.md: 320b23de1c8d19e2dacdf0ec9f2361037bcf8048
-context.zh.md: 2e4cdc1d2822d6cc19bf1907a44cc31c429016ea
+context.zh.md: 9b1f92a329ff4d75b3fafe7bf6bc8db317bcc267
diff --git a/docs/cordis-api/context.zh.md b/docs/cordis-api/context.zh.md
index 2e4cdc1d28..9b1f92a329 100644
--- a/docs/cordis-api/context.zh.md
+++ b/docs/cordis-api/context.zh.md
@@ -58,7 +58,7 @@ isolate(name: string, label?: symbol)
 
 创建一个子上下文，使 `name` 拥有独立的服务作用域。
 
-在返回的上下文之下，对服务 `name` 的读写会根据新标签解析，而不再根据父上下文的标签解析，因此可以提供不同的实现而不影响父作用域。向两次 `isolate()` 调用传入相同的 `label`，可使二者加入同一作用域。
+在返回的上下文之下，对服务 `name` 的读写会根据新标签解析，而不再根据父上下文的标签解析，因此可以提供不同的实现而不影响父作用域。将同一个 `label` 传给两次 `isolate()` 调用，可使二者加入同一作用域。
 
 - `name`：要隔离的服务名称。
 - `label`：要加入的作用域标签；默认为一个新建的唯一 symbol。
@@ -230,7 +230,7 @@ static is(value: any): value is Context
 
 - `value`：要测试的值。
 
-如果 `value` 是 Cordis 上下文，**返回** `true`，并收窄其类型。
+如果返回 `true`，则 `value` 是 Cordis 上下文，并会收窄其类型。
 
 [源码](../../vendor/cordis/src/context.ts#L61)
 
diff --git a/docs/cordis-api/fiber.i18n.yaml b/docs/cordis-api/fiber.i18n.yaml
index 0c45c03f5f..6c01366dc1 100644
--- a/docs/cordis-api/fiber.i18n.yaml
+++ b/docs/cordis-api/fiber.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-api/fiber.md
 fiber.md: 36d2861ac6a53e8186a92d86c65ba228d4b59ee5
-fiber.zh.md: 8fbc10c9870106f3fc7dfabe9725581898d9ef22
+fiber.zh.md: fafa559ca911677c43893862190009d82c39c56b
diff --git a/docs/cordis-api/fiber.zh.md b/docs/cordis-api/fiber.zh.md
index 8fbc10c987..fafa559ca9 100644
--- a/docs/cordis-api/fiber.zh.md
+++ b/docs/cordis-api/fiber.zh.md
@@ -29,7 +29,7 @@ effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
 
 在此 fiber 上注册一个支持清理的作用。
 
-`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose（资源释放），则抛出 `CordisError('INACTIVE_EFFECT')`；如果 `execute` 返回的结构无效，则抛出 `TypeError`。
+`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose（资源释放），则抛出 `CordisError('INACTIVE_EFFECT')`；如果结构无效，则抛出 `TypeError`，表示 `execute` 返回了不受支持的结果。
 
 - `execute`：作用主体；可接受的结构见 `Effect`。
 - `label`：在 `getEffects()` 诊断信息中显示的作用标签。
@@ -130,7 +130,7 @@ public store: Dict<Impl> | undefined
 public inertia: Promise<void> | undefined
 ```
 
-当前正在进行的加载或卸载转换；如果没有此类转换，则为 `undefined`。
+当前正在进行的加载或卸载转换；如果没有此类转换，则为 undefined。
 
 [源码](../../vendor/cordis/src/fiber.ts#L198)
 
@@ -185,7 +185,7 @@ effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
 
 在此 fiber 上注册一个支持清理的作用。
 
-`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose，则抛出 `CordisError('INACTIVE_EFFECT')`；如果 `execute` 返回的结构无效，则抛出 `TypeError`。
+`execute` 会立即运行；它产生的清理函数将被收集，并在调用返回的清理函数或卸载 fiber 时按相反顺序运行，以先发生者为准。重复调用清理函数不会产生任何效果。如果 fiber 已经 dispose，则抛出 `CordisError('INACTIVE_EFFECT')`；如果结构无效，则抛出 `TypeError`，表示 `execute` 返回了不受支持的结果。
 
 - `execute`：作用主体；可接受的结构见 `Effect`。
 - `label`：在 `getEffects()` 诊断信息中显示的作用标签。
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index d6d5d3dcc3..d2ea5f9122 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
 development.md: f7084403b30e8a6d12c4ef2b886f8fb61ed39b26
-development.zh.md: 60a4660f5d6be48fd4d0d8f30777ae37495d6296
+development.zh.md: 073810cb7e1042c43388b2299c2a1cb550fc0523
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 60a4660f5d..073810cb7e 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -21,7 +21,7 @@
 pnpm install
 ```
 
-安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。
+安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。
 
 如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：
 
@@ -100,7 +100,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 ### Git 集成
 
-当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。
+当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。
 
 安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。
 
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index c10cab36cb..8a8eb256fb 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/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 docs/i18n/README.md
-README.md: b6190e7dd84ae5f159fd452f093bf37f24edfda9
-README.zh.md: f1c808442efe3ca7da87c30ba22d3560bcf125e9
+README.md: 17d09eadd6d4eeb61d5f7ced188991f175070f98
+README.zh.md: 5e623777e1ca09295a7c690bfbb8760385527c98
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index b6190e7dd8..17d09eadd6 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -17,8 +17,8 @@ This repo's documentation is read by people and agents both inside and outside t
 
   Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).
 
-  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.
-- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.
+  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its required switchers and structural signature. The Chinese file must retain its English backlink; an authored English source must retain its Chinese link, while a listed generated English source is exempt. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.
+- **Language switcher.** The Chinese file always links back immediately after its H1 heading with `[English](foo.md) | 中文`. An authored English file reciprocates there with `English | [中文](foo.zh.md)`; a listed generated English source omits that line so it remains byte-identical to generator output.
 - **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
 
 ## The gate: verify-translation-pairing
@@ -26,7 +26,7 @@ This repo's documentation is read by people and agents both inside and outside t
 `pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:
 
 1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.
-2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.
+2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), the Chinese side and every authored English source carry their language switchers (listed generated English sources are exempt), and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.
 3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.
 
 Source-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.
@@ -57,4 +57,4 @@ Generated English references and graphs participate in pairing when a reviewed C
 
 ## Division of labor
 
-Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.
+Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, the Chinese backlink and authored-source switcher (with the documented generated-source exception), and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index f1c808442e..5e623777e1 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -17,8 +17,8 @@
 
   用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。
 
-  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。
-- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
+  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留必需的语言切换行和结构签名时，组合出一份新记录。中文文件必须保留指向英文的反向链接；普通撰写的英文源必须保留指向中文的链接，而清单内的生成英文源不作此要求。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。
+- **语言切换行。** 中文文件一律在 H1 标题后立即以 `[English](foo.md) | 中文` 链回英文。普通撰写的英文文件在同一位置以 `English | [中文](foo.zh.md)` 互链；清单内的生成英文源省略此行，以便与生成器输出逐字节一致。
 - **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
 
 ## 门禁：verify-translation-pairing
@@ -26,7 +26,7 @@
 `pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：
 
 1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。
-2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
+2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、中文侧和所有普通撰写的英文源都带语言切换行（清单内的生成英文源除外）、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
 3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。
 
 面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。
@@ -57,4 +57,4 @@
 
 ## 分工
 
-这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
+这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、中文反向链接和普通撰写源的切换行（生成源按本文规则例外），以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index 432c95e684..6860b91549 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -16,7 +16,7 @@
 
 > This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the generated regions of [subsystems/](../subsystems/core.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
 
-本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见 [subsystems/](../subsystems/core.md) 中的生成区块；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见 [subsystems/](../subsystems/core.md) 中的生成区块；各包的对外约定写在相应的 README 中（[索引](../../packages/README.md)）。
 
 ## ② 防御模式规则
 
@@ -60,7 +60,7 @@
 
 > The gate's limit, stated plainly: a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound. It checks hashes and shape; it cannot judge whether the two sides actually say the same thing — that is the reviewer's half of the contract. A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.
 
-门禁的边界很明确：通过门禁只说明两侧文件当前的 blob hash 与伴随记录吻合，并且结构签名一致，也就是说，这组内容曾被确认一致；它不代表这次确认可靠。门禁无法判断两种语言是否真正表达了相同的意思；这部分契约要由评审人把关。即使译文粗糙、表意有误，重新记录配对后仍能通过门禁，但绝不能通过人工评审。
+门禁的边界很明确：通过门禁只说明两侧文件当前的 blob hash 与伴随记录吻合，并且结构签名一致，也就是说，这组内容曾被确认一致；它不代表这次确认可靠。门禁无法判断两种语言是否真正表达了相同的意思；这部分约定要由评审人把关。即使译文粗糙、表意有误，重新记录配对后仍能通过门禁，但绝不能通过人工评审。
 
 ## ⑥ Agent Note 论证
 
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index 212b107093..a0ba36d097 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/module-graph.md
 module-graph.md: 6f47c36e970009838e1ab921f4abe013eaeded5f
-module-graph.zh.md: 5da7bc962e1c38e3febfbca59e6bb11b014ecc7f
+module-graph.zh.md: 644305dbde58f5c35ec57fb9c313dcb78fae9938
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index 5da7bc962e..644305dbde 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -1207,8 +1207,8 @@ flowchart TD
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`frontend-static`](../packages/host/frontend-static) | `host` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
-| [`helper`](../packages/scaffold/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
-| [`telemetry`](../packages/scaffold/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
+| [`helper`](../packages/scaffold/helper) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
+| [`telemetry`](../packages/scaffold/telemetry) | `scaffold` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
 | [`settings`](../packages/settings/settings) | `settings` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
 | [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
@@ -1240,18 +1240,18 @@ flowchart TD
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`session-persistence`](../packages/support/acp-snapshot) | `session-persistence` | [`brand`](../packages/support/invariants), [`invariants`](../packages/core/session), [`session`](../packages/boot/app-boot), [`timeout`](../packages/util/environment) |
-| [`acp-snapshot`](../packages/support/invariants) | `support` | [`invariants`](../packages/util/paths), [`session`](../packages/core/system-prompt) |
-| [`app-boot`](../packages/client/ui-question) | `ui` | [`environment`](../packages/client/locale), [`invariants`](../packages/support/invariants), [`paths`](../packages/client/ui-settings-general), [`system-prompt`](../packages/client/connection) |
-| [`client-ui-question`](../packages/client/locale) | `client` | [`client-locale`](../packages/client/runtime), [`invariants`](../packages/client/ui-primitives) |
-| [`client-ui-settings-general`](../packages/client/ui-settings) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/client/web-react), [`client-runtime`](../packages/support/invariants), [`client-ui-primitives`](../packages/client/ui-sidebar), [`client-ui-settings`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`client-web-react`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
-| [`client-ui-sidebar`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
-| [`client-ui-slash`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-theme), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
-| [`client-ui-theme`](../packages/support/invariants) | `client` | [`client-locale`](../packages/client/ui-workspace), [`client-runtime`](../packages/client/locale), [`client-ui-primitives`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-primitives), [`invariants`](../packages/client/ui-slots) |
-| [`client-ui-workspace`](../packages/support/invariants) | `client` | [`client-locale`](../packages/code-runtime/code-runtime-worker), [`client-runtime`](../packages/code-runtime/code-runtime), [`client-ui-primitives`](../packages/support/invariants), [`client-ui-slots`](../packages/core/session), [`invariants`](../packages/util/timeout) |
-| [`code-runtime-worker`](../packages/sandbox/sandbox-local) | `code-runtime` | [`code-runtime`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`session`](../packages/sandbox/sandbox), [`timeout`](../packages/session/session-persistence) |
-| [`sandbox-local`](../packages/util/brand) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/core/session), [`sandbox`](../packages/util/timeout) |
-| [`session-projection`](../packages/session/session-projection) | `session-projection` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`app-boot`](../packages/boot/app-boot) | `boot` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`system-prompt`](../packages/core/system-prompt) |
+| [`client-ui-question`](../packages/client/ui-question) | `client` | [`client-locale`](../packages/client/locale), [`invariants`](../packages/support/invariants) |
+| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`invariants`](../packages/support/invariants) |
+| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-slash`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
+| [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
@@ -1263,28 +1263,28 @@ flowchart TD
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`session-persistence-jsonl`](../packages/support/llm-replay) | `session-persistence` | [`invariants`](../packages/compact/compact), [`session`](../packages/support/invariants), [`session-persistence`](../packages/llm/llm) |
-| [`session-persistence-sqlite`](../packages/core/session) | `session-persistence` | [`invariants`](../packages/support/loader-smoke), [`session`](../packages/core/agent), [`session-persistence`](../packages/support/invariants) |
-| [`session-title`](../packages/llm/llm) | `session-title` | [`brand`](../packages/core/session), [`invariants`](../packages/bundle/headless), [`llm`](../packages/core/agent), [`session`](../packages/host/apiproxy), [`session-projection`](../packages/host/webserver) |
-| [`llm-replay`](../packages/support/invariants) | `support` | [`compact`](../packages/core/session), [`invariants`](../packages/client/ui-layout), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-slots) |
-| [`loader-smoke`](../packages/client/ui-theme) | `support` | [`agent`](../packages/support/invariants), [`invariants`](../packages/context/time-context), [`llm`](../packages/core/agent), [`session`](../packages/support/invariants) |
-| [`commands`](../packages/core/session) | `ui` | [`agent`](../packages/context/tmux-context), [`brand`](../packages/core/agent), [`invariants`](../packages/bash/bash), [`scope`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`user-approval`](../packages/e2b/fs-e2b) | `ui` | [`agent`](../packages/e2b/e2b), [`brand`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/host/directory-picker-browse), [`scope`](../packages/client/locale), [`session`](../packages/client/runtime), [`system-prompt`](../packages/client/ui-primitives) |
-| [`user-interaction`](../packages/client/ui-slots) | `ui` | [`agent`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants), [`llm`](../packages/host/directory-picker-native) |
-| [`headless`](../packages/client/runtime) | `bundle` | [`agent`](../packages/client/ui-slots), [`host-apiproxy`](../packages/client/ui-workspace), [`host-webserver`](../packages/support/invariants), [`invariants`](../packages/interaction/commands), [`session`](../packages/core/agent) |
-| [`client-ui-layout`](../packages/util/brand) | `client` | [`client-runtime`](../packages/support/invariants), [`client-ui-slots`](../packages/core/scope), [`client-ui-theme`](../packages/core/session), [`invariants`](../packages/interaction/user-approval) |
-| [`time-context`](../packages/core/agent) | `context` | [`agent`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/llm/llm) |
-| [`tmux-context`](../packages/core/scope) | `context` | [`agent`](../packages/core/session), [`bash`](../packages/core/system-prompt), [`invariants`](../packages/interaction/user-interaction), [`session`](../packages/core/agent) |
-| [`fs-e2b`](../packages/support/invariants) | `e2b` | [`e2b`](../packages/llm/llm), [`fs`](../packages/lsp/lsp-local), [`invariants`](../packages/util/brand) |
-| [`host-directory-picker-browse`](../packages/fs/fs) | `host` | [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/llm/llm), [`client-ui-primitives`](../packages/lsp/lsp), [`client-ui-slots`](../packages/subprocess/subprocess), [`client-ui-workspace`](../packages/util/timeout), [`invariants`](../packages/pty/pty) |
-| [`host-directory-picker-native`](../packages/core/agent) | `host` | [`client-runtime`](../packages/util/brand), [`client-ui-slots`](../packages/support/invariants), [`client-ui-workspace`](../packages/sandbox/sandbox-policy), [`invariants`](../packages/core/agent) |
-| [`lsp-local`](../packages/support/invariants) | `lsp` | [`brand`](../packages/sandbox/sandbox), [`fs`](../packages/core/session), [`invariants`](../packages/core/system-prompt), [`llm`](../packages/scaffold/scripts), [`lsp`](../packages/boot/app-boot), [`subprocess`](../packages/support/invariants), [`timeout`](../packages/session/session-persistence-jsonl) |
-| [`pty`](../packages/support/invariants) | `pty` | [`agent`](../packages/core/session), [`brand`](../packages/session/session-persistence), [`invariants`](../packages/session/session-persistence-sqlite) |
-| [`sandbox-policy`](../packages/support/invariants) | `sandbox` | [`agent`](../packages/core/session), [`invariants`](../packages/session/session-persistence), [`sandbox`](../packages/session/session-projection-cache), [`session`](../packages/support/invariants), [`system-prompt`](../packages/core/session) |
-| [`scripts`](../packages/session/session-persistence) | `sdk` | [`app-boot`](../packages/session/session-projection), [`invariants`](../packages/storage/storage-domain) |
-| [`session-projection-cache`](../packages/session/session-telemetry) | `session-projection` | [`invariants`](../packages/core/agent), [`session`](../packages/support/invariants), [`session-persistence`](../packages/core/session), [`session-projection`](../packages/session/session-title), [`storage-domain`](../packages/util/brand) |
-| [`tasks`](../packages/support/invariants) | `tasks` | [`agent`](../packages/llm/llm), [`brand`](../packages/core/session), [`invariants`](../packages/session/session-projection), [`session`](../packages/tasks/tasks) |
-| [`session-telemetry`](../packages/core/agent) | `telemetry` | [`agent`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
+| [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`fs-e2b`](../packages/e2b/fs-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
+| [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | `host` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`host-directory-picker-native`](../packages/host/directory-picker-native) | `host` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/support/invariants) |
+| [`commands`](../packages/interaction/commands) | `interaction` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
+| [`user-approval`](../packages/interaction/user-approval) | `interaction` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
+| [`user-interaction`](../packages/interaction/user-interaction) | `interaction` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`pty`](../packages/pty/pty) | `pty` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
+| [`scripts`](../packages/scaffold/scripts) | `scaffold` | [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants) |
+| [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) |
+| [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) |
+| [`session-telemetry`](../packages/session/session-telemetry) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`session-title`](../packages/session/session-title) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`workspace`](../packages/workspace/workspace) | `workspace` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage`](../packages/storage/storage), [`storage-domain`](../packages/storage/storage-domain) |
 | [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval) |
@@ -1295,14 +1295,14 @@ flowchart TD
 | [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
 | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
-| [`session-title-llm`](../packages/acp/acp) | `session-title` | [`invariants`](../packages/core/agent), [`llm`](../packages/support/invariants), [`session`](../packages/core/session), [`session-title`](../packages/interaction/user-approval), [`timeout`](../packages/api/remotes) |
-| [`acp`](../packages/core/agent) | `acp` | [`agent`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/session/session-persistence) |
-| [`permission`](../packages/typert/registry) | `ui` | [`bash`](../packages/client/ui-conversation), [`commands`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`sandbox`](../packages/client/ui-primitives), [`sandbox-policy`](../packages/client/ui-slash), [`session`](../packages/client/ui-slots), [`session-projection`](../packages/support/invariants), [`settings`](../packages/llm/token-meter), [`user-approval`](../packages/feedback/command-feedback) |
-| [`api-remotes`](../packages/interaction/commands) | `api` | [`agent`](../packages/support/invariants), [`goal`](../packages/core/session), [`invariants`](../packages/host/directory-picker-auto), [`session`](../packages/host/directory-picker-browse), [`session-persistence`](../packages/host/directory-picker-native), [`typert-registry`](../packages/host/webserver) |
-| [`client-ui-conversation`](../packages/support/invariants) | `client` | [`client-locale`](../packages/interaction/permission), [`client-runtime`](../packages/bash/bash), [`client-ui-primitives`](../packages/interaction/commands), [`client-ui-slash`](../packages/support/invariants), [`client-ui-slots`](../packages/sandbox/sandbox), [`invariants`](../packages/sandbox/sandbox-policy), [`token-meter`](../packages/core/session) |
-| [`command-feedback`](../packages/session/session-projection) | `feedback` | [`commands`](../packages/settings/settings), [`invariants`](../packages/interaction/user-approval), [`session`](../packages/pty/pty-local) |
-| [`host-directory-picker-auto`](../packages/core/agent) | `host` | [`host-directory-picker-browse`](../packages/support/invariants), [`host-directory-picker-native`](../packages/pty/pty), [`host-webserver`](../packages/sandbox/sandbox), [`invariants`](../packages/sandbox/sandbox-policy) |
-| [`pty-local`](../packages/core/session) | `pty` | [`agent`](../packages/subprocess/subprocess), [`invariants`](../packages/session/session-title-llm), [`pty`](../packages/support/invariants), [`sandbox`](../packages/llm/llm), [`sandbox-policy`](../packages/core/session), [`session`](../packages/session/session-title), [`subprocess`](../packages/util/timeout) |
+| [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
+| [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
+| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
+| [`permission`](../packages/interaction/permission) | `interaction` | [`bash`](../packages/bash/bash), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval) |
+| [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
+| [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -1315,31 +1315,31 @@ flowchart TD
 | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
-| [`timeout-policy`](../packages/todo/tool-todo) | `timeout` | [`invariants`](../packages/core/agent), [`llm`](../packages/support/invariants), [`timeout`](../packages/core/session), [`tools`](../packages/session/session-projection) |
-| [`tool-todo`](../packages/core/tools) | `todo` | [`agent`](../packages/plan/plan-mode), [`invariants`](../packages/core/agent), [`session`](../packages/interaction/commands), [`session-projection`](../packages/support/invariants), [`tools`](../packages/llm/llm) |
-| [`plan-mode`](../packages/core/session) | `plan` | [`agent`](../packages/session/session-projection), [`commands`](../packages/core/system-prompt), [`invariants`](../packages/core/tools), [`llm`](../packages/interaction/user-interaction), [`session`](../packages/hooks/hooks-codex), [`session-projection`](../packages/core/agent), [`system-prompt`](../packages/hooks/hook-protocol), [`tools`](../packages/support/invariants), [`user-interaction`](../packages/llm/llm) |
-| [`tool-cordis`](../packages/core/session) | `cordis` | [`invariants`](../packages/session/session-persistence), [`scope`](../packages/core/tools), [`tools`](../packages/session-query/session-query-sqlite) |
-| [`hooks-codex`](../packages/support/invariants) | `hooks` | [`agent`](../packages/core/session), [`hook-protocol`](../packages/session/session-persistence), [`invariants`](../packages/session-query/session-query), [`llm`](../packages/session-query/tool-session-query), [`session`](../packages/support/invariants), [`session-persistence`](../packages/llm/llm), [`tools`](../packages/core/session) |
-| [`session-checkpoint-policy`](../packages/session-query/session-query) | `session-persistence` | [`agent`](../packages/core/system-prompt), [`invariants`](../packages/util/timeout), [`llm`](../packages/core/tools), [`session`](../packages/support/agent-loop-testkit), [`session-persistence`](../packages/core/agent), [`tools`](../packages/support/invariants) |
-| [`session-query-sqlite`](../packages/llm/llm) | `session-query` | [`invariants`](../packages/core/session), [`session`](../packages/core/system-prompt), [`session-persistence`](../packages/core/tools), [`session-query`](../packages/client/ui-command) |
-| [`tool-session-query`](../packages/client/connection) | `session-query` | [`invariants`](../packages/client/locale), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-conversation), [`session-query`](../packages/client/ui-primitives), [`system-prompt`](../packages/client/ui-slash), [`timeout`](../packages/client/ui-slots), [`tools`](../packages/support/invariants) |
-| [`session-title-all-messages-llm`](../packages/client/ui-deliverables) | `session-title` | [`invariants`](../packages/client/locale), [`llm`](../packages/client/runtime), [`session`](../packages/client/ui-conversation), [`session-title`](../packages/client/ui-slots), [`session-title-llm`](../packages/support/invariants) |
-| [`session-title-first-message-llm`](../packages/client/ui-goal) | `session-title` | [`invariants`](../packages/api/remotes), [`llm`](../packages/client/locale), [`session`](../packages/client/runtime), [`session-title`](../packages/client/ui-conversation), [`session-title-llm`](../packages/client/ui-primitives) |
-| [`agent-loop-testkit`](../packages/client/ui-slots) | `support` | [`agent`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/client/ui-tool), [`session`](../packages/client/locale), [`system-prompt`](../packages/client/runtime), [`tools`](../packages/client/ui-conversation) |
-| [`tool-ask-user`](../packages/client/ui-primitives) | `ui` | [`agent`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`tools`](../packages/context/session-reference), [`user-interaction`](../packages/core/agent) |
-| [`client-ui-command`](../packages/compact/compact) | `client` | [`client-connection`](../packages/support/invariants), [`client-locale`](../packages/llm/llm), [`client-runtime`](../packages/util/retention), [`client-ui-conversation`](../packages/core/session), [`client-ui-primitives`](../packages/session-query/session-query), [`client-ui-slash`](../packages/context/workspace-context), [`client-ui-slots`](../packages/core/agent), [`invariants`](../packages/fs/fs) |
-| [`client-ui-deliverables`](../packages/support/invariants) | `client` | [`client-locale`](../packages/llm/llm), [`client-runtime`](../packages/util/paths), [`client-ui-conversation`](../packages/core/session), [`client-ui-slots`](../packages/core/tools), [`invariants`](../packages/guard/repeat-tool-guard) |
-| [`client-ui-goal`](../packages/core/agent) | `client` | [`api-remotes`](../packages/support/invariants), [`client-locale`](../packages/core/tools), [`client-runtime`](../packages/guard/timeout-policy), [`client-ui-conversation`](../packages/support/invariants), [`client-ui-primitives`](../packages/llm/llm), [`client-ui-slots`](../packages/util/timeout), [`goal`](../packages/core/tools), [`invariants`](../packages/interaction/tool-ask-user) |
-| [`client-ui-tool`](../packages/core/agent) | `client` | [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/core/tools), [`client-ui-conversation`](../packages/interaction/user-interaction), [`client-ui-primitives`](../packages/lsp/tool-lsp), [`client-ui-slots`](../packages/support/invariants), [`invariants`](../packages/llm/llm) |
-| [`session-reference`](../packages/lsp/lsp) | `context` | [`agent`](../packages/core/system-prompt), [`compact`](../packages/util/timeout), [`invariants`](../packages/core/tools), [`llm`](../packages/mcp/mcp-client), [`retention`](../packages/support/invariants), [`session`](../packages/llm/llm), [`session-query`](../packages/subprocess/subprocess) |
-| [`workspace-context`](../packages/core/tools) | `context` | [`agent`](../packages/pty/tool-bash-persistent), [`fs`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/pty/pty), [`paths`](../packages/util/timeout), [`session`](../packages/core/tools), [`tools`](../packages/pty/tool-pty) |
-| [`repeat-tool-guard`](../packages/core/agent) | `guard` | [`agent`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`tools`](../packages/pty/pty) |
-| [`tool-lsp`](../packages/util/retention) | `lsp` | [`invariants`](../packages/core/system-prompt), [`llm`](../packages/tasks/tasks), [`lsp`](../packages/core/tools), [`system-prompt`](../packages/self-modification/tool-cordis), [`timeout`](../packages/support/invariants), [`tools`](../packages/core/scope) |
-| [`mcp-client`](../packages/core/tools) | `mcp` | [`invariants`](../packages/session/session-checkpoint-policy), [`llm`](../packages/core/agent), [`subprocess`](../packages/support/invariants), [`tools`](../packages/llm/llm) |
-| [`tool-bash-persistent`](../packages/core/session) | `pty` | [`agent`](../packages/session/session-persistence), [`invariants`](../packages/core/tools), [`pty`](../packages/session/session-telemetry-otel), [`timeout`](../packages/util/brand), [`tools`](../packages/feedback/command-feedback) |
-| [`tool-pty`](../packages/support/invariants) | `pty` | [`agent`](../packages/llm/llm), [`invariants`](../packages/util/paths), [`llm`](../packages/core/session), [`pty`](../packages/session/session-telemetry), [`retention`](../packages/session/session-title-all-messages-llm), [`system-prompt`](../packages/support/invariants), [`tasks`](../packages/llm/llm), [`tools`](../packages/core/session) |
-| [`tool-tasks`](../packages/session/session-title) | `tasks` | [`agent`](../packages/session/session-title-llm), [`invariants`](../packages/session/session-title-first-message-llm), [`llm`](../packages/support/invariants), [`retention`](../packages/llm/llm), [`system-prompt`](../packages/core/session), [`tasks`](../packages/session/session-title), [`tools`](../packages/session/session-title-llm) |
-| [`session-telemetry-otel`](../packages/tasks/tool-tasks) | `telemetry` | [`brand`](../packages/core/agent), [`command-feedback`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`llm`](../packages/util/retention), [`paths`](../packages/core/system-prompt), [`session`](../packages/tasks/tasks), [`session-telemetry`](../packages/core/tools) |
+| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
+| [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-interaction`](../packages/interaction/user-interaction) |
+| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
+| [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
+| [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
+| [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
+| [`timeout-policy`](../packages/guard/timeout-policy) | `guard` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-ask-user`](../packages/interaction/tool-ask-user) | `interaction` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/interaction/user-interaction) |
+| [`tool-lsp`](../packages/lsp/tool-lsp) | `lsp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools) |
+| [`tool-bash-persistent`](../packages/pty/tool-bash-persistent) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-pty`](../packages/pty/tool-pty) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`pty`](../packages/pty/pty), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`tool-cordis`](../packages/self-modification/tool-cordis) | `self-modification` | [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
+| [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
+| [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
+| [`session-title-all-messages-llm`](../packages/session/session-title-all-messages-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
+| [`session-title-first-message-llm`](../packages/session/session-title-first-message-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`session-title-llm`](../packages/session/session-title-llm) |
+| [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
@@ -1349,22 +1349,22 @@ flowchart TD
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`repository-plugin`](../packages/hooks/hooks-claude) | `cordis` | [`invariants`](../packages/core/agent), [`mcp-client`](../packages/hooks/hook-protocol), [`paths`](../packages/support/invariants), [`skill-local`](../packages/llm/llm) |
-| [`hooks-claude`](../packages/core/session) | `hooks` | [`agent`](../packages/session/session-persistence), [`hook-protocol`](../packages/subagent/subagent), [`invariants`](../packages/core/tools), [`llm`](../packages/bundle/web-app), [`session`](../packages/bash/bash-env), [`session-persistence`](../packages/support/invariants), [`subagent`](../packages/core/system-prompt), [`tools`](../packages/client/ui-model) |
-| [`web-app`](../packages/client/connection) | `bundle` | [`bash-env`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`system-prompt`](../packages/client/ui-command) |
-| [`client-ui-model`](../packages/client/ui-conversation) | `client` | [`client-connection`](../packages/client/ui-primitives), [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/ui-slots), [`client-ui-command`](../packages/support/invariants), [`client-ui-conversation`](../packages/client/ui-permission), [`client-ui-primitives`](../packages/client/connection), [`client-ui-slash`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`invariants`](../packages/client/schema-form) |
-| [`client-ui-permission`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/ui-primitives), [`client-locale`](../packages/client/ui-slash), [`client-runtime`](../packages/client/ui-slots), [`client-schema-form`](../packages/support/invariants), [`client-ui-command`](../packages/interaction/permission), [`client-ui-primitives`](../packages/client/ui-plan), [`client-ui-slash`](../packages/client/connection), [`client-ui-slots`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`permission`](../packages/client/ui-conversation) |
-| [`client-ui-plan`](../packages/client/ui-primitives) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/support/invariants), [`client-runtime`](../packages/plan/plan-mode), [`client-ui-conversation`](../packages/client/ui-skill), [`client-ui-primitives`](../packages/client/connection), [`client-ui-slots`](../packages/client/locale), [`invariants`](../packages/client/runtime), [`plan-mode`](../packages/client/ui-primitives) |
-| [`client-ui-skill`](../packages/client/ui-slash) | `client` | [`client-connection`](../packages/client/ui-slots), [`client-locale`](../packages/client/ui-tool), [`client-runtime`](../packages/support/invariants), [`client-ui-primitives`](../packages/client/ui-subagent), [`client-ui-slash`](../packages/client/locale), [`client-ui-slots`](../packages/client/runtime), [`client-ui-tool`](../packages/client/ui-conversation), [`invariants`](../packages/client/ui-primitives) |
-| [`client-ui-subagent`](../packages/client/ui-slash) | `client` | [`client-locale`](../packages/client/ui-slots), [`client-runtime`](../packages/support/invariants), [`client-ui-conversation`](../packages/subagent/subagent), [`client-ui-primitives`](../packages/llm/token-meter), [`client-ui-slash`](../packages/scaffold/protocol), [`client-ui-slots`](../packages/support/invariants), [`invariants`](../packages/llm/llm), [`subagent`](../packages/core/session), [`token-meter`](../packages/subagent/subagent) |
-| [`sdk-protocol`](../packages/self-modification/repository-plugin) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/mcp/mcp-client), [`session`](../packages/util/paths), [`subagent`](../packages/skill/skill-local) |
+| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
+| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
+| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
+| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`repository-plugin`](../packages/self-modification/repository-plugin) | `self-modification` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
-| [`jsonrpc`](../packages/examples/agent-spine-demo) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/core/agent-loop), [`llm`](../packages/bash/bash-env), [`llm-deepseek`](../packages/goal/goal), [`scope`](../packages/goal/goal-session), [`sdk-protocol`](../packages/support/invariants), [`session`](../packages/llm/llm), [`subagent`](../packages/llm/llm-retry) |
-| [`agent-spine-demo`](../packages/util/paths) | `examples` | [`agent`](../packages/core/scope), [`agent-loop`](../packages/core/session), [`bash-env`](../packages/session/session-title), [`goal`](../packages/skill/skill), [`goal-session`](../packages/skill/skill-local), [`invariants`](../packages/core/system-prompt), [`llm`](../packages/tasks/tasks-local), [`llm-retry`](../packages/bash/tool-bash), [`paths`](../packages/goal/tool-goal), [`scope`](../packages/skill/tool-skill), [`session`](../packages/tasks/tool-tasks), [`session-title`](../packages/core/tools), [`skill`](../packages/context/workspace-context), [`skill-local`](../packages/scaffold/server), [`system-prompt`](../packages/core/agent), [`tasks-local`](../packages/support/invariants), [`tool-bash`](../packages/llm/llm), [`tool-goal`](../packages/llm/llm-deepseek), [`tool-skill`](../packages/core/scope), [`tool-tasks`](../packages/scaffold/protocol), [`tools`](../packages/core/session), [`workspace-context`](../packages/subagent/subagent) |
-| [`sdk-client`](../packages/scaffold/client) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
+| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`jsonrpc`](../packages/scaffold/server) | `scaffold` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`sdk-client`](../packages/scaffold/client) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index 49f2c2a45e..c15a931612 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/persistence-catalog.md
 persistence-catalog.md: 04c3a492fe837f7acc102901a289bf74f0cecf3f
-persistence-catalog.zh.md: 3f75cb55e2771b27e494aca9ea81ffeba3e69064
+persistence-catalog.zh.md: 5e2b62d71a5dea93ede0f1a5b16dc528dca197a7
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index 3f75cb55e2..5e2b62d71a 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -7,7 +7,7 @@
 
 会话持久事件日志中可能出现的所有事件类型：完整持久化的 `SessionEvent` 信封，以及可通过合并扩展的 `SessionEventMap` 中的每个成员，包括 `@deepseek-ai/dsh-session` 所属的词汇和本仓库中每个插件的声明合并，并附有源 JSDoc、完整 payload 声明、surface 标记和声明位置。本文档是 [session.md](subsystems/session.md)（surface 排序与 `deriveMessages()` 投影）、[persistence.md](subsystems/persistence.md)（如何让日志持久化）和 [session.md](subsystems/session.md#cordis-surface) 中生成区域（实时总线接线；日志事件**不是** cordis 事件，它通过唯一一次 `session/event` emit 到达监听器）的补充。
 
-英文源文件根据源码生成（`scripts/gen-persistence-catalog.ts`），并由 `pnpm run verify-persistence-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc，只移除其所在接口／模块带来的缩进，并使用 `ts persistence-catalog` 围栏（`doc-typecheck` 会跳过这些围栏，因为声明引用了其所属模块中的类型）。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。
+英文源文件根据源码生成（`scripts/gen-persistence-catalog.ts`），并由 `pnpm run verify-persistence-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc，只移除其所在接口／模块带来的缩进，并使用 `ts persistence-catalog` 围栏（doc-typecheck 会跳过这些围栏，因为声明引用了其所属模块中的类型）。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。
 
 以下信封声明组合了每个事件的 `type`、单调递增的 `seq`、以 epoch 毫秒表示的 `time`、`data`，以及条件字段 `surfaceOp`／`sourceEventSeqs`。**surface** 表示 `SurfaceEventType` 成员：它会生成一条 LLM（大语言模型）消息，并声明该事件如何加入 surface 列表。**log-only** 表示其他所有事件：这类记录可持久化、可回放，但不参与派生历史。每个 payload 均可进行 JSON 序列化（在 `Session.append` 处强制执行），整个格式固定为 `SESSION_FORMAT_VERSION = 0`：这是预发布格式，不暗示任何兼容性（参见[版本立场](subsystems/persistence.md)）。范围仅限本仓库中的包；下游插件可以继续合并其他事件类型，而这些类型按设计不属于本目录。
 
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index f1636e0191..b741c1cdf8 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/README.md
 README.md: 1c3d14aeb4fd11cbc45eaadd83f0b84de0dfda52
-README.zh.md: dda61d86c4d00117af851b4a55d16b97c6bc2f10
+README.zh.md: 04e07cc9c8b8b16c69bb09344e8533729525fe5c
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index dda61d86c4..04e07cc9c8 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -6,8 +6,8 @@
 
 | 页面 | 负责内容 |
 |---|---|
-| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截契约，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
-| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器契约（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
+| [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截约定，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
+| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器约定（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
 | [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
@@ -18,15 +18,15 @@
 | [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
 | [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
 | [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
-| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方契约 |
+| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方约定 |
 | [session-reference.md](session-reference.md) | 结构化跨会话引用：`SessionReferenceInput`/`Candidate`、prepared 消息上下文、稳定错误分类 |
 | [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
 | [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
 | [user-interaction.md](user-interaction.md) | UI 支持的人工问答 seam：`AskUserQuestionRequest`、answer/options 词汇、提供方 API、错误分类体系 |
-| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 契约 |
+| [approval.md](approval.md) | 一次性用户审批 seam：`ApprovalRequest`、`ApprovalOutcome`、逐会话策略、审计与 answerer 约定 |
 | [bash.md](bash.md) | bash 执行器 seam：`BashExecRequest`/`Spec`、`BashRunResult`、后台 `BashProcess` 句柄 |
 | [subprocess.md](subprocess.md) | 子进程 seam：完全显式的 `SubprocessSpawnSpec`、基于偏移的输出读取器、不含分类的 `SubprocessOutcome`，以及受管 `DSH_*` 环境词汇 |
-| [pty.md](pty.md) | 持久化终端 ID、后端/会话契约、发送就绪状态、有界读取与 owner 可见快照 |
+| [pty.md](pty.md) | 持久化终端 ID、后端/会话约定、发送就绪状态、有界读取与 owner 可见快照 |
 | [sandbox.md](sandbox.md) | 每会话策略解析与进程约束 seam：文件效果模式、执行/提供方策略、`ConfinedArgv`、强制执行与故障关闭错误 |
 | [code-runtime.md](code-runtime.md) | 代码执行 seam：`CodeRunRequest`/`Result`、绑定命名空间、捕获日志、`CodeRunFailure` 分类体系 |
 | [filesystem.md](filesystem.md) | 文件系统 seam：`FsTarget`、读/写/编辑结果、观测到的文件状态、`FsErrorCode` |
@@ -37,15 +37,15 @@
 | [web.md](web.md) | Web 访问 seam：`WebSearchRequest`/`Result`、`WebFetchRequest`/`Result`、`WebFetchBody`、提供方可用性、`WebError` |
 | [spill.md](spill.md) | spill 存储 seam：`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` |
 | [workflow.md](workflow.md) | 工作流 seam：`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 |
-| [tasks.md](tasks.md) | 后台任务运行时：品牌化 `TaskId`、producer 契约、consumer 视图、`ctx.tasks` 服务行为 |
+| [tasks.md](tasks.md) | 后台任务运行时：品牌化 `TaskId`、producer 约定、consumer 视图、`ctx.tasks` 服务行为 |
 | [permission.md](permission.md) | 权限预设层：`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 |
 | [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
-| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件契约 |
+| [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件约定 |
 | [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、可认领的回退席位、index 转换 |
 | [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
-| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 契约、`telemetry/record` 脱敏 waterfall |
+| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 约定、`telemetry/record` 脱敏 waterfall |
 
 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis surface** 小节。
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index 0945fee0a3..946aca73b0 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md
 llm-streaming.md: 1705c45697df98b51ba9f69c8c91b3a8a18dea76
-llm-streaming.zh.md: 591326582c96023df5a184e19e3e4fc812187fb4
+llm-streaming.zh.md: b47ae516e39cb6657ce5b6ada69d524d5f5ea174
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index 591326582c..b47ae516e3 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -2,7 +2,7 @@
 
 [English](llm-streaming.md) | 中文
 
-[`packages/llm`](../../packages/llm/README.md) 的对话与流式输出词汇：每个请求与持久历史共享的 `Message`/`ContentBlock` 形状、完整组装的模型请求、原始 `StreamChunk` 协议、每个适配器必须遵守的适配器契约（adapter contract），以及共享的 assembler。[核心主干](core.md)在每个轮次持有并记录这些值；本页声明它们。
+[`packages/llm`](../../packages/llm/README.md) 的对话与流式输出词汇：每个请求与持久历史共享的 `Message`/`ContentBlock` 形状、完整组装的模型请求、原始 `StreamChunk` 协议、每个适配器必须遵守的适配器约定（adapter contract），以及共享的 assembler。[核心主干](core.md)在每个轮次持有并记录这些值；本页声明它们。
 
 源码：[`packages/llm/llm/src/types.ts`](../../packages/llm/llm/src/types.ts)
 
@@ -202,7 +202,7 @@ interface LlmFailure {
 }
 ```
 
-## 适配器契约
+## 适配器约定
 
 每个适配器必须遵守以下规则，每个消费方可以依赖它们：
 
@@ -216,7 +216,7 @@ interface LlmFailure {
 - **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
 - **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容与 provenance，不会收到私有状态。
 
-该契约由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
+该约定由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
 
 ## `ResolvedRetryPolicy`
 
@@ -224,7 +224,7 @@ interface LlmFailure {
 
 ## `AppIdentity`：应用归属
 
-每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该契约有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包（package） manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
+每个适配器都会向提供方发送的静态公开应用标识（[`packages/llm/llm/src/attribution.ts`](../../packages/llm/llm/src/attribution.ts)）。`attributionHeaders(identity?)` 只把它映射到标准 `User-Agent` header；该约定有意不支持 OpenRouter 特有的应用归属 header。默认 `APP_IDENTITY` 从包（package） manifest（元数据清单）获取版本；每个字段都是公开产品事实——不含 secret、路径、会话 id 或逐用户标识，且任何逐请求信息都不得影响这些值。设计理由见[强制 `User-Agent` 归属](../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
 
 ```ts type-equiv
 /**
@@ -504,7 +504,7 @@ interface GenerateOptions {
 }
 ```
 
-模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式契约的 [`LlmFailure`](#llmfailure)：
+模型响应为何停止由可合并扩展的原因表示。提供方终态失败携带流式约定的 [`LlmFailure`](#llmfailure)：
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index f080915228..445596fe69 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: 3bf3ac7c48bfa08be86314bb43263d4ee6198654
+subagent.md: a934c84835334cd6d31c79c4d52b4fb5ebfd722d
 subagent.zh.md: 65ea762fcddb0f7b4ef5ec977cc14f13c8bf4589
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index 3bf3ac7c48..a934c84835 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -135,7 +135,7 @@ persisted Session
 
 `running` means the Agent has an active admission or turn, or waking inbox work; `waiting` means it is quiescent but still owns at least one child Activation that has not completed disposal; `settled` means quiescent with every owned child disposed, at which point the manager disposes the [`AgentHandle`](core.md#creation-and-ownership) and removes the Activation. The manager derives these internal conditions from Agent quiescence and the owned-child set rather than maintaining a second execution state machine.
 
-The Agent inbox is the only queue. Every continuation message becomes one `Agent.followup()` FIFO turn, so accepted messages have one observable order and a follow-up cannot redirect a turn already underway. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/enqueue`, `agent/inbox/dequeue`, and `agent/inbox/discard` events remain the message-lifecycle observations, and the continuation layer defines no subagent-specific delivery route.
+The Agent inbox is the only queue. Every continuation message becomes one `Agent.followup()` FIFO turn, so accepted messages have one observable order and a follow-up cannot redirect a turn already underway. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/inserted`, `agent/inbox/claimed`, and `agent/inbox/discarded` events remain the message-lifecycle observations, and the continuation layer defines no subagent-specific delivery route.
 
 Follow-up authority comes from an exact live Agent tool context. The authenticated Agent must be the durable child's direct parent recorded in `SessionHeader.parentSession`. `MessageSource` and `senderSessionId` are durable provenance after admission and grant no authority; the optional model-facing tool uses `CoordinatorMessageSource`.
 
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 8eecc6cc4a..9e530c0668 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/tool-catalog.md
 tool-catalog.md: 8986847d1ed2fe9d64ada0c71f34700ff95fb364
-tool-catalog.zh.md: ed78883f74a7d245de97bc45d7125e6245e140ce
+tool-catalog.zh.md: 831ed5d5cdcc15f32d2a4c8673858935fca1e435
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index ed78883f74..831ed5d5cd 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -17,26 +17,26 @@
 
 | 工具包 | 模型可见名称 | 依赖 | 写入／影响 | 随产品发布的别名 | 部署说明 |
 | --- | --- | --- | --- | --- | --- |
-| `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`、`ctx.userInteraction` | `tool/call`、`UI/provider 回答问题后的 tool/result` | - | ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。 |
-| `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`、`ctx.codeRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`每个桥接子调用对应的一组 tool/code-dispatch-start + tool/code-dispatch`、`tool/result` | - | 在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 |
-| `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userInteraction (execution time, opportunistic)` | `tool/call`、`获批评审后的 plan/mode inactive`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 |
-| `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `@deepseek-ai/dsh-tool-tasks` 的 `task_*` 工具收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 |
+| `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`、`ctx.userInteraction` | `tool/call`、`tool/result after a UI/provider answers the question` | - | ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。 |
+| `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`、`ctx.codeRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`one tool/code-dispatch-start + tool/code-dispatch pair per bridged sub-call`、`tool/result` | - | 在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 |
+| `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userInteraction (execution time, opportunistic)` | `tool/call`、`plan/mode inactive on an approved review`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 |
+| `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具（来自 `@deepseek-ai/dsh-tool-tasks`）收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 |
 | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
-| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`进程本地临时 Plugin 生命周期` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 `.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md`。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
+| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`process-local temporary Plugin lifecycle` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`成功完成文件操作后的 fs/observed`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
-| `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`变更对应的 fs/write-intent 或 fs/edit-intent`、`成功完成文件操作后的 fs/observed`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after successful file operations`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
+| `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`fs/write-intent or fs/edit-intent for mutations`、`fs/observed after successful file operations`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`、`grep` | `ctx.tools`、`ctx.subprocess`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`、`terminal_list`、`terminal_open`、`terminal_read`、`terminal_send`、`terminal_signal` | `ctx.tools`、`ctx.pty`、`ctx.systemPrompt`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 |
-| `@deepseek-ai/dsh-tool-goal` | `create_goal`、`get_goal`、`update_goal` | `ctx.tools`、`ctx.agents`、`ctx.goals`、`ctx.systemPrompt`、`a calling Agent in an authorized open turn` | `tool/call`、`变更对应的 goal/change`、`tool/result` | - | create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 |
+| `@deepseek-ai/dsh-tool-goal` | `create_goal`、`get_goal`、`update_goal` | `ctx.tools`、`ctx.agents`、`ctx.goals`、`ctx.systemPrompt`、`a calling Agent in an authorized open turn` | `tool/call`、`goal/change for mutations`、`tool/result` | - | create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 |
 | `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`、`ctx.lsp`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，因此其模型可见 schema 在更换提供方时保持稳定。运行时要求已注册提供方，例如 `@deepseek-ai/dsh-lsp-local`；如果没有提供方，查询会返回结构化 `LSP_UNAVAILABLE` 错误，而不会改变 schema。 |
-| `@deepseek-ai/dsh-tool-ralph` | `ralph` | `ctx.tools`、`ctx.workflows`、`ctx.subagents`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents every fresh round)` | `tool/call`、`tool/result`、`执行期间的工作流与子会话事件` | - | 固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。 |
-| `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`、`ctx.agents`、`ctx.skills` | `tool/call`、`tool/result`、`通过 agent.inject() 注入的 user/message 替换目录` | - | - |
+| `@deepseek-ai/dsh-tool-ralph` | `ralph` | `ctx.tools`、`ctx.workflows`、`ctx.subagents`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents every fresh round)` | `tool/call`、`tool/result`、`workflow and child session events during execution` | - | 固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。 |
+| `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`、`ctx.agents`、`ctx.skills` | `tool/call`、`tool/result`、`user/message replacement catalogs via agent.inject()` | - | - |
 | `@deepseek-ai/dsh-tool-session-query` | `session_event_read`、`session_event_search`、`session_event_trace`、`session_search`、`session_trace` | `ctx.tools`、`ctx.systemPrompt`、`ctx.sessionQuery`、`a calling Agent for workspace authority` | `tool/call`、`tool/result` | - | 这 5 个只读工具会隐藏提供方游标，并根据不可变的调用 agent 会话为每个结果授权。该包需要选择启用；需要强制截止时间或限制行内输出的组合还会挂载通用超时或 spill 策略。 |
-| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`、`ctx.subagents` | `tool/call`、`tool/result`、`经所选提供方产生的子会话事件` | `subagent`、`subagent_fork` | 注册的工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述 schema 对应默认值。随产品发布的示例 agent 会为每个 subagent 后端加载一次该包，因此模型还会看到 schema 相同、绑定到 fork 后端的 `subagent_fork`；见 `packages/bundle/base/cordis.patch.yml` 和 `examples/acp-agent/cordis.yml`。 |
-| `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`、`list_agents`、`send_message` | `ctx.tools`、`ctx.subagents`、`ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`、`tool/result`、`经 ctx.subagents 产生的子会话事件` | - | 这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，并通过单独加载的 `/list-agents` 插件提供 `list_agents`，其目录行使用 sessionProjections 和实时 Agent 注册表。 |
-| `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`、`a live continuable in-process child Agent` | `tool/call`、`tool/result`、`直接父会话中的 user 角色消息` | - | 按可继续的进程内子级注册，而非全局注册，因此该 schema 仅在这种子级内部可见，并且不受其全局 `toolFilter` 影响。面向父级的 `send_message` 工具单独安装。 |
-| `@deepseek-ai/dsh-tool-tasks` | `task_kill`、`task_list`、`task_output` | `ctx.tools`、`ctx.tasks`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`通过 agent.inject() 发送后台完成通知的 user/message` | - | 与任务种类无关的后台任务控制接口：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制接口，从而启用生产方的 `ctx.tasks.start()`。 |
+| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`、`ctx.subagents` | `tool/call`、`tool/result`、`child session events through the chosen provider` | `subagent`、`subagent_fork` | 注册的工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述 schema 对应默认值。随产品发布的示例 agent 会为每个 subagent 后端加载一次该包，因此模型还会看到 schema 相同、绑定到 fork 后端的 `subagent_fork`；见 `packages/bundle/base/cordis.patch.yml` 和 `examples/acp-agent/cordis.yml`。 |
+| `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`、`list_agents`、`send_message` | `ctx.tools`、`ctx.subagents`、`ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`、`tool/result`、`child session events through ctx.subagents` | - | 这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，另由 `list_agents` 通过单独加载的 `/list-agents` 插件提供，其目录行使用 sessionProjections 和实时 Agent 注册表。 |
+| `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`、`a live continuable in-process child Agent` | `tool/call`、`tool/result`、`a user-role message in the direct parent session` | - | 按可继续的进程内子级注册，而非全局注册，因此该 schema 仅在这种子级内部可见，并且不受其全局 `toolFilter` 影响。面向父级的 `send_message` 工具单独安装。 |
+| `@deepseek-ai/dsh-tool-tasks` | `task_kill`、`task_list`、`task_output` | `ctx.tools`、`ctx.tasks`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`user/message via agent.inject() for background completion notices` | - | 与任务种类无关的后台任务控制接口：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制接口，从而启用生产方的 `ctx.tasks.start()`。 |
 | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`、`owning Agent session` | `tool/call`、`todo/write`、`tool/result` | - | todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项，因此本目录明确选择 `true`，对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具，但描述会要求只能有 1 个活动任务。 |
 | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`、`ctx.workflows`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents the script children)` | `tool/call`、`tool/result` | - | - |
 | `@deepseek-ai/dsh-tool-web` | `web_fetch`、`web_search` | `ctx.tools`、`ctx.web`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | web_search 和 web_fetch 将提供方选择置于 ctx.web 之后，使模型可见 schema 在更换后端时保持稳定。 |
@@ -147,7 +147,7 @@ ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类
 
 ### `exit_plan_mode`
 
-仅在规划模式下使用。提交计划供用户评审，并在获批后退出规划模式。发送**完整的** Markdown 计划，以一个为计划命名的 `#` 标题开头。用户可以批准（从你的下一步骤起执行计划），也可以要求继续规划；其反馈会通过工具结果返回，请修改后再次提交。
+仅在规划模式下使用。提交计划供用户评审，并在获批后退出规划模式。发送**完整的** Markdown 计划，以一个为计划命名的 # 标题开头。用户可以批准（从你的下一步骤起执行计划），也可以要求继续规划；其反馈会通过工具结果返回，请修改后再次提交。
 
 ```json
 {
@@ -208,7 +208,7 @@ ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类
 
 来源：[`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)
 
-bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `@deepseek-ai/dsh-tool-tasks` 的 `task_*` 工具收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。
+bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具（来自 `@deepseek-ai/dsh-tool-tasks`）收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。
 
 ## `@deepseek-ai/dsh-tool-pwsh`
 
@@ -307,7 +307,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
 
 ### `cordis_unmount`
 
-卸载当前进程中由 cordis_mount 创建的临时 Plugin。它会等待该插件的工具、监听器、服务、定时器及其他自有效果全部清理完成。只接受 `dyn-N` 临时 id；无法移除 Loader、已配置或已安装的 Plugin。
+卸载当前进程中由 cordis_mount 创建的临时 Plugin。它会等待该插件的工具、监听器、服务、定时器及其他自有效果全部清理完成。只接受 dyn-N 临时 id；无法移除 Loader、已配置或已安装的 Plugin。
 
 ```json
 {
@@ -326,7 +326,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
 
 来源：[`packages/self-modification/tool-cordis/src/index.ts`](../packages/self-modification/tool-cordis/src/index.ts)
 
-不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 `.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md`。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。
+不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。
 
 ## `@deepseek-ai/dsh-tool-bash-persistent`
 
@@ -361,7 +361,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
 
 * 状态会在命令调用以及与用户的讨论之间持久保留
 * 如果 `path` 是文件，`view` 会显示应用 `cat -n` 后的结果。如果 `path` 是目录，`view` 会列出最多向下 2 层的非隐藏文件和目录
-* 如果指定的 `path` 已作为文件存在，则不能使用 `create` 命令
+* 如果指定的 `create` 命令目标 `path` 已作为文件存在，则不能使用该命令
 * 如果 `command` 产生较长输出，输出会被截断并标记为 `<response clipped>`
 
 使用 `str_replace` 命令时请注意：
@@ -1266,7 +1266,7 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
 
 来源：[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
 
-这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，并通过单独加载的 `/list-agents` 插件提供 `list_agents`，其目录行使用 sessionProjections 和实时 Agent 注册表。
+这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，另由 `list_agents` 通过单独加载的 `/list-agents` 插件提供，其目录行使用 sessionProjections 和实时 Agent 注册表。
 
 ## `@deepseek-ai/dsh-tool-subagent-report`
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 57fa7ebc3f..43904e9624 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -20,15 +20,15 @@
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通包只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host 包、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` 包及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` 包 extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新包只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client 插件的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client 包，也不维护 Host/Client 包过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client 插件在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 契约产物生成构建 Agent Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约产物生成 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Agent Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Agent Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务服务在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验包入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约产物生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；包的公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通包只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host 包、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` 包及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` 包 extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新包只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client 插件的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client 包，也不维护 Host/Client 包过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client 插件在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 契约产物生成构建 Agent Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约产物生成 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Agent Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Agent Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务服务在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验包入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约产物生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；包的公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",
-        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its switchers and structural signature. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\nGenerated English references and graphs participate in pairing when a reviewed Chinese counterpart is available. Their generators remain the English source of truth and their freshness gates run before pairing; regeneration that changes English leaves the pair out of sync until the reviewed Chinese counterpart is updated and re-recorded. Generated English sources omit the language switcher that ordinary authored sources carry, because adding it would make the generator stale; their Chinese counterparts still link back to the English source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md) — generated without a reviewed Chinese counterpart, so both website locales project the English source.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
+        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its required switchers and structural signature. The Chinese file must retain its English backlink; an authored English source must retain its Chinese link, while a listed generated English source is exempt. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** The Chinese file always links back immediately after its H1 heading with `[English](foo.md) | 中文`. An authored English file reciprocates there with `English | [中文](foo.zh.md)`; a listed generated English source omits that line so it remains byte-identical to generator output.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery is case-insensitive on the basename, so `missions/readme.md` is in scope alongside the other documentation roots.\n2. Every pair artifact that exists at all is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), the Chinese side and every authored English source carry their language switchers (listed generated English sources are exempt), and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.\n3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all. Frozen Agent Notes under `.agents/notes/archived/` are outside this evolving gate; their dedicated verifier requires and seals the complete existing triplet instead.\n\nSource-oriented code gates consume an exact `.zh.md` fence sequence as a derivative of its unsuffixed sibling instead of compiling or manifesting the same code twice. The sequence must match in length, order, fence kind, and byte-exact body; otherwise both copies remain independently checked and the pairing gate reports the structural mismatch.\n\n`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok. It never fails; `missing` and `out-of-sync` rows identify violations that the normal check rejects.\n\n`pnpm run verify-translation-pairing <pair...>` checks just the named pairs — any of a pair's three files (or its bare stem) names it — so an update loop verifies its own pair in seconds instead of re-scanning the corpus. The no-argument corpus-wide form is what `doc-sync` and CI run; a scoped green never substitutes for it at PR level.\n\nThe practical rule this gate creates: **when a PR edits either side of a paired document, the same PR updates the counterpart and re-records the pair** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill, then `--write <pair>`), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a pair out of sync goes red in CI.\n\nThe gate's limit, stated plainly: **a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.** It checks hashes and shape; it cannot judge whether the two sides actually say the same thing, or whether the wording is accurate, well-termed, and natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.\n\n## Scope and exclusions\n\n**Scope**: every non-vendor README, plus every active document under `.agents/notes/**`, `docs/**`, and `python/**`. README matching is case-insensitive on the basename and covers future directories without another manifest edit. Dependency and ignored build-output trees and the frozen `.agents/notes/archived/` tree are discovery exclusions, not evolving translation source.\n\nGenerated English references and graphs participate in pairing when a reviewed Chinese counterpart is available. Their generators remain the English source of truth and their freshness gates run before pairing; regeneration that changes English leaves the pair out of sync until the reviewed Chinese counterpart is updated and re-recorded. Generated English sources omit the language switcher that ordinary authored sources carry, because adding it would make the generator stale; their Chinese counterparts still link back to the English source.\n\n**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md) — generated without a reviewed Chinese counterpart, so both website locales project the English source.\n- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.\n- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.\n- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.\n- `.agents/notes/archived/` — frozen historical triplets. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) validates their completeness and content seals; translation maintenance must never rewrite them.\n\n**Universal requirement**: every current or future document in scope must merge as a complete bilingual pair. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) contains only explicit exclusions; there is no per-file rollout list, date cutoff, or README-specific policy class.\n\n## Division of labor\n\nCounterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, the Chinese backlink and authored-source switcher (with the documented generated-source exception), and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the committed template (terminology injected; the template carries its own calibrated rules) into either direction and parses the three-section response, while `verify-translation-prompt` exercises both render directions and the checked-in example in `doc-sync`.\n"
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对约定\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留两侧的语言切换行和结构签名时，组合出一份新记录。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n有经评审中文对侧的生成英文参考文档和图文档遵循配对规则。生成器仍是英文真源，新鲜度门禁先于配对运行；重新生成导致英文变化后，配对会保持失去同步状态，直至经评审的中文对侧完成更新并重新记录。生成的英文源文件不含普通撰写文档所带的语言切换行，因为添加该行会使生成器报告陈旧；中文对侧仍链接回英文源。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md)：该生成文档没有经评审的中文对侧，因此网站的两个 locale 都投影英文源文件。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对约定\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留必需的语言切换行和结构签名时，组合出一份新记录。中文文件必须保留指向英文的反向链接；普通撰写的英文源必须保留指向中文的链接，而清单内的生成英文源不作此要求。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 中文文件一律在 H1 标题后立即以 `[English](foo.md) | 中文` 链回英文。普通撰写的英文文件在同一位置以 `English | [中文](foo.zh.md)` 互链；清单内的生成英文源省略此行，以便与生成器输出逐字节一致。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、中文侧和所有普通撰写的英文源都带语言切换行（清单内的生成英文源除外）、结构签名按序一致：标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。\n3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。`.agents/notes/archived/` 下冻结的 Agent Note 不受这个持续演进的门禁约束；专用校验器会要求其现有的三个配对文件完整，并将其封存。\n\n面向源码的代码门禁会把精确的 `.zh.md` 围栏序列视为其无后缀兄弟文件的派生内容，而不会再次编译相同代码或在 manifest 中重复登记。该序列必须在长度、顺序、围栏类型和按字节精确的正文上一致；否则两份副本仍会独立受检，配对门禁也会报告结构不匹配。\n\n`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态（missing、out-of-sync 或 ok）。它从不失败；其中 missing 与 out-of-sync 行指出普通检查会拒绝的违规。\n\n`pnpm run verify-translation-pairing <pair...>` 只检查被点名的配对——配对的三个文件中的任意一个（或其裸词干）都能点名它——因此更新循环几秒内就能验证自己的配对，而不必重新扫描全语料。`doc-sync` 与 CI 运行的是无参数的全语料形式；限定范围的绿灯在 PR 层面永远不能替代它。\n\n这个门禁带来的实际规则是：**当一个 PR 修改了已配对文档的任一侧时，同一个 PR 更新另一侧并重新记录配对**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill（技能），再 `--write <pair>`），与本仓库既有的代码与 README 的 doc-sync 规则完全一致。留下失去同步的配对的 PR 会在 CI 变红。\n\n把门禁的边界说白：**门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。** 它检查记录的 hash 与结构签名；它无法判断两侧是否真的在说同样的话，也无法判断措辞是否准确、术语是否得当、行文是否自然；这部分约定由评审者把关，见 [translation-rules.md](translation-rules.md)。重新记录了 hash 但另一侧翻得潦草的配对能通过门禁；它不得通过评审。\n\n## 范围与排除\n\n**范围**：除 vendor 源码外的全部 README，以及 `.agents/notes/**`、`docs/**` 与 `python/**` 下的全部活跃文档。匹配 README 时只看文件名且不区分大小写，因此今后新增的目录无需再修改 manifest。依赖目录、被忽略的构建产物目录以及冻结的 `.agents/notes/archived/` 目录树只在发现阶段排除，不属于持续演进的翻译源文档。\n\n有经评审中文对侧的生成英文参考文档和图文档遵循配对规则。生成器仍是英文真源，新鲜度门禁先于配对运行；重新生成导致英文变化后，配对会保持失去同步状态，直至经评审的中文对侧完成更新并重新记录。生成的英文源文件不含普通撰写文档所带的语言切换行，因为添加该行会使生成器报告陈旧；中文对侧仍链接回英文源。\n\n**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：\n\n- [cordis-api/inherited.md](../cordis-api/inherited.md)：该生成文档没有经评审的中文对侧，因此网站的两个 locale 都投影英文源文件。\n- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。\n- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。\n- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。\n- `.agents/notes/archived/`：冻结的历史三文件配对。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 校验其完整性和内容封存记录；翻译维护绝不能重写这些文件。\n\n**统一要求**：当前及今后纳入范围的每篇文档，合并时都必须构成完整的双语配对。[scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 只包含显式排除项；不存在逐文件推进清单、日期分界或 README 专用政策类别。\n\n## 分工\n\n这里的对侧文件由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、中文反向链接和普通撰写源的切换行（生成源按本文规则例外），以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。提示词约定也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把仓库内置的模板（注入术语表；模板自带经人工校准的规则）渲染为英译中或中译英两个方向的提示词，并解析三段式响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向与仓库内示例。\n"
       },
       {
         "role": "user",
@@ -44,7 +44,7 @@
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证契约分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
       },
       {
         "role": "user",
diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts
index 118a2023b9..073e22ff89 100644
--- a/scripts/translation-pairing-merge.spec.ts
+++ b/scripts/translation-pairing-merge.spec.ts
@@ -119,6 +119,12 @@ const otherSource = baseSource.replace('Beta base.', 'Beta other.')
 const otherZh = baseZh.replace('乙基础。', '乙对侧。')
 const mergedSource = currentSource.replace('Beta base.', 'Beta other.')
 const mergedZh = currentZh.replace('乙基础。', '乙对侧。')
+const generatedBaseSource = '# Module graph\n\nAlpha base.\n\nBeta base.\n'
+const generatedBaseZh = '# 模块图\n\n[English](module-graph.md) | 中文\n\n甲基础。\n\n乙基础。\n'
+const generatedCurrentSource = generatedBaseSource.replace('Alpha base.', 'Alpha current.')
+const generatedCurrentZh = generatedBaseZh.replace('甲基础。', '甲当前。')
+const generatedOtherSource = generatedBaseSource.replace('Beta base.', 'Beta other.')
+const generatedOtherZh = generatedBaseZh.replace('乙基础。', '乙对侧。')
 const manualBaseSource = baseSource.replace('guide.zh.md', 'manual.zh.md')
 const manualBaseZh = baseZh.replace('guide.md', 'manual.md')
 const manualCurrentSource = manualBaseSource.replace('Alpha base.', 'Alpha current.')
@@ -257,6 +263,60 @@ describe('translation pairing merge composition', () => {
     expect(result.zhHash).toBe(gitBlobHash(Buffer.from(mergedZh)))
   })
 
+  it('merges a generated source without an English language switcher', () => {
+    const fixture = createFixture(false)
+    const ancestor = record(fixture.root, 'docs/module-graph.md', generatedBaseSource, generatedBaseZh)
+    const current = record(fixture.root, 'docs/module-graph.md', generatedCurrentSource, generatedCurrentZh)
+    const other = record(fixture.root, 'docs/module-graph.md', generatedOtherSource, generatedOtherZh)
+
+    const result = mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/module-graph.i18n.yaml',
+      ancestor,
+      current,
+      other,
+    )
+
+    expect(result.sourceContent.toString('utf8')).toBe(
+      generatedCurrentSource.replace('Beta base.', 'Beta other.'),
+    )
+    expect(result.zhContent.toString('utf8')).toBe(generatedCurrentZh.replace('乙基础。', '乙对侧。'))
+  })
+
+  it('rejects an authored source without an English language switcher', () => {
+    const fixture = createFixture(false)
+    const source = baseSource.replace('English | [中文](guide.zh.md)\n\n', '')
+    const ancestor = record(fixture.root, 'docs/guide.md', source, baseZh)
+    const current = record(fixture.root, 'docs/guide.md', source, baseZh)
+    const other = record(fixture.root, 'docs/guide.md', source, baseZh)
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/guide.i18n.yaml',
+      ancestor,
+      current,
+      other,
+    )).toThrow('docs/guide.md clean merge lost its language-switcher link to guide.zh.md')
+  })
+
+  it('rejects generated Chinese content without its English backlink', () => {
+    const fixture = createFixture(false)
+    const zh = generatedBaseZh.replace('[English](module-graph.md) | 中文\n\n', '')
+    const ancestor = record(fixture.root, 'docs/module-graph.md', generatedBaseSource, zh)
+    const current = record(fixture.root, 'docs/module-graph.md', generatedBaseSource, zh)
+    const other = record(fixture.root, 'docs/module-graph.md', generatedBaseSource, zh)
+
+    expect(() => mergeTranslationPairingRecords(
+      fixture.root,
+      'docs/module-graph.i18n.yaml',
+      ancestor,
+      current,
+      other,
+    )).toThrow(
+      'docs/module-graph.zh.md clean merge lost its language-switcher link to module-graph.md',
+    )
+  })
+
   it('leaves owner-content conflicts for a human', () => {
     const fixture = createFixture(false)
     const ancestor = record(fixture.root, 'docs/guide.md', baseSource, baseZh)
diff --git a/scripts/translation-pairing-merge.ts b/scripts/translation-pairing-merge.ts
index 7c6d38469c..5ba9ceb0cb 100644
--- a/scripts/translation-pairing-merge.ts
+++ b/scripts/translation-pairing-merge.ts
@@ -15,6 +15,7 @@ import {
   linksTo,
   isTranslationScopeFile,
   parseTranslationMarkdown,
+  requiresSourceLanguageSwitcher,
   translationStructureDiff,
   translationStructureSignature,
 } from './translation-pairing.ts'
@@ -163,7 +164,7 @@ function loadRecordOwners(
 function assertMergedPairStructure(paths: TranslationPairPaths, source: Buffer, zh: Buffer): void {
   const sourceTree = parseTranslationMarkdown(source.toString('utf8'))
   const zhTree = parseTranslationMarkdown(zh.toString('utf8'))
-  if (!linksTo(sourceTree, basename(paths.zh))) {
+  if (requiresSourceLanguageSwitcher(paths.source) && !linksTo(sourceTree, basename(paths.zh))) {
     throw new Error(`${paths.source} clean merge lost its language-switcher link to ${basename(paths.zh)}`)
   }
   if (!linksTo(zhTree, basename(paths.source))) {

From 17360907f6de707fc522f46f6cae9db449fc1d19 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 12:35:06 +0800
Subject: [PATCH 453/516] docs(i18n): address terminology review findings

---
 ...andatory-app-attribution-headers.i18n.yaml |  2 +-
 ...21-mandatory-app-attribution-headers.zh.md | 10 +++---
 ...-07-05-uniform-agent-note-format.i18n.yaml |  2 +-
 ...2026-07-05-uniform-agent-note-format.zh.md |  2 +-
 ...ackage-model-experience-contract.i18n.yaml |  2 +-
 ...12-package-model-experience-contract.zh.md |  2 +-
 ...-09-chinese-contract-terminology.i18n.yaml |  6 ++++
 ...2026-08-09-chinese-contract-terminology.md | 33 +++++++++++++++++++
 ...6-08-09-chinese-contract-terminology.zh.md | 33 +++++++++++++++++++
 ...collapse-persistence-flush-state.i18n.yaml |  2 +-
 ...-23-collapse-persistence-flush-state.zh.md | 18 +++++-----
 docs/i18n/style-samples.md                    |  4 +--
 docs/i18n/translation-prompt.md               |  4 +--
 packages/llm/README.i18n.yaml                 |  2 +-
 packages/llm/README.zh.md                     |  2 +-
 packages/plan/README.i18n.yaml                |  2 +-
 packages/plan/README.zh.md                    |  2 +-
 packages/tasks/tool-tasks/README.i18n.yaml    |  2 +-
 packages/tasks/tool-tasks/README.zh.md        |  2 +-
 python/README.i18n.yaml                       |  2 +-
 python/README.zh.md                           |  2 +-
 python/sdk/README.i18n.yaml                   |  2 +-
 python/sdk/README.zh.md                       |  2 +-
 23 files changed, 106 insertions(+), 34 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.md
 create mode 100644 .agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index 43c2f227df..6303b1e77a 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
 2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a
-2026-06-21-mandatory-app-attribution-headers.zh.md: d2f7300467790c0a67cfa0ab6222c40c9ee10311
+2026-06-21-mandatory-app-attribution-headers.zh.md: 6f0d0199f859fd462fdecc24e4063cbd27311bab
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index d2f7300467..6f0d0199f8 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -12,9 +12,9 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 ## 调研
 
-- **OpenRouter 的机制是提供方特有的。** 其当前文档说明应用归属通过 `HTTP-Referer`（必需）、`X-OpenRouter-Title` 和 `X-OpenRouter-Categories` 来追踪；`X-Title` 仅为向后兼容而接受。其 API 参考称这些头部为可选，并说它们使应用在 OpenRouter 上可被发现。这是一份具体的 OpenRouter 约定，而非 IETF 或 OpenAI 兼容 API 标准。
-- **在 agent 工具生态中，`HTTP-Referer` 是一种 OpenRouter 感知的约定，而非通用 agent 约定。** 它足够常见，以至于 OpenRouter SDK 和示例直接暴露它，面向 OpenRouter 的框架通常需要一种方式来透传它。但 ACP（Agent Client Protocol）等 agent 协议在自己的 initialize 消息中协商名称、版本和能力，而模型提供方请求仍需 HTTP 层面的身份标识。因此「在 agent 世界中被接受」意味着「被 OpenRouter 集成所识别」，而非「可跨 agent 运行时或提供方移植」。
-- **编程 agent 在 `User-Agent` 中标识产品和版本。** 公开实现在环境细节和提供方特有的附加头部上各有不同，但产品身份是共同约定；不存在通用的精确格式。
+- **OpenRouter 的机制是提供方特有的。** 其当前文档说明应用归属通过 `HTTP-Referer`（必需）、`X-OpenRouter-Title` 和 `X-OpenRouter-Categories` 来追踪；`X-Title` 仅为向后兼容而接受。其 API 参考称这些头部为可选，并说它们使应用在 OpenRouter 上可被发现。这是一项具体的 OpenRouter 惯例，而非 IETF 或 OpenAI 兼容 API 标准。
+- **在 agent 工具生态中，`HTTP-Referer` 是一种 OpenRouter 感知的惯例，而非通用 agent 惯例。** 它足够常见，以至于 OpenRouter SDK 和示例直接暴露它，面向 OpenRouter 的框架通常需要一种方式来透传它。但 ACP（Agent Client Protocol）等 agent 协议在自己的 initialize 消息中协商名称、版本和能力，而模型提供方请求仍需 HTTP 层面的身份标识。因此「在 agent 世界中被接受」意味着「被 OpenRouter 集成所识别」，而非「可跨 agent 运行时或提供方移植」。
+- **编程 agent 在 `User-Agent` 中标识产品和版本。** 公开实现在环境细节和提供方特有的附加头部上各有不同，但产品身份是共同惯例；不存在通用的精确格式。
 - **标准化的通用客户端身份头部是 `User-Agent`。** RFC 9110 第 10.1.5 节将 `User-Agent` 定义为用户代理软件身份，说明它用于互操作性报告和分析，并说用户代理应当在每个请求中发送它（除非被配置为不发送）。这是唯一直接对应「哪个产品在发出此 HTTP 请求」的标准头部。
 - **`Referer` 是标准的，但 OpenRouter 的 `HTTP-Referer` 不是标准字段。** RFC 9110 第 10.1.3 节将 `Referer` 定义为获取目标 URI 的来源 URI，并用大量篇幅讨论隐私限制。OpenRouter 则要求 `HTTP-Referer`，将其用作应用 URL 标识符。该名称和含义是 OpenRouter 特有的，尽管它形似标准 `Referer` 头部的 CGI 环境变量形式。
 - **`From` 是标准的，但不适合作为强制默认值。** RFC 9110 第 10.1.2 节将 `From` 定义为负责用户代理的人的电子邮件地址。机器人代理应当发送它以便服务器联系运营者，但非机器人代理出于隐私和安全策略考虑不应在未经用户显式配置的情况下发送。harness 可以后续支持运营者联系方式，但不得凭空捏造或全局强制要求。
@@ -51,7 +51,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 已落地的约定：
 
-- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属约定（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器约定章节）。
+- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属约定（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器约定（adapter contract）章节）。
 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。
 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。
 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。
@@ -63,7 +63,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 **现在就实现 OpenRouter 应用归属。** 本 Agent Note 否决。发送 `HTTP-Referer` 加 `X-OpenRouter-Title` 可以满足 OpenRouter 排名，但这些头部是提供方特有的产品功能，不是本 Agent Note 试图标准化的提供方无关的模型请求归属。支持它们应当是后续显式的 OpenRouter 适配器/模式决策，而非隐藏在首个共享归属辅助函数中。
 
-**向所有提供方发送 OpenRouter 头部。** 否决。这会把一份自定义的 OpenRouter 约定当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
+**向所有提供方发送 OpenRouter 头部。** 否决。这会把一项自定义的 OpenRouter 惯例当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
 
 **仅使用提供方账户/项目身份。** 否决。组织/项目头部、API key、云账户和计费项目标识的是谁付费或谁拥有请求，而非哪个应用在发送流量。它们也不暴露公开的应用标题/类别，无法帮助 OpenRouter 等网关构建应用排名。
 
diff --git a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
index 3b2ed0f39d..ae738e3fad 100644
--- a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.md
 2026-07-05-uniform-agent-note-format.md: 06082251c1b96c90ed470d84224662e00e29791b
-2026-07-05-uniform-agent-note-format.zh.md: a13c436a3fa157a0bfe551a7ed0594d052a4de90
+2026-07-05-uniform-agent-note-format.zh.md: 3daa686b64b31ee2638b25dd4c42e5d8172f1d97
diff --git a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
index a13c436a3f..3daa686b64 100644
--- a/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
+++ b/.agents/notes/implemented/process/2026-07-05-uniform-agent-note-format.zh.md
@@ -22,7 +22,7 @@ Agent Note 的路径编码了生命周期和类别，但文件内容仍混杂着
 - **带日期的 Status**（`Status: implemented (accepted YYYY-MM-DD)`）：否决。接受日期属于叙述性历史，写作规则将其排除在文档之外；文件名承载首次提出日期，git 承载其余信息；门禁能检查日期格式，但永远无法检查其真实性。
 - **裸 `# <title>` H1**：否决。文件脱离目录树单独阅读时，`Agent Note: ` 前缀能自描述其体裁，而格式门禁可防止它漂移。
 - **以 `## What we give up` 作为已实现记录的结尾**（README 对 Agent Note 所记录内容的原有表述）：否决。它只点出成本，而诚实的后果章节也会记录取舍换来了什么。
-- **只有约定没有门禁**（写下约定，靠评审强制执行）：否决。slop checklist 已经通过约定禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠约定在此处能达到什么效果。
+- **只有惯例没有门禁**（写下约定，靠评审强制执行）：否决。slop checklist 已经通过惯例禁止在 `implemented/` 中使用 spec 语气，而十九个文件展示了仅靠惯例在此处能达到什么效果。
 - **独立的 `FORMAT.md` 约定文件**：否决。由一个入口同时承载布局、分类和格式，比维护两个约定文件更易发现和维护。
 
 ## 后果
diff --git a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
index 091a912f94..444389759b 100644
--- a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
 2026-07-12-package-model-experience-contract.md: 92a8e5a1a81d00dae085e4af89456896373058e6
-2026-07-12-package-model-experience-contract.zh.md: 9fb6e36e75dcca43fd3ed450c364c57ae7fb7ca4
+2026-07-12-package-model-experience-contract.zh.md: ded8c9fd940b986d9b37ad1563060b8b96e966bb
diff --git a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
index 9fb6e36e75..ded8c9fd94 100644
--- a/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
+++ b/.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 - **使用表格**：否决。精确源码文本和条件式结果形状会使单元格密集而难以扫读。重复的小节在保留相同字段的同时，为每个上下文表面提供易读的纵向空间。
 - **允许所有零影响包省略该章节**：否决。无约束的缺失在「经审计的零影响」和「忘记写文档」之间有歧义。省略仅限于在验证器中以理由命名的模型无关通用包；模型相邻的零影响包保留一句显式说明。
 - **要求经审计的零效应包或简单间接包使用完整结构化格式**：否决。它会围绕一个事实重复标签。受门禁约束的句子加 cache 字段既保留显式覆盖，又没有多余仪式。
-- **只有约定而无门禁**：否决。仓库级约定必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
+- **只有惯例而无门禁**：否决。仓库级约定必须覆盖未来的每个包；评审者的记忆无法可靠地检测到遗漏的 README 章节。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.i18n.yaml
new file mode 100644
index 0000000000..408f164e06
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.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/process/2026-08-09-chinese-contract-terminology.md
+2026-08-09-chinese-contract-terminology.md: d2fea45c6864a19b89c78a52f614ccac341a0127
+2026-08-09-chinese-contract-terminology.zh.md: 772b78daba00c5d881fd0091951557dfc0951ee9
diff --git a/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.md b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.md
new file mode 100644
index 0000000000..d2fea45c68
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.md
@@ -0,0 +1,33 @@
+# Agent Note: Standardize Chinese contract terminology on 约定
+
+Status: implemented
+
+English | [中文](2026-08-09-chinese-contract-terminology.zh.md)
+
+## Problem
+
+The Chinese documentation rendered English `contract` inconsistently as `契约` and `约定`, sometimes within one file or paragraph. The terminology table prescribed `契约`, while reviewed incremental proofreading selected the more natural engineering rendering `约定`. Leaving the table and corpus split made either choice fail the repository's terminology rule and allowed later translations to reintroduce the disagreement.
+
+English `convention` also commonly renders as `约定`. That overlap is intentional: ordinary Chinese engineering prose uses `约定` for both concepts, and context normally carries whether a statement is descriptive practice or a binding interface rule. Where an English sentence explicitly contrasts a convention with a contract, the Chinese sentence must preserve the distinction through wording such as `惯例` versus `约定`, rather than mechanically giving every `convention` the same rendering.
+
+## Decision
+
+The terminology source of truth defines `contract` as `约定` and `adapter contract` as `适配器约定（adapter contract）` on first mention. Every active Chinese documentation pair follows that ruling; archived Agent Notes remain frozen. Unpaired bilingual calibration assets and the translation prompt's explanatory prose follow the same terms so they cannot teach the superseded rendering.
+
+The migration is semantic prose maintenance, not a rename of identifiers. Inline code, file paths, links, API names, English filenames containing `contract`, and machine-readable values remain unchanged. `convention` does not receive a global terminology row or corpus-wide rewrite: translators preserve natural Chinese and explicitly disambiguate only where the source contrasts the two concepts.
+
+## Alternatives considered
+
+**Keep `contract` as `契约`.** Rejected because the reviewed corpus consistently preferred `约定` for technical interfaces, lifecycle guarantees, and behavioral boundaries, and maintaining the older term would require reverting accepted proofreading across many documents.
+
+**Give `convention` a mandatory global rendering.** Rejected because its meaning ranges from naming practice to protocol convention. A single forced term would create a second broad migration without improving ordinary prose; only explicit source contrasts require a distinct rendering.
+
+**Permit both `契约` and `约定` for `contract`.** Rejected because it preserves the exact inconsistency that made package families and even individual paragraphs disagree.
+
+## Consequences
+
+Active Chinese documentation has one binding rendering for `contract`, and future translation prompts receive that decision directly from the terminology table. Archived records keep their historical text. A source sentence that contrasts convention and contract requires local semantic wording, so equal Chinese dictionary choices never erase a distinction the source actually uses.
+
+## Verification
+
+The migration scans every active bilingual pair, updates each affected Chinese document, re-records its pairing sidecar, and leaves active prose with no `契约` occurrences. The pairing gate, full `doc-sync`, website build, translation prompt tests and snapshot, and `git diff --check` verify the resulting corpus and pipeline assets.
diff --git a/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.zh.md b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.zh.md
new file mode 100644
index 0000000000..772b78daba
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-chinese-contract-terminology.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 将中文 contract 术语统一为「约定」
+
+Status: implemented
+
+[English](2026-08-09-chinese-contract-terminology.md) | 中文
+
+## 问题
+
+中文文档对英文 `contract` 的译法在「契约」与「约定」之间不一致，有时甚至出现在同一文件或段落中。术语表规定使用「契约」，而经过评审的增量复校选择了更符合工程语境的「约定」。若术语表与语料继续分裂，无论选择哪一种译法都会违反仓库术语规则，后续翻译也会再次引入分歧。
+
+英文 `convention` 也常译为「约定」。这种重合是有意保留的：普通中文工程文体会用「约定」表达这两个概念，通常可由上下文判断它描述的是惯常做法还是有约束力的接口规则。如果英文句子明确对比 convention 与 contract，中文必须通过「惯例」与「约定」等措辞保留这种区分，而不能机械地把每个 `convention` 都译成同一个词。
+
+## 决策
+
+术语真源规定 `contract` 译为「约定」，`adapter contract` 首次出现时写作「适配器约定（adapter contract）」。所有活跃中文文档配对均遵循该裁决；归档 Agent Note 保持冻结。未参与配对的双语校准资产和翻译提示词说明文字也采用相同术语，避免继续教授已被取代的译法。
+
+这次迁移只维护语义正文，不重命名标识符。行内代码、文件路径、链接、API 名称、文件名中包含的英文 `contract` 以及机器可读值均保持不变。`convention` 不新增全局术语行，也不做全语料改写：翻译时保留自然中文，只在源文明确对比两个概念时消歧。
+
+## 考虑过的替代方案
+
+**继续把 `contract` 译为「契约」。** 否决，因为经过评审的语料在技术接口、生命周期保证和行为边界中一致倾向使用「约定」；保留旧术语意味着回退大量已接受的复校结果。
+
+**为 `convention` 规定强制的全局译法。** 否决，因为它既可表示命名惯例，也可表示协议约定。强制一种译法会带来另一轮大规模迁移，却无法改善普通行文；只有源文明示对比时才需要使用不同措辞。
+
+**允许 `contract` 同时使用「契约」与「约定」。** 否决，因为这会保留导致包家族乃至同一段落互相矛盾的原始问题。
+
+## 后果
+
+活跃中文文档对 `contract` 只有一种有约束力的译法，后续翻译提示词会直接从术语表获得该决定。归档记录保留历史文字。源文若对比 convention 与 contract，仍需在局部使用语义化措辞，因此相同的常用中文译法不会抹去源文真正表达的区别。
+
+## 验证
+
+迁移扫描每一组活跃双语配对，更新受影响的中文文档并重新记录对应 sidecar，使活跃正文不再出现「契约」。配对门禁、完整 `doc-sync`、网站构建、翻译提示词测试与快照，以及 `git diff --check` 共同验证最终语料和流水线资产。
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
index 33051c7a3d..23214f72f8 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md
 2026-07-23-collapse-persistence-flush-state.md: 2801079e5b322d076eced3a0113e7958d9b4c3b9
-2026-07-23-collapse-persistence-flush-state.zh.md: 48896c7080ae28174e259318869c65b48b13418e
+2026-07-23-collapse-persistence-flush-state.zh.md: 2f7ed68984694ff8555aaef12f732a42d9305805
diff --git a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
index 48896c7080..2f7ed68984 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 将实时持久化归并到单个刷新控制器
+# Agent Note: 将实时持久化归并到单个刷写控制器
 
 Status: implemented
 
@@ -12,25 +12,25 @@ Status: implemented
 
 ## 决策
 
-每个活跃的 `Session` 都有一个生命周期条目，其中包含初始化和一个包私有写入控制器。该控制器负责 `pending`、固定批处理计时器、可选的活跃写入、自动重试暂停和共享刷新屏障。`session/event` 监听器将冻结的事件复制到 `pending`；第一个事件设定固定截止时间，后续事件加入但不会重置。一次写入会取出一个稳定的待处理前缀；写入期间接纳的事件仍留在待处理队列中，并形成另一个独立有界的后续批次。
+每个活跃的 `Session` 都有一个生命周期条目，其中包含初始化和一个包私有写入控制器。该控制器负责 `pending`、固定批处理计时器、可选的活跃写入、自动重试暂停和共享刷写屏障。`session/event` 监听器将冻结的事件复制到 `pending`；第一个事件设定固定截止时间，后续事件加入但不会重置。一次写入会取出一个稳定的待处理前缀；写入期间接纳的事件仍留在待处理队列中，并形成另一个独立有界的后续批次。
 
-`session/flush` 是即时完全停稳屏障。它等待初始化完成、取消批处理计时器、等待任何活跃尝试完成，并排空待处理事件，包括屏障运行期间接纳的事件。后台写入失败会被记录，但不会拒绝同步事件生产方；系统会恢复完整且顺序不变的批次，并暂停自动重试。新事件会开启新的固定窗口；显式刷新、退役或后端资源销毁会立即重试，并在失败再次发生时向调用方暴露失败。
+`session/flush` 是即时完全停稳屏障。它等待初始化完成、取消批处理计时器、等待任何活跃尝试完成，并排空待处理事件，包括屏障运行期间接纳的事件。后台写入失败会被记录，但不会拒绝同步事件生产方；系统会恢复完整且顺序不变的批次，并暂停自动重试。新事件会开启新的固定窗口；显式刷写、退役或后端资源销毁会立即重试，并在失败再次发生时向调用方暴露失败。
 
 初始化只进入现有的按 id 操作链一次，并在占有该轮执行权时调用未串行化的核心操作。该操作链与活跃控制器保持分离，因为公共 `create`、`append`、`load` 调用即使没有 `Session` 对象仍可能发生竞态，依然需要按标识串行执行。
 
-崩溃修复仅适用于冷态标识。对于活跃标识，`load(id)` 会在等待刷新完成前，先对内存中的权威事件生成快照，再将这些事件与 `SessionState.meta`（即持久化写入实际使用的标头）一同返回；若轮次仍打开，则在不读取或修复存储的情况下拒绝该次加载。冷态加载会先在按 id 操作链内同步占用对应标识，再等待读取已存储前缀或执行修复写入；在这项占用解除前，`session/created` 发布边界会拒绝同 id 活跃会话的发布并将其回滚。HMR（热模块替换）接管仍由 `loadStored` 与协调器的 cwd 检查独立处理，会截断撕裂的存储，但不会闭合权威的活跃轮次。
+崩溃修复仅适用于冷态标识。对于活跃标识，`load(id)` 会在等待刷写完成前，先对内存中的权威事件生成快照，再将这些事件与 `SessionState.meta`（即持久化写入实际使用的标头）一同返回；若轮次仍打开，则在不读取或修复存储的情况下拒绝该次加载。冷态加载会先在按 id 操作链内同步占用对应标识，再等待读取已存储前缀或执行修复写入；在这项占用解除前，`session/created` 发布边界会拒绝同 id 活跃会话的发布并将其回滚。HMR（热模块替换）接管仍由 `loadStored` 与协调器的 cwd 检查独立处理，会截断撕裂的存储，但不会闭合权威的活跃轮次。
 
-活跃控制器映射同时也是退役注册表。退役成功时，系统排空并移除其控制器；退役失败时，控制器保留在映射中。后端资源销毁会停止接纳事件，刷新所有仍存在的控制器，等待其余按 id 操作完成，然后关闭后端。无需另设退役集合来重新发现未完成的工作。
+活跃控制器映射同时也是退役注册表。退役成功时，系统排空并移除其控制器；退役失败时，控制器保留在映射中。后端资源销毁会停止接纳事件，刷写所有仍存在的控制器，等待其余按 id 操作完成，然后关闭后端。无需另设退役集合来重新发现未完成的工作。
 
 ## 备选方案
 
 **保留仅由检查点触发的延后写入。** 这种方式可以形成更大的批次，但会让持久性依赖另行挂载的检查点策略，并使检查点之间因崩溃而丢失数据的窗口达到最大。有界后台调度仍会合并突发事件，并在强制屏障之间持久化进度。
 
-**在整个协调器范围内使用一个刷新 promise。** 这种挂接方式适用于单个文件，但全局 promise 会串行化互不相关的会话。每个活跃会话各有一个控制器，既能让不同会话的后端操作独立推进，又由按 id 操作链保护同一标识的操作。
+**在整个协调器范围内使用一个刷写 promise。** 这种挂接方式适用于单个文件，但全局 promise 会串行化互不相关的会话。每个活跃会话各有一个控制器，既能让不同会话的后端操作独立推进，又由按 id 操作链保护同一标识的操作。
 
-**永久锁存首次后台写入错误。** 这会让后续每次刷新都得到确定的结果，却会阻止现有的资源销毁重试从暂时性存储故障中恢复。保留批次但不锁存错误，可以同时保留可观测性和重试能力。
+**永久锁存首次后台写入错误。** 这会让后续每次刷写都得到确定的结果，却会阻止现有的资源销毁重试从暂时性存储故障中恢复。保留批次但不锁存错误，可以同时保留可观测性和重试能力。
 
-**拒绝对所有活跃会话的加载。** 这样做很安全，但会让持久化消费方和测试无法再使用既有的闭合活跃会话快照。先生成快照再刷新，为调用提供了稳定的线性化点：刷新成功即可证明正是该快照已持久化，而活跃路径绝不调用崩溃修复。
+**拒绝对所有活跃会话的加载。** 这样做很安全，但会让持久化消费方和测试无法再使用既有的闭合活跃会话快照。先生成快照再刷写，为调用提供了稳定的线性化点：刷写成功即可证明正是该快照已持久化，而活跃路径绝不调用崩溃修复。
 
 ## 验证
 
@@ -44,6 +44,6 @@ Status: implemented
 
 ## 后果
 
-活跃会话条目把初始化与一个控制器放在一起；该控制器负责待处理事件、计时器、活跃写入、重试暂停和刷新屏障。协调器仍以独立容器保存已持久化的标识状态、准备好的冷态 Session、标识退役等待方和按 id 操作链，因为即使不存在可写的活跃 Session，这些生命周期仍然存在。有界写入缩短了通常情况下因崩溃而丢失数据的窗口，相比即时调度产生更少的后端批次，同时不改变强制屏障。
+活跃会话条目把初始化与一个控制器放在一起；该控制器负责待处理事件、计时器、活跃写入、重试暂停和刷写屏障。协调器仍以独立容器保存已持久化的标识状态、准备好的冷态 Session、标识退役等待方和按 id 操作链，因为即使不存在可写的活跃 Session，这些生命周期仍然存在。有界写入缩短了通常情况下因崩溃而丢失数据的窗口，相比即时调度产生更少的后端批次，同时不改变强制屏障。
 
 `session/flush` 不再决定普通持久化何时开始。它仍是循环和检查点策略使用的顺序与错误观测边界，因此检查点成功仍表示在其完成前接纳的每个事件都已持久化。
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index 432c95e684..1b8a0e3f1a 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -16,7 +16,7 @@
 
 > This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the generated regions of [subsystems/](../subsystems/core.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
 
-本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见 [subsystems/](../subsystems/core.md) 中的生成区块；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见 [subsystems/](../subsystems/core.md) 中的生成区块；各包（package）的对外约定写在相应的 README 中（[索引](../../packages/README.md)）。
 
 ## ② 防御模式规则
 
@@ -60,7 +60,7 @@
 
 > The gate's limit, stated plainly: a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound. It checks hashes and shape; it cannot judge whether the two sides actually say the same thing — that is the reviewer's half of the contract. A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.
 
-门禁的边界很明确：通过门禁只说明两侧文件当前的 blob hash 与伴随记录吻合，并且结构签名一致，也就是说，这组内容曾被确认一致；它不代表这次确认可靠。门禁无法判断两种语言是否真正表达了相同的意思；这部分契约要由评审人把关。即使译文粗糙、表意有误，重新记录配对后仍能通过门禁，但绝不能通过人工评审。
+门禁的边界很明确：通过门禁只说明两侧文件当前的 blob hash 与伴随记录吻合，并且结构签名一致，也就是说，这组内容曾被确认一致；它不代表这次确认可靠。门禁无法判断两种语言是否真正表达了相同的意思；这部分约定要由评审人把关。即使译文粗糙、表意有误，重新记录配对后仍能通过门禁，但绝不能通过人工评审。
 
 ## ⑥ Agent Note 论证
 
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index 0f8b836da4..06e426aa5c 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -1,8 +1,8 @@
 # Translation prompt (pipeline asset)
 
-本文件是自动翻译流水线的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。模板正文与内嵌 few-shot 正误例由 jingtingxiang 基于对存量译文的质量评审撰写，是流水线行为的拍板基线。渲染时把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`；除此之外不注入任何其他仓库文件（translation-rules.md 约束人和 agent 的翻译工作，不注入本模板）。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题，两者冲突时以文体样例为准。[提示词 v4 契约 Agent Note](../../.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md) 记录兼容协议；v7 保留该协议并选择性吸收经评估的生成质量改进。修改本文件会改变翻译行为，需正常经过 PR 评审。
+本文件是自动翻译流水线的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。模板正文与内嵌 few-shot 正误例由 jingtingxiang 基于对存量译文的质量评审撰写，是流水线行为的拍板基线。渲染时把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`；除此之外不注入任何其他仓库文件（translation-rules.md 约束人和 agent 的翻译工作，不注入本模板）。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题，两者冲突时以文体样例为准。[提示词 v4 约定 Agent Note](../../.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md) 记录兼容协议；v7 保留该协议并选择性吸收经评估的生成质量改进。修改本文件会改变翻译行为，需正常经过 PR 评审。
 
-## 占位符契约
+## 占位符约定
 
 流水线渲染模板时替换以下占位符，除此之外不改写系统消息：
 
diff --git a/packages/llm/README.i18n.yaml b/packages/llm/README.i18n.yaml
index a3ccfcf944..a8bc82817f 100644
--- a/packages/llm/README.i18n.yaml
+++ b/packages/llm/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/README.md
 README.md: 077ae600c89cff80cd71830e37bda00707c1d837
-README.zh.md: 95355d34c014a1b442da1028251301d6d4202c6b
+README.zh.md: 46d4aa8a6088b3d5f40718f0c2626783e6c05c4b
diff --git a/packages/llm/README.zh.md b/packages/llm/README.zh.md
index 95355d34c0..46d4aa8a60 100644
--- a/packages/llm/README.zh.md
+++ b/packages/llm/README.zh.md
@@ -14,4 +14,4 @@ LLM seam 及其提供方适配器。接口包（`llm`）负责抽象服务、内
 
 适配器在 seam 上注册提供方路由；重试与 token 测量仍是独立消费方。子 README 负责路由、元数据、回放和提供方协议细节；[LLM 架构决策](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)负责设计原理。
 
-子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器约定——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
+子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器约定（adapter contract）——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
diff --git a/packages/plan/README.i18n.yaml b/packages/plan/README.i18n.yaml
index 8291b525f1..c2a60d7d2d 100644
--- a/packages/plan/README.i18n.yaml
+++ b/packages/plan/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/plan/README.md
 README.md: 535a2b02e297d7c3bc68538fa1d03226089372e0
-README.zh.md: 1b28af328f6da5cfabb09093c339f6504316f0e7
+README.zh.md: 0ee1c658ee0a7863eb16b99d956e882f320a3717
diff --git a/packages/plan/README.zh.md b/packages/plan/README.zh.md
index 1b28af328f..0ee1c658ee 100644
--- a/packages/plan/README.zh.md
+++ b/packages/plan/README.zh.md
@@ -10,4 +10,4 @@ Plan mode 是按 agent（智能体）记录的协作状态，而不是通用模
 
 [plan 专用协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)决策记录了该家族的设计。
 
-子系统参考——`plan/mode` 折叠、步骤边界刷新、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
+子系统参考——`plan/mode` 折叠、步骤边界刷写、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。
diff --git a/packages/tasks/tool-tasks/README.i18n.yaml b/packages/tasks/tool-tasks/README.i18n.yaml
index 65b1128efb..24e6b6892a 100644
--- a/packages/tasks/tool-tasks/README.i18n.yaml
+++ b/packages/tasks/tool-tasks/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/tool-tasks/README.md
 README.md: 6e8e889c2330d6991cb384674b011e4d2e988268
-README.zh.md: 3b9dbd4f895eb38f0ffc7951169ff292da8603f1
+README.zh.md: 355b6736b476fb2434f17ea3857544f32c40adb3
diff --git a/packages/tasks/tool-tasks/README.zh.md b/packages/tasks/tool-tasks/README.zh.md
index 3b9dbd4f89..355b6736b4 100644
--- a/packages/tasks/tool-tasks/README.zh.md
+++ b/packages/tasks/tool-tasks/README.zh.md
@@ -18,7 +18,7 @@
 
 ## 完成通知
 
-一项尚未报告的完成会把 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` 注入到确切所有者的 next-step 收件箱。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。注入是等待后续 pre-step 领取的持久上下文，并非唤醒；取消或 owner 释放可能在领取前丢弃它。kill 或针对已终止任务的 read/wait 会把交付标为已报告，并抑制重复通知。
+一项尚未报告的完成会把 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` 注入到确切所有者的 next-step inbox。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。注入是等待后续 pre-step 领取的持久上下文，并非唤醒；取消或 owner 释放可能在领取前丢弃它。kill 或针对已终止任务的 read/wait 会把交付标为已报告，并抑制重复通知。
 
 ## 配置
 
diff --git a/python/README.i18n.yaml b/python/README.i18n.yaml
index 249bf6bb76..9e0a17e270 100644
--- a/python/README.i18n.yaml
+++ b/python/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write python/README.md
 README.md: 27637edb9d4d5e8714fe379a00b6aae3af1a541f
-README.zh.md: 9eed37aa10cc1bc1265938968d8084ce1ef840ce
+README.zh.md: b0587b25b66750780768786e02b02037dd10ec0a
diff --git a/python/README.zh.md b/python/README.zh.md
index 9eed37aa10..b0587b25b6 100644
--- a/python/README.zh.md
+++ b/python/README.zh.md
@@ -13,7 +13,7 @@
 
 ## 行为
 
-除非调用方选择显式通道，否则 SDK 会启动匹配的内置运行时。客户端负责选择通道和注入默认配置；运行时本身始终要求显式配置。完整的解析与配置约定分别由 [SDK 参考](sdk/README.md) 和 [运行时载体参考](sdk-runtime/README.md) 定义。
+除非调用方选择显式通道，否则 SDK 会启动匹配的内置运行时。客户端负责选择通道和注入默认配置；运行时本身始终要求显式配置。完整的解析与配置约定分别由 [SDK 参考](sdk/README.md)和[运行时载体参考](sdk-runtime/README.md)定义。
 
 ## 贡献者工作流
 
diff --git a/python/sdk/README.i18n.yaml b/python/sdk/README.i18n.yaml
index 081b8eb17e..6467b4ca87 100644
--- a/python/sdk/README.i18n.yaml
+++ b/python/sdk/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write python/sdk/README.md
 README.md: 2d545688c58a2f1b755e647d7cda9555249e41c4
-README.zh.md: 3f1e15bf8a148efd18fe66272bec2e0b28de8d21
+README.zh.md: b335d75aedc3a145771b23ea5d408315cae9a3e3
diff --git a/python/sdk/README.zh.md b/python/sdk/README.zh.md
index 3f1e15bf8a..b335d75aed 100644
--- a/python/sdk/README.zh.md
+++ b/python/sdk/README.zh.md
@@ -31,7 +31,7 @@ with DeepSeekHarness(
 
 `provider` 用于选择当前 Cordis 组合已注册的提供方路由；`model` 是该适配器解析的模型 ID。`max_tokens` 是可选的正整数，用于限制根 agent（智能体）及其进程内后代每次请求的输出 token；省略时由提供方默认值控制。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 `deepseek-official`。自定义组合可以挂载 `llm-pi-ai`，在其中配置各提供方的凭据与端点，再选择 pi-ai 已安装目录中的任意提供方/模型组合。
 
-`Session.run()` 拥有一个从收件箱持久接收该提示词时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
+`Session.run()` 拥有一个从提示词进入持久 inbox 时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
 
 `HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 `Session.run()` 时，`RunResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`RunResult.events` 只包含根会话事件，因此后代消息不会覆盖根会话回复。底层 `session_prompt()` 会立即返回已排队消息的 `MessageId`；绕过 `Session.run()` 的调用方必须自行负责后续的活动边界。
 

From 76b3353452fd46f2fa27453d18985fab994d14d7 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Wed, 22 Jul 2026 18:02:26 +0800
Subject: [PATCH 454/516] docs: call waterfall interception short-circuiting

---
 .../2026-06-11-microkernel-event-taxonomy.i18n.yaml           | 4 ++--
 .../architecture/2026-06-11-microkernel-event-taxonomy.md     | 2 +-
 .../architecture/2026-06-11-microkernel-event-taxonomy.zh.md  | 2 +-
 .../2026-07-12-agent-scope-runtime-design.i18n.yaml           | 4 ++--
 .../architecture/2026-07-12-agent-scope-runtime-design.md     | 4 ++--
 .../architecture/2026-07-12-agent-scope-runtime-design.zh.md  | 4 ++--
 .../2026-07-08-self-referential-cordis-toolset.i18n.yaml      | 4 ++--
 .../feature/2026-07-08-self-referential-cordis-toolset.md     | 2 +-
 .../feature/2026-07-08-self-referential-cordis-toolset.zh.md  | 2 +-
 AGENTS.md                                                     | 2 +-
 docs/architecture.i18n.yaml                                   | 4 ++--
 docs/architecture.md                                          | 2 +-
 docs/architecture.zh.md                                       | 2 +-
 docs/cordis-api/inherited.md                                  | 2 +-
 docs/tool-catalog.md                                          | 2 +-
 docs/user/develop/framework/events.i18n.yaml                  | 4 ++--
 docs/user/develop/framework/events.md                         | 4 ++--
 docs/user/develop/framework/events.zh.md                      | 4 ++--
 .../snapshots/advanced-toolchain/system-prompt.expected.md    | 2 +-
 .../snapshots/advanced-toolchain/tool-schemas.expected.json   | 2 +-
 .../tests/snapshots/cordis-inspect-jsdoc/session.jsonl        | 2 +-
 .../tests/snapshots/advanced-toolchain/session.1.jsonl        | 2 +-
 .../tests/snapshots/advanced-toolchain/session.2.jsonl        | 2 +-
 .../tests/snapshots/advanced-toolchain/session.jsonl          | 2 +-
 packages/core/agent-loop/tests/loop.spec.ts                   | 2 +-
 packages/self-modification/tool-cordis/src/api-catalog.ts     | 2 +-
 packages/self-modification/tool-cordis/src/index.ts           | 2 +-
 packages/self-modification/tool-cordis/src/inspect.ts         | 2 +-
 packages/self-modification/tool-cordis/tests/inspect.spec.ts  | 4 ++--
 scripts/gen-cordis-catalog.ts                                 | 2 +-
 30 files changed, 40 insertions(+), 40 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
index 1d561dd14a..5a5aa0eaea 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.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 .agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
-2026-06-11-microkernel-event-taxonomy.md: 202595fed125966a5d77920536e7f4ee88f875fe
-2026-06-11-microkernel-event-taxonomy.zh.md: 1365910157c36699bfe1fdb3a10aa0785948e0fa
+2026-06-11-microkernel-event-taxonomy.md: fe6c242acbc0b64123711a17a528f35c02d91087
+2026-06-11-microkernel-event-taxonomy.zh.md: aa3db53d640145836817f9835a30c69815f70d23
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
index 202595fed1..fe6c242acb 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
@@ -12,7 +12,7 @@ The product principle is "everything is a plugin": hooks, /goal, /loop, dynamic
 
 Pure Cordis event taxonomy. The loop's extension seams are typed events with deliberate dispatch modes:
 
-- **waterfall** (around-middleware) where plugins transform, veto, recover, or wrap: `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/pre-execute`, `tools/execute`, `tools/post-execute`, `llm/stream`, `system-prompt/assemble`.
+- **waterfall** (around-middleware) where plugins transform, short-circuit, recover, or wrap: `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/pre-execute`, `tools/execute`, `tools/post-execute`, `llm/stream`, `system-prompt/assemble`.
 - **serial** (awaited in listener order) for ordered checkpoints such as `agent/turn-stopping`.
 - **parallel** (awaited fan-out) where every listener must get an independent chance: the `session/flush` durability checkpoint.
 - **emit** (synchronous fire-and-forget) for notifications: inbox transitions, lifecycle, errors, and the contained immutable `tools/result` observation. Durable session events own turn and step boundaries.
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
index 1365910157..aa3db53d64 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 纯 Cordis 事件分类体系。agent loop（智能体循环）的扩展 seam 是带类型的事件，具有明确的分发模式：
 
-- **waterfall（瀑布式事件）**（around-middleware）：插件可变换、否决、恢复或包装：`agent/pre-step`、`agent/request`、`agent/request-error`、`tools/pre-execute`、`tools/execute`、`tools/post-execute`、`llm/stream`、`system-prompt/assemble`。
+- **waterfall（瀑布式事件）**（around-middleware）：插件可变换、短路、恢复或包装：`agent/pre-step`、`agent/request`、`agent/request-error`、`tools/pre-execute`、`tools/execute`、`tools/post-execute`、`llm/stream`、`system-prompt/assemble`。
 - **serial**（按监听器顺序依次 await）：用于 `agent/turn-stopping` 等有序检查点。
 - **parallel**（await 扇出）：每个监听器都必须获得独立执行的机会：`session/flush` 持久性检查点。
 - **emit**（同步 fire-and-forget）：用于通知：inbox 转换、生命周期、错误，以及受错误隔离的 `tools/result` 观测；该观测接收不可变的最终结果。轮次与步骤边界由持久会话事件拥有。
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index 380171ab17..f5fdd4e906 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.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 .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
-2026-07-12-agent-scope-runtime-design.md: b93c291957fab98ab9d0d04eb816bb01a15a0b51
-2026-07-12-agent-scope-runtime-design.zh.md: e0c01f31eb2664608139f95dc60025a5b33e4618
+2026-07-12-agent-scope-runtime-design.md: b8f265551c4ebbb94d32b3599959fe6cc4da974d
+2026-07-12-agent-scope-runtime-design.zh.md: 22cd35a601bc011c27a748098be11990f5ee4653
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
index b93c291957..b8f265551c 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
@@ -34,7 +34,7 @@ The [July 8 Agent Note](2026-07-08-agent-scope-contexts.md) remains the contribu
 
 ## Cordis model: context, fiber, effect, receiver, and waterfall
 
-Five Cordis ideas are required to understand the implementation. A context selects services and registration ownership; a fiber is one live plugin or child lifecycle; an effect attaches cleanup to a fiber; an event receiver selects listeners; and a waterfall lets listeners transform or veto an operation in sequence.
+Five Cordis ideas are required to understand the implementation. A context selects services and registration ownership; a fiber is one live plugin or child lifecycle; an effect attaches cleanup to a fiber; an event receiver selects listeners; and a waterfall lets listeners transform or short-circuit an operation in sequence.
 
 ### A context is an ownership path through one service graph
 
@@ -56,7 +56,7 @@ Cordis filters listeners using the dispatch receiver (`this`), while harness lis
 
 Product helpers therefore construct the carrier and pass the domain subject separately. This prevents listener routing from becoming an alternate object model and keeps event signatures understandable without knowledge of carrier internals.
 
-A Cordis waterfall is middleware-style dispatch. Each listener receives `next()`: calling it delegates to the remaining listeners and base operation, while returning without it vetoes or replaces the downstream result. Waterfalls power prompt assembly and tool policy; ordinary emit events notify synchronously, and parallel events await all listeners without a veto result.
+A Cordis waterfall is middleware-style dispatch. Each listener receives `next()`: calling it delegates to the remaining listeners and base operation, while returning without it short-circuits or replaces the downstream result. Waterfalls power prompt assembly and tool policy; ordinary emit events notify synchronously, and parallel events await all listeners without a veto result.
 
 ## Scope routing: one opaque key selects one layer
 
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
index e0c01f31eb..22cd35a601 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -34,7 +34,7 @@ Status: implemented
 
 ## Cordis 模型：上下文、fiber、effect、receiver 与 waterfall
 
-理解实现需要五个 Cordis 概念。上下文选择服务和注册所有权；fiber 是一个活跃的插件或子生命周期；effect 将清理逻辑附加到 fiber；事件接收器选择监听器；waterfall（瀑布式事件）让监听器按顺序变换或否决一个操作。
+理解实现需要五个 Cordis 概念。上下文选择服务和注册所有权；fiber 是一个活跃的插件或子生命周期；effect 将清理逻辑附加到 fiber；事件接收器选择监听器；waterfall（瀑布式事件）让监听器按顺序变换或短路一个操作。
 
 ### 上下文是贯穿单个服务图的所有权路径
 
@@ -56,7 +56,7 @@ Cordis 使用 dispatch receiver（`this`）过滤监听器，而 harness 的监
 
 因此，产品辅助函数构造载体并单独传递领域主体。这防止监听器路由变成另一套对象模型，并使事件签名在不了解载体内部的情况下也可理解。
 
-Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()`：调用它则委托给剩余监听器和基础操作，不调用则否决或替换下游结果。Waterfall 驱动提示词组装和工具策略；普通 emit 事件同步通知，parallel 事件等待所有监听器但没有否决结果。
+Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()`：调用它则委托给剩余监听器和基础操作，不调用则短路或替换下游结果。Waterfall 驱动提示词组装和工具策略；普通 emit 事件同步通知，parallel 事件等待所有监听器但没有否决结果。
 
 ## 作用域路由：一个不透明键选择一层
 
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
index 900fc9c374..2032c54723 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.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 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
-2026-07-08-self-referential-cordis-toolset.md: 29d331008d4111ae00147f2ddd19a628135339ac
-2026-07-08-self-referential-cordis-toolset.zh.md: d61ba794781226437a5d7499c20e5cd33119fe78
+2026-07-08-self-referential-cordis-toolset.md: a2f614cc5a236e45622eae2b30f518181331cc79
+2026-07-08-self-referential-cordis-toolset.zh.md: 6c56c2bf0c8cc8d175f451290620d9386bb69a23
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
index 29d331008d..a2f614cc5a 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
@@ -81,4 +81,4 @@ The correctness investment therefore goes where it pays for every capability at
 
 ## Consequences
 
-The toolset is a deliberate opt-in with a fully-privileged `ctx`, so a deployment adopts it as consciously as a bash tool. Several facts follow that the tool descriptions warn the model about directly: a waterfall listener (e.g. `tools/pre-execute`) that returns without calling `next()` vetoes the chain, so a mounted listener can lobotomize the agent's own tool dispatch ([waterfall semantics](../../../../docs/cordis-primer.md#cordis-waterfall-semantics)); mount code runs inside a tool call of the current turn, so awaiting anything that resolves only after the turn deadlocks; `vmTimeoutMs` bounds synchronous evaluation only; and mounts do not survive session resume.
+The toolset is a deliberate opt-in with a fully-privileged `ctx`, so a deployment adopts it as consciously as a bash tool. Several facts follow that the tool descriptions warn the model about directly: a waterfall listener (e.g. `tools/pre-execute`) that returns without calling `next()` short-circuits the chain, so a mounted listener can stop the agent's own tool dispatch ([waterfall semantics](../../../../docs/cordis-primer.md#cordis-waterfall-semantics)); mount code runs inside a tool call of the current turn, so awaiting anything that resolves only after the turn deadlocks; `vmTimeoutMs` bounds synchronous evaluation only; and mounts do not survive session resume.
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
index d61ba79478..6c56c2bf0c 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
@@ -81,4 +81,4 @@ vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节
 
 ## 后果
 
-该工具集是刻意的显式启用设计，具有完全特权的 `ctx`，因此部署方采用它的意识程度应与 bash 工具相当。以下几个事实由工具描述直接告知模型：一个 waterfall（瀑布式事件）监听器（如 `tools/pre-execute`）如果不调用 `next()` 就返回，会否决整条链，因此一个挂载的监听器可以瘫痪 agent 自身的工具分发（[waterfall 语义](../../../../docs/cordis-primer.md#cordis-waterfall-semantics)）；挂载代码在当前轮次的工具调用内运行，因此 await 任何只在该轮次结束后才 resolve 的东西会导致死锁；`vmTimeoutMs` 仅约束同步执行；挂载不会在会话恢复后存活。
+该工具集是刻意的显式启用设计，具有完全特权的 `ctx`，因此部署方采用它的意识程度应与 bash 工具相当。以下几个事实由工具描述直接告知模型：一个 waterfall（瀑布式事件）监听器（如 `tools/pre-execute`）如果不调用 `next()` 就返回，会短路整条链，因此一个挂载的监听器可以阻止 agent 自身的工具分发（[waterfall 语义](../../../../docs/cordis-primer.md#cordis-waterfall-semantics)）；挂载代码在当前轮次的工具调用内运行，因此 await 任何只在该轮次结束后才 resolve 的东西会导致死锁；`vmTimeoutMs` 仅约束同步执行；挂载不会在会话恢复后存活。
diff --git a/AGENTS.md b/AGENTS.md
index dcb001768e..deabc5ed99 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,7 +101,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. If a package has no plausible relationship, an explained empty companion is correct ([package contract](packages/AGENTS.md)).
 - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns.
 - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
-- **Waterfall listeners MUST call `next()`** to delegate; returning without it is the veto ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
+- **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
 - **Plugins, not loop changes**: new behavior goes on the documented extension seams; changing `agent-loop` requires updating docs/architecture.md.
 - **Capability seams are three packages** — interface / implementation / consumer; don't split preemptively.
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 6791ac709d..1b81c2c5da 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: f593ee5c54e5bd2cbdaa5da9f2de54b7b08ec14b
-architecture.zh.md: 80028f33c620b35ffc549b4f4828a23a5f930e93
+architecture.md: 06c15f204b3a695de49df29938781f8f033c4a7e
+architecture.zh.md: 29fe94f5a94c317854366e811dc6ceb74d2fddfe
diff --git a/docs/architecture.md b/docs/architecture.md
index f593ee5c54..06c15f204b 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -63,7 +63,7 @@ Events are the service extension API ([subsystems](subsystems/core.md), [produce
 
 ### Interception Semantics
 
-Waterfalls are around-middleware: listeners delegate with `next()`; returning without it vetoes or takes over ([semantics](cordis-primer.md#cordis-waterfall-semantics)).
+Waterfalls are around-middleware: listeners delegate with `next()`; returning without it short-circuits or takes over ([semantics](cordis-primer.md#cordis-waterfall-semantics)).
 
 ## Default Loop Lifecycle
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 80028f33c6..29fe94f5a9 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -63,7 +63,7 @@
 
 ### 拦截语义
 
-waterfall（瀑布式事件）是环绕中间件：监听器通过 `next()` 委托；不调用它而直接返回会否决或接管（[语义](cordis-primer.md#cordis-waterfall-semantics)）。
+waterfall（瀑布式事件）是环绕中间件：监听器通过 `next()` 委托；不调用它而直接返回会短路或接管（[语义](cordis-primer.md#cordis-waterfall-semantics)）。
 
 ## 默认循环生命周期
 
diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md
index 5582bdd1ac..8bf23274e5 100644
--- a/docs/cordis-api/inherited.md
+++ b/docs/cordis-api/inherited.md
@@ -10,7 +10,7 @@ This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verifie
 ## Inherited `ctx` members (cordis core + loader/hmr/timer)
 
 - `ctx.on / ctx.once` — Register an event listener (disposable). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
-- `ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall` — Dispatch an event (sync / awaited / first-bail / veto-chain). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
+- `ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall` — Dispatch an event (sync / awaited / first-bail / short-circuit chain). ([`vendor/cordis/src/events.ts:34`](../../vendor/cordis/src/events.ts))
 - `ctx.plugin / ctx.inject` — Load a plugin / declare required services. ([`vendor/cordis/src/registry.ts:164`](../../vendor/cordis/src/registry.ts))
 - `ctx.effect` — Register a disposable side effect tied to the fiber. ([`vendor/cordis/src/fiber.ts:9`](../../vendor/cordis/src/fiber.ts))
 - `ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin` — Low-level service-store access and binding. ([`vendor/cordis/src/reflect.ts:7`](../../vendor/cordis/src/reflect.ts))
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 8986847d1e..e598429553 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -284,7 +284,7 @@ Source: [`packages/self-modification/tool-cordis/src/index.ts`](../packages/self
 
 ### `cordis_mount`
 
-Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.
+Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.
 
 ```json
 {
diff --git a/docs/user/develop/framework/events.i18n.yaml b/docs/user/develop/framework/events.i18n.yaml
index d6bb924fc7..f39b04145d 100644
--- a/docs/user/develop/framework/events.i18n.yaml
+++ b/docs/user/develop/framework/events.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 docs/user/develop/framework/events.md
-events.md: c70150b4d9070063513021e420f253ff6d4e5de1
-events.zh.md: b3b79a86d249eed0df15380e17a1ee71766b1a72
+events.md: 8a8c076d9c7b40d73182db074c4f494fded8c6dd
+events.zh.md: 9649d89d575a1b05fa524bd460043da71dc9ae43
diff --git a/docs/user/develop/framework/events.md b/docs/user/develop/framework/events.md
index c70150b4d9..8a8c076d9c 100644
--- a/docs/user/develop/framework/events.md
+++ b/docs/user/develop/framework/events.md
@@ -63,7 +63,7 @@ await ctx.serial('setup-phase', context)
 
 ### waterfall — pipeline
 
-Each listener may wrap the downstream result to form a processing chain. A listener **must call `next()` to delegate downstream**; omitting the call vetoes the pipeline:
+Each listener may wrap the downstream result to form a processing chain. A listener **must call `next()` to delegate downstream**; omitting the call short-circuits the pipeline:
 
 ```ts ignore-check
 // Dispatch
@@ -77,7 +77,7 @@ ctx.on('my-plugin/transform', async (_input, next) => {
 ```
 
 ::: warning
-A waterfall listener **must call `next()`**. Omitting it vetoes the pipeline by design, enabling interception and gateway behavior.
+A waterfall listener **must call `next()`**. Omitting it short-circuits the pipeline by design, enabling interception and gateway behavior.
 :::
 
 ## Typed events
diff --git a/docs/user/develop/framework/events.zh.md b/docs/user/develop/framework/events.zh.md
index b3b79a86d2..9649d89d57 100644
--- a/docs/user/develop/framework/events.zh.md
+++ b/docs/user/develop/framework/events.zh.md
@@ -63,7 +63,7 @@ await ctx.serial('setup-phase', context)
 
 ### waterfall（瀑布式事件）— 流水线
 
-每个监听器可以包装下游返回值，形成处理链。**必须调用 `next()` 传递给下游**，不调用即为否决：
+每个监听器可以包装下游返回值，形成处理链。**必须调用 `next()` 传递给下游**，不调用即会短路流水线：
 
 ```ts ignore-check
 // Dispatch
@@ -77,7 +77,7 @@ ctx.on('my-plugin/transform', async (_input, next) => {
 ```
 
 ::: warning
-waterfall 监听器**必须调用 `next()`**。不调用 `next` 等于否决整个流水线，这是故意为之的设计——用于实现拦截/网关逻辑。
+waterfall 监听器**必须调用 `next()`**。不调用 `next` 会短路整个流水线，这是故意为之的设计——用于实现拦截/网关逻辑。
 :::
 
 ## 类型安全的事件
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
index b9fc8ec9d9..2014dc54e3 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
@@ -60,7 +60,7 @@ interface ToolArgsMap {
     /** Exact service key or event name whose original JSDoc to include; valid only with what:"api" or what:"events". */
     name?: string;
   } & Record<string, JsonValue>;
-  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */
+  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */
   cordis_mount: {
     /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */
     code: string;
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
index 70ab4e61f6..403d3fbc6c 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
@@ -72,7 +72,7 @@
     },
     {
       "name": "cordis_mount",
-      "description": "Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.",
+      "description": "Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
index 12a88365a6..9fcadd71d4 100644
--- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
@@ -25,7 +25,7 @@
 {"type":"assistant/chunk","seq":23,"time":1785730459921,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":24,"time":1785730459921,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-event","name":"cordis_inspect","arguments":"{\"what\":\"events\",\"name\":\"tools/pre-execute\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"283c82b3-1bda-481c-a716-c35f363c9752"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[19,20,21,22,23],"surfaceOp":"append"}
 {"type":"tool/call","seq":25,"time":1785730459921,"data":{"turn":1,"step":2,"callId":"inspect-tools-event","name":"cordis_inspect","arguments":"{\"what\":\"events\",\"name\":\"tools/pre-execute\"}"}}
-{"type":"tool/result","seq":26,"time":1785730459929,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"inspect-tools-event"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-event","content":[{"type":"text","text":"## events\n- tools/pre-execute [waterfall] — Allow, deny, or ask before dispatch.\n    /**\n     * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing\n     * approval support turns `ask` into denial. Async gates must observe\n     * `exec.signal`; the registry rechecks cancellation after they settle but\n     * never abandons their promise.\n     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.\n     * @param exec - the pending call (name, parsed arguments, caller agent).\n     * @mode waterfall\n     */\n    'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>\nwaterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain."}],"isError":false}],"role":"user","id":"c187306a-d73c-4bcd-b76c-8607ddbc0974"}},"sourceEventSeqs":[25],"surfaceOp":"append"}
+{"type":"tool/result","seq":26,"time":1785730459929,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"inspect-tools-event"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-event","content":[{"type":"text","text":"## events\n- tools/pre-execute [waterfall] — Allow, deny, or ask before dispatch.\n    /**\n     * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing\n     * approval support turns `ask` into denial. Async gates must observe\n     * `exec.signal`; the registry rechecks cancellation after they settle but\n     * never abandons their promise.\n     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.\n     * @param exec - the pending call (name, parsed arguments, caller agent).\n     * @mode waterfall\n     */\n    'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>\nwaterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() short-circuits the chain."}],"isError":false}],"role":"user","id":"c187306a-d73c-4bcd-b76c-8607ddbc0974"}},"sourceEventSeqs":[25],"surfaceOp":"append"}
 {"type":"step/end","seq":27,"time":1785730459929,"data":{"turn":1,"step":2}}
 {"type":"step/start","seq":28,"time":1785730459939,"data":{"turn":1,"step":3}}
 {"type":"assistant/chunk","seq":29,"time":1784449176735,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
index ff58bd3a43..44cbf0e360 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
@@ -6,7 +6,7 @@
 {"type":"step/start","seq":4,"time":1785730501506,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":5,"time":1785730501506,"data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"fc62f9e7-b8f6-441f-9ee8-17f1f9e4feca"},"surfaceOp":"append"}
 {"type":"session/title","seq":6,"time":1785730501506,"data":{"title":"Reply with exactly DIRECT_CHILD_OK and","messageSeqs":[5],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":7,"time":1785498583897,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":7,"time":1785498583897,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":8,"time":1785730501507,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":9,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":10,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"DIRECT_CHILD_OK"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
index 02c779e8f4..6988595618 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
@@ -6,7 +6,7 @@
 {"type":"step/start","seq":4,"time":1785730501645,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":5,"time":1785730501645,"data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"093bfc20-c6fc-4573-b172-2c6ca40c188b"},"surfaceOp":"append"}
 {"type":"session/title","seq":6,"time":1785730501645,"data":{"title":"Reply with exactly WORKFLOW_CHILD_OK and","messageSeqs":[5],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":7,"time":1785498584067,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":7,"time":1785498584067,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":8,"time":1785730501646,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":9,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":10,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"WORKFLOW_CHILD_OK"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
index a168db4b8b..6769414d10 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
@@ -5,7 +5,7 @@
 {"type":"step/start","seq":3,"time":1783957884486,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":4,"time":1785498583779,"data":{"content":[{"type":"text","text":"Run this advanced flow exactly once: try a no-op temporary Cordis Plugin named snapshot-marker; use run_code to inspect the live temporary Plugins through tools.cordis_inspect; delegate once to a direct spawn child; run one workflow that delegates to another spawn child; stop dyn-1; then reply with exactly ADVANCED_HEADLESS_OK."}],"source":{"kind":"user"},"role":"user","id":"d2f4f71c-78bc-4a22-908d-c08fbb3ab9ef"},"surfaceOp":"append"}
 {"type":"session/title","seq":5,"time":1785498583779,"data":{"title":"Run this advanced flow exactly","messageSeqs":[4],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":6,"time":1785498583782,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":6,"time":1785498583782,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` SHORT-CIRCUITS the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":7,"time":1785730501403,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":8,"time":1783950000007,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
 {"type":"assistant/chunk","seq":9,"time":1783950000008,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}
diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts
index 1173607ae9..c42331de58 100644
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -338,7 +338,7 @@ describe('agent loop', () => {
     expect(adapter.requests[0]!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou run on mock.')
   })
 
-  it('omits the system field when a system-prompt/assemble veto empties the assembly', async () => {
+  it('omits the system field when system-prompt/assemble short-circuits with an empty assembly', async () => {
     // The documented escape valve: a deployment that must drop the harness
     // openers short-circuits the assemble waterfall; the request then carries
     // NO system field at all (not an empty string).
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index 5bd34a8642..e8381a56a6 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -3306,7 +3306,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
 /** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */
 export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [
   { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).' },
-  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).' },
+  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / short-circuit chain).' },
   { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.' },
   { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.' },
   { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.' },
diff --git a/packages/self-modification/tool-cordis/src/index.ts b/packages/self-modification/tool-cordis/src/index.ts
index 5476dc0929..6ba56ccfe4 100644
--- a/packages/self-modification/tool-cordis/src/index.ts
+++ b/packages/self-modification/tool-cordis/src/index.ts
@@ -154,7 +154,7 @@ export function apply(ctx: Context, config: Config): void {
       + 'Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). '
       + 'Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a '
       + 'trailing `next` callback which MUST be called — returning without `next()` '
-      + 'VETOES the call; prefer plain notification events unless you intend to '
+      + 'SHORT-CIRCUITS the call; prefer plain notification events unless you intend to '
       + 'intercept. (2) Never await something that only resolves after the current '
       + 'turn (your code runs INSIDE a tool call of that turn — it would deadlock). '
       + '(3) Your `ctx` is a restricted façade: you can register tools, observe '
diff --git a/packages/self-modification/tool-cordis/src/inspect.ts b/packages/self-modification/tool-cordis/src/inspect.ts
index cc0f3a4cda..08bbeb44cf 100644
--- a/packages/self-modification/tool-cordis/src/inspect.ts
+++ b/packages/self-modification/tool-cordis/src/inspect.ts
@@ -224,6 +224,6 @@ export function describeEvents(events: readonly EventApiEntry[] = EVENT_API, nam
     entry.push(`    ${event.signature}`)
     return entry
   })
-  lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.')
+  lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() short-circuits the chain.')
   return lines
 }
diff --git a/packages/self-modification/tool-cordis/tests/inspect.spec.ts b/packages/self-modification/tool-cordis/tests/inspect.spec.ts
index 2b3b32aee8..ca9fb4e03f 100644
--- a/packages/self-modification/tool-cordis/tests/inspect.spec.ts
+++ b/packages/self-modification/tool-cordis/tests/inspect.spec.ts
@@ -95,7 +95,7 @@ describe('cordis_inspect', () => {
     expect(report).toContain('- tools/change [emit]')
     expect(report).toContain('- tools/pre-execute [waterfall]')
     expect(report).toMatch(/'agent\/status'\(/)
-    expect(report).toContain('returning without next() vetoes the chain')
+    expect(report).toContain('returning without next() short-circuits the chain')
     expect(report).not.toContain('/**')
     expect(report).not.toContain('@mode waterfall')
   })
@@ -171,7 +171,7 @@ describe('inspect renderers (direct)', () => {
 
   it('describeEvents renders an empty catalog as just the waterfall caution', () => {
     expect(describeEvents([])).toEqual([
-      'waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.',
+      'waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() short-circuits the chain.',
     ])
   })
 })
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index aaae6f7649..66b3cea813 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -508,7 +508,7 @@ export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
   ],
   inheritedServices: [
     { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
-    { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
+    { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / short-circuit chain).', source: 'vendor/cordis/src/events.ts:34' },
     { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
     { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
     { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },

From 9d5eb37638b36948f2fd8d134e40d75d9fd3c3c7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 12:13:58 +0800
Subject: [PATCH 455/516] fix(headless): dsh run is a direct core front door

---
 ...-model-catalog-and-acp-selection.i18n.yaml |   4 +-
 ...-15-llm-model-catalog-and-acp-selection.md |   4 +-
 ...-llm-model-catalog-and-acp-selection.zh.md |   4 +-
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |   4 +-
 ...026-07-19-gui-layering-and-rpc-protocol.md |   8 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |   8 +-
 ...tree-boot-and-transport-layering.i18n.yaml |   4 +-
 ...config-tree-boot-and-transport-layering.md |   8 +-
 ...fig-tree-boot-and-transport-layering.zh.md |   8 +-
 ...026-08-05-profile-plugin-bundles.i18n.yaml |   4 +-
 .../2026-08-05-profile-plugin-bundles.md      |   2 +-
 .../2026-08-05-profile-plugin-bundles.zh.md   |   2 +-
 ...-headless-direct-core-front-door.i18n.yaml |   6 +
 ...6-08-09-headless-direct-core-front-door.md |  44 +++
 ...8-09-headless-direct-core-front-door.zh.md |  44 +++
 ...07-24-web-session-model-selector.i18n.yaml |   4 +-
 .../2026-07-24-web-session-model-selector.md  |  20 +-
 ...026-07-24-web-session-model-selector.zh.md |  20 +-
 ...default-model-follows-the-picker.i18n.yaml |   4 +-
 ...-08-07-default-model-follows-the-picker.md |  40 ++-
 ...-07-default-model-follows-the-picker.zh.md |  40 ++-
 ...6-08-08-dsh-run-headless-command.i18n.yaml |   4 +-
 .../2026-08-08-dsh-run-headless-command.md    |  30 +-
 .../2026-08-08-dsh-run-headless-command.zh.md |  30 +-
 apps/cli/README.i18n.yaml                     |   4 +-
 apps/cli/README.md                            |   2 +-
 apps/cli/README.zh.md                         |   2 +-
 apps/cli/composition.md                       |   3 +
 apps/cli/reference/README.i18n.yaml           |   4 +-
 apps/cli/reference/README.md                  |   4 +-
 apps/cli/reference/README.zh.md               |   4 +-
 apps/cli/tests/built-bin.e2e.ts               |  16 +-
 apps/cli/tests/fixtures/never-dispose.mjs     |   1 +
 apps/cli/tests/headless-shutdown.e2e.ts       |   7 +-
 apps/web/tests/declared-reasoning.e2e.ts      |   6 +-
 apps/web/tests/declared-reasoning.overlay.yml |   2 +-
 apps/web/tests/default-model.e2e.ts           |   8 +-
 apps/web/tests/default-model.overlay.yml      |   2 +-
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   1 +
 docs/architecture.zh.md                       |   1 +
 docs/capability-seams.md                      |   7 +
 docs/config-catalog.md                        |  43 ++-
 docs/event-producer-consumer.md               |   2 +-
 docs/i18n/terminology.md                      |   1 +
 docs/module-graph.md                          |  18 +-
 docs/subsystems/core.i18n.yaml                |   4 +-
 docs/subsystems/core.md                       |  24 ++
 docs/subsystems/core.zh.md                    |  24 ++
 docs/user/guide/providers.i18n.yaml           |   4 +-
 docs/user/guide/providers.md                  |   6 +-
 docs/user/guide/providers.zh.md               |   6 +-
 docs/user/guide/quickstart.i18n.yaml          |   4 +-
 docs/user/guide/quickstart.md                 |   4 +-
 docs/user/guide/quickstart.zh.md              |   4 +-
 .../tests/fixtures/dsh-run.cordis.yml         |   2 +-
 .../headless-agent/tests/headless.snapshot.ts |   2 +-
 .../snapshots/dsh-run/session.expected.jsonl  |   4 +-
 knip.json                                     |   5 +
 packages/acp/acp/src/index.ts                 |   4 +-
 packages/boot/app-boot/README.i18n.yaml       |   4 +-
 packages/boot/app-boot/README.md              |   2 +-
 packages/boot/app-boot/README.zh.md           |   2 +-
 packages/boot/app-boot/src/profile.ts         |  33 +-
 packages/boot/app-boot/tests/profile.spec.ts  |  27 ++
 packages/bundle/README.i18n.yaml              |   4 +-
 packages/bundle/README.md                     |   2 +-
 packages/bundle/README.zh.md                  |   2 +-
 packages/bundle/base/README.i18n.yaml         |   4 +-
 packages/bundle/base/README.md                |   2 +-
 packages/bundle/base/README.zh.md             |   2 +-
 packages/bundle/base/cordis.patch.yml         |   8 +
 packages/bundle/base/package.json             |   1 +
 packages/bundle/headless/README.i18n.yaml     |   4 +-
 packages/bundle/headless/README.md            |   8 +-
 packages/bundle/headless/README.zh.md         |   8 +-
 packages/bundle/headless/cordis.patch.yml     |  31 +-
 packages/bundle/headless/package.json         |  11 +-
 packages/bundle/headless/src/index.ts         | 212 +++++------
 .../bundle/headless/tests/headless.spec.ts    | 335 ++++++++----------
 packages/bundle/headless/tsconfig.json        |  12 +-
 packages/bundle/web-app/README.i18n.yaml      |   4 +-
 packages/bundle/web-app/README.md             |   2 +-
 packages/bundle/web-app/README.zh.md          |   2 +-
 packages/bundle/web-app/cordis.patch.yml      |   6 +-
 packages/client/connection/src/client/api.ts  |   2 +-
 .../client/connection/src/client/fixture.ts   |  24 +-
 .../client/connection/src/client/index.ts     |   2 +-
 packages/client/connection/tests/fake-api.ts  |  12 +-
 .../client/connection/tests/fixture.spec.ts   |   2 +-
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |   4 +-
 packages/client/runtime/README.zh.md          |   4 +-
 packages/client/runtime/tests/fake-api.ts     |   6 +-
 packages/client/runtime/tests/manager.spec.ts |   2 +-
 packages/client/runtime/tests/session.spec.ts |  12 +-
 packages/client/ui-model/README.i18n.yaml     |   4 +-
 packages/client/ui-model/README.md            |   6 +-
 packages/client/ui-model/README.zh.md         |   6 +-
 .../ui-model/src/client/ModelSelect.tsx       |  18 +-
 .../client/ui-model/src/client/directory.ts   |  28 +-
 packages/client/ui-model/src/client/index.ts  |  20 +-
 packages/client/ui-model/src/client/slots.ts  |   8 +-
 .../ui-model/tests/browser-plugin.spec.ts     |   6 +-
 .../ui-model/tests/model-select.spec.tsx      |  10 +-
 packages/core/README.i18n.yaml                |   4 +-
 packages/core/README.md                       |   5 +-
 packages/core/README.zh.md                    |   5 +-
 .../core/agent-default-model/README.i18n.yaml |   6 +
 packages/core/agent-default-model/README.md   |  25 ++
 .../core/agent-default-model/README.zh.md     |  25 ++
 .../core/agent-default-model/package.json     |  44 +++
 .../core/agent-default-model/src/index.ts     | 107 ++++++
 .../core/agent-default-model/src/invariant.ts |  30 ++
 .../tests/agent-default-model.spec.ts         |  98 +++++
 .../core/agent-default-model/tsconfig.json    |  30 ++
 .../core/agent-default-model/tsdown.config.ts |  25 ++
 packages/core/agent/README.i18n.yaml          |   4 +-
 packages/core/agent/README.md                 |   2 +-
 packages/core/agent/README.zh.md              |   2 +-
 packages/core/agent/src/index.ts              |   2 +-
 .../src/{llm-target.ts => model-selection.ts} |  42 +--
 ...target.spec.ts => model-selection.spec.ts} |  14 +-
 packages/host/apiproxy/README.i18n.yaml       |   4 +-
 packages/host/apiproxy/README.md              |  20 +-
 packages/host/apiproxy/README.zh.md           |  22 +-
 packages/host/apiproxy/package.json           |   1 +
 packages/host/apiproxy/src/api-proxy.ts       | 116 +++---
 packages/host/apiproxy/src/api/index.ts       |   2 +-
 packages/host/apiproxy/src/api/llm.ts         |   4 +-
 .../host/apiproxy/src/api/sessions.schema.ts  |  12 +-
 packages/host/apiproxy/src/api/sessions.ts    |  12 +-
 packages/host/apiproxy/src/index.ts           |  97 +----
 .../apiproxy/tests/api-proxy-approval.spec.ts |   4 +-
 .../apiproxy/tests/api-proxy-blank.spec.ts    |   2 +-
 .../apiproxy/tests/api-proxy-cold.spec.ts     |  26 +-
 .../apiproxy/tests/api-proxy-commands.spec.ts |   2 +-
 .../apiproxy/tests/api-proxy-config.spec.ts   |  17 +-
 .../tests/api-proxy-default-route.spec.ts     | 108 ------
 .../apiproxy/tests/api-proxy-fork.spec.ts     |   4 +-
 .../apiproxy/tests/api-proxy-models.spec.ts   |  26 +-
 .../tests/api-proxy-projections.spec.ts       |   2 +-
 .../apiproxy/tests/api-proxy-question.spec.ts |   2 +-
 .../apiproxy/tests/api-proxy-rename.spec.ts   |   2 +-
 .../apiproxy/tests/api-proxy-search.spec.ts   |   2 +-
 .../tests/api-proxy-subagents.spec.ts         |   2 +-
 .../apiproxy/tests/api-proxy-view.spec.ts     |  10 +-
 .../tests/api-proxy-workspace.spec.ts         |   2 +-
 .../apiproxy/tests/client-handler.spec.ts     |   2 +-
 .../host/apiproxy/tests/rpc-schemas.spec.ts   |   2 +-
 packages/host/apiproxy/tsconfig.json          |   3 +
 .../tool-cordis/src/api-catalog.ts            |  18 +
 .../todo/tool-todo/tests/projection.spec.ts   |   2 +-
 pnpm-lock.yaml                                |  41 ++-
 scripts/gen-cordis-catalog.ts                 |   2 +
 scripts/gen-doc-graphs.ts                     |   8 +
 .../request-response.expected.json            |   2 +-
 .../verify-package-readme-model-experience.ts |   5 +-
 tsconfig.host.json                            |   1 +
 159 files changed, 1508 insertions(+), 1042 deletions(-)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
 create mode 100644 packages/core/agent-default-model/README.i18n.yaml
 create mode 100644 packages/core/agent-default-model/README.md
 create mode 100644 packages/core/agent-default-model/README.zh.md
 create mode 100644 packages/core/agent-default-model/package.json
 create mode 100644 packages/core/agent-default-model/src/index.ts
 create mode 100644 packages/core/agent-default-model/src/invariant.ts
 create mode 100644 packages/core/agent-default-model/tests/agent-default-model.spec.ts
 create mode 100644 packages/core/agent-default-model/tsconfig.json
 create mode 100644 packages/core/agent-default-model/tsdown.config.ts
 rename packages/core/agent/src/{llm-target.ts => model-selection.ts} (55%)
 rename packages/core/agent/tests/{llm-target.spec.ts => model-selection.spec.ts} (86%)
 delete mode 100644 packages/host/apiproxy/tests/api-proxy-default-route.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml
index faade67459..f38ba32c11 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.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 .agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
-2026-07-15-llm-model-catalog-and-acp-selection.md: 9edc723b0dfafeaf395eb9325373835138ddbc41
-2026-07-15-llm-model-catalog-and-acp-selection.zh.md: aefd0af3e4de8fac4f5819e0ee279d3343aec6be
+2026-07-15-llm-model-catalog-and-acp-selection.md: 41174209d2c44bedb5dd0615c5f877ecebd43639
+2026-07-15-llm-model-catalog-and-acp-selection.zh.md: 43442487649f7a552d66bd66b64e0e5072f5e00b
diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
index 9edc723b0d..41174209d2 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
@@ -34,9 +34,9 @@ The ACP automation transport is not a catalog consumer. Its deployment config su
 
 ### Prompt/request consistency and durability
 
-`installAgentLlmTarget` (in `dsh-agent`) installs scoped `system-prompt/assemble` and `agent/request` listeners for a front-door-owned target. Prompt assembly snapshots the selected pair once per step, overwrites the assembled `provider` and `model` variables after downstream prompt listeners, and the request listener applies that same snapshot after downstream request listeners. A selection during asynchronous assembly therefore starts on the next step rather than splitting prompt text from routing. Other call-config fields remain untouched.
+`installModelSelection` (in `dsh-agent`) installs scoped `system-prompt/assemble` and `agent/request` listeners for a front-door-owned selection. Prompt assembly snapshots the selected pair once per step, overwrites the assembled `provider` and `model` variables after downstream prompt listeners, and the request listener applies that same snapshot after downstream request listeners. A selection during asynchronous assembly therefore starts on the next step rather than splitting prompt text from routing. Other call-config fields remain untouched.
 
-The request header remains the durable source of truth. When a selected target is actually used, the existing full `request/header` snapshot records it, and a front door initializes its selection from the folded last request header before falling back to creation options. A selection that is never used by a request is intentionally in-memory only because it never became model-visible state.
+The request header remains the durable source of truth. When a selection is actually used, the existing full `request/header` snapshot records it, and a front door initializes its selection from the folded last request header before falling back to creation options. A selection that is never used by a request is intentionally in-memory only because it never became model-visible state.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
index aefd0af3e4..4344248764 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
@@ -34,9 +34,9 @@ ACP 自动化传输层不是目录消费方。它通过部署配置为新创建
 
 ### 提示词／请求一致性与持久化
 
-`installAgentLlmTarget`（位于 `dsh-agent`）为前门拥有的目标安装 agent 作用域的 `system-prompt/assemble` 与 `agent/request` 监听器。提示词组装在每个步骤对所选组合做一次快照，在下游提示词监听器之后覆写组装出的 `provider` 与 `model` 变量；请求监听器在下游请求监听器之后应用同一快照。因此，发生在异步组装期间的选择会从下一个步骤生效，而不会让提示词文本与路由分裂。其他调用配置字段保持不变。
+`installModelSelection`（位于 `dsh-agent`）为前门拥有的选择安装 agent 作用域的 `system-prompt/assemble` 与 `agent/request` 监听器。提示词组装在每个步骤对所选组合做一次快照，在下游提示词监听器之后覆写组装出的 `provider` 与 `model` 变量；请求监听器在下游请求监听器之后应用同一快照。因此，发生在异步组装期间的选择会从下一个步骤生效，而不会让提示词文本与路由分裂。其他调用配置字段保持不变。
 
-请求头仍是持久化的真源。当所选目标真正被使用时，现有的完整 `request/header` 快照会记录它；前门先从折叠后的最后一个请求头初始化其选择，然后才回退到创建选项。从未被请求使用的选择有意只保留在内存中，因为它从未成为模型可见状态。
+请求头仍是持久化的真源。当某个选择真正被使用时，现有的完整 `request/header` 快照会记录它；前门先从折叠后的最后一个请求头初始化其选择，然后才回退到创建选项。从未被请求使用的选择有意只保留在内存中，因为它从未成为模型可见状态。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 4578e9e268..13da6f9711 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: 8e020e4fe9b60100671c0cf0e98e28532d850f94
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 49ebd642264c663377f16b8669fedc112d3bb6c7
+2026-07-19-gui-layering-and-rpc-protocol.md: ceb8e5db593aef14d6db259f6293381fe83defe2
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: ecd577f7ec5af5d588d0dbf03f94010e00782732
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
index 8e020e4fe9..ceb8e5db59 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -31,7 +31,7 @@ Directories layer as follows:
     - **Fetch-arrival plugin packages** (`ui-layout`, `ui-sidebar`, `ui-conversation`, `ui-trajectory`): dual-entry — the root index is the node half (an empty `apply`, existing so the host Loader governs lifecycle and the web plugin registry discovers the package.json `dshClient` declaration); the implementation lives under `src/client/`, shipped as the `./client` subpath (a tsdown closure-factory bundle). Cross-plugin consumption of `/client` is type-only; value cooperation goes through cordis services.
 - `apps/` holds the externally exported application shapes, assembled from Client / Host mixtures.
     - `apps/web` (`dsh-frontend`) is the vite application: a thin `main.ts` over the shell surface exported by `dsh-client-web`.
-    - `apps/cli` (`@deepseek-ai/dsh`) dispatches shapes: `dsh web` = startHost + webserver + the built `dsh-frontend` dist; `dsh run` = headless in-process calls, zero HTTP.
+    - `apps/cli` (`@deepseek-ai/dsh`) dispatches shapes: `dsh web` = Host + webserver + the built `dsh-frontend` dist; `dsh run` = [a direct core Agent/Session front door](2026-08-09-headless-direct-core-front-door.md), with zero Host, HTTP, or browser layer.
     - A future Electron shape reuses the same web client packages over an IPC fetch carrier.
 
 ```
@@ -79,7 +79,7 @@ Packages under `packages/host/*` and `packages/client/*` **must carry the direct
 2. **Write an assembly module under `apps/`**: `startHost()` + a client subclass + the shape's private signal/print/exit semantics; a mixture never becomes a package — assembly is written in the app.
 3. **Import `dsh-host-webserver` only if you need HTTP carriage**, otherwise zero ports.
 
-The two existing shapes are the template: `apps/cli/src/web.ts` (startHost + dist location + startWebServer + signal shutdown) and `headless.ts` (startHost + InProcessApiClient isomorphic direct calls, zero HTTP zero ports). ACP-class protocol bridges do not follow this checklist: they expose core to the external ecosystem, mount via `ctx.plugin(front-door plugin)` directly, and wear no fetch.
+The two existing shapes preserve the boundary: the Web shape mounts Host, carrier, and browser composition, while `dsh run` mounts a direct core runner with zero Host, HTTP, or ports. ACP-class protocol bridges do not follow the client-carrier checklist: they expose core to the external ecosystem, mount via `ctx.plugin(front-door plugin)` directly, and wear no fetch.
 
 ## Message protocol
 
@@ -215,7 +215,7 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 
 | Subclass | Package | doFetch | Purpose |
 |---|---|---|---|
-| `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing — `dsh run` headless is the protocol's second real consumer |
+| `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing; carrier tests and callers can exercise the protocol without opening a port, while product `dsh run` drives core directly |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` uplink + one same-origin WebSocket downlink per logical stream | the browser shape; physical boundary in the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | unused (protocol-layer override) | serverless UI development (`?fixture`): overrides the `callUnary`/`openMux`/`openHost`/`respond` virtuals and is itself the fake server (frame rpcIds minted by it, semantics self-consistent) |
 | (future) IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
@@ -242,7 +242,7 @@ Every client shape consumes one contract: adding a unary method is a five-step m
 |---|---|
 | Packaging by "product shape" (a web family, an electron family) | What shapes share is host/client capability, not the shape itself; capability-provider layering means a new shape needs zero new packages |
 | A package per mixture (e.g. a standalone headless package) | A mixture has exactly one consumer (its own app); packaging it is ownerless abstraction, while assembly in the app is readable and disposable |
-| Consuming clients connecting to ctx directly (skipping the apiproxy layer) | A second command plane bypasses the contract, losing wire validation/observability/multi-client consistency; ctx keeps exactly two formal uses — front doors and headless event subscription |
+| Consuming clients connecting to ctx directly (skipping the apiproxy layer) | Client shapes require wire validation, observability, and multi-client consistency. Direct headless is a local front door with no client boundary and uses the public Agent/Session seams rather than a client command plane |
 | webserver depending on runtime (saving the handler injection) | Structural-typing injection keeps webserver reusable by sidecars/tests with zero workspace deps; a package dependency would drag assembly knowledge into the carrier layer |
 | Package names without the group prefix (continuing dsh-<tail>) | `dsh-runtime`/`dsh-web-ui` lose their belonging in the flat npm namespace; the cost is one explicit paths entry per package |
 | Reusing the in-repo JSON-RPC 2.0 (dsh-jsonrpc) | Numeric error codes degrade to a single fallback code, contracts get aligned by hand in two copies, and naming drifts without a convention |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 49ebd64226..ecd577f7ec 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -29,7 +29,7 @@ Status: implemented
     - **fetch 到达插件包**（`ui-layout`、`ui-sidebar`、`ui-conversation`、`ui-trajectory`）：双入口——根入口是 node 半边（空 `apply`，其存在是为了让 host Loader 管辖生命周期、让 web 插件注册表发现 package.json 的 `dshClient` 声明）；实现住在 `src/client/` 下，经 `./client` 子路径发布（tsdown 闭包工厂 bundle）。跨插件消费 `/client` 只限类型；值层面的协作走 cordis 服务。
 - `apps/` 作为对外导出的应用形态入口，可以由 Client / Host 混合组装。
     - `apps/web`（`dsh-frontend`）是 vite 应用：`dsh-client-web` 导出的壳表面之上的一层薄 `main.ts`。
-    - `apps/cli`（`@deepseek-ai/dsh`）做形态分发：`dsh web` = startHost + webserver + 构建出的 `dsh-frontend` dist；`dsh run` = headless 进程内直调，零 HTTP。
+    - `apps/cli`（`@deepseek-ai/dsh`）做形态分发：`dsh web` = Host + webserver + 构建出的 `dsh-frontend` dist；`dsh run` = [直接使用核心 Agent／Session 的前门](2026-08-09-headless-direct-core-front-door.md)，不含 Host、HTTP 或浏览器层。
     - 将来的 Electron 形态经由 IPC fetch 载体复用同一套 web client 包。
 
 ```
@@ -77,7 +77,7 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 2. **在 `apps/` 下写拼装模块**：`startHost()` + 客户端子类 + 该形态私有的信号/打印/退出语义；混合体不建包，拼装写在 app 里。
 3. **需要 HTTP 承载才 import `dsh-host-webserver`**，否则零端口。
 
-现有两形态即模板：`apps/cli/src/web.ts`（startHost + dist 定位 + startWebServer + 信号停机）与 `headless.ts`（startHost + InProcessApiClient 同构直调，零 HTTP 零端口）。ACP 类协议桥不走本清单：它把 core 暴露给外部生态，直接 `ctx.plugin(前门插件)` 挂载、不套 fetch。
+现有两种形态保持这一边界：Web 形态挂载 Host、载体与浏览器组合，而 `dsh run` 挂载直接使用核心服务的 runner，不包含 Host、HTTP 或端口。ACP 类协议桥不遵循 client 载体清单：它把 core 暴露给外部生态，直接通过 `ctx.plugin(前门插件)` 挂载，不套 fetch。
 
 ## 消息协议
 
@@ -213,7 +213,7 @@ export type ResponseValue<K> =
 
 | 子类 | 所在包 | doFetch | 用途 |
 |---|---|---|---|
-| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh run` headless 即协议第二真实消费者 |
+| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧；载体测试与调用方可以在不打开端口的情况下运行这套协议，而产品 `dsh run` 直接驱动 core |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
 | （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
@@ -240,7 +240,7 @@ export type ResponseValue<K> =
 |---|---|
 | 按「产品形态」分包（web 一族、electron 一族） | 形态间共享的是 host/client 两侧能力而非形态本身；能力支持方分层让新形态零新包 |
 | 混合体建包（如 headless 独立包） | 混合体只有一个消费者（它自己的 app），建包是无主抽象；拼装写在 app 里可读可弃 |
-| 消费型 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开约定，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
+| 消费型 client 直连 ctx（省 apiproxy 一层） | client 形态需要 wire 校验、观测与多 client 一致性。直接 headless 是没有 client 边界的本地前门，使用公开的 Agent／Session seam，而不是 client 命令面 |
 | webserver 依赖 runtime（省 handler 注入） | 结构 typing 注入让 webserver 可被 sidecar/测试复用且零 workspace 依赖；包依赖会把装配知识拖进承载层 |
 | 包名不带组前缀（沿用 dsh-<尾段>） | `dsh-runtime`/`dsh-web-ui` 在扁平 npm 命名空间里失去归属信息；代价只是每包一条显式 paths |
 | 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、约定双份人肉对齐、命名无 convention 自然漂移 |
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
index 2c1f309a79..2ee0de0625 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.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 .agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
-2026-07-24-web-config-tree-boot-and-transport-layering.md: 88f94b1f58ae7a3451c7772f4a9ff7d6564254c0
-2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 5f03dfbb8e5eaeeb52076584721e70ea66a292df
+2026-07-24-web-config-tree-boot-and-transport-layering.md: 496499a691dbca012e5e953cbb6eb1d0bf25b635
+2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 4a83db6f797ad2a0b048ef996d10dbc5ea0a33dd
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
index 88f94b1f58..496499a691 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
@@ -16,23 +16,23 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)
 
 **Boot glue is a class pair.** `AppCLIEntry` (apps/cli) and `AppWebEntry` (the shell kernel) hold only what must exist independently of cordis: argv facts, the composed patch set, the parsed boot manifest, the module system instance, loading-page handles — everything else lives in plugins. `AppCLIEntry.run()` is three stages: layered env (ambient > cwd `.env` > `$DSH_HOME/.env`, closing the defect above) → patch composition → Loader include boot plus the activation audit. `AppWebEntry.run()` mirrors it browser-side: parse `window.__DSH_BOOT__` into a `BootManifest` (two views: npm-package rows for the module table, cordis-plugin rows for entry composition; malformed wire throws), build the module system, render the loading page, prefetch the `immediately` tier in parallel with Context/Loader setup, **await the prefetch before creating entries** (materialization is `tree.import`'s synchronous require, unprotected by fiber inject waiting; cross-package require edges such as i18n → runtime/client need every immediately-tier factory registered first — an empirically found 10–25% boot race otherwise), adopt the modules entry, create the graph rows, settle, sweep.
 
-**Config sources have one declaration place each.** yml static values are engineering defaults; the profile json (`./.dsh-tmp-profile/config.json`, read-only, never created, cwd-anchored until the `$DSH_HOME` migration) is user config mapped through a static `PROFILE_MAPPINGS` table onto target rows (`provider`/`model` → the `api-gateway` row, `persistenceRoot` → the jsonl row); CLI flags map onto the `webserver` row with a field set disjoint from the json's; env values enter through yml `!!js` expressions, never through the mapping table. Patches replace a row's config wholesale, so the entry class re-reads the yml row's static values (bypass parse) and merges overrides on top. An unmapped json key fails loud. The resolved frontend `distIndex` rides the same patch channel — an assembly fact, not user config.
+**Config sources have one declaration place each.** Bundle yml values are engineering defaults, Settings sections are writable user preferences, CLI flags address their owning launcher rows, and env values enter through yml `!!js` expressions. Patches replace a row's config wholesale. The resolved frontend `distIndex` uses that patch channel as an assembly fact. The transport-independent provider/model default belongs to `ctx.agentDefaultModel`; the [direct headless front door](2026-08-09-headless-direct-core-front-door.md) and the Web gateway consume the same state.
 
-**The transport splits five ways.** `dsh-host-apiproxy` upgraded to the gateway plugin (`api-gateway` row): default-exports `ApiProxyService`, config `{provider, model}`, provides `ctx.apiProxy`, transport-agnostic and registers no routes — `createApiProxy` moved here from the retired runtime package. `dsh-host-webserver` shrank to a plain route-registration plugin: `HttpServerService` provides `ctx.httpServer` (`register(route) → disposer` with duplicate-pattern throw, `tapIndex` transforms applied in registration order, `port`), listens on activation, per-request failures answer 400 and log without exiting, and knows no harness concepts. The connection node half owns the binding: it injects both services and registers `toFetchHandler(ctx.apiProxy)` under the `/api` prefix — future IPC carriers swap connection's transport while the gateway stays untouched. The modules node half (`ClientModuleHostService`, providing `ctx.clientModuleHost`) owns the graph: incremental per-package scanning (no full-rescan code path — `internal/plugin` marks the fiber's entry name dirty, a flush reconciles each name against live entries, package metadata including negative verdicts is cached forever, re-hashing is reachable only through `rebuilt(id)`), the bundle route, the index tap, and `onRebuilt`/`onGraphChanged` notification. The hmr node half owns dev reload: `fs.watchFile` stat-polling driven by `onGraphChanged` membership, and the `/plugins/events` SSE route.
+**The transport splits five ways.** `dsh-host-apiproxy` is the gateway plugin (`api-gateway` row): it default-exports `ApiProxyService`, configures only `{workspaceRoot?}`, consumes the base layer's front-door-neutral `ctx.agentDefaultModel`, provides `ctx.apiProxy`, remains transport-agnostic, and registers no routes. `dsh-host-webserver` is a plain route-registration plugin: `HttpServerService` provides `ctx.httpServer` (`register(route) → disposer` with duplicate-pattern throw, `tapIndex` transforms applied in registration order, `port`), listens on activation, answers per-request failures with 400 and logging, and knows no harness concepts. The connection node half owns the `/api` binding from `ctx.apiProxy` through `toFetchHandler`. The modules node half (`ClientModuleHostService`, providing `ctx.clientModuleHost`) owns incremental package scanning, the bundle route, the index tap, and `onRebuilt`/`onGraphChanged` notification. The hmr node half owns dev reload through `fs.watchFile` membership and the `/plugins/events` SSE route.
 
 **Package export discipline.** The modules package exposes exactly `.` (node half) and `./client` (the complete browser half: `ClientModuleSystem`, `parseBootManifest`, the adoption plugin face) — no bespoke subpaths; wire types re-export through the root for host-side consumers. The adoption handshake: the kernel writes the constructed instance to `window.__DSH_MODULES__` before cordis exists; the `./client` apply reads the slot (missing = loud throw) and provides `ctx.modules`.
 
 ## Consequences
 
 - Recomposing a web deployment is a yml/patch edit; the retired pieces (`mountWebPlugins`, `CLIENT_PACKAGES`, `createHostWebPluginRegistry`, `startWebServer`, the webserver's graph/SSE/api knowledge) are deleted.
-- Headless boots the same composition through the same entry (landed in the stacked follow-up): port 0 is its only surface difference, the model face gains `ask_user_question`/workspace context/model titles per the unification ruling, and `bootHost`/`startHost` retired with the `dsh-host-runtime` package. The profile write path, the `$DSH_HOME` profile relocation, and IPC carriers remain recorded deferrals.
+- [Headless is a direct core front door](2026-08-09-headless-direct-core-front-door.md): its shipped profile contains the shared base Agent capabilities and omits Host, HTTP, Web, and browser layers. The transport split in this note is the browser surface's contract.
 - A TypeScript pitfall worth remembering: a `declare module 'cordis'` augmentation in a file with **no cordis import** is demoted to a standalone module declaration and silently shatters the program-wide `Context` merge (`ctx.on`/`ctx.effect` vanish across the program). Anchor with `import type {} from 'cordis'`.
 
 ## Alternatives considered
 
 | Rejected | One-line reason |
 |---|---|
-| Dedicated `dsh-host-profile` receiver package | The profile json is consumed at patch time; the only runtime consumer of `{provider, model}` is the gateway itself — its config is the receiver |
+| Dedicated `dsh-host-profile` receiver package | User model state belongs to the Settings-backed `ctx.agentDefaultModel`; an extra Host receiver would duplicate ownership and exclude direct front doors |
 | Runtime `assembly` shim plugin providing an `apiHandler` service | Existed only because `createApiProxy` lived in runtime; moving it into apiproxy made the gateway self-hosting, and `toFetchHandler` is a pure function the binding side calls |
 | Full-rescan + incremental scan coexisting | Two implementations, two semantics; the single per-package path covers the activation pass too |
 | A bespoke `./impl` export on the modules package | Non-uniform export surface; the standard `./client` carries the whole browser half |
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
index 5f03dfbb8e..4a83db6f79 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
@@ -16,23 +16,23 @@ Status: implemented
 
 **boot 胶水由两个类组成。** `AppCLIEntry`（apps/cli）与 `AppWebEntry`（壳内核）只持有那些必须独立于 cordis、提前存在的东西：argv 事实、合成的 patch 集、解析出的 boot manifest（元数据清单）、模块系统实例、loading 页句柄——其余一律进插件。`AppCLIEntry.run()` 三段：分层 env（ambient > cwd `.env` > `$DSH_HOME/.env`，顺手关掉上述缺陷）→ patch 合成 → Loader include boot 加 activation audit。`AppWebEntry.run()` 在浏览器侧镜像它：把 `window.__DSH_BOOT__` 解析成 `BootManifest`（双视角：npm 包行给模块表、cordis 插件行给 entry 组合；畸形 wire 大声抛）、建模块系统、渲染 loading 页、immediately 层预取与 Context/Loader 准备并行、**create entry 之前等预取齐**（物化是 `tree.import` 的同步 require，不受 fiber inject 等待保护；i18n → runtime/client 这类跨包 require 边要求 immediately 层工厂全部注册完——否则有实测 10–25% 的 boot 竞态）、收编 modules entry、逐一创建图行、settle、sweep。
 
-**每个配置源有唯一声明位置。** yml 静态值是工程默认；profile json（`./.dsh-tmp-profile/config.json`，只读、绝不创建、暂锚 cwd 直至 `$DSH_HOME` 迁移）是用户配置，经静态 `PROFILE_MAPPINGS` 表映射到目标行（`provider`/`model` → `api-gateway` 行，`persistenceRoot` → jsonl 行）；CLI（命令行界面）flags 映射到 `webserver` 行、字段集与 json 不相交；env 值经 yml `!!js` 表达式进入，绝不进映射表。patch 整体替换行 config，故 entry 类旁路 parse 重读 yml 行静态值再叠加覆盖。未映射的 json 键 fail loud。解析出的前端 `distIndex` 走同一 patch 通道——装配事实，不是用户配置。
+**每个配置源有唯一声明位置。** 组合包 yml 值是工程默认，Settings 分节是可写的用户偏好，CLI（命令行界面）flags 面向其归属的启动器配置行，env 值则通过 yml `!!js` 表达式进入。patch 会整体替换一行的 config。解析后的前端 `distIndex` 通过同一条 patch 通道作为组装事实传递。与传输无关的提供方／模型默认值归 `ctx.agentDefaultModel` 所有；[直接 headless 前门](2026-08-09-headless-direct-core-front-door.md)与 Web 网关消费同一份状态。
 
-**传输五分。** `dsh-host-apiproxy` 升格网关插件（`api-gateway` 行）：默认导出 `ApiProxyService`，config `{provider, model}`，provide `ctx.apiProxy`，传输无关、不注册路由——`createApiProxy` 从已退役的运行时包迁入。`dsh-host-webserver` 缩成朴素路由注册插件：`HttpServerService` provide `ctx.httpServer`（`register(route) → disposer`、重复 pattern 即抛、`tapIndex` 按注册序应用、`port`），激活即 listen，单请求失败答 400 并记日志，不退出进程，不认识任何 harness 概念。connection node 半拥有绑定：inject 两个服务，把 `toFetchHandler(ctx.apiProxy)` 注册在 `/api` 前缀下——将来 IPC 载体只换 connection 的传输，网关零改动。modules node 半（`ClientModuleHostService`，provide `ctx.clientModuleHost`）拥有图：单包增量扫描（无全量重扫路径——`internal/plugin` 把 fiber 的 entry 名标脏，flush 逐名对账 live entries，包括否定结论在内的包元数据会永久缓存，重哈希唯一入口 `rebuilt(id)`）、bundle 路由、index tap、`onRebuilt`/`onGraphChanged` 通知。HMR node 半拥有开发期重载：`fs.watchFile` stat 轮询、watch 集合跟随 `onGraphChanged`、`/plugins/events` SSE 路由。
+**传输五分。** `dsh-host-apiproxy` 是网关插件（`api-gateway` 行）：默认导出 `ApiProxyService`，只配置 `{workspaceRoot?}`，消费 base 层不偏向特定前门的 `ctx.agentDefaultModel`，provide `ctx.apiProxy`，保持传输无关且不注册路由。`dsh-host-webserver` 是朴素的路由注册插件：`HttpServerService` provide `ctx.httpServer`（`register(route) → disposer`、重复 pattern 即抛、`tapIndex` 按注册序应用、`port`），激活即 listen，单请求失败时答 400 并记日志，且不认识任何 harness 概念。connection node 半拥有从 `ctx.apiProxy` 经 `toFetchHandler` 绑定到 `/api` 的逻辑。modules node 半（`ClientModuleHostService`，provide `ctx.clientModuleHost`）拥有单包增量扫描、bundle 路由、index tap 与 `onRebuilt`/`onGraphChanged` 通知。HMR node 半通过 `fs.watchFile` membership 与 `/plugins/events` SSE 路由拥有开发期重载。
 
 **包出口纪律。** modules 包只暴露 `.`（node 半）与 `./client`（完整浏览器半：`ClientModuleSystem`、`parseBootManifest`、收编插件面）——不设专用子路径；wire 类型经根出口 re-export 给 host 侧消费方。收编握手：内核在 cordis 之前把建好的实例写入 `window.__DSH_MODULES__`；`./client` 的 apply 读取该槽位（缺少时显式抛错）并 provide `ctx.modules`。
 
 ## 后果
 
 - 重组一个 web 部署 = 改 yml/patch；退役件（`mountWebPlugins`、`CLIENT_PACKAGES`、`createHostWebPluginRegistry`、`startWebServer`、webserver 的图/SSE/api 知识）全部删除。
-- headless 已在 stacked 后续轮迁入同一组合同一入口：唯一面差异是 port 0，模型面按统一裁决获得 `ask_user_question`/workspace context/模型标题，`bootHost`/`startHost` 随 `dsh-host-runtime` 包退役。profile 写入路径、profile 迁 `$DSH_HOME`、IPC 载体仍为挂账项。
+- [Headless 是直接 core 前门](2026-08-09-headless-direct-core-front-door.md)：其随附 profile 包含共享的 base Agent 能力，并省去 Host、HTTP、Web 与浏览器层。本笔记的传输划分是浏览器 surface 的契约。
 - 一个值得记住的 TypeScript 坑：`declare module 'cordis'` augmentation 所在文件若**没有任何 cordis import**，会被降级成独立 module declaration，无声打散全程序的 `Context` merge（`ctx.on`/`ctx.effect` 全程序消失）。用 `import type {} from 'cordis'` 锚定。
 
 ## 考虑过的替代方案
 
 | 弃案 | 一行理由 |
 |---|---|
-| 专门的 `dsh-host-profile` 受体包 | profile json 在 patch 阶段消费完；`{provider, model}` 的唯一运行时消费方是网关自己——受体即网关 config |
+| 专门的 `dsh-host-profile` 受体包 | 用户模型状态归 Settings 支撑的 `ctx.agentDefaultModel` 所有；额外的 Host 受体会重复归属，并排除直接前门 |
 | 运行时里的 `assembly` 垫层插件（provide `apiHandler`） | 它的存在只因 `createApiProxy` 住运行时；本体迁入 apiproxy 后网关自持插件身份，且 `toFetchHandler` 是绑定方自己调的纯函数 |
 | 全量重扫与增量扫描并存 | 两条实现两份语义；单包路径足以覆盖激活初扫 |
 | modules 包特设 `./impl` 出口 | 出口面不统一；标准 `./client` 承载完整浏览器半 |
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index 3e1d038514..342bcac5e0 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.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 .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
-2026-08-05-profile-plugin-bundles.md: 8613e600ad633818abb4319e614230340c3b3876
-2026-08-05-profile-plugin-bundles.zh.md: 03a771364c4f3262801f28e68b96ec5de633e5ec
+2026-08-05-profile-plugin-bundles.md: f183fc5ff5f3c8d850e913d9a9b836f075da7a3b
+2026-08-05-profile-plugin-bundles.zh.md: a186a27aff9ff3b4202ce5327f88637caa52b11d
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
index 8613e600ad..f183fc5ff5 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
@@ -12,7 +12,7 @@ The `dsh` launcher hardcoded its compositions: `base.cordis.yml` + `web.cordis.y
 
 Everything becomes a **profile**: a directory `$DSH_HOME/profiles/<name>` with a `package.json` (pnpm-managed out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list) and a user `cordis.patch.yml`. A **bundle** is an npm package declaring `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; the two manifest kinds live under distinct `dsh.profile` / `dsh.bundle` keys so a package.json states which role it plays. The tree composes over an empty root by applying each bundle's patch in `dsh.profile.bundles` order, then the user layer, then `--patch` overlays, then flag patches — one `applyEntryPatches` call, identical for boot, flag derivation, and `--dump-config`.
 
-The shipped compositions became bundles: `@deepseek-ai/dsh-base` (the former base rows as one insert), `@deepseek-ai/dsh-web-app` (the former web overlay plus a runtime glue plugin that owns what used to be launcher code — frontend-dist resolution, the web-surface prompt section, bash runtime variables, the URL line), and `@deepseek-ai/dsh-headless` (a one-shot runner plugin over base + web-app). `dsh web` stays as an alias for `--profile web` carrying the Web flag family; `dsh run [--profile <name>] "task"` owns one-shot execution and defaults to the headless profile, while generic `dsh --profile <name>` boots without a task; `dsh --config` is removed (its uses migrate to `--patch`). `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` after `add`/`remove` (a bundle-less package warns and stays a plain dependency).
+The shipped bundles are `@deepseek-ai/dsh-base` (shared core rows), `@deepseek-ai/dsh-web-app` (browser Host rows and Web runtime glue), and `@deepseek-ai/dsh-headless` (a direct one-shot runner over base, without web-app). `dsh web` is the Web-flag alias for `--profile web`; `dsh run [--profile <name>] "task"` owns one-shot execution and defaults to the headless profile; generic `dsh --profile <name>` boots without a task. Patch overlays use `--patch`. `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` with installed bundle declarations; a package without a bundle declaration remains a plain dependency. [Headless as a direct core front door](2026-08-09-headless-direct-core-front-door.md) owns the headless composition contract.
 
 The [`dsh run` command decision](../feature/2026-08-08-dsh-run-headless-command.md) owns the one-shot grammar; this note owns the profile composition it selects.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index 03a771364c..a186a27aff 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
 
-已交付的组合改造成了组合包：`@deepseek-ai/dsh-base`（原有基础行合并为一次插入）、`@deepseek-ai/dsh-web-app`（原 web overlay，外加一个接管原启动器代码的运行时粘合插件——前端 dist 解析、web 表层提示词段落、bash 运行时变量、URL 行）、`@deepseek-ai/dsh-headless`（叠加在 base + web-app 之上的一次性 runner 插件）。`dsh web` 保留为携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile，而通用的 `dsh --profile <name>` 只启动 profile，不携带任务；`dsh --config` 被移除（其用途迁移到 `--patch`）。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并在 `add`／`remove` 后调和 `dsh.profile.bundles`（没有组合包声明的包会给出警告，保持为普通依赖）。
+随附的组合包是 `@deepseek-ai/dsh-base`（共享核心配置行）、`@deepseek-ai/dsh-web-app`（浏览器 Host 配置行与 Web 运行时粘合层）和 `@deepseek-ai/dsh-headless`（直接叠加在 base 上且不含 web-app 的一次性 runner）。`dsh web` 是携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile；通用的 `dsh --profile <name>` 启动 profile 而不携带任务。patch overlay 使用 `--patch`。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 前门](2026-08-09-headless-direct-core-front-door.md)负责 headless 组合契约。
 
 [`dsh run` 命令决策](../feature/2026-08-08-dsh-run-headless-command.md)负责一次性语法；本 Agent Note 负责该语法所选择的 profile 组合。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
new file mode 100644
index 0000000000..cab1c8e338
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-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 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
+2026-08-09-headless-direct-core-front-door.md: cae17970633d6eda9d4f823118827ee2bfe32abf
+2026-08-09-headless-direct-core-front-door.zh.md: 8ff5e870b7f0fbc82065c6c55b4635cdc586036c
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
new file mode 100644
index 0000000000..cae1797063
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
@@ -0,0 +1,44 @@
+# Agent Note: headless is a direct core front door
+
+Status: implemented
+
+English | [中文](2026-08-09-headless-direct-core-front-door.zh.md)
+
+## Problem
+
+The `headless` product contract is one local task with final assistant text on stdout, a success-sensitive exit code, empty stderr on success, and no listening port. A composition containing Workspace Host services, ApiProxy, HTTP, the Web runtime, or browser plugins contradicts that contract and makes local completion depend on an unrelated transport tree.
+
+The direct front door still needs the same deployment model state as Web-created Agents. A separate provider/model default would give one deployment two answers, while deriving completion before the Agent and Session persistence are quiescent permits stdout and the exit code to observe incomplete state.
+
+## Decision
+
+The shipped `headless` profile contains `dsh-base` and `dsh-headless`. The headless bundle supplies its persona and tool mode, disables HMR, mounts the Code Mode worker explicitly, and inserts `headless-runner`. Its tree contains no `@deepseek-ai/dsh-host-*` package, ApiProxy, HTTP server, Web runtime, or browser client. Code Mode and Session persistence are one-shot Agent capabilities independent of Web presentation.
+
+`headless-runner` is a direct core front door. After Loader settlement, it reads `ctx.agentDefaultModel.currentSelection()`, creates a fresh persisted Agent through `ctx.agents.create`, installs that `ModelSelection` in the Agent scope, waits for startup quiescence, anchors the Session sequence, submits one ordinary user message, and waits for quiescence again. It awaits `ctx.sessions.flush`, folds its durable event interval for the last non-empty assistant text and final `turn/end` reason, writes the text plus one newline to stdout, and requests bounded launcher shutdown with exit 0 exactly when the reason is `completed`. Unexpected driver failures use stderr and exit 1.
+
+`@deepseek-ai/dsh-agent-default-model` owns the transport-independent default used for an Agent without a session-local selection. `AgentDefaultModelService` provides `ctx.agentDefaultModel` and registers the `agent-default-model` Settings section. Composition config supplies `{provider, model}`; user settings may also supply `reasoningEffort`. `currentSelection()` returns the live complete selection and `saveSelection()` writes it as a complete section, so a selection without an effort clears any stored effort. `dsh-base` supplies the composition entry. Direct and ApiProxy front doors consume this service; ApiProxy alone owns session-local precedence, model validation, and persistence of accepted Web selections.
+
+`loadProfile` recognizes the exact installation-owned headless tuple (`dsh-base`, `dsh-web-app`, `dsh-headless`) and normalizes it to the shipped headless template while preserving every other manifest field. Extra, missing, or reordered bundle lists are user-owned and remain untouched.
+
+This note owns the headless transport and completion contracts. [`dsh run` owns one-shot headless execution](../feature/2026-08-08-dsh-run-headless-command.md) owns the command grammar, [GUI layering and RPC protocol](2026-07-19-gui-layering-and-rpc-protocol.md) owns browser gateway boundaries, [web config-tree boot and transport layering](2026-07-24-web-config-tree-boot-and-transport-layering.md) owns the Web tree, and [the default model follows the picker](../feature/2026-08-07-default-model-follows-the-picker.md) owns persistence of the shared Agent default.
+
+## Verification
+
+Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshot drives `dsh run` through a replayed tool round trip and records direct user-message provenance. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
+
+## Alternatives considered
+
+| Alternative | Contract mismatch |
+|---|---|
+| Keep `dsh-web-app` but suppress its observation line | The process still opens a port and carries the Host, Web, and browser trees. |
+| Build a Host-only one-shot bundle around ApiProxy | ApiProxy is a client protocol gateway; a local one-shot front door has no client boundary. |
+| Use `InProcessApiClient` for product-level protocol coverage | Product execution would depend on an unrelated protocol solely to exercise that protocol. |
+| Give headless a separate provider/model config | Direct and Web creation would have independent defaults and persistence. |
+| Omit Code Mode and Session persistence | Both capabilities belong to one-shot Agent execution rather than Web presentation. |
+| Normalize every tuple containing Web and headless bundles | Bundle lists are an extension surface; only the exact installation-owned tuple is safe to classify. |
+
+## Consequences
+
+`dsh run` provides a local Agent task rather than browser observation, Host APIs, or HTTP. Users who need those capabilities choose `dsh web`. Successful stderr is empty, completion follows durable flush, and the persisted Session remains available to later tooling. Its initial user message has direct user provenance and therefore carries no ApiProxy `rpcId`.
+
+ApiProxy carrier coverage stays in the ApiProxy package. Custom one-shot profiles may include Host or Web bundles explicitly, while the shipped profile and the recognized installation-owned tuple are Web-free.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
new file mode 100644
index 0000000000..8ff5e870b7
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
@@ -0,0 +1,44 @@
+# Agent Note: headless 是直接使用核心服务的入口
+
+Status: implemented
+
+[English](2026-08-09-headless-direct-core-front-door.md) | 中文
+
+## 问题
+
+`headless` 的产品契约是一个本地任务：最终 assistant 文本写入 stdout，退出状态反映成功与否，成功时 stderr 为空，并且不打开监听端口。包含 Workspace Host 服务、ApiProxy、HTTP、Web 运行时或浏览器插件的组合违背这一契约，也使本地完成状态依赖无关的传输树。
+
+直接前门仍需要与 Web 所创建 Agent 相同的部署模型状态。独立的提供方／模型默认值会让同一部署产生两种答案，而在 Agent 与会话持久化完全停稳之前推导完成状态，会让 stdout 与退出状态观察到不完整状态。
+
+## 决策
+
+随附的 `headless` profile 包含 `dsh-base` 与 `dsh-headless`。headless 组合包提供自身的 persona 与工具模式、禁用 HMR（热模块替换）、显式挂载 Code Mode worker，并插入 `headless-runner`。其插件树不包含任何 `@deepseek-ai/dsh-host-*` 包、ApiProxy、HTTP server、Web 运行时或浏览器客户端。Code Mode 与会话持久化均为独立于 Web 呈现的一次性 Agent 能力。
+
+`headless-runner` 是直接使用核心服务的入口。Loader 完全加载后，它读取 `ctx.agentDefaultModel.currentSelection()`，通过 `ctx.agents.create` 创建一个新的持久化 Agent，在 Agent 作用域中安装该 `ModelSelection`，等待启动工作完全停稳，锚定会话事件序号，提交一条普通用户消息，再次等待完全停稳。随后，它等待 `ctx.sessions.flush`，折叠自身持有的持久事件区间，以取得最后一条非空 assistant 文本和最终 `turn/end` 结束原因，将文本连同一个换行写入 stdout，并且仅在结束原因为 `completed` 时请求启动器以退出状态 0 有界关闭。驱动器的意外失败写入 stderr 并以 1 退出。
+
+`@deepseek-ai/dsh-agent-default-model` 拥有与传输无关的默认值，供没有会话级选择的 Agent 使用。`AgentDefaultModelService` 提供 `ctx.agentDefaultModel` 并注册 `agent-default-model` Settings 分节。组合配置提供 `{provider, model}`，用户设置还可以提供 `reasoningEffort`。`currentSelection()` 返回当前的完整选择，`saveSelection()` 则写入完整分节，因此不含强度的选择会清除已存强度。`dsh-base` 提供组合条目。直接前门与 ApiProxy 前门均消费该服务；只有 ApiProxy 负责会话级优先级、模型校验与已接受 Web 选择的持久化。
+
+`loadProfile` 识别安装过程拥有的精确 headless 元组（`dsh-base`、`dsh-web-app`、`dsh-headless`），将其规范化为随附的 headless 模板，并保留 manifest（元数据清单）的其他所有字段。带额外项、缺少项或顺序不同的组合包列表归用户所有，保持不变。
+
+本 Agent Note 负责 headless 的传输与完成契约。[`dsh run` 负责一次性 headless 执行](../feature/2026-08-08-dsh-run-headless-command.md)负责命令语法，[GUI 分层与 RPC 协议](2026-07-19-gui-layering-and-rpc-protocol.md)负责浏览器网关边界，[Web 配置树启动与传输分层](2026-07-24-web-config-tree-boot-and-transport-layering.md)负责 Web 插件树，[默认模型跟随选择器](../feature/2026-08-07-default-model-follows-the-picker.md)负责共享 Agent 默认值的持久化。
+
+## 验证
+
+包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，并记录直接用户消息的来源。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
+
+## 考虑过的替代方案
+
+| 替代方案 | 契约不匹配之处 |
+|---|---|
+| 保留 `dsh-web-app`，但隐藏观察行 | 进程仍会打开端口并携带 Host、Web 与浏览器插件树。 |
+| 围绕 ApiProxy 构建纯 Host 一次性组合包 | ApiProxy 是客户端协议网关，而本地一次性前门没有客户端边界。 |
+| 使用 `InProcessApiClient` 实现产品级协议覆盖 | 产品执行会仅为测试无关协议而依赖该协议。 |
+| 为 headless 单独提供提供方／模型配置 | 直接创建与 Web 创建会拥有彼此独立的默认值和持久化。 |
+| 省略 Code Mode 与会话持久化 | 两项能力都属于一次性 Agent 执行，而不是 Web 呈现。 |
+| 规范化所有包含 Web 与 headless 组合包的元组 | 组合包列表是扩展面；只有精确的安装过程所属元组可以安全分类。 |
+
+## 后果
+
+`dsh run` 提供本地 Agent 任务，而不是浏览器观察、Host API 或 HTTP。需要这些能力的用户选择 `dsh web`。成功时 stderr 为空，完成结果在持久化 flush 后推导，持久化会话仍可供后续工具使用。初始用户消息直接来自用户，因此不携带 ApiProxy `rpcId`。
+
+ApiProxy 载体覆盖保留在 ApiProxy 包中。自定义一次性 profile 可以显式包含 Host 或 Web 组合包；随附 profile 与可识别的安装过程所属元组均不含 Web。
diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml
index 77104f258e..626d98b3c8 100644
--- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.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 .agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md
-2026-07-24-web-session-model-selector.md: 05e923fb3b5df72485ffb8d6ff5aa0104b19a8a0
-2026-07-24-web-session-model-selector.zh.md: c1fd59ada0340a984ddf4a9dcc4c357f9609acb1
+2026-07-24-web-session-model-selector.md: 78017b14a806f8e609a85e340094cd2a349d47e1
+2026-07-24-web-session-model-selector.zh.md: 87a342721f5e47f5bcedfafb578eb6916101d2f5
diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md
index 05e923fb3b..78017b14a8 100644
--- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md
+++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md
@@ -6,17 +6,17 @@ English | [中文](2026-07-24-web-session-model-selector.zh.md)
 
 ## Problem
 
-The Web conversation displayed and sent through the Host's fixed provider/model route without exposing that route or letting a user change it. The TUI already had a session-local route target, but copying its presentation or hardcoding DeepSeek models in the browser would split model discovery and step-boundary semantics across front doors. A switch made while a response is running also needs one atomic boundary: prompt variables and request routing cannot observe different targets.
+The Web conversation needs a visible, mutable session model selection sourced from the Host. Copying TUI presentation or hardcoding DeepSeek models in the browser would split model discovery and step-boundary semantics across front doors. A switch made while a response is running also needs one atomic boundary: prompt variables and request routing cannot observe different selections.
 
 ## Decision
 
-The Web Host reuses `installAgentLlmTarget` for every created or resumed agent. The provider/model/reasoning target starts from the latest `request/header` when the session has used a model, otherwise from the Host default route. `session.selectModel` changes the session-local mutable target, and prompt assembly captures it with request routing; a switch during a running step therefore applies to the next assembled step. The next consumed target persists through the existing full `request/header` snapshot, while a choice that has not reached a request remains process-local.
+The Web Host installs `ModelSelection` for every created or resumed Agent. The provider/model/reasoning selection comes from the latest `request/header` when the session has used a model, otherwise from `ctx.agentDefaultModel`. `session.selectModel` assigns the session-local selection, and prompt assembly captures it with request routing; a switch during a running step therefore applies to the next assembled step. The next consumed selection persists through the full `request/header` snapshot, while a choice that has not reached a request remains process-local.
 
-The session RPC domain exposes a `session.models` directory and `session.selectModel`. The directory is built dynamically from the LLM registry and grouped by provider; each listed model's exact metadata adds adapter-owned reasoning effort ids, names, descriptions, and optional default. Provider catalogs and exact metadata load concurrently by provider and fail independently, so successful groups remain usable alongside retryable failure records. Catalog membership stays advisory: `session.models.current` is returned independently and can remain routable when absent from every group, but the Host does not synthesize an unlisted row after its provider stops advertising it. The two surfaces answer that state differently on purpose: the TUI still renders the unlisted current model as its own row and marks it current, while Web shows the unset trigger label and asks for a replacement. Web is the surface where a catalog is edited, so a target the user just deleted should read as a decision to make rather than a selection to keep; the TUI, which only picks from what exists, has no such edit to reconcile. The cost is real and accepted — a Web composer showing the unset label can still send to the routed target — and the divergence is deliberate, not a missed migration. Exact resolution decides whether a route and explicit effort are available. Selection uses `resolveCallConfig` to reject unsupported effort ids and materialize an adapter-configured default before updating the target.
+The session RPC domain exposes a `session.models` directory and `session.selectModel`. The directory is built dynamically from the LLM registry and grouped by provider; each listed model's exact metadata adds adapter-owned reasoning effort ids, names, descriptions, and optional default. Provider catalogs and exact metadata load concurrently by provider and fail independently, so successful groups remain usable alongside retryable failure records. Catalog membership stays advisory: `session.models.current` is returned independently and can remain routable when absent from every group, but the Host does not synthesize an unlisted row after its provider stops advertising it. The two surfaces answer that state differently: the TUI renders the unlisted current model as its own row, while Web shows the unset trigger label and asks for a replacement. Web is the surface where a catalog is edited, so an absent row presents a selection decision; the TUI only picks from existing rows. A Web composer showing the unset label can still send with its current routable selection. Exact resolution decides whether a provider/model pair and explicit effort are available. Selection uses `resolveCallConfig` to reject unsupported effort ids and materialize an adapter-configured default before assigning the selection.
 
-The browser `ModelService` owns one `ModelDirectory` per live session. Its snapshot contains the current complete target, grouped catalog, provider failures, operation error, and `idle`/`loading`/`ready`/`selecting`/`error` state. Mounting primes the trigger label and each menu open refreshes the directory. Directory and selection calls share an operation generation so older responses cannot replace a newer result; connection reset discards the process-local projection before restoring the Host target. Failures retain the previous current target and usable groups.
+The browser `ModelService` owns one `ModelDirectory` per live session. Its snapshot contains the current complete `ModelSelection`, grouped catalog, provider failures, operation error, and `idle`/`loading`/`ready`/`selecting`/`error` state. Mounting primes the trigger label and each menu open refreshes the directory. Directory and selection calls share an operation generation so an older response cannot replace a newer result; connection reset discards the process-local projection before restoring the Host selection. Failures retain the previous selection and usable groups.
 
-`@deepseek-ai/dsh-client-ui-conversation` declares the session-scoped single slot `conversation.input.model` as a child of its composer-bar entry. InputBar renders the seat in its trailing controls immediately before the pending indicator and primary button; the seat receives the bar's `locked` owner prop and session scope. `@deepseek-ai/dsh-client-ui-model` occupies that seat and also contributes `/model` over the same directory. Its compact trigger displays the exact catalog model name and effective reasoning label. When the current target is absent from the groups, the trigger instead displays `Select model`, the model list marks no row active, and the Effort row stays absent; choosing a listed model replaces the complete target through the existing selection path. The upward menu otherwise first offers Model and Effort; Model drills into provider groups, while Effort drills into the adapter-ordered levels. The provider-default row appears only when the adapter does not configure a model default.
+`@deepseek-ai/dsh-client-ui-conversation` declares the session-scoped single slot `conversation.input.model` as a child of its composer-bar entry. InputBar renders the seat in its trailing controls immediately before the pending indicator and primary button; the seat receives the bar's `locked` owner prop and session scope. `@deepseek-ai/dsh-client-ui-model` occupies that seat and also contributes `/model` over the same directory. Its compact trigger displays the exact catalog model name and effective reasoning label. When the current selection is absent from the groups, the trigger displays `Select model`, the model list marks no row active, and the Effort row stays absent; choosing a listed model assigns the complete selection through the shared selection path. The upward menu otherwise first offers Model and Effort; Model drills into provider groups, while Effort drills into the adapter-ordered levels. The provider-default row appears only when the adapter does not configure a model default.
 
 The production browser roster is assembled from `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml`; the model feature is one `dshClient` row rather than a package hardcoded in Web boot code. Its package manifest orders it after the runtime and command feature, while Cordis service injection waits for the conversation slot before registering the composer occupant.
 
@@ -26,18 +26,18 @@ The production browser roster is assembled from `apps/cli/config/base.cordis.yml
 
 **Hardcode the current DeepSeek catalog in the Web client.** This would drift from registered adapters and exclude deployment-owned providers. The LLM registry remains the source of provider and model metadata, including partial lookup failures.
 
-**Keep `High`/`Max` as client-local UI state.** Static DeepSeek labels cannot represent `off`, pi-ai provider vocabularies, adapter defaults, validation, resume, or the next provider request. Exact-model metadata owns the selectable vocabulary, and the session target owns the selected id.
+**Keep `High`/`Max` as client-local UI state.** Static DeepSeek labels cannot represent `off`, pi-ai provider vocabularies, adapter defaults, validation, resume, or the next provider request. Exact-model metadata owns the selectable vocabulary, and the session selection owns the selected id.
 
-**Make the selection a global default.** A global mutation would unexpectedly redirect other open conversations. The target belongs to one live session, while Host configuration remains the default for sessions without a logged request.
+**Use only a global default.** A default mutation would unexpectedly redirect blank conversations. The session selection belongs to one live session, while `ctx.agentDefaultModel` supplies the fallback for sessions without a logged request.
 
-**Reject changes while an agent is running.** The shared atomic target already separates the assembled step from the next selection. Keeping the selector available lets the user prepare the following step without altering the in-flight request.
+**Reject changes while an Agent is running.** The atomic selection snapshot separates the assembled step from the next selection. Keeping the selector available lets the user prepare the following step without altering the in-flight request.
 
 **Persist every click as a new session event.** A choice is not model-visible until prompt assembly consumes it. Persisting unused UI intent would add a durable event that does not reconstruct a model request; the existing `request/header` records the first request that actually uses the route.
 
 ## Consequences
 
-Any Host-backed Web conversation, including a blank session, can switch among dynamically discovered provider groups and adapter-owned reasoning levels without displaying duplicated `provider/model` labels. The current consumed target survives resume and reconnect; catalog names remain presentation-only, while selection and persistence use provider/model/effort ids. A provider catalog or exact-metadata outage degrades only that group. Route changes can reduce provider-side cache reuse, but the selector adds no prompt content and does not disturb the in-flight step. A model without reasoning metadata has no Effort row.
+Any Host-backed Web conversation, including a blank session, can switch among dynamically discovered provider groups and adapter-owned reasoning levels without displaying duplicated `provider/model` labels. The consumed selection survives resume and reconnect; catalog names remain presentation-only, while selection and persistence use provider/model/effort ids. A provider catalog or exact-metadata outage degrades only that group. Provider/model changes can reduce provider-side cache reuse, but the selector adds no prompt content and does not disturb the in-flight step. A model without reasoning metadata has no Effort row.
 
 ## Testing
 
-Host tests pin grouped discovery, catalog and exact-metadata failure isolation, logged effort restoration without stale-row injection, advisory unlisted selection, unsupported effort rejection, default materialization, and next-assembly switching. Client tests pin the shared directory, reconnect restoration, and complete-target submission. Component tests pin dynamic effort labels, descriptions, provider-default exposure, effort submission, and the `Select model` fallback for a removed row. The keyless built-app fixture loads the production model plugin, selects OpenAI's GPT-5 and its Max effort, sends a turn, and verifies that the next generated response reports both ids; the DeepSeek configuration fixture removes the active catalog row and pins the fallback before choosing a replacement.
+Host tests pin grouped discovery, catalog and exact-metadata failure isolation, logged effort restoration without stale-row injection, advisory unlisted selection, unsupported effort rejection, default materialization, and next-assembly switching. Client tests pin the shared directory, reconnect restoration, and complete-selection submission. Component tests pin dynamic effort labels, descriptions, provider-default exposure, effort submission, and the `Select model` fallback for an absent row. The keyless built-app fixture loads the production model plugin, selects OpenAI's GPT-5 and its Max effort, sends a turn, and verifies that the next generated response reports both ids; the DeepSeek configuration fixture omits the active catalog row and pins the fallback before choosing a replacement.
diff --git a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
index c1fd59ada0..87a342721f 100644
--- a/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md
@@ -6,17 +6,17 @@ Status: implemented
 
 ## 问题
 
-Web 对话原本通过 Host 固定的提供方与模型路由显示并发送消息，既不呈现该路由，也不允许用户更改。TUI 已经具备会话级的路由目标，但如果照搬其呈现方式，或在浏览器中硬编码 DeepSeek 模型，就会让模型发现逻辑和步骤边界语义分散到不同前门中。响应运行期间发生的切换还需要一个原子边界：提示词变量与请求路由不能观测到不同的目标。
+Web 对话需要一项由 Host 提供、可见且可更改的会话模型选择。如果照搬 TUI 的呈现方式，或在浏览器中硬编码 DeepSeek 模型，就会让模型发现逻辑和步骤边界语义分散到不同前门中。响应运行期间发生的切换还需要一个原子边界：提示词变量与请求路由不能观测到不同的选择。
 
 ## 决策
 
-Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlmTarget`。如果会话已经使用过模型，提供方／模型／推理（reasoning）目标从最新的 `request/header` 开始；否则采用 Host 默认路由。`session.selectModel` 会更改会话级可变目标，提示词组装则将该目标与请求路由一并捕获，因此运行中步骤发生的切换会应用于下一个组装步骤。下一个实际采用的目标通过现有的完整 `request/header` 快照持久化；尚未进入请求的选择则仅保存在当前进程中。
+Web Host 为每个新建或恢复的 Agent 安装 `ModelSelection`。如果会话已经使用过模型，提供方／模型／推理（reasoning）选择来自最新的 `request/header`；否则来自 `ctx.agentDefaultModel`。`session.selectModel` 会赋值会话级选择，提示词组装则将它与请求路由一并捕获，因此运行中步骤发生的切换会应用于下一个组装步骤。下一个实际采用的选择通过完整的 `request/header` 快照持久化；尚未进入请求的选择则仅保存在当前进程中。
 
-会话 RPC 领域公开 `session.models` 模型目录与 `session.selectModel`。该目录从 LLM（大语言模型）注册表动态构建，并按提供方分组；每个已列出模型的精确元数据还会加入由适配器持有的推理强度 ID、名称、说明和可选默认值。各提供方的目录与精确元数据会按提供方并发加载，且彼此独立失败，因此成功加载的分组仍可与可重试的失败记录一同使用。模型是否位于目录仅供参考：`session.models.current` 独立返回，即使不在任何分组中也仍然可以路由，但提供方停止公布该模型后，Host 不会合成未列出行。两个前门有意对这一状态给出不同回答：TUI 仍把未列出的当前模型渲染为独立一行并标记为当前，Web 则显示未设置状态的触发器标签并要求选择替代模型。Web 正是编辑目录所在的前门，因此用户刚刚删除的目标应当读作一个有待作出的决定，而不是一项可以保留的选择；TUI 只在已存在的模型中挑选，没有这类编辑需要调和。这一代价真实存在且已被接受——显示未设置标签的 Web composer 仍会发送到实际路由的目标——这一分歧是有意为之，而不是一处遗漏的迁移。精确解析决定路由与显式推理强度是否可用。选择操作通过 `resolveCallConfig` 拒绝不支持的推理强度 ID，并在更新目标前具体化适配器配置的默认值。
+会话 RPC 领域公开 `session.models` 模型目录与 `session.selectModel`。该目录从 LLM（大语言模型）注册表动态构建，并按提供方分组；每个已列出模型的精确元数据还会加入由适配器持有的推理强度 ID、名称、说明和可选默认值。各提供方的目录与精确元数据会按提供方并发加载，且彼此独立失败，因此成功加载的分组仍可与可重试的失败记录一同使用。模型是否位于目录仅供参考：`session.models.current` 独立返回，即使不在任何分组中也仍然可以路由，但提供方停止公布该模型后，Host 不会合成未列出行。两个前门对这一状态给出不同回答：TUI 把未列出的当前模型渲染为独立一行，Web 则显示未设置状态的触发器标签并要求选择替代模型。Web 是编辑目录的 surface，因此缺席的目录行代表一项待作出的选择；TUI 只从现有行中选择。显示未设置标签的 Web composer 仍可以使用当前可路由选择发送消息。精确解析决定提供方／模型组合与显式推理强度是否可用。选择操作通过 `resolveCallConfig` 拒绝不支持的推理强度 ID，并在赋值该选择前具体化适配器配置的默认值。
 
-浏览器中的 `ModelService` 为每个实时会话持有一个 `ModelDirectory`。其快照包含当前完整目标、分组目录、提供方失败记录、操作错误，以及 `idle`、`loading`、`ready`、`selecting`、`error` 状态。挂载时会预先填充触发器标签，此后每次打开菜单都会刷新目录。目录与选择调用共用操作代次，防止较早响应覆盖较新结果；连接重置会先丢弃当前进程中的投影，再恢复 Host 目标。失败时保留先前的当前目标和可用分组。
+浏览器中的 `ModelService` 为每个实时会话持有一个 `ModelDirectory`。其快照包含当前完整的 `ModelSelection`、分组目录、提供方失败记录、操作错误，以及 `idle`、`loading`、`ready`、`selecting`、`error` 状态。挂载时会预先填充触发器标签，此后每次打开菜单都会刷新目录。目录与选择调用共用操作代次，防止较早响应覆盖较新结果；连接重置会先丢弃当前进程中的投影，再恢复 Host 选择。失败时保留先前的选择和可用分组。
 
-`@deepseek-ai/dsh-client-ui-conversation` 将会话作用域的单实例 slot `conversation.input.model` 声明为其输入栏 entry 的子 slot。InputBar 在尾部控件区将该 seat 渲染于 pending 指示器与主按钮之前；该 seat 接收输入栏的 `locked` owner prop 与会话作用域。`@deepseek-ai/dsh-client-ui-model` 占用该 seat，并在同一目录上提供 `/model`。其紧凑型触发器显示目录中精确模型的名称与生效的推理强度标签。当前目标不在分组中时，触发器改为显示 `Select model`，模型列表不标记任何活动行，Effort 行也保持隐藏；选择一个已列出的模型，会通过现有选择路径替换完整目标。除此情形外，向上展开的菜单会首先提供 Model 与 Effort；Model 可深入提供方分组，Effort 可深入适配器排序的级别。仅当适配器没有配置模型默认值时，才显示提供方默认值行。
+`@deepseek-ai/dsh-client-ui-conversation` 将会话作用域的单实例 slot `conversation.input.model` 声明为其输入栏 entry 的子 slot。InputBar 在尾部控件区将该 seat 渲染于 pending 指示器与主按钮之前；该 seat 接收输入栏的 `locked` owner prop 与会话作用域。`@deepseek-ai/dsh-client-ui-model` 占用该 seat，并在同一目录上提供 `/model`。其紧凑型触发器显示目录中精确模型的名称与生效的推理强度标签。当前选择不在分组中时，触发器显示 `Select model`，模型列表不标记任何活动行，Effort 行也保持隐藏；选择一个已列出的模型，会通过共享的选择路径赋值完整选择。除此情形外，向上展开的菜单会首先提供 Model 与 Effort；Model 可深入提供方分组，Effort 可深入适配器排序的级别。仅当适配器没有配置模型默认值时，才显示提供方默认值行。
 
 生产环境的浏览器名册由 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 共同组装；模型功能对应其中一行 `dshClient` 配置项，而不是 Web boot 代码中硬编码的包。其包 manifest（元数据清单）将加载顺序置于运行时与命令功能之后；Cordis 服务注入则等待 conversation slot 可用，再注册 composer 占用方。
 
@@ -26,18 +26,18 @@ Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlm
 
 **在 Web 客户端中硬编码当前 DeepSeek 目录。** 该目录会与已注册适配器发生偏离，也会排除部署自有的提供方。LLM 注册表继续作为提供方与模型元数据的真源，也负责呈现部分查询失败。
 
-**将 `High`／`Max` 保留为客户端本地 UI 状态。** 静态 DeepSeek 标签无法覆盖 `off`、pi-ai 的提供方词汇、适配器默认值与校验，也不能参与恢复或下一次提供方请求。精确模型元数据拥有可选词汇，会话目标则拥有已选择的 ID。
+**将 `High`／`Max` 保留为客户端本地 UI 状态。** 静态 DeepSeek 标签无法覆盖 `off`、pi-ai 的提供方词汇、适配器默认值与校验，也不能参与恢复或下一次提供方请求。精确模型元数据拥有可选词汇，会话选择则拥有已选择的 ID。
 
-**将选择设为全局默认值。** 全局变更会意外改道其他已打开的对话。目标仅属于一个实时会话；对于没有已记录请求的会话，Host 配置仍是默认值。
+**只使用全局默认值。** 默认值变更会意外改道空白对话。会话选择仅属于一个实时会话；对于没有已记录请求的会话，`ctx.agentDefaultModel` 提供回退值。
 
-**agent 运行期间拒绝更改。** 共享原子目标已经将当前组装步骤与下一次选择分离。保持选择器可用，可以让用户为下一个步骤预先选择模型，而不会改变正在执行的请求。
+**Agent 运行期间拒绝更改。** 原子选择快照将当前组装步骤与下一次选择分离。保持选择器可用，可以让用户为下一个步骤预先选择模型，而不会改变正在执行的请求。
 
 **将每次点击作为新的会话事件持久化。** 只有提示词组装采用某项选择后，该选择才对模型可见。持久化尚未使用的 UI 意图，会增加一个无法重建模型请求的持久事件；现有 `request/header` 会记录首次实际使用该路由的请求。
 
 ## 影响
 
-任何由 Host 支撑的 Web 对话（包括空白会话）都可以在动态发现的提供方分组和适配器持有的推理级别之间切换，而无需显示重复的 `provider/model` 标签。当前实际采用的目标会在恢复和重连后保留；目录名称仅用于呈现，而选择和持久化使用提供方／模型／推理强度 ID。某个提供方的目录或精确元数据不可用时，只有相应分组会降级。路由变更可能降低提供方侧的缓存复用率，但选择器不会添加任何提示词内容，也不会干扰正在执行的步骤。没有推理元数据的模型不显示 Effort 行。
+任何由 Host 支撑的 Web 对话（包括空白会话）都可以在动态发现的提供方分组和适配器持有的推理级别之间切换，而无需显示重复的 `provider/model` 标签。实际采用的选择会在恢复和重连后保留；目录名称仅用于呈现，而选择和持久化使用提供方／模型／推理强度 ID。某个提供方的目录或精确元数据不可用时，只有相应分组会降级。提供方／模型变更可能降低提供方侧的缓存复用率，但选择器不会添加任何提示词内容，也不会干扰正在执行的步骤。没有推理元数据的模型不显示 Effort 行。
 
 ## 测试
 
-Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、不受目录约束的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整目标提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及已删除模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会删除活动目录行，在选择替代模型之前固定该回退。
+Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、不受目录约束的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整选择提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及缺席模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会省略活动目录行，在选择替代模型之前固定该回退。
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
index f513e90666..0f28e14222 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.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 .agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
-2026-08-07-default-model-follows-the-picker.md: d20f0ab8b8c8bd19f596e6ef73f0a58d96c24d38
-2026-08-07-default-model-follows-the-picker.zh.md: 0d2821cb63407fe766e6fe3d36de31d9fc6f1c13
+2026-08-07-default-model-follows-the-picker.md: ed7e7a424d2cacadea890506fd9150ffdf7a993c
+2026-08-07-default-model-follows-the-picker.zh.md: 52308518f06a140a9f79440e48229356bc61dca5
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
index d20f0ab8b8..ed7e7a424d 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md
@@ -6,38 +6,42 @@ English | [中文](2026-08-07-default-model-follows-the-picker.zh.md)
 
 ## Problem
 
-The route a new session started from was frozen into the gateway's composition entry (`api-gateway` in the web-app bundle patch). Switching models in a conversation reached that conversation only: the next session went back to the shipped default, and the only way to change it was to hand-edit a `cordis.yml` row and restart. There was no user-settings tier between the composition and the per-session choice.
+A session model picker and a deployment default are two layers of the same preference. If the picker affects only its addressed session, the next blank session can select a different model with no user-facing way to align the default. If the default lives inside a Host gateway, direct Agent front doors cannot share it without depending on Host or duplicating state.
+
+Reasoning effort makes the persistence shape significant: a model selection without an effort must clear a stored effort, or the next Agent may apply an effort that its selected model does not accept.
 
 ## Decision
 
-`ApiProxyService` registers its `{provider, model, reasoningEffort?}` slice as the `api-gateway` settings section: the composition entry is the `base` layer and `settings.yaml` layers the user's choice over it. `workspaceRoot` stays outside the section — a launcher fact, not a preference. `reasoningEffort` is the mirror case: it lives in the section but NOT in the plugin config, because the seam merges the user layer over the composition entry per field and an absent key cannot override a present one. A composition-set effort would therefore survive every later switch to a model without one — precisely the stranding the wholesale `replace` exists to prevent. Effort is a per-model fact anyway; a deployment default for it belongs on the adapter profile, which resolves per model.
+`AgentDefaultModelService` provides `ctx.agentDefaultModel` and registers `{provider, model, reasoningEffort?}` as the `agent-default-model` Settings section. Its `{provider, model}` composition entry is the base layer and `settings.yaml` supplies the user layer. The service is front-door-neutral, so direct creation and ApiProxy-backed creation share one default ([headless direct core front door](../architecture/2026-08-09-headless-direct-core-front-door.md)). `workspaceRoot` remains ApiProxy config because it is a Host launcher fact rather than model state.
 
-`session.selectModel` records an accepted switch as the new default. There is no separate gesture: switching models in the composer IS how the default is chosen. The write is `replace`, not `update` — switching to a model with no reasoning effort has to clear a stored one, and a merged patch would strand it for the next session to fail on. A storage failure is logged without undoing the switch, which already applies to its own session, and a deployment with no settings provider keeps the entry with the switch staying process-local.
+`reasoningEffort` belongs to the Settings section but not to the plugin config. Settings layers merge by field, so a configured effort would survive a user selection that omits it. `saveSelection()` instead writes the complete user section; absence therefore clears a stored effort. A deployment-wide effort default belongs to the adapter profile, which resolves it per model.
 
-`ApiProxyDefaults` carries `defaultTarget()` and `persistDefaultTarget()` closures instead of flat `provider`/`model` fields, so `createApiProxy` needs no knowledge of the settings seam.
+`session.selectModel` applies an accepted `ModelSelection` to its session and calls `saveDefaultModelSelection()` for the shared Agent default. A storage failure is logged without undoing the session selection. A deployment with no settings provider retains the composition entry and keeps the accepted selection only in that session.
 
-`targetFor` resolves its tiers on **every** read rather than seeding a ref once: an explicit selection in this process, else the session's own latest logged `request/header`, else the live default. Both directions depend on the re-read. A session that has run a turn derives from its log forever after, so changing the default never retargets it. A session still blank starts from a default saved after it was created — which matters because New Session reuses a blank session rather than minting another, so a creation-time seed would show the superseded model in exactly the flow the feature exists for.
+`ApiProxyDefaults` carries `defaultModelSelection()` and `saveDefaultModelSelection()` closures, so `createApiProxy` has no dependency on the Settings seam. `ApiProxyService` wires them to `ctx.agentDefaultModel.currentSelection()` and `ctx.agentDefaultModel.saveSelection()`.
 
-The stored route is not validated against the registry. A default naming a route the Models page has since removed still reaches `session.models` as `current`, matching no advertised group — which is what makes the composer seat's existing fallback prompt for a selection instead of naming a model the deployment cannot reach.
+`selectionFor(agent)` resolves its tiers on every read: a process-local session selection, otherwise the session's latest logged `request/header`, otherwise the live Agent default. A session with a logged request remains bound to that durable selection. A blank session observes the current default even when it was created before the preference was saved; this matches the New Session surface, which may reuse a blank session.
+
+The stored selection does not require catalog membership. A provider route may serve a model omitted from its advisory catalog. `session.models` therefore reports the stored selection independently of advertised groups and separately reports whether an adapter serves its provider.
 
 ## Consequences
 
-`ApiProxyDefaults` changed shape, updating ~40 test construction sites. `host.describe` now reports the live default rather than a captured one, which is what it always meant. `settings.yaml` gains an `api-gateway:` section the moment a user switches models; the `api-gateway` namespace is deliberately NOT added to the gateway's exposed-namespace allowlist, so the Settings page neither reads nor writes it — the model picker is its editor.
+`host.describe` reports the live Agent default. A successful model switch stores an `agent-default-model:` section in `settings.yaml`. The gateway does not expose that namespace through its Settings-page allowlist; the model picker is its editor.
 
-## Follow-up: blocking a session that cannot send
+## A session that cannot send
 
-A default naming a route the Models page has since removed leaves the composer saying "Select model" while the input still accepts a message, which then fails inside the adapter mid-turn. Two changes close it.
+`session.prompt` refuses with `model-unavailable` before opening a turn when no adapter serves the session's selected provider. This method is the enforcement boundary; a disabled composer is only a client affordance.
 
-The Host refuses. `session.prompt` checks whether an adapter serves the session's route and answers `model-unavailable` before opening a turn. This is the enforcement boundary: a client that disables its composer is an affordance, and the method stays callable regardless.
+`session.models` reports `routable`. The ui-model plugin projects an unroutable selection through `ctx.conversation.blocks`, and the composer becomes inert while leaving the model seat available. An unknown client-side routability state, including an initial or failed catalog load, does not block input.
 
-The composer goes inert. `session.models` reports `routable`, and ui-model pushes a block through the new `ctx.conversation.blocks` registry; the bar renders the same disabled textarea it already renders without a workspace, with the blocker's own localized reason as the placeholder — except the model seat, which a block deliberately leaves live, because choosing a model is how the user clears it. The push direction is forced — ui-model already depends on ui-conversation, so ui-conversation cannot read it back.
-
-The gate is `routable`, NOT "the current target matches no advertised group". Catalog membership is advisory by design: a route serving a model it stopped advertising is absent from the groups yet perfectly usable, and blocking there would break a supported configuration (a narrowed `models` list over a live route). `routable` is also three-valued on the client — `null` before the first load or after a failed one never blocks, so a slow or unreachable Host cannot lock a working composer.
+Routability is distinct from catalog membership. A live provider route can serve an unadvertised model, so absence from catalog groups does not imply that the session is unusable.
 
 ## Alternatives considered
 
-- **Falling back to the composition entry when the stored route is unregistered.** Rejected: the composer would then name the shipped DeepSeek model instead of prompting, which is both a silent switch to a provider the user did not pick and the opposite of the requested behavior.
-- **Validating and clearing a stale default.** Rejected: catalog membership is advisory by design (`buildModelCatalog` documents it), so an adapter may serve a model its own catalog stopped advertising; self-healing would break that deliberate case.
-- **A `settings.update` merge patch.** Rejected: it cannot clear `reasoningEffort`, so a switch from a reasoning model to a plain one leaves an effort the next session fails on.
-- **Persisting only from blank sessions.** Rejected: the most informative switch is the one made mid-conversation after seeing a model underperform, and that one would never be saved.
-- **A separate "set as default" affordance.** Rejected for now: it adds a second gesture for what every comparable product infers from the switch itself. The cost is that a temporary switch in an old session also moves the default.
+| Alternative | Contract mismatch |
+|---|---|
+| Fall back to the composition entry when the stored provider is unavailable | The product silently switches away from the user's selection. |
+| Validate the stored selection against catalog membership | Catalogs are advisory and may omit requestable models. |
+| Save with a merge patch | An omitted `reasoningEffort` cannot clear the stored field. |
+| Save only selections made in blank sessions | An informed mid-conversation selection never becomes the deployment default. |
+| Add a separate “set as default” gesture | The session picker and future-session preference can diverge despite representing the same user choice. |
diff --git a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
index 0d2821cb63..52308518f0 100644
--- a/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
@@ -6,38 +6,42 @@ Status: implemented
 
 ## 问题
 
-新会话的起始路由被冻结在网关的组合条目里（web-app bundle patch 中的 `api-gateway` 行）。在一段对话里切换模型只影响这段对话：下一个会话又回到出厂默认，而要改这个默认值，唯一的办法是手工编辑一条 `cordis.yml` 行并重启。组合层与每会话选择之间没有用户设置这一层。
+会话模型选择器与部署默认值是同一项偏好的两个层次。如果选择器只影响其所在会话，下一个空白会话可能选择不同模型，用户却没有途径使默认值与选择器一致。如果默认值位于 Host 网关内部，直接创建 Agent 的前门只有依赖 Host 或复制状态才能共享它。
+
+推理强度使持久化形态成为契约的一部分：不含强度的模型选择必须清除已存强度，否则下一个 Agent 可能会采用所选模型不接受的强度。
 
 ## 决定
 
-`ApiProxyService` 把自己的 `{provider, model, reasoningEffort?}` 切片注册为 `api-gateway` 设置段：组合条目是 `base` 层，`settings.yaml` 把用户的选择叠加其上。`workspaceRoot` 留在段外——它是启动器事实，不是偏好。`reasoningEffort` 则是镜像的一例：它在段里、但**不在**插件配置里，因为 seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键。组合层设的推理等级因此会在此后每一次切到不支持推理的模型时继续存活——正是整段 `replace` 想要杜绝的那种滞留。何况推理等级本就是按模型的事实，它的部署级默认值属于适配器 profile，那里是按模型解析的。
+`AgentDefaultModelService` 提供 `ctx.agentDefaultModel`，并把 `{provider, model, reasoningEffort?}` 注册为 `agent-default-model` Settings 分节。其 `{provider, model}` 组合条目是 base 层，`settings.yaml` 提供用户层。该服务不偏向特定前门，因此直接创建与 ApiProxy 支撑的创建共享同一个默认值（[headless 直接 core 前门](../architecture/2026-08-09-headless-direct-core-front-door.md)）。`workspaceRoot` 仍是 ApiProxy 配置，因为它是 Host 启动器事实，而不是模型状态。
 
-`session.selectModel` 把被接受的切换记录为新的默认值。没有另一个单独的手势：在输入框切模型**就是**选定默认值的方式。写入用 `replace` 而非 `update`——切到一个不支持推理的模型必须清掉已存的等级，而合并补丁会把它滞留下来，让下一个会话在它上面失败。存储失败只记日志，不撤销这次切换（它对自己所在的会话已经生效）；没有设置提供方的部署保留组合条目，切换只停留在进程内。
+`reasoningEffort` 属于 Settings 分节，但不属于插件配置。Settings 层按字段合并，因此已配置的强度会在用户选择省略它时继续存在。`saveSelection()` 写入完整的用户分节；缺席值由此清除已存强度。部署级强度默认值属于适配器 profile，并由它按模型解析。
 
-`ApiProxyDefaults` 改为携带 `defaultTarget()` 与 `persistDefaultTarget()` 两个闭包，而不是扁平的 `provider`／`model` 字段，这样 `createApiProxy` 不需要知道设置这条缝的存在。
+`session.selectModel` 把被接受的 `ModelSelection` 应用于所在会话，并调用 `saveDefaultModelSelection()` 保存共享的 Agent 默认值。存储失败只记日志，不撤销会话选择。没有 Settings 提供方的部署保留组合条目，被接受的选择只停留在该会话中。
 
-`targetFor` 在**每一次**读取时解析各级，而不是只在创建时种一次 ref：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是活的默认值。两个方向都依赖这次重新读取。已经跑过一轮的会话此后永远从自己的日志推导，改默认值不会重定向它；而仍然空白的会话会用上它创建之后才保存的默认值——这一点很关键，因为新建会话是复用空白会话而不是再开一个，创建时种下的值恰好会在这个功能存在的意义所在的流程里显示已被取代的模型。
+`ApiProxyDefaults` 携带 `defaultModelSelection()` 与 `saveDefaultModelSelection()` 闭包，因此 `createApiProxy` 不依赖 Settings seam。`ApiProxyService` 将它们分别接到 `ctx.agentDefaultModel.currentSelection()` 与 `ctx.agentDefaultModel.saveSelection()`。
 
-存下来的路由不做注册表校验。默认值指向一条模型页已经删除的路由时，它照样作为 `current` 送到 `session.models`，匹配不到任何已公布的分组——而这正是让输入框选择器已有的回退提示重新选择、而不是显示一个部署根本够不着的模型的原因。
+`selectionFor(agent)` 每次读取时都解析各层：先取进程内的会话选择，其次取会话最新记录的 `request/header`，最后取当前 Agent 默认值。已有请求日志的会话持续绑定到该持久选择。空白会话即使创建于偏好保存之前，也会观察到当前默认值；这与 New Session surface 可能复用空白会话的行为一致。
+
+已存选择不要求属于目录。某条提供方路由可能服务其咨询性目录未列出的模型。因此，`session.models` 会在已公布分组之外单独报告已存选择，并另行报告适配器是否服务其提供方。
 
 ## 影响
 
-`ApiProxyDefaults` 形状变了，约 40 处测试构造点随之更新。`host.describe` 现在报告的是活的默认值而非捕获的快照，这本就是它一直想表达的含义。用户一旦切换模型，`settings.yaml` 就会多出一个 `api-gateway:` 段；`api-gateway` 这个 namespace 刻意**没有**加进网关的暴露名单，因此设置页既不读也不写它——模型选择器就是它的编辑器。
+`host.describe` 报告当前 Agent 默认值。模型切换成功后，`settings.yaml` 中会存有一个 `agent-default-model:` 分节。网关不通过 Settings 页 allowlist 暴露该 namespace；模型选择器是它的编辑器。
 
-## 后续：让发不出消息的会话禁止输入
+## 无法发送消息的会话
 
-默认值指向一条模型页已删除的路由时，编辑器显示「选择模型」，输入框却仍接受消息，然后这一轮在适配器内部失败。两处改动关掉这个口子。
+当没有适配器服务会话所选提供方时，`session.prompt` 会在开启轮次前以 `model-unavailable` 拒绝。这一方法是执行边界；禁用 composer 只是客户端提供的便利。
 
-宿主拒绝。`session.prompt` 检查是否有适配器服务该会话的路由，在开启轮次之前就以 `model-unavailable` 应答。这是执行边界：客户端禁用编辑器只是提示性设计，这个方法始终可被调用。
+`session.models` 报告 `routable`。ui-model 插件通过 `ctx.conversation.blocks` 投影不可路由的选择，composer 随之变为不可操作，同时保留模型 seat 可用。客户端不知道是否可路由时不会阻断输入，包括目录首次加载或加载失败的情况。
 
-编辑器变惰性。`session.models` 报告 `routable`，ui-model 经新的 `ctx.conversation.blocks` 注册表推送一个 block；输入栏渲染的仍是它在没有 Workspace 时就会渲染的那个禁用 textarea，只是把抬起方自己的本地化理由作为 placeholder——唯独模型 seat 被 block 刻意保留可用，因为用户正是靠选模型来解除它。推送方向是被迫的——ui-model 本就依赖 ui-conversation，因此 ui-conversation 读不回去。
-
-闸门是 `routable`，**不是**「当前目标匹配不到任何已公布分组」。目录成员关系按设计是咨询性的：一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用，在那里阻断会破坏一种受支持的配置（对一条活着的路由收窄 `models` 列表）。`routable` 在客户端还是三值的——首次加载之前或加载失败之后的 `null` 绝不阻断，因此慢的或够不着的宿主锁不死一个本来能用的编辑器。
+可路由性与目录成员关系不同。仍在服务的提供方路由可以处理未公布的模型，因此不在目录分组中并不代表会话不可用。
 
 ## 考虑过的替代方案
 
-- **存下来的路由未注册时回落到组合条目。** 否决：那样输入框会显示出厂的 DeepSeek 模型而不是提示选择，既是静默切到用户没选的提供方，也与要求的行为正好相反。
-- **校验并清空失效的默认值。** 否决：目录成员关系按设计是咨询性的（`buildModelCatalog` 有注释说明），适配器可以服务一个自己目录已不再公布的模型；自动修复会破坏这个刻意保留的情形。
-- **用 `settings.update` 合并补丁。** 否决：它清不掉 `reasoningEffort`，于是从推理模型切到普通模型会留下一个等级，让下一个会话在它上面失败。
-- **只在空白会话里持久化。** 否决：最有信息量的切换恰恰是对话到一半发现模型不行时做的那一次，而它永远存不下来。
-- **单独做一个「设为默认」的入口。** 目前否决：同类产品都从切换本身推断的事情，它却要多一个手势。代价是在老会话里的临时切换也会移动默认值。
+| 替代方案 | 契约不匹配之处 |
+|---|---|
+| 已存提供方不可用时回落到组合条目 | 产品会静默切离用户选择。 |
+| 根据目录成员关系校验已存选择 | 目录仅供参考，可能省略仍可请求的模型。 |
+| 使用合并 patch 保存 | 省略的 `reasoningEffort` 无法清除已存字段。 |
+| 只保存空白会话中的选择 | 对话期间知情作出的选择不会成为部署默认值。 |
+| 增加单独的「设为默认」手势 | 会话选择器与未来会话偏好虽然代表同一用户选择，却仍可能分歧。 |
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
index 145c1cf619..f4e308c8f2 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-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 .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
-2026-08-08-dsh-run-headless-command.md: d1cc0573d1d94bb7b30e98aa685d2b7d89878a99
-2026-08-08-dsh-run-headless-command.zh.md: afb18fea6ac46064b6720d3bb68d7bc53a81d3f2
+2026-08-08-dsh-run-headless-command.md: 566eeb5b2a09a0d07d72a68e4a5f449d2822e708
+2026-08-08-dsh-run-headless-command.zh.md: 177410e783a37026940829da5f81343ddc61cb29
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
index d1cc0573d1..566eeb5b2a 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
@@ -6,36 +6,36 @@ English | [中文](2026-08-08-dsh-run-headless-command.zh.md)
 
 ## Problem
 
-The product launcher attached optional task text to its generic profile boot: `dsh --profile headless "task"`. That made one argv shape mean either a long-lived profile or a one-shot run according to a row discovered only after composition. The parser's `ProfileInvocation` carried optional task state, help presented a profile implementation detail as the user command, and a custom profile could accept a task only through the same overloaded root.
+Generic profile boot and one-shot task execution have different lifecycle contracts. A root grammar that accepts optional task text makes one argv shape mean either a long-lived process or a terminating task according to a plugin row discovered only after composition. It also exposes a profile implementation detail as the primary user command and gives custom profiles no explicit one-shot entry.
 
-The former `dsh -p` spelling was already absent from the parser, so restoring it or detecting it specially would add compatibility machinery to a pre-release interface. A separate application-file proposal also used the `run` verb, leaving two incompatible owners for one top-level command.
+The `run` verb must have one top-level meaning. Sharing it with application-file execution or inferring its meaning from positional shape creates the same ambiguity.
 
 ## Decision
 
-One-shot execution owns an explicit grammar:
+One-shot execution owns this grammar:
 
 ```text
 dsh run [--profile <name>] [--patch <path>...] <task...>
 ```
 
-`--profile` defaults to `headless` and remains available for custom one-shot compositions. `--patch` is repeatable and occupies the existing overlay layer. Commander joins the variadic task arguments with spaces and rejects a missing or blank task before boot.
+`--profile` defaults to `headless` and supports custom one-shot compositions. `--patch` is repeatable and occupies the normal overlay layer. Commander joins the variadic task arguments with spaces and rejects a missing or blank task before boot.
 
-The [profile plugin bundle decision](../architecture/2026-08-05-profile-plugin-bundles.md) owns the composition selected by this grammar.
+`RunInvocation` is a distinct `DshInvocation` member. The generic profile invocation carries no task state and accepts no positional arguments. Both dispatch paths use `runProfile`: profile boot omits `task`, while `run` supplies it. A one-shot profile without `headless-runner` fails through the composed-row check, and profile boot containing that row without a task points to `dsh run --profile <name> "<task>"`.
 
-`RunInvocation` is a separate `DshInvocation` member. The generic profile invocation no longer carries task text, and its root command accepts no positional arguments. Both dispatch paths call the existing deep `runProfile` module: `profile` omits `task`, while `run` supplies it. There is no shallow `run.ts` forwarding module and no alias, warning, or custom detector for former spellings; they fail through the ordinary Commander grammar. A one-shot profile without `headless-runner` still fails through the existing composed-row check, while booting a profile that contains that row without a task points to `dsh run --profile <name> "<task>"`.
+The [profile plugin bundle decision](../architecture/2026-08-05-profile-plugin-bundles.md) owns composition. [Headless is a direct core front door](../architecture/2026-08-09-headless-direct-core-front-door.md) owns the execution contract: one fresh persisted Session, final assistant text on stdout, completed/non-completed exit mapping, empty stderr on success, no listening port, and bounded signal shutdown after Agent quiescence and Session flush.
 
-The `run` verb belongs to one-shot task execution. Launching an application file must choose another command name; two top-level meanings selected by positional shape would recreate the ambiguity this command removes.
-
-The runner's user-visible contract stays the same: a fresh persisted session, browser observation URL on stderr, final assistant text on stdout, completed/non-completed exit mapping, and bounded signal shutdown. The product-level keyless acceptance exposed that the in-process mux consumer could lag the same-process `agent/status: idle` notification and derive output before reading the final frames. The idle notification now captures the authoritative final session sequence, and the runner waits until the ordered mux reaches that boundary (or the stream ends) before deriving text and exit reason. This enforces the existing idle-to-idle contract without adding a wire field or a timing delay.
+The `run` verb belongs only to one-shot task execution. Application-file launch requires a distinct command name.
 
 ## Alternatives considered
 
-- **Keep task text on `dsh --profile`.** Rejected because profile boot and one-shot execution remain one grammar whose meaning depends on a late composition check.
-- **Preserve `dsh -p` or the positional profile form as aliases.** Rejected under the pre-release stance: compatibility branches would outlive the interface they were meant to retire.
-- **Make `--profile headless` mandatory under `run`.** Rejected because the shipped one-shot surface should have the shortest canonical spelling, while optional `--profile` preserves plugin-defined one-shot compositions.
-- **Give `dsh run` to application-file launch and choose another headless verb.** Rejected because `run` describes executing a task through the harness; application-file ownership would make the product's primary one-shot command less direct and collide with custom one-shot profiles.
-- **Add `apps/cli/src/run.ts`.** Rejected because it would only forward to `runProfile`, splitting command ownership without hiding any complexity.
+| Alternative | Contract mismatch |
+|---|---|
+| Put task text on root profile boot | Lifecycle meaning depends on a plugin row discovered after parsing. |
+| Accept root aliases such as `dsh -p` | The pre-release grammar acquires compatibility branches with no current command ownership. |
+| Require `--profile headless` | The shipped one-shot surface loses its shortest canonical spelling. |
+| Use `dsh run` for application files | One top-level verb has two meanings and the primary task command becomes indirect. |
+| Add a shallow `apps/cli/src/run.ts` forwarder | Command ownership splits without hiding any complexity. |
 
 ## Consequences
 
-This is an intentional breaking CLI change. Documentation, help, parser tests, built-bin acceptance, PTY shutdown coverage, and the assembled keyless snapshot use `dsh run`. Existing custom one-shot profiles keep working through `--profile`; long-lived profiles and config dumps retain their existing root grammar. The competing application-file command must be renamed and rebased separately rather than sharing or overloading `run`.
+Help, documentation, parser tests, built-bin acceptance, PTY shutdown coverage, and the assembled keyless snapshot use `dsh run`. Custom one-shot profiles use `--profile`; long-lived profile boot and config dumps keep the root profile grammar. Application-file execution is a separate command concern.
diff --git a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
index afb18fea6a..177410e783 100644
--- a/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md
@@ -6,36 +6,36 @@ Status: implemented
 
 ## 问题
 
-产品启动器过去把可选任务文本挂在通用 profile 启动命令上：`dsh --profile headless "task"`。于是，同一种 argv 形态会表示常驻 profile 或一次性运行，具体含义取决于组合完成后才发现的配置行。解析器的 `ProfileInvocation` 携带可选任务状态，帮助信息把 profile 的实现细节呈现为用户命令，自定义 profile 也只能通过同一个过载的根命令接收任务。
+通用 profile 启动与一次性任务执行具有不同的生命周期约定。若根语法接受可选任务文本，同一种 argv 形态会表示常驻进程或终止式任务，具体含义取决于组合完成后才发现的插件配置行。它还会把 profile 实现细节暴露成主要用户命令，并使自定义 profile 缺少明确的一次性入口。
 
-解析器中已经没有原来的 `dsh -p` 写法，因此恢复该写法或加入特殊检测，会给预发布接口增加兼容机制。另一个应用文件提案也使用 `run` 动词，使同一个顶层命令同时归属两个互不兼容的功能。
+`run` 动词必须只有一种顶层含义。与应用文件执行共用该动词，或根据位置参数形态推断含义，都会产生相同的歧义。
 
 ## 决策
 
-一次性执行采用明确语法：
+一次性执行采用以下语法：
 
 ```text
 dsh run [--profile <name>] [--patch <path>...] <task...>
 ```
 
-`--profile` 默认为 `headless`，同时保留对自定义一次性组合的支持。`--patch` 可重复使用，并沿用既有 overlay 层的位置。Commander 用空格拼接可变数量的任务参数，并在启动前拒绝缺失或空白任务。
+`--profile` 默认为 `headless`，并支持自定义一次性组合。`--patch` 可重复使用，并占据正常的 overlay 层。Commander 用空格拼接可变数量的任务参数，并在启动前拒绝缺失或空白任务。
 
-[profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)负责该语法所选择的组合。
+`RunInvocation` 是单独的 `DshInvocation` 成员。通用 profile 调用不携带任务状态，也不接受位置参数。两条分派路径都使用 `runProfile`：profile 启动省略 `task`，而 `run` 提供该字段。缺少 `headless-runner` 的一次性 profile 会触发组合行检查；如果启动的 profile 包含该行却未提供任务，错误会指向 `dsh run --profile <name> "<task>"`。
 
-`RunInvocation` 是单独的 `DshInvocation` 成员。通用 profile 调用不再携带任务文本，其根命令也不接受位置参数。两条分派路径都调用已有的深层 `runProfile` 模块：`profile` 省略 `task`，`run` 则提供该字段。实现中没有只负责转发的浅层 `run.ts` 模块，也没有面向旧写法的别名、警告或自定义检测器；旧写法会按普通 Commander 语法失败。缺少 `headless-runner` 的一次性 profile 仍会触发既有的组合行检查；如果启动的 profile 包含该行却未提供任务，错误会指向 `dsh run --profile <name> "<task>"`。
+[profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)负责组合。[Headless 是直接 core 前门](../architecture/2026-08-09-headless-direct-core-front-door.md)负责执行约定：一个新的持久化会话、stdout 上的最终 assistant 文本、completed／非 completed 的退出状态映射、成功时为空的 stderr、无监听端口，以及 Agent 完全停稳且会话 flush 后的有界信号关闭。
 
-`run` 动词只负责一次性任务执行。应用文件启动必须选择其他命令名；如果让两个顶层含义由位置参数形态决定，就会重新引入本命令消除的歧义。
-
-运行器面向用户的约定保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 约定。
+`run` 动词只负责一次性任务执行。应用文件启动需要不同的命令名。
 
 ## 考虑过的替代方案
 
-- **把任务文本保留在 `dsh --profile` 上。** 不予采纳：profile 启动和一次性执行仍共用同一套语法，其含义取决于较晚发生的组合检查。
-- **保留 `dsh -p` 或位置参数 profile 形式作为别名。** 不予采纳：根据预发布立场，这些兼容分支会比本应退役的接口存续更久。
-- **要求在 `run` 下必须指定 `--profile headless`。** 不予采纳：已交付的一次性接口应采用最短的规范写法，同时用可选的 `--profile` 保留插件定义的一次性组合。
-- **把 `dsh run` 交给应用文件启动，并为 headless 选择另一个动词。** 不予采纳：`run` 描述的是通过 harness 执行任务；若归应用文件所有，产品的主要一次性命令会更不直接，并与自定义一次性 profile 冲突。
-- **新增 `apps/cli/src/run.ts`。** 不予采纳：它只会转发到 `runProfile`，拆分命令归属，却没有隐藏任何复杂度。
+| 替代方案 | 约定不匹配之处 |
+|---|---|
+| 把任务文本放在根 profile 启动命令上 | 生命周期含义依赖解析后才发现的插件配置行。 |
+| 接受 `dsh -p` 等根命令别名 | 预发布语法获得不属于任何当前命令的兼容分支。 |
+| 要求指定 `--profile headless` | 随附的一次性 surface 失去最短的规范写法。 |
+| 将 `dsh run` 用于应用文件 | 一个顶层动词具有两种含义，主要任务命令也变得间接。 |
+| 添加仅转发的 `apps/cli/src/run.ts` | 命令归属被拆分，却没有隐藏任何复杂度。 |
 
 ## 后果
 
-这是一次有意为之的 CLI（命令行界面）破坏性变更。文档、帮助信息、解析器测试、构建后二进制验收、PTY 关闭覆盖和组装应用的无密钥快照都使用 `dsh run`。现有自定义一次性 profile 可继续通过 `--profile` 工作；常驻 profile 和配置 dump 保留既有的根命令语法。与之竞争的应用文件命令必须单独改名并 rebase，不得共享或重载 `run`。
+帮助信息、文档、解析器测试、构建后二进制验收、PTY 关闭覆盖和组装应用的无密钥快照均使用 `dsh run`。自定义一次性 profile 使用 `--profile`；常驻 profile 启动与配置 dump 使用根 profile 语法。应用文件执行是独立的命令关注点。
diff --git a/apps/cli/README.i18n.yaml b/apps/cli/README.i18n.yaml
index 162ea534b7..101332555d 100644
--- a/apps/cli/README.i18n.yaml
+++ b/apps/cli/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 apps/cli/README.md
-README.md: 12108fcbff4e649d0bcb3e01e688fa334ab91b14
-README.zh.md: 37967973ed40143db0bc747875dbb6dad11d73b4
+README.md: dd29f7fc03a783079ea3194de99589c1f545be5b
+README.zh.md: 60e7aa1ec1ea2fad7e3f3d97a0f6bf42355adffc
diff --git a/apps/cli/README.md b/apps/cli/README.md
index 12108fcbff..dd29f7fc03 100644
--- a/apps/cli/README.md
+++ b/apps/cli/README.md
@@ -9,7 +9,7 @@ The `dsh` command is the product launcher for profiles: ordered stacks of plugin
 | Command | Purpose |
 |---|---|
 | `dsh --profile <name>` | Boot the named profile under `$DSH_HOME/profiles/<name>`. |
-| `dsh run [--profile <name>] [--patch <path>...] "task"` | Run one fresh persisted session, print the final answer, and exit; the profile defaults to `headless`. |
+| `dsh run [--profile <name>] [--patch <path>...] "task"` | Run one fresh persisted session directly over core, print the final answer, and exit; the profile defaults to `headless` and mounts no Web server. |
 | `dsh web` | Alias of `--profile web` with the Web flag family (`--host`, `--port`, `--dev`, ...). |
 | `dsh plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
 
diff --git a/apps/cli/README.zh.md b/apps/cli/README.zh.md
index 37967973ed..60e7aa1ec1 100644
--- a/apps/cli/README.zh.md
+++ b/apps/cli/README.zh.md
@@ -9,7 +9,7 @@
 | 命令 | 用途 |
 |---|---|
 | `dsh --profile <name>` | 启动位于 `$DSH_HOME/profiles/<name>` 的指定 profile。 |
-| `dsh run [--profile <name>] [--patch <path>...] "task"` | 运行一个新的持久化会话，打印最终答案并退出；profile 默认为 `headless`。 |
+| `dsh run [--profile <name>] [--patch <path>...] "task"` | 直接在 core 上运行一个新的持久化会话，打印最终答案并退出；profile 默认为 `headless`，且不挂载 Web server。 |
 | `dsh web` | `--profile web` 的别名，附带 Web flag 系列（`--host`、`--port`、`--dev` 等）。 |
 | `dsh plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
 
diff --git a/apps/cli/composition.md b/apps/cli/composition.md
index 8bebf18040..cfcd903e32 100644
--- a/apps/cli/composition.md
+++ b/apps/cli/composition.md
@@ -32,6 +32,8 @@ flowchart LR
   cfg --> plugin_dsh_base_user_interaction
   plugin_dsh_base_agent["agent<br/>@deepseek-ai/dsh-agent"]
   cfg --> plugin_dsh_base_agent
+  plugin_dsh_base_agent_default_model["agent-default-model<br/>@deepseek-ai/dsh-agent-default-model"]
+  cfg --> plugin_dsh_base_agent_default_model
   plugin_dsh_base_tasks["tasks<br/>@deepseek-ai/dsh-tasks-local"]
   cfg --> plugin_dsh_base_tasks
   plugin_dsh_base_llm_retry["llm-retry<br/>@deepseek-ai/dsh-llm-retry"]
@@ -174,6 +176,7 @@ flowchart LR
 | `session-title-llm` | `@deepseek-ai/dsh-session-title-first-message-llm` |
 | `user-interaction` | `@deepseek-ai/dsh-user-interaction` |
 | `agent` | `@deepseek-ai/dsh-agent` |
+| `agent-default-model` | `@deepseek-ai/dsh-agent-default-model` |
 | `tasks` | `@deepseek-ai/dsh-tasks-local` |
 | `llm-retry` | `@deepseek-ai/dsh-llm-retry` |
 | `settings` | `@deepseek-ai/dsh-settings-local` |
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index a478ae60d2..9bfe494ba6 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
-README.md: e616b420d60e0fa372bf38950207245cb60ced98
-README.zh.md: 81320ecbd19012123ab7e69967cbadb088356cfe
+README.md: 4f8aa86c0f6cdb91eb843048cd5ed4943a896c73
+README.zh.md: 09bc19220a869bedfcaa98baccbf6d4f6a3f3223
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index e616b420d6..4f8aa86c0f 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -10,7 +10,7 @@ This reference defines the profile, one-shot run, web-alias, plugin-management,
 
 Bundle names resolve from the dsh installation first, then from the profile directory. In-box bundles (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`, `@deepseek-ai/dsh-headless`) therefore always come from the same installation as the running `dsh`; out-of-tree bundles come from the profile's pnpm-managed `node_modules`. A bare plugin `name` in any patch row resolves through the profile directory's Node parent-walk, which reaches the maintained installation fallback `$DSH_HOME/profiles/node_modules` (one symlink per package the installation's app and bundles depend on, healed on every launch).
 
-The `web` and `headless` profiles auto-initialize from shipped templates on first use (`web`: base + web-app; `headless`: base + web-app + headless). Any other missing profile fails loud with a hint to run `dsh plugin --profile <name> add <package>`.
+The `web` and `headless` profiles auto-initialize from shipped templates on first use (`web`: base + web-app; `headless`: base + headless). On load, the exact installation-owned headless tuple (base + web-app + headless) normalizes to the shipped template; extra, missing, or reordered bundle lists are user-owned and remain untouched. Any other missing profile fails loud with a hint to run `dsh plugin --profile <name> add <package>`.
 
 Profile boot accepts no positional task. A profile that mounts the one-shot runner row (`headless-runner`) therefore fails loud with the canonical `dsh run --profile <name> "<task>"` command instead of reaching the row's raw required-field error.
 
@@ -27,7 +27,7 @@ dsh --profile web --patch ./extra.yml --dump-config
 
 `dsh run [--profile <name>] [--patch <path>...] <task...>` joins the task arguments with spaces, rejects a missing or blank task, and defaults `--profile` to `headless`. Repeatable `--patch` overlays occupy the same layer position as profile-boot overlays. A custom selected profile must mount `headless-runner`; otherwise launch fails before boot with a diagnostic naming that missing row.
 
-The launcher patches the task text into the runner row, which drives one fresh persisted session through the in-process API carrier, prints the final assistant text on stdout, and exits 0 on a completed turn, else 1. At the idle boundary, the runner waits until its mux consumer has observed the session's final event sequence before deriving that output and exit reason. The session's Web host runs on an OS-assigned port and is announced on stderr, so the run is observable in a browser.
+The launcher patches the task text into the runner row. After Loader settlement, the runner reads the shared `ctx.agentDefaultModel` default, creates one fresh persisted Agent through `ctx.agents`, submits the task, waits for quiescence, and flushes the Session before deriving the last non-empty assistant text and final `turn/end` reason from its durable interval. It prints the text on stdout and exits 0 for `completed`, else 1. The shipped headless profile mounts no ApiProxy, Host, HTTP server, Web runtime, or browser client; a successful run writes nothing to stderr and opens no listening port.
 
 ## Plugin management
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index 81320ecbd1..09bc19220a 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -10,7 +10,7 @@
 
 组合包名称先从 dsh 安装解析，再从 profile 目录解析。因此内置组合包（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`）总是来自与正在运行的 `dsh` 相同的安装；树外组合包来自 profile 由 pnpm 管理的 `node_modules`。任何 patch 行中的裸插件 `name` 通过 profile 目录的 Node 父目录逐级查找解析，该查找可达到持续维护的安装后备目录 `$DSH_HOME/profiles/node_modules`（安装的应用和组合包所依赖的每个包对应一个符号链接，每次启动时修复）。
 
-`web` 和 `headless` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app；`headless`：base + web-app + headless）。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
+`web` 和 `headless` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app；`headless`：base + headless）。加载时，与安装所管理的 headless 元组（base + web-app + headless）完全一致的列表会规范化为随附模板；包含额外项、缺少项或调整过顺序的组合包列表由用户拥有，保持不变。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
 
 Profile 启动不接受位置参数任务。因此，挂载了一次性运行器行（`headless-runner`）的 profile 会显式报错，并提示规范命令 `dsh run --profile <name> "<task>"`，而不会触发该行原始的必填字段错误。
 
@@ -27,7 +27,7 @@ dsh --profile web --patch ./extra.yml --dump-config
 
 `dsh run [--profile <name>] [--patch <path>...] <task...>` 会用空格拼接任务参数，拒绝缺失或空白任务，并让 `--profile` 默认为 `headless`。可重复使用的 `--patch` overlay 与 profile 启动的 overlay 位于同一层。所选的自定义 profile 必须挂载 `headless-runner`；否则启动器会在启动前失败，并在诊断中指明缺少该行。
 
-启动器把任务文本 patch 进运行器行，运行器再通过进程内 API 载体驱动一个全新的持久化会话，在 stdout 打印最终 assistant 文本，并在轮次完成时以 0 退出，否则以 1 退出。到达 idle 边界时，运行器会等到 mux 消费方观察到会话的最终事件序号，再生成输出与退出原因。会话的 Web 宿主运行在 OS 分配的端口上并公布到 stderr，因此该次运行可在浏览器中观察。
+启动器把任务文本 patch 进运行器行。Loader 结算后，运行器读取共享的 `ctx.agentDefaultModel` 默认值，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），提交任务、等待完全停稳并对 Session 执行 flush，再从其持久化事件区间中推导最后一个非空 assistant 文本与最终 `turn/end` 原因。它在 stdout 打印文本，并在原因为 `completed` 时以 0 退出，否则以 1 退出。随附 headless profile 不挂载 ApiProxy、Host、HTTP 服务器、Web 运行时或浏览器客户端；成功运行不会向 stderr 写入任何内容，也不会打开监听端口。
 
 ## 插件管理
 
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index a42780581f..073f541fe0 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -222,7 +222,7 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       })
       expect(result.code, result.stderr).toBe(0)
       expect(result.stdout).toBe('published dsh run reached the mock')
-      expect(result.stderr).toMatch(/^dsh: observing at http:\/\/127\.0\.0\.1:\d+$/u)
+      expect(result.stderr).toBe('')
       expect(server.requests.length).toBeGreaterThan(0)
       expect(server.requests.every(request => request.path === '/chat/completions')).toBe(true)
       expect(JSON.stringify(server.requests.map(request => request.body))).toContain('answer from the published entry')
@@ -470,6 +470,20 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       expect(stdout).toContain("name: '@deepseek-ai/dsh-host-webserver'")
     }, 30_000)
 
+    it('prints a headless profile with no Host, HTTP, or browser rows', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(
+        ['--profile', 'headless', '--dump-default-config'],
+        { DSH_HOME: home },
+      )
+      expect(code).toBe(0)
+      expect(stderr).toBe('')
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-agent-default-model'")
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-headless'")
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-host-")
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-web-app'")
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-client-")
+    }, 30_000)
+
     it('composes the profile user layer and a --patch overlay in order', async () => {
       // Auto-init the web profile first, then write its user layer.
       const init = await runBuiltBin(['--profile', 'web', '--dump-default-config'], { DSH_HOME: home })
diff --git a/apps/cli/tests/fixtures/never-dispose.mjs b/apps/cli/tests/fixtures/never-dispose.mjs
index 0c29cc2967..5dc8510550 100644
--- a/apps/cli/tests/fixtures/never-dispose.mjs
+++ b/apps/cli/tests/fixtures/never-dispose.mjs
@@ -8,6 +8,7 @@ import { existsSync } from 'node:fs'
  */
 export function apply(ctx) {
   const keepAlive = setInterval(() => {}, 60_000)
+  process.stderr.write('dsh-test: never-dispose ready\n')
   ctx.effect(() => async () => {
     clearInterval(keepAlive)
     const armFile = process.env.DSH_TEST_SHUTDOWN_ARM_FILE
diff --git a/apps/cli/tests/headless-shutdown.e2e.ts b/apps/cli/tests/headless-shutdown.e2e.ts
index 237554864c..b0bcbb7cae 100644
--- a/apps/cli/tests/headless-shutdown.e2e.ts
+++ b/apps/cli/tests/headless-shutdown.e2e.ts
@@ -22,7 +22,7 @@ if pid == 0:
     os.chdir(cwd)
     os.execvpe(node, [node, *json.loads(launch_args_json)], env)
 
-markers = [b"dsh: observing at ", b"dsh-test: never-dispose started"]
+markers = [b"dsh-test: never-dispose ready", b"dsh-test: never-dispose started"]
 output = bytearray()
 marker_index = 0
 deadline = time.monotonic() + float(timeout_seconds)
@@ -73,7 +73,7 @@ async function runHeadlessPtySmoke(): Promise<string> {
       name: 'dsh-profile-headless',
       private: true,
       dependencies: {},
-      dsh: { profile: { bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless'] } },
+      dsh: { profile: { bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'] } },
     }, undefined, 2))
     await writeFile(join(profileDir, 'cordis.patch.yml'), [
       '- insert:',
@@ -124,7 +124,8 @@ async function runHeadlessPtySmoke(): Promise<string> {
 describe.skipIf(process.platform === 'win32')('headless process shutdown (real Loader tree in a PTY)', () => {
   it('lets a second Ctrl+C force exit while the first signal is draining', async () => {
     const output = await runHeadlessPtySmoke()
-    expect(output).toContain('dsh: observing at ')
+    expect(output).not.toContain('dsh: observing at ')
+    expect(output).toContain('dsh-test: never-dispose ready')
     expect(output).toContain('dsh-test: never-dispose started')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })
diff --git a/apps/web/tests/declared-reasoning.e2e.ts b/apps/web/tests/declared-reasoning.e2e.ts
index 664f20dfe6..f908511214 100644
--- a/apps/web/tests/declared-reasoning.e2e.ts
+++ b/apps/web/tests/declared-reasoning.e2e.ts
@@ -1,6 +1,6 @@
 // Web e2e scenario: a hand-declared model's `reasoningEfforts` reaches the
 // composer's effort pane — the levels a settings profile declares are exactly
-// what the picker offers, and picking one records it with the default route.
+// what the picker offers, and picking one records it with the Agent default.
 // Zero model calls: declaring, describing, and switching are settings/llm
 // traffic only, so there is no fixture and a stray stream would fail loud.
 import { readFile } from 'node:fs/promises'
@@ -77,8 +77,8 @@ describe.skipIf(MODE === 'record')('web e2e: declared reasoning efforts reach th
     const snapshot = await captureStableAria(page, '[role="menu"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
 
-    // Picking a level is the same gesture that saves the default target, so
-    // the effort lands in the gateway's settings section beside the route.
+    // Picking a level is the same gesture that saves the default selection, so
+    // the effort lands in the Agent default Settings section beside provider/model.
     await page.getByRole('menuitemradio', { name: 'High' }).click()
     await expect.poll(
       async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'),
diff --git a/apps/web/tests/declared-reasoning.overlay.yml b/apps/web/tests/declared-reasoning.overlay.yml
index d90452178c..ff89f036b3 100644
--- a/apps/web/tests/declared-reasoning.overlay.yml
+++ b/apps/web/tests/declared-reasoning.overlay.yml
@@ -2,7 +2,7 @@
 # deepseek-official default would be a route nothing serves. This scenario
 # starts the default on its own declared reasoning model so the effort pane
 # describes that model from the first open.
-- id: api-gateway
+- id: agent-default-model
   config:
     provider: acme-gateway
     model: acme-think
diff --git a/apps/web/tests/default-model.e2e.ts b/apps/web/tests/default-model.e2e.ts
index 24ee5a1616..0c43bf3998 100644
--- a/apps/web/tests/default-model.e2e.ts
+++ b/apps/web/tests/default-model.e2e.ts
@@ -1,5 +1,5 @@
 // Web e2e scenario: switching models in the composer is how this deployment's
-// default is chosen. The gesture writes the `api-gateway` settings section, a
+// default is chosen. The gesture writes the shared `agent-default-model` settings section, a
 // session created afterwards starts from it, and a session that already logged
 // a route keeps deriving from its own log — the tier order the gateway
 // resolves on every read.
@@ -21,7 +21,7 @@ import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { launchWebScaffold, watchConsole, type WebScaffold } from './scaffold.ts'
 import { ZH_BROWSER_LOCALE, connectFreshWorkspaceZh, saveFailureShot } from './support.ts'
 
-/** Points the shipped `api-gateway` default at this scenario's own route. */
+/** Points the shipped shared Agent default at this scenario's own route. */
 const OVERLAY = fileURLToPath(new URL('./default-model.overlay.yml', import.meta.url))
 
 /** The route this scenario starts on, patched over the shipped default. */
@@ -110,12 +110,12 @@ describe('web e2e: the composer model switch is the default for later sessions',
     await page.getByRole('menuitem', { name: /模型/ }).click()
     await page.getByRole('menuitemradio', { name: 'Acme Large' }).click()
 
-    // The switch is what sets the default: the gateway's own settings section
+    // The switch is what sets the default: the shared Agent-route settings section
     // now names it, beside the provider profiles the Models page writes.
     await expect.poll(
       async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'),
       { timeout: 10_000 },
-    ).toContain('api-gateway:')
+    ).toContain('agent-default-model:')
     const document = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
     expect(document).toContain(`provider: ${ROUTE}`)
     expect(document).toContain(`model: ${MODEL}`)
diff --git a/apps/web/tests/default-model.overlay.yml b/apps/web/tests/default-model.overlay.yml
index 540e4891d6..5ec0e77405 100644
--- a/apps/web/tests/default-model.overlay.yml
+++ b/apps/web/tests/default-model.overlay.yml
@@ -2,7 +2,7 @@
 # deepseek-official default would be a route nothing serves — which the
 # composer now correctly refuses to type into. This scenario declares its own
 # pi-ai routes and starts the default on one of them.
-- id: api-gateway
+- id: agent-default-model
   config:
     provider: origin-gateway
     model: origin-large
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 1b81c2c5da..3b279ef25a 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 06c15f204b3a695de49df29938781f8f033c4a7e
-architecture.zh.md: 29fe94f5a94c317854366e811dc6ceb74d2fddfe
+architecture.md: ed33fb215c3b4fd830bef219da74f4ee98dec81d
+architecture.zh.md: 19d2500142449c63d725f89a651b22205af6b301
diff --git a/docs/architecture.md b/docs/architecture.md
index 06c15f204b..ed33fb215c 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -17,6 +17,7 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 | `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and variables |
 | `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline](tool-execution-pipeline.md) |
 | `ctx.agents` | `dsh-agent` | live agents, delegated creation, `agent/*` events, process-local initiator scope |
+| `ctx.agentDefaultModel` | [`dsh-agent-default-model`](../packages/core/agent-default-model/README.md) | Settings-backed model selection shared by Agent front doors |
 | `ctx.agentLoop` | `dsh-agent-loop` | concrete `Agent` driver |
 
 ### Capability Services
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 29fe94f5a9..19d2500142 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -17,6 +17,7 @@
 | `ctx.systemPrompt` | `dsh-system-prompt` | 有序的提示词片段、工具 schema 和变量 |
 | `ctx.tools` | `dsh-tools` | 工具注册表和[执行流水线](tool-execution-pipeline.md) |
 | `ctx.agents` | `dsh-agent` | 活跃 agent（智能体）、委托创建、`agent/*` 事件、进程内发起方作用域 |
+| `ctx.agentDefaultModel` | [`dsh-agent-default-model`](../packages/core/agent-default-model/README.md) | 由 Settings 支撑、供 Agent 入口共享的模型选择 |
 | `ctx.agentLoop` | `dsh-agent-loop` | 实体 `Agent` 驱动器 |
 
 ### 功能服务
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 4b46a6566b..d61353210e 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -94,6 +94,9 @@ flowchart LR
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
+  pkg_agent_default_model["agent-default-model"]
+  svc_agentDefaultModel["ctx.agentDefaultModel<br/>Default Agent model selection"]
+  pkg_headless["headless"]
   svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_goal["goal"]
@@ -176,6 +179,7 @@ flowchart LR
   pkg_tool_workflow["tool-workflow"]
   pkg_acp --> svc_approval
   pkg_agent --> svc_agents
+  pkg_agent_default_model --> svc_agentDefaultModel
   pkg_agent_loop --> svc_agentLoop
   pkg_api_gateway --> svc_typertGateway
   pkg_approval --> svc_approval
@@ -265,6 +269,8 @@ flowchart LR
   pkg_workflow --> svc_workflows
   pkg_workflow_workerthread --> svc_workflows
   pkg_workspace --> svc_workspace
+  svc_agentDefaultModel --> pkg_headless
+  svc_agentDefaultModel --> pkg_host_apiproxy
   svc_agentLoop --> pkg_agent_spine_demo
   svc_agents --> pkg_acp
   svc_agents --> pkg_agent_loop
@@ -397,6 +403,7 @@ flowchart LR
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.agentDefaultModel` | `core` | [`agent-default-model`](../packages/core/agent-default-model) | - | [`headless`](../packages/bundle/headless), [`host-apiproxy`](../packages/host/apiproxy) | - | Layers the default ModelSelection through settings so direct and Host-backed Agent front doors share one state owner. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
 | `ctx.e2b` | `core` | [`e2b`](../packages/e2b/e2b) | - | [`fs-e2b`](../packages/e2b/fs-e2b), [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | - | Owns one shared E2B SDK handle, remote working directory, and final sandbox disposition so both fundamental E2B providers inhabit the same Linux runtime. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 0a5d0f7519..6219a0080f 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -14,7 +14,7 @@ A `Requires:` line lists the service keys the plugin `inject`s: its `cordis.yml`
 Requires: `agents`
 
 ```ts config-catalog
-/** Plugin config: the provider/model target used for each ACP-created agent. */
+/** Plugin config: the provider/model selection used for each ACP-created agent. */
 export interface AcpConfig {
   /** Provider route for created agents. */
   provider?: string
@@ -80,6 +80,20 @@ Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) ·
 
 Source: [`packages/examples/acp-demo/src/index.ts:39`](../packages/examples/acp-demo/src/index.ts)
 
+## `@deepseek-ai/dsh-agent-default-model`
+
+```ts config-catalog
+/** Composition entry for the default model selection. */
+export interface Config {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+}
+```
+
+Source: [`packages/core/agent-default-model/src/index.ts:41`](../packages/core/agent-default-model/src/index.ts)
+
 ## `@deepseek-ai/dsh-agent-loop`
 
 Requires: `agents` · `sessions` · `llm` · `tools` · `systemPrompt`
@@ -475,17 +489,17 @@ Source: [`packages/goal/goal/src/index.ts:116`](../packages/goal/goal/src/index.
 
 ## `@deepseek-ai/dsh-headless`
 
-Requires: `apiProxy` · `httpServer`
+Requires: `agentDefaultModel` · `agents` · `sessions`
 
 ```ts config-catalog
 /** Plugin config: the task, patched in by the launcher. */
 export interface Config {
-  /** The prompt text for the single turn. */
+  /** The prompt text for the single run. */
   task: string
 }
 ```
 
-Source: [`packages/bundle/headless/src/index.ts:32`](../packages/bundle/headless/src/index.ts)
+Source: [`packages/bundle/headless/src/index.ts:29`](../packages/bundle/headless/src/index.ts)
 
 ## `@deepseek-ai/dsh-hooks-claude`
 
@@ -550,32 +564,17 @@ Source: [`packages/hooks/hooks-codex/src/index.ts:44`](../packages/hooks/hooks-c
 
 ## `@deepseek-ai/dsh-host-apiproxy`
 
-Requires: `agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
+Requires: `agentDefaultModel` · `agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
 
 ```ts config-catalog
-/**
- * Gateway plugin config: host-level agent routing and Workspace creation root.
- *
- * `reasoningEffort` is deliberately absent, so the section carries one field
- * the composition cannot. The seam resolves a section by MERGING the user
- * layer over the composition entry per field, and an absent key cannot
- * override a present one — so a composition-set effort would survive every
- * later switch to a model that has none, and strand it for the next session
- * to fail on. Effort is a per-model fact anyway: a deployment default belongs
- * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
- * which resolves per model rather than per gateway.
- */
+/** Gateway plugin config: the Host-only Workspace creation root. */
 export interface Config {
-  /** Default provider route for created agents. */
-  provider: string
-  /** Default model id. */
-  model: string
   /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
   workspaceRoot?: string
 }
 ```
 
-Source: [`packages/host/apiproxy/src/index.ts:67`](../packages/host/apiproxy/src/index.ts)
+Source: [`packages/host/apiproxy/src/index.ts:38`](../packages/host/apiproxy/src/index.ts)
 
 ## `@deepseek-ai/dsh-host-directory-picker-browse`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index f5ea3eba36..628750959e 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -18,7 +18,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
 | `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
 | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), `server` |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 846ade98b9..a089e2a1f0 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -137,6 +137,7 @@
 | message | 消息 | | | |
 | mod | 模组 | | | |
 | model provider | 模型提供方 | | | |
+| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |
 | module | 模块 | | | |
 | non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |
 | npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 6f47c36e97..e7d6b47e70 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -25,6 +25,7 @@ flowchart TD
   end
   subgraph group_core["packages/core"]
     pkg_agent["agent"]
+    pkg_agent_default_model["agent-default-model"]
     pkg_agent_loop["agent-loop"]
     pkg_scope["scope"]
     pkg_session["session"]
@@ -510,6 +511,10 @@ flowchart TD
   pkg_token_meter --> pkg_llm
   pkg_token_meter --> pkg_session
   pkg_token_meter --> pkg_session_projection
+  pkg_agent_default_model --> pkg_agent
+  pkg_agent_default_model --> pkg_invariants
+  pkg_agent_default_model --> pkg_llm
+  pkg_agent_default_model --> pkg_settings
   pkg_goal --> pkg_agent
   pkg_goal --> pkg_brand
   pkg_goal --> pkg_invariants
@@ -553,11 +558,6 @@ flowchart TD
   pkg_loader_smoke --> pkg_invariants
   pkg_loader_smoke --> pkg_llm
   pkg_loader_smoke --> pkg_session
-  pkg_headless --> pkg_agent
-  pkg_headless --> pkg_host_apiproxy
-  pkg_headless --> pkg_host_webserver
-  pkg_headless --> pkg_invariants
-  pkg_headless --> pkg_session
   pkg_client_ui_layout --> pkg_client_runtime
   pkg_client_ui_layout --> pkg_client_ui_slots
   pkg_client_ui_layout --> pkg_client_ui_theme
@@ -698,6 +698,11 @@ flowchart TD
   pkg_api_remotes --> pkg_session
   pkg_api_remotes --> pkg_session_persistence
   pkg_api_remotes --> pkg_typert_registry
+  pkg_headless --> pkg_agent
+  pkg_headless --> pkg_agent_default_model
+  pkg_headless --> pkg_invariants
+  pkg_headless --> pkg_llm
+  pkg_headless --> pkg_session
   pkg_client_ui_conversation --> pkg_client_locale
   pkg_client_ui_conversation --> pkg_client_runtime
   pkg_client_ui_conversation --> pkg_client_ui_primitives
@@ -1252,6 +1257,7 @@ flowchart TD
 | [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`agent-default-model`](../packages/core/agent-default-model) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pwsh-local`](../packages/bash/pwsh-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1263,7 +1269,6 @@ flowchart TD
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
@@ -1295,6 +1300,7 @@ flowchart TD
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
 | [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
+| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 42f00a896e..6a117435f5 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: cc9cc30677b0b657492d8a5118489e8b801f3fd3
-core.zh.md: 96854801d684509d4d77b6408a4bb45b93438cdb
+core.md: b09e5b4f0a076a7f95a751a6204836a81a4c31e9
+core.zh.md: 01ac656fb657296fb26217108b8a4a15a5a88280
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index cc9cc30677..b09e5b4f0a 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -314,6 +314,30 @@ The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm)
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxagentdefaultmodel--agentdefaultmodelservice"></a>
+
+### `ctx.agentDefaultModel` — `AgentDefaultModelService`
+
+Owns the default model selection independently of any Host or transport. The composition entry remains usable without a settings provider; when one is mounted, its user layer is read live.
+
+```ts cordis-catalog
+/**
+ * Read the current default model selection.
+ * @returns a detached provider, model, and optional reasoning selection.
+ */
+currentSelection(): ModelSelection
+
+/**
+ * Save the complete default model selection. A deployment without a settings
+ * provider keeps its composition entry.
+ * @param next - resolved selection accepted by a front door.
+ * @returns fulfillment after the optional settings write settles.
+ */
+async saveSelection(next: ModelSelection): Promise<void>
+```
+
+Source: [`packages/core/agent-default-model/src/index.ts:64`](../../packages/core/agent-default-model/src/index.ts)
+
 <a id="ctxagentloop--agentloop"></a>
 
 ### `ctx.agentLoop` — `AgentLoop`
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 96854801d6..01ac656fb6 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -322,6 +322,30 @@ type Branded<B extends string> = string & { readonly [BRAND]: B }
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxagentdefaultmodel--agentdefaultmodelservice"></a>
+
+### `ctx.agentDefaultModel` — `AgentDefaultModelService`
+
+Owns the default model selection independently of any Host or transport. The composition entry remains usable without a settings provider; when one is mounted, its user layer is read live.
+
+```ts cordis-catalog
+/**
+ * Read the current default model selection.
+ * @returns a detached provider, model, and optional reasoning selection.
+ */
+currentSelection(): ModelSelection
+
+/**
+ * Save the complete default model selection. A deployment without a settings
+ * provider keeps its composition entry.
+ * @param next - resolved selection accepted by a front door.
+ * @returns fulfillment after the optional settings write settles.
+ */
+async saveSelection(next: ModelSelection): Promise<void>
+```
+
+Source: [`packages/core/agent-default-model/src/index.ts:64`](../../packages/core/agent-default-model/src/index.ts)
+
 <a id="ctxagentloop--agentloop"></a>
 
 ### `ctx.agentLoop` — `AgentLoop`
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 38df7fb986..cf4fba292f 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
-providers.md: 8b52044e64411e3081d56c1ee1849d0b24cd1cda
-providers.zh.md: f4a42a4093d253b4b230e4a838ba275a0ce58ac9
+providers.md: ad0bd3696dbbdc4a89334932196d72a0afd3d209
+providers.zh.md: 719039cf7af8b59663642ebad81dbf315a023154
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index 8b52044e64..ad0bd3696d 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -124,16 +124,16 @@ Under `dsh`, references resolve from the inherited environment, the Models page'
 
 A configured route appears in the web model picker and can be switched at any time, which is how most people use it.
 
-Switching there also sets the default: the model you pick becomes the one the next new session starts on, recorded in `settings.yaml` under `api-gateway`. There is no separate gesture.
+Switching there also sets the default: the model you pick becomes the one the next new session starts on, recorded in `settings.yaml` under `agent-default-model`. There is no separate gesture.
 
 ```yaml
-api-gateway:
+agent-default-model:
   provider: acme-gateway
   model: acme-large
   reasoningEffort: high   # optional
 ```
 
-A session that has already run a turn is never retargeted by it — that session derives its route from its own log, so changing the default only reaches sessions that have not started. The shipped fallback under this section is the `api-gateway` composition entry (`deepseek-official` / `deepseek-v4-flash`), which a self-assembled `cordis.yml` may override; a composition you assemble yourself — headless, for instance — sets `agent-loop`'s `agents` instead.
+After a session has run a turn, its own log remains authoritative for its model selection; the default applies only to sessions without a recorded request. The shipped fallback under this section is the base bundle's `agent-default-model` composition entry (`deepseek-official` / `deepseek-v4-flash`). A self-assembled `cordis.yml` mounts and configures `@deepseek-ai/dsh-agent-default-model`; both direct front doors and Host-backed front doors read that same service.
 
 If the provider a saved default names is later removed, the composer says **Select model** and refuses input until you pick one, rather than sending to a route nothing serves.
 
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index f4a42a4093..719039cf7a 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -124,16 +124,16 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 配好的路由会出现在 Web 的模型选择器里，随时可切，这也是最常用的方式。
 
-在那里切换同时也就选定了默认值：你选的模型会成为下一个新会话的起点，记录在 `settings.yaml` 的 `api-gateway` 段里。没有另一个单独的手势。
+在那里切换同时也就选定了默认值：你选的模型会成为下一个新会话的起点，记录在 `settings.yaml` 的 `agent-default-model` 段里。没有另一个单独的手势。
 
 ```yaml
-api-gateway:
+agent-default-model:
   provider: acme-gateway
   model: acme-large
   reasoningEffort: high   # optional
 ```
 
-已经跑过一轮的会话不会被它重定向——那个会话从自己的日志推导路由，因此改默认值只影响还没开始的会话。这个段落之下的出厂兜底是 `api-gateway` 组合条目（`deepseek-official` / `deepseek-v4-flash`），自行组装的 `cordis.yml` 可以覆盖它；自行组装的组合（例如 headless）改的则是 `agent-loop` 的 `agents`。
+会话跑过一轮后，其自身日志仍是模型选择的权威；默认值只适用于尚无请求记录的会话。这个段落之下的出厂兜底是 base 组合包的 `agent-default-model` 组合条目（`deepseek-official` / `deepseek-v4-flash`）。自行组装的 `cordis.yml` 会挂载并配置 `@deepseek-ai/dsh-agent-default-model`；直接前门与 Host 支撑的前门都读取同一服务。
 
 如果某个已存默认值指向的提供方后来被删掉了，输入框会显示**选择模型**并拒绝输入，而不是把消息发给一个没人服务的路由。
 
diff --git a/docs/user/guide/quickstart.i18n.yaml b/docs/user/guide/quickstart.i18n.yaml
index dfdba88bec..9bb9b99bd8 100644
--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.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 docs/user/guide/quickstart.md
-quickstart.md: 9d1a04f0a094919bb008a7e94564a6612e10732d
-quickstart.zh.md: 7182f63586f4f08524c643a7c6c1ad599b2de098
+quickstart.md: ce196641f205324334533c025b4ac1dc791f857d
+quickstart.zh.md: ce12f43fa660f0a99be73749e0345570575fbbee
diff --git a/docs/user/guide/quickstart.md b/docs/user/guide/quickstart.md
index 9d1a04f0a0..ce196641f2 100644
--- a/docs/user/guide/quickstart.md
+++ b/docs/user/guide/quickstart.md
@@ -39,7 +39,7 @@ Run a non-interactive task and print its final answer:
 pnpm run dsh run "summarize the architecture of this workspace"
 ```
 
-`dsh run` creates and persists a fresh session, prints the final assistant answer, and exits. While it runs, stderr prints the local browser URL where the session can be observed.
+`dsh run` creates and persists a fresh session, prints the final assistant answer, and exits. It starts no Web server or listening port, and a successful run leaves stderr empty.
 
 ## Step 3: use the Web UI
 
@@ -53,7 +53,7 @@ Open `http://127.0.0.1:3080`. The agent can read and write files, run commands,
 
 ## What happened
 
-`dsh run` boots the `headless` profile: [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml), [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml), and [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) compose over an empty root. `dsh web` uses the first two layers without the one-shot runner. Both select the DeepSeek model and capability plugins appropriate to their entry mode.
+`dsh run` boots the `headless` profile: [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) and [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) compose over an empty root, then the runner drives the core Agent and Session services directly. `dsh web` instead composes `dsh-base` with [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml), which owns the Host, HTTP, and browser layers. Both read the same default DeepSeek model route from `dsh-base`.
 
 ## Next steps
 
diff --git a/docs/user/guide/quickstart.zh.md b/docs/user/guide/quickstart.zh.md
index 7182f63586..ce12f43fa6 100644
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -39,7 +39,7 @@ DEEPSEEK_API_KEY=sk-your-key-here
 pnpm run dsh run "summarize the architecture of this workspace"
 ```
 
-`dsh run` 创建并持久化一个新会话，打印最终 assistant 回答，然后退出。运行期间，stderr 会打印可用于观察该会话的本地浏览器 URL。
+`dsh run` 创建并持久化一个新会话，打印最终 assistant 回答，然后退出。它不会启动 Web 服务器或监听端口；成功运行时 stderr 为空。
 
 ## 第三步：使用 Web UI
 
@@ -53,7 +53,7 @@ pnpm run dsh web
 
 ## 回头看
 
-`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml)、[`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合。`dsh web` 使用前两层，不包含一次性 runner。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
+`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合，随后 runner 直接驱动 core Agent 与 Session 服务。`dsh web` 则由 `dsh-base` 与 [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 组合，后者拥有 Host、HTTP 与浏览器层。二者都从 `dsh-base` 读取同一个默认 DeepSeek 模型路由。
 
 ## 下一步
 
diff --git a/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml b/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
index 7d411f7a0f..4199bfb9ca 100644
--- a/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/dsh-run.cordis.yml
@@ -1,4 +1,4 @@
-- id: api-gateway
+- id: agent-default-model
   config:
     provider: cli-mock
     model: cli-mock
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 87261439da..593b05b4e8 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -234,7 +234,7 @@ describe('headless stream-json snapshots', () => {
     })
 
     expect(result.stdout).toBe('CLI tool round trip complete: CLI_TOOL_ROUND_TRIP\n')
-    expect(result.stderr).toMatch(/^dsh: observing at http:\/\/127\.0\.0\.1:\d+\n$/u)
+    expect(result.stderr).toBe('')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
   it('prints the original Loader activation error through the assembled one-shot app', async () => {
diff --git a/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl b/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl
index 1312eb6511..260ae241b0 100644
--- a/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl
@@ -2,11 +2,11 @@
 {"type":"permission/preset","seq":0,"time":0,"data":{"preset":"danger-full-access"}}
 {"type":"sandbox/mode","seq":1,"time":0,"data":{"mode":"danger-full-access"}}
 {"type":"approval/policy","seq":2,"time":0,"data":{"policy":"never"}}
-{"type":"agent/inbox/spliced","seq":3,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user","rpcId":"{{sessionId}}"},"role":"user","id":"{{sessionId}}"}]}}
+{"type":"agent/inbox/spliced","seq":3,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"}]}}
 {"type":"turn/start","seq":4,"time":0,"data":{"turn":1}}
 {"type":"agent/inbox/spliced","seq":5,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","seq":6,"time":0,"data":{"turn":1,"step":1}}
-{"type":"user/message","seq":7,"time":0,"data":{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user","rpcId":"{{sessionId}}"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":7,"time":0,"data":{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
 {"type":"user/message","seq":8,"time":0,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
 {"type":"session/title","seq":9,"time":0,"data":{"title":"Prove the product dsh run","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","seq":10,"time":0,"data":{"header":{"config":{"provider":"cli-mock","model":"cli-mock","reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/knip.json b/knip.json
index 9ca15de212..812f7446bc 100644
--- a/knip.json
+++ b/knip.json
@@ -751,6 +751,11 @@
         "@cordisjs/.+"
       ]
     },
+    "packages/bundle/headless": {
+      "ignoreDependencies": [
+        "@deepseek-ai/dsh-code-runtime-worker"
+      ]
+    },
     "packages/bundle/web-app": {
       "ignoreDependencies": [
         "@deepseek-ai/.+"
diff --git a/packages/acp/acp/src/index.ts b/packages/acp/acp/src/index.ts
index 50549d7ab0..a1d37e2aa9 100644
--- a/packages/acp/acp/src/index.ts
+++ b/packages/acp/acp/src/index.ts
@@ -66,7 +66,7 @@ function internalError(detail: string): RequestError {
   return RequestError.internalError(undefined, detail)
 }
 
-/** Plugin config: the provider/model target used for each ACP-created agent. */
+/** Plugin config: the provider/model selection used for each ACP-created agent. */
 export interface AcpConfig {
   /** Provider route for created agents. */
   provider?: string
@@ -100,7 +100,7 @@ interface SessionRecord {
 /**
  * Mount the automation-only ACP server.
  * @param ctx - Cordis context carrying the agent factory and session events.
- * @param config - Initial provider/model target and optional test transport.
+ * @param config - Initial provider/model selection and optional test transport.
  */
 export function apply(ctx: Context, config: AcpConfig): void {
   // ACP handlers execute outside this plugin's injection scope, so capture the
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index fd61b9bec2..e64706453e 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/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/boot/app-boot/README.md
-README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
-README.zh.md: 454d504be72c2120ec4aeaa1b22545e7d6ba2fee
+README.md: c060e99acb8cc40b8de92806727eea9e3723b7d2
+README.zh.md: f28b89e63e4bd6f07f2f7a55dfba5c2f78862feb
diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md
index c256b89288..c060e99acb 100644
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -33,7 +33,7 @@ This package carries no loader hooks and no dev-mode surface. The [`dsh` app](..
 
 ## Profiles
 
-A profile is a directory under `$DSH_HOME/profiles/<name>` (the Harness home resolves through [`resolveDshHome`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) holding a `package.json` — out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list — and the user's own `cordis.patch.yml`. A bundle is an npm package whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; `loadProfile` resolves each `dsh.profile.bundles` name two-anchored (the dsh installation first, then the profile directory) and fails loud on a listed package without a bundle declaration. `composeEntries` applies patch layers over an empty entry list through the include's own `applyEntryPatches`, so composition, flag derivation, and config dumps can never drift from what boots. `healProfilesModuleFallback` maintains the flat `$DSH_HOME/profiles/node_modules` directory — one symlink per package the installation's app and bundles depend on — so bare plugin names in any profile resolve through Node's ordinary parent-walk without pnpm ever managing in-box packages. `PROFILE_TEMPLATES` (`web`, `headless`) auto-initialize on first use; other names fail loud until `initProfile` creates them (the `dsh plugin` path).
+A profile is a directory under `$DSH_HOME/profiles/<name>` (the Harness home resolves through [`resolveDshHome`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) holding a `package.json` — out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list — and the user's own `cordis.patch.yml`. A bundle is an npm package whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; `loadProfile` resolves each `dsh.profile.bundles` name two-anchored (the dsh installation first, then the profile directory) and fails loud on a listed package without a bundle declaration. `composeEntries` applies patch layers over an empty entry list through the include's own `applyEntryPatches`, so composition, flag derivation, and config dumps cannot drift from what boots. `healProfilesModuleFallback` maintains the flat `$DSH_HOME/profiles/node_modules` directory — one symlink per package the installation's app and bundles depend on — so bare plugin names in any profile resolve through Node's ordinary parent-walk without pnpm managing in-box packages. `PROFILE_TEMPLATES` (`web`, `headless`) auto-initialize on first use; other names fail loud until `initProfile` creates them (the `dsh plugin` path). `loadProfile` normalizes an exact installation-owned bundle tuple to its shipped template while preserving every other manifest field; any extra, missing, or reordered entry makes the list user-owned and leaves it unchanged.
 
 User-level machine-local preferences also live in the Harness home:
 
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 454d504be7..f28b89e63e 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -35,7 +35,7 @@ Loader 并发挂载各个条目，因此当其他环节失败时，某个界面
 
 ## Profile
 
-profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则大声失败。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会大声失败（即 `dsh plugin` 路径）。
+profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则大声失败。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，且无需 pnpm 管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会大声失败（即 `dsh plugin` 路径）。`loadProfile` 会将与安装自有组合包元组完全一致的列表规范化为随发行版交付的模板，同时保留 manifest 中其他所有字段；一旦条目有任何额外、缺失或重排，该列表就归用户所有并保持不变。
 
 用户级的机器本地偏好同样位于 Harness home 中：
 
diff --git a/packages/boot/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts
index c353f18bef..1e71f3e8a7 100644
--- a/packages/boot/app-boot/src/profile.ts
+++ b/packages/boot/app-boot/src/profile.ts
@@ -114,6 +114,11 @@ export function resolveProfileDir(name: string, home: string = resolveDshHome())
 /** The shipped profile templates auto-initialized on first use, by name. */
 export const PROFILE_TEMPLATES: Record<string, readonly string[]> = {
   web: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'],
+  headless: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'],
+}
+
+/** Installation-owned bundle tuples normalized to the shipped template. */
+const INSTALLATION_OWNED_PROFILE_TUPLES: Record<string, readonly string[]> = {
   headless: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless'],
 }
 
@@ -279,6 +284,32 @@ export function writeProfileManifest(dir: string, manifest: ProfileManifest): vo
   writeFileSync(join(dir, 'package.json'), JSON.stringify(manifest, undefined, 2) + '\n')
 }
 
+/** Return whether two bundle lists have the same values in the same order. */
+function sameBundles(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+/**
+ * Normalize an exact installation-owned bundle tuple to its shipped template
+ * while preserving every other manifest field. Any other list is user-owned.
+ */
+function normalizeShippedProfile(name: string, dir: string, manifest: ProfileManifest): ProfileManifest {
+  const installationOwned = INSTALLATION_OWNED_PROFILE_TUPLES[name]
+  const current = PROFILE_TEMPLATES[name]
+  const bundles = manifest.dsh?.profile?.bundles
+  if (installationOwned === undefined || current === undefined || bundles === undefined
+    || !sameBundles(bundles, installationOwned)) return manifest
+  const normalized: ProfileManifest = {
+    ...manifest,
+    dsh: {
+      ...manifest.dsh,
+      profile: { ...manifest.dsh?.profile, bundles: [...current] },
+    },
+  }
+  writeProfileManifest(dir, normalized)
+  return normalized
+}
+
 /**
  * Resolve a package's root directory from one anchor without depending on the
  * package exporting `./package.json` (`require.resolve` would need that):
@@ -350,7 +381,7 @@ export function loadProfile(
     }
     initProfile(dir, template)
   }
-  const manifest = readProfileManifest(binName, dir)
+  const manifest = normalizeShippedProfile(name, dir, readProfileManifest(binName, dir))
   // A hand-written profile manifest may omit the dsh section entirely.
   const bundles = manifest.dsh?.profile?.bundles ?? []
   const layers = bundles.map((packageName): ProfileLayer => {
diff --git a/packages/boot/app-boot/tests/profile.spec.ts b/packages/boot/app-boot/tests/profile.spec.ts
index f0bd6f5da7..bd0294475d 100644
--- a/packages/boot/app-boot/tests/profile.spec.ts
+++ b/packages/boot/app-boot/tests/profile.spec.ts
@@ -161,6 +161,33 @@ describe('loadProfile', () => {
       .toEqual([...PROFILE_TEMPLATES.web ?? []])
   })
 
+  it('normalizes only the exact installation-owned headless bundle tuple', () => {
+    const anchor = stageInstallation({
+      '@deepseek-ai/dsh-base': { patch: '[]\n' },
+      '@deepseek-ai/dsh-web-app': { patch: '[]\n' },
+      '@deepseek-ai/dsh-headless': { patch: '[]\n' },
+      'custom-bundle': { patch: '[]\n' },
+    })
+    const home = tmp()
+    const stock = resolveProfileDir('headless', home)
+    initProfile(stock, [
+      '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless',
+    ])
+    loadProfile('t', 'headless', anchor, home)
+    expect(readProfileManifest('t', stock).dsh?.profile?.bundles)
+      .toEqual(['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'])
+
+    const customHome = tmp()
+    const custom = resolveProfileDir('headless', customHome)
+    initProfile(custom, [
+      '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless', 'custom-bundle',
+    ])
+    loadProfile('t', 'headless', anchor, customHome)
+    expect(readProfileManifest('t', custom).dsh?.profile?.bundles).toEqual([
+      '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless', 'custom-bundle',
+    ])
+  })
+
   it('fails loud when a listed bundle declares no dsh.bundle', () => {
     const anchor = stageInstallation({ 'not-a-bundle': {} })
     const home = tmp()
diff --git a/packages/bundle/README.i18n.yaml b/packages/bundle/README.i18n.yaml
index 860390d722..eafbe0b0ab 100644
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/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/bundle/README.md
-README.md: af06fe921a66378894a4ab0174ef403499f5f68c
-README.zh.md: b9656649782a638a3b39b4e1e6d330476b0732ba
+README.md: 696aa9ef7bbed23774f2b9ab2648ca83edcf0978
+README.zh.md: 2bb22c7949d759f404288548ea0eccfa0aac866b
diff --git a/packages/bundle/README.md b/packages/bundle/README.md
index af06fe921a..696aa9ef7b 100644
--- a/packages/bundle/README.md
+++ b/packages/bundle/README.md
@@ -8,6 +8,6 @@ Profile bundles: npm packages whose manifest declares `"dsh": { "bundle": { "pat
 |---|---|---|
 | [`base/`](base/README.md) | The shared dsh core every profile applies first | — (patch only) |
 | [`web-app/`](web-app/README.md) | Browser surface: web patch layer + runtime glue plugin | mounts rows |
-| [`headless/`](headless/README.md) | One-shot task mode over base + web-app | mounts `headless-runner` |
+| [`headless/`](headless/README.md) | Direct one-shot task mode over base, with no Host or Web layer | mounts `headless-runner` |
 
 In-box bundles resolve from the dsh installation; out-of-tree bundles install into a profile through `dsh plugin --profile <name> add <package>`.
diff --git a/packages/bundle/README.zh.md b/packages/bundle/README.zh.md
index b965664978..2bb22c7949 100644
--- a/packages/bundle/README.zh.md
+++ b/packages/bundle/README.zh.md
@@ -8,6 +8,6 @@ Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle
 |---|---|---|
 | [`base/`](base/README.md) | 每个 profile 最先应用的共享 dsh 核心 | —（仅 patch） |
 | [`web-app/`](web-app/README.md) | 浏览器表层：web patch 层 + 运行时粘合插件 | 挂载多条配置行 |
-| [`headless/`](headless/README.md) | 叠加在 base + web-app 之上的一次性任务模式 | 挂载 `headless-runner` |
+| [`headless/`](headless/README.md) | 直接运行在 base 之上的一次性任务模式，不含 Host 或 Web 层 | 挂载 `headless-runner` |
 
 内置组合包从 dsh 安装目录解析；树外（out-of-tree）组合包通过 `dsh plugin --profile <name> add <package>` 安装进 profile。
diff --git a/packages/bundle/base/README.i18n.yaml b/packages/bundle/base/README.i18n.yaml
index 2ae7df0bdc..973959478e 100644
--- a/packages/bundle/base/README.i18n.yaml
+++ b/packages/bundle/base/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/bundle/base/README.md
-README.md: 301d397d4c87687b382665cf63af47ab5e3f85be
-README.zh.md: f007bc817b6cbad84725fe8abe72549cf67d8cd7
+README.md: fb003908a262dc21edd3c9d49c972e487534f367
+README.zh.md: 13e64db6d34374fac63bf9bfd60544fc46b86f35
diff --git a/packages/bundle/base/README.md b/packages/bundle/base/README.md
index 301d397d4c..fb003908a2 100644
--- a/packages/bundle/base/README.md
+++ b/packages/bundle/base/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The shared dsh core as a profile bundle: [`cordis.patch.yml`](cordis.patch.yml) inserts every base plugin row — model adapters, tools, persistence, policy, settings/credentials, repository Plugins, telemetry — over the empty profile root, as the first layer of every profile's `dsh.profile.bundles` list. Later bundle layers (e.g. [`dsh-web-app`](../web-app/README.md)) and the user's profile `cordis.patch.yml` override these rows by id; a patch replaces a row's whole `config`, so mode-specific values live in mode bundles, not here. The package has no runtime API; the profile composer resolves the patch through the `dsh.bundle.patch` manifest field, never through code.
+The shared dsh core as a profile bundle: [`cordis.patch.yml`](cordis.patch.yml) inserts every base plugin row — model adapters, the shared [`agent-default-model`](../../core/agent-default-model/README.md) selection, tools, persistence, policy, settings/credentials, repository Plugins, telemetry — over the empty profile root, as the first layer of every profile's `dsh.profile.bundles` list. Later bundle layers (e.g. [`dsh-web-app`](../web-app/README.md)) and the user's profile `cordis.patch.yml` override these rows by id; a patch replaces a row's whole `config`, so mode-specific values live in mode bundles, not here. The package has no runtime API; the profile composer resolves the patch through the `dsh.bundle.patch` manifest field, never through code.
 
 The row set and its rationale are documented inline in the patch file; the [generated composition graph](../../../apps/cli/composition.md) renders it.
 
diff --git a/packages/bundle/base/README.zh.md b/packages/bundle/base/README.zh.md
index f007bc817b..13e64db6d3 100644
--- a/packages/bundle/base/README.zh.md
+++ b/packages/bundle/base/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-以 profile 组合包形式交付的共享 dsh 核心：[`cordis.patch.yml`](cordis.patch.yml) 在空的 profile 根之上插入全部基础插件行——模型适配器、工具、持久化、策略、settings／credentials、repository 插件、遥测——作为每个 profile 的 `dsh.profile.bundles` 列表中的第一层。后续的组合包层（例如 [`dsh-web-app`](../web-app/README.md)）和用户 profile 的 `cordis.patch.yml` 按 id 覆盖这些行；patch 会替换目标行的整个 `config`，因此模式专属的值放在各模式组合包中，而不是这里。该包没有运行时 API；profile 组合器通过 manifest（元数据清单）的 `dsh.bundle.patch` 字段解析 patch，绝不通过代码。
+以 profile 组合包形式交付的共享 dsh 核心：[`cordis.patch.yml`](cordis.patch.yml) 在空的 profile 根之上插入全部基础插件行——模型适配器、共享的 [`agent-default-model`](../../core/agent-default-model/README.md) 选择、工具、持久化、策略、settings／credentials、repository 插件、遥测——作为每个 profile 的 `dsh.profile.bundles` 列表中的第一层。后续的组合包层（例如 [`dsh-web-app`](../web-app/README.md)）和用户 profile 的 `cordis.patch.yml` 按 id 覆盖这些行；patch 会替换目标行的整个 `config`，因此模式专属的值放在各模式组合包中，而不是这里。该包没有运行时 API；profile 组合器通过 manifest（元数据清单）的 `dsh.bundle.patch` 字段解析 patch，绝不通过代码。
 
 行集合及其设计依据以行内注释写在 patch 文件里；[生成的组合图](../../../apps/cli/composition.md)负责渲染它。
 
diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml
index 799affc16b..c512127199 100644
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -65,6 +65,14 @@
     - id: agent
       name: '@deepseek-ai/dsh-agent'
 
+    # The transport-independent default for Agents created by front doors.
+    # Settings may supply a saved selection; consumers read it at creation time.
+    - id: agent-default-model
+      name: '@deepseek-ai/dsh-agent-default-model'
+      config:
+        provider: deepseek-official
+        model: deepseek-v4-flash
+
     - id: tasks
       name: '@deepseek-ai/dsh-tasks-local'
 
diff --git a/packages/bundle/base/package.json b/packages/bundle/base/package.json
index 507952b43a..c2cd151b3e 100644
--- a/packages/bundle/base/package.json
+++ b/packages/bundle/base/package.json
@@ -35,6 +35,7 @@
     "@cordisjs/plugin-hmr": "workspace:*",
     "@cordisjs/plugin-timer": "workspace:*",
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-default-model": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-bash-env": "workspace:^",
     "@deepseek-ai/dsh-bash-sandbox": "workspace:^",
diff --git a/packages/bundle/headless/README.i18n.yaml b/packages/bundle/headless/README.i18n.yaml
index f1a9d53be8..ea768061df 100644
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/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/bundle/headless/README.md
-README.md: 661b377817482d22f58f22b573075722646729a2
-README.zh.md: a6b91a8e60fdcc06ba23e07dcb2f4208ea1020f7
+README.md: 6faf1dc732345a86ec1d7b60c4f9a606e0491512
+README.zh.md: a189f77f57cf0f641abe7c11288dbc1cdf05355a
diff --git a/packages/bundle/headless/README.md b/packages/bundle/headless/README.md
index 661b377817..6faf1dc732 100644
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -2,11 +2,13 @@
 
 English | [中文](README.zh.md)
 
-The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md): it moves the webserver to an OS-assigned port (parallel runs never collide), silences the URL line, and inserts this package's `headless-runner` plugin (config `{task}`). The runner drives one task turn through the in-process API carrier (`InProcessApiClient` over `toFetchHandler(ctx.apiProxy)`, so the full wire chain — serialization, zod, SSE framing — really runs), waits at idle until that mux has consumed the session's final event sequence, aggregates the turn's final assistant text, writes it to stdout, and requests exit (completed → 0, else 1) through the launcher-provided `ctx.headlessIo` seam. The Web composition stays mounted, so the running session is observable in a browser at the stderr-announced URL. The launcher patches the task text in (`dsh run "task"`), and fails loud when the selected profile lacks this row.
+The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`). It mounts no Host, HTTP server, Web runtime, or browser plugin.
+
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` seam (final `turn/end` completed → 0, otherwise 1). A successful run writes nothing to stderr and opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
 
 ## Model Experience
 
-None, as the runner submits the task as an ordinary user message over the shared composition; prompts and tools belong to the base/web bundles.
+None, as the runner submits the task as an ordinary user message; prompts and tools belong to the base and headless bundle rows.
 
 #### KV Cache effect
 
@@ -14,5 +16,5 @@ None; the runner adds nothing to the request prefix.
 
 ## Known Limitations and Deferred Work
 
-- **One turn only** — the runner anchors on the first message-triggered turn and exits at its end; queued follow-ups and multi-turn tasks are out of scope.
+- **One submitted task only** — the runner has no interactive follow-up surface; it waits through any work the Agent completes before returning to idle and prints the last non-empty assistant message in that interval.
 - **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the seam.
diff --git a/packages/bundle/headless/README.zh.md b/packages/bundle/headless/README.zh.md
index a6b91a8e60..a189f77f57 100644
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -2,11 +2,13 @@
 
 [English](README.md) | 中文
 
-dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md) 之上：把 webserver 移到 OS 分配的端口（并行运行绝不冲突），关闭 URL 行输出，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。runner 通过进程内 API 载体（架在 `toFetchHandler(ctx.apiProxy)` 之上的 `InProcessApiClient`，因此序列化、zod、SSE（Server-Sent Events）帧封装这整条 wire 链路都会真实运行）驱动一个任务轮次，在 idle 时等待该 mux 消费完会话的最终事件序号，再聚合该轮次最终的 assistant 文本，写到 stdout，并经启动器提供的 `ctx.headlessIo` seam 请求退出（完成 → 0，否则 1）。Web 组合保持挂载，因此运行中的会话可在浏览器中通过 stderr 公告的 URL 观察。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
+dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
+
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（最终 `turn/end` 完成 → 0，否则为 1）。成功运行时不会向 stderr 写入任何内容，也不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
 
 ## 模型体验
 
-无。runner 把任务作为普通用户消息经共享组合提交；提示词与工具归 base／web 组合包所有。
+无影响，因为 runner 把任务作为普通用户消息提交；提示词与工具归 base 和 headless 组合包中的相应行所有。
 
 #### KV Cache 影响
 
@@ -14,5 +16,5 @@ dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 ## 已知限制与延期工作
 
-- **只运行一个轮次**：runner 锚定第一个由消息触发的轮次，并在其结束时退出；排队的后续消息与多轮任务不在范围内。
+- **只提交一个任务**：runner 没有用于交互式后续输入的 surface；它会等待 Agent 在返回 idle 前完成的所有工作，并打印该区间内最后一条非空 assistant 消息。
 - **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时大声失败，直到宿主提供该 seam。
diff --git a/packages/bundle/headless/cordis.patch.yml b/packages/bundle/headless/cordis.patch.yml
index 5801a20863..8b147714be 100644
--- a/packages/bundle/headless/cordis.patch.yml
+++ b/packages/bundle/headless/cordis.patch.yml
@@ -1,21 +1,26 @@
-# The dsh-headless bundle patch: one-shot task mode over dsh-base +
-# dsh-web-app. The web composition stays mounted (the session is observable
-# in a browser while it runs); this layer silences the URL line and the
-# GUI-orientation surface context (this user is not in the GUI), moves the
-# webserver to an OS-assigned port so parallel headless runs never collide,
-# and mounts the one-shot runner. The launcher patches the runner's `task`.
+# The dsh-headless bundle patch: one-shot task mode directly over dsh-base.
+# It mounts no Host, HTTP server, Web runtime, or browser plugin. The launcher
+# patches the runner's `task`; the direct driver creates an Agent through the
+# core registry and prints the final durable assistant message.
 
-- id: webserver
+- id: system-prompt
   config:
-    host: 127.0.0.1
-    port: 0
+    persona: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
 
-- id: web-runtime
+# One-shot runs never watch or reload their composition.
+- id: hmr
+  disabled: true
+
+- id: tools
   config:
-    mode: production
-    printUrl: false
-    surfaceContext: false
+    # Keep the same temporary process-wide Code Mode opt-in as the Web surface.
+    mode: !!js process.env.DSH_TOOLS_MODE
 
 - insert:
+    # Code Mode is a core execution capability, not a Web component.
+    - id: code-runtime
+      name: '@deepseek-ai/dsh-code-runtime-worker'
+
     - id: headless-runner
       name: '@deepseek-ai/dsh-headless'
diff --git a/packages/bundle/headless/package.json b/packages/bundle/headless/package.json
index 2b28423168..bc461e4c72 100644
--- a/packages/bundle/headless/package.json
+++ b/packages/bundle/headless/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-headless",
-  "description": "The dsh one-shot bundle: a patch layer over dsh-base + dsh-web-app plus the runner plugin driving one task turn through the in-process API carrier",
+  "description": "The dsh one-shot bundle: a direct core Agent/Session runner over dsh-base with no Host, HTTP, or browser layer",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -32,22 +32,23 @@
     }
   },
   "dependencies": {
+    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
     "schemastery": "^3.18.0"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
-    "@deepseek-ai/dsh-host-apiproxy": "^0.0.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.0.1",
+    "@deepseek-ai/dsh-agent-default-model": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
-    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-agent-default-model": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
diff --git a/packages/bundle/headless/src/index.ts b/packages/bundle/headless/src/index.ts
index 8db505c3ac..670838661a 100644
--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -1,36 +1,33 @@
 /**
- * @deepseek-ai/dsh-headless — the one-shot headless bundle: the bundle patch
- * (`cordis.patch.yml`) rides over dsh-base + dsh-web-app (the headless
- * session is web-observable while it runs — same composition), and this
- * runner plugin drives one task through the in-process API carrier
- * (InProcessApiClient over toFetchHandler(ctx.apiProxy), so the full wire
- * chain — serialization, zod, SSE framing — really runs), prints the final
- * assistant text at agent quiescence, and exits (completed → 0, else 1). The
- * task text arrives as launcher-patched config (`dsh run "task"`).
+ * @deepseek-ai/dsh-headless — one-shot direct Agent driver. The bundle patch
+ * rides over dsh-base without Host, HTTP, or browser plugins; this runner
+ * creates one Agent through the core registry, drives the task to quiescence,
+ * flushes its Session, prints the final assistant text, and exits.
+ *
  * @module @deepseek-ai/dsh-headless
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Context } from 'cordis'
 import z from 'schemastery'
-import { InProcessApiClient, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
-// Empty type imports carry the httpServer and agent/status Context merges used below.
-import type {} from '@deepseek-ai/dsh-host-webserver'
-import type {} from '@deepseek-ai/dsh-agent'
+import { installModelSelection } from '@deepseek-ai/dsh-agent'
+import type { ModelSelectionRef } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-agent-default-model'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 // Empty type import carries the loader Context merge for the settlement await.
 import type {} from '@cordisjs/plugin-loader'
-import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
-import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
-import type { SessionId } from '@deepseek-ai/dsh-session'
 
 /** Stable Cordis plugin name. */
 export const name = 'headless-runner'
 
-/** Services required before the one-shot turn can start. */
-export const inject = ['apiProxy', 'httpServer']
+/** Core services required before the one-shot turn can start. */
+export const inject = ['agentDefaultModel', 'agents', 'sessions']
 
 /** Plugin config: the task, patched in by the launcher. */
 export interface Config {
-  /** The prompt text for the single turn. */
+  /** The prompt text for the single run. */
   task: string
 }
 
@@ -38,16 +35,15 @@ export const Config: z<Config> = z.object({
   task: z.string().required(),
 })
 
-/** Outcome of one headless run: aggregated final text plus the last turn-end reason kind. */
-interface TurnOutcome {
+/** Outcome of one owned run interval. */
+interface RunOutcome {
   text: string
   reason: string
 }
 
 /**
- * The process-facing effects of one run, injectable for tests: output
- * streams and the exit request (the launcher wires it to its bounded
- * shutdown controller).
+ * Process-facing effects of one run, injectable for tests. The launcher owns
+ * bounded tree shutdown and wires `exit()` to it.
  */
 export interface HeadlessIo {
   stdout: { write(chunk: string): unknown }
@@ -56,127 +52,91 @@ export interface HeadlessIo {
   exit(code: number): void
 }
 
-/** Host seam: the launcher provides the exit wiring before the tree mounts. */
 declare module 'cordis' {
   interface Context {
-    /** Process-facing effects for the one-shot headless runner. */
+    /** Process-facing effects provided before the headless tree mounts. */
     headlessIo?: HeadlessIo
   }
 }
 
-/** Unwrap an RpcResponse or fail loud: business errors print and exit 1. */
-async function unwrap<T>(response: RpcResponse<T>, io: HeadlessIo): Promise<T> {
-  if (response.result.ok) return response.result.value
-  const { code, message } = response.result.error
-  io.stderr.write(`dsh: ${code}: ${message}\n`)
-  io.exit(1)
-  // Exit is asynchronous (bounded tree disposal); park this turn forever so
-  // no further request rides a session that is already being torn down.
-  return new Promise<never>(() => {})
-}
-
-/**
- * Consume mux frames until the agent reaches idle, per the one-shot CLI
- * idle-to-idle contract: the stream opens immediately before the prompt, and
- * its first observed turn/start begins the task. Text is the last committed
- * assistant message of the whole interval (steering or injected work may run
- * further turns before quiescence), and the outcome reason is the final
- * turn/end's kind. Idleness is signalled out of band by the caller's
- * `agent/status` subscription; the stream itself carries no status frame.
- * @param frames - the mux stream opened before the prompt.
- * @param sessionId - the headless session.
- * @param idle - resolves to the final session-event sequence when the agent reaches quiescence.
- * @param io - process-facing effects for stream diagnostics.
- * @returns the aggregated outcome.
- */
-async function consumeUntilIdle(
-  frames: AsyncIterable<RpcRequest<MuxFrame>>,
-  sessionId: SessionId,
-  idle: Promise<number>,
-  io: HeadlessIo,
-): Promise<TurnOutcome> {
+/** Aggregate the last assistant text and turn outcome in one owned interval. */
+function summarize(events: readonly SessionEvent[], firstSeq: number): RunOutcome {
   let started = false
   let text = ''
-  let reason: string = 'error'
-  let observedSeq = -1
-  let resolveProgress: (() => void) | undefined
-  const streamDone = (async () => {
-    try {
-      for await (const frame of frames) {
-        const payload = frame.payload
-        if (payload.type === 'stream/error') return
-        if (payload.type !== 'session/event' || payload.sessionId !== sessionId) continue
-        const event = payload.event
-        observedSeq = event.seq
-        resolveProgress?.()
-        resolveProgress = undefined
-        if (event.type === 'turn/start') {
-          started = true
-          continue
-        }
-        if (!started) continue
-        if (event.type === 'assistant/message') {
-          const joined = event.data.message.content.filter(block => block.type === 'text').map(block => block.text).join('')
-          if (joined !== '') text = joined
-        }
-        if (event.type === 'turn/end') reason = event.data.reason.kind
-      }
-    } catch (error: unknown) {
-      io.stderr.write(`dsh: event stream failed: ${String(error)}\n`)
+  let reason = 'error'
+  for (const event of events) {
+    if (event.seq < firstSeq) continue
+    if (event.type === 'turn/start') {
+      started = true
+      continue
     }
-  })()
-  const streamEnded = streamDone.then(() => 'ended' as const)
-  const idleSeq = await idle
-  while (observedSeq < idleSeq) {
-    const progress = new Promise<'progress'>((resolve) => { resolveProgress = () => { resolve('progress') } })
-    if (await Promise.race([progress, streamEnded]) === 'ended') break
+    if (!started) continue
+    if (event.type === 'assistant/message') {
+      const joined = event.data.message.content
+        .filter(block => block.type === 'text')
+        .map(block => block.text)
+        .join('')
+      if (joined !== '') text = joined
+    }
+    if (event.type === 'turn/end') reason = event.data.reason.kind
   }
   return { text, reason }
 }
 
+/** Report an unexpected direct-driver failure and request a failing exit. */
+function fail(io: HeadlessIo, error: unknown): void {
+  io.stderr.write(`dsh: ${error instanceof Error ? error.message : String(error)}\n`)
+  io.exit(1)
+}
+
 /**
- * Run one headless task to quiescence and request exit (completed → 0, else 1).
- * @param ctx - plugin context carrying apiProxy, httpServer, and the launcher's headlessIo.
- * @param config - validated {@link Config}.
+ * Run one task through a freshly created Agent and request process exit.
+ * @param ctx - plugin context carrying the Agent, default model, Session, and launcher IO services.
+ * @param task - one-shot task text.
+ * @param io - process-facing effects.
+ */
+async function run(ctx: Context, task: string, io: HeadlessIo): Promise<void> {
+  // Loader siblings mount concurrently. Await the complete application before
+  // creating an Agent so its scoped tools and adapters are not half-composed.
+  await ctx.get('loader')?.await()
+  const agents = ctx.get('agents')
+  const defaultModel = ctx.get('agentDefaultModel')
+  const sessions = ctx.get('sessions')
+  // Early process shutdown can dispose the tree while settlement is pending.
+  if (agents === undefined || defaultModel === undefined || sessions === undefined) return
+
+  const selection = defaultModel.currentSelection()
+  const { agent } = await agents.create({
+    sessionId: SessionId(`session-${randomUUID()}`),
+    meta: { cwd: process.cwd() },
+    agentOptions: { provider: selection.provider, model: selection.model },
+    setup: (agentCtx) => {
+      const selected: ModelSelectionRef = { current: selection, assembled: undefined }
+      installModelSelection(agentCtx, selected)
+    },
+  })
+  await agent.whenIdle()
+  const firstSeq = agent.session.seq
+  agent.followup(createUserMessage({
+    content: [{ type: 'text', text: task }],
+    source: { kind: 'user' },
+  }))
+  await agent.whenIdle()
+  await sessions.flush(agent.session)
+  const outcome = summarize(agent.session.events, firstSeq)
+  io.stdout.write(outcome.text + '\n')
+  io.exit(outcome.reason === 'completed' ? 0 : 1)
+}
+
+/**
+ * Mount the one-shot direct driver.
+ * @param ctx - plugin context carrying core services and the launcher-owned IO seam.
+ * @param config - validated task config.
  */
 export function apply(ctx: Context, config: Config): void {
   const io = ctx.headlessIo
   if (io === undefined) {
     throw new Error('headless-runner: the launcher must provide ctx.headlessIo before the tree mounts')
   }
-  // Fire-and-forget by design: the run outlives plugin activation, and every
-  // failure path inside ends in io.exit, not a rejection.
-  void (async () => {
-    // The Loader mounts sibling rows concurrently and this plugin's inject
-    // gate covers only apiProxy/httpServer; prompting before the agent loop,
-    // adapters, and tools settle would fail the turn on a half-mounted tree.
-    // The old launcher ran strictly after settled boot — preserve that.
-    // A tree disposed mid-settlement (early SIGTERM) has nothing to run.
-    await ctx.get('loader')?.await()
-    if (ctx.get('httpServer') === undefined) return
-    // The headless session is web-observable while it runs (same composition).
-    io.stderr.write(`dsh: observing at http://127.0.0.1:${String(ctx.httpServer.port)}\n`)
-    const api = new InProcessApiClient(toFetchHandler(ctx.apiProxy))
-    const created = await unwrap(await api.sessions.create({}), io)
-    // Open the stream before prompting so no frame is lost. The quiescence
-    // anchor below is an in-process ctx subscription, so a remote-carrier
-    // port of this runner must replace it with a wire-visible idle signal.
-    const abort = new AbortController()
-    const frames = api.events.mux({}, abort.signal)
-    const idle = new Promise<number>((resolve) => {
-      ctx.on('agent/status', ({ agent, status }) => {
-        if (agent.id === created.sessionId && status === 'idle') resolve(agent.session.seq - 1)
-      })
-    })
-    const done = consumeUntilIdle(frames, created.sessionId, idle, io)
-    await unwrap(await api.sessions.prompt({
-      sessionId: created.sessionId,
-      mode: 'queue',
-      content: [{ type: 'text', text: config.task }],
-    }), io)
-    const outcome = await done
-    io.stdout.write(outcome.text + '\n')
-    abort.abort()
-    io.exit(outcome.reason === 'completed' ? 0 : 1)
-  })()
+  void run(ctx, config.task, io).catch((error: unknown) => { fail(io, error) })
 }
diff --git a/packages/bundle/headless/tests/headless.spec.ts b/packages/bundle/headless/tests/headless.spec.ts
index 9408ee62bf..294c224354 100644
--- a/packages/bundle/headless/tests/headless.spec.ts
+++ b/packages/bundle/headless/tests/headless.spec.ts
@@ -1,170 +1,163 @@
-/**
- * One-shot runner behavior over a scripted in-process API: idle-to-idle
- * aggregation (last text of the whole interval), exit-code mapping by the
- * final turn-end reason, stream-error and RPC-error paths, and the
- * launcher-owned `ctx.headlessIo` requirement.
- */
+/** Direct one-shot Agent driving, durable aggregation, flushing, and exit mapping. */
 
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentHandle, CreateAgentOptions } from '@deepseek-ai/dsh-agent'
+import AgentDefaultModelService from '@deepseek-ai/dsh-agent-default-model'
+import { createAssistantMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
 import { apply, Config, type HeadlessIo } from '../src/index.ts'
 
-interface ScriptedEvent { type: string; seq?: number; time?: number; sessionId?: string; data: Record<string, unknown> }
-
-let nextSeq = 0
-/** Stamp the envelope fields the wire schema requires. */
-function stamped(event: ScriptedEvent): ScriptedEvent {
-  nextSeq += 1
-  return { seq: nextSeq, time: nextSeq, ...event }
+interface Script {
+  before?(session: Session): void
+  afterPrompt(session: Session, message: UserMessage): Promise<void> | void
 }
 
-interface RpcShapedRequest { rpcId: string }
-
-interface ScriptedApiOptions {
-  promptFails?: boolean
-  framesAfterPrompt?: boolean
-  onPrompt?: () => void
+function appendTurn(
+  session: Session,
+  turn: number,
+  message: UserMessage,
+  text: string | undefined,
+  completed: boolean,
+): void {
+  session.append('turn/start', { turn })
+  session.append('step/start', { turn, step: 1 })
+  session.append('user/message', message, { surfaceOp: 'append' })
+  if (text !== undefined) {
+    session.append('assistant/message', {
+      turn,
+      step: 1,
+      message: createAssistantMessage({
+        content: [{ type: 'text', text }],
+        source: { provider: 'test-provider', model: 'test-model' },
+      }),
+    }, { surfaceOp: 'append' })
+  }
+  session.append('step/end', { turn, step: 1 })
+  session.append('turn/end', {
+    turn,
+    reason: completed
+      ? { kind: 'completed' }
+      : { kind: 'aborted', reason: { kind: 'user' } },
+  })
 }
 
-/** Build a fake apiProxy (echoing rpcIds like the real gateway) whose mux stream replays `events` for the created session. */
-function scriptedApi(events: ScriptedEvent[], options: ScriptedApiOptions = {}): unknown {
-  let releaseFrames = (): void => {}
-  const framesReady = options.framesAfterPrompt === true
-    ? new Promise<void>((resolve) => { releaseFrames = resolve })
-    : Promise.resolve()
-  const prepared = events.map((event) => {
-    if (event.type === 'stream/error') return { streamError: true } as const
-    const { sessionId = 'S1', ...rest } = event
-    return { streamError: false, sessionId, event: stamped(rest) } as const
+/** Mount the real registries around a small scripted Agent factory. */
+async function bench(script: Script): Promise<{
+  ctx: Context
+  run(): Promise<{ code: number; out: string; err: string; order: string[] }>
+}> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentDefaultModelService, { provider: 'test-provider', model: 'test-model' })
+  ctx.agents.setFactory({
+    async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle> {
+      const session = ctx.sessions.create(options.sessionId, {
+        ...options.meta === undefined ? {} : { meta: options.meta },
+      })
+      let idle = Promise.resolve()
+      const agent = {} as Agent
+      const agentCtx = ownerCtx.extend({ agent })
+      Object.assign(agent, {
+        id: session.id,
+        options: options.agentOptions ?? {},
+        session,
+        inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+        status: 'idle',
+        ctx: agentCtx,
+        cancel: () => {},
+        runMaintenance: () => Promise.reject(new Error('not used')),
+        send: () => {},
+        followup: (message: UserMessage) => {
+          agent.inbox.append('next-turn', message)
+          idle = Promise.resolve().then(() => script.afterPrompt(session, message))
+        },
+        steer: () => {},
+        inject: () => {},
+        whenIdle: () => idle,
+      } satisfies Partial<Agent>)
+      await options.setup?.(agentCtx)
+      script.before?.(session)
+      ctx.agents.register(agent)
+      return { agent, dispose: () => Promise.resolve() }
+    },
+    resume: () => Promise.reject(new Error('not used')),
   })
   return {
-    sessions: {
-      create: (request: RpcShapedRequest) =>
-        Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
-      prompt: (request: RpcShapedRequest) => {
-        releaseFrames()
-        options.onPrompt?.()
-        return Promise.resolve(options.promptFails === true
-          // A code from the closed wire union: the carrier schema rejects invented codes.
-          ? { rpcId: request.rpcId, result: { ok: false, error: { code: 'agent-busy', message: 'agent is busy', details: { reason: 'test' } } } }
-          : { rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } })
-      },
-    },
-    events: {
-      mux: async function* () {
-        await framesReady
-        for (const item of prepared) {
-          if (item.streamError) {
-            yield { rpcId: 'e', payload: { type: 'stream/error', error: { code: 'cancelled', message: 'stream broke', details: {} } } }
-            continue
-          }
-          yield { rpcId: 'e', payload: { type: 'session/event', sessionId: item.sessionId, event: item.event } }
+    ctx,
+    run: async () => {
+      let out = ''
+      let err = ''
+      const order: string[] = []
+      ctx.on('session/flush', () => { order.push('flush') })
+      const exited = new Promise<number>((resolve) => {
+        const io: HeadlessIo = {
+          stdout: { write: (chunk: string) => { out += chunk; return true } },
+          stderr: { write: (chunk: string) => { err += chunk; return true } },
+          exit: (code) => { order.push('exit'); resolve(code) },
         }
-      },
+        ctx.provide('headlessIo', io)
+      })
+      apply(ctx, { task: 'do the thing' })
+      return { code: await exited, out, err, order }
     },
   }
 }
 
-/**
- * Mount the runner against a scripted API, emit the idle transition after the
- * scripted frames drain, and wait for its exit request.
- */
-async function run(
-  events: ScriptedEvent[],
-  options: { promptFails?: boolean; framesAfterPrompt?: boolean; idleInPrompt?: boolean } = {},
-): Promise<{ code: number; out: string; err: string }> {
-  const ctx = new Context()
-  let out = ''
-  let err = ''
-  const exited = new Promise<number>((resolve) => {
-    const io: HeadlessIo = {
-      stdout: { write: (chunk: string) => { out += chunk; return true } },
-      stderr: { write: (chunk: string) => { err += chunk; return true } },
-      exit: resolve,
-    }
-    ctx.provide('headlessIo', io)
-  })
-  const emitIdle = (): void => {
-    ctx.emit('agent/status', { agent: { id: 'S1', session: { seq: nextSeq + 1 } } as Agent, status: 'idle' })
-  }
-  ctx.provide('apiProxy', scriptedApi(events, {
-    ...options.promptFails === undefined ? {} : { promptFails: options.promptFails },
-    ...options.framesAfterPrompt === undefined ? {} : { framesAfterPrompt: options.framesAfterPrompt },
-    ...options.idleInPrompt === true ? { onPrompt: emitIdle } : {},
-  }) as never)
-  ctx.provide('httpServer', { port: 12345 } as never)
-  apply(ctx, { task: 'do the thing' })
-  // Quiescence is out of band: give the scripted stream a beat to drain, then
-  // flip the agent idle exactly as the loop would. Foreign agents and
-  // non-idle transitions must not settle the run.
-  if (options.idleInPrompt !== true) {
-    await new Promise(resolve => setTimeout(resolve, 10))
-    ctx.emit('agent/status', { agent: { id: 'OTHER' } as Agent, status: 'idle' })
-    ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'running' })
-    emitIdle()
-  }
-  const code = await exited
-  await ctx.fiber.dispose()
-  return { code, out, err }
-}
-
-const startupTurn: ScriptedEvent = { type: 'turn/start', data: { turn: 0, trigger: { kind: 'startup' } } }
-const messageTurn: ScriptedEvent = { type: 'turn/start', data: { turn: 1, trigger: { kind: 'message' } } }
-const text = (turn: number, value: string): ScriptedEvent => ({
-  type: 'assistant/message',
-  data: { turn, message: { content: [{ type: 'text', text: value }] } },
-})
-const end = (turn: number, reason: string): ScriptedEvent => ({ type: 'turn/end', data: { turn, reason: { kind: reason } } })
-
 describe('headless runner', () => {
-  it('aggregates to quiescence: last text wins across turns, final turn-end reason maps to exit 0', async () => {
-    const { code, out, err } = await run([
-      // Frames before the first turn/start are outside the task interval.
-      { type: 'assistant/message', data: { turn: 0, message: { content: [{ type: 'text', text: 'pre-task noise' }] } } },
-      startupTurn,
-      // Off-session, non-text, and text-empty frames never affect the aggregate.
-      { type: 'assistant/message', sessionId: 'OTHER', data: { turn: 1, message: { content: [{ type: 'text', text: 'other session' }] } } },
-      { type: 'assistant/message', data: { turn: 1, message: { content: [{ type: 'tool_call', text: 'ignored' }] } } },
-      text(0, 'draft'),
-      end(0, 'completed'),
-      messageTurn,
-      text(1, 'final answer'),
-      end(1, 'completed'),
-    ])
-    expect(code).toBe(0)
-    expect(out).toBe('final answer\n')
-    expect(err).toContain('observing at http://127.0.0.1:12345')
+  it('aggregates the final text across the complete idle-to-idle interval and flushes before exit', async () => {
+    const test = await bench({
+      before(session) {
+        const setupMessage = {
+          role: 'user', content: [{ type: 'text', text: 'setup' }], source: { kind: 'user' }, id: 'setup',
+        } as UserMessage
+        appendTurn(session, 0, setupMessage, 'pre-task noise', true)
+      },
+      async afterPrompt(session, message) {
+        await Promise.resolve()
+        appendTurn(session, 1, message, '', true)
+        appendTurn(session, 2, message, 'final answer', true)
+      },
+    })
+    const result = await test.run()
+    expect(result).toEqual({
+      code: 0,
+      out: 'final answer\n',
+      err: '',
+      order: ['flush', 'exit'],
+    })
+    await test.ctx.fiber.dispose()
   })
 
-  it('consumes through the idle sequence when queued frames arrive after the status transition', async () => {
-    const { code, out } = await run(
-      [messageTurn, text(1, 'race-free answer'), end(1, 'completed')],
-      { framesAfterPrompt: true, idleInPrompt: true },
-    )
-    expect(code).toBe(0)
-    expect(out).toBe('race-free answer\n')
+  it('waits for asynchronously appended events instead of racing Agent idleness', async () => {
+    const test = await bench({
+      afterPrompt: async (session, message) => {
+        await new Promise(resolve => setTimeout(resolve, 5))
+        appendTurn(session, 1, message, 'race-free answer', true)
+      },
+    })
+    expect(await test.run()).toMatchObject({ code: 0, out: 'race-free answer\n', err: '' })
+    await test.ctx.fiber.dispose()
   })
 
-  it('exits 1 when the final turn ends for any other reason', async () => {
-    const { code } = await run([messageTurn, end(1, 'aborted')])
-    expect(code).toBe(1)
+  it('exits 1 when the final turn does not complete', async () => {
+    const test = await bench({
+      afterPrompt(session, message) { appendTurn(session, 1, message, undefined, false) },
+    })
+    expect(await test.run()).toMatchObject({ code: 1, out: '\n', err: '' })
+    await test.ctx.fiber.dispose()
   })
 
-  it('exits 1 when no turn ever starts (idle without work)', async () => {
-    const { code, out } = await run([])
-    expect(code).toBe(1)
-    expect(out).toBe('\n')
+  it('exits 1 when the owned interval contains no turn', async () => {
+    const test = await bench({ afterPrompt: () => {} })
+    expect(await test.run()).toMatchObject({ code: 1, out: '\n', err: '' })
+    await test.ctx.fiber.dispose()
   })
 
-  it('keeps the error outcome after a stream error ends the frame consumer early', async () => {
-    const { code } = await run([messageTurn, { type: 'stream/error', data: {} }, end(1, 'completed')])
-    // The consumer stopped at the stream error; the completed turn-end after
-    // it is never observed, so the reason stays 'error'.
-    expect(code).toBe(1)
-  })
-
-  it('prints an RPC business error and exits 1 without waiting for idle', async () => {
+  it('reports a direct Agent creation failure', async () => {
     const ctx = new Context()
     let err = ''
     const exited = new Promise<number>((resolve) => {
@@ -174,15 +167,16 @@ describe('headless runner', () => {
         exit: resolve,
       } satisfies HeadlessIo)
     })
-    ctx.provide('apiProxy', scriptedApi([messageTurn, end(1, 'completed')], { promptFails: true }) as never)
-    ctx.provide('httpServer', { port: 1 } as never)
+    ctx.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
+    ctx.provide('sessions', { flush: () => Promise.resolve(true) } as never)
+    ctx.provide('agents', { create: () => Promise.reject(new Error('factory exploded')) } as never)
     apply(ctx, { task: 't' })
     expect(await exited).toBe(1)
-    expect(err).toContain('agent-busy')
+    expect(err).toBe('dsh: factory exploded\n')
     await ctx.fiber.dispose()
   })
 
-  it('reports the stream-failed diagnostic when the event channel dies, still settling at idle', async () => {
+  it('stringifies a non-Error Agent creation failure', async () => {
     const ctx = new Context()
     let err = ''
     const exited = new Promise<number>((resolve) => {
@@ -192,67 +186,52 @@ describe('headless runner', () => {
         exit: resolve,
       } satisfies HeadlessIo)
     })
-    ctx.provide('apiProxy', {
-      sessions: {
-        create: (request: RpcShapedRequest) =>
-          Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
-        prompt: (request: RpcShapedRequest) =>
-          Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } }),
+    ctx.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
+    ctx.provide('sessions', { flush: () => Promise.resolve(true) } as never)
+    const rejected = {
+      then(_resolve: (value: never) => void, reject: (reason: unknown) => void): void {
+        reject('factory exploded')
       },
-      events: {
-        // Synchronous throw: the SSE response never forms, so the client-side
-        // iterable rejects — the runner's own catch path, not a carrier frame.
-        mux: () => { throw new Error('channel exploded') },
-      },
-    } as never)
-    ctx.provide('httpServer', { port: 1 } as never)
+    }
+    ctx.provide('agents', { create: () => rejected } as never)
     apply(ctx, { task: 't' })
-    await new Promise(resolve => setTimeout(resolve, 10))
-    ctx.emit('agent/status', { agent: { id: 'S1', session: { seq: nextSeq + 1 } } as Agent, status: 'idle' })
     expect(await exited).toBe(1)
-    expect(err).toContain('event stream failed')
+    expect(err).toBe('dsh: factory exploded\n')
     await ctx.fiber.dispose()
   })
 
-  it('waits for Loader settlement and abandons the run when the tree died during it', async () => {
+  it('abandons a run when the tree is disposed during Loader settlement', async () => {
     const ctx = new Context()
-    let err = ''
     let exited = false
     ctx.provide('headlessIo', {
       stdout: { write: () => true },
-      stderr: { write: (chunk: string) => { err += chunk; return true } },
+      stderr: { write: () => true },
       exit: () => { exited = true },
     } satisfies HeadlessIo)
-    ctx.provide('apiProxy', scriptedApi([]) as never)
-    // The webserver is provided by a child fiber whose disposal (early
-    // SIGTERM during the boot window) removes the service; settlement
-    // resolves only afterwards, and the runner must abandon rather than
-    // crash on the torn-down port read.
-    const webserverFiber = ctx.plugin((childCtx: Context) => {
-      childCtx.provide('httpServer', { port: 1 } as never)
+    const services = ctx.plugin((child: Context) => {
+      child.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
+      child.provide('sessions', {} as never)
+      child.provide('agents', {} as never)
     })
-    await webserverFiber
+    await services
     let release: () => void
     const settlement = new Promise<void>((resolve) => { release = resolve })
     ctx.provide('loader', { await: () => settlement } as never)
     apply(ctx, { task: 't' })
-    await webserverFiber.dispose()
+    await services.dispose()
     release!()
     await new Promise(resolve => setTimeout(resolve, 10))
-    expect(err).toBe('')
     expect(exited).toBe(false)
     await ctx.fiber.dispose()
   })
 
   it('fails loud without the launcher-owned headlessIo seam', () => {
     const ctx = new Context()
-    ctx.provide('apiProxy', scriptedApi([]) as never)
-    ctx.provide('httpServer', { port: 1 } as never)
     expect(() => { apply(ctx, { task: 't' }) }).toThrow('must provide ctx.headlessIo')
   })
 
   it('validates config: the task is required', () => {
-    expect(() => new Config({ } as never)).toThrow()
+    expect(() => new Config({} as never)).toThrow()
     expect(new Config({ task: 'x' })).toEqual({ task: 'x' })
   })
 })
diff --git a/packages/bundle/headless/tsconfig.json b/packages/bundle/headless/tsconfig.json
index 7894985500..9ae3212f6b 100644
--- a/packages/bundle/headless/tsconfig.json
+++ b/packages/bundle/headless/tsconfig.json
@@ -17,15 +17,15 @@
     {
       "path": "../../../vendor/schemastery"
     },
-    {
-      "path": "../../host/apiproxy"
-    },
-    {
-      "path": "../../host/webserver"
-    },
     {
       "path": "../../core/agent"
     },
+    {
+      "path": "../../core/agent-default-model"
+    },
+    {
+      "path": "../../llm/llm"
+    },
     {
       "path": "../../core/session"
     },
diff --git a/packages/bundle/web-app/README.i18n.yaml b/packages/bundle/web-app/README.i18n.yaml
index 25bf18dc45..35f9bb4286 100644
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/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/bundle/web-app/README.md
-README.md: dc35cb4b596b265b70cea81aa5d6784fc1eff65b
-README.zh.md: bd14fe03d222f788563df0b562f86446df70b827
+README.md: d89ae4a7e28506166498caf0032f864bbb109cc5
+README.zh.md: 3c02ed81b0d34d0f8ec597e9dbea2690151ea5e3
diff --git a/packages/bundle/web-app/README.md b/packages/bundle/web-app/README.md
index dc35cb4b59..d89ae4a7e2 100644
--- a/packages/bundle/web-app/README.md
+++ b/packages/bundle/web-app/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, and mounts this package's own `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, lanAddresses}`). That plugin owns what used to be launcher code: it resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports (workspace knowledge of this bundle, never user config), mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the web-surface prompt section and the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses` and the flag family over these rows; [`dsh-headless`](../headless/README.md) layers on top, silences the URL line, and disables the surface context.
+The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, and mounts this package's `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, lanAddresses}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports, mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the web-surface prompt section and the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses` and the flag family over these rows. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.
 
 ## Model Experience
 
diff --git a/packages/bundle/web-app/README.zh.md b/packages/bundle/web-app/README.zh.md
index bd14fe03d2..3c02ed81b0 100644
--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包自己的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, lanAddresses}`）。该插件接管了原先属于启动器的代码：它通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist（这是本组合包的 workspace 知识，绝不是用户配置），在其上挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses` 与相应 flag 家族 patch 到这些行上；[`dsh-headless`](../headless/README.md) 再叠加一层，关闭 URL 行并禁用表层上下文。
+dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, lanAddresses}`）。该插件通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses` 与相应 flag 家族 patch 到这些行上。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。
 
 ## 模型体验
 
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 62ed35bd49..d4fb2e8511 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -72,13 +72,9 @@
       name: '@deepseek-ai/dsh-host-directory-picker-auto'
 
     # The API gateway: the transport-agnostic dispatch face every client shape
-    # shares. provider/model are the host default routing — the profile json's
-    # mapping target (user config overrides these engineering defaults).
+    # shares. The base layer's agent-default-model service owns the default model.
     - id: api-gateway
       name: '@deepseek-ai/dsh-host-apiproxy'
-      config:
-        provider: deepseek-official
-        model: deepseek-v4-flash
 
     # ── layer 2: transport/service ──────────────────────────────────────────────
 
diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts
index 6f29b2dda0..c373376710 100644
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -12,7 +12,7 @@ export type {
   WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
   ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels,
+  ModelReasoningEffort, ModelSelection, QueueAction, QueuedInboxItem, SessionModels,
   GoalsApi, GoalRef,
   SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView,
   CredentialsApi, CredentialView, ConfigurableProviderView, DiscoveredModelView, LlmApi,
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 2a081284b2..24f5668d42 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -30,7 +30,7 @@ import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import { deriveEventMessage, foldSurface } from '@deepseek-ai/dsh-session/surface'
 import type {
   ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
-  ModelProviderGroup, ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
+  ModelProviderGroup, ModelSelection, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
   ToolCallView, ToolEventView, ToolResultView, WorkspaceId, WorkspaceView,
 } from './api.ts'
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -1347,7 +1347,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     { sessionId: sid('fx-gamma'), updatedAt: Date.now() - 120_000, running: false, blank: false, cwd: '/tmp/fixture' },
   ]
   const logs = new Map<SessionId, SessionEvent[]>([[sid('fx-alpha'), buildAlphaLog()]])
-  const modelTargets = new Map<SessionId, ModelTarget>(sessions.map(session => [
+  const modelSelections = new Map<SessionId, ModelSelection>(sessions.map(session => [
     session.sessionId,
     { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
   ]))
@@ -1989,7 +1989,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
           sessionId: requestedId ?? sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, blank: true, cwd,
         }
         sessions.push(created)
-        modelTargets.set(created.sessionId, { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+        modelSelections.set(created.sessionId, { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
         attachedSessions += 1
         const emitSession = (): void => {
           // Mirrors the host: the frame fires at creation, so blank is constantly true.
@@ -2098,7 +2098,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         return ok(request, { ...page, ...projections === undefined ? {} : { projections } })
       },
       models: request => ok(request, {
-        current: modelTargets.get(request.payload.sessionId)
+        current: modelSelections.get(request.payload.sessionId)
           ?? { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
         // The fixture's routes all serve; a surface exercising the blocked
         // posture drives it through its own stub.
@@ -2107,14 +2107,14 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         failures: [],
       }),
       selectModel: (request) => {
-        const selected: ModelTarget = {
+        const selected: ModelSelection = {
           provider: request.payload.provider,
           model: request.payload.model,
           ...request.payload.reasoningEffort === undefined
             ? {}
             : { reasoningEffort: request.payload.reasoningEffort },
         }
-        modelTargets.set(request.payload.sessionId, selected)
+        modelSelections.set(request.payload.sessionId, selected)
         return ok(request, { selected })
       },
       prompt: (request) => {
@@ -2153,11 +2153,11 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         // Capacity parallel of the host token-meter's request/context record:
         // log-only, appended inside the open turn, and deduplicated against the
         // route already recorded (the fixture never varies contextWindow).
-        const target = modelTargets.get(id) ?? { provider: 'deepseek', model: 'deepseek-v4-flash' }
-        if (lastRequestContext(logOf(id))?.model !== target.model) {
+        const selection = modelSelections.get(id) ?? { provider: 'deepseek', model: 'deepseek-v4-flash' }
+        if (lastRequestContext(logOf(id))?.model !== selection.model) {
           append(id, {
             type: 'request/context',
-            data: { provider: target.provider, model: target.model, contextWindow: 128_000 },
+            data: { provider: selection.provider, model: selection.model, contextWindow: 128_000 },
           })
         }
         startReply(
@@ -2167,9 +2167,9 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
             ? MARKDOWN_FIXTURE
             : userText === 'report model'
               ? (() => {
-                const target = modelTargets.get(id)
-                return `当前模型：${target?.provider ?? 'unknown'}/${target?.model ?? 'unknown'}`
-                  + (target?.reasoningEffort === undefined ? '' : ` · 推理等级：${target.reasoningEffort}`)
+                const selection = modelSelections.get(id)
+                return `当前模型：${selection?.provider ?? 'unknown'}/${selection?.model ?? 'unknown'}`
+                  + (selection?.reasoningEffort === undefined ? '' : ` · 推理等级：${selection.reasoningEffort}`)
               })()
               : `回声：${userText}。这是 fixture 的流式回复，用于验证打字机增长与定稿切换。`,
         )
diff --git a/packages/client/connection/src/client/index.ts b/packages/client/connection/src/client/index.ts
index c2a6668d46..e14a0764a8 100644
--- a/packages/client/connection/src/client/index.ts
+++ b/packages/client/connection/src/client/index.ts
@@ -20,7 +20,7 @@ export type {
   ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
   ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  MessageId, ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels,
+  MessageId, ModelReasoningEffort, ModelSelection, QueueAction, QueuedInboxItem, SessionModels,
   SubagentsApi, SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt,
   RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
   ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
diff --git a/packages/client/connection/tests/fake-api.ts b/packages/client/connection/tests/fake-api.ts
index ef5071316e..c61b97833b 100644
--- a/packages/client/connection/tests/fake-api.ts
+++ b/packages/client/connection/tests/fake-api.ts
@@ -3,7 +3,7 @@
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
-  CommandDescriptor, HostFrame, IApiClient, ModelTarget, MuxFrame,
+  CommandDescriptor, HostFrame, IApiClient, ModelSelection, MuxFrame,
   RpcRequest, RpcResponse, SessionId, SessionModels, SessionSearchItem, SkillEntry,
 } from '../src/client/api.ts'
 import { RpcId } from '../src/client/api.ts'
@@ -50,11 +50,11 @@ export class FakeApiClient implements IApiClient {
   onRename: (payload: unknown) => Promise<RpcResponse<{ title: string; seq: number }>> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 }))
   onFork: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
-  => Promise<RpcResponse<{ events: never[]; hasMore: boolean; modelTarget: ModelTarget }>> =
+  => Promise<RpcResponse<{ events: never[]; hasMore: boolean; modelSelection: ModelSelection }>> =
     () => Promise.resolve(ok({
       events: [],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-chat' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-chat' },
     }))
 
   onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
@@ -63,8 +63,8 @@ export class FakeApiClient implements IApiClient {
     groups: [],
     failures: [],
   }))
-  onSelectModel: (payload: ModelTarget & { sessionId: SessionId })
-  => Promise<RpcResponse<{ selected: ModelTarget }>> =
+  onSelectModel: (payload: ModelSelection & { sessionId: SessionId })
+  => Promise<RpcResponse<{ selected: ModelSelection }>> =
     payload => Promise.resolve(ok({ selected: { provider: payload.provider, model: payload.model } }))
   onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
   onUpdateQueue: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
@@ -105,7 +105,7 @@ export class FakeApiClient implements IApiClient {
     history: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number }) =>
       this.record('session.history', payload, this.onHistory(payload)),
     models: (payload: unknown) => this.record('session.models', payload, this.onModels(payload)),
-    selectModel: (payload: ModelTarget & { sessionId: SessionId }) =>
+    selectModel: (payload: ModelSelection & { sessionId: SessionId }) =>
       this.record('session.selectModel', payload, this.onSelectModel(payload)),
     rename: (payload: unknown) => this.record('session.rename', payload, this.onRename(payload)),
     fork: (payload: unknown) => this.record('session.fork', payload, this.onFork(payload)),
diff --git a/packages/client/connection/tests/fixture.spec.ts b/packages/client/connection/tests/fixture.spec.ts
index f608190936..53b68ca786 100644
--- a/packages/client/connection/tests/fixture.spec.ts
+++ b/packages/client/connection/tests/fixture.spec.ts
@@ -168,7 +168,7 @@ describe('createFixtureApi', () => {
     })
   })
 
-  it('serves grouped models and keeps a selected target for later history and fixture requests', async () => {
+  it('serves grouped models and keeps a selection for later history and fixture requests', async () => {
     const api = createFixtureApi()
     const sessionId = sid('fx-alpha')
     const catalog = await api.sessions.models(req({ sessionId }))
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index f9af3fb8fe..930a12dea3 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: a9b604974595b1b7856f74b72d36093491ec1bd1
-README.zh.md: 41c81532667f445ce1c52e1b84185ef503e82141
+README.md: c2ce461439a89aa4fe2d59ebf92d14539479dac8
+README.zh.md: bca93b80989152eccccaf13c0f31435c91e7393c
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index a9b6049745..c2ce461439 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -62,7 +62,7 @@ The Session object validates plugin-owned, provider-routed `llm/retry` payloads
 
 ## Session model selection
 
-Each resident `Session` owns a `modelSelection` snapshot containing the current provider/model target, provider-grouped directory, provider-local failures, and the `idle`/`loading`/`ready`/`selecting`/`error` state. History establishes or refreshes the current target, opening a selector refreshes the directory, and selection failures preserve the last target and usable groups. Directory and selection operations share a monotonically increasing generation so an older response cannot overwrite a newer selection. A reconnect rebuild restores the target reported by the Host without replacing unchanged selection substructure.
+Each resident `Session` owns a `modelSelection` snapshot containing the current `ModelSelection`, provider-grouped directory, provider-local failures, and the `idle`/`loading`/`ready`/`selecting`/`error` state. History establishes or refreshes the current selection, opening a selector refreshes the directory, and selection failures preserve the last selection and usable groups. Directory and selection operations share a monotonically increasing generation so an older response cannot overwrite a newer selection. A reconnect rebuild restores the selection reported by the Host without replacing unchanged selection substructure.
 
 ## Model Experience
 
@@ -70,7 +70,7 @@ None, as the session object layer selects the provider/model route used by a lat
 
 #### KV Cache effect
 
-Changing the target can change or invalidate provider-side cache reuse; this package does not alter the prompt prefix itself.
+Changing the model selection can change or invalidate provider-side cache reuse; this package does not alter the prompt prefix itself.
 
 ## Known Limitations and Deferred Work
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 41c8153266..bca93b8098 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -62,7 +62,7 @@ Session 对象会在事件 wire 边界依据生产方的完整字段约定，验
 
 ## 会话模型选择
 
-每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前提供方/模型目标、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前目标，打开选择器会刷新目录；选择失败会保留上一个目标和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的目标，同时不替换未变化的选择子结构。
+每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前 `ModelSelection`、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前选择，打开选择器会刷新目录；选择失败会保留上一个选择和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的选择，同时不替换未变化的选择子结构。
 
 ## 模型体验
 
@@ -70,7 +70,7 @@ Session 对象会在事件 wire 边界依据生产方的完整字段约定，验
 
 #### KV Cache 影响
 
-更改目标可能改变提供方侧的缓存复用，或使其失效；该包本身不会改变提示词前缀。
+更改模型选择可能改变提供方侧的缓存复用，或使其失效；该包本身不会改变提示词前缀。
 
 ## 已知限制与暂缓事项
 
diff --git a/packages/client/runtime/tests/fake-api.ts b/packages/client/runtime/tests/fake-api.ts
index 5e510c0012..80f45db067 100644
--- a/packages/client/runtime/tests/fake-api.ts
+++ b/packages/client/runtime/tests/fake-api.ts
@@ -3,7 +3,7 @@
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
-  ClientResponse, CommandDescriptor, HostFrame, IApiClient, ModelTarget, MuxFrame,
+  ClientResponse, CommandDescriptor, HostFrame, IApiClient, ModelSelection, MuxFrame,
   RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId, SessionModels, SessionSearchItem, SkillEntry,
   WorkspaceId, WorkspaceView,
 } from '@deepseek-ai/dsh-client-connection/client'
@@ -64,7 +64,7 @@ export class FakeApiClient implements IApiClient {
   onSearch: (payload: unknown) => Promise<RpcResponse<{ items: SessionSearchItem[]; hasMore: boolean }>> =
     () => Promise.resolve(ok({ items: [], hasMore: false }))
   onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
-  readonly defaultModel: ModelTarget = { provider: 'deepseek-official', model: 'deepseek-v4-flash' }
+  readonly defaultModel: ModelSelection = { provider: 'deepseek-official', model: 'deepseek-v4-flash' }
   onRename: (payload: unknown) => Promise<RpcResponse<{ title: string; seq: number }>> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 }))
   onFork: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
@@ -82,7 +82,7 @@ export class FakeApiClient implements IApiClient {
     failures: [],
   }))
   onSelectModel: (payload: { provider: string; model: string }) =>
-  Promise<RpcResponse<{ selected: ModelTarget }>> =
+  Promise<RpcResponse<{ selected: ModelSelection }>> =
     payload => Promise.resolve(ok({ selected: { provider: payload.provider, model: payload.model } }))
   onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
   onUpdateQueue: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
diff --git a/packages/client/runtime/tests/manager.spec.ts b/packages/client/runtime/tests/manager.spec.ts
index e203e49dd9..c69465df45 100644
--- a/packages/client/runtime/tests/manager.spec.ts
+++ b/packages/client/runtime/tests/manager.spec.ts
@@ -842,7 +842,7 @@ describe('connected generation', () => {
     api.onHistory = () => Promise.resolve(ok({
       events: entries(plainTurn(0, 0, 'a', 'b')) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-chat' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-chat' },
     }))
     const manager = new SessionManager(api)
     const openedSession = manager.get(S1)
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index 5d5f292f92..834f37d434 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -89,7 +89,7 @@ describe('open', () => {
     gate.resolve(ok({
       events: entries(page) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }))
     await opening
     const seqs = session.getSnapshot().nodes.map(n => n.seq)
@@ -631,7 +631,7 @@ describe('paging', () => {
     gate.resolve(ok({
       events: entries(plainTurn(0, 0, 'a', 'b')) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }))
     await Promise.all([first, second])
     expect(api.callsOf('session.history')).toHaveLength(2) // open + one page, not two
@@ -1018,7 +1018,7 @@ describe('remaining branches', () => {
     stale.resolve(ok({
       events: entries(plainTurn(0, 0, '旧', '代')) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'stale' },
+      modelSelection: { provider: 'deepseek-official', model: 'stale' },
     })) // success, but its generation is gone
     await Promise.all([opening, resynced])
     expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9]) // only the fresh generation's window
@@ -1041,7 +1041,7 @@ describe('remaining branches', () => {
     secondPull.resolve(ok({
       events: entries([...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'stale' },
+      modelSelection: { provider: 'deepseek-official', model: 'stale' },
     }))
     await Promise.all([opening, resynced])
     expect(session.getSnapshot().openState).toBe('open')
@@ -1059,7 +1059,7 @@ describe('remaining branches', () => {
     repairPull.resolve(ok({
       events: entries(plainTurn(0, 0, '旧', '页')) as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'stale' },
+      modelSelection: { provider: 'deepseek-official', model: 'stale' },
     })) // repair result: stale, dropped
     await resynced
     expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9])
@@ -1104,7 +1104,7 @@ describe('remaining branches', () => {
         { event: ev.toolResult(7, 1, 'h1', 'done'), view: { for: 'result', view: { card: 'generic', title: '历史果' } } },
       ] as never[],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }))
     await session.open()
     expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml
index a909395148..e630daf0fa 100644
--- a/packages/client/ui-model/README.i18n.yaml
+++ b/packages/client/ui-model/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/client/ui-model/README.md
-README.md: 5a6f998476629566d35af32efa5d8bc5072a872b
-README.zh.md: 55ea296370ffa986c9b11b41f83ef83b12236e88
+README.md: b37f807944850fb34331cd8d78b4a2ccf157f21c
+README.zh.md: 906096bed06af26517e215b2d1e1da4b62e58095
diff --git a/packages/client/ui-model/README.md b/packages/client/ui-model/README.md
index 5a6f998476..b37f807944 100644
--- a/packages/client/ui-model/README.md
+++ b/packages/client/ui-model/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Model selection plugin, browser half: TWO entries over ONE per-session directory owned by `ModelService` (`ctx.models`). For ordinary sessions, the `/model` popupSelect contribution (registered through `ctx.command`) and the composer's named `conversation.input.model` seat both load the session's advisory directory through `session.models` and submit through `session.selectModel` via the same `ModelDirectory` instance. The compact composer trigger opens a two-level Model/Effort menu: models stay provider-grouped, while the selected exact model supplies its adapter-owned effort names, descriptions, and default. `/model` applies the selected model's default effort, and the composer can then choose any advertised effort.
 
-The Host-reported provider/model/reasoning target is the single selection fact, but it is echoed only when the exact route remains in the advertised groups; removing that catalog row leaves the routable target intact while the trigger prompts `Select model`, no stale row is synthesized, and no Effort row is shown until the user picks an advertised model. Directory loads and selections share a generation counter so an older response never overwrites a newer one; a connection reset drops every resident projection and repulls the Host-restored target before display. Provider-local metadata failures list inline while usable groups stay selectable, and selection failures retain the prior target and directory.
+The Host-reported provider/model/reasoning `ModelSelection` is the single selection fact, but it is echoed only when the exact provider/model pair remains in the advertised groups; an absent catalog row leaves the routable selection intact while the trigger prompts `Select model`, no stale row is synthesized, and no Effort row is shown until the user picks an advertised model. Directory loads and selections share a generation counter so an older response never overwrites a newer one; a connection reset drops every resident projection and repulls the Host-restored selection before display. Provider-local metadata failures list inline while usable groups stay selectable, and selection failures retain the prior selection and directory.
 
 When the Host reports that no adapter serves the session's route (`session.models.routable`), this plugin raises a composer block through `ctx.conversation.blocks` and the input goes inert with this plugin's own copy; recovering clears it without a reload. It follows `routable` and nothing else: a `null` — before the first load, or after one failed — never blocks, or a slow Host would lock a working composer, and catalog membership never blocks either, because a route serving a model it stopped advertising is missing from the groups yet perfectly usable. The trigger's own `Select model` fallback still covers that case, which is display, not a gate.
 
@@ -14,7 +14,7 @@ The `/client` export surface is the plugin body (`apply`/`inject`), `ModelServic
 
 ## Model Experience
 
-Indirectly, through the `session.selectModel` RPC available to ordinary sessions, both entries submit the provider/model/reasoning target that the Host snapshots at the next prompt-assembly boundary, so the following request uses the chosen route and effort while a running step keeps its assembled target; the selection becomes durable only when the existing request header records a request that consumes it, and menu interaction adds no prompt content.
+Indirectly, through the `session.selectModel` RPC available to ordinary sessions, both entries submit the complete `ModelSelection` that the Host snapshots at the next prompt-assembly boundary, so the following request uses the selected provider, model, and effort while a running step keeps its assembled selection; the selection becomes durable only when the existing request header records a request that consumes it, and menu interaction adds no prompt content.
 
 #### KV Cache effect
 
@@ -22,6 +22,6 @@ Switching the route can reduce or invalidate provider-side cache reuse for subse
 
 ## Known Limitations and Deferred Work
 
-- **No create-time or addressed-subagent selection** — both entries require an existing ordinary session's Agent; there is no draft-phase model choice to fold into session creation, and subagent continuation deliberately exposes no independent model-retargeting contract.
+- **No create-time or addressed-subagent selection** — both entries require an existing ordinary session's Agent; there is no draft-phase model choice to fold into session creation, and subagent continuation deliberately exposes no independent model-selection contract.
 - **Directory names are presentation-only** — selection and persistence use provider/model/effort ids; a provider whose catalog or exact-model metadata lookup fails lists as an unselectable failure row until reload.
 - **No arbitrary effort input** — the composer offers only the exact model's adapter-advertised levels; an adapter without reasoning metadata leaves the Effort row absent.
diff --git a/packages/client/ui-model/README.zh.md b/packages/client/ui-model/README.zh.md
index 55ea296370..906096bed0 100644
--- a/packages/client/ui-model/README.zh.md
+++ b/packages/client/ui-model/README.zh.md
@@ -4,7 +4,7 @@
 
 模型选择插件（浏览器侧）：**两个入口共用一份会话级目录**，由 `ModelService`（`ctx.models`）持有。对于普通会话，`/model` popupSelect 贡献项（经 `ctx.command` 注册）与 composer 的具名 `conversation.input.model` slot 都通过同一个 `ModelDirectory` 实例，经 `session.models` 加载会话的建议目录，并经 `session.selectModel` 提交。紧凑型 composer 触发器会打开两级 Model/Effort 菜单：模型仍按提供方分组，所选具体模型则提供由其适配器持有的推理强度名称、说明和默认值。`/model` 应用所选模型的默认推理强度，composer 随后可以选择任一已公布的推理强度。
 
-Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择事实，但只有当该精确路由仍在已公布分组中时才会回显；删除该目录行会保留仍可路由的目标，但触发器会提示 `Select model`，系统不会合成陈旧行，且在用户选择已公布的模型之前不会显示 Effort 行。目录加载与选择共享一个代次计数器，旧响应不会覆盖新结果；连接重置会丢弃所有常驻目录投影，并在显示前重新拉取 Host 恢复的目标。各提供方的元数据获取失败会内联列出，同时可用分组仍可选择；选择失败会保留先前的目标和目录。
+Host 报告的 `ModelSelection` 是唯一的选择事实，其中包含提供方、模型与推理（reasoning）强度；但只有当该提供方／模型对仍在已公布分组中时才会回显。目录行缺席时，可路由的选择保持不变，但触发器会提示 `Select model`；系统不会合成陈旧行，且在用户选择已公布的模型之前不会显示 Effort 行。目录加载与选择共享一个代次计数器，旧响应不会覆盖新结果；连接重置会丢弃所有常驻目录投影，并在显示前重新拉取 Host 恢复的选择。各提供方的元数据获取失败会内联列出，同时可用分组仍可选择；选择失败会保留先前的选择和目录。
 
 当宿主报告没有适配器服务该会话的路由（`session.models.routable`）时，本插件经 `ctx.conversation.blocks` 注册一个 composer 阻塞块，输入框随之停用并显示本插件自己的文案；恢复后无需重新加载即自动清除。它只跟随 `routable`：`null`（首次加载之前，或加载失败之后）绝不阻断，否则一个慢的宿主就会锁死一个本来可用的 composer；目录成员关系同样不阻断，因为一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用。触发器自己的 `Select model` 回退仍然覆盖那种情形——那是显示，不是闸门。
 
@@ -14,7 +14,7 @@ Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择
 
 ## 模型体验
 
-间接影响。两个入口都通过仅供普通会话使用的 `session.selectModel` RPC 提交提供方／模型／推理强度目标；Host 会在下一次提示词组装边界对该目标进行快照，因此后续请求采用所选路由和推理强度，而运行中的步骤保留已组装目标。只有当现有请求头记录一次实际采用该选择的请求后，选择才会持久化；菜单交互不会添加提示词内容。
+间接影响。两个入口都通过仅供普通会话使用的 `session.selectModel` RPC 提交完整的 `ModelSelection`；Host 会在下一次提示词组装边界对其进行快照，因此后续请求采用所选提供方、模型与推理强度，而运行中的步骤保留已组装选择。只有当现有请求头记录一次实际采用该选择的请求后，选择才会持久化；菜单交互不会添加提示词内容。
 
 #### KV Cache 影响
 
@@ -22,6 +22,6 @@ Host 报告的提供方／模型／推理（reasoning）目标是唯一的选择
 
 ## 已知限制与暂缓事项
 
-- **无创建期或已寻址 subagent 选择**——两个入口都要求既有普通会话的 agent；没有可纳入会话创建的草稿阶段模型选择，subagent 继续执行也有意不公开独立更改模型目标的约定。
+- **无创建期或已寻址 subagent 选择**——两个入口都要求既有普通会话的 agent；没有可纳入会话创建的草稿阶段模型选择，subagent 继续执行也有意不公开独立的模型选择约定。
 - **目录名仅供呈现**——选择与持久化使用提供方／模型／推理强度 id；目录查询或确切模型元数据查询失败的提供方以不可选失败行列出，重新加载前保持原样。
 - **不能任意输入推理强度**——composer 仅提供确切模型由适配器公布的推理强度；适配器没有推理元数据时不显示 Effort 行。
diff --git a/packages/client/ui-model/src/client/ModelSelect.tsx b/packages/client/ui-model/src/client/ModelSelect.tsx
index 343243a28c..6b7bfd19b9 100644
--- a/packages/client/ui-model/src/client/ModelSelect.tsx
+++ b/packages/client/ui-model/src/client/ModelSelect.tsx
@@ -14,7 +14,7 @@ import {
   type KeyboardEvent, type FocusEvent,
 } from 'react'
 import clsx from 'clsx'
-import type { ModelReasoningEffort, ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelReasoningEffort, ModelSelection } from '@deepseek-ai/dsh-client-connection/client'
 import {
   IconCheckOutline16, IconChevronDownOutline14, IconChevronRightOutline14,
 } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -58,17 +58,17 @@ export function ModelSelect(
     group.models.map(model => ({
       group,
       model,
-      target: {
+      selection: {
         provider: group.id,
         model: model.id,
         ...model.reasoning?.defaultEffort === undefined
           ? {}
           : { reasoningEffort: model.reasoning.defaultEffort },
-      } satisfies ModelTarget,
+      } satisfies ModelSelection,
     }))), [state.groups])
   const selectedIndex = state.current === null
     ? -1
-    : choices.findIndex(c => c.target.provider === state.current?.provider && c.target.model === state.current.model)
+    : choices.findIndex(c => c.selection.provider === state.current?.provider && c.selection.model === state.current.model)
   const currentChoice = choices[selectedIndex]
   const reasoning = currentChoice?.model.reasoning
   const effectiveEffort = state.current?.reasoningEffort ?? reasoning?.defaultEffort
@@ -148,12 +148,12 @@ export function ModelSelect(
     close()
   }
 
-  const choose = (target: ModelTarget): void => {
-    if (state.current?.provider === target.provider && state.current.model === target.model) {
+  const choose = (selection: ModelSelection): void => {
+    if (state.current?.provider === selection.provider && state.current.model === selection.model) {
       close(true)
       return
     }
-    void select(target).then((accepted) => {
+    void select(selection).then((accepted) => {
       if (accepted && rootRef.current !== null) close(true)
     })
   }
@@ -164,12 +164,12 @@ export function ModelSelect(
       close(true)
       return
     }
-    const target: ModelTarget = {
+    const selection: ModelSelection = {
       provider: state.current.provider,
       model: state.current.model,
       ...effort === undefined ? {} : { reasoningEffort: effort },
     }
-    void select(target).then((accepted) => {
+    void select(selection).then((accepted) => {
       if (accepted && rootRef.current !== null) close(true)
     })
   }
diff --git a/packages/client/ui-model/src/client/directory.ts b/packages/client/ui-model/src/client/directory.ts
index 8432cf1b77..1555a2df43 100644
--- a/packages/client/ui-model/src/client/directory.ts
+++ b/packages/client/ui-model/src/client/directory.ts
@@ -6,17 +6,17 @@
  * either entry is what the other shows next.
  */
 import type {
-  IApiClient, ModelCatalogFailure, ModelProviderGroup, ModelTarget, SessionId, SessionModels,
+  IApiClient, ModelCatalogFailure, ModelProviderGroup, ModelSelection, SessionId, SessionModels,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 
 /** Directory snapshot both entries render from. */
 export interface ModelDirectoryState {
-  /** Target the host reports for the next assembled step; null before the first load. */
-  current: ModelTarget | null
+  /** Model selection the host reports for the next assembled step; null before the first load. */
+  current: ModelSelection | null
   /**
-   * Whether an adapter serves the current target's route, as the host reports
+   * Whether an adapter serves the current selection's provider, as the host reports
    * it — null before the first load, which is NOT the same as blocked. Read
    * this rather than "current matches no group": catalog membership is
    * advisory, so a route serving a model it stopped advertising is missing
@@ -57,7 +57,7 @@ export class ModelDirectory {
 
   /**
    * Refresh the advisory directory (both entries call this on open).
-   * Failure preserves the last good groups and current target.
+   * Failure preserves the last good groups and current selection.
    * @returns the fresh directory value.
    */
   async load(): Promise<SessionModels> {
@@ -86,22 +86,22 @@ export class ModelDirectory {
   }
 
   /**
-   * Select the complete provider/model/reasoning target (both entries submit through here). Success
+   * Select the complete provider/model/reasoning selection (both entries submit through here). Success
    * updates the shared current; failure surfaces on the store and throws so
    * each entry's own retry surface engages.
-   * @param target - provider, provider-owned model id, and optional adapter-owned effort.
-   */
-  async select(target: ModelTarget): Promise<void> {
+   * @param selection - provider, provider-owned model id, and optional adapter-owned effort.
+ */
+  async select(selection: ModelSelection): Promise<void> {
     this.assertAvailable()
     const generation = ++this.generation
     this.store.update((s) => { s.status = 'selecting'; s.error = null })
     const { result } = await this.sessions.selectModel({
       sessionId: this.sessionId,
-      provider: target.provider,
-      model: target.model,
-      ...target.reasoningEffort === undefined
+      provider: selection.provider,
+      model: selection.model,
+      ...selection.reasoningEffort === undefined
         ? {}
-        : { reasoningEffort: target.reasoningEffort },
+        : { reasoningEffort: selection.reasoningEffort },
     })
     if (this.disposed || generation !== this.generation) {
       if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message}`)
@@ -124,7 +124,7 @@ export class ModelDirectory {
   /**
    * Drop the previous Host generation's projection and repull it. Clearing
    * first prevents an unconsumed process-local selection from being displayed
-   * while the restarted Host has restored the last logged request target.
+   * while the restarted Host has restored the last logged model selection.
    */
   resetConnected(): void {
     if (this.disposed) return
diff --git a/packages/client/ui-model/src/client/index.ts b/packages/client/ui-model/src/client/index.ts
index 68a82bd20a..f55cb83c1c 100644
--- a/packages/client/ui-model/src/client/index.ts
+++ b/packages/client/ui-model/src/client/index.ts
@@ -4,14 +4,14 @@
  * contribution and the composer's named `conversation.input.model` seat both
  * load the session's provider-grouped advisory directory (`session.models`)
  * and submit through `session.selectModel` via the same directory instance,
- * so the host-reported current target is the single fact both surfaces echo
+ * so the host-reported current selection is the single fact both surfaces echo
  * — a switch made in either entry is what the other shows next. Failures
  * ride each entry's own retry surface (popup shell error/retry; seat menu
  * inline error) without forking the state. Addressed subagent sessions expose
  * neither entry because those Agent-bound RPCs would activate persisted
  * history outside the direct-parent continuation seam.
  */
-import type { ModelTarget, SessionModels } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelSelection, SessionModels } from '@deepseek-ai/dsh-client-connection/client'
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { CommandServiceContract, SelectOption } from '@deepseek-ai/dsh-client-ui-command/client'
 // Type-only: pulls the ui-conversation SlotMap merge (the input.model seat).
@@ -68,13 +68,13 @@ function optionsOf(directory: SessionModels, t: TranslateNS<'model'>): SelectOpt
 }
 
 /**
- * Resolve a picked row back to its target by matching against the loaded
+ * Resolve a picked row back to its model selection by matching against the loaded
  * groups (the same data the rows were built from — ids stay opaque).
  * @param state - the session's directory snapshot.
  * @param id - the picked row id.
- * @returns the row's target, or undefined for failure rows / stale ids.
+ * @returns the row's model selection, or undefined for failure rows / stale ids.
  */
-function targetOf(state: ModelDirectoryState, id: string): ModelTarget | undefined {
+function selectionOf(state: ModelDirectoryState, id: string): ModelSelection | undefined {
   for (const group of state.groups) {
     for (const model of group.models) {
       if (rowId(group.id, model.id) !== id) continue
@@ -139,11 +139,11 @@ export function apply(ctx: ClientContext): void {
             throw new Error('model selection is unavailable for addressed subagent sessions')
           }
           const directory = models.directoryFor(session.sessionId)
-          const target = targetOf(directory.store.getSnapshot(), option.id)
-          if (target === undefined) {
+          const selection = selectionOf(directory.store.getSnapshot(), option.id)
+          if (selection === undefined) {
             throw new Error('this provider\'s catalog failed to load — pick a model from a loaded group')
           }
-          await directory.select(target)
+          await directory.select(selection)
         },
       },
     }), 'ui-model: /model contribution')
@@ -165,8 +165,8 @@ export function apply(ctx: ClientContext): void {
           load: () => {
             if (available) directory.load().catch(() => { /* surfaced on the store */ })
           },
-          select: (target: ModelTarget) => available
-            ? directory.select(target).then(() => true, () => false)
+          select: (selection: ModelSelection) => available
+            ? directory.select(selection).then(() => true, () => false)
             : Promise.resolve(false),
         }
       },
diff --git a/packages/client/ui-model/src/client/slots.ts b/packages/client/ui-model/src/client/slots.ts
index 3d408de232..e3e3957726 100644
--- a/packages/client/ui-model/src/client/slots.ts
+++ b/packages/client/ui-model/src/client/slots.ts
@@ -4,7 +4,7 @@
  * entry; this package only contributes the single occupant, so no SlotMap
  * merge lives here.
  */
-import type { ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelSelection } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ModelDirectoryState } from './directory.ts'
 
@@ -17,9 +17,9 @@ export interface ModelSelectInjected {
   /** Refresh the advisory directory (fire-and-forget; errors land on the store). */
   load: () => void
   /**
-   * Select a complete provider/model/reasoning target through the shared route.
-   * @param target - model target and optional adapter-owned effort.
+   * Select a complete provider/model/reasoning selection.
+   * @param selection - model selection and optional adapter-owned effort.
    * @returns whether the host accepted the selection.
    */
-  select: (target: ModelTarget) => Promise<boolean>
+  select: (selection: ModelSelection) => Promise<boolean>
 }
diff --git a/packages/client/ui-model/tests/browser-plugin.spec.ts b/packages/client/ui-model/tests/browser-plugin.spec.ts
index 4fbeca5600..422ada56b3 100644
--- a/packages/client/ui-model/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-model/tests/browser-plugin.spec.ts
@@ -13,7 +13,7 @@ import { describe, expect, it } from 'vitest'
 import { createScope } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
-import type { ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelSelection } from '@deepseek-ai/dsh-client-connection/client'
 import type { CommandContribution, SelectOption } from '@deepseek-ai/dsh-client-ui-command/client'
 import type { ModelSelectInjected } from '../src/client/slots.ts'
 import { apply, inject } from '../src/client/index.ts'
@@ -55,7 +55,7 @@ const GROUPS = [{
 /** Boot the plugin over fake faces + a stateful fake host (current moves on selectModel). */
 async function bench() {
   const ctx = new Context()
-  let current: ModelTarget = { provider: 'deepseek-official', model: 'deepseek-v4-flash' }
+  let current: ModelSelection = { provider: 'deepseek-official', model: 'deepseek-v4-flash' }
   const calls = { models: 0, select: 0 }
   ctx.provide('connection', { api: { sessions: {
     models: () => {
@@ -125,7 +125,7 @@ async function bench() {
     contribution: () => contribution!,
     seat: () => seats.get('conversation.input.model')!,
     hostCurrent: () => current,
-    setHostCurrent: (target: ModelTarget) => { current = target },
+    setHostCurrent: (selection: ModelSelection) => { current = selection },
     address: (id: SessionId) => { addressed.add(id) },
     setRoutable: (next: boolean) => { routable = next },
     blockOf: (key: string) => blocks.get(sid(key)),
diff --git a/packages/client/ui-model/tests/model-select.spec.tsx b/packages/client/ui-model/tests/model-select.spec.tsx
index 75a0622ed6..1b1e1ef17c 100644
--- a/packages/client/ui-model/tests/model-select.spec.tsx
+++ b/packages/client/ui-model/tests/model-select.spec.tsx
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import type { ModelTarget } from '@deepseek-ai/dsh-client-connection/client'
+import type { ModelSelection } from '@deepseek-ai/dsh-client-connection/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ComponentProps } from 'react'
 import type { ModelDirectoryState } from '../src/client/directory.ts'
@@ -48,10 +48,10 @@ function state(overrides: Partial<ModelDirectoryState> = {}): ModelDirectoryStat
 afterEach(cleanup)
 
 describe('ModelSelect reasoning effort', () => {
-  it('renders adapter metadata and submits the effort as part of the session target', async () => {
+  it('renders adapter metadata and submits the effort as part of the session selection', async () => {
     const directory = createSnapshotStore<ModelDirectoryState>(state())
-    const select = vi.fn(async (target: ModelTarget) => {
-      directory.set(state({ current: target }))
+    const select = vi.fn(async (selection: ModelSelection) => {
+      directory.set(state({ current: selection }))
       return true
     })
     render(<ModelSelect
@@ -112,7 +112,7 @@ describe('ModelSelect reasoning effort', () => {
       .toEqual(['Default', 'Standard'])
   })
 
-  it('prompts for a new selection when the current target is no longer advertised', () => {
+  it('prompts for a selection when the current model is no longer advertised', () => {
     const directory = createSnapshotStore(state({
       current: { provider: 'deepseek-official', model: 'removed-model' },
     }))
diff --git a/packages/core/README.i18n.yaml b/packages/core/README.i18n.yaml
index ff41da1511..f3ab9dcc56 100644
--- a/packages/core/README.i18n.yaml
+++ b/packages/core/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/core/README.md
-README.md: 40a888183a9338805d83c86bab9ae16f1c7bc04f
-README.zh.md: c0a24d78cb8ff2a2b2ccc2d2a2f4294424be55b0
+README.md: 19aed9abafa8e4531d2ee31ff0442003328a9ef6
+README.zh.md: 73ed1f500799cb235a8835ffb0317370f9a0a7e6
diff --git a/packages/core/README.md b/packages/core/README.md
index 40a888183a..19aed9abaf 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The session log, system-prompt assembly, tool registry, agent vocabulary, and concrete loop that form the harness's default control spine. These are **product** packages — the stable surface plugins and consumers build against.
+The session log, system-prompt assembly, tool registry, agent vocabulary, deployment-default model selection, and concrete loop that form the harness's default control spine. These are **product** packages — the stable surface plugins and consumers build against.
 
 | Package | Role | ctx key |
 |---|---|---|
@@ -11,9 +11,10 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
 | [`system-prompt/`](system-prompt/README.md) | Prompt and tool-schema assembly registry | `ctx.systemPrompt` |
 | [`tools/`](tools/README.md) | Scoped tool registry and execution pipeline | `ctx.tools` |
 | [`agent/`](agent/README.md) | Agent interface, registry, and event vocabulary | `ctx.agents` |
+| [`agent-default-model/`](agent-default-model/README.md) | Default model selection shared by Agent front doors | `ctx.agentDefaultModel` |
 | [`agent-loop/`](agent-loop/README.md) | Default concrete agent driver | `ctx.agentLoop` |
 
-`scope` supplies the shared scoping primitive. `agent` owns the public seam, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable.
+`scope` supplies the shared scoping primitive. `agent` owns the public seam, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable. `agent-default-model` owns the deployment selection an Agent front door uses only when a session has no selection of its own.
 
 Runnable compositions belong to [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md); this group owns only the swappable spine pieces.
 
diff --git a/packages/core/README.zh.md b/packages/core/README.zh.md
index c0a24d78cb..73ed1f5007 100644
--- a/packages/core/README.zh.md
+++ b/packages/core/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-构成 harness 默认控制主干的会话日志、系统提示词组装、工具注册表、agent（智能体）词汇和具体循环。这些是**产品**包，即插件和消费方构建所依赖的稳定 surface。
+构成 harness 默认控制主干的会话日志、系统提示词组装、工具注册表、agent（智能体）词汇、部署默认模型选择和具体循环。这些是**产品**包，即插件和消费方构建所依赖的稳定 surface。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
@@ -11,9 +11,10 @@
 | [`system-prompt/`](system-prompt/README.md) | 提示词和工具 schema 组装注册表 | `ctx.systemPrompt` |
 | [`tools/`](tools/README.md) | 作用域工具注册表和执行流水线 | `ctx.tools` |
 | [`agent/`](agent/README.md) | Agent 接口、注册表和事件词汇 | `ctx.agents` |
+| [`agent-default-model/`](agent-default-model/README.md) | 各 Agent 入口共享的默认模型选择 | `ctx.agentDefaultModel` |
 | [`agent-loop/`](agent-loop/README.md) | 默认具体 agent 驱动器 | `ctx.agentLoop` |
 
-`scope` 提供共享作用域原语。`agent` 负责公开 seam，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。
+`scope` 提供共享作用域原语。`agent` 负责公开 seam，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。`agent-default-model` 负责部署选择，Agent 入口仅在会话自身没有选择时使用它。
 
 可运行组合属于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)；该分组只负责可替换的主干组件。
 
diff --git a/packages/core/agent-default-model/README.i18n.yaml b/packages/core/agent-default-model/README.i18n.yaml
new file mode 100644
index 0000000000..92c6095788
--- /dev/null
+++ b/packages/core/agent-default-model/README.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 packages/core/agent-default-model/README.md
+README.md: 02bcc9be3adee2293a20b3ae87ddaf4d52e70deb
+README.zh.md: 807b612bd25e49aa318c13c8c8dc7595a6459080
diff --git a/packages/core/agent-default-model/README.md b/packages/core/agent-default-model/README.md
new file mode 100644
index 0000000000..02bcc9be3a
--- /dev/null
+++ b/packages/core/agent-default-model/README.md
@@ -0,0 +1,25 @@
+# @deepseek-ai/dsh-agent-default-model
+
+English | [中文](README.zh.md)
+
+The deployment default used when a front door creates an Agent that has no session-local model selection. `AgentDefaultModelService` provides `ctx.agentDefaultModel`; direct front doors such as `dsh run` and Host-backed front doors such as ApiProxy read the same service instead of owning parallel provider/model defaults.
+
+The plugin config requires `{ provider, model }`. That composition entry is the base of the `agent-default-model` Settings section; a mounted settings provider layers the user's choice over it and changes are visible on the next `currentSelection()` read. `reasoningEffort` belongs to the Settings section but deliberately not to plugin config: a complete saved selection can clear an effort when the next selected model has none, while a composition value would be inherited again.
+
+- `ctx.agentDefaultModel.currentSelection()` returns a detached `{ provider, model, reasoningEffort? }` selection for a newly created Agent.
+- `ctx.agentDefaultModel.saveSelection(selection)` saves the complete user selection. Without a settings provider it is a no-op and the composition entry remains current.
+
+The service does not validate catalog membership. A provider route may serve an unadvertised model, and the consumer that actually opens a model request owns availability diagnostics.
+
+## Model Experience
+
+Indirectly, through the provider/model selection supplied to a front door; request assembly and adapters own the model-visible request.
+
+#### KV Cache effect
+
+Changing the default affects only Agents that subsequently resolve from it. An existing session whose request log already names a selection keeps that selection, so this service does not invalidate its established prefix.
+
+## Known Limitations and Deferred Work
+
+- The service owns one process-wide default; per-session selection remains the front door's responsibility.
+- Without a settings provider, `saveSelection()` cannot retain a selection for a later Agent.
diff --git a/packages/core/agent-default-model/README.zh.md b/packages/core/agent-default-model/README.zh.md
new file mode 100644
index 0000000000..807b612bd2
--- /dev/null
+++ b/packages/core/agent-default-model/README.zh.md
@@ -0,0 +1,25 @@
+# @deepseek-ai/dsh-agent-default-model
+
+[English](README.md) | 中文
+
+该部署默认值供入口在创建尚无会话级模型选择的 Agent 时使用。`AgentDefaultModelService` 提供 `ctx.agentDefaultModel`；`dsh run` 这类直接入口与 ApiProxy 这类由 Host 支撑的入口读取同一服务，而不是分别持有平行的提供方／模型默认值。
+
+插件配置必须提供 `{ provider, model }`。该组合配置项构成 Settings 中 `agent-default-model` 分节的基础层；挂载的设置提供方在其上叠加用户选择，更改会在下一次调用 `currentSelection()` 时可见。`reasoningEffort` 属于该 Settings 分节，但特意不属于插件配置：完整保存的选择必须能在下一个选定模型没有推理（reasoning）强度时清除旧值，而组合配置值会再次被继承。
+
+- `ctx.agentDefaultModel.currentSelection()` 返回一份独立的 `{ provider, model, reasoningEffort? }` 选择，供新创建的 Agent 使用。
+- `ctx.agentDefaultModel.saveSelection(selection)` 保存完整的用户选择。未挂载设置提供方时，此调用不执行任何操作，组合配置项仍为当前值。
+
+该服务不校验目录成员关系。提供方路由可以服务未在目录中公布的模型；实际发起模型请求的消费方负责可用性诊断。
+
+## 模型体验
+
+通过提供给入口的提供方／模型选择间接影响；模型可见请求由请求组装与适配器负责。
+
+#### KV Cache 影响
+
+更改默认值只影响之后从该默认值解析选择的 Agent。请求日志已经指明选择的现有会话仍沿用该选择，因此本服务不会使其已建立的前缀失效。
+
+## 已知限制与暂缓事项
+
+- 该服务只拥有一项进程级默认值；每个会话的选择仍由入口负责。
+- 未挂载设置提供方时，`saveSelection()` 无法保留选择供后续 Agent 使用。
diff --git a/packages/core/agent-default-model/package.json b/packages/core/agent-default-model/package.json
new file mode 100644
index 0000000000..d012fbea93
--- /dev/null
+++ b/packages/core/agent-default-model/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@deepseek-ai/dsh-agent-default-model",
+  "description": "Default model selection shared by Agent front doors",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-settings": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-settings": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/core/agent-default-model/src/index.ts b/packages/core/agent-default-model/src/index.ts
new file mode 100644
index 0000000000..36b3b9ba44
--- /dev/null
+++ b/packages/core/agent-default-model/src/index.ts
@@ -0,0 +1,107 @@
+/**
+ * Default model selection for an Agent without a session-specific selection.
+ *
+ * @module @deepseek-ai/dsh-agent-default-model
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import type { ModelSelection } from '@deepseek-ai/dsh-agent'
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+
+declare module 'cordis' {
+  interface Context {
+    /** Default model selection for Agents created without an explicit model. */
+    agentDefaultModel: AgentDefaultModelService
+  }
+}
+
+/** Settings namespace carrying the default model selection for future Agents. */
+export const AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE = settingsNamespace('agent-default-model')
+
+/** Stored and composed default model selection. */
+export interface AgentDefaultModelSettings {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+  /** Adapter-owned reasoning effort, or provider/default behavior when absent. */
+  reasoningEffort?: string
+}
+
+/** Schema of the default Agent model settings section. */
+export const AGENT_DEFAULT_MODEL_SETTINGS_SCHEMA: z<AgentDefaultModelSettings> = z.object({
+  provider: z.string().required(),
+  model: z.string().required(),
+  reasoningEffort: z.string(),
+})
+
+/** Composition entry for the default model selection. */
+export interface Config {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+}
+
+/** Project stored settings onto the Agent-facing selection type. */
+function selection(settings: AgentDefaultModelSettings): ModelSelection {
+  return {
+    provider: settings.provider,
+    model: settings.model,
+    ...settings.reasoningEffort === undefined
+      ? {}
+      : { reasoningEffort: ReasoningEffortId(settings.reasoningEffort) },
+  }
+}
+
+/**
+ * Owns the default model selection independently of any Host or transport.
+ * The composition entry remains usable without a settings provider; when one
+ * is mounted, its user layer is read live.
+ */
+export class AgentDefaultModelService extends Service {
+  static Config: z<Config> = z.object({
+    provider: z.string().required(),
+    model: z.string().required(),
+  })
+
+  private source: () => AgentDefaultModelSettings
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'agentDefaultModel')
+    const entry: AgentDefaultModelSettings = { provider: config.provider, model: config.model }
+    this.source = () => entry
+    installSettingsSection(ctx, AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE, AGENT_DEFAULT_MODEL_SETTINGS_SCHEMA, entry, {
+      setSource: (current) => { this.source = current },
+      // Every consumer reads through currentSelection(), so no registration-level fact
+      // needs rebuilding when the settings document changes.
+      onChange: () => {},
+    })
+  }
+
+  /**
+   * Read the current default model selection.
+   * @returns a detached provider, model, and optional reasoning selection.
+   */
+  currentSelection(): ModelSelection {
+    return selection(this.source())
+  }
+
+  /**
+   * Save the complete default model selection. A deployment without a settings
+   * provider keeps its composition entry.
+   * @param next - resolved selection accepted by a front door.
+   * @returns fulfillment after the optional settings write settles.
+   */
+  async saveSelection(next: ModelSelection): Promise<void> {
+    await this.ctx.get('settings')?.replace(AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE, {
+      provider: next.provider,
+      model: next.model,
+      ...next.reasoningEffort === undefined ? {} : { reasoningEffort: String(next.reasoningEffort) },
+    })
+  }
+}
+
+export default AgentDefaultModelService
diff --git a/packages/core/agent-default-model/src/invariant.ts b/packages/core/agent-default-model/src/invariant.ts
new file mode 100644
index 0000000000..8366018661
--- /dev/null
+++ b/packages/core/agent-default-model/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for the default Agent model selection.
+ *
+ * The service owns no independent event relationship: settings registration
+ * already validates every mutable value before `currentSelection()` can observe it.
+ * The empty installer keeps that absence explicit in composed invariant sets.
+ *
+ * @module @deepseek-ai/dsh-agent-default-model/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-agent-default-model'
+
+/** Cordis companion plugin name. */
+export const name = 'agent-default-model-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** No runtime invariant: settings validation owns the only mutable-value relationship. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register the intentionally empty invariant contribution.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/core/agent-default-model/tests/agent-default-model.spec.ts b/packages/core/agent-default-model/tests/agent-default-model.spec.ts
new file mode 100644
index 0000000000..ef479b4a96
--- /dev/null
+++ b/packages/core/agent-default-model/tests/agent-default-model.spec.ts
@@ -0,0 +1,98 @@
+/** Default Agent model settings layered over a real settings provider. */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import AgentDefaultModelService, { AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE } from '../src/index.ts'
+import { Settings } from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+
+/** The smallest real provider: one in-memory document, always writable. */
+class MemorySettings extends Settings {
+  doc: Record<string, unknown> = {}
+
+  get writable(): boolean {
+    return true
+  }
+
+  protected load(): Promise<Record<string, unknown>> {
+    return Promise.resolve(structuredClone(this.doc))
+  }
+
+  protected persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
+    this.doc = { ...this.doc, [ns]: structuredClone(section) }
+    return Promise.resolve()
+  }
+}
+
+async function boot(): Promise<{
+  ctx: Context
+  settingsFiber: Context['fiber']
+  defaultModel: AgentDefaultModelService
+}> {
+  const ctx = new Context()
+  const settingsFiber = ctx.plugin(MemorySettings)
+  await settingsFiber.await()
+  await ctx.plugin(AgentDefaultModelService, {
+    provider: 'deepseek-official',
+    model: 'deepseek-v4-flash',
+  })
+  return { ctx, settingsFiber, defaultModel: ctx.agentDefaultModel }
+}
+
+describe('AgentDefaultModelService', () => {
+  it('resolves the user layer over the composition entry', async () => {
+    const bench = await boot()
+    expect(bench.defaultModel.currentSelection()).toEqual({
+      provider: 'deepseek-official', model: 'deepseek-v4-flash',
+    })
+
+    await bench.defaultModel.saveSelection({
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: ReasoningEffortId('high'),
+    })
+    expect(bench.defaultModel.currentSelection()).toEqual({
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
+    })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('clears a stored effort when the saved selection has none', async () => {
+    const bench = await boot()
+    await bench.defaultModel.saveSelection({
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: ReasoningEffortId('high'),
+    })
+    await bench.defaultModel.saveSelection({ provider: 'acme-gateway', model: 'acme-plain' })
+    expect(bench.defaultModel.currentSelection()).toEqual({ provider: 'acme-gateway', model: 'acme-plain' })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('layers a hand-written partial section over the entry', async () => {
+    const bench = await boot()
+    await bench.settingsFiber.ctx.settings.replace(AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE, {
+      model: 'deepseek-reasoner',
+    })
+    expect(bench.defaultModel.currentSelection()).toEqual({
+      provider: 'deepseek-official', model: 'deepseek-reasoner',
+    })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('falls back to the composition entry when the settings provider detaches', async () => {
+    const bench = await boot()
+    await bench.defaultModel.saveSelection({ provider: 'acme-gateway', model: 'acme-large' })
+    expect(bench.defaultModel.currentSelection().provider).toBe('acme-gateway')
+    await bench.settingsFiber.dispose()
+    expect(bench.defaultModel.currentSelection()).toEqual({
+      provider: 'deepseek-official', model: 'deepseek-v4-flash',
+    })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('keeps the composition entry when no settings provider is mounted', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentDefaultModelService, { provider: 'p', model: 'm' })
+    await ctx.agentDefaultModel.saveSelection({ provider: 'other', model: 'other' })
+    expect(ctx.agentDefaultModel.currentSelection()).toEqual({ provider: 'p', model: 'm' })
+    await ctx.fiber.dispose()
+  })
+})
diff --git a/packages/core/agent-default-model/tsconfig.json b/packages/core/agent-default-model/tsconfig.json
new file mode 100644
index 0000000000..95b89f17b5
--- /dev/null
+++ b/packages/core/agent-default-model/tsconfig.json
@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../settings/settings"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/core/agent-default-model/tsdown.config.ts b/packages/core/agent-default-model/tsdown.config.ts
new file mode 100644
index 0000000000..ab8dc26ee8
--- /dev/null
+++ b/packages/core/agent-default-model/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and invariant companion as independent bundles. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index 53a1a1f650..825c1714a2 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/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/core/agent/README.md
-README.md: 3a3bdf6a4b3bdc5bfef250495e84b7d90b003822
-README.zh.md: e421070a6eec2e6e7e1fc7b45f0a5e29040bf712
+README.md: ba0fa456593e598b6532c10ef2390bbd55f3a486
+README.zh.md: 581da5c8621e5653f57edce38ac9816da7a40d40
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index 3a3bdf6a4b..ba0fa45659 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -12,7 +12,7 @@ Tracks live agents and carries the initiating Agent through asynchronous driver
 
 ### Public API
 
-The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `installAgentLlmTarget(agentCtx, target)` snapshots a mutable provider/model/reasoning-effort selection during prompt assembly, applies the route to prompt variables, and applies the complete target to request routing for one step; an absent selected effort clears an inherited effort so the target uses adapter/provider defaults. `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
+The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `installModelSelection(agentCtx, selection)` snapshots a mutable provider/model/reasoning-effort selection during prompt assembly, applies its provider and model to prompt variables, and applies the complete selection to request routing for one step; an absent selected effort clears an inherited effort so adapter/provider defaults apply. `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
 
 `AgentOptions` supplies the initial provider/model route and an optional positive `maxTokens` output cap. The concrete loop resolves any exact-model adapter default, records the effective cap in the request header, and applies it to each conversation-model request; an explicit Agent option wins, while omission leaves the adapter or provider route default in control.
 
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index e421070a6e..581da5c862 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -12,7 +12,7 @@ Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事
 
 ### 公开 API
 
-带作用域的注册接口：`Agent.ctx` 是 agent 的作用域上下文（`dsh-scope`，键 = 该 agent）。通过它注册工具／段／变量／监听器，只对该 agent 生效，并在 dispose（资源释放）时全部撤销。`agentEvents(ctx, agent)` 是普通 agent 主体操作的融合分发器（一次完成载体 + 注入主体）；其通知 mode 会调用每个监听器，并同时收容同步抛出和返回 Promise 的拒绝。注册表生命周期对复用一个稳定路由载体。`assembleContextFor(agent)` 构建按 agent 的组装上下文（同时包含 `agent` + `scope`）。`installAgentLlmTarget(agentCtx, target)` 在提示词组装期间快照可变的提供方／模型／推理（reasoning）强度选择，将路由应用到提示词变量，并将完整目标应用到一个步骤的请求路由；如果没有选定推理强度，则会清除继承的推理强度，使该目标使用适配器／提供方默认值。`CreateAgentOptions.setup(agentCtx)` 和 `ResumeAgentOptions.setup(agentCtx)` 在新建或恢复的 agent 尚未发布时，组合其带作用域的世界。Setup 是受信任、仅用于组合的同进程代码：只有创建完成后才能驱动 agent。
+带作用域的注册接口：`Agent.ctx` 是 agent 的作用域上下文（`dsh-scope`，键 = 该 agent）。通过它注册工具／段／变量／监听器，只对该 agent 生效，并在 dispose（资源释放）时全部撤销。`agentEvents(ctx, agent)` 是普通 agent 主体操作的融合分发器（一次完成载体 + 注入主体）；其通知 mode 会调用每个监听器，并同时收容同步抛出和返回 Promise 的拒绝。注册表生命周期对复用一个稳定路由载体。`assembleContextFor(agent)` 构建按 agent 的组装上下文（同时包含 `agent` + `scope`）。`installModelSelection(agentCtx, selection)` 在提示词组装期间快照可变的提供方／模型／推理（reasoning）强度选择，将其中的提供方和模型应用到提示词变量，并将完整选择应用到一个步骤的请求路由；如果没有选定推理强度，则会清除继承的推理强度，使适配器／提供方默认值生效。`CreateAgentOptions.setup(agentCtx)` 和 `ResumeAgentOptions.setup(agentCtx)` 在新建或恢复的 agent 尚未发布时，组合其带作用域的世界。Setup 是受信任、仅用于组合的同进程代码：只有创建完成后才能驱动 agent。
 
 `AgentOptions` 提供初始的提供方／模型路由，以及可选的正数 `maxTokens` 输出上限。具体循环会解析确切模型的适配器默认值，把生效上限记录到请求 header，并应用到每次对话模型请求；显式 Agent 选项优先，省略时由适配器或提供方路由默认值控制。
 
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index 8f316f75dc..44c55d80a2 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -17,7 +17,7 @@ import type { Agent, AgentOptions } from './types.ts'
 
 export * from './types.ts'
 export * from './inbox.ts'
-export * from './llm-target.ts'
+export * from './model-selection.ts'
 export { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from './dispatch.ts'
 export type { AgentEventDispatch, AgentSubjectEvent } from './dispatch.ts'
 
diff --git a/packages/core/agent/src/llm-target.ts b/packages/core/agent/src/model-selection.ts
similarity index 55%
rename from packages/core/agent/src/llm-target.ts
rename to packages/core/agent/src/model-selection.ts
index e23ea9d750..4d36ca34fb 100644
--- a/packages/core/agent/src/llm-target.ts
+++ b/packages/core/agent/src/model-selection.ts
@@ -1,13 +1,13 @@
 /**
- * Agent-scoped LLM target snapshot shared by interactive front doors.
- * @module @deepseek-ai/dsh-agent/llm-target
+ * Agent-scoped model selection shared by interactive front doors.
+ * @module @deepseek-ai/dsh-agent/model-selection
  */
 
 import type { Context } from 'cordis'
 import type { LlmCallConfig, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 
-/** Complete provider/model route and optional reasoning effort selected for one live agent. */
-export interface AgentLlmTarget {
+/** Complete provider, model, and optional reasoning effort selected for one live Agent. */
+export interface ModelSelection {
   /** Registered provider route. */
   provider: string
   /** Provider-owned model id. */
@@ -16,31 +16,31 @@ export interface AgentLlmTarget {
   reasoningEffort?: ReasoningEffortId
 }
 
-/** Mutable selection plus the target captured for the current step. */
-export interface AgentLlmTargetRef {
-  /** Target selected for the next step that enters prompt assembly. */
-  current: AgentLlmTarget | undefined
-  /** Target captured when the current step entered prompt assembly. */
-  assembled: AgentLlmTarget | undefined
+/** Mutable model selection plus the value captured for the current step. */
+export interface ModelSelectionRef {
+  /** Model selected for the next step that enters prompt assembly. */
+  current: ModelSelection | undefined
+  /** Selection captured when the current step entered prompt assembly. */
+  assembled: ModelSelection | undefined
 }
 
 /**
- * Couple one mutable target to agent-scoped prompt assembly and request routing.
- * Prompt assembly snapshots the selected target before delegating, then applies
- * its route to prompt variables and its route/effort to request config so a
+ * Couple one mutable selection to Agent-scoped prompt assembly and request routing.
+ * Prompt assembly snapshots the selected model before delegating, then applies
+ * its provider/model pair and effort to request config so a
  * concurrent switch takes effect on a later step instead of splitting the two
- * surfaces. An absent selected effort clears any inherited effort so a model
- * switch can restore that target's provider/default behavior.
+ * surfaces. An absent selected effort clears any inherited effort, restoring
+ * the selected model's provider/default behavior.
  *
- * @param agentCtx - The target agent's scoped context.
- * @param target - Mutable selection owned by the calling front door.
+ * @param agentCtx - The selected Agent's scoped context.
+ * @param selection - Mutable selection owned by the calling front door.
  * @returns Disposer for both scoped waterfall listeners.
  */
-export function installAgentLlmTarget(agentCtx: Context, target: AgentLlmTargetRef): () => void {
+export function installModelSelection(agentCtx: Context, selection: ModelSelectionRef): () => void {
   const disposeAssembly = agentCtx.on('system-prompt/assemble', async (_assembly, _context, next) => {
-    const selected = target.current
+    const selected = selection.current
     const assembled = await next()
-    target.assembled = selected
+    selection.assembled = selected
     if (selected === undefined) return assembled
     return {
       ...assembled,
@@ -55,7 +55,7 @@ export function installAgentLlmTarget(agentCtx: Context, target: AgentLlmTargetR
     'agent/request',
     async (_payload, next): Promise<LlmCallConfig> => {
       const resolved = await next()
-      const selected = target.assembled
+      const selected = selection.assembled
       if (selected === undefined) return resolved
       const { reasoningEffort: _inheritedEffort, ...withoutInheritedEffort } = resolved
       return {
diff --git a/packages/core/agent/tests/llm-target.spec.ts b/packages/core/agent/tests/model-selection.spec.ts
similarity index 86%
rename from packages/core/agent/tests/llm-target.spec.ts
rename to packages/core/agent/tests/model-selection.spec.ts
index 991a69ea32..2d7a1a7336 100644
--- a/packages/core/agent/tests/llm-target.spec.ts
+++ b/packages/core/agent/tests/model-selection.spec.ts
@@ -3,18 +3,18 @@ import { Context } from 'cordis'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import {
   agentEvents,
-  installAgentLlmTarget,
+  installModelSelection,
   type Agent,
-  type AgentLlmTargetRef,
+  type ModelSelectionRef,
 } from '../src/index.ts'
 import { ReasoningEffortId, type LlmCallConfig } from '@deepseek-ai/dsh-llm'
 
-describe('installAgentLlmTarget()', () => {
+describe('installModelSelection()', () => {
   it('snapshots prompt variables and request routing together, then disposes both listeners', async () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
-    const target: AgentLlmTargetRef = { current: undefined, assembled: undefined }
-    const dispose = installAgentLlmTarget(ctx, target)
+    const selection: ModelSelectionRef = { current: undefined, assembled: undefined }
+    const dispose = installModelSelection(ctx, selection)
     const agent = {} as Agent
     const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
     const signal = new AbortController().signal
@@ -24,13 +24,13 @@ describe('installAgentLlmTarget()', () => {
       'agent/request', { turn: 1, step: 0, signal }, () => Promise.resolve(seed),
     )).resolves.toBe(seed)
 
-    target.current = {
+    selection.current = {
       provider: 'alpha',
       model: 'a1',
       reasoningEffort: ReasoningEffortId('high'),
     }
     expect((await ctx.systemPrompt.assemble()).variables).toMatchObject({ provider: 'alpha', model: 'a1' })
-    target.current = { provider: 'beta', model: 'b1' }
+    selection.current = { provider: 'beta', model: 'b1' }
     await expect(agentEvents(ctx, agent).waterfall(
       'agent/request', { turn: 1, step: 0, signal }, () => Promise.resolve(seed),
     )).resolves.toEqual({
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index bc7869b361..b994e46b03 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: a3c9f214690144ec0f39a8690e4fd346f5e315e2
-README.zh.md: 65475351e279f258f4417f2082673382e76a5be3
+README.md: 5e3a6cf57ce3fe11b3f31d7f68055f34708d74eb
+README.zh.md: b96487d6d67deb8a0a6ddf4a92784f31dafb3e89
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index a3c9f21469..5e3a6cf57c 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -2,19 +2,19 @@
 
 English | [中文](README.zh.md)
 
-The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, reasoningEffort?, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers such as HTTP wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml).
+The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers such as HTTP wrap `ctx.apiProxy` themselves. The shipped Web composition lives in [`packages/bundle/web-app/cordis.patch.yml`](../../bundle/web-app/cordis.patch.yml), while its default Agent model selection belongs to [`@deepseek-ai/dsh-agent-default-model`](../../core/agent-default-model/README.md) in the base bundle.
 
-## The default route (`api-gateway` settings section)
+## The shared Agent default (`agent-default-model` Settings section)
 
-`{provider, model, reasoningEffort?}` is also the gateway's user-settings section, registered under `api-gateway`: the composition entry is the `base` layer and `settings.yaml` layers the user's own choice over it. `workspaceRoot` is deliberately outside the section — a launcher fact, not a preference.
+`ApiProxyService` consumes `ctx.agentDefaultModel`; it does not own a provider/model config or settings section. The shared service registers `{provider, model, reasoningEffort?}` under `agent-default-model`: the base bundle's composition entry is the lower layer and `settings.yaml` layers the user's choice over it. `workspaceRoot` remains ApiProxy config because it is a Host launcher fact, not a model preference.
 
-A session resolves its route from three tiers, re-read on every access rather than seeded once: a selection made in this process, else the session's own latest logged `request/header`, else this default. Re-reading is what makes both directions hold — a session that has run a turn derives its route from its log forever after, so changing the default never retargets it, while a session still blank (New Session reuses one rather than minting another) starts from a default saved after it was created.
+A session resolves its model selection from three tiers on every access: a selection made in this process, otherwise the session's latest logged `request/header`, otherwise this default. A session that has run a turn derives its selection from its log, while a blank session observes a default saved after it was created.
 
-`session.selectModel` records an accepted switch as the new default, which is how the default is chosen in practice: there is no separate gesture. What it stores is the RESOLVED target, so an adapter-materialized default effort is pinned as the user saw it and a later adapter-default change does not silently move stored defaults. The write replaces the section wholesale rather than merging, because switching to a model with no reasoning effort has to clear a stored one; a storage failure is logged without undoing the switch, which already applies to its own session. A deployment with no settings provider keeps the composition entry and a switch stays process-local.
+`session.selectModel` saves an accepted switch as the deployment default; there is no separate gesture. It stores the resolved `ModelSelection`, including an adapter-materialized default effort. The complete-section write clears a stored effort when the selected model has none. A storage failure is logged without undoing the session selection. A deployment with no settings provider keeps the composition entry and the switch remains session-local.
 
-The section's `reasoningEffort` has no counterpart in the plugin config, deliberately: the seam merges the user layer over the composition entry per field, so an absent key cannot override a present one and a composition-set effort would survive every later switch to a model without one. A deployment default for effort belongs on the adapter profile, which resolves per model.
+The section's `reasoningEffort` has no counterpart in the agent-default-model plugin config, deliberately: the seam merges the user layer over the composition entry per field, so an absent key cannot override a present one and a composition-set effort would survive every later switch to a model without one. A deployment default for effort belongs on the adapter profile, which resolves per model.
 
-The stored route is not validated against the registry, in either direction. A default naming a route the Models page has since removed still reaches `session.models` as the session's `current` — matching no advertised group, which is precisely what makes a selector prompt for a replacement instead of naming a model the deployment cannot reach. Repairing it silently would also break the deliberate converse: an adapter may serve a model its catalog does not advertise.
+The stored selection is independent of catalog membership. A default naming an unavailable provider still reaches `session.models` as the session's `current`, allowing the selector to request a replacement instead of silently choosing another model. Conversely, an adapter may serve a model that its catalog does not advertise.
 
 ## Contract layer (`/api`)
 
@@ -30,9 +30,9 @@ Question responses are validated against their pending request before the first
 
 Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`.
 
-`session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged provider/model/reasoning target, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale.
+`session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged `ModelSelection`, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale.
 
-Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target separately from provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. The current target may be absent from the groups and is never injected as a synthetic row; clients can prompt for a replacement without turning the directory into a routing whitelist. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`. `session.models` additionally reports `routable`: whether an adapter currently serves the current target's route, which is deliberately NOT derivable from the groups — a route serving a model it stopped advertising is absent from them yet perfectly usable, while a route whose adapter is gone can serve nothing. `session.prompt` refuses on that same fact with `model-unavailable` rather than spending the pre-step path to fail inside an adapter; a client that disables its composer is an affordance, and this method stays callable regardless.
+Session model selection is a session-domain contract. `session.models` returns the current `ModelSelection` separately from provider-grouped advisory models, exact-model reasoning metadata, and provider-local lookup failures. The selection may be absent from the groups and is never injected as a synthetic row; clients can prompt for another selection without turning the directory into a routing whitelist. `session.selectModel` validates the optional adapter-owned reasoning effort and assigns the complete selection for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable provider or unsupported effort returns `model-unavailable`. `session.models` additionally reports `routable`: whether an adapter currently serves the selected provider. This is deliberately not derivable from the groups because an adapter may serve an unadvertised model. `session.prompt` refuses on the same fact with `model-unavailable` before opening a turn; a disabled composer is a client affordance, and the method remains callable.
 
 Pending queued input is a live control-plane contract, not conversation history. The gateway derives the complete `next-turn` queue from durable `agent/inbox/spliced` mutations and broadcasts authoritative `session/queue` snapshots after each change and on reconnect; pending `next-step` steering stays outside this Web projection. Within `next-step`, user-origin messages carry the `steering` placement while injected context (approval notices, task completion, attached snapshots) carries `context` and is not surfaced until claimed. The message-local `agent/inbox/inserted`, `claimed`, and `discarded` notifications remain available to lifecycle observers but do not build the queue view. `session.updateQueue` addresses one `MessageId`; edit and remove mutate the attached Agent through `Inbox.splice()`. A claim's pure deletion splice wins races before pre-step admission, so a later operation returns `queue-item-not-found`. `session.cancel` aborts only the active turn and preserves pending inbox work; after cancellation reaches quiescence and the closing turn flushes, AgentLoop claims the next waking message in FIFO order, and the browser never resends or promotes it. Queue operations never resume a cold session, and the client never infers retirement from turn or status events.
 
@@ -52,7 +52,7 @@ The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-pag
 
 ## Carrier layer (`/client` + root)
 
-`AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh run` headless.
+`AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` remains the isomorphic point for callers and carrier tests that need the full wire serialization/validation path without a network. Product `dsh run` is a direct core front door and does not mount this package.
 
 ## Model Experience
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index 65475351e2..b96487d6d6 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -2,19 +2,19 @@
 
 [English](README.md) | 中文
 
-所有客户端形态共用的 API 网关：TS 约定（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, reasoningEffort?, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml)。
+所有客户端形态共用的 API 网关：TS 约定（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。随发行版交付的 Web 组合位于 [`packages/bundle/web-app/cordis.patch.yml`](../../bundle/web-app/cordis.patch.yml)，其默认 Agent（智能体）模型选择属于 base 组合包中的 [`@deepseek-ai/dsh-agent-default-model`](../../core/agent-default-model/README.md)。
 
-## 默认路由（`api-gateway` 设置段）
+## 共享 Agent 默认值（`agent-default-model` Settings 分节）
 
-`{provider, model, reasoningEffort?}` 同时是网关的用户设置段，注册在 `api-gateway` 之下：组合条目是 `base` 层，`settings.yaml` 把用户自己的选择叠加其上。`workspaceRoot` 刻意不在段内——它是启动器事实，不是偏好。
+`ApiProxyService` 消费 `ctx.agentDefaultModel`；它不持有提供方／模型配置或 Settings 分节。共享服务在 `agent-default-model` 下注册 `{provider, model, reasoningEffort?}`：base 组合包的组合条目是底层，`settings.yaml` 把用户选择叠加其上。`workspaceRoot` 仍属于 ApiProxy 配置，因为它是 Host 启动器事实，而不是模型偏好。
 
-会话按三级解析自己的路由，且每次读取都重新解析，而不是只在创建时种一次：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是这个默认值。重新解析正是让两个方向都成立的原因——已经跑过一轮的会话此后永远从自己的日志推导路由，改默认值不会重定向它；而仍然空白的会话（新建会话会复用一个，而不是再开一个）则会用上它创建之后才保存的默认值。
+会话每次访问时都按三级解析模型选择：本进程内作出的选择，其次是该会话日志中最新的 `request/header`，最后是这个默认值。已经跑过一轮的会话从自己的日志推导选择，空白会话则能观察到创建之后保存的默认值。
 
-`session.selectModel` 会把被接受的切换记录为新的默认值，实践中默认值就是这样选定的，没有另一个单独的手势。它存下来的是**解析后**的目标，因此适配器实体化出来的默认推理等级会按用户当时看到的样子钉住，日后适配器改了自己的默认值也不会悄悄移动已存的默认路由。写入是整段替换而非合并，因为切到一个不带推理等级的模型必须清掉已存的等级；存储失败只记日志，不会撤销这次切换——它对自己所在的会话已经生效。没有设置提供方的部署保留组合条目，切换只停留在进程内。
+`session.selectModel` 会把接受的切换保存为部署默认值；没有单独的选择动作。它存储已解析的 `ModelSelection`，包括适配器实体化的默认推理强度。完整分节写入会在所选模型没有推理强度时清除已存值。存储失败只记日志，不会撤销会话选择。没有设置提供方的部署保留组合条目，切换只对当前会话生效。
 
-设置段里的 `reasoningEffort` 在插件配置中刻意没有对应字段：seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键，因此组合层设的推理等级会在此后每一次切到不带推理等级的模型时继续存活。推理等级的部署级默认值属于适配器 profile，那里是按模型解析的。
+Settings 分节中的 `reasoningEffort` 在 agent-default-model 插件配置中刻意没有对应字段：seam 按字段把用户层合并到组合条目之上，因此缺席的键无法覆盖已有键，组合层中的推理强度会在以后选择没有推理强度的模型时继续存在。推理强度的部署默认值属于按模型解析的适配器 profile。
 
-存下来的路由不做注册表校验，两个方向都不做。默认值指向一个已在模型页删除的路由时，它照样作为会话的 `current` 送到 `session.models`——匹配不到任何已公布的分组，而这恰恰是让选择器提示重新选择、而不是显示一个部署根本够不着的模型的原因。静默修复它还会破坏刻意保留的反面情形：适配器可以服务一个自己目录未公布的模型。
+存储的选择独立于目录成员关系。默认值指向不可用的提供方时，它仍会作为会话的 `current` 送到 `session.models`，让选择器请求用户重新选择，而不是静默选用其他模型。反过来，适配器也可以服务其目录中未公布的模型。
 
 ## 约定层（`/api`）
 
@@ -24,15 +24,15 @@
 
 首个回答认领待处理请求之前，系统会对照该请求校验问题响应。多选题的回答项可以同时携带 `selected` 中的请求选项标签与非空 `custom` 文本；单选题的回答项必须二选一。标签重复、标签未知、id 不匹配、批次不完整以及自定义文本为空都会以 `bad-response` 拒绝。
 
-`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent（智能体），然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
+`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent，然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
 会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。
 
-`session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的提供方／模型／推理（reasoning）目标及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。
+`session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的 `ModelSelection` 及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。
 
-会话模型路由属于会话领域约定。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。`session.models` 还会报告 `routable`：当前目标的路由是否有适配器在服务。这一点刻意不由分组推导——一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用；而适配器已经消失的路由什么都服务不了。`session.prompt` 依据同一个事实以 `model-unavailable` 拒绝，而不是把整条 pre-step 路径走完再在适配器内部失败；客户端禁用输入框只是提示性设计，这个方法始终可被调用。
+会话模型选择属于会话领域约定。`session.models` 将当前 `ModelSelection` 与按提供方分组的建议性模型、精确模型的推理（reasoning）元数据和逐提供方查询失败记录分开返回。该选择可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户作出另一项选择，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并指定将在下一提示词组装边界使用的完整选择。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用的提供方或不受支持的推理强度会返回 `model-unavailable`。`session.models` 还会报告 `routable`，即当前是否有适配器为所选提供方提供服务。该值刻意不从分组推导，因为适配器可以服务未公布的模型。`session.prompt` 会依据同一事实，在开启轮次之前以 `model-unavailable` 拒绝；客户端禁用 composer 只是提示性设计，这个方法始终可被调用。
 
 待处理的 queued 输入属于实时控制平面约定，而非对话历史。网关根据持久 `agent/inbox/spliced` 变更派生完整的 `next-turn` 队列，并在每次变更后及重连时广播权威 `session/queue` 快照；待处理的 `next-step` steering（中途引导）不进入此 Web 投影。在 `next-step` 内，用户来源的消息携带 `steering` placement，而注入上下文（审批通知、任务完成、附加快照）携带 `context`，领取前不对外呈现。面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知仍供生命周期观察方使用，但不用于构建队列视图。`session.updateQueue` 通过 `MessageId` 寻址单个项；编辑和移除经已挂载 Agent 的 `Inbox.splice()` 修改队列。claim 的纯删除 splice 会在 pre-step 准入前赢得竞态，因此之后的操作返回 `queue-item-not-found`。`session.cancel` 仅中止活动轮次并保留待处理 inbox 工作；取消达到完全停稳且结束中的轮次完成 flush 后，AgentLoop 按 FIFO 顺序认领下一条可唤醒消息，浏览器绝不重发或提升它。队列操作绝不恢复冷会话，客户端也绝不根据轮次或状态事件推断某项已退出队列。
 
@@ -52,7 +52,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 ## 载体层（`/client` + 根路径）
 
-`AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供 `dsh run` headless 模式使用。
+`AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，仍是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供需要该路径的调用方和载体测试使用。产品的 `dsh run` 是直连 core 的入口，不挂载本包。
 
 ## 模型体验
 
diff --git a/packages/host/apiproxy/package.json b/packages/host/apiproxy/package.json
index 91d03b4448..511fc25dba 100644
--- a/packages/host/apiproxy/package.json
+++ b/packages/host/apiproxy/package.json
@@ -39,6 +39,7 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-default-model": "workspace:^",
     "@deepseek-ai/dsh-api-remotes": "workspace:^",
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 52236b0f29..01b792353d 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -7,8 +7,9 @@ import { randomUUID } from 'node:crypto'
 import { mkdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Context } from 'cordis'
-import { installAgentLlmTarget } from '@deepseek-ai/dsh-agent'
-import type { Agent, AgentLlmTarget, AgentLlmTargetRef, AgentOptions, AgentStatus } from '@deepseek-ai/dsh-agent'
+import { installModelSelection } from '@deepseek-ai/dsh-agent'
+import type { Agent, ModelSelection, ModelSelectionRef, AgentOptions, AgentStatus } from '@deepseek-ai/dsh-agent'
+import { AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE } from '@deepseek-ai/dsh-agent-default-model'
 import { createUserMessage, freezeMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import { errorChain } from '@deepseek-ai/dsh-llm'
 import type { MessageSource } from '@deepseek-ai/dsh-llm'
@@ -83,14 +84,6 @@ import { openNativePath, openNativeTextFile } from './native-path-opener.ts'
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
 
-/**
- * The settings namespace carrying the user's default route. Named for the
- * gateway rather than for the package, because this key is what a person reads
- * and writes in `settings.yaml`; the row id in a composition happens to match
- * but does not determine it.
- */
-export const API_GATEWAY_SETTINGS_NAMESPACE = settingsNamespace('api-gateway')
-
 /** Non-model settings namespaces intentionally served to the Web client. */
 const WEB_SETTINGS_NAMESPACES = ['permission'] as const
 
@@ -152,7 +145,7 @@ function ok<T>(request: RpcRequest<unknown>, value: T): RpcResponse<T> {
 /**
  * Build the provider/model catalog over every registered route. Shared by the
  * session-scoped `session.models` and host-scoped `llm.models`. Catalog
- * membership stays advisory: an unlisted session target remains valid for
+ * membership stays advisory: an unlisted session selection remains valid for
  * provider dispatch, but is not injected back into the selector after its
  * owning catalog stops advertising it. Per-provider failures ride `failures`
  * without failing the sound groups; groups that advertise nothing are dropped.
@@ -345,14 +338,14 @@ function directoryError(error: unknown): RpcError {
   return { code: 'internal', message: error instanceof Error ? error.message : String(error), details: {} }
 }
 
-/** Resolved Host routing and project-directory defaults consumed by the API implementation. */
+/** Resolved Agent model and project-directory defaults consumed by the API implementation. */
 export interface ApiProxyDefaults {
   /**
-   * The route a session starts from when its own log names none. Read on
+   * The model selection a session starts from when its own log names none. Read on
    * every access rather than captured, so a default saved during this process
    * reaches the sessions that have not run a turn yet.
    */
-  defaultTarget: () => AgentLlmTarget
+  defaultModelSelection: () => ModelSelection
   /**
    * Record a selection as the new default. Either absent, or a closure that
    * may itself decline — the gateway plugin always passes one, and it no-ops
@@ -361,7 +354,7 @@ export interface ApiProxyDefaults {
    * reported and swallowed: the switch already applies to its own session,
    * and undoing it because storage failed would be the worse outcome.
    */
-  persistDefaultTarget?: (target: AgentLlmTarget) => Promise<void>
+  saveDefaultModelSelection?: (selection: ModelSelection) => Promise<void>
   /** Default project directory for new sessions whose create request carries no cwd. */
   cwd: string
   /** Parent directory for name-created workspaces. */
@@ -734,17 +727,17 @@ function changedWorkspaceView(workspaceId: string, value: unknown): WorkspaceVie
 /**
  * Implement ApiProxy over a composed host context.
  * @param ctx - a context with the Host spine and Workspace registry mounted.
- * @param defaults - host routing and project-directory defaults.
+ * @param defaults - Agent model and project-directory defaults.
  * @returns the ApiProxy implementation.
  */
 export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
-  /** The seed route each create/resume declares; re-read so it never goes stale. */
+  /** The seed model each create/resume declares; re-read so it never goes stale. */
   const agentOptions = (): AgentOptions => {
-    const { provider, model } = defaults.defaultTarget()
+    const { provider, model } = defaults.defaultModelSelection()
     return { provider, model }
   }
-  type WebLlmTargetRef = AgentLlmTargetRef & { current: AgentLlmTarget }
-  const targets = new WeakMap<Agent, WebLlmTargetRef>()
+  type WebModelSelectionRef = ModelSelectionRef & { current: ModelSelection }
+  const selections = new WeakMap<Agent, WebModelSelectionRef>()
   /** Client-chosen identity creation/resume, deduplicated across concurrent retries. */
   const sessionCreations = new Map<SessionId, Promise<Agent>>()
   /** Serializes path ownership and explicit title checks with Workspace mutations. */
@@ -754,29 +747,28 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
   const muxQueues = new Set<FrameQueue<RpcRequest<MuxFrame>>>()
 
   /**
-   * Install or return the session-local target that prompt assembly snapshots.
+   * Install or return the session-local model selection that prompt assembly snapshots.
    *
    * Precedence, resolved on EVERY read rather than seeded once: a selection
    * made in this process, else the session's own latest logged request/header,
-   * else the live host default. Re-reading is what keeps the two tiers honest
-   * in both directions — a session that has run a turn derives its route from
-   * its log forever after, so changing the default never retargets it; and a
-   * session still blank (New Session reuses one rather than minting another)
-   * starts from a default saved after it was created. There is no create-time
+   * else the live Agent default. Re-reading keeps the two tiers exact in both
+   * directions: a session with a recorded request derives its selection from
+   * its log, while a blank session (New Session reuses one rather than minting
+   * another) reads any default saved after it was created. There is no create-time
    * per-session override tier on this wire — if one returns (a create-options
    * contribution), it must fold in between the selection and the log.
    */
-  function targetFor(agent: Agent): WebLlmTargetRef {
-    const installed = targets.get(agent)
+  function selectionFor(agent: Agent): WebModelSelectionRef {
+    const installed = selections.get(agent)
     if (installed !== undefined) return installed
-    let picked: AgentLlmTarget | undefined
-    const target: WebLlmTargetRef = {
-      get current(): AgentLlmTarget {
+    let picked: ModelSelection | undefined
+    const selection: WebModelSelectionRef = {
+      get current(): ModelSelection {
         if (picked !== undefined) return picked
         // Incrementally folded by the session, so a per-step read costs
         // O(new events) rather than a rescan.
         const logged = agent.session.requestHeader()?.config
-        if (logged === undefined) return defaults.defaultTarget()
+        if (logged === undefined) return defaults.defaultModelSelection()
         return {
           provider: logged.provider,
           model: logged.model,
@@ -785,21 +777,21 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             : { reasoningEffort: logged.reasoningEffort },
         }
       },
-      set current(next: AgentLlmTarget) {
+      set current(next: ModelSelection) {
         picked = next
       },
       assembled: undefined,
     }
-    installAgentLlmTarget(agent.ctx, target)
-    targets.set(agent, target)
-    return target
+    installModelSelection(agent.ctx, selection)
+    selections.set(agent, selection)
+    return selection
   }
 
   /** Pre-publication setup used by both fresh and resumed Web agents. */
-  function installTarget(agentCtx: Context): void {
+  function installSelection(agentCtx: Context): void {
     const agent = agentCtx.agent
     if (agent === undefined) throw new Error('api-proxy: agent setup has no scoped agent')
-    targetFor(agent)
+    selectionFor(agent)
   }
 
   const hasSubagentOwner = (
@@ -810,7 +802,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     apiRemoteSubagentOwnershipError(sessionId)
   const inspectServable = (sessionId: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> =>
     inspectApiRemoteSession(ctx, sessionId)
-  const agentFor = createApiRemoteAgentResolver(ctx, { agentOptions, setup: installTarget })
+  const agentFor = createApiRemoteAgentResolver(ctx, { agentOptions, setup: installSelection })
 
   /** Send one transient frame to every connected mux consumer. */
   function broadcast(payload: MuxFrame): void {
@@ -1076,7 +1068,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           return (await ctx.agents.resume({
             resumeSessionId: sessionId,
             agentOptions: agentOptions(),
-            setup: installTarget,
+            setup: installSelection,
           })).agent
         }
 
@@ -1089,7 +1081,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           sessionId,
           agentOptions: agentOptions(),
           meta: { cwd },
-          setup: installTarget,
+          setup: installSelection,
         })).agent
       })().catch((error: unknown) => {
         // Another Host entry path may have published the same identity while
@@ -1235,10 +1227,10 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
   }
 
   /**
-   * Whether an adapter currently serves this route, and therefore whether a
-   * session pointed at it can start a turn. Catalog membership cannot answer
+   * Whether an adapter currently serves this provider, and therefore whether
+   * a session selecting it can start a turn. Catalog membership cannot answer
    * it: an adapter may serve a model its own catalog stopped advertising, so
-   * a route missing from the groups is not the same as one nothing serves.
+   * a provider missing from the groups is not the same as one nothing serves.
    * A composition with no llm registry at all cannot judge and says yes —
    * the dispatch it would have refused fails on its own terms.
    */
@@ -1249,7 +1241,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
 
   /**
    * Resolve the addressed agent for a turn-starting method and refuse when no
-   * adapter serves its current route: a route nothing serves cannot start a
+   * adapter serves its current selection: a provider nothing serves cannot start a
    * turn, and letting it try spends the whole pre-step path to fail inside
    * the adapter with a message about registration. Refusing here names the
    * model the session is pointed at while the draft is still in the composer.
@@ -1262,13 +1254,13 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     const found = await agentFor(sessionId)
     if ('error' in found) return { refused: err(request, found.error) }
     const agent = found.agent
-    const target = targetFor(agent).current
-    if (!routeServed(target.provider)) {
+    const selection = selectionFor(agent).current
+    if (!routeServed(selection.provider)) {
       return {
         refused: err(request, {
           code: 'model-unavailable',
-          message: `no adapter serves provider "${target.provider}"; select a model for this session`,
-          details: { provider: target.provider, model: target.model },
+          message: `no adapter serves provider "${selection.provider}"; select a model for this session`,
+          details: { provider: selection.provider, model: selection.model },
         }),
       }
     }
@@ -1643,7 +1635,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         const { sessionId } = request.payload
         const found = await agentFor(sessionId)
         if ('error' in found) return err(request, found.error)
-        const current = targetFor(found.agent).current
+        const current = selectionFor(found.agent).current
         const { groups, failures } = await buildModelCatalog(ctx)
         const routable = routeServed(current.provider)
         return ok(request, { current: { ...current }, routable, groups, failures })
@@ -1661,20 +1653,20 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
               ? {}
               : { reasoningEffort: ReasoningEffortId(reasoningEffort) },
           })
-          const selected: AgentLlmTarget = {
+          const selected: ModelSelection = {
             provider: resolved.provider,
             model: resolved.model,
             ...resolved.reasoningEffort === undefined
               ? {}
               : { reasoningEffort: resolved.reasoningEffort },
           }
-          targetFor(found.agent).current = selected
+          selectionFor(found.agent).current = selected
           // A switch is also how this deployment's default is chosen: the next
           // session created without one of its own starts here. Sessions that
-          // have already logged a route are unaffected — they derive from
-          // their own log (see targetFor).
+          // have already logged a selection are unaffected — they derive from
+          // their own log (see selectionFor).
           try {
-            await defaults.persistDefaultTarget?.(selected)
+            await defaults.saveDefaultModelSelection?.(selected)
           } catch (error: unknown) {
             ctx.logger.warn(
               `api-proxy: the model switch applies to this session but was not saved as the default: ${String(error)}`,
@@ -1783,7 +1775,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
               seedLength: cut,
             },
             agentOptions: agentOptions(),
-            setup: installTarget,
+            setup: installSelection,
           })
         } catch (error: unknown) {
           return err(request, {
@@ -2192,7 +2184,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     host: {
       describe(request) {
         // TODO(step2): version should read apps/cli's package.json; placeholder for now.
-        const route = defaults.defaultTarget()
+        const selection = defaults.defaultModelSelection()
         return Promise.resolve(ok(request, {
           version: '0.0.1',
           // Same source as session.create's fallback: the UI's default project
@@ -2200,8 +2192,8 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           cwd: defaults.cwd,
           // Read live for the same reason: this is what the NEXT session will
           // start from, so a saved default has to be what it reports.
-          provider: route.provider,
-          model: route.model,
+          provider: selection.provider,
+          model: selection.model,
           attachedSessions: ctx.agents.list().length,
         }))
       },
@@ -2730,11 +2722,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             // A provider's own settings carry its model catalog and endpoint,
             // so a change there invalidates the model list even when the route
             // set is untouched — `llm/adapters-updated` alone misses it. The
-            // gateway's own section is the other such source: it names the
-            // route every session with no logged one resolves to, so an
+            // Agent default section is the other such source: it names the
+            // selection every session with no logged one resolves to, so an
             // externally edited default (another tab, a hand-edited
             // settings.yaml) has to reach an open selector too.
-            if (modelProviderNamespaces().has(name) || name === String(API_GATEWAY_SETTINGS_NAMESPACE)) {
+            if (modelProviderNamespaces().has(name) || name === String(AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE)) {
               queue.push(frame({ type: 'host/models-changed' }))
             }
           }),
diff --git a/packages/host/apiproxy/src/api/index.ts b/packages/host/apiproxy/src/api/index.ts
index 5537a0e382..8e35c62514 100644
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -37,7 +37,7 @@ export interface ApiProxy {
 // ---- Domain interfaces and payload entities ----
 export type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, QueueAction, SessionModels, SessionProjectionsBlock, SessionSearchItem,
+  ModelReasoningEffort, ModelSelection, QueueAction, SessionModels, SessionProjectionsBlock, SessionSearchItem,
   SessionsApi, SessionSummary,
 } from './sessions.ts'
 export type { DirectoryEntry, DirectoryListing, HostApi } from './host.ts'
diff --git a/packages/host/apiproxy/src/api/llm.ts b/packages/host/apiproxy/src/api/llm.ts
index 29cda6cf78..01564992d0 100644
--- a/packages/host/apiproxy/src/api/llm.ts
+++ b/packages/host/apiproxy/src/api/llm.ts
@@ -3,8 +3,8 @@
  * surfaces. `llm.providers` merges the configurable-provider directory
  * (which providers CAN be configured, and where their settings live) with the
  * live route registry; `llm.models` is the session-independent model catalog
- * (the same groups as `session.models`, without the per-session current
- * target). Both invalidate on the `host/models-changed` frame.
+ * (the same groups as `session.models`, without a per-session selection).
+ * Both invalidate on the `host/models-changed` frame.
  */
 
 import type { RpcRequest, RpcResponse } from './rpc.ts'
diff --git a/packages/host/apiproxy/src/api/sessions.schema.ts b/packages/host/apiproxy/src/api/sessions.schema.ts
index 80e64fb12a..a1cc88dace 100644
--- a/packages/host/apiproxy/src/api/sessions.schema.ts
+++ b/packages/host/apiproxy/src/api/sessions.schema.ts
@@ -12,7 +12,7 @@ import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 import type {
   HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, SessionProjectionsBlock, SessionSearchItem, SessionSummary,
+  ModelReasoningEffort, ModelSelection, SessionProjectionsBlock, SessionSearchItem, SessionSummary,
 } from './sessions.ts'
 import type { ToolEventView } from './events.ts'
 import type { WorkspaceId } from './workspace.ts'
@@ -140,12 +140,12 @@ export const sessionHistoryRequestSchema = z.object({
   maxMessages: z.number().int().positive().optional(),
 }) satisfies z.ZodType<Wire<RequestPayload<'session.history'>>>
 
-/** Complete provider/model target. */
-export const modelTargetSchema = z.object({
+/** Complete provider/model selection. */
+export const modelSelectionSchema = z.object({
   provider: z.string().min(1),
   model: z.string().min(1),
   reasoningEffort: z.string().min(1).optional(),
-}) satisfies z.ZodType<Wire<ModelTarget>>
+}) satisfies z.ZodType<Wire<ModelSelection>>
 
 /** One adapter-owned reasoning effort. */
 export const modelReasoningEffortSchema = z.object({
@@ -224,7 +224,7 @@ export const sessionModelsRequestSchema = z.object({
 
 /** session.models response value. */
 export const sessionModelsValueSchema = z.object({
-  current: modelTargetSchema,
+  current: modelSelectionSchema,
   routable: z.boolean(),
   groups: z.array(modelProviderGroupSchema),
   failures: z.array(modelCatalogFailureSchema),
@@ -240,7 +240,7 @@ export const sessionSelectModelRequestSchema = z.object({
 
 /** session.selectModel response value. */
 export const sessionSelectModelValueSchema = z.object({
-  selected: modelTargetSchema,
+  selected: modelSelectionSchema,
 }) satisfies z.ZodType<Wire<ResponseValue<'session.selectModel'>>>
 
 /** ContentBlock passthrough: core is merge-extensible — the type discriminant envelope is strict, the rest stays wide. */
diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts
index 2e795928ec..a5fc8fffad 100644
--- a/packages/host/apiproxy/src/api/sessions.ts
+++ b/packages/host/apiproxy/src/api/sessions.ts
@@ -53,8 +53,8 @@ export interface SessionProjectionsBlock {
   values: Partial<SessionProjectionMap>
 }
 
-/** Complete model target selected for one session. */
-export interface ModelTarget {
+/** Complete model selection for one session. */
+export interface ModelSelection {
   /** Registered provider route. */
   provider: string
   /** Provider-owned model id. */
@@ -115,8 +115,8 @@ export interface ModelCatalogFailure {
 
 /** Detached model-directory snapshot for one session. */
 export interface SessionModels {
-  /** Target selected for the session's next assembled step. */
-  current: ModelTarget
+  /** Model selection for the session's next assembled step. */
+  current: ModelSelection
   /**
    * Whether an adapter currently serves `current.provider`, and therefore
    * whether this session can start a turn at all. Deliberately NOT derivable
@@ -240,7 +240,7 @@ export interface SessionsApi {
   models(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<SessionModels>>
 
   /**
-   * Selects the complete target for this session. Exact model metadata
+   * Selects the complete model selection for this session. Exact model metadata
    * validates an optional reasoning effort, while catalog membership remains
    * advisory. Session-backed subagents reject with `agent-busy`.
    */
@@ -250,7 +250,7 @@ export interface SessionsApi {
     model: string
     reasoningEffort?: string
   }>):
-  Promise<RpcResponse<{ selected: ModelTarget }>>
+  Promise<RpcResponse<{ selected: ModelSelection }>>
 
   /**
    * Renames a session: appends a `session/title` event with the `user`
diff --git a/packages/host/apiproxy/src/index.ts b/packages/host/apiproxy/src/index.ts
index 1a6e0be281..667e85bdac 100644
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -7,28 +7,24 @@
  * `ctx.apiProxy`). Transport-agnostic by design: this package registers no
  * routes — physical carriers wrap `ctx.apiProxy` themselves.
  *
- * The gateway also owns the `api-gateway` settings section: the route a
- * session starts from when its own log names none. The composition entry is
- * the shipped default and the section layers the user's choice over it, so
- * switching models in a conversation is what sets the default for the next
- * one. Sessions that have already logged a route are never retargeted by it.
+ * The gateway consumes `ctx.agentDefaultModel`, the transport-independent default
+ * shared with direct front doors. Switching models persists through that
+ * service; sessions that have already logged a selection remain unchanged.
  */
 
 import { resolve } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import type { AgentLlmTarget } from '@deepseek-ai/dsh-agent'
-import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
-import { installSettingsSection } from '@deepseek-ai/dsh-settings'
+import type {} from '@deepseek-ai/dsh-agent-default-model'
 import type { ApiProxy } from './api/index.ts'
-import { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from './api-proxy.ts'
+import { createApiProxy } from './api-proxy.ts'
 
 export type * from './api/index.ts'
 export { RpcId } from './api/rpc.ts'
 export { toFetchHandler } from './fetch/handler.ts'
 export { AbstractApiClient, InProcessApiClient } from './fetch/client.ts'
 export type { IApiClient } from './fetch/client.ts'
-export { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from './api-proxy.ts'
+export { createApiProxy } from './api-proxy.ts'
 export type { ApiProxyDefaults } from './api-proxy.ts'
 
 declare module 'cordis' {
@@ -38,62 +34,12 @@ declare module 'cordis' {
   }
 }
 
-/**
- * The `api-gateway` settings section: the route a session starts from when its
- * own log names none. `workspaceRoot` is deliberately not part of it — that is
- * a launcher fact, not a preference.
- */
-export interface DefaultRouteSettings {
-  /** Default provider route for created agents. */
-  provider: string
-  /** Default model id. */
-  model: string
-  /** Default reasoning effort; absence preserves the adapter/provider default. */
-  reasoningEffort?: string
-}
-
-/**
- * Gateway plugin config: host-level agent routing and Workspace creation root.
- *
- * `reasoningEffort` is deliberately absent, so the section carries one field
- * the composition cannot. The seam resolves a section by MERGING the user
- * layer over the composition entry per field, and an absent key cannot
- * override a present one — so a composition-set effort would survive every
- * later switch to a model that has none, and strand it for the next session
- * to fail on. Effort is a per-model fact anyway: a deployment default belongs
- * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
- * which resolves per model rather than per gateway.
- */
+/** Gateway plugin config: the Host-only Workspace creation root. */
 export interface Config {
-  /** Default provider route for created agents. */
-  provider: string
-  /** Default model id. */
-  model: string
   /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
   workspaceRoot?: string
 }
 
-/**
- * Schema of the `api-gateway` section, exported because it IS that section's
- * contract — the shape anything reading or writing `settings.yaml` addresses.
- */
-export const DEFAULT_ROUTE_SCHEMA: z<DefaultRouteSettings> = z.object({
-  provider: z.string().required(),
-  model: z.string().required(),
-  reasoningEffort: z.string(),
-})
-
-/** Project the stored/composed section onto the agent-facing target shape. */
-function routeTarget(settings: DefaultRouteSettings): AgentLlmTarget {
-  return {
-    provider: settings.provider,
-    model: settings.model,
-    ...settings.reasoningEffort === undefined
-      ? {}
-      : { reasoningEffort: ReasoningEffortId(settings.reasoningEffort) },
-  }
-}
-
 /**
  * The API gateway service: implements the ApiProxy contract over the composed
  * host context and provides it as `ctx.apiProxy`. The Host cwd is the default
@@ -101,13 +47,11 @@ function routeTarget(settings: DefaultRouteSettings): AgentLlmTarget {
  */
 export class ApiProxyService extends Service implements ApiProxy {
   static inject = [
-    'agents', 'directoryPicker', 'llm', 'sessions', 'subagents', 'sessionQuery',
+    'agentDefaultModel', 'agents', 'directoryPicker', 'llm', 'sessions', 'subagents', 'sessionQuery',
     'tools', 'userInteraction', 'workspace',
   ]
 
   static Config: z<Config> = z.object({
-    provider: z.string().required(),
-    model: z.string().required(),
     workspaceRoot: z.string(),
   })
 
@@ -127,30 +71,9 @@ export class ApiProxyService extends Service implements ApiProxy {
   constructor(ctx: Context, config: Config) {
     super(ctx, 'apiProxy')
     const cwd = process.cwd()
-    // The composition entry is the shipped default; the settings section
-    // layers the user's own choice over it, and a deployment without a
-    // settings provider simply keeps the entry.
-    const entry: DefaultRouteSettings = { provider: config.provider, model: config.model }
-    let route: () => DefaultRouteSettings = () => entry
-    installSettingsSection(ctx, API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA, entry, {
-      setSource: (current) => {
-        route = current
-      },
-      // Nothing registration-level derives from the default: every consumer
-      // reads it through the thunk at the moment it needs a route.
-      onChange: () => {},
-    })
     const api = createApiProxy(ctx, {
-      defaultTarget: () => routeTarget(route()),
-      // Wholesale, never a merge: switching to a model with no reasoning
-      // effort must clear a stored one, and a merged patch would strand it
-      // for the next session to fail on. This clears it because the entry
-      // below the user layer carries no effort to re-inherit — the reason
-      // `Config` deliberately has no such field. The section holds no
-      // secrets, so there is nothing a replace can collaterally drop.
-      persistDefaultTarget: async (target) => {
-        await ctx.get('settings')?.replace(API_GATEWAY_SETTINGS_NAMESPACE, target)
-      },
+      defaultModelSelection: () => ctx.agentDefaultModel.currentSelection(),
+      saveDefaultModelSelection: selection => ctx.agentDefaultModel.saveSelection(selection),
       cwd,
       workspaceRoot: resolve(config.workspaceRoot ?? cwd),
     })
diff --git a/packages/host/apiproxy/tests/api-proxy-approval.spec.ts b/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
index e6555898cd..2272c7c61d 100644
--- a/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
@@ -27,7 +27,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
   await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(ApprovalService)
-  const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+  const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
   return { ctx, api }
 }
 
@@ -217,7 +217,7 @@ describe('approval pending registry', () => {
     await ctx.plugin(ApprovalService)
     let api!: ApiProxy
     const fiber = ctx.plugin(Object.assign((fiberCtx: Context) => {
-      api = createApiProxy(fiberCtx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+      api = createApiProxy(fiberCtx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     }, { inject: ['sessions', 'agents', 'userInteraction', 'approval'] }))
     await fiber.await()
     const abort = new AbortController()
diff --git a/packages/host/apiproxy/tests/api-proxy-blank.spec.ts b/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
index 4943c051bb..ed2eaeefc5 100644
--- a/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
@@ -35,7 +35,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy; attach: (sessio
   await ctx.plugin(AgentRegistry)
   return {
     ctx,
-    api: createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
+    api: createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
     attach: (session) => {
       ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
     },
diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
index 8e79c641a8..be76bf4cc6 100644
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -64,7 +64,7 @@ describe('sessions.list cold merge', () => {
         return undefined
       },
     })
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const response = await api.sessions.list(request({}))
     expect(response.result.ok).toBe(true)
@@ -92,7 +92,7 @@ describe('attached updatedAt excludes end-seed', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(UserInteractionService)
     await ctx.plugin(AgentRegistry)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     // Old work, resumed just now: the log tail would report the pickup.
     const worked = 1_000_000
@@ -150,7 +150,7 @@ describe('cold history recovery view', () => {
       inspect: (id: SessionId, signal?: AbortSignal) => coordinator.inspect(id, signal),
       locate: () => undefined,
     } as never)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const history = await api.sessions.history(request({ sessionId, beforeSeq: 2, maxMessages: 10 }))
     if (!history.result.ok) throw new Error('history failed')
@@ -206,7 +206,7 @@ describe('Remote Agent and Session lookup policy', () => {
     })
     const defaultAgentLookup = ctx.typert.lookups.get('agent')
     const defaultSessionLookup = ctx.typert.lookups.get('session')
-    createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     await vi.waitFor(() => {
       expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
       expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
@@ -250,7 +250,7 @@ describe('Remote Agent and Session lookup policy', () => {
     const resume = vi.spyOn(ctx.agents, 'resume')
     const defaultAgentLookup = ctx.typert.lookups.get('agent')
     const defaultSessionLookup = ctx.typert.lookups.get('session')
-    createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     await vi.waitFor(() => {
       expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
       expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
@@ -312,7 +312,7 @@ describe('subagent ownership fence', () => {
       locate: () => undefined,
     } as never)
     const resume = vi.spyOn(ctx.agents, 'resume')
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const history = await api.sessions.history(request({ sessionId }))
     expect(history.result.ok).toBe(true)
@@ -371,7 +371,7 @@ describe('subagent ownership fence', () => {
     // instead of answering `agent-busy`.
     const resume = vi.spyOn(ctx.agents, 'resume')
       .mockRejectedValue(new Error('registry unavailable in this bench'))
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const prompt = await api.sessions.prompt(request({
       sessionId,
@@ -412,7 +412,7 @@ describe('subagent ownership fence', () => {
     })
     const startingChild = { id: startingSession.id, session: startingSession, status: 'idle', ctx } as Agent
     ctx.agents.enter(startingChild, parent)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const stopped = await api.sessions.cancel(request({ sessionId: originChild.id }))
     expect(stopped.result.ok).toBe(false)
@@ -458,7 +458,7 @@ describe('subagent ownership fence', () => {
     const followup = vi.fn()
     const agent = { id: session.id, session, status: 'idle', ctx, followup } as unknown as Agent
     ctx.agents.register(agent)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const response = await api.sessions.prompt(request({
       sessionId: agent.id,
@@ -476,7 +476,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const listed = await api.sessions.list(request({}))
     expect(listed.result.ok).toBe(true)
@@ -501,7 +501,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
       list: () => Promise.resolve([]),
       inspect,
     } as never)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const response = await api.sessions.history(request({ sessionId: sid('session-missing') }))
     expect(response.result.ok).toBe(false)
@@ -527,7 +527,7 @@ describe('sessions.prompt synchronous rejection', () => {
       followup: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
       steer: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
     } as unknown as Agent)
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     for (const mode of ['queue', 'steer'] as const) {
       const response = await api.sessions.prompt(request({
@@ -571,7 +571,7 @@ describe('sessions.prompt synchronous rejection', () => {
       ctx.agents.register(child)
       throw new Error('session id already published')
     })
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const models = await api.sessions.models(request({ sessionId }))
     expect(models.result.ok).toBe(false)
diff --git a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
index 09526c5a87..b44701fca0 100644
--- a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
@@ -25,7 +25,7 @@ import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
 import { createApiProxy } from '../src/api-proxy.ts'
 
-const DEFAULTS = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
+const DEFAULTS = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
 
 function request<P>(payload: P): RpcRequest<P> {
   return { rpcId: RpcId(`req-${String(nextRpc++)}`), payload }
diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
index 86a77f4af2..0beb7455cf 100644
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -22,9 +22,10 @@ import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepsee
 import type { HostFrame } from '../src/api/index.ts'
 import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
-import { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from '../src/api-proxy.ts'
+import { AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE } from '@deepseek-ai/dsh-agent-default-model'
+import { createApiProxy } from '../src/api-proxy.ts'
 
-const DEFAULTS = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
+const DEFAULTS = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
 
 let nextRpc = 1
 function request<P>(payload: P): RpcRequest<P> {
@@ -398,21 +399,21 @@ describe('settings domain', () => {
     expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'permission' }])
   })
 
-  it('invalidates the model catalog when the gateway default route changes', async () => {
+  it('invalidates the model catalog when the Agent default selection changes', async () => {
     const ctx = await harness()
-    const route = ctx.settings.register(API_GATEWAY_SETTINGS_NAMESPACE, z.object({
+    const defaultModel = ctx.settings.register(AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE, z.object({
       provider: z.string().required(),
       model: z.string().required(),
     }), { base: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } })
     const api = createApiProxy(ctx, DEFAULTS)
-    // The gateway's own section names the route every session with no logged
-    // one resolves to, so an externally edited default — another tab, a
+    // The shared section names the selection every blank session resolves to,
+    // so an externally edited default — another tab, a
     // hand-edited settings.yaml — has to reach an open selector as well.
     const frames = await collectHost(api, ['host/settings-changed', 'host/models-changed'], 2, async () => {
-      await route.replace({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
+      await defaultModel.replace({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
     })
     expect(frames).toEqual([
-      { type: 'host/settings-changed', ns: 'api-gateway' },
+      { type: 'host/settings-changed', ns: 'agent-default-model' },
       { type: 'host/models-changed' },
     ])
   })
diff --git a/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts b/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts
deleted file mode 100644
index 996cea5da2..0000000000
--- a/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-/**
- * The `api-gateway` settings section over a REAL settings provider: the
- * composition entry as the base layer, the wholesale replace the gateway
- * persists with, and the fallback when the provider detaches. The other model
- * specs drive hand-rolled `defaultTarget`/`persistDefaultTarget` closures, so
- * this is the only place the layering itself is exercised.
- */
-
-import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
-import { Settings, installSettingsSection } from '@deepseek-ai/dsh-settings'
-import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
-import { API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA } from '../src/index.ts'
-import type { DefaultRouteSettings } from '../src/index.ts'
-
-/** The smallest real provider: one in-memory document, always writable. */
-class MemorySettings extends Settings {
-  doc: Record<string, unknown> = {}
-
-  get writable(): boolean {
-    return true
-  }
-
-  protected load(): Promise<Record<string, unknown>> {
-    return Promise.resolve(structuredClone(this.doc))
-  }
-
-  protected persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
-    this.doc = { ...this.doc, [ns]: structuredClone(section) }
-    return Promise.resolve()
-  }
-}
-
-/** Mount the gateway's own section wiring over a live provider. */
-async function boot(entry: DefaultRouteSettings) {
-  const ctx = new Context()
-  const fiber = ctx.plugin(MemorySettings)
-  await fiber.await()
-  let route: () => DefaultRouteSettings = () => entry
-  const consumer = ctx.plugin(function section(child: Context) {
-    installSettingsSection(child, API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA, entry, {
-      setSource: (current) => { route = current },
-      onChange: () => {},
-    })
-  })
-  await consumer.await()
-  const settings = ctx.get('settings')
-  if (settings === undefined) throw new Error('settings provider did not mount')
-  return { ctx, fiber, consumer, settings, read: () => route() }
-}
-
-describe('the api-gateway default-route section', () => {
-  it('resolves the composition entry until the user layer overrides it', async () => {
-    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-
-    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
-      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
-    })
-    expect(bench.read()).toEqual({
-      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
-    })
-    await bench.ctx.fiber.dispose()
-  })
-
-  it('clears a stored effort when the next switch has none', async () => {
-    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
-      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
-    })
-    expect(bench.read().reasoningEffort).toBe('high')
-
-    // The whole reason the gateway persists with `replace` rather than a merge
-    // patch — and the reason `Config` carries no effort for the base layer to
-    // re-inherit here. A stranded effort would fail the next session's first
-    // request against a model that does not support it.
-    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
-      provider: 'acme-gateway', model: 'acme-plain',
-    })
-    expect(bench.read()).toEqual({ provider: 'acme-gateway', model: 'acme-plain' })
-    await bench.ctx.fiber.dispose()
-  })
-
-  it('layers a hand-written partial section over the entry', async () => {
-    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-    // Someone editing settings.yaml by hand may name only the model. The
-    // entry supplies the provider, which is what makes this legal — and is
-    // exactly why an effort in the entry could never be cleared, so there
-    // is none to inherit.
-    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, { model: 'deepseek-reasoner' })
-    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
-    await bench.ctx.fiber.dispose()
-  })
-
-  it('falls back to the composition entry when the provider detaches', async () => {
-    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
-      provider: 'acme-gateway', model: 'acme-large',
-    })
-    expect(bench.read().provider).toBe('acme-gateway')
-
-    // A deployment that loses its settings provider keeps serving the route it
-    // was composed with rather than the one it can no longer read.
-    await bench.fiber.dispose()
-    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
-    await bench.ctx.fiber.dispose()
-  })
-})
diff --git a/packages/host/apiproxy/tests/api-proxy-fork.spec.ts b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
index fb6f8cdfed..bc1f0a14df 100644
--- a/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
@@ -82,7 +82,7 @@ function liveAgent(
 }
 
 const api = (ctx: Context) => createApiProxy(ctx, {
-  defaultTarget: () => ({ provider: 'default-provider', model: 'default-model' }),
+  defaultModelSelection: () => ({ provider: 'default-provider', model: 'default-model' }),
   cwd: '/tmp',
   workspaceRoot: '/tmp',
 })
@@ -254,7 +254,7 @@ describe('sessions.fork', () => {
     await ctx.fiber.dispose()
   })
 
-  it('installs the latest logged model target before the child can run', async () => {
+  it('installs the latest logged model selection before the child can run', async () => {
     const ctx = await composed()
     const source = liveAgent(ctx, 'session-routed', 1)
     source.append('request/header', {
diff --git a/packages/host/apiproxy/tests/api-proxy-models.spec.ts b/packages/host/apiproxy/tests/api-proxy-models.spec.ts
index 818260504c..83d0fa3916 100644
--- a/packages/host/apiproxy/tests/api-proxy-models.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-models.spec.ts
@@ -1,6 +1,6 @@
 /**
  * Web session model-directory and selection behavior: dynamic provider grouping,
- * provider-local catalog failures, logged-target restoration without stale
+ * provider-local catalog failures, logged-selection restoration without stale
  * catalog injection, advisory pass-through models, and the prompt-assembly
  * boundary for a running selection change.
  */
@@ -119,13 +119,13 @@ function expectValue<T>(response: { result: { ok: true; value: T } | { ok: false
 }
 
 describe('Web session model selection', () => {
-  it('groups successful providers and leaves an unlisted current target out of the catalog', async () => {
+  it('groups successful providers and leaves an unlisted current selection out of the catalog', async () => {
     const { ctx, sessionId } = await harness({
       provider: 'deepseek-official',
       model: 'private-preview',
       reasoningEffort: ReasoningEffortId('max'),
     })
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const catalog = expectValue(await api.sessions.models(request({ sessionId })))
     expect(catalog.current).toEqual({
@@ -160,7 +160,7 @@ describe('Web session model selection', () => {
 
   it('accepts an advisory-unlisted model, rejects an unavailable provider, and switches only after the next assembly', async () => {
     const { ctx, agent, sessionId } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
     const signal = new AbortController().signal
 
@@ -226,11 +226,11 @@ describe('Web session model selection', () => {
     await ctx.fiber.dispose()
   })
 
-  it('reads the host default live for a session whose log names no route', async () => {
+  it('reads the Agent default live for a session whose log names no selection', async () => {
     const { ctx, sessionId } = await harness()
     let stored = { provider: 'deepseek-official', model: 'deepseek-chat' }
     const api = createApiProxy(ctx, {
-      defaultTarget: () => stored,
+      defaultModelSelection: () => stored,
       cwd: '/tmp',
       workspaceRoot: '/tmp',
     })
@@ -248,14 +248,14 @@ describe('Web session model selection', () => {
     await ctx.fiber.dispose()
   })
 
-  it('keeps a session that logged a route on it when the host default moves', async () => {
+  it('keeps a session on its logged selection when the Agent default differs', async () => {
     const { ctx, sessionId } = await harness({
       provider: 'deepseek-official',
       model: 'deepseek-chat',
     })
     let stored = { provider: 'deepseek-official', model: 'deepseek-chat' }
     const api = createApiProxy(ctx, {
-      defaultTarget: () => stored,
+      defaultModelSelection: () => stored,
       cwd: '/tmp',
       workspaceRoot: '/tmp',
     })
@@ -271,9 +271,9 @@ describe('Web session model selection', () => {
     const saved: unknown[] = []
     let reject = false
     const api = createApiProxy(ctx, {
-      defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }),
-      persistDefaultTarget: (target) => {
-        saved.push(target)
+      defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }),
+      saveDefaultModelSelection: (selection) => {
+        saved.push(selection)
         return reject ? Promise.reject(new Error('read-only document')) : Promise.resolve()
       },
       cwd: '/tmp',
@@ -306,7 +306,7 @@ describe('Web session model selection', () => {
   it('refuses a prompt no adapter can route, and reports it on the directory', async () => {
     const { ctx, sessionId } = await harness()
     const api = createApiProxy(ctx, {
-      defaultTarget: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
+      defaultModelSelection: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
       cwd: '/tmp',
       workspaceRoot: '/tmp',
     })
@@ -339,7 +339,7 @@ describe('Web session model selection', () => {
     const api = createApiProxy(ctx, {
       // What a Models-page removal leaves behind: the settings document still
       // names the route the user last picked, and nothing serves it.
-      defaultTarget: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
+      defaultModelSelection: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
       cwd: '/tmp',
       workspaceRoot: '/tmp',
     })
diff --git a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
index c9cb212004..ddc558fefd 100644
--- a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
@@ -68,7 +68,7 @@ function seedMessages(session: Session, count: number): void {
   }
 }
 
-const api = (ctx: Context) => createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+const api = (ctx: Context) => createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
 describe('session.history projections block', () => {
   it('serves the unit value on the tail page with asOfSeq = last event seq', async () => {
diff --git a/packages/host/apiproxy/tests/api-proxy-question.spec.ts b/packages/host/apiproxy/tests/api-proxy-question.spec.ts
index 32835f5054..00f7fdfffe 100644
--- a/packages/host/apiproxy/tests/api-proxy-question.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-question.spec.ts
@@ -14,7 +14,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
   await ctx.plugin(UserInteractionService)
   return {
     ctx,
-    api: createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
+    api: createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
   }
 }
 
diff --git a/packages/host/apiproxy/tests/api-proxy-rename.spec.ts b/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
index 2f93cdd9b3..9d5ddb09fd 100644
--- a/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
@@ -68,7 +68,7 @@ function liveAgent(ctx: Context, id: string, turns: number): Session {
   return session
 }
 
-const api = (ctx: Context) => createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+const api = (ctx: Context) => createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
 
 describe('sessions.rename', () => {
   it('accepts through the composed title service: normalized user-source event, echoed seq', async () => {
diff --git a/packages/host/apiproxy/tests/api-proxy-search.spec.ts b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
index 15a4ae3bf3..0220f4804b 100644
--- a/packages/host/apiproxy/tests/api-proxy-search.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
@@ -27,7 +27,7 @@ vi.mock('node:fs/promises', async (importOriginal) => {
 })
 
 const sid = (value: string): SessionId => value as SessionId
-const defaults = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
+const defaults = { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }
 
 function request(query: string): RpcRequest<{ query: string }> {
   return { rpcId: RpcId(`search-${query}`), payload: { query } }
diff --git a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
index 62c7e653e0..7542d328ba 100644
--- a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
@@ -95,7 +95,7 @@ function bench(options: {
   ctx.provide('sessionProjections', { snapshot, restore, onChanged: () => () => {} })
   ctx.provide('userInteraction', { registerProvider: () => () => {} })
   const api = createApiProxy(ctx, {
-    defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp',
+    defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp',
   })
   return { api, getAgent, listChildren, inspect, snapshot, restore, followup, interrupt, parent }
 }
diff --git a/packages/host/apiproxy/tests/api-proxy-view.spec.ts b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
index 4490c71bc2..9810ff5cb8 100644
--- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
@@ -105,7 +105,7 @@ async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: num
 describe('mux live view computation', () => {
   it('attaches the three standard card views, omits view without a presenter, soft-falls on throw', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux'), payload: {} }, abort.signal)
     const collected = collect(stream, 9, abort)
@@ -170,7 +170,7 @@ describe('mux live view computation', () => {
 
   it('serves history entries with call/result views, backscan pairing, and soft-falls', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const session = ctx.sessions.create()
     // history resolves the agent first; a live structural stub is enough (only
     // .session is read on this path).
@@ -238,7 +238,7 @@ describe('mux live view computation', () => {
 
   it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const session = ctx.sessions.create()
     ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
     session.append('turn/start', { turn: 1 })
@@ -287,7 +287,7 @@ describe('mux live view computation', () => {
 
   it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux3'), payload: {} }, abort.signal)
 
@@ -308,7 +308,7 @@ describe('mux live view computation', () => {
 
   it('pairs a result after turn/end via the in-memory backscan fallback', async () => {
     const { ctx } = await harness()
-    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux2'), payload: {} }, abort.signal)
     const collected = collect(stream, 4, abort)
diff --git a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
index aa560bdf58..637c2fcbe0 100644
--- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
@@ -100,7 +100,7 @@ async function harness(
   // object per harness mirrors the seam's stability contract.
   ctx.provide('directoryPicker', { capability: () => picker } as never)
   const api = createApiProxy(ctx, {
-    defaultTarget: () => ({ provider: 'test', model: 'test-model' }),
+    defaultModelSelection: () => ({ provider: 'test', model: 'test-model' }),
     cwd: workspaceRoot,
     workspaceRoot,
     ...extras.openPath === undefined ? {} : { openPath: extras.openPath },
diff --git a/packages/host/apiproxy/tests/client-handler.spec.ts b/packages/host/apiproxy/tests/client-handler.spec.ts
index 476ebf344f..ad95275e38 100644
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -41,7 +41,7 @@ function scriptedApi(overrides: {
       history: r => ok(r, {
         events: [],
         hasMore: false,
-        modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+        modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
       }),
       models: r => ok(r, {
         current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
diff --git a/packages/host/apiproxy/tests/rpc-schemas.spec.ts b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
index 75b6dff3f7..6d2ae5b23c 100644
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -192,7 +192,7 @@ describe('sessions domain schemas', () => {
     expect(sessionHistoryValueSchema.parse({
       events: [],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }).hasMore).toBe(false)
     expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
     expect(sessionModelsValueSchema.parse({
diff --git a/packages/host/apiproxy/tsconfig.json b/packages/host/apiproxy/tsconfig.json
index 64d7944892..eb22348935 100644
--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -35,6 +35,9 @@
     {
       "path": "../../core/agent"
     },
+    {
+      "path": "../../core/agent-default-model"
+    },
     {
       "path": "../../core/session"
     },
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index e8381a56a6..302fd4c9b3 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -62,6 +62,20 @@ export interface TypeApiEntry {
 
 /** Every harness `ctx.<key>` service, sorted by key. */
 export const SERVICE_API: readonly ServiceApiEntry[] = [
+  {
+    key: 'agentDefaultModel',
+    summary: 'Owns the default model selection independently of any Host or transport.',
+    methods: [
+      {
+        signature: 'currentSelection(): ModelSelection',
+        jsDoc: '/**\n * Read the current default model selection.\n * @returns a detached provider, model, and optional reasoning selection.\n */',
+      },
+      {
+        signature: 'async saveSelection(next: ModelSelection): Promise<void>',
+        jsDoc: '/**\n * Save the complete default model selection. A deployment without a settings\n * provider keeps its composition entry.\n * @param next - resolved selection accepted by a front door.\n * @returns fulfillment after the optional settings write settles.\n */',
+      },
+    ],
+  },
   {
     key: 'agentLoop',
     summary: 'Concrete agent factory and driver service.',
@@ -2233,6 +2247,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ModelMessageSource',
     declaration: 'export interface ModelMessageSource extends AssistantProvenance {\n    kind: \'model\';\n}',
   },
+  {
+    name: 'ModelSelection',
+    declaration: 'export interface ModelSelection {\n    provider: string;\n    model: string;\n    reasoningEffort?: ReasoningEffortId;\n}',
+  },
   {
     name: 'ObjectJsonSchema',
     declaration: 'export type ObjectJsonSchema = JsonSchemaNode & {\n    type: \'object\';\n};',
diff --git a/packages/todo/tool-todo/tests/projection.spec.ts b/packages/todo/tool-todo/tests/projection.spec.ts
index 08cb7d3216..d6d459a4d7 100644
--- a/packages/todo/tool-todo/tests/projection.spec.ts
+++ b/packages/todo/tool-todo/tests/projection.spec.ts
@@ -45,7 +45,7 @@ async function harness(withTodoTool: boolean): Promise<Bench> {
   if (withTodoTool) await ctx.plugin(ToolTodo, { allowParallelInProgress: true })
   const session = ctx.sessions.create()
   ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
-  const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+  const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
   return {
     ctx,
     session,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e9726e9bee..bd2eab469c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1013,6 +1013,9 @@ importers:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-default-model':
+        specifier: workspace:^
+        version: link:../../core/agent-default-model
       '@deepseek-ai/dsh-agent-loop':
         specifier: workspace:^
         version: link:../../core/agent-loop
@@ -1233,6 +1236,9 @@ importers:
 
   packages/bundle/headless:
     dependencies:
+      '@deepseek-ai/dsh-code-runtime-worker':
+        specifier: workspace:^
+        version: link:../../code-runtime/code-runtime-worker
       schemastery:
         specifier: ^3.18.0
         version: link:../../../vendor/schemastery
@@ -1243,15 +1249,15 @@ importers:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
-      '@deepseek-ai/dsh-host-apiproxy':
+      '@deepseek-ai/dsh-agent-default-model':
         specifier: workspace:^
-        version: link:../../host/apiproxy
-      '@deepseek-ai/dsh-host-webserver':
-        specifier: workspace:^
-        version: link:../../host/webserver
+        version: link:../../core/agent-default-model
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -2935,6 +2941,28 @@ importers:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
 
+  packages/core/agent-default-model:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-settings':
+        specifier: workspace:^
+        version: link:../../settings/settings
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
   packages/core/agent-loop:
     dependencies:
       schemastery:
@@ -3893,6 +3921,9 @@ importers:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-default-model':
+        specifier: workspace:^
+        version: link:../../core/agent-default-model
       '@deepseek-ai/dsh-api-remotes':
         specifier: workspace:^
         version: link:../../api/remotes
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 66b3cea813..de53d44755 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -44,6 +44,7 @@ export { REGION_BEGIN, REGION_END }
  */
 export const SERVICE_PAGE: Record<string, string> = {
   agentLoop: 'core.md',
+  agentDefaultModel: 'core.md',
   agents: 'core.md',
   approval: 'approval.md',
   bash: 'bash.md',
@@ -196,6 +197,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   AgentCancelCause: 'core.md',
   AgentFactory: 'core.md',
   AgentHandle: 'core.md',
+  ModelSelection: 'core.md',
   AgentOptions: 'core.md',
   AgentStatus: 'core.md',
   ContentBlock: 'llm-streaming.md',
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index cc26b6b0af..745bc23e4f 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -307,6 +307,14 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['agent-loop', 'acp', 'subagent-inprocess'],
     note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
   },
+  {
+    key: 'agentDefaultModel',
+    pkg: 'agent-default-model',
+    title: 'Default Agent model selection',
+    mode: 'core',
+    consumers: ['headless', 'host-apiproxy'],
+    note: 'Layers the default ModelSelection through settings so direct and Host-backed Agent front doors share one state owner.',
+  },
   {
     key: 'agentLoop',
     pkg: 'agent-loop',
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index f25007786c..ded84487bf 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index a0eec4960f..20e6c4bc14 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -48,6 +48,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/core/agent-default-model': { kind: 'indirect', reason: 'The service supplies a ModelSelection; request assembly and adapters own the model-visible request.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
   'packages/e2b/e2b': { kind: 'none', reason: 'The shared remote-runtime owner registers no model context; provider adapters and consumers own rendered effects.' },
@@ -68,7 +69,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/ui-deliverables': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-slash': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
   'packages/client/ui-command': { kind: 'indirect', reason: 'The dispatch paths trigger the host command.execute RPC; each command handler\'s host package owns any model-visible effect.' },
-  'packages/client/ui-model': { kind: 'indirect', reason: 'Selection routes session.selectModel; the host snapshots the target at the next prompt-assembly boundary and owns the model-visible effect.' },
+  'packages/client/ui-model': { kind: 'indirect', reason: 'Selection routes session.selectModel; the Host snapshots the selection at the next prompt-assembly boundary and owns the model-visible effect.' },
   'packages/client/ui-goal': { kind: 'indirect', reason: 'The strip verbs route goal.* mutations; the host GoalService owns the model-visible goal/change context message.' },
   'packages/client/ui-permission': { kind: 'indirect', reason: 'The picker submits the host /permission command; the knob events it appends own the model-visible effect through the sandbox/approval consumers.' },
   'packages/client/ui-plan': { kind: 'indirect', reason: 'The chip dispatches /plan off; dsh-plan-mode owns the model-visible policy, exit tool, and logged state.' },
@@ -94,7 +95,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/host/webserver': { kind: 'none', reason: 'The HTTP carrier bridges browser and API handler and registers no model surface.' },
   'packages/host/frontend-static': { kind: 'none', reason: 'The SPA dist server answers browser asset requests and registers no model surface.' },
   'packages/bundle/base': { kind: 'indirect', reason: 'The bundle is a patch-list carrier; each inserted row\'s package owns its model surface.' },
-  'packages/bundle/headless': { kind: 'none', reason: 'The one-shot runner submits the task as an ordinary user message; prompts and tools belong to the composed base/web bundles.' },
+  'packages/bundle/headless': { kind: 'none', reason: 'The one-shot runner submits the task as an ordinary user message; prompts and tools belong to the composed base and headless bundles.' },
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 31631995cf..f890487f3b 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -138,6 +138,7 @@
     { "path": "./packages/session/session-telemetry-otel" },
     { "path": "./packages/core/system-prompt" },
     { "path": "./packages/core/agent" },
+    { "path": "./packages/core/agent-default-model" },
     { "path": "./packages/interaction/commands" },
     { "path": "./packages/goal/goal" },
     { "path": "./packages/goal/tool-goal" },

From 63b6e18f71e9e5f65ce344714cde6083e3ffba02 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 13:35:00 +0800
Subject: [PATCH 456/516] fix(headless): terminal model failures reach stderr

---
 ...-headless-direct-core-front-door.i18n.yaml |  4 +-
 ...6-08-09-headless-direct-core-front-door.md |  4 +-
 ...8-09-headless-direct-core-front-door.zh.md |  4 +-
 .../tests/fixtures/cli-mock-llm.ts            |  4 ++
 .../headless-agent/tests/headless.snapshot.ts | 41 +++++++++++++++----
 .../snapshots/dsh-run/stderr.expected.txt     |  1 +
 packages/bundle/headless/README.i18n.yaml     |  4 +-
 packages/bundle/headless/README.md            |  2 +-
 packages/bundle/headless/README.zh.md         |  2 +-
 packages/bundle/headless/src/index.ts         | 11 +++--
 .../bundle/headless/tests/headless.spec.ts    | 21 ++++++++++
 11 files changed, 76 insertions(+), 22 deletions(-)
 create mode 100644 examples/headless-agent/tests/snapshots/dsh-run/stderr.expected.txt

diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
index cab1c8e338..921bc193e4 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.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 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
-2026-08-09-headless-direct-core-front-door.md: cae17970633d6eda9d4f823118827ee2bfe32abf
-2026-08-09-headless-direct-core-front-door.zh.md: 8ff5e870b7f0fbc82065c6c55b4635cdc586036c
+2026-08-09-headless-direct-core-front-door.md: 875939b424059907949e350d50d88ded331f3dc9
+2026-08-09-headless-direct-core-front-door.zh.md: 7de5efbe172c0c43c03d55724d27e32d08c11e9f
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
index cae1797063..875939b424 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
@@ -14,7 +14,7 @@ The direct front door still needs the same deployment model state as Web-created
 
 The shipped `headless` profile contains `dsh-base` and `dsh-headless`. The headless bundle supplies its persona and tool mode, disables HMR, mounts the Code Mode worker explicitly, and inserts `headless-runner`. Its tree contains no `@deepseek-ai/dsh-host-*` package, ApiProxy, HTTP server, Web runtime, or browser client. Code Mode and Session persistence are one-shot Agent capabilities independent of Web presentation.
 
-`headless-runner` is a direct core front door. After Loader settlement, it reads `ctx.agentDefaultModel.currentSelection()`, creates a fresh persisted Agent through `ctx.agents.create`, installs that `ModelSelection` in the Agent scope, waits for startup quiescence, anchors the Session sequence, submits one ordinary user message, and waits for quiescence again. It awaits `ctx.sessions.flush`, folds its durable event interval for the last non-empty assistant text and final `turn/end` reason, writes the text plus one newline to stdout, and requests bounded launcher shutdown with exit 0 exactly when the reason is `completed`. Unexpected driver failures use stderr and exit 1.
+`headless-runner` is a direct core front door. After Loader settlement, it reads `ctx.agentDefaultModel.currentSelection()`, creates a fresh persisted Agent through `ctx.agents.create`, installs that `ModelSelection` in the Agent scope, waits for startup quiescence, anchors the Session sequence, submits one ordinary user message, and waits for quiescence again. It awaits `ctx.sessions.flush`, folds its durable event interval for the last non-empty assistant text and final `turn/end` reason, writes the text plus one newline to stdout, and requests bounded launcher shutdown with exit 0 exactly when the reason is `completed`. A terminal `error` reason writes its durable code and message to stderr; unexpected driver failures also use stderr and exit 1.
 
 `@deepseek-ai/dsh-agent-default-model` owns the transport-independent default used for an Agent without a session-local selection. `AgentDefaultModelService` provides `ctx.agentDefaultModel` and registers the `agent-default-model` Settings section. Composition config supplies `{provider, model}`; user settings may also supply `reasoningEffort`. `currentSelection()` returns the live complete selection and `saveSelection()` writes it as a complete section, so a selection without an effort clears any stored effort. `dsh-base` supplies the composition entry. Direct and ApiProxy front doors consume this service; ApiProxy alone owns session-local precedence, model validation, and persistence of accepted Web selections.
 
@@ -24,7 +24,7 @@ This note owns the headless transport and completion contracts. [`dsh run` owns
 
 ## Verification
 
-Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshot drives `dsh run` through a replayed tool round trip and records direct user-message provenance. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
+Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, terminal model diagnostics, other non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshots drive `dsh run` through a replayed tool round trip, record direct user-message provenance, and expose a terminal model failure on stderr. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
index 8ff5e870b7..7de5efbe17 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 随附的 `headless` profile 包含 `dsh-base` 与 `dsh-headless`。headless 组合包提供自身的 persona 与工具模式、禁用 HMR（热模块替换）、显式挂载 Code Mode worker，并插入 `headless-runner`。其插件树不包含任何 `@deepseek-ai/dsh-host-*` 包、ApiProxy、HTTP server、Web 运行时或浏览器客户端。Code Mode 与会话持久化均为独立于 Web 呈现的一次性 Agent 能力。
 
-`headless-runner` 是直接使用核心服务的入口。Loader 完全加载后，它读取 `ctx.agentDefaultModel.currentSelection()`，通过 `ctx.agents.create` 创建一个新的持久化 Agent，在 Agent 作用域中安装该 `ModelSelection`，等待启动工作完全停稳，锚定会话事件序号，提交一条普通用户消息，再次等待完全停稳。随后，它等待 `ctx.sessions.flush`，折叠自身持有的持久事件区间，以取得最后一条非空 assistant 文本和最终 `turn/end` 结束原因，将文本连同一个换行写入 stdout，并且仅在结束原因为 `completed` 时请求启动器以退出状态 0 有界关闭。驱动器的意外失败写入 stderr 并以 1 退出。
+`headless-runner` 是直接使用核心服务的入口。Loader 完全加载后，它读取 `ctx.agentDefaultModel.currentSelection()`，通过 `ctx.agents.create` 创建一个新的持久化 Agent，在 Agent 作用域中安装该 `ModelSelection`，等待启动工作完全停稳，锚定会话事件序号，提交一条普通用户消息，再次等待完全停稳。随后，它等待 `ctx.sessions.flush`，折叠自身持有的持久事件区间，以取得最后一条非空 assistant 文本和最终 `turn/end` 结束原因，将文本连同一个换行写入 stdout，并且仅在结束原因为 `completed` 时请求启动器以退出状态 0 有界关闭。结束原因为 `error` 时，其持久化错误码与消息写入 stderr；驱动器的意外失败也写入 stderr 并以 1 退出。
 
 `@deepseek-ai/dsh-agent-default-model` 拥有与传输无关的默认值，供没有会话级选择的 Agent 使用。`AgentDefaultModelService` 提供 `ctx.agentDefaultModel` 并注册 `agent-default-model` Settings 分节。组合配置提供 `{provider, model}`，用户设置还可以提供 `reasoningEffort`。`currentSelection()` 返回当前的完整选择，`saveSelection()` 则写入完整分节，因此不含强度的选择会清除已存强度。`dsh-base` 提供组合条目。直接前门与 ApiProxy 前门均消费该服务；只有 ApiProxy 负责会话级优先级、模型校验与已接受 Web 选择的持久化。
 
@@ -24,7 +24,7 @@ Status: implemented
 
 ## 验证
 
-包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，并记录直接用户消息的来源。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
+包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、终止态模型诊断、其他未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，记录直接用户消息的来源，并在 stderr 暴露终止态模型失败。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
 
 ## 考虑过的替代方案
 
diff --git a/examples/headless-agent/tests/fixtures/cli-mock-llm.ts b/examples/headless-agent/tests/fixtures/cli-mock-llm.ts
index 80a4f7e240..b0b120ecb2 100644
--- a/examples/headless-agent/tests/fixtures/cli-mock-llm.ts
+++ b/examples/headless-agent/tests/fixtures/cli-mock-llm.ts
@@ -29,6 +29,10 @@ class CliMockAdapter extends LlmAdapter {
   }
 
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    if (process.env.DSH_CLI_MOCK_FAILURE === '1') {
+      yield { type: 'finish', reason: { kind: 'error', failure: { code: 'SERVER', message: 'CLI mock provider failed' } } }
+      return
+    }
     const toolResult = options.messages.at(-1)?.content.find(block => block.type === 'tool-result')
     if (toolResult === undefined) {
       const args = JSON.stringify({ command: 'printf CLI_TOOL_ROUND_TRIP', description: 'Prove the CLI tool round trip.' })
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index 593b05b4e8..ff00d42b6b 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -54,6 +54,7 @@ const reasoningConfigPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', i
 const deepseekDefaultsConfigPath = fileURLToPath(new URL('./fixtures/deepseek-defaults.cordis.yml', import.meta.url))
 const dshRunOverlayPath = fileURLToPath(new URL('./fixtures/dsh-run.cordis.yml', import.meta.url))
 const dshRunSessionExpected = join(snapshotsDir, 'dsh-run', 'session.expected.jsonl')
+const dshRunFailureExpected = join(snapshotsDir, 'dsh-run', 'stderr.expected.txt')
 const cliMockLlmPluginPath = fileURLToPath(new URL('./fixtures/cli-mock-llm.ts', import.meta.url))
 const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
 
@@ -196,6 +197,16 @@ async function persistedLogs(cwd: string, root: string = join(cwd, '.sessions'))
   }))
 }
 
+/** Install the keyless product-CLI adapter into the temporary headless profile. */
+async function prepareCliMockFixture(cwd: string): Promise<void> {
+  const fixtureDir = join(cwd, '.dsh', 'profiles', 'headless', 'snapshot-fixtures')
+  await mkdir(fixtureDir, { recursive: true })
+  await Promise.all([
+    copyFile(cliMockLlmPluginPath, join(fixtureDir, 'cli-mock-llm.ts')),
+    writeFile(join(fixtureDir, 'package.json'), '{"type":"module"}\n'),
+  ])
+}
+
 describe('headless stream-json snapshots', () => {
   it('runs one task through the product dsh run command', async () => {
     const task = 'Prove the product dsh run path with one real tool round trip.'
@@ -211,14 +222,7 @@ describe('headless stream-json snapshots', () => {
         DSH_TELEMETRY_DISABLED: '1',
         NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
       },
-      prepare: async (cwd) => {
-        const fixtureDir = join(cwd, '.dsh', 'profiles', 'headless', 'snapshot-fixtures')
-        await mkdir(fixtureDir, { recursive: true })
-        await Promise.all([
-          copyFile(cliMockLlmPluginPath, join(fixtureDir, 'cli-mock-llm.ts')),
-          writeFile(join(fixtureDir, 'package.json'), '{"type":"module"}\n'),
-        ])
-      },
+      prepare: prepareCliMockFixture,
       inspect: async (cwd) => {
         const logs = await persistedLogs(cwd, join(cwd, '.dsh', 'sessions'))
         expect(logs).toHaveLength(1)
@@ -237,6 +241,27 @@ describe('headless stream-json snapshots', () => {
     expect(result.stderr).toBe('')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
+  it('prints a terminal model failure through the product dsh run command', async () => {
+    const result = await runLoaderSmoke({
+      label: 'product dsh run model failure snapshot',
+      tempDirPrefix: 'headless-snapshot-dsh-run-failure-',
+      binScript: dshBinScript,
+      configPath: dshRunOverlayPath,
+      binArgs: ['run', '--patch', dshRunOverlayPath, 'Trigger the keyless model failure.'],
+      tsconfigPath,
+      expectedExitCode: 1,
+      env: {
+        DSH_CLI_MOCK_FAILURE: '1',
+        DSH_TELEMETRY_DISABLED: '1',
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      prepare: prepareCliMockFixture,
+    })
+
+    expect(result.stdout).toBe('\n')
+    await expect(result.stderr).toMatchFileSnapshot(dshRunFailureExpected)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
   it('prints the original Loader activation error through the assembled one-shot app', async () => {
     const result = await runLoaderSmoke({
       label: 'headless startup activation error snapshot',
diff --git a/examples/headless-agent/tests/snapshots/dsh-run/stderr.expected.txt b/examples/headless-agent/tests/snapshots/dsh-run/stderr.expected.txt
new file mode 100644
index 0000000000..79665a83c3
--- /dev/null
+++ b/examples/headless-agent/tests/snapshots/dsh-run/stderr.expected.txt
@@ -0,0 +1 @@
+dsh: SERVER: CLI mock provider failed
diff --git a/packages/bundle/headless/README.i18n.yaml b/packages/bundle/headless/README.i18n.yaml
index ea768061df..4d43c64eb3 100644
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/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/bundle/headless/README.md
-README.md: 6faf1dc732345a86ec1d7b60c4f9a606e0491512
-README.zh.md: a189f77f57cf0f641abe7c11288dbc1cdf05355a
+README.md: fbdf80be3d587b0ef526c1a36952a761035f7312
+README.zh.md: 833737e08643e0ad6b585f93fdc6ae018242b937
diff --git a/packages/bundle/headless/README.md b/packages/bundle/headless/README.md
index 6faf1dc732..fbdf80be3d 100644
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`). It mounts no Host, HTTP server, Web runtime, or browser plugin.
 
-After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` seam (final `turn/end` completed → 0, otherwise 1). A successful run writes nothing to stderr and opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` seam (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
 
 ## Model Experience
 
diff --git a/packages/bundle/headless/README.zh.md b/packages/bundle/headless/README.zh.md
index a189f77f57..833737e086 100644
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -4,7 +4,7 @@
 
 dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
 
-Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（最终 `turn/end` 完成 → 0，否则为 1）。成功运行时不会向 stderr 写入任何内容，也不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
 
 ## 模型体验
 
diff --git a/packages/bundle/headless/src/index.ts b/packages/bundle/headless/src/index.ts
index 670838661a..2ea68c441b 100644
--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -38,7 +38,7 @@ export const Config: z<Config> = z.object({
 /** Outcome of one owned run interval. */
 interface RunOutcome {
   text: string
-  reason: string
+  reason: SessionEvent<'turn/end'>['data']['reason'] | undefined
 }
 
 /**
@@ -63,7 +63,7 @@ declare module 'cordis' {
 function summarize(events: readonly SessionEvent[], firstSeq: number): RunOutcome {
   let started = false
   let text = ''
-  let reason = 'error'
+  let reason: SessionEvent<'turn/end'>['data']['reason'] | undefined
   for (const event of events) {
     if (event.seq < firstSeq) continue
     if (event.type === 'turn/start') {
@@ -78,7 +78,7 @@ function summarize(events: readonly SessionEvent[], firstSeq: number): RunOutcom
         .join('')
       if (joined !== '') text = joined
     }
-    if (event.type === 'turn/end') reason = event.data.reason.kind
+    if (event.type === 'turn/end') reason = event.data.reason
   }
   return { text, reason }
 }
@@ -125,7 +125,10 @@ async function run(ctx: Context, task: string, io: HeadlessIo): Promise<void> {
   await sessions.flush(agent.session)
   const outcome = summarize(agent.session.events, firstSeq)
   io.stdout.write(outcome.text + '\n')
-  io.exit(outcome.reason === 'completed' ? 0 : 1)
+  if (outcome.reason?.kind === 'error') {
+    io.stderr.write(`dsh: ${outcome.reason.error.code}: ${outcome.reason.error.message}\n`)
+  }
+  io.exit(outcome.reason?.kind === 'completed' ? 0 : 1)
 }
 
 /**
diff --git a/packages/bundle/headless/tests/headless.spec.ts b/packages/bundle/headless/tests/headless.spec.ts
index 294c224354..bd24a9300a 100644
--- a/packages/bundle/headless/tests/headless.spec.ts
+++ b/packages/bundle/headless/tests/headless.spec.ts
@@ -151,6 +151,27 @@ describe('headless runner', () => {
     await test.ctx.fiber.dispose()
   })
 
+  it('prints the durable model failure when the final turn ends in error', async () => {
+    const test = await bench({
+      afterPrompt(session, message) {
+        session.append('turn/start', { turn: 1 })
+        session.append('step/start', { turn: 1, step: 1 })
+        session.append('user/message', message, { surfaceOp: 'append' })
+        session.append('step/end', { turn: 1, step: 1 })
+        session.append('turn/end', {
+          turn: 1,
+          reason: { kind: 'error', error: { code: 'SERVER', message: 'provider unavailable' } },
+        })
+      },
+    })
+    expect(await test.run()).toMatchObject({
+      code: 1,
+      out: '\n',
+      err: 'dsh: SERVER: provider unavailable\n',
+    })
+    await test.ctx.fiber.dispose()
+  })
+
   it('exits 1 when the owned interval contains no turn', async () => {
     const test = await bench({ afterPrompt: () => {} })
     expect(await test.run()).toMatchObject({ code: 1, out: '\n', err: '' })

From 6607775604481a64825b5b3f1c95c6a07ebd4146 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 13:46:14 +0800
Subject: [PATCH 457/516] fix(docs): close final translation review gaps

---
 .../2026-07-12-agent-scope-runtime-design.i18n.yaml       | 2 +-
 .../2026-07-12-agent-scope-runtime-design.zh.md           | 8 ++++----
 .../2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml  | 2 +-
 .../2026-07-30-followup-enqueue-and-owned-runs.zh.md      | 2 +-
 .../2026-08-08-trusted-repository-package-code.i18n.yaml  | 2 +-
 .../2026-08-08-trusted-repository-package-code.zh.md      | 4 ++--
 ...31-composer-text-layers-share-one-scrollport.i18n.yaml | 2 +-
 ...-07-31-composer-text-layers-share-one-scrollport.zh.md | 2 +-
 .../2026-07-31-fail-loud-releases-the-terminal.i18n.yaml  | 2 +-
 .../2026-07-31-fail-loud-releases-the-terminal.zh.md      | 4 ++--
 .../2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml   | 2 +-
 .../2026-08-03-hmr-initial-scan-boot-deadlock.zh.md       | 2 +-
 .../2026-08-04-composer-tab-gutter-reservation.i18n.yaml  | 2 +-
 .../2026-08-04-composer-tab-gutter-reservation.zh.md      | 2 +-
 ...npm-backed-git-repository-plugin-preparation.i18n.yaml | 2 +-
 ...-08-npm-backed-git-repository-plugin-preparation.zh.md | 8 ++++----
 .../2026-07-26-todo-parallel-in-progress.i18n.yaml        | 2 +-
 .../feature/2026-07-26-todo-parallel-in-progress.zh.md    | 4 ++--
 .../2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml  | 4 ++--
 .../process/2026-07-02-bilingual-docs-and-pairing-gate.md | 2 +-
 .../2026-07-02-bilingual-docs-and-pairing-gate.zh.md      | 2 +-
 packages/boot/app-boot/README.i18n.yaml                   | 2 +-
 packages/boot/app-boot/README.zh.md                       | 6 +++---
 packages/host/directory-picker-native/README.i18n.yaml    | 2 +-
 packages/host/directory-picker-native/README.zh.md        | 4 ++--
 packages/support/acp-snapshot/README.i18n.yaml            | 2 +-
 packages/support/acp-snapshot/README.zh.md                | 2 +-
 scripts/project-doc-site.spec.ts                          | 1 +
 .../translation-prompt-v4/request-response.expected.json  | 4 ++--
 scripts/translation-pairing.ts                            | 1 +
 30 files changed, 44 insertions(+), 42 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index 380171ab17..df9ebc9337 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
 2026-07-12-agent-scope-runtime-design.md: b93c291957fab98ab9d0d04eb816bb01a15a0b51
-2026-07-12-agent-scope-runtime-design.zh.md: e0c01f31eb2664608139f95dc60025a5b33e4618
+2026-07-12-agent-scope-runtime-design.zh.md: b78cd5dfd97e6825e404e06666908c6b53ac9709
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
index e0c01f31eb..b78cd5dfd9 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 本 Agent Note 余下部分按依赖顺序展开这些选择：Cordis 机制、作用域路由、创建与会话提交、工具与提示词、subagent 与工作流，最后是可执行检查。
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md)仍然是贡献者约定。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md) 仍然是贡献者约定。独立的 [subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md) 拥有 `persona`、`toolFilter` 和 `maxDepth`；本文仅讨论它们的 setup 如何融入生命周期。
 
 ## Cordis 模型：上下文、fiber、effect、receiver 与 waterfall
 
@@ -208,7 +208,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 私有解析器应用当前展示模式、活跃的全局限制、精确的局部叠加和局部遮蔽。Schema、查找、执行、Code Mode SDK 生成和限制验证都使用该解析器或其限制前的全局名称视图。
 
-[subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md#tool-filtering-is-one-live-global-view-rule)拥有用户可见的 allow/deny 语义。实现要求是一致性：被过滤掉的全局工具不能通过另一条查找路径仍可执行，局部遮蔽的定义就是被展示和执行的同一个定义。
+[subagent 组合控制 Agent Note](../feature/2026-07-12-subagent-persona-tool-filter-and-depth.md#tool-filtering-is-one-live-global-view-rule) 拥有用户可见的 allow/deny 语义。实现要求是一致性：被过滤掉的全局工具不能通过另一条查找路径仍可执行，局部遮蔽的定义就是被展示和执行的同一个定义。
 
 `ToolRestriction` 接受 readonly 的 allow/deny 名称并将其编译为内部集合。多个限制取交集。公开的 `visible()` 和 `knownNames()` 方法是不必要的，因为只有注册表需要中间视图。
 
@@ -330,13 +330,13 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ### 生成的产物使公开约定保持对齐
 
-事件目录、服务目录、生产者/消费方矩阵、配置目录、模块图、工具目录、type-equiv 块和作用域事件解析器映射都是从源码生成或受新鲜度门禁约束的。[TypeScript 语义门禁 Agent Note](../process/2026-07-14-typescript-program-backed-semantic-gates.md)拥有 Program 构造、语义事件发现和解析器生成规则。
+事件目录、服务目录、生产者/消费方矩阵、配置目录、模块图、工具目录、type-equiv 块和作用域事件解析器映射都是从源码生成或受新鲜度门禁约束的。[TypeScript 语义门禁 Agent Note](../process/2026-07-14-typescript-program-backed-semantic-gates.md) 拥有 Program 构造、语义事件发现和解析器生成规则。
 
 行为测试固定了作用域路由和 dispose、最终写入注册表时的碰撞清理、发布回滚、有序完全停稳、持久化前/后提交行为、跨展示和执行的活跃工具过滤、协作式提示词组装、原生和 Code Mode 中的结构化输出提交、异步 subagent 启动和信号取消、worker 终端仲裁、ACP 结算和进程拆除。
 
 ## 曾考虑的替代方案
 
-[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered)拥有公开扁平作用域约定的替代方案。此处的替代方案关注实现形态。
+[7 月 8 日 Agent Note](2026-07-08-agent-scope-contexts.md#alternatives-considered) 拥有公开扁平作用域约定的替代方案。此处的替代方案关注实现形态。
 
 ### 使用透明代理作为作用域载体
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
index b4863f08b5..a066480489 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
 2026-07-30-followup-enqueue-and-owned-runs.md: 54f4af75eeb29b06504fa2629b0665f3e5f4c4ee
-2026-07-30-followup-enqueue-and-owned-runs.zh.md: 51f82b7c703be13165e0cd7d7b354ea14e3a965e
+2026-07-30-followup-enqueue-and-owned-runs.zh.md: 226f0b9b61883cee5f6e321ae6b89b7b27b79e35
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
index 51f82b7c70..226f0b9b61 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 只有明确拥有一个活动区间时，高层自动化 API 才返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其 `finalResponse` 是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行可以报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。
 
-ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，其他情况均报告通用的 `end_turn`。token 上限的轮次结束不归因于提示词：它们以 `end_turn` 结算。与该提示词关联的轮次上的模型错误会立即以该错误拒绝提示词（错误按其所属轮次归因），而 turnless 槽位（准入已丢弃提示词）会在 idle 时以 `cancelled` 结算，与显式 ACP 取消或dispose（资源释放）并列。
+ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，其他情况均报告通用的 `end_turn`。token 上限的轮次结束不归因于提示词：它们以 `end_turn` 结算。与该提示词关联的轮次上的模型错误会立即以该错误拒绝提示词（错误按其所属轮次归因），而 turnless 槽位（准入已丢弃提示词）会在 idle 时以 `cancelled` 结算，与显式 ACP 取消或 dispose（资源释放）并列。
 
 Goal 续行只保留 `MessageId`，用于识别持久排队和已准入的 goal 消息。它在整个 agent 进入 idle 时根据持久 goal 状态推进，不把消息映射到轮次结果。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
index af4950b20c..9d49d8b1c2 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.md
 2026-08-08-trusted-repository-package-code.md: 387479b3b36a8bc5e145641ae40802b3090ced70
-2026-08-08-trusted-repository-package-code.zh.md: aff34d4485553f076c5dd1b71f0a3c5b5c62bc8f
+2026-08-08-trusted-repository-package-code.zh.md: ecc325c3dd0a9e823f1411c3a809c30ada486289
diff --git a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
index aff34d4485..ecc325c3dd 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-trusted-repository-package-code.zh.md
@@ -24,7 +24,7 @@
 
 精确 ref、源路径包含约束、清除名称符合凭据模式的环境变量、已准备的 manifest 和不可变缓存键，可以保护身份与组合完整性；它们不会为可执行包输入提供沙箱隔离。Repository 生命周期脚本、传递性 NPM 依赖、已编译入口和 spawn 的 MCP server 可以行使 DSH 进程可用的权限，以及它们所获 Cordis 服务授予的权限。因此，用户必须信任所选仓库，应当固定不可变 ref，并只授予 Git 获取源码所需的最小只读凭据。
 
-模型可见行为仍由所属 DSH seam 管理。repository 入口可以注册工具、提示词段落、策略、命令、agent（智能体）或其他 effect，但任何进入模型请求的内容仍须具有对应的 DSH 日志表示和生命周期清理。repository 格式授予代码加载能力；它不会削弱这些服务契约。
+模型可见行为仍由所属 DSH seam 管理。repository 入口可以注册工具、提示词段落、策略、命令、agent（智能体）或其他 effect，但任何进入模型请求的内容仍须具有对应的 DSH 日志表示和生命周期清理。repository 格式授予代码加载能力；它不会削弱这些服务约定。
 
 ## 考虑过的替代方案
 
@@ -34,7 +34,7 @@
 
 **隐式导入 `main`、`exports` 或其他发现的入口。** 拒绝，因为 NPM 包可能包含并非 Cordis 插件的实用工具或 MCP 可执行文件。显式 `dsh.entry` 字段使代码激活可供评审，并让准备阶段校验打包后的路径。
 
-**为未来每种 DSH 贡献添加封闭 manifest 字段。** 不采用它作为通用扩展机制。skill 和通用 MCP 文件仍保留有用的可移植静态适配器；DSH 原生行为则通过现有 Cordis 插件与服务契约组合。
+**为未来每种 DSH 贡献添加封闭 manifest 字段。** 不采用它作为通用扩展机制。skill 和通用 MCP 文件仍保留有用的可移植静态适配器；DSH 原生行为则通过现有 Cordis 插件与服务约定组合。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
index 71f89e6866..d9a9857cc8 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-composer-text-layers-share-one-scrollport.md
 2026-07-31-composer-text-layers-share-one-scrollport.md: ba11384409714d6a64a964d63197705acf39d213
-2026-07-31-composer-text-layers-share-one-scrollport.zh.md: cf0ce7bc344f6566d56a9e3cd81a63be5f68d614
+2026-07-31-composer-text-layers-share-one-scrollport.zh.md: 7a2500a6253c7cf50a57458b66c9b80503414ace
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
index cf0ce7bc34..7a2500a625 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md
@@ -63,7 +63,7 @@ composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/cl
 - 光标不可能离开自己的字形。浏览器滚动的是同一个盒子，因此「textarea 把某一行放在哪」与「backdrop 把这一行画在哪」之间的距离在任何偏移下都是一个固定的行盒常量，手势进行中也不例外。场景测试度量的正是这个数。
 - 滚动条从 textarea 移到了滚动容器上——视觉位置相同，只是外移了一层。`.card` 的 l2 token 绑定仍会继承下去。
 - chip、claim token 高亮与文本引用标记在滚动时仍与其字形对齐，因为它们定位在 backdrop 内部、随之移动。除去掉哨兵之外，装饰扫描没有变化。
-- 在 Firefox 与 WebKit 上，点进一个草稿超过上限的 composer 现在还会把会话 transcript（文本记录）滚动到底部：光标的 scroll-into-view 会越过 composer 的滚动容器一路走到transcript 的滚动容器，而一个比自身盒子矮的 textarea 从不会引发这一步。chromium 不会。已实测，并试过 `overscroll-behavior: contain` 与 `contain: paint`，两者都拦不住这次上行——没有任何 CSS 能终止 scroll-into-view 的接力。接受：它滚向底部，而 composer 本来就在底部，而其替代方案是在每个引擎上都出现光标与文字明显分离。
+- 在 Firefox 与 WebKit 上，点进一个草稿超过上限的 composer 现在还会把会话 transcript（文本记录）滚动到底部：光标的 scroll-into-view 会越过 composer 的滚动容器一路走到 transcript 的滚动容器，而一个比自身盒子矮的 textarea 从不会引发这一步。chromium 不会。已实测，并试过 `overscroll-behavior: contain` 与 `contain: paint`，两者都拦不住这次上行——没有任何 CSS 能终止 scroll-into-view 的接力。接受：它滚向底部，而 composer 本来就在底部，而其替代方案是在每个引擎上都出现光标与文字明显分离。
 - 翻页与拖拽选区的行为未变，二者均做了新旧对照实测。`PageDown`/`PageUp` 本来就不会移动 textarea 的插入点——chromium 是滚动一页并保持 `selectionStart` 不变，新旧几何皆然，区别只在于滚的是哪个盒子。拖拽选区越过下边缘仍会自动滚动，且落点一致（chromium 628/628、firefox 625/620、WebKit 170/170——WebKit 自动滚动较慢，但改动前后一样慢）。
 - composer 自己发起的 `focus()` 全部加了 `preventScroll`——解锁/切会话的 effect，以及工具栏按钮上那个保持焦点的 mousedown——因此一次没有任何手势要求的聚焦，不会再通过更高的 textarea 的回视链把 transcript 挪走。抑制这条链之后，光标就回到了我们手上，而这在一条路径上确实要紧：composer 的 DOM 跨会话复用，因此切到更长的草稿时旧偏移会留着，而换值会把光标放到新草稿的末尾。三引擎实测，这会让光标落在停在 0 的盒子下方 940px 处；于是该 effect 会在自己的滚动容器里把它带回来，落点 625/628——正是旧几何靠浏览器达到的 628。mousedown 那条不需要回视：光标没动过，而下一次敲键会拿到浏览器原生的回视。另一个只负责回视的 effect 会处理渲染后才到达的非空草稿：`ConversationSession` 在自己的 mount effect 中注入持久化草稿，而该 effect 在本组件的 effect 之后运行，因此如果没有这个独立 effect，第一次回视会量到空镜像，且不会再为随后出现的草稿重跑。第二个 effect 从不聚焦，因此发送后清空或发送失败后恢复这类普通的空/非空转换不会从其他控件夺走焦点。
 - 撤销/重做可以在不恢复光标、也不回视的情况下改动草稿：状态机重放上一版草稿，DOM 选区停在浏览器钳位后的位置。这早于本次改动且未被改动——在此点名，是因为另外两处恢复都会回视，会让这处遗漏看起来像有意为之；真被报告时 helper 就在旁边。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
index 6bf16a8981..7449d1b5fc 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
@@ -3,4 +3,4 @@
 # 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-31-fail-loud-releases-the-terminal.md
 2026-07-31-fail-loud-releases-the-terminal.md: 5fe812e5fe64a1fab8ba9808d87f3581b6f5b206
-2026-07-31-fail-loud-releases-the-terminal.zh.md: d5fdf72013259a60df64e8f79e64169770f3435c
+2026-07-31-fail-loud-releases-the-terminal.zh.md: 407161d112cbbb6f476773f6f7e21c2ce820956e
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
index d5fdf72013..407161d112 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
@@ -17,9 +17,9 @@ zsh: command not found: 4cecho
 
 Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动顺序。`ui-tui` 会先激活并调用 pi-tui 的 `ProcessTerminal.start()`，它把 stdin 置为 raw 模式、启用 bracketed paste，并写出 Kitty 键盘协议探测序列——该序列以一个 Device Attributes 查询（`ESC [ c`）结尾。随后某个同级条目（这里是 `llm-pi-ai`）因自身配置而 rejection。
 
-在当时，该 rejection 以未处理 rejection 的形式浮现，而 `installFailLoud` 只写一行 stderr 就立即调用 `process.exit(1)`。（事务化 Loader 现在让配置树失败经 `boot()` 结算，由它自行释放部分构建的上下文；release 回调仍然守护 `boot()` 看不到的 rejection——插件游离的异步工作在挂载期间或挂载之后失败。）没有任何环节释放这棵树，因此 `ProcessTerminal.stop()` 从未执行：raw 模式、bracketed paste 和键盘协议都残留在比进程活得更久的 shell 上。终端对 Device Attributes 查询的回应（`1;2;4c`）在进程退出之后才到达，被 shell 当作用户输入读入——也就是上面那段字面文本。
+在当时，该 rejection 以未处理 rejection 的形式浮现，而 `installFailLoud` 只写一行 stderr 就立即调用 `process.exit(1)`。（事务化 Loader 现在让配置树失败经 `boot()` 结算，由它自行 dispose（资源释放）部分构建的上下文；release 回调仍然守护 `boot()` 看不到的 rejection——插件游离的异步工作在挂载期间或挂载之后失败。）没有任何环节 dispose 这棵树，因此 `ProcessTerminal.stop()` 从未执行：raw 模式、bracketed paste 和键盘协议都残留在比进程活得更久的 shell 上。终端对 Device Attributes 查询的回应（`1;2;4c`）在进程退出之后才到达，被 shell 当作用户输入读入——也就是上面那段字面文本。
 
-`/exit` 路径从不受影响，因为它会释放整棵树，从而进入 TUI 自身的 `shutdown()`：先 `drainInput()`（吸收尚未返回的响应），再 `ui.stop()`。缺陷在于**启动失败**没有通往这同一套拆卸流程的路径。
+`/exit` 路径从不受影响，因为它会 dispose 整棵树，从而进入 TUI 自身的 `shutdown()`：先 `drainInput()`（吸收尚未返回的响应），再 `ui.stop()`。缺陷在于**启动失败**没有通往这同一套拆卸流程的路径。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
index 1ca6de64cd..b265906af0 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md
 2026-08-03-hmr-initial-scan-boot-deadlock.md: 1a70fbafc74a1bf7024c675ddad82acefc995b72
-2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: a023420182971a62f125808f777f877bafe3e9e2
+2026-08-03-hmr-initial-scan-boot-deadlock.zh.md: 7123e423aab1293d138a1c24cb0dded00a83c89a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
index a023420182..7123e423aa 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md
@@ -20,7 +20,7 @@
 - `include/src/index.ts` 将每次子树变更——首次 apply、refresh、`internal/update` 补丁重应用——汇入每个 Include 一条的 promise 队列。group 的事务化 `update` 不可重入，因此序列化是正确性要求，而不是吞吐取舍。`refresh()` 也在队列内读取文件，使其内容变更判断与前一任务提交后的状态比较。
 - `hmr/src/index.ts` 给主 watcher 传入 `ignoreInitial: true`。初始扫描只会重新宣告启动刚刚消费过的文件；抑制它同时消除了启动期 refresh 和对已加载模块的多余 `add` 事件。`registerConfig()` 保留自己 `ignoreInitial: false` 的 watcher，因为注册时已存在的个人配置必须恰好应用一次。
 
-两者齐备后，失败的启动走上预期路径：唯一一次 apply 失败，回滚释放整棵树（执行 TUI 自身的 shutdown、恢复终端），`loader.create` reject，`boot()` 重新抛出带标签的诊断并以 1 退出。
+两者齐备后，失败的启动走上预期路径：唯一一次 apply 失败，回滚并 dispose（资源释放）整棵树（执行 TUI 自身的 shutdown、恢复终端），`loader.create` reject，`boot()` 重新抛出带标签的诊断并以 1 退出。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
index 64ec136c6d..3b41a39be5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md
 2026-08-04-composer-tab-gutter-reservation.md: 3b28c35c1f11676e41cabde76d1b0d16c688f034
-2026-08-04-composer-tab-gutter-reservation.zh.md: 8c435d85a2a068684ac4781296963f822df43484
+2026-08-04-composer-tab-gutter-reservation.zh.md: 8724195a53a846d0fb09fb1182f94a40214c23d8
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
index 8c435d85a2..8724195a53 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
@@ -10,7 +10,7 @@ composer 座位在组件树中只有一个节点、一个位置，但它究竟
 
 在 Chat 中它是会话列滚动容器（`[data-conversation-scroll]`）的 sticky **子元素**，因而依附于该容器的 content box——而占布局宽度的滚动条会把这个盒子收窄一条滚动条的宽度。声明了 `data-conversation-composer-overlay` 的视图（Trajectory 即是其一）会把会话列的滚动搬进视图自身：以该属性为条件的那条分支把滚动容器留作 `overflow: hidden`，并把座位改为绝对定位——对齐的是 padding box，而滚动条从不收窄这个盒子。
 
-于是只要transcript（文本记录）超出一屏——任何带历史的会话的常态——两个标签页就恰好相差一条滚动条的宽度。输入卡片是居中的，因此在 8px 的滚动条下切换标签页会让它横向移动 4px，而右侧留白整整变化 8px。同一位移也出现在 Chat 内部：transcript 增长到开始滚动的那一刻，以及从 hero 态进入第一个可滚动轮次时。
+于是只要 transcript（文本记录）超出一屏——任何带历史的会话的常态——两个标签页就恰好相差一条滚动条的宽度。输入卡片是居中的，因此在 8px 的滚动条下切换标签页会让它横向移动 4px，而右侧留白整整变化 8px。同一位移也出现在 Chat 内部：transcript 增长到开始滚动的那一刻，以及从 hero 态进入第一个可滚动轮次时。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
index f13bae898a..86e63238fa 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.md
 2026-08-08-npm-backed-git-repository-plugin-preparation.md: 958b932f82f4da3cf63aa911260411855e514409
-2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md: 4986c55787f291ba9e0d4594854c15eb3c892c72
+2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md: d2256e0eae303c371371b9b5ba1967105aa61834
diff --git a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
index 4986c55787..d2256e0eae 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-08-npm-backed-git-repository-plugin-preparation.zh.md
@@ -6,7 +6,7 @@
 
 ## 问题
 
-repository 插件创作契约要求 `scripts.prepack` 调用 `dsh-plugin-prepare`。如果由正在运行的 DSH 安装提供该可执行文件，即使源包自身的 manifest（元数据清单）无法取得辅助程序，它也会显得有效。因此，这并未证明 `@deepseek-ai/dsh-repository-plugin` 发布后用户所需的行为：普通 Git 托管 NPM 包必须只依靠自身声明的依赖即可安装和准备。
+repository 插件创作约定要求 `scripts.prepack` 调用 `dsh-plugin-prepare`。如果由正在运行的 DSH 安装提供该可执行文件，即使源包自身的 manifest（元数据清单）无法取得辅助程序，它也会显得有效。因此，这并未证明 `@deepseek-ai/dsh-repository-plugin` 发布后用户所需的行为：普通 Git 托管 NPM 包必须只依靠自身声明的依赖即可安装和准备。
 
 pnpm workspace 内可选择的 `.dsh-plugin` 还有另一项隔离要求。pnpm 会在打包所选子目录前运行仓库首选的包管理器，以准备 Git 托管包。嵌套的 `pnpm install` 可能加入外层 workspace；当根 lockfile 未把 `.dsh-plugin` 列为 importer 时，pnpm 可能报告成功，却未安装仅由该包声明的依赖。随后，其 TypeScript 构建或准备命令会失败；也可能因为存在预生成产物，依赖缺失被掩盖。
 
@@ -16,7 +16,7 @@ pnpm workspace 内可选择的 `.dsh-plugin` 还有另一项隔离要求。pnpm
 
 `.dsh-plugin` 包将已发布的 `@deepseek-ai/dsh-repository-plugin` 声明为普通开发依赖，并在 `scripts.prepack` 中调用其已发布的 `dsh-plugin-prepare` 可执行文件。该包可以声明其他任意构建依赖与运行时依赖，并在辅助程序前执行任意编译。repository 插件包把 Cordis 与 DSH 对等依赖（peer dependency）标为可选，因此仅为使用辅助程序而进行的开发安装只会解析辅助程序实际依赖的 `zod` 运行时依赖；应用组合仍会提供该包 Cordis 入口所使用的对等依赖。
 
-DSH 不会生成准备阶段可执行文件，也不会将其前置到 `PATH`。`RepositoryCache` 只提供一个由事务持有的 `pnpm` 包装脚本：外层安装直接运行锁定的 pnpm 入口，而 pnpm 为 Git 包硬编码的 `pnpm install` 会以 `--ignore-workspace` 重新调用同一入口。因此，即使位于另一个 pnpm lockfile 之下，所选包仍自行负责依赖解析，正常的包管理器生命周期 `PATH` 构造会暴露 `node_modules/.bin/dsh-plugin-prepare`。临时 pnpm 包装脚本会在子进程结算后消失。repository 仍是受信任的包管理器输入：所有依赖与生命周期代码都按既有信任契约执行。
+DSH 不会生成准备阶段可执行文件，也不会将其前置到 `PATH`。`RepositoryCache` 只提供一个由事务持有的 `pnpm` 包装脚本：外层安装直接运行锁定的 pnpm 入口，而 pnpm 为 Git 包硬编码的 `pnpm install` 会以 `--ignore-workspace` 重新调用同一入口。因此，即使位于另一个 pnpm lockfile 之下，所选包仍自行负责依赖解析，正常的包管理器生命周期 `PATH` 构造会暴露 `node_modules/.bin/dsh-plugin-prepare`。临时 pnpm 包装脚本会在子进程结算后消失。repository 仍是受信任的包管理器输入：所有依赖与生命周期代码都按既有信任约定执行。
 
 Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库与 SHA 派生的精确源。它复用现有私有 DeepSeek Harness 仓库，而不会为每次运行新建仓库。作业作用域的 Git 配置允许只读作业 token 访问该精确私有源，并把 pnpm 的 SSH 回退改写为已认证 HTTPS。
 
@@ -26,7 +26,7 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库与 SHA 
 
 **从正在运行的 DSH 安装注入 `dsh-plugin-prepare`。** 拒绝，因为这会让 manifest 不完整的 repository 包通过，并测试 NPM 消费方无法复现的纯宿主路径。
 
-**把源 fixture 本身发布到 NPM。** 拒绝，因为产品契约明确要求 DSH 插件仍托管在 Git；只有可复用的准备辅助程序是 NPM 依赖。
+**把源 fixture 本身发布到 NPM。** 拒绝，因为产品约定明确要求 DSH 插件仍托管在 Git；只有可复用的准备辅助程序是 NPM 依赖。
 
 **在每次 CI 运行中创建新的私有 GitHub 仓库。** 拒绝，因为 PR 仓库的精确 head SHA 已是经过认证的真实私有 Git remote。每次运行的仓库变更会增加凭据、清理和最终一致性失败模式，却不改变获取路径。
 
@@ -45,4 +45,4 @@ Node 24 消费方 CI 任务会传入从 PR（Pull Request）head 仓库与 SHA 
 
 ## 测试
 
-`packages/boot/app-boot/tests/repository-cache.spec.ts` 会通过本地 Git 子路径运行一个未列入源仓库根 pnpm lockfile 的包，并要求相对 `file:` 依赖同时提供构建命令与 `dsh-plugin-prepare`；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据与准备输出。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式契约。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：模拟发布的辅助程序包、作业本地 NPM 注册表、全新 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及已准备缓存检查。
+`packages/boot/app-boot/tests/repository-cache.spec.ts` 会通过本地 Git 子路径运行一个未列入源仓库根 pnpm lockfile 的包，并要求相对 `file:` 依赖同时提供构建命令与 `dsh-plugin-prepare`；该测试还证明可见环境变量得以保留，而名称符合凭据模式的变量会被清除。`packages/self-modification/repository-plugin/tests/repository-plugin.spec.ts` 锁定包含辅助命令的 `prepack` 元数据与准备输出。`examples/headless-agent/tests/keyless-smoke.e2e.ts` 使签入仓库的已准备 fixture 继续符合该源格式约定。`apps/cli/tests/github-repository-plugin.built.e2e.ts` 是产品验收测试：模拟发布的辅助程序包、作业本地 NPM 注册表、全新 DSH 主目录、精确且经过认证的私有 GitHub 源、实际构建的 `dsh run`、包自有 TypeScript 构建、真实 MCP 执行、代码入口转换、mock LLM（大语言模型）请求观测，以及已准备缓存检查。
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
index 43076fbfe4..90ea440ef8 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
 2026-07-26-todo-parallel-in-progress.md: 8d047f33ab1aebd8c0de2a0a5e90e7efb1b28154
-2026-07-26-todo-parallel-in-progress.zh.md: 64047e8b27e779e6ca23ea6c435bcdfecf38066d
+2026-07-26-todo-parallel-in-progress.zh.md: ebd4b1567eba637493956993b43b1ec56df14c39
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
index 64047e8b27..ebd4b1567e 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
@@ -41,9 +41,9 @@ Status: implemented
 
 工具行改用 `toolviews/plan-summary.ts` 中的 `planSummary`。它给出第一个活跃条目，并计数其余活跃项，因此工具行报告的是有多少任务在跑，而不是暗示只有一个。列出全部活跃条目被否决了：工具行是单行，无上界的拼接会溢出——在列表做不到的地方，计数能够可预测地降级。该推导放在 toolviews 域内而非 `contract/`（域间共享面）：面板自行内联计算其计数，与工具行不共享任何东西，因此放进 contract 会声明一种已不存在的共享关系。
 
-`planSummary` 把任务名与计数作为两个独立字段返回，而不是一个拼好的字符串，因为工具行用 `overflow: hidden` / `text-overflow: ellipsis` 截断其摘要文本。计数接在任务名之后时位于可截断文本的末端，于是恰恰是让计数变得有意义的那些场景——窄视口、长任务名——会把它裁掉，让并行计划看起来与顺序计划无异。因此工具行把计数交给共享的 `ToolRow`，作为 `summarySuffix`——一个紧邻被省略号截断的摘要文本、且不会收缩的slot；一个预先拼好的字符串无法表达这个切分，而把计数放到任务名之前也被否决了：读者首先要找的是任务名。
+`planSummary` 把任务名与计数作为两个独立字段返回，而不是一个拼好的字符串，因为工具行用 `overflow: hidden` / `text-overflow: ellipsis` 截断其摘要文本。计数接在任务名之后时位于可截断文本的末端，于是恰恰是让计数变得有意义的那些场景——窄视口、长任务名——会把它裁掉，让并行计划看起来与顺序计划无异。因此工具行把计数交给共享的 `ToolRow`，作为 `summarySuffix`——一个紧邻被省略号截断的摘要文本、且不会收缩的 slot；一个预先拼好的字符串无法表达这个切分，而把计数放到任务名之前也被否决了：读者首先要找的是任务名。
 
-`summarySuffix` 是 `ToolRow` 上的slot，而不是 todo 工具行自有的标记：每个 toolview 都经由这个共享组件渲染，而它的 `summary` 是一个会被省略号截断的普通字符串，容不下一个必须挺过截断的片段。该后缀落在 `.summary` 规则之外，因此重复了该规则的 `font-size` 与 `line-height`——Web 外壳把正文字号留在浏览器默认值而非该行的 14px，所以未加样式的 span 会明显大于同一 24px 行内与之并列的文本。错误行会丢弃该后缀，因为它折叠态的摘要是失败行，而非任何由调用 args 推导出的内容。
+`summarySuffix` 是 `ToolRow` 上的 slot，而不是 todo 工具行自有的标记：每个 toolview 都经由这个共享组件渲染，而它的 `summary` 是一个会被省略号截断的普通字符串，容不下一个必须挺过截断的片段。该后缀落在 `.summary` 规则之外，因此重复了该规则的 `font-size` 与 `line-height`——Web 外壳把正文字号留在浏览器默认值而非该行的 14px，所以未加样式的 span 会明显大于同一 24px 行内与之并列的文本。错误行会丢弃该后缀，因为它折叠态的摘要是失败行，而非任何由调用 args 推导出的内容。
 
 ## 暂缓项
 
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 56ffbc366d..4fd3657a7d 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.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 .agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
-2026-07-02-bilingual-docs-and-pairing-gate.md: b462efd99c008a1e8254b6754a408e9e94e787d6
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 564442ce9bd09a448c030e30f34930673a06727b
+2026-07-02-bilingual-docs-and-pairing-gate.md: 930efd3a2df8ad99b3c209c6084436ab6b27dc0a
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 2e288a29e9484683b9961d1e420a6e92ca05e5fe
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
index b462efd99c..930efd3a2d 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
@@ -12,7 +12,7 @@ This repo's documentation corpus is read by people and agents inside and outside
 
 - **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).
 - **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.
-- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.
+- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.
 - **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.
 - **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.
 - **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index 564442ce9b..2e288a29e9 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 - **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。
 - **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
-- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。
+- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、中文侧和所有普通撰写的英文源都带切换行而清单内的生成英文源除外、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。
 - **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。
 - **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。
 - **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index 7885dd3280..330c4c43ac 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
 README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
-README.zh.md: a0a437437f3bb562f0a0d2bb52b1cba1df681606
+README.zh.md: 6ff915c618f636f05f1f8591433feb3aef9151a8
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index a0a437437f..6ff915c618 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -18,14 +18,14 @@
 | `mountRootInclude(ctx, absoluteConfigPath, patches?)` | 挂载静态导入的 Include builtin，并保留用户 patch 层 HMR（热模块替换）使用的确切根配置项 |
 | `watchUserPatches(ctx, options)` | 向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步清理函数 |
 | `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile 机制（见 [Profile](#profiles)） |
-| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时释放部分构造的上下文，并返回带标签的拒绝结果 |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并返回带标签的拒绝结果 |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |
 
-Loader 结算会在导入或生命周期失败时返回拒绝结果，并携带失败的配置项与阶段；`boot()` 会释放部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：`assertEntriesLoaded` 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；`assertEntriesActivated` 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
+Loader 结算会在导入或生命周期失败时返回拒绝结果，并携带失败的配置项与阶段；`boot()` 会 dispose 部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：`assertEntriesLoaded` 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；`assertEntriesActivated` 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 `installFailLoud` 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
 
-Loader 并发挂载各个条目，因此当其他环节失败时，某个界面可能已经持有终端：此时不经过整棵树自身的拆卸就退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。配置树失败会经 `boot()` 结算：它先释放部分构建的上下文（从而执行该界面自身的 shutdown），再抛出带标签的 rejection。对于 `boot()` 看不到的 rejection（插件游离的异步工作在挂载期间或挂载完成后失败），持有终端的 bin 会传入 `release`，在提交退出前释放整棵树；`dsh` 在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值，使该回调覆盖整个挂载窗口。release 执行期间，处理函数保持注册并处于锁定状态：被报告的始终是第一个 rejection，后续拒绝（包括拆卸自身产生的拒绝）会被忽略，而不会变成未捕获错误、在拆卸中途杀死进程。
+Loader 并发挂载各个条目，因此当其他环节失败时，某个界面可能已经持有终端：此时不经过整棵树自身的拆卸就退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。配置树失败会经 `boot()` 结算：它先 dispose 部分构建的上下文（从而执行该界面自身的 shutdown），再抛出带标签的 rejection。对于 `boot()` 看不到的 rejection（插件游离的异步工作在挂载期间或挂载完成后失败），持有终端的 bin 会传入 `release`，在提交退出前 dispose 整棵树；`dsh` 在 `boot()` 的 `prepare` 回调中捕获根上下文，而不是取其返回值，使该回调覆盖整个挂载窗口。release 执行期间，处理函数保持注册并处于锁定状态：被报告的始终是第一个 rejection，后续拒绝（包括拆卸自身产生的拒绝）会被忽略，而不会变成未捕获错误、在拆卸中途杀死进程。
 
 配置中的裸插件 specifier（`@deepseek-ai/dsh-*`、npm 包）通过 Cordis Loader 的内部模块 loader 解析。仓库 bin 会安装 Loader 的可选 peer `node-addon-require-builtin`；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。相对 specifier 无需原生 helper，并以配置目录为基准解析。构建后的 `dsh-app-boot` 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与宿主会绑定到同一个 Loader peer。`dsh` 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个随附的原始／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。
 
diff --git a/packages/host/directory-picker-native/README.i18n.yaml b/packages/host/directory-picker-native/README.i18n.yaml
index 9f2c323183..c2062933e5 100644
--- a/packages/host/directory-picker-native/README.i18n.yaml
+++ b/packages/host/directory-picker-native/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/directory-picker-native/README.md
 README.md: 4dd0c79d080fe097d063cfd2200e30aafc2d2d42
-README.zh.md: bbf6d361f48792a9f385a83032546f6d95fd3fc8
+README.zh.md: e7d0ec99c1aaca8f22f8d5dc29fcbddd73d9f7c0
diff --git a/packages/host/directory-picker-native/README.zh.md b/packages/host/directory-picker-native/README.zh.md
index bbf6d361f4..e7d0ec99c1 100644
--- a/packages/host/directory-picker-native/README.zh.md
+++ b/packages/host/directory-picker-native/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-[目录选择 seam](../directory-picker/README.md) 的**原生 OS 选择器后端**：`NativeDirectoryPicker` 以 `native` 能力注册 `ctx.directoryPicker`，其 `pick(signal)` 每次调用打开一个原生选择器并解析出所选绝对路径（取消时为 `null`）。平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在派生的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。只有操作者坐在宿主屏幕前时才可用——远程部署应组合 [`-browse`](../directory-picker-browse/README.md)。命令边界（`DirectoryPickerRunner`）与平台事实可注入。共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.md)。
+[目录选择 seam](../directory-picker/README.md) 的**原生 OS 选择器后端**：`NativeDirectoryPicker` 以 `native` 能力注册 `ctx.directoryPicker`，其 `pick(signal)` 每次调用打开一个原生选择器并解析出所选绝对路径（取消时为 `null`）。平台工具不经 shell 调用：macOS 使用 `osascript`，Linux 使用 Zenity 并以 KDialog 回退；调用方的中止信号会终止原生进程。Windows 在 spawn 的子进程中打开现代 `IFileOpenDialog`——由 koffi 在子进程主线程上驱动的 COM 会话，采用宿主接受的最佳线程 DPI 感知（优先 per-monitor-v2），中止时向对话框线程投递 `WM_CLOSE`。只有操作者坐在宿主屏幕前时才可用——远程部署应组合 [`-browse`](../directory-picker-browse/README.md)。命令边界（`DirectoryPickerRunner`）与平台事实可注入。共享的免 shell 子进程运行器位于 [`dsh-native-command`](../../util/native-command/README.md)。
 
-**双面包**：浏览器端（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流 slot注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并通过 slot 的属主交互约定上报唯一结果（所选路径／取消／失败）。两个目录流程声明必须同时处于有效状态，任一贡献才会安装。因此一行 cordis.yml 同时组合原生交互的两侧；客户端不包含任何按能力类型进行的分支，挂载第二个流程包会在加载期失败（slot 的 kind 为 `single`）。
+**双面包**：浏览器端（`./client`）向 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流 slot 注册一个无渲染的流程占用者——每次 `open` 请求驱动 `host.pickDirectory`，并通过 slot 的属主交互约定上报唯一结果（所选路径／取消／失败）。两个目录流程声明必须同时处于有效状态，任一贡献才会安装。因此一行 cordis.yml 同时组合原生交互的两侧；客户端不包含任何按能力类型进行的分支，挂载第二个流程包会在加载期失败（slot 的 kind 为 `single`）。
 
 ## 模型体验
 
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index 648b807368..bf71e04e3e 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/support/acp-snapshot/README.md
 README.md: 0b935ef60c33fd24660d8ecf2497f5506157c724
-README.zh.md: 2f71649117f8f962cec9648a0cadd79f4e182c60
+README.zh.md: 7c1c3328ab8490c7eebd4b2492bc4ae6f4fcd5a5
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index 2f71649117..7c1c3328ab 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -6,7 +6,7 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 
 四层可单独导入：
 
-- **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动阶段报告异步派生失败，并默认拒绝未处理的权限请求，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才完成关闭或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
+- **`launchAcpTestAgent`（启动器）**：从指定 cwd 在 tsx 下启动源 agent，或在普通 Node 下启动已构建 `lib` agent；通过原始字节 stdout tee 连接 SDK 客户端，收集会话更新和 stderr，在启动阶段报告异步 spawn 失败，默认拒绝未处理的权限请求，并负责优雅或带信号关闭。关闭会等待进程退出、继承 stdio 关闭和 ACP parser 耗尽，然后才完成关闭或传播子级错误，使捕获内容完整，且调用方可在任一结果后移除自有路径。当 Windows 接受强制终止但异步发布退出标记时，关闭会给该标记有界宽限，然后才将回退拒绝视为第二次失败。快照和普通 e2e 套件共享该进程边界；测试只需提供 agent 路径、cwd、环境覆盖和任何权限策略。
 - **`runScenario`（harness）**：通过启动器从确定性 `input.json` 脚本驱动 ACP JSON-RPC stdio，将原始 stdout tee 给预期输出和纯度检查，并在优雅 stdin EOF 后收集每个持久化原始 JSONL 会话日志（父会话和 subagent 子会话，主会话优先）。`AgentUnderTest` 提供绝对 `binScript`、可选 `libBinScript`、`configPath` 和 `tsconfigPath` 路径，因为子进程 cwd 位于仓库外。当生成子级 cwd 自身位于待测授权中时，`workspaceParent` 可以将它从平台临时目录移出。启动失败会在拒绝诊断中保留已捕获 agent stderr。
 - **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每种原生／JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已进行 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
 - **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新模式写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件构成有序的主会话／子会话清单；场景表不重复其数量。必须在 vitest 收集时调用。
diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index 2385b3c24c..d3f00f3408 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -330,6 +330,7 @@ describe('docsPages locale routes', () => {
   })
 
   it('projects reviewed generated counterparts into root locale routes', () => {
+    // module-graph, event-producer-consumer, and graph-atlas are paired but intentionally unpublished.
     const routes = [
       'reference/capability-seams.md',
       'reference/agent-lifecycle.md',
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index d4aeea3fa1..161a52bbf9 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -40,11 +40,11 @@
       },
       {
         "role": "user",
-        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
+        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、中文侧和所有普通撰写的英文源都带切换行而清单内的生成英文源除外、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
       },
       {
         "role": "user",
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
index 87e31199a4..e80605c14b 100644
--- a/scripts/translation-pairing.ts
+++ b/scripts/translation-pairing.ts
@@ -320,6 +320,7 @@ export function requiresSourceLanguageSwitcher(source: string): boolean {
     'docs/cordis-api/context.md',
     'docs/cordis-api/events.md',
     'docs/cordis-api/fiber.md',
+    // Excluded from pairing, but kept here for generated-category completeness and direct spec coverage.
     'docs/cordis-api/inherited.md',
     'docs/cordis-api/registry.md',
     'docs/cordis-api/service.md',

From d5adb4b4a72d5f484e9a4b96bad9797d56af4171 Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 13:51:10 +0800
Subject: [PATCH 458/516] fix(docs): sync generated catalog terminology

---
 docs/tool-catalog.i18n.yaml | 4 ++--
 docs/tool-catalog.zh.md     | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 9e530c0668..b0125b77fa 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.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 docs/tool-catalog.md
-tool-catalog.md: 8986847d1ed2fe9d64ada0c71f34700ff95fb364
-tool-catalog.zh.md: 831ed5d5cdcc15f32d2a4c8673858935fca1e435
+tool-catalog.md: e598429553ad9e6666e483b4bf8f49b0e8dc6c1c
+tool-catalog.zh.md: 81ea65f88979801cc1262e3c1cd0f527dee4b9ae
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index 831ed5d5cd..81ea65f889 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -286,7 +286,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
 
 ### `cordis_mount`
 
-在当前 DSH 进程中挂载临时 Cordis Plugin。它创建的是内存中的运行时 Plugin，而不是已安装或已配置的 Plugin。该插件会在后续轮次中保持活动，直到执行 cordis_unmount、工具集卸载或 DSH 重启。它不会创建文件、安装包、修改 cordis.yml 或个人／项目配置、在重启后保留，也不会自动转为永久插件。若要保留，请让 Agent 通过常规开发工作流实现普通的本地、项目或仓库 Plugin。它可能影响同一进程中的其他会话；沙箱不是安全边界，注入的服务会访问真实运行时。`code` 会立即作为异步 JavaScript 函数的函数体在隔离沙箱中运行，并且**必须** `return` 一个插件。支持两种形式：函数形式 `return (ctx) => { … }`，它不声明 inject，因此可以注册工具、监听事件和提供服务，但访问**任何**服务（例如 ctx.bash）都会抛出异常；仅在不需要服务时使用。对象形式 `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }`，它声明依赖，Cordis 只在服务存在后激活插件；**优先使用**这种形式。你只能访问 inject 中列出的服务：即使未声明的服务存在，访问它也会抛出异常，因为如果提供方被卸载，未声明的依赖将无法清理。代码调用服务**之前**，请读取 cordis_inspect 的 what:"api"；它会列出方法签名以及参数／返回值的类型形状，不要猜测字段类型，例如 bash 运行的 stdout 是对象而非字符串。在 `apply` 内，请使用标准 Cordis API：通过 `ctx.on(event, listener)` 观察事件（见 cordis_inspect 的 what:"events"），或调用 `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` 为自己提供新工具；该工具会在你的**下一步骤**可调用。工具参数：每个键**就是**一个属性，即 { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }；每个直接 DSL 对象都声明 additionalProperties: true|false，而 oneOf: [schema, schema, ...] 会取代 type，表示恰好匹配一个成员的联合。也接受原始 JSON Schema { type: 'object', properties, required?: […] } 包装层，其中对象默认开放。工具的 `execute` **必须**返回 `output.schema` 声明的无损 JSON 值；`output.render(args, value)` 单独返回 Native／模型内容块。临时 Plugin 可以**组合**：一个 Plugin 可以通过 `ctx.provide('name', value)` 提供服务，另一个则可声明 `inject: ['name']` 来消费它；消费方会在提供方出现前保持等待，提供方卸载后重新回到等待状态。在 `apply` 中注册的一切都会由 cordis_unmount 自动清理。沙箱全局对象：`console`（带 `[cordis:<id>]` 标签，写入 harness 终端）、`harness.defineTool`、`harness.registerTool`、`btoa`、`atob`、`TextEncoder`、`TextDecoder`。Node API 已**禁用**：文件系统／网络／定时工作必须通过 Cordis 服务完成，绝不能使用 Node 内置能力；`require`、`setTimeout`／`setInterval` 和 `fetch` 会抛出重定向错误，`process` 和 `Buffer` 未定义。应改用 inject: ['fs'] + ctx.fs 处理文件、inject: ['web'] + ctx.web 处理 HTTP、inject: ['bash'] + ctx.bash 处理进程、inject: ['timer'] + ctx.setTimeout/ctx.setInterval 处理定时（这些是 fiber effect，卸载时自动清理）；cordis_inspect 的 what:"api" 会展示**当前**运行时提供的能力。请编写**纯** JavaScript，不要使用 TypeScript（不得使用 `as` 或类型注解）。注意事项：(1) waterfall（瀑布式事件）事件（例如 tools/pre-execute）会向监听器传入最后一个 `next` 回调，该回调**必须**被调用；不调用 `next()` 就返回会**否决**此次调用。除非你有意拦截，否则请优先使用普通通知事件。(2) 切勿等待只能在当前轮次之后解析的内容；你的代码运行在该轮次的工具调用**内部**，否则会死锁。(3) 你的 `ctx` 是受限门面：可以注册工具、观察事件、提供／消费服务和使用定时器，但不会提供框架内部能力（ctx.root、ctx.fiber、ctx.extend、ctx.plugin 等）。不过，它并非安全边界：你注入的服务（例如 ctx.bash）会访问真实运行时。
+在当前 DSH 进程中挂载临时 Cordis Plugin。它创建的是内存中的运行时 Plugin，而不是已安装或已配置的 Plugin。该插件会在后续轮次中保持活动，直到执行 cordis_unmount、工具集卸载或 DSH 重启。它不会创建文件、安装包、修改 cordis.yml 或个人／项目配置、在重启后保留，也不会自动转为永久插件。若要保留，请让 Agent 通过常规开发工作流实现普通的本地、项目或仓库 Plugin。它可能影响同一进程中的其他会话；沙箱不是安全边界，注入的服务会访问真实运行时。`code` 会立即作为异步 JavaScript 函数的函数体在隔离沙箱中运行，并且**必须** `return` 一个插件。支持两种形式：函数形式 `return (ctx) => { … }`，它不声明 inject，因此可以注册工具、监听事件和提供服务，但访问**任何**服务（例如 ctx.bash）都会抛出异常；仅在不需要服务时使用。对象形式 `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }`，它声明依赖，Cordis 只在服务存在后激活插件；**优先使用**这种形式。你只能访问 inject 中列出的服务：即使未声明的服务存在，访问它也会抛出异常，因为如果提供方被卸载，未声明的依赖将无法清理。代码调用服务**之前**，请读取 cordis_inspect 的 what:"api"；它会列出方法签名以及参数／返回值的类型形状，不要猜测字段类型，例如 bash 运行的 stdout 是对象而非字符串。在 `apply` 内，请使用标准 Cordis API：通过 `ctx.on(event, listener)` 观察事件（见 cordis_inspect 的 what:"events"），或调用 `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` 为自己提供新工具；该工具会在你的**下一步骤**可调用。工具参数：每个键**就是**一个属性，即 { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }；每个直接 DSL 对象都声明 additionalProperties: true|false，而 oneOf: [schema, schema, ...] 会取代 type，表示恰好匹配一个成员的联合。也接受原始 JSON Schema { type: 'object', properties, required?: […] } 包装层，其中对象默认开放。工具的 `execute` **必须**返回 `output.schema` 声明的无损 JSON 值；`output.render(args, value)` 单独返回 Native／模型内容块。临时 Plugin 可以**组合**：一个 Plugin 可以通过 `ctx.provide('name', value)` 提供服务，另一个则可声明 `inject: ['name']` 来消费它；消费方会在提供方出现前保持等待，提供方卸载后重新回到等待状态。在 `apply` 中注册的一切都会由 cordis_unmount 自动清理。沙箱全局对象：`console`（带 `[cordis:<id>]` 标签，写入 harness 终端）、`harness.defineTool`、`harness.registerTool`、`btoa`、`atob`、`TextEncoder`、`TextDecoder`。Node API 已**禁用**：文件系统／网络／定时工作必须通过 Cordis 服务完成，绝不能使用 Node 内置能力；`require`、`setTimeout`／`setInterval` 和 `fetch` 会抛出重定向错误，`process` 和 `Buffer` 未定义。应改用 inject: ['fs'] + ctx.fs 处理文件、inject: ['web'] + ctx.web 处理 HTTP、inject: ['bash'] + ctx.bash 处理进程、inject: ['timer'] + ctx.setTimeout/ctx.setInterval 处理定时（这些是 fiber effect，卸载时自动清理）；cordis_inspect 的 what:"api" 会展示**当前**运行时提供的能力。请编写**纯** JavaScript，不要使用 TypeScript（不得使用 `as` 或类型注解）。注意事项：(1) waterfall（瀑布式事件）事件（例如 tools/pre-execute）会向监听器传入最后一个 `next` 回调，该回调**必须**被调用；不调用 `next()` 就返回会**短路**此次调用。除非你有意拦截，否则请优先使用普通通知事件。(2) 切勿等待只能在当前轮次之后解析的内容；你的代码运行在该轮次的工具调用**内部**，否则会死锁。(3) 你的 `ctx` 是受限门面：可以注册工具、观察事件、提供／消费服务和使用定时器，但不会提供框架内部能力（ctx.root、ctx.fiber、ctx.extend、ctx.plugin 等）。不过，它并非安全边界：你注入的服务（例如 ctx.bash）会访问真实运行时。
 
 ```json
 {

From 3b5ee1dce17545efb97e220f0598aaa5d740d48d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 13:57:50 +0800
Subject: [PATCH 459/516] fix(windows): address native CI review findings

---
 ...rial-cross-platform-ci-reference.i18n.yaml |  4 ++--
 ...7-21-serial-cross-platform-ci-reference.md |  2 +-
 ...1-serial-cross-platform-ci-reference.zh.md |  2 +-
 .github/workflows/ci.yml                      |  5 +++--
 apps/cli/src/profile-boot.ts                  | 11 +++++++---
 .../boot/app-boot/tests/hmr-config.spec.ts    |  6 +++--
 packages/util/paths/src/index.ts              | 22 ++++++++++++++-----
 scripts/ci-workflow.spec.ts                   |  1 +
 vendor/README.md                              |  2 +-
 vendor/hmr/src/index.ts                       |  7 +++---
 10 files changed, 41 insertions(+), 21 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
index 5e8f015f50..33bffe92ff 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.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 .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
-2026-07-21-serial-cross-platform-ci-reference.md: dd41cdb51bd226b19bc6aca498c7713a3cc9a6b7
-2026-07-21-serial-cross-platform-ci-reference.zh.md: ec026df8164df0a2400200adbe81230920ce5daa
+2026-07-21-serial-cross-platform-ci-reference.md: 07dc430e6fed3fe75a006ca03523bd6e4fc969d0
+2026-07-21-serial-cross-platform-ci-reference.zh.md: 8bbb60cdead2957069de22ecaddf01c6cd9fb305
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
index dd41cdb51b..07dc430e6f 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
@@ -16,7 +16,7 @@ Real-kernel sandbox proofs require specific hosted operating systems and archite
 
 ## Decision
 
-[CI](../../../../.github/workflows/ci.yml) gives pull-request and master-push events complementary responsibilities. Pull requests run consolidated Linux and Wine-hosted Windows jobs plus the Node compatibility and Python contracts on standard GitHub-hosted capacity; an independent native Windows job reports the complete Windows inventory without participating in the required aggregate. A push to `master` skips those jobs and runs four explicit references: `serial / linux`, `serial / macos`, and `serial / windows` on standard hosted runners, plus `serial / linux (self-hosted standby)` on the in-house `vm-backup` pool — the hot-standby drill that continuously re-proves the failover target described in the [failover runbook](2026-07-26-ci-failover-runbook.md). They intentionally duplicate their short checkout, runtime setup, and immutable install sequences instead of hiding the operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks.
+[CI](../../../../.github/workflows/ci.yml) gives pull-request and master-push events complementary responsibilities. Pull requests run consolidated Linux and Wine-hosted Windows jobs plus the Node compatibility and Python contracts on standard GitHub-hosted capacity; an independent native Windows job reports the complete Windows inventory without participating in the required aggregate. On a push to `master`, the active reference is `serial / linux (self-hosted standby)` on the in-house `vm-backup` pool — the hot-standby drill that continuously re-proves the failover target described in the [failover runbook](2026-07-26-ci-failover-runbook.md). The standard-hosted `serial / linux`, `serial / macos`, and `serial / windows` definitions remain disabled under `TODO(hosted-serial-ci)` until their portable capacity can be restored. The separate job definitions intentionally keep their short checkout, runtime setup, and immutable install sequences visible instead of hiding operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks.
 
 Each reference job runs `pnpm run check:ci` without any shard selector. `DSH_GATE_CONCURRENCY=1` makes the top-level aggregate execute one ready gate at a time; coverage, snapshot replay, built-bin smoke, and publication validation also receive worker counts of one. The reference jobs may run beside one another, but each host's repository gates are serial and complete. Linux installs bubblewrap before replaying snapshots, and Windows enables Developer Mode before installing the symlinked workspace.
 
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
index ec026df816..8bbb60cdea 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 ## 决策
 
-[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和由 Wine 承载的 Windows 作业，以及 Node 兼容性与 Python 约定；一个独立的原生 Windows 作业会报告完整的 Windows 清单，但不参与必需聚合流程。向 `master` 推送时会跳过这些作业，改为运行四个显式参考作业：在标准托管运行器上的 `serial / linux`、`serial / macos` 和 `serial / windows`，以及在公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——后者是热备演练，持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。这些作业有意分别重复简短的代码检出、运行时设置和依赖锁定的安装步骤，不用矩阵或可复用工作流把操作系统差异隐藏起来。`workflow_dispatch` 仅用于运行器基准测试。
+[CI](../../../../.github/workflows/ci.yml) 为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求在 GitHub 标准托管容量上运行合并后的 Linux 和由 Wine 承载的 Windows 作业，以及 Node 兼容性与 Python 约定；一个独立的原生 Windows 作业会报告完整的 Windows 清单，但不参与必需聚合流程。向 `master` 推送时，当前启用的参考作业是公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)`——该热备演练持续验证[故障切换手册](2026-07-26-ci-failover-runbook.md)所描述的切换目标。标准托管的 `serial / linux`、`serial / macos` 和 `serial / windows` 定义仍处于禁用状态，并由 `TODO(hosted-serial-ci)` 标记，直到其可移植容量恢复。各自独立的作业定义有意显式保留简短的代码检出、运行时设置和依赖锁定的安装步骤，而不是用矩阵或可复用工作流隐藏操作系统差异。`workflow_dispatch` 仅用于运行器基准测试。
 
 每个参考作业均在不设置任何分片选择器的情况下运行 `pnpm run check:ci`。`DSH_GATE_CONCURRENCY=1` 使顶层聚合每次只执行一个已经就绪的门禁；覆盖率、快照回放、built-bin 冒烟测试和发布验证的 worker 数量也设为 1。各参考作业可以彼此并行，但每台主机上的仓库门禁都串行运行且完整执行。Linux 在回放快照前安装 bubblewrap，Windows 则在安装采用符号链接的工作区前启用开发人员模式。
 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d3e2239fdd..264cbd9f6c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -431,6 +431,7 @@ jobs:
     if: github.event_name == 'pull_request'
     runs-on: windows-2025
     name: windows node 24 / native complete
+    timeout-minutes: 60
     env:
       DSH_GATE_CONCURRENCY: '1'
       DSH_PUBLINT_CONCURRENCY: '1'
@@ -721,8 +722,8 @@ jobs:
         with:
           dest: ${{ runner.temp }}/setup-pnpm
 
-      # The Windows lanes deliberately skip the store cache like the required
-      # windows job; an empty cache input disables setup-node's caching.
+      # The benchmark's Windows lanes deliberately skip the store cache like
+      # the independent native Windows job; an empty input disables caching.
       - uses: actions/setup-node@v6
         with:
           node-version: ${{ env.PRIMARY_NODE_VERSION }}
diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts
index b49bd37535..b4fee306cf 100644
--- a/apps/cli/src/profile-boot.ts
+++ b/apps/cli/src/profile-boot.ts
@@ -168,6 +168,7 @@ export interface RunProfileOptions {
   environment: EnvironmentSnapshot
 }
 
+/** Re-throw setup failures unless this invocation's signal already owns shutdown. */
 function suppressSignalShutdownError(signal: AbortSignal, error: unknown): void {
   if (!signal.aborted) throw error
 }
@@ -253,9 +254,13 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
   })
   app.current = ctx
   // A surface can dispose the whole tree while startup or this post-boot
-  // watcher setup is still in flight. Fiber state owns liveness; the local
-  // signal fact distinguishes that expected exit race from a real HMR error.
-  if (watchProfilePatch && !signalShutdown.signal.aborted && ctx.fiber.state === FiberState.ACTIVE) {
+  // watcher setup is still in flight. Loader presence and fiber state own
+  // liveness; the local signal fact distinguishes that expected exit race
+  // from a real HMR error.
+  if (watchProfilePatch
+    && !signalShutdown.signal.aborted
+    && ctx.fiber.state === FiberState.ACTIVE
+    && ctx.get('loader') !== undefined) {
     try {
       // Config-only HMR for the live profile patch layer: the web bundle
       // disables the shared module-reload `hmr` row (its reload lifecycle is
diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index fe6bb556b4..ba14e6967f 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -6,7 +6,7 @@ import { Context } from 'cordis'
 import Hmr from '@cordisjs/plugin-hmr'
 import Loader from '@cordisjs/plugin-loader'
 import Timer from '@cordisjs/plugin-timer'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 
 async function bootHmr(dir: string, root: string[] = []): Promise<Context> {
   const ctx = new Context()
@@ -33,7 +33,8 @@ describe('HMR exact config paths', () => {
     symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
     writeFileSync(filename, 'export const generation = 0\n')
     const ctx = await bootHmr(alias, ['.'])
-    const expected = pathToFileURL(filename).href
+    const expected = pathToFileURL(join(realpathSync(target), 'module.ts')).href
+    const cacheHas = vi.spyOn(ctx.loader.internal!.loadCache, 'has').mockReturnValue(false)
     const observed: string[] = []
     ctx.on('hmr/change', (url) => { observed.push(url) })
     try {
@@ -43,6 +44,7 @@ describe('HMR exact config paths', () => {
         writeFileSync(filename, `export const generation = ${generation}\n`)
         await new Promise(resolve => setTimeout(resolve, 20))
       }
+      expect(cacheHas).toHaveBeenCalledWith(expected)
     } finally {
       await ctx.fiber.dispose()
       rmSync(alias, { force: true })
diff --git a/packages/util/paths/src/index.ts b/packages/util/paths/src/index.ts
index 591158d7c0..122408509a 100644
--- a/packages/util/paths/src/index.ts
+++ b/packages/util/paths/src/index.ts
@@ -4,7 +4,7 @@
  * @module @deepseek-ai/dsh-paths
  */
 
-import { realpath } from 'node:fs/promises'
+import { opendir, realpath } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 
@@ -20,19 +20,29 @@ export const DSH_HOME_ENV = 'DSH_HOME'
 /**
  * Give a native filesystem watcher one canonical spelling of a path, even
  * when its final components do not exist yet. The deepest existing ancestor
- * is resolved through {@link realpath}; the missing suffix is then restored.
- * This prevents Windows short-name aliases from being mixed with long paths
- * emitted by the native watcher backend.
+ * is resolved through {@link realpath}; when a suffix is missing, that
+ * ancestor is also proved to be an enumerable directory before the suffix is
+ * restored. This prevents Windows from treating a regular-file ancestor as
+ * ordinary absence, and prevents short-name aliases from being mixed with
+ * long paths emitted by the native watcher backend.
  * @param path - Watch target or root, resolved against the current directory.
  * @returns the target with its existing ancestor canonicalized.
- * @throws when ancestor traversal encounters an error other than absence.
+ * @throws when ancestor traversal encounters an error other than absence, or
+ * the existing ancestor of a missing suffix is not an enumerable directory.
  */
 export async function canonicalizeWatchPath(path: string): Promise<string> {
   let current = resolve(path)
   const missing: string[] = []
   while (true) {
     try {
-      return join(await realpath(current), ...missing.reverse())
+      const canonical = await realpath(current)
+      if (missing.length > 0) {
+        // A Windows file-as-parent probe reports ENOENT. Opening the resolved
+        // ancestor preserves the cross-platform directory requirement.
+        const directory = await opendir(canonical)
+        await directory.close()
+      }
+      return join(canonical, ...missing.reverse())
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
       const parent = dirname(current)
diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts
index 05edaaef55..128988a464 100644
--- a/scripts/ci-workflow.spec.ts
+++ b/scripts/ci-workflow.spec.ts
@@ -53,6 +53,7 @@ describe('CI workflow', () => {
     expect(workflow.jobs).toHaveProperty('wine-apt-cache')
     expect(windowsNative['runs-on']).toBe('windows-2025')
     expect(windowsNative.name).toBe('windows node 24 / native complete')
+    expect(windowsNative['timeout-minutes']).toBe(60)
     expect(windowsNative.if).toBe("github.event_name == 'pull_request'")
     expect(windowsNative).not.toHaveProperty('continue-on-error')
     expect(nativeCommandSteps).toHaveLength(3)
diff --git a/vendor/README.md b/vendor/README.md
index 0e44771616..a5e998ef39 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -38,7 +38,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 6. **`cordis/src/fiber.ts` lifecycle hardening**: locally closes three reentrant disposal gaps. An effect's owner-list wrapper is registered before its setup body runs, so an unload begun from inside setup awaits setup and every collected cleanup; synchronous setup failure removes the wrapper and rolls back collected cleanup. Async cleanup stays owner-visible until quiescence, and Cordis's internal effect composition joins an already-running cleanup while repeated public disposer calls retain their upstream single-shot result. Effect creation is rejected while the owner is `UNLOADING` (while `PENDING` and `LOADING` remain legal), preventing cleanup-time registrations from escaping the unload snapshot. Child fibers register and receive their parent-owned disposer before `internal/plugin` publication, resolve dependency declarations added by that notification before activation, drain effects attached while pending, skip plugin execution when reentrant disposal invalidates the load epoch before its first checkpoint, and contain teardown-notification failures per observer so one callback cannot starve peers or interrupt ownership cleanup. `Fiber.update()` returns its `internal/update` waterfall result, allowing Loader callers to await a restart while preserving synchronous config validation.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
-9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Module watches realpath their existing base directory; exact config watches realpath the deepest existing watch ancestor and restore the missing suffix. Those native paths prevent Windows short-name aliases from colliding with long-form libuv event paths while callbacks keep the requested filename. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
+9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Module watches realpath their existing base directory and use that spelling for Node module-cache identity; exact config watches realpath the deepest existing watch ancestor and restore the missing suffix. Those native paths prevent Windows short-name aliases from colliding with long-form libuv event paths while exact-config callbacks keep the requested filename. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
 10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. A transaction-owned `pnpm` wrapper makes pnpm's nested Git-package install reinvoke the same bundled entry with `--ignore-workspace`, so the selected package installs its own manifest dependencies instead of joining an enclosing source workspace. The temporary command directory is removed after the child settles. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` whose package is excluded from an enclosing pnpm lockfile and obtains both its build and prepare commands from declared dependencies.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
diff --git a/vendor/hmr/src/index.ts b/vendor/hmr/src/index.ts
index c1d379e36c..7c36201b13 100644
--- a/vendor/hmr/src/index.ts
+++ b/vendor/hmr/src/index.ts
@@ -242,12 +242,13 @@ class Hmr extends Service {
 
     const onChange = (kind: 'add' | 'change' | 'unlink', path: string) => {
       this.ctx.logger.debug('%s detected at %C', kind, path)
-      const filename = resolve(this.baseDir, path)
+      const filename = resolve(watchBaseDir, path)
+      const configuredFilename = resolve(this.baseDir, path)
       // Config reload: the file is a loader config file (e.g. cordis.yml).
       for (const entry of loader.entries()) {
         const include = entry.subtree as Include | undefined
-        if (include?.filename !== filename) continue
-        this.refreshConfig(include, filename, () => include.refresh())
+        if (include?.filename !== filename && include?.filename !== configuredFilename) continue
+        this.refreshConfig(include, include.filename, () => include.refresh())
         return
       }
 

From c12bcc6f4b1828e5c2e91abd11cdcc285638e9ae Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 14:33:57 +0800
Subject: [PATCH 460/516] fix(docs): close remaining typography review gaps

---
 .../2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml      | 2 +-
 .../2026-07-19-gui-layering-and-rpc-protocol.zh.md          | 6 +++---
 .../2026-08-04-composer-tab-gutter-reservation.i18n.yaml    | 2 +-
 .../2026-08-04-composer-tab-gutter-reservation.zh.md        | 2 +-
 .../2026-07-31-gui-full-access-confirmation.i18n.yaml       | 2 +-
 .../feature/2026-07-31-gui-full-access-confirmation.zh.md   | 2 +-
 .../feature/2026-07-31-session-archive-global-set.i18n.yaml | 2 +-
 .../feature/2026-07-31-session-archive-global-set.zh.md     | 2 +-
 .../feature/2026-08-03-fs-tool-error-remedy.i18n.yaml       | 2 +-
 .../feature/2026-08-03-fs-tool-error-remedy.zh.md           | 2 +-
 .../process/2026-07-20-gui-testing-system.i18n.yaml         | 2 +-
 .../implemented/process/2026-07-20-gui-testing-system.zh.md | 2 +-
 .../2026-08-06-doc-site-carries-its-images.i18n.yaml        | 2 +-
 .../process/2026-08-06-doc-site-carries-its-images.zh.md    | 2 +-
 .../process/2026-08-08-browser-gif-evidence-chain.i18n.yaml | 2 +-
 .../process/2026-08-08-browser-gif-evidence-chain.zh.md     | 2 +-
 16 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 4578e9e268..cb882f6bc5 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
 2026-07-19-gui-layering-and-rpc-protocol.md: 8e020e4fe9b60100671c0cf0e98e28532d850f94
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 49ebd642264c663377f16b8669fedc112d3bb6c7
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 5c7ee5a407216807e84bd2e62f604dc9c24b6ec9
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 49ebd64226..5c7ee5a407 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -8,8 +8,8 @@ Status: implemented
 
 ## Problem
 
-需要提供 UI 对接层，除已有 ACP/stdio基础版本外，还需要 Web(server) 、 Electron 、等其他产品 UI 形态。我们把这些形态统一称为 Client。希望有如下能力支持:
-- 以 `dsh` 进程，同时支持 `dsh web`(启动) 和 `dsh run`(headless) ，一个进程两种模式（设计预留）
+需要提供 UI 对接层，除已有 ACP（Agent Client Protocol）/stdio 基线外，还需要 Web（server）、Electron 等其他产品 UI 形态。我们把这些形态统一称为 Client。希望具备以下能力：
+- 一个 `dsh` 进程同时支持 `dsh web`（启动）和 `dsh run`（headless），一个进程两种模式（设计预留）
 - 以与 `dsh web` 同构的 Web 技术形态，在 Electron 中启动
 
 那么当前的工程代码需要稳定的分层职责模型，便于以后接入各类 client 形态。
@@ -20,7 +20,7 @@ Status: implemented
 
 ### 分层
 
-目录按照如下分层:
+目录按照如下分层：
 - `packages/host/*`: 包只提供 Host 侧能力（代表了以现在 Harness 实体插件系统为主体的 Node.js 代码核心工程），除此之外，还包含
     - 统一后端协议（fetch、HTTP、流式接口等）定义和支持，见本篇「消息协议」起各节
 - `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住三类包（两条轴归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有）：
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
index 3b41a39be5..8a9b6236ae 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md
 2026-08-04-composer-tab-gutter-reservation.md: 3b28c35c1f11676e41cabde76d1b0d16c688f034
-2026-08-04-composer-tab-gutter-reservation.zh.md: 8724195a53a846d0fb09fb1182f94a40214c23d8
+2026-08-04-composer-tab-gutter-reservation.zh.md: c357dd06c52a834c18d2e8a25246d4ad003db548
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
index 8724195a53..c357dd06c5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.zh.md
@@ -36,7 +36,7 @@ overlay 状态是一个没有任何东西会去滚动它的滚动容器：视图
 
 ## 后果
 
-- Chat 的内容列永久变窄 8px——hero 态与transcript 尚短、根本不绘制滚动条时同样如此。这就是这笔交易：以最宽的列换取卡片在任何内容高度下都只有一个位置。
+- Chat 的内容列永久变窄 8px——hero 态与 transcript 尚短、根本不绘制滚动条时同样如此。这就是这笔交易：以最宽的列换取卡片在任何内容高度下都只有一个位置。
 - 一条声明覆盖三种切换，因为这三者本就是同一个差异：Chat ↔ Trajectory、Chat 内部 transcript 较短 ↔ transcript 可滚动，以及 hero ↔ 第一个可滚动轮次。
 - overlay 状态现在是一个滚动容器。今天其中没有任何内容会溢出；将来若有视图允许自身内容超出会话列，这个盒子会滚动而不是裁剪，那个视图就需要像 Trajectory 视图那样自带裁剪。
 - 提交的 golden 记录了预留条带，因此样式表中 `::-webkit-scrollbar` 宽度的变化——决定这条预留有多宽的那个值——会在本场景中与在侧边栏场景中一样，以可评审的 diff 形式出现。
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
index fa5ea6f634..ef08e0829b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.md
 2026-07-31-gui-full-access-confirmation.md: ca89ed23fb1b5c6ea438dd22fdf20d2b82af754c
-2026-07-31-gui-full-access-confirmation.zh.md: a31c1ee744b111dd6917f0d2ed7ba9988c2aee47
+2026-07-31-gui-full-access-confirmation.zh.md: b4ab92271f6b4a6ebe3b7e7c3f82f859c53933bf
diff --git a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
index a31c1ee744..b4ab92271f 100644
--- a/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-gui-full-access-confirmation.zh.md
@@ -13,7 +13,7 @@ Status: implemented
 **每个权限选择器都把 `danger-full-access` 关进共享的页面内 `RiskConfirmation` 对话框：启用按钮在用户勾选明确的风险确认复选框前保持禁用；预设以产品标签 `Full access` 展示；所有取消路径都不作任何提交。**
 
 - `RiskConfirmation`（ui-primitives）是受控的 Modal 组合：标题、说明、确认复选框、取消，以及 `acknowledged` 勾选前禁用的确认按钮。它始终是页面内对话框——Modal portal 到本文档 body，绝不打开可能落在另一块显示器上的原生或独立浏览器窗口。`Modal` 新增 `contentClassName` slot，令警示正文在受限的移动端／横屏视口内滚动，动作行保持固定。
-- composer chip（ui-conversation 的 `PermissionSelect`）在 `/permission` 提交前拦截 Full-access 选择：`confirmation`/`acknowledged` 组件状态打开对话框，确认后经与其他选择完全相同的注入 `command` 通道提交 `/permission danger-full-access`；取消、Escape、关闭与遮罩点击均保持当前预设不变并重置复选框。会话锁定时确认自行撤销（`locked`／值缺席 effect），切换任务时随 `key={sessionId}` 重挂载而重置。文案经标准 `conversation` locale slot以 `access.confirm.*` 键供给。
+- composer chip（ui-conversation 的 `PermissionSelect`）在 `/permission` 提交前拦截 Full-access 选择：`confirmation`/`acknowledged` 组件状态打开对话框，确认后经与其他选择完全相同的注入 `command` 通道提交 `/permission danger-full-access`；取消、Escape、关闭与遮罩点击均保持当前预设不变并重置复选框。会话锁定时确认自行撤销（`locked`／值缺席 effect），切换任务时随 `key={sessionId}` 重挂载而重置。文案经标准 `conversation` locale slot 以 `access.confirm.*` 键供给。
 - `/permission` popup（ui-permission 构建于 ui-command 外壳之上）以数据而非第二套对话框实现完成把关：`SelectOption` 新增可选的 `confirmation` 载荷，popup 控制器拥有 `confirming`/`acknowledged` 状态迁移，`PopupSelectView` 在门控选项未决期间把选择卡换成同一个 `RiskConfirmation`。
 - 「通用」设置中的「权限」行在把 Full access 持久化为后续会话的默认值前，也使用同一个受控 `RiskConfirmation`。警示会明确说明该设置只影响后续会话；取消、Escape、关闭与点击遮罩均不会改动已存默认值。
 - `Full access` 在每个选择器中都有意覆盖 kebab 转 Title Case 的显示变换；命令与 Settings 写入在 wire 上保留机器名，每份警示正文都保持中英文 locale 感知。
diff --git a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
index 5565ea70b1..22cc5fb3ea 100644
--- a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-session-archive-global-set.md
 2026-07-31-session-archive-global-set.md: fab99a405a6f8264c36453473327e32905bac9c8
-2026-07-31-session-archive-global-set.zh.md: b10440039f1c6a8ea2f89d9239a0285dd70cf9a2
+2026-07-31-session-archive-global-set.zh.md: 4789c11a6d6883966b2218a16644177408e3df1f
diff --git a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
index b10440039f..4789c11a6d 100644
--- a/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-session-archive-global-set.zh.md
@@ -30,4 +30,4 @@ Sidebar workspace 浏览区的会话行菜单里，「Delete session」一直是
 
 ## 后果
 
-归档后 UI 无查看/取消归档入口（本期口径，记录在 README 的 Known Limitation 中）；数据与slot完好，后续加恢复面只是 UI + 一个逆向 RPC。`workspace.list` 响应形状变化是 pre-release 直改（无兼容层）。e2e（workspace-management）钉住了「归档→行消失→reload 后仍隐藏、日志仍在」的全链路；domain 层测试钉住幂等、未知 id 拒绝、跨重启恢复与旧介质默认升级。
+归档后 UI 无查看/取消归档入口（本期口径，记录在 README 的 Known Limitation 中）；数据与 slot 完好，后续加恢复面只是 UI + 一个逆向 RPC。`workspace.list` 响应形状变化是 pre-release 直改（无兼容层）。e2e（workspace-management）钉住了「归档→行消失→reload 后仍隐藏、日志仍在」的全链路；domain 层测试钉住幂等、未知 id 拒绝、跨重启恢复与旧介质默认升级。
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
index f0dba56167..d9d9142437 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
 2026-08-03-fs-tool-error-remedy.md: f227c31365725652b130e097d70c79d3daab3684
-2026-08-03-fs-tool-error-remedy.zh.md: ed3cbcf9c262db44321036fc1afcc829a5696b2f
+2026-08-03-fs-tool-error-remedy.zh.md: 6bb0d0b6ffcda282db67dd1a54f0074b3be5c6e1
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
index ed3cbcf9c2..6bb0d0b6ff 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
@@ -17,7 +17,7 @@ Status: implemented
 
 结构化 `FsError` 错误码保持不变，使重试/权限/UI 层继续基于它路由；原始错误作为 `cause` 链入。提供方消息保持面向机器且不变。
 
-在 `edit.ts` 中，`fs/edit-intent` waterfall（瀑布式事件）现在与提供方变更位于同一个 `try` 内，因此策略插件从 intent slot抛出的 `FS_NOT_OBSERVED` 拒绝也会获得恢复指令——两条拒绝路径都以相同的恢复措辞到达模型。
+在 `edit.ts` 中，`fs/edit-intent` waterfall（瀑布式事件）现在与提供方变更位于同一个 `try` 内，因此策略插件从 intent slot 抛出的 `FS_NOT_OBSERVED` 拒绝也会获得恢复指令——两条拒绝路径都以相同的恢复措辞到达模型。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
index bafe5adfdf..ddfa339fdd 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-20-gui-testing-system.md
 2026-07-20-gui-testing-system.md: 4a1600bbef7ef795677a446228fcc279a4b53f39
-2026-07-20-gui-testing-system.zh.md: bd617f39a7cd5fd49e5c3a8a992b7dff35a800bf
+2026-07-20-gui-testing-system.zh.md: a0e819fd5269da6aa3379309c76eea006975cef8
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
index bd617f39a7..a0e819fd52 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
@@ -18,7 +18,7 @@ GUI 栈需要考虑多种应用形态，同应用形态内的不同运行环境
 
 | 层 | 被测物 | 关键手段 | 文件落点 |
 |---|---|---|---|
-| 1 协议同构层 | `AbstractApiClient` + `toFetchHandler`（双向数据/rpcId/ZOD类型/SSE 流/合批/超时） | **同构点全链**：`InProcessApiClient(toFetchHandler(脚本化 impl))` 不过网络但真跑 wire 序列化——零浏览器、纯 node env | `packages/host/apiproxy/tests/client-handler.spec.ts` |
+| 1 协议同构层 | `AbstractApiClient` + `toFetchHandler`（双向数据/rpcId/ZOD 类型/SSE 流/合批/超时） | **同构点全链**：`InProcessApiClient(toFetchHandler(脚本化 impl))` 不过网络但真跑 wire 序列化——零浏览器、纯 node env | `packages/host/apiproxy/tests/client-handler.spec.ts` |
 | 2 对象层编排 | `Session`/`SessionManager`/`ConnectionController`（状态机与时序：缝合/去重/翻页/乐观清稿/pendingBuffers/重连/退避） | **「事件序列进→快照出」黄金路径**：可编程假体 + deferred 控时序 + fake timers 控退避 | `packages/client/{runtime,connection}/tests/` |
 | 3 组装呈现层 | 构建产物 × 真实 client loader 与插件组合 | 归应用所有的语义快照会在 jsdom 下启动全部 8 个已构建的 client 插件，以固定确定性的跨插件状态变化；独立使用 Playwright 裸库的冒烟测试负责验证真实浏览器/承载层边界，真 host 用例在无密钥时自行跳过；无密钥浏览器 e2e 车道会禁用交付配置中的模型适配器行，并通过 `dsh-llm-replay` 在真实进程内 web 组装中回放录制的会话 fixture，与会话区 aria 期望输出比对（[web e2e 车道](../testing/2026-07-24-web-gui-browser-e2e-lane.md)、[必需 CI 门禁](../testing/2026-07-30-web-browser-snapshot-ci-gate.md)） | `apps/web/tests/*.snapshot.ts`、`apps/web/tests/smoke-{fixture,real}.e2e.ts`、`apps/web/tests/{replay-round-trip,seeded-history}.e2e.ts` |
 
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
index 15045d2590..c3bf152222 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.md
 2026-08-06-doc-site-carries-its-images.md: 4078a9b6251cf67456590ae25602a9f288c88dc1
-2026-08-06-doc-site-carries-its-images.zh.md: 134bd20e628322dc9c6d95cb261648618fbdf7a7
+2026-08-06-doc-site-carries-its-images.zh.md: 4ab90f9736dae95090b0d805f6fbe5d4846c7a0c
diff --git a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
index 134bd20e62..4ab90f9736 100644
--- a/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-doc-site-carries-its-images.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-`rewriteMarkdown` 新增可选的 `placeImage(absPath): string`。当页面引用了一张manifest 未作为页面发布的图片时，投影把该文件复制进生成树中该页面的旁边，并把引用改写为 `./<basename>`；随后 Vite 会像处理其他站点资源一样打包它。仓库可见性再也影响不到已发布页面。
+`rewriteMarkdown` 新增可选的 `placeImage(absPath): string`。当页面引用了一张 manifest 未作为页面发布的图片时，投影把该文件复制进生成树中该页面的旁边，并把引用改写为 `./<basename>`；随后 Vite 会像处理其他站点资源一样打包它。仓库可见性再也影响不到已发布页面。
 
 副本落在页面旁边，而不是某个共享资源目录。每个 locale 的路由树各持一份副本，因此同一个相对 URL 在 `guide/` 与 `en/guide/` 下都正确，无需按 locale 计算前缀；manifest 撤下某页时，它的资源也随之消失。一张表登记所有被投影的路径——页面与图片一视同仁——同一路径出现第二个来源就抛错，与既有的重复路由检查同一个立场，而不是让最后写入的那个静默胜出。
 
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
index bd7ec32f75..822265cb31 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
 2026-08-08-browser-gif-evidence-chain.md: 93dfad76b3c4d0934120a164ab22dd4b898e2e01
-2026-08-08-browser-gif-evidence-chain.zh.md: 7b21abb23b5cb3a7b5dd8fd2accc561974008ad9
+2026-08-08-browser-gif-evidence-chain.zh.md: afb45b4771766c4ab6e44b0f4f91f01f3827668d
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
index 7b21abb23b..afb45b4771 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求worktree 干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器上下文时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
+[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求 worktree 干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器上下文时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
 
 浏览器自动化会等待唯一且精确的语义状态。如果需要证明工具调用、拒绝或恢复，分镜就必须包含详情帧或轨迹帧：标明工具、显示其状态或稳定错误码，并展示后续结果。最终编码出的 GIF 始终是验证对象；如果查看器无法播放动画，应从该 GIF 中解码出代表性帧，而不能将源截图视为等效证据。
 

From 3754c0d58615899d0040d12050b35526323e9b16 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 14:35:46 +0800
Subject: [PATCH 461/516] test(windows): let HMR atomic changes settle

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index ba14e6967f..033ad1661a 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -42,7 +42,8 @@ describe('HMR exact config paths', () => {
       for (let generation = 1; !observed.includes(expected); generation += 1) {
         if (Date.now() >= deadline) throw new Error('HMR did not observe a module change through the alias')
         writeFileSync(filename, `export const generation = ${generation}\n`)
-        await new Promise(resolve => setTimeout(resolve, 20))
+        // Leave Chokidar's atomic-write window idle so one coalesced change can publish.
+        await new Promise(resolve => setTimeout(resolve, 250))
       }
       expect(cacheHas).toHaveBeenCalledWith(expected)
     } finally {

From 7016ad93deb203e28cc306f8e88e98bdd69215ff Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 14:55:06 +0800
Subject: [PATCH 462/516] refactor: make lint workflows Oxlint-only

---
 .../2026-06-11-quality-gates.i18n.yaml        |   4 +-
 .../process/2026-06-11-quality-gates.md       |   2 +-
 .../process/2026-06-11-quality-gates.zh.md    |   2 +-
 .../2026-07-22-fast-local-git-hooks.i18n.yaml |   4 +-
 .../2026-07-22-fast-local-git-hooks.md        |   6 +-
 .../2026-07-22-fast-local-git-hooks.zh.md     |   6 +-
 .../2026-07-29-oxlint-linter.i18n.yaml        |   4 +-
 .../process/2026-07-29-oxlint-linter.md       |  14 +-
 .../process/2026-07-29-oxlint-linter.zh.md    |  14 +-
 ...6-08-09-oxlint-only-fix-workflow.i18n.yaml |   6 +
 .../2026-08-09-oxlint-only-fix-workflow.md    |  37 ++++
 .../2026-08-09-oxlint-only-fix-workflow.zh.md |  37 ++++
 .oxlintrc.json                                |  18 ++
 .oxlintrc.staged.json                         |  17 +-
 THIRD_PARTY_NOTICES.md                        |   2 -
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +-
 docs/development.zh.md                        |   2 +-
 eslint.format.config.mjs                      |  59 ------
 lefthook.yml                                  |   7 -
 package.json                                  |   4 +-
 pnpm-lock.yaml                                | 105 -----------
 scripts/oxlint-contract.spec.ts               | 172 +++++++++++++-----
 scripts/run-oxlint.ts                         |  48 ++++-
 24 files changed, 323 insertions(+), 253 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.md
 create mode 100644 .agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.zh.md
 delete mode 100644 eslint.format.config.mjs

diff --git a/.agents/notes/implemented/process/2026-06-11-quality-gates.i18n.yaml b/.agents/notes/implemented/process/2026-06-11-quality-gates.i18n.yaml
index e8cdb21a40..3134a16824 100644
--- a/.agents/notes/implemented/process/2026-06-11-quality-gates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-11-quality-gates.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 .agents/notes/implemented/process/2026-06-11-quality-gates.md
-2026-06-11-quality-gates.md: 60db7ba5cfa8184c0fcce764aa027f32a9b721ab
-2026-06-11-quality-gates.zh.md: 10585977820ba8e4f4bc6e251d484dc657d0558c
+2026-06-11-quality-gates.md: 83cba5c867f71471d421ab935e1f53b430b01c43
+2026-06-11-quality-gates.zh.md: 1162b3836424bd47a8d35bd754a7983ac2e9bebe
diff --git a/.agents/notes/implemented/process/2026-06-11-quality-gates.md b/.agents/notes/implemented/process/2026-06-11-quality-gates.md
index 60db7ba5cf..83cba5c867 100644
--- a/.agents/notes/implemented/process/2026-06-11-quality-gates.md
+++ b/.agents/notes/implemented/process/2026-06-11-quality-gates.md
@@ -19,7 +19,7 @@ Every mechanically checkable AGENTS.md promise gets a command that exits non-zer
 - jscpd detects cross-file clones in package production TypeScript and repository scripts; narrow source-range exceptions document deliberately parallel implementations.
 - Per-file 100% coverage on `packages/*/*/src` (v8); unreachable defensive guards carry `/* v8 ignore */ ` with stated reasons instead of deletion.
 - knip (dead code/deps), publint (package correctness), workspace constraints (workspace rules: private, cordis peer+dev, uniform version, ESM), and a NodeNext consumer typecheck for built package declarations.
-- lefthook pre-commit applies formatting-only ESLint fixes before Oxlint validation and native fixes, rejects staged whitespace, and checks the vendor manifest; pre-push runs incremental typecheck. CI runs the full matrix on node 22.19/24/26 plus built application smokes for the Headless, TUI, ACP, JSON-RPC, workflow, and code-runtime entry paths.
+- lefthook pre-commit applies project-free Oxlint validation and [safe fixes with a bounded retry](2026-08-09-oxlint-only-fix-workflow.md), rejects staged whitespace, and checks the vendor manifest; pre-push runs incremental typecheck. CI runs the full matrix on node 22.19/24/26 plus built application smokes for the Headless, TUI, ACP, JSON-RPC, workflow, and code-runtime entry paths.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-06-11-quality-gates.zh.md b/.agents/notes/implemented/process/2026-06-11-quality-gates.zh.md
index 1058597782..1162b38364 100644
--- a/.agents/notes/implemented/process/2026-06-11-quality-gates.zh.md
+++ b/.agents/notes/implemented/process/2026-06-11-quality-gates.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 - jscpd 检测包的生产 TypeScript 代码与仓库脚本中的跨文件克隆；窄范围的源码区间例外用于记录有意为之的并行实现。
 - `packages/*/*/src` 下按文件 100% 覆盖率（v8）；不可达的防御性守卫使用 `/* v8 ignore */ ` 并注明理由，而非删除。
 - knip（死代码/依赖）、publint（包的正确性）、workspace 约束（workspace 规则：private、cordis peer+dev、统一版本、ESM），以及对构建出的包声明文件进行 NodeNext 消费方类型检查。
-- lefthook pre-commit 先应用仅用于格式化的 ESLint 修复，再执行 Oxlint 验证和原生修复，拒绝已暂存的空白问题并检查 vendor manifest（元数据清单）；pre-push 运行增量类型检查。CI 在 Node 22.19/24/26 上运行完整矩阵，并对 Headless、TUI、ACP（Agent Client Protocol）、JSON-RPC、工作流和代码运行时入口路径执行已构建应用的冒烟测试。
+- lefthook pre-commit 执行不加载项目的 Oxlint 验证，并应用带[一次有界重试](2026-08-09-oxlint-only-fix-workflow.md)的安全修复，拒绝已暂存的空白问题并检查 vendor manifest（元数据清单）；pre-push 运行增量类型检查。CI 在 Node 22.19/24/26 上运行完整矩阵，并对 Headless、TUI、ACP（Agent Client Protocol）、JSON-RPC、工作流和代码运行时入口路径执行已构建应用的冒烟测试。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
index 0121a65219..701e850d7f 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.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 .agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
-2026-07-22-fast-local-git-hooks.md: af8a9380fc3cbf4f672ca0b32faa7b187522cf11
-2026-07-22-fast-local-git-hooks.zh.md: 1b2c3bf42a65f35d96c266f5f3afb63f26039388
+2026-07-22-fast-local-git-hooks.md: c3d3579b2e91419fad64f0e64a10926d2362881e
+2026-07-22-fast-local-git-hooks.zh.md: f85daa9c74a23987cc560f14c5e087fdfb3d7f5e
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
index af8a9380fc..c3d3579b2e 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.md
@@ -12,7 +12,7 @@ Fast hooks still need to reject cheap, high-confidence defects before work leave
 
 ## Decision
 
-[lefthook.yml](../../../../lefthook.yml) keeps both hooks as bounded local checkpoints. Pre-commit runs sequentially: a formatting-only ESLint config fixes and re-stages changed JavaScript and TypeScript, a project-free [Oxlint](2026-07-29-oxlint-linter.md) profile validates those files and applies native safe fixes, `git diff --cached --check` rejects staged whitespace errors, and the vendor manifest guard checks vendored-source metadata. Pre-push runs `pnpm run typecheck`, which prepares the generated Host TypeRT contracts before the Client incremental typecheck.
+[lefthook.yml](../../../../lefthook.yml) keeps both hooks as bounded local checkpoints. Pre-commit runs sequentially: a project-free [Oxlint](2026-07-29-oxlint-linter.md) profile validates changed JavaScript and TypeScript, applies safe fixes with a [bounded retry](2026-08-09-oxlint-only-fix-workflow.md), and re-stages them; `git diff --cached --check` rejects staged whitespace errors, and the vendor manifest guard checks vendored-source metadata. Pre-push runs `pnpm run typecheck`, which prepares the generated Host TypeRT contracts before the Client incremental typecheck.
 
 Pre-commit does not run type analysis, tests, snapshots, documentation checks, builds, hygiene, or the gate scheduler. Pre-push adds only the Host contract build required by repository typecheck. The opt-in `check:all` package script selects the `check-all` scheduler inventory in [scripts/run-gates.ts](../../../../scripts/run-gates.ts) independently of the hooks; it is a contributor command, not an agent instruction.
 
@@ -27,10 +27,10 @@ This decision supersedes the local-hook portion of [Parallel pre-push gates](202
 - **Keep the full pre-push suite and optimize its scheduler** — preserves the earliest exhaustive signal but still repeats agent-selected evidence and CI, while unrelated failures continue blocking publication.
 - **Remove pre-push entirely** — makes pushes cheapest but loses the fast cross-file guarantee that TypeScript provides after several commits.
 - **Keep typecheck in pre-commit** — catches type errors earlier but charges every intermediate commit instead of one push; staged lint already covers the commit-local syntax and style boundary.
-- **Make staged lint check-only** — avoids hook-side mutation, but contributors intentionally retain the auto-fix workflow; the formatting-only pass and Lefthook's `stage_fixed` preserve it without making ESLint a repository correctness runner or duplicating `git add`.
+- **Make staged lint check-only** — avoids hook-side mutation, but contributors intentionally retain the auto-fix workflow; Oxlint's bounded retry and Lefthook's `stage_fixed` preserve it without a separate formatter or duplicate `git add`.
 
 ## Consequences
 
-Normal commits take the project-free staged formatter-and-lint critical path, and warm pushes take the prepared incremental typecheck critical path. Contributors retain a one-command opt-in rehearsal without widening the hook critical paths or the agent-required validation set. Hook latency is observed in development and PR evidence rather than enforced by a timing test whose result would depend on host load and cache state.
+Normal commits take the project-free staged Oxlint fix-and-validate critical path, and warm pushes take the prepared incremental typecheck critical path. Contributors retain a one-command opt-in rehearsal without widening the hook critical paths or the agent-required validation set. Hook latency is observed in development and PR evidence rather than enforced by a timing test whose result would depend on host load and cache state.
 
 Local publication no longer proves the exhaustive repository matrix. Agents must select relevant behavioral evidence, reviewers must evaluate whether that selection matches the diff, and CI supplies the comprehensive signal once per pushed revision.
diff --git a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
index 1b2c3bf42a..f85daa9c74 100644
--- a/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
+++ b/.agents/notes/implemented/process/2026-07-22-fast-local-git-hooks.zh.md
@@ -12,7 +12,7 @@ agent（智能体）已经会运行能够覆盖自身改动的测试和检查，
 
 ## 决策
 
-[lefthook.yml](../../../../lefthook.yml) 将两个钩子都保留为有界的本地检查点。Pre-commit 按顺序运行：仅用于格式化的 ESLint 配置修复改动过的 JavaScript 和 TypeScript 文件并重新暂存，不加载项目的 [Oxlint](2026-07-29-oxlint-linter.md) 配置验证这些文件并应用原生安全修复，`git diff --cached --check` 拒绝暂存 diff 中的空白错误，vendor manifest（元数据清单）守卫检查 vendor 源码元数据。Pre-push 运行 `pnpm run typecheck`；该命令会先准备好生成的 Host TypeRT 约定，再运行 Client 增量类型检查。
+[lefthook.yml](../../../../lefthook.yml) 将两个钩子都保留为有界的本地检查点。Pre-commit 按顺序运行：不加载项目的 [Oxlint](2026-07-29-oxlint-linter.md) 配置验证改动过的 JavaScript 和 TypeScript 文件，应用带[一次有界重试](2026-08-09-oxlint-only-fix-workflow.md)的安全修复，并重新暂存这些文件；`git diff --cached --check` 拒绝暂存 diff 中的空白错误，vendor manifest（元数据清单）守卫检查 vendor 源码元数据。Pre-push 运行 `pnpm run typecheck`；该命令会先准备好生成的 Host TypeRT 约定，再运行 Client 增量类型检查。
 
 Pre-commit 不运行类型分析、测试、快照、文档检查、构建、`hygiene` 或门禁调度器。Pre-push 只增加仓库类型检查所需的 Host 约定构建。可选运行的 `check:all` 包脚本独立于这些钩子，从 [scripts/run-gates.ts](../../../../scripts/run-gates.ts) 中选择 `check-all` 调度器清单；它是贡献者命令，而非对 agent 的指令。
 
@@ -27,10 +27,10 @@ agent 检查待推送的 diff，并仅运行一次能够覆盖其行为的最小
 - **保留全量 pre-push 套件并优化其调度器**——能够最早提供全面信号，但仍会重复 agent 已选取的证据和 CI，且无关失败仍会阻塞推送。
 - **完全移除 pre-push**——推送成本最低，但会失去 TypeScript 在多个提交之后提供的快速跨文件保证。
 - **在 pre-commit 中保留类型检查**——更早捕获类型错误，但每次中间提交都要承担开销，而不是只在推送时运行一次；暂存文件 lint 已经覆盖提交本身的语法与风格边界。
-- **将暂存文件 lint 设为仅检查模式**——避免钩子修改文件，但贡献者有意保留自动修复工作流；仅用于格式化的流程和 Lefthook 的 `stage_fixed` 会保留该工作流，而不会让 ESLint 成为仓库正确性检查运行器，也无需重复执行 `git add`。
+- **将暂存文件 lint 设为仅检查模式**——避免钩子修改文件，但贡献者有意保留自动修复工作流；Oxlint 的一次有界重试和 Lefthook 的 `stage_fixed` 会保留该工作流，无需单独的格式化器，也无需重复执行 `git add`。
 
 ## 结果
 
-普通提交的关键路径是不加载项目的暂存文件格式化与 lint，缓存已预热时推送的关键路径是经过准备的增量类型检查。贡献者仍可选择用一条命令完整演练，且不会扩展钩子关键路径或 agent 必须运行的验证集合。钩子耗时只作为开发观察数据和 PR（Pull Request）证据记录，不设置会受主机负载与缓存状态影响的计时测试。
+普通提交的关键路径是不加载项目的暂存文件 Oxlint 修复与验证，缓存已预热时推送的关键路径是经过准备的增量类型检查。贡献者仍可选择用一条命令完整演练，且不会扩展钩子关键路径或 agent 必须运行的验证集合。钩子耗时只作为开发观察数据和 PR（Pull Request）证据记录，不设置会受主机负载与缓存状态影响的计时测试。
 
 从本地推送成功不再能证明仓库完整矩阵已通过。agent 必须选择相关的行为证据，评审人必须判断该选择是否与 diff 相符，CI 则对每个推送版本提供一次全面信号。
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
index 9115979c19..851b2a3674 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.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 .agents/notes/implemented/process/2026-07-29-oxlint-linter.md
-2026-07-29-oxlint-linter.md: 3e3de24be33b8f9461cea2967b0fa18f59ddb52a
-2026-07-29-oxlint-linter.zh.md: dae8c7451bd3fbe9296508491aaa51f1118abe92
+2026-07-29-oxlint-linter.md: 15bdd4302745fdf3d1a2bd0d28fbc3d4b9fc50bb
+2026-07-29-oxlint-linter.zh.md: 8e3d69cdce2cc05346149acbd49f9b0b75ac6098
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md
index 3e3de24be3..15bdd43027 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.md
@@ -12,25 +12,25 @@ A faster runner cannot justify losing rules. The migration must preserve the str
 
 ## Decision
 
-The root [`.oxlintrc.json`](../../../../.oxlintrc.json) is the authoritative type-aware repository lint configuration. The project-free [`.oxlintrc.staged.json`](../../../../.oxlintrc.staged.json) profile inherits its source rules but disables type analysis for the bounded pre-commit path. The `lint` package script, gate scheduler, CI, and lefthook invoke Oxlint through [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts); `lint:fix` and lefthook first invoke the formatting-only [`eslint.format.config.mjs`](../../../../eslint.format.config.mjs). The direct `eslint` and `@typescript-eslint/parser` development dependencies exist only for this parser-without-project formatting pass; their exact versions pin the tested parser/fixer pairing, and that config contains no correctness or type-aware rules.
+The root [`.oxlintrc.json`](../../../../.oxlintrc.json) is the authoritative type-aware repository lint configuration. The project-free [`.oxlintrc.staged.json`](../../../../.oxlintrc.staged.json) profile inherits its source rules, disables type analysis for the bounded pre-commit path, and re-includes preserved TypeGraph fixtures that the type-aware backend cannot analyze. The `lint` and `lint:fix` package scripts, gate scheduler, CI, and lefthook invoke Oxlint through [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts); the [Oxlint-only fix workflow](2026-08-09-oxlint-only-fix-workflow.md) owns multipass plugin fixes and supersedes the separate formatting fallback.
 
 `options.typeAware` enables `oxlint-tsgolint`. Its backend performs per-file TypeScript-project discovery: package sources use their package projects, host tests/examples/website use `tsconfig.host.json`, and client tests plus `scripts/client-bundle-purity.spec.ts` use `tsconfig.client.json`. The program-less root solution is never flattened. Oxlint's `--tsconfig` override affects import resolution but is ignored by type-aware linting, so this repository does not set it. The configuration explicitly carries the migrated strict-type-checked rules and repository overrides instead of enabling broad Oxlint categories whose contents may change. `typescript/no-unnecessary-condition` remains enabled from Oxlint's nursery set because it was an enforced repository rule before migration.
 
-Oxlint's JavaScript-plugin compatibility layer runs `@stylistic/eslint-plugin` and `eslint-plugin-sonarjs` so the existing formatting and file-local duplicate-logic rules remain enforced. The compatibility layer reports `@stylistic` violations but does not execute their fixers, so the formatting-only ESLint pass owns only the corresponding auto-fixes; an executable parity check keeps those fixable rule definitions aligned while `max-len` remains validation-only. Owned-source suppressions use `oxlint-*` directives and the `typescript/*` namespace, and unused directives remain warnings; vendored sources keep their upstream directives because Oxlint excludes `vendor/**`.
+Oxlint's JavaScript-plugin compatibility layer runs `@stylistic/eslint-plugin` and `eslint-plugin-sonarjs` so the existing formatting and file-local duplicate-logic rules remain enforced. The compatibility layer reports `@stylistic` violations and executes their safe fixes; `max-len` remains validation-only. Owned-source suppressions use `oxlint-*` directives and the `typescript/*` namespace, and unused directives remain warnings; vendored sources keep their upstream directives because Oxlint excludes `vendor/**`.
 
-CI does not restore or save a lint-result cache. `DSH_OXLINT_THREADS` makes the shared runner pass the same bound to Oxlint's `--threads` option and the type-aware backend's `GOMAXPROCS` environment variable; ordinary local runs use both defaults. Pre-commit applies the formatting-only ESLint fixes, runs project-free Oxlint validation and native safe fixes, accepts selections containing only ignored files, and re-stages the result through lefthook. Public `lint` and CI retain the complete type-aware rules after preparing generated declarations.
+CI does not restore or save a lint-result cache. `DSH_OXLINT_THREADS` makes the shared runner pass the same bound to Oxlint's `--threads` option and the type-aware backend's `GOMAXPROCS` environment variable; ordinary local runs use both defaults. Pre-commit runs project-free Oxlint validation and safe fixes with one bounded retry, accepts selections containing only ignored files, and re-stages the result through lefthook. Public `lint` and CI retain the complete type-aware rules after preparing generated declarations.
 
 ## Verification
 
 The migrated configuration reports the same clean owned-source baseline after resolving two analyzer differences: one redundant test assertion was removed, while one structural cast required by `tsc` carries a narrow Oxlint suppression. A one-time audit against the exact deleted ESLint configuration blob established source 88-to-88, examples 87-to-87, and tests 83-to-83 after the rule-name translations. The committed fingerprint pins those audited Oxlint profiles and the complete override shape; it neither executes the deleted configuration nor propagates later upstream preset changes. Evaluating `typescript-eslint@8.61.0` also confirms that `strictTypeChecked` did not enable `@typescript-eslint/no-empty-function`; the deleted tests-only `off` entry was inert.
 
-Executable contract tests require type-aware diagnostics from the package, host, and client projects; assert the client-only script's project; reject unmatched fallback analysis; and exercise the Stylistic, SonarJS, and nursery compatibility paths. They also pin the staged profile's project-free inheritance, unused-suppression reporting, ignored-only staged selections, formatter/validator rule parity, and final formatted bytes. Runner tests pin both worker controls, and typecheck confirms that migration-driven source edits preserve the TypeScript programs.
+Executable contract tests require type-aware diagnostics from the package, host, and client projects; assert the client-only script's project; reject unmatched fallback analysis; and exercise the Stylistic, SonarJS, and nursery compatibility paths. They also pin the staged profile's project-free inheritance and TypeGraph coverage, unused-suppression reporting, ignored-only staged selections, the complete Stylistic rule set, and convergent final formatted bytes. Runner tests pin both worker controls, and typecheck confirms that migration-driven source edits preserve the TypeScript programs.
 
 ## Alternatives considered
 
-**Run both linters repository-wide.** Every correctness rule is available through Oxlint's native rules, nursery rule, or JavaScript-plugin compatibility layer. A repository-wide ESLint fallback would preserve the slower project-service setup and two correctness configurations without adding a check; the retained ESLint pass is deliberately limited to project-free staged formatting.
+**Run both linters repository-wide.** Every correctness rule is available through Oxlint's native rules, nursery rule, or JavaScript-plugin compatibility layer. A repository-wide ESLint fallback would preserve the slower project-service setup and two correctness configurations without adding a check.
 
-**Rely on compatibility-layer fixes.** The layer reports the established `@stylistic` rules but does not apply their fixes under either Oxlint fix mode. Keeping the narrow staged formatter preserves the contributor contract without broadening ESLint back into a repository linter.
+**Use a separate formatter.** The migration retained a narrow ESLint pass because the compatibility-layer fixes were treated as unavailable. The [Oxlint-only fix workflow](2026-08-09-oxlint-only-fix-workflow.md) supersedes that part of the decision with one bounded retry after the pinned toolchain proved it could execute the same fixes.
 
 **Drop @stylistic or SonarJS rules that are not native.** This would remove dependencies but weaken the mechanical quality contract. The compatibility layer preserves those rules until native replacements can be evaluated as a separate decision.
 
@@ -42,4 +42,4 @@ Local migration measurements reduced a clean type-aware lint run from about 61 s
 
 Type-aware diagnostics now come from the TypeScript Go analyzer bundled through `oxlint-tsgolint`, so edge-case inference can differ from typescript-eslint even when `tsc` accepts the same program. Lint and typecheck remain separate required evidence.
 
-The JavaScript-plugin compatibility API, staged profile, and staged formatter are additional boundaries to maintain. Commits defer type-aware diagnostics to public lint and CI, pay one project-free ESLint startup before Oxlint, and avoid depending on generated declarations. The root development graph retains ESLint plus the TypeScript parser. Repository-wide validation, type-aware analysis, cache policy, worker control, and inline directives remain Oxlint-owned.
+The JavaScript-plugin compatibility API and staged profile are additional boundaries to maintain. Commits defer type-aware diagnostics to public lint and CI and avoid depending on generated declarations. Repository-wide validation, fixes, type-aware analysis, cache policy, worker control, and inline directives remain Oxlint-owned.
diff --git a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
index dae8c7451b..8e3d69cdce 100644
--- a/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
+++ b/.agents/notes/implemented/process/2026-07-29-oxlint-linter.zh.md
@@ -12,25 +12,25 @@ Status: implemented
 
 ## 决策
 
-根目录的 [`.oxlintrc.json`](../../../../.oxlintrc.json) 是仓库类型感知 lint 配置的权威来源。不加载项目的 [`.oxlintrc.staged.json`](../../../../.oxlintrc.staged.json) 配置继承其源码规则，但会为有界的 pre-commit 路径禁用类型分析。`lint` 包脚本、门禁调度器、CI 和 lefthook 通过 [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts) 调用 Oxlint；`lint:fix` 和 lefthook 会先调用仅用于格式化的 [`eslint.format.config.mjs`](../../../../eslint.format.config.mjs)。直接的 `eslint` 和 `@typescript-eslint/parser` 开发依赖仅用于这次不加载项目的格式化流程；其精确版本锁定经过测试的解析器与修复器配对，该配置不包含正确性规则或类型感知规则。
+根目录的 [`.oxlintrc.json`](../../../../.oxlintrc.json) 是仓库类型感知 lint 配置的权威来源。不加载项目的 [`.oxlintrc.staged.json`](../../../../.oxlintrc.staged.json) 配置继承其源码规则，为有界的 pre-commit 路径禁用类型分析，并重新纳入类型感知后端无法分析但需保留的 TypeGraph fixture（测试前置数据）。`lint` 与 `lint:fix` 包脚本、门禁调度器、CI 和 lefthook 通过 [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts) 调用 Oxlint；[仅使用 Oxlint 的修复工作流](2026-08-09-oxlint-only-fix-workflow.md)负责多轮插件修复，并取代单独的格式化回退路径。
 
 `options.typeAware` 启用 `oxlint-tsgolint`。其后端按文件发现 TypeScript 项目：包源码使用各自的包项目，host 测试、示例和网站使用 `tsconfig.host.json`，client 测试及 `scripts/client-bundle-purity.spec.ts` 使用 `tsconfig.client.json`。不含程序的根解决方案绝不会被扁平化。Oxlint 的 `--tsconfig` 覆盖项会影响导入解析，但类型感知 lint 会忽略它，因此本仓库不设置该选项。该配置显式载入迁移后的严格类型检查规则和仓库覆盖配置，而不启用内容可能发生变化的 Oxlint 宽泛类别。`typescript/no-unnecessary-condition` 仍从 Oxlint 的 nursery 规则集中启用，因为它在迁移前就是仓库强制执行的规则。
 
-Oxlint 的 JavaScript 插件兼容层运行 `@stylistic/eslint-plugin` 和 `eslint-plugin-sonarjs`，从而继续强制执行现有的格式和文件内重复逻辑规则。兼容层会报告 `@stylistic` 违规，但不会执行其修复器，因此仅用于格式化的 ESLint 流程只负责相应的自动修复；一项可执行检查确保这些可修复规则定义保持一致，而 `max-len` 仅用于验证。自有源码中的抑制指令使用 `oxlint-*` 指令和 `typescript/*` 命名空间，未使用的指令仍作为警告报告；vendor 源码保留其上游指令，因为 Oxlint 会排除 `vendor/**`。
+Oxlint 的 JavaScript 插件兼容层运行 `@stylistic/eslint-plugin` 和 `eslint-plugin-sonarjs`，从而继续强制执行现有的格式和文件内重复逻辑规则。兼容层会报告 `@stylistic` 违规并执行其安全修复；`max-len` 仍仅用于验证。自有源码中的抑制指令使用 `oxlint-*` 指令和 `typescript/*` 命名空间，未使用的指令仍作为警告报告；vendor 源码保留其上游指令，因为 Oxlint 会排除 `vendor/**`。
 
-CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行器将同一上限传给 Oxlint 的 `--threads` 选项和类型感知后端的 `GOMAXPROCS` 环境变量；普通本地运行对两者均采用默认值。Pre-commit 应用仅用于格式化的 ESLint 修复，运行不加载项目的 Oxlint 验证并应用原生安全修复，接受仅含已忽略文件的文件选择，并通过 lefthook 重新暂存结果。公共 `lint` 和 CI 会先准备生成的声明，并保留完整的类型感知规则。
+CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行器将同一上限传给 Oxlint 的 `--threads` 选项和类型感知后端的 `GOMAXPROCS` 环境变量；普通本地运行对两者均采用默认值。Pre-commit 运行不加载项目的 Oxlint 验证，应用带一次有界重试的安全修复，接受仅含已忽略文件的文件选择，并通过 lefthook 重新暂存结果。公共 `lint` 和 CI 会先准备生成的声明，并保留完整的类型感知规则。
 
 ## 验证
 
 解决两处分析器差异后，迁移后的配置报告与迁移前一致的自有源码无问题基线：移除了一项冗余测试断言，而 `tsc` 要求的一处结构性类型转换使用了窄范围的 Oxlint 抑制指令。以已删除 ESLint 配置的精确 blob 为基准进行的一次性审核在完成规则名映射后确认：源码为 88 项对 88 项，示例为 87 项对 87 项，测试为 83 项对 83 项。已提交的指纹锁定这些经审核的 Oxlint 规则配置及完整的覆盖结构；它既不执行已删除的配置，也不纳入后续的上游预设变更。对 `typescript-eslint@8.61.0` 的评估还确认，`strictTypeChecked` 并未启用 `@typescript-eslint/no-empty-function`；已删除、仅用于测试的 `off` 条目不起作用。
 
-可执行约定测试要求包、host 和 client 项目产生类型感知诊断，断言 client 专用脚本所用的项目，拒绝未匹配的回退分析，并检验 Stylistic、SonarJS 和 nursery 兼容路径。它们还锁定暂存配置不加载项目的继承行为、未使用抑制指令的报告行为、仅选择已忽略暂存文件的情况、格式化器与验证器之间的规则一致性，以及最终格式化后的字节。运行器测试锁定两项工作线程控制，类型检查则确认迁移引发的源码改动没有破坏 TypeScript 程序。
+可执行约定测试要求包、host 和 client 项目产生类型感知诊断，断言 client 专用脚本所用的项目，拒绝未匹配的回退分析，并检验 Stylistic、SonarJS 和 nursery 兼容路径。它们还锁定暂存配置不加载项目的继承行为与 TypeGraph fixture 覆盖、未使用抑制指令的报告行为、仅选择已忽略暂存文件的情况、完整的 Stylistic 规则集，以及收敛后最终格式化的字节。运行器测试锁定两项工作线程控制，类型检查则确认迁移引发的源码改动没有破坏 TypeScript 程序。
 
 ## 考虑过的替代方案
 
-**在全仓库范围内同时运行两个 linter。** 所有正确性规则均可通过 Oxlint 原生规则、nursery 规则或 JavaScript 插件兼容层获得。在全仓库范围启用 ESLint 回退会保留较慢的项目服务初始化和两套正确性配置，却不会增加任何检查；保留的 ESLint 流程被刻意限制为不加载项目的暂存文件格式化。
+**在全仓库范围内同时运行两个 linter。** 所有正确性规则均可通过 Oxlint 原生规则、nursery 规则或 JavaScript 插件兼容层获得。在全仓库范围启用 ESLint 回退会保留较慢的项目服务初始化和两套正确性配置，却不会增加任何检查。
 
-**依赖兼容层修复。** 兼容层会报告既有的 `@stylistic` 规则，但在 Oxlint 的两种修复模式下都不会应用这些规则的修复。保留窄范围的暂存文件格式化器，可以在不将 ESLint 扩张回仓库 linter 的情况下维持贡献者约定。
+**使用单独的格式化器。** 迁移保留了窄范围的 ESLint 流程，因为当时认为兼容层无法执行修复。锁定版本的工具链证明能够执行相同修复后，[仅使用 Oxlint 的修复工作流](2026-08-09-oxlint-only-fix-workflow.md)以一次有界重试取代了该部分决策。
 
 **移除尚无原生实现的 @stylistic 或 SonarJS 规则。** 这会移除依赖，但也会削弱机械质量约定。兼容层会保留这些规则，直到能够通过单独决策评估原生替代规则。
 
@@ -42,4 +42,4 @@ CI 不恢复或保存 lint 结果缓存。`DSH_OXLINT_THREADS` 使共享运行
 
 类型感知诊断现在来自通过 `oxlint-tsgolint` 捆绑的 TypeScript Go 分析器，因此即使 `tsc` 接受同一程序，边界场景下的类型推断也可能与 typescript-eslint 不同。lint 与类型检查仍是两项相互独立的必要证据。
 
-JavaScript 插件兼容 API、暂存配置和暂存文件格式化器是需要维护的额外边界。每次提交把类型感知诊断留给公共 lint 和 CI，在 Oxlint 之前启动一次不加载项目的 ESLint，并避免依赖生成的声明。根目录开发依赖图仍保留 ESLint 和 TypeScript 解析器。全仓库验证、类型感知分析、缓存政策、工作线程控制和内联指令仍由 Oxlint 负责。
+JavaScript 插件兼容 API 和暂存配置是需要维护的额外边界。每次提交把类型感知诊断留给公共 lint 和 CI，并避免依赖生成的声明。全仓库验证、修复、类型感知分析、缓存政策、工作线程控制和内联指令仍由 Oxlint 负责。
diff --git a/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.i18n.yaml
new file mode 100644
index 0000000000..824c74bd7f
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.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/process/2026-08-09-oxlint-only-fix-workflow.md
+2026-08-09-oxlint-only-fix-workflow.md: bc38812db101499d980c38cb6c1dc5cba32e5cd6
+2026-08-09-oxlint-only-fix-workflow.zh.md: 91674837dd7c0c2da8d5b6214082dc7a2f2f0fac
diff --git a/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.md b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.md
new file mode 100644
index 0000000000..bc38812db1
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.md
@@ -0,0 +1,37 @@
+# Agent Note: Oxlint-only fix workflow
+
+Status: implemented
+
+English | [中文](2026-08-09-oxlint-only-fix-workflow.zh.md)
+
+## Problem
+
+The [repository linter migration](2026-07-29-oxlint-linter.md) retained a formatting-only ESLint invocation because Oxlint's JavaScript-plugin bridge was treated as validation-only. The pinned Oxlint toolchain executes the safe fixers supplied by `@stylistic/eslint-plugin`, so the separate formatter duplicates a configuration boundary, command startup, and direct `eslint` plus `@typescript-eslint/parser` dependencies.
+
+A single Oxlint invocation is not an equivalent replacement. Overlapping plugin fixes can apply one change while leaving a newly exposed diagnostic; the repository's `semi` and `object-curly-spacing` fixture requires a second pass before it is clean. The workflow must retry that case without printing obsolete first-pass diagnostics.
+
+## Decision
+
+All repository lint and fix workflows invoke Oxlint through [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts). Normal validation remains one process with inherited output. An invocation containing `--fix`, `--fix-suggestions`, or `--fix-dangerously` captures the first Oxlint result; success emits its stdout and stderr on their original channels, while a completed non-zero run discards its potentially obsolete diagnostics and runs the same command once more with inherited output. The runner re-raises a child signal instead of retrying or converting it to an exit code, and the second process completion is final.
+
+The `lint:fix` package script and staged lefthook job use that runner directly. The type-aware root profile still ignores preserved TypeGraph fixture shapes that `oxlint-tsgolint` cannot analyze; the project-free staged profile re-includes that directory, carries its intentional `any` and quote exceptions, and applies its style fixes before the full type-aware fix pass. The formatting-only ESLint configuration and the direct `eslint` and `@typescript-eslint/parser` development dependencies are absent. `@stylistic/eslint-plugin` and `eslint-plugin-sonarjs` remain Oxlint JavaScript plugins because they preserve enforced rules; pnpm still installs ESLint as their declared peer, but no repository configuration or workflow invokes it.
+
+## Verification
+
+The executable lint contract drives a deliberately overlapping style violation through the repository runner and requires a successful exit plus exact final bytes. The same contract pins the complete Stylistic rule set, project-free TypeGraph fixture coverage, the package scripts, the staged hook command, the deleted formatter configuration, and the absence of direct ESLint parser and runner dependencies. Existing executable probes continue to cover the Stylistic and SonarJS compatibility plugins, project-free staged validation, and type-aware project discovery.
+
+## Alternatives considered
+
+**Keep the formatting-only ESLint pass.** This preserves ESLint's built-in multipass behavior but retains a second runner, a duplicated formatting config, and direct dependencies after Oxlint can execute the same plugin fixes.
+
+**Run Oxlint once with `--fix`.** This is simpler, but overlapping safe fixes can leave the command partially formatted and non-zero even though another identical pass completes it.
+
+**Adopt Oxfmt.** A formatter migration changes the repository's output contract and would create an unrelated formatting diff. It remains a separate decision from removing the redundant ESLint execution path.
+
+**Remove the JavaScript compatibility plugins.** This would eliminate their ESLint peer graph but would also drop the enforced Stylistic and SonarJS rules. Dependency-tree purity does not justify weakening the quality contract.
+
+## Consequences
+
+Contributors, package scripts, hooks, and CI have one lint runner and one rule configuration. The staged profile repeats the root ignore list so it can re-include formatter-only fixtures without exposing vendor or generated files. A completed non-zero fix invocation always pays for one retry, including a stable unfixable error. The first pass buffers each output stream up to 64 MiB so obsolete diagnostics are not printed when the retry succeeds; process creation and capture failures, including that limit being exceeded, surface immediately without a retry.
+
+The dependency lock can still contain ESLint through plugin peer resolution. Removing that transitive package requires native replacements or a formatter decision that also replaces the compatibility plugins; it is not part of the workflow simplification.
diff --git a/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.zh.md b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.zh.md
new file mode 100644
index 0000000000..91674837dd
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-oxlint-only-fix-workflow.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 仅使用 Oxlint 的修复工作流
+
+Status: implemented
+
+[English](2026-08-09-oxlint-only-fix-workflow.md) | 中文
+
+## 问题
+
+[仓库 linter 迁移](2026-07-29-oxlint-linter.md)保留了一次仅用于格式化的 ESLint 调用，因为当时认为 Oxlint 的 JavaScript 插件桥接层只能用于校验。固定版本的 Oxlint 工具链能够执行 `@stylistic/eslint-plugin` 提供的安全修复，因此单独的格式化器重复引入了配置边界、命令启动过程，以及对 `eslint` 和 `@typescript-eslint/parser` 的直接依赖。
+
+单次调用 Oxlint 并不能实现等价替代。相互重叠的插件修复可能先应用一项变更，却留下由此新暴露的诊断；仓库中包含 `semi` 和 `object-curly-spacing` 违规的 fixture（测试前置数据）需要运行第二轮才能完全修复。工作流必须重试这种情况，同时不得打印第一轮中已经失效的诊断。
+
+## 决策
+
+仓库的所有 lint 与修复工作流都通过 [`scripts/run-oxlint.ts`](../../../../scripts/run-oxlint.ts) 调用 Oxlint。普通校验仍由单个进程执行，并直接继承输出。包含 `--fix`、`--fix-suggestions` 或 `--fix-dangerously` 的调用会捕获第一次 Oxlint 的运行结果；如果成功，就通过原有通道输出其 stdout 和 stderr；如果进程正常结束但状态非零，则丢弃其中可能已经失效的诊断，随后以继承输出的方式再运行一次相同命令。子进程被信号终止时，运行器会重新触发该信号，而不会重试或将其转换为退出码；第二个进程的结束结果作为最终结果。
+
+`lint:fix` 包脚本和处理暂存文件的 lefthook 作业直接使用该运行器。类型感知的根配置仍会忽略 `oxlint-tsgolint` 无法分析、需要保留原始形态的 TypeGraph fixture；不加载项目的暂存配置会重新纳入该目录，保留其中有意设置的 `any` 与引号规则例外，并在完整的类型感知修复轮次之前应用其样式修复。仓库中不存在仅用于格式化的 ESLint 配置，也不直接依赖 `eslint` 和 `@typescript-eslint/parser` 这两个开发依赖。`@stylistic/eslint-plugin` 和 `eslint-plugin-sonarjs` 仍作为 Oxlint 的 JavaScript 插件保留，因为它们承载了已强制执行的规则；pnpm 仍会将 ESLint 作为这些插件声明的对等依赖（peer dependency）进行安装，但仓库中的配置和工作流均不会调用它。
+
+## 验证
+
+可执行 lint 约定将一项特意构造、修复相互重叠的样式违规交给仓库运行器处理，并要求运行器成功退出且最终字节完全一致。同一约定还会固定完整的 Stylistic 规则集、不加载项目时对 TypeGraph fixture 的覆盖、包脚本、暂存文件钩子命令、已删除的格式化器配置，以及 ESLint 解析器和运行器不存在直接依赖这一事实。现有的可执行探针继续覆盖 Stylistic 和 SonarJS 兼容插件、不加载项目的暂存文件校验，以及类型感知的项目发现。
+
+## 考虑过的替代方案
+
+**保留仅用于格式化的 ESLint 轮次。** 这会保留 ESLint 内置的多轮修复行为，但在 Oxlint 已能执行相同插件修复的情况下，仍需维护第二个运行器、重复的格式化配置和直接依赖。
+
+**仅运行一次带 `--fix` 的 Oxlint。** 这样更简单，但相互重叠的安全修复可能使命令只完成部分格式化并以非零状态退出，即使再次运行同一命令就能完成修复。
+
+**采用 Oxfmt。** 迁移格式化器会改变仓库的输出约定，并产生无关的格式化 diff。它与移除冗余 ESLint 执行路径是两项独立决策。
+
+**移除 JavaScript 兼容插件。** 这会消除这些插件引入的 ESLint 对等依赖图，但也会移除强制执行的 Stylistic 和 SonarJS 规则。追求依赖树纯净不能成为削弱质量约定的理由。
+
+## 结果
+
+贡献者、包脚本、钩子和 CI 统一使用一个 lint 运行器和一份规则配置。暂存配置会重复根配置的忽略清单，以便重新纳入仅用于格式化的 fixture，同时避免将 vendor 或生成文件纳入检查。修复进程正常结束但状态非零时，始终会额外执行一次重试；稳定存在且无法修复的错误也不例外。第一轮的每条输出流最多缓冲 64 MiB，因此重试成功时不会打印已经失效的诊断；进程创建或输出捕获失败（包括超出该上限）时会立即报告错误，不会重试。
+
+依赖锁中仍可能因插件的对等依赖解析而包含 ESLint。要移除这个传递依赖，需要使用原生替代方案，或另行决定采用能够同时取代兼容插件的格式化器；这不属于本次工作流简化的范围。
diff --git a/.oxlintrc.json b/.oxlintrc.json
index ed470ecd70..70f53fd4cd 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -298,6 +298,24 @@
       "jsPlugins": [
         "@stylistic/eslint-plugin"
       ]
+    },
+    {
+      // The project-free staged profile re-includes this syntax-coverage fixture.
+      "files": [
+        "packages/typert/generator/tests/fixtures/type-model/**/*.{ts,tsx}"
+      ],
+      "rules": {
+        "typescript/no-explicit-any": "off"
+      }
+    },
+    {
+      // TypeGraph coverage must retain source-authored syntax that the normal quote rule forbids.
+      "files": [
+        "packages/typert/generator/tests/fixtures/type-model/packages/host/src/models.ts"
+      ],
+      "rules": {
+        "@stylistic/quotes": "off"
+      }
     }
   ]
 }
diff --git a/.oxlintrc.staged.json b/.oxlintrc.staged.json
index db79a933fa..ca693f67ae 100644
--- a/.oxlintrc.staged.json
+++ b/.oxlintrc.staged.json
@@ -3,5 +3,20 @@
   "extends": ["./.oxlintrc.json"],
   "options": {
     "typeAware": false
-  }
+  },
+  "ignorePatterns": [
+    "**/lib/**",
+    "**/node_modules/**",
+    "**/.sessions/**",
+    ".claude/**",
+    "**/.doc-typecheck-*/**",
+    "**/.node-next-types-*/**",
+    "website/.generated/**",
+    "vendor/**",
+    "native/**",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.config.ts",
+    "packages/client/tsdown.client.ts"
+  ]
 }
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 48f04c9799..55c753b45d 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -139,7 +139,6 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`@types/spdx-expression-parse`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/turndown`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/ws`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
-| [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint) | MIT |
 | [`@vitejs/plugin-react`](https://github.com/vitejs/vite-plugin-react) | MIT |
 | [`@vitest/coverage-v8`](https://github.com/vitest-dev/vitest) | MIT |
 | [`@yarnpkg/cli-dist`](https://github.com/yarnpkg/berry) | BSD-2-Clause |
@@ -148,7 +147,6 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`dayjs`](https://github.com/iamkun/dayjs) | MIT |
 | [`debug`](https://github.com/debug-js/debug) | MIT |
 | [`esbuild`](https://github.com/evanw/esbuild) | MIT |
-| [`eslint`](https://github.com/eslint/eslint) | MIT |
 | [`eslint-plugin-sonarjs`](https://github.com/SonarSource/SonarJS) | LGPL-3.0-only |
 | [`execa`](https://github.com/sindresorhus/execa) | MIT |
 | [`fast-check`](https://github.com/dubzzz/fast-check) | MIT |
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 5e2895c8ba..84cff8fa96 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: f7084403b30e8a6d12c4ef2b886f8fb61ed39b26
-development.zh.md: 56df93beddbb128cac8e0bcf2adaa9dcfb72c751
+development.md: 8b6c148d87fdd6288695b0029b9dfcc0139d2144
+development.zh.md: 55ca013cc0dd901500e340a7447057de27665f61
diff --git a/docs/development.md b/docs/development.md
index f7084403b3..8b6c148d87 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -106,7 +106,7 @@ The installer probes the exact Node/tsx driver entrypoint before publishing its
 
 lefthook is configured in `lefthook.yml` as a fast local checkpoint:
 
-- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
+- `pre-commit` verifies staged pairing records against the staged owner blobs, validates staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint fixes with one bounded retry, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.
 - `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.
 - `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 56df93bedd..55ca013cc0 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -106,7 +106,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 lefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：
 
-- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
+- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件，并通过一次有界重试应用 Oxlint 修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；
 - `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；
 - `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。
 
diff --git a/eslint.format.config.mjs b/eslint.format.config.mjs
deleted file mode 100644
index 5681688e81..0000000000
--- a/eslint.format.config.mjs
+++ /dev/null
@@ -1,59 +0,0 @@
-import stylistic from '@stylistic/eslint-plugin'
-import parser from '@typescript-eslint/parser'
-
-// Oxlint's JavaScript-plugin compatibility layer reports these rules but does
-// not execute their fixers. Keep this config formatting-only: Oxlint remains
-// the authoritative repository linter after this pass applies safe fixes.
-export default [
-  {
-    ignores: [
-      '**/lib/**',
-      '**/node_modules/**',
-      '**/.sessions/**',
-      '.claude/**',
-      '**/.doc-typecheck-*/**',
-      '**/.node-next-types-*/**',
-      // Do not mirror Oxlint's contract-fixture ignore: those files must reach this formatter.
-      'website/.generated/**',
-      'vendor/**',
-      'native/**',
-      '**/*.js',
-      '**/*.mjs',
-      '**/*.config.ts',
-      'packages/client/tsdown.client.ts',
-    ],
-  },
-  {
-    files: ['**/*.{ts,tsx,mts,cts}'],
-    languageOptions: {
-      parser,
-      parserOptions: {
-        sourceType: 'module',
-      },
-    },
-    plugins: {
-      '@stylistic': stylistic,
-    },
-    rules: {
-      '@stylistic/indent': ['error', 2],
-      '@stylistic/semi': ['error', 'never'],
-      '@stylistic/quotes': ['error', 'single', { avoidEscape: true }],
-      '@stylistic/comma-dangle': ['error', 'always-multiline'],
-      '@stylistic/eol-last': ['error', 'always'],
-      '@stylistic/no-trailing-spaces': 'error',
-      '@stylistic/object-curly-spacing': ['error', 'always'],
-      '@stylistic/arrow-parens': ['error', 'as-needed', { requireForBlockBody: true }],
-      '@stylistic/member-delimiter-style': ['error', {
-        multiline: { delimiter: 'none' },
-        singleline: { delimiter: 'semi', requireLast: false },
-      }],
-    },
-  },
-  {
-    // TypeGraph coverage must retain source-authored syntax that the normal quote rule forbids.
-    files: ['packages/typert/generator/tests/fixtures/type-model/packages/host/src/models.ts'],
-    rules: {
-      '@stylistic/quotes': 'off',
-    },
-  },
-]
diff --git a/lefthook.yml b/lefthook.yml
index 0e78d16252..0ea7f4e537 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -8,13 +8,6 @@ pre-commit:
       glob: '*.i18n.yaml'
       run: node_modules/.bin/tsx scripts/verify-translation-pairing.ts --cached {staged_files}
 
-    - name: format (staged)
-      glob: '*.{ts,tsx,mts,cts,mjs}'
-      exclude:
-        - 'vendor/*/src/**'
-      run: node_modules/.bin/eslint --config eslint.format.config.mjs --fix --no-warn-ignored {staged_files}
-      stage_fixed: true
-
     - name: lint (staged)
       glob: '*.{ts,tsx,mts,cts,mjs}'
       exclude:
diff --git a/package.json b/package.json
index 864814ffe6..d417354739 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,7 @@
     "lint": "npm run build:lib:host && npm run lint:contracts-ready",
     "lint:contracts-ready": "tsx scripts/run-oxlint.ts .",
     "lint:fix": "npm run build:lib:host && npm run lint:fix:contracts-ready",
-    "lint:fix:contracts-ready": "eslint --config eslint.format.config.mjs --fix . && tsx scripts/run-oxlint.ts . --fix",
+    "lint:fix:contracts-ready": "tsx scripts/run-oxlint.ts --config .oxlintrc.staged.json packages/typert/generator/tests/fixtures/type-model --fix && tsx scripts/run-oxlint.ts . --fix",
     "duplication": "jscpd --config .jscpd.json packages scripts",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
@@ -139,10 +139,8 @@
     "@types/mdast": "^4.0.4",
     "@types/node": "^22.20.0",
     "@types/spdx-expression-parse": "^4.0.0",
-    "@typescript-eslint/parser": "8.61.0",
     "@vitest/coverage-v8": "^4.1.8",
     "@yarnpkg/cli-dist": "4.17.1",
-    "eslint": "10.5.0",
     "eslint-plugin-sonarjs": "^4.1.0",
     "execa": "^10.0.0",
     "fast-check": "^4.8.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bd2eab469c..da3703e5ff 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -41,18 +41,12 @@ importers:
       '@types/spdx-expression-parse':
         specifier: ^4.0.0
         version: 4.0.0
-      '@typescript-eslint/parser':
-        specifier: 8.61.0
-        version: 8.61.0(eslint@10.5.0(jiti@2.7.0))(typescript@6.0.3)
       '@vitest/coverage-v8':
         specifier: ^4.1.8
         version: 4.1.8(vitest@4.1.8)
       '@yarnpkg/cli-dist':
         specifier: 4.17.1
         version: 4.17.1
-      eslint:
-        specifier: 10.5.0
-        version: 10.5.0(jiti@2.7.0)
       eslint-plugin-sonarjs:
         specifier: ^4.1.0
         version: 4.1.0(eslint@10.5.0(jiti@2.7.0))
@@ -9962,53 +9956,10 @@ packages:
   '@types/ws@8.18.1':
     resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
 
-  '@typescript-eslint/parser@8.61.0':
-    resolution: {integrity: sha512-5B7PfA2e1NQGCnDHd/0lW7W3gvp3d59Ryw54FYO8Uswxo9f6ikw3AZV+Xj/TvpImmpsiYyUqAfhC6kJID1jF6w==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-    peerDependencies:
-      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
-      typescript: '>=4.8.4 <6.1.0'
-
-  '@typescript-eslint/project-service@8.61.0':
-    resolution: {integrity: sha512-DV42F7MLJO6Rax7SK1yg43tcnEfGUrurSpSxKuVX+a3RCTzBlH3fuxprrOJXKCJGAaw82xXocikJ0uQaqwXgGA==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-    peerDependencies:
-      typescript: '>=4.8.4 <6.1.0'
-
-  '@typescript-eslint/scope-manager@8.61.0':
-    resolution: {integrity: sha512-IWdXFHFSb6mlC3HPc7QsLDm5zYEbUla6trDEHf32D3/dnuUyXd87plScSNXSbm0/RxMvObpI17sv/EDTGrGZkA==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-
-  '@typescript-eslint/tsconfig-utils@8.61.0':
-    resolution: {integrity: sha512-O5Amvdv9ztMpxpf+vmFULGG78IE6Qwdr3bCGvqwG4nwc9H2qXkOYJJnRbRHyMkQTjv1d03olqwwwzHLMqpFePQ==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-    peerDependencies:
-      typescript: '>=4.8.4 <6.1.0'
-
-  '@typescript-eslint/tsconfig-utils@8.65.0':
-    resolution: {integrity: sha512-j6GzGqCiRdA7Qhur2VVmKZAkBLfnHFQfx4TaJGL9RMveZqCo48jSHHO0DTgizEnGhtWnqmbtCUSrqSkdiY/0Hg==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-    peerDependencies:
-      typescript: '>=4.8.4 <6.1.0'
-
   '@typescript-eslint/types@8.61.0':
     resolution: {integrity: sha512-9QTQpZ5Iin4CdIodfbDQFSeiSJKidgYJYug1P9CC2xWgUTvlmixViqDZNciMjwLBZyJnG4tGmPl97rVAFb1AJg==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
 
-  '@typescript-eslint/types@8.65.0':
-    resolution: {integrity: sha512-JSSwWNy+H0E/01jJEM+hrX6N0OFDzFzeIhHFSAS01tlVaevpG8cFyYRPhS5yjGOvBUx3sqQHVMjCL1CAZZMxBg==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-
-  '@typescript-eslint/typescript-estree@8.61.0':
-    resolution: {integrity: sha512-42zatd5qSvvcV1JdDBCLxYRznvP4eIHpPoZXdkPFnAmanA4FuZ5dibSnCBggY8hQnqajPpoGjXFdZ7fIJKQnlA==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-    peerDependencies:
-      typescript: '>=4.8.4 <6.1.0'
-
-  '@typescript-eslint/visitor-keys@8.61.0':
-    resolution: {integrity: sha512-QVLZu3ZPQEE+HICQyAMZ2yLQhxf0meY/wx6Hx14YcTNj13JB3qHlX3lJ02L3fLGHgERRH71kvYDwiXIguT3AjQ==}
-    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
-
   '@ungap/structured-clone@1.3.3':
     resolution: {integrity: sha512-60YRaenCQcVjYEKOcG824+DRGGIQ3VKErcBoAEDJZz5bKIs2ZG+X/H9Nk+Q6EVkwJk5QNApxbrc5QtBSwtrXAg==}
 
@@ -15039,64 +14990,8 @@ snapshots:
     dependencies:
       '@types/node': 22.20.0
 
-  '@typescript-eslint/parser@8.61.0(eslint@10.5.0(jiti@2.7.0))(typescript@6.0.3)':
-    dependencies:
-      '@typescript-eslint/scope-manager': 8.61.0
-      '@typescript-eslint/types': 8.61.0
-      '@typescript-eslint/typescript-estree': 8.61.0(typescript@6.0.3)
-      '@typescript-eslint/visitor-keys': 8.61.0
-      debug: 4.4.3
-      eslint: 10.5.0(jiti@2.7.0)
-      typescript: 6.0.3
-    transitivePeerDependencies:
-      - supports-color
-
-  '@typescript-eslint/project-service@8.61.0(typescript@6.0.3)':
-    dependencies:
-      '@typescript-eslint/tsconfig-utils': 8.65.0(typescript@6.0.3)
-      '@typescript-eslint/types': 8.65.0
-      debug: 4.4.3
-      typescript: 6.0.3
-    transitivePeerDependencies:
-      - supports-color
-
-  '@typescript-eslint/scope-manager@8.61.0':
-    dependencies:
-      '@typescript-eslint/types': 8.61.0
-      '@typescript-eslint/visitor-keys': 8.61.0
-
-  '@typescript-eslint/tsconfig-utils@8.61.0(typescript@6.0.3)':
-    dependencies:
-      typescript: 6.0.3
-
-  '@typescript-eslint/tsconfig-utils@8.65.0(typescript@6.0.3)':
-    dependencies:
-      typescript: 6.0.3
-
   '@typescript-eslint/types@8.61.0': {}
 
-  '@typescript-eslint/types@8.65.0': {}
-
-  '@typescript-eslint/typescript-estree@8.61.0(typescript@6.0.3)':
-    dependencies:
-      '@typescript-eslint/project-service': 8.61.0(typescript@6.0.3)
-      '@typescript-eslint/tsconfig-utils': 8.61.0(typescript@6.0.3)
-      '@typescript-eslint/types': 8.61.0
-      '@typescript-eslint/visitor-keys': 8.61.0
-      debug: 4.4.3
-      minimatch: 10.2.5
-      semver: 7.8.4
-      tinyglobby: 0.2.17
-      ts-api-utils: 2.5.0(typescript@6.0.3)
-      typescript: 6.0.3
-    transitivePeerDependencies:
-      - supports-color
-
-  '@typescript-eslint/visitor-keys@8.61.0':
-    dependencies:
-      '@typescript-eslint/types': 8.61.0
-      eslint-visitor-keys: 5.0.1
-
   '@ungap/structured-clone@1.3.3': {}
 
   '@upsetjs/venn.js@2.0.0':
diff --git a/scripts/oxlint-contract.spec.ts b/scripts/oxlint-contract.spec.ts
index 7592780881..ccb226fb41 100644
--- a/scripts/oxlint-contract.spec.ts
+++ b/scripts/oxlint-contract.spec.ts
@@ -1,14 +1,15 @@
 import { spawnSync } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
+import { fileURLToPath } from 'node:url'
 import { flattenDiagnosticMessageText, parseConfigFileTextToJson } from 'typescript'
 import { describe, expect, it } from 'vitest'
 
 const repositoryRoot = fileURLToPath(new URL('..', import.meta.url))
-const eslintCli = fileURLToPath(new URL('../node_modules/eslint/bin/eslint.js', import.meta.url))
 const oxlintCli = fileURLToPath(new URL('../node_modules/oxlint/bin/oxlint', import.meta.url))
+const tsxCli = fileURLToPath(new URL('../node_modules/tsx/dist/cli.mjs', import.meta.url))
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
@@ -18,11 +19,11 @@ function isUnknownArray(value: unknown): value is unknown[] {
   return Array.isArray(value)
 }
 
-function runStagedFormatter(paths: readonly string[]) {
-  return spawnSync(process.execPath, [eslintCli, '--config', 'eslint.format.config.mjs', '--fix', '--no-warn-ignored', ...paths], {
+function runRepositoryOxlint(args: readonly string[], env: NodeJS.ProcessEnv = {}) {
+  return spawnSync(process.execPath, [tsxCli, 'scripts/run-oxlint.ts', ...args], {
     cwd: repositoryRoot,
     encoding: 'utf8',
-    env: { ...process.env, NO_COLOR: '1' },
+    env: { ...process.env, NO_COLOR: '1', ...env },
   })
 }
 
@@ -150,7 +151,7 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
     }
   }, 20_000)
 
-  it('keeps formatter rules aligned with Oxlint validation', async () => {
+  it('keeps the complete stylistic contract in Oxlint', async () => {
     const oxlintPath = join(repositoryRoot, '.oxlintrc.json')
     const result = parseConfigFileTextToJson(oxlintPath, await readFile(oxlintPath, 'utf8'))
     if (result.error !== undefined) {
@@ -160,27 +161,67 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
     if (!isRecord(parsed) || !isUnknownArray(parsed.overrides)) {
       throw new Error('.oxlintrc.json must contain an overrides array')
     }
+    expect(parsed.ignorePatterns).toEqual(expect.arrayContaining([
+      'packages/typert/generator/tests/fixtures/type-model/**',
+    ]))
     const stylisticOverride = parsed.overrides.find((value: unknown) =>
       isRecord(value) && isRecord(value.rules) && '@stylistic/max-len' in value.rules)
     if (!isRecord(stylisticOverride) || !isRecord(stylisticOverride.rules)) {
       throw new Error('.oxlintrc.json must contain the @stylistic validator override')
     }
-    const validatorRules = { ...stylisticOverride.rules }
-    const maxLen = validatorRules['@stylistic/max-len']
-    delete validatorRules['@stylistic/max-len']
+    expect(stylisticOverride.rules).toMatchObject({
+      '@stylistic/indent': ['error', 2],
+      '@stylistic/semi': ['error', 'never'],
+      '@stylistic/quotes': ['error', 'single', { avoidEscape: true }],
+      '@stylistic/comma-dangle': ['error', 'always-multiline'],
+      '@stylistic/eol-last': ['error', 'always'],
+      '@stylistic/no-trailing-spaces': 'error',
+      '@stylistic/object-curly-spacing': ['error', 'always'],
+      '@stylistic/arrow-parens': ['error', 'as-needed', { requireForBlockBody: true }],
+      '@stylistic/member-delimiter-style': ['error', {
+        multiline: { delimiter: 'none' },
+        singleline: { delimiter: 'semi', requireLast: false },
+      }],
+      '@stylistic/max-len': ['error', { code: 140, ignoreUrls: true, ignoreStrings: true, ignoreTemplateLiterals: true }],
+    })
+    const typeGraphOverride = parsed.overrides.find((value: unknown) =>
+      isRecord(value)
+      && isUnknownArray(value.files)
+      && value.files.includes('packages/typert/generator/tests/fixtures/type-model/packages/host/src/models.ts'))
+    expect(typeGraphOverride).toMatchObject({
+      rules: { '@stylistic/quotes': 'off' },
+    })
+  })
 
-    const formatterUrl = pathToFileURL(join(repositoryRoot, 'eslint.format.config.mjs')).href
-    const formatterModule = await import(formatterUrl) as unknown
-    if (!isRecord(formatterModule) || !isUnknownArray(formatterModule.default)) {
-      throw new Error('eslint.format.config.mjs must default-export a config array')
-    }
-    const formatterOverride = formatterModule.default.find((value: unknown) => isRecord(value) && isRecord(value.rules))
-    if (!isRecord(formatterOverride) || !isRecord(formatterOverride.rules)) {
-      throw new Error('eslint.format.config.mjs must contain a rules object')
+  it('checks preserved TypeGraph syntax without type-aware analysis', () => {
+    const result = runOxlint([
+      '--config',
+      '.oxlintrc.staged.json',
+      'packages/typert/generator/tests/fixtures/type-model',
+    ])
+
+    expect(result.error).toBeUndefined()
+    expect(result.status, normalizedOutput(result)).toBe(0)
+  })
+
+  it('keeps repository lint workflows Oxlint-only', async () => {
+    const packageJson = JSON.parse(await readFile(join(repositoryRoot, 'package.json'), 'utf8')) as unknown
+    if (!isRecord(packageJson) || !isRecord(packageJson.scripts) || !isRecord(packageJson.devDependencies)) {
+      throw new Error('package.json must contain scripts and devDependencies objects')
     }
 
-    expect(validatorRules).toStrictEqual(formatterOverride.rules)
-    expect(maxLen).toStrictEqual(['error', { code: 140, ignoreUrls: true, ignoreStrings: true, ignoreTemplateLiterals: true }])
+    expect(packageJson.scripts['lint:contracts-ready']).toBe('tsx scripts/run-oxlint.ts .')
+    expect(packageJson.scripts['lint:fix:contracts-ready']).toBe(
+      'tsx scripts/run-oxlint.ts --config .oxlintrc.staged.json packages/typert/generator/tests/fixtures/type-model --fix && tsx scripts/run-oxlint.ts . --fix',
+    )
+    expect(packageJson.devDependencies).not.toHaveProperty('eslint')
+    expect(packageJson.devDependencies).not.toHaveProperty('@typescript-eslint/parser')
+    expect(existsSync(join(repositoryRoot, 'eslint.format.config.mjs'))).toBe(false)
+
+    const lefthook = await readFile(join(repositoryRoot, 'lefthook.yml'), 'utf8')
+    expect(lefthook).toContain('scripts/run-oxlint.ts --config .oxlintrc.staged.json --fix')
+    expect(lefthook).not.toContain('node_modules/.bin/eslint')
+    expect(lefthook).not.toContain('eslint.format.config.mjs')
   })
 
   it('reports an unused suppression', async () => {
@@ -227,10 +268,13 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
     if (result.error !== undefined) {
       throw new Error(flattenDiagnosticMessageText(result.error.messageText, '\n'))
     }
-    expect(result.config).toMatchObject({
+    const stagedConfig = result.config as unknown
+    if (!isRecord(stagedConfig)) throw new Error('.oxlintrc.staged.json must contain a config object')
+    expect(stagedConfig).toMatchObject({
       extends: ['./.oxlintrc.json'],
       options: { typeAware: false },
     })
+    expect(stagedConfig.ignorePatterns).not.toContain('packages/typert/generator/tests/fixtures/type-model/**')
 
     const suffix = randomUUID()
     const path = join(repositoryRoot, 'scripts', `staged-lint-probe-${suffix}.ts`)
@@ -254,30 +298,76 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
     }
   })
 
-  it('applies staged stylistic fixes before Oxlint validation', async () => {
+  it('preserves successful fix output channels', async () => {
     const suffix = randomUUID()
-    const configPath = await writeContractConfig(suffix)
-    const directory = join(repositoryRoot, 'scripts', `.oxlint-contract-${suffix}`)
-    const path = join(directory, 'fix.ts')
+    const path = join(repositoryRoot, 'scripts', `staged-lint-probe-${suffix}.ts`)
 
     try {
-      await mkdir(directory, { recursive: true })
-      await writeFile(path, 'const value={answer:1};  \nconsole.log(value)\n')
-
-      const relativePath = relative(repositoryRoot, path)
-      const formatResult = runStagedFormatter([relativePath])
-      const lintResult = runOxlint(['--config', relative(repositoryRoot, configPath), '--fix', relativePath])
-
-      expect(formatResult.error).toBeUndefined()
-      expect(formatResult.status, normalizedOutput(formatResult)).toBe(0)
-      expect(lintResult.error).toBeUndefined()
-      expect(lintResult.status, normalizedOutput(lintResult)).toBe(0)
-      await expect(readFile(path, 'utf8')).resolves.toBe('const value={ answer:1 }\nconsole.log(value)\n')
-    } finally {
-      await Promise.all([
-        rm(directory, { recursive: true, force: true }),
-        rm(configPath, { force: true }),
+      await writeFile(path, '// oxlint-disable-next-line no-console\nexport const value = 1\n')
+      const result = runRepositoryOxlint([
+        '--config',
+        '.oxlintrc.staged.json',
+        '--format',
+        'unix',
+        '--fix',
+        relative(repositoryRoot, path),
       ])
+
+      expect(result.error).toBeUndefined()
+      expect(result.status, normalizedOutput(result)).toBe(0)
+      expect(result.stdout).toContain('Unused oxlint-disable directive')
+      expect(result.stderr).toBe('')
+    } finally {
+      await rm(path, { force: true })
     }
-  }, 20_000)
+  })
+
+  it('prints only the final diagnostics when a fix retry still fails', async () => {
+    const suffix = randomUUID()
+    const path = join(repositoryRoot, 'scripts', `staged-lint-probe-${suffix}.ts`)
+
+    try {
+      await writeFile(path, `export const longProbe = ${'1 + '.repeat(80)}1\n`)
+      const result = runRepositoryOxlint([
+        '--config',
+        '.oxlintrc.staged.json',
+        '--format',
+        'unix',
+        '--fix',
+        relative(repositoryRoot, path),
+      ])
+      const output = normalizedOutput(result)
+
+      expect(result.error).toBeUndefined()
+      expect(result.status, output).toBe(1)
+      expect(output.match(/@stylistic\(max-len\)/g)).toHaveLength(1)
+    } finally {
+      await rm(path, { force: true })
+    }
+  })
+
+  it.each(['--fix', '--fix-suggestions', '--fix-dangerously'])(
+    'converges overlapping staged stylistic fixes through Oxlint under %s',
+    async (fixFlag) => {
+      const suffix = randomUUID()
+      const directory = join(repositoryRoot, 'scripts', `.oxlint-contract-${suffix}`)
+      const path = join(directory, 'fix.ts')
+
+      try {
+        await mkdir(directory, { recursive: true })
+        await writeFile(path, 'const value={answer:1};  \nconsole.log(value)\n')
+
+        const relativePath = relative(repositoryRoot, path)
+        const lintResult = runRepositoryOxlint(['--config', '.oxlintrc.staged.json', fixFlag, relativePath])
+
+        expect(lintResult.error).toBeUndefined()
+        expect(lintResult.status, normalizedOutput(lintResult)).toBe(0)
+        expect(normalizedOutput(lintResult)).not.toContain('@stylistic')
+        await expect(readFile(path, 'utf8')).resolves.toBe('const value={ answer:1 }\nconsole.log(value)\n')
+      } finally {
+        await rm(directory, { recursive: true, force: true })
+      }
+    },
+    20_000,
+  )
 })
diff --git a/scripts/run-oxlint.ts b/scripts/run-oxlint.ts
index e833f75c69..13ed84799f 100644
--- a/scripts/run-oxlint.ts
+++ b/scripts/run-oxlint.ts
@@ -3,6 +3,12 @@ import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const oxlintCli = fileURLToPath(new URL('../node_modules/oxlint/bin/oxlint', import.meta.url))
+const MAX_CAPTURED_OUTPUT_BYTES = 64 * 1024 * 1024
+const FIX_FLAGS = new Set(['--fix', '--fix-dangerously', '--fix-suggestions'])
+
+function isFixInvocation(args: readonly string[]): boolean {
+  return args.some(arg => FIX_FLAGS.has(arg))
+}
 
 /** Complete Oxlint child-process arguments and environment. */
 export interface OxlintInvocation {
@@ -32,14 +38,50 @@ export function resolveOxlintInvocation(args: readonly string[], env: NodeJS.Pro
   }
 }
 
+function completeFrom(result: { readonly signal: NodeJS.Signals | null; readonly status: number | null }): void {
+  if (result.signal !== null) {
+    process.kill(process.pid, result.signal)
+    return
+  }
+  process.exitCode = result.status ?? 1
+}
+
 function main(): void {
   const invocation = resolveOxlintInvocation(process.argv.slice(2), process.env)
-  const result = spawnSync(process.execPath, [oxlintCli, ...invocation.args], {
+  if (!isFixInvocation(invocation.args)) {
+    const result = spawnSync(process.execPath, [oxlintCli, ...invocation.args], {
+      env: invocation.env,
+      stdio: 'inherit',
+    })
+    if (result.error !== undefined) throw result.error
+    completeFrom(result)
+    return
+  }
+
+  const first = spawnSync(process.execPath, [oxlintCli, ...invocation.args], {
+    encoding: 'utf8',
+    env: invocation.env,
+    maxBuffer: MAX_CAPTURED_OUTPUT_BYTES,
+  })
+  if (first.error !== undefined) throw first.error
+  if (first.signal !== null) {
+    completeFrom(first)
+    return
+  }
+  if (first.status === 0) {
+    process.stdout.write(first.stdout)
+    process.stderr.write(first.stderr)
+    process.exitCode = 0
+    return
+  }
+
+  // Overlapping JS-plugin fixes can expose one more fixable diagnostic after the first pass.
+  const second = spawnSync(process.execPath, [oxlintCli, ...invocation.args], {
     env: invocation.env,
     stdio: 'inherit',
   })
-  if (result.error !== undefined) throw result.error
-  process.exitCode = result.status ?? 1
+  if (second.error !== undefined) throw second.error
+  completeFrom(second)
 }
 
 const entrypoint = process.argv[1]

From d950f60bdfbd3d9ef4a7fe3349f8a03a8b03afc5 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 14:58:54 +0800
Subject: [PATCH 463/516] test(windows): stabilize aliased HMR writes

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index 033ad1661a..1de504c221 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -26,21 +26,23 @@ async function eventually(test: () => boolean, message: string): Promise<void> {
 }
 
 describe('HMR exact config paths', () => {
-  it('observes module changes when its watch base is a filesystem alias', { timeout: 20_000 }, async () => {
+  it('observes module changes when its watch base is a filesystem alias', { timeout: 30_000 }, async () => {
     const target = mkdtempSync(join(tmpdir(), 'dsh-hmr-module-canonical-'))
     const alias = `${target}-alias`
-    const filename = join(alias, 'module.ts')
+    const aliasFilename = join(alias, 'module.ts')
     symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
-    writeFileSync(filename, 'export const generation = 0\n')
+    writeFileSync(aliasFilename, 'export const generation = 0\n')
     const ctx = await bootHmr(alias, ['.'])
-    const expected = pathToFileURL(join(realpathSync(target), 'module.ts')).href
+    const filename = join(realpathSync(target), 'module.ts')
+    const expected = pathToFileURL(filename).href
     const cacheHas = vi.spyOn(ctx.loader.internal!.loadCache, 'has').mockReturnValue(false)
     const observed: string[] = []
     ctx.on('hmr/change', (url) => { observed.push(url) })
     try {
-      const deadline = Date.now() + 10_000
+      const deadline = Date.now() + 20_000
       for (let generation = 1; !observed.includes(expected); generation += 1) {
         if (Date.now() >= deadline) throw new Error('HMR did not observe a module change through the alias')
+        // The watch base, not the writer spelling, is the alias under test.
         writeFileSync(filename, `export const generation = ${generation}\n`)
         // Leave Chokidar's atomic-write window idle so one coalesced change can publish.
         await new Promise(resolve => setTimeout(resolve, 250))

From 8829d15b8e252e9bc491c5ca0785a3ca570c00b4 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 15:02:52 +0800
Subject: [PATCH 464/516] test: update Oxlint override fingerprint

---
 scripts/lint-rule-fingerprint.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/lint-rule-fingerprint.spec.ts b/scripts/lint-rule-fingerprint.spec.ts
index a28afcc8cf..b1f57eba7b 100644
--- a/scripts/lint-rule-fingerprint.spec.ts
+++ b/scripts/lint-rule-fingerprint.spec.ts
@@ -85,7 +85,7 @@ describe('Oxlint repository rule fingerprint', () => {
   const overrides: readonly unknown[] = parsed.overrides
 
   it('pins the complete override shape', () => {
-    expect(overrides).toHaveLength(6)
+    expect(overrides).toHaveLength(8)
   })
 
   it.each(Object.entries(profiles))('pins the %s rule profile', (_name, profile) => {

From cf5e04f75c3f0cfeebef28454145051576b7b8af Mon Sep 17 00:00:00 2001
From: fz <fz@dsh.dev>
Date: Sun, 9 Aug 2026 15:12:23 +0800
Subject: [PATCH 465/516] docs: document idle watchdog activity pulses

---
 .../2026-07-06-timeout-deadline-library.i18n.yaml     |  4 ++--
 .../2026-07-06-timeout-deadline-library.md            | 11 ++++++-----
 .../2026-07-06-timeout-deadline-library.zh.md         | 11 ++++++-----
 3 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
index 24a047b540..8b3d66c3b0 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.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 .agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
-2026-07-06-timeout-deadline-library.md: 63463a76a65743436d4e78479800c19e257a42de
-2026-07-06-timeout-deadline-library.zh.md: c47e6d4e6ed0bec368fca8857e5bd4d7229b6b0e
+2026-07-06-timeout-deadline-library.md: 1afb8e326356f012498eed778e9bab1b0be64ea5
+2026-07-06-timeout-deadline-library.zh.md: c6992ba5463122e4eb4ebd1d904d0c0906140353
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
index 63463a76a6..1afb8e3263 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
@@ -57,10 +57,11 @@ export function deadline(
 export interface IdleWatchdog {
   readonly signal: AbortSignal
   next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>>
+  pulse(): void
   [Symbol.dispose](): void
 }
 
-/** Arm only while one iterator `next()` is outstanding, then rearm on later demand. */
+/** Arm only while one iterator `next()` is outstanding; rearm on later demand or out-of-band activity. */
 export function idleWatchdog(
   upstream: AbortSignal | undefined,
   timeoutMs: number,
@@ -71,7 +72,7 @@ export function idleWatchdog(
 export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string): TimeoutReason | undefined
 ```
 
-`deadline` fuses an upstream signal with a one-shot timer through `AbortSignal.any`, adds a typed `TimeoutReason`, and exposes disposable timer cleanup. Non-positive timeouts are an internal no-timeout sentinel for backend-owned background work; external hints pass through `clampTimeout` and must be positive and finite. Without a timer or upstream signal, the function returns a never-aborting signal with the same disposal shape. `idleWatchdog` instead requires a positive finite interval, keeps one stable fused signal for the entire stream, and arms its timer only while one iterator `next()` is outstanding; resolution disarms it, later demand rearms it, concurrent demand fails, and disposal clears the active arm. Providers translate timeout reasons into seam-specific results. `timeoutOf(signal, code)` scopes classification so an outer nested deadline is treated as upstream cancellation rather than the inner capability's timeout.
+`deadline` fuses an upstream signal with a one-shot timer through `AbortSignal.any`, adds a typed `TimeoutReason`, and exposes disposable timer cleanup. Non-positive timeouts are an internal no-timeout sentinel for backend-owned background work; external hints pass through `clampTimeout` and must be positive and finite. Without a timer or upstream signal, the function returns a never-aborting signal with the same disposal shape. `idleWatchdog` instead requires a positive finite interval, keeps one stable fused signal for the entire stream, and arms its timer only while one iterator `next()` is outstanding; resolution disarms it, later demand rearms it, and `pulse()` rearms that same outstanding demand after out-of-band transport activity. A pulse outside outstanding demand or after disposal is a no-op; concurrent demand fails, and disposal clears the active arm. Providers translate timeout reasons into seam-specific results. `timeoutOf(signal, code)` scopes classification so an outer nested deadline is treated as upstream cancellation rather than the inner capability's timeout.
 
 ### The division of labor
 
@@ -79,7 +80,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 |---|---|
 | Validate request hint and clamp default/max | `dsh-timeout` (`clampTimeout`) — pure arithmetic plus the shared positive-finite request contract |
 | Arm one-shot timer, abort on deadline, carry reason, fuse with upstream cancel | `dsh-timeout` (`deadline`) |
-| Arm and rearm only around outstanding iterator demand | `dsh-timeout` (`idleWatchdog`) |
+| Arm and rearm only around outstanding iterator demand, including out-of-band activity | `dsh-timeout` (`idleWatchdog`) |
 | Clear the timer | `dsh-timeout` (`[Symbol.dispose]` on either primitive) |
 | Classify the first abort reason after abort | `dsh-timeout` (`timeoutOf`) |
 | **Actually terminate the work** | the capability's implementation |
@@ -92,7 +93,7 @@ The signal only *notifies*; termination is always the listener's job, and the li
 
 - **web_fetch** — the tool stays validate-and-forward; the provider's hand-rolled controller + `setTimeout` + manual listener + `finally` + `signal.reason` recovery is replaced by provider-owned `deadline`/`timeoutOf`. A pre-aborted upstream signal still throws `WEB_ABORTED` up front; otherwise `fetch` runs against the fused `d.signal`, and `translateAbortOrNetwork` classifies a thrown error by the signal (`timeoutOf` → `WEB_FETCH_TIMEOUT`, else aborted → `WEB_ABORTED`, else network → `WEB_PROVIDER_ERROR`). The public error-code contract is unchanged, and `TimeoutReason` never crosses the web seam as the public error.
 - **bash** — `resolve()` clamps the request into an explicit spec. Foreground `run()` creates the deadline and passes its signal to process execution, whose existing abort listener performs the process-group kill. The executor classifies the first abort as timeout or cancellation. Background starts remain timeout-free and forward only upstream cancellation.
-- **LLM adapters** — `dsh-llm-deepseek` and `dsh-llm-pi-ai` wrap actual transport iteration with `idleWatchdog`. The five-minute configured interval covers only outstanding provider demand, not time the downstream consumer spends between chunks. The stable signal reaches `fetch` or the SDK for the whole call, so timeout closes the underlying request and maps to `TIMEOUT`, while an earlier caller abort maps to `ABORTED`.
+- **LLM adapters** — `dsh-llm-deepseek` and `dsh-llm-pi-ai` wrap actual transport iteration with `idleWatchdog`. The five-minute configured interval covers only outstanding provider demand, not time the downstream consumer spends between chunks. The direct DeepSeek adapter also pulses that outstanding demand when its SSE parser observes a comment, without yielding the comment as a `StreamChunk` or writing it to the session log. The pi-ai SDK does not expose comment activity to its adapter, so that path can rearm only when the SDK yields. The stable signal reaches `fetch` or the SDK for the whole call, so timeout closes the underlying request and maps to `TIMEOUT`, while an earlier caller abort maps to `ABORTED`.
 
 ## Consequences
 
@@ -100,7 +101,7 @@ The signal only *notifies*; termination is always the listener's job, and the li
 - `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. This is the one deviation from the literal proposal shape (which passed `timeoutMs: 0` into `runBash`); an always-0 field read by nothing is dead weight under the per-file coverage gate.
 - web_fetch shed its bespoke controller/timer/listener/reason-recovery; the classifier now keys off the deadline signal (`timeoutOf` + `aborted`) rather than the thrown error's shape, which is robust across both the request-phase reject-with-reason and the read-phase bare-`AbortError`.
 - `AbortSignal.any` and `using`/`Symbol.dispose` enter the repo for the first time here (Node ≥ 24 baseline, already met).
-- Model streams now share one rearmable timer contract without turning a sliding idle interval into a total-call deadline or charging consumer think time. The primitive still only notifies; adapter tests prove their transports observe its stable signal and terminate.
+- Model streams now share one rearmable timer contract without turning a sliding idle interval into a total-call deadline or charging consumer think time. Adapters that can observe out-of-band transport activity may pulse an outstanding demand; suppressed activity remains invisible to the watchdog. The primitive still only notifies; adapter tests prove their transports observe its stable signal and terminate.
 
 Out of scope, named to mark the boundary: `web_search` can gain an optional model-facing `timeout_ms` once its tool-schema/snapshot coverage is planned; future ripgrep-backed fs discovery tools can consume the same provider-owned deadline shape once they exist; a `tools/execute` waterfall middleware could arm a default deadline for every tool call by driving `exec.signal` — that would be a plugin that *consumes* this library and still only notifies, the hard kill remaining each capability's job.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
index c47e6d4e6e..c6992ba546 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
@@ -57,10 +57,11 @@ export function deadline(
 export interface IdleWatchdog {
   readonly signal: AbortSignal
   next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>>
+  pulse(): void
   [Symbol.dispose](): void
 }
 
-/** Arm only while one iterator `next()` is outstanding, then rearm on later demand. */
+/** Arm only while one iterator `next()` is outstanding; rearm on later demand or out-of-band activity. */
 export function idleWatchdog(
   upstream: AbortSignal | undefined,
   timeoutMs: number,
@@ -71,7 +72,7 @@ export function idleWatchdog(
 export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string): TimeoutReason | undefined
 ```
 
-`deadline` 通过 `AbortSignal.any` 将上游信号与一次性定时器融合，附加一个类型化的 `TimeoutReason`，并暴露可 dispose（资源释放）的定时器清理。非正数超时是内部的「无超时」哨兵，用于后端拥有的后台任务；外部提示经过 `clampTimeout`，必须为正有限值。既无定时器也无上游信号时，函数返回一个永不中止的信号，具有相同的 disposal 形状。`idleWatchdog` 则要求正有限的间隔，在整个流期间保持一个稳定的融合信号，并且只在一个迭代器 `next()` 尚未结算时启动定时器；结算会解除定时器，后续 demand 会重新启动，并发 demand 会失败，dispose 会清除当前 arm。提供方将超时原因转译为 seam 特定的结果。`timeoutOf(signal, code)` 限定分类范围，使外层嵌套的 deadline 被视为上游取消而非内层能力自身的超时。
+`deadline` 通过 `AbortSignal.any` 将上游信号与一次性定时器融合，附加一个类型化的 `TimeoutReason`，并暴露可 dispose（资源释放）的定时器清理。非正数超时是内部的「无超时」哨兵，用于后端拥有的后台任务；外部提示经过 `clampTimeout`，必须为正有限值。既无定时器也无上游信号时，函数返回一个永不中止的信号，具有相同的 disposal 形状。`idleWatchdog` 则要求正有限的间隔，在整个流期间保持一个稳定的融合信号，并且只在一个迭代器 `next()` 尚未结算时启动定时器；结算会解除定时器，后续 demand 会重新启动，带外传输活动发生后，`pulse()` 则会为同一个尚未结算的 demand 重新启动定时器。若没有尚未结算的 demand，或已经 dispose，pulse 不执行任何操作；并发 demand 会失败，dispose 会清除当前 arm。提供方将超时原因转译为 seam 特定的结果。`timeoutOf(signal, code)` 限定分类范围，使外层嵌套的 deadline 被视为上游取消而非内层能力自身的超时。
 
 ### 职责划分
 
@@ -79,7 +80,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 |---|---|
 | 校验请求提示并钳位默认值/最大值 | `dsh-timeout`（`clampTimeout`）：纯算术加共享的正有限请求约定 |
 | 启动一次性定时器、到期中止、携带 reason、与上游取消融合 | `dsh-timeout`（`deadline`） |
-| 仅围绕未结算的迭代器 demand 启动和重启 | `dsh-timeout`（`idleWatchdog`） |
+| 仅围绕未结算的迭代器 demand 启动和重启，带外活动也会触发重启 | `dsh-timeout`（`idleWatchdog`） |
 | 清除定时器 | `dsh-timeout`（任一原语的 `[Symbol.dispose]`） |
 | 中止后对首个 abort reason 进行分类 | `dsh-timeout`（`timeoutOf`） |
 | **实际终止工作** | 各能力的实现 |
@@ -92,7 +93,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 
 - **web_fetch**：工具层保持校验并转发；提供方手写的 controller + `setTimeout` + 手动监听器 + `finally` + `signal.reason` 恢复被替换为提供方自有的 `deadline`/`timeoutOf`。已预先中止的上游信号仍然立即抛出 `WEB_ABORTED`；否则 `fetch` 使用融合后的 `d.signal` 运行，`translateAbortOrNetwork` 根据信号分类抛出的错误（`timeoutOf` → `WEB_FETCH_TIMEOUT`，否则已中止 → `WEB_ABORTED`，否则网络错误 → `WEB_PROVIDER_ERROR`）。公开的错误码约定不变，`TimeoutReason` 永远不会作为公开错误跨越 web seam。
 - **bash**：`resolve()` 将请求钳位为显式规格。前台 `run()` 创建 deadline 并将其信号传给进程执行，后者既有的 abort 监听器执行进程组 kill。执行器将首个 abort 分类为超时或取消。后台启动保持无超时，仅转发上游取消。
-- **LLM（大语言模型）适配器**：`dsh-llm-deepseek` 和 `dsh-llm-pi-ai` 用 `idleWatchdog` 包装实际的传输迭代。配置的五分钟间隔只覆盖尚未结算的提供方 demand，不包括下游消费方在分片之间花费的时间。稳定信号在整个调用期间传给 `fetch` 或 SDK，因此超时会关闭底层请求并映射为 `TIMEOUT`，而更早的调用方中止映射为 `ABORTED`。
+- **LLM（大语言模型）适配器**：`dsh-llm-deepseek` 和 `dsh-llm-pi-ai` 用 `idleWatchdog` 包装实际的传输迭代。配置的五分钟间隔只覆盖尚未结算的提供方 demand，不包括下游消费方在分片之间花费的时间。DeepSeek 直连适配器还会在其 SSE（Server-Sent Events）解析器观察到注释时，对该项尚未结算的 demand 调用 `pulse()`；该注释既不会作为 `StreamChunk` 产出，也不会写入会话日志。pi-ai SDK 不会向其适配器暴露注释活动，因此该路径只能在 SDK 产出值时重新启动定时器。稳定信号在整个调用期间传给 `fetch` 或 SDK，因此超时会关闭底层请求并映射为 `TIMEOUT`，而更早的调用方中止映射为 `ABORTED`。
 
 ## 后果
 
@@ -100,7 +101,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 - `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。这是与字面提案形状（向 `runBash` 传入 `timeoutMs: 0`）的唯一偏差；一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
 - web_fetch 去除了其定制的 controller/timer/listener/reason-recovery；分类器现在基于 deadline 信号（`timeoutOf` + `aborted`）而非抛出错误的形状来判断，这在请求阶段的 reject-with-reason 和读取阶段的裸 `AbortError` 两种情况下都是健壮的。
 - `AbortSignal.any` 和 `using`/`Symbol.dispose` 在此首次进入本仓库（Node ≥ 24 基线，已满足）。
-- 模型流现在共享一个可重启的定时器约定，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
+- 模型流现在共享一个可重启的定时器约定，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。能够观察到带外传输活动的适配器可以对尚未结算的 demand 调用 `pulse()`；被屏蔽的活动对 watchdog 仍不可见。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
 
 以下内容不在本次范围内，列出以标明边界：`web_search` 可以在其工具 schema 和快照覆盖规划完成后获得可选的面向模型的 `timeout_ms`；未来基于 ripgrep 的文件系统发现工具可以在实现后消费同样的提供方自有 deadline 形状；`tools/execute` waterfall（瀑布式事件）中间件可以通过驱动 `exec.signal` 为每次工具调用设置默认 deadline——那将是一个*消费*本库的插件，仍然只做通知，硬终止仍是各能力自己的事。
 

From 996ff7a4409e92b26471507395937344bf22c847 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 15:14:14 +0800
Subject: [PATCH 466/516] test: refresh translation prompt snapshot

---
 .../translation-prompt-v4/request-response.expected.json      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index ded84487bf..0bd65e93e4 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -16,11 +16,11 @@
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [subsystems](subsystems/README.md) pages paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, validates staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint fixes with one bounded retry, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [subsystems](subsystems/README.md) pages paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n"
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成约定构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 约定 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成约定构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 约定 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备约定见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档约定](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件，并通过一次有界重试应用 Oxlint 修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 约定生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[子系统](subsystems/README.md)页面会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码约定。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码约定和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n"
       },
       {
         "role": "user",

From 9704749b0139cc539945990a2a00f36d49b1d3ef Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 15:35:02 +0800
Subject: [PATCH 467/516] docs: replace vague provenance prose with recorded
 facts

---
 .../2026-06-18-session-surface.i18n.yaml      |  4 +--
 .../2026-06-18-session-surface.md             | 10 +++---
 .../2026-06-18-session-surface.zh.md          | 10 +++---
 ...-21-bounded-llm-request-recovery.i18n.yaml |  4 +--
 ...2026-06-21-bounded-llm-request-recovery.md |  2 +-
 ...6-06-21-bounded-llm-request-recovery.zh.md |  2 +-
 ...bles-and-tool-guidance-ownership.i18n.yaml |  4 +--
 ...t-variables-and-tool-guidance-ownership.md |  2 +-
 ...ariables-and-tool-guidance-ownership.zh.md |  2 +-
 ...6-07-05-reconstructable-requests.i18n.yaml |  4 +--
 .../2026-07-05-reconstructable-requests.md    |  4 +--
 .../2026-07-05-reconstructable-requests.zh.md |  4 +--
 ...n-pressure-and-overflow-recovery.i18n.yaml |  4 +--
 ...mpaction-pressure-and-overflow-recovery.md |  2 +-
 ...ction-pressure-and-overflow-recovery.zh.md |  2 +-
 ...-14-provider-routed-llm-adapters.i18n.yaml |  4 +--
 ...2026-07-14-provider-routed-llm-adapters.md | 16 ++++-----
 ...6-07-14-provider-routed-llm-adapters.zh.md | 16 ++++-----
 ...07-15-replay-token-meter-service.i18n.yaml |  4 +--
 .../2026-07-15-replay-token-meter-service.md  |  8 ++---
 ...026-07-15-replay-token-meter-service.zh.md |  8 ++---
 ...-package-owned-invariant-service.i18n.yaml |  4 +--
 ...6-07-19-package-owned-invariant-service.md |  2 +-
 ...7-19-package-owned-invariant-service.zh.md |  2 +-
 ...0-canonical-tool-output-contract.i18n.yaml |  4 +--
 ...26-07-20-canonical-tool-output-contract.md |  2 +-
 ...07-20-canonical-tool-output-contract.zh.md |  2 +-
 ...send-and-coalesced-user-messages.i18n.yaml |  4 +--
 ...nified-send-and-coalesced-user-messages.md |  4 +--
 ...ied-send-and-coalesced-user-messages.zh.md |  4 +--
 ...xt-injection-from-turn-execution.i18n.yaml |  4 +--
 ...e-context-injection-from-turn-execution.md |  6 ++--
 ...ontext-injection-from-turn-execution.zh.md |  6 ++--
 ...-26-packed-chunk-rows-by-default.i18n.yaml |  4 +--
 ...2026-07-26-packed-chunk-rows-by-default.md |  2 +-
 ...6-07-26-packed-chunk-rows-by-default.zh.md |  2 +-
 ...ntified-immutable-message-values.i18n.yaml |  4 +--
 ...-28-identified-immutable-message-values.md |  6 ++--
 ...-identified-immutable-message-values.zh.md |  6 ++--
 ...-29-terminal-llm-stream-failures.i18n.yaml |  4 +--
 ...2026-07-29-terminal-llm-stream-failures.md |  4 +--
 ...6-07-29-terminal-llm-stream-failures.zh.md |  4 +--
 ...adapter-owned-max-token-defaults.i18n.yaml |  4 +--
 ...-07-30-adapter-owned-max-token-defaults.md |  4 +--
 ...-30-adapter-owned-max-token-defaults.zh.md |  4 +--
 ...ssion-persistence-write-batching.i18n.yaml |  4 +--
 ...nded-session-persistence-write-batching.md |  4 +--
 ...d-session-persistence-write-batching.zh.md |  4 +--
 ...ad-pre-identity-session-messages.i18n.yaml |  4 +--
 ...7-28-load-pre-identity-session-messages.md |  2 +-
 ...8-load-pre-identity-session-messages.zh.md |  2 +-
 ...9-human-transcript-append-origin.i18n.yaml |  4 +--
 ...26-07-29-human-transcript-append-origin.md |  6 ++--
 ...07-29-human-transcript-append-origin.zh.md |  6 ++--
 ...cky-composer-conversation-scroll.i18n.yaml |  2 +-
 ...-29-sticky-composer-conversation-scroll.md |  2 +-
 ...ranscript-log-ordered-projection.i18n.yaml |  4 +--
 ...0-web-transcript-log-ordered-projection.md |  2 +-
 ...eb-transcript-log-ordered-projection.zh.md |  2 +-
 ...-04-load-pre-react-loop-sessions.i18n.yaml |  4 +--
 ...2026-08-04-load-pre-react-loop-sessions.md |  2 +-
 ...6-08-04-load-pre-react-loop-sessions.zh.md |  2 +-
 ...ontext-meter-blind-to-compaction.i18n.yaml |  4 +--
 ...08-05-context-meter-blind-to-compaction.md |  2 +-
 ...05-context-meter-blind-to-compaction.zh.md |  2 +-
 ...-attribution-observed-top-ledger.i18n.yaml |  2 +-
 ...-scroll-attribution-observed-top-ledger.md |  4 +--
 ...06-18-compaction-capability-seam.i18n.yaml |  4 +--
 .../2026-06-18-compaction-capability-seam.md  | 10 +++---
 ...026-06-18-compaction-capability-seam.zh.md | 10 +++---
 .../feature/2026-07-06-sandbox.i18n.yaml      |  4 +--
 .../implemented/feature/2026-07-06-sandbox.md |  4 +--
 .../feature/2026-07-06-sandbox.zh.md          |  4 +--
 ...-self-referential-cordis-toolset.i18n.yaml |  4 +--
 ...6-07-08-self-referential-cordis-toolset.md |  2 +-
 ...7-08-self-referential-cordis-toolset.zh.md |  2 +-
 ...2026-07-13-session-query-tracing.i18n.yaml |  4 +--
 .../2026-07-13-session-query-tracing.md       | 12 +++----
 .../2026-07-13-session-query-tracing.zh.md    | 12 +++----
 .../2026-07-16-harness-level-loop.i18n.yaml   |  4 +--
 .../feature/2026-07-16-harness-level-loop.md  |  6 ++--
 .../2026-07-16-harness-level-loop.zh.md       |  6 ++--
 ...26-07-19-model-facing-goal-tools.i18n.yaml |  4 +--
 .../2026-07-19-model-facing-goal-tools.md     |  6 ++--
 .../2026-07-19-model-facing-goal-tools.zh.md  |  6 ++--
 ...6-07-21-cross-session-references.i18n.yaml |  4 +--
 .../2026-07-21-cross-session-references.md    |  2 +-
 .../2026-07-21-cross-session-references.zh.md |  2 +-
 ...-07-21-log-backed-session-titles.i18n.yaml |  4 +--
 .../2026-07-21-log-backed-session-titles.md   |  6 ++--
 ...2026-07-21-log-backed-session-titles.zh.md |  6 ++--
 ...model-facing-session-query-tools.i18n.yaml |  4 +--
 ...-07-24-model-facing-session-query-tools.md |  2 +-
 ...-24-model-facing-session-query-tools.zh.md |  2 +-
 ...-27-trajectory-inspection-ledger.i18n.yaml |  4 +--
 ...2026-07-27-trajectory-inspection-ledger.md |  4 +--
 ...6-07-27-trajectory-inspection-ledger.zh.md |  4 +--
 ...-workspace-registration-deletion.i18n.yaml |  4 +--
 ...6-07-27-workspace-registration-deletion.md |  4 +--
 ...7-27-workspace-registration-deletion.zh.md |  4 +--
 ...ntinuable-subagent-conversations.i18n.yaml |  4 +--
 ...7-28-continuable-subagent-conversations.md | 20 +++++------
 ...8-continuable-subagent-conversations.zh.md | 18 +++++-----
 ...continuable-subagent-report-tool.i18n.yaml |  4 +--
 ...-07-30-continuable-subagent-report-tool.md |  6 ++--
 ...-30-continuable-subagent-report-tool.zh.md |  6 ++--
 ...6-07-30-queued-manual-compaction.i18n.yaml |  4 +--
 .../2026-07-30-queued-manual-compaction.md    |  4 +--
 .../2026-07-30-queued-manual-compaction.zh.md |  4 +--
 ...b-context-source-and-steer-marks.i18n.yaml |  4 +--
 ...8-04-web-context-source-and-steer-marks.md | 10 +++---
 ...4-web-context-source-and-steer-marks.zh.md |  8 ++---
 ...26-08-05-context-form-vocabulary.i18n.yaml |  4 +--
 .../2026-08-05-context-form-vocabulary.md     | 12 +++----
 .../2026-08-05-context-form-vocabulary.zh.md  | 10 +++---
 ...-20-core-data-structures-catalog.i18n.yaml |  4 +--
 ...2026-06-20-core-data-structures-catalog.md |  4 +--
 ...6-06-20-core-data-structures-catalog.zh.md |  4 +--
 ...26-07-27-worktree-local-lefthook.i18n.yaml |  4 +--
 .../2026-07-27-worktree-local-lefthook.md     |  2 +-
 .../2026-07-27-worktree-local-lefthook.zh.md  |  2 +-
 ...6-in-repository-landlock-release.i18n.yaml |  4 +--
 ...26-08-06-in-repository-landlock-release.md |  4 +--
 ...08-06-in-repository-landlock-release.zh.md |  4 +--
 ...08-08-browser-gif-evidence-chain.i18n.yaml |  4 +--
 .../2026-08-08-browser-gif-evidence-chain.md  |  8 ++---
 ...026-08-08-browser-gif-evidence-chain.zh.md |  8 ++---
 ...08-unified-github-label-taxonomy.i18n.yaml |  4 +--
 ...026-08-08-unified-github-label-taxonomy.md |  4 +--
 ...-08-08-unified-github-label-taxonomy.zh.md |  4 +--
 ...-names-actors-and-recorded-facts.i18n.yaml |  6 ++++
 ...e-prose-names-actors-and-recorded-facts.md | 33 ++++++++++++++++++
 ...rose-names-actors-and-recorded-facts.zh.md | 33 ++++++++++++++++++
 ...plify-session-log-representation.i18n.yaml |  4 +--
 ...-12-simplify-session-log-representation.md |  2 +-
 ...-simplify-session-log-representation.zh.md |  2 +-
 ...t-invariants-from-shipped-config.i18n.yaml |  4 +--
 ...-03-omit-invariants-from-shipped-config.md |  2 +-
 ...-omit-invariants-from-shipped-config.zh.md |  2 +-
 ...2026-07-06-recallable-compaction.i18n.yaml |  4 +--
 .../2026-07-06-recallable-compaction.md       |  8 ++---
 .../2026-07-06-recallable-compaction.zh.md    |  8 ++---
 ...-07-08-interactive-side-sessions.i18n.yaml |  4 +--
 .../2026-07-08-interactive-side-sessions.md   |  4 +--
 ...2026-07-08-interactive-side-sessions.zh.md |  4 +--
 ...3-human-review-skill-maintenance.i18n.yaml |  4 +--
 ...26-07-13-human-review-skill-maintenance.md | 16 ++++-----
 ...07-13-human-review-skill-maintenance.zh.md | 16 ++++-----
 ...ndstrip-for-windows-sandbox-rung.i18n.yaml |  4 +--
 ...uate-landstrip-for-windows-sandbox-rung.md |  8 ++---
 ...e-landstrip-for-windows-sandbox-rung.zh.md |  8 ++---
 ...19-fold-compaction-package-split.i18n.yaml |  4 +--
 ...026-07-19-fold-compaction-package-split.md |  2 +-
 ...-07-19-fold-compaction-package-split.zh.md |  2 +-
 ...ency-swaps-rejected-by-nih-audit.i18n.yaml |  4 +--
 ...-dependency-swaps-rejected-by-nih-audit.md |  2 +-
 ...pendency-swaps-rejected-by-nih-audit.zh.md |  2 +-
 .agents/skills/record-browser-gif/SKILL.md    | 12 +++----
 apps/cli/reference/README.i18n.yaml           |  4 +--
 apps/cli/reference/README.md                  |  2 +-
 apps/cli/reference/README.zh.md               |  2 +-
 apps/cli/src/dump-config.ts                   |  4 +--
 apps/cli/tests/built-bin.e2e.ts               |  2 +-
 apps/web/tests/seeded-history.e2e.ts          |  2 +-
 docs/AGENTS.md                                |  2 +-
 docs/agent-lifecycle.md                       |  2 +-
 docs/architecture.i18n.yaml                   |  4 +--
 docs/architecture.md                          |  6 ++--
 docs/architecture.zh.md                       |  6 ++--
 docs/config-catalog.md                        |  2 +-
 .../maintaining-dsh-code-review.i18n.yaml     |  4 +--
 docs/cookbook/maintaining-dsh-code-review.md  |  4 +--
 .../maintaining-dsh-code-review.zh.md         |  4 +--
 docs/persistence-catalog.md                   |  8 ++---
 docs/subsystems/README.i18n.yaml              |  4 +--
 docs/subsystems/README.md                     |  2 +-
 docs/subsystems/README.zh.md                  |  2 +-
 docs/subsystems/compaction.i18n.yaml          |  4 +--
 docs/subsystems/compaction.md                 | 10 +++---
 docs/subsystems/compaction.zh.md              | 10 +++---
 docs/subsystems/core.i18n.yaml                |  4 +--
 docs/subsystems/core.md                       | 14 ++++----
 docs/subsystems/core.zh.md                    | 14 ++++----
 docs/subsystems/llm-streaming.i18n.yaml       |  4 +--
 docs/subsystems/llm-streaming.md              | 18 +++++-----
 docs/subsystems/llm-streaming.zh.md           | 18 +++++-----
 docs/subsystems/session-query.i18n.yaml       |  4 +--
 docs/subsystems/session-query.md              | 14 ++++----
 docs/subsystems/session-query.zh.md           | 14 ++++----
 docs/subsystems/session-title.i18n.yaml       |  4 +--
 docs/subsystems/session-title.md              | 10 +++---
 docs/subsystems/session-title.zh.md           | 10 +++---
 docs/subsystems/session.i18n.yaml             |  4 +--
 docs/subsystems/session.md                    | 34 +++++++++----------
 docs/subsystems/session.zh.md                 | 34 +++++++++----------
 docs/subsystems/spill.i18n.yaml               |  4 +--
 docs/subsystems/spill.md                      |  6 ++--
 docs/subsystems/spill.zh.md                   |  6 ++--
 docs/subsystems/subagent.i18n.yaml            |  4 +--
 docs/subsystems/subagent.md                   |  6 ++--
 docs/subsystems/subagent.zh.md                |  6 ++--
 docs/tool-catalog.md                          |  2 +-
 .../headless-agent/tests/compaction.e2e.ts    |  2 +-
 native/landlock-run/docs/architecture.md      |  2 +-
 native/landlock-run/scripts/build.ts          |  2 +-
 .../scripts/verify-launcher-binary.mjs        |  5 ++-
 packages/bash/bash-sandbox/README.i18n.yaml   |  4 +--
 packages/bash/bash-sandbox/README.md          |  4 +--
 packages/bash/bash-sandbox/README.zh.md       |  4 +--
 packages/bash/bash-sandbox/src/helpers.ts     |  2 +-
 packages/bash/bash-sandbox/src/index.ts       |  2 +-
 .../tests/partial-landlock.spec.ts            |  2 +-
 .../bash/bash-sandbox/tests/sandbox.spec.ts   |  4 +--
 packages/boot/app-boot/README.i18n.yaml       |  4 +--
 packages/boot/app-boot/README.md              |  2 +-
 packages/boot/app-boot/README.zh.md           |  2 +-
 packages/boot/app-boot/src/index.ts           | 16 ++++-----
 .../boot/app-boot/tests/config-dump.spec.ts   | 10 +++---
 packages/client/runtime/README.i18n.yaml      |  4 +--
 packages/client/runtime/README.md             |  4 +--
 packages/client/runtime/README.zh.md          |  4 +--
 .../src/client/sessions/context-provenance.ts |  2 +-
 .../src/client/sessions/conversation.ts       | 10 +++---
 .../runtime/src/client/sessions/session.ts    |  2 +-
 .../src/client/sessions/transcript-adapter.ts |  6 ++--
 packages/client/runtime/tests/event-script.ts |  2 +-
 .../client/runtime/tests/history-fold.spec.ts |  2 +-
 .../runtime/tests/transcript-adapter.spec.ts  | 12 +++----
 .../client/ui-conversation/README.i18n.yaml   |  4 +--
 packages/client/ui-conversation/README.md     |  4 +--
 packages/client/ui-conversation/README.zh.md  |  4 +--
 .../src/client/chat/CompactionItem.tsx        |  2 +-
 .../src/client/chat/ContextBody.module.css    |  2 +-
 .../src/client/chat/ContextBody.tsx           |  8 ++---
 .../src/client/chat/ContextInjectionRow.tsx   |  2 +-
 .../tests/chat-branch-tails.spec.tsx          |  6 ++--
 .../tests/markdown-dom-parity.spec.tsx        |  2 +-
 .../src/client/context-branches.ts            |  4 +--
 .../src/client/trajectory-record.ts           |  2 +-
 .../compact/compact-basic/README.i18n.yaml    |  4 +--
 packages/compact/compact-basic/README.md      |  6 ++--
 packages/compact/compact-basic/README.zh.md   |  6 ++--
 packages/compact/compact-basic/src/index.ts   |  4 +--
 packages/compact/compact-basic/src/region.ts  |  2 +-
 .../compact/compact-basic/src/summarizer.ts   |  4 +--
 .../compact-basic/tests/compact-basic.spec.ts |  2 +-
 .../tests/manual-compact.spec.ts              |  8 ++---
 .../compact-tool-result-prune/src/index.ts    |  2 +-
 .../compact-tool-result-prune/src/types.ts    |  2 +-
 .../tests/tool-result-prune.spec.ts           |  2 +-
 packages/compact/compact/README.i18n.yaml     |  4 +--
 packages/compact/compact/README.md            |  2 +-
 packages/compact/compact/README.zh.md         |  2 +-
 packages/compact/compact/src/types.ts         |  4 +--
 .../context/session-reference/src/types.ts    |  2 +-
 .../context/workspace-context/src/state.ts    |  2 +-
 packages/core/agent-loop/README.i18n.yaml     |  4 +--
 packages/core/agent-loop/README.md            |  4 +--
 packages/core/agent-loop/README.zh.md         |  4 +--
 packages/core/agent-loop/src/tool-calls.ts    |  4 +--
 .../tests/contract-regressions.spec.ts        |  2 +-
 packages/core/agent/README.i18n.yaml          |  4 +--
 packages/core/agent/README.md                 |  2 +-
 packages/core/agent/README.zh.md              |  2 +-
 packages/core/agent/src/types.ts              |  8 ++---
 packages/core/session/README.i18n.yaml        |  4 +--
 packages/core/session/README.md               | 12 +++----
 packages/core/session/README.zh.md            | 12 +++----
 packages/core/session/src/index.ts            |  8 ++---
 packages/core/session/src/invariant.ts        |  2 +-
 packages/core/session/src/repair.ts           |  4 +--
 packages/core/session/src/surface.ts          |  4 +--
 packages/core/session/src/types.ts            | 10 +++---
 .../tests/gen-persistence-catalog.spec.ts     |  4 +--
 packages/core/session/tests/session.spec.ts   |  2 +-
 packages/core/session/tests/surface.spec.ts   |  8 ++---
 packages/core/tools/README.i18n.yaml          |  4 +--
 packages/core/tools/README.md                 |  2 +-
 packages/core/tools/README.zh.md              |  2 +-
 packages/fs/fs-local/tests/fsio.spec.ts       |  2 +-
 packages/goal/tool-goal/README.i18n.yaml      |  4 +--
 packages/goal/tool-goal/README.md             |  2 +-
 packages/goal/tool-goal/README.zh.md          |  2 +-
 .../tests/repeat-tool-guard.spec.ts           |  2 +-
 packages/hooks/hook-protocol/README.i18n.yaml |  4 +--
 packages/hooks/hook-protocol/README.md        |  2 +-
 packages/hooks/hook-protocol/README.zh.md     |  2 +-
 packages/hooks/hook-protocol/src/events.ts    |  2 +-
 packages/hooks/hook-protocol/src/invariant.ts |  4 +--
 packages/hooks/hook-protocol/src/types.ts     |  4 +--
 .../hook-protocol/tests/invariant.spec.ts     |  2 +-
 packages/hooks/hooks-claude/src/index.ts      |  2 +-
 packages/hooks/hooks-claude/src/invariant.ts  |  2 +-
 packages/hooks/hooks-codex/src/index.ts       |  4 +--
 packages/hooks/hooks-codex/src/invariant.ts   |  2 +-
 packages/host/apiproxy/README.i18n.yaml       |  4 +--
 packages/host/apiproxy/README.md              |  2 +-
 packages/host/apiproxy/README.zh.md           |  2 +-
 packages/host/apiproxy/src/api-proxy.ts       |  4 +--
 packages/host/apiproxy/src/api/sessions.ts    |  2 +-
 .../apiproxy/tests/api-proxy-search.spec.ts   |  2 +-
 .../apiproxy/tests/api-proxy-view.spec.ts     |  6 ++--
 packages/interaction/commands/src/index.ts    |  2 +-
 packages/llm/llm-pi-ai/README.i18n.yaml       |  4 +--
 packages/llm/llm-pi-ai/README.md              |  4 +--
 packages/llm/llm-pi-ai/README.zh.md           |  4 +--
 packages/llm/llm-pi-ai/tests/convert.spec.ts  |  2 +-
 packages/llm/llm/README.i18n.yaml             |  4 +--
 packages/llm/llm/README.md                    |  6 ++--
 packages/llm/llm/README.zh.md                 |  6 ++--
 packages/llm/llm/src/call-config.ts           |  2 +-
 packages/llm/llm/src/message.ts               |  8 ++---
 packages/llm/llm/tests/message.spec.ts        |  2 +-
 packages/llm/llm/tests/service.spec.ts        |  2 +-
 packages/llm/token-meter/README.i18n.yaml     |  4 +--
 packages/llm/token-meter/README.md            |  6 ++--
 packages/llm/token-meter/README.zh.md         |  6 ++--
 packages/llm/token-meter/src/index.ts         |  6 ++--
 .../llm/token-meter/tests/token-meter.spec.ts |  6 ++--
 packages/sandbox/sandbox-local/src/index.ts   |  2 +-
 packages/scaffold/server/src/server.ts        |  2 +-
 packages/scaffold/server/tests/server.spec.ts |  2 +-
 .../tool-cordis/src/api-catalog.ts            |  8 ++---
 .../session-query/README.i18n.yaml            |  4 +--
 .../session-query/session-query/README.md     |  6 ++--
 .../session-query/session-query/README.zh.md  |  6 ++--
 .../session-query/session-query/src/index.ts  |  4 +--
 .../session-query/src/tracing.ts              |  2 +-
 .../session-query/session-query/src/types.ts  |  8 ++---
 .../session-query/tests/tracing.spec.ts       |  4 +--
 .../tool-session-query/src/index.ts           |  2 +-
 .../tool-session-query/src/presentation.ts    |  2 +-
 .../session-persistence/README.i18n.yaml      |  4 +--
 .../session/session-persistence/README.md     |  2 +-
 .../session/session-persistence/README.zh.md  |  2 +-
 .../session-title-llm/README.i18n.yaml        |  4 +--
 packages/session/session-title-llm/README.md  |  2 +-
 .../session/session-title-llm/README.zh.md    |  2 +-
 .../session/session-title-llm/src/index.ts    |  2 +-
 .../session-title-llm/src/invariant.ts        |  2 +-
 .../session/session-title/README.i18n.yaml    |  4 +--
 packages/session/session-title/README.md      |  2 +-
 packages/session/session-title/README.zh.md   |  2 +-
 packages/session/session-title/src/index.ts   | 10 +++---
 .../session/session-title/src/invariant.ts    |  5 +--
 .../session-title/tests/invariant.spec.ts     |  4 +--
 .../tests/service-contracts.spec.ts           | 12 +++----
 packages/settings/settings/README.i18n.yaml   |  4 +--
 packages/settings/settings/README.md          |  2 +-
 packages/settings/settings/README.zh.md       |  2 +-
 packages/skill/tool-skill/src/index.ts        |  2 +-
 packages/spill/spill/README.i18n.yaml         |  4 +--
 packages/spill/spill/README.md                |  2 +-
 packages/spill/spill/README.zh.md             |  2 +-
 packages/spill/spill/src/index.ts             |  2 +-
 packages/spill/spill/src/types.ts             |  2 +-
 packages/subagent/subagent/README.i18n.yaml   |  4 +--
 packages/subagent/subagent/README.md          |  8 ++---
 packages/subagent/subagent/README.zh.md       |  8 ++---
 .../subagent/subagent/src/continuation.ts     |  4 +--
 packages/subagent/subagent/src/index.ts       |  2 +-
 packages/subagent/subagent/src/invariant.ts   |  2 +-
 packages/subagent/subagent/src/types.ts       |  4 +--
 .../subagent/subagent/tests/invariant.spec.ts |  2 +-
 .../tool-subagent-control/README.i18n.yaml    |  4 +--
 .../subagent/tool-subagent-control/README.md  |  2 +-
 .../tool-subagent-control/README.zh.md        |  2 +-
 .../tests/tool-subagent-control.spec.ts       |  2 +-
 .../tool-subagent-report/README.i18n.yaml     |  4 +--
 .../subagent/tool-subagent-report/README.md   |  2 +-
 .../tool-subagent-report/README.zh.md         |  2 +-
 .../tests/tool-subagent-report.spec.ts        |  2 +-
 packages/support/invariants/README.i18n.yaml  |  4 +--
 packages/support/invariants/README.md         |  2 +-
 packages/support/invariants/README.zh.md      |  2 +-
 .../llm-replay/tests/llm-replay.spec.ts       |  2 +-
 packages/util/environment/package.json        |  2 +-
 packages/util/environment/src/index.ts        |  4 +--
 packages/workspace/workspace/src/index.ts     |  4 +--
 scripts/gen-doc-graphs.ts                     |  2 +-
 380 files changed, 946 insertions(+), 874 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
 create mode 100644 .agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
index ce26042716..b400a7b6c7 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.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 .agents/notes/implemented/architecture/2026-06-18-session-surface.md
-2026-06-18-session-surface.md: 1bb3baac5e9bea3f657cbd3be2623223bda78ce2
-2026-06-18-session-surface.zh.md: b967ad467e58ed4f4b4009fe4746f1b8b6b22f25
+2026-06-18-session-surface.md: 3a033960e7cbf577c69c1df9940e064ef34163d3
+2026-06-18-session-surface.zh.md: 5c1348595589e8b69b0fe4a679f2536a83ef3142
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
index 1bb3baac5e..3a033960e7 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-18-session-surface.zh.md)
 
 ## Problem
 
-The event log is authoritative, but history manipulation had no durable shared mechanism. Plugins such as compaction would otherwise rewrite derived requests through order-sensitive listeners, leave no provenance, and require repeated changes to `deriveMessages()`.
+The event log is authoritative, but history manipulation had no durable shared mechanism. Without one, plugins such as compaction would rewrite derived requests through order-sensitive listeners without recording which events each replacement used. Every new history manipulation would also require changes to `deriveMessages()`.
 
 ## Decision
 
@@ -16,7 +16,7 @@ Add a **surface** — a derived, cached order of event sequences (the subset of
 
 Every `SessionEvent` gains two optional fields (structural metadata, like `seq`/`time`):
 
-- **`sourceEventSeqs?: number[]`** — seq numbers of events that are provenance sources (e.g., the `assistant/chunk` seqs that built an `assistant/message`, or the surface nodes shadowed by a compaction marker). A present `[]` is valid only on `assistant/message` and records a known empty provider stream; omission there means legacy or otherwise unrecorded provenance. Other surface events require a non-empty list when the field is present. Provenance is a core design principle; without it, the replace-range operation cannot be validated on replay.
+- **`sourceEventSeqs?: number[]`** — seq numbers of earlier events cited as sources (e.g., the `assistant/chunk` seqs that built an `assistant/message`, or the surface nodes shadowed by a compaction marker). A present `[]` is valid only on `assistant/message` and records a known empty provider stream; omission there means a legacy or foreign event did not record the stream. Other surface events require a non-empty list when the field is present. Without these cited seqs, replay cannot validate that a replace-range operation names every event it removed.
 - **`surfaceOp?: SurfaceOp`** — how this event entered the surface. Absent for non-surface events.
 
 ### SurfaceOp: two operations
@@ -49,7 +49,7 @@ The `repair.ts` module synthesizes `tool/result` closers for orphaned tool calls
 
 ### Invariants
 
-`Session` validates `sourceEventSeqs` and `surfaceOp` at the always-on seed/append boundary: only `assistant/message` may use an empty provenance list; references are unique, earlier, and known; replacement endpoints exist in surface order; and provenance covers every shadowed node. These are single-record acceptance and storage-projection rules, not optional invariant-service contributions.
+`Session` validates `sourceEventSeqs` and `surfaceOp` at the always-on seed/append boundary: only `assistant/message` may use an empty source-event list; references are unique, earlier, and known; replacement endpoints exist in surface order; and `sourceEventSeqs` covers every shadowed node. These are single-record acceptance and storage-projection rules, not optional invariant-service contributions.
 
 Every surface-eligible event must carry `surfaceOp` or it would disappear from derived history. Typed `append` overloads enforce this for literal event types; runtime checks in `append` and the seed constructor cover widened unions and loaded logs. Invalid seeds are rejected rather than upgraded under the pre-release format policy.
 
@@ -63,11 +63,11 @@ Every surface-eligible event must carry `surfaceOp` or it would disappear from d
 ## Consequences
 
 - **`packages/core/session`**: `surface.ts` (`SurfaceManager`) maintains one ordered seq array for candidate acceptance and live projection; `SessionSurface` is its readonly public view. `SurfaceOp`/`SurfaceIntent` and the top-level session-event fields record how entries join it. `append()` requires a `SurfaceIntent` for surface events, `deriveMessages()` walks the surface as the sole derivation path, and `repair.ts` emits surface-aware closers. The seed constructor rejects a surface-eligible seed event missing its `surfaceOp` marker (see § Invariants).
-- **`packages/core/agent-loop`**: All surface-capable appends pass surface opts. Chunk seqs are collected for `assistant/message` provenance; `tool/call` seqs are captured for `tool/result` provenance.
+- **`packages/core/agent-loop`**: All surface-capable appends pass surface opts. Each `assistant/message` cites its chunk seqs; each `tool/result` cites its `tool/call` seq.
 - **`packages/session/session-persistence-sqlite`**: Two new nullable TEXT columns (`source_event_seqs`, `surface_op`) on the `events` table; `SCHEMA_VERSION` bumped (bump-and-reject, no migration).
 - **`packages/session/session-persistence-jsonl`**: No changes required.
 - **`packages/session/session-persistence`**: Abstract interface unchanged.
 
 The surface is the foundation for future history manipulation. A compaction or tool-result-prune plugin appends one of the existing message-producing event types (a `user/message` carrying the summary, say) with `surfaceOp: { op: 'replace', start, end }` and `sourceEventSeqs` covering the shadowed entries — the new event takes the range's place on the surface while the plugin's own trace events (e.g. `compaction/start`, `compaction/end`) stay off it. Replay preserves the decision deterministically.
 
-A `tool/result` replacement may rewrite exactly one current `tool/result` and must preserve every data field except `content`. Session acceptance enforces this rule together with positional range and provenance validation, independent of optional diagnostic plugins.
+A `tool/result` replacement may rewrite exactly one current `tool/result` and must preserve every data field except `content`. Session acceptance enforces this rule together with positional range and cited source-event validation, independent of optional diagnostic plugins.
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
index b967ad467e..5c13485955 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-事件日志是权威数据源，但历史操纵此前没有持久化的共享机制。如果没有这样的机制，上下文压缩（context compaction）等插件只能通过顺序敏感的监听器改写派生请求，不留溯源信息，且每次新增操纵都要反复修改 `deriveMessages()`。
+事件日志是权威数据源，但历史操纵此前没有持久化的共享机制。如果没有这样的机制，上下文压缩（context compaction）等插件会通过顺序敏感的监听器改写派生请求，却不记录每次替换使用了哪些事件。每次新增历史操纵时，还必须修改 `deriveMessages()`。
 
 ## 决策
 
@@ -16,7 +16,7 @@ Status: implemented
 
 每个 `SessionEvent` 获得两个可选字段（结构性元数据，与 `seq`/`time` 同级）：
 
-- **`sourceEventSeqs?: number[]`**：作为溯源来源的事件 seq 编号（例如构成 `assistant/message` 的各 `assistant/chunk` 的 seq，或被压缩标记遮蔽的 surface 节点）。出现的 `[]` 只在 `assistant/message` 上有效，表示已知为空的提供方流；在该事件上省略字段表示旧数据或未记录的溯源。其他 surface 事件一旦出现此字段，就必须是非空列表。溯源是核心设计原则；没有它，replace-range 操作在回放时无法被验证。
+- **`sourceEventSeqs?: number[]`**：被引用为数据来源的早期事件 seq 编号（例如构成 `assistant/message` 的各 `assistant/chunk` 的 seq，或被压缩标记遮蔽的 surface 节点）。出现的 `[]` 只在 `assistant/message` 上有效，表示已知为空的提供方流；在该事件上省略字段，表示某个旧事件或外部事件没有记录该流。其他 surface 事件一旦出现此字段，就必须是非空列表。如果没有这些引用的 seq，回放就无法验证 replace-range 操作是否列出了它移除的每个事件。
 - **`surfaceOp?: SurfaceOp`**：该事件如何进入 surface。非 surface 事件不携带此字段。
 
 ### SurfaceOp：两种操作
@@ -49,7 +49,7 @@ export type SurfaceOp =
 
 ### 不变式
 
-`Session` 在始终启用的 seed/append 边界校验 `sourceEventSeqs` 与 `surfaceOp`：只有 `assistant/message` 可以使用空的溯源列表；引用必须唯一、更早且已知；替换端点必须存在于 surface 顺序中；溯源必须覆盖每个被遮蔽的节点。这些是单记录接纳与存储投影规则，不是由可选的不变式服务提供的规则。
+`Session` 在始终启用的 seed/append 边界校验 `sourceEventSeqs` 与 `surfaceOp`：只有 `assistant/message` 可以使用空的源事件列表；引用必须唯一、更早且已知；替换端点必须存在于 surface 顺序中；`sourceEventSeqs` 必须覆盖每个被遮蔽的节点。这些是单记录接纳与存储投影规则，不是由可选的不变式服务提供的规则。
 
 每个可进入 surface 的事件都必须携带 `surfaceOp`，否则它将从派生历史中消失。类型化的 `append` 重载对字面事件类型强制执行此规则；`append` 和种子构造函数中的运行时检查覆盖宽化联合类型和加载的日志。按照预发布格式策略，无效的种子被拒绝而非升级。
 
@@ -63,11 +63,11 @@ export type SurfaceOp =
 ## 后果
 
 - **`packages/core/session`**：`surface.ts`（`SurfaceManager`）维护一个用于候选接纳和实时投影的有序 seq 数组；`SessionSurface` 是其只读公共视图。`SurfaceOp`/`SurfaceIntent` 与顶层会话事件字段记录条目如何加入它。`append()` 要求 surface 事件携带 `SurfaceIntent`，`deriveMessages()` 以遍历 surface 作为唯一派生路径，`repair.ts` 则发出 surface 感知的闭合事件。种子构造函数拒绝缺少 `surfaceOp` 标记的可进入 surface 的种子事件（见「不变式」一节）。
-- **`packages/core/agent-loop`**：所有涉及 surface 事件的追加操作都传入 surface 选项。收集分片 seq 用于 `assistant/message` 溯源；捕获 `tool/call` seq 用于 `tool/result` 溯源。
+- **`packages/core/agent-loop`**：所有涉及 surface 事件的追加操作都传入 surface 选项。每个 `assistant/message` 都引用产生它的分片 seq；每个 `tool/result` 都引用它的 `tool/call` seq。
 - **`packages/session/session-persistence-sqlite`**：`events` 表新增两个可空 TEXT 列（`source_event_seqs`、`surface_op`）；`SCHEMA_VERSION` 递增（bump-and-reject，无迁移）。
 - **`packages/session/session-persistence-jsonl`**：无需改动。
 - **`packages/session/session-persistence`**：抽象接口不变。
 
 Surface 是未来历史操纵的基础。压缩或 tool-result-prune 插件追加一个既有的消息产出事件类型（例如一条携带摘要的 `user/message`），附带 `surfaceOp: { op: 'replace', start, end }` 和覆盖被遮蔽条目的 `sourceEventSeqs`——新事件在 surface 上取代该范围的位置，而插件自身的 trace 事件（如 `compaction/start`、`compaction/end`）不进入 surface。回放以确定性方式保留该决策。
 
-一次 `tool/result` 替换只能改写当前的一个 `tool/result`，并且必须保留除 `content` 以外的每个数据字段。Session 接纳会与位置范围和溯源校验一起强制这条规则，不依赖可选的诊断插件。
+一次 `tool/result` 替换只能改写当前的一个 `tool/result`，并且必须保留除 `content` 以外的每个数据字段。Session 接纳会与位置范围和引用的源事件校验一起强制这条规则，不依赖可选的诊断插件。
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
index b8540c3319..dcfcccc3cf 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.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 .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
-2026-06-21-bounded-llm-request-recovery.md: 587f2d26eee922e91c8797018964f983890eb8ec
-2026-06-21-bounded-llm-request-recovery.zh.md: dfc5e3ab67b62042c37f05199ed39bf47ded0c5d
+2026-06-21-bounded-llm-request-recovery.md: 41f02f977a5fb628d57c162c64f8aaa1c2e6b1c0
+2026-06-21-bounded-llm-request-recovery.zh.md: 3e95865d73e75b8f7ae227ebabe322a21c2b83ae
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
index 587f2d26ee..41f02f977a 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
@@ -115,7 +115,7 @@ If recovery is exhausted, the final failure is stored once on `turn/end.reason`
 - HMR-during-backoff tests prove disposal unregisters the listener, aborts and awaits its captured callbacks, emits no retry decision after disposal, and leaves no timer or promise alive.
 - Pure unit tests cover transient-code selection, exponential backoff and jitter bounds, valid and over-cap `Retry-After`, exhausted budgets, deterministic timer/random seams, and abort during backoff.
 - Real agent-loop tests cover failure before chunks, partial chunks then failure, thrown and in-band failures, retry to success in a new turn, exhaustion to structured `turn/end.reason`, and composition with `dsh-compact-basic` context-overflow recovery.
-- The partial-chunk integration test proves failed chunks remain attributed to the failed step, no assistant message or tool side effect is committed for that step, and the successful retry has distinct provenance.
+- The partial-chunk integration test proves failed chunks remain attributed to the failed step, no assistant message or tool side effect is committed for that step, and the successful retry records its own chunk seqs and provider/model route.
 - The plugin-owned `llm/retry` event is non-surface, survives JSONL and SQLite round trips, is ignored by message derivation, and drives TUI and Web retraction plus scheduled-retry rendering. Client tests cover complete wire validation, clock-independent countdown, cancellation versus completed retry labels, and trajectory attribution; keyless UI snapshots cover Web scheduling and success, a real Web composition test covers partial transport failure through recovery, and ACP automation snapshots confirm that a discarded attempt stays off the wire while the recovered reply is emitted.
 - Idle-watchdog tests prove the stable signal is rearmed only while `next()` is outstanding, disarmed during consumer think time and in `finally`, and classified separately from a total-call deadline and an earlier caller abort; adapter tests prove the signal stops the underlying request rather than merely detaching it.
 - Direct `ctx.llm.stream()` callers remain single-attempt and receive the same structured failure facts.
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
index dfc5e3ab67..3e95865d73 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
@@ -115,7 +115,7 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 - 退避期间执行 HMR 的测试证明：dispose 过程会注销监听器、中止并等待其捕获的回调，dispose 后不发出重试决策，也不留下存活的定时器或 promise。
 - 纯单元测试覆盖暂时性 code 选择、指数退避和抖动边界、有效及超出上限的 `Retry-After`、耗尽的预算、确定性定时器／随机数 seam，以及退避期间中止。
 - 真实 agent-loop 测试覆盖分片前失败、部分分片后失败、抛出及带内失败、在新轮次中重试至成功、耗尽后写入结构化 `turn/end.reason`，以及与 `dsh-compact-basic` 上下文溢出恢复的组合。
-- 部分分片集成测试证明：失败分片仍归属于失败步骤，该步骤不会提交 assistant 消息或工具副作用，成功的重试具有不同的来源信息。
+- 部分分片集成测试证明：失败分片仍归属于失败步骤，该步骤不会提交 assistant 消息或工具副作用，成功的重试会记录自己的分片 seq 和提供方／模型路由。
 - 插件拥有的不进入表层的 `llm/retry` 事件可在 JSONL 和 SQLite 往返后保留，被消息派生忽略，并驱动 TUI 和 Web 撤回及计划重试渲染。客户端测试覆盖完整的 wire 验证、独立于时钟的倒计时、已取消与已完成重试标签的区别以及轨迹归属；无密钥 UI 快照覆盖 Web 的调度与成功，真实 Web 组合测试覆盖部分传输失败直至恢复，ACP 自动化快照确认，被丢弃的尝试不会通过协议发出，而恢复后的回复会正常发出。
 - 空闲看门狗测试证明：只有 `next()` 尚未完成时才会重新布防稳定信号；在消费方思考期间及 `finally` 中会解除布防；它与总调用 deadline 以及更早发生的调用方中止分开分类。适配器测试证明该信号会终止底层请求，而不只是与其脱离。
 - `ctx.llm.stream()` 的直接调用方仍只尝试一次，并收到相同的结构化失败事实。
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
index f80e5c3c77..b242af54ee 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.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 .agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
-2026-07-05-prompt-variables-and-tool-guidance-ownership.md: a3b5021daf323971308760bde4f97651db8edbda
-2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 0b84f188e6637d8b1b42ed2e6df3cd7e4061d75d
+2026-07-05-prompt-variables-and-tool-guidance-ownership.md: 199153741a5677e9f7b9bc6510f7a77b9791343e
+2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 988c128382fd8ff5a8a4742486860d931013ac80
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
index a3b5021daf..199153741a 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
@@ -18,7 +18,7 @@ The assembled system prompt had four defects, all of one family: facts the harne
 
 ## Decision
 
-**One principle: every fact in the prompt has exactly one owner.** The model name and workspace are config/session facts → the harness exposes them as variables and the persona references them. Per-tool semantics and when-to-use → the tool's `description`. Cross-call habits a description cannot carry → the tool package's prompt section. Harness provenance → the static `harness:identity` section. Deployment role and behavior → the deployment's persona.
+**One principle: every fact in the prompt has exactly one owner.** The model name and workspace are config/session facts → the harness exposes them as variables and the persona references them. Per-tool semantics and when-to-use → the tool's `description`. Cross-call habits a description cannot carry → the tool package's prompt section. The product name and SDK identity line → the static `harness:identity` section. Deployment role and behavior → the deployment's persona.
 
 ### Assemble context
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
index 0b84f188e6..988c128382 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 ## 决策
 
-**一条原则：提示词中的每个事实恰好有一个归属方。** 模型名称和工作区是配置/会话事实 → harness 将它们暴露为变量，persona 引用它们。每个工具的语义和何时使用 → 工具的 `description`。description 无法承载的跨调用习惯 → 包的提示词 section。harness 来源标识 → 静态的 `harness:identity` section。部署角色与行为 → 部署的 persona。
+**一条原则：提示词中的每个事实恰好有一个归属方。** 模型名称和工作区是配置/会话事实 → harness 将它们暴露为变量，persona 引用它们。每个工具的语义和何时使用 → 工具的 `description`。description 无法承载的跨调用习惯 → 包的提示词 section。产品名称和 SDK 身份说明 → 静态的 `harness:identity` section。部署角色与行为 → 部署的 persona。
 
 ### 组装上下文
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
index 1b5962f672..9acc4ee6f6 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.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 .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
-2026-07-05-reconstructable-requests.md: ebca9b99cad791159302da9c2bbce9f4df147aab
-2026-07-05-reconstructable-requests.zh.md: e7ed83bbc553e86d53d88e442b0fd8992973c9e7
+2026-07-05-reconstructable-requests.md: 3676e4bc7f6d0272f382b13e178f04b16f18f992
+2026-07-05-reconstructable-requests.zh.md: bcae6b941fb0110aa4e5011685365a5edf7512d3
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
index ebca9b99ca..3676e4bc7f 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
@@ -30,9 +30,9 @@ Each proposed step first claims its inbox batch and runs `agent/pre-step`. Rejec
 
 **Enforcement.** The `dsh-agent-loop/invariant` companion registers with `ctx.invariants` and, when selected, independently rebuilds each loop request through a fresh `Session`, so the live cache cannot vouch for itself, then compares messages and folded header fields at `llm/stream`. The loop records the exact frozen request through `markAgentLoopRequest()` in `dsh-llm`; the process-local identity lets the companion and other request observers recognize conversation work, while direct one-shots remain excluded regardless of their frozen shape or session id. Correctness depends on sequence-bounded reconstruction rather than listener order. A with-key e2e requires positive cache-read tokens after the first request; per-step usage is the production signal, and a header change or compaction appears as a cache-read drop on the next step.
 
-### The MiniCode shape: adopted, with the provenance arrow inverted
+### The MiniCode shape: adopted, with the event log as the source
 
-Like MiniCode, the conversation advances append-only and resets only when model-visible state changes. Unlike MiniCode, the event log remains the source of truth because it also owns persistence, recovery, boundaries, tool pairing, and provenance. `Session` caches message and header folds derived from that log, making every request independently checkable.
+Like MiniCode, the conversation advances append-only and resets only when model-visible state changes. Unlike MiniCode, the event log remains the source of truth because it also owns persistence, recovery, boundaries, tool pairing, and links from derived events to their inputs. `Session` caches message and header folds derived from that log, making every request independently checkable.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
index e7ed83bbc5..bcae6b941f 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
@@ -30,9 +30,9 @@ Status: implemented
 
 **强制执行。** `dsh-agent-loop/invariant` 配套插件向 `ctx.invariants` 注册，并在被选用时通过一个全新的 `Session` 独立重建每个循环请求，使活跃缓存无法为自身背书，然后在 `llm/stream` 处比较消息和折叠后的 header 字段。循环通过 `dsh-llm` 的 `markAgentLoopRequest()` 记录精确的冻结请求；这一进程内标识让配套插件和其他请求观察者识别对话工作，而直接的一次性调用无论其冻结形状或会话 id 如何都保持排除。正确性依赖于序列有界的重建，而非监听器顺序。带密钥的 e2e 要求首次请求之后有正值的 cache-read token；逐步骤用量是生产信号，header 变更或压缩表现为下一步骤的 cache-read 下降。
 
-### MiniCode 形态：采纳，但溯源箭头反转
+### MiniCode 形态：采纳，以事件日志为真源
 
-与 MiniCode 相同，对话仅追加推进，仅在模型可见状态变更时重置。与 MiniCode 不同，事件日志仍是真源，因为它同时拥有持久化、恢复、边界、工具配对和溯源。`Session` 缓存从日志推导的消息和 header 折叠结果，使每个请求都可独立检查。
+与 MiniCode 相同，对话仅追加推进，仅在模型可见状态变更时重置。与 MiniCode 不同，事件日志仍是真源，因为它同时拥有持久化、恢复、边界、工具配对，并记录派生事件到其输入事件的关联。`Session` 缓存从日志推导的消息和 header 折叠结果，使每个请求都可独立检查。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
index 03acf306b4..2330a5df0c 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.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 .agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 6fbd5e2c9d57da3f25c72c652ca50eb45b84323c
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 8a480999038cf892842290e3ea3902683d87e431
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 6f18d5da014f35b47c40c541ca75ca5ab81499b2
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 7b6ce75b145e96e58a49331e0390f1d3f82200e4
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
index 6fbd5e2c9d..6f18d5da01 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
@@ -32,7 +32,7 @@ If cancellation lands after assistant tool calls are durable but before all call
 
 `CompactService.compactIfNeeded(agent, trigger, signal)` accepts `trigger: 'pressure' | 'context-overflow'`. The interface gains no estimation methods or token types; `ctx.tokenMeter` remains the reusable accounting owner.
 
-For `pressure`, compact-basic resolves the durable provider/model target's adapter-owned capacity and exact-target policy, then applies the resulting threshold and retained-tail budgets to one unified `ctx.tokenMeter.measure()` result. Below pressure it returns without pruning. Once pressure qualifies, optional `ctx.toolResultPrune` rewrites oversized current results and compact-basic remeasures through the same meter; safe pressure skips the model call, while remaining pressure selects and summarizes from the pruned surface. The same singleton meter owns range pricing, provenance, shadowed token counts, and non-shrinking-summary rejection. Common defaults remain threshold ratio `0.8`, retained-history ratio `0.16`, summarization provider/model `''`, `maxTokens: 8192`, `compactionRetries: 1`, and `auto: true`; optional `modelPolicies` entries override them for an exact provider/model pair.
+For `pressure`, compact-basic resolves the durable provider/model target's adapter-owned capacity and exact-target policy, then applies the resulting threshold and retained-tail budgets to one unified `ctx.tokenMeter.measure()` result. Below pressure it returns without pruning. Once pressure qualifies, optional `ctx.toolResultPrune` rewrites oversized current results and compact-basic remeasures through the same meter; safe pressure skips the model call, while remaining pressure selects and summarizes from the pruned surface. The same singleton meter owns range pricing, cited source-event accounting, shadowed token counts, and non-shrinking-summary rejection. Common defaults remain threshold ratio `0.8`, retained-history ratio `0.16`, summarization provider/model `''`, `maxTokens: 8192`, `compactionRetries: 1`, and `auto: true`; optional `modelPolicies` entries override them for an exact provider/model pair.
 
 For canonical overflow, compact-basic requires no capacity metadata and bypasses scalar pressure and the normal retained-token budget. It prunes first, then chooses the maximal tool-balanced head range while leaving the newest indivisible unit and attempts one shrinking summary compaction under the same signal when a range exists. The automatic listener snapshots `session.surface.replaceGeneration` and returns `{ kind: 'retry' }` whenever pruning or summarization increases it. This remains true when pruning lands before later summary work throws; cancellation still wins. A backend returning a result without replacement cannot authorize retry, while pruning-only progress can authorize a retry without a `CompactionResult`.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
index 8a48099903..7b6ce75b14 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
@@ -32,7 +32,7 @@ Compact-basic 会在每个拟议请求之前包装 `agent/pre-step`。在续步
 
 `CompactService.compactIfNeeded(agent, trigger, signal)` 接收 `trigger: 'pressure' | 'context-overflow'`。接口不增加估算方法或 token 类型；`ctx.tokenMeter` 继续作为可复用的核算所有者。
 
-对于 `pressure`，compact-basic 先解析持久提供方/模型目标对应适配器所维护的容量与精确目标策略，再把得到的阈值与保留尾部预算应用到一次统一的 `ctx.tokenMeter.measure()` 结果。未达到压力阈值时直接返回，不执行剪枝。压力达到条件后，可选的 `ctx.toolResultPrune` 会改写当前表层中过大的工具结果，compact-basic 再通过同一个 meter 重新计量；若压力已降至安全水平则跳过模型调用，否则从已剪枝表层选择范围并生成摘要。范围定价、来源、被遮蔽 token 数与非缩小摘要拒绝也由同一个单例 meter 完成。通用默认值保持为阈值比例 `0.8`、保留历史比例 `0.16`、摘要提供方/模型 `''`、`maxTokens: 8192`、`compactionRetries: 1` 与 `auto: true`；可选 `modelPolicies` 项可以按精确提供方/模型组合覆盖这些值。
+对于 `pressure`，compact-basic 先解析持久提供方/模型目标对应适配器所维护的容量与精确目标策略，再把得到的阈值与保留尾部预算应用到一次统一的 `ctx.tokenMeter.measure()` 结果。未达到压力阈值时直接返回，不执行剪枝。压力达到条件后，可选的 `ctx.toolResultPrune` 会改写当前表层中过大的工具结果，compact-basic 再通过同一个 meter 重新计量；若压力已降至安全水平则跳过模型调用，否则从已剪枝表层选择范围并生成摘要。范围定价、引用的源事件计量、被遮蔽 token 数与非缩小摘要拒绝也由同一个单例 meter 完成。通用默认值保持为阈值比例 `0.8`、保留历史比例 `0.16`、摘要提供方/模型 `''`、`maxTokens: 8192`、`compactionRetries: 1` 与 `auto: true`；可选 `modelPolicies` 项可以按精确提供方/模型组合覆盖这些值。
 
 对于规范化溢出，compact-basic 不要求容量元数据，并绕过标量压力与普通保留 token 预算。它先执行剪枝，再在保留最新不可分割单元的同时选择最大的工具配对平衡头部范围；存在范围时，才在同一 signal 下尝试一次缩小摘要压缩。自动监听器先记录 `session.surface.replaceGeneration`，剪枝或摘要让 generation 增加时就返回 `{ kind: 'retry' }`。即使剪枝先落盘而后续摘要工作抛错，这条规则仍然成立；取消依然优先。后端若只返回结果但没有替换表层，不能授权重试；只有剪枝取得进展时，即使没有 `CompactionResult` 也可以授权重试。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
index 2d39db2332..6ed066b24a 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.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 .agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
-2026-07-14-provider-routed-llm-adapters.md: 9039334370ba5d71eb71879970c2e572a5b023df
-2026-07-14-provider-routed-llm-adapters.zh.md: eff33496e1a61472534009533270f8f943ccc1f8
+2026-07-14-provider-routed-llm-adapters.md: bb516a39b6c7303d125575bbd3d4138f9af65f7d
+2026-07-14-provider-routed-llm-adapters.zh.md: 2b6af0d509c28cb79dcd3342a007be8e54799ebc
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
index 9039334370..bb516a39b6 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
@@ -10,7 +10,7 @@ English | [中文](2026-07-14-provider-routed-llm-adapters.zh.md)
 
 The conflation prevents a provider gateway from serving an open-ended model catalog. OpenRouter, for example, is one provider with many model ids, while a private OpenAI-compatible endpoint may add models without changing the Harness plugin tree. Every newly selected model currently needs to have been registered during plugin startup. The same model id can also exist at multiple providers, so model-only registration cannot state which provider the caller intended.
 
-`dsh-llm-pi-ai` exposed none of pi-ai's provider abstraction. It constructed an inline DeepSeek `openai-completions` model, applied DeepSeek-specific payload patches, and stamped every replayed assistant message as DeepSeek. pi-ai itself has a provider/model catalog, selects APIs such as `openai-responses`, `anthropic-messages`, and `google-generative-ai`, and preserves provider-specific response ids and reasoning/tool signatures for later turns. The Harness conversion dropped that provenance, so simply replacing the inline model with a catalog lookup would have made same-model replay and cross-provider handoff incomplete.
+`dsh-llm-pi-ai` exposed none of pi-ai's provider abstraction. It constructed an inline DeepSeek `openai-completions` model, applied DeepSeek-specific payload patches, and stamped every replayed assistant message as DeepSeek. pi-ai itself has a provider/model catalog, selects APIs such as `openai-responses`, `anthropic-messages`, and `google-generative-ai`, and preserves provider-specific response ids and reasoning/tool signatures for later turns. The Harness conversion dropped the provider/model route and provider response fields, so simply replacing the inline model with a catalog lookup would have made same-model replay and cross-provider handoff incomplete.
 
 The adapter configuration also assumes one DeepSeek API key and endpoint. A generic backend needs independent credentials and endpoint overrides per provider while leaving AWS, Google ADC, OAuth, and other ambient authentication mechanisms to pi-ai.
 
@@ -36,15 +36,15 @@ The adapter calls pi-ai's `streamSimple()` so each catalog model chooses its reg
 
 pi-ai's common stream options do not expose stop sequences. `dsh-llm-pi-ai` rejects a defined Harness `stop` option with `UNSUPPORTED_OPTION` rather than silently ignoring it or growing a second provider-specific payload implementation. `dsh-llm-deepseek` continues to support `stop` through its native request serializer.
 
-### Durable assistant provenance and replay state
+### Recorded assistant route and replay state
 
-Assistant messages carry provider-neutral provenance containing the request's `provider` and `model`, plus an optional JSON-serializable adapter replay state. A successful `assistant/message` session event records this provenance and `deriveMessages()` returns it with the assistant message. User, system, context, and tool-result messages carry no assistant provenance. The provider/model fields are authoritative loop data; an adapter owns only its opaque replay-state payload.
+Assistant messages carry the request's `provider` and `model`, plus an optional JSON-serializable adapter replay state. A successful `assistant/message` session event records those fields and `deriveMessages()` returns them with the assistant message. User, system, context, and tool-result messages carry no assistant route fields. The provider/model fields are authoritative loop data; an adapter owns only its opaque replay-state payload.
 
-A terminal successful `finish` chunk may carry replay state, and `BlockAssembler` retains it alongside usage and finish reason. The loop attaches that state to the assembled assistant provenance without exposing a response-rewrite hook. Error and aborted responses do not produce a normal assistant message and therefore do not enter future model history.
+A terminal successful `finish` chunk may carry replay state, and `BlockAssembler` retains it alongside usage and finish reason. The loop attaches that state to the assembled assistant message's model source without exposing a response-rewrite hook. Error and aborted responses do not produce a normal assistant message and therefore do not enter future model history.
 
-The pi-ai replay state is a versioned, minimal projection of its successful `AssistantMessage`: source API/provider/model, response id/model, stop reason, and index-aligned text, thinking, and tool-call signatures. It does not duplicate text or tool arguments already carried by Harness content blocks, and it omits diagnostics, timestamps, usage, and errors. On a later request, `LlmService` gives replay state to the target adapter only when the historical provider and target provider are currently owned by the same adapter instance. That adapter combines the logged Harness content with replay state when it can restore the historical response, and owns any required cross-model or cross-provider conversion. An adapter receiving replay state with an unknown version or mismatched block shape fails explicitly; a different adapter receives only provider-neutral content and provenance.
+The pi-ai replay state is a versioned, minimal projection of its successful `AssistantMessage`: source API/provider/model, response id/model, stop reason, and index-aligned text, thinking, and tool-call signatures. It does not duplicate text or tool arguments already carried by Harness content blocks, and it omits diagnostics, timestamps, usage, and errors. On a later request, `LlmService` gives replay state to the target adapter only when the historical provider and target provider are currently owned by the same adapter instance. That adapter combines the logged Harness content with replay state when it can restore the historical response, and owns any required cross-model or cross-provider conversion. An adapter receiving replay state with an unknown version or mismatched block shape fails explicitly; a different adapter receives only provider-neutral content plus provider/model fields.
 
-This state is model-visible replay input and therefore follows the existing [reconstructable-request rule](2026-07-05-reconstructable-requests.md): it is present in both the terminal `finish` chunk and the assembled `assistant/message` provenance that drives derivation. Resume and fork preserve it verbatim. Compaction that shadows the assistant message also removes its replay state from the active surface; the summary is ordinary provider-neutral content.
+This state is model-visible replay input and therefore follows the existing [reconstructable-request rule](2026-07-05-reconstructable-requests.md): it is present in both the terminal `finish` chunk and the assembled `assistant/message` model source that drives derivation. Resume and fork preserve it verbatim. Compaction that shadows the assistant message also removes its replay state from the active surface; the summary is ordinary provider-neutral content.
 
 ### Propagate the target through every request producer
 
@@ -54,7 +54,7 @@ Compaction configuration gains `summarizationProvider` beside `summarizationMode
 
 The JSON-RPC runtime receives provider and model explicitly. Its convenience fallback mounts `dsh-llm-deepseek` only for provider `deepseek` when that provider has no registered owner; other missing providers fail without guessing an adapter.
 
-The on-disk session format remains the pre-release pinned version `0`, with no compatibility promise. Seed/load validation rejects request headers lacking provider and assistant messages lacking required provenance instead of accepting an old shape that can no longer reconstruct the request.
+The on-disk session format remains the pre-release pinned version `0`, with no compatibility promise. Seed/load validation rejects request headers and assistant messages that omit required provider/model fields instead of accepting an old shape that can no longer reconstruct the request.
 
 ## Alternatives considered
 
@@ -78,7 +78,7 @@ The on-disk session format remains the pre-release pinned version `0`, with no c
 - pi-ai credentials, transport knobs, SDK timeouts, and the five-minute-default `streamIdleTimeoutMs` watchdog are scoped per provider profile. Hidden provider retries are disabled; bounded retries belong to the separately composed agent recovery policy.
 - `dsh-llm-pi-ai` rejects stop sequences because pi-ai's common stream API cannot express them; the native DeepSeek adapter retains its stop support.
 - Replay state is portable only within the adapter instance that owns both the historical and target providers. Cross-provider and cross-model restoration is an adapter responsibility, and another adapter receives provider-neutral history without the opaque state.
-- Current pre-release session JSONL requires provider/model request headers and assistant provenance. Older shapes remain version `0` but are rejected rather than migrated.
+- Current pre-release session JSONL requires provider/model on request headers and assistant messages. Older shapes remain version `0` but are rejected rather than migrated.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
index eff33496e1..2b6af0d509 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 这种混淆使提供方网关无法提供开放的模型目录。例如，OpenRouter 是一个包含大量模型 ID 的提供方，私有 OpenAI 兼容端点也可能在不修改 Harness 插件树的情况下增加模型。目前，每个新选择的模型都必须在插件启动期间完成注册。同一个模型 ID 还可能存在于多个提供方中，因此仅按模型注册无法表达调用方预期使用的提供方。
 
-`dsh-llm-pi-ai` 没有暴露 pi-ai 的提供方抽象。它以内联方式构造 DeepSeek `openai-completions` 模型，应用 DeepSeek 专用的 payload 补丁，并将每条回放的助手消息标记为 DeepSeek。pi-ai 自身提供提供方/模型目录，能够选择 `openai-responses`、`anthropic-messages`、`google-generative-ai` 等 API，并保留提供方专用的响应 ID，以及后续轮次所需的推理和工具签名。Harness 转换丢弃了这些来源信息，因此仅将内联模型替换为目录查询，会导致同模型回放与跨提供方移交不完整。
+`dsh-llm-pi-ai` 没有暴露 pi-ai 的提供方抽象。它以内联方式构造 DeepSeek `openai-completions` 模型，应用 DeepSeek 专用的 payload 补丁，并将每条回放的助手消息标记为 DeepSeek。pi-ai 自身提供提供方/模型目录，能够选择 `openai-responses`、`anthropic-messages`、`google-generative-ai` 等 API，并保留提供方专用的响应 ID，以及后续轮次所需的推理和工具签名。Harness 转换丢弃了提供方／模型路由和提供方响应字段，因此仅将内联模型替换为目录查询，会导致同模型回放与跨提供方移交不完整。
 
 适配器配置同样假定只存在一个 DeepSeek API 密钥和端点。通用后端需要为各提供方分别配置凭据和端点覆盖，同时继续由 pi-ai 处理 AWS、Google ADC、OAuth 等环境认证机制。
 
@@ -36,15 +36,15 @@ Status: implemented
 
 pi-ai 的通用流选项不支持停止序列。若 Harness `stop` 选项已定义，`dsh-llm-pi-ai` 会以 `UNSUPPORTED_OPTION` 拒绝请求，不会静默忽略，也不会增加第二套提供方专用 payload 实现。`dsh-llm-deepseek` 继续通过原生请求序列化器支持 `stop`。
 
-### 持久化助手来源信息与回放状态
+### 已记录的助手路由与回放状态
 
-助手消息携带提供方无关的来源信息，其中包含请求的 `provider` 和 `model`，以及可选的 JSON 可序列化适配器回放状态。成功的 `assistant/message` 会话事件记录这些来源信息，`deriveMessages()` 返回助手消息时也会包含这些信息。用户、system、context 与工具结果消息不携带助手来源信息。provider/model 字段是 agent loop 的权威数据；适配器仅拥有其不透明回放状态 payload。
+助手消息携带请求的 `provider` 和 `model`，以及可选的 JSON 可序列化适配器回放状态。成功的 `assistant/message` 会话事件记录这些字段，`deriveMessages()` 返回助手消息时也会包含它们。用户、system、context 与工具结果消息不携带助手路由字段。provider/model 字段是 agent loop 的权威数据；适配器仅拥有其不透明回放状态 payload。
 
-成功的终止 `finish` 分片可以携带回放状态，`BlockAssembler` 会将其与 token 用量和结束原因一起保留。只有当 `agent/step-result` 处理后的内容与提供方组装输出在结构上相等时，agent loop 才会把回放状态附加到助手来源信息。监听器重写内容后，provider/model 来源信息仍会保留，但已经陈旧的回放状态会被移除。错误或中止响应不会生成正常助手消息，因此不会进入后续模型历史。
+成功的终止 `finish` 分片可以携带回放状态，`BlockAssembler` 会将其与 token 用量和结束原因一起保留。agent loop 会把该状态附加到已组装助手消息的模型来源中，但不公开响应改写钩子。错误或中止响应不会生成正常助手消息，因此不会进入后续模型历史。
 
-pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包含源 API/provider/model、响应 ID/model、停止原因，以及按索引对齐的文本、thinking 和工具调用签名。它不会重复 Harness 内容块中已有的文本或工具参数，也不包含诊断信息、时间戳、用量或错误。后续请求中，只有历史提供方和目标提供方当前归同一个适配器实例所有时，`LlmService` 才会把回放状态交给目标适配器。适配器在能够恢复历史响应时，将 Harness 记录的内容与回放状态组合，并负责所需的跨模型或跨提供方转换。适配器收到未知版本或块形状不匹配的回放状态时会显式失败；其他适配器只能收到提供方无关的内容与来源信息。
+pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包含源 API/provider/model、响应 ID/model、停止原因，以及按索引对齐的文本、thinking 和工具调用签名。它不会重复 Harness 内容块中已有的文本或工具参数，也不包含诊断信息、时间戳、用量或错误。后续请求中，只有历史提供方和目标提供方当前归同一个适配器实例所有时，`LlmService` 才会把回放状态交给目标适配器。适配器在能够恢复历史响应时，将 Harness 记录的内容与回放状态组合，并负责所需的跨模型或跨提供方转换。适配器收到未知版本或块形状不匹配的回放状态时会显式失败；其他适配器只能收到提供方无关的内容以及 provider/model 字段。
 
-该状态属于模型可见的回放输入，因此遵循现有的[请求可重建规则](2026-07-05-reconstructable-requests.md)：它同时存在于终止 `finish` 分片和驱动派生的已组装 `assistant/message` 来源信息中。恢复和 fork 会原样保留该状态。压缩（compaction）遮蔽助手消息时，也会从活动 surface 中移除其回放状态；摘要属于普通的提供方无关内容。
+该状态属于模型可见的回放输入，因此遵循现有的[请求可重建规则](2026-07-05-reconstructable-requests.md)：它同时存在于终止 `finish` 分片和驱动派生的已组装 `assistant/message` 模型来源中。恢复和 fork 会原样保留该状态。压缩（compaction）遮蔽助手消息时，也会从活动 surface 中移除其回放状态；摘要属于普通的提供方无关内容。
 
 ### 在所有请求生产方中传播目标
 
@@ -54,7 +54,7 @@ pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包
 
 JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方没有注册所有者时，其便利回退才会挂载 `dsh-llm-deepseek`；其他缺失的提供方会直接失败，不会猜测适配器。
 
-磁盘会话格式仍使用预发布阶段固定的版本 `0`，且不承诺兼容性。seed/load 验证会拒绝缺少 provider 的请求头，以及缺少必需来源信息的助手消息，不会接受已无法重建请求的旧格式。
+磁盘会话格式仍使用预发布阶段固定的版本 `0`，且不承诺兼容性。seed/load 验证会拒绝省略必需 provider/model 字段的请求头和助手消息，不会接受已无法重建请求的旧格式。
 
 ## 考虑过的替代方案
 
@@ -78,7 +78,7 @@ JSON-RPC 运行时显式接收 provider 与 model。仅当 `deepseek` 提供方
 - pi-ai 凭据、传输选项、SDK 超时，以及默认五分钟的 `streamIdleTimeoutMs` 空闲超时机制均按提供方配置隔离。系统禁用隐藏的提供方重试；有界重试由单独组合的 agent 恢复策略负责。
 - pi-ai 的通用流 API 无法表达停止序列，因此 `dsh-llm-pi-ai` 会拒绝停止序列；原生 DeepSeek 适配器仍支持停止序列。
 - 仅当历史提供方与目标提供方归同一个适配器实例所有时，回放状态才可移植。适配器负责跨提供方和跨模型恢复；其他适配器只接收不含不透明状态的提供方无关历史。
-- 当前预发布会话 JSONL 要求请求头包含 provider/model，助手消息包含来源信息。旧格式仍使用版本 `0`，但会被拒绝，不执行迁移。
+- 当前预发布会话 JSONL 要求请求头和助手消息都包含 provider/model。旧格式仍使用版本 `0`，但会被拒绝，不执行迁移。
 
 ## 测试
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml
index 80fe86f2bc..8579c7231a 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.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 .agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
-2026-07-15-replay-token-meter-service.md: c0f4b467ad0013dd4ac0a0301281b011ea8c261c
-2026-07-15-replay-token-meter-service.zh.md: c1d81dc0e76ee687ced5c23d26197627551e1ced
+2026-07-15-replay-token-meter-service.md: 4013cc92f67597a9b87edfc97d14c7f47f0523ac
+2026-07-15-replay-token-meter-service.zh.md: 4bee27db2a7d021b25dfdf1feefa148cfb016100
diff --git a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
index c0f4b467ad..4013cc92f6 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-15-replay-token-meter-service.zh.md)
 
 Context pressure is useful outside compaction. A compaction backend, an overflow guard, or a future request-policy plugin can all need the same answer: how many tokens does the durable request consume? Keeping that fold inside `dsh-compact-basic` duplicates replay logic, makes measurement unavailable without compaction, and encourages callers to reuse stale accounting.
 
-Provider usage is not a complete answer. It describes one successful call under one exact request envelope, while the current surface can grow, shrink, or be replaced afterward. Sessions also switch providers and models, old logs can lack chunk provenance, and usage fields separate input, cache-read, cache-write, output, and reasoning counts. A useful service therefore combines the latest exact anchor with conservative heuristic repricing and exposes the log revision consumed by each result.
+Provider usage is not a complete answer. It describes one successful call under one exact request envelope, while the current surface can grow, shrink, or be replaced afterward. Sessions also switch providers and models, old logs can omit the chunk seqs behind an assistant message, and usage fields separate input, cache-read, cache-write, output, and reasoning counts. A useful service therefore combines the latest exact anchor with conservative heuristic repricing and exposes the log revision consumed by each result.
 
 ## Decision
 
@@ -20,17 +20,17 @@ The service has no configuration. Estimation uses a fixed four-characters-per-to
 
 ### Per-session replay folds
 
-Each session owns one isolated incremental fold. Active folds advance from `session/event`; every read catches up through the durable tail, so listener ordering, seeded sessions, and service reload do not change the answer. The fold tracks canonical full request-header snapshots, step boundaries, surface appends and replacements, assistant usage, and assistant-chunk provenance. A malformed next event fails transactionally and remains unread rather than partially mutating state.
+Each session owns one isolated incremental fold. Active folds advance from `session/event`; every read catches up through the durable tail, so listener ordering, seeded sessions, and service reload do not change the answer. The fold tracks canonical full request-header snapshots, step boundaries, surface appends and replacements, assistant usage, and the chunk seqs cited by each assistant message. A malformed next event fails transactionally and remains unread rather than partially mutating state.
 
 `measure(session, requestHeader?)` synchronizes the fold once and returns scalar pressure together with positional per-node prices. `totalTokens` remains request-and-response pressure; `surfaceTokens` is the surface-only heuristic total and equals the sum of `nodes[].tokens`. A `requestHeader` override changes pressure pricing only, while the surface fields always describe the current session. `estimateMessage(message)` applies the fixed heuristic without session state. Each result is one detached, deeply immutable snapshot carrying one `logRevision`. Every measurement clones the current nodes and is therefore O(surface).
 
 Provider usage is reused only when the measured canonical request envelope equals the latest successful-call anchor. Any provider, model, system, prefix, tool, or call-config change causes complete heuristic repricing. Surface changes remain a signed delta from a matching anchor, including negative values after a shrinking replacement. A later successful request replaces the earlier anchor, including across provider or model switches.
 
-Usage sums the disjoint input, cache-read, cache-write, and output buckets. Reasoning is not added a second time. Every successful model call records an `assistant/message`, including content-less and max-token calls, with its exact earlier chunk seqs. An explicit empty provenance list means a known empty provider stream; absent legacy provenance conservatively treats the durable assistant output as provider output.
+Usage sums the disjoint input, cache-read, cache-write, and output buckets. Reasoning is not added a second time. Every successful model call records an `assistant/message`, including content-less and max-token calls, with its exact earlier chunk seqs. An explicit empty `sourceEventSeqs` list means a known empty provider stream; an absent legacy list conservatively treats the durable assistant output as provider output.
 
 ### Compact-basic consumes, but does not own, measurement
 
-`dsh-compact-basic` requires `ctx.tokenMeter`; `CompactService` gains no token methods or types. Configuration, the region transaction, and summarization stay in separate modules; the service registers automatic listeners itself, while `summarize()` remains its sole subclass hook. The singleton meter consistently prices pressure, retention, shadowed content, provenance, and non-shrinking-summary rejection.
+`dsh-compact-basic` requires `ctx.tokenMeter`; `CompactService` gains no token methods or types. Configuration, the region transaction, and summarization stay in separate modules; the service registers automatic listeners itself, while `summarize()` remains its sole subclass hook. The singleton meter consistently prices pressure, retention, shadowed content, cited source events, and non-shrinking-summary rejection.
 
 Automatic compaction uses one unified measurement for each threshold-and-retention decision. The region transaction measures after appending its durable `compact/start` lock and again after asynchronous summarization, then compares the detached surface-node vectors. An intervening surface mutation prevents replacement; `logRevision` may advance for unrelated log-only facts without invalidating an unchanged selected span.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md
index c1d81dc0e7..4bee27db2a 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 上下文压力并不只对压缩（compaction）有用。压缩后端、溢出保护或未来的请求策略插件都可能需要回答同一个问题：持久请求消耗了多少 token？如果把该折叠逻辑留在 `dsh-compact-basic` 内部，就会重复实现回放逻辑，使未加载压缩的调用方无法使用计量，并诱使调用方复用陈旧的核算结果。
 
-提供方 usage 也不是完整答案。它只描述某个精确请求信封下的一次成功调用，而当前表层之后还可能增长、缩小或被替换。会话也可能切换提供方与模型，旧日志可能缺少分片来源，usage 字段还会分别报告输入、缓存读取、缓存写入、输出与推理计数。因此，可用的服务必须把最新精确锚点与保守的启发式重新定价结合起来，并公开每个结果已经消费的日志修订号。
+提供方 usage 也不是完整答案。它只描述某个精确请求信封下的一次成功调用，而当前表层之后还可能增长、缩小或被替换。会话也可能切换提供方与模型，旧日志可能缺少构成 assistant 消息的分片 seq，usage 字段还会分别报告输入、缓存读取、缓存写入、输出与推理计数。因此，可用的服务必须把最新精确锚点与保守的启发式重新定价结合起来，并公开每个结果已经消费的日志修订号。
 
 ## 决策
 
@@ -20,17 +20,17 @@ Status: implemented
 
 ### 逐会话回放折叠
 
-每个会话都有一个隔离的增量折叠。活跃折叠通过 `session/event` 前进；每次读取都会追到持久日志尾部，因此监听器顺序、种子会话与服务重载不会改变答案。折叠跟踪规范的完整请求头快照、步骤边界、表层追加与替换、assistant usage，以及 assistant 分片来源。下一个畸形事件会以事务方式失败并保持未读，不会让状态只修改一半。
+每个会话都有一个隔离的增量折叠。活跃折叠通过 `session/event` 前进；每次读取都会追到持久日志尾部，因此监听器顺序、种子会话与服务重载不会改变答案。折叠跟踪规范的完整请求头快照、步骤边界、表层追加与替换、assistant usage，以及每条 assistant 消息引用的分片 seq。下一个畸形事件会以事务方式失败并保持未读，不会让状态只修改一半。
 
 `measure(session, requestHeader?)` 只同步一次折叠，并在返回标量压力的同时给出逐位置节点价格。`totalTokens` 仍表示请求与响应压力；`surfaceTokens` 是仅针对表层的启发式总量，并等于 `nodes[].tokens` 之和。`requestHeader` 覆盖只改变压力定价，表层字段始终描述当前会话。`estimateMessage(message)` 不依赖会话状态，直接应用固定启发式规则。每个结果都是一个分离且深度不可变的快照，只携带一个 `logRevision`。每次计量都会复制当前节点，因此成本为 O(surface)。
 
 只有当待计量的规范请求信封等于最近一次成功调用的锚点时，服务才复用提供方 usage。提供方、模型、系统提示词、前缀、工具或调用配置任一变化都会触发完整的启发式重新定价。表层变化相对匹配锚点保留有符号增量，包括缩小替换后的负值。后续成功请求会替换先前锚点，提供方或模型切换时也一样。
 
-Usage 会对互不重叠的输入、缓存读取、缓存写入与输出 bucket 求和，不会再次加入推理计数。每次成功模型调用都会记录 `assistant/message`，包括无内容调用与达到 token 上限的调用，并带上精确的更早分片 seq。显式空来源列表表示已知为空的提供方流；旧日志中缺失的来源则保守地把持久 assistant 输出视为提供方输出。
+Usage 会对互不重叠的输入、缓存读取、缓存写入与输出 bucket 求和，不会再次加入推理计数。每次成功模型调用都会记录 `assistant/message`，包括无内容调用与达到 token 上限的调用，并带上精确的更早分片 seq。显式的空 `sourceEventSeqs` 列表表示已知为空的提供方流；旧日志中缺失的列表则保守地把持久 assistant 输出视为提供方输出。
 
 ### compact-basic 消费计量，但不拥有计量
 
-`dsh-compact-basic` 要求 `ctx.tokenMeter`；`CompactService` 不增加 token 方法或类型。配置、区域事务与摘要分别保留在独立模块中，服务自身注册自动监听器，而 `summarize()` 仍是唯一的子类钩子。单例计量器一致用于压力、保留、被遮蔽内容、来源以及非缩小摘要拒绝的定价。
+`dsh-compact-basic` 要求 `ctx.tokenMeter`；`CompactService` 不增加 token 方法或类型。配置、区域事务与摘要分别保留在独立模块中，服务自身注册自动监听器，而 `summarize()` 仍是唯一的子类钩子。单例计量器一致用于压力、保留、被遮蔽内容、引用的源事件以及非缩小摘要拒绝的定价。
 
 自动压缩的每次阈值与保留联合决策只使用一次统一计量。区域事务会在追加持久 `compact/start` 锁后执行计量，在异步摘要完成后再次计量，随后比较分离的表层节点向量。期间发生的表层变更会阻止替换；`logRevision` 可以因无关的纯日志事实而推进，而不会使未变的选定范围失效。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
index 291a3f3ce1..ad5f67e601 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.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 .agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
-2026-07-19-package-owned-invariant-service.md: e32efe9f6b3ce6b782c61db56d928e87c160dc9a
-2026-07-19-package-owned-invariant-service.zh.md: abb77cfc2dc4c15510baf0b205cefdbf3c890041
+2026-07-19-package-owned-invariant-service.md: 6ab53f1a9bfa043f17875fa179a99b832b3fcf1a
+2026-07-19-package-owned-invariant-service.zh.md: 378b730c479eed05a2ad11e6a6e084929ec09653
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
index e32efe9f6b..6ab53f1a9b 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
@@ -102,4 +102,4 @@ Every Vitest configuration loads a test host that mounts an explicitly enabled s
 - One selected executable contribution adds one child fiber and its listener/state cost; a selected empty contribution has no listener or trace-state cost, while filtered registrations retain only name ownership.
 - Regex sources are deployment configuration and remain fixed until the service reloads.
 - Ordinary Vitest roots install the owning test package's selected companion; one exhaustive topology pays the full child-fiber cost once for repository-wide registration coverage.
-- Session storage validation, snapshotting, freezing, provenance, and surface acceptance remain always on and are not affected by invariant selection.
+- Session storage validation, snapshotting, freezing, cited source-event validation, and surface acceptance remain always on and are not affected by invariant selection.
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
index abb77cfc2d..378b730c47 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
@@ -102,4 +102,4 @@ Workspace 约束识别独立的不变式 bundle；包 exports、项目引用、
 - 每个选中的可执行贡献增加一个子 fiber 及其 listener/状态成本；选中的空贡献不增加 listener 或 trace 状态成本，被过滤注册则只保留包名占用。
 - 正则表达式源属于部署配置，在服务重载前保持固定。
 - 普通 Vitest 根上下文会安装当前测试包中被选中的伴随插件；一个完整拓扑只支付一次全部子 fiber 成本，用于覆盖整个仓库的注册。
-- 会话存储验证、快照、冻结、provenance 与 surface 接受规则始终启用，不受不变式选择影响。
+- 会话存储验证、快照、冻结、引用的源事件验证与 surface 接受规则始终启用，不受不变式选择影响。
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
index 75c2b53cef..1cb93a9643 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.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 .agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
-2026-07-20-canonical-tool-output-contract.md: 2429e1c141ad8c8ee932c6d654a6ba74bc4f7618
-2026-07-20-canonical-tool-output-contract.zh.md: 534aa2ed7ad65719b280f64f73a412bf5b17a1de
+2026-07-20-canonical-tool-output-contract.md: fc4a8d52f2ad6ff532fafdd7a987a095c8e3bcef
+2026-07-20-canonical-tool-output-contract.zh.md: a42c5d9a2b581012af823343991ac5789a787658
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
index 2429e1c141..fc4a8d52f2 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md
@@ -24,7 +24,7 @@ output: {
 
 `defineTool` infers the body return and both projectors from the unified `ValueSchemaSpec`. Raw and dynamic definitions provide the compiled `JsonSchemaNode` form. Registration rejects a missing declaration or unsupported raw schema; there is no content-return compatibility path.
 
-For each successful dispatch the registry snapshots the returned value as lossless `JsonValue`, validates it against `output.schema`, deep-freezes it, then invokes the pure renderer and, for a direct surface call, the optional metadata projector. Renderer, projector, schema, or lossless-JSON failures are contained as ordinary `ToolOutputError` results. An around `tools/execute` wrapper receives and returns the canonical success/failure union; a wrapper-authored success is normalized again through the resolved tool's output declaration instead of trusting independently authored content. Canonical-result provenance is scoped to the immutable dispatch token, so returning a cached result from another call or tool triggers normalization under the active declaration rather than bypassing it.
+For each successful dispatch the registry snapshots the returned value as lossless `JsonValue`, validates it against `output.schema`, deep-freezes it, then invokes the pure renderer and, for a direct surface call, the optional metadata projector. Renderer, projector, schema, or lossless-JSON failures are contained as ordinary `ToolOutputError` results. An around `tools/execute` wrapper receives and returns the canonical success/failure union; a wrapper-authored success is normalized again through the resolved tool's output declaration instead of trusting independently authored content. Each canonical result is tied to the immutable dispatch token that created it, so returning a cached result from another call or tool triggers normalization under the active declaration rather than bypassing it.
 
 ```ts ignore-check
 type ToolExecutionResult =
diff --git a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
index 534aa2ed7a..a42c5d9a2b 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md
@@ -24,7 +24,7 @@ output: {
 
 `defineTool` 从统一的 `ValueSchemaSpec` 推导工具主体返回值和两个投影器的类型。原始定义和动态定义则提供编译后的 `JsonSchemaNode` 形式。注册时会拒绝缺失输出声明或采用不受支持的原始 schema 的定义，不提供兼容旧式内容返回值的路径。
 
-每次成功分发时，注册表会将返回值快照为无损 `JsonValue`，依据 `output.schema` 校验并深度冻结，然后调用纯渲染器；对于直接的外层调用，还会调用可选的元数据投影器。渲染器、投影器、schema 或无损 JSON 处理失败都会被收敛为普通 `ToolOutputError` 结果。围绕 `tools/execute` 的包装层接收并返回规范的成功／失败联合；包装层自行产生的成功结果会再次通过已解析工具的输出声明完成归一化，而不会信任其独立编写的内容。每个规范结果的来源归属仅限于一个不可变的分发 token；因此，如果包装层返回来自其他调用或工具的缓存结果，系统会依据当前生效的输出声明重新执行归一化，而不会绕过这一步。
+每次成功分发时，注册表会将返回值快照为无损 `JsonValue`，依据 `output.schema` 校验并深度冻结，然后调用纯渲染器；对于直接的外层调用，还会调用可选的元数据投影器。渲染器、投影器、schema 或无损 JSON 处理失败都会被收敛为普通 `ToolOutputError` 结果。围绕 `tools/execute` 的包装层接收并返回规范的成功／失败联合；包装层自行产生的成功结果会再次通过已解析工具的输出声明完成归一化，而不会信任其独立编写的内容。每个规范结果都与创建它的不可变分发 token 绑定；因此，如果包装层返回来自其他调用或工具的缓存结果，系统会依据当前生效的输出声明重新执行归一化，而不会绕过这一步。
 
 ```ts ignore-check
 type ToolExecutionResult =
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
index 0575e85c1c..77ee43a2d9 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.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 .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
-2026-07-22-unified-send-and-coalesced-user-messages.md: f32d6ca65d5236e1fabdd177cdf54e36929c853f
-2026-07-22-unified-send-and-coalesced-user-messages.zh.md: 6148cf4e0dda9032fca0ced5b466787877b89fa0
+2026-07-22-unified-send-and-coalesced-user-messages.md: bc195e77c71b554d60c03c91134bbcef95678fff
+2026-07-22-unified-send-and-coalesced-user-messages.zh.md: 668ca01bc6b6854642fee2afe9f7be7354b25c5c
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
index f32d6ca65d..bc195e77c7 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md
@@ -14,9 +14,9 @@ Separately, `context/message` and `user/message` had converged: the surface proj
 
 **One primitive, three preset aliases.** The `Agent` interface's `send(message, target, wakeup)` covers the (`target` × `wakeup`) matrix. Its complete `UserMessage` owns identity, role, model-facing `content`, and producer `source`; the remaining arguments own only routing policy. `followup` (`next-turn`/wakeup), `steer` (`next-step`/wakeup), and `inject` (`next-step`/no-wakeup) each accept that one message and fix the policy. `wakeup` reserves a driver when the agent is idle; an already active driver receives no second reservation and can claim the input only if it reaches a later pre-step boundary. `next-turn`/no-wakeup (queue without waking) is representable with no alias and no current caller.
 
-**inject is a non-waking next-step delivery.** It always appends the complete message to the next-step inbox and records that insertion in a durable `agent/inbox/spliced` event. The driver claims it at a later pre-step and records it as model-visible `user/message` only when the final decision returns it in the entering batch; idle injection remains pending until another delivery wakes the driver. Its required `UserMessage.source` preserves the caller's explicit provenance.
+**inject is a non-waking next-step delivery.** It always appends the complete message to the next-step inbox and records that insertion in a durable `agent/inbox/spliced` event. The driver claims it at a later pre-step and records it as model-visible `user/message` only when the final decision returns it in the entering batch; idle injection remains pending until another delivery wakes the driver. Its required `UserMessage.source` preserves the source fields supplied by the caller.
 
-**context/message is gone.** Injected context uses one `UserMessage` value in the inbox and becomes a `user/message` event if admitted; context producers supply the appropriate non-user `source` explicitly, and typed source variants carry any domain-specific durable provenance. The surface, derivation, and `SurfaceEventType` drop `context/message`; consumers that need "is this a human prompt?" read `source.kind === 'user'` instead of the event type.
+**context/message is gone.** Injected context uses one `UserMessage` value in the inbox and becomes a `user/message` event if admitted; context producers supply the appropriate non-user `source` explicitly, and typed source variants carry any durable producer-specific fields. The surface, derivation, and `SurfaceEventType` drop `context/message`; consumers that need "is this a human prompt?" read `source.kind === 'user'` instead of the event type.
 
 **Goal continuation attribution uses positive rounds.** Goal lifecycle state commits through the domain-owned `goal/change` event defined by the later [goal-owned durable event decision](2026-07-31-goal-owned-durable-events.md). A positive round advances only from an admitted continuation `user/message`; goal persistence does not use injection or inbox state.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
index 6148cf4e0d..668ca01bc6 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md
@@ -14,9 +14,9 @@ agent 的对外驱动接口逐渐长出三个近乎平行的动词——`send`
 
 **一个原语，三个预设别名。** `Agent` 接口的 `send(message, target, wakeup)` 覆盖 (`target` × `wakeup`) 矩阵。完整的 `UserMessage` 持有标识、角色、模型可见 `content` 与生产方 `source`；其余参数只持有路由策略。`followup`（`next-turn`/wakeup）、`steer`（`next-step`/wakeup）和 `inject`（`next-step`/no-wakeup）都接收这一条消息并固定策略。`wakeup` 会在 agent 空闲时保留一个驱动器；已经活跃的驱动器不会获得第二次保留，只有在抵达后续 pre-step 边界时才能领取该输入。`next-turn`/no-wakeup（入队但不唤醒）可以表达，只是没有别名，也没有当前调用方。
 
-**inject 是不会唤醒的 next-step 投递。** 它始终把完整消息追加到 next-step inbox，并在持久 `agent/inbox/spliced` 事件中记录该插入。驱动器会在后续 pre-step 领取它，并且只有最终决策把它放入进入步骤的批次时，才会将其记录为模型可见的 `user/message`；空闲注入会保持待处理，直到其他投递唤醒驱动器。必填的 `UserMessage.source` 会保留调用方显式提供的来源信息。
+**inject 是不会唤醒的 next-step 投递。** 它始终把完整消息追加到 next-step inbox，并在持久 `agent/inbox/spliced` 事件中记录该插入。驱动器会在后续 pre-step 领取它，并且只有最终决策把它放入进入步骤的批次时，才会将其记录为模型可见的 `user/message`；空闲注入会保持待处理，直到其他投递唤醒驱动器。必填的 `UserMessage.source` 会保留调用方提供的源字段。
 
-**context/message 已移除。** 注入的上下文在 inbox 中使用同一个 `UserMessage` 值，并在获准时成为 `user/message` 事件；上下文生产方显式提供合适的非 `user` 类别 `source`，类型化 source 变体携带所有特定于领域的持久来源信息。对外接口、派生逻辑和 `SurfaceEventType` 都不再包含 `context/message`；需要判断“这是不是一条人类提示词？”的消费方改为读取 `source.kind === 'user'`，而不是事件类型。
+**context/message 已移除。** 注入的上下文在 inbox 中使用同一个 `UserMessage` 值，并在获准时成为 `user/message` 事件；上下文生产方显式提供合适的非 `user` 类别 `source`，类型化 source 变体携带持久化的生产方专用字段。对外接口、派生逻辑和 `SurfaceEventType` 都不再包含 `context/message`；需要判断“这是不是一条人类提示词？”的消费方改为读取 `source.kind === 'user'`，而不是事件类型。
 
 **Goal 继续执行归属使用正数 Round。** Goal 生命周期状态通过后续的[Goal 自有持久事件决策](2026-07-31-goal-owned-durable-events.md)所定义的领域自有 `goal/change` 事件提交。正数 Round 只从已准入的继续执行 `user/message` 推进；goal 持久化不使用注入或 inbox 状态。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
index d328c8a065..a55c6dbd74 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.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 .agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
-2026-07-24-separate-context-injection-from-turn-execution.md: bb28d96cf1494d94ad7a7d4a4714e536c7072d2f
-2026-07-24-separate-context-injection-from-turn-execution.zh.md: 0edf3f4e8a062fe82462e263da383e27d79034c5
+2026-07-24-separate-context-injection-from-turn-execution.md: 719c4562b6687e42cc70721658152992735ec662
+2026-07-24-separate-context-injection-from-turn-execution.zh.md: 4564c5376f3e6f9de4d50dc13f2d1f01e6230d91
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
index bb28d96cf1..719c4562b6 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.md
@@ -12,7 +12,7 @@ Atomic attachment to an inbox message forced the loop to preserve context throug
 
 Idle `inject()` exposed a second mismatch. Injection did not request model execution, yet the implementation opened and closed a zero-step `injection` turn solely to satisfy the turn-enclosure invariant and obtain a durability checkpoint. A turn therefore sometimes meant “run the agent loop” and sometimes meant “persist context without running it.”
 
-`HookContext` also named its producer rather than its role. The value could come from a native plugin, a hook bridge, prompt admission, or tool post-processing; its stable meaning was additional model-facing context with provenance.
+`HookContext` also named its producer rather than its role. The value could come from a native plugin, a hook bridge, prompt admission, or tool post-processing; its stable meaning was additional model-facing context whose source named the producer.
 
 ## Decision
 
@@ -22,7 +22,7 @@ A caller that owns context delivers an identified, frozen `UserMessage` through
 
 An entering pre-step returns the complete `PreStepDecision.messages` batch for the request being finalized. Tool extension points still return `additionalContexts`, which enter the next-step inbox only after the corresponding tool results. These values are extension-point outputs, not attachments captured from a caller's inbox item.
 
-Every additional context is an independent `UserMessage` whose `source` records provenance. Inbox insertion is durable immediately; admission later records the same value as `user/message`. There is no `context/message`, prompt-prefix placement, stable request delimiter, or prompt envelope. Transcript and UI consumers distinguish direct user messages from injected context by `source`.
+Every additional context is an independent `UserMessage` whose `source` names its producer and carries producer-specific fields. Inbox insertion is durable immediately; admission later records the same value as `user/message`. There is no `context/message`, prompt-prefix placement, stable request delimiter, or prompt envelope. Transcript and UI consumers distinguish direct user messages from injected context by `source`.
 
 ## Injection lifecycle
 
@@ -36,7 +36,7 @@ The loop appends injected `user/message` events only from entered batches inside
 
 ## Extension and caller semantics
 
-The enter branch's `PreStepDecision.messages` is the complete batch for the proposed step. A waterfall listener that delegates with `next()` preserves downstream messages unless it intentionally replaces them; additions follow natural waterfall return order. Tool-result `additionalContexts` retain FIFO order and individual provenance.
+The enter branch's `PreStepDecision.messages` is the complete batch for the proposed step. A waterfall listener that delegates with `next()` preserves downstream messages unless it intentionally replaces them; additions follow natural waterfall return order. Tool-result `additionalContexts` retain FIFO order and each message's source.
 
 Caller-driven injection and current-step context deliberately use different timing. `inject()` joins the next pre-step available and cannot promise that a request already being finalized will consume it. A listener that must affect that exact request returns the context in `PreStepDecision.messages`; downstream rejection or failure then prevents it from materializing.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
index 0edf3f4e8a..4564c5376f 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md
@@ -12,7 +12,7 @@ agent API 曾用三种相互重叠的方式表示面向模型的补充输入：
 
 空闲状态下的 `inject()` 还暴露了另一处语义错位。注入当时并不请求模型执行，但实现仅为了满足轮次封闭不变量并获得持久性检查点，就会打开并关闭一个零步骤的 `injection` 轮次。于是，当时的轮次有时表示「运行 agent loop」，有时却表示「不运行 agent，仅持久化上下文」。
 
-`HookContext` 的名字也描述了生产方，而非该值的职责。它可能来自原生插件、hook bridge、提示词准入或工具后处理；其稳定含义是带来源信息的额外模型上下文。
+`HookContext` 的名字也描述了生产方，而非该值的职责。它可能来自原生插件、hook bridge、提示词准入或工具后处理；其稳定含义是额外的模型可见上下文，并且 source 会指明生产方。
 
 ## 决策
 
@@ -22,7 +22,7 @@ agent API 曾用三种相互重叠的方式表示面向模型的补充输入：
 
 返回 enter 的 pre-step 会为正在最终确定的请求返回完整的 `PreStepDecision.messages` 批次。工具扩展点仍可返回 `additionalContexts`，这些上下文只会在对应工具结果之后进入 next-step inbox。这些值是扩展点的输出，而不是从调用方 inbox 条目捕获的附件。
 
-每项额外上下文都是独立的 `UserMessage`，并由 `source` 记录来源。inbox 插入会立即持久化；后续准入会将同一个值记录为 `user/message`。不再有 `context/message`、prompt-prefix 放置方式、稳定请求分隔符或提示词封套。transcript 与 UI 消费方通过 `source` 区分直接用户消息和注入上下文。
+每项额外上下文都是独立的 `UserMessage`，其 `source` 会指明生产方，并携带生产方专用字段。inbox 插入会立即持久化；后续准入会将同一个值记录为 `user/message`。不再有 `context/message`、prompt-prefix 放置方式、稳定请求分隔符或提示词封套。transcript 与 UI 消费方通过 `source` 区分直接用户消息和注入上下文。
 
 ## 注入生命周期
 
@@ -36,7 +36,7 @@ loop 只会在轮次内从进入步骤的批次追加注入的 `user/message`。
 
 ## 扩展点与调用方语义
 
-enter 分支的 `PreStepDecision.messages` 是拟议步骤的完整批次。waterfall（瀑布式事件）监听器调用 `next()` 委托时，会保留下游消息，除非有意替换；新增消息遵循 waterfall 的自然返回顺序。工具结果的 `additionalContexts` 保留 FIFO 顺序及各自来源。
+enter 分支的 `PreStepDecision.messages` 是拟议步骤的完整批次。waterfall（瀑布式事件）监听器调用 `next()` 委托时，会保留下游消息，除非有意替换；新增消息遵循 waterfall 的自然返回顺序。工具结果的 `additionalContexts` 保留 FIFO 顺序及每条消息的 source。
 
 调用方主动注入与当前步骤上下文刻意采用不同的时序。`inject()` 会加入下一个可用 pre-step，无法保证正在最终确定的请求会消费它。必须影响该请求的监听器在 `PreStepDecision.messages` 中返回上下文；下游 reject 或失败时，该上下文不会落入日志。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml
index 938d86ef4b..0b44906fd6 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.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 .agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md
-2026-07-26-packed-chunk-rows-by-default.md: d6a044676604e4a4512a7a6674edb80e120b2f3c
-2026-07-26-packed-chunk-rows-by-default.zh.md: 0e3e06e0d4185603cd21939589855a51797560a4
+2026-07-26-packed-chunk-rows-by-default.md: 141c9a32a07b5cb4885a21b419df30d45dc1061b
+2026-07-26-packed-chunk-rows-by-default.zh.md: a03654ec82755cadeea734d277c0893db546a5c1
diff --git a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md
index d6a0446766..141c9a32a0 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.md
@@ -48,7 +48,7 @@ JSONL persistence tests prove that omission writes a packed row, explicit `false
 
 **Remove `packChunks` and always pack.** One writer is simpler, but one-event-per-line output remains useful for diagnostics and for focused mixed-layout compatibility tests. The explicit opt-out preserves those current consumers without weakening the default.
 
-**Batch chunks as logical session events.** This reduces event count, but it delays or reshapes live delivery, renumbers provenance, and requires every UI and replay consumer to understand another streaming unit. Physical packing obtains the storage benefit behind the existing persistence interface.
+**Batch chunks as logical session events.** This reduces event count, but it delays or reshapes live delivery, renumbers the chunk seqs cited by assistant messages, and requires every UI and replay consumer to understand another streaming unit. Physical packing obtains the storage benefit behind the existing persistence interface.
 
 **Keep the branch migrator permanently.** The read-only canonicalizer and snapshot gate own continuing enforcement. A mutation command has value only while in-flight branches still carry the former fixture layout, so its lifetime is explicitly bounded by the removal proposal.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
index 0e3e06e0d4..a03654ec82 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-packed-chunk-rows-by-default.zh.md
@@ -48,7 +48,7 @@ JSONL 持久化测试证明：省略选项时会写入打包行，显式传入 `
 
 **删除 `packChunks` 并始终打包。** 只保留一个写入器更简单，但每个事件一行的输出仍适用于诊断和聚焦的混合布局兼容性测试。显式停用选项在不削弱默认值的同时，保留了这些现有消费方。
 
-**把分片批量合并为逻辑会话事件。** 这会减少事件数量，但也会延迟或重塑实时传递，改变溯源信息所引用的序号，并要求每个 UI 和回放消费方理解另一种流式单位。物理打包通过现有持久化接口获得存储收益。
+**把分片批量合并为逻辑会话事件。** 这会减少事件数量，但也会延迟或重塑实时传递，重新编号助手消息引用的分片 seq，并要求每个 UI 和回放消费方理解另一种流式单位。物理打包通过现有持久化接口获得存储收益。
 
 **永久保留分支迁移器。** 只读的规范布局转换器与快照门禁负责持续强制执行。只有在途分支仍携带旧 fixture 布局时，会修改仓库内容的命令才有价值，因此移除提案明确限定了其生命周期。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml
index 307dc12518..4aa30937c7 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.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 .agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md
-2026-07-28-identified-immutable-message-values.md: 472de8b133ba323c3e1ff5e53c8dacb3d66525c5
-2026-07-28-identified-immutable-message-values.zh.md: d322ff93765294478d2adce41a5903f3a7fdd67d
+2026-07-28-identified-immutable-message-values.md: f1e0e8c0b42bd2dc4b3c729dc15b5f2a36b98338
+2026-07-28-identified-immutable-message-values.zh.md: 0d1f2fcf5be76089f1c135757a7a50729f099ccd
diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md
index 472de8b133..f1e0e8c0b4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.md
@@ -8,13 +8,13 @@ English | [中文](2026-07-28-identified-immutable-message-values.zh.md)
 
 The harness had several message-shaped representations with different identity rules. Agent input acquired an inbox correlation id only when the loop accepted it, while durable user messages, assistant messages, tool results, and model-request messages could have no identity. Prompt admission therefore sat between creation and identity, and equivalent content was copied across live events, durable events, and model requests without one value that named the message throughout its lifetime.
 
-This made identity a routing side effect rather than a message invariant. Producers could not refer to a message before calling the agent, prompt hooks received content and source separately, and later projections had to reconstruct a message while deciding whether an id existed. Immutability also began at different boundaries: some inputs were frozen by the loop, some only by session append, and provider-produced assistant output used a separate provenance-bearing shape.
+This made identity a routing side effect rather than a message invariant. Producers could not refer to a message before calling the agent, prompt hooks received content and source separately, and later projections had to reconstruct a message while deciding whether an id existed. Immutability also began at different boundaries: some inputs were frozen by the loop, some only by session append, and provider-produced assistant output used a separate shape carrying provider, model, and replay state.
 
 ## Decision
 
 `@deepseek-ai/dsh-llm` owns one `Message` value with required `id`, `role`, `content`, and `source`. `MessageId` is opaque and shared by user, assistant, and tool-result messages. A message receives its id at creation, before inbox routing, claim, pre-step rewriting, durable append, or request projection. The same id survives every representation boundary.
 
-`createMessage(input)` is the canonical role-generic creation boundary. It mints a `MessageId`, detaches the supplied role, content, and source, and deep-freezes the complete value before returning it. `createUserMessage({ content, source })` fixes the user role for prompt and context producers. `createAssistantMessage({ content, source })` fixes both the assistant role and the model source kind, so model-output producers supply only content and model provenance. All creation helpers exclude an input id so callers cannot accidentally present creation as import. `freezeMessage(message)` is the separate import or transformation boundary: it detaches and deep-freezes a message whose identity already exists, without minting a replacement.
+`createMessage(input)` is the canonical role-generic creation boundary. It mints a `MessageId`, detaches the supplied role, content, and source, and deep-freezes the complete value before returning it. `createUserMessage({ content, source })` fixes the user role for prompt and context producers. `createAssistantMessage({ content, source })` fixes both the assistant role and the model source kind, so model-output producers supply only content plus provider, model, and optional replay state. All creation helpers exclude an input id so callers cannot accidentally present creation as import. `freezeMessage(message)` is the separate import or transformation boundary: it detaches and deep-freezes a message whose identity already exists, without minting a replacement.
 
 The helpers live in `dsh-llm` beside the base message vocabulary because their complete contracts depend only on that vocabulary. `createToolResultMessage()` belongs with the other creation helpers: it couples a tool call id to the exact user-role tool-result block and source without depending on session state or events. `dsh-session` consumes complete messages rather than owning their construction.
 
@@ -40,7 +40,7 @@ Every message producer must choose creation or import explicitly, and tests cons
 
 Live inbox events, durable events, derived history, and model requests can correlate one message without content equality or envelope-specific ids. Pending-input policy and UI attachment cleanup can compare `MessageId` before a turn exists, while claims retain that identity inside the open turn. Deep freezing prevents a producer, hook, or observer from changing the value after identity is established.
 
-The shared representation removes the old `UserMessageData`/`AgentMessage` split and folds provider provenance into typed message sources. Event envelopes still own facts that are not message semantics, such as turn and step position, token usage, internal tool failure identity, and presentation metadata.
+The shared representation removes the old `UserMessageData`/`AgentMessage` split and puts provider, model, and optional replay state into typed message sources. Event envelopes still own facts that are not message semantics, such as turn and step position, token usage, internal tool failure identity, and presentation metadata.
 
 The message and helper unit tests pin immediate identity, detachment, deep immutability, and preservation of an imported id. Agent-loop tests pin identity across admission, inbox lifecycle, durable append, content rewriting, and cancellation; session tests pin frozen derivation and identity-preserving replacement.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
index d322ff9376..0d1f2fcf5b 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.zh.md
@@ -8,13 +8,13 @@ Status: implemented
 
 harness 曾存在多种形似消息的表示，各自采用不同的标识规则。agent（智能体）输入只有在 agent loop 接受后才会取得 inbox 关联 id，而持久用户消息、assistant 消息、工具结果和模型请求消息都可能没有标识。因此，提示词准入介于创建消息与建立标识之间；等价内容会在实时事件、持久事件和模型请求之间复制，却没有一个值能在消息的整个生命周期中标识它。
 
-这使标识成为路由的副作用，而不是消息不变量。生产方无法在调用 agent 前引用一条消息，提示词钩子会分别接收内容和来源，后续投影则必须一边重建消息，一边决定 id 是否存在。不可变性也从不同边界开始：部分输入由 agent loop 冻结，部分直到会话追加时才冻结，由提供方生成的 assistant 输出则使用另一种携带溯源信息的形状。
+这使标识成为路由的副作用，而不是消息不变量。生产方无法在调用 agent 前引用一条消息，提示词钩子会分别接收内容和来源，后续投影则必须一边重建消息，一边决定 id 是否存在。不可变性也从不同边界开始：部分输入由 agent loop 冻结，部分直到会话追加时才冻结，由提供方生成的 assistant 输出则使用另一种携带提供方、模型和回放状态的形状。
 
 ## 决策
 
 `@deepseek-ai/dsh-llm` 持有唯一一种 `Message` 值，其 `id`、`role`、`content` 和 `source` 均为必填。`MessageId` 是不透明标识，由用户消息、assistant 消息和工具结果消息共享。消息在创建时就会获得 id，早于 inbox 路由、领取、pre-step 改写、持久追加或请求投影。同一个 id 会跨越每个表示边界。
 
-`createMessage(input)` 是角色通用的规范创建边界。它会生成 `MessageId`，将传入的角色、内容和来源与调用方对象解除引用关系，并在返回完整值前将其深度冻结。`createUserMessage({ content, source })` 为提示词和上下文生产方固定 user 角色。`createAssistantMessage({ content, source })` 同时固定 assistant 角色与模型来源类别，因此模型输出生产方只需提供内容和模型溯源信息。所有创建辅助函数的输入都不包含 id，因此调用方不会意外地把新消息的创建伪装成已有消息的导入。`freezeMessage(message)` 是独立的导入或转换边界：它会将已有标识的消息与调用方对象解除引用关系并深度冻结，不会生成替代标识。
+`createMessage(input)` 是角色通用的规范创建边界。它会生成 `MessageId`，将传入的角色、内容和来源与调用方对象解除引用关系，并在返回完整值前将其深度冻结。`createUserMessage({ content, source })` 为提示词和上下文生产方固定 user 角色。`createAssistantMessage({ content, source })` 同时固定 assistant 角色与模型来源类别，因此模型输出生产方只需提供内容，以及提供方、模型和可选的回放状态。所有创建辅助函数的输入都不包含 id，因此调用方不会意外地把新消息的创建伪装成已有消息的导入。`freezeMessage(message)` 是独立的导入或转换边界：它会将已有标识的消息与调用方对象解除引用关系并深度冻结，不会生成替代标识。
 
 这些辅助函数位于基础消息词汇旁的 `dsh-llm` 中，因为它们的完整约定只依赖该词汇。`createToolResultMessage()` 与其他创建辅助函数同属此处：它使用同一个工具调用 id，将工具来源与确切的 user-role 工具结果块耦合起来，不依赖会话状态或事件。`dsh-session` 只消费完整消息，不负责构造它们。
 
@@ -40,7 +40,7 @@ harness 曾存在多种形似消息的表示，各自采用不同的标识规则
 
 实时 inbox 事件、持久事件、派生历史和模型请求可以关联同一条消息，无需比较内容或使用封装专用 id。待处理输入策略和 UI 附件清理可以在轮次存在之前比较 `MessageId`，领取后则会在已打开的轮次内保留该标识。深度冻结可以防止生产方、钩子或观察方在标识建立后更改消息值。
 
-共享表示移除了旧的 `UserMessageData`/`AgentMessage` 划分，并将提供方溯源信息纳入带类型的消息来源。事件封装仍持有不属于消息语义的事实，例如轮次与步骤位置、token 用量、内部工具失败标识和呈现元数据。
+共享表示移除了旧的 `UserMessageData`/`AgentMessage` 划分，并将提供方、模型和可选的回放状态放入带类型的消息来源。事件封装仍持有不属于消息语义的事实，例如轮次与步骤位置、token 用量、内部工具失败标识和呈现元数据。
 
 消息和辅助函数的单元测试会锁定即时标识、解除输入引用、深度不可变性，以及导入 id 的保留。agent loop 测试会锁定标识跨越准入、inbox 生命周期、持久追加、内容改写和取消的行为；会话测试会锁定冻结派生和保留标识的替换行为。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml
index 2bef24442d..e43491d3d1 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.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 .agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md
-2026-07-29-terminal-llm-stream-failures.md: 1e26973360f07c212016c6a44103448a3510a75b
-2026-07-29-terminal-llm-stream-failures.zh.md: d3eeb0534f6cb8d4d1ad167cca089314eb02b513
+2026-07-29-terminal-llm-stream-failures.md: 3f9fc4255e5b2462e14f73414894c5912191c595
+2026-07-29-terminal-llm-stream-failures.zh.md: a73edd89180b22225eb97804857bd1d3b93a4c4a
diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md
index 1e26973360..3f9fc4255e 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md
@@ -28,10 +28,10 @@ The agent loop consumes one failure representation. It iterates and logs chunks
 
 **Require every adapter to emit failure chunks and forbid throws.** Library iterators, transports, and JavaScript dispatch can still throw. Requiring every adapter to reproduce the same catch boundary duplicates ownership and does not protect a direct `LlmService` consumer from an incomplete implementation.
 
-**Catch every iteration error in the agent loop.** The loop cannot reliably distinguish provider failure from middleware, session append, cancellation, or assembly failure without restoring the same sidecar provenance mechanism. Classification belongs where the adapter call is made.
+**Catch every iteration error in the agent loop.** The loop cannot reliably distinguish provider failure from middleware, session append, cancellation, or assembly failure without restoring a sidecar map from stream objects to the adapter calls that created them. Classification belongs where the adapter call is made.
 
 **Return a `Result` before streaming.** A pre-stream result cannot represent a transport failure after partial output without adding a second response lifecycle. The existing terminal chunk already represents both early and late attempt outcomes.
 
 ## Consequences
 
-All `LlmService.stream()` consumers receive adapter operational failures through one typed terminal protocol, while programming and lifecycle failures retain ordinary exception semantics. Recovery gives up exact thrown-object identity and exposes only detached provider-neutral facts. The stream service owns slightly more adapter plumbing, but consumers delete provenance catches and stream-keyed metadata. Prepared calls carry their policy explicitly, and middleware-only routing remains visibly policy-free.
+All `LlmService.stream()` consumers receive adapter operational failures through one typed terminal protocol, while programming and lifecycle failures retain ordinary exception semantics. Recovery gives up exact thrown-object identity and exposes only detached provider-neutral facts. The stream service owns slightly more adapter plumbing, but consumers delete catches that identify which adapter threw and delete stream-keyed metadata. Prepared calls carry their policy explicitly, and middleware-only routing remains visibly policy-free.
diff --git a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
index d3eeb0534f..a73edd8918 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md
@@ -28,10 +28,10 @@ agent loop 只消费一种失败表示。它不再使用分类 catch，而是直
 
 **要求所有适配器发出失败 chunk，并禁止抛出。** 库 iterator、transport 与 JavaScript 分发仍可能抛错。要求每个适配器复制同一 catch 边界会重复归属，也无法保护 `LlmService` 的直接消费方免受不完整实现影响。
 
-**在 agent loop 中捕获所有迭代错误。** 如果不恢复同一套 sidecar 溯源机制，loop 无法可靠区分提供方失败与 middleware、session append、取消或组装失败。分类属于发起适配器调用的边界。
+**在 agent loop 中捕获所有迭代错误。** 如果不恢复一张从流对象到创建该对象的适配器调用的 sidecar 映射，loop 无法可靠区分提供方失败与 middleware、session append、取消或组装失败。分类属于发起适配器调用的边界。
 
 **在流式输出前返回 `Result`。** 流前结果无法表示部分输出之后的传输失败，除非增加第二套响应生命周期。现有终止 chunk 已能表示早期和后期尝试结果。
 
 ## Consequences
 
-所有 `LlmService.stream()` 消费方都通过一种带类型的终止协议接收适配器运行失败，而编程与生命周期失败保留普通异常语义。恢复放弃精确抛出对象身份，只暴露与原对象分离的提供方无关事实。流服务承担略多的适配器管道工作，但消费方删除了溯源 catch 与以 stream 为 key 的元数据。准备完成的调用显式携带策略，而仅由 middleware 路由的调用仍明确没有策略。
+所有 `LlmService.stream()` 消费方都通过一种带类型的终止协议接收适配器运行失败，而编程与生命周期失败保留普通异常语义。恢复放弃精确抛出对象身份，只暴露与原对象分离的提供方无关事实。流服务承担略多的适配器管道工作，但消费方删除了用于识别哪个适配器抛出异常的 catch，也删除了以 stream 为 key 的元数据。准备完成的调用显式携带策略，而仅由 middleware 路由的调用仍明确没有策略。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml
index 752dc0f1aa..e417ee2d89 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.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 .agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md
-2026-07-30-adapter-owned-max-token-defaults.md: a522848fd4482f84859e587505b6a5e6f5c72d60
-2026-07-30-adapter-owned-max-token-defaults.zh.md: 8db6a06199fc1c4e73c86492d12dc86edafe8c7e
+2026-07-30-adapter-owned-max-token-defaults.md: c6a784f23a028f500c6e6ff80dc3e13eee93ec1b
+2026-07-30-adapter-owned-max-token-defaults.zh.md: 3caa81126c5d45db7ef5c84540b0deb81764aaf4
diff --git a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md
index a522848fd4..c6a784f23a 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.md
@@ -12,7 +12,7 @@ An LLM adapter could serialize an explicit `GenerateOptions.maxTokens`, but its
 
 `LlmResolvedModelInfo.defaultMaxTokens` carries an optional adapter-configured per-request output cap for one exact provider/model route. `LlmService` validates it as a positive safe integer and materializes it into `LlmCallConfig.maxTokens` only when the caller omitted a value. A prepared call identifies materialized `maxTokens` and `reasoningEffort` fields as adapter defaults; explicit request or Agent options remain unmarked and therefore win without clamping.
 
-The agent loop continues to prepare calls before logging `request/header`, so the effective config and its adapter-default provenance become durable request facts before dispatch. Before the next `agent/request` waterfall, the loop removes marked fields from the proposal; exact-model resolution then materializes the current route's defaults again. A provider/model switch therefore cannot mistake a previous adapter's default for an explicit override, while explicit conversation values persist. Direct `LlmService.stream()` calls resolve the same default at the final adapter boundary. The field is a request default rather than a hard model output limit; adapters that preserve provider-owned defaults omit it.
+The agent loop continues to prepare calls before logging `request/header`, so the effective config and markers for fields supplied by adapter defaults become durable request facts before dispatch. Before the next `agent/request` waterfall, the loop removes marked fields from the proposal; exact-model resolution then materializes the current route's defaults again. A provider/model switch therefore cannot mistake a previous adapter's default for an explicit override, while explicit conversation values persist. Direct `LlmService.stream()` calls resolve the same default at the final adapter boundary. The field is a request default rather than a hard model output limit; adapters that preserve provider-owned defaults omit it.
 
 The native DeepSeek adapter exposes `maxTokens` in Cordis config with a 256,000-token default and maps the effective value to `max_tokens`. Its default context capacity is 1,000,000 tokens: both built-in V4 entries publish that exact capacity, while configured entries without capacity and unlisted pass-through ids inherit the same adapter-wide fallback.
 
@@ -28,6 +28,6 @@ The native DeepSeek adapter exposes `maxTokens` in Cordis config with a 256,000-
 
 ## Consequences
 
-DeepSeek conversations send `max_tokens: 256000` by default, and the same value plus its adapter provenance appear in the session request header. Deployments can change the adapter default through `llm-deepseek.config.maxTokens`; per-agent and per-request values override it. Changing the route rematerializes the new exact adapter's default instead of carrying DeepSeek's derived value forward. Other adapters retain their existing behavior until they intentionally publish `defaultMaxTokens`.
+DeepSeek conversations send `max_tokens: 256000` by default, and the session request header records both the value and that the adapter supplied it. Deployments can change the adapter default through `llm-deepseek.config.maxTokens`; per-agent and per-request values override it. Changing the route rematerializes the new exact adapter's default instead of carrying DeepSeek's derived value forward. Other adapters retain their existing behavior until they intentionally publish `defaultMaxTokens`.
 
 The 256,000-token output budget reserves a large part of the one-million-token context on endpoints that pre-allocate requested output. Deployments whose gateway or model supports a smaller budget must lower `maxTokens`; the explicit configuration is preferable to an undocumented provider fallback.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
index 8db6a06199..3caa81126c 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-adapter-owned-max-token-defaults.zh.md
@@ -12,7 +12,7 @@ LLM（大语言模型）适配器可以序列化显式的 `GenerateOptions.maxTo
 
 `LlmResolvedModelInfo.defaultMaxTokens` 携带一条确切提供方／模型路由的可选单次请求输出上限，该值由适配器配置。`LlmService` 将其校验为正安全整数，并且仅在调用方省略值时才填入 `LlmCallConfig.maxTokens`。准备后的调用会将已填入的 `maxTokens` 和 `reasoningEffort` 字段标记为适配器默认值；显式请求值或 Agent 选项不带该标记，因此优先且不会被自动调整。
 
-agent loop 仍在记录 `request/header` 前准备调用，因此生效配置及其适配器默认值来源会在分派前成为持久请求事实。下一次 `agent/request` waterfall（瀑布式事件）前，agent loop 会从提议中移除带标记字段，随后精确模型解析会再次填入当前路由的默认值。因此，切换提供方／模型不会把前一个适配器的默认值误当成显式覆盖，而显式对话值则会保留。直接调用 `LlmService.stream()` 时，也会在最终适配器边界解析同一默认值。该字段是请求默认值，而非模型输出硬上限；保留提供方持有默认值的适配器会省略它。
+agent loop 仍在记录 `request/header` 前准备调用，因此生效配置和标明哪些字段由适配器默认值填入的标记，会在分派前成为持久请求事实。下一次 `agent/request` waterfall（瀑布式事件）前，agent loop 会从提议中移除带标记字段，随后精确模型解析会再次填入当前路由的默认值。因此，切换提供方／模型不会把前一个适配器的默认值误当成显式覆盖，而显式对话值则会保留。直接调用 `LlmService.stream()` 时，也会在最终适配器边界解析同一默认值。该字段是请求默认值，而非模型输出硬上限；保留提供方持有默认值的适配器会省略它。
 
 原生 DeepSeek 适配器在 Cordis 配置中公开 `maxTokens`，默认值为 256,000 token，并将生效值映射为 `max_tokens`。其默认上下文容量为 1,000,000 token：两个内置 V4 配置项均公布这一精确容量；不含容量的已配置项和未列出的原样传递 id 则继承同一个适配器级回退值。
 
@@ -28,6 +28,6 @@ agent loop 仍在记录 `request/header` 前准备调用，因此生效配置及
 
 ## Consequences
 
-DeepSeek 对话默认发送 `max_tokens: 256000`，会话请求 header 中也会出现相同的值及其适配器来源。部署可以通过 `llm-deepseek.config.maxTokens` 更改适配器默认值；每个 agent 和每次请求的值都会覆盖它。更改路由会重新填入新的精确适配器默认值，而不是继续沿用 DeepSeek 派生出的值。其他适配器会保留现有行为，直至主动公布 `defaultMaxTokens`。
+DeepSeek 对话默认发送 `max_tokens: 256000`，会话请求 header 会记录该值，并记录该值由适配器提供。部署可以通过 `llm-deepseek.config.maxTokens` 更改适配器默认值；每个 agent 和每次请求的值都会覆盖它。更改路由会重新填入新的精确适配器默认值，而不是继续沿用 DeepSeek 派生出的值。其他适配器会保留现有行为，直至主动公布 `defaultMaxTokens`。
 
 对于预分配请求输出的端点，256,000 token 的输出预算会占用 1,000,000 token 上下文中的很大部分。如果部署使用的 gateway 或模型仅支持较小预算，则必须调低 `maxTokens`；显式配置优于未记录的提供方回退值。
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
index df37c8aa83..38082cf462 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.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 .agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
-2026-08-08-bounded-session-persistence-write-batching.md: 46dc612492fa1bfa805f77f865f14b168f52776f
-2026-08-08-bounded-session-persistence-write-batching.zh.md: fe1227f7706ba67a12bd7f19db5c0c57cfcfca4f
+2026-08-08-bounded-session-persistence-write-batching.md: 6d77ef90276dcf143bb63019f801379b702b43b2
+2026-08-08-bounded-session-persistence-write-batching.zh.md: 37ebb1566f1826ebbc6fcaf3dca11b65aed3a8ba
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
index 46dc612492..6d77ef9027 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md
@@ -8,7 +8,7 @@ English | [中文](2026-08-08-bounded-session-persistence-write-batching.zh.md)
 
 Streaming responses can emit many `assistant/chunk` events in a short interval. The persistence coordinator previously scheduled a backend append as soon as an idle queue received one event. Events arriving while that append was active shared a follow-up batch, but a fast backend could still produce many small durable appends. Each JSONL append creates and syncs a Zstandard frame or raw suffix, while each SQLite append opens and commits a transaction and increments the session revision.
 
-Dropping chunk events or replacing them with assembled messages would reduce logical storage, but it would also change the event log, replay, sequence numbers, timestamps, and provenance. The write-amplification problem does not require that larger semantic change.
+Dropping chunk events or replacing them with assembled messages would reduce logical storage, but it would also change the event log, replay, sequence numbers, timestamps, and the chunk seqs cited by assistant messages. The write-amplification problem does not require that larger semantic change.
 
 ### Quantified baseline
 
@@ -36,7 +36,7 @@ This decision supersedes only the immediate scheduling cadence in [Collapse live
 
 ## Alternatives considered
 
-**Do not persist streaming chunk events.** Rejected here: it changes the event-sourced authority and recovery semantics rather than only physical write cadence. The existing [assembled-message rejection](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md) remains the guardrail until a no-information-loss replacement defines replay, fork, provenance, sequence, and crash behavior independently. The [packed-row decision](2026-07-26-packed-chunk-rows-by-default.md) remains the complementary JSONL storage-size optimization.
+**Do not persist streaming chunk events.** Rejected here: it changes the event-sourced authority and recovery semantics rather than only physical write cadence. The existing [assembled-message rejection](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md) remains the guardrail until a no-information-loss replacement defines replay, fork, cited source-event links, sequence, and crash behavior independently. The [packed-row decision](2026-07-26-packed-chunk-rows-by-default.md) remains the complementary JSONL storage-size optimization.
 
 **Write only at semantic checkpoints.** Rejected: it maximizes batching but makes the ordinary crash-loss window depend on a separately mounted policy. Bounded background writes preserve progress between checkpoints while mandatory flushes keep their stronger ordering contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
index fe1227f770..37ebb1566f 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 流式响应可能会在短时间内发出大量 `assistant/chunk` 事件。此前，只要空闲队列收到一个事件，持久化协调器就会立即调度一次后端追加。该追加仍在进行时到达的事件会共用一个后续批次，但如果后端速度很快，仍可能产生大量小规模的持久化追加。每次 JSONL 追加都会创建并同步一个 Zstandard 帧或原始格式后缀，而每次 SQLite 追加都会打开并提交一个事务，同时递增会话修订版本。
 
-丢弃分片事件或用组装后的消息替代它们可以减少逻辑存储量，但也会改变事件日志、回放、序列号、时间戳和来源信息。写放大问题不要求采取这项语义变化更大的方案。
+丢弃分片事件或用组装后的消息替代它们可以减少逻辑存储量，但也会改变事件日志、回放、序列号、时间戳，以及助手消息引用的分片 seq。写放大问题不要求采取这项语义变化更大的方案。
 
 ### 量化基线
 
@@ -36,7 +36,7 @@ SQLite 每个逻辑事件存储一行，因此同样的逻辑日志会分别保
 
 ## 备选方案
 
-**不持久化流式分片事件。** 这里不采纳：这会改变事件日志作为真源的地位及恢复语义，而不只是改变物理写入节奏。在无信息损失的替代方案独立定义回放、fork、来源信息、序列和崩溃行为之前，现有的[拒绝仅保留组装消息的决策](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)仍是防护规则。[打包行决策](2026-07-26-packed-chunk-rows-by-default.md)仍是配套的 JSONL 存储体积优化。
+**不持久化流式分片事件。** 这里不采纳：这会改变事件日志作为真源的地位及恢复语义，而不只是改变物理写入节奏。在无信息损失的替代方案独立定义回放、fork、引用源事件的关联、序列和崩溃行为之前，现有的[拒绝仅保留组装消息的决策](../../rejected/simplification/2026-06-20-assembled-assistant-messages-only.md)仍是防护规则。[打包行决策](2026-07-26-packed-chunk-rows-by-default.md)仍是配套的 JSONL 存储体积优化。
 
 **仅在语义检查点写入。** 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序约定。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
index 616caa6f68..1c8bb4a7d0 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.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 .agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
-2026-07-28-load-pre-identity-session-messages.md: 2901527658421b37576bdf5b49e66829104a3b41
-2026-07-28-load-pre-identity-session-messages.zh.md: bf6e58d8a895f41012449a1212533902e1211e99
+2026-07-28-load-pre-identity-session-messages.md: 694bf9ed9ec7a24399b5898665c2222a806f93c6
+2026-07-28-load-pre-identity-session-messages.zh.md: 23f55e1b67f988b6da0ae651f0b53059715eab86
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
index 2901527658..694bf9ed9e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md
@@ -28,7 +28,7 @@ The upgrade is read-only. Stored legacy records remain unchanged; a resumed sess
 
 ## Consequences
 
-Pre-identity JSONL and SQLite sessions resume with their original message content, sources, provider provenance, tool correlation, errors, metadata, and surface replacements. The returned events are otherwise indistinguishable from current imported message snapshots and remain deeply frozen.
+Pre-identity JSONL and SQLite sessions resume with their original message content, sources, assistant provider/model fields, tool correlation, errors, metadata, and surface replacements. The returned events are otherwise indistinguishable from current imported message snapshots and remain deeply frozen.
 
 This is one explicit same-version import exception, not a general v0 compatibility layer. Adding another exception requires another complete, unambiguous mapping at the persistence boundary; malformed current data continues to fail rather than being guessed into validity. The shared coordinator contract exercises the upgrade against the in-memory reference, JSONL, and SQLite backends, including deterministic reload and tool-result replacement identity.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
index bf6e58d8a8..23f55e1b67 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 后果
 
-消息标识机制引入前的 JSONL 和 SQLite 会话可以恢复，并保留原始的消息内容、来源、提供方溯源信息、工具调用关联、错误、元数据和 surface 替换。除此之外，返回事件与当前导入的消息快照无法区分，并且仍然经过深度冻结。
+消息标识机制引入前的 JSONL 和 SQLite 会话可以恢复，并保留原始的消息内容、来源、assistant 的提供方／模型字段、工具调用关联、错误、元数据和 surface 替换。除此之外，返回事件与当前导入的消息快照无法区分，并且仍然经过深度冻结。
 
 这是一个显式的同版本导入例外，而非通用的 v0 兼容层。若要增加另一个例外，必须在持久化边界提供另一套完整且无歧义的映射；当前数据若格式错误，系统仍会拒绝，而不会猜测如何将其变成有效数据。共享的协调器约定会在内存参考实现、JSONL 和 SQLite 后端上验证这项升级，包括重新加载时的确定性，以及工具结果替换时的标识继承。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
index 69359852c2..0e3118da05 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.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 .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
-2026-07-29-human-transcript-append-origin.md: 9804d3d8d67a4ad00c3d395c2081fd47e03c254a
-2026-07-29-human-transcript-append-origin.zh.md: 030be076bec9c64ffc97957bbc0fc2b6084d2030
+2026-07-29-human-transcript-append-origin.md: fe60ab6e745fdc08d84deb4a6e2e4fe8168a23e8
+2026-07-29-human-transcript-append-origin.zh.md: b8fe6f6e4b9b5298f9d07bdf395e33e33b4a200d
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
index 9804d3d8d6..fe60ab6e74 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-29-human-transcript-append-origin.zh.md)
 
 ## Problem
 
-The terminal and the host history gateway both treated the model-visible surface as the human transcript. A successful compaction replaces a surface range with one checkpoint node, so the moment that replacement landed the terminal dropped every message it shadowed — conversation the user had already read — and re-ran that destructive rebuild on any later replacement. The same confusion reached pagination: `maxMessages` counted every `user/message` and `assistant/message` in the window, so a model-only replacement copy consumed a page slot the human never filled, and the cut could land between a compaction's log-only provenance and the replacement that cites it.
+The terminal and the host history gateway both treated the model-visible surface as the human transcript. A successful compaction replaces a surface range with one checkpoint node, so the moment that replacement landed the terminal dropped every message it shadowed — conversation the user had already read — and re-ran that destructive rebuild on any later replacement. The same confusion reached pagination: `maxMessages` counted every `user/message` and `assistant/message` in the window, so a model-only replacement copy consumed a page slot the human never filled, and the cut could land between a compaction's log-only `compact/summary` event and the replacement that cites it.
 
 Nothing was lost from the log. `Session.events` still held every original message and full tool result; the surface only decides what the model is sent next. The defect was entirely in the projection.
 
@@ -18,13 +18,13 @@ The terminal replays the transcript from append-origin surface events and keeps
 
 A checkpoint is recognized through the compaction seam's own contract — `isCompactCheckpointSource`, the backend-independent marker `CompactService` requires on the replacement user message — so the terminal depends on the declared vocabulary, not on the shape of the replacement. `dsh-session-reference` already consumes that predicate to project another session's log; this is the same question asked by a different reader. Other replacements are silent: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary in the conversation.
 
-`session.history` counts only append-origin messages toward `maxMessages`. Each page remains one contiguous raw event range, so a compaction's `compact/summary` provenance stays on the page of the replacement that cites it.
+`session.history` counts only append-origin messages toward `maxMessages`. Each page remains one contiguous raw event range, so a compaction's `compact/summary` event stays on the page of the replacement that cites it.
 
 No persisted event, RPC envelope, compaction transaction, or model-visible surface changed, and no migration is required.
 
 ## Deferred
 
-The browser client is fixed separately, in [the web transcript projection note](2026-07-30-web-transcript-log-ordered-projection.md): it projects the same append-origin transcript in log order and renders a marker component, and it closes the pagination hole this change opened — because `session.history` no longer spends quota on the checkpoint, it never cuts on the checkpoint's provenance group, so a page can carry a checkpoint citing a `surfaceOp.start` outside the window, which the browser's surface fold rejected. That hole predates this change (counting could already run past a checkpoint into the range it shadows), but the old rule accidentally covered the case where the checkpoint was the oldest counted message and pulled the whole shadowed range onto its page.
+The browser client is fixed separately, in [the web transcript projection note](2026-07-30-web-transcript-log-ordered-projection.md): it projects the same append-origin transcript in log order and renders a marker component, and it closes the pagination hole this change opened — because `session.history` no longer spends quota on the checkpoint, it never cuts on the checkpoint and its cited source events as a unit, so a page can carry a checkpoint citing a `surfaceOp.start` outside the window, which the browser's surface fold rejected. That hole predates this change (counting could already run past a checkpoint into the range it shadows), but when the checkpoint was the oldest counted message, the old pagination rule happened to include the whole shadowed range on the same page.
 
 The terminal's [archived live compaction progress decision](../../archived/feature/2026-07-30-compaction-progress-visibility.md) uses standalone bracket events to drive the existing one-cell indicator. It does not change the completion marker owned here or add scale: the checkpoint's `sourceEventSeqs` remain available for a separately justified count or range. Progress therefore needs neither marker-content changes nor a prerequisite `renderReplacement(event)` extraction.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
index 030be076be..b8fe6f6e4b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-终端与宿主历史网关都把模型可见的 surface 当作人类可读记录（transcript）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message` 和 `assistant/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志溯源信息与引用它的替换之间。
+终端与宿主历史网关都把模型可见的 surface 当作人类可读记录（transcript）。一次成功的压缩（compaction）会用一个检查点节点替换一段 surface 范围，因此该替换一落地，终端就丢弃了它所遮蔽的每条消息——那些是用户已经读过的对话——并在此后任何替换到来时重新执行这次破坏性重建。同样的混淆也波及分页：`maxMessages` 统计窗口内的每个 `user/message` 和 `assistant/message`，于是仅供模型使用的替换副本占用了一个人类从未填充的页面额度，而切分点还可能落在压缩的仅日志 `compact/summary` 事件与引用它的替换之间。
 
 日志本身没有丢失任何内容。`Session.events` 仍保存着每条原始消息和完整的工具结果；surface 只决定接下来发送给模型的内容。缺陷完全在投影层。
 
@@ -18,13 +18,13 @@ Status: implemented
 
 检查点通过压缩接缝自身的约定来识别——`isCompactCheckpointSource`，即 `CompactService` 要求替换用户消息携带的、与后端无关的标记——因此终端依赖的是已声明的词汇，而不是替换的形态。`dsh-session-reference` 已经在用该谓词投影另一个会话的日志；这里只是另一个读者提出同样的问题。其他替换保持静默：被裁剪的 `tool/result` 与重新生成的 `assistant/message` 只是为模型重写一个节点，并不在对话中标出边界。
 
-`session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 溯源信息会与引用它的替换留在同一页。
+`session.history` 只把追加来源的消息计入 `maxMessages`。每一页仍是一段连续的原始事件区间，因此压缩的 `compact/summary` 事件会与引用它的替换留在同一页。
 
 持久事件、RPC 信封、压缩事务与模型可见的 surface 都没有变化，也不需要迁移。
 
 ## Deferred
 
-浏览器客户端在[Web 记录投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份 append 来源记录并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会按检查点的溯源分组切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝该范围。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但旧规则恰好覆盖了这样一种情形：检查点是最旧的被计数消息，其溯源分组把整段被遮蔽的范围一起拉到该页。
+浏览器客户端在[Web 记录投影笔记](2026-07-30-web-transcript-log-ordered-projection.md)中单独修复：它按日志顺序投影同一份 append 来源记录并渲染一个标记组件，同时闭合本次变更打开的分页缺口——因为 `session.history` 不再为检查点消耗额度，它永远不会在检查点与检查点引用的来源事件这个整体内切分，于是一页可以携带一个引用了窗口之外 `surfaceOp.start` 的检查点，而浏览器的 surface fold 会拒绝该范围。这个缺口早于本次变更（此前计数就可能越过检查点进入它所遮蔽的范围），但当检查点是最旧的被计数消息时，旧分页规则会把整段被遮蔽的范围放在同一页。
 
 终端的[已归档实时压缩进度决策](../../archived/feature/2026-07-30-compaction-progress-visibility.md)使用独立标记对中的事件驱动现有的单格指示器。它既不改变本文所负责的完成标记，也不添加规模信息：检查点的 `sourceEventSeqs` 仍可供经另行论证的计数或区间使用。因此，进度显示既不需要修改标记内容，也不以提取 `renderReplacement(event)` 为前置条件。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
index fdb487f16b..7bedb71288 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.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 .agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
-2026-07-29-sticky-composer-conversation-scroll.md: 8657080078e475d6e90f17a6c0f8cb5b2fb1555d
+2026-07-29-sticky-composer-conversation-scroll.md: d628e10979318ba371d56f61c5e96363b4135ad7
 2026-07-29-sticky-composer-conversation-scroll.zh.md: a588903adf51c6fcdd01f851d4f5e6570f695242
diff --git a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
index 8657080078..d628e10979 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
@@ -26,7 +26,7 @@ Chat history prepend follows reader intent through stable rendered node/call ide
 
 **Keep StatsLine inside ChatView below the message column.** Rejected: outside the sticky composer it would scroll away while the input stayed pinned.
 
-**Model every browser scroll input source.** Rejected for this narrow fix: the reproduced desktop path uses wheel/trackpad input. Pointer/touch scrolling, native-scrollbar dragging, keyboard scrolling, focus navigation, and nested overflow ownership were left outside the provenance model instead of adding a general input state machine. The [reader-scroll-attribution note](2026-08-06-reader-scroll-attribution-observed-top-ledger.md) later closed this deferral by generalizing attribution through the observed-top ledger, still without an input state machine.
+**Model every browser scroll input source.** Rejected for this narrow fix: the reproduced desktop path uses wheel/trackpad input. Pointer/touch scrolling, native-scrollbar dragging, keyboard scrolling, focus navigation, and nested overflow ownership were left outside the input-source model instead of adding a general input state machine. The [reader-scroll-attribution note](2026-08-06-reader-scroll-attribution-observed-top-ledger.md) later closed this deferral by generalizing attribution through the observed-top ledger, still without an input state machine.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index 17c4315966..a14b575c0f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: 3b7aaeb1178ff79e38a1b9646a9dc78efaeae48b
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 024d7dba7db7f06a684f5656abf7421e65cd4536
+2026-07-30-web-transcript-log-ordered-projection.md: dbc3f9e23be9120df62c2b6b7a9d9aba4c3a42a9
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 329392c47d69c4cf3506a5e14ca0ef48d35dce4c
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index 3b7aaeb117..dbc3f9e23b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -18,7 +18,7 @@ Node order is seq-monotonic by construction, and three things follow. The log-on
 
 `foldDegraded` is gone from `ConversationSnapshot`, and with it the padding sentinels, the `baseSeq` arithmetic they needed, and `degradedSeqs()`. They existed only to satisfy the core fold's `seq === index` assertion and to survive its throw; the fold they describe is no longer run. Deleting the flag is part of the fix, not cleanup after it — `degradedSeqs()` was already almost the log-ordered projection, reached after a thrown error instead of intended.
 
-The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's own `compact/summary` provenance, never from the framed checkpoint payload, which is an instruction envelope written for the model. A window cut that left the provenance outside makes those fields unavailable, the same soft-fall as a call-less tool result, and a later page supplying the provenance resolves them.
+The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's cited `compact/summary` event, never from the framed checkpoint payload, which is an instruction envelope written for the model. A window cut that left that event outside makes those fields unavailable, the same soft-fall as a call-less tool result, and a later page supplying the event resolves them.
 
 The [manual compaction command](../feature/2026-07-30-queued-manual-compaction.md) returns the summary event's seq as the successful `CommandResult.sourceEventSeq`, and `command/done` persists that optional reference. Chat pairs only a successful named `/compact` command whose reference equals exactly one loaded `CompactionSummaryNode.summaryEventSeq`. The running command first renders `compact · Compacting context…`; after the checkpoint lands, the same React key renders one collapsed `compact` disclosure at the checkpoint's flow position with the count and token estimate. Input rejection, no compactable history, cancellation, and failure remain generic command rows with complete handler-authored text. Automatic compaction has no command reference and keeps the standalone context-compacted marker.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 024d7dba7d..329392c47d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -18,7 +18,7 @@ surface 顺序还让另外两个问题成为结构性的。一次替换之后它
 
 `foldDegraded` 从 `ConversationSnapshot` 消失，随之消失的是哨兵填充、它们所需的 `baseSeq` 算术，以及 `degradedSeqs()`。它们的存在只为满足核心 fold 的 `seq === index` 断言并在其抛错时存活；它们所描述的 fold 已不再运行。删除该标志是修复的一部分，而非修复之后的清理——`degradedSeqs()` 本身已几乎就是按日志顺序的投影，只是作为抛错后的落点而非本意到达。
 
-标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点自己的 `compact/summary` 溯源，绝不取自成框的检查点载荷——那是为模型撰写的指令信封。窗口切分把溯源留在窗口外时这些字段不可用，与无调用的工具结果同一种软退让；后续补上溯源的分页会解析出它们。
+标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点引用的 `compact/summary` 事件，绝不取自成框的检查点载荷——那是为模型撰写的指令信封。窗口切分把该事件留在窗口外时这些字段不可用，与无调用的工具结果同一种软退让；后续补上该事件的分页会解析出它们。
 
 [手动压缩命令](../feature/2026-07-30-queued-manual-compaction.md)会把摘要事件的 seq 作为成功结果的 `CommandResult.sourceEventSeq` 返回，`command/done` 则持久化这项可选引用。Chat 只会配对成功且名称为 `/compact`、其引用恰好等于唯一一个已加载 `CompactionSummaryNode.summaryEventSeq` 的命令。运行中的命令先渲染为 `compact · Compacting context…`；检查点落地后，同一个 React key 会在检查点的消息流位置渲染一条收起的 `compact` 展开项，并显示条目数量和 token 估算值。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行，并保留处理器撰写的完整文本。自动压缩没有命令引用，继续使用独立的上下文已压缩标记。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
index 8aab23d8a2..ac37eaded2 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.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 .agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
-2026-08-04-load-pre-react-loop-sessions.md: b7dcad1ff7fe0aa8239ac03f52b50dfa55417515
-2026-08-04-load-pre-react-loop-sessions.zh.md: 9dc8666d301b3baf454079498bf3ad7e1f510c96
+2026-08-04-load-pre-react-loop-sessions.md: 277a481f366f1182fd3948caf858607efd550e5e
+2026-08-04-load-pre-react-loop-sessions.zh.md: 0d21ef1a97c5e841609406b9c8ed4723e6da09b1
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
index b7dcad1ff7..277a481f36 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md
@@ -24,7 +24,7 @@ The importer does not synthesize inbox splices. A resumed pre-react-loop agent b
 
 **Replay old inbox notifications into durable splices.** Those notifications were not session events and do not provide a trustworthy pending-state snapshot. Inferring insertions without every claim and discard would re-run consumed work.
 
-**Assign coarse aborted records to an existing caller.** Mapping them to `user`, `parent`, or `hook` would manufacture provenance. A dedicated `legacy` cause keeps the stop classification without making a false audit claim.
+**Assign coarse aborted records to an existing caller.** Mapping them to `user`, `parent`, or `hook` would invent a caller that the old record did not name. A dedicated `legacy` cause keeps the stop classification without making a false audit claim.
 
 **Rewrite stored JSONL and SQLite records.** A rewrite would violate the append-only contract and require backend-specific atomic migration machinery for a read compatibility boundary.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
index 9dc8666d30..0d21ef1a97 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.zh.md
@@ -24,7 +24,7 @@ react-loop 简化在保持 `SESSION_FORMAT_VERSION` 为 0 的同时更改了持
 
 **将旧 inbox 通知回放为持久 splice。** 这些通知不是会话事件，也无法提供可信的待处理状态快照。如果无法获知每一次领取和丢弃，就推断插入操作，会让已消费的工作再次执行。
 
-**将粗粒度中止记录归因于现有调用方。** 将其映射到 `user`、`parent` 或 `hook` 会虚构来源。专用的 `legacy` 原因既能保留停止分类，也不会产生虚假的审计事实。
+**将粗粒度中止记录归因于现有调用方。** 将其映射到 `user`、`parent` 或 `hook` 会凭空指定旧记录未注明的调用方。专用的 `legacy` 原因既能保留停止分类，也不会产生虚假的审计事实。
 
 **重写已存储的 JSONL 和 SQLite 记录。** 重写会违反仅追加约定，并要求为读取兼容边界建立后端专用的原子迁移机制。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
index dfaaea4ab7..1c3faea34f 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.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 .agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
-2026-08-05-context-meter-blind-to-compaction.md: 8f4845c3c9bf52c5c3a2d39dee2ff25bda30c7bd
-2026-08-05-context-meter-blind-to-compaction.zh.md: 94ada0a9118db63876d5805ef5a8197d9c764102
+2026-08-05-context-meter-blind-to-compaction.md: 10ded250cec9c92d90803bdf5969cc7f5aa54c50
+2026-08-05-context-meter-blind-to-compaction.zh.md: 1508a907e6a71b465a2b9aed137f40bb8e539ae5
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
index 8f4845c3c9..10ded250ce 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.md
@@ -27,7 +27,7 @@ This reverses the "the ring, header, and bar length stay provider-exact" half of
 
 ## Alternatives considered
 
-**Project `measure().totalTokens` instead.** The measurement service already composes exactly this (`baseline` anchor plus signed `surfaceDeltaTokens`), and it reacts correctly — measured at 4383 → 304 across the same compaction. But it is a service over private replay state, not a pure fold, and a projection cannot call it. Reproducing its anchor inside a `ProjectionDefinition` needs `_estimateProviderAssistant`'s random access to the chunk provenance (`session.events[seq]`), which `apply(state, event)` does not have. Anchoring on the sampled surface total is the same idea reachable from a pure per-event fold.
+**Project `measure().totalTokens` instead.** The measurement service already composes exactly this (`baseline` anchor plus signed `surfaceDeltaTokens`), and it reacts correctly — measured at 4383 → 304 across the same compaction. But it is a service over private replay state, not a pure fold, and a projection cannot call it. Reproducing its anchor inside a `ProjectionDefinition` needs `_estimateProviderAssistant`'s random access to the chunk events cited by seq (`session.events[seq]`), which `apply(state, event)` does not have. Anchoring on the sampled surface total is the same idea reachable from a pure per-event fold.
 
 **Emit a synthetic usage record at the end of compaction.** Would move `pressureTokens` itself, but the only usage compaction holds is the summarization request's own — a different prompt entirely. Recording it as the conversation's prompt size would be a lie in the durable log rather than in one display.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
index 94ada0a911..1508a907e6 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-05-context-meter-blind-to-compaction.zh.md
@@ -27,7 +27,7 @@ AFTER  compact:  ring=4%  header=~4227/100000   rows=[system 18, tools 0, messag
 
 ## 备选方案
 
-**改为投影 `measure().totalTokens`。** 测量服务本来就合成了正是这个量（`baseline` 锚点加有符号的 `surfaceDeltaTokens`），而且反应正确——同一次压缩前后实测为 4383 → 304。但它是一个建立在私有重放状态上的服务，不是纯折叠，投影无法调用它。要在 `ProjectionDefinition` 内部复现它的锚点，需要 `_estimateProviderAssistant` 对分片来源的随机访问（`session.events[seq]`），而 `apply(state, event)` 拿不到。以取样时的表层总量作为锚点，是同一个思路在纯逐事件折叠中可达的版本。
+**改为投影 `measure().totalTokens`。** 测量服务本来就合成了正是这个量（`baseline` 锚点加有符号的 `surfaceDeltaTokens`），而且反应正确——同一次压缩前后实测为 4383 → 304。但它是一个建立在私有重放状态上的服务，不是纯折叠，投影无法调用它。要在 `ProjectionDefinition` 内部复现它的锚点，需要 `_estimateProviderAssistant` 对按 seq 引用的分片事件进行随机访问（`session.events[seq]`），而 `apply(state, event)` 拿不到。以取样时的表层总量作为锚点，是同一个思路在纯逐事件折叠中可达的版本。
 
 **在压缩结束时补写一条合成的用量记录。** 这确实能推动 `pressureTokens` 本身，但压缩手上唯一的用量是摘要请求自己的用量——那是完全另一个提示词。把它记成本对话的提示词规模，等于把谎言写进持久日志，而不只是写进某一处展示。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
index 2982e05c65..d7e6553fd3 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.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 .agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
-2026-08-06-reader-scroll-attribution-observed-top-ledger.md: 2dcd0178e4216d4d3e2edcd3bfcc05b63606c333
+2026-08-06-reader-scroll-attribution-observed-top-ledger.md: ef5ddbeb9bea1393f474dfb4c809ae2e19bfea5c
 2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.md: 7a1142cdd793cfce46bfd3908ab28345701aec7a
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
index 2dcd0178e4..ef5ddbeb9b 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-reader-scroll-attribution-observed-top-ledger.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-06-reader-scroll-attribution-observed-top-ledger.zh.m
 
 ## Problem
 
-ChatView's bottom-follow recognized only wheel/trackpad gestures as reader input: while pinned to the floor, a scroll event without matching wheel movement was treated as programmatic and snapped back. Touch panning, native-scrollbar dragging, and keyboard paging therefore could not leave the bottom of a streaming transcript — on a phone the tail was effectively locked. That wheel-only provenance was a deliberate deferral in the [sticky-composer note](2026-07-29-sticky-composer-conversation-scroll.md), which rejected a general input state machine "for this narrow fix" and left every other scroll source outside the model.
+ChatView's bottom-follow recognized only wheel/trackpad gestures as reader input: while pinned to the floor, a scroll event without matching wheel movement was treated as programmatic and snapped back. Touch panning, native-scrollbar dragging, and keyboard paging therefore could not leave the bottom of a streaming transcript — on a phone the tail was effectively locked. That wheel-only input classification was a deliberate deferral in the [sticky-composer note](2026-07-29-sticky-composer-conversation-scroll.md), which rejected a general input state machine "for this narrow fix" and left every other scroll source outside the model.
 
 ## Decision
 
@@ -34,4 +34,4 @@ The lane's Chromium cannot synthesize any non-wheel device scrolling, which boun
 
 ## Consequences
 
-Every reader input owns bottom-follow uniformly, with less code: the wheel listener, its epoch counter, and the pre-input baseline bookkeeping are gone, and attribution rides state the component already maintained. The sticky-composer note's layout, wheel chaining, and prepend-anchoring decisions are untouched and remain authoritative; its narrow provenance rule is superseded by this note. The cost is the contract change above — a coalesced non-React shrink-plus-regrow clamp now pauses follow until the reader returns to the floor or presses Back to bottom — traded for touch, scrollbar, and keyboard correctness during streaming. The e2e lane gains non-wheel coverage only within what its browser can synthesize; if gesture synthesis starts working in a future Chromium, the fling emulation can be replaced by real touch strokes without changing the asserted contract.
+Every reader input owns bottom-follow uniformly, with less code: the wheel listener, its epoch counter, and the pre-input baseline bookkeeping are gone, and attribution rides state the component already maintained. The sticky-composer note's layout, wheel chaining, and prepend-anchoring decisions are untouched and remain authoritative; its wheel-only input rule is superseded by this note. The cost is the contract change above — a coalesced non-React shrink-plus-regrow clamp now pauses follow until the reader returns to the floor or presses Back to bottom — traded for touch, scrollbar, and keyboard correctness during streaming. The e2e lane gains non-wheel coverage only within what its browser can synthesize; if gesture synthesis starts working in a future Chromium, the fling emulation can be replaced by real touch strokes without changing the asserted contract.
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index 60a89e6fab..c23637d7e3 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.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 .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: 390d091fd6e6f7fa1694ba78b90522b70948fe92
-2026-06-18-compaction-capability-seam.zh.md: 297b9adda4f13f6fd4da9e73bf2bcf3d8d6ead0c
+2026-06-18-compaction-capability-seam.md: fa9325d08fa73dd1654216d211abb03cdf1a0940
+2026-06-18-compaction-capability-seam.zh.md: d8522f3714211f23bafb201e7354e8b0fc2f5fb1
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index 390d091fd6..fa9325d08f 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
@@ -8,7 +8,7 @@ English | [中文](2026-06-18-compaction-capability-seam.zh.md)
 
 A long-running agent conversation grows without bound. As the event log accumulates turns, the derived message history eventually approaches the model's context window — the model then truncates mid-response (`max-tokens`) or degrades. **Compaction** is the mitigation: replace a run of older history with a concise summary, keeping recent context intact.
 
-The [session surface](../architecture/2026-06-18-session-surface.md) was built as the foundation for exactly this — an ordered projection over the event log with a `surfaceOp: { op: 'replace', start, end }` operation purpose-built to shadow a range of entries and insert a replacement, with `sourceEventSeqs` recording provenance so the decision replays deterministically. What remained was the plugin that *decides what to compact and produces the summary*.
+The [session surface](../architecture/2026-06-18-session-surface.md) was built as the foundation for exactly this — an ordered projection over the event log with a `surfaceOp: { op: 'replace', start, end }` operation purpose-built to shadow a range of entries and insert a replacement, with `sourceEventSeqs` listing every source event so replay can validate that the replacement cites every event it removes. What remained was the plugin that *decides what to compact and produces the summary*.
 
 Two forces shape the design. First, compaction policy and reusable token measurement vary independently: measurement belongs to the LLM-family [`ctx.tokenMeter` service](../architecture/2026-07-15-replay-token-meter-service.md), while summarization can be a model call, a template, or a remote service. Second, `SurfaceEventType` is closed to the message-producing event types (`user/message`, `assistant/message`, `tool/result`); only those may carry `surfaceOp`. A bespoke `compaction/*` event therefore **cannot** itself appear on the surface — the compiler and Session's always-on append/seed boundary reject `surfaceOp` on it.
 
@@ -71,12 +71,12 @@ Auto-compaction always starts at the surface head, merging the prior checkpoint
 
 ### Surface replacement: `compact/*` events are log-only; one `user/message` carries the summary
 
-Because `SurfaceEventType` is closed, the summary cannot ride on a `compact/*` event. The backend instead appends a **single `user/message`** with `source: COMPACT_CHECKPOINT_SOURCE` and `surfaceOp: { op: 'replace', start, end }` whose `content` is the (framed) summary and whose `sourceEventSeqs` covers the shadowed entries *and* the bookkeeping events. The interface exports that source and `isCompactCheckpointSource()` so consumers recognize a persisted or cloned checkpoint without depending on backend package identity. The `compact/*` events are pure log records (lock + provenance). The surface mutation sits **inside** the lock — `compact/end` is the last event appended:
+Because `SurfaceEventType` is closed, the summary cannot ride on a `compact/*` event. The backend instead appends a **single `user/message`** with `source: COMPACT_CHECKPOINT_SOURCE` and `surfaceOp: { op: 'replace', start, end }` whose `content` is the (framed) summary and whose `sourceEventSeqs` covers the shadowed entries *and* the bookkeeping events. The interface exports that source and `isCompactCheckpointSource()` so consumers recognize a persisted or cloned checkpoint without depending on backend package identity. The `compact/*` events record the lock, summary, selected range, shadowed seqs, token count, and model call without joining the surface. The surface mutation sits **inside** the lock — `compact/end` is the last event appended:
 
 ```
 compact/start    → log-only. Acquires the lock.
 [summarize older range via the backend]
-compact/summary  → log-only. Provenance: raw summary, local-call marker, range, shadowed seqs, token count.
+compact/summary  → log-only. Records the raw summary, local-call marker, range, shadowed seqs, and token count.
 user/message     → canonical checkpoint source + surfaceOp { op:'replace', start, end }.
                    THE surface mutation (framed summary).
                    deriveMessages() renders it as a user-role message.
@@ -93,7 +93,7 @@ The basic backend wraps the summary as established checkpoint context and tags i
 
 The `compact/start … compact/end` bracket is justified by two roles:
 
-1. **Crash-detectable orphan + provenance** (primary). Summarization is a slow model call persisted *after* `compact/start`. A crash mid-summarization leaves a `compact/start` with no matching `compact/end` — a detectable orphan. Releasing the lock last (rather than first) converts the crash window from *silent corruption* into that detectable orphan.
+1. **Crash-detectable orphan plus recorded summary inputs** (primary). Summarization is a slow model call persisted *after* `compact/start`. A crash mid-summarization leaves a `compact/start` with no matching `compact/end` — a detectable orphan. Releasing the lock last (rather than first) converts the crash window from *silent corruption* into that detectable orphan.
 2. **Prevents concurrent compaction.** Every automatic, manual, and explicit-range entry point refuses a live unmatched `compact/start`. The bracket is the single lock; no process-local mutex duplicates it.
 
 The lock excludes another compaction, not unrelated facts. Its markers are time points rather than an exclusive container, so durable inbox splices may appear between a standalone manual start and end. Automatic work requires whole-surface stability inside its turn. Manual work revalidates only the selected positional span, letting append-only context outside it remain visible after replacement.
@@ -122,7 +122,7 @@ The lifecycle boundary makes crash state unambiguous:
 - **Automatic seams**: `agent/pre-step` (`@mode waterfall`) handles pressure before request derivation and `agent/request-error` (`@mode waterfall`) handles final request failures after the failed step closes. The pre-step payload carries the claimed batch, turn, step, and signal (see the [payload-object events decision](../architecture/2026-08-06-agent-event-payload-objects.md)), with no compaction-only prompt/prefix payload.
 - **`SessionEventMap`** gains `compact/start` / `compact/summary` / `compact/end` by declaration merging (merge-extensible); `SurfaceEventType` is **not** touched. These are session events, not cordis `Events`, so the event-taxonomy gate needs no entry.
 - **`dsh-compact`** owns `COMPACT_CHECKPOINT_SOURCE`, `isCompactCheckpointSource(source)`, `toolPairingBalancedBefore(session, seq)`, and `toolPairingBalancedAfter(session, seq)`. The marker identifies replacement summaries across backend implementations. The cached surface-edge checks prevent `compactRegion` and `compactIfNeeded` from splitting a tool-call/result pair, validate current membership by seq, answer both edges from one per-cut balance sequence, and reject stale or missing seqs and orphan results.
-- **`dsh-session`** validates positional replacement, complete provenance, and content-only single-node `tool/result` rewrites through its one surface manager. Its invariant companion treats fresh appended tool results as executions that require an open step and pending call, while the compaction companion owns numeric-turn versus standalone-null bracket relations.
+- **`dsh-session`** validates positional replacement, complete cited source-event coverage, and content-only single-node `tool/result` rewrites through its one surface manager. Its invariant companion treats fresh appended tool results as executions that require an open step and pending call, while the compaction companion owns numeric-turn versus standalone-null bracket relations.
 - **Wiring**: `examples/tui-agent/cordis.yml` loads zero-config `dsh-token-meter`, `dsh-compact-tool-result-prune`, `dsh-compact-basic`, then `dsh-command-compact`; service-wide defaults make the composition usable without repeated numeric policy.
 
 ## Testing
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index 297b9adda4..d8522f3714 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 长时间运行的 agent（智能体）对话会无限增长。随着事件日志不断累积轮次，派生出的消息历史最终逼近模型的上下文窗口，模型随即截断响应（`max-tokens`）或性能退化。**上下文压缩（context compaction）** 是对此的缓解手段：用一段简洁的摘要替换一批较早的历史，保持近期上下文完整。
 
-[会话接口面](../architecture/2026-06-18-session-surface.md)正是为此而构建的基础设施：一份建立在事件日志之上的有序投影，带有专门设计的 `surfaceOp: { op: 'replace', start, end }` 操作，用于遮蔽一段条目并插入替换内容，`sourceEventSeqs` 记录溯源信息以便决策可确定性地回放。剩下的是那个*决定压缩什么、并产出摘要*的插件。
+[会话接口面](../architecture/2026-06-18-session-surface.md)正是为此而构建的基础设施：一份建立在事件日志之上的有序投影，带有专门设计的 `surfaceOp: { op: 'replace', start, end }` 操作，用于遮蔽一段条目并插入替换内容，`sourceEventSeqs` 列出每个来源事件，使回放可以验证替换是否引用了它移除的每个事件。剩下的是那个*决定压缩什么、并产出摘要*的插件。
 
 两股力量塑造了设计。第一，压缩策略与可复用的 token 测量独立变化：测量归 LLM 系列的 [`ctx.tokenMeter` 服务](../architecture/2026-07-15-replay-token-meter-service.md)所有，摘要生成则可以使用模型调用、模板或远程服务。第二，`SurfaceEventType` 封闭为产生消息的事件类型（`user/message`、`assistant/message`、`tool/result`）；只有这些类型可以携带 `surfaceOp`。因此一个专用的 `compaction/*` 事件**不能**出现在 surface 上，编译器与 Session 始终启用的 append/seed 边界都会拒绝在其上附加 `surfaceOp`。
 
@@ -71,12 +71,12 @@ retry → next numbered step/start      ⟵ derives from the replacement surface
 
 ### Surface 替换：`compact/*` 事件仅存在于日志；一条 `user/message` 承载摘要
 
-由于 `SurfaceEventType` 是封闭的，摘要不能搭载在 `compact/*` 事件上。后端改为追加一条**单独的 `user/message`**，带有 `source: COMPACT_CHECKPOINT_SOURCE` 和 `surfaceOp: { op: 'replace', start, end }`；其 `content` 是（带框架的）摘要，`sourceEventSeqs` 覆盖被遮蔽的条目*和*簿记事件。接口导出该来源和 `isCompactCheckpointSource()`，使消费方无需依赖后端包身份，即可识别持久化或克隆得到的检查点。`compact/*` 事件是纯日志记录（锁 + 溯源信息）。surface 变更位于锁**内部**，`compact/end` 是最后追加的事件：
+由于 `SurfaceEventType` 是封闭的，摘要不能搭载在 `compact/*` 事件上。后端改为追加一条**单独的 `user/message`**，带有 `source: COMPACT_CHECKPOINT_SOURCE` 和 `surfaceOp: { op: 'replace', start, end }`；其 `content` 是（带框架的）摘要，`sourceEventSeqs` 覆盖被遮蔽的条目*和*簿记事件。接口导出该来源和 `isCompactCheckpointSource()`，使消费方无需依赖后端包身份，即可识别持久化或克隆得到的检查点。`compact/*` 事件记录锁、摘要、选中区间、被遮蔽的 seq、token 数和模型调用，但不加入 surface。surface 变更位于锁**内部**，`compact/end` 是最后追加的事件：
 
 ```
 compact/start    → log-only. Acquires the lock.
 [summarize older range via the backend]
-compact/summary  → log-only. Provenance: raw summary, local-call marker, range, shadowed seqs, token count.
+compact/summary  → log-only. Records the raw summary, local-call marker, range, shadowed seqs, and token count.
 user/message     → canonical checkpoint source + surfaceOp { op:'replace', start, end }.
                    THE surface mutation (framed summary).
                    deriveMessages() renders it as a user-role message.
@@ -93,7 +93,7 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 
 `compact/start … compact/end` 标记对承担两项职责：
 
-1. **可检测的崩溃孤儿 + 来源追溯**（首要）。摘要生成是一次慢速模型调用，持久化在 `compact/start` *之后*。摘要生成中途崩溃会留下一个没有匹配 `compact/end` 的 `compact/start`——一个可检测的孤儿。最后释放锁（而非最先）将崩溃窗口从*静默损坏*转变为可检测的孤儿。
+1. **可检测的崩溃孤儿 + 已记录的摘要输入**（首要）。摘要生成是一次慢速模型调用，持久化在 `compact/start` *之后*。摘要生成中途崩溃会留下一个没有匹配 `compact/end` 的 `compact/start`——一个可检测的孤儿。最后释放锁（而非最先）将崩溃窗口从*静默损坏*转变为可检测的孤儿。
 2. **防止并发压缩。** 每个自动、手动和显式范围入口点都会拒绝活动的未匹配 `compact/start`。该标记对就是唯一的锁；没有进程本地 mutex 重复承担同一职责。
 
 该锁只排除另一项压缩，不排除无关事实。其标记是时间点，而不是排他的容器，因此持久 inbox splice 可以出现在独立手动 start 与 end 之间。自动工作要求其轮次内的整个 surface 保持稳定。手动工作只重新验证所选位置 span，使其外部的仅追加上下文在替换后保持可见。
@@ -122,7 +122,7 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 - **自动 seam**：`agent/pre-step`（`@mode waterfall`）在请求派生前处理压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。pre-step 的 payload 携带已领取批次、轮次、步骤与 signal（参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)），不携带压缩专属的提示词/前缀 payload。
 - **`SessionEventMap`** 通过可合并扩展的声明合并获得 `compact/start` / `compact/summary` / `compact/end`；`SurfaceEventType` **未被**触及。这些是会话事件，不是 cordis `Events`，因此事件分类门禁无需新增条目。
 - **`dsh-compact`** 拥有 `COMPACT_CHECKPOINT_SOURCE`、`isCompactCheckpointSource(source)`、`toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`。该标记用于跨后端实现识别替换摘要。带缓存的 surface 边缘检查会防止 `compactRegion` 和 `compactIfNeeded` 拆分工具调用/结果对，按 seq 校验当前成员关系，从每个切割点的一条平衡序列回答两侧边缘，并拒绝陈旧或缺失的 seq 与孤立结果。
-- **`dsh-session`** 通过唯一的 surface 管理器校验位置替换、完整溯源信息和仅内容的单节点 `tool/result` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用，而压缩配套组件拥有数字轮次归属与独立 `null` 归属标记对之间的关系。
+- **`dsh-session`** 通过唯一的 surface 管理器校验位置替换、引用的来源事件是否覆盖完整，以及仅内容的单节点 `tool/result` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用，而压缩配套组件拥有数字轮次归属与独立 `null` 归属标记对之间的关系。
 - **接线**：`examples/tui-agent/cordis.yml` 依次加载零配置的 `dsh-token-meter`、`dsh-compact-tool-result-prune`、`dsh-compact-basic`，然后加载 `dsh-command-compact`；服务级默认值使组合无需重复数值策略即可使用。
 
 ## 测试
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 5002872c0b..5982d816f9 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: 06c5590454a6947030d828f087b92f44207dad6e
-2026-07-06-sandbox.zh.md: 85b9b6a65b6468b19c6044b4837abc4fab1cee1a
+2026-07-06-sandbox.md: d73bb5520ffba43142c70e3197ae033db1af67d9
+2026-07-06-sandbox.zh.md: 5fc2ee7c4a53df22fab93c358824a10dca89989e
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index 06c5590454..d73bb5520f 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -70,7 +70,7 @@ Backend profiles share the mode contract but differ in necessary host grants. La
 
 #### The bash consumer
 
-`dsh-bash-sandbox` extends `LocalBashExecutor`, hands `ctx.sandbox` the exact `['bash', '-c', command]` argv, and directly spawns the provider result. This leaves shell semantics and `BASH_ENV` on the inner Bash after the shipped native runner establishes confinement. A provider error propagates unchanged. A pre-process rejection is runner-owned only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with positive provenance for provider argv[0]; a bare `syscall: 'spawn'` without an exact error path, other codes, invalid workdirs, resource failures, unrelated syscalls, and unstructured rejections retain local command-start semantics. Foreground execution converts runner-owned rejections to `SANDBOX_UNAVAILABLE` with the original detail; an asynchronous background rejection stamps `runnerFailed: true`, `denied: false`. A `SubprocessService` that synchronously throws the same provenanced shape makes background start throw `SANDBOX_UNAVAILABLE`, while other synchronous errors propagate unchanged. After a process starts, foreground and background use one runner-failure classifier that requires the rule's exit-code gate and a remaining fatal line after informational exclusions. A match outranks denial: foreground execution throws `SANDBOX_UNAVAILABLE` with that fatal line as detail; a settled `BashProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `task_output`.
+`dsh-bash-sandbox` extends `LocalBashExecutor`, hands `ctx.sandbox` the exact `['bash', '-c', command]` argv, and directly spawns the provider result. This leaves shell semantics and `BASH_ENV` on the inner Bash after the shipped native runner establishes confinement. A provider error propagates unchanged. A pre-process rejection is runner-owned only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` whose error path equals provider argv[0]; a bare `syscall: 'spawn'` without an exact error path, other codes, invalid workdirs, resource failures, unrelated syscalls, and unstructured rejections retain local command-start semantics. Foreground execution converts runner-owned rejections to `SANDBOX_UNAVAILABLE` with the original detail; an asynchronous background rejection stamps `runnerFailed: true`, `denied: false`. A `SubprocessService` that synchronously throws the same shape with the runner path makes background start throw `SANDBOX_UNAVAILABLE`, while other synchronous errors propagate unchanged. After a process starts, foreground and background use one runner-failure classifier that requires the rule's exit-code gate and a remaining fatal line after informational exclusions. A match outranks denial: foreground execution throws `SANDBOX_UNAVAILABLE` with that fatal line as detail; a settled `BashProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `task_output`.
 
 The model sees the current effective file policy in the owner-derived `sandbox:policy` context, while the static tool description explains the denial marker (`[sandbox: file access denied under <mode> mode]`), encourages attempting commands that may be denied, and forbids retrying around a denial; when the escalation fields are advertised, a denied result additionally carries the escalation hint itself, so the sanctioned same-turn retry is prompted at the decision point rather than depending on the model recalling the description (§ Escalation). [The current-policy decision](2026-07-30-current-sandbox-policy-context.md) owns the context's rationale and boundaries.
 
@@ -185,7 +185,7 @@ Costs and accepted limits:
 ## FAQ
 
 - **A command came back with `[sandbox: file access denied under read-only mode]` — did it fail?** It RAN, and the kernel refused a file effect: the denial is a result fact orthogonal to exit code. The teaching forbids retrying around it; the one sanctioned move is the same command retried once with an escalation request.
-- **How is a BROKEN sandbox told apart from a failing command?** Any provider-argv spawn rejection proves the confined launch never started, but it identifies a broken runner only when the caller-owned workdir is usable and Node reports attributable `ENOENT` or `EACCES` for that argv[0]. A bare `syscall: 'spawn'` without an exact error path and all other rejections remain ordinary command-start errors. After a process starts, runner failure outranks denial only when one `runnerFailureRules` entry matches both its optional exit-code gate and a fatal stderr line after exact informational exclusions. Foreground failures throw structured `SANDBOX_UNAVAILABLE` with spawn or matched-line detail; an asynchronously rejected or settled background task stamps `sandbox.runnerFailed` and renders its own marker. A `SubprocessService` that synchronously throws the same provenanced `ENOENT`/`EACCES` shape makes background start throw the structured error; other synchronous errors propagate unchanged. A Landlock partial-enforcement notice plus an ordinary child failure remains a command result.
+- **How is a BROKEN sandbox told apart from a failing command?** Any provider-argv spawn rejection proves the confined launch never started, but it identifies a broken runner only when the caller-owned workdir is usable and Node reports attributable `ENOENT` or `EACCES` for that argv[0]. A bare `syscall: 'spawn'` without an exact error path and all other rejections remain ordinary command-start errors. After a process starts, runner failure outranks denial only when one `runnerFailureRules` entry matches both its optional exit-code gate and a fatal stderr line after exact informational exclusions. Foreground failures throw structured `SANDBOX_UNAVAILABLE` with spawn or matched-line detail; an asynchronously rejected or settled background task stamps `sandbox.runnerFailed` and renders its own marker. A `SubprocessService` that synchronously throws the same `ENOENT`/`EACCES` shape with the runner path makes background start throw the structured error; other synchronous errors propagate unchanged. A Landlock partial-enforcement notice plus an ordinary child failure remains a command result.
 - **What happens on a platform with no backend — Windows today?** `confine()` throws the fail-closed `SANDBOX_UNAVAILABLE` and the command never spawns; `win32` is a reserved EMPTY chain, pinned by test to fail closed identically until a Windows runner fills it (§ Deferred phases).
 - **`bwrap` is installed on my host but unusable (disabled unprivileged userns, an LSM denying `mount`) — what happens?** The chain probe is functional — it builds and enforces a real profile rather than checking `--version` — so a present-but-unusable `bwrap` fails its probe, selection falls to the packaged Landlock launcher, and the verdict is cached for the provider's lifetime.
 - **Does the sandbox restrict network or process visibility?** No — `SandboxMode` claims FILE effects only; the bwrap profile deliberately does not unshare pid, and no backend claims network. Whether network restriction becomes its own knob is left open in § The seam.
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index 85b9b6a65b..5fc2ee7c4a 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -70,7 +70,7 @@ Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 
 
 #### bash 消费方
 
-`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，把精确的 `['bash', '-c', command]` argv 交给 `ctx.sandbox`，并直接 spawn 提供方返回的 argv。这样，随附的原生 runner 建立约束后，shell 语义与 `BASH_ENV` 仍由内层 Bash 处理。提供方错误原样传播。进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且带有明确指向提供方 argv[0] 的来源信息时，拒绝才会归因于 runner；没有精确错误路径的裸 `syscall: 'spawn'`、其他错误码、无效 workdir、资源失败、无关 syscall 与无结构拒绝保留本地命令启动语义。前台执行会将可归因于 runner 的拒绝转为 `SANDBOX_UNAVAILABLE` 并附上原始详细信息；异步后台拒绝则盖章 `runnerFailed: true`、`denied: false`。如果 `SubprocessService` 同步抛出同样带有来源信息的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，前台与后台共用一个 runner 失败分类器：先排除信息性行，再要求规则的退出码门控与余下的一行致命诊断同时匹配。匹配结果优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`，并以该致命行作为详细信息；结算后的 `BashProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `task_output` 渲染它。
+`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，把精确的 `['bash', '-c', command]` argv 交给 `ctx.sandbox`，并直接 spawn 提供方返回的 argv。这样，随附的原生 runner 建立约束后，shell 语义与 `BASH_ENV` 仍由内层 Bash 处理。提供方错误原样传播。进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且错误对象的 `path` 字段等于提供方返回的 `argv[0]` 时，拒绝才会归因于 runner；没有精确错误路径的裸 `syscall: 'spawn'`、其他错误码、无效 workdir、资源失败、无关 syscall 与无结构拒绝保留本地命令启动语义。前台执行会将可归因于 runner 的拒绝转为 `SANDBOX_UNAVAILABLE` 并附上原始详细信息；异步后台拒绝则盖章 `runnerFailed: true`、`denied: false`。如果 `SubprocessService` 同步抛出同样带有 runner 路径的形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，前台与后台共用一个 runner 失败分类器：先排除信息性行，再要求规则的退出码门控与余下的一行致命诊断同时匹配。匹配结果优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`，并以该致命行作为详细信息；结算后的 `BashProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `task_output` 渲染它。
 
 模型会在归属方派生的 `sandbox:policy` 上下文中看到当前有效的文件策略；静态工具描述则解释拒绝标记（`[sandbox: file access denied under <mode> mode]`），鼓励尝试可能被拒绝的命令，并禁止绕过拒绝重试。当升级字段被公布时，被拒绝的结果还会携带升级提示本身，使被认可的同轮次重试在决策点获得提示，而非依赖模型回忆描述（§ 升级机制）。[当前策略决策](2026-07-30-current-sandbox-policy-context.md)负责该上下文的理由与边界。
 
@@ -185,7 +185,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 ## FAQ
 
 - **一个命令返回了 `[sandbox: file access denied under read-only mode]`——它失败了吗？** 它运行了，内核拒绝了一个文件操作：拒绝是与退出码正交的结果事实。相关指令禁止通过绕过限制来重试；唯一被认可的动作是以升级请求重试同一命令一次。
-- **如何区分损坏的沙箱与失败的命令？** 提供方 argv 的任何 spawn 拒绝都能证明受限启动从未开始，但只有在调用方拥有的 workdir 可用，且 Node 为该 argv[0] 报告可归因的 `ENOENT` 或 `EACCES` 时，才能据此判定 runner 损坏。没有精确错误路径的裸 `syscall: 'spawn'` 和其他所有拒绝仍是普通的命令启动错误。进程启动后，只有当 `runnerFailureRules` 中某一条目同时匹配其可选退出码门控，以及排除整行精确信息性行后的一行致命 stderr 诊断时，runner 失败才会优先于拒绝。前台失败会抛出结构化的 `SANDBOX_UNAVAILABLE`，并附带 spawn 错误或匹配行作为详细信息；遭异步拒绝或已结算的后台任务则盖章 `sandbox.runnerFailed` 并渲染自己的标记。如果 `SubprocessService` 同步抛出同样带有来源信息的 `ENOENT`／`EACCES` 形态，后台启动会抛出该结构化错误；其他同步错误原样传播。Landlock 部分强制执行通知加上普通子进程失败时，仍返回命令结果。
+- **如何区分损坏的沙箱与失败的命令？** 提供方 argv 的任何 spawn 拒绝都能证明受限启动从未开始，但只有在调用方拥有的 workdir 可用，且 Node 为该 argv[0] 报告可归因的 `ENOENT` 或 `EACCES` 时，才能据此判定 runner 损坏。没有精确错误路径的裸 `syscall: 'spawn'` 和其他所有拒绝仍是普通的命令启动错误。进程启动后，只有当 `runnerFailureRules` 中某一条目同时匹配其可选退出码门控，以及排除整行精确信息性行后的一行致命 stderr 诊断时，runner 失败才会优先于拒绝。前台失败会抛出结构化的 `SANDBOX_UNAVAILABLE`，并附带 spawn 错误或匹配行作为详细信息；遭异步拒绝或已结算的后台任务则盖章 `sandbox.runnerFailed` 并渲染自己的标记。如果 `SubprocessService` 同步抛出同样带有 runner 路径的 `ENOENT`／`EACCES` 形态，后台启动会抛出该结构化错误；其他同步错误原样传播。Landlock 部分强制执行通知加上普通子进程失败时，仍返回命令结果。
 - **在没有后端的平台上会发生什么——今天的 Windows？** `confine()` 抛出失败关闭的 `SANDBOX_UNAVAILABLE`，命令永不 spawn；`win32` 是保留的空链，由测试固定为同样失败关闭，直到 Windows runner 填充它（§ 延迟阶段）。
 - **`bwrap` 已安装在我的主机上但不可用（禁用了非特权 userns、LSM 拒绝 `mount`）——会发生什么？** 链探测是功能性的——它构建并强制一个真实 profile 而非检查 `--version`——因此存在但不可用的 `bwrap` 探测失败，选择落到已打包的 Landlock launcher，结论在提供方生命周期内缓存。
 - **沙箱限制网络或进程可见性吗？** 不——`SandboxMode` 仅声称文件操作；bwrap profile 刻意不 unshare pid，没有后端声称网络。网络限制是否成为自己的旋钮留在 § seam 中开放。
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
index 2032c54723..3023f86bba 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.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 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
-2026-07-08-self-referential-cordis-toolset.md: a2f614cc5a236e45622eae2b30f518181331cc79
-2026-07-08-self-referential-cordis-toolset.zh.md: 6c56c2bf0c8cc8d175f451290620d9386bb69a23
+2026-07-08-self-referential-cordis-toolset.md: 5fc2fb07fcd0b00bf72c818d3806b298312cdc31
+2026-07-08-self-referential-cordis-toolset.zh.md: 8f34c97d94cad9b79a0e823406c07cdcfb38793f
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
index a2f614cc5a..5fc2fb07fc 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
@@ -75,7 +75,7 @@ The correctness investment therefore goes where it pays for every capability at
 
 **A hand-maintained service/event reference in the tool.** The first cut of the inspect tool carried a hand-written table of service method signatures. It was replaced by the generated `api-catalog.ts` because a hand table drifts from the JSDoc the moment a signature changes and nothing gates the drift, whereas the generated artifact is freshness-checked against the same AST the docs use.
 
-**A new `cordis/mount` session event.** A durable provenance event recording each mount (source, name) has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a full changed request header, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs mount provenance separable from the tool call.
+**A new `cordis/mount` session event.** A durable event recording each mount's source and name has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a full changed request header, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs the mount source and name outside the tool call.
 
 **A hardened / capability-restricted sandbox.** Trapping Node built-ins and handing mount code a whitelist façade rather than the raw context might suggest an intent to sandbox for safety. It is explicitly not that: the traps and the façade narrow the *surface* mount code sees — steering it onto cordis services and away from leak-prone Node built-ins and framework internals — for correctness and to close the unguarded-context escape, but the capabilities the façade exposes (`ctx.bash`, `ctx.fs`, `ctx.web`) reach the real runtime, so it is not a security boundary. A real one (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime.
 
diff --git a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
index 6c56c2bf0c..8f34c97d94 100644
--- a/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.zh.md
@@ -75,7 +75,7 @@ vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节
 
 **在工具中手工维护服务/事件参考。** inspect 工具的第一版携带了一份手写的服务方法签名表。它被生成的 `api-catalog.ts` 取代，因为手写表在签名变化的瞬间就会与 JSDoc 脱节且没有门禁约束这种漂移，而生成产物的新鲜度由文档使用的同一套 AST 检查。
 
-**新增 `cordis/mount` 会话事件。** 一个持久的溯源事件记录每次挂载（源码、名称）有明确先例（`hook/invoked`、`compact/start`）。v1 中予以否决：挂载和卸载已经作为 `tool/call` / `tool/result` 对可见，工具集变化已经作为完整的变更 request header 被记录，因此专用事件只会重复记录。如果审计用例需要将挂载溯源从工具调用中分离出来，日后仍可添加。
+**新增 `cordis/mount` 会话事件。** 一个持久事件记录每次挂载的源码和名称，有明确先例（`hook/invoked`、`compact/start`）。v1 中予以否决：挂载和卸载已经作为 `tool/call` / `tool/result` 对可见，工具集变化已经作为完整的变更 request header 被记录，因此专用事件只会重复记录。如果审计用例需要在工具调用之外取得挂载的源码和名称，日后仍可添加。
 
 **加固的/能力受限的沙箱。** 对 Node 内置模块设陷阱并向挂载代码提供白名单门面而非原始上下文，可能暗示意图是为安全而沙箱化。这里明确不是：陷阱和门面收窄的是挂载代码所见的*接口面*——将其引导至 cordis 服务、远离易泄漏的 Node 内置模块和框架内部——目的是正确性和封堵未受保护的上下文逃逸，但门面暴露的能力（`ctx.bash`、`ctx.fs`、`ctx.web`）触及真实运行时，因此它不是安全边界。真正的安全边界（独立进程、权限提示）超出了一个开发/显式启用工具集的范围，且会与其核心目的——将活跃运行时交给模型——相冲突。
 
diff --git a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml
index f2d337c93c..a1f605b52b 100644
--- a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.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 .agents/notes/implemented/feature/2026-07-13-session-query-tracing.md
-2026-07-13-session-query-tracing.md: 47c12824a331546676d3bc79920f861afe648431
-2026-07-13-session-query-tracing.zh.md: f578a69a3004722395d5b731f82482b8ebd548e5
+2026-07-13-session-query-tracing.md: 66ec68cff116c973c723ee086cdb273f9375842b
+2026-07-13-session-query-tracing.zh.md: 6a39a9857d30ea7911a313bff5504d4f5ae04562
diff --git a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md
index 47c12824a3..66ec68cff1 100644
--- a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md
+++ b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-13-session-query-tracing.zh.md)
 
 ## Problem
 
-Session relationships are encoded across immutable headers, positional surface operations, and logged provenance arrays. A consumer reconstructing those relationships directly would need to duplicate corpus precedence, surface folding, malformed-log handling, deterministic lineage ordering, and cloning. Positional replacement and provenance are different graphs, so collapsing them into one generic edge type would also lose meaning.
+Session relationships are encoded across immutable headers, positional surface operations, and logged arrays of cited source-event seqs. A consumer reconstructing those relationships directly would need to duplicate corpus precedence, surface folding, malformed-log handling, deterministic lineage ordering, and cloning. Positional replacement and cited-source relationships mean different things, so collapsing them into one generic edge type would also lose meaning.
 
 ## Decision
 
@@ -14,20 +14,20 @@ Session relationships are encoded across immutable headers, positional surface o
 
 `SessionLineageTrace` returns the target, known parents in immediate-to-outward order, and recursive descendant trees whose siblings sort by creation time and then session id. `complete: true` carries the known root; `complete: false` carries the first unresolved parent id. A cycle connected to the target fails with `SESSION_QUERY_INVALID_LINEAGE`.
 
-`SessionEventTrace` keeps positional and provenance relationships separate. `replacedBy` is the immediate positional replacer, `replacementChain` follows replacers to the final node, and `replacedEventSeqs` lists the actual surface nodes directly removed by the target. `sourceEventSeqs` preserves direct logged source order, while `derivedEventSeqs` lists later direct reverse references in log order. Provenance is not expanded transitively.
+`SessionEventTrace` keeps positional replacements separate from cited source-event relationships. `replacedBy` is the immediate positional replacer, `replacementChain` follows replacers to the final node, and `replacedEventSeqs` lists the actual surface nodes directly removed by the target. `sourceEventSeqs` preserves direct logged source order, while `derivedEventSeqs` lists later direct reverse references in log order. The query does not follow cited source events transitively.
 
 ## Validation boundary
 
-Event tracing checks target existence before surface analysis. Both event listing and tracing then use `dsh-session`'s one-pass surface fold, which accepts or rejects the loaded log as a whole: event seqs are zero-based and contiguous, surface markers obey event-type eligibility, provenance belongs only to surface event types, present arrays are nonempty and duplicate-free, every source is an earlier seq, and every positional replacement names and cites all surface nodes it removes. Every contract failure uses `SESSION_QUERY_INVALID_SURFACE`; there is no weaker classification-only surface standard.
+Event tracing checks target existence before surface analysis. Both event listing and tracing then use `dsh-session`'s one-pass surface fold, which accepts or rejects the loaded log as a whole: event seqs are zero-based and contiguous, surface markers obey event-type eligibility, only surface event types may cite source-event seqs, present arrays are nonempty and duplicate-free, every source is an earlier seq, and every positional replacement names and cites all surface nodes it removes. Every contract failure uses `SESSION_QUERY_INVALID_SURFACE`; there is no weaker classification-only surface standard.
 
 All returned records and arrays are detached. A known live event trace never consults persistence; persisted event traces preserve the exact-read list/load consistency check. Session lineage is necessarily a cross-corpus operation and therefore preserves cross-corpus persistence failure semantics.
 
 ## Alternatives considered
 
 - **Expose standalone tracing helpers** — rejected because the source-precedence and detachment boundary belongs to `ctx.sessionQuery`; public helpers would invite callers to bypass it.
-- **Combine replacement and provenance edges** — rejected because a positional replacement can shadow surface nodes while also citing non-surface construction inputs, and consumers need to distinguish those meanings.
-- **Return transitive provenance closure** — rejected because it obscures logged direct evidence, increases result size, and lets one malformed distant edge alter otherwise local output.
-- **Best-effort traces over malformed provenance** — rejected because a structurally plausible partial graph would look authoritative. Exact inspection fails loudly when the canonical relationship contract is broken.
+- **Combine replacement and cited-source edges** — rejected because a positional replacement can shadow surface nodes while also citing non-surface construction inputs, and consumers need to distinguish those meanings.
+- **Return all transitively cited source events** — rejected because it obscures logged direct evidence, increases result size, and lets one malformed distant edge alter otherwise local output.
+- **Best-effort traces over malformed source-event lists** — rejected because a structurally plausible partial result would look authoritative. Exact inspection fails loudly when the canonical relationship contract is broken.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
index f578a69a30..6a39a9857d 100644
--- a/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-会话关系分散编码在不可变 header、位置式表面操作和已记录的来源数组中。消费方如果直接重建这些关系，就必须重复实现语料优先级、表面折叠、格式错误日志的处理、确定性的谱系顺序和克隆。位置替换与来源属于不同的图，因此把两者合并为一种通用边类型也会丢失含义。
+会话关系分散编码在不可变 header、位置式表面操作和已记录的来源事件 seq 引用数组中。消费方如果直接重建这些关系，就必须重复实现语料优先级、表面折叠、格式错误日志的处理、确定性的谱系顺序和克隆。位置替换关系与来源事件引用关系表示不同含义，因此把两者合并为一种通用边类型也会丢失含义。
 
 ## 决策
 
@@ -14,20 +14,20 @@ Status: implemented
 
 `SessionLineageTrace` 返回目标、按从直接父级到外层父级排序的已知父级，以及递归的后代树；同级节点先按创建时间排序，再按 session id 排序。`complete: true` 会携带已知根节点；`complete: false` 会携带第一个无法解析的父级 id。与目标相连的循环会以 `SESSION_QUERY_INVALID_LINEAGE` 失败。
 
-`SessionEventTrace` 将位置关系与来源关系分开保留。`replacedBy` 是直接的位置替换者，`replacementChain` 沿替换者追踪至最终节点，`replacedEventSeqs` 则列出目标直接移除的真实表面节点。`sourceEventSeqs` 保留日志中直接来源的顺序，而 `derivedEventSeqs` 按日志顺序列出后续的直接反向引用。来源关系不会传递展开。
+`SessionEventTrace` 将位置替换与来源事件引用关系分开保留。`replacedBy` 是直接的位置替换者，`replacementChain` 沿替换者追踪至最终节点，`replacedEventSeqs` 则列出目标直接移除的真实表面节点。`sourceEventSeqs` 保留日志中直接来源的顺序，而 `derivedEventSeqs` 按日志顺序列出后续的直接反向引用。查询不会继续传递追踪被引用的来源事件。
 
 ## 校验边界
 
-事件追踪会在分析表面之前检查目标是否存在。随后，事件列表与追踪都会使用 `dsh-session` 的单遍表面折叠，对加载的日志整体进行接受或拒绝：事件 seq 从零开始且连续；表面标记符合事件类型的适用范围；只有表面事件类型可以携带来源；存在的数组必须非空且没有重复项；每个来源必须是更早的 seq；每次位置替换必须指明并引用它所移除的全部表面节点。任何约定违例都使用 `SESSION_QUERY_INVALID_SURFACE`；系统不存在只用于分类、要求更弱的表面标准。
+事件追踪会在分析表面之前检查目标是否存在。随后，事件列表与追踪都会使用 `dsh-session` 的单遍表面折叠，对加载的日志整体进行接受或拒绝：事件 seq 从零开始且连续；表面标记符合事件类型的适用范围；只有表面事件类型可以引用来源事件 seq；存在的数组必须非空且没有重复项；每个来源必须是更早的 seq；每次位置替换必须指明并引用它所移除的全部表面节点。任何约定违例都使用 `SESSION_QUERY_INVALID_SURFACE`；系统不存在只用于分类、要求更弱的表面标准。
 
 所有返回的记录与数组都与内部状态分离。已知的实时事件追踪绝不查询持久化；持久化事件追踪保留精确读取所要求的列表／加载一致性检查。会话谱系必然属于跨语料操作，因此也保留跨语料的持久化失败语义。
 
 ## 考虑过的替代方案
 
 - **公开独立的追踪辅助函数**：不予采纳，因为源优先级与状态分离边界属于 `ctx.sessionQuery`；公开辅助函数会诱使调用方绕过该边界。
-- **合并替换边与来源边**：不予采纳，因为位置替换可以遮蔽表面节点，同时引用不在表面上的构造输入，而消费方需要区分这两种含义。
-- **返回传递来源闭包**：不予采纳，因为这会掩盖日志中直接记录的证据、增大结果，并让一条遥远的格式错误边改变原本局部的输出。
-- **在格式错误的来源关系上返回尽力而为的追踪结果**：不予采纳，因为结构上看似合理的局部图会显得具有权威性。当规范的关系约定损坏时，精确检查会明确报错。
+- **合并替换边与来源事件引用边**：不予采纳，因为位置替换可以遮蔽表面节点，同时引用不在表面上的构造输入，而消费方需要区分这两种含义。
+- **返回所有传递引用的来源事件**：不予采纳，因为这会掩盖日志中直接记录的证据、增大结果，并让一条遥远的格式错误边改变原本局部的输出。
+- **对格式错误的来源事件列表返回尽力而为的追踪结果**：不予采纳，因为结构上看似合理的局部结果会显得具有权威性。当规范的关系约定损坏时，精确检查会明确报错。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index 3893ff403f..7952219be6 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.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 .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
-2026-07-16-harness-level-loop.md: f37bea0842b3f40bf07c6660ad758d84ece23f1b
-2026-07-16-harness-level-loop.zh.md: 8d61c36915c7a3b5e0fde94c4c0ba52ec48eddd1
+2026-07-16-harness-level-loop.md: bc375621c5bf71ae6e3fbcd754d3b62e43353ae9
+2026-07-16-harness-level-loop.zh.md: fd74fbf85a63cb2f35fbcf7f694f738a07fe0cee
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
index f37bea0842..bc375621c5 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
@@ -36,7 +36,7 @@ Time-based `/loop` or scheduled execution is a third policy and is not implement
 | Package | Repository category | Owned structures and verbs |
 |---|---|---|
 | `@deepseek-ai/dsh-goal` | `packages/goal/goal/`, domain service | Owns `GoalId`, compare-and-set `GoalRef`, `GoalSnapshot`, four-state `GoalPhase`, structured `GoalBlockReason`, process-local `GoalActivation`, replay folding, and `get`, `create`, `edit`, `pause`, `resume`, `complete`, `block`, `clear`, and `disarm` verbs. |
-| `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`, model-facing consumer | Registers exclusive `get_goal`, `create_goal`, and `update_goal`; authenticates live turn provenance and narrows autonomous-round authority to completion or blocking reports with machine-routable reason codes. |
+| `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`, model-facing consumer | Registers exclusive `get_goal`, `create_goal`, and `update_goal`; requires a direct human message in a live root-agent turn and narrows autonomous-round authority to completion or blocking reports with machine-routable reason codes. |
 | `@deepseek-ai/dsh-goal-session` | `packages/goal/goal-session/`, continuation policy | Reserves, fences, admits, attributes, settles, cancels, and quiescently drains same-session goal rounds without importing the concrete loop. |
 | `@deepseek-ai/dsh-commands` | `packages/interaction/commands/`, UI registry | Owns `CommandDefinition`, discovery, scoped registration, direct dispatch, `CommandResult`, and request cancellation for human-only commands. |
 | `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`, human-command producer | Registers `/goal` status, creation, edit, pause, resume, and clear over the goal domain for TUI. |
@@ -68,7 +68,7 @@ Normal turn completion schedules another round only while the goal remains activ
 
 The human UX follows the compact Codex shape in the [public OpenAI Codex TUI dispatcher at commit `678157a`](https://github.com/openai/codex/blob/678157acaa819d5510adfe359abb5d0392cfe461/codex-rs/tui/src/chatwidget/slash_dispatch.rs#L750-L805): `/goal` shows status, `/goal <objective>` creates, and `edit`, `pause`, `resume`, or `clear` perform direct lifecycle actions. The commit permalink keeps the researched grammar verifiable as Codex evolves. Status includes durable phase, admitted/capped rounds, and live armed/disarmed activation. Direct status and command output do not enter model history; accepted domain mutations remain reconstructable because the goal service records them.
 
-The model receives only `get_goal`, `create_goal`, and `update_goal`. It may create a goal when a direct human request clearly asks for substantial multi-round work, and it may infer that intent in any language. It must not turn routine one-turn work into a goal. Direct-human provenance is enforced in code; semantic interpretation remains model judgment. An autonomous goal round may report `complete` or `blocked` for the exact current goal round but cannot edit, pause, resume, or replace the human objective.
+The model receives only `get_goal`, `create_goal`, and `update_goal`. It may create a goal when a direct human request clearly asks for substantial multi-round work, and it may infer that intent in any language. It must not turn routine one-turn work into a goal. Code requires a direct human message in the current live root-agent turn; semantic interpretation remains model judgment. An autonomous goal round may report `complete` or `blocked` for the exact current goal round but cannot edit, pause, resume, or replace the human objective.
 
 TUI mounts the shared command registry and complete goal stack by default and exposes `/goal` through one producer. ACP mounts the goal domain, model tools, and same-session driver but deliberately omits the human command plane. Every effective registered command is discoverable and invocable through every composed command adapter; a plugin incompatible with an application omits its command producer from that composition rather than relying on registry-level surface masks. The UI-less agent spine is opt-in so one-shot callers do not silently become multi-round operations. The headless CLI and JSON-RPC front doors do not consume the command plane; ordinary human text can still authorize model goal tools when that stack is composed.
 
@@ -111,7 +111,7 @@ The six owning Agent Notes record unit, integration, process, snapshot, cancella
 
 - Goal-based execution ships without one overloaded “loop” object: same-session continuation and fresh-agent iteration have explicit, separately testable contracts.
 - Durable goal history is replayable and forkable, while process-local activation prevents accidental work on resume.
-- Humans receive a small Codex-shaped UX; models receive a compact provenance-checked tool surface; deployments can remove either independently.
+- Humans receive a small Codex-shaped UX; models receive a compact tool set whose mutating calls require a direct human message in the current live root-agent turn; deployments can remove either independently.
 - Ralph demonstrates a nontrivial fixed policy entirely as a plugin over existing workflow and subagent primitives.
 - Round limits are generous by default but remain deployment-controlled. They bound iterations, not tokens, price, elapsed time, or external side effects.
 - The original proposal's evaluator, budget, reflector, background-task, CLI, and generic loop-session architecture is intentionally not part of the implemented public surface.
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index 8d61c36915..fd74fbf85a 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -36,7 +36,7 @@ Status: implemented
 | 包 | 仓库类别 | 所属结构与动词 |
 |---|---|---|
 | `@deepseek-ai/dsh-goal` | `packages/goal/goal/`，领域服务 | 拥有 `GoalId`、比较并交换 `GoalRef`、`GoalSnapshot`、四状态 `GoalPhase`、结构化 `GoalBlockReason`、进程本地 `GoalActivation`、重放折叠，以及 `get`、`create`、`edit`、`pause`、`resume`、`complete`、`block`、`clear` 与 `disarm` 动词。 |
-| `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`，面向模型消费方 | 注册互斥的 `get_goal`、`create_goal` 与 `update_goal`；认证实时 Turn 来源，并把自治 Round 权限收窄到带机器可路由原因代码的完成或阻塞报告。 |
+| `@deepseek-ai/dsh-tool-goal` | `packages/goal/tool-goal/`，面向模型消费方 | 注册互斥的 `get_goal`、`create_goal` 与 `update_goal`；要求实时根 agent Turn 中有一条人类直接发送的消息，并把自治 Round 权限收窄到带机器可路由原因代码的完成或阻塞报告。 |
 | `@deepseek-ai/dsh-goal-session` | `packages/goal/goal-session/`，续行策略 | 在不导入具体 loop 的情况下，预留、设围栏、接纳、归属、结算、取消并排空同会话 Goal Round，直至完全停稳。 |
 | `@deepseek-ai/dsh-commands` | `packages/interaction/commands/`，UI 注册表 | 拥有面向人类专用命令的 `CommandDefinition`、发现、作用域注册、直接分发、`CommandResult` 与请求取消。 |
 | `@deepseek-ai/dsh-command-goal` | `packages/goal/command-goal/`，人类命令生产方 | 为 TUI 注册构建在目标领域之上的 `/goal` 状态、创建、编辑、暂停、恢复与清除。 |
@@ -68,7 +68,7 @@ Goal Round 驱动器为每个特定的实时 agent 至多拥有一个待定预
 
 人类 UX 遵循 [OpenAI Codex 在提交 `678157a` 时的公开 TUI 分发器](https://github.com/openai/codex/blob/678157acaa819d5510adfe359abb5d0392cfe461/codex-rs/tui/src/chatwidget/slash_dispatch.rs#L750-L805)中的紧凑形态：`/goal` 显示状态，`/goal <objective>` 创建目标，而 `edit`、`pause`、`resume` 或 `clear` 执行直接生命周期操作。该提交永久链接让研究所得语法在 Codex 演进时仍可验证。状态包含持久阶段、已接纳/上限 Round 数以及实时已激活/未激活状态。直接状态与命令输出不会进入模型历史；已接受领域变更仍可重建，因为目标服务会记录它们。
 
-模型只接收 `get_goal`、`create_goal` 和 `update_goal`。当直接人类请求清楚要求大量多 Round 工作时，模型可以创建目标，并且可以从任何语言推断该意图。它不得把日常单 Turn 工作变成目标。直接人类来源由代码强制执行；语义解释仍是模型判断。自治目标 Round 可以为确切的当前 Goal Round 报告 `complete` 或 `blocked`，但不能编辑、暂停、恢复或替换人类目标。
+模型只接收 `get_goal`、`create_goal` 和 `update_goal`。当直接人类请求清楚要求大量多 Round 工作时，模型可以创建目标，并且可以从任何语言推断该意图。它不得把日常单 Turn 工作变成目标。代码要求当前实时根 agent Turn 中有一条人类直接发送的消息；语义解释仍是模型判断。自治目标 Round 可以为确切的当前 Goal Round 报告 `complete` 或 `blocked`，但不能编辑、暂停、恢复或替换人类目标。
 
 TUI 默认挂载共享命令注册表和完整目标栈，并通过一个生产方暴露 `/goal`。ACP（Agent Client Protocol）挂载目标领域、模型工具和同会话驱动器，但有意省略人类命令平面。每条有效已注册命令都能被每个已组合的命令适配器发现和调用；若插件与某应用不兼容，该应用组合会省略其命令生产方，而不是依赖注册表层面的表面掩码。无 UI 的 agent 主干要求显式选择加入，以免单次调用方静默变成多 Round 操作。无头 CLI（命令行界面）与 JSON-RPC 前端不消费命令平面；挂载目标栈后，普通人类文本仍可授权模型目标工具。
 
@@ -111,7 +111,7 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 
 - 目标式执行在没有单个过载「loop」对象的情况下交付：同会话续行与全新 agent 迭代拥有显式、可独立测试的约定。
 - 持久目标历史可以重放和 fork，而进程本地激活态会防止恢复时意外开始工作。
-- 人类获得小型 Codex 形态 UX；模型获得紧凑、带来源检查的工具表面；部署可以独立移除任一能力。
+- 人类获得小型 Codex 形态 UX；模型获得一组紧凑工具，其中的修改操作要求当前实时根 agent Turn 中有一条人类直接发送的消息；部署可以独立移除任一能力。
 - Ralph 展示了非平凡固定策略可以完全作为现有 workflow 与 subagent 原语之上的插件实现。
 - Round 上限默认宽裕，但仍由部署控制。它限制迭代次数，不限制 token、价格、耗时或外部副作用。
 - 原始提案中的评估器、预算、反思器、后台任务、CLI 与通用 loop-session 架构有意不进入已实现公开表面。
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
index 730de18a5a..088290b3fc 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.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 .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
-2026-07-19-model-facing-goal-tools.md: 0271194a38503711de77290c915010c26a9de74b
-2026-07-19-model-facing-goal-tools.zh.md: 097aaa3b160a394ff3d13681be04dd19c7856ebc
+2026-07-19-model-facing-goal-tools.md: abed410c7fd71b18c2cc0d0db745e76d98352546
+2026-07-19-model-facing-goal-tools.zh.md: a51ad417ff0928583ccddddafe65d23bc86bd24d
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
index 0271194a38..abed410c7f 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
@@ -28,7 +28,7 @@ An autonomous goal round that successfully reports completion or blocking defers
 
 Every call requires an `exec.agent` that is the exact running object in `AgentRegistry`, is the current inherited driver initiator, and has an open turn. These are execution-time checks and cannot be bypassed by prompt injection or hand-authored tool arguments.
 
-Create, edit, pause, and resume additionally require an accepted user message or user steering event in the current turn of a runtime-root agent. Root ownership is derived from the live agent graph rather than durable fork ancestry: a resumed fork can receive direct human authority, while a live child remains a subagent and cannot mutate these states. User source is a host attestation: every `Agent.followup()` or `steer()` input requires an explicit source, so the host labels direct human content `{ kind: 'user' }` and non-human producers label their own provenance. The runtime proves provenance, not whether the human's wording semantically warrants creation or resumption; that interpretation remains with the model.
+Create, edit, pause, and resume additionally require an accepted user message or user steering event in the current turn of a runtime-root agent. Root ownership is derived from the live agent graph rather than durable fork ancestry: a resumed fork can receive direct human authority, while a live child remains a subagent and cannot mutate these states. User source is a host attestation: every `Agent.followup()` or `steer()` input requires an explicit source, so the host labels direct human content `{ kind: 'user' }` and non-human producers identify themselves in their source fields. The runtime proves that the current turn contains a direct human message, not whether the human's wording semantically warrants creation or resumption; that interpretation remains with the model.
 
 Complete and blocked accept either direct-human authority or the exact current goal round. Goal-round authority requires a goal-sourced `user/message` whose goal id, revision, and round all equal the folded current goal. It grants only the two terminal reports. Direct human authority may stop a goal immediately.
 
@@ -44,7 +44,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr
 
 - **Rely on prompt instructions for authority** — rejected because text can guide model judgment but cannot authenticate the live caller, turn, or source event.
 - **Expose every goal-service verb as a separate tool** — rejected because a compact read/create/update surface reduces schema cost and keeps compare-and-set behavior uniform.
-- **Require exact command phrases** — rejected because natural-language intent, including languages other than English, should be interpreted by the model; execution authority depends on provenance rather than spelling.
+- **Require exact command phrases** — rejected because natural-language intent, including languages other than English, should be interpreted by the model; execution authority depends on a direct human message in the current turn rather than spelling.
 - **Authorize from persisted root or fork metadata** — rejected because a fork that becomes an independently resumed top-level session should accept new human authority, while a currently owned child should not.
 - **Let autonomous rounds edit or resume the goal** — rejected because continuation authority is narrower than authority to redefine or restart the human objective.
 - **Treat the blocked threshold as an evaluator** — rejected because event counts cannot prove that an obstacle is semantically unchanged or truly terminal.
@@ -53,7 +53,7 @@ Unit coverage pins registration and disposal, exclusive scheduling, generated pr
 ## Consequences
 
 - Models receive a stable, compact lifecycle surface without direct access to the goal service.
-- State-changing calls are constrained by live runtime provenance as well as durable compare-and-set references.
+- State-changing calls require a live runtime-root agent and a direct human message in the current turn, as well as durable compare-and-set references.
 - Human requests can create and rearm goals through ordinary natural language, while restored sessions remain inert until such input arrives.
 - Goal rounds can finish or report a repeated blocker but cannot broaden their own mandate.
 - Deployment policy selects the blocking lower bound; the same resolved value controls enforcement and prompt guidance.
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
index 097aaa3b16..a51ad417ff 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 每次调用都要求存在 `exec.agent`，且它必须是 `AgentRegistry` 中完全相同的运行中对象、当前继承的驱动发起者，并处于开放轮次内。这些检查在执行时进行，不能通过提示词注入或手写工具参数绕过。
 
-创建、编辑、暂停与恢复还要求运行时根 agent 的当前轮次已经接纳一条用户消息或用户 steering 事件。根所有权来自实时 agent 图，而非持久的 fork 祖先关系：恢复后的派生会话可以接收新的直接人类权限，实时子级则仍是 subagent，不能改变这些状态。用户来源是宿主的证明：每个 `Agent.followup()` 或 `steer()` 输入都必须显式提供来源，因此宿主把直接人类内容标为 `{ kind: 'user' }`，非人类生产者则标注自己的来源信息。运行时证明来源，而不判断人类措辞在语义上是否足以创建或恢复目标；该解释仍由模型完成。
+创建、编辑、暂停与恢复还要求运行时根 agent 的当前轮次已经接纳一条用户消息或用户 steering 事件。根所有权来自实时 agent 图，而非持久的 fork 祖先关系：恢复后的派生会话可以接收新的直接人类权限，实时子级则仍是 subagent，不能改变这些状态。用户来源是宿主的证明：每个 `Agent.followup()` 或 `steer()` 输入都必须显式提供来源，因此宿主把直接人类内容标为 `{ kind: 'user' }`，非人类生产者则在来源字段中注明自己。运行时证明当前轮次包含人类直接发送的消息，而不判断人类措辞在语义上是否足以创建或恢复目标；该解释仍由模型完成。
 
 完成与阻塞既接受直接人类权限，也接受准确的当前 Goal Round。Goal Round 权限要求存在一条来源为目标的 `user/message`，其中目标 id、修订号和 Round 都与折叠后的当前目标相等。它只授予这两种终止报告权限。直接人类权限可以立即停止目标。
 
@@ -44,7 +44,7 @@ Status: implemented
 
 - **依赖提示词指令实施权限**——不予采纳，因为文本可以指导模型判断，却不能认证实时调用者、轮次或来源事件。
 - **把每个目标服务动词分别暴露为工具**——不予采纳，因为紧凑的读取/创建/更新表面可以降低模式成本，并保持统一的比较并交换行为。
-- **要求精确命令短语**——不予采纳，因为自然语言意图（包括英语以外的语言）应由模型解释；执行权限取决于来源，而不是拼写。
+- **要求精确命令短语**——不予采纳，因为自然语言意图（包括英语以外的语言）应由模型解释；执行权限取决于当前轮次中人类直接发送的消息，而不是拼写。
 - **根据持久的根或派生元数据授权**——不予采纳，因为成为独立恢复顶层会话的派生应接受新的人类权限，而当前仍受所有权约束的子智能体则不应接受。
 - **允许自主回合编辑或恢复目标**——不予采纳，因为继续执行权限比重新定义或重启人类目标的权限更窄。
 - **把阻塞阈值当作评估器**——不予采纳，因为事件计数无法证明障碍在语义上未改变或确实不可继续。
@@ -53,7 +53,7 @@ Status: implemented
 ## 后果
 
 - 模型获得稳定而紧凑的生命周期表面，无需直接访问目标服务。
-- 改变状态的调用同时受到实时运行时来源与持久比较并交换引用的约束。
+- 改变状态的调用要求实时运行时根 agent、当前轮次中人类直接发送的消息，以及持久比较并交换引用。
 - 人类可以通过普通自然语言请求创建和重新激活目标，而恢复后的会话在收到此类输入前保持静止。
 - Goal Round 可以完成或报告重复阻塞，但不能自行扩大任务权限。
 - 部署策略选择阻塞下限；同一个解析后的值同时控制执行与提示词指导。
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
index e330fbd089..a4bc18ecce 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.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 .agents/notes/implemented/feature/2026-07-21-cross-session-references.md
-2026-07-21-cross-session-references.md: b2d428e0937fdd881720720401948a1c3e7ef1f6
-2026-07-21-cross-session-references.zh.md: ef89fd76c864c430f7b730d250e6511c2709f97e
+2026-07-21-cross-session-references.md: 46424e12949697054da2f920fbe55ca9dcbaf075
+2026-07-21-cross-session-references.zh.md: 7956dbef79aa77ab9d2be810420ae8c1b4e82a8d
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md
index b2d428e093..46424e1294 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-21-cross-session-references.zh.md)
 
 ## Problem
 
-TUI users need to bring relevant work from another conversation into one new message without resuming, forking, or granting the source transcript authority over the current session. The harness already exposes exact session enumeration and raw event inspection, but every host independently parsing logs would duplicate compaction folding, provenance filtering, size limits, error behavior, and persistence. Encoding host markup directly into the agent message contract would also bind the core loop to one UI syntax.
+TUI users need to bring relevant work from another conversation into one new message without resuming, forking, or granting the source transcript authority over the current session. The harness already exposes exact session enumeration and raw event inspection, but every host independently parsing logs would duplicate compaction folding, filtering by cited source-event seqs, size limits, error behavior, and persistence. Encoding host markup directly into the agent message contract would also bind the core loop to one UI syntax.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
index ef89fd76c8..7956dbef79 100644
--- a/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-TUI 用户需要把另一场对话中的相关工作带入一条新消息，但不恢复、不 fork，也不让源 transcript（文本记录）对当前会话拥有权威性。harness 已经提供准确的会话枚举与原始事件检查，但若每个宿主都独立解析日志，就会重复实现压缩（compaction）折叠、来源过滤、大小限制、错误行为和持久化。把宿主标记直接编码进 agent（智能体）消息约定，还会让核心循环绑定某一种 UI 语法。
+TUI 用户需要把另一场对话中的相关工作带入一条新消息，但不恢复、不 fork，也不让源 transcript（文本记录）对当前会话拥有权威性。harness 已经提供准确的会话枚举与原始事件检查，但若每个宿主都独立解析日志，就会重复实现压缩（compaction）折叠、按被引用来源事件 seq 过滤、大小限制、错误行为和持久化。把宿主标记直接编码进 agent（智能体）消息约定，还会让核心循环绑定某一种 UI 语法。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
index 3ea46677ab..75e87605ec 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.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 .agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
-2026-07-21-log-backed-session-titles.md: 89e6e67fb9ece4c087ba7b1bc52e61b78b94586c
-2026-07-21-log-backed-session-titles.zh.md: 21a0ec5dc9cc90726dda502ba46a52d717c39df5
+2026-07-21-log-backed-session-titles.md: 47025ba7e72ea6746d6f4428a81d6d754a8dcd03
+2026-07-21-log-backed-session-titles.zh.md: d7e12875354ca1fc66f0035020c7ffe2ddaa9354
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
index 89e6e67fb9..47025ba7e7 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md
@@ -16,7 +16,7 @@ The [`session-title` capability family](../../../../packages/session/README.md)
 
 ### Event ownership and folding
 
-Every accepted revision is a log-only `session/title` event. Its payload contains normalized non-empty text, the exact eligible human `user/message` seqs used to derive it, and either fallback provenance or the registered provider id plus optional provider/model route. Before an auxiliary title-model dispatch, the shared helper appends a log-only `session/title-llm-request` event containing the title-provider id, exact source seqs, route, system prompt, messages, and output-token cap; a later generation failure leaves the request auditable. The dispatched envelope is deep-frozen to preserve exact agreement with that record but carries no process-local agent-loop request identity, so loop-only reconstruction checks do not compare it with the main conversation header. Validation failures that never reach dispatch create no request event. `foldSessionTitle()` selects the latest title event and adds that event's seq and timestamp as `SessionTitleSnapshot`. Neither event enters `session.surface` or `deriveMessages()`.
+Every accepted revision is a log-only `session/title` event. Its payload contains normalized non-empty text, the exact eligible human `user/message` seqs used to derive it, and either the fallback source kind or the registered provider id plus optional provider/model route. Before an auxiliary title-model dispatch, the shared helper appends a log-only `session/title-llm-request` event containing the title-provider id, exact source seqs, route, system prompt, messages, and output-token cap; a later generation failure leaves the request auditable. The dispatched envelope is deep-frozen to preserve exact agreement with that record but carries no process-local agent-loop request identity, so loop-only reconstruction checks do not compare it with the main conversation header. Validation failures that never reach dispatch create no request event. `foldSessionTitle()` selects the latest title event and adds that event's seq and timestamp as `SessionTitleSnapshot`. Neither event enters `session.surface` or `deriveMessages()`.
 
 The title service appends `session/title` directly after checking its current revision and exact live session; the bundled model helper likewise appends its literal `session/title-llm-request` record before dispatch. Both records may sit between turns without inventing an execution boundary. Persistence admits them to bounded background batches and drains through ordinary checkpoints and lifecycle teardown; title publication does not force a per-event flush. No generic marker, cast, or settlement queue sits between the event owner and `Session.append()`. This is the domain-specific application of the [standalone log-only event decision](../simplification/2026-07-28-remove-synthetic-log-only-turns.md).
 
@@ -51,8 +51,8 @@ A fork inherits seed title events unchanged, like the rest of its source log —
 - **Mutable `SessionHeader` or side metadata** — rejected because it creates a second persistence mutation protocol, weakens immutable identity metadata, makes crash atomicity backend-specific, and gives forks ambiguous copy-versus-reference behavior. The append-only log already owns replayable latest-wins state.
 - **Await title generation before returning the agent response** — rejected because auxiliary provider latency and failure would sit on the main interaction's critical path. The deterministic fallback gives immediate useful state while a better title may arrive later.
 - **Put titles in derived history or the request prefix** — rejected because UI metadata would consume tokens, change cache identity, and make the main model observe its own label. A log-only event remains reconstructable without becoming model-visible.
-- **Permit multiple registered providers and resolve precedence after completion** — rejected because completion order is not product precedence and would make retries, HMR, and provenance nondeterministic. A deployment that needs a composite policy can register one provider that owns that policy.
-- **Silently truncate oversized auxiliary input** — rejected because the provider result would claim exact source-message provenance while receiving only partial text. Keeping the prior title and warning preserves truthful attribution.
+- **Permit multiple registered providers and resolve precedence after completion** — rejected because completion order is not product precedence and would make retries, HMR, and the recorded provider nondeterministic. A deployment that needs a composite policy can register one provider that owns that policy.
+- **Silently truncate oversized auxiliary input** — rejected because the provider result would cite source-message seqs whose complete text it did not receive. Keeping the prior title and warning preserves the exact input record.
 - **Index titles in `listSessions()` immediately** — rejected because the existing lightweight metadata list would need per-backend derived-index synchronization. Exact `readTitle()` establishes the read contract without precommitting search or indexing policy.
 - **Keep the Web host fallback-only** — rejected because the UI would expose durable titles but never improve them beyond the first-prompt prefix. The first-message provider keeps its latency off the main response path while making model summaries the default Web outcome.
 
diff --git a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
index 21a0ec5dc9..d7e1287535 100644
--- a/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 ### 事件归属与折叠
 
-每个已接受的修订都是纯日志 `session/title` 事件。其载荷包含规范化后的非空文本、用于派生标题的所有合格且来源为人类的 `user/message` 的准确 seq，以及回退来源信息，或已注册的提供方 id 加可选的提供方和模型路由。辅助标题模型发起调用前，共享辅助组件会追加一个纯日志 `session/title-llm-request` 事件，其载荷包含标题提供方 id、准确的源 seq、路由、系统提示词、消息和输出 token 上限；即使后续生成失败，这次请求仍可审计。发送的请求信封经过深度冻结，以确保其与该记录精确一致，但它有意不携带进程本地的 agent loop（智能体循环）请求身份，因此仅针对 agent loop 的重建检查不会将它与主对话请求头进行比较。未进入调用阶段的验证失败不会创建请求事件。`foldSessionTitle()` 选择最新的标题事件，并将该事件的 seq 和时间戳加入 `SessionTitleSnapshot`。这两类事件都不会进入 `session.surface` 或 `deriveMessages()`。
+每个已接受的修订都是纯日志 `session/title` 事件。其载荷包含规范化后的非空文本、用于派生标题的所有合格且来源为人类的 `user/message` 的准确 seq，以及回退来源 kind，或已注册的提供方 id 加可选的提供方和模型路由。辅助标题模型发起调用前，共享辅助组件会追加一个纯日志 `session/title-llm-request` 事件，其载荷包含标题提供方 id、准确的源 seq、路由、系统提示词、消息和输出 token 上限；即使后续生成失败，这次请求仍可审计。发送的请求信封经过深度冻结，以确保其与该记录精确一致，但它有意不携带进程本地的 agent loop（智能体循环）请求身份，因此仅针对 agent loop 的重建检查不会将它与主对话请求头进行比较。未进入调用阶段的验证失败不会创建请求事件。`foldSessionTitle()` 选择最新的标题事件，并将该事件的 seq 和时间戳加入 `SessionTitleSnapshot`。这两类事件都不会进入 `session.surface` 或 `deriveMessages()`。
 
 标题服务会在检查当前修订和确切的实时会话后，直接追加 `session/title`；随附模型辅助函数同样会在发起调用前追加其字面量 `session/title-llm-request` 记录。两类记录都可以位于轮次之间，而无需虚构执行边界。持久化会将它们接纳到有界后台批次中，并通过常规检查点和生命周期 teardown 排空；标题发布不会强制逐事件 flush。事件所有方与 `Session.append()` 之间不存在通用标记、类型断言或结算队列。这是[独立纯日志事件决策](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)在特定领域中的应用。
 
@@ -51,8 +51,8 @@ Status: implemented
 - **可变 `SessionHeader` 或独立元数据**：不予采纳，因为这会创建第二套持久化变更协议，削弱不可变身份元数据，让崩溃原子性因后端而异，并使 fork 的复制或引用行为产生歧义。仅追加日志已经负责可回放的后写覆盖状态。
 - **返回 agent 响应前等待标题生成**：不予采纳，因为辅助提供方的延迟和故障会进入主交互的关键路径。确定性回退方案可以立即提供可用状态，质量更高的标题则可稍后到达。
 - **将标题放入派生历史记录或请求前缀**：不予采纳，因为 UI 元数据会消耗 token、改变缓存标识，并让主模型观察到自己的标签。纯日志事件既保持可重建，又不会变得对模型可见。
-- **允许注册多个提供方，并在完成后解析优先级**：不予采纳，因为完成顺序并不等于产品优先级，而且会让重试、HMR 和来源信息变得不确定。需要组合策略的部署可以注册一个自行负责该策略的提供方。
-- **静默截断过大的辅助输入**：不予采纳，因为提供方结果会声明准确的源消息来源信息，实际却只接收了部分文本。保留原有标题并发出警告，可以保持归因真实。
+- **允许注册多个提供方，并在完成后解析优先级**：不予采纳，因为完成顺序并不等于产品优先级，而且会让重试、HMR 和已记录的提供方变得不确定。需要组合策略的部署可以注册一个自行负责该策略的提供方。
+- **静默截断过大的辅助输入**：不予采纳，因为提供方结果会引用源消息 seq，却没有收到这些消息的完整文本。保留原有标题并发出警告，可以保留准确的输入记录。
 - **立即在 `listSessions()` 中索引标题**：不予采纳，因为现有的轻量元数据列表将需要逐后端同步派生索引。精确的 `readTitle()` 建立了读取约定，而没有提前锁定搜索或索引策略。
 - **让 Web host 只使用回退标题**：不予采纳，因为 UI 虽会显示持久标题，却始终无法将第一条提示词的前缀改进为更好的标题。首消息提供方在主响应路径之外运行，并让模型摘要成为 Web 的默认结果。
 
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
index e90a23fd2e..f51e1f482a 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.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 .agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md
-2026-07-24-model-facing-session-query-tools.md: 863f557f11f89ff8dfc121b7da0b653852528394
-2026-07-24-model-facing-session-query-tools.zh.md: 2acbf44b42aafd2eac37903e1acbefc5ba098377
+2026-07-24-model-facing-session-query-tools.md: 7dcb25fc4205442bd0b0743a6228427fa66ead1c
+2026-07-24-model-facing-session-query-tools.zh.md: 29582ec498119ee5956f7a3fe9bcefaabf13b122
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md
index 863f557f11..7dcb25fc42 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.md
@@ -14,7 +14,7 @@ The unified `ctx.sessionQuery` service exposes exact reads, filters, relationshi
 
 The package entrypoint is only the public composition root for configuration, prompt registration, and tool registration. Its internal modules follow the execution boundary: `input.ts` owns model schemas, normalization, and filter construction; `service-boundary.ts` contains provider calls and model-safe error translation; `workspace-access.ts` owns caller identity, workspace authorization, title access, and lineage projection; `operations.ts` orchestrates the five service workflows; and `presentation.ts` renders tool results and call cards. This keeps policy in its owning layer without changing the package contract.
 
-`session_search` groups full-text matches by session and exposes typed session and event metadata filters. `session_event_search` searches one session, defaulting to the caller's current session. `session_trace` returns the complete authorized ancestor chain and recursive descendant trees. `session_event_trace` returns every known positional replacement and direct provenance relationship for one event. `session_event_read` returns the exact target event as unabridged JSON and optionally summarizes a bounded raw-event window; omitted `before` and `after` values mean target-only.
+`session_search` groups full-text matches by session and exposes typed session and event metadata filters. `session_event_search` searches one session, defaulting to the caller's current session. `session_trace` returns the complete authorized ancestor chain and recursive descendant trees. `session_event_trace` returns every known positional replacement and direct cited source-event relationship for one event. `session_event_read` returns the exact target event as unabridged JSON and optionally summarizes a bounded raw-event window; omitted `before` and `after` values mean target-only.
 
 Model-facing filters use flat snake-case fields. Timestamps are timezone-qualified ISO 8601 strings at the tool boundary, convert to inclusive epoch-millisecond ranges for the service, and render as UTC ISO 8601. List values are ORed inside one filter while separate filters are ANDed. Requested parent ids are deduplicated and authority-filtered before FTS, so only parents in the caller workspace enter the provider clause; missing and cross-workspace guesses behave identically, while the root-session marker remains independently ORed into that clause. Event type strings remain open because `SessionEventMap` is merge-extensible; availability and event surface use closed values.
 
diff --git a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
index 2acbf44b42..29582ec498 100644
--- a/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-24-model-facing-session-query-tools.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 该包入口仅作为配置、提示词注册与工具注册的公开组合根。内部模块沿执行边界划分：`input.ts` 负责模型 schema、规范化与过滤条件构造；`service-boundary.ts` 包含提供方调用与面向模型的安全错误转换；`workspace-access.ts` 负责调用者身份、工作区授权、标题访问与谱系投影；`operations.ts` 编排五个服务工作流；`presentation.ts` 渲染工具结果与调用卡片。这样可让策略留在其所属层，同时不改变包约定。
 
-`session_search` 按会话聚合全文匹配，并公开带类型的会话与事件元数据过滤条件。`session_event_search` 搜索一个会话，默认目标为调用者的当前会话。`session_trace` 返回完整的已授权祖先链与递归后代树。`session_event_trace` 返回一个事件所有已知的位置替换关系与直接来源关系。`session_event_read` 以未删节 JSON 返回准确的目标事件，并可选择汇总一个有界的原始事件窗口；省略 `before` 与 `after` 时只返回目标。
+`session_search` 按会话聚合全文匹配，并公开带类型的会话与事件元数据过滤条件。`session_event_search` 搜索一个会话，默认目标为调用者的当前会话。`session_trace` 返回完整的已授权祖先链与递归后代树。`session_event_trace` 返回一个事件所有已知的位置替换关系与直接引用来源事件的关系。`session_event_read` 以未删节 JSON 返回准确的目标事件，并可选择汇总一个有界的原始事件窗口；省略 `before` 与 `after` 时只返回目标。
 
 面向模型的过滤条件使用扁平的 snake-case 字段。工具边界上的时间戳采用带时区的 ISO 8601 字符串，转换为服务使用的闭区间毫秒时间戳，并以 UTC ISO 8601 渲染。同一个过滤条件中的列表值按 OR 组合，不同过滤条件按 AND 组合。请求的父会话 id 会在 FTS 之前去重并按权限过滤，因此只有调用者工作区中的父会话会进入提供方条件；缺失与跨工作区的猜测具有相同行为，而根会话标记仍会独立按 OR 加入该条件。由于 `SessionEventMap` 可通过声明合并扩展，事件类型字符串保持开放；可用状态与事件表层使用封闭取值。
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
index 37c876275c..d69b63df7f 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.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 .agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md
-2026-07-27-trajectory-inspection-ledger.md: e3fc22234c1df449c99eac90af27de7da0b6f202
-2026-07-27-trajectory-inspection-ledger.zh.md: f167d818281c39a06e658c294f45e47d3ba40642
+2026-07-27-trajectory-inspection-ledger.md: a905e65942365c17b7513028b275288c82428221
+2026-07-27-trajectory-inspection-ledger.zh.md: 70fcdcdb0d2f26d120325a76a3e1f49ae6350c57
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md
index e3fc22234c..a905e65942 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.md
@@ -19,7 +19,7 @@ Trajectory has to make prose, machine payloads, token usage, timing, and nested
 - The client runtime exposes a read-only history source independent from Session and SessionManager. Each activated source owns its raw entries, paging, live gap repair, and reconnect rebuild; the ordinary conversation snapshot remains the folded Chat projection. Trajectory opens the source's tail while mounted and requests one older page when the user reaches the loaded range's top, then lazily derives event order, context lineage, schema index, and Requests instead of imposing those structures on every conversation consumer.
 - Ordinary generation and compaction calls form one chronological Request projection, distinguished by purpose rather than separate collections. Effective prompt state and its change ride the Request that introduced them; compaction and prompt changes are not independent inspection entities. Request numbering and cumulative usage cover the loaded history window and expand as older pages arrive.
 - Call schemas come from the active recorded Request header. Keyless snapshot fixtures deliberately replace that catalog with the non-array `{{tools}}` token, which the durable inspection boundary treats as unavailable instead of attempting to project or fabricate schemas.
-- Selecting a record or Request opens an inspector inside Trajectory. Tabs and Summary sections follow the selected entity: Markdown messages expose rendered, source, provenance, and hierarchy views; tools add JSON payload/result and schema views; Requests add options, usage, timing, and result navigation. Scrollable Summary regions keep their scrollbar thumbs transparent until hover or `focus-within`, while retaining the scrollbar reservation and scroll behavior. Images render as media rather than serialized data.
+- Selecting a record or Request opens an inspector inside Trajectory. Tabs and Summary sections follow the selected entity: Markdown messages expose rendered content, source fields, provider/model fields, and hierarchy views; tools add JSON payload/result and schema views; Requests add options, usage, timing, and result navigation. Scrollable Summary regions keep their scrollbar thumbs transparent until hover or `focus-within`, while retaining the scrollbar reservation and scroll behavior. Images render as media rather than serialized data.
 - Turn folding removes all rows after its first record and replaces them with a compact step/tool-call count; Assistant folding applies the same interaction to its tool-call descendants. Global controls fold or expand both levels.
 - A long ledger initially positions the loaded tail at the bottom and mounts only the viewport's row window plus bounded overscan. Request-only separators join the next measurable virtual item, with a terminal separator retaining its own fixed clearance, so the virtualizer never owns a zero-height item. Semantic DOM-safe row keys and ARIA indexes expose identity independently from mount position. A tail with known older history virtualizes immediately even when its loaded projection is below the ordinary row threshold. Stable-key virtualizer anchoring preserves the visible item across prepends and appends; the manual scroll-height fallback applies only when completing pagination disables virtualization. Selection, timeline focus, folding, search, and bottom following address records by stable event or tool-call identity rather than requiring their DOM rows to exist. An explicit loading row covers records until initial positioning finishes and while an older page is pending. The raw window base sequence detects a prepend even when a page adds no surface-visible node.
 - The separate Waterfall tab is removed. A fixed Overview above the ledger projects every loaded record with known `startedAt` onto three semantic timing lanes using its own duration. While an older prefix remains unloaded and the viewport includes the loaded domain's start, a neutral ellipsis control covers the truncated edge and loads one earlier page without assigning unknown history a fabricated duration; hovering that control suppresses the ordinary timeline cursor. Finalized Assistant spans divide the recorded interval at the first non-empty token delta, so distinct TTFT and decoding colors retain their actual ratio; incomplete timing falls back to one Assistant color. Hovering for 500 ms exposes exact start/end, total duration, TTFT, and decoding time without relying on the browser's native tooltip delay. Dragging left or right commits an inclusive interval filter: any record whose active interval overlaps either boundary remains visible, records without known timing leave the focused ledger, and clearing the selection restores the full branch. Wheel gestures zoom the time domain. A right-button click clears the interval selection; dragging instead pans an already zoomed viewport without mutating it. The Overview keeps the full time domain while focused so the selection can be resized or cleared without losing orientation.
@@ -53,4 +53,4 @@ Trajectory has to make prose, machine payloads, token usage, timing, and nested
 
 ## Consequences
 
-Trajectory shows more useful records per viewport while retaining Turn and Request orientation. Context rewrites and compactions remain inline with their surrounding history, while a rewind begins a successor branch that inherits only the retained prefix. The floating composer leaves the ledger visible to the viewport edge without covering its final rows or hiding horizontal controls. The main ledger omits token usage and duration so content receives the available width; the local inspector exposes those facts together with full payloads, provenance, schemas, and request timing. The Overview uses recorded start/duration and token-boundary facts without fabricating live elapsed time, and its inclusive focus behavior matches the interaction users already know from Chrome DevTools Network. Tail-first paging bounds initial transport and projection work, virtualization bounds mounted row elements, incremental partial projection removes loaded-history length from ordinary token-frame work, and completed-step chunk compaction makes structural rebuilds proportional to inspection-relevant entries rather than the raw token count. Focused component tests pin tail-first paging, prepend anchoring and identity retention, the virtual window, tail following, content-only streaming without repeated scroll writes, streaming structural sharing, high-sequence window folding, timing projection, delayed detail disclosure, folding, record and interval selection, entity-specific tabs, and running/error semantics. A real-browser long-ledger contract pins stable prepend geometry, bounded mounting, top/middle/bottom reachability, and bounded scroll writes across a paced stream; the assembled Web snapshot pins the ledger, Overview timing details, composer overlay geometry, and inspector through the real client composition.
+Trajectory shows more useful records per viewport while retaining Turn and Request orientation. Context rewrites and compactions remain inline with their surrounding history, while a rewind begins a successor branch that inherits only the retained prefix. The floating composer leaves the ledger visible to the viewport edge without covering its final rows or hiding horizontal controls. The main ledger omits token usage and duration so content receives the available width; the local inspector exposes those facts together with full payloads, provider/model and source fields, schemas, and request timing. The Overview uses recorded start/duration and token-boundary facts without fabricating live elapsed time, and its inclusive focus behavior matches the interaction users already know from Chrome DevTools Network. Tail-first paging bounds initial transport and projection work, virtualization bounds mounted row elements, incremental partial projection removes loaded-history length from ordinary token-frame work, and completed-step chunk compaction makes structural rebuilds proportional to inspection-relevant entries rather than the raw token count. Focused component tests pin tail-first paging, prepend anchoring and identity retention, the virtual window, tail following, content-only streaming without repeated scroll writes, streaming structural sharing, high-sequence window folding, timing projection, delayed detail disclosure, folding, record and interval selection, entity-specific tabs, and running/error semantics. A real-browser long-ledger contract pins stable prepend geometry, bounded mounting, top/middle/bottom reachability, and bounded scroll writes across a paced stream; the assembled Web snapshot pins the ledger, Overview timing details, composer overlay geometry, and inspector through the real client composition.
diff --git a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
index f167d81828..70fcdcdb0d 100644
--- a/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-trajectory-inspection-ledger.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 - 客户端 runtime 提供独立于 Session 和 SessionManager 的只读历史数据源。每个已激活的数据源自行拥有原始条目、分页、实时缺口修复和重连重建；普通会话快照仍然只是 Chat 所需的折叠投影。Trajectory 在挂载期间打开该数据源的尾部，当用户到达已加载范围顶部时请求一页更早的历史，再按需派生事件顺序、上下文谱系、schema 索引和请求，避免让所有会话消费者承担这些结构。
 - 普通生成调用与压缩调用形成一条按时间排序的请求投影，以 purpose 区分而不是放入不同集合。生效的提示词状态及其变化附着在引入它们的请求上；压缩和提示词变化都不是独立检查实体。请求编号和累计用量覆盖已加载的历史窗口，并随更早页面到达而扩展。
 - 调用 schema 来自当前生效且已记录的请求头。无密钥快照 fixture（测试前置数据）有意将该目录替换为非数组 token `{{tools}}`，持久化检查边界会将其视为不可用，而不是尝试投影或虚构 schema。
-- 选择记录或请求后，轨迹视图内部会打开检查器，其标签页和概览区域随实体类型变化：Markdown 消息提供渲染、源码、来源和层级视图；工具提供 JSON 载荷／结果和 schema 视图；请求提供选项、用量、计时和结果跳转。可滚动的概述区域默认保持滚动条滑块透明，直到悬停或 `focus-within` 时才显示，同时保留滚动条预留空间和滚动行为。图片以媒体形式渲染，而不是显示为序列化数据。
+- 选择记录或请求后，轨迹视图内部会打开检查器，其标签页和概览区域随实体类型变化：Markdown 消息提供渲染内容、来源字段、提供方／模型字段和层级视图；工具提供 JSON 载荷／结果和 schema 视图；请求提供选项、用量、计时和结果跳转。可滚动的概述区域默认保持滚动条滑块透明，直到悬停或 `focus-within` 时才显示，同时保留滚动条预留空间和滚动行为。图片以媒体形式渲染，而不是显示为序列化数据。
 - 折叠轮次时保留其第一条记录，将后续行替换为紧凑的步骤和工具调用数量；折叠助手时对其工具调用后代应用相同交互。全局控件可以分别折叠或展开这两个层级。
 - 长记录表初始时将已加载尾部置于底部，只挂载视口对应的行窗口及有界的额外缓冲行。仅含请求的分隔行并入下一个具备可测高度的虚拟项，末尾分隔行则保留固定留白，因此虚拟化器不会管理零高度项。可安全用于 DOM 的语义行键与 ARIA 索引使标识不依赖挂载位置。只要已知尾部之前仍有更早历史，即使当前已加载投影低于常规行数阈值，也会立即启用虚拟化。基于稳定键的虚拟化器锚定会在向前补页和尾部追加时保留当前可见项；只有分页完成导致虚拟化停用时，才使用手动滚动高度兜底。选择、时间线聚焦、折叠、搜索和末尾跟随均按稳定的事件或工具调用标识定位，不要求对应 DOM 行已存在。初始定位完成前以及更早页面仍在等待时，明确的加载行会遮住真实记录。原始窗口的基准序号即使在一页未增加任何 surface 可见节点时，也能检测到这次向前补页。
 - 移除独立的 waterfall（瀑布式事件）标签页。固定在记录表上方的 Overview 区域将所有 `startedAt` 已知的已加载记录按各自耗时投影到三条语义计时轨道。仍有更早前缀尚未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会遮住截断边缘并加载一页更早历史，而不会为未知历史虚构耗时；悬停在该控件上会隐藏普通的时间线光标。已完成的助手时间条以首个非空 token 增量为分界，用不同颜色按真实比例表示 TTFT 与解码时间；计时不完整时退化为单一助手色。悬停 500 ms 后会显示精确起止时刻、总耗时、TTFT 和解码时间，而不依赖浏览器原生 tooltip 的延迟。向左或向右拖动会提交包含边界的区间筛选：任何活动区间与所选区间相交的记录都会保留，计时未知的记录会从聚焦后的记录表中移除，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除区间选择；右键拖动则只会平移已放大的 viewport，不会改变该选区。聚焦后，Overview 区域仍保留完整时间范围，以便在不失去方位的情况下调整或清除选择。
@@ -53,4 +53,4 @@ Status: implemented
 
 ## 后果
 
-轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、来源、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表约定锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
+轨迹视图在保留轮次与请求定位的同时，每个视口可以显示更多有效记录。上下文 `rewrite` 与压缩保持在周边历史中的原始位置，`rewind` 则建立仅继承保留前缀的后继分支。浮动 composer 让记录表一直显示到视口边缘，同时不会遮住最后几行，也不会隐藏横向控件。主记录表省略 token 用量和耗时，让内容获得可用宽度；局部检查器展示这些数据以及完整载荷、提供方／模型字段、来源字段、schema 和请求计时。Overview 区域使用记录的开始时间、耗时与 token 边界数据，而不虚构实时流逝时间，其包含边界的聚焦行为与用户熟悉的 Chrome DevTools Network 交互一致。尾部优先分页限制初始传输和投影工作量，虚拟化限制已挂载的行元素数量，未完成部分的增量投影让普通 token 帧的工作量不再随已加载历史长度增长，而已完成步骤的分片压缩则让结构重建的工作量与检查所需条目数量成正比，而非与原始 token 数量成正比。针对性组件测试锁定尾部优先分页、向前补页锚定与标识保持、虚拟窗口、末尾跟随、仅含内容的流式输出不会重复写入滚动位置、流式输出的结构共享、高序号窗口折叠、计时投影、延迟展示详情、折叠、记录与区间选择、实体特定标签页和运行／错误语义。真实浏览器中的长记录表约定锁定向前补页时稳定的几何位置、有界挂载、顶部／中部／底部可达性，以及按节奏进行的流式输出中有界的滚动写入；组装后的 Web 快照则通过真实客户端组合锁定记录表、Overview 计时详情、composer 浮层几何形状与检查器。
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
index 6a48bdc751..fa4523a51d 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.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 .agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
-2026-07-27-workspace-registration-deletion.md: ae12b09979f20385336eef8d805173dd9c08d887
-2026-07-27-workspace-registration-deletion.zh.md: 85f399142bb0faf4b4bbf438ef2892d957814fab
+2026-07-27-workspace-registration-deletion.md: ef8a7fb9ae13c23e04a5760cd443c4a744ec4f19
+2026-07-27-workspace-registration-deletion.zh.md: 21c378b5c6d738bc6b9a00856691a56d65217586
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
index ae12b09979..ef8a7fb9ae 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-27-workspace-registration-deletion.zh.md)
 
 ## Problem
 
-A Workspace registers an existing code directory so the GUI can name it and order its Sessions. That record has no reliable provenance proving that Harness created or owns the directory, and the Session log is an independent persistence object. Treating the row's Delete action as recursive source deletion or Session deletion would destroy data outside the record's ownership boundary.
+A Workspace registers an existing code directory so the GUI can name it and order its Sessions. That record does not say that Harness created or owns the directory, and the Session log is an independent persistence object. Treating the row's Delete action as recursive source deletion or Session deletion would destroy data outside the record's ownership boundary.
 
 The existing visual-only menu row also left deletion semantics undefined across durable order, the Workspace table, Host streams, concurrent browser tabs, reconnect baselines, and a list request racing the mutation.
 
@@ -22,7 +22,7 @@ Registry operations serialize create and delete. Deletion first writes the Works
 
 The Host stream keeps its committed-id set through the preceding global-order write and removes the id only on the table deletion. Create rollback therefore emits no false removal, while every connected tab receives exactly the id needed to delete its projection.
 
-Create and delete write a durable `pendingMutation` before their record/order pair can diverge. Startup completes only the named create or delete and clears the marker; it never infers crash provenance from an orphan row alone. Unmarked order/table divergence therefore retains the registry's fail-loud corruption behavior. A deletion whose table write committed but marker cleanup failed still reports success—the requested state and removal frame are already committed—and the next startup clears that marker idempotently.
+Create and delete write a durable `pendingMutation` before their record/order pair can diverge. Startup completes only the operation named by that marker and clears it; an orphan row alone does not identify which operation was interrupted. Unmarked order/table divergence therefore retains the registry's fail-loud corruption behavior. A deletion whose table write committed but marker cleanup failed still reports success—the requested state and removal frame are already committed—and the next startup clears that marker idempotently.
 
 ## Client convergence
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
index 85f399142b..21c378b5c6 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Workspace 注册已有代码目录，使 GUI 能够为目录命名，并对其会话排序。该记录没有可靠的来源信息来证明 Harness 创建或拥有该目录，会话日志也是独立的持久化对象。若将行内 Delete 操作视为递归删除源码或删除会话，就会破坏该记录所有权边界之外的数据。
+Workspace 注册已有代码目录，使 GUI 能够为目录命名，并对其会话排序。该记录没有说 Harness 创建或拥有该目录，会话日志也是独立的持久化对象。若将行内 Delete 操作视为递归删除源码或删除会话，就会破坏该记录所有权边界之外的数据。
 
 现有菜单行只有视觉呈现，没有实际功能，因此持久化顺序、Workspace 表、Host 流、并发浏览器标签页、重连基线，以及列表请求与变更并发时的删除语义也没有定义。
 
@@ -22,7 +22,7 @@ Workspace 注册已有代码目录，使 GUI 能够为目录命名，并对其
 
 Host 流在前一笔全局顺序写入期间继续保留其已提交 id 集合，只在删除表行时移除该 id。因此，创建回滚不会发出错误的移除帧，而每个已连接标签页都能收到从自身投影中删除该记录所需的准确 id。
 
-Create 与 delete 会在记录／顺序对可能分叉之前写入持久化的 `pendingMutation`。启动时只补全其中明确命名的 create 或 delete，并清除该标记；系统绝不会仅凭孤立表行的形状推断崩溃来源。因此，没有标记的顺序／表分叉仍会保持注册表原有的损坏直接失败语义。如果删除的表写入已经提交、但标记清理失败，操作仍会报告成功——请求状态和移除帧都已经提交——下一次启动会以幂等方式清除该标记。
+Create 与 delete 会在记录／顺序对可能分叉之前写入持久化的 `pendingMutation`。启动时只补全该标记明确命名的操作，并清除标记；仅有一行孤立记录无法确定哪个操作被中断。因此，没有标记的顺序／表分叉仍会保持注册表原有的损坏直接失败语义。如果删除的表写入已经提交、但标记清理失败，操作仍会报告成功——请求状态和移除帧都已经提交——下一次启动会以幂等方式清除该标记。
 
 ## 客户端收敛
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index cf0c2038cb..c0e97060b2 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
-2026-07-28-continuable-subagent-conversations.md: 56d9abb2b09577b2fba14b9a655a941417e0c493
-2026-07-28-continuable-subagent-conversations.zh.md: cd73d9a3b5ff1b9671a7b08ed1482fa1ad45f48e
+2026-07-28-continuable-subagent-conversations.md: 632de8c9f7a6d2c71dcca6d817a827f788645b4e
+2026-07-28-continuable-subagent-conversations.zh.md: 9752dab97684d7249418c1a6d19905ab48ac82ca
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
index 56d9abb2b0..632de8c9f7 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
@@ -40,17 +40,17 @@ Any failure before inbox acceptance rejects without returning either id. Agent c
 
 `backgroundMode: 'one-shot' | 'continuable'` remains deployment policy. Configured continuable mode requires `prepareContinuable`; method presence replaces `SubagentProvider.resume?()` as the capability check, while a capable provider may still run one-shot work.
 
-Cold resume does not dispatch through a subagent provider. The continuation manager folds the generic in-process descriptor, calls `ctx.agents.resume()` through the same activation-owner scope, installs the returned `AgentHandle`, and submits the waiting `next-turn`. `SubagentProvider.resume?()` and `SubagentProviderResumeRequest` are absent. The initial provider name remains lifecycle provenance after that provider unregisters; it is not a recovery capability or a requirement for later residency. Remote providers require a separate design.
+Cold resume does not dispatch through a subagent provider. The continuation manager folds the generic in-process descriptor, calls `ctx.agents.resume()` through the same activation-owner scope, installs the returned `AgentHandle`, and submits the waiting `next-turn`. `SubagentProvider.resume?()` and `SubagentProviderResumeRequest` are absent. The descriptor retains the initial provider name after that provider unregisters; the name does not grant a recovery capability or require the provider for later residency. Remote providers require a separate design.
 
 `SubagentProvider.start()` and `SubagentRun` remain exclusively on the unchanged one-shot path. A continuable Activation directly owns its `AgentHandle` and never creates, wraps, or retains a `SubagentRun`; `SubagentRun.steer?()` is therefore absent.
 
-`ctx.subagents.followup(parent, childId, content, { source, signal })` remains the sole parent-to-child continuation-message operation. The exact live parent Agent authorizes delivery; cold resume checks that authority before reconstruction and every path checks it again in the final no-await inbox-admission span, so a parent unregistered or replaced during materialization cannot authorize delivery. `source` remains durable provenance and grants no authority. The model-facing `send_message` tool keeps only its stable `subagent_id` and `message` fields and always submits a follow-up turn. Both start and follow-up return the accepted `MessageId`, and neither reports how the manager materialized the Activation.
+`ctx.subagents.followup(parent, childId, content, { source, signal })` remains the sole parent-to-child continuation-message operation. The exact live parent Agent authorizes delivery; cold resume checks that authority before reconstruction and every path checks it again in the final no-await inbox-admission span, so a parent unregistered or replaced during materialization cannot authorize delivery. `source` records who supplied the admitted message and grants no authority. The model-facing `send_message` tool keeps only its stable `subagent_id` and `message` fields and always submits a follow-up turn. Both start and follow-up return the accepted `MessageId`, and neither reports how the manager materialized the Activation.
 
 For start and follow-up, the caller signal owns lookup, materialization, and admission only until inbox acceptance. After the operation returns its `MessageId`, the manager owns the Activation independently; later caller cancellation does not cancel the accepted turn or dispose the child.
 
 ### Durable Session and live Activation
 
-The Session owns the stable child identity, transcript, direct-parent lineage, delegation depth, and versioned continuation descriptor. `SessionHeader.parentSession` is durable provenance and an authorization input; it is not a live routing capability and does not imply that the historical parent is resident.
+The Session owns the stable child identity, transcript, direct-parent lineage, delegation depth, and versioned continuation descriptor. `SessionHeader.parentSession` records the direct parent and is an authorization input; it is not a live routing capability and does not imply that the recorded parent is resident.
 
 An idle historical Session has no `AgentHandle`. The first authorized `next-turn` delivery resumes an Activation from the persisted Session and submits the message to its inbox. Cold resume uses the exact live parent Agent for authorization and, when that parent has an Activation, ownership; it never uses the parent for reconstruction.
 
@@ -121,9 +121,9 @@ This version exposes no subagent steering operation. Parent continuation message
 
 A later host UI may expose separate **Steer** and **Follow up** actions. Host steering would be strict and live-only: it may call the existing Agent steering path only while the Activation accepts a next step, must reject otherwise, and must never fall back to queueing or cold resume. Exposing parent steering to a model-facing tool remains a separate design.
 
-### Authority and provenance
+### Authority and recorded sender identity
 
-Authority is supplied by an exact live Agent tool context. `MessageSource` and `senderSessionId` are durable provenance after admission, not caller-controlled authority.
+Authority is supplied by an exact live Agent tool context. After admission, `MessageSource` and `senderSessionId` record who supplied the message; callers cannot use those fields as authority.
 
 This version authorizes only the durable child's direct parent. The manager checks `SessionHeader.parentSession` against the exact live parent Agent at the final no-await inbox-admission boundary before registering the child in that parent's `ownedChildren`; cold resume also performs an earlier check before reconstruction for fail-fast rejection. Other Agents, ancestors, hosts, teams, and workflows remain rejected until a concrete consumer justifies another authority protocol.
 
@@ -137,7 +137,7 @@ Host and manager teardown remains the lifecycle stop path. Manager unload applie
 
 Each turn requests the Session durability checkpoint, while final Activation settlement additionally awaits `ctx.sessions.flush()` as a best-effort barrier. The manager deliberately ignores the boolean result because listener participation cannot identify a persistence backend. A rejection is logged without changing the lifecycle result or host-drain outcome; the manager still disposes the handle and releases ownership, and the persisted child state may be missing or stale on a later resume.
 
-Only messages written to the child Session log are reconstructable with their admitted provenance; inbox acceptance alone provides no restart guarantee.
+Only messages written to the child Session log are reconstructable with the source that supplied them; inbox acceptance alone provides no restart guarantee.
 
 Session and descriptor persistence survive restart. Activation state, Agent inbox contents, and the ownership graph are process-local. A process crash may lose an accepted initial prompt or follow-up that remained in the inbox without reaching the Session log. The Session and descriptor may survive so a later authorized message can cold-resume the child, but the lost message is not replayed automatically. Recovering accepted unfinished or unlogged messages requires a durable inbox protocol and is not implied here.
 
@@ -159,7 +159,7 @@ It adds no host-user continuation, subagent steering operation, durable mailbox,
 
 **Make report delivery part of the base lifecycle.** Repeatable child-to-parent reporting is compatible with this lifecycle, but quiet versus waking delivery, acknowledgement, durability, and retry behavior are independent product choices. The later report package remains optional and consumes an explicit child-setup seam, so continuable residency does not silently grant a return channel.
 
-**Treat `SessionHeader.parentSession` as live ownership.** Durable lineage does not prove that the historical parent currently owns the child. Membership in the live parent's `ownedChildren` records the process-local relationship without changing durable provenance.
+**Treat `SessionHeader.parentSession` as live ownership.** Durable lineage does not prove that the recorded parent currently owns the child. Membership in the live parent's `ownedChildren` records the process-local relationship without changing the durable parent id.
 
 **Retain the exact parent Agent in a separate link.** The parent Activation already owns its `AgentHandle`, and `ownedChildren` prevents that Activation from disposing while the child remains live. Resolving the parent by Session id is therefore sufficient and avoids a redundant runtime reference.
 
@@ -181,9 +181,9 @@ The implementation pins these behaviors:
 - `SubagentProvider.prepareContinuable?()` returns only a detached `ContinuableCreateSpec`; configured continuable mode requires that capability, while `backgroundMode` remains an independent policy choice.
 - The manager calls `ctx.agents.create()` through its private activation-owner scope, installs the returned `AgentHandle` and parent ownership, calls `Agent.followup(initialPrompt)`, and returns `{ childId, messageId }` when inbox acceptance yields the `MessageId`, without waiting for turn start or a Session-log write.
 - Every failure before initial-prompt inbox acceptance rejects without ids and rolls back any created handle, Activation, and parent `ownedChildren` membership through a closing transaction visible to concurrent delivery and drain; lifecycle publication failure emits no unmatched terminal edge.
-- Cold resume calls `ctx.agents.resume()` from the continuation manager and never dispatches through or requires the initial subagent provider; the persisted provider name remains lifecycle provenance after provider removal, while `SubagentProvider.resume?()` and `SubagentProviderResumeRequest` are absent.
+- Cold resume calls `ctx.agents.resume()` from the continuation manager and never dispatches through or requires the initial subagent provider; the descriptor retains the initial provider name after provider removal, while `SubagentProvider.resume?()` and `SubagentProviderResumeRequest` are absent.
 - A continuable Activation directly owns `AgentHandle` and never creates, wraps, or retains `SubagentRun`; `SubagentProvider.start()` and `SubagentRun` remain one-shot-only, without `SubagentRun.steer?()`.
-- `followup()` accepts only the exact live direct parent and rechecks that identity at the final no-await inbox-admission boundary after any materialization; durable message provenance cannot authorize delivery.
+- `followup()` accepts only the exact live direct parent and rechecks that identity at the final no-await inbox-admission boundary after any materialization; durable message source fields cannot authorize delivery.
 - Continuation messages always use `Agent.followup()` and share its inbox FIFO, including when the child already has an open turn.
 - `ctx.subagents.followup()` and its `send_message` adapter return only the accepted `MessageId`; the continuation layer accepts no delivery target and defines no subagent-specific route result.
 - Caller signals stop start and follow-up only before inbox acceptance, while host-scoped and manager-global teardown retain child-first cleanup; the [current-turn interrupt](2026-08-06-continuable-subagent-interrupt.md) is the one public stop and does not enter teardown.
@@ -194,7 +194,7 @@ The implementation pins these behaviors:
 - Final Activation settlement awaits `ctx.sessions.flush(child.session)` as a best-effort barrier, logs rejection without interpreting listener participation as durability proof, then disposes the child handle and releases parent ownership so a flush failure cannot leak a `waiting` Activation.
 - Manager teardown closes admission globally; a host owning selected top-level Agents instead closes admission only below their exact identities until those roots leave the registry. Both track admitted materializations by exact ancestry, install one memoized disposal cutoff per selected visible Activation, propagate cancellation top-down, release handles child-first, await every selected branch despite individual failures, and only then dispose the corresponding top-level Agents or manager scope.
 - The base lifecycle has no implicit report behavior; the optional report package contributes an explicit child-scoped tool through the setup seam.
-- Session logs reconstruct only messages that were actually written, with their admitted provenance; inbox-accepted but unlogged messages have no restart guarantee.
+- Session logs reconstruct only messages that were actually written, with the source that supplied each message; inbox-accepted but unlogged messages have no restart guarantee.
 - No continuable-subagent path creates or depends on a Task, `TaskId`, Task completion notice, Task cancellation, or intermediate result-bearing execution wrapper.
 - Unit coverage pins the `startContinuable()` inbox-acceptance return boundary, complete rollback for each pre-acceptance and lifecycle-publication failure, global and parent-scoped drain quiescence for materialization caught between Agent publication and Activation registration, sibling-forest isolation, exact ancestry after an intermediate Agent leaves the registry, provider-independent cold resume, final exact-parent reauthorization after cold-resume materialization, caller-signal and teardown ownership on both sides of acceptance, and the absence of automatic replay for accepted-but-unlogged messages.
 - Unit coverage pins the residency-only routing table, single-inbox ordering, `MessageId` correlation through inbox events, follow-up during an open turn, waiting wakeup, cold resume, ownership registration and release, child-first disposal, send-versus-dispose races, best-effort final flush with absent and failing listeners, and the absence of public subagent cancellation and steering.
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index cd73d9a3b5..9752dab976 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -40,17 +40,17 @@ inbox 接受消息前发生任何失败，操作都会在不返回任何 id 的
 
 `backgroundMode: 'one-shot' | 'continuable'` 仍是部署策略。配置为 continuable 时要求存在 `prepareContinuable`；该方法是否存在会取代 `SubagentProvider.resume?()` 成为能力检查，而具备该能力的提供方仍可运行 one-shot 工作。
 
-冷恢复不会通过 subagent 提供方分发。继续执行管理器会归并通用的进程内描述符，通过同一个 activation-owner 作用域调用 `ctx.agents.resume()`，安装返回的 `AgentHandle`，并提交等待中的 `next-turn`。`SubagentProvider.resume?()` 和 `SubagentProviderResumeRequest` 均不存在。初始提供方注销后，其名称仍作为生命周期来源信息保留；它不是恢复能力，也不是后续驻留的必要条件。远程提供方需要单独设计。
+冷恢复不会通过 subagent 提供方分发。继续执行管理器会归并通用的进程内描述符，通过同一个 activation-owner 作用域调用 `ctx.agents.resume()`，安装返回的 `AgentHandle`，并提交等待中的 `next-turn`。`SubagentProvider.resume?()` 和 `SubagentProviderResumeRequest` 均不存在。初始提供方注销后，描述符仍保留其名称；该名称不赋予恢复能力，也不要求后续驻留时该提供方存在。远程提供方需要单独设计。
 
 `SubagentProvider.start()` 和 `SubagentRun` 只保留在不变的 one-shot 路径上。可继续激活直接持有自身的 `AgentHandle`，绝不创建、包装或保留 `SubagentRun`；因此，`SubagentRun.steer?()` 不存在。
 
-`ctx.subagents.followup(parent, childId, content, { source, signal })` 仍是唯一的从 parent 到 child 的继续执行消息操作。确切的在线 parent Agent 授权投递；冷恢复会在重建前检查该权限，每条路径还会在最终无 await 的 inbox 准入区间再次检查，因此在物化期间被注销或替换的 parent 无法授权投递。`source` 仍是持久化来源信息，不赋予任何权限。面向模型的 `send_message` 工具只保留稳定的 `subagent_id` 和 `message` 字段，并始终提交一个 follow-up 轮次。start 和 follow-up 都返回已接受的 `MessageId`，两者都不报告管理器如何物化激活。
+`ctx.subagents.followup(parent, childId, content, { source, signal })` 仍是唯一的从 parent 到 child 的继续执行消息操作。确切的在线 parent Agent 授权投递；冷恢复会在重建前检查该权限，每条路径还会在最终无 await 的 inbox 准入区间再次检查，因此在物化期间被注销或替换的 parent 无法授权投递。`source` 记录谁提供了获准消息，不赋予任何权限。面向模型的 `send_message` 工具只保留稳定的 `subagent_id` 和 `message` 字段，并始终提交一个 follow-up 轮次。start 和 follow-up 都返回已接受的 `MessageId`，两者都不报告管理器如何物化激活。
 
 对于 start 和 follow-up，调用方 signal 只在 inbox 接受消息前持有查找、物化和准入。操作返回 `MessageId` 后，管理器会独立持有该激活；调用方之后的取消不会取消已接受的轮次，也不会 dispose child。
 
 ### 持久化会话与在线激活
 
-会话持有稳定的 child 身份、transcript（文本记录）、直接 parent 谱系、委派深度和带版本的继续执行描述符。`SessionHeader.parentSession` 是持久化来源信息和鉴权输入；它不是在线路由能力，也不表示历史 parent 仍然驻留。
+会话持有稳定的 child 身份、transcript（文本记录）、直接 parent 谱系、委派深度和带版本的继续执行描述符。`SessionHeader.parentSession` 记录直接 parent，并作为鉴权输入；它不是在线路由能力，也不表示记录的 parent 仍然驻留。
 
 空闲的历史会话没有 `AgentHandle`。第一条通过鉴权的 `next-turn` 投递会根据持久化会话恢复激活，并将消息提交到其 inbox。冷恢复使用经过身份认证的确切在线 parent Agent 执行鉴权；当该 parent 有激活时，还使用它建立所有权，但绝不使用 parent 执行重建。
 
@@ -121,9 +121,9 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 后续宿主 UI 可以分别暴露 **Steer** 和 **Follow up** 操作。宿主 steering 必须严格且仅限在线使用：只有当激活接受下一步骤时，它才能调用现有的 Agent steering 路径；其他情况必须拒绝，而且绝不能转为排队或冷恢复。是否通过面向模型的工具暴露 parent steering 仍需单独设计。
 
-### 权限与来源
+### 权限与已记录的发送方身份
 
-权限来自确切的在线 Agent 工具上下文。`MessageSource` 和 `senderSessionId` 是准入后的持久化来源信息，不是由调用方控制的权限。
+权限来自确切的在线 Agent 工具上下文。准入后，`MessageSource` 和 `senderSessionId` 记录谁提供了消息；调用方不能用这些字段取得权限。
 
 本版本只授权持久化 child 的直接 parent。管理器会在将 child 注册到该 parent 的 `ownedChildren` 之前，于最终无 await 的 inbox 准入边界根据确切的在线 parent Agent 检查 `SessionHeader.parentSession`；冷恢复还会在重建前执行一次更早的检查，以便快速失败。其他 Agent、祖先、宿主、团队和工作流仍被拒绝，直至有具体消费方证明另一种权限协议合理。
 
@@ -137,7 +137,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 每个轮次都会请求执行会话持久性检查点，而 Activation 最终结算还会等待 `ctx.sessions.flush()`，将其作为 best-effort 屏障。管理器特意忽略布尔结果，因为 listener 是否参与无法标识持久化后端。rejection 会被记录，但不会改变生命周期结果或宿主 drain 的结果；管理器仍会 dispose handle 并释放所有权，后续恢复时持久化 child 状态可能缺失或陈旧。
 
-只有实际写入 child 会话日志的消息，才能根据其准入来源重建；仅被 inbox 接受并不提供重启保证。
+只有实际写入 child 会话日志的消息，才能在重建时保留提供它的来源；仅被 inbox 接受并不提供重启保证。
 
 会话和描述符的持久化状态可在重启后保留。激活状态、Agent inbox 内容和所有权图都是进程内状态。进程崩溃可能丢失已被接受但仍留在 inbox、尚未写入会话日志的初始提示词或 follow-up。会话和描述符可能保留，因此后续获得授权的消息仍可冷恢复 child，但丢失的消息不会自动回放。恢复已接受但未完成或未写入日志的消息需要持久化 inbox 协议，本提案不隐含该能力。
 
@@ -159,7 +159,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 **将报告投递纳入基础生命周期。** 可重复的 child 到 parent 报告与该生命周期兼容，但静默投递还是唤醒投递、确认、持久性和重试行为都是独立的产品决策。后续的 report 包保持可选，并消费一条显式 child 设置 seam，因此可继续驻留不会默认授予返回通道。
 
-**将 `SessionHeader.parentSession` 视为在线所有权。** 持久化谱系不能证明历史 parent 当前持有 child。在线 parent 的 `ownedChildren` 成员关系会记录进程内关系，而不改变持久化来源。
+**将 `SessionHeader.parentSession` 视为在线所有权。** 持久化谱系不能证明已记录的 parent 当前持有 child。在线 parent 的 `ownedChildren` 成员关系会记录进程内关系，而不改变持久化 parent id。
 
 **在单独的 link 中保留确切的 parent Agent。** parent 激活已经持有自身 `AgentHandle`，而且 `ownedChildren` 会在 child 仍然在线时阻止该激活 dispose。因此，通过会话 id 解析 parent 已经足够，也可以避免冗余的运行时引用。
 
@@ -181,7 +181,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 - `SubagentProvider.prepareContinuable?()` 只返回分离式 `ContinuableCreateSpec`；配置为 continuable 时要求具备该能力，而 `backgroundMode` 仍是独立的策略选择。
 - 管理器通过私有 activation-owner 作用域调用 `ctx.agents.create()`，安装返回的 `AgentHandle` 并建立 parent 所有权，调用 `Agent.followup(initialPrompt)`，然后在 inbox 接受消息并产生 `MessageId` 时返回 `{ childId, messageId }`，而不等待轮次开始或消息写入会话日志。
 - 初始提示词被 inbox 接受前的每条失败路径都会导致操作被拒绝且不返回 id，并通过一个对并发投递和 drain 可见的关闭事务回滚已创建的任何 handle、激活和 parent `ownedChildren` 成员关系；生命周期发布失败不会产生无配对的终止事件。
-- 冷恢复由继续执行管理器调用 `ctx.agents.resume()`，绝不通过或依赖初始 subagent 提供方；提供方移除后，持久化的提供方名称仍作为生命周期来源信息保留，且 `SubagentProvider.resume?()` 和 `SubagentProviderResumeRequest` 均不存在。
+- 冷恢复由继续执行管理器调用 `ctx.agents.resume()`，绝不通过或依赖初始 subagent 提供方；提供方移除后，描述符仍保留初始提供方名称，且 `SubagentProvider.resume?()` 和 `SubagentProviderResumeRequest` 均不存在。
 - 可继续激活直接持有 `AgentHandle`，绝不创建、包装或保留 `SubagentRun`；`SubagentProvider.start()` 和 `SubagentRun` 只用于 one-shot，且没有 `SubagentRun.steer?()`。
 - `followup()` 只接受确切的在线直接 parent，并在任何物化之后的最终无 await 的 inbox 准入边界再次检查该身份；持久化消息来源信息不能授权投递。
 - 继续执行消息始终使用 `Agent.followup()` 并共享其 inbox FIFO，包括 child 已有开放轮次的情况。
@@ -194,7 +194,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 - Activation 最终结算会等待 `ctx.sessions.flush(child.session)`，将其作为 best-effort 屏障；它会记录 rejection，但不会把 listener 参与解释为持久性证明，然后 dispose child handle 并释放 parent 所有权，使 flush 失败不会泄漏 `waiting` Activation。
 - 管理器拆卸会全局关闭准入；拥有选定顶层 Agent 的宿主则只关闭这些确切身份之下的准入，直到这些根离开注册表。两者都会按确切祖先关系跟踪已获准的物化过程，为每个选中的可见 Activation 安装一个记忆化 dispose 截止点，自顶向下传播取消，按 child-first 顺序释放 handle，即使个别分支失败也会等待所有选中分支，之后才 dispose 对应的顶层 Agent 或管理器作用域。
 - 基础生命周期不暴露隐式报告行为；可选的 report 包通过 setup seam 贡献一个显式的 child 作用域工具。
-- 会话日志只能根据准入来源重建实际写入的消息；已被 inbox 接受但未写入日志的消息没有重启保证。
+- 会话日志只会重建实际写入的消息，并保留每条消息的提供来源；已被 inbox 接受但未写入日志的消息没有重启保证。
 - 可继续 subagent 路径不创建或依赖 Task、`TaskId`、Task 完成通知、Task 取消或中间的带结果执行包装层。
 - 单元覆盖固定 `startContinuable()` 在 inbox 接受消息时的返回边界、每条接受前和生命周期发布失败路径的完整回滚、全局和限定到 parent 作用域的 drain 都会等待夹在 Agent 发布与 Activation 注册之间的物化过程完全停稳、同级森林隔离、中间 Agent 离开注册表后的确切祖先关系、不依赖提供方的冷恢复、冷恢复物化后的最终确切 parent 再授权、接受前后两个阶段的调用方 signal 与拆卸所有权，以及已接受但未写入日志的消息不会自动回放。
 - 单元覆盖固定仅由驻留状态决定的路由表、单 inbox 顺序、通过 inbox 事件关联 `MessageId`、在开放轮次期间 follow-up、等待唤醒、冷恢复、所有权注册与释放、child-first dispose、发送与 dispose 的竞争、没有 listener 和 listener 失败时的 best-effort 最终 flush，以及不存在公开 subagent 取消和 steering。
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
index 8e7e02fe37..716ac0d144 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.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 .agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
-2026-07-30-continuable-subagent-report-tool.md: 8324f1fa08f7dace6153712575e7e70a07ee9344
-2026-07-30-continuable-subagent-report-tool.zh.md: 6b7472717e724af9bf598fada6d7e82070d06f3c
+2026-07-30-continuable-subagent-report-tool.md: 6a607f1da48fdfde36b2d9351f131dd3ef67ba7f
+2026-07-30-continuable-subagent-report-tool.zh.md: 6dd408aff755ef7d4e27a62b347ffc839616c702
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
index 8324f1fa08..6a607f1da4 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md
@@ -28,7 +28,7 @@ The tool uses generic rendering with no locations. Its acknowledgement includes
 
 ### Service authority
 
-The subagent seam exposes `ctx.subagents.reportFrom(child, content, { delivery, signal }): Promise<MessageId>`. The exact live child Agent is the sender credential. The continuation manager accepts only an Activation whose `handle.agent === child`, derives its direct parent from the child's durable header, and requires that id to resolve to a live parent Agent in the final synchronous authorization-and-send span. The API accepts no caller-selected recipient, ancestor, or provenance.
+The subagent seam exposes `ctx.subagents.reportFrom(child, content, { delivery, signal }): Promise<MessageId>`. The exact live child Agent is the sender credential. The continuation manager accepts only an Activation whose `handle.agent === child`, derives its direct parent from the child's durable header, and requires that id to resolve to a live parent Agent in the final synchronous authorization-and-send span. The API accepts no caller-selected recipient, ancestor, or sender fields.
 
 Roots, one-shot children, forged objects, stale Agents, and same-id replacements fail with `UNAUTHORIZED`. A closing child Activation fails with `ACTIVATION_CLOSING`; manager drain and pre-acceptance cancellation retain their existing lifecycle errors. A missing or send-rejecting direct parent fails with `PARENT_UNAVAILABLE` and `direct parent is not live; report was not delivered`. Failure returns no id, cold-resumes no parent, writes no offline mailbox, and mutates no absent-parent Session.
 
@@ -42,7 +42,7 @@ Quiet delivery calls `parent.inject()`. It adds model-visible context without st
 
 Waking delivery calls `parent.followup()`. It creates one ordinary FIFO parent turn, wakes a parked parent driver, and never steers an open turn. When that parent is itself a continuable Activation, the send uses the manager's existing admission accounting so the parent cannot settle between synchronous enqueue and the admission microtask.
 
-Both modes frame one user-role message as `Background subagent <child-id> reported:` followed by the exact `output`. Durable provenance is `{ kind: 'subagent-report', senderSessionId: child.id }`. Normal Agent ordering governs concurrent sends; the subagent layer creates no second queue.
+Both modes frame one user-role message as `Background subagent <child-id> reported:` followed by the exact `output`. The durable message source is `{ kind: 'subagent-report', senderSessionId: child.id }`. Normal Agent ordering governs concurrent sends; the subagent layer creates no second queue.
 
 ### Acknowledgement and recovery
 
@@ -106,7 +106,7 @@ A post-creation revocation check can reject the Activation only after the Agent
 - Quiet delivery is the validated default and never starts a parent request. Wakeup creates exactly one later FIFO turn and never steers an open turn.
 - Child cancellation or disposal after parent acceptance does not retract the report. Before acceptance, child disposal, drain, parent loss, or caller cancellation rejects the operation.
 - Fresh and resumed Activations compose current setup contributions before publication. Grants wait for the next Activation; revocation is immediate for resident children.
-- Unit coverage pins visibility, allow-list behavior, both delivery modes, stable identity and provenance, nested routing, invalid senders, absent parents, cancellation, drain, revocation races, and the absence of Tasks or implicit final reporting.
+- Unit coverage pins visibility, allow-list behavior, both delivery modes, stable message and sender identities, nested routing, invalid senders, absent parents, cancellation, drain, revocation races, and the absence of Tasks or implicit final reporting.
 - The keyless assembled snapshot proves the real child tool, quiet non-wakeup behavior, durable parent framing, and later parent consumption.
 
 ### Accepted risks
diff --git a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
index 6b7472717e..6dd408aff7 100644
--- a/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ### 服务权限
 
-subagent seam 暴露 `ctx.subagents.reportFrom(child, content, { delivery, signal }): Promise<MessageId>`。确切的在线 child Agent 是发送方凭据。继续执行管理器只接受 `handle.agent === child` 的 Activation，从 child 的持久化 header 中推导其直接 parent，并要求该 id 在最终的同步授权与发送区间解析为一个在线 parent Agent。该 API 不接受由调用方选择的接收方、祖先或来源信息。
+subagent seam 暴露 `ctx.subagents.reportFrom(child, content, { delivery, signal }): Promise<MessageId>`。确切的在线 child Agent 是发送方凭据。继续执行管理器只接受 `handle.agent === child` 的 Activation，从 child 的持久化 header 中推导其直接 parent，并要求该 id 在最终的同步授权与发送区间解析为一个在线 parent Agent。该 API 不接受由调用方选择的接收方、祖先或发送方字段。
 
 root、one-shot child、伪造对象、陈旧 Agent 和同 id 替换对象都以 `UNAUTHORIZED` 失败。正在关闭的 child Activation 以 `ACTIVATION_CLOSING` 失败；管理器 drain 和接受前取消保留既有的生命周期错误。直接 parent 不存在或拒绝接受时，以 `PARENT_UNAVAILABLE` 和 `direct parent is not live; report was not delivered` 失败。失败不返回 id，不冷恢复 parent，不写入离线邮箱，也不会修改缺失 parent 的会话。
 
@@ -42,7 +42,7 @@ root、one-shot child、伪造对象、陈旧 Agent 和同 id 替换对象都以
 
 唤醒投递调用 `parent.followup()`。它会创建一个普通的 FIFO parent 轮次，唤醒已驻留的 parent driver，且绝不 steering 已开始的轮次。当该 parent 本身也是可继续 Activation 时，发送会使用管理器现有的准入计数，防止 parent 在同步入队与准入微任务之间结算。
 
-两种模式都会将一条用户角色消息封装为 `Background subagent <child-id> reported:`，后面跟随完全原样的 `output`。持久化来源信息为 `{ kind: 'subagent-report', senderSessionId: child.id }`。并发发送的顺序由 Agent 的常规规则决定；subagent 层不会创建第二条队列。
+两种模式都会将一条用户角色消息封装为 `Background subagent <child-id> reported:`，后面跟随完全原样的 `output`。持久化消息来源为 `{ kind: 'subagent-report', senderSessionId: child.id }`。并发发送的顺序由 Agent 的常规规则决定；subagent 层不会创建第二条队列。
 
 ### 确认与恢复
 
@@ -106,7 +106,7 @@ ACP（Agent Client Protocol）快照 harness 新增 `waitForSubagentTurnEnd`，
 - 静默投递是校验后的默认模式，绝不会启动 parent 请求。wakeup 会恰好创建一个后续 FIFO 轮次，绝不 steering 已开始的轮次。
 - parent 接受后取消或 dispose child 不会撤回报告。接受前，child dispose、drain、parent 丢失或调用方取消都会拒绝操作。
 - 新建和恢复的 Activation 都会在发布前组合当前设置贡献。新授权等待下一个 Activation 才生效，而已驻留 child 的授权撤销立即生效。
-- 单元覆盖固定可见性、allow-list 行为、两种投递模式、稳定身份与来源信息、嵌套路由、无效发送方、缺失的 parent、取消、drain、撤销竞争，以及不存在 Task 或隐式最终报告。
+- 单元覆盖固定可见性、allow-list 行为、两种投递模式、稳定的消息与发送方身份、嵌套路由、无效发送方、缺失的 parent、取消、drain、撤销竞争，以及不存在 Task 或隐式最终报告。
 - 无密钥整体组装快照证明真实 child 工具、静默且不唤醒的行为、持久化 parent 封装，以及 parent 后续消费。
 
 ### 已接受的风险
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
index f9944e3ed8..9921a12aee 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.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 .agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
-2026-07-30-queued-manual-compaction.md: 5100808ada4b7b284228113584e577d46ff91101
-2026-07-30-queued-manual-compaction.zh.md: fe3b0ff5e6b8cab7cb332f958adc6ab8d94f23b8
+2026-07-30-queued-manual-compaction.md: 94afdd84dfe573ee2b60eb3dbfdae2dd5b6beb1e
+2026-07-30-queued-manual-compaction.zh.md: 96eaa667eaee8adb42ec63e35beb0b32912c83a0
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
index 5100808ada..94afdd84df 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
@@ -91,7 +91,7 @@ That reference also carried client-side replacement-anchor machinery to preserve
 
 **Hold injection with waking prompts.** Rejected because idle injection is non-waking durable context by contract; delaying it would make plugin ordering depend on a UI command.
 
-**Require the marker interval to contain only compaction events.** Rejected because markers represent lock time points. Provenance names the selected and shadowed seqs exactly; exclusivity would add no correctness and would reject valid injection.
+**Require the marker interval to contain only compaction events.** Rejected because markers represent lock time points. `compact/summary` names the selected range and shadowed seqs exactly; exclusivity would add no correctness and would reject valid injection.
 
 **Treat every unmatched marker as permanently busy.** Rejected because a crash-recovered or forked session would remain wedged. `session/end-seed` is the explicit lifecycle evidence that distinguishes stale history from a live process-local attempt.
 
@@ -105,6 +105,6 @@ The command package pins registration, Loader composition, argument rejection, e
 
 Interactive users can compact useful history without spending a conversation-model turn. A prompt accepted before the command wins; one submitted during the command waits with its original queue identity. Manual compaction consumes session seqs but no turn number.
 
-The log exposes slow, failed, crashed, and successful attempts through the same bracket. A stale pre-boundary orphan no longer wedges a new lifecycle, while a current unmatched start remains a hard busy signal. Marker intervals may contain unrelated events, so consumers use provenance and relative ordering rather than assuming a contiguous compaction-only slice.
+The log exposes slow, failed, crashed, and successful attempts through the same bracket. A stale pre-boundary orphan no longer wedges a new lifecycle, while a current unmatched start remains a hard busy signal. Marker intervals may contain unrelated events, so consumers use the seqs recorded in `compact/summary` and relative ordering rather than assuming a contiguous compaction-only slice.
 
 The shared transaction keeps one ordering and one lock across every entry point. Failure reporting is precise about whether only the log changed, the surface may have partially changed, or the in-memory commit could not be persisted.
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
index fe3b0ff5e6..96eaa667ea 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
@@ -91,7 +91,7 @@ DSH 有意在调用摘要器前记录 `compact/start`。缓慢或崩溃的尝试
 
 **与唤醒提示词一起阻塞注入。** 不予采用，因为按约定，空闲注入是不会唤醒的持久上下文；延迟注入会使插件排序依赖某个 UI 命令。
 
-**要求标记区间只包含压缩事件。** 不予采用，因为标记表示锁的时间点。溯源信息会精确指明所选 seq 与被遮蔽 seq；排他性不会增加正确性，只会拒绝有效注入。
+**要求标记区间只包含压缩事件。** 不予采用，因为标记表示锁的时间点。`compact/summary` 会精确指明所选区间与被遮蔽 seq；排他性不会增加正确性，只会拒绝有效注入。
 
 **把每个未匹配标记都永久视为 busy。** 不予采用，因为崩溃恢复或 fork 后的会话会永久卡住。`session/end-seed` 是区分陈旧历史与当前进程活动尝试的显式生命周期证据。
 
@@ -105,6 +105,6 @@ Agent loop 测试覆盖同一 tick 内的优先权、保留 ID 与 FIFO 生命
 
 交互用户无需消耗会话模型轮次即可压缩有效历史。在命令前获接纳的提示词胜出；命令期间提交的提示词会以原有队列身份等待。手动压缩会消耗会话 seq，但不消耗轮次编号。
 
-日志通过同一对标记暴露缓慢、失败、崩溃与成功的尝试。边界前的陈旧未匹配标记不会再卡住新的生命周期，而当前未匹配 start 仍是严格的 busy 信号。标记区间可以包含不相关事件，因此消费方使用溯源信息与相对顺序，而不假定存在连续且仅含压缩事件的切片。
+日志通过同一对标记暴露缓慢、失败、崩溃与成功的尝试。边界前的陈旧未匹配标记不会再卡住新的生命周期，而当前未匹配 start 仍是严格的 busy 信号。标记区间可以包含不相关事件，因此消费方使用 `compact/summary` 记录的 seq 与相对顺序，而不假定存在连续且仅含压缩事件的切片。
 
 共享事务让每个入口点保持同一种顺序并使用同一把锁。失败报告会精确区分只有日志发生变化、surface 可能部分改变，以及内存 commit 无法持久化这三种情况。
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
index abb67be310..7876882425 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.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 .agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
-2026-08-04-web-context-source-and-steer-marks.md: ca44702cf637c4250d141396ac22d206a16acc15
-2026-08-04-web-context-source-and-steer-marks.zh.md: 09cefd07e3b417b63f05ce430cfed7b30597452f
+2026-08-04-web-context-source-and-steer-marks.md: d74badedaa9623014dbba10ae68ca680daf75de1
+2026-08-04-web-context-source-and-steer-marks.zh.md: f7a84db9d53a2f270ad47828c7aead2fd5ce8a68
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
index ca44702cf6..d74badedaa 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md
@@ -8,13 +8,13 @@ English | [中文](2026-08-04-web-context-source-and-steer-marks.zh.md)
 
 Everything a producer adds to the model-facing conversation reached the Web transcript as one of two anonymous shapes. Every logged non-user `user/message` — the skill catalog, the runtime snapshot, reconciled `AGENTS.md` instructions, a guard notice, a subagent report, a cross-session snapshot — collapsed into one identical `上下文注入` row, so a reader could not tell what had been added without expanding each row and reading raw JSON. Mid-turn steering was worse: it rendered in exactly the bubble a turn-opening prompt uses, leaving the transcript unable to say which message interrupted a running turn.
 
-The distinctions are already durable. `user/message.source` is the merge-extensible provenance every producer must supply, while `agent/inbox/spliced` records whether an identified message entered and left `next-turn` or `next-step`; only the presentation discarded them. The terminal transcript this Web UI replaced did name each card's producer, so the Web surface was a regression for the same log.
+The distinctions are already durable. Every producer must supply a merge-extensible `user/message.source` that identifies itself, while `agent/inbox/spliced` records whether an identified message entered and left `next-turn` or `next-step`; only the presentation discarded them. The terminal transcript this Web UI replaced did name each card's producer, so the Web surface was a regression for the same log.
 
 ## Decision
 
 The transcript names all three roles a non-prompt message can play — injected context, recalled session, and steering.
 
-`TranscriptAdapter` and the history fold attach a `provenance` view to every `ContextMessageNode`, computed by `contextProvenance()` from the durable source alone. It returns a `role` (`inject`, or `recall` for a cross-session snapshot) and a `label` naming the producer. `ContextInjectionRow` titles itself from the role and shows the label beside that title in `ToolRow`'s summary geometry, so the collapsed row already answers what was added and by whom; the 141px scrollport and truncation bound are unchanged from the [archived disclosure decision](../../archived/feature/2026-07-30-web-context-injection-disclosure.md). What renders inside that scrollport is chosen by the independent form axis added in the [context form decision](2026-08-05-context-form-vocabulary.md).
+`TranscriptAdapter` and the history fold attach a `provenance` view containing the producer role and label to every `ContextMessageNode`; `contextProvenance()` computes it from the durable source alone. It returns a `role` (`inject`, or `recall` for a cross-session snapshot) and a `label` naming the producer. `ContextInjectionRow` titles itself from the role and shows the label beside that title in `ToolRow`'s summary geometry, so the collapsed row already answers what was added and by whom; the 141px scrollport and truncation bound are unchanged from the [archived disclosure decision](../../archived/feature/2026-07-30-web-context-injection-disclosure.md). What renders inside that scrollport is chosen by the independent form axis added in the [context form decision](2026-08-05-context-form-vocabulary.md).
 
 **The label is read out of the log, never from a client-side table of producer names.** `workspace-instructions` is named by the distinct instruction paths it reconciled, `session-reference` by the titles of the sessions it read, a plugin source by its logged plugin id, and any other source by its own `kind` — the documented default arm for a merge-extensible union. A source carrying no readable kind degrades to an unnamed injection. A new or renamed producer is therefore identifiable without a client release, no label can go stale against the code, and a resumed, forked, or foreign log projects exactly like a live session.
 
@@ -24,7 +24,7 @@ The transcript names all three roles a non-prompt message can play — injected
 
 ## Alternatives considered
 
-**Localize producer names in the client.** A dictionary keyed by plugin id would read better than `@deepseek-ai/dsh-system-prompt`, but it drifts silently on every rename, needs a client change per new producer, and cannot name a producer from a foreign log at all. Provenance the log already carries is worth more than prose the client invents.
+**Localize producer names in the client.** A dictionary keyed by plugin id would read better than `@deepseek-ai/dsh-system-prompt`, but it drifts silently on every rename, needs a client change per new producer, and cannot name a producer from a foreign log at all. The producer name already recorded in the log is more reliable than a label the client invents.
 
 **Register presentations per source kind.** The disclosure decision deferred a keyed context-view slot until source-owned presentations emerged. Naming a row is not a distinct presentation, and a registry keyed on mounted producers would fail exactly where it matters — a resumed log whose producer is no longer mounted still has to render.
 
@@ -36,14 +36,14 @@ The transcript names all three roles a non-prompt message can play — injected
 
 ## Testing
 
-- `packages/client/runtime` unit coverage pins each provenance arm, the label fallbacks when a name field is missing, empty, or wrongly typed, the unnamed degradation for a source with no readable kind, and steering reconstruction on reset and live append paths.
+- `packages/client/runtime` unit coverage pins each source kind, the label fallbacks when a name field is missing, empty, or wrongly typed, the unnamed degradation for a source with no readable kind, and steering reconstruction on reset and live append paths.
 - `packages/client/ui-conversation` jsdom coverage pins the role title, the producer label beside it, the label's survival while expanded, the roleless header, and the steering caption on both durable and pending bubbles.
 - The keyless assembled-Web goldens carry the named header and the steering caption, so the assembled transcript — not only component tests — proves the marks.
 
 ## Consequences
 
 - A reader can attribute every non-prompt message in the transcript at a glance, and the header stays honest for logs this client version has never seen a producer for.
-- Producer names in the UI are package-shaped (`dsh-tool-skill`, `@deepseek-ai/dsh-system-prompt`) wherever the source carries only a plugin id. That is the cost of refusing a client-side name table; a producer that wants a better name records better provenance.
+- Producer names in the UI are package-shaped (`dsh-tool-skill`, `@deepseek-ai/dsh-system-prompt`) wherever the source carries only a plugin id. That is the cost of refusing a client-side name table; a producer that wants a better label must record one in its source fields.
 - `ContextMessageNode` gains a required field, so every constructed node — including test fixtures — must supply it.
 - `SteeringMessageNode` remains a distinct presentation node even though the agent loop now records admitted steering as `user/message`; its identity comes from the durable inbox history rather than a separate message event.
 - The `recall` arm has no producer in a shipped Web leaf until a host mounts `dsh-session-reference`; it is reachable only through logs written elsewhere.
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
index 09cefd07e3..f7a84db9d5 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.zh.md
@@ -8,13 +8,13 @@ Status: implemented
 
 生产方向模型侧对话补充的一切内容，进入 Web transcript（文本记录）后只剩两种匿名形态。每一条已记录的非用户 `user/message`——skill 目录、运行时快照、经过对账的 `AGENTS.md` 指令、guard 提示、子 agent 汇报、跨会话快照——都塌缩成同一行 `上下文注入`，读者不逐行展开去读原始 JSON 就无从知道究竟注入了什么。steering（中途引导）的情况更糟：它渲染成与开轮提示完全相同的气泡，于是 transcript 无法说明哪一条消息打断了正在运行的轮次。
 
-这些区分本来就是持久事实。`user/message.source` 是每个生产方都必须提供的可合并扩展来源，`agent/inbox/spliced` 则记录有身份的消息是从 `next-turn` 还是 `next-step` 进入和离开；把这些事实丢掉的只有呈现层。被这套 Web UI 取代的终端 transcript 本来会写出每张卡片的生产者，因此面对同一份日志，Web 侧是一次倒退。
+这些区分本来就是持久事实。每个生产方都必须提供可合并扩展的 `user/message.source` 并在其中注明自己，`agent/inbox/spliced` 则记录有身份的消息是从 `next-turn` 还是 `next-step` 进入和离开；把这些事实丢掉的只有呈现层。被这套 Web UI 取代的终端 transcript 本来会写出每张卡片的生产者，因此面对同一份日志，Web 侧是一次倒退。
 
 ## Decision
 
 transcript 为非提示消息可能承担的三种角色分别命名：注入上下文、召回会话、steering。
 
-`TranscriptAdapter` 与历史折叠为每个 `ContextMessageNode` 附加一份 `provenance` 视图，由 `contextProvenance()` 仅依据持久来源计算得出。它返回 `role`（`inject`，跨会话快照则为 `recall`）与命名生产者的 `label`。`ContextInjectionRow` 以角色作为标题，并按 `ToolRow` 摘要的几何在标题旁展示该名称，因此折叠态就已经回答了「注入了什么、由谁注入」；141px 滚动视口与截断上限沿用[已归档的展开项决策](../../archived/feature/2026-07-30-web-context-injection-disclosure.md)，未作改动。视口里渲染什么，则由[上下文形态决策](2026-08-05-context-form-vocabulary.md)引入的、相互独立的形态轴决定。
+`TranscriptAdapter` 与历史折叠为每个 `ContextMessageNode` 附加一份包含生产者角色和名称的 `provenance` 视图；`contextProvenance()` 仅依据持久来源计算该视图。它返回 `role`（`inject`，跨会话快照则为 `recall`）与命名生产者的 `label`。`ContextInjectionRow` 以角色作为标题，并按 `ToolRow` 摘要的几何在标题旁展示该名称，因此折叠态就已经回答了「注入了什么、由谁注入」；141px 滚动视口与截断上限沿用[已归档的展开项决策](../../archived/feature/2026-07-30-web-context-injection-disclosure.md)，未作改动。视口里渲染什么，则由[上下文形态决策](2026-08-05-context-form-vocabulary.md)引入的、相互独立的形态轴决定。
 
 **名称从日志中读出，绝不来自客户端维护的生产者名称表。** `workspace-instructions` 以它对账过的去重指令文件路径命名，`session-reference` 以它读取的会话标题命名，插件来源以其记录的插件 id 命名，其余来源则以自身的 `kind` 命名——这正是可合并扩展联合类型有文档记载的默认分支。没有可读 kind 的来源降级为无名注入。于是新增或重命名的生产者无需客户端发版即可辨识，任何名称都不会相对代码变味，恢复、fork 或来自外部的日志与实时会话的投影结果完全一致。
 
@@ -24,7 +24,7 @@ transcript 为非提示消息可能承担的三种角色分别命名：注入上
 
 ## Alternatives considered
 
-**在客户端本地化生产者名称。** 以插件 id 为键的字典读起来确实比 `@deepseek-ai/dsh-system-prompt` 好，但它会在每次重命名时悄悄失准，每新增一个生产者都要改客户端，而且对来自外部的日志根本无法命名。日志已经承载的来源，比客户端自己编出来的措辞更有价值。
+**在客户端本地化生产者名称。** 以插件 id 为键的字典读起来确实比 `@deepseek-ai/dsh-system-prompt` 好，但它会在每次重命名时悄悄失准，每新增一个生产者都要改客户端，而且对来自外部的日志根本无法命名。日志已经记录的生产者名称，比客户端自己编造的标签更可靠。
 
 **按来源 kind 注册呈现。** 展开项决策把键控的 context-view 槽位推迟到出现由来源自有的呈现需求为止。为一行命名并不构成独立呈现，而以「已挂载的生产者」为键的注册表恰恰会在最要紧的地方失效——生产者已不再挂载的恢复日志同样必须渲染出来。
 
@@ -43,7 +43,7 @@ transcript 为非提示消息可能承担的三种角色分别命名：注入上
 ## Consequences
 
 - 读者一眼即可归因 transcript 中每一条非提示消息；即便面对本客户端版本从未见过其生产者的日志，标题栏依然如实。
-- 只要来源仅携带插件 id，UI 中的生产者名称就呈现为包名形态（`dsh-tool-skill`、`@deepseek-ai/dsh-system-prompt`）。这是拒绝客户端名称表的代价；想要更好名称的生产者应当记录更好的来源。
+- 只要来源仅携带插件 id，UI 中的生产者名称就呈现为包名形态（`dsh-tool-skill`、`@deepseek-ai/dsh-system-prompt`）。这是拒绝客户端名称表的代价；想要更好标签的生产者必须在来源字段中记录该标签。
 - `ContextMessageNode` 增加了一个必填字段，因此每一处构造该节点的代码——包括测试 fixture——都必须提供它。
 - 即使 agent loop 现在把已经接纳的 steering 记录为 `user/message`，`SteeringMessageNode` 仍是独立的呈现节点；它的身份来自持久 inbox 历史，而不是独立消息事件。
 - 在某个宿主挂载 `dsh-session-reference` 之前，`recall` 分支在已发布的 Web 叶子中没有生产者，只能通过别处写入的日志抵达。
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
index 65d14e9aa4..e407eccd64 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.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 .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
-2026-08-05-context-form-vocabulary.md: 618c11b925208d09a62d10101656e3358e327ddb
-2026-08-05-context-form-vocabulary.zh.md: 66278b261f23601461c96f08e87ea58766b2bfc2
+2026-08-05-context-form-vocabulary.md: 7750523b89ebdda125a7bae8a853ab28a20eeb3f
+2026-08-05-context-form-vocabulary.zh.md: 8a6ced60b254ddf5e9075d199be98b3fbe442e2b
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
index 618c11b925..7750523b89 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-05-context-form-vocabulary.zh.md)
 
 ## Problem
 
-Every logged non-user `user/message` rendered through one body: the whole message serialized as inline JSON. A reader opening a row met `{ "content": [ { "type": "text", "text": "…\n\n…" } ], "source": { … } }`, where the escaping had collapsed the only thing worth reading — the model-facing prose — into a single line, and the provenance sat inside the same blob.
+Every logged non-user `user/message` rendered through one body: the whole message serialized as inline JSON. A reader opening a row met `{ "content": [ { "type": "text", "text": "…\n\n…" } ], "source": { … } }`, where the escaping had collapsed the only thing worth reading — the model-facing prose — into a single line, and the producer fields sat inside the same blob.
 
 Naming the producer in the header (the [source and steer marks decision](2026-08-04-web-context-source-and-steer-marks.md)) fixed *who added this*. It could not fix *what kind of thing was added*, because nothing in the log said so. Injected context is not one shape: a reconciled `AGENTS.md`, a catalog of available skills, a runtime policy snapshot, and a subagent's report are as different from each other as a terminal card is from a diff card, yet all four presented as the same wall of escaped JSON.
 
@@ -16,7 +16,7 @@ The tool surface already solved this shape. `ToolCallView` has three cards, not
 
 `MessageSource` gains an optional producer-declared `form: ContextForm` — a small tagged vocabulary of information *shapes*, independent of `kind`:
 
-- `kind` answers **who produced this** and remains pure provenance.
+- `kind` answers **who produced this** and carries no presentation choice.
 - `form` answers **what shape of information it is**. Several producers may share one form, and one producer may emit more than one over a session.
 
 The vocabulary is semantic, never visual. A value states that the content is a file's instructions or a catalog of available items; colors, icons, ordering, and collapse defaults are the consumer's business and must not enter the union. It grows one value at a time, as producers gain the structured fields their form needs. This release declares two:
@@ -41,7 +41,7 @@ Both readers are **all-or-nothing**: one unreadable entry disqualifies the recor
 
 The producer side validates the same durable data with the same posture. `catalogHistory` reads `source.entries` out of `agent.session.events`, which on resume or fork is a JSONL/SQLite seed whose validation only guarantees a source object with a non-empty `kind` — no per-kind field is checked. An unreadable catalog is therefore skipped as "not this plugin's record", the posture the replaced content digest had; throwing there would fail every later step of that session at the latest, least diagnosable point.
 
-Everything else — including a form this UI version does not present, a form absent from the source, and a `catalog` whose entries are unusable — renders the **opaque** body: the model-facing text with its real line breaks, then the remaining provenance as fields. Opaque is the documented default, not a leftover bin. A resumed, forked, or foreign log must render whether or not its producer is mounted here, which is also why the classification lives in the durable source rather than in a client-side table keyed by producer.
+Everything else — including a form this UI version does not present, a form absent from the source, and a `catalog` whose entries are unusable — renders the **opaque** body: the model-facing text with its real line breaks, then the remaining source data as fields. Opaque is the documented default; the contract assigns these unsupported cases to it. A resumed, forked, or foreign log must render whether or not its producer is mounted here, which is also why the classification lives in the durable source rather than in a client-side table keyed by producer.
 
 ## Why not a presenter registry
 
@@ -51,7 +51,7 @@ The tool seam pairs its vocabulary with `presentCall(args)`, a host-side pure fu
 
 **Map source kinds to renderers in the client.** Cheapest to write and requires no format change, but it puts producer knowledge back in the client: every new kind then needs a client release to render as anything but opaque, and a foreign log cannot be classified at all. It also reintroduces exactly the coupling the [source and steer marks decision](2026-08-04-web-context-source-and-steer-marks.md) removed for labels.
 
-**Reuse `kind` as the form.** One discriminant is simpler, and `workspace-instructions` is already 1:1 with its form. It breaks on the shared shapes: three producers emit runtime snapshots today, and folding them into one kind would erase their provenance. Two axes keep provenance exact while letting presentations be shared.
+**Reuse `kind` as the form.** One discriminant is simpler, and `workspace-instructions` is already 1:1 with its form. It breaks on the shared shapes: three producers emit runtime snapshots today, and folding them into one kind would erase which producer supplied each message. Two axes keep the producer exact while letting presentations be shared.
 
 **Let the client parse the model-facing prose.** The entries and file sections are visibly structured in the text. Parsing them couples the presentation to prompt wording, so every reword silently breaks a card — the same reason catalog identity moved off the text.
 
@@ -60,14 +60,14 @@ The tool seam pairs its vocabulary with `presentCall(args)`, a host-side pure fu
 ## Testing
 
 - `packages/client/runtime` pins the form projection, including the unknown, empty, wrongly-typed, and absent values that must degrade to opaque.
-- `packages/client/ui-conversation` pins each body: the opaque body's preserved line breaks and provenance fields, the instructions body's file list and verbatim framing, the catalog body's entry list, and a catalog with unusable entries falling back to opaque.
+- `packages/client/ui-conversation` pins each body: the opaque body's preserved line breaks and source fields, the instructions body's file list and verbatim framing, the catalog body's entry list, and a catalog with unusable entries falling back to opaque.
 - `packages/skill/tool-skill` pins the new source on first publication and replacement, republish behavior driven by the durable entries, and a malformed durable catalog leaving step observation intact.
 - The keyless assembled-Web seeded-history scenario expands a real `instructions` context in Chromium and asserts its file list, verbatim framing, and the unchanged disclosure geometry. `catalog` has no assembled coverage: the hermetic scaffold publishes no skills, so no catalog reaches a browser scenario.
 
 ## Consequences
 
 - A reader can tell what was added without expanding, and reading it no longer means reading escaped JSON.
-- The durable `MessageSource` now carries a semantic classification beside provenance. The boundary is load-bearing: facts and shape only, never presentation. A producer that wants a better card records better facts.
+- The durable `MessageSource` now records content shape beside the producer kind and its fields. The boundary is load-bearing: facts and shape only, never presentation. A producer that wants a better card records better facts.
 - Catalog identity no longer depends on the model-facing prose, deleting the text-slicing path that could mistake a reworded catalog for a changed one.
 - Every shipped producer except the two hook bridges now declares a form. The bridges stay opaque by design: their content is whatever an external program printed, so no shape can be promised for it. Unknown kinds and unreadable records land there too.
 - `ContextFormed` is discriminated by `form`, so a producer cannot declare a shape without the facts that shape is presented from — a `notice` without its summary, or a `snapshot` without its sections, fails to compile.
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
index 66278b261f..8a6ced60b2 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## Problem
 
-每一条已记录的非用户 `user/message` 都通过同一个内容区渲染：把整条消息序列化成内联 JSON。读者展开一行，看到的是 `{ "content": [ { "type": "text", "text": "…\n\n…" } ], "source": { … } }`——转义把唯一值得读的东西（面向模型的散文）压成了一行，而来源信息又和它挤在同一坨里。
+每一条已记录的非用户 `user/message` 都通过同一个内容区渲染：把整条消息序列化成内联 JSON。读者展开一行，看到的是 `{ "content": [ { "type": "text", "text": "…\n\n…" } ], "source": { … } }`——转义把唯一值得读的东西（面向模型的散文）压成了一行，生产者字段也放在同一个 JSON 对象中。
 
 在标题栏写出生产者（[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)）解决了「这是谁加的」。它解决不了「加进来的是什么东西」，因为日志里根本没有这句话。注入上下文不是一种形状：对账后的 `AGENTS.md`、可用 skill 的目录、运行时策略快照、子 agent 的汇报，彼此之间的差别不亚于终端卡片与 diff 卡片，然而这四者呈现出来是同一堵转义 JSON 的墙。
 
@@ -16,7 +16,7 @@ Status: implemented
 
 `MessageSource` 新增一个可选、由生产方声明的 `form: ContextForm`——一份关于信息**形状**的小型 tagged 词汇表，与 `kind` 相互独立：
 
-- `kind` 回答**由谁产生**，保持纯粹的溯源语义。
+- `kind` 回答**由谁产生**，不携带呈现选择。
 - `form` 回答**这是何种形态的信息**。多个生产方可以共用一种形态，一个生产方在一次会话中也可以发出多种。
 
 该词汇表是语义的，绝不涉及视觉。取值只陈述「内容是某个文件的指令」或「是一份可用项目录」；颜色、图标、排序、默认折叠状态归消费方管，不得进入这个联合类型。它随生产方补齐各自形态所需的结构化字段而逐个增长。本次声明两个：
@@ -41,7 +41,7 @@ Status: implemented
 
 生产方一侧对同一份持久数据采取同样的姿态。`catalogHistory` 从 `agent.session.events` 读 `source.entries`，而恢复或 fork 时它来自 JSONL／SQLite 种子，种子验证只保证来源是带非空 `kind` 的对象，不校验任何 kind 特有字段。因此不可读的目录被当作「不是本插件的记录」跳过——正是被替换掉的内容 digest 原有的姿态；在那里抛错会让该会话此后每一步都在最晚、最难定位的点失败。
 
-其余一切——包括本 UI 版本不呈现的形态、来源未声明形态、以及条目不可用的 `catalog`——一律渲染 **opaque** 内容区：按真实换行展示面向模型的文本，其后把剩余来源信息列成字段。opaque 是有文档的默认，不是兜底垃圾桶。恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处都必须渲染得出来——这同样是分类信息必须落在持久来源里、而不是落在客户端以生产方为键的表里的原因。
+其余一切——包括本 UI 版本不呈现的形态、来源未声明形态、以及条目不可用的 `catalog`——一律渲染 **opaque** 内容区：按真实换行展示面向模型的文本，其后把剩余来源数据列成字段。opaque 是文档规定的默认；约定要求这些不支持的情况使用它。恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处都必须渲染得出来——这同样是分类信息必须落在持久来源里、而不是落在客户端以生产方为键的表里的原因。
 
 ## 为什么不做 presenter 注册表
 
@@ -51,7 +51,7 @@ Status: implemented
 
 **在客户端把来源 kind 映射到渲染器。** 写起来最省，也不用改格式，但它把生产方知识放回了客户端：此后每新增一个 kind 都要客户端发版才能渲染成 opaque 以外的东西，而外部日志根本无法分类。它还会重新引入[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)刚为名称去掉的那种耦合。
 
-**复用 `kind` 充当形态。** 单一判别式更简单，`workspace-instructions` 本来也与它的形态一一对应。但它在共享形状上就崩了：今天有三个生产方发出运行时快照，把它们并成一个 kind 会抹掉各自的溯源。两根轴既保住溯源的精确，又让呈现可以共享。
+**复用 `kind` 充当形态。** 单一判别式更简单，`workspace-instructions` 本来也与它的形态一一对应。但它在共享形状上就崩了：今天有三个生产方发出运行时快照，把它们并成一个 kind 会删除每条消息中标明其生产方的 `source` 字段。两根轴会保留准确的生产方，同时让呈现方式可以共享。
 
 **让客户端解析面向模型的散文。** 条目与文件分节在文本里确实有可见结构。解析它们会把呈现耦合到 prompt 措辞上，于是每改一次文案就静默碎掉一张卡——这也正是目录身份从文本上迁走的原因。
 
@@ -67,7 +67,7 @@ Status: implemented
 ## Consequences
 
 - 读者不展开就能知道加进来的是什么，展开之后读到的也不再是转义 JSON。
-- 持久 `MessageSource` 现在在溯源之外还承载一个语义分类。这条边界是承重的：只放事实与形状，绝不放呈现。想要更好卡片的生产方应当记录更好的事实。
+- 持久 `MessageSource` 现在会在生产者 kind 及其字段之外记录内容形状。这条边界是承重的：只放事实与形状，绝不放呈现。想要更好卡片的生产方应当记录更好的事实。
 - 目录身份不再依赖面向模型的散文，删掉了那条可能把「改了措辞」误判为「改了内容」的文本切分路径。
 - 除两个 hook 桥接外，每个已发布的生产方现在都声明了形态。桥接按设计保持 opaque：其内容是外部程序打印出来的任意文本，无法承诺任何形状。未知 kind 与不可读记录同样落在这里。
 - `ContextFormed` 按 `form` 判别，因此生产方无法在缺少该形态所需事实的情况下声明它——没有 summary 的 `notice`、没有 sections 的 `snapshot`，都会编译失败。
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 483a429f97..3ae0cff501 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 9a3f80df592f28adc365d5e64cc15516d92b47b5
-2026-06-20-core-data-structures-catalog.zh.md: a1184cb25823c10949713271434628c3650678dd
+2026-06-20-core-data-structures-catalog.md: fd2b8ef8c7a43d9835cfbc39fc296465d7f5aba5
+2026-06-20-core-data-structures-catalog.zh.md: 6aafdd70384c89ce39113227d11db93f53107442
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 9a3f80df59..fd2b8ef8c7 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -35,7 +35,7 @@ The durability requirement was specific: the doc shows the **literal** current t
 
 - Complete type declarations and their JSDoc are pasted verbatim into a dedicated ` ```ts type-equiv ` fence. A concise ` ```ts public-api ` fence carries the source-equivalent ambient projection for a class whose implementation bodies do not belong in the catalog. `doc-typecheck` recognizes both and skips them (the bare declarations are not standalone-compilable), and **excludes them from the opt-out ratio** — they are a separately-checked category, not unchecked sketches.
 - A new `scripts/verify-type-equiv.ts` extracts each block via the TypeScript parser and asserts that its declaration structure and every JSDoc comment match the declared symbol, ignoring only formatting whitespace and non-JSDoc comments. Ordinary blocks retain the complete declaration. A `public-api` projection retains a class's public fields, constructor, accessors, and methods with their original JSDoc while removing implementation bodies and private or protected members. This is chosen over a compiled `_Check` assertion because source names and documentation identity, not assignability, are the properties the catalog preserves.
-- Provenance lives in a central `scripts/type-equiv.manifest.json` (`{ doc, symbol, source }` entries), **not** in directive comments in the prose. The script enforces a **1:1 correspondence** between each primary type-equiv block and one manifest entry, so a block can never be silently unchecked and an entry can never rot. A paired `.zh.md` block reuses the unsuffixed sibling's entry only when the complete tracked fence sequence matches in order, kind, and byte-exact body; otherwise the gate checks it independently, finds no manifest entry, and fails.
+- Each type block's document, symbol, and source file are recorded in `scripts/type-equiv.manifest.json` (`{ doc, symbol, source }` entries), **not** in directive comments in the prose. The script enforces a **1:1 correspondence** between each primary type-equiv block and one manifest entry, so a block can never be silently unchecked and an entry can never rot. A paired `.zh.md` block reuses the unsuffixed sibling's entry only when the complete tracked fence sequence matches in order, kind, and byte-exact body; otherwise the gate checks it independently, finds no manifest entry, and fails.
 - Wired into `doc-sync`, so relevant documentation changes run it locally and CI runs it with the other documentation checks.
 
 ### Maintenance is the author's job, with a gate backstop
@@ -46,7 +46,7 @@ The durability requirement was specific: the doc shows the **literal** current t
 
 - **A flat dump of all cross-package vocabulary** — the `BashExecRequest` test case killed it: if seam vocabulary is "core", the catalog helps no one; the tiered spine-vs-seam structure won.
 - **A compiled `_Check` assignability assertion** instead of the source match — rejected because assignability does not preserve names or JSDoc: a renamed field with the same type or a changed contract comment would pass.
-- **Provenance as directive comments in the prose** — rejected for the central manifest, whose enforced 1:1 correspondence means a block can never be silently unchecked and an entry can never rot.
+- **Put each type block's source in a directive comment** — rejected for the central manifest, whose enforced 1:1 correspondence means a block can never be silently unchecked and an entry can never rot.
 
 ## Verification lesson
 
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index a1184cb258..6aafdd7038 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -35,7 +35,7 @@ Status: implemented
 
 - 完整的类型声明及其 JSDoc 会逐字粘贴到专用的 ` ```ts type-equiv ` 围栏中。简洁的 ` ```ts public-api ` 围栏承载类的源码等价环境声明投影，用于实现体不应进入目录的类。`doc-typecheck` 会识别并跳过这两种围栏（裸声明无法独立编译），并且**将它们排除在 opt-out 比例之外**——它们是单独受检的类别，而不是未经检查的草图。
 - 新增的 `scripts/verify-type-equiv.ts` 通过 TypeScript 解析器提取每个块，并断言其声明结构和每条 JSDoc 注释都与所声明的符号匹配，只忽略格式空白和非 JSDoc 注释。普通块保留完整声明。`public-api` 投影保留类的公共字段、构造函数、访问器和方法及其原始 JSDoc，同时移除实现体以及私有或受保护成员。之所以选择它而非编译式 `_Check` 断言，是因为目录所保留的是源码名称与文档一致性，而不是可赋值性。
-- 来源信息存放在集中的 `scripts/type-equiv.manifest.json`（`{ doc, symbol, source }` 条目）中，**而非**行文中的指令注释。脚本在每个主 type-equiv 块与一条 manifest（元数据清单）条目之间强制执行 **1:1 对应**，因此一个块永远不会被静默漏检，一条条目也永远不会腐烂。只有当配对 `.zh.md` 块的完整受跟踪围栏序列在顺序、类型和按字节精确的正文上均与无后缀兄弟文件匹配时，才会复用后者的条目；否则门禁会独立检查该块，发现没有 manifest 条目后失败。
+- 每个类型块的文档、symbol 和源文件都记录在集中的 `scripts/type-equiv.manifest.json`（`{ doc, symbol, source }` 条目）中，**而非**行文中的指令注释。脚本在每个主 type-equiv 块与一条 manifest（元数据清单）条目之间强制执行 **1:1 对应**，因此一个块永远不会被静默漏检，一条条目也永远不会腐烂。只有当配对 `.zh.md` 块的完整受跟踪围栏序列在顺序、类型和按字节精确的正文上均与无后缀兄弟文件匹配时，才会复用后者的条目；否则门禁会独立检查该块，发现没有 manifest 条目后失败。
 - 接入 `doc-sync`，因此相关文档变更会在本地运行它，CI 也会与其他文档检查一起运行它。
 
 ### 维护是作者的职责，门禁作为兜底
@@ -46,7 +46,7 @@ Status: implemented
 
 - **平铺罗列所有跨包词汇**：`BashExecRequest` 测试案例否决了它。如果 seam 词汇算「核心」，目录对谁都没帮助；分层的主干与 seam 结构胜出。
 - **用编译式 `_Check` 可赋值性断言**代替源码匹配：否决。可赋值性不会保留名称或 JSDoc；同类型字段改名或约定注释变化仍会通过。
-- **来源信息作为行文中的指令注释**：否决，改用集中 manifest；其强制的 1:1 对应确保一个块永远不会被静默漏检，一条条目也永远不会腐烂。
+- **将每个类型块的源文件写进指令注释**：否决，改用集中 manifest；其强制的 1:1 对应确保一个块永远不会被静默漏检，一条条目也永远不会腐烂。
 
 ## 验证教训
 
diff --git a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.i18n.yaml
index 4dee769645..c39852515a 100644
--- a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.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 .agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md
-2026-07-27-worktree-local-lefthook.md: 75dfd47087356c34005ec4673e174e451a72c660
-2026-07-27-worktree-local-lefthook.zh.md: 42d4d89e375dfd7b28298d89e82c5e9e74908062
+2026-07-27-worktree-local-lefthook.md: 5a10c5d3769bbe5ad1fd0407982bb34c8763e2ae
+2026-07-27-worktree-local-lefthook.zh.md: e7e96f2317368621a348f4a851672bbec1b7e857
diff --git a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md
index 75dfd47087..5a10c5d376 100644
--- a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md
+++ b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md
@@ -12,7 +12,7 @@ Lefthook-generated hooks prefer an absolute binary path captured from the instal
 
 ## Decision
 
-Hook installation is worktree-scoped. With `CI=true` or `GITHUB_ACTIONS=true`, the installer returns before Git discovery or mutation because automated jobs do not consume contributor hooks. Otherwise, it requires Git 2.26 or newer for configuration-scope provenance, upgrades a format-0 repository to format 1, enables `extensions.worktreeConfig`, and assigns the current worktree an absolute `core.hooksPath` at `$GIT_DIR/dsh-hooks`.
+Hook installation is worktree-scoped. With `CI=true` or `GITHUB_ACTIONS=true`, the installer returns before Git discovery or mutation because automated jobs do not consume contributor hooks. Otherwise, it requires Git 2.26 or newer so `git config --show-scope` can report which scope supplied a value, upgrades a format-0 repository to format 1, enables `extensions.worktreeConfig`, and assigns the current worktree an absolute `core.hooksPath` at `$GIT_DIR/dsh-hooks`.
 
 Before upgrading format 0, the installer refuses direct common-config `extensions.*`; it also refuses direct `core.worktree` or `core.bare=true` and non-empty dormant worktree configs that enabling the extension would activate. The migration removes direct `core.bare=false` because false is Git's default. The common repository config and every existing `config.worktree` must be regular files. These checks disable include expansion because Git's repository-format parser also ignores included targets. A repository-scoped lock serializes migration and hook writes; its process ID, random token, file identity, and exact contents must still match at release. Dead or invalid locks require manual recovery rather than automatic breaking.
 
diff --git a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md
index 42d4d89e37..e7e96f2317 100644
--- a/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md
+++ b/.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.zh.md
@@ -12,7 +12,7 @@ Lefthook 生成的钩子会优先使用安装时从对应 worktree 记录的绝
 
 ## 决策
 
-钩子安装以 worktree 为作用域。当 `CI=true` 或 `GITHUB_ACTIONS=true` 时，安装程序会在探测 Git 或做出任何变更之前返回，因为自动化任务不会使用贡献者钩子。否则，为了获取配置作用域的来源信息，安装程序要求 Git 2.26 或更高版本；它会将格式版本为 0 的仓库升级到格式版本 1，启用 `extensions.worktreeConfig`，并将当前 worktree 的 `core.hooksPath` 设为指向 `$GIT_DIR/dsh-hooks` 的绝对路径。
+钩子安装以 worktree 为作用域。当 `CI=true` 或 `GITHUB_ACTIONS=true` 时，安装程序会在探测 Git 或做出任何变更之前返回，因为自动化任务不会使用贡献者钩子。否则，安装程序要求 Git 2.26 或更高版本，使 `git config --show-scope` 可以报告由哪个作用域提供配置值；它会将格式版本为 0 的仓库升级到格式版本 1，启用 `extensions.worktreeConfig`，并将当前 worktree 的 `core.hooksPath` 设为指向 `$GIT_DIR/dsh-hooks` 的绝对路径。
 
 升级格式 0 之前，安装程序会拒绝共用配置中直接设置的 `extensions.*`；它还会拒绝直接设置的 `core.worktree` 或 `core.bare=true`，以及启用扩展后将被激活的非空且尚未生效的 worktree 配置。迁移会移除直接设置的 `core.bare=false`，因为 false 是 Git 的默认值。共用仓库配置和每个已有的 `config.worktree` 都必须是常规文件。这些检查会禁用 include 展开，因为 Git 的仓库格式解析器也会忽略 include 目标。仓库级锁会串行化迁移和钩子写入；释放时，锁的进程 ID、随机令牌、文件身份和完整内容必须仍然匹配。所属进程已结束或内容无效的锁必须手动恢复，不会被自动破坏。
 
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
index 9cef49fa0a..ced42801aa 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.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 .agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
-2026-08-06-in-repository-landlock-release.md: 3ae9e9c3c50a1d0202a345e419cb2b7079e29ffa
-2026-08-06-in-repository-landlock-release.zh.md: ffebe45c537ee192ef855296b3334937485e2a89
+2026-08-06-in-repository-landlock-release.md: 1540cebbf5a3dffa20003c70ffcec426aeca104b
+2026-08-06-in-repository-landlock-release.zh.md: eaa576f0b39630eb07286906c1f537a0498ad646
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
index 3ae9e9c3c5..1540cebbf5 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.md
@@ -8,7 +8,7 @@ English | [中文](2026-08-06-in-repository-landlock-release.zh.md)
 
 The `@deepseek-ai/node-addon-landlock-run` source already lives beside its DeepSeek Harness consumers under `native/landlock-run`, but it previously kept a separate pnpm workspace and lockfile and depended on a standalone repository for npm publication. Harness packages consumed a fixed registry version, so one pull request could change the launcher contract and its consumer without testing those changes together. The source repository's native workflow could rehearse the package, but it did not publish the artifact it tested.
 
-The mirror also duplicated release coordination: export the source, update another lockfile, run another release workflow, publish the native family, then return to this repository to bump registry dependencies. That split made source-to-binary provenance, rollback, and security-fix coordination harder without changing what npm users actually needed.
+The mirror also duplicated release coordination: export the source, update another lockfile, run another release workflow, publish the native family, then return to this repository to bump registry dependencies. That split made it harder to match each binary to its source commit, roll back releases, and coordinate security fixes without changing what npm users actually needed.
 
 The existing unscoped npm names are owned by the standalone publisher account rather than the `@deepseek-ai` organization. Moving only the workflow would therefore leave publication dependent on a personal credential outside the repository's release ownership.
 
@@ -37,7 +37,7 @@ Launcher protocol, TypeScript entry code, native source, harness consumption, an
 
 npm consumers install `@deepseek-ai/node-addon-landlock-run`; the old unscoped package names are not silently redirected. A supported Linux host downloads the scoped entry package and its matching architecture package; the other architecture package is skipped. An unsupported host receives no platform binary and follows the existing deterministic fail-closed probe path.
 
-The implementation touches more files than a dependency-line edit because the repository must also own workspace constraints, TypeScript build order, cleanup, CI triggers, release tags, lockfile generation, packed-install provenance, release documentation, and generated notices. The behavioral boundary stays narrow: it changes only the Landlock package family and its three direct workspace consumers, not the version or publication state of other DeepSeek Harness packages.
+The implementation touches more files than a dependency-line edit because the repository must also own workspace constraints, TypeScript build order, cleanup, CI triggers, release tags, lockfile generation, comparison of installed binaries with workspace builds, release documentation, and generated notices. The behavioral boundary stays narrow: it changes only the Landlock package family and its three direct workspace consumers, not the version or publication state of other DeepSeek Harness packages.
 
 The first scoped release must use an `@deepseek-ai` organization token through the `npm-publish` environment's `NPM_TOKEN`, because npm cannot configure trusted publishing until a package exists. After bootstrap, all three packages must authorize this repository's release workflow before the fallback token can be removed. npm still publishes packages sequentially and offers no cross-package transaction, so a failed publish can leave a partial version. Because npm rejects an already-published name and version, an operator must inspect the registry and publish only the missing tarballs rather than rerunning the workflow unchanged. Linux x64 and arm64 runners remain the authoritative binary and real-kernel checks; a macOS checkout can verify the entry package and unsupported-platform behavior but cannot replace those jobs.
 
diff --git a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
index ffebe45c53..eaa576f0b3 100644
--- a/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-in-repository-landlock-release.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `@deepseek-ai/node-addon-landlock-run` 源码已经与其 DeepSeek Harness 消费方一同位于 `native/landlock-run` 下，但此前仍保留独立的 pnpm workspace 和锁文件，并依赖一个独立仓库发布到 npm。Harness 包使用 npm 注册表中的固定版本，因此同一个 PR（Pull Request）可以同时修改启动器约定及其消费方，却无法一起测试这些改动。源码仓库的原生工作流可以演练打包流程，但不会发布它实际测试过的产物。
 
-发布镜像还造成重复的发布协调工作：导出源码、更新另一份锁文件、运行另一套发布工作流、发布原生包家族，然后回到本仓库更新注册表依赖。npm 用户的实际需求并未改变，这种拆分却增加了从源码到二进制的溯源、回滚和安全修复协调难度。
+发布镜像还造成重复的发布协调工作：导出源码、更新另一份锁文件、运行另一套发布工作流、发布原生包家族，然后回到本仓库更新注册表依赖。npm 用户的实际需求并未改变，这种拆分却让每个二进制更难对应到其源提交，也让发布回滚和安全修复协调更困难。
 
 现有的非 scoped npm 包名归独立发布账号所有，而不属于 `@deepseek-ai` 组织。因此，仅迁移工作流仍会让发布依赖仓库发布归属之外的个人凭证。
 
@@ -37,7 +37,7 @@ Status: implemented
 
 npm 消费方改为安装 `@deepseek-ai/node-addon-landlock-run`；原先的非 scoped 包名不会被静默重定向。受支持的 Linux 主机会下载 scoped 入口包及与其架构匹配的包，并跳过另一架构的包。不受支持的主机不会收到平台二进制文件，并继续沿用现有的确定性失败闭合探测路径。
 
-实现涉及的文件比只修改一行依赖更多，因为仓库还必须负责 workspace 约束、TypeScript 构建顺序、清理、CI 触发条件、发布 tag、锁文件生成、打包安装来源证明、发布文档和生成的第三方声明。行为边界仍然很窄：此次改动只影响 Landlock 包家族及其 3 个直接 workspace 消费方，不改变其他 DeepSeek Harness 包的版本或发布状态。
+实现涉及的文件比只修改一行依赖更多，因为仓库还必须负责 workspace 约束、TypeScript 构建顺序、清理、CI 触发条件、发布 tag、锁文件生成、将已安装二进制与 workspace 构建进行比较、发布文档和生成的第三方声明。行为边界仍然很窄：此次改动只影响 Landlock 包家族及其 3 个直接 workspace 消费方，不改变其他 DeepSeek Harness 包的版本或发布状态。
 
 第一次发布 scoped 包时，必须通过 `npm-publish` 环境的 `NPM_TOKEN` 使用 `@deepseek-ai` 组织 token，因为 npm 只有在包已经存在后才能配置 trusted publishing。完成 bootstrap 后，必须让 3 个包都授权本仓库的发布工作流，才能移除后备 token。npm 仍会按顺序发布各个包，且不提供跨包事务，因此发布失败可能留下只完成了一部分的版本。由于 npm 会拒绝已经发布的同名同版本包，操作人员必须检查注册表并只发布缺失的 tarball，而不能原样重新运行工作流。Linux x64 和 arm64 runner 仍提供权威的二进制构建与真实内核检查；macOS checkout 可以验证入口包和不受支持平台上的行为，但不能取代这些作业。
 
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
index 21006b51db..b1246cc82e 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.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 .agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
-2026-08-08-browser-gif-evidence-chain.md: 93dfad76b3c4d0934120a164ab22dd4b898e2e01
-2026-08-08-browser-gif-evidence-chain.zh.md: 8aafc842e55775bade8885a792ce7b92dfc8df4e
+2026-08-08-browser-gif-evidence-chain.md: b1ee54aa21949c50d69be3384a35547b752e6858
+2026-08-08-browser-gif-evidence-chain.zh.md: 43fa0139b198c91363ccf30327a62c0b894557a0
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
index 93dfad76b3..b1ee54aa21 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.md
@@ -8,15 +8,15 @@ English | [中文](2026-08-08-browser-gif-evidence-chain.zh.md)
 
 A browser-demo storyboard can contain individually truthful screenshots without proving one truthful execution. Reusing global application state can admit old settings or sessions, capture automation can accidentally combine frames from separate model runs, and a chat transcript can show a successful fallback without exposing the tool rejection that caused it. Fuzzy accessible-name matching can also accept prompt echoes or descendant text instead of the intended result.
 
-Headless production recording has two further boundaries. A product default may open a native operating-system surface that automation cannot drive, while replacing that surface with a mock or test hook would change the provenance. After publication, a successful git push does not prove that a private-repository GIF is fetchable or that GitHub recognizes the pull-request Markdown as an image.
+Headless production recording has two further boundaries. A product default may open a native operating-system surface that automation cannot drive, while replacing that surface with a mock or test hook would mean the GIF no longer shows the production path. After publication, a successful git push does not prove that a private-repository GIF is fetchable or that GitHub recognizes the pull-request Markdown as an image.
 
 ## Decision
 
-The [`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) workflow treats one storyboard as one evidence chain pinned to an exact pull-request head. Before building, it requires a clean worktree and records that commit SHA. Each run uses fresh `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, session, and isolated browser state, and every published frame comes from the same server and model-backed scenario run. When a fresh browser context is unavailable, the exact origin's cookies and site storage are cleared before navigation. Existing user browser state is used only when requested or required, is declared in the provenance, and does not substantiate fresh client state. A failed capture run is discarded and repeated from fresh roots rather than combined with another run.
+The [`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) workflow treats one storyboard as one evidence chain pinned to an exact pull-request head. Before building, it requires a clean worktree and records that commit SHA. Each run uses fresh `DSH_HOME`, `DSH_AGENTS_HOME`, workspace, session, and isolated browser state, and every published frame comes from the same server and model-backed scenario run. When a fresh browser context is unavailable, the exact origin's cookies and site storage are cleared before navigation. Existing user browser state is used only when requested or required, is stated next to the GIF, and does not substantiate fresh client state. A failed capture run is discarded and repeated from fresh roots rather than combined with another run.
 
 Browser automation waits for unique, exact semantic states. When the claim concerns a tool call, rejection, or recovery, the storyboard includes a detail or trajectory frame that identifies the tool, shows its status or stable error code, and shows the downstream result. The final encoded GIF remains the verification subject; when a viewer cannot animate it, representative frames are decoded from that GIF instead of treating source screenshots as equivalent evidence.
 
-The available browser-control workflow remains preferred. When it is unavailable, the recorder uses the repository-declared Playwright dependency in an isolated headless browser rather than installing another driver or opening the user's browser. A native production surface may be replaced only through normal application configuration with an official browser-operable production backend, and that override is stated in the provenance. Fixtures, mock transports, synthetic events, and test-only hooks do not substantiate a real-production claim.
+The available browser-control workflow remains preferred. When it is unavailable, the recorder uses the repository-declared Playwright dependency in an isolated headless browser rather than installing another driver or opening the user's browser. A native production surface may be replaced only through normal application configuration with an official browser-operable production backend, and that override is stated next to the GIF. Fixtures, mock transports, synthetic events, and test-only hooks do not substantiate a real-production claim.
 
 Publication verifies the boundary again. The assets branch contains media only, the staged and published bytes match the verified artifact, and a private-repository asset is checked through authenticated API or raw requests for its path, byte size, checksum, response status, and media type. This proves the repository-member review path only; the [documentation-site image decision](2026-08-06-doc-site-carries-its-images.md) owns why a public site cannot depend on a private raw URL. Immediately before the pull-request body changes, the live head must still equal the recorded head. After the edit, the live head is checked again and must remain at that recorded value; GitHub's Markdown renderer separately must produce the expected image.
 
@@ -34,4 +34,4 @@ Publication verifies the boundary again. The assets branch contains media only,
 
 GUI evidence now establishes one causal execution rather than a collage of plausible states, and reviewers can inspect both a structured tool failure and the completed result. Publication detects stale pull-request heads, corrupted or misplaced media, and invalid image Markdown before the body is treated as finished.
 
-The workflow spends additional scratch state, may repeat a real model round after a capture failure, and usually adds a detail frame plus authenticated publication checks. Headless recordings can use fewer production backends than an interactive desktop, and every such selection remains part of the stated provenance.
+The workflow spends additional scratch state, may repeat a real model round after a capture failure, and usually adds a detail frame plus authenticated publication checks. Headless recordings can use fewer production backends than an interactive desktop, and every selected backend is stated next to the GIF.
diff --git a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
index 8aafc842e5..43fa0139b1 100644
--- a/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-browser-gif-evidence-chain.zh.md
@@ -8,15 +8,15 @@ Status: implemented
 
 浏览器演示的分镜可以由每张都真实的截图组成，却无法证明这些截图来自同一次真实执行。复用应用全局状态可能引入旧设置或旧会话；录制自动化可能误将不同模型运行的画面合并；聊天 transcript（文本记录）可能显示降级处理成功，却没有揭示触发降级的工具拒绝。按无障碍名称进行模糊匹配，还可能误把提示词回显或后代文本当成预期结果。
 
-无头模式下的生产环境录制还有两道边界。产品默认配置可能打开自动化无法操控的原生操作系统界面，而用 mock 或测试钩子替换该界面会改变证据来源。发布之后，git 推送成功也不能证明私有仓库中的 GIF 可以获取，或 GitHub 能将 PR（Pull Request）的 Markdown 识别为图片。
+无头模式下的生产环境录制还有两道边界。产品默认配置可能打开自动化无法操控的原生操作系统界面，而用 mock 或测试钩子替换该界面，就意味着 GIF 不再展示生产路径。发布之后，git 推送成功也不能证明私有仓库中的 GIF 可以获取，或 GitHub 能将 PR（Pull Request）的 Markdown 识别为图片。
 
 ## 决策
 
-[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求工作树干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器 context 时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在证据来源中声明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
+[`record-browser-gif`](../../../skills/record-browser-gif/SKILL.md) 工作流将一套分镜视为一条证据链，并将其固定到精确的 PR head。构建之前，工作流要求工作树干净并记录其 commit SHA。每次运行都使用全新的 `DSH_HOME`、`DSH_AGENTS_HOME`、工作区、会话和隔离浏览器状态，所有发布帧均来自同一个服务器及同一次由模型驱动的场景执行。无法创建全新浏览器 context 时，应在导航之前清除该 origin 的 cookie 和站点存储。只有用户提出要求或确有必要时才能使用用户已有的浏览器状态；必须在 GIF 旁说明，并不得以此证明客户端状态全新。录制失败时，丢弃该次运行并从全新的状态根目录重新执行，不与另一次运行合并。
 
 浏览器自动化会等待唯一且精确的语义状态。如果需要证明工具调用、拒绝或恢复，分镜就必须包含详情帧或轨迹帧：标明工具、显示其状态或稳定错误码，并展示后续结果。最终编码出的 GIF 始终是验证对象；如果查看器无法播放动画，应从该 GIF 中解码出代表性帧，而不能将源截图视为等效证据。
 
-仍应优先使用已有的浏览器控制工作流。如果该工作流不可用，录制程序应在隔离的无头浏览器中使用仓库已声明的 Playwright 依赖，而不是安装其他驱动或打开用户的浏览器。只有通过正常应用配置选用官方且可由浏览器操作的生产后端，才能替换原生生产界面，并且必须在证据来源说明中注明这一覆盖。fixture（测试前置数据）、mock 传输层、合成事件和测试专用钩子均不能支撑真实生产实现的主张。
+仍应优先使用已有的浏览器控制工作流。如果该工作流不可用，录制程序应在隔离的无头浏览器中使用仓库已声明的 Playwright 依赖，而不是安装其他驱动或打开用户的浏览器。只有通过正常应用配置选用官方且可由浏览器操作的生产后端，才能替换原生生产界面，并且必须在 GIF 旁注明这一覆盖。fixture（测试前置数据）、mock 传输层、合成事件和测试专用钩子均不能支撑真实生产实现的主张。
 
 发布环节会再次验证边界。资产分支只包含媒体文件，暂存和发布的字节必须与已验证产物一致；对于私有仓库中的资产，应通过经身份验证的 API 或原始内容请求，检查其路径、字节大小、校验和、响应状态和媒体类型。这只能证明仓库成员的评审访问路径；[文档站点图片决策](2026-08-06-doc-site-carries-its-images.md)解释了公共站点为何不能依赖私有的原始内容 URL。修改 PR 正文之前，必须再次确认在线 head 仍与录制时的 head 相同。编辑后还要再次检查在线 head，且它必须保持为该记录值；GitHub 的 Markdown 渲染器则须单独生成预期图片。
 
@@ -34,4 +34,4 @@ Status: implemented
 
 GUI 证据现在能证明一次具有因果关系的执行，而不是将若干可信状态拼成集合；评审者既可以检查结构化的工具失败，也可以检查最终完成的结果。在 PR 正文被视为完成之前，发布验证可以发现陈旧的 PR head、损坏或位置错误的媒体文件，以及无效的图片 Markdown。
 
-该工作流会占用额外的临时状态；录制失败后，可能需要重新执行一次由真实模型驱动的场景；通常还会增加一张详情帧和经身份验证的发布检查。相比交互式桌面，无头录制可使用的生产后端更少；每次选择这类后端时，都必须将其写入证据来源说明。
+该工作流会占用额外的临时状态；录制失败后，可能需要重新执行一次由真实模型驱动的场景；通常还会增加一张详情帧和经身份验证的发布检查。相比交互式桌面，无头录制可使用的生产后端更少；每个选中的后端都会写在 GIF 旁。
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
index 2e33d34157..295dcfd0bf 100644
--- a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.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 .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
-2026-08-08-unified-github-label-taxonomy.md: fddda6c99053e55d3e31a2f6e5c55add09772117
-2026-08-08-unified-github-label-taxonomy.zh.md: 75333e3823d6e96ef41b1359a81d53f4bd872f87
+2026-08-08-unified-github-label-taxonomy.md: 44508b4f0e2dc4de97950b0738829c0b362cc506
+2026-08-08-unified-github-label-taxonomy.zh.md: b1e3629fd93dcbff6e253058b4c465dc9bb5fd63
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
index fddda6c990..44508b4f0e 100644
--- a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
@@ -45,7 +45,7 @@ The area set is intentionally extensible. When no existing description honestly
 
 ### Issues and migrations
 
-Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record Issue provenance and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
+Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record how an Issue was created and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
 
 Label migrations preserve meaning before removing aliases: add the canonical replacement, verify the labelable, then remove the obsolete assignment. A label is deleted only after no pull request or Issue still uses it, and unrelated labels are never replaced as a set.
 
@@ -69,4 +69,4 @@ Label migrations preserve meaning before removing aliases: add the canonical rep
 
 ## Consequences
 
-Reviewers and automation can query intent, semantic scope, provenance, priority, and operational triggers independently. Maintainers must read the change and the live label descriptions instead of inferring classification from title prefixes or paths. The live catalog, this rationale, and policy enforcement must move together when a kind or a non-obvious area boundary changes, and taxonomy migrations carry an explicit historical backfill and verification cost.
+Reviewers and automation can query intent, semantic scope, how an Issue was created, priority, and operational triggers independently. Maintainers must read the change and the live label descriptions instead of inferring classification from title prefixes or paths. The live catalog, this rationale, and policy enforcement must move together when a kind or a non-obvious area boundary changes, and taxonomy migrations carry an explicit historical backfill and verification cost.
diff --git a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
index 75333e3823..b1e3629fd9 100644
--- a/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.zh.md
@@ -45,7 +45,7 @@ Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对
 
 ### Issue 与迁移
 
-Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然可选。`source/*` 标签记录 Issue 来源，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
+Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然可选。`source/*` 标签记录 Issue 的创建方式，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
 
 迁移标签时，须先保留语义，再移除别名：先添加规范替代标签，核验可加标签对象，再移除废弃的标签关系。只有在所有 PR 和 Issue 都不再使用某个标签后才能将其删除，且绝不整组替换无关标签。
 
@@ -69,4 +69,4 @@ Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然
 
 ## 后果
 
-评审人和自动化流程可以分别查询意图、语义范围、来源、优先级和工作流触发条件。维护者必须阅读变更内容和现行标签说明，而不能根据标题前缀或路径推断分类。当某种类型或某条非显然的领域边界发生变化时，现行标签清单、本记录中的决策依据和政策执行必须同步更新；分类体系迁移还会产生明确的历史回填和验证成本。
+评审人和自动化流程可以分别查询意图、语义范围、Issue 的创建方式、优先级和工作流触发条件。维护者必须阅读变更内容和现行标签说明，而不能根据标题前缀或路径推断分类。当某种类型或某条非显然的领域边界发生变化时，现行标签清单、本记录中的决策依据和政策执行必须同步更新；分类体系迁移还会产生明确的历史回填和验证成本。
diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml
new file mode 100644
index 0000000000..b18d088e03
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.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/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
+2026-08-09-concrete-prose-names-actors-and-recorded-facts.md: efb6e9bcc6f1c817bb0be07ccd31bafc4b2ac3fb
+2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md: 41b0ce82631536c53ea45d60c1405a8387885d0f
diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
new file mode 100644
index 0000000000..efb6e9bcc6
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
@@ -0,0 +1,33 @@
+# Agent Note: Concrete prose names actors and recorded facts
+
+Status: implemented
+
+English | [中文](2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md)
+
+## Problem
+
+Repository prose used abstract category labels where readers needed different concrete facts. The same label could mean earlier event seqs cited by a replacement, the provider and model that produced a message, the caller that supplied context, the file that supplied a configuration row, or the CI job that built a binary. Readers had to inspect code before they could tell which fact the sentence promised.
+
+Replacing one broad label with another would preserve that ambiguity. Renaming types, fields, and protocol members during an editorial cleanup would instead change contracts that the wording problem did not require changing.
+
+## Decision
+
+Maintained prose names the exact actor, action, source, event, field, file, or process needed by the local contract. It states what was recorded and who or what recorded it. Writers apply a spoken-language check and replace words they would not use while explaining the same point to a colleague.
+
+The rule applies to Markdown, READMEs, active Agent Notes, JSDoc and comments, prompts, diagnostics, and user-visible strings. An audit judges each sentence separately; it does not replace a term across the repository with one preferred synonym. The edited sentence preserves actor, action, conditions, order, modality, exceptions, ownership, failure behavior, and consequences.
+
+Exact code identifiers, public APIs, durable fields, protocol members, type names, headings with external references, and filenames stay unchanged unless a coordinated contract rename is independently required. Surrounding prose explains their fields or behavior directly. Generated documents and catalogs update from their owning source.
+
+This decision complements the [documentation tiers and budgets](2026-07-04-doc-tiers-and-budgets.md) decision, which continues to own placement, document form, and word budgets.
+
+## Alternatives considered
+
+**Ban a fixed list of words.** Rejected because a word may be an exact identifier or the clearest term in another contract. Sentence-level review catches ambiguity without rejecting valid names.
+
+**Replace every abstract label with “source,” “origin,” or “metadata.”** Rejected because another broad label still leaves readers to infer whether the sentence means a file, caller, event seq, provider/model pair, commit, or build job.
+
+**Rename every matching identifier with the prose.** Rejected because editorial clarity does not justify unrelated API, protocol, durable-format, type, or file migrations. Those changes require their own consumer audit and decision.
+
+## Consequences
+
+Documentation and diagnostics may use a few more words, but each statement tells readers which value or process matters without requiring source inspection. Repository-wide prose audits require semantic classification and cannot use blind replacement. Bilingual counterparts preserve the same concrete fact, and generated copies are refreshed only after their owning source changes.
diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md
new file mode 100644
index 0000000000..41b0ce8263
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 具体表述说明执行者和记录的事实
+
+Status: implemented
+
+[English](2026-08-09-concrete-prose-names-actors-and-recorded-facts.md) | 中文
+
+## 问题
+
+仓库行文使用了抽象的类别名称，但读者需要知道的具体事实各不相同。同一个名称可能指替换操作引用的早期事件 seq、生成消息的提供方和模型、提供上下文的调用方、提供某行配置的文件，或构建某个二进制文件的 CI 任务。读者必须查看代码，才能知道句子承诺的是哪项事实。
+
+用另一个宽泛名称替换原名称，仍会保留这种歧义。在行文整理中重命名类型、字段和协议成员，反而会改变与行文问题无关的约定。
+
+## 决策
+
+仓库维护的行文直接写明当地约定需要的执行者、动作、来源、事件、字段、文件或进程。句子说明记录了什么，以及由谁或什么记录。写作者还要检查自己是否会在向同事解释同一个问题时使用这些词；如果不会，就替换它们。
+
+该规则适用于 Markdown、README、活跃 Agent Note、JSDoc 与注释、提示词、诊断信息和用户可见字符串。审查会分别判断每个句子，不会在整个仓库中用一个偏好的近义词统一替换某个术语。编辑后的句子保留执行者、动作、条件、顺序、情态、例外、归属、失败行为和后果。
+
+除非另一项独立需求明确要求协调重命名约定，否则确切的代码标识符、公开 API、持久字段、协议成员、类型名、带有外部引用的标题和文件名均保持不变。它们周围的行文直接说明其字段或行为。生成的文档和目录在维护它们的源文件修改后更新。
+
+该决策补充了[文档层级与字数预算](2026-07-04-doc-tiers-and-budgets.md)决策；后者继续规定内容位置、文档形式和字数预算。
+
+## 曾考虑的替代方案
+
+**禁止一份固定词表中的所有词。** 不予采纳：某个词可能是确切的标识符，也可能是另一项约定中最清楚的用词。逐句审查可以找出歧义，且不会拒绝有效名称。
+
+**将每个抽象名称都替换为“来源”、“起源”或“元数据”。** 不予采纳：另一个宽泛名称仍会让读者自行推测句子指的是文件、调用方、事件 seq、提供方／模型组合、commit 还是构建任务。
+
+**在修改行文时重命名所有匹配的标识符。** 不予采纳：让行文更清楚，不能作为进行无关 API、协议、持久格式、类型或文件迁移的理由。这些改动需要各自的消费方审查和决策。
+
+## 后果
+
+文档和诊断信息可能会多用几个词，但每条说明都会告诉读者哪个值或哪个执行过程有关，无需查看源码。全仓库行文审查必须根据句子的具体含义分类，不能盲目替换。双语对侧文件保留相同的具体事实，只有在维护这些副本的源文件更改后才会刷新它们。
diff --git a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
index 4edba8fd79..a47ee48e1f 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.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 .agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md
-2026-07-12-simplify-session-log-representation.md: a40f4013a97a9c940012dbb37d59beb2faf8fb22
-2026-07-12-simplify-session-log-representation.zh.md: c4393511e1a78edacf60bc54a764721ad50e4d9d
+2026-07-12-simplify-session-log-representation.md: 3efb531d3c0822d7444d1270eac4da2617c12447
+2026-07-12-simplify-session-log-representation.zh.md: 5e9b453fd9905bf858dc5cb0cc09bf5c558ea0e6
diff --git a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md
index a40f4013a9..3efb531d3c 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.md
@@ -12,7 +12,7 @@ The session log maintains two representations that cost more machinery than thei
 
 The request-header subsystem implements a custom system/tool delta codec and transmission-decision layer even though its contract says deltas are an encoding optimization, not a reconstructability requirement. Retaining the initial/resume full snapshot at each loop-instance boundary, then writing a canonical full `request/header` whenever that instance's assembled header changes, preserves replay while deleting `SystemDelta`, `ToolsDelta`, round-trip fallback, and the durable `request/header-delta` variant. Codec-only vocabulary disappears with the codec, not because its individual arms were invalid.
 
-The implementation retains append and replacement `sourceEventSeqs`, crash-repair provenance, and all `SessionStartSource` variants because those fields have an audit/interception role that zero current readers does not overturn.
+The implementation retains append and replacement `sourceEventSeqs`, the `tool/call` seq cited by crash-repaired results, and all `SessionStartSource` variants because those fields have an audit/interception role that zero current readers does not overturn.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
index c4393511e1..5e9b453fd9 100644
--- a/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-12-simplify-session-log-representation.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 请求头子系统实现了一套自定义的系统/工具增量编解码器和传输决策层，尽管其约定声明增量只是编码优化，而非可重建性要求。在每个 agent loop（智能体循环）实例边界保留初始/恢复的完整快照，然后在该实例的组装头发生变化时写入一条规范的完整 `request/header`，即可保留回放能力，同时删除 `SystemDelta`、`ToolsDelta`、往返回退逻辑以及持久化的 `request/header-delta` 变体。编解码器专属的词汇随编解码器一起消失，并非因为其各分支本身无效。
 
-实现保留追加与替换操作的 `sourceEventSeqs`、崩溃修复的溯源信息，以及所有 `SessionStartSource` 变体，因为这些字段承担审计/拦截职责，当前没有读取方并不能推翻这一点。
+实现保留追加与替换操作的 `sourceEventSeqs`、崩溃修复结果引用的 `tool/call` seq，以及所有 `SessionStartSource` 变体，因为这些字段承担审计/拦截职责，当前没有读取方并不能推翻这一点。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
index 91b9e6a0c0..a5b5587c90 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.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 .agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
-2026-08-03-omit-invariants-from-shipped-config.md: ff9a3b0ab2b4797ca4e96bea9e6b961b2e38501f
-2026-08-03-omit-invariants-from-shipped-config.zh.md: 526ce0756e69b36b6f54b46b23e1814322d6a1fd
+2026-08-03-omit-invariants-from-shipped-config.md: a691a0949806a752203a41bd6c66a50e97d8f1d7
+2026-08-03-omit-invariants-from-shipped-config.zh.md: cb2b04de6f4634e9107052c6855cba532b3030ba
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
index ff9a3b0ab2..a691a09498 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.md
@@ -12,7 +12,7 @@ English | [中文](2026-08-03-omit-invariants-from-shipped-config.zh.md)
 
 The shipped `dsh` configuration trees under `apps/cli/config/` mount neither `@deepseek-ai/dsh-invariants` nor any package-owned `./invariant` companion. The CLI package therefore carries no direct dependency on the invariant service.
 
-Invariant support remains available for focused tests, example bundles, generated SDK compositions, and custom deployments that opt into diagnostics explicitly. Session validation, snapshotting, freezing, and provenance remain always on and do not depend on the optional service, as defined by the [source-owned immutability decision](../architecture/2026-06-11-dev-invariants-over-deep-readonly.md).
+Invariant support remains available for focused tests, example bundles, generated SDK compositions, and custom deployments that opt into diagnostics explicitly. Session validation, snapshotting, freezing, and cited source-event validation remain always on and do not depend on the optional service, as defined by the [source-owned immutability decision](../architecture/2026-06-11-dev-invariants-over-deep-readonly.md).
 
 The built CLI config-dump test checks both shipped surfaces and rejects either the service entry or any `@deepseek-ai/dsh-*/invariant` entry.
 
diff --git a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
index 526ce0756e..cb2b04de6f 100644
--- a/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-03-omit-invariants-from-shipped-config.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 `apps/cli/config/` 下交付的 `dsh` 配置树既不挂载 `@deepseek-ai/dsh-invariants`，也不挂载任何包拥有的 `./invariant` 伴随插件。因此，CLI 包不再直接依赖不变式服务。
 
-不变式支持仍可供聚焦测试、示例组合包、生成的 SDK 组合，以及显式选择诊断的自定义部署使用。会话验证、快照、冻结和 provenance 始终启用，且不依赖可选服务，具体由[源端拥有的不可变性决策](../architecture/2026-06-11-dev-invariants-over-deep-readonly.md)规定。
+不变式支持仍可供聚焦测试、示例组合包、生成的 SDK 组合，以及显式选择诊断的自定义部署使用。会话验证、快照、冻结和来源事件引用验证始终启用，且不依赖可选服务，具体由[源端拥有的不可变性决策](../architecture/2026-06-11-dev-invariants-over-deep-readonly.md)规定。
 
 构建后 CLI 的配置转储测试会检查两个交付的 surface，并拒绝服务条目或任何 `@deepseek-ai/dsh-*/invariant` 条目。
 
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
index ad963d6e81..f8d4a07f6c 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.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 .agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
-2026-07-06-recallable-compaction.md: ed5491e642ea7ac99fd9f4ba071a61e655f968d3
-2026-07-06-recallable-compaction.zh.md: dabc606d0056e91f9ac473de6f166083bcee25e8
+2026-07-06-recallable-compaction.md: 6f7baedeaae0038b7f5106cd5fc4e23bdfbbd8dd
+2026-07-06-recallable-compaction.zh.md: cbf8b4a3843ca35647cc569255dfe9d26b45b988
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
index ed5491e642..6f7baedeaa 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-06-recallable-compaction.zh.md)
 
 ## Problem
 
-Compaction is a one-way door. The summary the model sees carries no reference to what it shadows — the `shadowedRange` provenance lives only on the log-only `compact/summary` event — and no tool lets the model read a shadowed span back. Whatever the summarizer drops is gone from the model's reachable world, even though the append-only log holds every byte. Repeated compaction compounds this: the head checkpoint is rewritten every pass, so the request prefix takes a full prompt-cache miss each time, and earlier summaries are re-summarized generation after generation.
+Compaction is irreversible from the model's current context. The summary the model sees carries no reference to what it shadows — `shadowedRange` lives only on the log-only `compact/summary` event — and no tool lets the model read a shadowed span back. Whatever the summarizer drops is unavailable to the model, even though the append-only log holds every byte. Repeated compaction compounds this: the head checkpoint is rewritten every pass, so the request prefix takes a full prompt-cache miss each time, and earlier summaries are re-summarized generation after generation.
 
 The root cause is one artifact playing two conflicting roles. An **index** wants to be frozen, chronological, and cheap; the model's **working memory** wants a global view, re-prioritization, and mutability. A single summary can be neither well.
 
@@ -22,7 +22,7 @@ Newly stale history splits into chunks by deterministic policy: accumulate towar
 
 - two or three lines of what happened;
 - a keyword line of low-frequency literal anchors — exact error strings, values, config keys — grouped by kind;
-- a code-composed footer: `[checkpoint c<summarySeq>: shadows conversation span #<start>–#<end>; originals retrievable via history_read]`. Pointers are assembled from provenance, never model-authored.
+- a code-composed footer: `[checkpoint c<summarySeq>: shadows conversation span #<start>–#<end>; originals retrievable via history_read]`. Code assembles these pointers from the `compact/summary` seq and `shadowedRange`; the model never writes them.
 
 A committed stub is never rewritten and never re-enters a later compaction region. A stub call's input is layered: the fixed preamble and the byte-identical pass-start state checkpoint (the shared prefix across all calls in the phase), then the keyword lines of all previously committed stubs — so a new entry indexes what is distinctive to its chunk instead of repeating the directory — the one or two most recent committed stubs for chronological continuity, and the slice itself. Sibling stubs from the same pass are not inputs (the concurrent phase forbids it; turn-aligned boundaries carry local continuity instead), and the state checkpoint is background only, never material to summarize into the stub. A slice consisting of recalled content is stubbed by code alone — a pointer line, no LLM call. A failed stub call degrades the same way: its slice gets a code-only pointer stub and the pass continues, making the state rewrite the only hard LLM dependency in a pass.
 
@@ -46,7 +46,7 @@ A new package `@deepseek-ai/dsh-tool-recall` (consumer-only, over the `dsh-sessi
 - `history_read(checkpoint, offset?)` — renders the shadowed span of any checkpoint in the log, including superseded ones, as `User:`/`Assistant:`/`Tool result:` transcript, paginated by a configured budget with a continuation cursor.
 - `history_search(query, checkpoint?, limit?)` — case-insensitive literal scan over every shadowed span; returns snippets with checkpoint ids and coverage metadata (`scanned`/`matched`/`truncated`). The zero-match hint notes the scan is literal and points at direct `history_read` of a plausible checkpoint.
 
-Both read `exec.agent.session.events` (the tool-todo access pattern; non-agent callers rejected), render only surface-type message events, and return ordinary `tool/result`s — recalled bytes land at the context tail, logged, so reconstructability holds with no special casing. There is no new storage and no sidecar index: the session log is the archive, `compact/summary` provenance is the index metadata, and the tools are a read path over both. The tool schemas and the package's one system-prompt section are static strings; checkpoint ids reach the model only through footers. The transcript renderer moves from `compact-basic` into `dsh-session`, shared by summarizer and tools.
+Both read `exec.agent.session.events` (the tool-todo access pattern; non-agent callers rejected), render only surface-type message events, and return ordinary `tool/result`s — recalled bytes land at the context tail, logged, so reconstructability holds with no special casing. There is no new storage and no sidecar index: the session log stores the content, `compact/summary.shadowedRange` and `shadowedSeqs` identify what each checkpoint replaced, and the tools read both. The tool schemas and the package's one system-prompt section are static strings; checkpoint ids reach the model only through footers. The transcript renderer moves from `compact-basic` into `dsh-session`, shared by summarizer and tools.
 
 ### Cache and cost
 
@@ -94,7 +94,7 @@ Specified during review, deferred until observation calls for them:
 ## Acceptance criteria
 
 - Auto-compaction over a long session yields `[stubs…][state][tail]` after every completed pass; prior stubs stay byte-identical across passes; committed stubs never fall inside a later region; the superseded state checkpoint folds without a tombstone, renders labeled, and stays reachable and searchable through the two-hop chain.
-- Every checkpoint's surface text ends with the deterministic footer; footers round-trip through replay byte-identically; the state checkpoint's provenance records its wider input range.
+- Every checkpoint's surface text ends with the deterministic footer; footers round-trip through replay byte-identically; the state checkpoint's `shadowedRange` records its wider input range.
 - Nothing commits before all summaries exist and the guard passes on like-for-like accounting; a guard failure commits nothing and does not fail the turn; a mid-commit kill resumed at the next pre-step completes the pass with the state region committed unconditionally, merge base read from the log; a legacy head checkpoint is adopted as state-class.
 - `history_read` renders any logged checkpoint's span under budget with a working cursor; `history_search` covers every shadowed span with checkpoint-id snippets and coverage metadata, asserted in particular by finding content that exists only in a span shadowed by a superseded state checkpoint — the regression pin for trailing-slice reachability; both reject non-agent callers and never-existing ids or orphaned `compact/start` with typed errors; recalled content appears as ordinary `tool/result`s; request-reconstruction invariants pass over sessions with compaction plus recall; one keyless snapshot scenario covers compact-then-recall end to end; tool schemas and the prompt section are byte-identical across passes.
 - On the long-horizon bench suite: task success does not regress against `compact-basic` at equal budgets; a handoff-fidelity probe (restate K known decisions and constraints after a pass) scores no worse; recall usage frequency and hit usefulness are reported per run via the dsh bench report pipeline, alongside the stub-directory attention measurement and cache-hit telemetry.
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
index dabc606d00..cbf8b4a384 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-压缩（compaction）是一扇单向门。模型看到的摘要没有指向被其遮蔽内容的引用，因为 `shadowedRange` 来源只存在于仅写入日志、模型不可见的 `compact/summary` 事件上，也没有工具能让模型重新读取被遮蔽的区段。即使仅追加日志仍保存每一个字节，摘要器丢弃的内容也会离开模型可触达的世界。重复压缩会进一步放大问题：每一轮都会重写头部检查点，因此请求前缀每次都会完全失去提示词缓存命中，而更早的摘要也会一代又一代地被重新摘要。
+压缩（compaction）对模型的当前上下文不可逆。模型看到的摘要没有指向被其遮蔽内容的引用，因为 `shadowedRange` 只存在于仅写入日志、模型不可见的 `compact/summary` 事件上，也没有工具能让模型重新读取被遮蔽的区段。即使仅追加日志仍保存每一个字节，摘要器丢弃的内容也对模型不可用。重复压缩会进一步加重这些结果：每一轮都会重写头部检查点，因此请求前缀每次都会完全失去提示词缓存命中，而更早的摘要也会在后续每一轮中重新生成摘要。
 
 根本原因是一个产物承担了两个互相冲突的角色。**索引** 需要冻结、按时间排序且成本低廉；模型的**工作记忆** 则需要全局视图、重新确定优先级并且可变。单一摘要无法同时胜任两者。
 
@@ -22,7 +22,7 @@ Status: proposed
 
 - 用两三行说明发生了什么；
 - 用一行关键词记录低频字面锚点，例如确切的错误字符串、值和配置键，并按类别分组；
-- 由代码组装页脚：`[checkpoint c<summarySeq>: shadows conversation span #<start>–#<end>; originals retrievable via history_read]`。指针根据来源组装，绝不由模型编写。
+- 由代码组装页脚：`[checkpoint c<summarySeq>: shadows conversation span #<start>–#<end>; originals retrievable via history_read]`。代码根据 `compact/summary` seq 和 `shadowedRange` 组装这些指针，模型绝不会编写它们。
 
 已经提交的存根永不重写，也绝不再次进入之后的压缩区域。存根调用采用分层输入：固定前导内容与逐字节相同的本轮开始状态检查点（该阶段所有调用共享的前缀）；随后是先前所有已提交存根的关键词行，使新条目索引其分片的独特内容，而不是重复整个目录；再加最近一两个已提交存根以维持时间连续性；最后是切片本身。同一轮中的同级存根不作为输入，因为并发阶段禁止这种依赖，而与轮次对齐的边界已经维持局部连续性。状态检查点只作为背景，绝不能成为存根需要总结的材料。完全由回溯内容构成的切片只通过代码生成存根，即只写一行指针，不调用 LLM（大语言模型）。存根调用失败时采用相同降级方式：其切片获得一个仅由代码生成的指针存根，本轮继续执行，使状态重写成为一轮中唯一的强制 LLM 依赖。
 
@@ -46,7 +46,7 @@ Status: proposed
 - `history_read(checkpoint, offset?)`：把日志中任意检查点（包括已被取代的检查点）遮蔽的区段渲染为 `User:`／`Assistant:`／`Tool result:` transcript（文本记录），并按配置预算分页，提供续传游标。
 - `history_search(query, checkpoint?, limit?)`：对每个被遮蔽区段进行不区分大小写的字面量扫描；返回带检查点 id 的片段与覆盖元数据（`scanned`／`matched`／`truncated`）。零匹配提示会说明扫描按字面量执行，并建议对可能的检查点直接使用 `history_read`。
 
-两个工具都读取 `exec.agent.session.events`（沿用 tool-todo 访问模式；拒绝非 agent（智能体）调用方），只渲染表面类型的消息事件，并返回普通 `tool/result`：回溯字节会进入上下文尾部并记录到日志，因此无需特殊处理即可满足可重建性。系统不增加新存储或伴随索引：会话日志是归档，`compact/summary` 来源是索引元数据，而这些工具是两者之上的读取路径。工具 schema 与该包唯一的系统提示词章节都是静态字符串；检查点 id 只会通过页脚抵达模型。transcript 渲染器从 `compact-basic` 移入 `dsh-session`，供摘要器与工具共享。
+两个工具都读取 `exec.agent.session.events`（沿用 tool-todo 访问模式；拒绝非 agent（智能体）调用方），只渲染表面类型的消息事件，并返回普通 `tool/result`：回溯字节会进入上下文尾部并记录到日志，因此无需特殊处理即可满足可重建性。系统不增加新存储或伴随索引：会话日志存储内容，`compact/summary.shadowedRange` 和 `shadowedSeqs` 指明每个检查点替换了什么，这些工具读取两者。工具 schema 与该包唯一的系统提示词章节都是静态字符串；检查点 id 只会通过页脚抵达模型。transcript 渲染器从 `compact-basic` 移入 `dsh-session`，供摘要器与工具共享。
 
 ### 缓存与成本
 
@@ -94,7 +94,7 @@ Status: proposed
 ## 验收标准
 
 - 长会话自动压缩后，每一轮完成时都会得到 `[stubs…][state][tail]`；先前存根在各轮之间保持逐字节相同；已提交存根绝不落入后续区域；被取代的状态检查点无需墓碑即可折入历史，渲染时带有标签，并可通过两跳链路触达和搜索。
-- 每个检查点的表面文本都以确定性页脚结束；页脚通过回放逐字节往返；状态检查点的来源记录其更宽的输入范围。
+- 每个检查点的表面文本都以确定性页脚结束；页脚通过回放逐字节往返；状态检查点的 `shadowedRange` 记录其更宽的输入范围。
 - 在全部摘要就绪且保护逻辑通过同类核算前，不提交任何内容；保护失败不会提交任何内容，也不会让轮次失败；提交中途被终止后，下一次 pre-step 会恢复处理，从日志读取合并基线，并无条件提交状态区域以完成本轮；旧版头部检查点会被视为状态类。
 - `history_read` 在预算内渲染任意已记录检查点的区段，并提供可用游标；`history_search` 覆盖每个被遮蔽区段，返回带检查点 id 的片段与覆盖元数据，测试尤其要能找到只存在于被已取代状态检查点遮蔽区段中的内容，这是锁定尾随切片可达性的回归用例；两个工具都会拒绝非 agent 调用方，并对从未存在的 id 或遗留 `compact/start` 返回类型化错误；回溯内容作为普通 `tool/result` 出现；请求重建不变量会在同时包含压缩与回溯的会话上通过；一项无密钥快照场景端到端覆盖先压缩再回溯；工具 schema 与提示词章节在各轮之间逐字节相同。
 - 在长时间跨度 bench 套件中：任务成功率在预算相同的条件下不低于 `compact-basic`；交接保真探针（在一轮后重新陈述 K 项已知决策和约束）的得分不降低；每次运行都通过 dsh bench 报告流水线汇报回溯使用频率和命中有效性，并同时报告存根目录注意力度量与缓存命中遥测。
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
index 6963b28121..af92c05200 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.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 .agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
-2026-07-08-interactive-side-sessions.md: dfd325babe215782c9c1cbec3fd9f874783af7ab
-2026-07-08-interactive-side-sessions.zh.md: a1441cfe12df933855c7b9fe08c5e09f9e6107d3
+2026-07-08-interactive-side-sessions.md: 228380ca2d3d7b2efeb37e713574e1863ce17f38
+2026-07-08-interactive-side-sessions.zh.md: f4e3bfdddff16fe687f2637b3626e7e1382eba61
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
index dfd325babe..228380ca2d 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-08-interactive-side-sessions.zh.md)
 
 ## Problem
 
-A user may want to explore a question from a live session without changing its main context. Existing primitives do not expose that product shape: [session-store fork](../../implemented/feature/2026-06-30-session-store-fork-api.md) creates an unattached session, while [fork subagents](../../implemented/feature/2026-06-21-subagent-capability-seam.md) are model-driven tasks whose transcript collapses into one tool result. Neither gives the user a separate conversation, and neither records a conclusion back into the parent with provenance.
+A user may want to explore a question from a live session without changing its main context. Existing primitives do not expose that product shape: [session-store fork](../../implemented/feature/2026-06-30-session-store-fork-api.md) creates an unattached session, while [fork subagents](../../implemented/feature/2026-06-21-subagent-capability-seam.md) are model-driven tasks whose transcript collapses into one tool result. Neither gives the user a separate conversation, and neither records a conclusion in the parent together with the side session that produced it.
 
 ## Proposal
 
@@ -23,7 +23,7 @@ Rewind productization, session-tree views, a model-facing side-session tool, and
 
 - **Use the subagent seam:** rejected because side sessions are user-driven, client-visible, and may outlive a parent turn; subagents are model-driven runs returning one tool result.
 - **Change the child system prompt:** rejected by default because any byte change invalidates the prefix cache from token zero. Deployments may still prefer that stronger separation.
-- **Add `sidechat/*` events:** deferred because a sourced `context/message` already provides durability, provenance, and replay. A dedicated event is justified only by a surface that needs distinct rendering.
+- **Add `sidechat/*` events:** deferred because a sourced `context/message` already records the content, producer, and replay input durably. A dedicated event is justified only by a surface that needs distinct rendering.
 - **Bind a protocol surface now:** rejected because current UIs are client-owned. Live presentation must eventually derive from the durable message so replay renders the same record.
 
 ## Acceptance criteria
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
index a1441cfe12..f4e3bfdddf 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-用户可能希望在不改变当前会话主上下文的前提下，探索一个来自活跃会话的问题。现有原语无法提供这种产品形态：[会话存储 fork](../../implemented/feature/2026-06-30-session-store-fork-api.md)创建的是一个无关联的会话，而 [fork subagent](../../implemented/feature/2026-06-21-subagent-capability-seam.md)是模型驱动的任务，其 transcript（文本记录）会折叠为一条工具结果。两者都不能给用户一个独立的对话，也都不能将结论带着出处信息记录回父会话。
+用户可能希望在不改变当前会话主上下文的前提下，探索一个来自活跃会话的问题。现有原语无法提供这种产品形态：[会话存储 fork](../../implemented/feature/2026-06-30-session-store-fork-api.md)创建的是一个无关联的会话，而 [fork subagent](../../implemented/feature/2026-06-21-subagent-capability-seam.md)是模型驱动的任务，其 transcript（文本记录）会折叠为一条工具结果。两者都不能给用户一个独立的对话，也都不能在父会话中同时记录结论和产生该结论的侧会话。
 
 ## 提案
 
@@ -23,7 +23,7 @@ Status: proposed
 
 - **使用 subagent seam：** 否决。侧会话是用户驱动的、客户端可见的，且可能存活超过父会话的一个轮次；subagent 是模型驱动的运行，返回一条工具结果。
 - **修改子会话的系统提示词：** 默认否决，因为任何字节变化都会从第零个 token 起使前缀缓存失效。部署方仍可选择这种更强的隔离方式。
-- **新增 `sidechat/*` 事件：** 延后。插件来源的 `context/message` 已提供持久性、出处与回放能力；只有当某个界面需要差异化渲染时，专用事件才有正当理由。
+- **新增 `sidechat/*` 事件：** 延后。已标注来源的 `context/message` 已经持久记录内容、生产方和回放输入；只有当某个界面需要差异化渲染时，专用事件才有正当理由。
 - **现在就绑定一个协议界面：** 否决。当前 UI 由客户端拥有。实时呈现最终必须从持久消息派生，以使回放渲染出相同的记录。
 
 ## 验收标准
diff --git a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml
index 5dd07029b3..cb2b5d41c9 100644
--- a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.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 .agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md
-2026-07-13-human-review-skill-maintenance.md: 76391bd110b7a86b194a9340ffcf7cc4602d1d2e
-2026-07-13-human-review-skill-maintenance.zh.md: 8ebff759cf29fa7773e4b883f83c231f88e153d2
+2026-07-13-human-review-skill-maintenance.md: b741c8b595fcd36613cb246af483863d1e056697
+2026-07-13-human-review-skill-maintenance.zh.md: 1c00577fdb08c30b1fff794c08da20ec38891de1
diff --git a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md
index 76391bd110..b741c8b595 100644
--- a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md
+++ b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md
@@ -10,13 +10,13 @@ The `dsh-code-review` skill records failure modes that require reviewer judgment
 
 ## Proposal
 
-Periodic out-of-repo maintenance. A private tool, kept on the skill maintainer's machine rather than committed to this repository, runs against a clean full-history checkout at refreshed `origin/master`. The intended scheduler runs daily with a two-UTC-day overlap; manual runs accept another `--since` duration or repeated `--pr` arguments for an explicit set. The scan is idempotent against the current skill and stores no repository cursor. The only repository file changed by promotion is [.agents/skills/dsh-code-review/SKILL.md](../../../skills/dsh-code-review/SKILL.md); the draft PR carries a provenance summary so reviewers can audit the source feedback and adoption evidence without the private adapter logs.
+Periodic out-of-repo maintenance. A private tool, kept on the skill maintainer's machine rather than committed to this repository, runs against a clean full-history checkout at refreshed `origin/master`. The intended scheduler runs daily with a two-UTC-day overlap; manual runs accept another `--since` duration or repeated `--pr` arguments for an explicit set. The scan is idempotent against the current skill and stores no repository cursor. The only repository file changed by promotion is [.agents/skills/dsh-code-review/SKILL.md](../../../skills/dsh-code-review/SKILL.md); the draft PR lists the source feedback URLs or IDs and adoption evidence without exposing the private adapter logs.
 
 ```mermaid
 flowchart TD
   A["Maintainer or scheduler runs the tool on origin/master"] --> B["List PRs merged in the overlap window"]
   B --> C["Collect pre-merge User feedback and final PR evidence"]
-  C --> D["Two reviewers verify provenance and adoption"]
+  C --> D["Two reviewers verify the author and adoption"]
   D --> E{"Both confirm human-authored and adopted?"}
   E -- "No" --> F["Exclude or retain as unresolved"]
   E -- "Yes" --> G["Two reviewers classify against the current skill"]
@@ -38,7 +38,7 @@ Each feedback item carries a stable source ID and bounded change evidence. When
 
 ### Dual-reviewer classification and drafting
 
-Two independently configured reviewer adapters classify every eligible item by provenance (`human-authored`, `forwarded-automation`, or `unclear`) and adoption (`adopted`, `rejected`, or `unclear`). Only matching `human-authored` plus `adopted` verdicts proceed. The adopted set then receives a second independent classification against the current skill: candidate, already covered, implementation-specific, or not feedback. A singleton may qualify; recurrence is not required. Disagreement receives one bounded re-evaluation and remains visible in run artifacts if unresolved. A single batch whose adapter output fails schema or id validation is failed closed at the batch level — every feedback item in it is marked unclear and routed to `excluded` — rather than aborting the whole run; the offending raw output is preserved under the run's private artifacts for debugging. If either adapter returns no valid result for any nonempty batch in an operation, the run exits non-zero and emits a failure record instead of reporting “no candidate.”
+Two independently configured reviewer adapters classify who authored every eligible item (`human-authored`, `forwarded-automation`, or `unclear`) and whether the change adopted it (`adopted`, `rejected`, or `unclear`). Only matching `human-authored` plus `adopted` verdicts proceed. The adopted set then receives a second independent classification against the current skill: candidate, already covered, implementation-specific, or not feedback. A singleton may qualify; recurrence is not required. Disagreement receives one bounded re-evaluation and remains visible in run artifacts if unresolved. A single batch whose adapter output fails schema or id validation is failed closed at the batch level — every feedback item in it is marked unclear and routed to `excluded` — rather than aborting the whole run; the offending raw output is preserved under the run's private artifacts for debugging. If either adapter returns no valid result for any nonempty batch in an operation, the run exits non-zero and emits a failure record instead of reporting “no candidate.”
 
 The primary adapter drafts from structured agreed guidance, never raw review text. It remains tool-free and read-only by adapter-author contract: it returns complete candidate file content, which the tool validates before writing the sole target. Both adapters then review the same complete skill diff; blocking findings return to a bounded revision loop, and both must approve the same revision. The tool rejects staged changes and edits outside the target skill both before running the documentation and lint gates and again before reporting success, so a gate or concurrent process that adds another path cannot slip through. It restores its own write on failure using best-effort compare-and-swap so a concurrent maintainer edit is not overwritten. On success it saves a candidate bundle containing the source `origin/master` commit, source skill blob ID, reviewed diff, complete candidate, source feedback IDs and URLs, landed evidence ranges, adapter verdicts, and gate results; it never commits, pushes, opens, or merges a PR.
 
@@ -48,21 +48,21 @@ Each private executable receives a byte-bounded, versioned JSON request on stdin
 
 ### Promotion contract
 
-The promote helper starts from a clean checkout at refreshed `origin/master` and refuses to apply a candidate when the current skill blob differs from the bundle's recorded source blob. The operator then reruns the maintenance analysis or manually rebases the diff and repeats the candidate review; the helper never replaces a newer `SKILL.md` with stale complete-file output. After applying a current candidate, it opens a draft PR whose body lists the source feedback URLs or IDs, the landed commit range used as adoption evidence, the originating run, gate results, and any operator edits. Raw adapter prompts and responses remain private, but repository reviewers receive enough provenance to judge whether each proposed rule follows from adopted human feedback.
+The promote helper starts from a clean checkout at refreshed `origin/master` and refuses to apply a candidate when the current skill blob differs from the bundle's recorded source blob. The operator then reruns the maintenance analysis or manually rebases the diff and repeats the candidate review; the helper never replaces a newer `SKILL.md` with stale complete-file output. After applying a current candidate, it opens a draft PR whose body lists the source feedback URLs or IDs, the landed commit range used as adoption evidence, the originating run, gate results, and any operator edits. Raw adapter prompts and responses remain private, but repository reviewers receive those concrete inputs so they can judge whether each proposed rule follows from adopted human feedback.
 
 ### Where the mechanism lives
 
-The tool source, adapter binaries, provider credentials, and intended daily scheduler are kept private to the maintainer's machine rather than committed to this repository. This document specifies the protocol; the reference implementation is private infrastructure. The mechanism serves a single skill maintained by a single operator, so the ongoing cost of vetting mechanism edits through repository review outweighs any provenance benefit. If the mechanism is ever handed off to a second maintainer, that handoff is a follow-up Agent Note that revises this decision — the operator doc at [docs/cookbook/maintaining-dsh-code-review.md](../../../../docs/cookbook/maintaining-dsh-code-review.md) is the entry point for anyone taking over.
+The tool source, adapter binaries, provider credentials, and intended daily scheduler are kept private to the maintainer's machine rather than committed to this repository. This document specifies the protocol; the reference implementation is private infrastructure. The mechanism serves a single skill maintained by a single operator, so the ongoing cost of vetting mechanism edits through repository review outweighs the benefit of committing the tool and its history. If the mechanism is ever handed off to a second maintainer, that handoff is a follow-up Agent Note that revises this decision — the operator doc at [docs/cookbook/maintaining-dsh-code-review.md](../../../../docs/cookbook/maintaining-dsh-code-review.md) is the entry point for anyone taking over.
 
 ## Alternatives considered
 
-- **Ship the tool inside this repository.** Rejected for a single-maintainer scope: repository maintenance overhead (typecheck, lint, coverage, cross-cutting refactors) would exceed the value of committed provenance. Retained option for a later handoff.
+- **Ship the tool inside this repository.** Rejected for a single-maintainer scope: repository maintenance overhead (typecheck, lint, coverage, cross-cutting refactors) would exceed the value of committed source and review history. Retained option for a later handoff.
 - **Record every feedback-time PR head** — rejected: it improves causal isolation but requires a continuously running observer, durable event state, retries, and force-push reconciliation. Periodic maintenance uses reviewed-commit evidence where available and fails closed on broader whole-PR evidence.
 - **Persist a processed-PR cursor** — rejected: an overlapping time-window scan is cheap and naturally idempotent against the current skill, while cursor state creates recovery and missed-event problems.
 - **Run on every new comment** — rejected: review waves produce many related comments and lack the final artifact needed to judge adoption.
 - **Treat merge or thread resolution as adoption** — rejected: a PR can merge with rejected, superseded, or intentionally unresolved feedback.
 - **Create or merge repository changes automatically** — rejected: the tool first needs a track record of useful periodic output. The maintainer inspects and promotes the local diff through normal repository review.
-- **Learn from bot findings that were fixed** — rejected: the source contract is human review feedback. Actor type is filtered before analysis, and human accounts forwarding automated findings are excluded by provenance review.
+- **Learn from bot findings that were fixed** — rejected: the source contract is human review feedback. Author type is filtered before analysis, and human accounts forwarding automated findings are excluded by the author check.
 - **Use one reviewer as author and final judge** — rejected: independent verdicts expose unsupported generalization before it reaches the skill.
 
 ## Acceptance criteria
@@ -73,7 +73,7 @@ Promotion from `proposed/` to `implemented/` requires all of the following to be
 - Both reviewer adapters are independently configured (distinct providers or models) and complete an analyze / adopt / review pass without user intervention. **Observed on 2026-07-15:** distinct primary/secondary adapters completed adoption + analysis in ~8 minutes; batch fail-closed handled one adapter id-hallucination without aborting the run.
 - A scheduler triggers the tool without an interactive terminal, and a candidate diff (or a "no candidate" record) reaches the operator through a durable notification channel.
 - A controlled acquisition case advances the target branch with a feedback-matching change after the feedback baseline; the reviewer evidence excludes that target-only change while retaining a later PR-owned change.
-- The promote helper rejects a candidate after the source skill changes, and a current candidate opens a draft PR with the provenance summary defined above.
+- The promote helper rejects a candidate after the source skill changes, and a current candidate opens a draft PR with the source feedback IDs, adopted commit range, originating run, checks, and operator edits defined above.
 - At least one candidate diff produced by this workflow is inspected by the operator and promoted to `master` through a normal repository PR review. That PR is the evidence that the workflow can turn adopted feedback into shipped skill guidance.
 
 ## Risks
diff --git a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
index 8ebff759cf..1c00577fdb 100644
--- a/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
+++ b/.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md
@@ -10,13 +10,13 @@ Status: proposed
 
 ## 提案
 
-在仓库外定期维护。一项保存在 skill 维护者机器上、而不提交到本仓库的私有工具，会针对刷新至 `origin/master` 的干净完整历史 checkout 运行。预期的调度器每天运行，并使用两天的 UTC 重叠窗口；手动运行可以通过另一个 `--since` 时长或重复的 `--pr` 参数指定显式集合。扫描相对于当前 skill 是幂等的，不存储仓库游标。推广时唯一会变更的仓库文件是 [.agents/skills/dsh-code-review/SKILL.md](../../../skills/dsh-code-review/SKILL.md)；draft PR（Pull Request）携带来源概述，因此评审人无需私有适配器日志，也能审计源反馈与采纳证据。
+在仓库外定期维护。一项保存在 skill 维护者机器上、而不提交到本仓库的私有工具，会针对刷新至 `origin/master` 的干净完整历史 checkout 运行。预期的调度器每天运行，并使用两天的 UTC 重叠窗口；手动运行可以通过另一个 `--since` 时长或重复的 `--pr` 参数指定显式集合。扫描相对于当前 skill 是幂等的，不存储仓库游标。推广时唯一会变更的仓库文件是 [.agents/skills/dsh-code-review/SKILL.md](../../../skills/dsh-code-review/SKILL.md)；draft PR（Pull Request）列出源反馈 URL 或 ID 和采纳证据，不会公开私有适配器日志。
 
 ```mermaid
 flowchart TD
   A["Maintainer or scheduler runs the tool on origin/master"] --> B["List PRs merged in the overlap window"]
   B --> C["Collect pre-merge User feedback and final PR evidence"]
-  C --> D["Two reviewers verify provenance and adoption"]
+  C --> D["Two reviewers verify the author and adoption"]
   D --> E{"Both confirm human-authored and adopted?"}
   E -- "No" --> F["Exclude or retain as unresolved"]
   E -- "Yes" --> G["Two reviewers classify against the current skill"]
@@ -38,7 +38,7 @@ flowchart TD
 
 ### 双评审人分类与起草
 
-两个独立配置的评审适配器，会从来源（`human-authored`、`forwarded-automation` 或 `unclear`）和采纳情况（`adopted`、`rejected` 或 `unclear`）两个维度，对每个符合条件的条目进行分类。只有两个适配器都判定为 `human-authored` 加 `adopted` 的条目才会继续。采纳集合随后会针对当前 skill 接受第二次独立分类：候选项、已经覆盖、实现专用或并非反馈。单个条目即可符合要求，不要求重复出现。意见分歧会得到一次有界的重新评估；如果仍未解决，则继续保留在运行产物中。单个批次的适配器输出如果未通过 schema 或 id 校验，系统会在批次层按不采纳处理：其中的每条反馈都标记为 unclear 并路由到 `excluded`，而不是中止整次运行；有问题的原始输出会保存在该次运行的私有产物中，供调试使用。如果任一适配器在某项操作的任何非空批次中都没有返回有效结果，运行会以非零状态退出并发出失败记录，而不会报告「没有候选项」。
+两个独立配置的评审适配器，会对每个符合条件的条目分类：谁编写了它（`human-authored`、`forwarded-automation` 或 `unclear`），以及变更是否采纳了它（`adopted`、`rejected` 或 `unclear`）。只有两个适配器都判定为 `human-authored` 加 `adopted` 的条目才会继续。采纳集合随后会针对当前 skill 接受第二次独立分类：候选项、已经覆盖、实现专用或并非反馈。单个条目即可符合要求，不要求重复出现。意见分歧会得到一次有界的重新评估；如果仍未解决，则继续保留在运行产物中。单个批次的适配器输出如果未通过 schema 或 id 校验，系统会在批次层按不采纳处理：其中的每条反馈都标记为 unclear 并路由到 `excluded`，而不是中止整次运行；有问题的原始输出会保存在该次运行的私有产物中，供调试使用。如果任一适配器在某项操作的任何非空批次中都没有返回有效结果，运行会以非零状态退出并发出失败记录，而不会报告「没有候选项」。
 
 主适配器只根据结构化的共同指引起草，绝不接收原始评审文本。根据适配器作者的约定，它保持无工具且只读：返回完整的候选文件内容，由工具校验后写入唯一目标。两个适配器随后评审同一份完整 skill diff；阻塞性问题会进入有界修订循环，而且两者必须批准同一版修订。工具会在运行文档和 lint 检查前，以及报告成功前，再次拒绝暂存改动和目标 skill 之外的编辑，因此检查或并发进程无法通过添加其他路径混入。失败时，工具使用尽力而为的比较并交换回滚自身写入，以免覆盖维护者的并发编辑。成功时，它保存一份候选资料包，其中包含源 `origin/master` commit、源 skill blob ID、已评审 diff、完整候选文件、源反馈 ID 与 URL、落地证据范围、适配器判定和检查结果；它绝不提交、推送、打开或合并 PR。
 
@@ -48,21 +48,21 @@ flowchart TD
 
 ### 推广约定
 
-推广辅助工具从刷新至 `origin/master` 的干净 checkout 开始；当前 skill blob 与资料包中记录的源 blob 不同时，它拒绝应用候选项。运维方随后重新运行维护分析，或手动把 diff 变基后重新评审候选项；辅助工具绝不会用陈旧的完整文件输出替换较新的 `SKILL.md`。应用仍然有效的候选项后，它会打开 draft PR，其正文列出源反馈 URL 或 ID、用作采纳证据的落地 commit 范围、来源运行、检查结果和任何运维方编辑。原始适配器提示词与响应保持私有，但仓库评审人会获得足够的来源信息，以判断每条提议规则是否确实来自已采纳的人类反馈。
+推广辅助工具从刷新至 `origin/master` 的干净 checkout 开始；当前 skill blob 与资料包中记录的源 blob 不同时，它拒绝应用候选项。运维方随后重新运行维护分析，或手动把 diff 变基后重新评审候选项；辅助工具绝不会用陈旧的完整文件输出替换较新的 `SKILL.md`。应用仍然有效的候选项后，它会打开 draft PR，其正文列出源反馈 URL 或 ID、用作采纳证据的落地 commit 范围、发起该候选项的运行、检查结果和任何运维方编辑。原始适配器提示词与响应保持私有，但仓库评审人会获得这些具体输入，从而判断每条提议规则是否确实来自已采纳的人类反馈。
 
 ### 机制所在位置
 
-工具源码、适配器二进制文件、提供方凭据和预期的每日调度器保存在维护者机器上，不会提交到本仓库。本文规定协议，参考实现属于私有基础设施。该机制只服务于由单个运维方维护的一项 skill，因此，持续通过仓库评审审查机制改动的成本高于来源可追溯性的收益。如果该机制将来移交给第二位维护者，移交工作需要一篇后续 Agent Note 来修订本决策；任何接手者都应从运维文档 [docs/cookbook/maintaining-dsh-code-review.md](../../../../docs/cookbook/maintaining-dsh-code-review.md) 入手。
+工具源码、适配器二进制文件、提供方凭据和预期的每日调度器保存在维护者机器上，不会提交到本仓库。本文规定协议，参考实现属于私有基础设施。该机制只服务于由单个运维方维护的一项 skill，因此，持续通过仓库评审审查机制改动的成本高于提交工具及其历史的收益。如果该机制将来移交给第二位维护者，移交工作需要一篇后续 Agent Note 来修订本决策；任何接手者都应从运维文档 [docs/cookbook/maintaining-dsh-code-review.md](../../../../docs/cookbook/maintaining-dsh-code-review.md) 入手。
 
 ## 考虑过的替代方案
 
-- **把工具放入本仓库。** 对单维护者作用域不予采纳：仓库维护开销（类型检查、lint、覆盖率与横切重构）会超过已提交来源信息的价值。未来移交时仍可重新考虑。
+- **把工具放入本仓库。** 对单维护者作用域不予采纳：仓库维护开销（类型检查、lint、覆盖率与横切重构）会超过已提交源码和评审历史的价值。未来移交时仍可重新考虑。
 - **记录每条反馈产生时的 PR head**：不予采纳，因为这需要持续运行的观察器、持久事件状态、重试和强制推送协调。定期维护会在可用时使用经过评审的 commit 证据，并在整 PR 证据范围过宽、无法确认时直接排除。
 - **持久化已处理 PR 游标**：不予采纳，因为带重叠的时间窗口扫描成本低廉，并且相对于当前 skill 天然幂等；游标状态反而带来恢复和漏事件问题。
 - **每次新评论都运行**：不予采纳，因为一轮评审会产生许多相关评论，并且缺少判断采纳情况所需的最终产物。
 - **把合并或讨论串解决视为采纳**：不予采纳，因为 PR 可能在反馈被拒绝、被取代或刻意不解决的情况下合并。
 - **自动创建或合并仓库改动**：不予采纳，因为工具首先需要通过有用的定期输出积累可信记录。维护者检查并通过普通仓库评审推广本地 diff。
-- **从已经修复的 bot 问题中学习**：不予采纳，因为来源约定限定为人类评审反馈。系统会在分析前按 actor 类型过滤，并通过来源评审排除转发自动化问题的人类账号。
+- **从已经修复的 bot 问题中学习**：不予采纳，因为来源约定限定为人类评审反馈。系统会在分析前按作者类型过滤，并通过作者检查排除转发自动化问题的人类账号。
 - **让同一个评审人既当作者又作最终裁决**：不予采纳，因为独立判定能在不受支持的概括进入 skill 之前暴露问题。
 
 ## 验收标准
@@ -73,7 +73,7 @@ flowchart TD
 - 两个评审适配器独立配置（不同的提供方或模型），无需用户干预即可完成 analyze／adopt／review 流程。**2026-07-15 已观察：** 不同的主／次适配器约用 8 分钟完成采纳与分析；一次适配器 id 幻觉由批次级保守失败机制处理，没有中止整次运行。
 - 调度器在没有交互式终端的情况下触发工具，并通过持久通知通道把候选 diff（或「没有候选项」记录）送达运维方。
 - 一个受控采集场景会在反馈基线之后，向目标分支加入与反馈匹配的变更；评审证据排除该目标分支专有变更，同时保留后续由 PR 自身加入的变更。
-- 源 skill 改变后，推广辅助工具会拒绝候选项；仍然有效的候选项会按照上文定义的来源概述打开 draft PR。
+- 源 skill 改变后，推广辅助工具会拒绝候选项；仍然有效的候选项会打开 draft PR，其中包含上文定义的源反馈 ID、已采纳 commit 范围、发起该候选项的运行、检查和运维方编辑。
 - 该工作流生成的至少一个候选 diff 会由运维方检查，并通过普通仓库 PR 评审推广到 `master`。该 PR 用以证明工作流能够把已采纳反馈转化为已交付的 skill 指引。
 
 ## 风险
diff --git a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml
index 7bea4132ff..07f441de52 100644
--- a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.i18n.yaml
+++ b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.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 .agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md
-2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md: 236139f9198f178d44cdf0867cbad2377a127359
-2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md: 650217e936aa65884e8fb4fed0358406c78e9931
+2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md: e995ec4e20f41cc4377131c0f6e8672e0588ccea
+2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md: e2e8869f2b6f89559a4cc1403ec530ed45d4aaab
diff --git a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md
index 236139f919..e995ec4e20 100644
--- a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md
+++ b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md
@@ -17,16 +17,16 @@ When the Windows sandbox phase is picked up, evaluate wrapping landstrip's Windo
 - **Probe synthesis.** landstrip has no `--probe`; the chain's functional-probe contract would have to be synthesized from a trap run.
 - **Dialect mapping.** Denial and runner-failure stderr dialects, and fail-closed exit-code classification, need explicit mapping into the chain's vocabulary.
 - **License.** The binaries are LGPL-2.1-or-later; distribution review is required before it enters the shipped closure.
-- **Provenance.** The in-house launcher's value is byte-pinned native-CI provenance over a ~300-line reviewable C file; landstrip is a single-maintainer Rust binary set. For the *existing Linux rung* that trade is already settled — do not swap it ([sandbox note](../../implemented/feature/2026-07-06-sandbox.md) and the launcher's own migration away from a Rust dependency). For a rung we have not built, weighing third-party maintenance against a second in-house native repo is a genuinely open question.
+- **Source and build record.** Each in-house launcher binary is byte-pinned to a native CI build of a ~300-line reviewable C file; landstrip is a single-maintainer Rust binary set. For the *existing Linux rung* that trade is already settled — do not swap it ([sandbox note](../../implemented/feature/2026-07-06-sandbox.md) and the launcher's own migration away from a Rust dependency). For a rung we have not built, weighing third-party maintenance against a second in-house native repo is a genuinely open question.
 
 ## Alternatives considered
 
-- **Build the in-house AppContainer launcher as planned.** Still the default if the evaluation fails on license, provenance, or probe fit; the cost is owning a second native security launcher repo indefinitely.
-- **Swap the Linux Landlock rung to landstrip too.** Rejected outright: sandbox correctness is a security invariant, the current launcher's reviewability and provenance chain were chosen deliberately, and it already migrated away from a Rust dependency for exactly this reason.
+- **Build the in-house AppContainer launcher as planned.** Still the default if the evaluation fails on license, source/build auditability, or probe fit; the cost is owning a second native security launcher repo indefinitely.
+- **Swap the Linux Landlock rung to landstrip too.** Rejected outright: sandbox correctness is a security invariant, the current launcher has reviewable C source and binaries byte-pinned to native CI builds, and it already migrated away from a Rust dependency for exactly this reason.
 
 ## Acceptance criteria
 
-- Before any Windows-rung implementation starts, an evaluation records the probe, dialect, license, and provenance answers, and the go/no-go is added to the sandbox note's deferred-phases plan.
+- Before any Windows-rung implementation starts, an evaluation records the probe, dialect, license, source repository, release process, and binary build answers, and the go/no-go is added to the sandbox note's deferred-phases plan.
 
 ## Risks
 
diff --git a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
index 650217e936..e2e8869f2b 100644
--- a/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
+++ b/.agents/notes/rejected/feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.zh.md
@@ -17,16 +17,16 @@ Status: rejected — landstrip 未经实战检验（驳回时问世仅数天，
 - **探测合成。** landstrip 没有 `--probe`；链所要求的功能探测约定必须从一次 trap 运行中合成出来。
 - **方言映射。** 拒绝与运行器失败两类 stderr 方言，以及失败关闭的退出码分类，都需要显式映射到链的词汇中。
 - **许可证。** 其二进制文件采用 LGPL-2.1-or-later 许可；在进入随产品发布的依赖闭包之前需要先做分发审查。
-- **溯源。** 自研启动器的价值在于一个约 300 行、可完整评审，并由原生 CI 逐字节锁定来源的 C 文件；而 landstrip 是单一维护者手中的一组 Rust 二进制文件。对*既有的 Linux 层级*而言，这笔权衡早有定论——不要替换它（见[沙箱 Agent Note](../../implemented/feature/2026-07-06-sandbox.md)以及该启动器自身移除 Rust 依赖的迁移记录）。而对一个我们尚未构建的层级，在第三方维护与第二个自研原生仓库之间如何取舍，是一个真正悬而未决的问题。
+- **源码与构建记录。** 每个自研启动器二进制都逐字节锁定到一个约 300 行、可完整评审的 C 文件的原生 CI 构建；而 landstrip 是单一维护者手中的一组 Rust 二进制文件。对*既有的 Linux 层级*而言，这笔权衡早有定论——不要替换它（见[沙箱 Agent Note](../../implemented/feature/2026-07-06-sandbox.md)以及该启动器自身移除 Rust 依赖的迁移记录）。而对一个我们尚未构建的层级，在第三方维护与第二个自研原生仓库之间如何取舍，是一个真正悬而未决的问题。
 
 ## 曾考虑的替代方案
 
-- **按原计划构建自研 AppContainer 启动器。** 若评估在许可证、溯源或探测契合度上不通过，这仍是默认选项；代价是要长期维护第二个原生安全启动器仓库。
-- **把 Linux Landlock 层级也换成 landstrip。** 直接否决：沙箱正确性是安全不变量，当前启动器的可审阅性与溯源链是刻意选择的结果，而且它正是出于这一原因才迁移摆脱了 Rust 依赖。
+- **按原计划构建自研 AppContainer 启动器。** 若评估在许可证、源码／构建可审计性或探测契合度上不通过，这仍是默认选项；代价是要长期维护第二个原生安全启动器仓库。
+- **把 Linux Landlock 层级也换成 landstrip。** 直接否决：沙箱正确性是安全不变量，当前启动器有可审阅的 C 源码，其二进制逐字节锁定到原生 CI 构建，而且它正是出于这一原因才迁移摆脱了 Rust 依赖。
 
 ## 验收标准
 
-- 在任何 Windows 层级实现开始之前，先有一份评估记录下探测、方言、许可证与溯源问题的答案，并把「采用／不采用」（go/no-go）结论加入沙箱 Agent Note 的延后阶段计划。
+- 在任何 Windows 层级实现开始之前，先有一份评估记录下探测、方言、许可证、源代码仓库、发布流程和二进制构建问题的答案，并把「采用／不采用」（go/no-go）结论加入沙箱 Agent Note 的延后阶段计划。
 
 ## 风险
 
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml
index 71171bbd04..2e98c0fdc7 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.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 .agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
-2026-07-19-fold-compaction-package-split.md: 47c9feb6bb0dd06fec0f002b7c1e930b288abe5e
-2026-07-19-fold-compaction-package-split.zh.md: ef2d1ee34783477f1b77f75d05b58d7679c6c4d4
+2026-07-19-fold-compaction-package-split.md: eeb0b5871ceacbbefc8bfa9f782b4bdd6735f20a
+2026-07-19-fold-compaction-package-split.zh.md: 1b7e456536254acd98944c601da12d97453803ba
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
index 47c9feb6bb..eeb0b5871c 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
@@ -29,7 +29,7 @@ Amend the implemented compaction decision and the [recallable-compaction proposa
 - `@deepseek-ai/dsh-compact-basic` and its workspace/package metadata are removed.
 - `@deepseek-ai/dsh-compact` owns the current configuration, plugin class, algorithm, types, events, and shared helpers.
 - Existing deployments can load the surviving package with equivalent configuration and model-visible behavior.
-- Automatic and manual compaction preserve cancellation, locking, token accounting, tool pairing, durable events, provenance, retry convergence, and transcript rendering.
+- Automatic and manual compaction preserve cancellation, locking, token accounting, tool pairing, durable events, cited source-event seqs, retry convergence, and transcript rendering.
 - Loader composition, unit, runaway-turn, cancellation, snapshot, and real-model compaction tests pass; generated catalogs and module graphs are current.
 
 ## Risks
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
index ef2d1ee347..1b7e456536 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
@@ -29,7 +29,7 @@ Status: rejected — 计划增加更多压缩后端，因此接口包与 basic 
 - 删除 `@deepseek-ai/dsh-compact-basic` 及其工作区和包元数据。
 - `@deepseek-ai/dsh-compact` 拥有当前配置、插件类、算法、类型、事件和共享辅助方法。
 - 现有部署可以使用等效配置加载保留的包，模型可见行为等效。
-- 自动压缩和手动压缩保留取消、锁、token 用量、工具配对、持久事件、来源、重试收敛和 transcript 渲染行为。
+- 自动压缩和手动压缩保留取消、锁、token 用量、工具配对、持久事件、引用的来源事件 seq、重试收敛和 transcript 渲染行为。
 - loader 组合、单元、失控轮次、取消、快照和真实模型压缩测试全部通过；生成目录与模块图保持最新。
 
 ## 风险
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
index af897a186b..ae1231acde 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.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 .agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
-2026-07-26-dependency-swaps-rejected-by-nih-audit.md: 538f6a41b4d2db72f867e98810e8e9382cbdac98
-2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: cc56dd44938cfe6d4c4b0aff1c714d80b8d8f5b6
+2026-07-26-dependency-swaps-rejected-by-nih-audit.md: c3422a9c8b4d60b4795aed5108923ac3446b0a46
+2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md: 9e21c89fcba0b05cfb5c00bef5261e834302bea1
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
index 538f6a41b4..c3422a9c8b 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md
@@ -67,7 +67,7 @@ Adopt the following dependency swaps. Rejected — per-item evidence below; a fu
 - **`syncpack`/`manypkg` for `check-workspace-constraints.ts`**: they cover ~20 lines of range alignment; the load-bearing 200+ lines (computed `files` lists, cordis peer=dev pairing, hierarchy shape) are repo policy no generic engine expresses.
 - **`remark-validate-links` for `verify-md-links.ts`**: the gate rides the repo's shared mdast toolchain; adopting remark-cli adds a second markdown stack to delete one small file.
 - **`prebuildify`/`node-gyp-build` for the landlock launcher packaging**: inapplicable — those load `.node` addons via dlopen; the launcher ships a standalone exec'd static binary, and per-platform `optionalDependencies` *is* the ecosystem convention for binaries.
-- **Replacing the Landlock launcher itself with `@landstrip/landstrip`**: fails the security-invariant test — the launcher is a ~300-line reviewable C file with byte-pinned provenance that already migrated away from a Rust dependency; a single-maintainer LGPL Rust binary set is a larger audit surface with weaker provenance. (The unbuilt Windows rung was weighed separately and also [rejected](../feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md) — landstrip is not battle-tested.)
+- **Replacing the Landlock launcher itself with `@landstrip/landstrip`**: fails the security-invariant test — the launcher is a ~300-line reviewable C file whose binaries are byte-pinned to native CI builds and that already migrated away from a Rust dependency; a single-maintainer LGPL Rust binary set is a larger audit surface whose releases are harder to match to reviewed source. (The unbuilt Windows rung was weighed separately and also [rejected](../feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md) — landstrip is not battle-tested.)
 - **`hatch-nodejs-version` for Python release versioning**: roughly LOC-neutral (a custom metadata hook replaces the regex), inverts the recorded decision that the dev sentinel never determines a release version, and puts a single-maintainer build plugin in the release supply chain.
 - **YAML consolidation (`js-yaml` vs `yaml`)**: the repo carries both parsers, with the `!!js` tag defined four times on js-yaml (vendored include, app-boot, apps/cli, `scripts/verify-cordis-config.ts`) and twice on `yaml` (sdk-telemetry's `ScalarTag`, sdk-helper's comment-preserving Document editing). The direction is forced — js-yaml cannot replace `yaml` (sdk-helper needs the Document API) — but migrating the js-yaml sites cannot retire the library either (the vendored include pins it) and would put two parsers in charge of one dialect that must agree exactly, against the [personal-config note](../../implemented/feature/2026-07-20-dsh-cli-personal-config.md)'s deliberate load-only-copy parity. Deletable: ~20–25 lines of duplicate tag definitions and two `@types/js-yaml` entries. The consolidation moment is a future include sync, not now.
 
diff --git a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
index cc56dd4493..9e21c89fcb 100644
--- a/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.zh.md
@@ -67,7 +67,7 @@ Status: rejected — 下列每一项替换在证据上都未达到净简化门
 - **以 `syncpack`/`manypkg` 替换 `check-workspace-constraints.ts`**：它们只覆盖约 20 行的版本范围对齐；承重的 200+ 行（计算生成的 `files` 列表、cordis peer=dev 配对、层级形状）是仓库政策，没有通用引擎能表达。
 - **以 `remark-validate-links` 替换 `verify-md-links.ts`**：该门禁搭载仓库共享的 mdast 工具链；采用 remark-cli 等于为删掉一个小文件而增加第二套 markdown 技术栈。
 - **以 `prebuildify`/`node-gyp-build` 承担 landlock 启动器打包**：不适用——那些工具通过 dlopen 加载 `.node` addon；这个启动器交付的是独立 exec 的静态二进制，而按平台划分的 `optionalDependencies` 恰恰*就是*二进制分发的生态惯例。
-- **以 `@landstrip/landstrip` 替换 Landlock 启动器本身**：未通过安全不变式检验——启动器是一个约 300 行、可完整评审、来源逐字节锁定的 C 文件，且早已从一个 Rust 依赖迁移出来；单一维护者的 LGPL Rust 二进制集合是更大的审计面加更弱的来源保障。（尚未构建的 Windows 层级经单独权衡后同样被[驳回](../feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md)——landstrip 未经实战检验。）
+- **以 `@landstrip/landstrip` 替换 Landlock 启动器本身**：未通过安全不变式检验——启动器是一个约 300 行、可完整评审的 C 文件，其二进制逐字节锁定到原生 CI 构建，且早已从一个 Rust 依赖迁移出来；单一维护者的 LGPL Rust 二进制集合有更大的审计面，其发布更难与已审阅源码对应。（尚未构建的 Windows 层级经单独权衡后同样被[驳回](../feature/2026-07-26-evaluate-landstrip-for-windows-sandbox-rung.md)——landstrip 未经实战检验。）
 - **以 `hatch-nodejs-version` 承担 Python 发布版本号**：代码行数大致持平（一个自定义 metadata 钩子换掉那个正则），却反转了「dev 哨兵值绝不决定发布版本」这条记录在案的决策，还把一个单一维护者的构建插件放进发布供应链。
 - **YAML 归一（`js-yaml` 与 `yaml`）**：仓库同时携带两个解析器，`!!js` 标签在 js-yaml 上定义了四次（vendor 收录的 include、app-boot、apps/cli、`scripts/verify-cordis-config.ts`），在 `yaml` 上定义了两次（sdk-telemetry 的 `ScalarTag`、sdk-helper 的保留注释式 Document 编辑）。方向是被迫的——js-yaml 无法取代 `yaml`（sdk-helper 需要 Document API）——但迁移 js-yaml 各调用点也退休不了这个库（vendor 收录的 include 锁定了它），还会让两个解析器共管一种必须完全一致的方言，违背[个人配置决策](../../implemented/feature/2026-07-20-dsh-cli-personal-config.md)刻意的「仅加载副本」对等性。可删除的：约 20–25 行重复标签定义和两条 `@types/js-yaml` 条目。归一的时机是未来某次 include 同步，不是现在。
 
diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md
index 90862b113e..e6d8c2658f 100644
--- a/.agents/skills/record-browser-gif/SKILL.md
+++ b/.agents/skills/record-browser-gif/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: record-browser-gif
-description: Record browser or Web UI interaction demos as optimized GIFs using the available built-in browser, state-based frame capture, and deterministic encoding, then publish to a dedicated assets branch when the task includes attaching the GIF to a pull request. Use when asked to make, record, or generate a GIF that demonstrates a browser workflow, and for every pull request that changes product-user-visible GUI behavior, which MUST include such a GIF with real provenance.
+description: Record browser or Web UI interaction demos as optimized GIFs using the available built-in browser, state-based frame capture, and deterministic encoding, then publish to a dedicated assets branch when the task includes attaching the GIF to a pull request. Use when asked to make, record, or generate a GIF that demonstrates a browser workflow, and for every pull request that changes product-user-visible GUI behavior, which MUST include a GIF recorded from the pull request's real server and model flow.
 ---
 
 # Record Browser GIF
@@ -13,13 +13,13 @@ The [evidence-chain decision](../../notes/implemented/process/2026-08-08-browser
 
 A pull request that changes product-user-visible GUI behavior MUST include a demonstration GIF recorded with this skill and embedded in the pull request body via [the assets-branch workflow](#publish-to-an-assets-branch).
 
-The GIF's provenance is part of the evidence and must be real: a real server booted from that pull request's own branch tree, a real API key, and real model rounds. Never substitute fixture queries, mock transports, synthetic event injection, or test-only hooks unless the user explicitly asked for fixture provenance. State the provenance next to the embed — the exact demonstrated commit SHA, which tree and origin served, which mode flags or browser-state exceptions applied, and that a real model round ran — so reviewers know exactly what the recording proves.
+The recording itself is part of the evidence: use a real server booted from that pull request's branch tree, a real API key, and real model rounds. Never substitute fixture queries, mock transports, synthetic event injection, or test-only hooks unless the user explicitly asked for a fixture recording. Next to the embed, state the exact demonstrated commit SHA, the tree and origin that served it, any mode flags or browser-state exceptions, and whether a real model round ran, so reviewers know exactly what the recording proves.
 
 ## Keep the boundary explicit
 
 - Recording produces frame images and one local `.gif` artifact only; it never mutates remote state.
 - Publication — pushing the GIF to an assets branch and embedding it in a pull request body — is the separate final step, performed only when the task includes attaching the GIF to a pull request. It never touches the pull request's own branch.
-- Preserve the requested provenance. A real-server or real-API demo must not use fixture queries, mock transports, synthetic event injection, or test-only hooks. If credentials or the server are unavailable, report that limitation instead of substituting a fixture.
+- Preserve the requested recording conditions. A real-server or real-API demo must not use fixture queries, mock transports, synthetic event injection, or test-only hooks. If credentials or the server are unavailable, report that limitation instead of substituting a fixture.
 - Never read or expose credential values. Use the application's normal configuration path and a benign demonstration prompt.
 
 ## Stage the application
@@ -33,9 +33,9 @@ A GIF for a specific pull request demonstrates that pull request's tree, so stag
 
 ## Record the flow
 
-1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. Use the user's existing Chrome state only when requested or required; state that exception in the provenance and do not claim fresh client state. If browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser; do not install another driver or launch the user's browser. State that fallback in the provenance.
+1. Invoke the available browser-control skill and follow its setup, interaction, and cleanup instructions. Use the user's existing Chrome state only when requested or required; state that exception next to the GIF and do not claim fresh client state. If browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser; do not install another driver or launch the user's browser. State that fallback next to the GIF.
 2. Resolve the evidence boundary before recording: identify the exact origin, whether the app is built or in development, the transport, and any fixture or mock mode. Record only claims that the observed setup supports.
-3. When a production default opens a native operating-system surface that headless automation cannot drive, select an official browser-operable production backend through the application's normal configuration. State the override in the provenance; a fixture, mock transport, or test-only hook is not an acceptable substitute.
+3. When a production default opens a native operating-system surface that headless automation cannot drive, select an official browser-operable production backend through the application's normal configuration. State that override next to the GIF; a fixture, mock transport, or test-only hook is not an acceptable substitute.
 4. Choose three to six states that tell one story, such as typed, running, settled, and detail. Prefer semantic state changes over continuous capture; omit loading churn that does not help the viewer.
 5. Keep one viewport and crop for every frame, and name frames lexically: `00-initial.png`, `01-typed.png`, and so on.
 6. Store frames under the repository's gitignored `.playwright-mcp/` directory — browser-tool screenshots can only be written under the tool's allowed roots, and relative filenames resolve against the repository root. Create the frame subdirectory first (`mkdir -p .playwright-mcp/gif-frames-<label>`); writing into a missing directory fails with ENOENT at capture time.
@@ -99,7 +99,7 @@ For a new series, make a fresh shallow scratch clone (`git clone --depth 1 <repo
 
 After pushing, use authenticated GitHub API or raw requests to confirm the remote path, byte size, checksum, `200` response, and `image/gif` content type. An anonymous `404` does not disprove a private-repository asset; authenticate the verification instead. This proves the repository-member review path, not public availability.
 
-Immediately before editing the pull-request body, re-read its live head and compare it with the commit recorded in the GIF provenance. Stop and re-record when it moved. After the edit, re-read the live head and require it to remain at that recorded commit. Separately, render the body through GitHub's Markdown API and confirm that the expected `<img>` is present.
+Immediately before editing the pull-request body, re-read its live head and compare it with the commit recorded next to the GIF. Stop and re-record when it moved. After the edit, re-read the live head and require it to remain at that recorded commit. Separately, render the body through GitHub's Markdown API and confirm that the expected `<img>` is present.
 
 Embed the GIF in the pull request body with the raw blob URL; the `?raw=true` suffix is required, because the plain blob URL renders GitHub's file page instead of the image:
 
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 9bfe494ba6..0a03868e2b 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
-README.md: 4f8aa86c0f6cdb91eb843048cd5ed4943a896c73
-README.zh.md: 09bc19220a869bedfcaa98baccbf6d4f6a3f3223
+README.md: bb3e1d77f00e03f6a21f4da3c04994f208e84293
+README.zh.md: 3802f940ef6663ec215cf09293a9edda5ea4c512
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index 4f8aa86c0f..bb3e1d77f0 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -21,7 +21,7 @@ dsh --profile web --dump-default-config
 dsh --profile web --patch ./extra.yml --dump-config
 ```
 
-`--dump-default-config` prints only the bundle layers; `--dump-config` adds the profile's `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and `--patch` overlays. Both print provenance comments per layer; `!!js` expressions remain unevaluated, and unmatched patch targets are reported on stderr.
+`--dump-default-config` prints only the bundle layers; `--dump-config` adds the profile's `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and `--patch` overlays. Both print comments naming the file that supplied each row and every overlay that changed it; `!!js` expressions remain unevaluated, and unmatched patch targets are reported on stderr.
 
 ## One-shot run
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index 09bc19220a..3802f940ef 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -21,7 +21,7 @@ dsh --profile web --dump-default-config
 dsh --profile web --patch ./extra.yml --dump-config
 ```
 
-`--dump-default-config` 只打印组合包各层；`--dump-config` 额外加上 profile 的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 和 `--patch` overlay。两者都会按层打印来源注释；`!!js` 表达式保持未求值，找不到目标的 patch 会报告到 stderr。
+`--dump-default-config` 只打印组合包各层；`--dump-config` 额外加上 profile 的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 和 `--patch` overlay。两者都会打印注释，标明每行由哪个文件提供，以及哪些 overlay 修改过它；`!!js` 表达式保持未求值，找不到目标的 patch 会报告到 stderr。
 
 ## 一次性运行
 
diff --git a/apps/cli/src/dump-config.ts b/apps/cli/src/dump-config.ts
index 9de7a55f60..1754eb4efd 100644
--- a/apps/cli/src/dump-config.ts
+++ b/apps/cli/src/dump-config.ts
@@ -1,7 +1,7 @@
 /**
  * Config-dump entry for `dsh --profile <name> --dump-config`: compose the
  * profile's patch layers through the include plugin's patch algorithm without
- * booting or evaluating `!!js`, with one provenance layer per bundle, the
+ * booting or evaluating `!!js`, with one source layer per bundle, the
  * profile's own patch file, and each `--patch` overlay.
  * @module @deepseek-ai/dsh/dump-config
  */
@@ -20,7 +20,7 @@ const NAME = 'dsh'
 
 /* v8 ignore start -- built-bin acceptance drives this boot-free dispatch */
 /**
- * Print a profile composition with provenance comments.
+ * Print a profile composition with comments naming each source file and patch layer.
  * @param profile - the profile name.
  * @param defaultOnly - omit the profile's user layer and `--patch` overlays
  * (the recovery diagnostic for a broken `cordis.patch.yml`, which is then
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index 073f541fe0..de44b110a1 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -518,7 +518,7 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       expect(code).toBe(0)
       expect(stdout).toContain('provider: configured-provider')
       expect(stdout).not.toContain('personal-provider')
-      // Both layers patched the row; provenance lists them in application order.
+      // Both layers patched the row; the comment lists them in application order.
       expect(stdout).toContain(`patched by ${profilePatch}, ${overlay}`)
       expect(stderr).toContain('patch: entry "absent-row" not found')
     }, 30_000)
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index fac240fbe1..072a322fb6 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -83,7 +83,7 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
   /**
    * Append one event at the next seq/time.
    * @param event - the event body, without seq/time.
-   * @returns the seq it took, so provenance cites the push instead of arithmetic over the push order below.
+   * @returns the assigned seq, so later `sourceEventSeqs` cite the pushed event directly.
    */
   const at = (event: Record<string, unknown>): number => {
     const taken = seq++
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 672f6ba6f6..22a8ba53d7 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -42,7 +42,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 - **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
-- Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams".
+- Write for professional programmers. Use concise, direct English without metaphor. Name the actor, source, event, field, or process; use words you would say to a colleague ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Do not overuse "gate", "vocabulary", "surface", or "seam".
 
 ## Wordcount Budgets
 
diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md
index 8690c792be..7e3939b7fd 100644
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -71,7 +71,7 @@ sequenceDiagram
   Driver-->>SDK: <code>agent/status</code> idle
 ```
 
-The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.
+The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history, while the durable event keeps usage and `sourceEventSeqs` listing the exact `assistant/chunk` events, including an explicit empty list.
 
 `dsh-compact-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.
 
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 3b279ef25a..33c39a89b4 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: ed33fb215c3b4fd830bef219da74f4ee98dec81d
-architecture.zh.md: 19d2500142449c63d725f89a651b22205af6b301
+architecture.md: 5e009d8345112bb0adcb2f55b4e49bbbf3bf8d00
+architecture.zh.md: c99336a03cd32fc4fb44b06c40ddd08a36b6a378
diff --git a/docs/architecture.md b/docs/architecture.md
index ed33fb215c..5e009d8345 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -92,7 +92,7 @@ forever:
       'step/start'
       append the returned batch as separate 'user/message' events
       assemble ordered prompt and tool schemas -> snapshot derived messages
-      agent/request (config only) -> prepare adapter defaults/provenance + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
+      agent/request (config only) -> resolve adapter defaults and mark defaulted fields + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
       'assistant/chunk'
       'assistant/message'
       schedule tool calls by ctx.tools.executionMode:
@@ -144,13 +144,13 @@ The session log is authoritative. `deriveMessages()` projects model history; raw
 
 Durability is a plugin concern. Backends copy synchronous `session/event` notifications into fixed-window durable batches; `session/flush` bypasses the wait before requests and top-level tool dispatch, and after `turn/end` before another turn or idle. `SessionPersistence` stores events and header metadata; JSONL defaults to checksummed Zstandard and SQLite shares the contract ([checkpoint decision](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md), [batching decision](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
 
-Between turns, owners append log-only events through `Session`, flushing only for durability. `session/title` relies on bounded background persistence and lifecycle drains; manual compaction flushes its bracket before the operation completes. Title work never delays responses; latest wins with provenance. Title records are inherited fork boundaries ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)).
+Between turns, owners append log-only events through `Session`, flushing only for durability. `session/title` relies on bounded background persistence and lifecycle drains; manual compaction flushes its bracket before the operation completes. Title work never delays responses; the latest title event wins, and it records the source message seqs and whether the user, fallback, or provider supplied it. Title records are inherited fork boundaries ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)).
 
 ### Model Content
 
 Messages use typed blocks from merge-extensible `ContentBlockMap`; the pattern also types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New blocks coordinate adapters, UI, compaction, token metering, and persistence; replay measurements live in [token-meter.md](subsystems/token-meter.md).
 
-Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, successful provenance, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract](subsystems/llm-streaming.md)).
+Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, the successful provider/model route, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract](subsystems/llm-streaming.md)).
 
 ## Extension And Composition
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 19d2500142..c99336a03c 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -92,7 +92,7 @@ forever:
       'step/start'
       append the returned batch as separate 'user/message' events
       assemble ordered prompt and tool schemas -> snapshot derived messages
-      agent/request (config only) -> prepare adapter defaults/provenance + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
+      agent/request (config only) -> resolve adapter defaults and mark defaulted fields + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
       'assistant/chunk'
       'assistant/message'
       schedule tool calls by ctx.tools.executionMode:
@@ -144,13 +144,13 @@ idle inject:
 
 持久性由插件负责。后端会将同步的 `session/event` 通知复制到固定窗口的持久化批次中；`session/flush` 会绕过等待，在请求与顶层工具分发之前执行，并在 `turn/end` 之后、另一个轮次或空闲状态之前执行。`SessionPersistence` 存储事件和 header 元数据；JSONL 默认采用带校验和的 Zstandard，SQLite 遵循同一约定（[检查点决策](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md)、[批处理决策](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
 
-在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新标题按后写覆盖并携带来源信息。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
+在轮次之间，事件所有方通过 `Session` 追加纯日志事件，仅为持久性而刷写。`session/title` 依赖有界后台持久化与生命周期排空；手动压缩会在操作完成前 flush 其标记对。标题工作绝不延迟响应；最新的标题事件生效，并记录来源消息 seq，以及标题由用户、后备逻辑还是提供方提供。标题记录是可继承的 fork 边界（[决策](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)）。
 
 ### 模型内容
 
 消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](subsystems/token-meter.md)。
 
-流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[约定](subsystems/llm-streaming.md)）。
+流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功使用的提供方／模型路由和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[约定](subsystems/llm-streaming.md)）。
 
 ## 扩展与组合
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 6219a0080f..4c49120f17 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1197,7 +1197,7 @@ export interface Config {
    * non-empty override asserts full enforcement and skips built-in selection and
    * probing. A runner that starts but refuses its profile must be identifiable by
    * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
-   * attributable `ENOENT` or `EACCES` with runner argv[0] provenance becomes an
+   * attributable `ENOENT` or `EACCES` whose error path equals runner argv[0] becomes an
    * infrastructure failure.
    */
   runnerCommand?: string[]
diff --git a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml b/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
index cb578de462..fde0ddda14 100644
--- a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
+++ b/docs/cookbook/maintaining-dsh-code-review.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 docs/cookbook/maintaining-dsh-code-review.md
-maintaining-dsh-code-review.md: 2b5d0d926ae922f2650daac33cf35991cb71c5e5
-maintaining-dsh-code-review.zh.md: 4466565b294ede89fa34da9e76b88f4ac39748eb
+maintaining-dsh-code-review.md: 8aa8a5792bff2c49041f2f8b5e8146e7cff14e0e
+maintaining-dsh-code-review.zh.md: b26c98e8679eece78e72ee684580c1ed1181aa7c
diff --git a/docs/cookbook/maintaining-dsh-code-review.md b/docs/cookbook/maintaining-dsh-code-review.md
index 2b5d0d926a..8aa8a5792b 100644
--- a/docs/cookbook/maintaining-dsh-code-review.md
+++ b/docs/cookbook/maintaining-dsh-code-review.md
@@ -10,7 +10,7 @@ Run the private tool daily with a two-UTC-day overlap; until the proposed schedu
 
 1. It selects PRs merged in the chosen window (default two UTC days for the daily cadence, seven for weekly) whose merge commit is reachable from `origin/master`. PRs whose merge commit is not reachable (stacked branches whose parent was squashed) or that exceed a 250-commit acquisition cap are logged to `skipped-pulls.json` and skipped rather than aborting the run.
 2. It collects pre-merge human review feedback with commit anchors (inline comments and review submissions), then compares feedback-time and final landed PR patches. It does not acquire PR conversation comments because current GitHub state cannot give them a force-push-safe feedback-time baseline, and it excludes target-branch-only changes from adoption evidence.
-3. Two independently configured reviewer adapters classify provenance and adoption, then classify agreed-adopted items against the current skill.
+3. Two independently configured reviewer adapters classify who wrote each item and whether the change adopted it, then classify agreed-adopted items against the current skill.
 4. The primary adapter drafts a complete revised `SKILL.md`; both adapters review the same diff; blocking findings loop until both approve.
 5. `pnpm run doc-sync` and `pnpm run lint` run against the candidate before the tool declares success.
 
@@ -38,7 +38,7 @@ When a run produces a candidate, a macOS notification arrives with a `dsh-code-r
      rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md,manifest.json}
      ```
    - **Batch.** Keep the candidate aside if the update is small and could combine with a future one. The source-skill check still applies; rerun the analysis or manually rebase and re-review the diff if `master` changes first.
-   - **Promote.** From a clean `master` checkout of the repo, run the promote helper. It refreshes `master`, verifies that the current skill matches the recorded source blob, applies the saved diff, and opens a draft PR whose body carries the manifest's provenance summary. It stops on skill drift rather than overwriting newer guidance; the operator still reviews the PR on GitHub and either merges it or closes it.
+   - **Promote.** From a clean `master` checkout of the repo, run the promote helper. It refreshes `master`, verifies that the current skill matches the recorded source blob, applies the saved diff, and opens a draft PR whose body lists the source feedback URLs or IDs, landed commit range, originating run, checks, and operator edits. It stops on skill drift rather than overwriting newer guidance; the operator still reviews the PR on GitHub and either merges it or closes it.
 
      ```sh
      cd ~/path/to/deepseek-harness   # clean master
diff --git a/docs/cookbook/maintaining-dsh-code-review.zh.md b/docs/cookbook/maintaining-dsh-code-review.zh.md
index 4466565b29..b26c98e867 100644
--- a/docs/cookbook/maintaining-dsh-code-review.zh.md
+++ b/docs/cookbook/maintaining-dsh-code-review.zh.md
@@ -10,7 +10,7 @@
 
 1. 选择指定窗口内合并、且合并 commit 可从 `origin/master` 到达的 PR（每天运行默认选择 2 个 UTC 日，每周运行选择 7 日）。合并 commit 无法到达的 PR（例如父分支被 squash 的堆叠分支），或超出 250 个 commit 获取上限的 PR，会记录到 `skipped-pulls.json` 并跳过，不会中止本次运行。
 2. 收集合并前带 commit 锚点的人工评审反馈（行内评论和评审提交），然后比较反馈时与最终落地的 PR patch。它不获取 PR 会话评论，因为 GitHub 当前状态无法为这些评论提供可抵抗 force-push 的反馈时基线；它也不会把只存在于目标分支的变更作为采纳证据。
-3. 两个独立配置的评审适配器先对来源和采纳情况分类，再根据当前 skill 对双方一致认定已采纳的条目分类。
+3. 两个独立配置的评审适配器先对每个条目的作者以及更改是否采纳了它进行分类，再根据当前 skill 对双方一致认定已采纳的条目分类。
 4. 主适配器起草完整修订版 `SKILL.md`；两个适配器评审同一份 diff；只要仍有阻塞性问题，循环就会继续，直到双方批准。
 5. 工具声明成功前，会针对候选版本运行 `pnpm run doc-sync` 和 `pnpm run lint`。
 
@@ -38,7 +38,7 @@
      rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md,manifest.json}
      ```
    - **留待成批处理。** 如果更新很小，可以把候选版本留待与后续版本合并。源 skill 检查仍然适用；如果 `master` 先发生变化，请重新运行分析，或手动 rebase 并重新评审 diff。
-   - **提升。** 在仓库的干净 `master` checkout 中运行提升辅助工具。它会刷新 `master`、验证当前 skill 与记录的源 blob 一致、应用保存的 diff，并创建一份 draft PR，其正文包含 manifest 的来源摘要。如果 skill 已发生漂移，它会停止而不是覆盖更新后的指导；操作员仍需在 GitHub 上评审 PR，并选择合并或关闭。
+   - **提升。** 在仓库的干净 `master` checkout 中运行提升辅助工具。它会刷新 `master`、验证当前 skill 与记录的源 blob 一致、应用保存的 diff，并创建一份 draft PR，其正文列出原始反馈的 URL 或 ID、已落地的 commit 范围、发起这次更改的运行、检查以及操作员编辑。如果 skill 已发生漂移，它会停止而不是覆盖更新后的指导；操作员仍需在 GitHub 上评审 PR，并选择合并或关闭。
 
      ```sh
      cd ~/path/to/deepseek-harness   # clean master
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 04c3a492fe..975a882706 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -64,11 +64,11 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     data: SessionEventMap[K]
   } & (K extends SurfaceEventType ? {
     /**
-     * Seq numbers of events that are provenance sources of this event
+     * Seq numbers of earlier events that this event cites as sources
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
+     * provider stream; omission means the source stream was not recorded.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -286,7 +286,7 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
 
 ```ts persistence-catalog
 /**
- * Provenance record of a completed summarization — log-only, no surfaceOp.
+ * Completed summary, its inputs, and its model call facts — log-only, no surfaceOp.
  * The summary content is in `data.summary`; the actual surface replacement
  * is performed by the immediately following `user/message` event that
  * shadows the compacted range. That adjacency is contractual — the
@@ -365,7 +365,7 @@ Source: [`packages/goal/goal/src/domain.ts:66`](../packages/goal/goal/src/domain
 
 ```ts persistence-catalog
 /**
- * A hook command was invoked at a hook point — log-only provenance (like
+ * A hook command was invoked at a hook point — a log-only record (like
  * `compact/*`; NOT a {@link SurfaceEventType}, carries no `surfaceOp`).
  * `dialect` is the bridge that ran it (`claude`/`codex`), `point`
  * the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index b741c1cdf8..313b07ed56 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/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 docs/subsystems/README.md
-README.md: 1c3d14aeb4fd11cbc45eaadd83f0b84de0dfda52
-README.zh.md: 04e07cc9c8b8b16c69bb09344e8533729525fe5c
+README.md: 94e935998e39d4209476a8c62eb99fed0e0ce317
+README.zh.md: 0f4a4c65797cf75acc6f937e8e8beb5fcd641652
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
index 1c3d14aeb4..94e935998e 100644
--- a/docs/subsystems/README.md
+++ b/docs/subsystems/README.md
@@ -18,7 +18,7 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits |
 | [credentials.md](credentials.md) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo`, provider source layers |
 | [session-query.md](session-query.md) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages |
-| [session-title.md](session-title.md) | durable title snapshots, source provenance, and the asynchronous provider contract |
+| [session-title.md](session-title.md) | durable title snapshots, cited source-message seqs, and the asynchronous provider contract |
 | [session-reference.md](session-reference.md) | structured cross-session references: `SessionReferenceInput`/`Candidate`, prepared message contexts, the stable error taxonomy |
 | [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
 | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index 04e07cc9c8..0f4a4c6579 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -18,7 +18,7 @@
 | [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
 | [credentials.md](credentials.md) | 凭据 seam：配置中的 `CredentialRef` 引用（绝不含值）、按操作解析、对 UI 安全的 `CredentialInfo`、provider 来源层 |
 | [session-query.md](session-query.md) | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
-| [session-title.md](session-title.md) | 持久标题快照、来源 provenance 与异步提供方约定 |
+| [session-title.md](session-title.md) | 持久标题快照、被引用的来源消息 seq 与异步提供方约定 |
 | [session-reference.md](session-reference.md) | 结构化跨会话引用：`SessionReferenceInput`/`Candidate`、prepared 消息上下文、稳定错误分类 |
 | [system-prompt.md](system-prompt.md) | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
 | [tools.md](tools.md) | `ToolDefinition` 完整字段、schema DSL、`ToolExecution`/`ToolResult`、工具展示 UI 类型，以及受保护的执行流水线 |
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index ed13dea399..425f48409a 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 5aef839192ea6f67bb409622187fe65fed795e73
-compaction.zh.md: 20b4b2381f6e638e1d1b4db13ba98d53379b38db
+compaction.md: 058fdba7969ac1f5b337b7ff008b0e62cf9ed035
+compaction.zh.md: b4108ed5de55e027d633a180db968c7cd7ffee59
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 5aef839192..058fdba796 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -8,15 +8,15 @@ Source: [`packages/compact/compact/src/types.ts`](../../packages/compact/compact
 
 ## The `compact/*` session events
 
-Compaction extends [`SessionEventMap`](session.md) with three event types via declaration merging. All three are **log-only** — they record the compaction lock and its provenance, and never join the surface. `SurfaceEventType` is deliberately NOT extended (only message-producing events reach the model), so the summary itself rides on a separate `user/message` with `surfaceOp: { op: 'replace', start, end }` — the only surface mutation performed by summary compaction. See the Agent Note for why reusing `user/message` is honest rather than a workaround.
+Compaction extends [`SessionEventMap`](session.md) with three event types via declaration merging. All three are **log-only** — they record the lock, summary, selected range, shadowed event seqs, token count, and model call without joining the surface. `SurfaceEventType` is deliberately NOT extended (only message-producing events reach the model), so the summary itself rides on a separate `user/message` with `surfaceOp: { op: 'replace', start, end }` — the only surface mutation performed by summary compaction. See the Agent Note for why reusing `user/message` is honest rather than a workaround.
 
 | Event | Payload | Role |
 |---|---|---|
 | `compact/start` | `{ turn }` | acquires the log-recorded lock; a number identifies the open automatic turn, while `null` identifies a standalone manual attempt |
-| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance: the safe summary projection, optional complete provider output and usage, an `llmStreamCall: true` marker when producing the result consumed exactly one call through this context's `ctx.llm.stream()` (which requires complete `rawOutput`), the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note); unmarked `rawOutput` does not identify the call path |
+| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | the safe summary projection, optional complete provider output and usage, an `llmStreamCall: true` marker when producing the result consumed exactly one call through this context's `ctx.llm.stream()` (which requires complete `rawOutput`), the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note); unmarked `rawOutput` does not identify the call path |
 | `compact/end` | `{ turn, error? }` | releases the lock with the same numeric-or-null owner (`error` records an unsuccessful attempt) |
 
-The lock brackets the **whole** operation: `compact/start` is appended first, then summarization, the `compact/summary` provenance record, and the `user/message` replacement all land, and only then `compact/end`. Releasing the lock last turns a crash mid-operation into a detectable orphaned lock (a `compact/start` with no matching `compact/end`) rather than a `compact/end` that falsely claims compaction finished.
+The lock brackets the **whole** operation: `compact/start` is appended first, then summarization, the `compact/summary` record, and the `user/message` replacement all land, and only then `compact/end`. Releasing the lock last turns a crash mid-operation into a detectable orphaned lock (a `compact/start` with no matching `compact/end`) rather than a `compact/end` that falsely claims compaction finished.
 
 The markers are lock time points, not an exclusive container. An unrelated idle injection can appear between a standalone manual start and end while summarization is pending. The manual path revalidates only its selected positional span, so that injected context survives after the replacement checkpoint. A live unmatched start blocks every entry point; an unmatched start before a newer `session/end-seed` is stale evidence from a prior lifecycle and is ignored.
 
@@ -88,7 +88,7 @@ The seam exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalan
 The optional tool-result pruning service reports each durable content replacement and the aggregate Unicode-code-point reduction. Its public result types live in [`compact-tool-result-prune/src/types.ts`](../../packages/compact/compact-tool-result-prune/src/types.ts).
 
 ```ts type-equiv
-/** Provenance and size accounting for one landed surface replacement. */
+/** Cited source event and size accounting for one landed surface replacement. */
 interface PrunedEntry {
   /** Full-fidelity tool-result event shadowed by the replacement. */
   readonly originalSeq: number
@@ -212,7 +212,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 /**
  * Prune every over-budget tool result from one stable current-surface snapshot.
  * Each replacement preserves the complete event data except for `content`,
- * points at the shadowed node for durable provenance and replay, and is
+ * cites the shadowed node so replay can recover the replacement input, and is
  * immediately preceded by a `compact/prune` shadow-price event pricing the
  * shadowed node through the injected token meter, so pure consumers can
  * subtract it without per-node state.
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 20b4b2381f..b4108ed5de 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -8,15 +8,15 @@
 
 ## `compact/*` 会话事件
 
-压缩通过声明合并为 [`SessionEventMap`](session.md) 扩展三种事件类型。三者都**仅写入日志**——记录压缩锁及其 provenance，绝不进入 surface。这里有意不扩展 `SurfaceEventType`（只有产生消息的事件才到达模型），因此摘要本身承载在另一条带有 `surfaceOp: { op: 'replace', start, end }` 的 `user/message` 上——这是摘要压缩执行的唯一 surface 变更。关于复用 `user/message` 为何是如实建模而非权宜之计，见对应 Agent Note。
+压缩通过声明合并为 [`SessionEventMap`](session.md) 扩展三种事件类型。三者都**仅写入日志**——它们记录锁、摘要、选中范围、被遮蔽事件 seq、token 数以及模型调用，绝不进入 surface。这里有意不扩展 `SurfaceEventType`（只有产生消息的事件才到达模型），因此摘要本身承载在另一条带有 `surfaceOp: { op: 'replace', start, end }` 的 `user/message` 上——这是摘要压缩执行的唯一 surface 变更。关于复用 `user/message` 为何是如实建模而非权宜之计，见对应 Agent Note。
 
 | 事件 | 载荷 | 作用 |
 |---|---|---|
 | `compact/start` | `{ turn }` | 获取日志记录的锁；数字标识打开的自动轮次，`null` 标识独立手动尝试 |
-| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance：安全摘要投影、可选的完整 provider 输出与 usage、生成结果时恰好通过此上下文的 `ctx.llm.stream()` 发起一次调用所带的 `llmStreamCall: true` 标记（此时必须提供完整的 `rawOutput`）、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note）；未带标记的 `rawOutput` 并不能判定调用路径 |
+| `compact/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | 安全摘要投影、可选的完整 provider 输出与 usage、生成结果时恰好通过此上下文的 `ctx.llm.stream()` 发起一次调用所带的 `llmStreamCall: true` 标记（此时必须提供完整的 `rawOutput`）、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note）；未带标记的 `rawOutput` 并不能判定调用路径 |
 | `compact/end` | `{ turn, error? }` | 使用相同的数字或 `null` 归属值释放锁（`error` 记录失败尝试） |
 
-锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 来源记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。
+锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。
 
 这些标记表示锁的时间点，而不是排他的容器。摘要等待期间，不相关的空闲注入可以出现在独立的手动 start 与 end 之间。手动路径只重新验证所选位置 span，因此替换检查点之后仍保留该注入上下文。活动的未匹配 start 会阻塞所有入口点；较新 `session/end-seed` 之前的未匹配 start 是先前生命周期留下的陈旧证据，会被忽略。
 
@@ -88,7 +88,7 @@ type ManualCompactionErrorCode =
 可选的工具结果剪枝服务会报告每次持久内容替换以及 Unicode code point 的总减少量。其公开结果类型位于 [`compact-tool-result-prune/src/types.ts`](../../packages/compact/compact-tool-result-prune/src/types.ts)。
 
 ```ts type-equiv
-/** Provenance and size accounting for one landed surface replacement. */
+/** Cited source event and size accounting for one landed surface replacement. */
 interface PrunedEntry {
   /** Full-fidelity tool-result event shadowed by the replacement. */
   readonly originalSeq: number
@@ -212,7 +212,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null
 /**
  * Prune every over-budget tool result from one stable current-surface snapshot.
  * Each replacement preserves the complete event data except for `content`,
- * points at the shadowed node for durable provenance and replay, and is
+ * cites the shadowed node so replay can recover the replacement input, and is
  * immediately preceded by a `compact/prune` shadow-price event pricing the
  * shadowed node through the injected token meter, so pure consumers can
  * subtract it without per-node state.
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 6a117435f5..55589b0232 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: b09e5b4f0a076a7f95a751a6204836a81a4c31e9
-core.zh.md: 01ac656fb657296fb26217108b8a4a15a5a88280
+core.md: b6ed77c1f06b903924db31547d57e07ea37129be
+core.zh.md: e0cf8b39ba2430e250c9d0e51eebf902537cf198
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index b09e5b4f0a..b6ed77c1f0 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -107,7 +107,7 @@ interface Agent {
    * cancel leaves it parked. A wake submitted while already idle always opens
    * its turn boundary, even when its message is cleared before the driver
    * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
-   * @param message - identified content and its producer provenance.
+   * @param message - identified content and the source that supplied it.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.
    */
@@ -116,7 +116,7 @@ interface Agent {
   /**
    * Queue an ordinary follow-up turn and wake the driver. The item becomes the
    * sole ordinary message of its own turn.
-   * @param message - identified prompt content and its producer provenance.
+   * @param message - identified prompt content and the source that supplied it.
    */
   followup(message: UserMessage): void
 
@@ -125,7 +125,7 @@ interface Agent {
    * a running driver consumes it at its next step boundary.
    * A rejected step leaves steering parked in the inbox until the next
    * wake; cancellation or disposal may discard pending steering.
-   * @param message - identified steering content and its producer provenance.
+   * @param message - identified steering content and the source that supplied it.
    */
   steer(message: UserMessage): void
 
@@ -135,7 +135,7 @@ interface Agent {
    * idle drivers leave it pending until follow-up or steering
    * wakes them. It may miss a request whose pre-step already claimed its
    * batch. Cancellation or disposal may discard pending context.
-   * @param message - identified injected context and its producer provenance.
+   * @param message - identified injected context and the source that supplied it.
    */
   inject(message: UserMessage): void
 }
@@ -200,7 +200,7 @@ type AgentCancelCause =
   | { readonly kind: 'disposed' }
 ```
 
-The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
+The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; recording who requested cancellation would require a separate durable event rather than overloading the terminal result.
 
 The [event taxonomy](../architecture.md#event) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits.
 
@@ -210,7 +210,7 @@ The process-local initiator carried by `ctx.agents` is the exact `Agent` above,
 
 ## Interception decisions
 
-Pre-step decisions use the same identified `UserMessage` shape as durable user-role input. The entered batch is authoritative and preserves every message's identity and provenance. Hook bridges map their native decision fields onto this typed result.
+Pre-step decisions use the same identified `UserMessage` shape as durable user-role input. The entered batch is authoritative and preserves every message's id and source. Hook bridges map their native decision fields onto this typed result.
 
 Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
@@ -243,7 +243,7 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ## Sessions
 
-A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. Every entry carries a monotonic `seq`, a `time`, and a `type`-discriminated `data` payload; surface variants additionally carry `sourceEventSeqs` provenance and a `surfaceOp`.
+A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. Every entry carries a monotonic `seq`, a `time`, and a `type`-discriminated `data` payload; surface variants may also list cited earlier events in `sourceEventSeqs` and carry a `surfaceOp`.
 
 The `SessionEvent` envelope's exact conditional shape, the twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 01ac656fb6..e0cf8b39ba 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -111,7 +111,7 @@ interface Agent {
    * cancel leaves it parked. A wake submitted while already idle always opens
    * its turn boundary, even when its message is cleared before the driver
    * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
-   * @param message - identified content and its producer provenance.
+   * @param message - identified content and the source that supplied it.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.
    */
@@ -120,7 +120,7 @@ interface Agent {
   /**
    * Queue an ordinary follow-up turn and wake the driver. The item becomes the
    * sole ordinary message of its own turn.
-   * @param message - identified prompt content and its producer provenance.
+   * @param message - identified prompt content and the source that supplied it.
    */
   followup(message: UserMessage): void
 
@@ -129,7 +129,7 @@ interface Agent {
    * a running driver consumes it at its next step boundary.
    * A rejected step leaves steering parked in the inbox until the next
    * wake; cancellation or disposal may discard pending steering.
-   * @param message - identified steering content and its producer provenance.
+   * @param message - identified steering content and the source that supplied it.
    */
   steer(message: UserMessage): void
 
@@ -139,7 +139,7 @@ interface Agent {
    * idle drivers leave it pending until follow-up or steering
    * wakes them. It may miss a request whose pre-step already claimed its
    * batch. Cancellation or disposal may discard pending context.
-   * @param message - identified injected context and its producer provenance.
+   * @param message - identified injected context and the source that supplied it.
    */
   inject(message: UserMessage): void
 }
@@ -204,7 +204,7 @@ type AgentCancelCause =
   | { readonly kind: 'disposed' }
 ```
 
-cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
+cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录谁请求了取消，应使用单独的持久事件，而不是让终态结果承担额外含义。
 
 [事件分类](../architecture.md#event)拥有 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）约定。轮次和步骤边界是持久会话事件，而不是 agent emit。
 
@@ -216,7 +216,7 @@ cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有
 
 ## 拦截决策
 
-pre-step 决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。进入步骤的批次具有权威性，并保留每条消息的标识与 provenance。钩子桥接层把其原生决策字段映射到这一类型化结果上。
+pre-step 决策使用与持久 user-role 输入相同、带标识的 `UserMessage` 形状。进入步骤的批次具有权威性，并保留每条消息的 id 和 source。钩子桥接层把其原生决策字段映射到这一类型化结果上。
 
 源码：[`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
 
@@ -249,7 +249,7 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
 ## 会话
 
-`Session` 是一份类型化 `SessionEvent` 的**仅追加日志**——唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`），而非单独存储。每个条目携带单调的 `seq`、`time` 与按 `type` 判别的 `data` payload；surface 变体还额外携带 `sourceEventSeqs` provenance 与 `surfaceOp`。
+`Session` 是一份类型化 `SessionEvent` 的**仅追加日志**——唯一的真源。LLM（大语言模型）消息历史从日志*派生*（`deriveMessages()`），而非单独存储。每个条目携带单调的 `seq`、`time` 与按 `type` 判别的 `data` payload；surface 变体还可以在 `sourceEventSeqs` 中列出被引用的较早事件，并携带 `surfaceOp`。
 
 `SessionEvent` 信封的确切条件形状、十二种事件变体（`turn/start`、`turn/end`、`step/start`、`step/end`、`user/message`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`steering/message`、`todo/write`、`request/header`）、`deriveMessages()` 投影规则、`TurnTrigger`/`TurnEndReason` 原因以及执行封闭和独立事件规则都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index 946aca73b0..abb60661c8 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: 1705c45697df98b51ba9f69c8c91b3a8a18dea76
-llm-streaming.zh.md: b47ae516e39cb6657ce5b6ada69d524d5f5ea174
+llm-streaming.md: 37f2fcc51a8b899414927615a7c7750254fa9445
+llm-streaming.zh.md: f9dab459be1006c6ea894498b9a28b49e9ec7738
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index 1705c45697..37f2fcc51a 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -31,10 +31,10 @@ The block interfaces (full fields in source): `TextBlock` (`text`), `ReasoningBl
 
 Source: [`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
 
-A `Message` is one identified, immutable role/source/content value. Model-produced assistant messages carry provider/model ownership and optional adapter-private replay metadata in their source:
+A `Message` is one identified, immutable role/source/content value. Model-produced assistant messages name the provider and model that produced them and carry optional adapter-private replay data in their source:
 
 ```ts type-equiv
-/** Provider ownership and adapter-private replay data for an assistant message. */
+/** Provider/model identity and adapter-private replay data for an assistant message. */
 interface AssistantProvenance {
   /** Provider route that produced the message. */
   provider: string
@@ -58,7 +58,7 @@ interface Message {
   readonly role: 'system' | 'user' | 'assistant'
   /** Exact model-facing blocks. */
   readonly content: ContentBlock[]
-  /** Required producer provenance. */
+  /** Required source fields supplied by the producer. */
   readonly source: MessageSource
 }
 ```
@@ -78,12 +78,12 @@ interface MessageSourceMap {
 }
 ```
 
-Provenance and shape are two independent axes. `kind` answers *who produced this*; the optional `form` a producer mixes in answers *what shape of information it is*, so several producers may share one presentation and one producer may emit more than one shape over a session. The vocabulary is semantic and grows one value at a time; an absent or unrecognized value is the documented default, presented as opaque content:
+Producer identity and content shape are independent. `kind` answers *who produced this*; the optional `form` a producer mixes in answers *what shape of information it is*, so several producers may share one presentation and one producer may emit more than one shape over a session. The vocabulary is semantic and grows one value at a time; an absent or unrecognized value is the documented default, presented as opaque content:
 
 ```ts type-equiv
 /**
  * What SHAPE of information a producer-supplied context carries, declared by
- * the producer beside its provenance.
+ * the producer beside the source fields it supplied.
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
@@ -210,7 +210,7 @@ Every adapter MUST obey these, and every consumer may rely on them:
 - **Context overflow has one canonical code.** Both DeepSeek adapters classify explicit provider detail through `isContextWindowExceededError()` and surface `CONTEXT_WINDOW_EXCEEDED`, whether the failure arrives as a thrown HTTP `LlmError` or an in-band finish error. Consumers route on the code, never provider text.
 - **An empty completion is a retryable error, not a silent success.** Both adapters map a terminal `stop` finish that carried no content blocks to `finish {kind:'error'}` with the canonical `EMPTY_RESPONSE` code, and `dsh-llm-retry` retries it by default; see [empty model responses are retryable](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md).
 - **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test (mock server asserting the received header, or the library's header hook for a library-backed adapter).
-- **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmService` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content and provenance without the private state.
+- **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmService` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content plus provider/model fields without the private state.
 
 This contract is pinned down by two deliberately independent implementations: `dsh-llm-deepseek` (direct fetch, SSE framing via `eventsource-parser`) and `dsh-llm-pi-ai` (a generic multi-provider adapter through `@earendil-works/pi-ai`). The library-backed adapter exercises the finish-chunk error path, while transport-boundary tests prove each idle watchdog stops its actual request.
 
@@ -264,7 +264,7 @@ interface TokenUsage {
 
 ## `BlockAssembler`
 
-`BlockAssembler` ([`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)) is the single shared implementation that folds a `StreamChunk` stream back into `ContentBlock`s, usage, finish reason, and replay state. The loop logs the raw chunks while feeding the same chunks through an assembler, then stores the assembled assistant content with its provider/model provenance. A consumer that needs the assembled result without re-implementing the fold uses this.
+`BlockAssembler` ([`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)) is the single shared implementation that folds a `StreamChunk` stream back into `ContentBlock`s, usage, finish reason, and replay state. The loop logs the raw chunks while feeding the same chunks through an assembler, then stores the assembled assistant content with the provider and model that produced it. A consumer that needs the assembled result without re-implementing the fold uses this.
 
 ```ts public-api
 /**
@@ -585,9 +585,9 @@ interface LlmDiscoveredModel {
 
 ### The request envelope: `LlmCallConfig` and the logged header
 
-The loop builds each request from logged state. `EpochHeader` records call config, adapter-default provenance, rendered prompt, and authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
+The loop builds each request from logged state. `EpochHeader` records call config, marks the fields supplied by adapter defaults, and records the rendered prompt and authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset) through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability Agent Note](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
 
-`agent/request` receives a frozen call-config seed and may return a replacement to switch provider, model, reasoning effort, or sampling. Before the waterfall, the loop removes values marked as adapter defaults so exact-model preparation materializes the selected route's current values; unmarked explicit settings remain in the proposal. After the waterfall, preparation rejects unsupported explicit effort ids without clamping and logs the effective config plus provenance under the turn signal. The prepared call keeps one adapter registration through dispatch. Requests reaching `llm/stream` are deep-frozen, so mutation throws, and carry a process-local loop identity so observers do not confuse separately logged frozen auxiliary calls with conversation requests.
+`agent/request` receives a frozen call-config seed and may return a replacement to switch provider, model, reasoning effort, or sampling. Before the waterfall, the loop removes values marked as adapter defaults so exact-model preparation materializes the selected route's current values; unmarked explicit settings remain in the proposal. After the waterfall, preparation rejects unsupported explicit effort ids without clamping and logs the effective config plus the fields supplied by adapter defaults under the turn signal. The prepared call keeps one adapter registration through dispatch. Requests reaching `llm/stream` are deep-frozen, so mutation throws, and carry a process-local loop identity so observers do not confuse separately logged frozen auxiliary calls with conversation requests.
 
 On the wire, a loop-built request reads the `system` slot (the rendered prompt assembly) followed by the derived history — the boundary snapshot, whose tail is the newest `user/message` on a turn's first step and the previous step's tool results on later steps. The dev invariant recomputes exactly this equation against every loop-built request.
 
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index b47ae516e3..f9dab459be 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -31,10 +31,10 @@ interface ContentBlockMap {
 
 源码：[`packages/llm/llm/src/message.ts`](../../packages/llm/llm/src/message.ts)
 
-`Message` 是一个带标识且不可变的角色／来源／内容值。模型产生的 assistant 消息会在其来源中携带提供方／模型所有权与可选的适配器私有回放元数据：
+`Message` 是一个带标识且不可变的角色／来源／内容值。模型生成的 assistant 消息会在来源中记录生成它的提供方和模型，以及可选的适配器私有回放数据：
 
 ```ts type-equiv
-/** Provider ownership and adapter-private replay data for an assistant message. */
+/** Provider/model identity and adapter-private replay data for an assistant message. */
 interface AssistantProvenance {
   /** Provider route that produced the message. */
   provider: string
@@ -58,7 +58,7 @@ interface Message {
   readonly role: 'system' | 'user' | 'assistant'
   /** Exact model-facing blocks. */
   readonly content: ContentBlock[]
-  /** Required producer provenance. */
+  /** Required source fields supplied by the producer. */
   readonly source: MessageSource
 }
 ```
@@ -78,12 +78,12 @@ interface MessageSourceMap {
 }
 ```
 
-溯源与形态是相互独立的两根轴。`kind` 回答「由谁产生」；生产方可选混入的 `form` 回答「这是何种形态的信息」，因此多个生产方可以共用一种呈现，一个生产方在一次会话中也可以发出多种形态。该词汇表是语义的，逐个取值增长；未声明或无法识别的取值是有文档的默认，按不透明内容呈现：
+生产方标识与内容形态相互独立。`kind` 回答「由谁产生」；生产方可选混入的 `form` 回答「这是何种形态的信息」，因此多个生产方可以共用一种呈现，一个生产方在一次会话中也可以发出多种形态。该词汇表是语义的，逐个取值增长；未声明或无法识别的取值是有文档的默认，按不透明内容呈现：
 
 ```ts type-equiv
 /**
  * What SHAPE of information a producer-supplied context carries, declared by
- * the producer beside its provenance.
+ * the producer beside the source fields it supplied.
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
@@ -214,7 +214,7 @@ interface LlmFailure {
 - **上下文溢出只有一个规范 code。** 两个 DeepSeek 适配器都通过 `isContextWindowExceededError()` 对提供方的显式细节分类并暴露 `CONTEXT_WINDOW_EXCEEDED`，无论失败以抛出的 HTTP `LlmError` 还是带内 finish error 到达。消费方按 code 路由，绝不依赖提供方文本。
 - **空 completion 是可重试错误，而不是静默的成功结果。** 两个适配器都把没有携带任何内容块的终止性 `stop` 结束映射为携带规范 `EMPTY_RESPONSE` code 的 `finish {kind:'error'}`，`dsh-llm-retry` 默认会重试它；详见[空模型响应可重试](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md)。
 - **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
-- **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容与 provenance，不会收到私有状态。
+- **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容以及提供方／模型字段，不会收到私有状态。
 
 该约定由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
 
@@ -272,7 +272,7 @@ interface TokenUsage {
 
 ## `BlockAssembler`
 
-`BlockAssembler`（[`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)）是唯一的共享实现，负责把 `StreamChunk` 流折叠回 `ContentBlock`、usage、结束原因与回放状态。循环在记录原始分片的同时，把同一批分片送入 assembler，再将组装后的 assistant 内容连同其提供方/模型 provenance 一起存储。需要组装结果、又不想重新实现 fold 的消费方使用它。
+`BlockAssembler`（[`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)）是唯一的共享实现，负责把 `StreamChunk` 流折叠回 `ContentBlock`、usage、结束原因与回放状态。循环在记录原始分片的同时，把同一批分片送入 assembler，再将组装后的 assistant 内容连同生成它的提供方和模型一起存储。需要组装结果、又不想重新实现 fold 的消费方使用它。
 
 ```ts public-api
 /**
@@ -593,9 +593,9 @@ interface LlmDiscoveredModel {
 
 ### 请求信封：`LlmCallConfig` 与记录的 header
 
-循环从已记录状态构建每个请求。`EpochHeader` 通过完整的 `request/header` 快照记录调用配置、适配器默认值来源、渲染后的提示词以及权威返回工具顺序（由 `toolOrder` 配置；未配置时按字典序）。结合派生历史，请求便可由会话日志重建。见 [session.md](session.md#the-request-header-event-requestheader) 与[可重建性 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
+循环从已记录状态构建每个请求。`EpochHeader` 记录调用配置，标记由适配器默认值提供的字段，并通过完整的 `request/header` 快照记录渲染后的提示词以及权威返回工具顺序（由 `toolOrder` 配置；未配置时按字典序）。结合派生历史，请求便可由会话日志重建。见 [session.md](session.md#the-request-header-event-requestheader) 与[可重建性 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)。
 
-`agent/request` 接收冻结的调用配置种子，并可返回替代值以切换提供方、模型、推理强度或采样参数。waterfall 开始前，循环会移除标记为适配器默认值的值，使确切模型准备过程填入所选路由的当前值；未带标记的显式设置仍保留在提议中。waterfall 结束后，准备过程会在轮次信号控制下拒绝显式指定但不受支持的推理强度 ID（不自动调整），并记录生效配置及其来源。准备完成的调用直至分派完成始终持有同一项适配器注册。到达 `llm/stream` 的请求会被深度冻结，因此变更会抛异常；请求还携带进程本地循环标识，使观察者不会把单独记录的冻结辅助调用误认成对话请求。
+`agent/request` 接收冻结的调用配置种子，并可返回替代值以切换提供方、模型、推理强度或采样参数。waterfall 开始前，循环会移除标记为适配器默认值的值，使确切模型准备过程填入所选路由的当前值；未带标记的显式设置仍保留在提议中。waterfall 结束后，准备过程会在轮次信号控制下拒绝显式指定但不受支持的推理强度 ID（不自动调整），并记录生效配置以及由适配器默认值提供的字段。准备完成的调用直至分派完成始终持有同一项适配器注册。到达 `llm/stream` 的请求会被深度冻结，因此变更会抛异常；请求还携带进程本地循环标识，使观察者不会把单独记录的冻结辅助调用误认成对话请求。
 
 在协议格式上，循环构建的请求先读取 `system` 槽位（渲染后的提示词组装），再读取派生历史——边界快照，其尾部在轮次首步是最新的 `user/message`，在后续步骤是上一步的工具结果。开发不变式针对每个循环构建的请求精确重算此等式。
 
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index 728a6cf8db..02a3502a1a 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.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 docs/subsystems/session-query.md
-session-query.md: 54ae1eaf34a17d4979a621e4fc310780b425364e
-session-query.zh.md: b770514757c30aa5d87b25e5d280b1ce6710cd9c
+session-query.md: 9e907b2ebf12c01620921c7955f25d2fdd6ce4fb
+session-query.zh.md: 4452330ebd5e487387c0ad15bea45b76d9c643be
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index 54ae1eaf34..9e907b2ebf 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -292,10 +292,10 @@ interface SessionEventWindow {
 
 ## Event relationships
 
-Event traces distinguish positional surface replacement from logged provenance. Every seq list contains direct links except `replacementChain`, which follows immediate replacers from the target to the final positional replacement.
+Event traces distinguish positional surface replacement from events cited as sources. Every seq list contains direct links except `replacementChain`, which follows immediate replacers from the target to the final positional replacement.
 
 ```ts type-equiv
-/** Request for direct surface and provenance relationships around one event. */
+/** Request for direct surface replacements and relationships to cited source events around one event. */
 interface SessionEventTraceRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
@@ -305,7 +305,7 @@ interface SessionEventTraceRequest {
 ```
 
 ```ts type-equiv
-/** Direct surface and provenance relationships for one event. */
+/** Direct surface replacements and relationships to cited source events for one event. */
 interface SessionEventTrace {
   /** Lightweight target record. */
   target: SessionEventRecord
@@ -315,9 +315,9 @@ interface SessionEventTrace {
   replacementChain: number[]
   /** Surface nodes directly removed when the target itself performed a replacement. */
   replacedEventSeqs: number[]
-  /** Direct logged provenance sources in their recorded order. */
+  /** Earlier events cited directly as sources, in their recorded order. */
   sourceEventSeqs: number[]
-  /** Later events that directly name the target as a provenance source, in log order. */
+  /** Later events that directly cite the target as a source, in log order. */
   derivedEventSeqs: number[]
 }
 ```
@@ -471,11 +471,11 @@ async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
 async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>
 
 /**
- * Trace one event's direct positional and provenance relationships.
+ * Trace one event's direct positional replacements and cited source events.
  * @param request - target session id and event seq.
  * @param signal - optional cancellation for persisted source resolution.
  * @returns source header, direct links, and the target's positional replacement chain.
- * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+ * @throws when source resolution fails, the target is absent, or surface/source-event validation fails.
  */
 async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>
 
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index b770514757..4452330ebd 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -292,10 +292,10 @@ interface SessionEventWindow {
 
 ## 事件关系
 
-事件追踪会区分位置替换与日志中记录的来源关系。除 `replacementChain` 外，每个 seq 列表都只包含直接链接；该链从目标沿直接 replacer 追踪到最终的位置替换。
+事件追踪会区分位置替换与被引用为来源的事件。除 `replacementChain` 外，每个 seq 列表都只包含直接链接；该链从目标沿直接 replacer 追踪到最终的位置替换。
 
 ```ts type-equiv
-/** Request for direct surface and provenance relationships around one event. */
+/** Request for direct surface replacements and relationships to cited source events around one event. */
 interface SessionEventTraceRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
@@ -305,7 +305,7 @@ interface SessionEventTraceRequest {
 ```
 
 ```ts type-equiv
-/** Direct surface and provenance relationships for one event. */
+/** Direct surface replacements and relationships to cited source events for one event. */
 interface SessionEventTrace {
   /** Lightweight target record. */
   target: SessionEventRecord
@@ -315,9 +315,9 @@ interface SessionEventTrace {
   replacementChain: number[]
   /** Surface nodes directly removed when the target itself performed a replacement. */
   replacedEventSeqs: number[]
-  /** Direct logged provenance sources in their recorded order. */
+  /** Earlier events cited directly as sources, in their recorded order. */
   sourceEventSeqs: number[]
-  /** Later events that directly name the target as a provenance source, in log order. */
+  /** Later events that directly cite the target as a source, in log order. */
   derivedEventSeqs: number[]
 }
 ```
@@ -471,11 +471,11 @@ async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
 async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>
 
 /**
- * Trace one event's direct positional and provenance relationships.
+ * Trace one event's direct positional replacements and cited source events.
  * @param request - target session id and event seq.
  * @param signal - optional cancellation for persisted source resolution.
  * @returns source header, direct links, and the target's positional replacement chain.
- * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+ * @throws when source resolution fails, the target is absent, or surface/source-event validation fails.
  */
 async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>
 
diff --git a/docs/subsystems/session-title.i18n.yaml b/docs/subsystems/session-title.i18n.yaml
index 8b58415234..29804cae7e 100644
--- a/docs/subsystems/session-title.i18n.yaml
+++ b/docs/subsystems/session-title.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 docs/subsystems/session-title.md
-session-title.md: 3a2df284f2af14def284e502f4e37daaf4d7a262
-session-title.zh.md: 3a74baa9005459b35b658df95bdd7b57256b3e2e
+session-title.md: 339177b03a03b7d82375f7a293934cb164e9f266
+session-title.zh.md: b1353025a4f621e9a3117c0406ad304c35828a49
diff --git a/docs/subsystems/session-title.md b/docs/subsystems/session-title.md
index 3a2df284f2..339177b03a 100644
--- a/docs/subsystems/session-title.md
+++ b/docs/subsystems/session-title.md
@@ -8,7 +8,7 @@ Sources: [`packages/session/session-title/src/index.ts`](../../packages/session/
 
 ## Durable title state
 
-`SessionTitleProviderId` is recorded for provider-produced revisions. `SessionTitleEventData` carries exact human-message provenance, while `SessionTitleSnapshot` adds the durable event envelope facts selected by `foldSessionTitle()`.
+`SessionTitleProviderId` is recorded for provider-produced revisions. `SessionTitleEventData` lists the exact human-message seqs used for the title, while `SessionTitleSnapshot` adds the durable event envelope facts selected by `foldSessionTitle()`.
 
 ```ts type-equiv
 /** Identifies one session-title provider registration. */
@@ -47,7 +47,7 @@ interface SessionTitleEventData {
   readonly title: string
   /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
   readonly messageSeqs: number[]
-  /** Built-in fallback, registered-provider, or explicit-user provenance. */
+  /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
   readonly source: SessionTitleSource
 }
 ```
@@ -86,7 +86,7 @@ interface SessionTitleLlmRequestEventData {
 
 ## Provider input and output
 
-The service snapshots eligible messages through one revision. A provider returns only seqs from that request; service-owned acceptance verifies ordering, normalizes the title, enforces the byte limit, and appends provenance.
+The service snapshots eligible messages through one revision. A provider returns only seqs from that request; service-owned acceptance verifies ordering, normalizes the title, enforces the byte limit, and appends the title with its source-message seqs and source kind.
 
 ```ts type-equiv
 /** One eligible human text message exposed to title providers. */
@@ -132,14 +132,14 @@ interface SessionTitleProviderResult {
 ```ts type-equiv
 /** One optional asynchronous title implementation registered with the service. */
 interface SessionTitleProvider {
-  /** Stable provider identity recorded in title provenance. */
+  /** Stable id of the provider recorded with the title. */
   readonly id: SessionTitleProviderId
   /** When new human prompts start automatic generation. */
   readonly automatic: SessionTitleAutomaticMode
   /**
    * Produce one title revision.
    * @param request - message snapshot, current route, session, and cancellation.
-   * @returns proposed title plus exact input seqs and optional model provenance.
+   * @returns proposed title plus exact input seqs and the optional provider/model route used to generate it.
    */
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
diff --git a/docs/subsystems/session-title.zh.md b/docs/subsystems/session-title.zh.md
index 3a74baa900..b1353025a4 100644
--- a/docs/subsystems/session-title.zh.md
+++ b/docs/subsystems/session-title.zh.md
@@ -8,7 +8,7 @@
 
 ## 持久标题状态
 
-提供方生成修订时会记录 `SessionTitleProviderId`。`SessionTitleEventData` 携带精确的人类消息来源信息，`SessionTitleSnapshot` 则加入 `foldSessionTitle()` 选出的持久事件封装信息。
+提供方生成修订时会记录 `SessionTitleProviderId`。`SessionTitleEventData` 列出生成标题时使用的精确人类消息 seq，`SessionTitleSnapshot` 则加入 `foldSessionTitle()` 选出的持久事件封装信息。
 
 ```ts type-equiv
 /** Identifies one session-title provider registration. */
@@ -47,7 +47,7 @@ interface SessionTitleEventData {
   readonly title: string
   /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
   readonly messageSeqs: number[]
-  /** Built-in fallback, registered-provider, or explicit-user provenance. */
+  /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
   readonly source: SessionTitleSource
 }
 ```
@@ -86,7 +86,7 @@ interface SessionTitleLlmRequestEventData {
 
 ## 提供方输入与输出
 
-服务会对截至某一修订的合格消息创建快照。提供方返回的 seq 仅可来自该请求；由服务负责的接纳流程会验证顺序、规范化标题、强制执行字节上限并追加来源信息。
+服务会对截至某一修订的合格消息创建快照。提供方返回的 seq 仅可来自该请求；由服务负责的接纳流程会验证顺序、规范化标题、强制执行字节上限，并追加标题及其来源消息 seq 和来源类型。
 
 ```ts type-equiv
 /** One eligible human text message exposed to title providers. */
@@ -132,14 +132,14 @@ interface SessionTitleProviderResult {
 ```ts type-equiv
 /** One optional asynchronous title implementation registered with the service. */
 interface SessionTitleProvider {
-  /** Stable provider identity recorded in title provenance. */
+  /** Stable id of the provider recorded with the title. */
   readonly id: SessionTitleProviderId
   /** When new human prompts start automatic generation. */
   readonly automatic: SessionTitleAutomaticMode
   /**
    * Produce one title revision.
    * @param request - message snapshot, current route, session, and cancellation.
-   * @returns proposed title plus exact input seqs and optional model provenance.
+   * @returns proposed title plus exact input seqs and the optional provider/model route used to generate it.
    */
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 6f28409864..890563b91d 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 7735e90807f6fce1b3645096437b3e86189dc8ec
-session.zh.md: 63eb460f7ef300decf3e32c0ace16b354606c271
+session.md: 6fb39e946cf5acdc407aab99888d40960d617248
+session.zh.md: 30edd630b4c945d3b696b5ac346b4bcebfb3df16
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 7735e90807..6fb39e946c 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -8,7 +8,7 @@ Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/t
 
 ## `SessionEventMap` — the event vocabulary
 
-The append-only event types. Merge-extensible: a plugin declares extra event types via declaration merging — e.g. the [compaction seam](compaction.md) adds `compact/start` / `compact/summary` / `compact/end`, and `@deepseek-ai/dsh-hook-protocol` adds log-only `hook/invoked` / `hook/result` provenance for a hook bridge. Like `compact/*`, these are NOT `SurfaceEventType`s (no `surfaceOp`). The generated [persistence log event catalog](../persistence-catalog.md) enumerates every member — core and merged — with its payload, surface badge, and declaration site.
+The append-only event types. Merge-extensible: a plugin declares extra event types via declaration merging — e.g. the [compaction seam](compaction.md) adds `compact/start` / `compact/summary` / `compact/end`, and `@deepseek-ai/dsh-hook-protocol` adds log-only `hook/invoked` / `hook/result` records for a hook bridge. Like `compact/*`, these are NOT `SurfaceEventType`s (no `surfaceOp`). The generated [persistence log event catalog](../persistence-catalog.md) enumerates every member — core and merged — with its payload, surface badge, and declaration site.
 
 ```ts type-equiv
 /** A user-role specialization of the one shared message representation. */
@@ -151,7 +151,7 @@ interface TodoItem {
 
 ### The request header event: `request/header`
 
-The request envelope — the `EpochHeader` (call config + adapter-default provenance + rendered system prompt + assembled tool schemas) — is logged session state, so every conversation request is a pure function of the log (the reconstructability Agent Note). A full `request/header` snapshot with reason `'initial'` or `'resume'` records each loop-instance boundary; a later changed request records another full snapshot with reason `'change'`. `foldRequestHeader(events)` reconstructs the header by selecting the latest snapshot. The event is not a `SurfaceEventType`: it produces no LLM message.
+The request envelope — the `EpochHeader` (call config + markers for adapter-supplied defaults + rendered system prompt + assembled tool schemas) — is logged session state, so every conversation request is a pure function of the log (the reconstructability Agent Note). A full `request/header` snapshot with reason `'initial'` or `'resume'` records each loop-instance boundary; a later changed request records another full snapshot with reason `'change'`. `foldRequestHeader(events)` reconstructs the header by selecting the latest snapshot. The event is not a `SurfaceEventType`: it produces no LLM message.
 
 ```ts type-equiv
 /**
@@ -217,11 +217,11 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
     data: SessionEventMap[K]
   } & (K extends SurfaceEventType ? {
     /**
-     * Seq numbers of events that are provenance sources of this event
+     * Seq numbers of earlier events that this event cites as sources
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
+     * provider stream; omission means the source stream was not recorded.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -232,7 +232,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 `SessionEventType = keyof SessionEventMap`. Because `SessionEventMap` is merge-extensible, switches over `SessionEvent` must NOT use `assertNever` — a plugin-added variant is a valid unknown value; handle the known cases and fall through `default`.
 
-For `assistant/message`, a present `sourceEventSeqs: []` is a complete known-empty provider stream, while an absent field means legacy or otherwise unrecorded provenance. The loop writes the field for every successful model call; every other surface event requires a non-empty list when the field is present.
+For `assistant/message`, a present `sourceEventSeqs: []` is a complete known-empty provider stream, while an absent field means the source stream was not recorded in a legacy or foreign event. The loop writes the field for every successful model call; every other surface event requires a non-empty list when the field is present.
 
 ## Surface types
 
@@ -278,15 +278,15 @@ type SurfaceOp =
 
 ```ts type-equiv
 /**
- * Surface placement and provenance for {@link Session.append}. Required on
+ * Surface placement and cited source-event seqs for {@link Session.append}. Required on
  * message-producing events and forbidden on log-only events.
  */
 interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
-   * Complete known provenance source set. `assistant/message` may use a
+   * Complete set of known source-event seqs. `assistant/message` may use a
    * present empty array for a known empty provider stream; omission means its
-   * provenance was not recorded. Other surface events require a non-empty set
+   * source stream was not recorded. Other surface events require a non-empty set
    * when this field is present.
    */
   sourceEventSeqs?: number[]
@@ -295,7 +295,7 @@ interface SurfaceIntent {
 
 Required for `SurfaceEventType` events — every message-producing event must declare how it joins the surface, the sole source of derived model history. A human-facing transcript is the other projection and reads the log's append-origin events instead, because the surface deliberately shadows the ranges a replacement summarizes (`isAppendSurfaceEvent` in [dsh-session](../../packages/core/session/README.md)). Non-surface types reject it at compile time.
 
-The same provenance distinction applies here: only `assistant/message` may carry a present empty `sourceEventSeqs`; omission does not assert that its source stream was empty.
+Only `assistant/message` may carry a present empty `sourceEventSeqs`; omission means the source stream was not recorded and does not assert that the stream was empty.
 
 ### `SessionSurface` — the live readonly surface projection
 
@@ -430,8 +430,8 @@ declare class Session {
    * @param type - The event type (key of {@link SessionEventMap}).
    * @param data - The event payload; must be JSON-serializable.
    * @param opts - Surface metadata: `surfaceOp` controls how the event enters
-   *   the ordered surface; `sourceEventSeqs` records provenance (the seq
-   *   numbers of events this one derives from). REQUIRED for
+   *   the ordered surface; `sourceEventSeqs` lists the seq numbers of earlier
+   *   events this one derives from. REQUIRED for
    *   {@link SurfaceEventType} events (every message-producing event must
    *   declare how it joins the surface, the sole source of derived model
    *   history) and
@@ -445,7 +445,7 @@ declare class Session {
    *   circular reference, sparse array, or an exotic object such as
    *   Map/Set/Date/class instance), or when the candidate violates the
    *   canonical surface contract (marker shape and eligibility, unique
-   *   earlier provenance, positional replacement validity, and complete
+   *   earlier source-event references, positional replacement validity, and complete
    *   shadowed-node coverage). One recursive pass reads, validates, and
    *   copies each nested value once, so a stateful getter cannot supply one value
    *   to validation and another to storage. The event log is the durable source
@@ -508,11 +508,11 @@ declare class Session {
 `Session.deriveMessages()` projects the event log into the `Message[]` the model sees — cached (each surface node projected once, when first seen; a surface rewrite rebuilds) and frozen (a fresh array per call over shared, deep-frozen messages, so mutating logged history through a projection is unrepresentable). `deriveEventMessage(event)` is the per-node pure function the fold applies — public so external reconstructors and the dev invariant project a log prefix with exactly the same rules and cannot disagree with the cache. The projection rules:
 
 - `user/message` → a user message carrying exact `content`; an optional envelope remains log-only display metadata.
-- `assistant/message` → an assistant message with the event's provider/model provenance and optional adapter-private replay state. Raw `assistant/chunk` events are replay/UI data and are **skipped** in derivation (the assembled message is authoritative). An **empty-content** `assistant/message` is also skipped — a max-tokens step cut off with no content still records an `assistant/message` to host its usage/provenance, but a content-less assistant turn must not enter the provider transcript.
+- `assistant/message` → an assistant message with the provider and model that produced it plus optional adapter-private replay state. Raw `assistant/chunk` events are replay/UI data and are **skipped** in derivation (the assembled message is authoritative). An **empty-content** `assistant/message` is also skipped — a max-tokens step cut off with no content still records an `assistant/message` to hold its usage, provider, and model, but a content-less assistant turn must not enter the provider transcript.
 - `tool/result` → a user message carrying a `tool-result` block.
-- `user/message` (injected context, i.e. non-`user` source) → a user-role message carrying its `content` verbatim at its chronological position; provenance and domain data live in its typed source.
+- `user/message` (injected context, i.e. non-`user` source) → a user-role message carrying its `content` verbatim at its chronological position; its typed source names the producer and carries any producer-specific data.
 
-Everything else (`turn/*`, `step/*`, plugin-owned `llm/retry`) is structural and does not project into a message. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message, so their usage chunk is the durable accounting record. Because this unreleased format intentionally has no compatibility promise, seed/load validation rejects request headers without provider+model and assistant messages without provider/model provenance instead of guessing a route for historical data.
+Everything else (`turn/*`, `step/*`, plugin-owned `llm/retry`) is structural and does not project into a message. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message, so their usage chunk is the durable accounting record. Because this unreleased format intentionally has no compatibility promise, seed/load validation rejects request headers and assistant messages that omit provider/model instead of guessing a route for historical data.
 
 ## Live-session fork API
 
@@ -577,9 +577,9 @@ Activity ordering excludes the boundary through `lastActivityTime(events)`: pick
 
 ## Plugin-contributed log-only events
 
-A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The full per-event enumeration — core and plugin-contributed alike, with payloads and provenance — is the generated [persistence log event catalog](../persistence-catalog.md); the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).
+A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The generated [persistence log event catalog](../persistence-catalog.md) enumerates every core and plugin-contributed event with its payload, surface badge, cited source-event seqs, and declaration site; the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).
 
-The hook bridges' `hook/invoked` / `hook/result` provenance pairs (from `@deepseek-ai/dsh-hook-protocol`) correlate by `handlerId`. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` fire inside the loop's open turn, so their `hook/*` records are turn-enclosed by construction. `SessionStart` gets no `hook/*` record because it runs before turn 1; its context remains pending in the inbox until a waking delivery opens a turn (see [the hook-bridges Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)).
+The hook bridges' `hook/invoked` / `hook/result` pairs (from `@deepseek-ai/dsh-hook-protocol`) correlate by `handlerId`. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` fire inside the loop's open turn, so their `hook/*` records are turn-enclosed by construction. `SessionStart` gets no `hook/*` record because it runs before turn 1; its context remains pending in the inbox until a waking delivery opens a turn (see [the hook-bridges Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)).
 
 ## Durability contract
 
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 63eb460f7e..30edd630b4 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -8,7 +8,7 @@
 
 ## `SessionEventMap`：事件词汇
 
-仅追加的事件类型。可通过声明合并扩展：插件通过 declaration merging 声明额外的事件类型。例如[压缩（compaction） seam](compaction.md) 添加了 `compact/start` / `compact/summary` / `compact/end`，`@deepseek-ai/dsh-hook-protocol` 添加了仅记录日志的 `hook/invoked` / `hook/result` 溯源事件，用于钩子桥接。与 `compact/*` 一样，这些都不是 `SurfaceEventType`（没有 `surfaceOp`）。生成的[持久化日志事件目录](../persistence-catalog.md)列举了所有成员（核心与合并扩展的），包含其 payload、surface 标记与声明位置。
+仅追加的事件类型。可通过声明合并扩展：插件通过 declaration merging 声明额外的事件类型。例如[压缩（compaction） seam](compaction.md) 添加了 `compact/start` / `compact/summary` / `compact/end`，`@deepseek-ai/dsh-hook-protocol` 为钩子桥接添加了仅记录日志的 `hook/invoked` / `hook/result` 记录。与 `compact/*` 一样，这些都不是 `SurfaceEventType`（没有 `surfaceOp`）。生成的[持久化日志事件目录](../persistence-catalog.md)列举了所有成员（核心与合并扩展的），包含其 payload、surface 标记与声明位置。
 
 ```ts type-equiv
 /** A user-role specialization of the one shared message representation. */
@@ -153,7 +153,7 @@ interface TodoItem {
 
 ### 请求头事件：`request/header`
 
-请求信封（即 `EpochHeader`：调用配置 + 适配器默认值来源 + 渲染后的系统提示词 + 已组装的工具 schema）会作为会话状态写入日志，因此每个对话请求都是日志的纯函数（见可重建性 Agent Note）。带有 reason `'initial'` 或 `'resume'` 的完整 `request/header` 快照记录每个 agent loop 实例的边界；之后请求发生变化时，系统会以 reason `'change'` 记录另一份完整快照。`foldRequestHeader(events)` 通过选择最新快照重建请求头。该事件不是 `SurfaceEventType`，不产生 LLM 消息。
+请求信封（即 `EpochHeader`：调用配置 + 适配器所提供默认值的标记 + 渲染后的系统提示词 + 已组装的工具 schema）会作为会话状态写入日志，因此每个对话请求都是日志的纯函数（见可重建性 Agent Note）。带有 reason `'initial'` 或 `'resume'` 的完整 `request/header` 快照记录每个 agent loop 实例的边界；之后请求发生变化时，系统会以 reason `'change'` 记录另一份完整快照。`foldRequestHeader(events)` 通过选择最新快照重建请求头。该事件不是 `SurfaceEventType`，不产生 LLM 消息。
 
 ```ts type-equiv
 /**
@@ -219,11 +219,11 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
     data: SessionEventMap[K]
   } & (K extends SurfaceEventType ? {
     /**
-     * Seq numbers of events that are provenance sources of this event
+     * Seq numbers of earlier events that this event cites as sources
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
+     * provider stream; omission means the source stream was not recorded.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -234,7 +234,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 `SessionEventType = keyof SessionEventMap`。由于 `SessionEventMap` 可通过合并扩展，对 `SessionEvent` 的 switch 语句禁止使用 `assertNever`：插件添加的变体是合法的未知值；处理已知 case 后在 `default` 中放行。
 
-对于 `assistant/message`，存在的 `sourceEventSeqs: []` 表示提供方流已知且完整地为空；字段缺失则表示旧格式或其他未记录溯源信息的情况。agent loop 会为每次成功的模型调用写入该字段；其他 surface 事件只要包含该字段，其列表就必须非空。
+对于 `assistant/message`，存在的 `sourceEventSeqs: []` 表示提供方流已知且完整地为空；字段缺失则表示旧格式或外部事件没有记录源流。agent loop 会为每次成功的模型调用写入该字段；其他 surface 事件只要包含该字段，其列表就必须非空。
 
 ## Surface 类型
 
@@ -280,15 +280,15 @@ type SurfaceOp =
 
 ```ts type-equiv
 /**
- * Surface placement and provenance for {@link Session.append}. Required on
+ * Surface placement and cited source-event seqs for {@link Session.append}. Required on
  * message-producing events and forbidden on log-only events.
  */
 interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
-   * Complete known provenance source set. `assistant/message` may use a
+   * Complete set of known source-event seqs. `assistant/message` may use a
    * present empty array for a known empty provider stream; omission means its
-   * provenance was not recorded. Other surface events require a non-empty set
+   * source stream was not recorded. Other surface events require a non-empty set
    * when this field is present.
    */
   sourceEventSeqs?: number[]
@@ -297,7 +297,7 @@ interface SurfaceIntent {
 
 对 `SurfaceEventType` 事件必填：每个产生消息的事件都必须声明它如何加入 surface（派生模型历史的唯一来源）。面向人类的记录（transcript）是另一个投影，读取的是日志中追加来源的事件，因为 surface 会有意遮蔽替换所概括的范围（见 [dsh-session](../../packages/core/session/README.md) 的 `isAppendSurfaceEvent`）。非 surface 类型在编译期拒绝此参数。
 
-此处适用相同的溯源区分：只有 `assistant/message` 可以携带存在但为空的 `sourceEventSeqs`；省略该字段并不表示其源流为空。
+只有 `assistant/message` 可以携带存在但为空的 `sourceEventSeqs`；省略该字段表示源流没有记录，而不是表示源流为空。
 
 ### `SessionSurface`：实时只读 surface 投影
 
@@ -432,8 +432,8 @@ declare class Session {
    * @param type - The event type (key of {@link SessionEventMap}).
    * @param data - The event payload; must be JSON-serializable.
    * @param opts - Surface metadata: `surfaceOp` controls how the event enters
-   *   the ordered surface; `sourceEventSeqs` records provenance (the seq
-   *   numbers of events this one derives from). REQUIRED for
+   *   the ordered surface; `sourceEventSeqs` lists the seq numbers of earlier
+   *   events this one derives from. REQUIRED for
    *   {@link SurfaceEventType} events (every message-producing event must
    *   declare how it joins the surface, the sole source of derived model
    *   history) and
@@ -447,7 +447,7 @@ declare class Session {
    *   circular reference, sparse array, or an exotic object such as
    *   Map/Set/Date/class instance), or when the candidate violates the
    *   canonical surface contract (marker shape and eligibility, unique
-   *   earlier provenance, positional replacement validity, and complete
+   *   earlier source-event references, positional replacement validity, and complete
    *   shadowed-node coverage). One recursive pass reads, validates, and
    *   copies each nested value once, so a stateful getter cannot supply one value
    *   to validation and another to storage. The event log is the durable source
@@ -510,11 +510,11 @@ declare class Session {
 `Session.deriveMessages()` 将事件日志投影为模型看到的 `Message[]`。它是缓存的（每个 surface 节点在首次出现时投影一次；surface 重写触发重建）且冻结的（每次调用返回一个新数组，引用共享的深冻结消息，因此通过投影修改已记录的历史在类型上不可表达）。`deriveEventMessage(event)` 是折叠所应用的逐节点纯函数，公开暴露以便外部重建器和开发不变式检查能以完全相同的规则投影日志前缀，不会与缓存产生分歧。投影规则：
 
 - `user/message` → 一条携带确切 `content` 的 user 消息；可选 envelope 仅作为日志中的展示元数据保留。
-- `assistant/message` → 一条 assistant 消息，包含事件的提供方/模型溯源信息和可选的适配器私有回放状态。原始 `assistant/chunk` 事件属于回放/UI 数据，在派生时会被**跳过**（组装后的消息才是权威）。**内容为空的** `assistant/message` 也会跳过：因 max-tokens 而截断且无内容的步骤仍会记录一条 `assistant/message` 以承载用量和溯源信息，但无内容的 assistant 轮次不得进入提供方 transcript（文本记录）。
+- `assistant/message` → 一条 assistant 消息，包含生成它的提供方和模型，以及可选的适配器私有回放状态。原始 `assistant/chunk` 事件属于回放/UI 数据，在派生时会被**跳过**（组装后的消息才是权威）。**内容为空的** `assistant/message` 也会跳过：因 max-tokens 而截断且无内容的步骤仍会记录一条 `assistant/message` 来保存用量、提供方和模型，但无内容的 assistant 轮次不得进入提供方 transcript（文本记录）。
 - `tool/result` → 一条携带 `tool-result` 块的 user 消息。
-- `user/message`（注入上下文，即非 `user` 来源）→ 按时间顺序在相应位置生成一条 user-role 消息，并原样承载其 `content`；溯源信息与领域数据都在其类型化的 source 中。
+- `user/message`（注入上下文，即非 `user` 来源）→ 按时间顺序在相应位置生成一条 user-role 消息，并原样承载其 `content`；其类型化 source 标明生产方，并携带所有生产方专用数据。
 
-其余所有事件（`turn/*`、`step/*`、插件所有的 `llm/retry`）均为结构信息，不会投影为消息。token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息，因此其用量分片是持久化的记账记录。由于这一尚未发布的格式有意不提供兼容性承诺，seed/load 校验会拒绝缺少提供方和模型的请求头，以及缺少提供方/模型溯源信息的 assistant 消息，而不会猜测历史数据应走的提供方路由。
+其余所有事件（`turn/*`、`step/*`、插件所有的 `llm/retry`）均为结构信息，不会投影为消息。token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息，因此其用量分片是持久化的记账记录。由于这一尚未发布的格式有意不提供兼容性承诺，seed/load 校验会拒绝没有提供方／模型的请求头和 assistant 消息，而不会猜测历史数据应走的提供方路由。
 
 ## 活跃会话 fork API
 
@@ -581,9 +581,9 @@ interface TurnEndReasonMap {
 
 ## 插件贡献的仅日志事件
 
-插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。完整的逐事件枚举（核心与插件贡献的，含 payload 与溯源信息）见生成的[持久化日志事件目录](../persistence-catalog.md)；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
+插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。生成的[持久化日志事件目录](../persistence-catalog.md)会列出每个核心或插件贡献的事件，以及其 payload、surface 标记、被引用的来源事件 seq 和声明位置；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
 
-钩子桥接层的 `hook/invoked` / `hook/result` 溯源对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次（见[钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)）。
+钩子桥接层的 `hook/invoked` / `hook/result` 对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次（见[钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)）。
 
 ## 持久性约定
 
diff --git a/docs/subsystems/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
index 67b938a93a..1e9547cc28 100644
--- a/docs/subsystems/spill.i18n.yaml
+++ b/docs/subsystems/spill.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 docs/subsystems/spill.md
-spill.md: 41a3fdaf7d9b15fbc6d479724f77f579b8a98738
-spill.zh.md: 02a6fc4e88dfcfdb47f7639d988fc09c6bc42c69
+spill.md: a0a476761ab0633227d7c87033daee79f649bf50
+spill.zh.md: 65d7e4cb89a93e2e709af0a620f523aad2315ed2
diff --git a/docs/subsystems/spill.md b/docs/subsystems/spill.md
index 41a3fdaf7d..a0a476761a 100644
--- a/docs/subsystems/spill.md
+++ b/docs/subsystems/spill.md
@@ -8,7 +8,7 @@ Source: [`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/typ
 
 ## The save request
 
-`saveText` is the whole seam: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), WHERE it came from (`source`, descriptive provenance for naming and inspection — not access control), and a `suggestedName` the backend may use as a naming hint (it is not a path).
+`saveText` is the whole seam: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), the tool and call that produced it (`source`, used for naming and inspection — not access control), and a `suggestedName` the backend may use as a naming hint (it is not a path).
 
 ```ts type-equiv
 /** One request to persist text to a spill artifact. */
@@ -42,7 +42,7 @@ interface SpillOwner {
 
 ```ts type-equiv
 /**
- * Provenance of one spilled artifact — recorded by the backend for a readable
+ * Tool and call that produced one spilled artifact — recorded by the backend for a readable
  * filename and inspection. Not interpreted for access control; purely
  * descriptive.
  */
@@ -107,7 +107,7 @@ Semantics every implementation must honor:
 ```ts cordis-catalog
 /**
  * Persist `input.content` to a session-scoped spill artifact.
- * @param input - the owner, provenance, suggested name, and full text to save.
+ * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
  * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
  */
 abstract saveText(input: SaveTextSpill): Promise<SpillRef>
diff --git a/docs/subsystems/spill.zh.md b/docs/subsystems/spill.zh.md
index 02a6fc4e88..65d7e4cb89 100644
--- a/docs/subsystems/spill.zh.md
+++ b/docs/subsystems/spill.zh.md
@@ -8,7 +8,7 @@
 
 ## 保存请求
 
-`saveText` 是整个 seam：原样持久保存 `content`，并返回不透明的定位符、后端提供的检索提示和准确字节数。请求携带保存时的存储命名空间（`owner`）、内容来源（`source`，用于命名和检查的描述性来源信息，而非访问控制）以及后端可用作命名提示的 `suggestedName`（它不是路径）。
+`saveText` 是整个 seam：原样持久保存 `content`，并返回不透明的定位符、后端提供的检索提示和准确字节数。请求携带保存时的存储命名空间（`owner`）、生成内容的工具和调用（`source`，用于命名和检查，而非访问控制）以及后端可用作命名提示的 `suggestedName`（它不是路径）。
 
 ```ts type-equiv
 /** One request to persist text to a spill artifact. */
@@ -42,7 +42,7 @@ interface SpillOwner {
 
 ```ts type-equiv
 /**
- * Provenance of one spilled artifact — recorded by the backend for a readable
+ * Tool and call that produced one spilled artifact — recorded by the backend for a readable
  * filename and inspection. Not interpreted for access control; purely
  * descriptive.
  */
@@ -107,7 +107,7 @@ Semantics every implementation must honor:
 ```ts cordis-catalog
 /**
  * Persist `input.content` to a session-scoped spill artifact.
- * @param input - the owner, provenance, suggested name, and full text to save.
+ * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
  * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
  */
 abstract saveText(input: SaveTextSpill): Promise<SpillRef>
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 9ecb6e4628..cad0584ea2 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: 3bf3ac7c48bfa08be86314bb43263d4ee6198654
-subagent.zh.md: 37b274d7f3ffa5b5aadea773d29f7e6b4e5a833b
+subagent.md: cbb7c37f1ff3bce673f78a29ff8993659078df73
+subagent.zh.md: 308770141aa44fadeabed5f080d0df47c3802f15
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index 3bf3ac7c48..cbb7c37f1f 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -137,7 +137,7 @@ persisted Session
 
 The Agent inbox is the only queue. Every continuation message becomes one `Agent.followup()` FIFO turn, so accepted messages have one observable order and a follow-up cannot redirect a turn already underway. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/enqueue`, `agent/inbox/dequeue`, and `agent/inbox/discard` events remain the message-lifecycle observations, and the continuation layer defines no subagent-specific delivery route.
 
-Follow-up authority comes from an exact live Agent tool context. The authenticated Agent must be the durable child's direct parent recorded in `SessionHeader.parentSession`. `MessageSource` and `senderSessionId` are durable provenance after admission and grant no authority; the optional model-facing tool uses `CoordinatorMessageSource`.
+Follow-up authority comes from an exact live Agent tool context. The authenticated Agent must be the durable child's direct parent recorded in `SessionHeader.parentSession`. `MessageSource` and `senderSessionId` record who supplied an admitted message but grant no authority; the optional model-facing tool uses `CoordinatorMessageSource`.
 
 For both operations the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child, and the seam exposes no steering operation.
 
@@ -425,7 +425,7 @@ interface SubagentProvider {
 }
 ```
 
-Provider `start()` fulfills with a published run. The service mints a unique `runId`, snapshots `local` from the provider's exact `localAgent`, observes the result, emits `subagent/start`, and returns the same run; a `start()` rejection implies cleanup of unpublished resources and emits no lifecycle pair, while a post-publication result rejection closes the emitted pair. Each continuable Activation emits the same observe-only pair for its residency epoch, so a cold resume is a new epoch with its own `runId`. The paired `subagent/end` carries the same identity and the final output or infrastructure failure. Both events are observe-only and contain listener exceptions. Their `provider` field is provenance for the run or Activation epoch, not a claim that the provider remains registered when the edge is emitted.
+Provider `start()` fulfills with a published run. The service mints a unique `runId`, snapshots `local` from the provider's exact `localAgent`, observes the result, emits `subagent/start`, and returns the same run; a `start()` rejection implies cleanup of unpublished resources and emits no lifecycle pair, while a post-publication result rejection closes the emitted pair. Each continuable Activation emits the same observe-only pair for its residency epoch, so a cold resume is a new epoch with its own `runId`. The paired `subagent/end` carries the same identity and the final output or infrastructure failure. Both events are observe-only and contain listener exceptions. Their `provider` field names the provider that started the run or Activation epoch; it does not claim that the provider remains registered when the edge is emitted.
 
 ## In-process backends: depth and seed
 
@@ -469,7 +469,7 @@ async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
  * @param parent - the exact live direct parent authorizing this delivery.
  * @param childId - durable child session id.
  * @param content - user-role content to deliver.
- * @param options - durable provenance and caller cancellation, which stops the
+ * @param options - the message source fields and caller cancellation, which stops the
  *   operation only before inbox acceptance.
  * @returns the accepted message's inbox id.
  * @throws when continuation services are unavailable, parent authority is
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 37b274d7f3..308770141a 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -137,7 +137,7 @@ persisted Session
 
 Agent 收件箱是唯一的队列。每条继续执行消息都会成为一个 `Agent.followup()` FIFO 轮次，因此已接受的消息共享同一个可观测顺序，且后续消息无法改变已在进行中的轮次。投递成功会返回被接受的 `MessageId`；既有的 `agent/inbox/enqueue`、`agent/inbox/dequeue` 与 `agent/inbox/discard` 事件仍是消息生命周期的观测点，继续执行层不定义任何 subagent 专属的投递路由。
 
-后续操作的权限来自确切的在线 Agent 工具上下文。已认证的 Agent 必须是持久化子 agent 在 `SessionHeader.parentSession` 中记录的直接父级。`MessageSource` 与 `senderSessionId` 在准入之后是持久的来源凭据，不授予任何权限；可选的面向模型工具使用 `CoordinatorMessageSource`。
+后续操作的权限来自确切的在线 Agent 工具上下文。已认证的 Agent 必须是持久化子 agent 在 `SessionHeader.parentSession` 中记录的直接父级。`MessageSource` 与 `senderSessionId` 记录谁提供了已准入的消息，但不授予任何权限；可选的面向模型工具使用 `CoordinatorMessageSource`。
 
 对于这两种操作，调用方 signal 仅在收件箱接受之前掌管查找、物化与准入。此后管理器独立掌管该 Activation：之后的调用方取消既不会取消已接受的轮次，也不会 dispose 子 agent，并且该 seam 不对外暴露任何 steering（中途引导）操作。
 
@@ -427,7 +427,7 @@ interface SubagentProvider {
 }
 ```
 
-提供方的 `start()` 会以已发布的 run fulfill。服务铸造唯一的 `runId`，从提供方确切的 `localAgent` 快照 `local`，观察结果，emit `subagent/start`，并返回同一个 run；`start()` rejection 意味着未发布资源已清理，且不会 emit 生命周期事件对，而发布后的结果 rejection 会结束已经 emit 的事件对。每个可继续 Activation 都会为其驻留纪元 emit 相同的仅观察事件对，因此一次冷恢复就是一段拥有自己 `runId` 的新纪元。配对的 `subagent/end` 携带相同标识与最终输出或基础设施失败。两个事件都仅用于观察，且会隔离各自的 listener 异常。其中的 `provider` 字段是 run 或 Activation 时段的来源信息，并不声明该 edge 发出时提供方仍处于注册状态。
+提供方的 `start()` 会以已发布的 run fulfill。服务铸造唯一的 `runId`，从提供方确切的 `localAgent` 快照 `local`，观察结果，emit `subagent/start`，并返回同一个 run；`start()` rejection 意味着未发布资源已清理，且不会 emit 生命周期事件对，而发布后的结果 rejection 会结束已经 emit 的事件对。每个可继续 Activation 都会为其驻留纪元 emit 相同的仅观察事件对，因此一次冷恢复就是一段拥有自己 `runId` 的新纪元。配对的 `subagent/end` 携带相同标识与最终输出或基础设施失败。两个事件都仅用于观察，且会隔离各自的 listener 异常。其中的 `provider` 字段标明了启动 run 或 Activation 时段的提供方，并不声明该 edge 发出时提供方仍处于注册状态。
 
 ## 进程内后端：深度与种子
 
@@ -471,7 +471,7 @@ async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>
  * @param parent - the exact live direct parent authorizing this delivery.
  * @param childId - durable child session id.
  * @param content - user-role content to deliver.
- * @param options - durable provenance and caller cancellation, which stops the
+ * @param options - the message source fields and caller cancellation, which stops the
  *   operation only before inbox acceptance.
  * @returns the accepted message's inbox id.
  * @throws when continuation services are unavailable, parent authority is
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index e598429553..36ea230990 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -1021,7 +1021,7 @@ Source: [`packages/session-query/tool-session-query/src/index.ts`](../packages/s
 
 ### `session_event_trace`
 
-Read every direct replacement and provenance relationship for one event in an authorized session.
+Read every direct replacement and relationship to a cited source event for one event in an authorized session.
 
 ```json
 {
diff --git a/examples/headless-agent/tests/compaction.e2e.ts b/examples/headless-agent/tests/compaction.e2e.ts
index 6fe6f4055b..35a9a1627e 100644
--- a/examples/headless-agent/tests/compaction.e2e.ts
+++ b/examples/headless-agent/tests/compaction.e2e.ts
@@ -64,7 +64,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa
     expect(starts.length).toBeGreaterThan(0)
     expect(ends.length).toBe(starts.length) // every start was released
 
-    // It succeeded at least once: a compact/summary provenance event and a
+    // It succeeded at least once: a `compact/summary` event describing the summary and a
     // replace-op user/message (the surface mutation) both landed.
     const summaries = events.filter(e => e.type === 'compact/summary')
     expect(summaries.length).toBeGreaterThan(0)
diff --git a/native/landlock-run/docs/architecture.md b/native/landlock-run/docs/architecture.md
index b462b40635..458281bf29 100644
--- a/native/landlock-run/docs/architecture.md
+++ b/native/landlock-run/docs/architecture.md
@@ -25,7 +25,7 @@ The launcher exits `125` without exec'ing the command on any launcher-level fail
 
 ## Build and release model
 
-Builds are native-only. `scripts/build.ts` compiles the running architecture's binaries with the distro `musl-gcc` (static: no loader or libc expectations on consumers, one binary for glibc and musl distros); CI's per-architecture runners are the builders of record, and no cross toolchain exists in the repo. The audit surface of a tool is its reviewed C source plus CI provenance, enforced by three gates: platform prepack refuses missing/wrong-ELF binaries, entry prepack refuses unbuilt `lib/`, and the release pipeline byte-pins installed binaries against the workspace builds they were packed from.
+Builds are native-only. `scripts/build.ts` compiles the running architecture's binaries with the distro `musl-gcc` (static: no loader or libc expectations on consumers, one binary for glibc and musl distros); CI's per-architecture runners are the builders of record, and no cross toolchain exists in the repo. Review covers the C source and the CI job that built each binary, enforced by three gates: platform prepack refuses missing/wrong-ELF binaries, entry prepack refuses unbuilt `lib/`, and the release pipeline byte-pins installed binaries against the workspace builds they were packed from.
 
 The package matrix is checked-in metadata (`prebuilds.json` + `os`/`cpu` fields); `scripts/github-matrix.mjs` derives the CI and Release matrices from it, so adding a platform extends automation without editing workflows.
 
diff --git a/native/landlock-run/scripts/build.ts b/native/landlock-run/scripts/build.ts
index 5866cc0dc4..b8e2d34f12 100644
--- a/native/landlock-run/scripts/build.ts
+++ b/native/landlock-run/scripts/build.ts
@@ -10,7 +10,7 @@
  * distros alike, no loader or libc expectations on the consumer host), and
  * CI's per-arch runners are the builders of record. No cross toolchain
  * exists here on purpose: native runners replace it, and the audit surface
- * is the reviewed C source plus CI provenance.
+ * is the reviewed C source plus the CI job that built the binary.
  *
  * Binaries land in `packages/<name>/bin/` — git-ignored (root
  * `.gitignore`), packed into the platform package's npm tarball behind its
diff --git a/native/landlock-run/scripts/verify-launcher-binary.mjs b/native/landlock-run/scripts/verify-launcher-binary.mjs
index 083cd837aa..997b20ca0f 100644
--- a/native/landlock-run/scripts/verify-launcher-binary.mjs
+++ b/native/landlock-run/scripts/verify-launcher-binary.mjs
@@ -8,9 +8,8 @@
  * binary's absence surfacing only at runtime as a failed probe on every
  * consumer — and a binary copied across packages would advertise an
  * architecture it cannot execute. The check is presence + ELF `e_machine`
- * against the package's declared `cpu`; byte provenance is
- * `verify-packed-install.mjs`'s concern (it pins the installed tarball
- * against the workspace build).
+ * against the package's declared `cpu`. `verify-packed-install.mjs`
+ * separately pins the installed tarball bytes to the workspace build.
  *
  * Runs from each platform package's `prepack` hook (pnpm sets the script
  * cwd to the package directory). Also callable directly with an explicit
diff --git a/packages/bash/bash-sandbox/README.i18n.yaml b/packages/bash/bash-sandbox/README.i18n.yaml
index b4eb8c4869..97ea5f301b 100644
--- a/packages/bash/bash-sandbox/README.i18n.yaml
+++ b/packages/bash/bash-sandbox/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/bash/bash-sandbox/README.md
-README.md: 74c1e28f76db35603bb9f72e0522e16ece5589f7
-README.zh.md: 34ad936f31bf4ce11e175653a3a895a56e4822cc
+README.md: 3ac46eaef8a0c6ee47c3141e2580c4d2e7750e8c
+README.zh.md: 4f3fb85c8de00497e4aff546d8234a81336586cb
diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md
index 74c1e28f76..3ac46eaef8 100644
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -17,7 +17,7 @@ Every command is confined by handing the provider the exact `['bash', '-c', comm
 Semantics:
 
 - **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `BashRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI).
-- **Runner attribution is conservative.** Before a process starts, a rejection is attributed to the runner only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with positive provenance for provider argv[0]. This covers a missing runner, a non-executable runner, or an executable script whose shebang interpreter is unavailable. A bare `syscall: 'spawn'` without an exact error path, any other code, an invalid or unusable workdir, a resource failure, an unrelated syscall, or an unstructured rejection retains the local executor's command-start failure semantics. Foreground execution throws `SANDBOX_UNAVAILABLE` with the original spawn detail, while asynchronous background settlement stamps `runnerFailed: true` and `denied: false`. If a `SubprocessService` synchronously throws the same provenanced `ENOENT`/`EACCES` shape, background start throws `SANDBOX_UNAVAILABLE`; other synchronous errors propagate unchanged. After a process starts, a rule's optional exit-code gate and a remaining fatal stderr line must both match after exact informational-line exclusions. A match outranks denial; foreground execution throws `SANDBOX_UNAVAILABLE` with the matched fatal line, while a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`. Confined background handles retain their mode/enforcement facts and release per-process accounting in either path.
+- **Runner attribution is conservative.** Before a process starts, a rejection is attributed to the runner only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` whose error path equals provider argv[0]. This covers a missing runner, a non-executable runner, or an executable script whose shebang interpreter is unavailable. A bare `syscall: 'spawn'` without an exact error path, any other code, an invalid or unusable workdir, a resource failure, an unrelated syscall, or an unstructured rejection retains the local executor's command-start failure semantics. Foreground execution throws `SANDBOX_UNAVAILABLE` with the original spawn detail, while asynchronous background settlement stamps `runnerFailed: true` and `denied: false`. If a `SubprocessService` synchronously throws the same `ENOENT`/`EACCES` shape with the runner path, background start throws `SANDBOX_UNAVAILABLE`; other synchronous errors propagate unchanged. After a process starts, a rule's optional exit-code gate and a remaining fatal stderr line must both match after exact informational-line exclusions. A match outranks denial; foreground execution throws `SANDBOX_UNAVAILABLE` with the matched fatal line, while a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`. Confined background handles retain their mode/enforcement facts and release per-process accounting in either path.
 - **Deployment fallback, per-call policy.** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) resolves a complete `SandboxExecutionPolicy` for every tool call: the calling session supplies its mode override and immutable cwd root, while deployment config supplies the fallbacks for agentless calls. An approved escalation changes only that policy's mode; its session root stays attached. `resolve()` carries the policy onto the spec, so overlapping commands from different projects run, classify, and report under their own roots and modes. The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted; the static bash tool description separately owns denial and escalation guidance.
 - **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce.
 - Process mechanics (spawn, process-group kills, output collection/spill, background handles, credential scrub) are inherited from [`dsh-bash-local`](../bash-local/); runner selection lives in [`dsh-sandbox-local`](../../sandbox/sandbox-local/).
@@ -84,5 +84,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 - **Confinement covers file effects only** — network access and process visibility are unchanged, so the modes are not a general-purpose security sandbox.
 - **Denials are inferred from failed-command stderr** — backend signatures make the inference portable, but a matching application error can be classified as a denial and a denial omitted from the retained tail can be missed.
-- **An asynchronously observed background runner failure has no immediate error channel** — it is recorded on the settled process and surfaces when the caller reads the generic task with `task_output`; a provenanced synchronous `SubprocessService` throw instead fails `start()` immediately.
+- **An asynchronously observed background runner failure has no immediate error channel** — it is recorded on the settled process and surfaces when the caller reads the generic task with `task_output`; a synchronous `SubprocessService` throw that names the runner path instead fails `start()` immediately.
 - **`danger-full-access` deliberately bypasses `ctx.sandbox`** — it is an explicit unconfined mode, not a wider sandbox profile.
diff --git a/packages/bash/bash-sandbox/README.zh.md b/packages/bash/bash-sandbox/README.zh.md
index 34ad936f31..4f3fb85c8d 100644
--- a/packages/bash/bash-sandbox/README.zh.md
+++ b/packages/bash/bash-sandbox/README.zh.md
@@ -17,7 +17,7 @@
 语义：
 
 - **拒绝是结果事实。** 如果一次失败运行的 stderr 包含所选后端自身的拒绝方言，即提供方在每次包装时加上的特征（bwrap 下的 EROFS 文本、Landlock 下的 EACCES、Seatbelt 下的 EPERM），则结果报告 `BashRunResult.sandbox.denied: true`（从已收集的 stderr 尾部进行保守分类）。每次受限制运行还会携带执行时模式（`result.sandbox.mode`）与提供方强制执行完整性（`result.sandbox.enforcement`：`full`，或在较旧 Landlock ABI 上为 `partial`）。
-- **Runner 归因是保守的。** 进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且带有明确指向提供方 argv[0] 的来源信息时，才会将拒绝归因于 runner。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessService` 同步抛出同样带有来源信息的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，先按整行精确匹配排除信息性行，随后规则的可选退出码门控和余下 stderr 中的一行致命诊断必须同时匹配。匹配结果优先于拒绝；前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带匹配到的致命行，已结算的后台进程则会标记 `process.sandbox.runnerFailed`，Bash 结果生成方通过通用 `task_output` 渲染它。无论走哪条路径，受限制的后台句柄都会保留自身的模式／强制执行事实，并释放每进程计数。
+- **Runner 归因是保守的。** 进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且错误对象的 `path` 字段等于提供方返回的 `argv[0]` 时，才会将拒绝归因于 runner。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessService` 同步抛出同样带 runner 路径的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，先按整行精确匹配排除信息性行，随后规则的可选退出码门控和余下 stderr 中的一行致命诊断必须同时匹配。匹配结果优先于拒绝；前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带匹配到的致命行，已结算的后台进程则会标记 `process.sandbox.runnerFailed`，Bash 结果生成方通过通用 `task_output` 渲染它。无论走哪条路径，受限制的后台句柄都会保留自身的模式／强制执行事实，并释放每进程计数。
 - **部署回退，每次调用策略。** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) 为每次工具调用解析完整的 `SandboxExecutionPolicy`：调用会话提供自身的模式覆盖与不可变 cwd 根目录，部署配置则为无 agent（智能体）调用提供回退。已批准的升权只更改该策略的模式，会话根目录仍然附着其上。`resolve()` 把策略带入 spec，因此来自不同项目的重叠命令会在各自的根目录与模式下运行、分类和报告。能力事实 `ctx.bash.sandboxMode` 报告已配置的默认值，因此工具层只在装载该执行器时才公布升权；静态 bash 工具描述则单独负责拒绝与升权引导。
 - **只限制文件影响。** 设计上不限制网络与进程可见性：模式词汇不会声称覆盖后端未强制执行的范围。
 - 进程机制（spawn、进程组终止、输出收集／spill、后台句柄、凭证清理）继承自 [`dsh-bash-local`](../bash-local/)；runner 选择位于 [`dsh-sandbox-local`](../../sandbox/sandbox-local/)。
@@ -84,5 +84,5 @@
 
 - **限制只覆盖文件影响**：网络访问与进程可见性不变，因此这些模式不是通用安全沙箱。
 - **拒绝从失败命令的 stderr 推断**：后端特征使该推断可跨平台使用，但包含相同后端特征的应用错误可能被分类为拒绝，也可能遗漏未出现在保留尾部中的拒绝。
-- **异步观测到的后台 runner 失败没有即时错误通道**：它记录在已结算进程上，并在调用方使用 `task_output` 读取通用任务时呈现；同步 `SubprocessService` 抛出带有来源信息的 `ENOENT`／`EACCES` 时，则会使 `start()` 立即失败。
+- **异步观测到的后台 runner 失败没有即时错误通道**：它记录在已结算进程上，并在调用方使用 `task_output` 读取通用任务时呈现；`SubprocessService` 同步抛出的错误包含 runner 路径时，则会使 `start()` 立即失败。
 - **`danger-full-access` 有意绕过 `ctx.sandbox`**：它是显式无约束模式，不是更宽的沙箱 profile。
diff --git a/packages/bash/bash-sandbox/src/helpers.ts b/packages/bash/bash-sandbox/src/helpers.ts
index 357c73efa1..24ecb390de 100644
--- a/packages/bash/bash-sandbox/src/helpers.ts
+++ b/packages/bash/bash-sandbox/src/helpers.ts
@@ -23,7 +23,7 @@ function isUsableWorkdir(path: string): boolean {
 }
 
 /**
- * Attribute only Node ENOENT/EACCES failures with positive argv[0] provenance
+ * Attribute only Node ENOENT/EACCES failures whose error path equals argv[0]
  * after independently ruling out the caller-owned cwd. A supplied error path
  * must exactly identify the runner; without one, the syscall must. With a
  * usable cwd, these codes describe resolution or execute permission for that
diff --git a/packages/bash/bash-sandbox/src/index.ts b/packages/bash/bash-sandbox/src/index.ts
index eadbae9fef..32695c475d 100644
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -124,7 +124,7 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     try {
       proc = this.startArgv(spec, confined.argv)
     } catch (error) {
-      // LocalSubprocessService reports provenanced ENOENT/EACCES through async
+      // LocalSubprocessService reports ENOENT/EACCES with the failed executable path through async
       // `done` rejection; this covers alternatives that throw that shape synchronously.
       if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) {
         throw new SandboxUnavailableError(mode, String(error))
diff --git a/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts b/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
index b578716c43..9176ac320b 100644
--- a/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
+++ b/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
@@ -151,7 +151,7 @@ describe('partial Landlock runner-failure classification', () => {
 
     // Node/libuv may expose execve's ENOEXEC directly (Darwin) or retry a
     // no-shebang executable through /bin/sh (Linux). Neither path supplies the
-    // provenanced ENOENT/EACCES evidence required for runner attribution.
+    // ENOENT/EACCES with the exact failed executable path required for runner attribution.
     const foreground = await bash.run(bash.resolve(request)).catch((value: unknown) => value)
     expect(foreground).not.toBeInstanceOf(SandboxUnavailableError)
 
diff --git a/packages/bash/bash-sandbox/tests/sandbox.spec.ts b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
index 5bcf68df2d..9c3eceda1e 100644
--- a/packages/bash/bash-sandbox/tests/sandbox.spec.ts
+++ b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
@@ -240,7 +240,7 @@ describe('fail closed', () => {
     expect(background).not.toBeInstanceOf(SandboxUnavailableError)
   })
 
-  it('classifies a synchronous SubprocessService EACCES with exact runner provenance', async () => {
+  it('classifies a synchronous SubprocessService EACCES with the exact runner path', async () => {
     const runner = join(spillDir, 'unexecutable-runner')
     const { ctx, bash } = await setup({}, argv => ({
       argv: [runner, ...argv],
@@ -439,7 +439,7 @@ describe('isRunnerSpawnFailure', () => {
     expect(isRunnerSpawnFailure(spawnError('ENOENT'), undefined, process.cwd())).toBe(false)
   })
 
-  it('accepts only syscall provenance compatible with the exact runner program', () => {
+  it('accepts only syscall and error-path facts that identify the exact runner program', () => {
     const runner = join(spillDir, 'runner with spaces')
     const spawnError = (syscall: string, path?: string) =>
       Object.assign(new Error('spawn failed'), { code: 'ENOENT', syscall, path })
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index e64706453e..21b4371c29 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/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/boot/app-boot/README.md
-README.md: c060e99acb8cc40b8de92806727eea9e3723b7d2
-README.zh.md: f28b89e63e4bd6f07f2f7a55dfba5c2f78862feb
+README.md: 1bbd376121ae79bf37376b51f5ac3eb405af6dfd
+README.zh.md: 0ecaa38deebfafe39673725ee8d35c36d60c5a41
diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md
index c060e99acb..1bbd376121 100644
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -19,7 +19,7 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md) and [`ds
 | `watchUserPatches(ctx, options)` | Register the named patch file with the existing Cordis HMR service; each add/change/removal transactionally recomposes the full patch list through the caller's `compose` closure (app-owned layers around the current user layer) and returns an async disposer |
 | `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile machinery (see [Profiles](#profiles)) |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, expose `dshHomePath(...segments)` to Loader `!!js` config expressions, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots), then mount and await the include tree, assert entries loaded and activated, and return the root context — or dispose the partial context and reject a labelled error |
-| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | Compose the base config and labeled overlay layers offline — the include's own parser and patch algorithm (`entryListSchema`/`applyEntryPatches`), so the result equals what `boot()` mounts — and render YAML with `!!js` expressions verbatim; each run of same-provenance rows is preceded by a `# ==` comment naming the contributing file and the layers that patched it, keeping the output one loadable document; a patch matching no row goes to `warn` with its layer label (default: one stderr line), read/parse/shape failures throw |
+| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | Compose the base config and labeled overlay layers offline — the include's own parser and patch algorithm (`entryListSchema`/`applyEntryPatches`), so the result equals what `boot()` mounts — and render YAML with `!!js` expressions verbatim; each run of rows from the same file and patch layers is preceded by a `# ==` comment naming them, keeping the output one loadable document; a patch matching no row goes to `warn` with its layer label (default: one stderr line), read/parse/shape failures throw |
 | `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to the DSH implementation checkout while warning it not to infer the current working directory from that path and to use `pwd` instead; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
 | `HARNESS_SOURCE_SECTION` | The `'harness:source'` section name `addHarnessSourceSection` registers under |
 
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index f28b89e63e..0ecaa38dee 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -19,7 +19,7 @@
 | `watchUserPatches(ctx, options)` | 向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步 disposer |
 | `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile 机制（见 [Profile](#profiles)） |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject |
-| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
+| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来自同一文件且经相同补丁层修改的连续行之前都有一条 `# ==` 注释，标明该文件和这些补丁层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |
 
diff --git a/packages/boot/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts
index dec77aecab..c722f30f0f 100644
--- a/packages/boot/app-boot/src/index.ts
+++ b/packages/boot/app-boot/src/index.ts
@@ -165,7 +165,7 @@ function readEnvLayer(
  * Load the product CLI's inherited > invoking-directory `.env` > Harness-home
  * `.env` snapshot. The Harness home resolves before either file; both files
  * are checked before either is applied, and accepted values are materialized
- * without replacing inherited ones. The snapshot preserves source provenance.
+ * without replacing inherited ones. The snapshot preserves which layer supplied each value.
  * @param binName - the diagnostic prefix on the diagnostics.
  * @param cwd - the invoking directory whose `.env` is the project layer.
  * @param warn - sink for the one-line misconfiguration diagnostics.
@@ -335,9 +335,9 @@ function parsePatchList(
   return parsed as PatchOptions[]
 }
 
-/** One overlay patch list with the label provenance comments print for it. */
+/** One overlay patch list with the source label printed in dump comments. */
 export interface ConfigDumpLayer {
-  /** Source name shown in provenance comments (a file basename or path). */
+  /** Source name shown in dump comments (a file basename or path). */
   label: string
   /** The layer's patches, from {@link loadOverlayPatches} / {@link loadOptionalPatches}. */
   patches: PatchOptions[]
@@ -353,10 +353,10 @@ export interface ConfigDumpLayer {
  * sees) compose identically — then render the result as YAML in the same
  * dialect (`!!js` expressions print verbatim, unevaluated).
  *
- * Every run of rows with the same provenance is preceded by a `# ==` comment
+ * Every run of rows from the same file and patch layers is preceded by a `# ==` comment
  * naming the file that contributed the rows and any layers that patched them,
  * so the output stays a loadable YAML document while showing which section
- * comes from which file. Provenance is derived from single-call prefix
+ * comes from which file. The file and patch labels are derived from single-call prefix
  * snapshots (base + layers 1..k), diffed positionally: the patch algorithm
  * only rewrites rows in place or appends, so a top-level index identifies one
  * row across snapshots, and a layer whose addition changes the row (config
@@ -372,7 +372,7 @@ export interface ConfigDumpLayer {
  * @param layers - overlay layers in application order (later wins).
  * @param warn - sink for skipped-patch diagnostics; defaults to stderr.
  * @returns the composed entry list rendered as a YAML document with
- * provenance comment separators.
+ * source comment separators.
  */
 export function renderConfigDump(
   binName: string,
@@ -439,7 +439,7 @@ export function renderConfigDump(
   return groupedDump(composed, provenance)
 }
 
-/** Render the composed rows grouped under one provenance comment per contiguous run. */
+/** Render the composed rows grouped under one source-and-patches comment per contiguous run. */
 function groupedDump(
   composed: readonly unknown[],
   provenance: readonly { origin: string; patchedBy: string[] }[],
@@ -455,7 +455,7 @@ function groupedDump(
   }
   for (let index = 0; index < composed.length; index += 1) {
     const record = provenance[index]
-    /* v8 ignore next -- provenance is index-aligned with composed by construction */
+    /* v8 ignore next -- this array is index-aligned with composed by construction */
     if (record === undefined) continue
     const label = record.patchedBy.length === 0
       ? record.origin
diff --git a/packages/boot/app-boot/tests/config-dump.spec.ts b/packages/boot/app-boot/tests/config-dump.spec.ts
index 4f5d8e83e5..3876ec2421 100644
--- a/packages/boot/app-boot/tests/config-dump.spec.ts
+++ b/packages/boot/app-boot/tests/config-dump.spec.ts
@@ -1,7 +1,7 @@
 /**
  * `renderConfigDump` behavior: the offline composition must equal what
  * `boot()` mounts (same parser, same patch algorithm), print `!!js`
- * expressions verbatim, separate provenance runs with comment lines while
+ * expressions verbatim, separate source-file runs with comment lines while
  * staying one loadable YAML document, and report skipped patches through
  * `warn` instead of failing — mirroring the Loader's boot-time warning for a
  * shared overlay whose row exists only on another surface.
@@ -35,7 +35,7 @@ function writeBase(dir: string): string {
 }
 
 describe('renderConfigDump', () => {
-  it('composes overlay layers in order, prints !!js verbatim, and labels each section with its provenance', () => {
+  it('composes overlay layers in order, prints !!js verbatim, and labels each section with its source and patches', () => {
     const dir = tmp()
     const base = writeBase(dir)
     const surface = join(dir, 'surface.yml')
@@ -78,7 +78,7 @@ describe('renderConfigDump', () => {
     ])
     // Unevaluated: the expression text round-trips as a !!js scalar.
     expect(dump).toContain('!!js process.env.DSH_DUMP_SPEC')
-    // Provenance separators: origin file, plus every layer that changed the
+    // Source separators: origin file, plus every layer that changed the
     // row; an inserted row carries the inserting layer as its origin.
     expect(dump).toContain('# == base.yml, patched by surface.yml')
     expect(dump).toContain('# == base.yml\n- id: untouched')
@@ -86,7 +86,7 @@ describe('renderConfigDump', () => {
     expect(dump.indexOf('# == base.yml, patched by surface.yml')).toBeLessThan(dump.indexOf('# == base.yml\n- id: untouched'))
   })
 
-  it('groups contiguous same-provenance rows under one separator', () => {
+  it('groups contiguous rows with the same origin and patches under one separator', () => {
     const dir = tmp()
     const base = join(dir, 'base.yml')
     writeFileSync(base, [
@@ -130,7 +130,7 @@ describe('renderConfigDump', () => {
       config?: { config?: { v?: number } }[]
     }[]
     expect(parsed[0]?.config?.[0]?.config?.v).toBe(1)
-    // The skipped layer did not change the row, so it is not in provenance.
+    // The skipped layer did not change the row, so the comment does not list it.
     expect(dump).toContain('# == base.yml, patched by a.yml\n- id: g')
     expect(dump).not.toContain('b.yml\n- id: g')
   })
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 930a12dea3..641898424e 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: c2ce461439a89aa4fe2d59ebf92d14539479dac8
-README.zh.md: bca93b80989152eccccaf13c0f31435c91e7393c
+README.md: 08a45adc441cc2f672e84dea38d0991537187a1f
+README.zh.md: 7abf86aee015a7108547a0025ca8ba5beceecfb2
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index c2ce461439..08a45adc44 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -36,9 +36,9 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 ## The human transcript
 
-`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
+`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view with the producer role and name: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
 
-Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's `compact/summary` provenance; a window cut that left the provenance outside makes those fields unavailable, and a later page that supplies it resolves them. `CommandNode.outcome.sourceEventSeq` preserves a successful command's explicit reference to that summary event, allowing the presentation layer to pair `/compact` with its checkpoint without parsing settlement copy or assuming the two rows are adjacent. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
+Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's cited `compact/summary` event; a window cut that left that event outside makes those fields unavailable, and a later page that supplies it resolves them. `CommandNode.outcome.sourceEventSeq` preserves a successful command's explicit reference to that summary event, allowing the presentation layer to pair `/compact` with its checkpoint without parsing settlement copy or assuming the two rows are adjacent. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
 
 ## Request inspection
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index bca93b8098..7abf86aee0 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -36,9 +36,9 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 面向人的 transcript（文本记录）
 
-`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
+`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份包含生产者角色和名称的 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
 
-由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点的 `compact/summary` 溯源；窗口切分把溯源留在窗口外时这些字段不可用，后续补上溯源的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
+由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点引用的 `compact/summary` 事件；窗口切分把该事件留在窗口外时这些字段不可用，后续包含该事件的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
 
 ## 请求检查
 
diff --git a/packages/client/runtime/src/client/sessions/context-provenance.ts b/packages/client/runtime/src/client/sessions/context-provenance.ts
index 6f46a510c1..e487f78b5d 100644
--- a/packages/client/runtime/src/client/sessions/context-provenance.ts
+++ b/packages/client/runtime/src/client/sessions/context-provenance.ts
@@ -1,4 +1,4 @@
-// Context provenance projection: the role and the human-facing producer name
+// Context source projection: the role and the human-facing producer name
 // of one logged non-user `user/message`, read from its durable `source` alone.
 // The client keeps no table of known plugin ids — a renamed or newly mounted
 // producer must never need a client release to stay identifiable, and a resumed
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index dba9ec9513..2681bb33f3 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -191,14 +191,14 @@ export interface CompactionSummaryNode {
   seq: number
   /** Unix epoch ms of the checkpoint event. */
   time: number
-  /** Summary text from the checkpoint's `compact/summary` provenance; null when
-   *  the window cut left that provenance outside (the marker is then not expandable). */
+  /** Summary text from the checkpoint's cited `compact/summary` event; null when
+   *  the window cut left that event outside (the marker is then not expandable). */
   summary: string | null
-  /** Seq of the loaded `compact/summary` event, or null when that provenance is outside the window. */
+  /** Seq of the loaded `compact/summary` event, or null when that event is outside the window. */
   summaryEventSeq: number | null
-  /** Number of surface items replaced, or null when summary provenance is unavailable or malformed. */
+  /** Number of surface items replaced, or null when the summary event is unavailable or malformed. */
   shadowedItemCount: number | null
-  /** Estimated token price of the replaced items, or null when summary provenance is unavailable or malformed. */
+  /** Estimated token price of the replaced items, or null when the summary event is unavailable or malformed. */
   shadowedTokenCount: number | null
 }
 
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 659afcac4a..aee51d3dc2 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -686,7 +686,7 @@ export class Session implements SessionFace {
    *  a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an
    *  expected reconnect-window artifact, repaired by refetch). The window stays one contiguous
    *  raw range, which is what lets the transcript render every event between its ends and lets a
-   *  compaction checkpoint find its own provenance. */
+   *  compaction checkpoint find its cited summary event. */
   private acceptLiveEvent(event: SessionEvent, view?: ToolEventView): void {
     if (this.openState === 'loading' || this.stitching) {
       this.liveBuffer.push({ event, view })
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index 25fade8633..e9e1c1d8d6 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -184,10 +184,10 @@ function compactSummaryDetails(event: SessionEvent): CompactSummaryDetails {
 
 /**
  * One landed checkpoint -> the human-facing compaction marker. The summary text
- * comes from the checkpoint's own provenance (`sourceEventSeqs` names the
+ * comes from the checkpoint's cited `compact/summary` event (`sourceEventSeqs` names the
  * `compact/summary` event), never from the framed checkpoint payload, which is
  * an instruction envelope written for the model. A window cut that left the
- * provenance outside soft-falls to `summary: null` (a non-expandable marker),
+ * summary event outside soft-falls to `summary: null` (a non-expandable marker),
  * the same posture as a call-less tool result.
  */
 function materializeCompaction(
@@ -222,7 +222,7 @@ function materializeCompaction(
 
 /** Log-ordered human transcript over a paged raw event window (never consults surface order). */
 export class TranscriptAdapter {
-  /** Window events by seq: provenance lookup for a checkpoint's summary. */
+  /** Window events by seq, used to find the summary event cited by a checkpoint. */
   private eventIndex = new Map<number, SessionEvent>()
   /** Transcript nodes in log order; copy-on-write so a published array never mutates. */
   private projected: ConversationNode[] = []
diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts
index bc3c10e762..de72d5b351 100644
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -105,7 +105,7 @@ export const ev = {
       ...text === undefined ? {} : { text },
       ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
     } }),
-  /** A compaction's log-only `compact/summary` provenance record. */
+  /** A compaction's log-only `compact/summary` record. */
   compactSummary: (seq: number, summary: string, start: number, end: number): SessionEvent =>
     at(seq, { type: 'compact/summary', data: {
       summary: text(summary),
diff --git a/packages/client/runtime/tests/history-fold.spec.ts b/packages/client/runtime/tests/history-fold.spec.ts
index 37a1060fec..2f15bc9c92 100644
--- a/packages/client/runtime/tests/history-fold.spec.ts
+++ b/packages/client/runtime/tests/history-fold.spec.ts
@@ -12,7 +12,7 @@ const at = (seq: number, event: Record<string, unknown>): SessionEvent =>
 describe('projectConversationHistory', () => {
   it('names an injected context node from its durable source, like the live adapter', () => {
     // The fold declares its own node mapping (jscpd:ignore in the source), so
-    // the provenance projection is pinned on both sides independently.
+    // the source projection is pinned on both sides independently.
     const injected = at(0, {
       type: 'user/message',
       surfaceOp: 'append',
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
index 05dc2855ca..b161046f84 100644
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ b/packages/client/runtime/tests/transcript-adapter.spec.ts
@@ -14,7 +14,7 @@ import { ev, plainTurn } from './event-script.ts'
 const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
   ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
 
-/** A `compact/summary` provenance event (log-only, no surfaceOp). */
+/** A `compact/summary` event (log-only, no surfaceOp). */
 function compactSummary(seq: number, summary: unknown = [{ type: 'text', text: '# 摘要\n\n保留事实' }]): SessionEvent {
   return at(seq, {
     type: 'compact/summary',
@@ -188,7 +188,7 @@ describe('TranscriptAdapter', () => {
 
   it('skips events core does not call surface-eligible, marker or not', () => {
     // The transcript is the append-origin surface, so log-only events (a chunk,
-    // a turn boundary, a compact/* provenance record) and a future type core
+    // a turn boundary, a `compact/*` record) and a future type core
     // has not admitted contribute no node.
     const adapter = new TranscriptAdapter()
     adapter.reset([
@@ -313,7 +313,7 @@ describe('TranscriptAdapter', () => {
     })
 
     it.each([
-      ['absent provenance', undefined],
+      ['absent summary event', undefined],
       ['text-less summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])],
       ['a whitespace-only summary', compactSummary(1, [{ type: 'text', text: '   ' }])],
       ['an empty summary array', compactSummary(1, [])],
@@ -345,7 +345,7 @@ describe('TranscriptAdapter', () => {
       ])
     })
 
-    it('leaves the summary null when the checkpoint records no provenance at all', () => {
+    it('leaves the summary null when the checkpoint cites no source events', () => {
       const adapter = new TranscriptAdapter()
       adapter.reset([at(2, {
         type: 'user/message',
@@ -361,7 +361,7 @@ describe('TranscriptAdapter', () => {
       }])
     })
 
-    it('skips a non-summary provenance seq before reaching the real one', () => {
+    it('skips a cited non-summary seq before reaching the summary event', () => {
       const adapter = new TranscriptAdapter()
       adapter.reset([
         ev.user(0, '被压缩的问题'),
@@ -372,7 +372,7 @@ describe('TranscriptAdapter', () => {
       expect(adapter.nodes().at(-1)).toMatchObject({ kind: 'compaction', summary: '第三个来源才是摘要' })
     })
 
-    it('resolves the summary once an older page supplies the provenance', () => {
+    it('resolves the summary once an older page supplies the cited summary event', () => {
       const adapter = new TranscriptAdapter()
       const landed = checkpoint(8, 7, { start: 0, end: 0, sourceEventSeqs: [7, 0] })
       adapter.reset([landed])
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index c03e330672..341a3409c3 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: f5cf9b72b4f8f4ce7b1a07c0c1e30f5213edf678
-README.zh.md: b3ce1b66308213650505b8838b9b43cb9987c757
+README.md: 58c8dc68758ddae11966195c42cf324e388cfc47
+README.zh.md: f60b89c0ac378f5a87bb49194465fd8bc65d7c42
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index f5cf9b72b4..58c8dc6875 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Conversation domain: skeleton (header/tabs/composer/empty state), chat view (grouped step-summary flow, streaming tail isolation, and turn status), composer dock (session stats sticky with the input), input dock (queue rows plus the todo plan strip), details shell, and scope-addressed ConversationService. Tool presentation belongs to [`ui-tool`](../ui-tool/README.md).
 
-Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Every completed marker with structured summary provenance shows the replaced-item and estimated-token counts and discloses the summary on click. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key. A completed checkpoint keeps the context-compaction icon at rest and replaces it with the collapsed or expanded disclosure only on hover or keyboard focus. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when summary provenance is outside the loaded window, the checkpoint remains visible but non-expandable.
+Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Every completed marker with a loaded `compact/summary` event shows the replaced-item and estimated-token counts and discloses the summary on click. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key. A completed checkpoint keeps the context-compaction icon at rest and replaces it with the collapsed or expanded disclosure only on hover or keyboard focus. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when the cited `compact/summary` event is outside the loaded window, the checkpoint remains visible but non-expandable.
 
 The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
 
@@ -16,7 +16,7 @@ Approvals take over the composer through the chain this package declares: `Appro
 
 The session header declares and renders the session-scoped `'conversation.session.header.actions'` list beside the title, allowing feature plugins to contribute controls without entering the skeleton. The composer chain currency includes the current conversation `session`; ui-subagent selects one-shot or parent-unavailable addressed sessions for reason-specific read-only copy, while the ordinary InputBar keeps every addressed child Send-only because the continuation service exposes no public per-Activation cancellation operation and `session.cancel` would bypass its ownership.
 
-Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The shared `DisclosureRow` primitive gives this context surface the same compact geometry as other flow rows while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state or summary ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
+Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The shared `DisclosureRow` primitive gives this context surface the same compact geometry as other flow rows while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state or summary ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [producer-label decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining source fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
 
 A Think row stays collapsed by default and exposes live reasoning throughput without expanding the chain of thought: while its reasoning block is the streaming tail, the summary switches from the settled first line to the latest non-blank line and its one-line scrollport follows each delta to the inline end. Expanding the row removes the moving summary and leaves the full reasoning in ordinary page flow, so page reading never fights an internal follower; settlement restores the stable first-line summary at the left edge ([decision](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)).
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index b3ce1b6630..f60b89c0ac 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -4,7 +4,7 @@
 
 会话领域：骨架（标题栏／标签页／编辑器／空状态）、聊天视图（分组步骤摘要流、流式尾部隔离与轮次状态）、编辑器 dock（与输入区一同 sticky 的会话统计行）、输入区 dock（队列行加 todo 计划条）、详情壳层，以及按 scope 寻址的 ConversationService。Tool 展示属于 [`ui-tool`](../ui-tool/README.md)。
 
-压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。每个具备结构化摘要溯源的完成标记都会显示被替换条目数量和估算 token 数量，并可点击展开摘要。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；摘要溯源位于已加载窗口之外时，检查点仍然可见但不可展开。
+压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。每个已加载对应 `compact/summary` 事件的完成标记都会显示被替换条目数量和估算 token 数量，并可点击展开摘要。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行。完成的检查点静止时保留上下文压缩图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；被引用的 `compact/summary` 事件位于已加载窗口之外时，检查点仍然可见但不可展开。
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
@@ -14,7 +14,7 @@
 
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 
-已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。共享的 `DisclosureRow` 原子组件让该上下文界面与消息流中的其他紧凑行保持相同几何，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态或摘要（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
+已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。共享的 `DisclosureRow` 原子组件让该上下文界面与消息流中的其他紧凑行保持相同几何，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态或摘要（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[生产者标签决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源字段列出。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 
diff --git a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
index 5bd5a081cf..0995149e67 100644
--- a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
@@ -3,7 +3,7 @@
 // marker reports where the model stopped seeing that history — it never
 // replaces it. The framed checkpoint payload is written for the model and is
 // not rendered; the disclosure shows the summary from the checkpoint's own
-// provenance, and a window cut that left that provenance outside makes the row
+// cited `compact/summary` event, and a window cut that left that event outside makes the row
 // non-expandable rather than empty.
 
 import { memo, useState } from 'react'
diff --git a/packages/client/ui-conversation/src/client/chat/ContextBody.module.css b/packages/client/ui-conversation/src/client/chat/ContextBody.module.css
index c1f6f5361b..3ed07752bc 100644
--- a/packages/client/ui-conversation/src/client/chat/ContextBody.module.css
+++ b/packages/client/ui-conversation/src/client/chat/ContextBody.module.css
@@ -9,7 +9,7 @@
   overflow-wrap: anywhere;
 }
 
-/* Provenance beneath the text: dimmer than the content it describes. */
+/* Source fields beneath the text: dimmer than the content they describe. */
 .fields {
   display: flex;
   flex-direction: column;
diff --git a/packages/client/ui-conversation/src/client/chat/ContextBody.tsx b/packages/client/ui-conversation/src/client/chat/ContextBody.tsx
index 6af65bcdb9..3bbf9a842f 100644
--- a/packages/client/ui-conversation/src/client/chat/ContextBody.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ContextBody.tsx
@@ -66,7 +66,7 @@ function boundedText(text: string, t: Translate): string {
 
 /**
  * One source field rendered as a value row; nested shapes stay compact JSON.
- * Bounded on its own, because provenance is as unbounded as the text: an unknown
+ * Bounded on its own, because source fields are as unbounded as the text: an unknown
  * producer may record an arbitrarily large string or array.
  */
 function fieldValue(value: unknown, t: Translate): string {
@@ -77,7 +77,7 @@ function fieldValue(value: unknown, t: Translate): string {
 }
 
 /**
- * Provenance fields as a key/value list. `kind` is always omitted because the
+ * Source fields as a key/value list. `kind` is always omitted because the
  * row header already names the producer. `form` is omitted only when a
  * dedicated body rendered for it — then the presentation the reader is looking
  * at IS that value. On the opaque fallback the declaration is kept, because
@@ -159,7 +159,7 @@ function ModelFacingContent({ content, t }: {
 
 /**
  * Default presentation: the model-facing text as text, with its real line
- * breaks, and the remaining provenance beneath it. This is what every form
+ * breaks, and the remaining source fields beneath it. This is what every form
  * this UI version does not recognize renders as.
  * @param props - Durable content, its source, and the locale seat.
  * @returns The opaque context body.
@@ -428,7 +428,7 @@ export function NoticeBody({ content, t }: {
 /**
  * `relay` form: which agent sent this, then what it said.
  *
- * The sender is an opaque session id; it is shown as provenance rather than a
+ * The sender is an opaque session id; it is shown as a field rather than a
  * label, because this client cannot resolve it to a title.
  * @param props - Durable content, its source, and the locale seat.
  * @returns The relay context body.
diff --git a/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx b/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx
index 1afdad37f1..889b15b085 100644
--- a/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx
@@ -25,7 +25,7 @@ export interface ContextInjectionRowProps {
  * from a workspace instruction file or a recalled session without expanding.
  * The expanded body follows the producer-declared form; an absent or unknown
  * form renders the opaque body.
- * @param props - Durable content, its projected provenance and form, and the locale seat.
+ * @param props - Durable content, its projected producer role/name and form, and the locale seat.
  * @returns A collapsed context row with a bounded, form-specific body.
  */
 export function ContextInjectionRow({ content, source, provenance, form, t }: ContextInjectionRowProps) {
diff --git a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
index 41cbd61afc..0362c3ee4b 100644
--- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
@@ -226,7 +226,7 @@ describe('MessageItem arms', () => {
     expect(disclosure.getAttribute('aria-expanded')).toBe('true')
     // An unknown form renders the opaque body: the model-facing text keeps its
     // real line breaks instead of being escaped into one JSON line, and the
-    // remaining provenance follows it as fields.
+    // remaining source data follows it as fields.
     expect(ctxView.container.querySelector('[data-context-text]')?.textContent)
       .toBe('line one\n\nline two')
     const fields = [...ctxView.container.querySelectorAll('[data-context-fields] dt')].map(node => node.textContent)
@@ -418,7 +418,7 @@ describe('MessageItem arms', () => {
     expect(view.container.querySelector('[data-context-text]')?.textContent).toBe('firstsecond')
   })
 
-  it('bounds an oversized provenance field, not only the model-facing text', () => {
+  it('bounds an oversized source field, not only the model-facing text', () => {
     const view = render(
       <MessageItem t={t} node={{
         kind: 'context',
@@ -708,7 +708,7 @@ describe('MessageItem arms', () => {
     expect(row.getAttribute('aria-expanded')).toBe('false')
   })
 
-  it('a marker whose provenance fell outside the window is not expandable', () => {
+  it('a marker whose cited summary event fell outside the window is not expandable', () => {
     const view = render(<MessageItem t={t} node={{
       kind: 'compaction', seq: 6, time: 1_000, summary: null,
       summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
diff --git a/packages/client/ui-primitives/tests/markdown-dom-parity.spec.tsx b/packages/client/ui-primitives/tests/markdown-dom-parity.spec.tsx
index c1b4eb2f2f..70197763da 100644
--- a/packages/client/ui-primitives/tests/markdown-dom-parity.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown-dom-parity.spec.tsx
@@ -7,7 +7,7 @@
 // change and must be reviewed as such — never re-record to silence a
 // refactor.
 //
-// Provenance is reproducible: the replaced pipeline last lived at commit
+// The fixture source is reproducible: the replaced pipeline last lived at commit
 // 9e8101b800 (origin/master before the renderer swap merged). Checking out
 // that ref in a worktree, copying this spec, and running it records all
 // fixtures from react-markdown byte-identical to the ones committed here:
diff --git a/packages/client/ui-trajectory/src/client/context-branches.ts b/packages/client/ui-trajectory/src/client/context-branches.ts
index bc5b74057b..2501511c50 100644
--- a/packages/client/ui-trajectory/src/client/context-branches.ts
+++ b/packages/client/ui-trajectory/src/client/context-branches.ts
@@ -12,7 +12,7 @@ export interface TrajectoryContextBranch {
   contexts: readonly ConversationContext[]
   latest: ConversationContext
   nodes: readonly ConversationNode[]
-  /** Seq that opened this branch; earlier requests require retained surface provenance. */
+  /** Seq that opened this branch; earlier requests require retained cited surface events. */
   startSeq: number
   /** Exact pre-rewind surface records inherited by this branch. */
   retainedSurfaceSeqs: ReadonlySet<number>
@@ -101,7 +101,7 @@ export function deriveTrajectoryContextBranches(
 
 /**
  * Test whether a provider request belongs to one rewind branch.
- * @param branch - Branch carrying exact inherited surface provenance.
+ * @param branch - Branch carrying the exact inherited surface event seqs.
  * @param request - Provider request to classify.
  * @returns Whether the request began on this branch or produced a retained surface record.
  */
diff --git a/packages/client/ui-trajectory/src/client/trajectory-record.ts b/packages/client/ui-trajectory/src/client/trajectory-record.ts
index a979278f3f..2c3f2a1a83 100644
--- a/packages/client/ui-trajectory/src/client/trajectory-record.ts
+++ b/packages/client/ui-trajectory/src/client/trajectory-record.ts
@@ -46,7 +46,7 @@ export interface TrajectoryCellProps extends HTMLAttributes<HTMLDivElement> {
   opensTurn?: boolean
   /** Source session-event seq for cross-record navigation. */
   sourceSeq?: number
-  /** Producer provenance from a user-role message or context injection. */
+  /** Producer role and name from a user-role message or context injection. */
   messageSource?: unknown
   /** Producer-owned model-hidden metadata carried beside the message source. */
   /** A separator-only anchor for an auxiliary request with no visible record. */
diff --git a/packages/compact/compact-basic/README.i18n.yaml b/packages/compact/compact-basic/README.i18n.yaml
index 61b6e4e6fb..c01b9166b5 100644
--- a/packages/compact/compact-basic/README.i18n.yaml
+++ b/packages/compact/compact-basic/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/compact/compact-basic/README.md
-README.md: 4241899788998a744801bb0406a15ecd70af6401
-README.zh.md: c1df4afaa1837a3b689da80cc1b49df43f60e513
+README.md: 5395219147e8932c8e5874e84e534a2c2fe33d53
+README.zh.md: 59479b26c5c8cf27e6ac84814c09f14ecbf9662c
diff --git a/packages/compact/compact-basic/README.md b/packages/compact/compact-basic/README.md
index 4241899788..5395219147 100644
--- a/packages/compact/compact-basic/README.md
+++ b/packages/compact/compact-basic/README.md
@@ -16,12 +16,12 @@ This backend owns the compaction policy:
 - **Retention** — compact the oldest whole surface units while preserving a recent tail and balanced tool-call/result cuts through the [`dsh-compact` boundary helpers](../compact/README.md#tool-pairing-boundaries). Turn boundaries do not protect old steps inside a runaway turn. An open indivisible tail declines until it closes. The optional pruner can repair an oversized closed tool unit when its text-bearing result is the removable bulk; indivisible non-tool units and non-prunable tool remainders remain out of scope.
 - **Convergence** — retry head-checkpoint compaction up to `compactionRetries`; reject a summary that does not shrink its source, and throw if retries cannot return below threshold.
 - **Summarization** — a direct `llm/stream` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the agent target, without running the loop-only `agent/request` seam. The call replays the conversation's own system prompt, tools, and shadowed-region messages verbatim and appends the compaction instruction as the final user message, so it reuses the provider's warm prefix cache instead of invalidating it. It sets `GenerateOptions.purpose` to `compaction`, which adapters may forward as request attribution (the DeepSeek adapter sends `x-deepseek-harness-compact: 1`) without touching the model-visible body. Only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
-- **Framing** — the replacement user message marks established checkpoint context with `<compacted-summary>` tags. The raw summary remains on the provenance event, and later automatic cycles merge the prior checkpoint.
-- **Lifecycle** — all entry points share one bracket-first region transaction. It validates the range and live lock, appends `compact/start` synchronously, prepares and awaits the summary, revalidates, appends provenance plus the replacement, and makes exactly one closing attempt. Automatic and explicit-region calls require a numeric open-turn owner and whole-surface stability; the serial `agent/pre-step` listener checks pressure before request derivation, while canonical provider overflow enters through `agent/request-error` and authorizes retry only after durable surface progress. `compactNow()` reserves idle admission, uses `turn: null`, accepts append-only context outside its selected span, flushes every closed attempt, and releases admission in `finally`.
+- **Framing** — the replacement user message marks established checkpoint context with `<compacted-summary>` tags. The raw summary remains on the `compact/summary` event, and later automatic cycles merge the prior checkpoint.
+- **Lifecycle** — all entry points share one bracket-first region transaction. It validates the range and live lock, appends `compact/start` synchronously, prepares and awaits the summary, revalidates, appends `compact/summary` plus the replacement, and makes exactly one closing attempt. Automatic and explicit-region calls require a numeric open-turn owner and whole-surface stability; the serial `agent/pre-step` listener checks pressure before request derivation, while canonical provider overflow enters through `agent/request-error` and authorizes retry only after durable surface progress. `compactNow()` reserves idle admission, uses `turn: null`, accepts append-only context outside its selected span, flushes every closed attempt, and releases admission in `finally`.
 - **Overflow recovery** — provider-confirmed overflow needs no capacity metadata: it bypasses normal pressure and retention, prunes, then attempts one maximal balanced head reduction while leaving the newest indivisible unit. Retry is authorized whenever `surface.replaceGeneration` advances, including when pruning lands before later summary work throws. No replacement, an exhausted target-specific cap, cancellation, or an unknown/noncanonical error preserves the original provider failure.
 - **Failure handling** — a live unmatched `compact/start` is the durable lock. An unmatched marker before a newer `session/end-seed` is stale evidence from a prior lifecycle and does not block; one after that boundary reports `busy`. Summary and changed-span failures close with an error and leave the conversation surface untouched, though the attempt remains in the log. A failed close deliberately leaves a blocking orphan. Operational pressure failures warn and continue, while overflow-recovery failure preserves the original provider error only when no earlier replacement advanced the surface. Cancellation remains authoritative after cleanup and durability.
 
-The protected `summarize()` method is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, provenance, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the safe summary plus the complete provider output, call envelope, and usage when available (`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`); `llmStreamCall: true` means producing that result consumed exactly one call through this context's `ctx.llm.stream()` and requires complete `rawOutput`, while unmarked `rawOutput` does not identify the call path. The transaction preserves those fields on `compact/summary`.
+The protected `summarize()` method is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, cited source events, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the safe summary plus the complete provider output, call envelope, and usage when available (`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`); `llmStreamCall: true` means producing that result consumed exactly one call through this context's `ctx.llm.stream()` and requires complete `rawOutput`, while unmarked `rawOutput` does not identify the call path. The transaction preserves those fields on `compact/summary`.
 
 ## Config (`BasicCompactConfig`)
 
diff --git a/packages/compact/compact-basic/README.zh.md b/packages/compact/compact-basic/README.zh.md
index c1df4afaa1..59479b26c5 100644
--- a/packages/compact/compact-basic/README.zh.md
+++ b/packages/compact/compact-basic/README.zh.md
@@ -16,12 +16,12 @@
 - **保留**：压缩最旧的完整表层单元，同时保留近期尾部，并通过 [`dsh-compact` 边界 helper](../compact/README.md#tool-pairing-boundaries) 将切分点调整到工具调用／结果配对平衡的位置。轮次边界不会保护失控轮次内的旧步骤。尚未闭合且不可分的尾部会在闭合前拒绝压缩。当闭合的超大工具单元以文本型结果为可移除主体时，可选 pruner 可以修复它；不可分的非工具单元与不可剪枝的工具剩余部分不在范围内。
 - **收敛**：最多按 `compactionRetries` 重试头部检查点压缩；拒绝不能缩小源内容的摘要，如果重试仍无法回到阈值以下，则抛出异常。
 - **摘要**：直接 `llm/stream` 调用使用已配置的提供方／模型对与上限，回退到最新已记录请求目标，然后再回退到 agent 目标，而不运行仅用于 agent loop 的 `agent/request` seam。该调用会逐字回放会话自身的系统提示词、工具与已遮蔽区域消息，并将压缩指令作为最后一条 user 消息追加，从而复用提供方的热前缀 cache，而非使它失效。它将 `GenerateOptions.purpose` 设为 `compaction`，适配器可将其作为请求归因转发（DeepSeek 适配器发送 `x-deepseek-harness-compact: 1`），但不会触碰模型可见的请求体。只有返回的文本会进入检查点；推理（reasoning）和工具调用都会被排除，以免泄露私有推理或产生遗留调用。
-- **框定**：替换 user 消息使用 `<compacted-summary>` 标签标记已建立的检查点上下文。原始摘要保留在溯源事件上，后续自动周期会合并之前的检查点。
-- **生命周期**：所有入口点共享一个先记录标记的区域事务。它会验证范围与活动锁，同步追加 `compact/start`，准备并等待摘要，重新验证，再追加溯源信息和替换，最后恰好进行一次闭合尝试。自动调用和显式范围调用要求数字标识的开放轮次归属，并要求整个表层保持稳定；串行 `agent/pre-step` listener 会在派生请求之前检查压力，而规范提供方溢出则经由 `agent/request-error` 进入，并且只在表层取得持久进展后才允许重试。`compactNow()` 会预留空闲接纳，使用 `turn: null`，允许所选 span 之外追加仅追加上下文，flush 每次已闭合尝试，并在 `finally` 中释放接纳预留。
+- **框定**：替换 user 消息使用 `<compacted-summary>` 标签标记已建立的检查点上下文。原始摘要保留在 `compact/summary` 事件上，后续自动周期会合并之前的检查点。
+- **生命周期**：所有入口点共享一个先记录标记的区域事务。它会验证范围与活动锁，同步追加 `compact/start`，准备并等待摘要，重新验证，再追加 `compact/summary` 和替换，最后恰好进行一次闭合尝试。自动调用和显式范围调用要求数字标识的开放轮次归属，并要求整个表层保持稳定；串行 `agent/pre-step` listener 会在派生请求之前检查压力，而规范提供方溢出则经由 `agent/request-error` 进入，并且只在表层取得持久进展后才允许重试。`compactNow()` 会预留空闲接纳，使用 `turn: null`，允许所选 span 之外追加仅追加上下文，flush 每次已闭合尝试，并在 `finally` 中释放接纳预留。
 - **溢出恢复**：提供方已确认的溢出不需容量元数据。它会绕过常规压力与保留，执行剪枝，再尝试一次最大平衡头部缩减，并留下最新不可分单元。只要 `surface.replaceGeneration` 前进，就允许重试，包括剪枝在后续摘要工作抛出异常前已落地的情况。如果没有替换、目标特定上限已耗尽、已取消，或遇到未知／非规范错误，则保留原始提供方失败。
 - **失败处理**：活动的未匹配 `compact/start` 是持久锁。位于较新 `session/end-seed` 之前的未匹配标记，是先前生命周期留下的陈旧证据，不会阻塞；位于该边界之后的标记报告 `busy`。摘要和 span 变更失败会以错误闭合，并保持会话表层不变，但日志中仍保留该尝试。闭合失败会有意留下阻塞性的未匹配标记。压力检查中的运行故障会发出警告并继续；只有此前没有替换推进表层时，溢出恢复失败才保留原始提供方错误。完成清理与持久化后，取消仍具有最终决定权。
 
-受保护的 `summarize()` 方法是唯一的子类钩子。基于模板或远程摘要器的子类可以覆盖该方法，同时压力、保留、溯源、缩减验证与已遮蔽 token 计量仍由 `ctx.tokenMeter` 负责。钩子返回安全摘要，以及完整提供方输出、调用 envelope 和可用时的 usage（`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`）；`llmStreamCall: true` 表示生成该结果时恰好通过此上下文的 `ctx.llm.stream()` 发起了一次调用，且必须提供完整的 `rawOutput`；未带标记的 `rawOutput` 并不能判定调用路径。事务会在 `compact/summary` 上保留这些字段。
+受保护的 `summarize()` 方法是唯一的子类钩子。基于模板或远程摘要器的子类可以覆盖该方法，同时压力、保留、被引用的源事件、缩减验证与已遮蔽 token 计量仍由 `ctx.tokenMeter` 负责。钩子返回安全摘要，以及完整提供方输出、调用 envelope 和可用时的 usage（`{ summary, rawOutput?, llmStreamCall?, provider, model, maxTokens?, usage? }`）；`llmStreamCall: true` 表示生成该结果时恰好通过此上下文的 `ctx.llm.stream()` 发起了一次调用，且必须提供完整的 `rawOutput`；未带标记的 `rawOutput` 并不能判定调用路径。事务会在 `compact/summary` 上保留这些字段。
 
 ## 配置（`BasicCompactConfig`）
 
diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts
index 211ac8a920..27b59d0451 100644
--- a/packages/compact/compact-basic/src/index.ts
+++ b/packages/compact/compact-basic/src/index.ts
@@ -93,7 +93,7 @@ const modelPolicy: z<ModelCompactPolicyConfig> = z.object({
 
 /**
  * Dependency-light compaction backend using `ctx.tokenMeter` for pressure,
- * retention, provenance, and summary-convergence pricing.
+ * retention, cited source events, and summary-convergence pricing.
  *
  * `summarize()` is the sole subclass customization hook; the replay and durable
  * mutation strategy stays fixed so every pricing decision uses the singleton
@@ -230,7 +230,7 @@ export class BasicCompactService extends CompactService {
    * @param input - replayed conversation prefix (system, tools, and leading messages) to condense.
    * @param agent - supplies routed-model history, fallback model, and session id.
    * @param signal - optional cancellation forwarded to the adapter.
-   * @returns safe text summary blocks and exact auxiliary-call provenance.
+   * @returns safe text summary blocks and the exact auxiliary call envelope and output.
    */
   protected async summarize(
     input: SummarizationInput,
diff --git a/packages/compact/compact-basic/src/region.ts b/packages/compact/compact-basic/src/region.ts
index 352603579b..b220074e02 100644
--- a/packages/compact/compact-basic/src/region.ts
+++ b/packages/compact/compact-basic/src/region.ts
@@ -403,7 +403,7 @@ function assertSelectedSpanStable(
   }
 }
 
-/** Append one already-summarized provenance and replacement body without yielding. */
+/** Append one completed summary record and replacement body without yielding. */
 function commitCompactionBody(
   session: Session,
   startEvent: SessionEvent<'compact/start'>,
diff --git a/packages/compact/compact-basic/src/summarizer.ts b/packages/compact/compact-basic/src/summarizer.ts
index 8113dcd439..bed4dedb69 100644
--- a/packages/compact/compact-basic/src/summarizer.ts
+++ b/packages/compact/compact-basic/src/summarizer.ts
@@ -84,7 +84,7 @@ export interface SummarizationInput {
   readonly messages: readonly Message[]
 }
 
-/** Safe summary content plus the exact auxiliary call envelope recorded in provenance. */
+/** Safe summary content plus the exact auxiliary call envelope recorded with it. */
 export type SummaryResult = {
   summary: ContentBlock[]
   provider: string
@@ -116,7 +116,7 @@ export type SummaryResult = {
  * @param input - replayed conversation prefix (system, tools, and leading messages) to condense.
  * @param agent - supplies routed-model history, fallback model, and session id.
  * @param signal - optional cancellation forwarded to the adapter.
- * @returns safe text-only summary blocks and exact call provenance.
+ * @returns safe text-only summary blocks and the exact call envelope and output.
  */
 export async function summarizeWithLlm(
   ctx: Context,
diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts
index 0e74a77e04..996d5d61e1 100644
--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -838,7 +838,7 @@ describe('optional model-free tool-result pruning', () => {
 })
 
 describe('compaction region transaction', () => {
-  it('lands a framed, replayable checkpoint with exact pricing provenance', async () => {
+  it('lands a framed, replayable checkpoint with exact source seqs and token price', async () => {
     const compact = service()
     compact.rawOutput = [
       { type: 'reasoning', text: 'private compact thought' },
diff --git a/packages/compact/compact-basic/tests/manual-compact.spec.ts b/packages/compact/compact-basic/tests/manual-compact.spec.ts
index d2dcda461e..7544c3223b 100644
--- a/packages/compact/compact-basic/tests/manual-compact.spec.ts
+++ b/packages/compact/compact-basic/tests/manual-compact.spec.ts
@@ -618,7 +618,7 @@ describe('compactNow transaction and failure classification', () => {
     const agent = fakeAgent(session, () => () => { released += 1 })
     const append = session.append.bind(session)
     vi.spyOn(session, 'append').mockImplementation(((type: string, ...rest: never[]) => {
-      if (type === 'compact/summary') throw new Error('provenance rejected')
+      if (type === 'compact/summary') throw new Error('summary record rejected')
       return (append as (...args: never[]) => unknown)(type as never, ...rest)
     }) as never)
 
@@ -627,7 +627,7 @@ describe('compactNow transaction and failure classification', () => {
     expect(error.code).toBe('commit')
     expect(released).toBe(1)
     const end = session.events.findLast(event => event.type === 'compact/end')
-    expect(end?.type === 'compact/end' && end.data.error).toContain('provenance rejected')
+    expect(end?.type === 'compact/end' && end.data.error).toContain('summary record rejected')
     expect(end?.type === 'compact/end' && end.data.turn).toBeNull()
   })
 
@@ -637,14 +637,14 @@ describe('compactNow transaction and failure classification', () => {
     const agent = fakeAgent(session, () => () => undefined)
     const append = session.append.bind(session)
     vi.spyOn(session, 'append').mockImplementation(((type: string, ...rest: never[]) => {
-      if (type === 'compact/summary') throw new Error('provenance rejected')
+      if (type === 'compact/summary') throw new Error('summary record rejected')
       return (append as (...args: never[]) => unknown)(type as never, ...rest)
     }) as never)
     vi.spyOn(ctx.sessions, 'flush').mockRejectedValueOnce(new Error('disk full'))
 
     const error = await rejection(compact.compactNow(agent, SIGNAL))
     expect(error.code).toBe('commit')
-    expect(causeOf(error).message).toBe('provenance rejected')
+    expect(causeOf(error).message).toBe('summary record rejected')
     vi.restoreAllMocks()
   })
 
diff --git a/packages/compact/compact-tool-result-prune/src/index.ts b/packages/compact/compact-tool-result-prune/src/index.ts
index f783cdd59d..48e3ee308b 100644
--- a/packages/compact/compact-tool-result-prune/src/index.ts
+++ b/packages/compact/compact-tool-result-prune/src/index.ts
@@ -124,7 +124,7 @@ export class ToolResultPruneService extends Service {
   /**
    * Prune every over-budget tool result from one stable current-surface snapshot.
    * Each replacement preserves the complete event data except for `content`,
-   * points at the shadowed node for durable provenance and replay, and is
+   * cites the shadowed node so replay can recover the replacement input, and is
    * immediately preceded by a `compact/prune` shadow-price event pricing the
    * shadowed node through the injected token meter, so pure consumers can
    * subtract it without per-node state.
diff --git a/packages/compact/compact-tool-result-prune/src/types.ts b/packages/compact/compact-tool-result-prune/src/types.ts
index f9dd846f35..13544b163e 100644
--- a/packages/compact/compact-tool-result-prune/src/types.ts
+++ b/packages/compact/compact-tool-result-prune/src/types.ts
@@ -17,7 +17,7 @@ export interface ResolvedConfig {
   readonly tailChars: number
 }
 
-/** Provenance and size accounting for one landed surface replacement. */
+/** Cited source event and size accounting for one landed surface replacement. */
 export interface PrunedEntry {
   /** Full-fidelity tool-result event shadowed by the replacement. */
   readonly originalSeq: number
diff --git a/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts b/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts
index c5c7171c08..69a28eb123 100644
--- a/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts
+++ b/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts
@@ -159,7 +159,7 @@ describe('ToolResultPruneService content transform', () => {
 })
 
 describe('ToolResultPruneService session transaction', () => {
-  it('prunes a stable snapshot, preserves all data, and records provenance', () => {
+  it('prunes a stable snapshot, preserves all data, and cites the replaced result', () => {
     const session = Session.create(SessionId('preserve'))
     const originalSeq = appendToolStep(session, 1, 'one', [{
       type: 'text',
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index dc2254d647..c5045934c9 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: 2bf39cac91798b1e0fdb679d2a9b674caceffe22
-README.zh.md: d068869f1d9091e9671d8c2fb17df53a48c9916d
+README.md: c32be20117abfe15e278082089c5fd87828c81ef
+README.zh.md: 530b1ca30061956fbe37a4b4b90fed99c02e5a7f
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index 2bf39cac91..c32be20117 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -42,7 +42,7 @@ The private per-session cache is keyed by `session.surface.replaceGeneration` an
 
 1. appends `compact/start` (log-only) — acquires the lock,
 2. summarizes the range,
-3. appends `compact/summary` (log-only) — provenance: summary, range, shadowed seqs, token count, and provider/model call envelope,
+3. appends `compact/summary` (log-only) with the summary, range, shadowed seqs, token count, and provider/model call envelope,
 4. appends a single `user/message` with `source: COMPACT_CHECKPOINT_SOURCE` and `surfaceOp: { op: 'replace', start, end }` carrying the summary — **the only surface mutation in this operation**,
 5. appends `compact/end` (log-only) — releases the lock.
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index d068869f1d..530b1ca300 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -42,7 +42,7 @@
 
 1. 追加 `compact/start`（仅日志）：获取锁；
 2. 摘要该范围；
-3. 追加 `compact/summary`（仅日志）：溯源信息包括摘要、范围、已遮蔽 seq、token 数与提供方／模型调用 envelope；
+3. 追加 `compact/summary`（仅日志），其中记录摘要、范围、已遮蔽 seq、token 数与提供方／模型调用 envelope；
 4. 追加单个 `user/message`，其携带 `source: COMPACT_CHECKPOINT_SOURCE` 和包含摘要的 `surfaceOp: { op: 'replace', start, end }`：这是**本操作唯一的表层变更**；
 5. 追加 `compact/end`（仅日志）：释放锁。
 
diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index c235507c6a..4429e8b291 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -1,6 +1,6 @@
 /**
  * Compaction vocabulary: the result type and the `compact/*` session events.
- * Those declaration-merged events are log-only lock/provenance markers, not
+ * Those declaration-merged events record the lock and summary inputs without entering the surface, so they are not
  * surface events; a separate replacement `user/message` carries the summary.
  * Backend packages own configuration and retention policy; see
  * `.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md`.
@@ -18,7 +18,7 @@ declare module '@deepseek-ai/dsh-session' {
      */
     'compact/start': { turn: number | null }
     /**
-     * Provenance record of a completed summarization — log-only, no surfaceOp.
+     * Completed summary, its inputs, and its model call facts — log-only, no surfaceOp.
      * The summary content is in `data.summary`; the actual surface replacement
      * is performed by the immediately following `user/message` event that
      * shadows the compacted range. That adjacency is contractual — the
diff --git a/packages/context/session-reference/src/types.ts b/packages/context/session-reference/src/types.ts
index 0693e0d212..e1eff84244 100644
--- a/packages/context/session-reference/src/types.ts
+++ b/packages/context/session-reference/src/types.ts
@@ -3,7 +3,7 @@
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionId, UserMessage } from '@deepseek-ai/dsh-session'
 
-/** Durable provenance for one prepared cross-session context. */
+/** Durable source session, cited event seqs, and snapshot facts for prepared cross-session context. */
 export interface SessionReferenceSource {
   kind: 'session-reference'
   /** Material lifted out of another session's log (`recall` context form). */
diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts
index f302e48363..20343c9512 100644
--- a/packages/context/workspace-context/src/state.ts
+++ b/packages/context/workspace-context/src/state.ts
@@ -33,7 +33,7 @@ import {
 
 export const name = 'workspace-context'
 
-/** Durable provenance and reconciliation facts for one workspace context. */
+/** Durable producer, file, and reconciliation facts for one workspace context. */
 export interface WorkspaceInstructionSource {
   kind: 'workspace-instructions'
   /** Every workspace context carries instructions read out of a file (the `instructions` context form). */
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index c8a81c8d13..9eb0eb4921 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/core/agent-loop/README.md
-README.md: 81bc4411977f7335defef5af82d4a67a740b2ed5
-README.zh.md: 22f9655d46c4c9764118f05cc919be26a471c00b
+README.md: 608a21a2f00545bbc03f675ee2f76034624bb10d
+README.zh.md: fc23c6cb0645c88f2e081a5dbb81dface8c553d6
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 81bc441197..608a21a2f0 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -63,9 +63,9 @@ Every inbox mutation publishes one normalized `agent/inbox/spliced` event before
 
 The driver owns one agent for its lifetime and runs inside `ctx.agents.withInitiator(agent, ...)`. Package-private orchestration entry points recover the exact Agent, derive `agent.session` once, and let operation-local helpers capture it instead of forwarding the concrete driver or per-operation `Session` through shallow interfaces. A helper keeps an explicit `Session` when that is its actual interface, while creation, persistence load, unpublished setup, services, workers, processes, persistence, and wire protocols retain their explicit identities. The [agent service](../agent/README.md#initiating-agent-scope) owns propagation, teardown, and detached-work rules.
 
-Every provider call that reaches a successful finish appends exactly one `assistant/message` completion anchor, including content-less calls and `max-tokens` finishes. The anchor records the assembled content as-is, retains exact chunk provenance (`[]` for a stream with no chunks), and includes usage when available; empty content stays out of derived message history.
+Every provider call that reaches a successful finish appends exactly one `assistant/message` completion anchor, including content-less calls and `max-tokens` finishes. The anchor records the assembled content as-is, lists the exact chunk seqs in `sourceEventSeqs` (`[]` for a stream with no chunks), and includes usage when available; empty content stays out of derived message history.
 
-After `agent/request` returns a provider/model call config, the loop asks `ctx.llm.prepareCall()` to validate adapter-owned fields and materialize configured reasoning-effort and output-token defaults under the active turn signal. The prepared call retains the exact adapter registration across this asynchronous resolution, `request/header` logging, and terminal dispatch, so HMR cannot mix one adapter's capability result with another adapter's request. The header records the effective config and which fields came from the adapter. Before the next waterfall, the loop removes those marked fields from the proposal so the current exact route rematerializes its own defaults; unmarked explicit settings persist across steps and route changes. A route with no registered adapter preserves the proposed config so an `llm/stream` listener can own and short-circuit it; unhandled terminal dispatch still fails with `NO_ADAPTER`. A new loop instance applies the same provenance rule when resuming.
+After `agent/request` returns a provider/model call config, the loop asks `ctx.llm.prepareCall()` to validate adapter-owned fields and materialize configured reasoning-effort and output-token defaults under the active turn signal. The prepared call retains the exact adapter registration across this asynchronous resolution, `request/header` logging, and terminal dispatch, so HMR cannot mix one adapter's capability result with another adapter's request. The header records the effective config and which fields came from the adapter. Before the next waterfall, the loop removes those marked fields from the proposal so the current exact route rematerializes its own defaults; unmarked explicit settings persist across steps and route changes. A route with no registered adapter preserves the proposed config so an `llm/stream` listener can own and short-circuit it; unhandled terminal dispatch still fails with `NO_ADAPTER`. A new loop instance follows the same adapter-default marker rule when resuming.
 
 Plugin failure ends the current turn, not the loop. Final adapter selection, dispatch, and iteration failures arrive from `ctx.llm` as terminal error or aborted finishes and enter `agent/request-error`; middleware, result processing, tools, and other extension failures remain thrown and close directly. Recovery receives request coordinates, immutable provider facts, the immutable retry policy captured by the prepared adapter registration, and the turn signal; the policy is absent when middleware owns an unprepared route. A handling listener returns `{ kind: 'retry' }`; an unhandled failure is terminal. AgentLoop owns one cancellation signal for the current admission or turn. An effective `cancel(cause)` clears pending work unless `keepInbox` is set and cooperatively aborts that signal; idle cancellation is a no-op. Waking input that lands after the abort fires but before the activity converges to idle is latched (`wakeRequested`) and replayed at the driver's own convergence boundary, so it runs without a further waking send; a `disposed` cancel never latches, and a wake submitted while already idle always opens its turn boundary (status shows a transient `idle → running → idle` pair even when the message was cleared). Durable `turn/end` records `aborted` for `user` and `parent`, while disposal records `disposed`; undispatched model tool calls receive synthetic `tool/call` and `ABORTED_BEFORE_DISPATCH` result pairs. The cancellation cause changes reporting, not how result context finalized after cancellation is handled. Disposal waits for signal-ignoring work before registry removal. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) and the [cancel-convergence wake latch](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md) own the lifecycle and race contract.
 
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index 22f9655d46..fc23c6cb06 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -63,9 +63,9 @@ interface Config {
 
 驱动器在其整个生命周期内拥有一个 agent，并在 `ctx.agents.withInitiator(agent, ...)` 内运行。包私有的编排入口点会恢复确切的 Agent，一次性派生 `agent.session`，并让操作局部的辅助函数捕获它，而不是通过浅层接口继续传递具体驱动器或每次操作的 `Session`。如果显式 `Session` 正是辅助函数的实际接口，该辅助函数会保留它；创建、持久化加载、未发布 setup、服务、worker、进程、持久化和 wire 协议则继续保留各自的显式身份。[agent 服务](../agent/README.md#initiating-agent-scope)规定传播、teardown 和分离工作规则。
 
-每次提供方调用成功结束时，都会恰好追加一个 `assistant/message` 完成锚点，包括无内容调用和以 `max-tokens` 结束的调用。该锚点原样记录组装后的内容，保留确切的分片溯源（流没有分片时为 `[]`），并在用量可用时包含用量；空内容不会进入派生消息历史。
+每次提供方调用成功结束时，都会恰好追加一个 `assistant/message` 完成锚点，包括无内容调用和以 `max-tokens` 结束的调用。该锚点原样记录组装后的内容，在 `sourceEventSeqs` 中列出确切的分片 seq（流没有分片时为 `[]`），并在用量可用时包含用量；空内容不会进入派生消息历史。
 
-在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的字段，并填入配置的推理（reasoning）强度和输出 token 默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。请求 header 会记录生效配置以及哪些字段来自适配器。下一次 waterfall（瀑布式事件）前，循环会从提议中移除这些带标记字段，使当前精确路由重新填入自身默认值；未带标记的显式设置会跨步骤和路由变化保留。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例在恢复时会应用同一来源规则。
+在 `agent/request` 返回提供方／模型调用配置后，循环会调用 `ctx.llm.prepareCall()`，在活跃轮次信号的控制下校验由适配器持有的字段，并填入配置的推理（reasoning）强度和输出 token 默认值。准备完成的调用会在这次异步解析、`request/header` 日志记录和最终分派期间保留同一项确切的适配器注册，因此 HMR（热模块替换）不会把某个适配器的能力解析结果与另一适配器的请求混用。请求 header 会记录生效配置以及哪些字段来自适配器。下一次 waterfall（瀑布式事件）前，循环会从提议中移除这些带标记字段，使当前精确路由重新填入自身默认值；未带标记的显式设置会跨步骤和路由变化保留。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 监听器可以接管并短路该请求；最终分派仍会以 `NO_ADAPTER` 拒绝未得到处理的路由。新循环实例在恢复时会遵循同一套适配器默认值标记规则。
 
 插件失败会结束当前轮次，而不是结束循环。最终适配器选择、分发与迭代失败会以终止错误或中止结束的形式由 `ctx.llm` 传来，并进入 `agent/request-error`；middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次。恢复逻辑会接收请求坐标、不可变的提供方事实、准备完成的适配器注册所捕获的不可变重试策略以及轮次信号；middleware 接管未准备路由时，该策略缺失。处理失败的监听器返回 `{ kind: 'retry' }`；未被处理的失败是终态。AgentLoop 为当前接纳或轮次拥有一个取消信号。有效的 `cancel(cause)` 在未设置 `keepInbox` 时清除待处理工作，并以协作方式中止该信号；空闲取消是空操作。abort 触发后、活动收敛到空闲前到达的唤醒输入会被锁存（`wakeRequested`），并在 driver 自身的收敛边界重放，无需再发一条唤醒 send 即可执行；`disposed` 取消从不锁存，而 agent 已处于空闲时发送的唤醒总是打开自己的 turn 边界（即使消息已被清除，状态也会显示瞬态 `idle → running → idle` 对）。持久 `turn/end` 为 `user` 和 `parent` 记录 `aborted`，dispose 则记录 `disposed`；未分发的模型工具调用会收到合成的 `tool/call` 与 `ABORTED_BEFORE_DISPATCH` 结果对。取消原因只改变报告方式，不改变对取消后已定案结果上下文的处理。dispose 会等待忽略信号的工作完成，然后才从注册表移除。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)与[取消收敛窗口唤醒锁存](../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)规定生命周期与竞态约定。
 
diff --git a/packages/core/agent-loop/src/tool-calls.ts b/packages/core/agent-loop/src/tool-calls.ts
index 47082dac18..693ff7bd91 100644
--- a/packages/core/agent-loop/src/tool-calls.ts
+++ b/packages/core/agent-loop/src/tool-calls.ts
@@ -130,7 +130,7 @@ async function runGroup(
   const { session } = ctx.agents.requireInitiator()
   const { maxParallelToolCalls } = ctx.agentLoop.config
   const slots: (Slot | undefined)[] = group.map(() => undefined)
-  // Started slots retain their tool/call seq for result provenance.
+  // Started slots retain their `tool/call` seq so the result can cite it.
   const callSeqs: number[] = group.map(() => -1)
   let nextToStart = 0
   let committed = 0
@@ -258,7 +258,7 @@ function appendSkippedToolCall(session: Session, turn: number, step: number, blo
   }, callSeq)
 }
 
-/** Append a started call and return its provenance sequence. */
+/** Append a started call and return the event seq that its result must cite. */
 function appendToolCall(session: Session, turn: number, step: number, block: ToolCallBlock): number {
   const event = session.append('tool/call', { turn, step, callId: block.id, name: block.name, arguments: block.arguments })
   return event.seq
diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts
index b6540d9912..7dfbaddc41 100644
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -59,7 +59,7 @@ function inboxText(message: UserMessage): string {
     .join('')
 }
 
-describe('assistant replay provenance', () => {
+describe('assistant replay provider and model fields', () => {
   it('records adapter replay state with the assembled assistant content', async () => {
     const response = textResponse('unchanged')
     const replayState = { private: 'state' }
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index 825c1714a2..d1d8e5401d 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/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/core/agent/README.md
-README.md: ba0fa456593e598b6532c10ef2390bbd55f3a486
-README.zh.md: 581da5c8621e5653f57edce38ac9816da7a40d40
+README.md: 73d32d09d880b0d27b80a7aeecc1eb75bf03f8dd
+README.zh.md: e140d76c940ac605ddc6dedad8a9f2f16457fde0
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index ba0fa45659..73d32d09d8 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -115,5 +115,5 @@ Prefix-stable while an agent's scoped registrations are unchanged. Setup or relo
 - **Inter-agent channels beyond delegation** — shared state, streaming child output, and background/poll semantics remain outside the current synchronous `ctx.subagents` seam.
 - **`agent/session-start` cannot gate startup** — it remains a synchronous, veto-less notification; async composition that must finish before publication belongs in the factory's `setup(agentCtx)` transaction instead.
 - **`cancel()` clears the inbox by default** — it aborts the in-flight turn plus queued and steering work; `cancel(cause, { keepInbox: true })` aborts only the turn and preserves pending items. There is still no step-only abort that keeps the in-flight turn running ([stop-surface Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)).
-- **Each additional `UserMessage` carries exactly one `MessageSource`** — contributions from several plugins merged onto one tool call collapse under one source; mixed provenance is unrepresentable.
+- **Each additional `UserMessage` carries exactly one `MessageSource`** — contributions from several plugins merged onto one tool call collapse under one source, so the message cannot name several producers.
 - **`SessionStartSource` reserves `'clear'`/`'compact'` with no emitter yet** — only `'startup'`/`'resume'` occur until the driving subsystems land (`TODO(compaction)`).
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index 581da5c862..e140d76c94 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -115,5 +115,5 @@ inbox 的实时通知刻意采用逐消息的最小载荷：`agent/inbox/inserte
 - **委派以外的 agent 间通道**：共享状态、流式子输出和后台／轮询语义仍在当前同步 `ctx.subagents` seam 之外。
 - **`agent/session-start` 不能为启动设置门禁**：它仍是同步且不可 veto 的通知；必须在发布前完成的异步组合属于工厂的 `setup(agentCtx)` 事务。
 - **`cancel()` 默认清空 inbox**：它会中止正在处理的轮次以及排队和 steering 工作；`cancel(cause, { keepInbox: true })` 只中止轮次并保留待处理项。仍不存在只中止步骤、同时让正在处理的轮次继续运行的操作（[关于停止操作接口的 Agent Note](../../../.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md)）。
-- **每条附加 `UserMessage` 恰好携带一个 `MessageSource`**：多个插件合并到一次工具调用上的贡献会归入一个来源；无法表示混合来源。
+- **每条附加 `UserMessage` 恰好携带一个 `MessageSource`**：多个插件合并到一次工具调用上的贡献会归入同一来源，因此该消息无法列出多个生产者。
 - **`SessionStartSource` 预留 `'clear'`/`'compact'`，但还没有发出方**：在驱动子系统落地前，只会出现 `'startup'`/`'resume'`（`TODO(compaction)`）。
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index d8cb5c4114..ba9afa50d7 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -109,7 +109,7 @@ export interface Agent {
    * cancel leaves it parked. A wake submitted while already idle always opens
    * its turn boundary, even when its message is cleared before the driver
    * claims ([cancel-convergence wake latch](../../../../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)).
-   * @param message - identified content and its producer provenance.
+   * @param message - identified content and the source that supplied it.
    * @param target - the preferred next-turn or next-step inbox boundary.
    * @param wakeup - whether delivery may wake the driver.
    */
@@ -118,7 +118,7 @@ export interface Agent {
   /**
    * Queue an ordinary follow-up turn and wake the driver. The item becomes the
    * sole ordinary message of its own turn.
-   * @param message - identified prompt content and its producer provenance.
+   * @param message - identified prompt content and the source that supplied it.
    */
   followup(message: UserMessage): void
 
@@ -127,7 +127,7 @@ export interface Agent {
    * a running driver consumes it at its next step boundary.
    * A rejected step leaves steering parked in the inbox until the next
    * wake; cancellation or disposal may discard pending steering.
-   * @param message - identified steering content and its producer provenance.
+   * @param message - identified steering content and the source that supplied it.
    */
   steer(message: UserMessage): void
 
@@ -137,7 +137,7 @@ export interface Agent {
    * idle drivers leave it pending until follow-up or steering
    * wakes them. It may miss a request whose pre-step already claimed its
    * batch. Cancellation or disposal may discard pending context.
-   * @param message - identified injected context and its producer provenance.
+   * @param message - identified injected context and the source that supplied it.
    */
   inject(message: UserMessage): void
 }
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index abb9bfc6f2..67364cb415 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
-README.md: 00e007ee6064f485bf80dfda0227ab6e834f6414
-README.zh.md: e9d074f52db46cb42e497ad1ef49c2b37a6ec7d8
+README.md: 04d3cec7e431f5f265d52851eae59600536ce5b7
+README.zh.md: e9529b3c91c8d2413c64b4e344af83b6ebe698de
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index 00e007ee60..04d3cec7e4 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it. A **surface** layer (an ordered projection of message-producing events) is maintained on top of the raw log for efficient derivation and compaction.
 
-The optional `@deepseek-ai/dsh-session/invariant` companion registers this package's relational trace checks with `ctx.invariants`: monotonic sequence numbers, turn/step enclosure, and same-step tool call/result pairing. It replays existing sessions when loaded or reloaded; storage validation, snapshotting, freezing, provenance, and surface acceptance remain always-on responsibilities of the root session package.
+The optional `@deepseek-ai/dsh-session/invariant` companion registers this package's relational trace checks with `ctx.invariants`: monotonic sequence numbers, turn/step enclosure, and same-step tool call/result pairing. It replays existing sessions when loaded or reloaded; storage validation, snapshotting, freezing, cited source-event validation, and surface acceptance remain always-on responsibilities of the root session package.
 
 ## Service: `SessionStore` (ctx key: `sessions`)
 
@@ -36,8 +36,8 @@ The store pairs announced creation with disposal, publishes post-commit append n
 
 Plain class (not a Cordis Service). Create live sessions through `ctx.sessions.create()` and detached replay or inspection sessions through `Session.create()`; the detached factory does not publish lifecycle events or bind the session to a fiber.
 
-- `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, provenance, complete replacement coverage, and content-only single-result `tool/result` rewrites, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
-- `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over the complete identified, frozen messages stored by those entries. Assistant messages preserve provider/model provenance and adapter-private replay state in their model source. A surface rewrite rebuilds the projection; there is no raw-log fallback.
+- `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, cited source-event seqs, complete replacement coverage, and content-only single-result `tool/result` rewrites, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
+- `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over the complete identified, frozen messages stored by those entries. Assistant messages preserve the provider and model that produced them plus adapter-private replay state in their model source. A surface rewrite rebuilds the projection; there is no raw-log fallback.
 - `session.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and request checks.
 - `session.surface` exposes the readonly `SessionSurface` view owned by the session's single incremental surface manager; `replaceGeneration` changes on every committed rewrite.
 - `session.events` is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen.
@@ -68,7 +68,7 @@ A `user/message` stores the complete `UserMessage` directly, including the ident
 
 ### Session event vocabulary (`types.ts`)
 
-The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated [persistence log event catalog](../../../docs/persistence-catalog.md). Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Provider/model/replay provenance rides on `assistant/message`.
+The generated [persistence log event catalog](../../../docs/persistence-catalog.md) enumerates each append-only event type with its payload, surface badge, cited source-event seqs, and declaration site. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Each `assistant/message` records the provider, model, and optional replay state.
 
 Merge-extensible via `SessionEventMap` — a plugin declaration-merges its own types (the compaction seam's `compact/*`, bounded recovery's non-surface `llm/retry`, the hook bridges' `hook/*`); merged members appear in the same catalog. A plugin owns the relational invariant for its merged events, including whether a log-only event may appear between turns. A producer that requires durability appends through `Session` and then awaits `ctx.sessions.flush(session)` without fabricating an execution turn.
 
@@ -78,7 +78,7 @@ An interrupted live turn ends with `{ kind: 'aborted', reason: AgentCancelCause
 
 Every `SessionEvent` carries two optional top-level fields (structural metadata):
 
-- `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed entries behind a compaction replacement entry). On `assistant/message`, a present `[]` records a known empty provider stream, while omission means legacy or otherwise unrecorded provenance; other surface events require a non-empty list when this field is present.
+- `sourceEventSeqs?: number[]` — seq numbers of earlier events cited as sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed entries behind a compaction replacement entry). On `assistant/message`, a present `[]` records a known empty provider stream, while omission means a legacy or foreign event did not record the source stream; other surface events require a non-empty list when this field is present.
 - `surfaceOp?: SurfaceOp` — how this event entered the surface. Absent for non-surface events (boundaries, chunks, usage, errors).
 
 ### Metadata types (`types.ts`)
@@ -88,7 +88,7 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 ### Extension points
 
 - Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
-- Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers require provider/model, and assistant messages require provider/model provenance. Persistence owns read compatibility before constructing this current-format seed. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
+- Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers and assistant messages require provider/model. Persistence owns read compatibility before constructing this current-format seed. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
 - Compaction: `dsh-compact-basic` appends a `user/message` replacement for summary checkpoints, while `dsh-compact-tool-result-prune` appends a content-only `tool/result` replacement. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns ordered surface membership, replacement validation, and `replaceGeneration`.
 
 ## Model Experience
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index e9d074f52d..e9529b3c91 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -4,7 +4,7 @@
 
 事件溯源的会话日志和内存存储。`Session` 是 agent（智能体）全部交互历史的仅追加真源，LLM（大语言模型）消息历史由它*派生*。原始日志之上维护一个 **surface** 层（产生消息事件的有序投影），以便高效派生和压缩（compaction）。
 
-可选配套入口 `@deepseek-ai/dsh-session/invariant` 将此包的关系轨迹检查注册到 `ctx.invariants`：序号单调递增、轮次／步骤闭合，以及同一步骤内的工具调用／结果配对。加载或重新加载时，它会回放现有会话；存储校验、快照、冻结、溯源信息和 surface 准入仍始终由根会话包负责。
+可选配套入口 `@deepseek-ai/dsh-session/invariant` 将此包的关系轨迹检查注册到 `ctx.invariants`：序号单调递增、轮次／步骤闭合，以及同一步骤内的工具调用／结果配对。加载或重新加载时，它会回放现有会话；存储校验、快照、冻结、被引用的源事件校验和 surface 准入仍始终由根会话包负责。
 
 ## 服务：`SessionStore`（ctx 键：`sessions`）
 
@@ -36,8 +36,8 @@
 
 普通类（不是 Cordis 服务）。活跃会话通过 `ctx.sessions.create()` 创建，脱离态的回放或检查会话通过 `Session.create()` 创建；脱离态工厂不会发布生命周期事件，也不会将会话绑定到 fiber。
 
-- `session.append(type, data, opts?)` 会为持久数据和 surface 元数据制作快照并冻结它们，校验标记形态、溯源信息、替换覆盖完整性，以及仅修改内容的单个 `tool/result` 重写，随后同步提交，再在彼此独立的失败收容下通知观察者。对已附加会话的重入追加会被拒绝，运行时检查也覆盖扩宽后的联合类型和已加载日志。
-- `session.deriveMessages()` 对每个新的 surface 条目只做一次增量投影，并返回一个新数组，其中包含这些条目存储的完整、带标识且冻结的消息。assistant 消息会在其模型来源中保留提供方／模型溯源信息及适配器私有回放状态。surface 重写会重建投影；不存在原始日志回退。
+- `session.append(type, data, opts?)` 会为持久数据和 surface 元数据制作快照并冻结它们，校验标记形态、被引用的源事件 seq、替换覆盖完整性，以及仅修改内容的单个 `tool/result` 重写，随后同步提交，再在彼此独立的失败收容下通知观察者。对已附加会话的重入追加会被拒绝，运行时检查也覆盖扩宽后的联合类型和已加载日志。
+- `session.deriveMessages()` 对每个新的 surface 条目只做一次增量投影，并返回一个新数组，其中包含这些条目存储的完整、带标识且冻结的消息。assistant 消息的模型来源会保留生成该消息的提供方和模型，以及适配器私有回放状态。surface 重写会重建投影；不存在原始日志回退。
 - `session.deriveEventMessage(event)` 是重建和请求检查使用的规范逐事件投影。
 - `session.surface` 暴露只读 `SessionSurface` 视图，由会话唯一的增量 surface 管理器所有；每次提交重写，`replaceGeneration` 都会变化。
 - `session.events` 是按追加失效的缓存冻结快照；已接受事件保持深度冻结。
@@ -68,7 +68,7 @@
 
 ### 会话事件词汇（`types.ts`）
 
-生成的[持久化日志事件目录](../../../docs/persistence-catalog.md)逐成员列举仅追加日志的事件类型、载荷、surface 标记和溯源信息。Token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息。提供方／模型／回放溯源信息随 `assistant/message` 一同保存。
+生成的[持久化日志事件目录](../../../docs/persistence-catalog.md)逐成员列举仅追加日志的事件类型、载荷、surface 标记、被引用的源事件 seq 与声明位置。Token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息。每条 `assistant/message` 都会记录提供方、模型和可选回放状态。
 
 `SessionEventMap` 可通过合并扩展：插件使用声明合并添加自身类型（压缩 seam 的 `compact/*`、有界恢复的非 surface `llm/retry`、hook（钩子）桥接层的 `hook/*`）；合并成员会出现在同一目录中。插件拥有其合并事件的关系不变量，包括是否允许纯日志事件出现在轮次之间。需要持久性的生产方通过 `Session` 追加，再等待 `ctx.sessions.flush(session)`，无需虚构一个执行轮次。
 
@@ -78,7 +78,7 @@
 
 每个 `SessionEvent` 都有两个可选顶层字段（结构元数据）：
 
-- `sourceEventSeqs?: number[]`：溯源信息的源序号（例如 `assistant/chunk` 的序号，它们是 `assistant/message` 的来源；或压缩替换条目背后被遮蔽的条目）。对于 `assistant/message`，存在的 `[]` 记录已知为空的提供方流；省略则表示旧版或其他未记录的溯源信息。其他 surface 事件若有此字段，则要求非空列表。
+- `sourceEventSeqs?: number[]`：被引用为来源的较早事件 seq（例如 `assistant/message` 引用的 `assistant/chunk` seq，或压缩替换条目引用的已遮蔽条目）。对于 `assistant/message`，存在的 `[]` 表示已知提供方流为空；省略则表示旧版或外部事件没有记录源流。其他 surface 事件若有此字段，则要求非空列表。
 - `surfaceOp?: SurfaceOp`：事件进入 surface 的方式。非 surface 事件（边界、分片、用量、错误）不含该字段。
 
 ### 元数据类型（`types.ts`）
@@ -88,7 +88,7 @@
 ### 扩展点
 
 - 持久化插件：订阅 `session/event`（延后写入），并在 `session/flush`（受等待）及 fiber dispose（资源释放）时排空。持久后端读取日志并重新加载到实时会话；这类后端会把元数据 seam（`SessionHeader`、`session.header`）与日志一同存储。
-- 回放／fork：`create(id, { seed })` 校验并冻结连续的当前格式日志，再重建 surface；请求头必须包含提供方／模型，assistant 消息必须包含提供方／模型溯源信息。持久化层在构造该当前格式 seed 前负责读取兼容性处理。`fork(source, boundary?, childSessionId?)` 选择已完成轮次前缀并记录谱系。
+- 回放／fork：`create(id, { seed })` 校验并冻结连续的当前格式日志，再重建 surface；请求头和 assistant 消息都必须包含提供方／模型。持久化层在构造该当前格式 seed 前负责读取兼容性处理。`fork(source, boundary?, childSessionId?)` 选择已完成轮次前缀并记录谱系。
 - 压缩：`dsh-compact-basic` 为摘要检查点追加一个替换用 `user/message`，而 `dsh-compact-tool-result-prune` 追加仅修改内容的 `tool/result` 替换。工具配对边界策略及其缓存归 [`dsh-compact` seam](../../compact/compact/README.md) 所有；此包拥有有序 surface 成员关系、替换校验与 `replaceGeneration`。
 
 ## 模型体验
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index 3f73242958..1c1d2a3023 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -293,7 +293,7 @@ function assertCurrentLlmShape(event: Record<string, unknown>, index: number): v
 
 const allowedAdapterKeys = new Set(['reasoningEffort', 'maxTokens'])
 
-/** Validate adapter-default provenance imported from a durable request header. */
+/** Validate adapter-default markers imported from a durable request header. */
 function assertAdapterDefaults(
   value: unknown,
   config: Record<string, unknown>,
@@ -592,8 +592,8 @@ export class Session {
    * @param type - The event type (key of {@link SessionEventMap}).
    * @param data - The event payload; must be JSON-serializable.
    * @param opts - Surface metadata: `surfaceOp` controls how the event enters
-   *   the ordered surface; `sourceEventSeqs` records provenance (the seq
-   *   numbers of events this one derives from). REQUIRED for
+   *   the ordered surface; `sourceEventSeqs` lists the seq numbers of earlier
+   *   events this one derives from. REQUIRED for
    *   {@link SurfaceEventType} events (every message-producing event must
    *   declare how it joins the surface, the sole source of derived model
    *   history) and
@@ -607,7 +607,7 @@ export class Session {
    *   circular reference, sparse array, or an exotic object such as
    *   Map/Set/Date/class instance), or when the candidate violates the
    *   canonical surface contract (marker shape and eligibility, unique
-   *   earlier provenance, positional replacement validity, and complete
+   *   earlier source-event references, positional replacement validity, and complete
    *   shadowed-node coverage). One recursive pass reads, validates, and
    *   copies each nested value once, so a stateful getter cannot supply one value
    *   to validation and another to storage. The event log is the durable source
diff --git a/packages/core/session/src/invariant.ts b/packages/core/session/src/invariant.ts
index f86b43716e..77d2b22ac2 100644
--- a/packages/core/session/src/invariant.ts
+++ b/packages/core/session/src/invariant.ts
@@ -125,7 +125,7 @@ function validateEvent(
       break
     }
     case 'tool/result': {
-      // Session has already validated a provenance-backed content rewrite.
+      // Session has already validated a content rewrite that cites its replaced event.
       // It is durable turn work, not a second execution of the original call.
       if (event.surfaceOp !== 'append') {
         if (trace.openTurn === null) {
diff --git a/packages/core/session/src/repair.ts b/packages/core/session/src/repair.ts
index 1114156c2e..1203bed341 100644
--- a/packages/core/session/src/repair.ts
+++ b/packages/core/session/src/repair.ts
@@ -47,7 +47,7 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
   let openTurn: number | null = null
   let openStep: number | null = null
   // Reset at each turn boundary so earlier calls cannot leak into tail repair.
-  // Assistant blocks register calls; later tool/call events add provenance seqs.
+  // Assistant blocks register calls; later `tool/call` events add their seqs to `sourceEventSeqs`.
   const pendingCalls = new Map<CallId, { step: number; callSeq?: number }>()
   for (const event of events) {
     switch (event.type) {
@@ -76,7 +76,7 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
         }
         break
       case 'tool/call':
-        // Add the tool/call seq used as provenance on a synthetic result.
+        // Cite the `tool/call` seq from the synthetic result.
         {
           const entry = pendingCalls.get(event.data.callId)
           if (entry) {
diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts
index ad1c4b2ad3..4e2690a227 100644
--- a/packages/core/session/src/surface.ts
+++ b/packages/core/session/src/surface.ts
@@ -207,7 +207,7 @@ function surfaceOpOf(event: SessionEvent): SurfaceOp | undefined {
   return op
 }
 
-/** Validate provenance against prior log entries and the replacement range. */
+/** Validate cited source-event seqs against prior log entries and the replacement range. */
 function assertProvenance(
   event: SessionEvent,
   shadowedSeqs: readonly number[],
@@ -382,7 +382,7 @@ function applySurfacePlan(
  * Replay a complete session log through the canonical surface fold.
  * @param events - session events in contiguous seq order.
  * @returns detached current sequences and replacement history.
- * @throws when an event violates surface metadata, provenance, range, or tool-result rewrite rules.
+ * @throws when an event violates surface metadata, source-event references, range, or tool-result rewrite rules.
  */
 export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult {
   const state = createFoldState()
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index d655c2488e..c1071e1e01 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -345,15 +345,15 @@ export type SurfaceOp =
   | { op: 'replace'; start: number; end: number }
 
 /**
- * Surface placement and provenance for {@link Session.append}. Required on
+ * Surface placement and cited source-event seqs for {@link Session.append}. Required on
  * message-producing events and forbidden on log-only events.
  */
 export interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
-   * Complete known provenance source set. `assistant/message` may use a
+   * Complete set of known source-event seqs. `assistant/message` may use a
    * present empty array for a known empty provider stream; omission means its
-   * provenance was not recorded. Other surface events require a non-empty set
+   * source stream was not recorded. Other surface events require a non-empty set
    * when this field is present.
    */
   sourceEventSeqs?: number[]
@@ -382,11 +382,11 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     data: SessionEventMap[K]
   } & (K extends SurfaceEventType ? {
     /**
-     * Seq numbers of events that are provenance sources of this event
+     * Seq numbers of earlier events that this event cites as sources
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means unrecorded provenance.
+     * provider stream; omission means the source stream was not recorded.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
diff --git a/packages/core/session/tests/gen-persistence-catalog.spec.ts b/packages/core/session/tests/gen-persistence-catalog.spec.ts
index 9f18e75bbe..9a09cb3489 100644
--- a/packages/core/session/tests/gen-persistence-catalog.spec.ts
+++ b/packages/core/session/tests/gen-persistence-catalog.spec.ts
@@ -95,10 +95,10 @@ describe('gen-persistence-catalog collectLogEvents', () => {
 
   it('extracts a member declaration-merged via the session module', () => {
     const events = collectLogEvents(make({
-      'packages/group/fix/src/types.ts': merge('    /** Merged provenance. */\n    \'fix/merged\': { id: string }'),
+      'packages/group/fix/src/types.ts': merge('    /** Merged event source record. */\n    \'fix/merged\': { id: string }'),
     }))
     expect(events).toHaveLength(1)
-    expect(events[0]).toMatchObject({ name: 'fix/merged', doc: 'Merged provenance.' })
+    expect(events[0]).toMatchObject({ name: 'fix/merged', doc: 'Merged event source record.' })
   })
 
   it('collapses a newline-separated multi-line payload to a valid one-line fragment', () => {
diff --git a/packages/core/session/tests/session.spec.ts b/packages/core/session/tests/session.spec.ts
index 1394db01e3..39f0530874 100644
--- a/packages/core/session/tests/session.spec.ts
+++ b/packages/core/session/tests/session.spec.ts
@@ -417,7 +417,7 @@ describe('Session', () => {
     }
   })
 
-  it('round-trips adapter-default provenance and rejects invalid durable values', () => {
+  it('round-trips adapter-default markers and rejects invalid durable values', () => {
     const valid = {
       type: 'request/header',
       seq: 0,
diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts
index 4a7de73b03..7c7ca160b6 100644
--- a/packages/core/session/tests/surface.spec.ts
+++ b/packages/core/session/tests/surface.spec.ts
@@ -78,8 +78,8 @@ function toolResultEvent(
   }
 }
 
-describe('foldSurface provenance', () => {
-  it('accepts absent or valid provenance and complete replacement coverage', () => {
+describe('foldSurface source-event references', () => {
+  it('accepts absent or valid source-event references and complete replacement coverage', () => {
     const events = [
       provenanceEvent(0, undefined),
       provenanceEvent(1, undefined),
@@ -91,7 +91,7 @@ describe('foldSurface provenance', () => {
     expect(() => foldSurface(events)).not.toThrow()
   })
 
-  it('rejects provenance on a non-surface event', () => {
+  it('rejects source-event references on a non-surface event', () => {
     const event = {
       type: 'turn/start',
       seq: 0,
@@ -102,7 +102,7 @@ describe('foldSurface provenance', () => {
     expect(() => foldSurface([event])).toThrow(/cannot carry sourceEventSeqs/)
   })
 
-  it('accepts explicit empty provenance on an assistant message', () => {
+  it('accepts an explicit empty source-event list on an assistant message', () => {
     const event = {
       type: 'assistant/message',
       seq: 0,
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index 53f11f85a1..80c185d9b3 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: 97aa97c6ca7675ff5b891e62224a4d1d7780ef42
-README.zh.md: 7ecc146e1f47c95b01b47740868a333cee694b59
+README.md: 73c18552baa4b8b68c3d34c2d928d479548180ba
+README.zh.md: 9812fd50b2500b6393c9328ea1c366eb04963e74
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index 97aa97c6ca..73c18552ba 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -54,7 +54,7 @@ The live registry pipeline has three transformable waterfalls, then the definiti
 
 - Tool plugins call `ctx.tools.register()` — schemas flow into the assembly automatically.
 - `tools/pre-execute` is the reorderable allow/deny/ask gate; `ctx.tools.guard()` adds monotonic owner policy after it.
-- `tools/execute` wraps normalized canonical dispatch for timeout, retry, or metrics. Wrappers may replace only the operational signal; a wrapper-authored success is normalized through the resolved tool's output declaration. Canonical-result provenance belongs to one immutable dispatch token, so a cached result from another call or tool is revalidated under the active declaration.
+- `tools/execute` wraps normalized canonical dispatch for timeout, retry, or metrics. Wrappers may replace only the operational signal; a wrapper-authored success is normalized through the resolved tool's output declaration. Each canonical result belongs to one immutable dispatch token, so a cached result from another call or tool is revalidated under the active declaration.
 - `tools/post-execute` may replace presentation content, replace the canonical value, block with feedback, or attach ordered contexts. A definition's optional `finalizeContent` then owns its last content-only invariant across normal results and outer pipeline failures; `tools/result` observes the immutable final outcome. Content replacement is not a confidentiality boundary: block or replace the value when programmatic consumers must not receive it.
 - Exact signatures and ordering live in the generated region of [tools.md](../../../docs/subsystems/tools.md#cordis-surface) and [pipeline](../../../docs/tool-execution-pipeline.md).
 - MCP servers: one plugin per server, discover tools, call `ctx.tools.register()` with the server's schemas.
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 7ecc146e1f..9812fd50b2 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -54,7 +54,7 @@ tools:
 
 - 工具插件调用 `ctx.tools.register()`：schema 会自动流入组装结果。
 - `tools/pre-execute` 是可重排的允许／拒绝／询问门禁；`ctx.tools.guard()` 在其后添加单调的拥有方策略。
-- `tools/execute` 会环绕包装规范化后的规范分发，以支持超时、重试或指标采集。包装层只能替换操作信号；包装层生成的成功结果会根据已解析工具的输出声明进行规范化。规范结果的来源属于一个不可变分发 token，因此，来自其他调用或工具的缓存结果会根据当前声明重新验证。
+- `tools/execute` 会环绕包装规范化后的规范分发，以支持超时、重试或指标采集。包装层只能替换操作信号；包装层生成的成功结果会根据已解析工具的输出声明进行规范化。每个规范结果属于一个不可变分发 token，因此来自其他调用或工具的缓存结果会根据当前声明重新验证。
 - `tools/post-execute` 可以替换呈现内容、替换规范值、通过反馈阻止，或附加有序上下文。随后，定义可选的 `finalizeContent` 会在普通结果和外层流水线失败中维护其最终、仅涉及内容的不变式；`tools/result` 观测不可变的最终结果。内容替换不是保密边界：当编程消费方不得接收某个值时，应阻止或替换该值。
 - 确切签名与顺序位于 [tools.md](../../../docs/subsystems/tools.md#cordis-surface) 的生成区块和[流水线](../../../docs/tool-execution-pipeline.md)中。
 - MCP 服务器：每个服务器使用一个插件；发现工具后，使用服务器的 schema 调用 `ctx.tools.register()`。
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index 15588e40b9..ed30b896bf 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -382,7 +382,7 @@ function daclAcePolicy(descriptor: Buffer): string[] {
   for (let index = 0; index < aceCount; index++) {
     const size = descriptor.readUInt16LE(offset + 2)
     const ace = Buffer.from(descriptor.subarray(offset, offset + size))
-    // INHERITED_ACE records provenance, not the entry's access policy.
+    // INHERITED_ACE records which parent ACE produced this entry, not the entry's access policy.
     ace.writeUInt8(ace.readUInt8(1) & ~0x10, 1)
     const key = ace.toString('hex')
     if (!seen.has(key)) {
diff --git a/packages/goal/tool-goal/README.i18n.yaml b/packages/goal/tool-goal/README.i18n.yaml
index 3f4131c2b1..5f12f06484 100644
--- a/packages/goal/tool-goal/README.i18n.yaml
+++ b/packages/goal/tool-goal/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/goal/tool-goal/README.md
-README.md: c8c1ab84c237ee34db7abcd63962476693b5e56c
-README.zh.md: 7120280fcaa8710e5bab819a0539c926ab4e424a
+README.md: b93da1ced1cfbea0b4cdc2a7e253b9a515e75b21
+README.zh.md: 2c813c6406b170f93ee0b90939904d3570425ec3
diff --git a/packages/goal/tool-goal/README.md b/packages/goal/tool-goal/README.md
index c8c1ab84c2..b93da1ced1 100644
--- a/packages/goal/tool-goal/README.md
+++ b/packages/goal/tool-goal/README.md
@@ -73,7 +73,7 @@ Schemas are prefix-stable while their definitions and visibility are unchanged.
 
 ## Known Limitations and Deferred Work
 
-- **Semantic intent remains model judgment** — execution can prove direct human provenance, not whether a request is substantial enough to merit a goal.
+- **Semantic intent remains model judgment** — execution can prove that the current turn contains a direct human message, not whether the request is substantial enough to merit a goal.
 - **Same-condition blocking remains model judgment** — the runtime enforces distinct admitted-round count, not semantic equivalence of obstacles; an independent evaluator is deferred.
 - **No scheduling or direct human rendering** — these tools mutate state only; the same-session driver and [`dsh-command-goal`](../command-goal/README.md) are independent consumers of the same domain.
 - **Goal-round authority requires a driver** — the autonomous `complete`/`blocked` path is dormant unless a continuation driver admits goal-sourced user turns; mounting this tool package alone does not create them.
diff --git a/packages/goal/tool-goal/README.zh.md b/packages/goal/tool-goal/README.zh.md
index 7120280fca..2c813c6406 100644
--- a/packages/goal/tool-goal/README.zh.md
+++ b/packages/goal/tool-goal/README.zh.md
@@ -73,7 +73,7 @@ schema 的定义与可见性不变时，前缀保持稳定。调用和结果会
 
 ## 已知限制与暂缓事项
 
-- **语义意图仍由模型判断**：执行只能证明人类直接来源，无法证明请求是否足够重大而值得创建 goal。
+- **语义意图仍由模型判断**：执行只能证明当前轮次包含一条人类直接发送的消息，无法证明请求是否足够重大而值得创建 goal。
 - **阻塞条件是否相同仍由模型判断**：运行时强制统计互不重复的已准入 Goal Round，而不判断障碍在语义上是否等价；独立评估器的实现暂缓。
 - **不负责调度或直接面向人类呈现**：这些工具只变更状态；同会话驱动器与 [`dsh-command-goal`](../command-goal/README.md) 是同一领域的独立消费方。
 - **Goal Round 权限需要驱动器**：除非续行驱动器准入 goal 来源的用户轮次，否则自主 `complete`／`blocked` 路径不会启用；只挂载这个包不会创建这些轮次。
diff --git a/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts b/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts
index 40382218d8..20cd9a0104 100644
--- a/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts
+++ b/packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts
@@ -330,7 +330,7 @@ describe('fold onto the downstream decision', () => {
 
     const found = reminders(agent)
     expect(found).toHaveLength(3)
-    // Only the repeated call adds guard context; downstream provenance survives.
+    // Only the repeated call adds guard context; downstream source fields survive.
     expect(found[0]!.text).toBe('downstream-ctx')
     expect(found[0]!.source).toEqual({ kind: 'plugin', plugin: 'test' })
     expect(found[1]!.text).toContain('repeating the exact same tool call')
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index f082be00ef..b7c8ec3ee8 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/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/hooks/hook-protocol/README.md
-README.md: e807d9597eb5f811195bab9a0ad2b30b545e1205
-README.zh.md: c206224b45a5b12a7aa85d24de301f3d949f294b
+README.md: 797d15c357bd26e0db072b30b61c251005021905
+README.zh.md: 8a96cd2f1f91ad2d7a12fc15ffc06ea0c2c1d80f
diff --git a/packages/hooks/hook-protocol/README.md b/packages/hooks/hook-protocol/README.md
index e807d9597e..797d15c357 100644
--- a/packages/hooks/hook-protocol/README.md
+++ b/packages/hooks/hook-protocol/README.md
@@ -29,7 +29,7 @@ Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claud
 
 Declaration-merged into `SessionEventMap` (log-only, like `compact/*` — NOT a `SurfaceEventType`, no `surfaceOp`): `hook/invoked` (a hook command ran) and `hook/result` (its outcome, paired by `handlerId`, with `appendHookResult` owning the decision rule). Payloads and per-event JSDoc are in the generated [persistence log event catalog](../../../docs/persistence-catalog.md); `stderrSummary` is truncated to the record's `stderrSummaryMaxChars` (the bridge's config, reference default `DEFAULT_STDERR_SUMMARY_MAX_CHARS` = 500; omitted when empty).
 
-Hook provenance records must sit inside an open turn. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` satisfy that owner-defined relation by construction. `SessionStart` runs before turn 1 and gets no `hook/*` record; its allowed context remains pending in the inbox until a waking delivery opens a turn — see the hooks Agent Note.
+Hook invocation/result records must sit inside an open turn. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` satisfy that owner-defined relation by construction. `SessionStart` runs before turn 1 and gets no `hook/*` record; its allowed context remains pending in the inbox until a waking delivery opens a turn — see the hooks Agent Note.
 
 ## Model Experience
 
diff --git a/packages/hooks/hook-protocol/README.zh.md b/packages/hooks/hook-protocol/README.zh.md
index c206224b45..8a96cd2f1f 100644
--- a/packages/hooks/hook-protocol/README.zh.md
+++ b/packages/hooks/hook-protocol/README.zh.md
@@ -29,7 +29,7 @@ Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它
 
 通过 declaration merging 合并到 `SessionEventMap`（仅日志，与 `compact/*` 相同；不是 `SurfaceEventType`，没有 `surfaceOp`）：`hook/invoked`（hook 命令已运行）与 `hook/result`（其结果，按 `handlerId` 配对，决策规则由 `appendHookResult` 负责）。Payload 与每事件 JSDoc 位于生成的 [持久化日志事件目录](../../../docs/persistence-catalog.md)；`stderrSummary` 会截断到记录的 `stderrSummaryMaxChars`（桥接配置，参考默认值 `DEFAULT_STDERR_SUMMARY_MAX_CHARS` = 500；为空时省略）。
 
-Hook 溯源记录必须位于一个尚未结束的轮次内。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 按构造满足这条由所有者定义的关系。`SessionStart` 在轮次 1 之前运行，因此没有 `hook/*` 记录；其获准的上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次，详见 hooks Agent Note。
+Hook 调用／结果记录必须位于一个尚未结束的轮次内。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 按构造满足这条由所有者定义的关系。`SessionStart` 在轮次 1 之前运行，因此没有 `hook/*` 记录；其获准的上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次，详见 hooks Agent Note。
 
 ## 模型体验
 
diff --git a/packages/hooks/hook-protocol/src/events.ts b/packages/hooks/hook-protocol/src/events.ts
index 025250cdac..3f1a827ecc 100644
--- a/packages/hooks/hook-protocol/src/events.ts
+++ b/packages/hooks/hook-protocol/src/events.ts
@@ -68,7 +68,7 @@ export function summarizeStderr(stderr: string, maxChars: number): string | unde
 }
 
 /**
- * Append a `hook/invoked` provenance event to `session`.
+ * Append a `hook/invoked` event naming the handler and hook point to `session`.
  * @param session - the session whose open turn records the event.
  * @param invocation - the invocation identity; an absent `matcher` is omitted from the payload.
  */
diff --git a/packages/hooks/hook-protocol/src/invariant.ts b/packages/hooks/hook-protocol/src/invariant.ts
index 9bc5e6a1e1..8a7c7338c3 100644
--- a/packages/hooks/hook-protocol/src/invariant.ts
+++ b/packages/hooks/hook-protocol/src/invariant.ts
@@ -1,4 +1,4 @@
-/** Package-owned hook provenance-stream invariants. @module @deepseek-ai/dsh-hook-protocol/invariant */
+/** Package-owned hook invocation/result stream invariants. @module @deepseek-ai/dsh-hook-protocol/invariant */
 
 import type { Context } from 'cordis'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
@@ -98,7 +98,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
     }
     if (event.type !== 'hook/invoked' && event.type !== 'hook/result') return
     const candidate = staged.get(event)
-    /* v8 ignore next -- internal/dispatch stages every hook provenance event */
+    /* v8 ignore next -- internal/dispatch stages every hook invocation/result event */
     if (candidate === undefined || candidate.session !== session) return fail('hook event published without pre-commit validation')
     staged.delete(event)
     applyHookTransition(trace.pending, candidate.transition)
diff --git a/packages/hooks/hook-protocol/src/types.ts b/packages/hooks/hook-protocol/src/types.ts
index 6a3dd616f3..1be2b7cb04 100644
--- a/packages/hooks/hook-protocol/src/types.ts
+++ b/packages/hooks/hook-protocol/src/types.ts
@@ -8,7 +8,7 @@
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
     /**
-     * A hook command was invoked at a hook point — log-only provenance (like
+     * A hook command was invoked at a hook point — a log-only record (like
      * `compact/*`; NOT a {@link SurfaceEventType}, carries no `surfaceOp`).
      * `dialect` is the bridge that ran it (`claude`/`codex`), `point`
      * the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group
@@ -43,7 +43,7 @@ declare module '@deepseek-ai/dsh-session' {
 /**
  * The bridge that ran a hook — the CC bridge stamps `'claude'`, the Codex
  * bridge `'codex'`. A native plugin on the interception seams is not a bridge
- * and writes no `hook/*` provenance (see the interception-seams Agent Note).
+ * and writes no `hook/*` invocation/result records (see the interception-seams Agent Note).
  */
 export type HookDialect = 'claude' | 'codex'
 
diff --git a/packages/hooks/hook-protocol/tests/invariant.spec.ts b/packages/hooks/hook-protocol/tests/invariant.spec.ts
index f1792be67f..94e5b57847 100644
--- a/packages/hooks/hook-protocol/tests/invariant.spec.ts
+++ b/packages/hooks/hook-protocol/tests/invariant.spec.ts
@@ -45,7 +45,7 @@ describe('hook-protocol invariants', () => {
     session.append('hook/result', result())
   })
 
-  it('rebuilds pending hook provenance from an existing session', async () => {
+  it('rebuilds pending hook invocations from an existing session', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create()
diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts
index 77b3a2711b..e42f875f13 100644
--- a/packages/hooks/hooks-claude/src/index.ts
+++ b/packages/hooks/hooks-claude/src/index.ts
@@ -195,7 +195,7 @@ export function apply(ctx: Context, config: Config): void {
     return createUserMessage({ content, source: PLUGIN_SOURCE })
   }
 
-  /** Prepend one context without flattening downstream provenance or metadata. */
+  /** Prepend one context without flattening source fields or other downstream metadata. */
   function prependContext(ours: UserMessage, theirs: UserMessage[] | undefined): UserMessage[] {
     return [ours, ...theirs ?? []]
   }
diff --git a/packages/hooks/hooks-claude/src/invariant.ts b/packages/hooks/hooks-claude/src/invariant.ts
index 18bc942e9f..d7908419d4 100644
--- a/packages/hooks/hooks-claude/src/invariant.ts
+++ b/packages/hooks/hooks-claude/src/invariant.ts
@@ -16,7 +16,7 @@ export const inject = ['invariants']
 
 /**
  * No runtime invariant: this bridge publishes hook-protocol session events, whose companion owns
- * their cross-event provenance relation.
+ * which invocation event each result cites.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts
index 304deef63c..873b1e35ae 100644
--- a/packages/hooks/hooks-codex/src/index.ts
+++ b/packages/hooks/hooks-codex/src/index.ts
@@ -107,7 +107,7 @@ export function apply(ctx: Context, config: Config): void {
   /**
    * Run and fold one configured Codex hook point.
    *
-   * A supplied turn records the hook provenance pair inside that open turn.
+   * A supplied turn records the hook invocation/result pair inside that open turn.
    * Detached lifecycle points omit it.
    */
   async function runPoint(
@@ -177,7 +177,7 @@ export function apply(ctx: Context, config: Config): void {
     return createUserMessage({ content, source: PLUGIN_SOURCE })
   }
 
-  /** Prepend one context without flattening downstream provenance or metadata. */
+  /** Prepend one context without flattening source fields or other downstream metadata. */
   function prependContext(ours: UserMessage, theirs: UserMessage[] | undefined): UserMessage[] {
     return [ours, ...theirs ?? []]
   }
diff --git a/packages/hooks/hooks-codex/src/invariant.ts b/packages/hooks/hooks-codex/src/invariant.ts
index 5f0f6ed173..c3eacb7ab0 100644
--- a/packages/hooks/hooks-codex/src/invariant.ts
+++ b/packages/hooks/hooks-codex/src/invariant.ts
@@ -16,7 +16,7 @@ export const inject = ['invariants']
 
 /**
  * No runtime invariant: this bridge publishes hook-protocol session events, whose companion owns
- * their cross-event provenance relation.
+ * which invocation event each result cites.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index b994e46b03..3069ec7948 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 5e3a6cf57ce3fe11b3f31d7f68055f34708d74eb
-README.zh.md: b96487d6d67deb8a0a6ddf4a92784f31dafb3e89
+README.md: 9b430fca1c2352334e6428eb37b80726a4e02c02
+README.zh.md: c36a88b44348d0054e71ea9d796291b91fadbf20
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 5e3a6cf57c..9b430fca1c 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -24,7 +24,7 @@ The layering/protocol decisions are recorded in the [GUI layering and RPC protoc
 
 Question responses are validated against their pending request before the first answer claims it. A multi-select item may carry both requested option labels in `selected` and non-empty `custom` text; a single-select item must use one or the other. Duplicate labels, unknown labels, mismatched ids, incomplete batches, and empty custom text are rejected as `bad-response`.
 
-`session.history` reads an attached Session in memory or inspects a cold log through persistence without resuming or publishing an Agent, then pages on append-origin message boundaries. `maxMessages` counts `user/message` and `assistant/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it.
+`session.history` reads an attached Session in memory or inspects a cold log through persistence without resuming or publishing an Agent, then pages on append-origin message boundaries. `maxMessages` counts `user/message` and `assistant/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only `compact/summary` record on the same page as the replacement that cites it.
 
 `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index b96487d6d6..c36a88b443 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -24,7 +24,7 @@ Settings 分节中的 `reasoningEffort` 在 agent-default-model 插件配置中
 
 首个回答认领待处理请求之前，系统会对照该请求校验问题响应。多选题的回答项可以同时携带 `selected` 中的请求选项标签与非空 `custom` 文本；单选题的回答项必须二选一。标签重复、标签未知、id 不匹配、批次不完整以及自定义文本为空都会以 `bad-response` 拒绝。
 
-`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent，然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
+`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent，然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志 `compact/summary` 记录与引用它的替换留在同一页。
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 01b792353d..a4ce497c1d 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -109,7 +109,7 @@ function isAborted(signal: AbortSignal): boolean {
  * backwards from the window tail. Replacement copies never entered the
  * conversation a reader sees — they restate a shadowed range for the model
  * alone — so they consume no quota; the page stays one contiguous raw range,
- * which keeps a compaction's log-only provenance on the same page as its
+ * which keeps a compaction's log-only `compact/summary` record on the same page as its
  * replacement. The cut is the starting seq of the oldest message group (chunks
  * group via sourceEventSeqs — never cut mid-message). The tail page naturally
  * includes the in-progress partial.
@@ -1508,7 +1508,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             // Host visibility is the authorization boundary. Consume the
             // provider's globally ranked stream rather than binding every
             // visible id into one SQLite statement, then re-check complete
-            // provenance before emitting any snippet.
+            // provider id before emitting any snippet.
             for (const hit of page.items) {
               if (authorized.length > SESSION_SEARCH_RESULT_LIMIT) continue
               if (
diff --git a/packages/host/apiproxy/src/api/sessions.ts b/packages/host/apiproxy/src/api/sessions.ts
index a5fc8fffad..0a4da455a2 100644
--- a/packages/host/apiproxy/src/api/sessions.ts
+++ b/packages/host/apiproxy/src/api/sessions.ts
@@ -216,7 +216,7 @@ export interface SessionsApi {
    * Reads a window of history events; page boundaries align to append-origin message
    * boundaries: one page = all raw events owned by a whole number of such messages (including
    * their chunk / tool events), never cut mid-message. Model-only replacement copies consume no
-   * `maxMessages`, so a compaction's provenance stays on the page of its replacement. The tail
+   * `maxMessages`, so a compaction's `compact/summary` record stays on the page of its replacement. The tail
    * page (beforeSeq absent) additionally carries the in-flight
    * partial — chunk events already emitted for the last unfinalized message.
    * Each entry pairs the raw SessionEvent with the host-computed view (tool events whose
diff --git a/packages/host/apiproxy/tests/api-proxy-search.spec.ts b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
index 0220f4804b..8b2e030509 100644
--- a/packages/host/apiproxy/tests/api-proxy-search.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
@@ -165,7 +165,7 @@ describe('session.search', () => {
     expect(searchSessions).not.toHaveBeenCalled()
   })
 
-  it('rejects snippets whose provider provenance violates the Host filters', async () => {
+  it('rejects snippets whose recorded provider violates the Host filters', async () => {
     const ctx = await baseContext()
     const visible = hit('visible')
     ctx.sessions.create(visible.header.id, { meta: visible.header })
diff --git a/packages/host/apiproxy/tests/api-proxy-view.spec.ts b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
index 9810ff5cb8..8b82a99d27 100644
--- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
@@ -236,7 +236,7 @@ describe('mux live view computation', () => {
     expect('view' in (byKey.get('tool/result:h-plain') ?? {})).toBe(false)
   })
 
-  it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
+  it('counts only append-origin messages toward maxMessages and keeps each compaction summary with its replacement', async () => {
     const { ctx } = await harness()
     const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
     const session = ctx.sessions.create()
@@ -247,7 +247,7 @@ describe('mux live view computation', () => {
     const third = appendUserText(session, 'second prompt')
     appendAssistantText(session, 'second reply', 2)
     const shadowed = [...session.surface.nodes]
-    // A compaction transaction: log-only provenance immediately followed by the
+    // A compaction transaction: a log-only summary record immediately followed by the
     // replacement that shadows the range.
     const summary = appendExtension(session, 'compact/summary', {
       summary: [{ type: 'text', text: 'summary' }],
@@ -277,7 +277,7 @@ describe('mux live view computation', () => {
     expect(messages.map(event => event.seq)).toEqual([third.seq, third.seq + 1, third.seq + 3])
     expect(page.some(event => event.seq === first.seq)).toBe(false)
     expect(response.result.value.hasMore).toBe(true)
-    // The range stays contiguous, so the checkpoint's provenance is readable on
+    // The range stays contiguous, so the checkpoint's summary record is readable on
     // the same page as the checkpoint itself.
     const summaryIndex = page.findIndex(event => event.seq === summary.seq)
     expect(summaryIndex).toBeGreaterThan(-1)
diff --git a/packages/interaction/commands/src/index.ts b/packages/interaction/commands/src/index.ts
index 64a9f8e8c8..94c4861e66 100644
--- a/packages/interaction/commands/src/index.ts
+++ b/packages/interaction/commands/src/index.ts
@@ -18,7 +18,7 @@ const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/u
 
 /**
  * Producer record for one command invocation (the `command/run` event's
- * provenance slot). Merge-extensible sum type mirroring `MessageSourceMap`'s
+ * source slot). Merge-extensible sum type mirroring `MessageSourceMap`'s
  * shape; minimal today because every executor caller is a human-facing UI
  * surface dispatching a human-typed line, so the sole variant is `user`.
  */
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 37ea49150b..eea304b414 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: eb67ce889193aadbd694d7aae53e47c7d20703be
-README.zh.md: 8b8e5e6a219841d700db7161a7352a1880c41165
+README.md: 4ad669344056a8290057cd39cbde56b0a2d80ba4
+README.zh.md: 96e1ef2dd3219e8b1fe0d5afbf5c784d9c3e42d5
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index eb67ce8891..4ad6693440 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -133,9 +133,9 @@ Credentials never enter that collection. The harness resolves a route's key thro
 
 The selected model descriptor supplies the protocol implementation. This includes native API differences such as OpenAI models whose descriptor uses the Responses API rather than Chat Completions; the harness adapter does not hardcode endpoint selection by model name.
 
-Successful assistant responses store a versioned, lossless-JSON replay state beside their durable provider/model provenance. At request time, `LlmService` passes replay state only when the historical provider route and target provider route are currently owned by this same `PiAiAdapter` instance. The adapter validates the state and restores pi-ai response ids and provider signatures even when the target provider or model changes; pi-ai then decides which metadata its target API can reuse. History without replay state is translated as foreign provider-neutral content and never impersonates a native pi-ai response.
+Successful assistant responses store a versioned, lossless-JSON replay state beside the provider and model that produced them. At request time, `LlmService` passes replay state only when the historical provider route and target provider route are currently owned by this same `PiAiAdapter` instance. The adapter validates the state and restores pi-ai response ids and provider signatures even when the target provider or model changes; pi-ai then decides which metadata its target API can reuse. History without replay state is translated as foreign provider-neutral content and never impersonates a native pi-ai response.
 
-If a listener rewrites assembled assistant content, the loop drops replay state before logging the message because its provider metadata no longer describes the content. Invalid versions, malformed metadata, provenance provider/model mismatches, and content/block mismatches fail explicitly with `LlmError('INVALID_REPLAY_STATE')`.
+If a listener rewrites assembled assistant content, the loop drops replay state before logging the message because its provider metadata no longer describes the content. Invalid versions, malformed metadata, provider/model mismatches between the message and replay state, and content/block mismatches fail explicitly with `LlmError('INVALID_REPLAY_STATE')`.
 
 ## Vocabulary differences
 
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index 8b8e5e6a21..96e1ef2dd3 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -133,9 +133,9 @@ profile 的 `models` 列表是*替换*该路由已安装 catalog，而不是扩
 
 所选模型 descriptor 提供协议实现。这包括原生 API 差异，例如 descriptor 使用 Responses API 而非 Chat Completions 的 OpenAI 模型；harness 适配器不会按模型名称硬编码端点选择。
 
-成功的 assistant 响应会在自身持久提供方／模型溯源旁存储经版本化的无损 JSON 回放状态。请求时，`LlmService` 只有在历史提供方路由与目标提供方路由当前由同一个 `PiAiAdapter` 实例拥有时，才会传递回放状态。即使目标提供方或模型改变，适配器也会验证状态并恢复 pi-ai 响应 id 与提供方 signature；随后由 pi-ai 判定目标 API 可以复用哪些元数据。没有回放状态的历史会被转换为外来的、与提供方无关的内容，绝不伪装为原生 pi-ai 响应。
+成功的 assistant 响应会将经版本化的无损 JSON 回放状态与生成该响应的提供方和模型一同存储。请求时，`LlmService` 只有在历史提供方路由与目标提供方路由当前由同一个 `PiAiAdapter` 实例拥有时，才会传递回放状态。即使目标提供方或模型改变，适配器也会验证状态并恢复 pi-ai 响应 id 与提供方 signature；随后由 pi-ai 判定目标 API 可以复用哪些元数据。没有回放状态的历史会被转换为外来的、与提供方无关的内容，绝不伪装为原生 pi-ai 响应。
 
-如果 listener 改写已组装 assistant 内容，loop 会在记录消息前丢弃回放状态，因为其提供方元数据不再描述该内容。无效版本、格式错误元数据、溯源提供方／模型不匹配，以及内容／块不匹配都会显式以 `LlmError('INVALID_REPLAY_STATE')` 失败。
+如果 listener 改写已组装 assistant 内容，loop 会在记录消息前丢弃回放状态，因为其提供方元数据不再描述该内容。无效版本、格式错误元数据、消息与回放状态之间的提供方／模型不匹配，以及内容／块不匹配都会显式以 `LlmError('INVALID_REPLAY_STATE')` 失败。
 
 ## 词汇差异
 
diff --git a/packages/llm/llm-pi-ai/tests/convert.spec.ts b/packages/llm/llm-pi-ai/tests/convert.spec.ts
index d125578b7f..b71d67b6c7 100644
--- a/packages/llm/llm-pi-ai/tests/convert.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/convert.spec.ts
@@ -102,7 +102,7 @@ describe('toPiContext', () => {
     expect((context.messages[0] as AssistantMessage).stopReason).toBe('stop')
   })
 
-  it('preserves model provenance for foreign assistant messages without replay state', () => {
+  it('preserves provider and model for foreign assistant messages without replay state', () => {
     const context = toPiContext({
       provider: 'openai',
       model: 'new-model',
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 4b1eda16c0..c4e8277b42 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
-README.md: ddbc2ea482ca0848fb0ee0813839cf5ff1829bcc
-README.zh.md: 0ebb99c6e3743b881905110985575d348f1c7601
+README.md: a437a689e934701b925dbf5a39a912c3af7dd46b
+README.zh.md: 7ed0c9c8a93e102b3d350be48be3a07e30011582
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index ddbc2ea482..a437a689e9 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -21,7 +21,7 @@ An adapter registry plus a single streaming call surface, interceptable via a wa
 - `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` Discover the models one registered provider currently advertises.
 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>` Resolve validated exact-model identity plus available context, output-default, and reasoning metadata from the owning adapter, with optional cancellation for asynchronous adapters.
 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>` Validate an explicit effort and materialize adapter-configured call defaults without clamping.
-- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` Resolve a config plus detached context metadata and adapter-default provenance in one exact-model lookup, then capture its current adapter registration and immutable retry policy as one cancellable, one-shot call.
+- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` Resolve a config plus detached context metadata and markers for fields supplied by adapter defaults in one exact-model lookup, then capture its current adapter registration and immutable retry policy as one cancellable, one-shot call.
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` Stream one model call as raw chunks (token-level deltas). Consumers assemble the chunks into blocks/messages with `BlockAssembler`.
 
 `LlmService` normalizes failures from final adapter selection, synchronous dispatch, iterator construction, and iteration into the stream protocol's single terminal form: `finish { kind: 'error' | 'aborted', failure }`. A failure after partial deltas may leave content blocks open; consumers discard that incomplete output. Errors from `llm/stream` middleware, nested calls, adapter cleanup, and downstream consumers remain thrown because they are plugin or consumer failures rather than model-request outcomes. A prepared call exposes the immutable retry policy captured with its exact adapter registration; a route handled entirely by middleware has no serving policy.
@@ -51,13 +51,13 @@ Exact-model metadata is a separate correctness query, not a catalog decoration o
 
 `Message` is the shared immutable value used by delivery, durable history, and model requests. Every message has a required `MessageId`, role, content, and typed source from creation onward. `createMessage(input)` mints the identity and returns a detached deep-frozen value; `createUserMessage({ content, source })` fixes the user role; `createAssistantMessage({ content, source })` fixes the assistant role and model source kind; `createToolResultMessage({ callId, content, isError })` fixes the user role and couples the tool source to its result block; `freezeMessage(message)` imports an identity that already exists and never replaces it. Message rewrites preserve the identity and produce another frozen value. Browser code imports these value constructors from the dependency-minimal `@deepseek-ai/dsh-llm/message` entry instead of the service-bearing package root.
 
-Message content is an array of typed blocks: `text`, `reasoning`, `tool-call`, `tool-result`. The union is derived from the merge-extensible `ContentBlockMap`, so plugins can add block types via declaration merging. Assistant messages use a model source carrying provider/model provenance and optional adapter-private replay state. Before dispatch, `LlmService` retains that state only when the historical provider route and target provider route are currently owned by the exact same adapter instance; the adapter then decides whether it can restore or convert the state across models/providers. The core block set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the map together with the adapter/UI/compaction support that honors it.
+Message content is an array of typed blocks: `text`, `reasoning`, `tool-call`, `tool-result`. The union is derived from the merge-extensible `ContentBlockMap`, so plugins can add block types via declaration merging. Assistant messages use a model source carrying the provider and model that produced them plus optional adapter-private replay state. Before dispatch, `LlmService` retains that state only when the historical provider route and target provider route are currently owned by the exact same adapter instance; the adapter then decides whether it can restore or convert the state across models/providers. The core block set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the map together with the adapter/UI/compaction support that honors it.
 
 Streaming is a raw chunk protocol (`block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`). Every adapter outcome reaches consumers as one terminal `finish`; operational failure uses its `error` or `aborted` reason rather than throwing across the stream API. `BlockAssembler` is the single shared implementation that assembles chunks into blocks/messages.
 
 ### Call configuration (`call-config.ts`)
 
-`LlmCallConfig` is the provider, model, optional adapter-owned reasoning effort, and sampling scalars of one conversation's requests (`provider`, `model`, `reasoningEffort`, `temperature`, `maxTokens`, `stop` — each mapping 1:1 onto the same-named `GenerateOptions` field). It is per-conversation state recorded in the session log as part of the request header (see the dsh-session `request/header` events), never a silently-adjustable per-call knob: the `agent/request` waterfall proposes a replacement, `prepareCall()` validates it and materializes adapter defaults under the turn signal, and the loop logs the effective value plus adapter-default provenance before using the prepared call's registration-bound stream. The next proposal omits marked defaults so a changed route resolves its own values; unmarked explicit fields persist. `callConfigEquals(a, b)` is the field-wise real-change detector; `deepFreeze(value)` is the ownership helper the loop applies to every built request before dispatch (`llm/stream` listeners and adapters read, never rewrite). `markAgentLoopRequest()` gives that exact object process-local loop provenance, and `isAgentLoopRequest()` lets observers distinguish it from independently logged auxiliary calls that may also be frozen and session-associated. `GenerateOptions.purpose` classifies logged auxiliary compaction and session-title calls so adapters can apply purpose-specific transport policy without changing ordinary conversation requests.
+`LlmCallConfig` is the provider, model, optional adapter-owned reasoning effort, and sampling scalars of one conversation's requests (`provider`, `model`, `reasoningEffort`, `temperature`, `maxTokens`, `stop` — each mapping 1:1 onto the same-named `GenerateOptions` field). It is per-conversation state recorded in the session log as part of the request header (see the dsh-session `request/header` events), never a silently-adjustable per-call knob: the `agent/request` waterfall proposes a replacement, `prepareCall()` validates it and materializes adapter defaults under the turn signal, and the loop logs the effective value plus markers for fields supplied by adapter defaults before using the prepared call's registration-bound stream. The next proposal omits marked defaults so a changed route resolves its own values; unmarked explicit fields persist. `callConfigEquals(a, b)` is the field-wise real-change detector; `deepFreeze(value)` is the ownership helper the loop applies to every built request before dispatch (`llm/stream` listeners and adapters read, never rewrite). `markAgentLoopRequest()` marks that exact object as created by the process-local agent loop, and `isAgentLoopRequest()` lets observers distinguish it from independently logged auxiliary calls that may also be frozen and session-associated. `GenerateOptions.purpose` classifies logged auxiliary compaction and session-title calls so adapters can apply purpose-specific transport policy without changing ordinary conversation requests.
 
 ### App attribution (`attribution.ts`)
 
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 0ebb99c6e3..7ed0c9c8a9 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -21,7 +21,7 @@
 - `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` 发现某个已注册提供方当前公布的模型。
 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>` 从拥有精确路由的适配器解析经校验的确切模型身份，以及可用上下文、输出默认值和推理（reasoning）元数据；异步适配器可选地支持取消。
 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>` 校验显式推理强度，并填入适配器配置的调用默认值，但不自动调整。
-- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` 在一次精确模型查询中解析配置、脱耦的上下文元数据与适配器默认值溯源，再将当前适配器注册和不可变重试策略捕获为一次可取消、一次性调用。
+- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` 在一次精确模型查询中解析配置、脱耦的上下文元数据以及标明哪些字段由适配器默认值填入的标记，再将当前适配器注册和不可变重试策略捕获为一次可取消、一次性调用。
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` 将一次模型调用流式输出为原始分片（token 级增量）。消费方使用 `BlockAssembler` 将分片组装为块／消息。
 
 `LlmService` 将最终适配器选择、同步 dispatch、iterator 构造与迭代中的失败规范化为流协议唯一的终止形式：`finish { kind: 'error' | 'aborted', failure }`。部分增量输出后发生失败时，内容块可能仍未闭合；消费方会丢弃这些不完整输出。`llm/stream` middleware、嵌套调用、适配器清理和下游消费方的错误仍会抛出，因为它们属于插件或消费方失败，而非模型请求结果。已准备调用会暴露随其确切适配器注册一同捕获的不可变重试策略；完全由 middleware 处理的路由没有服务策略。
@@ -51,13 +51,13 @@
 
 `Message` 是投递、持久历史和模型请求共享的不可变值。每条消息从创建起都必须具有 `MessageId`、角色、内容和带类型的来源。`createMessage(input)` 生成标识，并返回与输入分离且深度冻结的值；`createUserMessage({ content, source })` 固定 user 角色；`createAssistantMessage({ content, source })` 固定 assistant 角色与模型来源类别；`createToolResultMessage({ callId, content, isError })` 固定 user 角色，并将工具来源与其结果块耦合；`freezeMessage(message)` 导入已有标识，绝不将其替换。改写消息时会保留标识，并产生另一个冻结值。浏览器端代码会从依赖最少的 `@deepseek-ai/dsh-llm/message` 入口导入这些值构造函数，而不是从包含服务的包根入口导入。
 
-消息内容是类型化内容块数组：`text`、`reasoning`、`tool-call`、`tool-result`。联合从可合并扩展的 `ContentBlockMap` 派生，因此插件可以通过 declaration merging 添加块类型。assistant 消息使用模型来源，其中携带提供方／模型溯源与可选适配器私有回放状态。dispatch 前，`LlmService` 只在历史提供方路由与目标提供方路由当前由完全相同的适配器实例拥有时才保留该状态；随后由适配器判定能否在模型／提供方间恢复或转换该状态。核心块集只包含每条已发布路径都支持的块。多模态内容（图像、音频等）没有核心块类型；需要它的功能会通过 map 添加，并一并添加相应的适配器／UI／压缩（compaction）支持。
+消息内容是类型化内容块数组：`text`、`reasoning`、`tool-call`、`tool-result`。联合从可合并扩展的 `ContentBlockMap` 派生，因此插件可以通过 declaration merging 添加块类型。assistant 消息使用模型来源，其中携带生成该消息的提供方和模型，以及可选的适配器私有回放状态。dispatch 前，`LlmService` 只在历史提供方路由与目标提供方路由当前由完全相同的适配器实例拥有时才保留该状态；随后由适配器判定能否在模型／提供方间恢复或转换该状态。核心块集只包含每条已发布路径都支持的块。多模态内容（图像、音频等）没有核心块类型；需要它的功能会通过 map 添加，并一并添加相应的适配器／UI／压缩（compaction）支持。
 
 流式输出是原始分片协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）。每个适配器结果都以一个终止 `finish` 到达消费方；运行故障使用其 `error` 或 `aborted` 原因，而不会跨流 API 抛出。`BlockAssembler` 是将分片组装为块／消息的唯一共享实现。
 
 ### 调用配置（`call-config.ts`）
 
-`LlmCallConfig` 是一个会话中各次请求的提供方、模型、可选的适配器持有推理强度和采样标量（`provider`、`model`、`reasoningEffort`、`temperature`、`maxTokens`、`stop`，每个都与同名 `GenerateOptions` 字段 1:1 映射）。它是作为请求标头一部分记录在会话日志中的每会话状态（见 dsh-session `request/header` 事件），绝不是可静默调整的每次调用旋钮：`agent/request` waterfall 会提议替换，`prepareCall()` 在轮次 signal 控制下校验它并填入适配器默认值，loop 随后记录生效值及适配器默认值来源，再使用已准备调用中与注册绑定的流。下一次提议会省略带标记的默认值，使变更后的路由解析自身的值；未带标记的显式字段会保留。`callConfigEquals(a, b)` 是逐字段真实变更检测器；`deepFreeze(value)` 是 loop 在 dispatch 前对每个已构建请求应用的所有权 helper（`llm/stream` listener 与适配器只读，绝不改写）。`markAgentLoopRequest()` 为该精确对象添加进程本地 loop 溯源，`isAgentLoopRequest()` 让观测方可以将其与同样可能冻结并关联会话、但独立记录的辅助调用区分。`GenerateOptions.purpose` 对已记录辅助压缩与会话标题调用分类，让适配器可以应用目的特定传输策略，而不改变普通会话请求。
+`LlmCallConfig` 是一个会话中各次请求的提供方、模型、可选的适配器持有推理强度和采样标量（`provider`、`model`、`reasoningEffort`、`temperature`、`maxTokens`、`stop`，每个都与同名 `GenerateOptions` 字段 1:1 映射）。它是作为请求标头一部分记录在会话日志中的每会话状态（见 dsh-session `request/header` 事件），绝不是可静默调整的每次调用旋钮：`agent/request` waterfall 会提议替换，`prepareCall()` 在轮次 signal 控制下校验它并填入适配器默认值，loop 随后记录生效值以及标明哪些字段由适配器默认值填入的标记，再使用已准备调用中与注册绑定的流。下一次提议会省略带标记的默认值，使变更后的路由解析自身的值；未带标记的显式字段会保留。`callConfigEquals(a, b)` 是逐字段真实变更检测器；`deepFreeze(value)` 是 loop 在 dispatch 前对每个已构建请求应用的所有权 helper（`llm/stream` listener 与适配器只读，绝不改写）。`markAgentLoopRequest()` 将该精确对象标记为由进程本地 agent loop 创建，`isAgentLoopRequest()` 让观测方可以将其与同样可能冻结并关联会话、但独立记录的辅助调用区分。`GenerateOptions.purpose` 对已记录辅助压缩与会话标题调用分类，让适配器可以应用目的特定传输策略，而不改变普通会话请求。
 
 ### 应用归因（`attribution.ts`）
 
diff --git a/packages/llm/llm/src/call-config.ts b/packages/llm/llm/src/call-config.ts
index 848654ad3b..6bf108dc1a 100644
--- a/packages/llm/llm/src/call-config.ts
+++ b/packages/llm/llm/src/call-config.ts
@@ -61,7 +61,7 @@ export function callConfigEquals(a: LlmCallConfig, b: LlmCallConfig): boolean {
 /**
  * Mark one exact request object as assembled by dsh-agent-loop.
  * @param request - loop-owned request envelope before LLM dispatch.
- * @returns the same request object with process-local loop provenance.
+ * @returns the same request object marked as created by the process-local agent loop.
  */
 export function markAgentLoopRequest<T extends GenerateOptions>(request: T): T {
   AGENT_LOOP_REQUESTS.add(request)
diff --git a/packages/llm/llm/src/message.ts b/packages/llm/llm/src/message.ts
index 7db1f855a8..c4032f5294 100644
--- a/packages/llm/llm/src/message.ts
+++ b/packages/llm/llm/src/message.ts
@@ -4,7 +4,7 @@ import { MessageId, type CallId } from './brand.ts'
 import { deepFreeze } from './call-config.ts'
 import type { ContentBlock, ToolResultBlock } from './types.ts'
 
-/** Provider ownership and adapter-private replay data for an assistant message. */
+/** Provider/model identity and adapter-private replay data for an assistant message. */
 export interface AssistantProvenance {
   /** Provider route that produced the message. */
   provider: string
@@ -31,7 +31,7 @@ export interface ToolMessageSource {
 
 /**
  * What SHAPE of information a producer-supplied context carries, declared by
- * the producer beside its provenance.
+ * the producer beside the source fields it supplied.
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
@@ -133,7 +133,7 @@ export interface Message {
   readonly role: 'system' | 'user' | 'assistant'
   /** Exact model-facing blocks. */
   readonly content: ContentBlock[]
-  /** Required producer provenance. */
+  /** Required source fields supplied by the producer. */
   readonly source: MessageSource
 }
 
@@ -200,7 +200,7 @@ export function createUserMessage<T extends NewUserMessage>(
 
 /**
  * Create one identified model-produced assistant message and freeze it before publication.
- * @param input - complete content and model provenance for a new assistant message.
+ * @param input - complete content plus the provider, model, and optional replay state for a new assistant message.
  * @returns an immutable assistant message with fixed role/source tags and a fresh stable identity.
  */
 export function createAssistantMessage(
diff --git a/packages/llm/llm/tests/message.spec.ts b/packages/llm/llm/tests/message.spec.ts
index c906c97e8b..846d37c9df 100644
--- a/packages/llm/llm/tests/message.spec.ts
+++ b/packages/llm/llm/tests/message.spec.ts
@@ -74,7 +74,7 @@ describe('message construction', () => {
     expect(Object.isFrozen(message.source)).toBe(true)
   })
 
-  it('couples tool-result content and provenance to one call identity', () => {
+  it('couples tool-result content and its cited call seq to one call identity', () => {
     const callId = CallId('call-1')
     const message = createToolResultMessage({
       callId,
diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts
index 990d1c38ea..414c50cd28 100644
--- a/packages/llm/llm/tests/service.spec.ts
+++ b/packages/llm/llm/tests/service.spec.ts
@@ -1046,7 +1046,7 @@ describe('LlmService', () => {
     })
   })
 
-  it('strips replay state but preserves provenance when the target uses a different adapter instance', async () => {
+  it('strips replay state but preserves provider and model when the target uses a different adapter instance', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     ctx.llm.registerAdapter(['historical'], new RecordingAdapter(SCRIPT))
diff --git a/packages/llm/token-meter/README.i18n.yaml b/packages/llm/token-meter/README.i18n.yaml
index 5b2d79f7fb..9b68fa047a 100644
--- a/packages/llm/token-meter/README.i18n.yaml
+++ b/packages/llm/token-meter/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/llm/token-meter/README.md
-README.md: 8f868f25f3c4caf1fdab5b50965aab41efecf5af
-README.zh.md: e3908ecea17b16669458f89a6359a432f5b24c0c
+README.md: 929d0322f6268562a10b9ab715cc0330800966b5
+README.zh.md: 40cea07c7dea20d0af9bf67ade2cb4164f7aed08
diff --git a/packages/llm/token-meter/README.md b/packages/llm/token-meter/README.md
index 8f868f25f3..929d0322f6 100644
--- a/packages/llm/token-meter/README.md
+++ b/packages/llm/token-meter/README.md
@@ -17,9 +17,9 @@ The estimator has no settings. It intentionally uses one fixed heuristic: four c
 
 `measure()` synchronizes once and returns one detached, deeply immutable snapshot. `totalTokens` is request-and-response pressure, while `surfaceTokens` is the surface-only heuristic total and equals the sum of `nodes[].tokens`. A `requestHeader` override affects pressure fields only; the surface fields still describe the current session. Every call clones the positional nodes, so measurement is O(surface).
 
-The fold tracks full request-header snapshots, step boundaries, surface appends and replacements, successful assistant messages, provider usage, and assistant-chunk provenance. Provider usage is reused only when the latest successful call's canonical request envelope matches the measured envelope and its total is no lower than that call's full heuristic anchor; a later success replaces the earlier anchor. Otherwise the complete current envelope and surface are estimated. Surface changes remain signed relative to a matching anchor, including negative deltas after shrinking replacements.
+The fold tracks full request-header snapshots, step boundaries, surface appends and replacements, successful assistant messages, provider usage, and the chunk seqs cited by each assistant message. Provider usage is reused only when the latest successful call's canonical request envelope matches the measured envelope and its total is no lower than that call's full heuristic anchor; a later success replaces the earlier anchor. Otherwise the complete current envelope and surface are estimated. Surface changes remain signed relative to a matching anchor, including negative deltas after shrinking replacements.
 
-Usage accounting sums disjoint input, cache-read, cache-write, and output buckets; reasoning is not added again. Every successful call records an assistant anchor, including content-less calls. An explicit empty provenance list means a known empty provider stream, while absent legacy provenance conservatively treats the durable assistant output as provider output.
+Usage accounting sums disjoint input, cache-read, cache-write, and output buckets; reasoning is not added again. Every successful call records an assistant anchor, including content-less calls. An explicit empty `sourceEventSeqs` list means a known empty provider stream, while an absent legacy list conservatively treats the durable assistant output as provider output.
 
 ## Session projections
 
@@ -65,4 +65,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **The fixed heuristic is approximate** — content without reusable provider usage is priced by character count plus structural overhead, not an exact provider tokenizer or request serializer.
 - **Every measurement clones the current surface** — coherent immutable snapshots make reads O(surface), including below-threshold pressure checks.
 - **Provider usage is only reusable for an identical canonical envelope** — prompt, prefix, tools, provider, model, or call-config changes deliberately fall back to full heuristic estimation.
-- **Legacy provenance is conservative** — assistant messages without `sourceEventSeqs` cannot distinguish provider output from listener rewrites, so the fold avoids claiming a known empty or exact chunk stream.
+- **Missing legacy source seqs are handled conservatively** — assistant messages without `sourceEventSeqs` cannot distinguish provider output from listener rewrites, so the fold avoids claiming a known empty or exact chunk stream.
diff --git a/packages/llm/token-meter/README.zh.md b/packages/llm/token-meter/README.zh.md
index e3908ecea1..40cea07c7d 100644
--- a/packages/llm/token-meter/README.zh.md
+++ b/packages/llm/token-meter/README.zh.md
@@ -17,9 +17,9 @@
 
 `measure()` 会同步一次，并返回一个独立且深度不可变的快照。`totalTokens` 是请求与响应压力，`surfaceTokens` 是仅表层启发式总量，等于 `nodes[].tokens` 之和。`requestHeader` 覆盖只影响压力字段；表层字段仍描述当前会话。每次调用都会克隆带位置的节点，因此测量是 O(surface)。
 
-fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成功 assistant 消息、提供方用量和 assistant 分片溯源。只有当最新成功调用的规范请求 envelope 与已测量 envelope 匹配，且其总量不低于该调用的完整启发式锚点时，才会复用提供方用量；后续成功会替换较早锚点。否则会对当前 envelope 与表层进行完整估算。表层变更保持相对于匹配锚点的带符号值，包括缩减替换后的负 delta。
+fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成功 assistant 消息、提供方用量，以及每条 assistant 消息引用的分片 seq。只有当最新成功调用的规范请求 envelope 与已测量 envelope 匹配，且其总量不低于该调用的完整启发式锚点时，才会复用提供方用量；后续成功会替换较早锚点。否则会对当前 envelope 与表层进行完整估算。表层变更保持相对于匹配锚点的带符号值，包括缩减替换后的负 delta。
 
-用量计量会求和不重叠的输入、cache-read、cache-write 与输出 bucket；不会再次添加推理（reasoning）。每次成功调用都会记录一个 assistant 锚点，包括无内容调用。显式空溯源列表表示已知空提供方流，而遗留溯源缺失时，fold 会保守地将持久 assistant 输出视为提供方输出。
+用量计量会求和不重叠的输入、cache-read、cache-write 与输出 bucket；不会再次添加推理（reasoning）。每次成功调用都会记录一个 assistant 锚点，包括无内容调用。显式的空 `sourceEventSeqs` 列表表示已知空提供方流；遗留记录缺少该列表时，fold 会保守地将持久 assistant 输出视为提供方输出。
 
 ## 会话投影
 
@@ -65,4 +65,4 @@ fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成
 - **固定启发式规则是近似值**：没有可复用提供方用量的内容按字符数加结构开销计价，而不是使用精确提供方 tokenizer 或请求 serializer。
 - **每次测量都会克隆当前表层**：一致且不可变的快照使读取成为 O(surface)，包括低于阈值的压力检查。
 - **提供方用量只能为完全相同的规范 envelope 复用**：提示词、前缀、工具、提供方、模型或调用配置变更都会有意回退到完整启发式估算。
-- **遗留溯源采取保守策略**：没有 `sourceEventSeqs` 的 assistant 消息无法区分提供方输出与 listener 改写，因此 fold 不会声称已知空流或精确分片流。
+- **保守处理缺少源事件 seq 的遗留记录**：没有 `sourceEventSeqs` 的 assistant 消息无法区分提供方输出与 listener 改写，因此 fold 不会声称已知空流或精确分片流。
diff --git a/packages/llm/token-meter/src/index.ts b/packages/llm/token-meter/src/index.ts
index 31991b482a..caea2a2701 100644
--- a/packages/llm/token-meter/src/index.ts
+++ b/packages/llm/token-meter/src/index.ts
@@ -270,9 +270,9 @@ export class TokenMeterService extends Service {
   }
 
   /**
-   * Reassemble provider output from exact chunk provenance for a usage anchor.
-   * Missing legacy provenance conservatively treats the durable output as the
-   * provider output; explicit empty provenance prices a known empty stream.
+   * Reassemble provider output from the exact cited chunk seqs for a usage anchor.
+   * Missing legacy source seqs conservatively treat the durable output as the
+   * provider output; an explicit empty list prices a known empty stream.
    */
   private _estimateProviderAssistant(
     session: Session,
diff --git a/packages/llm/token-meter/tests/token-meter.spec.ts b/packages/llm/token-meter/tests/token-meter.spec.ts
index 7009cc6a33..5638ce642b 100644
--- a/packages/llm/token-meter/tests/token-meter.spec.ts
+++ b/packages/llm/token-meter/tests/token-meter.spec.ts
@@ -313,7 +313,7 @@ describe('replay anchors and surface folds', () => {
     expect(advanced.surfaceDeltaTokens).toBeGreaterThan(0)
   })
 
-  it('distinguishes explicit empty provenance from absent legacy provenance', () => {
+  it('distinguishes an explicit empty source-event list from an absent legacy list', () => {
     const explicit = Session.create(SessionId('explicit-empty'))
     const legacy = Session.create(SessionId('legacy-absent'))
     appendSuccessfulCall(explicit, header('deepseek-v4-flash'), {
@@ -503,7 +503,7 @@ describe('malformed replay and listener lifecycle', () => {
     )
   })
 
-  it('rejects invalid assistant provenance', () => {
+  it('rejects invalid assistant source-event references', () => {
     const cases: Array<{
       name: string
       appendSource(session: Session): number[]
@@ -553,7 +553,7 @@ describe('malformed replay and listener lifecycle', () => {
     }
   })
 
-  it('rejects repeated and non-earlier assistant provenance', () => {
+  it('rejects repeated and non-earlier assistant source-event references', () => {
     const duplicate = Session.create(SessionId('duplicate-source'))
     duplicate.append('step/start', { turn: 1, step: 1 })
     appendHeader(duplicate, header('deepseek-v4-flash'))
diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts
index 7e9405d14b..0b1cf3a34d 100644
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -27,7 +27,7 @@ export interface Config {
    * non-empty override asserts full enforcement and skips built-in selection and
    * probing. A runner that starts but refuses its profile must be identifiable by
    * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
-   * attributable `ENOENT` or `EACCES` with runner argv[0] provenance becomes an
+   * attributable `ENOENT` or `EACCES` whose error path equals runner argv[0] becomes an
    * infrastructure failure.
    */
   runnerCommand?: string[]
diff --git a/packages/scaffold/server/src/server.ts b/packages/scaffold/server/src/server.ts
index 797e0cbfea..e6c22d7ff2 100644
--- a/packages/scaffold/server/src/server.ts
+++ b/packages/scaffold/server/src/server.ts
@@ -87,7 +87,7 @@ export class HarnessSdkServer {
     this.disposers.push(ctx.on('subagent/end', function (this: Scoped<SubagentService>, info: SubagentRunEndInfo) {
       const parent = subagentParentOf(this)
       // This protocol reports only in-process child sessions. The service
-      // snapshots the provider's exact run provenance through child disposal;
+      // snapshots the provider name and local flag through child disposal;
       // matching ids or parent lineage alone never establishes locality.
       if (!info.local) return
       const payload: SubagentFinishedNotification = {
diff --git a/packages/scaffold/server/tests/server.spec.ts b/packages/scaffold/server/tests/server.spec.ts
index c9d1944781..0acfcfccef 100644
--- a/packages/scaffold/server/tests/server.spec.ts
+++ b/packages/scaffold/server/tests/server.spec.ts
@@ -664,7 +664,7 @@ describe('HarnessSdkServer', () => {
     }
   })
 
-  it('uses explicit local provenance when start was missed and ignores remote runs', async () => {
+  it('uses the recorded local flag when start was missed and ignores remote runs', async () => {
     const storageDir = await mkdtemp(join(tmpdir(), 'dsh-jsonrpc-subagent-fallback-'))
     const ctx = await makeHarness(storageDir)
     let parentHandle: AgentHandle | undefined
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index 302fd4c9b3..a8fa2b4cff 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -768,7 +768,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>',
-        jsDoc: '/**\n * Trace one event\'s direct positional and provenance relationships.\n * @param request - target session id and event seq.\n * @param signal - optional cancellation for persisted source resolution.\n * @returns source header, direct links, and the target\'s positional replacement chain.\n * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.\n */',
+        jsDoc: '/**\n * Trace one event\'s direct positional replacements and cited source events.\n * @param request - target session id and event seq.\n * @param signal - optional cancellation for persisted source resolution.\n * @returns source header, direct links, and the target\'s positional replacement chain.\n * @throws when source resolution fails, the target is absent, or surface/source-event validation fails.\n */',
       },
       {
         signature: 'async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>',
@@ -916,7 +916,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'abstract saveText(input: SaveTextSpill): Promise<SpillRef>',
-        jsDoc: '/**\n * Persist `input.content` to a session-scoped spill artifact.\n * @param input - the owner, provenance, suggested name, and full text to save.\n * @returns the saved artifact\'s {@link SpillRef}; rejects on a storage failure.\n */',
+        jsDoc: '/**\n * Persist `input.content` to a session-scoped spill artifact.\n * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.\n * @returns the saved artifact\'s {@link SpillRef}; rejects on a storage failure.\n */',
       },
     ],
   },
@@ -962,7 +962,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>',
-        jsDoc: '/**\n * Deliver one later message to a continuable child as its next FIFO turn. A\n * resident child\'s Agent inbox accepts it directly (waking a `waiting`\n * Activation), while an absent one is cold-resumed from its persisted\n * Session. The Agent inbox is the only queue, so every accepted message has\n * one observable order.\n * @param parent - the exact live direct parent authorizing this delivery.\n * @param childId - durable child session id.\n * @param content - user-role content to deliver.\n * @param options - durable provenance and caller cancellation, which stops the\n *   operation only before inbox acceptance.\n * @returns the accepted message\'s inbox id.\n * @throws when continuation services are unavailable, parent authority is\n *   rejected, or the message was not admitted.\n */',
+        jsDoc: '/**\n * Deliver one later message to a continuable child as its next FIFO turn. A\n * resident child\'s Agent inbox accepts it directly (waking a `waiting`\n * Activation), while an absent one is cold-resumed from its persisted\n * Session. The Agent inbox is the only queue, so every accepted message has\n * one observable order.\n * @param parent - the exact live direct parent authorizing this delivery.\n * @param childId - durable child session id.\n * @param content - user-role content to deliver.\n * @param options - the message source fields and caller cancellation, which stops the\n *   operation only before inbox acceptance.\n * @returns the accepted message\'s inbox id.\n * @throws when continuation services are unavailable, parent authority is\n *   rejected, or the message was not admitted.\n */',
       },
       {
         signature: 'interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void',
@@ -1134,7 +1134,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'pruneSession(session: Session): PruneResult',
-        jsDoc: '/**\n * Prune every over-budget tool result from one stable current-surface snapshot.\n * Each replacement preserves the complete event data except for `content`,\n * points at the shadowed node for durable provenance and replay, and is\n * immediately preceded by a `compact/prune` shadow-price event pricing the\n * shadowed node through the injected token meter, so pure consumers can\n * subtract it without per-node state.\n * @param session - session whose current surface is rewritten.\n * @returns landed replacements and aggregate Unicode-code-point savings.\n * @throws when the session rejects a replacement; replacements committed\n * earlier in the pass remain durable.\n */',
+        jsDoc: '/**\n * Prune every over-budget tool result from one stable current-surface snapshot.\n * Each replacement preserves the complete event data except for `content`,\n * cites the shadowed node so replay can recover the replacement input, and is\n * immediately preceded by a `compact/prune` shadow-price event pricing the\n * shadowed node through the injected token meter, so pure consumers can\n * subtract it without per-node state.\n * @param session - session whose current surface is rewritten.\n * @returns landed replacements and aggregate Unicode-code-point savings.\n * @throws when the session rejects a replacement; replacements committed\n * earlier in the pass remain durable.\n */',
       },
     ],
   },
diff --git a/packages/session-query/session-query/README.i18n.yaml b/packages/session-query/session-query/README.i18n.yaml
index 423d3f2d90..3735d1c559 100644
--- a/packages/session-query/session-query/README.i18n.yaml
+++ b/packages/session-query/session-query/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/session-query/session-query/README.md
-README.md: b75c1f23264cfa7c9323970b3c1a77ddcfe69be0
-README.zh.md: 4f1c4749a847326fd9fbc0ffa627651c052ccd71
+README.md: 5d4d689477fca4fd6b01091f1304ff3065af7443
+README.zh.md: 957b5c39d9ff2127e7819ae01077fec51950b26f
diff --git a/packages/session-query/session-query/README.md b/packages/session-query/session-query/README.md
index b75c1f2326..5d4d689477 100644
--- a/packages/session-query/session-query/README.md
+++ b/packages/session-query/session-query/README.md
@@ -15,7 +15,7 @@ English | [中文](README.zh.md)
 - `readSurface(sessionId)` returns one cloned header, raw-log capture boundary, and the complete folded current surface in model-history order. A live session wins over persistence; compaction is observed before or after its replacement append, never as a synthetic mixture.
 - `readEvent(request, signal?)` returns a cloned header, the full target event, and a bounded raw-seq window. `before` and `after` default to zero and may not exceed `readWindowMax`.
 - `traceSession(sessionId, signal?)` reads the corpus once and returns immediate-to-outward ancestors plus deterministic recursive descendant trees. `complete: false` identifies the first missing parent; a target-connected cycle fails with `SESSION_QUERY_INVALID_LINEAGE`.
-- `traceEvent(request, signal?)` loads the logical log once and returns its cloned source header with direct positional replacements and direct logged provenance. `replacementChain` follows positional replacers to the final replacement; provenance links remain non-transitive.
+- `traceEvent(request, signal?)` loads the logical log once and returns its cloned source header with direct positional replacements and direct cited source-event links. `replacementChain` follows positional replacers to the final replacement; source-event links remain non-transitive.
 
 Persistence is optional and may mount or unmount dynamically. Cross-corpus listing and lineage tracing fail with `SESSION_QUERY_PERSISTENCE_FAILED` while mounted persistence is unreadable; a successfully read durable record that fails Session validation reports `SESSION_QUERY_CORRUPT_SESSION` instead. A title read, event trace, or event read targeting a known live session does not consult persistence, so durable backend health cannot make current in-memory state unreadable. Persisted title and event operations list before loading and reject a metadata mismatch rather than combining inconsistent observations. Lineage-trace cancellation is passed to persisted listing; event-trace and event-read cancellation is passed to persisted listing and inspection. Each waits for the started backend call to settle, then rejects with the signal's exact reason even when the backend ignored that signal. A pre-aborted known-live title read, event trace, or event read rejects before folding or snapshotting without consulting persistence. A batch title observation performs one metadata listing, inspects its unique persisted ids with at most `persistedInspectConcurrency` workers, and preserves each title's own observed header for downstream authorization. Cancellation starts no queued inspections and rejects only after already-started workers settle. `listSessions()` remains lightweight and does not load logs or index titles.
 
@@ -33,7 +33,7 @@ The package has no provider coordinator, fallback implementation, or standalone
 
 `SessionQueryError.code` is a closed union covering request validation, missing targets, malformed surfaces, source conflicts, persistence/index failures, cancellation, and invalid or stale cursors; the exact literals are defined in [`src/config.ts`](src/config.ts).
 
-`listEvents()`, `readSurface()`, and `traceEvent()` run the same one-pass `dsh-session` surface fold. A loaded log is valid only when event seqs are zero-based and contiguous, surface markers obey event-type eligibility, provenance arrays are nonempty and duplicate-free, references name earlier events, and each positional replacement names and cites every surface node it removes; every violation fails with `SESSION_QUERY_INVALID_SURFACE`.
+`listEvents()`, `readSurface()`, and `traceEvent()` run the same one-pass `dsh-session` surface fold. A loaded log is valid only when event seqs are zero-based and contiguous, surface markers obey event-type eligibility, source-event arrays are nonempty and duplicate-free, references name earlier events, and each positional replacement names and cites every surface node it removes; every violation fails with `SESSION_QUERY_INVALID_SURFACE`.
 
 ## Configuration
 
@@ -53,4 +53,4 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **No caller authorization** — this is trusted context-wide infrastructure; a future model tool or UI must constrain which sessions its caller may inspect.
-- **No registries or model-facing tool** — extractor and search-provider registries, recursive event-provenance traversal, and a model-facing tool are absent. The [tracing decision](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) owns relationship semantics; SQLite ownership and tokenizer decisions live in the [implemented search note](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md).
+- **No registries or model-facing tool** — extractor and search-provider registries, recursive traversal through cited source events, and a model-facing tool are absent. The [tracing decision](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) owns relationship semantics; SQLite ownership and tokenizer decisions live in the [implemented search note](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md).
diff --git a/packages/session-query/session-query/README.zh.md b/packages/session-query/session-query/README.zh.md
index 4f1c4749a8..957b5c39d9 100644
--- a/packages/session-query/session-query/README.zh.md
+++ b/packages/session-query/session-query/README.zh.md
@@ -15,7 +15,7 @@
 - `readSurface(sessionId)` 返回一个克隆 header、原始日志捕获边界，以及按模型历史顺序排列的完整折叠后当前表层。实时会话优先于持久化；压缩（compaction）只会在其替换追加之前或之后被观察，绝不会出现合成混合。
 - `readEvent(request, signal?)` 返回一个克隆 header、完整目标事件和有界的原始 seq 窗口。`before` 和 `after` 默认为 0，且不得超过 `readWindowMax`。
 - `traceSession(sessionId, signal?)` 只读取一次语料库，返回从直接父级向外的祖先，以及确定性的递归后代树。`complete: false` 标识第一个缺失父级；与目标相连的循环会以 `SESSION_QUERY_INVALID_LINEAGE` 失败。
-- `traceEvent(request, signal?)` 只加载一次逻辑日志，返回其克隆源 header、直接位置替换和直接已记录来源信息。`replacementChain` 沿位置替换者跟踪到最终替换；来源链接仍不传递。
+- `traceEvent(request, signal?)` 只加载一次逻辑日志，返回其克隆源 header、直接位置替换和直接引用的源事件链接。`replacementChain` 沿位置替换者跟踪到最终替换；源事件链接仍不传递。
 
 持久化是可选的，可动态挂载或卸载。已挂载持久化无法读取时，跨语料库列表和血缘跟踪以 `SESSION_QUERY_PERSISTENCE_FAILED` 失败；已经成功读取、但无法通过 Session 校验的持久化记录则以 `SESSION_QUERY_CORRUPT_SESSION` 失败。针对已知实时会话的标题读取、事件跟踪或事件读取不会查询持久化，因此持久化后端的健康状态无法使当前内存状态变得不可读。持久化标题和事件操作在加载前先执行列表查询，并在元数据不匹配时拒绝，而不会组合不一致的观察。血缘跟踪的取消信号会传递给持久化列表查询；事件跟踪和事件读取的取消信号会传递给持久化列表查询和检查。每项操作都会等待已启动的后端调用结算，然后使用信号的精确原因拒绝，即使后端忽略了该信号。针对已知实时会话且预先中止的标题读取、事件跟踪或事件读取会在 fold 或快照之前拒绝，且不查询持久化。批量标题观察执行一次元数据列表查询，使用最多 `persistedInspectConcurrency` 个 worker 检查唯一持久化 id，并保留每个标题自己观察到的 header，供下游授权使用。取消不会启动已排队检查，且只在已启动 worker 结算后拒绝。`listSessions()` 仍保持轻量，不加载日志或索引标题。
 
@@ -33,7 +33,7 @@
 
 `SessionQueryError.code` 是一个封闭联合，覆盖请求验证、缺失目标、格式错误的表层、来源冲突、持久化/索引失败、取消，以及无效或陈旧游标；精确字面值在 [`src/config.ts`](src/config.ts) 中定义。
 
-`listEvents()`、`readSurface()` 和 `traceEvent()` 执行同一个单遍 `dsh-session` 表层 fold。只有当事件 seq 从零开始且连续、表层标记符合事件类型的适用性要求、来源数组非空且无重复、引用指向较早事件，且每个位置替换都命名并引用它移除的每个表层节点时，加载的日志才有效；任何违规都以 `SESSION_QUERY_INVALID_SURFACE` 失败。
+`listEvents()`、`readSurface()` 和 `traceEvent()` 执行同一个单遍 `dsh-session` 表层 fold。只有当事件 seq 从零开始且连续、表层标记符合事件类型的适用性要求、源事件数组非空且无重复、引用指向较早事件，且每个位置替换都命名并引用它移除的每个表层节点时，加载的日志才有效；任何违规都以 `SESSION_QUERY_INVALID_SURFACE` 失败。
 
 ## 配置
 
@@ -53,4 +53,4 @@
 ## 已知限制与暂缓事项
 
 - **无调用方授权**：这是上下文范围内的可信基础设施；未来的模型工具或 UI 必须限制调用方可检查的会话。
-- **无注册表或面向模型工具**：尚未提供提取器和搜索提供方注册表、递归事件来源遍历以及面向模型的工具。[跟踪决策](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) 负责关系语义；SQLite 归属和 tokenizer 决策位于[已实现搜索记录](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md)。
+- **无注册表或面向模型工具**：尚未提供提取器和搜索提供方注册表、递归遍历所引用的源事件的能力，以及面向模型的工具。[跟踪决策](../../../.agents/notes/implemented/feature/2026-07-13-session-query-tracing.md) 负责关系语义；SQLite 归属和 tokenizer 决策位于[已实现搜索记录](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md)。
diff --git a/packages/session-query/session-query/src/index.ts b/packages/session-query/session-query/src/index.ts
index 7878026345..f2c6b57c66 100644
--- a/packages/session-query/session-query/src/index.ts
+++ b/packages/session-query/session-query/src/index.ts
@@ -283,11 +283,11 @@ export abstract class SessionQueryService extends Service {
   }
 
   /**
-   * Trace one event's direct positional and provenance relationships.
+   * Trace one event's direct positional replacements and cited source events.
    * @param request - target session id and event seq.
    * @param signal - optional cancellation for persisted source resolution.
    * @returns source header, direct links, and the target's positional replacement chain.
-   * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+   * @throws when source resolution fails, the target is absent, or surface/source-event validation fails.
    */
   async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation> {
     const loaded = await this._corpus.load(request.sessionId, signal)
diff --git a/packages/session-query/session-query/src/tracing.ts b/packages/session-query/session-query/src/tracing.ts
index d929317b50..681e6ce59a 100644
--- a/packages/session-query/session-query/src/tracing.ts
+++ b/packages/session-query/session-query/src/tracing.ts
@@ -60,7 +60,7 @@ export function currentSurfaceEvents(
  * @param sessionId - owner of the event log.
  * @param events - detached raw event log.
  * @param seq - target event seq.
- * @returns direct surface and provenance relationships.
+ * @returns direct surface replacements and relationships to cited source events.
  */
 export function traceEvent(
   sessionId: SessionId,
diff --git a/packages/session-query/session-query/src/types.ts b/packages/session-query/session-query/src/types.ts
index b01d80dade..c98b5a749e 100644
--- a/packages/session-query/session-query/src/types.ts
+++ b/packages/session-query/session-query/src/types.ts
@@ -93,7 +93,7 @@ export type SessionLineageTrace = {
   }
 )
 
-/** Request for direct surface and provenance relationships around one event. */
+/** Request for direct surface replacements and relationships to cited source events around one event. */
 export interface SessionEventTraceRequest {
   /** Session that owns the target event. */
   sessionId: SessionId
@@ -101,7 +101,7 @@ export interface SessionEventTraceRequest {
   seq: number
 }
 
-/** Direct surface and provenance relationships for one event. */
+/** Direct surface replacements and relationships to cited source events for one event. */
 export interface SessionEventTrace {
   /** Lightweight target record. */
   target: SessionEventRecord
@@ -111,9 +111,9 @@ export interface SessionEventTrace {
   replacementChain: number[]
   /** Surface nodes directly removed when the target itself performed a replacement. */
   replacedEventSeqs: number[]
-  /** Direct logged provenance sources in their recorded order. */
+  /** Earlier events cited directly as sources, in their recorded order. */
   sourceEventSeqs: number[]
-  /** Later events that directly name the target as a provenance source, in log order. */
+  /** Later events that directly cite the target as a source, in log order. */
   derivedEventSeqs: number[]
 }
 
diff --git a/packages/session-query/session-query/tests/tracing.spec.ts b/packages/session-query/session-query/tests/tracing.spec.ts
index a6b5d73eb9..24e8622ab2 100644
--- a/packages/session-query/session-query/tests/tracing.spec.ts
+++ b/packages/session-query/session-query/tests/tracing.spec.ts
@@ -275,7 +275,7 @@ describe('session lineage tracing', () => {
 })
 
 describe('session event tracing', () => {
-  it('returns direct replacement and provenance links in their contract order', async () => {
+  it('returns direct replacement and cited source-event links in their contract order', async () => {
     const ctx = await queryContext()
     const session = ctx.sessions.create(SessionId('trace'))
     appendTraceEvents(session)
@@ -380,7 +380,7 @@ describe('session event tracing', () => {
       .rejects.toThrow(expectCode('SESSION_QUERY_SOURCE_CONFLICT'))
   })
 
-  it('checks target existence before surface or provenance analysis', async () => {
+  it('checks target existence before surface or source-event analysis', async () => {
     const bad = header('bad-target')
     const malformed: SessionEvent[] = [appendEvent(0), {
       type: 'assistant/message',
diff --git a/packages/session-query/tool-session-query/src/index.ts b/packages/session-query/tool-session-query/src/index.ts
index d6eb659b4d..5187e254ae 100644
--- a/packages/session-query/tool-session-query/src/index.ts
+++ b/packages/session-query/tool-session-query/src/index.ts
@@ -95,7 +95,7 @@ export function apply(ctx: Context, config: Config): void {
 
   ctx.tools.register(defineTool({
     name: 'session_event_trace',
-    description: 'Read every direct replacement and provenance relationship for one event in an authorized session.',
+    description: 'Read every direct replacement and relationship to a cited source event for one event in an authorized session.',
     parameters: {
       ...toolInput.targetSessionParameter,
       seq: { type: 'integer', required: true, description: 'Target event sequence number.' },
diff --git a/packages/session-query/tool-session-query/src/presentation.ts b/packages/session-query/tool-session-query/src/presentation.ts
index 6e99bd22eb..659a48d17b 100644
--- a/packages/session-query/tool-session-query/src/presentation.ts
+++ b/packages/session-query/tool-session-query/src/presentation.ts
@@ -157,7 +157,7 @@ function formatEventTrace(
     `Replaced by: ${trace.replacedBy ?? 'none'}`,
     `Replacement chain: ${seqList(trace.replacementChain)}`,
     `Events replaced by target: ${seqList(trace.replacedEventSeqs)}`,
-    `Direct provenance sources: ${seqList(trace.sourceEventSeqs)}`,
+    `Events cited directly as sources: ${seqList(trace.sourceEventSeqs)}`,
     `Direct derived events: ${seqList(trace.derivedEventSeqs)}`,
   ].join('\n')
 }
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index b6c2b25e6f..8341e48a1e 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/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/session/session-persistence/README.md
-README.md: 89c7cd5ebaff6f9ce9df9b60a50121dff4ddeeb5
-README.zh.md: 6b02f37343da07a80953ecb9d05e5903bd42d95c
+README.md: 29ee219a55d0823f03bb512c0fa37b7e249817eb
+README.zh.md: c750d2f85fd267a94c36770452f1e5c7e647a2fb
diff --git a/packages/session/session-persistence/README.md b/packages/session/session-persistence/README.md
index 89c7cd5eba..29ee219a55 100644
--- a/packages/session/session-persistence/README.md
+++ b/packages/session/session-persistence/README.md
@@ -35,7 +35,7 @@ Each `session/event` copies its event into the session controller. The first pen
 
 Crash repair is cold-only. For a live id, `load(id)` snapshots the authoritative in-memory log, waits for that snapshot to become durable, and returns it only when balanced; an open live turn rejects instead of receiving synthetic interruption closers. For a cold id, inspection reads, validates, freezes, and constructs one unpublished Session; repeated inspection reuses that object graph only while its source revision remains current. `prepare(id)` performs the same check before repair, reserves the exact Session, commits any pending torn-tail/interrupted-turn repair, and returns it for publication. HMR adoption reads through `loadStored`, applies the coordinator's cwd check, and never closes the active turn.
 
-Backend reads normalize the exact supported same-version shapes before current-shape validation. Pre-identity messages receive the deterministic id `legacy-message:<session-id>:<event-seq>`; a tool-result content replacement inherits its target's imported id. A pre-react-loop `turn/start` loses its obsolete trigger, a removed `steering/message` becomes the same identified `user/message`, and an older `turn/end` maps its terminal reason without inventing unavailable cancellation provenance. The coordinator uses the same normalized view for `load`, `inspect`, `readFrom`, ownerless-state claims, and HMR prefix adoption. Storage remains append-only: reads do not rewrite old records, and later appends use the current shape. These are narrow import exceptions from the [pre-identity message](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md) and [pre-react-loop session](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md) decisions, not a general v0 migration promise.
+Backend reads normalize the exact supported same-version shapes before current-shape validation. Pre-identity messages receive the deterministic id `legacy-message:<session-id>:<event-seq>`; a tool-result content replacement inherits its target's imported id. A pre-react-loop `turn/start` loses its obsolete trigger, a removed `steering/message` becomes the same identified `user/message`, and an older `turn/end` maps its terminal reason without inventing a caller that the old record did not name. The coordinator uses the same normalized view for `load`, `inspect`, `readFrom`, ownerless-state claims, and HMR prefix adoption. Storage remains append-only: reads do not rewrite old records, and later appends use the current shape. These are narrow import exceptions from the [pre-identity message](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md) and [pre-react-loop session](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md) decisions, not a general v0 migration promise.
 
 When a live session emits `session/disposed`, the coordinator waits for its controller, serializes a final drain, then releases state owned by that exact `Session` object. Failed retirement leaves the controller in the live-session map, so backend teardown can retry it. Backend teardown stops event admission first, flushes every remaining controller, awaits per-id operations, and only then closes the storage handle.
 
diff --git a/packages/session/session-persistence/README.zh.md b/packages/session/session-persistence/README.zh.md
index 6b02f37343..c750d2f85f 100644
--- a/packages/session/session-persistence/README.zh.md
+++ b/packages/session/session-persistence/README.zh.md
@@ -35,7 +35,7 @@
 
 崩溃修复只适用于冷状态。对于实时 id，`load(id)` 为权威内存日志制作快照，等待该快照持久，并只在平衡时返回；开放实时轮次会被拒绝，而不会收到合成中断 closer。对于冷 id，检查只读取、验证、冻结并构造一次未发布 Session；只有来源修订值仍然是当前值时，重复检查才会复用该对象图。`prepare(id)` 在修复前执行相同校验，预留该 Session 本身，提交任何待处理的撕裂尾部或中断轮次修复，并将其返回用于发布。HMR 接管通过 `loadStored` 读取，应用协调器 cwd 检查，并绝不关闭活动轮次。
 
-后端读取会在当前形状验证前，规范化明确受支持的同版本形状。消息标识机制引入前的消息会获得确定性的 id `legacy-message:<session-id>:<event-seq>`；工具结果的内容替换会继承其目标导入后的 id。react-loop 引入前的 `turn/start` 会移除过时的 trigger，已移除的 steering（中途引导）事件 `steering/message` 会转换为同一条带标识的 `user/message`；旧版 `turn/end` 会在不虚构无法获得的取消来源的前提下映射终止原因。协调器对 `load`、`inspect`、`readFrom`、无所有者状态的认领和 HMR 前缀接管使用同一份规范化视图。存储仍然仅追加：读取不会重写旧记录，此后追加的事件使用当前形状。这些是[消息标识机制引入前的消息](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)与 [react-loop 引入前会话](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md)决策所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
+后端读取会在当前形状验证前，规范化明确受支持的同版本形状。消息标识机制引入前的消息会获得确定性的 id `legacy-message:<session-id>:<event-seq>`；工具结果的内容替换会继承其目标导入后的 id。react-loop 引入前的 `turn/start` 会移除过时的 trigger，已移除的 steering（中途引导）事件 `steering/message` 会转换为同一条带标识的 `user/message`；旧版 `turn/end` 会在不虚构旧记录中未命名调用方的前提下映射终止原因。协调器对 `load`、`inspect`、`readFrom`、无所有者状态的认领和 HMR 前缀接管使用同一份规范化视图。存储仍然仅追加：读取不会重写旧记录，此后追加的事件使用当前形状。这些是[消息标识机制引入前的消息](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)与 [react-loop 引入前会话](../../../.agents/notes/implemented/bug-fix/2026-08-04-load-pre-react-loop-sessions.md)决策所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
 
 实时会话发出 `session/disposed` 时，协调器等待其 controller，串行化最终 drain，然后释放该精确 `Session` 对象拥有的状态。失败退役会将 controller 保留在实时会话 map 中，使后端拆卸可重试。后端拆卸先停止事件接纳，flush 每个剩余 controller，等待每 id 操作，最后才关闭存储句柄。
 
diff --git a/packages/session/session-title-llm/README.i18n.yaml b/packages/session/session-title-llm/README.i18n.yaml
index a7744c490b..d0a3459c64 100644
--- a/packages/session/session-title-llm/README.i18n.yaml
+++ b/packages/session/session-title-llm/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/session/session-title-llm/README.md
-README.md: 342687b5aa0cd35a70abf8cc66b3fe80342bce0b
-README.zh.md: 10496a727baa8a515f831feb425bc3d66ad91b5f
+README.md: db03205cabf9f723ee9bf6ad122026d75cb92113
+README.zh.md: a214caae84aeee7a3a5c90f55e8a01ea957b823f
diff --git a/packages/session/session-title-llm/README.md b/packages/session/session-title-llm/README.md
index 342687b5aa..db03205cab 100644
--- a/packages/session/session-title-llm/README.md
+++ b/packages/session/session-title-llm/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shared implementation policy for model-backed session-title providers. It resolves the auxiliary route, frames exact selected human messages as JSON, records the exact dispatchable request, applies a language-aware title instruction, enforces input and output budgets, composes timeout and caller cancellation, assembles the stream, and returns normalized text with exact source seqs and model provenance.
+Shared implementation policy for model-backed session-title providers. It resolves the auxiliary route, frames exact selected human messages as JSON, records the exact dispatchable request, applies a language-aware title instruction, enforces input and output budgets, composes timeout and caller cancellation, assembles the stream, and returns normalized text with exact source seqs plus the provider/model route used to generate it.
 
 This package is a library, not a Cordis plugin. The provider plugins call `registerSessionTitleLlmProvider()` with their cadence and message selector; it validates shared config and delegates each revision to `generateSessionTitleWithLlm()`, so registration, route, prompt, cancellation, and validation behavior cannot drift between them.
 
diff --git a/packages/session/session-title-llm/README.zh.md b/packages/session/session-title-llm/README.zh.md
index 10496a727b..a214caae84 100644
--- a/packages/session/session-title-llm/README.zh.md
+++ b/packages/session/session-title-llm/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-由模型支持的会话标题提供方的共享实现策略。它解析辅助路由，将精确选中的用户消息封装为 JSON，记录可分发的确切请求，应用语言感知的标题指令，强制执行输入和输出预算，组合超时与调用方取消，组装流，并返回带有确切来源 seq 和模型来源信息的规范化文本。
+由模型支持的会话标题提供方的共享实现策略。它解析辅助路由，将精确选中的用户消息封装为 JSON，记录可分发的确切请求，应用语言感知的标题指令，强制执行输入和输出预算，组合超时与调用方取消，组装流，并返回规范化文本，同时给出确切来源 seq 以及生成该文本时使用的提供方／模型路由。
 
 此包是普通库，不是 Cordis 插件。提供方插件调用 `registerSessionTitleLlmProvider()`，传入各自节奏与消息选择器；该函数验证共享配置，并将每次修订委派给 `generateSessionTitleWithLlm()`，使各插件的注册、路由、提示词、取消与验证行为不会漂移。
 
diff --git a/packages/session/session-title-llm/src/index.ts b/packages/session/session-title-llm/src/index.ts
index 646c9e53d5..1b0e328621 100644
--- a/packages/session/session-title-llm/src/index.ts
+++ b/packages/session/session-title-llm/src/index.ts
@@ -146,7 +146,7 @@ export type SessionTitleLlmMessageSelector = (
  * Register one model-backed provider through the shared configuration and call policy.
  * @param ctx - context exposing the title and LLM services.
  * @param config - untrusted required deployment policy.
- * @param id - stable plugin identity recorded in title provenance.
+ * @param id - stable plugin id recorded with generated titles.
  * @param automatic - provider-owned automatic generation cadence.
  * @param selectMessages - exact source-message selection for one revision.
  */
diff --git a/packages/session/session-title-llm/src/invariant.ts b/packages/session/session-title-llm/src/invariant.ts
index 419db90185..64350ebf20 100644
--- a/packages/session/session-title-llm/src/invariant.ts
+++ b/packages/session/session-title-llm/src/invariant.ts
@@ -16,7 +16,7 @@ export const inject = ['invariants']
 
 /**
  * No runtime invariant: this stateless helper validates and freezes each auxiliary request before
- * dispatch; deadline, stream, and provenance relationships are checked synchronously and by tests.
+ * dispatch; deadline, stream, cited message seqs, and provider/model fields are checked synchronously and by tests.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/session/session-title/README.i18n.yaml b/packages/session/session-title/README.i18n.yaml
index f87ea98542..4b038799f3 100644
--- a/packages/session/session-title/README.i18n.yaml
+++ b/packages/session/session-title/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/session/session-title/README.md
-README.md: 13a2a1c298c3abb8c8987b9373edc46a071ce9db
-README.zh.md: 075e9e31fc7acbc76f0e3fd7a2642b4d879569d3
+README.md: e7004eb2e03757cb28b4b5756a876e1dee4b6229
+README.zh.md: 45c1aafdf214f63ae7a071d2558eaefec13ea70f
diff --git a/packages/session/session-title/README.md b/packages/session/session-title/README.md
index 13a2a1c298..e7004eb2e0 100644
--- a/packages/session/session-title/README.md
+++ b/packages/session/session-title/README.md
@@ -29,7 +29,7 @@ All limits are required; the library supplies no defaults.
 
 ## Provider contract
 
-A provider supplies a branded stable id, automatic mode (`first-message` or `all-user-messages`), and `generate(request)`. The request carries the live session, all eligible messages through one fixed revision, the current logged main-request route when available, and cancellation. The result identifies a non-empty title, unique ordered source-message seqs from that request, and optional model provenance. The service normalizes and validates the result before it becomes durable.
+A provider supplies a branded stable id, automatic mode (`first-message` or `all-user-messages`), and `generate(request)`. The request carries the live session, all eligible messages through one fixed revision, the current logged main-request route when available, and cancellation. The result identifies a non-empty title, unique ordered source-message seqs from that request, and the optional provider/model route used to generate it. The service normalizes and validates the result before it becomes durable.
 
 See the [session-title data structures](../../../docs/subsystems/session-title.md) and [implemented decision](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md).
 
diff --git a/packages/session/session-title/README.zh.md b/packages/session/session-title/README.zh.md
index 075e9e31fc..45c1aafdf2 100644
--- a/packages/session/session-title/README.zh.md
+++ b/packages/session/session-title/README.zh.md
@@ -29,7 +29,7 @@ Fork 出的会话会原样继承种子中的标题事件。首消息节奏不会
 
 ## 提供方约定
 
-提供方会提供带品牌类型的稳定 id、自动模式（`first-message` 或 `all-user-messages`）和 `generate(request)`。请求携带活跃会话、截至一次固定修订的所有符合条件消息、可用时当前已记录的主请求路由，以及取消信号。结果包含非空标题、该请求中唯一且有序的来源消息 seq，以及可选的模型来源信息。服务会在结果持久保存前进行规范化和验证。
+提供方会提供带品牌类型的稳定 id、自动模式（`first-message` 或 `all-user-messages`）和 `generate(request)`。请求携带活跃会话、截至一次固定修订的所有符合条件消息、可用时当前已记录的主请求路由，以及取消信号。结果包含非空标题、该请求中唯一且有序的来源消息 seq，以及生成该标题时使用的可选提供方／模型路由。服务会在结果持久保存前进行规范化和验证。
 
 参见[会话标题数据结构](../../../docs/subsystems/session-title.md)与[已实现决策](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)。
 
diff --git a/packages/session/session-title/src/index.ts b/packages/session/session-title/src/index.ts
index 12da431c68..ab2298aa6c 100644
--- a/packages/session/session-title/src/index.ts
+++ b/packages/session/session-title/src/index.ts
@@ -63,7 +63,7 @@ export interface SessionTitleEventData {
   readonly title: string
   /** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
   readonly messageSeqs: number[]
-  /** Built-in fallback, registered-provider, or explicit-user provenance. */
+  /** Whether the built-in fallback, a registered provider, or the user supplied the title. */
   readonly source: SessionTitleSource
 }
 
@@ -146,14 +146,14 @@ export interface SessionTitleProviderResult {
 
 /** One optional asynchronous title implementation registered with the service. */
 export interface SessionTitleProvider {
-  /** Stable provider identity recorded in title provenance. */
+  /** Stable id of the provider recorded with the title. */
   readonly id: SessionTitleProviderId
   /** When new human prompts start automatic generation. */
   readonly automatic: SessionTitleAutomaticMode
   /**
    * Produce one title revision.
    * @param request - message snapshot, current route, session, and cancellation.
-   * @returns proposed title plus exact input seqs and optional model provenance.
+   * @returns proposed title plus exact input seqs and the optional provider/model route used to generate it.
    */
   generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
 }
@@ -615,12 +615,12 @@ export class SessionTitleService extends Service {
     let model: SessionTitleModelProvenance | undefined
     if (modelCandidate !== undefined) {
       if (modelCandidate === null || typeof modelCandidate !== 'object') {
-        throw new Error('session-title provider model provenance requires non-empty provider and model')
+        throw new Error('session-title provider result model must contain non-empty provider and model strings')
       }
       const record = modelCandidate as Record<string, unknown>
       if (typeof record.provider !== 'string' || record.provider.length === 0
         || typeof record.model !== 'string' || record.model.length === 0) {
-        throw new Error('session-title provider model provenance requires non-empty provider and model')
+        throw new Error('session-title provider result model must contain non-empty provider and model strings')
       }
       model = { provider: record.provider, model: record.model }
     }
diff --git a/packages/session/session-title/src/invariant.ts b/packages/session/session-title/src/invariant.ts
index 25b00a10aa..a826104489 100644
--- a/packages/session/session-title/src/invariant.ts
+++ b/packages/session/session-title/src/invariant.ts
@@ -16,7 +16,7 @@ export const name = 'session-title-invariant'
 export const inject = ['invariants']
 
 /**
- * Durable title-provenance invariant: an automatic title always cites at
+ * Durable title-source invariant: an automatic title always cites at
  * least one human `user/message` seq, and an explicit user rename cites none
  * — `messageSeqs` is empty iff `source.kind` is `user`. Provider revisions
  * are validated by the service before their append; this checks the durable
@@ -32,7 +32,8 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
     if (event.type !== 'session/title') return
     const { source, messageSeqs } = event.data
     if ((messageSeqs.length === 0) !== (source.kind === 'user')) {
-      fail(`session/title event ${String(event.seq)} breaks provenance: source "${source.kind}" with ${String(messageSeqs.length)} cited message seq(s)`)
+      const requirement = source.kind === 'user' ? 'cite no message seqs' : 'cite at least one message seq'
+      fail(`session/title event ${String(event.seq)} with source "${source.kind}" must ${requirement}; got ${String(messageSeqs.length)}`)
     }
   }, { global: true })
 }, { inject: ['sessions'] })
diff --git a/packages/session/session-title/tests/invariant.spec.ts b/packages/session/session-title/tests/invariant.spec.ts
index 5b316448da..d1a6abb527 100644
--- a/packages/session/session-title/tests/invariant.spec.ts
+++ b/packages/session/session-title/tests/invariant.spec.ts
@@ -1,4 +1,4 @@
-// Title-provenance invariant: messageSeqs is empty iff source.kind is 'user'
+// Title-source invariant: `messageSeqs` is empty iff `source.kind` is `user`.
 // — the durable relationship every appended session/title event must keep.
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
@@ -14,7 +14,7 @@ async function setup(): Promise<Context> {
   return ctx
 }
 
-describe('session-title provenance invariant', () => {
+describe('session-title source invariant', () => {
   it('accepts cited automatic titles and citation-free user renames', async () => {
     const ctx = await setup()
     const session = ctx.sessions.create(SessionId('title-invariant-valid'))
diff --git a/packages/session/session-title/tests/service-contracts.spec.ts b/packages/session/session-title/tests/service-contracts.spec.ts
index 6a425ae36f..28d7e6749e 100644
--- a/packages/session/session-title/tests/service-contracts.spec.ts
+++ b/packages/session/session-title/tests/service-contracts.spec.ts
@@ -436,12 +436,12 @@ describe('SessionTitleService provider validation and stale scheduling', () => {
       { value: { title: 'valid', messageSeqs: [999] }, error: /unique, ordered seqs/ },
       { value: { title: 'valid', messageSeqs: [first.seq, first.seq] }, error: /unique, ordered seqs/ },
       { value: { title: 'valid', messageSeqs: [second.seq, first.seq] }, error: /unique, ordered seqs/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: null }, error: /model provenance/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: 'route' }, error: /model provenance/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 1, model: 'm' } }, error: /model provenance/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: '', model: 'm' } }, error: /model provenance/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 'p', model: 1 } }, error: /model provenance/ },
-      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 'p', model: '' } }, error: /model provenance/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: null }, error: /provider result model/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: 'route' }, error: /provider result model/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 1, model: 'm' } }, error: /provider result model/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: '', model: 'm' } }, error: /provider result model/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 'p', model: 1 } }, error: /provider result model/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 'p', model: '' } }, error: /provider result model/ },
     ]
     for (const item of cases) {
       result = item.value
diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml
index dbbb9ba698..f1dc1c8851 100644
--- a/packages/settings/settings/README.i18n.yaml
+++ b/packages/settings/settings/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/settings/settings/README.md
-README.md: 0841624e553364fa03f7a1f1209aa72ab13d97e4
-README.zh.md: 3dbe14a7ce6fc002569eb612f355fa0ff7372ae3
+README.md: 49ae5b405c003b6116e459cf377fc7a099538f2e
+README.zh.md: c55db331ece9421fb7f0367697ce158b8e9b06f1
diff --git a/packages/settings/settings/README.md b/packages/settings/settings/README.md
index 0841624e55..49ae5b405c 100644
--- a/packages/settings/settings/README.md
+++ b/packages/settings/settings/README.md
@@ -38,6 +38,6 @@ No direct invalidation; a consumer that folds a settings value into the request
 
 ## Known Limitations and Deferred Work
 
-- **Single user layer** — resolution knows schema defaults, one composition `base`, and one user document; there is no project/managed layering or per-value provenance yet.
+- **Single user layer** — resolution knows schema defaults, one composition `base`, and one user document; it does not yet record which layer supplied each resolved value.
 - **`redactSecrets` is not a proven wire boundary** — the walker follows `object`/`dict`/`array`, so a `role('secret')` reached only through a union, intersection, or transform is returned VERBATIM with an empty `secrets` list, and `schema.toJSON()` carries a secret field's `.default(...)` to every client. Neither case is rejected; a schema whose secrets are not reachable through the walked containers must not be registered on a wire-exposed namespace. A fail-closed `describeForWire()` — one that refuses a schema it cannot prove safe, and sanitizes the serialized envelope and error text — is the real answer and is deferred.
 - **Cross-process concurrency is provider-defined** — the seam serializes writes per namespace in-process only; concurrent processes converge by provider behavior (the local file provider read-modify-writes under a writer lock, so namespaces survive concurrent writers and same-namespace conflicts resolve last-write-wins).
diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md
index 3dbe14a7ce..c55db331ec 100644
--- a/packages/settings/settings/README.zh.md
+++ b/packages/settings/settings/README.zh.md
@@ -38,6 +38,6 @@
 
 ## 已知限制与暂缓事项
 
-- **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；尚无 project/managed 分层或按值溯源。
+- **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；它尚未记录每个解析值由哪一层提供。
 - **`redactSecrets` 并非一条可被证明的协议边界**：walker 只跟随 `object`/`dict`/`array`，因此只能经由 union、intersection 或 transform 抵达的 `role('secret')` 会被**原样**返回，且 `secrets` 列表为空；而 `schema.toJSON()` 会把 secret 字段的 `.default(...)` 一并带给每个客户端。这两种情况都不会被拒绝；机密无法经由被遍历的容器抵达的 schema，绝不可注册到暴露于协议的 namespace 上。真正的答案是一个 fail-closed 的 `describeForWire()`——它拒绝自己无法证明安全的 schema，并对序列化信封与错误文本做净化——此项暂缓。
 - **跨进程并发由 provider 定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按 provider 行为收敛（本地文件 provider 在写锁下读-改-写，因此 namespace 在并发写入者下不会丢失，同 namespace 冲突按后写胜出解决）。
diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts
index 604cd63bcf..bc9a1634a1 100644
--- a/packages/skill/tool-skill/src/index.ts
+++ b/packages/skill/tool-skill/src/index.ts
@@ -26,7 +26,7 @@ export const inject = ['agents', 'tools', 'skills']
 
 const DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH = 500
 /**
- * Durable provenance for one published session skill catalog. The catalog is a
+ * Durable provider and item records for one published session skill catalog. The catalog is a
  * `catalog`-form context, so it records the entries it published beside the
  * model-facing prose: a consumer presenting the list must not re-parse the
  * `<available_skills>` block, whose framing exists for the model.
diff --git a/packages/spill/spill/README.i18n.yaml b/packages/spill/spill/README.i18n.yaml
index 4948b880f0..110d814fe2 100644
--- a/packages/spill/spill/README.i18n.yaml
+++ b/packages/spill/spill/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/spill/spill/README.md
-README.md: c3434f90a8f7ab30baa6b237beab6dd9763f9bff
-README.zh.md: fc80f8a5fee713a6cba1a5c8173c489bfc2c14d8
+README.md: d3cce987f80c0db5165718b7cc4fd6ada92f2a02
+README.zh.md: 37d6587d08d96c55a36c9b7388f2ae418531a6cd
diff --git a/packages/spill/spill/README.md b/packages/spill/spill/README.md
index c3434f90a8..d3cce987f8 100644
--- a/packages/spill/spill/README.md
+++ b/packages/spill/spill/README.md
@@ -24,7 +24,7 @@ Storage is grouped by the request's `owner` session as a save-time namespace; th
 
 ## Vocabulary
 
-`SaveTextSpill` (owner, source, suggestedName, content) is the request; `SpillRef` (locator, bytes, retrievalHint) is the result. `SpillLocator` is [branded](../../util/brand) and rendered to the model as an opaque string — a local path for `dsh-spill-local`, but a future backend may return a URI, key, or command token without changing policy/tool consumers. `SpillOwner.sessionId` is the save-time storage namespace: forked sessions inherit existing locators from the seeded log without copying or re-owning them, and new spills after the fork use the child session id. `SpillSource` (toolName, callId, label) is descriptive provenance for backend naming and inspection, not access control. See `src/types.ts` for the full contracts.
+`SaveTextSpill` (owner, source, suggestedName, content) is the request; `SpillRef` (locator, bytes, retrievalHint) is the result. `SpillLocator` is [branded](../../util/brand) and rendered to the model as an opaque string — a local path for `dsh-spill-local`, but a future backend may return a URI, key, or command token without changing policy/tool consumers. `SpillOwner.sessionId` is the save-time storage namespace: forked sessions inherit existing locators from the seeded log without copying or re-owning them, and new spills after the fork use the child session id. `SpillSource` records the producing `toolName`, `callId`, and `label` for backend naming and inspection, not access control. See `src/types.ts` for the full contracts.
 
 See the [tool output spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) for the design rationale, including why creation belongs to the runtime spill seam rather than the model-facing `write` tool.
 
diff --git a/packages/spill/spill/README.zh.md b/packages/spill/spill/README.zh.md
index fc80f8a5fe..37d6587d08 100644
--- a/packages/spill/spill/README.zh.md
+++ b/packages/spill/spill/README.zh.md
@@ -24,7 +24,7 @@
 
 ## 词汇
 
-`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource`（toolName、callId、label）是供后端命名和检查使用的描述性来源信息，而非访问控制信息。完整约定见 `src/types.ts`。
+`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource` 记录产生该 spill 的 `toolName`、`callId` 和 `label`，供后端命名和检查使用，不用于访问控制。完整约定见 `src/types.ts`。
 
 设计原理见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中说明了为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。
 
diff --git a/packages/spill/spill/src/index.ts b/packages/spill/spill/src/index.ts
index 4c8826defb..73bfe75f33 100644
--- a/packages/spill/spill/src/index.ts
+++ b/packages/spill/spill/src/index.ts
@@ -49,7 +49,7 @@ export abstract class SpillStore extends Service {
 
   /**
    * Persist `input.content` to a session-scoped spill artifact.
-   * @param input - the owner, provenance, suggested name, and full text to save.
+   * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
    * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
    */
   abstract saveText(input: SaveTextSpill): Promise<SpillRef>
diff --git a/packages/spill/spill/src/types.ts b/packages/spill/spill/src/types.ts
index 96376bb268..a3657e5c3c 100644
--- a/packages/spill/spill/src/types.ts
+++ b/packages/spill/spill/src/types.ts
@@ -39,7 +39,7 @@ export interface SpillOwner {
 }
 
 /**
- * Provenance of one spilled artifact — recorded by the backend for a readable
+ * Tool and call that produced one spilled artifact — recorded by the backend for a readable
  * filename and inspection. Not interpreted for access control; purely
  * descriptive.
  */
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index ca81aa07a6..e1ba59aa50 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: cd25bace16c91e8b44331dc8e5eab0987607e83a
-README.zh.md: 52971add9646fd45a33661bb33b3f7d8c452219c
+README.md: 7658dad2fc8d79ca178ed5467448de9527f7bc49
+README.zh.md: 8d3bc4b96ac366e919256f4409ebd54d3505de87
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index cd25bace16..7658dad2fc 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -27,7 +27,7 @@ The [subagent family overview](../README.md) maps implementations and model-faci
 
 `SubagentStartRequest.label` is an optional short durable display label for a session-backed one-shot child. Model-facing delegation supplies its existing `description`; lower-level callers need not invent presentation metadata. Continuable starts always carry their own required label. `signal` is required and is the canonical cancellation channel for a one-shot `start`. An abort before publication makes `start()` reject after rollback; an abort after publication cancels the returned run's remaining turn work without hiding its id. The request may also select a model, require structured output, cap delegation depth, restrict child tools, or set a child persona. For a continuable start or follow-up, the caller signal owns lookup, materialization, and admission only until inbox acceptance; afterward the manager owns the Activation independently, so later caller cancellation neither cancels the accepted turn nor disposes the child.
 
-Follow-up authority comes from the exact live direct parent recorded in the child's durable header. Cold resume checks that authority before reconstruction and again in the final no-await inbox-admission span, so a parent unregistered or replaced during materialization cannot authorize delivery. The `source` on a follow-up is durable provenance retained on the delivered message and grants no authority.
+Follow-up authority comes from the exact live direct parent recorded in the child's durable header. Cold resume checks that authority before reconstruction and again in the final no-await inbox-admission span, so a parent unregistered or replaced during materialization cannot authorize delivery. The `source` on a follow-up records who supplied the delivered message and grants no authority.
 
 Same-process requests, descriptors, results, and event payloads are trusted typed values borrowed as immutable. The service does not clone or freeze them; serialization and hostile-input validation belong at actual process, worker, persistence, and model boundaries.
 
@@ -72,13 +72,13 @@ A continuation-managed parent Activation records each child Session id in an `ow
 
 ## Lifecycle events
 
-The service emits a `subagent/start`/`subagent/end` pair for each one-shot run and each resident continuable Activation epoch, so continuable children are observable with the same vocabulary as one-shot runs without exposing whether the manager materialized, woke, or cold-resumed them. For a one-shot start it attaches the result observer before the synchronous `subagent/start`, so even an already-settled child still produces `subagent/start` before `subagent/end`; a continuable epoch that fails before residency emits neither edge. The pair shares a service-minted `runId`; the `local` flag is snapshotted from the provider's exact `localAgent` (always true for a continuable child), so observers never infer run identity or locality from reusable provider/session names. The `provider` field is lifecycle provenance rather than a live-registry claim: an accepted one-shot run may settle after provider removal, and a cold-resumed epoch retains its descriptor's initial provider name without requiring that provider to be registered.
+The service emits a `subagent/start`/`subagent/end` pair for each one-shot run and each resident continuable Activation epoch, so continuable children are observable with the same vocabulary as one-shot runs without exposing whether the manager materialized, woke, or cold-resumed them. For a one-shot start it attaches the result observer before the synchronous `subagent/start`, so even an already-settled child still produces `subagent/start` before `subagent/end`; a continuable epoch that fails before residency emits neither edge. The pair shares a service-minted `runId`; the `local` flag is snapshotted from the provider's exact `localAgent` (always true for a continuable child), so observers never infer run identity or locality from reusable provider/session names. The `provider` field names the provider that started the run or Activation epoch rather than claiming current registration: an accepted one-shot run may settle after provider removal, and a cold-resumed epoch retains its descriptor's initial provider name without requiring that provider to be registered.
 
 Run events are scoped to the delegating parent. Every listener is independently contained: a synchronous throw or rejected returned promise is logged without starving peer listeners or changing the run.
 
 Provider additions and removals also emit `subagent/provider-added` and `subagent/provider-removed`. Consumers such as the model-facing tool use those events because Cordis may load sibling plugins concurrently; configuration order does not prove registration order.
 
-Continuable children do not create `SubagentRun` or Tasks. The continuation manager directly owns one process-local Activation and retained `AgentHandle` per resident child Session, uses the Agent inbox as the only FIFO, and cold-resumes from the durable descriptor. Exact live direct-parent identity authorizes parent-to-child delivery. Exact live child identity authorizes reports; the manager derives the recipient from durable `parentSession`, and `MessageSource` remains provenance rather than authority. Interrupt authority is deliberately wider than delivery authority: a human presents the durable direct-parent address so a live child stays stoppable while its parent Agent is offline, and any exact live ancestor recorded in the Activation's materialization lineage may stop its descendant, because stopping a turn is idempotent and delivers no content.
+Continuable children do not create `SubagentRun` or Tasks. The continuation manager directly owns one process-local Activation and retained `AgentHandle` per resident child Session, uses the Agent inbox as the only FIFO, and cold-resumes from the durable descriptor. Exact live direct-parent identity authorizes parent-to-child delivery. Exact live child identity authorizes reports; the manager derives the recipient from durable `parentSession`, and `MessageSource` records the sender without granting authority. Interrupt authority is deliberately wider than delivery authority: a human presents the durable direct-parent address so a live child stays stoppable while its parent Agent is offline, and any exact live ancestor recorded in the Activation's materialization lineage may stop its descendant, because stopping a turn is idempotent and delivers no content.
 
 When `ctx.sessionProjections` is available, the service registers two projection units. `subagentTiming` resets at each descriptor so a fork seed's ancestor work cannot enter the child's total, then accumulates `turn/start` → `turn/end` active time and retains same-cut `active.since` and `active.through` bounds for an open turn; while that turn remains open, `active.through` follows the latest folded event, giving an inactive consumer a conservative crash bound without mixing in newer session metadata. `subagent` folds the durable identity — mode plus creation label — from `subagent/descriptor` events with the same last-wins reset discipline, so a fork seed's ancestor descriptor stands only until the child's own overrides it; a malformed or unrecognized-version payload folds to the serializable `null` sentinel — indistinguishable from a log with no descriptor, and surviving every JSON push frame so a consumer replaces a stale identity instead of keeping it — and never throws.
 
@@ -105,6 +105,6 @@ No direct invalidation; the named consumers own any request-prefix changes.
 - **No current-turn steering** — continuable messages and waking reports enqueue later turns; neither redirects an open turn.
 - **Wake gap during cancellation convergence** — a waking follow-up accepted after the interrupt signal is issued but before the active driver becomes idle remains queued until another waking send. Issue #1838 owns the agent-loop wake latch, which also affects ordinary session cancellation.
 - **Process-local residency** — the Activation inbox and ownership graph do not coordinate two harness processes; concurrent access to one persistence store still requires a durable mailbox and cross-process lease protocol.
-- **No replay of accepted-but-unlogged messages** — only messages written to the child Session log are reconstructable with their admitted provenance. A crash may lose an accepted initial prompt or follow-up that never reached the log; a later authorized message can cold-resume the child, but the lost message is not replayed automatically.
+- **No replay of accepted-but-unlogged messages** — only messages written to the child Session log are reconstructable with the source that supplied them. A crash may lose an accepted initial prompt or follow-up that never reached the log; a later authorized message can cold-resume the child, but the lost message is not replayed automatically.
 - **No durable report mailbox** — reports require a live direct parent and provide acceptance identity rather than exactly-once delivery or a read receipt.
 - **Lifecycle events are observe-only** — a run-affecting `subagent/end` continuation or decision surface waits for a concrete consumer.
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 52971add96..8d3bc4b96a 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -27,7 +27,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 `SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。
 
-后续操作的权限来自子 agent 持久化 header 中记录的确切在线直接父级。冷恢复会在重建前检查该权限，并在最终无 await 的 inbox 准入区间再次检查，因此在物化期间被注销或替换的 parent 无法授权投递。后续操作上的 `source` 是保留在所投递消息上的持久化来源，不授予任何权限。
+后续操作的权限来自子 agent 持久化 header 中记录的确切在线直接父级。冷恢复会在重建前检查该权限，并在最终无 await 的 inbox 准入区间再次检查，因此在物化期间被注销或替换的 parent 无法授权投递。后续操作上的 `source` 记录谁提供了所投递的消息，不授予任何权限。
 
 同进程请求、描述符、结果和事件 payload 都是以不可变方式借用的可信类型值。服务不会克隆或冻结它们；序列化和不可信输入校验属于真实的进程、worker、持久化和模型边界。
 
@@ -72,13 +72,13 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 生命周期事件
 
-服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不会发出这对生命周期事件中的任何一个。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段是生命周期来源信息，而非提供方仍在注册的声明：已接受的一次性 run 可在提供方移除后才结算，冷恢复时段也会保留描述符中的初始提供方名称，而不要求该提供方仍处于注册状态。
+服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不会发出这对生命周期事件中的任何一个。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段指明启动该运行或 Activation 时段的提供方，不表示该提供方当前仍在注册：已接受的一次性 run 可在提供方移除后才结算，冷恢复时段也会保留描述符中的初始提供方名称，而不要求该提供方仍处于注册状态。
 
 运行事件受执行委派的父级作用域约束。每个监听器都独立隔离：同步抛出或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变运行。
 
 提供方新增和移除还会发出 `subagent/provider-added` 与 `subagent/provider-removed`。面向模型的工具等消费方使用这些事件，因为 Cordis 可能并发加载同级插件；配置顺序不能证明注册顺序。
 
-可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代，因为停止一个轮次是幂等的，且不投递任何内容。
+可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 记录发送方，但不授予权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代，因为停止一个轮次是幂等的，且不投递任何内容。
 
 当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置规则从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，使消费方替换陈旧身份而不是将其保留——绝不抛错。
 
@@ -105,6 +105,6 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 - **不对当前轮次进行 steering**：可继续消息和唤醒式 report 会排入后续轮次，均不会重定向正在进行的轮次。
 - **取消收敛期间存在唤醒缺口**：中断信号发出后、活动 driver 进入 idle 前被接受的唤醒型 follow-up 会保持排队，直到另一条唤醒发送到达。Issue #1838 负责 agent-loop 的唤醒锁存；普通会话取消也受此影响。
 - **驻留仅限进程内**：Activation inbox 与所有权图不会在两个 harness 进程之间协调；对单个持久化存储的并发访问仍然需要持久化邮箱和跨进程租约协议。
-- **不重放已接受但未记录的消息**：只有写入子 agent Session 日志的消息才能连同其被接受时的来源一起重建。崩溃可能丢失从未写入日志、已被接受的初始提示词或后续消息；此后一条经授权的消息可以冷恢复该子 agent，但丢失的消息不会自动重放。
+- **不重放已接受但未记录的消息**：只有写入子 agent Session 日志的消息才能连同提供该消息的来源一起重建。崩溃可能丢失从未写入日志、已被接受的初始提示词或后续消息；此后一条经授权的消息可以冷恢复该子 agent，但丢失的消息不会自动重放。
 - **没有持久化的上报 mailbox**：上报需要实时直接父级，提供的是接受标识，不保证恰好一次投递，也不提供已读回执。
 - **生命周期事件只供观察**：影响运行的 `subagent/end` 延续或决策接口仍需等待具体消费方。
diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts
index 67cc177fe1..3425a12851 100644
--- a/packages/subagent/subagent/src/continuation.ts
+++ b/packages/subagent/subagent/src/continuation.ts
@@ -386,7 +386,7 @@ export class SubagentContinuationManager {
    * @param parent - the exact live direct parent authorizing this delivery.
    * @param childId - the durable child session id.
    * @param content - the user-role content to deliver.
-   * @param options - durable provenance and caller cancellation.
+   * @param options - the message source fields and caller cancellation.
    * @returns the accepted message's inbox id.
    * @throws when parent authority, availability, or admission rejects the delivery.
    */
@@ -826,7 +826,7 @@ export class SubagentContinuationManager {
    * Submit to a freshly materialized Activation or roll it back completely.
    * @param activation - the just-published Activation to admit or release.
    * @param content - the initial or resumed message content.
-   * @param source - durable provenance for the accepted message.
+   * @param source - durable fields naming who supplied the accepted message.
    * @param parent - the live direct parent authorizing admission.
    * @param signal - caller cancellation owning admission until acceptance.
    * @returns the accepted inbox message id.
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 2a118565fa..241682c006 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -218,7 +218,7 @@ export class SubagentService extends Service {
    * @param parent - the exact live direct parent authorizing this delivery.
    * @param childId - durable child session id.
    * @param content - user-role content to deliver.
-   * @param options - durable provenance and caller cancellation, which stops the
+   * @param options - the message source fields and caller cancellation, which stops the
    *   operation only before inbox acceptance.
    * @returns the accepted message's inbox id.
    * @throws when continuation services are unavailable, parent authority is
diff --git a/packages/subagent/subagent/src/invariant.ts b/packages/subagent/subagent/src/invariant.ts
index 8797f0513f..d9a497eb77 100644
--- a/packages/subagent/subagent/src/invariant.ts
+++ b/packages/subagent/subagent/src/invariant.ts
@@ -45,7 +45,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
       const info = args[0] as SubagentRunInfo
       // Provider availability is an admission-time relationship. A published
       // one-shot run may outlive provider removal, and a cold-resumed Activation
-      // carries durable provider provenance without dispatching through it.
+      // records the initial provider name without dispatching through it.
       if (info.provider.length === 0 || String(info.runId).length === 0 || String(info.id).length === 0) {
         fail('subagent/start provider, runId, and child id must be non-empty')
       }
diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts
index 91e11ad661..b003b75507 100644
--- a/packages/subagent/subagent/src/types.ts
+++ b/packages/subagent/subagent/src/types.ts
@@ -37,7 +37,7 @@ export interface SubagentRunInfo {
   /** Unique identity shared with the paired terminal event. */
   readonly runId: SubagentRunId
   /**
-   * Provider provenance for this run or Activation epoch. The named provider
+   * Provider that started this run or Activation epoch. The named provider
    * may be absent when an accepted run becomes ready or a persisted Activation
    * cold-resumes, because neither lifecycle depends on continued registration.
    */
@@ -55,7 +55,7 @@ export interface SubagentRunInfo {
 export interface SubagentRunEndInfo {
   /** Unique identity shared with the paired start event. */
   readonly runId: SubagentRunId
-  /** The same provider provenance carried by the paired start event. */
+  /** The same provider name carried by the paired start event. */
   readonly provider: string
   /** The child agent's id. */
   readonly id: SessionId
diff --git a/packages/subagent/subagent/tests/invariant.spec.ts b/packages/subagent/subagent/tests/invariant.spec.ts
index e288b77a86..21bdda0e06 100644
--- a/packages/subagent/subagent/tests/invariant.spec.ts
+++ b/packages/subagent/subagent/tests/invariant.spec.ts
@@ -80,7 +80,7 @@ describe('subagent invariants', () => {
       .toThrow(/identity diverges/)
   })
 
-  it('accepts historical provider provenance after registration ends', async () => {
+  it('accepts the recorded provider name after registration ends', async () => {
     const ctx = await setup()
     const historical = provider('historical')
     ctx.emit('subagent/provider-added', historical)
diff --git a/packages/subagent/tool-subagent-control/README.i18n.yaml b/packages/subagent/tool-subagent-control/README.i18n.yaml
index d25adaad9d..885345b576 100644
--- a/packages/subagent/tool-subagent-control/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-control/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/subagent/tool-subagent-control/README.md
-README.md: 4d9991b720bbbff8862e693b6aaed332f414af0e
-README.zh.md: 6f7138571fa7f8cb500df1a513f92d1f7f2b82e6
+README.md: 460617378841b791f7d8750962a9e4549643928e
+README.zh.md: 5939a1636a5f92dc797e5788c88bba7048ec7c96
diff --git a/packages/subagent/tool-subagent-control/README.md b/packages/subagent/tool-subagent-control/README.md
index 4d9991b720..4606173788 100644
--- a/packages/subagent/tool-subagent-control/README.md
+++ b/packages/subagent/tool-subagent-control/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The optional, globally named `send_message`, `interrupt_agent`, and `list_agents` tools are thin adapters over `ctx.subagents`. Provider-bound `@deepseek-ai/dsh-tool-subagent` instances register distinct delegation tools per transport; this separately loaded package registers shared control tools once, so multiple delegation tools never register duplicate global controls. The root plugin registers `send_message` and `interrupt_agent` and requires only `subagents`; the separately loadable `./list-agents` plugin registers `list_agents` and declares `subagents` plus `agents` as load-time dependencies. Its catalog reads additionally require the session store and projection registry at call time, but no query service. A deployment can keep the root tools while omitting the list tool. No tool's presence determines whether a delegation tool starts continuable work. These tools own only the parent-to-child direction; the independently installed [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) owns the child-to-parent direction.
 
-The tool performs no lifecycle routing — residency and cold resume belong to the subagent service. It passes `exec.agent` as the exact live parent that authorizes delivery and attributes every message as durable provenance `{ kind: 'coordinator', senderSessionId: parent.id }`, which the service retains but never treats as authority. Every message becomes the subagent's next FIFO turn through `Agent.followup()`: if the child is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. The tool forwards its execution signal, which owns admission only until inbox acceptance; once the child accepts the message the accepted turn cannot be cancelled through this tool. This call returns no child reply — its transcript by that id is the source of what it did — and a child with `report` sends content on its own initiative as a separate parent message. A delivery failure becomes an errored tool result stating the message was not delivered.
+The tool performs no lifecycle routing — residency and cold resume belong to the subagent service. It passes `exec.agent` as the exact live parent that authorizes delivery and records every message source as `{ kind: 'coordinator', senderSessionId: parent.id }`, which the service retains but never treats as authority. Every message becomes the subagent's next FIFO turn through `Agent.followup()`: if the child is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. The tool forwards its execution signal, which owns admission only until inbox acceptance; once the child accepts the message the accepted turn cannot be cancelled through this tool. This call returns no child reply — its transcript by that id is the source of what it did — and a child with `report` sends content on its own initiative as a separate parent message. A delivery failure becomes an errored tool result stating the message was not delivered.
 
 `interrupt_agent(agent_id)` passes `exec.agent` as the exact live ancestor authority for `ctx.subagents.interrupt()`: the target may be a direct child or a deeper descendant, and the service — never this tool — verifies the caller against the target Activation's recorded lineage. Only the target's current turn stops (`keepInbox`): queued messages stay parked until a later `send_message`, published descendants keep running, and the child stays available for follow-ups. The call returns as soon as the stop request is accepted, without waiting for target quiescence; an absent or already-settled target is an accepted no-op, while self, sibling, stale, and non-ancestor callers become errored results.
 
diff --git a/packages/subagent/tool-subagent-control/README.zh.md b/packages/subagent/tool-subagent-control/README.zh.md
index 6f7138571f..5939a1636a 100644
--- a/packages/subagent/tool-subagent-control/README.zh.md
+++ b/packages/subagent/tool-subagent-control/README.zh.md
@@ -4,7 +4,7 @@
 
 可选的全局具名 `send_message`、`interrupt_agent` 与 `list_agents` 工具是 `ctx.subagents` 之上的轻量适配器。绑定提供方的 `@deepseek-ai/dsh-tool-subagent` 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 `send_message` 与 `interrupt_agent`，且只要求 `subagents`；可单独加载的 `./list-agents` 插件注册 `list_agents`，并将 `subagents` 与 `agents` 声明为加载时依赖。其目录读取在调用时还要求会话存储与投影注册表，但不要求任何查询服务。部署可保留根插件工具并省略列表工具。是否加载这些工具不会决定委派工具是否启动可继续工作。这些工具只负责父到子的方向；单独安装的 [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) 负责子到父的方向。
 
-本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源标记为持久化来源 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
+本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源记录为 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
 
 `interrupt_agent(agent_id)` 将 `exec.agent` 作为 `ctx.subagents.interrupt()` 的确切在线 ancestor 授权传入：目标可以是直接 child 或更深的后代，由服务——而不是本工具——依据目标 Activation 记录的 lineage 校验调用方。只有目标的当前轮次会停止（`keepInbox`）：已排队的消息保持暂停直到之后的 `send_message`，已发布的后代继续运行，child 也仍可接受后续消息。调用在停止请求被接受后立即返回，不等待目标完全停稳；目标不存在或已结算是被接受的 no-op，而 self、sibling、过期与非 ancestor 调用方会成为出错结果。
 
diff --git a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
index 9b5f98dd7e..c5ea8fd1b8 100644
--- a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
@@ -132,7 +132,7 @@ describe('dsh-tool-subagent-control', () => {
 
     const loaded = await ctx.sessionPersistence.load(started.childId)
     const followUp = loaded.events.findLast(event => event.type === 'user/message')
-    // Durable provenance records the calling agent without granting authority.
+    // The durable message source records the calling agent without granting authority.
     expect(followUp?.type === 'user/message' && followUp.data.source).toEqual({
       kind: 'coordinator',
       form: 'relay',
diff --git a/packages/subagent/tool-subagent-report/README.i18n.yaml b/packages/subagent/tool-subagent-report/README.i18n.yaml
index 1b10e2628a..8d64d7e87f 100644
--- a/packages/subagent/tool-subagent-report/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-report/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/subagent/tool-subagent-report/README.md
-README.md: cd73154dfb9c8b37f4a811c3beedbe6a63207f58
-README.zh.md: 501598ec4e731b9315f3f08e0c81f5bb655c2b34
+README.md: 1772b72d83563e89ed0e3814e515b06a2b36fe0f
+README.zh.md: 94101fbc9611a04c56ed3a9171889499c9144c21
diff --git a/packages/subagent/tool-subagent-report/README.md b/packages/subagent/tool-subagent-report/README.md
index cd73154dfb..1772b72d83 100644
--- a/packages/subagent/tool-subagent-report/README.md
+++ b/packages/subagent/tool-subagent-report/README.md
@@ -46,7 +46,7 @@ Append-only in the child. In the parent, the framed report follows existing hist
 
 #### What the model sees
 
-One user-role parent message framed as `Background subagent <child-id> reported:` followed by the child's exact `output`, with durable provenance `{ kind: 'subagent-report', senderSessionId: <child-id> }`.
+One user-role parent message framed as `Background subagent <child-id> reported:` followed by the child's exact `output`, with a durable source `{ kind: 'subagent-report', senderSessionId: <child-id> }` that names the child.
 
 #### Token effect
 
diff --git a/packages/subagent/tool-subagent-report/README.zh.md b/packages/subagent/tool-subagent-report/README.zh.md
index 501598ec4e..94101fbc96 100644
--- a/packages/subagent/tool-subagent-report/README.zh.md
+++ b/packages/subagent/tool-subagent-report/README.zh.md
@@ -46,7 +46,7 @@
 
 #### 模型看到的内容
 
-一条用户角色的父级消息，以 `Background subagent <child-id> reported:` 开头，后接子级未经改动的 `output`，并带有持久化来源 `{ kind: 'subagent-report', senderSessionId: <child-id> }`。
+一条用户角色的父级消息，以 `Background subagent <child-id> reported:` 开头，后接子级未经改动的 `output`，并带有指明该子级的持久化来源 `{ kind: 'subagent-report', senderSessionId: <child-id> }`。
 
 #### Token 影响
 
diff --git a/packages/subagent/tool-subagent-report/tests/tool-subagent-report.spec.ts b/packages/subagent/tool-subagent-report/tests/tool-subagent-report.spec.ts
index ac90b4612b..17d5025c61 100644
--- a/packages/subagent/tool-subagent-report/tests/tool-subagent-report.spec.ts
+++ b/packages/subagent/tool-subagent-report/tests/tool-subagent-report.spec.ts
@@ -159,7 +159,7 @@ describe('dsh-tool-subagent-report', () => {
     expect(names).not.toContain('send_message')
   })
 
-  it('delivers quiet reports with stable identity and provenance without waking', async () => {
+  it('delivers quiet reports with stable message and sender identities without waking', async () => {
     const { ctx, parent, adapter } = await setup()
     const { started, child } = await startChild(ctx, parent)
     const parentRequests = adapter.requests.filter(request => request.sessionId === parent.id).length
diff --git a/packages/support/invariants/README.i18n.yaml b/packages/support/invariants/README.i18n.yaml
index 44427199b2..9d85ffd0a5 100644
--- a/packages/support/invariants/README.i18n.yaml
+++ b/packages/support/invariants/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/support/invariants/README.md
-README.md: 203dbd5ad09f5b1378061fbf9adcff885889eae2
-README.zh.md: 10f072e1d49b778944dfc0914eab48c527b21fed
+README.md: 71f7fb8b913610aad03694effad7746c0cb16499
+README.zh.md: ce2fc593a294a7f870bb42faa980fab462348e3b
diff --git a/packages/support/invariants/README.md b/packages/support/invariants/README.md
index 203dbd5ad0..71f7fb8b91 100644
--- a/packages/support/invariants/README.md
+++ b/packages/support/invariants/README.md
@@ -24,7 +24,7 @@ The service owns every registration fiber, while the returned disposer also belo
 
 `InvariantError` extends `Error`, carries stable `code: 'INVARIANT'`, and exposes the owning `packageName` without adding a product dependency to the service.
 
-Session itself owns immutable, surface-valid log storage in every composition: it takes one lossless JSON snapshot of each candidate, validates complete provenance and positional replacement, restricts `tool/result` replacement to one current result's `content`, deep-freezes the accepted record, and exposes the log through immutable array snapshots. The `dsh-session` invariant companion checks the remaining cross-record rules that Session does not own.
+Session itself owns immutable, surface-valid log storage in every composition: it takes one lossless JSON snapshot of each candidate, validates complete cited source-event coverage and positional replacement, restricts `tool/result` replacement to one current result's `content`, deep-freezes the accepted record, and exposes the log through immutable array snapshots. The `dsh-session` invariant companion checks the remaining cross-record rules that Session does not own.
 
 ## Package companions
 
diff --git a/packages/support/invariants/README.zh.md b/packages/support/invariants/README.zh.md
index 10f072e1d4..ce2fc593a2 100644
--- a/packages/support/invariants/README.zh.md
+++ b/packages/support/invariants/README.zh.md
@@ -24,7 +24,7 @@ interface Config {
 
 `InvariantError` 扩展 `Error`，携带稳定 `code: 'INVARIANT'`，并公开所属 `packageName`，而不向服务添加产品依赖。
 
-在每个组合中，Session 自身负责不可变且通过对外接口校验的日志存储：它对每个候选项制作一份无损 JSON 快照，验证完整来源和位置替换，将 `tool/result` 替换限制为一个当前结果的 `content`，深度冻结已接受记录，并通过不可变数组快照公开日志。`dsh-session` 不变量配套入口检查 Session 不负责的其余跨记录规则。
+在每个组合中，Session 自身负责不可变且通过对外接口校验的日志存储：它对每个候选项制作一份无损 JSON 快照，验证引用的源事件是否齐全以及位置替换是否合法，将 `tool/result` 替换限制为一个当前结果的 `content`，深度冻结已接受记录，并通过不可变数组快照公开日志。`dsh-session` 不变量配套入口检查 Session 不负责的其余跨记录规则。
 
 ## 包配套入口
 
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index 4be9e01c9d..5c9a575f5c 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -267,7 +267,7 @@ describe('deriveReplayScript', () => {
         seq: 1,
         time: 0,
         data: {
-          summary: [{ type: 'text', text: 'incomplete provenance' }],
+          summary: [{ type: 'text', text: 'missing source events' }],
           llmStreamCall: true,
           shadowedRange: { start: 1, end: 1 },
           shadowedSeqs: [1],
diff --git a/packages/util/environment/package.json b/packages/util/environment/package.json
index 6029a9f52a..15cbb603a5 100644
--- a/packages/util/environment/package.json
+++ b/packages/util/environment/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-environment",
-  "description": "Immutable launch-time environment snapshot with per-layer provenance for the DeepSeek Harness",
+  "description": "Immutable DeepSeek Harness launch environment that records which layer supplied each value",
   "version": "0.0.1",
   "private": true,
   "type": "module",
diff --git a/packages/util/environment/src/index.ts b/packages/util/environment/src/index.ts
index 741e5752cd..63a59c7337 100644
--- a/packages/util/environment/src/index.ts
+++ b/packages/util/environment/src/index.ts
@@ -1,6 +1,6 @@
 /**
- * Immutable launch-time environment snapshot with per-value source
- * provenance. Harness consumers resolve through it instead of a flattened
+ * Immutable launch-time environment snapshot that records which layer
+ * supplied each value. Harness consumers resolve through it instead of a flattened
  * `process.env`; launchers may still materialize accepted values for config
  * expressions and third-party libraries.
  * @module @deepseek-ai/dsh-environment
diff --git a/packages/workspace/workspace/src/index.ts b/packages/workspace/workspace/src/index.ts
index 71401862f2..ddd2b901b3 100644
--- a/packages/workspace/workspace/src/index.ts
+++ b/packages/workspace/workspace/src/index.ts
@@ -363,7 +363,7 @@ export class WorkspaceRegistry extends Service {
   /**
    * Complete the one mutation explicitly named by durable state. Unexplained
    * order/table divergence still reaches {@link validateStoredState} and
-   * fails loud; this path never infers provenance from shape alone.
+   * fails loud; this path never guesses which operation created a row from its shape alone.
    */
   private async recoverPendingMutation(): Promise<void> {
     const state = this.requireState()
@@ -608,7 +608,7 @@ export class WorkspaceRegistry extends Service {
   private enqueueOperation<T>(operation: () => Promise<T>): Promise<T> {
     const result = this.operationTail.then(async () => {
       // A committed delete may leave only its marker cleanup pending. Retry
-      // recovery before another create/delete can overwrite that provenance.
+      // recovery before another create/delete can overwrite that pending operation record.
       await this.recoverPendingMutation()
       return await operation()
     })
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 745bc23e4f..7991a7355e 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -1230,7 +1230,7 @@ function renderLifecycle(): string {
     `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
     '```',
     '',
-    'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
+    'The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history, while the durable event keeps usage and `sourceEventSeqs` listing the exact `assistant/chunk` events, including an explicit empty list.',
     '',
     '`dsh-compact-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
     '',

From 48882aa988b528fb9d1629f8dfff443e6ff14767 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:42:24 +0800
Subject: [PATCH 468/516] test(windows): isolate HMR alias identity

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index 1de504c221..b555645da8 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -8,12 +8,12 @@ import Loader from '@cordisjs/plugin-loader'
 import Timer from '@cordisjs/plugin-timer'
 import { describe, expect, it, vi } from 'vitest'
 
-async function bootHmr(dir: string, root: string[] = []): Promise<Context> {
+async function bootHmr(dir: string, root: string[] = [], usePolling?: boolean): Promise<Context> {
   const ctx = new Context()
   ctx.baseUrl = pathToFileURL(dir).href + '/'
   await ctx.plugin(Loader)
   await ctx.plugin(Timer)
-  await ctx.plugin(Hmr, { root, ignored: [], debounce: 0 })
+  await ctx.plugin(Hmr, { root, ignored: [], debounce: 0, usePolling })
   return ctx
 }
 
@@ -32,7 +32,9 @@ describe('HMR exact config paths', () => {
     const aliasFilename = join(alias, 'module.ts')
     symlinkSync(target, alias, process.platform === 'win32' ? 'junction' : 'dir')
     writeFileSync(aliasFilename, 'export const generation = 0\n')
-    const ctx = await bootHmr(alias, ['.'])
+    // This acceptance owns alias-to-cache identity. Other cases below exercise
+    // native events; polling keeps Windows fs.watch queue pressure out of it.
+    const ctx = await bootHmr(alias, ['.'], true)
     const filename = join(realpathSync(target), 'module.ts')
     const expected = pathToFileURL(filename).href
     const cacheHas = vi.spyOn(ctx.loader.internal!.loadCache, 'has').mockReturnValue(false)

From dcb45aae65b9ac4b37dd57712e62619daecd9040 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:43:01 +0800
Subject: [PATCH 469/516] test(windows): preserve watcher defaults

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index b555645da8..9a1bc250cd 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -13,7 +13,12 @@ async function bootHmr(dir: string, root: string[] = [], usePolling?: boolean):
   ctx.baseUrl = pathToFileURL(dir).href + '/'
   await ctx.plugin(Loader)
   await ctx.plugin(Timer)
-  await ctx.plugin(Hmr, { root, ignored: [], debounce: 0, usePolling })
+  await ctx.plugin(Hmr, {
+    root,
+    ignored: [],
+    debounce: 0,
+    ...usePolling === undefined ? {} : { usePolling },
+  })
   return ctx
 }
 

From 3766e333b1cfee2cf53842eebeae024c73fe9c29 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 15:51:34 +0800
Subject: [PATCH 470/516] test(snapshot): refresh session query tool schema

---
 .../snapshots/session-query-spill/tool-schemas.expected.json    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
index 7719bd3193..aed34842df 100644
--- a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
@@ -298,7 +298,7 @@
     },
     {
       "name": "session_event_trace",
-      "description": "Read every direct replacement and provenance relationship for one event in an authorized session.",
+      "description": "Read every direct replacement and relationship to a cited source event for one event in an authorized session.",
       "parameters": {
         "type": "object",
         "properties": {

From 96beea5cad22735d7c3f3bc8f3b8665a76f8cfbc Mon Sep 17 00:00:00 2001
From: xjt <xjt@example.com>
Date: Sun, 9 Aug 2026 16:02:05 +0800
Subject: [PATCH 471/516] fix(docs): align merged contract terminology

---
 ...24-web-config-tree-boot-and-transport-layering.i18n.yaml | 2 +-
 ...-07-24-web-config-tree-boot-and-transport-layering.zh.md | 2 +-
 .../2026-08-05-profile-plugin-bundles.i18n.yaml             | 2 +-
 .../architecture/2026-08-05-profile-plugin-bundles.zh.md    | 2 +-
 .../2026-08-09-headless-direct-core-front-door.i18n.yaml    | 2 +-
 .../2026-08-09-headless-direct-core-front-door.zh.md        | 6 +++---
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
index 2ee0de0625..ff517555db 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md
 2026-07-24-web-config-tree-boot-and-transport-layering.md: 496499a691dbca012e5e953cbb6eb1d0bf25b635
-2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 4a83db6f797ad2a0b048ef996d10dbc5ea0a33dd
+2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: c4bed7b730cf37e1d90750f5c93fbccb920ced21
diff --git a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
index 4a83db6f79..c4bed7b730 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md
@@ -25,7 +25,7 @@ Status: implemented
 ## 后果
 
 - 重组一个 web 部署 = 改 yml/patch；退役件（`mountWebPlugins`、`CLIENT_PACKAGES`、`createHostWebPluginRegistry`、`startWebServer`、webserver 的图/SSE/api 知识）全部删除。
-- [Headless 是直接 core 前门](2026-08-09-headless-direct-core-front-door.md)：其随附 profile 包含共享的 base Agent 能力，并省去 Host、HTTP、Web 与浏览器层。本笔记的传输划分是浏览器 surface 的契约。
+- [Headless 是直接 core 前门](2026-08-09-headless-direct-core-front-door.md)：其随附 profile 包含共享的 base Agent 能力，并省去 Host、HTTP、Web 与浏览器层。本笔记的传输划分是浏览器 surface 的约定。
 - 一个值得记住的 TypeScript 坑：`declare module 'cordis'` augmentation 所在文件若**没有任何 cordis import**，会被降级成独立 module declaration，无声打散全程序的 `Context` merge（`ctx.on`/`ctx.effect` 全程序消失）。用 `import type {} from 'cordis'` 锚定。
 
 ## 考虑过的替代方案
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index f5c23bd7e3..f68aeb97b3 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
 2026-08-05-profile-plugin-bundles.md: f183fc5ff5f3c8d850e913d9a9b836f075da7a3b
-2026-08-05-profile-plugin-bundles.zh.md: 294082249c2d3244321cb7efabf0eb286d11ef46
+2026-08-05-profile-plugin-bundles.zh.md: 8887bd39b7d0002f7c683ec74b7c91f002b18406
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index 294082249c..8887bd39b7 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest（元数据清单）`dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
 
-随附的组合包是 `@deepseek-ai/dsh-base`（共享核心配置行）、`@deepseek-ai/dsh-web-app`（浏览器 Host 配置行与 Web 运行时粘合层）和 `@deepseek-ai/dsh-headless`（直接叠加在 base 上且不含 web-app 的一次性 runner）。`dsh web` 是携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile；通用的 `dsh --profile <name>` 启动 profile 而不携带任务。patch overlay 使用 `--patch`。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 前门](2026-08-09-headless-direct-core-front-door.md)负责 headless 组合契约。
+随附的组合包是 `@deepseek-ai/dsh-base`（共享核心配置行）、`@deepseek-ai/dsh-web-app`（浏览器 Host 配置行与 Web 运行时粘合层）和 `@deepseek-ai/dsh-headless`（直接叠加在 base 上且不含 web-app 的一次性 runner）。`dsh web` 是携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile；通用的 `dsh --profile <name>` 启动 profile 而不携带任务。patch overlay 使用 `--patch`。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 前门](2026-08-09-headless-direct-core-front-door.md)负责 headless 组合约定。
 
 [`dsh run` 命令决策](../feature/2026-08-08-dsh-run-headless-command.md)负责一次性语法；本 Agent Note 负责该语法所选择的 profile 组合。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
index 921bc193e4..4088beaa7d 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
 2026-08-09-headless-direct-core-front-door.md: 875939b424059907949e350d50d88ded331f3dc9
-2026-08-09-headless-direct-core-front-door.zh.md: 7de5efbe172c0c43c03d55724d27e32d08c11e9f
+2026-08-09-headless-direct-core-front-door.zh.md: ff05661513f784ed735f823cf2a8ac28b267f694
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
index 7de5efbe17..ff05661513 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`headless` 的产品契约是一个本地任务：最终 assistant 文本写入 stdout，退出状态反映成功与否，成功时 stderr 为空，并且不打开监听端口。包含 Workspace Host 服务、ApiProxy、HTTP、Web 运行时或浏览器插件的组合违背这一契约，也使本地完成状态依赖无关的传输树。
+`headless` 的产品约定是一个本地任务：最终 assistant 文本写入 stdout，退出状态反映成功与否，成功时 stderr 为空，并且不打开监听端口。包含 Workspace Host 服务、ApiProxy、HTTP、Web 运行时或浏览器插件的组合违背这一约定，也使本地完成状态依赖无关的传输树。
 
 直接前门仍需要与 Web 所创建 Agent 相同的部署模型状态。独立的提供方／模型默认值会让同一部署产生两种答案，而在 Agent 与会话持久化完全停稳之前推导完成状态，会让 stdout 与退出状态观察到不完整状态。
 
@@ -20,7 +20,7 @@ Status: implemented
 
 `loadProfile` 识别安装过程拥有的精确 headless 元组（`dsh-base`、`dsh-web-app`、`dsh-headless`），将其规范化为随附的 headless 模板，并保留 manifest（元数据清单）的其他所有字段。带额外项、缺少项或顺序不同的组合包列表归用户所有，保持不变。
 
-本 Agent Note 负责 headless 的传输与完成契约。[`dsh run` 负责一次性 headless 执行](../feature/2026-08-08-dsh-run-headless-command.md)负责命令语法，[GUI 分层与 RPC 协议](2026-07-19-gui-layering-and-rpc-protocol.md)负责浏览器网关边界，[Web 配置树启动与传输分层](2026-07-24-web-config-tree-boot-and-transport-layering.md)负责 Web 插件树，[默认模型跟随选择器](../feature/2026-08-07-default-model-follows-the-picker.md)负责共享 Agent 默认值的持久化。
+本 Agent Note 负责 headless 的传输与完成约定。[`dsh run` 负责一次性 headless 执行](../feature/2026-08-08-dsh-run-headless-command.md)负责命令语法，[GUI 分层与 RPC 协议](2026-07-19-gui-layering-and-rpc-protocol.md)负责浏览器网关边界，[Web 配置树启动与传输分层](2026-07-24-web-config-tree-boot-and-transport-layering.md)负责 Web 插件树，[默认模型跟随选择器](../feature/2026-08-07-default-model-follows-the-picker.md)负责共享 Agent 默认值的持久化。
 
 ## 验证
 
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-| 替代方案 | 契约不匹配之处 |
+| 替代方案 | 约定不匹配之处 |
 |---|---|
 | 保留 `dsh-web-app`，但隐藏观察行 | 进程仍会打开端口并携带 Host、Web 与浏览器插件树。 |
 | 围绕 ApiProxy 构建纯 Host 一次性组合包 | ApiProxy 是客户端协议网关，而本地一次性前门没有客户端边界。 |

From 93e858faf969881c49e4fc3dc0e141b5527e542b Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 16:31:15 +0800
Subject: [PATCH 472/516] docs: address prose review findings

---
 .../2026-06-18-session-surface.i18n.yaml          |  4 ++--
 .../architecture/2026-06-18-session-surface.md    |  2 +-
 .../architecture/2026-06-18-session-surface.zh.md |  2 +-
 ...8-09-headless-direct-core-front-door.i18n.yaml |  4 ++--
 .../2026-08-09-headless-direct-core-front-door.md |  4 ++--
 ...26-08-09-headless-direct-core-front-door.zh.md |  4 ++--
 .../feature/2026-07-06-sandbox.i18n.yaml          |  4 ++--
 .../implemented/feature/2026-07-06-sandbox.md     |  2 +-
 .../implemented/feature/2026-07-06-sandbox.zh.md  |  2 +-
 .../2026-08-05-context-form-vocabulary.i18n.yaml  |  4 ++--
 .../feature/2026-08-05-context-form-vocabulary.md |  2 +-
 .../2026-08-05-context-form-vocabulary.zh.md      |  2 +-
 docs/config-catalog.md                            |  7 ++++---
 docs/persistence-catalog.md                       |  3 ++-
 docs/subsystems/session.i18n.yaml                 |  4 ++--
 docs/subsystems/session.md                        | 15 ++++++++-------
 docs/subsystems/session.zh.md                     | 15 ++++++++-------
 packages/bash/bash-sandbox/README.i18n.yaml       |  4 ++--
 packages/bash/bash-sandbox/README.md              |  4 ++--
 packages/bash/bash-sandbox/README.zh.md           |  4 ++--
 packages/core/session/README.i18n.yaml            |  4 ++--
 packages/core/session/README.md                   |  2 +-
 packages/core/session/README.zh.md                |  2 +-
 packages/core/session/src/types.ts                |  9 +++++----
 packages/host/apiproxy/src/api-proxy.ts           |  7 ++++---
 packages/sandbox/sandbox-local/src/index.ts       |  7 ++++---
 .../tests/tool-session-query.spec.ts              |  1 +
 packages/subagent/subagent/README.i18n.yaml       |  4 ++--
 packages/subagent/subagent/README.md              |  2 +-
 packages/subagent/subagent/README.zh.md           |  2 +-
 packages/subagent/subagent/src/types.ts           |  7 ++++---
 31 files changed, 74 insertions(+), 65 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
index b400a7b6c7..c10a8a497c 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.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 .agents/notes/implemented/architecture/2026-06-18-session-surface.md
-2026-06-18-session-surface.md: 3a033960e7cbf577c69c1df9940e064ef34163d3
-2026-06-18-session-surface.zh.md: 5c1348595589e8b69b0fe4a679f2536a83ef3142
+2026-06-18-session-surface.md: 73b3ab9080506edb9b0693c22a4c30544b506c11
+2026-06-18-session-surface.zh.md: 0c7ebbacd2f89da8012f3c08f1e4354a1d6c2e8e
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
index 3a033960e7..73b3ab9080 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
@@ -16,7 +16,7 @@ Add a **surface** — a derived, cached order of event sequences (the subset of
 
 Every `SessionEvent` gains two optional fields (structural metadata, like `seq`/`time`):
 
-- **`sourceEventSeqs?: number[]`** — seq numbers of earlier events cited as sources (e.g., the `assistant/chunk` seqs that built an `assistant/message`, or the surface nodes shadowed by a compaction marker). A present `[]` is valid only on `assistant/message` and records a known empty provider stream; omission there means a legacy or foreign event did not record the stream. Other surface events require a non-empty list when the field is present. Without these cited seqs, replay cannot validate that a replace-range operation names every event it removed.
+- **`sourceEventSeqs?: number[]`** — seq numbers of earlier events cited as sources (e.g., the `assistant/chunk` seqs that built an `assistant/message`, or the surface nodes shadowed by a compaction marker). A present `[]` is valid only on `assistant/message` and records a known empty provider stream; when the field is absent, a legacy or foreign event does not record which earlier events produced the message. Other surface events require a non-empty list when the field is present. Without these cited seqs, replay cannot validate that a replace-range operation names every event it removed.
 - **`surfaceOp?: SurfaceOp`** — how this event entered the surface. Absent for non-surface events.
 
 ### SurfaceOp: two operations
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
index 5c13485955..0c7ebbacd2 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 每个 `SessionEvent` 获得两个可选字段（结构性元数据，与 `seq`/`time` 同级）：
 
-- **`sourceEventSeqs?: number[]`**：被引用为数据来源的早期事件 seq 编号（例如构成 `assistant/message` 的各 `assistant/chunk` 的 seq，或被压缩标记遮蔽的 surface 节点）。出现的 `[]` 只在 `assistant/message` 上有效，表示已知为空的提供方流；在该事件上省略字段，表示某个旧事件或外部事件没有记录该流。其他 surface 事件一旦出现此字段，就必须是非空列表。如果没有这些引用的 seq，回放就无法验证 replace-range 操作是否列出了它移除的每个事件。
+- **`sourceEventSeqs?: number[]`**：被引用为数据来源的早期事件 seq 编号（例如构成 `assistant/message` 的各 `assistant/chunk` 的 seq，或被压缩标记遮蔽的 surface 节点）。出现的 `[]` 只在 `assistant/message` 上有效，表示已知为空的提供方流；旧格式或外部事件缺少该字段时，没有记录这条消息由哪些早期事件产生。其他 surface 事件一旦出现此字段，就必须是非空列表。如果没有这些引用的 seq，回放就无法验证 replace-range 操作是否列出了它移除的每个事件。
 - **`surfaceOp?: SurfaceOp`**：该事件如何进入 surface。非 surface 事件不携带此字段。
 
 ### SurfaceOp：两种操作
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
index 921bc193e4..46d4a76284 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.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 .agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
-2026-08-09-headless-direct-core-front-door.md: 875939b424059907949e350d50d88ded331f3dc9
-2026-08-09-headless-direct-core-front-door.zh.md: 7de5efbe172c0c43c03d55724d27e32d08c11e9f
+2026-08-09-headless-direct-core-front-door.md: f4604329a9276448a0021bb749b09e8c1b82e3c1
+2026-08-09-headless-direct-core-front-door.zh.md: 1299840f84eb4dacb093f1e6551bef03636b338f
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
index 875939b424..f4604329a9 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md
@@ -24,7 +24,7 @@ This note owns the headless transport and completion contracts. [`dsh run` owns
 
 ## Verification
 
-Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, terminal model diagnostics, other non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshots drive `dsh run` through a replayed tool round trip, record direct user-message provenance, and expose a terminal model failure on stderr. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
+Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, terminal model diagnostics, other non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshots drive `dsh run` through a replayed tool round trip, record a `user/message` with `source.kind: 'user'`, and expose a terminal model failure on stderr. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
 
 ## Alternatives considered
 
@@ -39,6 +39,6 @@ Package tests use the real Session store and Agent registry around a scripted Ag
 
 ## Consequences
 
-`dsh run` provides a local Agent task rather than browser observation, Host APIs, or HTTP. Users who need those capabilities choose `dsh web`. Successful stderr is empty, completion follows durable flush, and the persisted Session remains available to later tooling. Its initial user message has direct user provenance and therefore carries no ApiProxy `rpcId`.
+`dsh run` provides a local Agent task rather than browser observation, Host APIs, or HTTP. Users who need those capabilities choose `dsh web`. Successful stderr is empty, completion follows durable flush, and the persisted Session remains available to later tooling. Its initial user message records `source.kind: 'user'` and therefore carries no ApiProxy `rpcId`.
 
 ApiProxy carrier coverage stays in the ApiProxy package. Custom one-shot profiles may include Host or Web bundles explicitly, while the shipped profile and the recognized installation-owned tuple are Web-free.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
index 7de5efbe17..1299840f84 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 ## 验证
 
-包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、终止态模型诊断、其他未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，记录直接用户消息的来源，并在 stderr 暴露终止态模型失败。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
+包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、终止态模型诊断、其他未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，记录一条带 `source.kind: 'user'` 的 `user/message`，并在 stderr 暴露终止态模型失败。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
 
 ## 考虑过的替代方案
 
@@ -39,6 +39,6 @@ Status: implemented
 
 ## 后果
 
-`dsh run` 提供本地 Agent 任务，而不是浏览器观察、Host API 或 HTTP。需要这些能力的用户选择 `dsh web`。成功时 stderr 为空，完成结果在持久化 flush 后推导，持久化会话仍可供后续工具使用。初始用户消息直接来自用户，因此不携带 ApiProxy `rpcId`。
+`dsh run` 提供本地 Agent 任务，而不是浏览器观察、Host API 或 HTTP。需要这些能力的用户选择 `dsh web`。成功时 stderr 为空，完成结果在持久化 flush 后推导，持久化会话仍可供后续工具使用。初始用户消息记录 `source.kind: 'user'`，因此不携带 ApiProxy `rpcId`。
 
 ApiProxy 载体覆盖保留在 ApiProxy 包中。自定义一次性 profile 可以显式包含 Host 或 Web 组合包；随附 profile 与可识别的安装过程所属元组均不含 Web。
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index 5982d816f9..fdb075d228 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: d73bb5520ffba43142c70e3197ae033db1af67d9
-2026-07-06-sandbox.zh.md: 5fc2ee7c4a53df22fab93c358824a10dca89989e
+2026-07-06-sandbox.md: 943b1e27ff2d61a56e5532a20b9983d181c15e29
+2026-07-06-sandbox.zh.md: 89a73afb6154363b9d3e7c1afedbda386994325a
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index d73bb5520f..943b1e27ff 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -70,7 +70,7 @@ Backend profiles share the mode contract but differ in necessary host grants. La
 
 #### The bash consumer
 
-`dsh-bash-sandbox` extends `LocalBashExecutor`, hands `ctx.sandbox` the exact `['bash', '-c', command]` argv, and directly spawns the provider result. This leaves shell semantics and `BASH_ENV` on the inner Bash after the shipped native runner establishes confinement. A provider error propagates unchanged. A pre-process rejection is runner-owned only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` whose error path equals provider argv[0]; a bare `syscall: 'spawn'` without an exact error path, other codes, invalid workdirs, resource failures, unrelated syscalls, and unstructured rejections retain local command-start semantics. Foreground execution converts runner-owned rejections to `SANDBOX_UNAVAILABLE` with the original detail; an asynchronous background rejection stamps `runnerFailed: true`, `denied: false`. A `SubprocessService` that synchronously throws the same shape with the runner path makes background start throw `SANDBOX_UNAVAILABLE`, while other synchronous errors propagate unchanged. After a process starts, foreground and background use one runner-failure classifier that requires the rule's exit-code gate and a remaining fatal line after informational exclusions. A match outranks denial: foreground execution throws `SANDBOX_UNAVAILABLE` with that fatal line as detail; a settled `BashProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `task_output`.
+`dsh-bash-sandbox` extends `LocalBashExecutor`, hands `ctx.sandbox` the exact `['bash', '-c', command]` argv, and directly spawns the provider result. This leaves shell semantics and `BASH_ENV` on the inner Bash after the shipped native runner establishes confinement. A provider error propagates unchanged. A pre-process rejection counts as a runner failure only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with either an `error.path` equal to provider argv[0] or, when `error.path` is absent, an exact `syscall: 'spawn <runner>'`; a present path also requires `syscall: 'spawn'` or the exact `spawn <runner>`. Other codes, invalid workdirs, resource failures, unrelated syscalls, and unstructured rejections retain local command-start semantics. Foreground execution converts runner failures to `SANDBOX_UNAVAILABLE` with the original detail; an asynchronous background rejection stamps `runnerFailed: true`, `denied: false`. A `SubprocessService` that synchronously throws the same runner-identifying shape makes background start throw `SANDBOX_UNAVAILABLE`, while other synchronous errors propagate unchanged. After a process starts, foreground and background use one runner-failure classifier that requires the rule's exit-code check and a remaining fatal line after informational exclusions. A match takes priority over denial: foreground execution throws `SANDBOX_UNAVAILABLE` with that fatal line as detail; a settled `BashProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `task_output`.
 
 The model sees the current effective file policy in the owner-derived `sandbox:policy` context, while the static tool description explains the denial marker (`[sandbox: file access denied under <mode> mode]`), encourages attempting commands that may be denied, and forbids retrying around a denial; when the escalation fields are advertised, a denied result additionally carries the escalation hint itself, so the sanctioned same-turn retry is prompted at the decision point rather than depending on the model recalling the description (§ Escalation). [The current-policy decision](2026-07-30-current-sandbox-policy-context.md) owns the context's rationale and boundaries.
 
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index 5fc2ee7c4a..89a73afb61 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -70,7 +70,7 @@ Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 
 
 #### bash 消费方
 
-`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，把精确的 `['bash', '-c', command]` argv 交给 `ctx.sandbox`，并直接 spawn 提供方返回的 argv。这样，随附的原生 runner 建立约束后，shell 语义与 `BASH_ENV` 仍由内层 Bash 处理。提供方错误原样传播。进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且错误对象的 `path` 字段等于提供方返回的 `argv[0]` 时，拒绝才会归因于 runner；没有精确错误路径的裸 `syscall: 'spawn'`、其他错误码、无效 workdir、资源失败、无关 syscall 与无结构拒绝保留本地命令启动语义。前台执行会将可归因于 runner 的拒绝转为 `SANDBOX_UNAVAILABLE` 并附上原始详细信息；异步后台拒绝则盖章 `runnerFailed: true`、`denied: false`。如果 `SubprocessService` 同步抛出同样带有 runner 路径的形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，前台与后台共用一个 runner 失败分类器：先排除信息性行，再要求规则的退出码门控与余下的一行致命诊断同时匹配。匹配结果优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`，并以该致命行作为详细信息；结算后的 `BashProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `task_output` 渲染它。
+`dsh-bash-sandbox` 扩展 `LocalBashExecutor`，把精确的 `['bash', '-c', command]` argv 交给 `ctx.sandbox`，并直接 spawn 提供方返回的 argv。这样，随附的原生 runner 建立约束后，shell 语义与 `BASH_ENV` 仍由内层 Bash 处理。提供方错误原样传播。进程启动前，只有当调用方拥有的 workdir 经独立验证可用，Node 报告 `ENOENT` 或 `EACCES`，并且错误符合以下一种形态时，才判定为 runner 失败：`error.path` 等于提供方返回的 `argv[0]`，同时 `syscall` 为 `'spawn'` 或精确的 `'spawn <runner>'`；或者 `error.path` 不存在，同时 `syscall` 为精确的 `'spawn <runner>'`。其他错误码、无效 workdir、资源失败、无关 syscall 与无结构拒绝保留本地命令启动语义。前台执行会将 runner 失败转为 `SANDBOX_UNAVAILABLE` 并附上原始详细信息；异步后台拒绝则盖章 `runnerFailed: true`、`denied: false`。如果 `SubprocessService` 同步抛出同样能指明 runner 的形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，前台与后台共用一个 runner 失败分类器：先排除信息性行，再要求规则的退出码检查与余下的一行致命诊断同时匹配。匹配结果优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`，并以该致命行作为详细信息；结算后的 `BashProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `task_output` 渲染它。
 
 模型会在归属方派生的 `sandbox:policy` 上下文中看到当前有效的文件策略；静态工具描述则解释拒绝标记（`[sandbox: file access denied under <mode> mode]`），鼓励尝试可能被拒绝的命令，并禁止绕过拒绝重试。当升级字段被公布时，被拒绝的结果还会携带升级提示本身，使被认可的同轮次重试在决策点获得提示，而非依赖模型回忆描述（§ 升级机制）。[当前策略决策](2026-07-30-current-sandbox-policy-context.md)负责该上下文的理由与边界。
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
index e407eccd64..1ae3905478 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.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 .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
-2026-08-05-context-form-vocabulary.md: 7750523b89ebdda125a7bae8a853ab28a20eeb3f
-2026-08-05-context-form-vocabulary.zh.md: 8a6ced60b254ddf5e9075d199be98b3fbe442e2b
+2026-08-05-context-form-vocabulary.md: 3362059974443d1f6b543358e1eaba99ef239e43
+2026-08-05-context-form-vocabulary.zh.md: cee66c0b39f6dadd8579d7d95c4051e0c712e620
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
index 7750523b89..3362059974 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
@@ -51,7 +51,7 @@ The tool seam pairs its vocabulary with `presentCall(args)`, a host-side pure fu
 
 **Map source kinds to renderers in the client.** Cheapest to write and requires no format change, but it puts producer knowledge back in the client: every new kind then needs a client release to render as anything but opaque, and a foreign log cannot be classified at all. It also reintroduces exactly the coupling the [source and steer marks decision](2026-08-04-web-context-source-and-steer-marks.md) removed for labels.
 
-**Reuse `kind` as the form.** One discriminant is simpler, and `workspace-instructions` is already 1:1 with its form. It breaks on the shared shapes: three producers emit runtime snapshots today, and folding them into one kind would erase which producer supplied each message. Two axes keep the producer exact while letting presentations be shared.
+**Reuse `kind` as the form.** One discriminant is simpler, and `workspace-instructions` is already 1:1 with its form. This design loses information when several producers share one form: three producers emit runtime snapshots today, and combining them into one kind would make it impossible to tell which producer supplied each message. Separate `kind` and `form` fields record the producer while allowing several producers to share one presentation.
 
 **Let the client parse the model-facing prose.** The entries and file sections are visibly structured in the text. Parsing them couples the presentation to prompt wording, so every reword silently breaks a card — the same reason catalog identity moved off the text.
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
index 8a6ced60b2..cee66c0b39 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
@@ -51,7 +51,7 @@ Status: implemented
 
 **在客户端把来源 kind 映射到渲染器。** 写起来最省，也不用改格式，但它把生产方知识放回了客户端：此后每新增一个 kind 都要客户端发版才能渲染成 opaque 以外的东西，而外部日志根本无法分类。它还会重新引入[来源与 steer 标识决策](2026-08-04-web-context-source-and-steer-marks.md)刚为名称去掉的那种耦合。
 
-**复用 `kind` 充当形态。** 单一判别式更简单，`workspace-instructions` 本来也与它的形态一一对应。但它在共享形状上就崩了：今天有三个生产方发出运行时快照，把它们并成一个 kind 会删除每条消息中标明其生产方的 `source` 字段。两根轴会保留准确的生产方，同时让呈现方式可以共享。
+**复用 `kind` 充当形态。** 单一判别式更简单，`workspace-instructions` 本来也与它的形态一一对应。但多个生产方共享同一形态时，这种设计无法保留完整信息：今天有三个生产方发出运行时快照，把它们并成一个 kind 后，将无法分辨每条消息由哪个生产方提供。独立的 `kind` 和 `form` 字段会记录生产方，同时允许多个生产方共用一种呈现方式。
 
 **让客户端解析面向模型的散文。** 条目与文件分节在文本里确实有可见结构。解析它们会把呈现耦合到 prompt 措辞上，于是每改一次文案就静默碎掉一张卡——这也正是目录身份从文本上迁走的原因。
 
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 4c49120f17..e1d0374afa 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1196,9 +1196,10 @@ export interface Config {
    * Override the runner argv; bwrap-shaped profile arguments are appended. A
    * non-empty override asserts full enforcement and skips built-in selection and
    * probing. A runner that starts but refuses its profile must be identifiable by
-   * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
-   * attributable `ENOENT` or `EACCES` whose error path equals runner argv[0] becomes an
-   * infrastructure failure.
+   * {@link runnerFailureSignatures}. Consumers classify a spawn rejection only after
+   * confirming the workdir is usable. `ENOENT` or `EACCES` identifies the runner when
+   * `error.path` equals argv[0] and `error.syscall` is `spawn` or `spawn <runner>`, or
+   * when `error.path` is absent and `error.syscall` is exactly `spawn <runner>`.
    */
   runnerCommand?: string[]
   /**
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 975a882706..614f6afbeb 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -68,7 +68,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means the source stream was not recorded.
+     * provider stream; when the field is absent, the event does not record which
+     * earlier events produced the message.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 890563b91d..da4ec0a16b 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 6fb39e946cf5acdc407aab99888d40960d617248
-session.zh.md: 30edd630b4c945d3b696b5ac346b4bcebfb3df16
+session.md: 4b057317969c8dc59c899fb07812e01a0b5d94d3
+session.zh.md: 804edc32635ddfcc1335ecd9c0a6c4df4f998594
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 6fb39e946c..4b05731796 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -221,7 +221,8 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means the source stream was not recorded.
+     * provider stream; when the field is absent, the event does not record which
+     * earlier events produced the message.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -232,7 +233,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 `SessionEventType = keyof SessionEventMap`. Because `SessionEventMap` is merge-extensible, switches over `SessionEvent` must NOT use `assertNever` — a plugin-added variant is a valid unknown value; handle the known cases and fall through `default`.
 
-For `assistant/message`, a present `sourceEventSeqs: []` is a complete known-empty provider stream, while an absent field means the source stream was not recorded in a legacy or foreign event. The loop writes the field for every successful model call; every other surface event requires a non-empty list when the field is present.
+For `assistant/message`, a present `sourceEventSeqs: []` is a complete known-empty provider stream, while a legacy or foreign event with no field does not record which earlier events produced the message. The loop writes the field for every successful model call; every other surface event requires a non-empty list when the field is present.
 
 ## Surface types
 
@@ -285,9 +286,9 @@ interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
    * Complete set of known source-event seqs. `assistant/message` may use a
-   * present empty array for a known empty provider stream; omission means its
-   * source stream was not recorded. Other surface events require a non-empty set
-   * when this field is present.
+   * present empty array for a known empty provider stream; when the field is
+   * absent, the event does not record which earlier events produced the message.
+   * Other surface events require a non-empty set when this field is present.
    */
   sourceEventSeqs?: number[]
 }
@@ -295,7 +296,7 @@ interface SurfaceIntent {
 
 Required for `SurfaceEventType` events — every message-producing event must declare how it joins the surface, the sole source of derived model history. A human-facing transcript is the other projection and reads the log's append-origin events instead, because the surface deliberately shadows the ranges a replacement summarizes (`isAppendSurfaceEvent` in [dsh-session](../../packages/core/session/README.md)). Non-surface types reject it at compile time.
 
-Only `assistant/message` may carry a present empty `sourceEventSeqs`; omission means the source stream was not recorded and does not assert that the stream was empty.
+Only `assistant/message` may carry a present empty `sourceEventSeqs`; when the field is absent, the event does not record which earlier events produced the message, and the provider may still have emitted chunks.
 
 ### `SessionSurface` — the live readonly surface projection
 
@@ -577,7 +578,7 @@ Activity ordering excludes the boundary through `lastActivityTime(events)`: pick
 
 ## Plugin-contributed log-only events
 
-A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The generated [persistence log event catalog](../persistence-catalog.md) enumerates every core and plugin-contributed event with its payload, surface badge, cited source-event seqs, and declaration site; the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).
+A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The generated [persistence log event catalog](../persistence-catalog.md) enumerates every core and plugin-contributed event with its payload, surface badge, and declaration site; the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).
 
 The hook bridges' `hook/invoked` / `hook/result` pairs (from `@deepseek-ai/dsh-hook-protocol`) correlate by `handlerId`. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` fire inside the loop's open turn, so their `hook/*` records are turn-enclosed by construction. `SessionStart` gets no `hook/*` record because it runs before turn 1; its context remains pending in the inbox until a waking delivery opens a turn (see [the hook-bridges Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)).
 
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 30edd630b4..804edc3263 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -223,7 +223,8 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means the source stream was not recorded.
+     * provider stream; when the field is absent, the event does not record which
+     * earlier events produced the message.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
@@ -234,7 +235,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 `SessionEventType = keyof SessionEventMap`。由于 `SessionEventMap` 可通过合并扩展，对 `SessionEvent` 的 switch 语句禁止使用 `assertNever`：插件添加的变体是合法的未知值；处理已知 case 后在 `default` 中放行。
 
-对于 `assistant/message`，存在的 `sourceEventSeqs: []` 表示提供方流已知且完整地为空；字段缺失则表示旧格式或外部事件没有记录源流。agent loop 会为每次成功的模型调用写入该字段；其他 surface 事件只要包含该字段，其列表就必须非空。
+对于 `assistant/message`，存在的 `sourceEventSeqs: []` 表示提供方流已知且完整地为空；旧格式或外部事件缺少该字段时，没有记录这条消息由哪些早期事件产生。agent loop 会为每次成功的模型调用写入该字段；其他 surface 事件只要包含该字段，其列表就必须非空。
 
 ## Surface 类型
 
@@ -287,9 +288,9 @@ interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
    * Complete set of known source-event seqs. `assistant/message` may use a
-   * present empty array for a known empty provider stream; omission means its
-   * source stream was not recorded. Other surface events require a non-empty set
-   * when this field is present.
+   * present empty array for a known empty provider stream; when the field is
+   * absent, the event does not record which earlier events produced the message.
+   * Other surface events require a non-empty set when this field is present.
    */
   sourceEventSeqs?: number[]
 }
@@ -297,7 +298,7 @@ interface SurfaceIntent {
 
 对 `SurfaceEventType` 事件必填：每个产生消息的事件都必须声明它如何加入 surface（派生模型历史的唯一来源）。面向人类的记录（transcript）是另一个投影，读取的是日志中追加来源的事件，因为 surface 会有意遮蔽替换所概括的范围（见 [dsh-session](../../packages/core/session/README.md) 的 `isAppendSurfaceEvent`）。非 surface 类型在编译期拒绝此参数。
 
-只有 `assistant/message` 可以携带存在但为空的 `sourceEventSeqs`；省略该字段表示源流没有记录，而不是表示源流为空。
+只有 `assistant/message` 可以携带存在但为空的 `sourceEventSeqs`；字段不存在时，该事件没有记录这条消息由哪些早期事件产生，但提供方仍可能发出过分片。
 
 ### `SessionSurface`：实时只读 surface 投影
 
@@ -581,7 +582,7 @@ interface TurnEndReasonMap {
 
 ## 插件贡献的仅日志事件
 
-插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。生成的[持久化日志事件目录](../persistence-catalog.md)会列出每个核心或插件贡献的事件，以及其 payload、surface 标记、被引用的来源事件 seq 和声明位置；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
+插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。生成的[持久化日志事件目录](../persistence-catalog.md)会列出每个核心或插件贡献的事件，以及其 payload、surface 标记和声明位置；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
 
 钩子桥接层的 `hook/invoked` / `hook/result` 对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次（见[钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)）。
 
diff --git a/packages/bash/bash-sandbox/README.i18n.yaml b/packages/bash/bash-sandbox/README.i18n.yaml
index 97ea5f301b..426f2901e5 100644
--- a/packages/bash/bash-sandbox/README.i18n.yaml
+++ b/packages/bash/bash-sandbox/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/bash/bash-sandbox/README.md
-README.md: 3ac46eaef8a0c6ee47c3141e2580c4d2e7750e8c
-README.zh.md: 4f3fb85c8de00497e4aff546d8234a81336586cb
+README.md: 884681ec73990af600833756caf5dd7305b0d481
+README.zh.md: a19b4cae4606a56ae5ce496fa9f0c10ba2eb9156
diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md
index 3ac46eaef8..884681ec73 100644
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -17,7 +17,7 @@ Every command is confined by handing the provider the exact `['bash', '-c', comm
 Semantics:
 
 - **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `BashRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI).
-- **Runner attribution is conservative.** Before a process starts, a rejection is attributed to the runner only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` whose error path equals provider argv[0]. This covers a missing runner, a non-executable runner, or an executable script whose shebang interpreter is unavailable. A bare `syscall: 'spawn'` without an exact error path, any other code, an invalid or unusable workdir, a resource failure, an unrelated syscall, or an unstructured rejection retains the local executor's command-start failure semantics. Foreground execution throws `SANDBOX_UNAVAILABLE` with the original spawn detail, while asynchronous background settlement stamps `runnerFailed: true` and `denied: false`. If a `SubprocessService` synchronously throws the same `ENOENT`/`EACCES` shape with the runner path, background start throws `SANDBOX_UNAVAILABLE`; other synchronous errors propagate unchanged. After a process starts, a rule's optional exit-code gate and a remaining fatal stderr line must both match after exact informational-line exclusions. A match outranks denial; foreground execution throws `SANDBOX_UNAVAILABLE` with the matched fatal line, while a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`. Confined background handles retain their mode/enforcement facts and release per-process accounting in either path.
+- **The runner path or syscall must match.** Before a process starts, a rejection is attributed to the runner only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with either an `error.path` equal to provider argv[0] or, when `error.path` is absent, an exact `syscall: 'spawn <runner>'`. A present path also requires `syscall: 'spawn'` or the exact `spawn <runner>`. This covers a missing runner, a non-executable runner, or an executable script whose shebang interpreter is unavailable. A bare `syscall: 'spawn'` without an exact error path, any other code, an invalid or unusable workdir, a resource failure, an unrelated syscall, or an unstructured rejection retains the local executor's command-start failure semantics. Foreground execution throws `SANDBOX_UNAVAILABLE` with the original spawn detail, while asynchronous background settlement stamps `runnerFailed: true` and `denied: false`. If a `SubprocessService` synchronously throws the same runner-identifying `ENOENT`/`EACCES` shape, background start throws `SANDBOX_UNAVAILABLE`; other synchronous errors propagate unchanged. After a process starts, a rule's optional exit-code check and a remaining fatal stderr line must both match after exact informational-line exclusions. A match takes priority over denial; foreground execution throws `SANDBOX_UNAVAILABLE` with the matched fatal line, while a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`. Confined background handles retain their mode/enforcement facts and release per-process accounting in either path.
 - **Deployment fallback, per-call policy.** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) resolves a complete `SandboxExecutionPolicy` for every tool call: the calling session supplies its mode override and immutable cwd root, while deployment config supplies the fallbacks for agentless calls. An approved escalation changes only that policy's mode; its session root stays attached. `resolve()` carries the policy onto the spec, so overlapping commands from different projects run, classify, and report under their own roots and modes. The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted; the static bash tool description separately owns denial and escalation guidance.
 - **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce.
 - Process mechanics (spawn, process-group kills, output collection/spill, background handles, credential scrub) are inherited from [`dsh-bash-local`](../bash-local/); runner selection lives in [`dsh-sandbox-local`](../../sandbox/sandbox-local/).
@@ -70,7 +70,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-If no runner can enforce a confined mode, the foreground call propagates the [`SANDBOX_UNAVAILABLE` error owned by `dsh-sandbox`](../../sandbox/sandbox/README.md#confinement-error-indirectly). A runner-attributable spawn failure supplies the original spawn error as detail; a rejection without `ENOENT`/`EACCES` argv[0] evidence remains an ordinary command-start error. A settled runner failure supplies the matched fatal stderr line and preserves the original stderr collection. When present, the appended `Runner failure: <detail>` is the authoritative diagnosis; the preceding backend-install text is the generic `SANDBOX_UNAVAILABLE` prefix.
+If no runner can enforce a confined mode, the foreground call propagates the [`SANDBOX_UNAVAILABLE` error owned by `dsh-sandbox`](../../sandbox/sandbox/README.md#confinement-error-indirectly). A runner-attributable spawn failure supplies the original spawn error as detail; a rejection without `ENOENT`/`EACCES` path or syscall evidence that names argv[0] remains an ordinary command-start error. A settled runner failure supplies the matched fatal stderr line and preserves the original stderr collection. When present, the appended `Runner failure: <detail>` is the authoritative diagnosis; the preceding backend-install text is the generic `SANDBOX_UNAVAILABLE` prefix.
 
 #### Token effect
 
diff --git a/packages/bash/bash-sandbox/README.zh.md b/packages/bash/bash-sandbox/README.zh.md
index 4f3fb85c8d..a19b4cae46 100644
--- a/packages/bash/bash-sandbox/README.zh.md
+++ b/packages/bash/bash-sandbox/README.zh.md
@@ -17,7 +17,7 @@
 语义：
 
 - **拒绝是结果事实。** 如果一次失败运行的 stderr 包含所选后端自身的拒绝方言，即提供方在每次包装时加上的特征（bwrap 下的 EROFS 文本、Landlock 下的 EACCES、Seatbelt 下的 EPERM），则结果报告 `BashRunResult.sandbox.denied: true`（从已收集的 stderr 尾部进行保守分类）。每次受限制运行还会携带执行时模式（`result.sandbox.mode`）与提供方强制执行完整性（`result.sandbox.enforcement`：`full`，或在较旧 Landlock ABI 上为 `partial`）。
-- **Runner 归因是保守的。** 进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且错误对象的 `path` 字段等于提供方返回的 `argv[0]` 时，才会将拒绝归因于 runner。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessService` 同步抛出同样带 runner 路径的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，先按整行精确匹配排除信息性行，随后规则的可选退出码门控和余下 stderr 中的一行致命诊断必须同时匹配。匹配结果优先于拒绝；前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带匹配到的致命行，已结算的后台进程则会标记 `process.sandbox.runnerFailed`，Bash 结果生成方通过通用 `task_output` 渲染它。无论走哪条路径，受限制的后台句柄都会保留自身的模式／强制执行事实，并释放每进程计数。
+- **Runner 路径或 syscall 必须匹配。** 进程启动前，调用方拥有的 workdir 必须经独立验证可用，Node 必须报告 `ENOENT` 或 `EACCES`，并且错误必须符合以下一种形态：`error.path` 等于提供方返回的 `argv[0]`，同时 `syscall` 为 `'spawn'` 或精确的 `'spawn <runner>'`；或者 `error.path` 不存在，同时 `syscall` 为精确的 `'spawn <runner>'`。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessService` 同步抛出同样能指明 runner 的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，先按整行精确匹配排除信息性行，随后规则的可选退出码检查和余下 stderr 中的一行致命诊断必须同时匹配。匹配结果优先于拒绝；前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带匹配到的致命行，已结算的后台进程则会标记 `process.sandbox.runnerFailed`，Bash 结果生成方通过通用 `task_output` 渲染它。无论走哪条路径，受限制的后台句柄都会保留自身的模式／强制执行事实，并释放每进程计数。
 - **部署回退，每次调用策略。** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) 为每次工具调用解析完整的 `SandboxExecutionPolicy`：调用会话提供自身的模式覆盖与不可变 cwd 根目录，部署配置则为无 agent（智能体）调用提供回退。已批准的升权只更改该策略的模式，会话根目录仍然附着其上。`resolve()` 把策略带入 spec，因此来自不同项目的重叠命令会在各自的根目录与模式下运行、分类和报告。能力事实 `ctx.bash.sandboxMode` 报告已配置的默认值，因此工具层只在装载该执行器时才公布升权；静态 bash 工具描述则单独负责拒绝与升权引导。
 - **只限制文件影响。** 设计上不限制网络与进程可见性：模式词汇不会声称覆盖后端未强制执行的范围。
 - 进程机制（spawn、进程组终止、输出收集／spill、后台句柄、凭证清理）继承自 [`dsh-bash-local`](../bash-local/)；runner 选择位于 [`dsh-sandbox-local`](../../sandbox/sandbox-local/)。
@@ -70,7 +70,7 @@
 
 #### 模型看到的内容
 
-如果没有 runner 能强制执行受限模式，前台调用会传播 [`SANDBOX_UNAVAILABLE` 错误](../../sandbox/sandbox/README.md#confinement-error-indirectly)；该错误由 `dsh-sandbox` 定义。可归因于 runner 的 spawn 失败会以原始 spawn 错误作为详细信息；没有 `ENOENT`／`EACCES` argv[0] 证据的拒绝仍是普通的命令启动错误。已结算的 runner 失败则以匹配到的致命 stderr 行作为详细信息，并保留原始 stderr 收集结果。如果追加了 `Runner failure: <detail>`，它就是权威诊断；前面的后端安装文本只是通用的 `SANDBOX_UNAVAILABLE` 前缀。
+如果没有 runner 能强制执行受限模式，前台调用会传播 [`SANDBOX_UNAVAILABLE` 错误](../../sandbox/sandbox/README.md#confinement-error-indirectly)；该错误由 `dsh-sandbox` 定义。判定为 runner 失败的 spawn 错误会以原始 spawn 错误作为详细信息；如果拒绝没有通过 `ENOENT`／`EACCES` 的 `path` 或 `syscall` 证据指明 `argv[0]`，它仍是普通的命令启动错误。已结算的 runner 失败则以匹配到的致命 stderr 行作为详细信息，并保留原始 stderr 收集结果。如果追加了 `Runner failure: <detail>`，它就是权威诊断；前面的后端安装文本只是通用的 `SANDBOX_UNAVAILABLE` 前缀。
 
 #### Token 影响
 
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index 67364cb415..71cb01a34d 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
-README.md: 04d3cec7e431f5f265d52851eae59600536ce5b7
-README.zh.md: e9529b3c91c8d2413c64b4e344af83b6ebe698de
+README.md: 09e027c82fe1a81d97b3e70d95231ccc553e3ed1
+README.zh.md: 3fdd1e68b18f5ce4b3846ca0d2376b968a0754e3
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index 04d3cec7e4..09e027c82f 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -68,7 +68,7 @@ A `user/message` stores the complete `UserMessage` directly, including the ident
 
 ### Session event vocabulary (`types.ts`)
 
-The generated [persistence log event catalog](../../../docs/persistence-catalog.md) enumerates each append-only event type with its payload, surface badge, cited source-event seqs, and declaration site. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Each `assistant/message` records the provider, model, and optional replay state.
+The generated [persistence log event catalog](../../../docs/persistence-catalog.md) enumerates each append-only event type with its payload, surface badge, and declaration site. Token accounting reads per-step `assistant/chunk { type: 'usage' }` records and treats `assistant/message.usage` as the committed-step fallback when no usage chunk exists; failed model-request attempts have no assistant message. Each `assistant/message` records the provider, model, and optional replay state.
 
 Merge-extensible via `SessionEventMap` — a plugin declaration-merges its own types (the compaction seam's `compact/*`, bounded recovery's non-surface `llm/retry`, the hook bridges' `hook/*`); merged members appear in the same catalog. A plugin owns the relational invariant for its merged events, including whether a log-only event may appear between turns. A producer that requires durability appends through `Session` and then awaits `ctx.sessions.flush(session)` without fabricating an execution turn.
 
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index e9529b3c91..3fdd1e68b1 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -68,7 +68,7 @@
 
 ### 会话事件词汇（`types.ts`）
 
-生成的[持久化日志事件目录](../../../docs/persistence-catalog.md)逐成员列举仅追加日志的事件类型、载荷、surface 标记、被引用的源事件 seq 与声明位置。Token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息。每条 `assistant/message` 都会记录提供方、模型和可选回放状态。
+生成的[持久化日志事件目录](../../../docs/persistence-catalog.md)逐成员列举仅追加日志的事件类型、载荷、surface 标记与声明位置。Token 记账读取每个步骤的 `assistant/chunk { type: 'usage' }` 记录；如果没有用量分片，则将 `assistant/message.usage` 作为已提交步骤的后备。失败的模型请求尝试没有 assistant 消息。每条 `assistant/message` 都会记录提供方、模型和可选回放状态。
 
 `SessionEventMap` 可通过合并扩展：插件使用声明合并添加自身类型（压缩 seam 的 `compact/*`、有界恢复的非 surface `llm/retry`、hook（钩子）桥接层的 `hook/*`）；合并成员会出现在同一目录中。插件拥有其合并事件的关系不变量，包括是否允许纯日志事件出现在轮次之间。需要持久性的生产方通过 `Session` 追加，再等待 `ctx.sessions.flush(session)`，无需虚构一个执行轮次。
 
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index c1071e1e01..1c9a622643 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -352,9 +352,9 @@ export interface SurfaceIntent {
   surfaceOp: SurfaceOp
   /**
    * Complete set of known source-event seqs. `assistant/message` may use a
-   * present empty array for a known empty provider stream; omission means its
-   * source stream was not recorded. Other surface events require a non-empty set
-   * when this field is present.
+   * present empty array for a known empty provider stream; when the field is
+   * absent, the event does not record which earlier events produced the message.
+   * Other surface events require a non-empty set when this field is present.
    */
   sourceEventSeqs?: number[]
 }
@@ -386,7 +386,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
      * or the surface nodes shadowed by a compaction replace node). An
      * `assistant/message` may carry a present empty array for a known empty
-     * provider stream; omission means the source stream was not recorded.
+     * provider stream; when the field is absent, the event does not record which
+     * earlier events produced the message.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index a4ce497c1d..fde6cd32ee 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -1506,9 +1506,10 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
               )
             }
             // Host visibility is the authorization boundary. Consume the
-            // provider's globally ranked stream rather than binding every
-            // visible id into one SQLite statement, then re-check complete
-            // provider id before emitting any snippet.
+            // provider's globally ranked results rather than binding every
+            // visible id into one SQLite statement, then require each hit to
+            // name a visible session and a current message from that same
+            // session before emitting its snippet.
             for (const hit of page.items) {
               if (authorized.length > SESSION_SEARCH_RESULT_LIMIT) continue
               if (
diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts
index 0b1cf3a34d..67698f80b4 100644
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -26,9 +26,10 @@ export interface Config {
    * Override the runner argv; bwrap-shaped profile arguments are appended. A
    * non-empty override asserts full enforcement and skips built-in selection and
    * probing. A runner that starts but refuses its profile must be identifiable by
-   * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
-   * attributable `ENOENT` or `EACCES` whose error path equals runner argv[0] becomes an
-   * infrastructure failure.
+   * {@link runnerFailureSignatures}. Consumers classify a spawn rejection only after
+   * confirming the workdir is usable. `ENOENT` or `EACCES` identifies the runner when
+   * `error.path` equals argv[0] and `error.syscall` is `spawn` or `spawn <runner>`, or
+   * when `error.path` is absent and `error.syscall` is exactly `spawn <runner>`.
    */
   runnerCommand?: string[]
   /**
diff --git a/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts b/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts
index db1cc4483b..23ca3f939e 100644
--- a/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts
+++ b/packages/session-query/tool-session-query/tests/tool-session-query.spec.ts
@@ -1978,6 +1978,7 @@ describe('trace and exact read rendering', () => {
     )
     const result = await mounted.call('session_event_trace', { session_id: session.id, seq: 0 })
     expect(text(result)).toContain('Replacement chain: 1')
+    expect(text(result)).toContain('Events cited directly as sources: none')
     expect(text(result)).toContain('Direct derived events: 1')
     expect(text(result)).toContain(new Date(session.events[0]?.time ?? 0).toISOString())
   })
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index e1ba59aa50..4fac8ecd2e 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: 7658dad2fc8d79ca178ed5467448de9527f7bc49
-README.zh.md: 8d3bc4b96ac366e919256f4409ebd54d3505de87
+README.md: a1b5807e5e9e880879e39e0bacaa1a54743f227e
+README.zh.md: 823227af1841730c8fd926295bf7c4ca74497255
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 7658dad2fc..a1b5807e5e 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -72,7 +72,7 @@ A continuation-managed parent Activation records each child Session id in an `ow
 
 ## Lifecycle events
 
-The service emits a `subagent/start`/`subagent/end` pair for each one-shot run and each resident continuable Activation epoch, so continuable children are observable with the same vocabulary as one-shot runs without exposing whether the manager materialized, woke, or cold-resumed them. For a one-shot start it attaches the result observer before the synchronous `subagent/start`, so even an already-settled child still produces `subagent/start` before `subagent/end`; a continuable epoch that fails before residency emits neither edge. The pair shares a service-minted `runId`; the `local` flag is snapshotted from the provider's exact `localAgent` (always true for a continuable child), so observers never infer run identity or locality from reusable provider/session names. The `provider` field names the provider that started the run or Activation epoch rather than claiming current registration: an accepted one-shot run may settle after provider removal, and a cold-resumed epoch retains its descriptor's initial provider name without requiring that provider to be registered.
+The service emits a `subagent/start`/`subagent/end` pair for each one-shot run and each resident continuable Activation epoch, so continuable children are observable with the same vocabulary as one-shot runs without exposing whether the manager materialized, woke, or cold-resumed them. For a one-shot start it attaches the result observer before the synchronous `subagent/start`, so even an already-settled child still produces `subagent/start` before `subagent/end`; a continuable epoch that fails before residency emits neither edge. The pair shares a service-minted `runId`; the `local` flag is snapshotted from the provider's exact `localAgent` (always true for a continuable child), so observers never infer run identity or locality from reusable provider/session names. The `provider` field contains the provider name recorded when the child was first created rather than claiming current registration: an accepted one-shot run may settle after provider removal, and a cold-resumed epoch reads the initial provider name from its descriptor without calling or registering that provider.
 
 Run events are scoped to the delegating parent. Every listener is independently contained: a synchronous throw or rejected returned promise is logged without starving peer listeners or changing the run.
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 8d3bc4b96a..823227af18 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -72,7 +72,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 生命周期事件
 
-服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不会发出这对生命周期事件中的任何一个。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段指明启动该运行或 Activation 时段的提供方，不表示该提供方当前仍在注册：已接受的一次性 run 可在提供方移除后才结算，冷恢复时段也会保留描述符中的初始提供方名称，而不要求该提供方仍处于注册状态。
+服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不会发出这对生命周期事件中的任何一个。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段包含子 agent 初次创建时记录的提供方名称，不表示该提供方当前仍在注册：已接受的一次性 run 可在提供方移除后才结算；冷恢复时段会从描述符读取初始提供方名称，不会调用或注册该提供方。
 
 运行事件受执行委派的父级作用域约束。每个监听器都独立隔离：同步抛出或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变运行。
 
diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts
index b003b75507..f83b65f559 100644
--- a/packages/subagent/subagent/src/types.ts
+++ b/packages/subagent/subagent/src/types.ts
@@ -37,9 +37,10 @@ export interface SubagentRunInfo {
   /** Unique identity shared with the paired terminal event. */
   readonly runId: SubagentRunId
   /**
-   * Provider that started this run or Activation epoch. The named provider
-   * may be absent when an accepted run becomes ready or a persisted Activation
-   * cold-resumes, because neither lifecycle depends on continued registration.
+   * Provider name recorded when the child was first created. The provider may
+   * be absent when an accepted one-shot run becomes ready or a persisted
+   * Activation cold-resumes, because neither lifecycle depends on continued
+   * registration.
    */
   readonly provider: string
   /** The child agent's id. */

From 455e6ec583d3bdbc5deebf229af5e0b7b488348e Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 16:40:13 +0800
Subject: [PATCH 473/516] fix(hmr): await module watcher readiness

---
 ...8-native-windows-pull-request-ci.i18n.yaml |  4 +-
 ...26-08-08-native-windows-pull-request-ci.md |  2 +-
 ...08-08-native-windows-pull-request-ci.zh.md |  2 +-
 vendor/README.md                              |  2 +-
 vendor/hmr/src/index.ts                       | 41 ++++++++++++++-----
 5 files changed, 36 insertions(+), 15 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index 8cc2763444..75d7f8b670 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: e98de723dfe118a297a2e9074d94d52dd6dddc47
-2026-08-08-native-windows-pull-request-ci.zh.md: 02ad94b095c8fd1361c4b113d486f8091bb9cf5a
+2026-08-08-native-windows-pull-request-ci.md: 4e2ea07e90656f212f0613ffa17184ff2c3c8c45
+2026-08-08-native-windows-pull-request-ci.zh.md: 306243af3f3e0b280dd25caa5c99df2176590f3b
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index e98de723df..4e2ea07e90 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -16,7 +16,7 @@ Every pull request also starts an independent `windows-native` job named `window
 
 The native gate keeps workspace build and production-site failures blocking inside its own job while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
 
-The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path.
+The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path. Module HMR attaches listeners and awaits the main watcher's ready event before plugin startup settles, so an immediate post-boot edit cannot race the initial scan.
 
 The next exact-head run exposed one remaining observational built-bin failure: its lifecycle fixtures used `process.kill()` or `subprocess.kill()` to send `SIGTERM`, which unconditionally terminates a Windows target instead of delivering the registered process event for graceful disposal. POSIX acceptance still sends the real signal. On Windows the fixture requests that same registered event from inside the child, directly for a self-terminating probe and through a marker for parent-controlled lifecycle cases, so the assembled shutdown and disposal path remains covered without asserting an operating-system facility that does not exist. That acceptance then exposed the underlying early-shutdown race: a signal could dispose the root after boot returned while fallback HMR watchers were mounting, and the resulting inactive-service error escaped as a boot failure. Post-boot setup now admits work only while the authoritative root fiber is active and contains a concurrent setup error only when the same invocation's recorded signal already owns shutdown; unrelated HMR failures remain loud.
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 02ad94b095..306243af3f 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 原生门禁在其自身作业内继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
 
-首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。
+首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。模块 HMR 会挂接监听器并等待主 watcher 的 ready 事件，之后插件启动才会完成，因此启动后立即发生的编辑无法与初始扫描形成竞态。
 
 下一次分支头精确运行暴露出观测项中剩余的一项 built-bin 故障：其生命周期 fixture（测试前置数据）通过 `process.kill()` 或 `subprocess.kill()` 发送 `SIGTERM`；在 Windows 上，这种调用会无条件终止目标进程，而不会交付为优雅释放所注册的进程事件。POSIX 验收仍发送真实信号。在 Windows 上，fixture 改为从子进程内部请求同一个已注册事件：自终止探测直接请求，由父进程控制的生命周期场景则通过标记请求；因此，完整组装后的关闭与释放路径仍得到覆盖，也无需断言操作系统提供了本不存在的信号机制。该项验收随即暴露出底层的提前关闭竞态：boot 返回后，回退 HMR watcher 仍在挂载，此时信号可能对根 fiber 执行 dispose（资源释放），由此产生的服务未激活错误会逸出并被报告为 boot 失败。boot 后 setup 现在只会在权威根 fiber 仍处于活跃状态时接纳工作；只有当本次调用所记录的信号已取得关闭流程所有权时，才会隔离并发 setup 错误，无关的 HMR 故障仍会响亮失败。
 
diff --git a/vendor/README.md b/vendor/README.md
index a5e998ef39..c2004c36e0 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -38,7 +38,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 6. **`cordis/src/fiber.ts` lifecycle hardening**: locally closes three reentrant disposal gaps. An effect's owner-list wrapper is registered before its setup body runs, so an unload begun from inside setup awaits setup and every collected cleanup; synchronous setup failure removes the wrapper and rolls back collected cleanup. Async cleanup stays owner-visible until quiescence, and Cordis's internal effect composition joins an already-running cleanup while repeated public disposer calls retain their upstream single-shot result. Effect creation is rejected while the owner is `UNLOADING` (while `PENDING` and `LOADING` remain legal), preventing cleanup-time registrations from escaping the unload snapshot. Child fibers register and receive their parent-owned disposer before `internal/plugin` publication, resolve dependency declarations added by that notification before activation, drain effects attached while pending, skip plugin execution when reentrant disposal invalidates the load epoch before its first checkpoint, and contain teardown-notification failures per observer so one callback cannot starve peers or interrupt ownership cleanup. `Fiber.update()` returns its `internal/update` waterfall result, allowing Loader callers to await a restart while preserving synchronous config validation.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **Transactional Loader/Include config reconciliation**: Loader imports a changed entry name before disposal, awaits lifecycle settlement, and restores the previous plugin or config when candidate application fails. Loader settlement rechecks service-gated fibers after current tasks drain, rejects failures, and leaves fibers with absent dependencies pending. Group updates start candidates concurrently, await every outcome, undo changes and additions on failure, await removal, preserve programmatic option identity, and persist direct or tree-level mutations only after success. Include reads and validates detached candidate content, applies patches to a clone, reconciles the tree, and only then commits its cached content/data; direct refresh failures propagate for the caller to contain. A non-array parse is invalid, patches re-apply on every file or Include-config update, an omitted patch list clears the overlay, and initial content falls back to `initial` only on `ENOENT`. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts` and `packages/host/webserver/tests/webserver.spec.ts`.
-9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Module watches realpath their existing base directory and use that spelling for Node module-cache identity; exact config watches realpath the deepest existing watch ancestor and restore the missing suffix. Those native paths prevent Windows short-name aliases from colliding with long-form libuv event paths while exact-config callbacks keep the requested filename. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
+9. **`hmr/src/index.ts` exact config watching**: `registerConfig()` watches one absolute config path outside module roots, including a path under missing parents, serializes and coalesces refreshes, and returns an async disposer that closes the watcher and drains active work. Module watches realpath their existing base directory, attach change listeners before declaring the service ready, and use that spelling for Node module-cache identity; exact config watches realpath the deepest existing watch ancestor and restore the missing suffix. Those native paths prevent Windows short-name aliases from colliding with long-form libuv event paths while exact-config callbacks keep the requested filename. Refresh failures are normalized to `Error`, logged, and broadcast through the parallel `hmr/config-update-failed` event; observer failures are contained. Config-file changes discovered by the ordinary HMR watcher use the same serialized path. Covered by `packages/boot/app-boot/tests/hmr-config.spec.ts`.
 10. **`loader/src/repository.ts`, `loader/tsdown.config.ts`, and the `@cordisjs/plugin-loader/repository` export**: the Node-only `RepositoryCache` installs one exact dependency specifier through the bundled `pnpm@11.7.0`, single-flights callers, and atomically publishes only a prepared package plus marker under the specifier hash. The subpath stays out of the browser-reachable Loader entry. Identical specifiers permanently reuse that entry; callers change the ref/specifier for another generation. A transaction-owned `pnpm` wrapper makes pnpm's nested Git-package install reinvoke the same bundled entry with `--ignore-workspace`, so the selected package installs its own manifest dependencies instead of joining an enclosing source workspace. The temporary command directory is removed after the child settles. The isolated workspace permits dependency build scripts because a configured repository is executable code, while the child drops ambient credential-shaped variables. Covered by `packages/boot/app-boot/tests/repository-cache.spec.ts`, including a keyless local-Git `prepack` whose package is excluded from an enclosing pnpm lockfile and obtains both its build and prepare commands from declared dependencies.
 11. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
 12. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm. `applyEntryPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes an empty profile root with each bundle's patch layer, the profile's and the home-level `cordis.patch.yml`, and any `--patch` overlays as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/boot/app-boot/tests/config-reload.spec.ts`.
diff --git a/vendor/hmr/src/index.ts b/vendor/hmr/src/index.ts
index 7c36201b13..169ee2e00a 100644
--- a/vendor/hmr/src/index.ts
+++ b/vendor/hmr/src/index.ts
@@ -214,6 +214,17 @@ class Hmr extends Service {
 
     const match = picomatch(ignored)
     const watchBaseDir = await realpath(this.baseDir)
+
+    // Collect externals before opening the watcher so every post-ready change
+    // is observed by listeners that already have their classification state.
+    const mainUrl = pathToFileURL(resolve(process.argv[1])).href
+    const mainJob = this.internal.loadCache.get(mainUrl)
+    if (mainJob) {
+      this.externals = await loadDependencies(mainJob)
+    } else {
+      this.externals = new Set()
+    }
+
     this.watcher = watch(root, {
       ...this.config,
       cwd: watchBaseDir,
@@ -228,16 +239,6 @@ class Hmr extends Service {
       ignoreInitial: true,
     })
 
-    // Collect externals: framework modules reachable from the main entry.
-    // Changes to these files require a full process restart, not HMR.
-    const mainUrl = pathToFileURL(resolve(process.argv[1])).href
-    const mainJob = this.internal.loadCache.get(mainUrl)
-    if (mainJob) {
-      this.externals = await loadDependencies(mainJob)
-    } else {
-      this.externals = new Set()
-    }
-
     const partialReload = this.ctx.debounce(() => this.partialReload(), this.config.debounce)
 
     const onChange = (kind: 'add' | 'change' | 'unlink', path: string) => {
@@ -271,6 +272,26 @@ class Hmr extends Service {
     this.watcher.on('add', path => onChange('add', path))
     this.watcher.on('change', path => onChange('change', path))
     this.watcher.on('unlink', path => onChange('unlink', path))
+
+    const ready = Promise.withResolvers<void>()
+    let readyState: 'pending' | 'resolved' | 'rejected' = root.length === 0 ? 'resolved' : 'pending'
+    if (root.length === 0) {
+      ready.resolve()
+    } else {
+      this.watcher.once('ready', () => {
+        readyState = 'resolved'
+        ready.resolve()
+      })
+    }
+    this.watcher.on('error', (error) => {
+      if (readyState === 'pending') {
+        readyState = 'rejected'
+        ready.reject(error)
+      } else {
+        this.ctx.logger.warn(error)
+      }
+    })
+    await ready.promise
   }
 
   private refreshConfig(key: object, filename: string, refresh: () => Promise<void> | void) {

From 829e874ed2d42fc0dd2916797384b540511b3f06 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 16:42:54 +0800
Subject: [PATCH 474/516] docs: keep prose rule within budget

---
 docs/AGENTS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 4dc640fa93..a7e6b06747 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -42,7 +42,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 - **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
-- Write for professional programmers. Use concise, direct English without metaphor. Name the actor, source, event, field, or process; use words you would say to a colleague ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Do not overuse "gate", "vocabulary", "surface", or "seam".
+- Write directly without metaphor. Name actors and exact facts; use words you'd say to a colleague ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Avoid "gate", "vocabulary", "surface", or "seam".
 
 ## Wordcount Budgets
 

From e94cacd088273a31a3ae19ea33f95ffc90c237f1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 16:50:20 +0800
Subject: [PATCH 475/516] test(hmr): separate repeated watcher failures

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index 9a1bc250cd..dbb3a8ca83 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -185,6 +185,9 @@ describe('HMR exact config paths', () => {
       expect(observed.error).toBeInstanceOf(Error)
       expect(observed.error.message).toBe('42')
 
+      // Let Chokidar's atomic-write window close before requiring a distinct
+      // second notification from the same path.
+      await new Promise(resolve => setTimeout(resolve, 250))
       writeFileSync(filename, 'invalid again')
       await eventually(() => failureCount === 2, 'HMR stopped broadcasting after an observer rejected')
     } finally {

From 27ac49e6877e638d9c9d91c30316875a052d2b80 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Mon, 20 Jul 2026 14:45:32 +0800
Subject: [PATCH 476/516] docs: define a seam as the (Service, Service
 provider, Consumer) trio

---
 .../architecture/2026-06-13-capability-seams.i18n.yaml      | 4 ++--
 .../implemented/architecture/2026-06-13-capability-seams.md | 4 ++++
 .../architecture/2026-06-13-capability-seams.zh.md          | 4 ++++
 AGENTS.md                                                   | 2 +-
 docs/architecture.i18n.yaml                                 | 4 ++--
 docs/architecture.md                                        | 4 +++-
 docs/architecture.zh.md                                     | 4 +++-
 docs/glossary.i18n.yaml                                     | 4 ++--
 docs/glossary.md                                            | 4 ++++
 docs/glossary.zh.md                                         | 4 ++++
 docs/i18n/terminology.md                                    | 2 +-
 docs/subsystems/bash.i18n.yaml                              | 4 ++--
 docs/subsystems/bash.md                                     | 4 ++--
 docs/subsystems/bash.zh.md                                  | 4 ++--
 docs/subsystems/code-runtime.i18n.yaml                      | 4 ++--
 docs/subsystems/code-runtime.md                             | 4 ++--
 docs/subsystems/code-runtime.zh.md                          | 4 ++--
 docs/subsystems/compaction.i18n.yaml                        | 4 ++--
 docs/subsystems/compaction.md                               | 4 ++--
 docs/subsystems/compaction.zh.md                            | 4 ++--
 docs/subsystems/credentials.i18n.yaml                       | 4 ++--
 docs/subsystems/credentials.md                              | 4 ++--
 docs/subsystems/credentials.zh.md                           | 4 ++--
 docs/subsystems/filesystem.i18n.yaml                        | 4 ++--
 docs/subsystems/filesystem.md                               | 6 +++---
 docs/subsystems/filesystem.zh.md                            | 6 +++---
 docs/subsystems/persistence.i18n.yaml                       | 4 ++--
 docs/subsystems/persistence.md                              | 6 +++---
 docs/subsystems/persistence.zh.md                           | 6 +++---
 docs/subsystems/sandbox.i18n.yaml                           | 4 ++--
 docs/subsystems/sandbox.md                                  | 4 ++--
 docs/subsystems/sandbox.zh.md                               | 4 ++--
 docs/subsystems/session-query.i18n.yaml                     | 4 ++--
 docs/subsystems/session-query.md                            | 4 ++--
 docs/subsystems/session-query.zh.md                         | 4 ++--
 docs/subsystems/settings.i18n.yaml                          | 4 ++--
 docs/subsystems/settings.md                                 | 4 ++--
 docs/subsystems/settings.zh.md                              | 4 ++--
 docs/subsystems/spill.i18n.yaml                             | 4 ++--
 docs/subsystems/spill.md                                    | 4 ++--
 docs/subsystems/spill.zh.md                                 | 4 ++--
 docs/subsystems/subprocess.i18n.yaml                        | 4 ++--
 docs/subsystems/subprocess.md                               | 6 +++---
 docs/subsystems/subprocess.zh.md                            | 6 +++---
 docs/subsystems/tasks.i18n.yaml                             | 4 ++--
 docs/subsystems/tasks.md                                    | 4 ++--
 docs/subsystems/tasks.zh.md                                 | 4 ++--
 docs/subsystems/telemetry.i18n.yaml                         | 4 ++--
 docs/subsystems/telemetry.md                                | 6 +++---
 docs/subsystems/telemetry.zh.md                             | 6 +++---
 docs/subsystems/workflow.i18n.yaml                          | 4 ++--
 docs/subsystems/workflow.md                                 | 4 ++--
 docs/subsystems/workflow.zh.md                              | 4 ++--
 docs/subsystems/workspace.i18n.yaml                         | 4 ++--
 docs/subsystems/workspace.md                                | 4 ++--
 docs/subsystems/workspace.zh.md                             | 4 ++--
 packages/bash/bash/README.i18n.yaml                         | 4 ++--
 packages/bash/bash/README.md                                | 2 +-
 packages/bash/bash/README.zh.md                             | 2 +-
 packages/code-runtime/code-runtime/README.i18n.yaml         | 4 ++--
 packages/code-runtime/code-runtime/README.md                | 2 +-
 packages/code-runtime/code-runtime/README.zh.md             | 2 +-
 packages/compact/compact/README.i18n.yaml                   | 4 ++--
 packages/compact/compact/README.md                          | 2 +-
 packages/compact/compact/README.zh.md                       | 2 +-
 packages/fs/fs/README.i18n.yaml                             | 4 ++--
 packages/fs/fs/README.md                                    | 2 +-
 packages/fs/fs/README.zh.md                                 | 2 +-
 packages/spill/spill/README.i18n.yaml                       | 4 ++--
 packages/spill/spill/README.md                              | 2 +-
 packages/spill/spill/README.zh.md                           | 2 +-
 packages/typert/generator/src/cordis-catalog.ts             | 6 +-----
 .../typert/generator/tests/cordis-catalog-contract.spec.ts  | 2 +-
 packages/web/web/README.i18n.yaml                           | 4 ++--
 packages/web/web/README.md                                  | 2 +-
 packages/web/web/README.zh.md                               | 2 +-
 .../translation-prompt-v4/request-response.expected.json    | 2 +-
 77 files changed, 155 insertions(+), 139 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
index 2a310c8172..4a8f0149e2 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.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 .agents/notes/implemented/architecture/2026-06-13-capability-seams.md
-2026-06-13-capability-seams.md: 7c755dced7825d2831acc0901f6412b8e5afe95a
-2026-06-13-capability-seams.zh.md: 31d20bb15f91533ab3c09d337a3cb11f812dbeb4
+2026-06-13-capability-seams.md: 1bad79a9d6d46e56afba862521403ee7c921ba21
+2026-06-13-capability-seams.zh.md: a44913539eed800f82d3f270fef05be17f524a2c
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
index 7c755dced7..1bad79a9d6 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
@@ -22,6 +22,10 @@ Implementation and consumer then evolve independently: a sandboxed executor repl
 
 The split is not mandatory when the parts are genuinely one concern: the LLM seam folds interface + consumer into `dsh-llm` (the consumer is the loop itself, not a swappable schema surface) with adapters as the implementation packages. Don't split preemptively — a capability with one conceivable implementation and one consumer stays one package until a second appears.
 
+## Terminology: "seam" names the trio, not the interface
+
+A **seam** is the whole capability — the three roles together: a **Service Definition** (the Cordis `Service` that owns `ctx.<key>` and the vocabulary; an abstract class such as `BashExecutor`, or a concrete registry such as `WebService`), one or more **Service providers** (implementations that register a backend), and a **Consumer** (the model- or plugin-facing surface). `packages/bash` is the canonical example — `dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`. The interface package alone is the *Service Definition*, one member — not the seam. The Service Definition is never a TypeScript `interface`; where prose must name it, use the class name or `abstract class`, never `interface`. Reserving "seam" strictly for the trio and realigning the many existing "the X seam" usages is deferred to a follow-up; the [glossary](../../../../docs/glossary.md#capability-seam) is the canonical entry.
+
 ## Alternatives considered
 
 - **One combined package** — rejected because it recouples the three rates of change the split exists to separate (the whole point).
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
index 31d20bb15f..a44913539e 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
@@ -22,6 +22,10 @@ harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化
 
 当各部分确实属于同一个关注点时，三分并非强制：LLM（大语言模型） seam 将接口 + 消费方合并为 `dsh-llm`（消费方是 agent loop（智能体循环）本身，而非可替换的 schema 接口），适配器作为实现包。不要预防性地拆分——如果一项能力只有一种可设想的实现和一个消费方，就保持为一个包，直到出现第二种实现或第二个消费方。
 
+## 术语：seam 指三者组合，而非接口
+
+一个 **seam** 是完整的能力——三个角色合在一起：**Service Definition**（拥有 `ctx.<key>` 和词汇的 Cordis `Service`；可以是 `BashExecutor` 这样的抽象类，也可以是 `WebService` 这样的具体注册表）、一个或多个 **Service provider**（注册后端的实现）和 **Consumer**（面向模型或插件的表面）。`packages/bash` 是规范范例——`dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`。接口包本身只是 *Service Definition*，是其中一个成员——不是 seam。Service Definition 从不是 TypeScript `interface`；在正文必须命名它时，使用类名或 `abstract class`，永远不要用 `interface`。严格把「seam」保留给三者组合，并校准现有大量「X seam」用法的工作推迟到后续；[术语表](../../../../docs/glossary.md#capability-seam)是规范条目。
+
 ## 曾考虑的替代方案
 
 - **单一合并包**：否决。因为它重新耦合了三分设计本要分离的三种变化速率（这正是拆分的意义所在）。
diff --git a/AGENTS.md b/AGENTS.md
index deabc5ed99..def643ad95 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -104,7 +104,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
 - **Plugins, not loop changes**: new behavior goes on the documented extension seams; changing `agent-loop` requires updating docs/architecture.md.
-- **Capability seams are three packages** — interface / implementation / consumer; don't split preemptively.
+- **Capability seams span three packages** — interface / implementation / consumer; don't split preemptively. The seam is all three ([glossary](docs/glossary.md#capability-seam)).
 - **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).
 - **Explicit > implicit at package seams**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-bash` request/spec split is the template).
 - **No hardcoded tunables in plugins**: deployment-varying choices are validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test seam is not configurability. Protocol constants, external specs, and security invariants stay fixed.
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index f380ec5e42..7c8b1b95c8 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 5e009d8345112bb0adcb2f55b4e49bbbf3bf8d00
-architecture.zh.md: a1f01d734819d76276ae5b9ec74b4a7f9e98fc93
+architecture.md: bb76e6ce106bf6ab06b3a12b536aabbae581740f
+architecture.zh.md: eb2fc4dea190914d0b5f0732db571c81f2f0d471
diff --git a/docs/architecture.md b/docs/architecture.md
index 5e009d8345..bb76e6ce10 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -156,7 +156,9 @@ Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is on
 
 ### Capability Pattern
 
-Capabilities separate **interface / implementation / consumer** layers. Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks. See the [capability graph](capability-seams.md).
+A **seam** is a swappable capability across three packages: a **Service Definition** (the Cordis `Service` owning its `ctx` key and vocabulary), a **Service provider** (the implementation plugin), and a **Consumer**. The Service Definition alone is the service, not the seam. Bash is the reference; the [capability graph](capability-seams.md) shows every family.
+
+Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks.
 
 Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](subsystems/subagent.md)).
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index a1f01d7348..eb2fc4dea1 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -156,7 +156,9 @@ idle inject:
 
 ### 能力模式
 
-能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[能力图](capability-seams.md)。
+一个 **seam** 是跨三个包的一项可替换能力：**Service Definition**（拥有自身 `ctx` key 和词汇的 Cordis `Service`）、**Service provider**（实现插件）和 **Consumer**。Service Definition 本身只是服务，不是 seam。Bash 是参考；[能力图](capability-seams.md)展示每个家族。
+
+文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。
 
 例外情况包括 LLM（大语言模型）接口／消费方合并、文件系统策略、web 注册表，以及具名 skill/subagent 提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。
 
diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml
index ab9b5cec1d..b9dd5915c0 100644
--- a/docs/glossary.i18n.yaml
+++ b/docs/glossary.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 docs/glossary.md
-glossary.md: 16409517bff623a80d6e1e00888d95f63b42f780
-glossary.zh.md: a84447dd067a3364033601742c116583661cdf45
+glossary.md: acb093b097da62c92e3ade07f2dcb454eee576d2
+glossary.zh.md: ddf76edb1fd7e810badb68fadc0e3c67f2bc2b58
diff --git a/docs/glossary.md b/docs/glossary.md
index 16409517bf..acb093b097 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -4,6 +4,10 @@ English | [中文](glossary.zh.md)
 
 Domain vocabulary for the DeepSeek Harness SDK uses one canonical term per concept. Terms link to their entries with standard Markdown anchors; implementation detail stays in package READMEs and Agent Notes.
 
+## capability-seam
+
+- **seam** — a *swappable capability* packaged as a trio: a **Service Definition** (the Cordis `Service` that owns its `ctx.<key>` and vocabulary types — an abstract class such as `BashExecutor`, or a concrete registry such as `WebService`, never a TypeScript `interface`), one or more **Service providers** (the implementation plugins that register a backend), and a **Consumer** (the model- or plugin-facing surface that injects the service). `packages/bash` is the canonical example: `dsh-bash` (Service Definition), `dsh-bash-local` / `dsh-bash-sandbox` (providers), `dsh-tool-bash` (consumer). The seam is all three together; the interface package alone is the *Service Definition*, one member — calling it "the seam" is the misuse this entry names. Fold roles only when they are genuinely one concern (`dsh-llm` folds the Service Definition and consumer); never split preemptively.
+
 ## agent-scope
 
 - **scope** — the unit of per-agent registration: a contribution (tool, prompt section, variable, restriction, listener) is either *global* (visible to every agent) or *scoped* (owned by exactly one [scope key](#scope-key)). Two levels, flat: scoped registrations do not inherit down to subagents; subtree behavior is expressed with [lineage](#lineage) data, never scope structure.
diff --git a/docs/glossary.zh.md b/docs/glossary.zh.md
index a84447dd06..ddf76edb1f 100644
--- a/docs/glossary.zh.md
+++ b/docs/glossary.zh.md
@@ -4,6 +4,10 @@
 
 DeepSeek Harness SDK 的领域词汇为每个概念规定一个规范术语。各术语通过标准 Markdown 锚点链接到相应条目；实现细节留在各包的 README 与 Agent Note 中。
 
+## capability-seam
+
+- **seam**：一种*可替换能力*，以三者组合的形式打包：**Service Definition**（拥有自身 `ctx.<key>` 和词汇类型的 Cordis `Service`——可以是 `BashExecutor` 这样的抽象类，也可以是 `WebService` 这样的具体注册表，从不是 TypeScript `interface`）、一个或多个 **Service provider**（注册后端的实现插件）以及 **Consumer**（注入该服务、面向模型或插件的表面）。`packages/bash` 是规范范例：`dsh-bash`（Service Definition）、`dsh-bash-local` / `dsh-bash-sandbox`（提供方）、`dsh-tool-bash`（消费方）。seam 是三者整体；接口包本身只是 *Service Definition*，是其中一个成员——把它称为「seam」正是本条目指出的误用。只有在角色确实属于同一个关注点时才合并角色（`dsh-llm` 合并 Service Definition 和消费方）；永远不要预防性地拆分。
+
 ## agent-scope
 
 - **scope**：按 agent（智能体）划分的注册单位。一项贡献（工具、提示词片段、变量、限制、监听器）要么是*全局的*（对所有 agent 可见），要么是*带作用域的*（归属于恰好一个 [scope key](#scope-key)）。只有两层，采用扁平结构：带作用域的注册不会向下继承给 subagent；子树行为通过 [lineage](#lineage) 数据表达，从不通过 scope 结构。
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index a089e2a1f0..4e49ef9694 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -55,7 +55,7 @@
 | Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |
 | schema | schema | | | |
 | schema DSL | schema DSL | | | |
-| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |
+| seam | seam | | 接缝 | 一个可替换能力的三包整体（Service Definition / Service provider 实现 / Consumer），以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface，且不能单独称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |
 | skill | skill | skill（技能） | | |
 | slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |
 | spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index 6f035bdbd5..077edaa10e 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.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 docs/subsystems/bash.md
-bash.md: dd7649ce46bea5642270fa553eb3d82f2dc33e9b
-bash.zh.md: e3c607cb1599da97cb69369a34135abc310387ed
+bash.md: 232443daf944237e0c9f8904a0ebeeab3d2de749
+bash.zh.md: aaabc8fb1de654096e01fcee1ad1d0f881d534e8
diff --git a/docs/subsystems/bash.md b/docs/subsystems/bash.md
index dd7649ce46..232443daf9 100644
--- a/docs/subsystems/bash.md
+++ b/docs/subsystems/bash.md
@@ -228,9 +228,9 @@ interface BashProcessRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxbash--bashexecutor-abstract-seam"></a>
+<a id="ctxbash--bashexecutor"></a>
 
-### `ctx.bash` — `BashExecutor` (abstract seam)
+### `ctx.bash` — `BashExecutor`
 
 Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index e3c607cb15..aaabc8fb1d 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -228,9 +228,9 @@ interface BashProcessRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxbash--bashexecutor-abstract-seam"></a>
+<a id="ctxbash--bashexecutor"></a>
 
-### `ctx.bash` — `BashExecutor` (abstract seam)
+### `ctx.bash` — `BashExecutor`
 
 Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index 3caad2c5f7..5c6c47580d 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.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 docs/subsystems/code-runtime.md
-code-runtime.md: 12779f1aafc8930410ae0d695e3f617caafcf607
-code-runtime.zh.md: 0bb18aaafff5a9b390685ee4c93a67f3f15502d5
+code-runtime.md: 7185e99042101b2c3707f3d0ed80ae6c1f1f58f0
+code-runtime.zh.md: 2b5ebea4e0e43cebd695c20d59fa6e705e4ebcf2
diff --git a/docs/subsystems/code-runtime.md b/docs/subsystems/code-runtime.md
index 12779f1aaf..7185e99042 100644
--- a/docs/subsystems/code-runtime.md
+++ b/docs/subsystems/code-runtime.md
@@ -168,9 +168,9 @@ interface CodeRunFailure {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
+<a id="ctxcoderuntime--coderuntime"></a>
 
-### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
+### `ctx.codeRuntime` — `CodeRuntime`
 
 Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
 
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index 0bb18aaaff..2b5ebea4e0 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -168,9 +168,9 @@ interface CodeRunFailure {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
+<a id="ctxcoderuntime--coderuntime"></a>
 
-### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
+### `ctx.codeRuntime` — `CodeRuntime`
 
 Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
 
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 425f48409a..384a29469b 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 058fdba7969ac1f5b337b7ff008b0e62cf9ed035
-compaction.zh.md: b4108ed5de55e027d633a180db968c7cd7ffee59
+compaction.md: 47d115710a66bf1501e61806cbc68febbe4667ca
+compaction.zh.md: a89b218f16a44dbd184340631fa4f468f15f48f5
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 058fdba796..47d115710a 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -121,9 +121,9 @@ interface PruneResult {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcompact--compactservice-abstract-seam"></a>
+<a id="ctxcompact--compactservice"></a>
 
-### `ctx.compact` — `CompactService` (abstract seam)
+### `ctx.compact` — `CompactService`
 
 Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index b4108ed5de..a89b218f16 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -121,9 +121,9 @@ interface PruneResult {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcompact--compactservice-abstract-seam"></a>
+<a id="ctxcompact--compactservice"></a>
 
-### `ctx.compact` — `CompactService` (abstract seam)
+### `ctx.compact` — `CompactService`
 
 Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
 
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index 7e9e057c75..2ea649fe56 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: 0bc2224ac039addc795d3806e8c85004f2bb84a7
-credentials.zh.md: f236b0b2daef85784308f10dbcfc67db84c42234
+credentials.md: 84b156e366b2f4d0aeaba11b1b8d005ff59ad11d
+credentials.zh.md: c12191529e4324aed57b0ec8870fdca5c4dcae8a
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index 0bc2224ac0..84b156e366 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -57,9 +57,9 @@ interface CredentialInfo {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcredentials--credentials-abstract-seam"></a>
+<a id="ctxcredentials--credentials"></a>
 
-### `ctx.credentials` — `Credentials` (abstract seam)
+### `ctx.credentials` — `Credentials`
 
 Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
 
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index f236b0b2da..c12191529e 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -57,9 +57,9 @@ interface CredentialInfo {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcredentials--credentials-abstract-seam"></a>
+<a id="ctxcredentials--credentials"></a>
 
-### `ctx.credentials` — `Credentials` (abstract seam)
+### `ctx.credentials` — `Credentials`
 
 Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
 
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index e57b2aef45..3b5987bfec 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 591f1b4d4b1177ccbe7c2280d2054da5d4be8b99
-filesystem.zh.md: d599e48c1fba2d564a544f628ca3475b781e5cd5
+filesystem.md: 6c89f6f88babf09b1cf0f6ac2b739b511568f18b
+filesystem.zh.md: 16be774c74d02894434467dc68e927fdba2e38c7
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 591f1b4d4b..6c89f6f88b 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -262,7 +262,7 @@ type FsErrorCode =
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem) below shows the exact signatures.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -272,9 +272,9 @@ type FsErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxfs--filesystem-abstract-seam"></a>
+<a id="ctxfs--filesystem"></a>
 
-### `ctx.fs` — `FileSystem` (abstract seam)
+### `ctx.fs` — `FileSystem`
 
 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index d599e48c1f..16be774c74 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -262,7 +262,7 @@ type FsErrorCode =
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem) 展示确切的 `ctx.fs` 签名。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -272,9 +272,9 @@ type FsErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxfs--filesystem-abstract-seam"></a>
+<a id="ctxfs--filesystem"></a>
 
-### `ctx.fs` — `FileSystem` (abstract seam)
+### `ctx.fs` — `FileSystem`
 
 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
 
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index ae2ef3a216..1ee31d85d0 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: 580ec250ebad3f2b51982f98a611268f26487321
-persistence.zh.md: 8785ca9c7dad562e6b27261920ab48c72c607121
+persistence.md: c8d8bba1650dd54b533e95a4ddd0a8f5a19bb0c6
+persistence.zh.md: b4440183bc56086739ac1e9fa6390e9287335986
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index 580ec250eb..c8d8bba165 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -200,7 +200,7 @@ interface SessionPersistenceSnapshot {
 
 ## The backends
 
-Both implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass `runPersistenceContract`, proving the seam is genuinely backend-agnostic:
+Both implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass `runPersistenceContract`:
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)** — `node:sqlite`, one row per `SessionEvent`. The row shape `(session_id, seq, type, time, data, source_event_seqs, surface_op)` maps 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
@@ -213,9 +213,9 @@ Both implement the same abstract `SessionPersistence` (locate/create/append/prep
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
+<a id="ctxsessionpersistence--sessionpersistence"></a>
 
-### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
+### `ctx.sessionPersistence` — `SessionPersistence`
 
 Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
 
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 8785ca9c7d..b4440183bc 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -200,7 +200,7 @@ interface SessionPersistenceSnapshot {
 
 ## 后端
 
-两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过 `runPersistenceContract`，证明该 seam 确实与后端无关：
+两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过 `runPersistenceContract`：
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行结构 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。
@@ -213,9 +213,9 @@ interface SessionPersistenceSnapshot {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
+<a id="ctxsessionpersistence--sessionpersistence"></a>
 
-### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
+### `ctx.sessionPersistence` — `SessionPersistence`
 
 Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
 
diff --git a/docs/subsystems/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
index a6f8fd2609..ab7bbb6b07 100644
--- a/docs/subsystems/sandbox.i18n.yaml
+++ b/docs/subsystems/sandbox.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 docs/subsystems/sandbox.md
-sandbox.md: dd960b3021dcdc87cfd36fd439cbec0a810dd736
-sandbox.zh.md: 23644bb43a131a0e3c8595187a6fc11e74682d9e
+sandbox.md: b08eacbc040568fa40c681f65577b64afe53fbaa
+sandbox.zh.md: 1e5f7f55b4923f96ffb9263e9d0784f849fd4d13
diff --git a/docs/subsystems/sandbox.md b/docs/subsystems/sandbox.md
index dd960b3021..b08eacbc04 100644
--- a/docs/subsystems/sandbox.md
+++ b/docs/subsystems/sandbox.md
@@ -155,9 +155,9 @@ Provider selection, probing, caching, and backend-specific enforcement reports b
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
+<a id="ctxsandbox--sandboxprovider"></a>
 
-### `ctx.sandbox` — `SandboxProvider` (abstract seam)
+### `ctx.sandbox` — `SandboxProvider`
 
 Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
 
diff --git a/docs/subsystems/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
index 23644bb43a..1e5f7f55b4 100644
--- a/docs/subsystems/sandbox.zh.md
+++ b/docs/subsystems/sandbox.zh.md
@@ -155,9 +155,9 @@ interface ConfinedArgv {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
+<a id="ctxsandbox--sandboxprovider"></a>
 
-### `ctx.sandbox` — `SandboxProvider` (abstract seam)
+### `ctx.sandbox` — `SandboxProvider`
 
 Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
 
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index 02a3502a1a..02734a5cdc 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.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 docs/subsystems/session-query.md
-session-query.md: 9e907b2ebf12c01620921c7955f25d2fdd6ce4fb
-session-query.zh.md: 4452330ebd5e487387c0ad15bea45b76d9c643be
+session-query.md: e62cd1c6ff744e7ccdc6f26f5ad76a6512a205bf
+session-query.zh.md: 7bd2b55509e4c5bb971a44680d0d7576c5d10146
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index 9e907b2ebf..e62cd1c6ff 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -363,9 +363,9 @@ type SessionQueryErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
+<a id="ctxsessionquery--sessionqueryservice"></a>
 
-### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
+### `ctx.sessionQuery` — `SessionQueryService`
 
 Unified live-preferred session query service.
 
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index 4452330ebd..7bd2b55509 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -363,9 +363,9 @@ type SessionQueryErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
+<a id="ctxsessionquery--sessionqueryservice"></a>
 
-### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
+### `ctx.sessionQuery` — `SessionQueryService`
 
 Unified live-preferred session query service.
 
diff --git a/docs/subsystems/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
index a257e0e33e..e541d20f69 100644
--- a/docs/subsystems/settings.i18n.yaml
+++ b/docs/subsystems/settings.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 docs/subsystems/settings.md
-settings.md: 9256bf9436d2e77093fc8c6a3728b62fc4e8d67f
-settings.zh.md: 720eb9c2718c1fa14a148cced806c224634dba69
+settings.md: c15b11c8635def88aba49b6df66aa56a22fbe0ae
+settings.zh.md: 7f588ededd0ad2eb058995d4d54fe71c8b6bc67a
diff --git a/docs/subsystems/settings.md b/docs/subsystems/settings.md
index 9256bf9436..c15b11c863 100644
--- a/docs/subsystems/settings.md
+++ b/docs/subsystems/settings.md
@@ -169,9 +169,9 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsettings--settings-abstract-seam"></a>
+<a id="ctxsettings--settings"></a>
 
-### `ctx.settings` — `Settings` (abstract seam)
+### `ctx.settings` — `Settings`
 
 Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
 
diff --git a/docs/subsystems/settings.zh.md b/docs/subsystems/settings.zh.md
index 720eb9c271..7f588ededd 100644
--- a/docs/subsystems/settings.zh.md
+++ b/docs/subsystems/settings.zh.md
@@ -169,9 +169,9 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsettings--settings-abstract-seam"></a>
+<a id="ctxsettings--settings"></a>
 
-### `ctx.settings` — `Settings` (abstract seam)
+### `ctx.settings` — `Settings`
 
 Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
 
diff --git a/docs/subsystems/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
index 1e9547cc28..c0e9f9f50d 100644
--- a/docs/subsystems/spill.i18n.yaml
+++ b/docs/subsystems/spill.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 docs/subsystems/spill.md
-spill.md: a0a476761ab0633227d7c87033daee79f649bf50
-spill.zh.md: 65d7e4cb89a93e2e709af0a620f523aad2315ed2
+spill.md: 4998ac62d1cd4e86a6e92ec5a0c85955b137f4be
+spill.zh.md: 0495c6fbcdb5c909a142539f69d5dd2bd551413c
diff --git a/docs/subsystems/spill.md b/docs/subsystems/spill.md
index a0a476761a..4998ac62d1 100644
--- a/docs/subsystems/spill.md
+++ b/docs/subsystems/spill.md
@@ -92,9 +92,9 @@ The local backend ([dsh-spill-local](../../packages/spill/spill-local)) writes u
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxspillstore--spillstore-abstract-seam"></a>
+<a id="ctxspillstore--spillstore"></a>
 
-### `ctx.spillStore` — `SpillStore` (abstract seam)
+### `ctx.spillStore` — `SpillStore`
 
 Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/spill.zh.md b/docs/subsystems/spill.zh.md
index 65d7e4cb89..0495c6fbcd 100644
--- a/docs/subsystems/spill.zh.md
+++ b/docs/subsystems/spill.zh.md
@@ -92,9 +92,9 @@ type SpillLocator = Branded<'SpillLocator'>
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxspillstore--spillstore-abstract-seam"></a>
+<a id="ctxspillstore--spillstore"></a>
 
-### `ctx.spillStore` — `SpillStore` (abstract seam)
+### `ctx.spillStore` — `SpillStore`
 
 Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index 4c63f77618..0af3183692 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.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 docs/subsystems/subprocess.md
-subprocess.md: 0bc2bf86518bcc60bef02554b94471425f2ac433
-subprocess.zh.md: 7e27bf15dfe0cdde09459dbfb239ab25ccde126a
+subprocess.md: b501af81dca94025713d46a23a67b543f5df95cd
+subprocess.zh.md: 84b497c90bb5956b0dcb65ca1cb72122b415bd7e
diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md
index 0bc2bf8651..b501af81dc 100644
--- a/docs/subsystems/subprocess.md
+++ b/docs/subsystems/subprocess.md
@@ -242,7 +242,7 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches quiescence for every session member the provider can still observe; providers document substrate-specific observability limits. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
 
-The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessservice-abstract-seam).
+The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessservice).
 
 ## Service behavior
 
@@ -273,9 +273,9 @@ async getSandbox(): Promise<Sandbox>
 
 Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
 
-<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
+<a id="ctxsubprocess--subprocessservice"></a>
 
-### `ctx.subprocess` — `SubprocessService` (abstract seam)
+### `ctx.subprocess` — `SubprocessService`
 
 Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index 7e27bf15df..84b497c90b 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -242,7 +242,7 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，提供方则会记录执行基底特有的可观察性限制。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
 
-终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessservice-abstract-seam)中。
+终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessservice)中。
 
 ## 服务行为
 
@@ -273,9 +273,9 @@ async getSandbox(): Promise<Sandbox>
 
 Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
 
-<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
+<a id="ctxsubprocess--subprocessservice"></a>
 
-### `ctx.subprocess` — `SubprocessService` (abstract seam)
+### `ctx.subprocess` — `SubprocessService`
 
 Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
index d1110928e7..6f9d3c6861 100644
--- a/docs/subsystems/tasks.i18n.yaml
+++ b/docs/subsystems/tasks.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 docs/subsystems/tasks.md
-tasks.md: 6237607307cbab8511f968ed591e3e3b8b845c6a
-tasks.zh.md: c73765b4d5ad0309f3473890557171af21527682
+tasks.md: f042dfec7438bd2e385cc8c225a3faa171b9ca4f
+tasks.zh.md: bf660a9606f0bc9081532c970e88f249ea0ec4ae
diff --git a/docs/subsystems/tasks.md b/docs/subsystems/tasks.md
index 6237607307..f042dfec74 100644
--- a/docs/subsystems/tasks.md
+++ b/docs/subsystems/tasks.md
@@ -161,9 +161,9 @@ The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam defin
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtasks--taskservice-abstract-seam"></a>
+<a id="ctxtasks--taskservice"></a>
 
-### `ctx.tasks` — `TaskService` (abstract seam)
+### `ctx.tasks` — `TaskService`
 
 Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/tasks.zh.md b/docs/subsystems/tasks.zh.md
index c73765b4d5..bf660a9606 100644
--- a/docs/subsystems/tasks.zh.md
+++ b/docs/subsystems/tasks.zh.md
@@ -161,9 +161,9 @@ interface TaskRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtasks--taskservice-abstract-seam"></a>
+<a id="ctxtasks--taskservice"></a>
 
-### `ctx.tasks` — `TaskService` (abstract seam)
+### `ctx.tasks` — `TaskService`
 
 Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index d520d56dcf..b53153692f 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: 131c5814f29d70c356989e62fda1db5c1c5448d6
-telemetry.zh.md: 147418000f240093f356fe9033612967f8e29ffb
+telemetry.md: c9afd276f7c4183db0d1accea2b9aafe71a0e5cc
+telemetry.zh.md: e7ea255a50cace18c7d59b2c77c96bc426d5ee0c
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index 131c5814f2..c9afd276f7 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -105,7 +105,7 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry` (`ctx.telemetry`, [signatures](#ctxtelemetry--telemetry-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
+`Telemetry` (`ctx.telemetry`, [signatures](#ctxtelemetry--telemetry)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
 
 ## The redact waterfall: `telemetry/record`
 
@@ -119,9 +119,9 @@ Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordi
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtelemetry--telemetry-abstract-seam"></a>
+<a id="ctxtelemetry--telemetry"></a>
 
-### `ctx.telemetry` — `Telemetry` (abstract seam)
+### `ctx.telemetry` — `Telemetry`
 
 The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
 
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 147418000f..e7ea255a50 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -105,7 +105,7 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry-abstract-seam)）是该约定的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
+`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
 
 ## 脱敏 waterfall：`telemetry/record`
 
@@ -119,9 +119,9 @@ interface TelemetryBackend {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtelemetry--telemetry-abstract-seam"></a>
+<a id="ctxtelemetry--telemetry"></a>
 
-### `ctx.telemetry` — `Telemetry` (abstract seam)
+### `ctx.telemetry` — `Telemetry`
 
 The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
 
diff --git a/docs/subsystems/workflow.i18n.yaml b/docs/subsystems/workflow.i18n.yaml
index 4f581d8bae..fed94d62bc 100644
--- a/docs/subsystems/workflow.i18n.yaml
+++ b/docs/subsystems/workflow.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 docs/subsystems/workflow.md
-workflow.md: 53cb8be2c975fba396c3d2023c60fc1da2ed9c8a
-workflow.zh.md: 652b68c833f7f20fe72307946d02f89558be2c2b
+workflow.md: c87e88f1e1dddcd57822e47e5773dba127f9cdcf
+workflow.zh.md: 57d69ffd5300a6b4d6e037758a75c19e9ccd51a7
diff --git a/docs/subsystems/workflow.md b/docs/subsystems/workflow.md
index 53cb8be2c9..c87e88f1e1 100644
--- a/docs/subsystems/workflow.md
+++ b/docs/subsystems/workflow.md
@@ -139,9 +139,9 @@ The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `wo
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxworkflows--workflowservice-abstract-seam"></a>
+<a id="ctxworkflows--workflowservice"></a>
 
-### `ctx.workflows` — `WorkflowService` (abstract seam)
+### `ctx.workflows` — `WorkflowService`
 
 Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
 
diff --git a/docs/subsystems/workflow.zh.md b/docs/subsystems/workflow.zh.md
index 652b68c833..57d69ffd53 100644
--- a/docs/subsystems/workflow.zh.md
+++ b/docs/subsystems/workflow.zh.md
@@ -139,9 +139,9 @@ interface WorkflowRun {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxworkflows--workflowservice-abstract-seam"></a>
+<a id="ctxworkflows--workflowservice"></a>
 
-### `ctx.workflows` — `WorkflowService` (abstract seam)
+### `ctx.workflows` — `WorkflowService`
 
 Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
 
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index b2c2248876..1b94464e30 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
-workspace.md: ca088a2091a7f47a3d52992fec13fae44061a608
-workspace.zh.md: e414c759a043f934e1a8b5d89c7a3b6101bbb6f4
+workspace.md: 21b08bd8b0936e9c7357ad15e7ff4176a981a042
+workspace.zh.md: 30bfc0054880ca82b5f7c64780d405524656a1f1
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index ca088a2091..21b08bd8b0 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -133,9 +133,9 @@ Sessions get their cwd at create time from whoever creates them, not from this r
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
+<a id="ctxdirectorypicker--directorypicker"></a>
 
-### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
+### `ctx.directoryPicker` — `DirectoryPicker`
 
 Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
 
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index e414c759a0..30bfc00548 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -133,9 +133,9 @@ interface Workspace {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
+<a id="ctxdirectorypicker--directorypicker"></a>
 
-### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
+### `ctx.directoryPicker` — `DirectoryPicker`
 
 Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
 
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index 169a45d5cd..72bd7650be 100644
--- a/packages/bash/bash/README.i18n.yaml
+++ b/packages/bash/bash/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/bash/bash/README.md
-README.md: 690f4e61740faf2648ecbc7f5995ec0fdaa64aee
-README.zh.md: f8bcfce06a406eb94a2486e9825f2beb11b8fd5e
+README.md: e142a796e94dab4ecaa67b8dfce0be4f554f26c0
+README.zh.md: 24a44b418a675d863551642f2edb1f655a2705ab
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index 690f4e6174..e142a796e9 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **bash executor seam**: an abstract `BashExecutor` service (`ctx.bash`) defining WHAT a bash backend does — run foreground commands and start background processes — without saying HOW. Task ids, ownership, collection, cancellation, and notices belong to the generic `ctx.tasks` runtime.
+The **`BashExecutor`** (`ctx.bash`) defines WHAT a bash backend does — run foreground commands and start background processes — without saying HOW. Task ids, ownership, collection, cancellation, and notices belong to the generic `ctx.tasks` runtime.
 
 This package is the interface quarter of the bash capability, split so each concern can evolve (and be swapped) independently:
 
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index f8bcfce06a..24a44b418a 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**bash 执行器 seam**：抽象 `BashExecutor` 服务（`ctx.bash`）定义 bash 后端做什么，即运行前台命令与启动后台进程，但不规定如何实现。task id、所有权、收集、取消与通知属于通用 `ctx.tasks` 运行时。
+**`BashExecutor`**（`ctx.bash`）定义 bash 后端做什么，即运行前台命令与启动后台进程，但不规定如何实现。task id、所有权、收集、取消与通知属于通用 `ctx.tasks` 运行时。
 
 本包是 bash 能力中负责接口的四分之一，各项职责因此可以独立演进（和替换）：
 
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index 99d66e084f..0a72d1608c 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/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/code-runtime/code-runtime/README.md
-README.md: bb1c20d00a260f643f601c42c6e48722437d5aab
-README.zh.md: 2a68e6f05d12b737bdff530a351aa038628d85fc
+README.md: 637cc6adae3372ea60ca003f74af416513484270
+README.zh.md: fcc4c7323dd547c2421bb1e5a009481bf78cfc70
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index bb1c20d00a..637cc6adae 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **code-execution seam**: an abstract `CodeRuntime` service (`ctx.codeRuntime`) defining WHAT a code runtime does — run one model-written program against a set of host-provided async bindings and report `{ value, logs, error? }` — without saying HOW.
+The **`CodeRuntime`** (`ctx.codeRuntime`) defines WHAT a code runtime does — run one model-written program against a set of host-provided async bindings and report `{ value, logs, error? }` — without saying HOW.
 
 This package is the interface third of the capability (the bash trio is the template — see [capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): implementations subclass `CodeRuntime` and register the service; the consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md), whose first implementation is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the consumer.
 
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index 2a68e6f05d..fcc4c7323d 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这是**代码执行 seam**：抽象的 `CodeRuntime` 服务（`ctx.codeRuntime`）只定义代码运行时做什么，即针对宿主提供的一组异步绑定运行一段模型编写的程序，并报告 `{ value, logs, error? }`，而不规定如何实现。
+**`CodeRuntime`**（`ctx.codeRuntime`）定义代码运行时做什么，即针对宿主提供的一组异步绑定运行一段模型编写的程序，并报告 `{ value, logs, error? }`，而不规定如何实现。
 
 此包承担该能力三个组成部分中的接口职责（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。这两项职责均由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有与工具有关的内容都留在消费方。
 
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index c5045934c9..dae5564742 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: c32be20117abfe15e278082089c5fd87828c81ef
-README.zh.md: 530b1ca30061956fbe37a4b4b90fed99c02e5a7f
+README.md: c7fdbef33b2e65089a0f0112e19122db4f26bb77
+README.zh.md: 493d269202b3a5b89cd600391e7144219ed2bf12
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index c32be20117..c7fdbef33b 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **compaction seam**: an abstract `CompactService` (`ctx.compact`) defining WHAT compaction does — decide when history is too large and summarize an older range into a single surface node — without saying HOW.
+The **`CompactService`** (`ctx.compact`) defines WHAT compaction does — decide when history is too large and summarize an older range into a single surface node — without saying HOW.
 
 This package is the interface tier of the compaction capability, split so each concern evolves (and swaps) independently:
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index 530b1ca300..493d269202 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**压缩（compaction） seam**：抽象 `CompactService`（`ctx.compact`）定义压缩做什么，即判定历史记录是否过大，并将较早范围摘要为单个表层节点，但不规定如何实现。
+**`CompactService`**（`ctx.compact`）定义压缩做什么，即判定历史记录是否过大，并将较早范围摘要为单个表层节点，但不规定如何实现。
 
 这个包是压缩能力的接口层，因此各项职责均可独立演进，也可独立替换：
 
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index e0095d9858..5ed8633331 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: 5c58fc476b9b11a83bbe0d6c33ac782d94d6ffbc
-README.zh.md: 8eb2634df2754cdcada4e48046e19eb32b1cf3af
+README.md: 11134e6298e6c87d1046952c65bb2dadff43e4a2
+README.zh.md: 7edece618150739d5ff67c605788dae42a5a5c32
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index 5c58fc476b..11134e6298 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read whole or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
+The **`FileSystem`** (`ctx.fs`) defines the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read whole or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
 This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
 
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 8eb2634df2..7edece6181 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
+**`FileSystem`**（`ctx.fs`）定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
 
 本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
 
diff --git a/packages/spill/spill/README.i18n.yaml b/packages/spill/spill/README.i18n.yaml
index 110d814fe2..cddfc91ea7 100644
--- a/packages/spill/spill/README.i18n.yaml
+++ b/packages/spill/spill/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/spill/spill/README.md
-README.md: d3cce987f80c0db5165718b7cc4fd6ada92f2a02
-README.zh.md: 37d6587d08d96c55a36c9b7388f2ae418531a6cd
+README.md: ecaef9fc53ec3d9017143cfc012abc9cabe77072
+README.zh.md: 5393ccb312245f3bbfcf28ea8e097b0a343966e9
diff --git a/packages/spill/spill/README.md b/packages/spill/spill/README.md
index d3cce987f8..ecaef9fc53 100644
--- a/packages/spill/spill/README.md
+++ b/packages/spill/spill/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **spill storage seam**: an abstract `SpillStore` service (`ctx.spillStore`) defining WHAT a spill backend does — persist a tool's oversized text and return a model-facing locator plus retrieval guidance — without saying HOW.
+The **`SpillStore`** (`ctx.spillStore`) defines WHAT a spill backend does — persist a tool's oversized text and return a model-facing locator plus retrieval guidance — without saying HOW.
 
 This package is one third of the spill capability, split so each concern evolves (and swaps) independently:
 
diff --git a/packages/spill/spill/README.zh.md b/packages/spill/spill/README.zh.md
index 37d6587d08..5393ccb312 100644
--- a/packages/spill/spill/README.zh.md
+++ b/packages/spill/spill/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**spill 存储 seam**：抽象的 `SpillStore` 服务（`ctx.spillStore`）定义 spill 后端做什么，即持久化某个工具过大的文本，并返回面向模型的定位信息与取回指引；它不规定如何实现。
+**`SpillStore`**（`ctx.spillStore`）定义 spill 后端做什么，即持久化某个工具过大的文本，并返回面向模型的定位信息与取回指引；它不规定如何实现。
 
 该包是 spill 能力的三个组成部分之一。拆分后，各项关注点可独立演进和替换：
 
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index 1950c255cb..553ab75490 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -84,8 +84,6 @@ export interface ServiceEntry {
   key: string
   /** The service class/interface name, e.g. `LlmService`. */
   type: string
-  /** Whether the service class is abstract (a seam interface). */
-  abstract: boolean
   /** Class-level JSDoc prose, one line per paragraph. */
   doc: string
   /** Public methods (bodies stripped), in source order. */
@@ -258,7 +256,6 @@ export class CordisCatalogProjector {
         entries.push({
           key: service.key,
           type: declaration.name,
-          abstract: declaration.abstract,
           doc,
           methods,
           source,
@@ -747,8 +744,7 @@ function renderEvent(e: EventEntry, onPage: string, linkedTypePages: Readonly<Re
 
 /** Render one harness service entry onto its owning page. */
 function renderService(s: ServiceEntry, onPage: string, linkedTypePages: Readonly<Record<string, string>>): string[] {
-  const kind = s.abstract ? ' (abstract seam)' : ''
-  const out = [...anchorFor(`ctx.${s.key} — ${s.type}${kind}`), `### \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
+  const out = [...anchorFor(`ctx.${s.key} — ${s.type}`), `### \`ctx.${s.key}\` — \`${s.type}\``, '']
   if (s.doc) out.push(s.doc, '')
   if (s.methods.length) {
     const declarations = s.methods.flatMap((method, index) => [
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index bde52505dc..a6b68a4ee7 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -259,7 +259,7 @@ export class FixService {
   it('extracts a well-formed service with its methods and class JSDoc', () => {
     const services = collectServices(makeService(WELL_FORMED))
     expect(services).toHaveLength(1)
-    expect(services[0]).toMatchObject({ key: 'fix', type: 'FixService', abstract: false, doc: 'Fixture service.' })
+    expect(services[0]).toMatchObject({ key: 'fix', type: 'FixService', doc: 'Fixture service.' })
     expect(services[0]?.methods).toHaveLength(3)
     expect(services[0]?.methods[0]).toEqual({
       signature: 'run(id: string): string',
diff --git a/packages/web/web/README.i18n.yaml b/packages/web/web/README.i18n.yaml
index b6c139d63c..5adff6e81c 100644
--- a/packages/web/web/README.i18n.yaml
+++ b/packages/web/web/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/web/web/README.md
-README.md: 73765fe060cc0a2b0fa3d69703a670f488a29ac9
-README.zh.md: bebdb52d6c9bd33db5a982c1f278e71c1882f2de
+README.md: c05965478a049b4145a94075e42bd9602675628f
+README.zh.md: 686157cc87ff456ccc535e3f92fd6524758b35f4
diff --git a/packages/web/web/README.md b/packages/web/web/README.md
index 73765fe060..c05965478a 100644
--- a/packages/web/web/README.md
+++ b/packages/web/web/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **web access seam**: an abstract `WebService` (`ctx.web`) defining WHAT web access the harness has — search the web, fetch a URL — over multiple providers, without binding the model contract to one vendor's API shape.
+The **`WebService`** (`ctx.web`) defines WHAT web access the harness has — search the web, fetch a URL — over multiple providers, without binding the model contract to one vendor's API shape.
 
 This package is the interface third of the web capability. Unlike bash/fs it spans two capabilities (search and fetch) on one seam, with potentially multiple providers each:
 
diff --git a/packages/web/web/README.zh.md b/packages/web/web/README.zh.md
index bebdb52d6c..686157cc87 100644
--- a/packages/web/web/README.zh.md
+++ b/packages/web/web/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**web 访问 seam**：抽象 `WebService`（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型约定绑定到某个厂商的 API 形状。
+**`WebService`**（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型契约绑定到某个厂商的 API 形状。
 
 该包是 web 能力中负责接口的三分之一。与 bash/fs 不同，它在一个 seam 上跨越搜索与抓取两种能力，每种能力都可能有多个提供方：
 
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index cbdd3d758e..38cc7950ec 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 本仓库的命名架构概念，正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 一个可替换能力的三包整体（Service Definition / Service provider 实现 / Consumer），以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface，且不能单独称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",

From 95eb4bcf40e62a5f22434fe9feaa2ba6f1b0845d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:20:58 +0800
Subject: [PATCH 477/516] test(windows): vary HMR polling writes

---
 packages/boot/app-boot/tests/hmr-config.spec.ts | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index dbb3a8ca83..d21e222104 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -48,9 +48,13 @@ describe('HMR exact config paths', () => {
     try {
       const deadline = Date.now() + 20_000
       for (let generation = 1; !observed.includes(expected); generation += 1) {
-        if (Date.now() >= deadline) throw new Error('HMR did not observe a module change through the alias')
+        if (Date.now() >= deadline) {
+          throw new Error(`HMR did not observe ${expected} through the alias; observed ${JSON.stringify(observed)}`)
+        }
         // The watch base, not the writer spelling, is the alias under test.
-        writeFileSync(filename, `export const generation = ${generation}\n`)
+        // Grow the file on every write: polling must not depend on timestamp
+        // precision when several generations land inside one filesystem tick.
+        writeFileSync(filename, `export const generation = ${generation}\n${' '.repeat(generation)}\n`)
         // Leave Chokidar's atomic-write window idle so one coalesced change can publish.
         await new Promise(resolve => setTimeout(resolve, 250))
       }

From dda02250f52a4e85052a7c6bbed245d7d8509309 Mon Sep 17 00:00:00 2001
From: Turtle <turtle1999@deepseek.com>
Date: Sun, 9 Aug 2026 15:34:32 +0800
Subject: [PATCH 478/516] docs: reserve seam for complete capabilities

---
 ...ev-invariants-over-deep-readonly.i18n.yaml |  4 +-
 ...06-11-dev-invariants-over-deep-readonly.md |  2 +-
 ...11-dev-invariants-over-deep-readonly.zh.md |  2 +-
 ...06-11-microkernel-event-taxonomy.i18n.yaml |  4 +-
 .../2026-06-11-microkernel-event-taxonomy.md  |  6 +--
 ...026-06-11-microkernel-event-taxonomy.zh.md |  6 +--
 .../2026-06-13-capability-seams.i18n.yaml     |  4 +-
 .../2026-06-13-capability-seams.md            | 22 ++++-----
 .../2026-06-13-capability-seams.zh.md         | 22 ++++-----
 .../2026-06-14-session-persistence.i18n.yaml  |  4 +-
 .../2026-06-14-session-persistence.md         |  6 +--
 .../2026-06-14-session-persistence.zh.md      | 12 ++---
 ...06-17-filesystem-capability-seam.i18n.yaml |  4 +-
 .../2026-06-17-filesystem-capability-seam.md  | 14 +++---
 ...026-06-17-filesystem-capability-seam.zh.md | 14 +++---
 ...fecycle-and-ownership-contracts.i18n.yaml} |  6 +--
 ...gent-lifecycle-and-ownership-contracts.md} | 16 +++----
 ...t-lifecycle-and-ownership-contracts.zh.md} | 16 +++----
 ...ed-persistence-write-coordinator.i18n.yaml |  4 +-
 ...18-shared-persistence-write-coordinator.md |  2 +-
 ...shared-persistence-write-coordinator.zh.md |  6 +--
 .../2026-06-20-branded-ids.i18n.yaml          |  4 +-
 .../architecture/2026-06-20-branded-ids.md    | 12 ++---
 .../architecture/2026-06-20-branded-ids.zh.md | 12 ++---
 ...eneric-long-running-tool-runtime.i18n.yaml |  4 +-
 ...06-20-generic-long-running-tool-runtime.md |  6 +--
 ...20-generic-long-running-tool-runtime.zh.md |  6 +--
 ...-21-bounded-llm-request-recovery.i18n.yaml |  4 +-
 ...2026-06-21-bounded-llm-request-recovery.md |  8 ++--
 ...6-06-21-bounded-llm-request-recovery.zh.md |  8 ++--
 ...andatory-app-attribution-headers.i18n.yaml |  4 +-
 ...06-21-mandatory-app-attribution-headers.md |  4 +-
 ...21-mandatory-app-attribution-headers.zh.md |  4 +-
 .../2026-06-24-web-capability-seam.i18n.yaml  |  4 +-
 .../2026-06-24-web-capability-seam.md         |  8 ++--
 .../2026-06-24-web-capability-seam.zh.md      |  8 ++--
 ...06-26-file-context-as-event-gate.i18n.yaml |  4 +-
 .../2026-06-26-file-context-as-event-gate.md  |  8 ++--
 ...026-06-26-file-context-as-event-gate.zh.md |  8 ++--
 ...stdin-env-trusted-plugin-surface.i18n.yaml |  4 +-
 ...0-bash-stdin-env-trusted-plugin-surface.md |  4 +-
 ...ash-stdin-env-trusted-plugin-surface.zh.md |  4 +-
 ...026-06-30-event-domain-semantics.i18n.yaml |  4 +-
 .../2026-06-30-event-domain-semantics.md      |  4 +-
 .../2026-06-30-event-domain-semantics.zh.md   |  6 +--
 .../2026-07-02-fs-per-session-cwd.i18n.yaml   |  4 +-
 .../2026-07-02-fs-per-session-cwd.md          |  2 +-
 .../2026-07-02-fs-per-session-cwd.zh.md       |  2 +-
 ...6-07-05-reconstructable-requests.i18n.yaml |  4 +-
 .../2026-07-05-reconstructable-requests.md    |  2 +-
 .../2026-07-05-reconstructable-requests.zh.md |  8 ++--
 ...6-07-06-timeout-deadline-library.i18n.yaml |  4 +-
 .../2026-07-06-timeout-deadline-library.md    |  2 +-
 .../2026-07-06-timeout-deadline-library.zh.md |  2 +-
 ...6-07-07-tool-call-timeout-policy.i18n.yaml |  4 +-
 .../2026-07-07-tool-call-timeout-policy.md    |  6 +--
 .../2026-07-07-tool-call-timeout-policy.zh.md |  6 +--
 ...26-07-08-tool-output-spill-files.i18n.yaml |  4 +-
 .../2026-07-08-tool-output-spill-files.md     |  2 +-
 .../2026-07-08-tool-output-spill-files.zh.md  |  2 +-
 ...n-pressure-and-overflow-recovery.i18n.yaml |  4 +-
 ...mpaction-pressure-and-overflow-recovery.md |  2 +-
 ...ction-pressure-and-overflow-recovery.zh.md |  2 +-
 ...07-12-agent-scope-runtime-design.i18n.yaml |  4 +-
 .../2026-07-12-agent-scope-runtime-design.md  |  4 +-
 ...026-07-12-agent-scope-runtime-design.zh.md |  4 +-
 ...-14-provider-routed-llm-adapters.i18n.yaml |  4 +-
 ...2026-07-14-provider-routed-llm-adapters.md |  2 +-
 ...6-07-14-provider-routed-llm-adapters.zh.md |  2 +-
 ...-model-catalog-and-acp-selection.i18n.yaml |  4 +-
 ...-15-llm-model-catalog-and-acp-selection.md |  4 +-
 ...-llm-model-catalog-and-acp-selection.zh.md |  4 +-
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |  4 +-
 .../2026-07-15-lsp-capability-seam.md         |  6 +--
 .../2026-07-15-lsp-capability-seam.zh.md      |  6 +--
 ...07-16-explicit-turn-cancellation.i18n.yaml |  4 +-
 .../2026-07-16-explicit-turn-cancellation.md  |  8 ++--
 ...026-07-16-explicit-turn-cancellation.zh.md | 10 ++--
 ...19-cooperative-tool-cancellation.i18n.yaml |  4 +-
 ...026-07-19-cooperative-tool-cancellation.md |  4 +-
 ...-07-19-cooperative-tool-cancellation.zh.md |  4 +-
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |  4 +-
 ...026-07-19-gui-layering-and-rpc-protocol.md | 10 ++--
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |  8 ++--
 ...7-19-gui-web-client-architecture.i18n.yaml |  4 +-
 .../2026-07-19-gui-web-client-architecture.md |  4 +-
 ...26-07-19-gui-web-client-architecture.zh.md |  4 +-
 ...kage-invariant-runtime-contracts.i18n.yaml |  4 +-
 ...-19-package-invariant-runtime-contracts.md |  2 +-
 ...-package-invariant-runtime-contracts.zh.md |  2 +-
 ...-package-owned-invariant-service.i18n.yaml |  4 +-
 ...6-07-19-package-owned-invariant-service.md |  2 +-
 ...7-19-package-owned-invariant-service.zh.md |  2 +-
 ...el-context-and-compaction-policy.i18n.yaml |  4 +-
 ...ted-model-context-and-compaction-policy.md |  4 +-
 ...-model-context-and-compaction-policy.zh.md |  4 +-
 ...2-slot-type-chain-implementation.i18n.yaml |  4 +-
 ...26-07-22-slot-type-chain-implementation.md |  4 +-
 ...07-22-slot-type-chain-implementation.zh.md |  4 +-
 ...7-23-client-plugin-loading-model.i18n.yaml |  4 +-
 .../2026-07-23-client-plugin-loading-model.md | 12 ++---
 ...26-07-23-client-plugin-loading-model.zh.md | 12 ++---
 ...ession-scope-and-provide-channel.i18n.yaml |  4 +-
 ...lient-session-scope-and-provide-channel.md |  2 +-
 ...nt-session-scope-and-provide-channel.zh.md |  2 +-
 .../2026-07-26-subprocess-seam.i18n.yaml      |  4 +-
 .../2026-07-26-subprocess-seam.md             | 12 ++---
 .../2026-07-26-subprocess-seam.zh.md          | 12 ++---
 .../2026-07-26-task-registry-seam.i18n.yaml   |  4 +-
 .../2026-07-26-task-registry-seam.md          | 22 ++++-----
 .../2026-07-26-task-registry-seam.zh.md       | 22 ++++-----
 ...07-27-dispose-ladder-to-consumer.i18n.yaml |  4 +-
 .../2026-07-27-dispose-ladder-to-consumer.md  |  4 +-
 ...026-07-27-dispose-ladder-to-consumer.zh.md |  6 +--
 ...directory-picker-capability-seam.i18n.yaml |  4 +-
 ...-07-28-directory-picker-capability-seam.md |  8 ++--
 ...-28-directory-picker-capability-seam.zh.md |  8 ++--
 .../2026-07-28-user-settings-seam.i18n.yaml   |  4 +-
 .../2026-07-28-user-settings-seam.md          |  4 +-
 .../2026-07-28-user-settings-seam.zh.md       |  4 +-
 ...undaries-and-atomic-registration.i18n.yaml |  4 +-
 ...tial-boundaries-and-atomic-registration.md |  2 +-
 ...l-boundaries-and-atomic-registration.zh.md |  2 +-
 ...-followup-enqueue-and-owned-runs.i18n.yaml |  4 +-
 ...6-07-30-followup-enqueue-and-owned-runs.md |  2 +-
 ...7-30-followup-enqueue-and-owned-runs.zh.md |  2 +-
 ...-manager-native-repository-cache.i18n.yaml |  4 +-
 ...package-manager-native-repository-cache.md |  2 +-
 ...kage-manager-native-repository-cache.zh.md |  2 +-
 ...30-settings-write-path-integrity.i18n.yaml |  4 +-
 ...026-07-30-settings-write-path-integrity.md |  4 +-
 ...-07-30-settings-write-path-integrity.zh.md |  6 +--
 .../2026-07-30-web-config-plane.i18n.yaml     |  4 +-
 .../2026-07-30-web-config-plane.md            |  4 +-
 .../2026-07-30-web-config-plane.zh.md         |  4 +-
 ...claimed-pre-step-inbox-lifecycle.i18n.yaml |  4 +-
 ...-07-31-claimed-pre-step-inbox-lifecycle.md |  4 +-
 ...-31-claimed-pre-step-inbox-lifecycle.zh.md |  4 +-
 ...runtime-portable-identifier-seam.i18n.yaml |  4 +-
 ...1-code-runtime-portable-identifier-seam.md | 16 +++----
 ...ode-runtime-portable-identifier-seam.zh.md | 16 +++----
 ...26-08-01-packaged-ripgrep-search.i18n.yaml |  4 +-
 .../2026-08-01-packaged-ripgrep-search.md     |  2 +-
 .../2026-08-01-packaged-ripgrep-search.zh.md  |  2 +-
 ...-pi-ai-declared-provider-catalog.i18n.yaml |  4 +-
 ...6-08-03-pi-ai-declared-provider-catalog.md |  2 +-
 ...8-03-pi-ai-declared-provider-catalog.zh.md |  2 +-
 ...4-configuration-source-ownership.i18n.yaml |  4 +-
 ...26-08-04-configuration-source-ownership.md |  2 +-
 ...08-04-configuration-source-ownership.zh.md |  2 +-
 ...-provider-endpoint-interrogation.i18n.yaml |  4 +-
 ...4-draft-provider-endpoint-interrogation.md |  4 +-
 ...raft-provider-endpoint-interrogation.zh.md |  4 +-
 ...08-04-websocket-downlink-carrier.i18n.yaml |  4 +-
 .../2026-08-04-websocket-downlink-carrier.md  |  4 +-
 ...026-08-04-websocket-downlink-carrier.zh.md |  4 +-
 ...026-08-05-profile-plugin-bundles.i18n.yaml |  4 +-
 .../2026-08-05-profile-plugin-bundles.md      |  2 +-
 .../2026-08-05-profile-plugin-bundles.zh.md   |  2 +-
 .../2026-08-05-session-preparation.i18n.yaml  |  4 +-
 .../2026-08-05-session-preparation.md         |  2 +-
 .../2026-08-05-session-preparation.zh.md      |  2 +-
 ...ubagent-list-identity-projection.i18n.yaml |  4 +-
 ...08-06-subagent-list-identity-projection.md |  2 +-
 ...06-subagent-list-identity-projection.zh.md |  2 +-
 ...ient-tool-presentation-ownership.i18n.yaml |  4 +-
 ...8-08-client-tool-presentation-ownership.md |  6 +--
 ...8-client-tool-presentation-ownership.zh.md |  6 +--
 ...20-error-cause-chain-diagnostics.i18n.yaml |  4 +-
 ...026-07-20-error-cause-chain-diagnostics.md |  8 ++--
 ...-07-20-error-cause-chain-diagnostics.zh.md |  8 ++--
 ...nsport-truncation-classification.i18n.yaml |  2 +-
 ...-ai-transport-truncation-classification.md |  2 +-
 ...ranscript-log-ordered-projection.i18n.yaml |  4 +-
 ...0-web-transcript-log-ordered-projection.md |  2 +-
 ...eb-transcript-log-ordered-projection.zh.md |  2 +-
 ...resume-selector-batch-projection.i18n.yaml |  4 +-
 ...-07-31-resume-selector-batch-projection.md |  2 +-
 ...-31-resume-selector-batch-projection.zh.md |  2 +-
 ...-08-06-api-key-format-validation.i18n.yaml |  4 +-
 .../2026-08-06-api-key-format-validation.md   |  6 +--
 ...2026-08-06-api-key-format-validation.zh.md |  6 +--
 .../feature/2026-06-15-code-mode.i18n.yaml    |  4 +-
 .../feature/2026-06-15-code-mode.md           |  4 +-
 .../feature/2026-06-15-code-mode.zh.md        |  4 +-
 ...26-06-17-filesystem-tool-schemas.i18n.yaml |  4 +-
 .../2026-06-17-filesystem-tool-schemas.md     |  2 +-
 .../2026-06-17-filesystem-tool-schemas.zh.md  |  2 +-
 ...06-18-compaction-capability-seam.i18n.yaml |  4 +-
 .../2026-06-18-compaction-capability-seam.md  |  6 +--
 ...026-06-18-compaction-capability-seam.zh.md |  8 ++--
 ...6-06-21-subagent-capability-seam.i18n.yaml |  4 +-
 .../2026-06-21-subagent-capability-seam.md    |  6 +--
 .../2026-06-21-subagent-capability-seam.zh.md |  6 +--
 .../2026-06-22-acp-subagent-backend.i18n.yaml |  4 +-
 .../2026-06-22-acp-subagent-backend.md        |  2 +-
 .../2026-06-22-acp-subagent-backend.zh.md     |  2 +-
 .../feature/2026-06-30-hook-bridges.i18n.yaml |  4 +-
 .../feature/2026-06-30-hook-bridges.md        | 12 ++---
 .../feature/2026-06-30-hook-bridges.zh.md     | 12 ++---
 .../2026-06-30-hook-protocol-lib.i18n.yaml    |  4 +-
 .../feature/2026-06-30-hook-protocol-lib.md   |  2 +-
 .../2026-06-30-hook-protocol-lib.zh.md        |  2 +-
 ...0-interception-extension-points.i18n.yaml} |  6 +--
 ...26-06-30-interception-extension-points.md} | 14 +++---
 ...06-30-interception-extension-points.zh.md} | 20 ++++----
 .../2026-07-05-dynamic-workflows.i18n.yaml    |  4 +-
 .../feature/2026-07-05-dynamic-workflows.md   |  4 +-
 .../2026-07-05-dynamic-workflows.zh.md        |  4 +-
 .../feature/2026-07-05-skill-system.i18n.yaml |  4 +-
 .../feature/2026-07-05-skill-system.md        |  4 +-
 .../feature/2026-07-05-skill-system.zh.md     |  4 +-
 .../2026-07-06-approval-seam.i18n.yaml        |  4 +-
 .../feature/2026-07-06-approval-seam.md       |  4 +-
 .../feature/2026-07-06-approval-seam.zh.md    |  4 +-
 .../2026-07-06-explicit-tool-order.i18n.yaml  |  4 +-
 .../feature/2026-07-06-explicit-tool-order.md |  2 +-
 .../2026-07-06-explicit-tool-order.zh.md      |  2 +-
 .../feature/2026-07-06-sandbox.i18n.yaml      |  4 +-
 .../implemented/feature/2026-07-06-sandbox.md | 14 +++---
 .../feature/2026-07-06-sandbox.zh.md          | 14 +++---
 ...-10-parallel-tool-call-execution.i18n.yaml |  4 +-
 ...2026-07-10-parallel-tool-call-execution.md |  2 +-
 ...6-07-10-parallel-tool-call-execution.zh.md |  2 +-
 ...10-sqlite-session-query-provider.i18n.yaml |  4 +-
 ...026-07-10-sqlite-session-query-provider.md |  2 +-
 ...-07-10-sqlite-session-query-provider.zh.md |  2 +-
 .../2026-07-16-harness-level-loop.i18n.yaml   |  4 +-
 .../feature/2026-07-16-harness-level-loop.md  |  8 ++--
 .../2026-07-16-harness-level-loop.zh.md       |  8 ++--
 ...26-07-16-persistent-pty-sessions.i18n.yaml |  4 +-
 .../2026-07-16-persistent-pty-sessions.md     |  4 +-
 .../2026-07-16-persistent-pty-sessions.zh.md  |  4 +-
 ...-fresh-agent-ralph-workflow-tool.i18n.yaml |  4 +-
 ...6-07-19-fresh-agent-ralph-workflow-tool.md |  4 +-
 ...7-19-fresh-agent-ralph-workflow-tool.zh.md |  4 +-
 ...26-07-19-model-facing-goal-tools.i18n.yaml |  4 +-
 .../2026-07-19-model-facing-goal-tools.md     |  2 +-
 .../2026-07-19-model-facing-goal-tools.zh.md  |  2 +-
 ...rsisted-same-session-goal-domain.i18n.yaml |  4 +-
 ...7-19-persisted-same-session-goal-domain.md |  2 +-
 ...9-persisted-same-session-goal-domain.zh.md |  2 +-
 ...9-same-session-goal-round-driver.i18n.yaml |  4 +-
 ...26-07-19-same-session-goal-round-driver.md |  4 +-
 ...07-19-same-session-goal-round-driver.zh.md |  4 +-
 ...-20-code-mode-typed-tool-returns.i18n.yaml |  4 +-
 ...2026-07-20-code-mode-typed-tool-returns.md |  4 +-
 ...6-07-20-code-mode-typed-tool-returns.zh.md |  4 +-
 ...-07-25-workspace-ui-product-flow.i18n.yaml |  4 +-
 .../2026-07-25-workspace-ui-product-flow.md   |  2 +-
 ...2026-07-25-workspace-ui-product-flow.zh.md |  2 +-
 ...26-07-26-code-dispatch-log-spill.i18n.yaml |  4 +-
 .../2026-07-26-code-dispatch-log-spill.md     |  4 +-
 .../2026-07-26-code-dispatch-log-spill.zh.md  |  4 +-
 ...7-26-code-dispatch-ui-foundation.i18n.yaml |  4 +-
 .../2026-07-26-code-dispatch-ui-foundation.md |  4 +-
 ...26-07-26-code-dispatch-ui-foundation.zh.md |  4 +-
 ...2026-07-27-tmux-location-context.i18n.yaml |  4 +-
 .../2026-07-27-tmux-location-context.md       |  2 +-
 .../2026-07-27-tmux-location-context.zh.md    |  2 +-
 ...ipt-sdk-and-sdk-subagent-backend.i18n.yaml |  4 +-
 ...typescript-sdk-and-sdk-subagent-backend.md |  6 +--
 ...escript-sdk-and-sdk-subagent-backend.zh.md |  6 +--
 ...07-27-web-subagent-conversations.i18n.yaml |  4 +-
 .../2026-07-27-web-subagent-conversations.md  |  6 +--
 ...026-07-27-web-subagent-conversations.zh.md |  6 +--
 ...-workspace-registration-deletion.i18n.yaml |  4 +-
 ...6-07-27-workspace-registration-deletion.md |  2 +-
 ...7-27-workspace-registration-deletion.zh.md |  2 +-
 ...ntinuable-subagent-conversations.i18n.yaml |  4 +-
 ...7-28-continuable-subagent-conversations.md | 10 ++--
 ...8-continuable-subagent-conversations.zh.md | 10 ++--
 ...26-07-28-skill-invocation-policy.i18n.yaml |  4 +-
 .../2026-07-28-skill-invocation-policy.md     |  4 +-
 .../2026-07-28-skill-invocation-policy.zh.md  |  2 +-
 .../2026-07-28-web-terminal-card.i18n.yaml    |  4 +-
 .../feature/2026-07-28-web-terminal-card.md   |  4 +-
 .../2026-07-28-web-terminal-card.zh.md        |  4 +-
 ...0-current-sandbox-policy-context.i18n.yaml |  4 +-
 ...26-07-30-current-sandbox-policy-context.md |  2 +-
 ...07-30-current-sandbox-policy-context.zh.md |  2 +-
 ...-plan-review-presentation-intent.i18n.yaml |  4 +-
 ...6-07-30-plan-review-presentation-intent.md |  4 +-
 ...7-30-plan-review-presentation-intent.zh.md |  2 +-
 ...6-07-30-web-result-card-frontend.i18n.yaml |  4 +-
 .../2026-07-30-web-result-card-frontend.md    |  4 +-
 .../2026-07-30-web-result-card-frontend.zh.md |  4 +-
 ...7-31-code-mode-language-dispatch.i18n.yaml |  4 +-
 .../2026-07-31-code-mode-language-dispatch.md |  6 +--
 ...26-07-31-code-mode-language-dispatch.zh.md |  6 +--
 ...7-31-web-telemetry-default-mount.i18n.yaml |  4 +-
 .../2026-07-31-web-telemetry-default-mount.md |  2 +-
 ...26-07-31-web-telemetry-default-mount.zh.md |  2 +-
 ...nter-revealed-sidebar-scrollbars.i18n.yaml |  4 +-
 ...-04-pointer-revealed-sidebar-scrollbars.md |  2 +-
 ...-pointer-revealed-sidebar-scrollbars.zh.md |  2 +-
 ...26-08-05-context-form-vocabulary.i18n.yaml |  4 +-
 .../2026-08-05-context-form-vocabulary.md     |  2 +-
 .../2026-08-05-context-form-vocabulary.zh.md  |  2 +-
 .../2026-08-05-pwsh-ui-bash-parity.i18n.yaml  |  4 +-
 .../feature/2026-08-05-pwsh-ui-bash-parity.md |  4 +-
 .../2026-08-05-pwsh-ui-bash-parity.zh.md      |  4 +-
 ...6-08-07-web-inline-file-mentions.i18n.yaml |  4 +-
 .../2026-08-07-web-inline-file-mentions.md    |  2 +-
 .../2026-08-07-web-inline-file-mentions.zh.md |  2 +-
 ...8-user-explicit-skill-invocation.i18n.yaml |  4 +-
 ...26-08-08-user-explicit-skill-invocation.md |  2 +-
 ...08-08-user-explicit-skill-invocation.zh.md |  2 +-
 ...-20-core-data-structures-catalog.i18n.yaml |  4 +-
 ...2026-06-20-core-data-structures-catalog.md | 22 ++++-----
 ...6-06-20-core-data-structures-catalog.zh.md | 24 +++++-----
 .../2026-07-02-tool-schema-catalog.i18n.yaml  |  4 +-
 .../process/2026-07-02-tool-schema-catalog.md |  4 +-
 .../2026-07-02-tool-schema-catalog.zh.md      |  4 +-
 .../2026-07-20-gui-testing-system.i18n.yaml   |  4 +-
 .../process/2026-07-20-gui-testing-system.md  |  2 +-
 .../2026-07-20-gui-testing-system.zh.md       |  2 +-
 ...package-anchored-subsystem-pages.i18n.yaml |  4 +-
 ...-08-03-package-anchored-subsystem-pages.md |  2 +-
 ...-03-package-anchored-subsystem-pages.zh.md |  2 +-
 ...-06-20-public-agent-stop-surface.i18n.yaml |  4 +-
 .../2026-06-20-public-agent-stop-surface.md   |  4 +-
 ...2026-06-20-public-agent-stop-surface.zh.md |  4 +-
 .../2026-06-26-fsspec-style-fs-seam.i18n.yaml |  4 +-
 .../2026-06-26-fsspec-style-fs-seam.md        | 10 ++--
 .../2026-06-26-fsspec-style-fs-seam.zh.md     | 10 ++--
 ...4-tighten-hook-protocol-contract.i18n.yaml |  4 +-
 ...26-07-04-tighten-hook-protocol-contract.md |  2 +-
 ...07-04-tighten-hook-protocol-contract.zh.md |  2 +-
 ...lan-specific-collaboration-state.i18n.yaml |  4 +-
 ...07-22-plan-specific-collaboration-state.md |  2 +-
 ...22-plan-specific-collaboration-state.zh.md |  2 +-
 ...-23-acp-automation-only-protocol.i18n.yaml |  4 +-
 ...2026-07-23-acp-automation-only-protocol.md |  2 +-
 ...6-07-23-acp-automation-only-protocol.zh.md |  2 +-
 ...nt-loop-observable-state-machine.i18n.yaml |  4 +-
 ...-24-agent-loop-observable-state-machine.md |  2 +-
 ...-agent-loop-observable-state-machine.zh.md |  4 +-
 ...6-merge-subagent-control-service.i18n.yaml |  4 +-
 ...26-07-26-merge-subagent-control-service.md |  2 +-
 ...07-26-merge-subagent-control-service.zh.md |  2 +-
 ...-remove-synthetic-log-only-turns.i18n.yaml |  4 +-
 ...6-07-28-remove-synthetic-log-only-turns.md |  2 +-
 ...7-28-remove-synthetic-log-only-turns.zh.md |  2 +-
 ...-31-one-route-to-add-a-workspace.i18n.yaml |  4 +-
 ...2026-07-31-one-route-to-add-a-workspace.md |  2 +-
 ...6-07-31-one-route-to-add-a-workspace.zh.md |  2 +-
 .../2026-08-04-remove-tui-package.i18n.yaml   |  4 +-
 .../2026-08-04-remove-tui-package.md          |  2 +-
 .../2026-08-04-remove-tui-package.zh.md       |  2 +-
 ...-fork-child-replay-seed-boundary.i18n.yaml |  4 +-
 ...6-06-22-fork-child-replay-seed-boundary.md |  2 +-
 ...6-22-fork-child-replay-seed-boundary.zh.md |  2 +-
 ...6-06-22-subagent-snapshot-replay.i18n.yaml |  4 +-
 .../2026-06-22-subagent-snapshot-replay.md    |  2 +-
 .../2026-06-22-subagent-snapshot-replay.zh.md |  2 +-
 ...-22-cross-platform-test-fixtures.i18n.yaml |  4 +-
 ...2026-07-22-cross-platform-test-fixtures.md |  2 +-
 ...6-07-22-cross-platform-test-fixtures.zh.md |  2 +-
 ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml |  4 +-
 .../2026-07-24-web-gui-browser-e2e-lane.md    |  8 ++--
 .../2026-07-24-web-gui-browser-e2e-lane.zh.md |  8 ++--
 .../2026-06-16-typed-event-schemas.i18n.yaml  |  4 +-
 .../2026-06-16-typed-event-schemas.md         |  4 +-
 .../2026-06-16-typed-event-schemas.zh.md      |  4 +-
 ...on-through-tool-capability-seams.i18n.yaml |  4 +-
 ...cellation-through-tool-capability-seams.md |  2 +-
 ...lation-through-tool-capability-seams.zh.md |  2 +-
 ...-25-client-settings-locale-theme.i18n.yaml |  4 +-
 ...2026-07-25-client-settings-locale-theme.md |  2 +-
 ...6-07-25-client-settings-locale-theme.zh.md |  6 +--
 ...ssion-projection-and-command-log.i18n.yaml |  4 +-
 ...7-27-session-projection-and-command-log.md |  4 +-
 ...7-session-projection-and-command-log.zh.md |  6 +--
 ...026-06-30-pre-tool-input-rewrite.i18n.yaml |  4 +-
 .../2026-06-30-pre-tool-input-rewrite.md      |  4 +-
 .../2026-06-30-pre-tool-input-rewrite.zh.md   |  4 +-
 ...2026-07-06-recallable-compaction.i18n.yaml |  4 +-
 .../2026-07-06-recallable-compaction.md       |  2 +-
 .../2026-07-06-recallable-compaction.zh.md    |  2 +-
 ...-07-08-interactive-side-sessions.i18n.yaml |  4 +-
 .../2026-07-08-interactive-side-sessions.md   |  2 +-
 ...2026-07-08-interactive-side-sessions.zh.md |  2 +-
 ...07-17-sdk-follow-up-capabilities.i18n.yaml |  4 +-
 .../2026-07-17-sdk-follow-up-capabilities.md  |  2 +-
 ...026-07-17-sdk-follow-up-capabilities.zh.md |  2 +-
 ...04-prune-dead-core-spine-surface.i18n.yaml |  4 +-
 ...026-07-04-prune-dead-core-spine-surface.md |  6 +--
 ...-07-04-prune-dead-core-spine-surface.zh.md |  6 +--
 ...ld-session-persistence-interface.i18n.yaml |  4 +-
 ...6-20-fold-session-persistence-interface.md | 10 ++--
 ...0-fold-session-persistence-interface.zh.md | 10 ++--
 ...apse-workflow-to-foreground-core.i18n.yaml |  4 +-
 ...12-collapse-workflow-to-foreground-core.md |  4 +-
 ...collapse-workflow-to-foreground-core.zh.md |  4 +-
 ...ne-unused-skill-registry-surface.i18n.yaml |  4 +-
 ...-12-prune-unused-skill-registry-surface.md |  2 +-
 ...-prune-unused-skill-registry-surface.zh.md |  2 +-
 ...19-fold-compaction-package-split.i18n.yaml |  4 +-
 ...026-07-19-fold-compaction-package-split.md |  8 ++--
 ...-07-19-fold-compaction-package-split.zh.md |  8 ++--
 AGENTS.md                                     | 40 ++++++++--------
 apps/web/tests/approval-composer.e2e.ts       |  2 +-
 apps/web/tests/default-model.e2e.ts           |  2 +-
 apps/web/tests/lifecycle-chrome.e2e.ts        |  2 +-
 apps/web/tests/live-interactions.e2e.ts       |  2 +-
 apps/web/tests/models-settings.e2e.ts         |  2 +-
 apps/web/tests/replay-round-trip.e2e.ts       |  2 +-
 apps/web/tests/scaffold.ts                    |  2 +-
 .../tests/sidebar-subagent-activity.e2e.ts    |  2 +-
 apps/web/tests/skill-user-invoke.e2e.ts       |  4 +-
 docs/AGENTS.md                                |  6 +--
 docs/architecture.i18n.yaml                   |  4 +-
 docs/architecture.md                          |  8 ++--
 docs/architecture.zh.md                       |  8 ++--
 docs/config-catalog.i18n.yaml                 |  4 +-
 docs/config-catalog.md                        |  4 +-
 docs/config-catalog.zh.md                     |  4 +-
 docs/cookbook/adding-a-package.i18n.yaml      |  4 +-
 docs/cookbook/adding-a-package.md             |  2 +-
 docs/cookbook/adding-a-package.zh.md          |  2 +-
 docs/cookbook/extension-cookbook.i18n.yaml    |  4 +-
 docs/cookbook/extension-cookbook.md           |  8 ++--
 docs/cookbook/extension-cookbook.zh.md        |  8 ++--
 docs/defensive-patterns.i18n.yaml             |  4 +-
 docs/defensive-patterns.md                    |  4 +-
 docs/defensive-patterns.zh.md                 |  6 +--
 docs/event-producer-consumer.i18n.yaml        |  4 +-
 docs/event-producer-consumer.md               |  2 +-
 docs/event-producer-consumer.zh.md            |  2 +-
 docs/glossary.i18n.yaml                       |  4 +-
 docs/glossary.md                              |  2 +-
 docs/glossary.zh.md                           |  2 +-
 docs/i18n/terminology.md                      |  4 +-
 docs/i18n/translation-prompt.md               |  2 +-
 docs/subsystems/README.i18n.yaml              |  4 +-
 docs/subsystems/README.md                     | 10 ++--
 docs/subsystems/README.zh.md                  | 10 ++--
 docs/subsystems/bash.i18n.yaml                |  4 +-
 docs/subsystems/bash.md                       |  8 ++--
 docs/subsystems/bash.zh.md                    |  8 ++--
 docs/subsystems/code-runtime.i18n.yaml        |  4 +-
 docs/subsystems/code-runtime.md               | 14 +++---
 docs/subsystems/code-runtime.zh.md            | 12 ++---
 docs/subsystems/commands.i18n.yaml            |  4 +-
 docs/subsystems/commands.md                   |  4 +-
 docs/subsystems/commands.zh.md                |  4 +-
 docs/subsystems/compaction.i18n.yaml          |  4 +-
 docs/subsystems/compaction.md                 |  8 ++--
 docs/subsystems/compaction.zh.md              |  8 ++--
 docs/subsystems/core.i18n.yaml                |  4 +-
 docs/subsystems/core.md                       | 14 +++---
 docs/subsystems/core.zh.md                    | 14 +++---
 docs/subsystems/credentials.i18n.yaml         |  4 +-
 docs/subsystems/credentials.md                |  4 +-
 docs/subsystems/credentials.zh.md             |  4 +-
 docs/subsystems/filesystem.i18n.yaml          |  4 +-
 docs/subsystems/filesystem.md                 | 16 +++----
 docs/subsystems/filesystem.zh.md              | 16 +++----
 docs/subsystems/invariants.i18n.yaml          |  4 +-
 docs/subsystems/invariants.md                 |  2 +-
 docs/subsystems/invariants.zh.md              |  2 +-
 docs/subsystems/llm-streaming.i18n.yaml       |  4 +-
 docs/subsystems/llm-streaming.md              |  4 +-
 docs/subsystems/llm-streaming.zh.md           |  4 +-
 docs/subsystems/lsp.i18n.yaml                 |  4 +-
 docs/subsystems/lsp.md                        |  2 +-
 docs/subsystems/lsp.zh.md                     |  2 +-
 docs/subsystems/persistence.i18n.yaml         |  4 +-
 docs/subsystems/persistence.md                |  4 +-
 docs/subsystems/persistence.zh.md             |  4 +-
 docs/subsystems/plan.i18n.yaml                |  4 +-
 docs/subsystems/plan.md                       |  2 +-
 docs/subsystems/plan.zh.md                    |  2 +-
 docs/subsystems/sandbox.i18n.yaml             |  4 +-
 docs/subsystems/sandbox.md                    |  4 +-
 docs/subsystems/sandbox.zh.md                 |  4 +-
 docs/subsystems/session-projection.i18n.yaml  |  4 +-
 docs/subsystems/session-projection.md         |  2 +-
 docs/subsystems/session-projection.zh.md      |  2 +-
 docs/subsystems/session-query.i18n.yaml       |  4 +-
 docs/subsystems/session-query.md              |  6 +--
 docs/subsystems/session-query.zh.md           |  6 +--
 docs/subsystems/session.i18n.yaml             |  4 +-
 docs/subsystems/session.md                    |  2 +-
 docs/subsystems/session.zh.md                 |  2 +-
 docs/subsystems/settings.i18n.yaml            |  4 +-
 docs/subsystems/settings.md                   |  4 +-
 docs/subsystems/settings.zh.md                |  4 +-
 docs/subsystems/skills.i18n.yaml              |  4 +-
 docs/subsystems/skills.md                     |  6 +--
 docs/subsystems/skills.zh.md                  |  6 +--
 docs/subsystems/spill.i18n.yaml               |  4 +-
 docs/subsystems/spill.md                      |  8 ++--
 docs/subsystems/spill.zh.md                   |  8 ++--
 docs/subsystems/storage.i18n.yaml             |  4 +-
 docs/subsystems/storage.md                    |  4 +-
 docs/subsystems/storage.zh.md                 |  4 +-
 docs/subsystems/subagent.i18n.yaml            |  4 +-
 docs/subsystems/subagent.md                   | 12 ++---
 docs/subsystems/subagent.zh.md                | 14 +++---
 docs/subsystems/subprocess.i18n.yaml          |  4 +-
 docs/subsystems/subprocess.md                 | 10 ++--
 docs/subsystems/subprocess.zh.md              | 10 ++--
 docs/subsystems/tasks.i18n.yaml               |  4 +-
 docs/subsystems/tasks.md                      |  6 +--
 docs/subsystems/tasks.zh.md                   |  6 +--
 docs/subsystems/telemetry.i18n.yaml           |  4 +-
 docs/subsystems/telemetry.md                  | 16 +++----
 docs/subsystems/telemetry.zh.md               | 16 +++----
 docs/subsystems/tools.i18n.yaml               |  4 +-
 docs/subsystems/tools.md                      |  6 +--
 docs/subsystems/tools.zh.md                   |  6 +--
 docs/subsystems/web.i18n.yaml                 |  4 +-
 docs/subsystems/web.md                        |  4 +-
 docs/subsystems/web.zh.md                     |  4 +-
 docs/subsystems/workflow.i18n.yaml            |  4 +-
 docs/subsystems/workflow.md                   |  8 ++--
 docs/subsystems/workflow.zh.md                |  8 ++--
 docs/subsystems/workspace.i18n.yaml           |  4 +-
 docs/subsystems/workspace.md                  |  4 +-
 docs/subsystems/workspace.zh.md               |  4 +-
 docs/user/develop/basic/tool.i18n.yaml        |  4 +-
 docs/user/develop/basic/tool.md               |  2 +-
 docs/user/develop/basic/tool.zh.md            |  2 +-
 docs/user/develop/practice/index.i18n.yaml    |  4 +-
 docs/user/develop/practice/index.md           | 44 ++++++++---------
 docs/user/develop/practice/index.zh.md        | 48 +++++++++----------
 docs/user/guide/config.i18n.yaml              |  2 +-
 docs/user/guide/config.md                     |  2 +-
 examples/acp-agent/tests/acp.snapshot.ts      |  2 +-
 native/landlock-run/AGENTS.md                 |  4 +-
 native/landlock-run/docs/architecture.md      |  2 +-
 .../landlock-run/packages/entry/src/index.ts  |  4 +-
 native/landlock-run/test/entry.test.js        |  2 +-
 packages/AGENTS.md                            |  2 +-
 packages/README.i18n.yaml                     |  4 +-
 packages/README.md                            | 12 ++---
 packages/README.zh.md                         | 12 ++---
 packages/bash/README.i18n.yaml                |  4 +-
 packages/bash/README.md                       |  2 +-
 packages/bash/README.zh.md                    |  8 ++--
 packages/bash/bash-local/README.i18n.yaml     |  4 +-
 packages/bash/bash-local/README.md            |  2 +-
 packages/bash/bash-local/README.zh.md         |  2 +-
 packages/bash/bash-local/src/index.ts         |  4 +-
 packages/bash/bash-sandbox/README.i18n.yaml   |  4 +-
 packages/bash/bash-sandbox/README.md          |  2 +-
 packages/bash/bash-sandbox/README.zh.md       |  2 +-
 packages/bash/bash/README.i18n.yaml           |  4 +-
 packages/bash/bash/README.md                  | 12 ++---
 packages/bash/bash/README.zh.md               | 12 ++---
 packages/bash/bash/src/index.ts               |  2 +-
 packages/bash/bash/src/invariant.ts           |  2 +-
 packages/bash/pwsh-local/README.i18n.yaml     |  4 +-
 packages/bash/pwsh-local/README.md            |  2 +-
 packages/bash/pwsh-local/README.zh.md         |  2 +-
 packages/bash/pwsh-local/src/index.ts         |  4 +-
 packages/bash/tool-bash/README.i18n.yaml      |  4 +-
 packages/bash/tool-bash/README.md             |  6 +--
 packages/bash/tool-bash/README.zh.md          |  6 +--
 packages/bash/tool-bash/src/index.ts          |  4 +-
 .../bash/tool-bash/tests/integration.spec.ts  |  2 +-
 packages/bash/tool-pwsh/src/background.ts     |  2 +-
 packages/bash/tool-pwsh/src/index.ts          |  4 +-
 packages/boot/app-boot/src/profile.ts         | 10 ++--
 packages/bundle/headless/README.i18n.yaml     |  4 +-
 packages/bundle/headless/README.md            |  4 +-
 packages/bundle/headless/README.zh.md         |  4 +-
 packages/bundle/web-app/src/index.ts          |  2 +-
 packages/bundle/web-app/tests/web-app.spec.ts |  4 +-
 packages/client/AGENTS.md                     |  2 +-
 packages/client/connection/README.i18n.yaml   |  4 +-
 packages/client/connection/README.md          |  2 +-
 packages/client/connection/README.zh.md       |  2 +-
 packages/client/connection/src/client/api.ts  |  2 +-
 packages/client/locale/src/client/index.ts    |  2 +-
 packages/client/locale/tests/locale.spec.ts   |  2 +-
 packages/client/modules/README.i18n.yaml      |  4 +-
 packages/client/modules/README.md             |  2 +-
 packages/client/modules/README.zh.md          |  2 +-
 .../client/modules/src/client/manifest.ts     | 16 +++----
 packages/client/modules/src/client/system.ts  |  8 ++--
 packages/client/modules/tests/loader.spec.ts  |  2 +-
 packages/client/runtime/README.i18n.yaml      |  4 +-
 packages/client/runtime/README.md             |  2 +-
 packages/client/runtime/README.zh.md          | 12 ++---
 .../runtime/src/client/contract/sessions.ts   |  2 +-
 .../src/client/sessions/projection-store.ts   |  2 +-
 .../runtime/src/client/sessions/service.ts    |  6 +--
 .../runtime/src/client/sessions/session.ts    |  2 +-
 .../src/client/sessions/transcript-adapter.ts |  4 +-
 packages/client/runtime/src/client/slots.ts   |  2 +-
 .../src/client/workspaces/workspace.ts        |  2 +-
 .../tests/compact-checkpoint-pin.spec.ts      | 10 ++--
 .../runtime/tests/projection-store.spec.ts    |  2 +-
 .../runtime/tests/slots-service.spec.ts       |  8 ++--
 packages/client/schema-form/README.i18n.yaml  |  4 +-
 packages/client/schema-form/README.md         |  2 +-
 packages/client/schema-form/README.zh.md      |  2 +-
 packages/client/test-runtime/src/index.ts     |  8 ++--
 packages/client/test-runtime/src/sessions.ts  |  2 +-
 .../client/ui-conversation/README.i18n.yaml   |  4 +-
 packages/client/ui-conversation/README.md     |  2 +-
 packages/client/ui-conversation/README.zh.md  |  2 +-
 .../ui-conversation/src/client/apply.ts       |  2 +-
 .../src/client/input/facade.ts                |  2 +-
 .../src/client/queue/QueueDock.tsx            |  2 +-
 .../tests/input-scenarios.spec.tsx            |  2 +-
 .../tests/selection-survival.spec.tsx         |  2 +-
 packages/client/ui-layout/src/client/index.ts |  2 +-
 .../client/ui-layout/src/client/service.ts    |  2 +-
 .../client/ui-layout/tests/service.spec.ts    |  2 +-
 packages/client/ui-model/README.i18n.yaml     |  4 +-
 packages/client/ui-model/README.md            |  2 +-
 packages/client/ui-model/README.zh.md         |  2 +-
 packages/client/ui-model/src/client/index.ts  |  2 +-
 .../client/ui-primitives/src/clipboard.ts     |  2 +-
 .../ui-primitives/src/markdown/incremental.ts |  2 +-
 .../ui-primitives/tests/diff-block.spec.tsx   |  2 +-
 .../tests/terminal-block.spec.tsx             |  2 +-
 .../ui-sidebar/src/client/contract/slots.ts   |  2 +-
 .../client/ui-slash/src/client/controller.ts  |  2 +-
 packages/client/ui-slots/README.i18n.yaml     |  4 +-
 packages/client/ui-slots/README.md            |  6 +--
 packages/client/ui-slots/README.zh.md         |  6 +--
 packages/client/ui-slots/src/index.ts         |  6 +--
 packages/client/ui-slots/src/renderer.ts      | 10 ++--
 .../ui-theme/src/client/settings-contract.ts  |  2 +-
 .../ui-tool/tests/chat-code-subcalls.spec.tsx |  5 +-
 .../ui-tool/tests/toolview-slot.spec.tsx      |  2 +-
 .../client/web-react/src/scoped-slots.tsx     |  4 +-
 packages/client/web/README.i18n.yaml          |  4 +-
 packages/client/web/README.md                 |  4 +-
 packages/client/web/README.zh.md              |  4 +-
 packages/client/web/src/boot.tsx              |  8 ++--
 packages/code-runtime/README.i18n.yaml        |  4 +-
 packages/code-runtime/README.md               |  6 +--
 packages/code-runtime/README.zh.md            |  6 +--
 .../code-runtime-worker/src/index.ts          |  6 +--
 .../code-runtime/README.i18n.yaml             |  4 +-
 packages/code-runtime/code-runtime/README.md  |  6 +--
 .../code-runtime/code-runtime/README.zh.md    |  6 +--
 .../code-runtime/code-runtime/src/index.ts    |  6 +--
 .../code-runtime/code-runtime/src/types.ts    |  2 +-
 .../code-runtime/tests/reserved.spec.ts       |  2 +-
 .../code-runtime/tests/service.spec.ts        |  2 +-
 packages/compact/README.i18n.yaml             |  4 +-
 packages/compact/README.md                    |  2 +-
 packages/compact/README.zh.md                 |  2 +-
 .../compact/compact-basic/README.i18n.yaml    |  4 +-
 packages/compact/compact-basic/README.md      |  6 +--
 packages/compact/compact-basic/README.zh.md   |  6 +--
 packages/compact/compact/README.i18n.yaml     |  4 +-
 packages/compact/compact/README.md            | 16 +++----
 packages/compact/compact/README.zh.md         | 16 +++----
 packages/compact/compact/src/index.ts         |  2 +-
 .../compact/compact/tests/compact.spec.ts     |  2 +-
 .../context/tmux-context/README.i18n.yaml     |  4 +-
 packages/context/tmux-context/README.md       |  2 +-
 packages/context/tmux-context/README.zh.md    |  2 +-
 packages/context/tmux-context/src/index.ts    |  4 +-
 packages/core/README.i18n.yaml                |  4 +-
 packages/core/README.md                       |  2 +-
 packages/core/README.zh.md                    |  2 +-
 packages/core/agent-loop/README.i18n.yaml     |  4 +-
 packages/core/agent-loop/README.md            |  6 +--
 packages/core/agent-loop/README.zh.md         |  6 +--
 packages/core/agent-loop/src/index.ts         |  2 +-
 packages/core/agent-loop/tests/cancel.spec.ts |  2 +-
 .../agent-loop/tests/interception.spec.ts     |  2 +-
 packages/core/agent/README.i18n.yaml          |  4 +-
 packages/core/agent/README.md                 |  6 +--
 packages/core/agent/README.zh.md              |  8 ++--
 packages/core/agent/src/inbox.ts              |  2 +-
 packages/core/agent/src/index.ts              |  2 +-
 packages/core/agent/src/types.ts              |  6 +--
 packages/core/session/README.i18n.yaml        |  4 +-
 packages/core/session/README.md               |  6 +--
 packages/core/session/README.zh.md            |  6 +--
 packages/core/session/src/index.ts            |  2 +-
 packages/core/system-prompt/README.i18n.yaml  |  4 +-
 packages/core/system-prompt/README.md         |  2 +-
 packages/core/system-prompt/README.zh.md      |  2 +-
 packages/core/tools/README.i18n.yaml          |  4 +-
 packages/core/tools/README.md                 |  2 +-
 packages/core/tools/README.zh.md              |  2 +-
 packages/core/tools/src/code-mode.ts          |  2 +-
 packages/core/tools/src/index.ts              |  6 +--
 packages/core/tools/src/presentation.ts       |  6 +--
 packages/core/tools/src/py-types.ts           |  2 +-
 packages/core/tools/tests/code-mode.spec.ts   |  2 +-
 packages/core/tools/tests/tools.spec.ts       |  4 +-
 .../credentials-local/src/invariant.ts        |  2 +-
 .../credentials/credentials/README.i18n.yaml  |  4 +-
 packages/credentials/credentials/README.md    |  2 +-
 packages/credentials/credentials/README.zh.md |  2 +-
 packages/credentials/credentials/src/index.ts |  2 +-
 packages/e2b/fs-e2b/README.i18n.yaml          |  4 +-
 packages/e2b/fs-e2b/README.md                 |  4 +-
 packages/e2b/fs-e2b/README.zh.md              |  4 +-
 packages/e2b/fs-e2b/src/index.ts              |  2 +-
 packages/e2b/subprocess-e2b/README.i18n.yaml  |  4 +-
 packages/e2b/subprocess-e2b/README.md         |  2 +-
 packages/e2b/subprocess-e2b/README.zh.md      |  2 +-
 packages/e2b/subprocess-e2b/src/index.ts      |  2 +-
 packages/e2b/subprocess-e2b/src/process.ts    |  2 +-
 .../agent-spine-demo/README.i18n.yaml         |  4 +-
 packages/examples/agent-spine-demo/README.md  |  4 +-
 .../examples/agent-spine-demo/README.zh.md    |  4 +-
 packages/fs/README.i18n.yaml                  |  4 +-
 packages/fs/README.md                         |  8 ++--
 packages/fs/README.zh.md                      | 14 +++---
 packages/fs/fs-local/README.i18n.yaml         |  4 +-
 packages/fs/fs-local/README.md                |  2 +-
 packages/fs/fs-local/README.zh.md             |  2 +-
 packages/fs/fs-local/src/fsio.ts              |  4 +-
 packages/fs/fs-local/src/index.ts             |  2 +-
 packages/fs/fs-local/tests/filesystem.spec.ts |  4 +-
 packages/fs/fs-policy/README.i18n.yaml        |  4 +-
 packages/fs/fs-policy/README.md               |  4 +-
 packages/fs/fs-policy/README.zh.md            |  4 +-
 packages/fs/fs-sandbox/src/index.ts           |  2 +-
 packages/fs/fs/README.i18n.yaml               |  4 +-
 packages/fs/fs/README.md                      |  6 +--
 packages/fs/fs/README.zh.md                   | 26 +++++-----
 packages/fs/fs/src/index.ts                   |  2 +-
 packages/fs/fs/src/types.ts                   |  2 +-
 packages/fs/fs/tests/service.spec.ts          |  2 +-
 packages/fs/tool-fs/README.i18n.yaml          |  4 +-
 packages/fs/tool-fs/README.md                 |  2 +-
 packages/fs/tool-fs/README.zh.md              |  2 +-
 packages/fs/tool-fs/src/session-cwd.ts        |  2 +-
 packages/goal/goal-session/README.i18n.yaml   |  4 +-
 packages/goal/goal-session/README.md          |  2 +-
 packages/goal/goal-session/README.zh.md       |  2 +-
 packages/goal/goal-session/src/index.ts       |  2 +-
 packages/guard/README.i18n.yaml               |  4 +-
 packages/guard/README.md                      |  2 +-
 packages/guard/README.zh.md                   |  4 +-
 packages/guard/timeout-policy/src/index.ts    |  2 +-
 packages/hooks/README.i18n.yaml               |  4 +-
 packages/hooks/README.md                      |  2 +-
 packages/hooks/README.zh.md                   |  2 +-
 packages/hooks/hook-protocol/README.i18n.yaml |  4 +-
 packages/hooks/hook-protocol/README.md        |  4 +-
 packages/hooks/hook-protocol/README.zh.md     |  4 +-
 packages/hooks/hook-protocol/src/detached.ts  |  2 +-
 packages/hooks/hook-protocol/src/index.ts     |  2 +-
 packages/hooks/hook-protocol/src/merge.ts     |  2 +-
 packages/hooks/hook-protocol/src/runner.ts    |  2 +-
 packages/hooks/hook-protocol/src/types.ts     | 10 ++--
 .../hooks/hook-protocol/tests/runner.spec.ts  |  2 +-
 packages/hooks/hooks-claude/README.i18n.yaml  |  4 +-
 packages/hooks/hooks-claude/README.md         | 10 ++--
 packages/hooks/hooks-claude/README.zh.md      | 10 ++--
 packages/hooks/hooks-claude/src/index.ts      | 12 ++---
 .../hooks-claude/tests/coverage-cases.ts      |  2 +-
 packages/hooks/hooks-codex/README.i18n.yaml   |  4 +-
 packages/hooks/hooks-codex/README.md          |  8 ++--
 packages/hooks/hooks-codex/README.zh.md       |  8 ++--
 packages/hooks/hooks-codex/src/index.ts       |  8 ++--
 .../hooks/hooks-codex/tests/coverage-cases.ts |  2 +-
 packages/host/apiproxy/src/api-proxy.ts       |  6 +--
 packages/host/apiproxy/src/api/events.ts      |  2 +-
 .../host/apiproxy/src/native-path-opener.ts   |  4 +-
 .../apiproxy/tests/api-proxy-cold.spec.ts     |  2 +-
 .../apiproxy/tests/api-proxy-config.spec.ts   |  2 +-
 .../tests/api-proxy-subagents.spec.ts         |  2 +-
 .../src/native-picker.ts                      |  2 +-
 .../src/win32-dialog-logic.ts                 |  2 +-
 .../src/win32-dialog.ts                       |  2 +-
 packages/host/directory-picker/src/index.ts   |  2 +-
 .../host/directory-picker/src/invariant.ts    |  5 +-
 packages/host/webserver/src/index.ts          |  2 +-
 packages/interaction/README.i18n.yaml         |  4 +-
 packages/interaction/README.md                |  2 +-
 packages/interaction/README.zh.md             |  2 +-
 .../tool-ask-user/README.i18n.yaml            |  4 +-
 packages/interaction/tool-ask-user/README.md  |  2 +-
 .../interaction/tool-ask-user/README.zh.md    |  2 +-
 .../interaction/tool-ask-user/src/index.ts    |  2 +-
 .../interaction/user-approval/src/index.ts    |  2 +-
 .../user-interaction/README.i18n.yaml         |  4 +-
 .../interaction/user-interaction/README.md    |  4 +-
 .../interaction/user-interaction/README.zh.md |  4 +-
 .../interaction/user-interaction/src/index.ts |  2 +-
 packages/llm/README.i18n.yaml                 |  4 +-
 packages/llm/README.md                        |  2 +-
 packages/llm/README.zh.md                     |  6 +--
 packages/llm/llm-deepseek/src/adapter.ts      |  4 +-
 packages/llm/llm-pi-ai/README.i18n.yaml       |  4 +-
 packages/llm/llm-pi-ai/README.md              |  2 +-
 packages/llm/llm-pi-ai/README.zh.md           |  2 +-
 packages/llm/llm-pi-ai/src/adapter.ts         |  2 +-
 packages/llm/llm-retry/src/index.ts           |  6 +--
 packages/llm/llm/README.i18n.yaml             |  4 +-
 packages/llm/llm/README.md                    |  4 +-
 packages/llm/llm/README.zh.md                 |  4 +-
 packages/llm/llm/src/error.ts                 |  2 +-
 packages/llm/llm/src/retry-policy.ts          |  2 +-
 packages/llm/llm/tests/attribution.spec.ts    |  2 +-
 packages/llm/token-meter/src/index.ts         |  2 +-
 packages/lsp/README.i18n.yaml                 |  4 +-
 packages/lsp/README.md                        |  6 +--
 packages/lsp/README.zh.md                     |  6 +--
 packages/lsp/lsp-local/src/connection.ts      |  6 +--
 packages/lsp/lsp-local/src/instance.ts        |  2 +-
 packages/lsp/lsp-local/src/translate.ts       |  6 +--
 packages/lsp/lsp/README.i18n.yaml             |  4 +-
 packages/lsp/lsp/README.md                    |  8 ++--
 packages/lsp/lsp/README.zh.md                 |  8 ++--
 packages/lsp/lsp/src/index.ts                 |  2 +-
 packages/lsp/tool-lsp/README.i18n.yaml        |  4 +-
 packages/lsp/tool-lsp/README.md               |  2 +-
 packages/lsp/tool-lsp/README.zh.md            |  2 +-
 .../plan/plan-mode/tests/plan-mode.spec.ts    |  2 +-
 packages/sandbox/sandbox-local/src/index.ts   |  8 ++--
 .../sandbox/sandbox-local/tests/local.spec.ts |  6 +--
 packages/sandbox/sandbox/README.i18n.yaml     |  4 +-
 packages/sandbox/sandbox/README.md            |  4 +-
 packages/sandbox/sandbox/README.zh.md         |  6 +--
 packages/sandbox/sandbox/src/index.ts         |  2 +-
 packages/scaffold/create-sdk/src/headless.ts  |  2 +-
 packages/scaffold/scripts/src/telemetry.ts    |  4 +-
 packages/scaffold/server/README.i18n.yaml     |  4 +-
 packages/scaffold/server/README.md            |  2 +-
 packages/scaffold/server/README.zh.md         |  2 +-
 packages/scaffold/server/src/index.ts         |  8 ++--
 .../server/tests/plugin-apply.spec.ts         |  2 +-
 .../scaffold/telemetry/src/anonymous-id.ts    |  8 ++--
 packages/scaffold/telemetry/src/reporter.ts   |  4 +-
 .../repository-plugin/src/mcp.ts              |  2 +-
 .../tool-cordis/src/api-catalog.ts            | 20 ++++----
 .../session-query-sqlite/README.i18n.yaml     |  4 +-
 .../session-query-sqlite/README.md            |  2 +-
 .../session-query-sqlite/README.zh.md         |  2 +-
 .../session-query/session-query/src/index.ts  |  2 +-
 .../session-persistence-jsonl/src/index.ts    |  2 +-
 .../README.i18n.yaml                          |  4 +-
 .../session-persistence-sqlite/README.md      |  2 +-
 .../session-persistence-sqlite/README.zh.md   |  6 +--
 .../session-persistence/README.i18n.yaml      |  4 +-
 .../session/session-persistence/README.md     |  4 +-
 .../session/session-persistence/README.zh.md  |  4 +-
 .../session-persistence/src/coordinator.ts    |  2 +-
 .../session/session-persistence/src/index.ts  |  4 +-
 .../tests/persistence.spec.ts                 |  2 +-
 .../session-projection/README.i18n.yaml       |  4 +-
 packages/session/session-projection/README.md |  6 +--
 .../session/session-projection/README.zh.md   |  6 +--
 .../session/session-projection/src/index.ts   |  4 +-
 .../session/session-projection/src/types.ts   |  2 +-
 .../session-telemetry-otel/src/index.ts       |  8 ++--
 .../session-telemetry-otel/src/invariant.ts   |  2 +-
 .../session-telemetry-otel/src/user-id.ts     |  6 +--
 .../tests/user-id.spec.ts                     |  2 +-
 .../session-telemetry/README.i18n.yaml        |  4 +-
 packages/session/session-telemetry/README.md  |  6 +--
 .../session/session-telemetry/README.zh.md    |  6 +--
 .../session-telemetry/src/coordinator.ts      |  8 ++--
 .../session/session-telemetry/src/index.ts    | 10 ++--
 .../session-telemetry/src/invariant.ts        |  2 +-
 packages/session/session-title/src/index.ts   |  2 +-
 .../settings-local/tests/lock-race.spec.ts    |  2 +-
 packages/settings/settings/README.i18n.yaml   |  4 +-
 packages/settings/settings/README.md          |  2 +-
 packages/settings/settings/README.zh.md       |  2 +-
 packages/settings/settings/src/index.ts       |  8 ++--
 packages/settings/settings/tests/memory.ts    |  4 +-
 .../settings/settings/tests/settings.spec.ts  |  2 +-
 packages/skill/skill/src/index.ts             |  3 +-
 packages/skill/tool-skill/README.i18n.yaml    |  4 +-
 packages/skill/tool-skill/README.md           |  2 +-
 packages/skill/tool-skill/README.zh.md        |  6 +--
 packages/spill/spill-policy/src/index.ts      |  2 +-
 packages/spill/spill/README.i18n.yaml         |  4 +-
 packages/spill/spill/README.md                |  8 ++--
 packages/spill/spill/README.zh.md             |  8 ++--
 packages/spill/spill/src/index.ts             |  4 +-
 packages/spill/spill/src/types.ts             |  2 +-
 packages/spill/spill/tests/service.spec.ts    |  2 +-
 packages/storage/README.i18n.yaml             |  4 +-
 packages/storage/README.md                    |  2 +-
 packages/storage/README.zh.md                 |  2 +-
 .../storage/storage-domain/README.i18n.yaml   |  4 +-
 packages/storage/storage-domain/README.md     |  2 +-
 packages/storage/storage-domain/README.zh.md  |  2 +-
 packages/storage/storage-domain/src/domain.ts |  2 +-
 .../tests/helpers/memory-backend.ts           |  2 +-
 packages/subagent/README.i18n.yaml            |  4 +-
 packages/subagent/README.md                   |  2 +-
 packages/subagent/README.zh.md                |  2 +-
 .../subagent-acp/tests/subagent-acp.e2e.ts    |  2 +-
 .../subagent/subagent-claude-code/src/run.ts  |  4 +-
 packages/subagent/subagent-codex/src/run.ts   |  4 +-
 packages/subagent/subagent/README.i18n.yaml   |  4 +-
 packages/subagent/subagent/README.md          |  4 +-
 packages/subagent/subagent/README.zh.md       | 10 ++--
 packages/subagent/subagent/src/index.ts       |  6 +--
 packages/subagent/subagent/src/lifecycle.ts   |  2 +-
 .../subagent/subagent/src/list-children.ts    |  2 +-
 packages/subprocess/README.i18n.yaml          |  4 +-
 packages/subprocess/README.md                 |  4 +-
 packages/subprocess/README.zh.md              |  4 +-
 .../subprocess-local/README.i18n.yaml         |  4 +-
 .../subprocess/subprocess-local/README.md     |  4 +-
 .../subprocess/subprocess-local/README.zh.md  |  6 +--
 .../subprocess/subprocess-local/src/index.ts  | 12 ++---
 .../subprocess-local/src/terminal.ts          |  4 +-
 .../subprocess-local/tests/spawn.spec.ts      |  2 +-
 .../subprocess/subprocess/README.i18n.yaml    |  4 +-
 packages/subprocess/subprocess/README.md      |  4 +-
 packages/subprocess/subprocess/README.zh.md   |  4 +-
 packages/subprocess/subprocess/src/index.ts   |  2 +-
 .../subprocess/subprocess/src/invariant.ts    |  2 +-
 packages/subprocess/subprocess/src/types.ts   |  2 +-
 .../tests/fixtures/fake-acp-agent.ts          |  2 +-
 packages/support/invariants/src/index.ts      |  2 +-
 .../llm-replay/tests/llm-replay.spec.ts       |  2 +-
 packages/tasks/README.i18n.yaml               |  4 +-
 packages/tasks/README.md                      |  2 +-
 packages/tasks/README.zh.md                   |  2 +-
 packages/tasks/tasks-local/README.i18n.yaml   |  4 +-
 packages/tasks/tasks-local/README.md          |  2 +-
 packages/tasks/tasks-local/README.zh.md       |  2 +-
 packages/tasks/tasks-local/src/index.ts       |  4 +-
 packages/tasks/tasks-local/src/invariant.ts   |  2 +-
 packages/tasks/tasks/README.i18n.yaml         |  4 +-
 packages/tasks/tasks/README.md                |  2 +-
 packages/tasks/tasks/README.zh.md             |  2 +-
 packages/tasks/tasks/src/index.ts             |  2 +-
 packages/tasks/tasks/tests/service.spec.ts    |  2 +-
 packages/todo/README.i18n.yaml                |  4 +-
 packages/todo/README.md                       |  2 +-
 packages/todo/README.zh.md                    |  2 +-
 packages/todo/tool-todo/README.i18n.yaml      |  4 +-
 packages/todo/tool-todo/README.md             |  2 +-
 packages/todo/tool-todo/README.zh.md          |  2 +-
 .../todo/tool-todo/tests/integration.spec.ts  |  2 +-
 .../typert/generator/src/cordis-catalog.ts    |  6 ++-
 .../tests/cordis-catalog-contract.spec.ts     |  2 +-
 packages/web/tool-web/README.i18n.yaml        |  4 +-
 packages/web/tool-web/README.md               |  2 +-
 packages/web/tool-web/README.zh.md            |  2 +-
 packages/web/tool-web/src/fetch.ts            |  2 +-
 packages/web/web-fetch-local/README.i18n.yaml |  4 +-
 packages/web/web-fetch-local/README.md        |  2 +-
 packages/web/web-fetch-local/README.zh.md     |  2 +-
 .../web/web-search-deepseek/src/provider.ts   |  2 +-
 packages/web/web-search-exa/README.i18n.yaml  |  4 +-
 packages/web/web-search-exa/README.md         |  2 +-
 packages/web/web-search-exa/README.zh.md      |  2 +-
 packages/web/web-search-exa/src/provider.ts   |  2 +-
 .../web-search-perplexity/README.i18n.yaml    |  4 +-
 packages/web/web-search-perplexity/README.md  |  4 +-
 .../web/web-search-perplexity/README.zh.md    |  4 +-
 packages/web/web/README.i18n.yaml             |  4 +-
 packages/web/web/README.md                    | 14 +++---
 packages/web/web/README.zh.md                 | 16 +++----
 packages/web/web/src/index.ts                 |  2 +-
 packages/workflow/tool-ralph/src/index.ts     |  2 +-
 .../workflow-workerthread/src/runtime.ts      |  4 +-
 packages/workflow/workflow/src/index.ts       |  4 +-
 .../request-response.expected.json            |  2 +-
 vitest.config.ts                              |  2 +-
 966 files changed, 2166 insertions(+), 2159 deletions(-)
 rename .agents/notes/implemented/architecture/{2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml => 2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml} (64%)
 rename .agents/notes/implemented/architecture/{2026-06-18-agent-lifecycle-and-ownership-seams.md => 2026-06-18-agent-lifecycle-and-ownership-contracts.md} (72%)
 rename .agents/notes/implemented/architecture/{2026-06-18-agent-lifecycle-and-ownership-seams.zh.md => 2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md} (71%)
 rename .agents/notes/implemented/feature/{2026-06-30-interception-seams.i18n.yaml => 2026-06-30-interception-extension-points.i18n.yaml} (56%)
 rename .agents/notes/implemented/feature/{2026-06-30-interception-seams.md => 2026-06-30-interception-extension-points.md} (83%)
 rename .agents/notes/implemented/feature/{2026-06-30-interception-seams.zh.md => 2026-06-30-interception-extension-points.zh.md} (76%)

diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
index f89d1da013..5027c64154 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.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 .agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
-2026-06-11-dev-invariants-over-deep-readonly.md: f1a741927cf63b43b1aaf558efc148ff80d2d881
-2026-06-11-dev-invariants-over-deep-readonly.zh.md: ade3e20adb8f5301adb87130d42c2bd7a37f8a47
+2026-06-11-dev-invariants-over-deep-readonly.md: 66980f1ee09c6112f72786d6c3a147aadbc57f6c
+2026-06-11-dev-invariants-over-deep-readonly.zh.md: 38a19ee7dd63823b5a5e103908410786c20435c6
diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
index f1a741927c..66980f1ee0 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-11-dev-invariants-over-deep-readonly.zh.md)
 
 ## Problem
 
-The session log needs two different protections: immutable ownership of each stored fact, and checks for relationships among facts across time and service seams. Conflating them in an optional development plugin would leave production history vulnerable; trying to express both through TypeScript readonly types would not create a runtime boundary or describe relational rules.
+The session log needs two different protections: immutable ownership of each stored fact, and checks for relationships among facts across time and service contracts. Conflating them in an optional development plugin would leave production history vulnerable; trying to express both through TypeScript readonly types would not create a runtime boundary or describe relational rules.
 
 The session log is the durable source of truth for replay, request reconstruction, persistence, and user-visible history. Code outside the session package must be able to inspect that history without retaining a reference that can rewrite it later, and inputs accepted from callers must not remain connected to caller-owned mutable objects.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
index ade3e20adb..38a19ee7dd 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-会话日志需要两种不同的保护：对每条已存储事实的不可变所有权，以及对跨时间和服务 seam 的事实之间关系的检查。如果将二者混为一个可选的开发插件，生产环境的历史记录将失去保护；如果试图通过 TypeScript readonly 类型同时表达两者，既无法建立运行时边界，也无法描述关系规则。
+会话日志需要两种不同的保护：对每条已存储事实的不可变所有权，以及对跨时间和服务约定的事实之间关系的检查。如果将二者混为一个可选的开发插件，生产环境的历史记录将失去保护；如果试图通过 TypeScript readonly 类型同时表达两者，既无法建立运行时边界，也无法描述关系规则。
 
 会话日志是回放、请求重建、持久化与用户可见历史的持久真源。会话包外部的代码必须能检视历史，但不能保留一个可在之后改写历史的引用；从调用方接受的输入也不能继续连接到调用方拥有的可变对象。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
index 5a5aa0eaea..6c3244e519 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.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 .agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
-2026-06-11-microkernel-event-taxonomy.md: fe6c242acbc0b64123711a17a528f35c02d91087
-2026-06-11-microkernel-event-taxonomy.zh.md: aa3db53d640145836817f9835a30c69815f70d23
+2026-06-11-microkernel-event-taxonomy.md: 6cacbc30f29c863de0f8ddfa4df7251a64bc80ca
+2026-06-11-microkernel-event-taxonomy.zh.md: 40edfa1ada0c11395e8ff29e0abfcb0c38de096a
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
index fe6c242acb..6cacbc30f2 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
@@ -10,14 +10,14 @@ The product principle is "everything is a plugin": hooks, /goal, /loop, dynamic
 
 ## Decision
 
-Pure Cordis event taxonomy. The loop's extension seams are typed events with deliberate dispatch modes:
+Pure Cordis event taxonomy. The loop's extension points are typed events with deliberate dispatch modes:
 
 - **waterfall** (around-middleware) where plugins transform, short-circuit, recover, or wrap: `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/pre-execute`, `tools/execute`, `tools/post-execute`, `llm/stream`, `system-prompt/assemble`.
 - **serial** (awaited in listener order) for ordered checkpoints such as `agent/turn-stopping`.
 - **parallel** (awaited fan-out) where every listener must get an independent chance: the `session/flush` durability checkpoint.
 - **emit** (synchronous fire-and-forget) for notifications: inbox transitions, lifecycle, errors, and the contained immutable `tools/result` observation. Durable session events own turn and step boundaries.
 
-The event vocabulary lives in interface packages (dsh-agent declares the agent/* events); `@deepseek-ai/dsh-agent-loop` is the only concrete loop plugin and is itself swappable — nothing outside it may depend on it.
+The event vocabulary lives in contract packages (`dsh-agent` declares the `agent/*` events); `@deepseek-ai/dsh-agent-loop` is the only concrete loop plugin and is itself swappable — nothing outside it may depend on it.
 
 ## Alternatives considered
 
@@ -28,4 +28,4 @@ The event vocabulary lives in interface packages (dsh-agent declares the agent/*
 - Every MVP feature maps to a listener (the [feature → mechanism map](../../../../docs/cookbook/extension-cookbook.md#the-feature--mechanism-map) is the proof obligation, kept current).
 - HMR and disposal come free: listeners and registrations are Cordis effects.
 - Waterfall semantics (call `next()` or short-circuit) are non-obvious and must be taught — documented in AGENTS.md and covered by composition tests.
-- The loop must be defensive: plugin exceptions are contained at turn level, steering from any seam is never stranded (regression-tested).
+- The loop must be defensive: plugin exceptions are contained at turn level, steering from any extension point is never stranded (regression-tested).
diff --git a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
index aa3db53d64..40edfa1ada 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md
@@ -10,14 +10,14 @@ Status: implemented
 
 ## 决策
 
-纯 Cordis 事件分类体系。agent loop（智能体循环）的扩展 seam 是带类型的事件，具有明确的分发模式：
+纯 Cordis 事件分类体系。agent loop（智能体循环）的扩展点是带类型的事件，具有明确的分发模式：
 
 - **waterfall（瀑布式事件）**（around-middleware）：插件可变换、短路、恢复或包装：`agent/pre-step`、`agent/request`、`agent/request-error`、`tools/pre-execute`、`tools/execute`、`tools/post-execute`、`llm/stream`、`system-prompt/assemble`。
 - **serial**（按监听器顺序依次 await）：用于 `agent/turn-stopping` 等有序检查点。
 - **parallel**（await 扇出）：每个监听器都必须获得独立执行的机会：`session/flush` 持久性检查点。
 - **emit**（同步 fire-and-forget）：用于通知：inbox 转换、生命周期、错误，以及受错误隔离的 `tools/result` 观测；该观测接收不可变的最终结果。轮次与步骤边界由持久会话事件拥有。
 
-事件词汇定义在接口包中（dsh-agent 声明 agent/* 事件）；`@deepseek-ai/dsh-agent-loop` 是唯一的具体循环插件，且自身可替换——外部不得依赖它。
+事件词汇定义在约定包中（`dsh-agent` 声明 `agent/*` 事件）；`@deepseek-ai/dsh-agent-loop` 是唯一的具体循环插件，且自身可替换——外部不得依赖它。
 
 ## 曾考虑的替代方案
 
@@ -28,4 +28,4 @@ Status: implemented
 - 每个 MVP 功能都映射到一个监听器（[功能→机制映射](../../../../docs/cookbook/extension-cookbook.md#the-feature--mechanism-map)是证明义务，保持更新）。
 - HMR 与 dispose 无需额外工作：监听器和注册均为 Cordis effect。
 - waterfall 语义（调用 `next()` 或短路）不直观，需要教学——在 AGENTS.md 中记录，并由组合测试覆盖。
-- 循环必须具备防御性：插件异常在轮次级别被隔离，任何 seam 发出的 steering（中途引导）永远不会被搁置（有回归测试保障）。
+- 循环必须具备防御性：插件异常在轮次级别被隔离，任何扩展点发出的 steering（中途引导）永远不会被搁置（有回归测试保障）。
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
index 4a8f0149e2..ccf15a5c1e 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.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 .agents/notes/implemented/architecture/2026-06-13-capability-seams.md
-2026-06-13-capability-seams.md: 1bad79a9d6d46e56afba862521403ee7c921ba21
-2026-06-13-capability-seams.zh.md: a44913539eed800f82d3f270fef05be17f524a2c
+2026-06-13-capability-seams.md: ca5071cff1b26ba3b89537a73f40d7ecbde4b2bb
+2026-06-13-capability-seams.zh.md: 7790124b980e0525705c2db398802ea6a418685a
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
index 1bad79a9d6..ca5071cff1 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md
@@ -1,4 +1,4 @@
-# Agent Note: Capability seams — interface / implementation / consumer split
+# Agent Note: Capability seams — Service Definition / Service provider / Consumer roles
 
 Status: implemented
 
@@ -12,25 +12,25 @@ This is distinct from "who provides vs. needs a capability at runtime", which Co
 
 ## Decision
 
-A swappable capability is **three packages**:
+A swappable capability has **three roles**:
 
-1. **Interface** — an abstract service + the vocabulary types, owning the `ctx.<key>` and depending only on its vocabulary dependencies (e.g. `dsh-bash`: `BashExecutor`, `BashRunResult`, `BashProcess`).
-2. **Implementation** — a concrete subclass loaded as a plugin (e.g. `dsh-bash-local`: subprocesses, process-group kills, spill-file truncation). Sandboxed/remote backends are sibling packages implementing the same interface.
-3. **Consumer** — what the model and plugins see (e.g. `dsh-tool-bash`: the `bash` schema, with background handles registered into the generic task runtime). Consumers `inject` the interface key and never import implementation types.
+1. **Service Definition** — the Cordis `Service` and vocabulary types owning `ctx.<key>` and depending only on the vocabulary the contract needs (e.g. `dsh-bash`: `BashExecutor`, `BashRunResult`, `BashProcess`). A definition may be an abstract class or a concrete registry service; it is never a TypeScript `interface`.
+2. **Service provider** — a plugin that supplies or registers an implementation (e.g. `dsh-bash-local`: subprocesses, process-group kills, spill-file truncation). Sandboxed and remote providers are sibling packages implementing or registering against the same Service Definition.
+3. **Consumer** — what the model and plugins program against (e.g. `dsh-tool-bash`: the `bash` schema, with background handles registered into the generic task runtime). Consumers inject the service key and never import provider-specific types.
 
-Implementation and consumer then evolve independently: a sandboxed executor replaces `dsh-bash-local` without touching a tool schema.
+Service providers and Consumers then evolve independently: a sandboxed executor replaces `dsh-bash-local` without touching a tool schema.
 
-The split is not mandatory when the parts are genuinely one concern: the LLM seam folds interface + consumer into `dsh-llm` (the consumer is the loop itself, not a swappable schema surface) with adapters as the implementation packages. Don't split preemptively — a capability with one conceivable implementation and one consumer stays one package until a second appears.
+Roles normally use separate packages when they evolve independently, but the split is not mandatory when the roles are genuinely one concern: the LLM seam folds Service Definition and Consumer into `dsh-llm` (the Consumer is the loop itself, not a swappable schema surface) with adapters as Service provider packages. Don't split preemptively — a capability with one conceivable provider and one Consumer stays one package until a second appears.
 
 ## Terminology: "seam" names the trio, not the interface
 
-A **seam** is the whole capability — the three roles together: a **Service Definition** (the Cordis `Service` that owns `ctx.<key>` and the vocabulary; an abstract class such as `BashExecutor`, or a concrete registry such as `WebService`), one or more **Service providers** (implementations that register a backend), and a **Consumer** (the model- or plugin-facing surface). `packages/bash` is the canonical example — `dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`. The interface package alone is the *Service Definition*, one member — not the seam. The Service Definition is never a TypeScript `interface`; where prose must name it, use the class name or `abstract class`, never `interface`. Reserving "seam" strictly for the trio and realigning the many existing "the X seam" usages is deferred to a follow-up; the [glossary](../../../../docs/glossary.md#capability-seam) is the canonical entry.
+A **seam** is the whole capability — the three roles together: a **Service Definition** (the Cordis `Service` that owns `ctx.<key>` and the vocabulary), one or more **Service providers**, and one or more **Consumers**. `packages/bash` is the canonical example — `dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`. A package may own multiple roles, but one role alone is not the seam. The term "seam" is reserved for this complete capability; name a constituent by its role, class, service, contract, or extension point. The [glossary](../../../../docs/glossary.md#capability-seam) is the canonical entry.
 
 ## Alternatives considered
 
-- **One combined package** — rejected because it recouples the three rates of change the split exists to separate (the whole point).
-- **`@cordisjs/plugin-capability`** — a different axis entirely: it is a permission/capability-*security* service (named permissions with inheritance, tested against a session via `ctx.capability.test`), a candidate for the deferred permissions/sandbox work on the `tools/pre-execute` deny/ask seam, NOT a mechanism for swapping implementations. Confusing the two ("capability") is the trap this Agent Note names.
+- **Always combine the roles** — rejected because it recouples independently changing Service Definitions, providers, and Consumers.
+- **`@cordisjs/plugin-capability`** — a different axis entirely: it is a permission/capability-*security* service (named permissions with inheritance, tested against a session via `ctx.capability.test`), a candidate for the deferred permissions/sandbox work on the `tools/pre-execute` deny/ask gate, NOT a mechanism for swapping implementations. Confusing the two ("capability") is the trap this Agent Note names.
 
 ## Consequences
 
-More packages and more boilerplate per capability (a `package.json`/`tsconfig`/README trio, the inject wiring). Bought: implementations and consumers ship and version independently, and a new backend never risks the model-facing contract. The rule is documented in [AGENTS.md](../../../../AGENTS.md) § Conventions ("Capability seams are three packages") and [architecture.md](../../../../docs/architecture.md) § "Capability seams"; the bash trio is the reference template. When to fold vs. split is a judgment call the architecture doc spells out — this Agent Note records *why* the default is to split.
+Separating roles adds packages and boilerplate (`package.json`, `tsconfig`, README, and injection wiring). In return, Service providers and Consumers ship and version independently, and a new backend never risks the model-facing contract. [AGENTS.md](../../../../AGENTS.md) and [architecture.md](../../../../docs/architecture.md) carry the rule; the bash trio is the reference template. This Agent Note records why independently changing roles normally split while genuinely shared concerns may remain folded.
diff --git a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
index a44913539e..7790124b98 100644
--- a/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 能力 seam——接口／实现／消费方三分
+# Agent Note: 能力 seam——Service Definition / Service provider / Consumer 角色
 
 Status: implemented
 
@@ -12,25 +12,25 @@ harness 具有可替换的能力：当前是 bash 执行，未来会有沙箱化
 
 ## 决策
 
-一项可替换的能力由**三个包**构成：
+一项可替换的能力包含**三个角色**：
 
-1. **接口**——一个抽象服务加词汇类型，拥有 `ctx.<key>`，仅依赖其词汇依赖（例如 `dsh-bash`：`BashExecutor`、`BashRunResult`、`BashProcess`）。
-2. **实现**——一个具体子类，以插件形式加载（例如 `dsh-bash-local`：子进程、进程组 kill、spill 文件截断）。沙箱化／远程后端是实现同一接口的兄弟包。
-3. **消费方**——模型和插件看到的内容（例如 `dsh-tool-bash`：`bash` schema，后台句柄注册到通用任务运行时）。消费方 `inject` 接口键，从不导入实现类型。
+1. **Service Definition**——拥有 `ctx.<key>` 的 Cordis `Service` 和词汇类型，仅依赖约定所需的词汇（例如 `dsh-bash`：`BashExecutor`、`BashRunResult`、`BashProcess`）。Service Definition 可以是抽象类，也可以是具体的注册表服务；绝不是 TypeScript `interface`。
+2. **Service provider**——提供或注册实现的插件（例如 `dsh-bash-local`：子进程、进程组 kill、spill 文件截断）。沙箱化和远程 Service provider 是依据同一 Service Definition 实现或注册的兄弟包。
+3. **Consumer**——模型和插件编程所面向的内容（例如 `dsh-tool-bash`：`bash` schema，后台句柄注册到通用任务运行时）。Consumer 注入服务键，从不导入 Service provider 特有的类型。
 
-实现与消费方由此独立演进：沙箱化执行器替换 `dsh-bash-local` 时无需触碰任何工具 schema。
+Service provider 与 Consumer 由此独立演进：沙箱化执行器替换 `dsh-bash-local` 时无需触碰任何工具 schema。
 
-当各部分确实属于同一个关注点时，三分并非强制：LLM（大语言模型） seam 将接口 + 消费方合并为 `dsh-llm`（消费方是 agent loop（智能体循环）本身，而非可替换的 schema 接口），适配器作为实现包。不要预防性地拆分——如果一项能力只有一种可设想的实现和一个消费方，就保持为一个包，直到出现第二种实现或第二个消费方。
+当角色独立演进时，通常使用不同的包；但当各角色确实属于同一个关注点时，并非必须拆分：LLM（大语言模型） seam 将 Service Definition 和 Consumer 合并为 `dsh-llm`（Consumer 是 agent loop（智能体循环）本身，而非可替换的 schema 接口），适配器作为 Service provider 包。不要预防性地拆分——如果一项能力只有一种可设想的 Service provider 和一个 Consumer，就保持为一个包，直到出现第二个。
 
 ## 术语：seam 指三者组合，而非接口
 
-一个 **seam** 是完整的能力——三个角色合在一起：**Service Definition**（拥有 `ctx.<key>` 和词汇的 Cordis `Service`；可以是 `BashExecutor` 这样的抽象类，也可以是 `WebService` 这样的具体注册表）、一个或多个 **Service provider**（注册后端的实现）和 **Consumer**（面向模型或插件的表面）。`packages/bash` 是规范范例——`dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`。接口包本身只是 *Service Definition*，是其中一个成员——不是 seam。Service Definition 从不是 TypeScript `interface`；在正文必须命名它时，使用类名或 `abstract class`，永远不要用 `interface`。严格把「seam」保留给三者组合，并校准现有大量「X seam」用法的工作推迟到后续；[术语表](../../../../docs/glossary.md#capability-seam)是规范条目。
+一个 **seam** 是完整的能力——三个角色合在一起：**Service Definition**（拥有 `ctx.<key>` 和词汇的 Cordis `Service`）、一个或多个 **Service provider**，以及一个或多个 **Consumer**。`packages/bash` 是规范范例——`dsh-bash` / `dsh-bash-local`+`dsh-bash-sandbox` / `dsh-tool-bash`。一个包可以承担多个角色，但单个角色本身不是 seam。「seam」一词严格保留给这种完整能力；命名其中一个组成部分时，应使用其角色、类、服务、约定或扩展点。[术语表](../../../../docs/glossary.md#capability-seam)是规范条目。
 
 ## 曾考虑的替代方案
 
-- **单一合并包**：否决。因为它重新耦合了三分设计本要分离的三种变化速率（这正是拆分的意义所在）。
-- **`@cordisjs/plugin-capability`**：这是完全不同的维度。它是一个权限／能力*安全*服务（具名权限加继承，通过 `ctx.capability.test` 对会话进行检测），是延后的权限/沙箱工作（`tools/pre-execute` deny/ask seam）的候选方案，不是替换实现的机制。混淆这两个「能力」概念正是本 Agent Note 所指出的陷阱。
+- **始终合并各角色**：否决。因为它会重新耦合独立变化的 Service Definition、Service provider 和 Consumer。
+- **`@cordisjs/plugin-capability`**：这是完全不同的维度。它是一个权限／能力*安全*服务（具名权限加继承，通过 `ctx.capability.test` 对会话进行检测），是延后的权限/沙箱工作（`tools/pre-execute` deny/ask 门）的候选方案，不是替换实现的机制。混淆这两个「能力」概念正是本 Agent Note 所指出的陷阱。
 
 ## 后果
 
-每项能力需要更多包和更多样板代码（一组 `package.json`/`tsconfig`/README，加上 inject 接线）。换来的是：实现与消费方独立发布和版本管理，新后端永远不会波及面向模型的约定。该规则记录在 [AGENTS.md](../../../../AGENTS.md) § Conventions（「Capability seams are three packages」）和 [architecture.md](../../../../docs/architecture.md) §「Capability seams」中；bash 三件套是参考模板。何时合并、何时拆分是一个判断问题，架构文档对此有详细说明——本 Agent Note 记录的是*为什么*默认选择拆分。
+分离角色会增加包和样板代码（`package.json`、`tsconfig`、README 和注入接线）。换来的是：Service provider 与 Consumer 独立发布和版本管理，新后端永远不会波及面向模型的约定。[AGENTS.md](../../../../AGENTS.md) 和 [architecture.md](../../../../docs/architecture.md) 载有这项规则；bash 三件套是参考模板。本 Agent Note 记录为什么独立变化的角色通常需要拆分，而确实共享的关注点可以保持合并。
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
index bead51ff09..f2b2982bc1 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.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 .agents/notes/implemented/architecture/2026-06-14-session-persistence.md
-2026-06-14-session-persistence.md: 00e129e57c7144fd62eec26f5854ee21dec4e964
-2026-06-14-session-persistence.zh.md: df03dce6bd978f10deb64b8d75ae0685dabab7cd
+2026-06-14-session-persistence.md: 46fd3755a3c35bd342119fb59b560775a679f740
+2026-06-14-session-persistence.zh.md: f29b192ec9814de2a183599bcfc0a4a0c301b31e
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
index 00e129e57c..46fd3755a3 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
@@ -12,7 +12,7 @@ The [event-sourced model](2026-06-11-event-sourced-sessions.md) makes the append
 
 ## Decision
 
-Persistence is an abstract **capability seam** ([capability seams](2026-06-13-capability-seams.md), the `dsh-bash` template), not loop or core logic:
+Persistence is a **capability seam** with an abstract Service Definition ([capability seams](2026-06-13-capability-seams.md), the `dsh-bash` template), not loop or core logic:
 
 1. **Interface** (`dsh-session-persistence`, `ctx.sessionPersistence`) — an abstract `SessionPersistence` service: `locate`/`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`/`list`/`listSnapshots`. Its persisted unit IS the existing `SessionEvent` (`{ type, seq, time, data }`), reused verbatim — no conversion type.
 2. **Implementation** (`dsh-session-persistence-jsonl`) — an append-only logical JSONL log per session: a `SessionHeader` line followed by storage records that losslessly represent the contiguous `SessionEvent` stream. Eligible `assistant/chunk` delta runs use packed rows by default; [checksummed Zstandard frames](2026-07-19-zstandard-jsonl-session-logs.md) are the default physical encoding, with raw lines configurable.
@@ -22,7 +22,7 @@ Key choices recorded here because they are durable, contested, and surprising:
 - **The canonical durable log persists every `SessionEvent` losslessly, including `assistant/chunk`.** JSONL storage may encode a consecutive delta run as one packed row, but logical readers reconstruct the exact event boundaries, sequence numbers, and timestamps. `deriveMessages()` skips chunks, and a chunk-filtered rollout (Codex's `policy.rs`) is tempting — but `seq = log.length` and validation of `events[i].seq === i` require a *contiguous* logical log; filtering chunks out would leave holes and break both the contract and resume. A chunk-filtered projection is possible later as a derived view with its own renumbering, but it is NOT the canonical log.
 - **Append-only; a crashed turn is closed, never truncated.** Flushed events are never rewritten. The [semantic checkpoint policy](../bug-fix/2026-07-21-semantic-session-checkpoints.md) drains the request before model dispatch, a recorded top-level call before tool dispatch, and the complete response/result batch after a step; the loop drains the final turn boundary. Because one interrupted turn may contain substantial valid work, cold inspection preserves its contiguous, parseable events and adds risk-classified error results for unanswered assistant calls, a missing `step/end`, and `turn/end` with `{ kind: 'interrupted' }` to the in-memory logical view. `prepare` or `load` commits those closers before returning a recoverable view; the synthetic results keep resumed provider transcripts valid. Only an incomplete final record is discarded during committed repair; a parse error or sequence gap at or before the last real `turn/end` is corruption and makes the session unloadable.
 - **File backend canonical, DB backend a proven drop-in.** `SessionEvent` maps 1:1 onto a row `(session_id, seq, type, time, data)` — `append` is INSERT (in a transaction asserting the contiguous-seq contract), and reads use SELECT … ORDER BY seq. `dsh-session-persistence-sqlite` is exactly this: a `SessionPersistence` subclass with no interface change (opencode runs this exact shape on SQLite/WAL), and it passes the same `runPersistenceContract` suite as the JSONL backend — so the contract holds both backends to identical semantics (lazy materialization, logical interrupted-turn closure, single committed repair, contiguous-seq), expressed once over file bytes and once over rows. Its database carries a dedicated application id and monotonic schema version. A pristine file creates all tables and stamps both header values in one transaction; an unversioned file with any user-defined schema object or application identity, a foreign current-version identity, and every non-current version reject before journal-mode mutation.
-- **Metadata is out-of-log.** Format version, cwd, and lineage are storage concerns, not replayable conversation state, so they live in a `SessionHeader` owned by `dsh-session` and attached to a `Session` via a new readonly `session.header` — never in `SessionEventMap`, never reaching `deriveMessages()`. `createdAt` is non-negative safe-integer Unix epoch milliseconds: live creation and persistence registration reject fractional values, JSONL validates the decoded header, and SQLite stores it in a strict `INTEGER` column. The alternative (a merge-extensible `session/meta` event as log line 0) was rejected: an in-log event would ride along with a seeded/forked session for free, but metadata is not replayable state, so the explicit out-of-log header seam is the cleaner cost. (The header was originally split into an immutable `SessionHeader` plus a mutable `SessionSummary` whose union was `SessionMeta`; the mutable summary was later removed as dead state — see [Drop the mutable session summary](../simplification/2026-06-19-drop-mutable-session-summary.md).)
+- **Metadata is out-of-log.** Format version, cwd, and lineage are storage concerns, not replayable conversation state, so they live in a `SessionHeader` owned by `dsh-session` and attached to a `Session` via a new readonly `session.header` — never in `SessionEventMap`, never reaching `deriveMessages()`. `createdAt` is non-negative safe-integer Unix epoch milliseconds: live creation and persistence registration reject fractional values, JSONL validates the decoded header, and SQLite stores it in a strict `INTEGER` column. The alternative (a merge-extensible `session/meta` event as log line 0) was rejected: an in-log event would ride along with a seeded/forked session for free, but metadata is not replayable state, so the explicit out-of-log header boundary is the cleaner cost. (The header was originally split into an immutable `SessionHeader` plus a mutable `SessionSummary` whose union was `SessionMeta`; the mutable summary was later removed as dead state — see [Drop the mutable session summary](../simplification/2026-06-19-drop-mutable-session-summary.md).)
 - **`ctx.agents.create()` and `ctx.agents.resume()` are async factories; resume additionally crosses the persistence boundary.** `ctx.agents.resume({ resumeSessionId })` obtains the exact unpublished Session through `ctx.sessionPersistence.prepare()`, publishes it under the persisted id, and continues its projections. The [Session preparation decision](2026-08-05-session-preparation.md) owns reuse between history inspection and resume. The agent-loop does NOT hard-inject `sessionPersistence` (that would pend non-persistent demos forever); `resume` rejects with a clear error when it is absent.
 
 ## Alternatives considered
@@ -33,4 +33,4 @@ Format versioning: the header carries a `version`; cold reads reject any non-cur
 
 ## Consequences
 
-Two new packages and the metadata seam in `dsh-session` (`session.header`, the `create(id?, options?)` signature). Bought: durable resume/fork, a read/replay path, crash tolerance, and host-side session access over the existing event-sourced log, with the backend swappable behind one interface. The reusable `runPersistenceContract` suite holds every backend to the same append-only, contiguous-seq, lazy-materialization, logical-recovery, integer-metadata, and serializability semantics. Persisting the full logical log also settles event fidelity: every `assistant/chunk` survives exactly even when JSONL packs several into one storage row. SQLite initialization either commits its complete owned schema and header identity or leaves no partial schema to strand on the next open.
+Two new packages and the metadata contract in `dsh-session` (`session.header`, the `create(id?, options?)` signature). Bought: durable resume/fork, a read/replay path, crash tolerance, and host-side session access over the existing event-sourced log, with the backend swappable behind one interface. The reusable `runPersistenceContract` suite holds every backend to the same append-only, contiguous-seq, lazy-materialization, logical-recovery, integer-metadata, and serializability semantics. Persisting the full logical log also settles event fidelity: every `assistant/chunk` survives exactly even when JSONL packs several into one storage row. SQLite initialization either commits its complete owned schema and header identity or leaves no partial schema to strand on the next open.
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
index df03dce6bd..f29b192ec9 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-持久化是一个抽象的**能力 seam**（[能力 seam](2026-06-13-capability-seams.md)，`dsh-bash` 模板），而非循环或核心逻辑：
+持久化是一个具有抽象 Service Definition 的**能力 seam**（[能力 seam](2026-06-13-capability-seams.md)，`dsh-bash` 模板），而非循环或核心逻辑：
 
 1. **接口**（`dsh-session-persistence`，`ctx.sessionPersistence`）：一个抽象的 `SessionPersistence` 服务，提供 `locate`/`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`/`list`/`listSnapshots`。其持久化单元就是现有的 `SessionEvent`（`{ type, seq, time, data }`），原样复用，无转换类型。
 2. **实现**（`dsh-session-persistence-jsonl`）：每个会话一个仅追加的逻辑 JSONL 日志：先是一行 `SessionHeader`，随后是无损表示连续 `SessionEvent` 流的存储记录。符合条件的 `assistant/chunk` 增量连续段默认使用打包行；[带校验和的 Zstandard 帧](2026-07-19-zstandard-jsonl-session-logs.md)是默认物理编码，也可通过配置使用原始行。
@@ -20,10 +20,10 @@ Status: implemented
 以下关键选择记录于此，因为它们长期有效、存在争议且出人意料：
 
 - **规范的持久日志无损保留每个 `SessionEvent`，包括 `assistant/chunk`。** JSONL 存储可以将一段连续的增量事件编码为一条打包行，但逻辑读取方会重建精确的事件边界、序号与时间戳。`deriveMessages()` 跳过分片，而过滤分片的方案（Codex 的 `policy.rs`）很有吸引力，但 `seq = log.length` 以及 `events[i].seq === i` 验证要求*连续*的逻辑日志；过滤掉分片会留下空洞，同时破坏约定和恢复功能。基于分片过滤的投影可以作为派生视图在后续实现（带有自己的重新编号），但它不是规范日志。
-- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些收尾事件；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
-- **文件后端为规范实现，数据库后端为经过验证的直接替换。** `SessionEvent` 1:1 映射到一行 `(session_id, seq, type, time, data)`：`append` 是 INSERT（在一个断言连续 seq 约定成立的事务中），读取使用 SELECT … ORDER BY seq。`dsh-session-persistence-sqlite` 正是如此：一个 `SessionPersistence` 子类，接口无变化（opencode 在 SQLite/WAL 上运行的正是这个形状），且通过与 JSONL 后端相同的 `runPersistenceContract` 测试套件。该约定以相同的语义约束两个后端（惰性物化、逻辑关闭中断轮次、修复只提交一次、连续 seq），一次表达在文件字节上，一次表达在数据库行上。其数据库拥有专用的 application id 与单调递增的 schema 版本。系统会在一个事务中为全新文件创建所有表并写入这两个 header 值；未版本化文件若带有任何用户定义的 schema 对象或应用标识、当前版本文件若带有外部应用标识，以及任何非当前版本文件，都会在修改日志模式之前被拒绝。
-- **元数据在日志之外。** 格式版本、cwd 和谱系是存储关注点，不是可回放的对话状态，因此它们存放在 `dsh-session` 拥有的 `SessionHeader` 中，并通过新的只读属性 `session.header` 附加到 `Session` 上——永远不进入 `SessionEventMap`，永远不到达 `deriveMessages()`。`createdAt` 是以 Unix epoch 毫秒表示的非负安全整数：运行时创建和持久化注册会拒绝小数值，JSONL 会验证解码后的 header，SQLite 则将其存入严格的 `INTEGER` 列。替代方案（一个可合并扩展的 `session/meta` 事件作为日志第 0 行）被否决：日志内事件会自然随 seed/fork 的会话携带，但元数据不是可回放状态，因此显式的日志外 header seam 是更清晰的取舍。（header 最初被拆分为不可变的 `SessionHeader` 加可变的 `SessionSummary`，二者的联合类型为 `SessionMeta`；可变 summary 后来因属于死状态而被移除——见 [移除可变会话摘要](../simplification/2026-06-19-drop-mutable-session-summary.md)。）
-- **`ctx.agents.create()` 和 `ctx.agents.resume()` 是异步工厂；恢复还跨越持久化边界。** `ctx.agents.resume({ resumeSessionId })` 通过 `ctx.sessionPersistence.prepare()` 取得原本那个尚未发布的会话，以持久化 id 发布该会话，并延续其投影。[会话准备决策](2026-08-05-session-preparation.md)负责历史检查与恢复之间的复用。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
+- **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些 closer；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
+- **文件后端为规范实现，数据库后端为经过验证的直接替换。** `SessionEvent` 1:1 映射到一行 `(session_id, seq, type, time, data)`：`append` 是 INSERT（在一个断言连续 seq 约定的事务中），读取使用 SELECT … ORDER BY seq。`dsh-session-persistence-sqlite` 正是如此：一个 `SessionPersistence` 子类，接口无变化（opencode 在 SQLite/WAL 上运行的正是这个形状），且通过与 JSONL 后端相同的 `runPersistenceContract` 测试套件。该约定以相同的语义约束两个后端（惰性物化、逻辑关闭中断轮次、修复只提交一次、连续 seq），一次表达在文件字节上，一次表达在数据库行上。其数据库拥有专用的 application id 与单调递增的 schema 版本。系统会在一个事务中为全新文件创建所有表并写入这两个 header 值；未版本化文件若带有任何用户定义的 schema 对象或应用标识、当前版本文件若带有外部应用标识，以及任何非当前版本文件，都会在修改日志模式之前被拒绝。
+- **元数据在日志之外。** 格式版本、cwd 和谱系是存储关注点，不是可回放的对话状态，因此它们存放在 `dsh-session` 拥有的 `SessionHeader` 中，并通过新的只读属性 `session.header` 附加到 `Session` 上——永远不进入 `SessionEventMap`，永远不到达 `deriveMessages()`。`createdAt` 是以 Unix epoch 毫秒表示的非负安全整数：运行时创建和持久化注册会拒绝小数值，JSONL 会验证解码后的 header，SQLite 则将其存入严格的 `INTEGER` 列。替代方案（一个可合并扩展的 `session/meta` 事件作为日志第 0 行）被否决：日志内事件会自然随 seed/fork 的会话携带，但元数据不是可回放状态，因此显式的日志外 header 边界是更清晰的取舍。（header 最初被拆分为不可变的 `SessionHeader` 加可变的 `SessionSummary`，二者的联合类型为 `SessionMeta`；可变 summary 后来因属于死状态而被移除——见 [移除可变会话摘要](../simplification/2026-06-19-drop-mutable-session-summary.md)。）
+- **`ctx.agents.create()` 和 `ctx.agents.resume()` 是异步工厂；恢复还跨越持久化边界。** `ctx.agents.resume({ resumeSessionId })` 通过 `ctx.sessionPersistence.prepare()` 取得精确的未发布 Session，以持久化 id 发布它，并继续其投影。[Session 准备阶段决策](2026-08-05-session-preparation.md)定义历史检查与恢复之间的复用。agent loop（智能体循环）不会硬注入 `sessionPersistence`（那样会让非持久化的演示永远挂起）；当它不存在时，`resume` 会以明确的错误拒绝。
 
 ## 曾考虑的替代方案
 
@@ -33,4 +33,4 @@ Status: implemented
 
 ## 后果
 
-新增两个包，以及 `dsh-session` 中的元数据 seam（`session.header`，`create(id?, options?)` 签名）。收益：持久恢复/fork、读取/回放路径、崩溃容忍，以及基于现有事件溯源日志的宿主侧会话访问，后端可在同一接口下替换。可复用的 `runPersistenceContract` 测试套件以相同的仅追加、连续 seq、惰性物化、逻辑恢复、整数元数据与可序列化语义约束每个后端。持久化完整的逻辑日志还确定了事件保真度：即使 JSONL 将多个 `assistant/chunk` 打包到一条存储行中，每个事件也会精确保留。SQLite 初始化要么提交完整的自有 schema 与 header 标识，要么不留下任何会使下次打开受阻的部分 schema。
+新增两个包，以及 `dsh-session` 中的元数据约定（`session.header`，`create(id?, options?)` 签名）。收益：持久恢复/fork、读取/回放路径、崩溃容忍，以及基于现有事件溯源日志的宿主侧会话访问，后端可在同一接口下替换。可复用的 `runPersistenceContract` 测试套件以相同的仅追加、连续 seq、惰性物化、逻辑恢复、整数元数据与可序列化语义约束每个后端。持久化完整的逻辑日志还确定了事件保真度：即使 JSONL 将多个 `assistant/chunk` 打包到一条存储行中，每个事件也会精确保留。SQLite 初始化要么提交完整的自有 schema 与 header 标识，要么不留下任何会使下次打开受阻的部分 schema。
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index 4511cefb31..159483fb73 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.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 .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
-2026-06-17-filesystem-capability-seam.md: 7436d2a9402c76f17c7d6571eb489a86e550ebfb
-2026-06-17-filesystem-capability-seam.zh.md: a96d513d7f4fa793ebb3427e3f7b290862d0d5e9
+2026-06-17-filesystem-capability-seam.md: 35fe5148ca44f733aa0a354e215cd1d77eb8180e
+2026-06-17-filesystem-capability-seam.zh.md: 998b5ead48dcaf168ad48c8ad7a403a7e3b3e955
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
index 7436d2a940..35fe5148ca 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
@@ -26,9 +26,9 @@ Filesystem access is a first-class capability seam following [the capability-sea
 2. `@deepseek-ai/dsh-fs-local` (`packages/fs/fs-local`) provides the first implementation, backed by the local filesystem.
 3. `@deepseek-ai/dsh-tool-fs` (`packages/fs/tool-fs`) provides the model-facing `read`, `write`, and `edit` tools over `ctx.fs`, and is the executor that dispatches the `fs/*` events.
 
-The consumer package depends only on the interface package, never on `dsh-fs-local`. A deployment that wants a different backend loads a different provider for `ctx.fs` without changing the tool schemas or model-facing prompt guidance.
+The Consumer package depends only on the Service Definition package, never on `dsh-fs-local`. A deployment that wants a different backend loads a different provider for `ctx.fs` without changing the tool schemas or model-facing prompt guidance.
 
-The read-before-write/edit and observed-state policy is a fourth package, `@deepseek-ai/dsh-fs-policy` (`packages/fs/fs-policy`), contributed through the `fs/*` event gate rather than living on `ctx.fs`; a deployment loading `dsh-tool-fs` also loads `dsh-fs-policy` to get read-before-write/edit. This Agent Note established the three-package seam; the split of policy off the provider base class is decided by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md), and its realization as an event-gate plugin (not a method service) by [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md). This document is updated to describe that landed four-package shape.
+The read-before-write/edit and observed-state policy is a fourth package, `@deepseek-ai/dsh-fs-policy` (`packages/fs/fs-policy`), contributed through the `fs/*` event gate rather than living on `ctx.fs`; a deployment loading `dsh-tool-fs` also loads `dsh-fs-policy` to get read-before-write/edit. This Agent Note established the three-package boundary; the split of policy off the provider base class is decided by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md), and its realization as an event-gate plugin (not a method service) by [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md). This document is updated to describe that landed four-package shape.
 
 The first backend is deliberately local-only: `dsh-fs-local` implements `ctx.fs` against the host filesystem. Future sibling backends can provide sandboxed, remote, virtual, or project-scoped filesystems behind the same interface.
 
@@ -53,7 +53,7 @@ The filesystem seam uses the same dependency direction as the bash trio:
 
 `@deepseek-ai/dsh-tool-fs` depends on `@deepseek-ai/dsh-fs`, `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-system-prompt`, and `cordis`. It registers model-facing tools and prompt sections. It must not import `node:fs`, `node:path`, or `@deepseek-ai/dsh-fs-local`; filesystem execution always goes through `ctx.fs`. If the implementation needs concrete agent or session helper types, those dependencies belong in `tool-fs`; they must not leak back into `dsh-fs`.
 
-The root `tool-fs` plugin registers the full filesystem tool suite (`read`, `write`, and `edit`) by composing the per-tool registration helpers. It injects `fs` and never imports an implementation package.
+The root `tool-fs` plugin registers the full filesystem tool suite (`read`, `write`, and `edit`) by composing the per-tool registration helpers. It injects `fs` and never imports a Service provider package.
 
 ## `ctx.fs` contract
 
@@ -68,7 +68,7 @@ The interface covers these semantic operations:
 - Create or replace a UTF-8 text file.
 - Edit an existing UTF-8 text file by literal replacement.
 
-The provider seam also carries the freshness hooks that policy builds on — but the observed-state store and owner derivation live in the `dsh-fs-policy` plugin, not on `ctx.fs`:
+The provider contract also carries the freshness hooks that policy builds on — but the observed-state store and owner derivation live in the `dsh-fs-policy` plugin, not on `ctx.fs`:
 
 - The backend mints an opaque `version` token per target (in `stat` and in every read/mutation outcome).
 - `writeText`/`editText` take an OPTIONAL version expectation: omit it for an unconditional bare-provider mutation, or supply it to guard the mutation inside the backend's atomic critical section.
@@ -127,7 +127,7 @@ The root plugin registers the full suite by composing the per-tool registration
 
 ## Testing
 
-Tests follow the package boundary, not only the user-visible tools: the service seam in `dsh-fs`; real filesystem behavior through the `ctx.fs` interface in `dsh-fs-local` (resolution, symlinks, streaming, binary/UTF-8 rejection, unconditional and version-guarded writes, literal-edit semantics, line-ending preservation, structured `FsError` codes); the consumer surface in `dsh-tool-fs` against the real local provider (mock only the model/clock, never the collaborator); and integration through `ctx.tools.execute()` with and without `dsh-fs-policy`, world-verified by reading files back from disk rather than trusting either the canonical value or rendered content. The observed-state/owner-derivation policy is tested in `dsh-fs-policy`, not here.
+Tests follow the package boundary, not only the user-visible tools: the service contract in `dsh-fs`; real filesystem behavior through the `ctx.fs` interface in `dsh-fs-local` (resolution, symlinks, streaming, binary/UTF-8 rejection, unconditional and version-guarded writes, literal-edit semantics, line-ending preservation, structured `FsError` codes); the consumer surface in `dsh-tool-fs` against the real local provider (mock only the model/clock, never the collaborator); and integration through `ctx.tools.execute()` with and without `dsh-fs-policy`, world-verified by reading files back from disk rather than trusting either the canonical value or rendered content. The observed-state/owner-derivation policy is tested in `dsh-fs-policy`, not here.
 
 The defensive-pattern classes this repo has been bitten by are pinned directly:
 
@@ -139,7 +139,7 @@ The defensive-pattern classes this repo has been bitten by are pinned directly:
 ## Alternatives considered
 
 - **Model-facing tools directly over `node:fs`** — the tool package would own execution policy, path resolution, atomic writes, text decoding, and edit semantics at once, coupling the three independently-changing concerns the Problem names and churning schemas on any backend swap.
-- **One combined `dsh-fs-tools` package** — the pre-seam shape; rejected for the same interface/implementation/consumer split as bash, and the combined name never became public surface.
+- **One combined `dsh-fs-tools` package** — the pre-seam shape; rejected for the same Service Definition / Service provider / Consumer split as bash, and the combined name never became public surface.
 - **Observed-state on `ctx.fs`** — the shape this Agent Note first landed; superseded by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) and [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md): a sandboxed/remote backend must not inherit model-facing observation policy, so the provider keeps only the version token and the optional version-guarded mutation.
 
 ## Consequences
@@ -152,7 +152,7 @@ The defensive-pattern classes this repo has been bitten by are pinned directly:
 
 **Edit semantics are race-prone by nature.** Literal edit is a read-modify-write operation; the guard is the backend's atomic mutation critical section plus the optional version expectation, so concurrent edits settle deterministically — one wins, the other gets `FS_STALE_VERSION`.
 
-**Observed state does not belong on `ctx.fs`.** Recording what an execution context has seen is workflow policy, not raw filesystem I/O. This Agent Note first placed it inside the filesystem seam; the split-fs-seam Agent Note then established that a sandboxed/remote backend should not inherit model-facing observation policy, and moved it into the `dsh-fs-policy` plugin. The provider seam keeps only what write/edit safety genuinely needs at the storage layer — a backend-minted version token and an optional version-guarded mutation — while the policy plugin owns owner derivation, observed-state, and read-before-edit gating over the `fs/*` events.
+**Observed state does not belong on `ctx.fs`.** Recording what an execution context has seen is workflow policy, not raw filesystem I/O. This Agent Note first placed it inside the filesystem seam; the split-fs-seam Agent Note then established that a sandboxed/remote backend should not inherit model-facing observation policy, and moved it into the `dsh-fs-policy` plugin. The provider contract keeps only what write/edit safety genuinely needs at the storage layer — a backend-minted version token and an optional version-guarded mutation — while the policy plugin owns owner derivation, observed-state, and read-before-edit gating over the `fs/*` events.
 
 **The `resolve`-then-operate shape costs an extra round-trip per call.** Each tool may resolve a path to an `FsTarget` and then issue the read/write/edit as a separate `ctx.fs` call. For the local backend this is negligible (resolution is in-memory path normalization), but a remote/sandboxed backend may turn each step into its own request, so a single `read` can become two network round-trips. Backends where the round-trip matters can cache or fold resolution internally while preserving the observable contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
index a96d513d7f..998b5ead48 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -26,9 +26,9 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 2. `@deepseek-ai/dsh-fs-local`（`packages/fs/fs-local`）提供第一个实现，以本地文件系统为后端。
 3. `@deepseek-ai/dsh-tool-fs`（`packages/fs/tool-fs`）通过 `ctx.fs` 提供面向模型的 `read`、`write` 和 `edit` 工具，是分发 `fs/*` 事件的执行器。
 
-消费方包仅依赖接口包，从不依赖 `dsh-fs-local`。需要不同后端的部署只需为 `ctx.fs` 加载不同的提供方，无需改动工具 schema 或面向模型的提示词引导。
+Consumer 包仅依赖 Service Definition 包，从不依赖 `dsh-fs-local`。需要不同后端的部署只需为 `ctx.fs` 加载不同的提供方，无需改动工具 schema 或面向模型的提示词引导。
 
-读后写/编辑与观测状态策略是第四个包 `@deepseek-ai/dsh-fs-policy`（`packages/fs/fs-policy`），通过 `fs/*` 事件门控贡献，而非挂在 `ctx.fs` 上；加载 `dsh-tool-fs` 的部署同时加载 `dsh-fs-policy` 以获得读后写/编辑能力。本 Agent Note 确立了由三个包构成的 seam；策略从提供方基类拆出的决策由 [拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 做出，其以事件门控插件（而非方法服务）实现的方式由 [事件门控 Agent Note](2026-06-26-file-context-as-event-gate.md) 做出。本文已更新为描述最终落地的四包形态。
+读后写/编辑与观测状态策略是第四个包 `@deepseek-ai/dsh-fs-policy`（`packages/fs/fs-policy`），通过 `fs/*` 事件门控贡献，而非挂在 `ctx.fs` 上；加载 `dsh-tool-fs` 的部署同时加载 `dsh-fs-policy` 以获得读后写/编辑能力。本 Agent Note 确立了由三个包构成的边界；策略从提供方基类拆出的决策由 [拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 做出，其以事件门控插件（而非方法服务）实现的方式由 [事件门控 Agent Note](2026-06-26-file-context-as-event-gate.md) 做出。本文已更新为描述最终落地的四包形态。
 
 第一个后端有意仅限本地：`dsh-fs-local` 基于宿主文件系统实现 `ctx.fs`。未来的兄弟后端可在同一接口之后提供沙箱、远程、虚拟或项目作用域的文件系统。
 
@@ -53,7 +53,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 `@deepseek-ai/dsh-tool-fs` 依赖 `@deepseek-ai/dsh-fs`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-system-prompt` 和 `cordis`。它注册面向模型的工具和提示词段落。它禁止导入 `node:fs`、`node:path` 或 `@deepseek-ai/dsh-fs-local`；文件系统执行始终通过 `ctx.fs`。如果实现需要具体的 agent 或会话辅助类型，这些依赖属于 `tool-fs`；它们禁止回漏到 `dsh-fs` 中。
 
-根 `tool-fs` 插件通过组合各工具的注册辅助函数来注册完整的文件系统工具套件（`read`、`write` 和 `edit`）。它注入 `fs`，从不导入实现包。
+根 `tool-fs` 插件通过组合各工具的注册辅助函数来注册完整的文件系统工具套件（`read`、`write` 和 `edit`）。它注入 `fs`，从不导入 Service provider 包。
 
 ## `ctx.fs` 约定
 
@@ -68,7 +68,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 - 创建或替换一个 UTF-8 文本文件。
 - 通过字面替换编辑一个已有的 UTF-8 文本文件。
 
-提供方 seam 还携带策略所依赖的新鲜度钩子——但观测状态存储和 owner 推导位于 `dsh-fs-policy` 插件中，而非 `ctx.fs` 上：
+提供方约定还携带策略所依赖的新鲜度钩子——但观测状态存储和 owner 推导位于 `dsh-fs-policy` 插件中，而非 `ctx.fs` 上：
 
 - 后端为每个目标铸造一个不透明的 `version` 令牌（在 `stat` 以及每次读取/变更结果中）。
 - `writeText`/`editText` 接受一个可选的版本期望：省略它表示无条件的裸提供方变更；提供它则在后端的原子临界区内守护变更。
@@ -127,7 +127,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 ## 测试
 
-测试遵循包边界，而不仅是用户可见的工具：`dsh-fs` 中的服务 seam；`dsh-fs-local` 中通过 `ctx.fs` 接口测试的真实文件系统行为（解析、符号链接、流式传输、二进制/UTF-8 拒绝、无条件和版本守护的写入、字面编辑语义、行尾保留、结构化 `FsError` 错误码）；`dsh-tool-fs` 中基于真实本地提供方的消费方接口（只 mock 模型/时钟，从不 mock 协作者）；以及通过 `ctx.tools.execute()` 在有和没有 `dsh-fs-policy` 的情况下进行集成测试，通过从磁盘回读文件来验证世界状态，既不信任规范值，也不信任渲染内容。观测状态/owner 推导策略在 `dsh-fs-policy` 中测试，不在此处。
+测试遵循包边界，而不仅是用户可见的工具：`dsh-fs` 中的服务约定；`dsh-fs-local` 中通过 `ctx.fs` 接口测试的真实文件系统行为（解析、符号链接、流式传输、二进制/UTF-8 拒绝、无条件和版本守护的写入、字面编辑语义、行尾保留、结构化 `FsError` 错误码）；`dsh-tool-fs` 中基于真实本地提供方的消费方接口（只 mock 模型/时钟，从不 mock 协作者）；以及通过 `ctx.tools.execute()` 在有和没有 `dsh-fs-policy` 的情况下进行集成测试，通过从磁盘回读文件来验证世界状态，既不信任规范值，也不信任渲染内容。观测状态/owner 推导策略在 `dsh-fs-policy` 中测试，不在此处。
 
 本仓库曾踩过的防御性模式类别被直接固定：
 
@@ -139,7 +139,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 ## 曾考虑的替代方案
 
 - **面向模型的工具直接基于 `node:fs`**：工具包将同时承担执行策略、路径解析、原子写入、文本解码和编辑语义，耦合问题部分所列的三个独立变化的关注点，且任何后端替换都会搅动 schema。
-- **单一合并包 `dsh-fs-tools`**：seam 之前的形态；以与 bash 相同的接口/实现/消费方拆分理由否决，且合并名称从未成为公开接口。
+- **单一合并包 `dsh-fs-tools`**：seam 之前的形态；以与 bash 相同的 Service Definition / Service provider / Consumer 拆分理由否决，且合并名称从未成为公开接口。
 - **观测状态放在 `ctx.fs` 上**：本 Agent Note 最初落地的形态；被 [拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 和 [事件门控 Agent Note](2026-06-26-file-context-as-event-gate.md) 取代：沙箱/远程后端不应继承面向模型的观测策略，因此提供方只保留版本令牌和可选的版本守护变更。
 
 ## 后果
@@ -152,7 +152,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 **编辑语义天然易受竞争影响。** 字面编辑是读-改-写操作；守护手段是后端的原子变更临界区加上可选的版本期望，因此并发编辑确定性地收敛——一个赢，另一个得到 `FS_STALE_VERSION`。
 
-**观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本 Agent Note 最初将其放在文件系统 seam 内部；拆分文件系统 seam Agent Note 随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方 seam 只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
+**观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本 Agent Note 最初将其放在文件系统 seam 内部；拆分文件系统 seam Agent Note 随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方约定只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
 
 **`resolve` 然后操作的形态每次调用多一次往返。** 每个工具可能先将路径解析为 `FsTarget`，再以单独的 `ctx.fs` 调用发起读取/写入/编辑。对本地后端来说这可以忽略（解析是内存中的路径规范化），但远程/沙箱后端可能将每步变成独立请求，使单次 `read` 变为两次网络往返。往返开销重要的后端可以在内部缓存或折叠解析，同时保持可观测约定不变。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml
similarity index 64%
rename from .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml
rename to .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.i18n.yaml
index 70c9f791f4..4ea64d5530 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.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 .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md
-2026-06-18-agent-lifecycle-and-ownership-seams.md: 93247a6da7446a5a67db33423d2b766ce4cf3308
-2026-06-18-agent-lifecycle-and-ownership-seams.zh.md: e17650c7789764dfb4240132f5903795e6f86381
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
+2026-06-18-agent-lifecycle-and-ownership-contracts.md: ad334d30afcaf1864a1ea3dd42f3c5b7d157603b
+2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md: b9240969c9e952c1b38cbd4c088853005e156067
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
similarity index 72%
rename from .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md
rename to .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
index 93247a6da7..ad334d30af 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md
@@ -1,16 +1,16 @@
-# Agent Note: Agent lifecycle and ownership seams
+# Agent Note: Agent lifecycle and ownership contracts
 
 Status: implemented
 
-English | [中文](2026-06-18-agent-lifecycle-and-ownership-seams.zh.md)
+English | [中文](2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md)
 
 ## Problem
 
-Several ACP and tool-bash limitations were symptoms of the same missing seam: plugins could create or resume agents through `ctx.agents`, but they could not own and dispose one agent independently, and long-running bash tasks carried no stable owner in the executor itself. ACP aborted and awaited agents on disconnect but could not unregister just that session's agent; `session/cancel` could not cancel queued-but-not-yet-started work; and `tool-bash` kept task ownership in a plugin-local `Map`, so an HMR reload could make an old task look unowned.
+Several ACP and tool-bash limitations were symptoms of the same missing ownership contract: plugins could create or resume agents through `ctx.agents`, but they could not own and dispose one agent independently, and long-running bash tasks carried no stable owner in the executor itself. ACP aborted and awaited agents on disconnect but could not unregister just that session's agent; `session/cancel` could not cancel queued-but-not-yet-started work; and `tool-bash` kept task ownership in a plugin-local `Map`, so an HMR reload could make an old task look unowned.
 
 ## Decision
 
-Three seams: the queue-aware cancel, the `AgentHandle` disposer, and the bash owner token.
+Three contract changes: the queue-aware cancel, the `AgentHandle` disposer, and the bash owner token.
 
 ### 1. Queue-aware `Agent.cancel(cause?)`
 
@@ -22,9 +22,9 @@ A new `cancel()` verb on the `Agent` interface — the single public stop primit
 
 **Teardown ORDER is load-bearing for durability**, and the implementation folds the session lifecycle into the agent's SINGLE composite cordis effect (`SessionStore.prepare`/`enter`/`announce`, replacing a sibling-effect split). A fiber unload disposes sibling effects concurrently (`Promise.all`), which would race removing the session store's append publication hooks against the loop's closing `session/flush` and drop the closing `turn/end`; inside one effect the disposers run as an ordered LIFO chain (loop stopped + `await agent.done` BEFORE the session detaches), so the loop's final flush is captured on BOTH the handle's `dispose()` and a fiber unload. The contained `agent/disposed` and `session/disposed` notifications cannot reject the chain or skip later teardown.
 
-### 3. Bash owner token in the seam
+### 3. Bash owner token in the Service Definition
 
-Background-task ownership moved from a `tool-bash` plugin-local `Map<string, Agent>` into the executor. `BashExecRequest` gains an optional `owner?: string`; the resolved `BashExecSpec` carries it as required-but-nullable `owner: string | undefined` (a forgotten owner is a visible `undefined`, never a silently-absent property). The executor stores the token on its task and exposes it via a new `BashExecutor.ownerOf(id): string | undefined` seam (NOT on the public `BashTask` — one read path, no redundant API). `tool-bash` deletes its `Map` entirely: it stamps `exec.agent?.id` (the shared registry/session id) as the owner at `start`, and `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token with `!== undefined` semantics (an empty-string token is still a real owner). The completion notice finds the live agent by scanning `ctx.get('agents')?.list()` for `agent.id === ownerToken` (read via `ctx.get` — `onTaskDone` runs on the bash fiber, a foreign fiber, where the `ctx.agents` proxy would throw). Because ownership now lives on the task in the executor (disposed with the `dsh-bash` fiber), it SURVIVES a `tool-bash` HMR reload — closing the old `XXX(tool-bash-owner-hmr)` gap. (The `onTaskDone` listener is still effect-scoped to `tool-bash`'s `apply`, so a completion landing during the reload gap still drops its one notice — the pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
+Background-task ownership moved from a `tool-bash` plugin-local `Map<string, Agent>` into the executor. `BashExecRequest` gains an optional `owner?: string`; the resolved `BashExecSpec` carries it as required-but-nullable `owner: string | undefined` (a forgotten owner is a visible `undefined`, never a silently-absent property). The executor stores the token on its task and exposes it via a new `BashExecutor.ownerOf(id): string | undefined` method (NOT on the public `BashTask` — one read path, no redundant API). `tool-bash` deletes its `Map` entirely: it stamps `exec.agent?.id` (the shared registry/session id) as the owner at `start`, and `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token with `!== undefined` semantics (an empty-string token is still a real owner). The completion notice finds the live agent by scanning `ctx.get('agents')?.list()` for `agent.id === ownerToken` (read via `ctx.get` — `onTaskDone` runs on the bash fiber, a foreign fiber, where the `ctx.agents` proxy would throw). Because ownership now lives on the task in the executor (disposed with the `dsh-bash` fiber), it SURVIVES a `tool-bash` HMR reload — closing the old `XXX(tool-bash-owner-hmr)` gap. (The `onTaskDone` listener is still effect-scoped to `tool-bash`'s `apply`, so a completion landing during the reload gap still drops its one notice — the pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
 
 ## Verification
 
@@ -37,11 +37,11 @@ These invariants hold and are pinned by tests:
 
 ## Session owner tokens are unique among live agents
 
-The bash owner-token comparison relies on the shared `Agent.id`/`SessionId` being unique among live agents. Concurrent same-ID operations may both prepare privately, but publication enters the session and agent in order; `SessionStore.enter()` rejects a duplicate live session id, and every losing transaction rolls its private state back. A programmatic caller therefore cannot publish two live agents with one session token. The access *policy* (token comparison) stays in `tool-bash` (the consumer); the bash seam stores only an opaque `owner` string and never interprets it — the correct interface/implementation/consumer split.
+The bash owner-token comparison relies on the shared `Agent.id`/`SessionId` being unique among live agents. Concurrent same-ID operations may both prepare privately, but publication enters the session and agent in order; `SessionStore.enter()` rejects a duplicate live session id, and every losing transaction rolls its private state back. A programmatic caller therefore cannot publish two live agents with one session token. The access *policy* (token comparison) stays in `tool-bash` (the Consumer); the bash capability keeps `owner` opaque and never interprets it — the correct Service Definition / Service provider / Consumer split.
 
 ## Alternatives considered
 
-- **A public `BashTask.owner` field** instead of the `BashExecutor.ownerOf(id)` seam — rejected: one read path, no redundant API.
+- **A public `BashTask.owner` field** instead of the `BashExecutor.ownerOf(id)` Service Definition method — rejected: one read path, no redundant API.
 - **Sibling cordis effects for the agent's session lifecycle** — rejected: a fiber unload disposes sibling effects concurrently (`Promise.all`), racing removal of the store-owned append publication hooks against the loop's closing `session/flush`; the single composite effect's ordered LIFO chain is what captures the closing `turn/end` on both disposal paths.
 - **A separate step-only `abort()` beside `cancel()`** — shipped originally, then removed as unused; `cancel()` is the single public stop primitive ([the public-stop-surface Agent Note](../simplification/2026-06-20-public-agent-stop-surface.md)).
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md
similarity index 71%
rename from .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
rename to .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md
index e17650c778..b9240969c9 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.zh.md
@@ -1,16 +1,16 @@
-# Agent Note: Agent 生命周期与所有权 seam
+# Agent Note: Agent 生命周期与所有权约定
 
 Status: implemented
 
-[English](2026-06-18-agent-lifecycle-and-ownership-seams.md) | 中文
+[English](2026-06-18-agent-lifecycle-and-ownership-contracts.md) | 中文
 
 ## 问题
 
-ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个缺失 seam 的症状：插件可以通过 `ctx.agents` 创建或恢复 agent（智能体），但无法独立拥有和 dispose（资源释放）单个 agent，而长时间运行的 bash 任务在执行器中也没有稳定的所有者。ACP 在断连时中止并等待 agent，却无法仅注销该会话的 agent；`session/cancel` 无法取消已入队但尚未开始的工作；`tool-bash` 将任务所有权保存在插件本地的 `Map` 中，因此一次 HMR（热模块替换）重载就可能让旧任务看起来无主。
+ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个所有权约定缺失的症状：插件可以通过 `ctx.agents` 创建或恢复 agent（智能体），但无法独立拥有和 dispose（资源释放）单个 agent，而长时间运行的 bash 任务在执行器中也没有稳定的所有者。ACP 在断连时中止并等待 agent，却无法仅注销该会话的 agent；`session/cancel` 无法取消已入队但尚未开始的工作；`tool-bash` 将任务所有权保存在插件本地的 `Map` 中，因此一次 HMR（热模块替换）重载就可能让旧任务看起来无主。
 
 ## 决策
 
-三个 seam：队列感知的取消、`AgentHandle` 释放器，以及 bash 所有者令牌。
+三项约定变更：队列感知的取消、`AgentHandle` 释放器，以及 bash 所有者令牌。
 
 ### 1. 队列感知的 `Agent.cancel(cause?)`
 
@@ -22,9 +22,9 @@ ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个缺失 se
 
 **拆除顺序对持久性至关重要**，实现将会话生命周期折叠进 agent 的单个复合 Cordis effect（`SessionStore.prepare`/`enter`/`announce`，取代兄弟 effect 拆分）。fiber 卸载会并发释放兄弟 effect（`Promise.all`），这会让会话存储的 append 发布钩子移除与循环关闭时的 `session/flush` 竞争，从而丢失关闭的 `turn/end`；在一个 effect 内，释放器作为有序的 LIFO 链运行（停止循环 + `await agent.done` 在会话分离之前），因此无论 handle 的 `dispose()` 还是 fiber 卸载，都会捕获循环的最终刷写。被隔离的 `agent/disposed` 和 `session/disposed` 通知无法拒绝该链或跳过后续拆除。
 
-### 3. Bash seam 中的所有者令牌
+### 3. Service Definition 中的 Bash 所有者令牌
 
-后台任务所有权从 `tool-bash` 插件本地的 `Map<string, Agent>` 移入执行器。`BashExecRequest` 新增可选的 `owner?: string`；解析后的 `BashExecSpec` 将其作为必需但可空的 `owner: string | undefined` 携带（被遗忘的 owner 是可见的 `undefined`，而非静默缺失的属性）。执行器把 token 存在任务上，并通过新的 `BashExecutor.ownerOf(id): string | undefined` seam 暴露它（不放在公开的 `BashTask` 上——只有一条读取路径，没有冗余 API）。`tool-bash` 完全删除其 `Map`：它在 `start` 时将 `exec.agent?.id`（共享的注册表/会话 id）盖章为 owner，`bash_output`/`bash_kill` 则以 `!== undefined` 语义把 `ctx.bash.ownerOf(id)` 与调用方 token 比较（空字符串 token 仍是真实 owner）。完成通知通过扫描 `ctx.get('agents')?.list()` 查找 `agent.id === ownerToken` 的存活 agent（经 `ctx.get` 读取——`onTaskDone` 运行在 bash fiber 这一外部 fiber 上，直接使用 `ctx.agents` proxy 会抛异常）。由于所有权现在保存在执行器的任务上（随 `dsh-bash` fiber dispose），它能跨越 `tool-bash` HMR 重载，关闭旧的 `XXX(tool-bash-owner-hmr)` 缺口。（`onTaskDone` 监听器仍受 `tool-bash` 的 `apply` effect 约束，因此落在重载间隙的完成仍会丢失一条通知——既有的重载间隙丢失——但所有权隔离本身已经不受 HMR 影响。）
+后台任务所有权从 `tool-bash` 插件本地的 `Map<string, Agent>` 移入执行器。`BashExecRequest` 新增可选的 `owner?: string`；解析后的 `BashExecSpec` 将其作为必需但可空的 `owner: string | undefined` 携带（被遗忘的 owner 是可见的 `undefined`，而非静默缺失的属性）。执行器把 token 存在任务上，并通过新的 `BashExecutor.ownerOf(id): string | undefined` 方法暴露它（不放在公开的 `BashTask` 上——只有一条读取路径，没有冗余 API）。`tool-bash` 完全删除其 `Map`：它在 `start` 时将 `exec.agent?.id`（共享的注册表/会话 id）盖章为 owner，`bash_output`/`bash_kill` 则以 `!== undefined` 语义把 `ctx.bash.ownerOf(id)` 与调用方 token 比较（空字符串 token 仍是真实 owner）。完成通知通过扫描 `ctx.get('agents')?.list()` 查找 `agent.id === ownerToken` 的存活 agent（经 `ctx.get` 读取——`onTaskDone` 运行在 bash fiber 这一外部 fiber 上，直接使用 `ctx.agents` proxy 会抛异常）。由于所有权现在保存在执行器的任务上（随 `dsh-bash` fiber dispose），它能跨越 `tool-bash` HMR 重载，关闭旧的 `XXX(tool-bash-owner-hmr)` 缺口。（`onTaskDone` 监听器仍受 `tool-bash` 的 `apply` effect 约束，因此落在重载间隙的完成仍会丢失一条通知——既有的重载间隙丢失——但所有权隔离本身已经不受 HMR 影响。）
 
 ## 验证
 
@@ -37,11 +37,11 @@ ACP（Agent Client Protocol）与 tool-bash 的若干限制是同一个缺失 se
 
 ## 会话所有者令牌在存活 agent 中唯一
 
-bash 所有者 token 比较依赖共享的 `Agent.id`/`SessionId` 在存活 agent 中唯一。并发的同 ID 操作可以都私下准备，但发布时会依次登记会话和 agent；`SessionStore.enter()` 拒绝重复的存活会话 id，每个失败事务都回滚自己的私有状态。因此程序化调用方无法发布两个共享同一会话 token 的存活 agent。访问*策略*（token 比较）留在消费方 `tool-bash`；bash seam 只存储不透明的 `owner` 字符串且从不解释它——这是正确的接口/实现/消费方拆分。
+bash 所有者 token 比较依赖共享的 `Agent.id`/`SessionId` 在存活 agent 中唯一。并发的同 ID 操作可以都私下准备，但发布时会依次登记会话和 agent；`SessionStore.enter()` 拒绝重复的存活会话 id，每个失败事务都回滚自己的私有状态。因此程序化调用方无法发布两个共享同一会话 token 的存活 agent。访问*策略*（token 比较）留在 Consumer `tool-bash`；bash 能力只存储不透明的 `owner` 字符串且从不解释它——这是正确的 Service Definition / Service provider / Consumer 拆分。
 
 ## 曾考虑的替代方案
 
-- **公开的 `BashTask.owner` 字段**而非 `BashExecutor.ownerOf(id)` seam：否决。一条读取路径即可，无需冗余 API。
+- **公开的 `BashTask.owner` 字段**而非 `BashExecutor.ownerOf(id)` Service Definition 方法：否决。一条读取路径即可，无需冗余 API。
 - **为 agent 的会话生命周期使用兄弟 Cordis effect**：否决。fiber 卸载时并发释放兄弟 effect（`Promise.all`），store 拥有的 append 发布钩子的移除与循环的关闭 `session/flush` 产生竞争；单一复合 effect 的有序 LIFO 链才能在两条释放路径上都捕获关闭的 `turn/end`。
 - **在 `cancel()` 之外另设一个仅中止步骤的 `abort()`**：最初发布过，后因无人使用而移除；`cancel()` 是唯一的公开停止原语（见[公开停止接口 Agent Note](../simplification/2026-06-20-public-agent-stop-surface.md)）。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index 84edacb9dc..702a9035d5 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.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 .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
-2026-06-18-shared-persistence-write-coordinator.md: 12131ebf8380fb8ba816618f0cbaf72cb004623a
-2026-06-18-shared-persistence-write-coordinator.zh.md: 0a7fbf351171d305b3b6245832a0b35a283c7c1d
+2026-06-18-shared-persistence-write-coordinator.md: 1d373317664f605e5164e2eb6980b8fa7c6b4e05
+2026-06-18-shared-persistence-write-coordinator.zh.md: 607f1fe68d1404a56c84848c8561cf8749daab0b
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
index 12131ebf83..1d37331766 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-18-shared-persistence-write-coordinator.zh.md)
 
 ## Problem
 
-`dsh-session-persistence-jsonl` and `dsh-session-persistence-sqlite` intentionally prove the same `SessionPersistence` contract over different storage media, but their write-path orchestration was duplicated: per-session state, `session/created` adoption, backend-specific prefix reads, write-behind control, per-id operation serialization, HMR seeding, and dispose drains. The pure seed-prefix collision and serializability guards had already moved into the seam package; the remaining orchestration was still correctness-heavy and received the same fixes twice. Only the storage primitives (write bytes vs. INSERT rows) differed.
+`dsh-session-persistence-jsonl` and `dsh-session-persistence-sqlite` intentionally prove the same `SessionPersistence` contract over different storage media, but their write-path orchestration was duplicated: per-session state, `session/created` adoption, backend-specific prefix reads, write-behind control, per-id operation serialization, HMR seeding, and dispose drains. The pure seed-prefix collision and serializability guards had already moved into the Service Definition package; the remaining orchestration was still correctness-heavy and received the same fixes twice. Only the storage primitives (write bytes vs. INSERT rows) differed.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
index 0a7fbf3511..607f1fe68d 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -6,13 +6,13 @@ Status: implemented
 
 ## 问题
 
-`dsh-session-persistence-jsonl` 与 `dsh-session-persistence-sqlite` 有意在不同存储介质上证明同一份 `SessionPersistence` 约定，但它们重复实现了写入路径编排：每会话状态、`session/created` 接管、后端特定的前缀读取、write-behind 控制、按 id 串行执行操作、HMR（热模块替换）种子注入与 dispose（资源释放）排空。纯粹的种子前缀碰撞检查与可序列化守卫已迁入 seam 包；剩余的编排仍然对正确性要求很高，且同样的修复被应用了两次。唯一的差异在于存储原语（写字节 vs. INSERT 行）。
+`dsh-session-persistence-jsonl` 与 `dsh-session-persistence-sqlite` 有意在不同存储介质上证明同一份 `SessionPersistence` 约定，但它们重复实现了写入路径编排：每会话状态、`session/created` 接管、后端特定的前缀读取、write-behind 控制、按 id 串行执行操作、HMR（热模块替换）种子注入与 dispose（资源释放）排空。纯粹的种子前缀碰撞检查与可序列化守卫已迁入 Service Definition 包；剩余的编排仍然对正确性要求很高，且同样的修复被应用了两次。唯一的差异在于存储原语（写字节 vs. INSERT 行）。
 
 ## 决策
 
 将一个后端无关的 `PersistenceCoordinator` 提取到 `dsh-session-persistence` 中。协调器统一拥有编排逻辑；每个第一方后端组合一个协调器实例（`new PersistenceCoordinator(ctx, this)`），实现一个小型 `PersistenceBackend` 钩子接口，并将其有状态的公开方法（`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`）委托给协调器。由后端拥有的元数据与修订版本列举会绕过协调器。
 
-组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不修改状态的逻辑检查，以及通过 `load` 实现的默认准备回退。
+组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不可变逻辑检查，以及通过 `load` 实现的默认准备回退。
 
 协调器为每个存活的 `Session` 实例持有一个生命周期条目：初始化，加上一个包私有写入控制器，后者负责待处理事件、固定批处理截止时间、活跃写入、失败保留和共享 flush 屏障。每个 `session/event` 都进入这条有界写入路径，`session/flush` 则绕过等待以观察完全停稳。控制器归并由 [flush 控制器简化](../simplification/2026-07-23-collapse-persistence-flush-state.md)定义；调度节奏由[有界批处理决策](2026-08-08-bounded-session-persistence-write-batching.md)定义。
 
@@ -44,4 +44,4 @@ Status: implemented
 
 ## 后果
 
-协调器增加了一层间接、一个不透明的 torn marker、脱离会话生命周期的退役任务，以及有界的已准备 Session 状态，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查、准备与不修改状态的检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时不会提交中断 closers；复用、预留与发布由 [Session 准备阶段决策](2026-08-05-session-preparation.md)定义。新后端只需实现存储原语，而无需复制有界写入生命周期。
+协调器增加了一层间接、一个不透明的 torn marker、脱离会话生命周期的退役任务，以及有界的已准备 Session 状态，但将此前每个后端重复的、对正确性要求很高的编排逻辑集中到一处。会话 dispose 仍是仅观察事件，因此会话所有者不会等待持久化退役；协调器会收容失败、在存活控制器中保留待处理事件，并以后端 teardown 为完全停稳边界。其钩子面保持窄小：标识校验、接管、碰撞检查、准备与不可变检查共用 `loadStored`；物化保持在 `appendBatch` 内原子完成；列举绕过协调器。读模型使用 `inspect` 而非 `load`，因此观察已持久化但仍开放的轮次时不会提交中断 closers；复用、预留与发布由 [Session 准备阶段决策](2026-08-05-session-preparation.md)定义。新后端只需实现存储原语，而无需复制有界写入生命周期。
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
index 0af0c0038b..f906aa4336 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.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 .agents/notes/implemented/architecture/2026-06-20-branded-ids.md
-2026-06-20-branded-ids.md: 7c0b7ca89418e8312ec728223dac519f70edc3ed
-2026-06-20-branded-ids.zh.md: 039953754b184af97eb9b4ea3bbb1325d45eda25
+2026-06-20-branded-ids.md: 005706a12769a03e9c8ce66bf631ca0d75ade8b4
+2026-06-20-branded-ids.zh.md: b6b58a8b703d5637a6a5053543193bf9779489ac
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
index 7c0b7ca894..005706a127 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
@@ -12,15 +12,15 @@ The harness brands `CallId` (`packages/llm/llm/src/brand.ts`) and the shared age
 
 The bash **owner token** is the related sub-case: `BashExecRequest.owner?: string` and `BashExecSpec.owner: string | undefined` (`packages/bash/bash/src/types.ts`) are documented as a deliberately *opaque* isolation key, but in every live caller the value IS the owning agent's shared `Agent.id`/`SessionId` (`callerToken = (exec) => exec.agent?.id` in `packages/bash/tool-bash/src/index.ts`) wearing a different seam-local name. It is compared for access control (`owner !== callerToken(exec)`), so a mismatched-but-well-typed string here is a cross-session isolation bug the type system currently cannot catch. This is the shared id alias covered by the [unified agent/session identity decision](../simplification/2026-06-20-unify-agent-and-session-id.md).
 
-**Gap 2 — brand erosion at the seams of the *already-branded* IDs.** Even `CallId` and `SessionId` decay back to bare `string` at exactly the places confusion is most likely: registry/store key types and public method params. Representative sites include the session store, the agent registry (both keyed by the shared `SessionId`), tool-presentation call-id maps, ACP's session records, and the persistence coordinator. A brand that is dropped at a collection key buys nothing on lookups — the value of the existing brands is partly unrealized.
+**Gap 2 — brand erosion at the boundaries of the *already-branded* IDs.** Even `CallId` and `SessionId` decay back to bare `string` at exactly the places confusion is most likely: registry/store key types and public method params. Representative sites include the session store, the agent registry (both keyed by the shared `SessionId`), tool-presentation call-id maps, ACP's session records, and the persistence coordinator. A brand that is dropped at a collection key buys nothing on lookups — the value of the existing brands is partly unrealized.
 
 ## Decision
 
 A type-only change. Brands are zero-cost casts; nothing about runtime behavior, serialization, comparison, or the wire format changes. The work is in three parts, all honoring the existing "not every string" policy.
 
-- **Brand the bash task id.** Add `BashTaskId = Branded<'BashTaskId'>` plus its same-named factory in `packages/bash/bash/src/types.ts` (the package that *owns* the id), importing `Branded` from `@deepseek-ai/dsh-brand` exactly as `SessionId` does. The brand primitive lives in the dependency-free `dsh-brand` utility package precisely so `dsh-bash` can brand its ids by depending on it alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`. Thread it through `BashTask.id`, the `BashExecutor` seam methods (`get`/`ownerOf`/`readOutput`/`kill`), the generation site in `dsh-bash-local` (brand the counter output once, at creation), and the `dsh-tool-bash` validate/access surface (`validateTaskId` returns a `BashTaskId`; `task_id` is branded at the tool boundary where the model's string arrives).
+- **Brand the bash task id.** Add `BashTaskId = Branded<'BashTaskId'>` plus its same-named factory in `packages/bash/bash/src/types.ts` (the package that *owns* the id), importing `Branded` from `@deepseek-ai/dsh-brand` exactly as `SessionId` does. The brand primitive lives in the dependency-free `dsh-brand` utility package precisely so `dsh-bash` can brand its ids by depending on it alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`. Thread it through `BashTask.id`, the `BashExecutor` Service Definition methods (`get`/`ownerOf`/`readOutput`/`kill`), the generation site in `dsh-bash-local` (brand the counter output once, at creation), and the `dsh-tool-bash` validate/access surface (`validateTaskId` returns a `BashTaskId`; `task_id` is branded at the tool boundary where the model's string arrives).
 
-- **Mint a distinct `OwnerToken` brand.** Add `OwnerToken = Branded<'OwnerToken'>` in `packages/bash/bash/src/types.ts`; type `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` as `OwnerToken | undefined`. The `dsh-tool-bash` consumer casts the agent's shared `id` (`SessionId`) into an `OwnerToken` at the boundary — the one place the two vocabularies meet. The bash seam never imports `dsh-session`. (Rationale in the next section.)
+- **Mint a distinct `OwnerToken` brand.** Add `OwnerToken = Branded<'OwnerToken'>` in `packages/bash/bash/src/types.ts`; type `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` as `OwnerToken | undefined`. The `dsh-tool-bash` consumer casts the agent's shared `id` (`SessionId`) into an `OwnerToken` at the boundary — the one place the two vocabularies meet. The bash Service Definition never imports `dsh-session`. (Rationale in the next section.)
 
 - **Stop the brand erosion.** Propagate the existing brands to the `Map` key types and public method params listed under Gap 2 — `Map<SessionId, Session>`, `Map<SessionId, Agent>`, `get(id: SessionId)`, `Map<CallId, …>`, ACP's `SessionId` surface, and the coordinator's `Map<SessionId, …>`. This is the larger mechanical share of the diff and the part that makes the *existing* brands actually load-bearing on lookups, not just on struct fields.
 
@@ -46,7 +46,7 @@ export function OwnerToken(id: string): OwnerToken {
 
 ### Why not typing `owner` as `SessionId`?
 
-The obvious shortcut is to type `owner` as `SessionId` directly — it always *is* one. We reject that. The bash executor seam is a capability seam (interface `dsh-bash`, implementation `dsh-bash-local`, consumer `dsh-tool-bash`) and its owner token is *documented as deliberately opaque*: the executor "never interprets it (no access policy lives in the seam — that is the consumer's job)" (`packages/bash/bash/src/types.ts`). Typing the seam's field as `SessionId` would import `dsh-session`'s vocabulary into a package that must not know what an owner token *means* — it would couple a generic execution backend to the session model and contradict the opaque-token design. A sandboxed or remote executor that replaces `dsh-bash-local` should not inherit a session dependency. The distinct `OwnerToken` brand keeps the seam decoupled: `dsh-bash` knows only "an owner is some opaque branded token," and the `dsh-tool-bash` consumer — which already decides the access policy — is the single boundary that casts its `SessionId` into an `OwnerToken`. The brand still delivers the safety win (you cannot pass a `BashTaskId` or a raw string where an owner is expected) without the coupling.
+The obvious shortcut is to type `owner` as `SessionId` directly — it always *is* one. We reject that. The bash executor seam is a capability seam (Service Definition `dsh-bash`, Service provider `dsh-bash-local`, Consumer `dsh-tool-bash`) and its owner token is *documented as deliberately opaque*: the executor "never interprets it (no access policy lives in the seam — that is the consumer's job)" (`packages/bash/bash/src/types.ts`). Typing the Service Definition's field as `SessionId` would import `dsh-session`'s vocabulary into a package that must not know what an owner token *means* — it would couple a generic execution backend to the session model and contradict the opaque-token design. A sandboxed or remote executor that replaces `dsh-bash-local` should not inherit a session dependency. The distinct `OwnerToken` brand keeps the seam decoupled: `dsh-bash` knows only "an owner is some opaque branded token," and the `dsh-tool-bash` consumer — which already decides the access policy — is the single boundary that casts its `SessionId` into an `OwnerToken`. The brand still delivers the safety win (you cannot pass a `BashTaskId` or a raw string where an owner is expected) without the coupling.
 
 ## Out of scope / possible extensions
 
@@ -60,10 +60,10 @@ Kept deliberately narrow per the "not every string needs a brand" policy. Each o
 
 ## Verification
 
-The landed invariants: `BashTaskId` and `OwnerToken` are defined in `dsh-bash` and threaded end-to-end (executor seam, the `dsh-bash-local` generation site, the `dsh-tool-bash` model-facing surface) with no `dsh-bash` dependency on `dsh-session`; no collection keyed by an in-scope branded id (`CallId`/`SessionId`/`BashTaskId`) is keyed by bare `string`; public method params and exported signatures keep the brand; and brands are constructed via the cast factory at each boundary where a raw string enters (provider call id, ACP session id, model-supplied `task_id`), never as scattered `as` casts.
+The landed invariants: `BashTaskId` and `OwnerToken` are defined in `dsh-bash` and threaded end-to-end (Service Definition, the `dsh-bash-local` generation site, the `dsh-tool-bash` model-facing surface) with no `dsh-bash` dependency on `dsh-session`; no collection keyed by an in-scope branded id (`CallId`/`SessionId`/`BashTaskId`) is keyed by bare `string`; public method params and exported signatures keep the brand; and brands are constructed via the cast factory at each boundary where a raw string enters (provider call id, ACP session id, model-supplied `task_id`), never as scattered `as` casts.
 
 ## Consequences
 
-- **Mechanical churn across two surfaces.** Propagating brands touches the bash seam (interface + impl + consumer) and the ACP session-id surface plus the persistence coordinator. The churn is broad but low-severity: a missed site is a compile error, not a silent bug. The change is observably type-only — no snapshot or e2e behavioral diff. It sits next to the [unified agent/session identity decision](../simplification/2026-06-20-unify-agent-and-session-id.md) because both touch the session-id / owner-token boundary; `OwnerToken` stays distinct from the unified id for the decoupling reason above.
+- **Mechanical churn across two surfaces.** Propagating brands touches the bash seam (Service Definition + Service provider + Consumer) and the ACP session-id surface plus the persistence coordinator. The churn is broad but low-severity: a missed site is a compile error, not a silent bug. The change is observably type-only — no snapshot or e2e behavioral diff. It sits next to the [unified agent/session identity decision](../simplification/2026-06-20-unify-agent-and-session-id.md) because both touch the session-id / owner-token boundary; `OwnerToken` stays distinct from the unified id for the decoupling reason above.
 - **Brands do not validate.** A brand is a confusability guard, not a correctness proof: a *wrong* session id that is still a well-formed string passes the type checker exactly as before. This Agent Note does not close that gap (see Out of scope) — it only stops the *category* error of passing the wrong *kind* of id.
 - **The "where to stop" line stays a judgment call.** Branding `BashTaskId` but not `ToolName`, `OwnerToken` but not `ModelId`, is a taste call about which strings "could plausibly be confused." Reasonable reviewers may want more or fewer; the policy in `brand.ts` is the tie-breaker, and this Agent Note errs toward the ids that are model-facing or used for access control.
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
index 039953754b..b6b58a8b70 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
@@ -12,15 +12,15 @@ harness 使用 `Branded<B> = string & { readonly [BRAND]: B }` 机制，为 `Cal
 
 bash **owner token** 是相关的子情形：`BashExecRequest.owner?: string` 和 `BashExecSpec.owner: string | undefined`（`packages/bash/bash/src/types.ts`）被文档描述为刻意*不透明*的隔离键，但在所有实际调用方中，该值就是所属 agent（智能体）共享的 `Agent.id`/`SessionId`（`callerToken = (exec) => exec.agent?.id`，位于 `packages/bash/tool-bash/src/index.ts`），只是披着另一个 seam 本地名称。它被用于访问控制比较（`owner !== callerToken(exec)`），因此一个不匹配但类型正确的 string 在此处就是跨会话隔离 bug，而当前类型系统无法捕获。这正是[统一 agent/session 标识决策](../simplification/2026-06-20-unify-agent-and-session-id.md)覆盖的共享 id 别名。
 
-**缺口 2：*已经 brand* 的 ID 在 seam 处被侵蚀。** 就连 `CallId` 和 `SessionId` 也恰好在最容易混淆的地方退化为裸 `string`：注册表/store 键类型和公开方法参数。代表性位置包括会话存储、agent 注册表（二者都以共享的 `SessionId` 为键）、工具展示层的 call-id map、ACP（Agent Client Protocol）的会话记录，以及持久化协调器。在集合键处丢弃 brand，会让既有 brand 在查找时毫无价值；它们的价值只实现了一部分。
+**缺口 2：*已经 brand* 的 ID 在边界处被侵蚀。** 就连 `CallId` 和 `SessionId` 也恰好在最容易混淆的地方退化为裸 `string`：注册表/store 键类型和公开方法参数。代表性位置包括会话存储、agent 注册表（二者都以共享的 `SessionId` 为键）、工具展示层的 call-id map、ACP（Agent Client Protocol）的会话记录，以及持久化协调器。在集合键处丢弃 brand，会让既有 brand 在查找时毫无价值；它们的价值只实现了一部分。
 
 ## 决策
 
 纯类型变更。Brand 是零开销 cast；运行时行为、序列化、比较和协议格式（wire format）均不变。工作分三部分，全部遵循既有的「不是每个 string 都需要」策略。
 
-- **为 bash task id 加 brand。** 在 `packages/bash/bash/src/types.ts`（*拥有*该 id 的包）中添加 `BashTaskId = Branded<'BashTaskId'>` 及其同名工厂，从 `@deepseek-ai/dsh-brand` 导入 `Branded`，方式与 `SessionId` 完全一致。brand 原语位于无依赖的 `dsh-brand` 工具包中，正是为了让 `dsh-bash` 仅依赖它就能为自己的 id 加 brand，而无需引入 `dsh-llm`（或 `dsh-session`）来获取 `Branded`。将其贯穿 `BashTask.id`、`BashExecutor` seam 方法（`get`/`ownerOf`/`readOutput`/`kill`）、`dsh-bash-local` 中的生成点（在创建时对计数器输出做一次 brand），以及 `dsh-tool-bash` 的校验/访问面（`validateTaskId` 返回 `BashTaskId`；`task_id` 在模型 string 到达的工具边界处被 brand）。
+- **为 bash task id 加 brand。** 在 `packages/bash/bash/src/types.ts`（*拥有*该 id 的包）中添加 `BashTaskId = Branded<'BashTaskId'>` 及其同名工厂，从 `@deepseek-ai/dsh-brand` 导入 `Branded`，方式与 `SessionId` 完全一致。brand 原语位于无依赖的 `dsh-brand` 工具包中，正是为了让 `dsh-bash` 仅依赖它就能为自己的 id 加 brand，而无需引入 `dsh-llm`（或 `dsh-session`）来获取 `Branded`。将其贯穿 `BashTask.id`、`BashExecutor` Service Definition 方法（`get`/`ownerOf`/`readOutput`/`kill`）、`dsh-bash-local` 中的生成点（在创建时对计数器输出做一次 brand），以及 `dsh-tool-bash` 的校验/访问面（`validateTaskId` 返回 `BashTaskId`；`task_id` 在模型 string 到达的工具边界处被 brand）。
 
-- **铸造独立的 `OwnerToken` brand。** 在 `packages/bash/bash/src/types.ts` 中添加 `OwnerToken = Branded<'OwnerToken'>`；将 `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` 的类型标注为 `OwnerToken | undefined`。`dsh-tool-bash` 消费方在边界处将 agent 共享的 `id`（`SessionId`）cast 为 `OwnerToken`——这是两套词汇唯一交汇的地方。bash seam 从不导入 `dsh-session`。（理由见下一节。）
+- **铸造独立的 `OwnerToken` brand。** 在 `packages/bash/bash/src/types.ts` 中添加 `OwnerToken = Branded<'OwnerToken'>`；将 `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` 的类型标注为 `OwnerToken | undefined`。`dsh-tool-bash` 消费方在边界处将 agent 共享的 `id`（`SessionId`）cast 为 `OwnerToken`——这是两套词汇唯一交汇的地方。bash Service Definition 从不导入 `dsh-session`。（理由见下一节。）
 
 - **阻止 brand 侵蚀。** 将既有 brand 传播到缺口 2 列出的 `Map` 键类型和公开方法参数中：`Map<SessionId, Session>`、`Map<SessionId, Agent>`、`get(id: SessionId)`、`Map<CallId, …>`、ACP 的 `SessionId` surface、协调器的 `Map<SessionId, …>`。这是 diff 中机械量最大的部分，也是让*既有* brand 在查找处真正发挥作用（而不仅仅标注在结构体字段上）的关键。
 
@@ -46,7 +46,7 @@ export function OwnerToken(id: string): OwnerToken {
 
 ### 为什么不把 `owner` 类型标注为 `SessionId`？
 
-显而易见的捷径是直接把 `owner` 类型标注为 `SessionId`——它确实*总是*一个会话 id。我们否决这个方案。bash 执行器 seam 是能力 seam（接口 `dsh-bash`、实现 `dsh-bash-local`、消费方 `dsh-tool-bash`），其 owner token 被*明确记录为刻意不透明*：执行器「从不解释它（seam 中没有访问策略——那是消费方的职责）」（`packages/bash/bash/src/types.ts`）。把 seam 字段类型标注为 `SessionId`，会把 `dsh-session` 的词汇引入一个不应知道 owner token *含义*的包——这会让通用执行后端耦合会话模型，并违背不透明 token 的设计。取代 `dsh-bash-local` 的沙箱或远程执行器不应继承会话依赖。独立的 `OwnerToken` brand 使 seam 保持解耦：`dsh-bash` 只知道「owner 是某种带 brand 的不透明 token」，而已经决定访问策略的 `dsh-tool-bash` 消费方，是把其 `SessionId` cast 为 `OwnerToken` 的唯一边界。该 brand 仍带来安全收益（不能把 `BashTaskId` 或裸 string 传到 owner 位置），且不引入耦合。
+显而易见的捷径是直接把 `owner` 类型标注为 `SessionId`——它确实*总是*一个会话 id。我们否决这个方案。bash 执行器 seam 是能力 seam（Service Definition `dsh-bash`、Service provider `dsh-bash-local`、Consumer `dsh-tool-bash`），其 owner token 被*明确记录为刻意不透明*：执行器「从不解释它（seam 中没有访问策略——那是消费方的职责）」（`packages/bash/bash/src/types.ts`）。把 Service Definition 的字段类型标注为 `SessionId`，会把 `dsh-session` 的词汇引入一个不应知道 owner token *含义*的包——这会让通用执行后端耦合会话模型，并违背不透明 token 的设计。取代 `dsh-bash-local` 的沙箱或远程执行器不应继承会话依赖。独立的 `OwnerToken` brand 使 seam 保持解耦：`dsh-bash` 只知道「owner 是某种带 brand 的不透明 token」，而已经决定访问策略的 `dsh-tool-bash` 消费方，是把其 `SessionId` cast 为 `OwnerToken` 的唯一边界。该 brand 仍带来安全收益（不能把 `BashTaskId` 或裸 string 传到 owner 位置），且不引入耦合。
 
 ## 不在范围内 / 可能的扩展
 
@@ -60,10 +60,10 @@ export function OwnerToken(id: string): OwnerToken {
 
 ## 验证
 
-已落地的不变式：`BashTaskId` 和 `OwnerToken` 定义在 `dsh-bash` 中，并端到端贯穿执行器 seam、`dsh-bash-local` 生成点与 `dsh-tool-bash` 面向模型的 surface，且 `dsh-bash` 未添加对 `dsh-session` 的依赖；没有任何以范围内 brand id（`CallId`/`SessionId`/`BashTaskId`）为键的集合使用裸 `string`；公开方法参数和导出签名保留 brand；每个原始 string 进入的边界（提供方 call id、ACP 会话 id、模型提供的 `task_id`）都通过 cast 工厂构造 brand，而不是散落的 `as` cast。
+已落地的不变式：`BashTaskId` 和 `OwnerToken` 定义在 `dsh-bash` 中，并端到端贯穿 Service Definition、`dsh-bash-local` 生成点与 `dsh-tool-bash` 面向模型的 surface，且 `dsh-bash` 未添加对 `dsh-session` 的依赖；没有任何以范围内 brand id（`CallId`/`SessionId`/`BashTaskId`）为键的集合使用裸 `string`；公开方法参数和导出签名保留 brand；每个原始 string 进入的边界（提供方 call id、ACP 会话 id、模型提供的 `task_id`）都通过 cast 工厂构造 brand，而不是散落的 `as` cast。
 
 ## 后果
 
-- **两个接口面的机械性改动。** 传播 brand 涉及 bash seam（接口 + 实现 + 消费方）以及 ACP 会话 id 接口和持久化协调器。改动面广但严重度低：遗漏的位置是编译错误而非静默 bug。变更可观察地为纯类型变更——无快照或 e2e 行为差异。它与[统一 agent/会话标识决策](../simplification/2026-06-20-unify-agent-and-session-id.md)相邻，因为二者都触及会话 id / owner-token 边界；`OwnerToken` 出于上述解耦理由仍与统一后的 id 保持独立。
+- **两个接口面的机械性改动。** 传播 brand 涉及 bash seam（Service Definition + Service provider + Consumer）以及 ACP 会话 id 接口和持久化协调器。改动面广但严重度低：遗漏的位置是编译错误而非静默 bug。变更可观察地为纯类型变更——无快照或 e2e 行为差异。它与[统一 agent/会话标识决策](../simplification/2026-06-20-unify-agent-and-session-id.md)相邻，因为二者都触及会话 id / owner-token 边界；`OwnerToken` 出于上述解耦理由仍与统一后的 id 保持独立。
 - **Brand 不做校验。** Brand 是混淆防护，不是正确性证明：一个*错误的*会话 id 只要仍是格式正确的 string，就和以前一样能通过类型检查器。本 Agent Note 不关闭这个缺口（见「不在范围内」）——它只阻止这类*类别*错误：传入错误*种类*的 id。
 - **「在哪里停下」仍是判断题。** 为 `BashTaskId` 加 brand 但不为 `ToolName` 加，为 `OwnerToken` 加但不为 `ModelId` 加，是对哪些 string「可能被混淆」的品味判断。合理的评审者可能想要更多或更少；`brand.ts` 中的策略是裁决依据，本 Agent Note 倾向于面向模型或用于访问控制的 id。
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
index ebabaccdbb..6da549618b 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.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 .agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
-2026-06-20-generic-long-running-tool-runtime.md: 8cf6a34c3e4fc042bd73c147d83838734dfc9585
-2026-06-20-generic-long-running-tool-runtime.zh.md: 44241321f6e4da428fe3a6402440af344fd69f10
+2026-06-20-generic-long-running-tool-runtime.md: 0dd49fe60f2c45081973657ff960b780d2d47257
+2026-06-20-generic-long-running-tool-runtime.zh.md: 6e8458aea73536859bf4c81894679d31a5034d3a
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 8cf6a34c3e..0dd49fe60f 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -17,9 +17,9 @@ The `tasks/` package group owns background-task semantics:
 - `@deepseek-ai/dsh-tasks` registers running work as `ctx.tasks` and owns task ids, authorization, snapshots, reads, cancellation, waiting, completion listeners, and cleanup.
 - `@deepseek-ai/dsh-tool-tasks` exposes `task_output`, `task_list`, and `task_kill`, injects completion notices, and supplies the background-task system-prompt guidance.
 
-Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into incremental output and process cancellation; `dsh-tool-subagent` adapts a child run into final output and child disposal. The execution seams remain independent of sessions and the task registry.
+Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into incremental output and process cancellation; `dsh-tool-subagent` adapts a child run into final output and child disposal. The bash and subagent capability seams remain independent of sessions and the task registry.
 
-`TaskService` is the abstract seam in `@deepseek-ai/dsh-tasks`; the process-local registry is `LocalTaskService` in `@deepseek-ai/dsh-tasks-local` (the [task-registry seam Agent Note](2026-07-26-task-registry-seam.md) records that split).
+`TaskService` is the Service Definition in `@deepseek-ai/dsh-tasks`; the process-local provider is `LocalTaskService` in `@deepseek-ai/dsh-tasks-local` (the [task-registry contract Agent Note](2026-07-26-task-registry-seam.md) records that split).
 
 ## Runtime contract
 
@@ -103,7 +103,7 @@ Separate bash and subagent output/stop tools duplicate ids, isolation, cleanup,
 
 ### An immediate abstract task-runtime backend
 
-The current `TaskStart.run()` contract passes in-process callbacks and exact `Agent` objects. A durable backend changes identity, restart, ownership, and observation semantics, so at introduction time the registry stayed one concrete service rather than freezing the wrong boundary. The [task-registry seam Agent Note](2026-07-26-task-registry-seam.md) later separated the contract from the process-local implementation without changing these in-process semantics.
+The current `TaskStart.run()` contract passes in-process callbacks and exact `Agent` objects. A durable backend changes identity, restart, ownership, and observation semantics, so at introduction time the registry stayed one concrete service rather than freezing the wrong boundary. The [task-registry contract Agent Note](2026-07-26-task-registry-seam.md) later separated the contract from the process-local implementation without changing these in-process semantics.
 
 ### Consumer-owned authorization or cleanup events
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
index 44241321f6..6e8458aea7 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
@@ -17,9 +17,9 @@ Status: implemented
 - `@deepseek-ai/dsh-tasks` 将运行中的工作注册为 `ctx.tasks`，并拥有 task id、授权、快照、读取、取消、等待、完成监听器与清理。
 - `@deepseek-ai/dsh-tool-tasks` 暴露 `task_output`、`task_list` 和 `task_kill`，注入完成通知，并提供后台任务的系统提示词指导。
 
-长时间运行工具是生产方。`dsh-tool-bash` 将 `BashProcess` 适配为增量输出与进程取消；`dsh-tool-subagent` 将子运行适配为最终输出与子运行释放。执行 seam 保持独立，不依赖会话或任务注册表。
+长时间运行工具是生产方。`dsh-tool-bash` 将 `BashProcess` 适配为增量输出与进程取消；`dsh-tool-subagent` 将子运行适配为最终输出与子运行释放。bash 与 subagent 能力 seam 保持独立，不依赖会话或任务注册表。
 
-`TaskService` 是 `@deepseek-ai/dsh-tasks` 中的抽象 seam；进程内注册表是 `@deepseek-ai/dsh-tasks-local` 中的 `LocalTaskService`（该拆分记录在[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.md)中）。
+`TaskService` 是 `@deepseek-ai/dsh-tasks` 中的 Service Definition；进程内 Service provider 是 `@deepseek-ai/dsh-tasks-local` 中的 `LocalTaskService`（该拆分记录在[任务注册表约定 Agent Note](2026-07-26-task-registry-seam.md)中）。
 
 ## 运行时约定
 
@@ -103,7 +103,7 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `Bas
 
 ### 立即抽象任务运行时后端
 
-当前 `TaskStart.run()` 约定传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表 seam Agent Note](2026-07-26-task-registry-seam.md)后来在不改变这些进程内语义的前提下，将约定与进程内实现分离。
+当前 `TaskStart.run()` 约定传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表约定 Agent Note](2026-07-26-task-registry-seam.md)后来在不改变这些进程内语义的前提下，将约定与进程内实现分离。
 
 ### 由消费方负责授权或清理事件
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
index 72569c7b6a..16dde8df0e 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.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 .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
-2026-06-21-bounded-llm-request-recovery.md: 8879d77a6f6191d028e321487020de7df91c73ae
-2026-06-21-bounded-llm-request-recovery.zh.md: dfbe0e0afa6dfd131cc2be72682c4de9f3c27c9a
+2026-06-21-bounded-llm-request-recovery.md: 985ac3803b8d35ea9275052946dc2cbb33480a9f
+2026-06-21-bounded-llm-request-recovery.zh.md: 8d845cce797d3a17d1223970186a23ffcece1ec8
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
index 8879d77a6f..985ac3803b 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md
@@ -48,11 +48,11 @@ Adapters extract structured facts before falling back to message inspection. The
 
 The shared transient-code set is intentionally small: adapter mappings for `RATE_LIMIT` and `SERVER`, explicit `TIMEOUT` and `TRANSPORT` codes for remote failures, and `EMPTY_RESPONSE` for a completed provider response with no content blocks. Both adapters classify the last case as an error finish; see [empty model responses are retryable](../bug-fix/2026-07-24-empty-model-response-is-retryable.md). Authentication, quota, invalid request, context overflow, protocol, abort, and unknown failures keep distinct stable codes and are not transient by default. Adding a code requires adapter fixtures and a documented policy decision; it does not require expanding a second failure-class enum.
 
-### Put retry policy on the existing failed-step seam
+### Put retry policy on the existing failed-step extension point
 
 `@deepseek-ai/dsh-llm-retry` is a function plugin that listens to `agent/request-error`. It introduces no service or new loop branch; the agent-loop package changes only the data carried through its existing failed-step recovery control flow.
 
-The `agent/request-error` seam carries the current `LlmFailure`, an immutable list of prior failures that authorized retry turns in the consecutive recovery sequence, and the serving registration's immutable retry policy. The loop transports but does not interpret that policy, owns the consecutive failure history, and clears it after a successful model request. Normal `dsh-llm-retry` policy counts durable retry records scheduled by the same exact-provider policy, while `dsh-compact-basic` keeps its own context-overflow budget. Alternating transient and context-overflow failures therefore consume their owning finite budgets independently; the maximum request count is one plus the sum of the loaded finite budgets.
+The `agent/request-error` waterfall carries the current `LlmFailure`, an immutable list of prior failures that authorized retry turns in the consecutive recovery sequence, and the serving registration's immutable retry policy. The loop transports but does not interpret that policy, owns the consecutive failure history, and clears it after a successful model request. Normal `dsh-llm-retry` policy counts durable retry records scheduled by the same exact-provider policy, while `dsh-compact-basic` keeps its own context-overflow budget. Alternating transient and context-overflow failures therefore consume their owning finite budgets independently; the maximum request count is one plus the sum of the loaded finite budgets.
 
 The [provider-policy decision](../feature/2026-07-24-provider-retry-policies.md) owns the current configuration shape. Provider adapters register their nested `retryPolicy`; omission uses normal defaults: two transient retries, a 500 millisecond initial delay, a 10 second delay cap, 10 percent jitter, and the five transient codes above. The count and delay bounds match the conservative edge of the inspected implementations: [OpenCode uses two request retries with 500 ms/10 s bounds](https://github.com/anomalyco/opencode/blob/9976269ab1accfc9f9dc98a4a688c516934de422/%70ackages/llm/src/route/executor.ts#L36-L39), [Pi separates three agent-level retries from provider retries and defaults provider retries to zero](https://github.com/earendil-works/pi/blob/3da591ab74ab9ab407e72ed882600b2c851fae21/%70ackages/coding-agent/docs/settings.md#L139-L147), and [Codex uses finite request/stream budgets plus a five-minute idle timeout](https://github.com/openai/codex/blob/0fb559f0f6e231a88ac02ea002d3ecd248e2b515/codex-rs/model-provider-info/src/lib.rs#L25-L33). Ten percent follows [Codex's bounded jitter](https://github.com/openai/codex/blob/0fb559f0f6e231a88ac02ea002d3ecd248e2b515/codex-rs/codex-client/src/retry.rs#L40-L47).
 
@@ -113,7 +113,7 @@ If recovery is exhausted, the final failure is stored once on `turn/end.reason`
 - `agent/request-error` carries current failure facts, immutable prior-retried failure facts, and the serving registration's immutable retry policy; a success clears the history, and alternating transient/context-overflow integration tests prove the two policies consume only their own finite budgets.
 - Each provider adapter validates its nested retry policy at Loader startup, and `ctx.llm` captures it with the route; normal mode delegates ineligible paths and makes at most `maxRetries + 1` provider requests when no other policy applies.
 - HMR-during-backoff tests prove disposal unregisters the listener, aborts and awaits its captured callbacks, emits no retry decision after disposal, and leaves no timer or promise alive.
-- Pure unit tests cover transient-code selection, exponential backoff and jitter bounds, valid and over-cap `Retry-After`, exhausted budgets, deterministic timer/random seams, and abort during backoff.
+- Pure unit tests cover transient-code selection, exponential backoff and jitter bounds, valid and over-cap `Retry-After`, exhausted budgets, deterministic timer/random hooks, and abort during backoff.
 - Real agent-loop tests cover failure before chunks, partial chunks then failure, thrown and in-band failures, retry to success in a new turn, exhaustion to structured `turn/end.reason`, and composition with `dsh-compact-basic` context-overflow recovery.
 - The partial-chunk integration test proves failed chunks remain attributed to the failed step, no assistant message or tool side effect is committed for that step, and the successful retry records its own chunk seqs and provider/model route.
 - The plugin-owned `llm/retry` event is non-surface, survives JSONL and SQLite round trips, is ignored by message derivation, and drives TUI and Web retraction plus scheduled-retry rendering. Client tests cover complete wire validation, clock-independent countdown, cancellation versus completed retry labels, and trajectory attribution; keyless UI snapshots cover Web scheduling and success, a real Web composition test covers partial transport failure through recovery, and ACP automation snapshots confirm that a discarded attempt stays off the wire while the recovered reply is emitted.
@@ -134,5 +134,5 @@ If recovery is exhausted, the final failure is stored once on `turn/end.reason`
 - [Structured error taxonomy](../../implemented/architecture/2026-06-11-structured-error-taxonomy.md) owns stable machine-routable codes and cause chaining.
 - [Reconstructable requests](../../implemented/architecture/2026-07-05-reconstructable-requests.md) makes provider/model and complete request inputs durable before dispatch.
 - [Timeout deadline library](../../implemented/architecture/2026-07-06-timeout-deadline-library.md) separates shared deadline classification from capability-owned termination.
-- [After-call compaction pressure and context-overflow recovery](../../implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md) owns the current closed-step request-recovery seam and bounded overflow retry.
+- [After-call compaction pressure and context-overflow recovery](../../implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md) owns the current closed-step request-recovery extension point and bounded overflow retry.
 - [Provider-routed LLM adapters](../../implemented/architecture/2026-07-14-provider-routed-llm-adapters.md) owns explicit provider/model routing and the one-adapter-per-provider invariant.
diff --git a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
index dfbe0e0afa..8d845cce79 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md
@@ -48,11 +48,11 @@ agent loop（智能体循环）会将终止 finish 的 `LlmFailure` 传给 `agen
 
 共享的暂时性 code 集有意保持很小：适配器针对 `RATE_LIMIT` 和 `SERVER` 的映射，远程失败使用的显式 `TIMEOUT` 和 `TRANSPORT` code，以及提供方响应已完成却没有内容块时使用的 `EMPTY_RESPONSE`。两个适配器都会把最后一种情况归类为错误 finish；详见[空模型响应可重试](../bug-fix/2026-07-24-empty-model-response-is-retryable.md)。身份验证、配额、无效请求、上下文溢出、协议、中止和未知失败都保留不同的稳定 code，且默认不属于暂时性失败。新增 code 需要适配器 fixture（测试前置数据）和已记录的策略决策；无需扩展第二个失败类枚举。
 
-### 将重试策略放在现有失败步骤 seam 上
+### 将重试策略放在现有失败步骤扩展点上
 
 `@deepseek-ai/dsh-llm-retry` 是监听 `agent/request-error` 的函数插件。它不引入服务或新的循环分支；agent-loop 包仅会更改通过现有失败步骤恢复控制流携带的数据。
 
-`agent/request-error` seam 携带当前 `LlmFailure`、在连续恢复序列中授权重试轮次的不可变先前失败列表，以及实际服务注册所对应的不可变重试策略。循环只传递而不解释该策略；它拥有连续失败历史，并在模型请求成功后清除。`dsh-llm-retry` 的 normal 策略统计由同一项确切提供方策略安排的持久重试记录，`dsh-compact-basic` 则维护自己的上下文溢出预算。因此，暂时性失败与上下文溢出交替出现时，会各自独立消耗其有限预算；最大请求数等于 1 加上所有已加载有限预算之和。
+`agent/request-error` waterfall 携带当前 `LlmFailure`、在连续恢复序列中授权重试轮次的不可变先前失败列表，以及实际服务注册所对应的不可变重试策略。循环只传递而不解释该策略；它拥有连续失败历史，并在模型请求成功后清除。`dsh-llm-retry` 的 normal 策略统计由同一项确切提供方策略安排的持久重试记录，`dsh-compact-basic` 则维护自己的上下文溢出预算。因此，暂时性失败与上下文溢出交替出现时，会各自独立消耗其有限预算；最大请求数等于 1 加上所有已加载有限预算之和。
 
 当前配置形状由[提供方策略决策](../feature/2026-07-24-provider-retry-policies.md)规定。提供方适配器会注册嵌套的 `retryPolicy`；省略时使用 normal 默认值：两次暂时性重试、500 毫秒初始延迟、10 秒延迟上限、10% 抖动，以及上述五个暂时性 code。计数与延迟边界参考了所调查实现中较保守的一端：[OpenCode 使用两次请求重试，延迟边界为 500 毫秒／10 秒](https://github.com/anomalyco/opencode/blob/9976269ab1accfc9f9dc98a4a688c516934de422/%70ackages/llm/src/route/executor.ts#L36-L39)；[Pi 将三次 agent 级重试与提供方重试分开，且提供方重试默认为零](https://github.com/earendil-works/pi/blob/3da591ab74ab9ab407e72ed882600b2c851fae21/%70ackages/coding-agent/docs/settings.md#L139-L147)；[Codex 使用有限请求／流预算以及五分钟空闲超时](https://github.com/openai/codex/blob/0fb559f0f6e231a88ac02ea002d3ecd248e2b515/codex-rs/model-provider-info/src/lib.rs#L25-L33)。10% 抖动参考 [Codex 的有界抖动](https://github.com/openai/codex/blob/0fb559f0f6e231a88ac02ea002d3ecd248e2b515/codex-rs/codex-client/src/retry.rs#L40-L47)。
 
@@ -113,7 +113,7 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 - `agent/request-error` 携带当前失败事实、不可变的先前已重试失败事实，以及实际服务注册所对应的不可变重试策略；成功会清除历史，暂时性失败／上下文溢出交替发生的集成测试证明两种策略只消耗各自的有限预算。
 - 每个提供方适配器都在 Loader 启动时验证其嵌套重试策略，`ctx.llm` 则将该策略与路由一同捕获；normal mode 会委托不合格路径，而且在没有其他策略时最多发起 `maxRetries + 1` 次提供方请求。
 - 退避期间执行 HMR 的测试证明：dispose 过程会注销监听器、中止并等待其捕获的回调，dispose 后不发出重试决策，也不留下存活的定时器或 promise。
-- 纯单元测试覆盖暂时性 code 选择、指数退避和抖动边界、有效及超出上限的 `Retry-After`、耗尽的预算、确定性定时器／随机数 seam，以及退避期间中止。
+- 纯单元测试覆盖暂时性 code 选择、指数退避和抖动边界、有效及超出上限的 `Retry-After`、耗尽的预算、确定性定时器／随机数钩子，以及退避期间中止。
 - 真实 agent-loop 测试覆盖分片前失败、部分分片后失败、抛出及带内失败、在新轮次中重试至成功、耗尽后写入结构化 `turn/end.reason`，以及与 `dsh-compact-basic` 上下文溢出恢复的组合。
 - 部分分片集成测试证明：失败分片仍归属于失败步骤，该步骤不会提交 assistant 消息或工具副作用，成功的重试会记录自己的分片 seq 和提供方／模型路由。
 - 插件拥有的不进入表层的 `llm/retry` 事件可在 JSONL 和 SQLite 往返后保留，被消息派生忽略，并驱动 TUI 和 Web 撤回及计划重试渲染。客户端测试覆盖完整的 wire 验证、独立于时钟的倒计时、已取消与已完成重试标签的区别以及轨迹归属；无密钥 UI 快照覆盖 Web 的调度与成功，真实 Web 组合测试覆盖部分传输失败直至恢复，ACP 自动化快照确认，被丢弃的尝试不会通过协议发出，而恢复后的回复会正常发出。
@@ -134,5 +134,5 @@ agent-spine 演示组合包加载该插件，因此共享的 stdio/TUI、一次
 - [结构化错误分类体系](../../implemented/architecture/2026-06-11-structured-error-taxonomy.md)负责稳定、可供机器路由的 code 与 cause chaining。
 - [可重建请求](../../implemented/architecture/2026-07-05-reconstructable-requests.md)使提供方／模型和完整请求输入在分发前持久化。
 - [超时 deadline 库](../../implemented/architecture/2026-07-06-timeout-deadline-library.md)将共享的 deadline 分类与能力自身拥有的终止操作分开。
-- [调用后压缩压力与上下文溢出恢复](../../implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)负责当前已关闭步骤的请求恢复 seam 与有界溢出重试。
+- [调用后压缩压力与上下文溢出恢复](../../implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)负责当前已关闭步骤的请求恢复扩展点与有界溢出重试。
 - [提供方路由的 LLM（大语言模型）适配器](../../implemented/architecture/2026-07-14-provider-routed-llm-adapters.md)负责显式提供方／模型路由与每个提供方仅有一个适配器的不变量。
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index 6303b1e77a..32db924032 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.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 .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
-2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a
-2026-06-21-mandatory-app-attribution-headers.zh.md: 6f0d0199f859fd462fdecc24e4063cbd27311bab
+2026-06-21-mandatory-app-attribution-headers.md: 71e74e753c39c8eddfe886d69ee9f28edff9ebab
+2026-06-21-mandatory-app-attribution-headers.zh.md: 9cc2c178cd83f3f041282a0dac34b70f78bcc467
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
index de9125bc89..71e74e753c 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-21-mandatory-app-attribution-headers.zh.md)
 
 ## Problem
 
-LLM provider requests should identify the product making them. That is useful for provider-side support, abuse investigation, compatibility debugging, and traffic analytics. Before this Agent Note the harness only partially did this: the hand-rolled DeepSeek adapter sent a hand-copied `User-Agent` constant (`packages/llm/llm-deepseek/src/adapter.ts`), while the pi-ai-backed twin sent no harness-owned headers at all (`packages/llm/llm-pi-ai/src/adapter.ts`). New adapters could therefore omit attribution silently, and a library-backed adapter could drift from the hand-rolled adapter even though [the twin-adapter Agent Note](2026-06-13-twin-llm-adapters.md) exists to keep the provider seam honest across both implementations.
+LLM provider requests should identify the product making them. That is useful for provider-side support, abuse investigation, compatibility debugging, and traffic analytics. Before this Agent Note the harness only partially did this: the hand-rolled DeepSeek adapter sent a hand-copied `User-Agent` constant (`packages/llm/llm-deepseek/src/adapter.ts`), while the pi-ai-backed twin sent no harness-owned headers at all (`packages/llm/llm-pi-ai/src/adapter.ts`). New adapters could therefore omit attribution silently, and a library-backed adapter could drift from the hand-rolled adapter even though [the twin-adapter Agent Note](2026-06-13-twin-llm-adapters.md) exists to keep the provider contract honest across both implementations.
 
 The immediate prompt came from OpenRouter's [App Attribution](https://openrouter.ai/docs/app-attribution) docs. OpenRouter creates app pages and rankings from `HTTP-Referer` plus display/category headers. That is valuable, but it is not the HTTP standard for application identity. The risk is adopting OpenRouter's exact header set as if it were universal, then leaking provider-specific headers to direct DeepSeek requests, future OpenAI/Anthropic/Vertex adapters, test servers, or proxies that log unknown fields indefinitely.
 
@@ -34,7 +34,7 @@ The provider-neutral identity is owned by `dsh-llm` (`packages/llm/llm/src/attri
 - version: read from the owning package's manifest via `createRequire`, never a hand-copied constant
 - app URL: `https://github.com/deepseek-ai/deepseek-harness-sdk` - the planned public home, which must exist before release
 
-The default is mandatory and non-empty. White-label deployments pass their own `AppIdentity` to `attributionHeaders(identity)` - the override seam is the function parameter, with no deployment config plumbing until a consumer needs it - and omission falls back to the harness default rather than suppressing attribution. There is no per-request API for the model, user prompt, session id, cwd, user email, API key owner, or local machine identity to influence these fields.
+The default is mandatory and non-empty. White-label deployments pass their own `AppIdentity` to `attributionHeaders(identity)` - the override hook is the function parameter, with no deployment config plumbing until a consumer needs it - and omission falls back to the harness default rather than suppressing attribution. There is no per-request API for the model, user prompt, session id, cwd, user email, API key owner, or local machine identity to influence these fields.
 
 Wire mapping (`attributionHeaders`; header names lowercase in code - HTTP field names are case-insensitive on the wire):
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index 6f0d0199f8..9cc2c178cd 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-LLM（大语言模型）提供方请求应当标识发出请求的产品。这对提供方侧的技术支持、滥用调查、兼容性调试和流量分析都有价值。在本 Agent Note 之前，harness 只做了部分工作：手写的 DeepSeek 适配器发送了一个手动复制的 `User-Agent` 常量（`packages/llm/llm-deepseek/src/adapter.ts`），而基于 pi-ai 的孪生适配器则完全不发送 harness 自有的头部（`packages/llm/llm-pi-ai/src/adapter.ts`）。因此新适配器可以悄无声息地省略归属标识，而基于库的适配器也可能与手写适配器产生偏差——尽管[孪生适配器 Agent Note](2026-06-13-twin-llm-adapters.md) 的存在正是为了让两种实现在提供方 seam 上保持诚实。
+LLM（大语言模型）提供方请求应当标识发出请求的产品。这对提供方侧的技术支持、滥用调查、兼容性调试和流量分析都有价值。在本 Agent Note 之前，harness 只做了部分工作：手写的 DeepSeek 适配器发送了一个手动复制的 `User-Agent` 常量（`packages/llm/llm-deepseek/src/adapter.ts`），而基于 pi-ai 的孪生适配器则完全不发送 harness 自有的头部（`packages/llm/llm-pi-ai/src/adapter.ts`）。因此新适配器可以悄无声息地省略归属标识，而基于库的适配器也可能与手写适配器产生偏差——尽管[孪生适配器 Agent Note](2026-06-13-twin-llm-adapters.md) 的存在正是为了让两种实现在提供方约定上保持诚实。
 
 直接触发因素来自 OpenRouter 的[应用归属](https://openrouter.ai/docs/app-attribution)文档。OpenRouter 根据 `HTTP-Referer` 加上 display/category 头部来创建应用页面和排名。这有价值，但它不是 HTTP 标准中的应用身份机制。风险在于：把 OpenRouter 的精确头部集当作通用标准来采纳，然后将提供方特有的头部泄漏到直连 DeepSeek 的请求、未来的 OpenAI/Anthropic/Vertex 适配器、测试服务器或无限期记录未知字段的代理中。
 
@@ -34,7 +34,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 - 版本：通过 `createRequire` 从所属包的 manifest（元数据清单）读取，绝不手动复制常量
 - 应用 URL：`https://github.com/deepseek-ai/deepseek-harness-sdk`——计划中的公开主页，且必须在发布前实际存在
 
-默认值是强制的且非空。白标部署通过向 `attributionHeaders(identity)` 传入自己的 `AppIdentity` 来覆盖——覆盖 seam 就是函数参数，在有消费方需要之前不做部署配置管道——省略时回退到 harness 默认值而非抑制归属。没有逐请求 API 允许模型、用户提示词、会话 id、cwd、用户邮箱、API key 所有者或本地机器身份影响这些字段。
+默认值是强制的且非空。白标部署通过向 `attributionHeaders(identity)` 传入自己的 `AppIdentity` 来覆盖——覆盖钩子就是函数参数，在有消费方需要之前不做部署配置管道——省略时回退到 harness 默认值而非抑制归属。没有逐请求 API 允许模型、用户提示词、会话 id、cwd、用户邮箱、API key 所有者或本地机器身份影响这些字段。
 
 线路映射（`attributionHeaders`；代码中头部名称小写——HTTP 字段名在线路上不区分大小写）：
 
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
index 43259e19b2..4147d8dc12 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.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 .agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
-2026-06-24-web-capability-seam.md: b705236690859961ed69b307dbb59ebefcbd65ac
-2026-06-24-web-capability-seam.zh.md: ea9261b4bc16cbd913c90f5ccb1aeebc1a0d8dea
+2026-06-24-web-capability-seam.md: 3893c9f9d45eac90c9ae381f9fa92ad8c7ae7644
+2026-06-24-web-capability-seam.zh.md: 70745c235d17e3cbf6152c2ef470283b0bad85f2
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
index b705236690..3893c9f9d4 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-24-web-capability-seam.zh.md)
 
 ## Problem
 
-The harness needs model-facing web tools without binding the model contract to one vendor's API shape. Search is the immediate pressure point: supporting both Exa search and Perplexity search from the start — two deliberately different provider shapes (Exa returns a flat `results[]` of `{title, url, highlights, publishedDate}`; Perplexity returns a generated answer plus citations) — is what proves the normalized seam does not just mirror one vendor. Fetch is a separate capability: an anonymous public HTTP(S) fetch backend has transport, security, redirect, decoding, and size-limit concerns that are not the same as provider-backed search.
+The harness needs model-facing web tools without binding the model contract to one vendor's API shape. Search is the immediate pressure point: supporting both Exa search and Perplexity search from the start — two deliberately different provider shapes (Exa returns a flat `results[]` of `{title, url, highlights, publishedDate}`; Perplexity returns a generated answer plus citations) — is what proves the normalized web contract does not just mirror one vendor. Fetch is a separate operation: an anonymous public HTTP(S) fetch backend has transport, security, redirect, decoding, and size-limit concerns that are not the same as provider-backed search.
 
 The model-facing surface must stay stable while backends change. A search provider swap should not change how the model asks for a query, and a fetch implementation swap should not change how the model asks for a URL. Conversely, a provider package should not expose its own model-facing tool schema just because it has extra provider-specific knobs.
 
@@ -38,7 +38,7 @@ The seam deliberately exposes no observation surface — no registry-change even
 
 ## Package topology
 
-The three-package interface/implementation/consumer split follows bash and filesystem, but the *interface* package is closer to the LLM seam. `LlmService` (`packages/llm/llm/src/index.ts`) is a name-keyed provider registry: `registerAdapter(models, adapter)` stores adapters in a `Map`, returns a disposer, throws `DUPLICATE_ADAPTER` on duplicate keys, and throws `NO_ADAPTER` at resolution time. `ctx.web` follows that registry shape, but has two capability kinds and a richer selection policy (a configured provider id, or auto-select when exactly one usable provider is registered), so the `WebError` an execution throws can explain why a search or fetch capability cannot run.
+The three-package Service Definition / Service provider / Consumer split follows bash and filesystem, but the *interface* package is closer to the LLM seam. `LlmService` (`packages/llm/llm/src/index.ts`) is a name-keyed provider registry: `registerAdapter(models, adapter)` stores adapters in a `Map`, returns a disposer, throws `DUPLICATE_ADAPTER` on duplicate keys, and throws `NO_ADAPTER` at resolution time. `ctx.web` follows that registry shape, but has two capability kinds and a richer selection policy (a configured provider id, or auto-select when exactly one usable provider is registered), so the `WebError` an execution throws can explain why a search or fetch capability cannot run.
 
 The dependency direction mirrors bash and filesystem:
 
@@ -280,7 +280,7 @@ Tool execution lets these errors flow through `ToolRegistry.execute()`, which al
 
 ## Testing
 
-Each layer is pinned at its own seam: the registry/selection/truncation/abort contract and the `WebError` codes in `dsh-web`; per-provider request/response mapping over recorded fixtures (Perplexity fixtures include URL-only citations so the optional source fields stay honest) plus a self-skipping with-key smoke per real provider; real local-HTTP behavior in `web-fetch-local`; and enablement-driven registration, structured execution errors, and result formatting through the real tool registry in `dsh-tool-web`. A real-Loader smoke guards the two export shapes ([postmortem 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)): `dsh-web` is a default-exported service, while the providers and `tool-web` are namespace plugins where a stray `export default` would drop `inject`.
+Each layer is pinned at its own boundary: the registry/selection/truncation/abort contract and the `WebError` codes in `dsh-web`; per-provider request/response mapping over recorded fixtures (Perplexity fixtures include URL-only citations so the optional source fields stay honest) plus a self-skipping with-key smoke per real provider; real local-HTTP behavior in `web-fetch-local`; and enablement-driven registration, structured execution errors, and result formatting through the real tool registry in `dsh-tool-web`. A real-Loader smoke guards the two export shapes ([postmortem 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)): `dsh-web` is a default-exported service, while the providers and `tool-web` are namespace plugins where a stray `export default` would drop `inject`.
 
 ## Alternatives considered
 
@@ -302,7 +302,7 @@ Rejected. Registration order is not a product policy. It can change with config
 
 ### Treat Firecrawl/Exa/Tavily/Parallel extraction as fetch
 
-Rejected for the first version. Those providers often return extracted or summarized content rather than a concrete HTTP response. If the product needs extraction, design `web_extract` or deliberately widen the fetch seam later.
+Rejected for the first version. Those providers often return extracted or summarized content rather than a concrete HTTP response. If the product needs extraction, design `web_extract` or deliberately widen the fetch operation later.
 
 ### Mirror Claude Code's `url + prompt` WebFetch shape
 
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
index ea9261b4bc..70745c235d 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-harness 需要面向模型的 web 工具，但不能将模型约定绑定到某一家厂商的 API 形状上。搜索是当前的压力点：从一开始就同时支持 Exa 搜索和 Perplexity 搜索——两种刻意不同的提供方形状（Exa 返回扁平的 `results[]`，每项包含 `{title, url, highlights, publishedDate}`；Perplexity 返回一段生成式回答加引用列表）——正是用来证明归一化的 seam 并非只是镜像某一家厂商。Fetch 是另一项独立能力：匿名公开 HTTP(S) fetch 后端涉及传输、安全、重定向、解码和大小限制等关注点，与提供方支撑的搜索并不相同。
+harness 需要面向模型的 web 工具，但不能将模型约定绑定到某一家厂商的 API 形状上。搜索是当前的压力点：从一开始就同时支持 Exa 搜索和 Perplexity 搜索——两种刻意不同的提供方形状（Exa 返回扁平的 `results[]`，每项包含 `{title, url, highlights, publishedDate}`；Perplexity 返回一段生成式回答加引用列表）——正是用来证明归一化的 web 约定并非只是镜像某一家厂商。Fetch 是另一项独立操作：匿名公开 HTTP(S) fetch 后端涉及传输、安全、重定向、解码和大小限制等关注点，与提供方支撑的搜索并不相同。
 
 面向模型的接口必须保持稳定，而后端可以更换。更换搜索提供方不应改变模型发起查询的方式；更换 fetch 实现不应改变模型请求 URL 的方式。反过来，提供方包也不应仅仅因为自己有额外的提供方特有旋钮就暴露自己的面向模型工具 schema。
 
@@ -38,7 +38,7 @@ Web 访问是一个一等能力 seam，遵循[能力 seam Agent Note](2026-06-13
 
 ## 包拓扑
 
-由三个包构成的接口/实现/消费方拆分沿用 bash 和 filesystem 的模式，但*接口*包更接近 LLM（大语言模型） seam。`LlmService`（`packages/llm/llm/src/index.ts`）是一个按名称键控的提供方注册表：`registerAdapter(models, adapter)` 将适配器存入 `Map`、返回 disposer、对重复键抛出 `DUPLICATE_ADAPTER`、在解析时抛出 `NO_ADAPTER`。`ctx.web` 沿用该注册表形状，但有两种能力类别和更丰富的选择策略（配置的提供方 id，或在恰好只有一个可用提供方注册时自动选择），因此执行时抛出的 `WebError` 能解释搜索或 fetch 能力为何无法运行。
+由三个包构成的 Service Definition / Service provider / Consumer 拆分沿用 bash 和 filesystem 的模式，但*接口*包更接近 LLM（大语言模型） seam。`LlmService`（`packages/llm/llm/src/index.ts`）是一个按名称键控的提供方注册表：`registerAdapter(models, adapter)` 将适配器存入 `Map`、返回 disposer、对重复键抛出 `DUPLICATE_ADAPTER`、在解析时抛出 `NO_ADAPTER`。`ctx.web` 沿用该注册表形状，但有两种能力类别和更丰富的选择策略（配置的提供方 id，或在恰好只有一个可用提供方注册时自动选择），因此执行时抛出的 `WebError` 能解释搜索或 fetch 能力为何无法运行。
 
 依赖方向与 bash 和 filesystem 一致：
 
@@ -280,7 +280,7 @@ SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他
 
 ## 测试
 
-每一层在自己的 seam 处固定：`dsh-web` 中的注册/选择/截断/abort 约定与 `WebError` 码；每个提供方基于录制的 fixture（测试前置数据）的请求/响应映射（Perplexity fixture 包含纯 URL 引用，以保持可选 source 字段的诚实性），加上每个真实提供方的自跳过带密钥冒烟测试；`web-fetch-local` 中的真实本地 HTTP 行为；`dsh-tool-web` 中通过真实工具注册表的启用驱动注册、结构化执行错误和结果格式化。一个真实 Loader 冒烟测试守护两种导出形状（[事故复盘（postmortem） 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）：`dsh-web` 是默认导出的服务，而提供方和 `tool-web` 是命名空间插件，误加 `export default` 会丢失 `inject`。
+每一层在自己的边界处固定：`dsh-web` 中的注册/选择/截断/abort 约定与 `WebError` 码；每个提供方基于录制的 fixture（测试前置数据）的请求/响应映射（Perplexity fixture 包含纯 URL 引用，以保持可选 source 字段的诚实性），加上每个真实提供方的自跳过带密钥冒烟测试；`web-fetch-local` 中的真实本地 HTTP 行为；`dsh-tool-web` 中通过真实工具注册表的启用驱动注册、结构化执行错误和结果格式化。一个真实 Loader 冒烟测试守护两种导出形状（[事故复盘（postmortem） 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）：`dsh-web` 是默认导出的服务，而提供方和 `tool-web` 是命名空间插件，误加 `export default` 会丢失 `inject`。
 
 ## 曾考虑的替代方案
 
@@ -302,7 +302,7 @@ SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他
 
 ### 将 Firecrawl/Exa/Tavily/Parallel 提取视为 fetch
 
-在第一版中否决。这些提供方通常返回提取或摘要后的内容，而非具体的 HTTP 响应。如果产品需要提取，日后设计 `web_extract` 或刻意扩展 fetch seam。
+在第一版中否决。这些提供方通常返回提取或摘要后的内容，而非具体的 HTTP 响应。如果产品需要提取，日后设计 `web_extract` 或刻意扩展 fetch 操作。
 
 ### 镜像 Claude Code 的 `url + prompt` WebFetch 形状
 
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
index 726ab7374d..ffa6f48889 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.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 .agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
-2026-06-26-file-context-as-event-gate.md: 4700222aa2e0f91d9f355495c228e2eb92825f55
-2026-06-26-file-context-as-event-gate.zh.md: dff5c3e9ea99e73d3d1a86c4012da1e4232021bb
+2026-06-26-file-context-as-event-gate.md: df1a43e252cff02b287497210664c3d14dcd35a9
+2026-06-26-file-context-as-event-gate.zh.md: 3d784c9e150430c8054f6b08ccc5c66fa85e09b4
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
index 4700222aa2..df1a43e252 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
@@ -26,7 +26,7 @@ tool          dsh-tool-fs       executor: resolves, reads windows, writes/edits
 policy        dsh-fs-policy  plugin: listens to fs/write-intent +
                                 fs/edit-intent (single-slot waterfall) and fs/observed
                                 (emit) events; adds observed-state + freshness.
-provider seam dsh-fs            ctx.fs: text IO + ATOMIC mutation primitives whose version
+provider contract dsh-fs            ctx.fs: text IO + ATOMIC mutation primitives whose version
                                 guard is OPTIONAL; owns the fs policy event vocabulary
 provider      dsh-fs-local      local implementation of ctx.fs
 ```
@@ -72,7 +72,7 @@ These events carry existing `dsh-fs` vocabulary (`FsTarget`, `FsVersion`, `FsWri
 
 **The two `fs/*` decision events are single-slot, first-wins waterfalls.** `dsh-fs-policy` returns without calling `next()`, so it owns the slot in the default deployment; a listener registered earlier or with `prepend` would replace that policy. Permission, audit, and sandbox concerns remain on the composable `tools/execute` waterfall.
 
-The actor is typed `object` in `dsh-fs` — a pure opaque carrier the provider seam never reads or narrows. The owner-derivation (`actor.agent?.session`) and the `{ agent?: { session? } }` structural shape stay entirely inside `dsh-fs-policy`, which narrows the `object` actor to that shape in its listeners. `dsh-fs` owns the event names and the fs vocabulary; it does NOT own the policy layer's runtime owner structure.
+The actor is typed `object` in `dsh-fs` — a pure opaque carrier the provider contract never reads or narrows. The owner-derivation (`actor.agent?.session`) and the `{ agent?: { session? } }` structural shape stay entirely inside `dsh-fs-policy`, which narrows the `object` actor to that shape in its listeners. `dsh-fs` owns the event names and the fs vocabulary; it does NOT own the policy layer's runtime owner structure.
 
 ```ts
 import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
@@ -136,7 +136,7 @@ The tool passes `exec` (the tool-execution context) as the `actor` argument on e
 
 An observed-state entry is the **prior-observation record**: a successful `read`, `write`, OR `edit` all emit `fs/observed` and record `{ version }`, so the entry's presence means "this owner has observed this target at this version", not narrowly "has read it". This is what lets a create-then-edit or edit-then-edit sequence work without an intervening re-read: the mutation refreshes the recorded version to its own result, so the next edit's basis is the version it just produced. `FS_NOT_OBSERVED` rejects only an edit with NO prior observation of any kind. The owner is derived structurally from `{ agent?: { session? } }`; disposal drops all state (HMR safety).
 
-`dsh-fs-policy` is now a pure policy/recording plugin with no service surface — it influences the world only through the event seam. That is what removes the method coupling from `dsh-tool-fs`.
+`dsh-fs-policy` is now a pure policy/recording plugin with no service surface — it influences the world only through the event gate. That is what removes the method coupling from `dsh-tool-fs`.
 
 ## Bare-provider behavior (no `dsh-fs-policy`)
 
@@ -166,6 +166,6 @@ Tests pin both paths: without `dsh-fs-policy`, the root tool plugin boots agains
 
 - **Event indirection over a method call.** A waterfall + emit is less direct than `await ctx.fileContext.edit(...)`. The payoff is removing the tool-to-policy method dependency while keeping the default policy plugin; the cost is one more event vocabulary to learn. Mitigated by keeping the three events narrow and documenting the default-thunk semantics on each.
 - **Policy events in the storage seam.** `dsh-fs` gains two version-decision events plus a recording event though it is "just storage". This is the price of decoupling (the emitter cannot depend on the policy plugin). The events carry only `dsh-fs` vocabulary plus an opaque `object` actor and no model-facing concepts, so the seam stays free of line-window/observation policy types and of the agent/session owner structure.
-- **Single policy occupant, first-wins by convention.** The `fs/write-intent`/`fs/edit-intent` slots hold exactly one decider; the first-registered (or `prepend`ed) listener wins and the rest are short-circuited. `dsh-fs-policy` owning the slot is a deployment convention, not an event-enforced invariant — a second decider registered first would bypass it. This is acceptable because a second fs-version-policy decider is a misconfiguration, not a feature. If a future need for *layered* fs version policy appears, it is a new Agent Note (a composable value-passing seam), not a silent second listener on these events. Layered permission/audit/sandbox interception already has its home on `tools/execute`.
+- **Single policy occupant, first-wins by convention.** The `fs/write-intent`/`fs/edit-intent` slots hold exactly one decider; the first-registered (or `prepend`ed) listener wins and the rest are short-circuited. `dsh-fs-policy` owning the slot is a deployment convention, not an event-enforced invariant — a second decider registered first would bypass it. This is acceptable because a second fs-version-policy decider is a misconfiguration, not a feature. If a future need for *layered* fs version policy appears, it is a new Agent Note (a composable value-passing waterfall), not a silent second listener on these events. Layered permission/audit/sandbox interception already has its home on `tools/execute`.
 - **Dropping the post-read confirming stat** makes a follow-up *guarded* edit occasionally fail-closed (`FS_STALE_VERSION` → re-read) under a read/write race. This is a UX nicety lost, never a correctness hole; the provider lock still prevents wrong-version writes.
 - **The bare provider does no read-before-write/edit and no version check.** A deployment without `dsh-fs-policy` lets the model overwrite or edit any existing file unconditionally. This is the deliberate meaning of keeping the tool independent of a policy service: the safety disciplines live in the `dsh-fs-policy` plugin. A deployment that omits it is opting into an unconstrained filesystem on purpose; that is not the intended stance for a config that ships the fs tools.
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
index dff5c3e9ea..3d784c9e15 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
@@ -26,7 +26,7 @@ tool          dsh-tool-fs       executor: resolves, reads windows, writes/edits
 policy        dsh-fs-policy  plugin: listens to fs/write-intent +
                                 fs/edit-intent (single-slot waterfall) and fs/observed
                                 (emit) events; adds observed-state + freshness.
-provider seam dsh-fs            ctx.fs: text IO + ATOMIC mutation primitives whose version
+provider contract dsh-fs            ctx.fs: text IO + ATOMIC mutation primitives whose version
                                 guard is OPTIONAL; owns the fs policy event vocabulary
 provider      dsh-fs-local      local implementation of ctx.fs
 ```
@@ -72,7 +72,7 @@ editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion
 
 **两个 `fs/*` 决策事件是单槽、先到先得的 waterfall。** `dsh-fs-policy` 不调用 `next()` 直接返回，因此在默认部署中它占据该槽位；更早注册或使用 `prepend` 的监听器会替代该策略。权限、审计和沙箱关注点仍留在可组合的 `tools/execute` waterfall 上。
 
-actor 在 `dsh-fs` 中类型为 `object`——一个纯粹的不透明载体，提供方 seam 从不读取或收窄它。owner 的推导（`actor.agent?.session`）和 `{ agent?: { session? } }` 结构形状完全留在 `dsh-fs-policy` 内部，由其在监听器中将 `object` actor 收窄为该形状。`dsh-fs` 拥有事件名和 fs 词汇；它不拥有策略层的运行时 owner 结构。
+actor 在 `dsh-fs` 中类型为 `object`——一个纯粹的不透明载体，提供方约定从不读取或收窄它。owner 的推导（`actor.agent?.session`）和 `{ agent?: { session? } }` 结构形状完全留在 `dsh-fs-policy` 内部，由其在监听器中将 `object` actor 收窄为该形状。`dsh-fs` 拥有事件名和 fs 词汇；它不拥有策略层的运行时 owner 结构。
 
 ```ts
 import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
@@ -136,7 +136,7 @@ interface Events {
 
 一条观测状态条目是**先前观测记录**：成功的 `read`、`write` 或 `edit` 都会 emit `fs/observed` 并记录 `{ version }`，因此条目的存在意味着「此 owner 在此版本观测过此目标」，而非狭义的「已读取过」。这使得 create-then-edit 或 edit-then-edit 序列无需中间重新读取即可工作：mutation 将记录的版本刷新为自身的结果，因此下一次编辑的基准就是它刚产出的版本。`FS_NOT_OBSERVED` 只拒绝完全没有任何先前观测的编辑。owner 从 `{ agent?: { session? } }` 结构化推导；dispose 时丢弃所有状态（HMR 安全）。
 
-`dsh-fs-policy` 现在是一个纯策略/记录插件，没有服务面——它只通过事件 seam 影响外界。这正是移除 `dsh-tool-fs` 方法耦合的关键。
+`dsh-fs-policy` 现在是一个纯策略/记录插件，没有服务面——它只通过事件门控影响外界。这正是移除 `dsh-tool-fs` 方法耦合的关键。
 
 ## 裸提供方行为（无 `dsh-fs-policy`）
 
@@ -166,6 +166,6 @@ interface Events {
 
 - **事件间接层取代方法调用。** 一次 waterfall + emit 不如 `await ctx.fileContext.edit(...)` 直接。收益是移除了工具到策略的方法依赖，同时保留默认策略插件；代价是多一套事件词汇需要学习。通过保持三个事件的窄小范围并在每个事件上记录 default-thunk 语义来缓解。
 - **策略事件位于存储 seam 中。** `dsh-fs` 增加了两个版本决策事件和一个记录事件，尽管它「只是存储」。这是解耦的代价（发射方不能依赖策略插件）。这些事件只携带 `dsh-fs` 词汇加一个不透明的 `object` actor，不携带面向模型的概念，因此 seam 不沾染行窗口/观测策略类型，也不沾染 agent/会话所有者结构。
-- **单一策略占位者，按约定先到先得。** `fs/write-intent`/`fs/edit-intent` 槽位恰好容纳一个决策者；先注册（或 `prepend`）的监听器获胜，其余被短路。`dsh-fs-policy` 占据该槽位是部署约定，而非事件系统强制的不变式——一个先注册的第二决策者会绕过它。这是可接受的，因为第二个 fs 版本策略决策者是配置错误，而非功能。如果未来出现*分层* fs 版本策略的需求，那是一个新 Agent Note（可组合的值传递 seam），而非在这些事件上静默添加第二个监听器。分层的权限/审计/沙箱拦截已有其归属：`tools/execute`。
+- **单一策略占位者，按约定先到先得。** `fs/write-intent`/`fs/edit-intent` 槽位恰好容纳一个决策者；先注册（或 `prepend`）的监听器获胜，其余被短路。`dsh-fs-policy` 占据该槽位是部署约定，而非事件系统强制的不变式——一个先注册的第二决策者会绕过它。这是可接受的，因为第二个 fs 版本策略决策者是配置错误，而非功能。如果未来出现*分层* fs 版本策略的需求，那是一个新 Agent Note（可组合的值传递 waterfall），而非在这些事件上静默添加第二个监听器。分层的权限/审计/沙箱拦截已有其归属：`tools/execute`。
 - **移除读后确认 stat** 使后续*有守卫*的编辑在 read/write 竞争下偶尔为安全起见拒绝写入（`FS_STALE_VERSION` → 重新读取）。这是丢失的 UX 便利，绝非正确性漏洞；提供方锁仍阻止基于错误版本的写入。
 - **裸提供方不做先读后写/编辑，也不做版本检查。** 没有 `dsh-fs-policy` 的部署允许模型无条件覆写或编辑任何已有文件。这正是保持工具独立于策略服务的有意含义：安全纪律存在于 `dsh-fs-policy` 插件中。省略它的部署是有意选择无约束的文件系统；对于发布 fs 工具的配置而言，这不是预期的姿态。
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
index 459ffa188c..8201388c72 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.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 .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
-2026-06-30-bash-stdin-env-trusted-plugin-surface.md: aa0c785be84bcb8a49f8a2670afa0f6bed6277db
-2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 48108fdd5b8217263590fba336480f1b487e882f
+2026-06-30-bash-stdin-env-trusted-plugin-surface.md: 1c2cfc4257e93b2f2f126947e93b38aa2d4cd570
+2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 050f604259033f20be8174754c32f624e9a0ce76
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
index aa0c785be8..1c2cfc4257 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
@@ -8,7 +8,7 @@ English | [中文](2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md)
 
 The hooks subsystem runs external hook commands the way Claude Code and Codex do: a hook is a shell command that receives its event payload as **JSON on stdin** and reads context from a handful of **environment variables** (`CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `PLUGIN_ROOT`, …). The harness already has a perfectly good command runner behind the `ctx.bash` capability seam ([dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)), with process-group kills, output truncation/spill, and a credential scrub. Reusing it for hook execution means a hook bridge does not re-implement subprocess plumbing — but the seam had no way to write stdin or set extra env. This Agent Note adds those two inputs.
 
-`stdin` and `env` do not create a new model capability because ordinary shell syntax already supplies both. Ambient credentials are protected by `dsh-bash-local`'s child-environment scrub, not by hiding these seam fields; model tool arguments are static JSON and do not expand shell variables. The fields therefore serve trusted in-process callers, such as hook bridges, that need to pass structured input and `CLAUDE_*` variables without embedding them in model-visible shell text. See [defensive-patterns.md](../../../../docs/defensive-patterns.md) for the ambient-environment rule.
+`stdin` and `env` do not create a new model capability because ordinary shell syntax already supplies both. Ambient credentials are protected by `dsh-bash-local`'s child-environment scrub, not by hiding these Service Definition fields; model tool arguments are static JSON and do not expand shell variables. The fields therefore serve trusted in-process callers, such as hook bridges, that need to pass structured input and `CLAUDE_*` variables without embedding them in model-visible shell text. See [defensive-patterns.md](../../../../docs/defensive-patterns.md) for the ambient-environment rule.
 
 ## Decision
 
@@ -16,7 +16,7 @@ Add `stdin?: string` and `env?: Record<string, string>` to **both** `BashExecReq
 
 Three deliberate choices:
 
-1. **The model-facing tool omits `stdin` and `env`.** Shell syntax already covers those needs, so duplicate parameters would add surface without authority separation. The tool builds requests only from declared model arguments, signal, and owner; trusted in-process callers may set the seam fields directly. Harness-owned variables use the separate `dshEnv` channel from the [managed environment decision](../feature/2026-07-10-agent-session-identity-and-log-location.md), so ordinary `env` cannot replace them.
+1. **The model-facing tool omits `stdin` and `env`.** Shell syntax already covers those needs, so duplicate parameters would add surface without authority separation. The tool builds requests only from declared model arguments, signal, and owner; trusted in-process callers may set the request fields directly. Harness-owned variables use the separate `dshEnv` channel from the [managed environment decision](../feature/2026-07-10-agent-session-identity-and-log-location.md), so ordinary `env` cannot replace them.
 
 2. **`env` merges AFTER the credential scrub, so an explicit caller entry wins even on a credential-shaped name.** The later managed-namespace decision manages `DSH_*`: ambient entries are removed, and trusted `dshEnv` merges last, so an ordinary `env` entry can never displace a managed value. The complete order is `scrub(process.env, including DSH_*)` → `ENV_OVERRIDES` → ordinary `env` → `dshEnv`.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
index 48108fdd5b..050f604259 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 钩子子系统以 Claude Code 和 Codex 的方式运行外部钩子命令：钩子是一条 shell 命令，通过 **stdin 上的 JSON** 接收事件载荷，并从若干**环境变量**（`CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT`、`PLUGIN_ROOT`……）读取上下文。harness 已经在 `ctx.bash` 能力 seam 后面有一个完善的命令执行器（[dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)），具备进程组终止、输出截断/溢出处理和凭证擦除功能。复用它来执行钩子意味着钩子桥接层无需重新实现子进程管道——但该 seam 此前无法写入 stdin 或设置额外 env。本 Agent Note 添加这两个输入。
 
-`stdin` 和 `env` 不构成新的模型能力，因为普通 shell 语法已经能提供两者。环境凭证由 `dsh-bash-local` 的子环境擦除机制保护，而非靠隐藏这些 seam 字段；模型工具参数是静态 JSON，不会展开 shell 变量。因此这些字段服务于受信的进程内调用方（如钩子桥接层），它们需要传递结构化输入和 `CLAUDE_*` 变量，而不必将其嵌入模型可见的 shell 文本。环境变量规则见 [defensive-patterns.md](../../../../docs/defensive-patterns.md)。
+`stdin` 和 `env` 不构成新的模型能力，因为普通 shell 语法已经能提供两者。环境凭证由 `dsh-bash-local` 的子环境擦除机制保护，而非靠隐藏这些 Service Definition 字段；模型工具参数是静态 JSON，不会展开 shell 变量。因此这些字段服务于受信的进程内调用方（如钩子桥接层），它们需要传递结构化输入和 `CLAUDE_*` 变量，而不必将其嵌入模型可见的 shell 文本。环境变量规则见 [defensive-patterns.md](../../../../docs/defensive-patterns.md)。
 
 ## 决策
 
@@ -16,7 +16,7 @@ Status: implemented
 
 三个有意为之的选择：
 
-1. **模型侧工具不暴露 `stdin` 和 `env`。** Shell 语法已覆盖这些需求，重复参数只会增加接口面而不带来权限隔离。工具仅从声明的模型参数、signal 和 owner 构建请求；受信的进程内调用方可以直接设置 seam 字段。harness 自有变量使用[托管环境决策](../feature/2026-07-10-agent-session-identity-and-log-location.md)规定的独立 `dshEnv` 通道，因此普通 `env` 无法替换它们。
+1. **模型侧工具不暴露 `stdin` 和 `env`。** Shell 语法已覆盖这些需求，重复参数只会增加接口面而不带来权限隔离。工具仅从声明的模型参数、signal 和 owner 构建请求；受信的进程内调用方可以直接设置请求字段。harness 自有变量使用[托管环境决策](../feature/2026-07-10-agent-session-identity-and-log-location.md)规定的独立 `dshEnv` 通道，因此普通 `env` 无法替换它们。
 
 2. **`env` 在凭证擦除之后合并，因此调用方显式设置的条目即使具有凭证形态的名称也会胜出。** 后续的托管命名空间决策负责管理 `DSH_*`：这类环境条目会被移除，受信的 `dshEnv` 最后合并，因此普通 `env` 条目永远无法顶掉托管值。完整顺序为 `scrub(process.env, including DSH_*)` → `ENV_OVERRIDES` → 普通 `env` → `dshEnv`。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
index 2e69991c33..fab7f4d6d6 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.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 .agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
-2026-06-30-event-domain-semantics.md: 14102b105e7bcaa6a00ac9c406933f772fc45a6f
-2026-06-30-event-domain-semantics.zh.md: 2607e59490d8ba139bb1289d0f2941894281f6c6
+2026-06-30-event-domain-semantics.md: a3af693126b71c5844260f53c62b4ab4a28fe56f
+2026-06-30-event-domain-semantics.zh.md: 1f6df779fdccb921861f6ea848e33d9cd866b027
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
index 14102b105e..a3af693126 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
@@ -10,7 +10,7 @@ The harness extends the agent loop through a Cordis event taxonomy (see [the mic
 
 - `session/*` carries the durable, event-sourced log (`SessionEventMap`).
 - `agent/*` carries live runtime signals that hand a plugin the `Agent` handle.
-- `tools/*` carries the tool registry + execution seam.
+- `tools/*` carries the tool registry and execution pipeline.
 
 Two problems motivated pinning the semantics down. First, several turn/step boundaries existed BOTH as a durable `SessionEvent` (`turn/start`, `turn/end`, `step/start`, `step/end`) AND as a mirrored `agent/*` emit (`agent/turn-start`, `agent/turn-end`, `agent/step-start`, `agent/step-end`). A consumer had two sources of truth for the same fact, and every lifecycle change had to update both. Second, the upcoming Hooks subsystem needs ONE coherent, documented surface to subscribe to — a plugin author (and the Claude Code / Codex hook bridges built on top) must know, without reading the loop, whether to listen on a session event or an agent event, and why.
 
@@ -22,7 +22,7 @@ This vocabulary is the foundation for interception decisions, the durable `hook/
 
 - **`session/*` — the durable, replayable FACT log.** Owns `SessionEventMap`; every entry is JSON-only (no live objects). One `session/event` emit per append, plus the `session/flush` parallel durability checkpoint. It is also the live transcript feed: a consumer that wants to render or react to what happened subscribes here, so live rendering and replay projections share one path.
 - **`agent/*` — the LIVE runtime surface.** Always carries the live `Agent`. Interception waterfalls (`agent/pre-step`, `agent/request`, `agent/request-error`) transform, reject, or recover; awaited `agent/turn-stopping` observes the stop boundary; transient emits report lifecycle, status, inbox insertion/claim/discard, and errors. Turn and step BOUNDARIES are NOT here — they are durable session events read off `session/event`, as are the token stream (`assistant/chunk`) and mid-turn steering (a `user/message`).
-- **`tools/*` — the tool registry + execution seam.**
+- **`tools/*` — the tool registry and execution pipeline.**
 
 **The boundary rule:** a durable, replayable fact is a `SessionEvent`; a live interception or a transient/live-object signal is an `agent`/`tools` Cordis event. A turn or step boundary is a durable fact, so it lives in the session log and is read off the `session/event` feed — it is NOT mirrored as an `agent/*` emit.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
index 2607e59490..1f6df779fd 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
@@ -10,7 +10,7 @@ harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）
 
 - `session/*` 承载持久的、事件溯源的日志（`SessionEventMap`）。
 - `agent/*` 承载运行时实时信号，向插件传递 `Agent` 句柄。
-- `tools/*` 承载工具注册表与执行 seam。
+- `tools/*` 承载工具注册表与执行流水线。
 
 两个问题促使我们固定语义。第一，若干轮次/步骤边界同时作为持久的 `SessionEvent`（`turn/start`、`turn/end`、`step/start`、`step/end`）和镜像的 `agent/*` emit（`agent/turn-start`、`agent/turn-end`、`agent/step-start`、`agent/step-end`）存在。消费方对同一事实有两个真源，每次生命周期变更都必须同时更新两处。第二，即将到来的钩子子系统需要一个连贯且有文档的订阅表面——插件作者（以及基于其上构建的 Claude Code / Codex 钩子桥接）必须在不阅读循环代码的情况下知道应该监听会话事件还是 agent 事件，以及原因。
 
@@ -21,8 +21,8 @@ harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）
 **三个域，各司其职，以一条边界规则统一。**
 
 - **`session/*`——持久的、可回放的事实日志。** 拥有 `SessionEventMap`；每条记录仅含 JSON（无活对象）。每次追加触发一次 `session/event` emit，加上 `session/flush` 并行持久性检查点。它同时也是实时 transcript（文本记录）源：想渲染或响应已发生事件的消费方在此订阅，因此实时渲染与回放投影共享同一路径。
-- **`agent/*`——运行时实时表面。** 始终携带活的 `Agent`。拦截 waterfall（瀑布式事件）（`agent/pre-step`、`agent/request`、`agent/request-error`）负责变换、拒绝或恢复；awaited `agent/turn-stopping` 观察停止边界；瞬态 emit 报告生命周期、状态、inbox 插入／领取／丢弃与错误。轮次和步骤边界不在此处——它们是持久的会话事件，从 `session/event` 读取；token 流（`assistant/chunk`）和作为一条 `user/message` 的轮次中途 steering（中途引导）同理。
-- **`tools/*`——工具注册表与执行 seam。**
+- **`agent/*`——运行时实时表面。** 始终携带活的 `Agent`。拦截 waterfall（瀑布式事件）（`agent/pre-step`、`agent/request`、`agent/request-error`）负责变换、拒绝或恢复；awaited `agent/turn-stopping` 观察停止边界；瞬态 emit 报告生命周期、状态、inbox 插入／领取／丢弃与错误。轮次和步骤边界不在此处——它们是持久的会话事件，从 `session/event` 读取；token 流（`assistant/chunk`）和中途 steering（以 `user/message` 呈现）同理。
+- **`tools/*`——工具注册表与执行流水线。**
 
 **边界规则：** 持久的、可回放的事实是 `SessionEvent`；实时拦截或瞬态/活对象信号是 `agent`/`tools` Cordis 事件。轮次或步骤边界是持久事实，因此存在于会话日志中并从 `session/event` 源读取——不会被镜像为 `agent/*` emit。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.i18n.yaml
index da7848d581..ceccf93631 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.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 .agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md
-2026-07-02-fs-per-session-cwd.md: d3f54e89e735016a373fa14c60123c681b3e7adf
-2026-07-02-fs-per-session-cwd.zh.md: 86058437a14f64cc7faf6e6ad413c52efba5fd39
+2026-07-02-fs-per-session-cwd.md: 23c9f414590df8c79109e46f24af031b765b8f58
+2026-07-02-fs-per-session-cwd.zh.md: 5e429bbda16c2c7e29114e6d8586c13b658cac0a
diff --git a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md
index d3f54e89e7..23c9f41459 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md
+++ b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md
@@ -26,7 +26,7 @@ Thread the caller's session cwd into path resolution, exactly as `dsh-tool-bash`
 
 ### Why the caller supplies the cwd (not the provider)
 
-The provider seam must not depend on `dsh-agent` / `dsh-session` — it is a text-storage backend that a sandboxed or remote implementation also satisfies, and those have no notion of an "agent session". The tool already receives the `ToolExecution` (`exec`), which carries the agent, so the tool is the right place to project `exec → cwd` and hand the provider a plain string. This is the "explicit > implicit at package seams" convention: the base directory arrives as an explicit argument the provider acts on, not smuggled in by having the provider reach into a session it should not know about. It also matches `dsh-tool-bash` one-to-one, so the two model-facing file surfaces resolve paths identically.
+The provider contract must not depend on `dsh-agent` / `dsh-session` — it is a text-storage backend that a sandboxed or remote implementation also satisfies, and those have no notion of an "agent session". The tool already receives the `ToolExecution` (`exec`), which carries the agent, so the tool is the right place to project `exec → cwd` and hand the provider a plain string. This is the "explicit > implicit at package boundaries" convention: the base directory arrives as an explicit argument the provider acts on, not smuggled in by having the provider reach into a session it should not know about. It also matches `dsh-tool-bash` one-to-one, so the two model-facing file surfaces resolve paths identically.
 
 The default lives in ONE place — the provider's `config.cwd`. `sessionCwd` returns `undefined` rather than `process.cwd()` when there is no session, so the tool never manufactures a base the provider would otherwise choose.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.zh.md b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.zh.md
index 86058437a1..5e429bbda1 100644
--- a/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.zh.md
@@ -26,7 +26,7 @@ ACP（Agent Client Protocol）桥接层为每个会话提供独立的工作区
 
 ### 为何由调用方（而非提供方）提供 cwd
 
-提供方 seam 不得依赖 `dsh-agent`／`dsh-session`——它是一个文本存储后端，沙箱或远程实现同样满足该接口，而这些实现没有「agent 会话」的概念。工具已经接收了 `ToolExecution`（`exec`），其中携带 agent，因此工具是将 `exec → cwd` 投影并向提供方传递一个纯字符串的正确位置。这遵循「包边界处显式优于隐式」的约定：基准目录作为显式参数传入，提供方据此行动，而非让提供方越界去读取它不应知晓的会话。这也与 `dsh-tool-bash` 一一对应，使两个面向模型的文件操作接口以相同方式解析路径。
+提供方约定不得依赖 `dsh-agent`／`dsh-session`——它是一个文本存储后端，沙箱或远程实现同样满足该接口，而这些实现没有「agent 会话」的概念。工具已经接收了 `ToolExecution`（`exec`），其中携带 agent，因此工具是将 `exec → cwd` 投影并向提供方传递一个纯字符串的正确位置。这遵循「包边界处显式优于隐式」的约定：基准目录作为显式参数传入，提供方据此行动，而非让提供方越界去读取它不应知晓的会话。这也与 `dsh-tool-bash` 一一对应，使两个面向模型的文件操作接口以相同方式解析路径。
 
 默认值只存在于一个地方——提供方的 `config.cwd`。`sessionCwd` 在没有会话时返回 `undefined` 而非 `process.cwd()`，因此工具永远不会自行制造一个提供方本应自行选择的基准目录。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
index 9acc4ee6f6..b85c732f6e 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.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 .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
-2026-07-05-reconstructable-requests.md: 3676e4bc7f6d0272f382b13e178f04b16f18f992
-2026-07-05-reconstructable-requests.zh.md: bcae6b941fb0110aa4e5011685365a5edf7512d3
+2026-07-05-reconstructable-requests.md: c971f411eb932cab29d7a52662a0e05a1f638daa
+2026-07-05-reconstructable-requests.zh.md: b788f895cbb33f6ffa59b36430e81384a468f582
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
index 3676e4bc7f..c971f411eb 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
@@ -49,7 +49,7 @@ Like MiniCode, the conversation advances append-only and resets only when model-
 - A request that is not explained by the log cannot be constructed by accident — not by the loop, not by a listener; mutating a built request throws; every header change is a durable, diffable log event.
 - Model-visible context uses logged message channels. `agent.inject()` and tool `additionalContexts` enter the inbox for a later claim, while `agent/pre-step` returns context that must settle with the current claimed batch. Each entered value is a durable sourced `user/message`, paid once and prefix-cached thereafter at the price of accumulating in history until compaction.
 - What still costs full price at the provider is inherent and logged: compaction (its `compact/*` events and replacement entry), a real prompt, tool, or config change (`request/header` with reason `change`), or a process boundary with drift (a differing `resume` snapshot). The provider's own reasoning-content exclusion is managed server-side.
-- `agent/pre-step` is the current-request message seam; direct inbox mutation is the eventual later-request seam.
+- `agent/pre-step` is the current-request message channel; direct inbox mutation is the eventual later-request channel.
 - Tool-result trimming (planned) needs no new mechanism: a logged single-entry surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic.
 - Session logs grow one `request/header` snapshot per loop instance plus snapshots on real changes. This is larger than a delta codec but small beside chunk-heavy logs and retains one replay representation. `SESSION_FORMAT_VERSION` stays `0`; legacy delta events are rejected rather than migrated.
 - Snapshot expected outputs changed once (every transcript gains its header events); the fs-writing fixtures are stored in the normalized authored form with cwd-relative tool arguments, because replay only round-trips cwd-independent argument paths.
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
index bcae6b941f..b788f895cb 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
@@ -47,9 +47,9 @@ Status: implemented
 ## 后果
 
 - 一个日志无法解释的请求不可能被意外构造——无论是循环还是监听器；变异已构建的请求会抛异常；每个 header 变更都是持久的、可 diff 的日志事件。
-- 模型可见上下文使用已记录消息通道。`agent.inject()` 与工具 `additionalContexts` 进入 inbox，等待后续领取；必须与当前已领取批次一起结算的上下文由 `agent/pre-step` 返回。每个进入步骤的值都是带来源的持久 `user/message`，只付出一次代价，此后即被前缀缓存，代价是会在历史中累积直至压缩。
-- 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身对思考内容的排除由服务端管理。
-- `agent/pre-step` 是当前请求的消息 seam；直接修改 inbox 则是最终进入后续请求的 seam。
-- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存失效由相同的压力逻辑批量处理。
+- 模型可见上下文使用已记录消息通道。`agent.inject()` 与工具 `additionalContexts` 进入 inbox，等待后续领取；必须与当前已领取批次一起结算的上下文由 `agent/pre-step` 返回。每个进入步骤的值都是带来源的持久 `user/message`，只付出一次代价并在后续成为可缓存前缀，代价是会在历史中累积直至压缩。
+- 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身的 reasoning-content 排除由服务端管理。
+- `agent/pre-step` 是当前请求的消息通道；直接修改 inbox 则是最终进入后续请求的通道。
+- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存击穿由相同的压力逻辑批量处理。
 - 会话日志每个循环实例增长一个 `request/header` 快照，并在真正变更时增加快照。它比 delta 编解码器更大，但相对分片密集型日志仍然很小，并只保留一种回放表示。`SESSION_FORMAT_VERSION` 保持 `0`；旧的 delta 事件被拒绝而非迁移。
 - 快照预期输出变更一次（每个 transcript（文本记录）增加其 header 事件）；写入文件系统的 fixture（测试前置数据）以规范化的撰写形式存储，工具参数使用 cwd 相对路径，因为回放只对 cwd 无关的参数路径做往返。
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
index 8b3d66c3b0..c85785a097 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.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 .agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
-2026-07-06-timeout-deadline-library.md: 1afb8e326356f012498eed778e9bab1b0be64ea5
-2026-07-06-timeout-deadline-library.zh.md: c6992ba5463122e4eb4ebd1d904d0c0906140353
+2026-07-06-timeout-deadline-library.md: 72f02208f601ff5514fe6ea0006ea922cdbd49b7
+2026-07-06-timeout-deadline-library.zh.md: c4da7f2028abc32d0c393dd1aeb3c59a4c05acec
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
index 1afb8e3263..72f02208f6 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
@@ -97,7 +97,7 @@ The signal only *notifies*; termination is always the listener's job, and the li
 
 ## Consequences
 
-- `runBash`'s outcome no longer independently latches `timedOut` and `aborted`; a timeout and a user abort racing before process close now report a single first-abort cause instead of both being true. The uniform SIGTERM→grace→SIGKILL kill is unchanged, and the seam type `BashRunResult` keeps both booleans (now mutually exclusive), so `dsh-tool-bash`'s result rendering is untouched.
+- `runBash`'s outcome no longer independently latches `timedOut` and `aborted`; a timeout and a user abort racing before process close now report a single first-abort cause instead of both being true. The uniform SIGTERM→grace→SIGKILL kill is unchanged, and the Service Definition type `BashRunResult` keeps both booleans (now mutually exclusive), so `dsh-tool-bash`'s result rendering is untouched.
 - `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. This is the one deviation from the literal proposal shape (which passed `timeoutMs: 0` into `runBash`); an always-0 field read by nothing is dead weight under the per-file coverage gate.
 - web_fetch shed its bespoke controller/timer/listener/reason-recovery; the classifier now keys off the deadline signal (`timeoutOf` + `aborted`) rather than the thrown error's shape, which is robust across both the request-phase reject-with-reason and the read-phase bare-`AbortError`.
 - `AbortSignal.any` and `using`/`Symbol.dispose` enter the repo for the first time here (Node ≥ 24 baseline, already met).
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
index c6992ba546..c4da7f2028 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
@@ -97,7 +97,7 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 
 ## 后果
 
-- `runBash` 的结果不再独立锁存 `timedOut` 和 `aborted`；超时与用户中止在进程关闭前竞争时，现在报告单一的首个 abort 原因，而非两者同时为 true。统一的 SIGTERM→宽限期→SIGKILL 终止路径不变，seam 类型 `BashRunResult` 保留两个布尔值（现在互斥），因此 `dsh-tool-bash` 的结果渲染不受影响。
+- `runBash` 的结果不再独立锁存 `timedOut` 和 `aborted`；超时与用户中止在进程关闭前竞争时，现在报告单一的首个 abort 原因，而非两者同时为 true。统一的 SIGTERM→宽限期→SIGKILL 终止路径不变，Service Definition 类型 `BashRunResult` 保留两个布尔值（现在互斥），因此 `dsh-tool-bash` 的结果渲染不受影响。
 - `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。这是与字面提案形状（向 `runBash` 传入 `timeoutMs: 0`）的唯一偏差；一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
 - web_fetch 去除了其定制的 controller/timer/listener/reason-recovery；分类器现在基于 deadline 信号（`timeoutOf` + `aborted`）而非抛出错误的形状来判断，这在请求阶段的 reject-with-reason 和读取阶段的裸 `AbortError` 两种情况下都是健壮的。
 - `AbortSignal.any` 和 `using`/`Symbol.dispose` 在此首次进入本仓库（Node ≥ 24 基线，已满足）。
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
index 6e7aa8291a..36484da590 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.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 .agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
-2026-07-07-tool-call-timeout-policy.md: b85a4d2d60ef60d9f75bd47d4d405aa55c132af6
-2026-07-07-tool-call-timeout-policy.zh.md: f6a85c13a66689c48b10f160890ce3825125aec1
+2026-07-07-tool-call-timeout-policy.md: d341a2c598765b6de4d2a7e242f38847e48f081b
+2026-07-07-tool-call-timeout-policy.zh.md: 6d10b552b951f428f475323ba115007e39b66aaf
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
index b85a4d2d60..d341a2c598 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
@@ -32,7 +32,7 @@ ctx.tools.execute(exec)
 
 The default behavior is conservative: a tool that declares no `timeoutMs` receives no `TOOL_TIMEOUT` deadline from the plugin.
 
-### The `tools/execute` around seam
+### The `tools/execute` around-dispatch extension point
 
 `@deepseek-ai/dsh-tools` declares a `tools/execute` waterfall whose base `next()` is the dispatch-with-normalization thunk — the same inner `try`/`catch` that turns a thrown tool (or unknown tool) into an `isError` `ToolExecutionResult`. A listener receives `(exec, next)`: it calls `next()` to delegate to dispatch (returning its result, optionally wrapped) or returns a replacement result to short-circuit dispatch. The whole pipeline still sits inside `execute`'s outer try/catch, so a throwing listener becomes an `isError` result, never a turn failure.
 
@@ -101,13 +101,13 @@ A future model-facing grep/glob tool can be implemented on top of `ctx.bash` wit
 
 **Let `timeout-policy` match tool arguments itself.** A rule engine such as "disable timeout when `bash.run_in_background` is true" would make the policy plugin know tool-specific argument semantics. Avoided by not migrating bash to tool-call timeout.
 
-**Use `tools/pre-execute` plus `tools/post-execute` instead of a new around seam.** A pre listener could arm a deadline and mutate `exec.signal`; a post listener could classify and replace. That loses because the deadline lifetime would cross two independent waterfalls: a call-id map, cleanup on every pre-deny/tool-throw/post-throw/dispose path, and ordering rules with every other listener. `tools/pre-execute` is also the allow/deny gate, not an execution wrapper. `tools/execute` gives the timeout one lexical scope: arm, delegate, classify, dispose.
+**Use `tools/pre-execute` plus `tools/post-execute` instead of a new around-dispatch extension point.** A pre listener could arm a deadline and mutate `exec.signal`; a post listener could classify and replace. That loses because the deadline lifetime would cross two independent waterfalls: a call-id map, cleanup on every pre-deny/tool-throw/post-throw/dispose path, and ordering rules with every other listener. `tools/pre-execute` is also the allow/deny gate, not an execution wrapper. `tools/execute` gives the timeout one lexical scope: arm, delegate, classify, dispose.
 
 **Use `Promise.race` to enforce timeouts for non-cooperative tools.** Rejected for the same reason as the timeout-library Agent Note: it returns control to the caller while the underlying process, fetch, or provider operation may still be running. The plugin only sends a signal; termination remains the implementation's responsibility.
 
 ## Consequences
 
-- `@deepseek-ai/dsh-tools` gains an around-dispatch surface after the interception seams deliberately split pre/post tool hooks. Its contract is narrow — wrap registry dispatch, not replace the pre-gate or post-result policy — and the base `next()` is dispatch-with-normalization so a wrapper never sees a raw tool throw.
+- `@deepseek-ai/dsh-tools` gains an around-dispatch surface after the interception points deliberately split pre/post tool hooks. Its contract is narrow — wrap registry dispatch, not replace the pre-gate or post-result policy — and the base `next()` is dispatch-with-normalization so a wrapper never sees a raw tool throw.
 - Multiple `tools/execute` listeners compose by ordinary Cordis waterfall order: a listener that calls `next()` wraps downstream listeners plus dispatch; one that returns without `next()` short-circuits them. A deployment combining timeout with a future retry/sandbox/metrics wrapper chooses semantics by registration order ("timeout covers the whole retry" vs "timeout covers each attempt").
 - Opt-in by declaration is a deliberate misconfiguration risk: a tool can declare a `timeoutMs` without honoring `exec.signal`, and that tool will not stop on timeout. The registry awaits that non-quiescent body rather than racing it, while the plugin contract states that declaring a budget means cooperative; the web tools prove the pattern on tools that already forward the signal.
 - During the transition `bash` and the migrated web tools use different timeout paths on purpose: `TOOL_TIMEOUT` is the model-facing tool-call budget, while `BASH_TIMEOUT` remains the bash backend timeout used by bash and hooks.
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
index f6a85c13a6..6d10b552b9 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
@@ -32,7 +32,7 @@ ctx.tools.execute(exec)
 
 默认行为是保守的：未声明 `timeoutMs` 的工具不会从该插件收到 `TOOL_TIMEOUT` 截止信号。
 
-### `tools/execute` 环绕 seam
+### `tools/execute` 环绕分发扩展点
 
 `@deepseek-ai/dsh-tools` 声明了一个 `tools/execute` waterfall，其基础 `next()` 是带规范化的分发 thunk——即同一个内部 `try`/`catch`，将抛出的工具错误（或未知工具错误）转换为 `isError` 的 `ToolExecutionResult`。监听器接收 `(exec, next)`：调用 `next()` 委托给分发（返回其结果，可选地包装），或返回替代结果以短路分发。整个流水线仍位于 `execute` 的外层 try/catch 内，因此抛出异常的监听器会变成 `isError` 结果，而非轮次失败。
 
@@ -101,13 +101,13 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 
 **让 `timeout-policy` 自行匹配工具参数。** 诸如「当 `bash.run_in_background` 为 true 时禁用超时」之类的规则引擎会让策略插件了解工具特定的参数语义。通过不将 bash 迁移到工具调用超时来规避此问题。
 
-**使用 `tools/pre-execute` 加 `tools/post-execute` 代替新的环绕 seam。** pre 监听器可以启动截止时间并修改 `exec.signal`；post 监听器可以分类并替换。这样做的问题是截止时间的生命周期会跨越两个独立的 waterfall：需要 call-id 映射、在每条 pre-deny/tool-throw/post-throw/dispose（资源释放）路径上清理，以及与其他监听器的排序规则。`tools/pre-execute` 也是允许/拒绝门禁，而非执行包装器。`tools/execute` 给超时一个词法作用域：启动、委托、分类、释放。
+**使用 `tools/pre-execute` 加 `tools/post-execute` 代替新的环绕分发扩展点。** pre 监听器可以启动截止时间并修改 `exec.signal`；post 监听器可以分类并替换。这样做的问题是截止时间的生命周期会跨越两个独立的 waterfall：需要 call-id 映射、在每条 pre-deny/tool-throw/post-throw/dispose（资源释放）路径上清理，以及与其他监听器的排序规则。`tools/pre-execute` 也是允许/拒绝门禁，而非执行包装器。`tools/execute` 给超时一个词法作用域：启动、委托、分类、释放。
 
 **使用 `Promise.race` 对非协作工具强制超时。** 与超时库 Agent Note 相同的理由否决：它在底层进程、fetch 或提供方操作可能仍在运行时就将控制权返回给调用方。插件只发送信号；终止仍是实现方的责任。
 
 ## 后果
 
-- `@deepseek-ai/dsh-tools` 在有意拆分 pre/post 工具钩子的拦截 seam 之后，获得了一个环绕分发接口。其约定是狭窄的——包装注册表分发，而非替代 pre 门禁或 post 结果策略——且基础 `next()` 是带规范化的分发，因此包装器永远不会看到未经处理的工具异常。
+- `@deepseek-ai/dsh-tools` 在拦截点有意拆分 pre/post 工具钩子之后，获得了一个环绕分发接口。其约定是狭窄的——包装注册表分发，而非替代 pre 门禁或 post 结果策略——且基础 `next()` 是带规范化的分发，因此包装器永远不会看到未经处理的工具异常。
 - 多个 `tools/execute` 监听器按普通 Cordis waterfall 顺序组合：调用 `next()` 的监听器包装下游监听器加分发；不调用 `next()` 直接返回的监听器短路它们。一个同时组合超时与未来重试/沙箱/指标包装器的部署通过注册顺序选择语义（「超时覆盖整个重试」vs「超时覆盖每次尝试」）。
 - 按声明加入是一个有意的误配置风险：工具可以声明 `timeoutMs` 但不遵循 `exec.signal`，这样的工具在超时时不会停止。注册表会等待这个尚未完全停稳的工具体结束，而不是与它竞速；同时插件约定声明：声明预算意味着协作；web 工具在已转发信号的工具上验证了这一模式。
 - 过渡期间 `bash` 和已迁移的 web 工具有意使用不同的超时路径：`TOOL_TIMEOUT` 是面向模型的工具调用预算，而 `BASH_TIMEOUT` 仍是 bash 和钩子使用的 bash 后端超时。
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
index dbac0c0688..34abd78451 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.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 .agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
-2026-07-08-tool-output-spill-files.md: 7c0ca90452645d251559be25108d12883210d00e
-2026-07-08-tool-output-spill-files.zh.md: 628023a9d12fec17d32749f9d17a3b701ca3a475
+2026-07-08-tool-output-spill-files.md: 0c8e5e25fc8a229db8fca36512ba781e548b5256
+2026-07-08-tool-output-spill-files.zh.md: 771253335bf5822cb855c63e7dd0bbf0d517bab3
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
index 7c0ca90452..0c8e5e25fc 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md
@@ -22,7 +22,7 @@ A thin spill storage seam plus a default spill policy plugin, in a new `packages
 | `@deepseek-ai/dsh-spill-local` | Local backend: private, session-scoped file storage on the host filesystem. |
 | `@deepseek-ai/dsh-spill-policy` | Tool-result policy plugin: wraps final text results after dispatch and replaces oversized results with a retained preview plus a spill locator. |
 
-There is no dedicated model-facing consumer package. The consumer is the existing `ctx.tools` execution pipeline: `dsh-spill-policy` consumes final tool results through the `tools/post-execute` waterfall, and the model follows the backend-supplied retrieval hint for the returned locator.
+There is no dedicated model-facing Consumer package. The Consumer is the existing `ctx.tools` execution pipeline: `dsh-spill-policy` consumes final tool results through the `tools/post-execute` waterfall, and the model follows the backend-supplied retrieval hint for the returned locator.
 
 ### Spill seam
 
diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
index 628023a9d1..771253335b 100644
--- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 | `@deepseek-ai/dsh-spill-local` | 本地后端：在宿主文件系统中提供私有、会话作用域的文件存储。 |
 | `@deepseek-ai/dsh-spill-policy` | 工具结果策略插件：包装分发后的最终文本结果，并以保留预览和落盘定位符替换超大结果。 |
 
-系统不增加专用的面向模型消费方包。消费方是现有 `ctx.tools` 执行流水线：`dsh-spill-policy` 通过 `tools/post-execute` waterfall（瀑布式事件）使用最终工具结果，模型则按照后端随定位符返回的检索提示读取内容。
+系统不增加专用的面向模型 Consumer 包。Consumer 是现有 `ctx.tools` 执行流水线：`dsh-spill-policy` 通过 `tools/post-execute` waterfall（瀑布式事件）使用最终工具结果，模型则按照后端随定位符返回的检索提示读取内容。
 
 ### 落盘 seam
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
index 2330a5df0c..d658f71140 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.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 .agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 6f18d5da014f35b47c40c541ca75ca5ab81499b2
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 7b6ce75b145e96e58a49331e0390f1d3f82200e4
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: 08715d3ad6ad7a2346327861e7134b10da184f00
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 77b57274d0d931f0ec58fecd3d5f9ca5bba3f624
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
index 6f18d5da01..08715d3ad6 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-10-after-call-compaction-pressure-and-overflow-recove
 
 ## Problem
 
-`agent/pre-step` runs before final request routing and before assistant output, tool results, buffered context, and steering exist. Even with the assembled prompt and session prefix, its pressure view is provisional because `agent/request` can still change routing or call configuration and tool schemas are not frozen with those inputs. Adding fields cannot make pre-call state describe a completed call and couples the generic seam to compaction.
+`agent/pre-step` runs before final request routing and before assistant output, tool results, buffered context, and steering exist. Even with the assembled prompt and session prefix, its pressure view is provisional because `agent/request` can still change routing or call configuration and tool schemas are not frozen with those inputs. Adding fields cannot make pre-call state describe a completed call and couples the generic extension point to compaction.
 
 Successful calls are not the only pressure signal. A provider can reject a request for exceeding its context window before it returns usage, and some successful calls omit usage. The system therefore needs replayable post-call pressure plus a narrow failure-recovery path that preserves the provider error whenever compaction cannot prove useful progress.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
index 7b6ce75b14..77b57274d0 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`agent/pre-step` 运行在最终请求路由之前，也早于 assistant 输出、工具结果、缓冲上下文与 steering（中途引导）的产生。即使它接收已装配提示词与会话前缀，压力视图仍是临时的，因为 `agent/request` 还可以改变路由或调用配置，工具 schema 也没有与这些输入一同冻结。增加字段无法让调用前状态描述已完成调用，还会把通用 seam 与压缩耦合。
+`agent/pre-step` 运行在最终请求路由之前，也早于 assistant 输出、工具结果、缓冲上下文与 steering（中途引导）的产生。即使它接收已装配提示词与会话前缀，压力视图仍是临时的，因为 `agent/request` 还可以改变路由或调用配置，工具 schema 也没有与这些输入一同冻结。增加字段无法让调用前状态描述已完成调用，还会把通用扩展点与压缩耦合。
 
 成功调用也不是唯一的压力信号。提供方可能在返回 usage 之前就因上下文窗口超限拒绝请求，一些成功调用也不提供 usage。因此，系统需要可回放的调用后压力，以及一条狭窄的失败恢复路径；当压缩无法证明取得有效进展时，必须保留原始提供方错误。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
index dcdf18b494..91deb7153c 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.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 .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
-2026-07-12-agent-scope-runtime-design.md: b8f265551c4ebbb94d32b3599959fe6cc4da974d
-2026-07-12-agent-scope-runtime-design.zh.md: 51fc92fcc6da21b163122984f6e2b102b2e65521
+2026-07-12-agent-scope-runtime-design.md: 8903a2fefa83dba042f8105b182e590783a9adde
+2026-07-12-agent-scope-runtime-design.zh.md: d86ab3d8cb9a051d4664aedac812b10b53521f22
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
index b8f265551c..8903a2fefa 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
@@ -226,7 +226,7 @@ After post-execute or outer pipeline normalization, the registry losslessly snap
 
 SystemPrompt first resolves the global-plus-agent sections, variables, and tool providers into a deterministic registry contribution. The scope-filtered `system-prompt/assemble` waterfall may then reorder, replace, add, or remove any section, variable, or schema. Its returned assembly is authoritative; there is no later restoration pass and no finality metadata on ordinary prompt sections, tool definitions, or provider results.
 
-This is a trusted same-process extension seam, not an authority boundary. A listener that changes Code Mode's `run_code` schema or `tools:sdk` instructions, or a structured child's capture schema or instruction, owns preserving a coherent protocol in the assembly it returns. ToolRegistry still reserves `run_code` against ordinary tool registration and restriction because those are registry invariants, but assembly middleware remains free to transform the final model-visible surface.
+This is a trusted same-process extension point, not an authority boundary. A listener that changes Code Mode's `run_code` schema or `tools:sdk` instructions, or a structured child's capture schema or instruction, owns preserving a coherent protocol in the assembly it returns. ToolRegistry still reserves `run_code` against ordinary tool registration and restriction because those are registry invariants, but assembly middleware remains free to transform the final model-visible surface.
 
 Scope solves the real isolation problem directly. Structured-output contributions register in the child's exact scope, while Code Mode derives its transport and SDK from the same resolved tool view. A second named-protection system would need another ownership and collision rule across arbitrary schema providers—including providers that intentionally contribute duplicate names—without creating a new trust boundary.
 
@@ -360,7 +360,7 @@ This splits provider acceptance from publication and forces every consumer to re
 
 ### Restore selected prompt or tool contributions after assembly
 
-A post-waterfall restoration pass would create a second composition rule after the documented cooperative seam. Correctly assigning canonical presence or absence would also require provider ownership and collision rules for arbitrary tool-schema providers, whose ordinary output may contain duplicate names. Scoped registration already supplies the required per-agent isolation, and trusted assembly listeners own the protocol consistency of what they return, so named restoration adds machinery without establishing an independent boundary.
+A post-waterfall restoration pass would create a second composition rule after the documented cooperative waterfall. Correctly assigning canonical presence or absence would also require provider ownership and collision rules for arbitrary tool-schema providers, whose ordinary output may contain duplicate names. Scoped registration already supplies the required per-agent isolation, and trusted assembly listeners own the protocol consistency of what they return, so named restoration adds machinery without establishing an independent boundary.
 
 ### Remove worker/process lifecycle guards with same-process hardening
 
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
index 51fc92fcc6..d86ab3d8cb 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md
@@ -226,7 +226,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造
 
 SystemPrompt 首先将全局加 agent 的段、变量和工具提供方解析为确定性的注册表贡献。作用域过滤的 `system-prompt/assemble` waterfall 随后可以重排、替换、添加或移除任何段、变量或 schema。其返回的组装结果即为权威；没有后续的恢复步骤，普通提示词段、工具定义或提供方结果上也没有终态元数据。
 
-这是一个可信的同进程扩展 seam，而非权限边界。修改 Code Mode 的 `run_code` schema 或 `tools:sdk` 指令，或结构化子级的捕获 schema 或指令的监听器，有责任在其返回的组装中保持协议的一致性。ToolRegistry 仍然保留 `run_code` 不受普通工具注册和限制影响，因为那些是注册表不变式，但 assembly 中间件仍然可以自由变换最终的模型可见表面。
+这是一个可信的同进程扩展点，而非权限边界。修改 Code Mode 的 `run_code` schema 或 `tools:sdk` 指令，或结构化子级的捕获 schema 或指令的监听器，有责任在其返回的组装中保持协议的一致性。ToolRegistry 仍然保留 `run_code` 不受普通工具注册和限制影响，因为那些是注册表不变式，但 assembly 中间件仍然可以自由变换最终的模型可见表面。
 
 Scope 直接解决了真正的隔离问题。结构化输出贡献注册在子级的精确作用域中，而 Code Mode 从同一个已解析的工具视图派生其传输和 SDK。第二套命名保护系统需要另一套所有权和碰撞规则来覆盖任意 schema 提供方（包括有意贡献重复名称的提供方），却不创建新的信任边界。
 
@@ -360,7 +360,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进
 
 ### 在 assembly 之后恢复选定的提示词或工具贡献
 
-Waterfall 之后的恢复步骤会在文档化的协作式 seam 之后创建第二套组合规则。正确分配规范的存在或缺失还需要为任意工具 schema 提供方制定所有权和碰撞规则，而这些提供方的普通输出可能包含重复名称。作用域注册已经提供了所需的按 agent 隔离，可信的 assembly 监听器拥有其返回内容的协议一致性，因此命名恢复增加了机制却不建立独立边界。
+Waterfall 之后的恢复步骤会在文档化的协作式 waterfall 之后创建第二套组合规则。正确分配规范的存在或缺失还需要为任意工具 schema 提供方制定所有权和碰撞规则，而这些提供方的普通输出可能包含重复名称。作用域注册已经提供了所需的按 agent 隔离，可信的 assembly 监听器拥有其返回内容的协议一致性，因此命名恢复增加了机制却不建立独立边界。
 
 ### 用同进程加固替代 worker/进程生命周期守卫
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
index 6ed066b24a..dd7ff64291 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.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 .agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
-2026-07-14-provider-routed-llm-adapters.md: bb516a39b6c7303d125575bbd3d4138f9af65f7d
-2026-07-14-provider-routed-llm-adapters.zh.md: 2b6af0d509c28cb79dcd3342a007be8e54799ebc
+2026-07-14-provider-routed-llm-adapters.md: 8bd34126d05140e486cd170bfc9255f0962dc413
+2026-07-14-provider-routed-llm-adapters.zh.md: 09d9032da5845d3e416dcfa047fde8e6527025b4
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
index bb516a39b6..8bd34126d0 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md
@@ -28,7 +28,7 @@ A provider has exactly one adapter owner in a Cordis context. `dsh-llm-deepseek`
 
 ### Explicit pi-ai provider profiles
 
-`dsh-llm-pi-ai` takes one non-empty list of provider profiles. Provider names must be unique within the list and present in pi-ai's `getProviders()` result. Each profile contains the provider name plus optional `apiKey`, `baseURL`, headers, reasoning level and budgets, cache retention, transport, SDK timeouts, a Harness stream-idle timeout, and a provider-owned `retryPolicy`. The adapter forces pi-ai's `maxRetries` to zero so one `stream()` call makes one visible provider attempt, while `dsh-llm-retry` executes the resolved policy at the agent failed-step seam. Credentials are never global: an explicit key applies only to its profile, while an absent key lets pi-ai resolve its standard environment variable, OAuth token, AWS credential chain, Google ADC, or other provider-native ambient authentication. An explicitly empty key is invalid configuration rather than an environment fallback.
+`dsh-llm-pi-ai` takes one non-empty list of provider profiles. Provider names must be unique within the list and present in pi-ai's `getProviders()` result. Each profile contains the provider name plus optional `apiKey`, `baseURL`, headers, reasoning level and budgets, cache retention, transport, SDK timeouts, a Harness stream-idle timeout, and a provider-owned `retryPolicy`. The adapter forces pi-ai's `maxRetries` to zero so one `stream()` call makes one visible provider attempt, while `dsh-llm-retry` executes the resolved policy at the agent failed-step extension point. Credentials are never global: an explicit key applies only to its profile, while an absent key lets pi-ai resolve its standard environment variable, OAuth token, AWS credential chain, Google ADC, or other provider-native ambient authentication. An explicitly empty key is invalid configuration rather than an environment fallback.
 
 The plugin registers all configured provider names against one `PiAiAdapter` in one all-or-nothing call. A request uses its provider to select the matching profile and finds its model in `getModels(provider)` to obtain the catalog descriptor. An unknown provider fails at plugin load; an unknown model fails before network I/O with `UNKNOWN_MODEL`. The catalog object is never mutated. When a profile supplies `baseURL`, the adapter clones the selected descriptor and overrides only `baseUrl`, so a private endpoint can retain pi-ai's API, capabilities, compatibility flags, context limits, and reasoning map. The private endpoint must implement the selected provider's protocol, and the model id must still exist in the installed pi-ai catalog.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
index 2b6af0d509..09d9032da5 100644
--- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ### 显式 pi-ai 提供方配置
 
-`dsh-llm-pi-ai` 接受一个非空的提供方配置列表。列表内的提供方名称必须唯一，并且存在于 pi-ai 的 `getProviders()` 结果中。每项配置包含提供方名称，以及可选的 `apiKey`、`baseURL`、headers、推理级别和预算、缓存保留设置、传输方式、SDK 超时、Harness 流空闲超时，以及由提供方拥有的 `retryPolicy`。适配器强制将 pi-ai 的 `maxRetries` 设为零，使一次 `stream()` 调用只发起一次可见的提供方请求；`dsh-llm-retry` 则在 agent 失败步骤 seam 上执行解析后的策略。凭据不设全局值：显式密钥仅对所属配置生效；未提供密钥时，pi-ai 使用标准环境变量、OAuth token、AWS 凭据链、Google ADC 或其他提供方原生环境认证。显式空密钥属于无效配置，不会回退到环境认证。
+`dsh-llm-pi-ai` 接受一个非空的提供方配置列表。列表内的提供方名称必须唯一，并且存在于 pi-ai 的 `getProviders()` 结果中。每项配置包含提供方名称，以及可选的 `apiKey`、`baseURL`、headers、推理级别和预算、缓存保留设置、传输方式、SDK 超时、Harness 流空闲超时，以及由提供方拥有的 `retryPolicy`。适配器强制将 pi-ai 的 `maxRetries` 设为零，使一次 `stream()` 调用只发起一次可见的提供方请求；`dsh-llm-retry` 则在 agent 失败步骤扩展点上执行解析后的策略。凭据不设全局值：显式密钥仅对所属配置生效；未提供密钥时，pi-ai 使用标准环境变量、OAuth token、AWS 凭据链、Google ADC 或其他提供方原生环境认证。显式空密钥属于无效配置，不会回退到环境认证。
 
 插件通过一次全有或全无调用，将所有已配置的提供方名称注册到同一个 `PiAiAdapter`。请求按 provider 选择对应配置，并在 `getModels(provider)` 中查找模型以取得目录描述符。未知提供方会在插件加载时失败；未知模型会在网络 I/O 前以 `UNKNOWN_MODEL` 失败。适配器不会修改目录对象。当配置提供 `baseURL` 时，适配器复制选中的描述符，仅覆盖 `baseUrl`，使私有端点保留 pi-ai 的 API、能力、兼容标志、上下文限制与推理映射。私有端点必须实现所选提供方的协议，模型 ID 也仍须存在于已安装的 pi-ai 目录中。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml
index f38ba32c11..02d531f642 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.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 .agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
-2026-07-15-llm-model-catalog-and-acp-selection.md: 41174209d2c44bedb5dd0615c5f877ecebd43639
-2026-07-15-llm-model-catalog-and-acp-selection.zh.md: 43442487649f7a552d66bd66b64e0e5072f5e00b
+2026-07-15-llm-model-catalog-and-acp-selection.md: 77f8e379e2b07ecf4e67fa7197752543cfedd6dd
+2026-07-15-llm-model-catalog-and-acp-selection.zh.md: ce4a04a66e345834bc2b16b743be89dc7a0b9424
diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
index 41174209d2..77f8e379e2 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-15-llm-model-catalog-and-acp-selection.zh.md)
 
 ## Problem
 
-Provider-routed adapters let every request choose `provider + model`, but `LlmService` exposed only routing and streaming. A UI could not discover which providers were registered or which models an adapter was prepared to recommend. ACP clients therefore received no `model` session config option, so Zed, JetBrains, and VS Code integrations had no model list even though the request seam already supported runtime switching.
+Provider-routed adapters let every request choose `provider + model`, but `LlmService` exposed only routing and streaming. A UI could not discover which providers were registered or which models an adapter was prepared to recommend. ACP clients therefore received no `model` session config option, so Zed, JetBrains, and VS Code integrations had no model list even though the LLM service already supported runtime switching.
 
 Model discovery cannot become request validation. The hand-written DeepSeek adapter deliberately forwards arbitrary model ids to a public or private endpoint, while pi-ai has a finite installed catalog that is authoritative for its own request resolution. Treating one shared catalog as a whitelist would remove the private-endpoint behavior that provider routing was designed to preserve.
 
@@ -50,7 +50,7 @@ The request header remains the durable source of truth. When a selection is actu
 
 ## Consequences
 
-- Any adapter can expose a dynamic model list without leaking provider-library types into the core seam.
+- Any adapter can expose a dynamic model list without leaking provider-library types into the LLM Service Definition.
 - Catalog consumers must treat absence as “not advertised,” never “invalid request.”
 - pi-ai adapters expose their installed provider catalogs; hand-written DeepSeek deployments list known choices explicitly and retain arbitrary model support.
 - Human-facing catalog consumers own their selection interaction. ACP uses its fixed deployment target and does not widen the protocol with model discovery.
diff --git a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
index 4344248764..ce4a04a66e 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 ## 问题
 
-基于提供方路由的适配器允许每次请求选择 `provider + model`，但 `LlmService` 只暴露路由和流式调用。UI 无法发现已注册的提供方，也无法知道适配器愿意推荐哪些模型。因此，ACP 客户端收不到 `model` 会话配置项；即使请求 seam 已经支持运行时切换，Zed、JetBrains 和 VS Code 集成仍没有模型列表。
+基于提供方路由的适配器允许每次请求选择 `provider + model`，但 `LlmService` 只暴露路由和流式调用。UI 无法发现已注册的提供方，也无法知道适配器愿意推荐哪些模型。因此，ACP 客户端收不到 `model` 会话配置项；即使 LLM 服务已经支持运行时切换，Zed、JetBrains 和 VS Code 集成仍没有模型列表。
 
 模型发现不能变成请求校验。手写 DeepSeek 适配器会把任意模型 ID 原样转发给公开或私有端点，而 pi-ai 的有限安装目录则是其自身请求解析的权威依据。将共享目录视为白名单，会破坏提供方路由需要保留的私有端点能力。
 
@@ -50,7 +50,7 @@ ACP 自动化传输层不是目录消费方。它通过部署配置为新创建
 
 ## 结果
 
-- 任意适配器都能暴露动态模型列表，无需把提供方库类型泄漏到核心 seam。
+- 任意适配器都能暴露动态模型列表，无需把提供方库类型泄漏到 LLM Service Definition。
 - 目录消费方必须把缺失理解为「未展示」，而不是「请求无效」。
 - pi-ai 适配器会暴露其已安装的提供方目录；手写 DeepSeek 部署显式列出已知选项，同时保留对任意模型的支持。
 - 面向人类的目录消费方拥有各自的选择交互。ACP 使用固定部署目标，不会为模型发现扩大协议范围。
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index ebf474f78b..03b17f5f33 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: 63cec0a4e349ffc5be27a84e955b15e9168f898b
-2026-07-15-lsp-capability-seam.zh.md: fa82e29e0252b612ae38357c363478f1cbad9ead
+2026-07-15-lsp-capability-seam.md: 65d547a51568cca43fd8b2887bfe9a61c512b34d
+2026-07-15-lsp-capability-seam.zh.md: a9dcedaa80742bb338dbca4c0c532ca6e7cb2655
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index 63cec0a4e3..65d547a515 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -79,7 +79,7 @@ interface LspService {
 
 Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `findReferences` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`; navigation results carry the provider's canonical workspace URI so consumers relativize file URIs in the execution world's namespace. The seam exposes no protocol types, process or document controls, or generic request escape hatch.
 
-`dsh-lsp-local` owns server configuration, JSON-RPC, process and transient-document state, and protocol translation. It reads through `ctx.fs` and launches through `ctx.subprocess`, depending on their interface packages rather than concrete providers; the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) owns that pairing. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider.
+`dsh-lsp-local` owns server configuration, JSON-RPC, process and transient-document state, and protocol translation. It reads through `ctx.fs` and launches through `ctx.subprocess`, depending on their Service Definition packages rather than concrete providers; the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md) owns that pairing. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider.
 
 ## Model-facing contract
 
@@ -155,7 +155,7 @@ The provider trusts its configured server. Its filesystem visibility and process
 
 **Expose `resolve(request)` / `query(spec)`.** With no defaulted fields, resolution would only expose provider selection, and a public spec could outlive provider disposal or replacement. One operation keeps selection and invocation atomic to the registration lifetime.
 
-**Wrap the signal in a per-seam execution-context object.** Web passes a bare `AbortSignal`; wrapping this single field would add unexplained asymmetry. `query()` gains a context object only when another field requires it.
+**Wrap the signal in an LSP execution-context object.** Web passes a bare `AbortSignal`; wrapping this single field would add unexplained asymmetry. `query()` gains a context object only when another field requires it.
 
 **Read through the model-facing `read` tool.** Rejected because tool output is windowed, numbered, transcript-visible, and observed. The provider consumes streamed full text directly through the same `ctx.fs` execution world used by its subprocess.
 
@@ -178,7 +178,7 @@ The provider trusts its configured server. Its filesystem visibility and process
 - Registry tests pin atomic reservation/release, order-independent selection, and structured unavailable, disposed, conflict, and unsupported-operation errors.
 - Fake-stdio tests pin exact initialization capabilities, four protocol mappings, `Location`/`LocationLink` and hover normalization, and `findReferences` mapping to `references.includeDeclaration`.
 - Synchronization tests pin UTF-16 negotiation and conversion, supported and rejected `textDocumentSync` forms, blocked and failed open writes, balanced transient open/close, close-write failure, and malformed-response rejection.
-- Timeout tests pin one `TOOL_TIMEOUT` budget, unclassified upstream cancellation, no hidden seam deadline, and bounded awaited teardown.
+- Timeout tests pin one `TOOL_TIMEOUT` budget, unclassified upstream cancellation, no hidden LSP deadline, and bounded awaited teardown.
 - Lifecycle tests pin startup single-flight, complete-lifecycle serialization with fresh queued source reads, cross-workspace parallelism, abortable queues, crash replacement without replay, failed-stdin teardown, and quiescent disposal.
 - Filesystem-host tests pin session-cwd requirements, provider-owned containment and URI rendering, bounded document reads, unformatted source, and no `fs/observed` event.
 - A keyless pinned TypeScript real-server e2e exercises all four operations; runnable configuration uses the same explicit provider mapping.
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index fa82e29e02..a9dcedaa80 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -79,7 +79,7 @@ interface LspService {
 
 映射键规范化为带前导点的小写扩展名，并按 `filePath` 的最后一个扩展名选择；语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`findReferences` 始终包含声明：提供方在内部执行该约束，本地映射设置 `context.includeDeclaration: true`，调用方不能配置。封闭结果联合将导航统一为位置，将 `hover` 统一为内容或 `null`；导航结果携带提供方的规范工作区 URI，使消费方在执行世界的命名空间内相对化文件 URI。服务边界不公开协议类型、进程或文档控制，也不提供通用请求逃生口。
 
-`dsh-lsp-local` 负责服务器配置、JSON-RPC、进程与临时文档状态和协议转换。它通过 `ctx.fs` 读取，通过 `ctx.subprocess` 启动，只依赖二者的接口包而非具体提供方；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)负责定义这种配对。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
+`dsh-lsp-local` 负责服务器配置、JSON-RPC、进程与临时文档状态和协议转换。它通过 `ctx.fs` 读取，通过 `ctx.subprocess` 启动，只依赖二者的 Service Definition 包而非具体提供方；[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)负责定义这种配对。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置；如果后续映射无效或发生冲突，插件会撤销此前的注册，并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`，通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区，其取值方式与文件系统工具一致，也不导入提供方。
 
 ## 面向模型的约定
 
@@ -155,7 +155,7 @@ interface LspToolInput {
 
 **公开 `resolve(request)` / `query(spec)`。** 没有需要填充默认值的字段时，resolve 只会暴露提供方选择，而公开 spec 可能活过提供方释放或替换。单一操作让选择与调用共用注册生命周期。
 
-**将信号包装为每服务边界的执行上下文对象。** Web 传递裸 `AbortSignal`；仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时，`query()` 才引入上下文对象。
+**将信号包装为 LSP 执行上下文对象。** Web 传递裸 `AbortSignal`；仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时，`query()` 才引入上下文对象。
 
 **通过面向模型的 `read` 工具读取。**拒绝，因为工具输出带窗口与行号，会进入 transcript 且已被观察。提供方直接通过子进程所用的同一 `ctx.fs` 执行环境消费流式传输的完整文本。
 
@@ -178,7 +178,7 @@ interface LspToolInput {
 - 注册表测试固定原子占用/释放、不受顺序影响的选择，以及结构化的不可用、已释放、冲突和不支持操作错误。
 - 测试用 stdio server 固定精确的初始化能力、四种协议映射、`Location`/`LocationLink` 与 `hover` 归一化，以及 `findReferences` 到 `references.includeDeclaration` 的映射。
 - 同步测试固定 UTF-16 协商与转换、受支持和被拒绝的 `textDocumentSync` 形式、打开写入阻塞与失败、配对的临时打开/关闭、关闭写入失败和错误响应拒绝。
-- 超时测试固定一个 `TOOL_TIMEOUT` 预算、不对上游取消错误分类、服务边界无隐藏截止时间，以及受限且等待完成的清理。
+- 超时测试固定一个 `TOOL_TIMEOUT` 预算、不对上游取消错误分类、LSP 无隐藏截止时间，以及受限且等待完成的清理。
 - 生命周期测试固定启动 single-flight、完整生命周期串行化及排队查询读取最新源文件、跨工作区并行、可取消队列、崩溃后不重放的替换、stdin 失败后的进程拆除，以及释放后完全停稳。
 - 文件系统宿主测试固定 session cwd 要求、提供方自有的 containment 与 URI 渲染、有界文档读取、无格式源文本和不发送 `fs/observed`。
 - 无密钥且固定版本的 TypeScript 真实服务器 e2e 覆盖四种操作；可运行配置使用同一项显式提供方映射。
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
index f683189f93..19f77344e1 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.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 .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
-2026-07-16-explicit-turn-cancellation.md: 2b7cb8cc77184edf1331764d28aefe748c1614a1
-2026-07-16-explicit-turn-cancellation.zh.md: 0b9a06c0ae340a41eab9d6bff6126996bfc63bcf
+2026-07-16-explicit-turn-cancellation.md: 5d7b5856ceebd3dc49564c1800004188da162fd8
+2026-07-16-explicit-turn-cancellation.zh.md: ba20b80f3c280087d71688ef4596fb075fa5782b
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
index 2b7cb8cc77..5d7b5856ce 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
@@ -12,7 +12,7 @@ The [initiating Agent scope decision](2026-07-15-agent-initiator-scope.md) inten
 
 ## Decision
 
-Agent owns the runtime-only `AgentCancelCause` union `{ kind: 'user' } | { kind: 'parent' }`; `agent.cancel()` defaults to `user`. TypeScript enforces that vocabulary at this typed same-process seam, with no runtime validator, fallback, or special compatibility contract for untyped callers. An active `TurnCancellation` copies the typed discriminant into a fresh frozen signal reason; idle cancellation has no holder to mutate and does not arm later work.
+Agent owns the runtime-only `AgentCancelCause` union `{ kind: 'user' } | { kind: 'parent' }`; `agent.cancel()` defaults to `user`. TypeScript enforces that vocabulary at this typed same-process boundary, with no runtime validator, fallback, or special compatibility contract for untyped callers. An active `TurnCancellation` copies the typed discriminant into a fresh frozen signal reason; idle cancellation has no holder to mutate and does not arm later work.
 
 An interrupted live turn ends with the coarse durable `{ kind: 'aborted' }` outcome. The terminal event records what happened to the turn, while the runtime signal identifies who requested cancellation; it does not duplicate `user` or `parent` into replay. Session seed/load rejects legacy aborted records with a reason or any other extra field, so replay cannot reintroduce caller-owned cancellation detail. The process-local `agent/cancel-requested` notification is not durable; a future audit requirement uses a separate durable control-request event so a request and its eventual outcome remain distinct. Durable events contain no stack, signal, error object, free-form cancellation text, or backend-private detail.
 
@@ -20,7 +20,7 @@ AgentLoop privately owns one `TurnCancellation` per prospective turn. It install
 
 The driver keeps only a cause-less pre-run marker for queued work cancelled before a turn is claimed. An effective `cancel()` emits the observe-only `agent/cancel-requested` notification with its resolved typed cause before clearing queued and steering work or aborting the holder; notification failures cannot veto the stop, and an idle call emits nothing. Work synchronously queued by a notification observer is included in that clear, while work queued by a later signal abort observer is latched and runs when the aborted activity converges to idle — a `disposed` cancel leaves it parked ([cancel-convergence wake latch](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)). If a `running` listener synchronously cancels old work and sends a replacement, the driver discards the aborted holder and creates a fresh one for the replacement. Repeated cancellation is first-wins for the active holder, while later calls may still clear newly queued pending work.
 
-The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining seams keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's process-group kill and join boundary. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn.
+The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining APIs keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's process-group kill and join boundary. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn.
 
 `ctx.agents` continues to carry only the initiating Agent. Ambient Agent presence does not imply liveness, a current turn, or cancellation authority. The cause reader is private to the loop and states the machine-private slot invariant (only `cancel()` aborts a turn controller, always with a canonical frozen cause) instead of re-validating the reason structurally; no public helper reads a cause off an arbitrary signal. Concurrent Agents isolate both their initiator identities and their turn signals; a child driver shadows the parent initiator while its parent request signal still travels through the subagent seam.
 
@@ -46,10 +46,10 @@ Initiator-scope tests assert that every hook still observes the exact Agent and
 
 **Expose public turn or step context wrappers.** Existing seams already identify Agent, turn, and step. A wrapper would widen every API, duplicate ownership, and tempt callers to treat a captured object as durable authority.
 
-**Abandon uncooperative work after a grace period.** Returning idle while same-process work still runs breaks teardown and resource-ownership guarantees. Hard termination requires a worker or process isolation boundary and is outside this control seam.
+**Abandon uncooperative work after a grace period.** Returning idle while same-process work still runs breaks teardown and resource-ownership guarantees. Hard termination requires a worker or process isolation boundary and is outside this control boundary.
 
 ## Consequences
 
-Cancellation has one runtime owner, one signal per live turn, and one typed runtime caller vocabulary. Session retains the coarse `aborted` outcome that its consumers actually use, rejects reason-bearing legacy forms, and stays isolated from runtime objects. Cooperative cancellation reaches every asynchronous turn seam, including work before the first step and after the last one, while terminal publication and persistence remain outside its authority.
+Cancellation has one runtime owner, one signal per live turn, and one typed runtime caller vocabulary. Session retains the coarse `aborted` outcome that its consumers actually use, rejects reason-bearing legacy forms, and stays isolated from runtime objects. Cooperative cancellation reaches every asynchronous turn extension point, including work before the first step and after the last one, while terminal publication and persistence remain outside its authority.
 
 The explicit signal adds parameters to several public events and requires plugins to forward cancellation deliberately. This is intentional: authority is visible at the call boundary, lifetime matches the turn, and stale ambient descendants cannot acquire control. Uncooperative in-process work may delay cancellation, but the reported quiescent state remains truthful.
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
index 0b9a06c0ae..ba20b80f3c 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`；`agent.cancel()` 默认使用 `user`。TypeScript 在这个类型化的同进程 seam 中强制执行该词汇，不提供运行时校验器、后备行为，也不为无类型调用方提供特殊兼容性约定。活跃的 `TurnCancellation` 会把类型化判别字段复制为一个全新且已冻结的 signal 原因；空闲状态下没有可修改的持有者，也不会让后续工作预先进入取消状态。
+Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`；`agent.cancel()` 默认使用 `user`。TypeScript 在这个类型化的同进程边界中强制执行该词汇，不提供运行时校验器、后备行为，也不为无类型调用方提供特殊兼容性约定。活跃的 `TurnCancellation` 会把类型化判别字段复制为一个全新且已冻结的 signal 原因；空闲状态下没有可修改的持有者，也不会让后续工作预先进入取消状态。
 
 正在运行的轮次被中断后，以粗粒度的持久化结果 `{ kind: 'aborted' }` 结束。终态事件记录轮次发生了什么，运行时 signal 标识谁请求了取消；回放不会重复保存 `user` 或 `parent`。会话 seed/load 会拒绝携带取消原因或任何其他额外字段的旧式中止记录，因此回放无法重新引入由调用方持有的取消细节。仅限进程内的 `agent/cancel-requested` 通知不会持久化；未来若有审计需求，应使用独立的持久化控制请求事件，让请求与最终结果保持为两项事实。持久化事件不包含调用栈、signal、错误对象、自由文本取消原因或后端私有细节。
 
@@ -20,7 +20,7 @@ AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它
 
 对于轮次被认领前已取消的排队工作，驱动器只保留一个不携带取消原因的运行前标记。实际生效的 `cancel()` 会先发出仅供观察的 `agent/cancel-requested` 通知并携带最终确定的类型化取消原因，然后才清除排队工作和 steering（中途引导）工作或中止持有者；通知失败不能阻止此次停止，空闲状态下调用则不发出任何通知。通知观察者同步加入队列的工作也会被这次清除，而稍后由 signal 中止观察者加入队列的工作会被锁存，并在被中止的活动收敛到空闲时执行——`disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。若 `running` 监听器同步取消旧工作并发送替代提示词，驱动器会丢弃已中止的持有者，并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先，后续调用仍可清除新入队的待处理工作。
 
-显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 seam 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。步骤前处理入口、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
+显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 API 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。pre-step 进入决策、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
 
 `ctx.agents` 仍只携带发起 Agent。环境中的 Agent 并不代表存活、当前轮次或取消权限。cause 读取器是 loop 私有的，它直接陈述机器私有的 slot 不变量（只有 `cancel()` 会中止轮次控制器，且总是携带规范的冻结 cause），而不是对 reason 做结构化再校验；不存在从任意 signal 读取 cause 的公开辅助函数。并发 Agent 会同时隔离各自的发起方身份和轮次 signal；子驱动会遮蔽父发起方，而父请求 signal 仍通过 subagent seam 传递。
 
@@ -30,7 +30,7 @@ Agent dispose（资源释放）会在活跃持有者上请求仅用于运行时
 
 ## 验证
 
-约定测试验证类型化调用方联合类型、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在步骤前处理、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal；并断言同一轮次使用一个 signal，不同轮次使用全新的 signal，终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。
+约定测试验证类型化调用方联合类型、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在 pre-step、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal；并断言同一轮次使用一个 signal，不同轮次使用全新的 signal，终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。
 
 发起方作用域测试断言所有钩子仍观察到同一个 Agent 且没有环境中的轮次 signal，并发 Agent 保持独立的身份与 signal，嵌套子驱动只遮蔽身份。竞态测试覆盖空闲状态取消、运行前取消、从 `running` 监听器提交替代提示词、重复取消以及取消与 dispose 竞争下的完全停稳。
 
@@ -46,10 +46,10 @@ Agent dispose（资源释放）会在活跃持有者上请求仅用于运行时
 
 **公开轮次或步骤上下文包装类型。** 现有 seam 已经标识 Agent、轮次和步骤。包装类型会加宽所有 API、重复归属，并诱导调用方把捕获的对象当成持久权限。
 
-**在宽限期后放弃不协作的工作。** 同进程工作仍在运行时就报告空闲状态，会破坏资源清理与资源归属保证。硬终止需要 worker 或进程隔离边界，不属于该控制 seam。
+**在宽限期后放弃不协作的工作。** 同进程工作仍在运行时就报告空闲状态，会破坏资源清理与资源归属保证。硬终止需要 worker 或进程隔离边界，不属于该控制边界。
 
 ## 后果
 
-取消拥有一个运行时归属方、每个活跃轮次一个 signal，以及一套类型化的运行时调用方词汇。会话保留其消费方实际使用的粗粒度 `aborted` 结果，拒绝携带原因的旧式形式，并与运行时对象保持隔离。协作式取消覆盖每个异步轮次 seam，包括第一个步骤之前和最后一个步骤之后的工作，而终态发布和持久化仍在其权限范围之外。
+取消拥有一个运行时归属方、每个活跃轮次一个 signal，以及一套类型化的运行时调用方词汇。会话保留其消费方实际使用的粗粒度 `aborted` 结果，拒绝携带原因的旧式形式，并与运行时对象保持隔离。协作式取消覆盖每个异步轮次扩展点，包括第一个步骤之前和最后一个步骤之后的工作，而终态发布和持久化仍在其权限范围之外。
 
 显式 signal 会给多个公开事件增加参数，并要求插件有意识地转发取消。这是有意设计：权限在调用边界可见，生命周期与轮次匹配，陈旧的环境异步后代无法获得控制能力。不协作的进程内工作可能延迟取消，但所报告的完全停稳仍然真实。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
index a0956af598..a1f8d14b76 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.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 .agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
-2026-07-19-cooperative-tool-cancellation.md: 4e82452cd6883593d4693766bea803c97fa4c977
-2026-07-19-cooperative-tool-cancellation.zh.md: aa94fd9f3d32167dc7d6b906ff14a6afd36ccb32
+2026-07-19-cooperative-tool-cancellation.md: 781202688a5cbcd7076ee694fc7dd9489683d8e8
+2026-07-19-cooperative-tool-cancellation.zh.md: 8e61d6fb4eb99c5d6726e1b1af15765b84c34b03
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
index 4e82452cd6..781202688a 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
@@ -42,7 +42,7 @@ The registry first creates the call token, snapshots the visible definition's op
 
 Once a tool body starts, the registry awaits it. Cancellation reaches the body through the fused signal but never races or abandons its promise. A cooperative implementation stops or forwards cancellation and settles after its owned work reaches quiescence; an uncooperative same-process implementation can keep the registry pending indefinitely. Process, worker, network, and provider layers retain responsibility for their own termination mechanisms.
 
-This decision requires cancellation at the tool invocation seam only. Making signals required on asynchronous capabilities reachable from tool bodies is a separate migration proposed in [Required cancellation through tool-reachable capability seams](../../proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md).
+This decision requires cancellation at the tool invocation boundary only. Making signals required on asynchronous capabilities reachable from tool bodies is a separate migration proposed in [Required cancellation through tool-reachable capability seams](../../proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md).
 
 ## Verification
 
@@ -54,7 +54,7 @@ No registry test can prove that arbitrary third-party same-process code observes
 
 **Keep the signal optional and synthesize a fallback.** Rejected because a registry-owned fallback has no caller lifetime to represent and preserves the exact omission the type should prevent.
 
-**Validate `AbortSignal` at runtime.** Rejected because this is a typed same-process seam, not a serialization boundary. Runtime checks would duplicate the static contract without making cooperative use enforceable.
+**Validate `AbortSignal` at runtime.** Rejected because this is a typed same-process boundary, not a serialization boundary. Runtime checks would duplicate the static contract without making cooperative use enforceable.
 
 **Add `supportsCancellation` metadata, callback-arity checks, or signal-use linting.** Rejected because none proves that asynchronous work observes or correctly forwards cancellation. Availability is a type contract; behavior remains a tool and capability responsibility.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
index aa94fd9f3d..8e61d6fb4e 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
@@ -42,7 +42,7 @@ Status: implemented
 
 工具主体一旦启动，注册表就会等待它完成。取消通过融合信号到达工具主体，但注册表不会与其 promise 竞速或丢弃该 promise。协作式实现会停止自身工作或继续转发取消，并在所持有的工作完全停稳后完成；不协作的同进程实现可能让注册表无限期保持等待。进程、worker、网络和提供方层仍负责各自的终止机制。
 
-这项决策只要求工具调用 seam 携带取消信号。让工具主体可达的异步能力也必须接收信号，属于另一项迁移，见提议中的[工具可达能力 seam 中的必填取消](../../proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md)。
+这项决策只要求工具调用边界携带取消信号。让工具主体可达的异步能力也必须接收信号，属于另一项迁移，见提议中的[工具可达能力 seam 中的必填取消](../../proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md)。
 
 ## 验证
 
@@ -54,7 +54,7 @@ Status: implemented
 
 **保留可选信号并生成后备值。** 不予采纳，因为注册表持有的后备信号不代表任何调用方生命周期，也会保留类型系统本应阻止的缺失情况。
 
-**在运行时校验 `AbortSignal`。** 不予采纳，因为这是类型化同进程 seam，不是序列化边界。运行时检查只会重复静态约定，仍无法强制实现协作式使用信号。
+**在运行时校验 `AbortSignal`。** 不予采纳，因为这是类型化同进程边界，不是序列化边界。运行时检查只会重复静态约定，仍无法强制实现协作式使用信号。
 
 **添加 `supportsCancellation` 元数据、回调参数数量检查或信号使用 lint。** 不予采纳，因为这些方法都无法证明异步工作会观察或正确转发取消。信号可用性属于类型约定；具体行为仍由工具和能力负责。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index c7f632c50e..4632c7e1ac 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: ceb8e5db593aef14d6db259f6293381fe83defe2
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: bc0b6a9e883a1ce7d2990f8dc7284035649ac215
+2026-07-19-gui-layering-and-rpc-protocol.md: ebab36e66768f6216603923d2313e77eaf412ae1
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 308446e48772c3bb8d6e0b5851dd526af641593a
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
index ceb8e5db59..ebab36e667 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -175,7 +175,7 @@ Two logical streams: the mux stream (`/api/events.mux`, all-session aggregate) a
 |---|---|---|
 | `session/event` | `{ sessionId; event: SessionEvent }` | core passthrough: core events pass verbatim, `assistant/chunk` IS the token stream, no separate delta frame |
 
-The remaining frame types are not re-copied here; the full unions are `MuxFrame`/`HostFrame` in `api/events.ts`. Three semantic points to know: `session/subscribed` carries lastSeq for history seam-race detection; the `approval/question` requested frames are answerable (stable rpcId) and the resolved frames are the convergence surface; `host/agent-error` is the only outlet for live failures with no turn position.
+The remaining frame types are not re-copied here; the full unions are `MuxFrame`/`HostFrame` in `api/events.ts`. Three semantic points to know: `session/subscribed` carries lastSeq for history-race detection; the `approval/question` requested frames are answerable (stable rpcId) and the resolved frames are the convergence surface; `host/agent-error` is the only outlet for live failures with no turn position.
 
 **Passthrough discipline**: events/messages/content blocks on the wire ARE the core types (`SessionEvent`/`ContentBlock`) — no second DTO set; types reach the browser through the `import type` dependency chain. `SessionEventMap` is merge-extensible: the client applies its documented default (ignore) to unknown types, and the event schema keeps a "valid envelope + unknown type" branch — the envelope stays strict; this is not field-level passthrough.
 
@@ -183,11 +183,11 @@ The remaining frame types are not re-copied here; the full unions are `MuxFrame`
 
 - **History = event replay**: one fold (client side); history pagination and live increments share one code path; the server maintains no second materialized-snapshot system. History **page boundaries align to message boundaries** (never cut mid-message; chunks group with their finalized message), and the tail page includes the in-flight partial's chunks.
 - **Prompt correlation**: the prompt's rpcId rides MessageSource (`'user-rpc'`) into the `user/message` event; the client uses it to promote the optimistic echo.
-- **Reconnect = rebuild**: no resume cursor (`mux`'s `since` signature is a reserved seat, ignored if passed); on disconnect reopen the stream + refetch history; compare `subscribed.lastSeq` with the history tail seq and backfill once if there is a seam.
+- **Reconnect = rebuild**: no resume cursor (`mux`'s `since` signature is a reserved seat, ignored if passed); on disconnect reopen the stream + refetch history; compare `subscribed.lastSeq` with the history tail seq and backfill once if there is a gap.
 - **Cold session handling follows ownership**: `session.history` and the source read for `session.fork` inspect persistence without an Agent, while Agent-bound ordinary-session methods such as `prompt` resume through a deduplicated in-flight table. Session-backed subagents reject that generic resume path, and attachment status is not exposed to clients (`running` already covers it).
 - **Approvals/questions**: the requested frame mints a stable rpcId on acceptance; first answer wins, and the host's in-memory pending table (keyed by rpcId) is the only referee; after a mux reopen, still-pending requested frames replay after the subscribed frame (rpcId reused verbatim — refresh recovery). The audit events `approval/asked`/`decided` continue through the durable log — frames = the live control plane, events = the durable audit. **Status**: the contract and frame types are shipped; the host-side pending table/wire answerer is unimplemented (`respond` in `api-proxy.ts` is a stub, always `not-pending`); PendingCard v1 is display-only.
 - **No protocol version**: client and host release bound together; `host.describe` has no protocolVersion field; introduce one when an independently released client appears.
-- **Reserved-seam discipline**: the map holds only implemented methods; an unknown method fails loud at envelope parse (`bad-request`) — no not-implemented fallback code. The reservation list (implementing = copy the signature into the domain interface + add the map row + add the schema pair): `session.fork`, `prompt.mode` gaining `'inject'`, `task.list`, `host.listModels`, describe gaining `hostInstanceId`. (`session.rename` graduated from this list: it appends a user-source `session/title` event.)
+- **Reserved-method discipline**: the map holds only implemented methods; an unknown method fails loud at envelope parse (`bad-request`) — no not-implemented fallback code. The reservation list (implementing = copy the signature into the domain interface + add the map row + add the schema pair): `session.fork`, `prompt.mode` gaining `'inject'`, `task.list`, `host.listModels`, describe gaining `hostInstanceId`. (`session.rename` graduated from this list: it appends a user-source `session/title` event.)
 
 ## The client carrier: the AbstractApiClient class family (`fetch/client.ts`)
 
@@ -230,11 +230,11 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 
 **Plug in a new carrier**: subclass `AbstractApiClient` implementing only `doFetch`; to intercept at the protocol layer (like the fixture), override the `callUnary`/`openMux`/`openHost` virtuals instead. Contract and base class stay unchanged.
 
-**Promote a reserved seam**: copy the reserved signature into the domain interface → add the map row → add the schema pair → add the UNARY_ROUTES row → implement.
+**Promote a reserved method**: copy the reserved signature into the domain interface → add the map row → add the schema pair → add the UNARY_ROUTES row → implement.
 
 ## Consequences
 
-Every client shape consumes one contract: adding a unary method is a five-step mechanical change radiating from a single signature, swapping a carrier touches only a `doFetch` subclass, and every wire message is zod-validated, observable through the envelope tap, and reconcilable by rpcId. Ordinary unary calls remain bounded, while `host.pickDirectory` and `command.execute` may stay pending until the operation finishes or caller/connection cancellation arrives; this accepts that a non-cooperative user-paced operation can hang its request rather than treating valid operation duration as transport failure. The other accepted costs: two groups of packages need explicit tsconfig paths entries, and the reserved seams (fork/inject/task.list/listModels/hostInstanceId) stay dormant until a real consumer arrives.
+Every client shape consumes one contract: adding a unary method is a five-step mechanical change radiating from a single signature, swapping a carrier touches only a `doFetch` subclass, and every wire message is zod-validated, observable through the envelope tap, and reconcilable by rpcId. Ordinary unary calls remain bounded, while `host.pickDirectory` and `command.execute` may stay pending until the operation finishes or caller/connection cancellation arrives; this accepts that a non-cooperative user-paced operation can hang its request rather than treating valid operation duration as transport failure. The other accepted costs: two groups of packages need explicit tsconfig paths entries, and the reserved methods (fork/inject/task.list/listModels/hostInstanceId) stay dormant until a real consumer arrives.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index bc0b6a9e88..308446e487 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -173,7 +173,7 @@ export type ResponseValue<K> =
 |---|---|---|
 | `session/event` | `{ sessionId; event: SessionEvent }` | 核心透传：core 事件原样过，`assistant/chunk` 即 token 流，无独立 delta 帧 |
 
-其余帧型不在此复写，union 全集见 `api/events.ts` 的 `MuxFrame`/`HostFrame`。语义上须知三点：`session/subscribed` 的 lastSeq 供 history 补缝竞态检测；`approval/question` 的 requested 帧可应答（rpcId 稳定）、resolved 帧是收敛面；`host/agent-error` 是无 turn 位置 live 失败的唯一出口。
+其余帧型不在此复写，union 全集见 `api/events.ts` 的 `MuxFrame`/`HostFrame`。语义上须知三点：`session/subscribed` 的 lastSeq 供 history 竞态检测；`approval/question` 的 requested 帧可应答（rpcId 稳定）、resolved 帧是收敛面；`host/agent-error` 是无 turn 位置 live 失败的唯一出口。
 
 **透传纪律**：wire 上的事件/消息/内容块就是 core 类型（`SessionEvent`/`ContentBlock`），不造第二套 DTO；类型经 `import type` 依赖链直达浏览器。`SessionEventMap` merge-extensible：client 对未知 type documented-default（忽略），事件 schema 留「合法信封+未知类型」分支——信封仍严格，不是字段级 passthrough。
 
@@ -185,7 +185,7 @@ export type ResponseValue<K> =
 - **冷会话处理遵循所有权**：`session.history` 与 `session.fork` 的源端读取会在不获取 Agent 的情况下检查持久化存储，而绑定到 Agent 的普通会话方法（如 `prompt`）则通过在途表去重后恢复会话。由会话支撑的 subagent 会拒绝这条通用恢复路径，且附加状态不对客户端暴露（`running` 已经覆盖）。
 - **审批/问答**：requested 帧受理时 mint 稳定 rpcId；先到先赢，host 内存 pending 表（keyed by rpcId）是唯一裁判；mux 重开后在 subscribed 帧后重放仍 pending 的 requested 帧（rpcId 原样复用，刷新恢复）。审计事件 `approval/asked`/`decided` 照旧走 durable 日志——帧=live 控制面，事件=durable 审计。**现状**：约定与帧类型已 shipped，host 侧 pending 表/wire answerer 未实现（`api-proxy.ts` 的 `respond` 是 stub，恒回 `not-pending`）；PendingCard v1 只展示。
 - **不设协议版本**：client 与 host 绑定发布，`host.describe` 无 protocolVersion 字段；出现独立发布的 client 时再引入。
-- **预留接缝纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。（`session.rename` 已从本清单毕业：追加 user 来源的 `session/title` 事件。）
+- **预留方法纪律**：map 只含已实现方法，未知 method 在信封 parse 即 fail loud（`bad-request`），不设 not-implemented 兜底码。预留清单（实现时把签名抄进域接口+map 加行+schema 加对即升格）：`session.fork`、`prompt.mode` 加 `'inject'`、`task.list`、`host.listModels`、describe 加 `hostInstanceId`。（`session.rename` 已从本清单毕业：追加 user 来源的 `session/title` 事件。）
 
 ## 客户端载体：AbstractApiClient 类体系（`fetch/client.ts`）
 
@@ -228,11 +228,11 @@ export type ResponseValue<K> =
 
 **接一种新载体**：继承 `AbstractApiClient` 只实现 `doFetch`；需要拦截协议层（如 fixture）再覆写 `callUnary`/`openMux`/`openHost` 虚方法。约定与基类零改。
 
-**升格一个预留接缝**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
+**升格一个预留方法**：把预留签名抄进域接口 → map 加行 → schema 加对 → UNARY_ROUTES 加行 → impl 实现。
 
 ## Consequences
 
-所有 client 形态消费同一约定：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
+所有 client 形态消费同一约定：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留方法（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index 5523e6d3b2..b7e331c934 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: e25d002b92df2016faf4073108aa905b65a1b115
-2026-07-19-gui-web-client-architecture.zh.md: 10779107a9dc6dc7335b2c5932c8c4877b531b50
+2026-07-19-gui-web-client-architecture.md: 7567ac3cb8b1a580e145f8f0da49b6ec371a35bd
+2026-07-19-gui-web-client-architecture.zh.md: 9b682febf1bd1aad1a767b8b2db4e83dd993cf2f
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index e25d002b92..7567ac3cb8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -30,7 +30,7 @@ Both ends run cordis. The host is a cordis plugin tree; the browser runs a secon
 
 ## The client cordis tree and the loading chain
 
-The loading chain — the two package kinds (plain vs dshClient plugin), the module-system/plugin-governor split, the two-phase boot over the host-authored entry graph with revisions, and hot reload — is owned by the [client plugin loading RFC](2026-07-23-client-plugin-loading-model.md). The load-bearing facts for this document: the browser boots the same vendored `@cordisjs/plugin-loader` as the host with a client module system (`ctx.modules`, `packages/client/modules`) filling its `internal` seam; every unit with product behavior is an entry in the host-authored `__DSH_BOOT__` graph — every production plugin package (infrastructure included) carries the `dshClient` declaration and arrives as a fetched `./client` tsdown closure bundle, `immediately` rows differing only in boot phase-one prefetch, while plain packages (react family, cordis, the not-yet-promoted libraries) stay shell-bundled, seeded, and invisible to the graph; bundles execute `window.__ModuleLoader__.load({ id, factory })` and their `require` is answered from the lazy CJS module table (seed words + registered factories, materialized and memoized on first require — cross-plugin value imports are a build error, cooperation goes through cordis services); plugin CSS is inlined in the bundle and injected as `<style data-plugin="<id>">` at materialization (CSS Modules hashing + ownership tag = isolation, removal on reload); hot reload is live in dev graphs — the webserver stat-polls the bundles it serves and broadcasts `rebuilt` SSE frames, and the `client-hmr` plugin swaps one fiber per frame. The settled flip (`loader.await()` + an all-ACTIVE sweep) still switches the shell from the loading page to the real UI in one pass — settled means every entry is created and every fiber reached ACTIVE, with FAILED/PENDING fibers listed loud; there is no partial-availability mode (progressive rendering is deferred work).
+The loading chain — the two package kinds (plain vs dshClient plugin), the module-system/plugin-governor split, the two-phase boot over the host-authored entry graph with revisions, and hot reload — is owned by the [client plugin loading RFC](2026-07-23-client-plugin-loading-model.md). The load-bearing facts for this document: the browser boots the same vendored `@cordisjs/plugin-loader` as the host with a client module system (`ctx.modules`, `packages/client/modules`) filling its `internal` contract; every unit with product behavior is an entry in the host-authored `__DSH_BOOT__` graph — every production plugin package (infrastructure included) carries the `dshClient` declaration and arrives as a fetched `./client` tsdown closure bundle, `immediately` rows differing only in boot phase-one prefetch, while plain packages (react family, cordis, the not-yet-promoted libraries) stay shell-bundled, seeded, and invisible to the graph; bundles execute `window.__ModuleLoader__.load({ id, factory })` and their `require` is answered from the lazy CJS module table (seed words + registered factories, materialized and memoized on first require — cross-plugin value imports are a build error, cooperation goes through cordis services); plugin CSS is inlined in the bundle and injected as `<style data-plugin="<id>">` at materialization (CSS Modules hashing + ownership tag = isolation, removal on reload); hot reload is live in dev graphs — the webserver stat-polls the bundles it serves and broadcasts `rebuilt` SSE frames, and the `client-hmr` plugin swaps one fiber per frame. The settled flip (`loader.await()` + an all-ACTIVE sweep) still switches the shell from the loading page to the real UI in one pass — settled means every entry is created and every fiber reached ACTIVE, with FAILED/PENDING fibers listed loud; there is no partial-availability mode (progressive rendering is deferred work).
 
 Type universes stay split at the aggregate level — `tsconfig.host.json` is the host program and `tsconfig.client.json` the client program, both referenced by the solution root `tsconfig.json` — because both sides merge cordis `Context` under the same keys (`sessions`, `loader`) with different services; client packages consume the wire vocabulary through pure type subpaths (`@deepseek-ai/dsh-session/types` and kin) so no host augmentation rides into the client program.
 
@@ -42,7 +42,7 @@ Implementation homes: registry core and the props-share types in `packages/clien
 
 ## Services and scope addressing
 
-A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer install seam), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
+A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer installation contract), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
 There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: Runtime projects Code Dispatch topology into each root's recursive `subCalls`; ui-conversation places that ordered root into the single `'conversation.chat.tool'` seat without interpreting Tool names or topology; ui-tool renders the supplied tree and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index 10779107a9..9b682febf1 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 ## client cordis 树与装载链
 
-装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双层 boot、热重载——归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` seam；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一层预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE 帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
+装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双层 boot、热重载——归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` 约定；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一层预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE 帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
 
 类型宇宙在聚合层拆分——`tsconfig.host.json` 是 host program、`tsconfig.client.json` 是 client program，二者由 solution 根 `tsconfig.json` 引用，因为两侧都在相同键（`sessions`、`loader`）上对 cordis `Context` 做声明合并且服务不同；client 包经纯类型子路径（`@deepseek-ai/dsh-session/types` 等）消费协议词汇，host 侧的声明合并不会搭车进入 client program。
 
@@ -42,7 +42,7 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-
 
 ## 服务与 scope 寻址
 
-服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装缝）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
+服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装约定）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
 slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：运行时把 Code Dispatch 拓扑投影进每个 root 递归的 `subCalls`；ui-conversation 把这个已排序 root 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或拓扑；ui-tool 渲染传入的树，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
index 6af30fd423..9a1610a341 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.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 .agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
-2026-07-19-package-invariant-runtime-contracts.md: 86d86f69b606c348e85d1ae654b6b35c4326985a
-2026-07-19-package-invariant-runtime-contracts.zh.md: 94d332a34c1d6e681c10832ea4deb559d88b21a6
+2026-07-19-package-invariant-runtime-contracts.md: c1a5aa1e55965b07b34ce307375d77e75cdeb9be
+2026-07-19-package-invariant-runtime-contracts.zh.md: 29fc2ecf2937b7557e16d972ad71230c0e304617
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
index 86d86f69b6..c1a5aa1e55 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-19-package-invariant-runtime-contracts.zh.md)
 
 ## Problem
 
-The package-owned invariant seam made publication and registration exhaustive, but its first generated baseline accepted empty installers. A follow-up then replaced those empties with generic assertions about plugin names, injections, effects, service methods, and fixed pure-library examples. Those assertions made every companion executable without making the system safer: TypeScript, Cordis startup, package tests, and module-load tests already enforce those shapes, while the invariant service should detect impossible runtime state.
+The package-owned invariant service made publication and registration exhaustive, but its first generated baseline accepted empty installers. A follow-up then replaced those empties with generic assertions about plugin names, injections, effects, service methods, and fixed pure-library examples. Those assertions made every companion executable without making the system safer: TypeScript, Cordis startup, package tests, and module-load tests already enforce those shapes, while the invariant service should detect impossible runtime state.
 
 A useful runtime invariant relates observations over time or across a mutable data structure. Examples include a terminal event without its start, an LLM delta for a block that is not open, or a durable result whose identity differs from its request. Merely confirming that a declared method exists, that a plugin has its expected name, or that a constant example still returns a known value is not such a relation.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
index 94d332a34c..29fc2ecf29 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-包自有不变量 seam 让发布和注册实现了全覆盖，但最初的生成基线允许空安装器。后续方案又用针对插件名称、注入、effect、服务方法和纯工具库中的固定示例的通用断言替代这些空实现。这些断言虽然让每个 companion 都能执行，却没有提高系统安全性：TypeScript、Cordis 启动、包测试和模块加载测试已经约束这些形状，而不变量服务应当发现不可能出现的运行时状态。
+包自有不变量服务让发布和注册实现了全覆盖，但最初的生成基线允许空安装器。后续方案又用针对插件名称、注入、effect、服务方法和纯工具库中的固定示例的通用断言替代这些空实现。这些断言虽然让每个 companion 都能执行，却没有提高系统安全性：TypeScript、Cordis 启动、包测试和模块加载测试已经约束这些形状，而不变量服务应当发现不可能出现的运行时状态。
 
 有用的运行时不变量会关联时间上的多个观测，或关联可变数据结构中的多个部分。例如：终止事件没有对应的开始事件、LLM（大语言模型）delta 指向未打开的块，或持久化结果的身份与请求不同。仅确认声明的方法存在、插件名称符合预期，或常量示例仍返回已知值，都不属于这种关系。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
index ad5f67e601..a6875e43df 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.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 .agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
-2026-07-19-package-owned-invariant-service.md: 6ab53f1a9bfa043f17875fa179a99b832b3fcf1a
-2026-07-19-package-owned-invariant-service.zh.md: 378b730c479eed05a2ad11e6a6e084929ec09653
+2026-07-19-package-owned-invariant-service.md: 296c55b21b947d32412acff54715d3687cf9c43b
+2026-07-19-package-owned-invariant-service.zh.md: 8aa776feabdef84a4007dc317115e6d72f6bbc50
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
index 6ab53f1a9b..296c55b21b 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
@@ -1,4 +1,4 @@
-# Agent Note: Package-owned invariant service seam
+# Agent Note: Package-owned invariant service contract
 
 Status: implemented
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
index 378b730c47..8aa776feab 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 包拥有的不变式服务 seam
+# Agent Note: 包拥有的不变式服务约定
 
 Status: implemented
 
diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml
index 20abdeec64..9223e938a7 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.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 .agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md
-2026-07-20-routed-model-context-and-compaction-policy.md: 6a2626d4eea3e30533199320b6b0ed5b05e7fd28
-2026-07-20-routed-model-context-and-compaction-policy.zh.md: 128563718554e2f8ed49f933aceb77cb18623dee
+2026-07-20-routed-model-context-and-compaction-policy.md: 630c259e5bbf6edc46cc837aedb627e673dc71f2
+2026-07-20-routed-model-context-and-compaction-policy.zh.md: ba2b5286995cb735baf9821294b8b5e0e625da5a
diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md
index 6a2626d4ee..630c259e5b 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md
@@ -28,7 +28,7 @@ Compact-basic owns consumer policy. Top-level fields define defaults; `modelPoli
 
 For proactive pressure, compact-basic reads the latest durable request route, resolves its adapter capacity and exact-target policy, and scales ratios into a `ResolvedCompactSpec`. It performs this resolution on every check, so a provider or model switch in one session changes capacity and policy immediately. An absolute retained budget that is not below the scaled threshold fails when the target capacity first makes that comparison possible.
 
-The same exact-target override can select summarization provider/model, summarization output cap, convergence retries, and overflow retry cap. These are compaction concerns and never enter the adapter seam.
+The same exact-target override can select summarization provider/model, summarization output cap, convergence retries, and overflow retry cap. These are compaction concerns and never enter an LLM provider.
 
 ### Target-specific pressure failures preserve optional composition
 
@@ -48,7 +48,7 @@ Service tests cover detached context metadata, invalid adapter output, catalog i
 
 ## Consequences
 
-- Capacity has one authoritative owner at the provider seam, while compaction policy stays in the optional consuming plugin.
+- Capacity has one authoritative owner at the provider contract, while compaction policy stays in the optional consuming plugin.
 - The same compact-basic instance safely handles different windows, provider switches, and identical model ids under different providers without consulting discovery metadata.
 - LLM-only and meter-only compositions remain valid; loading compact-basic adds no reverse dependency from adapters.
 - DeepSeek deployments may set exact per-model capacities, or use `defaultContextWindow` for entries without capacity and unlisted pass-through ids.
diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md
index 1285637185..ba2b528699 100644
--- a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md
@@ -28,7 +28,7 @@ Compact-basic 拥有消费方策略。顶层字段定义默认值；`modelPolici
 
 对于主动压力检查，compact-basic 读取最新持久请求路由，解析其适配器容量与精确目标策略，再把比例缩放为 `ResolvedCompactSpec`。每次检查都会重新解析，因此同一会话切换提供方或模型后，容量与策略会立即变化。若绝对保留预算不小于缩放后的阈值，系统会在目标容量首次允许比较两者时失败。
 
-同一精确目标覆盖还可以选择摘要提供方/模型、摘要输出上限、收敛重试次数与溢出重试上限。这些都属于压缩问题，不会进入适配器 seam。
+同一精确目标覆盖还可以选择摘要提供方/模型、摘要输出上限、收敛重试次数与溢出重试上限。这些都属于压缩问题，不会进入任何 LLM 提供方。
 
 ### 目标专用压力错误仍保留可选组合
 
@@ -48,7 +48,7 @@ Compact-basic 拥有消费方策略。顶层字段定义默认值；`modelPolici
 
 ## 后果
 
-- 容量在提供方 seam 上拥有唯一权威归属方，而压缩策略留在可选消费插件中。
+- 容量在提供方约定上拥有唯一权威归属方，而压缩策略留在可选消费插件中。
 - 同一个 compact-basic 实例无需查询发现元数据，就能安全处理不同窗口、提供方切换，以及不同提供方下的相同模型 id。
 - 仅 LLM 与仅 meter 的组合仍然有效；加载 compact-basic 不会让适配器产生反向依赖。
 - DeepSeek 部署可以设置精确的逐模型容量，也可以让未提供容量的模型项与未列出的透传 id 使用 `defaultContextWindow`。
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
index 7c13de5842..be5e4be24f 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.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 .agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
-2026-07-22-slot-type-chain-implementation.md: 2f0ec32766100e492c68c474f8798be3df0a3d15
-2026-07-22-slot-type-chain-implementation.zh.md: 6ef7eaa7614b88b33f0fa2aa6089e97eb3a45c25
+2026-07-22-slot-type-chain-implementation.md: 9930aaa62bd4b1f37dac9736517524b7e01b1746
+2026-07-22-slot-type-chain-implementation.zh.md: 2778d223cd89b4394bd629661dbb58105e6655cb
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
index 2f0ec32766..9930aaa62b 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md
@@ -88,11 +88,11 @@ An inject factory takes what its declarations earn it — `sessionId` for sessio
 
 Hooks are framework-made only: `useSession`, `useSessions`, `useWorkspaces`, `useStore`, `renderSlot` plus the hooks bound from provide contributions and inject `hooks` compartments — every one synthesized by the renderer's single binding machinery; business code passes plain data and callbacks between parent and child (a component's own behavioral hooks that subscribe to nothing external remain fine). Live data has exactly three channels: what the parent knows travels as owner props at the renderSlot site; what only the component knows is local state; what must be shared across entries or survive remounts is a declared store. Derivation is a pure function over framework-hook data (`useMemo`), never a subscription of its own.
 
-### Tree context and the renderer seam
+### Tree context and the renderer contract
 
 `SessionProvider` is a framework component **delivered as a standard-kit seat**: an entry whose `children` declare a session-scope slot receives it as a prop (type in ui-slots, value injected by the renderer) — components never value-import it. It is self-wired (it reads the runtime's current-session state internally; the assembler passes nothing), render-prop shaped — `children(sessionId)` with an `empty` branch, remounting under `key={sessionId}`. `BindingContext` is machinery-internal; business components see zero React contexts. Inject factories execute inside the outlet on purpose (per-entry error boundaries catch them; a crashing registrant blacks out only its own entry while assembly errors rethrow); the outlet reads tree context as a machinery-only implicit parameter — the "identity from the register closure, situation from the tree position" split.
 
-Rendering lives behind an install seam so the runtime stays React-free: `SlotRenderer` (interface in ui-slots, implementation `createSlotRenderer()` in web-react) is installed once at shell boot via `ctx.slots.install(...)`; double install and render-before-install throw. Ownership bookkeeping is a single `Map<key, entry>` in the service — ledger, slots, contributions, render bindings, and store instances all live and die on the one entry axis, which closes the stale-authority window across plugin reloads by construction (a disposed entry's captured `renderSlot` throws a stale-authorization error on entry).
+Rendering lives behind an installation contract so the runtime stays React-free: `SlotRenderer` (interface in ui-slots, implementation `createSlotRenderer()` in web-react) is installed once at shell boot via `ctx.slots.install(...)`; double install and render-before-install throw. Ownership bookkeeping is a single `Map<key, entry>` in the service — ledger, slots, contributions, render bindings, and store instances all live and die on the one entry axis, which closes the stale-authority window across plugin reloads by construction (a disposed entry's captured `renderSlot` throws a stale-authorization error on entry).
 
 ### Type-chain implementation rulings
 
diff --git a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
index 6ef7eaa761..2778d223cd 100644
--- a/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.zh.md
@@ -88,11 +88,11 @@ inject 工厂只接收其声明所授权的形参——session slot 获得 `sess
 
 hook 只许框架造：`useSession`、`useSessions`、`useWorkspaces`、`useStore`、`renderSlot` 五席，加上 provide 贡献与 inject `hooks` 格绑出的 hook——全部出自渲染器同一台绑定机械；业务代码在父子组件之间只传普通数据与回调（组件自用、不订阅任何外部数据源的行为 hook 不在此限）。活数据恰有三条通道：父知道的，作为 owner props 在 renderSlot 现场传入；只有组件自己知道的，是本地 state；需要跨 entry 共享或跨重挂载存活的，是声明的 store。派生是对框架 hook 数据做纯函数（`useMemo`），绝不自成一路订阅。
 
-### 树上语境与渲染器安装缝
+### 树上语境与渲染器约定
 
 `SessionProvider` 是框架组件，**以标配 slot 形式送达**：`children` 里声明了 session scope slot 的 entry 经 prop 收到它（类型住 ui-slots，值由渲染器注入）——组件永不对它做值 import。它框架自接线（内部自读 runtime 的当前会话状态，装配方零传参），render-prop 形——`children(sessionId)` 外加 `empty` 分支，以 `key={sessionId}` 重挂。`BindingContext` 属机械内部；业务组件可见的 React Context 为零。inject 工厂有意在 outlet 内部执行（per-entry 错误边界接得住它们；崩溃的注册方只黑掉自己那一格，装配错误则重抛）；outlet 将树上下文作为仅供框架机制使用的隐式参数读取——即「身份出自 register 闭包、现场出自树位置」的分工。
 
-渲染位于一个 install seam 之后，因此 runtime 不依赖 React：`SlotRenderer`（接口住 ui-slots，实现 `createSlotRenderer()` 住 web-react）在壳 boot 时经 `ctx.slots.install(...)` 安装一次；双重安装与安装前渲染均 throw。归属记账是服务里的单一 `Map<key, entry>`——账本、slot、贡献、渲染绑定、store 实例全部沿同一条 entry 轴生灭，跨插件重载的陈旧权威窗口由此在构造上关闭（已 dispose 的 entry 所捕获的 `renderSlot`，一进入口即抛陈旧授权（stale-authorization）错误）。
+渲染位于一份安装约定之后，因此 runtime 不依赖 React：`SlotRenderer`（接口住 ui-slots，实现 `createSlotRenderer()` 住 web-react）在壳 boot 时经 `ctx.slots.install(...)` 安装一次；双重安装与安装前渲染均 throw。归属记账是服务里的单一 `Map<key, entry>`——账本、slot、贡献、渲染绑定、store 实例全部沿同一条 entry 轴生灭，跨插件重载的陈旧权威窗口由此在构造上关闭（已 dispose 的 entry 所捕获的 `renderSlot`，一进入口即抛陈旧授权（stale-authorization）错误）。
 
 ### 类型链实现裁定
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
index 33ff739db9..7c4e3bef22 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.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 .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
-2026-07-23-client-plugin-loading-model.md: 2dc0c68e5f20bd790c2362f92c16dece171babf5
-2026-07-23-client-plugin-loading-model.zh.md: abe62f4c03147cc4716103e531adb812f073e622
+2026-07-23-client-plugin-loading-model.md: 302363fcb03a7aa2438b9d97d4e3405db7d6ce8d
+2026-07-23-client-plugin-loading-model.zh.md: 23061a9800b21ada64ef1a3c205c588a9406b67d
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
index 2dc0c68e5f..302363fcb0 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-23-client-plugin-loading-model.zh.md)
 
 ## Problem
 
-On the host, cordis plugin loading stands on Node's module machinery — the require cache and the internal ESM loader own module identity and bytes. The vendored `@cordisjs/plugin-loader` implements plugin governance and hot reload on top of that substrate, and the two meet at one seam: `Loader.internal`.
+On the host, cordis plugin loading stands on Node's module machinery — the require cache and the internal ESM loader own module identity and bytes. The vendored `@cordisjs/plugin-loader` implements plugin governance and hot reload on top of that substrate, and the two meet at one boundary: `Loader.internal`.
 
 The browser client runs the same cordis plugin mechanism, so it needs the same substrate underneath — and the browser has no Node module system.
 
@@ -16,7 +16,7 @@ Conventional frontend engineering digests all dependencies at build time: one bu
 
 The lower layer supplies four capabilities: externals (the platform list), remote arrival (same-origin external classic scripts plus lazy factory registration), versioning (content-hash revs), and hot update (invalidate/prefetch).
 
-Plugin bundles are built independently outside Vite's module graph. Feeding response text into an inline script leaves the browser with a dynamic source execution: no standard source-map chain connects the network resource, generated bundle, and TypeScript/TSX source, so performance profiles and stacks stop at generated `client.js`; the module system must also buffer the complete source and split one arrival responsibility across fetch and execute transport seams.
+Plugin bundles are built independently outside Vite's module graph. Feeding response text into an inline script leaves the browser with a dynamic source execution: no standard source-map chain connects the network resource, generated bundle, and TypeScript/TSX source, so performance profiles and stacks stop at generated `client.js`; the module system must also buffer the complete source and split one arrival responsibility across fetch and execute transport boundaries.
 
 On top of that, client and host plugins register and load consistently: a package declares `dshClient` once, the host scans the declaration into the boot graph, and the same Loader semantics govern entries on both sides.
 
@@ -35,7 +35,7 @@ The manifest owns the package's loading contract: its `inject` dependency edges,
 
 To add a plugin package: declare `dshClient`, emit the `./client` bundle through the shared preset, add the name to the composing app's roster. Nothing else changes hands.
 
-When does a plain package become a plugin? The upgrade law, recorded so the migration path stays honest: **a plain package becomes a plugin package when its consumers switch to cordis DI, not before.** Three promotions are queued: ui-slots (will receive the slots machinery now living in runtime — SlotsService, the renderer seam, the root slot), web-react (will take the renderer install into its own `apply`), and ui-primitives (once components are served through slots/services). Until then they stay plain, and their symbol exports stay ordinary static imports.
+When does a plain package become a plugin? The upgrade law, recorded so the migration path stays honest: **a plain package becomes a plugin package when its consumers switch to cordis DI, not before.** Three promotions are queued: ui-slots (will receive the slots machinery now living in runtime — SlotsService, the renderer contract, the root slot), web-react (will take the renderer install into its own `apply`), and ui-primitives (once components are served through slots/services). Until then they stay plain, and their symbol exports stay ordinary static imports.
 
 Four edge rules govern imports across the two kinds. None of them depends on any per-package mark:
 
@@ -50,7 +50,7 @@ The browser mirrors the host's division of labor. `dsh-client-modules` (`ClientM
 
 `ClientModuleSystem` is a lazy CJS table. Executing a bundle only **registers** its factory — the bundle calls `window.__ModuleLoader__.load({ id, factory })` and nothing else happens. Every module body side effect, CSS injection included, lives inside the factory closure and runs at materialization: the first `require`/import of that id, memoized after that. A factory that requires a registered-but-unmaterialized sibling materializes it recursively, so no sort order exists anywhere. When asked to import an id, the table resolves through a fixed branch order: seed word → memoized record → static registration (shell-own modules, e.g. app-shell) → registered factory → graph-row external classic-script load → loud throw. That final throw is the runtime mirror of the build-time purity gate. The system also keeps per-module bookkeeping — owned `<style data-plugin>` tag ids, observed require edges — and exposes the two verbs HMR needs: `prefetch(id)` (load the script and register its factory; concurrent calls share one in-flight task) and `invalidate(id)` (drop the factory and record so the next arrival reloads it).
 
-The vendored Loader consumes the module system through its `internal` seam — the only call site is `tree.import` — and owns everything entry-shaped: entry creation, fiber activation through cordis service waiting (PENDING until injected services exist, cascading when a service is provided), update/refresh, teardown. The governance code is byte-identical to the host side, per vendor policy. Browserization is compile-time mapping in the shell's vite config: a `node:module` stub alias plus `process.*` defines make `ModuleLoader.fromInternal()` return undefined — exactly the empty slot the shell fills. The module system mounts as `ctx.modules`.
+The vendored Loader consumes the module system through its `internal` contract — the only call site is `tree.import` — and owns everything entry-shaped: entry creation, fiber activation through cordis service waiting (PENDING until injected services exist, cascading when a service is provided), update/refresh, teardown. The governance code is byte-identical to the host side, per vendor policy. Browserization is compile-time mapping in the shell's vite config: a `node:module` stub alias plus `process.*` defines make `ModuleLoader.fromInternal()` return undefined — exactly the empty slot the shell fills. The module system mounts as `ctx.modules`.
 
 ### External-script arrival and source maps
 
@@ -122,7 +122,7 @@ The support boundary, stated honestly. Reload is coarse by design: fresh fiber,
 
 ## Consequences
 
-One governance implementation runs on both sides of the wire; the browser-specific surface is one module system plus one reload plugin. Plugin packages have one shape, so the purity gate covers them all. Dependency edges and the boot tier live with their owners — the manifests — while the composing app holds only the roster and the `--dev` switch. The drift classes stay structurally closed: share-list hand-sync, load-order coupling, cross-plugin imports, roster/tier double bookkeeping. Browser-native script loading preserves the standard mapping among plugin network resources, generated bundles, and TypeScript/TSX sources, while the module system keeps only one replaceable `loadBundle` seam.
+One governance implementation runs on both sides of the wire; the browser-specific surface is one module system plus one reload plugin. Plugin packages have one shape, so the purity gate covers them all. Dependency edges and the boot tier live with their owners — the manifests — while the composing app holds only the roster and the `--dev` switch. The drift classes stay structurally closed: share-list hand-sync, load-order coupling, cross-plugin imports, roster/tier double bookkeeping. Browser-native script loading preserves the standard mapping among plugin network resources, generated bundles, and TypeScript/TSX sources, while the module system keeps only one replaceable `loadBundle` hook.
 
 Costs accepted: the vendored Loader carries idle machinery in the browser (EntryTree persistence is a no-op, groups/isolation unused); every plugin edit in dev pays a bundle rebuild plus fiber remount; graph `inject` rows are informational — activation truth is service-level — so a mismatch surfaces at the settled sweep, not at graph validation; the three not-yet-promoted libraries keep their static-import export surface until their DI conversions land; every bundle gains a source-map artifact; and external-script failures provide only coarse URL diagnostics instead of the HTTP status available to an explicit fetch.
 
@@ -139,5 +139,5 @@ Roster endgame (landed 2026-07-25 with the config-tree boot move): the roster li
 | Import maps | Ruled out earlier; the DI require table is the terminal mechanism |
 | Full ctx-ification now (react and libraries via services, no module table) | The module-axis extreme; parked — the upgrade law walks there one package at a time instead |
 | Eager instantiation with a frozen table | Requires arrival-time ordering; lazy CJS registration makes recursive `require` self-ordering and matches the naive-puller phase split |
-| Fetch response text, then inject an inline `<script>` | Makes the module system buffer the complete source and maintain separate fetch/execute seams; dynamic source execution also breaks the browser-native association among the network resource, source map, and profile |
+| Fetch response text, then inject an inline `<script>` | Makes the module system buffer the complete source and maintain separate fetch/execute paths; dynamic source execution also breaks the browser-native association among the network resource, source map, and profile |
 | Builder-push rebuild channel (`POST /plugins/rebuilt` from the orchestrator's `onSuccess`) | Couples reload to one blessed builder process and a second wire protocol; the webserver already holds every bundle path, and stat polling covers the torn-write race (re-hash on every stat change) that once justified pushing |
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
index abe62f4c03..23061a9800 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 ## Problem
 
-host 侧，cordis 插件装载站在 Node 的模块机制之上——require cache 与内部 ESM loader 拥有模块身份与字节。vendored `@cordisjs/plugin-loader` 在这层基座之上实现插件治理与热重载，二者在唯一一道 seam 相接：`Loader.internal`。
+host 侧，cordis 插件装载站在 Node 的模块机制之上——require cache 与内部 ESM loader 拥有模块身份与字节。vendored `@cordisjs/plugin-loader` 在这层基座之上实现插件治理与热重载，二者在唯一一道边界相接：`Loader.internal`。
 
 浏览器客户端跑同一套 cordis 插件机制，因此底下需要同样的基座——而浏览器没有 Node 模块系统。
 
@@ -16,7 +16,7 @@ host 侧，cordis 插件装载站在 Node 的模块机制之上——require cac
 
 下层供给四项能力：external（平台清单）、远程到达（同源外部 classic script 加惰性工厂登记）、版本化（内容哈希 rev）、热更新（invalidate/prefetch）。
 
-插件 bundle 独立构建在 Vite 模块图之外。若把响应文本塞进内联 script，浏览器只能看到一次动态源码执行：网络资源、生成 bundle、TypeScript/TSX 源码之间没有标准 sourcemap 链，性能 profile 与 stack 只能落到生成后的 `client.js`；模块系统还要持有整份源码文本，并把同一项到达职责拆成 fetch 与 execute 两道传输 seam。
+插件 bundle 独立构建在 Vite 模块图之外。若把响应文本塞进内联 script，浏览器只能看到一次动态源码执行：网络资源、生成 bundle、TypeScript/TSX 源码之间没有标准 sourcemap 链，性能 profile 与 stack 只能落到生成后的 `client.js`；模块系统还要持有整份源码文本，并把同一项到达职责拆成 fetch 与 execute 两道传输边界。
 
 在此之上，client 与 host 插件以一致的方式注册与装载：包声明一次 `dshClient`，host 把声明扫描进 boot 图，同一套 Loader 语义在两侧治理 entry。
 
@@ -35,7 +35,7 @@ manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `im
 
 新增一个插件包：声明 `dshClient`，经共享预设产出 `./client` bundle，把包名加进负责组合的 app 的名册。除此之外无需任何交接。
 
-普通包何时升格为插件？升级法则，记录在案让迁移路径保持诚实：**普通包在其消费方改用 cordis DI 之时升格为插件包，绝不提前。**三项升格在排队：ui-slots（将接收现居 runtime 的 slots 机件——SlotsService、渲染器 seam、root slot）、web-react（将把渲染器安装收进自己的 `apply`）、ui-primitives（组件经 slot/服务供给之时）。在那之前它们保持普通包身份，符号导出保持普通的静态 import。
+普通包何时升格为插件？升级法则，记录在案让迁移路径保持诚实：**普通包在其消费方改用 cordis DI 之时升格为插件包，绝不提前。**三项升格在排队：ui-slots（将接收现居 runtime 的 slots 机件——SlotsService、渲染器约定、root slot）、web-react（将把渲染器安装收进自己的 `apply`）、ui-primitives（组件经 slot/服务供给之时）。在那之前它们保持普通包身份，符号导出保持普通的静态 import。
 
 四条边规则治理横跨两类包的 import。没有一条依赖任何单包标记：
 
@@ -50,7 +50,7 @@ manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `im
 
 `ClientModuleSystem` 是一张 lazy CJS 表。执行 bundle 只**登记**其工厂——bundle 调用 `window.__ModuleLoader__.load({ id, factory })`，此外什么都不发生。模块体的一切副作用（包括 CSS 注入）都住在工厂闭包里，在物化时运行：物化即该 id 的首次 `require`/import，此后记忆化。工厂若 require 一个已登记未物化的同伴，就递归物化它，因此任何地方都不存在排序。被要求 import 一个 id 时，表按固定分支顺序解析：种子词条 → 记忆化的记录 → 静态登记（壳自有模块，如 app-shell）→ 已登记的工厂 → 图行外部 classic script 加载 → 大声抛错。最后这一抛是构建期纯度门禁在运行期的镜像。系统还保管逐模块的簿记——名下 `<style data-plugin>` 标签 id、观测到的 require 边——并暴露 HMR（热模块替换）需要的两个动词：`prefetch(id)`（加载脚本、只登记工厂；并发调用共享同一在途任务）与 `invalidate(id)`（丢弃工厂与记录，下次到达即重新加载）。
 
-vendored Loader 经其 `internal` seam 消费模块系统——唯一调用点是 `tree.import`——并拥有一切 entry 形状的事务：entry 创建、fiber 经 cordis 服务等待的激活（注入的服务未就位即保持 PENDING，服务 provide 时级联激活）、update/refresh、拆除。治理代码按 vendor 政策与 host 侧逐字节相同。浏览器化是壳 vite 配置里的编译期映射：一个 `node:module` stub 别名加若干 `process.*` define，使 `ModuleLoader.fromInternal()` 返回 undefined——这正是留给壳来填的空槽。模块系统挂载为 `ctx.modules`。
+vendored Loader 经其 `internal` 约定消费模块系统——唯一调用点是 `tree.import`——并拥有一切 entry 形状的事务：entry 创建、fiber 经 cordis 服务等待的激活（注入的服务未就位即保持 PENDING，服务 provide 时级联激活）、update/refresh、拆除。治理代码按 vendor 政策与 host 侧逐字节相同。浏览器化是壳 vite 配置里的编译期映射：一个 `node:module` stub 别名加若干 `process.*` define，使 `ModuleLoader.fromInternal()` 返回 undefined——这正是留给壳来填的空槽。模块系统挂载为 `ctx.modules`。
 
 ### 外部脚本到达与源码映射
 
@@ -122,7 +122,7 @@ vendored Loader 经其 `internal` seam 消费模块系统——唯一调用点
 
 ## Consequences
 
-wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模块系统加一个重载插件。插件包只有一种形态，纯度门禁因此覆盖全部插件。依赖边与启动档位都与其所有者——manifest——同住，负责组合的 app 只握名册与 `--dev` 开关。各漂移缺陷类被结构性关死：共享清单人肉同步、装载顺序耦合、跨插件 import、名册/档位双重记账。浏览器原生脚本装载使插件网络资源、生成 bundle 与 TypeScript/TSX 源码保持标准映射，模块系统也只保留一道可替换的 `loadBundle` seam。
+wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模块系统加一个重载插件。插件包只有一种形态，纯度门禁因此覆盖全部插件。依赖边与启动档位都与其所有者——manifest——同住，负责组合的 app 只握名册与 `--dev` 开关。各漂移缺陷类被结构性关死：共享清单人肉同步、装载顺序耦合、跨插件 import、名册/档位双重记账。浏览器原生脚本装载使插件网络资源、生成 bundle 与 TypeScript/TSX 源码保持标准映射，模块系统也只保留一个可替换的 `loadBundle` 钩子。
 
 接受的代价：vendored Loader 在浏览器里背着闲置机件（EntryTree 持久化是 no-op，分组/隔离未用）；开发期每次修改插件都要付一次 bundle 重建加 fiber 重挂；图中 `inject` 行仅是信息性说明——激活的真相在服务层——因此不匹配会在 settled 扫描时浮出，而不是在图校验时被拦下；三个尚未升格的库在各自的 DI 转换落地之前保持静态 import 的导出面；每个 bundle 多出一份 sourcemap 产物，外部脚本失败也只能给出粗粒度的 URL 诊断，不能像显式 fetch 那样报告 HTTP 状态。
 
@@ -139,5 +139,5 @@ wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模
 | import map | 早已排除；DI require 表是终局机制 |
 | 现在就彻底 ctx 化（react 与库全走服务，不设模块表） | 模块轴上的极端形态；搁置——升级法则改为一次一包走向它 |
 | 冻结表 + 到达即实例化 | 要求按到达时刻排序；lazy CJS 登记让递归 `require` 自行定序，且与朴素拉取器的分层相合 |
-| fetch 响应文本后注入内联 `<script>` | 模块系统必须缓冲整份源码并维护 fetch/execute 两道 seam；动态源码执行也切断浏览器网络资源、sourcemap 与 profile 的原生关联 |
+| fetch 响应文本后注入内联 `<script>` | 模块系统必须缓冲整份源码并维护 fetch/execute 两条路径；动态源码执行也切断浏览器网络资源、sourcemap 与 profile 的原生关联 |
 | 构建器推送重建通道（编排器在 `onSuccess` 里 POST `/plugins/rebuilt`） | 把重载耦合到一个钦定的构建器进程和第二套 wire 协议；webserver 本就握有每个 bundle 路径，stat 轮询（每次 stat 变化即重哈希）已兜住当年为推送辩护的撕裂写竞态 |
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
index 06bfd11c4f..073a71d118 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.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 .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
-2026-07-25-web-client-session-scope-and-provide-channel.md: 3c51f06fca23a495f0fbc0cc4f1c289edea07b3b
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: cccc0b6d8f7309c5344e042d9cc2171587a18cb5
+2026-07-25-web-client-session-scope-and-provide-channel.md: 6e4c58c229cea9ff9f0e5ccf03b04c799755244b
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 4d4824f5596139523f5d5b94cb79ba9d1944ff15
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
index 3c51f06fca..6e4c58c229 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
@@ -116,7 +116,7 @@ Slot scope is the closed set `root | session-maybe | session`:
 |---|---|
 | A client-local Intent + materialize (published CAS / the pendingPrompt attach transaction / the before-create chain) | The client is forced to simulate the first half-life the host lacks, breeding a pile of state machinery — published CAS, the attach transaction, partial publication |
 | Host-reserved IDs (a draft Map) | The host merely acknowledges a number; the state machine stays on the client untouched |
-| A host draft Session (a Session without an Agent) | Every host surface that looks up the Agent must fork for drafts; core would need an attachAgent seam plus late-written header cwd |
+| A host draft Session (a Session without an Agent) | Every host surface that looks up the Agent must fork for drafts; core would need an `attachAgent` API plus late-written header cwd |
 | Binding an Agent before cwd (ungrouped) | Overturns the readonly header.cwd "created in" invariant, plus the launch-dir side-effect product trap |
 | Passing session context down through React Context | Plugins should hold one mental model across host and client; the scope mechanism is isomorphic to the host dsh-scope |
 | A `scopeTarget` carrier + fused dispatcher (mirroring the host `agentEvents`) | The host wrapper layer guards the business Agent subject against drifting from the scope key; client events have no subject to guard — the filter on the actx plus cordis primitives covers every need |
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
index cccc0b6d8f..4d4824f559 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
@@ -116,7 +116,7 @@ slot scope 是闭集 `root | session-maybe | session`：
 |---|---|
 | client-local Intent + materialize（published CAS / pendingPrompt attach 事务 / before-create 链） | client 被迫模拟 host 缺失的前半段生命，养出 published CAS、attach 事务、部分发布一坨状态机 |
 | host 预留 ID（draft Map） | host 只认了个号，状态机原封留在 client |
-| host draft Session（有 Session 无 Agent） | 每个查 Agent 的 host 面都要为 draft 分叉；core 要开 attachAgent seam + header cwd 后写 |
+| host draft Session（有 Session 无 Agent） | 每个查 Agent 的 host 面都要为 draft 分叉；core 要新增 `attachAgent` API + header cwd 后写 |
 | 无 cwd 先绑 Agent（ungrouped） | header.cwd readonly「created in」不变性被推翻 + launch-dir 副作用产品坑 |
 | React Context 层层传会话语境 | 插件在 host/client 两侧应是一个心智模型；scope 机制与 host dsh-scope 同构 |
 | `scopeTarget` carrier + 融合派发器（镜像 host `agentEvents`） | host 包装层护的是「业务 Agent subject 与 scope key 不漂移」，client 事件无 subject 可护；filter 住 actx + cordis 原语覆盖全部需求 |
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index f805e7cde3..830661f8cd 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: 8797102c65ebab663bcf72fced5791364fe2c6ae
-2026-07-26-subprocess-seam.zh.md: 8a7ff14079374d6d74a1ec729dd02c8961fa23e6
+2026-07-26-subprocess-seam.md: 378f941ead65ebdcacac665d31cd269e7a2e0565
+2026-07-26-subprocess-seam.zh.md: 4e085dcde46ef041985006019d3c6b98fed609c8
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index 8797102c65..378f941ead 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -12,14 +12,14 @@ English | [中文](2026-07-26-subprocess-seam.zh.md)
 
 A new `subprocess/` capability family owns "run and manage a process"; the bash family keeps "run a bash command" and consumes it:
 
-- **`@deepseek-ai/dsh-subprocess` (interface)** — the abstract `SubprocessService` owning `ctx.subprocess`: executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The seam also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
-- **`@deepseek-ai/dsh-subprocess-local` (implementation)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the seam's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The implementation has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their consumers.
-- **`dsh-bash-local` (consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
-- **`dsh-bash` (seam)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
+- **`@deepseek-ai/dsh-subprocess` (Service Definition)** — the abstract `SubprocessService` owning `ctx.subprocess`: executable lookup, fully explicit ordinary spawns, and the terminal primitive added by the [portable execution-world decision](2026-07-28-portable-execution-world-consumers.md). Each stdio stream independently selects `'pipe'`, `'inherit'`, or bounded collection `{ maxBytes, spill? }`; stdin selects `'ignore'`, `'pipe'`, or `{ data }`. `SubprocessOutcome` carries exit facts with deliberately no timeout/cancel classification, while collected output remains on the handle after settlement. The Service Definition also owns process and terminal handles, the shared scrub, and `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`; `argv` is never shell-interpreted.
+- **`@deepseek-ai/dsh-subprocess-local` (Service provider)** — `LocalSubprocessService` over the former `run.ts` plumbing (`spawn.ts`) plus `node-pty`: detached groups, bounded collection and private spill files, executable lookup, foreground/session inspection, and disposal that terminates and joins every managed process. `terminate()` owns TERM→grace→KILL for the tree, `waitForExit()` observes tree liveness, and injected `taskkill /T` covers Windows. Ordinary and terminal spawns apply the Service Definition's case-insensitive `KEY`/`PASSWORD`/`SECRET`/`TOKEN` scrub before explicit env. The provider has no config; every limit arrives on the spec, while Bash and PTY presentation environment overrides stay in their Consumers.
+- **`dsh-bash-local` (Consumer)** — `inject: ['subprocess']`; maps each resolved `BashExecSpec` onto a `SubprocessSpawnSpec` (`['bash', '-c', command]`), keeps its config, `resolve()` defaulting, fused-deadline `timedOut`/`aborted` classification, the `[stderr]`-marked background read merge with its consuming cursor, and the `onProcessDone` subclass hook. `dsh-bash-sandbox` is unchanged apart from redeclaring the inherited inject; it still wraps at the command-string level and re-enters the inherited spawn path.
+- **`dsh-bash` (Service Definition)** — re-exports the moved vocabulary from `dsh-subprocess`, so no bash Consumer changes an import; `BashExecRequest`/`BashExecSpec`/`BashProcess` and the sandbox facts remain bash-owned.
 
 Every composition that loads a bash executor now also loads `@deepseek-ai/dsh-subprocess-local` (CLI, examples, python bundled runtime, create-sdk's bash feature resources, inline test configs).
 
-Background-process lifetime moved from the executor to the subprocess service: the executor no longer retains a live-process set, so an executor reload leaves background work running and readable, and composition teardown (the service's disposal) remains the kill-and-join boundary. One behavioral seam shifted with it: a background spawn failure can no longer be buffered as fake stderr inside the plumbing (the service rejects `done` and buffers nothing for a process that never ran), so the executor injects the `spawn failed: …` note into exactly one `readOutput()` delta.
+Background-process lifetime moved from the executor to the subprocess service: the executor no longer retains a live-process set, so an executor reload leaves background work running and readable, and composition teardown (the service's disposal) remains the kill-and-join boundary. One behavioral contract shifted with it: a background spawn failure can no longer be buffered as fake stderr inside the plumbing (the service rejects `done` and buffers nothing for a process that never ran), so the executor injects the `spawn failed: …` note into exactly one `readOutput()` delta.
 
 Observed stream and lifecycle needs then moved the eligible process consumers onto the seam: LSP uses piped protocol streams plus a collected stderr tail; the ACP backend uses piped ndjson, inherited stderr, and a consumer-owned stdin-EOF disposal ladder; PTY uses `spawnTerminal()` while keeping readiness and terminal policy. `dsh-subagent-subprocess` and the private LSP tree helpers were deleted. MCP transport spawning, the SDK package-manager runner, synchronous TUI Git probing, and dependency-light test-support launchers remain outside by ownership or execution shape; their production callers share the scrub where applicable.
 
@@ -33,7 +33,7 @@ Observed stream and lifecycle needs then moved the eligible process consumers on
 
 **Route every process launch through `ctx.subprocess`.** Rejected because the MCP SDK owns its transport spawn, the SDK wizard has no Cordis context and needs inherited redirection, the TUI probe is synchronous, and support launchers deliberately stay independent of product seams. PTY allocation did move behind `spawnTerminal()` because the provider, not the consumer, owns that substrate-specific primitive.
 
-**Put `run_in_background`/task semantics into the process seam instead.** Rejected: that boundary already exists — `ctx.tasks` owns ids, ownership, and notices, and the bash tool adapts a `BashProcess` into task hooks. The process seam sits *below* the bash executor, not beside the task registry.
+**Put `run_in_background`/task semantics into the subprocess capability seam instead.** Rejected: that boundary already exists — `ctx.tasks` owns ids, ownership, and notices, and the bash tool adapts a `BashProcess` into task hooks. The subprocess seam sits *below* the bash executor, not beside the task registry.
 
 **Move `ENV_OVERRIDES` (TERM=dumb, PAGER=cat …) into the subprocess service.** Rejected: a generic subprocess service must not impose terminal presentation policy on non-terminal consumers; the ambient scrub (credential-shaped and `DSH_*` names) is a security/identity invariant and stays, but terminal friendliness is the bash tool's choice, expressed through the spec's explicit env where a caller's own entry still wins.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 8a7ff14079..4e085dcde4 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -12,14 +12,14 @@ Status: implemented
 
 新的 `subprocess/` 能力家族拥有「运行并管理一个进程」；bash 家族保留「运行一条 bash 命令」，并成为前者的消费方：
 
-- **`@deepseek-ai/dsh-subprocess`（接口）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 seam 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
-- **`@deepseek-ai/dsh-subprocess-local`（实现）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 seam 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该实现没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自消费方所有。
-- **`dsh-bash-local`（消费方）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
-- **`dsh-bash`（seam）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash 消费方需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
+- **`@deepseek-ai/dsh-subprocess`（Service Definition）**——拥有 `ctx.subprocess` 的抽象 `SubprocessService`：可执行文件查找、完全显式的普通 spawn，以及[可移植执行环境决策](2026-07-28-portable-execution-world-consumers.md)新增的终端原语。每条 stdio 流独立选择 `'pipe'`、`'inherit'` 或有界收集 `{ maxBytes, spill? }`；stdin 选择 `'ignore'`、`'pipe'` 或 `{ data }`。`SubprocessOutcome` 只承载刻意不含超时／取消分类的退出事实，收集输出在结算后仍留在句柄上。该 Service Definition 还拥有进程与终端句柄、共享凭据清除，以及 `DSH_ENV_PREFIX`/`DshEnvironment`/`CollectedOutput`；`argv` 绝不经过 shell 解释。
+- **`@deepseek-ai/dsh-subprocess-local`（Service provider）**——`LocalSubprocessService` 构建在原 `run.ts` 管道（现为 `spawn.ts`）与 `node-pty` 之上：detached 进程组、有界收集与私有 spill 文件、可执行文件查找、前台／会话检查，以及终止每个受管进程并等待其退出的 dispose。`terminate()` 拥有面向进程树的 TERM→宽限→KILL，`waitForExit()` 观察进程树存活性，可注入的 `taskkill /T` 覆盖 Windows。普通与终端 spawn 都先应用 Service Definition 对 `KEY`/`PASSWORD`/`SECRET`/`TOKEN` 不区分大小写的清除，再合并显式 env。该 Service provider 没有配置；每项限制都随 spec 到达，Bash 与 PTY 的呈现环境覆盖仍归各自 Consumer 所有。
+- **`dsh-bash-local`（Consumer）**——`inject: ['subprocess']`；把每个解析后的 `BashExecSpec` 映射为一个 `SubprocessSpawnSpec`（`['bash', '-c', command]`），并保留自身配置、`resolve()` 默认值补全、基于融合 deadline 的 `timedOut`/`aborted` 分类、带 `[stderr]` 标记的后台读取合并及其消费游标，以及 `onProcessDone` 子类钩子。`dsh-bash-sandbox` 除了重新声明继承来的 inject 之外没有变化；它仍在命令字符串层面做包装，并重新进入继承的 spawn 路径。
+- **`dsh-bash`（Service Definition）**——把迁走的词汇从 `dsh-subprocess` 重导出，因此没有任何 bash Consumer 需要改动导入；`BashExecRequest`/`BashExecSpec`/`BashProcess` 与沙箱事实仍归 bash 所有。
 
 如今，每个加载 bash 执行器的组合都同时加载 `@deepseek-ai/dsh-subprocess-local`：CLI（命令行界面）、各示例、Python 捆绑运行时、create-sdk 的 bash 功能资源，以及各内联测试配置。
 
-后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为 seam 随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
+后台进程的存续期从执行器移到了管理器：执行器不再保有存活进程集合，于是重载执行器后，后台工作会继续运行且仍可读取，而组合拆除（管理器的 dispose）仍是先终止再等待退出的边界。一条行为约定随之挪动：后台 spawn 失败不再能在管道内部被缓冲成伪造的 stderr（对一个从未真正运行的进程，管理器会 reject `done`，且不缓冲任何内容），因此执行器把 `spawn failed: …` 提示注入恰好一个 `readOutput()` 增量。
 
 基于已观察到的流与生命周期需求，具备条件的进程消费方随后迁到该 seam：LSP 使用管道化协议流加收集式 stderr 尾部；ACP（Agent Client Protocol）后端使用管道化 ndjson、继承式 stderr 和消费方拥有的 stdin-EOF dispose 阶梯；PTY 使用 `spawnTerminal()`，同时保留就绪与终端策略。`dsh-subagent-subprocess` 与 LSP 私有进程树辅助函数均被删除。MCP 传输 spawn、SDK 包管理器运行器、同步 TUI Git 探测和刻意保持轻依赖的 test-support 启动器因所有权或执行形状仍留在外部；适用的生产调用方共享凭据清除。
 
@@ -33,7 +33,7 @@ Status: implemented
 
 **把每一次进程启动都路由到 `ctx.subprocess`。**否决：MCP SDK 拥有其传输 spawn，SDK 向导没有 Cordis 上下文且需要继承式重定向，TUI 探测是同步的，support 启动器则刻意独立于产品 seam。PTY 分配迁到 `spawnTerminal()`，因为这项底层专用原语归提供方而非消费方所有。
 
-**改把 `run_in_background`/任务语义放进进程 seam。**否决：那条边界已经存在。`ctx.tasks` 拥有 id、所有权与通知，bash 工具则把 `BashProcess` 适配成任务钩子。进程 seam 位于 bash 执行器*之下*，而不是与任务注册表并列。
+**改把 `run_in_background`/任务语义放进 subprocess 能力 seam。**否决：那条边界已经存在。`ctx.tasks` 拥有 id、所有权与通知，bash 工具则把 `BashProcess` 适配成任务钩子。subprocess seam 位于 bash 执行器*之下*，而不是与任务注册表并列。
 
 **把 `ENV_OVERRIDES`（TERM=dumb、PAGER=cat 等）移入管理器。**否决：通用进程管理器不得把终端呈现策略强加给非终端消费方；对环境中凭据形态名称与 `DSH_*` 名称的清除是安全与身份不变式，予以保留，但终端友好性是 bash 工具自己的选择，经 spec 的显式 env 表达，而调用方自己的条目依旧优先。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
index 6b969a2c03..fc8cf85334 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.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 .agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
-2026-07-26-task-registry-seam.md: 57ac176cf6d2b0a50fcbcfacd77f6a26b462b582
-2026-07-26-task-registry-seam.zh.md: b81940a8f778f1ed9a65bf96e3a66c047fd234c2
+2026-07-26-task-registry-seam.md: 45801505f1729ec6094900acf94b4c17ed92c3b1
+2026-07-26-task-registry-seam.zh.md: 8dd90b34d2da1d22caba13fe8c388dab4a29be0d
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
index 57ac176cf6..45801505f1 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md
@@ -6,30 +6,30 @@ English | [中文](2026-07-26-task-registry-seam.zh.md)
 
 ## Problem
 
-The [background-task runtime](2026-06-20-generic-long-running-tool-runtime.md) shipped `TaskService` as one concrete package: `@deepseek-ai/dsh-tasks` owned both the `ctx.tasks` contract every producer and control surface programs against and the process-local implementation (the in-memory store, settlement bookkeeping, owner-cleanup effects, teardown). That bundling recouples the two rates of change the repository's [capability-seam rule](2026-06-13-capability-seams.md) separates: swapping the registry's storage or lifecycle backend would churn the same package whose types and `ctx.tasks` surface producers (`dsh-tool-bash`, `dsh-tool-pty`, `dsh-tool-subagent`), the control surface (`dsh-tool-tasks`), and `TaskKindMap` extenders import. Every other swappable capability in the harness — bash, pty, fs, skill, subagent, web, session persistence — already carries the interface / implementation / consumer split; the task registry was the remaining `core`-mode exception, guarded only by a `TODO(task-service-backend)` comment.
+The [background-task runtime](2026-06-20-generic-long-running-tool-runtime.md) shipped `TaskService` as one concrete package: `@deepseek-ai/dsh-tasks` owned both the `ctx.tasks` contract every producer and control surface programs against and the process-local provider (the in-memory store, settlement bookkeeping, owner-cleanup effects, teardown). That bundling recouples the two rates of change the repository's [capability-seam rule](2026-06-13-capability-seams.md) separates: swapping the registry's storage or lifecycle backend would churn the same package whose types and `ctx.tasks` surface producers (`dsh-tool-bash`, `dsh-tool-pty`, `dsh-tool-subagent`), the control surface (`dsh-tool-tasks`), and `TaskKindMap` extenders import. Every other swappable capability in the harness — bash, pty, fs, skill, subagent, web, session persistence — already carries the Service Definition / Service provider / Consumer split; the task registry was the remaining `core`-mode exception, guarded only by a `TODO(task-service-backend)` comment.
 
 ## Decision
 
 `tasks/` is now a three-package capability family in the bash-trio shape:
 
-- **`@deepseek-ai/dsh-tasks` (interface)** — the abstract `TaskService extends Service` owning `ctx.tasks`, the eight-method contract (`start`, `list`, `get`, `read`, `kill`, `wait`, `onTaskDone`, `attachSurface`), all vocabulary types (`TaskId`, `TaskKindMap`, `TaskStart`, `TaskHooks`, `TaskOutcome`, `TaskSnapshot`, `TaskRead`, `TaskDoneListener`), and the snapshot invariant companion. The class-level JSDoc states the semantics every implementation owes: registrations outlive producer and surface fibers, owned access is session-fenced, settlement is first-wins with contained listeners, and `start` refuses work while no control surface is attached.
-- **`@deepseek-ai/dsh-tasks-local` (implementation)** — `LocalTaskService`, the process-local registry moved verbatim: the in-memory store, per-kind counters, waiter bookkeeping, `TASK_WAIT_TIMEOUT` deadline code, owner-cleanup effects, and force-fail teardown. The `dsh-timeout` dependency moves here with it; the seam has no implementation dependencies.
-- **`@deepseek-ai/dsh-tool-tasks` (consumer)** — unchanged; it injects `'tasks'` and never imports implementation types.
+- **`@deepseek-ai/dsh-tasks` (Service Definition)** — the abstract `TaskService extends Service` owning `ctx.tasks`, the eight-method contract (`start`, `list`, `get`, `read`, `kill`, `wait`, `onTaskDone`, `attachSurface`), all vocabulary types (`TaskId`, `TaskKindMap`, `TaskStart`, `TaskHooks`, `TaskOutcome`, `TaskSnapshot`, `TaskRead`, `TaskDoneListener`), and the snapshot invariant companion. The class-level JSDoc states the semantics every Service provider owes: registrations outlive producer and surface fibers, owned access is session-fenced, settlement is first-wins with contained listeners, and `start` refuses work while no control surface is attached.
+- **`@deepseek-ai/dsh-tasks-local` (Service provider)** — `LocalTaskService`, the process-local registry moved verbatim: the in-memory store, per-kind counters, waiter bookkeeping, `TASK_WAIT_TIMEOUT` deadline code, owner-cleanup effects, and force-fail teardown. The `dsh-timeout` dependency moves here with it; the Service Definition package has no provider dependencies.
+- **`@deepseek-ai/dsh-tool-tasks` (Consumer)** — unchanged; it injects `'tasks'` and never imports provider types.
 
-Compositions load `dsh-tasks-local` where they previously loaded `dsh-tasks` (the CLI cordis.yml row, `agent-spine-demo`, test harnesses, the tool-catalog generator boot). Producer misconfiguration diagnostics ("background tasks unavailable: load …") name `dsh-tasks` — the seam that defines the absent `ctx.tasks` service — and the seam's own surfaces (its README and the direct-mount fence) point at implementations, so the producer message stays correct when another backend becomes the recommended default. Producers, `TaskKindMap` declaration merges, and the control surface keep importing `@deepseek-ai/dsh-tasks` only.
+Compositions load `dsh-tasks-local` where they previously loaded `dsh-tasks` (the CLI cordis.yml row, `agent-spine-demo`, test harnesses, the tool-catalog generator boot). Producer misconfiguration diagnostics ("background tasks unavailable: load …") name `dsh-tasks` — the Service Definition package that declares the absent `ctx.tasks` service — and the Service Definition package's own surfaces (its README and the direct-mount fence) point at Service providers, so the producer message stays correct when another backend becomes the recommended default. Producers, `TaskKindMap` declaration merges, and the control surface keep importing `@deepseek-ai/dsh-tasks` only.
 
-The seam keeps the in-process contract semantics unchanged: `TaskStart.run()` still passes callbacks and exact `Agent` objects, so a durable or cross-process backend still has design work to do before it can implement this interface (identity, restart, ownership, observation). The split moves that future work out of every consumer's dependency graph; it does not pre-design the backend.
+The seam keeps the in-process contract semantics unchanged: `TaskStart.run()` still passes callbacks and exact `Agent` objects, so a durable or cross-process backend still has design work to do before it can satisfy this Service Definition (identity, restart, ownership, observation). The split moves that future work out of every Consumer's dependency graph; it does not pre-design the backend.
 
 ## Alternatives considered
 
-**Keep the concrete service until a second backend exists (status quo).** This was the original runtime note's position: extracting an interface before a second implementation risks freezing the wrong boundary. It lost because the boundary is no longer speculative — the eight service methods and their semantics have been stable across every producer integration since introduction, they are exactly the surface `dsh-tool-tasks` and the producers already program against, and the repository convention treats swappable capabilities as three packages by default. The residual risk (a durable backend needing contract changes) is unchanged by the split: those changes would land in the seam package either way, and today they would also churn every consumer's implementation dependency.
+**Keep the concrete service until a second backend exists (status quo).** This was the original runtime note's position: extracting a Service Definition before a second provider risks freezing the wrong boundary. It lost because the boundary is no longer speculative — the eight service methods and their semantics have been stable across every producer integration since introduction, they are exactly the surface `dsh-tool-tasks` and the producers already program against, and the repository convention treats swappable capabilities as three packages by default. The residual risk (a durable backend needing contract changes) is unchanged by the split: those changes would land in the Service Definition package either way, and today they would also churn every Consumer's provider dependency.
 
-**Interface-only extraction inside one package (export an abstract class beside the concrete one).** Rejected because it separates nothing operationally: consumers still depend on the package that carries the implementation and its dependencies, and a replacement backend still cannot ship without the local one in its graph. The package boundary is the unit of independent evolution here.
+**Service-Definition-only extraction inside one package (export an abstract class beside the concrete one).** Rejected because it separates nothing operationally: Consumers still depend on the package that carries the provider and its dependencies, and a replacement backend still cannot ship without the local one in its graph. The package boundary is the unit of independent evolution here.
 
-**Splitting `types.ts` out but leaving the service concrete.** Rejected for the same reason — the types are not the seam; `ctx.tasks` and its method contract are. Producers need the service key and semantics, not just the shapes.
+**Splitting `types.ts` out but leaving the service concrete.** Rejected for the same reason — the types are not the complete capability; the `ctx.tasks` Service Definition and its method contract are. Producers need the service key and semantics, not just the shapes.
 
 ## Consequences
 
-Bought: the task registry now matches the repository-wide seam shape; a durable, remote, or instrumented registry is a sibling package implementing eight abstract methods, and no producer, control surface, or `TaskKindMap` extender changes when one lands. The seam README states the contract; the implementation README owns the lifecycle bookkeeping facts. The registry behavior suite (owner cleanup, settlement, waits, teardown) lives with `dsh-tasks-local`; the seam keeps a stub-subclass test pinning registration under `ctx.tasks` and single-service duplication behavior, plus the probe-based invariant suite.
+Bought: the task registry now matches the repository-wide seam shape; a durable, remote, or instrumented registry is a sibling Service provider implementing eight abstract methods, and no producer, control surface, or `TaskKindMap` extender changes when one lands. The Service Definition README states the contract; the provider README owns the lifecycle bookkeeping facts. The registry behavior suite (owner cleanup, settlement, waits, teardown) lives with `dsh-tasks-local`; the Service Definition package keeps a stub-subclass test pinning registration under `ctx.tasks` and single-service duplication behavior, plus the probe-based invariant suite.
 
-Cost: one more package (manifest, tsconfig, README, invariant companion), and compositions must name the implementation package. `abstract` erases at runtime and this package name used to be the mountable registry, so the seam constructor fails loudly when mounted directly — a stale composition row gets "load an implementation such as @deepseek-ai/dsh-tasks-local" at load time instead of a half-registered `ctx.tasks` failing far from the misconfiguration.
+Cost: one more package (manifest, tsconfig, README, invariant companion), and compositions must name the Service provider package. `abstract` erases at runtime and this package name used to be the mountable registry, so the Service Definition constructor fails loudly when mounted directly — a stale composition row gets "load a Service provider such as @deepseek-ai/dsh-tasks-local" at load time instead of a half-registered `ctx.tasks` failing far from the misconfiguration.
diff --git a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
index b81940a8f7..8dd90b34d2 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.zh.md
@@ -6,30 +6,30 @@ Status: implemented
 
 ## 问题
 
-[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包：`@deepseek-ai/dsh-tasks` 既拥有每个生产方和控制接口面向编程的 `ctx.tasks` 约定，也拥有进程内实现（内存存储、结算簿记、所有者清理 effect、拆除）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制接口（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` 接口。harness 中其余每项可替换能力——bash、pty、fs、skill（技能）、subagent、web、会话持久化——都已具备接口／实现／消费方三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
+[后台任务运行时](2026-06-20-generic-long-running-tool-runtime.md)交付时把 `TaskService` 做成了单个具体包：`@deepseek-ai/dsh-tasks` 既拥有每个生产方和控制接口面向编程的 `ctx.tasks` 约定，也拥有进程内 Service provider（内存存储、结算簿记、所有者清理 effect、拆除）。这种捆绑重新耦合了仓库[能力 seam 规则](2026-06-13-capability-seams.md)本要分离的两种变化速率：一旦替换注册表的存储或生命周期后端，被搅动的就是同一个包，而生产方（`dsh-tool-bash`、`dsh-tool-pty`、`dsh-tool-subagent`）、控制接口（`dsh-tool-tasks`）和 `TaskKindMap` 扩展方正是从这个包导入类型与 `ctx.tasks` 接口。harness 中其余每项可替换能力——bash、pty、fs、skill（技能）、subagent、web、会话持久化——都已具备 Service Definition / Service provider / Consumer 三分；任务注册表曾是仅剩的 `core` 模式例外，仅由一条 `TODO(task-service-backend)` 注释把守。
 
 ## 决策
 
 `tasks/` 如今是一个 bash 三件套形态的三包能力家族：
 
-- **`@deepseek-ai/dsh-tasks`（接口）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的约定（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachSurface`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个实现都必须兑现的语义：注册的存续期长于生产方与控制接口的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且在没有附加任何控制接口时 `start` 拒绝启动工作。
-- **`@deepseek-ai/dsh-tasks-local`（实现）**——`LocalTaskService`，即原样迁移的进程内注册表：内存存储、按 kind 划分的计数器、等待方簿记、`TASK_WAIT_TIMEOUT` deadline 代码、所有者清理 effect，以及强制失败的拆除。`dsh-timeout` 依赖随之迁入此包；seam 包不含任何实现依赖。
-- **`@deepseek-ai/dsh-tool-tasks`（消费方）**——保持不变；它注入 `'tasks'`，从不导入实现类型。
+- **`@deepseek-ai/dsh-tasks`（Service Definition）**——抽象的 `TaskService extends Service`，拥有 `ctx.tasks`、八个方法的约定（`start`、`list`、`get`、`read`、`kill`、`wait`、`onTaskDone`、`attachSurface`）、全部词汇类型（`TaskId`、`TaskKindMap`、`TaskStart`、`TaskHooks`、`TaskOutcome`、`TaskSnapshot`、`TaskRead`、`TaskDoneListener`），以及快照不变式配套插件。类级 JSDoc 陈述了每个 Service provider 都必须兑现的语义：注册的存续期长于生产方与控制接口的 fiber，有所有者的访问以会话为界，结算遵循首次结果优先且监听器错误被隔离，并且在没有附加任何控制接口时 `start` 拒绝启动工作。
+- **`@deepseek-ai/dsh-tasks-local`（Service provider）**——`LocalTaskService`，即原样迁移的进程内注册表：内存存储、按 kind 划分的计数器、等待方簿记、`TASK_WAIT_TIMEOUT` deadline 代码、所有者清理 effect，以及强制失败的拆除。`dsh-timeout` 依赖随之迁入此包；Service Definition 包不含任何提供方依赖。
+- **`@deepseek-ai/dsh-tool-tasks`（Consumer）**——保持不变；它注入 `'tasks'`，从不导入提供方类型。
 
-各组合在原先加载 `dsh-tasks` 的位置改为加载 `dsh-tasks-local`：CLI（命令行界面）的 cordis.yml 配置项、`agent-spine-demo`、各测试 harness，以及工具目录生成器的启动流程。生产方的配置错误诊断信息（「background tasks unavailable: load …」）点名 `dsh-tasks`——即定义缺失的 `ctx.tasks` 服务的 seam 包；seam 自身的对外呈现（其 README 与直接挂载防线）会指向各实现，因此当另一个后端日后成为推荐默认时，生产方的消息依旧正确。生产方、`TaskKindMap` 声明合并和控制接口仍然只导入 `@deepseek-ai/dsh-tasks`。
+各组合在原先加载 `dsh-tasks` 的位置改为加载 `dsh-tasks-local`：CLI（命令行界面）的 cordis.yml 配置项、`agent-spine-demo`、各测试 harness，以及工具目录生成器的启动流程。生产方的配置错误诊断信息（「background tasks unavailable: load …」）点名 `dsh-tasks`——即声明缺失的 `ctx.tasks` 服务的 Service Definition 包；Service Definition 包自身的对外呈现（其 README 与直接挂载防线）会指向各 Service provider，因此当另一个后端日后成为推荐默认时，生产方的消息依旧正确。生产方、`TaskKindMap` 声明合并和控制接口仍然只导入 `@deepseek-ai/dsh-tasks`。
 
-该 seam 保持进程内约定语义不变：`TaskStart.run()` 仍然传入回调和确切的 `Agent` 对象，因此持久化或跨进程后端在能实现此接口之前仍有设计工作要做（身份、重启、所有权、观察）。这次拆分把该项未来工作移出了每个消费方的依赖图；它并不预先设计后端。
+该 seam 保持进程内约定语义不变：`TaskStart.run()` 仍然传入回调和确切的 `Agent` 对象，因此持久化或跨进程后端在能满足此 Service Definition 之前仍有设计工作要做（身份、重启、所有权、观察）。这次拆分把该项未来工作移出了每个 Consumer 的依赖图；它并不预先设计后端。
 
 ## 曾考虑的替代方案
 
-**在第二个后端出现之前保持具体服务（维持现状）。**这正是运行时 Agent Note 当初的立场：在第二种实现出现前抽取接口，可能固化错误的边界。该方案落选，因为这条边界已不再是臆测：八个服务方法及其语义自引入以来在每一次生产方集成中都保持稳定，它们正是 `dsh-tool-tasks` 与各生产方已经面向编程的那套接口，而且仓库约定默认将可替换能力拆成三个包。剩余风险（持久化后端可能需要变更约定）不因这次拆分而改变：无论拆分与否，这类变更都会落在 seam 包里；而若维持现状，它们今天还会连带搅动每个消费方的实现依赖。
+**在第二个后端出现之前保持具体服务（维持现状）。**这正是运行时 Agent Note 当初的立场：在第二个 Service provider 出现前抽取 Service Definition，可能固化错误的边界。该方案落选，因为这条边界已不再是臆测：八个服务方法及其语义自引入以来在每一次生产方集成中都保持稳定，它们正是 `dsh-tool-tasks` 与各生产方已经面向编程的那套接口，而且仓库约定默认将可替换能力拆成三个包。剩余风险（持久化后端可能需要变更约定）不因这次拆分而改变：无论拆分与否，这类变更都会落在 Service Definition 包里；而若维持现状，它们今天还会连带搅动每个 Consumer 的提供方依赖。
 
-**在单个包内仅抽取接口（在具体类旁导出一个抽象类）。**否决，因为它在运作层面并未分离任何东西：消费方依然依赖携带实现及其依赖项的那个包，而替换后端若不把本地实现纳入自身依赖图，就仍然无法发布。在这里，包边界才是独立演进的单位。
+**在单个包内仅抽取 Service Definition（在具体类旁导出一个抽象类）。**否决，因为它在运作层面并未分离任何东西：Consumer 依然依赖携带 Service provider 及其依赖项的那个包，而替换后端若不把本地 Service provider 纳入自身依赖图，就仍然无法发布。在这里，包边界才是独立演进的单位。
 
-**拆出 `types.ts` 但让服务保持具体。**基于同样的理由否决：类型并不是 seam，`ctx.tasks` 及其方法约定才是。生产方需要的是服务键和语义，而不只是类型形状。
+**拆出 `types.ts` 但让服务保持具体。**基于同样的理由否决：类型并不是完整能力，`ctx.tasks` Service Definition 及其方法约定才是。生产方需要的是服务键和语义，而不只是类型形状。
 
 ## 后果
 
-换来的是：任务注册表如今与全仓库通行的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的同级包，这样的注册表落地时，任何生产方、控制接口或 `TaskKindMap` 扩展方都无需改动。seam 包的 README 陈述约定；生命周期簿记方面的事实归实现包的 README 所有。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；seam 包保留一个桩子类（stub subclass）测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
+换来的是：任务注册表如今与全仓库通行的 seam 形态一致；持久化、远程或带插桩的注册表将是一个实现八个抽象方法的同级 Service provider，这样的注册表落地时，任何生产方、控制接口或 `TaskKindMap` 扩展方都无需改动。Service Definition 的 README 陈述约定；生命周期簿记方面的事实归 Service provider 的 README 所有。注册表行为测试套件（所有者清理、结算、等待、拆除）随 `dsh-tasks-local` 存放；Service Definition 包保留一个桩子类（stub subclass）测试，固定 `ctx.tasks` 下的注册行为与单一服务的重复注册行为，外加基于探针的不变式测试套件。
 
-代价是：多出一个包，即多一份 manifest（元数据清单）、tsconfig、README 与不变式配套插件；同时各组合必须点名实现包。`abstract` 在运行时会被擦除，而这个包名过去正是可挂载的具体注册表，因此直接挂载 seam 时，其构造函数会明确报错——一条陈旧的组合配置行会在加载时得到「load an implementation such as @deepseek-ai/dsh-tasks-local」，而不是一个未完整注册的 `ctx.tasks` 在远离错误配置处才失败。
+代价是：多出一个包，即多一份 manifest（元数据清单）、tsconfig、README 与不变式配套插件；同时各组合必须点名 Service provider 包。`abstract` 在运行时会被擦除，而这个包名过去正是可挂载的具体注册表，因此直接挂载 Service Definition 时，其构造函数会明确报错——一条陈旧的组合配置行会在加载时得到「load a Service provider such as @deepseek-ai/dsh-tasks-local」，而不是一个未完整注册的 `ctx.tasks` 在远离错误配置处才失败。
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
index cf0c363672..16ec810666 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.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 .agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
-2026-07-27-dispose-ladder-to-consumer.md: e9af88e8e7ef962213a74e96a249241cbe8d5994
-2026-07-27-dispose-ladder-to-consumer.zh.md: afa385120d6ac33e6084a56585d8d610622e604c
+2026-07-27-dispose-ladder-to-consumer.md: 25deabe811f8eb361690fec2d4fdd40cdf23dd57
+2026-07-27-dispose-ladder-to-consumer.zh.md: 359f800c9c190b7af7c08bf1d7b9b5ebf275cbaf
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
index e9af88e8e7..25deabe811 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
@@ -14,10 +14,10 @@ The ladder moves to its one consumer. `dsh-subagent-acp` owns `disposeAcpChild(c
 
 ## Alternatives considered
 
-**Keep the ladder on the handle as a convenience.** Rejected: a seam method every implementation must provide is not a convenience, it is contract surface — and this one encodes one consumer's cooperation shape (stdin-EOF-first) as if it were process vocabulary. The seam's own README already had to caveat that children quiescing on other signals need "their own tier-1", which is the admission that the ladder is policy.
+**Keep the ladder on the handle as a convenience.** Rejected: a Service Definition method every Service provider must implement is not a convenience, it is contract surface — and this one encodes one consumer's cooperation shape (stdin-EOF-first) as if it were process vocabulary. The seam's own README already had to caveat that children quiescing on other signals need "their own tier-1", which is the admission that the ladder is policy.
 
 **Move the ladder to a shared helper package.** Rejected: one consumer. A second out-of-process backend with the same stdin-EOF cooperation shape can lift `disposeAcpChild` to shared code when it exists; extracting now would recreate `dsh-subagent-subprocess`, the single-purpose library this stack just deleted.
 
 ## Consequences
 
-Bought: the seam is one method and one type smaller; implementations owe four verbs and no teardown policy; the cooperative EOF window lives beside the ACP config field that tunes it, while the subprocess owner alone owns the termination window and final join. Cost: a future backend wanting EOF-first teardown writes ~20 lines against the verbs (or lifts the ACP helper); the ladder's tier tests live in the ACP suite, and the seam suite pins the verbs the ladder composes (bounded `waitForExit` false before escalation and an unbounded whole-tree join after it) instead of the composed policy.
+Bought: the Service Definition is one method and one type smaller; Service providers owe four verbs and no teardown policy; the cooperative EOF window lives beside the ACP config field that tunes it, while the subprocess owner alone owns the termination window and final join. Cost: a future backend wanting EOF-first teardown writes ~20 lines against the verbs (or lifts the ACP helper); the ladder's tier tests live in the ACP suite, and the Service Definition suite pins the verbs the ladder composes (bounded `waitForExit` false before escalation and an unbounded whole-tree join after it) instead of the composed policy.
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
index afa385120d..359f800c9c 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
@@ -10,14 +10,14 @@ Status: implemented
 
 ## 决策
 
-阶梯移入其唯一消费方。`dsh-subagent-acp` 拥有 `disposeAcpChild(child, eofGraceMs)`，完全构建在 seam 的公开动词之上：关闭 `stdin`，以 `eofGraceMs` 约束一次 `waitForExit`，随后调用 `terminate()`（其 SIGTERM→spec 宽限期→SIGKILL 升级已拥有信号定时器），再无界等待 `waitForExit()`，由子进程所有者证明整棵进程树已经退出。seam 保留 `kill`／`terminate`／`waitForExit`——机制而非策略——而 `waitForExit(signal?)` 恰是消费方阶梯在协作层确认进程树真正退出所需的完全停稳探针，无需从终止宽限期再派生一个定时器。seam 的句柄少了一个方法和一个导出接口。
+阶梯移入其唯一消费方。`dsh-subagent-acp` 拥有 `disposeAcpChild(child, eofGraceMs)`，完全构建在 seam 的公开动词之上：关闭 `stdin`，以 `eofGraceMs` 约束一次 `waitForExit`，随后调用 `terminate()`（其 SIGTERM→spec 宽限期→SIGKILL 升级已拥有信号定时器），再无界等待 `waitForExit()`，由子进程责任方证明整棵进程树已经退出。seam 保留 `kill`／`terminate`／`waitForExit`——机制而非策略——而 `waitForExit(signal?)` 恰是消费方阶梯在协作层确认进程树真正退出所需的停稳探针，无需从终止宽限期再派生一个定时器。seam 的句柄少了一个方法和一个导出接口。
 
 ## 曾考虑的替代方案
 
-**把阶梯作为便利方法留在句柄上。**否决：一个每个实现都必须提供的 seam 方法不是便利，而是约定表面——而这一个把某一消费方的配合形状（stdin EOF 打头）当作进程词汇来编码。seam 自己的 README 早已不得不加注「依赖其他信号才能完全停稳的子进程需要自己的第一阶」，这本身就是承认该阶梯是策略。
+**把阶梯作为便利方法留在句柄上。**否决：一个每个 Service provider 都必须实现的 Service Definition 方法不是便利，而是约定表面——而这一个把某一消费方的配合形状（stdin EOF 打头）当作进程词汇来编码。seam 自己的 README 早已不得不加注「依赖其他信号才能完全停稳的子进程需要自己的第一阶」，这本身就是承认该阶梯是策略。
 
 **把阶梯移到共享辅助包。**否决：只有一个消费方。当第二个具有相同 stdin EOF 配合形状的进程外后端出现时，可以再把 `disposeAcpChild` 提升为共享代码；现在抽取只会重造 `dsh-subagent-subprocess`——这组堆叠变更刚刚删掉的那个单一用途库。
 
 ## 后果
 
-换来的是：seam 少了一个方法和一个类型；实现只需提供四个动词，无需提供拆卸策略；协作式 EOF 时间窗与调节它的 ACP 配置字段住在一起，而终止时间窗与最终的整树退出等待仅由子进程所有者拥有。代价：未来想要 EOF 打头拆卸的后端需针对这些动词写约 20 行（或直接搬 ACP 的辅助函数）；阶梯的层级测试位于 ACP 套件，seam 套件转而钉住阶梯所组合的动词（升级前有界 `waitForExit` 返回假，升级后无界等待整棵进程树退出），而非组合后的策略。
+买到的：Service Definition 少了一个方法和一个类型；Service provider 只欠四个动词，不欠拆卸策略；协作式 EOF 时间窗与调节它的 ACP 配置字段住在一起，而终止时间窗与最终的整树退出等待仅由子进程责任方拥有。代价：未来想要 EOF 打头拆卸的后端需针对这些动词写约 20 行（或直接搬 ACP 的辅助函数）；阶梯的层级测试位于 ACP 套件，Service Definition 套件转而钉住阶梯所组合的动词（升级前有界 `waitForExit` 返回假，升级后无界等待整棵进程树退出），而非组合后的策略。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
index 018c4812b1..2ab9d7c12b 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.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 .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
-2026-07-28-directory-picker-capability-seam.md: 01968990db81852dbf965a90fc151bab357ecb55
-2026-07-28-directory-picker-capability-seam.zh.md: f96f835c5f68d0ef6eff5410a7db18dc24eb8c2c
+2026-07-28-directory-picker-capability-seam.md: 898d8dc3a6fa41cfacc694f15c88d3a71c48f413
+2026-07-28-directory-picker-capability-seam.zh.md: fce9a801ad8535b264c91f6d3b32373e35cb146d
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
index 01968990db..898d8dc3a6 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
@@ -6,11 +6,11 @@ English | [中文](2026-07-28-directory-picker-capability-seam.zh.md)
 
 ## Problem
 
-The web GUI's "Open local folder" flow was hardwired to one interaction: `host.pickDirectory` invoked a native OS chooser compiled into `dsh-host-apiproxy` (private module, test-only injection seam). That shape cannot serve remote deployments — no OS dialog reaches a browser on another machine — and the planned in-app directory browser (Figma `Harness` 802-56979) needs listing/creation primitives, which are a different interaction contract, not a different implementation of the same one. Swapping interactions required editing gateway source, against the repo's everything-is-a-plugin stance.
+The web GUI's "Open local folder" flow was hardwired to one interaction: `host.pickDirectory` invoked a native OS chooser compiled into `dsh-host-apiproxy` (private module, test-only injection point). That shape cannot serve remote deployments — no OS dialog reaches a browser on another machine — and the planned in-app directory browser (Figma `Harness` 802-56979) needs listing/creation primitives, which are a different interaction contract, not a different implementation of the same one. Swapping interactions required editing gateway source, against the repo's everything-is-a-plugin stance.
 
 ## Decision
 
-A three-package capability seam in `packages/host/` — `directory-picker` (interface), `directory-picker-native`, `directory-picker-browse` (backends) — with one contract method: `capability()` returns a **discriminated union**, `{ kind: 'native', pick(signal) }` or `{ kind: 'browse', list(path?), createDirectory(path, name) }`. The gateway (`dsh-host-apiproxy`) injects `directoryPicker`, serves the matching RPCs, and answers `directory-picker-unavailable` for the other kind. The union is discriminated because the backends differ in *interaction shape* — flattening them into one method set would force every backend to fake the other's shape.
+A three-package capability seam in `packages/host/` — `directory-picker` (Service Definition), `directory-picker-native`, `directory-picker-browse` (backends) — with one contract method: `capability()` returns a **discriminated union**, `{ kind: 'native', pick(signal) }` or `{ kind: 'browse', list(path?), createDirectory(path, name) }`. The gateway (`dsh-host-apiproxy`) injects `directoryPicker`, serves the matching RPCs, and answers `directory-picker-unavailable` for the other kind. The union is discriminated because the backends differ in *interaction shape* — flattening them into one method set would force every backend to fake the other's shape.
 
 **The client side is slot-composed, not advertisement-branched.** ui-workspace's two trigger surfaces each declare a `single` directory-flow hole (`conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`; two keys because a hole has exactly one declaring slot entry — same owner contract, same occupant). Backend packages are **dual-face**: the browser half registers the matching interaction into both holes — `-native` a renderless occupant driving `host.pickDirectory`, `-browse` the in-app Select Workspace Directory dialog. The hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`) carries the whole exchange: ui-workspace keeps the trigger (menu entry rendered only while the hole is occupied) and the adoption (`createWorkspace({path})`, retryable error dialog, Choose again), the occupant owns everything between `open` and the picked path. One `cordis.yml` row therefore swaps the host capability and the client flow together; a mismatch is impossible by construction, and mounting two flow packages fails at client load (`single` hole). The earlier `host.describe.directoryPicker` advertisement and the client's kind branching are deleted — with composition wiring both sides, a wire fact for the client to branch on had no remaining consumer. The hole registry (`ctx.slots.entries`) replaces it as the per-menu-open occupancy read.
 
@@ -30,7 +30,7 @@ Placement and policy rulings folded into this decision:
 ## Alternatives considered
 
 - **Extend `ctx.fs` with browse methods.** Rejected: authority-domain coupling above; also a listing-for-display contract (hidden flags, crumbs, home anchor) does not belong on a storage seam.
-- **One uniform seam method set (`pick(): path`).** Rejected: an in-app browser cannot be served behind a single host-side call — the browsing loop lives in the client and needs primitives on the wire; the native chooser cannot implement primitives. The interaction difference is irreducible, hence the discriminant.
+- **One uniform Service Definition method set (`pick(): path`).** Rejected: an in-app browser cannot be served behind a single host-side call — the browsing loop lives in the client and needs primitives on the wire; the native chooser cannot implement primitives. The interaction difference is irreducible, hence the discriminant.
 - **Direct stdlib calls inside apiproxy (no seam).** Rejected: keeps the gateway the only swap point (source edits), loses fixture/test backends, and contradicts the plugin doctrine that motivated the work.
 - **Adopting a file-manager/drive-enumeration dependency.** Rejected per the survey above; recorded here as the dependency policy requires.
 - **A flip-label show-hidden toggle ("Hide hidden files").** Rejected: a flipping action label is ambiguous between state and action and doubles the negative; the fixed label with a pressed presentation states both at once.
@@ -38,7 +38,7 @@ Placement and policy rulings folded into this decision:
 - **A permanently visible path input above the Miller view.** Rejected: the breadcrumb is already the "where am I" reading, and a second always-present field duplicates it while costing a row of a 500px card that the columns need. The glyph plus the hover-lit zone puts the affordance on the bar that already answers the question.
 - **Scanning the draft on every keystroke, or only on Enter.** Per keystroke: walking one path segment issues a listing per character, most of them for directories the operator is typing through, not at. Only on Enter (what shipped first): the panes and the typed text disagreed for the whole edit — the complaint this bullet answers. The 250ms rest keeps one scan per directory the typing actually settles on.
 - **Emptying a pane on a prefix miss (what shipped first).** Rejected: mid-name the miss is the normal state, so the pane blanked exactly while the operator needed it to confirm the name; releasing the filter keeps the level readable and costs only the transient wideness.
-- **A wire `separator` field on `DirectoryListing` (host stamps `path.sep`).** Deferred, not rejected: it is the authoritative form — a POSIX home directory containing a backslash defeats the `listing.home` heuristic — but it touches the seam type and every backend; the browse client's `separatorOf` carries a TODO pointing at this alternative until a wire change is next scheduled.
+- **A wire `separator` field on `DirectoryListing` (host stamps `path.sep`).** Deferred, not rejected: it is the authoritative form — a POSIX home directory containing a backslash defeats the `listing.home` heuristic — but it touches the Service Definition type and every backend; the browse client's `separatorOf` carries a TODO pointing at this alternative until a wire change is next scheduled.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
index f96f835c5f..fce9a801ad 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
@@ -6,11 +6,11 @@
 
 ## 问题
 
-web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入缝）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互约定**，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
+web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入点）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互约定**，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
 
 ## 决策
 
-在 `packages/host/` 落一个三包能力 seam——`directory-picker`（接口）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一约定方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。
+在 `packages/host/` 落一个三包能力 seam——`directory-picker`（Service Definition）、`directory-picker-native`、`directory-picker-browse`（后端）——唯一约定方法 `capability()` 返回**可辨识联合**：`{ kind: 'native', pick(signal) }` 或 `{ kind: 'browse', list(path?), createDirectory(path, name) }`。网关（`dsh-host-apiproxy`）注入 `directoryPicker`，提供对应的 RPC，另一种 kind 的调用以 `directory-picker-unavailable` 应答。联合之所以可辨识，是因为后端差异在**交互形态**——压平成统一方法集会逼每个后端伪装另一方的形态。
 
 **client 侧靠 slot 组合，而非按广播分支。** ui-workspace 的两个触发表层各自声明一个 `single` 目录流洞（`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`；之所以是两个 key，是因为一个洞只有一个声明它的 slot entry——owner 约定相同、占用者相同）。后端包是**双面包**：browser half 把匹配的交互注册进两个洞——`-native` 是驱动 `host.pickDirectory` 的无渲染占用者，`-browse` 是应用内的选择工作区目录对话框。洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）承载整个交换：ui-workspace 保留触发（菜单入口仅在洞被占用时渲染）与接纳（`createWorkspace({path})`、可重试的错误对话框、重新选择），占用者持有从 `open` 到所选路径之间的一切。因此一行 `cordis.yml` 同时切换宿主能力与 client 流程；错配在构造上不可能，同时挂两个流程包会在 client 加载期失败（`single` 洞）。早先的 `host.describe.directoryPicker` 广播与客户端 kind 分支被删除——组合已经接好两侧后，供客户端分支用的 wire 事实不再有任何消费者。洞注册表（`ctx.slots.entries`）取而代之，成为每次打开菜单的占用读取。
 
@@ -30,7 +30,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick
 ## 曾考虑的替代方案
 
 - **给 `ctx.fs` 增加浏览方法。** 否决：上述权限域耦合；且面向展示的列举约定（hidden 标志、面包屑、home 锚点）不属于存储 seam。
-- **统一方法集的 seam（`pick(): path`）。** 否决：应用内浏览器无法藏在一次宿主侧调用后面——浏览循环在客户端，需要协议上的原语；而对话框实现不了原语。交互差异不可约，故用判别标签。
+- **统一的 Service Definition 方法集（`pick(): path`）。** 否决：应用内浏览器无法藏在一次宿主侧调用后面——浏览循环在客户端，需要协议上的原语；而对话框实现不了原语。交互差异不可约，故用判别标签。
 - **apiproxy 里直接调标准库（不建 seam）。** 否决：换装点仍是改网关源码，失去 fixture／测试后端，与促成这项工作的插件教义相悖。
 - **引入文件管理器／盘符枚举依赖。** 按上文调研否决；依赖政策要求记录于此。
 - **动作标签随状态翻转的"显示隐藏"开关（"隐藏隐藏文件"）。** 否决：会翻转的动作标签在状态与动作之间有歧义，还把否定叠了两层；固定标签加按下态呈现一次说清两者。
@@ -38,7 +38,7 @@ web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pick
 - **在 Miller 视图上方常驻一个路径输入框。** 否决：面包屑本就在回答"我在哪儿"，再常驻一个字段是重复回答，还要从 500px 卡片里挪走一行——那是列需要的高度。图标加悬停亮起的区域，把这个入口放在了已经回答该问题的那一栏上。
 - **每敲一个键就扫描草稿，或只在 Enter 时扫描。** 每键扫描：走完一段路径就是每个字符一次列举，其中多数目录操作者只是路过而非停留。只在 Enter 时扫描（最初落地的行为）：整个编辑过程中各栏与所键入文本各说各话——正是本条所回应的抱怨。250ms 的停顿把扫描收敛为"键入真正停下来的每个目录一次"。
 - **前缀无一匹配时清空该栏（最初落地的行为）。** 否决：名字敲到一半时"无匹配"才是常态，于是恰恰在操作者需要它确认名字时把栏清空了；解除过滤保住了层级的可读性，代价只是短暂的宽松。
-- **在 `DirectoryListing` 上增设线上 `separator` 字段（宿主标注 `path.sep`）。** 延期而非否决：它才是权威形态——含反斜杠的 POSIX 家目录会击穿 `listing.home` 启发式——但它触及 seam 类型与每个后端；browse 客户端的 `separatorOf` 挂着指向本方案的 TODO，直到下次安排线上变更。
+- **在 `DirectoryListing` 上增设线上 `separator` 字段（宿主标注 `path.sep`）。** 延期而非否决：它才是权威形态——含反斜杠的 POSIX 家目录会击穿 `listing.home` 启发式——但它触及 Service Definition 类型与每个后端；browse 客户端的 `separatorOf` 挂着指向本方案的 TODO，直到下次安排线上变更。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
index e876d151ab..512bd4fac7 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.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 .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
-2026-07-28-user-settings-seam.md: bf93f95168b1b6d0dec5a9fc2c9aac5531f0564a
-2026-07-28-user-settings-seam.zh.md: 42e1196cfd8a4cc2ad1a4e2e2fee77bbd5ebbcd2
+2026-07-28-user-settings-seam.md: 62eae0db157d61266af165f609daaefcd7d5e285
+2026-07-28-user-settings-seam.zh.md: bf0f5d850f4cf303efdbd6476ae210cf8779a31d
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
index bf93f95168..62eae0db15 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-28-user-settings-seam.zh.md)
 
-> Scope: the `packages/settings/` capability family — the abstract seam, the file-backed provider, and the composition boundary between user settings and `cordis.yml`. The [web config-tree note](2026-07-24-web-config-tree-boot-and-transport-layering.md) recorded "the profile write path" as a deferral; this seam is that write path's owner. Consumer migrations (theme, locale, default model route) and the web `settings.*` RPC surface are follow-ups, not part of this note's shipped scope.
+> Scope: the `packages/settings/` capability family — the Service Definition, the file-backed provider, and the composition boundary between user settings and `cordis.yml`. The [web config-tree note](2026-07-24-web-config-tree-boot-and-transport-layering.md) recorded "the profile write path" as a deferral; this seam is that write path's owner. Consumer migrations (theme, locale, default model route) and the web `settings.*` RPC surface are follow-ups, not part of this note's shipped scope.
 
 ## Problem
 
@@ -14,7 +14,7 @@ User-editable configuration had no owner: `dsh web` read a cwd-anchored profile
 
 **Two planes with a litmus test.** `cordis.yml` (+ Include patches) stays the composition plane: which plugins exist, wiring, deployment config, owned by the orchestrator and upgraded with the product. A settings namespace carries only the user-editable subset; the test is "should the personal config page edit it?" Values live in both planes without ambiguity because layering is the contract: schema defaults, then the registrant's composition `base` (its entry-config subset), then the user document section.
 
-**Three-package seam mirroring `session-persistence/`.** `dsh-settings` owns the abstract `Settings` service: namespace registry, layered resolution, schema validation, per-namespace deep-equal change detection, and the `settings/updated` commit event. Providers implement only `writable`/`load()`/`persist(ns, section)` and push externally observed documents through the protected `publish(doc)` — so hot-update semantics are identical across providers, and a network configuration-center backend (nacos-style, possibly read-only) is a sibling package away. `dsh-settings-local` is the file provider: YAML/JSON under `resolveSpec` (explicit defaulting to `<DSH_HOME>/settings.yaml`), chokidar watch, read-modify-write persists under a cross-process writer lock with atomic `0600` tmp+rename commits, leaf-level diff patching of the written namespace (comments survive untouched nodes), and content-equality self-write suppression ([write-path integrity note](2026-07-30-settings-write-path-integrity.md)).
+**Three-package boundary mirroring `session-persistence/`.** `dsh-settings` owns the abstract `Settings` service: namespace registry, layered resolution, schema validation, per-namespace deep-equal change detection, and the `settings/updated` commit event. Providers implement only `writable`/`load()`/`persist(ns, section)` and push externally observed documents through the protected `publish(doc)` — so hot-update semantics are identical across providers, and a network configuration-center backend (nacos-style, possibly read-only) is a sibling package away. `dsh-settings-local` is the file provider: YAML/JSON under `resolveSpec` (explicit defaulting to `<DSH_HOME>/settings.yaml`), chokidar watch, read-modify-write persists under a cross-process writer lock with atomic `0600` tmp+rename commits, leaf-level diff patching of the written namespace (comments survive untouched nodes), and content-equality self-write suppression ([write-path integrity note](2026-07-30-settings-write-path-integrity.md)).
 
 **Registrations are caller-fiber effects.** `register()` runs through the service proxy, so `this.ctx` is the registrant's context and the registration rides `ctx.effect`: disposing the registrant removes the namespace and its watchers (proven by the HMR disposal test), while the user's section keeps living in storage for the next owner.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
index 42e1196cfd..bf0f5d850f 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-28-user-settings-seam.md) | 中文
 
-> 范围：`packages/settings/` 能力族——抽象 seam、文件 provider，以及用户设置与 `cordis.yml` 的组合边界。[web config-tree note](2026-07-24-web-config-tree-boot-and-transport-layering.md) 曾把"profile 写路径"记为延后项；本 seam 就是该写路径的归属。消费者迁移（主题、语言、默认模型路由）与 web `settings.*` RPC 面是后续工作，不在本 note 已交付范围内。
+> 范围：`packages/settings/` 能力族——Service Definition、文件 provider，以及用户设置与 `cordis.yml` 的组合边界。[web config-tree note](2026-07-24-web-config-tree-boot-and-transport-layering.md) 曾把"profile 写路径"记为延后项；本 seam 就是该写路径的归属。消费者迁移（主题、语言、默认模型路由）与 web `settings.*` RPC 面是后续工作，不在本 note 已交付范围内。
 
 ## 问题
 
@@ -14,7 +14,7 @@ Status: implemented
 
 **两个面，一条判定。**`cordis.yml`（+ Include patches）仍是组合面：有哪些插件、接线、部署配置，归 orchestrator 所有并随产品升级。settings namespace 只承载用户可编辑子集；判定是"个人配置页应该能改它吗？"值可同时存在于两个面而不歧义，因为分层就是约定：schema 默认值，然后注册方的组合 `base`（其 entry 配置子集），最后用户文档分节。
 
-**镜像 `session-persistence/` 的三包 seam。**`dsh-settings` 拥有抽象 `Settings` 服务：namespace 注册表、分层解析、schema 校验、按 namespace 深相等变更检测，以及 `settings/updated` 提交事件。provider 只实现 `writable`/`load()`/`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档——因此热更新语义对所有 provider 一致，网络配置中心后端（nacos 类，可能只读）只是一个平级包的距离。`dsh-settings-local` 是文件 provider：`resolveSpec` 显式默认到 `<DSH_HOME>/settings.yaml` 的 YAML/JSON、chokidar 监听、跨进程写锁下以 `0600` tmp+rename 原子提交的读-改-写 persist、对被写 namespace 的叶子级 diff 修补（未触碰节点的注释得以保留）、按内容相等抑制自写（[write-path integrity note](2026-07-30-settings-write-path-integrity.md)）。
+**镜像 `session-persistence/` 的三包边界。**`dsh-settings` 拥有抽象 `Settings` 服务：namespace 注册表、分层解析、schema 校验、按 namespace 深相等变更检测，以及 `settings/updated` 提交事件。provider 只实现 `writable`/`load()`/`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档——因此热更新语义对所有 provider 一致，网络配置中心后端（nacos 类，可能只读）只是一个平级包的距离。`dsh-settings-local` 是文件 provider：`resolveSpec` 显式默认到 `<DSH_HOME>/settings.yaml` 的 YAML/JSON、chokidar 监听、跨进程写锁下以 `0600` tmp+rename 原子提交的读-改-写 persist、对被写 namespace 的叶子级 diff 修补（未触碰节点的注释得以保留）、按内容相等抑制自写（[write-path integrity note](2026-07-30-settings-write-path-integrity.md)）。
 
 **注册是调用方 fiber 上的 effect。**`register()` 经服务代理调用，`this.ctx` 即注册方 context，注册挂在 `ctx.effect` 上：dispose 注册方即移除 namespace 及其观察者（HMR disposal 测试证明），而用户的分节继续留在存储中等待下一任 owner。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index 15189e7387..3a6b661601 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.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 .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
-2026-07-30-credential-boundaries-and-atomic-registration.md: 94b32c3cfaa3e1c5059573881a2f393d29aed3ac
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 088e24cbfd7db9da73c2ed3e3d11fdef24249c37
+2026-07-30-credential-boundaries-and-atomic-registration.md: 300280e6d4f8be2c0519efcb7ecfc82028d05445
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 2b66c543bdd80612bee65a6e6e4a78ab565d5188
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
index 94b32c3cfa..300280e6d4 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-30-credential-boundaries-and-atomic-registration.zh.md)
 
-> Scope: the third review round over the [request-level LLM configuration seam](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this round applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
+> Scope: the third review round over the [request-level LLM configuration boundary](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this round applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
 
 ## Problem
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index 088e24cbfd..2b66c543bd 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-30-credential-boundaries-and-atomic-registration.md) | 中文
 
-> 范围：对[请求级 LLM（大语言模型）配置 seam](2026-07-29-request-level-llm-config-credentials.md)的第三轮评审——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：本轮把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
+> 范围：对[请求级 LLM（大语言模型）配置边界](2026-07-29-request-level-llm-config-credentials.md)的第三轮评审——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：本轮把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
 
 ## 问题
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
index a066480489..b478070862 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.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 .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
-2026-07-30-followup-enqueue-and-owned-runs.md: 54f4af75eeb29b06504fa2629b0665f3e5f4c4ee
-2026-07-30-followup-enqueue-and-owned-runs.zh.md: 226f0b9b61883cee5f6e321ae6b89b7b27b79e35
+2026-07-30-followup-enqueue-and-owned-runs.md: e0561f8cfc975dd60e69307b160070c292efff8e
+2026-07-30-followup-enqueue-and-owned-runs.zh.md: a807b3ebe47399cae95c38bc2232e20e00e839f5
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
index 54f4af75ee..e0561f8cfc 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-30-followup-enqueue-and-owned-runs.zh.md)
 
 `Agent.followup()` identifies and queues a user message, but one follow-up does not own the activity that follows it. Steering, injected context, tool continuations, recovery, and later queued messages can all contribute before the agent next becomes idle. A `MessageId` can therefore prove inbox admission, but it cannot identify which assistant message or `turn/end` is the result of that input.
 
-The [one-send-one-turn decision](../simplification/2026-07-17-one-send-one-turn.md) already rejects a per-send completion handle at the core seam. Protocol and SDK layers that pair one prompt request with a turn result manufacture that missing relationship downstream. The pairing becomes ambiguous as soon as activity admits more input, and it exposes turn mechanics as if they were a prompt-level outcome.
+The [one-send-one-turn decision](../simplification/2026-07-17-one-send-one-turn.md) already rejects a per-send completion handle in the core API. Protocol and SDK layers that pair one prompt request with a turn result manufacture that missing relationship downstream. The pairing becomes ambiguous as soon as activity admits more input, and it exposes turn mechanics as if they were a prompt-level outcome.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
index 226f0b9b61..a807b3ebe4 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `Agent.followup()` 会标识一条用户消息并将其排入队列，但单次 follow-up 并不拥有随后发生的活动。在 agent（智能体）下一次进入 idle 前，steering（中途引导）、注入的上下文、工具续行、恢复和后续排队消息都可能参与活动。因此，`MessageId` 可以证明 inbox 已准入，但不能标识哪一条 assistant 消息或哪一个 `turn/end` 是该输入的结果。
 
-[one-send-one-turn 决策](../simplification/2026-07-17-one-send-one-turn.md) 已经在核心 seam 中排除了按 send 返回完成句柄的设计。凡是把一项提示词请求与一个轮次结果配对的协议层和 SDK 层，都会在下游人为构造这一缺失的关系。一旦活动准入更多输入，该配对就会产生歧义，还会把轮次机制暴露为提示词级结果。
+[one-send-one-turn 决策](../simplification/2026-07-17-one-send-one-turn.md) 已经在核心 API 中排除了按 send 返回完成句柄的设计。凡是把一项提示词请求与一个轮次结果配对的协议层和 SDK 层，都会在下游人为构造这一缺失的关系。一旦活动准入更多输入，该配对就会产生歧义，还会把轮次机制暴露为提示词级结果。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
index 53eb3cefe5..df68353802 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.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 .agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
-2026-07-30-package-manager-native-repository-cache.md: 0ea145f20a58e4e3e9feb7ba5574818c0352e2c4
-2026-07-30-package-manager-native-repository-cache.zh.md: a4ad07c42eec7b05f51b18aaf54fcfedaa4d4b3c
+2026-07-30-package-manager-native-repository-cache.md: 38e7356d4abfc8eba8854f0a96700da448ff4ac4
+2026-07-30-package-manager-native-repository-cache.zh.md: 6833eeb4279c9feb9ac1860e780b8ed58b09d334
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
index 0ea145f20a..38e7356d4a 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.md
@@ -32,7 +32,7 @@ An identical specifier permanently reuses its published entry. The caller change
 
 **Disable repository lifecycle scripts.** Rejected because common plugin repositories need a declarative `prepare` step to validate and package their plugin subdirectory. The trust boundary is explicit configuration of executable source, not an incomplete illusion that only static files can run.
 
-**Introduce a Cordis repository service.** Rejected because cache lookup has no runtime contribution registry or provider variation. A small helper lets the later host own Cordis lifecycle and HMR without adding a service seam prematurely.
+**Introduce a Cordis repository service.** Rejected because cache lookup has no runtime contribution registry or provider variation. A small helper lets the later host own Cordis lifecycle and HMR without adding a service contract prematurely.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
index a4ad07c42e..6833eeb427 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-package-manager-native-repository-cache.zh.md
@@ -32,7 +32,7 @@ Loader 将 `pnpm@11.7.0` 作为固定版本的运行时依赖，并使用当前
 
 **禁用仓库生命周期脚本。** 不予采纳：常见插件仓库需要声明式 `prepare` 步骤来校验并打包插件子目录。信任边界是显式配置可执行来源，而不是营造一种不完整的假象，仿佛只有静态文件能够运行。
 
-**引入 Cordis 仓库服务。** 不予采纳：缓存查找没有运行时贡献注册表，也不存在提供方变体。小型 helper 让后续宿主负责 Cordis 生命周期与 HMR（热模块替换），无需过早新增服务 seam。
+**引入 Cordis 仓库服务。** 不予采纳：缓存查找没有运行时贡献注册表，也不存在提供方变体。小型 helper 让后续宿主负责 Cordis 生命周期与 HMR（热模块替换），无需过早新增服务约定。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
index b8dcd32d8e..14a0ad2bb0 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.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 .agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
-2026-07-30-settings-write-path-integrity.md: 7bd50adc8a812759c3ae3f80a50978d75baa712a
-2026-07-30-settings-write-path-integrity.zh.md: 155fb55b886ab41d11d947ee09194a367ac8a90f
+2026-07-30-settings-write-path-integrity.md: f9b56ca83ad3027083884442a051eca102207c24
+2026-07-30-settings-write-path-integrity.zh.md: 1e8ce7eddb6a639512cd792e98fc135f49a8c0be
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
index 7bd50adc8a..f9b56ca83a 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-30-settings-write-path-integrity.zh.md)
 
 ## Problem
 
-Review found the provider's write path could destroy state it never observed, and the seam's observer lifecycle leaked past disposal. Concretely: watcher reloads and document writes ran on two independent promise chains while every write rendered the whole next document from the cached text, so an external edit still inside the debounce window was overwritten — and the follow-up reload no-oped because the post-rename content matched the cache, erasing the edit without a trace. The initial `load()` raced the watcher's own setup, leaving a startup window whose changes never fire an event. Two processes sharing a harness home rendered from independent caches, last writer winning whole namespaces. On the seam side, a `watch()` disposer only removed the observer from its set — an invocation already chained onto the watcher tail still ran after disposal, and nothing drained started invocations at service dispose; the `settings/updated` manual fan-out caught only synchronous throws, so an async listener's rejection escaped as an unhandled rejection; and `structuredClone` admitted Dates, Maps, BigInts, and cycles that YAML/JSON storage silently distorts on the reload round-trip (a Date lands as a timestamp string, a BigInt as a plain number). YAML writes replaced the whole namespace node, deleting every comment inside the section a comment-preserving provider had promised to keep.
+Review found the provider's write path could destroy state it never observed, and the Service Definition's observer lifecycle leaked past disposal. Concretely: watcher reloads and document writes ran on two independent promise chains while every write rendered the whole next document from the cached text, so an external edit still inside the debounce window was overwritten — and the follow-up reload no-oped because the post-rename content matched the cache, erasing the edit without a trace. The initial `load()` raced the watcher's own setup, leaving a startup window whose changes never fire an event. Two processes sharing a harness home rendered from independent caches, last writer winning whole namespaces. On the Service Definition side, a `watch()` disposer only removed the observer from its set — an invocation already chained onto the watcher tail still ran after disposal, and nothing drained started invocations at service dispose; the `settings/updated` manual fan-out caught only synchronous throws, so an async listener's rejection escaped as an unhandled rejection; and `structuredClone` admitted Dates, Maps, BigInts, and cycles that YAML/JSON storage silently distorts on the reload round-trip (a Date lands as a timestamp string, a BigInt as a plain number). YAML writes replaced the whole namespace node, deleting every comment inside the section a comment-preserving provider had promised to keep.
 
 ## Decision
 
@@ -28,7 +28,7 @@ Review found the provider's write path could destroy state it never observed, an
 - **Revision/CAS instead of a lock** — rename cannot express compare-and-swap, so a CAS needs a version sidecar or content re-hash and a retry loop in every writer; the lock achieves the same serialization with one primitive and keeps readers free.
 - **Merging external edits into the in-flight write's own section** — the seam merges patches over the state visible at call time, so a same-namespace external edit racing a write still resolves last-write-wins; folding it in would need three-way merge semantics no consumer has asked for. The write publishes the external state first, so the loser is at least observed before being superseded.
 - **Declaring async `settings/updated` listeners unsupported** — the typed signature is `void` and lint flags misused promises, but an unlinted JS plugin can still register an async listener; a contract note cannot un-throw an unhandled rejection, so containment is the only defense that holds at runtime.
-- **Keeping `structuredClone` and validating in the provider** — the seam is the durable boundary's owner (every provider stores JSON-shaped documents), and rejecting at call time gives the caller the offending path; a provider-side check would reject after merge, blaming the merged section instead of the caller's value.
+- **Keeping `structuredClone` and validating in the provider** — the Service Definition is the durable boundary's owner (every provider stores JSON-shaped documents), and rejecting at call time gives the caller the offending path; a provider-side check would reject after merge, blaming the merged section instead of the caller's value.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
index 155fb55b88..1e8ce7eddb 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
@@ -8,9 +8,9 @@ Status: implemented
 
 ## 问题
 
-评审发现，提供方的写路径可能销毁它从未观察到的状态，而 seam 的观察者生命周期会泄漏到 dispose 之后。具体而言：watcher 重载与文档写入跑在两条相互独立的 promise 链上，而每次写入都从缓存文本渲染出完整的下一份文档，于是仍处于防抖窗口内的外部编辑会被覆盖——随后的重载又因 rename 后的内容与缓存一致而成为空操作，这次编辑就被无痕抹去。初始 `load()` 与 watcher 自身的建立过程存在竞态，留下一个启动窗口：落在这个窗口内的变更永远不会触发事件。共享同一 harness home 的两个进程各自从独立的缓存渲染，后写者以整个 namespace 为单位胜出。
+评审发现，提供方的写路径可能销毁它从未观察到的状态，而 Service Definition 的观察者生命周期会泄漏到 dispose 之后。具体而言：watcher 重载与文档写入跑在两条相互独立的 promise 链上，而每次写入都从缓存文本渲染出完整的下一份文档，于是仍处于防抖窗口内的外部编辑会被覆盖——随后的重载又因 rename 后的内容与缓存一致而成为空操作，这次编辑就被无痕抹去。初始 `load()` 与 watcher 自身的建立过程存在竞态，留下一个启动窗口：落在这个窗口内的变更永远不会触发事件。共享同一 harness home 的两个进程各自从独立的缓存渲染，后写者以整个 namespace 为单位胜出。
 
-在 seam 一侧，`watch()` 的释放器只把观察者从集合中移除——已经接到 watcher 链尾的调用在 dispose 之后照常运行，服务 dispose 时也没有任何环节排空已启动的调用；`settings/updated` 的手动扇出只捕获同步抛错，异步监听器的 rejection 会以 unhandled rejection 的形式逃逸；`structuredClone` 则放行 Date、Map、BigInt 与循环引用，而 YAML/JSON 存储会在重载往返中悄悄扭曲这些值（Date 会变成时间戳字符串，BigInt 会变成普通数字）。
+在 Service Definition 一侧，`watch()` 的释放器只把观察者从集合中移除——已经接到 watcher 链尾的调用在 dispose 之后照常运行，服务 dispose 时也没有任何环节排空已启动的调用；`settings/updated` 的手动扇出只捕获同步抛错，异步监听器的 rejection 会以 unhandled rejection 的形式逃逸；`structuredClone` 则放行 Date、Map、BigInt 与循环引用，而 YAML/JSON 存储会在重载往返中悄悄扭曲这些值（Date 会变成时间戳字符串，BigInt 会变成普通数字）。
 
 YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删掉——而这个保注释的提供方承诺过要保住它们。
 
@@ -32,7 +32,7 @@ YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删
 - **用修订号/CAS 取代锁**——rename 表达不了 compare-and-swap，因此 CAS 需要一个版本伴随文件或内容重哈希，外加每个写方里的一个重试循环；锁用一个原语实现同样的串行化，还让读方完全免锁。
 - **把外部编辑合并进正在进行的写入自身的分节**——seam 是在调用时刻可见的状态之上合并 patch 的，因此与写入竞态的同 namespace 外部编辑仍按后写胜出解决；要把外部编辑并进来，需要三方合并语义，而没有任何消费方提出过这种需求。写入会先发布外部状态，落败一方至少在被取代之前被观察到。
 - **宣布不支持异步 `settings/updated` 监听器**——类型签名是 `void`，lint 也会标记误用的 promise，但未经 lint 的 JS 插件仍能注册异步监听器；约定里的一句说明无法收回已经抛出的 unhandled rejection，收容是唯一在运行时守得住的防线。
-- **保留 `structuredClone`、在提供方里做校验**——seam 才是持久化边界的所有者（每个提供方存储的都是 JSON 形态文档），而且在调用时刻拒绝能把违规值的路径给到调用方；提供方侧的检查要到合并之后才拒绝，归咎的是合并后的分节，而不是调用方传入的值。
+- **保留 `structuredClone`、在提供方里做校验**——Service Definition 才是持久化边界的所有者（每个提供方存储的都是 JSON 形态文档），而且在调用时刻拒绝能把违规值的路径给到调用方；提供方侧的检查要到合并之后才拒绝，归咎的是合并后的分节，而不是调用方传入的值。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
index 6c9f7d8ce0..7fbaf3c2b9 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.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 .agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
-2026-07-30-web-config-plane.md: 483058c8a24ad8c414278eba84f4226e973f2923
-2026-07-30-web-config-plane.zh.md: 840ac7f2e46c82e7b858c353086e1a9541db563e
+2026-07-30-web-config-plane.md: 78fa9cf970dea30fdc842799134bc1d11608c800
+2026-07-30-web-config-plane.zh.md: b8a4347f95a741140a61e1d47f837aa0502d85ee
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
index 483058c8a2..78fa9cf970 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
@@ -22,7 +22,7 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer
 
 **A hand-written editor over a schema model layer.** `dsh-client-schema-form` rehydrates the wire's `toJSON()` envelope into live schemastery nodes for validation, path resolution, and immutable draft editing — but no generic rendering: the first cut shipped a full schema-driven form renderer, and the resulting page was an unstyled schema dump (every advanced field flattened onto the card, raw field names as labels, the `retryPolicy` unsupported-fallback in the main flow). The user chose the hand-written direction over adding a hint/grouping system, and a second round removed the reference input entirely: the card's primary field is one **API key** input, a whole-section provider without a configured key opens as its setup card, and the collapsed 自定义设置 fold carries the curated per-family extras (`baseURL` for both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, plus direct DeepSeek model rows with `id`, `name`, and `contextWindow`). Existing model fields outside that visible set survive array edits; retry policy, timeouts, and other fields remain owned by `settings.yaml`. Validation still runs the rehydrated schema before writing, while adapter-specific checks reject catalog invariants that the serialized schema cannot express. The card's colors resolve through the `--dsw-alias-*` design tokens; it had named `--border`/`--surface`/`--text-*`, which nothing in this app defines, so it rendered their light-mode fallbacks and stayed light under the dark theme. The model catalog takes the row shape the pi-ai provider form introduces: one bordered entry per model, id and display name on the row, and the capacities behind the row's own disclosure, so the two editors read as one design rather than diverging once both land. Every field keeps the indexed `aria-label` that names it. Both capacities are text fields reading a decimal `K`/`M` suffix (`1M` is 1000K, matching how capacities are quoted) and storing the plain count: a field holds the typed text while it has focus, because re-deriving it from the parsed count on every keystroke would rewrite `1000` to `1K` mid-word, and text that does not parse stays on screen so the save-time rejection names a row the user can still see. The shared class names carry this file's token spellings, not that branch's: `--dsw-alias-border-subtle`, `--dsw-alias-text-tertiary`, and `--dsw-alias-text-primary` are undeclared, so they resolve to the light-mode literals in their fallback slots — the defect this section was moved off. A styles test now rejects any `--dsw-*` name the token sheet does not declare, so the next editor to name one fails rather than shipping a light-only surface.
 
-**The Models page is a three-domain join with seam-shaped apply semantics.** Rows are configured providers; the add card's select is the dormant directory remainder. Route liveness still gates readiness and invalidates the join, but the page does not render it as provider status because configuration presence and runtime availability are distinct. The key path stays reference-shaped without ever showing a reference: a typed key stores **write-only** through `credentials.set` under the profile's `apiKeyEnv`, deriving `<ROUTE>_API_KEY` when none exists (the pi-ai profile records the derivation only when a key is entered), so `settings.yaml` never carries a key value; a blank pi-ai key materializes a reference-free profile and preserves provider-native authentication. Profile edits and removals land as minimal path-addressed `settings.mutate` operations against the redacted user section, which never names a secret the page did not receive. Removing a user-layer provider first opens a localized confirmation dialog whose row actions, title, description, and final action identify the same provider; confirmation removes an exact configured+writable derived credential before the profile, while custom, environment, and unidentified targets remain untouched. Both stages are idempotent and a partial failure stays in the dialog for retry. DeepSeek's model list is array-replace configuration: inherited effective rows remain visible until the first edit materializes the complete list in the user layer, and reset unsets the list override. The partial-commit and credential-ownership rationale lives in the [provider credential lifecycle note](../bug-fix/2026-08-06-provider-credential-lifecycle.md).
+**The Models page is a three-domain join with service-shaped apply semantics.** Rows are configured providers; the add card's select is the dormant directory remainder. Route liveness still gates readiness and invalidates the join, but the page does not render it as provider status because configuration presence and runtime availability are distinct. The key path stays reference-shaped without ever showing a reference: a typed key stores **write-only** through `credentials.set` under the profile's `apiKeyEnv`, deriving `<ROUTE>_API_KEY` when none exists (the pi-ai profile records the derivation only when a key is entered), so `settings.yaml` never carries a key value; a blank pi-ai key materializes a reference-free profile and preserves provider-native authentication. Profile edits and removals land as minimal path-addressed `settings.mutate` operations against the redacted user section, which never names a secret the page did not receive. Removing a user-layer provider first opens a localized confirmation dialog whose row actions, title, description, and final action identify the same provider; confirmation removes an exact configured+writable derived credential before the profile, while custom, environment, and unidentified targets remain untouched. Both stages are idempotent and a partial failure stays in the dialog for retry. DeepSeek's model list is array-replace configuration: inherited effective rows remain visible until the first edit materializes the complete list in the user layer, and reset unsets the list override. The partial-commit and credential-ownership rationale lives in the [provider credential lifecycle note](../bug-fix/2026-08-06-provider-credential-lifecycle.md).
 
 ## Alternatives considered
 
@@ -36,4 +36,4 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer
 
 ## Consequences
 
-The whole loop is pinned keyless in the browser lane (`apps/web/tests/models-settings.e2e.ts`): the add card offers the dormant pi-ai catalog, adding `minimax-cn` with a typed key writes the reference-only profile into `settings.yaml`, stores the value into the harness home's `.env` under the derived `MINIMAX_CN_API_KEY`, registers the route live on the topology frame, and the customized fold merges `reasoning` beside the reference — zero model calls, ARIA goldens for the add-card, configured, and identified delete-confirmation states, plus a scaffold `harnessHome` so tests never touch a real `~/.dsh` (the provider under test is one whose derived reference cannot collide with a developer's exported keys). The settings-shell scenario intercepts the pathless native intent; seam, provider, wire, React, and native-opener tests separately pin provider absence, custom-path resolution, absent-file materialization, owner-only permissions, hidden remote/unavailable states, duplicate-click collapse, localized failure, macOS text-editor dispatch, and Linux/Windows desktop dispatch. The removal scenario proves cancellation leaves both profile and key intact, then confirmation removes both the profile and its identified managed credential. The DeepSeek onboarding fixture edits the default catalog into a user-owned list, persists an arbitrary model id/name/context window, removes the active row, and observes the model selector's empty-selection fallback. The rename touched 239 files (fixtures, goldens, docs, python) in one commit with no compatibility alias. The renderer replacement cost one commit and no wire change: apply semantics, redaction, and the directory join were renderer-agnostic all along. Deferred: a per-row models preview (the picker already lists models) and a page address for live routes that never declared configurability.
+The whole loop is pinned keyless in the browser lane (`apps/web/tests/models-settings.e2e.ts`): the add card offers the dormant pi-ai catalog, adding `minimax-cn` with a typed key writes the reference-only profile into `settings.yaml`, stores the value into the harness home's `.env` under the derived `MINIMAX_CN_API_KEY`, registers the route live on the topology frame, and the customized fold merges `reasoning` beside the reference — zero model calls, ARIA goldens for the add-card, configured, and identified delete-confirmation states, plus a scaffold `harnessHome` so tests never touch a real `~/.dsh` (the provider under test is one whose derived reference cannot collide with a developer's exported keys). The settings-shell scenario intercepts the pathless native intent; Service Definition, provider, wire, React, and native-opener tests separately pin provider absence, custom-path resolution, absent-file materialization, owner-only permissions, hidden remote/unavailable states, duplicate-click collapse, localized failure, macOS text-editor dispatch, and Linux/Windows desktop dispatch. The removal scenario proves cancellation leaves both profile and key intact, then confirmation removes both the profile and its identified managed credential. The DeepSeek onboarding fixture edits the default catalog into a user-owned list, persists an arbitrary model id/name/context window, removes the active row, and observes the model selector's empty-selection fallback. The rename touched 239 files (fixtures, goldens, docs, python) in one commit with no compatibility alias. The renderer replacement cost one commit and no wire change: apply semantics, redaction, and the directory join were renderer-agnostic all along. Deferred: a per-row models preview (the picker already lists models) and a page address for live routes that never declared configurability.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
index 840ac7f2e4..b8a4347f95 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
@@ -22,7 +22,7 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 **架在 schema 模型层之上的手写编辑器。**`dsh-client-schema-form` 把 wire 的 `toJSON()` 信封还原（rehydrate）为活的 schemastery 节点，用于校验、路径解析与不可变草稿编辑——但不做通用渲染：第一版交付了完整的 schema 驱动表单渲染器，得到的却是一个未加样式、把 schema 原样倾倒出来的页面（每个进阶字段都平铺到卡片上、原始字段名直接充当标签、`retryPolicy` 的「不支持」回退落在主流程里）。用户没有再加一套提示／分组系统，而是选择了手写方向，第二轮又把引用输入框整个移除：卡片的主字段是一个 **API 密钥**输入框，未配置密钥的整分节提供方会以其设置卡片的形式打开，收起的「自定义设置」折叠区承载按家族精选的额外字段（两个家族都有 `baseURL`，deepseek 有 `reasoningEffort`／pi-ai 有 `reasoning`，另有直接 DeepSeek 模型行的 `id`、`name` 和 `contextWindow`）。现有模型字段中不在可见集合内的部分会在数组编辑后保留；重试策略、超时及其他字段仍归 `settings.yaml` 所有。校验仍会在写入前运行还原出的 schema，适配器特有的检查则会拒绝序列化 schema 无法表达的目录不变量。卡片的颜色经 `--dsw-alias-*` 设计 token 解析；它此前引用的 `--border`／`--surface`／`--text-*` 在本应用中无人定义，于是渲染出的是它们的亮色模式回退值，在暗色主题下依旧保持亮色。模型目录采用 pi-ai 提供方表单引入的行形态：每个模型一个带边框的条目，ID 与显示名称落在行上，容量则收在该行自己的折叠区里，使两个编辑器呈现为同一套设计，而不是在双方都落地后各自分岔。每个字段都保留那个为其命名的带序号 `aria-label`。两项容量都是文本输入框，读取十进制的 `K`／`M` 后缀（`1M` 即 1000K，与容量的通行标注方式一致）并存储纯数值：字段持有焦点期间保留键入的文本，因为若每次按键都从解析出的数值重新推导该文本，`1000` 会在尚未输完时就被改写成 `1K`；无法解析的文本也会留在屏幕上，因此保存时的拒绝点名的是用户仍能看见的那一行。共用的类名承载的是本文件的 token 写法，而非那个分支的：`--dsw-alias-border-subtle`、`--dsw-alias-text-tertiary` 和 `--dsw-alias-text-primary` 均未声明，于是它们解析为各自回退槽位中的亮色模式字面值——正是本节此前迁离的那个缺陷。现在有一个样式测试会拒绝 token 表未声明的任何 `--dsw-*` 名称，因此下一个写出这类名称的编辑者会当场失败，而不是交付一个只有亮色的界面。
 
-**Models 页是一次三领域联接，应用语义与 seam 同形。**每一行是一个已配置的提供方；「新增」卡片的选择框是可配置提供方目录中剩余的休眠条目。路由存活状态仍用于就绪判定，并会使该联接失效，但页面不将其渲染为提供方状态，因为配置存在与运行时可用性是两个不同概念。密钥通道保持引用形态，却从不展示任何引用：键入的密钥经 `credentials.set` **只写**存入 profile 的 `apiKeyEnv` 之下，引用不存在时便派生 `<ROUTE>_API_KEY`（仅在输入密钥时，pi-ai profile 才会记录该派生），因此 `settings.yaml` 从不携带密钥值；留空 pi-ai 密钥会具化一个不带引用的 profile，并保留提供方原生认证。profile 的编辑和删除会针对脱敏后的用户分节，以按路径寻址的最小 `settings.mutate` 操作落地，绝不会点名页面未收到的机密。删除用户层提供方时，会先打开本地化确认对话框，其行操作、标题、说明和最终操作都会点名同一个提供方；确认后会先清除与派生目标精确匹配且已配置、可写的凭据，再删除 profile，自定义目标、环境目标和无法识别的目标则保持不变。两个阶段都具备幂等性，部分失败会留在对话框中供重试。DeepSeek 的模型列表是数组替换配置：继承而来的生效模型行会一直显示，直到第一次编辑将完整列表具化到用户层；重置则会取消设置该列表覆盖。部分提交与凭据所有权的理由记录在[提供方凭据生命周期 note](../bug-fix/2026-08-06-provider-credential-lifecycle.md)中。
+**Models 页是一次三领域联接，应用语义与服务同形。**每一行是一个已配置的提供方；「新增」卡片的选择框是可配置提供方目录中剩余的休眠条目。路由存活状态仍用于就绪判定，并会使该联接失效，但页面不将其渲染为提供方状态，因为配置存在与运行时可用性是两个不同概念。密钥通道保持引用形态，却从不展示任何引用：键入的密钥经 `credentials.set` **只写**存入 profile 的 `apiKeyEnv` 之下，引用不存在时便派生 `<ROUTE>_API_KEY`（仅在输入密钥时，pi-ai profile 才会记录该派生），因此 `settings.yaml` 从不携带密钥值；留空 pi-ai 密钥会具化一个不带引用的 profile，并保留提供方原生认证。profile 的编辑和删除会针对脱敏后的用户分节，以按路径寻址的最小 `settings.mutate` 操作落地，绝不会点名页面未收到的机密。删除用户层提供方时，会先打开本地化确认对话框，其行操作、标题、说明和最终操作都会点名同一个提供方；确认后会先清除与派生目标精确匹配且已配置、可写的凭据，再删除 profile，自定义目标、环境目标和无法识别的目标则保持不变。两个阶段都具备幂等性，部分失败会留在对话框中供重试。DeepSeek 的模型列表是数组替换配置：继承而来的生效模型行会一直显示，直到第一次编辑将完整列表具化到用户层；重置则会取消设置该列表覆盖。部分提交与凭据所有权的理由记录在[提供方凭据生命周期 note](../bug-fix/2026-08-06-provider-credential-lifecycle.md)中。
 
 ## 曾考虑的替代方案
 
@@ -36,4 +36,4 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 ## 后果
 
-整条闭环以无密钥方式固定在浏览器测试通道（`apps/web/tests/models-settings.e2e.ts`）：「新增」卡片提供休眠的 pi-ai catalog，携键入的密钥添加 `minimax-cn` 会把只含引用的 profile 写入 `settings.yaml`、把密钥值存入 harness 家目录 `.env` 中派生的 `MINIMAX_CN_API_KEY` 之下、路由随拓扑帧注册为存活，「自定义设置」折叠区则把 `reasoning` 合并到引用旁边——全程零模型调用，「新增」卡片态、已配置态与已点名目标的删除确认态各有 ARIA golden，另有脚手架式的 `harnessHome`，测试绝不触碰真实的 `~/.dsh`（受测提供方是派生引用不可能与开发者已导出密钥相撞的那一个）。设置外壳场景会截获无路径参数的原生意图；seam、提供方、wire、React 与原生打开器测试分别固定了提供方缺失、自定义路径解析、缺失文件创建、仅属主权限、远程／不可用时隐藏、重复点击合并、本地化失败、macOS 文本编辑器分发，以及 Linux/Windows 桌面分发。删除场景证明，取消会保留 profile 和密钥，随后的确认会同时删除 profile 及其已识别的受管凭据。DeepSeek 首次使用 fixture 会把默认目录编辑为用户自有列表、持久化任意模型的 ID／名称／上下文窗口、移除活动模型行，并观察模型选择器的空选择回退。这次重命名在一次提交中触及 239 个文件（fixture（测试前置数据）、golden、文档、python），未保留兼容别名。替换渲染器只花了一次提交，且没有任何 wire 变更：应用语义、脱敏与目录联接从一开始就与渲染器无关。延后事项：每行的模型预览（选择器已能列出模型）和为从未声明可配置性的存活路由提供页面地址。
+整条闭环以无密钥方式固定在浏览器测试通道（`apps/web/tests/models-settings.e2e.ts`）：「新增」卡片提供休眠的 pi-ai catalog，携键入的密钥添加 `minimax-cn` 会把只含引用的 profile 写入 `settings.yaml`、把密钥值存入 harness 家目录 `.env` 中派生的 `MINIMAX_CN_API_KEY` 之下、路由随拓扑帧注册为存活，「自定义设置」折叠区则把 `reasoning` 合并到引用旁边——全程零模型调用，「新增」卡片态、已配置态与已点名目标的删除确认态各有 ARIA golden，另有脚手架式的 `harnessHome`，测试绝不触碰真实的 `~/.dsh`（受测提供方是派生引用不可能与开发者已导出密钥相撞的那一个）。设置外壳场景会截获无路径参数的原生意图；Service Definition、提供方、wire、React 与原生打开器测试分别固定了提供方缺失、自定义路径解析、缺失文件创建、仅属主权限、远程／不可用时隐藏、重复点击合并、本地化失败、macOS 文本编辑器分发，以及 Linux/Windows 桌面分发。删除场景证明，取消会保留 profile 和密钥，随后的确认会同时删除 profile 及其已识别的受管凭据。DeepSeek 首次使用 fixture 会把默认目录编辑为用户自有列表、持久化任意模型的 ID／名称／上下文窗口、移除活动模型行，并观察模型选择器的空选择回退。这次重命名在一次提交中触及 239 个文件（fixture（测试前置数据）、golden、文档、python），未保留兼容别名。替换渲染器只花了一次提交，且没有任何 wire 变更：应用语义、脱敏与目录联接从一开始就与渲染器无关。延后事项：每行的模型预览（选择器已能列出模型）和为从未声明可配置性的存活路由提供页面地址。
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
index a6be2d99e5..927f3d1c6d 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.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 .agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
-2026-07-31-claimed-pre-step-inbox-lifecycle.md: 5184c00335b3084a8eb6d58fa33a0af8d3a16ed6
-2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 4718b1b519051f0ae82b4c7f9d0599f45a800f1d
+2026-07-31-claimed-pre-step-inbox-lifecycle.md: 037b17fa823a28d1ded6f599c62374432d546c22
+2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: b77a2e052b57151ee897555ed88d6632820e0ebf
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
index 5184c00335..037b17fa82 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
@@ -14,7 +14,7 @@ Occurrence-local inbox wrappers also duplicated the identity already carried by
 
 Before every proposed step, `Inbox.claim(target)` atomically removes the complete batch: all `next-step` messages and, at a turn boundary, one `next-turn` message. At the initial boundary the loop first commits `turn/start`, so the claim and its single `agent/pre-step` decision have durable turn ownership. Claiming records normalized `agent/inbox/spliced` pure deletions with no outcome. The loop then emits `agent/inbox/claimed { message, turn }` once per claimed message and awaits the waterfall with that exclusive batch and `{ turn, step, signal }`.
 
-`PreStepDecision` is `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`. Reject opens no step, leaves the claimed batch removed, and closes the turn as blocked without any step events. Empty entry, cancellation, and failure before `step/start` likewise close a balanced no-step turn. Enter supplies the complete batch appended as `user/message` events after `step/start`. A listener wrapping `next()` preserves downstream changes unless it intentionally replaces them, so all message rewrites settle once in the final return value. There is no `agent/prompt-prepare`, `agent/prompt-submit`, or `agent/step` seam.
+`PreStepDecision` is `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`. Reject opens no step, leaves the claimed batch removed, and closes the turn as blocked without any step events. Empty entry, cancellation, and failure before `step/start` likewise close a balanced no-step turn. Enter supplies the complete batch appended as `user/message` events after `step/start`. A listener wrapping `next()` preserves downstream changes unless it intentionally replaces them, so all message rewrites settle once in the final return value. There is no `agent/prompt-prepare`, `agent/prompt-submit`, or `agent/step` extension point.
 
 The durable inbox remains two `UserMessage[]` lists addressed by `MessageId`. `append`, `prepend`, and `splice` take a target, while `replace(messageId, newMessage)` and `remove(messageId)` locate the pending message across both lists before committing a normalized splice. Replacement may change identity and emits the old message as discarded followed by the new message as inserted. Every insertion emits `agent/inbox/inserted { message }`; an ordinary removal records `outcome: 'canceled'` and emits `agent/inbox/discarded { message }`. Claiming is the loop's internal step-boundary operation on the inbox and records pure deletions without notifications or an outcome, so the loop can publish claimed events itself. These live events add no placement, outcome, or batch fields.
 
@@ -34,7 +34,7 @@ The archived [addressable queue occurrence decision](../../archived/feature/2026
 
 ## Verification
 
-Agent-loop coverage pins turn-start-before-claim-before-pre-step ordering, exact live event payloads, balanced no-step rejection, final-batch rewriting, input inserted after a claim, listener failure, and cancellation. Inbox and consumer tests pin pure claim deletions, canceled ordinary removals, workspace-context staging, replacement, and same-step entry, plan/goal/hook behavior, UI cleanup, compaction, checkpointing, and resumed durable projection. Generated event and type catalogs expose only the new seam and payloads.
+Agent-loop coverage pins turn-start-before-claim-before-pre-step ordering, exact live event payloads, balanced no-step rejection, final-batch rewriting, input inserted after a claim, listener failure, and cancellation. Inbox and consumer tests pin pure claim deletions, canceled ordinary removals, workspace-context staging, replacement, and same-step entry, plan/goal/hook behavior, UI cleanup, compaction, checkpointing, and resumed durable projection. Generated event and type catalogs expose only the new waterfall and payloads.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
index 4718b1b519..b77a2e052b 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 每个拟议步骤之前，`Inbox.claim(target)` 会原子移除完整批次：全部 `next-step` 消息，以及轮次边界上的一条 `next-turn` 消息。在首次边界，循环会先提交 `turn/start`，使领取及其唯一一次 `agent/pre-step` 决策拥有持久轮次归属。领取会记录规范化、不带 outcome 的纯删除 `agent/inbox/spliced`。随后，循环针对每条已领取消息发出一次 `agent/inbox/claimed { message, turn }`，并用该独占批次与 `{ turn, step, signal }` 等待 waterfall（瀑布式事件）。
 
-`PreStepDecision` 为 `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`。reject 不会打开步骤，会让已领取批次保持已删除，并将轮次关闭为 blocked，且不产生任何步骤事件。空的 enter、取消以及 `step/start` 前的失败同样会关闭一个边界平衡的无步骤轮次。enter 提供在 `step/start` 后以 `user/message` 追加的完整批次。包装 `next()` 的监听器会保留下游变更，除非有意替换，因此全部消息改写只在最终返回值中一次性结算。系统不再存在 `agent/prompt-prepare`、`agent/prompt-submit` 或 `agent/step` seam。
+`PreStepDecision` 为 `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`。reject 不会打开步骤，会让已领取批次保持已删除，并将轮次关闭为 blocked，且不产生任何步骤事件。空的 enter、取消以及 `step/start` 前的失败同样会关闭一个边界平衡的无步骤轮次。enter 提供在 `step/start` 后以 `user/message` 追加的完整批次。包装 `next()` 的监听器会保留下游变更，除非有意替换，因此全部消息改写只在最终返回值中一次性结算。系统不再存在 `agent/prompt-prepare`、`agent/prompt-submit` 或 `agent/step` 扩展点。
 
 持久 inbox 仍是两份通过 `MessageId` 寻址的 `UserMessage[]` 列表。`append`、`prepend` 与 `splice` 接受 target；`replace(messageId, newMessage)` 与 `remove(messageId)` 则在提交规范化 splice 前，通过 `MessageId` 跨两份列表定位待处理消息。替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。每次插入发出 `agent/inbox/inserted { message }`；普通删除记录 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`。领取是循环在 inbox 上的内部步骤边界操作，记录不带通知或 outcome 的纯删除，因此循环可以自行发布 claimed 事件。这些实时事件不增加 placement、outcome 或批次字段。
 
@@ -34,7 +34,7 @@ Status: implemented
 
 ## 验证
 
-Agent-loop 覆盖固定先 `turn/start`、再领取、后 pre-step 的顺序、实时事件的确切载荷、边界平衡的无步骤 reject、最终批次改写、领取后插入的输入、监听器失败与取消。Inbox 和消费方测试固定纯领取删除、普通删除的 canceled 结果、workspace-context 的暂存、替换与同一步骤进入、plan/goal/hook 行为、UI 清理、压缩、检查点以及恢复后的持久投影。生成的事件与类型目录只公开新的 seam 与载荷。
+Agent-loop 覆盖固定先 `turn/start`、再领取、后 pre-step 的顺序、实时事件的确切载荷、边界平衡的无步骤 reject、最终批次改写、领取后插入的输入、监听器失败与取消。Inbox 和消费方测试固定纯领取删除、普通删除的 canceled 结果、workspace-context 的暂存、替换与同一步骤进入、plan/goal/hook 行为、UI 清理、压缩、检查点以及恢复后的持久投影。生成的事件与类型目录只公开新的 waterfall 与载荷。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
index 58470f9780..37ab3eda38 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.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 .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
-2026-07-31-code-runtime-portable-identifier-seam.md: 9e9df50235b3505458e3645e2c6ff6e9bd439183
-2026-07-31-code-runtime-portable-identifier-seam.zh.md: 215024467f6f76a79a1f48f33e9d3c5b216df08d
+2026-07-31-code-runtime-portable-identifier-seam.md: ba2aa8eeabb823978fca32a59d98d56971784a92
+2026-07-31-code-runtime-portable-identifier-seam.zh.md: 689ffa1b1ffcb5be1e2aa2bd9cd49c2ae40ba7ee
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
index 9e9df50235..ba2aa8eeab 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
@@ -8,24 +8,24 @@ English | [中文](2026-07-31-code-runtime-portable-identifier-seam.zh.md)
 
 The code-runtime seam promises that a binding-namespace list valid on one backend is valid on every backend, so a Code Mode consumer can hand the same bindings to any registered runtime without knowing its language. The first backend, `dsh-code-runtime-worker`, privately owned the identifier rules that enforce part of that promise: an `IDENTIFIER` regex that allowed the JS-only `$`, a `RESERVED_WORDS` set holding only ECMAScript keywords, and a `RESERVED_ERROR_PROPERTIES` set of three JS `Error` slots. Those rules described the worker's own language, not the seam's portability contract.
 
-A second backend written against a different language (CPython, arriving in a later PR of this stack) would either re-declare its own rules — letting `lambda` pass the worker and fail Python, or `$tools` pass the worker and fail every non-JS backend — or import the worker's, inverting the dependency so the seam's implementation reached into a sibling implementation. Neither keeps the portability promise real: it would hold only for the backend a caller happened to test against.
+A second backend written against a different language (CPython, arriving in a later PR of this stack) would either re-declare its own rules — letting `lambda` pass the worker and fail Python, or `$tools` pass the worker and fail every non-JS backend — or import the worker's, inverting the dependency so a Service provider reached into a sibling Service provider. Neither keeps the portability promise real: it would hold only for the backend a caller happened to test against.
 
 ## Decision
 
-The seam package (`@deepseek-ai/dsh-code-runtime`) exports the portable-identifier exclusion contract as four named constants, and every backend imports them rather than re-declaring:
+The Service Definition package (`@deepseek-ai/dsh-code-runtime`) exports the portable-identifier exclusion contract as four named constants, and every Service provider imports them rather than re-declaring:
 
 - `PORTABLE_RESERVED_WORDS` — the union of ECMAScript and Python reserved words. A namespace global or error-class name matching any is refused on all backends, so `lambda` is refused even though it is a legal JS parameter name. Adding a language widens this union, which is a deliberate breaking review of existing binding names.
 - `RESERVED_BINDING_GLOBALS` — globals some backend owns in the program's namespace: `console` (the worker's log capture), `__dsh_main__`/`__builtins__`/`__name__` (the Python bootstrap's wrapper and seeded module globals), and `__debug__` (not a seeded slot but a CPython compile-time constant that rejects assignment, so an injected global under that name is unreachable — the same portability split by a different mechanism). Refused everywhere so a namespace list cannot pick a name that works on one backend and collides on another.
 - `RESERVED_ERROR_MEMBERS` — error-member names every backend refuses: the JS `Error` slots (`name`, `message`, `stack`) and Python's exception-protocol members (`args`, `with_traceback`, `add_note`).
 - `DUNDER_MEMBER` — the dunder-form regex (`__x__`, non-empty middle), refused as an error member wholesale because several are constrained CPython descriptors whose exact set is an interpreter-version detail.
 
-The seam also narrows the portable identifier subset to `[A-Za-z_][A-Za-z0-9_]*` (documented on `CodeBindingNamespace.global` and `CodeBindingErrorClass`), dropping the JS-only `$`. The worker consumes the shared constants directly by their seam names — `PORTABLE_RESERVED_WORDS` for both binding-global and error-class names, `RESERVED_BINDING_GLOBALS` for backend-owned slots, `RESERVED_ERROR_MEMBERS` plus `DUNDER_MEMBER` for error members — with no local re-alias; its `IDENTIFIER` regex loses `$`.
+The Service Definition also narrows the portable identifier subset to `[A-Za-z_][A-Za-z0-9_]*` (documented on `CodeBindingNamespace.global` and `CodeBindingErrorClass`), dropping the JS-only `$`. The worker consumes the shared constants directly under their exported names — `PORTABLE_RESERVED_WORDS` for both binding-global and error-class names, `RESERVED_BINDING_GLOBALS` for backend-owned slots, `RESERVED_ERROR_MEMBERS` plus `DUNDER_MEMBER` for error members — with no local re-alias; its `IDENTIFIER` regex loses `$`.
 
-The constants live at the seam even though only one backend ships in this PR: the whole point is that the contract is language-agnostic and owned above any single language. A backend that violated it would be the bug, and the shared set is where a reviewer looks to see what "portable" means.
+The constants live in the Service Definition even though only one backend ships in this PR: the whole point is that the contract is language-agnostic and owned above any single language. A Service provider that violated it would be the bug, and the shared set is where a reviewer looks to see what "portable" means.
 
 ## Scope
 
-This PR delivers only the seam extension and the worker's adoption of it. No Python backend, `py-types` renderer, or Code Mode language dispatch ships here — they are later PRs in the stack that depend on these exports. The seam README's worker-only wording is left unchanged for the same reason: linking to a `dsh-code-runtime-python` README that does not yet exist would break the dead-link gate.
+This PR delivers only the Service Definition extension and the worker's adoption of it. No Python backend, `py-types` renderer, or Code Mode language dispatch ships here — they are later PRs in the stack that depend on these exports. The Service Definition README's worker-only wording is left unchanged for the same reason: linking to a `dsh-code-runtime-python` README that does not yet exist would break the dead-link gate.
 
 `RESERVED_BINDING_GLOBALS` currently encodes the not-yet-merged Python bootstrap's concrete design: it seeds exactly `__builtins__`/`__name__` and wraps the program under `__dsh_main__`. The Python-backend PR that seeds any additional module global (`__doc__`, `__loader__`, `__spec__`, `__file__`, `__package__`, …) MUST widen this set in the same change, exactly as adding a language widens `PORTABLE_RESERVED_WORDS` — a name the bootstrap seeds but the set omits is the portability split this contract exists to prevent.
 
@@ -33,12 +33,12 @@ This PR delivers only the seam extension and the worker's adoption of it. No Pyt
 
 **Each backend declares its own exclusions.** Rejected: it makes the portability promise per-backend. A binding list the caller tested on the worker could be refused by Python, which is exactly the split the seam exists to prevent.
 
-**The Python backend imports the worker's constants.** Rejected: it inverts the dependency — the seam's implementations would reach into a sibling implementation for a contract neither owns. The contract belongs above both, at the seam.
+**The Python backend imports the worker's constants.** Rejected: it inverts the dependency — the seam's Service providers would reach into a sibling implementation for a contract neither owns. The contract belongs above both, at the seam.
 
 **Keep `$` in the portable identifier subset.** Rejected: `$` is JS-only spelling. Allowing it would let `$tools` pass the worker and fail every non-JS backend, breaking portability for a purely cosmetic gain.
 
 ## Consequences
 
-Bought: one place — the seam package — defines what a portable binding name is, and every backend enforces the same contract by import. A namespace list valid on one backend is valid on all, verifiably, not by coincidence of which backend the caller tested.
+Bought: one place — the Service Definition package — defines what a portable binding name is, and every backend enforces the same contract by import. A namespace list valid on one backend is valid on all, verifiably, not by coincidence of which backend the caller tested.
 
-Cost: existing worker callers using a `$`-containing global now fail identifier validation. Under the pre-release stance this is a corrected foundation, not a compatibility break to shim. The worker's seam-misuse tests gain cases for `$tools`, Python exception members (`args`), dunders (`__dict__`), and a Python-owned global (`__dsh_main__`), proving the shared set is enforced from the worker side.
+Cost: existing worker callers using a `$`-containing global now fail identifier validation. Under the pre-release stance this is a corrected foundation, not a compatibility break to shim. The worker's Service Definition misuse tests gain cases for `$tools`, Python exception members (`args`), dunders (`__dict__`), and a Python-owned global (`__dsh_main__`), proving the shared set is enforced from the worker side.
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
index 215024467f..689ffa1b1f 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
@@ -8,24 +8,24 @@ Status: implemented
 
 code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性约定。
 
-一个针对不同语言（CPython，将在本 stack 后续 PR 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使 seam 的一个实现伸手进入另一个兄弟实现。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
+一个针对不同语言（CPython，将在本 stack 后续 PR 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使一个 Service provider 伸手进入另一个兄弟 Service provider。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
 
 ## Decision
 
-seam 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除约定，每个后端导入它们而非重新声明：
+Service Definition 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量导出可移植标识符排除约定，每个 Service provider 导入它们而非重新声明：
 
 - `PORTABLE_RESERVED_WORDS`——ECMAScript 与 Python 保留字的联集。任何命名空间 global 或 error-class 名称匹配其中之一，都在所有后端上被拒绝，因此 `lambda` 即便是合法的 JS 参数名也被拒绝。新增一门语言即扩宽此联集，这是对现有绑定名称的一次有意的破坏性复审。
 - `RESERVED_BINDING_GLOBALS`——某个后端在程序命名空间中拥有的 global：`console`（worker 的日志捕获）、`__dsh_main__`/`__builtins__`/`__name__`（Python bootstrap 的包装器与预置模块 global），以及 `__debug__`（不是 seed 的槽位，而是 CPython 编译期常量，赋值会被拒，故以该名注入的 global 不可达——同一种可移植性分裂，只是机制不同）。在所有后端上被拒绝，使命名空间列表无法选到一个在某后端能用、在另一后端冲突的名称。
 - `RESERVED_ERROR_MEMBERS`——每个后端都拒绝的 error-member 名称：JS `Error` 槽位（`name`、`message`、`stack`）与 Python 异常协议成员（`args`、`with_traceback`、`add_note`）。
 - `DUNDER_MEMBER`——dunder 形式正则（`__x__`，非空中缀），作为 error member 被整体拒绝，因为其中若干是受约束的 CPython 描述符，其确切集合是解释器版本细节。
 
-seam 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记录在 `CodeBindingNamespace.global` 与 `CodeBindingErrorClass` 上），去掉 JS 专有的 `$`。worker 直接以 seam 名消费这些共享常量——binding-global 与 error-class 名称用 `PORTABLE_RESERVED_WORDS`、后端拥有槽位用 `RESERVED_BINDING_GLOBALS`、error member 用 `RESERVED_ERROR_MEMBERS` 加 `DUNDER_MEMBER`——不再本地起别名；其 `IDENTIFIER` 正则去掉 `$`。
+Service Definition 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记录在 `CodeBindingNamespace.global` 与 `CodeBindingErrorClass` 上），去掉 JS 专有的 `$`。worker 直接以这些常量的导出名称消费它们——binding-global 与 error-class 名称用 `PORTABLE_RESERVED_WORDS`、后端拥有槽位用 `RESERVED_BINDING_GLOBALS`、error member 用 `RESERVED_ERROR_MEMBERS` 加 `DUNDER_MEMBER`——不再本地起别名；其 `IDENTIFIER` 正则去掉 `$`。
 
-尽管本 PR 只交付一个后端，这些常量仍置于 seam：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的后端才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
+尽管本 PR 只交付一个后端，这些常量仍置于 Service Definition：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的 Service provider 才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
 
 ## Scope
 
-本 PR 只交付 seam 扩展与 worker 对它的采用。这里不交付任何 Python 后端、`py-types` 渲染器或 Code Mode 的语言分发——它们是本 stack 中依赖这些导出的后续 PR。seam README 中仅描述 worker 的措辞保持不变，理由相同：链接到一个尚不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
+本 PR 只交付 Service Definition 扩展与 worker 对它的采用。这里不交付任何 Python 后端、`py-types` 渲染器或 Code Mode 的语言分发——它们是本 stack 中依赖这些导出的后续 PR。Service Definition README 中仅描述 worker 的措辞保持不变，理由相同：链接到一个尚不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
 
 `RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本约定要防止的可移植性分裂。
 
@@ -33,12 +33,12 @@ seam 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记
 
 **每个后端声明自己的排除集。** 拒绝：这让可移植承诺变成逐后端成立。调用方在 worker 上测过的绑定列表可能被 Python 拒绝，而这正是 seam 存在要防止的分裂。
 
-**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的实现会为一个二者都不拥有的约定伸手进入兄弟实现。约定属于二者之上，即 seam。
+**Python 后端导入 worker 的常量。** 拒绝：这反转依赖——seam 的 Service provider 会为一个二者都不拥有的约定伸手进入兄弟实现。约定属于二者之上，即 seam。
 
 **在可移植标识符子集中保留 `$`。** 拒绝：`$` 是 JS 专有拼写。允许它会让 `$tools` 通过 worker 却在每个非 JS 后端上失败，为纯粹表面的好处破坏可移植性。
 
 ## Consequences
 
-获得：一个地方——seam 包——定义什么是可移植绑定名称，每个后端通过导入执行同一约定。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
+获得：一个地方——Service Definition 包——定义什么是可移植绑定名称，每个后端通过导入执行同一约定。在一个后端上有效的命名空间列表在所有后端上都有效，这是可验证的，而非取决于调用方测试了哪个后端的巧合。
 
-代价：现有使用含 `$` global 的 worker 调用方现在会在标识符校验时失败。在预发布立场下这是一次被纠正的地基，而非需要 shim 的兼容性破坏。worker 的 seam-misuse 测试新增了 `$tools`、Python 异常成员（`args`）、dunder（`__dict__`）与一个 Python 拥有的 global（`__dsh_main__`）等用例，从 worker 侧证明共享集合被执行。
+代价：现有使用含 `$` global 的 worker 调用方现在会在标识符校验时失败。在预发布立场下这是一次被纠正的地基，而非需要 shim 的兼容性破坏。worker 的 Service Definition misuse 测试新增了 `$tools`、Python 异常成员（`args`）、dunder（`__dict__`）与一个 Python 拥有的 global（`__dsh_main__`）等用例，从 worker 侧证明共享集合被执行。
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
index b8f2e4d7d7..86a7237e7e 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.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 .agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
-2026-08-01-packaged-ripgrep-search.md: 7c515618a18b61bd90177a6fdf19bbd52e564209
-2026-08-01-packaged-ripgrep-search.zh.md: d06841b220603d832048d1c76784f0e1d283679c
+2026-08-01-packaged-ripgrep-search.md: 0320e9db1e1bead7d36ba66aa42ad5da345cdcbf
+2026-08-01-packaged-ripgrep-search.zh.md: 40471048ece89b0cd56aad7211097003a40ac3df
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
index 7c515618a1..0320e9db1e 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.md
@@ -22,7 +22,7 @@ The `fs-glob-sampling` ACP snapshot scenario now executes the real packaged bina
 
 **Keep the bash seam and probe, but document `rg` as a required host dependency.** Rejected: the host dependency is exactly the failure this change removes, and Windows support for the discovery tools was the point of the exercise; a documented requirement is still a requirement.
 
-**Make `rgPath` injectable (a config field or env override) so tests and snapshots keep substituting a stand-in binary.** Rejected: it adds a public deployment surface whose only consumer would be test seams, and the real binary is deterministic enough to pin directly through fixture mtimes — the packaged binary is the deployment, so tests should exercise it.
+**Make `rgPath` injectable (a config field or env override) so tests and snapshots keep substituting a stand-in binary.** Rejected: it adds a public deployment surface whose only consumer would be test hooks, and the real binary is deterministic enough to pin directly through fixture mtimes — the packaged binary is the deployment, so tests should exercise it.
 
 **Switch to a pure-JS glob/search engine (e.g. `picomatch`/`tinyglobby`).** Rejected: the [dependency-swaps audit](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) already rejected that on the "no glob engine exists" evidence; ripgrep semantics (`--sort=modified`, VCS pruning, JSON transport, regex dialect) are the tool contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
index d06841b220..40471048ec 100644
--- a/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 **保留 bash seam 与探针，仅把 `rg` 记为必需宿主依赖。** 否决：宿主依赖正是本次改动要消除的失败模式，而让发现工具支持 Windows 正是此举的目的；写进文档的依赖仍是依赖。
 
-**让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试 seam 会消费的公开部署面，而真实二进制本身足够确定——通过 fixture mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
+**让 `rgPath` 可注入（配置字段或环境变量覆盖），让测试与快照继续替换替身二进制。** 否决：这会新增一个只有测试钩子会消费的公开部署面，而真实二进制本身足够确定——通过 fixture mtime 即可直接钉住；打包二进制就是部署形态，测试应当拿它来测。
 
 **改用纯 JS 的 glob/搜索引擎（如 `picomatch`/`tinyglobby`）。** 否决：[依赖替换审计](../../rejected/simplification/2026-07-26-dependency-swaps-rejected-by-nih-audit.md) 已基于"不存在 glob 引擎"的证据否决过该方向；ripgrep 语义（`--sort=modified`、VCS 剪枝、JSON 传输、正则方言）就是工具约定。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
index fb4922d5c5..0b7c4c42a8 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.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 .agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
-2026-08-03-pi-ai-declared-provider-catalog.md: f908eb6293b77680193fcd8f7be7a9089477855a
-2026-08-03-pi-ai-declared-provider-catalog.zh.md: 9ed1abc5cedbba637466531f7fc48f73c1e18a0d
+2026-08-03-pi-ai-declared-provider-catalog.md: f4b5a8565dbeb836c7aa4edb9c565f649de20f0a
+2026-08-03-pi-ai-declared-provider-catalog.zh.md: 61e2053efe4dd1234bcd319eb989d946639d2e86
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
index f908eb6293..f4b5a8565d 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
@@ -35,7 +35,7 @@ The configurable-provider directory is now the installed catalog **joined with**
 
 pi-ai reports a model with no reasoning metadata as supporting the single level `off`, and the adapter used to pass that straight through. It reaches the seam as a one-item effort list, which every surface renders as a picker holding one selectable control — and that control is a lie: `off` becomes an *omitted* reasoning option at dispatch, byte-for-byte the request that naming no effort already produces. A provider whose own default is to think keeps thinking while the surface shows `off` selected.
 
-`reasoningInfo` therefore omits the seam's `reasoning` field whenever `model.reasoning` is falsy. The condition is the model's own metadata, not where the model came from, so this covers every hand-declared model whose entry declares no `reasoningEfforts` ([[2026-08-08-pi-ai-per-model-reasoning-declarations]] made declared efforts carry that metadata) **and** the 251 installed-catalog models pi-ai marks as non-reasoning. Those previously offered the lone `off`; they now offer nothing, and the surface shows the provider default alone. Models that do carry reasoning metadata are untouched — their level list still crosses the seam unfiltered, `off` included, because there it selects between real alternatives.
+`reasoningInfo` therefore omits the Service Definition's `reasoning` field whenever `model.reasoning` is falsy. The condition is the model's own metadata, not where the model came from, so this covers every hand-declared model whose entry declares no `reasoningEfforts` ([[2026-08-08-pi-ai-per-model-reasoning-declarations]] made declared efforts carry that metadata) **and** the 251 installed-catalog models pi-ai marks as non-reasoning. Those previously offered the lone `off`; they now offer nothing, and the surface shows the provider default alone. Models that do carry reasoning metadata are untouched — their level list still crosses the seam unfiltered, `off` included, because there it selects between real alternatives.
 
 ### Credentials stay outside pi-ai
 
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
index 9ed1abc5ce..61e2053efe 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
@@ -35,7 +35,7 @@ Status: implemented
 
 pi-ai 把没有推理元数据的模型报告为只支持 `off` 一档，而适配器此前原样透传。它抵达 seam 时是一个单元素的 effort 列表，任何界面都会把它渲染成一个只有一项可选控件的选择器——而这个控件在撒谎：`off` 在派发时变成被*省略*的 reasoning 选项，与「不点名任何档位」产出的请求逐字节相同。自身默认就在思考的提供方会继续思考，界面却显示 `off` 已选中。
 
-因此只要 `model.reasoning` 为假，`reasoningInfo` 就省略 seam 的 `reasoning` 字段。判据是模型自身的元数据，而非模型的来源，所以它覆盖条目未声明 `reasoningEfforts` 的每一个手工声明模型（[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 让声明的档位携带这份元数据）**以及** pi-ai 标记为不具备推理能力的那 251 个已安装 catalog 模型。它们此前提供那个孤零零的 `off`，现在什么也不提供，界面只剩提供方默认。携带推理元数据的模型不受影响——其档位列表仍不经筛选地穿过 seam、`off` 也在内，因为在那里它是在真实备选之间做选择。
+因此只要 `model.reasoning` 为假，`reasoningInfo` 就省略 Service Definition 的 `reasoning` 字段。判据是模型自身的元数据，而非模型的来源，所以它覆盖条目未声明 `reasoningEfforts` 的每一个手工声明模型（[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 让声明的档位携带这份元数据）**以及** pi-ai 标记为不具备推理能力的那 251 个已安装 catalog 模型。它们此前提供那个孤零零的 `off`，现在什么也不提供，界面只剩提供方默认。携带推理元数据的模型不受影响——其档位列表仍不经筛选地穿过 seam、`off` 也在内，因为在那里它是在真实备选之间做选择。
 
 ### 凭据留在 pi-ai 之外
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 6e2e6e1453..989393cfc3 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: ef30a22c120af1437f348e52843e1dd45c9837ae
-2026-08-04-configuration-source-ownership.zh.md: ef352ce4c7b8eef8fc2dcd3aa7154bda770ffd4e
+2026-08-04-configuration-source-ownership.md: dc24fd4eb57294b73c3d2f8935418182726b35c2
+2026-08-04-configuration-source-ownership.zh.md: 20a8aebb626cf2282b7ddf27540be2c05eaae946
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index ef30a22c12..dc24fd4eb5 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -56,7 +56,7 @@ The line is that these take effect with no user action, before any turn, outside
 - A `.env` holding `DSH_*`, `PATH`, or a proxy variable fails the launch instead of being applied. Developers keeping switches in a repository `.env` move them to their shell — a deliberate, loud break.
 - Composition is no longer overridable by a stale shell endpoint. It is still overridable by a user's stored `settings.yaml`, which is the settings seam's layering and not something this note changes; the product CLI offers no flag above it, so a deployment that must win against stored settings owns its own bin or loader tree.
 - Not solved: the layers are still materialized into `process.env`, so ordinary project variables continue to reach child processes under the subprocess scrub. Bootstrap variables cannot come from a file at all; the environment package records the remaining subprocess reach as a limitation.
-- Exa and Perplexity still capture their key at load time rather than through the credential seam. They no longer read raw `process.env` — they resolve through the trusted layers — but converting them to per-request seam resolution is separate work.
+- Exa and Perplexity still capture their key at load time rather than through the credential seam. They no longer read raw `process.env` — they resolve through the trusted layers — but converting them to per-request credential resolution is separate work.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index ef352ce4c7..20a8aebb62 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -58,7 +58,7 @@ inherited process environment      (read-only, wins)
 - 含 `DSH_*`、`PATH` 或 proxy 变量的 `.env` 会导致启动失败而不是被应用。把开关放在仓库 `.env` 里的开发者需要改放到 shell——这是一次刻意且响亮的破坏。
 - composition 不再会被陈旧的 shell endpoint 覆盖。但它仍然会被用户已存的 `settings.yaml` 覆盖，这是 settings seam 的分层方式，本 Note 不改变它；产品 CLI 没有高于它的标志，因此需要压过已存 settings 的部署方要自带 bin 或 loader 配置树。
 - 未解决的：各层仍然会被物化进 `process.env`，因此普通项目变量继续按子进程清洗规则抵达子进程。bootstrap 变量完全不能来自文件；环境包将其余变量仍可抵达子进程这一点记录为一项限制。
-- Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求经 seam 解析是另一件事。
+- Exa 与 Perplexity 仍在加载时捕获密钥，而不是经凭据 seam。它们不再读裸 `process.env`——改为经受信层解析——但把它们改造成按请求解析凭据是另一件事。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml
index 9b8339d0e2..ba894a29e5 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.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 .agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
-2026-08-04-draft-provider-endpoint-interrogation.md: 65545098cd1063c40081481c1ac8f0afdb4fb390
-2026-08-04-draft-provider-endpoint-interrogation.zh.md: 6300e357182e0e81028c6d01026ea93c4fc5202f
+2026-08-04-draft-provider-endpoint-interrogation.md: 6a545ea5c97ef7e7f0e916c1676c1361f7a9bf3b
+2026-08-04-draft-provider-endpoint-interrogation.zh.md: 852e140cafc6eb595e8784f3735e79cec1b78c42
diff --git a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
index 65545098cd..6a545ea5c9 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.md
@@ -10,7 +10,7 @@ Once a pi-ai route became [a declaration rather than a catalog lookup](2026-08-0
 
 The obvious answer, a dynamic runtime catalog refreshed in the background, was rejected with the layer below it: it makes a route's model list external mutable state needing a cache, an invalidation story, and an offline path, while the product need is narrower. What is needed is a *question asked once*, whose answer the user adopts into `settings.yaml` — so `settings.yaml` remains the only thing deciding what a route serves.
 
-The awkward part is that the question is about something that does not exist yet. The provider being added has no route, no stored profile, and no stored credential; the endpoint and key are values in a form the user is still typing. Every existing seam operation is keyed by a registered provider route, so none of them can carry this.
+The awkward part is that the question is about something that does not exist yet. The provider being added has no route, no stored profile, and no stored credential; the endpoint and key are values in a form the user is still typing. Every existing LLM Service Definition operation is keyed by a registered provider route, so none of them can carry this.
 
 ## Decision
 
@@ -29,7 +29,7 @@ pi-ai supplies `createProvider({ fetchModels })` plus `Models.refresh()` and a `
 
 ## Alternatives considered
 
-**Key interrogation by provider route.** Symmetric with every other seam operation, and it would let the request omit the endpoint. But the case that motivates the feature — adding a provider — has no route, so the operation would only work for providers already configured, which are the ones that need it least.
+**Key interrogation by provider route.** Symmetric with every other LLM Service Definition operation, and it would let the request omit the endpoint. But the case that motivates the feature — adding a provider — has no route, so the operation would only work for providers already configured, which are the ones that need it least.
 
 **Put the capability on `LlmAdapter`.** Adapters are reached through a route registration, so this has the same problem, plus it would make an adapter instance answer questions about endpoints it does not serve.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
index 6300e35718..852e140caf 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-draft-provider-endpoint-interrogation.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 显而易见的答案——后台刷新的运行时动态 catalog——已随下层一并被拒绝：它会把路由的模型列表变成需要缓存、失效语义与离线路径的外部可变状态，而产品需求要窄得多。真正需要的是*只问一次*，其答案由用户采纳进 `settings.yaml`，从而让 `settings.yaml` 始终是决定路由服务内容的唯一真源。
 
-麻烦之处在于，被问的对象还不存在。正在新增的提供方没有路由、没有已存 profile、也没有已存凭据；端点与密钥都是用户尚在输入的表单值。而现有的每个 seam 操作都以已注册的提供方路由为键，因此没有一个能承载它。
+麻烦之处在于，被问的对象还不存在。正在新增的提供方没有路由、没有已存 profile、也没有已存凭据；端点与密钥都是用户尚在输入的表单值。而现有的每个 LLM Service Definition 操作都以已注册的提供方路由为键，因此没有一个能承载它。
 
 ## Decision
 
@@ -29,7 +29,7 @@ pi-ai 提供了 `createProvider({ fetchModels })` 加上 `Models.refresh()` 与
 
 ## Alternatives considered
 
-**以提供方路由为键。** 与其他每个 seam 操作对称，也能让请求省去端点。但催生该功能的场景——新增提供方——没有路由，于是这个操作只对已配置好的提供方可用，而它们恰恰最不需要它。
+**以提供方路由为键。** 与其他每个 LLM Service Definition 操作对称，也能让请求省去端点。但催生该功能的场景——新增提供方——没有路由，于是这个操作只对已配置好的提供方可用，而它们恰恰最不需要它。
 
 **把能力挂在 `LlmAdapter` 上。** 适配器要经由路由注册才能抵达，因此问题相同；而且这会让一个适配器实例去回答它并不服务的端点的问题。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
index d6c40df351..bf5e1a833d 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.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 .agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
-2026-08-04-websocket-downlink-carrier.md: b41ad687725c55acb8517fe7e93d645f007a0453
-2026-08-04-websocket-downlink-carrier.zh.md: c8c8c34c7b7365bc3099cb33a5861051e015b226
+2026-08-04-websocket-downlink-carrier.md: f757487c7b0880cfff25b93644341dc85b5e0e38
+2026-08-04-websocket-downlink-carrier.zh.md: fb07520602b66d33d4bc6e00764ff839f9553a7a
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
index b41ad68772..f757487c7b 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md
@@ -16,7 +16,7 @@ WebSocket carries only the host→browser downlink. All client→host unary call
 
 ## Upgrade and lifecycle boundaries
 
-`dsh-host-webserver` provides an exact upgrade-route registration seam alongside ordinary routes, dispatches Node upgrade sockets by pathname only, contains raw-socket errors, and waits for surviving upgraded connections to close during server teardown; it knows nothing about Harness frames or WebSocket messages. `dsh-client-connection` owns the WebSocket handshake, frame output, and stream cancellation, and reuses the `/api` Host/Origin trust fence before upgrade. An untrusted authority or cross-origin Origin is rejected before `ctx.apiProxy.events.*` starts.
+`dsh-host-webserver` provides an exact upgrade-route registration point alongside ordinary routes, dispatches Node upgrade sockets by pathname only, contains raw-socket errors, and waits for surviving upgraded connections to close during server teardown; it knows nothing about Harness frames or WebSocket messages. `dsh-client-connection` owns the WebSocket handshake, frame output, and stream cancellation, and reuses the `/api` Host/Origin trust fence before upgrade. An untrusted authority or cross-origin Origin is rejected before `ctx.apiProxy.events.*` starts.
 
 A browser abort or socket close cancels the corresponding host stream; plugin teardown also waits for that source iterator's cleanup. If a host stream throws midway, the carrier sends one existing `stream/error` frame and then closes the socket; the client treats that frame as connection loss rather than delivering it to a business sink. Each WebSocket reports open independently, and the existing readiness handshake still waits until mux and host are both open and the `host.describe` HTTP call has succeeded before publishing connected.
 
@@ -36,4 +36,4 @@ Webserver contract tests pin upgrade-pathname dispatch, duplicate-registration r
 
 ## Consequences
 
-Each Web page still has two long-lived downlink connections, but they no longer consume the browser's six-connection HTTP/1.1 quota. The runtime continues to consume the original two streams and retains all reconnect, seam-repair, and cross-stream unordered semantics. The cost is one more upgrade-registration surface in the webserver, a WebSocket implementation dependency in the connection package's host half, and separate maintenance of the browser WebSocket and in-process SSE physical codecs. They share the same `ServerRequest`/frame schemas and `IApiClient` semantics, avoiding a second application protocol.
+Each Web page still has two long-lived downlink connections, but they no longer consume the browser's six-connection HTTP/1.1 quota. The runtime continues to consume the original two streams and retains all reconnect, stream-repair, and cross-stream unordered semantics. The cost is one more upgrade-registration surface in the webserver, a WebSocket implementation dependency in the connection package's host half, and separate maintenance of the browser WebSocket and in-process SSE physical codecs. They share the same `ServerRequest`/frame schemas and `IApiClient` semantics, avoiding a second application protocol.
diff --git a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
index c8c8c34c7b..fb07520602 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md
@@ -16,7 +16,7 @@ WebSocket 只承担 host→browser 下行。所有 client→host unary 调用和
 
 ## Upgrade 与生命周期边界
 
-`dsh-host-webserver` 提供与普通 route 并列的精确 upgrade-route 注册缝，只按 pathname 分发 Node upgrade socket，隔离原始 socket 错误，并在 server teardown 期间等待仍存活的升级连接关闭；它不认识 Harness 帧或 WebSocket message。`dsh-client-connection` 拥有 WebSocket handshake、frame 写出和 stream cancellation，并在 upgrade 前复用 `/api` 的 Host／Origin 信任栅栏。未受信任的 authority 或跨来源 Origin 在 `ctx.apiProxy.events.*` 启动前即被拒绝。
+`dsh-host-webserver` 提供与普通 route 并列的精确 upgrade-route 注册点，只按 pathname 分发 Node upgrade socket，隔离原始 socket 错误，并在 server teardown 期间等待仍存活的升级连接关闭；它不认识 Harness 帧或 WebSocket message。`dsh-client-connection` 拥有 WebSocket handshake、frame 写出和 stream cancellation，并在 upgrade 前复用 `/api` 的 Host／Origin 信任栅栏。未受信任的 authority 或跨来源 Origin 在 `ctx.apiProxy.events.*` 启动前即被拒绝。
 
 浏览器 abort 或 socket close 会取消对应的 host stream；plugin teardown 还会等待该 source iterator 完成清理。host stream 中途抛错时，载体发送一份现有的 `stream/error` frame 后关闭 socket；客户端把该 frame 收敛为连接丢失，不投递给业务 sink。每条 WebSocket 独立报告 open，既有 readiness handshake 仍等待 mux、host 都 open 且 `host.describe` HTTP 调用成功后才发布 connected。
 
@@ -36,4 +36,4 @@ webserver 约定测试钉住 upgrade pathname 分发、重复注册拒绝、disp
 
 ## Consequences
 
-每个 Web 页面仍有两条长期下行连接，但它们不再消耗浏览器的 HTTP/1.1 六连接配额；runtime 继续消费原有双流并保留所有重连、补缝和跨流无序语义。代价是 webserver 多一个 upgrade 注册面，connection host 半依赖 WebSocket 实现，并需分别维护浏览器 WebSocket 与进程内 SSE 两种物理编解码；它们共享同一 `ServerRequest`／frame schema 和 `IApiClient` 语义，避免形成第二套业务协议。
+每个 Web 页面仍有两条长期下行连接，但它们不再消耗浏览器的 HTTP/1.1 六连接配额；runtime 继续消费原有双流并保留所有重连、流修复和跨流无序语义。代价是 webserver 多一个 upgrade 注册面，connection host 半依赖 WebSocket 实现，并需分别维护浏览器 WebSocket 与进程内 SSE 两种物理编解码；它们共享同一 `ServerRequest`／frame schema 和 `IApiClient` 语义，避免形成第二套业务协议。
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index f68aeb97b3..fcac71abf4 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.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 .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
-2026-08-05-profile-plugin-bundles.md: f183fc5ff5f3c8d850e913d9a9b836f075da7a3b
-2026-08-05-profile-plugin-bundles.zh.md: 8887bd39b7d0002f7c683ec74b7c91f002b18406
+2026-08-05-profile-plugin-bundles.md: 8b5ab0c99282f6868fc3f70781e618af9a317c09
+2026-08-05-profile-plugin-bundles.zh.md: 2a685d68b3de9210488e26f8e6dd93dfc07f956c
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
index f183fc5ff5..8b5ab0c992 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
@@ -24,7 +24,7 @@ Two supporting refactors: the webserver's built-in static dist serving became th
 
 - **Dependency-scan plus partial `patchOrder`** (the original sketch): scanning `dependencies` for bundles and ordering unlisted ones alphabetically has two sources of truth and an implicit tie-break; one explicit ordered `dsh.profile.bundles` list is smaller and fully deterministic. A raw `pnpm add` inside the profile installs a library without activating any patch — explicit, no spooky scan.
 - **`link:` entries for in-box bundles**: pnpm cannot version, install, or update a `link:` into the installation, it embeds a machine path in a user file, and it breaks when the installation moves. The two-anchor resolution plus healed symlink fallback gives the same guarantee ("bundles come from the installation") without ceremony.
-- **A pre-boot `context` module in the bundle manifest** for boot-time values (dist path, flag facts): rejected in favor of pure plugins — the glue is ordinary rows the launcher patches, so the composition stays fully dumpable and the manifest stays data-only. The launcher-owned `ctx.headlessIo` seam is the one host-provided slot, and it is provided in `boot()`'s `prepare` hook, before any config-tree entry mounts.
+- **A pre-boot `context` module in the bundle manifest** for boot-time values (dist path, flag facts): rejected in favor of pure plugins — the glue is ordinary rows the launcher patches, so the composition stays fully dumpable and the manifest stays data-only. The launcher-owned `ctx.headlessIo` host hook is the one host-provided slot, and it is provided in `boot()`'s `prepare` hook, before any config-tree entry mounts.
 - **Transitive bundle auto-application**: only direct `dsh.profile.bundles` entries contribute layers; a meta-bundle wanting to re-export another bundle's patch must do so explicitly in its own patch file.
 
 ## Consequences
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index 8887bd39b7..2a685d68b3 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 - **依赖扫描加部分 `patchOrder`**（最初的草案）：扫描 `dependencies` 找出组合包、未列出者按字母序排列，会产生两个真源和一条隐式决胜规则；一份显式有序的 `dsh.profile.bundles` 列表更小、完全确定。在 profile 内直接 `pnpm add` 只会安装一个库，不激活任何 patch——行为显式，没有暗中扫描。
 - **内置组合包使用 `link:` 条目**：pnpm 无法对指向安装目录的 `link:` 做版本管理、安装或更新，它会把机器路径嵌进用户文件，并且在安装目录移动后失效。双锚点解析加上每次启动修复的符号链接回退提供了同样的保证（「组合包来自安装目录」），且没有这些繁文缛节。
-- **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是启动器 patch 的普通配置行，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` seam 是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
+- **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是启动器 patch 的普通配置行，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` 宿主钩子是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
 - **组合包的传递式自动应用**：只有直接列在 `dsh.profile.bundles` 中的条目才贡献层；想重新导出另一个组合包 patch 的元组合包，必须在自己的 patch 文件中显式完成。
 
 ## Consequences
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
index d59721303b..563a2b6bb1 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.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 .agents/notes/implemented/architecture/2026-08-05-session-preparation.md
-2026-08-05-session-preparation.md: 69d39f552ed3041403a24b5aefb435e4e721b09c
-2026-08-05-session-preparation.zh.md: 23681c7cb52d670482bc83e665ec7731dea98bbd
+2026-08-05-session-preparation.md: 50f1ea38e671c6aa7b0f4adaf2fecbf83decc23c
+2026-08-05-session-preparation.zh.md: 84b5cf48452bb09f8ca2d1572772490b703589da
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md
index 69d39f552e..50f1ea38e6 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md
@@ -16,7 +16,7 @@ Fresh creation and persisted resume also reached the same publication boundary t
 
 The Agent loop consumes both forms through one setup-and-publication pipeline: it acquires the preparation, builds the private Agent context around `preparation.session`, awaits optional setup, publishes that exact Session and Agent, and disposes the preparation on every exit. Publication transfers the live lifecycle to the existing Session and Agent stores; `SessionPreparation` itself owns no Agent behavior.
 
-This refines the publication boundary from the [Agent lifecycle and ownership decision](2026-06-18-agent-lifecycle-and-ownership-seams.md) without replacing its ownership model.
+This refines the publication boundary from the [Agent lifecycle and ownership decision](2026-06-18-agent-lifecycle-and-ownership-contracts.md) without replacing its ownership model.
 
 ## Persisted preparation lifecycle
 
diff --git a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
index 23681c7cb5..84b5cf4845 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-session-preparation.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 agent loop（智能体循环）通过同一条设置与发布流水线消费这两种形式：先取得准备对象，围绕 `preparation.session` 构建私有 agent 上下文，等待可选设置完成，再发布该精确 Session 和 agent，并在所有退出路径上对准备对象执行 dispose（资源释放）。发布后，实时生命周期由现有 Session 与 agent 存储接管；`SessionPreparation` 本身不负责任何 agent 行为。
 
-该机制细化了 [agent 生命周期与所有权决策](2026-06-18-agent-lifecycle-and-ownership-seams.md)中的发布边界，但不替换其所有权模型。
+该机制细化了 [agent 生命周期与所有权决策](2026-06-18-agent-lifecycle-and-ownership-contracts.md)中的发布边界，但不替换其所有权模型。
 
 ## 持久化准备生命周期
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
index 3bf5339f3e..c12ec3a68c 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.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 .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
-2026-08-06-subagent-list-identity-projection.md: ba023d04805ff3335c8f243510aa8ddc15fe13d6
-2026-08-06-subagent-list-identity-projection.zh.md: 78aec8f4d0c47178bc033cc74f0314762f49cf7d
+2026-08-06-subagent-list-identity-projection.md: 727c9113fc95a85e6c2732902289a49a76ee8a8d
+2026-08-06-subagent-list-identity-projection.zh.md: c499247a1bd6bd4c971638a29e82f35b16b64690
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
index ba023d0480..727c9113fc 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
@@ -149,7 +149,7 @@ Consuming surfaces: diagnostic handling across wire, tool, and GUI **stays entir
 
 **The projection-cache ladder (v3 draft: `cachedSnapshot ?? coldSnapshot` plus fail-soft write-back).** The mechanism works — session-projection-cache's checkpoint ladder is designed for cold reads in the first place. But checkpoint write-back is a whole list-driven body of derived-data persistence and invalidation orchestration (floor/identity/putSoft); what was rejected is that orchestration as the primary mechanism. The settled three-rung ladder later reuses this cache opportunistically, read-only, as its second rung — no write-back, no orchestration, skipped when absent.
 
-**A bounded-read primitive on persistence to rescue pre-existing data.** Opens a new seam primitive for a one-time problem; superseded by the read-time `inspect` full read — the full read the first time pre-existing data is listed is itself the value retrieval.
+**A bounded-read primitive on persistence to rescue pre-existing data.** Opens a new persistence primitive for a one-time problem; superseded by the read-time `inspect` full read — the full read the first time pre-existing data is listed is itself the value retrieval.
 
 **Optional mode/label on list rows (one v4 draft).** Healthy data is always computable; optionality merely spills garbage-data handling complexity onto every consumer — each consuming surface has to grow filter branches and an unknown display state. The strong contract plus omit-when-uncomputable is cleaner.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
index 78aec8f4d0..c499247a1b 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
@@ -149,7 +149,7 @@ export type SubagentListEntry =
 
 **projection-cache 阶梯（v3 稿：`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的第三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
 
-**给 persistence 加有界读原语抢救存量。** 为一次性问题新开 seam 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
+**给 persistence 加有界读原语抢救存量。** 为一次性问题新开 persistence 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
 
 **list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强约定加算不出即 omit 更干净。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index 81e53d0e26..12e27bf58c 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.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 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
-2026-08-08-client-tool-presentation-ownership.md: 9ea7d7dfc5e18e541550569795c5e1db84d6ad91
-2026-08-08-client-tool-presentation-ownership.zh.md: 010907144dea256fa97cc6bd49bbcf493ad64c78
+2026-08-08-client-tool-presentation-ownership.md: f12a116c34064186b6be1496e1071025221817c4
+2026-08-08-client-tool-presentation-ownership.zh.md: f5f7d71f1e05b27855d29acc223b340c8d89f1d8
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
index 9ea7d7dfc5..f12a116c34 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
@@ -20,11 +20,11 @@ Tool is a first-class Client UI concept with one presentation owner, `@deepseek-
 
 `ui-tool` occupies that whole-Tool seat. `ToolCallTree` recursively walks the root block's `subCalls` and routes every level through one keyed/session `'tool.call.toolview'` child slot using `entryKey: toolName`. An absent business registration renders `GenericToolCard`. It neither reads Session nor maintains a second call topology.
 
-Business plugins register only atomic views against `'tool.call.toolview'`. Their owner payload is the standard Tool call block plus identity, cwd, and host actions; it carries no Session projector or conversation service. Skill remains an ordinary Tool and `ui-skill` registers the `skill` key through this seam. Existing first-party views live in `ui-tool` until a business package has a reason to own one independently.
+Business plugins register only atomic views against `'tool.call.toolview'`. Their owner payload is the standard Tool call block plus identity, cwd, and host actions; it carries no Session projector or conversation service. Skill remains an ordinary Tool and `ui-skill` registers the `skill` key through this slot. Existing first-party views live in `ui-tool` until a business package has a reason to own one independently.
 
 The details panel is a second Tool presentation site but not a call-tree owner. `ui-conversation` delegates its selected output body through the single/session `'conversation.details.tool'` seat; `ui-tool` renders the card-aware output and the seat fallback preserves raw result text when the plugin is absent. Card models therefore have one production owner without introducing a reverse implementation import.
 
-The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch is an official top-level concept because it changes parent/child identity; a private `ToolCallTree` shares one fold between live and history paths and projects its index into standard recursive call blocks. Ordinary Tool business differences stay at the keyed presentation seam, and this package boundary adds no Tool projector/fold registry.
+The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch is an official top-level concept because it changes parent/child identity; a private `ToolCallTree` shares one fold between live and history paths and projects its index into standard recursive call blocks. Ordinary Tool business differences stay at the keyed presentation contract, and this package boundary adds no Tool projector/fold registry.
 
 ## Runtime and render path
 
@@ -102,4 +102,4 @@ Test ownership follows production ownership. `ui-conversation` tests install a l
 
 ## Consequences
 
-`ui-conversation` becomes independent of Tool-name business presentation while retaining ChatFlow, selection, and host interaction responsibilities. Root calls and subcalls cannot drift onto different dispatch paths, and business packages can own atomic Tool presentation without Session changes. The cost is one new Client package and two cross-package slot seams; `ui-tool` also deliberately depends on conversation's declared seats and locale namespace. The assembled Web bundle therefore mounts `ui-tool`; omitting it leaves chat Tool seats empty while the details seat keeps its raw-result fallback, without changing Session reconstruction.
+`ui-conversation` becomes independent of Tool-name business presentation while retaining ChatFlow, selection, and host interaction responsibilities. Root calls and subcalls cannot drift onto different dispatch paths, and business packages can own atomic Tool presentation without Session changes. The cost is one new Client package and two cross-package slot contracts; `ui-tool` also deliberately depends on conversation's declared seats and locale namespace. The assembled Web bundle therefore mounts `ui-tool`; omitting it leaves chat Tool seats empty while the details seat keeps its raw-result fallback, without changing Session reconstruction.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index 010907144d..f5f7d71f1e 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -20,11 +20,11 @@ Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool`
 
 `ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 直接递归遍历 root block 的 `subCalls`，并让每一层调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。它不读取 Session，也不维护第二份调用拓扑。
 
-业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 seam 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
+业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 slot 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
 
 details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 通过 single/session 的 `'conversation.details.tool'` 席位委托 selected output body；`ui-tool` 渲染能够识别 card 的输出，插件缺席时由席位 fallback 保留 raw result text。因此 card model 只有一个生产代码所有者，也不需要引入反向实现依赖。
 
-Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 作为官方顶级概念改变 parent/child identity；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示 seam，这个包边界不会增加 Tool projector/fold registry。
+Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 作为官方顶级概念改变 parent/child identity；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示约定，这个包边界不会增加 Tool projector/fold registry。
 
 ## Runtime 与渲染链路
 
@@ -102,4 +102,4 @@ ctx.slots.inject('tool.call.toolview', () =>
 
 ## Consequences
 
-`ui-conversation` 不再依赖 Tool 名称对应的业务展示，同时保留 ChatFlow、selection 与宿主交互责任。root call 与 subcall 不会漂移到不同分发路径，业务包无需修改 Session 即可拥有原子 Tool 展示。代价是新增一个 Client package 与两个跨包 slot seam；`ui-tool` 也明确依赖 conversation 声明的席位与 locale namespace。因此组装后的 Web bundle 会挂载 `ui-tool`；省略该插件时，chat Tool 席位为空，details 席位则保留 raw-result fallback，且 Session 重建不受影响。
+`ui-conversation` 不再依赖 Tool 名称对应的业务展示，同时保留 ChatFlow、selection 与宿主交互责任。root call 与 subcall 不会漂移到不同分发路径，业务包无需修改 Session 即可拥有原子 Tool 展示。代价是新增一个 Client package 与两份跨包 slot 约定；`ui-tool` 也明确依赖 conversation 声明的席位与 locale namespace。因此组装后的 Web bundle 会挂载 `ui-tool`；省略该插件时，chat Tool 席位为空，details 席位则保留 raw-result fallback，且 Session 重建不受影响。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
index eda7b29acf..c9581fcbfb 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.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 .agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
-2026-07-20-error-cause-chain-diagnostics.md: 89edd4529cc16617fdca736dbbea4b170400d6bd
-2026-07-20-error-cause-chain-diagnostics.zh.md: 673921c913a9f1fefe6f85303cf5952f8edbcc1d
+2026-07-20-error-cause-chain-diagnostics.md: 32716b5a68b3b73bded47633eca95995cdbfc586
+2026-07-20-error-cause-chain-diagnostics.zh.md: 9911c32b6d68c1f5569a1fceadb65e23c6586594
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
index 89edd4529c..32716b5a68 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.md
@@ -1,4 +1,4 @@
-# Agent Note: Render error cause chains at every diagnostic seam
+# Agent Note: Render error cause chains at every diagnostic boundary
 
 Status: implemented
 
@@ -8,14 +8,14 @@ English | [中文](2026-07-20-error-cause-chain-diagnostics.zh.md)
 
 A TUI run against an unreachable DeepSeek endpoint failed with the single notice `fetch failed` and no further detail. Two independent gaps produced that dead end:
 
-1. undici's `fetch` wraps every transport failure (DNS, refused connection, TLS, proxy) in a bare `TypeError: fetch failed` whose actionable detail — `ECONNREFUSED`, `bad port`, the Happy Eyeballs AggregateError — lives on `error.cause`. Every diagnostic seam in the harness rendered only `error.message` (or `String(error)`, which is equivalent for Errors), so the wrapper masked the diagnosis in the TUI notice, the durable `turn/end` reason, and every logger line.
+1. undici's `fetch` wraps every transport failure (DNS, refused connection, TLS, proxy) in a bare `TypeError: fetch failed` whose actionable detail — `ECONNREFUSED`, `bad port`, the Happy Eyeballs AggregateError — lives on `error.cause`. Every diagnostic boundary in the harness rendered only `error.message` (or `String(error)`, which is equivalent for Errors), so the wrapper masked the diagnosis in the TUI notice, the durable `turn/end` reason, and every logger line.
 2. The readline front door (`dsh-stdio`) rendered no failure reason at all: a `turn/end` with `reason.kind === 'error'` printed nothing but the next `> ` prompt, so the same failure in `demo:repl` was pure silence.
 
 ## Decision
 
 - `dsh-llm` exports `errorChain(value)`: renders a thrown value with its full `cause` chain (`outer: inner: …`) and AggregateError members (`msg [m1; m2]`), with circular-cause and hostile-coercion containment. It is a diagnostic-surface renderer only; routing stays on `HarnessError.code`.
 - The DeepSeek adapter wraps a pre-response transport failure in `LlmError('TRANSPORT')` naming the configured `baseURL` and chaining the original rejection as `cause`. An aborted request becomes `LlmError('ABORTED')`; because the turn signal is already aborted, the loop still classifies the turn as cancellation rather than recovery.
-- Every diagnostic seam renders through `errorChain` instead of `error.message`/`String(error)`: the agent-loop's durable `turn/end` error message (`errorData`), its logger warnings, the TUI's `agent/error` notice and startup-failure line, and `dsh-stdio`'s startup-failure log lines. The live `agent/error` event and `SettleReason` preserve the thrown value as `unknown`; each diagnostic consumer renders it instead of the loop wrapping it into another error. The per-package `renderThrown` copies in `dsh-agent-loop`, `dsh-stdio`, and `dsh-tui` are deleted in favor of the one shared renderer.
+- Every diagnostic boundary renders through `errorChain` instead of `error.message`/`String(error)`: the agent-loop's durable `turn/end` error message (`errorData`), its logger warnings, the TUI's `agent/error` notice and startup-failure line, and `dsh-stdio`'s startup-failure log lines. The live `agent/error` event and `SettleReason` preserve the thrown value as `unknown`; each diagnostic Consumer renders it instead of the loop wrapping it into another error. The per-package `renderThrown` copies in `dsh-agent-loop`, `dsh-stdio`, and `dsh-tui` are deleted in favor of the one shared renderer.
 - `dsh-stdio` renders failure `turn/end` reasons: `[turn failed <code>] <message>`, `[turn aborted] <reason>`, `[turn rejected] <reason>`, `[turn interrupted by a previous process exit]`, and the output-token-limit notice. Unknown merge-extended kinds fall through as ordinary turn ends.
 
 `errorChain` lives in `dsh-llm` beside `HarnessError` for the same reason the base class does: it is the leaf package every consumer already imports, so sharing costs no new dependency edge.
@@ -32,6 +32,6 @@ A TUI run against an unreachable DeepSeek endpoint failed with the single notice
 
 - A transport failure now reads `DeepSeek API request to <baseURL> failed: fetch failed: connect ECONNREFUSED …` in the TUI notice, the readline transcript, and the persisted session log, at the cost of longer diagnostic strings.
 - Durable `turn/end` error messages include cause detail. Existing snapshot fixtures replay byte-identically because their scripted errors carry no `cause` (for such errors `errorChain(err)` equals `err.message`); only unit-test expectation strings changed. A fixture recorded from a real transport failure would carry the chain.
-- `errorChain` renders `message` without the class name (`String(error)` rendered `Error: <message>`), so a bare `TypeError` in a log line loses its type label unless its message is empty (then the name is the fallback). The chain detail was judged worth more than the class name at these seams.
+- `errorChain` renders `message` without the class name (`String(error)` rendered `Error: <message>`), so a bare `TypeError` in a log line loses its type label unless its message is empty (then the name is the fallback). The chain detail was judged worth more than the class name at these diagnostic boundaries.
 - `dsh-stdio` output for failed turns is no longer silent; piped consumers that parsed the transcript see new `[turn …]` lines.
 - Remaining `renderThrown` copies in `dsh-subagent`, `dsh-workflow`, `dsh-skill`, and `dsh-workflow-workerthread` still render without the chain; they wrap package-local errors that carry their own messages, and can adopt `errorChain` when their diagnostics prove insufficient.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
index 673921c913..9911c32b6d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-20-error-cause-chain-diagnostics.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 在每个诊断界面渲染错误 cause 链
+# Agent Note: 在每个诊断边界渲染错误 cause 链
 
 Status: implemented
 
@@ -8,14 +8,14 @@ Status: implemented
 
 TUI 连接不可达的 DeepSeek 端点时，失败只显示一条 `fetch failed` 通知，没有任何进一步细节。两个独立缺口共同造成了这个死胡同：
 
-1. undici 的 `fetch` 把所有传输层失败（DNS、连接被拒、TLS、代理）包装成裸的 `TypeError: fetch failed`，可操作的细节——`ECONNREFUSED`、`bad port`、Happy Eyeballs 的 AggregateError——都在 `error.cause` 上。harness 里的每个诊断界面都只渲染 `error.message`（或对 Error 等价的 `String(error)`），于是包装层在 TUI 通知、持久化的 `turn/end` reason 和所有日志行里都掩盖了诊断信息。
+1. undici 的 `fetch` 把所有传输层失败（DNS、连接被拒、TLS、代理）包装成裸的 `TypeError: fetch failed`，可操作的细节——`ECONNREFUSED`、`bad port`、Happy Eyeballs 的 AggregateError——都在 `error.cause` 上。harness 里的每个诊断边界都只渲染 `error.message`（或对 Error 等价的 `String(error)`），于是包装层在 TUI 通知、持久化的 `turn/end` reason 和所有日志行里都掩盖了诊断信息。
 2. readline 前门（`dsh-stdio`）完全不渲染失败原因：`reason.kind === 'error'` 的 `turn/end` 只打印下一个 `> ` 提示符，同样的失败在 `demo:repl` 里就是纯粹的沉默。
 
 ## 决策
 
 - `dsh-llm` 导出 `errorChain(value)`：渲染抛出值及其完整 `cause` 链（`outer: inner: …`）与 AggregateError 成员（`msg [m1; m2]`），并容错循环 cause 和恶意强制转换。它只是用于诊断界面的渲染器；路由仍然基于 `HarnessError.code`。
 - DeepSeek 适配器把拿到响应之前的传输失败包装成 `LlmError('TRANSPORT')`，写明配置的 `baseURL` 并将原始拒绝值作为 `cause` 串入错误链。被中止的请求变为 `LlmError('ABORTED')`；由于轮次信号已处于中止状态，agent loop（智能体循环）仍将该轮次归类为取消而非恢复。
-- 每个诊断界面改用 `errorChain` 而非 `error.message`/`String(error)`：agent-loop 的持久化 `turn/end` 错误消息（`errorData`）、其日志警告、TUI 的 `agent/error` 通知与启动失败行、以及 `dsh-stdio` 的启动失败日志行。实时 `agent/error` 事件与 `SettleReason` 以 `unknown` 原样保留抛出值；各诊断消费方自行渲染，而不是由循环把它包装成另一个错误。`dsh-agent-loop`、`dsh-stdio`、`dsh-tui` 里各自的 `renderThrown` 副本被删除，统一使用这一个共享渲染器。
+- 每个诊断边界改用 `errorChain` 而非 `error.message`/`String(error)`：agent-loop 的持久化 `turn/end` 错误消息（`errorData`）、其日志警告、TUI 的 `agent/error` 通知与启动失败行、以及 `dsh-stdio` 的启动失败日志行。实时 `agent/error` 事件与 `SettleReason` 以 `unknown` 原样保留抛出值；各诊断 Consumer 自行渲染，而不是由循环把它包装成另一个错误。`dsh-agent-loop`、`dsh-stdio`、`dsh-tui` 里各自的 `renderThrown` 副本被删除，统一使用这一个共享渲染器。
 - `dsh-stdio` 渲染失败的 `turn/end` reason：`[turn failed <code>] <message>`、`[turn aborted] <reason>`、`[turn rejected] <reason>`、`[turn interrupted by a previous process exit]` 以及输出 token 上限通知。通过声明合并扩展出的未知 kind 按普通 turn 结束处理。
 
 `errorChain` 与 `HarnessError` 一样放在 `dsh-llm` 里，理由相同：它是每个消费方都已导入的叶子包，共享不增加新的依赖边。
@@ -32,6 +32,6 @@ TUI 连接不可达的 DeepSeek 端点时，失败只显示一条 `fetch failed`
 
 - 传输失败现在在 TUI 通知、readline transcript（文本记录）和持久化会话日志里显示为 `DeepSeek API request to <baseURL> failed: fetch failed: connect ECONNREFUSED …`，代价是更长的诊断字符串。
 - 持久化的 `turn/end` 错误消息包含 cause 细节。现有快照 fixture（测试前置数据）字节级一致地回放，因为其脚本化错误不带 `cause`（对这类错误 `errorChain(err)` 等于 `err.message`）；只有单元测试的期望字符串有变化。从真实传输失败录制的 fixture 会携带完整链。
-- `errorChain` 渲染 `message` 而不带类名（`String(error)` 会渲染 `Error: <message>`），因此日志行里的裸 `TypeError` 会丢失类型标签，除非消息为空（此时回退到类名）。在这些诊断界面上，链细节被判断为比类名更有价值。
+- `errorChain` 渲染 `message` 而不带类名（`String(error)` 会渲染 `Error: <message>`），因此日志行里的裸 `TypeError` 会丢失类型标签，除非消息为空（此时回退到类名）。在这些诊断边界上，链细节被判断为比类名更有价值。
 - `dsh-stdio` 对失败轮次的输出不再沉默；解析 transcript 的管道消费方会看到新的 `[turn …]` 行。
 - `dsh-subagent`、`dsh-workflow`、`dsh-skill`、`dsh-workflow-workerthread` 里剩余的 `renderThrown` 副本仍不渲染链；它们包装的是自带消息的包内错误，等诊断信息证明不足时再采用 `errorChain`。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.i18n.yaml
index 4a4e6d71cc..c7891f6a05 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.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 .agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md
-2026-07-22-pi-ai-transport-truncation-classification.md: 119200a788c0b0521f385f4cf4e6adf05a0512f9
+2026-07-22-pi-ai-transport-truncation-classification.md: 4f645a26286bac3d95b285d1f37422797775e979
 2026-07-22-pi-ai-transport-truncation-classification.zh.md: 0625d6041ccaeaff9d0d6f659c7b3856ab985ef6
diff --git a/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md b/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md
index 119200a788..4f645a2628 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md
@@ -22,7 +22,7 @@ Classification stays on message text because that is the only signal pi-ai deliv
 
 ## Alternatives considered
 
-**Capture the `cause` via a pi-ai fetch/dispatcher/client hook.** Rejected: pi-ai 0.81.1 exposes none. `StreamOptions` offers only `onPayload`/`onResponse`; `onResponse` fires before the body stream is consumed, so it cannot observe a mid-stream drop. The Anthropic path accepts a `client` object, but constructing and injecting a provider SDK client per request to intercept transport errors reaches around the adapter seam for one diagnostic string.
+**Capture the `cause` via a pi-ai fetch/dispatcher/client hook.** Rejected: pi-ai 0.81.1 exposes none. `StreamOptions` offers only `onPayload`/`onResponse`; `onResponse` fires before the body stream is consumed, so it cannot observe a mid-stream drop. The Anthropic path accepts a `client` object, but constructing and injecting a provider SDK client per request to intercept transport errors reaches around the adapter boundary for one diagnostic string.
 
 **Leave both as `PI_AI_ERROR` and widen `llm-retry`'s retryable set.** Rejected: `PI_AI_ERROR` is the catch-all for genuinely unclassified failures, including non-retryable ones (a malformed provider response, an unexpected SDK bug). Making the catch-all retryable would retry failures that will never succeed; the fix is to classify the recoverable case, not to blur the bucket.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index a14b575c0f..231502dcb7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: dbc3f9e23be9120df62c2b6b7a9d9aba4c3a42a9
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 329392c47d69c4cf3506a5e14ca0ef48d35dce4c
+2026-07-30-web-transcript-log-ordered-projection.md: e261ccba597f27149a9527f99b93454dfe5fe5fb
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 5684a8157bb7e1b23cd868fa13ab201ffd07a274
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index dbc3f9e23b..e261ccba59 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -37,7 +37,7 @@ import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpo
 const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 ```
 
-Renaming the seam's plugin id is now a compile error in the client: `TS2322: Type '"compact"' is not assignable to type '"compaction"'`. The import must stay **type-only** — a value import of any `@deepseek-ai` package that is neither a platform module nor an inline-safe wire layer is rejected by the client purity gate (`packages/client/tsdown.client.ts`), whose own message records that type-only imports are erased and never reach it. A type-only leaf import needs both a `tsconfig.base.json` `paths` entry and `{"path": "../../compact/compact"}` in `packages/client/runtime/tsconfig.json` `references`: composite `rootDir` rules apply to erased imports as well, and without the reference the diagnostic is `TS6059`/`TS6307`.
+Renaming the Service Definition's plugin id is now a compile error in the client: `TS2322: Type '"compact"' is not assignable to type '"compaction"'`. The import must stay **type-only** — a value import of any `@deepseek-ai` package that is neither a platform module nor an inline-safe wire layer is rejected by the client purity gate (`packages/client/tsdown.client.ts`), whose own message records that type-only imports are erased and never reach it. A type-only leaf import needs both a `tsconfig.base.json` `paths` entry and `{"path": "../../compact/compact"}` in `packages/client/runtime/tsconfig.json` `references`: composite `rootDir` rules apply to erased imports as well, and without the reference the diagnostic is `TS6059`/`TS6307`.
 
 `packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` stays as the behavioral half, driving the adapter with a checkpoint built from the canonical **value**. The test value-imports the cordis-free `@deepseek-ai/dsh-compact/checkpoint` leaf and deliberately never loads the compact package root or the host-side `Context` merges reachable through it.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 329392c47d..5684a8157b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -37,7 +37,7 @@ import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpo
 const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 ```
 
-重命名缝隙的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。
+重命名 Service Definition 的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。
 
 `packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` 作为行为侧的另一半保留，用由权威**值**构造的检查点驱动适配器。该测试以值导入方式从不含 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 叶子路径取得该值，并刻意不加载 compact 包根或经由它可达的宿主侧 `Context` 合并。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
index 7832e30b52..e7139bc607 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.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 .agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
-2026-07-31-resume-selector-batch-projection.md: 39146527f13b20813bb6f5d5f1349ecab5724662
-2026-07-31-resume-selector-batch-projection.zh.md: 19bea7211cc61fa7db80370ee3092e5c88bf931b
+2026-07-31-resume-selector-batch-projection.md: 5b0b33c34137efb95f31e07e7fce7622aeb2dbce
+2026-07-31-resume-selector-batch-projection.zh.md: a12df91ba75b7bdc2d9f48dc633ad1689d163180
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
index 39146527f1..5b0b33c341 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.md
@@ -22,7 +22,7 @@ No session-query or session-persistence surface changed. The shipped TUI composi
 
 ## Alternatives considered
 
-**Keep per-row route/turn/goal columns via a generic batch projection (`projectSessions`).** Implemented first, then rejected: it still decompressed and parsed every log on every `/resume`, so browsing cost stayed O(total log bytes), and it grew the session-query public API for one consumer. The public seam was reverted; `readTitleSnapshots` keeps using the internal `projectMany` unchanged.
+**Keep per-row route/turn/goal columns via a generic batch projection (`projectSessions`).** Implemented first, then rejected: it still decompressed and parsed every log on every `/resume`, so browsing cost stayed O(total log bytes), and it grew the session-query public API for one consumer. The public contract was reverted; `readTitleSnapshots` keeps using the internal `projectMany` unchanged.
 
 **Fix only the O(N²) listing inside `SessionCorpus.load()`.** Rejected as the primary fix: the per-candidate full decompress, replay validation, and triple clone dominated on large logs. The redundant pre-listing in `load()` remains a candidate cleanup with error-semantics implications.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
index 19bea7211c..a12df91ba7 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-resume-selector-batch-projection.zh.md
@@ -22,7 +22,7 @@ session-query 与 session-persistence 的任何表面都未改变。随附的 TU
 
 ## Alternatives considered
 
-**通过通用批量投影（`projectSessions`）保留每行的路由/轮次/目标列。** 先实现后否决：它仍在每次 `/resume` 时解压并解析全部日志，浏览开销依旧是 O(日志总字节数)，且为单一消费者扩大了 session-query 公开 API。该公开 seam 已回退；`readTitleSnapshots` 继续使用内部 `projectMany`，保持不变。
+**通过通用批量投影（`projectSessions`）保留每行的路由/轮次/目标列。** 先实现后否决：它仍在每次 `/resume` 时解压并解析全部日志，浏览开销依旧是 O(日志总字节数)，且为单一消费者扩大了 session-query 公开 API。该公开约定已回退；`readTitleSnapshots` 继续使用内部 `projectMany`，保持不变。
 
 **只修复 `SessionCorpus.load()` 内部的 O(N²) 列表查询。** 作为主要修复被否决：在大日志上，按候选行执行的完整解压、回放验证和三重克隆才是主要开销。`load()` 中的冗余预列表查询仍是一个候选清理项，但涉及错误语义。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index 3a9d189fb5..c20fdb52b5 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.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 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
-2026-08-06-api-key-format-validation.md: 2174cb466c6af72f15005ce1ba3dec8100de6f2f
-2026-08-06-api-key-format-validation.zh.md: 540239c34637eb5940be105127f3367e0969acfa
+2026-08-06-api-key-format-validation.md: f404a3bed728f9917f794f9c06f1a9dad32e64c8
+2026-08-06-api-key-format-validation.zh.md: a94d7eb577a84e7adf440c034aebe603faec7f64
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
index 2174cb466c..f404a3bed7 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
@@ -42,9 +42,9 @@ The rule applies to a value that was *provided*; deciding whether one was provid
 
 ### Where the rule lives
 
-`normalizeApiKey` is a module of the `dsh-llm` seam, beside [attribution.ts](../../../../packages/llm/llm/src/attribution.ts), which already owns shared header concerns. Both adapters depend on the seam and both need the rule, so it has two current consumers rather than a speculative one. It returns the trimmed value or a reason (`empty`, `illegalCharacters`).
+`normalizeApiKey` is a module of the `dsh-llm` Service Definition, beside [attribution.ts](../../../../packages/llm/llm/src/attribution.ts), which already owns shared header concerns. Both adapters depend on the seam and both need the rule, so it has two current consumers rather than a speculative one. It returns the trimmed value or a reason (`empty`, `illegalCharacters`).
 
-Both adapters also need the identical "refuse a stored credential" diagnosis, differing only by package prefix. `LlmError` is declared in the seam's `index.ts`, so `assertUsableApiKey(raw, pkg, ref)` lives there beside it and neither adapter carries a local copy. The predicate module stays dependency-free: importing `LlmError` into `api-key.ts` would cycle with `index.ts`'s re-export of it.
+Both adapters also need the identical "refuse a stored credential" diagnosis, differing only by package prefix. `LlmError` is declared in the Service Definition's `index.ts`, so `assertUsableApiKey(raw, pkg, ref)` lives there beside it and neither adapter carries a local copy. The predicate module stays dependency-free: importing `LlmError` into `api-key.ts` would cycle with `index.ts`'s re-export of it.
 
 The client cannot import any of this: client packages reference only client packages, so `packages/client/ui-models` mirrors the predicate in its own `apiKey.ts` and owns the localized messages, exactly as `validateDeepSeekModels` mirrors the host's `catalogModel` schema. Each side names the other in a comment.
 
@@ -66,7 +66,7 @@ The client cannot import any of this: client packages reference only client pack
 
 **A validation module shared by client and host.** Rejected by the source-plane layout: client packages reference only client packages plus `vendor/cordis` and `support/invariants`, and widening that to reach a host package would collide the two `Context` merges the split exists to keep apart. Mirroring a one-line predicate with a test on each side is the established shape here.
 
-**A per-adapter thrower in each of `llm-deepseek` and `llm-pi-ai`.** The first plan gave each adapter its own, differing only by the package prefix in the message, with a duplication-gate exemption to excuse the pair. Rejected before implementation: `LlmError` is declared in the seam, so the seam can own the diagnosis outright, and an exemption there would have hidden exactly the duplication it was covering for.
+**A per-adapter thrower in each of `llm-deepseek` and `llm-pi-ai`.** The first plan gave each adapter its own, differing only by the package prefix in the message, with a duplication-gate exemption to excuse the pair. Rejected before implementation: `LlmError` is declared in the Service Definition, so that package can own the diagnosis outright, and an exemption there would have hidden exactly the duplication it was covering for.
 
 **Sniffing the `TypeError` in the adapter's `catch`.** This would classify the ByteString failure after the fact, leaving the header construction itself unguarded. It depends on the wording of a Node error message, so it degrades silently across runtime versions, and it cannot help `llm-pi-ai`, whose request header is built inside the pi-ai SDK. Refusing the key before handing it over works for both adapters and for the discovery probe.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index 540239c346..a94d7eb577 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -42,9 +42,9 @@ Status: implemented
 
 ### 规则住在哪里
 
-`normalizeApiKey` 是 `dsh-llm` seam 的一个模块，与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则，因此它拥有两个当前消费方而非一个预设消费方。它返回 trim 后的值，或一个原因（`empty`、`illegalCharacters`）。
+`normalizeApiKey` 是 `dsh-llm` Service Definition 的一个模块，与已经承担共享 header 事务的 [attribution.ts](../../../../packages/llm/llm/src/attribution.ts) 并列。两个适配器都依赖该 seam 且都需要这条规则，因此它拥有两个当前消费方而非一个预设消费方。它返回 trim 后的值，或一个原因（`empty`、`illegalCharacters`）。
 
-两个适配器同样都需要那句完全相同的「拒绝一个已存储凭据」的诊断，差别仅在包名前缀。`LlmError` 声明在 seam 的 `index.ts` 中，因此 `assertUsableApiKey(raw, pkg, ref)` 就住在它旁边，两个适配器都不再各留一份。断言模块本身保持零依赖：把 `LlmError` 引入 `api-key.ts` 会与 `index.ts` 对它的再导出成环。
+两个适配器同样都需要那句完全相同的「拒绝一个已存储凭据」的诊断，差别仅在包名前缀。`LlmError` 声明在 Service Definition 的 `index.ts` 中，因此 `assertUsableApiKey(raw, pkg, ref)` 就住在它旁边，两个适配器都不再各留一份。断言模块本身保持零依赖：把 `LlmError` 引入 `api-key.ts` 会与 `index.ts` 对它的再导出成环。
 
 客户端无法引入其中任何一个：client 包只 reference client 包，因此 `packages/client/ui-models` 在自己的 `apiKey.ts` 中镜像这个断言并持有本地化文案，正如 `validateDeepSeekModels` 镜像 host 侧的 `catalogModel` schema。两侧在注释中互相指名。
 
@@ -66,7 +66,7 @@ Status: implemented
 
 **由 client 与 host 共享一个校验模块。** 被 source plane 布局否决：client 包只 reference client 包外加 `vendor/cordis` 与 `support/invariants`，把它放宽到够得着 host 包会撞上这一分割本就要隔开的两份 `Context` 合并。在两侧各镜像一行断言并各配一份测试，是此处的既定形态。
 
-**在 `llm-deepseek` 与 `llm-pi-ai` 中各留一个抛错 helper。** 最初的计划正是各留一份，差别仅在消息中的包名前缀，并配一个重复检测豁免来放行这一对。在实现之前即被否决：`LlmError` 声明在 seam 中，因此 seam 完全可以自己拥有这句诊断，而那里的一个豁免恰恰会掩盖它本要遮掩的重复。
+**在 `llm-deepseek` 与 `llm-pi-ai` 中各留一个抛错 helper。** 最初的计划正是各留一份，差别仅在消息中的包名前缀，并配一个重复检测豁免来放行这一对。在实现之前即被否决：`LlmError` 声明在 Service Definition 中，因此该包完全可以自己拥有这句诊断，而那里的一个豁免恰恰会掩盖它本要遮掩的重复。
 
 **在适配器的 `catch` 中嗅探 `TypeError`。** 这只是事后归类 ByteString 失败，header 构造本身仍无防护。它依赖 Node 错误消息的措辞，因而会随运行时版本静默失效；它也帮不到 `llm-pi-ai`——后者的请求 header 构造在 pi-ai SDK 内部。在交出 Key 之前就拒绝，则对两个适配器与探测路径同时有效。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 97e5ee763f..34e437c316 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 99bbed3edab32512f88ece9694d6519a1f89c2dd
-2026-06-15-code-mode.zh.md: 87e39d7b68dd1dc2ebdee57f731be30d396a907b
+2026-06-15-code-mode.md: 8a6fa068a4c7fee6fbfd9e16757a0fae5efa0c8b
+2026-06-15-code-mode.zh.md: 00d4fd48b83e183d45423722bf223a63e305d5a4
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index 99bbed3eda..8a6fa068a4 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -19,7 +19,7 @@ Tool presentation belongs to the registry that owns tool visibility: implementin
 Three decisions, each elaborated in its own section below:
 
 1. **Code Mode is a first-class presentation mode of `ToolRegistry`** (`dsh-tools`), selected by a validated `mode` config: `'native'` (the default, contributing the visible capability schemas), `'code'` (the registry contributes only its reserved `run_code` transport plus a generated SDK `.d.ts` in the system prompt), or `'both'` (native schemas and the transport + SDK). The registry shapes its canonical contribution at the source; the cooperative prompt-assembly result remains authoritative, and the logged request header records exactly that returned presentation.
-2. **Code execution is a capability seam** — `packages/code-runtime/` contains the interface package `@deepseek-ai/dsh-code-runtime`, which owns `ctx.codeRuntime` ([capability seams](../architecture/2026-06-13-capability-seams.md); consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is another implementation package, not a redesign.
+2. **Code execution is a capability seam** — `packages/code-runtime/` contains the Service Definition package `@deepseek-ai/dsh-code-runtime`, which owns `ctx.codeRuntime` ([capability seams](../architecture/2026-06-13-capability-seams.md); Consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is another Service provider package, not a redesign.
 3. **The shipped implementation is `@deepseek-ai/dsh-code-runtime-worker`**: one fresh Node worker thread per run, executing the model's TypeScript after type-strip, with bindings bridged over the message port, an empty environment, configurable heap/output/time caps, and hard termination. Its trust posture is bash-equivalent by design — no unsafe-acknowledgement flags — because the harness already ships `dsh-bash-local`, which executes arbitrary model-written shell commands with strictly *more* ambient authority.
 
 This note owns Code Mode's presentation, composition, isolation, and settlement foundation. The later [typed tool-return Agent Note](2026-07-20-code-mode-typed-tool-returns.md) owns the generated output map, canonical binding values, `ToolCallError`, and the lossless outer-output boundary.
@@ -118,7 +118,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 ## Risks
 
-**The worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool, containment exceeds it, gating uses the same seams. Deployments needing more need a future `isolation: 'container'` backend — tracked as the seam's designed extension, not a TODO on this design.
+**The worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool, containment exceeds it, gating uses the same approval and sandbox policies. Deployments needing more need a future `isolation: 'container'` backend — tracked as the seam's designed extension, not a TODO on this design.
 
 **`stripTypeScriptTypes` is marked experimental.** It is the same engine (amaro/swc) behind Node's own native `.ts` execution, exposed as an API across this repo's whole engines range. Mitigations: the runtime's unit suite pins the behaviors relied on (position preservation, erasable-only rejection message shape loosely), the call sits behind one private function, and `amaro`/`sucrase` are drop-in replacements if the API shifts. The erasable-only subset is a model-facing contract line, and the error path is a working feedback loop, not a dead end.
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index 87e39d7b68..00d4fd48b8 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -19,7 +19,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 三项决策，各自在下方独立小节中展开：
 
 1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
-2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包`@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
+2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含 Service Definition 包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；Consumer = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个 Service provider 包，而非重新设计。
 3. **交付的实现是 `@deepseek-ai/dsh-code-runtime-worker`**：每次运行 spawn 一个全新的 Node worker 线程，对模型的 TypeScript 进行 type-strip 后执行，绑定通过消息端口桥接，环境为空，堆/输出/时间上限可配置，并支持硬终止。其信任姿态在设计上等同于 bash——无需 unsafe-acknowledgement flag——因为 harness 已经交付了 `dsh-bash-local`，后者以严格*更高*的环境权限执行模型编写的任意 shell 命令。
 
 本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
@@ -118,7 +118,7 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 ## 风险
 
-**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，约束能力强于它，门禁使用相同的 seam。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
+**Worker 不是硬安全边界。** 有意为之且已文档化（§信任姿态）：姿态等同于既有的 bash 工具，约束能力强于它，门禁使用相同的审批与沙箱策略。需要更强隔离的部署需要未来的 `isolation: 'container'` 后端——作为 seam 设计的扩展点跟踪，而非本设计的 TODO。
 
 **`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的约定线，错误路径是一个可工作的反馈循环，而非死胡同。
 
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
index 586cab797e..860156eb06 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.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 .agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
-2026-06-17-filesystem-tool-schemas.md: 9941b3916b361a916c8148eb099eb8cfd46371c8
-2026-06-17-filesystem-tool-schemas.zh.md: 8ba3c18629863ca9f04548d5993e9d200ecd4912
+2026-06-17-filesystem-tool-schemas.md: b48f8e5d44913f2b6a2b7e1b19269c58e72efd1f
+2026-06-17-filesystem-tool-schemas.zh.md: ad4081d28950a4a2df4f5718038e2a4124bf70b5
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
index 9941b3916b..b48f8e5d44 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
@@ -20,7 +20,7 @@ The schema should be small enough to implement in the first `dsh-tool-fs` pass,
 | `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | Creates or overwrites UTF-8 text. Under the default fs-policy, updates to existing files require a prior observation; new-file creates do not. | YES |
 | `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | Literal string replacement; unique match required by default; under the default fs-policy requires a prior observation (any windowed read counts). | YES |
 
-The schema uses snake_case field names (`file_path`, `old_string`, `new_string`, `replace_all`) to align with Claude Code and with existing DeepSeek Harness tool-schema examples. The consumer package translates these model-facing names into `ctx.fs` calls and `fs/*` event dispatches.
+The schema uses snake_case field names (`file_path`, `old_string`, `new_string`, `replace_all`) to align with Claude Code and with existing DeepSeek Harness tool-schema examples. The Consumer package translates these model-facing names into `ctx.fs` calls and `fs/*` event dispatches.
 
 ## Tool schemas
 
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
index 8ba3c18629..ad4081d289 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 | `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | 创建或覆盖 UTF-8 文本。在默认 fs-policy 下，更新现有文件前必须先观测；创建新文件则不需要。 | 是 |
 | `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | 字面字符串替换；默认要求唯一匹配；在默认 fs-policy 下必须先观测（任意窗口读取均算作观测）。 | 是 |
 
-schema 使用 snake_case 字段名（`file_path`、`old_string`、`new_string`、`replace_all`），与 Claude Code 及现有 DeepSeek Harness 工具 schema 示例保持一致。消费方包将这些面向模型的名称转换为 `ctx.fs` 调用和 `fs/*` 事件分发。
+schema 使用 snake_case 字段名（`file_path`、`old_string`、`new_string`、`replace_all`），与 Claude Code 及现有 DeepSeek Harness 工具 schema 示例保持一致。Consumer 包将这些面向模型的名称转换为 `ctx.fs` 调用和 `fs/*` 事件分发。
 
 ## 工具 schema
 
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index c23637d7e3..1ab18b72e9 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.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 .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: fa9325d08fa73dd1654216d211abb03cdf1a0940
-2026-06-18-compaction-capability-seam.zh.md: d8522f3714211f23bafb201e7354e8b0fc2f5fb1
+2026-06-18-compaction-capability-seam.md: 6357482600fabd0354325a19118ec245eee5d855
+2026-06-18-compaction-capability-seam.zh.md: a5c60c667734f119a8bd9d9b6a8fbc9c66155470
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index fa9325d08f..6357482600 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
@@ -14,7 +14,7 @@ Two forces shape the design. First, compaction policy and reusable token measure
 
 ## Decision
 
-### Compaction is a capability seam, split interface / implementation
+### Compaction is a capability seam with separate Service Definition and Service provider roles
 
 Per the [capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md), compaction ships as separate packages so the contract, the algorithm, and (later) the consumer surface evolve independently:
 
@@ -25,7 +25,7 @@ Per the [capability-seams Agent Note](../architecture/2026-06-13-capability-seam
 
 ### The contract depends on `dsh-session` and `dsh-llm` — a deliberate deviation
 
-The capability-seams Agent Note states the interface package "depends only on cordis" (true of `dsh-bash`, whose vocabulary is self-contained). Compaction **cannot** honor that: its verbs act on an agent-owned `Session` (`compactRegion(start, end, agent)`) and its output uses the content vocabulary (`CompactionResult.summary: ContentBlock[]`). There is no way to express the contract without naming `Session`/`SessionEvent` (from `dsh-session`) and `ContentBlock` (from `dsh-llm`).
+The capability-seams Agent Note states the Service Definition package "depends only on cordis" (true of `dsh-bash`, whose vocabulary is self-contained). Compaction **cannot** honor that: its verbs act on an agent-owned `Session` (`compactRegion(start, end, agent)`) and its output uses the content vocabulary (`CompactionResult.summary: ContentBlock[]`). There is no way to express the contract without naming `Session`/`SessionEvent` (from `dsh-session`) and `ContentBlock` (from `dsh-llm`).
 
 This is not a coupling smell — it is the contract's domain. The "only cordis" guidance was always shorthand for "the interface depends only on what the contract genuinely names, and never on an implementation." `dsh-session` and `dsh-llm` are themselves interface/vocabulary packages, not implementations; `dsh-compact` still imports no backend. The seam's real invariant — *consumers and implementations evolve independently behind an abstract service* — holds intact.
 
@@ -119,7 +119,7 @@ The lifecycle boundary makes crash state unambiguous:
 ## Consequences
 
 - **Packages**: `packages/compact/compact` supplies the interface, `compact-basic` supplies the backend, `compact-tool-result-prune` supplies optional deterministic rewriting, and `command-compact` supplies human `/compact`. `packages/llm/token-meter` owns replay-aware measurement independently.
-- **Automatic seams**: `agent/pre-step` (`@mode waterfall`) handles pressure before request derivation and `agent/request-error` (`@mode waterfall`) handles final request failures after the failed step closes. The pre-step payload carries the claimed batch, turn, step, and signal (see the [payload-object events decision](../architecture/2026-08-06-agent-event-payload-objects.md)), with no compaction-only prompt/prefix payload.
+- **Automatic extension points**: `agent/pre-step` (`@mode waterfall`) handles pressure before request derivation and `agent/request-error` (`@mode waterfall`) handles final request failures after the failed step closes. The pre-step payload carries the claimed batch, turn, step, and signal (see the [payload-object events decision](../architecture/2026-08-06-agent-event-payload-objects.md)), with no compaction-only prompt/prefix payload.
 - **`SessionEventMap`** gains `compact/start` / `compact/summary` / `compact/end` by declaration merging (merge-extensible); `SurfaceEventType` is **not** touched. These are session events, not cordis `Events`, so the event-taxonomy gate needs no entry.
 - **`dsh-compact`** owns `COMPACT_CHECKPOINT_SOURCE`, `isCompactCheckpointSource(source)`, `toolPairingBalancedBefore(session, seq)`, and `toolPairingBalancedAfter(session, seq)`. The marker identifies replacement summaries across backend implementations. The cached surface-edge checks prevent `compactRegion` and `compactIfNeeded` from splitting a tool-call/result pair, validate current membership by seq, answer both edges from one per-cut balance sequence, and reject stale or missing seqs and orphan results.
 - **`dsh-session`** validates positional replacement, complete cited source-event coverage, and content-only single-node `tool/result` rewrites through its one surface manager. Its invariant companion treats fresh appended tool results as executions that require an open step and pending call, while the compaction companion owns numeric-turn versus standalone-null bracket relations.
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index d8522f3714..a5c60c6677 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-### 压缩是一个能力 seam，接口与实现分离
+### 压缩是一个能力 seam，Service Definition 与 Service provider 角色分离
 
 遵循[能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)，压缩以独立包发布，使约定、算法和（后续的）消费方 surface 各自独立演进：
 
@@ -25,7 +25,7 @@ Status: implemented
 
 ### 约定依赖 `dsh-session` 和 `dsh-llm`——有意为之的偏离
 
-能力 seam Agent Note 规定接口包「仅依赖 cordis」（对 `dsh-bash` 成立，因为其词汇是自包含的）。压缩**无法**遵守这一点：它的动词作用于 agent 所有的 `Session`（`compactRegion(start, end, agent)`），其输出使用内容词汇（`CompactionResult.summary: ContentBlock[]`）。不引用 `Session`/`SessionEvent`（来自 `dsh-session`）和 `ContentBlock`（来自 `dsh-llm`），约定就无法表达。
+能力 seam Agent Note 规定 Service Definition 包「仅依赖 cordis」（对 `dsh-bash` 成立，因为其词汇是自包含的）。压缩**无法**遵守这一点：它的动词作用于 agent 所有的 `Session`（`compactRegion(start, end, agent)`），其输出使用内容词汇（`CompactionResult.summary: ContentBlock[]`）。不引用 `Session`/`SessionEvent`（来自 `dsh-session`）和 `ContentBlock`（来自 `dsh-llm`），约定就无法表达。
 
 这不是耦合异味，而是约定的领域所在。「仅 cordis」的指导原则一直是「接口仅依赖约定真正需要命名的东西，绝不依赖实现」的简写。`dsh-session` 和 `dsh-llm` 本身是接口/词汇包，不是实现；`dsh-compact` 仍然不导入任何后端。seam 的真正不变式——*消费方和实现在抽象服务背后独立演进*——完好无损。
 
@@ -33,7 +33,7 @@ Status: implemented
 
 早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将约定重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
 
-`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV Cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
+`compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
 
 ### 成功的持久步骤工作完成后运行自动压力检查
 
@@ -119,7 +119,7 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 ## 后果
 
 - **包**：`packages/compact/compact` 提供接口，`compact-basic` 提供后端，`compact-tool-result-prune` 提供可选的确定性重写，`command-compact` 提供面向用户的 `/compact`。`packages/llm/token-meter` 独立拥有回放感知的测量。
-- **自动 seam**：`agent/pre-step`（`@mode waterfall`）在请求派生前处理压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。pre-step 的 payload 携带已领取批次、轮次、步骤与 signal（参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)），不携带压缩专属的提示词/前缀 payload。
+- **自动扩展点**：`agent/pre-step`（`@mode waterfall`）在请求派生前处理压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。pre-step 的 payload 携带已领取批次、轮次、步骤与 signal（参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)），不携带压缩专属的提示词/前缀 payload。
 - **`SessionEventMap`** 通过可合并扩展的声明合并获得 `compact/start` / `compact/summary` / `compact/end`；`SurfaceEventType` **未被**触及。这些是会话事件，不是 cordis `Events`，因此事件分类门禁无需新增条目。
 - **`dsh-compact`** 拥有 `COMPACT_CHECKPOINT_SOURCE`、`isCompactCheckpointSource(source)`、`toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`。该标记用于跨后端实现识别替换摘要。带缓存的 surface 边缘检查会防止 `compactRegion` 和 `compactIfNeeded` 拆分工具调用/结果对，按 seq 校验当前成员关系，从每个切割点的一条平衡序列回答两侧边缘，并拒绝陈旧或缺失的 seq 与孤立结果。
 - **`dsh-session`** 通过唯一的 surface 管理器校验位置替换、引用的来源事件是否覆盖完整，以及仅内容的单节点 `tool/result` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用，而压缩配套组件拥有数字轮次归属与独立 `null` 归属标记对之间的关系。
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index 45dc5edb5c..ac018acdc8 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.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 .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
-2026-06-21-subagent-capability-seam.md: 752e639b09ea2ac0ba19841ddfe38b15b44d22e9
-2026-06-21-subagent-capability-seam.zh.md: f0b0ba2ab8b0bb7b611e995c56e30db68b21cfa7
+2026-06-21-subagent-capability-seam.md: 553411a0d8f989c883e3eea929669ccebcfe807b
+2026-06-21-subagent-capability-seam.zh.md: 5fa2bd62828e9afcb79647ec4821c2da1da041e7
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
index 752e639b09..553411a0d8 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -14,18 +14,18 @@ The distinctive requirement — the one that shapes the whole design — is that
 
 - **in-process** — a child concrete `Agent` on the same `Context` (the cheapest, and nearly free given the existing agent factory);
 - **ACP** — act as an ACP *client* driving another agent process (which can be another instance of ourselves);
-- **Codex app-server and Claude Code Agent SDK** — current one-shot siblings that apply the same named-provider seam to official product processes ([product-provider Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md));
+- **Codex app-server and Claude Code Agent SDK** — current one-shot siblings that apply the same named-provider contract to official product processes ([product-provider Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md));
 - later: **A2A** using the same out-of-process "start a child, prompt it, settle, cancel" shape.
 
 ## Alternatives considered
 
 ### Why not the bash seam shape
 
-The bash seam ([capability seams](../architecture/2026-06-13-capability-seams.md)) registers exactly one `BashExecutor` per context; loading a second throws. That is correct for bash (one machine, one way to run a command) but wrong here: coexistence is the requirement. So the subagent service is a **named-provider registry** — each implementation registers under a unique name and a caller picks one by name — mirroring the **LLM adapter registry** (`LlmService.registerAdapter`), not the single-service bash executor. The seam is still three-package (interface / implementation / consumer); only the "one vs. many implementations" axis differs.
+The bash seam ([capability seams](../architecture/2026-06-13-capability-seams.md)) registers exactly one `BashExecutor` per context; loading a second throws. That is correct for bash (one machine, one way to run a command) but wrong here: coexistence is the requirement. So the subagent service is a **named-provider registry** — each implementation registers under a unique name and a caller picks one by name — mirroring the **LLM adapter registry** (`LlmService.registerAdapter`), not the single-service bash executor. The seam is still three-package (Service Definition / Service provider / Consumer); only the "one vs. many implementations" axis differs.
 
 ## Decision
 
-### The three-package seam
+### The three-package boundary
 
 A new package group `packages/subagent/`:
 
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index f0b0ba2ab8..5fa2bd6282 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -14,18 +14,18 @@ harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent 将工
 
 - **进程内**：在同一个 `Context` 上创建一个具体的子 `Agent`（最廉价，且鉴于现有 agent 工厂几乎零成本）；
 - **ACP**：作为 ACP *客户端*驱动另一个 agent 进程（可以是自身的另一个实例）；
-- **Codex app-server 与 Claude Code Agent SDK**：当前的一次性同类提供方，将同一个命名提供方 seam 应用于官方产品进程（[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）；
+- **Codex app-server 与 Claude Code Agent SDK**：当前的一次性同类提供方，将同一个命名提供方约定应用于官方产品进程（[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）；
 - 后续：**A2A**，采用同样的进程外形态：「启动子 agent、发送提示词、结算、取消」。
 
 ## 曾考虑的替代方案
 
 ### 为何不采用 bash seam 的形状
 
-bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个上下文中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（接口、实现、消费方）；只是「一个 vs. 多个实现」这个维度不同。
+bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个上下文中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（Service Definition / Service provider / Consumer）；只是「一个 vs. 多个实现」这个维度不同。
 
 ## 决策
 
-### 由三个包构成的 seam
+### 由三个包构成的边界
 
 新建包组 `packages/subagent/`：
 
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
index e55d06834c..4cf94795a8 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.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 .agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
-2026-06-22-acp-subagent-backend.md: c994ebfa69649bb9e79d3aa389a0e13c178131c7
-2026-06-22-acp-subagent-backend.zh.md: 79be03dfc8310f6fc759d620c36d0d279c703073
+2026-06-22-acp-subagent-backend.md: 211030a6ecc9b6f673174ba410415c7bd80818ef
+2026-06-22-acp-subagent-backend.zh.md: 2dde3d96329cc47d9c7cca08e1d25764c32f8ebe
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
index c994ebfa69..211030a6ec 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
@@ -59,4 +59,4 @@ Every run pays a fresh subprocess (spawn + `initialize` + `newSession`). The par
 
 ## Product-provider siblings
 
-The [Codex app-server and Claude Code Agent SDK providers](2026-08-04-claude-code-and-codex-subagent-backends.md) apply the same out-of-process spawn/prompt/settle/cancel boundary as siblings registered by name. A2A remains a future sibling transport; the ACP backend proves that the common seam supports this boundary without owning product-private protocols.
+The [Codex app-server and Claude Code Agent SDK providers](2026-08-04-claude-code-and-codex-subagent-backends.md) apply the same out-of-process spawn/prompt/settle/cancel boundary as siblings registered by name. A2A remains a future sibling transport; the ACP backend proves that the subagent seam supports this boundary without owning product-private protocols.
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
index 79be03dfc8..2dde3d9632 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
@@ -59,4 +59,4 @@ ACP `StopReason` → harness `SubagentStopReason`：`end_turn`→`completed`、`
 
 ## 兄弟产品提供方
 
-[Codex app-server 与 Claude Code Agent SDK 提供方](2026-08-04-claude-code-and-codex-subagent-backends.md)作为按名称注册的兄弟提供方，采用同样的进程外启动/提示词/结算/取消边界。A2A 仍是未来的兄弟传输方式；ACP 后端证明了通用 seam 能够支持这项边界，而无需负责产品私有协议。
+[Codex app-server 与 Claude Code Agent SDK 提供方](2026-08-04-claude-code-and-codex-subagent-backends.md)作为按名称注册的兄弟提供方，采用同样的进程外启动/提示词/结算/取消边界。A2A 仍是未来的兄弟传输方式；ACP 后端证明了 subagent seam 能够支持这项边界，而无需负责产品私有协议。
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
index de978c055c..96e76345cc 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.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 .agents/notes/implemented/feature/2026-06-30-hook-bridges.md
-2026-06-30-hook-bridges.md: a31116818c57e18d04e656f371efd1101a63b6af
-2026-06-30-hook-bridges.zh.md: 0fa76c0cee0f74101e70f44d442daa2fb46e6649
+2026-06-30-hook-bridges.md: eecc1fc75c10618481231083f890e0e4b122c1ee
+2026-06-30-hook-bridges.zh.md: dcc8f496cb3bc6ea7857ce804a9159cbfcbc3f08
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.md b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.md
index a31116818c..eecc1fc75c 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.md
@@ -6,9 +6,9 @@ English | [中文](2026-06-30-hook-bridges.zh.md)
 
 ## Problem
 
-The harness's extension surface is its typed interception seams ([the interception-seams Agent Note](2026-06-30-interception-seams.md)): a "native hook" is just an ordinary cordis plugin subscribing to `agent/session-start`, `agent/pre-step`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-stopping`, `subagent/start`, or `subagent/end`. But users arrive with **existing** Claude Code (CC) and Codex hook configs — a `hooks.json` (or a settings file's `hooks` key) full of shell-command hooks — and want those to run unmodified. This Agent Note introduces the two **bridge plugins** that translate that external shell-hook protocol onto the typed seams, built on the shared wire-protocol library ([the hook-protocol-lib Agent Note](2026-06-30-hook-protocol-lib.md)).
+The harness's extension surface is its typed interception points ([the interception extension-points Agent Note](2026-06-30-interception-extension-points.md)): a "native hook" is just an ordinary cordis plugin subscribing to `agent/session-start`, `agent/pre-step`, `tools/pre-execute`, `tools/post-execute`, `agent/turn-stopping`, `subagent/start`, or `subagent/end`. But users arrive with **existing** Claude Code (CC) and Codex hook configs — a `hooks.json` (or a settings file's `hooks` key) full of shell-command hooks — and want those to run unmodified. This Agent Note introduces the two **bridge plugins** that translate that external shell-hook protocol onto the typed extension points, built on the shared wire-protocol library ([the hook-protocol-lib Agent Note](2026-06-30-hook-protocol-lib.md)).
 
-The framing that shapes the whole design: **a bridge is a compatibility adapter, not a power tool.** Anything a bridge does (block a tool, inject context, force continuation, observe a subagent) a native cordis plugin does more powerfully — typed returns, full `ctx`, no serialization boundary. The bridge's reason to exist is to run the explicitly supported subset of external CC/Codex command hooks. That keeps each bridge thin: parse the config, pick a matcher mode, build the per-event payload, call `runHook` + `mergeHookOutputs` from the shared lib, and map the neutral outcome onto a seam Decision. The package READMEs own the exact current unsupported-event and partial-field inventory against the official protocols.
+The framing that shapes the whole design: **a bridge is a compatibility adapter, not a power tool.** Anything a bridge does (block a tool, inject context, force continuation, observe a subagent) a native cordis plugin does more powerfully — typed returns, full `ctx`, no serialization boundary. The bridge's reason to exist is to run the explicitly supported subset of external CC/Codex command hooks. That keeps each bridge thin: parse the config, pick a matcher mode, build the per-event payload, call `runHook` + `mergeHookOutputs` from the shared lib, and map the neutral outcome to a typed Decision. The package READMEs own the exact current unsupported-event and partial-field inventory against the official protocols.
 
 ## Decision
 
@@ -19,9 +19,9 @@ Two independent plugins in the `packages/hooks/` group, each a function/namespac
 
 ### Outcome → Decision mapping
 
-Each bridge maps the neutral `MergedHookOutcome` from the shared lib onto the seam's typed Decision:
+Each bridge maps the neutral `MergedHookOutcome` from the shared lib onto each extension point's typed Decision:
 
-| Seam | CC | Codex |
+| Extension point | CC | Codex |
 |---|---|---|
 | `agent/session-start` (emit) | additionalContext → `agent.inject()` | plain-stdout output → additionalContext → `agent.inject()` |
 | `agent/pre-step` | `deny`→`reject`; context-only→delegate+fold into `enter` | `block`→`reject`; context-only→delegate+fold into `enter` |
@@ -59,9 +59,9 @@ Hooks run in the agent's session workspace, so relative paths target the user's
 
 - **Tool-input rewrite.** A CC/Codex `updatedInput` is logged + warned, not honored — input rewrite is a deferred consistency-design problem ([the pre-tool-input-rewrite Agent Note](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)), because the pre-execution args are read by `tool/call` audit + `assistant/message` history + tool presentation, so an honest rewrite is a design unit, not a field.
 - **Stop loop-guard** (`TODO(stop-loop-guard)`). Claude Code supplies `stop_hook_active` and overrides a hook after eight consecutive blocks; Codex supplies `stop_hook_active` but documents no equivalent cap. Both bridges always report `false`, so a Stop hook that unconditionally blocks force-continues every step — a hook author must self-limit until state tracking lands.
-- **Hook `continue:false` (hard halt).** A hook can ask to halt the whole run (CC/Codex `continue:false`); the shared merge folds it into `MergedHookOutcome.stop`/`stopReason`, but no bridge acts on it (`TODO(hook-continue-false)`) — the interception seams have no "hard-halt the agent" primitive yet (a Decision blocks/steers a single point, not the run). Deferred with the loop-guard work; mid-turn requests record the halt in `hook/result`, and the hook keeps its per-point effect (decision/context) meanwhile.
+- **Hook `continue:false` (hard halt).** A hook can ask to halt the whole run (CC/Codex `continue:false`); the shared merge folds it into `MergedHookOutcome.stop`/`stopReason`, but no bridge acts on it (`TODO(hook-continue-false)`) — the interception points have no "hard-halt the agent" primitive yet (a Decision blocks/steers a single point, not the run). Deferred with the loop-guard work; mid-turn requests record the halt in `hook/result`, and the hook keeps its per-point effect (decision/context) meanwhile.
 - **Config discovery.** The path is explicit in `cordis.yml` and process-level (see above); the full multi-layer CC/Codex precedence walk, per-session project-local discovery, and the trust/hash model are not reimplemented (`TODO(per-session-hook-config)`).
-- **Session-start / subagent-start context is best-effort (`TODO(session-start-gating)`).** Both hooks run detached from startup, so their context is injected when ready but may miss the first request or a short-lived child. Guaranteeing first-request delivery requires an awaited startup seam.
+- **Session-start / subagent-start context is best-effort (`TODO(session-start-gating)`).** Both hooks run detached from startup, so their context is injected when ready but may miss the first request or a short-lived child. Guaranteeing first-request delivery requires an awaited startup extension point.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
index 0fa76c0cee..dcc8f496cb 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
@@ -6,9 +6,9 @@ Status: implemented
 
 ## 问题
 
-harness 的扩展面是其类型化的拦截 seam（见[拦截 seam Agent Note](2026-06-30-interception-seams.md)）：所谓「原生钩子」不过是一个普通的 Cordis 插件，订阅 `agent/session-start`、`agent/pre-step`、`tools/pre-execute`、`tools/post-execute`、`agent/turn-stopping`、`subagent/start` 或 `subagent/end`。但用户带着**既有的** Claude Code（CC）和 Codex 钩子配置到来，一个 `hooks.json`（或 settings 文件中的 `hooks` 键）里满是 shell 命令钩子，并希望它们原样运行。本 Agent Note 引入两个**桥接插件**，将外部 shell 钩子协议翻译到类型化 seam 上，构建于共享的协议格式（wire format）库之上（见 [hook-protocol-lib Agent Note](2026-06-30-hook-protocol-lib.md)）。
+harness 的扩展面是其类型化拦截点（见[拦截扩展点 Agent Note](2026-06-30-interception-extension-points.md)）：所谓「原生钩子」不过是一个普通的 Cordis 插件，订阅 `agent/session-start`、`agent/pre-step`、`tools/pre-execute`、`tools/post-execute`、`agent/turn-stopping`、`subagent/start` 或 `subagent/end`。但用户带着**既有的** Claude Code（CC）和 Codex 钩子配置到来，一个 `hooks.json`（或 settings 文件中的 `hooks` 键）里满是 shell 命令钩子，并希望它们原样运行。本 Agent Note 引入两个**桥接插件**，将外部 shell 钩子协议翻译到类型化扩展点上，构建于共享的协议格式（wire format）库之上（见 [hook-protocol-lib Agent Note](2026-06-30-hook-protocol-lib.md)）。
 
-贯穿整个设计的定位：**桥接是兼容性适配器，不是高级工具。** 桥接能做的事（阻止工具、注入上下文、强制继续、观察 subagent），原生 Cordis 插件都能做得更强——类型化返回值、完整 `ctx`、无序列化边界。桥接存在的理由是运行外部 CC/Codex 命令钩子中被明确支持的子集。这使每个桥接保持精简：解析配置、选择匹配模式、构建每事件的 payload、调用共享库的 `runHook` + `mergeHookOutputs`，再将中性结果映射为 seam Decision。各包的 README 维护着当前不支持的事件和部分字段的完整清单，以官方协议为参照。
+贯穿整个设计的定位：**桥接是兼容性适配器，不是高级工具。** 桥接能做的事（阻止工具、注入上下文、强制继续、观察 subagent），原生 Cordis 插件都能做得更强——类型化返回值、完整 `ctx`、无序列化边界。桥接存在的理由是运行外部 CC/Codex 命令钩子中被明确支持的子集。这使每个桥接保持精简：解析配置、选择匹配模式、构建每事件的 payload、调用共享库的 `runHook` + `mergeHookOutputs`，再将中性结果映射为类型化 Decision。各包的 README 维护着当前不支持的事件和部分字段的完整清单，以官方协议为参照。
 
 ## 决策
 
@@ -19,9 +19,9 @@ harness 的扩展面是其类型化的拦截 seam（见[拦截 seam Agent Note](
 
 ### Outcome → Decision 映射
 
-每个桥接将共享库返回的中性 `MergedHookOutcome` 映射到 seam 的类型化 Decision：
+每个桥接将共享库返回的中性 `MergedHookOutcome` 映射到各扩展点的类型化 Decision：
 
-| Seam | CC | Codex |
+| 扩展点 | CC | Codex |
 |---|---|---|
 | `agent/session-start`（emit） | additionalContext → `agent.inject()` | 纯 stdout 输出 → additionalContext → `agent.inject()` |
 | `agent/pre-step` | `deny`→`reject`；仅上下文→委托并折叠到 `enter` | `block`→`reject`；仅上下文→委托并折叠到 `enter` |
@@ -59,9 +59,9 @@ Claude Code 始终导出 `CLAUDE_PROJECT_DIR`，常见的未修改钩子引用 `
 
 - **工具输入重写。** CC/Codex 的 `updatedInput` 被记录日志并发出警告，但不予执行——输入重写是一个推迟的一致性设计问题（见 [pre-tool-input-rewrite Agent Note](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)），因为 pre-execution 参数被 `tool/call` 审计、`assistant/message` 历史和工具展示共同读取，诚实的重写是一个设计单元，而非一个字段。
 - **Stop 循环防护**（`TODO(stop-loop-guard)`）。Claude Code 提供 `stop_hook_active` 并在连续八次阻塞后覆盖钩子；Codex 提供 `stop_hook_active` 但未记录等效上限。两个桥接始终报告 `false`，因此一个无条件阻塞的 Stop 钩子会在每一步强制继续——在状态追踪落地之前，钩子作者必须自行限制。
-- **钩子 `continue:false`（硬停止）。** 钩子可以请求终止整个运行（CC/Codex `continue:false`）；共享合并将其折叠为 `MergedHookOutcome.stop`/`stopReason`，但没有桥接对其采取行动（`TODO(hook-continue-false)`）——拦截 seam 尚无「硬停止 agent」原语（Decision 阻塞/引导的是单个点，而非整个运行）。与循环防护工作一同推迟；轮中请求会将停止请求记录在 `hook/result` 中，钩子在此期间保留其逐点效果（决策/上下文）。
+- **钩子 `continue:false`（硬停止）。** 钩子可以请求终止整个运行（CC/Codex `continue:false`）；共享合并将其折叠为 `MergedHookOutcome.stop`/`stopReason`，但没有桥接对其采取行动（`TODO(hook-continue-false)`）——拦截点尚无「硬停止 agent」原语（Decision 阻塞/引导的是单个点，而非整个运行）。与循环防护工作一同推迟；轮中请求会将停止请求记录在 `hook/result` 中，钩子在此期间保留其逐点效果（决策/上下文）。
 - **配置发现。** 路径在 `cordis.yml` 中显式指定且为进程级（见上文）；完整的多层 CC/Codex 优先级遍历、按会话的项目本地发现以及信任/hash 模型未被重新实现（`TODO(per-session-hook-config)`）。
-- **Session-start / subagent-start 上下文为尽力而为（`TODO(session-start-gating)`）。** 两个钩子以 detached 方式运行，不阻塞启动流程，因此其上下文在就绪时注入，但可能错过首个请求或短命的 subagent。要保证首请求送达，需要一个 awaited 的启动 seam。
+- **Session-start / subagent-start 上下文为尽力而为（`TODO(session-start-gating)`）。** 两个钩子以 detached 方式运行，不阻塞启动流程，因此其上下文在就绪时注入，但可能错过首个请求或短命的 subagent。要保证首请求送达，需要一个 awaited 的启动扩展点。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
index b5b5ea3b97..547f88999e 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.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 .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
-2026-06-30-hook-protocol-lib.md: 2edff0d501cd7695873c68054eeb3a1e9942eced
-2026-06-30-hook-protocol-lib.zh.md: 90648c535e8bccd264ef9ae1ffd5f66590b1ac6d
+2026-06-30-hook-protocol-lib.md: 576a126e1022ac72265c476e03ef36aaf17f78b4
+2026-06-30-hook-protocol-lib.zh.md: f2554eaa378a26bf8254d86d458e0de5ce1aa4fd
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
index 2edff0d501..576a126e10 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
@@ -21,7 +21,7 @@ A new `packages/hooks/` group with `hook-protocol` as a pure library. It owns fo
 - **Merge** — `mergeHookOutputs(outputs)`, folding multiple matched hooks into one most-restrictive `MergedHookOutcome`: permission precedence **deny > ask > allow**, halt sticky on the first `continue:false`, block reasons joined `\n\n`, context/system-messages accumulated in order.
 - **`hook/*` session events** — `hook/invoked` / `hook/result`, declaration-merged into `SessionEventMap` (log-only, like `compact/*` — NOT `SurfaceEventType`s), with `appendHookInvoked`/`appendHookResult` helpers so the invoked/result pairing and owner-defined execution relation stay consistent across bridges. `appendHookResult` also owns the durable record's semantics — the decision string (the hook's parsed decision, else `'stop'` on `continue:false`, else `'pass'`) and the 500-character `stderrSummary` truncation derive from the `HookOutput` here, not per-bridge.
 
-**Per-dialect (the bridge plugins):** building each event's stdin payload (CC's base+per-event field sets vs Codex's snake_case with `turn_id`/`model` extras), the dialect's env + `${CLAUDE_PLUGIN_ROOT}` substitution (CC) vs none (Codex), and mapping the neutral `HookOutput`/`MergedHookOutcome` onto the harness's seam-specific typed Decisions (`PreToolDecision`, `PreStepDecision`, `ContinuationDecision`, `PostToolDecision`).
+**Per-dialect (the bridge plugins):** building each event's stdin payload (CC's base+per-event field sets vs Codex's snake_case with `turn_id`/`model` extras), the dialect's env + `${CLAUDE_PLUGIN_ROOT}` substitution (CC) vs none (Codex), and mapping the neutral `HookOutput`/`MergedHookOutcome` onto the harness's extension-point-specific typed Decisions (`PreToolDecision`, `PreStepDecision`, `ContinuationDecision`, `PostToolDecision`).
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
index 90648c535e..f2554eaa37 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 - **合并** — `mergeHookOutputs(outputs)`，将多个匹配钩子的输出折叠为一个最严格的 `MergedHookOutcome`：权限优先级 **deny > ask > allow**，halt 在首个 `continue:false` 时粘滞，阻止原因以 `\n\n` 拼接，context/system-messages 按序累积。
 - **`hook/*` 会话事件** — `hook/invoked` / `hook/result`，通过声明合并进入 `SessionEventMap`（仅日志，如 `compact/*`——不是 `SurfaceEventType`），配有 `appendHookInvoked`/`appendHookResult` 辅助函数，确保 invoked/result 配对与由所有者定义的执行关系在各桥接插件间保持一致。`appendHookResult` 还负责定义持久化记录的语义：decision 字符串（钩子解析出的 decision，否则 `continue:false` 时为 `'stop'`，否则为 `'pass'`）和 500 字符的 `stderrSummary` 截断均从本库的 `HookOutput` 派生，而非各桥接插件各自实现。
 
-**方言专属（桥接插件）：** 构建每个事件的 stdin payload（CC 的 base+per-event 字段集 vs Codex 的 snake_case 加 `turn_id`/`model` 额外字段）、方言的 env 与 `${CLAUDE_PLUGIN_ROOT}` 替换（CC）vs 两者皆无（Codex），以及将方言无关的 `HookOutput`/`MergedHookOutcome` 映射为 harness seam 专属的类型化 Decision（`PreToolDecision`、`PreStepDecision`、`ContinuationDecision`、`PostToolDecision`）。
+**方言专属（桥接插件）：** 构建每个事件的 stdin payload（CC 的 base+per-event 字段集 vs Codex 的 snake_case 加 `turn_id`/`model` 额外字段）、方言的 env 与 `${CLAUDE_PLUGIN_ROOT}` 替换（CC）vs 无替换（Codex），以及将方言无关的 `HookOutput`/`MergedHookOutcome` 映射为 harness 各扩展点专属的类型化 Decision（`PreToolDecision`、`PreStepDecision`、`ContinuationDecision`、`PostToolDecision`）。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.i18n.yaml
similarity index 56%
rename from .agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
rename to .agents/notes/implemented/feature/2026-06-30-interception-extension-points.i18n.yaml
index b436887b7a..6955ae64a6 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.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 .agents/notes/implemented/feature/2026-06-30-interception-seams.md
-2026-06-30-interception-seams.md: 3b2c62cd4413f6d93cef247c51304a8d46753218
-2026-06-30-interception-seams.zh.md: 110b28d48a342b50f8e5c1024ed2f2df704e4099
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
+2026-06-30-interception-extension-points.md: 68be3c94f55ae13155e9b22cb91ef1ad10b1e0ed
+2026-06-30-interception-extension-points.zh.md: 262793dd7a297f343391a22fb8d9f1d57a9ff531
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
similarity index 83%
rename from .agents/notes/implemented/feature/2026-06-30-interception-seams.md
rename to .agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
index 3b2c62cd44..68be3c94f5 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md
@@ -1,18 +1,18 @@
-# Agent Note: Interception seams — the typed-Decision surface a hook programs against
+# Agent Note: Interception extension points — the typed-Decision surface a hook programs against
 
 Status: implemented
 
-English | [中文](2026-06-30-interception-seams.zh.md)
+English | [中文](2026-06-30-interception-extension-points.zh.md)
 
 ## Problem
 
 The harness needs a hooks subsystem: users extend or gate the agent at lifecycle points the way Claude Code (CC) and Codex do. The key reframe driving this design is that **"native hooks" are not a package** — a native hook is just an ordinary Cordis plugin subscribing to the canonical lifecycle events. So the real product is a *powerful, well-typed canonical event surface*; the CC/Codex bridges (the `dsh-hooks-claude` / `dsh-hooks-codex` packages) are merely translators that map an external shell-hook protocol onto that same surface. Anything a bridge can do, a plain plugin can do directly — more powerfully (no serialization boundary, full `ctx`, typed returns).
 
-The surface needs distinct contracts for per-prompt policy (CC's `UserPromptSubmit`), session-start observation (CC's `SessionStart`), pre-tool policy, around-dispatch control, post-tool transformation, final-result observation, and continuation with a model-facing reason. Conflating those phases gives plugins mutation channels they do not need and makes finality depend on listener ordering. The [event-domain-semantics Agent Note](../architecture/2026-06-30-event-domain-semantics.md) supplies the three-domain rule and the typed-Decision idiom; this Agent Note applies them to the lifecycle seams.
+The surface needs distinct contracts for per-prompt policy (CC's `UserPromptSubmit`), session-start observation (CC's `SessionStart`), pre-tool policy, around-dispatch control, post-tool transformation, final-result observation, and continuation with a model-facing reason. Conflating those phases gives plugins mutation channels they do not need and makes finality depend on listener ordering. The [event-domain-semantics Agent Note](../architecture/2026-06-30-event-domain-semantics.md) supplies the three-domain rule and the typed-Decision idiom; this Agent Note applies them to the lifecycle extension points.
 
 ## Decision
 
-The canonical surface separates transformable policy, around-dispatch control, and observe-only notification. Policy waterfalls return small seam-specific **typed Decision unions**; wrappers return normalized results; notifications receive immutable snapshots and cannot affect the outcome. The set covers the hook points in scope (`session-start`, `prompt-submit`, `pre-tool`, `post-tool`, `stop`-via-continuation) while leaving non-hook execution policy independently composable.
+The canonical surface separates transformable policy, around-dispatch control, and observe-only notification. Policy waterfalls return small extension-point-specific **typed Decision unions**; wrappers return normalized results; notifications receive immutable snapshots and cannot affect the outcome. The set covers the hook points in scope (`session-start`, `prompt-submit`, `pre-tool`, `post-tool`, `stop`-via-continuation) while leaving non-hook execution policy independently composable.
 
 **Agent events** (`dsh-agent`):
 - `agent/session-start({ agent, source })` — emit, once before turn 1, carrying a `SessionStartSource` (`startup` for a fresh/forked create, `resume` for a reloaded persisted session; `clear`/`compact` reserved). A pure notification — it CANNOT block startup (a deliberate gap: a bridge logs/injects, it does not gate startup). A listener seeds context via `agent.inject()`.
@@ -47,12 +47,12 @@ Core dispatch and the tool body sit inside normalization boundaries, so tool, li
 
 ### Boundaries
 
-The seam package does **not** declare `hook/*` session events (the durable hook-invocation log); those belong to `dsh-hook-protocol`, because a native plugin uses typed decisions without an external hook log. The native-plugin integration test (`packages/core/agent-loop/tests/interception.spec.ts`) composes the seams through the real loop with no `hook/*` protocol. Compaction (`PreCompact`/`PostCompact`), Notification, and Codex `PermissionRequest` remain outside this decision. The [approval seam](2026-07-06-approval-seam.md) resolves `ask` decisions through `ctx.approval`; terminal monotonic stopping is expressed by tool-result data, while `agent/turn-stopping` is the last chance to steer another step.
+The Service Definition package does **not** declare `hook/*` session events (the durable hook-invocation log); those belong to `dsh-hook-protocol`, because a native plugin uses typed decisions without an external hook log. The native-plugin integration test (`packages/core/agent-loop/tests/interception.spec.ts`) composes the extension points through the real loop with no `hook/*` protocol. Compaction (`PreCompact`/`PostCompact`), Notification, and Codex `PermissionRequest` remain outside this decision. The [approval seam](2026-07-06-approval-seam.md) resolves `ask` decisions through `ctx.approval`; terminal monotonic stopping is expressed by tool-result data, while `agent/turn-stopping` is the last chance to steer another step.
 
 ## Alternatives considered
 
-- **Shipping pre-tool INPUT rewrite as part of this seam set** — deferred as the over-reach signal; the section above carries the consistency problem (audit, history, and presentation all read `tool/call.arguments` logged before execution), and [the pre-tool input-rewrite proposal](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md) owns the design.
-- **Declaring the durable `hook/*` SessionEvents alongside the seams** — rejected: a native plugin uses the typed Decisions with no hook log at all (the worked example proves it), so the durable log belongs to [the hook-protocol library](2026-06-30-hook-protocol-lib.md), not the seam surface.
+- **Shipping pre-tool INPUT rewrite as part of this extension-point set** — deferred as the over-reach signal; the section above carries the consistency problem (audit, history, and presentation all read `tool/call.arguments` logged before execution), and [the pre-tool input-rewrite proposal](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md) owns the design.
+- **Declaring the durable `hook/*` SessionEvents alongside the extension points** — rejected: a native plugin uses the typed Decisions with no hook log at all (the worked example proves it), so the durable log belongs to [the hook-protocol library](2026-06-30-hook-protocol-lib.md), not the extension surface.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.zh.md
similarity index 76%
rename from .agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
rename to .agents/notes/implemented/feature/2026-06-30-interception-extension-points.zh.md
index 110b28d48a..262793dd7a 100644
--- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-interception-extension-points.zh.md
@@ -1,22 +1,22 @@
-# Agent Note: 拦截 seam——钩子编程所面对的类型化 Decision 表面
+# Agent Note: 拦截扩展点——钩子编程所面对的类型化 Decision 表面
 
 Status: implemented
 
-[English](2026-06-30-interception-seams.md) | 中文
+[English](2026-06-30-interception-extension-points.md) | 中文
 
 ## 问题
 
 harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那样在生命周期节点扩展或管控 agent（智能体）。驱动本设计的关键视角转换是：**「原生钩子」不是一个包**——原生钩子只是一个普通的 Cordis 插件，订阅规范的生命周期事件。因此真正的产品是一个*强大、类型完备的规范事件表面*；CC/Codex 桥接（`dsh-hooks-claude` / `dsh-hooks-codex` 包）只是将外部 shell 钩子协议映射到同一表面的翻译层。桥接能做的事，普通插件可以直接做——而且更强大（无序列化边界、完整 `ctx`、类型化返回值）。
 
-该表面需要为以下场景提供各自独立的约定：逐提示词策略（CC 的 `UserPromptSubmit`）、会话启动观测（CC 的 `SessionStart`）、工具执行前策略、环绕调度控制、工具执行后变换、最终结果观测，以及携带面向模型的原因的继续执行。如果把这些阶段混为一谈，插件就会获得不需要的 mutation 通道，而终结性将依赖监听器的注册顺序。[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 提供了三域规则与类型化 Decision 惯用法；本 Agent Note 将其应用于生命周期 seam。
+该表面需要为以下场景提供各自独立的约定：逐提示词策略（CC 的 `UserPromptSubmit`）、会话启动观测（CC 的 `SessionStart`）、工具执行前策略、环绕调度控制、工具执行后变换、最终结果观测，以及携带面向模型的原因的继续执行。如果把这些阶段混为一谈，插件就会获得不需要的 mutation 通道，而终结性将依赖监听器的注册顺序。[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 提供了三域规则与类型化 Decision 惯用法；本 Agent Note 将其应用于生命周期扩展点。
 
 ## 决策
 
-规范表面将可变换策略、环绕调度控制与仅观测通知分离。策略 waterfall（瀑布式事件）返回小型的、seam 专属的**类型化 Decision 联合类型**；包装层返回规范化结果；通知接收不可变快照，无法影响结果。覆盖的钩子点包括 `session-start`、`prompt-submit`、`pre-tool`、`post-tool`、通过 continuation 实现的 `stop`，同时将非钩子的执行策略留作独立可组合。
+规范表面将可变换策略、环绕调度控制与仅观测通知分离。策略 waterfall（瀑布式事件）返回小型的、扩展点专属的**类型化 Decision 联合类型**；包装层返回规范化结果；通知接收不可变快照，无法影响结果。覆盖的钩子点包括 `session-start`、`prompt-submit`、`pre-tool`、`post-tool`、通过 continuation 实现的 `stop`，同时将非钩子的执行策略留作独立可组合。
 
 **Agent 事件**（`dsh-agent`）：
 - `agent/session-start({ agent, source })` ——emit，在第 1 轮次之前触发一次，携带 `SessionStartSource`（`startup` 表示全新/fork 创建，`resume` 表示重新加载的持久化会话；`clear`/`compact` 保留）。纯通知，不能阻塞启动（这是有意的空白：桥接可以记录/注入，但不管控启动）。监听器通过 `agent.inject()` 注入上下文。
-- `agent/pre-step({ agent, messages, turn, step, signal }, next) → PreStepDecision` ——waterfall，在每个拟议步骤之前、循环原子移除其独占 inbox 批次后触发。payload 携带该请求的 `turn`、`step` 与取消 `signal`（已退役的 `PreStepContext` 字段位于 payload 中；参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)）；没有中途输入的工具续步中，`messages` 为空。`enter` 返回完整消息批次，其中包括监听器为当前请求贡献的上下文；`reject` 不打开步骤，并让已领取消息保持移除状态。
+- `agent/pre-step({ agent, messages, turn, step, signal }, next) → PreStepDecision` ——waterfall，在每个拟议步骤之前、循环原子移除其独占 inbox 批次后触发。payload 携带该请求的 `turn`、`step` 与取消 `signal`（已退役的 `PreStepContext` 字段位于 payload 中；参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)）；没有中途输入的工具续步会收到空批次。`enter` 返回完整消息批次，其中包括监听器为当前请求贡献的上下文；`reject` 不打开步骤，并让已领取消息保持已删除。
 
 **`agent/turn-stopping`** 是自然停止边界上的一次 awaited 通知。需要再执行一步的监听器调用 `agent.steer()`，传入来源显式的 steering（中途引导）内容供模型使用；循环随后重新读取 outbox，继续执行或关闭轮次。
 
@@ -35,7 +35,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 
 ### 三个承重的循环决策
 
-1. **在每个拟议步骤运行 pre-step 策略。** 循环会在首次领取和决策之前打开轮次，因此 reject 会关闭一个持久、blocked 且不含步骤或模型可见消息的轮次。即使工具续步没有新取得所有权的输入，也会提交空批次，使逐请求上下文生产方可以把会记录到日志中的消息加入这一次请求。enter 时，循环先开启步骤，再把返回批次作为 `user/message` 追加，然后派生请求。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个已领取 follow-up 仍是其轮次中唯一的直接提示词。
+1. **在每个拟议步骤运行 pre-step 策略。** 循环会在首次领取和决策之前打开轮次，因此 reject 会关闭一个持久、blocked 且不含步骤或模型可见消息的轮次。即使工具续步没有新取得所有权的输入，也会提交空批次，使逐请求上下文生产方可以把带日志的消息加入这一次请求。enter 时，循环先开启步骤，再把返回批次作为 `user/message` 追加，然后派生请求。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个已领取 follow-up 仍是其轮次中唯一的直接提示词。
 
 2. **工具执行后的 `additionalContexts` 与异步注入进入活跃批次 FIFO，并在该批次结算时追加。** `content`/`feedback` 塑造 `execute()` 返回的结果，但每项上下文都是一条独立的带来源 `user/message`，而单个步骤或组合工具可以产生许多上下文。立即追加上下文会产生 `result(c1) → context → result(c2)` 的交错，或把嵌套上下文放在外层结果之前，破坏工具调用／工具结果邻接性。因此 `ToolRunContext.deferContext()` 会在失败路径上也收集嵌套调度上下文，`execute()` 在 `ToolExecutionResult` 上暴露有序数组，循环再把它接纳到与执行期间 `agent.inject()` 调用相同的 FIFO 中。FIFO 在批次结算时，在所有已记录结果之后追加，其中也包括被中断轮次关闭之前。被接受的外层调用将 deferred contexts 保留在 decision contexts 之前；被外层阻止时则丢弃 deferred contexts，只暴露阻止 decision 显式提供的上下文。
 
@@ -47,13 +47,13 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 
 ### 边界
 
-seam 包**不**声明 `hook/*` 会话事件（持久的钩子调用日志）；那些属于 `dsh-hook-protocol`，因为原生插件使用类型化 decision 而无需外部钩子日志。原生插件集成测试（`packages/core/agent-loop/tests/interception.spec.ts`）通过真实循环组合这些 seam，不涉及 `hook/*` 协议。压缩（compaction）（`PreCompact`/`PostCompact`）、Notification 和 Codex `PermissionRequest` 不在本决策范围内。[审批 seam](2026-07-06-approval-seam.md) 通过 `ctx.approval` 解析 `ask` decision；终结性的单调停止由工具结果数据表达，而 `agent/turn-stopping` 是引导再执行一步的最后机会。
+Service Definition 包**不**声明 `hook/*` 会话事件（持久的钩子调用日志）；那些属于 `dsh-hook-protocol`，因为原生插件使用类型化 decision 而无需外部钩子日志。原生插件集成测试（`packages/core/agent-loop/tests/interception.spec.ts`）通过真实循环组合这些扩展点，不涉及 `hook/*` 协议。压缩（compaction）（`PreCompact`/`PostCompact`）、Notification 和 Codex `PermissionRequest` 不在本决策范围内。[审批 seam](2026-07-06-approval-seam.md) 通过 `ctx.approval` 解析 `ask` decision；终结性的单调停止由工具结果数据表达，而 `agent/turn-stopping` 是引导再执行一步的最后机会。
 
 ## 曾考虑的替代方案
 
-- **将工具执行前输入重写作为本 seam 集的一部分发布**：推迟，视为越界信号；上文已阐述一致性问题（审计、历史和展示都读取执行前记录的 `tool/call.arguments`），[工具执行前输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)负责该设计。
-- **将持久的 `hook/*` SessionEvents 与 seam 一起声明**：否决。原生插件使用类型化 Decision 而完全不需要钩子日志（实际示例已证明），因此持久日志属于[钩子协议库](2026-06-30-hook-protocol-lib.md)，而非 seam 表面。
+- **将工具执行前输入重写作为本扩展点集合的一部分发布**：推迟，视为越界信号；上文已阐述一致性问题（审计、历史和展示都读取执行前记录的 `tool/call.arguments`），[工具执行前输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)负责该设计。
+- **将持久的 `hook/*` SessionEvents 与扩展点一起声明**：否决。原生插件使用类型化 Decision 而完全不需要钩子日志（实际示例已证明），因此持久日志属于[钩子协议库](2026-06-30-hook-protocol-lib.md)，而非扩展表面。
 
 ## 后果
 
-规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的约定记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP（Agent Client Protocol）桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
+规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的约定记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP 桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
index 52c64ec86d..5c845ed10b 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.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 .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
-2026-07-05-dynamic-workflows.md: b0fb2349e64093beab8220ea75715b55903772e3
-2026-07-05-dynamic-workflows.zh.md: b66e767090e29f7e0cceb35b59eedb2ea60d12eb
+2026-07-05-dynamic-workflows.md: 4dc8744f7505aeb84a14dbf5ad0cc8cb5783d234
+2026-07-05-dynamic-workflows.zh.md: 5d3f5b014ff4532050bb0afd5464f7ec5e91a323
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
index b0fb2349e6..4dc8744f75 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
@@ -10,7 +10,7 @@ The harness can delegate ONE task to ONE child (`dsh-tool-subagent`), but work t
 
 ## Decision
 
-A workflow capability family at `packages/workflow/` in the bash seam shape (interface / implementation / consumer), plus the structured-output foundation it needs on the subagent seam.
+A workflow capability family at `packages/workflow/` in the bash seam shape (Service Definition / Service provider / Consumer), plus the structured-output foundation it needs on the subagent seam.
 
 ### The script contract (Claude Code-compatible)
 
@@ -36,7 +36,7 @@ The engine exposes an in-process `MessageChannel` test path because main-process
 
 **Value boundary**: `materializeFromRealm` copies outbound values and rejects functions, symbols, nested `undefined`, exotic prototypes, cycles, sparse arrays, and non-finite numbers. Data-property copies make `"__proto__"` safe; getters are read normally and a throwing getter fails loudly. `args` crosses through `workerData` and is cloned again before exposure. Realm functions are invoked rather than copied, and thrown values use a total renderer so `result` cannot reject. Hook errors are host-realm `WorkflowError`s, so scripts branch on `name` or `code` rather than `instanceof Error`, as documented in the engine README. Concurrency, total-agent, item, timeout, and grace limits are validated config.
 
-### The consumer (dsh-tool-workflow)
+### The Consumer (`dsh-tool-workflow`)
 
 A `workflow` tool mirroring `dsh-tool-subagent`'s synchronous shape: start, await, `try/finally` dispose, abort-bridge `exec.signal`, non-`completed` → `isError`. Render intent: a `generic` card titled by the call's `meta.name` parameter (presentation is a pure function of args). The tool description IS the model-facing authoring spec. The usage policy ships with the tool as its own `tool:<toolName>` prompt section (explicit-ask-only guidance — tool guidance lives in tool plugins, never in the deployment persona); the harness has no ultracode-style effort gate.
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
index b66e767090..5d3f5b014f 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
@@ -10,7 +10,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 ## 决策
 
-在 `packages/workflow/` 下以 bash seam 的形态（接口／实现／消费方）提供一组工作流能力，以及它在 subagent seam 上所需的结构化输出基础。
+在 `packages/workflow/` 下以 bash seam 的形态（Service Definition／Service provider／Consumer）提供一组工作流能力，以及它在 subagent seam 上所需的结构化输出基础。
 
 ### 脚本约定（兼容 Claude Code）
 
@@ -36,7 +36,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 **值边界**：`materializeFromRealm` 复制出站值，并拒绝函数、symbol、嵌套 `undefined`、异域原型、循环引用、稀疏数组和非有限数字。数据属性复制使 `"__proto__"` 安全；getter 正常读取，抛出异常的 getter 会明确报错。`args` 通过 `workerData` 传入，暴露前再次克隆。realm 函数被调用而非复制，抛出的值使用对所有输入均有定义的渲染器，因此 `result` 不会 reject。钩子错误是宿主 realm 的 `WorkflowError`，脚本应基于 `name` 或 `code` 分支而非 `instanceof Error`，如引擎 README 所述。并发、total-agent、item、超时和宽限限制均为经校验的配置。
 
-### 消费方（dsh-tool-workflow）
+### Consumer（`dsh-tool-workflow`）
 
 一个 `workflow` 工具，镜像 `dsh-tool-subagent` 的同步形态：启动、await、`try/finally` dispose、abort 桥接 `exec.signal`、非 `completed` → `isError`。渲染意图：一张以调用的 `meta.name` 参数为标题的 `generic` 卡片（展示是参数的纯函数）。工具描述即面向模型的编写规范。使用策略以工具自身的 `tool:<toolName>` 提示词段落随工具发布（显式请求才使用的引导——工具引导存在于工具插件中，从不在部署 persona 中）；harness 没有 ultracode 风格的 effort 门控。
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
index 05b3a3700f..59204fcfa0 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.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 .agents/notes/implemented/feature/2026-07-05-skill-system.md
-2026-07-05-skill-system.md: 5961c535a1397c487b0255f8a27d60929c2eeace
-2026-07-05-skill-system.zh.md: 42ae08e603411bee6212f6f321eb766c9b9d1859
+2026-07-05-skill-system.md: c4b177d84c97e5c541bffb6dfeb2135aedb8d5b8
+2026-07-05-skill-system.zh.md: d0ca688e96c10e674c9b92da8805d653ce5fd063
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
index 5961c535a1..c4b177d84c 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.md
@@ -24,7 +24,7 @@ Each skill is either `<name>/SKILL.md` or `<name>.md` with YAML frontmatter. `na
 
 Local skill filesystem I/O goes through `ctx.fs` when a filesystem service is loaded: project-root lookup probes `.git` with `resolve` and `stat`, root discovery uses `listDir`, and skill reads use `readText`. The Node filesystem remains a fallback for minimal contexts that mount `dsh-skill-local` without the fs seam. Missing roots, unreadable or malformed skill files, and transient provider `list()` failures degrade to warn-and-skip so one bad source does not make every agent request fail; malformed candidates still fail fast because they are provider contract violations.
 
-`dsh-tool-skill` injects one durable user-role `<system-reminder>` catalog as a sourced `user/message` at the session's first `agent/pre-step`, and only when that agent's tool view resolves this plugin's exact `skill` registration. The catalog contains sorted skill name and description only; it excludes bodies, paths, sources, providers, and routing hints. Descriptions are whitespace-normalized, XML-escaped, and capped by `catalogDescriptionMaxLength`, whose default is `500` and minimum is `3`. Full skill bodies are never included in the catalog. (The catalog originally rode the request-only [session-prefix seam](../../archived/feature/2026-07-07-session-prefix.md), archived; the [unified sourced-message decision](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) moved it into durable history.)
+`dsh-tool-skill` injects one durable user-role `<system-reminder>` catalog as a sourced `user/message` at the session's first `agent/pre-step`, and only when that agent's tool view resolves this plugin's exact `skill` registration. The catalog contains sorted skill name and description only; it excludes bodies, paths, sources, providers, and routing hints. Descriptions are whitespace-normalized, XML-escaped, and capped by `catalogDescriptionMaxLength`, whose default is `500` and minimum is `3`. Full skill bodies are never included in the catalog. (The catalog originally rode the request-only [session-prefix extension point](../../archived/feature/2026-07-07-session-prefix.md), archived; the [unified sourced-message decision](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md) moved it into durable history.)
 
 The registry's `list()` returns every winning summary, while model and user consumers apply the invocation predicates owned by the [independent invocation-policy decision](2026-07-28-skill-invocation-policy.md). The `skill({ name })` tool loads one model-invocable skill for the current agent cwd and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` supplies a directory, URL, or opaque provider-managed base for explicitly referenced scripts, references, and assets; resources load only as needed, without directory enumeration. An unresolved name reports that the skill is unknown or no longer available; invalid names and skills with `invocation.modelInvocable: false` retain distinct tool errors. The tool result is the model-visible disclosure path.
 
@@ -38,7 +38,7 @@ The data structures and catalog/tool contract are documented in [skills.md](../.
 
 **Put local filesystem scanning directly inside `ctx.skills`.** Rejected because coding agents, web agents, and future plugin ecosystems need different skill sources. A provider registry mirrors the subagent seam: the registry owns conflict resolution and consumers, while implementations own loading.
 
-**Use a system-prompt section.** Rejected because the rendered system prompt is a single string, while the catalog is a user-role `<system-reminder>` message. The [request-only session-prefix seam](../../archived/feature/2026-07-07-session-prefix.md) (archived) was the original mechanism; after the unified sourced-message decision removed that seam, the catalog became a durable sourced injection with the same message shape.
+**Use a system-prompt section.** Rejected because the rendered system prompt is a single string, while the catalog is a user-role `<system-reminder>` message. The [request-only session-prefix extension point](../../archived/feature/2026-07-07-session-prefix.md) (archived) was the original mechanism; after the unified sourced-message decision removed it, the catalog became a durable sourced injection with the same message shape.
 
 **Materialize built-in DSH authoring skills under `~/.dsh/skills/.system`.** Rejected because bundled skills do not write user home on startup, and embedded or remote providers supply configured skills.
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
index 42ae08e603..d0ca688e96 100644
--- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
@@ -24,7 +24,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 本地 skill 的文件系统 I/O 在加载了文件系统服务时通过 `ctx.fs` 进行：项目根目录查找使用 `resolve` 和 `stat` 探测 `.git`，根目录发现使用 `listDir`，skill 读取使用 `readText`。Node 文件系统作为后备，供在不挂载 fs seam 的最小上下文中加载 `dsh-skill-local` 时使用。缺失的根目录、不可读或格式错误的 skill 文件、以及提供方 `list()` 的瞬态失败均降级为警告并跳过，使一个坏源不会导致所有 agent 请求失败；格式错误的候选项仍然快速失败，因为它们违反了提供方约定。
 
-`dsh-tool-skill` 在会话的第一个 `agent/pre-step` 注入一个持久化的 user-role `<system-reminder>` 目录，作为带来源的 `user/message`，且仅当该 agent 的工具视图解析到本插件精确的 `skill` 注册时才注入。该目录仅包含排序后的 skill 名称与描述；不包含正文、路径、来源、提供方和路由提示。描述经过空白规范化、XML 转义，并受 `catalogDescriptionMaxLength` 上限约束，其默认值为 `500`，最小值为 `3`。完整的 skill 正文从不包含在目录中。（目录最初通过仅请求的[会话前缀 seam](../../archived/feature/2026-07-07-session-prefix.md)（已归档）传递；[统一带来源消息的决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)将其移入持久化历史。）
+`dsh-tool-skill` 在会话的第一个 `agent/pre-step` 注入一个持久化的 user-role `<system-reminder>` 目录，作为带来源的 `user/message`，且仅当该 agent 的工具视图解析到本插件精确的 `skill` 注册时才注入。该目录仅包含排序后的 skill 名称与描述；不包含正文、路径、来源、提供方和路由提示。描述经过空白规范化、XML 转义，并受 `catalogDescriptionMaxLength` 上限约束，其默认值为 `500`，最小值为 `3`。完整的 skill 正文从不包含在目录中。（目录最初通过仅请求的[会话前缀扩展点](../../archived/feature/2026-07-07-session-prefix.md)（已归档）传递；[统一带来源消息的决策](../architecture/2026-07-22-unified-send-and-coalesced-user-messages.md)将其移入持久化历史。）
 
 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。
 
@@ -38,7 +38,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
 
 **将本地文件系统扫描直接放入 `ctx.skills`。** 否决，因为编码 agent、Web agent 和未来的插件生态需要不同的 skill 来源。提供方注册表与 subagent seam 镜像：注册表拥有冲突解决和消费方，实现拥有加载。
 
-**使用系统提示词段落。** 否决，因为渲染后的系统提示词是单一字符串，而目录是一条 user-role `<system-reminder>` 消息。[仅请求的会话前缀 seam](../../archived/feature/2026-07-07-session-prefix.md)（已归档）是最初的机制；统一带来源消息的决策移除该 seam 后，目录改为具有相同消息形状的持久化带来源注入。
+**使用系统提示词段落。** 否决，因为渲染后的系统提示词是单一字符串，而目录是一条 user-role `<system-reminder>` 消息。[仅请求的会话前缀扩展点](../../archived/feature/2026-07-07-session-prefix.md)（已归档）是最初的机制；统一带来源消息的决策移除该扩展点后，目录改为具有相同消息形状的持久化带来源注入。
 
 **在 `~/.dsh/skills/.system` 下物化内置 DSH 编写 skill。** 否决，因为打包的 skill 不应在启动时写入用户主目录，嵌入式或远程提供方在配置后提供 skill。
 
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
index 46f1ed0675..c1ba01b255 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.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 .agents/notes/implemented/feature/2026-07-06-approval-seam.md
-2026-07-06-approval-seam.md: a286e07d51a70232f9aab0af5d8a19622cd222d4
-2026-07-06-approval-seam.zh.md: b15fcb2f6ed52ee591082770d68e265b5a703ff8
+2026-07-06-approval-seam.md: 7c830d93f19a40ab193cfebabca854882ab68d62
+2026-07-06-approval-seam.zh.md: 9dedfddadc23b0da44b28e8750508653ee20bb83
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.md b/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
index a286e07d51..7c830d93f1 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.md
@@ -97,7 +97,7 @@ Snapshots record allowed and rejected sandbox escalation through `session/reques
 - **An inline `tools/pre-execute` permission gate in the ACP bridge** — rejected: prompting for every bridge-owned call hardwires the asking policy into the transport, cannot serve a second asker (sandbox escalation happens after execution starts, with no pre-execute moment), and leaves hook-produced `ask` decisions without a shared mechanism.
 - **The generic user-interaction seam (`ctx.userInteraction`)** — rejected as the approval mechanism: the two share a skeleton (route by agent, block for a human, handle absence), but approval's contract is narrower in every dimension that matters: a closed outcome vocabulary instead of free text, a protocol-native prompt attached to a tool call instead of a generic form, mandatory fail-closed absence, and audit events. Approval therefore does not ride the shipped `packages/interaction/user-interaction` / `ask_user_question` elicitation path — an elicitation form is not a permission prompt, and a free-text answer is not a closed outcome; sharing provider plumbing stays open if the two ever converge.
 - **Static optional injection in `dsh-tools`** — rejected: the vendored cordis `Inject` type has no optional flag — the object form maps service names to intercept config, and a declared inject gates the fiber. `ctx.get('approval')` is the documented opportunistic-consumption pattern (the `tool-bash` owner-token lookup, the loop's persistence probe), reads presence per call, and degrades correctly across HMR without extra machinery.
-- **The capability-seam three-package split** — rejected: interface/implementation/consumer fits a seam whose implementation is swappable (bash-local vs bash-sandbox). Here the service body is fixed mechanism and the variable part is listeners that live with their owners — splitting would manufacture an implementation package with nothing in it ("don't split preemptively").
+- **The capability-seam three-package split** — rejected: Service Definition / Service provider / Consumer fits a seam whose Service provider is swappable (bash-local vs bash-sandbox). Here the service body is fixed mechanism and the variable part is listeners that live with their owners — splitting would manufacture a Service provider package with nothing in it ("don't split preemptively").
 - **Offering `allow_always` now** — rejected: the protocol can express it, but honoring it means designing grant storage, scope identity, and revocation (§ Deferred). Advertising an option the harness cannot honor manufactures doomed grants.
 
 ## Consequences
@@ -134,6 +134,6 @@ In-repo precedents this design copies or contrasts with:
 
 - The `fs/write-intent` gate (`packages/fs/fs/`) — the documented single-occupancy decision-slot waterfall semantics (first answer wins, delegate via `next()`) the answerer contract reuses.
 - `hook/invoked`/`hook/result` — the log-only audit-pair precedent `approval/asked`/`approval/decided` follows; [the hook-bridges Agent Note](2026-06-30-hook-bridges.md) ships `permissionDecision: ask`, the first producer.
-- [The interception-seams Agent Note](2026-06-30-interception-seams.md) — the `tools/pre-execute` `allow`/`deny`/`ask` vocabulary whose `ask` this seam services.
+- [The interception extension-points Agent Note](2026-06-30-interception-extension-points.md) — the `tools/pre-execute` `allow`/`deny`/`ask` vocabulary whose `ask` this seam services.
 - [The automation-only ACP Agent Note](../simplification/2026-07-23-acp-automation-only-protocol.md) — the exact-agent ownership check against the session map that the answerer routes through; [the multi-session Agent Note](2026-06-14-acp-multi-session.md) — the per-session permission-ownership blocker this implements.
 - The opportunistic `ctx.get()` consumption pattern (`tool-bash`'s owner-token lookup, the loop's persistence probe) — how `dsh-tools` consumes the seam without gating its fiber on it.
diff --git a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
index b15fcb2f6e..9dedfddadc 100644
--- a/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
@@ -97,7 +97,7 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 - **在 ACP 桥中内联 `tools/pre-execute` 权限门禁**：否决。对桥拥有的每次调用都弹出提示，会将请求策略硬编码进传输层，无法服务第二个发起方（沙箱升级发生在执行开始之后，没有 pre-execute 时刻），且钩子产生的 `ask` 决策没有共享机制。
 - **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的约定在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/interaction/user-interaction` / `ask_user_question` 信息征集路径——信息征集表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
 - **`dsh-tools` 中的静态可选注入**：否决。vendor 的 Cordis `Inject` 类型没有 optional 标志——对象形式将服务名映射到拦截配置，声明的 inject 会阻塞 fiber。`ctx.get('approval')` 是文档化的机会性消费模式（`tool-bash` 的 owner-token 查找、loop 的持久化探测），按调用读取存在性，跨 HMR 正确降级，无需额外机制。
-- **能力 seam 的三包拆分**：否决。接口/实现/消费方适合实现可替换的 seam（bash-local vs bash-sandbox）。此处服务体是固定机制，可变部分是留在各自通道拥有者插件中的监听器——拆分只会制造一个空的实现包（「不要预防性拆分」）。
+- **能力 seam 的三包拆分**：否决。Service Definition/Service provider/Consumer 适合 Service provider 可替换的 seam（bash-local vs bash-sandbox）。此处服务体是固定机制，可变部分是留在各自通道拥有者插件中的监听器——拆分只会制造一个空的 Service provider 包（「不要预防性拆分」）。
 - **现在就提供 `allow_always`**：否决。协议能表达它，但兑现它意味着设计授权存储、作用域标识和撤销（§ 延后）。展示 harness 无法兑现的选项只会制造注定失败的授权。
 
 ## 后果
@@ -134,6 +134,6 @@ ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有
 
 - `fs/write-intent` 门禁（`packages/fs/fs/`）——文档化的单占用决策槽 waterfall 语义（先到先得，通过 `next()` 委派），应答者约定复用了它。
 - `hook/invoked`/`hook/result`——仅日志审计对先例，`approval/asked`/`approval/decided` 沿用了它；[钩子桥 Agent Note](2026-06-30-hook-bridges.md) 交付了 `permissionDecision: ask`，即第一个生产者。
-- [拦截 seam Agent Note](2026-06-30-interception-seams.md)——`tools/pre-execute` 的 `allow`/`deny`/`ask` 词汇，本 seam 服务其中的 `ask`。
+- [拦截扩展点 Agent Note](2026-06-30-interception-extension-points.md)——`tools/pre-execute` 的 `allow`/`deny`/`ask` 词汇，本 seam 服务其中的 `ask`。
 - [仅面向自动化的 ACP Agent Note](../simplification/2026-07-23-acp-automation-only-protocol.md)——应答者路由时对会话映射执行的精确 agent 归属检查；[多会话 Agent Note](2026-06-14-acp-multi-session.md)——本设计实现的每会话权限归属阻塞项。
 - 机会性 `ctx.get()` 消费模式（`tool-bash` 的 owner-token 查找、loop 的持久化探测）——`dsh-tools` 消费该 seam 而不阻塞其 fiber 的方式。
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
index 3ede7af472..786f76c858 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.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 .agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
-2026-07-06-explicit-tool-order.md: bd6d0a04aa470ca33e618957ae1f08c1ef15fcfe
-2026-07-06-explicit-tool-order.zh.md: 69365151f2c20cfa782ecc5560a6c600c8dec6a2
+2026-07-06-explicit-tool-order.md: 7a4553b50da409b531a9fe14fcfbb201a5165fc4
+2026-07-06-explicit-tool-order.zh.md: a78a38a6ada3ed0a2f3a756830747916446e188c
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
index bd6d0a04aa..7a4553b50d 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.md
@@ -39,7 +39,7 @@ Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it:
 ## Consequences
 
 - Every registry-built assembly starts with a deterministic tool order on every host; absent an expert listener that deliberately changes it, every `request/header` event and model request inherits that order. The CI-vs-local registration-order flip is structurally gone, and the default is lexicographic.
-- The initial `PromptAssembly.tools` is canonical, so waterfall listeners start from the model-facing order; provider registration order is observable nowhere before that cooperative seam.
+- The initial `PromptAssembly.tools` is canonical, so waterfall listeners start from the model-facing order; provider registration order is observable nowhere before that cooperative extension point.
 - The snapshot suite's single pinned request-header fixture (`text-turn`) carries the new canonical tool order; every other ACP snapshot keeps the header bulk scrubbed as `{{system}}`/`{{tools}}`, per the pinned-header design.
 - A pure tool reordering between steps is logged like any other header change: a full `request/header` snapshot with reason `'change'`. Stable canonical order prevents registration timing from creating such changes in the ordinary path.
 - The `toolOrder` key rides the app → `agent-core` → `SystemPrompt` forwarding chain, so deployments set it next to `persona` in the app config; `dsh-llm` and the agent loop are untouched.
diff --git a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
index 69365151f2..a78a38a6ad 100644
--- a/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-explicit-tool-order.zh.md
@@ -39,7 +39,7 @@ Status: implemented
 ## 后果
 
 - 每个由注册表构建的组装在任何宿主上都以确定性工具顺序开始；在没有专家监听器刻意改变的情况下，每个 `request/header` 事件和模型请求都继承该顺序。CI 与本地之间的注册顺序翻转从结构上被消除，默认为字典序。
-- 初始 `PromptAssembly.tools` 是权威的，因此 waterfall 监听器从模型侧顺序开始；提供方注册顺序在该协作 seam 之前无处可观测。
+- 初始 `PromptAssembly.tools` 是权威的，因此 waterfall 监听器从模型侧顺序开始；提供方注册顺序在该协作扩展点之前无处可观测。
 - 快照套件中唯一锁定请求头的 fixture（`text-turn`）携带新的权威工具顺序；按照锁定请求头的设计，其他 ACP 快照仍将大段 header 替换为 `{{system}}`/`{{tools}}`。
 - 步骤之间的纯工具重排与其他 header 变更一样记录：一份原因是 `'change'` 的完整 `request/header` 快照。稳定的权威顺序会防止注册时序在普通路径上制造这类变化。
 - `toolOrder` 键沿 app → `agent-core` → `SystemPrompt` 的转发链传递，因此部署时将其放在 app 配置中 `persona` 旁边即可；`dsh-llm` 和 agent loop 无需改动。
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
index fdb075d228..289e9a582a 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md
-2026-07-06-sandbox.md: 943b1e27ff2d61a56e5532a20b9983d181c15e29
-2026-07-06-sandbox.zh.md: 89a73afb6154363b9d3e7c1afedbda386994325a
+2026-07-06-sandbox.md: 0214a202a41983c76fa25e3a82e1cfaec70a0d55
+2026-07-06-sandbox.zh.md: bd8dcdb74f723a955ea2a1cc5b224ef2ded4a8d5
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
index 943b1e27ff..0214a202a4 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md
@@ -38,7 +38,7 @@ Four `cordis.yml` entries turn an unconfined coding agent into the sandboxed pro
 
 The swap is invisible to every consumer of `ctx.bash`: the bash tools, hook commands, and background tasks run exactly as before by directly spawning the wrapped argv the provider returns. Deleting the `sandbox` and `permission` entries and replacing `bash` with `@deepseek-ai/dsh-bash-local` is the opt-out — execution is unconfined again and the escalation fields vanish from the tool schema, because they are capability-gated on the mounted executor, not on configuration. Omitting only `approval` keeps confinement but fails every escalation closed with its own error text; `permission` also requires the approval seam and a confining executor, so a partially composed preset layer fails loud at load.
 
-Misconfiguration fails loud: `mode` outside the closed vocabulary is rejected at plugin load, and a host with no usable backend throws the structured `SANDBOX_UNAVAILABLE` at `confine()` rather than degrading to unconfined execution. If the selected runner rejects with attributable `ENOENT` or `EACCES`, the consumer reports the same infrastructure error from the spawn channel before any command starts; other spawn errors retain local command-start semantics while still running nothing. `runnerCommand` on `dsh-sandbox-local` is the operator's explicit assertion of a bwrap-compatible runner (chain and probes skipped); it doubles as the deterministic fake-runner seam for keyless tests.
+Misconfiguration fails loud: `mode` outside the closed vocabulary is rejected at plugin load, and a host with no usable backend throws the structured `SANDBOX_UNAVAILABLE` at `confine()` rather than degrading to unconfined execution. If the selected runner rejects with attributable `ENOENT` or `EACCES`, the consumer reports the same infrastructure error from the spawn channel before any command starts; other spawn errors retain local command-start semantics while still running nothing. `runnerCommand` on `dsh-sandbox-local` is the operator's explicit assertion of a bwrap-compatible runner (chain and probes skipped); it doubles as the deterministic fake-runner hook for keyless tests.
 
 Denied file effects return a `[sandbox: file access denied under <mode> mode]` marker and instructions not to work around the denial. A confining executor adds paired `sandbox_permissions` and `justification` fields for one approved retry that must be strictly wider than the session's effective mode. A grant widens only that retry; rejection executes nothing, returns `the user rejected escalating this command to "<mode>"`, and permits no re-ask. The owner-derived pending policy context states the current file policy without replacing those enforcement boundaries. When `dsh-permission` is composed with a UI adapter, one preset selects both knob values; unmatched values fold to `custom`. The [ACP automation composition](../../../../examples/acp-agent/README.md) does not mount that UI service and selects its deployment mode explicitly.
 
@@ -54,7 +54,7 @@ OS subprocess confinement applies to the bash executor, including hook commands,
 
 Policy rides each CALL, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is a new call with a wider policy — inexpressible under a config-fixed provider mode.
 
-The seam confines SAME-WORLD subprocesses only: a backend shares the host's filesystem and kernel. Containers, microVMs, and remote executors are NOT backends of this seam — they replace whole capability implementations (`ctx.bash`, `ctx.fs`) as environment-coherent groups, because an agent whose bash runs in a container while its fs tools write the host lives in two split worlds.
+The seam confines SAME-WORLD subprocesses only: a backend shares the host's filesystem and kernel. Containers, microVMs, and remote executors are NOT backends of this seam — they replace the Service providers for whole capability seams (`ctx.bash`, `ctx.fs`) as environment-coherent groups, because an agent whose bash runs in a container while its fs tools write the host lives in two split worlds.
 
 Left open, for the phase that needs them: whether network restriction arrives as a separate `network_mode` or merges into `sandbox_mode` once a runner enforces both, and whether `SandboxPolicy` grows extra writable-root grants now (the launcher already speaks `--rw <path>`) or only when escalation needs them.
 
@@ -82,7 +82,7 @@ The model sees the current effective file policy in the owner-derived `sandbox:p
 
 When a confining executor is mounted, `bash` advertises paired `sandbox_permissions` and `justification` fields. The schema exposes the full closed escalation vocabulary because effective mode is per-session; execution rejects any target that is not strictly wider than that call's effective mode. Approval resolves before execution. `allowed-once` stamps the granted mode onto only that request, while `rejected`, `cancelled`, `unavailable`, a missing approval service, or a missing agent all fail closed with distinct results. No grant is persisted.
 
-Escalation is a same-turn retry of the denied command with the narrowest sufficient `sandbox_permissions` and a `justification`; the approval prompt is the consent step. It must be grounded in an actual denial, except when the session already observed the same denied access, and a disabled or rejected approval ends that command. The retry, approval decision, and result use existing tool and approval events. `dsh-tool-bash` owns the ask because the executor seam has neither the agent nor call id required for user interaction.
+Escalation is a same-turn retry of the denied command with the narrowest sufficient `sandbox_permissions` and a `justification`; the approval prompt is the consent step. It must be grounded in an actual denial, except when the session already observed the same denied access, and a disabled or rejected approval ends that command. The retry, approval decision, and result use existing tool and approval events. `dsh-tool-bash` owns the ask because the executor Service Definition has neither the agent nor call id required for user interaction.
 
 Left open: what a durable grant's scope identity is beyond the sandbox mode — exact call, path, command prefix, session, or time window — before an `allow_always` option can be advertised.
 
@@ -113,7 +113,7 @@ Before each proposed step, sandbox and approval policy are rendered as ordered c
 
 #### In-process tools
 
-fs/web/todo execute in-process, so their sandbox semantics are policy at their seams. The fs seam now enforces the shared mode vocabulary through a sandboxed provider (`dsh-fs-sandbox` fences write/edit by mode; see [the cross-family fs sandbox RFC](2026-07-14-cross-family-fs-sandbox.md)), so `read-only`/`workspace-write` are real boundaries for the filesystem tools, not a bash-only approximation. web/todo remain unfenced (web's only effect is network, outside the file-effect mode vocabulary). No generic per-tool sandbox runtime: a host-mediated tool leaves the process only by returning declarative effects the host validates, which is a rewrite, not a wrapper — the follow-up settled on one shared policy home (`ctx.sandboxPolicy`) with per-seam enforcement, not a uniform wrapper.
+fs/web/todo execute in-process, so their sandbox semantics are policy at their capability boundaries. The fs seam now enforces the shared mode vocabulary through a sandboxed provider (`dsh-fs-sandbox` fences write/edit by mode; see [the cross-family fs sandbox RFC](2026-07-14-cross-family-fs-sandbox.md)), so `read-only`/`workspace-write` are real boundaries for the filesystem tools, not a bash-only approximation. web/todo remain unfenced (web's only effect is network, outside the file-effect mode vocabulary). No generic per-tool sandbox runtime: a host-mediated tool leaves the process only by returning declarative effects the host validates, which is a rewrite, not a wrapper — the follow-up settled on one shared policy home (`ctx.sandboxPolicy`) with per-capability enforcement, not a uniform wrapper.
 
 ### Testing
 
@@ -142,7 +142,7 @@ Each phase gets its full design when picked up, validated against the code at th
 - **Config-fixed mode on the provider** — rejected: one mode per process; cannot serve concurrent consumers with different policies nor the one-shot widened retry.
 - **One interface spanning containers/VMs too** — rejected: `confine(argv)` presupposes a shared filesystem; environment isolation is capability-sibling backends deployed as coherent groups.
 - **Generic ToolRuntime wrapping any tool** — rejected: mechanically false for in-process tools (closures over `ctx`); the declarative-effects rewrite is unjustified for fs/web/todo.
-- **Ask inside the executor (`dsh-bash-sandbox`)** — rejected: no `agent` to route through, no `callId` to attach the prompt to; adding them teaches a transport seam about sessions and UIs — the tool layer holds both and owns the model-facing vocabulary.
+- **Ask inside the executor (`dsh-bash-sandbox`)** — rejected: no `agent` to route through, no `callId` to attach the prompt to; adding them teaches a transport boundary about sessions and UIs — the tool layer holds both and owns the model-facing vocabulary.
 - **Auto-retry inside the same tool call** — rejected: a hidden re-entry the log cannot reconstruct: one `tool/call` would have produced two executions with different policies — the retry is a NEW logged call with its own arguments and result facts.
 - **Advertise the escalation fields unconditionally** — rejected: under `dsh-bash-local` they are a dead lever — advertising an option the harness cannot honor manufactures doomed grants; capability-gating costs one registration-time read.
 - **A default-relative escalation ladder (advertise only the modes wider than the executor's registration-time default)** — rejected: per-session overrides make the default the wrong baseline — a session switched narrower than the default loses exactly the lever it needs, and under a `danger-full-access` default the fields vanish entirely while a `read-only`-overridden session stays confined with no escalation path. The enum pins the closed target vocabulary; strict widening is a per-call execution check against the session's effective mode.
@@ -199,8 +199,8 @@ Costs and accepted limits:
 
 In-repo precedents this design copies or contrasts with:
 
-- [The capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md) — the interface/implementation/consumer split and the "don't split preemptively" timing rule the second consumer satisfied.
+- [The capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md) — the Service Definition / Service provider / Consumer split and the "don't split preemptively" timing rule the second consumer satisfied.
 - The `dsh-bash` request/spec split ([the bash vocabulary catalog](../../../../docs/subsystems/bash.md)) — the complete `sandboxPolicy` rides its per-call carrier, and the explicit-`resolve()` defaulting convention.
 - [The approval seam Agent Note](2026-07-06-approval-seam.md) — the channel escalation asks through; its answerer waterfall, audit pair, and one-package rationale are recorded there.
 - [Event-sourced sessions](../architecture/2026-06-11-event-sourced-sessions.md) and [standalone log-only events](../simplification/2026-07-28-remove-synthetic-log-only-turns.md) — the log-as-store foundation the per-session modes fold over, and the explicit durability boundary the anchoring design obeys.
-- [The interception-seams Agent Note](2026-06-30-interception-seams.md) — the `tools/pre-execute` vocabulary the escalation gate deliberately does not reuse (an escalating call has no pre-execute moment of its own).
+- [The interception extension-points Agent Note](2026-06-30-interception-extension-points.md) — the `tools/pre-execute` vocabulary the escalation gate deliberately does not reuse (an escalating call has no pre-execute moment of its own).
diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
index 89a73afb61..bd8dcdb74f 100644
--- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
@@ -38,7 +38,7 @@ harness 是一个 SDK，因此约束必须是开发者可组合的能力：是
 
 这一替换对 `ctx.bash` 的所有消费方透明：bash 工具、钩子命令和后台任务照常运行，直接使用提供方返回的已包装 argv 启动。删除 `sandbox` 和 `permission` 条目、将 `bash` 替换为 `@deepseek-ai/dsh-bash-local` 即为退出——执行恢复为无约束，升级字段从工具 schema 中消失，因为它们是基于已挂载执行器的能力门控，而非基于配置。仅省略 `approval` 则保留约束但以自身错误文本关闭每次升级；`permission` 还要求 approval seam 和约束执行器同时存在，因此部分组合的 preset 层在加载时即大声失败。
 
-配置错误会显式导致失败：`mode` 不在封闭词汇中时在插件加载时被拒绝；主机上没有可用后端时在 `confine()` 阶段抛出结构化的 `SANDBOX_UNAVAILABLE`，而非降级为无约束执行。如果所选 runner 以可归因的 `ENOENT` 或 `EACCES` 拒绝，消费方会在任何命令开始前通过 spawn 通道报告同一基础设施错误；其他 spawn 错误仍保留本地命令启动语义，同时也不会运行任何内容。`dsh-sandbox-local` 上的 `runnerCommand` 是运维人员对一个 bwrap 兼容 runner 的显式断言（跳过链和探测）；它同时充当 keyless 测试的确定性 fake-runner seam。
+配置错误会显式导致失败：`mode` 不在封闭词汇中时在插件加载时被拒绝；主机上没有可用后端时在 `confine()` 阶段抛出结构化的 `SANDBOX_UNAVAILABLE`，而非降级为无约束执行。如果所选 runner 以可归因的 `ENOENT` 或 `EACCES` 拒绝，消费方会在任何命令开始前通过 spawn 通道报告同一基础设施错误；其他 spawn 错误仍保留本地命令启动语义，同时也不会运行任何内容。`dsh-sandbox-local` 上的 `runnerCommand` 是运维人员对一个 bwrap 兼容 runner 的显式断言（跳过链和探测）；它同时充当 keyless 测试的确定性 fake-runner 钩子。
 
 被拒绝的文件操作返回 `[sandbox: file access denied under <mode> mode]` 标记，并附带不要绕过拒绝的指令。约束执行器添加配对的 `sandbox_permissions` 和 `justification` 字段，用于一次经批准的重试，该重试必须严格宽于会话的有效模式。授权仅放宽该次重试；拒绝则不执行任何内容，返回 `the user rejected escalating this command to "<mode>"`，且不允许再次请求。由归属方派生的待处理策略上下文会说明当前文件策略，但不会取代这些强制执行边界。当 `dsh-permission` 与某个 UI 适配器一起组合时，一个 preset 同时选定两个旋钮值；不匹配的组合折叠为 `custom`。[ACP 自动化组合](../../../../examples/acp-agent/README.md)不挂载该 UI 服务，而是显式选定其部署模式。
 
@@ -54,7 +54,7 @@ OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还
 
 策略随每次调用而非提供方携带：两个消费方可以在同一时刻以不同策略约束（bash 在 `read-only` 下运行，而一个受约束的子 agent 保持其状态目录可写），且经批准的升级重试是一次带有更宽策略的新调用——在配置固定的提供方模式下无法表达。
 
-该 seam 仅约束与宿主机共享文件系统和内核的子进程。容器、microVM 和远程执行器不是此 seam 的后端——它们以环境一致的组替换整个能力实现（`ctx.bash`、`ctx.fs`），因为一个 bash 在容器中运行而 fs 工具写主机的 agent 生活在两个割裂的世界中。
+该 seam 仅约束与宿主机共享文件系统和内核的子进程。容器、microVM 和远程执行器不是此 seam 的后端——它们以环境一致的组替换整个能力 seam（`ctx.bash`、`ctx.fs`）的 Service provider，因为一个 bash 在容器中运行而 fs 工具写主机的 agent 生活在两个割裂的世界中。
 
 留待需要时再决定：网络限制是作为独立的 `network_mode` 到来，还是在某个 runner 同时强制两者后合并进 `sandbox_mode`；以及 `SandboxPolicy` 是现在就增加额外的可写根授权（launcher 已支持 `--rw <path>`），还是等到升级机制需要时再加。
 
@@ -82,7 +82,7 @@ Landlock launcher 源码和包家族位于 `native/landlock-run`，与 harness 
 
 当约束执行器被挂载时，`bash` 公布配对的 `sandbox_permissions` 和 `justification` 字段。schema 暴露完整的封闭升级词汇，因为有效模式是按会话的；执行拒绝任何不严格宽于该调用有效模式的目标。批准在执行之前解析。`allowed-once` 仅将授权模式盖章到该请求上，而 `rejected`、`cancelled`、`unavailable`、缺失的 approval 服务或缺失的 agent 都以各自不同的结果文本失败关闭。授权不持久化。
 
-升级是对被拒绝命令的同轮次重试，使用最窄的足够 `sandbox_permissions` 和一个 `justification`；批准提示是同意步骤。它必须基于实际的拒绝，除非会话已观察到相同的被拒绝访问；禁用或被拒绝的批准终结该命令。重试、批准决策和结果使用既有的工具和批准事件。`dsh-tool-bash` 拥有请求动作，因为执行器 seam 既没有 agent 也没有用户交互所需的 call id。
+升级是对被拒绝命令的同轮次重试，使用最窄的足够 `sandbox_permissions` 和一个 `justification`；批准提示是同意步骤。它必须基于实际的拒绝，除非会话已观察到相同的被拒绝访问；禁用或被拒绝的批准终结该命令。重试、批准决策和结果使用既有的工具和批准事件。`dsh-tool-bash` 拥有请求动作，因为执行器 Service Definition 既没有 agent 也没有用户交互所需的 call id。
 
 仍未决定：持久授权超出沙箱模式之外的作用域标识是什么——确切调用、路径、命令前缀、会话或时间窗口——这是公布 `allow_always` 选项之前必须回答的问题。
 
@@ -113,7 +113,7 @@ interface SessionEventMap {
 
 #### 进程内工具
 
-fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层面的策略。fs seam 现在通过沙箱提供方强制共享模式词汇（`dsh-fs-sandbox` 按模式限制 write/edit；见[跨工具族 fs 沙箱 Agent Note](2026-07-14-cross-family-fs-sandbox.md)），因此 `read-only`/`workspace-write` 对文件系统工具也是真实边界，而非仅限 bash 的近似。web/todo 仍不受限制（web 的唯一效果是网络，不在文件效果模式词汇内）。没有通用的按工具沙箱运行时：主机中介的工具仅通过返回主机验证的声明式效果来离开进程，那是一次重写而非包装——后续设计选择了一个共享策略归属 `ctx.sandboxPolicy`，由各 seam 强制，而不是统一包装器。
+fs/web/todo 在进程内执行，因此它们的沙箱语义是各自能力边界层面的策略。fs seam 现在通过沙箱提供方强制共享模式词汇（`dsh-fs-sandbox` 按模式限制 write/edit；见[跨工具族 fs 沙箱 Agent Note](2026-07-14-cross-family-fs-sandbox.md)），因此 `read-only`/`workspace-write` 对文件系统工具也是真实边界，而非仅限 bash 的近似。web/todo 仍不受限制（web 的唯一效果是网络，不在文件效果模式词汇内）。没有通用的按工具沙箱运行时：主机中介的工具仅通过返回主机验证的声明式效果来离开进程，那是一次重写而非包装——后续设计选择了一个共享策略归属 `ctx.sandboxPolicy`，由各能力强制，而不是统一包装器。
 
 ### 测试
 
@@ -142,7 +142,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 - **提供方上的配置固定模式**：否决。每进程一个模式；无法服务具有不同策略的并发消费方，也无法表达一次性放宽重试。
 - **一个接口同时覆盖容器/VM**：否决。`confine(argv)` 预设共享文件系统；环境隔离是作为一致组部署的能力兄弟后端。
 - **通用 ToolRuntime 包装任何工具**：否决。对进程内工具（闭包了 `ctx`）机械上不成立；声明式效果重写对 fs/web/todo 而言不合理。
-- **在执行器内部（`dsh-bash-sandbox`）请求批准**：否决。没有可路由的 `agent`，没有可附加提示词的 `callId`；添加它们会让传输 seam 了解会话和 UI——工具层持有两者并拥有面向模型的词汇。
+- **在执行器内部（`dsh-bash-sandbox`）请求批准**：否决。没有可路由的 `agent`，没有可附加提示词的 `callId`；添加它们会让传输边界了解会话和 UI——工具层持有两者并拥有面向模型的词汇。
 - **同一工具调用内自动重试**：否决。日志无法重建的隐藏重入：一个 `tool/call` 会产生两次具有不同策略的执行——重试是一次新的带有自身参数和结果事实的已记录调用。
 - **无条件公布升级字段**：否决。在 `dsh-bash-local` 下它们是死杠杆——公布 harness 无法兑现的选项会制造注定失败的授权；能力门控仅需注册时一次读取。
 - **默认值相对的升级阶梯（仅公布比执行器注册时默认值更宽的模式）**：否决。按会话覆盖使默认值成为错误的基线——切换到比默认值更窄的会话恰恰失去它需要的杠杆，而在 `danger-full-access` 默认值下字段完全消失，同时一个被覆盖为 `read-only` 的会话仍处于约束中却没有升级路径。枚举固定封闭的目标词汇；严格放宽是针对会话有效模式的按调用执行检查。
@@ -199,8 +199,8 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
 
 本设计复制或对比的仓库内先例：
 
-- [能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)——接口/实现/消费方拆分与「不要过早拆分」的时机规则（第二个消费方满足了该规则）。
+- [能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)——Service Definition/Service provider/Consumer 拆分与「不要过早拆分」的时机规则（第二个消费方满足了该规则）。
 - `dsh-bash` 的 request/spec 拆分（[bash 词汇目录](../../../../docs/subsystems/bash.md)）——完整的 `sandboxPolicy` 搭载其按调用载体，以及显式 `resolve()` 默认约定。
 - [批准 seam Agent Note](2026-07-06-approval-seam.md)——升级请求通过的通道；其应答器 waterfall（瀑布式事件）、审计对和单包理由记录在那里。
 - [事件溯源会话](../architecture/2026-06-11-event-sourced-sessions.md)与[独立纯日志事件](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)——按会话模式 fold 所依赖的日志即存储基础，以及锚定设计遵守的显式持久性边界。
-- [拦截 seam Agent Note](2026-06-30-interception-seams.md)——`tools/pre-execute` 词汇，升级门控刻意不复用它（升级调用没有自己的 pre-execute 时刻）。
+- [拦截扩展点 Agent Note](2026-06-30-interception-extension-points.md)——`tools/pre-execute` 词汇，升级门控刻意不复用它（升级调用没有自己的 pre-execute 时刻）。
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
index 9566e667f2..527dd9bead 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.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 .agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
-2026-07-10-parallel-tool-call-execution.md: 7fd540539fd358b3254470f420a0cc11f2927d45
-2026-07-10-parallel-tool-call-execution.zh.md: 278996fedb8c9dcc86916a1544535b1444b6e9f5
+2026-07-10-parallel-tool-call-execution.md: 830691b7596accd1c5746fc51e38a9022f09e501
+2026-07-10-parallel-tool-call-execution.zh.md: bd336919adbf9b96f64477c1e24964172cde6d92
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
index 7fd540539f..830691b759 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
@@ -82,7 +82,7 @@ Snapshot coverage pins the visible multi-call transcript: pending calls may over
 
 **Parallelize the complete tool pipeline.** This keeps the loop on the public one-call API but runs pre- and post-execute middleware concurrently. Existing guards and hook bridges may carry ordered state, so only dispatch overlaps.
 
-**Expose staged methods or a scheduling waterfall.** Public `prepare` / `dispatch` / `finalize` methods or a `tools/execution-mode` event add extension surface before another consumer needs it. The loop uses an internal scheduler view, while `executionMode(exec)` leaves an insertion point for a policy seam.
+**Expose staged methods or a scheduling waterfall.** Public `prepare` / `dispatch` / `finalize` methods or a `tools/execution-mode` event add extension surface before another consumer needs it. The loop uses an internal scheduler view, while `executionMode(exec)` leaves an insertion point for a policy hook.
 
 **Convert scheduler failures into tool results.** AgentLoop cannot determine whether a rejected dispatch invoked the tool body; ToolRegistry owns body-invocation state and typed tool outcomes. Internal scheduler failures therefore remain terminal instead of being reclassified as `ABORTED` results.
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
index 278996fedb..bd336919ad 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
@@ -82,7 +82,7 @@ Code Mode 仍不使用此调度器，因为模型只会发出一个原生 `run_c
 
 **并行执行完整的工具流水线。** 这样可以让循环继续使用公开的单调用 API，但会并发运行 pre-execute 和 post-execute 中间件。现有防护和钩子桥可能承载有序状态，因此只允许派发重叠。
 
-**公开分阶段方法或调度 waterfall。** 公开的 `prepare` / `dispatch` / `finalize` 方法或 `tools/execution-mode` 事件，会在出现另一个消费方之前扩大扩展接口。循环使用内部调度器视图，而 `executionMode(exec)` 为策略 seam 保留了插入点。
+**公开分阶段方法或调度 waterfall。** 公开的 `prepare` / `dispatch` / `finalize` 方法或 `tools/execution-mode` 事件，会在出现另一个消费方之前扩大扩展接口。循环使用内部调度器视图，而 `executionMode(exec)` 为策略钩子保留了插入点。
 
 **将调度器故障转换为工具结果。** AgentLoop 无法判断被拒绝的派发是否已调用工具主体；ToolRegistry 负责工具主体调用状态和类型化工具结果。因此，内部调度器故障保持为终态，而不会被重新分类为 `ABORTED` 结果。
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
index 55a4439855..3d36c07567 100644
--- a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.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 .agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
-2026-07-10-sqlite-session-query-provider.md: 372c21241f9ae5d7300165f016db9b36e6b52855
-2026-07-10-sqlite-session-query-provider.zh.md: f5f2d22a209350975a4ccff9a538a55dfc8ff71e
+2026-07-10-sqlite-session-query-provider.md: 0e15ea15f516091825276c4a9bcde2184c653123
+2026-07-10-sqlite-session-query-provider.zh.md: caf700fd5979ff64c1445caba7fd44ffc28cb925
diff --git a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
index 372c21241f..0e15ea15f5 100644
--- a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md
@@ -16,7 +16,7 @@ Splitting those concerns across a provider coordinator and a database implementa
 
 `@deepseek-ai/dsh-session-query-sqlite` extends the interface service and is the sole concrete owner of `ctx.sessionQuery`. It depends on live `ctx.sessions`, observes optional `ctx.sessionPersistence` dynamically, and owns a dedicated derived SQLite database. There is no search-provider registry, coordinator, persistence event, or agent-loop integration.
 
-The interface package also owns shared first-party semantic extraction and provider-independent filtering. `SessionResultFilter` covers id, nullable cwd, created-at range, nullable parent, and availability; `ctx.sessionQuery.filterSessions()` applies it without an FTS provider. `SessionEventResultFilter` covers seq/time ranges, event type, surface, and literal semantic text. Arrays are ANDed and list values are ORed. The text clause escapes caller input into a Unicode case-insensitive regular expression whose whitespace runs match one or more whitespace characters; it is available through `ctx.sessionQuery.filterEvents()` and is not delegated to an FTS provider.
+The Service Definition package also owns shared first-party semantic extraction and provider-independent filtering. `SessionResultFilter` covers id, nullable cwd, created-at range, nullable parent, and availability; `ctx.sessionQuery.filterSessions()` applies it without an FTS provider. `SessionEventResultFilter` covers seq/time ranges, event type, surface, and literal semantic text. Arrays are ANDed and list values are ORed. The text clause escapes caller input into a Unicode case-insensitive regular expression whose whitespace runs match one or more whitespace characters; it is available through `ctx.sessionQuery.filterEvents()` and is not delegated to an FTS provider.
 
 ## Search semantics
 
diff --git a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
index f5f2d22a20..caf700fd59 100644
--- a/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 `@deepseek-ai/dsh-session-query-sqlite` 扩展接口服务，并且是 `ctx.sessionQuery` 唯一的具体所有者。它依赖实时的 `ctx.sessions`，动态观察可选的 `ctx.sessionPersistence`，并拥有一个专用的派生 SQLite 数据库。系统没有搜索提供方注册表、协调器、持久化事件或 agent loop（智能体循环）集成。
 
-接口包还拥有共享的第一方语义提取与提供方无关的过滤。`SessionResultFilter` 涵盖 id、可空的 cwd、创建时间范围、可空的父会话与可用性；`ctx.sessionQuery.filterSessions()` 无需 FTS 提供方即可应用这些过滤器。`SessionEventResultFilter` 涵盖 seq/时间范围、事件类型、surface 与字面语义文本。过滤器数组内各项按逻辑与（AND）组合，列表值按逻辑或（OR）组合。文本子句会将调用方输入转义为不区分大小写的 Unicode 正则表达式，其中每段连续空白都匹配一个或多个空白字符；该子句通过 `ctx.sessionQuery.filterEvents()` 提供，不会委托给 FTS 提供方。
+Service Definition 包还拥有共享的第一方语义提取与提供方无关的过滤。`SessionResultFilter` 涵盖 id、可空的 cwd、创建时间范围、可空的父会话与可用性；`ctx.sessionQuery.filterSessions()` 无需 FTS 提供方即可应用这些过滤器。`SessionEventResultFilter` 涵盖 seq/时间范围、事件类型、surface 与字面语义文本。过滤器数组内各项按逻辑与（AND）组合，列表值按逻辑或（OR）组合。文本子句会将调用方输入转义为不区分大小写的 Unicode 正则表达式，其中每段连续空白都匹配一个或多个空白字符；该子句通过 `ctx.sessionQuery.filterEvents()` 提供，不会委托给 FTS 提供方。
 
 ## 搜索语义
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index 7952219be6..d7d288e9f9 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.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 .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
-2026-07-16-harness-level-loop.md: bc375621c5bf71ae6e3fbcd754d3b62e43353ae9
-2026-07-16-harness-level-loop.zh.md: fd74fbf85a63cb2f35fbcf7f694f738a07fe0cee
+2026-07-16-harness-level-loop.md: 2efcf64adf07152b544c82f5bbf3bd8e415cd64d
+2026-07-16-harness-level-loop.zh.md: 8b83ca4a7f957f304c093e4b3f4c462c6301d6bc
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
index bc375621c5..2efcf64adf 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
@@ -19,7 +19,7 @@ This proposal is implemented in amended form as two explicit plugin policies ove
 1. **Same-session goals** retain one durable objective in the current session and admit goal-attributed continuation turns only while live activation is armed.
 2. **Fresh-agent Ralph runs** execute a fixed foreground workflow whose rounds each spawn a new structured child with no conversation seed.
 
-There is no `packages/loop/` family, `LoopDriver`, `LoopId`, universal `StopCondition`, or model-facing generic `loop` tool. The two policies share the repository's ordinary agent, session, tools, workflow, subagent, and UI extension seams, but they do not pretend that one lifecycle fits both.
+There is no `packages/loop/` family, `LoopDriver`, `LoopId`, universal `StopCondition`, or model-facing generic `loop` tool. The two policies share the repository's ordinary agent, session, tools, workflow, subagent, and UI extension points, but they do not pretend that one lifecycle fits both.
 
 ### Vocabulary and policy boundary
 
@@ -98,11 +98,11 @@ The six owning Agent Notes record unit, integration, process, snapshot, cancella
 
 ## Alternatives considered
 
-- **Implement the original universal loop capability seam** — rejected because `Evaluator`, `BudgetPolicy`, `RoundHandoff`, `GoalReflector`, background task ownership, persistence, and scheduling do not form one coherent mandatory abstraction. Building all of them before their first concrete consumers would create broad speculative surface and duplicate existing session, workflow, subagent, and task machinery.
+- **Implement the original universal loop capability** — rejected because `Evaluator`, `BudgetPolicy`, `RoundHandoff`, `GoalReflector`, background task ownership, persistence, and scheduling do not form one coherent mandatory abstraction. Building all of them before their first concrete consumers would create broad speculative surface and duplicate existing session, workflow, subagent, and task machinery.
 - **Implement only same-session goals** — rejected because fresh-context iteration is materially different and is a valuable demonstration of the plugin architecture. Ralph belongs as a fixed workflow consumer with explicit context reset.
 - **Put Ralph inside the goal-round driver** — rejected because same-session goals deliberately preserve one conversation while Ralph deliberately removes it. Combining them would make activation, replay, handoff, and UI state ambiguous.
 - **Treat a fork as a fresh Ralph child** — rejected because a fork carries a conversation prefix. Fresh children plus workspace state and one explicit report are easier to bound and replay without a synthetic cancel record.
-- **Copy Claude Code's evaluator into the first goal implementation** — rejected because a transcript-only model evaluator is one useful policy, not a generally trustworthy completion certificate. Deterministic evaluation and isolation must remain possible, so the evaluator is deferred until its authority and provider seam are designed.
+- **Copy Claude Code's evaluator into the first goal implementation** — rejected because a transcript-only model evaluator is one useful policy, not a generally trustworthy completion certificate. Deterministic evaluation and isolation must remain possible, so the evaluator is deferred until its authority and provider contract are designed.
 - **Automatically continue after session restore** — rejected because opening a session is observation, not authority to spend resources. Durable state is restored while activation waits for a new human prompt.
 - **Route `/goal` through the model** — rejected because status and explicit lifecycle controls should be deterministic, token-free UI actions; ordinary natural-language prompts remain the semantic model path.
 - **Modify the concrete agent loop with goal or Ralph modes** — rejected because public queue, prompt, session, cancellation, workflow, and subagent seams already support both policies. The generic cancel-requested observation is the only core coordination addition.
@@ -125,5 +125,5 @@ The six owning Agent Notes record unit, integration, process, snapshot, cancella
 - **No generic loop journal or execution-world rewind** — session replay reconstructs goal history, not prior files, processes, environment, credentials, or external side effects. Ralph treats the current workspace as authority and carries no cross-run journal.
 - **No goal reflector** — concern events, automatic no-progress heuristics, goal revision by an independent reflector, stuck-pattern detection, and `loop_split` are not implemented. Humans can edit, pause, clear, or resume the goal directly.
 - **Ralph policy remains narrow** — one round creates one fresh child; within-round fan-out, evaluator/worker role separation, dynamic provider/model selection, and structural recursive-Ralph tool denial need separate policy surfaces. Prompt guidance is not enforcement.
-- **Ralph does not retry a failed child** — an ordinary failure preserves the failed round and last good handoff, while fatal workflow infrastructure failures can end before that state is available. Retry count, backoff, and richer failure transport need separate policy and seam design.
+- **Ralph does not retry a failed child** — an ordinary failure preserves the failed round and last good handoff, while fatal workflow infrastructure failures can end before that state is available. Retry count, backoff, and richer failure transport need separate policy and boundary design.
 - **Portable UI remains modest** — TUI renders plain-text goal status and generic Ralph cards. ACP carries only committed assistant text; there is no continuous status widget, reconnectable command output, modal goal editor, or command plane in ACP, the headless CLI, or JSON-RPC.
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index fd74fbf85a..8b83ca4a7f 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 1. **同会话目标**在当前会话中保留一个持久目标，并且只在实时激活态已激活时接纳带目标归属的续行轮次。
 2. **全新 agent Ralph 运行**执行一个固定前台工作流，其中每个 Round 都生成一个不带对话种子的全新结构化子 agent。
 
-系统中没有 `packages/loop/` 包族、`LoopDriver`、`LoopId`、通用 `StopCondition` 或面向模型的通用 `loop` 工具。两项策略共享本仓库普通的 agent、会话、工具、工作流、subagent 与 UI 扩展 seam，但不会假装一种生命周期可以同时适配两者。
+系统中没有 `packages/loop/` 包族、`LoopDriver`、`LoopId`、通用 `StopCondition` 或面向模型的通用 `loop` 工具。两项策略共享本仓库普通的 agent、会话、工具、工作流、subagent 与 UI 扩展点，但不会假装一种生命周期可以同时适配两者。
 
 ### 词汇与策略边界
 
@@ -98,11 +98,11 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 
 ## 考虑过的替代方案
 
-- **实现原始通用 loop 能力 seam**——不予采纳，因为 `Evaluator`、`BudgetPolicy`、`RoundHandoff`、`GoalReflector`、后台任务所有权、持久化与调度并不构成一项一致的必选抽象。在出现首个具体消费者前全部构建，会产生宽泛推测性表面，并重复现有 session、workflow、subagent 与 task 机制。
+- **实现原始通用 loop 能力**——不予采纳，因为 `Evaluator`、`BudgetPolicy`、`RoundHandoff`、`GoalReflector`、后台任务所有权、持久化与调度并不构成一项一致的必选抽象。在出现首个具体消费者前全部构建，会产生宽泛推测性表面，并重复现有 session、workflow、subagent 与 task 机制。
 - **只实现同会话目标**——不予采纳，因为全新上下文迭代在实质上不同，也是插件架构的重要示范。Ralph 应作为带显式上下文重置的固定工作流消费者。
 - **把 Ralph 放进目标回合驱动器**——不予采纳，因为同会话目标有意保留一段对话，而 Ralph 有意移除对话。合并两者会让激活、重放、交接与 UI 状态含糊不清。
 - **把 fork 当成全新 Ralph 子 agent**——不予采纳，因为 fork 会携带对话前缀。全新子 agent 加工作区状态与一份显式报告更容易限制和重放，并且无需合成取消记录。
-- **把 Claude Code 评估器复制进首个目标实现**——不予采纳，因为只读取转录的模型评估器是一项有用策略，但不是普遍可信的完成证书。系统必须仍能支持确定性评估与隔离，因此评估器延期到其权限与 provider seam 完成设计之后。
+- **把 Claude Code 评估器复制进首个目标实现**——不予采纳，因为只读取转录的模型评估器是一项有用策略，但不是普遍可信的完成证书。系统必须仍能支持确定性评估与隔离，因此评估器延期到其权限与提供方约定完成设计之后。
 - **会话恢复后自动续行**——不予采纳，因为打开会话是观察行为，不是花费资源的权限。系统恢复持久状态，而激活态等待新的人类提示词。
 - **通过模型路由 `/goal`**——不予采纳，因为状态与显式生命周期控制应是确定性且零 token 的 UI 操作；普通自然语言提示词仍是语义模型路径。
 - **为具体 agent loop 增加目标或 Ralph 模式**——不予采纳，因为公开队列、提示词、会话、取消、工作流与 subagent seam 已经支持两项策略。通用 cancel-requested 观察是唯一核心协调新增项。
@@ -125,5 +125,5 @@ Codex 提供了这里采用的最小可观察目标 UX：一个附着于聊天
 - **没有通用 loop 日志或执行世界回退**——会话重放会重建目标历史，而不会恢复此前文件、进程、环境、凭据或外部副作用。Ralph 把当前工作区作为权威，并且没有跨运行日志。
 - **没有目标反思器**——concern 事件、自动无进展启发式、由独立反思器执行的目标修订、卡住模式检测与 `loop_split` 均未实现。人类可以直接编辑、暂停、清除或恢复目标。
 - **Ralph 策略仍然狭窄**——一个 Round 创建一个全新子 agent；Round 内扇出、评估器/工作者角色分离、动态 provider/模型选择与从结构上禁止递归调用 Ralph 工具都需要独立策略表面。提示词指导不是强制执行。
-- **Ralph 不会重试失败的子 agent**——普通失败会保留失败 Round 与上一份有效交接，而致命工作流基础设施错误可能在该状态可用前结束。重试次数、退避与更丰富的失败传输需要独立的策略与 seam 设计。
+- **Ralph 不会重试失败的子 agent**——普通失败会保留失败 Round 与上一份有效交接，而致命工作流基础设施错误可能在该状态可用前结束。重试次数、退避与更丰富的失败传输需要独立的策略与边界设计。
 - **可移植 UI 仍较朴素**——TUI 渲染纯文本目标状态和通用 Ralph 卡片。ACP 只承载已提交的助手文本；系统没有持续状态组件、可重连命令输出、模态目标编辑器，ACP、无头 CLI 与 JSON-RPC 也没有命令平面。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index f41c42e700..1730793d35 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: 219f48235d527cffbf66020ceb22e80ca473093d
-2026-07-16-persistent-pty-sessions.zh.md: c3842936248fb2d1705708dfd694be563ce2adf9
+2026-07-16-persistent-pty-sessions.md: 5d45f5fd13099352d503bc3296e4f6b7b0c53bc8
+2026-07-16-persistent-pty-sessions.zh.md: a0b4150157110b64943a42ce4e3544342e1be788
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index 219f48235d..5d45f5fd13 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -26,7 +26,7 @@ The implementation supports interactive shells and line-oriented REPLs on Linux
 | `dsh-pty-local` | Persistent-shell backend over `ctx.subprocess.spawnTerminal()`: readiness, bounded terminal buffers, sandbox resolution, and owner-aware session lifecycle | registers a backend on `ctx.pty` |
 | `dsh-tool-pty` | Six model-facing tools, task-runtime integration for background sends, guidance, and UI render intents | registers on `ctx.tools` |
 
-Readiness remains PTY-backend behavior, not a second public seam. The terminal-process provider supplies only substrate facts such as the foreground process group and whether it can prove that group is waiting on input; `dsh-pty-local` combines those facts with prompt and silence evidence into the common send result.
+Readiness remains PTY-backend behavior, not a second public contract. The terminal-process provider supplies only substrate facts such as the foreground process group and whether it can prove that group is waiting on input; `dsh-pty-local` combines those facts with prompt and silence evidence into the common send result.
 
 ### Agent ownership and identity
 
@@ -64,7 +64,7 @@ The UI render contract is exact and location-free. `terminal_send` uses terminal
 
 Foreground sends return a bounded rendered delta and two independent facts: `waitReason` (`stdin_read | inferred_idle | timeout | session_exit`) and `sessionStatus` (`running` or `exited` with exit code or signal). `session_exit` refers to the PTY's top-level shell process, not an arbitrary foreground command whose status the shell consumes. A timeout never implies process exit. `dsh-tool-pty.maxResultBytes` defaults to 262144, rejects values below 64 so creation acknowledgements retain registry-issued ids, and caps each single-text UTF-8 result after normalized tool or pipeline errors, wait, session, pagination, truncation, generic task-status wrappers, policy denials or short-circuits, and post-execute replacements or blocks; the terminal definitions' last-mile `finalizeContent` callback leaves deliberately structured multi-block policy content unchanged. The renderer reserves suffix space and preserves code-point boundaries instead of treating the backend payload cap as the final model bound.
 
-With `run_in_background: true`, `dsh-tool-pty` registers the in-flight send on `ctx.tasks` and returns immediately with `taskId`. The producer places `maxResultBytes` on the task snapshot so `task_output`, terminal kill status, and completion notices enforce the same complete-result cap after generic metadata. `task_output(wait: true)` waits, reads incremental output, and records the final result; `task_kill` resolves the current foreground PGID and delivers a real `SIGINT`, including when the application has disabled terminal `ISIG`, and escalates only through the PTY backend's owned teardown path. If the task surface is absent, background mode fails before writing input. No PTY-specific `sleep` tool or general wake-up seam is added.
+With `run_in_background: true`, `dsh-tool-pty` registers the in-flight send on `ctx.tasks` and returns immediately with `taskId`. The producer places `maxResultBytes` on the task snapshot so `task_output`, terminal kill status, and completion notices enforce the same complete-result cap after generic metadata. `task_output(wait: true)` waits, reads incremental output, and records the final result; `task_kill` resolves the current foreground PGID and delivers a real `SIGINT`, including when the application has disabled terminal `ISIG`, and escalates only through the PTY backend's owned teardown path. If the task surface is absent, background mode fails before writing input. No PTY-specific `sleep` tool or general wake-up API is added.
 
 `terminal_read` pages backward from the newest retained line. The backend enforces both line and UTF-8 byte caps on retained scrollback and the returned page payload, so one oversized line cannot bypass the backend bound; the tool then caps the fully rendered page including pagination and truncation metadata. `truncated` distinguishes retention loss from an ordinary viewport delta.
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index c384293624..a0b4150157 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -26,7 +26,7 @@ harness 可以运行前台与后台命令、编辑文件和委派工作，但无
 | `dsh-pty-local` | 基于 `ctx.subprocess.spawnTerminal()` 的持久 shell 后端：就绪状态、有界终端缓冲、沙箱解析和感知 owner 的会话生命周期 | 在 `ctx.pty` 上注册后端 |
 | `dsh-tool-pty` | 6 个面向模型的工具、后台发送的 task 运行时集成、使用指引和 UI 渲染意图 | 注册到 `ctx.tools` |
 
-就绪判定仍属于 PTY 后端行为，不是第二条公共 seam。终端进程提供方只提供基底事实，例如前台进程组，以及能否证明该组正在等待输入；`dsh-pty-local` 将这些事实与提示符和静默证据组合成统一的发送结果。
+就绪判定仍属于 PTY 后端行为，不是第二条公共约定。终端进程提供方只提供基底事实，例如前台进程组，以及能否证明该组正在等待输入；`dsh-pty-local` 将这些事实与提示符和静默证据组合成统一的发送结果。
 
 ### agent 所有权与身份
 
@@ -64,7 +64,7 @@ UI 渲染约定精确且不携带位置信息。`terminal_send` 只为前台发
 
 前台发送返回有界的渲染增量和两个独立事实：`waitReason`（`stdin_read | inferred_idle | timeout | session_exit`）与 `sessionStatus`（`running`，或携带退出码或信号的 `exited`）。`session_exit` 指 PTY 顶层 shell 进程退出，不指由 shell 消费状态的任意前台命令。timeout 从不意味着进程已经退出。`dsh-tool-pty.maxResultBytes` 默认为 262144；低于 64 的值会被拒绝，以确保创建确认保留 registry 签发的 id；每个单文本 UTF-8 结果在加入规范化的工具或流水线错误、等待、会话、分页、截断、通用 task 状态包装、策略拒绝或短路以及 post-execute 替换或阻断后，仍受该值限制；终端定义自有的末端 `finalizeContent` callback 会原样保留策略刻意返回的结构化多 block 内容。渲染器会为后缀预留空间并保持代码点边界，而不会把后端载荷上限当作面向模型结果的最终上限。
 
-当 `run_in_background: true` 时，`dsh-tool-pty` 在 `ctx.tasks` 上注册进行中的发送，并立即返回 `taskId`。生产方把 `maxResultBytes` 写入 task 快照，使 `task_output`、kill 返回的终态状态和完成通知在加上通用元数据后，仍对完整结果执行同一上限。`task_output(wait: true)` 负责等待、读取增量输出并记录最终结果；`task_kill` 会解析当前前台 PGID 并发送真正的 `SIGINT`，即使应用已禁用终端 `ISIG` 也同样如此，且后续升级仍只通过 PTY 后端拥有的 teardown 路径进行。若 task 对外接口不存在，后台模式必须在写入输入前失败。设计不新增 PTY 专用的 `sleep` 工具或通用唤醒 seam。
+当 `run_in_background: true` 时，`dsh-tool-pty` 在 `ctx.tasks` 上注册进行中的发送，并立即返回 `taskId`。生产方把 `maxResultBytes` 写入 task 快照，使 `task_output`、kill 返回的终态状态和完成通知在加上通用元数据后，仍对完整结果执行同一上限。`task_output(wait: true)` 负责等待、读取增量输出并记录最终结果；`task_kill` 会解析当前前台 PGID 并发送真正的 `SIGINT`，即使应用已禁用终端 `ISIG` 也同样如此，且后续升级仍只通过 PTY 后端拥有的 teardown 路径进行。若 task 对外接口不存在，后台模式必须在写入输入前失败。设计不新增 PTY 专用的 `sleep` 工具或通用唤醒 API。
 
 `terminal_read` 从最新保留行向后分页。后端同时对保留的 scrollback 和返回页载荷执行行数与 UTF-8 字节上限，因此单个超长行无法绕过后端上限；工具随后再限制包含分页与截断元数据的完整渲染页。`truncated` 用于区分保留数据丢失与普通 viewport 增量。
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
index 2e02bddec1..50c5668e6c 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.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 .agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
-2026-07-19-fresh-agent-ralph-workflow-tool.md: 6fe96587c49ef0316d1618fda2ee26b015b1ce87
-2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 7cd3cf388f9d1e03390dd08ed045562bcfeb1f4d
+2026-07-19-fresh-agent-ralph-workflow-tool.md: bbc8aba54bbd2cbfe9d9ba1fcc8cf9ad5c257d4f
+2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 7ac405c2f6f80fa3151fb8b88c266ae2b83ea3eb
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
index 6fe96587c4..bbc8aba54b 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
@@ -12,7 +12,7 @@ Adding Ralph behavior to `dsh-agent-loop`, the goal driver, or the public model-
 
 ## Decision
 
-Add `@deepseek-ai/dsh-tool-ralph` as a separate consumer package under `packages/workflow/`. It registers `ralph({ objective, maxRounds? })`, owns a fixed workflow script, and depends only on `ctx.tools`, `ctx.systemPrompt`, `ctx.workflows`, and `ctx.subagents`. A Ralph run is not a session goal, creates no goal state, and requires no branch in the concrete agent loop.
+Add `@deepseek-ai/dsh-tool-ralph` as a separate Consumer package under `packages/workflow/`. It registers `ralph({ objective, maxRounds? })`, owns a fixed workflow script, and depends only on `ctx.tools`, `ctx.systemPrompt`, `ctx.workflows`, and `ctx.subagents`. A Ralph run is not a session goal, creates no goal state, and requires no branch in the concrete agent loop.
 
 The tool is foreground-only. The calling agent parents every child for cwd and lineage, the parent tool call waits for the complete run, and the parent step's abort signal cancels the workflow. `run.dispose()` is awaited on every path, so cancellation reaches the worker engine's bounded settlement and child quiescence before the call returns.
 
@@ -70,5 +70,5 @@ A keyless real-stack integration drives the fixed script through the actual work
 - Runs are foreground and process-local. Background collection, persistence/resume, scheduling, and restart recovery are absent.
 - Round count is the only aggregate budget. Token, currency, elapsed-time, and provider-usage budgets remain separate future policy.
 - One round creates one child. Within-round fan-out, evaluator/worker role separation, dynamic provider or model selection, and cross-run journals are deferred.
-- An ordinary child failure ends the run without retry, while preserving the failed round and last successful handoff. Fatal workflow infrastructure failures can end before the fixed script returns that state; adding retry or richer failure transport requires separate policy and seam design.
+- An ordinary child failure ends the run without retry, while preserving the failed round and last successful handoff. Fatal workflow infrastructure failures can end before the fixed script returns that state; adding retry or richer failure transport requires separate policy and boundary design.
 - Prompt guidance asks models not to invoke Ralph recursively; a structural child-tool restriction would require a separately designed workflow child-policy surface.
diff --git a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
index 7cd3cf388f..7ac405c2f6 100644
--- a/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-在 `packages/workflow/` 下新增独立的消费方包 `@deepseek-ai/dsh-tool-ralph`。它注册 `ralph({ objective, maxRounds? })`，拥有固定工作流脚本，并且只依赖 `ctx.tools`、`ctx.systemPrompt`、`ctx.workflows` 和 `ctx.subagents`。Ralph 运行不是会话目标，不会创建目标状态，也不要求在具体 agent loop 中增加分支。
+在 `packages/workflow/` 下新增独立的 Consumer 包 `@deepseek-ai/dsh-tool-ralph`。它注册 `ralph({ objective, maxRounds? })`，拥有固定工作流脚本，并且只依赖 `ctx.tools`、`ctx.systemPrompt`、`ctx.workflows` 和 `ctx.subagents`。Ralph 运行不是会话目标，不会创建目标状态，也不要求在具体 agent loop 中增加分支。
 
 该工具仅以前台方式运行。调用 agent 作为每个子 agent 的父级以提供 cwd 和谱系，父工具调用等待整次运行结束，父步骤的中止信号会取消工作流。每条路径都会等待 `run.dispose()`，因此调用返回前，取消会经过工作线程引擎的有界收敛并使子 agent 完全停稳。
 
@@ -70,5 +70,5 @@ Ralph 插件的 `subagentProvider` 默认为 `spawn`。每次调用前，它要
 - 运行位于前台且只存在于进程内。后台收集、持久化/恢复、调度和重启恢复均不存在。
 - Round 数是唯一聚合预算。token、货币、耗时和提供方用量预算仍属于未来的独立策略。
 - 每个 Round 创建一个子 agent。Round 内扇出、evaluator/工作者角色分离、动态提供方或模型选择，以及跨运行日志均被推迟。
-- 普通子 agent 失败会结束运行且不重试，同时保留失败 Round 与上一份成功交接。致命工作流基础设施错误可能在固定脚本返回该状态前结束；增加重试或更丰富的失败传输需要独立的策略与 seam 设计。
+- 普通子 agent 失败会结束运行且不重试，同时保留失败 Round 与上一份成功交接。致命工作流基础设施错误可能在固定脚本返回该状态前结束；增加重试或更丰富的失败传输需要独立的策略与边界设计。
 - 提示指导模型不要递归调用 Ralph；结构化的子 agent 工具限制需要另行设计工作流子策略表面。
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
index 088290b3fc..bedab21f20 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.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 .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
-2026-07-19-model-facing-goal-tools.md: abed410c7fd71b18c2cc0d0db745e76d98352546
-2026-07-19-model-facing-goal-tools.zh.md: a51ad417ff0928583ccddddafe65d23bc86bd24d
+2026-07-19-model-facing-goal-tools.md: c2f1210ea636b61e99111d261cf9302c77576b46
+2026-07-19-model-facing-goal-tools.zh.md: fd8ca90ba3b6809a7225b118ec6d311fb193cc8f
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
index abed410c7f..c2f1210ea6 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md
@@ -12,7 +12,7 @@ The surface also needs to preserve the separation between durable state and live
 
 ## Decision
 
-`@deepseek-ai/dsh-tool-goal` in `packages/goal/tool-goal/` contributes three exclusive tools and one system-prompt policy section over `ctx.goals`: `get_goal`, `create_goal`, and `update_goal`. The names and read-create-update shape follow Codex's compact goal tool surface while the authority rules use this repository's public agent, session, tool, and goal seams.
+`@deepseek-ai/dsh-tool-goal` in `packages/goal/tool-goal/` contributes three exclusive tools and one system-prompt policy section over `ctx.goals`: `get_goal`, `create_goal`, and `update_goal`. The names and read-create-update shape follow Codex's compact goal tool surface while the authority rules use this repository's public agent, session, tool, and goal services.
 
 ### Tools and model contract
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
index a51ad417ff..fd8ca90ba3 100644
--- a/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-位于 `packages/goal/tool-goal/` 的 `@deepseek-ai/dsh-tool-goal` 在 `ctx.goals` 之上贡献三个独占工具和一个系统提示词策略段：`get_goal`、`create_goal` 与 `update_goal`。工具名称和读取—创建—更新形态遵循 Codex 的紧凑目标工具表面，而权限规则使用本仓库公共的 agent（智能体）、会话、工具与目标 seam。
+位于 `packages/goal/tool-goal/` 的 `@deepseek-ai/dsh-tool-goal` 在 `ctx.goals` 之上贡献三个独占工具和一个系统提示词策略段：`get_goal`、`create_goal` 与 `update_goal`。工具名称和读取—创建—更新形态遵循 Codex 的紧凑目标工具表面，而权限规则使用本仓库公共的 agent（智能体）、会话、工具与目标服务。
 
 ### 工具与模型约定
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
index 578218ce21..c14cfe4c3b 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.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 .agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
-2026-07-19-persisted-same-session-goal-domain.md: ce93a652f3910912fbf6afc28061de4d13eb2de2
-2026-07-19-persisted-same-session-goal-domain.zh.md: ddb4fdedafbacbfec355a7a1c912a5f9545e208a
+2026-07-19-persisted-same-session-goal-domain.md: cdbbdd55c8c9b73851d5e729492656eda1380430
+2026-07-19-persisted-same-session-goal-domain.zh.md: 7c8af321ec78779ecbf4e5e00805ef6f152b2aa1
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
index ce93a652f3..cdbbdd55c8 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-19-persisted-same-session-goal-domain.zh.md)
 
 A long-running objective outlives one prompt, turn, or model request. Treating that objective as an in-memory loop variable loses it on process restart, while putting it only in UI state makes model behavior impossible to reconstruct. Treating every session turn as progress also charges unrelated human messages against an automatic-work budget.
 
-Durable lifecycle and permission to continue are different facts. A session may retain an active objective after restart or fork, but silently starting work when a user opens that session is surprising. The domain needs replayable state without persisted auto-execution authority, and it must remain a plugin on the public agent/session seams rather than a special case in the concrete loop.
+Durable lifecycle and permission to continue are different facts. A session may retain an active objective after restart or fork, but silently starting work when a user opens that session is surprising. The domain needs replayable state without persisted auto-execution authority, and it must remain a plugin on the public agent and session services rather than a special case in the concrete loop.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
index ddb4fdedaf..7c8af321ec 100644
--- a/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 长时间运行的目标会跨越单个提示词、轮次或模型请求。若把该目标视为内存中的循环变量，进程重启时就会丢失；若只存放在 UI 状态中，又无法重建模型行为。若把会话中的每个轮次都视为目标进度，与自动工作无关的人类消息也会消耗预算。
 
-持久化的生命周期与继续执行的权限是两个不同事实。会话在重启或 fork（派生）后可以保留活跃目标，但用户打开会话时静默启动工作并不符合直觉。该领域需要可回放的状态，却不能持久化自动执行权限；它还必须作为公共 agent（智能体）与会话 seam 上的插件存在，而不是具体循环中的特例。
+持久化的生命周期与继续执行的权限是两个不同事实。会话在重启或 fork（派生）后可以保留活跃目标，但用户打开会话时静默启动工作并不符合直觉。该领域需要可回放的状态，却不能持久化自动执行权限；它还必须作为公共 agent（智能体）与会话服务上的插件存在，而不是具体循环中的特例。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml
index 4fd53a1941..d5c7073d5c 100644
--- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.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 .agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md
-2026-07-19-same-session-goal-round-driver.md: a989b9d3487ebbf8ff11a4e34cb08029f1e4ace4
-2026-07-19-same-session-goal-round-driver.zh.md: 309b5ce45c2edb516a329f9992cea5558a2aeb8c
+2026-07-19-same-session-goal-round-driver.md: 2ca08e4b6f0d16d66663db5275f3bce72bd3a9d7
+2026-07-19-same-session-goal-round-driver.zh.md: a41d9705e18cddb851c0a99a8dd7fc901f2be81a
diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md
index a989b9d348..2ca08e4b6f 100644
--- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md
+++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md
@@ -49,7 +49,7 @@ The driver classifies one closed goal-owned turn as follows:
 
 No abnormal outcome requests an automatic retry. A later human prompt can ask to continue in any language; the model reads the stopped goal and uses the goal tool's resume action, which records a new revision and arms continuation.
 
-### Durability and cancellation seam
+### Durability and cancellation contract
 
 Every `goal/changed` notification creates a checkpoint obligation. The driver awaits `ctx.sessions.flush(session)` before reserving work, then checks for a newer mutation, agent lifecycle change, or competing prompt. Turn-end flush failure is reported by the existing `agent/error` notification after `turn/end`; the driver finds that exact closed turn even when a concurrent one-shot injection appended a later turn, associates the failure with the exact attempt, and disarms before the next idle decision.
 
@@ -75,7 +75,7 @@ The core cancellation test proves notification order and containment: observers
 
 ## Alternatives considered
 
-- **Add a goal loop inside `dsh-agent-loop`** — rejected because the public queue, prompt, session, cancellation, and status seams are sufficient, and a concrete-loop branch would privilege one policy.
+- **Add a goal loop inside `dsh-agent-loop`** — rejected because the public queue, prompt, session, cancellation, and status contracts are sufficient, and a concrete-loop branch would privilege one policy.
 - **Use `agent/turn-continuation` to make every round another step** — rejected because a goal round is an outer policy iteration and must have its own durable user prompt, turn boundary, round count, and failure settlement.
 - **Persist a pending reservation** — rejected because a crash cannot prove that queued process memory had reached admission; only the durable `user/message` consumes the round.
 - **Retry provider or persistence errors automatically** — rejected because retry policy spends resources and needs explicit authority; stopped phases plus later human resume are simpler and observable.
diff --git a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
index 309b5ce45c..a41d9705e1 100644
--- a/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md
@@ -49,7 +49,7 @@ Status: implemented
 
 异常结果都不会请求自动重试。之后的人类提示词可以用任何语言要求继续；模型读取已停止目标并调用目标工具的 resume 动作，记录新修订并重新激活继续执行。
 
-### 持久性与取消 seam
+### 持久性与取消约定
 
 每次 `goal/changed` 通知都会产生一个检查点义务。驱动器在预留工作前等待 `ctx.sessions.flush(session)`，随后检查是否出现了更新的变更、agent 生命周期变化或竞争提示词。轮次结束时的 flush 失败会在 `turn/end` 之后通过现有 `agent/error` 通知报告；即使并发的一次性注入已追加后续轮次，驱动器仍会找到对应的同一个已关闭轮次，把失败关联到对应的同一次尝试，并在下一次空闲决策前解除激活。
 
@@ -75,7 +75,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-- **在 `dsh-agent-loop` 内添加目标循环**——不予采纳，因为公共队列、提示词、会话、取消和状态 seam 已经足够，具体循环分支还会赋予某种策略特权。
+- **在 `dsh-agent-loop` 内添加目标循环**——不予采纳，因为公共队列、提示词、会话、取消和状态约定已经足够，具体循环分支还会赋予某种策略特权。
 - **使用 `agent/turn-continuation` 把每个 Round 变成另一个步骤**——不予采纳，因为 Goal Round 是外层策略迭代，必须拥有自己的持久用户提示词、轮次边界、Round 计数和失败结算。
 - **持久化待处理预留**——不予采纳，因为崩溃无法证明进程内队列已经达到接纳点；只有持久 `user/message` 才消耗回合。
 - **自动重试提供方或持久化错误**——不予采纳，因为重试会消耗资源，需要显式授权；停止阶段加之后的人类恢复更简单，也可观察。
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
index 900165a080..bd135deda4 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.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 .agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
-2026-07-20-code-mode-typed-tool-returns.md: 2081d8161f0ee14493a09762b18ec7d9d07ea3c4
-2026-07-20-code-mode-typed-tool-returns.zh.md: 808f8f96dbb1655dc00d1ccd9bb7f7ac93c9550f
+2026-07-20-code-mode-typed-tool-returns.md: 059c715e35fb856e92d35926e6133701e5602c97
+2026-07-20-code-mode-typed-tool-returns.zh.md: 1bb88d29ffd96d65ce06033202499d2780814abd
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
index 2081d8161f..059c715e35 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md
@@ -51,9 +51,9 @@ declare const tools: {
 
 Before dispatch the bridge snapshots binding arguments as lossless JSON and snapshots the detached value again for an independent durable summary event. Host-side detachment, immutable execution, and output-schema projection all use iterative traversals rather than nested structured clone or recursive freezing. `undefined`, non-finite numbers, `-0`, sparse arrays, cycles, functions, and exotic objects reject that call before the tool runs. Successful dispatch returns `ToolExecutionResult.value`; Native `content`, metadata, and internal error information do not cross to the program.
 
-Code Mode declares its rejection capability on the runtime request as `{ name: "ToolCallError", memberNameProperty: "toolName" }`. The runtime seam treats those names as data: the worker materializes and injects the actual constructor used for `tools` binding failures, so `error instanceof ToolCallError` works without making a generic runtime know about tools. The worker constructs failures and defines their public fields through module-captured error and property-definition intrinsics plus null-prototype descriptors, so model mutations cannot replace the promised rejection with a worker failure. The error has the standard `Error` message plus the exact `toolName`; it deliberately omits `ToolFailure.info`, error codes, and Native content. This is an exception contract for control flow, not a failure union for programmatic classification.
+Code Mode declares its rejection capability on the runtime request as `{ name: "ToolCallError", memberNameProperty: "toolName" }`. The runtime Service Definition treats those names as data: the worker materializes and injects the actual constructor used for `tools` binding failures, so `error instanceof ToolCallError` works without making a generic runtime know about tools. The worker constructs failures and defines their public fields through module-captured error and property-definition intrinsics plus null-prototype descriptors, so model mutations cannot replace the promised rejection with a worker failure. The error has the standard `Error` message plus the exact `toolName`; it deliberately omits `ToolFailure.info`, error codes, and Native content. This is an exception contract for control flow, not a failure union for programmatic classification.
 
-Binding arguments and resolutions are revalidated as lossless JSON on both sides of the hostile worker protocol and have no byte cap. Before crossing through structured clone, each detached value is encoded as a flat pre-order token stream whose transport nesting is bounded; the receiver rebuilds it iteratively. Valid application nesting therefore has neither a JavaScript call-stack depth cap nor a platform-specific nested structured-clone limit. At module initialization the worker captures its own realm's `Array.prototype` and `Object.prototype` identities, the native function-source intrinsic used only to recognize foreign-realm plain-container prototypes, and every structural and metering intrinsic used by the JSON boundary. Property writes use null-prototype descriptors, while private array and set operations invoke captured methods without consulting mutable global or prototype slots. Model code can therefore replace helpers such as `Object.keys`, `Array.isArray`, collection methods, string methods, or `Buffer.byteLength`, rewrite intrinsic-prototype constructor slots, or add descriptor-shaped fields to `Object.prototype` without changing validation, wire transport, or byte accounting. The foreign-realm native function-source check still rejects user-authored constructors that imitate `Object` or `Array`. The dependency-light runtime seam names its structural equivalent `CodeJsonValue` so it need not depend on the session-owned canonical type; the generated SDK and tool API use `JsonValue`. Intermediate values are not prompt-truncated, context-spilled, or persisted. This preserves full acquired search, workflow, task, filesystem, and MCP values for programmatic filtering while leaving provider and executor acquisition limits truthful.
+Binding arguments and resolutions are revalidated as lossless JSON on both sides of the hostile worker protocol and have no byte cap. Before crossing through structured clone, each detached value is encoded as a flat pre-order token stream whose transport nesting is bounded; the receiver rebuilds it iteratively. Valid application nesting therefore has neither a JavaScript call-stack depth cap nor a platform-specific nested structured-clone limit. At module initialization the worker captures its own realm's `Array.prototype` and `Object.prototype` identities, the native function-source intrinsic used only to recognize foreign-realm plain-container prototypes, and every structural and metering intrinsic used by the JSON boundary. Property writes use null-prototype descriptors, while private array and set operations invoke captured methods without consulting mutable global or prototype slots. Model code can therefore replace helpers such as `Object.keys`, `Array.isArray`, collection methods, string methods, or `Buffer.byteLength`, rewrite intrinsic-prototype constructor slots, or add descriptor-shaped fields to `Object.prototype` without changing validation, wire transport, or byte accounting. The foreign-realm native function-source check still rejects user-authored constructors that imitate `Object` or `Array`. The dependency-light runtime Service Definition names its structural equivalent `CodeJsonValue` so it need not depend on the session-owned canonical type; the generated SDK and tool API use `JsonValue`. Intermediate values are not prompt-truncated, context-spilled, or persisted. This preserves full acquired search, workflow, task, filesystem, and MCP values for programmatic filtering while leaving provider and executor acquisition limits truthful.
 
 ### Outer result and output ledger
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
index 808f8f96db..1bb88d29ff 100644
--- a/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.zh.md
@@ -51,9 +51,9 @@ declare const tools: {
 
 分发前，桥接层会把绑定参数快照为无损 JSON，再对分离后的值生成一次快照，供独立的持久摘要事件使用。宿主侧的值分离、执行数据的不可变处理与输出 schema 投影均采用迭代遍历，而不使用嵌套结构化克隆或递归冻结。`undefined`、非有限数、`-0`、稀疏数组、循环引用、函数和非普通对象都会使该调用在工具运行前被拒绝。成功分发会返回 `ToolExecutionResult.value`；Native `content`、元数据和内部错误信息不会传入程序。
 
-Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProperty: "toolName" }` 声明其以异常拒绝 Promise 的能力。运行时 seam 只把这些名称视为数据：worker 会动态生成并注入真正用于 `tools` 绑定失败的构造函数，因此无需让通用运行时了解工具，`error instanceof ToolCallError` 也能成立。worker 使用模块初始化时捕获的 Error 构造函数与属性定义内建方法，配合原型为 null 的属性描述符，构造失败对象并定义其公开字段，因此模型代码的修改不会把约定承诺的 reject 变成 worker 失败。该错误包含标准的 `Error` 消息和确切的 `toolName`，并有意省略 `ToolFailure.info`、错误代码与 Native 内容。这是一项用于控制流的异常约定，而不是供程序分类的失败联合。
+Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProperty: "toolName" }` 声明其以异常拒绝 Promise 的能力。运行时 Service Definition 只把这些名称视为数据：worker 会动态生成并注入真正用于 `tools` 绑定失败的构造函数，因此无需让通用运行时了解工具，`error instanceof ToolCallError` 也能成立。worker 使用模块初始化时捕获的 Error 构造函数与属性定义内建方法，配合原型为 null 的属性描述符，构造失败对象并定义其公开字段，因此模型代码的修改不会把约定承诺的 reject 变成 worker 失败。该错误包含标准的 `Error` 消息和确切的 `toolName`，并有意省略 `ToolFailure.info`、错误代码与 Native 内容。这是一项用于控制流的异常约定，而不是供程序分类的失败联合。
 
-绑定参数与绑定返回值会在不可信 worker 协议的两端重新校验为无损 JSON，且不设字节上限。每个分离后的值在通过结构化克隆跨越边界前，都会编码为扁平的前序 token 流，其传输结构的嵌套深度有界；接收方再以迭代方式重建该值。因此，有效应用数据的嵌套深度既不受 JavaScript 调用栈深度上限限制，也不受特定平台对嵌套结构化克隆施加的上限限制。模块初始化时，worker 会捕获自身 JavaScript 运行域中 `Array.prototype` 和 `Object.prototype` 的引用、仅用于识别其他运行域普通容器原型、可获取原生函数源码的内建函数，以及 JSON 边界用于结构处理和计量的全部内建方法。属性写入使用原型为 null 的属性描述符；内部的数组与集合操作直接调用捕获的方法，不会访问可变的全局或原型槽位。因此，即使模型代码替换 `Object.keys`、`Array.isArray`、集合方法、字符串方法或 `Buffer.byteLength` 等辅助方法，重写内建原型的构造函数槽位，或向 `Object.prototype` 添加形如属性描述符的字段，也不会改变校验、协议传输或字节计量。面向其他运行域的原生函数源码检查仍会拒绝由用户编写、冒充 `Object` 或 `Array` 的构造函数。为保持依赖轻量，运行时 seam 将结构等价类型命名为 `CodeJsonValue`，从而无需依赖会话侧拥有的规范类型；生成的 SDK 和工具 API 则使用 `JsonValue`。这些值不会经过提示词截断、上下文输出落盘或持久化。因此，程序可以完整筛选已经采集的搜索、工作流、任务、文件系统与 MCP 值，同时提供方和执行器的采集上限仍会实际生效。
+绑定参数与绑定返回值会在不可信 worker 协议的两端重新校验为无损 JSON，且不设字节上限。每个分离后的值在通过结构化克隆跨越边界前，都会编码为扁平的前序 token 流，其传输结构的嵌套深度有界；接收方再以迭代方式重建该值。因此，有效应用数据的嵌套深度既不受 JavaScript 调用栈深度上限限制，也不受特定平台对嵌套结构化克隆施加的上限限制。模块初始化时，worker 会捕获自身 JavaScript 运行域中 `Array.prototype` 和 `Object.prototype` 的引用、仅用于识别其他运行域普通容器原型、可获取原生函数源码的内建函数，以及 JSON 边界用于结构处理和计量的全部内建方法。属性写入使用原型为 null 的属性描述符；内部的数组与集合操作直接调用捕获的方法，不会访问可变的全局或原型槽位。因此，即使模型代码替换 `Object.keys`、`Array.isArray`、集合方法、字符串方法或 `Buffer.byteLength` 等辅助方法，重写内建原型的构造函数槽位，或向 `Object.prototype` 添加形如属性描述符的字段，也不会改变校验、协议传输或字节计量。面向其他运行域的原生函数源码检查仍会拒绝由用户编写、冒充 `Object` 或 `Array` 的构造函数。为保持依赖轻量，运行时 Service Definition 将结构等价类型命名为 `CodeJsonValue`，从而无需依赖会话侧拥有的规范类型；生成的 SDK 和工具 API 则使用 `JsonValue`。这些值不会经过提示词截断、上下文输出落盘或持久化。因此，程序可以完整筛选已经采集的搜索、工作流、任务、文件系统与 MCP 值，同时提供方和执行器的采集上限仍会实际生效。
 
 ### 外层结果与输出账本
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
index 5fd9467179..535d2a86a4 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.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 .agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
-2026-07-25-workspace-ui-product-flow.md: 7a6a41e19d2930fbcbf7ba5fc9e6809d96e23166
-2026-07-25-workspace-ui-product-flow.zh.md: 14f33b0eebcf8885670e72cfb6e2c9a87b7a3432
+2026-07-25-workspace-ui-product-flow.md: bfdde9797433eca67e47da73468cba855f2a02b9
+2026-07-25-workspace-ui-product-flow.zh.md: 74a9dd6f70396201a78f3204bfdc7d8b5d4f5d98
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
index 7a6a41e19d..bfdde97974 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md
@@ -82,7 +82,7 @@ Deleting a Workspace registration removes its group without deleting or closing
 
 React components only consume `useSessions`, `useWorkspaces`, and session-scoped hooks; they do not own entity lifecycles. The Zustand store retains only layout, the current view, composer text for ordinary real Sessions, and other purely presentational state. Session and Workspace Intents, materialization phases, errors, and retained prompts reside in the React-free runtime object layer.
 
-The Sidebar and conversation empty hero receive standardized actions through slots: `startSession`, `updateSessionPrompt`, `sendSession`, `open`, and `toggleSidebar`. The Workspace picker reuses the same component and the `createWorkspace` seam; its owner supplies only popover state, an anchor, and a selection callback. The presentation layer does not send `host/workspace-changed` directly; Host events originate only from Host mutations and the stream adapter.
+The Sidebar and conversation empty hero receive standardized actions through slots: `startSession`, `updateSessionPrompt`, `sendSession`, `open`, and `toggleSidebar`. The Workspace picker reuses the same component and the `createWorkspace` action; its owner supplies only popover state, an anchor, and a selection callback. The presentation layer does not send `host/workspace-changed` directly; Host events originate only from Host mutations and the stream adapter.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
index 14f33b0eeb..74a9dd6f70 100644
--- a/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.zh.md
@@ -82,7 +82,7 @@ Workspace 组严格使用 Host 返回的持久顺序。Bootstrap 一次性确定
 
 React 组件只消费 `useSessions`、`useWorkspaces` 与 session-scoped 钩子，不拥有实体生命周期。Zustand store 只保留布局、当前 view、普通真实 Session 的 composer 文本和其他纯呈现状态；Session/Workspace Intent、materialize phase、错误和 retained prompt 位于 React-free 运行时对象层。
 
-Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSession`、`updateSessionPrompt`、`sendSession`、`open` 与 `toggleSidebar`。Workspace picker 复用同一组件与 `createWorkspace` seam；owner 只提供 popover 开关、锚点和选中回调。呈现层不直接发送 `host/workspace-changed`，Host 事件只由 Host mutation 与流适配器产生。
+Sidebar 与 conversation empty hero 通过 slot 获得标准化动作：`startSession`、`updateSessionPrompt`、`sendSession`、`open` 与 `toggleSidebar`。Workspace picker 复用同一组件与 `createWorkspace` 动作；owner 只提供 popover 开关、锚点和选中回调。呈现层不直接发送 `host/workspace-changed`，Host 事件只由 Host mutation 与流适配器产生。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml
index f44f0911f5..71cb05f10a 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.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 .agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
-2026-07-26-code-dispatch-log-spill.md: eee8fb73b3f1ddba0a2da3ad5a9d2d4417d5951c
-2026-07-26-code-dispatch-log-spill.zh.md: 3ef95b5bc0aec1238fd9bb89f545b7f23938ea79
+2026-07-26-code-dispatch-log-spill.md: 3892a4a5a21c03d97d1873c68e2228119010e5c5
+2026-07-26-code-dispatch-log-spill.zh.md: c98b29e491e059fe27eb5b1ccea1b9664dce4639
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
index eee8fb73b3..3892a4a5a2 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
@@ -14,8 +14,8 @@ Since the full-content dispatch logging landed, a `run_code` program that reads
 
 **A log-shaping waterfall on the registry, and the spill policy as its first listener.**
 
-- **Seam**: `tools/code-dispatch-log` — a scope-filtered waterfall the bridge runs (via the registry's PRIVATE `shapeDispatchLog` invoker, handed to the bridge as a capability closure in `RunCodeBridgeOptions` — the waterfall is the public seam, the invoker never widens the service surface; contained: a throwing listener falls back to the unshaped content, with total error formatting so a hostile thrown value cannot escape the containment) over each settled sub-dispatch before appending `tool/code-dispatch`. The payload (`CodeDispatchLog`) carries the outer execution, the hoisted `agent` routing key, the sub-call identity, and the default content — the RENDERED result projection a native `tool/result` would carry (the program itself received the structured `value`). Only the durable copy is shapeable; the model sees neither. Shaping runs OFF the program path as tracked side work, but bounded: past `maxParallelSubCalls` pending log tasks the ordered commit lane holds, so a slow spill backend backpressures the run instead of accumulating unbounded pending I/O; run settlement still drains every task inside the open turn.
-- **Policy**: `dsh-spill-policy` registers a second arm on the new seam sharing the exact replacement pipeline of its model-facing arm (same `maxInlineBytes` cap, same preview + locator + within-cap invariant, same best-effort fallbacks), with the artifact labeled `dispatch` under the sub-call id. UIs and replay read the full text through the spill artifact exactly as they do for spilled native results, so the native-parity rendering story survives bounding.
+- **Extension point**: `tools/code-dispatch-log` — a scope-filtered waterfall the bridge runs (via the registry's PRIVATE `shapeDispatchLog` invoker, handed to the bridge as a capability closure in `RunCodeBridgeOptions` — the waterfall is the public contract, the invoker never widens the service surface; contained: a throwing listener falls back to the unshaped content, with total error formatting so a hostile thrown value cannot escape the containment) over each settled sub-dispatch before appending `tool/code-dispatch`. The payload (`CodeDispatchLog`) carries the outer execution, the hoisted `agent` routing key, the sub-call identity, and the default content — the RENDERED result projection a native `tool/result` would carry (the program itself received the structured `value`). Only the durable copy is shapeable; the model sees neither. Shaping runs OFF the program path as tracked side work, but bounded: past `maxParallelSubCalls` pending log tasks the ordered commit lane holds, so a slow spill backend backpressures the run instead of accumulating unbounded pending I/O; run settlement still drains every task inside the open turn.
+- **Policy**: `dsh-spill-policy` registers a second arm on the new extension point sharing the exact replacement pipeline of its model-facing arm (same `maxInlineBytes` cap, same preview + locator + within-cap invariant, same best-effort fallbacks), with the artifact labeled `dispatch` under the sub-call id. UIs and replay read the full text through the spill artifact exactly as they do for spilled native results, so the native-parity rendering story survives bounding.
 - **One deliberate asymmetry**: the model-facing arm skips `read` (the `read → spill → read again` loop); the dispatch-log arm bounds `read` sub-calls too — a log copy is not model context, so the loop cannot happen, and `read` is precisely the tool that produces huge logs.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
index 3ef95b5bc0..c98b29e491 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
@@ -14,8 +14,8 @@ Status: implemented
 
 **在注册表上增设一个日志整形 waterfall（瀑布式事件），spill 策略作为其第一个监听器。**
 
-- **seam**：`tools/code-dispatch-log`，一个按作用域过滤的 waterfall，由桥接层在追加 `tool/code-dispatch` 之前对每个已结算的子分发运行（经由注册表的私有 `shapeDispatchLog` 调用器——作为能力闭包经 `RunCodeBridgeOptions` 交给桥接层；waterfall 才是公开 seam，调用器绝不扩大服务接口。故障被兜住：监听器抛出异常时回退到未整形的内容，并用可处理任意抛出值的错误格式化，确保恶意抛出值无法逃出兜底）。载荷（`CodeDispatchLog`）携带外层执行、提升出来的 `agent` 路由键、子调用标识与默认内容——即原生 `tool/result` 所载的渲染后结果投影（程序本身收到的是结构化 `value`）。可整形的只有持久副本；模型两者都看不到。整形作为被跟踪的旁路工作在程序路径之外运行，但有界：待处理日志任务超过 `maxParallelSubCalls` 时有序提交通道会暂停，因此慢速 spill 后端会对整个 run 施加背压，而不是无限累积待完成 I/O；run 结算仍会在开放轮次内排空全部任务。
-- **策略**：`dsh-spill-policy` 在新 seam 上注册第二个分支，与其面向模型的分支共用一模一样的替换流水线（同样的 `maxInlineBytes` 上限、同样的预览 + 定位符 + 不超上限不变式、同样的尽力而为回退），产物以 `dispatch` 为标签，记在子调用 id 名下。UI 与回放通过 spill 产物读取全文，方式与读取被 spill 的原生结果完全相同，因此与原生同等保真的渲染在施加边界之后依然成立。
+- **扩展点**：`tools/code-dispatch-log`，一个按作用域过滤的 waterfall，由桥接层在追加 `tool/code-dispatch` 之前对每个已结算的子分发运行（经由注册表的私有 `shapeDispatchLog` 调用器——作为能力闭包经 `RunCodeBridgeOptions` 交给桥接层；waterfall 才是公开约定，调用器绝不扩大服务接口。故障被兜住：监听器抛出异常时回退到未整形的内容，并用可处理任意抛出值的错误格式化，确保恶意抛出值无法逃出兜底）。载荷（`CodeDispatchLog`）携带外层执行、提升出来的 `agent` 路由键、子调用标识与默认内容——即原生 `tool/result` 所载的渲染后结果投影（程序本身收到的是结构化 `value`）。可整形的只有持久副本；模型两者都看不到。整形作为被跟踪的旁路工作在程序路径之外运行，但有界：待处理日志任务超过 `maxParallelSubCalls` 时有序提交通道会暂停，因此慢速 spill 后端会对整个 run 施加背压，而不是无限累积待完成 I/O；run 结算仍会在开放轮次内排空全部任务。
+- **策略**：`dsh-spill-policy` 在新扩展点上注册第二个分支，与其面向模型的分支共用一模一样的替换流水线（同样的 `maxInlineBytes` 上限、同样的预览 + 定位符 + 不超上限不变式、同样的尽力而为回退），产物以 `dispatch` 为标签，记在子调用 id 名下。UI 与回放通过 spill 产物读取全文，方式与读取被 spill 的原生结果完全相同，因此与原生同等保真的渲染在施加边界之后依然成立。
 - **一处有意的不对称**：面向模型的分支跳过 `read`（避免 `read → spill → read again` 循环）；分发日志分支则连 `read` 子调用也施加边界：日志副本不是模型上下文，该循环因此不可能发生，而 `read` 恰恰是会产生巨大日志的那个工具。
 
 ## 曾考虑的替代方案
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
index f8ccab3362..e809bdfc6c 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.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 .agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
-2026-07-26-code-dispatch-ui-foundation.md: a1629c77304bc7ef744f7a09241bcdfc81e461ae
-2026-07-26-code-dispatch-ui-foundation.zh.md: 8f40281454e78d3d1baaf0dce3635bdf01d0a658
+2026-07-26-code-dispatch-ui-foundation.md: 1714472018a415114efed7ce189a3d82268dd8e3
+2026-07-26-code-dispatch-ui-foundation.zh.md: 8ede615bf15b99c5ecf9a8da427b571180921e54
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
index a1629c7730..1714472018 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-26-code-dispatch-ui-foundation.zh.md)
 
-> Scope: the host-side contract changes that let a UI render a Code Mode turn with the same fidelity as native tool calls — the first PR of the Code Mode web-UI stack. The [Code Mode foundation](2026-06-15-code-mode.md) owns the transport design; this note owns the model-visible `description` parameter, the full-content `tool/code-dispatch` payload, and the temporary `DSH_TOOLS_MODE` enablement seam for the `dsh` config tree.
+> Scope: the host-side contract changes that let a UI render a Code Mode turn with the same fidelity as native tool calls — the first PR of the Code Mode web-UI stack. The [Code Mode foundation](2026-06-15-code-mode.md) owns the transport design; this note owns the model-visible `description` parameter, the full-content `tool/code-dispatch` payload, and the temporary `DSH_TOOLS_MODE` enablement switch for the `dsh` config tree.
 
 ## Problem
 
@@ -16,7 +16,7 @@ Three changes, one per obstacle:
 
 1. **`run_code` gains a required `description` parameter** (bash's exact contract: active voice, 5-10 words, shown in the UI; whitespace-only rejected at execute). `presentCall` now titles the card with the description and moves the program to `rawInput`. The prompt-side cost is a few tokens per call; the return is that every surface — TUI card, ACP title, web row — gets a human-readable label without parsing TypeScript.
 2. **`tool/code-dispatch` logs the sub-call's complete model-facing outcome** — `content: ContentBlock[]` + `isError`, the `tool/result` vocabulary — replacing `resultSummary` and deleting the summarize/cwd-normalization machinery outright. A UI renders a sub-call through the identical code path as a native result, including error text and non-text blocks. The event stays log-only (`deriveMessages()` ignores it): nothing about model context changes.
-3. **`DSH_TOOLS_MODE` env var on the `dsh` config tree** (`native`|`code`|`both`; unset keeps the schema default): the `tools` row reads it via `!!js`, and the worker code runtime is mounted unconditionally (Loader metadata is static, so no conditional row exists; a native boot only registers the service — workers spawn per run). This is an explicitly temporary seam: per-session tool-mode selection owned by the web UI is the design goal, and the env var dies when that lands.
+3. **`DSH_TOOLS_MODE` env var on the `dsh` config tree** (`native`|`code`|`both`; unset keeps the schema default): the `tools` row reads it via `!!js`, and the worker code runtime is mounted unconditionally (Loader metadata is static, so no conditional row exists; a native boot only registers the service — workers spawn per run). This is an explicitly temporary configuration hook: per-session tool-mode selection owned by the web UI is the design goal, and the env var dies when that lands.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
index 8f40281454..8ede615bf1 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-26-code-dispatch-ui-foundation.md) | 中文
 
-> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧约定变更，即 Code Mode Web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用 seam，归本篇所有。
+> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧约定变更，即 Code Mode Web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用开关，归本篇所有。
 
 ## 问题
 
@@ -16,7 +16,7 @@ Status: implemented
 
 1. **`run_code` 新增必填的 `description` 参数**（与 bash 完全相同的约定：主动语态、5-10 个词、展示在 UI 中；仅含空白的取值在执行时被拒绝）。`presentCall` 现在以该 description 作为卡片标题，并把程序文本移入 `rawInput`。提示词侧的成本是每次调用多出几个 token；换来的是每个表面——TUI 卡片、ACP（Agent Client Protocol）标题、Web 行——都无需解析 TypeScript 就能获得可供人阅读的标签。
 2. **`tool/code-dispatch` 记录子调用面向模型的完整结果**（`content: ContentBlock[]` 加 `isError`，即 `tool/result` 的词汇），取代 `resultSummary`，并把摘要与 cwd 归一化机制彻底删除。UI 渲染子调用走的代码路径与渲染原生结果完全相同，包括错误文本和非文本块。该事件保持仅日志（`deriveMessages()` 忽略它）：模型上下文没有任何变化。
-3. **`dsh` 配置树上的 `DSH_TOOLS_MODE` 环境变量**（`native`|`code`|`both`；未设置时保持 schema 默认值）：`tools` 行通过 `!!js` 读取它，worker 代码运行时则无条件挂载（loader 元数据是静态的，因此不存在条件行；native 启动只是注册该服务，worker 要到每次运行时才 spawn）。这是一个明确标注为临时的 seam：设计目标是让 Web UI 拥有按会话的工具模式选择，该目标落地后，这个环境变量随即退役。
+3. **`dsh` 配置树上的 `DSH_TOOLS_MODE` 环境变量**（`native`|`code`|`both`；未设置时保持 schema 默认值）：`tools` 行通过 `!!js` 读取它，worker 代码运行时则无条件挂载（loader 元数据是静态的，因此不存在条件行；native 启动只是注册该服务，worker 要到每次运行时才 spawn）。这是一个明确标注为临时的配置钩子：设计目标是让 Web UI 拥有按会话的工具模式选择，该目标落地后，这个环境变量随即退役。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml
index 1f1ab7d8d2..63a7bda71b 100644
--- a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.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 .agents/notes/implemented/feature/2026-07-27-tmux-location-context.md
-2026-07-27-tmux-location-context.md: dc9e559d1ed5cbb419901303a81e69cb0d0ba828
-2026-07-27-tmux-location-context.zh.md: 9c8a56f12406ff17ce9c25538dcfdf8e7aa06f91
+2026-07-27-tmux-location-context.md: 2a2188c920b678565173d28fb18268f951cc9a11
+2026-07-27-tmux-location-context.zh.md: c0f6e9f5ca56bef9794f55e72ffbbe3ee1be7240
diff --git a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md
index dc9e559d1e..2a2188c920 100644
--- a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md
+++ b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.md
@@ -52,7 +52,7 @@ Unit tests pin: first-step injection and source/surface metadata; the `$TMUX_PAN
 
 - **Push from a tmux hook / background watcher** — rejected: requires installing hooks in the user's tmux and a background process with teardown, to gain mid-step freshness that per-turn context does not need.
 - **Run every step** — rejected: location is stable within a turn; re-querying adds token cost without new information. Gating on `step === 1` yields per-turn readings.
-- **Raw `child_process`** — rejected: bypasses the sandbox/policy seam and hand-rolls subprocess code the `ctx.bash` executor already owns.
+- **Raw `child_process`** — rejected: bypasses the sandbox policy path and hand-rolls subprocess code the `ctx.bash` executor already owns.
 - **Include pane/window pixel sizes** — rejected: sizes churn on every resize and add noise; the layout tree already conveys structure.
 - **Scrape sibling panes with `capture-pane`** — rejected: large, noisy, and privacy-sensitive; out of scope for "own location".
 - **Dynamic system-prompt section** — rejected: replacing a value erases the earlier readings behind prior reasoning and is not reconstructable; one durable attributed message records each location where it became visible.
diff --git a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md
index 9c8a56f124..c0f6e9f5ca 100644
--- a/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-tmux-location-context.zh.md
@@ -52,7 +52,7 @@ window active=<0|1>, pane active=<0|1>, layout <window-layout>
 
 - **由 tmux hook / 后台监视器推送**——否决：需要在用户的 tmux 中安装 hook，并引入带清理的后台进程，只为换取按轮次上下文并不需要的步内新鲜度。
 - **每个 step 都运行**——否决：位置在一轮内稳定；重复查询只增加 token 成本而无新信息。以 `step === 1` 为门槛得到按轮次读数。
-- **裸 `child_process`**——否决：绕过沙箱/策略 seam，并手写 `ctx.bash` 执行器已拥有的子进程代码。
+- **裸 `child_process`**——否决：绕过沙箱策略路径，并手写 `ctx.bash` 执行器已拥有的子进程代码。
 - **包含 pane/window 像素尺寸**——否决：尺寸每次缩放都变动、徒增噪声；布局树已传达结构。
 - **用 `capture-pane` 抓取相邻 pane**——否决：庞大、嘈杂且涉及隐私；超出"自身位置"范围。
 - **动态系统提示区块**——否决：替换某个值会抹去支撑先前推理的历史读数且不可重建；单条持久且带来源的消息在每个位置变得可见时予以记录。
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
index e3e6e045f8..912cc3a7d7 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.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 .agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: c5c6c4eac053e9a3adfa2a2a441ac492ba3391ac
-2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: fe0e93cd13d0decb8d6a95abb0c5feb141dcb78b
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.md: e4ceeb6b1bc0b9e10fb5383454cbac1b404d4ad8
+2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md: 18e5c891f5810135b1ed5e6cfc27b94ad452c575
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
index c5c6c4eac0..e4ceeb6b1b 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md
@@ -10,7 +10,7 @@ The stdio JSON-RPC serving surface (`@deepseek-ai/dsh-jsonrpc`, the [single-exe
 
 ## Decision
 
-Three packages, layered exactly like the existing Python stack, plus one seam registration:
+Three packages, layered exactly like the existing Python stack, plus one Service provider registration:
 
 - **`@deepseek-ai/dsh-sdk-protocol`** (`packages/scaffold/protocol/`) — the wire made shared and nominal. `JsonRpcLineTransport` moves here verbatim from `dsh-jsonrpc` (which now imports it), and `types.ts` names every payload the server speaks: `InitializeParams/Result`, `SessionPromptParams/Result`, the four notification payloads, and the `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` indexes. The package root explicitly exports that complete interface and provides no source-module deep imports. The server's `notify()` call sites are typed against these named payloads, so server drift breaks compilation, not clients. One behavioral change: an error response now rejects with `JsonRpcResponseError` carrying the wire `code`/`data` (the Python client already preserved these; the old transport threw a bare `Error` with only the message).
 - **`@deepseek-ai/dsh-sdk-client`** (`packages/scaffold/client/`) — the TypeScript twin of `python/sdk`: `HarnessClient` (spawn, frame, fan out notifications, typed error surfaces, close-to-quiescence via the shared dispose ladder) under `DeepSeekHarness`/`HarnessSession` (lazy start, memoized `initialize`, `run()` pairing one `session/prompt` with its `session.finished`). Its package-root consumer interface explicitly exports both client layers, caller-facing types, and the protocol-owned `JsonRpcResponseError`; source modules, normalization helpers, and the notification producer stay internal. `TurnResult.events` contains only the root session's typed events, while `notifications` retains session ids across the root and descendants discovered from `subagent.started`; session-tree scoping is client-side, mirroring `client.py`. Deliberate asymmetries with Python: the launch spec is explicit `command`/`args` (no bundled-runtime resolution — that is a distribution concern with no TS consumer yet); `env` replaces rather than merges (callers own credential policy; `scrubbedParentEnv` from the subprocess seam is one import away); `TurnResult` carries the structured `reason` (Python exposes only `status`); teardown walks a private stdin-EOF → SIGTERM → SIGKILL ladder to actual exit (the client runs outside any harness context, so it cannot ride `ctx.subprocess`).
@@ -30,7 +30,7 @@ Four tiers, per [testing policy](../../../../docs/testing.md):
 
 ## Alternatives considered
 
-**Import wire types from `dsh-jsonrpc` instead of extracting a protocol package.** Makes every SDK consumer (including `subagent-dsh-sdk`, which must not serve JSON-RPC) depend on the server plugin and its `dsh-agent`/`dsh-llm-deepseek` peer set, and leaves the notification payloads anonymous. The capability-seam rule (interface/implementation/consumer as separate packages) already names this shape; the transport is genuinely two-sided.
+**Import wire types from `dsh-jsonrpc` instead of extracting a protocol package.** Makes every SDK consumer (including `subagent-dsh-sdk`, which must not serve JSON-RPC) depend on the server plugin and its `dsh-agent`/`dsh-llm-deepseek` peer set, and leaves the notification payloads anonymous. The capability-seam rule (Service Definition / Service provider / Consumer as separate packages) already names this shape; the transport is genuinely two-sided.
 
 **Have `subagent-dsh-sdk` speak raw JSON-RPC without the client SDK.** Duplicates the request/notification pairing, subscription fan-out, timeout, and teardown logic the SDK exists to own; the user's ask was explicitly a backend that *uses* the SDK, and the layering earns its keep by making the backend ~200 lines of policy over a reusable client.
 
@@ -38,7 +38,7 @@ Four tiers, per [testing policy](../../../../docs/testing.md):
 
 **Give the TS SDK bundled-runtime resolution parity with Python.** Python's carrier resolution exists to ship wheels to users without Node. A TypeScript consumer definitionally has Node and (in-repo) the workspace; inventing a distribution story with no consumer violates the require-current-need rule. Deferred until a real npm-distribution consumer appears.
 
-**Export source modules, normalization helpers, and subscription producer operations.** These are implementation seams with no caller need; exposing them would make callers learn how the client validates and distributes wire input. The package roots instead enumerate the supported client and protocol interfaces, and the client re-exports the one protocol error callers must distinguish.
+**Export source modules, normalization helpers, and subscription producer operations.** These are implementation details with no caller need; exposing them would make callers learn how the client validates and distributes wire input. The package roots instead enumerate the supported client and protocol interfaces, and the client re-exports the one protocol error callers must distinguish.
 
 **Reuse `dsh-acp-snapshot`'s `runScenario` for the SDK snapshots.** That harness speaks ACP (`ClientSideConnection`, `InputStep` scripts). The SDK suite's whole point is to drive the *SDK client* as the entry surface; it reuses the normalize/refresh library layer (`normalizeSessionLog`, `refreshFixtureReplacements`, …) and leaves the ACP driver alone.
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
index fe0e93cd13..18e5c891f5 100644
--- a/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.zh.md
@@ -10,7 +10,7 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 ## 决策
 
-三个包，分层与既有 Python 栈完全一致，外加一个 seam 注册：
+三个包，分层与既有 Python 栈完全一致，外加一个 Service provider 注册：
 
 - **`@deepseek-ai/dsh-sdk-protocol`**（`packages/scaffold/protocol/`）—— 把线协议做成共享且具名。`JsonRpcLineTransport` 从 `dsh-jsonrpc` 原样移入（后者现在导入它），`types.ts` 为服务器所说的每个载荷命名：`InitializeParams/Result`、`SessionPromptParams/Result`、四个通知载荷，以及 `HarnessSdkRequestMap`/`HarnessSdkNotificationMap` 索引。该包根显式导出这一完整接口，且不提供指向源模块的深层导入。服务器的 `notify()` 调用点以这些具名载荷标注类型，服务器漂移会先破坏编译而不是破坏客户端。一处行为变化：错误响应现在以携带线上 `code`/`data` 的 `JsonRpcResponseError` 拒绝（Python 客户端本就保留这些；旧传输只抛携带消息的裸 `Error`）。
 - **`@deepseek-ai/dsh-sdk-client`**（`packages/scaffold/client/`）—— `python/sdk` 的 TypeScript 孪生：`HarnessClient`（spawn、分帧、通知扇出、有类型的错误表面、经共享 dispose（资源释放）阶梯关闭至完全停稳）之上是 `DeepSeekHarness`/`HarnessSession`（惰性启动、记忆化 `initialize`、`run()` 把一个 `session/prompt` 与其 `session.finished` 配对）。其包根消费方接口显式导出两层客户端、面向调用方的类型，以及协议包所拥有的 `JsonRpcResponseError`；源模块、规范化辅助函数和通知投递端都保留为内部实现。`TurnResult.events` 只包含根会话的类型化事件，而 `notifications` 则保留根会话及从 `subagent.started` 发现的后代各自的会话 id；基于 `subagent.started` 血缘边的会话树范围限定在客户端完成，镜像 `client.py`。与 Python 的刻意不对称：启动规格是显式 `command`/`args`（无捆绑运行时解析——那是尚无 TS 消费方的发行问题）；`env` 整体替换而非合并（凭据策略归调用方；subprocess seam 的 `scrubbedParentEnv` 一个 import 即得）；`TurnResult` 携带结构化 `reason`（Python 只暴露 `status`）；拆除走私有的 stdin-EOF → SIGTERM → SIGKILL 阶梯直到真正退出（客户端运行在任何 harness 上下文之外，无法搭乘 `ctx.subprocess`）。
@@ -30,7 +30,7 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 ## 考虑过的替代方案
 
-**从 `dsh-jsonrpc` 导入线类型而不是提取协议包。** 会让每个 SDK 消费方（包括绝不能提供 JSON-RPC 服务的 `subagent-dsh-sdk`）依赖服务器插件及其 `dsh-agent`/`dsh-llm-deepseek` peer 集合，且通知载荷仍然匿名。能力 seam 规则（接口/实现/消费方三个包分立）已经点名了这种形态；这个传输是货真价实的双边物。
+**从 `dsh-jsonrpc` 导入线类型而不是提取协议包。** 会让每个 SDK 消费方（包括绝不能提供 JSON-RPC 服务的 `subagent-dsh-sdk`）依赖服务器插件及其 `dsh-agent`/`dsh-llm-deepseek` peer 集合，且通知载荷仍然匿名。能力 seam 规则（Service Definition/Service provider/Consumer 三个包分立）已经点名了这种形态；这个传输是货真价实的双边物。
 
 **让 `subagent-dsh-sdk` 直说裸 JSON-RPC、绕开客户端 SDK。** 会复制 SDK 存在意义所在的请求/通知配对、订阅扇出、超时与拆除逻辑；用户的要求明确是一个*使用* SDK 的后端，分层的回报是后端成为可复用客户端之上约 200 行的纯策略。
 
@@ -38,7 +38,7 @@ stdio JSON-RPC 对外服务接口（`@deepseek-ai/dsh-jsonrpc`，见[单文件
 
 **给 TS SDK 与 Python 对等的捆绑运行时解析。** Python 的载体解析是为了给没有 Node 的用户发 wheel。TypeScript 消费方按定义就有 Node，且仓库内消费方还有工作区；为尚不存在的消费方编造发行方案违反「只实现当前需求」的规则。推迟到真实的 npm 发行消费方出现时再处理。
 
-**导出源模块、规范化辅助函数和订阅投递端操作。** 这些都是调用方不需要的实现 seam；暴露它们会让调用方不得不理解客户端如何校验与分发线输入。各包根转而枚举受支持的客户端接口与协议接口，客户端则只重新导出调用方必须区分的那一种协议错误。
+**导出源模块、规范化辅助函数和订阅投递端操作。** 这些都是调用方不需要的实现细节；暴露它们会让调用方不得不理解客户端如何校验与分发线输入。各包根转而枚举受支持的客户端接口与协议接口，客户端则只重新导出调用方必须区分的那一种协议错误。
 
 **复用 `dsh-acp-snapshot` 的 `runScenario` 做 SDK 快照。** 那个 harness 说 ACP（`ClientSideConnection`、`InputStep` 脚本）。SDK 套件的全部意义就是以 *SDK 客户端*为入口表面；它复用 normalize/refresh 库层（`normalizeSessionLog`、`refreshFixtureReplacements`……），不动 ACP 驱动器。
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index e6cb63c10d..5a47ad865c 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: 46c4949c56ebffe78e5ffda126a5784a1c648421
-2026-07-27-web-subagent-conversations.zh.md: f06e5f38ba49d35ac28582f1ad3ff5eebc8ace15
+2026-07-27-web-subagent-conversations.md: 42b1a553adc0222d33feeea21fa5690235d6e5e3
+2026-07-27-web-subagent-conversations.zh.md: d373662987f7afc820b180b360493c5725f13617
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index 46c4949c56..42b1a553ad 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -47,7 +47,7 @@ Selecting a row records its exact address before opening the resident client `Se
 
 A one-shot row always replaces the composer with copy explaining that the execution record is read-only. A continuable row does so only while `parentAvailable` is false and the child is not running; a running parent-offline child keeps the ordinary composer with its input and Send action disabled so independent Stop stays reachable, and the read-only takeover returns once it stops. With a live parent, Enter and Send admit another FIFO turn even while the child runs, while independent Stop routes through `subagent.interrupt` ([interrupt contract](2026-08-06-continuable-subagent-interrupt.md)). Prompt failures retain the draft through the ordinary error behavior.
 
-Agent-bound auxiliary controls are unavailable in addressed child views. In particular, the model selector and `/model` contribution do not call ordinary `session.models` or `session.selectModel`; the Host also rejects any accidental call instead of activating persisted child history outside the direct-parent continuation seam.
+Agent-bound auxiliary controls are unavailable in addressed child views. In particular, the model selector and `/model` contribution do not call ordinary `session.models` or `session.selectModel`; the Host also rejects any accidental call instead of activating persisted child history outside the direct-parent continuation path.
 
 ## Host adapter and wire contract
 
@@ -89,7 +89,7 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 
 **Auto-resume an absent parent.** Rejected because continuation requires the exact live direct parent. Child navigation must not mutate the parent lifecycle.
 
-**Expose ordinary cancellation.** Rejected because the accepted inbox turn outlives its admission request and, at this decision's time, the continuation seam exposed no authority-safe cancellation handle. The later [current-turn interrupt contract](2026-08-06-continuable-subagent-interrupt.md) added that explicit authority as a dedicated subagent route; falling through to `session.cancel` remains rejected.
+**Expose ordinary cancellation.** Rejected because the accepted inbox turn outlives its admission request and, at this decision's time, the continuation contract exposed no authority-safe cancellation handle. The later [current-turn interrupt contract](2026-08-06-continuable-subagent-interrupt.md) added that explicit authority as a dedicated subagent route; falling through to `session.cancel` remains rejected.
 
 **Show only continuable children.** Rejected because the durable catalog deliberately describes both session-backed modes. One-shot transcripts remain useful even though they never accept follow-ups.
 
@@ -105,7 +105,7 @@ The shipped Web composition mounts SQLite session query beside JSONL persistence
 - Generic Host tests pin attached and cold history and forks without Agent publication, cold projection folding, descriptor/origin/runtime-owner denial, explicit-id adoption denial, and the direct queue-control fence.
 - Client object tests pin retained and restored addresses, one-shot read-only and cancel rejection, history routing, continuable prompt and interrupt routing, suppression of Agent-bound model controls, live activity flips including in-flight response replay and detach fallback, subagent-parent expandability flips, and membership refresh.
 - jsdom tests pin the aggregate descendant count and activity, sidebar propagation across nested lineage and ordinary-fork boundaries, row-status precedence, token totals, second-precision running and frozen inactive durations, adaptive long-duration units with exact accessible text, the summary-backed root action across absent and stale-empty catalogs, known loading-row shape, mixed-mode rows, pre-click leaf disclosure, diagnostics, lazy descendant disclosure, direct-parent addresses, keyboard behavior, and both read-only reasons.
-- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, and the aggregate running transition, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the model seam while it pins the aggregate running state in both the header and visible idle owner row, then cancels the turn during teardown.
+- The keyless assembled Web snapshot contains an inactive continuable child with durable usage, an inactive one-shot sibling with a deterministic long duration, and a persisted grandchild; it pins the three-descendant trigger across a stale empty catalog response, usage and timing rows, adaptive long-duration presentation, and the aggregate running transition, expands without activation, opens persisted history, admits a human FIFO follow-up, reconciles child mux events, and proves one-shot history remains read-only. A separate assembled scenario holds a real child Agent turn at the LLM seam while it pins the aggregate running state in both the header and visible idle owner row, then cancels the turn during teardown.
 - Navigation tests pin subagent-only breadcrumbs, workspace placement for forks created from subagents, and `origin: 'subagent'` sidebar filtering without hiding ordinary forks.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index f06e5f38ba..d373662987 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -47,7 +47,7 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
 
 one-shot 行始终会用文案替代输入框，说明执行记录为只读。可继续行仅在 `parentAvailable` 为 false 且 child 未在运行时如此；parent 离线但仍在运行的 child 保留普通输入框，并禁用其输入区和 Send 操作，让独立的 Stop 保持可达，停止后只读替代恢复。parent 在线时，即使 child 正在运行，Enter 和 Send 也会准入另一个 FIFO 轮次，而独立的 Stop 经由 `subagent.interrupt` 路由（[中断约定](2026-08-06-continuable-subagent-interrupt.md)）。提示词失败会通过普通错误行为保留草稿。
 
-已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行 seam 之外激活持久化 child 历史。
+已寻址 child 视图不提供绑定到 agent 的辅助控件。具体而言，模型选择器与 `/model` contribution 不会调用普通 `session.models` 或 `session.selectModel`；Host 也会拒绝任何意外调用，而不是在直接 parent 继续执行路径之外激活持久化 child 历史。
 
 ## 宿主适配器与协议约定
 
@@ -89,7 +89,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 
 **自动恢复缺失的 parent。** 不予采纳，因为继续执行要求确切的存活直接 parent。child 导航不得改变 parent 生命周期。
 
-**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行 seam 未公开具备安全授权的取消句柄。后来的[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
+**公开普通取消操作。** 不予采纳，因为已获 inbox 接受的轮次会比其准入请求存续更久，且在本决定当时，继续执行约定未公开具备安全授权的取消句柄。后来的[当前轮次中断约定](2026-08-06-continuable-subagent-interrupt.md)以专用 subagent 路由补上了这项显式授权；回退到 `session.cancel` 仍被拒绝。
 
 **只显示可继续 child。** 不予采纳，因为持久化目录有意描述由会话支撑的两种 mode。one-shot transcript 即使绝不接受后续消息，仍然有用。
 
@@ -105,7 +105,7 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。
 - 通用 Host 测试固定在不发布 Agent 的情况下读取已附加与冷态历史及执行 fork、冷态投影归并、按描述符／origin／运行时 owner 拒绝、拒绝显式 id 接纳，以及直接队列控制栅栏。
 - 客户端对象测试固定已保留与已恢复的地址、one-shot 只读与取消拒绝、历史路由、可继续提示词与中断路由、屏蔽绑定到 agent 的模型控件、实时活动状态翻转（包括在途响应回放与 detach 回退）、subagent parent 可展开性翻转与成员刷新。
 - jsdom 测试固定后代聚合计数与活动状态、侧边栏活动在嵌套谱系中的传播与普通 fork 边界、行状态优先级、token 用量总计、精确到秒的运行中耗时与冻结后 inactive 耗时、采用自适应单位的长耗时及其精确无障碍文本、目录缺失或为陈旧空目录时由摘要支撑的根操作、已知加载行的形态、混合 mode 行、点击前的叶子展开控件、diagnostic、后代懒加载展开、直接 parent 地址、键盘行为与两种只读原因。
-- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现及聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 model seam 处保持一个真实的 child Agent 轮次进行中，同时固定页头和可见空闲 owner 行中的聚合运行状态，随后在 teardown 期间取消该轮次。
+- 无密钥的组装 Web 快照包含一个具有持久化 token 用量的 inactive 可继续 child、一个具有确定性长耗时的 inactive one-shot sibling 和一个持久化 grandchild；它会固定触发器在一次陈旧的空目录响应后仍显示三个后代，并固定 token 用量与计时行、自适应长耗时呈现及聚合 `running` 状态转换，在不激活的情况下展开、打开持久化历史、准入一条用户 FIFO 后续消息、归并 child mux 事件，并证明 one-shot 历史仍然只读。另一个独立的组装场景会在 LLM seam 处保持一个真实的 child Agent 轮次进行中，同时固定页头和可见空闲 owner 行中的聚合运行状态，随后在 teardown 期间取消该轮次。
 - 导航测试固定仅含 subagent 的面包屑导航、从 subagent 创建 fork 时的 Workspace 归属，以及 `origin: 'subagent'` 侧边栏过滤，同时不隐藏普通 fork。
 
 ## 后果
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
index fa4523a51d..ca3cf443f9 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.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 .agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
-2026-07-27-workspace-registration-deletion.md: ef8a7fb9ae13c23e04a5760cd443c4a744ec4f19
-2026-07-27-workspace-registration-deletion.zh.md: 21c378b5c6d738bc6b9a00856691a56d65217586
+2026-07-27-workspace-registration-deletion.md: 08bce9fefa13f6e093aaf5ef6c8e8dfb9a409c1d
+2026-07-27-workspace-registration-deletion.zh.md: c75d29c102e3528dc755d21a2a9854a8c4a5a811
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
index ef8a7fb9ae..08bce9fefa 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md
@@ -14,7 +14,7 @@ The existing visual-only menu row also left deletion semantics undefined across
 
 `ctx.workspace.delete(id)` deletes only the Workspace registration: its id leaves durable `workspaceIds`, its `workspaces` table row and entity-cache entry disappear, and its ordered `sessionIds` account disappears with that row. It never calls filesystem removal or `SessionPersistence`; the directory, every user file, every live Session, and every persisted Session log remain. Because sidebar grouping is the complement of all surviving Workspace accounts, those Sessions immediately appear under Ungrouped, including the current Session.
 
-Unknown ids return `false` at the domain seam. `workspace.delete({ workspaceId })` maps that distinction to `workspace-not-found`; success returns `{ deleted: true }`. `workspace.list` remains the reconnect baseline.
+Unknown ids return `false` at the domain contract. `workspace.delete({ workspaceId })` maps that distinction to `workspace-not-found`; success returns `{ deleted: true }`. `workspace.list` remains the reconnect baseline.
 
 ## Durable commit and publication
 
diff --git a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
index 21c378b5c6..c75d29c102 100644
--- a/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md
@@ -14,7 +14,7 @@ Workspace 注册已有代码目录，使 GUI 能够为目录命名，并对其
 
 `ctx.workspace.delete(id)` 只删除 Workspace 注册记录：其 id 会从持久化的 `workspaceIds` 中移除，`workspaces` 表行与实体缓存条目会消失，有序 `sessionIds` 账本也随该行一并消失。它绝不调用文件系统移除操作或 `SessionPersistence`；目录、所有用户文件、所有实时会话和所有已持久化的会话日志都会保留。侧边栏分组是所有存续 Workspace 账本的补集，因此这些会话（包括当前会话）会立即出现在 Ungrouped 下。
 
-未知 id 在 domain seam 返回 `false`。`workspace.delete({ workspaceId })` 将该结果映射为 `workspace-not-found`；成功时返回 `{ deleted: true }`。`workspace.list` 仍是重连基线。
+未知 id 在领域约定处返回 `false`。`workspace.delete({ workspaceId })` 将该结果映射为 `workspace-not-found`；成功时返回 `{ deleted: true }`。`workspace.list` 仍是重连基线。
 
 ## 持久化提交与发布
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index c0e97060b2..2e5c66b55c 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
-2026-07-28-continuable-subagent-conversations.md: 632de8c9f7a6d2c71dcca6d817a827f788645b4e
-2026-07-28-continuable-subagent-conversations.zh.md: 9752dab97684d7249418c1a6d19905ab48ac82ca
+2026-07-28-continuable-subagent-conversations.md: 991b89599d7f300c79928e568833a2cd488f5a4e
+2026-07-28-continuable-subagent-conversations.zh.md: a7d282c4fadd943ad9250e01de5d379a776a32a0
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
index 632de8c9f7..991b89599d 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
@@ -117,7 +117,7 @@ The optional child-scoped `report(output)` tool was added later without changing
 
 ### Deferred steering
 
-This version exposes no subagent steering operation. Parent continuation messages always open later FIFO turns, so the continuation layer stores no current-turn controller and adds no controller-aware Agent admission seam.
+This version exposes no subagent steering operation. Parent continuation messages always open later FIFO turns, so the continuation layer stores no current-turn controller and adds no controller-aware Agent admission contract.
 
 A later host UI may expose separate **Steer** and **Follow up** actions. Host steering would be strict and live-only: it may call the existing Agent steering path only while the Activation accepts a next step, must reject otherwise, and must never fall back to queueing or cold resume. Exposing parent steering to a model-facing tool remains a separate design.
 
@@ -155,9 +155,9 @@ It adds no host-user continuation, subagent steering operation, durable mailbox,
 
 **Dispose the Agent while waiting.** Reconstructing a parent while its child still belongs to the previous process-local ownership graph would require a durable ownership and teardown protocol. Retaining the `AgentHandle` only for the unfinished graph preserves child-first teardown without keeping settled history resident.
 
-**Let the provider create, resume, or deliver through an Agent handle.** Initial providers own only `prepareContinuable()` and its detached creation-spec distinction: whether a child begins fresh or with a parent prefix. The manager must call `ctx.agents.create()` through its private activation-owner scope so that scope is a structural owner of every handle. A persisted in-process Session already contains the initial prefix and generic reconstruction descriptor, while delivery belongs to the Agent inbox. Giving providers any later handle, `SubagentRun`, or message ownership would preserve a seam with no shipped behavior to own.
+**Let the provider create, resume, or deliver through an Agent handle.** Initial providers own only `prepareContinuable()` and its detached creation-spec distinction: whether a child begins fresh or with a parent prefix. The manager must call `ctx.agents.create()` through its private activation-owner scope so that scope is a structural owner of every handle. A persisted in-process Session already contains the initial prefix and generic reconstruction descriptor, while delivery belongs to the Agent inbox. Giving providers any later handle, `SubagentRun`, or message ownership would retain provider ownership with no shipped behavior to justify it.
 
-**Make report delivery part of the base lifecycle.** Repeatable child-to-parent reporting is compatible with this lifecycle, but quiet versus waking delivery, acknowledgement, durability, and retry behavior are independent product choices. The later report package remains optional and consumes an explicit child-setup seam, so continuable residency does not silently grant a return channel.
+**Make report delivery part of the base lifecycle.** Repeatable child-to-parent reporting is compatible with this lifecycle, but quiet versus waking delivery, acknowledgement, durability, and retry behavior are independent product choices. The later report package remains optional and consumes an explicit child-setup hook, so continuable residency does not silently grant a return channel.
 
 **Treat `SessionHeader.parentSession` as live ownership.** Durable lineage does not prove that the recorded parent currently owns the child. Membership in the live parent's `ownedChildren` records the process-local relationship without changing the durable parent id.
 
@@ -167,7 +167,7 @@ It adds no host-user continuation, subagent steering operation, durable mailbox,
 
 **Expose subagent steering now.** Parent steering needs current-turn controller state and a separate admission policy from follow-up delivery. Queueing every first-version continuation avoids that state and its admission race.
 
-**Expose host-user follow-up without a host consumer.** A public authority-minting method and user branch would make cold resume possible without the historical parent, but no production host adapter calls that operation. The seam accepts only the exact live parent until a concrete authenticated host interaction can receive a private capability.
+**Expose host-user follow-up without a host consumer.** A public authority-minting method and user branch would make cold resume possible without the historical parent, but no production host adapter calls that operation. The continuation API accepts only the exact live parent until a concrete authenticated host interaction can receive a private capability.
 
 **Return a subagent-specific delivery route.** Labels such as `started`, `queued`, and `resumed` duplicate Activation and inbox state without giving the caller an independent result. Reusing `MessageId` and the existing inbox events keeps delivery correlation on the Agent contract that owns it.
 
@@ -193,7 +193,7 @@ The implementation pins these behaviors:
 - Every continuation-managed parent Activation disposes only after all directly owned child Activations complete `AgentHandle` disposal; top-level Agents do not join the waiting graph.
 - Final Activation settlement awaits `ctx.sessions.flush(child.session)` as a best-effort barrier, logs rejection without interpreting listener participation as durability proof, then disposes the child handle and releases parent ownership so a flush failure cannot leak a `waiting` Activation.
 - Manager teardown closes admission globally; a host owning selected top-level Agents instead closes admission only below their exact identities until those roots leave the registry. Both track admitted materializations by exact ancestry, install one memoized disposal cutoff per selected visible Activation, propagate cancellation top-down, release handles child-first, await every selected branch despite individual failures, and only then dispose the corresponding top-level Agents or manager scope.
-- The base lifecycle has no implicit report behavior; the optional report package contributes an explicit child-scoped tool through the setup seam.
+- The base lifecycle has no implicit report behavior; the optional report package contributes an explicit child-scoped tool through the setup hook.
 - Session logs reconstruct only messages that were actually written, with the source that supplied each message; inbox-accepted but unlogged messages have no restart guarantee.
 - No continuable-subagent path creates or depends on a Task, `TaskId`, Task completion notice, Task cancellation, or intermediate result-bearing execution wrapper.
 - Unit coverage pins the `startContinuable()` inbox-acceptance return boundary, complete rollback for each pre-acceptance and lifecycle-publication failure, global and parent-scoped drain quiescence for materialization caught between Agent publication and Activation registration, sibling-forest isolation, exact ancestry after an intermediate Agent leaves the registry, provider-independent cold resume, final exact-parent reauthorization after cold-resume materialization, caller-signal and teardown ownership on both sides of acceptance, and the absence of automatic replay for accepted-but-unlogged messages.
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index 9752dab976..a7d282c4fa 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -117,7 +117,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ### 延后的 steering（中途引导）
 
-本版本不暴露 subagent steering 操作。parent 的继续执行消息始终开启后续 FIFO 轮次，因此继续执行层不存储当前轮次控制方，也不新增能够感知控制方的 Agent 准入 seam。
+本版本不暴露 subagent steering 操作。parent 的继续执行消息始终开启后续 FIFO 轮次，因此继续执行层不存储当前轮次控制方，也不新增能够感知控制方的 Agent 准入约定。
 
 后续宿主 UI 可以分别暴露 **Steer** 和 **Follow up** 操作。宿主 steering 必须严格且仅限在线使用：只有当激活接受下一步骤时，它才能调用现有的 Agent steering 路径；其他情况必须拒绝，而且绝不能转为排队或冷恢复。是否通过面向模型的工具暴露 parent steering 仍需单独设计。
 
@@ -155,9 +155,9 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 **等待期间 dispose Agent。** child 仍属于上一个进程内所有权图时重建 parent，需要持久化所有权与拆卸协议。只为尚未完成的所有权图保留 `AgentHandle`，可以在不让已结算历史驻留的前提下，保留 child-first 拆卸。
 
-**让提供方通过 Agent handle 创建、恢复 child 或投递消息。** 初始提供方只持有 `prepareContinuable()` 及其分离式创建规格这一项差异：child 是全新启动，还是带有 parent 前缀。管理器必须通过私有 activation-owner 作用域自行调用 `ctx.agents.create()`，使该作用域成为每个 handle 的结构化所有者。持久化的进程内会话已经包含初始前缀及通用重建描述符，消息投递则属于 Agent inbox。让提供方持有任何后续 handle、`SubagentRun` 或消息所有权，会保留一条没有已发布行为可承载的 seam。
+**让提供方通过 Agent handle 创建、恢复 child 或投递消息。** 初始提供方只持有 `prepareContinuable()` 及其分离式创建规格这一项差异：child 是全新启动，还是带有 parent 前缀。管理器必须通过私有 activation-owner 作用域自行调用 `ctx.agents.create()`，使该作用域成为每个 handle 的结构化所有者。持久化的进程内会话已经包含初始前缀及通用重建描述符，消息投递则属于 Agent inbox。让提供方持有任何后续 handle、`SubagentRun` 或消息所有权，会让提供方保留所有权，却没有已发布行为需要它。
 
-**将报告投递纳入基础生命周期。** 可重复的 child 到 parent 报告与该生命周期兼容，但静默投递还是唤醒投递、确认、持久性和重试行为都是独立的产品决策。后续的 report 包保持可选，并消费一条显式 child 设置 seam，因此可继续驻留不会默认授予返回通道。
+**将报告投递纳入基础生命周期。** 可重复的 child 到 parent 报告与该生命周期兼容，但静默投递还是唤醒投递、确认、持久性和重试行为都是独立的产品决策。后续的 report 包保持可选，并消费一个显式的 child 设置钩子，因此可继续驻留不会默认授予返回通道。
 
 **将 `SessionHeader.parentSession` 视为在线所有权。** 持久化谱系不能证明已记录的 parent 当前持有 child。在线 parent 的 `ownedChildren` 成员关系会记录进程内关系，而不改变持久化 parent id。
 
@@ -167,7 +167,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 **现在就暴露 subagent steering。** parent steering 需要当前轮次控制方状态，以及不同于 follow-up 投递的单独准入策略。首个版本将每条继续执行消息都排队，可以避免引入该状态及其准入竞争。
 
-**在没有 host 消费方的情况下暴露 host-user follow-up。** 公开的权限铸造方法和用户分支可以在没有历史 parent 的情况下实现冷恢复，但没有生产 host 适配器调用该操作。在具体的经认证宿主交互能够收到私有能力之前，该 seam 只接受确切的在线 parent。
+**在没有 host 消费方的情况下暴露 host-user follow-up。** 公开的权限铸造方法和用户分支可以在没有历史 parent 的情况下实现冷恢复，但没有生产 host 适配器调用该操作。在具体的经认证宿主交互能够收到私有能力之前，继续执行 API 只接受确切的在线 parent。
 
 **返回 subagent 专属的投递路由。** `started`、`queued` 和 `resumed` 等标签重复了激活与 inbox 状态，却没有给调用方提供独立结果。复用 `MessageId` 和现有 inbox 事件，可以让投递关联继续由其所属的 Agent 约定承载。
 
@@ -193,7 +193,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 - 每个由继续执行管理器管理的 parent 激活只会在直接持有的所有 child 激活完成 `AgentHandle` dispose 后进行 dispose；顶层 Agent 不加入等待图。
 - Activation 最终结算会等待 `ctx.sessions.flush(child.session)`，将其作为 best-effort 屏障；它会记录 rejection，但不会把 listener 参与解释为持久性证明，然后 dispose child handle 并释放 parent 所有权，使 flush 失败不会泄漏 `waiting` Activation。
 - 管理器拆卸会全局关闭准入；拥有选定顶层 Agent 的宿主则只关闭这些确切身份之下的准入，直到这些根离开注册表。两者都会按确切祖先关系跟踪已获准的物化过程，为每个选中的可见 Activation 安装一个记忆化 dispose 截止点，自顶向下传播取消，按 child-first 顺序释放 handle，即使个别分支失败也会等待所有选中分支，之后才 dispose 对应的顶层 Agent 或管理器作用域。
-- 基础生命周期不暴露隐式报告行为；可选的 report 包通过 setup seam 贡献一个显式的 child 作用域工具。
+- 基础生命周期不暴露隐式报告行为；可选的 report 包通过 setup 钩子贡献一个显式的 child 作用域工具。
 - 会话日志只会重建实际写入的消息，并保留每条消息的提供来源；已被 inbox 接受但未写入日志的消息没有重启保证。
 - 可继续 subagent 路径不创建或依赖 Task、`TaskId`、Task 完成通知、Task 取消或中间的带结果执行包装层。
 - 单元覆盖固定 `startContinuable()` 在 inbox 接受消息时的返回边界、每条接受前和生命周期发布失败路径的完整回滚、全局和限定到 parent 作用域的 drain 都会等待夹在 Agent 发布与 Activation 注册之间的物化过程完全停稳、同级森林隔离、中间 Agent 离开注册表后的确切祖先关系、不依赖提供方的冷恢复、冷恢复物化后的最终确切 parent 再授权、接受前后两个阶段的调用方 signal 与拆卸所有权，以及已接受但未写入日志的消息不会自动回放。
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
index 1d67db187c..9ecdf26043 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.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 .agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
-2026-07-28-skill-invocation-policy.md: 9d34bcb77ab7933ef9bf4e9b5227dade39903667
-2026-07-28-skill-invocation-policy.zh.md: 687bd582ce3f4c74e50d36640afc6b683e289c90
+2026-07-28-skill-invocation-policy.md: 67b50c7f92f7c93a13b495877bb8f87cfac44552
+2026-07-28-skill-invocation-policy.zh.md: 20d41ec1b2fdbfe5bbbe3c54a681dd4f807c703e
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
index 9d34bcb77a..67b50c7f92 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.md
@@ -12,7 +12,7 @@ The local parser also exposed an internal camel-case spelling as frontmatter. Su
 
 ## Decision
 
-`SkillSummary` carries a required typed `invocation: SkillInvocationPolicy` object whose `modelInvocable: boolean` and `userInvocable: boolean` fields are positive and symmetric. Omission exists only at explicit input seams: a runtime `SkillRegistration` without a policy and local frontmatter without either invocation key resolve to `{ modelInvocable: true, userInvocable: true }` before producing candidates or definitions. Future frontmatter keys remain outside the domain model until a consumer and enforcement contract exist; the local provider still parses frontmatter as an open `Record<string, unknown>`, then projects only recognized fields and their defaults into the normalized typed policy.
+`SkillSummary` carries a required typed `invocation: SkillInvocationPolicy` object whose `modelInvocable: boolean` and `userInvocable: boolean` fields are positive and symmetric. Omission exists only at explicit input boundaries: a runtime `SkillRegistration` without a policy and local frontmatter without either invocation key resolve to `{ modelInvocable: true, userInvocable: true }` before producing candidates or definitions. Future frontmatter keys remain outside the domain model until a consumer and enforcement contract exist; the local provider still parses frontmatter as an open `Record<string, unknown>`, then projects only recognized fields and their defaults into the normalized typed policy.
 
 `ctx.skills.list()` returns every winning summary and no longer chooses an invocation surface. `isModelInvocable(skill)` and `isUserInvocable(skill)` read the matching positive field directly. `ctx.skills.get()` remains policy-neutral because trusted internal callers may need any definition, while a public consumer must enforce its own predicate before advertising or loading a skill. The model tool and TUI check the invocation-neutral summary before calling `get()`, then recheck the loaded definition so a denied name never reaches definition loading and a policy change between discovery and load cannot expose its body.
 
@@ -33,7 +33,7 @@ This decision extends the [skill system](2026-07-05-skill-system.md) and superse
 
 ## Alternatives considered
 
-**Store all frontmatter in a generic `Map` and read string keys in `isModelInvocable` / `isUserInvocable`.** Rejected because misspelled keys, non-boolean values, and consumer-specific coercion would cross package seams without type checking. The parser boundary remains open; the domain model is deliberately typed and narrow.
+**Store all frontmatter in a generic `Map` and read string keys in `isModelInvocable` / `isUserInvocable`.** Rejected because misspelled keys, non-boolean values, and consumer-specific coercion would cross package boundaries without type checking. The parser boundary remains open; the domain model is deliberately typed and narrow.
 
 **Keep `ctx.skills.list()` model-filtered and add a second user list.** Rejected because discovery, duplicate resolution, caching, and ordering are surface-neutral work. One complete catalog plus explicit predicates prevents those mechanisms from drifting while making each consumer's policy visible at its boundary.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
index 687bd582ce..20d41ec1b2 100644
--- a/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md
@@ -12,7 +12,7 @@ skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会
 
 ## 决策
 
-`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入 seam 可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行约定后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
+`SkillSummary` 包含一个必填且类型明确的 `invocation: SkillInvocationPolicy` 对象，其 `modelInvocable: boolean` 和 `userInvocable: boolean` 字段为正向且对称。只有显式输入边界可以省略它：未提供策略的运行时 `SkillRegistration`，以及两个调用键均未提供的本地 frontmatter，都会在生成候选项或定义前解析为 `{ modelInvocable: true, userInvocable: true }`。未来的 frontmatter 键只有在具备消费方和执行约定后，才会进入领域模型；本地提供方仍将 frontmatter 解析为开放的 `Record<string, unknown>`，然后只把已识别字段及其默认值投影到规范化的类型化策略中。
 
 `ctx.skills.list()` 返回所有胜出的摘要，不再替任何调用接口选择策略。`isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 保持策略无关，因为可信内部调用方可能需要任意定义；对外消费方则必须在展示或加载 skill 之前执行自身对应的判定函数。模型工具和 TUI 会在调用 `get()` 前检查与调用策略无关的摘要，随后再次检查已加载的定义：被拒绝的名称绝不会进入定义加载流程，发现与加载之间发生策略变更也无法暴露该 skill 的正文。
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
index 77df231e1c..65af28ee2e 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.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 .agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
-2026-07-28-web-terminal-card.md: 026b32fed2c79533abfadc58314e2844ff556414
-2026-07-28-web-terminal-card.zh.md: 3a9025b3f2dee546253d923c121df0e04da73414
+2026-07-28-web-terminal-card.md: 0338fa1cdb4a19177bddd4181661173bf75492b0
+2026-07-28-web-terminal-card.zh.md: f9dc686cfbf817fe5a1c15b8d5a94e3f8ab2adee
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
index 026b32fed2..0338fa1cdb 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
@@ -12,7 +12,7 @@ The Web client ignored it. `packages/client/ui-tool/src/client/tool/models/tool-
 
 ## Decision
 
-`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs at this seam; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means.
+`TerminalBlock` is a `ui-primitives` component that renders a shell command as a terminal surface, and both Web render sites for a bash call consume the terminal render intent through it: the chat tool row's expanded body and the details panel's Output section. `packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a command, its cwd, or its exit status. It returns null — the generic path — whenever neither side declares `card: 'terminal'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how the bash tool's execution errors and background starts keep their existing rendering. Two duties the render-intent contract assigns to the UI bridge land here rather than in the tool: a settled result's `title` REPLACES the pending one, and the working directory resolves against the session workspace — an absolute view cwd is used as-is, a relative one joins under the workspace, and an omitted one IS the workspace, which is the common case for a bash call with no `workdir`. A pure presenter cannot see the session cwd, which is why the resolution belongs in this UI bridge; each render site supplies the cwd off the session list row. Only a PRESENT call view can mean "omitted, so use the workspace": when the paging window drops the call head there is no cwd anywhere — the result view carries none — and the original call may have used an explicit workdir, so the prompt draws a bare `$` rather than naming a directory it cannot know. The resolved path also normalizes its `.`/`..` segments, because the bash executor resolves the workdir before running: a `..` against `/w/app` runs in `/w`, so the prompt label has to read `w` rather than `..`. A UNC path's `server` and `share` are part of its root rather than poppable segments, since Windows cannot climb above a share. The call view's `description` rides the same derivation, since the contract renders it above the card and it must outrank the row's args-derived summary. All three render sites draw it: both chat-row shapes and the details panel. An expanded row draws it itself, because the collapsed summary is hidden while a row is open — without that the description would only ever be visible collapsed, which is the opposite of what "above the card" means.
 
 The component's contract:
 
@@ -49,7 +49,7 @@ One premise of that split has since weakened: [tool rows stopped being details-p
 
 `TerminalBlock` reads only the terminal view's fields, so it stays a pure function of what the render intent carries — no session lookups, replay-safe like the presenters that produce the view. A UI without the terminal capability still gets the bridge's fenced fallback; nothing about the tool's result shape changed.
 
-A `run_code` sub-dispatch does not reach a terminal card on the shipped wire: `session.ts` folds `tool/code-dispatch(-start)` with `callView: null`/`resultView: null`, and the host's `viewFor` presents only top-level `tool/call`/`tool/result`, so a nested bash call keeps the generic flattened form. Both arms are pinned — the resolution path with views injected, and the no-view shape the wire actually delivers — so the gap is recorded rather than implied. Carrying presenter views through the code-dispatch wire is that seam's own change.
+A `run_code` sub-dispatch does not reach a terminal card on the shipped wire: `session.ts` folds `tool/code-dispatch(-start)` with `callView: null`/`resultView: null`, and the host's `viewFor` presents only top-level `tool/call`/`tool/result`, so a nested bash call keeps the generic flattened form. Both arms are pinned — the resolution path with views injected, and the no-view shape the wire actually delivers — so the gap is recorded rather than implied. Carrying presenter views through the code-dispatch wire is that boundary's own change.
 
 Inline rendering is licensed for the terminal intent alone. A future intent that wants it needs its own bound and its own decision, argued against the reason recorded here rather than against the panel-only convention on its own.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index 3a9025b3f2..f9dc686cfb 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -12,7 +12,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 ## Decision
 
-`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图约定交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这道接缝；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为约定把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
+`TerminalBlock` 是 `ui-primitives` 中把 shell 命令渲染为终端表面的组件，bash 调用在 Web 侧的两个渲染点都经由它消费 terminal 渲染意图：聊天工具行展开后的正文，以及详情面板的 Output 区。`packages/client/ui-tool/src/client/tool/models/terminal-card-model.ts` 是把快照上的 `callView`/`resultView` 这一对转换为该组件 props 的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧。当两侧都不声明 `card: 'terminal'` 时它返回 null，即走 generic 路径——包括本 client 版本不认识的 `card` 取值；当一个已落定调用的结果视图是 generic 时同样返回 null，这正是 bash 工具的执行错误与后台启动得以保持既有渲染的方式。渲染意图约定交给 UI 桥接层的两项职责也落在这里，而不在工具侧：已落定结果的 `title` **替换**待定标题；工作目录针对会话 workspace 解析——视图给出的绝对路径原样使用，相对路径在 workspace 之下拼接，省略则**就是** workspace，而这正是不带 `workdir` 的 bash 调用的常见情形。纯 presenter 看不到会话 cwd，因此该解析属于这个 UI 桥接层；两个渲染点各自从会话列表行取出 cwd 传入。只有**存在**的调用视图才能表示「省略了 cwd，因此取 workspace」：当分页窗口丢掉调用头时，任何地方都不再有 cwd——结果视图并不携带它——而原调用完全可能使用过一个显式 workdir，因此提示行绘制一个裸 `$`，而不是命名一个它无法知晓的目录。解析后的路径还会归一化其 `.`／`..` 段，因为 bash 执行器在运行前就已解析 workdir：相对 `/w/app` 的 `..` 实际运行在 `/w`，因此提示标签必须读作 `w` 而不是 `..`。UNC 路径的 `server` 与 `share` 属于其根，而非可弹出的路径段，因为 Windows 无法越过一个共享向上。调用视图的 `description` 走同一处推导，因为约定把它渲染在卡片上方，且它必须优先于该行由参数推导出的摘要。三个渲染点都会绘制它：两种聊天行形态与详情面板。展开后的行自行绘制它，因为一行处于展开态时其折叠摘要是隐藏的——否则该描述将只在折叠时可见，这与「位于卡片上方」的含义正好相反。
 
 该组件的约定：
 
@@ -49,7 +49,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 `TerminalBlock` 只读取 terminal 视图携带的字段，因此它始终是渲染意图内容的纯函数——不查会话状态，与产出该视图的 presenter 一样可安全回放。不具备终端能力的 UI 仍从桥接层拿到围栏式回退；工具的结果形态未作任何改动。
 
-在当前已交付的 wire 上，`run_code` 子派发不会得到终端卡片：`session.ts` 把 `tool/code-dispatch(-start)` 折叠为 `callView: null`／`resultView: null`，而 host 的 `viewFor` 只呈现顶层的 `tool/call`／`tool/result`，因此嵌套的 bash 调用保持通用的压平形式。两条分支都已钉住——注入视图后的解析路径，以及 wire 实际投递的无视图形态——因此这个缺口是被记录下来的，而非暗含的。把 presenter 视图贯穿 code-dispatch wire 属于那道接缝自身的改动。
+在当前已交付的 wire 上，`run_code` 子派发不会得到终端卡片：`session.ts` 把 `tool/code-dispatch(-start)` 折叠为 `callView: null`／`resultView: null`，而 host 的 `viewFor` 只呈现顶层的 `tool/call`／`tool/result`，因此嵌套的 bash 调用保持通用的压平形式。两条分支都已钉住——注入视图后的解析路径，以及 wire 实际投递的无视图形态——因此这个缺口是被记录下来的，而非暗含的。把 presenter 视图贯穿 code-dispatch wire 属于该边界自身的改动。
 
 内嵌渲染的许可仅授予 terminal 意图。将来想要内嵌的意图需要有自己的边界与自己的决定，且需针对此处记录的理由来论证，而不是仅针对「只在面板」这条约定本身。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
index 9ae0827be2..e16de3af0f 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.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 .agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
-2026-07-30-current-sandbox-policy-context.md: 093f9a8a0b58256bb4f2301cc62fa83629de4fbd
-2026-07-30-current-sandbox-policy-context.zh.md: ce7ff2d0cff0fc1068995fde174a4eb1df5343b7
+2026-07-30-current-sandbox-policy-context.md: ab231d19aec4852369c0f1a13fc50c69ab8128f1
+2026-07-30-current-sandbox-policy-context.zh.md: f269f70702373c4bd3d8172ccfaae921868146ca
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
index 093f9a8a0b..ab231d19ae 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.md
@@ -52,7 +52,7 @@ The cache-safe delivery rework then supplied a separate, non-statistical accepta
 
 **Keep sandbox mode absent because a standing mode label once caused preemptive refusal.** Rejected because a fresh Web request otherwise exposes mutation tools while withholding their standing policy, producing false capability claims before the first operation. The earlier live measurement remains a required counter-test: five of twelve turns ended without a tool call under `Bash commands run under the "read-only" file sandbox.` The committed tool-owned attempt guidance postdates that measurement, so the replacement is selected through a new positive-control experiment under the current tool contract rather than assuming the old and current conditions match.
 
-**A separate model-context package.** Rejected because the policy owner can resolve current session state directly and the existing assembly service can order it. A new package would add a shallow composition seam and documentation/gate surface around the same request boundary.
+**A separate model-context package.** Rejected because the policy owner can resolve current session state directly and the existing assembly service can order it. A new package would add a shallow composition layer and documentation/gate surface around the same request boundary.
 
 **Enumerate writable temporary roots.** Rejected because the backend is selected later at `confine()`: bwrap, Landlock, Seatbelt, and the in-process filesystem fence do not grant one common temporary-path set. Host-specific paths in a standing request would be both unstable and overclaimed.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
index ce7ff2d0cf..f269f70702 100644
--- a/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-current-sandbox-policy-context.zh.md
@@ -52,7 +52,7 @@ Status: implemented
 
 **继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具约定下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
 
-**独立的模型上下文包。** 不予采用，因为策略归属方可以直接解析当前会话状态，现有组装服务也可以对其排序。新包只会围绕同一个请求边界引入浅层组合 seam 和额外的文档／门禁表面。
+**独立的模型上下文包。** 不予采用，因为策略归属方可以直接解析当前会话状态，现有组装服务也可以对其排序。新包只会围绕同一个请求边界引入浅层组合层和额外的文档／门禁表面。
 
 **枚举可写临时根目录。** 不予采用，因为后端要到稍后的 `confine()` 才会选定：bwrap、Landlock、Seatbelt 和进程内文件系统围栏并不授予一套共同的临时路径。常驻请求中的主机特定路径既不稳定，也会作出过度承诺。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml
index 4571273d21..0e4f334485 100644
--- a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.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 .agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md
-2026-07-30-plan-review-presentation-intent.md: aeab12aac308c24aa5c4b5953a60ae0f2cf6c5b5
-2026-07-30-plan-review-presentation-intent.zh.md: 1e52d7363ccc2fe5390a4f91aa7fe058229fe34a
+2026-07-30-plan-review-presentation-intent.md: f524f7ec67dff3e6d7a6bf59ac204f5c8aae13c6
+2026-07-30-plan-review-presentation-intent.zh.md: 69e0ae00fbc2a98ed45a6d2b711a17f7c947c7e6
diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md
index aeab12aac3..f524f7ec67 100644
--- a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md
+++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.md
@@ -30,7 +30,7 @@ Dismissal became its own model-facing outcome. `ASK_CANCELLED` previously reache
 
 **Route the card on the question's `id` or `header` (`plan-review` / `Plan review`).** Rejected: string-sniffing a foreign package's copy across a wire boundary, which any wording change silently breaks. The intent is the declaration that makes the routing legible.
 
-**Order the options and let the card read position 0 as approve.** Rejected: a positional contract at a package seam, invisible in both the type and the wire frame, and unenforceable — a producer that reorders its options would invert a user's verdict. Naming the label costs one string.
+**Order the options and let the card read position 0 as approve.** Rejected: a positional contract at a package boundary, invisible in both the type and the wire frame, and unenforceable — a producer that reorders its options would invert a user's verdict. Naming the label costs one string.
 
 **Register a second composer-chain entry for the plan card.** Rejected: two entries would select over the same pending question carrier, making the surface depend on chain priority and on whether the plan package's client half is composed at all. One entry that picks its own shape cannot race itself, and the generic flow is the built-in fallback.
 
@@ -42,7 +42,7 @@ Dismissal became its own model-facing outcome. `ASK_CANCELLED` previously reache
 
 ## Consequences
 
-The question protocol now carries a presentation axis. Adding a second intent is a tag on the union, a producer that sets it, a schema member, and a panel — no new frame, service, or answer shape. The cost is that the question seam knows presentation exists at all, and that `ui-question` knows the word "plan"; both are the price of one entry owning every question surface.
+The question protocol now carries a presentation axis. Adding a second intent is a tag on the union, a producer that sets it, a schema member, and a panel — no new frame, service, or answer shape. The cost is that the question contract knows presentation exists at all, and that `ui-question` knows the word "plan"; both are the price of one entry owning every question surface.
 
 The plan gate reads as a plan gate: the plan is the card's content, the verdict is two labelled buttons, and taking the turn back is a third. The generic flow is untouched for every other question, and its committed goldens did not move.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md
index 1e52d7363c..69e0ae00fb 100644
--- a/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-plan-review-presentation-intent.zh.md
@@ -42,7 +42,7 @@ Status: implemented
 
 ## 结果
 
-问题协议从此带有一个呈现轴。新增第二个意图 = 联合上的一个标签、一个设置它的生产方、一个 schema 成员、一个面板 —— 不需要新的帧、服务或回答形状。代价是问题 seam 从此知道"呈现"这件事存在，且 `ui-question` 知道"plan"这个词；两者都是由单一条目拥有全部问题界面所要付的价钱。
+问题协议从此带有一个呈现轴。新增第二个意图 = 联合上的一个标签、一个设置它的生产方、一个 schema 成员、一个面板 —— 不需要新的帧、服务或回答形状。代价是问题约定从此知道"呈现"这件事存在，且 `ui-question` 知道"plan"这个词；两者都是由单一条目拥有全部问题界面所要付的价钱。
 
 计划关口读起来就像计划关口：计划是卡片的内容，裁决是两个带标签的按钮，把轮次拿回来是第三个。通用流程对其他每个问题都未受影响，其已提交的 golden 也没有变动。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index b844594397..9233d3f0c6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.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 .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
-2026-07-30-web-result-card-frontend.md: c7e63220d824cf0bd3ac3536c528707d0db379bc
-2026-07-30-web-result-card-frontend.zh.md: e40d103c295b4699cde3327252c8bca3719e7962
+2026-07-30-web-result-card-frontend.md: 0f3e46cda1aeeb0f526f839a9071f09058810b86
+2026-07-30-web-result-card-frontend.zh.md: d9802099f7d2300b4a4c88556103d0c014aaebee
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
index c7e63220d8..0f3e46cda1 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
@@ -32,13 +32,13 @@ A separate later PR unifies the whole-row collapse/expand interaction and will f
 
 **Reparse the model-facing render text instead of consuming the structured view.** Rejected for the same reason the contract note gives: `web_search`'s render collapses each source's fields into one free-text line labelled by title OR hostname, so reparsing cannot recover `{url, title?, snippet?, publishedAt?}`. The structured `resultView` is the only faithful source, which is why the backend PR added it.
 
-**Render plain anchors without the protocol allowlist.** Rejected: the URL is model-authored and unverified at this seam, so an unfiltered href would let a `javascript:` URL execute on click. The allowlist is the http(s) subset of MarkdownText's (which also permits `mailto:`), so untrusted retrieval links behave identically wherever they render.
+**Render plain anchors without the protocol allowlist.** Rejected: the URL is model-authored and unverified at this presentation boundary, so an unfiltered href would let a `javascript:` URL execute on click. The allowlist is the http(s) subset of MarkdownText's (which also permits `mailto:`), so untrusted retrieval links behave identically wherever they render.
 
 ## Testing
 
 `packages/client/ui-primitives/tests/web-block.spec.tsx` pins the component per-file to the 100% gate: both kinds; the title-or-hostname-or-raw-URL label fallback; the safe-link attributes on both kinds (an http(s) URL becoming an external anchor with `target`/`rel`, a `javascript:`/`file:`/unparseable URL rendering as a plain span with no href); the snippet and date shown or omitted on present/empty/absent; the truncation indicator gated on the flag; and the full source list rendering inside one scroll container with no expand control and `<li value>` numbering every source contiguously from 1.
 
-`packages/client/ui-tool/tests/web-card.spec.tsx` mirrors `terminal-card.spec.tsx` at every wiring seam: `webCardModel`'s derivation projecting every source field, its truncation and absent-answer arms, the fetch derivation, and each null arm (running, null result view, generic result view, unknown card tag, unknown web `kind`); the keyed `WebRow`'s resident card for both kinds, its summary-row-alone running and failed arms; the `GenericToolCard` fallback growing the resident card for a web-declaring tool and keeping the plain row for a non-web call; the details panel's Output section for both kinds — including a `web_fetch`'s body flattened below its URL/status card — and its flattened fallback for a non-web result; and the keyed registration under both `web_search` and `web_fetch` with one component. That file sits on the coverage `exclude` list (`ui-tool/src/*`), so a coverage run measures none of it.
+`packages/client/ui-tool/tests/web-card.spec.tsx` mirrors `terminal-card.spec.tsx` at every wiring boundary: `webCardModel`'s derivation projecting every source field, its truncation and absent-answer arms, the fetch derivation, and each null arm (running, null result view, generic result view, unknown card tag, unknown web `kind`); the keyed `WebRow`'s resident card for both kinds, its summary-row-alone running and failed arms; the `GenericToolCard` fallback growing the resident card for a web-declaring tool and keeping the plain row for a non-web call; the details panel's Output section for both kinds — including a `web_fetch`'s body flattened below its URL/status card — and its flattened fallback for a non-web result; and the keyed registration under both `web_search` and `web_fetch` with one component. That file sits on the coverage `exclude` list (`ui-tool/src/*`), so a coverage run measures none of it.
 
 The fixture (`packages/client/connection/src/client/fixture.ts`) adds turns 66 (`web_search`) and 67 (`web_fetch`), authored inline because the client-side fixture cannot import the web tool: turn 66's result view carries an answer and three sources exercising the citation list (a titled source with a snippet and date, a source with no title so its hostname labels the link, and a source with a date but no snippet) with the capped indicator on; turn 67's carries the fetched URL and a 200 status. Both keep a generic pending call view and add the `web` card only at result time, matching the contract's result-only web shape, and are named after the real tools so they hit the keyed `WebRow`. They are ordered before the todo turn (renumbered to 68) for the same reason the terminal turn is: the standing plan retires at the next `turn/start`, so a turn appended after it would empty the dock's plan strip. This drives the built-boot snapshot and a live `?fixture` server.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index e40d103c29..d9802099f7 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -32,13 +32,13 @@ Status: implemented
 
 **重解析模型可见的渲染文本,而非消费结构化视图。** 因约定笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
 
-**不加协议 allowlist 直接渲染裸锚点。** 拒绝:URL 在此接缝处是模型创作、未经验证的,所以未过滤的 href 会让 `javascript:` URL 在点击时执行。该 allowlist 是 MarkdownText allowlist（它还允许 `mailto:`）的 http(s) 子集,因此不受信任的检索链接无论在何处渲染都行为相同。
+**不加协议 allowlist 直接渲染裸锚点。** 拒绝:URL 在此展示边界处是模型创作、未经验证的,所以未过滤的 href 会让 `javascript:` URL 在点击时执行。该 allowlist 是 MarkdownText allowlist（它还允许 `mailto:`）的 http(s) 子集,因此不受信任的检索链接无论在何处渲染都行为相同。
 
 ## Testing
 
 `packages/client/ui-primitives/tests/web-block.spec.tsx` 把组件钉到 per-file 100% 门槛:两种 kind;标题-或-主机名-或-原始 URL 的标签回退;两种 kind 上的安全链接属性（http(s) URL 成为带 `target`/`rel` 的外链,`javascript:`/`file:`/无法解析的 URL 渲染为无 href 的纯 span）;snippet 与日期在存在/为空/缺失时的显示或省略;由标志位控制的截断提示;以及完整 source 列表渲染在单个滚动容器内、无展开控件、`<li value>` 从 1 起为每条 source 连续编号。
 
-`packages/client/ui-tool/tests/web-card.spec.tsx` 在每个接线接缝镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-tool/src/*`）,因此覆盖率运行不度量它。
+`packages/client/ui-tool/tests/web-card.spec.tsx` 在每个接线边界镜像 `terminal-card.spec.tsx`:`webCardModel` 的派生投影每个 source 字段、其截断与缺失 answer 的支路、fetch 派生、以及每个 null 支路（运行中、null result view、generic result view、未知 card 标签、未知 web `kind`）;键控 `WebRow` 对两种 kind 的常驻卡片、其仅摘要行的运行中与失败支路;`GenericToolCard` 兜底为 web 声明工具长出常驻卡片、并为非 web 调用保持纯行;详情面板 Output 区对两种 kind —— 含 `web_fetch` 正文摊平在其 URL/状态卡片下方 —— 及其对非 web 结果的摊平回退;以及在 `web_search` 与 `web_fetch` 两键下用一个组件的键控注册。该文件位于覆盖率 `exclude` 列表（`ui-tool/src/*`）,因此覆盖率运行不度量它。
 
 fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（`web_search`）与 67（`web_fetch`）,内联撰写,因为客户端 fixture 无法 import web 工具:turn 66 的 result view 携带一个 answer 与三个 source,演练引用列表（一个带 snippet 与日期的有标题 source、一个无标题因而以主机名标注链接的 source、一个有日期无 snippet 的 source）并开启截断提示;turn 67 携带抓取的 URL 与一个 200 状态。两者都保留 generic pending call view,仅在 result 时添加 `web` 卡片,匹配约定的 result-only web 形状,且以真实工具命名,使其命中键控 `WebRow`。它们被排在 todo turn（重编号为 68）之前,理由与终端 turn 相同:待定计划在下一个 `turn/start` 退休,所以排在其后的 turn 会清空 dock 的 plan strip。这驱动 built-boot snapshot 与一个实时 `?fixture` 服务。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
index ee89a37a8b..2c8ee18abb 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.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 .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
-2026-07-31-code-mode-language-dispatch.md: 71e4fd5a30e90ac66132dbdcea16917bacc80b68
-2026-07-31-code-mode-language-dispatch.zh.md: c8ab776dfb01265fa79b5f2b1001ca8109a96d7f
+2026-07-31-code-mode-language-dispatch.md: 3a6e248160f165d6b341a5c8719abffd69a43820
+2026-07-31-code-mode-language-dispatch.zh.md: 46ef842f4b4209787c831b657159a97604324a66
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
index 71e4fd5a30..3a6e248160 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
@@ -19,7 +19,7 @@ Language selection is a lookup on `ctx.codeRuntime.language`, resolved lazily at
 
 Both tables are read with `Object.hasOwn` before use so a language named `toString`/`constructor` cannot resolve an inherited `Object.prototype` member as a renderer. The two guards differ in reachability: `SDK_RENDERERS`' in-callback guard is unreachable because `requireCodeRuntime` validated the same `const` table earlier in the same callback (it carries a `/* v8 ignore */`), while `RUN_CODE_FLAVORS`' guard is the primary, publicly reachable rejection — any language absent from the flavor table hits it through `run_code`'s language-aware getters, which the public `schemas()` reaches without passing `requireCodeRuntime` first; the test reads one of those getters off the definition directly, under a language absent from both tables. A language present in `SDK_RENDERERS` but not `RUN_CODE_FLAVORS` is drift the shared `CodeSdkLanguage` `satisfies` pins reject at `typecheck`, so it is not an input either guard can see; what the guards still own is a mounted runtime reporting a language absent from both tables. Schema emission reads the runtime through `peekRuntime()` rather than `requireRuntime()`: `undefined` (no runtime mounted, reached by definition readers and `schemas()`, of which the doc-catalog harvest is the only shipped one and none of which feeds a model because assembly passes `requireCodeRuntime` first) degrades to the TypeScript flavor, whereas a mounted unknown language fails loud — this is NOT the silent fallback rejected below, which concerns emitting a wrong-language SDK for a real runtime. Adding a backend language is three parallel edits — a `CodeSdkLanguage` member and the two table entries — plus its renderer and the prose that names the well-known values instead of deriving them (the seam's `dsh-code-runtime` README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair; this package's own README pair and its `Config.mode` JSDoc — no gate checks any of it), with no `agent-loop` or registry-structure change.
 
-`code-mode.ts` depends only on the runtime seam (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer therefore lands independently of the protocol and backend PRs — it needs only the seam's `language` field, which is already on master.
+`code-mode.ts` depends only on the runtime Service Definition (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer therefore lands independently of the protocol and backend PRs — it needs only the service's `language` field, which is already on master.
 
 ### The Python SDK renderer
 
@@ -27,7 +27,7 @@ Both tables are read with `Object.hasOwn` before use so a language named `toStri
 
 The standard that cap serves is grammatical validity, and the boundary is deliberate: a long `A | B | …` union is valid Python at any length and is left uncapped, even though CPython's `compile()` exhausts its C recursion walking the left-nested `BinOp` spine (measured on 3.9: 1,000 branches compile, 5,000 raise `RecursionError`). Nothing compiles this block — it is prompt text — so that limit costs nothing, whereas capping union length would retire the deep-chain tests that pin the walk's linear time and the class-name propagation cap. A future renderer that does need compilable output should flatten unions rather than truncate them.
 
-`renderType` validates the whole schema once (`assertSupportedJsonSchema`) and then trusts it, wrapping the walk in one `try/catch` that degrades to `Any` — the same trusted-after-validation stance the sibling `ts-types` renderer takes at this typed same-process seam ([Trust TypeScript at typed same-process seams](../../../../AGENTS.md)). It deliberately carries NO defenses against a schema whose accessors mutate between reads (post-validation cycles, TOCTOU on `const`/`enum`, self-referential functions): the input is a first-party registration (a `defineTool` literal or a raw registration) or a wire-derived plain JSON schema — the former is trusted per AGENTS.md, the latter is a `JSON.parse` product that physically cannot carry accessors, and `renderType` re-validates the whole tree on every call regardless — so such inputs are unreachable, and adding per-shape guards here would break symmetry with `ts-types` (which has none) for values the static interface forbids. `jsonSchemaToPy(schema: unknown)` accepts `unknown` and returns `Any` on a malformed schema — the Python counterpart of the TS flavor's `unknown` — but its contract is "degrade an unsupported schema", not "survive an adversarial mutating one".
+`renderType` validates the whole schema once (`assertSupportedJsonSchema`) and then trusts it, wrapping the walk in one `try/catch` that degrades to `Any` — the same trusted-after-validation stance the sibling `ts-types` renderer takes at this typed same-process boundary ([Trust TypeScript at typed same-process boundaries](../../../../AGENTS.md)). It deliberately carries NO defenses against a schema whose accessors mutate between reads (post-validation cycles, TOCTOU on `const`/`enum`, self-referential functions): the input is a first-party registration (a `defineTool` literal or a raw registration) or a wire-derived plain JSON schema — the former is trusted per AGENTS.md, the latter is a `JSON.parse` product that physically cannot carry accessors, and `renderType` re-validates the whole tree on every call regardless — so such inputs are unreachable, and adding per-shape guards here would break symmetry with `ts-types` (which has none) for values the static interface forbids. `jsonSchemaToPy(schema: unknown)` accepts `unknown` and returns `Any` on a malformed schema — the Python counterpart of the TS flavor's `unknown` — but its contract is "degrade an unsupported schema", not "survive an adversarial mutating one".
 
 ## Alternatives considered
 
@@ -37,7 +37,7 @@ The standard that cap serves is grammatical validity, and the boundary is delibe
 
 ## Consequences
 
-Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the interface package must not import its consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the seam would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend.
+Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the Consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the Service Definition package must not import its Consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the Service Definition would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend.
 
 The cost is that the Python branch of both tables is unreachable on this base: `CodeRuntime.language` is set by the loaded backend, the only published backend is `dsh-code-runtime-worker` (`'typescript'`), and the registry reads the loaded runtime rather than a config field, so no assembled application can select `renderToolsSdkPy` or `PYTHON_FLAVOR`. The model-visible surface is therefore unchanged by this note's work until a backend reporting `'python'` is published, and this PR's coverage is unit-level — the renderer output plus the dispatch and rejection paths. The keyless snapshot for the Python model interface belongs to the PR that publishes that backend, because only there does a real `cordis.yml` over published plugins produce a Python assembly; a snapshot example that mounted a fixture runtime here would assert against a test double, which [docs/testing.md](../../../../docs/testing.md) rejects as a substitute for the assembled application transcript.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
index c8ab776dfb..46ef842f4b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
@@ -19,7 +19,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 两张表在使用前都以 `Object.hasOwn` 读取，这样名为 `toString`/`constructor` 的语言不会把继承自 `Object.prototype` 的成员解析成渲染器。两个守卫的可达性不同：`SDK_RENDERERS` 的段内守卫不可达，因为 `requireCodeRuntime` 已在同一回调更早处校验过同一张 `const` 表（它带 `/* v8 ignore */`）；而 `RUN_CODE_FLAVORS` 的守卫是主要的、可公开到达的拒绝路径——任何缺席 flavor 表的语言都经 `run_code` 的语言感知 getter 到达它，而公共 `schemas()` 抵达那些 getter 时并未先过 `requireCodeRuntime`；测试直读 definition 上的其中一个 getter，用的是对两张表都缺席的语言。「在 `SDK_RENDERERS` 里却不在 `RUN_CODE_FLAVORS` 里」这种漂移已由共享的 `CodeSdkLanguage` `satisfies` 在 `typecheck` 处拒绝，两个守卫都看不到这种输入；它们如今负责的是所挂载运行时报告了一门两张表都缺席的语言。schema 发射通过 `peekRuntime()` 而非 `requireRuntime()` 读取运行时：`undefined`（无运行时，由直读 definition 的读者与 `schemas()` 到达，其中 doc-catalog 采集是唯一已交付的一个，而它们都不会喂给模型，因为组装路径先过 `requireCodeRuntime`）降级到 TypeScript flavor，而挂载了未知语言则 fail loud——这不是下方被否决的静默回退，那指的是为真实运行时发出错误语言的 SDK。新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员加两条表项——再加它的渲染器，以及点名已知值而非从中派生的散文（seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对；本包自己的 README 双语对与它的 `Config.mode` JSDoc，无任何 gate 检查其中任何一处），不动 `agent-loop`，也不动注册表结构。
 
-`code-mode.ts` 只依赖运行时 seam（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于协议和后端 PR 落地——它只需要 seam 的 `language` 字段，而该字段已在 master 上。
+`code-mode.ts` 只依赖运行时 Service Definition（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于协议和后端 PR 落地——它只需要服务的 `language` 字段，而该字段已在 master 上。
 
 ### Python SDK 渲染器
 
@@ -27,7 +27,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 该上限服务的标准是**语法合法性**，这条边界是有意划定的：长的 `A | B | …` union 在任何长度下都是合法 Python，故不设上限——尽管 CPython 的 `compile()` 在沿左嵌套 `BinOp` 脊柱下降时会耗尽 C 递归（在 3.9 上实测：1,000 个分支可编译，5,000 个抛 `RecursionError`）。没有任何东西会编译这个块——它是提示词文本——所以那条限制在这里没有代价；而给 union 长度封顶会作废那几个钉住 walk 线性时间与类名传播上限的深链测试。将来若有渲染器确实需要可编译的输出，应当把 union 拍平，而不是截断。
 
-`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程 seam 上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process seams](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的约定是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
+`renderType` 先用 `assertSupportedJsonSchema` 整树校验一次、随后信任它，用单个 `try/catch` 把整个遍历兜住并降级为 `Any`——与姊妹渲染器 `ts-types` 在这个 typed 同进程边界上采取的「校验后信任」姿态一致（[Trust TypeScript at typed same-process boundaries](../../../../AGENTS.md)）。它有意不设任何针对「访问器在多次读取间变值」的防御（校验后成环、`const`/`enum` 的 TOCTOU、自引用函数）：输入是第一方注册（`defineTool` 字面量或 raw 注册）或从 wire 桥接而来的纯 JSON——前者按 AGENTS.md 受信任，后者是 `JSON.parse` 产物、物理上不可能携带访问器，且每次调用 `renderType` 都会整树重新校验——这类输入不可达，而在此加逐形态守卫会为静态接口所禁止的值破坏与 `ts-types`（没有这类守卫）的对称。`jsonSchemaToPy(schema: unknown)` 接受 `unknown` 并对畸形 schema 返回 `Any`——TypeScript 形态 `unknown` 的对应物——但它的约定是「降级不支持的 schema」，而非「扛住对抗性的可变 schema」。
 
 ## Alternatives considered
 
@@ -37,7 +37,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 ## Consequences
 
-新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在消费方的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：接口包不得 import 其消费方的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 seam 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
+新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在 Consumer 的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：Service Definition 包不得 import 其 Consumer 的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 Service Definition 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
 
 代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml
index 5866d98309..6f61384fd8 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.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 .agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md
-2026-07-31-web-telemetry-default-mount.md: c1525a44196991d5059969ea70af34501b199323
-2026-07-31-web-telemetry-default-mount.zh.md: ef5f7e4500a1776e049ac27e0e64756e78725a61
+2026-07-31-web-telemetry-default-mount.md: 3e20fa44666139778e85a8bd5b948ab2df14529b
+2026-07-31-web-telemetry-default-mount.zh.md: 97b153255a1e64aba0a686faf1817b69467fb663
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md
index c1525a4419..3e20fa4466 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md
@@ -26,7 +26,7 @@ The keyless integration test `apps/cli/tests/telemetry-web.e2e.ts` pins the depl
 
 ## Alternatives considered
 
-**No default mount; deployments add the row themselves (continuing the SDK stance).** Rejected for this stage: this repo's web/headless composition IS the internal deployment, and default-on reporting is that deployment's product requirement; the SDK stance survives in the seam packages (unmounted = nothing leaves).
+**No default mount; deployments add the row themselves (continuing the SDK stance).** Rejected for this stage: this repo's web/headless composition IS the internal deployment, and default-on reporting is that deployment's product requirement; the SDK stance survives in the Service Definition packages (unmounted = nothing leaves).
 
 **A config field instead of an env patch for the switch.** Infeasible: cordis rows have no config-level disable semantic, and `exporter.url` validation fails loud at plugin construction, so the switch must take effect before the Loader — AppCLIEntry's patch layer is the only seat.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
index ef5f7e4500..97b153255a 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-**默认不挂载，部署方自行加行（SDK 立场的延续）。** 当前阶段不采用：本仓的 web/headless 组合就是内部部署本身，「上报默认开」是这个部署的产品要求；SDK 立场仍由 seam 包保持（不挂 = 零外发）。
+**默认不挂载，部署方自行加行（SDK 立场的延续）。** 当前阶段不采用：本仓的 web/headless 组合就是内部部署本身，「上报默认开」是这个部署的产品要求；SDK 立场仍由 Service Definition 包保持（不挂 = 零外发）。
 
 **开关做成 config 字段而非 env patch。** 不可行：cordis 行没有 config 层的 disable 语义，且 `exporter.url` 校验在插件构造期 fail-loud，开关必须在 Loader 之前生效——AppCLIEntry patch 层是唯一落点。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
index fa352e395b..87dd63043d 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.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 .agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
-2026-08-04-pointer-revealed-sidebar-scrollbars.md: eb86f710e44cd8f1fb2cef41db99504af42413bb
-2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: f3a92d6645c7f98a60fd3c4431cdfb84babfd51b
+2026-08-04-pointer-revealed-sidebar-scrollbars.md: 997945d55f7294f56a30917b050b5455de74acdf
+2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md: 128d7f12ba3e5be1c87774e79b3278383f59bf0b
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
index eb86f710e4..997945d55f 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md
@@ -20,7 +20,7 @@ The pointer surface is the column, not the list. A pointer heading for the bar c
 
 `transparent` is what makes the reveal free of layout. `scrollbar-gutter: stable` on the list exists so rows never move ([the gutter note](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)); rebinding a colour leaves that reservation in force, so the thumb appears in space the list was already holding for it.
 
-The indirection pair rather than a rule on the list, because that pair is ui-theme's documented rebinding seam: one declaration reaches both rendering paths (the WebKit pseudo-elements and Firefox's `scrollbar-color`), and custom properties inherit, which is what makes the column — rather than each scroll region in it — the thing that owns the state.
+The indirection pair rather than a rule on the list, because that pair is ui-theme's documented rebinding contract: one declaration reaches both rendering paths (the WebKit pseudo-elements and Firefox's `scrollbar-color`), and custom properties inherit, which is what makes the column — rather than each scroll region in it — the thing that owns the state.
 
 That widens the rebinding contract, so its gate states the new shape rather than accepting it by silence: `ui-theme/tests/scrollbar-styles.spec.ts` admits exactly two rebind targets, the l2 pair or `transparent`, and judges the *rule* rather than each declaration — a mixed rule (`thumb: transparent` beside an l2 hover) would repaint the bar the moment the pointer reached it while passing a per-declaration check. The elevation half compares whole values against the pair's canonical spelling, which is also what rejects a crossed pair and a token wrapped in a literal expression; an l1 rebind and a bare colour were already out.
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
index f3a92d6645..128d7f12ba 100644
--- a/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-pointer-revealed-sidebar-scrollbars.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 `transparent` 正是让这次显示不触发任何布局的原因。列表上的 `scrollbar-gutter: stable` 存在的意义就是让行永不移动（见[空槽 Agent Note](../bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)）；重新绑定的只是颜色，那份预留始终有效，所以滑块出现在列表本就为它留出的空间里。
 
-选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定 seam：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
+选择这组间接变量而不是给列表加规则，是因为这组变量正是 ui-theme 写明的重新绑定约定：一次声明同时作用于两条渲染路径（WebKit 伪元素与 Firefox 的 `scrollbar-color`），而自定义属性会继承——这正是让整列、而不是列内每个滚动区域，成为该状态所有者的原因。
 
 这拓宽了重新绑定约定，因此它的门禁把新的形态明写出来，而不是默许通过：`ui-theme/tests/scrollbar-styles.spec.ts` 只接受两种重新绑定目标，即 l2 那一组或 `transparent`，并且判定的是**整条规则**而不是逐条声明——混合规则（`thumb: transparent` 与 l2 的 hover 并列）会在指针一碰到滚动条时重新上色，却能通过逐条检查。抬升那一半按整个值与这组变量的规范写法比对，这同时也拒绝了交叉绑定和被包在字面表达式里的 token；绑回 l1 与裸颜色本来就在门外。
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
index 5cb1a7a155..98861322f3 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.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 .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
-2026-08-05-context-form-vocabulary.md: 3362059974443d1f6b543358e1eaba99ef239e43
-2026-08-05-context-form-vocabulary.zh.md: 164f6e4a2cd4c76ff4418a0540a2030a0be1b845
+2026-08-05-context-form-vocabulary.md: 573be191cd228f8ca41641c4298b2987781b3435
+2026-08-05-context-form-vocabulary.zh.md: 2c7a2124f3528a6b660f6f26253bf76a53ab7b8e
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
index 3362059974..573be191cd 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
@@ -45,7 +45,7 @@ Everything else — including a form this UI version does not present, a form ab
 
 ## Why not a presenter registry
 
-The tool seam pairs its vocabulary with `presentCall(args)`, a host-side pure function each tool implements. Context deliberately has no equivalent, because the input differs in ownership: a tool's `args` are generated by the **model** against a model-facing schema, so a translation step is unavoidable; a context `source` is constructed by the **producing plugin** itself, under no external constraint, and can simply record the facts a presentation needs. Adding a registry would have bought a translation nobody needs, at the cost of a host computation point, a wire field per context message, and a browser bundle for every producing package (the client purity gate forbids host packages from contributing components).
+The tool presentation contract pairs its vocabulary with `presentCall(args)`, a host-side pure function each tool implements. Context deliberately has no equivalent, because the input differs in ownership: a tool's `args` are generated by the **model** against a model-facing schema, so a translation step is unavoidable; a context `source` is constructed by the **producing plugin** itself, under no external constraint, and can simply record the facts a presentation needs. Adding a registry would have bought a translation nobody needs, at the cost of a host computation point, a wire field per context message, and a browser bundle for every producing package (the client purity gate forbids host packages from contributing components).
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
index 164f6e4a2c..2c7a2124f3 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
@@ -45,7 +45,7 @@ Status: implemented
 
 ## 为什么不做 presenter 注册表
 
-工具 seam 把它的词汇表与 `presentCall(args)` 配对，那是每个工具在 host 侧实现的纯函数。上下文刻意不设对应物，因为输入的归属不同：工具的 `args` 由**模型**按面向模型的 schema 生成，翻译步骤无法回避；而上下文的 `source` 由**生产方插件**自己构造，不受任何外部约束，完全可以直接记录呈现所需的事实。加一层注册表买到的是一次没人需要的翻译，代价却是一个 host 计算点、每条上下文消息一个 wire 字段、以及每个生产方包都要出浏览器 bundle（客户端纯度门禁禁止 host 包贡献组件）。
+工具呈现约定把它的词汇表与 `presentCall(args)` 配对，那是每个工具在 host 侧实现的纯函数。上下文刻意不设对应物，因为输入的归属不同：工具的 `args` 由**模型**按面向模型的 schema 生成，翻译步骤无法回避；而上下文的 `source` 由**生产方插件**自己构造，不受任何外部约束，完全可以直接记录呈现所需的事实。加一层注册表买到的是一次没人需要的翻译，代价却是一个 host 计算点、每条上下文消息一个 wire 字段、以及每个生产方包都要出浏览器 bundle（客户端纯度门禁禁止 host 包贡献组件）。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
index 439826ee6c..21dc393ff4 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.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 .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
-2026-08-05-pwsh-ui-bash-parity.md: 815b448b894e9c53b4c4a2076f6b94fdd316dd35
-2026-08-05-pwsh-ui-bash-parity.zh.md: 40109a32ed146a31a2424feb53a7cf0f41d87106
+2026-08-05-pwsh-ui-bash-parity.md: 95e884e9b67f3fb3927cd5154883ab08b3e7b3bb
+2026-08-05-pwsh-ui-bash-parity.zh.md: 937e6cefd3ac74f8e2fe797cdc4480b2b78fc3cb
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
index 815b448b89..95e884e9b6 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
@@ -12,7 +12,7 @@ The [pwsh tool bash parity decision](../../implemented/feature/2026-08-02-pwsh-t
 
 `dsh-tool-pwsh`'s `presentResult` now mirrors `dsh-tool-bash`'s call-for-call: a completed foreground result is a `terminal` card whose output body is the marker-free rendered text and whose exit-status pill is the parsed `exitCode`/`signal`; background acknowledgements and `isError` results stay generic `console`-fenced cards; non-single-text-block results stay untouched (`undefined`).
 
-The parse is shared, not duplicated: `parseExitStatus`/`ParsedExitStatus` moved from `dsh-tool-bash`'s private render module into the `@deepseek-ai/dsh-bash` seam package (exported from its index), and `dsh-tool-bash`'s `render.ts` re-exports it so its source-plane consumers keep one import root. Both tools' renderers emit the same `[exit code: N]` / `[killed by signal: X]` markers, so one seam-owned inverse can never drift between the twins — the same "shared, not duplicated" shape the [bash-env extraction](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) used for the `DSH_*` registry.
+The parse is shared, not duplicated: `parseExitStatus`/`ParsedExitStatus` moved from `dsh-tool-bash`'s private render module into the `@deepseek-ai/dsh-bash` Service Definition package (exported from its index), and `dsh-tool-bash`'s `render.ts` re-exports it so its source-plane consumers keep one import root. Both tools' renderers emit the same `[exit code: N]` / `[killed by signal: X]` markers, so one Service-Definition-owned inverse can never drift between the twins — the same "shared, not duplicated" shape the [bash-env extraction](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) used for the `DSH_*` registry.
 
 The Web UI needs no per-tool code for the card itself: the client's terminal-card bridge maps any `card: 'terminal'` result view (`terminal-card-model` in `dsh-client-ui-conversation`), so the pwsh presenter change flows through the same rendering path bash already has. The collapsed tool row does get one client classification entry: `classifyTool('pwsh')` now yields the shell-family row (`bash` variant, its own `Pwsh` title) instead of the generic `others` "Tool call" row. A keyless browser lane (`apps/web/tests/pwsh-terminal.e2e.ts`) seeds a session whose pwsh call/result is presented by the real tool on replay — the api-proxy recomputes views from logged args/result content — and pins the terminal card golden, including the exit pill and the run-state dot.
 
@@ -27,6 +27,6 @@ The Web UI needs no per-tool code for the card itself: the client's terminal-car
 ## Consequences
 
 - A Windows composition using `dsh-tool-pwsh` now shows its shell calls exactly as bash calls look in the Web UI: cwd-headed terminal card, raw output, exit-status pill, run-state dot, and the red failure treatment on non-zero exits.
-- `parseExitStatus` becomes public seam surface on `@deepseek-ai/dsh-bash`; `dsh-tool-bash/src/render.ts` keeps re-exporting it, so no bash-tool consumer changes.
+- `parseExitStatus` becomes public contract surface on `@deepseek-ai/dsh-bash`; `dsh-tool-bash/src/render.ts` keeps re-exporting it, so no bash-tool consumer changes.
 - The roadmap's stage 2 shrinks: the TUI is removed (EOL), and the terminal-card counterpart now ships on the Web surface. The Windows default composition (stage 1) remains the outstanding stage.
 - Verification: `dsh-bash` owns the parse edge cases under the per-file coverage gate; `tool-pwsh`'s presenter suite mirrors `tool-bash`'s (clean/non-zero/signal/timeout round-trip, marker-like output, background/error generics, multi-block fallback); the client row-model suite pins the `Pwsh` shell-family row; the web `pwsh-terminal` lane is the assembled keyless scenario.
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
index 40109a32ed..937e6cefd3 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 `dsh-tool-pwsh` 的 `presentResult` 现在逐调用镜像 `dsh-tool-bash`：完成的前台结果是 `terminal` 卡，输出正文为去 marker 的渲染文本，退出状态 pill 为解析出的 `exitCode`/`signal`；后台 ack 与 `isError` 结果保持通用 `console` 围栏卡片；非单一文本块结果保持不变（`undefined`）。
 
-解析是共享而非复制：`parseExitStatus`/`ParsedExitStatus` 从 `dsh-tool-bash` 的私有 render 模块迁入 `@deepseek-ai/dsh-bash` seam 包（由其 index 导出），`dsh-tool-bash` 的 `render.ts` 再导出它，使源平面消费方保持单一导入根。两个工具的渲染器发出相同的 `[exit code: N]` / `[killed by signal: X]` marker，因此一个由 seam 拥有的逆解析永远不会在孪生之间漂移——与 [bash-env 抽取](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 处理 `DSH_*` 注册表时相同的 "共享而非复制" 形态。
+解析是共享而非复制：`parseExitStatus`/`ParsedExitStatus` 从 `dsh-tool-bash` 的私有 render 模块迁入 `@deepseek-ai/dsh-bash` Service Definition 包（由其 index 导出），`dsh-tool-bash` 的 `render.ts` 再导出它，使源平面消费方保持单一导入根。两个工具的渲染器发出相同的 `[exit code: N]` / `[killed by signal: X]` marker，因此一个由 Service Definition 拥有的逆解析永远不会在孪生之间漂移——与 [bash-env 抽取](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 处理 `DSH_*` 注册表时相同的 "共享而非复制" 形态。
 
 Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 terminal 卡桥接（`dsh-client-ui-conversation` 的 `terminal-card-model`）映射任意 `card: 'terminal'` 结果视图，因此 pwsh presenter 变更直接流经 bash 已有的同一渲染路径。折叠的工具行有一处客户端分类条目：`classifyTool('pwsh')` 现在归入 shell 家族行（`bash` variant，自有 `Pwsh` 标题），而非通用的 `others` "Tool call" 行。一条 keyless 浏览器通道（`apps/web/tests/pwsh-terminal.e2e.ts`）播种一个会话，其 pwsh 调用/结果在回放时由真实工具呈现（api-proxy 从已记录的 args/result 内容重新计算视图），并钉住 terminal 卡 golden，包括退出 pill 与运行状态点。
 
@@ -27,6 +27,6 @@ Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 ter
 ## Consequences
 
 - 使用 `dsh-tool-pwsh` 的 Windows 组合现在在 Web UI 中显示的 shell 调用与 bash 调用完全一致：cwd 头的 terminal 卡、原始输出、退出状态 pill、运行状态点，以及非零退出时的红色失败处理。
-- `parseExitStatus` 成为 `@deepseek-ai/dsh-bash` 的公开 seam 表面；`dsh-tool-bash/src/render.ts` 继续再导出它，bash 工具消费方零改动。
+- `parseExitStatus` 成为 `@deepseek-ai/dsh-bash` 的公开约定表面；`dsh-tool-bash/src/render.ts` 继续再导出它，bash 工具消费方零改动。
 - 路线图阶段 2 收窄：TUI 已移除（EOL），terminal 卡对应物现已在 Web 表面交付。Windows 默认组合（阶段 1）仍是未完成的阶段。
 - 验证：`dsh-bash` 在逐文件覆盖率门禁下拥有解析边界用例；`tool-pwsh` 的 presenter 套件镜像 `tool-bash` 的（干净/非零/信号/超时往返、marker 状输出、后台/错误 generic、多块回退）；客户端行模型套件钉住 `Pwsh` shell 家族行；web `pwsh-terminal` 通道是组装后的 keyless 场景。
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
index 8153420c3d..1f486c1684 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.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 .agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
-2026-08-07-web-inline-file-mentions.md: 581efb5a9eb497e030d19118d52d003b37118108
-2026-08-07-web-inline-file-mentions.zh.md: 25c8ca6e106cd877a4d46a7b1338728e96771fc1
+2026-08-07-web-inline-file-mentions.md: cb51e6cfa5eebe0341b50c7638d51ac2d8641ba7
+2026-08-07-web-inline-file-mentions.zh.md: 1dfbf712fa6017ca0ee7238e0589b85d05902804
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
index 581efb5a9e..cb51e6cfa5 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.md
@@ -20,7 +20,7 @@ The produced-files row lists a turn's output, but the closing message usually al
 
 - **Path-shaped regex over all prose** — links `package.json` mentioned abstractly and examples that were never written; every false positive is a click that opens nothing or the wrong file. The vocabulary approach cannot produce a dead link.
 - **Linking suffix matches (`out/index.html` mentioned as `index.html` in a subdirectory listing)** — deferred; exact path and unique basename cover the observed closing-message shapes, and a wider matcher can loosen later without breaking the seam.
-- **Resolving in ui-primitives against a passed path list** — puts matching policy in the generic renderer, where other consumers would inherit it unasked. The resolver seam keeps policy with the owner.
+- **Resolving in ui-primitives against a passed path list** — puts matching policy in the generic renderer, where other consumers would inherit it unasked. The resolver contract keeps policy with the owner.
 - **Threading the vocabulary through the turn-tail chain** — the chain is a render dispatch below the message; mentions decorate markdown inside it, which only data reaching MarkdownText can do. The optional service is that data path, and its absence is the off state.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
index 25c8ca6e10..1dfbf712fa 100644
--- a/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-07-web-inline-file-mentions.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 - **对全部正文跑路径形状的正则**——会把随口提到的 `package.json` 和从未写过的示例都链接上；每个误报都是一次打开空无或错误文件的点击。词表方案不可能产生死链。
 - **链接后缀匹配（子目录列表里把 `out/index.html` 写作 `index.html`）**——暂缓；精确路径加唯一 basename 已覆盖观察到的收尾消息形态，之后放宽匹配器不会破坏这道 seam。
-- **在 ui-primitives 里对传入的路径列表做解析**——把匹配策略放进通用渲染器，其他消费方会被动继承。解析器 seam 让策略留在持有者手里。
+- **在 ui-primitives 里对传入的路径列表做解析**——把匹配策略放进通用渲染器，其他消费方会被动继承。解析器约定让策略留在持有者手里。
 - **经由 turn-tail chain 传递词表**——chain 是消息下方的渲染派发；提及要装饰的是消息内部的 markdown，只有抵达 MarkdownText 的数据才做得到。可选 service 就是那条数据通路，它的缺席即关闭态。
 
 ## 后果
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
index 51b05b277e..963e4b1cae 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.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 .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
-2026-08-08-user-explicit-skill-invocation.md: d925938279923282170dc99934f4fa44d8ecf2b4
-2026-08-08-user-explicit-skill-invocation.zh.md: 2d6d7130a1e80e3e9dba2681815668b3510356ba
+2026-08-08-user-explicit-skill-invocation.md: 55001ec2b352bba6f37dd937f64ec8b10853bffb
+2026-08-08-user-explicit-skill-invocation.zh.md: 5e9eb90502a178c4171899247ebac9bec965c89f
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
index d925938279..55001ec2b3 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
@@ -21,7 +21,7 @@ Peer-product survey (Pi, OpenCode, Claude Code, Kimi Code, Codex, DeepSeek-Reaso
 
 ## Alternatives considered
 
-- **`skill.invoke` RPC (host injects, client claims)** — implemented first, in two iterations: a single mixed message (user text folded into the body), then a gesture prompt plus injection delivered through inbox primitives. Rejected after real-session testing: the mixed message polluted the injection with user prose; the two-message form depended on wake-ordering subtleties (`followup` claims the whole next-turn queue synchronously inside the first waking call, stranding any later message in the next turn — reproduced live), and the dedicated RPC duplicated a path `session.prompt` already provides while leaving TUI/ACP to reimplement recognition. The pre-step seam removes the RPC, the claim machinery, and the ordering hazard outright.
+- **`skill.invoke` RPC (host injects, client claims)** — implemented first, in two iterations: a single mixed message (user text folded into the body), then a gesture prompt plus injection delivered through inbox primitives. Rejected after real-session testing: the mixed message polluted the injection with user prose; the two-message form depended on wake-ordering subtleties (`followup` claims the whole next-turn queue synchronously inside the first waking call, stranding any later message in the next turn — reproduced live), and the dedicated RPC duplicated a path `session.prompt` already provides while leaving TUI/ACP to reimplement recognition. The pre-step extension point removes the RPC, the claim machinery, and the ordering hazard outright.
 - **`agent.inject()` from the RPC handler** — the inject queue (`next-step`, wake-free) is claimed ahead of the next-turn prompt, putting the injection above the gesture in the log; and pairing it with a waking `followup` reintroduces the same ordering coupling. The pre-step listener injects inside the step assembly, where ordering is explicit.
 - **A host `/skill <name>` command** (command registry, plan-mode precedent) — two-token UX, no name completion, and user-only skills stay undiscoverable in the menu; the per-cwd skill catalog also fits the static command registry poorly. Rejected.
 - **Client-side expansion** (fetch body, splice into the prompt) — authorization becomes bypassable client courtesy, the log loses the invocation semantics, and Codex deleted its equivalent mechanism (custom prompts) in favor of core injection. Rejected.
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
index 2d6d7130a1..5e9eb90502 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-- **`skill.invoke` RPC（宿主注入、客户端认领）**——最先实现，共两轮迭代：先是单条混合消息（用户文本折进正文），后是经 inbox 原语投递的手势提示词加注入两条消息。经真实会话测试后否决：混合消息让用户行文污染了注入；两条消息的形态依赖唤醒顺序的微妙之处（`followup` 在第一个唤醒调用内同步认领整个 next-turn 队列，把之后的消息滞留到下一轮次——已实际复现），而专设 RPC 复制了 `session.prompt` 已提供的路径，还让 TUI/ACP（Agent Client Protocol）不得不各自重新实现识别。pre-step seam 把 RPC、认领机制与顺序隐患一并干净移除。
+- **`skill.invoke` RPC（宿主注入、客户端认领）**——最先实现，共两轮迭代：先是单条混合消息（用户文本折进正文），后是经 inbox 原语投递的手势提示词加注入两条消息。经真实会话测试后否决：混合消息让用户行文污染了注入；两条消息的形态依赖唤醒顺序的微妙之处（`followup` 在第一个唤醒调用内同步认领整个 next-turn 队列，把之后的消息滞留到下一轮次——已实际复现），而专设 RPC 复制了 `session.prompt` 已提供的路径，还让 TUI/ACP（Agent Client Protocol）不得不各自重新实现识别。pre-step 扩展点把 RPC、认领机制与顺序隐患一并干净移除。
 - **从 RPC 处理器调用 `agent.inject()`**——inject 队列（`next-step`，不唤醒）会在 next-turn 提示词之前被认领，使注入在日志中排到手势之上；而与会唤醒的 `followup` 搭配又会重新引入同样的顺序耦合。pre-step 监听器在步骤组装内部注入，那里的顺序是显式的。
 - **宿主 `/skill <name>` 命令**（命令注册表，plan 模式先例）——两 token 的 UX、没有名称补全、仅限用户的 skill 在菜单里仍不可发现；按 cwd 的 skill 目录也与静态命令注册表格格不入。否决。
 - **客户端展开**（拉取正文、拼进提示词）——授权沦为可被绕过的客户端善意，日志失去调用语义，而且 Codex 已删除其等价机制（custom prompts）转向核心注入。否决。
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 3ae0cff501..20bd2a96db 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: fd2b8ef8c7a43d9835cfbc39fc296465d7f5aba5
-2026-06-20-core-data-structures-catalog.zh.md: 6aafdd70384c89ce39113227d11db93f53107442
+2026-06-20-core-data-structures-catalog.md: 2f2e1fe43e29c972577f6b31fcd2f8249229779f
+2026-06-20-core-data-structures-catalog.zh.md: e2653a8248f6be24699dc55196e64231280cb7f9
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index fd2b8ef8c7..2f2e1fe43e 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -14,20 +14,20 @@ So the work had two intertwined questions: **what belongs in such a catalog** (t
 
 A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type-equiv` doc-sync gate that keeps every pasted type declaration and its JSDoc synchronized with source.
 
-### What counts as "core" — the spine-vs-seam line
+### What counts as "core" — the spine-vs-subsystem line
 
 > **Superseded as the page-scoping rule** by [package-anchored subsystem pages](2026-08-03-package-anchored-subsystem-pages.md): each page now anchors to the package group that declares its vocabulary. The `ts type-equiv` mechanism below remains current.
 
-The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own seam page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
+The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own subsystem page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
 
-The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a seam-page detail.*** Worked through:
+The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a subsystem-page detail.*** Worked through:
 
 - A data structure is **core** if it flows through the agent-loop spine — the loop holds, derives, streams, or logs it on every turn regardless of which plugins load (`Message`, `StreamChunk`, `SessionEvent`, the `Agent` handle) — **or** it is the single headline type a plugin author writes against a pipeline (`ToolDefinition`).
-- `ToolDefinition` is core (it is what every tool author writes) **even though the loop never holds one** — authoring-importance overrides the strict flows-through-spine rule for this one headline type. But its typing machinery — `ValueSchemaSpec`, `ParameterSchemaSpec`, `InferValue`, and `InferArgs` — is a seam-page detail. That is the spine-vs-seam line made sharp.
+- `ToolDefinition` is core (it is what every tool author writes) **even though the loop never holds one** — authoring-importance overrides the strict flows-through-spine rule for this one headline type. But its typing machinery — `ValueSchemaSpec`, `ParameterSchemaSpec`, `InferValue`, and `InferArgs` — is a subsystem-page detail. That is the spine-vs-subsystem line made sharp.
 - `ToolSchema` is core (it is a field of `GenerateOptions`, the model request that flows through every step) even though it is conceptually part of the tool pipeline — *flows through the spine* wins over *conceptual home* when they conflict.
-- The tool-presentation vocabulary (`ToolCallView`/`ToolResultView`, …), the `SessionPersistence` durability seam, and bash vocabulary are seam pages.
+- The tool-presentation vocabulary (`ToolCallView`/`ToolResultView`, …), the `SessionPersistence` durability seam, and bash vocabulary belong on subsystem pages.
 
-`core.md` is a **self-contained spine doc**: it states the exact type definition of each spine structure with minimal prose and links to sibling seam pages for the per-seam detail; the folder's [README](../../../../docs/subsystems/README.md) indexes every page. The original seam pages are `llm-streaming.md`, `session.md`, `persistence.md` (split from session along the in-memory-model vs. durability-seam line), `tools.md`, and `bash.md`.
+`core.md` is a **self-contained spine doc**: it states the exact type definition of each spine structure with minimal prose and links to sibling subsystem pages for package-owned detail; the folder's [README](../../../../docs/subsystems/README.md) indexes every page. The original subsystem pages are `llm-streaming.md`, `session.md`, `persistence.md` (split from session along the in-memory-model vs. durability-seam line), `tools.md`, and `bash.md`.
 
 ### The `ts type-equiv` mechanism — literal AND drift-proof
 
@@ -44,20 +44,20 @@ The durability requirement was specific: the doc shows the **literal** current t
 
 ## Alternatives considered
 
-- **A flat dump of all cross-package vocabulary** — the `BashExecRequest` test case killed it: if seam vocabulary is "core", the catalog helps no one; the tiered spine-vs-seam structure won.
+- **A flat dump of all cross-package vocabulary** — the `BashExecRequest` test case killed it: if seam vocabulary is "core", the catalog helps no one; the tiered spine-vs-subsystem structure won.
 - **A compiled `_Check` assignability assertion** instead of the source match — rejected because assignability does not preserve names or JSDoc: a renamed field with the same type or a changed contract comment would pass.
 - **Put each type block's source in a directive comment** — rejected for the central manifest, whose enforced 1:1 correspondence means a block can never be silently unchecked and an entry can never rot.
 
 ## Verification lesson
 
-The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and definitions, the schema DSL, presentation types, and the session/persistence split before adoption.
+The spine-vs-subsystem rule was tested against `BashExecRequest`, tool schemas and definitions, the schema DSL, presentation types, and the session/persistence split before adoption.
 
-`verify-type-equiv` must scan the complete Markdown scope, not only manifest-named documents. Otherwise an unmanifested `type-equiv` block escapes the claimed one-to-one check. The gate therefore reports such blocks as orphans. This Agent Note records that fail-closed scan rule together with the spine-vs-seam and verbatim-match decisions; the generated Cordis catalog has the symmetric design record in [its archived Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md).
+`verify-type-equiv` must scan the complete Markdown scope, not only manifest-named documents. Otherwise an unmanifested `type-equiv` block escapes the claimed one-to-one check. The gate therefore reports such blocks as orphans. This Agent Note records that fail-closed scan rule together with the spine-vs-subsystem and verbatim-match decisions; the generated Cordis catalog has the symmetric design record in [its archived Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md).
 
 ## Consequences
 
 - The vocabulary now has a single home that **cannot silently drift**: a field or public class-member change in source fails `verify-type-equiv` in `doc-sync` and CI until the paste is refreshed. Cordis service methods remain owned by the generated services catalog rather than being duplicated here.
-- The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
+- The spine-vs-subsystem line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
-- Since 2026-07-27 the seam-page tier spans every service-bearing subsystem: nine lean pages (permission presets, plan mode, runtime invariants, the HTTP carrier, storage — owning both `ctx.storage` and `ctx.storageDomain` — TUI extensions, workspaces, client modules, telemetry) cover the ten `ctx` services that had none, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
+- Since 2026-07-27 the subsystem-page tier spans every service-bearing subsystem: nine lean pages (permission presets, plan mode, runtime invariants, the HTTP carrier, storage — owning both `ctx.storage` and `ctx.storageDomain` — TUI extensions, workspaces, client modules, telemetry) cover the ten `ctx` services that had none, so each harness service and event scope has exactly one owning subsystems page — the precondition for generating per-subsystem service/event reference into these pages instead of flat catalogs.
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index 6aafdd7038..e2653a8248 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -1,4 +1,4 @@
-# Agent Note: 子系统目录与 `ts type-equiv` 漂移门禁
+# Agent Note: 核心数据结构目录与 `ts type-equiv` 漂移门禁
 
 Status: implemented
 
@@ -14,20 +14,20 @@ Status: implemented
 
 新增的 `docs/subsystems/` 目录对这些词汇编目，并配有新的 `verify-type-equiv` doc-sync（文档同步门禁），使每个粘贴的类型声明及其 JSDoc 与源码保持同步。
 
-### 何为「核心」——主干与 seam 的分界线
+### 何为「核心」——主干与子系统的分界线
 
 > **作为页面范围界定规则已被取代**，见[按包锚定的子系统页面](2026-08-03-package-anchored-subsystem-pages.md)：每页现在锚定到声明其词汇的包分组。下文的 `ts type-equiv` 机制仍然有效。
 
-范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入自己的 seam 页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
+范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入其自身的子系统页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
 
-确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是 seam 页面细节。*** 逐一验证如下：
+确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是子系统页面细节。*** 逐一验证如下：
 
 - 一个数据结构是**核心**的，如果它流经 agent loop 主干——无论加载了哪些插件，循环在每个轮次都会持有、派生、流式输出或记录它（`Message`、`StreamChunk`、`SessionEvent`、`Agent` 句柄）——**或者**它是插件作者面对某条流水线时编写的唯一标志性类型（`ToolDefinition`）。
-- `ToolDefinition` 是核心（它是每个工具作者编写的东西），**即使循环从不持有它**——对于这一个标志性类型，编写层面的重要性压过了严格的「流经主干」规则。但它的类型推导机制——`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue` 与 `InferArgs`——是 seam 页面细节。这就是主干与 seam 分界线的精确表述。
+- `ToolDefinition` 是核心（它是每个工具作者编写的东西），**即使循环从不持有它**——对于这一个标志性类型，编写层面的重要性压过了严格的「流经主干」规则。但它的类型推导机制——`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue` 与 `InferArgs`——是子系统页面细节。这就是主干与子系统分界线的精确表述。
 - `ToolSchema` 是核心（它是流经每个步骤的模型请求 `GenerateOptions` 的一个字段），即使它在概念上属于工具流水线——当*流经主干*与*概念归属*冲突时，前者胜出。
-- 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇属于 seam 页面。
+- 工具展示词汇（`ToolCallView`/`ToolResultView` 等）、`SessionPersistence` 持久性 seam 以及 bash 词汇归入子系统页面。
 
-`core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到同级 seam 页面获取各 seam 的细节；目录的 [README](../../../../docs/subsystems/README.md) 索引全部页面。最初的 seam 页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
+`core.md` 是一份**自包含的主干文档**：它给出每个主干结构的确切类型定义，辅以最少的行文，并链接到同级子系统页面获取包所拥有的细节；目录的 [README](../../../../docs/subsystems/README.md) 索引全部页面。最初的子系统页面包括 `llm-streaming.md`、`session.md`、`persistence.md`（沿内存模型与持久性 seam 的分界线从会话页面拆出）、`tools.md` 和 `bash.md`。
 
 ### `ts type-equiv` 机制——既逐字又防漂移
 
@@ -44,20 +44,20 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-- **平铺罗列所有跨包词汇**：`BashExecRequest` 测试案例否决了它。如果 seam 词汇算「核心」，目录对谁都没帮助；分层的主干与 seam 结构胜出。
+- **平铺罗列所有跨包词汇**：`BashExecRequest` 测试案例否决了它。如果 seam 词汇算「核心」，目录对谁都没帮助；分层的主干与子系统结构胜出。
 - **用编译式 `_Check` 可赋值性断言**代替源码匹配：否决。可赋值性不会保留名称或 JSDoc；同类型字段改名或约定注释变化仍会通过。
 - **将每个类型块的源文件写进指令注释**：否决，改用集中 manifest；其强制的 1:1 对应确保一个块永远不会被静默漏检，一条条目也永远不会腐烂。
 
 ## 验证教训
 
-主干与 seam 规则在采纳前经过了 `BashExecRequest`、工具 schema 与定义、schema DSL、展示类型以及会话/持久化拆分的逐一测试。
+主干与子系统规则在采纳前经过了 `BashExecRequest`、工具 schema 与定义、schema DSL、展示类型以及会话/持久化拆分的逐一测试。
 
-`verify-type-equiv` 必须扫描完整的 Markdown 范围，而不仅是 manifest 点名的文档。否则，未列入清单的 `type-equiv` 块就会逃过所宣称的一一检查。因此，门禁会将此类块报告为未列入清单的块。本 Agent Note 将这条默认拒绝放行的扫描规则，连同主干与 seam 的分界决策及逐字匹配决策一并记录；生成的 Cordis 目录在[其已归档的 Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md) 中有对称的设计记录。
+`verify-type-equiv` 必须扫描完整的 Markdown 范围，而不仅是 manifest 点名的文档。否则，未列入清单的 `type-equiv` 块就会逃过所宣称的一一检查。因此，门禁会将此类块报告为未列入清单的块。本 Agent Note 将这条默认拒绝放行的扫描规则，连同主干与子系统的分界决策及逐字匹配决策一并记录；生成的 Cordis 目录在[其已归档的 Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md) 中有对称的设计记录。
 
 ## 后果
 
 - 这些词汇现在有一个**无法悄然漂移**的唯一归属：源码中的字段或公共类成员发生变化后，`doc-sync` 和 CI 中的 `verify-type-equiv` 会持续失败，直至粘贴内容刷新。Cordis 服务方法仍由生成的服务目录负责，而不会在此重复。
-- 主干与 seam 分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
+- 主干与子系统分界线是一个可复用的范围界定工具，而非一次性的：同一条「你编写/持有/接收的东西是核心；为其提供类型推导/渲染/持久化的机制是细节」规则，后来也被用于界定事件/服务目录的 harness 层与继承层分层。
 - `ts type-equiv` 围栏是继 ` ```ts `（编译）和 ` ```ts ignore-check `（草稿）之后的第三种文档块类别。后续的姊妹门禁又增加了第四种 ` ```ts cordis-catalog `（生成签名），复用了相同的跳过并排除处理。
 - 添加或重塑核心类型现在附带一项文档义务，作者必须履行（门禁无法检测缺失的*新*类型），由 `dsh-code-review` 检查清单兜底。
-- 自 2026-07-27 起，子页面层级覆盖每个承载服务的子系统：九个精简页面（权限预设、计划模式、运行时不变式、HTTP 载体、存储——同时拥有 `ctx.storage` 与 `ctx.storageDomain`——终端扩展、工作区、客户端模块、遥测）覆盖了原先没有页面的十个 `ctx` 服务，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
+- 自 2026-07-27 起，子系统页面层级覆盖每个承载服务的子系统：九个精简页面（权限预设、计划模式、运行时不变式、HTTP 载体、存储——同时拥有 `ctx.storage` 与 `ctx.storageDomain`——终端扩展、工作区、客户端模块、遥测）覆盖了原先没有页面的十个 `ctx` 服务，于是每个 harness 服务和事件作用域都有恰好一个所属的 subsystems 页面——这是把按子系统生成的服务/事件参考写入这些页面（而非平铺目录）的前提。
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml
index d97c4dd0b7..5daaeb33b1 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.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 .agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
-2026-07-02-tool-schema-catalog.md: 673b51831512662c4e2cc3b79cd85b149c78f585
-2026-07-02-tool-schema-catalog.zh.md: 8e47d807a2490e362bb3db6d1d634c75c60997e3
+2026-07-02-tool-schema-catalog.md: 1339d6631cb6abd7abc3cf193ed805de612b8425
+2026-07-02-tool-schema-catalog.zh.md: d7275ee4b5fa7d351c1a0cf6240343d75d726630
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
index 673b518315..1339d6631c 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md
@@ -10,7 +10,7 @@ The repository had no single reference for the names, descriptions, and JSON Sch
 
 ## Decision
 
-Generate the catalog by **booting each tool plugin and reading its registered schemas**, not by parsing source. `scripts/gen-tool-catalog.ts` mounts each shipped tool package on a fresh cordis `Context` (with `SystemPrompt` + `ToolRegistry` and the injected seams the plugin's `apply` reads), calls `ctx.tools.schemas()` — exactly the `ToolSchema[]` the model is sent — disposes the context, and renders one `## <package>` section per package with a ` ```json ` `parameters` block per tool. It mirrors the `gen-cordis-catalog` / `gen-module-graph` CLI shape: default `--write` regenerates, `--check` fails if the committed copy is stale, output is deterministic (manifest-ordered, tools sorted by name). `verify-tool-catalog` (the `--check`) runs inside `doc-sync`, so relevant documentation changes and CI exercise the same freshness check.
+Generate the catalog by **booting each tool plugin and reading its registered schemas**, not by parsing source. `scripts/gen-tool-catalog.ts` mounts each shipped tool package on a fresh cordis `Context` (with `SystemPrompt` + `ToolRegistry` and the injected services the plugin's `apply` reads), calls `ctx.tools.schemas()` — exactly the `ToolSchema[]` the model is sent — disposes the context, and renders one `## <package>` section per package with a ` ```json ` `parameters` block per tool. It mirrors the `gen-cordis-catalog` / `gen-module-graph` CLI shape: default `--write` regenerates, `--check` fails if the committed copy is stale, output is deterministic (manifest-ordered, tools sorted by name). `verify-tool-catalog` (the `--check`) runs inside `doc-sync`, so relevant documentation changes and CI exercise the same freshness check.
 
 ### Why boot, not parse (the crux)
 
@@ -29,7 +29,7 @@ Booting has a cost the AST pass did not: there is no source declaration set to e
 
 ### A hand-maintained boot manifest is the irreducible policy
 
-The filesystem discovers the tool-package inventory and the completeness guard rejects omissions. `TOOL_PACKAGES` still owns an explicit boot recipe for each package because required seam implementations and config are policy, not facts that can be inferred safely from layout or injection names.
+The filesystem discovers the tool-package inventory and the completeness guard rejects omissions. `TOOL_PACKAGES` still owns an explicit boot recipe for each package because required Service providers and config are policy, not facts that can be inferred safely from layout or injection names.
 
 ### Scope
 
diff --git a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
index 8e47d807a2..d7275ee4b5 100644
--- a/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-目录通过**启动每个工具插件并读取其已注册 schema** 来生成，而不是解析源码。`scripts/gen-tool-catalog.ts` 在全新的 Cordis `Context` 上挂载每个已发布工具包；该上下文还提供 `SystemPrompt`、`ToolRegistry` 以及插件 `apply` 所读取的注入 seam。生成器调用 `ctx.tools.schemas()`——也就是发送给模型的确切 `ToolSchema[]`——随后 dispose（资源释放）上下文，并为每个包渲染一个 `## <package>` 章节，每个工具附带一个 ` ```json ` `parameters` 块。它与 `gen-cordis-catalog` / `gen-module-graph` 的 CLI 形状一致：默认 `--write` 重新生成；提交副本陈旧时 `--check` 失败；输出具有确定性（按清单排序，工具按名称排序）。`verify-tool-catalog`（即 `--check`）在 `doc-sync` 内运行，因此相关文档变更和 CI 会执行同一项新鲜度检查。
+目录通过**启动每个工具插件并读取其已注册 schema** 来生成，而不是解析源码。`scripts/gen-tool-catalog.ts` 在全新的 Cordis `Context` 上挂载每个已发布工具包；该上下文还提供 `SystemPrompt`、`ToolRegistry` 以及插件 `apply` 所读取的注入服务。生成器调用 `ctx.tools.schemas()`——也就是发送给模型的确切 `ToolSchema[]`——随后 dispose（资源释放）上下文，并为每个包渲染一个 `## <package>` 章节，每个工具附带一个 ` ```json ` `parameters` 块。它与 `gen-cordis-catalog` / `gen-module-graph` 的 CLI 形状一致：默认 `--write` 重新生成；提交副本陈旧时 `--check` 失败；输出具有确定性（按清单排序，工具按名称排序）。`verify-tool-catalog`（即 `--check`）在 `doc-sync` 内运行，因此相关文档变更和 CI 会执行同一项新鲜度检查。
 
 ### 为何启动而非解析（核心要点）
 
@@ -29,7 +29,7 @@ Cordis 目录是纯 TypeScript AST 遍历，因为每个事件/服务名都是
 
 ### 手动维护的启动 manifest 是不可化约的策略
 
-文件系统负责发现工具包清单，完整性守卫负责拒绝遗漏。`TOOL_PACKAGES` 仍然为每个包持有一份显式的启动配方，因为所需的 seam 实现和配置属于策略，不是能从目录布局或注入名称安全推断的事实。
+文件系统负责发现工具包清单，完整性守卫负责拒绝遗漏。`TOOL_PACKAGES` 仍然为每个包持有一份显式的启动配方，因为所需的 Service provider 和配置属于策略，不是能从目录布局或注入名称安全推断的事实。
 
 ### 范围
 
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
index ddfa339fdd..4442f5c345 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.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 .agents/notes/implemented/process/2026-07-20-gui-testing-system.md
-2026-07-20-gui-testing-system.md: 4a1600bbef7ef795677a446228fcc279a4b53f39
-2026-07-20-gui-testing-system.zh.md: a0e819fd5269da6aa3379309c76eea006975cef8
+2026-07-20-gui-testing-system.md: 20e2709d070439f33664d07c6424c864cd84e850
+2026-07-20-gui-testing-system.zh.md: ca59abd65a450f4afde1eed63a969bd09650ed9f
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md
index 4a1600bbef..20e2709d07 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.md
@@ -14,7 +14,7 @@ The GUI stack spans multiple application shapes, and within one shape multiple r
 
 ## Decision
 
-Cut along the architecture's natural test seams into three tiers, bottom-up:
+Cut along the architecture's natural test hooks into three tiers, bottom-up:
 
 | Tier | Under test | Key technique | File location |
 |---|---|---|---|
diff --git a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
index a0e819fd52..ca59abd65a 100644
--- a/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
+++ b/.agents/notes/implemented/process/2026-07-20-gui-testing-system.zh.md
@@ -14,7 +14,7 @@ GUI 栈需要考虑多种应用形态，同应用形态内的不同运行环境
 
 ## Decision（三层结构）
 
-贴架构天然测试缝切三层，自底向上：
+沿架构天然的测试钩子切分为三层，自底向上：
 
 | 层 | 被测物 | 关键手段 | 文件落点 |
 |---|---|---|---|
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
index 19dd1f9ab3..b124dbfd9e 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.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 .agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
-2026-08-03-package-anchored-subsystem-pages.md: 5ba7937f0c142727d343a107a3ff87f5f337931e
-2026-08-03-package-anchored-subsystem-pages.zh.md: 9166843cbfbbd065eca06e8716098581433ba41d
+2026-08-03-package-anchored-subsystem-pages.md: f429f3d41c1f152e83faeb12c379d221627e767f
+2026-08-03-package-anchored-subsystem-pages.zh.md: 3a56fa39357591197606a28b49cf0eac8f58963e
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
index 5ba7937f0c..f429f3d41c 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md
@@ -20,7 +20,7 @@ The [subsystems README](../../../../docs/subsystems/README.md) indexes every pag
 
 ## Alternatives considered
 
-**Keep the spine-vs-seam scoping rule.** It answered "is this type core?" per type, which is why the front page accumulated types from four packages while missing half of `packages/core/agent`'s public surface. Predictability by repository layout won.
+**Keep the spine-vs-subsystem scoping rule.** It answered "is this type core?" per type, which is why the front page accumulated types from four packages while missing half of `packages/core/agent`'s public surface. Predictability by repository layout won.
 
 **A flat single-document catalog.** Already rejected in the [original catalog note](2026-06-20-core-data-structures-catalog.md); the growth to forty-one pages confirmed that verdict.
 
diff --git a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
index 9166843cbf..3a56fa3935 100644
--- a/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
+++ b/.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 ## Alternatives considered
 
-**保留主干-vs-seam 界定规则。**它逐类型回答「这个类型是核心吗？」，这正是首页积累了四个包的类型、却缺失 `packages/core/agent` 一半公开 surface 的原因。按仓库布局可预测性胜出。
+**保留主干-vs-子系统界定规则。**它逐类型回答「这个类型是核心吗？」，这正是首页积累了四个包的类型、却缺失 `packages/core/agent` 一半公开 surface 的原因。按仓库布局可预测性胜出。
 
 **扁平的单文档目录。**在[原目录 note](2026-06-20-core-data-structures-catalog.md) 中已被否决；增长到四十一页证实了该结论。
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
index 77b76293e3..a07b952a01 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.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 .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
-2026-06-20-public-agent-stop-surface.md: e9c713c7ba8c784d3d66fe8f391e1b197f7394d2
-2026-06-20-public-agent-stop-surface.zh.md: c57bb32643344c237dd68479e3ab8f8a7404a594
+2026-06-20-public-agent-stop-surface.md: ecbd00864f9e11205e544049a2e1c641ac132213
+2026-06-20-public-agent-stop-surface.zh.md: e9b0a3b8735537f2323dfe246eb7002b23c14947
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
index e9c713c7ba..ecbd00864f 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
@@ -18,9 +18,9 @@ The extra surface area made the loop carry a public verb that was mostly a teard
 
 `cancel()` is the only public *stop* primitive on `Agent`. Lifecycle owners use `AgentHandle.dispose()` to stop and unregister an agent; non-owners use broad `cancel()` to abandon current and queued work or `keepInbox` to abort the active turn while retaining pending work. The implementation keeps a private turn cancellation holder, but it is not part of the plugin-facing `Agent` contract. The [Web stop decision](../bug-fix/2026-07-31-web-stop-preserves-queue.md) is the production `keepInbox` consumer.
 
-`whenIdle()` is **retained** as the public quiescence-observation primitive (resolve once the agent settles out of `running`, resolve immediately when already idle, await the loop exit when disposed). It is not a stop verb; it is how a non-owner observes the stop *completing* without disposing the agent. Its live consumers are ACP and agent tests that await settlement through this public seam (`packages/acp/acp/tests`, `packages/core/agent-loop/tests`); the production ACP bridge owns its agents and tears them down through `AgentHandle.dispose()`, so `packages/acp/acp/src` itself has no `whenIdle()` call.
+`whenIdle()` is **retained** as the public quiescence-observation primitive (resolve once the agent settles out of `running`, resolve immediately when already idle, await the loop exit when disposed). It is not a stop verb; it is how a non-owner observes the stop *completing* without disposing the agent. Its live consumers are ACP and agent tests that await settlement through this public contract (`packages/acp/acp/tests`, `packages/core/agent-loop/tests`); the production ACP bridge owns its agents and tears them down through `AgentHandle.dispose()`, so `packages/acp/acp/src` itself has no `whenIdle()` call.
 
-Public `abort()` is absent, and the disposer remains async and waits for the loop to stop. Tests exercise cancellation through the public typed cause and explicit signal seams rather than reaching into the holder.
+Public `abort()` is absent, and the disposer remains async and waits for the loop to stop. Tests exercise cancellation through the public typed cause and explicit signal APIs rather than reaching into the holder.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
index c57bb32643..e9b0a3b873 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
@@ -18,9 +18,9 @@ Status: implemented
 
 `cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用广义 `cancel()` 放弃当前和已排队工作，或使用 `keepInbox` 中止活动轮次并保留待处理工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 约定。[Web 停止决策](../bug-fix/2026-07-31-web-stop-preserves-queue.md)是生产环境中的 `keepInbox` 消费方。
 
-`whenIdle()` **保留**为公开的完全停稳观测原语（agent 从 `running` 状态稳定后 resolve，已处于 idle 时立即 resolve，dispose 后等待循环退出）。它不是停止动词；它是非所有者在不 dispose agent 的前提下观测停止*完成*的方式。它的活跃消费方是 ACP 和通过此公开 seam 等待结算的 agent 测试（`packages/acp/acp/tests`、`packages/core/agent-loop/tests`）；生产环境的 ACP 桥接层拥有其 agent 并通过 `AgentHandle.dispose()` 销毁它们，因此 `packages/acp/acp/src` 本身没有 `whenIdle()` 调用。
+`whenIdle()` **保留**为公开的完全停稳观测原语（agent 从 `running` 状态稳定后 resolve，已处于 idle 时立即 resolve，dispose 后等待循环退出）。它不是停止动词；它是非所有者在不 dispose agent 的前提下观测停止*完成*的方式。它的活跃消费方是 ACP 和通过此公开约定等待结算的 agent 测试（`packages/acp/acp/tests`、`packages/core/agent-loop/tests`）；生产环境的 ACP 桥接层拥有其 agent 并通过 `AgentHandle.dispose()` 销毁它们，因此 `packages/acp/acp/src` 本身没有 `whenIdle()` 调用。
 
-公共 `abort()` 已不存在，disposer 仍为异步并等待循环停止。测试通过公共类型化原因和显式 signal seam 验证取消，而不会伸入 holder 内部。
+公共 `abort()` 已不存在，disposer 仍为异步并等待循环停止。测试通过公共类型化原因和显式 signal API 验证取消，而不会伸入 holder 内部。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
index 7aab9c96af..956cfcee91 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.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 .agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
-2026-06-26-fsspec-style-fs-seam.md: b5c201fb192782f130d3609978d16f0fc6d4d55e
-2026-06-26-fsspec-style-fs-seam.zh.md: 2ed74af594296f2853f4d97474c4ee07ef83dbd5
+2026-06-26-fsspec-style-fs-seam.md: c11c129a55c2e9e37efc83b01a219cae8b937fbc
+2026-06-26-fsspec-style-fs-seam.zh.md: 0e73ee134563bf8208e63f37bf36415eb1bf562d
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
index b5c201fb19..c11c129a55 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
@@ -24,7 +24,7 @@ Split the stack into four layers:
 ```text
 tool          dsh-tool-fs       model-facing schemas + read windowing + text rendering; the EXECUTOR (reads/writes/edits via ctx.fs, dispatches the fs/* events)
 policy        dsh-fs-policy  observed-state + read-before-edit + write/edit freshness, contributed through the fs/* event gate (no service)
-provider seam dsh-fs            ctx.fs: text IO + atomic mutation primitives (optional version guard)
+provider contract dsh-fs            ctx.fs: text IO + atomic mutation primitives (optional version guard)
 provider      dsh-fs-local      local implementation of ctx.fs
 ```
 
@@ -61,7 +61,7 @@ type FsWriteIntent =
 
 `writeText` is atomic temp-file + rename with an explicit write expectation. `createIfAbsent` creates a missing target and rejects an existing target with `FS_NOT_OBSERVED`; it is the path used when the owner has no prior read. `replaceIfVersion` replaces only when the target exists at the observed version; a missing target or version mismatch throws `FS_STALE_VERSION`.
 
-`editText` is a provider-level guarded text mutation. When guarded it first verifies the target still exists at `expected.version`, then reads the current text, applies literal replacement, and writes atomically. The stale check must happen before literal matching so an edit based on an old read reports `FS_STALE_VERSION`, not `FS_EDIT_NOT_FOUND` or `FS_AMBIGUOUS_EDIT` from matching against newer content. Keeping this primitive on the provider seam preserves backend-local locking and lets a future remote backend implement native compare-and-edit without forcing the policy layer to pull the whole file through it.
+`editText` is a provider-level guarded text mutation. When guarded it first verifies the target still exists at `expected.version`, then reads the current text, applies literal replacement, and writes atomically. The stale check must happen before literal matching so an edit based on an old read reports `FS_STALE_VERSION`, not `FS_EDIT_NOT_FOUND` or `FS_AMBIGUOUS_EDIT` from matching against newer content. Keeping this primitive on the provider contract preserves backend-local locking and lets a future remote backend implement native compare-and-edit without forcing the policy layer to pull the whole file through it.
 
 This is a *text-storage* seam, deliberately half a level above byte-level fsspec (`cat`/`open` hand back raw bytes). UTF-8 decoding, binary/NUL rejection, guarded full-file writes, and guarded literal text edits live in the provider so the policy layer never touches raw bytes, reimplements cross-chunk decoding, or separates stale checks from the mutation critical section. Model-facing concepts still stay out of the provider: no line windows, numbered lines, rendered footers, or observed-state store leak down.
 
@@ -105,7 +105,7 @@ This Agent Note reverses two decisions from [filesystem-capability-seam](../arch
 - Text reads no longer return backend-numbered line records or `full`/`partial` views; authorization is based on version freshness, so a windowed read can authorize edit when the file is unchanged.
 - Literal edit no longer sits behind the old `applyEdit` API that mixed backend mutation with seam-owned observation policy. It remains a provider primitive as `editText`, because version guard + literal match + atomic rewrite must stay inside the provider's mutation critical section.
 
-It keeps the interface/implementation/consumer discipline, consumer-never-imports-backend rule, backend-defined target/version/display metadata, atomic local writes, and the shared `FsError` taxonomy.
+It keeps the Service Definition / Service provider / Consumer discipline, consumer-never-imports-backend rule, backend-defined target/version/display metadata, atomic local writes, and the shared `FsError` taxonomy.
 
 ## Verification
 
@@ -123,8 +123,8 @@ The seam was later extended with direct directory listing by [Add direct directo
 
 ## Consequences
 
-- Adds a fourth fs package and a new plugin layer. This is intentional: it is the previously deferred policy layer, not a second abstract backend seam.
+- Adds a fourth fs package and a new plugin layer. This is intentional: it is the previously deferred policy layer, not a second abstract backend contract.
 - Direct `ctx.fs` use bypasses the policy: a direct `ctx.fs.readText` emits no `fs/observed`, so under the default policy a later `edit` rejects with `FS_NOT_OBSERVED` until the file is read through the `read` tool. The failure is explicit and documented.
 - Large-file line windowing moves from the backend to the `read` tool in `dsh-tool-fs`; text decoding and binary rejection stay in `ctx.fs.streamText`, so this is relocation of windowing only, not a second text-IO implementation.
-- Keeping `editText` in the provider seam means every backend must implement the literal replacement contract. This is intentional: the operation is not pure storage, but stale guard + literal match + atomic rewrite is the unit that must stay together for correct error attribution and concurrency behavior. The contract should stay narrow and text-only so future backends can implement it natively or by whole-file rewrite.
+- Keeping `editText` in the provider contract means every backend must implement the literal replacement contract. This is intentional: the operation is not pure storage, but stale guard + literal match + atomic rewrite is the unit that must stay together for correct error attribution and concurrency behavior. The contract should stay narrow and text-only so future backends can implement it natively or by whole-file rewrite.
 - Freshness permits full-file `write` after a windowed read. That is weaker than the old view check, but avoids making large files impossible to edit; prompt guidance still discourages blind full replaces.
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
index 2ed74af594..0e73ee1345 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 ```text
 tool          dsh-tool-fs       model-facing schemas + read windowing + text rendering; the EXECUTOR (reads/writes/edits via ctx.fs, dispatches the fs/* events)
 policy        dsh-fs-policy  observed-state + read-before-edit + write/edit freshness, contributed through the fs/* event gate (no service)
-provider seam dsh-fs            ctx.fs: text IO + atomic mutation primitives (optional version guard)
+provider contract dsh-fs            ctx.fs: text IO + atomic mutation primitives (optional version guard)
 provider      dsh-fs-local      local implementation of ctx.fs
 ```
 
@@ -61,7 +61,7 @@ type FsWriteIntent =
 
 `writeText` 通过临时文件 + rename 实现原子写入，并带有显式的写入期望。`createIfAbsent` 创建不存在的目标，对已存在的目标以 `FS_NOT_OBSERVED` 拒绝；这是 owner 没有先前读取时使用的路径。`replaceIfVersion` 仅在目标以观测到的版本存在时替换；目标不存在或版本不匹配时抛出 `FS_STALE_VERSION`。
 
-`editText` 是提供方级别的受保护文本变更。启用守卫时，它首先验证目标仍以 `expected.version` 存在，然后读取当前文本、应用字面替换并原子写入。陈旧检查必须在字面匹配之前发生，这样基于旧读取的编辑会报告 `FS_STALE_VERSION`，而不是对更新内容进行匹配后报告 `FS_EDIT_NOT_FOUND` 或 `FS_AMBIGUOUS_EDIT`。将此原语保留在提供方 seam 上，保持了后端本地锁定的能力，也让未来的远程后端能够实现原生的 compare-and-edit，而无需策略层拉取整个文件。
+`editText` 是提供方级别的受保护文本变更。启用守卫时，它首先验证目标仍以 `expected.version` 存在，然后读取当前文本、应用字面替换并原子写入。陈旧检查必须在字面匹配之前发生，这样基于旧读取的编辑会报告 `FS_STALE_VERSION`，而不是对更新内容进行匹配后报告 `FS_EDIT_NOT_FOUND` 或 `FS_AMBIGUOUS_EDIT`。将此原语保留在提供方约定上，保持了后端本地锁定的能力，也让未来的远程后端能够实现原生的 compare-and-edit，而无需策略层拉取整个文件。
 
 这是一个*文本存储* seam，刻意比字节级 fsspec（`cat`/`open` 返回原始字节）高半个层次。UTF-8 解码、二进制/NUL 拒绝、受保护的全文件写入和受保护的字面文本编辑都在提供方内完成，因此策略层从不接触原始字节、不重新实现跨分片解码、也不将陈旧检查与变更临界区分离。面向模型的概念仍然不下沉到提供方：行窗口、带行号的行、渲染的页脚、观测状态存储都不会泄漏下去。
 
@@ -105,7 +105,7 @@ type FsWriteIntent =
 - 文本读取不再返回后端编号的行记录或 `full`/`partial` 视图；授权基于版本新鲜度，因此窗口化读取在文件未变时即可授权编辑。
 - 字面编辑不再位于旧的 `applyEdit` API 之后（该 API 混合了后端变更与 seam 拥有的观测策略）。它作为 `editText` 保留为提供方原语，因为版本守卫 + 字面匹配 + 原子重写必须留在提供方的变更临界区内。
 
-保留的内容：接口/实现/消费方纪律、消费方不导入后端规则、后端定义的 target/version/display 元数据、原子本地写入，以及共享的 `FsError` 分类体系。
+保留的内容：Service Definition / Service provider / Consumer 纪律、消费方不导入后端规则、后端定义的 target/version/display 元数据、原子本地写入，以及共享的 `FsError` 分类体系。
 
 ## 验证
 
@@ -123,8 +123,8 @@ type FsWriteIntent =
 
 ## 后果
 
-- 新增第四个 fs 包和一个新的插件层。这是有意为之：它是此前推迟的策略层，而非第二个抽象后端 seam。
+- 新增第四个 fs 包和一个新的插件层。这是有意为之：它是此前推迟的策略层，而非第二个抽象后端约定。
 - 直接使用 `ctx.fs` 会绕过策略：直接 `ctx.fs.readText` 不发出 `fs/observed`，因此在默认策略下，后续 `edit` 会以 `FS_NOT_OBSERVED` 拒绝，直到通过 `read` 工具读取该文件。这一失败是显式且有文档记录的。
 - 大文件行窗口化从后端移至 `dsh-tool-fs` 中的 `read` 工具；文本解码和二进制拒绝留在 `ctx.fs.streamText` 中，因此这只是窗口化逻辑的迁移，而非第二套文本 IO 实现。
-- 将 `editText` 保留在提供方 seam 上意味着每个后端都必须实现字面替换约定。这是有意为之：该操作不是纯存储，但陈旧守卫 + 字面匹配 + 原子重写是必须保持在一起的单元，以确保正确的错误归因和并发行为。该约定应保持窄且仅限文本，以便未来后端可以原生实现或通过全文件重写实现。
+- 将 `editText` 保留在提供方约定上意味着每个后端都必须实现字面替换约定。这是有意为之：该操作不是纯存储，但陈旧守卫 + 字面匹配 + 原子重写是必须保持在一起的单元，以确保正确的错误归因和并发行为。该约定应保持窄且仅限文本，以便未来后端可以原生实现或通过全文件重写实现。
 - 新鲜度允许在窗口化读取后进行全文件 `write`。这比旧的视图检查更弱，但避免了大文件无法编辑的问题；提示词引导仍然不鼓励盲目的全文件替换。
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
index 6a77e7a95a..80f7b1a144 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.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 .agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
-2026-07-04-tighten-hook-protocol-contract.md: a67d0e8447e36516006e57051581c03877c1ba12
-2026-07-04-tighten-hook-protocol-contract.zh.md: b57a8da8d9f0f921b69d0b63ad5c655eb47f5967
+2026-07-04-tighten-hook-protocol-contract.md: 0c2397fa298ebd67d24f86d66d7d049b9da57ce9
+2026-07-04-tighten-hook-protocol-contract.zh.md: b0edd754eb5115936a03a892a2db0b67552f64f1
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
index a67d0e8447..0c2397fa29 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-04-tighten-hook-protocol-contract.zh.md)
 
 Four pieces of the `dsh-hook-protocol`/bridge contract missed the discipline the [subagent-observe-enrich Agent Note](../../archived/feature/2026-06-30-subagent-observe-enrich.md) records — it dropped an `agentType` lifecycle field for lacking a consumer, and these failed the same test:
 
-1. **`HookDialect`'s `'native'` variant** (`packages/hooks/hook-protocol/src/types.ts`) had zero producers — the bridges stamp `'claude'` and `'codex'`; the only `'native'` constructor anywhere was the lib's own unit test. The field's own JSDoc defines `dialect` as "the bridge that ran it", and native is not a bridge: the [interception-seams Agent Note](../feature/2026-06-30-interception-seams.md) records that native hooks are not a package and that "a native plugin can already use the typed Decisions" without the durable hook log, and the flagship native-plugin worked example asserts exactly that (no `hook/*` events at all).
+1. **`HookDialect`'s `'native'` variant** (`packages/hooks/hook-protocol/src/types.ts`) had zero producers — the bridges stamp `'claude'` and `'codex'`; the only `'native'` constructor anywhere was the lib's own unit test. The field's own JSDoc defines `dialect` as "the bridge that ran it", and native is not a bridge: the [interception extension-points Agent Note](../feature/2026-06-30-interception-extension-points.md) records that native hooks are not a package and that "a native plugin can already use the typed Decisions" without the durable hook log, and the flagship native-plugin worked example asserts exactly that (no `hook/*` events at all).
 2. **`HookOutput.suppressOutput`** (same file) was parsed by the codec and discarded on every path: no bridge branch, no merge fold, no warn, no deferred-list row — uniquely among its parsed-but-unhonored siblings, each of which carries a stated deferral (`updatedInput` → a logged warn plus the [pre-tool-input-rewrite proposal](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md); `systemMessage` → a logged warn plus a README deferred row; `continue`/`stopReason` → a `TODO(hook-continue-false)` anchor plus the `'stop'` decision record). Structurally there is nothing to suppress: hook stdout never enters any transcript (context flows only via `additionalContext`; the log records only `decision`/`stderrSummary`), so a hook author setting `suppressOutput: true` got silent nothing with no warn.
 3. **`defaultTimeoutMs` was double-defaulted in both bridge configs with a floating literal** — a schema `.default(600_000)` AND a `?? 600_000` fallback (`packages/hooks/hooks-claude/src/index.ts`, `packages/hooks/hooks-codex/src/index.ts`), two homes per bridge for one protocol-level constant, so the bridges could silently drift apart on the shared default. *The proposal's original remedy — delete the knob outright — was overtaken by the no-hardcoded-tunables audit, which kept the knob as the explicit bridge-owned config (and added `stderrSummaryMaxChars` beside it); what remained to fix was the literal's home.*
 4. **The `hook/result` semantics lived in the bridges, twice, not in the lib that owns the event.** `summarize()` — the stderr truncation rule — was byte-identical in `packages/hooks/hooks-claude/src/index.ts` and `packages/hooks/hooks-codex/src/index.ts`, and so was the decision-string rule `output.decision ?? (output.continue === false ? 'stop' : 'pass')`; yet `dsh-hook-protocol` declared `hook/result`, documented `stderrSummary` as "truncated" without owning the truncation, and documented the decision values without owning the mapping. If one bridge drifted (a different cap, a different fallback), the shared durable event's semantics would fork silently.
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
index b57a8da8d9..b0edd754eb 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `dsh-hook-protocol`/bridge 约定中有四部分没有遵守 [subagent observe/enrich Agent Note](../../archived/feature/2026-06-30-subagent-observe-enrich.md)记下的准则——后者因缺少消费方而删除 `agentType` 生命周期字段，以下各项没有通过同一检验：
 
-1. **`HookDialect` 的 `'native'` 变体**（`packages/hooks/hook-protocol/src/types.ts`）没有生产者——bridge 会标记 `'claude'` 和 `'codex'`；所有位置中唯一构造 `'native'` 的是该库自己的单元测试。字段自身的 JSDoc 将 `dialect` 定义为“运行它的 bridge”，而 native 不是 bridge：[拦截 seam Agent Note](../feature/2026-06-30-interception-seams.md) 记载 native 钩子不是一个包，并且“native 插件无需持久钩子日志即可使用类型化 Decision”；旗舰 native 插件实践示例恰好断言了这一点（完全没有 `hook/*` 事件）。
+1. **`HookDialect` 的 `'native'` 变体**（`packages/hooks/hook-protocol/src/types.ts`）没有生产者——bridge 会标记 `'claude'` 和 `'codex'`；所有位置中唯一构造 `'native'` 的是该库自己的单元测试。字段自身的 JSDoc 将 `dialect` 定义为“运行它的 bridge”，而 native 不是 bridge：[拦截扩展点 Agent Note](../feature/2026-06-30-interception-extension-points.md) 记载 native 钩子不是一个包，并且“native 插件无需持久钩子日志即可使用类型化 Decision”；旗舰 native 插件实践示例恰好断言了这一点（完全没有 `hook/*` 事件）。
 2. **`HookOutput.suppressOutput`**（同一文件）被 codec 解析后在所有路径上均被丢弃：没有 bridge 分支处理它、没有合并 fold、没有 warn、没有 deferred-list 行——在所有「被解析但未兑现」的同类字段中它是唯一没有明确延期声明的（`updatedInput` → 一条 warn 日志加 [pre-tool-input-rewrite 提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)；`systemMessage` → 一条 warn 日志加 README deferred 行；`continue`/`stopReason` → 一个 `TODO(hook-continue-false)` 锚点加 `'stop'` decision 记录）。从结构上看根本无物可抑制：钩子 stdout 从不进入任何 transcript（文本记录）；上下文仅通过 `additionalContext` 流入，日志也只记录 `decision`/`stderrSummary`。因此，钩子作者设置 `suppressOutput: true` 得到的是无声的空操作，且无任何警告。
 3. **`defaultTimeoutMs` 在两个 bridge 配置中都以游离的字面量重复设置了默认值**——schema 的 `.default(600_000)` 加上一个 `?? 600_000` 回退（`packages/hooks/hooks-claude/src/index.ts`、`packages/hooks/hooks-codex/src/index.ts`），一个协议级常量在每个 bridge 中有两个归属地，两个 bridge 可能在共享默认值上悄然分歧。*提案最初的补救措施是彻底删除该旋钮，但被 no-hardcoded-tunables 审计所取代：审计保留了该旋钮作为 bridge 拥有的显式配置（并在旁边新增了 `stderrSummaryMaxChars`）；剩下要修的是字面量的归属地。*
 4. **`hook/result` 的语义存在于两个 bridge 中（各一份），而非拥有该事件的 lib。** `summarize()`——stderr 截断规则——在 `packages/hooks/hooks-claude/src/index.ts` 与 `packages/hooks/hooks-codex/src/index.ts` 中逐字节相同；decision 字符串规则 `output.decision ?? (output.continue === false ? 'stop' : 'pass')` 同样如此。然而 `dsh-hook-protocol` 声明了 `hook/result`、在文档中将 `stderrSummary` 描述为「已截断」却不拥有截断逻辑，记录了 decision 值却不拥有映射逻辑。如果某个 bridge 漂移（不同的上限、不同的回退），共享持久化事件的语义就会悄然分叉。
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
index 9c7359d8d6..5355169c7f 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.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 .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
-2026-07-22-plan-specific-collaboration-state.md: d139f3d861244c80acfb604d17172461bbf0cd57
-2026-07-22-plan-specific-collaboration-state.zh.md: 3d51b8fc31196efca49693050258c323ff3af843
+2026-07-22-plan-specific-collaboration-state.md: bab39ccc594c35b482c8a24ab805b6c4f2d2472b
+2026-07-22-plan-specific-collaboration-state.zh.md: 9dc88884b5a63baff4d682ff04b40f6970160c70
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
index d139f3d861..bab39ccc59 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md
@@ -49,7 +49,7 @@ The tool renders the submitted plan as a generic card titled by its first headin
 
 **Let one presentation transport own plan state.** Rejected because TUI, Web, resume, fork, prompt assembly, and the exit tool need the same logged fact independently of any one transport. Presentation adapters own only their projections.
 
-**Split a capability-seam trio or put the state in the agent loop.** Rejected because plan mode has no swappable backend, while existing session, prompt, tool, command, and lifecycle seams already provide every required hook.
+**Split a capability-seam trio or put the state in the agent loop.** Rejected because plan mode has no swappable backend, while existing session, prompt, tool, command, and lifecycle extension points already provide every required hook.
 
 **Put flips in surface messages or store plans in files.** Rejected because the stance is a log-only fact and the tool argument already records the reviewable plan. Surface duplication spends model context, while a plan directory creates a second durable home.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
index 3d51b8fc31..9dc88884b5 100644
--- a/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md
@@ -49,7 +49,7 @@ Plan mode 拥有一个 plan 专用产品包：位于 `packages/plan/plan-mode/`
 
 **让一种呈现传输拥有 plan 状态。** 不予采纳，因为 TUI、Web、恢复、fork、提示词组装和退出工具都需要独立于任何单一传输使用同一项已记录事实。呈现适配器只拥有各自的投影。
 
-**拆成能力 seam 三包，或把状态放进 agent loop。** 不予采纳，因为 plan mode 没有可替换后端，而现有的会话、提示词、工具、命令和生命周期 seam 已经提供所需的全部钩子。
+**拆成能力 seam 三包，或把状态放进 agent loop。** 不予采纳，因为 plan mode 没有可替换后端，而现有的会话、提示词、工具、命令和生命周期扩展点已经提供所需的全部钩子。
 
 **将状态切换写入表层消息，或把计划存入文件。** 不予采纳，因为协作状态是仅日志事实，工具参数已经记录了可评审的计划。重复写入表层会消耗模型上下文，而计划目录会形成第二个持久归属。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
index 736a9aee5f..d09614a7fa 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.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 .agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
-2026-07-23-acp-automation-only-protocol.md: 0fe2fc27a963d21e8a24c1682359ab3bc9e7af48
-2026-07-23-acp-automation-only-protocol.zh.md: d161f22672b1c1a1db131a58b4b8da531930ab97
+2026-07-23-acp-automation-only-protocol.md: 29da3025251f9826c5780493bb2725b114a40601
+2026-07-23-acp-automation-only-protocol.zh.md: bf326ce9f6fea8c55b842bc61e3d8521032ea4d1
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
index 0fe2fc27a9..29da302525 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
@@ -36,7 +36,7 @@ Protocol and lifecycle tests pin stop-reason and prompt codecs, version negotiat
 
 **Keep ACP as an editor UI until Web reaches parity.** Rejected because it leaves two interactive contracts to evolve and keeps editor conventions in the automation boundary.
 
-**Keep the earlier editor bridge behind disciplined seams.** Rejected even though that bridge correctly used interface services, tool-owned render intents, approval and user-interaction answerers, harness-owned execution, and a stdout-pure composition. Its terminal cards were capability-gated, display-only Zed `_meta` projections with a text fallback rather than ACP `terminal/create`, so shell execution never left the harness. The projection derived each display terminal id from the stable per-call id to prevent collisions and recovered exit code or signal from the rendered status markers because the pure result presenter received content blocks rather than a structured exit; marker round-trip tests and an explicit no-capability `console` fallback test pinned both contracts. Those boundaries were coherent but could not make editor cards, session navigation, configuration pickers, and human elicitation belong in an automation protocol.
+**Keep the earlier editor bridge behind disciplined service boundaries.** Rejected even though that bridge correctly used interface services, tool-owned render intents, approval and user-interaction answerers, harness-owned execution, and a stdout-pure composition. Its terminal cards were capability-gated, display-only Zed `_meta` projections with a text fallback rather than ACP `terminal/create`, so shell execution never left the harness. The projection derived each display terminal id from the stable per-call id to prevent collisions and recovered exit code or signal from the rendered status markers because the pure result presenter received content blocks rather than a structured exit; marker round-trip tests and an explicit no-capability `console` fallback test pinned both contracts. Those boundaries were coherent but could not make editor cards, session navigation, configuration pickers, and human elicitation belong in an automation protocol.
 
 **Replace ACP with a private subagent RPC.** Rejected because ACP already supplies a typed, interoperable process protocol and is used by the out-of-process subagent backend.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
index d161f22672..bf326ce9f6 100644
--- a/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md
@@ -36,7 +36,7 @@ ACP 快照套件仍会启动组装后的 ACP 示例，并保留用于锁定后
 
 **在 Web 达到同等能力前，继续将 ACP 作为编辑器 UI。** 不予采用，因为这会留下两套需要演进的交互约定，并使编辑器约定继续存在于自动化边界中。
 
-**通过严格的 seam 保留早期编辑器桥接层。** 不予采用，尽管该桥接层正确使用了接口服务、工具自有的 render intent、审批与用户交互应答者、harness 自有执行，以及保持 stdout 纯净的组装。其终端卡片是经过能力门控、仅用于展示的 Zed `_meta` 投影，并提供文本回退，而非使用 ACP `terminal/create`，因此 shell 执行从未离开 harness。该投影从稳定的逐调用 id 派生每个展示用终端 id，以避免冲突；由于纯结果展示器接收的是内容块，而不是结构化退出信息，它会从渲染后的状态标记中恢复退出码或信号。标记往返测试和显式的无能力 `console` 回退测试锁定了这两项约定。这些边界保持一致，却无法让编辑器卡片、会话导航、配置选择器和面向人类的询问成为自动化协议应有的职责。
+**通过严格的服务边界保留早期编辑器桥接层。** 不予采用，尽管该桥接层正确使用了接口服务、工具自有的 render intent、审批与用户交互应答者、harness 自有执行，以及保持 stdout 纯净的组装。其终端卡片是经过能力门控、仅用于展示的 Zed `_meta` 投影，并提供文本回退，而非使用 ACP `terminal/create`，因此 shell 执行从未离开 harness。该投影从稳定的逐调用 id 派生每个展示用终端 id，以避免冲突；由于纯结果展示器接收的是内容块，而不是结构化退出信息，它会从渲染后的状态标记中恢复退出码或信号。标记往返测试和显式的无能力 `console` 回退测试锁定了这两项约定。这些边界保持一致，却无法让编辑器卡片、会话导航、配置选择器和面向人类的询问成为自动化协议应有的职责。
 
 **用私有 subagent RPC 替换 ACP。** 不予采用，因为 ACP 已经提供类型化、可互操作的进程协议，并由跨进程 subagent 后端使用。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
index 611d20bfe2..f749676ff4 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.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 .agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
-2026-07-24-agent-loop-observable-state-machine.md: b1773fdf7fd3bcbea9c6b9a4a0ce37c715bce4ca
-2026-07-24-agent-loop-observable-state-machine.zh.md: ef44e9c058d165bfbbe226e9d0fca1e6f8072f53
+2026-07-24-agent-loop-observable-state-machine.md: 2c9cdd3ac090d2236e8922e06c94b5504570fead
+2026-07-24-agent-loop-observable-state-machine.zh.md: 0659fb3414de49d3ee12dc913fa62698bb2e6a79
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
index b1773fdf7f..2c9cdd3ac0 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.md
@@ -31,7 +31,7 @@ The event taxonomy removes the legacy prompt preparation/submission and serial s
 
 ## Alternatives considered
 
-**Keep the fine-grained event sequence.** This preserves a dedicated interception point for every internal phase, including request-only prefixes, assistant-message rewriting, post-step work, in-turn request recovery, and terminal stop overrides. It also makes the loop's private sequencing a permanent public contract and lets overlapping seams express conflicting decisions. The decision accepts the lost interception points in exchange for one boundary per supported extension responsibility.
+**Keep the fine-grained event sequence.** This preserves a dedicated interception point for every internal phase, including request-only prefixes, assistant-message rewriting, post-step work, in-turn request recovery, and terminal stop overrides. It also makes the loop's private sequencing a permanent public contract and lets overlapping extension points express conflicting decisions. The decision accepts the lost interception points in exchange for one boundary per supported extension responsibility.
 
 **Represent disposal as a third `AgentStatus`.** This gives retained handles a terminal status value but duplicates the registry lifecycle already expressed by `agent/disposed`. The decision keeps `AgentStatus` about live activity and makes registration lifetime a separate dimension.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
index ef44e9c058..0659fb3414 100644
--- a/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.zh.md
@@ -21,7 +21,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 - 待处理消息插入时会发出 `agent/inbox/inserted`，随后要么在原子纯删除领取后发出 `agent/inbox/claimed`，要么在普通删除后发出 `agent/inbox/discarded`。`MessageId` 关联确切消息；持久 splice 坐标保留 placement 与取消信息。inbox 事件描述插入、领取和丢弃，而不是轮次完成。
 - 已领取的轮次经过 pre-step 进入决策和零个或多个请求步骤。自动重试会关闭失败轮次并立即开启另一个轮次；`agent/settled` 只报告该重试链的终态轮次，且仍不同于 agent 整体转换到 `status === 'idle'`。
 
-循环保留四个状态机扩展事件。`agent/pre-step` 对独占的已领取批次执行 reject 或 enter 决策，并在每个拟议步骤前运行。`agent/request` 是冻结调用配置所用的 waterfall；配置只能来自 `await next()`，不再通过重复的位置参数提供。`agent/request-error` 串行确定需要等待的模型请求恢复由谁负责。当轮次原本已经没有剩余工作时，`agent/turn-stopping` 运行；需要再执行一个步骤的监听器使用 `agent.steer()` 记录真实的 steering（中途引导），循环在所有监听器完成后根据这份数据作出决定。
+循环保留四个状态机扩展事件。`agent/pre-step` 对独占的已领取批次执行 reject 或 enter 决策，并在每个拟议步骤前运行。`agent/request` 是冻结调用配置所用的 waterfall；配置只能来自 `await next()`，不再通过重复的位置参数提供。`agent/request-error` 串行确定需要等待的模型请求恢复由谁负责。当轮次原本已经没有剩余工作时，`agent/turn-stopping` 运行；需要再执行一个步骤的监听器使用 `agent.steer()` 记录真实的 steering，循环在所有监听器完成后根据这份数据作出决定。
 
 是否继续和终止执行由数据表达，不再由返回的控制枚举表达。工具调用和已接受的 steering 要求再执行一个步骤。携带 `concludesTurn` 的工具结果会在其所属步骤终止工具循环。循环不再暴露通用的 `ContinuationDecision` 或终止返回通道。
 
@@ -31,7 +31,7 @@ agent 生命周期、agent 整体活动状态、收件箱条目的进度以及
 
 ## 考虑过的替代方案
 
-**保留细粒度事件序列。** 这样可以为每个内部阶段保留专用拦截点，包括仅用于请求的前缀、助手消息改写、步骤后处理、轮次内请求恢复以及终止覆盖。但这也会使循环的私有执行顺序成为永久的公开约定，并允许相互重叠的 seam 表达彼此冲突的决策。当前决策接受这些拦截点的缺失，以换取每项受支持的扩展职责仅对应一个边界。
+**保留细粒度事件序列。** 这样可以为每个内部阶段保留专用拦截点，包括仅用于请求的前缀、助手消息改写、步骤后处理、轮次内请求恢复以及终止覆盖。但这也会使循环的私有执行顺序成为永久的公开约定，并允许相互重叠的扩展点表达彼此冲突的决策。当前决策接受这些拦截点的缺失，以换取每项受支持的扩展职责仅对应一个边界。
 
 **将 dispose 表示为第三种 `AgentStatus`。** 这样会让仍被持有的句柄得到一个终止状态值，但也会重复表达 `agent/disposed` 已经体现的注册表生命周期。当前决策让 `AgentStatus` 只表示 agent 存续期间的活动状态，并将注册生命周期作为独立维度。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
index c9735b903f..36c3b2190c 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.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 .agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
-2026-07-26-merge-subagent-control-service.md: ae7214f7c8c28f8a4b7d754839acbc938270f125
-2026-07-26-merge-subagent-control-service.zh.md: 85a7f62ce789d80dc38ca52017554aa2c2921599
+2026-07-26-merge-subagent-control-service.md: 2757ba678863a355e0f9c4bb324035ba666796be
+2026-07-26-merge-subagent-control-service.zh.md: d9fd913fb229f63548d2aae65ed62c98a7bd4de0
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
index ae7214f7c8..2757ba6788 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md
@@ -8,7 +8,7 @@ The public operation set is refined by [Intent-named subagent continuation opera
 
 ## Problem
 
-Continuable-child orchestration originally lived in a separate `ctx.subagentControl` service above the raw `ctx.subagents` provider seam. That split kept provider dispatch independent of Tasks and persistence, and gave model and human adapters one orchestration contract. In practice the two services described one capability family, every continuable caller needed both, and the provider-bound delegation tool had to infer policy from `provider.resume` and inspect whether the control service and `send_message` tool happened to be loaded. This made sibling plugin presence decide execution semantics and coupled starting continuable work to an optional follow-up surface.
+Continuable-child orchestration originally lived in a separate `ctx.subagentControl` service above the raw `ctx.subagents` provider contract. That split kept provider dispatch independent of Tasks and persistence, and gave model and human adapters one orchestration contract. In practice the two services described one capability family, every continuable caller needed both, and the provider-bound delegation tool had to infer policy from `provider.resume` and inspect whether the control service and `send_message` tool happened to be loaded. This made sibling plugin presence decide execution semantics and coupled starting continuable work to an optional follow-up surface.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
index 85a7f62ce7..d9fd913fb2 100644
--- a/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 ## 问题
 
-可继续 child 的编排最初位于原始 `ctx.subagents` 提供方 seam 之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排约定。实践中，两个服务属于同一组功能，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
+可继续 child 的编排最初位于原始 `ctx.subagents` 提供方约定之上的独立 `ctx.subagentControl` 服务中。该拆分使提供方分发与 Task 和持久化无关，并为模型与人工适配器提供统一的编排约定。实践中，两个服务属于同一组功能，每个可继续调用方都需要二者，而绑定提供方的委派工具必须根据 `provider.resume` 推断策略，并检查控制服务与 `send_message` 工具是否碰巧已加载。如此一来，配套插件是否存在会决定执行语义，并将可继续工作的启动耦合到可选的后续操作接口。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
index 9d3eb4677f..e25830686b 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.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 .agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
-2026-07-28-remove-synthetic-log-only-turns.md: 61c1aa4b1599fe020e0cd96c32daea01d419e95a
-2026-07-28-remove-synthetic-log-only-turns.zh.md: 65281d8342997165b465a744bb08dd2d815e014e
+2026-07-28-remove-synthetic-log-only-turns.md: cb4925fb7897d95898b3f620c5034b3082a72a0d
+2026-07-28-remove-synthetic-log-only-turns.zh.md: 1fb572449e0a78697a9c32a0e42bb5ae7499f97c
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
index 61c1aa4b15..cb4925fb78 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md
@@ -10,7 +10,7 @@ The session store exposed `appendOutOfBand()` so a plugin could publish a late l
 
 That rule was introduced when persistence recovery treated the last `turn/end` as the only committed boundary. The persistence scanners now preserve every valid contiguous event, and crash repair reacts only to an actually open turn. Retaining synthetic turns for title updates therefore inflated turn counts, produced execution outcomes for work that never ran the model, and let a late metadata write consume the next turn number.
 
-The generic seam also duplicated domain policy. Its marker map said which plugin events were eligible, while the title capability already owned cancellation, liveness, and stale-result rules. Replacing it with another generic or title-specific append wrapper would preserve the same type indirection for two literal event types.
+The generic helper also duplicated domain policy. Its marker map said which plugin events were eligible, while the title capability already owned cancellation, liveness, and stale-result rules. Replacing it with another generic or title-specific append wrapper would preserve the same type indirection for two literal event types.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
index 65281d8342..1fb572449e 100644
--- a/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 引入该规则时，持久化恢复曾将最后一个 `turn/end` 视为唯一的已提交边界。如今，持久化扫描器会保留每个合法且连续的事件，崩溃修复也只处理确实处于开放状态的轮次。因此，为标题更新保留合成轮次会夸大轮次计数、为从未运行模型的工作产生执行结果，还会让延迟到达的元数据写入占用下一个轮次编号。
 
-通用 seam 还重复了领域策略。它的标记映射说明哪些插件事件符合条件，而标题功能本就拥有取消、活跃性和陈旧结果处理规则。改用另一个通用或标题专属追加包装层，仍会为两个字面量事件类型保留同一层类型间接性。
+通用辅助函数还重复了领域策略。它的标记映射说明哪些插件事件符合条件，而标题功能本就拥有取消、活跃性和陈旧结果处理规则。改用另一个通用或标题专属追加包装层，仍会为两个字面量事件类型保留同一层类型间接性。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
index 77f0bb98ae..26e91f9351 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.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 .agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
-2026-07-31-one-route-to-add-a-workspace.md: 5d002265b5eb1178bb1dbc7bd17f8b364d9b9856
-2026-07-31-one-route-to-add-a-workspace.zh.md: 9e0940e2a59fac907f023d6433f0056b99c41a60
+2026-07-31-one-route-to-add-a-workspace.md: 93f10493848a65aee9c9e67502abfd73fe1e6d1f
+2026-07-31-one-route-to-add-a-workspace.zh.md: 83d91abb9ada3c1431a1b4ef126ea42a8406d326
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
index 5d002265b5..93f1049384 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
@@ -27,7 +27,7 @@ The direct-open path carries the busy rule the menu entry states: while a pick i
 
 ## Wire and CLI residue
 
-The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace-root` still feeds its target directory, but no product surface reaches either any more. The same is true of the client seam that carried the name to the wire: `WorkspaceCreateInput`, `WorkspacesService.create`'s `{ name }` arm, `intentName`'s name branch, and the manager's "name under workspaceRoot" contract. `apps/cli/README.md` and its Chinese counterpart still document `--workspace-root` as creating named Workspaces. The whole set is marked for deletion at the call site in `packages/host/apiproxy/src/api-proxy.ts` and left to a follow-up change: it is backend, client-seam, and CLI surface with its own reviewer and its own test fallout (the api-proxy workspace suite, the runtime workspace suite, the config catalog), and the release-blocking part of this decision is the UI.
+The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace-root` still feeds its target directory, but no product surface reaches either any more. The same is true of the client contract that carried the name to the wire: `WorkspaceCreateInput`, `WorkspacesService.create`'s `{ name }` arm, `intentName`'s name branch, and the manager's "name under workspaceRoot" contract. `apps/cli/README.md` and its Chinese counterpart still document `--workspace-root` as creating named Workspaces. The whole set is marked for deletion at the call site in `packages/host/apiproxy/src/api-proxy.ts` and left to a follow-up change: it is backend, client-contract, and CLI surface with its own reviewer and its own test fallout (the api-proxy workspace suite, the runtime workspace suite, the config catalog), and the release-blocking part of this decision is the UI.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
index 9e0940e2a5..83d91abb9a 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
@@ -27,7 +27,7 @@ Status: implemented
 
 ## Wire and CLI residue
 
-Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端一段同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一约定。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端 seam 与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
+Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端约定同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一约定。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端约定与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
 
 ## Testing
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
index b688f011de..73c3fb6e55 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
-2026-08-04-remove-tui-package.md: 1057243c70f6f2775a5d0c5f5eddcb72cbad699e
-2026-08-04-remove-tui-package.zh.md: 17a75921f3e8f227772133243bc0ea5b8ba927a7
+2026-08-04-remove-tui-package.md: f048a04db02b582d038ebf549999c0fda50e30d3
+2026-08-04-remove-tui-package.zh.md: be18cbd33cd4a2bb592de4e7986b2786da272d0f
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
index 1057243c70..f048a04db0 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.md
@@ -14,7 +14,7 @@ The package also made the repository's supported application inventory misleadin
 
 The `packages/ui/tui` package is deleted without a compatibility package or alias. Its source, package tests, terminal snapshots, dependency declarations, patched `pi-tui` artifact, workspace references, generated service catalog entry, and documentation are removed together. Generic host and agent-loop capabilities remain unchanged.
 
-The SDK run-interface union now contains only `acp` and `embed`. `create-sdk` defaults to ACP, generated templates contain no terminal startup, resume, session-environment, or model-argument branch, and the builtin `ask-user` feature is removed because neither remaining generated interface supplies a `UserInteractionProvider`. Host applications may still mount the provider-neutral `dsh-user-interaction`, `dsh-commands`, and presentation seams directly.
+The SDK run-interface union now contains only `acp` and `embed`. `create-sdk` defaults to ACP, generated templates contain no terminal startup, resume, session-environment, or model-argument branch, and the builtin `ask-user` feature is removed because neither remaining generated interface supplies a `UserInteractionProvider`. Host applications may still mount the provider-neutral `dsh-user-interaction`, `dsh-commands`, and presentation services directly.
 
 This decision supersedes the reusable-package retention in [the explicit-config `dsh` entrypoint decision](../../archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md) and the current applicability of the archived TUI implementation notes. Their historical records remain frozen, but they are not authority for the supported package or application inventory.
 
diff --git a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
index 17a75921f3..be18cbd33c 100644
--- a/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
+++ b/.agents/notes/implemented/simplification/2026-08-04-remove-tui-package.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 删除 `packages/ui/tui` 包，不提供兼容包或别名。其源码、包测试、终端快照、依赖声明、已打补丁的 `pi-tui` 产物、workspace 引用、生成的服务目录条目和文档会一并移除。通用宿主能力与 agent loop（智能体循环）能力保持不变。
 
-SDK 的运行接口联合类型现在只包含 `acp` 与 `embed`。`create-sdk` 默认使用 ACP，生成的模板不再包含终端启动、恢复、会话环境或模型参数分支；内置的 `ask-user` 功能也被移除，因为剩余两个生成接口都不提供 `UserInteractionProvider`。宿主应用仍可直接挂载提供方无关的 `dsh-user-interaction`、`dsh-commands` 和呈现 seam。
+SDK 的运行接口联合类型现在只包含 `acp` 与 `embed`。`create-sdk` 默认使用 ACP，生成的模板不再包含终端启动、恢复、会话环境或模型参数分支；内置的 `ask-user` 功能也被移除，因为剩余两个生成接口都不提供 `UserInteractionProvider`。宿主应用仍可直接挂载提供方无关的 `dsh-user-interaction`、`dsh-commands` 和呈现服务。
 
 本决策取代[显式配置 `dsh` 入口决策](../../archived/simplification/2026-08-03-explicit-config-dsh-entrypoint.md)中保留可复用包的决定，也使已归档 TUI 实现记录不再适用于当前状态。这些历史记录继续保持冻结，但不再作为受支持包或应用清单的依据。
 
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
index 36c58755cc..32c0bd83b9 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.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 .agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
-2026-06-22-fork-child-replay-seed-boundary.md: 27db3b768f2503121b0bc8912f9bc0fecb00a10d
-2026-06-22-fork-child-replay-seed-boundary.zh.md: 9e3f7e59394a5160f5ca5db1c9798b2e05f9d2dc
+2026-06-22-fork-child-replay-seed-boundary.md: bcbbd279771a2ebe7eee643958ecf09cbd7ca7be
+2026-06-22-fork-child-replay-seed-boundary.zh.md: ad086880d77a842be8c5dc7378018c92af95e698
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
index 27db3b768f..bcbbd27977 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md
@@ -39,7 +39,7 @@ This closes the routing correctness gap, and two recorded fork scenarios exercis
 
 ## Alternatives considered
 
-- **Derive the boundary heuristically in `llm-replay`** (the seeded prefix is contiguous parent events ending at the last `turn/end` before the child's first `user/message`). Rejected: a brittle heuristic in the test harness that re-derives a fact the producer already knows. Persisting the boundary at its source (the fork backend) is the "explicit > implicit at package seams" rule applied across the persistence boundary — the reader of a child fixture never has to reconstruct where the inheritance ended.
+- **Derive the boundary heuristically in `llm-replay`** (the seeded prefix is contiguous parent events ending at the last `turn/end` before the child's first `user/message`). Rejected: a brittle heuristic in the test harness that re-derives a fact the producer already knows. Persisting the boundary at its source (the fork backend) is the "explicit > implicit at package boundaries" rule applied across the persistence boundary — the reader of a child fixture never has to reconstruct where the inheritance ended.
 - **Pin the format version instead of bumping** (the `SESSION_FORMAT_VERSION = 0` "unstable" stance the event log uses). Rejected for the SQLite *table* layout: `SCHEMA_VERSION` is the monotonic bump-and-reject knob (a small enumerable set of revisions worth telling apart), distinct from the event-vocabulary `version`. Adding a column is precisely the breaking table change it versions, so it bumps.
 
 ## Consequences
diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
index 9e3f7e5939..ad086880d7 100644
--- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md
@@ -39,7 +39,7 @@ subagent 脚本由 [`deriveReplayScript`](../../../../packages/support/llm-repla
 
 ## 曾考虑的替代方案
 
-- **在 `llm-replay` 中启发式推导边界**（播种前缀是连续的父事件，止于子会话第一条 `user/message` 之前的最后一个 `turn/end`）。否决：在测试 harness 中用脆弱的启发式重新推导一个生产者已经知道的事实。在源头（fork 后端）持久化边界，是「在包 seam 处显式优于隐式」这条规则跨越持久化边界的应用——子会话 fixture（测试前置数据）的读取者永远不需要重建继承在哪里结束。
+- **在 `llm-replay` 中启发式推导边界**（播种前缀是连续的父事件，止于子会话第一条 `user/message` 之前的最后一个 `turn/end`）。否决：在测试 harness 中用脆弱的启发式重新推导一个生产者已经知道的事实。在源头（fork 后端）持久化边界，是「在包边界处显式优于隐式」这条规则跨越持久化边界的应用——子会话 fixture（测试前置数据）的读取者永远不需要重建继承在哪里结束。
 - **固定格式版本而不递增**（事件日志使用的 `SESSION_FORMAT_VERSION = 0`「不稳定」姿态）。对 SQLite *表*布局否决：`SCHEMA_VERSION` 是单调递增并拒绝旧版的旋钮（一组小的、值得区分的修订），与事件词汇表的 `version` 不同。新增列正是它所版本化的那种破坏性表变更，因此需要递增。
 
 ## 后果
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml
index 947e2da6eb..34edafb0d1 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.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 .agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
-2026-06-22-subagent-snapshot-replay.md: b8fefce5ff27b0cd3cfa2920b137e78cda0d696d
-2026-06-22-subagent-snapshot-replay.zh.md: e8bd8917a02e02f2ce89105eb64794876653574d
+2026-06-22-subagent-snapshot-replay.md: 45034c29f608eb5b58f44b80438b801b6224cb82
+2026-06-22-subagent-snapshot-replay.zh.md: 1b90c1bda854b7cd8cd9eae1e8c9f34328477f15
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
index b8fefce5ff..45034c29f6 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
@@ -53,6 +53,6 @@ Both replay keyless in the default gate.
 ## Consequences
 
 - The `TODO(subagent-snapshots)` deferral is resolved: nested-agent transcripts are now a first-class snapshot shape.
-- `GenerateOptions.sessionId` is a small, honest core-seam addition useful beyond replay (telemetry, request routing).
+- `GenerateOptions.sessionId` is a small, honest core API addition useful beyond replay (telemetry, request routing).
 - The `subagent` tool is bound to a single provider, so both children in `subagent-multi` are spawn (fresh). The keying routes by session, not by backend, so it is already correct for fork. The script *derivation* was not: a fork child's log begins with the seeded parent prefix (the parent's `assistant/chunk` events), so deriving its script from the whole log would replay the parent's responses as the child's. That correctness gap is closed by persisting a seed boundary — see [Persist the seed boundary so fork-child replay routes correctly](2026-06-22-fork-child-replay-seed-boundary.md) — and recorded fork + mixed spawn+fork scenarios now exercise both transports through one transcript (see [Record fork and mixed spawn+fork snapshot scenarios](../../archived/testing/2026-06-22-fork-snapshot-scenarios.md)).
 - Out-of-process (ACP) subagents are a different replay shape entirely (each child is its own PROCESS with its own replay), tracked as `TODO(acp-subagent-replay)` in the PR3 plan.
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
index e8bd8917a0..1b90c1bda8 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
@@ -53,6 +53,6 @@ Status: implemented
 ## 后果
 
 - `TODO(subagent-snapshots)` 延期项已解决：嵌套 agent 的 transcript 现在是快照层的一等形态。
-- `GenerateOptions.sessionId` 是一个小而诚实的 core-seam 新增，在回放之外同样有用（遥测、请求路由）。
+- `GenerateOptions.sessionId` 是一个小而诚实的 core API 新增，在回放之外同样有用（遥测、请求路由）。
 - `subagent` 工具绑定到单一提供方，因此 `subagent-multi` 中的两个子 agent 都是 spawn（全新创建）。键控按会话路由而非按后端路由，因此对 fork 同样正确。但脚本*派生*逻辑此前不正确：fork 子会话的日志以种子化的父前缀（父会话的 `assistant/chunk` 事件）开头，如果从完整日志派生脚本，就会把父 agent 的响应当作子 agent 的来回放。这一正确性缺口通过持久化种子边界来弥合——见[持久化 seed 边界以确保 fork 子会话回放正确路由](2026-06-22-fork-child-replay-seed-boundary.md)——录制的 fork 与混合 spawn+fork 场景现在通过一份 transcript 同时验证两种传输方式（见[记录 fork 与混合 spawn+fork 快照场景](../../archived/testing/2026-06-22-fork-snapshot-scenarios.md)）。
 - 进程外（ACP（Agent Client Protocol））subagent 是完全不同的回放形态（每个子 agent 是自己的进程、有自己的回放），作为 `TODO(acp-subagent-replay)` 记录在 PR3 计划中。
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
index 80395b6359..dcc666c622 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.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 .agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
-2026-07-22-cross-platform-test-fixtures.md: 6217aabfdbe8f14f869004c8dafb7e19f4b7443a
-2026-07-22-cross-platform-test-fixtures.zh.md: bb6649a19766967e0c2f70272433c1fa2e93f72a
+2026-07-22-cross-platform-test-fixtures.md: 9114481543d6cae1661cbed70868eddb2faa09fc
+2026-07-22-cross-platform-test-fixtures.zh.md: 710ec5887f02b5c3c71d69f16ab726323501ac92
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
index 6217aabfdb..9114481543 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.md
@@ -30,4 +30,4 @@ Tests for a genuinely POSIX-only primitive use a narrow Windows exclusion on tha
 
 ## Consequences
 
-Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer seam. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Windows teardown depends on the host `taskkill` command after graceful protocol shutdown has failed; a successful synchronous result keeps disposal bounded and makes descendant exit observable before cleanup returns, while a failed tree kill remains visible to the disposer.
+Portable fixtures are slightly more explicit because expected paths derive from shared native constants and transport failures enter through a narrow writer hook. Platform-only exclusions require a neighboring cross-platform assertion for the product behavior they support. Windows teardown depends on the host `taskkill` command after graceful protocol shutdown has failed; a successful synchronous result keeps disposal bounded and makes descendant exit observable before cleanup returns, while a failed tree kill remains visible to the disposer.
diff --git a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
index bb6649a197..710ec5887f 100644
--- a/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-22-cross-platform-test-fixtures.zh.md
@@ -30,4 +30,4 @@ Status: implemented
 
 ## 后果
 
-可移植 fixture 需要更显式地构造，因为预期路径要从共享的原生常量派生，传输故障则通过狭窄的写入器 seam 注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。协议级优雅关停失败后，Windows 上的资源清理依赖宿主的 `taskkill` 命令；命令同步执行成功时，可确保 dispose（资源释放）在有限时间内完成，并确保清理返回前即可观察到后代进程退出；若进程树终止失败，资源释放逻辑仍能观察到该失败。
+可移植 fixture 需要更显式地构造，因为预期路径要从共享的原生常量派生，传输故障则通过狭窄的写入器钩子注入。仅适用于特定平台的排除项必须配有相邻的跨平台断言，以继续覆盖相应的产品行为。协议级优雅关停失败后，Windows 上的资源清理依赖宿主的 `taskkill` 命令；命令同步执行成功时，可确保 dispose（资源释放）在有限时间内完成，并确保清理返回前即可观察到后代进程退出；若进程树终止失败，资源释放逻辑仍能观察到该失败。
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
index b41a72fb3c..dcd5119f92 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.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 .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
-2026-07-24-web-gui-browser-e2e-lane.md: 095ad9055c8462ecec67609ed9af55df2a2d7adb
-2026-07-24-web-gui-browser-e2e-lane.zh.md: d32837d0e320df0dd53ef49a50092503328d0d73
+2026-07-24-web-gui-browser-e2e-lane.md: aa289c9a70623904606e2d06b6492acb3a7d98a3
+2026-07-24-web-gui-browser-e2e-lane.zh.md: 9e26dcb53f0373ac967c627b95b895385784f925
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
index 095ad9055c..aa289c9a70 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
@@ -18,7 +18,7 @@ A plain shared-fixture module (the [testing-policy sanctioned shape](../../../..
 
 `launchWebScaffold()` boots the real web composition from the shipped `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml` through the vendored Loader's include mechanism — the same tree and mechanism `AppCLIEntry` drives for `dsh web`. Divergences ride include patches over that tree, the ACP `cordis.snapshot.yml` pattern expressed in-process: temp `persistenceRoot`; every host-level `skill-local` root (`dshHome`, `agentsHome`, and `bundledSkillDir`) pinned beneath the temp workspace with watching disabled, because ambient skill catalogs are model-visible input; `workspace-context` disabled (recorded fixtures must not embed this repo's AGENTS.md); `session-title-llm` disabled (its fire-and-forget title call would race the loop for the session's replay cursor); the webserver row pinned to port 0 with the built dist; and in keyless modes `llm-deepseek` disabled. A patch id that stops matching a row fails the boot sweep loudly instead of drifting. The boot runs `chdir`'d to the temp workspace so the api-gateway's `process.cwd()` session default, tool cwds, and fixtures agree; the `dsh web` bin's own glue (argv, profile json, AppCLIEntry) stays held by the keyless CLI smokes in `smoke-real.e2e.ts`. Setup rollback and ordinary close both dispose the Cordis tree before removing the two owned temp roots, attempt every cleanup independently, and report cleanup failures without masking the setup failure.
 
-Keyless model displacement is the disabled adapter row plus `installLlmReplay` filling the open seam on the settled root ctx in providers-catalog mode — never catch-all: with the adapter row disabled no adapter exists, so catch-all would leave `resolveModelInfo` unroutable and `compact-basic`'s post-step pressure check would warn every step instead of being provably inert (the published 128k `contextWindow` keeps it inert for small fixtures). The direct install rather than an inserted replay plugin row is deliberate: it returns the `ReplayHandle` the teardown consumption check needs. A scenario with no fixture leaves the seam empty, so a stray stream fails loud with NO_ADAPTER.
+Keyless model displacement is the disabled adapter row plus `installLlmReplay` filling the empty adapter registry on the settled root ctx in providers-catalog mode — never catch-all: with the adapter row disabled no adapter exists, so catch-all would leave `resolveModelInfo` unroutable and `compact-basic`'s post-step pressure check would warn every step instead of being provably inert (the published 128k `contextWindow` keeps it inert for small fixtures). The direct install rather than an inserted replay plugin row is deliberate: it returns the `ReplayHandle` the teardown consumption check needs. A scenario with no fixture leaves the registry empty, so a stray stream fails loud with NO_ADAPTER.
 
 `seedSession()` seeds cold sessions through the real persistence API — a throwaway `Context` mounting `SessionStore` + `SessionPersistenceJsonl` against the host's root, `create()` + `append()`, one `utimes` backdate for deterministic sidebar order (the `semantic-checkpoint.snapshot.ts` precedent) — never raw file writes, so the seeder knows nothing of bucket hashing, filename encoding, or compression, and the host's zstd default needs no boot knob. Seeds are validated at seed time (parseable, ending in `turn/end` — an open final turn would be mutated by resume's crash repair).
 
@@ -52,7 +52,7 @@ High-cardinality performance diagnostics use the separate opt-in `apps/web/tests
 
 ## Prior art
 
-Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot + AI SDK, lobe-chat, open-webui, OpenHands, Chainlit, continue, cline, langfuse, gradio/streamlit; Playwright HAR/route, MSW, Polly/nock, WireMock, aimock). The dominant proven architecture for apps that own their backend is an in-process fake/replay model behind the real backend seam with everything downstream real (LibreChat's `LIBRECHAT_TEST_RUN_HOOK` fake model; ai-chatbot's `MockLanguageModelV3` + `simulateReadableStream`; continue's scripted mock provider classes) — which is what `dsh-llm-replay` already is. Browser-level SSE interception cannot exercise incremental rendering (`route.fulfill` delivers the whole body at once; playwright#33564) and leaves the server SSE stack untested, so projects use it only for edge cases. Chunk pacing as a fixture parameter recurs everywhere (LibreChat 10ms default with slow profiles; ai-chatbot 500ms); real models in CI rot (open-webui's suite grew 120-second timeouts, was disabled, then deleted); sessions are seeded at the persistence layer with controlled timestamps (LibreChat inserts backdated Mongo documents; langfuse seeds its DB). No surveyed project replays a recorded agent-event log through the real backend for UI tests — the closest are provider-level recorded fixtures (aimock) and frontend-level socket history emission (OpenHands MSW) — so the session-log-as-fixture design goes one step beyond prior art along the axis this repo's model-visible ⟺ logged invariant makes natural.
+Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot + AI SDK, lobe-chat, open-webui, OpenHands, Chainlit, continue, cline, langfuse, gradio/streamlit; Playwright HAR/route, MSW, Polly/nock, WireMock, aimock). The dominant proven architecture for apps that own their backend is an in-process fake/replay model behind the real backend contract with everything downstream real (LibreChat's `LIBRECHAT_TEST_RUN_HOOK` fake model; ai-chatbot's `MockLanguageModelV3` + `simulateReadableStream`; continue's scripted mock provider classes) — which is what `dsh-llm-replay` already is. Browser-level SSE interception cannot exercise incremental rendering (`route.fulfill` delivers the whole body at once; playwright#33564) and leaves the server SSE stack untested, so projects use it only for edge cases. Chunk pacing as a fixture parameter recurs everywhere (LibreChat 10ms default with slow profiles; ai-chatbot 500ms); real models in CI rot (open-webui's suite grew 120-second timeouts, was disabled, then deleted); sessions are seeded at the persistence layer with controlled timestamps (LibreChat inserts backdated Mongo documents; langfuse seeds its DB). No surveyed project replays a recorded agent-event log through the real backend for UI tests — the closest are provider-level recorded fixtures (aimock) and frontend-level socket history emission (OpenHands MSW) — so the session-log-as-fixture design goes one step beyond prior art along the axis this repo's model-visible ⟺ logged invariant makes natural.
 
 ## Alternatives considered
 
@@ -60,7 +60,7 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot
 
 **Mock HTTP provider at `DEEPSEEK_BASE_URL`.** Rejected as the lane's mechanism (kept for the one existing workspace-probe smoke): fixtures become hand-authored OpenAI SSE byte scripts, a second fixture format that drifts from the session-log format the rest of the repo records and replays; the adapter's real HTTP path is with-key e2e's job.
 
-**Growing the `?fixture` client.** Rejected: tier separation — `FixtureApiClient` exists to test the client shell without a server; everything below the client API seam stays untested by construction.
+**Growing the `?fixture` client.** Rejected: tier separation — `FixtureApiClient` exists to test the client shell without a server; everything below the client API boundary stays untested by construction.
 
 **Placeholder `DEEPSEEK_API_KEY` + replay interception instead of disabling the adapter row.** Rejected despite zero composition change and two in-tree precedents: it satisfies `llm-deepseek`'s fail-loud key check with a lie and leaves a dead adapter mounted-but-intercepted; the disabled row (the ACP overlay's move) is honest keylessness and fails loud at the earliest resolvable point.
 
@@ -70,7 +70,7 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot
 
 **Spawning the `dsh web` bin with a `DSH_SNAPSHOT` replay branch.** Rejected: it needs a test-only replay branch plus environment plumbing in the shipped CLI. The in-process scaffold already loads the same `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml`; only argv, profile JSON, and `AppCLIEntry` glue remain outside it, and the keyless CLI smokes cover those paths.
 
-**Changing the wire protocol for testability.** Rejected: the contract already has a first-class keyless isomorphic seam (`InProcessApiClient(toFetchHandler(api))`), the per-event unbatched SSE is exactly what makes replay observable in a browser, and testing a wire we no longer ship would invert the tier's purpose.
+**Changing the wire protocol for testability.** Rejected: the contract already has a first-class keyless in-process path (`InProcessApiClient(toFetchHandler(api))`), the per-event unbatched SSE is exactly what makes replay observable in a browser, and testing a wire we no longer ship would invert the tier's purpose.
 
 **Real-model browser tests as the keyless lane.** Rejected: nondeterministic by construction; the surveyed cautionary case (open-webui) grew unbounded timeouts and was deleted. The with-key W5 smoke stays as the live-model complement.
 
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
index d32837d0e3..9e26dcb53f 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
@@ -18,7 +18,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 `launchWebScaffold()` 通过 vendored Loader 的 include 机制，从交付的 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 启动真实 web 组合——与 `AppCLIEntry` 为 `dsh web` 驱动的是同一棵树、同一套机制。差异全部经 include patch 覆盖在这棵树上，即 ACP `cordis.snapshot.yml` 模式的进程内表达：临时 `persistenceRoot`；每个主机级 `skill-local` 根目录（`dshHome`、`agentsHome` 和 `bundledSkillDir`）都钉在临时工作区下并禁用监听，因为环境 skill（技能）目录是模型可见输入；禁用 `workspace-context`（录制的 fixture 不得嵌入本仓库的 AGENTS.md）；禁用 `session-title-llm`（其发后不管的标题调用会与循环争抢会话的回放游标）；webserver 行钉到端口 0 加已构建 dist；无密钥模式下禁用 `llm-deepseek`。patch 的 id 一旦不再匹配任何行，boot 扫描会大声失败而不是漂移。boot 在临时工作区 `chdir` 下运行，使 api-gateway 的 `process.cwd()` 会话默认值、工具 cwd 与 fixture 一致；`dsh web` bin 自身的胶水（argv、profile json、AppCLIEntry）仍由 `smoke-real.e2e.ts` 中的无密钥 CLI 冒烟把守。初始化回滚和正常关闭都会先对 Cordis 树执行 dispose（资源释放），再删除 scaffold 持有的两个临时根目录；每项清理都会独立尝试，并会报告清理失败而不掩盖初始化失败。
 
-无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充开放的 seam——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步后压力检查将步步告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让 seam 保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。
+无密钥的模型替换 = 禁用适配器行的 patch 加 `installLlmReplay` 在停稳的根 ctx 上以提供方目录（providers-catalog）模式填充空的适配器注册表——绝不用 catch-all：适配器行被禁用后不存在任何适配器，catch-all 会让 `resolveModelInfo` 无路由可走，`compact-basic` 的步后压力检查将步步告警，而不是被可证明地闲置（发布的 128k `contextWindow` 使该路径对小 fixture 保持闲置）。选择直接安装而非插入回放插件行是刻意的：直接安装返回收尾消费检查所需的 `ReplayHandle`。没有 fixture 的场景让注册表保持空置，任何离群的流式调用都会以 NO_ADAPTER 大声失败。
 
 `seedSession()` 通过真实持久化 API 播种冷会话——一次性 `Context` 挂载 `SessionStore` + `SessionPersistenceJsonl` 指向 host 的根目录，`create()` + `append()`，一次 `utimes` 回拨保证侧栏顺序确定（`semantic-checkpoint.snapshot.ts` 先例）——绝不裸写文件，因此播种器对桶哈希、文件名编码、压缩一无所知，host 的 zstd 默认值也无需任何启动开关。种子在播种时即校验（可解析、以 `turn/end` 结尾——未闭合的最终轮次会被恢复（resume）的崩溃修复改写）。
 
@@ -52,7 +52,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 ## 业界先例
 
-调研了 AI 聊天/agent web UI 与 mock 层（LibreChat、vercel/ai-chatbot + AI SDK、lobe-chat、open-webui、OpenHands、Chainlit、continue、cline、langfuse、gradio/streamlit；Playwright HAR/route、MSW、Polly/nock、WireMock、aimock）。自有后端的应用的主流成熟架构是：真实后端 seam 后放一个进程内伪造/回放模型，下游全部真实（LibreChat 的 `LIBRECHAT_TEST_RUN_HOOK` 伪模型；ai-chatbot 的 `MockLanguageModelV3` + `simulateReadableStream`；continue 的脚本化 mock 提供方类）——这正是 `dsh-llm-replay` 已然所是。浏览器层 SSE 拦截无法检验增量渲染（`route.fulfill` 一次性交付整个响应体；playwright#33564），且服务端 SSE 栈完全失测，因此各项目只把它用于边缘用例。分片节奏作为 fixture 参数反复出现（LibreChat 默认 10ms 附慢速档；ai-chatbot 500ms）；CI 里的真实模型会腐烂（open-webui 的套件长出 120 秒超时，先被禁用后被删除）；会话在持久化层以受控时间戳播种（LibreChat 直插回拨时间的 Mongo 文档；langfuse 播种其数据库）。没有任何被调研项目为 UI 测试把录制的 agent 事件日志经真实后端回放——最接近的是提供方层录制 fixture（aimock）与前端层 socket 历史发射（OpenHands MSW）——因此会话日志即 fixture 的设计沿着本仓库「模型可见 ⟺ 已记录」不变式所指的方向比业界先例多走了一步。
+调研了 AI 聊天/agent web UI 与 mock 层（LibreChat、vercel/ai-chatbot + AI SDK、lobe-chat、open-webui、OpenHands、Chainlit、continue、cline、langfuse、gradio/streamlit；Playwright HAR/route、MSW、Polly/nock、WireMock、aimock）。自有后端的应用的主流成熟架构是：真实后端约定后放一个进程内伪造/回放模型，下游全部真实（LibreChat 的 `LIBRECHAT_TEST_RUN_HOOK` 伪模型；ai-chatbot 的 `MockLanguageModelV3` + `simulateReadableStream`；continue 的脚本化 mock 提供方类）——这正是 `dsh-llm-replay` 已然所是。浏览器层 SSE 拦截无法检验增量渲染（`route.fulfill` 一次性交付整个响应体；playwright#33564），且服务端 SSE 栈完全失测，因此各项目只把它用于边缘用例。分片节奏作为 fixture 参数反复出现（LibreChat 默认 10ms 附慢速档；ai-chatbot 500ms）；CI 里的真实模型会腐烂（open-webui 的套件长出 120 秒超时，先被禁用后被删除）；会话在持久化层以受控时间戳播种（LibreChat 直插回拨时间的 Mongo 文档；langfuse 播种其数据库）。没有任何被调研项目为 UI 测试把录制的 agent 事件日志经真实后端回放——最接近的是提供方层录制 fixture（aimock）与前端层 socket 历史发射（OpenHands MSW）——因此会话日志即 fixture 的设计沿着本仓库「模型可见 ⟺ 已记录」不变式所指的方向比业界先例多走了一步。
 
 ## 曾考虑的替代方案
 
@@ -60,7 +60,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **`DEEPSEEK_BASE_URL` 处的 mock HTTP 提供方。** 作为本车道机制已否决（仅保留给既有的工作区探针冒烟）：fixture 会变成手写的 OpenAI SSE 字节脚本，一种与仓库其余部分录制回放的会话日志格式渐行渐远的第二 fixture 格式；适配器的真实 HTTP 路径归带密钥 e2e 管。
 
-**扩展 `?fixture` 客户端。** 已否决：分层纪律——`FixtureApiClient` 的存在意义就是脱离服务器测试客户端 shell；client API seam 以下按构造即失测。
+**扩展 `?fixture` 客户端。** 已否决：分层纪律——`FixtureApiClient` 的存在意义就是脱离服务器测试客户端 shell；client API 边界以下按构造即失测。
 
 **用占位 `DEEPSEEK_API_KEY` + 回放拦截替代禁用适配器行。** 尽管零组合改动且树内有两处先例仍被否决：它用谎言满足 `llm-deepseek` 的快速失败密钥检查，还留下一个挂载却被拦截的死适配器；禁用行（ACP overlay 的同款做法）是诚实的无密钥，并在最早可解析点快速失败。
 
@@ -70,7 +70,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **以 `DSH_SNAPSHOT` 回放分支拉起 `dsh web` bin。** 已否决：它需要在交付的 CLI 中增加测试专用回放分支和环境变量管道。进程内 scaffold 已加载同一份 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml`；只剩 argv、profile JSON 和 `AppCLIEntry` 胶水不在其覆盖范围内，而这些路径已由无密钥 CLI 冒烟覆盖。
 
-**为可测试性改 wire 协议。** 已否决：约定已有第一等的无密钥同构 seam（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
+**为可测试性改 wire 协议。** 已否决：约定已有第一等的无密钥进程内路径（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
 
 **以真实模型浏览器测试充当无密钥车道。** 已否决：按构造即不确定；被调研的前车之鉴（open-webui）长出无界超时后被删除。带密钥的 W5 冒烟仍是真实模型侧的补充。
 
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
index 318262eecb..29932b1d06 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.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 .agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
-2026-06-16-typed-event-schemas.md: 97a7d0c3787eb5556696e25a6c8b1bb75642aba9
-2026-06-16-typed-event-schemas.zh.md: 6d665151a9c5879b3810ae93af8cc6bf5a21727c
+2026-06-16-typed-event-schemas.md: d919db18f347d0633155f92bfecc43b8bf846659
+2026-06-16-typed-event-schemas.zh.md: 369a70846265035d92bf51fcd516793b648e2f0f
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
index 97a7d0c378..d919db18f3 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
@@ -42,7 +42,7 @@ This is a repository-wide vocabulary redesign, not a persistence implementation
 Keep the compile-time pattern. Persistence stays opaque-JSON + serializability guard. Plugins extend via declaration merging; correctness of event *shape* is the producer's responsibility and is enforced by TypeScript at compile time. Package-owned invariant companions check selected cross-record relationships when enabled but do not provide general runtime shape schemas.
 
 - **Pros**: zero churn; plugin extension is a one-line `interface` augmentation with full type inference and no runtime registration ceremony; no new runtime dependency; the `defineTool` DSL and `assertNever` exhaustiveness keep working.
-- **Cons**: no runtime structural validation at the persistence boundary or at plugin seams; a malformed-but-JSON datum is caught late.
+- **Cons**: no runtime structural validation at the persistence boundary or at plugin boundaries; a malformed-but-JSON datum is caught late.
 
 ### B. Header/closed-shape validation only (schemastery), events stay opaque
 Tighten only the genuinely-closed shapes that already have hand-rolled type guards — e.g. the JSONL `HeaderLine` guard (`isHeaderLine`) — using **schemastery** (the repo's existing schema library, already used for every plugin `static Config`). Leave the merge-extensible event union as-is.
@@ -53,7 +53,7 @@ Tighten only the genuinely-closed shapes that already have hand-rolled type guar
 ### C. Runtime schema registry for the whole vocabulary (Zod or schemastery)
 Replace the merge-extensible maps with a runtime registry the producers contribute to and the persistence/consumer paths validate against.
 
-- **Pros**: real runtime validation at the durable boundary and at plugin seams; one source of truth; enables generic tooling (auto-generated docs, fuzzing, wire-format checks).
+- **Pros**: real runtime validation at the durable boundary and at plugin boundaries; one source of truth; enables generic tooling (auto-generated docs, fuzzing, wire-format checks).
 - **Cons**: the full blast radius above; **Zod is not currently a direct dependency** (only a transitive dep of `@earendil-works/pi-ai`) and the repo's chosen schema lib is **schemastery** — adopting Zod broadly is itself a dependency decision; declaration-merge ergonomics (one-line plugin extension, full inference) are replaced by runtime registration + manual type wiring; the `assertNever` exhaustiveness guarantee weakens (runtime variants aren't statically exhaustive).
 
 ## Proposal
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
index 6d665151a9..369a708462 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
@@ -42,7 +42,7 @@ harness 将其核心词汇——内容块、消息来源、结束原因、轮次
 保留编译期模式。持久化继续使用不透明 JSON + 可序列化性守卫。插件通过声明合并扩展；事件*形状*的正确性由生产者负责，并由 TypeScript 在编译期保证。启用包自有的不变式 companion 后，它们会检查选定的跨记录关系，但不提供通用运行时形状 schema。
 
 - **优点**：零变动；插件扩展只需一行 `interface` 增补，享有完整类型推断，无需运行时注册仪式；无新运行时依赖；`defineTool` DSL 与 `assertNever` 穷举继续工作。
-- **缺点**：持久化边界和插件 seam 处无运行时结构校验；格式错误但仍为合法 JSON 的数据被延迟捕获。
+- **缺点**：持久化边界和插件边界处无运行时结构校验；格式错误但仍为合法 JSON 的数据被延迟捕获。
 
 ### B. 仅对头部/封闭形状做校验（schemastery），事件仍为不透明
 仅对那些已有手写类型守卫的真正封闭形状加以收紧——例如 JSONL 的 `HeaderLine` 守卫（`isHeaderLine`）——使用 **schemastery**（仓库现有的 schema 库，已用于每个插件的 `static Config`）。merge-extensible 事件联合类型保持不变。
@@ -53,7 +53,7 @@ harness 将其核心词汇——内容块、消息来源、结束原因、轮次
 ### C. 为整个词汇建立运行时 schema 注册表（Zod 或 schemastery）
 用运行时注册表替换 merge-extensible map，生产者向其贡献 schema，持久化/消费路径据此校验。
 
-- **优点**：持久化边界和插件 seam 处获得真正的运行时校验；单一真源；可支撑通用工具（自动生成文档、模糊测试、协议格式（wire format）检查）。
+- **优点**：持久化边界和插件边界处获得真正的运行时校验；单一真源；可支撑通用工具（自动生成文档、模糊测试、协议格式（wire format）检查）。
 - **缺点**：上述全部影响范围；**Zod 目前不是直接依赖**（仅作为 `@earendil-works/pi-ai` 的传递依赖），仓库选定的 schema 库是 **schemastery**——广泛引入 Zod 本身就是一个依赖决策；声明合并的易用性（一行插件扩展、完整推断）被运行时注册 + 手动类型接线取代；`assertNever` 穷举保证弱化（运行时变体在静态层面不可穷举）。
 
 ## 提案
diff --git a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml
index 25b4c76ff7..c383ac1f48 100644
--- a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.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 .agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md
-2026-07-19-required-cancellation-through-tool-capability-seams.md: c2cfb09f27222136965058695e9b6b706ac688a9
-2026-07-19-required-cancellation-through-tool-capability-seams.zh.md: 0544a17629c4fb130bed9ec6c7cae1a15d2211a8
+2026-07-19-required-cancellation-through-tool-capability-seams.md: 1909b8451b6c70bde7c67f0cc0c1c3f4db443f7f
+2026-07-19-required-cancellation-through-tool-capability-seams.zh.md: 7a9c78c71afe4d51f3d0f46f2cb59fc7cb5bf133
diff --git a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md
index c2cfb09f27..1909b8451b 100644
--- a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md
+++ b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.md
@@ -18,7 +18,7 @@ Require an `AbortSignal` on every asynchronous same-process capability operation
 
 Each direct caller supplies a signal it owns or propagates from its own required operation context. Implementations may derive a child deadline or cancellation scope, but the derived signal remains linked to the upstream signal for the delegated lifetime. Capability implementations do not synthesize never-abort signals, use ambient async-local cancellation, or validate `AbortSignal` at runtime solely to repeat the typed same-process contract.
 
-The migration begins with an inventory from every first-party `ToolDefinition.execute()` through the capability calls it awaits. It then changes each coherent interface/implementation/consumer seam together, including tests and generated API documentation. Separate PRs may migrate filesystem, bash/task, web/provider, workflow/subagent, code-runtime, and similar families so each change remains reviewable, but no migrated interface keeps an optional compatibility overload under the repository's pre-release policy.
+The migration begins with an inventory from every first-party `ToolDefinition.execute()` through the capability calls it awaits. It then changes each coherent Service Definition / Service provider / Consumer seam together, including tests and generated API documentation. Separate PRs may migrate filesystem, bash/task, web/provider, workflow/subagent, code-runtime, and similar families so each change remains reviewable, but no migrated interface keeps an optional compatibility overload under the repository's pre-release policy.
 
 ### Scope boundary
 
diff --git a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
index 0544a17629..7a9c78c71a 100644
--- a/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-19-required-cancellation-through-tool-capability-seams.zh.md
@@ -18,7 +18,7 @@ Status: proposed
 
 每个直接调用方提供自己持有的信号，或从自身必填的操作上下文继续传递信号。实现可以派生子截止时间或取消作用域，但派生信号在委托期间仍须与上游信号关联。能力实现不得生成永不中止信号、使用环境式异步本地取消，也不得仅为重复类型化同进程约定而在运行时校验 `AbortSignal`。
 
-迁移首先从每个第一方 `ToolDefinition.execute()` 出发，清点其等待的能力调用；随后按内聚的接口／实现／消费方 seam，将测试与生成的 API 文档一并修改。文件系统、Bash 与任务、Web 与提供方、工作流与 subagent、代码运行时等能力族可以通过独立 PR（Pull Request）迁移，以保持每项变更可审查；但根据仓库的预发布原则，已经迁移的接口不得保留可选兼容重载。
+迁移首先从每个第一方 `ToolDefinition.execute()` 出发，清点其等待的能力调用；随后按内聚的 Service Definition／Service provider／Consumer seam，将测试与生成的 API 文档一并修改。文件系统、Bash 与任务、Web 与提供方、工作流与 subagent、代码运行时等能力族可以通过独立 PR（Pull Request）迁移，以保持每项变更可审查；但根据仓库的预发布原则，已经迁移的接口不得保留可选兼容重载。
 
 ### 范围边界
 
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
index 1bf84824b2..0ba77577f4 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.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 .agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
-2026-07-25-client-settings-locale-theme.md: fdcdcff92fa324803d5f2343f3fc3d9dcca069c7
-2026-07-25-client-settings-locale-theme.zh.md: efcbbff3727a7a5ce14ba7273c7d0e826a3e5cbd
+2026-07-25-client-settings-locale-theme.md: 961a7d96705095486ed7e4b2044f8f0f4a3cd79c
+2026-07-25-client-settings-locale-theme.zh.md: 9c7be340f508f7bb12d1448625232258da412e10
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
index fdcdcff92f..961a7d9670 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.md
@@ -55,7 +55,7 @@ root
             └─ models (order 10)         ui-models 注册
 ```
 
-Section and item contributions use `ctx.slots.inject()` and do not depend on the client manifest's apply order; localized labels ride the label thunk from the [full-rollout note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md). The SlotMap types split homes: trigger/header/close/section have their canonical home in the ui-settings contract (the consumers, general and models, both depend on the shell — no cycle); `settings.general.item`'s canonical home is the locale package — it is the lowest common dependency of all item registrants (a settings row always carries copy), while the declarer general's contract is unreachable from locale/ui-theme (it would form a cycle); ui-theme consumes it through a re-export seam.
+Section and item contributions use `ctx.slots.inject()` and do not depend on the client manifest's apply order; localized labels ride the label thunk from the [full-rollout note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md). The SlotMap types split homes: trigger/header/close/section have their canonical home in the ui-settings contract (the consumers, general and models, both depend on the shell — no cycle); `settings.general.item`'s canonical home is the locale package — it is the lowest common dependency of all item registrants (a settings row always carries copy), while the declarer general's contract is unreachable from locale/ui-theme (it would form a cycle); ui-theme consumes it through a re-export outlet.
 
 ### Slot declarations are first-class injectable waits
 
diff --git a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
index efcbbff372..9c7be340f5 100644
--- a/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-25-client-settings-locale-theme.zh.md
@@ -55,11 +55,11 @@ root
             └─ models (order 10)         ui-models 注册
 ```
 
-section/item contribution 使用 `ctx.slots.inject()`，不依赖 client manifest（元数据清单）的 apply 顺序；本地化 label 走 [全量接入 Note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md) 的 label thunk。SlotMap 类型分家：trigger/header/close/section 正家在 ui-settings 约定（消费方 general/models 均依赖壳，无环）；`settings.general.item` 正家在 locale 包——它是全部 item 注册方的最低公共依赖（设置行必带文案），而声明方 general 的约定对 locale/ui-theme 不可达（会成环）；ui-theme 经 re-export seam 消费。
+section/item contribution 使用 `ctx.slots.inject()`，不依赖 client manifest 的 apply 顺序；本地化 label 走 [全量接入 Note](../../implemented/architecture/2026-07-30-client-locale-full-rollout.md) 的 label thunk。SlotMap 类型分家：trigger/header/close/section 正家在 ui-settings contract（消费者 general/models 均依赖壳，无环）；`settings.general.item` 正家在 locale 包——它是全部 item 注册方的最低公共依赖（设置行必带文案），而声明方 general 的 contract 对 locale/ui-theme 不可达（会成环）；ui-theme 经 re-export 出口消费。
 
 ### slot 声明是一等可注入等待对象
 
-`SlotsService.inject()` 直接等待有类型约束的 ledger key；它不会将声明桥接为合成的 `slot:<name>` Cordis 服务。回调会跟随声明撤销与重新声明，而其控制器仍归贡献方插件 fiber 所有；直接向未声明 slot 注册仍会显式报错。这移除了陈旧 disposer 的在位判定机制和容易因拼写错误出错的平行服务命名空间。完整的生命周期与失败约定见 [slot 声明注入决策](../../implemented/architecture/2026-08-05-slot-declaration-injection.md)。
+`SlotsService.inject()` 直接等待有类型约束的 ledger key；它不会将声明桥接为合成的 `slot:<name>` Cordis 服务。回调会跟随声明折叠与重新声明，而其控制器仍归贡献方插件 fiber 所有；直接向未声明 slot 注册仍会大声失败。这删除了陈旧 disposer 判在位机器和容易因拼写错误出错的平行服务命名空间。完整的生命周期与失败约定见 [slot 声明注入决策](../../implemented/architecture/2026-08-05-slot-declaration-injection.md)。
 
 ### 服务约定
 
@@ -127,4 +127,4 @@ Locale 内置中文和 English；`setLocale`/`setTheme` 是唯一写入口，未
 
 ## 风险
 
-slot 声明与 contribution 的 apply 顺序不固定，所有 section/item 注册方必须使用 `ctx.slots.inject()`，而不能以服务或本地 disposer 作为在位信号。服务事件可能早于行首次渲染，功能行 store 的 init 与 inject attach 都必须从 getter 对齐当前 snapshot。`settings.general.item` 的重复合并副本（locale、ui-theme）与 ui-settings 正家必须逐字一致，漂移即三处一起改。Layout 卸载时必须清理自己设置的全局属性，ThemeService dispose 时必须移除 matchMedia 监听，避免 HMR（热模块替换）后残留。
+slot 声明与 contribution 的 apply 顺序不固定，所有 section/item 注册方必须使用 `ctx.slots.inject()`，而不能以服务或本地 disposer 作为在位信号。service event 可能早于行首次渲染，功能行 store 的 init 与 inject attach 都必须从 getter 对齐当前 snapshot。`settings.general.item` 的重复合并副本（locale、ui-theme）与 ui-settings 正家必须逐字一致，漂移即三处一起改。Layout 卸载时必须清理自己设置的全局属性，ThemeService dispose 时必须移除 matchMedia 监听，避免 HMR 后残留。
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index ce7e7f5f4f..c5910fb083 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.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 .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
-2026-07-27-session-projection-and-command-log.md: 2fc463ab6e65998c19b0a0fce186c7eb17dacbf6
-2026-07-27-session-projection-and-command-log.zh.md: ef4de5ea924e28c28896558206566639295c4c8e
+2026-07-27-session-projection-and-command-log.md: 6c2c8137453d04ba6b631fe7f80a788a639b096b
+2026-07-27-session-projection-and-command-log.zh.md: f3370ea2631e9c9904c6fc996c2c8aff698c3830
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
index 2fc463ab6e..6c2c813745 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
@@ -24,7 +24,7 @@ A state-carrying log event MUST carry the complete post-change state, never a ba
 
 ### Host projection registry (`dsh-session-projection`, new package)
 
-A light interface package: the merge-extensible type map, the registry service, zod at the boundary. Capability-seam three-way split: domain host plugins contribute, carriers consume, neither knows the other.
+A light Service Definition package: the merge-extensible type map, the registry service, zod at the boundary. Capability-seam roles: domain host plugins provide projection units, carriers consume them, and neither knows the other.
 
 What a domain registers is a **state-driven computation unit** — three pure functions plus declarations — never an opaque getter. The framework owns driving it (subscription, watermark, caching, and later checkpointing); the domain owns only the mathematics. Projections serve every business domain (session title, plan, goal, permission, todos); commands are merely one trigger path and hold no special position in this contract.
 
@@ -147,7 +147,7 @@ Infrastructure first; the three in-flight PRs are left untouched and re-target a
 
 **A live-only overlay hook (`live?(agent, base)`) for plan's pending intent** — rejected: it existed solely because the user's plan *selection* was not in the log. Routing the selection through the standard command channel puts `command/run` on the account, pending becomes a pure replay quantity, and the projection contract stays exactly three pure functions.
 
-**Naming the seam `registerFold`** — superseded by the unit contract: the registered object now genuinely is a fold, but `fold*` in this repo names pure `(events) => state` helper functions while this seam registers a keyed, schema'd, versioned unit. Projection remains the event-sourcing term for the read-model role, and both #587's note title and #497's comments already use it.
+**Naming the registration API `registerFold`** — superseded by the unit contract: the registered object now genuinely is a fold, but `fold*` in this repo names pure `(events) => state` helper functions while this registry accepts a keyed, schema'd, versioned unit. Projection remains the event-sourcing term for the read-model role, and both #587's note title and #497's comments already use it.
 
 **Client-side folding (per-domain projection cells with a `fromEvent`)** — rejected after being the second draft: once plan's unit folds two event types, a client cell must duplicate the host's transition logic in the browser — the same fold written twice, evolving separately. Pushing finished values (the title-frame precedent, generalized) keeps one computation site and reduces the client to a generic seq-guarded value store; domains write zero client code.
 
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index ef4de5ea92..f3370ea263 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -24,7 +24,7 @@ Status: proposed
 
 ### host 侧投影注册表（`dsh-session-projection`，新包）
 
-一个轻量的接口包：merge-extensible 类型表、注册表服务、边界上的 zod 校验。能力 seam 三方拆分：领域 host 插件负责贡献，载体负责消费，两侧互不相识。
+一个轻量的 Service Definition 包：merge-extensible 类型表、注册表服务、边界上的 zod 校验。能力 seam 的角色如下：领域 host 插件提供投影单元，载体消费这些单元，两侧互不相识。
 
 领域注册的是一个**状态驱动计算单元（state-driven computation unit）**——三个纯函数外加若干声明——绝不是一个不透明的 getter。驱动它是框架的职责（订阅、水位线（watermark）、缓存，以及后续的检查点机制），领域只负责数学本身。投影服务于所有业务领域（会话标题、plan、goal、权限、todos）；命令只是其中一条触发路径，在本约定中没有任何特殊地位。
 
@@ -58,7 +58,7 @@ declare module 'cordis' {
 
 ### 已交付的消费方：subagent 身份单元
 
-注册表的两处既有读法已经服务于本 RFC 协议计划之外的一个已交付消费方：[subagent 列表经投影单元读取身份](../../implemented/architecture/2026-08-06-subagent-list-identity-projection.md)注册了 `subagent` 单元——从 `subagent/descriptor` 按 last-wins 折叠出的持久的 mode/label 身份——`SubagentService.listChildren` 对 live child 经 `snapshot()` 读取（水位线缓存，零日志读），对 cold child 则对一次持久化读取所得的事件调用 `restore({}, events, 0)` 读取。注册表约定不变：没有失败通道、没有新读法——单元永不抛错，值缺席本身就是信号，缺席如何呈现是该消费方自己的决定。
+注册表的两处既有读法已经服务于本 RFC 协议计划之外的一个已交付消费方：[subagent 列表经投影单元读取身份](../../implemented/architecture/2026-08-06-subagent-list-identity-projection.md)注册了 `subagent` 单元——从 `subagent/descriptor` 按 last-wins 折叠出的持久化 mode/label 身份——`SubagentService.listChildren` 对 live child 经 `snapshot()` 读取（水位缓存，零日志读），对 cold child 则用一次持久化整读的结果调用 `restore({}, events, 0)` 读取。注册表约定不变：没有失败通道、没有新读法——单元永不抛错，值缺席本身就是信号，缺席如何呈现是该消费方自己的决定。
 
 ### 协议层：历史尾页上的 projections 块
 
@@ -147,7 +147,7 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 
 **为 plan 待定意图专设的仅实时叠加钩子（`live?(agent, base)`）**——不予采纳：它存在的唯一理由是用户的 plan *选择*不在日志里。让选择走标准命令通道后，`command/run` 上了账，待定态成为纯回放量，投影约定保持恰好三个纯函数。
 
-**把 seam 命名为 `registerFold`**——已被单元约定取代：注册对象如今确实是一个折叠，但本仓库里 `fold*` 专指纯 `(events) => state` 辅助函数，而该 seam 注册的是带 key、带 schema、带版本的单元。投影仍是事件溯源中指称读模型角色的术语，#587 的 Note 标题与 #497 的评论也都已在使用它。
+**把注册 API 命名为 `registerFold`**——已被单元约定取代：注册对象如今确实是一个折叠，但本仓库里 `fold*` 专指纯 `(events) => state` 辅助函数，而该注册表接收的是带 key、带 schema、带版本的单元。投影仍是事件溯源中指称读模型角色的术语，#587 的 Note 标题与 #497 的评论也都已在使用它。
 
 **客户端侧折叠（带 `fromEvent` 的按领域投影 cell）**——曾是第二稿，后被否决：一旦 plan 的单元要折叠两种事件，客户端 cell 就必须在浏览器里复刻 host 的状态转移逻辑——同一个折叠写两遍、各自演化。推送成品值（标题帧先例的泛化）保住唯一计算地点，并把客户端简化为一个由 seq 把守的通用值仓；领域零客户端代码。
 
diff --git a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.i18n.yaml b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.i18n.yaml
index 0b1aa5995a..cfe816fde7 100644
--- a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.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 .agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md
-2026-06-30-pre-tool-input-rewrite.md: f35e6af465ce8cec5685911c43e12b8dd66f2e6a
-2026-06-30-pre-tool-input-rewrite.zh.md: 5793b38293e117e328350722ad1efb3126fd176c
+2026-06-30-pre-tool-input-rewrite.md: 63027079a996f2f7b9d2ef87afcd4e64a2691fb1
+2026-06-30-pre-tool-input-rewrite.zh.md: 8930a3a0b1ca136eb2c788e081f4093df8940162
diff --git a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md
index f35e6af465..63027079a9 100644
--- a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md
+++ b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-30-pre-tool-input-rewrite.zh.md)
 
 ## Problem
 
-The [interception-seams Agent Note](../../implemented/feature/2026-06-30-interception-seams.md) defines `tools/pre-execute` as an allow/deny/ask gate over an execution whose identity is already protected and whose arguments are deeply frozen. Claude Code's `PreToolUse` hook also offers `updatedInput`, so a faithful bridge needs an explicit rewrite mechanism. A rewrite cannot be a mutation escape hatch on the existing execution object: it must keep the durable history, audit record, presentation, and executed value consistent.
+The [interception extension-points Agent Note](../../implemented/feature/2026-06-30-interception-extension-points.md) defines `tools/pre-execute` as an allow/deny/ask gate over an execution whose identity is already protected and whose arguments are deeply frozen. Claude Code's `PreToolUse` hook also offers `updatedInput`, so a faithful bridge needs an explicit rewrite mechanism. A rewrite cannot be a mutation escape hatch on the existing execution object: it must keep the durable history, audit record, presentation, and executed value consistent.
 
 ## The problem: three readers of pre-execution arguments
 
@@ -49,5 +49,5 @@ Allowing a pre-execute listener to assign `exec.arguments` would provide only an
 
 - Does rewriting the `assistant/message` tool-call block corrupt any provider's expectation on replay, or is a separate correction safer?
 - Should the original arguments be preserved on the `tool/call` event (audit) and, if so, under what field?
-- Does the rewrite decision move before the log commit or become a dedicated earlier seam, and how do existing pre-tool allow/deny hooks avoid running twice?
+- Does the rewrite decision move before the log commit or become a dedicated earlier extension point, and how do existing pre-tool allow/deny hooks avoid running twice?
 - How does this interact with a future permission `ask` flow (a user approving a rewritten call)?
diff --git a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md
index 5793b38293..8930a3a0b1 100644
--- a/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md
+++ b/.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-[拦截 seam Agent Note](../../implemented/feature/2026-06-30-interception-seams.md) 将 `tools/pre-execute` 定义为一道针对执行的允许/拒绝/询问门禁，此时执行的身份标识已受保护、参数已被深度冻结。Claude Code 的 `PreToolUse` 钩子还提供了 `updatedInput`，因此忠实的桥接需要一个显式的重写机制。重写不能是对现有执行对象的可变逃逸口：它必须保持持久化历史、审计记录、展示层与实际执行值之间的一致性。
+[拦截扩展点 Agent Note](../../implemented/feature/2026-06-30-interception-extension-points.md) 将 `tools/pre-execute` 定义为一道针对执行的允许/拒绝/询问门禁，此时执行的身份标识已受保护、参数已被深度冻结。Claude Code 的 `PreToolUse` 钩子还提供了 `updatedInput`，因此忠实的桥接需要一个显式的重写机制。重写不能是对现有执行对象的可变逃逸口：它必须保持持久化历史、审计记录、展示层与实际执行值之间的一致性。
 
 ## 问题本质：执行前参数的三个读取方
 
@@ -49,5 +49,5 @@ Status: proposed
 
 - 重写 `assistant/message` 中的工具调用块是否会破坏某些提供方在回放时的预期？还是单独的修正更安全？
 - 原始参数是否应保留在 `tool/call` 事件（审计）上？如果是，放在什么字段？
-- 重写决策是移到日志提交之前，还是成为一个专门的更早 seam？现有的 pre-tool 允许/拒绝钩子如何避免运行两次？
+- 重写决策是移到日志提交之前，还是成为一个专门的更早扩展点？现有的 pre-tool 允许/拒绝钩子如何避免运行两次？
 - 这与未来的权限 `ask` 流程（用户批准一个被重写的调用）如何交互？
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
index f8d4a07f6c..aa6add0de4 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.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 .agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
-2026-07-06-recallable-compaction.md: 6f7baedeaae0038b7f5106cd5fc4e23bdfbbd8dd
-2026-07-06-recallable-compaction.zh.md: cbf8b4a3843ca35647cc569255dfe9d26b45b988
+2026-07-06-recallable-compaction.md: 5fd26dd2d4086dd6f834f7bdb3194b0ad16db1eb
+2026-07-06-recallable-compaction.zh.md: 25ce6ca50d1755e3a90dbadb35d027c95262e5a4
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
index 6f7baedeaa..5fd26dd2d4 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
@@ -83,7 +83,7 @@ Specified during review, deferred until observation calls for them:
 - **Pure stubs, no state checkpoint** — rejected: presumes the model knows what it is missing; fails on unknown unknowns.
 - **LLM aging/consolidation of frozen chunks** — rejected as a routine mechanism: summary-of-summary loss and frozen-prefix churn; the code-only rollup is its surviving form, deferred.
 - **Full prefix as chunk-summarizer input** — rejected: O(N²); the state document gives the same background at O(state).
-- **One summarize call emitting all outputs** — rejected: the summarize path has no structured-output enforcement; parsing one free-text response apart is the fragile seam the fail-closed design avoids.
+- **One summarize call emitting all outputs** — rejected: the summarize path has no structured-output enforcement; parsing one free-text response apart is the fragile boundary the fail-closed design avoids.
 - **Model-chosen chunk boundaries** — deferred: parse-and-validate cost against unproven value; chunk policy sits behind config.
 - **Model-authored pointers** — rejected: pointers must be exact; deterministic assembly is.
 - **FTS/vector index sidecar** — rejected in-session: the live log is in memory and bounded, a literal scan under budget suffices; an index earns its keep at cross-session scope.
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
index cbf8b4a384..25ce6ca50d 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
@@ -83,7 +83,7 @@ Status: proposed
 - **只保留纯存根，不设状态检查点**：不予采纳，因为这假定模型知道自己缺少什么，在面对未知的未知时会失败。
 - **由 LLM 老化／整合冻结分片**：不作为常规机制，因为摘要的摘要会丢失信息，并使冻结前缀频繁变化；其保留下来的形式是由代码汇总，且延后实现。
 - **把完整前缀作为分片摘要器输入**：不予采纳，因为成本为 O(N²)；状态文档以 O(state) 提供相同背景。
-- **一次摘要调用输出全部结果**：不予采纳，因为摘要路径没有结构化输出约束；解析一份自由文本响应并将其拆开，正是保守失败设计要避免的脆弱 seam。
+- **一次摘要调用输出全部结果**：不予采纳，因为摘要路径没有结构化输出约束；解析一份自由文本响应并将其拆开，正是保守失败设计要避免的脆弱边界。
 - **由模型选择分片边界**：延后实现，因为相对于未经证明的收益，解析与校验成本过高；分片策略由配置控制。
 - **由模型编写指针**：不予采纳，因为指针必须精确，应由确定性代码组装。
 - **FTS／向量索引伴随存储**：在会话内不予采纳，因为实时日志已在内存中且大小有界，在预算内进行字面量扫描已经足够；只有跨会话范围才能证明索引的价值。
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
index af92c05200..fe92cb6fdd 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.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 .agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
-2026-07-08-interactive-side-sessions.md: 228380ca2d3d7b2efeb37e713574e1863ce17f38
-2026-07-08-interactive-side-sessions.zh.md: f4e3bfdddff16fe687f2637b3626e7e1382eba61
+2026-07-08-interactive-side-sessions.md: ff7f152b8a106c5b3856846e6980160d1ed59b43
+2026-07-08-interactive-side-sessions.zh.md: f81a3809231ac18ba6b134abd4a821f47af8b662
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
index 228380ca2d..ff7f152b8a 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.md
@@ -36,6 +36,6 @@ Rewind productization, session-tree views, a model-facing side-session tool, and
 
 ## Risks
 
-- Read-only behavior is advisory until a `tools/pre-execute` deny gate enforces it; [the interception seam](../../implemented/feature/2026-06-30-interception-seams.md) can add that gate without changing these mechanics.
+- Read-only behavior is advisory until a `tools/pre-execute` deny gate enforces it; [the interception point](../../implemented/feature/2026-06-30-interception-extension-points.md) can add that gate without changing these mechanics.
 - A compacted source forks its compacted view, so a bound surface should disclose that the child inherits summaries rather than replaced turns.
 - Repeated handbacks consume parent context. The per-merge length cap bounds each note; later consolidation belongs to compaction.
diff --git a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
index f4e3bfdddf..f81a380923 100644
--- a/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-08-interactive-side-sessions.zh.md
@@ -36,6 +36,6 @@ Status: proposed
 
 ## 风险
 
-- 只读行为在 `tools/pre-execute` 拒绝门禁强制执行之前仅为建议性质；[拦截 seam](../../implemented/feature/2026-06-30-interception-seams.md) 可在不改变本机制的前提下添加该门禁。
+- 只读行为在 `tools/pre-execute` 拒绝门禁强制执行之前仅为建议性质；[拦截点](../../implemented/feature/2026-06-30-interception-extension-points.md) 可在不改变本机制的前提下添加该门禁。
 - 经过压缩（compaction）的源会话 fork 出的是其压缩视图，因此绑定的界面应当告知用户子会话继承的是摘要而非被替换的轮次。
 - 反复的 handback 会消耗父会话上下文。每次合并的长度上限约束了单条笔记的大小；后续的合并整理属于上下文压缩的职责。
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
index f5a16fae7e..a0a0dc998d 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.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 .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
-2026-07-17-sdk-follow-up-capabilities.md: 88d5d2f9bd1ce01c20177bcaee5bbe6b434bb978
-2026-07-17-sdk-follow-up-capabilities.zh.md: d54dc4d0635ef37d7196ff5cecbdd6ed093c98e3
+2026-07-17-sdk-follow-up-capabilities.md: 9a17f07139014f95666789e41cacb7af180ef5d8
+2026-07-17-sdk-follow-up-capabilities.zh.md: 2431c5c3d9e45605223d9bb1843e48a3c711759e
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
index 88d5d2f9bd..9a17f07139 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.md
@@ -12,7 +12,7 @@ These gaps are coupled. Create and config already share questions, feature confi
 
 ## Proposal
 
-The SDK extends the existing prompt and project-editing boundaries instead of creating parallel workflows. A non-interactive prompt port and structured feature plan drive create and config, `dsh-sdk create <source>` delegates dependency resolution to the project package manager before mounting the resolved package through `ProjectEditSession`, launcher-side telemetry wraps `create-sdk` and every `dsh-sdk` command, and injected prompt streams provide the primary interactive-test seam.
+The SDK extends the existing prompt and project-editing boundaries instead of creating parallel workflows. A non-interactive prompt port and structured feature plan drive create and config, `dsh-sdk create <source>` delegates dependency resolution to the project package manager before mounting the resolved package through `ProjectEditSession`, launcher-side telemetry wraps `create-sdk` and every `dsh-sdk` command, and injected prompt streams provide the primary interactive-test hook.
 
 | Capability | Product entrypoint | Owning mechanism | Required outcome |
 |---|---|---|---|
diff --git a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
index d54dc4d063..2431c5c3d9 100644
--- a/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md
@@ -12,7 +12,7 @@ Status: proposed
 
 ## 提案
 
-SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非交互式 `PromptPort` 实现和结构化功能计划驱动 create 与 config；`dsh-sdk create <source>` 先把依赖解析交给工程的包管理器，再通过 `ProjectEditSession` 挂载解析所得的包；启动器侧遥测包住 `create-sdk` 和每个 `dsh-sdk` 命令；交互测试主要通过注入的提示词输入输出流完成。
+SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非交互式 `PromptPort` 实现和结构化功能计划驱动 create 与 config；`dsh-sdk create <source>` 先把依赖解析交给工程的包管理器，再通过 `ProjectEditSession` 挂载解析所得的包；启动器侧遥测包住 `create-sdk` 和每个 `dsh-sdk` 命令；注入的提示词输入输出流提供主要的交互测试钩子。
 
 | 功能 | 产品入口 | 所属机制 | 必须达到的结果 |
 |---|---|---|---|
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
index 76abf19851..91cfd64d91 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.i18n.yaml
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.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 .agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
-2026-07-04-prune-dead-core-spine-surface.md: 7ee7ffc6e8c0f3672c98be6e23ef45a1abfc2b4e
-2026-07-04-prune-dead-core-spine-surface.zh.md: 69470658683f70ccc7ed71313654b769c3211cc9
+2026-07-04-prune-dead-core-spine-surface.md: a2ae3170884bd011676f057004549ff7c93b49d4
+2026-07-04-prune-dead-core-spine-surface.zh.md: 6bf796f1203683acdb7ea6e2389a7f2996fb8351
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
index 7ee7ffc6e8..a2ae317088 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
@@ -23,7 +23,7 @@ The production corpus is `packages/*/*/src`, example sources/config, and runtime
 | `PersistenceCoordinator.inits`, backend `inits` accessors, `seedCoversPrefix`, and `assertSerializable` | The accessors exist for white-box tests; `seedCoversPrefix` has no outside production importer; `assertSerializable` has no production caller and duplicates the coordinator append boundary's lossless snapshot. | Observe initialization through `session/flush`, make `seedCoversPrefix` source-private, and delete `assertSerializable`. Keep both backends, `SessionHeader`, and SQLite's version contract. |
 | `LlmError.status` and replay status | Adapters/replay populate it, but production branches on stable error code/message and never reads raw status. | Remove the unread field and replay plumbing while preserving error classification. |
 | `BlockAssembler.push()` return value | Both production callers ignore the returned completed block. | Return `void`; keep the deliberately public `blocks()`/`message()` contract. |
-| `compactRegion`'s separate `session` argument | The fixed caller passes the same object already present as `agent.session`; the model-visible mount API can also call the method, but accepting two identities permits a mounted plugin to provide an incoherent pair. | Keep the manual-region seam while deliberately narrowing it to `agent.session` as the one source of truth. |
+| `compactRegion`'s separate `session` argument | The fixed caller passes the same object already present as `agent.session`; the model-visible mount API can also call the method, but accepting two identities permits a mounted plugin to provide an incoherent pair. | Keep the manual-region API while deliberately narrowing it to `agent.session` as the one source of truth. |
 | `CompactionResult.startSeq`, `summarySeq`, `endSeq`, and `summary` | The production consumer reads only shadowed range/seq/token accounting; the durable log owns summary and event identity. | Remove the four result echoes while keeping both shared transcript renderers. |
 | `BasicCompactService` estimation/summarization visibility | No outside production caller invokes the five methods; the implemented Agent Note names only `estimateContentTokens()` and `summarize()` as subclass hooks. | Make those two `protected` and the three orchestration-only estimators private. |
 | `CodeLogEntry.source`/`level` and `RunCodeMeta.dispatches` | Every production consumer maps logs to text; no presenter/model path reads the other fields or the persisted dispatch count. | Make code-runtime logs strings (or text-only entries) and remove result-meta dispatch plumbing; keep the local counter that mints deterministic dispatch ids. |
@@ -43,7 +43,7 @@ The production corpus is `packages/*/*/src`, example sources/config, and runtime
 
 ## Proposal
 
-Remove or demote every row as one bounded coordinated public-surface cleanup. Update package READMEs, JSDoc, generated API/event catalogs, type-equivalence records, exports maps where needed, and tests so they exercise the owning public seam instead of preserving test-only entry points. Do not collapse any capability seam, LLM adapter, persistence backend, or lifecycle quiescence contract.
+Remove or demote every row as one bounded coordinated public-surface cleanup. Update package READMEs, JSDoc, generated API/event catalogs, type-equivalence records, exports maps where needed, and tests so they exercise the owning public contract instead of preserving test-only entry points. Do not collapse any capability seam, LLM adapter, persistence backend, or lifecycle quiescence contract.
 
 ## Alternatives considered
 
@@ -60,4 +60,4 @@ Remove or demote every row as one bounded coordinated public-surface cleanup. Up
 
 ## Risks
 
-Most removals are compile-visible but runtime-neutral. The compaction argument cleanup deliberately forbids a session/context mismatch while retaining the manual-region seam. External pre-release embedders and existing model-written mounts may import fewer helpers, pass fewer arguments, or receive narrower result shapes; this is an intentional product-surface contraction, not merely generated-catalog cleanup. The repository is unreleased, so carrying unsupported surface is the larger foundation cost.
+Most removals are compile-visible but runtime-neutral. The compaction argument cleanup deliberately forbids a session/context mismatch while retaining the manual-region API. External pre-release embedders and existing model-written mounts may import fewer helpers, pass fewer arguments, or receive narrower result shapes; this is an intentional product-surface contraction, not merely generated-catalog cleanup. The repository is unreleased, so carrying unsupported surface is the larger foundation cost.
diff --git a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
index 6947065868..6bf796f120 100644
--- a/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
+++ b/.agents/notes/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.zh.md
@@ -23,7 +23,7 @@ Status: proposed
 | `PersistenceCoordinator.inits`、后端 `inits` 访问器、`seedCoversPrefix` 与 `assertSerializable` | 访问器为白盒测试而存在；`seedCoversPrefix` 没有包外生产导入者；`assertSerializable` 没有生产调用者，且与 coordinator append 边界的无损快照重复。 | 通过 `session/flush` 观察初始化，将 `seedCoversPrefix` 改为源码私有，删除 `assertSerializable`。保留两个后端、`SessionHeader` 和 SQLite 的版本约定。 |
 | `LlmError.status` 与回放 status | 适配器/回放填充它，但生产分支基于稳定的错误码/消息判断，从不读取原始 status。 | 移除未读字段和回放管道，保留错误分类。 |
 | `BlockAssembler.push()` 返回值 | 两个生产调用者都忽略返回的已完成块。 | 返回 `void`；保留有意公开的 `blocks()`/`message()` 约定。 |
-| `compactRegion` 的独立 `session` 参数 | 固定调用方传入的对象就是 `agent.session` 中已有的对象；模型可见的 mount API 也可以调用该方法，但同时接受两个独立对象，会让挂载的插件传入不一致的组合。 | 保留手动 region seam，同时有意将其收窄为以 `agent.session` 为唯一真源。 |
+| `compactRegion` 的独立 `session` 参数 | 固定调用方传入的对象就是 `agent.session` 中已有的对象；模型可见的 mount API 也可以调用该方法，但同时接受两个独立对象，会让挂载的插件传入不一致的组合。 | 保留手动 region API，同时有意将其收窄为以 `agent.session` 为唯一真源。 |
 | `CompactionResult.startSeq`、`summarySeq`、`endSeq` 与 `summary` | 生产消费方只读取 shadowed range/seq/token 统计；持久日志拥有 summary 和事件标识。 | 移除四个结果回显，保留两个共享的 transcript（文本记录）渲染器。 |
 | `BasicCompactService` 的估算/摘要方法可见性 | 没有包外生产调用者调用这五个方法；已实现的 Agent Note 只将 `estimateContentTokens()` 和 `summarize()` 命名为子类钩子。 | 将这两个方法改为 `protected`，其余三个编排专用的估算器改为 private。 |
 | `CodeLogEntry.source`/`level` 与 `RunCodeMeta.dispatches` | 每个生产消费方都将日志映射为文本；没有 presenter/模型路径读取其他字段或持久化的 dispatch 计数。 | 将 code-runtime 日志改为字符串（或纯文本条目），移除 result-meta 的 dispatch 管道；保留用于生成确定性 dispatch id 的本地计数器。 |
@@ -43,7 +43,7 @@ Status: proposed
 
 ## 提案
 
-以一次有界的、协调的公开接口清理，移除或降级上述每一行。同步更新包 README、JSDoc、生成的 API/事件 catalog、type-equiv 记录、必要的 exports map 以及测试，使测试通过所属的公开 seam 验证行为，而非保留仅为测试而存在的入口。不折叠任何能力 seam、LLM（大语言模型）适配器、持久化后端或生命周期完全停稳约定。
+以一次有界的、协调的公开接口清理，移除或降级上述每一行。同步更新包 README、JSDoc、生成的 API/事件 catalog、type-equiv 记录、必要的 exports map 以及测试，使测试通过所属的公开约定验证行为，而非保留仅为测试而存在的入口。不折叠任何能力 seam、LLM（大语言模型）适配器、持久化后端或生命周期完全停稳约定。
 
 ## 曾考虑的替代方案
 
@@ -60,4 +60,4 @@ Status: proposed
 
 ## 风险
 
-大多数移除在编译时可见但对运行时无影响。上下文压缩参数清理有意禁止会话/上下文不匹配，同时保留手动 region seam。外部预发布嵌入者和现有模型编写的 mount 可能导入更少的辅助函数、传递更少的参数或接收更窄的结果形状；这是有意的产品接口收缩，而非仅仅是生成 catalog 的清理。仓库尚未发布，因此承载不受支持的接口才是更大的基础成本。
+大多数移除在编译时可见但对运行时无影响。上下文压缩参数清理有意禁止会话/上下文不匹配，同时保留手动 region API。外部预发布嵌入者和现有模型编写的 mount 可能导入更少的辅助函数、传递更少的参数或接收更窄的结果形状；这是有意的产品接口收缩，而非仅仅是生成 catalog 的清理。仓库尚未发布，因此承载不受支持的接口才是更大的基础成本。
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
index 6c492ef3ee..08fbd08cee 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.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 .agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
-2026-06-20-fold-session-persistence-interface.md: c0da160e766cf0bed532f0d11bd52e3a027dbe8b
-2026-06-20-fold-session-persistence-interface.zh.md: 8abdf77d2717cfed7209df72182187f75e32e241
+2026-06-20-fold-session-persistence-interface.md: 3079e9495cdbf4dd698fccc65d3c2fdada29cfc1
+2026-06-20-fold-session-persistence-interface.zh.md: e028089399e15d5d125d28788586fa1ef58980e7
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
index c0da160e76..3079e9495c 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.md
@@ -1,18 +1,18 @@
 # Agent Note: Fold the persistence interface into dsh-session
 
-Status: rejected — the separate persistence interface package is the intended modular capability seam for durable backends. Folding it into `dsh-session` would reduce package count at the cost of a cleaner backend boundary.
+Status: rejected — the separate persistence Service Definition package is the intended modular role split for the durable-persistence capability seam. Folding it into `dsh-session` would reduce package count at the cost of a cleaner backend boundary.
 
 English | [中文](2026-06-20-fold-session-persistence-interface.zh.md)
 
 ## Problem
 
-`dsh-session-persistence` is an interface package whose main concepts are already owned by `dsh-session`: `SessionHeader`, `SessionEvent`, `SessionId`, `session/event`, and `session/flush`. The package adds the abstract `SessionPersistence` service, the shared write coordinator, and contract helpers. Backend packages depend on it, and `agent-loop` has to optionally find a sibling service for resume.
+`dsh-session-persistence` is a Service Definition package whose main concepts are already owned by `dsh-session`: `SessionHeader`, `SessionEvent`, `SessionId`, `session/event`, and `session/flush`. The package adds the abstract `SessionPersistence` service, the shared write coordinator, and contract helpers. Provider packages depend on it, and `agent-loop` has to optionally find a sibling service for resume.
 
-The capability-seam split made sense when persistence was a new swappable backend design. After the mutable summary was removed, the interface package mostly wraps the session log's own storage concern. Keeping it separate may be more ceremony than clarity.
+The capability-seam split made sense when persistence was a new swappable backend design. After the mutable summary was removed, the Service Definition package mostly wraps the session log's own storage concern. Keeping it separate may be more ceremony than clarity.
 
 ## Proposal
 
-Move the abstract `SessionPersistence` service, the coordinator, and persistence contract helpers into `dsh-session`. Keep JSONL and SQLite as separate backend packages that register the session-owned service. This preserves backend swappability while deleting one support package and one cross-package seam.
+Move the abstract `SessionPersistence` service, the coordinator, and persistence contract helpers into `dsh-session`. Keep JSONL and SQLite as separate backend packages that register the session-owned service. This preserves backend swappability while deleting one support package and one cross-package boundary.
 
 The implementing PR should update the [capability seams](../../implemented/architecture/2026-06-13-capability-seams.md) guidance with the exception: persistence is not like bash or LLM because its vocabulary and lifecycle events are already the session package's core domain.
 
@@ -26,6 +26,6 @@ The implementing PR should update the [capability seams](../../implemented/archi
 
 ## What we give up
 
-`dsh-session` becomes heavier: it owns both the in-memory log and the persistence interface. That is the trade. If third-party persistence backends were already a public ecosystem, the separate interface package would be a cleaner SDK boundary; pre-release, the extra package looks like abstraction before there is an external consumer.
+`dsh-session` becomes heavier: it owns both the in-memory log and the persistence Service Definition. That is the trade. If third-party persistence backends were already a public ecosystem, the separate Service Definition package would be a cleaner SDK boundary; pre-release, the extra package looks like abstraction before there is an external Consumer.
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
index 8abdf77d27..e028089399 100644
--- a/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-06-20-fold-session-persistence-interface.zh.md
@@ -1,18 +1,18 @@
 # Agent Note: 将持久化接口合并进 dsh-session
 
-Status: rejected — 独立的持久化接口包是为持久化后端设计的模块化能力 seam。将其折叠进 `dsh-session` 虽能减少包数量，却会牺牲更清晰的后端边界。
+Status: rejected — 独立的持久化 Service Definition 包是持久化能力 seam 预期的模块化角色拆分。将其折叠进 `dsh-session` 虽能减少包数量，却会牺牲更清晰的后端边界。
 
 [English](2026-06-20-fold-session-persistence-interface.md) | 中文
 
 ## 问题
 
-`dsh-session-persistence` 是一个接口包，其核心概念已经由 `dsh-session` 拥有：`SessionHeader`、`SessionEvent`、`SessionId`、`session/event` 与 `session/flush`。该包额外添加了抽象的 `SessionPersistence` 服务、共享写入协调器和约定辅助工具。后端包依赖它，为实现恢复，`agent-loop`（智能体循环）还需要按需查找这个同级服务。
+`dsh-session-persistence` 是一个 Service Definition 包，其核心概念已经由 `dsh-session` 拥有：`SessionHeader`、`SessionEvent`、`SessionId`、`session/event` 与 `session/flush`。该包额外添加了抽象的 `SessionPersistence` 服务、共享写入协调器和约定辅助工具。提供方包依赖它，为实现恢复，`agent-loop`（智能体循环）还需要按需查找这个同级服务。
 
-当持久化还是一个全新的可替换后端设计时，能力 seam 的拆分是合理的。但在可变摘要被移除之后，这个接口包基本上只是包装了会话日志自身的存储职责。继续保持独立可能带来的仪式感多于清晰度。
+当持久化还是一个全新的可替换后端设计时，能力 seam 的拆分是合理的。但在可变摘要被移除之后，这个 Service Definition 包基本上只是包装了会话日志自身的存储职责。继续保持独立可能带来的仪式感多于清晰度。
 
 ## 提案
 
-将抽象的 `SessionPersistence` 服务、协调器和持久化约定辅助工具移入 `dsh-session`。JSONL 和 SQLite 仍作为独立的后端包，注册由会话包拥有的服务。这样既保留了后端可替换性，又删除了一个支撑包和一条跨包 seam。
+将抽象的 `SessionPersistence` 服务、协调器和持久化约定辅助工具移入 `dsh-session`。JSONL 和 SQLite 仍作为独立的后端包，注册由会话包拥有的服务。这样既保留了后端可替换性，又删除了一个支撑包和一条跨包边界。
 
 实施 PR（Pull Request）应更新[能力 seam](../../implemented/architecture/2026-06-13-capability-seams.md) 指南，补充此例外：持久化不同于 bash 或 LLM（大语言模型），因为它的词汇和生命周期事件本就属于会话包的核心领域。
 
@@ -26,6 +26,6 @@ Status: rejected — 独立的持久化接口包是为持久化后端设计的
 
 ## 放弃了什么
 
-`dsh-session` 变得更重：它同时拥有内存日志和持久化接口。这就是代价。如果第三方持久化后端已经形成公开生态，独立的接口包会是更清晰的 SDK 边界；但在预发布阶段尚无外部消费方时，这个额外的包更像是过早引入的抽象。
+`dsh-session` 变得更重：它同时拥有内存日志和持久化 Service Definition。这就是代价。如果第三方持久化后端已经形成公开生态，独立的 Service Definition 包会是更清晰的 SDK 边界；但在预发布阶段尚无外部 Consumer 时，这个额外的包更像是过早引入的抽象。
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
index 820638a9f6..9ade4e5770 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.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 .agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
-2026-07-12-collapse-workflow-to-foreground-core.md: 629e2140523c3ae7caf533de99821206d05f1b8e
-2026-07-12-collapse-workflow-to-foreground-core.zh.md: 9683d5a15bc7d201eaff905c440bbdf88bbc9388
+2026-07-12-collapse-workflow-to-foreground-core.md: 5fc46584f83eb5307ff16f3353b56951b928aef3
+2026-07-12-collapse-workflow-to-foreground-core.zh.md: 0b4c73e5df973215b10166f3dc2bbd525cc8231b
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
index 629e214052..5fc46584f8 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.md
@@ -28,7 +28,7 @@ Amend the implemented dynamic-workflow Agent Note and update the seam/tool/worke
 
 ## Acceptance criteria
 
-- The workflow public seam contains only execution, cancellation, result, and disposal contracts with a production consumer.
+- The workflow public contract contains only execution, cancellation, result, and disposal contracts with a production consumer.
 - No workflow event, phase/log protocol message, run-id generator, progress-only metadata, host pairing ledger, or fatal-mode branch remains.
 - The run handle has no id/meta echoes, and cancellation has one holder-owned channel after synchronous `start()` returns.
 - Parallel/pipeline behavior, caps, cancellation quiescence, worker containment, structured output, and the model-facing workflow scenarios retain coverage.
@@ -36,4 +36,4 @@ Amend the implemented dynamic-workflow Agent Note and update the seam/tool/worke
 
 ## Risks
 
-This is a compile-visible contraction of the workflow DSL, event taxonomy, handle, and start request. Existing workflow calls that supply descriptive metadata, and scripts that use `phase`, `log`, or labels, must shrink; programmatic callers bridge their own abort source to the returned handle; and a future observer must add a better-correlated seam. The execution semantics that make workflows useful do not change.
+This is a compile-visible contraction of the workflow DSL, event taxonomy, handle, and start request. Existing workflow calls that supply descriptive metadata, and scripts that use `phase`, `log`, or labels, must shrink; programmatic callers bridge their own abort source to the returned handle; and a future observer must add a better-correlated event contract. The execution semantics that make workflows useful do not change.
diff --git a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
index 9683d5a15b..0b4c73e5df 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-collapse-workflow-to-foreground-core.zh.md
@@ -28,7 +28,7 @@ Status: rejected — 工作流进度是有意设计的观测接口面；应通
 
 ## 验收标准
 
-- 工作流公开 seam 仅包含有生产消费方的执行、取消、结果与 dispose 约定。
+- 工作流公开约定仅包含有生产消费方的执行、取消、结果与 dispose 约定。
 - 不再保留任何工作流事件、phase/log 协议消息、run-id 生成器、仅供进度使用的元数据、host 配对账本或 fatal 模式分支。
 - run handle 不再有 id/meta 回显，取消在同步 `start()` 返回后只有一条持有者拥有的通道。
 - parallel/pipeline 行为、上限、取消后的完全停稳、worker 隔离、结构化输出与面向模型的工作流场景保持测试覆盖。
@@ -36,4 +36,4 @@ Status: rejected — 工作流进度是有意设计的观测接口面；应通
 
 ## 风险
 
-这是对工作流 DSL、事件分类体系、handle 与 start request 的编译可见收缩。现有提供描述性元数据的工作流调用，以及使用 `phase`、`log` 或 label 的脚本，都必须相应精简；程序化调用方需自行将 abort source 桥接到返回的 handle；未来的观测者必须添加一个关联性更好的 seam。使工作流有用的执行语义不变。
+这是对工作流 DSL、事件分类体系、handle 与 start request 的编译可见收缩。现有提供描述性元数据的工作流调用，以及使用 `phase`、`log` 或 label 的脚本，都必须相应精简；程序化调用方需自行将 abort source 桥接到返回的 handle；未来的观测者必须添加一个关联性更好的事件约定。使工作流有用的执行语义不变。
diff --git a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
index 3da21fcadc..66c131db5f 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.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 .agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
-2026-07-12-prune-unused-skill-registry-surface.md: 5a13effa04a6cd9954741a0a33ebc6fc3512fab8
-2026-07-12-prune-unused-skill-registry-surface.zh.md: f0cca25cb642eba851b63ce784d8fb9343d1f692
+2026-07-12-prune-unused-skill-registry-surface.md: 30247cad9c3b05f2a3afbffa1e1c140e9cd88e25
+2026-07-12-prune-unused-skill-registry-surface.zh.md: 02e47919c8d171ebd00aa03bf8612d5ca5f3e901
diff --git a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
index 5a13effa04..30247cad9c 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-12-prune-unused-skill-registry-surface.zh.md)
 
 ## Problem
 
-The skill service's embedded-runtime subsystem has zero production caller of `ctx.skills.register()`. It adds a reserved `runtime` provider name, a runtime map/rank/source, duplicate policy, a second revision in cache keys, normalization, disposers, and tests alongside the provider seam every shipped skill already uses. `SkillSummary.whenToUse` and candidate/definition `path` are parsed and copied but never read by a production consumer: the model catalog renders name/description, resource loading uses `resourceBase`, and providers own their locator. The deliberately open `metadata` extension point stays.
+The skill service's embedded-runtime subsystem has zero production caller of `ctx.skills.register()`. It adds a reserved `runtime` provider name, a runtime map/rank/source, duplicate policy, a second revision in cache keys, normalization, disposers, and tests alongside the provider contract every shipped skill already uses. `SkillSummary.whenToUse` and candidate/definition `path` are parsed and copied but never read by a production consumer: the model catalog renders name/description, resource loading uses `resourceBase`, and providers own their locator. The deliberately open `metadata` extension point stays.
 
 ## Proposal
 
diff --git a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
index f0cca25cb6..02e47919c8 100644
--- a/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-12-prune-unused-skill-registry-surface.zh.md
@@ -6,7 +6,7 @@ Status: rejected — 直接在运行时注册 skill 是为第三方插件保留
 
 ## 问题
 
-skill（技能）服务的嵌入式运行时子系统中，`ctx.skills.register()` 没有任何生产调用方。它引入了一个保留的 `runtime` 提供方名称、一套运行时 map/rank/source、重复策略、缓存键中的第二个 revision、规范化逻辑、dispose（资源释放）函数以及相应测试——而所有已交付的 skill 都只使用提供方 seam。`SkillSummary.whenToUse` 和 candidate/definition 的 `path` 被解析和复制，但没有任何生产消费方读取它们：模型目录只渲染 name/description，资源加载使用 `resourceBase`，提供方自行管理其定位器。有意开放的 `metadata` 扩展点保留不动。
+skill（技能）服务的嵌入式运行时子系统中，`ctx.skills.register()` 没有任何生产调用方。它引入了一个保留的 `runtime` 提供方名称、一套运行时 map/rank/source、重复策略、缓存键中的第二个 revision、规范化逻辑、dispose（资源释放）函数以及相应测试——而所有已交付的 skill 都只使用提供方约定。`SkillSummary.whenToUse` 和 candidate/definition 的 `path` 被解析和复制，但没有任何生产消费方读取它们：模型目录只渲染 name/description，资源加载使用 `resourceBase`，提供方自行管理其定位器。有意开放的 `metadata` 扩展点保留不动。
 
 ## 提案
 
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml
index 2e98c0fdc7..6e9bbece70 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.i18n.yaml
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.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 .agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
-2026-07-19-fold-compaction-package-split.md: eeb0b5871ceacbbefc8bfa9f782b4bdd6735f20a
-2026-07-19-fold-compaction-package-split.zh.md: 1b7e456536254acd98944c601da12d97453803ba
+2026-07-19-fold-compaction-package-split.md: 8bd83c389454092171633af806178ef8a9a74c72
+2026-07-19-fold-compaction-package-split.zh.md: ada725cbf726695836cc2dfce47fce82bea8d0f0
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
index eeb0b5871c..8bd83c3894 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.md
@@ -1,12 +1,12 @@
 # Agent Note: Fold the single compaction backend into its service package
 
-Status: rejected — More compaction backends are planned, so the interface and basic implementation packages remain separate.
+Status: rejected — More compaction backends are planned, so the Service Definition and basic provider packages remain separate.
 
 English | [中文](2026-07-19-fold-compaction-package-split.zh.md)
 
 ## Problem
 
-Compaction is split between `@deepseek-ai/dsh-compact`, which owns an abstract two-method service and shared types, and `@deepseek-ai/dsh-compact-basic`, which owns the only complete implementation. Shipped configurations load only the basic package, and no production package independently consumes the interface package except that implementation.
+Compaction is split between `@deepseek-ai/dsh-compact`, which owns an abstract two-method service and shared types, and `@deepseek-ai/dsh-compact-basic`, which owns the only complete provider. Shipped configurations load only the basic package, and no production package independently consumes the Service Definition package except that provider.
 
 The split adds a package manifest, README, project boundary, dependency edge, abstract forwarding class, generated catalog entries, and composition wiring without demonstrating backend substitution. The [capability-seam decision](../../implemented/architecture/2026-06-13-capability-seams.md) requires a real interface, implementation, and consumer rather than a preemptive split; the [compaction decision](../../implemented/feature/2026-06-18-compaction-capability-seam.md) records that its independent consumer was deferred.
 
@@ -14,7 +14,7 @@ The split adds a package manifest, README, project boundary, dependency edge, ab
 
 Move the basic implementation into `@deepseek-ai/dsh-compact` and remove `@deepseek-ai/dsh-compact-basic`. Keep `ctx.compact`, `CompactionResult`, the shared transcript and tool-pairing helpers, the existing configuration, and the concrete compaction algorithm in one package.
 
-Preserve `summarize()` as a protected customization hook. A deployment-specific summarizer can subclass or intercept the existing LLM call without requiring a second capability package. Reintroduce an interface package only when a second complete backend and an independent consumer need substitution.
+Preserve `summarize()` as a protected customization hook. A deployment-specific summarizer can subclass or intercept the existing LLM call without requiring a second capability package. Reintroduce a separate Service Definition package only when a second complete backend and an independent Consumer need substitution.
 
 Amend the implemented compaction decision and the [recallable-compaction proposal](../../proposed/feature/2026-07-06-recallable-compaction.md) if this proposal is accepted so package ownership has one durable description.
 
@@ -22,7 +22,7 @@ Amend the implemented compaction decision and the [recallable-compaction proposa
 
 **Keep the split because a remote or recall backend may arrive.** A possible future implementation does not justify the current package boundary. Recall adds a consumer of compaction results, not necessarily another implementation, and a remote summarizer can use the protected hook.
 
-**Move the implementation package name onto the interface package.** Keeping `compact-basic` as the surviving name would make the product service appear to be one optional backend. `compact` is the stable service identity already used by `ctx.compact` and is the clearer single-package owner.
+**Move the provider package name onto the Service Definition package.** Keeping `compact-basic` as the surviving name would make the product service appear to be one optional backend. `compact` is the stable service identity already used by `ctx.compact` and is the clearer single-package owner.
 
 ## Acceptance criteria
 
diff --git a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
index 1b7e456536..ada725cbf7 100644
--- a/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
+++ b/.agents/notes/rejected/simplification/2026-07-19-fold-compaction-package-split.zh.md
@@ -1,12 +1,12 @@
 # Agent Note: 将唯一的压缩后端并入服务包
 
-Status: rejected — 计划增加更多压缩后端，因此接口包与 basic 实现包继续分离。
+Status: rejected — 计划增加更多压缩后端，因此 Service Definition 包与 basic 提供方包继续分离。
 
 [English](2026-07-19-fold-compaction-package-split.md) | 中文
 
 ## 问题
 
-压缩（compaction）目前拆分在两个包中：`@deepseek-ai/dsh-compact` 拥有一个含两个方法的抽象服务和共享类型，`@deepseek-ai/dsh-compact-basic` 拥有唯一的完整实现。交付配置只加载 basic 包，除了该实现外，没有生产包独立消费接口包。
+压缩（compaction）目前拆分在两个包中：`@deepseek-ai/dsh-compact` 拥有一个含两个方法的抽象服务和共享类型，`@deepseek-ai/dsh-compact-basic` 拥有唯一的完整提供方。交付配置只加载 basic 包，除了该提供方外，没有生产包独立消费 Service Definition 包。
 
 该拆分增加了一份包 manifest（元数据清单）、README、项目边界、依赖边、抽象转发类、生成目录项和组合接线，却没有实际的后端替换用例。[能力 seam 决策](../../implemented/architecture/2026-06-13-capability-seams.md)要求接口、实现和消费方都必须真实存在，而不能预先拆分；[压缩决策](../../implemented/feature/2026-06-18-compaction-capability-seam.md)也记录了独立消费方仍被推迟。
 
@@ -14,7 +14,7 @@ Status: rejected — 计划增加更多压缩后端，因此接口包与 basic 
 
 把 basic 实现移入 `@deepseek-ai/dsh-compact`，并删除 `@deepseek-ai/dsh-compact-basic`。`ctx.compact`、`CompactionResult`、共享 transcript（文本记录）和工具配对辅助方法、现有配置以及具体压缩算法都由一个包负责。
 
-保留 `summarize()` 作为受保护的自定义钩子。部署专用的摘要器可以通过继承或拦截现有 LLM（大语言模型）调用完成定制，无需第二个能力包。只有在第二个完整后端与独立消费方确实需要替换实现时，才重新提取接口包。
+保留 `summarize()` 作为受保护的自定义钩子。部署专用的摘要器可以通过继承或拦截现有 LLM（大语言模型）调用完成定制，无需第二个能力包。只有在第二个完整后端与独立 Consumer 确实需要替换实现时，才重新引入独立的 Service Definition 包。
 
 如果本提案获准，应同步修订已实现的压缩决策与[可回忆压缩提案](../../proposed/feature/2026-07-06-recallable-compaction.md)，使包所有权只有一处持久说明。
 
@@ -22,7 +22,7 @@ Status: rejected — 计划增加更多压缩后端，因此接口包与 basic 
 
 **为可能出现的远程或回忆后端保留拆分。** 一种可能的未来实现不足以支撑当前包边界。回忆功能会增加压缩结果的消费方，但不一定增加另一种实现；远程摘要器也可以使用受保护钩子。
 
-**将实现包名用于接口包。** 如果保留 `compact-basic` 作为最终名称，产品服务会看起来像一个可选后端。`compact` 已经是 `ctx.compact` 使用的稳定服务标识，更适合作为单包所有者。
+**将提供方包名用于 Service Definition 包。** 如果保留 `compact-basic` 作为最终名称，产品服务会看起来像一个可选后端。`compact` 已经是 `ctx.compact` 使用的稳定服务标识，更适合作为单包所有者。
 
 ## 验收标准
 
diff --git a/AGENTS.md b/AGENTS.md
index def643ad95..ff31eb0b65 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,30 +14,30 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   core/        product API spine: session, system-prompt, tools, agent, agent-loop
   api/         Remote BFF assembly and TypeRT RPC gateway
   typert/      type graph generator, loader, and runtime registry
-  llm/         LLM seam + DeepSeek adapters (direct-fetch + pi-ai design twin)
+  llm/         LLM capability: Service Definition/Consumer + DeepSeek providers
   e2b/         E2B POC: sandbox + FS/subprocess adapters
-  bash/        bash executor seam + local/pwsh impls + model-facing shell tools
-  subprocess/  subprocess seam + local process-tree impl
-  pty/         persistent PTY seam/backend/tools
-  fs/          filesystem seam/backends/policy/tools
-  lsp/         language-server seam/local backend/tool
+  bash/        bash capability: Service Definition + local/pwsh providers + shell Consumers
+  subprocess/  subprocess capability + local process-tree provider
+  pty/         persistent PTY capability
+  fs/          filesystem capability + policy
+  lsp/         language-server capability
   skill/       skill provider registry + local impl + catalog/loader tool
-  web/         web seam + search/fetch providers + model-facing web tools
-  compact/     compaction seam + basic backend
+  web/         web capability: Service Definition + search/fetch providers + tool Consumer
+  compact/     compaction capability + basic provider
   context/     request-context plugins
-  subagent/    subagent seam + spawn/fork/ACP backends + tool
+  subagent/    subagent capability: Service Definition + providers + delegation Consumers
   bundle/      installable dsh --profile patch-layer bundles
-  workflow/    workflow seam + worker-thread engine + workflow tool
+  workflow/    workflow capability + worker-thread provider + tool Consumer
   todo/        todo_write tool
   plan/        plan mode as logged state
   guard/       loop-hygiene + tool-timeout plugins
   self-modification/  the agent inspects/mounts its own plugins
   hooks/       Claude Code/Codex hook bridges + wire-protocol library
   session/     durable session data: persistence, projection, titles, telemetry
-  settings/    user-settings seam + file provider
-  credentials/ credential-reference seam + env/.env provider
+  settings/    user-settings capability + file provider
+  credentials/ credential-reference capability + env/.env provider
   acp/         automation-only Agent Client Protocol server
-  interaction/ approval/interaction seams, permission, commands, ask-user
+  interaction/ approval/interaction capabilities, permission, commands, ask-user
   boot/        shared app-bin glue
   scaffold/    project tooling: helper, launcher, initializer, SDK protocol
   examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins)
@@ -103,14 +103,14 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
-- **Plugins, not loop changes**: new behavior goes on the documented extension seams; changing `agent-loop` requires updating docs/architecture.md.
-- **Capability seams span three packages** — interface / implementation / consumer; don't split preemptively. The seam is all three ([glossary](docs/glossary.md#capability-seam)).
+- **Plugins, not loop changes**: new behavior goes on documented extension points; changing `agent-loop` requires updating docs/architecture.md.
+- **A capability seam comprises Service Definition / Service provider / Consumer roles.** It is complete, never one role; split only when roles evolve independently ([glossary](docs/glossary.md#capability-seam)).
 - **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).
-- **Explicit > implicit at package seams**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-bash` request/spec split is the template).
-- **No hardcoded tunables in plugins**: deployment-varying choices are validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test seam is not configurability. Protocol constants, external specs, and security invariants stay fixed.
+- **Explicit > implicit at package boundaries**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-bash` request/spec split is the template).
+- **No hardcoded tunables in plugins**: deployment-varying choices are validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test hook is not configurability. Protocol constants, external specs, and security invariants stay fixed.
 - **Misconfiguration fails loud** at load when self-contained, otherwise at the earliest resolvable point; never silently skip a missing referent.
 - **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string`.
-- **Trust TypeScript at typed same-process seams.** Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.
+- **Trust TypeScript at typed same-process boundaries.** Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.
 - **Source plane vs artifact plane, never mixed.** Static gates and tests resolve workspace imports through tsconfig `paths` to `src` and pass on a clean tree; gates consuming built `lib/` declare that dependency ([layout](docs/development.md#typescript-project-layout)).
 - **Keep compiler faces explicit.** Each package uses one aggregate except `api/remotes`; repo-wide programs seed a face config, never the root solution ([layout](docs/development.md#typescript-project-layout)).
 - **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement.
@@ -119,7 +119,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Non-trivial changes MUST include an Agent Note in the same PR;** only mechanical/local edits are exempt ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)).
 - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
 - **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
-- **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
+- **Plan unit, e2e, and snapshot coverage** for new capability seams, lifecycle shapes, and transcript surfaces; add missing snapshot-harness support in the same change.
 - **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
 - **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md)).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
@@ -131,7 +131,7 @@ Read [docs/defensive-patterns.md](docs/defensive-patterns.md) before lifecycle,
 
 ## Type safety and documentation
 
-Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` explains why a narrower type is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include `@param`/`@returns`, as enforced by `verify-export-jsdoc`. Heritage-declared members, plugin-protocol slots, and constructors keep their docs at the declaring seam, protocol, or class.
+Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` explains why narrowing is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include `@param`/`@returns`, as enforced by `verify-export-jsdoc`. Heritage-declared members, plugin-protocol slots, and constructors keep their docs at the declaring Service Definition, protocol, or class.
 
 Comments and docs preserve complete contracts and non-obvious orientation, not reasoning transcripts. Do not narrate control flow or tests, preserve review history, or restate code. Keep factual clauses affecting behavior, failure, timing, ownership, or safe use; link aggressively to owning rationale. Use [dsh-prose-standard](.agents/skills/dsh-prose-standard/SKILL.md) for prose decisions. Wire mechanically checkable invariants into an executed top-level gate and prove each new or changed acceptance path rejects an invalid case. Use narrow justified exceptions instead of disabling a rule globally.
 
diff --git a/apps/web/tests/approval-composer.e2e.ts b/apps/web/tests/approval-composer.e2e.ts
index 5723c7a9db..33259b6ed2 100644
--- a/apps/web/tests/approval-composer.e2e.ts
+++ b/apps/web/tests/approval-composer.e2e.ts
@@ -89,7 +89,7 @@ describe('web e2e: approval takeover keeps its actions reachable', () => {
     await input.fill('')
 
     // Read-only: the mode whose denial the model escalates from. Switched
-    // through the shipped access-mode chip, not a test-only seam.
+    // through the shipped access-mode chip, not a test-only override.
     await page.locator('[aria-label^="Access mode"]').click()
     await page.getByRole('menuitem', { name: 'Read Only' }).click()
     await expect.poll(
diff --git a/apps/web/tests/default-model.e2e.ts b/apps/web/tests/default-model.e2e.ts
index 0c43bf3998..791f8e98c1 100644
--- a/apps/web/tests/default-model.e2e.ts
+++ b/apps/web/tests/default-model.e2e.ts
@@ -4,7 +4,7 @@
 // a route keeps deriving from its own log — the tier order the gateway
 // resolves on every read.
 // Zero model calls: the switch is settings/llm-domain traffic only, so there
-// is no fixture and a stray stream would fail loud on the open seam. Both
+// is no fixture and a stray stream would fail loud because the adapter registry is empty. Both
 // routes are declared host-side (not through the UI, which has its own
 // scenario) through the pi-ai adapter the shipped tree already mounts: a
 // fixture-less scaffold registers no adapter at all, so the routes the
diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index 1aa6b3dea9..5f2173248e 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -232,7 +232,7 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
 
   it.skipIf(MODE === 'record')('cascades the dark theme from the body attribute to painted surfaces', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-lifecycle-dark'))
-    // This scenario pins the ThemeService's DOM contract seam directly (the
+    // This scenario pins the ThemeService's DOM contract directly (the
     // body[data-ds-dark-theme] attribute -> stylesheet cascade); the REAL
     // user gesture above it (Settings -> Appearance cubes) is owned by
     // settings-chrome.e2e.ts. Driving the attribute here keeps the cascade
diff --git a/apps/web/tests/live-interactions.e2e.ts b/apps/web/tests/live-interactions.e2e.ts
index e3a427c446..90383f6987 100644
--- a/apps/web/tests/live-interactions.e2e.ts
+++ b/apps/web/tests/live-interactions.e2e.ts
@@ -1,6 +1,6 @@
 // Web e2e scenarios: live-turn interactions — cancellation, error surfacing,
 // and transient-retry recovery, all through the real composition and wire.
-// The model seam is dsh-llm-replay with override sidecars: `hang` (+ a
+// The model adapter is dsh-llm-replay with override sidecars: `hang` (+ a
 // readyFile marker) makes mid-stream cancel deterministic by construction,
 // `throw` entries express provider failures by stable code, and `{ patches }`
 // augmentation injects a transient throw before the recorded success so
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index be3c6f18a1..53d5ef4982 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -7,7 +7,7 @@
 // provider status. The customized-settings fold writes the curated
 // reasoning field as a merge patch. Zero model calls: configuration is pure
 // settings/credentials/llm-domain traffic, so there is no fixture and a
-// stray stream would fail loud on the open seam. The provider under test is
+// stray stream would fail loud because the adapter registry is empty. The provider under test is
 // minimax-cn so a developer's real ANTHROPIC/OPENAI environment keys can
 // never shadow the derived reference. The deletion dialog distinguishes a
 // reference-free profile from a page-managed key before the credential and
diff --git a/apps/web/tests/replay-round-trip.e2e.ts b/apps/web/tests/replay-round-trip.e2e.ts
index 19271ad020..0bb0bc8176 100644
--- a/apps/web/tests/replay-round-trip.e2e.ts
+++ b/apps/web/tests/replay-round-trip.e2e.ts
@@ -1,6 +1,6 @@
 // Web e2e scenario: fresh round trip. A real chromium types a prompt into the
 // real composer; the wire, apiproxy, agent loop, and the REAL bash tool (echo
-// in the temp workspace) all run; the model seam is dsh-llm-replay (keyless)
+// in the temp workspace) all run; the model adapter is dsh-llm-replay (keyless)
 // or the live adapter (record). Drive steps run in every mode and wait only
 // on generic completion (whenTurnSettled — never model-content selectors, so
 // record cannot hang on a live model answering differently); assertion steps
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 6a8ff82ff1..31a638c12e 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -151,7 +151,7 @@ export interface WebScaffold {
   mode: WebSnapshotMode
   /** Browser-facing origin for the bound test server. */
   baseUrl: string
-  /** Settled root context (the in-process barrier seam; headless event subscription is its sanctioned use). */
+  /** Settled root context (the in-process readiness barrier; headless event subscription is its sanctioned use). */
   ctx: Context
   /** Temp project directory sessions run in (bash/fs tool cwd). */
   workspaceCwd: string
diff --git a/apps/web/tests/sidebar-subagent-activity.e2e.ts b/apps/web/tests/sidebar-subagent-activity.e2e.ts
index 4c37ea6fc1..8e40480090 100644
--- a/apps/web/tests/sidebar-subagent-activity.e2e.ts
+++ b/apps/web/tests/sidebar-subagent-activity.e2e.ts
@@ -27,7 +27,7 @@ const MODE = webSnapshotMode()
 const HOLD_PROVIDER = 'web-test-hold'
 const HOLD_MODEL = 'hold'
 
-/** Model seam that completes the owner turn, then holds its delegated child open. */
+/** Model stub that completes the owner turn, then holds its delegated child open. */
 class StagedAdapter extends LlmAdapter {
   activeCalls = 0
   private calls = 0
diff --git a/apps/web/tests/skill-user-invoke.e2e.ts b/apps/web/tests/skill-user-invoke.e2e.ts
index 2d5a039623..302aa062b0 100644
--- a/apps/web/tests/skill-user-invoke.e2e.ts
+++ b/apps/web/tests/skill-user-invoke.e2e.ts
@@ -2,7 +2,7 @@
 // the composer (issue #1470). The entered `/name args` line claims into
 // skill.invoke: the real host forwards the gesture as an ordinary user
 // prompt, injects the rendered body as instructions context named after the
-// skill, and starts a turn answered by the replay seam. The transcript shows
+// skill, and starts a turn answered by the replay adapter. The transcript shows
 // the gesture bubble, the collapsed context-injection row, and the reply.
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
@@ -133,7 +133,7 @@ describe.skipIf(MODE === 'record')('web e2e: user-explicit skill invocation thro
     expect(injected).not.toContain(ARGS_TEXT)
     await injectionRow.click()
 
-    // The injection started a turn; the replay seam answers it.
+    // The injection started a turn; the replay adapter answers it.
     await page.getByText('USER_INVOKE_REPLY', { exact: false }).first().waitFor({ timeout: 20_000 })
 
     const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index a7e6b06747..f373fd6469 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -20,7 +20,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
 |---|---|---|
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
-| [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
+| [architecture.md](architecture.md) | System map: services, loop, capability seams, extension points — read before changing `packages/` | Type shapes (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
 | [subsystems/](subsystems/README.md) | One reference page per subsystem: type shapes, semantics, and the generated Cordis surface | Behavior narration (→ architecture.md) |
 | [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and verification contract; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
@@ -42,7 +42,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 - **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
-- Write directly without metaphor. Name actors and exact facts; use words you'd say to a colleague ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Avoid "gate", "vocabulary", "surface", or "seam".
+- Write directly: name actors and facts plainly ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Reserve `seam` for the defined capability; avoid metaphorical "gate", "vocabulary", and "surface".
 
 ## Wordcount Budgets
 
@@ -65,7 +65,7 @@ Hunt these in any doc; the [dsh-doc-standards](../.agents/skills/dsh-doc-standar
 - Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
 - Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
 - Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
-- Rationale repeated beside sibling methods instead of once at the owning seam or helper.
+- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
 - Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it, or demote the detail to the linked home.
 - Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
 - Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 7c8b1b95c8..dff7978387 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: bb76e6ce106bf6ab06b3a12b536aabbae581740f
-architecture.zh.md: eb2fc4dea190914d0b5f0732db571c81f2f0d471
+architecture.md: 506283bfc651d38fe4bccd50fb8a86143d2b41d8
+architecture.zh.md: ea48af8131ebbdc70a45e403dfddc78dfcfb6f47
diff --git a/docs/architecture.md b/docs/architecture.md
index bb76e6ce10..506283bfc6 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -156,11 +156,9 @@ Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is on
 
 ### Capability Pattern
 
-A **seam** is a swappable capability across three packages: a **Service Definition** (the Cordis `Service` owning its `ctx` key and vocabulary), a **Service provider** (the implementation plugin), and a **Consumer**. The Service Definition alone is the service, not the seam. Bash is the reference; the [capability graph](capability-seams.md) shows every family.
+A **seam** is a swappable capability with **Service Definition**, **Service provider**, and **Consumer** roles. Packages may combine roles; individual roles are not seams. Filesystem and subprocess providers share one execution world; Bash, PTY, and LSP need no provider forks ([capability graph](capability-seams.md)).
 
-Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks.
-
-Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](subsystems/subagent.md)).
+Exceptions combine LLM Service Definition/Consumer roles, filesystem policy, web registries, and skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate a self-contained turn to Codex or another product provider ([subagent.md](subsystems/subagent.md)).
 
 `dsh-workspace-context` composes its baseline on the first `agent/pre-step` and folds it into the final entering batch right after the claimed prompt, so it reaches the first request with the direct prompt; rejection keeps it in the next-step inbox. When compaction removes that baseline from the visible surface, the next entering pre-step composes the current baseline and carries it in the same request. Filesystem changes projected after tools are likewise folded into the next entering pre-step instead of creating a later context-only step ([decision](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)). `dsh-paths` owns shared paths.
 
@@ -191,4 +189,4 @@ New behavior attaches to a documented extension point; a loop change updates thi
 | Fork a live session | call `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | Scope a registration to one agent | use its `agent.ctx` (see Agent Scope) |
 
-The [extension cookbook](cookbook/extension-cookbook.md) has plugin skeletons and the feature-to-seam map; guides cover [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [vendored packages](cookbook/adding-a-vendored-package.md).
+The [extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities; guides cover [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [vendored packages](cookbook/adding-a-vendored-package.md).
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index eb2fc4dea1..ea48af8131 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -156,11 +156,9 @@ idle inject:
 
 ### 能力模式
 
-一个 **seam** 是跨三个包的一项可替换能力：**Service Definition**（拥有自身 `ctx` key 和词汇的 Cordis `Service`）、**Service provider**（实现插件）和 **Consumer**。Service Definition 本身只是服务，不是 seam。Bash 是参考；[能力图](capability-seams.md)展示每个家族。
+一个 **seam** 是一项包含 **Service Definition**、**Service provider** 和 **Consumer** 三种角色的可替换能力。包可以合并承担多个角色；任何单一角色都不是 seam。文件系统与进程管理提供方共享一个执行世界，Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork（[能力图](capability-seams.md)）。
 
-文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。
-
-例外情况包括 LLM（大语言模型）接口／消费方合并、文件系统策略、web 注册表，以及具名 skill/subagent 提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。
+例外情况包括 LLM（大语言模型）Service Definition／消费方角色合并、文件系统策略、web 注册表，以及 skill/subagent 提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 或其他产品提供方（[subagent.md](subsystems/subagent.md)）。
 
 `dsh-workspace-context` 在第一次 `agent/pre-step` 组合基线并将它折入最终进入的批次、紧随已领取的直接提示词之后，使其与直接提示词一同抵达第一次请求；reject 则将它留在 next-step inbox。当压缩从可见表层移除该基线时，下一次进入步骤的 pre-step 会组合当前基线，并在同一请求中携带它。工具执行后投影的文件系统变更也会折入下一次进入步骤的 pre-step，而不会另外创建稍后的纯上下文步骤（[决策](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)）。`dsh-paths` 负责共享路径。
 
@@ -191,4 +189,4 @@ idle inject:
 | fork 活跃会话 | 调用 `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | 将注册项限定到单个 agent | 使用其 `agent.ctx`（参见 Agent 作用域） |
 
-[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)提供插件骨架和功能到 seam 的映射；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
+[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)将功能映射到能力；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 1fd835771a..5ec532504d 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: e1d0374afab497982b862ab84af4c003a30b5d93
-config-catalog.zh.md: 93ca0a02b0027a77f3f2f9e1c41faa1275161ed2
+config-catalog.md: a059159aae690330c55971bc49d62fcb1b030660
+config-catalog.zh.md: 9a0742ec8af10db90d0a2aad146c0cbec5a1a8a2
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index e1d0374afa..a059159aae 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -623,7 +623,7 @@ Source: [`packages/support/invariants/src/index.ts:15`](../packages/support/inva
 Requires: `agents`
 
 ```ts config-catalog
-/** JSON-RPC deployment config plus runtime-only test seams. */
+/** JSON-RPC deployment config plus runtime-only test hooks. */
 export interface JsonRpcConfig {
   /** Report max-token turn/subagent termination as a successful SDK result. */
   maxTokensAsSuccess?: boolean
@@ -1515,7 +1515,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/skill/skill/src/index.ts:265`](../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:266`](../packages/skill/skill/src/index.ts)
 
 ## `@deepseek-ai/dsh-skill-local`
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 93ca0a02b0..9a0742ec8a 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -625,7 +625,7 @@ export interface Config {
 需要：`agents`
 
 ```ts config-catalog
-/** JSON-RPC deployment config plus runtime-only test seams. */
+/** JSON-RPC deployment config plus runtime-only test hooks. */
 export interface JsonRpcConfig {
   /** Report max-token turn/subagent termination as a successful SDK result. */
   maxTokensAsSuccess?: boolean
@@ -1517,7 +1517,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/skill/skill/src/index.ts:265`](../packages/skill/skill/src/index.ts)
+来源：[`packages/skill/skill/src/index.ts:266`](../packages/skill/skill/src/index.ts)
 
 ## `@deepseek-ai/dsh-skill-local`
 
diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml
index 98b5a7fe23..aa582c2bb1 100644
--- a/docs/cookbook/adding-a-package.i18n.yaml
+++ b/docs/cookbook/adding-a-package.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/adding-a-package.md
-adding-a-package.md: 8ab603ea7b235bd2a582c9232afaca281a969448
-adding-a-package.zh.md: 400bd080b04ff5791393b56e67c1e3b9ade987de
+adding-a-package.md: 79e8604a47a4bdbb7e2912990a8b1c8be300b3b0
+adding-a-package.zh.md: 5fcdf03f52dfdfe375aeb2b6fd41e50ee406d043
diff --git a/docs/cookbook/adding-a-package.md b/docs/cookbook/adding-a-package.md
index 8ab603ea7b..79e8604a47 100644
--- a/docs/cookbook/adding-a-package.md
+++ b/docs/cookbook/adding-a-package.md
@@ -40,7 +40,7 @@ Covered automatically by globs or package-manifest discovery — no edits needed
 
 ## 3. Decide the package topology
 
-For a swappable capability, split interface / implementation / consumer into separate packages (see docs/architecture.md § "Capability seams" — the bash trio is the template). A single-purpose plugin stays one package.
+For a swappable capability, separate Service Definition / Service provider / Consumer roles into packages when they evolve independently (see docs/architecture.md § "Capability seams" — the bash trio is the template). A single-purpose plugin stays one package.
 
 ## 4. Write the package README
 
diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md
index 400bd080b0..5fcdf03f52 100644
--- a/docs/cookbook/adding-a-package.zh.md
+++ b/docs/cookbook/adding-a-package.zh.md
@@ -40,7 +40,7 @@ package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-c
 
 ## 3. 确定包拓扑
 
-对于可替换的能力，将接口、实现、消费方拆分为独立的包（见 docs/architecture.md § "Capability seams"——bash 三组件是模板）。单一用途的插件保持为一个包。
+对于可替换的能力，当 Service Definition／Service provider／Consumer 角色需要独立演进时，将它们拆分到不同包中（见 docs/architecture.md § "Capability seams"——bash 三组件是模板）。单一用途的插件保持为一个包。
 
 ## 4. 编写包 README
 
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index c053132c54..0509a67549 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/extension-cookbook.md
-extension-cookbook.md: e04f6ffcf9a32ba3ee7344db18cad113b347c667
-extension-cookbook.zh.md: 83521cd348c68ba6f20f5beecfbcde51b0f2fb02
+extension-cookbook.md: 025a1b6ecd11593b5d6be9d0f64e57ac8b5e3139
+extension-cookbook.zh.md: f838a281fabdba473b72b27f7b14274d9aa97528
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index e04f6ffcf9..025a1b6ecd 100644
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -2,7 +2,7 @@
 
 English | [中文](extension-cookbook.zh.md)
 
-Reference shapes for the harness extension surface. The snippets omit imports and helper implementations and are not copy-paste-complete. For concrete authoring paths, see the [package checklist](adding-a-package.md), [first-tool tutorial](../user/develop/basic/tool.md), [tool reference](adding-a-tool.md), and [LLM adapter guide](adding-an-llm-adapter.md); the [architecture](../architecture.md) owns the system and extension-seam map.
+Reference shapes for the harness extension surface. The snippets omit imports and helper implementations and are not copy-paste-complete. For concrete authoring paths, see the [package checklist](adding-a-package.md), [first-tool tutorial](../user/develop/basic/tool.md), [tool reference](adding-a-tool.md), and [LLM adapter guide](adding-an-llm-adapter.md); the [architecture](../architecture.md) owns the system and extension-point map.
 
 ## A tool plugin
 
@@ -10,7 +10,7 @@ A tool registers on `ctx.tools`. The annotated `defineTool` example (typed `exec
 
 ## A hook plugin (permission-gate example)
 
-This permission gate is one example of a hook plugin. It returns a typed decision from the `tools/pre-execute` gate to allow or deny a call; sandbox, permission, and plan-mode plugins can use this seam. Hook plugins can intercept other seams and are not inherently permission gates. A "native hook" is an ordinary Cordis plugin on an interception seam; it needs no external protocol.
+This permission gate is one example of a hook plugin. It returns a typed decision from the `tools/pre-execute` gate to allow or deny a call; sandbox, permission, and plan-mode plugins can use this extension point. Hook plugins can intercept other extension points and are not inherently permission gates. A "native hook" is an ordinary Cordis plugin on an interception point; it needs no external protocol.
 
 ```ts
 import type { Context } from 'cordis'
@@ -94,13 +94,13 @@ Runnable leaves load their plugin trees from `examples/*/cordis.yml`; the root `
 
 ## The feature → mechanism map
 
-Every product feature maps to a listener on a documented extension seam — the microkernel claim made checkable ([microkernel Agent Note](../../.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)). No row modifies the loop.
+Every product feature maps to a listener on a documented extension point — the microkernel claim made checkable ([microkernel Agent Note](../../.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)). No row modifies the loop.
 
 `system-prompt/assemble` is an expert cooperative whole-assembly transform: its returned assembly is authoritative, so listener authors own preserving active Code Mode and structured-output protocol contributions. Prefer `ctx.tools.restrict()` for tool filtering that must stay aligned across presentation, lookup, and execution.
 
 | Product feature | Plugin mechanism |
 |---|---|
-| Hook system (user + project level) | listeners on `agent/session-start`, `agent/pre-step`, `agent/request`, `tools/pre-execute`, `tools/post-execute`, and `agent/turn-stopping`; the waterfall seams return typed decisions, while `agent/turn-stopping` may steer another step; the `dsh-hooks-claude` / `dsh-hooks-codex` bridges map hook config files onto these seams |
+| Hook system (user + project level) | listeners on `agent/session-start`, `agent/pre-step`, `agent/request`, `tools/pre-execute`, `tools/post-execute`, and `agent/turn-stopping`; the waterfalls return typed decisions, while `agent/turn-stopping` may steer another step; the `dsh-hooks-claude` / `dsh-hooks-codex` bridges map hook config files onto these extension points |
 | `/goal` | `ctx.goals` owns durable state, `dsh-goal-session` schedules same-session rounds through the public `Agent`, and separate command/tool producers expose human/model control |
 | `/loop` | on the `turn/end` session event, `followup()` the next iteration; or force-continue |
 | Dynamic workflow | `ctx.workflows` + the worker-thread engine + the `workflow` tool; structured in-process children enforce output with scoped prompt/tool registrations, a monotonic tool guard, final `tools/result` commit (including enclosing `run_code`), and the structured-output execution's monotonic `concludeTurn()` marker |
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index 83521cd348..f838a281fa 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -2,7 +2,7 @@
 
 [English](extension-cookbook.md) | 中文
 
-harness 扩展表面的参考形态。代码片段省略了 import 和辅助实现，无法直接复制运行。具体编写路径见[包检查清单](adding-a-package.md)、[第一个工具教程](../user/develop/basic/tool.md)、[工具参考](adding-a-tool.md)和 [LLM（大语言模型）适配器指南](adding-an-llm-adapter.md)；系统与扩展 seam 映射由[架构文档](../architecture.md)负责。
+harness 扩展表面的参考形态。代码片段省略了 import 和辅助实现，无法直接复制运行。具体编写路径见[包检查清单](adding-a-package.md)、[第一个工具教程](../user/develop/basic/tool.md)、[工具参考](adding-a-tool.md)和 [LLM（大语言模型）适配器指南](adding-an-llm-adapter.md)；系统与扩展点映射由[架构文档](../architecture.md)负责。
 
 ## 工具插件
 
@@ -10,7 +10,7 @@ harness 扩展表面的参考形态。代码片段省略了 import 和辅助实
 
 ## 钩子插件（以权限门禁为例）
 
-这个权限门禁是钩子插件的一个示例。它从 `tools/pre-execute` 门禁返回一个类型化的决策，用于允许或拒绝一次调用；沙箱、权限和 plan-mode 插件都可以使用该 seam。钩子插件也可以拦截其他 seam，本身并不等同于权限门禁。「原生钩子」是在拦截 seam 上运行的普通 Cordis 插件，不需要外部协议。
+这个权限门禁是钩子插件的一个示例。它从 `tools/pre-execute` 门禁返回一个类型化的决策，用于允许或拒绝一次调用；沙箱、权限和 plan-mode 插件都可以使用该扩展点。钩子插件也可以拦截其他扩展点，本身并不等同于权限门禁。「原生钩子」是在拦截点上运行的普通 Cordis 插件，不需要外部协议。
 
 ```ts
 import type { Context } from 'cordis'
@@ -94,13 +94,13 @@ export function apply(ctx: Context) {
 
 ## 功能→机制映射
 
-每个产品功能都映射到一个文档化扩展 seam 上的监听器——微内核声明由此可验证（[微内核 Agent Note](../../.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)）。没有任何一行修改循环本身。
+每个产品功能都映射到一个文档化扩展点上的监听器——微内核声明由此可验证（[微内核 Agent Note](../../.agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)）。没有任何一行修改循环本身。
 
 `system-prompt/assemble` 是一个专家协作式的整体装配变换：其返回的装配结果具有权威性，因此监听器作者有责任保留活跃的 Code Mode 和结构化输出协议的贡献。对于需要在展示、查找和执行之间保持对齐的工具过滤，优先使用 `ctx.tools.restrict()`。
 
 | 产品功能 | 插件机制 |
 |---|---|
-| 钩子系统（用户级 + 项目级） | `agent/session-start`、`agent/pre-step`、`agent/request`、`tools/pre-execute`、`tools/post-execute` 和 `agent/turn-stopping` 上的监听器；waterfall seam 返回类型化决策，`agent/turn-stopping` 则可通过 steering（中途引导）触发下一步；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些 seam 上 |
+| 钩子系统（用户级 + 项目级） | `agent/session-start`、`agent/pre-step`、`agent/request`、`tools/pre-execute`、`tools/post-execute` 和 `agent/turn-stopping` 上的监听器；waterfall 返回类型化决策，`agent/turn-stopping` 则可通过 steering（中途引导）触发下一步；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些扩展点上 |
 | `/goal` | `ctx.goals` 管理持久状态，`dsh-goal-session` 通过公共 `Agent` 调度同会话 Round，独立的命令/工具生产方分别提供人类/模型控制 |
 | `/loop` | 在 `turn/end` 会话事件上 `followup()` 下一次迭代；或强制继续 |
 | 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的提示词/工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code`）和结构化输出执行的单调 `concludeTurn()` 标记来强制输出 |
diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml
index 8f27720c45..68f62583c2 100644
--- a/docs/defensive-patterns.i18n.yaml
+++ b/docs/defensive-patterns.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 docs/defensive-patterns.md
-defensive-patterns.md: 6dc1708f0b9bbcb00ad4774006d6d60059accf6a
-defensive-patterns.zh.md: 587d09a812857e6cf61f64bfd0e17e3386d1a772
+defensive-patterns.md: afb462e120892eafe676d8b7feef273c2d0e42df
+defensive-patterns.zh.md: ab5f689d47f89b6930b749824c69325490bd4586
diff --git a/docs/defensive-patterns.md b/docs/defensive-patterns.md
index 6dc1708f0b..afb462e120 100644
--- a/docs/defensive-patterns.md
+++ b/docs/defensive-patterns.md
@@ -8,9 +8,9 @@ Hard-won bug-class rules: each pattern below is a class of defect that actually
 
 A result can be several things at once — a process can time out AND exit 0 because it trapped the signal. Surface each independent fact (`timedOut`, `signal`, `exitCode`) on its own; never nest one flag's report inside another's branch, or a caller reads a cut-short run as a clean success.
 
-## Honor cross-seam contracts on BOTH sides
+## Honor public contracts on BOTH sides
 
-When an implementation boundary receives several representations of one outcome, normalize them before crossing the public seam. `LlmAdapter.stream()` implementations may throw or emit `finish {kind:'error'|'aborted'}`, but `LlmService.stream()` exposes model-request failures only as terminal finish chunks; middleware and consumer defects remain thrown. This keeps consumers from guessing whether a caught exception came from the provider, a wrapper, chunk logging, or their own assembly. Document the normalized contract where the type is defined; exercise every source form through the real consumer.
+When an implementation boundary receives several representations of one outcome, normalize them before crossing the public contract. `LlmAdapter.stream()` implementations may throw or emit `finish {kind:'error'|'aborted'}`, but `LlmService.stream()` exposes model-request failures only as terminal finish chunks; middleware and consumer defects remain thrown. This keeps consumers from guessing whether a caught exception came from the provider, a wrapper, chunk logging, or their own assembly. Document the normalized contract where the type is defined; exercise every source form through the real consumer.
 
 ## Async state is not synchronous state
 
diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md
index 587d09a812..ab5f689d47 100644
--- a/docs/defensive-patterns.zh.md
+++ b/docs/defensive-patterns.zh.md
@@ -8,13 +8,13 @@
 
 一个结果可以同时具有多种性质：进程可能已经超时，却仍以退出码 0 结束，因为它捕获了终止信号。每个独立事实（`timedOut`、`signal`、`exitCode`）都应单独上报；切勿把一个标志的上报嵌套在另一个标志的分支中，否则调用方可能把提前终止的运行误判为正常成功。
 
-## 跨 seam 约定两侧都要遵守
+## 公共约定两侧都要遵守
 
-当一个实现边界接收到同一结果的多种表示时，应在跨越公共 seam 前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止型 finish 分片暴露模型请求失败；middleware 缺陷与消费方缺陷仍会以异常形式抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化后的约定；通过真实消费方覆盖每种来源形式。
+当一个实现边界接收到同一结果的多种表示时，应在跨越公共约定前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmService.stream()` 只会通过终止 finish chunk 暴露模型请求失败；middleware 与消费方缺陷仍会抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、chunk 日志记录还是自身组装逻辑。请在类型定义处记录规范化约定；通过真实消费方覆盖每种来源形式。
 
 ## 异步状态不是同步状态
 
-`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent（智能体）下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。
+`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent 下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。
 
 ## Dispose 必须达到完全停稳，而不仅仅是请求停止
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 8aaa444853..788069e02d 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: 628750959e9c165006e221655cacb2de2dfcf637
-event-producer-consumer.zh.md: f09d8dc0b877c2c1d167b1aaad391bfe524828ed
+event-producer-consumer.md: d5f6674a5e9355f6f2c3fac23a45fcda180b3a0f
+event-producer-consumer.zh.md: 7568e852c891e6c9556486899fe1bdcd3053cb07
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 628750959e..d5f6674a5e 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -36,7 +36,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
-| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:283`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
+| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:284`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), `server`, [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:136`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index f09d8dc0b8..7568e852c8 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -38,7 +38,7 @@
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/index.ts:170`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/index.ts:157`](../packages/settings/settings/src/index.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
-| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:283`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
+| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:284`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:162`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), `server`, [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:136`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:142`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml
index b9dd5915c0..1dfb89b07f 100644
--- a/docs/glossary.i18n.yaml
+++ b/docs/glossary.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 docs/glossary.md
-glossary.md: acb093b097da62c92e3ade07f2dcb454eee576d2
-glossary.zh.md: ddf76edb1fd7e810badb68fadc0e3c67f2bc2b58
+glossary.md: d556e760dd2f07ab640aafca06b2757b47935406
+glossary.zh.md: d6a8e423ff2a6324ce0cdd65dd3edde573fac5b1
diff --git a/docs/glossary.md b/docs/glossary.md
index acb093b097..d556e760dd 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -6,7 +6,7 @@ Domain vocabulary for the DeepSeek Harness SDK uses one canonical term per conce
 
 ## capability-seam
 
-- **seam** — a *swappable capability* packaged as a trio: a **Service Definition** (the Cordis `Service` that owns its `ctx.<key>` and vocabulary types — an abstract class such as `BashExecutor`, or a concrete registry such as `WebService`, never a TypeScript `interface`), one or more **Service providers** (the implementation plugins that register a backend), and a **Consumer** (the model- or plugin-facing surface that injects the service). `packages/bash` is the canonical example: `dsh-bash` (Service Definition), `dsh-bash-local` / `dsh-bash-sandbox` (providers), `dsh-tool-bash` (consumer). The seam is all three together; the interface package alone is the *Service Definition*, one member — calling it "the seam" is the misuse this entry names. Fold roles only when they are genuinely one concern (`dsh-llm` folds the Service Definition and consumer); never split preemptively.
+- **seam** — a *swappable capability* with three roles: a **Service Definition** (the Cordis `Service` that owns its `ctx.<key>` and vocabulary types — an abstract class such as `BashExecutor`, or a concrete registry such as `WebService`, never a TypeScript `interface`), one or more **Service providers**, and one or more **Consumers** that inject the service. `packages/bash` is the canonical example: `dsh-bash` (Service Definition), `dsh-bash-local` / `dsh-bash-sandbox` (providers), and `dsh-tool-bash` (Consumer). Roles normally occupy separate packages when they evolve independently, but a package may own multiple roles when they are one concern (`dsh-llm` owns its Service Definition and Consumer). The seam is the complete capability, never one role; reserve the term for that meaning and name a constituent by its role, class, service, contract, or extension point.
 
 ## agent-scope
 
diff --git a/docs/glossary.zh.md b/docs/glossary.zh.md
index ddf76edb1f..d6a8e423ff 100644
--- a/docs/glossary.zh.md
+++ b/docs/glossary.zh.md
@@ -6,7 +6,7 @@ DeepSeek Harness SDK 的领域词汇为每个概念规定一个规范术语。
 
 ## capability-seam
 
-- **seam**：一种*可替换能力*，以三者组合的形式打包：**Service Definition**（拥有自身 `ctx.<key>` 和词汇类型的 Cordis `Service`——可以是 `BashExecutor` 这样的抽象类，也可以是 `WebService` 这样的具体注册表，从不是 TypeScript `interface`）、一个或多个 **Service provider**（注册后端的实现插件）以及 **Consumer**（注入该服务、面向模型或插件的表面）。`packages/bash` 是规范范例：`dsh-bash`（Service Definition）、`dsh-bash-local` / `dsh-bash-sandbox`（提供方）、`dsh-tool-bash`（消费方）。seam 是三者整体；接口包本身只是 *Service Definition*，是其中一个成员——把它称为「seam」正是本条目指出的误用。只有在角色确实属于同一个关注点时才合并角色（`dsh-llm` 合并 Service Definition 和消费方）；永远不要预防性地拆分。
+- **seam**：一种包含三种角色的*可替换能力*：**Service Definition**（拥有自身 `ctx.<key>` 和词汇类型的 Cordis `Service`——可以是 `BashExecutor` 这样的抽象类，也可以是 `WebService` 这样的具体注册表，从不是 TypeScript `interface`）、一个或多个 **Service provider**，以及一个或多个注入该服务的 **Consumer**。`packages/bash` 是规范范例：`dsh-bash`（Service Definition）、`dsh-bash-local` / `dsh-bash-sandbox`（提供方），以及 `dsh-tool-bash`（Consumer）。角色需要独立演进时通常位于不同包，但属于同一关注点时，一个包也可以承担多个角色（`dsh-llm` 同时承担 Service Definition 和 Consumer）。seam 是完整能力，绝不是其中一个角色；该术语仅保留此义，能力成员应按其角色、类、服务、约定或扩展点命名。
 
 ## agent-scope
 
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 4e49ef9694..51ec3673a6 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -55,7 +55,7 @@
 | Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |
 | schema | schema | | | |
 | schema DSL | schema DSL | | | |
-| seam | seam | | 接缝 | 一个可替换能力的三包整体（Service Definition / Service provider 实现 / Consumer），以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface，且不能单独称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |
+| seam | seam | | 接缝 | 一个可替换能力的整体，包含 Service Definition / Service provider / Consumer 三种角色；角色需要独立演化时才拆包，也可由同一包承担多个角色。以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |
 | skill | skill | skill（技能） | | |
 | slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |
 | spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |
@@ -84,7 +84,7 @@
 | cancel | 取消 | | | |
 | canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |
 | capability | 能力 | | | 必须与 `feature` → `功能` 区分 |
-| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |
+| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库 Service Definition、Service provider 与 Consumer 三种角色组成完整可替换能力的命名架构概念；普通 `seam` 仍按其词条处理 |
 | feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |
 | feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |
 | checkpoint | 检查点 | | | |
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index 06e426aa5c..f4aece8a52 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -91,7 +91,7 @@ A lower-priority rule may refine but never override a higher-priority requiremen
 - Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.
 
 #### When translating into Chinese
-- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: "three-package seam" → "由三个包构成的 seam", not "三包 seam". Do not add classifiers to code, identifiers, versions, units, or fixed names.
+- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: "three-role capability seam" → "包含三种角色的能力 seam", not "三角色 seam". Do not add classifiers to code, identifiers, versions, units, or fixed names.
 
 ### Punctuation
 
diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml
index 313b07ed56..2379b7d25b 100644
--- a/docs/subsystems/README.i18n.yaml
+++ b/docs/subsystems/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 docs/subsystems/README.md
-README.md: 94e935998e39d4209476a8c62eb99fed0e0ce317
-README.zh.md: 0f4a4c65797cf75acc6f937e8e8beb5fcd641652
+README.md: 096fd7de4d2644dac664fac940b6487052115258
+README.zh.md: 6b6758db8f7118a09f6b0998231d3944f44f5052
diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md
index 94e935998e..096fd7de4d 100644
--- a/docs/subsystems/README.md
+++ b/docs/subsystems/README.md
@@ -7,12 +7,12 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | Page | Owns |
 |---|---|
 | [core.md](core.md) | the `packages/core` control spine: the package-by-package loop map, agent creation and ownership (`AgentHandle`), the `Agent` handle with its delivery/cancellation/interception contracts, and the repo-wide type patterns (`…Map → derived-union`, branded ids) |
-| [llm-streaming.md](llm-streaming.md) | the `packages/llm` conversation vocabulary — `Message`/`ContentBlock`, the assembled model request, the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
+| [llm-streaming.md](llm-streaming.md) | the `packages/llm` conversation vocabulary — `Message`/`ContentBlock`, the assembled model request, the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` provider contract |
 | [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
 | [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
-| [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API seams |
+| [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, TypeRT registries, and the Host Gateway/Client API boundaries |
 | [goal.md](goal.md) | persisted goal identity, lifecycle snapshots, activation, change records, and round attribution |
-| [commands.md](commands.md) | the human-command seam: definitions, adapter discovery, direct invocation, results, and parsing views |
+| [commands.md](commands.md) | the human-command registry service: definitions, adapter discovery, direct invocation, results, and parsing views |
 | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events |
 | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
 | [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits |
@@ -42,10 +42,10 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures
 | [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
 | [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
 | [http-server.md](http-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the claimable fallback seat, index taps |
-| [storage.md](storage.md) | the storage subsystem: the backend seam (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
+| [storage.md](storage.md) | the storage subsystem: the backend contract (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
 | [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
 | [client-modules.md](client-modules.md) | the web plugin table: `dshClient` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
 | [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
-| [telemetry.md](telemetry.md) | the outbound reporting seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
+| [telemetry.md](telemetry.md) | the session-telemetry capability seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, the `telemetry/record` redact waterfall |
 
 > Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated **Cordis surface** section.
diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md
index 0f4a4c6579..6b6758db8f 100644
--- a/docs/subsystems/README.zh.md
+++ b/docs/subsystems/README.zh.md
@@ -7,12 +7,12 @@
 | 页面 | 负责内容 |
 |---|---|
 | [core.md](core.md) | `packages/core` 控制主干：逐包循环地图、agent 创建与所有权（`AgentHandle`）、`Agent` 句柄及其投递/取消/拦截约定，以及全仓通用类型模式（`…Map → 派生联合`、品牌化 id） |
-| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器约定（adapter contract）、`BlockAssembler`、`LlmAdapter` seam |
+| [llm-streaming.md](llm-streaming.md) | `packages/llm` 的对话词汇——`Message`/`ContentBlock`、组装完成的模型请求、`StreamChunk` 协议格式（wire format）+ 适配器约定（adapter contract）、`BlockAssembler`、`LlmAdapter` 提供方约定 |
 | [token-meter.md](token-meter.md) | 不可变的标量与位置回放度量，附带已消费日志修订号 |
 | [scope.md](scope.md) | 作用域注册标识、dispatch 载体，以及拥有的 `Scope` 上下文 |
-| [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API seam |
+| [typert.md](typert.md) | 远程调用描述符、lookup/Context 声明、TypeRT 注册表，以及 Host Gateway/Client API 边界 |
 | [goal.md](goal.md) | 持久 goal 标识、生命周期快照、激活、变更记录与 Round 归属 |
-| [commands.md](commands.md) | 人类命令 seam：定义、适配器发现、直接调用、结果与解析视图 |
+| [commands.md](commands.md) | 人类命令注册表服务：定义、适配器发现、直接调用、结果与解析视图 |
 | [session.md](session.md) | 完整的 `SessionEventMap` 变体目录、`TurnTrigger`/`TurnEndReason`、`deriveMessages()`、执行封闭与独立事件 |
 | [persistence.md](persistence.md) | 持久性 seam：`SessionPersistence`、JSONL + SQLite 后端、`session/flush`、崩溃恢复、`SessionHeader` |
 | [settings.md](settings.md) | 用户设置 seam：`SettingsNamespace` 注册、分层解析（默认值 → 组合 `base` → 用户文档）、owner scope、热提交 |
@@ -42,10 +42,10 @@
 | [plan.md](plan.md) | 计划模式：仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 |
 | [invariants.md](invariants.md) | 运行时不变式注册表：选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件约定 |
 | [http-server.md](http-server.md) | HTTP 载体：`WebRouteKind`/`WebRoute`、匹配顺序、可认领的回退席位、index 转换 |
-| [storage.md](storage.md) | 存储子系统：后端 seam（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
+| [storage.md](storage.md) | 存储子系统：后端约定（`StorageBackend`）、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed` |
 | [workspace.md](workspace.md) | 工作区注册表：`Workspace`/`WorkspaceId`、注册与解析、与会话 `cwd` 的关系 |
 | [client-modules.md](client-modules.md) | Web 插件表：`dshClient` 声明、`WebBootGraph` 线上组合、bundle 路由与 index 转换 |
 | [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 |
-| [telemetry.md](telemetry.md) | 对外上报 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 约定、`telemetry/record` 脱敏 waterfall |
+| [telemetry.md](telemetry.md) | 会话遥测能力 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 约定、`telemetry/record` 脱敏 waterfall |
 
 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis surface** 小节。
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index 077edaa10e..81dc8ce5d7 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.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 docs/subsystems/bash.md
-bash.md: 232443daf944237e0c9f8904a0ebeeab3d2de749
-bash.zh.md: aaabc8fb1de654096e01fcee1ad1d0f881d534e8
+bash.md: 1c60f261e292f389ea4afa3f962f698e0272007b
+bash.zh.md: 2533cbe10dc0a480d285f87e458cf5ee5fa12d75
diff --git a/docs/subsystems/bash.md b/docs/subsystems/bash.md
index 232443daf9..1c60f261e2 100644
--- a/docs/subsystems/bash.md
+++ b/docs/subsystems/bash.md
@@ -2,7 +2,7 @@
 
 English | [中文](bash.zh.md)
 
-The bash execution seam is split across interface ([dsh-bash](../../packages/bash/bash), `ctx.bash`), implementations ([dsh-bash-local](../../packages/bash/bash-local) and [dsh-bash-sandbox](../../packages/bash/bash-sandbox)), and consumer ([dsh-tool-bash](../../packages/bash/tool-bash), the `bash` schema). Generic background-task ids, ownership, and controls live in [tasks.md](tasks.md); this seam returns a task-free process handle. Raw process-group mechanics live behind the [subprocess seam](subprocess.md).
+The bash execution seam is split across a Service Definition ([dsh-bash](../../packages/bash/bash), `ctx.bash`), Service providers ([dsh-bash-local](../../packages/bash/bash-local) and [dsh-bash-sandbox](../../packages/bash/bash-sandbox)), and Consumer ([dsh-tool-bash](../../packages/bash/tool-bash), the `bash` schema). Generic background-task ids, ownership, and controls live in [tasks.md](tasks.md); this seam returns a task-free process handle. Raw process-group mechanics live behind the [subprocess seam](subprocess.md).
 
 Source: [`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.ts)
 
@@ -12,7 +12,7 @@ Source: [`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.t
 
 ## Request vs. spec: the `resolve()` split
 
-The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.bash.resolve(request)` between them — this is the repo's "explicit > implicit at package seams" rule made concrete: the reader of a `BashExecSpec` never wonders where the working directory or output budget came from.
+The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.bash.resolve(request)` between them — this is the repo's "explicit > implicit at package boundaries" rule made concrete: the reader of a `BashExecSpec` never wonders where the working directory or output budget came from.
 
 ```ts type-equiv
 /**
@@ -228,9 +228,9 @@ interface BashProcessRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxbash--bashexecutor"></a>
+<a id="ctxbash--bashexecutor-abstract-seam"></a>
 
-### `ctx.bash` — `BashExecutor`
+### `ctx.bash` — `BashExecutor` (abstract seam)
 
 Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index aaabc8fb1d..2533cbe10d 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -2,7 +2,7 @@
 
 [English](bash.md) | 中文
 
-bash 执行 seam 分为接口（[dsh-bash](../../packages/bash/bash)，`ctx.bash`）、实现（[dsh-bash-local](../../packages/bash/bash-local) 与 [dsh-bash-sandbox](../../packages/bash/bash-sandbox)）和消费方（[dsh-tool-bash](../../packages/bash/tool-bash)，即 `bash` schema）。通用后台任务的 task id、所有权与控制位于 [tasks.md](tasks.md)；本 seam 返回一个不含任务概念的进程句柄。原始进程组机制位于[进程管理器 seam](subprocess.md)之后。
+bash 执行 seam 分为 Service Definition（[dsh-bash](../../packages/bash/bash)，`ctx.bash`）、Service provider（[dsh-bash-local](../../packages/bash/bash-local) 与 [dsh-bash-sandbox](../../packages/bash/bash-sandbox)）和 Consumer（[dsh-tool-bash](../../packages/bash/tool-bash)，即 `bash` schema）。通用后台任务的 task id、所有权与控制位于 [tasks.md](tasks.md)；本 seam 返回一个不含任务概念的进程句柄。原始进程组机制位于[进程管理器 seam](subprocess.md)之后。
 
 源码：[`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.ts)
 
@@ -12,7 +12,7 @@ bash 执行 seam 分为接口（[dsh-bash](../../packages/bash/bash)，`ctx.bash
 
 ## 请求与规格：`resolve()` 拆分
 
-该 seam 将**面向模型/插件的请求**（`workdir`/`timeoutMs`/`stdoutMaxBytes` 可选，由配置或请求策略补全）与执行器实际使用的**完全解析后的 spec**（这些字段均为必填）分开。工具层在二者之间调用 `ctx.bash.resolve(request)`——这具体落实了仓库的「包 seam 上显式优于隐式」规则：`BashExecSpec` 的读者不必猜测工作目录或输出预算来自何处。
+该 seam 将**面向模型/插件的请求**（`workdir`/`timeoutMs`/`stdoutMaxBytes` 可选，由配置或请求策略补全）与执行器实际使用的**完全解析后的 spec**（这些字段均为必填）分开。工具层在二者之间调用 `ctx.bash.resolve(request)`——这具体落实了仓库的「包边界处显式优于隐式」规则：`BashExecSpec` 的读者不必猜测工作目录或输出预算来自何处。
 
 ```ts type-equiv
 /**
@@ -228,9 +228,9 @@ interface BashProcessRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxbash--bashexecutor"></a>
+<a id="ctxbash--bashexecutor-abstract-seam"></a>
 
-### `ctx.bash` — `BashExecutor`
+### `ctx.bash` — `BashExecutor` (abstract seam)
 
 Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index 5c6c47580d..cbe983a780 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.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 docs/subsystems/code-runtime.md
-code-runtime.md: 7185e99042101b2c3707f3d0ed80ae6c1f1f58f0
-code-runtime.zh.md: 2b5ebea4e0e43cebd695c20d59fa6e705e4ebcf2
+code-runtime.md: 8a767287414824e6f76659c02c47193522eb21c7
+code-runtime.zh.md: e6bb7cb93cb542dceb2c7e335162a03429d161e8
diff --git a/docs/subsystems/code-runtime.md b/docs/subsystems/code-runtime.md
index 7185e99042..8a76728741 100644
--- a/docs/subsystems/code-runtime.md
+++ b/docs/subsystems/code-runtime.md
@@ -2,13 +2,13 @@
 
 English | [中文](code-runtime.zh.md)
 
-The code-execution seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) whose interface ([dsh-code-runtime](../../packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread backend and tool-registry consumer are specified by the [Code Mode foundation](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) and [typed-return contract](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md).
+The code-execution seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) whose Service Definition ([dsh-code-runtime](../../packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread Service provider and tool-registry Consumer are specified by the [Code Mode foundation](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) and [typed-return contract](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md).
 
 Source: [`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)
 
 ## The run: request in, result out
 
-A `CodeRunRequest` carries **everything the runtime acts on** — per the "explicit > implicit at package seams" rule, defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`:
+A `CodeRunRequest` carries **everything the runtime acts on** — per the "explicit > implicit at package boundaries" rule, defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`:
 
 ```ts type-equiv
 /**
@@ -112,7 +112,7 @@ interface CodeBindingNamespace {
 ```
 
 ```ts type-equiv
-/** A lossless JSON value transferable across the dependency-light code-runtime seam. */
+/** A lossless JSON value transferable through the dependency-light Service Definition. */
 type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
 ```
 
@@ -168,17 +168,17 @@ interface CodeRunFailure {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcoderuntime--coderuntime"></a>
+<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
 
-### `ctx.codeRuntime` — `CodeRuntime`
+### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
 
-Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
+Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only Service Definition contract misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
 
 ```ts cordis-catalog
 /**
  * Execute one program against the request's bindings and capture what it
  * emitted. See the class doc for the resolution contract (error is a result
- * field; rejection means seam misuse only).
+ * field; rejection means Service Definition contract misuse only).
  * @param request - the program, its bindings, and the abort signal; the
  *   request carries everything the runtime acts on, with no hidden defaults.
  * @returns the run's outcome: completion value (when transferable), the
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index 2b5ebea4e0..e6bb7cb93c 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -2,7 +2,7 @@
 
 [English](code-runtime.md) | 中文
 
-代码执行 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：其接口（[dsh-code-runtime](../../packages/code-runtime/code-runtime)，`ctx.codeRuntime`）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread 后端与工具注册表消费方的约定见 [Code Mode 基础设计](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 和[类型化返回约定](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)。
+代码执行 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：其 Service Definition（[dsh-code-runtime](../../packages/code-runtime/code-runtime)，`ctx.codeRuntime`）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread Service provider 与工具注册表 Consumer 的约定见 [Code Mode 基础设计](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 和[类型化返回约定](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)。
 
 源码：[`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)
 
@@ -112,7 +112,7 @@ interface CodeBindingNamespace {
 ```
 
 ```ts type-equiv
-/** A lossless JSON value transferable across the dependency-light code-runtime seam. */
+/** A lossless JSON value transferable through the dependency-light Service Definition. */
 type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
 ```
 
@@ -168,17 +168,17 @@ interface CodeRunFailure {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcoderuntime--coderuntime"></a>
+<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
 
-### `ctx.codeRuntime` — `CodeRuntime`
+### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
 
-Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only seam misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
+Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only Service Definition contract misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
 
 ```ts cordis-catalog
 /**
  * Execute one program against the request's bindings and capture what it
  * emitted. See the class doc for the resolution contract (error is a result
- * field; rejection means seam misuse only).
+ * field; rejection means Service Definition contract misuse only).
  * @param request - the program, its bindings, and the abort signal; the
  *   request carries everything the runtime acts on, with no hidden defaults.
  * @returns the run's outcome: completion value (when transferable), the
diff --git a/docs/subsystems/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
index 3bd5420573..5bc05d2916 100644
--- a/docs/subsystems/commands.i18n.yaml
+++ b/docs/subsystems/commands.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 docs/subsystems/commands.md
-commands.md: c1ab6d9782f515321104d0cf4d9e037c6a68a18d
-commands.zh.md: 3b3d8def042b107c5098e76c511424f023975e77
+commands.md: c71c19b8a3f94ba468e6871d5658c4eca1c6276d
+commands.zh.md: 3f1df0e8aa40524160c8f770793b6064dd5988ae
diff --git a/docs/subsystems/commands.md b/docs/subsystems/commands.md
index c1ab6d9782..c71c19b8a3 100644
--- a/docs/subsystems/commands.md
+++ b/docs/subsystems/commands.md
@@ -2,13 +2,13 @@
 
 English | [中文](commands.zh.md)
 
-The human-command seam of [`dsh-commands`](../../packages/interaction/commands). Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The [command Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) owns dispatch and lifecycle rationale; the [package README](../../packages/interaction/commands/README.md) owns composition and limitations.
+The human-command registry service from [`dsh-commands`](../../packages/interaction/commands). Interactive adapters use it to discover and directly execute plugin-owned commands for an exact agent without creating a model message. The [command Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) owns dispatch and lifecycle rationale; the [package README](../../packages/interaction/commands/README.md) owns composition and limitations.
 
 Source: [`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
 
 ## Input metadata
 
-The seam exposes one optional unstructured-input hint. Command availability follows plugin composition: every adapter consuming the registry sees every effective definition.
+The service exposes one optional unstructured-input hint. Command availability follows plugin composition: every adapter consuming the registry sees every effective definition.
 
 ```ts type-equiv
 /** Immutable metadata for a command's optional unstructured input. */
diff --git a/docs/subsystems/commands.zh.md b/docs/subsystems/commands.zh.md
index 3b3d8def04..3f1df0e8aa 100644
--- a/docs/subsystems/commands.zh.md
+++ b/docs/subsystems/commands.zh.md
@@ -2,13 +2,13 @@
 
 [English](commands.md) | 中文
 
-[`dsh-commands`](../../packages/interaction/commands) 的用户命令 seam。交互式适配器用它发现插件拥有的命令，并针对确切的 agent（智能体）直接执行这些命令，而不创建模型消息。[命令 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) 负责分发与生命周期的决策依据；[包 README](../../packages/interaction/commands/README.md) 负责组合方式与限制。
+[`dsh-commands`](../../packages/interaction/commands) 提供的用户命令注册表服务。交互式适配器用它发现插件拥有的命令，并针对确切的 agent（智能体）直接执行这些命令，而不创建模型消息。[命令 Agent Note](../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) 负责分发与生命周期的决策依据；[包 README](../../packages/interaction/commands/README.md) 负责组合方式与限制。
 
 来源：[`packages/interaction/commands/src/index.ts`](../../packages/interaction/commands/src/index.ts)
 
 ## 输入元数据
 
-该 seam 公开一个可选的非结构化输入提示。命令的可用性由插件组合决定：每个消费注册表的适配器都会看到全部生效定义。
+该服务公开一个可选的非结构化输入提示。命令的可用性由插件组合决定：每个消费注册表的适配器都会看到全部生效定义。
 
 ```ts type-equiv
 /** Immutable metadata for a command's optional unstructured input. */
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 384a29469b..6445fa5d5c 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 47d115710a66bf1501e61806cbc68febbe4667ca
-compaction.zh.md: a89b218f16a44dbd184340631fa4f468f15f48f5
+compaction.md: 942cc740db6b7006952bfc33a39ea9826d673e61
+compaction.zh.md: c5b65a95f9c0db8b02912c68ef93edce2ceb7c43
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 47d115710a..942cc740db 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -2,7 +2,7 @@
 
 English | [中文](compaction.zh.md)
 
-The compaction seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) split like bash: interface ([dsh-compact](../../packages/compact/compact), `ctx.compact`), implementation (a backend such as [dsh-compact-basic](../../packages/compact/compact-basic)), and human consumer ([dsh-command-compact](../../packages/compact/command-compact)). Compaction is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A tokenizer- or template-based backend is a sibling package implementing the same interface. Unlike bash, the interface necessarily depends on `dsh-session` and `dsh-llm`: its verbs act on an agent-owned `Session`, and its durable summary event uses the `ContentBlock` vocabulary (see the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)).
+The compaction seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) split like bash: Service Definition ([dsh-compact](../../packages/compact/compact), `ctx.compact`), Service provider (a backend such as [dsh-compact-basic](../../packages/compact/compact-basic)), and human Consumer ([dsh-command-compact](../../packages/compact/command-compact)). Compaction is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A tokenizer- or template-based backend is a sibling package implementing the same interface. Unlike bash, the interface necessarily depends on `dsh-session` and `dsh-llm`: its verbs act on an agent-owned `Session`, and its durable summary event uses the `ContentBlock` vocabulary (see the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)).
 
 Source: [`packages/compact/compact/src/types.ts`](../../packages/compact/compact/src/types.ts)
 
@@ -81,7 +81,7 @@ type ManualCompactionErrorCode =
 
 Pressure compaction runs at serial `agent/pre-step` before request derivation. Once pressure or canonical overflow qualifies, compact-basic invokes optional [`ctx.toolResultPrune`](../../packages/compact/compact-tool-result-prune/README.md) before range selection, remeasures through `ctx.tokenMeter`, and can advance the surface without a summary. Failed-request recovery runs through `agent/request-error` after the failed step closes and returns a retry action only when the surface replacement generation advances, even if later summary work throws after pruning; cancellation still wins. Region boundaries preserve tool-call/result pairing but not whole turns, allowing early closed steps of one oversized turn to compact. `dsh-compact-basic` owns thresholds, retained-tail policy, overflow caps, and failure handling.
 
-The seam exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for those edge checks. Both validate current surface membership and reject missing seqs and orphan results; the [package contract](../../packages/compact/compact/README.md#tool-pairing-boundaries) owns their cache semantics.
+The Service Definition exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for those edge checks. Both validate current surface membership and reject missing seqs and orphan results; the [package contract](../../packages/compact/compact/README.md#tool-pairing-boundaries) owns their cache semantics.
 
 ## Tool-result pruning outcomes
 
@@ -121,9 +121,9 @@ interface PruneResult {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcompact--compactservice"></a>
+<a id="ctxcompact--compactservice-abstract-seam"></a>
 
-### `ctx.compact` — `CompactService`
+### `ctx.compact` — `CompactService` (abstract seam)
 
 Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index a89b218f16..c5b65a95f9 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -2,7 +2,7 @@
 
 [English](compaction.md) | 中文
 
-压缩 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)，与 bash 一样分为接口（[dsh-compact](../../packages/compact/compact)，`ctx.compact`）、实现（例如 [dsh-compact-basic](../../packages/compact/compact-basic) 后端）和面向用户的消费方（[dsh-command-compact](../../packages/compact/command-compact)）。压缩是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。基于 tokenizer 或模板的后端是实现同一接口的兄弟包。与 bash 不同，该接口必然依赖 `dsh-session` 和 `dsh-llm`：其动词作用于 agent 所有的 `Session`，而其持久摘要事件使用 `ContentBlock` 词汇（见[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)）。
+压缩 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)，与 bash 一样分为 Service Definition（[dsh-compact](../../packages/compact/compact)，`ctx.compact`）、Service provider（例如 [dsh-compact-basic](../../packages/compact/compact-basic) 后端）和面向用户的 Consumer（[dsh-command-compact](../../packages/compact/command-compact)）。压缩是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。基于 tokenizer 或模板的后端是实现同一接口的兄弟包。与 bash 不同，该接口必然依赖 `dsh-session` 和 `dsh-llm`：其动词作用于 agent 所有的 `Session`，而其持久摘要事件使用 `ContentBlock` 词汇（见[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)）。
 
 源码：[`packages/compact/compact/src/types.ts`](../../packages/compact/compact/src/types.ts)
 
@@ -81,7 +81,7 @@ type ManualCompactionErrorCode =
 
 压力压缩在串行 `agent/pre-step` 中运行，先于请求推导。一旦压力或规范化溢出满足条件，compact-basic 会在选择范围前调用可选的 [`ctx.toolResultPrune`](../../packages/compact/compact-tool-result-prune/README.md)，再通过 `ctx.tokenMeter` 重新测量，并且可以在不生成摘要的情况下推进 surface。失败请求的恢复在失败的步骤关闭后通过 `agent/request-error` 运行；仅当 surface replacement generation 前进时才返回重试动作，即便后续摘要工作在剪枝后抛异常亦如此；取消仍然优先。区域边界保持工具调用/结果配对，但不保持整个轮次，因此一个过大轮次中较早关闭的步骤可以被压缩。`dsh-compact-basic` 拥有阈值、保留尾部策略、溢出上限与失败处理。
 
-该 seam 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于这些边缘检查。两者都会验证当前 surface 成员关系，并拒绝缺失的 seq 与遗留结果；其缓存语义由[包约定](../../packages/compact/compact/README.md#tool-pairing-boundaries)规定。
+该 Service Definition 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于这些边缘检查。两者都会验证当前 surface 成员关系，并拒绝缺失的 seq 与遗留结果；其缓存语义由[包约定](../../packages/compact/compact/README.md#tool-pairing-boundaries)规定。
 
 ## 工具结果剪枝产出
 
@@ -121,9 +121,9 @@ interface PruneResult {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcompact--compactservice"></a>
+<a id="ctxcompact--compactservice-abstract-seam"></a>
 
-### `ctx.compact` — `CompactService`
+### `ctx.compact` — `CompactService` (abstract seam)
 
 Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
 
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 52df396cf2..2fb9c399be 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: b6ed77c1f06b903924db31547d57e07ea37129be
-core.zh.md: d4bee1240a7f66ee0f0dc2ff2a81edb20700d99e
+core.md: ec9a966164f2b706ae16341c628fb8f849eb7382
+core.zh.md: 4de168fd9714a935b4d9b08bbabd52492d1ea1cc
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index b6ed77c1f0..ec9a966164 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -17,7 +17,7 @@ A turn flows through the six packages in one loop: the driver in [`agent-loop`](
 | `agent-loop/` | The concrete driver implementing the public `Agent` contract (`ctx.agentLoop`) | this page |
 | `scope/` | The scoped-registration primitive the registries and loop build per-agent scoping on | [scope.md](scope.md) |
 
-`scope/` is the one non-service package: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) that sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle. `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; it runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent` — including when they need the initiating Agent — and never on `agent-loop` directly, so the loop stays swappable. The default composition that wires this spine into a runnable agent is [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md).
+`scope/` is the one non-service package: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) that sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle. `agent-loop` is the one concrete implementation of the public `Agent` contract and lives here because it is the harness's default product loop; it runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent` — including when they need the initiating Agent — and never on `agent-loop` directly, so the loop stays swappable. The default composition that wires this spine into a runnable agent is [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md).
 
 ## Creation and ownership
 
@@ -48,7 +48,7 @@ interface AgentHandle {
 
 `CreateAgentOptions` carries the shared identity and everything a fresh agent needs before publication: session metadata (`meta` — validated `cwd`, fork lineage, seed boundary, origin classification, delegation depth), an optional `seed` replay prefix for forks, per-agent `AgentOptions`, a creation-only cancellation `signal`, and `setup`. `ResumeAgentOptions` is the persisted-identity counterpart: `resumeSessionId`, `agentOptions`, `signal`, and `setup`. The `setup` callback (`AgentSetup`) composes the agent's scoped world while both ids are still unpublished — everything registered through `agentCtx` exists before `agent/created` and the first prompt assembly — and may return a synchronous commit invoked immediately before publication; a setup rejection, commit throw, or owner disposal rolls the transaction back without publishing either id.
 
-`AgentFactory` is the creation seam behind the registry: the loop registers its factory via `ctx.agents.setFactory()`, so consumers program against `ctx.agents` without depending on the concrete loop package. The exact `create`/`resume` signatures and their rollback contracts are in the [generated section](#ctxagents--agentregistry) below.
+`AgentFactory` is the creation contract behind the registry: the loop registers its factory via `ctx.agents.setFactory()`, so consumers program against `ctx.agents` without depending on the concrete loop package. The exact `create`/`resume` signatures and their rollback contracts are in the [generated section](#ctxagents--agentregistry) below.
 
 ## The agent handle
 
@@ -401,7 +401,7 @@ currentInitiator(): Agent | undefined
  * Read the initiating Agent and fail when no initiator boundary is active.
  * Use this for private helpers contractually below a driver, or for a
  * deployment-owned outbound request whose contract forbids agentless calls.
- * Generic or direct-call seams use optional lookup or explicit request fields.
+ * Generic or direct-call paths use optional lookup or explicit request fields.
  * @returns the inherited Agent.
  * @throws when no initiator is active or this service instance has been disposed.
  */
@@ -557,12 +557,12 @@ Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/i
 
 #### `agent/created` — emit
 
-A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
+A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving extension point. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
 
 ```ts cordis-catalog
 /**
  * A fully configured agent and live session were published. Setup is
- * composition-only; `agent/session-start` is the first startup-driving seam.
+ * composition-only; `agent/session-start` is the first startup-driving extension point.
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
@@ -718,14 +718,14 @@ Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/t
 
 #### `agent/request` — waterfall
 
-Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this seam cannot mutate messages.
+Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this waterfall cannot mutate messages.
 
 ```ts cordis-catalog
 /**
  * Replace the frozen call configuration. `await next()` yields the config
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
- * content must use logged channels; this seam cannot mutate messages.
+ * content must use logged channels; this waterfall cannot mutate messages.
  * @param payload.agent - the agent making the model call.
  * @param payload.turn - the open turn number.
  * @param payload.step - the step whose request this is.
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index d4bee1240a..4de168fd97 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -17,7 +17,7 @@
 | `agent-loop/` | 实现公开 `Agent` 约定的具体 driver（`ctx.agentLoop`） | 本页 |
 | `scope/` | 注册表与循环用于构建按 agent 作用域的注册原语 | [scope.md](scope.md) |
 
-`scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是 `agent` seam 的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
+`scope/` 是这里唯一的非服务包：一个零依赖库（`createScope`/`scopeOf`/`scopeTarget`），在模块图中位于 `session/` 与 `system-prompt/` 之下，正是为了让它们消费它而不形成环。`agent-loop` 是公开 `Agent` 约定的唯一具体实现，放在这里因为它是 harness 的默认产品循环；它在 `ctx.agents.withInitiator()` 内运行每个 driver。扩展插件依赖 `agent`——包括需要发起 Agent 时——而绝不直接依赖 `agent-loop`，因此循环保持可替换。把这条主干接成可运行 agent 的默认组合是 [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md)。
 
 <a id="creation-and-ownership"></a>
 
@@ -50,7 +50,7 @@ interface AgentHandle {
 
 `CreateAgentOptions` 携带共享标识以及新 agent 发布前所需的一切：会话元数据（`meta`——已校验的 `cwd`、fork 谱系、seed 边界、来源分类、委派深度）、fork 用的可选 `seed` 回放前缀、按 agent 的 `AgentOptions`、仅创建期有效的取消 `signal`，以及 `setup`。`ResumeAgentOptions` 是持久标识的对应物：`resumeSessionId`、`agentOptions`、`signal` 与 `setup`。`setup` 回调（`AgentSetup`）在两个 id 都尚未发布时组装 agent 的作用域世界——凡经 `agentCtx` 注册的内容都先于 `agent/created` 与第一次提示词组装存在——并可返回一个在发布前一刻调用的同步 commit；setup 拒绝、commit 抛出或所有者 dispose 都会回滚事务，两个 id 均不发布。
 
-`AgentFactory` 是注册表背后的创建 seam：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚约定见下方[生成区块](#ctxagents--agentregistry)。
+`AgentFactory` 是注册表背后的创建约定：循环经 `ctx.agents.setFactory()` 注册其工厂，因此消费方面向 `ctx.agents` 编程，无需依赖具体循环包。确切的 `create`/`resume` 签名及其回滚约定见下方[生成区块](#ctxagents--agentregistry)。
 
 <a id="the-agent-handle"></a>
 
@@ -409,7 +409,7 @@ currentInitiator(): Agent | undefined
  * Read the initiating Agent and fail when no initiator boundary is active.
  * Use this for private helpers contractually below a driver, or for a
  * deployment-owned outbound request whose contract forbids agentless calls.
- * Generic or direct-call seams use optional lookup or explicit request fields.
+ * Generic or direct-call paths use optional lookup or explicit request fields.
  * @returns the inherited Agent.
  * @throws when no initiator is active or this service instance has been disposed.
  */
@@ -565,12 +565,12 @@ Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/i
 
 #### `agent/created` — emit
 
-A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving seam. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
+A fully configured agent and live session were published. Setup is composition-only; `agent/session-start` is the first startup-driving extension point. Synchronous listener failure vetoes publication, while returned-promise rejection is reported. Detach requested during dispatch waits until every creation listener has observed the stable entry.
 
 ```ts cordis-catalog
 /**
  * A fully configured agent and live session were published. Setup is
- * composition-only; `agent/session-start` is the first startup-driving seam.
+ * composition-only; `agent/session-start` is the first startup-driving extension point.
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
@@ -726,14 +726,14 @@ Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/t
 
 #### `agent/request` — waterfall
 
-Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this seam cannot mutate messages.
+Replace the frozen call configuration. `await next()` yields the config the machine would use (agent options on the first request, the logged header afterwards); return a replacement to switch. Model-visible content must use logged channels; this waterfall cannot mutate messages.
 
 ```ts cordis-catalog
 /**
  * Replace the frozen call configuration. `await next()` yields the config
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
- * content must use logged channels; this seam cannot mutate messages.
+ * content must use logged channels; this waterfall cannot mutate messages.
  * @param payload.agent - the agent making the model call.
  * @param payload.turn - the open turn number.
  * @param payload.step - the step whose request this is.
diff --git a/docs/subsystems/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml
index 2ea649fe56..7e9e057c75 100644
--- a/docs/subsystems/credentials.i18n.yaml
+++ b/docs/subsystems/credentials.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 docs/subsystems/credentials.md
-credentials.md: 84b156e366b2f4d0aeaba11b1b8d005ff59ad11d
-credentials.zh.md: c12191529e4324aed57b0ec8870fdca5c4dcae8a
+credentials.md: 0bc2224ac039addc795d3806e8c85004f2bb84a7
+credentials.zh.md: f236b0b2daef85784308f10dbcfc67db84c42234
diff --git a/docs/subsystems/credentials.md b/docs/subsystems/credentials.md
index 84b156e366..0bc2224ac0 100644
--- a/docs/subsystems/credentials.md
+++ b/docs/subsystems/credentials.md
@@ -57,9 +57,9 @@ interface CredentialInfo {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcredentials--credentials"></a>
+<a id="ctxcredentials--credentials-abstract-seam"></a>
 
-### `ctx.credentials` — `Credentials`
+### `ctx.credentials` — `Credentials` (abstract seam)
 
 Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
 
diff --git a/docs/subsystems/credentials.zh.md b/docs/subsystems/credentials.zh.md
index c12191529e..f236b0b2da 100644
--- a/docs/subsystems/credentials.zh.md
+++ b/docs/subsystems/credentials.zh.md
@@ -57,9 +57,9 @@ interface CredentialInfo {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxcredentials--credentials"></a>
+<a id="ctxcredentials--credentials-abstract-seam"></a>
 
-### `ctx.credentials` — `Credentials`
+### `ctx.credentials` — `Credentials` (abstract seam)
 
 Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.
 
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 3b5987bfec..3dad767e63 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 6c89f6f88babf09b1cf0f6ac2b739b511568f18b
-filesystem.zh.md: 16be774c74d02894434467dc68e927fdba2e38c7
+filesystem.md: 6748ddc7f290b6714302223758587226647641e7
+filesystem.zh.md: 28535d3d9d40e92bb6d5b2b0995a535b42fd9a23
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 6c89f6f88b..6748ddc7f2 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -8,7 +8,7 @@ The model is **additive, not subtractive**: `ctx.fs` alone is a complete, uncons
 
 Provider source: [`packages/fs/fs/src/types.ts`](../../packages/fs/fs/src/types.ts) and [`packages/fs/fs/src/index.ts`](../../packages/fs/fs/src/index.ts). Policy source: [`packages/fs/fs-policy/src/types.ts`](../../packages/fs/fs-policy/src/types.ts). Read-rendering source: [`packages/fs/tool-fs/src/read-render.ts`](../../packages/fs/tool-fs/src/read-render.ts).
 
-## Target identity and metadata (provider seam)
+## Target identity and metadata (provider contract)
 
 Every operation resolves a user-supplied path to an opaque backend target first. Consumers may display `displayPath`, but must not parse `targetKey` (a branded opaque id) or assume it is a local absolute path.
 
@@ -111,7 +111,7 @@ interface FsDirEntry {
 }
 ```
 
-## Write and edit guards (provider seam)
+## Write and edit guards (provider contract)
 
 Both `writeText` and `editText` take their version guard OPTIONALLY: omit it for an unconditional (bare-provider) mutation, supply it to guard. `writeText`'s guard is an `FsWriteIntent` — `createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only when the target exists at the observed version, else `FS_STALE_VERSION`. Omitting `expected` unconditionally creates-or-overwrites. The union itself carries only the two guarded intents; "no guard" is expressed by omission, so write and edit share one symmetric `expected?` shape.
 
@@ -177,7 +177,7 @@ interface FsEditOutcome {
 }
 ```
 
-## The fs policy events (provider-seam vocabulary)
+## The fs policy events (provider contract vocabulary)
 
 `dsh-fs` owns three events the tool dispatches and the policy plugin listens for, so the emitter (`dsh-tool-fs`) and the listener (`dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
@@ -229,7 +229,7 @@ interface FileReadOutcome {
 
 Observed state is a `WeakMap<owner, Map<targetKey, { version }>>` held inside the `dsh-fs-policy` plugin. An entry exists **iff** the owner has read, written, OR edited that target (every success emits `fs/observed`), so its presence is the prior-observation record — there is no separate `hasRead` flag and no view distinction. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. A successful read/write/edit refreshes the recorded version for that owner; disposal drops everything (HMR safety).
 
-## Error taxonomy (provider seam)
+## Error taxonomy (provider contract)
 
 Filesystem failures use stable `FsErrorCode` strings carried by `FsError` (`HarnessError`). The tool registry preserves `{ name, code }` on error results, so retry, permission, and UI layers can branch without parsing text.
 
@@ -258,11 +258,11 @@ type FsErrorCode =
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise, and an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise, and an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem) below shows the exact signatures.
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -272,9 +272,9 @@ type FsErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxfs--filesystem"></a>
+<a id="ctxfs--filesystem-abstract-seam"></a>
 
-### `ctx.fs` — `FileSystem`
+### `ctx.fs` — `FileSystem` (abstract seam)
 
 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 16be774c74..28535d3d9d 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -8,7 +8,7 @@
 
 提供方源码：[`packages/fs/fs/src/types.ts`](../../packages/fs/fs/src/types.ts) 与 [`packages/fs/fs/src/index.ts`](../../packages/fs/fs/src/index.ts)。策略源码：[`packages/fs/fs-policy/src/types.ts`](../../packages/fs/fs-policy/src/types.ts)。读取渲染源码：[`packages/fs/tool-fs/src/read-render.ts`](../../packages/fs/tool-fs/src/read-render.ts)。
 
-## 目标标识与元数据（提供方 seam）
+## 目标标识与元数据（提供方约定）
 
 每个操作首先将用户提供的路径解析为不透明的后端目标。消费方可以显示 `displayPath`，但禁止解析 `targetKey`（一个品牌化的不透明 id），也不得假设它是本地绝对路径。
 
@@ -111,7 +111,7 @@ interface FsDirEntry {
 }
 ```
 
-## 写入与编辑守卫（提供方 seam）
+## 写入与编辑守卫（提供方约定）
 
 `writeText` 和 `editText` 的版本守卫都是可选的：省略守卫时执行无条件的裸提供方变更，提供守卫时则执行相应的条件检查。`writeText` 的守卫是 `FsWriteIntent`：`createIfAbsent` 在目标缺失时创建，目标已存在时以 `FS_NOT_OBSERVED` 拒绝；`replaceIfVersion` 仅在目标存在且版本匹配时替换，否则报 `FS_STALE_VERSION`。省略 `expected` 则无条件创建或覆盖。联合类型本身只包含两种有守卫的意图；「无守卫」通过省略表达，因此 write 和 edit 共享同一个对称的 `expected?` 形状。
 
@@ -177,7 +177,7 @@ interface FsEditOutcome {
 }
 ```
 
-## fs 策略事件（提供方 seam 词汇）
+## fs 策略事件（提供方约定词汇）
 
 `dsh-fs` 拥有三个事件，由工具分发、策略插件监听，使发射方（`dsh-tool-fs`）与监听方（`dsh-fs-policy`）共享词汇，而发射方无需依赖策略插件。它们只携带 `dsh-fs` 词汇加一个不透明的 `object` actor，不含面向模型的概念，也不含 agent/会话所有者结构。
 
@@ -229,7 +229,7 @@ interface FileReadOutcome {
 
 已观测状态是 `dsh-fs-policy` 插件内部持有的 `WeakMap<owner, Map<targetKey, { version }>>`。**当且仅当**所有者已读取、写入或编辑过该目标时（每次成功都 emit `fs/observed`），条目才存在，因此其存在本身就是先前观测的记录——没有单独的 `hasRead` 标志，也没有视图区分。所有者从事件 actor 推导（通常是 `exec.agent.session`），被视为不透明且从不读取。成功的 read/write/edit 会刷新该所有者对应的已记录版本；dispose（资源释放）时丢弃全部数据（HMR（热模块替换）安全）。
 
-## 错误分类体系（提供方 seam）
+## 错误分类体系（提供方约定）
 
 文件系统故障使用稳定的 `FsErrorCode` 字符串，由 `FsError`（`HarnessError`）携带。工具注册表在错误结果上保留 `{ name, code }`，使重试、权限和 UI 层可以按 code 分支而无需解析文本。
 
@@ -258,11 +258,11 @@ type FsErrorCode =
 
 ## 文件 IO 不设超时
 
-`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方 seam 也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的截止时间会成为无法兑现承诺的旋钮，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。两个参照 agent（Claude Code、Codex）出于同样原因不给文件 IO 计时；取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
+`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方约定也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的截止时间会成为无法兑现承诺的旋钮，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。两个参照 agent（Claude Code、Codex）出于同样原因不给文件 IO 计时；取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem) 展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -272,9 +272,9 @@ type FsErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxfs--filesystem"></a>
+<a id="ctxfs--filesystem-abstract-seam"></a>
 
-### `ctx.fs` — `FileSystem`
+### `ctx.fs` — `FileSystem` (abstract seam)
 
 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
 
diff --git a/docs/subsystems/invariants.i18n.yaml b/docs/subsystems/invariants.i18n.yaml
index 23364aacc1..2ff4b67060 100644
--- a/docs/subsystems/invariants.i18n.yaml
+++ b/docs/subsystems/invariants.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 docs/subsystems/invariants.md
-invariants.md: 184d982bb27ab3ff98f715f0751c8bfcc1d08bea
-invariants.zh.md: e79b1c90a1c6284691404411ad9fa8ce62ef7e5e
+invariants.md: ccf81f0252dd2db4eec666df6fab8c7d6a830f25
+invariants.zh.md: 046aa4a56d48fa0386fba3a51d850ab21ce5145d
diff --git a/docs/subsystems/invariants.md b/docs/subsystems/invariants.md
index 184d982bb2..ccf81f0252 100644
--- a/docs/subsystems/invariants.md
+++ b/docs/subsystems/invariants.md
@@ -2,7 +2,7 @@
 
 English | [中文](invariants.zh.md)
 
-[dsh-invariants](../../packages/support/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in [AGENTS.md](../../AGENTS.md#conventions); the seam design is owned by the [invariant-service Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md).
+[dsh-invariants](../../packages/support/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in [AGENTS.md](../../AGENTS.md#conventions); the registry design is owned by the [invariant-service Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md).
 
 Source: [`packages/support/invariants/src/index.ts`](../../packages/support/invariants/src/index.ts)
 
diff --git a/docs/subsystems/invariants.zh.md b/docs/subsystems/invariants.zh.md
index e79b1c90a1..046aa4a56d 100644
--- a/docs/subsystems/invariants.zh.md
+++ b/docs/subsystems/invariants.zh.md
@@ -2,7 +2,7 @@
 
 [English](invariants.md) | 中文
 
-[dsh-invariants](../../packages/support/invariants) 是面向包（package）自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；seam 设计由[不变式服务 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md)规定。
+[dsh-invariants](../../packages/support/invariants) 是面向包（package）自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；注册表设计由[不变式服务 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md)规定。
 
 源码：[`packages/support/invariants/src/index.ts`](../../packages/support/invariants/src/index.ts)
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index abb60661c8..1808f2d8e4 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: 37f2fcc51a8b899414927615a7c7750254fa9445
-llm-streaming.zh.md: f9dab459be1006c6ea894498b9a28b49e9ec7738
+llm-streaming.md: 0cfce7a06d1db73268e2457c4979d1b1ccc889b7
+llm-streaming.zh.md: 19541462805c50b0ed446a346523d20de91d0351
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index 37f2fcc51a..0cfce7a06d 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -621,9 +621,9 @@ interface LlmCallConfigAdapterDefaults {
 }
 ```
 
-## The seam
+## Service and provider contracts
 
-`LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmService.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#model-content).
+`LlmAdapter` is the provider contract: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerRetryPolicy()` is captured per route with normal defaults, while `providerInfo()` and asynchronous `listModels()` feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. One asynchronous `resolveModel()` query returns exact model identity plus optional correctness-sensitive context capacity, an adapter-configured `defaultMaxTokens`, and ordered model-owned reasoning ids with an optional deployment default; absent fields mean unavailable metadata or provider-owned behavior, not invalid catalog membership. The resolver receives optional cancellation and must settle promptly after abort. `LlmService.resolveModelInfo()` validates and detaches the aggregate. At the final adapter boundary, `resolveCallConfig()` materializes the output default only when `maxTokens` is absent and validates and materializes reasoning, so direct calls cannot bypass either configured behavior; direct dispatch captures one registration before awaiting that resolution. The agent loop instead uses `prepareCall()` to keep the same registration across model resolution, durable header logging, and dispatch, retain detached context metadata from that exact lookup, and report which config fields the adapter defaulted. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. AgentLoop observes a request attempt once the outer waterfall returns a stream handle; that limited boundary does not prove a lazy terminal adapter was constructed or began provider I/O. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#model-content).
 
 ```ts type-equiv
 /** One model call whose config and adapter registration were resolved together. */
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index f9dab459be..1954146280 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -629,9 +629,9 @@ interface LlmCallConfigAdapterDefaults {
 }
 ```
 
-## seam
+## 服务与提供方约定
 
-`LlmAdapter` 是提供方 seam：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmService.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#model-content)。
+`LlmAdapter` 是提供方约定：创建子类、实现 `stream()`，再用 `ctx.llm.registerAdapter(providers, adapter)` 注册一个适配器实例。`GenerateOptions.provider` 选择已注册适配器；`GenerateOptions.model` 会传给该适配器，无需在生命周期启动时注册。重复提供方路由会原子失败。可选的 `providerRetryPolicy()` 会按路由捕获并填入 normal 默认值，`providerInfo()` 与异步 `listModels()` 方法则为 `LlmService.listProviders()` / `listModels()` 提供分离的 selector 元数据。该目录仅供参考，不是请求白名单：适配器仍是权威，并可接受未列出的模型 id。单次异步 `resolveModel()` 查询返回确切模型身份，以及可选的对正确性敏感的上下文容量、适配器配置的 `defaultMaxTokens`、由模型持有的有序推理强度 ID 和部署默认值；字段缺失表示元数据不可用或保留提供方持有的行为，而不表示目录成员关系无效。解析器会接收可选的取消信号，并且必须在信号中止后迅速完成结算。`LlmService.resolveModelInfo()` 会校验聚合结果并返回分离值。在最终适配器边界，`resolveCallConfig()` 仅在 `maxTokens` 缺失时填入输出默认值，并校验和填入推理强度，因此直接调用也无法绕过任何一项已配置行为；直接分派会在等待解析前捕获一项适配器注册。agent loop 则使用 `prepareCall()`，使模型解析、请求头持久记录和分派全程使用同一项注册，保留来自同一次查询的分离上下文元数据，并报告适配器填入的配置字段。适配器查找发生在 `llm/stream` waterfall（瀑布式事件）的终端 continuation，因此 listener 可以在查找前短路调用，或路由一个可变的一次性请求。AgentLoop 在外层 waterfall 返回流句柄时观察到一次请求尝试；这个有限边界不能证明惰性终端适配器已构造完成或开始提供方 I/O。`block-start` / `block-end` 的 `index` 关联与 assembler 共同意味着适配器只需 emit 格式正确的分片——块重组不是每个适配器各自的问题。消费方 surface（`ctx.llm.stream()`）与 `llm/stream` waterfall 见 [architecture.md § 内容块与流式传输](../architecture.md#model-content)。
 
 ```ts type-equiv
 /** One model call whose config and adapter registration were resolved together. */
diff --git a/docs/subsystems/lsp.i18n.yaml b/docs/subsystems/lsp.i18n.yaml
index eb3a5e36ba..400274ceef 100644
--- a/docs/subsystems/lsp.i18n.yaml
+++ b/docs/subsystems/lsp.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 docs/subsystems/lsp.md
-lsp.md: 03d0ce2dbe246aadb6f6c9a702fa50e3e792eb09
-lsp.zh.md: d428f2b5f9568b231b0b50a13bd4a41f7ea81346
+lsp.md: f8fa2be3d79c0aff9b288f61bf64bbb91e327f1d
+lsp.zh.md: fc9214fa7b10c2dac2a6cd90e0c29776313653f4
diff --git a/docs/subsystems/lsp.md b/docs/subsystems/lsp.md
index 03d0ce2dbe..f8fa2be3d7 100644
--- a/docs/subsystems/lsp.md
+++ b/docs/subsystems/lsp.md
@@ -2,7 +2,7 @@
 
 English | [中文](lsp.zh.md)
 
-The LSP seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) exposing semantic code navigation on one `ctx.lsp` service, split across packages: interface ([dsh-lsp](../../packages/lsp/lsp), `ctx.lsp` + the provider registry), a generic implementation ([dsh-lsp-local](../../packages/lsp/lsp-local), a configured stdio language-server host), and consumer ([dsh-tool-lsp](../../packages/lsp/tool-lsp), the `lsp` tool schema). LSP is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A provider swap does not change how the model asks for navigation.
+The LSP seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) exposing semantic code navigation on one `ctx.lsp` service, split across packages: Service Definition ([dsh-lsp](../../packages/lsp/lsp), `ctx.lsp` + the provider registry), a generic Service provider ([dsh-lsp-local](../../packages/lsp/lsp-local), a configured stdio language-server host), and Consumer ([dsh-tool-lsp](../../packages/lsp/tool-lsp), the `lsp` tool schema). LSP is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A provider swap does not change how the model asks for navigation.
 
 Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
 
diff --git a/docs/subsystems/lsp.zh.md b/docs/subsystems/lsp.zh.md
index d428f2b5f9..fc9214fa7b 100644
--- a/docs/subsystems/lsp.zh.md
+++ b/docs/subsystems/lsp.zh.md
@@ -2,7 +2,7 @@
 
 [English](lsp.md) | 中文
 
-LSP seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)：它在单一 `ctx.lsp` 服务上公开语义代码导航，并拆分到多个包：接口（[dsh-lsp](../../packages/lsp/lsp)，`ctx.lsp` + 提供方注册表）、通用实现（[dsh-lsp-local](../../packages/lsp/lsp-local)，经过配置的 stdio 语言服务器宿主）和消费方（[dsh-tool-lsp](../../packages/lsp/tool-lsp)，即 `lsp` 工具 schema）。LSP 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换提供方不会改变模型请求导航的方式。
+LSP seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)：它在单一 `ctx.lsp` 服务上公开语义代码导航，并拆分到多个包：Service Definition（[dsh-lsp](../../packages/lsp/lsp)，`ctx.lsp` + 提供方注册表）、通用 Service provider（[dsh-lsp-local](../../packages/lsp/lsp-local)，经过配置的 stdio 语言服务器宿主）和 Consumer（[dsh-tool-lsp](../../packages/lsp/tool-lsp)，即 `lsp` 工具 schema）。LSP 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换提供方不会改变模型请求导航的方式。
 
 源文件：[`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
 
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index 1ee31d85d0..eb5478eef8 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: c8d8bba1650dd54b533e95a4ddd0a8f5a19bb0c6
-persistence.zh.md: b4440183bc56086739ac1e9fa6390e9287335986
+persistence.md: 991efe39a059e08cdf7904b473486b336cb2071c
+persistence.zh.md: 2391eeb2a751388b6aa139d0646b52fe5af04601
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index c8d8bba165..991efe39a0 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -213,9 +213,9 @@ Both implement the same abstract `SessionPersistence` (locate/create/append/prep
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionpersistence--sessionpersistence"></a>
+<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
 
-### `ctx.sessionPersistence` — `SessionPersistence`
+### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
 
 Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
 
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index b4440183bc..2391eeb2a7 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -213,9 +213,9 @@ interface SessionPersistenceSnapshot {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionpersistence--sessionpersistence"></a>
+<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
 
-### `ctx.sessionPersistence` — `SessionPersistence`
+### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
 
 Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
 
diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml
index efe9e376c6..2286bad3fd 100644
--- a/docs/subsystems/plan.i18n.yaml
+++ b/docs/subsystems/plan.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 docs/subsystems/plan.md
-plan.md: ee4b911050863765960ba46952ba923a7115e129
-plan.zh.md: 0481bdf76adf2f00fe18073fe8daa5ba172bbfe1
+plan.md: 29a2473c440b654422c4c563820efa72847a820a
+plan.zh.md: bcb327719102b90c1c7009d78cee0fa930cdc7a8
diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md
index ee4b911050..29a2473c44 100644
--- a/docs/subsystems/plan.md
+++ b/docs/subsystems/plan.md
@@ -14,7 +14,7 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/s
 
 Because every session event is turn-enclosed, a user selection is held as pending intent until the next step boundary — the next request derivation, in whichever turn it occurs (selection never forces continuation, so an intent recorded after a turn's final step lands in a later turn). `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
 
-The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception seam that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
+The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception point that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
 
 ## Configuration
 
diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md
index 0481bdf76a..bcb3277191 100644
--- a/docs/subsystems/plan.zh.md
+++ b/docs/subsystems/plan.zh.md
@@ -14,7 +14,7 @@
 
 由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到下一个步骤边界——即下一次请求派生，落在哪个轮次就在哪个轮次生效（选择绝不强制续行，因此在某轮最后一步之后记录的意图会在之后的轮次落地）。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。
 
-唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截 seam，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
+唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截点，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。
 
 ## 配置
 
diff --git a/docs/subsystems/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml
index ab7bbb6b07..a6f8fd2609 100644
--- a/docs/subsystems/sandbox.i18n.yaml
+++ b/docs/subsystems/sandbox.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 docs/subsystems/sandbox.md
-sandbox.md: b08eacbc040568fa40c681f65577b64afe53fbaa
-sandbox.zh.md: 1e5f7f55b4923f96ffb9263e9d0784f849fd4d13
+sandbox.md: dd960b3021dcdc87cfd36fd439cbec0a810dd736
+sandbox.zh.md: 23644bb43a131a0e3c8595187a6fc11e74682d9e
diff --git a/docs/subsystems/sandbox.md b/docs/subsystems/sandbox.md
index b08eacbc04..dd960b3021 100644
--- a/docs/subsystems/sandbox.md
+++ b/docs/subsystems/sandbox.md
@@ -155,9 +155,9 @@ Provider selection, probing, caching, and backend-specific enforcement reports b
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsandbox--sandboxprovider"></a>
+<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
 
-### `ctx.sandbox` — `SandboxProvider`
+### `ctx.sandbox` — `SandboxProvider` (abstract seam)
 
 Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
 
diff --git a/docs/subsystems/sandbox.zh.md b/docs/subsystems/sandbox.zh.md
index 1e5f7f55b4..23644bb43a 100644
--- a/docs/subsystems/sandbox.zh.md
+++ b/docs/subsystems/sandbox.zh.md
@@ -155,9 +155,9 @@ interface ConfinedArgv {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsandbox--sandboxprovider"></a>
+<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
 
-### `ctx.sandbox` — `SandboxProvider`
+### `ctx.sandbox` — `SandboxProvider` (abstract seam)
 
 Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
 
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index 98efe87541..54cadaf5b5 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.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 docs/subsystems/session-projection.md
-session-projection.md: 64351195028c62f623b32cbeb80c952795c1e9e6
-session-projection.zh.md: e4a03c6719095cc342d914612faf364fc48e4fa0
+session-projection.md: ddb3877618904d3185eba7d9d351afbcc81b2d04
+session-projection.zh.md: 39e6099130ba0d91e72e8f1afd5661e5894f8d0f
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
index 6435119502..ddb3877618 100644
--- a/docs/subsystems/session-projection.md
+++ b/docs/subsystems/session-projection.md
@@ -2,7 +2,7 @@
 
 English | [中文](session-projection.zh.md)
 
-The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the interface and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame today). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
+The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the Service Definition and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame today). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
 
 Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index e4a03c6719..39e6099130 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -2,7 +2,7 @@
 
 [English](session-projection.md) | 中文
 
-会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是接口与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流约定：[包（package）README](../../packages/session/session-projection/README.md)。
+会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是 Service Definition 与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流约定：[包（package）README](../../packages/session/session-projection/README.md)。
 
 源码：[`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 
diff --git a/docs/subsystems/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml
index 02734a5cdc..4ba7a3392b 100644
--- a/docs/subsystems/session-query.i18n.yaml
+++ b/docs/subsystems/session-query.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 docs/subsystems/session-query.md
-session-query.md: e62cd1c6ff744e7ccdc6f26f5ad76a6512a205bf
-session-query.zh.md: 7bd2b55509e4c5bb971a44680d0d7576c5d10146
+session-query.md: 3b6d99af58ffb7c3e7b58cc4a3e9143732382861
+session-query.zh.md: c23e9ad53ef6a3e4a8e50a892824068f33e4e15b
diff --git a/docs/subsystems/session-query.md b/docs/subsystems/session-query.md
index e62cd1c6ff..3b6d99af58 100644
--- a/docs/subsystems/session-query.md
+++ b/docs/subsystems/session-query.md
@@ -2,7 +2,7 @@
 
 English | [中文](session-query.zh.md)
 
-Query vocabulary over the live-preferred logical session corpus. The [interface package](../../packages/session-query/session-query) owns exact reads, source precedence, relationship tracing, semantic extraction, and provider-independent filters, while the [SQLite package](../../packages/session-query/session-query-sqlite) owns the concrete full-text index lifecycle.
+Query vocabulary over the live-preferred logical session corpus. The [Service Definition package](../../packages/session-query/session-query) owns exact reads, source precedence, relationship tracing, semantic extraction, and provider-independent filters, while the [SQLite provider](../../packages/session-query/session-query-sqlite) owns the concrete full-text index lifecycle.
 
 Source: [`packages/session-query/session-query/src/types.ts`](../../packages/session-query/session-query/src/types.ts)
 
@@ -363,9 +363,9 @@ type SessionQueryErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionquery--sessionqueryservice"></a>
+<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
 
-### `ctx.sessionQuery` — `SessionQueryService`
+### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
 
 Unified live-preferred session query service.
 
diff --git a/docs/subsystems/session-query.zh.md b/docs/subsystems/session-query.zh.md
index 7bd2b55509..c23e9ad53e 100644
--- a/docs/subsystems/session-query.zh.md
+++ b/docs/subsystems/session-query.zh.md
@@ -2,7 +2,7 @@
 
 [English](session-query.md) | 中文
 
-本文定义逻辑会话语料库的查询词汇；当 live 数据存在时，该语料库优先使用 live 数据。[接口包](../../packages/session-query/session-query)负责精确读取、来源优先级、关系追踪、语义提取，以及与提供方无关的过滤器；[SQLite 包](../../packages/session-query/session-query-sqlite)负责具体全文索引的生命周期。
+本文定义逻辑会话语料库的查询词汇；当 live 数据存在时，该语料库优先使用 live 数据。[Service Definition 包](../../packages/session-query/session-query)负责精确读取、来源优先级、关系追踪、语义提取，以及与提供方无关的过滤器；[SQLite 提供方](../../packages/session-query/session-query-sqlite)负责具体全文索引的生命周期。
 
 源码：[`packages/session-query/session-query/src/types.ts`](../../packages/session-query/session-query/src/types.ts)
 
@@ -363,9 +363,9 @@ type SessionQueryErrorCode =
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsessionquery--sessionqueryservice"></a>
+<a id="ctxsessionquery--sessionqueryservice-abstract-seam"></a>
 
-### `ctx.sessionQuery` — `SessionQueryService`
+### `ctx.sessionQuery` — `SessionQueryService` (abstract seam)
 
 Unified live-preferred session query service.
 
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index da4ec0a16b..04f3cc5394 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 4b057317969c8dc59c899fb07812e01a0b5d94d3
-session.zh.md: 804edc32635ddfcc1335ecd9c0a6c4df4f998594
+session.md: a5162c77d510c5ab66fa2dd6789693e1449970fb
+session.zh.md: 989a3f5368aa0b0475dec4272fde724fd4a98230
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 4b05731796..a5162c77d5 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -663,7 +663,7 @@ prepare(id?: SessionId, options?: PrepareSessionOptions): Session
  * another create) between them, so a stale prepared session must NOT overwrite
  * a live store entry of the same id — its detach disposer would later delete
  * the REAL session. The {@link create} convenience and the agent factory call
- * the two back-to-back so they never trip this, but the public seam cannot
+ * the two back-to-back so they never trip this, but the public API cannot
  * assume that.
  *
  * @param session - a {@link prepare}d session not yet in the store.
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 804edc3263..989a3f5368 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -667,7 +667,7 @@ prepare(id?: SessionId, options?: PrepareSessionOptions): Session
  * another create) between them, so a stale prepared session must NOT overwrite
  * a live store entry of the same id — its detach disposer would later delete
  * the REAL session. The {@link create} convenience and the agent factory call
- * the two back-to-back so they never trip this, but the public seam cannot
+ * the two back-to-back so they never trip this, but the public API cannot
  * assume that.
  *
  * @param session - a {@link prepare}d session not yet in the store.
diff --git a/docs/subsystems/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml
index e541d20f69..a257e0e33e 100644
--- a/docs/subsystems/settings.i18n.yaml
+++ b/docs/subsystems/settings.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 docs/subsystems/settings.md
-settings.md: c15b11c8635def88aba49b6df66aa56a22fbe0ae
-settings.zh.md: 7f588ededd0ad2eb058995d4d54fe71c8b6bc67a
+settings.md: 9256bf9436d2e77093fc8c6a3728b62fc4e8d67f
+settings.zh.md: 720eb9c2718c1fa14a148cced806c224634dba69
diff --git a/docs/subsystems/settings.md b/docs/subsystems/settings.md
index c15b11c863..9256bf9436 100644
--- a/docs/subsystems/settings.md
+++ b/docs/subsystems/settings.md
@@ -169,9 +169,9 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsettings--settings"></a>
+<a id="ctxsettings--settings-abstract-seam"></a>
 
-### `ctx.settings` — `Settings`
+### `ctx.settings` — `Settings` (abstract seam)
 
 Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
 
diff --git a/docs/subsystems/settings.zh.md b/docs/subsystems/settings.zh.md
index 7f588ededd..720eb9c271 100644
--- a/docs/subsystems/settings.zh.md
+++ b/docs/subsystems/settings.zh.md
@@ -169,9 +169,9 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsettings--settings"></a>
+<a id="ctxsettings--settings-abstract-seam"></a>
 
-### `ctx.settings` — `Settings`
+### `ctx.settings` — `Settings` (abstract seam)
 
 Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
 
diff --git a/docs/subsystems/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
index 570dfe223f..5945dfb286 100644
--- a/docs/subsystems/skills.i18n.yaml
+++ b/docs/subsystems/skills.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 docs/subsystems/skills.md
-skills.md: 78d510fafca0017b9528a215270172a74e9b0de1
-skills.zh.md: 12e51c45a779e3ca0634db62ac9adfe69112d09f
+skills.md: 1c3d683c6fb2c2ac26e00c32329e41b8d4636fb1
+skills.zh.md: b38effdd5858625bb1aa5f10108d5d654f692b7c
diff --git a/docs/subsystems/skills.md b/docs/subsystems/skills.md
index 78d510fafc..1c3d683c6f 100644
--- a/docs/subsystems/skills.md
+++ b/docs/subsystems/skills.md
@@ -2,7 +2,7 @@
 
 English | [中文](skills.zh.md)
 
-The [skill capability family](../../packages/skill) includes the registry ([dsh-skill](../../packages/skill/skill), `ctx.skills`), the local provider ([dsh-skill-local](../../packages/skill/skill-local)), the optional packaged badge provider ([dsh-skill-badge](../../packages/skill/skill-badge)), and the consumer ([dsh-tool-skill](../../packages/skill/tool-skill)). The registry merges provider catalogs; providers contribute local or packaged skills; the consumer owns the initial and replacement catalogs plus the model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
+The [skill capability family](../../packages/skill) includes the Service Definition ([dsh-skill](../../packages/skill/skill), `ctx.skills`), the local Service provider ([dsh-skill-local](../../packages/skill/skill-local)), the optional packaged badge provider ([dsh-skill-badge](../../packages/skill/skill-badge)), and the Consumer ([dsh-tool-skill](../../packages/skill/tool-skill)). The registry merges provider catalogs; providers contribute local or packaged skills; the Consumer owns the initial and replacement catalogs plus the model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
 
 Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts), [`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts), [`packages/skill/skill-badge/src/index.ts`](../../packages/skill/skill-badge/src/index.ts), and [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts).
 
@@ -283,7 +283,7 @@ async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
 async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
 ```
 
-Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:305`](../../packages/skill/skill/src/index.ts)
 
 <a id="skills-events"></a>
 
@@ -306,5 +306,5 @@ A skill provider, runtime contribution, or provider-backed catalog may have chan
 'skills/change'(): void
 ```
 
-Source: [`packages/skill/skill/src/index.ts:283`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:284`](../../packages/skill/skill/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/skills.zh.md b/docs/subsystems/skills.zh.md
index 12e51c45a7..b38effdd58 100644
--- a/docs/subsystems/skills.zh.md
+++ b/docs/subsystems/skills.zh.md
@@ -2,7 +2,7 @@
 
 [English](skills.md) | 中文
 
-[skill（技能）能力族](../../packages/skill) 包含注册表（[dsh-skill](../../packages/skill/skill)，`ctx.skills`）、本地提供方（[dsh-skill-local](../../packages/skill/skill-local)）、可选的随包徽章提供方（[dsh-skill-badge](../../packages/skill/skill-badge)）和消费方（[dsh-tool-skill](../../packages/skill/tool-skill)）。注册表合并各提供方的目录；提供方贡献本地或随包 skill；消费方拥有初始目录和替换目录，以及面向模型的 `skill` 工具。skill 是可选的指令而非会话事件，因此其词汇定义在此处而非 [core.md](core.md)。
+[skill（技能）能力族](../../packages/skill) 包含 Service Definition（[dsh-skill](../../packages/skill/skill)，`ctx.skills`）、本地 Service provider（[dsh-skill-local](../../packages/skill/skill-local)）、可选的随包徽章提供方（[dsh-skill-badge](../../packages/skill/skill-badge)）和 Consumer（[dsh-tool-skill](../../packages/skill/tool-skill)）。注册表合并各提供方的目录；提供方贡献本地或随包 skill；Consumer 拥有初始目录和替换目录，以及面向模型的 `skill` 工具。skill 是可选的指令而非会话事件，因此其词汇定义在此处而非 [core.md](core.md)。
 
 源码：[`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts)、[`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts)、[`packages/skill/skill-badge/src/index.ts`](../../packages/skill/skill-badge/src/index.ts) 与 [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts)。
 
@@ -283,7 +283,7 @@ async snapshot(options: SkillLookupOptions = {}): Promise<SkillCatalogSnapshot>
 async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
 ```
 
-Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:305`](../../packages/skill/skill/src/index.ts)
 
 <a id="skills-events"></a>
 
@@ -306,5 +306,5 @@ A skill provider, runtime contribution, or provider-backed catalog may have chan
 'skills/change'(): void
 ```
 
-Source: [`packages/skill/skill/src/index.ts:283`](../../packages/skill/skill/src/index.ts)
+Source: [`packages/skill/skill/src/index.ts:284`](../../packages/skill/skill/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml
index c0e9f9f50d..da210bd7d2 100644
--- a/docs/subsystems/spill.i18n.yaml
+++ b/docs/subsystems/spill.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 docs/subsystems/spill.md
-spill.md: 4998ac62d1cd4e86a6e92ec5a0c85955b137f4be
-spill.zh.md: 0495c6fbcdb5c909a142539f69d5dd2bd551413c
+spill.md: bc323f8d2591e93a56e938c245274ef6be86085f
+spill.zh.md: f81d5e5de3633561a5a090a14c39b43268b8c63f
diff --git a/docs/subsystems/spill.md b/docs/subsystems/spill.md
index 4998ac62d1..bc323f8d25 100644
--- a/docs/subsystems/spill.md
+++ b/docs/subsystems/spill.md
@@ -2,13 +2,13 @@
 
 English | [中文](spill.zh.md)
 
-The spill storage seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) that persists a tool's oversized text and returns a model-facing locator plus retrieval guidance, split across packages: interface ([dsh-spill](../../packages/spill/spill), `ctx.spillStore`), implementation ([dsh-spill-local](../../packages/spill/spill-local), private session-scoped files on the host filesystem), and consumer ([dsh-spill-policy](../../packages/spill/spill-policy), the `tools/post-execute` policy). Spill is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Preview mechanics stay in [dsh-retention](../../packages/util/retention); this seam only saves the final text the policy hands it.
+The spill storage seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) that persists a tool's oversized text and returns a model-facing locator plus retrieval guidance, split across packages: Service Definition ([dsh-spill](../../packages/spill/spill), `ctx.spillStore`), Service provider ([dsh-spill-local](../../packages/spill/spill-local), private session-scoped files on the host filesystem), and Consumer ([dsh-spill-policy](../../packages/spill/spill-policy), the `tools/post-execute` policy). Spill is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Preview mechanics stay in [dsh-retention](../../packages/util/retention); this seam only saves the final text the policy hands it.
 
 Source: [`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)
 
 ## The save request
 
-`saveText` is the whole seam: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), the tool and call that produced it (`source`, used for naming and inspection — not access control), and a `suggestedName` the backend may use as a naming hint (it is not a path).
+`saveText` is the sole service operation: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), the tool and call that produced it (`source`, used for naming and inspection — not access control), and a `suggestedName` the backend may use as a naming hint (it is not a path).
 
 ```ts type-equiv
 /** One request to persist text to a spill artifact. */
@@ -92,9 +92,9 @@ The local backend ([dsh-spill-local](../../packages/spill/spill-local)) writes u
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxspillstore--spillstore"></a>
+<a id="ctxspillstore--spillstore-abstract-seam"></a>
 
-### `ctx.spillStore` — `SpillStore`
+### `ctx.spillStore` — `SpillStore` (abstract seam)
 
 Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/spill.zh.md b/docs/subsystems/spill.zh.md
index 0495c6fbcd..f81d5e5de3 100644
--- a/docs/subsystems/spill.zh.md
+++ b/docs/subsystems/spill.zh.md
@@ -2,13 +2,13 @@
 
 [English](spill.md) | 中文
 
-落盘存储 seam 是一项[能力 seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，它持久保存工具的超大文本，并返回面向模型的定位符与检索指引；该能力拆分到三个包：接口（[dsh-spill](../../packages/spill/spill)，`ctx.spillStore`）、实现（[dsh-spill-local](../../packages/spill/spill-local)，宿主文件系统中会话作用域的私有文件）和消费方（[dsh-spill-policy](../../packages/spill/spill-policy)，`tools/post-execute` 策略）。落盘是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇记录在此处，而不在 [core.md](core.md) 中。预览机制仍归 [dsh-retention](../../packages/util/retention) 所有；该 seam 只保存策略交给它的最终文本。
+落盘存储 seam 是一项[能力 seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，它持久保存工具的超大文本，并返回面向模型的定位符与检索指引；该能力拆分到三个包：Service Definition（[dsh-spill](../../packages/spill/spill)，`ctx.spillStore`）、Service provider（[dsh-spill-local](../../packages/spill/spill-local)，宿主文件系统中会话作用域的私有文件）和 Consumer（[dsh-spill-policy](../../packages/spill/spill-policy)，`tools/post-execute` 策略）。落盘是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇记录在此处，而不在 [core.md](core.md) 中。预览机制仍归 [dsh-retention](../../packages/util/retention) 所有；该 seam 只保存策略交给它的最终文本。
 
 源码：[`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)
 
 ## 保存请求
 
-`saveText` 是整个 seam：原样持久保存 `content`，并返回不透明的定位符、后端提供的检索提示和准确字节数。请求携带保存时的存储命名空间（`owner`）、生成内容的工具和调用（`source`，用于命名和检查，而非访问控制）以及后端可用作命名提示的 `suggestedName`（它不是路径）。
+`saveText` 是唯一的服务操作：原样持久保存 `content`，并返回不透明的定位符、后端提供的检索提示和准确字节数。请求携带保存时的存储命名空间（`owner`）、生成内容的工具和调用（`source`，用于命名和检查，而非访问控制）以及后端可用作命名提示的 `suggestedName`（它不是路径）。
 
 ```ts type-equiv
 /** One request to persist text to a spill artifact. */
@@ -92,9 +92,9 @@ type SpillLocator = Branded<'SpillLocator'>
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxspillstore--spillstore"></a>
+<a id="ctxspillstore--spillstore-abstract-seam"></a>
 
-### `ctx.spillStore` — `SpillStore`
+### `ctx.spillStore` — `SpillStore` (abstract seam)
 
 Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 3d8db33ada..5b4d6d1040 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.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 docs/subsystems/storage.md
-storage.md: 52dc84b699921e911276ce5214bc975abfd22fa4
-storage.zh.md: 89ff7f69ed43b55101be834c21d11cf74ca2340b
+storage.md: 94d3c3f39a65462cd8cd58a65b02066d5bad4b8c
+storage.zh.md: c3cea8eb5e44f2e589b0196dc690c6473e3552ca
diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md
index 52dc84b699..94d3c3f39a 100644
--- a/docs/subsystems/storage.md
+++ b/docs/subsystems/storage.md
@@ -2,7 +2,7 @@
 
 English | [中文](storage.zh.md)
 
-The storage subsystem persists everything that is not a session event log (session logs have their own seam — [persistence.md](persistence.md)). It is one optional capability, not part of the agent-loop spine, split as a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): the hub and backend interface ([dsh-storage](../../packages/storage/storage), `ctx.storage`), the backend implementations ([dsh-storage-json](../../packages/storage/storage-json), registered as `json`, and [dsh-storage-sqlite](../../packages/storage/storage-sqlite), registered as `sqlite`), and the domain data form ([dsh-storage-domain](../../packages/storage/storage-domain), `ctx.storageDomain`, also reachable as `ctx.storage.domain`) — the backend seam's only consumer and the typed API everything else uses. The hub performs no IO itself: backends own media, data forms own semantics, and product packages never touch backends directly. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).
+The storage subsystem persists everything that is not a session event log (session logs have their own seam — [persistence.md](persistence.md)). It is one optional capability, not part of the agent-loop spine, split as a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): the hub and Service Definition ([dsh-storage](../../packages/storage/storage), `ctx.storage`), the Service providers ([dsh-storage-json](../../packages/storage/storage-json), registered as `json`, and [dsh-storage-sqlite](../../packages/storage/storage-sqlite), registered as `sqlite`), and the Consumer data form ([dsh-storage-domain](../../packages/storage/storage-domain), `ctx.storageDomain`, also reachable as `ctx.storage.domain`) — the backend contract's only Consumer and the typed API everything else uses. The hub performs no IO itself: backends own media, data forms own semantics, and product packages never touch backends directly. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).
 
 Source: [`packages/storage/storage/src/backend.ts`](../../packages/storage/storage/src/backend.ts) · [`packages/storage/storage-domain/src/spec.ts`](../../packages/storage/storage-domain/src/spec.ts) · [`packages/storage/storage-domain/src/events.ts`](../../packages/storage/storage-domain/src/events.ts)
 
@@ -23,7 +23,7 @@ interface StorageForms {}
 
 `mount(form, facility)` is an effect whose disposer unmounts; a second mount of the same key throws `duplicate-mount`. `form(form)` resolves a mounted facility and throws `form-not-mounted` until the owning plugin loads — assemblies order plugins accordingly rather than silently deferring. The domain layer merges `domain: DomainFacility`, so `ctx.storage.domain` and `ctx.storageDomain` are the same object.
 
-## The backend seam
+## The backend contract
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index 89ff7f69ed..c3cea8eb5e 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -2,7 +2,7 @@
 
 [English](storage.md) | 中文
 
-存储子系统持久保存一切不属于会话事件日志的数据（会话日志有自己的 seam——见 [persistence.md](persistence.md)）。它是一项可选能力，不属于 agent loop（智能体循环）主干，并按[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)拆分：枢纽（hub）与后端接口（[dsh-storage](../../packages/storage/storage)，`ctx.storage`）、后端实现（注册为 `json` 的 [dsh-storage-json](../../packages/storage/storage-json) 与注册为 `sqlite` 的 [dsh-storage-sqlite](../../packages/storage/storage-sqlite)），以及领域数据形式（[dsh-storage-domain](../../packages/storage/storage-domain)，`ctx.storageDomain`，也可经 `ctx.storage.domain` 访问）——它是后端 seam 的唯一消费方，也是其他一切所使用的类型化 API。枢纽自身不做任何 IO：后端拥有介质，数据形式拥有语义，产品包（package）绝不直接触碰后端。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
+存储子系统持久保存一切不属于会话事件日志的数据（会话日志有自己的 seam——见 [persistence.md](persistence.md)）。它是一项可选能力，不属于 agent loop（智能体循环）主干，并按[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)拆分：枢纽（hub）与 Service Definition（[dsh-storage](../../packages/storage/storage)，`ctx.storage`）、Service provider（注册为 `json` 的 [dsh-storage-json](../../packages/storage/storage-json) 与注册为 `sqlite` 的 [dsh-storage-sqlite](../../packages/storage/storage-sqlite)），以及 Consumer 数据形式（[dsh-storage-domain](../../packages/storage/storage-domain)，`ctx.storageDomain`，也可经 `ctx.storage.domain` 访问）——它是后端约定的唯一 Consumer，也是其他一切所使用的类型化 API。枢纽自身不做任何 IO：后端拥有介质，数据形式拥有语义，产品包（package）绝不直接触碰后端。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
 
 源码：[`packages/storage/storage/src/backend.ts`](../../packages/storage/storage/src/backend.ts) · [`packages/storage/storage-domain/src/spec.ts`](../../packages/storage/storage-domain/src/spec.ts) · [`packages/storage/storage-domain/src/events.ts`](../../packages/storage/storage-domain/src/events.ts)
 
@@ -23,7 +23,7 @@ interface StorageForms {}
 
 `mount(form, facility)` 是一个 effect，其 disposer 负责卸载；对同一键的第二次挂载抛出 `duplicate-mount`。`form(form)` 解析已挂载的 facility，在拥有插件加载之前抛出 `form-not-mounted`——组合方应据此安排插件顺序，而不是静默推迟。领域层合并 `domain: DomainFacility`，因此 `ctx.storage.domain` 与 `ctx.storageDomain` 是同一个对象。
 
-## 后端 seam
+## 后端约定
 
 ```ts type-equiv
 /**
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 3fc905e09b..5e8fdefb08 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: 9fd6c8ae16abb6d99180bad105c54cdb6db4fac5
-subagent.zh.md: 874fbfdb31b8389e4495a2f8494d9c3cb82e41b9
+subagent.md: a14e9ec5fad3f25f231016c142c3965561790afe
+subagent.zh.md: 7bf3595324ecfec85329ea3f51ab5a8cc0d4c329
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index 9fd6c8ae16..a14e9ec5fa 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -4,13 +4,13 @@ English | [中文](subagent.zh.md)
 
 The subagent seam — an agent delegating work to a child agent. Like [bash](bash.md) it is **one optional capability**, not part of the agent-loop spine, so its vocabulary lives here rather than in [core.md](core.md). But it differs from every other seam on one axis: **multiple provider implementations coexist** in one context, registered by name (`ctx.subagents`), where bash allows only one executor. The registry shape mirrors the [LLM adapter registry](llm-streaming.md), not the single-service bash executor.
 
-Interface: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Implementations are sibling packages (`dsh-subagent-spawn`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message`, `interrupt_agent`, and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only child and descendant discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
+Service Definition: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Service providers are sibling packages (`dsh-subagent-spawn`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing Consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message`, `interrupt_agent`, and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only child and descendant discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
 
 Sources: [`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts), [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts), and [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
 ## Two kinds of capability, discovered two ways
 
-A provider advertises its **start-time** features on a static descriptor the service checks BEFORE a one-shot run exists; a request that needs one the provider lacks is rejected loud (`SubagentError('UNSUPPORTED_CAPABILITY')`), never accepted-then-ignored. Those flags describe only the one-shot [`start()`](#the-provider-seam-subagentprovider) path, where the provider composes the child. **Continuable** children are composed by the continuation manager itself, so they are gated by one optional method whose presence IS the capability, with TS narrowing as the discovery mechanism: [`SubagentProvider.prepareContinuable`](#the-provider-seam-subagentprovider).
+A provider advertises its **start-time** features on a static descriptor the service checks BEFORE a one-shot run exists; a request that needs one the provider lacks is rejected loud (`SubagentError('UNSUPPORTED_CAPABILITY')`), never accepted-then-ignored. Those flags describe only the one-shot [`start()`](#the-provider-contract-subagentprovider) path, where the provider composes the child. **Continuable** children are composed by the continuation manager itself, so they are gated by one optional method whose presence IS the capability, with TS narrowing as the discovery mechanism: [`SubagentProvider.prepareContinuable`](#the-provider-contract-subagentprovider).
 
 ```ts type-equiv
 /**
@@ -191,7 +191,7 @@ interface ContinuableStart {
 
 An optional continuable-child setup contribution can install scope-local capabilities after base child composition and before Activation publication. The registry is ordered and transactional: a failed or revoked setup rolls back the unpublished Activation, child-scope disposal releases every installation, new registrations affect the next Activation, and registration removal revokes every resident installation immediately.
 
-`SubagentService.reportFrom()` uses that extension seam without adding a second queue or a result-bearing child wrapper. The exact live child Agent authorizes the call; callers cannot name a recipient. The manager derives the only recipient from the child's durable `parentSession`, requires that parent Agent to be live, frames the selected content as one `subagent-report` user message, and returns the message's stable `MessageId`. Quiet delivery uses `Agent.inject()` and creates no inbox occurrence or parent turn; waking delivery uses `Agent.followup()` and creates one ordinary later parent turn. Neither mode concludes the child's turn, and no final answer reports implicitly.
+`SubagentService.reportFrom()` uses that extension point without adding a second queue or a result-bearing child wrapper. The exact live child Agent authorizes the call; callers cannot name a recipient. The manager derives the only recipient from the child's durable `parentSession`, requires that parent Agent to be live, frames the selected content as one `subagent-report` user message, and returns the message's stable `MessageId`. Quiet delivery uses `Agent.inject()` and creates no inbox occurrence or parent turn; waking delivery uses `Agent.followup()` and creates one ordinary later parent turn. Neither mode concludes the child's turn, and no final answer reports implicitly.
 
 ```ts type-equiv
 /** Durable attribution for a continuable child's explicit parent report. */
@@ -265,7 +265,7 @@ A local one-shot provider appends the descriptor inside the child's initial turn
 
 ## Durable enumeration: `listChildren()`, `listDescendants()`, and their entries
 
-`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query seam, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry's `running`/`idle`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
+`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query service, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry's `running`/`idle`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
 
 `SubagentService.listDescendants(rootSessionId)` applies the same live-preferred corpus and projection-backed interpretation to the root's complete descendant tree in stable pre-order. Ordinary sessions and one-shot children remain traversal nodes, so continuable descendants below them are discovered; only `origin: 'subagent'` candidates produce rows. Each returned child or diagnostic adds its position from the enumerated durable header, while a cold inspection revalidates that complete lifecycle before serving identity:
 
@@ -376,7 +376,7 @@ interface SubagentRun {
 
 A local one-shot run MUST publish an ordinary child agent/session before `start()` fulfills, return that child session id as `SubagentRun.id`, expose the exact child as `localAgent`, record `request.parent.session.id` in the child's `parentSession` header, and append the resolved descriptor inside the child's initial turn before its first request. Runtime ownership may place the child under the parent, provider, or root scope. A remote provider instead returns a parent-scoped lifecycle id and `localAgent: undefined`; without a local child Session, it is absent from durable enumeration.
 
-## The provider seam: `SubagentProvider`
+## The provider contract: `SubagentProvider`
 
 Each provider is a named child-agent transport, and multiple providers may coexist. The service validates requested start-time capabilities before `start()`, and rejects a continuable start on a provider without `prepareContinuable`. `inheritsParentContext` describes only conversation seeding (`fork`: true; `spawn` and `acp`: false), allowing consumers to generate accurate model-facing wording without implying inherited tools, services, or authority.
 
@@ -531,7 +531,7 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
 
 /**
  * Enumerate the parent's direct session-backed subagents without loading or
- * resuming an Agent and without any query seam: the listing merges the live
+ * resuming an Agent and without any query service: the listing merges the live
  * session store with optional session persistence (live-preferred) and
  * serves each child's durable mode/label from the registered `subagent`
  * projection unit down a three-rung ladder — the registry's watermark
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 874fbfdb31..7bf3595324 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -4,13 +4,13 @@
 
 subagent seam：一个 agent（智能体）将工作委派给子 agent。与 [bash](bash.md) 一样，它是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。但它在一个维度上与其他所有 seam 不同：**同一上下文中可共存多个提供方实现**，按名称注册（`ctx.subagents`），而 bash 只允许一个执行器。注册表的形状参照 [LLM（大语言模型）适配器注册表](llm-streaming.md)，而非单服务的 bash 执行器。
 
-接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接基于会话存储和可选的会话持久化提供只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
+Service Definition：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。Service provider 是六个兄弟包：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的 Consumer 包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接基于会话存储和可选的会话持久化提供只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
 
 源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)、[`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)和 [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
 ## 两类能力，两种发现方式
 
-提供方通过一个静态描述符公布其**启动时**功能，服务会在单次 run 存在之前即行检查；如果请求依赖提供方不具备的功能，会被明确拒绝（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不会被接受后静默忽略。这些 flag 仅描述单次 [`start()`](#the-provider-seam-subagentprovider) 路径，即由提供方组合子 agent 的路径。**可继续**子 agent 由继续执行管理器自行组合，因此它们由唯一一个可选方法把关，方法存在即为能力，并以 TypeScript 的类型收窄作为发现机制：[`SubagentProvider.prepareContinuable`](#the-provider-seam-subagentprovider)。
+提供方通过一个静态描述符公布其**启动时**功能，服务会在单次 run 存在之前即行检查；如果请求依赖提供方不具备的功能，会被明确拒绝（`SubagentError('UNSUPPORTED_CAPABILITY')`），绝不会被接受后静默忽略。这些 flag 仅描述单次 [`start()`](#the-provider-contract-subagentprovider) 路径，即由提供方组合子 agent 的路径。**可继续**子 agent 由继续执行管理器自行组合，因此它们由唯一一个可选方法把关，方法存在即为能力，并以 TypeScript 的类型收窄作为发现机制：[`SubagentProvider.prepareContinuable`](#the-provider-contract-subagentprovider)。
 
 ```ts type-equiv
 /**
@@ -191,7 +191,7 @@ interface ContinuableStart {
 
 可选的可继续 child 设置贡献可以在 child 基础组合完成后、Activation 发布前安装限定在作用域内的能力。该注册表按顺序执行且具有事务性：设置失败或被撤销时会回滚未发布的 Activation；child 作用域 dispose 时会释放所有安装；新注册项在下一个 Activation 生效；移除注册项时则会立即撤销每个驻留中的安装。
 
-`SubagentService.reportFrom()` 通过该扩展 seam 实现报告，无需新增第二条队列或承载结果的 child 包装层。调用由确切的在线 child Agent 授权，调用方不能指定接收方。管理器从 child 的持久化 `parentSession` 中推导唯一接收方，要求该 parent Agent 必须在线，将选中内容封装为一条 `subagent-report` 用户消息，并返回该消息的稳定 `MessageId`。静默投递使用 `Agent.inject()`，不产生 inbox 条目实例或 parent 轮次；唤醒投递使用 `Agent.followup()`，会产生一个普通的后续 parent 轮次。两种模式都不会结束 child 轮次，最终回答也不会隐式报告。
+`SubagentService.reportFrom()` 通过该扩展点实现报告，无需新增第二条队列或承载结果的 child 包装层。调用由确切的在线 child Agent 授权，调用方不能指定接收方。管理器从 child 的持久化 `parentSession` 中推导唯一接收方，要求该 parent Agent 必须在线，将选中内容封装为一条 `subagent-report` 用户消息，并返回该消息的稳定 `MessageId`。静默投递使用 `Agent.inject()`，不产生 inbox 条目实例或 parent 轮次；唤醒投递使用 `Agent.followup()`，会产生一个普通的后续 parent 轮次。两种模式都不会结束 child 轮次，最终回答也不会隐式报告。
 
 ```ts type-equiv
 /** Durable attribution for a continuable child's explicit parent report. */
@@ -265,7 +265,7 @@ interface ContinuableCreateSpec {
 
 ## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
 
-`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询服务，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 `SubagentService.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
@@ -376,9 +376,9 @@ interface SubagentRun {
 
 本地单次 run 必须在 `start()` fulfill 之前发布一个普通子 agent／会话，将该子会话 id 作为 `SubagentRun.id` 返回，以 `localAgent` 暴露确切的子 agent，在子 agent 的 `parentSession` header 中记录 `request.parent.session.id`，并在子 agent 的初始轮次内、首次请求前追加已解析的描述符。运行时所有权可以把子 agent 放在 parent、提供方或 root 作用域下。远程提供方则返回 parent 作用域的生命周期 id 与 `localAgent: undefined`；由于没有本地 child Session，它不会出现在持久化枚举结果中。
 
-<a id="the-provider-seam-subagentprovider"></a>
+<a id="the-provider-contract-subagentprovider"></a>
 
-## 提供方 seam：`SubagentProvider`
+## 提供方约定：`SubagentProvider`
 
 每个提供方都是一个具名的子 agent 传输层，多个提供方可以共存。服务在 `start()` 之前校验请求的启动时能力，并拒绝在没有 `prepareContinuable` 的提供方上发起可继续 start。`inheritsParentContext` 仅描述对话种子注入（`fork`：true；`spawn` 和 `acp`：false），使消费方能生成准确的面向模型措辞，而不暗示继承了工具、服务或权限。
 
@@ -533,7 +533,7 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
 
 /**
  * Enumerate the parent's direct session-backed subagents without loading or
- * resuming an Agent and without any query seam: the listing merges the live
+ * resuming an Agent and without any query service: the listing merges the live
  * session store with optional session persistence (live-preferred) and
  * serves each child's durable mode/label from the registered `subagent`
  * projection unit down a three-rung ladder — the registry's watermark
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index 0af3183692..e89be8fdc9 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.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 docs/subsystems/subprocess.md
-subprocess.md: b501af81dca94025713d46a23a67b543f5df95cd
-subprocess.zh.md: 84b497c90bb5956b0dcb65ca1cb72122b415bd7e
+subprocess.md: eedf95abc2a51872ffc9964481bb3685ace31993
+subprocess.zh.md: 669baa52a92fc3869b057dc802c72989fa8cfcf1
diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md
index b501af81dc..eedf95abc2 100644
--- a/docs/subsystems/subprocess.md
+++ b/docs/subsystems/subprocess.md
@@ -2,7 +2,7 @@
 
 English | [中文](subprocess.zh.md)
 
-The subprocess seam is split across interface ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and implementation ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its consumers are other capability seams and out-of-process backends: the [bash executor family](bash.md) uses collected batch output, LSP uses raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
+The subprocess seam is split across a Service Definition ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and Service provider ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its Consumers are other capability seams and out-of-process backends: the [bash executor family](bash.md) uses collected batch output, LSP uses raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-bash](../../packages/bash/bash) re-exports the vocabulary so bash consumers keep one import root.
 
 Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) and [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
 
@@ -242,11 +242,11 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches quiescence for every session member the provider can still observe; providers document substrate-specific observability limits. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
 
-The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessservice).
+The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessservice-abstract-seam).
 
 ## Service behavior
 
-The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam defines execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) implements them with detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the interface contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
+The abstract [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) Service Definition specifies execution-world coordinates, executable lookup, ordinary `spawn`, and `spawnTerminal`. [`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) provides them with detached process trees, per-disposition wiring, credential scrubbing, `node-pty`, platform process inspection, and terminate-and-join disposal. See [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md) for the Service Definition contract and [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md) for local mechanics.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -273,9 +273,9 @@ async getSandbox(): Promise<Sandbox>
 
 Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
 
-<a id="ctxsubprocess--subprocessservice"></a>
+<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
 
-### `ctx.subprocess` — `SubprocessService`
+### `ctx.subprocess` — `SubprocessService` (abstract seam)
 
 Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index 84b497c90b..669baa52a9 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -2,7 +2,7 @@
 
 [English](subprocess.md) | 中文
 
-进程管理器 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式的批量输出，LSP 使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用管道化 ndjson 加 inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
+进程管理器 seam 分为 Service Definition（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与 Service provider（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的 Consumer 是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式的批量输出，LSP 使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用管道化 ndjson 加 inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
 
 源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) 与 [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
 
@@ -242,11 +242,11 @@ interface SubprocessOutcome {
 
 `spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，提供方则会记录执行基底特有的可观察性限制。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
 
-终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessservice)中。
+终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`；确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessservice-abstract-seam)中。
 
 ## 服务行为
 
-抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 定义执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放实现这些能力。接口约定见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) Service Definition 规定执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 以 detached 进程树、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放提供这些能力。Service Definition 约定见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -273,9 +273,9 @@ async getSandbox(): Promise<Sandbox>
 
 Source: [`packages/e2b/e2b/src/index.ts:74`](../../packages/e2b/e2b/src/index.ts)
 
-<a id="ctxsubprocess--subprocessservice"></a>
+<a id="ctxsubprocess--subprocessservice-abstract-seam"></a>
 
-### `ctx.subprocess` — `SubprocessService`
+### `ctx.subprocess` — `SubprocessService` (abstract seam)
 
 Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml
index 6f9d3c6861..c229d0a5c0 100644
--- a/docs/subsystems/tasks.i18n.yaml
+++ b/docs/subsystems/tasks.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 docs/subsystems/tasks.md
-tasks.md: f042dfec7438bd2e385cc8c225a3faa171b9ca4f
-tasks.zh.md: bf660a9606f0bc9081532c970e88f249ea0ec4ae
+tasks.md: d3e92891a6736a85519b97775ebe7aa6f12a5ae2
+tasks.zh.md: fe54d7a6482743a8f2ef31b143edb25afe0a478b
diff --git a/docs/subsystems/tasks.md b/docs/subsystems/tasks.md
index f042dfec74..d3e92891a6 100644
--- a/docs/subsystems/tasks.md
+++ b/docs/subsystems/tasks.md
@@ -151,7 +151,7 @@ interface TaskRead {
 
 ## Service behavior
 
-The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam defines atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, contained `onTaskDone` listeners, and the `attachSurface` availability fence; [`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) is the process-local implementation. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the seam contract, [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md) for the registry lifecycle, and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing surface.
+The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, contained `onTaskDone` listeners, and the `attachSurface` availability fence; [`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) is the process-local provider. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the Service Definition contract, [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md) for the registry lifecycle, and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing Consumer.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -161,9 +161,9 @@ The abstract [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam defin
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtasks--taskservice"></a>
+<a id="ctxtasks--taskservice-abstract-seam"></a>
 
-### `ctx.tasks` — `TaskService`
+### `ctx.tasks` — `TaskService` (abstract seam)
 
 Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/tasks.zh.md b/docs/subsystems/tasks.zh.md
index bf660a9606..fe54d7a648 100644
--- a/docs/subsystems/tasks.zh.md
+++ b/docs/subsystems/tasks.zh.md
@@ -151,7 +151,7 @@ interface TaskRead {
 
 ## 服务行为
 
-抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) seam 定义原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 监听器，以及 `attachSurface` 可用性防线；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部实现。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。seam 约定见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的接口见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
+抽象的 [`TaskService`](../../packages/tasks/tasks/src/index.ts) Service Definition 规定原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onTaskDone` 监听器，以及 `attachSurface` 可用性防线；[`LocalTaskService`](../../packages/tasks/tasks-local/src/index.ts) 是其进程局部提供方。授权会比较拥有者会话；拥有者清理会选择确切的已注册 `Agent` 实例。Service Definition 约定见 [`dsh-tasks`](../../packages/tasks/tasks/README.md)，注册表生命周期见 [`dsh-tasks-local`](../../packages/tasks/tasks-local/README.md)，面向模型的 Consumer 见 [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md)。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -161,9 +161,9 @@ interface TaskRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtasks--taskservice"></a>
+<a id="ctxtasks--taskservice-abstract-seam"></a>
 
-### `ctx.tasks` — `TaskService`
+### `ctx.tasks` — `TaskService` (abstract seam)
 
 Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index b53153692f..ec9f0cd48b 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: c9afd276f7c4183db0d1accea2b9aafe71a0e5cc
-telemetry.zh.md: e7ea255a50cace18c7d59b2c77c96bc426d5ee0c
+telemetry.md: c9e51eb38e680723ead0a88f4a9748620fd6b893
+telemetry.zh.md: 1af25c505574db6b3513547ae604eda66fc21766
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index c9afd276f7..c9e51eb38e 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -2,7 +2,7 @@
 
 English | [中文](telemetry.zh.md)
 
-Outbound session reporting, split as a [capability seam](../capability-seams.md): the seam ([dsh-session-telemetry](../../packages/session/session-telemetry), `ctx.telemetry`) owns the capture points, the fixed chunk projection, the `telemetry/record` redaction waterfall, the handoff cursor, and the minimal backend contract; the backend a deployment loads ([dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [seam README](../../packages/session/session-telemetry/README.md).
+Outbound session reporting is split as a [capability seam](../capability-seams.md): the Service Definition and capture coordinator ([dsh-session-telemetry](../../packages/session/session-telemetry), `ctx.telemetry`) own the capture points, fixed chunk projection, `telemetry/record` redaction waterfall, handoff cursor, and minimal backend contract; the Service provider a deployment loads ([dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [Service Definition README](../../packages/session/session-telemetry/README.md).
 
 Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
 
@@ -22,7 +22,7 @@ type TelemetrySeverity = 'info' | 'warn' | 'error'
 
 ```ts type-equiv
 /**
- * One logical record handed to a backend — the seam's whole outbound
+ * One logical record handed to a backend — the capture contract's whole outbound
  * vocabulary. Ledger records mirror session-log events one-to-one;
  * operational records (`channel: 'ops'`) carry the two signals with no log
  * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
@@ -105,7 +105,7 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry` (`ctx.telemetry`, [signatures](#ctxtelemetry--telemetry)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
+`Telemetry` (`ctx.telemetry`, [signatures](#ctxtelemetry--telemetry-abstract-seam)) is the contract's loadable form — one implementation per context, duplicate load throws — and a backend composes the seam's `TelemetryCoordinator` in its constructor to install the capture side.
 
 ## The redact waterfall: `telemetry/record`
 
@@ -119,15 +119,15 @@ Every record passes the `telemetry/record` [waterfall](../cordis-primer.md#cordi
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtelemetry--telemetry"></a>
+<a id="ctxtelemetry--telemetry-abstract-seam"></a>
 
-### `ctx.telemetry` — `Telemetry`
+### `ctx.telemetry` — `Telemetry` (abstract seam)
 
 The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
 
 ```ts cordis-catalog
 /**
- * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+ * See {@link TelemetryBackend.emit} — that declaration is the contract's one home.
  * @param record - the logical record to report; owned by the backend after the call.
  */
 abstract emit(record: TelemetryRecord): void
@@ -152,12 +152,12 @@ Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/s
 
 #### `telemetry/record` — waterfall
 
-Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+Transform one outbound record before it reaches the backend. This waterfall is the Service Definition's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
 
 ```ts cordis-catalog
 /**
  * Transform one outbound record before it reaches the backend. This
- * waterfall is the seam's redaction extension point. It ships NO rules
+ * waterfall is the Service Definition's redaction extension point. It ships NO rules
  * of its own: the
  * innermost `next()` passes the record through unchanged, and with no
  * listener mounted records reach the backend as captured, so exported
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index e7ea255a50..1af25c5055 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -2,7 +2,7 @@
 
 [English](telemetry.md) | 中文
 
-对外的会话上报，拆分为一项[能力 seam](../capability-seams.md)：seam 一侧（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端约定；部署方加载的后端（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的约定见 [seam README](../../packages/session/session-telemetry/README.md)。
+对外的会话上报拆分为一项[能力 seam](../capability-seams.md)：Service Definition 与捕获协调器（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.telemetry`）拥有捕获点、固定分片投影、`telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端约定；部署方加载的 Service provider（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的约定见 [Service Definition README](../../packages/session/session-telemetry/README.md)。
 
 源码：[`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
 
@@ -22,7 +22,7 @@ type TelemetrySeverity = 'info' | 'warn' | 'error'
 
 ```ts type-equiv
 /**
- * One logical record handed to a backend — the seam's whole outbound
+ * One logical record handed to a backend — the capture contract's whole outbound
  * vocabulary. Ledger records mirror session-log events one-to-one;
  * operational records (`channel: 'ops'`) carry the two signals with no log
  * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
@@ -105,7 +105,7 @@ interface TelemetryBackend {
 }
 ```
 
-`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry)）是该契约的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
+`Telemetry`（`ctx.telemetry`，[签名](#ctxtelemetry--telemetry-abstract-seam)）是该约定的可加载形态：每个上下文只允许一个实现，重复加载会抛出异常；后端在其构造函数中组合 seam 的 `TelemetryCoordinator`，以此装配捕获侧。
 
 ## 脱敏 waterfall：`telemetry/record`
 
@@ -119,15 +119,15 @@ interface TelemetryBackend {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxtelemetry--telemetry"></a>
+<a id="ctxtelemetry--telemetry-abstract-seam"></a>
 
-### `ctx.telemetry` — `Telemetry`
+### `ctx.telemetry` — `Telemetry` (abstract seam)
 
 The backend contract in its loadable form: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a TelemetryCoordinator in its constructor to install the capture side.
 
 ```ts cordis-catalog
 /**
- * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+ * See {@link TelemetryBackend.emit} — that declaration is the contract's one home.
  * @param record - the logical record to report; owned by the backend after the call.
  */
 abstract emit(record: TelemetryRecord): void
@@ -152,12 +152,12 @@ Source: [`packages/session/session-telemetry/src/index.ts:140`](../../packages/s
 
 #### `telemetry/record` — waterfall
 
-Transform one outbound record before it reaches the backend. This waterfall is the seam's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
+Transform one outbound record before it reaches the backend. This waterfall is the Service Definition's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
 
 ```ts cordis-catalog
 /**
  * Transform one outbound record before it reaches the backend. This
- * waterfall is the seam's redaction extension point. It ships NO rules
+ * waterfall is the Service Definition's redaction extension point. It ships NO rules
  * of its own: the
  * innermost `next()` passes the record through unchanged, and with no
  * listener mounted records reach the backend as captured, so exported
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index b12daefe88..42f73824cf 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: 0551ee1c9dfa12b415c1f4575b5225f771cb53bc
-tools.zh.md: acdf10a0140e81dada9104653dee92dc9cb6f50d
+tools.md: 87910dfbb86e9db0f0545bc2fe1135c4aefb2e69
+tools.zh.md: d312090b722de3fd1b8efc7703eafdf7f3c38682
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index 0551ee1c9d..87910dfbb8 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -362,7 +362,7 @@ On success the registry snapshots and validates the body value, freezes it, and
 
 Before final content, the registry materializes the candidate result; a failure in content, structured error, additional context, or presentation metadata becomes a JSON-safe `isError` result that still reaches `finalizeContent`. The registry invokes that callback exactly once, then materializes and freezes the accepted result immediately before `tools/result`, so the observed live outcome is safe for the later durable `tool/result` append.
 
-Each interception waterfall returns a typed **Decision** (the idiom shared with the `agent/*` seams). `tools/pre-execute` listeners receive `(exec, next)` and return a `PreToolDecision`; `tools/execute` wrappers return a `ToolExecutionResult`; `tools/post-execute` listeners receive `(exec, result, next)` and return a `PostToolDecision`:
+Each interception waterfall returns a typed **Decision** (the idiom shared with the `agent/*` waterfalls). `tools/pre-execute` listeners receive `(exec, next)` and return a `PreToolDecision`; `tools/execute` wrappers return a `ToolExecutionResult`; `tools/post-execute` listeners receive `(exec, result, next)` and return a `PostToolDecision`:
 
 ```ts type-equiv
 /**
@@ -628,12 +628,12 @@ Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/i
 
 #### `tools/post-execute` — waterfall
 
-Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this seam as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this waterfall as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
 
 ```ts cordis-catalog
 /**
  * Accept, replace, enrich, or block a normalized dispatch result. `next()`
- * accepts it unchanged; thrown tools still reach this seam as errors. Async
+ * accepts it unchanged; thrown tools still reach this waterfall as errors. Async
  * listeners must observe `exec.signal`; after they settle, caller
  * cancellation replaces only a successful accepted outcome with the code
  * selected by whether the tool body was invoked.
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index acdf10a014..d312090b72 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -362,7 +362,7 @@ type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure
 
 在得到最终内容之前，注册表会物化候选结果；若内容、结构化错误、附加上下文或展示元数据无法物化，则会转为仍可到达 `finalizeContent` 的 JSON 安全 `isError` 结果。注册表恰好调用该回调一次，随后在 `tools/result` 之前立即物化并冻结已接受的结果，因此实时观察到的产出可安全用于后续持久化的 `tool/result` 追加。
 
-每个拦截 waterfall 返回一个类型化的 **Decision**（与 `agent/*` seam 共享的惯用模式）。`tools/pre-execute` 监听器接收 `(exec, next)` 并返回 `PreToolDecision`；`tools/execute` 包装层返回 `ToolExecutionResult`；`tools/post-execute` 监听器接收 `(exec, result, next)` 并返回 `PostToolDecision`：
+每个拦截 waterfall 返回一个类型化的 **Decision**（与 `agent/*` waterfall 共享的惯用模式）。`tools/pre-execute` 监听器接收 `(exec, next)` 并返回 `PreToolDecision`；`tools/execute` 包装层返回 `ToolExecutionResult`；`tools/post-execute` 监听器接收 `(exec, result, next)` 并返回 `PostToolDecision`：
 
 ```ts type-equiv
 /**
@@ -628,12 +628,12 @@ Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/i
 
 #### `tools/post-execute` — waterfall
 
-Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this seam as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts it unchanged; thrown tools still reach this waterfall as errors. Async listeners must observe `exec.signal`; after they settle, caller cancellation replaces only a successful accepted outcome with the code selected by whether the tool body was invoked. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
 
 ```ts cordis-catalog
 /**
  * Accept, replace, enrich, or block a normalized dispatch result. `next()`
- * accepts it unchanged; thrown tools still reach this seam as errors. Async
+ * accepts it unchanged; thrown tools still reach this waterfall as errors. Async
  * listeners must observe `exec.signal`; after they settle, caller
  * cancellation replaces only a successful accepted outcome with the code
  * selected by whether the tool body was invoked.
diff --git a/docs/subsystems/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
index b22cd94946..f5e4289b30 100644
--- a/docs/subsystems/web.i18n.yaml
+++ b/docs/subsystems/web.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 docs/subsystems/web.md
-web.md: f300bf2daef172fe4a69c00f36c804cf874c189d
-web.zh.md: 36afee9a964a0ad185242d5ee8f4f91689b1d295
+web.md: e6dc49353e50181b7844a658008edfa075cfedc3
+web.zh.md: 63f85a8d235e5c0778af8547251ebf2c299f036a
diff --git a/docs/subsystems/web.md b/docs/subsystems/web.md
index f300bf2dae..e6dc49353e 100644
--- a/docs/subsystems/web.md
+++ b/docs/subsystems/web.md
@@ -2,11 +2,11 @@
 
 English | [中文](web.zh.md)
 
-The web access seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) that spans **two capabilities** (search and fetch) on one `ctx.web` service, split across packages: interface ([dsh-web](../../packages/web/web), `ctx.web` + the provider registries), implementations ([dsh-web-search-exa](../../packages/web/web-search-exa), [dsh-web-search-perplexity](../../packages/web/web-search-perplexity), [dsh-web-search-deepseek](../../packages/web/web-search-deepseek), [dsh-web-fetch-local](../../packages/web/web-fetch-local)), and consumer ([dsh-tool-web](../../packages/web/tool-web), the `web_search`/`web_fetch` tool schemas). Web is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A search-provider swap does not change how the model asks for a query, and a fetch-implementation swap does not change how the model asks for a URL.
+The web access seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) that spans **two operations** (search and fetch) on one `ctx.web` service, split across packages: Service Definition ([dsh-web](../../packages/web/web), `ctx.web` + the provider registries), Service providers ([dsh-web-search-exa](../../packages/web/web-search-exa), [dsh-web-search-perplexity](../../packages/web/web-search-perplexity), [dsh-web-search-deepseek](../../packages/web/web-search-deepseek), [dsh-web-fetch-local](../../packages/web/web-fetch-local)), and Consumer ([dsh-tool-web](../../packages/web/tool-web), the `web_search`/`web_fetch` tool schemas). Web is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A search-provider swap does not change how the model asks for a query, and a fetch-provider swap does not change how the model asks for a URL.
 
 Source: [`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)
 
-## Why one seam for two capabilities
+## Why one capability has two operations
 
 Search and fetch share no request schema and no business logic, but they are deliberately one `ctx.web` middle layer: one provider-selection policy owner, one abort/error vocabulary, one product-facing "how this harness reaches the web" config surface. The cost is the parallel `searchX`/`fetchX` method pairs on the service; that parallelism is intentional, not a missed extraction. Providers register **capabilities** (a `WebSearchProvider` or `WebFetchProvider`), not tools; the model-facing names, schemas, prompt guidance, and presentation all live in the single `dsh-tool-web` consumer.
 
diff --git a/docs/subsystems/web.zh.md b/docs/subsystems/web.zh.md
index 36afee9a96..63f85a8d23 100644
--- a/docs/subsystems/web.zh.md
+++ b/docs/subsystems/web.zh.md
@@ -2,11 +2,11 @@
 
 [English](web.md) | 中文
 
-Web 访问 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)，在同一个 `ctx.web` 服务上横跨**两项能力**（search 与 fetch），并拆分到多个包：接口（[dsh-web](../../packages/web/web)，`ctx.web` + 提供方注册表）、实现（[dsh-web-search-exa](../../packages/web/web-search-exa)、[dsh-web-search-perplexity](../../packages/web/web-search-perplexity)、[dsh-web-search-deepseek](../../packages/web/web-search-deepseek)、[dsh-web-fetch-local](../../packages/web/web-fetch-local)）与消费方（[dsh-tool-web](../../packages/web/tool-web)，即 `web_search`/`web_fetch` 工具 schema）。Web 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换 search 提供方不会改变模型提交查询的方式，更换 fetch 实现也不会改变模型请求 URL 的方式。
+Web 访问 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)，在同一个 `ctx.web` 服务上横跨**两项操作**（search 与 fetch），并拆分到多个包：Service Definition（[dsh-web](../../packages/web/web)，`ctx.web` + 提供方注册表）、Service provider（[dsh-web-search-exa](../../packages/web/web-search-exa)、[dsh-web-search-perplexity](../../packages/web/web-search-perplexity)、[dsh-web-search-deepseek](../../packages/web/web-search-deepseek)、[dsh-web-fetch-local](../../packages/web/web-fetch-local)）与 Consumer（[dsh-tool-web](../../packages/web/tool-web)，即 `web_search`/`web_fetch` 工具 schema）。Web 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换 search 提供方不会改变模型提交查询的方式，更换 fetch 提供方也不会改变模型请求 URL 的方式。
 
 源码：[`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)
 
-## 为什么两项能力合为一个 seam
+## 为什么一项能力包含两项操作
 
 搜索与抓取既不共享请求 schema，也不共享业务逻辑，但它们被有意设计为同一个 `ctx.web` 中间层：一个提供方选择策略的所有者、一套中止与错误词汇，以及一个面向产品的「此 harness 如何访问 Web」配置界面。代价是服务上并行的 `searchX`／`fetchX` 方法对；这种并行是有意为之，而不是遗漏了可抽取的共性。提供方注册的是**能力**（`WebSearchProvider` 或 `WebFetchProvider`），而非工具；面向模型的名称、schema、提示词引导与展示全部集中在唯一的消费方 `dsh-tool-web` 中。
 
diff --git a/docs/subsystems/workflow.i18n.yaml b/docs/subsystems/workflow.i18n.yaml
index fed94d62bc..f1ddf20d11 100644
--- a/docs/subsystems/workflow.i18n.yaml
+++ b/docs/subsystems/workflow.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 docs/subsystems/workflow.md
-workflow.md: c87e88f1e1dddcd57822e47e5773dba127f9cdcf
-workflow.zh.md: 57d69ffd5300a6b4d6e037758a75c19e9ccd51a7
+workflow.md: 4c552b31435963d4133a31f2e98f8a913305c1f8
+workflow.zh.md: 53ef84134b00e323bd5331ff30b18012124b5241
diff --git a/docs/subsystems/workflow.md b/docs/subsystems/workflow.md
index c87e88f1e1..4c552b3143 100644
--- a/docs/subsystems/workflow.md
+++ b/docs/subsystems/workflow.md
@@ -4,7 +4,7 @@ English | [中文](workflow.zh.md)
 
 The workflow seam — an agent running a model-written orchestration SCRIPT that fans out subagents. Like [subagent](subagent.md) it is **one optional capability**, not part of the agent-loop spine, so its vocabulary lives here rather than in [core.md](core.md). Unlike the subagent registry it takes the bash shape: ONE engine implementation per context provides `ctx.workflows`; there is no named-provider registry (a second engine is a plugin swap, not a co-resident).
 
-Interface: [dsh-workflow](../../packages/workflow/workflow) (`ctx.workflows` + the vocabulary below). The implementation is [dsh-workflow-workerthread](../../packages/workflow/workflow-workerthread) (a `node:worker_threads` engine — one worker per run, the script's vm context inside it); the model-facing consumer is [dsh-tool-workflow](../../packages/workflow/tool-workflow). The proposal and rationale: [the dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md).
+Service Definition: [dsh-workflow](../../packages/workflow/workflow) (`ctx.workflows` + the vocabulary below). The Service provider is [dsh-workflow-workerthread](../../packages/workflow/workflow-workerthread) (a `node:worker_threads` engine — one worker per run, the script's vm context inside it); the model-facing Consumer is [dsh-tool-workflow](../../packages/workflow/tool-workflow). The proposal and rationale: [the dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md).
 
 Source: [`packages/workflow/workflow/src/types.ts`](../../packages/workflow/workflow/src/types.ts)
 
@@ -139,11 +139,11 @@ The `workflow/*` events (`workflow/start`, `workflow/phase`, `workflow/log`, `wo
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxworkflows--workflowservice"></a>
+<a id="ctxworkflows--workflowservice-abstract-seam"></a>
 
-### `ctx.workflows` — `WorkflowService`
+### `ctx.workflows` — `WorkflowService` (abstract seam)
 
-Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
+Workflow Service Definition contract. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
 
 ```ts cordis-catalog
 /**
diff --git a/docs/subsystems/workflow.zh.md b/docs/subsystems/workflow.zh.md
index 57d69ffd53..53ef84134b 100644
--- a/docs/subsystems/workflow.zh.md
+++ b/docs/subsystems/workflow.zh.md
@@ -4,7 +4,7 @@
 
 工作流 seam 允许 agent（智能体）运行由模型编写的编排脚本，并由该脚本扇出 subagent。与 [subagent](subagent.md) 一样，它是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此处而非 [core.md](core.md)。与 subagent 注册表不同，它采用 bash 形态：每个上下文只有一个引擎实现提供 `ctx.workflows`；没有命名提供方注册表（第二个引擎是插件替换，而非共存）。
 
-接口：[dsh-workflow](../../packages/workflow/workflow)（`ctx.workflows` + 下文词汇）。实现是 [dsh-workflow-workerthread](../../packages/workflow/workflow-workerthread)（一个 `node:worker_threads` 引擎——每个 run 一个 worker，脚本的 vm 上下文位于其中）；面向模型的消费方是 [dsh-tool-workflow](../../packages/workflow/tool-workflow)。提案与设计理由见 [dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
+Service Definition：[dsh-workflow](../../packages/workflow/workflow)（`ctx.workflows` + 下文词汇）。Service provider 是 [dsh-workflow-workerthread](../../packages/workflow/workflow-workerthread)（一个 `node:worker_threads` 引擎——每个 run 一个 worker，脚本的 vm 上下文位于其中）；面向模型的 Consumer 是 [dsh-tool-workflow](../../packages/workflow/tool-workflow)。提案与设计理由见 [dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
 
 源码：[`packages/workflow/workflow/src/types.ts`](../../packages/workflow/workflow/src/types.ts)
 
@@ -139,11 +139,11 @@ interface WorkflowRun {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxworkflows--workflowservice"></a>
+<a id="ctxworkflows--workflowservice-abstract-seam"></a>
 
-### `ctx.workflows` — `WorkflowService`
+### `ctx.workflows` — `WorkflowService` (abstract seam)
 
-Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
+Workflow Service Definition contract. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
 
 ```ts cordis-catalog
 /**
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index 1b94464e30..b2c2248876 100644
--- a/docs/subsystems/workspace.i18n.yaml
+++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md
-workspace.md: 21b08bd8b0936e9c7357ad15e7ff4176a981a042
-workspace.zh.md: 30bfc0054880ca82b5f7c64780d405524656a1f1
+workspace.md: ca088a2091a7f47a3d52992fec13fae44061a608
+workspace.zh.md: e414c759a043f934e1a8b5d89c7a3b6101bbb6f4
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index 21b08bd8b0..ca088a2091 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -133,9 +133,9 @@ Sessions get their cwd at create time from whoever creates them, not from this r
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxdirectorypicker--directorypicker"></a>
+<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
 
-### `ctx.directoryPicker` — `DirectoryPicker`
+### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
 
 Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
 
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index 30bfc00548..e414c759a0 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -133,9 +133,9 @@ interface Workspace {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxdirectorypicker--directorypicker"></a>
+<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
 
-### `ctx.directoryPicker` — `DirectoryPicker`
+### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
 
 Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
 
diff --git a/docs/user/develop/basic/tool.i18n.yaml b/docs/user/develop/basic/tool.i18n.yaml
index cb9759860e..594e2c2872 100644
--- a/docs/user/develop/basic/tool.i18n.yaml
+++ b/docs/user/develop/basic/tool.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 docs/user/develop/basic/tool.md
-tool.md: 8505bdaf6fcece3235b0302d54e82ee8aed3cbab
-tool.zh.md: c6c579c5da9dc545c2795e65331810528c37219f
+tool.md: ba2f3b1302ba31735d67be264f498a0395394d06
+tool.zh.md: 676f8fc996d752a05d94b55d4522e61e3b3e2161
diff --git a/docs/user/develop/basic/tool.md b/docs/user/develop/basic/tool.md
index 8505bdaf6f..ba2f3b1302 100644
--- a/docs/user/develop/basic/tool.md
+++ b/docs/user/develop/basic/tool.md
@@ -49,4 +49,4 @@ Open `http://127.0.0.1:3080` and ask: `Use the greet tool to greet Ada.` The mod
 
 - [Plugin configuration](./config.md) — make the greeting configurable.
 - [Tool authoring reference](../../../cookbook/adding-a-tool.md) — look up nested schemas, canonical values, background work, policy hooks, Code Mode, and UI cards.
-- [Capability layering](../practice/) — split a replaceable capability into interface, implementation, and consumer packages.
+- [Capability layering](../practice/) — split a replaceable capability into Service Definition, Service provider, and Consumer packages.
diff --git a/docs/user/develop/basic/tool.zh.md b/docs/user/develop/basic/tool.zh.md
index c6c579c5da..676f8fc996 100644
--- a/docs/user/develop/basic/tool.zh.md
+++ b/docs/user/develop/basic/tool.zh.md
@@ -49,4 +49,4 @@ pnpm run dsh web --patch ./scratch-plugin/cordis.yml
 
 - [插件配置](./config.md) — 让问候语可配置。
 - [工具编写参考](../../../cookbook/adding-a-tool.md) — 查阅嵌套 schema、规范值、后台工作、策略钩子、Code Mode 和 UI 卡片。
-- [能力分层](../practice/) — 将可替换能力拆分为接口、实现和消费方包。
+- [能力分层](../practice/) — 将可替换能力拆分为 Service Definition、Service provider 和 Consumer 包。
diff --git a/docs/user/develop/practice/index.i18n.yaml b/docs/user/develop/practice/index.i18n.yaml
index 65057da78e..24ae066e89 100644
--- a/docs/user/develop/practice/index.i18n.yaml
+++ b/docs/user/develop/practice/index.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 docs/user/develop/practice/index.md
-index.md: c3306725f47993aa9d3322423261a260754c1d5f
-index.zh.md: 3609cbce21e17ce9ca0a40b69999b293dee29012
+index.md: 6ae9fd152ca2e3b82bdb1ea9b3aa3d348ebfce66
+index.zh.md: 0056a81402761310fe5f0463b83762d98ed9745f
diff --git a/docs/user/develop/practice/index.md b/docs/user/develop/practice/index.md
index c3306725f4..6ae9fd152c 100644
--- a/docs/user/develop/practice/index.md
+++ b/docs/user/develop/practice/index.md
@@ -1,25 +1,25 @@
-# Three-layer capability design
+# Three-role capability design
 
 English | [中文](index.zh.md)
 
-This page has two parts: a concept reference for the three-layer capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/) and [services tutorial](../framework/service.md) first.
+This page has two parts: a concept reference for the three-role capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/) and [services tutorial](../framework/service.md) first.
 
 ## Concept reference
 
-When a capability is general enough to need replaceable implementations, such as Bash execution, Harness splits it into three packages: an **interface**, an **implementation**, and a **consumer**. Each layer can evolve or be replaced independently.
+When a capability is general enough to need replaceable providers, such as Bash execution, Harness separates three roles: a **Service Definition**, a **Service provider**, and a **Consumer**. Put the roles in separate packages when they need to evolve or be replaced independently; a package may otherwise own more than one role. The complete capability is its seam. No individual role is a seam.
 
 ## Bash example
 
 The Bash execution capability consists of:
 
-- **Interface** (`dsh-bash`) — defines Bash request and result shapes
-- **Implementation** (`dsh-bash-local`) — executes commands on the local machine
+- **Service Definition** (`dsh-bash`) — defines the Cordis service and Bash request/result vocabulary
+- **Service provider** (`dsh-bash-local`) — supplies local command execution
 - **Consumer** (`dsh-tool-bash`) — exposes the capability as a model-callable tool
 
 ```
 ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
 │  dsh-bash   │────▶│  dsh-bash-local  │     │ dsh-tool-bash│
-│ (interface) │     │ (implementation) │     │(consumer/tool)│
+│(definition) │     │    (provider)     │     │(consumer/tool)│
 └─────────────┘     └──────────────────┘     └──────────────┘
        ▲                                            │
        └────────────────────────────────────────────┘
@@ -28,36 +28,36 @@ The Bash execution capability consists of:
 
 ## Benefits of the split
 
-### Replace implementations
+### Replace providers
 
-One interface can have multiple implementations selected through `cordis.yml`:
+One Service Definition can have multiple providers selected through `cordis.yml`:
 
 ```yaml
 # Local execution
 - name: '@deepseek-ai/dsh-bash-local'
 
-# Replace this row with another package that implements the same service.
+# Replace this row with another package that provides the same service.
 ```
 
-The interface and tool remain unchanged while the implementation changes.
+The Service Definition and tool remain unchanged while the provider changes.
 
 ### Evolve independently
 
-- The interface changes rarely after its contract stabilizes.
-- Implementations can improve performance and security independently.
+- The Service Definition changes rarely after its contract stabilizes.
+- Service providers can improve performance and security independently.
 - Consumers can change how they present the capability to the model.
 
 ### Decouple dependencies
 
-- The implementation depends on the interface.
-- The consumer depends on the interface.
-- The implementation and consumer **do not depend on each other**.
+- The Service provider depends on the Service Definition.
+- The Consumer depends on the Service Definition.
+- The Service provider and Consumer **do not depend on each other**.
 
 The [capability-seam reference](../../../capability-seams.md) owns the current built-in families and package links.
 
-## Tutorial: develop a three-layer capability
+## Tutorial: develop a three-role capability
 
-### Step 1: define the interface
+### Step 1: write the Service Definition
 
 ```ts ignore-check
 // packages/my-cap/my-cap/src/index.ts
@@ -87,7 +87,7 @@ export interface MyCapResult {
 }
 ```
 
-### Step 2: write an implementation
+### Step 2: write a Service provider
 
 ```ts ignore-check
 // packages/my-cap/my-cap-local/src/index.ts
@@ -96,7 +96,7 @@ import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/
 
 class MyCapLocal extends MyCapService {
   async execute(request: MyCapRequest): Promise<MyCapResult> {
-    // Concrete implementation.
+    // Local provider behavior.
     return { output: request.input.toUpperCase() }
   }
 }
@@ -146,10 +146,10 @@ export function apply(ctx: Context) {
 
 ## Design points
 
-- **Do not split preemptively** — use three packages only when the capability needs replaceable implementations. A simple tool plugin does not.
-- **The interface owns Request/Result types** — implementations and consumers depend only on the interface package.
+- **Do not split preemptively** — use separate packages only when the roles need to evolve independently. A simple tool plugin does not.
+- **The Service Definition owns Request/Result types** — Service providers and Consumers depend only on the Service Definition package.
 - **Explicit > implicit** — resolve defaults in an explicit `resolve(request): Spec` step rather than hiding `?? default` expressions inside `run()`.
 
 ## Next steps
 
-- [LLM adapter](./llm-adapter.md) — implement an LLM backend, a common capability interface extension
+- [LLM adapter](./llm-adapter.md) — implement an LLM provider
diff --git a/docs/user/develop/practice/index.zh.md b/docs/user/develop/practice/index.zh.md
index 3609cbce21..0056a81402 100644
--- a/docs/user/develop/practice/index.zh.md
+++ b/docs/user/develop/practice/index.zh.md
@@ -1,25 +1,25 @@
-# 能力的三层拆分
+# 能力的三种角色设计
 
 [English](index.md) | 中文
 
-本文分为两部分：先参考三层能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
+本文分为两部分：先参考三种角色能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
 
 ## 概念参考
 
-当一项能力足够通用，需要支持可替换的实现时（例如 Bash 执行），Harness 会将其拆成三个包：**接口**、**实现**和**消费方**。这样便可独立替换其中任何一层。
+当一项能力足够通用，需要支持可替换的提供方时（例如 Bash 执行），Harness 会区分三种角色：**Service Definition**、**Service provider** 和 **Consumer**。角色需要独立演进或替换时，将它们放入不同包；否则一个包可以承担多个角色。完整能力构成其 seam。任何单一角色都不是 seam。
 
 ## 以 Bash 为例
 
 以 Bash 执行能力为例：
 
-- **接口** (`dsh-bash`)：定义 Bash 请求和结果的结构
-- **实现** (`dsh-bash-local`)：在本地计算机上执行命令
-- **消费方** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
+- **Service Definition** (`dsh-bash`)：定义 Cordis 服务以及 Bash 请求／结果词汇
+- **Service provider** (`dsh-bash-local`)：提供本地命令执行
+- **Consumer** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
 
 ```
 ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
 │  dsh-bash   │────▶│  dsh-bash-local  │     │ dsh-tool-bash│
-│ (interface) │     │ (implementation) │     │(consumer/tool)│
+│(definition) │     │    (provider)     │     │(consumer/tool)│
 └─────────────┘     └──────────────────┘     └──────────────┘
        ▲                                            │
        └────────────────────────────────────────────┘
@@ -28,36 +28,36 @@
 
 ## 拆分的好处
 
-### 具体实现可替换
+### 提供方可替换
 
-同一个接口可以有多种实现。用户通过 `cordis.yml` 选择：
+同一个 Service Definition 可以有多个提供方。用户通过 `cordis.yml` 选择：
 
 ```yaml
 # Local execution
 - name: '@deepseek-ai/dsh-bash-local'
 
-# Replace this row with another package that implements the same service.
+# Replace this row with another package that provides the same service.
 ```
 
-更换实现时，接口和工具均保持不变。
+更换提供方时，Service Definition 和工具均保持不变。
 
 ### 独立演进
 
-- 接口定义稳定后很少改动
-- 实现可以独立优化（性能、安全）
-- 消费方可以调整能力向模型呈现的方式。
+- Service Definition 的约定稳定后很少改动
+- Service provider 可以独立优化性能和安全性
+- Consumer 可以调整能力向模型呈现的方式。
 
 ### 依赖解耦
 
-- 实现依赖接口。
-- 消费方依赖接口。
-- 实现和消费方**互不依赖**。
+- Service provider 依赖 Service Definition。
+- Consumer 依赖 Service Definition。
+- Service provider 和 Consumer **互不依赖**。
 
 当前内置系列及其包链接由[能力 seam 参考](../../../capability-seams.md)负责。
 
-## 教程：开发三层能力
+## 教程：开发三种角色的能力
 
-### 第一步：定义接口
+### 第一步：编写 Service Definition
 
 ```ts ignore-check
 // packages/my-cap/my-cap/src/index.ts
@@ -87,7 +87,7 @@ export interface MyCapResult {
 }
 ```
 
-### 第二步：编写实现
+### 第二步：编写 Service provider
 
 ```ts ignore-check
 // packages/my-cap/my-cap-local/src/index.ts
@@ -96,7 +96,7 @@ import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/
 
 class MyCapLocal extends MyCapService {
   async execute(request: MyCapRequest): Promise<MyCapResult> {
-    // Concrete implementation.
+    // Local provider behavior.
     return { output: request.input.toUpperCase() }
   }
 }
@@ -146,10 +146,10 @@ export function apply(ctx: Context) {
 
 ## 设计要点
 
-- **不要预防性拆分**：只有确实需要可替换实现时，才拆分为三个包。简单的工具插件无需拆分。
-- **接口拥有 Request/Result 类型**：实现和消费方只依赖接口包。
+- **不要预防性拆分**：只有角色需要独立演进时，才使用不同包。简单的工具插件无需拆分。
+- **Service Definition 拥有 Request/Result 类型**：Service provider 和 Consumer 只依赖 Service Definition 包。
 - **显式优于隐式**：实现应通过显式的 `resolve(request): Spec` 步骤处理默认值，而不是在 `run()` 中隐藏 `?? default`。
 
 ## 下一步
 
-- [LLM 适配器](./llm-adapter.md)：实现一个 LLM 后端，这是一种常见的能力 seam 扩展
+- [LLM 适配器](./llm-adapter.md)：实现一个 LLM 提供方
diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml
index 10e4f2429b..d54550f499 100644
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.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 docs/user/guide/config.md
-config.md: 34ab38c60cc7a9b6026f5be2be47f440eb6cb08d
+config.md: 3ce797e3dc91a279de1076a234c9ba0b476b3501
 config.zh.md: 621b5a75a98ab4b8d8517f4ec8894db0472e994c
diff --git a/docs/user/guide/config.md b/docs/user/guide/config.md
index 34ab38c60c..3ce797e3dc 100644
--- a/docs/user/guide/config.md
+++ b/docs/user/guide/config.md
@@ -64,4 +64,4 @@ The tag is `!!js`, not `!js`.
 
 ## Exact configuration reference
 
-The generated [plugin configuration catalog](../../config-catalog.md) lists every current field, type, and default. For composition concepts, continue to the [architecture](../../architecture.md) and [capability interfaces](../../capability-seams.md). To create a configuration, copy the closest entry from the [examples overview](../../../examples/README.md) and adapt it.
+The generated [plugin configuration catalog](../../config-catalog.md) lists every current field, type, and default. For composition concepts, continue to the [architecture](../../architecture.md) and [capability seams](../../capability-seams.md). To create a configuration, copy the closest entry from the [examples overview](../../../examples/README.md) and adapt it.
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index 62a1a674d5..b0b646eade 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -398,7 +398,7 @@ const SCENARIOS: Scenario[] = [
   // the real Loader/app path, rather than retaining the earlier valid group.
   { name: 'hook-cc-invalid-matcher', hasModelTurn: true, recorded: false },
   { name: 'hook-codex-invalid-matcher', hasModelTurn: true, recorded: false },
-  // The mid-turn seams fire during a real model turn, so each is recorded with its hook active
+  // The mid-turn interception points fire during a real model turn, so each is recorded with its hook active
   // (the model's reaction to a deny/block/force-continue is part of the captured transcript).
   // SessionStart/SubagentStart are excluded because detached injection races log
   // order; SubagentStop writes no transcript, so an expected output could not prove it ran.
diff --git a/native/landlock-run/AGENTS.md b/native/landlock-run/AGENTS.md
index 6742ff81d4..29bf66fa9d 100644
--- a/native/landlock-run/AGENTS.md
+++ b/native/landlock-run/AGENTS.md
@@ -18,10 +18,10 @@ The project is pre-1.0. Prefer the correct public shape over compatibility shims
 ## Repository layout
 
 ```text
-packages/entry/     Published entry package: JS seam (resolve/probe/grants) + the C source.
+packages/entry/     Published entry package: JavaScript API (resolve/probe/grants) + the C source.
 packages/linux-*/   Published per-platform packages: one prebuilt static binary, no JavaScript.
 scripts/            Build, matrix derivation, prepack gates, and release orchestration.
-test/               Plain-node behavioral tests (entry seam + real-kernel launcher proofs).
+test/               Plain-node behavioral tests (entry API + real-kernel launcher proofs).
 docs/               Architecture, packaging, CLI contract, release, support matrix, naming.
 ```
 
diff --git a/native/landlock-run/docs/architecture.md b/native/landlock-run/docs/architecture.md
index 458281bf29..33c71d6893 100644
--- a/native/landlock-run/docs/architecture.md
+++ b/native/landlock-run/docs/architecture.md
@@ -1,6 +1,6 @@
 # Architecture
 
-This repository owns confinement *mechanism*, not policy: consumers (agent harnesses, sandbox seams) decide which paths a run may read or write; this package family provides the launcher that enforces those grants and the JS seam that resolves and speaks to it. The packaging follows the per-platform-package model of [`node-addon-require-builtin`](https://www.npmjs.com/package/@esplus/node-addon-require-builtin) (and esbuild), adapted from Node addons to standalone static executables.
+This repository owns confinement *mechanism*, not policy: consumers (agent harnesses and sandbox capabilities) decide which paths a run may read or write; this package family provides the launcher that enforces those grants and the JavaScript API that resolves and speaks to it. The packaging follows the per-platform-package model of [`node-addon-require-builtin`](https://www.npmjs.com/package/@esplus/node-addon-require-builtin) (and esbuild), adapted from Node addons to standalone static executables.
 
 ## Two-layer package family
 
diff --git a/native/landlock-run/packages/entry/src/index.ts b/native/landlock-run/packages/entry/src/index.ts
index ec909f928a..2bb0699381 100644
--- a/native/landlock-run/packages/entry/src/index.ts
+++ b/native/landlock-run/packages/entry/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The JS seam over the prebuilt `landlock-run` launcher: resolve the
+ * The JavaScript API over the prebuilt `landlock-run` launcher: resolve the
  * binary for this host, build its grant argv, and run its functional probe.
  *
  * This module owns the launcher's CLI contract (`docs/cli-contract.md`) so
@@ -61,7 +61,7 @@ export interface LauncherGrants {
  * deliberately not checked either way: {@link probe} is the single
  * availability signal (a missing binary probes `unusable` the same way an
  * unenforcing kernel does).
- * @param resolvePackageJson - test seam over `require.resolve` (the default
+ * @param resolvePackageJson - test hook over `require.resolve` (the default
  *   covers real installs); receives the platform package's `package.json`
  *   specifier and returns its absolute path, throwing when unresolvable.
  * @returns the absolute launcher path to probe and exec.
diff --git a/native/landlock-run/test/entry.test.js b/native/landlock-run/test/entry.test.js
index 2b535559a2..76e2e4321a 100644
--- a/native/landlock-run/test/entry.test.js
+++ b/native/landlock-run/test/entry.test.js
@@ -1,6 +1,6 @@
 /**
  * Keyless entry-package tests — run on every host, no kernel or binary
- * required. Cover the JS seam's pure surface: grant-argv construction, the
+ * required. Cover the JavaScript API's pure surface: grant-argv construction, the
  * resolution contract (platform package → fallback), and probe verdicts over
  * fake launchers. Requires built `lib/` (`pnpm build:ts`).
  */
diff --git a/packages/AGENTS.md b/packages/AGENTS.md
index 58db577ee5..6cff1b6327 100644
--- a/packages/AGENTS.md
+++ b/packages/AGENTS.md
@@ -7,7 +7,7 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md
 - **Product-visible plugins require a non-unit REAL-composition test.** Hand-built `ctx.plugin(...)` suites are insufficient. Boot test-only `cordis.yml` through the Loader and app/process; mock only external/nondeterministic boundaries and assert model-visible, durable, or user-visible output. Keep opt-ins out of shipped defaults. [Policy](../docs/testing.md).
 - **Initiator-owned private chains derive, then capture.** Under `ctx.agents.withInitiator()`, recover the Agent at each orchestration entry, derive `agent.session`, and let operation-local helpers close over it. Keep `Agent` and `Session` explicit at lifecycle, session-log, service, authority, worker/process, persistence, and wire interfaces; do not widen a leaf helper from `Session` to `Context` merely to hide a parameter ([rationale](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
 - **Represent one asynchronous operation with one lifecycle controller or transaction.** Separate readiness, cancellation, disposal, reservation, or sentinel state requires an independent owner or settlement boundary; otherwise fold it while preserving rollback, callback containment, and quiescence.
-- **Shape capability interfaces around all current consumers.** Keep tool-schema, Loader, UI, transport, and backend-specific behavior in the consumer or adapter; do not let one consumer dictate the interface ([capability-seam rationale](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)). Inverse smell: a public service method with one internal caller — pass a private capability closure instead (`RunCodeBridgeOptions`).
+- **Shape Service Definitions around all current Consumers.** Keep tool-schema, Loader, UI, transport, and provider-specific behavior in the Consumer or provider; do not let one Consumer dictate the service contract ([capability-seam rationale](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)). Inverse smell: a public service method with one internal caller — pass a private capability closure instead (`RunCodeBridgeOptions`).
 - **Require a current owner and need.** Tie each abstraction, state machine, option, defensive copy, and compatibility path to a current contract or production consumer, and keep behavior in its owning plugin or service.
 - **Require evidence for public choices.** Configurability does not justify an unsupported default, public operation set, format, or imported external concept. Use current-consumer evidence or relevant prior art; otherwise require an explicit value or defer the choice.
 - **Write model-facing contracts from the model's perspective.** Prompts, tool schemas, results, and diagnostics contain only task-relevant concepts, not UI, transport, or implementation vocabulary. Pin stable model-visible text verbatim and dynamic behavior through snapshots or end-to-end coverage.
diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml
index 25b3709d91..27f5c79ca4 100644
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 7589f37b174b94558bff9f74f860bb4b42705fb8
-README.zh.md: e7b8b0ab2b5bb5bd38d7068091bc675e1d27f84a
+README.md: eff1d9522e3ca6e8a7efaa20463d73036101f8f5
+README.zh.md: cc2d37d3999e2e59095a8000feb3f963d0b4e4a1
diff --git a/packages/README.md b/packages/README.md
index 7589f37b17..eff1d9522e 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -17,19 +17,19 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
 | [`e2b/`](e2b/README.md) | E2B providers | POC |
-| [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
+| [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition + local process-tree provider | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: Service Definition + worker-thread provider + Code Mode Consumer | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable surface |
 | [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface |
 | [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
-| [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
+| [`compact/`](compact/README.md) | Compaction capability family: Service Definition + basic provider + command Consumer | Product — stable surface |
 | [`context/`](context/README.md) | Model-visible request context, including workspace instructions and time context | Product — stable surface |
-| [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
+| [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry contract and the model-facing delegation tool | Product — stable surface |
 | [`tasks/`](tasks/README.md) | Generic background-task runtime and model-facing `task_*` control tools | Product — stable surface |
-| [`workflow/`](workflow/README.md) | Script seam, worker-thread engine, and model-facing `workflow`/`ralph` tools | Product — stable surface |
+| [`workflow/`](workflow/README.md) | Workflow seam, worker-thread engine, and model-facing `workflow`/`ralph` tools | Product — stable surface |
 | [`web/`](web/README.md) | Web capability family: seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
 | [`spill/`](spill/README.md) | Spill capability family: storage seam, local impl, tool-result spill policy | Product — stable surface |
 | [`todo/`](todo/README.md) | The model-facing `todo_write` tool | Product — stable surface |
@@ -61,6 +61,6 @@ New packages join existing groups; new groups update their README and this table
 
 The dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI).
 
-**Extension plugins depend on interfaces, never the concrete loop.** `dsh-agent-loop` is swappable; UI, hook, and tool plugins use `dsh-agent`. Composition bundles, including `dsh-agent-spine-demo`, may depend on spine plugins. Capabilities split into interface / implementation / consumer packages; see [capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md).
+**Extension plugins depend on Service Definitions, never concrete providers.** `dsh-agent-loop` is swappable; UI, hook, and tool plugins use `dsh-agent`. Composition bundles, including `dsh-agent-spine-demo`, may depend on spine plugins. Capabilities separate Service Definition / Service provider / Consumer roles when they evolve independently; see [capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md).
 
 Package READMEs cover purpose, APIs, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless on the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts). They also carry `## Known Limitations and Deferred Work` or use its [allowlist](../scripts/verify-package-readme-limitations.ts).
diff --git a/packages/README.zh.md b/packages/README.zh.md
index e7b8b0ab2b..cc2d37d399 100644
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -17,19 +17,19 @@
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定接口 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定接口 |
 | [`e2b/`](e2b/README.md) | E2B 提供方 | POC |
-| [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定接口 |
+| [`subprocess/`](subprocess/README.md) | 进程管理能力系列：Service Definition + 本地进程树提供方 | 产品：稳定接口 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定接口 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定接口 |
-| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：面向模型所写程序的运行时 seam + worker 线程后端 | 产品：稳定接口 |
+| [`code-runtime/`](code-runtime/README.md) | 代码执行能力系列：Service Definition + worker 线程提供方 + Code Mode Consumer | 产品：稳定接口 |
 | [`sandbox/`](sandbox/README.md) | 进程限制 seam；bwrap/Landlock/Seatbelt 后端 | 产品：稳定接口 |
 | [`fs/`](fs/README.md) | 文件系统能力系列：seam、本地实现、面向模型的文件工具、bash 后端发现工具 | 产品：稳定接口 |
 | [`lsp/`](lsp/README.md) | LSP 能力系列：seam、通用 stdio 提供方和 `lsp` 工具 | 产品：稳定接口 |
 | [`skill/`](skill/README.md) | skill（技能）能力系列：提供方注册表、本地提供方和面向模型的目录／加载器 | 产品：稳定接口 |
-| [`compact/`](compact/README.md) | 压缩（compaction）能力系列：抽象 seam + 基础后端（工具延后） | 产品：稳定接口 |
+| [`compact/`](compact/README.md) | 压缩（compaction）能力系列：Service Definition + 基础提供方 + 命令 Consumer | 产品：稳定接口 |
 | [`context/`](context/README.md) | 模型可见请求上下文，包括 workspace 指令和时间上下文 | 产品：稳定接口 |
-| [`subagent/`](subagent/README.md) | subagent 能力系列：提供方注册表 seam 和面向模型的委托工具 | 产品：稳定接口 |
+| [`subagent/`](subagent/README.md) | subagent 能力系列：提供方注册表约定和面向模型的委托工具 | 产品：稳定接口 |
 | [`tasks/`](tasks/README.md) | 通用后台任务运行时和面向模型的 `task_*` 控制工具 | 产品：稳定接口 |
-| [`workflow/`](workflow/README.md) | 脚本 seam、worker 线程引擎和面向模型的 `workflow`/`ralph` 工具 | 产品：稳定接口 |
+| [`workflow/`](workflow/README.md) | 工作流 seam、worker 线程引擎和面向模型的 `workflow`/`ralph` 工具 | 产品：稳定接口 |
 | [`web/`](web/README.md) | Web 能力系列：seam、搜索／获取提供方实现和面向模型的 Web 工具 | 产品：稳定接口 |
 | [`spill/`](spill/README.md) | spill 能力系列：存储 seam、本地实现、工具结果 spill 策略 | 产品：稳定接口 |
 | [`todo/`](todo/README.md) | 面向模型的 `todo_write` 工具 | 产品：稳定接口 |
@@ -61,6 +61,6 @@
 
 依赖图由工具生成：[docs/module-graph.md](../docs/module-graph.md)（`pnpm run gen-module-graph`，CI 中有新鲜度门禁）。
 
-**扩展插件依赖接口，绝不依赖具体循环。** `dsh-agent-loop` 可替换；UI、钩子和工具插件使用 `dsh-agent`。包括 `dsh-agent-spine-demo` 在内的组合包可以依赖主干插件。能力拆分为接口／实现／消费方包；详见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)。
+**扩展插件依赖 Service Definition，绝不依赖具体提供方。** `dsh-agent-loop` 可替换；UI、钩子和工具插件使用 `dsh-agent`。包括 `dsh-agent-spine-demo` 在内的组合包可以依赖主干插件。能力在 Service Definition／Service provider／Consumer 角色需要独立演进时将其分离；详见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)。
 
 包 README 覆盖用途、API、扩展点和[模型体验](../docs/cookbook/adding-a-package.md#4-write-the-package-readme)；列入模型无关[省略允许清单](../scripts/verify-package-readme-model-experience.ts)的包除外。它们还要包含 `## Known Limitations and Deferred Work`，或使用其[允许清单](../scripts/verify-package-readme-limitations.ts)。
diff --git a/packages/bash/README.i18n.yaml b/packages/bash/README.i18n.yaml
index a55672b9e1..7860ae302e 100644
--- a/packages/bash/README.i18n.yaml
+++ b/packages/bash/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/bash/README.md
-README.md: 7395a051742af24b96842966b71297dc01853dca
-README.zh.md: 043394f429d406a6d14f00b6d8a0384bd022abe0
+README.md: edffdd67a982a885b7e3e537be77c8971f5b697b
+README.zh.md: 8cb56f38df4999cb2055b9e2808ce092bc7a8282
diff --git a/packages/bash/README.md b/packages/bash/README.md
index 7395a05174..edffdd67a9 100644
--- a/packages/bash/README.md
+++ b/packages/bash/README.md
@@ -6,7 +6,7 @@ The capability family spans the canonical executor seam, its implementations, th
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`bash/`](bash/README.md) | Defines the executor contract shared by implementations and consumers. | `ctx.bash` |
+| [`bash/`](bash/README.md) | Defines the executor contract shared by Service providers and Consumers. | `ctx.bash` |
 | [`bash-local/`](bash-local/README.md) | Executes commands through the local [`subprocess`](../subprocess/README.md) service. | (registers `ctx.bash`) |
 | [`bash-sandbox/`](bash-sandbox/README.md) | Applies the configured [`sandbox`](../sandbox/README.md) backend before local execution. | (registers `ctx.bash`) |
 | [`pwsh-local/`](pwsh-local/README.md) | Executes PowerShell commands with Windows-specific process behavior. | (registers `ctx.bash`) |
diff --git a/packages/bash/README.zh.md b/packages/bash/README.zh.md
index 043394f429..8cb56f38df 100644
--- a/packages/bash/README.zh.md
+++ b/packages/bash/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-该能力家族涵盖规范的执行器 seam、其实现、共享 shell 环境和面向模型的工具。这些全是**产品**包。
+该能力家族涵盖规范执行器 seam、其实现、共享 shell 环境和面向模型的工具。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`bash/`](bash/README.md) | 定义实现与消费方共享的执行器约定。 | `ctx.bash` |
+| [`bash/`](bash/README.md) | 定义 Service provider 与 Consumer 共享的执行器约定。 | `ctx.bash` |
 | [`bash-local/`](bash-local/README.md) | 通过本地 [`subprocess`](../subprocess/README.md) 服务执行命令。 | （注册 `ctx.bash`） |
 | [`bash-sandbox/`](bash-sandbox/README.md) | 在本地执行前应用已配置的 [`sandbox`](../sandbox/README.md) 后端。 | （注册 `ctx.bash`） |
-| [`pwsh-local/`](pwsh-local/README.md) | 采用 Windows 特有的进程行为执行 PowerShell 命令。 | （注册 `ctx.bash`） |
-| [`bash-env/`](bash-env/README.md) | 提供 shell 工具共享的受管 `DSH_*` 环境。 | `ctx.bashEnv` |
+| [`pwsh-local/`](pwsh-local/README.md) | 以 Windows 专用进程行为执行 PowerShell 命令。 | （注册 `ctx.bash`） |
+| [`bash-env/`](bash-env/README.md) | 提供 shell 工具共享的托管 `DSH_*` 环境。 | `ctx.bashEnv` |
 | [`tool-bash/`](tool-bash/README.md) | 向模型公开 Bash 执行和后台任务集成。 | （注册到 `ctx.tools`） |
 | [`tool-pwsh/`](tool-pwsh/README.md) | 向模型公开 PowerShell 执行。 | （注册到 `ctx.tools`） |
 
diff --git a/packages/bash/bash-local/README.i18n.yaml b/packages/bash/bash-local/README.i18n.yaml
index a33f59641e..aa5f35a125 100644
--- a/packages/bash/bash-local/README.i18n.yaml
+++ b/packages/bash/bash-local/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/bash/bash-local/README.md
-README.md: cb40cb8fa40d95d5b4589b7c804f450a2bf38c8e
-README.zh.md: bd4f73babdb47ff92e87e20eb7d60657ed515ec4
+README.md: cb8e7f0ae766d9b1c5f1678e77d35992085d3d52
+README.zh.md: 20af9c18998c6f3f0403c50f3a8ac599607dc094
diff --git a/packages/bash/bash-local/README.md b/packages/bash/bash-local/README.md
index cb40cb8fa4..cb8e7f0ae7 100644
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Local implementation of the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `LocalBashExecutor` spawns `bash -c <command>` per call as a managed process group through `ctx.subprocess`, and owns everything bash-shaped — command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the subprocess service's.
+Local Service provider for the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `LocalBashExecutor` spawns `bash -c <command>` per call as a managed process group through `ctx.subprocess`, and owns everything bash-shaped — command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the subprocess service's.
 
 The package root exports the default and named `LocalBashExecutor` plugin plus its `Config`.
 
diff --git a/packages/bash/bash-local/README.zh.md b/packages/bash/bash-local/README.zh.md
index bd4f73babd..20af9c1899 100644
--- a/packages/bash/bash-local/README.zh.md
+++ b/packages/bash/bash-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`@deepseek-ai/dsh-bash` 执行器 seam 的本地实现，构建在 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务之上：`LocalBashExecutor` 每次调用都通过 `ctx.subprocess` 把 `bash -c <command>` 作为受管进程组 spawn，并负责所有 Bash 层职责（命令默认值补全与上限、超时与取消分类、适合模型的终端环境，以及后台读取时面向模型的 stdout/stderr 合并）。以 spill 文件兜底的有界输出、凭据清除、kill 升级和 dispose（资源释放）等进程组机制则由 subprocess 服务负责。
+`@deepseek-ai/dsh-bash` 执行器 seam 的本地 Service provider，构建在 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务之上：`LocalBashExecutor` 每次调用都通过 `ctx.subprocess` 把 `bash -c <command>` 作为受管进程组 spawn，并负责所有 Bash 层职责（命令默认值补全与上限、超时与取消分类、适合模型的终端环境，以及后台读取时面向模型的 stdout/stderr 合并）。以 spill 文件兜底的有界输出、凭据清除、kill 升级和 dispose（资源释放）等进程组机制则由 subprocess 服务负责。
 
 包根目录导出默认与具名的 `LocalBashExecutor` 插件及其 `Config`。
 
diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts
index ccb5a32aa8..3d3ca833bc 100644
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -1,6 +1,6 @@
 /**
- * Local implementation of the bash executor seam over the subprocess
- * seam. Public commands run as `bash -c` in a managed process group spawned
+ * Local Service provider for the bash capability seam over the subprocess
+ * capability seam. Public commands run as `bash -c` in a managed process group spawned
  * through `ctx.subprocess`; subclasses may reuse the same mechanics with an
  * explicit argv. This executor owns command defaulting, deadlines and cause
  * classification, the model-friendly terminal environment, and the model-facing
diff --git a/packages/bash/bash-sandbox/README.i18n.yaml b/packages/bash/bash-sandbox/README.i18n.yaml
index 426f2901e5..0df4d4067a 100644
--- a/packages/bash/bash-sandbox/README.i18n.yaml
+++ b/packages/bash/bash-sandbox/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/bash/bash-sandbox/README.md
-README.md: 884681ec73990af600833756caf5dd7305b0d481
-README.zh.md: a19b4cae4606a56ae5ce496fa9f0c10ba2eb9156
+README.md: 44321d7ef26e9e4399438f61b3fdfbfa2e4d8c11
+README.zh.md: f3e110c049871a5a6121716307aaa3d1d1f3eedb
diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md
index 884681ec73..44321d7ef2 100644
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Sandbox-consuming implementation of the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) and a [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) (which owns the default mode + workspace root, shared with the sandboxed filesystem) — no alternate tool plugin is needed; `dsh-tool-bash` detects the executor's `sandboxMode` capability and adds the escalation fields.
+Sandbox-consuming Service provider for the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) and a [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) (which owns the default mode + workspace root, shared with the sandboxed filesystem) — no alternate tool plugin is needed; `dsh-tool-bash` detects the executor's `sandboxMode` capability and adds the escalation fields.
 
 The package root exports the default and named `SandboxBashExecutor` plugin plus its `Config`; result-classification helpers stay internal.
 
diff --git a/packages/bash/bash-sandbox/README.zh.md b/packages/bash/bash-sandbox/README.zh.md
index a19b4cae46..f3e110c049 100644
--- a/packages/bash/bash-sandbox/README.zh.md
+++ b/packages/bash/bash-sandbox/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这是使用沙箱能力的 [`@deepseek-ai/dsh-bash`](../bash/) 执行器 seam 实现。加载它时，应**用它替代** `@deepseek-ai/dsh-bash-local`，并同时加载 [`ctx.sandbox`](../../sandbox/sandbox/) 提供方（例如 [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)）及 [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/)；默认模式和工作区根目录由后者负责，并与受沙箱约束的文件系统共享这些设置。无需使用替代工具插件；`dsh-tool-bash` 会检测执行器的 `sandboxMode` 能力并添加升权字段。
+这是使用沙箱能力的 [`@deepseek-ai/dsh-bash`](../bash/) 执行器 seam Service provider。加载它时，应**用它替代** `@deepseek-ai/dsh-bash-local`，并同时加载 [`ctx.sandbox`](../../sandbox/sandbox/) 提供方（例如 [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)）及 [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/)；默认模式和工作区根目录由后者负责，并与受沙箱约束的文件系统共享这些设置。无需使用替代工具插件；`dsh-tool-bash` 会检测执行器的 `sandboxMode` 能力并添加升权字段。
 
 包根目录导出默认与具名的 `SandboxBashExecutor` 插件及其 `Config`；结果分类 helper 保留在内部。
 
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index 72bd7650be..597a17e088 100644
--- a/packages/bash/bash/README.i18n.yaml
+++ b/packages/bash/bash/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/bash/bash/README.md
-README.md: e142a796e94dab4ecaa67b8dfce0be4f554f26c0
-README.zh.md: 24a44b418a675d863551642f2edb1f655a2705ab
+README.md: 1230149bd03d07cfb6208d82ea6ee8e81751b2c8
+README.zh.md: 168ac9f40e01dc786e29933afb0ebc4c3a745d0f
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index e142a796e9..1230149bd0 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -4,16 +4,16 @@ English | [中文](README.zh.md)
 
 The **`BashExecutor`** (`ctx.bash`) defines WHAT a bash backend does — run foreground commands and start background processes — without saying HOW. Task ids, ownership, collection, cancellation, and notices belong to the generic `ctx.tasks` runtime.
 
-This package is the interface quarter of the bash capability, split so each concern can evolve (and be swapped) independently:
+This package owns the Service Definition role of the bash capability, split so each role can evolve (and be swapped) independently:
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-bash` (this) | the interface: abstract service + vocabulary types |
-| `@deepseek-ai/dsh-bash-local` | an implementation: local subprocesses |
-| `@deepseek-ai/dsh-bash-sandbox` | an implementation: `dsh-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts |
+| `@deepseek-ai/dsh-bash` (this) | Service Definition: abstract service + vocabulary types |
+| `@deepseek-ai/dsh-bash-local` | Service provider: local subprocesses |
+| `@deepseek-ai/dsh-bash-sandbox` | Service provider: `dsh-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts |
 | `@deepseek-ai/dsh-tool-bash` | the model-facing tool schemas over `ctx.bash` |
 
-The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. `dsh-bash-sandbox` is exactly that swap in action — a sandboxing executor behind the same interface; the consumer detects its `sandboxMode` capability and adds escalation fields without importing the implementation. A containerized or remote executor slots in the same way.
+The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. `dsh-bash-sandbox` is exactly that swap in action — a sandboxing executor behind the same Service Definition; the Consumer detects its `sandboxMode` capability and adds escalation fields without importing the provider. A containerized or remote executor slots in the same way.
 
 ## Service API (`ctx.bash`)
 
@@ -35,7 +35,7 @@ The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, th
 
 `stdin` and ordinary `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload and `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` values. `dshEnv` is a separate trusted overlay restricted by type to managed keys; the exported `DSH_ENV_PREFIX` is the single source for that namespace, its `DshEnvironmentKey` template type, executor scrubbing, registry validation, derived built-in names, and model guidance. Model bash uses the current snapshot collected by `ctx.bashEnv`. Implementations remove inherited managed keys, then merge `dshEnv` after ordinary `env`, so an omitted current fact cannot fall back to stale ambient state and an `env` entry cannot displace a managed value. The model-facing tool exposes none of these as parameters. All three remain optional on the resolved spec; absent means no input/overlay. See [the bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [the session environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 
-The exported `parseExitStatus` (with `ParsedExitStatus`) is the shared rendering contract half of the shell tools: the inverse of the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append. Both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill; it lives on the seam so the two tools never drift on the marker contract.
+The exported `parseExitStatus` (with `ParsedExitStatus`) is the shared rendering contract half of the shell tools: the inverse of the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append. Both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill; it lives with the Service Definition so the two tools never drift on the marker contract.
 
 ## Model Experience
 
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index 24a44b418a..168ac9f40e 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -4,16 +4,16 @@
 
 **`BashExecutor`**（`ctx.bash`）定义 bash 后端做什么，即运行前台命令与启动后台进程，但不规定如何实现。task id、所有权、收集、取消与通知属于通用 `ctx.tasks` 运行时。
 
-本包是 bash 能力中负责接口的四分之一，各项职责因此可以独立演进（和替换）：
+本包承担 bash 能力的 Service Definition 角色，各角色因此可以独立演进（和替换）：
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-bash`（本包） | 接口：抽象服务 + 词汇类型 |
-| `@deepseek-ai/dsh-bash-local` | 实现：本地子进程 |
-| `@deepseek-ai/dsh-bash-sandbox` | 实现：沿用 `dsh-bash-local` 的机制，但通过 [`ctx.sandbox`](../../sandbox/sandbox/) 限制每次 spawn，并将拒绝报告为结果事实 |
+| `@deepseek-ai/dsh-bash`（本包） | Service Definition：抽象服务 + 词汇类型 |
+| `@deepseek-ai/dsh-bash-local` | Service provider：本地子进程 |
+| `@deepseek-ai/dsh-bash-sandbox` | Service provider：沿用 `dsh-bash-local` 的机制，但通过 [`ctx.sandbox`](../../sandbox/sandbox/) 限制每次 spawn，并将拒绝报告为结果事实 |
 | `@deepseek-ai/dsh-tool-bash` | 基于 `ctx.bash`、面向模型的工具 schema |
 
-该拆分与 LLM（大语言模型） seam（`LlmService`／`LlmAdapter`）及 agent（智能体）工具调研结果一致：pi 将执行隐藏在 `BashOperations` 接口之后（本地 shell／SSH／VM 后端），Codex 则隐藏在 exec-server 协议之后。`dsh-bash-sandbox` 正是这种替换的实际应用：沙箱执行器位于同一接口之后；消费方检测其 `sandboxMode` 能力并添加升权字段，无需导入实现。容器化或远程执行器也可以同样接入。
+该拆分与 LLM（大语言模型） seam（`LlmService`／`LlmAdapter`）及 agent（智能体）工具调研结果一致：pi 将执行隐藏在 `BashOperations` 接口之后（本地 shell／SSH／VM 后端），Codex 则隐藏在 exec-server 协议之后。`dsh-bash-sandbox` 正是这种替换的实际应用：沙箱执行器位于同一 Service Definition 之后；Consumer 检测其 `sandboxMode` 能力并添加升权字段，无需导入提供方。容器化或远程执行器也可以同样接入。
 
 ## 服务 API（`ctx.bash`）
 
@@ -35,7 +35,7 @@
 
 `stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的统一来源。模型 bash 使用 `ctx.bashEnv` 收集的当前快照。实现会移除继承的受管 key，再在普通 `env` 之后合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态，`env` 条目也无法顶掉受管值。面向模型的工具不将这三者中的任何一个公开为参数。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 
-导出的 `parseExitStatus`（连同 `ParsedExitStatus`）是 shell 工具共享渲染约定的一部分：它对 `dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 所追加的 `[exit code: N]`／`[killed by signal: X]` marker 进行逆解析。两个工具的 `presentResult` 都用它把渲染文本拆成 terminal 卡的输出正文与退出状态 pill；它位于 seam 上，因此两个工具的 marker 约定不会发生偏离。
+导出的 `parseExitStatus`（连同 `ParsedExitStatus`）是 shell 工具共享渲染约定的另一半：`dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 追加的 `[exit code: N]`／`[killed by signal: X]` marker 的逆解析。两个工具的 `presentResult` 都用它把渲染文本拆成 terminal 卡的输出正文与其退出状态 pill；它放在 Service Definition 中，两个工具便永远不会在 marker 约定上漂移。
 
 ## 模型体验
 
diff --git a/packages/bash/bash/src/index.ts b/packages/bash/bash/src/index.ts
index 904c427ed0..73f3d7b519 100644
--- a/packages/bash/bash/src/index.ts
+++ b/packages/bash/bash/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The `ctx.bash` executor seam for foreground commands and background process
+ * Service Definition for the `ctx.bash` capability seam, covering foreground commands and background process
  * handles. Task ids, ownership, polling, and notices belong to
  * `@deepseek-ai/dsh-tasks`, keeping executors independent of sessions.
  * @module @deepseek-ai/dsh-bash
diff --git a/packages/bash/bash/src/invariant.ts b/packages/bash/bash/src/invariant.ts
index f54f280f5d..acf00f48a4 100644
--- a/packages/bash/bash/src/invariant.ts
+++ b/packages/bash/bash/src/invariant.ts
@@ -10,7 +10,7 @@ export const name = 'bash-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
-/** No runtime invariant: this stateless seam owns request/result types, while executors and policy own observations. */
+/** No runtime invariant: this stateless Service Definition owns request/result types, while executors and policy own observations. */
 const install: InvariantInstaller = () => {}
 
 /**
diff --git a/packages/bash/pwsh-local/README.i18n.yaml b/packages/bash/pwsh-local/README.i18n.yaml
index a3b4ec3597..4f25e9f6aa 100644
--- a/packages/bash/pwsh-local/README.i18n.yaml
+++ b/packages/bash/pwsh-local/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/bash/pwsh-local/README.md
-README.md: 3e38ea3830cb651a80eaee744a42f68891767358
-README.zh.md: d84a4ef4c94cd266bbb8f19bd21d7517016c50d5
+README.md: a06126e29ac5bf711bfbbb0d369e097b70918ba6
+README.zh.md: 947e994b59539d137cc1a332bb252a8325533747
diff --git a/packages/bash/pwsh-local/README.md b/packages/bash/pwsh-local/README.md
index 3e38ea3830..a06126e29a 100644
--- a/packages/bash/pwsh-local/README.md
+++ b/packages/bash/pwsh-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Local PowerShell implementation of the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `PwshLocalExecutor` spawns `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` per call as a managed process through `ctx.subprocess`, and owns everything PowerShell-shaped — executable resolution, command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the subprocess service's.
+Local PowerShell Service provider for the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `PwshLocalExecutor` spawns `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` per call as a managed process through `ctx.subprocess`, and owns everything PowerShell-shaped — executable resolution, command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the subprocess service's.
 
 The command string rides as ONE argv element to `-Command`: PowerShell itself parses the text, and no intermediate shell exists, so there is no shell-quoting layer to escape (the `bash -c` string domain has no equivalent here). Native Win32 paths (`C:\...`) pass through unchanged.
 
diff --git a/packages/bash/pwsh-local/README.zh.md b/packages/bash/pwsh-local/README.zh.md
index d84a4ef4c9..947e994b59 100644
--- a/packages/bash/pwsh-local/README.zh.md
+++ b/packages/bash/pwsh-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`@deepseek-ai/dsh-bash` 执行器 seam 的本地 PowerShell 实现，基于 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务：`PwshLocalExecutor` 每次调用以受管进程的方式通过 `ctx.subprocess` spawn `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>`，并拥有所有 PowerShell 形状的职责——可执行文件解析、命令默认化与上限、超时/取消分类、面向模型的终端环境，以及后台读取的 stdout/stderr 合并。进程组机制（有界 spill 输出、凭据清理、终止升级、销毁）属于 subprocess 服务。
+`@deepseek-ai/dsh-bash` 执行器 seam 的本地 PowerShell Service provider，基于 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务：`PwshLocalExecutor` 每次调用以受管进程的方式通过 `ctx.subprocess` spawn `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>`，并拥有所有 PowerShell 形状的职责——可执行文件解析、命令默认化与上限、超时/取消分类、面向模型的终端环境，以及后台读取的 stdout/stderr 合并。进程组机制（有界 spill 输出、凭据清理、终止升级、销毁）属于 subprocess 服务。
 
 命令字符串作为 ONE argv 元素传给 `-Command`：由 PowerShell 自己解析文本，不存在中间 shell，因此没有需要转义的 shell 引号层（这里不存在与 `bash -c` 字符串域对应的层）。原生 Win32 路径（`C:\...`）原样通过。
 
diff --git a/packages/bash/pwsh-local/src/index.ts b/packages/bash/pwsh-local/src/index.ts
index 20ecffd969..f654ea45ed 100644
--- a/packages/bash/pwsh-local/src/index.ts
+++ b/packages/bash/pwsh-local/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Local PowerShell implementation of the bash executor seam. Each command runs
+ * Local PowerShell Service provider for the bash capability seam. Each command runs
  * as `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` in a managed
  * process spawned through `ctx.subprocess`; the executor owns command
  * defaulting, deadlines and cause classification, the model-friendly terminal
@@ -279,7 +279,7 @@ export class PwshLocalExecutor extends BashExecutor {
    * Settlement hook for subclasses that attach execution facts to a process.
    * The base implementation is intentionally empty. Mirrored from
    * `dsh-bash-local` (whose sandboxing subclass consumes the same hook); it is
-   * the declared seam for a future pwsh-confining subclass and has no consumer
+   * the protected extension point for a future pwsh-confining subclass and has no consumer
    * in this package yet.
    * @param _proc - the settled process handle.
    * @param _stderr - the process's retained stderr tail used by subclasses for settlement classification.
diff --git a/packages/bash/tool-bash/README.i18n.yaml b/packages/bash/tool-bash/README.i18n.yaml
index e5eb0dfc41..40c218e528 100644
--- a/packages/bash/tool-bash/README.i18n.yaml
+++ b/packages/bash/tool-bash/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/bash/tool-bash/README.md
-README.md: 47101e1198d13518c3d82877df8726c1fbf26b82
-README.zh.md: c7e0b3ffdc02705bbbd6fd6bd9b8cce2548445f3
+README.md: 9e2cd0c2ed999a11dcbffcd99a1d0cb672367905
+README.zh.md: 8a1e7ba0af36ffd891b38491075ee75283fdbed5
diff --git a/packages/bash/tool-bash/README.md b/packages/bash/tool-bash/README.md
index 47101e1198..9e2cd0c2ed 100644
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The model-facing `bash` tool registered over the `ctx.bash` executor seam. Foreground execution stays behind that seam; a background process handle is registered with the generic `ctx.tasks` runtime and controlled through `task_output`, `task_list`, and `task_kill` from `@deepseek-ai/dsh-tool-tasks`.
 
-Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`) and the [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) registry; the plugin stays pending until every injected service exists (`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`). The tool contract is bash-dialect — mount a bash-parsing executor.
+Requires a loaded executor Service provider (e.g. `@deepseek-ai/dsh-bash-local`) and the [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) registry; the plugin stays pending until every injected service exists (`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`). The tool contract is bash-dialect — mount a bash-parsing executor.
 
 The package root exposes only the Cordis plugin contract (`name`, `inject`, `Config`, `apply`); result rendering and background-process adaptation remain package-internal.
 
@@ -24,7 +24,7 @@ The plugin also contributes the `tool:bash` prompt section (order 105): check th
 | `sandbox_permissions` | string enum | ADVERTISED ONLY when the mounted executor sandboxes (`ctx.bash.sandboxMode` reports a confining default): the wider mode a denied command needs, from the closed target vocabulary `workspace-write`/`danger-full-access` (never cut down to the executor's default — the effective mode is per-session; strict widening is checked at execution against it, and a non-widening request fails without prompting anyone). |
 | `justification` | string | Required together with `sandbox_permissions` (each without the other is a validation error): one sentence for the user explaining why this exact command needs the wider access. |
 
-`command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.bash.resolve()` before execution, so the executor seam (`BashExecSpec`) receives explicit `workdir`/`timeoutMs` values. The workdir default is applied in the tool layer from the calling agent's `session.header.cwd` BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`. When sandbox policy is present, the tool reuses its already-canonical `workspaceRoot` as the workdir base so confinement and process launch cannot resolve the same session spelling differently.
+`command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.bash.resolve()` before execution, so the Service Definition (`BashExecSpec`) receives explicit `workdir`/`timeoutMs` values. The workdir default is applied in the tool layer from the calling agent's `session.header.cwd` BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`. When sandbox policy is present, the tool reuses its already-canonical `workspaceRoot` as the workdir base so confinement and process launch cannot resolve the same session spelling differently.
 
 ### Managed shell environment
 
@@ -42,7 +42,7 @@ The tool owns its `presentCall`/`presentResult` render intent. A foreground call
 
 ## The tool builds its request from named args only
 
-The `BashExecRequest` seam carries optional `stdoutMaxBytes`, `stdin`, ordinary `env`, and managed `dshEnv`, used by trusted in-process plugins and this tool's environment registry. The model-facing tool exposes none of `stdoutMaxBytes`, `stdin`, or `env`: it builds requests from named command/workdir/timeout/signal/sandbox fields plus the registry-collected `dshEnv`. Extra model keys are ignored and cannot replace managed values. Shell syntax provides equivalent command-level behavior, while the local executor scrubs ambient credentials and stale `DSH_*` values. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+`BashExecRequest` carries optional `stdoutMaxBytes`, `stdin`, ordinary `env`, and managed `dshEnv`, used by trusted in-process plugins and this tool's environment registry. The model-facing tool exposes none of `stdoutMaxBytes`, `stdin`, or `env`: it builds requests from named command/workdir/timeout/signal/sandbox fields plus the registry-collected `dshEnv`. Extra model keys are ignored and cannot replace managed values. Shell syntax provides equivalent command-level behavior, while the local executor scrubs ambient credentials and stale `DSH_*` values. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
 
 ## Permissions and escalation
 
diff --git a/packages/bash/tool-bash/README.zh.md b/packages/bash/tool-bash/README.zh.md
index c7e0b3ffdc..8a1e7ba0af 100644
--- a/packages/bash/tool-bash/README.zh.md
+++ b/packages/bash/tool-bash/README.zh.md
@@ -4,7 +4,7 @@
 
 模型侧 `bash` 工具，注册在 `ctx.bash` 执行器 seam 上。前台执行始终位于该 seam 之后；后台进程句柄会注册到通用 `ctx.tasks` 运行时，并通过 `task_output`、`task_list` 和 `task_kill` 控制；这些工具由 `@deepseek-ai/dsh-tool-tasks` 提供。
 
-需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具约定是 bash 方言——请挂载能解析 bash 的执行器。
+需要加载执行器 Service provider（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具约定是 bash 方言——请挂载能解析 bash 的执行器。
 
 包（package）根只公开 Cordis 插件约定（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍保留在包内部。
 
@@ -24,7 +24,7 @@
 | `sandbox_permissions` | string enum | 仅当已挂载的执行器启用沙箱时才会公开（`ctx.bash.sandboxMode` 报告一个具有限制作用的默认值）：被拒命令所需的更宽模式，取自封闭的目标词汇 `workspace-write`/`danger-full-access`（绝不能缩减为执行器默认值；有效模式按会话确定，执行时会基于它检查是否严格拓宽，未拓宽的请求直接失败，不会向任何人发起提示）。 |
 | `justification` | string | 必须与 `sandbox_permissions` 一同提供（缺少任一项都会产生验证错误）：用一句话向用户解释此命令为何需要这项更宽权限。 |
 
-执行前，`command`、`workdir` 和 `timeoutMs` 会通过 `ctx.bash.resolve()` 依据执行器配置默认值完成解析，因此执行器 seam（`BashExecSpec`）收到显式的 `workdir`/`timeoutMs` 值。工具层会根据调用方 agent 的 `session.header.cwd` 应用工作目录默认值，然后才调用 `resolve()`：由于 N 个会话共享一个执行器，逐会话 cwd 必须来自 `exec.agent`；只有无法取得会话 cwd 时，执行器才回退到自身配置／`process.cwd()`。存在沙箱策略时，工具会复用已经规范化的 `workspaceRoot` 作为工作目录基准，防止限制逻辑与进程启动过程对同一个会话路径拼写产生不同解析结果。
+执行前，`command`、`workdir` 和 `timeoutMs` 会通过 `ctx.bash.resolve()` 依据执行器配置默认值完成解析，因此 Service Definition（`BashExecSpec`）收到显式的 `workdir`/`timeoutMs` 值。工具层会根据调用方 agent 的 `session.header.cwd` 应用工作目录默认值，然后才调用 `resolve()`：由于 N 个会话共享一个执行器，逐会话 cwd 必须来自 `exec.agent`；只有无法取得会话 cwd 时，执行器才回退到自身配置／`process.cwd()`。存在沙箱策略时，工具会复用已经规范化的 `workspaceRoot` 作为工作目录基准，防止限制逻辑与进程启动过程对同一个会话路径拼写产生不同解析结果。
 
 ### 托管 shell 环境
 
@@ -42,7 +42,7 @@
 
 ## 工具仅使用具名参数构建请求
 
-`BashExecRequest` seam 携带可选的 `stdoutMaxBytes`、`stdin`、普通 `env` 和托管 `dshEnv`，供可信进程内插件及此工具的环境注册表使用。模型侧工具不公开 `stdoutMaxBytes`、`stdin` 或 `env`：它使用具名的命令／工作目录／超时／信号／沙箱字段，加上从注册表收集的 `dshEnv` 来构建请求。额外模型键会被忽略，无法替换托管值。Shell 语法可以提供等价的命令级行为，而本地执行器会清除环境中的凭据和陈旧 `DSH_*` 值。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)。
+`BashExecRequest` 携带可选的 `stdoutMaxBytes`、`stdin`、普通 `env` 和托管 `dshEnv`，供可信进程内插件及此工具的环境注册表使用。模型侧工具不公开 `stdoutMaxBytes`、`stdin` 或 `env`：它使用具名的命令／工作目录／超时／信号／沙箱字段，加上从注册表收集的 `dshEnv` 来构建请求。额外模型键会被忽略，无法替换托管值。Shell 语法可以提供等价的命令级行为，而本地执行器会清除环境中的凭据和陈旧 `DSH_*` 值。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)。
 
 ## 权限与升权
 
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index 91a88c9cca..adbfd88851 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Model-facing `bash` tool over the `ctx.bash` executor seam. Background calls
+ * Model-facing Consumer of the `ctx.bash` capability seam. Background calls
  * register process handles with `ctx.tasks`; their work uses task cancellation
  * rather than the tool-call signal after an id is returned.
  *
@@ -155,7 +155,7 @@ function resolveWorkdir(
   return modelWorkdir
 }
 
-/** Detach the executor DTO from readonly seam interfaces into plain JSON data. */
+/** Detach the executor DTO from readonly Service Definition types into plain JSON data. */
 function canonicalBashResult(result: BashRunResult) {
   const output = (stream: BashRunResult['stdout']) => ({
     text: stream.text,
diff --git a/packages/bash/tool-bash/tests/integration.spec.ts b/packages/bash/tool-bash/tests/integration.spec.ts
index 69c641a06d..99510dc6e5 100644
--- a/packages/bash/tool-bash/tests/integration.spec.ts
+++ b/packages/bash/tool-bash/tests/integration.spec.ts
@@ -19,7 +19,7 @@ import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent
 
 /**
  * Full-loop integration: a scripted mock model drives the REAL bash tool
- * through the agent loop, exercising the same seams a live model would
+ * through the agent loop, exercising the same execution paths a live model would
  * (tool/call + tool/result session events, the generic `ctx.tasks` runtime,
  * agent.inject completion notices).
  */
diff --git a/packages/bash/tool-pwsh/src/background.ts b/packages/bash/tool-pwsh/src/background.ts
index 5e3464f76b..b245006a4d 100644
--- a/packages/bash/tool-pwsh/src/background.ts
+++ b/packages/bash/tool-pwsh/src/background.ts
@@ -20,7 +20,7 @@ import type { BashProcess } from '@deepseek-ai/dsh-bash'
 export function processOutcome(proc: BashProcess): { status: 'completed' | 'killed'; detail: string } {
   // TODO(background-infrastructure-outcome): widen BashProcess with an explicit
   // infrastructure-failure outcome, then map spawn failures and
-  // sandbox.runnerFailed to task `failed`. The current seam aliases a spawn
+  // sandbox.runnerFailed to task `failed`. The current contract aliases a spawn
   // failure with a signal-less kill and a runner failure with an ordinary
   // wrapper exit; real nonzero command exits must remain `completed`.
   if (proc.status === 'killed') {
diff --git a/packages/bash/tool-pwsh/src/index.ts b/packages/bash/tool-pwsh/src/index.ts
index a68d5d2e35..8f30de893c 100644
--- a/packages/bash/tool-pwsh/src/index.ts
+++ b/packages/bash/tool-pwsh/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Model-facing `pwsh` tool over the `ctx.bash` executor seam. Intended for
+ * Model-facing PowerShell Consumer of the `ctx.bash` capability seam. Intended for
  * Windows compositions where a PowerShell executor (e.g.
  * `@deepseek-ai/dsh-pwsh-local`) backs `ctx.bash`; the tool contract is
  * PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables.
@@ -112,7 +112,7 @@ function resolveWorkdir(modelWorkdir: string | undefined, exec: { agent?: Agent
   return modelWorkdir
 }
 
-/** Detach the executor DTO from readonly seam interfaces into plain JSON data. */
+/** Detach the executor DTO from readonly Service Definition types into plain JSON data. */
 function canonicalPwshResult(result: BashRunResult): PwshForegroundResult {
   const output = (stream: BashRunResult['stdout']) => ({
     text: stream.text,
diff --git a/packages/boot/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts
index 1e71f3e8a7..d951a87cf0 100644
--- a/packages/boot/app-boot/src/profile.ts
+++ b/packages/boot/app-boot/src/profile.ts
@@ -208,10 +208,10 @@ function ensureSymlink(link: string, target: string): void {
  * directory after the profile's own `node_modules`, so every in-box plugin
  * resolves without pnpm ever managing it — the exact "bundles come from the
  * installation" contract. The closure (not just direct dependencies) is
- * required for out-of-tree plugins: their peer dependencies name seam
- * packages (`dsh-compact`, `dsh-invariants`, ...) that the app reaches only
- * through its implementation packages. Symlinked packages resolve their own
- * dependencies from their real directories (Node's default
+ * required for out-of-tree plugins: their peer dependencies name Service
+ * Definition packages (`dsh-compact`, `dsh-invariants`, ...) that the app
+ * reaches only through its Service provider packages. Symlinked packages
+ * resolve their own dependencies from their real directories (Node's default
  * symlink-following), so each package needs only its one flat link.
  * Idempotent: correct links are kept and moved installations are
  * re-pointed; a stale link to a vanished package stays until its name is
@@ -231,7 +231,7 @@ export function healProfilesModuleFallback(installAnchor: string, home: string =
   // map itself (first resolution wins, matching Node's own nearest-wins).
   const queue: { anchor: string; manifest: ProfileManifest }[] = [{ anchor: installAnchor, manifest: appManifest }]
   for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
-    // Peer dependencies participate: seam packages (dsh-subprocess,
+    // Peer dependencies participate: Service Definition packages (dsh-subprocess,
     // dsh-compact, ...) are peers of their implementations, never plain
     // dependencies, yet out-of-tree plugins import them directly.
     /* v8 ignore next -- a real app manifest always declares dependencies */
diff --git a/packages/bundle/headless/README.i18n.yaml b/packages/bundle/headless/README.i18n.yaml
index 2a1dfc271c..2ded85f25b 100644
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/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/bundle/headless/README.md
-README.md: fbdf80be3d587b0ef526c1a36952a761035f7312
-README.zh.md: fa1b5ac280eb9020d71035cc6b09ab2508bff45d
+README.md: f8b76b77f2beb22f501a49f0fc4cf5cd72223765
+README.zh.md: aae8ab5bea663b8909de942f72615f5ef9b16c84
diff --git a/packages/bundle/headless/README.md b/packages/bundle/headless/README.md
index fbdf80be3d..f8b76b77f2 100644
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`). It mounts no Host, HTTP server, Web runtime, or browser plugin.
 
-After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` seam (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` host hook (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
 
 ## Model Experience
 
@@ -17,4 +17,4 @@ None; the runner adds nothing to the request prefix.
 ## Known Limitations and Deferred Work
 
 - **One submitted task only** — the runner has no interactive follow-up surface; it waits through any work the Agent completes before returning to idle and prints the last non-empty assistant message in that interval.
-- **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the seam.
+- **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the hook.
diff --git a/packages/bundle/headless/README.zh.md b/packages/bundle/headless/README.zh.md
index fa1b5ac280..aae8ab5bea 100644
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -4,7 +4,7 @@
 
 dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
 
-Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` 宿主钩子请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
 
 ## 模型体验
 
@@ -17,4 +17,4 @@ Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/a
 ## 已知限制与延期工作
 
 - **只提交一个任务**：runner 没有用于交互式后续输入的 surface；它会等待 Agent 在返回 idle 前完成的所有工作，并打印该区间内最后一条非空 assistant 消息。
-- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该 seam。
+- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该钩子。
diff --git a/packages/bundle/web-app/src/index.ts b/packages/bundle/web-app/src/index.ts
index b817642be8..9a85b02cba 100644
--- a/packages/bundle/web-app/src/index.ts
+++ b/packages/bundle/web-app/src/index.ts
@@ -101,7 +101,7 @@ function resolveDistIndex(): string {
   }
 }
 
-/** Test seam: hosts with no built frontend dist substitute the resolver; production never touches this. */
+/** Test hook: hosts with no built frontend dist substitute the resolver; production never touches this. */
 export const internals: { resolveDistIndex: () => string } = { resolveDistIndex }
 
 /**
diff --git a/packages/bundle/web-app/tests/web-app.spec.ts b/packages/bundle/web-app/tests/web-app.spec.ts
index a4e300b08b..c73f9817db 100644
--- a/packages/bundle/web-app/tests/web-app.spec.ts
+++ b/packages/bundle/web-app/tests/web-app.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Web runtime glue behavior: dist resolution through the bundle's own seam,
+ * Web runtime glue behavior: dist resolution through the bundle's own hook,
  * the frontend-static child claiming the fallback seat, the web-surface
  * prompt section and bash runtime variables, and URL-line printing with the
  * launcher's LAN snapshot.
@@ -184,7 +184,7 @@ describe('web-app runtime glue', () => {
   })
 
   it('resolves the real built frontend dist through the package exports, failing loud unbuilt', () => {
-    // The production resolver (not the test seam). A built checkout resolves
+    // The production resolver (not the test hook). A built checkout resolves
     // the frontend package's index.html; a dist-less one (the CI coverage
     // lane runs before any build) must fail with the build hint, never a
     // silent fallback.
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index d534e5bb83..78704f52fa 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -22,7 +22,7 @@ How live data reaches render code, and what may cross a business boundary:
 
 1. **Everything a render reads that can change outside React arrives through a framework hook** (rule 4 above). Event-handler code may read live snapshots (e.g. `keyboard.snapshot`); render code subscribes.
 2. **Business components contain no subscription machinery** — no `useSyncExternalStore`, no manual subscribe wiring, no mirroring an external snapshot into local state or a second store. Give each reactive fact its owning channel instead: registrant-private → the inject `hooks` compartment; cross-entry or remount-surviving → a declared store; per-session standard → `sessions.provide`.
-3. **Data-access ladder** — resolve needs in this order: framework hooks (standing seats + provide/inject-bound `use<Name>`) → a declared store (`useStore`/`actions`) → inject callbacks → anything else is a new framework seam and needs main-thread arbitration.
+3. **Data-access ladder** — resolve needs in this order: framework hooks (standing seats + provide/inject-bound `use<Name>`) → a declared store (`useStore`/`actions`) → inject callbacks → anything else is a new framework extension point and needs main-thread arbitration.
 4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are grandfathered and get migrated to slots progressively).
 5. **An observable source keeps two identities stable**: the source object itself (hook binding is cached per source), and its snapshot between changes (`getSnapshot` returns the same reference until the fact moves).
 6. **Whoever rebuilds a published value republishes it through the same source in the same step**, and a registration path that can run after consumers exist notifies the live consumers as part of registering.
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 57d4c4c75c..5e2d35f4e8 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
-README.md: 161e34c4b6018625fb690e178eb9a9f8ac0ef21b
-README.zh.md: 731daa15c8944febae1712788a9ae017d4756960
+README.md: dba01cb8c487dbc670a471053f8cd12dd277ef4c
+README.zh.md: d12ef605f1113411a59c2d73c2bf105dfb021be8
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index 161e34c4b6..dba01cb8c4 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. The Host half owns the single `/api` route and its Fetch bridge; a registered TypeRT interceptor claims its Remote endpoints before the API Proxy fallback. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md); the protocol contract is api-contracts v3 §3.
+Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` abstraction, and the loop's sink/config types. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. The Host half owns the single `/api` route and its Fetch bridge; a registered TypeRT interceptor claims its Remote endpoints before the API Proxy fallback. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md); the protocol contract is api-contracts v3 §3.
 
 ## /api browser-trust fence
 
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index 731daa15c8..d12ef605f1 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议约定见 api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` 抽象，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议约定见 api-contracts v3 §3。
 
 ## /api 浏览器信任栅栏
 
diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts
index c373376710..fbf995e652 100644
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -1,7 +1,7 @@
 // Central contract re-export point: every contract import inside
 // web-runtime goes through this single file.
 // Types and runtime protocol helpers/bounds come from the apiproxy api/ layer
-// (zero Node deps, browser-safe); AbstractApiClient is the client seam.
+// (zero Node deps, browser-safe); AbstractApiClient is the client boundary.
 // NEVER import the package root: it drags bootHost/cordis into the browser bundle.
 // The ./api and ./client subpath exports are the browser-safe channels added for this.
 
diff --git a/packages/client/locale/src/client/index.ts b/packages/client/locale/src/client/index.ts
index 5d195ee275..795388c5fd 100644
--- a/packages/client/locale/src/client/index.ts
+++ b/packages/client/locale/src/client/index.ts
@@ -172,7 +172,7 @@ export class LocaleService {
    * the typed form: each dictionary is checked against the namespace's
    * {@link LocaleNamespaceMap} key union (a missing or extra key is a
    * compile error), and every shipped locale is required (bilingual balance
-   * enforced at the seam). Duplicate (ns, locale) throws (single occupant; a
+   * enforced at registration). Duplicate (ns, locale) throws (single occupant; a
    * namespace's texts have one owner). Registration bumps the revision so
    * mounted outlets pick up late-arriving dictionaries.
    * @param ns - a namespace merged into LocaleNamespaceMap.
diff --git a/packages/client/locale/tests/locale.spec.ts b/packages/client/locale/tests/locale.spec.ts
index 442701dbb3..7e9a7802e1 100644
--- a/packages/client/locale/tests/locale.spec.ts
+++ b/packages/client/locale/tests/locale.spec.ts
@@ -60,7 +60,7 @@ describe('LocaleService', () => {
     expect(t('own')).toBe('自有')
     // common itself must not recurse: a miss inside common echoes the key.
     // (Wide-string ns hits the untyped bind overload — the typed one rejects
-    // unknown keys at compile time, which is the point of the seam.)
+    // unknown keys at compile time, which is the point of the typed registry contract.)
     expect(svc.bind('common' as string)('nope')).toBe('nope')
   })
 
diff --git a/packages/client/modules/README.i18n.yaml b/packages/client/modules/README.i18n.yaml
index 2f7278eae2..86d87df60f 100644
--- a/packages/client/modules/README.i18n.yaml
+++ b/packages/client/modules/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/client/modules/README.md
-README.md: 7d661c806955d0fac021dd6620994aab83c0f773
-README.zh.md: aec59474fbf01857380709ebecb6ae99a6ca8174
+README.md: 1d327c7252f4b3001ad758b7a4db01e9907c3060
+README.zh.md: a97672b909c98367e8c1287e3b341fb612f2d110
diff --git a/packages/client/modules/README.md b/packages/client/modules/README.md
index 7d661c8069..1d327c7252 100644
--- a/packages/client/modules/README.md
+++ b/packages/client/modules/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Client module system: the browser peer of Node's internal ESM loader, built as a lazy CJS table. The web shell mounts the vendored cordis Loader for entry governance (fiber lifecycle, inject waiting, update/refresh) and injects this package's `ClientModuleLoader` as its `internal` seam — the vendored side's only consumption point is `EntryTree.import`, so replacing `internal` replaces exactly "how plugin code arrives" and nothing else.
+Client module system: the browser peer of Node's internal ESM loader, built as a lazy CJS table. The web shell mounts the vendored cordis Loader for entry governance (fiber lifecycle, inject waiting, update/refresh) and injects this package's `ClientModuleLoader` through its `internal` contract — the vendored side's only consumption point is `EntryTree.import`, so replacing `internal` replaces exactly "how plugin code arrives" and nothing else.
 
 Lazy CJS model (web2): executing a plugin bundle only REGISTERS its factory (`window.__ModuleLoader__.load({id, factory})`); every module body side effect — CSS injection included — lives in the factory closure and runs at materialization (`factory(require)` → export surface, memoized in `loadCache`), not at script execution. A factory that requires another registered-but-unmaterialized module materializes it recursively, so load order needs no external sequencing; require cycles throw (factory-form CJS cannot deliver partial exports). `<id>/client` and the bare id name the same surface (a plugin bundle IS its package's client half).
 
diff --git a/packages/client/modules/README.zh.md b/packages/client/modules/README.zh.md
index aec59474fb..a97672b909 100644
--- a/packages/client/modules/README.zh.md
+++ b/packages/client/modules/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-客户端模块系统：Node 内部 ESM loader 的浏览器端对等实现，以惰性 CJS 表实现。web 外壳挂载 vendored cordis Loader 来治理配置项（fiber 生命周期、inject 等待、update/refresh），并把该包（package）的 `ClientModuleLoader` 作为其 `internal` seam 注入；vendored 一侧唯一的消费点是 `EntryTree.import`，因此替换 `internal` 恰好只会替换「插件代码如何到达」，不会改变其他内容。
+客户端模块系统：Node 内部 ESM loader 的浏览器端对等实现，以惰性 CJS 表实现。web 外壳挂载 vendored cordis Loader 来治理配置项（fiber 生命周期、inject 等待、update/refresh），并通过其 `internal` 约定注入该包（package）的 `ClientModuleLoader`；vendored 一侧唯一的消费点是 `EntryTree.import`，因此替换 `internal` 恰好只会替换「插件代码如何到达」，不会改变其他内容。
 
 惰性 CJS 模型（web2）：执行插件组合包只会注册其 factory（`window.__ModuleLoader__.load({id, factory})`）；每个模块主体的副作用（包括 CSS 注入）都位于 factory 闭包中，在物化时运行（`factory(require)` → 导出表层，并在 `loadCache` 中记忆化），不会在脚本执行时运行。如果 factory 依赖另一个已注册但尚未物化的模块，系统会递归物化它，因此加载顺序无需外部编排；require 循环会抛出异常（factory 形式的 CJS 无法提供部分导出）。`<id>/client` 与裸 id 指向同一表层（一个插件组合包就是其包的客户端侧）。
 
diff --git a/packages/client/modules/src/client/manifest.ts b/packages/client/modules/src/client/manifest.ts
index 20e2bcf1bd..ff7a7d8692 100644
--- a/packages/client/modules/src/client/manifest.ts
+++ b/packages/client/modules/src/client/manifest.ts
@@ -1,7 +1,7 @@
 /**
  * Client module system: the browser peer of Node's internal ESM loader, built
  * as a lazy CJS table. The vendored cordis Loader consumes this object
- * through its `internal` seam (the only call site is `EntryTree.import` →
+ * through its `internal` contract (the only call site is `EntryTree.import` →
  * `internal.import`), which keeps entry governance (fiber lifecycle, inject
  * waiting, update/refresh) entirely on the vendored side while this package
  * owns code arrival.
@@ -25,7 +25,7 @@
  * imports are a build error anyway.
  *
  * This file is the browser-safe contract face (zero node imports): the
- * `__DSH_BOOT__` wire types, the boot-manifest parser, and the seams around
+ * `__DSH_BOOT__` wire types, the boot-manifest parser, and the boundaries around
  * {@link ClientModuleSystem}. The package root is the host-side service that
  * composes the wire.
  */
@@ -170,7 +170,7 @@ export interface DshWindow {
   __DSH_MODULES__?: ClientModuleSystem
 }
 
-/** Per-module bookkeeping in {@link ClientModuleLoader.loadCache} (module-graph seam, flat today). */
+/** Per-module bookkeeping in {@link ClientModuleLoader.loadCache} (module-graph boundary, flat today). */
 export interface ClientModuleRecord {
   /** Module id (entry name / package name). */
   id: string
@@ -178,12 +178,12 @@ export interface ClientModuleRecord {
   surface: unknown
   /** Owned `<style data-plugin>` tag ids (`data-plugin-css` values) injected during materialization. */
   styles: string[]
-  /** Observed `require()` edges (module-graph seam; only table words can appear today). */
+  /** Observed `require()` edges (module-graph boundary; only table words can appear today). */
   edges: Set<string>
 }
 
 /**
- * The internal-seam subset the vendored Loader and the client HMR plugin
+ * The internal-contract subset the vendored Loader and the client HMR plugin
  * consume. Mounted on `ctx.loader.internal` by the shell boot and provided
  * as `ctx.modules` (contract C5).
  */
@@ -193,12 +193,12 @@ export interface ClientModuleLoader {
   /** Materialized-module registry: id → record. The governance-side read face for entry export surfaces. */
   loadCache: Map<string, ClientModuleRecord>
   /**
-   * Internal seam consumed by the vendored Loader's `tree.import`. Resolves
+   * Internal contract consumed by the vendored Loader's `tree.import`. Resolves
    * `specifier` through the branch order documented on the module, fetching
    * and executing a bundle when needed.
    * @param specifier - module specifier (entry name or table word).
    * @param parentURL - importer URL (unused — the client module graph is flat).
-   * @param attrs - import attributes (unused; interface parity with Node's seam).
+   * @param attrs - Import attributes (unused; interface parity with Node's loader contract).
    * @returns the module's export surface.
    */
   import(specifier: string, parentURL: string, attrs: Record<string, unknown>): Promise<unknown>
@@ -232,6 +232,6 @@ export interface ClientModuleSystemOptions {
   modules: BootModuleRow[]
   /** Module-table seed: platform-singleton specifier → shell instance. */
   staticModules: Record<string, unknown>
-  /** Bundle-load seam. Defaults to a same-origin classic `<script src>` element. */
+  /** Bundle-load hook. Defaults to a same-origin classic `<script src>` element. */
   loadBundle?: (url: string) => Promise<void>
 }
diff --git a/packages/client/modules/src/client/system.ts b/packages/client/modules/src/client/system.ts
index f9044d2c2d..5a6b11bb1e 100644
--- a/packages/client/modules/src/client/system.ts
+++ b/packages/client/modules/src/client/system.ts
@@ -1,6 +1,6 @@
 /**
  * ClientModuleSystem — the implementation behind the {@link ClientModuleLoader}
- * seam. The conceptual contract (lazy CJS model, resolution branch order) is
+ * contract. The conceptual contract (lazy CJS model, resolution branch order) is
  * documented on the public interfaces in `./manifest.ts`; this file owns the
  * state tables and the load/materialize machinery.
  */
@@ -9,7 +9,7 @@ import type {
   ClientModuleSystemOptions, ClientPluginHandoff, DshWindow,
 } from './manifest.ts'
 
-/** Default bundle-load seam: same-origin external classic script. */
+/** Default bundle-load hook: same-origin external classic script. */
 const defaultLoadBundle = (url: string): Promise<void> => new Promise((resolve, reject) => {
   const el = document.createElement('script')
   el.async = true
@@ -53,7 +53,7 @@ const claimStyles = (id: string): string[] => {
 /**
  * The client module system: state tables plus the arrival/materialization
  * machinery implementing {@link ClientModuleLoader} (whose members carry the
- * seam contract docs). Construction indexes the boot rows and installs the
+ * contract documentation). Construction indexes the boot rows and installs the
  * `window.__ModuleLoader__` registration sink (contract C6) — once per page.
  */
 export class ClientModuleSystem implements ClientModuleLoader {
@@ -72,7 +72,7 @@ export class ClientModuleSystem implements ClientModuleLoader {
 
   /**
    * Build the module system over the parsed boot rows.
-   * @param options - module rows, module-table staticModules, and bundle-load seam.
+   * @param options - Module rows, module-table staticModules, and bundle-load hook.
    */
   constructor(options: ClientModuleSystemOptions) {
     this.seed = new Map(Object.entries(options.staticModules))
diff --git a/packages/client/modules/tests/loader.spec.ts b/packages/client/modules/tests/loader.spec.ts
index 4c41419cd8..bd3c5601e3 100644
--- a/packages/client/modules/tests/loader.spec.ts
+++ b/packages/client/modules/tests/loader.spec.ts
@@ -4,7 +4,7 @@
  * registers the factory), materialization on first import/require with
  * memoization and recursive self-sequencing, the resolution branch order,
  * shared in-flight arrival, invalidate-refetch (HMR), style claiming, the
- * default transport seam, and the loud failure modes (duplicate
+ * default transport hook, and the loud failure modes (duplicate
  * registration, cycles, table misses, double boot).
  */
 import { afterEach, describe, expect, it, vi } from 'vitest'
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 641898424e..e1c07abae3 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: 08a45adc441cc2f672e84dea38d0991537187a1f
-README.zh.md: 7abf86aee015a7108547a0025ca8ba5beceecfb2
+README.md: bd8528e97b04d5b4b28922266306969e8f19295a
+README.zh.md: 9aea486fb17c5a170ee8c1195435d220b495b615
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index 08a45adc44..bd8528e97b 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -36,7 +36,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 ## The human transcript
 
-`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view with the producer role and name: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the seam's own declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
+`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view with the producer role and name: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the Service Definition's declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
 
 Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's cited `compact/summary` event; a window cut that left that event outside makes those fields unavailable, and a later page that supplies it resolves them. `CommandNode.outcome.sourceEventSeq` preserves a successful command's explicit reference to that summary event, allowing the presentation layer to pair `/compact` with its checkpoint without parsing settlement copy or assuming the two rows are adjacent. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 7abf86aee0..9aea486fb1 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -8,7 +8,7 @@
 
 `ctx.slots.inject(name, callback)` 将完整的 `SlotMap` key 作为贡献项的依赖，适用于贡献方插件可独立于声明条目激活的情形。声明存在时，它会同步运行 `callback`，否则等待；声明折叠会 dispose（资源释放）回调 effect，重新声明则会再次运行回调。控制器归调用方的插件 fiber 所有，因此卸载贡献方会取消等待或移除其活跃注册项。直接调用 `slots.register()` 向未声明 slot 注册仍会抛出异常。
 
-回调返回一个同步 disposer 或由多个 disposer 构成的 iterable。因此，generator 可以 yield 多个 `slots.register()` 调用，并将它们组成一项事务：setup 失败会回滚先前 yield 的注册项，teardown 则按逆序运行它们。声明生命周期使用专用的单调 declaration epoch（声明代次），因此，即使折叠与重新声明合并在同一次 renderer 通知中，回调仍会重启，而普通条目变更不会重启它。声明绑定的 teardown 与账本变更同步运行，在同一 tick 内的后续注册之前释放运行时资源。详见 [slot 声明注入决策](../../../.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md)。
+回调返回一个同步 disposer 或由多个 disposer 构成的 iterable。因此，generator 可以 yield 多个 `slots.register()` 调用，并将它们组成一项事务：setup 失败会回滚先前 yield 的 effect，teardown 则按逆序运行它们。声明生命周期使用专用的单调 declaration epoch（声明代次），因此，即使折叠与重新声明合并在同一次 renderer 通知中，回调仍会重启，而普通条目变更不会重启它。声明绑定的 teardown 与账本变更同步运行，在同一 tick 内的后续注册之前释放运行时资源。详见 [slot 声明注入决策](../../../.agents/notes/implemented/architecture/2026-08-05-slot-declaration-injection.md)。
 
 ## Workspace 与 Session 列表
 
@@ -18,7 +18,7 @@ Workspace 和 Session 列表各自具有单调的 `pending` → `ready` 基线
 
 `WorkspacesService.delete(workspaceId)` 在一元响应成功后从客户端投影中移除注册记录；对应的 `host/workspace-removed` 帧具有幂等性，并负责同步其他标签页。Session 状态与当前 Session selection 相互独立，因此 Workspace 消失后，其已纳入客户端投影的 Session 会立即投影到 Ungrouped 下。
 
-`WorkspaceListState.archivedSessionIds` 镜像 Host 的注册表级全局归档集合（一个按 Host 顺序的 `readonly SessionId[]`，仅在成员变化时才替换；需要 O(1) 查询的消费方自建临时 Set）。它是全快照状态：`workspace.list` 基线、`archiveSession` 一元回声和 `host/archived-sessions-changed` 帧各自安装完整集合。`WorkspacesService.archiveSession(sessionId)` 通过 wire 归档；投影扫描在当前 selection 落入归档集合时将其清空为 New Session 视图状态——一条规则同时覆盖本地回声、其他标签页的帧、以及重连基线恢复出一个离线期间被归档的 selection。在 `workspace.list` 请求进行中安装的集合还会取代该过期基线携带的集合。各分组视图在所有位置隐藏集合成员，而会话行本身仍留在列表 store 中。
+`WorkspaceListState.archivedSessionIds` 镜像 Host 的注册表级全局归档集合（一个按 Host 顺序的 `readonly SessionId[]`，仅在成员变化时才替换；需要 O(1) 查询的消费方自建临时 Set）。它是全快照状态：`workspace.list` 基线、`archiveSession` 一元回声和 `host/archived-sessions-changed` 帧各自安装完整集合。`WorkspacesService.archiveSession(sessionId)` 通过 wire 归档；投影层在当前 selection 落入归档集合时统一清空为 New Session 视图状态——一条规则同时覆盖本地回声、其他标签页的帧、以及重连基线恢复出一个离线期间被归档的 selection。在 `workspace.list` 请求进行中安装的集合还会取代该过期基线携带的集合。各分组视图在所有位置隐藏集合成员，而会话行本身仍留在列表 store 中。
 
 SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸 observable；web-react 创建钩子。Workspace 业务状态不会进入 `SessionListState` 或配置项 store。
 
@@ -36,7 +36,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 面向人的 transcript（文本记录）
 
-`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份包含生产者角色和名称的 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在压缩 seam 自己的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
+`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份包含生产者角色和名称的 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在 Service Definition 的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
 
 由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点引用的 `compact/summary` 事件；窗口切分把该事件留在窗口外时这些字段不可用，后续包含该事件的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
 
@@ -54,7 +54,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## 模型重试投影
 
-Session 对象会在事件 wire 边界依据生产方的完整字段约定，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括对计时器、整数、状态、提供方延迟和非空诊断字段的约束。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose 时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。
+Session 对象会在事件 wire 边界依据生产方的完整字段约定，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括计时器、整数、状态、提供方延迟和非空诊断字段的边界。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose 时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。
 
 ## 会话 fork
 
@@ -62,7 +62,7 @@ Session 对象会在事件 wire 边界依据生产方的完整字段约定，验
 
 ## 会话模型选择
 
-每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前 `ModelSelection`、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前选择，打开选择器会刷新目录；选择失败会保留上一个选择和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的选择，同时不替换未变化的选择子结构。
+每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前提供方/模型目标、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前目标，打开选择器会刷新目录；选择失败会保留上一个目标和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的目标，同时不替换未变化的选择子结构。
 
 ## 模型体验
 
@@ -70,7 +70,7 @@ Session 对象会在事件 wire 边界依据生产方的完整字段约定，验
 
 #### KV Cache 影响
 
-更改模型选择可能改变提供方侧的缓存复用，或使其失效；该包本身不会改变提示词前缀。
+更改目标可能改变提供方侧的缓存复用，或使其失效；该包本身不会改变提示词前缀。
 
 ## 已知限制与暂缓事项
 
diff --git a/packages/client/runtime/src/client/contract/sessions.ts b/packages/client/runtime/src/client/contract/sessions.ts
index 2af2ef51c8..3e74510dd8 100644
--- a/packages/client/runtime/src/client/contract/sessions.ts
+++ b/packages/client/runtime/src/client/contract/sessions.ts
@@ -100,7 +100,7 @@ export interface ISessions {
    */
   scope(id: SessionId): AgentContext | undefined
   /**
-   * Read the Agent scope tag off a context (service-method seam: fetch
+   * Read the Agent scope tag off a context (service-method boundary: fetch
    * bundles must reach scope resolution through ctx.sessions).
    * @param ctx - any client context.
    * @returns the session id, or undefined on root contexts.
diff --git a/packages/client/runtime/src/client/sessions/projection-store.ts b/packages/client/runtime/src/client/sessions/projection-store.ts
index 32401146af..1af9ad726e 100644
--- a/packages/client/runtime/src/client/sessions/projection-store.ts
+++ b/packages/client/runtime/src/client/sessions/projection-store.ts
@@ -12,7 +12,7 @@ import type { ObservableSnapshot } from '../contract/store.ts'
 import { Notifier } from './notifier.ts'
 
 // The single projection type table, typed end to end (host unit, wire block,
-// client store, React hook) — the interface package's pure-type outlet
+// client store, React hook) — the Service Definition package's pure-type outlet
 // (`/types`, zero imports), never the package root: the root's dsh-agent →
 // dsh-session chain would drag the host `Context.sessions` merge into the
 // client program (one program must not hold both sides). No second
diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts
index 621760df02..64eeaf91d7 100644
--- a/packages/client/runtime/src/client/sessions/service.ts
+++ b/packages/client/runtime/src/client/sessions/service.ts
@@ -488,7 +488,7 @@ export class SessionsService implements ISessions {
   }
 
   /**
-   * Read the Agent scope tag off a context. Service-method seam: fetch
+   * Read the Agent scope tag off a context. Service-method boundary: fetch
    * bundles must reach scope resolution through ctx.sessions — a cross-bundle
    * value import of the standalone helper would inline a second module
    * instance whose private tag Symbol never matches.
@@ -503,7 +503,7 @@ export class SessionsService implements ISessions {
    * Resolve the business Session behind an Agent-scoped context — the one
    * hop every scoped consumer (event listeners, per-session controllers)
    * takes from ctx-space into object-space (the client mirror of host
-   * `agent.session`). Same service-method seam as
+   * `agent.session`). Same service-method boundary as
    * {@link SessionsService.scopeOf}.
    * @param ctx - an Agent-scoped context.
    * @returns the session face, or undefined when the ctx is untagged or its scope was pruned.
@@ -590,7 +590,7 @@ export class SessionsService implements ISessions {
       ctx,
       binding,
       session,
-      // Sources are bare observables; React binds selector hooks at its own seam.
+      // Sources are bare observables; React binds selector hooks at its own boundary.
       provideInfo: this.provideChannel.materializeInfo(binding),
     }
     this.scopes.set(id, record)
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index aee51d3dc2..0813c02711 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -198,7 +198,7 @@ export class Session implements SessionFace {
   /**
    * Bind the Agent-scoped context minted by SessionsService (single write;
    * a second bind is a wiring error and throws). Direction stays one-way at
-   * the seam: consumers still reach the Session via `sessions.sessionOf`,
+   * this binding boundary: consumers still reach the Session via `sessions.sessionOf`,
    * while the Session holds its own dispatch point (host Agent.loopCtx
    * mirror).
    * @param actx - the agent's scoped context.
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
index e9e1c1d8d6..78090ce87f 100644
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -12,7 +12,7 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 // browser bundle cannot resolve; surface.ts has no Node dependencies.
 import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-// Cordis-free leaf subpath (the dsh-commands/brand shape): the seam's own
+// Cordis-free leaf subpath (the dsh-commands/brand shape): the Service Definition's
 // declaration of the checkpoint source, reachable as a TYPE from this program.
 // The package ROOT is not — it reaches dsh-session's root, whose Context merge
 // declares the HOST `sessions: SessionStore` against this program's
@@ -28,7 +28,7 @@ import type { AssistantStepMetadata } from './assistant-timing.ts'
 import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts'
 
 /**
- * The compaction seam's checkpoint plugin, pinned to the seam's own declaration
+ * The compaction capability's checkpoint plugin, pinned to the Service Definition's declaration
  * at COMPILE time: renaming it there fails this annotation (`TS2322`). The
  * import stays type-only because a value import would fail the client purity
  * gate (`packages/client/tsdown.client.ts`) — cross-plugin value imports are
diff --git a/packages/client/runtime/src/client/slots.ts b/packages/client/runtime/src/client/slots.ts
index 9da8755b2d..a30adb4dd6 100644
--- a/packages/client/runtime/src/client/slots.ts
+++ b/packages/client/runtime/src/client/slots.ts
@@ -4,7 +4,7 @@
  * the load-time validations, and the unload cascade). This layer owns what
  * needs the runtime: the 'slots/changed' event bridge, register and
  * declaration injection through the caller's ctx.effect (fiber unload
- * collects both), the renderer install seam (install()/renderSlot('root') +
+ * collects both), the renderer installation contract (install()/renderSlot('root') +
  * the SlotRendererHost face), and the store INSTANCE axis — handle x scope
  * key -> create/cache, dropped with the last holding entry, session instances
  * cleared (with persisted state) on scope death.
diff --git a/packages/client/runtime/src/client/workspaces/workspace.ts b/packages/client/runtime/src/client/workspaces/workspace.ts
index afa4dd65b6..e1e280d1c6 100644
--- a/packages/client/runtime/src/client/workspaces/workspace.ts
+++ b/packages/client/runtime/src/client/workspaces/workspace.ts
@@ -59,7 +59,7 @@ export class Workspace implements ObservableSnapshot<WorkspaceSnapshot> {
   }
 
   /**
-   * Materialize this local Workspace through the Host create seam.
+   * Materialize this local Workspace through the Host create API.
    * Re-entry shares the in-flight completion; a materialized instance returns undefined.
    * @returns the Host result, or undefined when this Workspace is already materialized.
    */
diff --git a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
index aed658af51..1f969c5121 100644
--- a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
+++ b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
@@ -1,12 +1,12 @@
 /**
  * Behavioral half of the compaction-checkpoint drift trap.
  *
- * `TranscriptAdapter` pins its plugin literal to the seam's own declaration at
+ * `TranscriptAdapter` pins its plugin literal to the Service Definition's declaration at
  * compile time through a type-only import of `dsh-compact/checkpoint`, so
- * renaming the seam's plugin already fails `tsc`. This spec covers the same
+ * renaming the Service Definition's plugin already fails `tsc`. This spec covers the same
  * drift from the other side — end to end through the adapter, driving it with a
  * checkpoint built from the canonical `COMPACT_CHECKPOINT_SOURCE` value and
- * checking the seam's own predicate agrees. Both values come from the
+ * checking the Service Definition's predicate agrees. Both values come from the
  * cordis-free checkpoint leaf, so the client test program never loads the host
  * package root or its `Context` merges.
  */
@@ -17,7 +17,7 @@ import { describe, expect, it } from 'vitest'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts'
 
-/** A replacement user message stamped with the seam's own canonical source. */
+/** A replacement user message stamped with the Service Definition's canonical source. */
 function canonicalCheckpoint(seq: number): SessionEvent {
   return {
     type: 'user/message',
@@ -43,7 +43,7 @@ describe('compaction checkpoint recognition', () => {
   })
 
   it("agrees with the seam's own predicate on the source it recognizes", () => {
-    // Both sides answer the same question about the same value: if the seam
+    // Both sides answer the same question about the same value: if the Service Definition
     // renames its plugin, this equality is what breaks.
     const checkpoint = canonicalCheckpoint(1)
     expect(checkpoint.type === 'user/message' && isCompactCheckpointSource(checkpoint.data.source)).toBe(true)
diff --git a/packages/client/runtime/tests/projection-store.spec.ts b/packages/client/runtime/tests/projection-store.spec.ts
index 143da92348..6547d365f5 100644
--- a/packages/client/runtime/tests/projection-store.spec.ts
+++ b/packages/client/runtime/tests/projection-store.spec.ts
@@ -14,7 +14,7 @@ import { SessionManager } from '../src/client/sessions/manager.ts'
 import { FakeApiClient, ok } from './fake-api.ts'
 import { entries, plainTurn } from './event-script.ts'
 
-// Test-domain keys merged into the projection map (the interface package's
+// Test-domain keys merged into the projection map (the Service Definition package's
 // pure-type outlet), the same way domain host plugins merge theirs.
 declare module '@deepseek-ai/dsh-session-projection/types' {
   interface SessionProjectionMap {
diff --git a/packages/client/runtime/tests/slots-service.spec.ts b/packages/client/runtime/tests/slots-service.spec.ts
index f8968926c1..0b8ce8a301 100644
--- a/packages/client/runtime/tests/slots-service.spec.ts
+++ b/packages/client/runtime/tests/slots-service.spec.ts
@@ -1,8 +1,8 @@
 /**
  * SlotsService terminal-design account (design.md §11-3 main landing):
  * built-in 'root', the three load-time throws (duplicate declaration /
- * undeclared contribution / cross-scope store handle), the renderer install
- * seam (double install / not installed / non-root key), store instance
+ * undeclared contribution / cross-scope store handle), the renderer installation
+ * contract (double install / not installed / non-root key), store instance
  * resolution and lifecycle on the ledger axis, and the entry-unload cascade.
  */
 import { Context } from 'cordis'
@@ -92,13 +92,13 @@ function captureHost(bench: Bench, children?: object): SlotRendererHost {
   return host
 }
 
-/** Minimal independent Workspace list source for the renderer host seam. */
+/** Minimal independent Workspace list source for the renderer host contract. */
 function fakeWorkspaces() {
   const state = { items: [], phase: 'ready' as const }
   return { list: { getSnapshot: () => state, subscribe: () => () => undefined } }
 }
 
-/** Minimal sessions face for the host seam (list observable + current provide projection). */
+/** Minimal sessions face for the host contract (list observable + current provide projection). */
 function fakeSessions() {
   const state = { ids: [], byId: {}, current: undefined as string | undefined }
   const absentInfo = { sessionId: undefined, hooks: { session: undefined }, props: {} }
diff --git a/packages/client/schema-form/README.i18n.yaml b/packages/client/schema-form/README.i18n.yaml
index 9dfa981a3f..9c24cc754c 100644
--- a/packages/client/schema-form/README.i18n.yaml
+++ b/packages/client/schema-form/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/client/schema-form/README.md
-README.md: 716cc7ba3c24f3a4de081e2d26f803b905235fac
-README.zh.md: 9473620da83e73f7a095694b2321f1ebc5f9c53d
+README.md: ef1d2f9d8ce936fe60d38849f975dc8c0a08ded4
+README.zh.md: aff77bc4c31a9aaa13977480d32551536ddceadd
diff --git a/packages/client/schema-form/README.md b/packages/client/schema-form/README.md
index 716cc7ba3c..ef1d2f9d8c 100644
--- a/packages/client/schema-form/README.md
+++ b/packages/client/schema-form/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Schema/draft model layer for settings editors. The wire's `settings.describe` carries each namespace's serialized schemastery schema (`schema.toJSON()` ref envelope); `rehydrateSchema` turns it back into a live validator with `new Schema(json)` — the same schema object that validates a section on the host validates drafts in the browser, so client-side validation never drifts from the seam's. Editors render their own controls (the Models page hand-writes its card around the fields it probes here); this package owns no React and no rendering.
+Schema/draft model layer for settings editors. The wire's `settings.describe` carries each namespace's serialized schemastery schema (`schema.toJSON()` ref envelope); `rehydrateSchema` turns it back into a live validator with `new Schema(json)` — the same schema object that validates a section on the host validates drafts in the browser, so client-side validation never drifts from the Service Definition's. Editors render their own controls (the Models page hand-writes its card around the fields it probes here); this package owns no React and no rendering.
 
 ## Contract
 
diff --git a/packages/client/schema-form/README.zh.md b/packages/client/schema-form/README.zh.md
index 9473620da8..aff77bc4c3 100644
--- a/packages/client/schema-form/README.zh.md
+++ b/packages/client/schema-form/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向 settings 编辑器的 schema／草稿模型层。wire 侧的 `settings.describe` 携带每个 namespace 的序列化 schemastery schema（`schema.toJSON()` 的 ref 信封）；`rehydrateSchema` 用 `new Schema(json)` 将其还原（rehydrate）为活的校验器——在宿主上校验分节的那份 schema 对象，就是在浏览器里校验草稿的那份对象，因此客户端校验绝不会偏离 seam 侧的校验。编辑器各自渲染自己的控件（Models 页围绕它在此探测到的字段手写自己的卡片）；该包不含任何 React，也不做任何渲染。
+面向 settings 编辑器的 schema／草稿模型层。wire 侧的 `settings.describe` 携带每个 namespace 的序列化 schemastery schema（`schema.toJSON()` 的 ref 信封）；`rehydrateSchema` 用 `new Schema(json)` 将其还原（rehydrate）为活的校验器——在宿主上校验分节的那份 schema 对象，就是在浏览器里校验草稿的那份对象，因此客户端校验绝不会偏离 Service Definition 的校验。编辑器各自渲染自己的控件（Models 页围绕它在此探测到的字段手写自己的卡片）；该包不含任何 React，也不做任何渲染。
 
 ## 约定
 
diff --git a/packages/client/test-runtime/src/index.ts b/packages/client/test-runtime/src/index.ts
index 5ef5350434..3005c061e7 100644
--- a/packages/client/test-runtime/src/index.ts
+++ b/packages/client/test-runtime/src/index.ts
@@ -40,7 +40,7 @@ export type { SessionBehaviorOverrides, SessionFixture, Stabilizer } from './fix
 export { makeTranslate } from './translate.ts'
 export { usePinnedBrowserLanguages } from './locale-env.ts'
 
-/** Erased register face for the internal root call (the public declare seam holds the typing). */
+/** Erased register face for the internal root call (the public declaration contract holds the typing). */
 type ErasedRegister = (options: object, component: unknown) => () => void
 
 /**
@@ -80,7 +80,7 @@ export interface FeatureHandle {
 /**
  * Owner-props cell behind the auto frame: one external store the frame
  * subscribes to, so {@link SlotTestRuntime.renderSlot} and
- * {@link SlotView.update} drive React through the standard uSES seam.
+ * {@link SlotView.update} drive React through the standard uSES boundary.
  */
 class OwnerPropsCell {
   private readonly owners = new Map<string, object>()
@@ -146,7 +146,7 @@ export class TestRoot {
   ): Promise<void> {
     await this.stabilize(() => {
       // Erased hop (same pattern as SlotsService's own implementation arm);
-      // the declare signature above is the typed seam.
+      // the declaration signature above is the typed contract.
       this.disposeEntry = (this.slots.register as unknown as ErasedRegister)({ name: 'root', children }, frame)
     })
   }
@@ -267,7 +267,7 @@ export class SlotTestRuntime {
 
   /**
    * Render the root slot tree through the ctx-level entry (the shell's own
-   * seam): `ctx.slots.renderSlot('root', {})` under Testing Library.
+   * entry point): `ctx.slots.renderSlot('root', {})` under Testing Library.
    * @returns the Testing Library view.
    */
   renderRoot(): RenderResult {
diff --git a/packages/client/test-runtime/src/sessions.ts b/packages/client/test-runtime/src/sessions.ts
index 4747929572..f700cb4ba1 100644
--- a/packages/client/test-runtime/src/sessions.ts
+++ b/packages/client/test-runtime/src/sessions.ts
@@ -368,7 +368,7 @@ export class TestSessions implements ISessions {
   }
 
   /**
-   * Read the session scope tag off a context (service-method seam mirror).
+   * Read the session scope tag off a context (service-method boundary mirror).
    * @param ctx - any client context.
    * @returns the session id, or undefined on root contexts.
    */
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 341a3409c3..2066b22ec5 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 58c8dc68758ddae11966195c42cf324e388cfc47
-README.zh.md: f60b89c0ac378f5a87bb49194465fd8bc65d7c42
+README.md: 911bca28dcfb31b1d8ef9ea5458a0d2017d8b31d
+README.zh.md: 25574421bbcc3992188e378a49a69acf25744af7
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 58c8dc6875..911bca28dc 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -40,7 +40,7 @@ The chat stats line takes its token accounting from the generic token-meter `tok
 
 `src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` export surface contains only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations.
 
-A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` seam — an absent service leaves the prose inert.
+A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` contract — an absent service leaves the prose inert.
 
 ## Model Experience
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index f60b89c0ac..25574421bb 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -40,7 +40,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 `src/client/` 按领域组织。`contract/` 是 slot 声明、组合 props 与跨领域类型的共享表层；`skeleton/`、`chat/`、`input/`、`queue/` 和 `settings/` 保持内部实现，`apply.ts` 是它们的组装点。`/client` 导出表层只包含 loader entry、service class 和 contract 类型；组件与 store factory 经 slot 注册抵达页面。
 
-完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。收尾正文经由同一个开关参与其中：chat 视图向可选的 `chatFileMentions` service（ctx.get；由同一插件提供）索取收尾消息的行内代码词表，并把结果接进 MarkdownText 的 `fileMentions` seam——service 缺席时正文保持死文本。
+完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。收尾正文经由同一个开关参与其中：chat 视图向可选的 `chatFileMentions` service（ctx.get；由同一插件提供）索取收尾消息的行内代码词表，并把结果接进 MarkdownText 的 `fileMentions` 约定——service 缺席时正文保持死文本。
 
 ## 模型体验
 
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 2d42aef367..0e486e9154 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -363,7 +363,7 @@ export function apply(ctx: Context): void {
   ctx.plugin(todoDockEntry)
 
   // The read-only queue dock entry (T9 file territory) rides the same
-  // registration seam into the input dock declared above.
+  // registration path into the input dock declared above.
   ctx.plugin(queueDockEntry)
 
   slots.register({
diff --git a/packages/client/ui-conversation/src/client/input/facade.ts b/packages/client/ui-conversation/src/client/input/facade.ts
index 79516d04fa..3c6d1fd0fb 100644
--- a/packages/client/ui-conversation/src/client/input/facade.ts
+++ b/packages/client/ui-conversation/src/client/input/facade.ts
@@ -25,7 +25,7 @@ export interface PopupDismissFace {
 }
 
 /**
- * Construction seams of one facade. The slash/popup faces are THUNKS: the
+ * Construction dependencies of one facade. The slash/popup faces are THUNKS: the
  * shell is created inside the sessions provide materialization (before the
  * scope record is queryable), where `slash.sessionOf`/`command.popupFor`
  * cannot resolve yet — resolution defers to first interactive use.
diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx
index 8a301d03ff..35dac88ffd 100644
--- a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx
+++ b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx
@@ -214,7 +214,7 @@ export function QueueDock({ useSession, updateQueue, notify, t }: QueueDockProps
 
 /**
  * The dock entry as a plain registrant plugin. The conversation service is
- * the action seam; the slot declaration is its independent lifecycle seam.
+ * the action contract; the slot declaration has an independent lifecycle boundary.
  */
 export const queueDockEntry = {
   name: 'conversation-queue-dock',
diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
index c47b726b66..aae5bb4818 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
@@ -6,7 +6,7 @@
  * table's relevant cells + the real SessionInput machine (scoped-event
  * listeners wired the way the hub does) + the real InputBar. ui-command
  * itself is not a dependency of this package; the source below is the
- * decision-table contract at the SlashSource seam.
+ * decision-table contract at the `SlashSource` boundary.
  */
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
diff --git a/packages/client/ui-conversation/tests/selection-survival.spec.tsx b/packages/client/ui-conversation/tests/selection-survival.spec.tsx
index 07e9ad0c79..d7c701d6ae 100644
--- a/packages/client/ui-conversation/tests/selection-survival.spec.tsx
+++ b/packages/client/ui-conversation/tests/selection-survival.spec.tsx
@@ -95,7 +95,7 @@ describe('selection survives on the store seat', () => {
     doomed.actions.select({ turnSeq: 1 })
     expect(localStorage.getItem('dsh.conversation.chat.s1')).not.toBeNull()
 
-    // TestSessions.remove drives the same public slot lifecycle seam the
+    // TestSessions.remove drives the same public slot lifecycle contract the
     // production SessionsService calls when the scope dies (pruneStoreScope).
     await b.runtime.sessions.remove('s1')
 
diff --git a/packages/client/ui-layout/src/client/index.ts b/packages/client/ui-layout/src/client/index.ts
index bb78596a0b..8050cb0916 100644
--- a/packages/client/ui-layout/src/client/index.ts
+++ b/packages/client/ui-layout/src/client/index.ts
@@ -3,7 +3,7 @@
  * the runtime's built-in 'root' slot and, in the same breath, declares the
  * four child slots (declaration = exclusive render authority), seats the
  * layout store (panel geometry), and wires the panel-action service face.
- * ctx.layout is the cross-plugin panel-action seam; navigation state lives
+ * ctx.layout is the cross-plugin panel-action contract; navigation state lives
  * with the runtime sessions service. A second effect seats the theme
  * presenter, which projects ctx.theme snapshots onto document.body.
  */
diff --git a/packages/client/ui-layout/src/client/service.ts b/packages/client/ui-layout/src/client/service.ts
index ecfd862a03..b1fae0b494 100644
--- a/packages/client/ui-layout/src/client/service.ts
+++ b/packages/client/ui-layout/src/client/service.ts
@@ -3,7 +3,7 @@
  * Panel geometry itself lives in the root entry's layout store (stores.ts);
  * the current-session selection lives with the runtime sessions service, and
  * the per-session active view dissolved into ui-conversation's session store
- * (its only consumer). What remains here is the seam other plugins'
+ * (its only consumer). What remains here is the contract other plugins'
  * apply worlds reach for panel transitions (sidebar toggle from ui-sidebar,
  * details open/close from ui-conversation) — writes stay inside the store's
  * declared action set, delivered as the registration's bound actions.
diff --git a/packages/client/ui-layout/tests/service.spec.ts b/packages/client/ui-layout/tests/service.spec.ts
index c7c9cca5ba..1a309d83e5 100644
--- a/packages/client/ui-layout/tests/service.spec.ts
+++ b/packages/client/ui-layout/tests/service.spec.ts
@@ -1,7 +1,7 @@
 /**
  * LayoutService behavior: the cross-plugin panel-action face. Geometry
  * lives in the entry store (layout-store.spec.ts) — here we assert the
- * delegation seam: attachPanels wiring, the three actions forwarding, the
+ * delegation contract: attachPanels wiring, the three actions forwarding, the
  * unwired fail-loud, and re-attach overwriting a stale action set.
  */
 import { describe, expect, it, vi } from 'vitest'
diff --git a/packages/client/ui-model/README.i18n.yaml b/packages/client/ui-model/README.i18n.yaml
index e630daf0fa..c1449560d5 100644
--- a/packages/client/ui-model/README.i18n.yaml
+++ b/packages/client/ui-model/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/client/ui-model/README.md
-README.md: b37f807944850fb34331cd8d78b4a2ccf157f21c
-README.zh.md: 906096bed06af26517e215b2d1e1da4b62e58095
+README.md: 519429834f214fcb82eeb692378fb79770fa30be
+README.zh.md: 116e151d1afeaaa22618c408eed2c7542d1357e7
diff --git a/packages/client/ui-model/README.md b/packages/client/ui-model/README.md
index b37f807944..519429834f 100644
--- a/packages/client/ui-model/README.md
+++ b/packages/client/ui-model/README.md
@@ -8,7 +8,7 @@ The Host-reported provider/model/reasoning `ModelSelection` is the single select
 
 When the Host reports that no adapter serves the session's route (`session.models.routable`), this plugin raises a composer block through `ctx.conversation.blocks` and the input goes inert with this plugin's own copy; recovering clears it without a reload. It follows `routable` and nothing else: a `null` — before the first load, or after one failed — never blocks, or a slow Host would lock a working composer, and catalog membership never blocks either, because a route serving a model it stopped advertising is missing from the groups yet perfectly usable. The trigger's own `Select model` fallback still covers that case, which is display, not a gate.
 
-Directories are per-session, resolved lazily through `ctx.models.directoryFor(sessionId)`, and disposed with the session scope. Addressed subagent sessions expose neither entry, and their directory rejects loads, selections, and reconnect refreshes, because ordinary Agent-bound model RPCs would activate persisted child history outside the direct-parent continuation seam.
+Directories are per-session, resolved lazily through `ctx.models.directoryFor(sessionId)`, and disposed with the session scope. Addressed subagent sessions expose neither entry, and their directory rejects loads, selections, and reconnect refreshes, because ordinary Agent-bound model RPCs would activate persisted child history outside the direct-parent continuation path.
 
 The `/client` export surface is the plugin body (`apply`/`inject`), `ModelService`, `ModelDirectory` with its state shape, and the seat's injected face type.
 
diff --git a/packages/client/ui-model/README.zh.md b/packages/client/ui-model/README.zh.md
index 906096bed0..116e151d1a 100644
--- a/packages/client/ui-model/README.zh.md
+++ b/packages/client/ui-model/README.zh.md
@@ -8,7 +8,7 @@ Host 报告的 `ModelSelection` 是唯一的选择事实，其中包含提供方
 
 当宿主报告没有适配器服务该会话的路由（`session.models.routable`）时，本插件经 `ctx.conversation.blocks` 注册一个 composer 阻塞块，输入框随之停用并显示本插件自己的文案；恢复后无需重新加载即自动清除。它只跟随 `routable`：`null`（首次加载之前，或加载失败之后）绝不阻断，否则一个慢的宿主就会锁死一个本来可用的 composer；目录成员关系同样不阻断，因为一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用。触发器自己的 `Select model` 回退仍然覆盖那种情形——那是显示，不是闸门。
 
-目录按会话惰性解析（`ctx.models.directoryFor(sessionId)`），随会话作用域一并释放。已寻址 subagent 会话不公开任一入口，其目录会拒绝加载、选择与重新连接刷新，因为绑定到 agent（智能体）的普通模型 RPC 会在直接 parent 继续执行 seam 之外激活持久化 child 历史。
+目录按会话惰性解析（`ctx.models.directoryFor(sessionId)`），随会话作用域一并释放。已寻址 subagent 会话不公开任一入口，其目录会拒绝加载、选择与重新连接刷新，因为绑定到 agent（智能体）的普通模型 RPC 会在直接 parent 继续执行路径之外激活持久化 child 历史。
 
 `/client` 导出面为插件本体（`apply`/`inject`）、`ModelService`、`ModelDirectory` 及其状态形状、slot 注入面类型。
 
diff --git a/packages/client/ui-model/src/client/index.ts b/packages/client/ui-model/src/client/index.ts
index f55cb83c1c..63feadebef 100644
--- a/packages/client/ui-model/src/client/index.ts
+++ b/packages/client/ui-model/src/client/index.ts
@@ -9,7 +9,7 @@
  * ride each entry's own retry surface (popup shell error/retry; seat menu
  * inline error) without forking the state. Addressed subagent sessions expose
  * neither entry because those Agent-bound RPCs would activate persisted
- * history outside the direct-parent continuation seam.
+ * history outside the direct-parent continuation path.
  */
 import type { ModelSelection, SessionModels } from '@deepseek-ai/dsh-client-connection/client'
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
diff --git a/packages/client/ui-primitives/src/clipboard.ts b/packages/client/ui-primitives/src/clipboard.ts
index 0ef84a4123..aa45f4c76d 100644
--- a/packages/client/ui-primitives/src/clipboard.ts
+++ b/packages/client/ui-primitives/src/clipboard.ts
@@ -1,5 +1,5 @@
 // Host clipboard write shared by Web UI copy controls. Success feedback stays
-// with each control; this seam only reports whether the host accepted a write.
+// with each control; this helper only reports whether the host accepted a write.
 
 /**
  * Write text to the host clipboard, preferring the async Clipboard API and
diff --git a/packages/client/ui-primitives/src/markdown/incremental.ts b/packages/client/ui-primitives/src/markdown/incremental.ts
index 3947d4801f..18638a25b6 100644
--- a/packages/client/ui-primitives/src/markdown/incremental.ts
+++ b/packages/client/ui-primitives/src/markdown/incremental.ts
@@ -95,7 +95,7 @@ export class IncrementalMarkdownParser {
     // to verify the whole retained prefix, and startsWith compares bytes two
     // orders of magnitude faster than parsing them — the cost this class
     // exists to remove. Passing append/reset deltas instead would push
-    // append bookkeeping across the session-projection seam for a check
+    // append bookkeeping across the session-projection update boundary for a check
     // that stays sub-millisecond at realistic reply sizes.
     if (!text.startsWith(this.prevText)) {
       this.prevText = ''
diff --git a/packages/client/ui-primitives/tests/diff-block.spec.tsx b/packages/client/ui-primitives/tests/diff-block.spec.tsx
index bb4a2fdac3..575cfd06bd 100644
--- a/packages/client/ui-primitives/tests/diff-block.spec.tsx
+++ b/packages/client/ui-primitives/tests/diff-block.spec.tsx
@@ -4,7 +4,7 @@
 // its singular/plural, the head/tail height cap and its expand control, the
 // empty-diffs null render, and the copy control writing the prefixed diff text
 // on both the accepted and the refused clipboard paths. writeClipboard's own
-// return contract is pinned in terminal-block.spec.tsx (the shared seam), so
+// return contract is pinned in terminal-block.spec.tsx (the shared return contract), so
 // only its DOM consequence is asserted here.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
diff --git a/packages/client/ui-primitives/tests/terminal-block.spec.tsx b/packages/client/ui-primitives/tests/terminal-block.spec.tsx
index 13121351a8..23a38e8e09 100644
--- a/packages/client/ui-primitives/tests/terminal-block.spec.tsx
+++ b/packages/client/ui-primitives/tests/terminal-block.spec.tsx
@@ -3,7 +3,7 @@
 // arms, the prompt line's run-state dot, the exit-status pill, the head/tail height cap and its expand control,
 // and the copy control writing the raw output on both the accepted and the
 // refused clipboard paths. writeClipboard's own return contract is pinned here
-// too, since it is the seam both copy controls in this package share; the
+// too, since it is the return contract both copy controls in this package share; the
 // resolution of ANSI runs into styles is pinned in ansi.spec.ts, so only its
 // DOM consequence (which runs get a span wrapper) is asserted here.
 
diff --git a/packages/client/ui-sidebar/src/client/contract/slots.ts b/packages/client/ui-sidebar/src/client/contract/slots.ts
index dea4fea6c9..7b30e4232e 100644
--- a/packages/client/ui-sidebar/src/client/contract/slots.ts
+++ b/packages/client/ui-sidebar/src/client/contract/slots.ts
@@ -32,7 +32,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 
 /**
  * Owner share of the browser hole — the only facts crossing the shell/region
- * seam. Business data and actions arrive through the region's own inject.
+ * boundary. Business data and actions arrive through the region's own inject.
  */
 export interface SidebarSectionOwnerProps {
   /** Shell fold-state output: wide renders the full browser, rail the icon column. */
diff --git a/packages/client/ui-slash/src/client/controller.ts b/packages/client/ui-slash/src/client/controller.ts
index 0b57f3dd74..fdf78d316e 100644
--- a/packages/client/ui-slash/src/client/controller.ts
+++ b/packages/client/ui-slash/src/client/controller.ts
@@ -22,7 +22,7 @@ export interface SourceRoster {
   all(): readonly SlashSource[]
 }
 
-/** Construction seams of one controller. */
+/** Construction hooks for one controller. */
 export interface SlashControllerDeps {
   /** The owning session scope (event dispatch + teardown registration site). */
   actx: ClientContext
diff --git a/packages/client/ui-slots/README.i18n.yaml b/packages/client/ui-slots/README.i18n.yaml
index a3bf047f84..8f7c3293be 100644
--- a/packages/client/ui-slots/README.i18n.yaml
+++ b/packages/client/ui-slots/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/client/ui-slots/README.md
-README.md: bb489dea0c3848cf3d501dcf095a65fe1cef9ef6
-README.zh.md: 8b10ddf2d974c3054b5e086a302cd8f84dca9667
+README.md: 7ee2a3d22c2a41b0e5c356c52d383a047cf99029
+README.zh.md: 793bb2d1f77e02e34a41fab16b2c2c64b78744dc
diff --git a/packages/client/ui-slots/README.md b/packages/client/ui-slots/README.md
index bb489dea0c..7ee2a3d22c 100644
--- a/packages/client/ui-slots/README.md
+++ b/packages/client/ui-slots/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Slot registry pure core, slot terminal design: SlotMap declaration merging, the single `register` composition API on SlotCore, the four-share component-props type family, the store-seat type family, and the renderer install-seam contract. React types only at runtime — the package is React-free and cordis-free.
+Slot registry pure core, slot terminal design: SlotMap declaration merging, the single `register` composition API on SlotCore, the four-share component-props type family, the store-seat type family, and the renderer installation contract. React types only at runtime — the package is React-free and cordis-free.
 
 One `register({ name, children?, store?, inject?, ...kind }, Component)` call contributes a component into a declared slot and, in the same breath, declares child slots (declaration = render authorization = runtime spec, one table), a store seat, and the registrant's business face. The component is checked at the call site against `ComposedProps` — the intersection of four shares, each derived from its single source of truth:
 
@@ -17,9 +17,9 @@ Chain-kind slots invert keyed routing — entries self-nominate instead of the d
 
 The standard-kit interfaces (`SessionStandardProps`, `GlobalStandardProps`) are declared empty here and merged by the runtime package (same declare-merge pattern as SlotMap keys). The renderer binds the runtime's session and workspace observable sources into selector hooks. Inject factory parameters derive from the declaration (`InjectParams`): session slots get `sessionId`, a declared store appends baked `actions`, nothing else — data access lives in the apply closure's ctx.
 
-The store family (`defineStore` spec in / `StoreHandle<T, A>` out) types the store seat: `init` infers the state schema, `actions` is the complete draft-transform write set, `BakedActions` strips the draft parameter into the callbacks components and inject factories receive. The `defineStore` value implementation lives in the runtime package (the engine's home) and satisfies the `DefineStore` contract exported here. Engine products and the renderer host contract carry bare snapshot sources (`getSnapshot`/`subscribe`), never React hooks — hook binding is the render machinery's side of the seam; only the props-contract hook type (`SnapshotSelectorHook`) lives here.
+The store family (`defineStore` spec in / `StoreHandle<T, A>` out) types the store seat: `init` infers the state schema, `actions` is the complete draft-transform write set, `BakedActions` strips the draft parameter into the callbacks components and inject factories receive. The `defineStore` value implementation lives in the runtime package (the engine's home) and satisfies the `DefineStore` contract exported here. Engine products and the renderer host contract carry bare snapshot sources (`getSnapshot`/`subscribe`), never React hooks — hook binding belongs to the render machinery; only the props-contract hook type (`SnapshotSelectorHook`) lives here.
 
-`SlotCore` seeds the a-priori `'root'` slot at construction and enforces load-time validation (undeclared-slot registration, duplicate child declaration, one shared handle under two scopes, a chain registration without `select` — all throw at register). An entry's disposer collapses its declared child slots recursively: ledger rows, contributions, and store mounts die on one lifecycle axis. Each key also carries a declaration epoch that advances only on declaration and collapse; the runtime uses it for [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection), independently from ordinary entry versions. `renderer.ts` carries the install seam (`SlotRenderer`, `SlotRendererHost`) plus `StaleAuthorizationError`/`SlotOwnershipError`; the implementation lives in web-react, the installation in the shell boot.
+`SlotCore` seeds the a-priori `'root'` slot at construction and enforces load-time validation (undeclared-slot registration, duplicate child declaration, one shared handle under two scopes, a chain registration without `select` — all throw at register). An entry's disposer collapses its declared child slots recursively: ledger rows, contributions, and store mounts die on one lifecycle axis. Each key also carries a declaration epoch that advances only on declaration and collapse; the runtime uses it for [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection), independently from ordinary entry versions. `renderer.ts` carries the installation contract (`SlotRenderer`, `SlotRendererHost`) plus `StaleAuthorizationError`/`SlotOwnershipError`; the implementation lives in web-react, the installation in the shell boot.
 
 ## Model Experience
 
diff --git a/packages/client/ui-slots/README.zh.md b/packages/client/ui-slots/README.zh.md
index 8b10ddf2d9..793bb2d1f7 100644
--- a/packages/client/ui-slots/README.zh.md
+++ b/packages/client/ui-slots/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Slot 注册表纯核心、slot 终端设计：SlotMap 声明合并、SlotCore 上唯一的 `register` 组合 API、四 share 组件 props 类型家族、store seat 类型家族，以及 renderer 安装 seam 约定。只使用 React 类型；该包不依赖 React，也不依赖 Cordis。
+Slot 注册表纯核心、slot 终端设计：SlotMap 声明合并、SlotCore 上唯一的 `register` 组合 API、四 share 组件 props 类型家族、store seat 类型家族，以及 renderer 安装约定。只使用 React 类型；该包不依赖 React，也不依赖 Cordis。
 
 一次 `register({ name, children?, store?, inject?, ...kind }, Component)` 调用会向已声明 slot 贡献一个组件，同时声明子 slot（声明 = 渲染授权 = 运行时规范，三者共用一张表）、store seat 以及注册方的业务表层。组件会在调用点依据 `ComposedProps` 接受检查；该类型是四个 share 的交集，每个 share 都从各自的唯一真源派生：
 
@@ -17,9 +17,9 @@ chain-kind slot 会反转键控路由：条目自行提名，而不是由分发
 
 标准工具包接口（`SessionStandardProps`、`GlobalStandardProps`）在这里声明为空，由 runtime 包合并（与 SlotMap key 相同的 declare-merge 模式）。renderer 会把运行时 Session 和 Workspace observable source 绑定为 selector hook。Inject factory 参数从声明派生（`InjectParams`）：Session slot 获得 `sessionId`；声明 store 时追加 baked `actions`；没有其他参数，数据访问位于 apply 闭包的 ctx 中。
 
-store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 约定。引擎产物与 renderer host 约定携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制这一侧的 seam，只有 props 约定 hook 类型（`SnapshotSelectorHook`）位于这里。
+store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 约定。引擎产物与 renderer host 约定携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制，只有 props 约定 hook 类型（`SnapshotSelectorHook`）位于这里。
 
-`SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与移除时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装 seam（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
+`SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与折叠时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装约定（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
 
 ## 模型体验
 
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index 6a20a8b916..7d7d9a6c34 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -211,7 +211,7 @@ export type MatchedShare<E extends SlotEntryDef, M> =
 /**
  * Conversation-session selector hook alias for props contracts. Wide by
  * default at this dependency-inverted layer; the runtime narrows at its
- * export seam (`UseSession<ConversationSnapshot>`).
+ * export outlet (`UseSession<ConversationSnapshot>`).
  */
 export type UseSession<Snap extends object = object> = SnapshotSelectorHook<Snap>
 
@@ -392,7 +392,7 @@ type BaseOptions<K extends keyof SlotMap & string, D extends ChildrenDecl, H, M
 
 /**
  * One stored registration, as recorded by the core and read by the render
- * machinery (type-erased at this boundary; the register seam already proved
+ * machinery (type-erased at this boundary; the registration contract already proved
  * the shares against the component).
  */
 export interface StoredEntry {
@@ -467,7 +467,7 @@ interface SlotRecord {
 const NO_ENTRIES: readonly StoredEntry[] = Object.freeze([])
 
 /**
- * Pure slot registry (no cordis; event emission and the renderer install seam
+ * Pure slot registry (no cordis; event emission and the renderer installation contract
  * live in the runtime Service wrapper).
  *
  * The 'root' slot is the one a-priori declaration, seeded at construction
diff --git a/packages/client/ui-slots/src/renderer.ts b/packages/client/ui-slots/src/renderer.ts
index 3bcb864a9d..2a676fa22a 100644
--- a/packages/client/ui-slots/src/renderer.ts
+++ b/packages/client/ui-slots/src/renderer.ts
@@ -34,11 +34,11 @@ export interface HostObservable<T> {
 }
 
 /**
- * Type-erased store instance face at the render seam (the typed twin is
+ * Type-erased store instance face at the render boundary (the typed twin is
  * {@link StoreInstance}): a bare snapshot source plus the draft-stripped
- * action callbacks. No React hook crosses this seam — the render machinery
+ * action callbacks. No React hook crosses this boundary — the render machinery
  * binds `useStore` from the source at its own side (cached per instance);
- * typing lands at the component seam via {@link PropsStore}.
+ * typing lands at the component boundary via {@link PropsStore}.
  */
 export interface StoreInstanceLike {
   getSnapshot(): unknown
@@ -54,7 +54,7 @@ export interface StoreInstanceLike {
 /**
  * Per-session standard props resolved per session id (identity-stable per
  * session scope; a recreated scope yields a new info). Plugins contribute
- * members through the runtime `sessions.provide` seam; the render side binds
+ * members through the runtime `sessions.provide` contract; the render side binds
  * every `hooks` source into a `use<Name>` selector hook (hooks never appear
  * on the host contract) and spreads `props` verbatim. The runtime itself
  * contributes the first entry (`'session'` → `useSession`).
@@ -161,7 +161,7 @@ export interface SlotRendererHost {
   locale?: LocaleFace | undefined
 }
 
-/** The install seam: runtime owns install()/renderSlot(); web-react implements rendering. */
+/** The installation contract: runtime owns install()/renderSlot(); web-react implements rendering. */
 export interface SlotRenderer {
   /**
    * Render the root slot tree over the host surface (the only ctx-level entry).
diff --git a/packages/client/ui-theme/src/client/settings-contract.ts b/packages/client/ui-theme/src/client/settings-contract.ts
index 60bfffebb5..f4fc5fe8da 100644
--- a/packages/client/ui-theme/src/client/settings-contract.ts
+++ b/packages/client/ui-theme/src/client/settings-contract.ts
@@ -1,5 +1,5 @@
 /**
- * Re-export seam for the `settings.general.item` slot type consumed by this
+ * Re-export outlet for the `settings.general.item` slot type consumed by this
  * package's Appearance row. The canonical home is the locale package (the
  * common dependency of every item registrant); this file exists so row
  * modules import the type from within their own package.
diff --git a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
index 2f5efae420..6c0bb956bd 100644
--- a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
@@ -89,7 +89,10 @@ function AppRoot({ renderSlot }: AppRootProps) {
   return <>{renderSlot('conversation', {})}</>
 }
 
-/** Same real-stack bench as the toolview-slot spec: SlotsService + renderer + both owning package applies; fakes only at service seams. */
+/**
+ * Same real-stack bench as the toolview-slot spec: SlotsService + renderer +
+ * both owning package applies; fakes only at service boundaries.
+ */
 async function bench(snapshot: ConversationSnapshot) {
   const ctx = new Context()
   const slotsFiber = ctx.plugin(SlotsService)
diff --git a/packages/client/ui-tool/tests/toolview-slot.spec.tsx b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
index e96c460576..c927cc30ea 100644
--- a/packages/client/ui-tool/tests/toolview-slot.spec.tsx
+++ b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
@@ -58,7 +58,7 @@ const LAYOUT_CHILDREN = {
 
 /**
  * Real-stack bench: SlotTestRuntime with the session/layout doubles at the
- * service seams only (external boundaries), the package apply on its own
+ * service boundaries only, the package apply on its own
  * fiber, and the test AppFrame occupying 'root'.
  */
 async function bench(nodes: ToolResultNode[]) {
diff --git a/packages/client/web-react/src/scoped-slots.tsx b/packages/client/web-react/src/scoped-slots.tsx
index 9c67da18d2..f7a3c32e93 100644
--- a/packages/client/web-react/src/scoped-slots.tsx
+++ b/packages/client/web-react/src/scoped-slots.tsx
@@ -350,7 +350,7 @@ function standardKit(
 /**
  * One rendered entry: standard kit + cached inject + owner props (owner
  * wins). The kit and injected shares are erased at the render boundary — the
- * register seam already proved the composed contract — so each Entry renders
+ * registration contract already proved the composed type — so each Entry renders
  * through a props-widened view of the component (the design-budgeted
  * composition point, one per scope branch).
  */
@@ -584,7 +584,7 @@ function RootOutlet({ ownerProps }: { ownerProps: object }) {
 /**
  * Build the renderer the shell installs into the runtime SlotsService
  * (ctx.slots.install(createSlotRenderer()) at boot; the service owns the
- * install/renderSlot seam and the double-install/not-installed throws).
+ * install/renderSlot contract and the double-install/not-installed throws).
  * @returns the renderer.
  */
 export function createSlotRenderer(): SlotRenderer {
diff --git a/packages/client/web/README.i18n.yaml b/packages/client/web/README.i18n.yaml
index cf0e86691f..cbb7dc9c17 100644
--- a/packages/client/web/README.i18n.yaml
+++ b/packages/client/web/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/client/web/README.md
-README.md: 74c481d573fb716e624e639c74b35c82e6894f63
-README.zh.md: 0e36107e50b2e22d65c126a4fd8873a89b0bb687
+README.md: 48355a046910bd5b78249af7b7781dab6a7c3a60
+README.zh.md: f0b567569849c698e8a1a29323e7088b49996522
diff --git a/packages/client/web/README.md b/packages/client/web/README.md
index 74c481d573..48355a0469 100644
--- a/packages/client/web/README.md
+++ b/packages/client/web/README.md
@@ -2,13 +2,13 @@
 
 English | [中文](README.zh.md)
 
-Web shell kernel: `new AppWebEntry(el, seams?).run()` mounts the whole client through the two-stage boot (web2). Stage one (module face): build the client module system (`@deepseek-ai/dsh-client-modules`) over the host-pushed entry graph (`window.__DSH_BOOT__`) and prefetch the `immediately` tier in parallel — bundle execution registers factories only. Stage two (plugin face): mount the vendored cordis Loader with the module system injected as its `internal` seam, create one loader entry per graph row plus the shell-own app-shell assembly entry (tree.import materializes each module), and gate AppRoot on the settle (loader quiesced + every entry fiber ACTIVE → full UI in one switch). Composition is entirely the host graph's: the roster and the immediately tier live in the composing app; the shell makes zero composition decisions.
+Web shell kernel: `new AppWebEntry(el, seams?).run()` mounts the whole client through the two-stage boot (web2). Stage one (module face): build the client module system (`@deepseek-ai/dsh-client-modules`) over the host-pushed entry graph (`window.__DSH_BOOT__`) and prefetch the `immediately` tier in parallel — bundle execution registers factories only. Stage two (plugin face): mount the vendored cordis Loader with the module system injected through its `internal` contract, create one loader entry per graph row plus the shell-own app-shell assembly entry (tree.import materializes each module), and gate AppRoot on the settle (loader quiesced + every entry fiber ACTIVE → full UI in one switch). Composition is entirely the host graph's: the roster and the immediately tier live in the composing app; the shell makes zero composition decisions.
 
 Shell self-sufficiency (web2 hard rule): the kernel value-imports no plugin package — the boot status store and signals are hand-rolled here (`loader-status.ts`), so the loading page works while (and especially when) plugins fail. The app-shell assembly (`@deepseek-ai/dsh-client-app-shell`, a shell-owned pseudo entry with no npm package behind it) is the only module registered through `registerStatic`; it inject-waits on slots/sessions/layout like any plugin.
 
 `PLATFORM_MODULES` (src/platform.ts) is the single source of truth for the shared module surface: seed-table keys, tsdown client externals, and the vite alias set are its projections.
 
-The optional `seams` parameter forwards the module system's `loadBundle` transport override (`BootSeams`) for environments where external `<script>` execution cannot reach the page context; ordinary browser callers omit it.
+The optional override parameter `seams` forwards the module system's `loadBundle` transport override (`BootSeams`) for environments where external `<script>` execution cannot reach the page context; ordinary browser callers omit it.
 
 The shell owns browser-title projection. With a selected session carrying a durable title, it renders `<session title> — <existing HTML title>` and reacts to later title revisions; no selection or a selected untitled session preserves the existing title, and shell unmount restores it. The existing HTML title remains the configurable product suffix.
 
diff --git a/packages/client/web/README.zh.md b/packages/client/web/README.zh.md
index 0e36107e50..f0b5675698 100644
--- a/packages/client/web/README.zh.md
+++ b/packages/client/web/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-Web 外壳内核：`new AppWebEntry(el, seams?).run()` 通过两阶段启动（web2）挂载整个客户端。第一阶段（模块侧）：构建客户端模块系统（`@deepseek-ai/dsh-client-modules`），以主机推送的配置项图（`window.__DSH_BOOT__`）为基础，并行预取 `immediately` 层级；执行组合包只会注册 factory。第二阶段（插件侧）：挂载仓库内置的 Cordis Loader，并把模块系统作为其 `internal` seam 注入；为每一行图数据创建一个 loader 配置项，另创建外壳自身的 app-shell 组装配置项（tree.import 会物化各模块）；以 settle 作为 AppRoot 的门禁（loader 完全停稳 + 每个配置项 fiber 都为 ACTIVE → 一次切换显示完整 UI）。组合完全由主机图决定：花名册和 immediately 层级都位于负责组合的应用中；外壳不作任何组合决策。
+Web 外壳内核：`new AppWebEntry(el, seams?).run()` 通过两阶段启动（web2）挂载整个客户端。第一阶段（模块侧）：构建客户端模块系统（`@deepseek-ai/dsh-client-modules`），以主机推送的配置项图（`window.__DSH_BOOT__`）为基础，并行预取 `immediately` 层级；执行组合包只会注册 factory。第二阶段（插件侧）：挂载仓库内置的 Cordis Loader，并通过其 `internal` 约定注入模块系统；为每一行图数据创建一个 loader 配置项，另创建外壳自身的 app-shell 组装配置项（tree.import 会物化各模块）；以 settle 作为 AppRoot 的门禁（loader 完全停稳 + 每个配置项 fiber 都为 ACTIVE → 一次切换显示完整 UI）。组合完全由主机图决定：花名册和 immediately 层级都位于负责组合的应用中；外壳不作任何组合决策。
 
 外壳自给自足（web2 硬性规则）：内核不对任何插件包（package）执行值导入；启动状态 store 与信号在这里手写（`loader-status.ts`），因此即使插件失败，加载页面仍能工作，而此时这一点尤其重要。app-shell 组装（`@deepseek-ai/dsh-client-app-shell`，由外壳拥有、背后没有 npm 包的伪配置项）是唯一通过 `registerStatic` 注册的模块；它与任何插件一样，通过 inject 等待 slots/sessions/layout。
 
 `PLATFORM_MODULES`（src/platform.ts）是共享模块表层的唯一真源：种子表 key、tsdown 客户端 external 和 vite alias 集都是它的投影。
 
-可选 `seams` 参数会为外部 `<script>` 执行无法到达页面上下文的环境转发模块系统的 `loadBundle` 传输覆盖（`BootSeams`）；普通浏览器调用方省略此参数。
+可选的覆盖参数 `seams` 会为外部 `<script>` 执行无法到达页面上下文的环境转发模块系统的 `loadBundle` 传输覆盖（`BootSeams`）；普通浏览器调用方省略此参数。
 
 外壳拥有浏览器标题投影。选中带有持久标题的会话时，它会渲染 `<session title> — <existing HTML title>` 并响应后续标题修订；未选择会话或选中无标题会话时，会保留现有标题；外壳卸载时恢复标题。现有 HTML 标题仍是可配置的产品后缀。
 
diff --git a/packages/client/web/src/boot.tsx b/packages/client/web/src/boot.tsx
index 010f0ea437..cf63247915 100644
--- a/packages/client/web/src/boot.tsx
+++ b/packages/client/web/src/boot.tsx
@@ -12,7 +12,7 @@
  * `window.__DSH_BOOT__` into the two-view BootManifest (wire boundary, D16)
  * → build the module system over the module-view rows → render the loading
  * page → prefetch every `immediately` row in parallel with mounting the
- * vendored cordis Loader (internal-seam injection BEFORE any entry exists —
+ * vendored cordis Loader (`internal` contract injection BEFORE any entry exists —
  * the bare-import fallback in tree.import must never run in a browser) →
  * await the prefetch tier, THEN adopt the modules entry and create one
  * loader entry per plugin-view row plus the shell-own app-shell assembly
@@ -47,7 +47,7 @@ import { getStaticModules } from './seed.ts'
 import { STATE_LABELS, createLoaderStatusStore, createSignal } from './loader-status.ts'
 import './base.css'
 
-/** Module transport seam the shell passes through (jsdom tests replace the <script> path). */
+/** Module transport hook the shell passes through (jsdom tests replace the <script> path). */
 export type BootSeams = Pick<ClientModuleSystemOptions, 'loadBundle'>
 
 /**
@@ -80,7 +80,7 @@ export class AppWebEntry {
   /**
    * Hold the mount point; all work happens in {@link run}.
    * @param el - mount point (the app's #root).
-   * @param seams - optional module transport overrides (test environments).
+   * @param seams - Optional module transport overrides for test environments.
    */
   constructor(el: HTMLElement, seams?: BootSeams) {
     this.el = el
@@ -157,7 +157,7 @@ export class AppWebEntry {
       })))
   }
 
-  /** Plugin face: mount the Loader, inject the internal seam, adopt modules, create the graph entries, settle, sweep. */
+  /** Plugin face: mount the Loader, inject the `internal` contract, adopt modules, create the graph entries, settle, sweep. */
   private async runPluginBoot(prefetching: Promise<void>): Promise<void> {
     const ctx = this.ctx
     await ctx.plugin(Loader)
diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml
index 1f9b94c59b..fb72d6b9c2 100644
--- a/packages/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/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/code-runtime/README.md
-README.md: 45dd55b8609fd33b7116f6b2ea36df3b3332e419
-README.zh.md: ebf288a49f87ad01b1ec80c3843c87c91206af26
+README.md: 024dea980b1678ca7d375bad4d4a627b4956bb02
+README.zh.md: eaedc8acf7211e0347fdfbcb934f9013dc7539bd
diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md
index 45dd55b860..024dea980b 100644
--- a/packages/code-runtime/README.md
+++ b/packages/code-runtime/README.md
@@ -2,13 +2,13 @@
 
 English | [中文](README.zh.md)
 
-The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's [Code Mode](../core/tools/README.md) (`tools: { mode: code }` — the `run_code` tool and the SDK generated in the loaded runtime's `language`); design in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
+The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): a runtime Service Definition for executing one model-written program against host-provided async bindings, capturing what it printed and returned; replaceable providers; and the tool registry's [Code Mode](../core/tools/README.md) Consumer (`tools: { mode: code }` — the `run_code` tool and the SDK generated in the loaded runtime's `language`). Design is in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`code-runtime/`](code-runtime/README.md) | Code-execution seam and shared vocabulary | `ctx.codeRuntime` |
+| [`code-runtime/`](code-runtime/README.md) | Service Definition and shared vocabulary | `ctx.codeRuntime` |
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend | registers `ctx.codeRuntime` |
 
-Backends register the seam without changing its consumer. The child READMEs own language, isolation, and execution-budget details.
+Providers register the service without changing its Consumer. The child READMEs own language, isolation, and execution-budget details.
 
 The subsystem reference — run requests/results, binding namespaces, the failure taxonomy — is [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md).
diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md
index ebf288a49f..eaedc8acf7 100644
--- a/packages/code-runtime/README.zh.md
+++ b/packages/code-runtime/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：一个抽象运行时接口，用于对宿主提供的异步绑定执行模型编写的程序，并捕获它打印和返回的内容。消费方是工具注册表的 [Code Mode](../core/tools/README.md)（`tools: { mode: code }`，即 `run_code` 工具和按所加载运行时 `language` 生成的 SDK）；设计见 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)。这些全是**产品**包。
+代码执行能力 seam（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：运行时 Service Definition，用于对宿主提供的异步绑定执行模型编写的程序，并捕获它打印和返回的内容；可替换的提供方；以及工具注册表的 [Code Mode](../core/tools/README.md) Consumer（`tools: { mode: code }`，即 `run_code` 工具和按所加载运行时 `language` 生成的 SDK）。设计见 [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`code-runtime/`](code-runtime/README.md) | 代码执行 seam 与共享词汇 | `ctx.codeRuntime` |
+| [`code-runtime/`](code-runtime/README.md) | Service Definition 与共享词汇 | `ctx.codeRuntime` |
 | [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker 线程后端 | 注册 `ctx.codeRuntime` |
 
-后端在不改变消费方的情况下注册该 seam。子 README 负责语言、隔离和执行预算细节。
+提供方在不改变 Consumer 的情况下注册该服务。子 README 负责语言、隔离和执行预算细节。
 
 子系统参考——运行请求/结果、绑定命名空间、失败分类体系——见 [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md)。
diff --git a/packages/code-runtime/code-runtime-worker/src/index.ts b/packages/code-runtime/code-runtime-worker/src/index.ts
index 43801899a2..8193cb587e 100644
--- a/packages/code-runtime/code-runtime-worker/src/index.ts
+++ b/packages/code-runtime/code-runtime-worker/src/index.ts
@@ -231,7 +231,7 @@ class OutputLedger {
 /**
  * The shipped {@link CodeRuntime} backend (`ctx.codeRuntime`). Registers as
  * the `codeRuntime` service; every cap comes from validated config. See the
- * module doc for the containment model and the class JSDoc on the seam for
+ * module doc for the containment model and the Service Definition's class JSDoc for
  * the contract this implements (error-as-field, hostile-peer port,
  * no cross-run state, dispose to quiescence).
  */
@@ -285,7 +285,7 @@ export class WorkerCodeRuntime extends CodeRuntime {
   /**
    * Execute one program in a fresh worker. Program outcomes — including a
    * type-strip syntax error, which never spawns a worker — resolve with
-   * `result.error`; the method rejects only for seam misuse (a disposed
+   * `result.error`; the method rejects only for Service Definition contract misuse (a disposed
    * runtime, an invalid binding namespace).
    * @param request - the program, its bindings, and the abort signal.
    * @returns the run's outcome per the seam contract.
@@ -316,7 +316,7 @@ export class WorkerCodeRuntime extends CodeRuntime {
     return new OutputLedger(this.config.maxOutputBytes).failure([], error)
   }
 
-  /** Reject malformed binding globals or typed-error declarations as seam misuse. */
+  /** Reject malformed binding globals or typed-error declarations as Service Definition contract misuse. */
   private validateBindings(request: CodeRunRequest): Map<string, CodeBindingNamespace> {
     const bindings = new Map<string, CodeBindingNamespace>()
     for (const namespace of request.bindings) {
diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml
index 0a72d1608c..77bd626bec 100644
--- a/packages/code-runtime/code-runtime/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime/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/code-runtime/code-runtime/README.md
-README.md: 637cc6adae3372ea60ca003f74af416513484270
-README.zh.md: fcc4c7323dd547c2421bb1e5a009481bf78cfc70
+README.md: 1d3cee958c186b7d0b2be1f69400977d009abc40
+README.zh.md: 9aac1196085d12dfe240af7667e98787f445c534
diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md
index 637cc6adae..1d3cee958c 100644
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -4,13 +4,13 @@ English | [中文](README.zh.md)
 
 The **`CodeRuntime`** (`ctx.codeRuntime`) defines WHAT a code runtime does — run one model-written program against a set of host-provided async bindings and report `{ value, logs, error? }` — without saying HOW.
 
-This package is the interface third of the capability (the bash trio is the template — see [capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): implementations subclass `CodeRuntime` and register the service; the consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md), whose first implementation is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the consumer.
+This package owns the Service Definition role of the capability (the bash trio is the template — see [capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): providers subclass `CodeRuntime` and register the service; the Consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md), whose first provider is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the Consumer.
 
 ## Service API (`ctx.codeRuntime`)
 
 | Member | Semantics |
 |---|---|
-| `run(request)` | Execute one program against the request's bindings. **Resolves with an error FIELD for every program outcome** — parse/transform failure, thrown exception, invalid completion, output overflow, budget expiry, abort, or substrate death (`CodeRunFailure`'s orthogonal `kind` taxonomy); it rejects only for caller misuse of the seam itself (e.g. a run submitted after disposal). The program runs as the body of an async function: top-level `await`/`return` work, and a lossless JSON completion becomes `result.value`. |
+| `run(request)` | Execute one program against the request's bindings. **Resolves with an error FIELD for every program outcome** — parse/transform failure, thrown exception, invalid completion, output overflow, budget expiry, abort, or substrate death (`CodeRunFailure`'s orthogonal `kind` taxonomy); it rejects only for caller misuse of the Service Definition contract (e.g. a run submitted after disposal). The program runs as the body of an async function: top-level `await`/`return` work, and a lossless JSON completion becomes `result.value`. |
 | `language` | Readonly descriptor: the source language `run` expects. `'typescript'` and `'python'` are the well-known values — those `dsh-tools` presents; only `'typescript'` has a published backend. Informational, not gating — a consumer that generates language-specific presentation switches on it and fails loud on a language it cannot present. |
 | `isolation` | Readonly descriptor: the execution substrate (`'worker-thread'`, `'process'`, `'container'`). A label for deployments and diagnostics, **not a security claim**. |
 
@@ -18,7 +18,7 @@ Semantics every implementation must honor (contract details in the class JSDoc):
 
 ## Vocabulary
 
-`CodeRunRequest` (`program`, `bindings`, `signal?`) carries everything the runtime acts on — defaulting (time budgets and outer-output cap) is the implementation's validated config, never a hidden `??` inside `run()`. `bindings` is a list of `CodeBindingNamespace`s (`global` + `functions` + optional `errorClass`), each exposed to the program as one global object of async callables returning `CodeJsonValue`, the seam-local structural equivalent of canonical `JsonValue` that keeps this interface package independent of sessions. An `errorClass` descriptor names a real program-global constructor and the own property that receives the rejected member name; runtimes remain independent of consumer terms such as `ToolCallError`. `CodeRunResult` reports the lossless JSON completion `value?`, ordered `logs: string[]`, and the `error?` (`CodeRunFailure`: `kind` + model-feedable `message`). See `src/types.ts` for the full contracts.
+`CodeRunRequest` (`program`, `bindings`, `signal?`) carries everything the runtime acts on — defaulting (time budgets and outer-output cap) is the provider's validated config, never a hidden `??` inside `run()`. `bindings` is a list of `CodeBindingNamespace`s (`global` + `functions` + optional `errorClass`), each exposed to the program as one global object of async callables returning `CodeJsonValue`, the service-local structural equivalent of canonical `JsonValue` that keeps this Service Definition package independent of sessions. An `errorClass` descriptor names a real program-global constructor and the own property that receives the rejected member name; runtimes remain independent of Consumer terms such as `ToolCallError`. `CodeRunResult` reports the lossless JSON completion `value?`, ordered `logs: string[]`, and the `error?` (`CodeRunFailure`: `kind` + model-feedable `message`). See `src/types.ts` for the full contracts.
 
 Binding-global and error-class names are **language-portable**: they must match the identifier subset `[A-Za-z_][A-Za-z0-9_]*` (no JS-only `$`) and clear the seam-exported exclusion sets, so one `bindings` list is valid against every backend regardless of its `language`. The package exports the contract every backend enforces — `PORTABLE_RESERVED_WORDS` (ECMAScript ∪ Python reserved words), `RESERVED_BINDING_GLOBALS` (backend-owned globals such as `console`), `RESERVED_ERROR_MEMBERS` and `DUNDER_MEMBER` (error-member exclusions) — so a name like `$tools`, `lambda`, or `__dsh_main__` makes `run()` reject as seam misuse on any backend, not just some. See `src/index.ts` for the exact sets and rationale.
 
diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md
index fcc4c7323d..9aac119608 100644
--- a/packages/code-runtime/code-runtime/README.zh.md
+++ b/packages/code-runtime/code-runtime/README.zh.md
@@ -4,13 +4,13 @@
 
 **`CodeRuntime`**（`ctx.codeRuntime`）定义代码运行时做什么，即针对宿主提供的一组异步绑定运行一段模型编写的程序，并报告 `{ value, logs, error? }`，而不规定如何实现。
 
-此包承担该能力三个组成部分中的接口职责（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：实现通过继承 `CodeRuntime` 并注册服务接入；消费方是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。这两项职责均由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个实现是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有与工具有关的内容都留在消费方。
+此包承担该能力的 Service Definition 角色（以 bash 三包结构为模板，参见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：提供方通过继承 `CodeRuntime` 并注册服务接入；Consumer 是工具注册表的 Code Mode，它生成面向模型的 SDK，并桥接工具分发。这两项职责均由 [Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 规定，首个提供方是 Node worker 线程后端。运行时不了解工具或会话：调用方只向它提供具名异步函数与程序字符串；所有与工具有关的内容都留在 Consumer。
 
 ## 服务 API（`ctx.codeRuntime`）
 
 | 成员 | 语义 |
 |---|---|
-| `run(request)` | 针对请求的绑定执行一段程序。**所有程序失败结果都通过 resolve 结果中的 error 字段报告**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底终止（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 seam 本身时才 reject（例如 dispose（资源释放）后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
+| `run(request)` | 针对请求的绑定执行一段程序。**所有程序失败结果都通过 resolve 结果中的 error 字段报告**：包括解析／转换失败、抛出异常、无效完成值、输出溢出、预算到期、中止或执行基底终止（由 `CodeRunFailure` 的正交 `kind` 分类表示）；只有调用方误用 Service Definition 约定时才 reject（例如 dispose（资源释放）后仍提交运行）。程序作为异步函数的函数体运行，因此顶层 `await`／`return` 可用，无损 JSON 完成值会成为 `result.value`。 |
 | `language` | 只读描述符：`run` 期望的源语言。已知值为 `'typescript'` 与 `'python'`——`dsh-tools` 能呈现的那些；其中只有 `'typescript'` 有已发布的后端。仅供参考，不作门禁；生成语言专用呈现的消费方会根据该值选择分支，遇到无法呈现的语言时明确失败。 |
 | `isolation` | 只读描述符：执行基底（`'worker-thread'`、`'process'`、`'container'`）。供部署与诊断使用，**不构成安全声明**。 |
 
@@ -18,7 +18,7 @@
 
 ## 词汇
 
-`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于实现的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型，使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整约定见 `src/types.ts`。
+`CodeRunRequest`（`program`、`bindings`、`signal?`）携带运行时操作所需的全部内容；默认值解析（时间预算与外层输出上限）属于提供方的已验证配置，绝不能是隐藏的 `??`，更不能藏在 `run()` 内部。`bindings` 是 `CodeBindingNamespace` 列表（`global` + `functions` + 可选 `errorClass`）；每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序，这些函数返回 `CodeJsonValue`。后者是服务本地、与规范 `JsonValue` 结构等价的类型，使 Service Definition 包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器，以及用于接收被拒绝成员名称的自有属性；运行时不依赖 `ToolCallError` 等 Consumer 术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]` 和 `error?`（`CodeRunFailure`：`kind` + 可反馈给模型的 `message`）。完整约定见 `src/types.ts`。
 
 binding-global 与 error-class 名称是**语言可移植**的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效，无论其 `language` 为何。本包导出每个后端都执行的约定——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda`、`__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject，而非只在某些后端。确切集合与理由见 `src/index.ts`。
 
diff --git a/packages/code-runtime/code-runtime/src/index.ts b/packages/code-runtime/code-runtime/src/index.ts
index 3428b5c0e4..a4edc604c8 100644
--- a/packages/code-runtime/code-runtime/src/index.ts
+++ b/packages/code-runtime/code-runtime/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Code-execution seam for running one model-written program against host async bindings.
+ * Service Definition for the code-execution capability seam that runs one model-written program against host async bindings.
  * Runtimes know nothing about tools or sessions; consumers own those concerns.
  * @module @deepseek-ai/dsh-code-runtime
  */
@@ -96,7 +96,7 @@ declare module 'cordis' {
 
 /**
  * Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate
- * failures resolve in {@link CodeRunResult}; only seam misuse rejects. Implementations bridge
+ * failures resolve in {@link CodeRunResult}; only Service Definition contract misuse rejects. Implementations bridge
  * structured-cloneable bindings, materialize each declared namespace rejection
  * class, treat programs as hostile peers, isolate runs from one another, and
  * terminate and await in-flight runs during disposal.
@@ -127,7 +127,7 @@ export abstract class CodeRuntime extends Service {
   /**
    * Execute one program against the request's bindings and capture what it
    * emitted. See the class doc for the resolution contract (error is a result
-   * field; rejection means seam misuse only).
+   * field; rejection means Service Definition contract misuse only).
    * @param request - the program, its bindings, and the abort signal; the
    *   request carries everything the runtime acts on, with no hidden defaults.
    * @returns the run's outcome: completion value (when transferable), the
diff --git a/packages/code-runtime/code-runtime/src/types.ts b/packages/code-runtime/code-runtime/src/types.ts
index 6d83ace689..a204b113ac 100644
--- a/packages/code-runtime/code-runtime/src/types.ts
+++ b/packages/code-runtime/code-runtime/src/types.ts
@@ -17,7 +17,7 @@
  */
 export type CodeBindingFunction = (args: unknown) => Promise<CodeJsonValue>
 
-/** A lossless JSON value transferable across the dependency-light code-runtime seam. */
+/** A lossless JSON value transferable through the dependency-light Service Definition. */
 export type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
 
 /**
diff --git a/packages/code-runtime/code-runtime/tests/reserved.spec.ts b/packages/code-runtime/code-runtime/tests/reserved.spec.ts
index f93b63b5ef..c2df873fc4 100644
--- a/packages/code-runtime/code-runtime/tests/reserved.spec.ts
+++ b/packages/code-runtime/code-runtime/tests/reserved.spec.ts
@@ -7,7 +7,7 @@ import {
 } from '@deepseek-ai/dsh-code-runtime'
 
 /**
- * The seam owns the portable-identifier exclusion sets so every backend
+ * The Service Definition owns the portable-identifier exclusion sets so every backend
  * enforces one contract: a namespace list valid on one backend is valid on
  * all. These assertions pin the shared membership backends import rather than
  * re-declare.
diff --git a/packages/code-runtime/code-runtime/tests/service.spec.ts b/packages/code-runtime/code-runtime/tests/service.spec.ts
index 605b51934f..7ea3a30b31 100644
--- a/packages/code-runtime/code-runtime/tests/service.spec.ts
+++ b/packages/code-runtime/code-runtime/tests/service.spec.ts
@@ -6,7 +6,7 @@ import type { CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtim
 /**
  * Minimal concrete runtime: records requests, "executes" by invoking every
  * binding once in declaration order, and lets tests script the outcome. The
- * seam package ships no implementation, so the contract is exercised through
+ * Service Definition package ships no provider, so the contract is exercised through
  * the smallest subclass that honors it.
  */
 class StubRuntime extends CodeRuntime {
diff --git a/packages/compact/README.i18n.yaml b/packages/compact/README.i18n.yaml
index 7e8ef24260..ab4714ff9d 100644
--- a/packages/compact/README.i18n.yaml
+++ b/packages/compact/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/compact/README.md
-README.md: 0a83b87f57e4c948ee6df9e622f17964aff00f0f
-README.zh.md: 001ca6f7c079a60cbd432664e4f0b06955aaf487
+README.md: 0b5a5b18b963dc7be0bd314420bdb3c88715533d
+README.zh.md: 5d6d8a1c076e444094cc030c9495f346f40bf7ea
diff --git a/packages/compact/README.md b/packages/compact/README.md
index 0a83b87f57..0b5a5b18b9 100644
--- a/packages/compact/README.md
+++ b/packages/compact/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-A compaction capability family (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract interface, a summarizing backend, a model-free tool-result pruning companion, and a human command adapter. All **product** packages.
+A compaction capability family (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): a Service Definition, a summarizing provider, a model-free tool-result pruning companion, and a human command Consumer. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/compact/README.zh.md b/packages/compact/README.zh.md
index 001ca6f7c0..5d6d8a1c07 100644
--- a/packages/compact/README.zh.md
+++ b/packages/compact/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个压缩（compaction）能力家族（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：抽象接口、摘要后端、无模型工具结果修剪配套工具，以及用户命令适配器。这些全是**产品**包。
+一个压缩（compaction）能力家族（参见[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：Service Definition、摘要提供方、无模型工具结果修剪配套工具，以及人类命令 Consumer。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/compact/compact-basic/README.i18n.yaml b/packages/compact/compact-basic/README.i18n.yaml
index c01b9166b5..f44b45245d 100644
--- a/packages/compact/compact-basic/README.i18n.yaml
+++ b/packages/compact/compact-basic/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/compact/compact-basic/README.md
-README.md: 5395219147e8932c8e5874e84e534a2c2fe33d53
-README.zh.md: 59479b26c5c8cf27e6ac84814c09f14ecbf9662c
+README.md: e0e3413d42e6afb8e95f91d79f9bdf3a1f17fbda
+README.zh.md: 4515592710f855dc713f078479ebe7c9c7299de1
diff --git a/packages/compact/compact-basic/README.md b/packages/compact/compact-basic/README.md
index 5395219147..e0e3413d42 100644
--- a/packages/compact/compact-basic/README.md
+++ b/packages/compact/compact-basic/README.md
@@ -2,9 +2,9 @@
 
 English | [中文](README.zh.md)
 
-The **basic compaction backend**: a `BasicCompactService` implementing the `@deepseek-ai/dsh-compact` seam with reusable `ctx.tokenMeter` pressure, token-budget retention, and summarization as a direct one-shot `ctx.llm.stream()` call that replays the conversation prefix to reuse the provider's KV cache (interceptable at `llm/stream`).
+The **basic compaction backend**: a `BasicCompactService` implementing the `@deepseek-ai/dsh-compact` Service Definition with reusable `ctx.tokenMeter` pressure, token-budget retention, and summarization as a direct one-shot `ctx.llm.stream()` call that replays the conversation prefix to reuse the provider's KV cache (interceptable at `llm/stream`).
 
-This is the implementation tier of the compaction capability — see the [interface package](../compact/README.md) for the seam and the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) for the design.
+This package owns the Service provider role of the compaction capability — see the [Service Definition package](../compact/README.md) for its contract and the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) for the design.
 
 ## What it owns
 
@@ -15,7 +15,7 @@ This backend owns the compaction policy:
 - **Model-free pruning** — after pressure or canonical overflow qualifies, the optional [`ctx.toolResultPrune`](../compact-tool-result-prune/README.md) service rewrites oversized tool results before range selection. Compact-basic remeasures through `ctx.tokenMeter`, skips summarization when pressure becomes safe, and otherwise summarizes the pruned surface. Below-pressure step checks never prune.
 - **Retention** — compact the oldest whole surface units while preserving a recent tail and balanced tool-call/result cuts through the [`dsh-compact` boundary helpers](../compact/README.md#tool-pairing-boundaries). Turn boundaries do not protect old steps inside a runaway turn. An open indivisible tail declines until it closes. The optional pruner can repair an oversized closed tool unit when its text-bearing result is the removable bulk; indivisible non-tool units and non-prunable tool remainders remain out of scope.
 - **Convergence** — retry head-checkpoint compaction up to `compactionRetries`; reject a summary that does not shrink its source, and throw if retries cannot return below threshold.
-- **Summarization** — a direct `llm/stream` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the agent target, without running the loop-only `agent/request` seam. The call replays the conversation's own system prompt, tools, and shadowed-region messages verbatim and appends the compaction instruction as the final user message, so it reuses the provider's warm prefix cache instead of invalidating it. It sets `GenerateOptions.purpose` to `compaction`, which adapters may forward as request attribution (the DeepSeek adapter sends `x-deepseek-harness-compact: 1`) without touching the model-visible body. Only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
+- **Summarization** — a direct `llm/stream` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the agent target, without running the loop-only `agent/request` extension point. The call replays the conversation's own system prompt, tools, and shadowed-region messages verbatim and appends the compaction instruction as the final user message, so it reuses the provider's warm prefix cache instead of invalidating it. It sets `GenerateOptions.purpose` to `compaction`, which adapters may forward as request attribution (the DeepSeek adapter sends `x-deepseek-harness-compact: 1`) without touching the model-visible body. Only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
 - **Framing** — the replacement user message marks established checkpoint context with `<compacted-summary>` tags. The raw summary remains on the `compact/summary` event, and later automatic cycles merge the prior checkpoint.
 - **Lifecycle** — all entry points share one bracket-first region transaction. It validates the range and live lock, appends `compact/start` synchronously, prepares and awaits the summary, revalidates, appends `compact/summary` plus the replacement, and makes exactly one closing attempt. Automatic and explicit-region calls require a numeric open-turn owner and whole-surface stability; the serial `agent/pre-step` listener checks pressure before request derivation, while canonical provider overflow enters through `agent/request-error` and authorizes retry only after durable surface progress. `compactNow()` reserves idle admission, uses `turn: null`, accepts append-only context outside its selected span, flushes every closed attempt, and releases admission in `finally`.
 - **Overflow recovery** — provider-confirmed overflow needs no capacity metadata: it bypasses normal pressure and retention, prunes, then attempts one maximal balanced head reduction while leaving the newest indivisible unit. Retry is authorized whenever `surface.replaceGeneration` advances, including when pruning lands before later summary work throws. No replacement, an exhausted target-specific cap, cancellation, or an unknown/noncanonical error preserves the original provider failure.
diff --git a/packages/compact/compact-basic/README.zh.md b/packages/compact/compact-basic/README.zh.md
index 59479b26c5..4515592710 100644
--- a/packages/compact/compact-basic/README.zh.md
+++ b/packages/compact/compact-basic/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-**基础压缩（compaction）后端**：`BasicCompactService` 实现 `@deepseek-ai/dsh-compact` seam，使用可复用的 `ctx.tokenMeter` 压力、token 预算保留与摘要。摘要是直接的一次性 `ctx.llm.stream()` 调用，它会回放会话前缀以复用提供方的 KV Cache（可在 `llm/stream` 处拦截）。
+**基础压缩（compaction）后端**：`BasicCompactService` 实现 `@deepseek-ai/dsh-compact` Service Definition，使用可复用的 `ctx.tokenMeter` 压力、token 预算保留与摘要。摘要是直接的一次性 `ctx.llm.stream()` 调用，它会回放会话前缀以复用提供方的 KV Cache（可在 `llm/stream` 处拦截）。
 
-这是压缩能力的实现层。seam 见 [接口包](../compact/README.md)，设计见 [能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
+本包承担压缩能力的 Service provider 角色；其约定见 [Service Definition 包](../compact/README.md)，设计见 [能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。
 
 ## 拥有的职责
 
@@ -15,7 +15,7 @@
 - **不依赖模型的剪枝**：在压力或规范溢出符合条件后，可选的 [`ctx.toolResultPrune`](../compact-tool-result-prune/README.md) 服务会在选择范围之前改写超大工具结果。Compact-basic 通过 `ctx.tokenMeter` 重新测量；如果压力已回到安全范围，就跳过摘要，否则对已剪枝的表层进行摘要。低于压力的步骤检查绝不剪枝。
 - **保留**：压缩最旧的完整表层单元，同时保留近期尾部，并通过 [`dsh-compact` 边界 helper](../compact/README.md#tool-pairing-boundaries) 将切分点调整到工具调用／结果配对平衡的位置。轮次边界不会保护失控轮次内的旧步骤。尚未闭合且不可分的尾部会在闭合前拒绝压缩。当闭合的超大工具单元以文本型结果为可移除主体时，可选 pruner 可以修复它；不可分的非工具单元与不可剪枝的工具剩余部分不在范围内。
 - **收敛**：最多按 `compactionRetries` 重试头部检查点压缩；拒绝不能缩小源内容的摘要，如果重试仍无法回到阈值以下，则抛出异常。
-- **摘要**：直接 `llm/stream` 调用使用已配置的提供方／模型对与上限，回退到最新已记录请求目标，然后再回退到 agent 目标，而不运行仅用于 agent loop 的 `agent/request` seam。该调用会逐字回放会话自身的系统提示词、工具与已遮蔽区域消息，并将压缩指令作为最后一条 user 消息追加，从而复用提供方的热前缀 cache，而非使它失效。它将 `GenerateOptions.purpose` 设为 `compaction`，适配器可将其作为请求归因转发（DeepSeek 适配器发送 `x-deepseek-harness-compact: 1`），但不会触碰模型可见的请求体。只有返回的文本会进入检查点；推理（reasoning）和工具调用都会被排除，以免泄露私有推理或产生遗留调用。
+- **摘要**：直接 `llm/stream` 调用使用已配置的提供方／模型对与上限，回退到最新已记录请求目标，然后再回退到 agent 目标，而不运行仅用于 agent loop 的 `agent/request` 扩展点。该调用会逐字回放会话自身的系统提示词、工具与已遮蔽区域消息，并将压缩指令作为最后一条 user 消息追加，从而复用提供方的热前缀 cache，而非使它失效。它将 `GenerateOptions.purpose` 设为 `compaction`，适配器可将其作为请求归因转发（DeepSeek 适配器发送 `x-deepseek-harness-compact: 1`），但不会触碰模型可见的请求体。只有返回的文本会进入检查点；推理（reasoning）和工具调用都会被排除，以免泄露私有推理或产生遗留调用。
 - **框定**：替换 user 消息使用 `<compacted-summary>` 标签标记已建立的检查点上下文。原始摘要保留在 `compact/summary` 事件上，后续自动周期会合并之前的检查点。
 - **生命周期**：所有入口点共享一个先记录标记的区域事务。它会验证范围与活动锁，同步追加 `compact/start`，准备并等待摘要，重新验证，再追加 `compact/summary` 和替换，最后恰好进行一次闭合尝试。自动调用和显式范围调用要求数字标识的开放轮次归属，并要求整个表层保持稳定；串行 `agent/pre-step` listener 会在派生请求之前检查压力，而规范提供方溢出则经由 `agent/request-error` 进入，并且只在表层取得持久进展后才允许重试。`compactNow()` 会预留空闲接纳，使用 `turn: null`，允许所选 span 之外追加仅追加上下文，flush 每次已闭合尝试，并在 `finally` 中释放接纳预留。
 - **溢出恢复**：提供方已确认的溢出不需容量元数据。它会绕过常规压力与保留，执行剪枝，再尝试一次最大平衡头部缩减，并留下最新不可分单元。只要 `surface.replaceGeneration` 前进，就允许重试，包括剪枝在后续摘要工作抛出异常前已落地的情况。如果没有替换、目标特定上限已耗尽、已取消，或遇到未知／非规范错误，则保留原始提供方失败。
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index dae5564742..ec95ee2165 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: c7fdbef33b2e65089a0f0112e19122db4f26bb77
-README.zh.md: 493d269202b3a5b89cd600391e7144219ed2bf12
+README.md: 3fecc91422bcdc994bcbe4db308ee4a52cb3c53f
+README.zh.md: ea66d8bdb0684f27cf68a5431be75966041b7534
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index c7fdbef33b..3fecc91422 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -4,19 +4,19 @@ English | [中文](README.zh.md)
 
 The **`CompactService`** (`ctx.compact`) defines WHAT compaction does — decide when history is too large and summarize an older range into a single surface node — without saying HOW.
 
-This package is the interface tier of the compaction capability, split so each concern evolves (and swaps) independently:
+This package owns the Service Definition role of the compaction capability, split so each role evolves (and swaps) independently:
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` + canonical checkpoint source + tool-pairing boundary helpers |
-| `@deepseek-ai/dsh-compact-basic` | a backend: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization |
-| `@deepseek-ai/dsh-command-compact` | the human `/compact` command over `ctx.compact.compactNow()` |
+| `@deepseek-ai/dsh-compact` (this) | Service Definition: abstract service + `compact/*` events + `CompactionResult` + canonical checkpoint source + tool-pairing boundary helpers |
+| `@deepseek-ai/dsh-compact-basic` | Service provider: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization |
+| `@deepseek-ai/dsh-command-compact` | Consumer: the human `/compact` command over `ctx.compact.compactNow()` |
 
-Unlike the bash seam, this interface depends on `@deepseek-ai/dsh-session` and `@deepseek-ai/dsh-llm` — the contract's verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so they cannot be expressed without naming those packages. That deviation from the "interface depends only on cordis" guidance is intentional and recorded in the [compaction capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
+Unlike the bash seam, this Service Definition depends on `@deepseek-ai/dsh-session` and `@deepseek-ai/dsh-llm` — the contract's verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so they cannot be expressed without naming those packages. That deviation from the "Service Definition depends only on cordis" guidance is intentional and recorded in the [compaction capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
 
 ## Service API (`ctx.compact`)
 
-All three operations are **abstract** — the backend owns trigger policy, retention, event sequencing, and summarization. Reusable request measurement is a separate service, [`ctx.tokenMeter`](../../llm/token-meter/README.md), rather than part of this interface.
+All three operations are **abstract** — the backend owns trigger policy, retention, event sequencing, and summarization. Reusable request measurement is a separate service, [`ctx.tokenMeter`](../../llm/token-meter/README.md), rather than part of this Service Definition.
 
 | Member | Semantics |
 |---|---|
@@ -32,7 +32,7 @@ All three operations are **abstract** — the backend owns trigger policy, reten
 
 ## Tool-pairing boundaries
 
-The interface exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for snapping and validating compaction edges. A safe edge has no unanswered assistant tool call crossing it. Each helper validates that the event sequence is in the current surface and answers from balances cached per cut in surface order.
+The Service Definition exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for snapping and validating compaction edges. A safe edge has no unanswered assistant tool call crossing it. Each helper validates that the event sequence is in the current surface and answers from balances cached per cut in surface order.
 
 The private per-session cache is keyed by `session.surface.replaceGeneration` and the processed surface-entry count. An unchanged generation extends the fold with unseen tail entries only; a log-only append with no new surface entry does no event reads, while a replacement generation rebuilds current membership and balances. Missing event seqs and a `tool/result` without a preceding open call reject as corrupt surface state.
 
@@ -80,7 +80,7 @@ A successful implementation replaces an older surface range with one user-role s
 
 #### Token effect
 
-Zero direct tokens from this interface. A backend trades many retained history tokens for one summary and leaves the recent tail unchanged.
+Zero direct tokens from this Service Definition. A backend trades many retained history tokens for one summary and leaves the recent tail unchanged.
 
 #### KV Cache effect
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index 493d269202..ea66d8bdb0 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -4,19 +4,19 @@
 
 **`CompactService`**（`ctx.compact`）定义压缩做什么，即判定历史记录是否过大，并将较早范围摘要为单个表层节点，但不规定如何实现。
 
-这个包是压缩能力的接口层，因此各项职责均可独立演进，也可独立替换：
+本包承担压缩能力的 Service Definition 角色，因此各角色均可独立演进，也可独立替换：
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-compact`（本包） | 接口：抽象服务 + `compact/*` 事件 + `CompactionResult` + 规范检查点源 + 工具配对边界 helper |
-| `@deepseek-ai/dsh-compact-basic` | 后端：`ctx.tokenMeter` 压力 + token 预算保留 + `llm.stream()` 摘要 |
-| `@deepseek-ai/dsh-command-compact` | 面向用户的 `/compact` 命令，基于 `ctx.compact.compactNow()` 实现 |
+| `@deepseek-ai/dsh-compact`（本包） | Service Definition：抽象服务 + `compact/*` 事件 + `CompactionResult` + 规范检查点源 + 工具配对边界 helper |
+| `@deepseek-ai/dsh-compact-basic` | Service provider：`ctx.tokenMeter` 压力 + token 预算保留 + `llm.stream()` 摘要 |
+| `@deepseek-ai/dsh-command-compact` | Consumer：面向人类的 `/compact` 命令，基于 `ctx.compact.compactNow()` 实现 |
 
-与 bash seam 不同，该接口依赖 `@deepseek-ai/dsh-session` 和 `@deepseek-ai/dsh-llm`。约定的动词基于 `Session` 定义，其输出使用 `ContentBlock` 词汇，因此无法在不指名这些包的情况下表达。这项对「接口只依赖 cordis」指引的偏离是有意的，并记录在 [压缩能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 中。
+与 bash seam 不同，该 Service Definition 依赖 `@deepseek-ai/dsh-session` 和 `@deepseek-ai/dsh-llm`。约定的动词基于 `Session` 定义，其输出使用 `ContentBlock` 词汇，因此无法在不指名这些包的情况下表达。这项对「Service Definition 只依赖 cordis」指引的偏离是有意的，并记录在 [压缩能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 中。
 
 ## 服务 API（`ctx.compact`）
 
-三个操作都是**抽象方法**：触发策略、保留、事件顺序与摘要均属于后端。可复用的请求测量是独立服务 [`ctx.tokenMeter`](../../llm/token-meter/README.md)，而非本接口的一部分。
+三个操作都是**抽象方法**：触发策略、保留、事件顺序与摘要均属于后端。可复用的请求测量是独立服务 [`ctx.tokenMeter`](../../llm/token-meter/README.md)，而非本 Service Definition 的一部分。
 
 | 成员 | 语义 |
 |---|---|
@@ -32,7 +32,7 @@
 
 ## 工具配对边界
 
-该接口导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于对齐和验证压缩边界。安全边界不会被尚未回答的 assistant 工具调用跨越。每个 helper 都会验证给定事件 seq 位于当前表层，并根据按表层顺序缓存的各切分点配对状态返回结果。
+该 Service Definition 导出 `toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`，用于对齐和验证压缩边界。安全边界不会被尚未回答的 assistant 工具调用跨越。每个 helper 都会验证给定事件 seq 位于当前表层，并根据按表层顺序缓存的各切分点配对状态返回结果。
 
 每个会话的私有 cache 以 `session.surface.replaceGeneration` 和已处理表层条目数为 key。generation 未变时，只需将尚未处理的尾部条目纳入累计结果；仅向日志追加、但未新增表层条目时，不会读取事件。replace generation 变化时则会重建当前成员关系与配对状态。事件 seq 缺失以及 `tool/result` 没有对应的先前未闭合调用，均会被视为表层状态损坏并遭拒绝。
 
@@ -80,7 +80,7 @@
 
 #### Token 影响
 
-该接口不会直接产生 token。后端用一份摘要换取多个原本保留的历史 token，并保持近期尾部不变。
+该 Service Definition 不会直接产生 token。后端用一份摘要换取多个原本保留的历史 token，并保持近期尾部不变。
 
 #### KV Cache 影响
 
diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts
index e537639adc..7b0bd25091 100644
--- a/packages/compact/compact/src/index.ts
+++ b/packages/compact/compact/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Compaction service seam (`ctx.compact`): implementations decide when to
+ * Compaction Service Definition (`ctx.compact`): providers decide when to
  * compact and replace a history range with one summary node by subclassing
  * {@link CompactService}. This interface necessarily depends on session and LLM
  * vocabulary; the rationale is in the
diff --git a/packages/compact/compact/tests/compact.spec.ts b/packages/compact/compact/tests/compact.spec.ts
index f063609808..7e6915354f 100644
--- a/packages/compact/compact/tests/compact.spec.ts
+++ b/packages/compact/compact/tests/compact.spec.ts
@@ -13,7 +13,7 @@ import type { ManualCompactAgentContext } from '@deepseek-ai/dsh-compact'
 
 /**
  * A trivial concrete CompactService implementing the abstract contract. The
- * interface package owns no algorithm — these tests exercise the seam itself:
+ * Service Definition package owns no algorithm — these tests exercise its contract:
  * service registration, the abstract method shape, and the `compact/*` event
  * declaration merge.
  */
diff --git a/packages/context/tmux-context/README.i18n.yaml b/packages/context/tmux-context/README.i18n.yaml
index 0e3f1898ad..b315a68fd9 100644
--- a/packages/context/tmux-context/README.i18n.yaml
+++ b/packages/context/tmux-context/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/context/tmux-context/README.md
-README.md: 26eff205b399bfcd20f55e91ef46cadbd70ae604
-README.zh.md: 7f256a829860df3f39e913d003b4e53d09243365
+README.md: 59c452be53b8bb7cb7244a9bb2017749750ce4bf
+README.zh.md: f343c9b25c832cafcb3366209bc2ce39308ad0d5
diff --git a/packages/context/tmux-context/README.md b/packages/context/tmux-context/README.md
index 26eff205b3..59c452be53 100644
--- a/packages/context/tmux-context/README.md
+++ b/packages/context/tmux-context/README.md
@@ -17,7 +17,7 @@ Opt-in durable context naming the tmux session, window, and pane this agent proc
 
 ## How it reads tmux
 
-The plugin prepends an `agent/pre-step` listener that runs only on the first step of each turn. When due, it runs one read-only command through the `ctx.bash` executor seam:
+The plugin prepends an `agent/pre-step` listener that runs only on the first step of each turn. When due, it runs one read-only command through the `ctx.bash` executor service:
 
 ```sh
 [ -n "$TMUX_PANE" ] || exit 1
diff --git a/packages/context/tmux-context/README.zh.md b/packages/context/tmux-context/README.zh.md
index 7f256a8298..f343c9b25c 100644
--- a/packages/context/tmux-context/README.zh.md
+++ b/packages/context/tmux-context/README.zh.md
@@ -17,7 +17,7 @@
 
 ## 如何读取 tmux
 
-插件前置注册一个 `agent/pre-step` 监听器，仅在每轮的第一个 step 运行。当需要注入时，它通过 `ctx.bash` 执行器 seam 运行一条只读命令：
+插件前置注册一个 `agent/pre-step` 监听器，仅在每轮的第一个 step 运行。当需要注入时，它通过 `ctx.bash` 执行器服务运行一条只读命令：
 
 ```sh
 [ -n "$TMUX_PANE" ] || exit 1
diff --git a/packages/context/tmux-context/src/index.ts b/packages/context/tmux-context/src/index.ts
index e79ad89b6b..c489ec0970 100644
--- a/packages/context/tmux-context/src/index.ts
+++ b/packages/context/tmux-context/src/index.ts
@@ -4,7 +4,7 @@
  * and pane this agent process runs in, plus the window's pane-tree layout.
  *
  * The plugin pulls state once per turn, for the first request (`step === 1`), by
- * running one `tmux display-message` through the `ctx.bash` executor seam. It
+ * running one `tmux display-message` through the `ctx.bash` executor service. It
  * confirms this process genuinely runs inside the pane `$TMUX_PANE` names by
  * matching the pane's `#{pane_tty}` against this process's controlling terminal,
  * so a terminal that merely inherited `$TMUX`/`$TMUX_PANE` from a tmux ancestor
@@ -98,7 +98,7 @@ const FIELD_SEP = '\\t'
  * `run()` only promises to resolve for nonzero exits, timeouts, and aborts, so
  * both are contained and reported as a warning.
  *
- * @param bash - the executor seam used to run the read-only tmux/ps commands.
+ * @param bash - The executor service used to run the read-only tmux/ps commands.
  * @param logger - receives a warning when the executor rejects the query.
  * @param processId - this agent process's pid, whose controlling tty must match the pane.
  * @param signal - abort signal forwarded to the executor.
diff --git a/packages/core/README.i18n.yaml b/packages/core/README.i18n.yaml
index f3ab9dcc56..4d9ab302d8 100644
--- a/packages/core/README.i18n.yaml
+++ b/packages/core/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/core/README.md
-README.md: 19aed9abafa8e4531d2ee31ff0442003328a9ef6
-README.zh.md: 73ed1f500799cb235a8835ffb0317370f9a0a7e6
+README.md: 8349371ab565f2e9e735cd959026936c7ec44081
+README.zh.md: e19c446584cfac75cb50833fa01586688b9c7c92
diff --git a/packages/core/README.md b/packages/core/README.md
index 19aed9abaf..8349371ab5 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -14,7 +14,7 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, deploy
 | [`agent-default-model/`](agent-default-model/README.md) | Default model selection shared by Agent front doors | `ctx.agentDefaultModel` |
 | [`agent-loop/`](agent-loop/README.md) | Default concrete agent driver | `ctx.agentLoop` |
 
-`scope` supplies the shared scoping primitive. `agent` owns the public seam, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable. `agent-default-model` owns the deployment selection an Agent front door uses only when a session has no selection of its own.
+`scope` supplies the shared scoping primitive. `agent` owns the public contract, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable. `agent-default-model` owns the deployment selection an Agent front door uses only when a session has no selection of its own.
 
 Runnable compositions belong to [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md); this group owns only the swappable spine pieces.
 
diff --git a/packages/core/README.zh.md b/packages/core/README.zh.md
index 73ed1f5007..e19c446584 100644
--- a/packages/core/README.zh.md
+++ b/packages/core/README.zh.md
@@ -14,7 +14,7 @@
 | [`agent-default-model/`](agent-default-model/README.md) | 各 Agent 入口共享的默认模型选择 | `ctx.agentDefaultModel` |
 | [`agent-loop/`](agent-loop/README.md) | 默认具体 agent 驱动器 | `ctx.agentLoop` |
 
-`scope` 提供共享作用域原语。`agent` 负责公开 seam，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。`agent-default-model` 负责部署选择，Agent 入口仅在会话自身没有选择时使用它。
+`scope` 提供共享作用域原语。`agent` 负责公开约定，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。`agent-default-model` 负责部署选择，Agent 入口仅在会话自身没有选择时使用它。
 
 可运行组合属于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)；该分组只负责可替换的主干组件。
 
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index 9eb0eb4921..60ceaa7572 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/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/core/agent-loop/README.md
-README.md: 608a21a2f00545bbc03f675ee2f76034624bb10d
-README.zh.md: fc23c6cb0645c88f2e081a5dbb81dface8c553d6
+README.md: 6092363fae2853d6c5d92aaf8cd01e41e18e0b52
+README.zh.md: b65b5334d735a1e0b51fa517ce41c0c953f87cf7
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 608a21a2f0..6092363fae 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 THE concrete agent plugin and loop driver. Its package-internal implementation satisfies the `Agent` interface and drives the session/turn/step lifecycle.
 
-This is the only package in the harness that contains concrete loop logic. Everything else is an abstract service or a plugin against extension seams — new behavior goes into plugins, not here.
+This is the only package in the harness that contains concrete loop logic. Everything else is an abstract service or a plugin against extension points — new behavior goes into plugins, not here.
 
 ## Service: `AgentLoop` (ctx key: `agentLoop`)
 
@@ -18,7 +18,7 @@ Each agent and its session share one caller-chosen `SessionId`, assumed globally
 
 - `ctx.agentLoop.create(id: SessionId, options?: AgentOptions, meta?: { cwd?: string }): Agent` — synchronous no-setup create under the exact shared agent/session id, disposed with the calling fiber. Declarative config treats `agents[].id` as a stable label and normally mints `${label}-session-<uuid>` before calling this boundary. An app may instead supply a stable exact `sessionId`: first use creates it, while a remount with persistence already present resumes its materialized history. `resumeSessionId` requires and loads an existing persisted id and is mutually exclusive with `sessionId`. This keeps default fresh restarts collision-free without retaining a second live routing identity.
 
-`AgentLoop` also implements the `AgentFactory` seam and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents` (the interface):
+`AgentLoop` also implements the `AgentFactory` contract and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents`:
 
 - `ctx.agents.create({ sessionId, meta?, seed?, agentOptions?, setup?, signal? }): Promise<AgentHandle>` — programmatic create under the caller-supplied shared id. It awaits the unpublished setup transaction before returning; `meta` carries cwd/lineage/seed-boundary metadata and `seed` reconstructs a forked child prefix after the session boundary validates and snapshots the durable values. `signal` applies only until this promise settles. The resolved [`AgentHandle`](../agent/README.md) owns exact teardown.
 - `ctx.agents.resume({ resumeSessionId, agentOptions?, setup?, signal? }): Promise<AgentHandle>` — load a persisted session via `ctx.sessionPersistence` ([session persistence](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)), register the agent under that same id, reconstruct its history, then await setup against a fresh unpublished agent scope before rollback-covered publication. Turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; `resume` rejects with a clear error when persistence is absent). `signal` is creation-only. Returns an `AgentHandle`.
@@ -131,4 +131,4 @@ Append-only; each synthetic result follows the reusable request prefix and does
 - **Classification is unary** — calls whose safety depends on comparing siblings or resources must remain exclusive ([rationale](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)).
 - **Config labels are fresh by default** — omitting `sessionId` creates a fresh `${id}-session-<uuid>` on every startup; exact resume-or-create behavior requires an explicit stable `sessionId`, while `resumeSessionId` requires existing persisted history.
 - **Config agents have no per-agent persona field or setup hook** — they use the deployment persona; scoped persona/tool composition is available only through the programmatic `ctx.agents.create()` / `resume()` factory options.
-- **No built-in turn budget** — tool calls or steering continue the current turn; a policy that bounds runaway turns must cancel from an existing lifecycle seam such as `agent/turn-stopping`.
+- **No built-in turn budget** — tool calls or steering continue the current turn; a policy that bounds runaway turns must cancel from an existing lifecycle extension point such as `agent/turn-stopping`.
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index fc23c6cb06..b65b5334d7 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -4,7 +4,7 @@
 
 唯一的具体 agent（智能体）插件与循环驱动器。其包内部实现满足 `Agent` 接口，并驱动会话／轮次／步骤生命周期。
 
-这是 harness 中唯一包含具体循环逻辑的包。其他所有内容要么是抽象服务，要么是针对扩展 seam 的插件：新行为应放入插件，而不是这里。
+这是 harness 中唯一包含具体循环逻辑的包。其他所有内容要么是抽象服务，要么是针对扩展点的插件：新行为应放入插件，而不是这里。
 
 ## 服务：`AgentLoop`（ctx 键：`agentLoop`）
 
@@ -18,7 +18,7 @@
 
 - `ctx.agentLoop.create(id: SessionId, options?: AgentOptions, meta?: { cwd?: string }): Agent`：在确切共享的 agent／会话 id 下同步创建，不运行 setup，并随调用 fiber dispose。声明式配置把 `agents[].id` 视为稳定 label，通常会先生成 `${label}-session-<uuid>`，再调用此边界。应用也可以提供稳定且确切的 `sessionId`：首次使用时创建；重新挂载且持久化内容已存在时，则恢复已经实体化的历史。`resumeSessionId` 要求并加载现有的持久化 id，且与 `sessionId` 互斥。这样，默认的全新重启不会冲突，也无需保留第二个实时路由身份。
 
-`AgentLoop` 还实现 `AgentFactory` seam，并通过 `ctx.agents.setFactory(this)` 注册自身，因此插件会通过接口 `ctx.agents` 创建／恢复 agent：
+`AgentLoop` 还实现 `AgentFactory` 约定，并通过 `ctx.agents.setFactory(this)` 注册自身，因此插件会通过 `ctx.agents` 创建／恢复 agent：
 
 - `ctx.agents.create({ sessionId, meta?, seed?, agentOptions?, setup?, signal? }): Promise<AgentHandle>`：使用调用方提供的共享 id 以编程方式创建。它会等待尚未发布的 setup 事务，然后才返回；`meta` 携带 cwd／谱系／seed 边界元数据，`seed` 则在会话边界验证并快照持久值后，重建 fork 子级的前缀。`signal` 只在此 Promise 结算前生效。解析得到的 [`AgentHandle`](../agent/README.md) 拥有确切的 teardown。
 - `ctx.agents.resume({ resumeSessionId, agentOptions?, setup?, signal? }): Promise<AgentHandle>`：通过 `ctx.sessionPersistence` 加载持久化会话（参见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），使用同一 id 注册 agent，重建历史，然后针对全新且尚未发布的 agent 作用域等待 setup，再执行受回滚保护的发布。轮次编号和派生历史从已加载日志继续。此操作要求存在会话持久化后端（不会硬注入，因此非持久化 demo 仍能工作；缺少持久化时，`resume` 会以明确错误拒绝）。`signal` 仅用于创建。返回 `AgentHandle`。
@@ -131,4 +131,4 @@ interface Config {
 - **分类是一元的**：安全性取决于比较同级调用或资源的调用必须保持独占（参见[设计原理](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)）。
 - **配置 label 默认每次新建**：省略 `sessionId` 会在每次启动时创建全新的 `${id}-session-<uuid>`；确切的恢复或创建行为要求显式提供稳定的 `sessionId`，而 `resumeSessionId` 要求已有持久化历史。
 - **配置 agent 没有逐 agent persona 字段或 setup 钩子**：它们使用部署 persona；只有编程式 `ctx.agents.create()` / `resume()` 工厂选项支持带作用域的 persona／工具组合。
-- **没有内置轮次预算**：工具调用或 steering 会让当前轮次继续；限制失控轮次的策略必须从既有生命周期 seam（如 `agent/turn-stopping`）执行取消。
+- **没有内置轮次预算**：工具调用或 steering 会让当前轮次继续；限制失控轮次的策略必须从既有生命周期扩展点（如 `agent/turn-stopping`）执行取消。
diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts
index a589f3c131..e7c840e296 100644
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -524,7 +524,7 @@ export class AgentLoop extends Service implements AgentFactory {
           assertLive()
           // A synchronous announce/session-start listener may have started
           // teardown; the machine is already live (delivery works from the
-          // session-start seam), so only the liveness recheck is owed.
+          // session-start extension point), so only the liveness recheck is owed.
           emitAgentEvent(loopCtx, agent, 'agent/session-start', { source })
           assertLive()
           return { agent, dispose }
diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts
index 79bc65a105..6fb77d141c 100644
--- a/packages/core/agent-loop/tests/cancel.spec.ts
+++ b/packages/core/agent-loop/tests/cancel.spec.ts
@@ -485,7 +485,7 @@ describe('Agent.cancel()', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // A step/start session-event listener fires AFTER step/start is appended
-    // (and after the pre-step seam), so cancelling there lands in the SECOND
+    // (and after the pre-step extension point), so cancelling there lands in the SECOND
     // cancel check (the one that must closeStep() to balance the already-open
     // step) — distinct from a turn-start cancel, caught before the step opens.
     let streamed = false
diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts
index a26f463b0d..646c6d41fa 100644
--- a/packages/core/agent-loop/tests/interception.spec.ts
+++ b/packages/core/agent-loop/tests/interception.spec.ts
@@ -19,7 +19,7 @@ import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
 /**
- * The interception seams introduced by the hooks taxonomy: `agent/pre-step`,
+ * The interception points introduced by the hooks taxonomy: `agent/pre-step`,
  * `agent/session-start`, `agent/turn-stopping`, and the
  * `tools/pre-execute` / `tools/post-execute`
  * split with `additionalContexts` buffering. These verify the canonical event
diff --git a/packages/core/agent/README.i18n.yaml b/packages/core/agent/README.i18n.yaml
index d1d8e5401d..477c3a5cb6 100644
--- a/packages/core/agent/README.i18n.yaml
+++ b/packages/core/agent/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/core/agent/README.md
-README.md: 73d32d09d880b0d27b80a7aeecc1eb75bf03f8dd
-README.zh.md: e140d76c940ac605ddc6dedad8a9f2f16457fde0
+README.md: 0fb65b94a3b311aa9f0df09d39dd937cba4cc7b4
+README.zh.md: 44f67483343a98c280317793ece544bd0b984596
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index 73d32d09d8..0fb65b94a3 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -34,7 +34,7 @@ The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-
 
 The scope carries the `Agent` itself and is process-local. Ambient presence is neither liveness proof nor authorization; explicit Agent fields remain authoritative at service, worker, process, persistence, and wire boundaries. Teardown rejects new boundaries, lets injected dependents and returned-Promise boundaries drain, then disables the underlying `AsyncLocalStorage`; unreturned work remains owned by the subsystem that detached it. If a boundary's inherited async chain starts an owning Cordis fiber's unload, that nested boundary chain is released from the drain so the unload cannot wait on itself; its continuations observe the disposed service after teardown. The [initiator-scope decision](../../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md) owns the detailed boundary and teardown contract.
 
-#### Factory seam (creation)
+#### Factory API (creation)
 
 Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-agent-loop`), registered via `setFactory`. This keeps creation on the `dsh-agent` interface so consumers (UI, the ACP bridge) program against `ctx.agents` without depending on the concrete loop package. The registry canonicalizes an already traced Service to its concrete target and re-traces each call through the caller's context; this avoids nested Cordis shadows while passing an explicit caller-bound `ownerCtx` to plain factories.
 
@@ -50,7 +50,7 @@ Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-age
 
 The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist. Setup is trusted composition-only code; the immediately following non-vetoing `agent/session-start` notification is the first supported startup injection point. `agent/disposed` always means the exact agent has left the registry. AgentLoop emits it after its driver is quiescent, while ordered teardown may still be detaching the session and unwinding the scope; custom agents registered directly own any stronger driver-ordering contract themselves.
 
-Most interception points are cooperative waterfalls. `agent/pre-step` receives a payload carrying the subject `agent`, the exclusive claimed `UserMessage[]`, and the proposed `turn`, `step`, and cancellation `signal`; its batch may be empty when tools already require another request. Agent-scoped turn seams carry their explicit `AbortSignal` in the payload; the remaining turn-scoped seams receive it through their request value. Listeners may cooperate with a signal but must not retain it as authority over another turn. `agent/request-error` is the failed-model-request recovery waterfall: it receives request coordinates, normalized failure facts, the serving registration's retry policy when available, and the signal. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery. `agent/turn-stopping` runs before an otherwise completed turn closes. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement.
+Most interception points are cooperative waterfalls. `agent/pre-step` receives a payload carrying the subject `agent`, the exclusive claimed `UserMessage[]`, and the proposed `turn`, `step`, and cancellation `signal`; its batch may be empty when tools already require another request. Agent-scoped turn extension points carry their explicit `AbortSignal` in the payload; the remaining turn-scoped extension points receive it through their request value. Listeners may cooperate with a signal but must not retain it as authority over another turn. `agent/request-error` is the failed-model-request recovery waterfall: it receives request coordinates, normalized failure facts, the serving registration's retry policy when available, and the signal. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery. `agent/turn-stopping` runs before an otherwise completed turn closes. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement.
 
 `PreStepDecision` is either `{ kind: 'reject' }` or `{ kind: 'enter', messages }`. The enter branch is the complete identified, frozen batch for the proposed step. A listener that wraps downstream entry preserves that batch unless it intentionally replaces it; additions follow the waterfall's natural return order. Claiming already removed the offered messages from the inbox, so rejection does not retain them. Messages inserted after the claim remain pending for a later boundary.
 
@@ -76,7 +76,7 @@ The handle every plugin programs against:
 
 - Agent creation: `AgentLoop.create()` is the concrete config-path implementation (in `dsh-agent-loop`), while programmatic consumers create/resume owned agents through `ctx.agents.create()` / `ctx.agents.resume()`. Replace the loop by implementing `Agent` and registering via `ctx.agents.register()`.
 - Event listeners: all `agent/*` events are declared here — no dependency on the loop package needed.
-- Subagent delegation is not an `Agent` method; providers create or drive ordinary handles through the factory seam, so delegation transports stay outside the core agent interface.
+- Subagent delegation is not an `Agent` method; providers create or drive ordinary handles through the factory API, so delegation transports stay outside the core agent interface.
 
 ## Model Experience
 
diff --git a/packages/core/agent/README.zh.md b/packages/core/agent/README.zh.md
index e140d76c94..44f6748334 100644
--- a/packages/core/agent/README.zh.md
+++ b/packages/core/agent/README.zh.md
@@ -12,7 +12,7 @@ Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事
 
 ### 公开 API
 
-带作用域的注册接口：`Agent.ctx` 是 agent 的作用域上下文（`dsh-scope`，键 = 该 agent）。通过它注册工具／段／变量／监听器，只对该 agent 生效，并在 dispose（资源释放）时全部撤销。`agentEvents(ctx, agent)` 是普通 agent 主体操作的融合分发器（一次完成载体 + 注入主体）；其通知 mode 会调用每个监听器，并同时收容同步抛出和返回 Promise 的拒绝。注册表生命周期对复用一个稳定路由载体。`assembleContextFor(agent)` 构建按 agent 的组装上下文（同时包含 `agent` + `scope`）。`installModelSelection(agentCtx, selection)` 在提示词组装期间快照可变的提供方／模型／推理（reasoning）强度选择，将其中的提供方和模型应用到提示词变量，并将完整选择应用到一个步骤的请求路由；如果没有选定推理强度，则会清除继承的推理强度，使适配器／提供方默认值生效。`CreateAgentOptions.setup(agentCtx)` 和 `ResumeAgentOptions.setup(agentCtx)` 在新建或恢复的 agent 尚未发布时，组合其带作用域的世界。Setup 是受信任、仅用于组合的同进程代码：只有创建完成后才能驱动 agent。
+带作用域的注册接口：`Agent.ctx` 是 agent 的作用域上下文（`dsh-scope`，键 = 该 agent）。通过它注册工具／段／变量／监听器，只对该 agent 生效，并在 dispose（资源释放）时全部撤销。`agentEvents(ctx, agent)` 是普通 agent 主体操作的融合分发器（一次完成载体 + 注入主体）；其通知 mode 会调用每个监听器，并同时收容同步抛出和返回 Promise 的拒绝。注册表生命周期对复用一个稳定路由载体。`assembleContextFor(agent)` 构建按 agent 的组装上下文（同时包含 `agent` + `scope`）。`installAgentLlmTarget(agentCtx, target)` 在提示词组装期间快照可变的提供方／模型／推理（reasoning）强度选择，将路由应用到提示词变量，并将完整目标应用到一个步骤的请求路由；如果没有选定推理强度，则会清除继承的推理强度，使该目标使用适配器／提供方默认值。`CreateAgentOptions.setup(agentCtx)` 和 `ResumeAgentOptions.setup(agentCtx)` 在新建或恢复的 agent 尚未发布时，组合其带作用域的世界。Setup 是受信任、仅用于组合的同进程代码：只有创建完成后才能驱动 agent。
 
 `AgentOptions` 提供初始的提供方／模型路由，以及可选的正数 `maxTokens` 输出上限。具体循环会解析确切模型的适配器默认值，把生效上限记录到请求 header，并应用到每次对话模型请求；显式 Agent 选项优先，省略时由适配器或提供方路由默认值控制。
 
@@ -34,7 +34,7 @@ Agent 接口、注册表、进程本地发起方作用域，以及 `agent/*` 事
 
 该作用域携带 `Agent` 本身，并且只在进程内有效。环境中的身份既不是存活证明，也不是授权；在服务、worker、进程、持久化和 wire 边界，显式 Agent 字段仍是权威来源。Teardown 会拒绝新边界，允许注入的依赖方和返回 Promise 的边界 drain，然后禁用底层 `AsyncLocalStorage`；未返回的工作仍归将其分离的子系统所有。如果某个边界继承的异步链开始卸载一个拥有它的 Cordis fiber，该嵌套边界链会从 drain 中释放，使卸载不会等待自身；其 continuation 会在 teardown 后观察到已 dispose 的服务。详细边界与 teardown 约定由[发起方作用域决策](../../../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)拥有。
 
-#### 工厂 seam（创建）
+#### 工厂 API（创建）
 
 Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，并通过 `setFactory` 注册。这样，创建功能留在 `dsh-agent` 接口上，消费方（UI、ACP（Agent Client Protocol）桥接层）可以面向 `ctx.agents` 编程，而不依赖具体循环包。注册表会把已经 traced 的 Service 规范化为具体目标，并通过调用方上下文重新 trace 每次调用；这既避免嵌套 Cordis shadow，也会把显式、绑定调用方的 `ownerCtx` 传给普通工厂。
 
@@ -50,7 +50,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
 
 生命周期边有两个重要的本地注意事项。`agent/created` 在作用域 setup 之后、会话与 agent 注册表条目都存在之后运行。Setup 是受信任、仅用于组合的代码；紧随其后且不可 veto 的 `agent/session-start` 通知是第一个受支持的启动注入点。`agent/disposed` 始终表示确切 agent 已离开注册表。AgentLoop 在其驱动器完全停稳后发出该事件，而有序 teardown 此时可能仍在分离会话并撤销作用域；直接注册的自定义 agent 自行拥有任何更强的驱动器顺序约定。
 
-大多数拦截点都是协作式 waterfall（瀑布式事件）。`agent/pre-step` 接收一个 payload，携带主体 `agent`、独占的已领取 `UserMessage[]` 以及拟进入的 `turn`、`step` 与取消 `signal`；当工具已经要求继续请求时，该批次可以为空。agent 作用域轮次 seam 在 payload 中携带显式 `AbortSignal`；其余轮次作用域 seam 通过其请求值接收它。监听器可以配合信号，但不得将它保留为控制另一轮次的权限。`agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域运行时设计 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
+大多数拦截点都是协作式 waterfall（瀑布式事件）。`agent/pre-step` 接收一个 payload，携带主体 `agent`、独占的已领取 `UserMessage[]` 以及拟进入的 `turn`、`step` 与取消 `signal`；当工具已经要求继续请求时，该批次可以为空。agent 作用域轮次扩展点在 payload 中携带显式 `AbortSignal`；其余轮次作用域扩展点通过其请求值接收它。监听器可以配合信号，但不得将它保留为控制另一轮次的权限。`agent/request-error` 是失败模型请求的恢复 waterfall：它接收请求坐标、规范化失败事实、可用时提供服务的注册项重试策略以及信号。拥有恢复权的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`。`agent/turn-stopping` 在本可完成的轮次关闭前运行。信号生命周期由[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)拥有；作用域分发与终止结算由 [agent 作用域 runtime 设计 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way)拥有。
 
 `PreStepDecision` 要么是 `{ kind: 'reject' }`，要么是 `{ kind: 'enter', messages }`。enter 分支是拟进入步骤的完整、带标识且冻结的批次。包装下游 enter 的监听器会保留该批次，除非有意替换它；新增消息遵循 waterfall 的自然返回顺序。领取操作已经把候选消息从 inbox 删除，因此 reject 不会保留它们；领取后插入的消息仍等待后续边界。
 
@@ -76,7 +76,7 @@ inbox 的实时通知刻意采用逐消息的最小载荷：`agent/inbox/inserte
 
 - Agent 创建：`AgentLoop.create()` 是具体配置路径实现（位于 `dsh-agent-loop`），程序化消费方则通过 `ctx.agents.create()`/`ctx.agents.resume()` 创建或恢复有所有权的 agent。替换循环时，应实现 `Agent` 并通过 `ctx.agents.register()` 注册。
 - 事件监听器：全部 `agent/*` 事件都在此处声明，不需要依赖循环包。
-- subagent 委派不是 `Agent` 方法；提供方通过工厂 seam 创建或驱动普通 handle，因此委派传输留在核心 agent 接口之外。
+- subagent 委派不是 `Agent` 方法；提供方通过工厂 API 创建或驱动普通 handle，因此委派传输留在核心 agent 接口之外。
 
 ## 模型体验
 
diff --git a/packages/core/agent/src/inbox.ts b/packages/core/agent/src/inbox.ts
index 4448847cd8..d457277035 100644
--- a/packages/core/agent/src/inbox.ts
+++ b/packages/core/agent/src/inbox.ts
@@ -68,7 +68,7 @@ export class Inbox {
    * @param target - whether this boundary also consumes one queued turn.
    * @param turn - turn that will own the claimed batch.
    * @returns next-step input followed by the queued turn, when requested.
-   * @internal - the agent loop's step-boundary operation, not a plugin seam.
+   * @internal - The agent loop's step-boundary operation, not a plugin extension point.
    */
   claim(target: InboxTarget, turn: number): UserMessage[] {
     const claimed = this.mutate('next-step', 0, this.nextStep.length, [], false)
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index 44c55d80a2..bedfc819dc 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -312,7 +312,7 @@ export class AgentRegistry extends Service {
    * Read the initiating Agent and fail when no initiator boundary is active.
    * Use this for private helpers contractually below a driver, or for a
    * deployment-owned outbound request whose contract forbids agentless calls.
-   * Generic or direct-call seams use optional lookup or explicit request fields.
+   * Generic or direct-call paths use optional lookup or explicit request fields.
    * @returns the inherited Agent.
    * @throws when no initiator is active or this service instance has been disposed.
    */
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index ba9afa50d7..d21f25cdc7 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -147,7 +147,7 @@ declare module 'cordis' {
     // ---- lifecycle (emit) ----
     /**
      * A fully configured agent and live session were published. Setup is
-     * composition-only; `agent/session-start` is the first startup-driving seam.
+     * composition-only; `agent/session-start` is the first startup-driving extension point.
      * Synchronous listener failure vetoes publication, while returned-promise
      * rejection is reported. Detach requested during dispatch waits until every
      * creation listener has observed the stable entry.
@@ -215,7 +215,7 @@ declare module 'cordis' {
      */
     'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
 
-    // ---- the machine's extension seams ----
+    // ---- the machine's extension points ----
     /**
      * Reject a proposed step or replace the messages that enter it. Calling
      * `next()` preserves the current messages.
@@ -232,7 +232,7 @@ declare module 'cordis' {
      * Replace the frozen call configuration. `await next()` yields the config
      * the machine would use (agent options on the first request, the logged
      * header afterwards); return a replacement to switch. Model-visible
-     * content must use logged channels; this seam cannot mutate messages.
+     * content must use logged channels; this waterfall cannot mutate messages.
      * @param payload.agent - the agent making the model call.
      * @param payload.turn - the open turn number.
      * @param payload.step - the step whose request this is.
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index 71cb01a34d..c5ed6a2c98 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/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/core/session/README.md
-README.md: 09e027c82fe1a81d97b3e70d95231ccc553e3ed1
-README.zh.md: 3fdd1e68b18f5ce4b3846ca0d2376b968a0754e3
+README.md: db477d94037d3463870fc8e66ea35d5e607fb6fe
+README.zh.md: 1ce1e823a7e0fdbcf7b6898764a89c52b74adf6a
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index 09e027c82f..db477d9403 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -26,7 +26,7 @@ Use the split lifecycle only when teardown must be ordered with another resource
 - `enter(session)` performs the collision check, publishes without announcing, and returns an entry-bound idempotent detach. Concurrent same-id preparations are allowed, but only one entry succeeds; a stale detach cannot remove its replacement.
 - `announce(session)` emits the single creation edge and rejects repeat or reentrant announcements. Detach during that dispatch is deferred and later emits the paired disposal edge; an unannounced entry emits neither lifecycle edge.
 
-`dsh-agent-loop` uses this split so final loop flush precedes session detach; see the [ownership Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md).
+`dsh-agent-loop` uses this split so final loop flush precedes session detach; see the [ownership Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md).
 
 ### Live service events
 
@@ -87,8 +87,8 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 
 ### Extension points
 
-- Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
-- Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers and assistant messages require provider/model. Persistence owns read compatibility before constructing this current-format seed. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
+- Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata contract (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
+- Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers require provider/model, and assistant messages require provider/model provenance. Persistence owns read compatibility before constructing this current-format seed. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
 - Compaction: `dsh-compact-basic` appends a `user/message` replacement for summary checkpoints, while `dsh-compact-tool-result-prune` appends a content-only `tool/result` replacement. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns ordered surface membership, replacement validation, and `replaceGeneration`.
 
 ## Model Experience
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index 3fdd1e68b1..1ce1e823a7 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -26,7 +26,7 @@
 - `enter(session)` 执行冲突检查，在不通知的情况下发布，并返回一个绑定到该条目的幂等脱离函数。允许并发准备相同 id，但只有一个条目能够成功进入；陈旧的脱离函数无法移除其替代项。
 - `announce(session)` 发出唯一一次创建边，并拒绝重复或重入通知。该次分发期间请求的脱离操作会延后，之后再发出成对的释放边；未通知的条目不会发出任何生命周期边。
 
-`dsh-agent-loop` 使用这一拆分，以保证循环的最终刷新先于会话脱离；详见[所有权 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md)。
+`dsh-agent-loop` 使用这一拆分，以保证循环的最终刷新先于会话脱离；详见[所有权 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-contracts.md)。
 
 ### 实时服务事件
 
@@ -87,8 +87,8 @@
 
 ### 扩展点
 
-- 持久化插件：订阅 `session/event`（延后写入），并在 `session/flush`（受等待）及 fiber dispose（资源释放）时排空。持久后端读取日志并重新加载到实时会话；这类后端会把元数据 seam（`SessionHeader`、`session.header`）与日志一同存储。
-- 回放／fork：`create(id, { seed })` 校验并冻结连续的当前格式日志，再重建 surface；请求头和 assistant 消息都必须包含提供方／模型。持久化层在构造该当前格式 seed 前负责读取兼容性处理。`fork(source, boundary?, childSessionId?)` 选择已完成轮次前缀并记录谱系。
+- 持久化插件：订阅 `session/event`（延后写入），并在 `session/flush`（受等待）及 fiber dispose（资源释放）时排空。持久后端读取日志并重新加载到实时会话；这类后端会把元数据约定（`SessionHeader`、`session.header`）与日志一同存储。
+- 回放／fork：`create(id, { seed })` 校验并冻结连续的当前格式日志，再重建 surface；请求头必须包含提供方／模型，assistant 消息必须包含提供方／模型溯源信息。持久化层在构造该当前格式 seed 前负责读取兼容性处理。`fork(source, boundary?, childSessionId?)` 选择已完成轮次前缀并记录谱系。
 - 压缩：`dsh-compact-basic` 为摘要检查点追加一个替换用 `user/message`，而 `dsh-compact-tool-result-prune` 追加仅修改内容的 `tool/result` 替换。工具配对边界策略及其缓存归 [`dsh-compact` seam](../../compact/compact/README.md) 所有；此包拥有有序 surface 成员关系、替换校验与 `replaceGeneration`。
 
 ## 模型体验
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index 1c1d2a3023..2e9bf49271 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -915,7 +915,7 @@ export class SessionStore extends Service {
    * another create) between them, so a stale prepared session must NOT overwrite
    * a live store entry of the same id — its detach disposer would later delete
    * the REAL session. The {@link create} convenience and the agent factory call
-   * the two back-to-back so they never trip this, but the public seam cannot
+   * the two back-to-back so they never trip this, but the public API cannot
    * assume that.
    *
    * @param session - a {@link prepare}d session not yet in the store.
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index 57641e4618..7d4e8f07bb 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/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/core/system-prompt/README.md
-README.md: e98c45a8829a945500ef5282d84e1904b31c68bf
-README.zh.md: 5827ae27706505bde86a4ee0d86542a7a2ff63d9
+README.md: 13b05bfcd19212ade42f22ece455871d022e6260
+README.zh.md: 0f9e7a2358134018975db1bc3c6b7206a274b3ec
diff --git a/packages/core/system-prompt/README.md b/packages/core/system-prompt/README.md
index e98c45a882..13b05bfcd1 100644
--- a/packages/core/system-prompt/README.md
+++ b/packages/core/system-prompt/README.md
@@ -19,7 +19,7 @@ System prompt assembly registry. Plugins contribute ordered sections, tool schem
 - `ctx.systemPrompt.section(section: PromptSection): () => void` Contribute a section. The layer is the calling context's scope: `agent.ctx` contributes to that agent alone, shadowing a same-named global section there. Duplicate names within one layer and non-finite orders throw. Disposed with the calling fiber.
 - `ctx.systemPrompt.tools(provider: (context: AssembleContext) => ToolProviderResult): () => void` Contribute tool schemas, evaluated at each assembly with that assembly's context. `ToolProviderResult` = `{ schemas, knownNames? }`: `schemas` is the post-restriction visible set; `knownNames` is the pre-restriction universe used by `toolOrder`. A provider must not return a schema named `TOOL_ORDER_REST`. Scoped providers are consulted only for their scope's assemblies. Disposed with the calling fiber.
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void` Contribute a prompt variable, referenced from section text as `{{name}}`. Scoped variables shadow a same-named global for that agent. Duplicate-in-layer or unreferenceable names throw; `undefined` means "no value for this assembly". Disposed with the calling fiber.
-- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller: the global layer merged with `context.scope`'s layer, with tool schemas detached before the transform seam. Runs through the scope-filtered `system-prompt/assemble` waterfall and returns its authoritative result. An optional `context.signal` explicitly controls this assembly request; providers and listeners may cooperate with it but must not retain it for another turn. Rejects when a configured `toolOrder` names a tool outside the providers' `knownNames` universe, or when a provider returns the reserved rest-entry name.
+- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller: the global layer merged with `context.scope`'s layer, with tool schemas detached before the transform waterfall. Runs through the scope-filtered `system-prompt/assemble` waterfall and returns its authoritative result. An optional `context.signal` explicitly controls this assembly request; providers and listeners may cooperate with it but must not retain it for another turn. Rejects when a configured `toolOrder` names a tool outside the providers' `knownNames` universe, or when a provider returns the reserved rest-entry name.
 
 ### Live events
 
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index 5827ae2770..0f9e7a2358 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -19,7 +19,7 @@
 - `ctx.systemPrompt.section(section: PromptSection): () => void`：贡献一个段。层由调用上下文的作用域决定：`agent.ctx` 只为该 agent 贡献，并在该处遮蔽同名全局段。同一层中的重复名称和非有限顺序会抛出。随调用 fiber 一并 dispose（资源释放）。
 - `ctx.systemPrompt.tools(provider: (context: AssembleContext) => ToolProviderResult): () => void`：贡献工具 schema；每次组装时使用该次组装的上下文求值。`ToolProviderResult` = `{ schemas, knownNames? }`：`schemas` 是限制后的可见集合；`knownNames` 是限制前由 `toolOrder` 使用的全集。提供方不得返回名为 `TOOL_ORDER_REST` 的 schema。带作用域提供方只在其作用域的组装中查询。随调用 fiber 一并 dispose。
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void`：贡献提示词变量，在段文本中以 `{{name}}` 引用。带作用域变量会为该 agent 遮蔽同名全局变量。同层重复或无法引用的名称会抛出；`undefined` 表示「本次组装没有值」。随调用 fiber 一并 dispose。
-- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>`：为一个调用方组装提示词：将全局层与 `context.scope` 的层合并，并在变换 seam 前分离工具 schema。它经过按作用域筛选的 `system-prompt/assemble` waterfall，并返回其权威结果。可选的 `context.signal` 显式控制本次组装请求；提供方与监听器可以配合该信号，但不得将它保留给另一轮次。当已配置的 `toolOrder` 指名提供方 `knownNames` 全集以外的工具，或提供方返回保留的其余项名称时，调用会被拒绝。
+- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>`：为一个调用方组装提示词：将全局层与 `context.scope` 的层合并，并在变换 waterfall 前分离工具 schema。它经过按作用域筛选的 `system-prompt/assemble` waterfall，并返回其权威结果。可选的 `context.signal` 显式控制本次组装请求；提供方与监听器可以配合该信号，但不得将它保留给另一轮次。当已配置的 `toolOrder` 指名提供方 `knownNames` 全集以外的工具，或提供方返回保留的其余项名称时，调用会被拒绝。
 
 <a id="live-events"></a>
 
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index 80c185d9b3..9d9ed71d8d 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/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/core/tools/README.md
-README.md: 73c18552baa4b8b68c3d34c2d928d479548180ba
-README.zh.md: 9812fd50b2500b6393c9328ea1c366eb04963e74
+README.md: b1de96293f8ec823ec52d6142a46de877f7fc5e6
+README.zh.md: fa42f7c02a09579bd7b1c995246696d8808889de
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index 73c18552ba..b1de96293f 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -186,7 +186,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **Concurrency policy is not an event seam** — `executionMode()` reads the resolved tool definition directly; plugins can only declare a classifier on definitions they own.
+- **Concurrency policy is not an event gate** — `executionMode()` reads the resolved tool definition directly; plugins can only declare a classifier on definitions they own.
 - **`tools/pre-execute` deliberately cannot rewrite `exec.arguments`** — logged and rendered args would desync from what ran; the rewrite design is [a proposed Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md).
 - **Caller-defined subagent and workflow structured outputs remain object-rooted** — this is a consumer-level guard; the shared schema vocabulary and tool outputs support every JSON root.
 - **`timeoutMs` on a definition is declarative only** — the registry never enforces deadlines; enforcement requires the `@deepseek-ai/dsh-timeout-policy` wrapper.
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 9812fd50b2..fa42f7c02a 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -186,7 +186,7 @@ The available tools:
 
 ## 已知限制与暂缓事项
 
-- **并发策略不是事件 seam**：`executionMode()` 直接读取已解析的工具定义；插件只能在自身拥有的定义上声明分类器。
+- **并发策略不是事件门禁**：`executionMode()` 直接读取已解析的工具定义；插件只能在自身拥有的定义上声明分类器。
 - **`tools/pre-execute` 有意不允许改写 `exec.arguments`**：否则日志记录和呈现的参数会与实际运行内容失去同步；改写设计记录在[拟议的 Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md)中。
 - **调用方定义的 subagent 与工作流结构化输出仍要求对象根**：这是消费方层面的守卫；共享 schema 词汇和工具输出支持任意 JSON 根。
 - **定义上的 `timeoutMs` 仅为声明**：注册表绝不会强制执行截止时间；要强制执行，必须使用 `@deepseek-ai/dsh-timeout-policy` 包装层。
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index aa4a1f027a..2ec5a1bb25 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -373,7 +373,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
 
       let dispatches = 0
       // The per-run scheduler, reusing the NATIVE concurrency contract through
-      // the registry's staged view (the loop scheduler's own seam) — and the
+      // the registry's staged view (the loop scheduler's own boundary) — and the
       // native loop's SEQUENCING: every ordered stage (the dispatch-start
       // append, prepare = pre-execute/guards, finalize/finish = post-execute,
       // context deferral, the settle append) runs inside ONE driver lane, so
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 657de4578e..7c2346e723 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -148,7 +148,7 @@ declare module 'cordis' {
     'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolDispatchExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
     /**
      * Accept, replace, enrich, or block a normalized dispatch result. `next()`
-     * accepts it unchanged; thrown tools still reach this seam as errors. Async
+     * accepts it unchanged; thrown tools still reach this waterfall as errors. Async
      * listeners must observe `exec.signal`; after they settle, caller
      * cancellation replaces only a successful accepted outcome with the code
      * selected by whether the tool body was invoked.
@@ -418,7 +418,7 @@ export type ScheduledToolDispatch =
 /**
  * Symbol-keyed scheduler view that keeps pre/post policy ordered while
  * overlapping dispatch. Ordinary callers use {@link ToolRegistry.execute};
- * this is not a plugin seam.
+ * this is not a plugin extension point.
  * @internal
  */
 export interface ToolRegistryScheduler {
@@ -1069,7 +1069,7 @@ export class ToolRegistry extends Service {
    * shaping must never fail the dispatch or lose the settle event. Private:
    * the ONE consumer is the `run_code` bridge this registry constructs, which
    * receives it as a capability parameter (the `requireRuntime` idiom) — the
-   * waterfall, not this invoker, is the public extension seam.
+   * waterfall, not this invoker, is the public extension point.
    */
   private async shapeDispatchLog(dispatch: CodeDispatchLog): Promise<ContentBlock[]> {
     try {
diff --git a/packages/core/tools/src/presentation.ts b/packages/core/tools/src/presentation.ts
index 5ca7bc5989..b719e16472 100644
--- a/packages/core/tools/src/presentation.ts
+++ b/packages/core/tools/src/presentation.ts
@@ -310,8 +310,8 @@ export interface ReadResultView {
 /**
  * One citeable source in a completed {@link WebSearchResultView}, the faithful
  * projection of one web-search source. The presentation projection of `dsh-web`'s
- * `WebSearchSource`: that seam type is the authoritative shape (core cannot depend
- * on the web seam, so the two are declared separately and MUST evolve together).
+ * `WebSearchSource`: that Service Definition type is authoritative (core cannot depend
+ * on the web Service Definition, so the two are declared separately and MUST evolve together).
  * A web tool projects this shape through `output.presentationMeta` because the
  * render text cannot losslessly carry it (see the web-result-card Agent Note); its
  * `presentResult` reads it back.
@@ -361,7 +361,7 @@ export interface WebSearchResultView {
   sources: WebSource[]
   /** The provider-generated answer text, when any. */
   answer?: string
-  /** True when the seam cut the source list to honor the result cap. */
+  /** True when the web service cut the source list to honor the result cap. */
   truncated: boolean
 }
 
diff --git a/packages/core/tools/src/py-types.ts b/packages/core/tools/src/py-types.ts
index d1358124c3..33c05db92e 100644
--- a/packages/core/tools/src/py-types.ts
+++ b/packages/core/tools/src/py-types.ts
@@ -500,7 +500,7 @@ function renderType(schema: unknown, className: string, state: RenderState): str
     ({ schema, className, phase: 'start', listDepth, children: [], childIndex: 0, childTypes: [], entries: [] })
   try {
     // Validate the WHOLE tree once, then trust it — the same contract the
-    // sibling ts-types renderer follows at a typed same-process seam. Every
+    // sibling ts-types renderer follows at a typed same-process boundary. Every
     // node past this point is a validated JSON-schema node, so the walk reads
     // its fields without re-checking. An unsupported or malformed schema throws
     // here (before anything is emitted) and degrades to `Any`, the Python
diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts
index e2c2c8be7e..06993467e8 100644
--- a/packages/core/tools/tests/code-mode.spec.ts
+++ b/packages/core/tools/tests/code-mode.spec.ts
@@ -19,7 +19,7 @@ const testToolSignal = new AbortController().signal
  * misconfiguration rejections, the run_code dispatch bridge (serialization,
  * abort, JSON normalization, error mapping, events, quiescence), and HMR
  * safety — all against an in-repo fake runtime, exactly the
- * interface/implementation/consumer shape the seam promises.
+ * Service Definition / Service provider / Consumer roles the seam promises.
  */
 
 /** A scriptable in-repo CodeRuntime: each test sets `behavior` to drive the bindings however it needs. */
diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts
index 4149a21273..cfb1f6db05 100644
--- a/packages/core/tools/tests/tools.spec.ts
+++ b/packages/core/tools/tests/tools.spec.ts
@@ -1068,7 +1068,7 @@ describe('ToolRegistry', () => {
 
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'traced', arguments: { text: 'hi' } })
     expect(result).toEqual({ content: [{ type: 'text', text: 'hi' }], isError: false, value: [{ type: 'text', text: 'hi' }] })
-    // The around seam wraps dispatch; pre gates before it, post runs over its result.
+    // The around-dispatch extension point wraps dispatch; pre gates before it, post runs over its result.
     expect(order).toEqual(['pre', 'execute:before', 'dispatch', 'execute:after', 'post'])
   })
 
@@ -1646,7 +1646,7 @@ describe('ToolRegistry', () => {
     const result = await ctx.tools.execute({ signal: testToolSignal, callId: CallId('c1'), name: 'echo', arguments: { text: 'hi' } })
     expect(result.isError).toBe(true)
     expect(result.content[0]).toMatchObject({ text: 'Error: nope' })
-    expect(entered).toBe(false) // a denied call never enters the around-dispatch seam
+    expect(entered).toBe(false) // A denied call never enters the around-dispatch extension point.
   })
 
   it('a thrown tool is normalized to an isError result BEFORE a tools/execute listener sees next()', async () => {
diff --git a/packages/credentials/credentials-local/src/invariant.ts b/packages/credentials/credentials-local/src/invariant.ts
index 9ec75ed21d..454f2b808e 100644
--- a/packages/credentials/credentials-local/src/invariant.ts
+++ b/packages/credentials/credentials-local/src/invariant.ts
@@ -15,7 +15,7 @@ export const name = 'credentials-local-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: the seam companion (`dsh-credentials/invariant`) owns the
+ * No runtime invariant: the Service Definition companion (`dsh-credentials/invariant`) owns the
  * `credentials/updated` lifecycle contract; this provider's file/environment layering is
  * asynchronous I/O pinned by its unit suite.
  */
diff --git a/packages/credentials/credentials/README.i18n.yaml b/packages/credentials/credentials/README.i18n.yaml
index 34c5ffc794..053af47617 100644
--- a/packages/credentials/credentials/README.i18n.yaml
+++ b/packages/credentials/credentials/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/credentials/credentials/README.md
-README.md: 95ef76d145727340d8135bf1d48babd6d8adb882
-README.zh.md: dce426fde734e3368317ccd2fa6848ca1e00048e
+README.md: fc4fb16991a3396f106bed65b468d0ae538bbab8
+README.zh.md: 6007618e5dc917ebc38fd322b34427cb5281e70c
diff --git a/packages/credentials/credentials/README.md b/packages/credentials/credentials/README.md
index 95ef76d145..fc4fb16991 100644
--- a/packages/credentials/credentials/README.md
+++ b/packages/credentials/credentials/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Abstract credential seam (`ctx.credentials`). One doctrine, three consequences:
+Credential Service Definition (`ctx.credentials`). One doctrine, three consequences:
 
 **Configuration carries references to secrets, never the secrets.** A settings section or `cordis.yml` entry says `apiKeyEnv: DEEPSEEK_API_KEY`; the value behind that reference lives with a credential provider. So the settings document stays safe to sync and to render in a configuration UI, `describe()` can answer "is this configured, where from, can I write it" without ever holding a value, and rotating a secret touches no configuration file.
 
diff --git a/packages/credentials/credentials/README.zh.md b/packages/credentials/credentials/README.zh.md
index dce426fde7..6007618e5d 100644
--- a/packages/credentials/credentials/README.zh.md
+++ b/packages/credentials/credentials/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-抽象凭据 seam（`ctx.credentials`）。一条准则，三个推论：
+凭据 Service Definition（`ctx.credentials`）。一条准则，三个推论：
 
 **配置只携带对机密的引用，绝不携带机密本身。** settings 分节或 `cordis.yml` 条目写 `apiKeyEnv: DEEPSEEK_API_KEY`，引用背后的值归凭据提供方所有。于是设置文档可以放心同步、放心渲染进配置界面；`describe()` 无需持有值就能回答「配置了吗、来自哪层、能否写入」；轮换机密不触碰任何配置文件。
 
diff --git a/packages/credentials/credentials/src/index.ts b/packages/credentials/credentials/src/index.ts
index c6470c1628..5f1efb010c 100644
--- a/packages/credentials/credentials/src/index.ts
+++ b/packages/credentials/credentials/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Credential seam (`ctx.credentials`). Settings and composition files carry
+ * Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
  * *references* to secrets — environment-variable names — while providers own
  * the actual values and their storage. Consumers resolve a reference once per
  * operation, so a changed credential reaches the next operation without any
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index a8edcb34ab..90c7931644 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: cd170bcbe2831b0856b51791a2045382d93c1148
-README.zh.md: f97790cf1d4ef90f042df8ed564723e186327f00
+README.md: b346b4c5bc7bc2888ccd3dc210bb90e0f1cc5965
+README.zh.md: b84b2382c03dc6e422228b19a58aff927e8a5db7
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index cd170bcbe2..b346b4c5bc 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -2,14 +2,14 @@
 
 English | [中文](README.zh.md)
 
-E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provider seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
+E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provider contract. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
 
 ## Behavior
 
 - **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; GNU `realpath -mz` supplies canonical target identity without requiring the final file to exist, and ASCII/base64 plus strict NUL framing preserves newline and multibyte paths across the decoded SDK transport. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam; listings reuse returned metadata and resolve symbolic-link entries sequentially. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
 - **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
-- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
+- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the filesystem seam's observed-state semantics.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before rename. The signal is not forwarded into the rename RPC, so cancellation cannot interrupt the atomic commit; a successful rename is the commit point.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index f97790cf1d..b84b2382c0 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -2,14 +2,14 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) 提供方 seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
+[`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) 提供方约定的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
 
 ## 行为
 
 - **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；GNU `realpath -mz` 提供规范化目标身份，且不要求最终文件存在；ASCII/base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam；目录列表会复用已返回的元数据，并依次解析符号链接条目。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
 - **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
-- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
+- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留文件系统 seam 的已观察状态语义。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在 rename 前立即检查。信号不会传入 rename RPC，因此取消无法中断原子提交；成功 rename 是提交点。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 84c9ac7868..83ff7bd99b 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * E2B implementation of the filesystem provider seam. Paths, contents, and
+ * E2B provider for the filesystem capability seam. Paths, contents, and
  * atomic staging files remain inside the shared remote sandbox.
  * @module @deepseek-ai/dsh-fs-e2b
  */
diff --git a/packages/e2b/subprocess-e2b/README.i18n.yaml b/packages/e2b/subprocess-e2b/README.i18n.yaml
index d0ce148746..d6f23acf04 100644
--- a/packages/e2b/subprocess-e2b/README.i18n.yaml
+++ b/packages/e2b/subprocess-e2b/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/e2b/subprocess-e2b/README.md
-README.md: 926d4f22f8e96daa103c236121d35e461290221a
-README.zh.md: d1634b6d1a701f7f4815135b4ec6bb86ad1a8c87
+README.md: bb0ac1d5f1f3dbfd0f021d5fbebbab13dcee37ee
+README.zh.md: d511df72284b047626ece628b702a2ac8d2f873d
diff --git a/packages/e2b/subprocess-e2b/README.md b/packages/e2b/subprocess-e2b/README.md
index 926d4f22f8..bb0ac1d5f1 100644
--- a/packages/e2b/subprocess-e2b/README.md
+++ b/packages/e2b/subprocess-e2b/README.md
@@ -24,7 +24,7 @@ The default E2B base image supplies the runtime and Bash/GNU utilities this adap
 
 ## Model Experience
 
-Indirectly, through consumer seams such as the Bash executor behind `dsh-tool-bash`, which render remote output, exit facts, background deltas, and spill paths.
+Indirectly, through Consumers such as the Bash executor behind `dsh-tool-bash`, which render remote output, exit facts, background deltas, and spill paths.
 
 #### KV Cache effect
 
diff --git a/packages/e2b/subprocess-e2b/README.zh.md b/packages/e2b/subprocess-e2b/README.zh.md
index d1634b6d1a..d511df7228 100644
--- a/packages/e2b/subprocess-e2b/README.zh.md
+++ b/packages/e2b/subprocess-e2b/README.zh.md
@@ -24,7 +24,7 @@ E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：
 
 ## 模型体验
 
-通过消费方 seam 间接影响模型，例如 `dsh-tool-bash` 背后的 Bash 执行器；这些消费方会渲染远程输出、退出事实、后台增量和 spill 路径。
+通过 Consumer 间接影响模型，例如 `dsh-tool-bash` 背后的 Bash 执行器；这些 Consumer 会渲染远程输出、退出事实、后台增量和 spill 路径。
 
 #### KV Cache 影响
 
diff --git a/packages/e2b/subprocess-e2b/src/index.ts b/packages/e2b/subprocess-e2b/src/index.ts
index c6d2dbd4eb..3c0063c457 100644
--- a/packages/e2b/subprocess-e2b/src/index.ts
+++ b/packages/e2b/subprocess-e2b/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * E2B implementation of the subprocess seam. Each handle starts through the
+ * E2B Service provider for the subprocess capability seam. Each handle starts through the
  * shared sandbox and retains command output/status paths in that remote world.
  * @module @deepseek-ai/dsh-subprocess-e2b
  */
diff --git a/packages/e2b/subprocess-e2b/src/process.ts b/packages/e2b/subprocess-e2b/src/process.ts
index c80a2f5bd9..2dc552b575 100644
--- a/packages/e2b/subprocess-e2b/src/process.ts
+++ b/packages/e2b/subprocess-e2b/src/process.ts
@@ -184,7 +184,7 @@ export class E2BSubprocessHandle implements SubprocessHandle {
   private terminationSignal: NodeJS.Signals | null = null
 
   /**
-   * Begin an E2B command without blocking the synchronous subprocess spawn seam.
+   * Begin an E2B command without blocking the synchronous subprocess spawn call.
    * @param runtime - Shared E2B sandbox owner.
    * @param spec - Fully resolved subprocess request.
    * @param stateDir - Remote directory retaining process identity, status, and valid spills.
diff --git a/packages/examples/agent-spine-demo/README.i18n.yaml b/packages/examples/agent-spine-demo/README.i18n.yaml
index 43cdef4af8..a698160634 100644
--- a/packages/examples/agent-spine-demo/README.i18n.yaml
+++ b/packages/examples/agent-spine-demo/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/examples/agent-spine-demo/README.md
-README.md: d1c3c28183956b4f66db7ed4a6f3a08588b5352c
-README.zh.md: cf372a428c16893b1d328ea60ad70c09d6d9725c
+README.md: cfec2c46ada8ed97aef44fb1d4145ddecdeecab1
+README.zh.md: d482ea9ca7034874383472050a8c837bea5bfaad
diff --git a/packages/examples/agent-spine-demo/README.md b/packages/examples/agent-spine-demo/README.md
index d1c3c28183..cfec2c46ad 100644
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -49,7 +49,7 @@ The spine is everything COMMON to every front door. The swappable and front-door
 - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
 - **front-door + per-app infrastructure** — headless, ACP, and JSON-RPC app packages own transport, stdout, and reload choices. `timer` stays in the spine because it is common and stdout-silent.
 
-This is the [interface/implementation/consumer seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.
+This applies the [Service Definition / Service provider / Consumer separation](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) at the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.
 
 ## Config
 
@@ -80,4 +80,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **Most of the spine set is fixed in code** — `apply()` always mounts the core services; config can omit bundled goals, skills, bash, and task-control tools, but swapping the loop or dropping another spine member means composing a different bundle.
-- **The invariant seam and companions remain fixed members** — `invariants.enabled: false` or package filters suppress checks but do not remove the service or companion registrations; Session's always-on validation and freezing are separate.
+- **The invariant service and companions remain fixed members** — `invariants.enabled: false` or package filters suppress checks but do not remove the service or companion registrations; Session's always-on validation and freezing are separate.
diff --git a/packages/examples/agent-spine-demo/README.zh.md b/packages/examples/agent-spine-demo/README.zh.md
index cf372a428c..d482ea9ca7 100644
--- a/packages/examples/agent-spine-demo/README.zh.md
+++ b/packages/examples/agent-spine-demo/README.zh.md
@@ -49,7 +49,7 @@
 - **非本地 skill 提供方**：组合包交付 skill 注册表、本地文件系统提供方和 `skill` 工具；部署可以把嵌入式目录或远程目录等其他提供方作为同级插件添加。
 - **前端入口与各应用基础设施**：无头、ACP（Agent Client Protocol）和 JSON-RPC 应用包负责传输、stdout 与重新加载选择。`timer` 保留在主干中，因为它是共有组件且不写 stdout。
 
-这把[接口／实现／消费方 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) 提升到组合层：组合包拥有共享主干，叶节点拥有后端，应用包拥有前端入口。
+这里在组合层应用 [Service Definition／Service provider／Consumer 的职责分离](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：组合包拥有共享主干，叶节点拥有后端，应用包拥有前端入口。
 
 ## 配置
 
@@ -80,4 +80,4 @@ YAML include 可以去重配置，却无法拥有 bin 或提供前端入口默
 ## 已知限制与暂缓事项
 
 - **大部分主干集合固定在代码中**：`apply()` 始终挂载核心服务；配置可以省略组合包内的目标、skill、bash 与任务控制工具，但要替换循环或删除其他主干成员，就必须组合另一个组合包。
-- **不变式 seam 与配套插件仍是固定成员**：`invariants.enabled: false` 或包筛选器会抑制检查，但不会移除服务或配套插件注册；Session 始终启用的校验与冻结是另一套机制。
+- **不变式服务与配套插件仍是固定成员**：`invariants.enabled: false` 或包筛选器会抑制检查，但不会移除服务或配套插件注册；Session 始终启用的校验与冻结是另一套机制。
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index aa010c33f2..edda1470df 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: 162e2c75e92bc4ea6aba377c14db62e8ce83fbb9
-README.zh.md: 196a2aad89203905148581d6364be7f02e2f4e35
+README.md: fad17083817bd8023649ef7d0f0f1b62fbb9295f
+README.zh.md: e8544d71ee853547400e5970f0db9a9946562d48
diff --git a/packages/fs/README.md b/packages/fs/README.md
index 162e2c75e9..fad1708381 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -2,11 +2,11 @@
 
 English | [中文](README.zh.md)
 
-The filesystem stack: a provider seam (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the bash-backed discovery tools. All **product** packages.
+The filesystem stack: a provider contract (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the bash-backed discovery tools. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| `fs/` | Provider seam: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
+| `fs/` | Service Definition: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
 | `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
 | [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | E2B-backed `FileSystem` implementation sharing the remote runtime owned by `ctx.e2b` | (registers `ctx.fs`) |
 | `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
@@ -14,10 +14,10 @@ The filesystem stack: a provider seam (execution-world paths, bounded text IO, a
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
 | `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+The Service Definition lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the Service Definition, policy gate, or model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider contract: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
 
 The subsystem reference — targets, outcomes, guards, policy events, the error taxonomy, and why file IO takes no timeout — is [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md); the sandbox fence in the [cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md).
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index 196a2aad89..e8544d71ee 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -2,22 +2,22 @@
 
 [English](README.md) | 中文
 
-文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、策略门禁插件（已观察状态、编辑前读取、版本防护的写入／编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品**包。
+文件系统栈包括：提供方约定（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品** 包。
 
 | 包 | 角色 | ctx 键 |
 |---|---|---|
-| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 策略事件 | `ctx.fs` |
+| `fs/` | Service Definition：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
 | `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
 | [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
-| `fs-sandbox/` | 强制实施沙箱约束的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根策略约束写入／编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
-| `fs-policy/` | 策略门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
+| `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
+| `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
 | `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、策略门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。策略（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去策略，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索约定；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+Service Definition 位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方约定：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索约定；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
 
 ## 文件 I/O 不设超时
 
-`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
+`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方约定也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
 
-子系统参考——目标、结果、守卫、策略事件、错误分类体系，以及文件 I/O 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
+子系统参考——目标、结果、防护、策略事件、错误分类体系，以及文件 IO 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index 250b94dacf..dd384cd2b1 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-local/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/fs/fs-local/README.md
-README.md: 2e934298ceff75440357b0742770010c8b1c3904
-README.zh.md: 14f4867ce0f9eaae2a1dea98dbd7d401c98d4535
+README.md: ec0cffea1c82ab3bb2485fcb22ac5339d5d2a0d9
+README.zh.md: 99adba8c8b58f1f0b6f0f5ab8b672eb074b38f31
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index 2e934298ce..ec0cffea1c 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eleven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+The **local-filesystem implementation** of the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eleven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 14f4867ce0..99adba8c8b 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十一个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
+`ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十一个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index c93e4ddaeb..7e063ca347 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -70,7 +70,7 @@ function versionOf(info: BigIntStats): FsVersion {
 }
 
 /**
- * Test seam: lets specs pin the atomic-write temp names (to prove
+ * Test hook: lets specs pin the atomic-write temp names (to prove
  * exclusive-open behavior without a name race) and observe the staged temp
  * file before it is renamed over the target.
  */
@@ -427,7 +427,7 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
  * @param mode - existing destination's POSIX mode to preserve, or `undefined` for a new file;
  * inert as a mode on Windows but identifies replacement security semantics.
  * @param signal - cancellation checked before the final rename.
- * @param internals - test seam for pinning temp names and observing the staged file.
+ * @param internals - Test hook for pinning temp names and observing the staged file.
  */
 export async function writeFileAtomic(
   absolutePath: string,
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index f6049b1795..6f9af5cec2 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -56,7 +56,7 @@ export class LocalFileSystem extends FileSystem {
 
   /** Validated config (schemastery applied the defaults before construction). */
   readonly config: ResolvedConfig
-  /** Test seam forwarded to fsio (force streaming path, pin temp names). */
+  /** Test hook forwarded to fsio (force streaming path, pin temp names). */
   internals: FsIoInternals = {}
   /** Per-targetKey tail promise: serializes mutating ops so the read→guard→write
    * window can't interleave, making concurrent writes/edits deterministically
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index 4906bb0adc..ee3abeebb8 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Tests for the local backend through the `ctx.fs` provider seam: stat, whole-
+ * Tests for the local backend through the `ctx.fs` Service Definition: stat, whole-
  * file/streamed text reads, atomic guarded writes (createIfAbsent /
  * replaceIfVersion), version-guarded literal edits, concurrency races, symlink
  * identity, and HMR/disposal. Read WINDOWING is policy and lives in
@@ -55,7 +55,7 @@ describe('registration', () => {
 describe('resolve', () => {
   it('resolves a relative path against opts.cwd, not config.cwd', async () => {
     // config.cwd is `dir`; a call supplying a DIFFERENT cwd bases the relative
-    // path there (the per-session-workspace seam — mirrors tool-bash workdir).
+    // path there (the per-session workspace mapping — mirrors tool-bash workdir).
     const other = await mkdtemp(join(tmpdir(), 'dsh-fs-other-'))
     try {
       await writeFile(join(other, 'x.txt'), 'in other')
diff --git a/packages/fs/fs-policy/README.i18n.yaml b/packages/fs/fs-policy/README.i18n.yaml
index e4d85c9a88..c2b72c65c8 100644
--- a/packages/fs/fs-policy/README.i18n.yaml
+++ b/packages/fs/fs-policy/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/fs/fs-policy/README.md
-README.md: f6b3292bdc6e5565df0393a59c50d4e594921401
-README.zh.md: 2ebd2f054ece0472c7147f6f9e740987b11c6031
+README.md: bf6486f6f7fe574b576a71b430be91031f7805d2
+README.zh.md: 2e38d63d8e310c7f22b764d46cbec0c82ffb96cf
diff --git a/packages/fs/fs-policy/README.md b/packages/fs/fs-policy/README.md
index f6b3292bdc..bf6486f6f7 100644
--- a/packages/fs/fs-policy/README.md
+++ b/packages/fs/fs-policy/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **fs-policy plugin**: it adds observed-state, read-before-edit, and version-guarded write/edit on top of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)) — through the `fs/*` event gate, **NOT** through a method service. This plugin registers **no** `ctx.fsPolicy` service and has no public `read`/`write`/`edit`/`resolve` methods. It is the policy third of the filesystem stack: not a swappable seam, but the policy that does not belong on the `FileSystem` provider base class.
+The **fs-policy plugin**: it adds observed-state, read-before-edit, and version-guarded write/edit on top of the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)) — through the `fs/*` event gate, **NOT** through a method service. This plugin registers **no** `ctx.fsPolicy` service and has no public `read`/`write`/`edit`/`resolve` methods. It is the policy third of the filesystem stack: not a swappable seam, but the policy that does not belong on the `FileSystem` provider base class.
 
 ```ts
 import type { Context } from 'cordis'
@@ -24,7 +24,7 @@ await ctx.plugin(FsPolicy)
 |---|---|---|
 | tool / executor | `@deepseek-ai/dsh-tool-fs` | model-facing schemas + read windowing + text rendering; reads/writes/edits via `ctx.fs`, dispatches the `fs/*` events |
 | policy | `@deepseek-ai/dsh-fs-policy` (this) | observed-state + read-before-edit + version-guarded write/edit, contributed through the `fs/*` event gate (no service) |
-| provider seam | `@deepseek-ai/dsh-fs` | `ctx.fs`: text IO + atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
+| provider contract | `@deepseek-ai/dsh-fs` | `ctx.fs`: text IO + atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
 | provider | `@deepseek-ai/dsh-fs-local` | local implementation of `ctx.fs` |
 
 ## How the gate participates
diff --git a/packages/fs/fs-policy/README.zh.md b/packages/fs/fs-policy/README.zh.md
index 2ebd2f054e..2e38d63d8e 100644
--- a/packages/fs/fs-policy/README.zh.md
+++ b/packages/fs/fs-policy/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**fs-policy 插件**：它在 `ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）之上增加已观察状态、编辑前读取和版本防护的写入/编辑；它通过 `fs/*` 事件门禁参与，**不是**通过方法服务。该插件**不**注册 `ctx.fsPolicy` 服务，也没有公开的 `read`/`write`/`edit`/`resolve` 方法。它是文件系统栈的策略层：不是可替换 seam，而是不应位于 `FileSystem` 提供方基类上的策略。
+**fs-policy 插件**：它在 `ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）之上增加已观察状态、编辑前读取和版本防护的写入/编辑；它通过 `fs/*` 事件门禁参与，**不是**通过方法服务。该插件**不**注册 `ctx.fsPolicy` 服务，也没有公开的 `read`/`write`/`edit`/`resolve` 方法。它是文件系统栈的策略层：不是可替换 seam，而是不应位于 `FileSystem` 提供方基类上的策略。
 
 ```ts
 import type { Context } from 'cordis'
@@ -24,7 +24,7 @@ await ctx.plugin(FsPolicy)
 |---|---|---|
 | 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
 | 策略 | `@deepseek-ai/dsh-fs-policy`（本包） | 通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑（无服务） |
-| 提供方 seam | `@deepseek-ai/dsh-fs` | `ctx.fs`：文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
+| 提供方约定 | `@deepseek-ai/dsh-fs` | `ctx.fs`：文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
 | 提供方 | `@deepseek-ai/dsh-fs-local` | `ctx.fs` 的本地实现 |
 
 ## 门禁的参与方式
diff --git a/packages/fs/fs-sandbox/src/index.ts b/packages/fs/fs-sandbox/src/index.ts
index 5e0121c89a..1d5f972da9 100644
--- a/packages/fs/fs-sandbox/src/index.ts
+++ b/packages/fs/fs-sandbox/src/index.ts
@@ -1,6 +1,6 @@
 /**
  * `SandboxedFileSystem`: the sandbox-enforcing implementation of the
- * `@deepseek-ai/dsh-fs` provider seam. It extends `LocalFileSystem` so all
+ * `@deepseek-ai/dsh-fs` Service Definition. It extends `LocalFileSystem` so all
  * text-storage mechanics — resolve, stat, read/stream, list, the atomic
  * write and the read-match-write edit critical section — are the local
  * implementation's, verbatim; this package adds only the per-call POLICY fence
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index 5ed8633331..a77f4c8e04 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: 11134e6298e6c87d1046952c65bb2dadff43e4a2
-README.zh.md: 7edece618150739d5ff67c605788dae42a5a5c32
+README.md: c7c978b7530a9b26e178f164dae61ae60f8f321f
+README.zh.md: 9761fc81bcb160edfc96d42cea45183abcfc087d
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index 11134e6298..c7c978b753 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -4,13 +4,13 @@ English | [中文](README.zh.md)
 
 The **`FileSystem`** (`ctx.fs`) defines the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read whole or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
-This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
+This package owns the Service Definition and provider contract layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
 
 | Layer | Package | Role |
 |---|---|---|
 | tool / executor | `@deepseek-ai/dsh-tool-fs` | model-facing `read`/`write`/`edit` schemas + read windowing + text rendering; reads/writes/edits via `ctx.fs`, dispatches the `fs/*` events |
 | policy | `@deepseek-ai/dsh-fs-policy` | observed-state + read-before-edit + version-guarded write/edit, contributed through the `fs/*` event gate (no service) |
-| provider seam | `@deepseek-ai/dsh-fs` (this) | `ctx.fs`: execution-world paths, text IO, and atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
+| provider contract | `@deepseek-ai/dsh-fs` (this) | `ctx.fs`: execution-world paths, text IO, and atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
 | provider | `@deepseek-ai/dsh-fs-local` | the host-filesystem implementation |
 
 A future sandboxed, virtual, or remote backend implements this interface and the policy/tool layers don't change.
@@ -39,7 +39,7 @@ The mutation runs inside the backend's per-target lock either way, so an uncondi
 
 This package declares three events (see the generated region of [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
-## A provider seam, not the policy layer
+## A provider contract, not the policy layer
 
 `ctx.fs` is deliberately close to fsspec-style storage primitives — half a level above byte-level `cat`/`open`, because it decodes text and rejects binaries so the policy layer never touches raw bytes. It owns UTF-8 decoding, binary rejection, atomic writes, and the literal-edit critical section. It does **not** own line windows, numbered lines, rendered footers, or observed-state. Observed-state, read-before-edit, and version-guarded write/edit are policy a plugin (`@deepseek-ai/dsh-fs-policy`) ADDS by supplying the optional guard — not provider behavior — so a sandboxed/remote backend inherits no model-facing observation policy.
 
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 7edece6181..9761fc81bc 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -2,18 +2,18 @@
 
 [English](README.md) | 中文
 
-**`FileSystem`**（`ctx.fs`）定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
+**`FileSystem`**（`ctx.fs`）定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
 
-本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
+本包是四层文件系统栈中的提供方约定层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
 
 | 层 | 包 | 角色 |
 |---|---|---|
 | 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 `read`/`write`/`edit` schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
-| 策略 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
-| 提供方 seam | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
+| 政策 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
+| 提供方约定 | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
 | 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
 
-未来的沙箱化、虚拟或远程后端只需实现该接口，策略层和工具层无需改变。
+未来的沙箱化、虚拟或远程后端只需实现该接口，政策层和工具层无需改变。
 
 ## 服务 API（`ctx.fs`）
 
@@ -26,7 +26,7 @@
 | `fileUrl(target)` | 返回采用执行世界平台语法的规范化 `file:` URI。编码由后端而非宿主进程负责。 |
 | `contains(parent, child)` | 在不公开或解析目标 key 的情况下，检查规范化身份相等或后代包含关系。两个目标都来自该提供方。 |
 | `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
-| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库自有的符号链接进入目标前拒绝它。 |
+| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
 | `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
 | `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
@@ -35,15 +35,15 @@
 
 无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
 
-## `fs/*` 策略事件
+## `fs/*` 政策事件
 
-本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和策略监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖策略插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
-## 提供方 seam，不是策略层
+## 提供方约定，不是政策层
 
-`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察策略。
+`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使政策层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不** 负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的政策，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
 
-`editText` 留在该 seam 上，不由策略层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
+`editText` 留在该 seam 上，不由政策层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
 
 ## 词汇
 
@@ -55,9 +55,9 @@
 
 #### KV Cache 影响
 
-不会直接使缓存失效；上述消费方负责请求前缀的任何变化。
+不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
 
 - **约定只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
 - **只有十一个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts
index 2d46868a57..b4e3884c3b 100644
--- a/packages/fs/fs/src/index.ts
+++ b/packages/fs/fs/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Filesystem provider seam for one execution world. Backends own stable target
+ * Filesystem Service Definition for one execution world. Backends own stable target
  * identity, process paths and file URIs, containment, text reads, decoding,
  * binary rejection, and atomic mutations. Read windows and
  * observed-state policy stay in consumer and policy plugins; `editText`
diff --git a/packages/fs/fs/src/types.ts b/packages/fs/fs/src/types.ts
index f5753f09bd..6a34f3848f 100644
--- a/packages/fs/fs/src/types.ts
+++ b/packages/fs/fs/src/types.ts
@@ -1,5 +1,5 @@
 /**
- * Vocabulary for the filesystem provider seam (`ctx.fs`): the opaque target/version
+ * Vocabulary for the filesystem Service Definition (`ctx.fs`): the opaque target/version
  * identities, the metadata `stat` returns, the write-intent and outcome shapes, the
  * literal-edit request/outcome, and the typed error taxonomy.
  * @module @deepseek-ai/dsh-fs/types
diff --git a/packages/fs/fs/tests/service.spec.ts b/packages/fs/fs/tests/service.spec.ts
index f225e51cc0..2340871304 100644
--- a/packages/fs/fs/tests/service.spec.ts
+++ b/packages/fs/fs/tests/service.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Tests for the filesystem provider seam itself: registration, duplicate-service
+ * Tests for the filesystem Service Definition: registration, duplicate-service
  * behavior, disposal, and the branded id factories. The provider primitives and
  * policy live in `dsh-fs-local` and `dsh-fs-policy`; this seam owns only the
  * abstract service contract, so a minimal fake backend exercises it.
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index 8db18757f6..f6f036b33c 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md
-README.md: 6f96970d8194c0992f9b955b95aec092185054b2
-README.zh.md: 6cc8ebfe3ca4fc4e7c016aab64a0136cf4a07f14
+README.md: c9375a3ee803db48c547c7553d10f9b5ebde3fd2
+README.zh.md: 70ff15f2beff2674719f3084594e5cc0c7309f68
diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md
index 6f96970d81..c9375a3ee8 100644
--- a/packages/fs/tool-fs/README.md
+++ b/packages/fs/tool-fs/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **model-facing filesystem tools** — `read`, `write`, `edit` — and their **executor**. This is the consumer layer of the filesystem stack: it owns tool names, JSON schemas, argument validation, prompt sections, **read windowing**, and result formatting. It reads/writes/edits through the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)) **directly**. The freshness/observation policy is contributed by a separate plugin ([`@deepseek-ai/dsh-fs-policy`](../fs-policy)) through the `fs/*` event gate; the tool is not method-coupled to it. Under a confining provider, the shared sandbox-policy service is required for per-session execution and the tool exposes escalation for filesystem mutations.
+The **model-facing filesystem tools** — `read`, `write`, `edit` — and their **executor**. This is the consumer layer of the filesystem stack: it owns tool names, JSON schemas, argument validation, prompt sections, **read windowing**, and result formatting. It reads/writes/edits through the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)) **directly**. The freshness/observation policy is contributed by a separate plugin ([`@deepseek-ai/dsh-fs-policy`](../fs-policy)) through the `fs/*` event gate; the tool is not method-coupled to it. Under a confining provider, the shared sandbox-policy service is required for per-session execution and the tool exposes escalation for filesystem mutations.
 
 ```ts ignore-check
 // Default deployment: a ctx.fs provider, the policy plugin, then the tools.
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index 6cc8ebfe3c..70ff15f2be 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**面向模型的文件系统工具**（`read`、`write`、`edit`）及其**执行器**。这是文件系统栈的消费方层：拥有工具名称、JSON Schema、参数校验、提示词段、**读取窗口逻辑**和结果格式化。它**直接**通过 `ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）读取／写入／编辑。新鲜度／观察策略由独立插件（[`@deepseek-ai/dsh-fs-policy`](../fs-policy)）通过 `fs/*` 事件门禁贡献；工具不与其方法耦合。使用施加沙箱限制的提供方时，逐会话执行需要共享沙箱策略服务，工具还会为文件系统变更提供升权路径。
+**面向模型的文件系统工具**（`read`、`write`、`edit`）及其**执行器**。这是文件系统栈的消费方层：拥有工具名称、JSON Schema、参数校验、提示词段、**读取窗口逻辑**和结果格式化。它**直接**通过 `ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）读取／写入／编辑。新鲜度／观察策略由独立插件（[`@deepseek-ai/dsh-fs-policy`](../fs-policy)）通过 `fs/*` 事件门禁贡献；工具不与其方法耦合。使用施加沙箱限制的提供方时，逐会话执行需要共享沙箱策略服务，工具还会为文件系统变更提供升权路径。
 
 ```ts ignore-check
 // Default deployment: a ctx.fs provider, the policy plugin, then the tools.
diff --git a/packages/fs/tool-fs/src/session-cwd.ts b/packages/fs/tool-fs/src/session-cwd.ts
index 396e50351c..fd4a134acf 100644
--- a/packages/fs/tool-fs/src/session-cwd.ts
+++ b/packages/fs/tool-fs/src/session-cwd.ts
@@ -4,7 +4,7 @@
  * `read`/`write`/`edit` act on ITS workspace, not the server's launch dir — mirroring how
  * `dsh-tool-bash` defaults a bash `workdir` to the session cwd.
  * Non-agent calls return `undefined`, leaving the fallback in the provider rather than reading
- * `process.cwd()` at the tool seam.
+ * `process.cwd()` at the tool boundary.
  * @module @deepseek-ai/dsh-tool-fs/session-cwd
  */
 
diff --git a/packages/goal/goal-session/README.i18n.yaml b/packages/goal/goal-session/README.i18n.yaml
index 226316dbd7..1b9a48cbc7 100644
--- a/packages/goal/goal-session/README.i18n.yaml
+++ b/packages/goal/goal-session/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/goal/goal-session/README.md
-README.md: 89413062de8cbb49d7066ec3ae42769a99c939a2
-README.zh.md: a39a45232e7a2376154bc35182e77cc3b9ba1569
+README.md: 4534c937fcc53295b83bb207416715ef67b1f911
+README.zh.md: 389d692b44f89dc612efdf06f1e05a3f65eff7fd
diff --git a/packages/goal/goal-session/README.md b/packages/goal/goal-session/README.md
index 89413062de..4534c937fc 100644
--- a/packages/goal/goal-session/README.md
+++ b/packages/goal/goal-session/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Same-session continuation driver for [`ctx.goals`](../goal/README.md). It turns an active, armed goal into sequential [goal rounds](../../../docs/glossary.md#goal-round) through the public `Agent` and session seams; the [same-session driver Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md) owns the race and lifecycle rationale.
+Same-session continuation driver for [`ctx.goals`](../goal/README.md). It turns an active, armed goal into sequential [goal rounds](../../../docs/glossary.md#goal-round) through the public `Agent` and session services; the [same-session driver Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md) owns the race and lifecycle rationale.
 
 ## Composition
 
diff --git a/packages/goal/goal-session/README.zh.md b/packages/goal/goal-session/README.zh.md
index a39a45232e..389d692b44 100644
--- a/packages/goal/goal-session/README.zh.md
+++ b/packages/goal/goal-session/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`ctx.goals`](../goal/README.md) 的同会话续行驱动器。它通过公开 `Agent` 与会话 seam，把 phase 为 active 且已启用续行的目标转换为连续的 [Goal Round](../../../docs/glossary.md#goal-round)；[同会话驱动器 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md) 记载竞态与生命周期方面的设计理由。
+[`ctx.goals`](../goal/README.md) 的同会话续行驱动器。它通过公开 `Agent` 与会话服务，把 phase 为 active 且已启用续行的目标转换为连续的 [Goal Round](../../../docs/glossary.md#goal-round)；[同会话驱动器 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md) 记载竞态与生命周期方面的设计理由。
 
 ## 组合
 
diff --git a/packages/goal/goal-session/src/index.ts b/packages/goal/goal-session/src/index.ts
index 5c92f048d8..64c90e0c35 100644
--- a/packages/goal/goal-session/src/index.ts
+++ b/packages/goal/goal-session/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Same-session goal-round driver over public agent, session, and goal seams.
+ * Same-session goal-round driver over public agent, session, and goal services.
  * @module @deepseek-ai/dsh-goal-session
  */
 
diff --git a/packages/guard/README.i18n.yaml b/packages/guard/README.i18n.yaml
index 3097eeba3b..6e66ab407a 100644
--- a/packages/guard/README.i18n.yaml
+++ b/packages/guard/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/guard/README.md
-README.md: f0a80b1f497ee5b2459bebb55f886b42d74e4323
-README.zh.md: 43f60599b737d66578b463386b872ca9cc3108e4
+README.md: 73ca00e858c4ddaeb1ba9ccee7fb7e0cfce518f4
+README.zh.md: c5a5ac391d3b6f0b2d7615a92ac1b7920c2b80e6
diff --git a/packages/guard/README.md b/packages/guard/README.md
index f0a80b1f49..73ca00e858 100644
--- a/packages/guard/README.md
+++ b/packages/guard/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Behavioral guard plugins watch the agent loop for unproductive patterns and enforce per-call budgets. A guard is a self-contained consumer of core seams, not a swappable capability.
+Behavioral guard plugins watch the agent loop for unproductive patterns and enforce per-call budgets. A guard is a self-contained consumer of core services and extension points, not a swappable capability.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/guard/README.zh.md b/packages/guard/README.zh.md
index 43f60599b7..c5a5ac391d 100644
--- a/packages/guard/README.zh.md
+++ b/packages/guard/README.zh.md
@@ -1,8 +1,8 @@
-# guard/ — 循环健康 guard 家族
+# guard/ — 循环卫生 guard 家族
 
 [English](README.md) | 中文
 
-行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并强制执行单次调用预算。guard 是核心 seam 的自包含消费方，而非可替换能力。
+行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并强制执行单次调用预算。guard 是核心服务和扩展点的自包含消费方，而非可替换能力。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
diff --git a/packages/guard/timeout-policy/src/index.ts b/packages/guard/timeout-policy/src/index.ts
index f554b1a93e..1ff88b46a9 100644
--- a/packages/guard/timeout-policy/src/index.ts
+++ b/packages/guard/timeout-policy/src/index.ts
@@ -27,7 +27,7 @@ export const TOOL_TIMEOUT = 'TOOL_TIMEOUT'
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'timeout-policy'
 
-/** The tool registry seam this plugin wraps (`tools/execute`) and reads (`get`). */
+/** The tool registry service this plugin wraps (`tools/execute`) and reads (`get`). */
 export const inject = ['tools']
 
 /**
diff --git a/packages/hooks/README.i18n.yaml b/packages/hooks/README.i18n.yaml
index 3aff382ea6..82051c1e9d 100644
--- a/packages/hooks/README.i18n.yaml
+++ b/packages/hooks/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/hooks/README.md
-README.md: 35989292313c6cef47c02041eb671a73ff7c5786
-README.zh.md: 3d169d1286f38658d98f4c5f8d016ef77e1b6517
+README.md: fe743705ea8c07a2422847606cdfa42227be962f
+README.zh.md: 909ecf8e5414c382603beb7ee3fd0acbecdcfc47
diff --git a/packages/hooks/README.md b/packages/hooks/README.md
index 3598929231..fe743705ea 100644
--- a/packages/hooks/README.md
+++ b/packages/hooks/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The hooks subsystem lets users extend the agent at lifecycle points the way Claude Code and Codex do — by pointing a bridge plugin at an existing `hooks.json` (or settings) so those external shell hooks run faithfully. The canonical extension surface itself is the harness's typed interception seams ([the interception-seams Agent Note](../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)); a "native hook" is just an ordinary cordis plugin on those seams. These packages are the **bridges** that translate the external shell-hook protocol onto that same surface, plus the shared wire-protocol library they build on.
+The hooks subsystem lets users extend the agent at lifecycle points the way Claude Code and Codex do — by pointing a bridge plugin at an existing `hooks.json` (or settings) so those external shell hooks run faithfully. The canonical extension surface itself is the harness's typed interception points ([the interception extension-points Agent Note](../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)); a "native hook" is just an ordinary Cordis plugin on those extension points. These packages are the **bridges** that translate the external shell-hook protocol onto that same surface, plus the shared wire-protocol library they build on.
 
 | Package | Role | Shape |
 |---|---|---|
diff --git a/packages/hooks/README.zh.md b/packages/hooks/README.zh.md
index 3d169d1286..909ecf8e54 100644
--- a/packages/hooks/README.zh.md
+++ b/packages/hooks/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-hooks 子系统让用户像使用 Claude Code 和 Codex 一样，在生命周期节点扩展 agent（智能体）：把桥接插件指向现有 `hooks.json`（或 settings），即可忠实运行这些外部 shell 钩子。规范扩展 surface 本身是 harness 的类型化拦截 seam（参见[拦截 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)）；“原生钩子”只是这些 seam 上的普通 Cordis 插件。这些包是把外部 shell 钩子协议转换到同一 surface 的**桥接**，也包括它们共同依赖的共享协议格式库。
+hooks 子系统让用户像使用 Claude Code 和 Codex 一样，在生命周期节点扩展 agent（智能体）：把桥接插件指向现有 `hooks.json`（或 settings），即可忠实运行这些外部 shell 钩子。规范扩展 surface 本身是 harness 的类型化拦截点（参见[拦截扩展点 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)）；“原生钩子”只是这些扩展点上的普通 Cordis 插件。这些包是把外部 shell 钩子协议转换到同一 surface 的**桥接**，也包括它们共同依赖的共享协议格式库。
 
 | 包 | 职责 | 形态 |
 |---|---|---|
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index b7c8ec3ee8..61361487ba 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/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/hooks/hook-protocol/README.md
-README.md: 797d15c357bd26e0db072b30b61c251005021905
-README.zh.md: 8a96cd2f1f91ad2d7a12fc15ffc06ea0c2c1d80f
+README.md: 230f14c2bc053555991e5fb96e2753aef5bbff8a
+README.zh.md: d83ea99065123c9cf0f85c0abbbeeff6eadb17bc
diff --git a/packages/hooks/hook-protocol/README.md b/packages/hooks/hook-protocol/README.md
index 797d15c357..230f14c2bc 100644
--- a/packages/hooks/hook-protocol/README.md
+++ b/packages/hooks/hook-protocol/README.md
@@ -12,7 +12,7 @@ Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claud
 |---|---|---|
 | Matcher validation + test | `matcherDiagnostic(pattern, mode)` for parse-time diagnostics; `matchesMatcher(pattern, query, mode)` for contained runtime matching | picks its `mode` (`claude` = literal-or-regex, `codex` = always regex) and rejects a config group carrying a diagnostic |
 | Run a hook | `runHook(bash, hook, opts, now)` — stdin payload + env via `ctx.bash`, decode | builds the per-event stdin **payload** + the dialect's **env** |
-| Decode output | `parseHookOutput(exit, stdout, stderr)` → neutral `HookOutput` | maps the neutral `HookOutput` onto a seam-specific typed Decision |
+| Decode output | `parseHookOutput(exit, stdout, stderr)` → neutral `HookOutput` | maps the neutral `HookOutput` onto an extension-point-specific typed Decision |
 | Merge N hooks | `mergeHookOutputs(outputs)` → most-restrictive `MergedHookOutcome` | — |
 | Durable record | `appendHookInvoked` / `appendHookResult` (`hook/*` session events; the result's `decision`/`stderrSummary` derive from the `HookOutput` here) | calls them around each invocation |
 | Detached-run quiescence | `createDetachedRuns()` — track fire-and-forget run chains; `drain()` aborts, then awaits them | passes `signal` to each detached `runHook`, registers `drain` as its effect disposer |
@@ -23,7 +23,7 @@ Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claud
 - **`runHook(bash, hook, options, now)`** — require and forward the caller-owned `options.signal`, serialize `options.payload` to the hook's stdin (with a trailing newline iff `options.trailingNewline`), merge `options.env` after the executor's credential scrub (the `dsh-bash` trusted-plugin surface), honor the hook's `timeoutSec` (else `options.defaultTimeoutMs` — the bridge owns the default, its config defaulting to the lib's `DEFAULT_HOOK_TIMEOUT_MS` 10-minute reference), and decode the result (threading `options.expectedEventName` to the codec). Cancellation therefore reaches the executor's process-group kill and join boundary. Never throws: an executor rejection (infra fault) becomes a `HookOutput` with `exitCode: undefined` (a non-blocking error). `now` is injected for testable durations.
 - **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** decodes exit status and structured stdout. Exit 2 blocks with stderr; other failures are non-blocking. A matching hook-specific permission decision overrides the legacy top-level decision; mismatched or missing event discriminators suppress only event-specific fields. Top-level fields remain event-agnostic, and successful non-JSON output is left to the bridge.
 - **`mergeHookOutputs(outputs)`** — fold the results of every hook that matched one point: permission precedence **deny > ask > allow**, halt sticky on the first `continue:false`, block reasons joined with `\n\n`, `additionalContext`/`systemMessages` accumulated in order.
-- **`createDetachedRuns()`** — quiescence tracking for the emit-shaped points, which run detached (no seam awaits them). The bridge tracks each run chain — the hook run PLUS its continuation — and registers `drain()` as its effect disposer: drain fires the tracker's abort `signal` (so a still-running hook process is killed via `runHook`, not awaited out to its timeout), then resolves once every tracked chain has settled. `fiber.dispose()` resolving therefore means no detached hook work is left to fire into a disposed context ([defensive patterns](../../../docs/defensive-patterns.md): dispose must reach quiescence).
+- **`createDetachedRuns()`** — quiescence tracking for the emit-shaped points, which run detached (no extension point awaits them). The bridge tracks each run chain — the hook run PLUS its continuation — and registers `drain()` as its effect disposer: drain fires the tracker's abort `signal` (so a still-running hook process is killed via `runHook`, not awaited out to its timeout), then resolves once every tracked chain has settled. `fiber.dispose()` resolving therefore means no detached hook work is left to fire into a disposed context ([defensive patterns](../../../docs/defensive-patterns.md): dispose must reach quiescence).
 
 ## `hook/*` session events
 
diff --git a/packages/hooks/hook-protocol/README.zh.md b/packages/hooks/hook-protocol/README.zh.md
index 8a96cd2f1f..d83ea99065 100644
--- a/packages/hooks/hook-protocol/README.zh.md
+++ b/packages/hooks/hook-protocol/README.zh.md
@@ -12,7 +12,7 @@ Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它
 |---|---|---|
 | Matcher 校验 + 测试 | `matcherDiagnostic(pattern, mode)` 用于解析时诊断；`matchesMatcher(pattern, query, mode)` 用于隔离的运行时匹配 | 选择自身的 `mode`（`claude` = 字面量或正则，`codex` = 始终使用正则），并拒绝带有诊断的配置组 |
 | 运行 hook | `runHook(bash, hook, opts, now)`：通过 `ctx.bash` 提供 stdin payload + env，再解码 | 构造每个事件的 stdin **payload** + 该方言的 **env** |
-| 解码输出 | `parseHookOutput(exit, stdout, stderr)` → 中性 `HookOutput` | 将中性 `HookOutput` 映射到 seam 特定的类型化 Decision |
+| 解码输出 | `parseHookOutput(exit, stdout, stderr)` → 中性 `HookOutput` | 将中性 `HookOutput` 映射到扩展点特定的类型化 Decision |
 | 合并 N 个 hook | `mergeHookOutputs(outputs)` → 最严格的 `MergedHookOutcome` | （无） |
 | 持久记录 | `appendHookInvoked` / `appendHookResult`（`hook/*` 会话事件；结果的 `decision`／`stderrSummary` 从此处的 `HookOutput` 派生） | 在每次调用前后调用它们 |
 | 脱离运行完全停稳 | `createDetachedRuns()`：跟踪触发后不等待的运行链；`drain()` 先 abort，再等待它们 | 将 `signal` 传给每个脱离的 `runHook`，并将 `drain` 注册为 effect disposer |
@@ -23,7 +23,7 @@ Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它
 - **`runHook(bash, hook, options, now)`**：要求并转发调用方拥有的 `options.signal`，将 `options.payload` 序列化到 hook stdin（当且仅当 `options.trailingNewline` 时添加尾随换行符），在执行器凭证清理后合并 `options.env`（`dsh-bash` 受信任插件接口），遵循 hook 的 `timeoutSec`（否则使用 `options.defaultTimeoutMs`；默认值属于桥接，其配置默认为 lib 的 `DEFAULT_HOOK_TIMEOUT_MS` 10 分钟参考值），再解码结果（将 `options.expectedEventName` 传递给 codec）。因此取消会到达执行器的进程组终止与 join 边界。它绝不抛出异常：执行器拒绝（基础设施故障）会变为 `HookOutput`，其 `exitCode: undefined`（非阻塞错误）。`now` 会被注入，以便测试持续时间。
 - **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** 解码退出状态与结构化 stdout。退出码为 2 时，会以 stderr 内容阻止执行；其他失败不阻塞。匹配的 hook 特定权限决策会覆盖遗留顶层决策；事件判别字段不匹配或缺失只会抑制事件特定字段。顶层字段仍与事件无关，成功但非 JSON 的输出会留给桥接处理。
 - **`mergeHookOutputs(outputs)`**：折叠在一个点上匹配的每个 hook 结果：权限优先级为 **deny > ask > allow**，从首个 `continue:false` 起，halt 状态保持不变，阻塞原因用 `\n\n` 连接，`additionalContext`／`systemMessages` 按顺序累积。
-- **`createDetachedRuns()`**：跟踪以 emit 形式脱离运行的点是否完全停稳（没有 seam 等待它们）。桥接会跟踪每条运行链，包括 hook 运行及其 continuation，并将 `drain()` 注册为 effect disposer。drain 会触发 tracker 的 abort `signal`（因此仍在运行的 hook 进程会通过 `runHook` 终止，而不是等待到超时），随后在所有已跟踪链结算后 resolve。因此 `fiber.dispose()` resolve 时，不会遗留任何可能作用于已 dispose（资源释放）的上下文的脱离 hook 工作（见 [防御模式](../../../docs/defensive-patterns.md)：dispose 必须达到完全停稳）。
+- **`createDetachedRuns()`**：跟踪以 emit 形式脱离运行的点是否完全停稳（没有扩展点等待它们）。桥接会跟踪每条运行链，包括 hook 运行及其 continuation，并将 `drain()` 注册为 effect disposer。drain 会触发 tracker 的 abort `signal`（因此仍在运行的 hook 进程会通过 `runHook` 终止，而不是等待到超时），随后在所有已跟踪链结算后 resolve。因此 `fiber.dispose()` resolve 时，不会遗留任何可能作用于已 dispose（资源释放）的上下文的脱离 hook 工作（见 [防御模式](../../../docs/defensive-patterns.md)：dispose 必须达到完全停稳）。
 
 ## `hook/*` 会话事件
 
diff --git a/packages/hooks/hook-protocol/src/detached.ts b/packages/hooks/hook-protocol/src/detached.ts
index 8fa21cadf2..92eee06858 100644
--- a/packages/hooks/hook-protocol/src/detached.ts
+++ b/packages/hooks/hook-protocol/src/detached.ts
@@ -1,5 +1,5 @@
 /**
- * Quiescence tracking for emit-shaped hook runs that no seam awaits. Bridges
+ * Quiescence tracking for emit-shaped hook runs that no extension point awaits. Bridges
  * track the run plus its continuation, pass the tracker signal into execution,
  * and drain on disposal so no process or late callback outlives the fiber.
  * @module @deepseek-ai/dsh-hook-protocol/detached
diff --git a/packages/hooks/hook-protocol/src/index.ts b/packages/hooks/hook-protocol/src/index.ts
index d67746f824..68ea0b37dd 100644
--- a/packages/hooks/hook-protocol/src/index.ts
+++ b/packages/hooks/hook-protocol/src/index.ts
@@ -2,7 +2,7 @@
  * Shared, non-plugin hook protocol library: matching, command execution and
  * decoding, restrictive outcome merging, durable event helpers, and detached
  * run quiescence. Claude Code and Codex bridges own their distinct payloads,
- * environment rules, matcher mode, and typed seam mappings.
+ * environment rules, matcher mode, and typed extension-point mappings.
  * @module @deepseek-ai/dsh-hook-protocol
  */
 
diff --git a/packages/hooks/hook-protocol/src/merge.ts b/packages/hooks/hook-protocol/src/merge.ts
index c121135501..c2d25f0ab5 100644
--- a/packages/hooks/hook-protocol/src/merge.ts
+++ b/packages/hooks/hook-protocol/src/merge.ts
@@ -57,7 +57,7 @@ function decisionForRank(maxRank: number): MergedDecision {
  * yields a neutral outcome (`decision: 'none'`, no stop, empty context) — the
  * caller treats that as "no hook had anything to say".
  * @param outputs - every matched hook's decoded output, in hook order.
- * @returns the single folded outcome the bridge maps onto its seam.
+ * @returns the single folded outcome the bridge maps onto its extension point.
  */
 export function mergeHookOutputs(outputs: HookOutput[]): MergedHookOutcome {
   let maxRank = 0
diff --git a/packages/hooks/hook-protocol/src/runner.ts b/packages/hooks/hook-protocol/src/runner.ts
index 802022085e..1fa84507aa 100644
--- a/packages/hooks/hook-protocol/src/runner.ts
+++ b/packages/hooks/hook-protocol/src/runner.ts
@@ -58,7 +58,7 @@ export interface RunHookResult {
  * timeout in seconds overrides the default; trusted environment entries merge
  * after the executor scrub. Infrastructure rejection becomes an outcome with
  * no exit code, so this function never throws or crashes the calling turn.
- * @param bash - the executor seam the command runs through.
+ * @param bash - The executor service the command runs through.
  * @param hook - the configured command; its `timeoutSec` (wire unit: seconds) overrides the default timeout.
  * @param options - the invocation's payload, env, cwd, signal, stdin framing, and default timeout.
  * @param now - millisecond clock used for the reported duration.
diff --git a/packages/hooks/hook-protocol/src/types.ts b/packages/hooks/hook-protocol/src/types.ts
index 1be2b7cb04..82a67f9b93 100644
--- a/packages/hooks/hook-protocol/src/types.ts
+++ b/packages/hooks/hook-protocol/src/types.ts
@@ -1,7 +1,7 @@
 /**
  * Dialect-neutral vocabulary and log-only events shared by the Claude Code and
  * Codex hook bridges. Payload construction, matching differences, environment,
- * and seam-specific decision mapping remain owned by each bridge.
+ * and extension-point-specific decision mapping remain owned by each bridge.
  * @module @deepseek-ai/dsh-hook-protocol/types
  */
 
@@ -42,8 +42,8 @@ declare module '@deepseek-ai/dsh-session' {
 
 /**
  * The bridge that ran a hook — the CC bridge stamps `'claude'`, the Codex
- * bridge `'codex'`. A native plugin on the interception seams is not a bridge
- * and writes no `hook/*` invocation/result records (see the interception-seams Agent Note).
+ * bridge `'codex'`. A native plugin at the interception points is not a bridge
+ * and writes no `hook/*` invocation/result records (see the interception extension-points Agent Note).
  */
 export type HookDialect = 'claude' | 'codex'
 
@@ -81,7 +81,7 @@ export type MatcherMode = 'claude' | 'codex'
 /**
  * The dialect-neutral OUTCOME a hook produced, parsed from its exit code +
  * stdout JSON + stderr by {@link parseHookOutput}. A bridge maps this onto a
- * seam-specific typed Decision (PreToolDecision, PreStepDecision, …). Every field
+ * extension-point-specific typed Decision (PreToolDecision, PreStepDecision, …). Every field
  * is OPTIONAL because a hook may exercise any subset; the bridge decides which
  * fields are meaningful for its hook point and which it ignores (faithful-but-
  * degraded — e.g. Codex ignores `allow`/`ask`).
@@ -130,7 +130,7 @@ export interface HookOutput {
   systemMessage?: string
   /**
    * A tool-input rewrite a hook requested (CC `updatedInput`). PARSED but NOT
-   * honored — input rewrite is deferred (see the interception-seams Agent Note); a
+   * honored — input rewrite is deferred (see the interception extension-points Agent Note); a
    * bridge logs + warns when this is present.
    */
   updatedInput?: Record<string, unknown>
diff --git a/packages/hooks/hook-protocol/tests/runner.spec.ts b/packages/hooks/hook-protocol/tests/runner.spec.ts
index cda3a31bd4..646d7e5a17 100644
--- a/packages/hooks/hook-protocol/tests/runner.spec.ts
+++ b/packages/hooks/hook-protocol/tests/runner.spec.ts
@@ -6,7 +6,7 @@ import type { RunHookOptions } from '@deepseek-ai/dsh-hook-protocol'
 /**
  * A minimal stand-in for the bits of {@link BashExecutor} that {@link runHook}
  * actually calls (`resolve` then `run`). `runHook` is pure plumbing over those
- * two methods, so a duck-typed recorder is the right test seam — the REAL
+ * two methods, so a duck-typed recorder is the right test hook — the REAL
  * executor (dsh-bash-local) is exercised end-to-end by the hook-bridge plugins
  * that consume this library, not here.
  */
diff --git a/packages/hooks/hooks-claude/README.i18n.yaml b/packages/hooks/hooks-claude/README.i18n.yaml
index 55c8aecd2b..b69d0456c3 100644
--- a/packages/hooks/hooks-claude/README.i18n.yaml
+++ b/packages/hooks/hooks-claude/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/hooks/hooks-claude/README.md
-README.md: c97643832821746b816d80d498e8a66fbb9db895
-README.zh.md: 1562c99fc9d5c24ea3f303ea034a13efec022f77
+README.md: 77806514a9ae928ec0e6a233b0760016cad1eded
+README.zh.md: 7ba8f269eedb8791042a5cc8cff1affe35fd2920
diff --git a/packages/hooks/hooks-claude/README.md b/packages/hooks/hooks-claude/README.md
index c976438328..77806514a9 100644
--- a/packages/hooks/hooks-claude/README.md
+++ b/packages/hooks/hooks-claude/README.md
@@ -2,9 +2,9 @@
 
 English | [中文](README.zh.md)
 
-A cordis plugin that runs the supported command-hook subset of a user's existing **Claude Code** hook config (a `hooks.json`, or a settings file's `hooks` key) on the harness's canonical interception seams. It is the **CC dialect** half of the hooks subsystem: it owns the bridge's CC-shaped per-event stdin payloads, CC's env + `${CLAUDE_PLUGIN_ROOT}`/`${CLAUDE_PROJECT_DIR}` substitution, and the mapping from a hook's neutral outcome onto the harness's typed Decisions. The dialect-agnostic primitives (matcher, exit-code/stdout codec, `ctx.bash` execution, most-restrictive merge, the `hook/*` events) come from [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md).
+A cordis plugin that runs the supported command-hook subset of a user's existing **Claude Code** hook config (a `hooks.json`, or a settings file's `hooks` key) on the harness's canonical interception points. It is the **CC dialect** half of the hooks subsystem: it owns the bridge's CC-shaped per-event stdin payloads, CC's env + `${CLAUDE_PLUGIN_ROOT}`/`${CLAUDE_PROJECT_DIR}` substitution, and the mapping from a hook's neutral outcome onto the harness's typed Decisions. The dialect-agnostic primitives (matcher, exit-code/stdout codec, `ctx.bash` execution, most-restrictive merge, the `hook/*` events) come from [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md).
 
-A native cordis plugin could do everything this bridge does — more powerfully, with typed returns and no serialization boundary. **The bridge exists only as a compatibility path for the mapped CC command-hook subset**; anything bespoke should be a native plugin on the same seams (see [the interception-seams Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)).
+A native cordis plugin could do everything this bridge does — more powerfully, with typed returns and no serialization boundary. **The bridge exists only as a compatibility path for the mapped CC command-hook subset**; anything bespoke should be a native plugin on the same extension points (see [the interception extension-points Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)).
 
 ## Config
 
@@ -32,9 +32,9 @@ The config is parsed **once** at load. `configPath` is **process-level**: a rela
 
 The hooks **themselves** run in the agent's session workspace: for the agent-scoped points the bridge passes the session's `cwd` (the `session/new.cwd`) as the hook process's working directory, so a hook's `pwd`/relative-path/marker operates in the user's project tree, not the server launch dir.
 
-## Hook points → seam Decisions
+## Hook points → typed Decisions
 
-| CC hook | Harness seam | Mapping |
+| CC hook | Harness point | Mapping |
 |---|---|---|
 | `SessionStart` | `agent/session-start` (emit) | additionalContext → `agent.inject()` into the new session (cannot block) |
 | `UserPromptSubmit` | `agent/pre-step` (waterfall) | `deny` → `PreStepDecision.reject`; additionalContext-only → delegate via `next()` then append a separately sourced message to a downstream `enter` decision (a later outer listener can still reject/rewrite) |
@@ -44,7 +44,7 @@ The hooks **themselves** run in the agent's session workspace: for the agent-sco
 | `SubagentStart` | `subagent/start` (emit) | additionalContext → `agent.inject()` into a live in-process child; a remote child has no local injection target |
 | `SubagentStop` | `subagent/end` (emit) | observe-only |
 
-The three emit points run detached — no seam awaits a `SessionStart`/`SubagentStart`/`SubagentStop` hook. Each run chain is tracked, and disposing the bridge aborts still-running hook processes, then drains the continuations before the dispose resolves (`createDetachedRuns` in `dsh-hook-protocol`).
+The three emit points run detached — no extension point awaits a `SessionStart`/`SubagentStart`/`SubagentStop` hook. Each run chain is tracked, and disposing the bridge aborts still-running hook processes, then drains the continuations before the dispose resolves (`createDetachedRuns` in `dsh-hook-protocol`).
 
 The matcher subject is the tool name (`PreToolUse`/`PostToolUse`), the session source (`SessionStart`), or a constant `agent_type` of `general-purpose` (`SubagentStart`/`SubagentStop` — the harness subagent seam carries no per-kind label, so the bridge reports Claude Code's own Task-tool default; a default/`*`/empty `agent_type` matcher fires, a specific-kind matcher does not); `UserPromptSubmit`/`Stop` ignore matchers. Multiple file-configured hooks on one point run **serially, in config order**, and fold most-restrictively (`deny > ask > allow`, see `dsh-hook-protocol`); serial keeps each hook's `hook/invoked`/`hook/result` pair adjacent in the log, and the fold is order-independent for the decision (see the Agent Note's "run serially, not concurrently" note).
 
diff --git a/packages/hooks/hooks-claude/README.zh.md b/packages/hooks/hooks-claude/README.zh.md
index 1562c99fc9..7ba8f269ee 100644
--- a/packages/hooks/hooks-claude/README.zh.md
+++ b/packages/hooks/hooks-claude/README.zh.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-一个 Cordis 插件，在 harness 的规范拦截 seam 上运行用户现有 **Claude Code** hook 配置（`hooks.json` 或 settings 文件的 `hooks` key）中受支持的 command hook 子集。它是 hooks 子系统的 **CC 方言**部分，负责桥接中 CC 格式的逐事件 stdin payload、CC 的 env 和 `${CLAUDE_PLUGIN_ROOT}`／`${CLAUDE_PROJECT_DIR}` 替换，以及将 hook 的中性结果映射为 harness 的类型化 Decision。方言无关原语（matcher、退出码／stdout codec、`ctx.bash` 执行、最严格合并、`hook/*` 事件）来自 [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md)。
+一个 Cordis 插件，在 harness 的规范拦截点上运行用户现有 **Claude Code** hook 配置（`hooks.json` 或 settings 文件的 `hooks` key）中受支持的 command hook 子集。它是 hooks 子系统的 **CC 方言**部分，负责桥接中 CC 格式的逐事件 stdin payload、CC 的 env 和 `${CLAUDE_PLUGIN_ROOT}`／`${CLAUDE_PROJECT_DIR}` 替换，以及将 hook 的中性结果映射为 harness 的类型化 Decision。方言无关原语（matcher、退出码／stdout codec、`ctx.bash` 执行、最严格合并、`hook/*` 事件）来自 [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md)。
 
-原生 Cordis 插件可以完成此桥接的所有工作，功能更强，且具有类型化返回，没有序列化边界。**该桥接只是已映射 CC command hook 子集的兼容路径**；所有定制行为都应当使用相同 seam 上的原生插件（见 [拦截 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)）。
+原生 Cordis 插件可以完成此桥接的所有工作，功能更强，且具有类型化返回，没有序列化边界。**该桥接只是已映射 CC command hook 子集的兼容路径**；所有定制行为都应当使用相同扩展点上的原生插件（见 [拦截扩展点 Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)）。
 
 ## 配置
 
@@ -32,9 +32,9 @@ const config: Config = {
 
 hook **本身**会在 agent 的会话工作区中运行：对 agent scope 点，桥接会将会话 `cwd`（`session/new.cwd`）作为 hook 进程工作目录，因此 hook 的 `pwd`／相对路径／marker 作用于用户项目树，而非服务器启动目录。
 
-## Hook 点 → seam Decision
+## Hook 点 → 类型化 Decision
 
-| CC hook | Harness seam | 映射 |
+| CC hook | Harness 点 | 映射 |
 |---|---|---|
 | `SessionStart` | `agent/session-start`（emit） | additionalContext → `agent.inject()` 到新会话（无法阻塞） |
 | `UserPromptSubmit` | `agent/pre-step`（waterfall，瀑布式事件） | `deny` → `PreStepDecision.reject`；仅 additionalContext → 通过 `next()` 委托，再向下游 `enter` 决策追加一条单独标记来源的消息（后续外层 listener 仍可 reject／改写） |
@@ -44,7 +44,7 @@ hook **本身**会在 agent 的会话工作区中运行：对 agent scope 点，
 | `SubagentStart` | `subagent/start`（emit） | additionalContext → `agent.inject()` 到仍在运行的同进程 child；远程 child 没有本地注入目标 |
 | `SubagentStop` | `subagent/end`（emit） | 只观测 |
 
-三个 emit 点都以分离方式运行：没有 seam 会等待 `SessionStart`／`SubagentStart`／`SubagentStop` hook。每条运行链都会被跟踪；对桥接执行 dispose（资源释放）时，会中止仍在运行的 hook 进程，并在 dispose 完成前排空 continuation（`createDetachedRuns`，位于 `dsh-hook-protocol`）。
+三个 emit 点都以分离方式运行：没有扩展点会等待 `SessionStart`／`SubagentStart`／`SubagentStop` hook。每条运行链都会被跟踪；对桥接执行 dispose（资源释放）时，会中止仍在运行的 hook 进程，并在 dispose 完成前排空 continuation（`createDetachedRuns`，位于 `dsh-hook-protocol`）。
 
 matcher subject 是工具名称（`PreToolUse`／`PostToolUse`）、会话源（`SessionStart`），或常量 `agent_type`，其值为 `general-purpose`（`SubagentStart`／`SubagentStop`）。harness subagent seam 不携带每 kind label，因此桥接报告 Claude Code 自身 Task 工具默认值；默认／`*`／空 `agent_type` matcher 会触发，特定 kind matcher 不会触发。`UserPromptSubmit`／`Stop` 忽略 matcher。一个点上文件配置的多个 hook 会**按配置顺序串行运行**，并按最严格方式折叠（`deny > ask > allow`，见 `dsh-hook-protocol`）。串行使每个 hook 的 `hook/invoked`／`hook/result` 对在日志中相邻，决策折叠与顺序无关（见 Agent Note 的「run serially, not concurrently」说明）。
 
diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts
index e42f875f13..39802d0b6c 100644
--- a/packages/hooks/hooks-claude/src/index.ts
+++ b/packages/hooks/hooks-claude/src/index.ts
@@ -1,10 +1,10 @@
 /**
  * Bridge for unmodified Claude Code command hooks on harness interception
- * seams. It supports SessionStart, prompt/tool pre/post, Stop, and subagent
+ * extension points. It supports SessionStart, prompt/tool pre/post, Stop, and subagent
  * start/stop. It owns Claude payloads, environment, substitution, and decision
  * mapping; shared execution and parsing live in `dsh-hook-protocol`.
  * `updatedInput` is logged and warned but not honored. Bespoke behavior should
- * use typed native plugins on the same seams; see the
+ * use typed native plugins on the same extension points; see the
  * [hook-bridges Agent Note](../../../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md).
  * @module @deepseek-ai/dsh-hooks-claude
  */
@@ -38,7 +38,7 @@ import { parseClaudeConfig, type ClaudeHookConfig } from './config.ts'
 
 export const name = 'hooks-claude'
 // `bash` is required to run hooks; the rest are read opportunistically via
-// ctx.get so a deployment can load this bridge without every seam present.
+// ctx.get so a deployment can load this bridge without every extension point present.
 export const inject = ['bash']
 
 /** Plugin config: where the CC hook config lives + substitution roots. */
@@ -130,7 +130,7 @@ export function apply(ctx: Context, config: Config): void {
    * `matchQuery`, with the per-event `payload` on stdin, and fold the results.
    * Writes a `hook/invoked`/`hook/result` pair per hook when `opts.turn` names
    * an open turn. Detached lifecycle points omit the pair. Returns the merged outcome (a neutral,
-   * already-most-restrictive view) for the caller to map onto its seam
+   * already-most-restrictive view) for the caller to map onto its extension point
    * decision. `matchQuery` is the event's matcher subject (tool name, session
    * source, …); `''` for events that ignore matchers.
    */
@@ -186,7 +186,7 @@ export function apply(ctx: Context, config: Config): void {
     return mergeHookOutputs(outputs)
   }
 
-  // TODO(hook-continue-false): `merged.stop` is logged but needs a run-level halt seam.
+  // TODO(hook-continue-false): `merged.stop` is logged but needs a run-level halt mechanism.
 
   /** Build additional model context from hook output, or return undefined when empty. */
   function contextFrom(merged: MergedHookOutcome): UserMessage | undefined {
@@ -310,7 +310,7 @@ const SUBAGENT_TYPE = 'general-purpose'
 function lastTurn(agent: Agent | undefined): number {
   if (!agent) return 0
   const last = [...agent.session.events].findLast(e => e.type === 'turn/start')
-  /* v8 ignore next -- agent-present callers are tool/stop seams inside an open turn. */
+  /* v8 ignore next -- agent-present callers are tool/stop extension points inside an open turn. */
   return last?.type === 'turn/start' ? last.data.turn : 0
 }
 
diff --git a/packages/hooks/hooks-claude/tests/coverage-cases.ts b/packages/hooks/hooks-claude/tests/coverage-cases.ts
index b7ea693583..c82f0320f3 100644
--- a/packages/hooks/hooks-claude/tests/coverage-cases.ts
+++ b/packages/hooks/hooks-claude/tests/coverage-cases.ts
@@ -416,7 +416,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
 
   if (group === 'context') describe('hooks-claude coverage — continue:false, context arm, no-cwd', () => {
     it('a {"continue":false} hook is RECORDED as decision "stop" but does not halt the run (TODO(hook-continue-false))', async () => {
-    // The seams cannot yet honor `continue:false` as a hard halt. The log must still record the
+    // The extension points cannot yet honor `continue:false` as a hard halt. The log must still record the
     // stop decision while execution and the turn continue normally.
       const d = dir()
       const s = sh(d, 'stop.sh', '#!/usr/bin/env bash\necho \'{"continue":false,"stopReason":"halt"}\'\n')
diff --git a/packages/hooks/hooks-codex/README.i18n.yaml b/packages/hooks/hooks-codex/README.i18n.yaml
index 212192df3c..4af0518ab2 100644
--- a/packages/hooks/hooks-codex/README.i18n.yaml
+++ b/packages/hooks/hooks-codex/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/hooks/hooks-codex/README.md
-README.md: 60dd1d098966aad6ccdb0957ee223b9843db499f
-README.zh.md: 80162e9fb82eb0f9e358c3d14bd24bf4bfeddaca
+README.md: f8e0684e0bf4eafadcb31d8c82dde177411db2bf
+README.zh.md: d278e78204c1bd320980420b506135997cd3a4cc
diff --git a/packages/hooks/hooks-codex/README.md b/packages/hooks/hooks-codex/README.md
index 60dd1d0989..f8e0684e0b 100644
--- a/packages/hooks/hooks-codex/README.md
+++ b/packages/hooks/hooks-codex/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-A cordis plugin that runs the supported subset of a user's existing **Codex** hook config on the harness's canonical interception seams. The **Codex dialect** half of the hooks subsystem. The dialect-agnostic primitives come from [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md); this bridge owns the Codex-shaped payloads, matcher mode, and decision mapping.
+A cordis plugin that runs the supported subset of a user's existing **Codex** hook config on the harness's canonical interception points. The **Codex dialect** half of the hooks subsystem. The dialect-agnostic primitives come from [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md); this bridge owns the Codex-shaped payloads, matcher mode, and decision mapping.
 
 This bridge implements a deliberate subset of Codex's current hook protocol:
 
@@ -12,7 +12,7 @@ This bridge implements a deliberate subset of Codex's current hook protocol:
 - **No Codex plugin env injection and no config-time placeholder substitution** (the command still receives the executor's environment and runs through its shell).
 - **No pre-tool approval or rewrite path** — a hook can block, but the bridge does not pre-approve or replace tool input.
 
-A native cordis plugin could do everything this bridge does, more powerfully; the bridge exists only as a compatibility path for the mapped Codex subset (see [the interception-seams Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)).
+A native cordis plugin could do everything this bridge does, more powerfully; the bridge exists only as a compatibility path for the mapped Codex subset (see [the interception extension-points Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)).
 
 ## Config
 
@@ -38,9 +38,9 @@ The config is parsed **once** at load. `configPath` is **process-level** — a r
 
 The hooks themselves run in the agent's session workspace: for the agent-scoped points the bridge passes the session's `cwd` as the hook process's working directory, so a hook operates in the user's project tree, not the server launch dir.
 
-## Hook points → seam Decisions
+## Hook points → typed Decisions
 
-| Codex hook | Harness seam | Mapping |
+| Codex hook | Harness point | Mapping |
 |---|---|---|
 | `SessionStart` | `agent/session-start` (emit) | a plain-stdout hook's output → additionalContext → `agent.inject()` |
 | `UserPromptSubmit` | `agent/pre-step` (waterfall) | `block` (exit 2) → `PreStepDecision.reject`; additionalContext-only → delegate via `next()` then append a separately sourced message to a downstream `enter` decision |
diff --git a/packages/hooks/hooks-codex/README.zh.md b/packages/hooks/hooks-codex/README.zh.md
index 80162e9fb8..d278e78204 100644
--- a/packages/hooks/hooks-codex/README.zh.md
+++ b/packages/hooks/hooks-codex/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个 Cordis 插件，在 harness 的规范拦截 seam 上运行用户现有 **Codex** hook 配置的受支持子集。它是 hooks 子系统中采用 **Codex 方言** 的一侧。方言无关原语来自 [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md)；该桥接负责处理 Codex 形状的 payload、matcher 模式和决策映射。
+一个 Cordis 插件，在 harness 的规范拦截点上运行用户现有 **Codex** hook 配置的受支持子集。它是 hooks 子系统中采用 **Codex 方言** 的一侧。方言无关原语来自 [`@deepseek-ai/dsh-hook-protocol`](../hook-protocol/README.md)；该桥接负责处理 Codex 形状的 payload、matcher 模式和决策映射。
 
 该桥接实现 Codex 当前 hook 协议的一个明确子集：
 
@@ -12,7 +12,7 @@
 - **没有 Codex 插件 env 注入，也没有配置时 placeholder 替换**（命令仍会接收执行器环境，并通过其 shell 运行）。
 - **没有工具前审批或改写路径**：hook 可以阻塞，但桥接不会预审批或替换工具输入。
 
-原生 Cordis 插件可以完成此桥接的所有工作，并且功能更强；该桥接只是已映射 Codex 子集的兼容路径（见 [拦截 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-seams.md)）。
+原生 Cordis 插件可以完成此桥接的所有工作，并且功能更强；该桥接只是已映射 Codex 子集的兼容路径（见 [拦截扩展点 Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)）。
 
 ## 配置
 
@@ -38,9 +38,9 @@ const config: Config = {
 
 hook 本身会在 agent（智能体）的会话工作区中运行：对 agent scope 点，桥接会将会话 `cwd` 作为 hook 进程工作目录，因此 hook 作用于用户项目树，而非服务器启动目录。
 
-## Hook 点 → seam Decision
+## Hook 点 → 类型化 Decision
 
-| Codex hook | Harness seam | 映射 |
+| Codex hook | Harness 点 | 映射 |
 |---|---|---|
 | `SessionStart` | `agent/session-start`（emit） | 纯 stdout hook 的输出 → additionalContext → `agent.inject()` |
 | `UserPromptSubmit` | `agent/pre-step`（waterfall，瀑布式事件） | `block`（退出码 2）→ `PreStepDecision.reject`；仅 additionalContext → 通过 `next()` 委托，再向下游 `enter` 决策追加一条单独标记来源的消息 |
diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts
index 873b1e35ae..34f47f5a7e 100644
--- a/packages/hooks/hooks-codex/src/index.ts
+++ b/packages/hooks/hooks-codex/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Bridge for unmodified Codex command hooks on harness interception seams. It
+ * Bridge for unmodified Codex command hooks on harness interception points. It
  * supports five points (SessionStart, prompt/tool pre/post, Stop), regex-only
  * matchers, snake_case payloads without a trailing newline, no hook environment
  * or command substitution, and no pre-tool approval or rewrite path; only
@@ -156,7 +156,7 @@ export function apply(ctx: Context, config: Config): void {
         }
         outputs.push(output)
         // Execution and decision mapping remain in each bridge so dialect
-        // differences stay explicit at their owning seam.
+        // differences stay explicit at their owning extension point.
         /* jscpd:ignore-start */
         if (output.systemMessage !== undefined) {
           ctx.logger.warn(`hooks-codex: ${point} hook emitted a systemMessage, which is not yet surfaced (ignored)`)
@@ -169,7 +169,7 @@ export function apply(ctx: Context, config: Config): void {
     return mergeHookOutputs(outputs)
   }
 
-  // TODO(hook-continue-false): `merged.stop` is logged but needs a run-level halt seam.
+  // TODO(hook-continue-false): `merged.stop` is logged but needs a run-level halt mechanism.
 
   function contextFrom(merged: MergedHookOutcome): UserMessage | undefined {
     if (merged.additionalContext.length === 0) return undefined
@@ -279,7 +279,7 @@ export function apply(ctx: Context, config: Config): void {
 function lastTurn(agent: Agent | undefined): number {
   if (!agent) return 0
   const last = [...agent.session.events].findLast(e => e.type === 'turn/start')
-  /* v8 ignore next -- agent-present turnBase callers are tool/stop seams inside an open turn. */
+  /* v8 ignore next -- agent-present turnBase callers are tool/stop extension points inside an open turn. */
   return last?.type === 'turn/start' ? last.data.turn : 0
 }
 
diff --git a/packages/hooks/hooks-codex/tests/coverage-cases.ts b/packages/hooks/hooks-codex/tests/coverage-cases.ts
index 942feaaa05..d92ea597bd 100644
--- a/packages/hooks/hooks-codex/tests/coverage-cases.ts
+++ b/packages/hooks/hooks-codex/tests/coverage-cases.ts
@@ -395,7 +395,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
     })
 
     it('a {"continue":false} hook is RECORDED as "stop" but does not halt the run (TODO(hook-continue-false))', async () => {
-    // Honoring `continue:false` is deferred — the seams have no hard-halt
+    // Honoring `continue:false` is deferred — the extension points have no hard-halt
     // primitive. Assert the LOG records the halt request AND that the run is not
     // actually halted (the tool still runs, the turn completes).
       const d = dir()
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index fde6cd32ee..d0f3698328 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -811,7 +811,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
   }
 
   // Projection change feed → session/projection push frames. The carrier
-  // mints the wire frame (the seam package holds no wire vocabulary); the
+  // mints the wire frame (the Service Definition package holds no wire vocabulary); the
   // child activates only when a projection registry is composed, and the
   // subscription unwinds with this gateway's fiber.
   ctx.inject(['sessionProjections'], (projectionCtx) => {
@@ -1319,7 +1319,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     return { code: 'internal', message: 'credentials service is absent: this deployment does not mount a credential provider (e.g. @deepseek-ai/dsh-credentials-local) in its composition', details: {} }
   }
 
-  /** Map one redacted seam descriptor to its wire view. */
+  /** Map one redacted settings descriptor to its wire view. */
   function namespaceView(descriptor: SettingsDescriptor): SettingsNamespaceView {
     return {
       ns: String(descriptor.ns),
@@ -2048,7 +2048,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       // the Web picker collapsed onto the directory flow
       // (.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md).
       // Delete it with the wire schema's `name` member, this
-      // `defaults.workspaceRoot`, the client seam that carried the name
+      // `defaults.workspaceRoot`, the client contract that carried the name
       // (`WorkspaceCreateInput`, `WorkspacesService.create`'s `{ name }` arm,
       // `intentName`'s name branch, the manager's "name under workspaceRoot"
       // contract), and the `dsh web --workspace-root` flag plus its apps/cli
diff --git a/packages/host/apiproxy/src/api/events.ts b/packages/host/apiproxy/src/api/events.ts
index 7fc54f6f01..bf2f694eca 100644
--- a/packages/host/apiproxy/src/api/events.ts
+++ b/packages/host/apiproxy/src/api/events.ts
@@ -49,7 +49,7 @@ export interface EventsApi {
    * attached session, then replays each session's still-pending approval/question requested
    * frames (rpcId reused verbatim — the refresh-recovery baseline). Session titles ride the
    * generic projection pair (history-tail projections block + session/projection frames).
-   * since: resume seam, unimplemented in v1 (ignored if passed); reconnection = reopen the
+   * since: resume hook, unimplemented in v1 (ignored if passed); reconnection = reopen the
    * stream + refetch history.
    */
   mux(request: RpcRequest<{ since?: Record<SessionId, number> }>, signal: AbortSignal): AsyncIterable<RpcRequest<MuxFrame>>
diff --git a/packages/host/apiproxy/src/native-path-opener.ts b/packages/host/apiproxy/src/native-path-opener.ts
index bc75460236..6d8d3e0170 100644
--- a/packages/host/apiproxy/src/native-path-opener.ts
+++ b/packages/host/apiproxy/src/native-path-opener.ts
@@ -157,7 +157,7 @@ async function openNativePathWithIntent(
  * with the default browser when the path names a document a browser renders.
  * @param path - absolute or host-resolvable path (caller owns resolution).
  * @param signal - caller/connection lifetime; abort terminates the native command.
- * @param internals - platform, environment, and runner seam for deterministic tests.
+ * @param internals - Platform, environment, and runner hooks for deterministic tests.
  */
 export function openNativePath(
   path: string,
@@ -172,7 +172,7 @@ export function openNativePath(
  * so a YAML association with a browser cannot consume the gesture.
  * @param path - absolute or host-resolvable text-document path.
  * @param signal - caller/connection lifetime; abort terminates the native command.
- * @param internals - platform and runner seam for deterministic tests.
+ * @param internals - Platform and runner hooks for deterministic tests.
  */
 export function openNativeTextFile(
   path: string,
diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
index be76bf4cc6..4449df15f6 100644
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -518,7 +518,7 @@ describe('sessions.prompt synchronous rejection', () => {
     await ctx.plugin(UserInteractionService)
     const session = ctx.sessions.create(sid('session-throwing'))
     // A live structural stub whose delivery verbs throw synchronously, the
-    // shape a disposed loop presents at this seam.
+    // shape a disposed loop presents at this gateway boundary.
     ctx.agents.register({
       id: session.id,
       session,
diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
index 0beb7455cf..13968616b8 100644
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -44,7 +44,7 @@ function expectErr<T>(response: RpcResponse<T>): { code: string; message: string
   return response.result.error
 }
 
-/** In-memory settings provider: the seam base class owns all tested behavior. */
+/** In-memory settings provider: the Service Definition base class owns all tested behavior. */
 class MemorySettings extends Settings {
   doc: Record<string, unknown>
 
diff --git a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
index 7542d328ba..5e46e4b212 100644
--- a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
@@ -91,7 +91,7 @@ function bench(options: {
     locate: () => undefined,
   })
   // The gateway's own projection push feed subscribes at construction; the
-  // no-op disposer keeps that seam quiet while these tests pin history reads.
+  // no-op disposer keeps that feed quiet while these tests pin history reads.
   ctx.provide('sessionProjections', { snapshot, restore, onChanged: () => () => {} })
   ctx.provide('userInteraction', { registerProvider: () => () => {} })
   const api = createApiProxy(ctx, {
diff --git a/packages/host/directory-picker-native/src/native-picker.ts b/packages/host/directory-picker-native/src/native-picker.ts
index e25b04ce6c..576353ea8c 100644
--- a/packages/host/directory-picker-native/src/native-picker.ts
+++ b/packages/host/directory-picker-native/src/native-picker.ts
@@ -42,7 +42,7 @@ function rethrowIfAborted(signal: AbortSignal, error: unknown): void {
 /**
  * Open the platform directory picker.
  * @param signal - caller/connection lifetime; abort terminates the native command.
- * @param internals - platform and runner seam for deterministic tests.
+ * @param internals - Platform and runner hooks for deterministic tests.
  * @returns the selected path, or null when the user cancels.
  */
 export async function pickNativeDirectory(
diff --git a/packages/host/directory-picker-native/src/win32-dialog-logic.ts b/packages/host/directory-picker-native/src/win32-dialog-logic.ts
index aa9d1445c4..9ce2b42464 100644
--- a/packages/host/directory-picker-native/src/win32-dialog-logic.ts
+++ b/packages/host/directory-picker-native/src/win32-dialog-logic.ts
@@ -1,6 +1,6 @@
 /**
  * Pure sequencing of the Win32 `IFileOpenDialog` folder-picker COM
- * conversation over an injectable bindings seam, so every outcome path
+ * conversation over injectable platform bindings, so every outcome path
  * (selection, cancellation, HRESULT failure, cleanup ordering) is testable on
  * any platform. The koffi-backed bindings live in
  * `win32-dialog-bindings.ts`, which only a real win32 process ever loads.
diff --git a/packages/host/directory-picker-native/src/win32-dialog.ts b/packages/host/directory-picker-native/src/win32-dialog.ts
index 247d9a1733..cb8a492faa 100644
--- a/packages/host/directory-picker-native/src/win32-dialog.ts
+++ b/packages/host/directory-picker-native/src/win32-dialog.ts
@@ -60,7 +60,7 @@ function assertNever(value: never): never {
 /**
  * Open the modern Win32 folder picker off the event loop.
  * @param signal - caller lifetime; abort closes the dialog and rejects.
- * @param internals - worker/window seams for deterministic tests.
+ * @param internals - Worker/window hooks for deterministic tests.
  * @returns the selected path, or null when the user cancels.
  */
 export async function pickWin32Directory(
diff --git a/packages/host/directory-picker/src/index.ts b/packages/host/directory-picker/src/index.ts
index 4dba9c9c22..4a0a831247 100644
--- a/packages/host/directory-picker/src/index.ts
+++ b/packages/host/directory-picker/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The `ctx.directoryPicker` seam: how the web-GUI host lets an operator
+ * Service Definition for the `ctx.directoryPicker` capability seam: how the web-GUI host lets an operator
  * select a workspace directory. Backends differ in interaction shape, not
  * just mechanism, so the service exposes a discriminated capability instead
  * of one method set: a `native` backend opens one OS chooser on the
diff --git a/packages/host/directory-picker/src/invariant.ts b/packages/host/directory-picker/src/invariant.ts
index 9128850f3b..05638bd0cf 100644
--- a/packages/host/directory-picker/src/invariant.ts
+++ b/packages/host/directory-picker/src/invariant.ts
@@ -10,7 +10,10 @@ export const name = 'host-directory-picker-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
-/** No runtime invariant: this stateless seam owns the capability vocabulary, while backends and the RPC consumer own observations. */
+/**
+ * No runtime invariant: this stateless Service Definition owns the capability
+ * vocabulary, while backends and the RPC consumer own observations.
+ */
 const install: InvariantInstaller = () => {}
 
 /**
diff --git a/packages/host/webserver/src/index.ts b/packages/host/webserver/src/index.ts
index a536f9e1f5..fbd275eeed 100644
--- a/packages/host/webserver/src/index.ts
+++ b/packages/host/webserver/src/index.ts
@@ -3,7 +3,7 @@
  * server plus the `httpServer` service (HTTP and upgrade route registries,
  * index transform taps, and the single fallback seat for everything no route
  * claims). Knows no harness concepts and serves no files; the composing
- * application's frontend plugin owns dist serving through the fallback seam.
+ * application's frontend plugin owns dist serving through the fallback hook.
  * Web shape only — Electron loads dist over file:// and carries fetch over an
  * IPC bridge. This package never prints: the URL line belongs to the shell.
  */
diff --git a/packages/interaction/README.i18n.yaml b/packages/interaction/README.i18n.yaml
index 5c99feeaf3..d8b76378eb 100644
--- a/packages/interaction/README.i18n.yaml
+++ b/packages/interaction/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/interaction/README.md
-README.md: a72cd48bb1d3ec15b1116d576fac86619df59528
-README.zh.md: 03fab9c4ce4479b3ab82f372f14f4d4208d7de04
+README.md: 8fe77ae845390359e2c1e3302400c08828a186a1
+README.zh.md: 68e13be7c55e64305bbe0b87ede8d37e55a7cd36
diff --git a/packages/interaction/README.md b/packages/interaction/README.md
index a72cd48bb1..8fe77ae845 100644
--- a/packages/interaction/README.md
+++ b/packages/interaction/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The seams through which a human collaborates with a running agent — questions, approvals, permission presets, commands. These are **product** packages: real interfaces a person drives.
+The services and plugins through which a human collaborates with a running agent — questions, approvals, permission presets, commands. These are **product** packages: real interfaces a person drives.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/interaction/README.zh.md b/packages/interaction/README.zh.md
index 03fab9c4ce..68e13be7c5 100644
--- a/packages/interaction/README.zh.md
+++ b/packages/interaction/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-人与运行中的 agent（智能体）协作所经由的各个 seam——提问、审批、权限预设、命令。这些是**产品**包（package）：由用户直接操作的真实接口。
+人与运行中的 agent（智能体）协作所经由的服务与插件——提问、审批、权限预设、命令。这些是**产品**包（package）：由用户直接操作的真实接口。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
diff --git a/packages/interaction/tool-ask-user/README.i18n.yaml b/packages/interaction/tool-ask-user/README.i18n.yaml
index 4feb6f3b0f..c6fefae1ed 100644
--- a/packages/interaction/tool-ask-user/README.i18n.yaml
+++ b/packages/interaction/tool-ask-user/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/interaction/tool-ask-user/README.md
-README.md: 7af356263ea6582a081e7c6de22fd317ca8b96df
-README.zh.md: 5e5e8f2a8208c003c68ce1f3992c0bd34f2cb552
+README.md: bb0af4286d6d0626596202d57e55fd818b92f44b
+README.zh.md: 1a8c7ceec56a0d5a4ed25793b306d2b5d9e8a526
diff --git a/packages/interaction/tool-ask-user/README.md b/packages/interaction/tool-ask-user/README.md
index 7af356263e..bb0af4286d 100644
--- a/packages/interaction/tool-ask-user/README.md
+++ b/packages/interaction/tool-ask-user/README.md
@@ -19,7 +19,7 @@ The tool calls `ctx.userInteraction.ask()` and returns canonical `{ answers: [{
 
 ## Role
 
-This is the consumer package for the user-interaction seam. It does not render UI and does not know how input is collected; it only translates model arguments into `AskUserQuestionRequest` and returns the human answer to the agent loop.
+This is the Consumer package for the user-interaction seam. It does not render UI and does not know how input is collected; it only translates model arguments into `AskUserQuestionRequest` and returns the human answer to the agent loop.
 
 ## Model Experience
 
diff --git a/packages/interaction/tool-ask-user/README.zh.md b/packages/interaction/tool-ask-user/README.zh.md
index 5e5e8f2a82..1a8c7ceec5 100644
--- a/packages/interaction/tool-ask-user/README.zh.md
+++ b/packages/interaction/tool-ask-user/README.zh.md
@@ -19,7 +19,7 @@
 
 ## 职责
 
-此包是用户交互 seam 的消费方。它不渲染 UI，也不了解输入的收集方式；它只将模型参数转换为 `AskUserQuestionRequest`，并把用户回答返回给 agent loop（智能体循环）。
+此包是用户交互 seam 的 Consumer 包。它不渲染 UI，也不了解输入的收集方式；它只将模型参数转换为 `AskUserQuestionRequest`，并把用户回答返回给 agent loop（智能体循环）。
 
 ## 模型体验
 
diff --git a/packages/interaction/tool-ask-user/src/index.ts b/packages/interaction/tool-ask-user/src/index.ts
index f908bdad4d..ccfdefe6d3 100644
--- a/packages/interaction/tool-ask-user/src/index.ts
+++ b/packages/interaction/tool-ask-user/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Model-facing `ask_user_question` tool over the `ctx.userInteraction` seam.
+ * Model-facing Consumer of the `ctx.userInteraction` capability seam.
  * The tool pauses until a UI provider returns a human answer, then feeds that
  * answer back into the agent loop as an ordinary tool result.
  *
diff --git a/packages/interaction/user-approval/src/index.ts b/packages/interaction/user-approval/src/index.ts
index 6af9de6428..3dfeabe570 100644
--- a/packages/interaction/user-approval/src/index.ts
+++ b/packages/interaction/user-approval/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Approval request, cancellation, audit, and per-session policy seam. Missing
+ * Service Definition for the approval capability seam, covering requests, cancellation, audit, and per-session policy. Missing
  * answerers fail closed; grants apply only to the requested action.
  * @module @deepseek-ai/dsh-user-approval
  */
diff --git a/packages/interaction/user-interaction/README.i18n.yaml b/packages/interaction/user-interaction/README.i18n.yaml
index 6326ea0dee..4537cfd7da 100644
--- a/packages/interaction/user-interaction/README.i18n.yaml
+++ b/packages/interaction/user-interaction/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/interaction/user-interaction/README.md
-README.md: cba015e782623b3a5adf018303823577a0b96774
-README.zh.md: acfacd1cef8150d6995d5c6285b5a331310fb89b
+README.md: cf000dd59754dfe2f14395c33384bad5bda76910
+README.zh.md: 67167649e29afe99667ab6c863127d27d4bceb48
diff --git a/packages/interaction/user-interaction/README.md b/packages/interaction/user-interaction/README.md
index cba015e782..cf000dd597 100644
--- a/packages/interaction/user-interaction/README.md
+++ b/packages/interaction/user-interaction/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a model-facing tool or permission plugin uses when it needs to pause work and ask the human for a decision.
+User-interaction Service Definition. It owns `ctx.userInteraction`, the service a model-facing tool or permission plugin uses when it needs to pause work and ask the human for a decision.
 
 ## Service: `UserInteractionService` (ctx key: `userInteraction`)
 
@@ -30,7 +30,7 @@ When a request carries an agent, `ask()` authenticates its exact identity throug
 
 ## Role
 
-This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this seam; the Web host runtime provides the shipped interactive implementation. The loop stays unchanged: a tool call awaits a promise, and the tool result resumes the normal agent loop.
+This is the Service Definition package. Consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this service; the Web host runtime supplies the shipped Service provider. The loop stays unchanged: a tool call awaits a promise, and the tool result resumes the normal agent loop.
 
 ## Model Experience
 
diff --git a/packages/interaction/user-interaction/README.zh.md b/packages/interaction/user-interaction/README.zh.md
index acfacd1cef..67167649e2 100644
--- a/packages/interaction/user-interaction/README.zh.md
+++ b/packages/interaction/user-interaction/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-抽象用户交互 seam。它定义 `ctx.userInteraction`，供面向模型的工具或权限插件在需要暂停工作并询问人类决定时使用。
+用户交互 Service Definition。它定义 `ctx.userInteraction`，供面向模型的工具或权限插件在需要暂停工作并询问人类决定时使用。
 
 ## 服务：`UserInteractionService`（ctx 键：`userInteraction`）
 
@@ -30,7 +30,7 @@
 
 ## 职责
 
-这是接口包。`@deepseek-ai/dsh-tool-ask-user` 等面向模型的消费方依赖此 seam；Web 宿主运行时提供随产品交付的交互式实现。循环保持不变：工具调用等待 Promise，工具结果随后恢复正常的 agent loop（智能体循环）。
+这是 Service Definition 包。`@deepseek-ai/dsh-tool-ask-user` 等 Consumer 依赖此服务；Web 宿主运行时提供随产品交付的 Service provider。循环保持不变：工具调用等待 Promise，工具结果随后恢复正常的 agent loop（智能体循环）。
 
 ## 模型体验
 
diff --git a/packages/interaction/user-interaction/src/index.ts b/packages/interaction/user-interaction/src/index.ts
index 761db57c65..82ab06e25b 100644
--- a/packages/interaction/user-interaction/src/index.ts
+++ b/packages/interaction/user-interaction/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * User-interaction seam (`ctx.userInteraction`): a UI-backed service for
+ * Service Definition for the user-interaction capability seam (`ctx.userInteraction`): a UI-backed service for
  * pausing an agent tool call until the human answers a question. The model-
  * facing tool lives in `@deepseek-ai/dsh-tool-ask-user`; UI packages provide
  * the single active provider.
diff --git a/packages/llm/README.i18n.yaml b/packages/llm/README.i18n.yaml
index a8bc82817f..3feb8a9e79 100644
--- a/packages/llm/README.i18n.yaml
+++ b/packages/llm/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/llm/README.md
-README.md: 077ae600c89cff80cd71830e37bda00707c1d837
-README.zh.md: 46d4aa8a6088b3d5f40718f0c2626783e6c05c4b
+README.md: 15f90024abf3256560d67099af79be7d4e0ee310
+README.zh.md: 5f733808ddd591f10e4f2ed437a3f59db3bfb679
diff --git a/packages/llm/README.md b/packages/llm/README.md
index 077ae600c8..15f90024ab 100644
--- a/packages/llm/README.md
+++ b/packages/llm/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The LLM seam and its provider adapters. The interface package (`llm`) owns the abstract service, the content-block vocabulary, and the stream-chunk assembler; the adapters are concrete implementations that register on `ctx.llm`. All **product** packages.
+The LLM seam and its provider adapters. The `llm` package owns both the Service Definition and Consumer roles: the abstract service, content-block vocabulary, and stream-chunk assembler. Provider adapters register on `ctx.llm`. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/llm/README.zh.md b/packages/llm/README.zh.md
index 46d4aa8a60..5f733808dd 100644
--- a/packages/llm/README.zh.md
+++ b/packages/llm/README.zh.md
@@ -1,8 +1,8 @@
-# llm/ — LLM（大语言模型）能力家族
+# llm/ — LLM 能力家族
 
 [English](README.md) | 中文
 
-LLM seam 及其提供方适配器。接口包（`llm`）负责抽象服务、内容块词汇和流式分片组装器；适配器是注册到 `ctx.llm` 的具体实现。这些全是**产品**包。
+LLM（大语言模型）seam 及其提供方适配器。`llm` 包同时承担 Service Definition 和 Consumer 角色：抽象服务、内容块词汇和流式分片组装器。提供方适配器注册到 `ctx.llm`。这些全是**产品**包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
@@ -14,4 +14,4 @@ LLM seam 及其提供方适配器。接口包（`llm`）负责抽象服务、内
 
 适配器在 seam 上注册提供方路由；重试与 token 测量仍是独立消费方。子 README 负责路由、元数据、回放和提供方协议细节；[LLM 架构决策](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)负责设计原理。
 
-子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器约定（adapter contract）——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
+子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器约定——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 1d284f7ade..4c29bfcf11 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -69,7 +69,7 @@ export interface DeepSeekConnectionOptions {
   retryPolicy: ResolvedRetryPolicy
 }
 
-/** Constructor options for {@link DeepSeekAdapter}: the two resolution seams the plugin owns. */
+/** Constructor options for {@link DeepSeekAdapter}: the two resolution hooks the plugin owns. */
 export interface DeepSeekAdapterOptions {
   /** Current validated connection facts; called once per operation. */
   options: () => DeepSeekConnectionOptions
@@ -298,7 +298,7 @@ export class DeepSeekAdapter extends LlmAdapter {
       // fetch wraps every transport failure (DNS, refused connection, TLS,
       // proxy) in a bare `TypeError: fetch failed` whose actionable detail
       // lives on `cause`. Wrapping with the endpoint and chaining the cause
-      // lets `errorChain` render the full diagnosis at every reporting seam.
+      // lets `errorChain` render the full diagnosis at every reporting boundary.
       throw new LlmError(
         `DeepSeek API request to ${connection.baseURL} failed`,
         'TRANSPORT',
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index eea304b414..840a8c2865 100644
--- a/packages/llm/llm-pi-ai/README.i18n.yaml
+++ b/packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: 4ad669344056a8290057cd39cbde56b0a2d80ba4
-README.zh.md: 96e1ef2dd3219e8b1fe0d5afbf5c784d9c3e42d5
+README.md: 7151fdf5b63f48e625d00a92dc42aa24b7de2f31
+README.zh.md: 0bfd5c706e01dd4448edb9cf0eec812831f68093
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index 4ad6693440..7151fdf5b6 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -194,4 +194,4 @@ Recorded response content appends to the next request and does not invalidate it
 - **`GenerateOptions.stop` is unsupported** — pi-ai's common stream options cannot guarantee stop-sequence behavior across providers, so the adapter rejects the field.
 - **In-history `system` messages use pi-ai's common context conversion** — provider-specific placement follows pi-ai rather than a harness-owned wire override.
 - **Provider HTTP status is unavailable** — pi-ai error events do not expose a stable HTTP status across providers; failures expose only stable harness error codes.
-- **Retry policy is provider-owned, not an SDK retry** — each provider profile may configure nested `retryPolicy`, which `dsh-llm-retry` executes at the agent failed-step seam; pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.
+- **Retry policy is provider-owned, not an SDK retry** — each provider profile may configure nested `retryPolicy`, which `dsh-llm-retry` executes at the agent failed-step extension point; pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index 96e1ef2dd3..0bfd5c706e 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -194,4 +194,4 @@ pi-ai 事件会变为 harness 推理、文本、工具调用、usage 与 finish
 - **不支持 `GenerateOptions.stop`**：pi-ai 的通用流选项无法保证所有提供方都支持 stop sequence，因此适配器会拒绝该字段。
 - **历史中的 `system` 消息使用 pi-ai 通用上下文转换**：提供方特定位置由 pi-ai 决定，而非由 harness 拥有的协议覆盖决定。
 - **无法获取提供方 HTTP 状态**：pi-ai 错误事件不会在所有提供方上公开稳定 HTTP 状态；失败只公开稳定 harness 错误 code。
-- **重试策略由提供方持有，而不是 SDK 重试**：每个提供方 profile 都可以配置嵌套的 `retryPolicy`，由 `dsh-llm-retry` 在 agent 的失败步骤 seam 上执行；pi-ai SDK 重试仍保持禁用，因此持久化的 agent 步骤与 `llm/retry` 事件记录每次可见尝试，直接 `ctx.llm.stream()` 调用仍只尝试一次。
+- **重试策略由提供方持有，而不是 SDK 重试**：每个提供方 profile 都可以配置嵌套的 `retryPolicy`，由 `dsh-llm-retry` 在 agent 的失败步骤扩展点上执行；pi-ai SDK 重试仍保持禁用，因此持久化的 agent 步骤与 `llm/retry` 事件记录每次可见尝试，直接 `ctx.llm.stream()` 调用仍只尝试一次。
diff --git a/packages/llm/llm-pi-ai/src/adapter.ts b/packages/llm/llm-pi-ai/src/adapter.ts
index e974cdff7c..09c72719ec 100644
--- a/packages/llm/llm-pi-ai/src/adapter.ts
+++ b/packages/llm/llm-pi-ai/src/adapter.ts
@@ -59,7 +59,7 @@ interface PiAiSnapshot {
   models: Models
 }
 
-/** Constructor options for {@link PiAiAdapter}: the two resolution seams the plugin owns. */
+/** Constructor options for {@link PiAiAdapter}: the two resolution hooks the plugin owns. */
 export interface PiAiAdapterOptions {
   /** Current validated profiles by provider route; called once per operation. */
   profiles: () => ReadonlyMap<string, ResolvedPiAiProviderProfile>
diff --git a/packages/llm/llm-retry/src/index.ts b/packages/llm/llm-retry/src/index.ts
index 620e367742..82b441fb8f 100644
--- a/packages/llm/llm-retry/src/index.ts
+++ b/packages/llm/llm-retry/src/index.ts
@@ -1,6 +1,6 @@
 /**
  * Provider-routed model-request retry policy on the agent loop's request
- * recovery seam. Each scheduled retry is durable before its cancellable wait.
+ * recovery extension point. Each scheduled retry is durable before its cancellable wait.
  *
  * @module @deepseek-ai/dsh-llm-retry
  */
@@ -57,7 +57,7 @@ function validateConfig(config: Config): void {
   throw new Error(`llm-retry: unknown key "${key}"`)
 }
 
-/** Non-serializable seams used to make timing policy deterministic in tests. */
+/** Non-serializable hooks used to make timing policy deterministic in tests. */
 export interface RetryInternals {
   /** Random sample in the inclusive zero-to-one range used for jitter. */
   random?: () => number
@@ -116,7 +116,7 @@ function cancellableDelay(delayMs: number, signal: AbortSignal): Promise<boolean
  * Install provider-routed normal or unbounded request recovery.
  * @param ctx - plugin context that owns the listener and active waits.
  * @param config - empty executor config; provider registrations own policy.
- * @param internals - non-serializable deterministic seams for tests.
+ * @param internals - non-serializable deterministic hooks for tests.
  */
 export function apply(ctx: Context, config: Config = {}, internals: RetryInternals = {}): void {
   validateConfig(config)
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index c4e8277b42..2c5cb7bb48 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
-README.md: a437a689e934701b925dbf5a39a912c3af7dd46b
-README.zh.md: 7ed0c9c8a93e102b3d350be48be3a07e30011582
+README.md: 0b463c73175e46d20e9c8f719b55b3fa4f56fde2
+README.zh.md: cbabeb72216e9fc92b74d6c216d7f7b7154bc1a8
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index a437a689e9..0b463c7317 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -71,7 +71,7 @@ Every adapter that puts a credential in an HTTP header judges it the same way be
 
 - `LlmAdapter` — abstract base class for provider adapters. The only required method is `stream()`.
 - `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and can create an identified, frozen assistant message from them. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks for history.
-- `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at seams.
+- `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at process boundaries.
 - `LlmError` — extends `HarnessError`; its stable `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) matches its frozen serializable `failure.code`. The payload may also retain validated status, `Retry-After`, and branded provider request id facts; policy remains outside the error.
 - `errorChain(value)` — renders a thrown value with its full `cause` chain and AggregateError members for diagnostic surfaces (UI notices, logger lines, durable `turn/end` messages), so transport wrappers like undici's `TypeError: fetch failed` surface the underlying `ECONNREFUSED`/DNS/TLS detail instead of masking it. Rendering only — route on `code`, never by parsing the result.
 - `CONTEXT_WINDOW_EXCEEDED_CODE` — the provider-neutral code both DeepSeek adapters use when a request exceeds the model context window, regardless of thrown-HTTP versus in-band finish delivery. `isContextWindowExceededError(detail)` is their shared conservative classifier for OpenAI-compatible provider detail.
@@ -93,7 +93,7 @@ Pass-through; the registry preserves the assembled request prefix, while the sel
 
 ## Known Limitations and Deferred Work
 
-- **No retry execution, caching, or rate limiting ships in this service** — provider registration stores retry policy, but `llm/stream` remains a single-attempt call-wrapper seam. The agent loop separately offers proven model-request failures to `agent/request-error`, whose default preserves the original failure; `@deepseek-ai/dsh-llm-retry` is the optional executor loaded by the shared example spine.
+- **No retry execution, caching, or rate limiting ships in this service** — provider registration stores retry policy, but `llm/stream` remains a single-attempt call wrapper. The agent loop separately offers proven model-request failures to `agent/request-error`, whose default preserves the original failure; `@deepseek-ai/dsh-llm-retry` is the optional executor loaded by the shared example spine.
 - **`GenerateOptions` sampling is `temperature`/`maxTokens`/`stop` only** — no `tool_choice`, `top_p`, or penalty fields; the vocabulary grows when a producer lands ([dropped inert knobs](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)).
 - **Producer-gated variants stay out until produced** — `prefill`, per-tool `strict`, block `cache` hints, and the `agent` message-source variant were pruned as producerless ([Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)).
 - **`BlockAssembler` handles core block kinds only** — a plugin-added block type whose stream is never closed by `block-end` makes `blocks()` throw.
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 7ed0c9c8a9..cbabeb7221 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -71,7 +71,7 @@
 
 - `LlmAdapter`：提供方适配器的抽象基类。唯一必需方法是 `stream()`。
 - `BlockAssembler`：将原始分片逐步组装为完整内容块，并能据此创建带标识且冻结的 assistant 消息。agent loop 向它提供原始分片（同时记录以供回放），并读取已组装块以构建历史。
-- `HarnessError`：harness 错误分类体系的基类，包含稳定 `code` 字符串（与面向人的 `message` 不同）加 `cause` 链接。它位于所有其他包都从中导入的叶子包中，因此可以共享单一基类，无需新的依赖边。各包的错误（`LlmError`、`ToolArgsError`、`InvariantError` 等）都继承自它。`isHarnessError(value)` 在 seam 处收窄类型。
+- `HarnessError`：harness 错误分类体系的基类，包含稳定 `code` 字符串（与面向人的 `message` 不同）加 `cause` 链接。它位于所有其他包都从中导入的叶子包中，因此可以共享单一基类，无需新的依赖边。各包的错误（`LlmError`、`ToolArgsError`、`InvariantError` 等）都继承自它。`isHarnessError(value)` 在进程边界处收窄类型。
 - `LlmError`：继承自 `HarnessError`；其稳定 `code` 字符串（`NO_ADAPTER`、`DUPLICATE_ADAPTER` 与 `AUTH`／`RATE_LIMIT` 等适配器 code）与冻结可序列化 `failure.code` 匹配。Payload 还可以保留已验证状态、`Retry-After` 和品牌化提供方请求 id 事实；策略位于错误之外。
 - `errorChain(value)`：渲染抛出值的完整 `cause` 链与 AggregateError 成员，供诊断表层使用，包括 UI 通知、logger 行和持久 `turn/end` 消息。因此 undici 的 `TypeError: fetch failed` 等传输包装层会显示底层 `ECONNREFUSED`／DNS／TLS 详细信息，而不是将其遮蔽。该函数只负责渲染：请按 `code` 路由，绝不解析结果。
 - `CONTEXT_WINDOW_EXCEEDED_CODE`：当请求超过模型上下文窗口时，无论通过 HTTP 异常抛出还是带内 finish 交付，两个 DeepSeek 适配器都使用的提供方无关 code。`isContextWindowExceededError(detail)` 是它们针对 OpenAI 兼容提供方详细信息的共享保守分类器。
@@ -93,7 +93,7 @@
 
 ## 已知限制与暂缓事项
 
-- **本服务不执行重试、缓存或速率限制**：提供方注册会存储重试策略，但 `llm/stream` 仍是单次尝试调用包装 seam。agent loop 会将已验证模型请求失败单独提供给 `agent/request-error`，其默认行为是保留原始失败；`@deepseek-ai/dsh-llm-retry` 是共享示例主干加载的可选执行器。
+- **本服务不执行重试、缓存或速率限制**：提供方注册会存储重试策略，但 `llm/stream` 仍是单次尝试调用包装层。agent loop 会将已验证模型请求失败单独提供给 `agent/request-error`，其默认行为是保留原始失败；`@deepseek-ai/dsh-llm-retry` 是共享示例主干加载的可选执行器。
 - **`GenerateOptions` 采样只包含 `temperature`／`maxTokens`／`stop`**：没有 `tool_choice`、`top_p` 或 penalty 字段；有产生方落地时词汇才会增长（见 [已删除惰性旋钮](../../../.agents/notes/archived/simplification/2026-07-04-drop-inert-request-knobs.md)）。
 - **受产生方约束的变体在实际产生前不会加入**：`prefill`、每工具 `strict`、块 `cache` 提示与 `agent` 消息源变体因没有产生方而被剪除（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)）。
 - **`BlockAssembler` 只处理核心块类型**：如果插件添加块类型的流从未由 `block-end` 关闭，`blocks()` 会抛出异常。
diff --git a/packages/llm/llm/src/error.ts b/packages/llm/llm/src/error.ts
index 9ff193f1f8..4b3e25c75f 100644
--- a/packages/llm/llm/src/error.ts
+++ b/packages/llm/llm/src/error.ts
@@ -154,7 +154,7 @@ export function errorChain(value: unknown): string {
 }
 
 /**
- * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at seams).
+ * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at runtime boundaries).
  * @param value - the caught value (`unknown` in catch clauses).
  * @returns true only for real instances; duck-typed or cross-realm errors do not narrow.
  */
diff --git a/packages/llm/llm/src/retry-policy.ts b/packages/llm/llm/src/retry-policy.ts
index 7d4c4601eb..6f5548a111 100644
--- a/packages/llm/llm/src/retry-policy.ts
+++ b/packages/llm/llm/src/retry-policy.ts
@@ -2,7 +2,7 @@
  * Provider-owned request-retry policy configuration and resolution.
  *
  * Adapters expose one resolved policy per registered provider route; the
- * optional dsh-llm-retry plugin executes it on the agent's failed-step seam.
+ * optional dsh-llm-retry plugin executes it on the agent's failed-step extension point.
  *
  * @module @deepseek-ai/dsh-llm/retry-policy
  */
diff --git a/packages/llm/llm/tests/attribution.spec.ts b/packages/llm/llm/tests/attribution.spec.ts
index e797af5b38..db74773314 100644
--- a/packages/llm/llm/tests/attribution.spec.ts
+++ b/packages/llm/llm/tests/attribution.spec.ts
@@ -5,7 +5,7 @@ import type { AppIdentity } from '@deepseek-ai/dsh-llm'
 
 const manifest = createRequire(import.meta.url)('../package.json') as { version: string }
 
-/** A white-label identity exercising every override seam. */
+/** A white-label identity exercising every override hook. */
 const forkIdentity: AppIdentity = {
   product: 'fork-agent',
   version: '9.9.9',
diff --git a/packages/llm/token-meter/src/index.ts b/packages/llm/token-meter/src/index.ts
index caea2a2701..d3b024a2ee 100644
--- a/packages/llm/token-meter/src/index.ts
+++ b/packages/llm/token-meter/src/index.ts
@@ -10,7 +10,7 @@ import { BlockAssembler, deepFreeze } from '@deepseek-ai/dsh-llm'
 import type { Message, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type { EpochHeader, Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { canonicalHeader, headerEquals, isSurfaceEvent } from '@deepseek-ai/dsh-session'
-// Type-only: resolves the optional projection registry Context seam.
+// Type-only: resolves the optional projection registry Context declaration.
 import type {} from '@deepseek-ai/dsh-session-projection'
 import type {
   TokenMeasurement,
diff --git a/packages/lsp/README.i18n.yaml b/packages/lsp/README.i18n.yaml
index abe4d95c7e..cc3ddc6e53 100644
--- a/packages/lsp/README.i18n.yaml
+++ b/packages/lsp/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/lsp/README.md
-README.md: 01c464c9993571990e0542df9fadb2848a6c9a79
-README.zh.md: 7a24bffa0e92f30c16a3307357ba7f1aa295ef52
+README.md: 3b472492ba12146101bae0e2eae9c837a7f6cb1d
+README.zh.md: e9e2781fdb9da8a3094080759730d01e179bff98
diff --git a/packages/lsp/README.md b/packages/lsp/README.md
index 01c464c999..3b472492ba 100644
--- a/packages/lsp/README.md
+++ b/packages/lsp/README.md
@@ -2,15 +2,15 @@
 
 English | [中文](README.zh.md)
 
-The language-server capability seam: an abstract LSP interface, a generic stdio provider, and the model-facing `lsp` tool. All **product** packages.
+The language-server capability seam: an LSP Service Definition, a generic stdio provider, and the model-facing `lsp` tool. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
+| `lsp/` | Service Definition (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
 | `lsp-local/` | Generic multi-server stdio backend over `ctx.fs` and `ctx.subprocess` (JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
 | `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
-The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
+The Service Definition lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
 
 See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
 
diff --git a/packages/lsp/README.zh.md b/packages/lsp/README.zh.md
index 7a24bffa0e..e9e2781fdb 100644
--- a/packages/lsp/README.zh.md
+++ b/packages/lsp/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品**包。
+语言服务器能力 seam：LSP Service Definition、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品** 包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
+| `lsp/` | Service Definition（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
 | `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
 | `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
-接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型约定。提供方注册的是**能力**而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
+Service Definition 位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型约定。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
 
 设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
 
diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts
index 4be75cbd33..0a267c879f 100644
--- a/packages/lsp/lsp-local/src/connection.ts
+++ b/packages/lsp/lsp-local/src/connection.ts
@@ -1,12 +1,12 @@
 /**
  * A JSON-RPC endpoint over one language server spawned through the subprocess
- * seam. Owns id correlation, outbound requests/notifications, and inbound
+ * capability. Owns id correlation, outbound requests/notifications, and inbound
  * server→client requests: it answers `workspace/configuration` from static
  * config, and rejects `workspace/applyEdit` (this host never applies edits or
  * runs commands). It caps stderr, surfaces framing/decoder failures as a
  * fatal close, and exposes tree-scoped termination through the handle so the
- * instance owns teardown; group/tree mechanics live in the seam's
- * implementation.
+ * instance owns teardown; group/tree mechanics live in the subprocess
+ * Service provider.
  * @module @deepseek-ai/dsh-lsp-local/connection
  */
 
diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts
index 318704b9fc..4ecd444f1e 100644
--- a/packages/lsp/lsp-local/src/instance.ts
+++ b/packages/lsp/lsp-local/src/instance.ts
@@ -92,7 +92,7 @@ export class LspInstance {
    */
   query(request: LspProviderQuery, source: HostSource, signal?: AbortSignal): Promise<LspQueryResult> {
     // Serialize behind prior work, but observe abort DURING the queue wait too: if an earlier query
-    // hangs (e.g. a signal-less seam caller), a later tool's timeout must still be able to give up
+    // hangs (e.g. a signal-less service caller), a later tool's timeout must still be able to give up
     // rather than block on the shared tail forever.
     const run = abortable(this.queue, signal)
       .then(() => this.runQuery(request, source, signal))
diff --git a/packages/lsp/lsp-local/src/translate.ts b/packages/lsp/lsp-local/src/translate.ts
index a49246c8bb..13ba14455b 100644
--- a/packages/lsp/lsp-local/src/translate.ts
+++ b/packages/lsp/lsp-local/src/translate.ts
@@ -25,8 +25,8 @@ import type {
 } from './protocol.ts'
 
 /**
- * The `textDocument/*` request method for each seam operation.
- * @param operation - the seam operation to map.
+ * The `textDocument/*` request method for each LSP operation.
+ * @param operation - the LSP operation to map.
  * @returns the LSP request method name.
  */
 export function requestMethod(operation: LspOperation): string {
@@ -62,7 +62,7 @@ function supportsCapability(value: WireProviderCapability): boolean {
 /**
  * Whether the server advertises the requested operation.
  * @param capabilities - the server's `initialize` capabilities.
- * @param operation - the seam operation to check.
+ * @param operation - the LSP operation to check.
  * @returns true when the corresponding provider capability is present.
  */
 export function supportsOperation(capabilities: WireServerCapabilities, operation: LspOperation): boolean {
diff --git a/packages/lsp/lsp/README.i18n.yaml b/packages/lsp/lsp/README.i18n.yaml
index cceabd1036..af06afd030 100644
--- a/packages/lsp/lsp/README.i18n.yaml
+++ b/packages/lsp/lsp/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/lsp/lsp/README.md
-README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
-README.zh.md: a35f870603718ee6b7bcbfdf65f5d689d800447b
+README.md: bab312e73f746d0d782ab5771429fed1397255aa
+README.zh.md: 7ef95c725eba4a35f99014b446fc5648d8aab20a
diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md
index 5c1044be50..bab312e73f 100644
--- a/packages/lsp/lsp/README.md
+++ b/packages/lsp/lsp/README.md
@@ -4,13 +4,13 @@ English | [中文](README.zh.md)
 
 The **LSP capability seam**: an abstract `LspService` (`ctx.lsp`) defining WHAT semantic code navigation the harness has — go to definition, find references, find implementations, hover — over language-server providers, without binding the model contract to local subprocesses.
 
-This package is the interface third of the LSP capability:
+This package owns the Service Definition role of the LSP capability:
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-lsp` (this) | the interface: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
-| `@deepseek-ai/dsh-lsp-local` | a generic local backend that registers configured stdio language-server providers |
-| `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool over `ctx.lsp` |
+| `@deepseek-ai/dsh-lsp` (this) | Service Definition: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy |
+| `@deepseek-ai/dsh-lsp-local` | Service provider: a generic local backend that registers configured stdio language-server providers |
+| `@deepseek-ai/dsh-tool-lsp` | Consumer: the model-facing `lsp` tool over `ctx.lsp` |
 
 The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`.
 
diff --git a/packages/lsp/lsp/README.zh.md b/packages/lsp/lsp/README.zh.md
index a35f870603..7ef95c725e 100644
--- a/packages/lsp/lsp/README.zh.md
+++ b/packages/lsp/lsp/README.zh.md
@@ -4,13 +4,13 @@
 
 **LSP 能力 seam**：抽象 `LspService`（`ctx.lsp`）定义 harness 具备哪些语义代码导航能力（转到定义、查找引用、查找实现、悬停），并通过语言服务器提供方实现，不把模型约定绑定到本地子进程。
 
-该包是 LSP 能力中负责接口的三分之一：
+本包承担 LSP 能力的 Service Definition 角色：
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
-| `@deepseek-ai/dsh-lsp-local` | 通用本地后端，注册已配置的 stdio 语言服务器提供方 |
-| `@deepseek-ai/dsh-tool-lsp` | 面向模型的 `lsp` 工具，基于 `ctx.lsp` |
+| `@deepseek-ai/dsh-lsp`（本包） | Service Definition：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
+| `@deepseek-ai/dsh-lsp-local` | Service provider：通用本地后端，注册已配置的 stdio 语言服务器提供方 |
+| `@deepseek-ai/dsh-tool-lsp` | Consumer：面向模型的 `lsp` 工具，基于 `ctx.lsp` |
 
 该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且没有通用 JSON-RPC 逃生口，因此任何协议载荷或未经评审的命令／修改都无法通过 `ctx.lsp` 到达提供方。
 
diff --git a/packages/lsp/lsp/src/index.ts b/packages/lsp/lsp/src/index.ts
index d7b1a80d01..ec780b76f1 100644
--- a/packages/lsp/lsp/src/index.ts
+++ b/packages/lsp/lsp/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The LSP capability seam (`ctx.lsp`): a language-server provider registry and per-query,
+ * Service Definition for the LSP capability seam (`ctx.lsp`): a language-server provider registry and per-query,
  * order-independent selection over normalized goToDefinition/findReferences/goToImplementation/
  * hover queries.
  *
diff --git a/packages/lsp/tool-lsp/README.i18n.yaml b/packages/lsp/tool-lsp/README.i18n.yaml
index 85a33f73af..cb728b0168 100644
--- a/packages/lsp/tool-lsp/README.i18n.yaml
+++ b/packages/lsp/tool-lsp/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/lsp/tool-lsp/README.md
-README.md: 1e89abf22e853735c094d17047b2c946af210905
-README.zh.md: 396b4d22ada8761b17c01d0c40e4bb4cfe80ca67
+README.md: 36fa3026cba3fc692ae5a86c7307acf77563cf53
+README.zh.md: 1b0b1f4847cf711e7939b79ac2f8035f26cb73aa
diff --git a/packages/lsp/tool-lsp/README.md b/packages/lsp/tool-lsp/README.md
index 1e89abf22e..36fa3026cb 100644
--- a/packages/lsp/tool-lsp/README.md
+++ b/packages/lsp/tool-lsp/README.md
@@ -10,7 +10,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). In
 
 `lsp` accepts `operation` (`goToDefinition` | `findReferences` | `goToImplementation` | `hover`), `file_path`, `line`, and `character`. `line` and `character` are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based positions and converts rendered locations back. `findReferences` includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable stay outside model input.
 
-The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized seam union: `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering projects stable, file-grouped `path:line:character` entries against the provider's canonical workspace URI rather than applying host-platform path rules to the session cwd. A `file:` URI becomes a workspace-relative path inside that URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs stay verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
+The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized Service Definition union: `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering projects stable, file-grouped `path:line:character` entries against the provider's canonical workspace URI rather than applying host-platform path rules to the session cwd. A `file:` URI becomes a workspace-relative path inside that URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs stay verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
 
 ## Configuration
 
diff --git a/packages/lsp/tool-lsp/README.zh.md b/packages/lsp/tool-lsp/README.zh.md
index 396b4d22ad..1b0b1f4847 100644
--- a/packages/lsp/tool-lsp/README.zh.md
+++ b/packages/lsp/tool-lsp/README.zh.md
@@ -10,7 +10,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 `lsp` 接受 `operation`（`goToDefinition` | `findReferences` | `goToImplementation` | `hover`）、`file_path`、`line` 和 `character`。`line` 与 `character` 是正的、从 1 开始的 UTF-16 光标坐标；工具将其转换为 seam 从零开始的位置，并把渲染位置转换回来。`findReferences` 包含声明，因此影响分析不会遗漏定义位置。提供方、language id、Workspace 根、限制、超时、初始化和可执行文件均不进入模型输入。
 
-该工具要求从会话 `header.cwd` 取得 Workspace 根，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 seam 联合：`{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。原生渲染以提供方的规范工作区 URI 为基准，投影按文件稳定分组的 `path:line:character` 条目，而不对会话 cwd 应用宿主平台路径规则。`file:` URI 落在该工作区 URI 内时成为工作区相对路径，位于其外时成为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
+该工具要求从会话 `header.cwd` 取得 Workspace 根，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 Service Definition 联合：`{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。原生渲染以提供方的规范工作区 URI 为基准，投影按文件稳定分组的 `path:line:character` 条目，而不对会话 cwd 应用宿主平台路径规则。`file:` URI 落在该工作区 URI 内时成为工作区相对路径，位于其外时成为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
 
 ## 配置
 
diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts
index 3a18e44088..fddee83915 100644
--- a/packages/plan/plan-mode/tests/plan-mode.spec.ts
+++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts
@@ -362,7 +362,7 @@ describe('the boundary flush', () => {
     ctx.planMode.set(agent, true)
     const original = agent.session.append.bind(agent.session)
     // Only the flush's own plan/mode append fails; the boundary event itself
-    // lands (the loop appended it before the seam fires).
+    // lands (the loop appended it before the between-step hook fires).
     agent.session.append = (((type: string, ...rest: unknown[]) => {
       if (type === 'plan/mode') throw new Error('backend gone')
       return (original as (...args: unknown[]) => unknown)(type, ...rest)
diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts
index 67698f80b4..1deefc7657 100644
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -70,7 +70,7 @@ function defaultProbeSeatbelt(seatbeltExec: string, timeoutMs: number): boolean
   return probe.status === 0
 }
 
-/** Test seam: inject probe verdicts / a fake launcher / a platform without real runners. */
+/** Test hook: inject probe verdicts / a fake launcher / a platform without real runners. */
 export interface SandboxInternals {
   /** Replaces `process.platform` for chain selection (exercise any platform's chain from any host). */
   platform?: string
@@ -179,7 +179,7 @@ export class LocalSandboxProvider extends SandboxProvider {
     probeTimeoutMs: z.natural().default(5_000),
   })
 
-  /** Test seam (mirrors the bash executors' `internals`). */
+  /** Test hook (mirrors the bash executors' `internals`). */
   internals: SandboxInternals = {}
 
   private readonly runnerCommand: string[] | undefined
@@ -300,12 +300,12 @@ export class LocalSandboxProvider extends SandboxProvider {
     }
   }
 
-  /** The Landlock launcher to probe and exec (test seam over the resolved one). */
+  /** The Landlock launcher to probe and exec (test hook over the resolved one). */
   private landlockLauncher(): string {
     return this.internals.landlockLauncher ?? landlockLauncherPath()
   }
 
-  /** The `sandbox-exec` executable to probe and exec (test seam over the system one). */
+  /** The `sandbox-exec` executable to probe and exec (test hook over the system one). */
   private seatbeltExec(): string {
     return this.internals.seatbeltExec ?? 'sandbox-exec'
   }
diff --git a/packages/sandbox/sandbox-local/tests/local.spec.ts b/packages/sandbox/sandbox-local/tests/local.spec.ts
index b1b8b2c4a8..93f725fe48 100644
--- a/packages/sandbox/sandbox-local/tests/local.spec.ts
+++ b/packages/sandbox/sandbox-local/tests/local.spec.ts
@@ -237,7 +237,7 @@ describe('the platform chains', () => {
 
   it('a multi-rung chain probes a seatbelt rung like any other (the walk, not the platform table, decides)', async () => {
     // The product chains reach seatbelt only as darwin's sole (unprobed)
-    // candidate; the chain seam exercises the probing path it would take in
+    // candidate; the probe chain exercises the path it would take in
     // a grown chain, keeping the default seatbelt probe honest.
     const exec = fakeSeatbeltExec(0)
     const probeBwrap = vi.fn(() => false)
@@ -349,8 +349,8 @@ describe('probeTimeoutMs config', () => {
 
 describe('the default seatbelt probe (sandbox-exec contract)', () => {
   // The product chains reach seatbelt only unprobed (darwin's sole
-  // candidate), so the default probe's contract is pinned through the chain
-  // seam: a grown chain must probe it like any other rung.
+  // candidate), so the default probe's contract is pinned through the provider
+  // chain: a grown chain must probe it like any other rung.
   it('selects the rung when the executable applies the read-only profile and exits 0', async () => {
     const exec = fakeSeatbeltExec(0)
     const { sandbox } = await setup({}, { chain: ['bwrap', 'seatbelt'], probeBwrap: () => false, seatbeltExec: exec })
diff --git a/packages/sandbox/sandbox/README.i18n.yaml b/packages/sandbox/sandbox/README.i18n.yaml
index 3c29efec12..d431dd97c4 100644
--- a/packages/sandbox/sandbox/README.i18n.yaml
+++ b/packages/sandbox/sandbox/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/sandbox/sandbox/README.md
-README.md: 8c1c747f6c7178f9c8c1a9827675ffa98f29aa6d
-README.zh.md: abc5d387384e3a69e35496d6ce4bc9830185c55d
+README.md: 50b7eff1a287ee0bc2432a7bf409586ff879920e
+README.zh.md: ff68a49f5487b5da9700698c5376199727f1cd5f
diff --git a/packages/sandbox/sandbox/README.md b/packages/sandbox/sandbox/README.md
index 8c1c747f6c..50b7eff1a2 100644
--- a/packages/sandbox/sandbox/README.md
+++ b/packages/sandbox/sandbox/README.md
@@ -2,13 +2,13 @@
 
 English | [中文](README.zh.md)
 
-Abstract process-sandbox seam. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxExecutionPolicy` (the complete per-call mode + workspace root), `SandboxPolicy` (its confined subset), and the fail-closed `SANDBOX_UNAVAILABLE` error. Interface package of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): depends only on cordis (+ the harness error base), never on a backend.
+Process-sandbox Service Definition. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxExecutionPolicy` (the complete per-call mode + workspace root), `SandboxPolicy` (its confined subset), and the fail-closed `SANDBOX_UNAVAILABLE` error. As the Service Definition role of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), it depends only on cordis (+ the harness error base), never on a backend.
 
 The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus the selected backend's enforcement completeness, denial dialect (`denialSignatures`), and structured runner-failure evidence (`runnerFailureRules`); when no backend is usable it throws rather than passing the argv through unconfined. The [core type catalog](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects) owns the exact classifier shape.
 
 Policy rides the call, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is just a new call with a wider policy.
 
-**Same-world confinement only.** A backend shares the host's filesystem and kernel (`bwrap`, Landlock, Seatbelt); `workspaceRoot` names the filesystem-canonical real host directory. Workspace identity is resolved before lexical normalization, so a valid cwd containing `symlink/..` grants the directory where `chdir` actually lands rather than an unrelated lexical parent. Containers, microVMs, and remote executors are NOT backends of this seam — they replace whole capability implementations (`ctx.bash`, `ctx.fs`) as environment-coherent groups. The boundary and its rationale: [the sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
+**Same-world confinement only.** A backend shares the host's filesystem and kernel (`bwrap`, Landlock, Seatbelt); `workspaceRoot` names the filesystem-canonical real host directory. Workspace identity is resolved before lexical normalization, so a valid cwd containing `symlink/..` grants the directory where `chdir` actually lands rather than an unrelated lexical parent. Containers, microVMs, and remote executors are NOT backends of this seam — they replace the Service providers for whole capability seams (`ctx.bash`, `ctx.fs`) as environment-coherent groups. The boundary and its rationale: [the sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
 
 Implementations: [`@deepseek-ai/dsh-sandbox-local`](../sandbox-local/) (Linux: `bwrap`, else the per-platform Landlock launcher; macOS: `sandbox-exec`/Seatbelt). Consumers: [`@deepseek-ai/dsh-bash-sandbox`](../../bash/bash-sandbox/) (wraps `['bash', '-c', command]`).
 
diff --git a/packages/sandbox/sandbox/README.zh.md b/packages/sandbox/sandbox/README.zh.md
index abc5d38738..ff68a49f54 100644
--- a/packages/sandbox/sandbox/README.zh.md
+++ b/packages/sandbox/sandbox/README.zh.md
@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务约定（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。
+进程沙箱 Service Definition。负责定义 `ctx.sandbox` 服务约定（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。作为[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)中的 Service Definition 角色，它只依赖 cordis（及 harness 错误基类），绝不依赖后端。
 
 用一句话概括约定：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。
 
 策略随调用传递，而不属于提供方：两个消费方可以同时按不同策略施加限制（bash 使用 `read-only`，而受限制的子 agent（智能体）保持其状态目录可写）；获批的升权重试只是使用更宽策略发起的新调用。
 
-**只支持与宿主共享文件系统和内核的限制。** 后端与宿主共享文件系统和内核（`bwrap`、Landlock、Seatbelt）；`workspaceRoot` 指向文件系统规范化后的真实主机目录。系统先解析工作区所指的目录，再做词法规范化，因此包含 `symlink/..` 的有效 cwd 会授权 `chdir` 实际到达的目录，而非无关的词法父目录。容器、microVM 与远程执行器都不是该 seam 的后端：它们会以环境一致的分组替换整个能力实现（`ctx.bash`、`ctx.fs`）。边界及其设计理由见[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
+**只支持与宿主共享文件系统和内核的限制。** 后端与宿主共享文件系统和内核（`bwrap`、Landlock、Seatbelt）；`workspaceRoot` 指向文件系统规范化后的真实主机目录。系统先解析工作区所指的目录，再做词法规范化，因此包含 `symlink/..` 的有效 cwd 会授权 `chdir` 实际到达的目录，而非无关的词法父目录。容器、microVM 与远程执行器都不是该 seam 的后端：它们会以环境一致的分组替换整个能力 seam 的 Service provider（`ctx.bash`、`ctx.fs`）。边界及其设计理由见[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
 
 实现：[`@deepseek-ai/dsh-sandbox-local`](../sandbox-local/)（Linux：`bwrap`，否则使用相应平台的 Landlock launcher；macOS：`sandbox-exec`／Seatbelt）。消费方：[`@deepseek-ai/dsh-bash-sandbox`](../../bash/bash-sandbox/)（包装 `['bash', '-c', command]`）。
 
@@ -39,5 +39,5 @@ sandbox mode "<mode>" is requested but no sandbox backend is usable on this host
 - **文件操作是完整的策略词汇**：该 seam 不表达网络、进程、系统调用、设备或凭据限制。
 - **只支持与宿主共享文件系统和内核的限制**：容器、microVM 与远程执行需要替换能力实现，而不是在此处增加提供方。
 - **拒绝报告是一种 stderr 方言**：该 seam 返回后端签名，而非类型化运行时拒绝通道，因此需要分类的消费方必须从子进程输出推断。
-- **Runner 诊断使用带内通道**：退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此受限子进程若故意模仿 runner，就可能造成可用性或诊断误归因。这无法绕过限制；带外 runner 状态通道暂缓实现。
+- **Runner 诊断使用带内通道**：退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此受限子进程若故意模仿 runner，就可能造成可用性或诊断误归因。这无法绕过约束；带外 runner 状态通道暂缓实现。
 - **每个上下文只有一个提供方**：同时组合不同沙箱机制需要提供方级阶梯或独立 Cordis 上下文；调用方逐调用选择策略，而非后端标识。
diff --git a/packages/sandbox/sandbox/src/index.ts b/packages/sandbox/sandbox/src/index.ts
index aeca1ba8d6..75f8e9b846 100644
--- a/packages/sandbox/sandbox/src/index.ts
+++ b/packages/sandbox/sandbox/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Same-world process-confinement seam: wrap exact subprocess argv under a
+ * Service Definition for the same-world process-confinement capability seam: wrap exact subprocess argv under a
  * host-path file policy. Containers, microVMs, and remote execution replace the
  * surrounding capability seam instead; this service shares the host kernel and filesystem.
  * @module @deepseek-ai/dsh-sandbox
diff --git a/packages/scaffold/create-sdk/src/headless.ts b/packages/scaffold/create-sdk/src/headless.ts
index 9210f12fc1..8f6130acd7 100644
--- a/packages/scaffold/create-sdk/src/headless.ts
+++ b/packages/scaffold/create-sdk/src/headless.ts
@@ -62,7 +62,7 @@ function parseHeadlessSpec(text: string, source: string): HeadlessCreateSpec {
  * Load a headless spec from `--config-json` (inline) or `--config` (a JSON file),
  * returning `undefined` when neither is supplied.
  * @param args - parsed create args.
- * @param readFileText - file reader seam for tests.
+ * @param readFileText - File-reader hook for tests.
  * @returns the resolved args + feature plan, or `undefined` for interactive runs.
  */
 export async function resolveHeadless(
diff --git a/packages/scaffold/scripts/src/telemetry.ts b/packages/scaffold/scripts/src/telemetry.ts
index 1ef74fdbb7..d739a7164b 100644
--- a/packages/scaffold/scripts/src/telemetry.ts
+++ b/packages/scaffold/scripts/src/telemetry.ts
@@ -25,7 +25,7 @@ export interface CommandTelemetryEvent {
   success: boolean
 }
 
-/** Injectable consent and delivery seams for tests. */
+/** Injectable consent and delivery hooks for tests. */
 export interface CommandTelemetryDeps {
   resolve?: (cwd: string) => Promise<ConsentDecision>
   reporter?: Pick<TelemetryReporter, 'report' | 'flush'>
@@ -36,7 +36,7 @@ export interface CommandTelemetryDeps {
  * telemetry event, draining in-flight sends before returning. Swallows every
  * error so telemetry can never change a command's result.
  * @param event - the command lifecycle facts.
- * @param deps - consent and delivery seams; defaults hit the real endpoint.
+ * @param deps - Consent and delivery hooks; defaults hit the real endpoint.
  */
 export async function reportCommandTelemetry(
   event: CommandTelemetryEvent,
diff --git a/packages/scaffold/server/README.i18n.yaml b/packages/scaffold/server/README.i18n.yaml
index fc60d047d1..d6c24c3566 100644
--- a/packages/scaffold/server/README.i18n.yaml
+++ b/packages/scaffold/server/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/scaffold/server/README.md
-README.md: 0afb3a38ece57f74729a218dc85348fa6c7fa529
-README.zh.md: 5305434abbd83eb230dcdd81e72120d96da26cda
+README.md: 9c53946f4112e9ce8e17590c2ff91fb4b8c2ef74
+README.zh.md: 270691f859426dbdc6ca9d8f05049d290eaa8e1b
diff --git a/packages/scaffold/server/README.md b/packages/scaffold/server/README.md
index 0afb3a38ec..9c53946f41 100644
--- a/packages/scaffold/server/README.md
+++ b/packages/scaffold/server/README.md
@@ -10,7 +10,7 @@ The `jsonrpc` plugin serves newline-delimited JSON-RPC over stdio so out-of-proc
 
 ## Config
 
-`maxTokensAsSuccess` defaults to `false` and affects only the deployment-mapped status on `subagent.finished`; root-session prompts have no prompt-level status. `JsonRpcConfig.input`, `output`, and `exit` are runtime-only transport seams; production uses process stdio and `process.exit`.
+`maxTokensAsSuccess` defaults to `false` and affects only the deployment-mapped status on `subagent.finished`; root-session prompts have no prompt-level status. `JsonRpcConfig.input`, `output`, and `exit` are runtime-only transport hooks; production uses process stdio and `process.exit`.
 
 ## stdout is the protocol
 
diff --git a/packages/scaffold/server/README.zh.md b/packages/scaffold/server/README.zh.md
index 5305434abb..270691f859 100644
--- a/packages/scaffold/server/README.zh.md
+++ b/packages/scaffold/server/README.zh.md
@@ -10,7 +10,7 @@
 
 ## 配置
 
-`maxTokensAsSuccess` 默认为 `false`，且只影响 `subagent.finished` 上由部署映射的状态；根会话提示词没有提示词级状态。`JsonRpcConfig.input`、`output` 和 `exit` 是仅供运行时使用的传输 seam；生产环境使用进程 stdio 和 `process.exit`。
+`maxTokensAsSuccess` 默认为 `false`，且只影响 `subagent.finished` 上由部署映射的状态；根会话提示词没有提示词级状态。`JsonRpcConfig.input`、`output` 和 `exit` 是仅供运行时使用的传输钩子；生产环境使用进程 stdio 和 `process.exit`。
 
 ## stdout 即协议
 
diff --git a/packages/scaffold/server/src/index.ts b/packages/scaffold/server/src/index.ts
index f0261e1a21..be7252007a 100644
--- a/packages/scaffold/server/src/index.ts
+++ b/packages/scaffold/server/src/index.ts
@@ -25,7 +25,7 @@ export const name = 'jsonrpc'
 // Only the agent factory is required; initialize reads the optional LLM seam with ctx.get().
 export const inject = ['agents']
 
-/** JSON-RPC deployment config plus runtime-only test seams. */
+/** JSON-RPC deployment config plus runtime-only test hooks. */
 export interface JsonRpcConfig {
   /** Report max-token turn/subagent termination as a successful SDK result. */
   maxTokensAsSuccess?: boolean
@@ -53,11 +53,11 @@ export function apply(ctx: Context, config: JsonRpcConfig): void {
   // Protocol shutdown owns the complete runtime process, so it must await the
   // root lifecycle (including persistence) before exiting.
   const rootFiber = ctx.root.fiber
-  /* v8 ignore next -- production stdio wiring; tests always inject the runtime seams */
+  /* v8 ignore next -- production stdio wiring; tests always inject the runtime hooks */
   const input = config.input ?? process.stdin
-  /* v8 ignore next -- production stdio wiring; tests always inject the runtime seams */
+  /* v8 ignore next -- production stdio wiring; tests always inject the runtime hooks */
   const output = config.output ?? process.stdout
-  /* v8 ignore next -- production exit wiring; tests always inject the runtime seams */
+  /* v8 ignore next -- production exit wiring; tests always inject the runtime hooks */
   const exit = config.exit ?? ((code: number): void => { process.exit(code) })
 
   const transport = new JsonRpcLineTransport(input, output)
diff --git a/packages/scaffold/server/tests/plugin-apply.spec.ts b/packages/scaffold/server/tests/plugin-apply.spec.ts
index af64092933..b2109b8c51 100644
--- a/packages/scaffold/server/tests/plugin-apply.spec.ts
+++ b/packages/scaffold/server/tests/plugin-apply.spec.ts
@@ -11,7 +11,7 @@ import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as jsonrpc from '../src/index.ts'
 
 /**
- * Mount the real namespace plugin with in-memory stdio and exit seams. Covers
+ * Mount the real namespace plugin with in-memory stdio and exit hooks. Covers
  * the full transport/server path, response-before-exit shutdown exactly once,
  * and bare-fiber disposal without process exit.
  */
diff --git a/packages/scaffold/telemetry/src/anonymous-id.ts b/packages/scaffold/telemetry/src/anonymous-id.ts
index dcfe08c158..08925d1ad2 100644
--- a/packages/scaffold/telemetry/src/anonymous-id.ts
+++ b/packages/scaffold/telemetry/src/anonymous-id.ts
@@ -27,11 +27,11 @@ export const ANONYMOUS_ID_FILE_NAME = 'telemetry.json'
 
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
-/** Ambient seams for locating and generating the id; every field has a default. */
+/** Ambient hooks for locating and generating the id; every field has a default. */
 export interface AnonymousIdOptions {
   /** Environment consulted for `DSH_HOME`; defaults to `process.env`. */
   env?: NodeJS.ProcessEnv
-  /** UUID generator; defaults to `crypto.randomUUID` (test seam). */
+  /** UUID generator; defaults to `crypto.randomUUID` (test hook). */
   randomUUID?: () => string
 }
 
@@ -40,7 +40,7 @@ export interface AnonymousIdOptions {
  * Delegates to {@link resolveDshHome} so telemetry shares the harness's one
  * home-resolution policy (`DSH_HOME` > `~/.dsh`) instead of maintaining a
  * second config-directory convention.
- * @param options - environment seam.
+ * @param options - Environment hook.
  * @returns absolute harness home path.
  */
 export function globalConfigDir(options: AnonymousIdOptions = {}): string {
@@ -74,7 +74,7 @@ async function readPersistedId(file: string): Promise<AnonymousId | undefined> {
  * Return the harness home's anonymous id, creating and persisting one on first use.
  * Persistence is best-effort: a write failure still returns a usable id for the
  * current run so telemetry is never blocked by config-dir permissions.
- * @param options - config-location and UUID-generation seams.
+ * @param options - config-location and UUID-generation hooks.
  * @returns the stable per-harness-home anonymous id.
  */
 export async function getOrCreateAnonymousId(options: AnonymousIdOptions = {}): Promise<AnonymousId> {
diff --git a/packages/scaffold/telemetry/src/reporter.ts b/packages/scaffold/telemetry/src/reporter.ts
index b7ac75a23f..7a03c9a0f7 100644
--- a/packages/scaffold/telemetry/src/reporter.ts
+++ b/packages/scaffold/telemetry/src/reporter.ts
@@ -45,7 +45,7 @@ interface TelemetryEnvelope extends TelemetryPayload {
   sentAt: string
 }
 
-/** Injectable seams for {@link TelemetryReporter}; every field has a default. */
+/** Injectable dependencies for {@link TelemetryReporter}; every field has a default. */
 export interface TelemetryReporterOptions {
   /** Collection endpoint; defaults to {@link DSH_TELEMETRY_ENDPOINT}. */
   endpoint?: string
@@ -71,7 +71,7 @@ export class TelemetryReporter {
   readonly #now: () => number
   readonly #inflight = new Set<Promise<DeliveryOutcome>>()
 
-  /** @param options - endpoint, transport, id provider, and timing seams. */
+  /** @param options - endpoint, transport, id provider, and timing dependencies. */
   constructor(options: TelemetryReporterOptions = {}) {
     this.#endpoint = options.endpoint ?? DSH_TELEMETRY_ENDPOINT
     this.#fetch = options.fetch ?? globalThis.fetch
diff --git a/packages/self-modification/repository-plugin/src/mcp.ts b/packages/self-modification/repository-plugin/src/mcp.ts
index 6c1c5ccbf3..d2294fb5c6 100644
--- a/packages/self-modification/repository-plugin/src/mcp.ts
+++ b/packages/self-modification/repository-plugin/src/mcp.ts
@@ -7,7 +7,7 @@ import { z } from 'zod'
 
 /**
  * Restates dsh-mcp-client's `SERVER_NAME_PATTERN` rather than importing it:
- * the prepare bin must stay a zod-only module graph (no tools seam, no MCP
+ * the prepare bin must stay a zod-only module graph (no tools service, no MCP
  * SDK). Exported so `repository-plugin.spec.ts` pins equality with the
  * client's exported pattern — prepare-time validation cannot drift from the
  * registry that enforces uniqueness.
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index a8fa2b4cff..eb7f2a0eac 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -104,7 +104,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'requireInitiator(): Agent',
-        jsDoc: '/**\n * Read the initiating Agent and fail when no initiator boundary is active.\n * Use this for private helpers contractually below a driver, or for a\n * deployment-owned outbound request whose contract forbids agentless calls.\n * Generic or direct-call seams use optional lookup or explicit request fields.\n * @returns the inherited Agent.\n * @throws when no initiator is active or this service instance has been disposed.\n */',
+        jsDoc: '/**\n * Read the initiating Agent and fail when no initiator boundary is active.\n * Use this for private helpers contractually below a driver, or for a\n * deployment-owned outbound request whose contract forbids agentless calls.\n * Generic or direct-call paths use optional lookup or explicit request fields.\n * @returns the inherited Agent.\n * @throws when no initiator is active or this service instance has been disposed.\n */',
       },
       {
         signature: 'withInitiator<T>(agent: Agent, operation: () => T): T',
@@ -242,7 +242,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'abstract run(request: CodeRunRequest): Promise<CodeRunResult>',
-        jsDoc: '/**\n * Execute one program against the request\'s bindings and capture what it\n * emitted. See the class doc for the resolution contract (error is a result\n * field; rejection means seam misuse only).\n * @param request - the program, its bindings, and the abort signal; the\n *   request carries everything the runtime acts on, with no hidden defaults.\n * @returns the run\'s outcome: completion value (when transferable), the\n *   ordered log capture, and the failure (if any).\n */',
+        jsDoc: '/**\n * Execute one program against the request\'s bindings and capture what it\n * emitted. See the class doc for the resolution contract (error is a result\n * field; rejection means Service Definition contract misuse only).\n * @param request - the program, its bindings, and the abort signal; the\n *   request carries everything the runtime acts on, with no hidden defaults.\n * @returns the run\'s outcome: completion value (when transferable), the\n *   ordered log capture, and the failure (if any).\n */',
       },
     ],
   },
@@ -804,7 +804,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'enter(session: Session): () => void',
-        jsDoc: '/**\n * Enter a {@link prepare}d session into the store: install the module-private\n * append publication hooks and add it to the store. Returns the DETACH\n * disposer (hooks + store removal). Does NOT emit `session/created` —\n * the caller yields this disposer inside its effect and THEN calls\n * {@link announce}, so a throwing `session/created` listener rolls the attach\n * back instead of leaking it.\n *\n * Re-checks the id for a duplicate: `prepare` and `enter` are public\n * cross-package primitives and a caller may interleave arbitrary work (or\n * another create) between them, so a stale prepared session must NOT overwrite\n * a live store entry of the same id — its detach disposer would later delete\n * the REAL session. The {@link create} convenience and the agent factory call\n * the two back-to-back so they never trip this, but the public seam cannot\n * assume that.\n *\n * @param session - a {@link prepare}d session not yet in the store.\n * @returns the detach disposer (publication hooks + store removal). When called from\n *   a synchronous `session/created` listener, removal and disposal wait until\n *   that creation dispatch unwinds.\n * @throws if a session with this id is already in the store.\n */',
+        jsDoc: '/**\n * Enter a {@link prepare}d session into the store: install the module-private\n * append publication hooks and add it to the store. Returns the DETACH\n * disposer (hooks + store removal). Does NOT emit `session/created` —\n * the caller yields this disposer inside its effect and THEN calls\n * {@link announce}, so a throwing `session/created` listener rolls the attach\n * back instead of leaking it.\n *\n * Re-checks the id for a duplicate: `prepare` and `enter` are public\n * cross-package primitives and a caller may interleave arbitrary work (or\n * another create) between them, so a stale prepared session must NOT overwrite\n * a live store entry of the same id — its detach disposer would later delete\n * the REAL session. The {@link create} convenience and the agent factory call\n * the two back-to-back so they never trip this, but the public API cannot\n * assume that.\n *\n * @param session - a {@link prepare}d session not yet in the store.\n * @returns the detach disposer (publication hooks + store removal). When called from\n *   a synchronous `session/created` listener, removal and disposal wait until\n *   that creation dispatch unwinds.\n * @throws if a session with this id is already in the store.\n */',
       },
       {
         signature: 'announce(session: Session): void',
@@ -982,7 +982,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>',
-        jsDoc: '/**\n * Enumerate the parent\'s direct session-backed subagents without loading or\n * resuming an Agent and without any query seam: the listing merges the live\n * session store with optional session persistence (live-preferred) and\n * serves each child\'s durable mode/label from the registered `subagent`\n * projection unit down a three-rung ladder — the registry\'s watermark\n * snapshot for a live child; for a cold one, a durable projection-cache\n * row when the optional cache serves an own-suffix identity (its `seq`\n * gate proves the value postdates the fork seed, where a child\'s own\n * descriptor is immutable once appended), else one persistence inspection\n * folded through the registry. The\n * projection fold is the single classification authority; per-child\n * diagnostics relay a fold that served no identity or a failed inspection,\n * never a list-time descriptor parse. Absent persistence, enumeration is\n * live-only (a cold child cannot be resumed then either, so its absence is\n * capability absence, not an error). This service consults no Agent\n * registrations, Activations, or providers.\n *\n * Every persistence read receives `signal`, and the listing rechecks\n * cancellation around each of those awaits. Read rejections that settle\n * after an abort become a stable `SubagentError` with code `CANCELLED`.\n * @param parentSessionId - parent session whose direct children are listed.\n * @param signal - caller-owned cancellation forwarded to persistence reads\n *   and observed around every read await.\n * @returns children and per-child diagnostics ordered by `createdAt`, then id.\n * @throws {@link SubagentError} when the projection registry or the session\n *   store is not mounted, or the caller cancels the listing.\n */',
+        jsDoc: '/**\n * Enumerate the parent\'s direct session-backed subagents without loading or\n * resuming an Agent and without any query service: the listing merges the live\n * session store with optional session persistence (live-preferred) and\n * serves each child\'s durable mode/label from the registered `subagent`\n * projection unit down a three-rung ladder — the registry\'s watermark\n * snapshot for a live child; for a cold one, a durable projection-cache\n * row when the optional cache serves an own-suffix identity (its `seq`\n * gate proves the value postdates the fork seed, where a child\'s own\n * descriptor is immutable once appended), else one persistence inspection\n * folded through the registry. The\n * projection fold is the single classification authority; per-child\n * diagnostics relay a fold that served no identity or a failed inspection,\n * never a list-time descriptor parse. Absent persistence, enumeration is\n * live-only (a cold child cannot be resumed then either, so its absence is\n * capability absence, not an error). This service consults no Agent\n * registrations, Activations, or providers.\n *\n * Every persistence read receives `signal`, and the listing rechecks\n * cancellation around each of those awaits. Read rejections that settle\n * after an abort become a stable `SubagentError` with code `CANCELLED`.\n * @param parentSessionId - parent session whose direct children are listed.\n * @param signal - caller-owned cancellation forwarded to persistence reads\n *   and observed around every read await.\n * @returns children and per-child diagnostics ordered by `createdAt`, then id.\n * @throws {@link SubagentError} when the projection registry or the session\n *   store is not mounted, or the caller cancels the listing.\n */',
       },
       {
         signature: 'listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>',
@@ -1094,7 +1094,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'abstract emit(record: TelemetryRecord): void',
-        jsDoc: '/**\n * See {@link TelemetryBackend.emit} — the seam declaration is the contract\'s one home.\n * @param record - the logical record to report; owned by the backend after the call.\n */',
+        jsDoc: '/**\n * See {@link TelemetryBackend.emit} — that declaration is the contract\'s one home.\n * @param record - the logical record to report; owned by the backend after the call.\n */',
       },
       {
         signature: 'flush?(): void',
@@ -1254,7 +1254,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'workflows',
-    summary: 'Workflow execution seam.',
+    summary: 'Workflow Service Definition contract.',
     methods: [
       {
         signature: 'abstract start(request: WorkflowStartRequest): WorkflowRun',
@@ -1307,7 +1307,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/created',
     mode: 'emit',
     signature: '\'agent/created\'(this: Scoped<Agent>, payload: { agent: Agent }): void',
-    jsDoc: '/**\n * A fully configured agent and live session were published. Setup is\n * composition-only; `agent/session-start` is the first startup-driving seam.\n * Synchronous listener failure vetoes publication, while returned-promise\n * rejection is reported. Detach requested during dispatch waits until every\n * creation listener has observed the stable entry.\n * @param payload.agent - the newly registered agent with its live session and completed setup.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    jsDoc: '/**\n * A fully configured agent and live session were published. Setup is\n * composition-only; `agent/session-start` is the first startup-driving extension point.\n * Synchronous listener failure vetoes publication, while returned-promise\n * rejection is reported. Detach requested during dispatch waits until every\n * creation listener has observed the stable entry.\n * @param payload.agent - the newly registered agent with its live session and completed setup.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'A fully configured agent and live session were published.',
   },
   {
@@ -1356,7 +1356,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/request',
     mode: 'waterfall',
     signature: '\'agent/request\'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>',
-    jsDoc: '/**\n * Replace the frozen call configuration. `await next()` yields the config\n * the machine would use (agent options on the first request, the logged\n * header afterwards); return a replacement to switch. Model-visible\n * content must use logged channels; this seam cannot mutate messages.\n * @param payload.agent - the agent making the model call.\n * @param payload.turn - the open turn number.\n * @param payload.step - the step whose request this is.\n * @param payload.signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n*/',
+    jsDoc: '/**\n * Replace the frozen call configuration. `await next()` yields the config\n * the machine would use (agent options on the first request, the logged\n * header afterwards); return a replacement to switch. Model-visible\n * content must use logged channels; this waterfall cannot mutate messages.\n * @param payload.agent - the agent making the model call.\n * @param payload.turn - the open turn number.\n * @param payload.step - the step whose request this is.\n * @param payload.signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n*/',
     summary: 'Replace the frozen call configuration.',
   },
   {
@@ -1552,7 +1552,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'telemetry/record',
     mode: 'waterfall',
     signature: '\'telemetry/record\'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord',
-    jsDoc: '/**\n * Transform one outbound record before it reaches the backend. This\n * waterfall is the seam\'s redaction extension point. It ships NO rules\n * of its own: the\n * innermost `next()` passes the record through unchanged, and with no\n * listener mounted records reach the backend as captured, so exported\n * data is exactly as clean as the rules a deployment mounts. Listeners\n * stack by transforming `next()`\'s return value; returning without\n * `next()` replaces everything beneath. Dispatched synchronously on the\n * capture hot path inside the coordinator\'s containment: a throwing\n * listener withholds that one record (fail-closed) and never reaches the\n * agent loop. Live capture dispatches at append time; on-demand capture\n * dispatches while reading the canonical log. Redaction applies to the\n * exported copy only; the canonical session log is never rewritten.\n * @param record - the candidate record, already the coordinator\'s own deep\n *   copy; listeners return a (possibly new) record and must not mutate it.\n * @mode waterfall\n */',
+    jsDoc: '/**\n * Transform one outbound record before it reaches the backend. This\n * waterfall is the Service Definition\'s redaction extension point. It ships NO rules\n * of its own: the\n * innermost `next()` passes the record through unchanged, and with no\n * listener mounted records reach the backend as captured, so exported\n * data is exactly as clean as the rules a deployment mounts. Listeners\n * stack by transforming `next()`\'s return value; returning without\n * `next()` replaces everything beneath. Dispatched synchronously on the\n * capture hot path inside the coordinator\'s containment: a throwing\n * listener withholds that one record (fail-closed) and never reaches the\n * agent loop. Live capture dispatches at append time; on-demand capture\n * dispatches while reading the canonical log. Redaction applies to the\n * exported copy only; the canonical session log is never rewritten.\n * @param record - the candidate record, already the coordinator\'s own deep\n *   copy; listeners return a (possibly new) record and must not mutate it.\n * @mode waterfall\n */',
     summary: 'Transform one outbound record before it reaches the backend.',
   },
   {
@@ -1580,7 +1580,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'tools/post-execute',
     mode: 'waterfall',
     signature: '\'tools/post-execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>',
-    jsDoc: '/**\n * Accept, replace, enrich, or block a normalized dispatch result. `next()`\n * accepts it unchanged; thrown tools still reach this seam as errors. Async\n * listeners must observe `exec.signal`; after they settle, caller\n * cancellation replaces only a successful accepted outcome with the code\n * selected by whether the tool body was invoked.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent\'s calls.\n * @param exec - the call that just ran (name, parsed arguments, caller agent).\n * @param result - the dispatch outcome a listener may accept, replace, or block.\n * @mode waterfall\n */',
+    jsDoc: '/**\n * Accept, replace, enrich, or block a normalized dispatch result. `next()`\n * accepts it unchanged; thrown tools still reach this waterfall as errors. Async\n * listeners must observe `exec.signal`; after they settle, caller\n * cancellation replaces only a successful accepted outcome with the code\n * selected by whether the tool body was invoked.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent\'s calls.\n * @param exec - the call that just ran (name, parsed arguments, caller agent).\n * @param result - the dispatch outcome a listener may accept, replace, or block.\n * @mode waterfall\n */',
     summary: 'Accept, replace, enrich, or block a normalized dispatch result.',
   },
   {
diff --git a/packages/session-query/session-query-sqlite/README.i18n.yaml b/packages/session-query/session-query-sqlite/README.i18n.yaml
index 75fff04fcd..ce1fae24c9 100644
--- a/packages/session-query/session-query-sqlite/README.i18n.yaml
+++ b/packages/session-query/session-query-sqlite/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/session-query/session-query-sqlite/README.md
-README.md: 4bf4d979f2d2954cd6280c80bf7f5988d8121fd1
-README.zh.md: 56f7dfa8bad3a04a6bf17eac08b62a1a11f4d53f
+README.md: dbbb63e9dd18f3c68cc21b84b560403f4a508709
+README.zh.md: 0b183f63ad2f3cfa670babca80d6e4abee6a4bcb
diff --git a/packages/session-query/session-query-sqlite/README.md b/packages/session-query/session-query-sqlite/README.md
index 4bf4d979f2..dbbb63e9dd 100644
--- a/packages/session-query/session-query-sqlite/README.md
+++ b/packages/session-query/session-query-sqlite/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Concrete `ctx.sessionQuery` backend. `SessionQuerySqlite` inherits exact reads, traces, and provider-independent filters from the interface package and implements its two full-text methods with SQLite FTS5. Search uses the live-preferred logical session corpus and groups cross-session results by their strongest event.
+Concrete `ctx.sessionQuery` provider. `SessionQuerySqlite` inherits exact reads, traces, and provider-independent filters from the Service Definition package and implements its two full-text methods with SQLite FTS5. Search uses the live-preferred logical session corpus and groups cross-session results by their strongest event.
 
 ## Search contract
 
diff --git a/packages/session-query/session-query-sqlite/README.zh.md b/packages/session-query/session-query-sqlite/README.zh.md
index 56f7dfa8ba..0b183f63ad 100644
--- a/packages/session-query/session-query-sqlite/README.zh.md
+++ b/packages/session-query/session-query-sqlite/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-具体 `ctx.sessionQuery` 后端。`SessionQuerySqlite` 从接口包继承精确读取、跟踪和提供方无关的过滤，并使用 SQLite FTS5 实现其两个全文方法。搜索使用实时优先的逻辑会话语料库，并按每个会话中匹配度最高的事件对跨会话结果分组。
+具体 `ctx.sessionQuery` 提供方。`SessionQuerySqlite` 从 Service Definition 包继承精确读取、跟踪和提供方无关的过滤，并使用 SQLite FTS5 实现其两个全文方法。搜索使用实时优先的逻辑会话语料库，并按每个会话中匹配度最高的事件对跨会话结果分组。
 
 ## 搜索约定
 
diff --git a/packages/session-query/session-query/src/index.ts b/packages/session-query/session-query/src/index.ts
index f2c6b57c66..b891f5750d 100644
--- a/packages/session-query/session-query/src/index.ts
+++ b/packages/session-query/session-query/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Combined session-history reads, traces, filters, and full-text search seam.
+ * Service Definition for combined session-history reads, traces, filters, and full-text search.
  *
  * @module @deepseek-ai/dsh-session-query
  */
diff --git a/packages/session/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
index 3534382316..8d4aad8e7a 100644
--- a/packages/session/session-persistence-jsonl/src/index.ts
+++ b/packages/session/session-persistence-jsonl/src/index.ts
@@ -161,7 +161,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
   }
 
   // Each backend keeps the typed service surface beside its storage hooks;
-  // extracting these trivial forwards would add an inheritance seam.
+  // extracting these trivial forwards would add an inheritance layer.
   /* jscpd:ignore-start */
   // --- SessionPersistence service surface (delegated to the coordinator) ---
 
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index 41cd655b31..0f5de36bc2 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/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/session/session-persistence-sqlite/README.md
-README.md: 4961f62bf6854c343d35b8406c9d721590274534
-README.zh.md: 0507e0fa99bc553317c34e51f30e4daaceee93fd
+README.md: 745c25616e06c391a70b37471917aa9d2539c4dd
+README.zh.md: c86531bcaeca85fa565b537f1fc1beca5d6ac7b3
diff --git a/packages/session/session-persistence-sqlite/README.md b/packages/session/session-persistence-sqlite/README.md
index 4961f62bf6..745c25616e 100644
--- a/packages/session/session-persistence-sqlite/README.md
+++ b/packages/session/session-persistence-sqlite/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-A SQLite durable session-persistence backend — a second `SessionPersistence` implementation ([session persistence](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)), built to validate that the abstract seam and the shared `runPersistenceContract` suite are genuinely backend-agnostic. It satisfies the SAME contract as `dsh-session-persistence-jsonl` (append-only, contiguous-seq, lazy materialization, interrupted-turn close on load), expressed over `node:sqlite` rows instead of file bytes.
+A SQLite durable session-persistence backend — a second `SessionPersistence` provider ([session persistence](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)), built to validate that the Service Definition and the shared `runPersistenceContract` suite are genuinely backend-agnostic. It satisfies the SAME contract as `dsh-session-persistence-jsonl` (append-only, contiguous-seq, lazy materialization, interrupted-turn close on load), expressed over `node:sqlite` rows instead of file bytes.
 
 `locate(meta)` returns `undefined`: all sessions share one database, so there is no honest independent per-session transcript path.
 
diff --git a/packages/session/session-persistence-sqlite/README.zh.md b/packages/session/session-persistence-sqlite/README.zh.md
index 0507e0fa99..c86531bcae 100644
--- a/packages/session/session-persistence-sqlite/README.zh.md
+++ b/packages/session/session-persistence-sqlite/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证抽象 seam 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的约定（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
+SQLite 持久会话存储后端：第二个 `SessionPersistence` 提供方（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证 Service Definition 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的约定（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
 
 `locate(meta)` 返回 `undefined`：所有会话共享一个数据库，因此不存在真实、独立的逐会话 transcript（文本记录）路径。
 
@@ -22,7 +22,7 @@ SQLite 持久会话存储后端：第二个 `SessionPersistence` 实现（见[
 - **延迟实体化。**`create()` 只在内存记录意图，第一次 `append` 前不写行。从未 append 的会话没有 `sessions` 行，因此不在 `list()` 中（它精确报告有行的会话）。
 - **在 load 时关闭中断轮次。**`load()` 实现共享[崩溃恢复约定](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)：保留有效中断轮次，在一个事务中追加合成关闭事件，并只移除撕裂尾部行。已提交解析错误或序列缺口使会话无法加载。恢复会变更已存储行，因此下一次 append 从平衡日志和准确游标开始。
 - **非变更检查。**`inspect()` 返回不可变、平衡的逻辑视图，并可在内存中合成恢复 closer，但不会删除撕裂尾部行、追加恢复行或更改轻量修订。
-- **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。完整前缀读取在同一个读事务中捕获该修订及其事件行，`readStoredRevision()` 则只查询会话行来校验保留的准备结果。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
+- **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。完整前缀读取在同一个读事务中捕获该 revision 及其事件行，`readStoredRevision()` 则只查询 session 行来校验保留的 preparation。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
 
 ## 配置（schemastery）
 
@@ -37,7 +37,7 @@ interface Config {
 
 ## 写入路径
 
-与 JSONL 后端一样，插件将每个冻结的 `session/event` 复制到每个活动会话各自的 controller。第一个待处理事件会开启配置的固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个事务；该次写入期间接纳的事件会形成另一个独立有界的后续批次。`session/flush` 会取消等待并排空当前与待处理批次。Controller 会持久化一次 fork 种子，并保留写入游标，使恢复操作绝不重新 append 已存储事件；它还会在 apply 时为活动会话设置初始状态，因为 HMR（热模块替换）不回放 `session/created`。dispose（资源释放）会在关闭数据库前排空每个保留的 controller。每个事件仍各占一行 SQLite 记录；批处理只把更多 INSERT 归入同一个事务和同一次修订递增。
+与 JSONL 后端一样，插件将每个冻结的 `session/event` 复制到每个活动会话各自的 controller。第一个待处理事件会开启配置的固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个事务；该次写入期间接纳的事件会形成另一个独立有界的后续批次。`session/flush` 会取消等待并排空当前与待处理批次。Controller 会持久化一次 fork 种子，并保留写入游标，使恢复操作绝不重新 append 已存储事件；它还会在 apply 时为活动会话设置初始状态，因为 HMR（热模块替换）不回放 `session/created`。dispose（资源释放）会在关闭数据库前排空每个保留的 controller。每个事件仍各占一行 SQLite 记录；批处理只把更多 INSERT 归入同一个事务和同一次修订版本递增。
 
 ## 模型体验
 
diff --git a/packages/session/session-persistence/README.i18n.yaml b/packages/session/session-persistence/README.i18n.yaml
index 8341e48a1e..74a0d4c8a9 100644
--- a/packages/session/session-persistence/README.i18n.yaml
+++ b/packages/session/session-persistence/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/session/session-persistence/README.md
-README.md: 29ee219a55d0823f03bb512c0fa37b7e249817eb
-README.zh.md: c750d2f85fd267a94c36770452f1e5c7e647a2fb
+README.md: c64826db1e9c7339f43a64ad7c13f01a2a39638e
+README.zh.md: 651d920404300fa602f77cee63b0f31aec837919
diff --git a/packages/session/session-persistence/README.md b/packages/session/session-persistence/README.md
index 29ee219a55..c64826db1e 100644
--- a/packages/session/session-persistence/README.md
+++ b/packages/session/session-persistence/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The abstract durable session-persistence seam (`ctx.sessionPersistence`). Defines WHAT a persistence backend does — durably store, reload, and list sessions — without saying HOW. Mirrors the `dsh-bash` capability-seam template ([capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract service here, a concrete implementation in a sibling package, consumers that inject the interface.
+The durable session-persistence Service Definition (`ctx.sessionPersistence`). Defines WHAT a persistence backend does — durably store, reload, and list sessions — without saying HOW. Mirrors the `dsh-bash` capability-seam template ([capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract service here, a Service provider in a sibling package, and Consumers that inject the service.
 
 The persisted unit IS the existing `SessionEvent` (event-sourced model — the log is the single source of truth), so there is no parallel "persisted message" type. Metadata that is NOT replayable conversation state (format version, cwd, lineage, seed boundary, origin, delegation depth) travels separately as `SessionHeader`, owned by `dsh-session` and re-exported here.
 
@@ -41,7 +41,7 @@ When a live session emits `session/disposed`, the coordinator waits for its cont
 
 The side-effect-free `locate`, lightweight `listSnapshots`, and per-id `readStoredRevision` queries remain backend-owned because they describe storage topology and revision identity rather than write orchestration. `listSnapshots(signal?)` passes the caller's exact signal into backend discovery so observers can cancel that work without detaching it.
 
-The `PersistenceBackend<TornMarker>` hooks (the only seam between the coordinator and storage):
+The `PersistenceBackend<TornMarker>` hooks (the only contract between the coordinator and storage):
 
 | Hook | Role |
 |---|---|
diff --git a/packages/session/session-persistence/README.zh.md b/packages/session/session-persistence/README.zh.md
index c750d2f85f..651d920404 100644
--- a/packages/session/session-persistence/README.zh.md
+++ b/packages/session/session-persistence/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这是用于持久保存会话的抽象 seam（`ctx.sessionPersistence`）。它定义持久化后端做什么：持久存储、重新加载和列出会话，而不规定如何实现。它与 `dsh-bash` 能力 seam 模板一致（见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：本包提供抽象服务，同级包提供具体实现，消费方注入接口。
+这是用于持久保存会话的 Service Definition（`ctx.sessionPersistence`）。它定义持久化后端做什么：持久存储、重新加载和列出会话，而不规定如何实现。它与 `dsh-bash` 能力 seam 模板一致（见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：本包提供抽象服务，同级包提供 Service provider，Consumer 注入服务。
 
 持久化单元就是现有 `SessionEvent`（事件溯源模型：日志是唯一真源），因此不存在另一套并行的「持久消息」类型。不属于可回放对话状态的元数据（格式版本、cwd、血缘、种子边界、origin、委托深度）作为 `SessionHeader` 单独传输，该类型归 `dsh-session` 所有，并在此重新导出。
 
@@ -41,7 +41,7 @@
 
 无副作用 `locate`、轻量 `listSnapshots` 和按 id 查询的 `readStoredRevision` 仍由后端负责，因为它们描述存储拓扑和修订身份，而非写入编排。`listSnapshots(signal?)` 将调用方传入的同一个信号传给后端发现流程，使观察者可在不脱离该工作的情况下取消。
 
-`PersistenceBackend<TornMarker>` 钩子（协调器与存储之间的唯一 seam）：
+`PersistenceBackend<TornMarker>` 钩子（协调器与存储之间的唯一约定）：
 
 | 钩子 | 职责 |
 |---|---|
diff --git a/packages/session/session-persistence/src/coordinator.ts b/packages/session/session-persistence/src/coordinator.ts
index cf013887d3..ec4fb72aeb 100644
--- a/packages/session/session-persistence/src/coordinator.ts
+++ b/packages/session/session-persistence/src/coordinator.ts
@@ -78,7 +78,7 @@ export interface StoredSuffix {
 }
 
 /**
- * The storage seam between {@link PersistenceCoordinator} and a concrete
+ * The storage contract between {@link PersistenceCoordinator} and a concrete
  * backend: the minimal set of durable primitives the orchestration calls. A
  * backend implements these (over files, rows, an object store, …); the
  * coordinator supplies everything else (buffering, serialization, cursors,
diff --git a/packages/session/session-persistence/src/index.ts b/packages/session/session-persistence/src/index.ts
index 1d1cf01331..5c3df73b30 100644
--- a/packages/session/session-persistence/src/index.ts
+++ b/packages/session/session-persistence/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Durable session-persistence seam (`ctx.sessionPersistence`). Backends store
+ * Durable session-persistence Service Definition (`ctx.sessionPersistence`). Backends store
  * {@link SessionEvent}s as the event-sourced log and carry non-replayable
  * {@link SessionHeader} metadata separately.
  * @module @deepseek-ai/dsh-session-persistence
@@ -10,7 +10,7 @@ import { SessionPreparation } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 import type { SessionPersistenceRevision } from './revision.ts'
 
-// Re-export the metadata vocabulary so consumers import it from the seam.
+// Re-export the metadata vocabulary so Consumers import it from the Service Definition.
 export type { SessionHeader } from '@deepseek-ai/dsh-session'
 export { SessionPersistenceRevision } from './revision.ts'
 
diff --git a/packages/session/session-persistence/tests/persistence.spec.ts b/packages/session/session-persistence/tests/persistence.spec.ts
index 75455abe81..d3e715b085 100644
--- a/packages/session/session-persistence/tests/persistence.spec.ts
+++ b/packages/session/session-persistence/tests/persistence.spec.ts
@@ -1279,7 +1279,7 @@ describe('PersistenceCoordinator observation cancellation', () => {
       }
       const suffix = await coordinator.readFrom(id, 3)
       expect(suffix.events).toEqual(log.slice(3))
-      // The hook's undefined is the seam's not-found.
+      // The hook's `undefined` is the backend contract's not-found result.
       await expect(coordinator.readFrom(SessionId('missing-seek'), 0)).rejects.toThrow('not found')
 
       // A hook failure with no cancellation in play propagates as-is.
diff --git a/packages/session/session-projection/README.i18n.yaml b/packages/session/session-projection/README.i18n.yaml
index a39e3c8586..c7b7530b09 100644
--- a/packages/session/session-projection/README.i18n.yaml
+++ b/packages/session/session-projection/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/session/session-projection/README.md
-README.md: a42e88c262915fc5e53cd72205079cbc8029a8df
-README.zh.md: 01b23a7152a509efab6e169043a823d49d6d9fde
+README.md: 2615b253999c798172168ec9d0232eb965b07fbc
+README.zh.md: 0712e9c7a61fbcf43939791b3e7cd24af6777c3a
diff --git a/packages/session/session-projection/README.md b/packages/session/session-projection/README.md
index a42e88c262..2615b25399 100644
--- a/packages/session/session-projection/README.md
+++ b/packages/session/session-projection/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Session-projection seam. It owns `ctx.sessionProjections`, the registry that drives every registered projection unit over committed session events and serves finished whole values to carriers, currently the api-proxy history tail page and `session/projection` push frame. A domain registers pure mathematics; the framework owns the drive. The [session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) records the design rationale.
+Session-projection Service Definition and drive registry. It owns `ctx.sessionProjections`, the registry that drives every registered projection unit over committed session events and serves finished whole values to carriers, currently the api-proxy history tail page and `session/projection` push frame. A domain registers pure mathematics; the framework owns the drive. The [session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) records the design rationale.
 
 ## Service: `SessionProjectionRegistry` (ctx key: `sessionProjections`)
 
@@ -25,11 +25,11 @@ Session-projection seam. It owns `ctx.sessionProjections`, the registry that dri
 - **Synchronous unit discipline.** `init`/`apply`/`view` MUST be synchronous; carriers read `snapshot()` in the same tick as their page slice, which is what makes `asOfSeq` one consistent cut. An accidentally-async `view` returns a Promise, which fails the boundary `schema.parse` loudly.
 - **State is plain JSON, `stateVersion` is its invalidation anchor.** The persisted projection cache stores `(sessionId, key, ver, seq, val)` rows; bump `stateVersion` whenever the state shape or the fold semantics change so stale rows are discarded instead of forward-applied into garbage.
 - **No wire vocabulary here.** The registry exposes only the change feed and the snapshot read face; carriers (api-proxy) mint their own frames (`session/projection`) and blocks from them.
-- **Optional seam.** Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected; carriers use `ctx.get('sessionProjections')` and omit their block/frames entirely when the registry is absent.
+- **Optional capability.** Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected; carriers use `ctx.get('sessionProjections')` and omit their block/frames entirely when the registry is absent.
 
 ## Role
 
-This is the interface-plus-drive package of the capability-seam split: domain host plugins (e.g. `dsh-tool-todo`) contribute units, carriers (`dsh-host-apiproxy`) consume the snapshot and change feed, and neither knows the other.
+This package owns the Service Definition and drive roles of the capability seam: domain host plugins (e.g. `dsh-tool-todo`) contribute units, carriers (`dsh-host-apiproxy`) consume the snapshot and change feed, and neither knows the other.
 
 ## Model Experience
 
diff --git a/packages/session/session-projection/README.zh.md b/packages/session/session-projection/README.zh.md
index 01b23a7152..0712e9c7a6 100644
--- a/packages/session/session-projection/README.zh.md
+++ b/packages/session/session-projection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-会话投影 seam。它拥有 `ctx.sessionProjections`：该注册表在已提交的会话事件上驱动每个已注册的投影单元，并向载体提供完整的最终值，目前包括 api-proxy 历史尾页和 `session/projection` 推送帧。领域注册的只是纯数学；驱动权归框架。[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) 记录了设计理由。
+会话投影 Service Definition 与驱动注册表。它拥有 `ctx.sessionProjections`：该注册表在已提交的会话事件上驱动每个已注册的投影单元，并向载体提供完整的最终值，目前包括 api-proxy 历史尾页和 `session/projection` 推送帧。领域注册的只是纯数学；驱动权归框架。[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)记录了设计理由。
 
 ## 服务：`SessionProjectionRegistry`（ctx 键：`sessionProjections`）
 
@@ -25,11 +25,11 @@
 - **单元的同步纪律。**`init`/`apply`/`view` 必须是同步的；载体在切出页面切片的同一 tick 内读取 `snapshot()`，`asOfSeq` 之所以是一个一致切面正系于此。误写成异步的 `view` 会返回 Promise，让边界的 `schema.parse` 当场大声失败。
 - **状态是纯 JSON，`stateVersion` 是其失效锚点。** 持久投影缓存（persisted projection cache）存储 `(sessionId, key, ver, seq, val)` 行；状态形状或折叠语义一旦变化就递增 `stateVersion`，使陈旧行被丢弃，而不是被正向 apply 成垃圾。
 - **本层没有协议词汇。** 注册表只暴露变更流与快照读取面；载体（api-proxy）据此自铸各自的帧（`session/projection`）与块。
-- **可选 seam。** 领域插件在 `ctx.inject(['sessionProjections'], …)` 下注册，因此不带注册表的 headless 组装完全不受影响；载体使用 `ctx.get('sessionProjections')`，注册表缺席时完全省略自己的块与帧。
+- **可选能力。** 领域插件在 `ctx.inject(['sessionProjections'], …)` 下注册，因此不带注册表的 headless 组装完全不受影响；载体使用 `ctx.get('sessionProjections')`，注册表缺席时完全省略自己的块与帧。
 
 ## 职责
 
-这是能力 seam 拆分中「接口 + 驱动」的那个包：领域 host 插件（如 `dsh-tool-todo`）贡献单元，载体（`dsh-host-apiproxy`）消费快照与变更流，两侧互不相识。
+本包承担能力 seam 的 Service Definition 与驱动角色：领域 host 插件（如 `dsh-tool-todo`）贡献单元，载体（`dsh-host-apiproxy`）消费快照与变更流，两侧互不相识。
 
 ## 模型体验
 
diff --git a/packages/session/session-projection/src/index.ts b/packages/session/session-projection/src/index.ts
index 90c36ed579..208c850363 100644
--- a/packages/session/session-projection/src/index.ts
+++ b/packages/session/session-projection/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Session-projection seam: the merge-extensible `SessionProjectionMap` type
+ * Service Definition and drive registry for the session-projection capability seam: the merge-extensible `SessionProjectionMap` type
  * table, the `ProjectionDefinition` state-driven computation unit contract,
  * and the `ctx.sessionProjections` registry that DRIVES every registered unit
  * forward eagerly over committed session events. Domain host plugins
@@ -117,7 +117,7 @@ export interface ProjectionCheckpointRow {
 /** Checkpoint rows keyed by projection key (one session's persisted cache value). */
 export type ProjectionCheckpoint = Record<string, ProjectionCheckpointRow>
 
-/** Type-erased unit view the drive machinery works with (the register seam already proved the typed contract). */
+/** Type-erased unit view the drive machinery works with (the registration contract already proved the typed form). */
 interface ErasedDefinition {
   key: string
   schema: { parse(value: unknown): unknown }
diff --git a/packages/session/session-projection/src/types.ts b/packages/session/session-projection/src/types.ts
index 39f2aa24e2..37d24b5b40 100644
--- a/packages/session/session-projection/src/types.ts
+++ b/packages/session/session-projection/src/types.ts
@@ -1,5 +1,5 @@
 /**
- * Pure-type outlet of the session-projection seam: the one projection type
+ * Pure-type outlet of the session-projection Service Definition: the one projection type
  * table, importable from client aggregates without dragging the host-side
  * cordis Context merges of the package root (dsh-agent → dsh-session). Domain
  * packages may declare-merge through either the package root or this outlet —
diff --git a/packages/session/session-telemetry-otel/src/index.ts b/packages/session/session-telemetry-otel/src/index.ts
index 4f146bdb95..37ba236477 100644
--- a/packages/session/session-telemetry-otel/src/index.ts
+++ b/packages/session/session-telemetry-otel/src/index.ts
@@ -1,9 +1,9 @@
 /**
- * OpenTelemetry backend for the DeepSeek Harness telemetry seam.
+ * OpenTelemetry Service provider for the DeepSeek Harness telemetry capability.
  *
  * Composes the OTel JS SDK as-is — a `LoggerProvider` with a
  * `BatchLogRecordProcessor` and an OTLP/HTTP log exporter — and maps each
- * record handed over by the seam onto `logger.emit()`. Per the seam's
+ * record handed over by the capture coordinator onto `logger.emit()`. Per the Service Definition's
  * boundary axiom, everything downstream of that call (batching, retry,
  * queueing, loss policy) is the SDK's documented behavior, configured
  * verbatim through the `exporter`/`processor` passthroughs. This package owns
@@ -121,7 +121,7 @@ export const DEFAULT_SHUTDOWN_TIMEOUT_MILLIS = 3_000
 // protocol limit, not a deployment default.
 const MAX_TIMER_DELAY_MILLIS = 2_147_483_647
 
-/** Severity mapping from the seam's three-level vocabulary to OTel severity numbers. */
+/** Severity mapping from the Service Definition's three-level vocabulary to OTel severity numbers. */
 const SEVERITY: Record<TelemetrySeverity, { severityNumber: SeverityNumber; severityText: string }> = {
   info: { severityNumber: SeverityNumber.INFO, severityText: 'INFO' },
   warn: { severityNumber: SeverityNumber.WARN, severityText: 'WARN' },
@@ -250,7 +250,7 @@ export class TelemetryOtel extends Telemetry {
     this.directEmit(record)
   }
 
-  // The seam's optional flush() hint is deliberately NOT implemented. The
+  // The Service Definition's optional flush() hint is deliberately NOT implemented. The
   // batch processor exports on its own cadence (`processor.scheduledDelayMillis`,
   // the SDK's documented knob), and this backend is the SDK pipeline's only
   // caller — forwarding the hint to `forceFlush()` was the sole source of
diff --git a/packages/session/session-telemetry-otel/src/invariant.ts b/packages/session/session-telemetry-otel/src/invariant.ts
index 030b7ce670..0eaffeb8b5 100644
--- a/packages/session/session-telemetry-otel/src/invariant.ts
+++ b/packages/session/session-telemetry-otel/src/invariant.ts
@@ -17,7 +17,7 @@ export const inject = ['invariants']
 /**
  * No runtime invariant: mode selection changes capture handoff, SDK setup, and
  * local diagnostics without mutating session or service state an independent
- * companion can compare. Export remains inside the SDK past the seam boundary.
+ * companion can compare. Export remains inside the SDK past the backend boundary.
  */
 const install: InvariantInstaller = () => {}
 
diff --git a/packages/session/session-telemetry-otel/src/user-id.ts b/packages/session/session-telemetry-otel/src/user-id.ts
index f06d9856fe..0a2cf95a6a 100644
--- a/packages/session/session-telemetry-otel/src/user-id.ts
+++ b/packages/session/session-telemetry-otel/src/user-id.ts
@@ -33,11 +33,11 @@ export const USER_ID_FILE_NAME = '.userid'
 
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
-/** Ambient seams for locating and generating the id; every field has a default. */
+/** Ambient hooks for locating and generating the id; every field has a default. */
 export interface AnonymousUserIdOptions {
   /** Environment consulted for `DSH_HOME`; defaults to `process.env`. */
   env?: NodeJS.ProcessEnv
-  /** UUID generator; defaults to `crypto.randomUUID` (test seam). */
+  /** UUID generator; defaults to `crypto.randomUUID` (test hook). */
   randomUUID?: () => string
 }
 
@@ -65,7 +65,7 @@ function readPersistedId(file: string): AnonymousUserId | undefined {
  * run; the next launch converges on the persisted one.) Persistence is
  * best-effort — a write failure (read-only home) still returns a usable id
  * for the current run so telemetry is never blocked.
- * @param options - home-location and UUID-generation seams.
+ * @param options - Home-location and UUID-generation hooks.
  * @returns the stable per-harness-home anonymous user id.
  */
 export function getOrCreateAnonymousUserId(options: AnonymousUserIdOptions = {}): AnonymousUserId {
diff --git a/packages/session/session-telemetry-otel/tests/user-id.spec.ts b/packages/session/session-telemetry-otel/tests/user-id.spec.ts
index f4d9505546..63106c7316 100644
--- a/packages/session/session-telemetry-otel/tests/user-id.spec.ts
+++ b/packages/session/session-telemetry-otel/tests/user-id.spec.ts
@@ -57,7 +57,7 @@ describe('getOrCreateAnonymousUserId', () => {
     const home = tempHome()
     const winner = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee'
     const file = join(home, USER_ID_FILE_NAME)
-    // The generator seam runs between the initial read (absent) and the wx
+    // The generator hook runs between the initial read (absent) and the wx
     // write, so planting the winner here simulates the concurrent first launch.
     const id = getOrCreateAnonymousUserId({
       env: { DSH_HOME: home },
diff --git a/packages/session/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml
index 5fd708de38..c6c4b9eff9 100644
--- a/packages/session/session-telemetry/README.i18n.yaml
+++ b/packages/session/session-telemetry/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/session/session-telemetry/README.md
-README.md: 67d95bcc62bbf6783f8dcd11f0236d8c926b557b
-README.zh.md: 80044ceb57c93f8406398a9239d83cbb6015e98c
+README.md: 506f0f5bcb03a54f09805ed0f866a396e3cf0334
+README.zh.md: b5e47c8832452ece281dcdcfac007d6082813583
diff --git a/packages/session/session-telemetry/README.md b/packages/session/session-telemetry/README.md
index 67d95bcc62..506f0f5bcb 100644
--- a/packages/session/session-telemetry/README.md
+++ b/packages/session/session-telemetry/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The telemetry seam: the capture side of session-event reporting, behind a backend contract any reporting SDK satisfies with zero bending. Capture can follow live session events or replay a canonical session-log prefix on demand. The boundary axiom that shapes everything here: **this package's aspect ends at `emit()`** — batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md), [feedback-gated delivery](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md), and [buffer-free feedback replay](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md).
+The telemetry Service Definition and capture coordinator sit behind a backend contract any reporting SDK satisfies with zero bending. Capture can follow live session events or replay a canonical session-log prefix on demand. The boundary axiom that shapes everything here: **this package's aspect ends at `emit()`** — batching, retry, queueing, and loss policy belong to the backend's SDK and are neither specified nor wrapped. Rationale and rejected alternatives: [the revival Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md), [feedback-gated delivery](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md), and [buffer-free feedback replay](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md).
 
 ## The backend contract
 
@@ -14,7 +14,7 @@ In `live` mode the coordinator registers, all through the composing fiber's effe
 
 ## The redact waterfall
 
-Every record passes the `telemetry/record` waterfall immediately after projection — the seam's scrubbing extension point. The seam ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Live capture runs the waterfall at append time; on-demand capture runs it while replaying the canonical log, using the rules mounted at that time. Redaction applies to the outbound copy only; the canonical session log is never rewritten.
+Every record passes the `telemetry/record` waterfall immediately after projection — the Service Definition's scrubbing extension point. This package ships NO rules of its own: the innermost `next()` passes the record through unchanged, so with no listener mounted records reach the backend exactly as captured, and exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath, and a throwing listener withholds that one record fail-closed inside the coordinator's containment. Live capture runs the waterfall at append time; on-demand capture runs it while replaying the canonical log, using the rules mounted at that time. Redaction applies to the outbound copy only; the canonical session log is never rewritten.
 
 ## The handoff cursor
 
@@ -30,7 +30,7 @@ Only the first `assistant/chunk` of each `(turn, step)` ships; the rest are drop
 
 ## Model Experience
 
-None, as the seam only observes the session stream and hands redacted copies to a reporting backend; it never contributes to a model request.
+None, as this package only observes the session stream and hands redacted copies to a reporting backend; it never contributes to a model request.
 
 #### KV Cache effect
 
diff --git a/packages/session/session-telemetry/README.zh.md b/packages/session/session-telemetry/README.zh.md
index 80044ceb57..b5e47c8832 100644
--- a/packages/session/session-telemetry/README.zh.md
+++ b/packages/session/session-telemetry/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-遥测（telemetry）seam：会话事件上报的捕获侧，隔在一个后端约定之后，任何上报 SDK 都无需变形即可满足该约定。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
+遥测（telemetry）Service Definition 与捕获协调器位于一个后端约定之后，任何上报 SDK 都无需变形即可满足该约定。捕获侧可跟随实时会话事件，也可按需回放权威会话日志前缀。塑造本包（package）一切设计的边界公理：**本包的职责止于 `emit()`**。批处理、重试、排队与丢失策略都属于后端自身的 SDK，本包既不为其立规，也不做包装。设计依据与被否决的替代方案见[复活 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)、[反馈门控投递](../../../.agents/notes/implemented/feature/2026-08-05-feedback-gated-session-telemetry.md)与[无缓冲反馈回放](../../../.agents/notes/implemented/simplification/2026-08-06-buffer-free-feedback-telemetry.md)。
 
 ## 后端约定
 
@@ -14,7 +14,7 @@
 
 ## 脱敏 waterfall（瀑布式事件）
 
-每条记录在投影后立即经过 `telemetry/record` waterfall，这是该 seam 的脱敏扩展点。seam 自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。实时捕获在追加时运行 waterfall；按需捕获则在回放权威日志时使用当时挂载的规则运行 waterfall。脱敏只作用于外发副本；权威会话日志永不改写。
+每条记录在投影后立即经过 `telemetry/record` waterfall，这是 Service Definition 的脱敏扩展点。本包自身不带任何规则：最内层的 `next()` 原样透传记录，因此未挂载监听器时，记录以捕获时的原样到达后端；导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 `next()` 的返回值来堆叠；不调用 `next()` 就返回，即替换其下方的全部逻辑；抛出异常的监听器会在协调器的隔离范围内以 fail-closed 方式拦下这一条记录。实时捕获在追加时运行 waterfall；按需捕获则在回放权威日志时使用当时挂载的规则运行 waterfall。脱敏只作用于外发副本；权威会话日志永不改写。
 
 ## handoff 游标
 
@@ -30,7 +30,7 @@
 
 ## 模型体验
 
-无。该 seam 只观察会话流，并把脱敏后的副本交给上报后端；它绝不向模型请求贡献任何内容。
+无。本包只观察会话流，并把脱敏后的副本交给上报后端；它绝不向模型请求贡献任何内容。
 
 #### KV Cache 影响
 
diff --git a/packages/session/session-telemetry/src/coordinator.ts b/packages/session/session-telemetry/src/coordinator.ts
index 4e99859a4f..f06d1b7b9e 100644
--- a/packages/session/session-telemetry/src/coordinator.ts
+++ b/packages/session/session-telemetry/src/coordinator.ts
@@ -1,5 +1,5 @@
 /**
- * Capture coordinator: the seam's upstream half. Live capture subscribes to
+ * Capture coordinator for the telemetry capability. Live capture subscribes to
  * the session firehose plus the one live-bus relay (`agent/error`). Both
  * capture paths apply the fixed chunk projection, build logical records, and
  * run each through the
@@ -159,7 +159,7 @@ export class TelemetryCoordinator {
    * at or below the start still feed the projection state (first-chunk
    * tracking) without being re-handed, so a resumed fiber drops mid-step
    * chunk continuations exactly like the fiber that saw the step begin. The
-   * cost, accepted with the seam's at-most-once stance: a resume no longer
+   * cost, accepted with the capture contract's at-most-once stance: a resume no longer
    * backfills records a previous process failed to deliver.
    * @param session - the live session to adopt; a second adoption is a no-op.
    */
@@ -204,7 +204,7 @@ export class TelemetryCoordinator {
 
   /**
    * Run the `telemetry/record` waterfall at capture time. The innermost `next`
-   * passes the record through unchanged — the seam ships no rules; exported
+   * passes the record through unchanged — this package ships no rules; exported
    * data is as clean as the listeners a deployment mounts. Callers run inside
    * {@link contain}, so a throwing rule withholds the record instead of
    * reaching the loop (fail-closed). On-demand capture invokes this waterfall
@@ -289,7 +289,7 @@ function severityOf(event: SessionEvent): TelemetrySeverity {
     case 'turn/end':
       return event.data.reason.kind === 'error' ? 'error' : 'info'
     default:
-      // Merge-extensible fall-through (no assertNever): event types this seam
+      // Merge-extensible fall-through (no assertNever): event types this coordinator
       // does not depend on — including plugin-merged ones it never heard of —
       // pass through as info; their owners' outcome semantics stay theirs.
       return 'info'
diff --git a/packages/session/session-telemetry/src/index.ts b/packages/session/session-telemetry/src/index.ts
index 6a8e9ed2ad..7606cc3ca6 100644
--- a/packages/session/session-telemetry/src/index.ts
+++ b/packages/session/session-telemetry/src/index.ts
@@ -1,7 +1,7 @@
 /**
- * Telemetry seam for the DeepSeek Harness.
+ * Telemetry Service Definition for the DeepSeek Harness.
  *
- * The seam owns the CAPTURE side of session-event reporting — which records
+ * This package owns the CAPTURE side of session-event reporting — which records
  * exist (the chunk projection), what they carry (the logical record), when
  * they are captured (adoption, the per-append firehose, lifecycle
  * forwarding), live versus on-demand canonical-log capture, and the HMR
@@ -24,7 +24,7 @@ declare module 'cordis' {
   interface Events {
     /**
      * Transform one outbound record before it reaches the backend. This
-     * waterfall is the seam's redaction extension point. It ships NO rules
+     * waterfall is the Service Definition's redaction extension point. It ships NO rules
      * of its own: the
      * innermost `next()` passes the record through unchanged, and with no
      * listener mounted records reach the backend as captured, so exported
@@ -55,7 +55,7 @@ declare module 'cordis' {
 export type TelemetrySeverity = 'info' | 'warn' | 'error'
 
 /**
- * One logical record handed to a backend — the seam's whole outbound
+ * One logical record handed to a backend — the capture contract's whole outbound
  * vocabulary. Ledger records mirror session-log events one-to-one;
  * operational records (`channel: 'ops'`) carry the two signals with no log
  * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
@@ -143,7 +143,7 @@ export abstract class Telemetry extends Service implements TelemetryBackend {
   }
 
   /**
-   * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+   * See {@link TelemetryBackend.emit} — that declaration is the contract's one home.
    * @param record - the logical record to report; owned by the backend after the call.
    */
   abstract emit(record: TelemetryRecord): void
diff --git a/packages/session/session-telemetry/src/invariant.ts b/packages/session/session-telemetry/src/invariant.ts
index ffc55b0107..1c265877f8 100644
--- a/packages/session/session-telemetry/src/invariant.ts
+++ b/packages/session/session-telemetry/src/invariant.ts
@@ -15,7 +15,7 @@ export const name = 'session-telemetry-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: the seam's whole output is the backend handoff — a
+ * No runtime invariant: the package's whole output is the backend handoff — a
  * synchronous `emit()` call outside every authoritative event stream — and its
  * capture side never appends session events, so no event/data relation exists
  * for an independent companion to observe.
diff --git a/packages/session/session-title/src/index.ts b/packages/session/session-title/src/index.ts
index ab2298aa6c..12ca7924b4 100644
--- a/packages/session/session-title/src/index.ts
+++ b/packages/session/session-title/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Log-backed session title service, deterministic fallback, and provider seam.
+ * Log-backed session title service, deterministic fallback, and provider contract.
  * @module @deepseek-ai/dsh-session-title
  */
 
diff --git a/packages/settings/settings-local/tests/lock-race.spec.ts b/packages/settings/settings-local/tests/lock-race.spec.ts
index 3ef6f16fa4..46dd24353f 100644
--- a/packages/settings/settings-local/tests/lock-race.spec.ts
+++ b/packages/settings/settings-local/tests/lock-race.spec.ts
@@ -1,4 +1,4 @@
-// A temp-file write failure cannot be timed from outside. The fs/promises seam
+// A temp-file write failure cannot be timed from outside. The `fs/promises` API
 // injects it once so the test can prove that the writer lock still releases.
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
diff --git a/packages/settings/settings/README.i18n.yaml b/packages/settings/settings/README.i18n.yaml
index 8a8522fe57..4452e78dab 100644
--- a/packages/settings/settings/README.i18n.yaml
+++ b/packages/settings/settings/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/settings/settings/README.md
-README.md: 49ae5b405c003b6116e459cf377fc7a099538f2e
-README.zh.md: d8f3bff5878b575d571b7aab4b627daa51e215f1
+README.md: 5bfbf4623c937c2b66886f71adf27075523f5d28
+README.zh.md: 98808424ba1af2210067bd7f74baa6027decbb06
diff --git a/packages/settings/settings/README.md b/packages/settings/settings/README.md
index 49ae5b405c..5bfbf4623c 100644
--- a/packages/settings/settings/README.md
+++ b/packages/settings/settings/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Abstract user-settings seam (`ctx.settings`). One provider holds a raw document of per-namespace sections; plugins register a namespace schema and read a resolved value layered as schema defaults, then the registrant's composition `base` (its cordis.yml entry-config subset), then the user document section. Without a mounted provider nothing changes for consumers: they keep resolving entry config alone, so every composition works with or without settings.
+User-settings Service Definition (`ctx.settings`). One provider holds a raw document of per-namespace sections; plugins register a namespace schema and read a resolved value layered as schema defaults, then the registrant's composition `base` (its cordis.yml entry-config subset), then the user document section. Without a mounted provider nothing changes for consumers: they keep resolving entry config alone, so every composition works with or without settings.
 
 ## Service API
 
diff --git a/packages/settings/settings/README.zh.md b/packages/settings/settings/README.zh.md
index d8f3bff587..98808424ba 100644
--- a/packages/settings/settings/README.zh.md
+++ b/packages/settings/settings/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-抽象用户设置 seam（`ctx.settings`）。一个提供方持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载提供方时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
+用户设置 Service Definition（`ctx.settings`）。一个提供方持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载提供方时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
 
 ## 服务 API
 
diff --git a/packages/settings/settings/src/index.ts b/packages/settings/settings/src/index.ts
index 64e9f147b1..d0f85a2b1b 100644
--- a/packages/settings/settings/src/index.ts
+++ b/packages/settings/settings/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * User-settings seam (`ctx.settings`). Providers store one raw document of
+ * Service Definition for the user-settings capability seam (`ctx.settings`). Providers store one raw document of
  * per-namespace sections; plugins register a namespace schema and read the
  * resolved value, which layers schema defaults, the registrant's composition
  * `base`, and the user document section, in that order.
@@ -69,7 +69,7 @@ export interface SettingsRegisterOptions<T> {
 /** One registered namespace as surfaced to configuration UIs. */
 export interface SettingsDescriptor {
   // TODO(settings-namespace-vocabulary): Rename `ns` to `namespace` across the
-  // public seam, provider contract, implementations, tests, and consumers.
+  // public API, provider contract, implementations, tests, and consumers.
   /** The registered namespace. */
   ns: SettingsNamespace
   /** Serialized schemastery schema (`schema.toJSON()`). */
@@ -173,7 +173,7 @@ declare module 'cordis' {
 
 /**
  * Deep equality over JSON-shaped data (objects, arrays, primitives) — the
- * seam's single change-detection predicate, exported so the invariant
+ * Service Definition's single change-detection predicate, exported so the invariant
  * companion checks exactly the implementation's relation.
  * @param a - one JSON-shaped value.
  * @param b - the other JSON-shaped value.
@@ -195,7 +195,7 @@ export function deepEqualJson(a: unknown, b: unknown): boolean {
 
 /**
  * A write refused because the namespace moved since the caller read it. The
- * seam's serialized write queue orders writes; it cannot tell a fresh writer
+ * Service Definition's serialized write queue orders writes; it cannot tell a fresh writer
  * from one holding a stale snapshot, which is what this reports.
  */
 export class SettingsConflictError extends Error {
diff --git a/packages/settings/settings/tests/memory.ts b/packages/settings/settings/tests/memory.ts
index bb310c939d..58ce1f545e 100644
--- a/packages/settings/settings/tests/memory.ts
+++ b/packages/settings/settings/tests/memory.ts
@@ -1,5 +1,5 @@
 /**
- * In-memory settings provider fixture: the smallest real subclass of the seam,
+ * In-memory settings provider fixture: the smallest real subclass of the Service Definition,
  * used by the base-class behavior suite in place of a file- or network-backed
  * provider. Kept in `tests/` because production providers live in their own
  * packages.
@@ -7,7 +7,7 @@
 
 import { Settings, type SettingsNamespace } from '../src/index.ts'
 
-/** In-memory provider exposing the protected seam hooks to tests. */
+/** In-memory provider exposing the protected provider hooks to tests. */
 export class MemorySettings extends Settings {
   /** Raw document the provider "storage" currently holds. */
   doc: Record<string, unknown>
diff --git a/packages/settings/settings/tests/settings.spec.ts b/packages/settings/settings/tests/settings.spec.ts
index c6a1e57016..66c0f1fcf6 100644
--- a/packages/settings/settings/tests/settings.spec.ts
+++ b/packages/settings/settings/tests/settings.spec.ts
@@ -4,7 +4,7 @@ import z from 'schemastery'
 import { Settings, SettingsConflictError, deepEqualJson, installSettingsSection, settingsNamespace, type SettingsNamespace, type SettingsScope, type SettingsUpdateSource } from '../src/index.ts'
 import { MemorySettings } from './memory.ts'
 
-/** A provider implementing only the three primitives: the seam owns init. */
+/** A provider implementing only the three primitives: the Service Definition owns initialization. */
 class BareProvider extends Settings {
   doc: Record<string, unknown>
 
diff --git a/packages/skill/skill/src/index.ts b/packages/skill/skill/src/index.ts
index 16af8d55d3..18c878d74b 100644
--- a/packages/skill/skill/src/index.ts
+++ b/packages/skill/skill/src/index.ts
@@ -1,7 +1,8 @@
 /**
  * Agent skill provider registry.
  *
- * This package is the interface third of the skill capability seam. Concrete
+ * This package owns the Service Definition role of the skill capability seam.
+ * Concrete
  * providers such as `@deepseek-ai/dsh-skill-local` decide where skills come
  * from; this service only merges provider catalogs, resolves the winning skill
  * for a name, and exposes the winning summaries and definitions to consumers.
diff --git a/packages/skill/tool-skill/README.i18n.yaml b/packages/skill/tool-skill/README.i18n.yaml
index 58ae7e6afd..f78825d1f7 100644
--- a/packages/skill/tool-skill/README.i18n.yaml
+++ b/packages/skill/tool-skill/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/skill/tool-skill/README.md
-README.md: b7309657d85a3d2a19de78a4ee6173d742519daa
-README.zh.md: 10834e13b4bfb745b4cd084ce41f616a8dd95807
+README.md: fd2cb2dc00994a79856ad605ce126387c27a9f65
+README.zh.md: 3fb76e079033ef39e475e6795cf28407e52a83cc
diff --git a/packages/skill/tool-skill/README.md b/packages/skill/tool-skill/README.md
index b7309657d8..fd2cb2dc00 100644
--- a/packages/skill/tool-skill/README.md
+++ b/packages/skill/tool-skill/README.md
@@ -36,7 +36,7 @@ Tool execution does not add a synthetic context message. Its freshly loaded resu
 
 #### What the model sees
 
-If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names. The template's closing sentence is the seam rule against double-loading: the user-explicit gesture boundary (the pre-step listener below) injects the same `renderSkillContent` output (shared from `@deepseek-ai/dsh-skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same sentence in both arms, including the emptied catalog.
+If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names. The template's closing sentence is the rule against double-loading: the user-explicit gesture boundary (the pre-step listener below) injects the same `renderSkillContent` output (shared from `@deepseek-ai/dsh-skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same sentence in both arms, including the emptied catalog.
 
 ##### Skill catalog template
 
diff --git a/packages/skill/tool-skill/README.zh.md b/packages/skill/tool-skill/README.zh.md
index 10834e13b4..3fb76e0790 100644
--- a/packages/skill/tool-skill/README.zh.md
+++ b/packages/skill/tool-skill/README.zh.md
@@ -36,7 +36,7 @@
 
 #### 模型看到的内容
 
-如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的 seam 规则：用户显式的手势边界（下文的 pre-step 监听器）会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个分支——包括清空后的目录——都携带同一句话。
+如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的规则：用户显式的手势边界（下文的 pre-step 监听器）会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个臂——包括清空后的目录——都携带同一句话。
 
 ##### Skill 目录模板
 
@@ -149,11 +149,11 @@ Load referenced resources only as needed.
 
 #### 模型看到的内容
 
-已认领的用户消息中任意位置、以空白为界、指名工作区目录中某个用户可调用 skill 的 `/name` token，会把该 skill 的完整 `<skill_content>` 渲染（与上文结果模板完全相同的形态）作为 `user` 角色的指令上下文注入，追加在该步骤所有其他注入之后——背景在前，模型要着手处理的材料在最后。只扫描直接的用户输入，检查在已加载定义上进行，未知名称和用户不可调用的名称保持为普通行文。这是 `disable-model-invocation` skill 唯一的入口，目录和 `skill` 工具永不暴露这类 skill；目录的结尾一句会告诉模型遵循注入块，而不是重新加载它。
+已认领用户消息中任意位置、以空白为界、指名工作区目录中某个用户可调用 skill 的 `/name` token，会把该 skill 的完整 `<skill_content>` 渲染（与上文结果模板完全相同的形态）作为 `user` 角色的指令上下文注入，追加在该步骤所有其他注入之后——背景在前，模型要着手处理的材料在最后。只扫描直接的用户输入，检查在已加载定义上进行，未知名称和用户不可调用的名称保持为普通行文。这是 `disable-model-invocation` skill 唯一的入口，目录和 `skill` 工具永不暴露这类 skill；目录的结尾一句会告诉模型遵循注入块，而不是重新加载它。
 
 #### Token 影响
 
-每次手势会把一份渲染后的 skill 正文作为注入上下文加进该轮次——其大小与同一 skill 的工具结果相同；这项成本会在用户请求时确定产生，而非由模型自行裁量。同一步骤内对同一 skill 的重复手势只注入一次。
+每次手势会把一份渲染后的 skill 正文作为注入上下文加进该轮次——尺寸与同一 skill 的工具结果相同，按用户的请求确定性地支付，而非由模型自行裁量。同一步骤内对同一 skill 的重复手势只注入一次。
 
 #### KV Cache 影响
 
diff --git a/packages/spill/spill-policy/src/index.ts b/packages/spill/spill-policy/src/index.ts
index 470fd1cacd..45d7ba2e74 100644
--- a/packages/spill/spill-policy/src/index.ts
+++ b/packages/spill/spill-policy/src/index.ts
@@ -69,7 +69,7 @@ export interface Config {
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'spill-policy'
 
-/** Require the tool registry (its `tools/post-execute` waterfall is the seam we transform). */
+/** Require the tool registry (its `tools/post-execute` waterfall is the extension point we transform). */
 export const inject = ['tools']
 
 export const Config: z<Config> = z.object({
diff --git a/packages/spill/spill/README.i18n.yaml b/packages/spill/spill/README.i18n.yaml
index cddfc91ea7..2478cdc7d4 100644
--- a/packages/spill/spill/README.i18n.yaml
+++ b/packages/spill/spill/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/spill/spill/README.md
-README.md: ecaef9fc53ec3d9017143cfc012abc9cabe77072
-README.zh.md: 5393ccb312245f3bbfcf28ea8e097b0a343966e9
+README.md: a9e3ec7169e0239117f7f9222ad2ba53619e0369
+README.zh.md: 9bfacda928e30a1338bedaef9d39e43cff4c667d
diff --git a/packages/spill/spill/README.md b/packages/spill/spill/README.md
index ecaef9fc53..a9e3ec7169 100644
--- a/packages/spill/spill/README.md
+++ b/packages/spill/spill/README.md
@@ -8,11 +8,11 @@ This package is one third of the spill capability, split so each concern evolves
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-spill` (this) | the interface: abstract service + vocabulary types |
-| `@deepseek-ai/dsh-spill-local` | an implementation: private session-scoped files on the host filesystem |
-| `@deepseek-ai/dsh-spill-policy` | the tool-result policy that spills oversized final results |
+| `@deepseek-ai/dsh-spill` (this) | Service Definition: abstract service + vocabulary types |
+| `@deepseek-ai/dsh-spill-local` | Service provider: private session-scoped files on the host filesystem |
+| `@deepseek-ai/dsh-spill-policy` | Consumer: the tool-result policy that spills oversized final results |
 
-The split mirrors the bash/fs seams. A future remote or virtual backend (e.g. a `spill://…` URI, a database key, or a backend-specific retrieval tool) implements this interface without touching the policy plugin.
+The split mirrors the bash/fs seams. A future remote or virtual backend (e.g. a `spill://…` URI, a database key, or a backend-specific retrieval tool) implements this Service Definition without touching the policy plugin.
 
 ## Service API (`ctx.spillStore`)
 
diff --git a/packages/spill/spill/README.zh.md b/packages/spill/spill/README.zh.md
index 5393ccb312..9bfacda928 100644
--- a/packages/spill/spill/README.zh.md
+++ b/packages/spill/spill/README.zh.md
@@ -8,11 +8,11 @@
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-spill`（本包） | 接口：抽象服务与词汇类型 |
-| `@deepseek-ai/dsh-spill-local` | 实现：位于宿主文件系统中的私有会话级文件 |
-| `@deepseek-ai/dsh-spill-policy` | 对过大最终结果执行 spill 的工具结果策略 |
+| `@deepseek-ai/dsh-spill`（本包） | Service Definition：抽象服务与词汇类型 |
+| `@deepseek-ai/dsh-spill-local` | Service provider：位于宿主文件系统中的私有会话级文件 |
+| `@deepseek-ai/dsh-spill-policy` | Consumer：对过大最终结果执行 spill 的工具结果策略 |
 
-这种拆分方式与 bash/fs seam 相同。未来的远程或虚拟后端（例如 `spill://…` URI、数据库键或后端专用取回工具）可实现此接口，无需修改策略插件。
+这种拆分方式与 bash/fs seam 相同。未来的远程或虚拟后端（例如 `spill://…` URI、数据库键或后端专用取回工具）可实现此 Service Definition，无需修改策略插件。
 
 ## 服务 API（`ctx.spillStore`）
 
diff --git a/packages/spill/spill/src/index.ts b/packages/spill/spill/src/index.ts
index 73bfe75f33..0d98ea9f66 100644
--- a/packages/spill/spill/src/index.ts
+++ b/packages/spill/spill/src/index.ts
@@ -1,11 +1,11 @@
 /**
- * The spill storage seam (`ctx.spillStore`): an abstract service defining WHAT a
+ * Service Definition for the spill storage capability seam (`ctx.spillStore`): an abstract service defining WHAT a
  * spill backend does — persist a tool's oversized text and return a model-facing
  * locator plus retrieval guidance — without saying HOW. Implementations
  * subclass {@link SpillStore} and register as the `spillStore` service;
  * `@deepseek-ai/dsh-spill-local` (host filesystem) is the first.
  *
- * The seam is deliberately minimal: `saveText` and nothing else. It owns NO
+ * The Service Definition is deliberately minimal: `saveText` and nothing else. It owns NO
  * retention policy (that is `@deepseek-ai/dsh-retention`), NO tool-result
  * replacement (that is `@deepseek-ai/dsh-spill-policy`), and NO retrieval or
  * search API. The backend supplies the locator and retrieval hint appropriate
diff --git a/packages/spill/spill/src/types.ts b/packages/spill/spill/src/types.ts
index a3657e5c3c..f07e13f4ef 100644
--- a/packages/spill/spill/src/types.ts
+++ b/packages/spill/spill/src/types.ts
@@ -1,5 +1,5 @@
 /**
- * Vocabulary for the spill storage seam. Types only — the abstract service
+ * Vocabulary for the spill storage Service Definition. Types only — the abstract service
  * lives in `./index.ts`, implementations in sibling packages
  * (`@deepseek-ai/dsh-spill-local` first).
  *
diff --git a/packages/spill/spill/tests/service.spec.ts b/packages/spill/spill/tests/service.spec.ts
index ddbc4086e1..141072d67a 100644
--- a/packages/spill/spill/tests/service.spec.ts
+++ b/packages/spill/spill/tests/service.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Tests for the spill seam INTERFACE: a minimal concrete subclass registers as
+ * Tests for the spill Service Definition: a minimal concrete subclass registers as
  * `ctx.spillStore`, a second load throws (duplicate service), and disposal
  * releases the service. The storage behavior is the implementation's concern
  * (`@deepseek-ai/dsh-spill-local`); here we only pin the seam contract.
diff --git a/packages/storage/README.i18n.yaml b/packages/storage/README.i18n.yaml
index ef32481991..2d6db691b7 100644
--- a/packages/storage/README.i18n.yaml
+++ b/packages/storage/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/storage/README.md
-README.md: a178495fca5cc433182b8e75f20d479cb7c5bc99
-README.zh.md: 1a08f1676e5c699a55f9956a42059d1f5acf7e8d
+README.md: dd9eb5ac97529c75df5986c56b714331dca0b6f1
+README.zh.md: a69414826b3ffd613c432836ea506b664ceb8da5
diff --git a/packages/storage/README.md b/packages/storage/README.md
index a178495fca..dd9eb5ac97 100644
--- a/packages/storage/README.md
+++ b/packages/storage/README.md
@@ -13,4 +13,4 @@ This family persists application data other than session event logs through name
 
 Consumers use a data form rather than accessing a backend directly. The [domain storage decision](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) records the family design.
 
-The subsystem reference — the backend seam, `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` — is [docs/subsystems/storage.md](../../docs/subsystems/storage.md).
+The subsystem reference — the backend contract, `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` — is [docs/subsystems/storage.md](../../docs/subsystems/storage.md).
diff --git a/packages/storage/README.zh.md b/packages/storage/README.zh.md
index 1a08f1676e..a69414826b 100644
--- a/packages/storage/README.zh.md
+++ b/packages/storage/README.zh.md
@@ -13,4 +13,4 @@
 
 消费方使用数据形式，而不是直接访问后端。[领域存储决策](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)记录了该家族的设计。
 
-子系统参考——后端 seam、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed`——见 [docs/subsystems/storage.md](../../docs/subsystems/storage.md)。
+子系统参考——后端约定、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed`——见 [docs/subsystems/storage.md](../../docs/subsystems/storage.md)。
diff --git a/packages/storage/storage-domain/README.i18n.yaml b/packages/storage/storage-domain/README.i18n.yaml
index 2b5cbc7a14..80ccac9a5f 100644
--- a/packages/storage/storage-domain/README.i18n.yaml
+++ b/packages/storage/storage-domain/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/storage/storage-domain/README.md
-README.md: 41e777c3d9a870530593a414839f905514a27134
-README.zh.md: 2f6b4daa09769d5a03eb30964c12447951c432e3
+README.md: 7c058ab557cfb128f54c15e715685d59f6720696
+README.zh.md: 10eb33711e147bc5ac6b7770a196bfea4fe66306
diff --git a/packages/storage/storage-domain/README.md b/packages/storage/storage-domain/README.md
index 41e777c3d9..7c058ab557 100644
--- a/packages/storage/storage-domain/README.md
+++ b/packages/storage/storage-domain/README.md
@@ -19,7 +19,7 @@ Design rationale, open semantics, and the storage/domain layer split live in the
 
 #### What the model sees
 
-Nothing. The package registers no tools, injects no prompts, and appends no session events; it stores non-session data (workspace records, future session sidecars) behind `ctx.storageDomain` and emits only the in-process `domain/changed` event, which reaches a model only if a consumer package renders it through its own documented surface.
+Nothing. The package registers no tools, injects no prompts, and appends no session events; it stores non-session data (workspace records, future session sidecars) behind `ctx.storageDomain` and emits only the in-process `domain/changed` event, which reaches a model only if a Consumer package renders it through its own documented surface.
 
 #### Token effect
 
diff --git a/packages/storage/storage-domain/README.zh.md b/packages/storage/storage-domain/README.zh.md
index 2f6b4daa09..10eb33711e 100644
--- a/packages/storage/storage-domain/README.zh.md
+++ b/packages/storage/storage-domain/README.zh.md
@@ -19,7 +19,7 @@ DeepSeek Harness 存储中心的领域数据形式：在所有已配置的后端
 
 #### 模型看到的内容
 
-无。该包不注册工具、不注入提示词，也不追加会话事件；它在 `ctx.storageDomain` 后面存储非会话数据（工作区记录、未来的会话伴随数据），只发出进程内 `domain/changed` 事件。只有消费方包通过自身有文档说明的接口呈现该事件时，它才会到达模型。
+无。该包不注册工具、不注入提示词，也不追加会话事件；它在 `ctx.storageDomain` 后面存储非会话数据（工作区记录、未来的会话伴随数据），只发出进程内 `domain/changed` 事件。只有 Consumer 包通过自身有文档说明的接口呈现该事件时，它才会到达模型。
 
 #### Token 影响
 
diff --git a/packages/storage/storage-domain/src/domain.ts b/packages/storage/storage-domain/src/domain.ts
index 7327580630..26ed726b93 100644
--- a/packages/storage/storage-domain/src/domain.ts
+++ b/packages/storage/storage-domain/src/domain.ts
@@ -118,7 +118,7 @@ export interface Domain<S extends DomainSpec> {
   close(): Promise<void>
 }
 
-/** Internal seam handing table handles their domain-owned write machinery. */
+/** Internal boundary handing table handles their domain-owned write machinery. */
 interface TableHost {
   readonly domainName: string
   readonly unit: KvUnit
diff --git a/packages/storage/storage-domain/tests/helpers/memory-backend.ts b/packages/storage/storage-domain/tests/helpers/memory-backend.ts
index 1eb1bffe2d..3c8547d280 100644
--- a/packages/storage/storage-domain/tests/helpers/memory-backend.ts
+++ b/packages/storage/storage-domain/tests/helpers/memory-backend.ts
@@ -39,7 +39,7 @@ export class MemoryMediaPool {
   /**
    * When positive, that many subsequent write primitives (putRecord /
    * deleteRecord / setGlobal) reject without touching the medium, decrementing
-   * per rejection. Negative-path seam: callers assert their state is
+   * per rejection. Negative path: callers assert their state is
    * untouched after a durability failure.
    */
   failNextWrites = 0
diff --git a/packages/subagent/README.i18n.yaml b/packages/subagent/README.i18n.yaml
index c7d3ce46ee..10ad9837b2 100644
--- a/packages/subagent/README.i18n.yaml
+++ b/packages/subagent/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/subagent/README.md
-README.md: c8969ad313fc673456d2740b40d90c6d8db794ac
-README.zh.md: 04351f26721849de730db6083f55abc8e8571ce4
+README.md: 134028c9993255464c08d912d305c65ed85d65c0
+README.zh.md: ab4284d0525ceed349a778385c918a9dec19406f
diff --git a/packages/subagent/README.md b/packages/subagent/README.md
index c8969ad313..134028c999 100644
--- a/packages/subagent/README.md
+++ b/packages/subagent/README.md
@@ -20,4 +20,4 @@ This family lets an agent delegate work to child agents. Multiple named provider
 
 See the decisions for the [capability family](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable children](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [control tools](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
 
-The subsystem reference — start requests, results, live runs, the provider seam, continuable background children — is [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md); design rationale in the [subagent capability seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable background subagents](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [merged subagent control service](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Notes.
+The subsystem reference — start requests, results, live runs, the provider contract, continuable background children — is [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md); design rationale in the [subagent capability seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable background subagents](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [merged subagent control service](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Notes.
diff --git a/packages/subagent/README.zh.md b/packages/subagent/README.zh.md
index 04351f2672..ab4284d052 100644
--- a/packages/subagent/README.zh.md
+++ b/packages/subagent/README.zh.md
@@ -20,4 +20,4 @@
 
 参见有关[能力家族](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续执行的子级](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)和[控制工具](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)的决策。
 
-子系统参考——启动请求、结果、实时运行、提供方 seam、可续跑后台子 agent——见 [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md)；设计依据见 [subagent 能力 seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可续跑后台 subagent](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md) 与[合并 subagent 控制服务](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Note。
+子系统参考——启动请求、结果、实时运行、提供方约定、可续跑后台子 agent——见 [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md)；设计依据见 [subagent 能力 seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可续跑后台 subagent](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md) 与[合并 subagent 控制服务](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Note。
diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts b/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
index d361d26f4f..9216068b07 100644
--- a/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
@@ -11,7 +11,7 @@ import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
 import * as acp from '../src/index.ts'
 
 /**
- * With-key cross-process seam proof: the backend spawns the real acp-agent example, speaks ACP over
+ * With-key cross-process boundary proof: the backend spawns the real acp-agent example, speaks ACP over
  * stdio, and returns its real model answer. This is the out-of-process counterpart to in-process
  * spawn coverage and self-skips without `DEEPSEEK_API_KEY`.
  */
diff --git a/packages/subagent/subagent-claude-code/src/run.ts b/packages/subagent/subagent-claude-code/src/run.ts
index d5f222b6c4..9dc4d740ac 100644
--- a/packages/subagent/subagent-claude-code/src/run.ts
+++ b/packages/subagent/subagent-claude-code/src/run.ts
@@ -167,7 +167,7 @@ export async function disposeClaudeCodeChild(
 
 /**
  * Build the fixed official SDK options for one one-shot provider run.
- * @param spec - workspace, environment, process seam, and disposal policy.
+ * @param spec - Workspace, environment, process service, and disposal policy.
  * @param controller - per-run cancellation owner.
  * @param capture - receives the real managed child synchronously from the SDK hook.
  * @returns options that inherit native settings while disabling persistence and user questions.
@@ -194,7 +194,7 @@ export function claudeQueryOptions(
 /**
  * Start one official Claude Agent SDK query and publish its one-shot run.
  * @param request - resolved shared subagent request.
- * @param spec - workspace, environment, process seam, and diagnostic policy.
+ * @param spec - Workspace, environment, process service, and diagnostic policy.
  * @returns the published run after both Query and real CLI handle exist.
  */
 export async function startClaudeCodeRun(
diff --git a/packages/subagent/subagent-codex/src/run.ts b/packages/subagent/subagent-codex/src/run.ts
index c3ebf4ba19..ebce244f3b 100644
--- a/packages/subagent/subagent-codex/src/run.ts
+++ b/packages/subagent/subagent-codex/src/run.ts
@@ -61,7 +61,7 @@ function thrown(value: unknown): Error {
 }
 
 /**
- * Validate and preserve the one-shot task before crossing the process seam.
+ * Validate and preserve the one-shot task before crossing the process boundary.
  * @param prompt - task content accepted from the shared subagent service.
  * @returns the exact non-empty text block sequence.
  */
@@ -110,7 +110,7 @@ export async function disposeCodexChild(
 /**
  * Start the real `codex app-server --stdio` child and publish its one-shot run.
  * @param request - resolved shared subagent request.
- * @param spec - workspace, environment, process seam, and diagnostic policy.
+ * @param spec - Workspace, environment, process service, and diagnostic policy.
  * @returns the published run after initialization and ephemeral thread creation.
  */
 export async function startCodexRun(
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index 4fac8ecd2e..1241aa8042 100644
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/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/subagent/subagent/README.md
-README.md: a1b5807e5e9e880879e39e0bacaa1a54743f227e
-README.zh.md: 823227af1841730c8fd926295bf7c4ca74497255
+README.md: 762030629c09305c48adebc71244655a5faa6585
+README.zh.md: 535cc25895e04e82b6667e6d2769f2dcbfa49cff
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index a1b5807e5e..762030629c 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -44,11 +44,11 @@ Continuable creation is the optional `SubagentProvider.prepareContinuable?()` me
 
 ## The durable descriptor
 
-The seam owns the versioned `subagent/descriptor` session event vocabulary (`src/descriptor.ts`): `snapshotSubagentDescriptor()` validates and detaches the record before provider work, and `foldSubagentDescriptor()` validates the complete current-version payload before recovering it from a loaded child log. Every local session-backed start appends one descriptor with the provider name and lifecycle `mode`. A `one-shot` descriptor optionally carries the caller-owned durable display `label`; a `continuable` descriptor requires its durable creation label and additionally records resolved child `agentOptions.provider`/`model` and optional `persona`/`toolFilter` for cold resume. These are explicit fields, never the merge-extensible `AgentOptions` object, so an unrelated extension value cannot break continuation. The descriptor omits `subagentDepth` (the persisted header's `delegationDepth` is the monotone floor) and `outputSchema` (an Activation's result contract). The event is log-only: no `surfaceOp`, absent from model history, and retained by the append-only log across compaction. Malformed current-version payloads are corrupt; unsupported versions cannot be classified by this runtime.
+The Service Definition owns the versioned `subagent/descriptor` session event vocabulary (`src/descriptor.ts`): `snapshotSubagentDescriptor()` validates and detaches the record before provider work, and `foldSubagentDescriptor()` validates the complete current-version payload before recovering it from a loaded child log. Every local session-backed start appends one descriptor with the provider name and lifecycle `mode`. A `one-shot` descriptor optionally carries the caller-owned durable display `label`; a `continuable` descriptor requires its durable creation label and additionally records resolved child `agentOptions.provider`/`model` and optional `persona`/`toolFilter` for cold resume. These are explicit fields, never the merge-extensible `AgentOptions` object, so an unrelated extension value cannot break continuation. The descriptor omits `subagentDepth` (the persisted header's `delegationDepth` is the monotone floor) and `outputSchema` (an Activation's result contract). The event is log-only: no `surfaceOp`, absent from model history, and retained by the append-only log across compaction. Malformed current-version payloads are corrupt; unsupported versions cannot be classified by this runtime.
 
 ## Delegation depth
 
-The seam owns the depth vocabulary shared by implementations and consumers: the `AgentOptions.subagentDepth` declaration, `assertSubagentMaxDepth`, and `delegationDepthOf(agent)`. The persisted `SessionHeader.delegationDepth` is authoritative and monotone — runtime options may deepen the count but never lower it, so a resumed child cannot be re-counted as top-level.
+The seam owns the depth vocabulary shared by Service providers and Consumers: the `AgentOptions.subagentDepth` declaration, `assertSubagentMaxDepth`, and `delegationDepthOf(agent)`. The persisted `SessionHeader.delegationDepth` is authoritative and monotone — runtime options may deepen the count but never lower it, so a resumed child cannot be re-counted as top-level.
 
 `inheritsParentContext` is descriptive rather than enforceable. It says only whether the child sees completed parent conversation history (`fork` does; `spawn` and the out-of-process one-shot providers do not), not whether it inherits tools, services, or authority.
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 823227af18..535cc25895 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -4,7 +4,7 @@
 
 subagent seam 允许一个 agent（智能体）通过具名提供方把工作委派给子 agent。调用方使用统一的服务 API（`ctx.subagents`）；提供方决定子 agent 在当前进程、另一进程还是未来的传输之上运行。
 
-[subagent 家族概述](../README.md)列出了实现和面向模型的消费方。本包负责提供方注册表、共享的请求与结果约定、持久描述符以及可继续子级编排。多个具名提供方可以在该约定背后共存。
+[subagent 家族概述](../README.md)列出了实现和面向模型的消费方。本包负责提供方注册表、共享请求和结果约定、持久描述符以及可继续子级编排。多个具名提供方可以在该约定背后共存。
 
 ## 服务 API
 
@@ -23,7 +23,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
 | `listChildren(parentSessionId, signal?)` | 按 `createdAt` 再按 id 的顺序列出由会话支撑的直接 subagent，包括其 `one-shot`／`continuable` 模式、`running`／`inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic，且不会加载或恢复它们。直接读取在线会话存储与可选的会话持久化（持久化缺席时仅枚举在线 child），并要求已挂载 `sessionProjections` 注册表；不要求 `ctx.agents`、继续执行管理器或任何查询服务。 |
-| `listDescendants(rootSessionId, signal?)` | 从同一份在线优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth`。普通会话与一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现。身份、diagnostic、依赖与取消约定均沿用 `listChildren()`。 |
+| `listDescendants(rootSessionId, signal?)` | 从同一份实时优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth`。普通会话与一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现。身份、diagnostic、依赖与取消约定均沿用 `listChildren()`。 |
 
 `SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。
 
@@ -44,11 +44,11 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 持久化描述符
 
-该 seam 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果约定）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩（compaction）保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
+该 Service Definition 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果约定）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩（compaction）保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
 
 ## 委派深度
 
-该 seam 拥有实现和消费方共享的深度词汇：`AgentOptions.subagentDepth` 声明、`assertSubagentMaxDepth` 和 `delegationDepthOf(agent)`。持久化的 `SessionHeader.delegationDepth` 具有权威性且单调：运行时选项可以加深计数，但绝不能降低它，因此恢复后的子 agent 不会被重新计为顶层。
+该 seam 拥有 Service provider 和 Consumer 共享的深度词汇：`AgentOptions.subagentDepth` 声明、`assertSubagentMaxDepth` 和 `delegationDepthOf(agent)`。持久化的 `SessionHeader.delegationDepth` 具有权威性且单调：运行时选项可以加深计数，但绝不能降低它，因此恢复后的子 agent 不会被重新计为顶层。
 
 `inheritsParentContext` 只用于描述，不能强制执行。它仅说明子 agent 是否能看到父级已完成的对话历史（`fork` 可以；`spawn` 和各进程外一次性提供方不可以），不表示是否继承工具、服务或权限。
 
@@ -80,7 +80,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 记录发送方，但不授予权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；Activation 物化时记录的任何确切在线 ancestor 也可以停止其后代，因为停止一个轮次是幂等的，且不投递任何内容。
 
-当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置规则从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，使消费方替换陈旧身份而不是将其保留——绝不抛错。
+当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置纪律从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，让消费方以之替换掉手中过时的身份而非永久滞留——绝不抛错。
 
 `registerContinuableSetup()` 允许可选包添加子级作用域能力，而无需让继续执行管理器知道这些能力的名称。贡献会在 Activation 发布前同步安装，在设置失败时一并回滚，并随子级作用域释放。新授权须等到下一个 Activation，移除贡献则会立即撤销每个驻留安装项。
 
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 241682c006..eddcf63c3c 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The subagent seam (`ctx.subagents`): a named-provider registry plus a
+ * Service Definition for the subagent capability seam (`ctx.subagents`): a named-provider registry plus a
  * capability-validating asynchronous start surface. Providers establish a
  * child before returning its run, so fulfillment is the single publication and
  * ownership-transfer boundary.
@@ -9,7 +9,7 @@
  * one by name. The shape mirrors the LLM adapter registry
  * (`LlmService.registerAdapter`), not the single-service bash executor.
  *
- * This package is the INTERFACE third of the capability seam. Implementations
+ * This package owns the Service Definition role of the capability seam. Service providers
  * (`@deepseek-ai/dsh-subagent-spawn`, `-fork`, `-acp`) and the model-facing
  * consumer (`@deepseek-ai/dsh-tool-subagent`) are separate packages.
  *
@@ -306,7 +306,7 @@ export class SubagentService extends Service {
 
   /**
    * Enumerate the parent's direct session-backed subagents without loading or
-   * resuming an Agent and without any query seam: the listing merges the live
+   * resuming an Agent and without any query service: the listing merges the live
    * session store with optional session persistence (live-preferred) and
    * serves each child's durable mode/label from the registered `subagent`
    * projection unit down a three-rung ladder — the registry's watermark
diff --git a/packages/subagent/subagent/src/lifecycle.ts b/packages/subagent/subagent/src/lifecycle.ts
index 4e86664340..65c61ae9eb 100644
--- a/packages/subagent/subagent/src/lifecycle.ts
+++ b/packages/subagent/subagent/src/lifecycle.ts
@@ -27,7 +27,7 @@ import type { SubagentResult, SubagentRun, SubagentRunEndInfo, SubagentRunInfo }
  * Lifecycle observer for one Activation's residency epoch, so continuable
  * children emit the same start/end pair as one-shot runs. Package-private: the
  * continuation manager is the only consumer, and its call ordering is an
- * in-package contract rather than a published extension seam.
+ * in-package contract rather than a published extension point.
  */
 export interface ActivationObserver {
   /**
diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index bf259212bb..47b6f7f712 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -1,7 +1,7 @@
 /**
  * Read-only enumeration of durable subagent children and descendant trees
  * straight from the live session store and optional session persistence — no
- * query seam. Candidates come from one live-preferred corpus; each child's
+ * query service. Candidates come from one live-preferred corpus; each child's
  * mode/label is the registered `subagent` projection unit's value, resolved
  * down a three-rung ladder: the registry's watermark cache for a live child,
  * a durable projection-cache row when it serves an own-suffix identity (the
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index c90e0949bd..f2f5798d6c 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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/subprocess/README.md
-README.md: 9a8628e2b6d16852895be33ae516c8b33b078502
-README.zh.md: 734a2a5a27f0337a3015989556e571f4d18228e0
+README.md: 23c8ba44916379c032991bc92df557157c2e66c4
+README.zh.md: d3400b8b6cc5e839d77858f0684125b54b2daadd
diff --git a/packages/subprocess/README.md b/packages/subprocess/README.md
index 9a8628e2b6..23c8ba4491 100644
--- a/packages/subprocess/README.md
+++ b/packages/subprocess/README.md
@@ -6,8 +6,8 @@ The shared process substrate for one execution world: executable lookup, fully-s
 
 | Package | ctx key | Role |
 |---|---|---|
-| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | The seam: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
-| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
+| [`subprocess`](subprocess/README.md) (`@deepseek-ai/dsh-subprocess`) | `ctx.subprocess` | Service Definition: executable lookup, ordinary managed spawns, the terminal-process primitive, handle lifecycles, and shared environment/output vocabulary |
+| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | Local Service provider: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
 
 The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
 
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index 734a2a5a27..d3400b8b6c 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -6,8 +6,8 @@
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
-| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | Service Definition：可执行文件查找、普通受管 spawn、终端进程原语、句柄生命周期，以及共享的环境／输出词汇 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地 Service provider：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
 
 即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
 
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 22d971b251..f0e9a8a597 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: 087ca24a3207cb8cb1568769a462fbbb010aaa35
-README.zh.md: 4d400906f71b653ce2be95a22751fd9893f447bd
+README.md: ed2b4c3558aa034c8d9fa1049c81d6628c86dff7
+README.zh.md: 832a82dc6a12096e85a1b939f5021767a3c5cb68
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index 087ca24a32..ed2b4c3558 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), and [`dsh-pty-local`](../../pty/pty-local/README.md)).
+Local Service provider for the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling capability seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), and [`dsh-pty-local`](../../pty/pty-local/README.md)).
 
 ## Behavior (and where it came from)
 
@@ -16,7 +16,7 @@ Local implementation of the [`@deepseek-ai/dsh-subprocess`](../subprocess/README
 
 ## Model Experience
 
-Indirectly, through consumer seams (today the bash executor family behind `dsh-tool-bash`), which own all model-facing rendering of process output and lifecycle.
+Indirectly, through Consumers (today the bash executor family behind `dsh-tool-bash`), which own all model-facing rendering of process output and lifecycle.
 
 #### KV Cache effect
 
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 4d400906f7..832a82dc6a 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md) 和 [`dsh-pty-local`](../../pty/pty-local/README.md)）。
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地 Service provider。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方能力 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md) 和 [`dsh-pty-local`](../../pty/pty-local/README.md)）。
 
 ## 行为（以及设计来源）
 
@@ -10,13 +10,13 @@
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在接缝处被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
+- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在该能力入口被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
 - **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
 - **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
 
-通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出与生命周期面向模型的全部渲染归消费方所有。
+通过 Consumer 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出与生命周期面向模型的全部渲染归 Consumer 所有。
 
 #### KV Cache 影响
 
diff --git a/packages/subprocess/subprocess-local/src/index.ts b/packages/subprocess/subprocess-local/src/index.ts
index e441944225..858bf3fc75 100644
--- a/packages/subprocess/subprocess-local/src/index.ts
+++ b/packages/subprocess/subprocess-local/src/index.ts
@@ -1,9 +1,9 @@
 /**
- * Local implementation of the subprocess seam. Each spawn is a detached
+ * Local Service provider for the subprocess capability seam. Each spawn is a detached
  * process tree with the spec's per-stream stdio dispositions; disposal
  * terminates and joins live trees. It has no config: every disposition and
  * limit arrives on the spec, so the deployment-varying choices stay with the
- * calling seam's config (the bash executor's, the LSP host's, …).
+ * caller's config (the bash executor's, the LSP host's, …).
  * @module @deepseek-ai/dsh-subprocess-local
  */
 
@@ -37,9 +37,9 @@ export class LocalSubprocessService extends SubprocessService {
   private live = new Set<SubprocessHandle>()
   /** Live terminal sessions retained through whole-session quiescence. */
   private terminals = new Set<SubprocessTerminalHandle>()
-  /** Test seam: spill and platform knobs forwarded to spawnSubprocess. */
+  /** Test hook: spill and platform knobs forwarded to spawnSubprocess. */
   internals: SpawnInternals = {}
-  /** Test seam for platform process inspection; production resolves lazily on terminal spawn. */
+  /** Test hook for platform process inspection; production resolves lazily on terminal spawn. */
   terminalInspector: ProcessInspector | undefined
 
   constructor(ctx: Context) {
@@ -123,8 +123,8 @@ export class LocalSubprocessService extends SubprocessService {
     return handle
   }
 
-  // Local PTY allocation is synchronous, but the provider seam permits remote asynchronous allocation.
-  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
+  // Local PTY allocation is synchronous, but the provider contract permits remote asynchronous allocation.
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider contract.
   async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
     const file = spec.argv[0]
     if (file === undefined || file.length === 0) {
diff --git a/packages/subprocess/subprocess-local/src/terminal.ts b/packages/subprocess/subprocess-local/src/terminal.ts
index 2a763948bb..11d13a405a 100644
--- a/packages/subprocess/subprocess-local/src/terminal.ts
+++ b/packages/subprocess/subprocess-local/src/terminal.ts
@@ -72,14 +72,14 @@ export class LocalTerminalHandle implements SubprocessTerminalHandle {
   }
 
   // node-pty writes synchronously; the seam returns a promise for remote transports.
-  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider contract.
   async write(data: string): Promise<void> {
     if (this.exited) throw new Error('terminal process has exited')
     this.terminal.write(data)
   }
 
   // Local inspection is synchronous; the seam returns a promise for remote transports.
-  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider seam.
+  // oxlint-disable-next-line typescript/require-await -- Preserve promise rejection semantics at the async provider contract.
   async inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
     this.descendants()
     const processGroupId = this.inspector.foregroundPgid(this.pid)
diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index 6bac46ac16..36da8307e3 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -329,7 +329,7 @@ describe('stdin and extra env (set by in-process plugins)', () => {
   })
 
   it('gives fd 0 the exact pre-seam type: /dev/null when no stdin, a pipe when supplied', async () => {
-    // With no bytes, fd 0 remains the pre-seam `ignore` default (/dev/null, a character device).
+    // With no bytes, fd 0 remains the pre-spawn `ignore` default (/dev/null, a character device).
     // Supplied bytes use Node's spawn pipe, which is an AF_UNIX socket rather than a FIFO.
     const none = await finish(spawnSubprocess(spec('test -c /dev/stdin && echo char || echo other')))
     expect(none.stdout.text).toBe('char\n')
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 6da5dc1939..d3b075caaa 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: c28361f5e767f81fe8d1ca4757aece83dccfea5c
-README.zh.md: b5d0aac765e433dbaeb9b6e24638ffa6bea6cc51
+README.md: 71ed60c6bdbecbddf45ee4c6a3d31e4a3fbb479b
+README.zh.md: a3789954edf5cedfa96f26774250b2cec877c503
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index c28361f5e7..71ed60c6bd 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -8,7 +8,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl
 
 - `spawn(spec)` returns immediately with a live handle; `done` resolves at process close with exit facts (`SubprocessOutcome` carries no output and no cause classification) and rejects only for spawn-level failures.
 - Spawn working directories and executable paths belong to the provider's execution world. `resolveExecutable(command, env?, signal?)` verifies absolute commands or resolves bare names against that world's scrubbed PATH plus explicit overrides.
-- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
+- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the caller's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
 - `spawnTerminal(spec)` is the only non-pipe primitive. Its handle owns a real PTY, UTF-8 text I/O, foreground-process-group inspection/signalling, and one awaited `terminate()` operation that reaches quiescence for every session member the provider can still observe and settles in-flight handle calls; providers document substrate-specific observability limits. The spec signal cancels allocation only; the published handle owns its lifetime. The output stream ends after queued output when the top-level process exits, and a live transport failure rejects `done`. These operations remain one substrate primitive because ordinary pipes cannot allocate a controlling terminal or clean terminal-session members; readiness, scrollback, and owner policy remain in the PTY consumer.
@@ -19,7 +19,7 @@ See the [subprocess subsystem page](../../../docs/subsystems/subprocess.md) and
 
 ## Model Experience
 
-Indirectly, through consumer seams (today the bash executor family behind `dsh-tool-bash`), which own all model-facing rendering of process output and lifecycle.
+Indirectly, through Consumers (today the bash executor family behind `dsh-tool-bash`), which own all model-facing rendering of process output and lifecycle.
 
 #### KV Cache effect
 
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index b5d0aac765..a3789954ed 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -8,7 +8,7 @@
 
 - `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
 - spawn 工作目录和可执行文件路径属于提供方的执行世界。`resolveExecutable(command, env?, signal?)` 验证绝对命令，或根据该执行世界清理后的 PATH 加显式覆盖来解析裸名称。
-- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
+- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
 - `spawnTerminal(spec)` 是唯一的非管道原语。其句柄负责真实 PTY、UTF-8 文本 I/O、前台进程组检查／信号发送，以及一项须等待的 `terminate()` 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，并结算在途句柄调用；提供方会记录执行基底特有的可观察性限制。spec 信号只取消分配；句柄一经发布，便负责自身生命周期。顶层进程退出时，输出流在已排队输出之后结束；仍处于活动状态的传输若发生故障，会使 `done` 拒绝。这些操作保留为一项执行基底原语，因为普通管道无法分配控制终端或清理终端会话成员；就绪状态、scrollback 和所有者策略仍归 PTY 消费方所有。
@@ -19,7 +19,7 @@
 
 ## 模型体验
 
-通过消费方 seam 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出和生命周期的全部面向模型渲染均由消费方负责。
+通过 Consumer 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出和生命周期的全部面向模型渲染均由 Consumer 负责。
 
 #### KV Cache 影响
 
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index 6b9904078f..0eaed5620b 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The subprocess seam (`ctx.subprocess`): execution-world executable lookup,
+ * Service Definition for the subprocess capability seam (`ctx.subprocess`): execution-world executable lookup,
  * fully specified managed process trees with raw or
  * collected stdio, and one terminal-process primitive. Command defaulting,
  * shell semantics, deadlines, protocol framing, terminal readiness, and
diff --git a/packages/subprocess/subprocess/src/invariant.ts b/packages/subprocess/subprocess/src/invariant.ts
index 62a720babd..3a6ae526b0 100644
--- a/packages/subprocess/subprocess/src/invariant.ts
+++ b/packages/subprocess/subprocess/src/invariant.ts
@@ -10,7 +10,7 @@ export const name = 'subprocess-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
-/** No runtime invariant: this stateless seam owns spawn-spec/handle types, while implementations own observations. */
+/** No runtime invariant: this stateless Service Definition owns spawn-spec/handle types, while Service providers own observations. */
 const install: InvariantInstaller = () => {}
 
 /**
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index 2aa2de0c91..058d11efb3 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -1,5 +1,5 @@
 /**
- * Vocabulary for the subprocess seam: fully-specified spawn requests with
+ * Vocabulary for the subprocess Service Definition: fully-specified spawn requests with
  * Node-shaped per-stream stdio modes, bounded collected output with spill
  * recovery, raw piped streams, and tree-scoped termination. Command
  * defaulting, shell semantics, protocol framing, and presentation belong to
diff --git a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
index 96aedb5e98..e74de2bd0e 100644
--- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
+++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
@@ -149,7 +149,7 @@ async function handlePrompt(id: number | string): Promise<void> {
       override: process.env.DSH_SNAPSHOT_OVERRIDE ?? null,
       childFiles: process.env.DSH_SNAPSHOT_CHILD_FILES ?? null,
       spillRoot: process.env.DSH_SNAPSHOT_SPILL_ROOT ?? null,
-      // Scenario-supplied deployment env (the `Scenario.env` layering seam).
+      // Scenario-supplied deployment env (the `Scenario.env` layering hook).
       permissionMode: process.env.DSH_PERMISSION_MODE ?? null,
     })}`)
   }
diff --git a/packages/support/invariants/src/index.ts b/packages/support/invariants/src/index.ts
index 9e5c30ea60..917e5327d4 100644
--- a/packages/support/invariants/src/index.ts
+++ b/packages/support/invariants/src/index.ts
@@ -191,7 +191,7 @@ export class InvariantService extends Service {
       throw error
     }
     // Cordis attaches setup thenability and async teardown to this callable;
-    // the service seam intentionally exposes only the conventional disposer.
+    // the service contract intentionally exposes only the conventional disposer.
     // oxlint-disable-next-line typescript/no-misused-promises -- the extra runtime shape stays private.
     return registration
   }
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index 5c9a575f5c..efdab32824 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -23,7 +23,7 @@ import {
 /**
  * Unit tests for the replay llm/stream plugin. These drive the listener through
  * the REAL LlmService waterfall (not a hand-rolled stub) so they verify the
- * actual seam the snapshot harness depends on, plus the pure
+ * actual LLM capability seam the snapshot harness depends on, plus the pure
  * derive/parse/load helpers that turn a recorded session JSONL into a script.
  */
 
diff --git a/packages/tasks/README.i18n.yaml b/packages/tasks/README.i18n.yaml
index bf9be6a596..13061d820b 100644
--- a/packages/tasks/README.i18n.yaml
+++ b/packages/tasks/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/tasks/README.md
-README.md: e0b6769cd1d28cc7159310a6ec6f5c8d94a81a24
-README.zh.md: 97d258ffdc88b728ecabd9d20afaf228d620d8a4
+README.md: 32db45b822299f9d18f79a08d3a9264a12661b60
+README.zh.md: a33f390bddab7b51778b153f5121e2d11c6ed380
diff --git a/packages/tasks/README.md b/packages/tasks/README.md
index e0b6769cd1..32db45b822 100644
--- a/packages/tasks/README.md
+++ b/packages/tasks/README.md
@@ -12,4 +12,4 @@ This family gives long-running tools one owner-isolated background-task protocol
 
 See the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) decisions.
 
-The subsystem reference — the id scheme, the owner-fenced contract, snapshots — is [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md); design in the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Notes.
+The subsystem reference — the id scheme, the owner-fenced contract, snapshots — is [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md); design in the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry contract](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Notes.
diff --git a/packages/tasks/README.zh.md b/packages/tasks/README.zh.md
index 97d258ffdc..a33f390bdd 100644
--- a/packages/tasks/README.zh.md
+++ b/packages/tasks/README.zh.md
@@ -12,4 +12,4 @@
 
 参见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和[任务注册表](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)决策。
 
-子系统参考——id 方案、拥有者围栏约定、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表 seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。
+子系统参考——id 方案、拥有者围栏约定、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表约定](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。
diff --git a/packages/tasks/tasks-local/README.i18n.yaml b/packages/tasks/tasks-local/README.i18n.yaml
index 7dbd6dd7e4..d4fa5d09bf 100644
--- a/packages/tasks/tasks-local/README.i18n.yaml
+++ b/packages/tasks/tasks-local/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/tasks/tasks-local/README.md
-README.md: 23ca6fca61ccb59c855e5d6da6b0a2e23e7cb632
-README.zh.md: 5b04caaf640042049e4ef9e6fa58a30adc6f8f72
+README.md: 663ce0d333c6df0f84900a2570d5487d8d7abe55
+README.zh.md: a5d1acaa50f63dc95b7607657b157272c15a4f11
diff --git a/packages/tasks/tasks-local/README.md b/packages/tasks/tasks-local/README.md
index 23ca6fca61..663ce0d333 100644
--- a/packages/tasks/tasks-local/README.md
+++ b/packages/tasks/tasks-local/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Process-local implementation of the [`@deepseek-ai/dsh-tasks`](../tasks/README.md) registry seam: `LocalTaskService` keeps every record in memory, issues per-kind `<kind>-N` ids, and hands out fresh snapshots, never live state. It has no config; load it as a plugin and it registers as `ctx.tasks`.
+Process-local implementation of the [`@deepseek-ai/dsh-tasks`](../tasks/README.md) registry contract: `LocalTaskService` keeps every record in memory, issues per-kind `<kind>-N` ids, and hands out fresh snapshots, never live state. It has no config; load it as a plugin and it registers as `ctx.tasks`.
 
 ## Lifecycle
 
diff --git a/packages/tasks/tasks-local/README.zh.md b/packages/tasks/tasks-local/README.zh.md
index 5b04caaf64..a5d1acaa50 100644
--- a/packages/tasks/tasks-local/README.zh.md
+++ b/packages/tasks/tasks-local/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-tasks`](../tasks/README.md) 注册表 seam 的进程本地实现：`LocalTaskService` 把每条记录保存在内存中，按 kind 签发 `<kind>-N` id，并且只交出全新快照，从不交出实时状态。它没有配置；作为插件加载后即注册为 `ctx.tasks`。
+[`@deepseek-ai/dsh-tasks`](../tasks/README.md) 注册表约定的进程本地实现：`LocalTaskService` 把每条记录保存在内存中，按 kind 签发 `<kind>-N` id，并且只交出全新快照，从不交出实时状态。它没有配置；作为插件加载后即注册为 `ctx.tasks`。
 
 ## 生命周期
 
diff --git a/packages/tasks/tasks-local/src/index.ts b/packages/tasks/tasks-local/src/index.ts
index f108022b17..60a7beb012 100644
--- a/packages/tasks/tasks-local/src/index.ts
+++ b/packages/tasks/tasks-local/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Process-local implementation of the background task registry seam
+ * Process-local provider for the background-task capability seam
  * (`ctx.tasks`). It keeps every record in memory and hands out fresh
  * snapshots, never live state.
  *
@@ -50,7 +50,7 @@ function isTerminal(status: TaskStatus): boolean {
 }
 
 /**
- * The in-memory `tasks` registry. See the seam contract in
+ * The in-memory `tasks` registry. See the Service Definition contract in
  * `@deepseek-ai/dsh-tasks` for the ownership, isolation, and lifecycle
  * semantics this implementation honors.
  */
diff --git a/packages/tasks/tasks-local/src/invariant.ts b/packages/tasks/tasks-local/src/invariant.ts
index 3447287c08..22f2b4fecd 100644
--- a/packages/tasks/tasks-local/src/invariant.ts
+++ b/packages/tasks/tasks-local/src/invariant.ts
@@ -15,7 +15,7 @@ export const name = 'tasks-local-invariant'
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: the seam companion in `@deepseek-ai/dsh-tasks` already
+ * No runtime invariant: the Service Definition companion in `@deepseek-ai/dsh-tasks` already
  * validates every registry snapshot this implementation publishes.
  */
 const install: InvariantInstaller = () => {}
diff --git a/packages/tasks/tasks/README.i18n.yaml b/packages/tasks/tasks/README.i18n.yaml
index e7206370dd..94f8993c2c 100644
--- a/packages/tasks/tasks/README.i18n.yaml
+++ b/packages/tasks/tasks/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/tasks/tasks/README.md
-README.md: b5a7380e0cb7df5dd20baecea8656db2aad3460a
-README.zh.md: 5cbcfac8d7153616c39642c11860fc88b8495d1f
+README.md: 04ca125580104d0cb5ab0ce8cdd20d104c4a1668
+README.zh.md: b0b079566246549c7acab7a83fcc3c21c44ef868
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index b5a7380e0c..04ca125580 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The background task registry seam (`ctx.tasks`). The abstract `TaskService` and its vocabulary types give long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup under one contract; the process-local registry lives in [`dsh-tasks-local`](../tasks-local/README.md). Producer plugins extend `TaskKindMap` with their opaque id namespace.
+The background task registry contract (`ctx.tasks`). The abstract `TaskService` and its vocabulary types give long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup under one contract; the process-local registry lives in [`dsh-tasks-local`](../tasks-local/README.md). Producer plugins extend `TaskKindMap` with their opaque id namespace.
 
 ## Service contract
 
diff --git a/packages/tasks/tasks/README.zh.md b/packages/tasks/tasks/README.zh.md
index 5cbcfac8d7..b0b0795662 100644
--- a/packages/tasks/tasks/README.zh.md
+++ b/packages/tasks/tasks/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-后台任务注册表 seam（`ctx.tasks`）。抽象的 `TaskService` 及其词汇类型在同一份约定下为长时间运行的生产方提供共享 id、owner 隔离、读取、取消、等待、通知和清理；进程局部注册表位于 [`dsh-tasks-local`](../tasks-local/README.md)。生产方插件使用其不透明 id namespace 扩展 `TaskKindMap`。
+后台任务注册表约定（`ctx.tasks`）。抽象的 `TaskService` 及其词汇类型在同一份约定下为长时间运行的生产方提供共享 id、owner 隔离、读取、取消、等待、通知和清理；进程局部注册表位于 [`dsh-tasks-local`](../tasks-local/README.md)。生产方插件使用其不透明 id namespace 扩展 `TaskKindMap`。
 
 ## 服务约定
 
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index e237aa0681..26b690437c 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The background task registry seam (`ctx.tasks`). It owns the contract for
+ * The background-task Service Definition (`ctx.tasks`). It owns the contract for
  * task ids, session-scoped access, lifecycle state, completion listeners, and
  * owner cleanup while producers retain their execution resources. The
  * process-local registry lives in `@deepseek-ai/dsh-tasks-local`.
diff --git a/packages/tasks/tasks/tests/service.spec.ts b/packages/tasks/tasks/tests/service.spec.ts
index 82fc415f51..9c6e2654e3 100644
--- a/packages/tasks/tasks/tests/service.spec.ts
+++ b/packages/tasks/tasks/tests/service.spec.ts
@@ -5,7 +5,7 @@ import { TaskId, TaskService } from '@deepseek-ai/dsh-tasks'
 import type { TaskDoneListener, TaskRead, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
 
 /**
- * Minimal concrete registry: one canned record. The seam owns the contract
+ * Minimal concrete registry: one canned record. The Service Definition owns the contract
  * only (ids, snapshots, authorization-shaped signatures); the registry
  * behavior suite lives with `@deepseek-ai/dsh-tasks-local`.
  */
diff --git a/packages/todo/README.i18n.yaml b/packages/todo/README.i18n.yaml
index b9f4c9fef1..4df1b35bcb 100644
--- a/packages/todo/README.i18n.yaml
+++ b/packages/todo/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/todo/README.md
-README.md: 6c7dccbbfb007737593550cea91444f8f735cf81
-README.zh.md: 9c5d6a9cc3f6078d5609aea668684ea0e4275835
+README.md: 6bbc9fe4f04cc4a82573c643c5c00bbecde069ed
+README.zh.md: ae7de52eeded877e92c94dbc6c6e1addf76aa8b4
diff --git a/packages/todo/README.md b/packages/todo/README.md
index 6c7dccbbfb..6bbc9fe4f0 100644
--- a/packages/todo/README.md
+++ b/packages/todo/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The model-facing todo capability. It is a single **product** package because one agent session owns the list; there is no replaceable provider seam.
+The model-facing todo capability. It is a single **product** package because one agent session owns the list; there is no replaceable provider contract.
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/todo/README.zh.md b/packages/todo/README.zh.md
index 9c5d6a9cc3..ae7de52eed 100644
--- a/packages/todo/README.zh.md
+++ b/packages/todo/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向模型的 todo 能力。它是单一**产品**包，因为一个 agent（智能体）会话拥有该列表；不存在可替换的提供方 seam。
+面向模型的 todo 能力。它是单一**产品**包，因为一个 agent（智能体）会话拥有该列表；不存在可替换的提供方约定。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
diff --git a/packages/todo/tool-todo/README.i18n.yaml b/packages/todo/tool-todo/README.i18n.yaml
index 6aa521df26..750040bb87 100644
--- a/packages/todo/tool-todo/README.i18n.yaml
+++ b/packages/todo/tool-todo/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/todo/tool-todo/README.md
-README.md: 7c993ac6f7f0047d008a09e5ff52cb752f94763c
-README.zh.md: 9cea66147beddab7d62ed7344cbe866495e28022
+README.md: 4848758dd8f2049221901744e5d09cef2dd31591
+README.zh.md: 39cb243d1cf59bf51e524a9a778f67e841ae16ff
diff --git a/packages/todo/tool-todo/README.md b/packages/todo/tool-todo/README.md
index 7c993ac6f7..4848758dd8 100644
--- a/packages/todo/tool-todo/README.md
+++ b/packages/todo/tool-todo/README.md
@@ -30,7 +30,7 @@ The canonical result is `{ todos, counts: { pending, inProgress, completed } }`;
 
 ## Session projection
 
-When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `todos` projection unit under an injected child: `init` = `null` (no write yet), `apply` = take the whole list from each `todo/write` and clear to `null` on each `turn/start` (standing plan; `turn/end` keeps the finished checklist; every other event returns the same state reference), `view` = identity, `stateVersion` = 2. The key merges into `SessionProjectionMap` here (via the interface package's `/types` outlet); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected. Lifetime rationale: [todo plan clears on next turn](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md).
+When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `todos` projection unit under an injected child: `init` = `null` (no write yet), `apply` = take the whole list from each `todo/write` and clear to `null` on each `turn/start` (standing plan; `turn/end` keeps the finished checklist; every other event returns the same state reference), `view` = identity, `stateVersion` = 2. The key merges into `SessionProjectionMap` here (via the Service Definition package's `/types` outlet); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected. Lifetime rationale: [todo plan clears on next turn](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md).
 
 ## Export shape
 
diff --git a/packages/todo/tool-todo/README.zh.md b/packages/todo/tool-todo/README.zh.md
index 9cea66147b..39cb243d1c 100644
--- a/packages/todo/tool-todo/README.zh.md
+++ b/packages/todo/tool-todo/README.zh.md
@@ -30,7 +30,7 @@
 
 ## 会话投影
 
-当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)）时，本包在一个注入的子插件中注册 `todos` 投影单元：`init` = `null`（尚无写入）、`apply` = 从每个 `todo/write` 取整表，并在每个 `turn/start` 清为 `null`（当前有效计划；`turn/end` 保留刚完成的清单；其余事件都返回同一个状态引用）、`view` = 恒等、`stateVersion` = 2。该键在本包中合并进 `SessionProjectionMap`（经接口包的 `/types` 出口）；框架驱动该单元，载体通过历史尾页与 `session/projection` 推送帧提供该值。未挂载注册表的组合不受影响。生命周期理由见 [在下一轮次清空 todo 计划](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)。
+当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)）时，本包在一个注入的子插件中注册 `todos` 投影单元：`init` = `null`（尚无写入）、`apply` = 从每个 `todo/write` 取整表，并在每个 `turn/start` 清为 `null`（当前有效计划；`turn/end` 保留刚完成的清单；其余事件都返回同一个状态引用）、`view` = 恒等、`stateVersion` = 2。该键在本包中合并进 `SessionProjectionMap`（经 Service Definition 包的 `/types` 出口）；框架驱动该单元，载体通过历史尾页与 `session/projection` 推送帧提供该值。未挂载注册表的组合不受影响。生命周期理由见 [在下一轮次清空 todo 计划](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)。
 
 ## 导出形状
 
diff --git a/packages/todo/tool-todo/tests/integration.spec.ts b/packages/todo/tool-todo/tests/integration.spec.ts
index f10f2c49e2..568b0f764a 100644
--- a/packages/todo/tool-todo/tests/integration.spec.ts
+++ b/packages/todo/tool-todo/tests/integration.spec.ts
@@ -10,7 +10,7 @@ import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent
 
 /**
  * Full-loop integration: a scripted mock model drives the REAL todo_write tool
- * through the agent loop, exercising the same seams a live model would — the
+ * through the agent loop, exercising the same execution paths a live model would — the
  * tool/call + tool/result session events AND the todo/write event the tool
  * appends. Only the model is mocked; the tool and the session log are real.
  */
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index 553ab75490..1950c255cb 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -84,6 +84,8 @@ export interface ServiceEntry {
   key: string
   /** The service class/interface name, e.g. `LlmService`. */
   type: string
+  /** Whether the service class is abstract (a seam interface). */
+  abstract: boolean
   /** Class-level JSDoc prose, one line per paragraph. */
   doc: string
   /** Public methods (bodies stripped), in source order. */
@@ -256,6 +258,7 @@ export class CordisCatalogProjector {
         entries.push({
           key: service.key,
           type: declaration.name,
+          abstract: declaration.abstract,
           doc,
           methods,
           source,
@@ -744,7 +747,8 @@ function renderEvent(e: EventEntry, onPage: string, linkedTypePages: Readonly<Re
 
 /** Render one harness service entry onto its owning page. */
 function renderService(s: ServiceEntry, onPage: string, linkedTypePages: Readonly<Record<string, string>>): string[] {
-  const out = [...anchorFor(`ctx.${s.key} — ${s.type}`), `### \`ctx.${s.key}\` — \`${s.type}\``, '']
+  const kind = s.abstract ? ' (abstract seam)' : ''
+  const out = [...anchorFor(`ctx.${s.key} — ${s.type}${kind}`), `### \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
   if (s.doc) out.push(s.doc, '')
   if (s.methods.length) {
     const declarations = s.methods.flatMap((method, index) => [
diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
index a6b68a4ee7..bde52505dc 100644
--- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
+++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts
@@ -259,7 +259,7 @@ export class FixService {
   it('extracts a well-formed service with its methods and class JSDoc', () => {
     const services = collectServices(makeService(WELL_FORMED))
     expect(services).toHaveLength(1)
-    expect(services[0]).toMatchObject({ key: 'fix', type: 'FixService', doc: 'Fixture service.' })
+    expect(services[0]).toMatchObject({ key: 'fix', type: 'FixService', abstract: false, doc: 'Fixture service.' })
     expect(services[0]?.methods).toHaveLength(3)
     expect(services[0]?.methods[0]).toEqual({
       signature: 'run(id: string): string',
diff --git a/packages/web/tool-web/README.i18n.yaml b/packages/web/tool-web/README.i18n.yaml
index 4a1d973a1a..4628341ad1 100644
--- a/packages/web/tool-web/README.i18n.yaml
+++ b/packages/web/tool-web/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/web/tool-web/README.md
-README.md: 646601bb5bd6c27876918b7aca49962ae34bae33
-README.zh.md: 135c75831045225a0ac6d4637ff5c8b4105336c0
+README.md: 643da4e2f083c2efabd39a462290559ddbd291c8
+README.zh.md: 7b52f2b08f393a584258dea1a216d9124ec8760a
diff --git a/packages/web/tool-web/README.md b/packages/web/tool-web/README.md
index 646601bb5b..643da4e2f0 100644
--- a/packages/web/tool-web/README.md
+++ b/packages/web/tool-web/README.md
@@ -15,7 +15,7 @@ Each tool is registered independently; a product that wants only one disables th
 
 Both tools opt into concurrent scheduling because provider reads return content without mutating parent-agent state.
 
-The normalized seam results are also the canonical tool values: `WebSearchResult` and `WebFetchResult`. Native renderers preserve the answer/source and fetched-body text below; provider search/body caps remain acquisition limits rather than presentation-only truncation.
+The normalized service results are also the canonical tool values: `WebSearchResult` and `WebFetchResult`. Native renderers preserve the answer/source and fetched-body text below; provider search/body caps remain acquisition limits rather than presentation-only truncation.
 
 ## Config
 
diff --git a/packages/web/tool-web/README.zh.md b/packages/web/tool-web/README.zh.md
index 135c758310..7b52f2b08f 100644
--- a/packages/web/tool-web/README.zh.md
+++ b/packages/web/tool-web/README.zh.md
@@ -15,7 +15,7 @@
 
 两个工具都选择并发调度，因为提供方读取会返回内容，不会修改父 agent（智能体）的状态。
 
-规范化后的 seam 结果也是标准工具值：`WebSearchResult` 与 `WebFetchResult`。原生渲染器会保留下文所述的答案、来源和抓取正文文本；提供方对搜索结果数量和正文大小的上限仍属于获取限制，而非仅用于呈现的截断。
+规范化后的服务结果也是标准工具值：`WebSearchResult` 与 `WebFetchResult`。原生渲染器会保留下文所述的答案、来源和抓取正文文本；提供方对搜索结果数量和正文大小的上限仍属于获取限制，而非仅用于呈现的截断。
 
 ## 配置
 
diff --git a/packages/web/tool-web/src/fetch.ts b/packages/web/tool-web/src/fetch.ts
index d642615874..94130df697 100644
--- a/packages/web/tool-web/src/fetch.ts
+++ b/packages/web/tool-web/src/fetch.ts
@@ -2,7 +2,7 @@
  * The model-facing `web_fetch` tool. This module owns its schema, validation, and presentation;
  * `ctx.web` owns retrieval. Timeout is deployment policy, not a model argument: config becomes
  * `ToolDefinition.timeoutMs`, timeout policy enforces it, and this tool forwards the resulting
- * signal. A provider timeout remains a backstop for direct seam callers.
+ * signal. A provider timeout remains a backstop for direct service callers.
  */
 
 import type { Context } from 'cordis'
diff --git a/packages/web/web-fetch-local/README.i18n.yaml b/packages/web/web-fetch-local/README.i18n.yaml
index 5511f72975..b1a9a6a7bf 100644
--- a/packages/web/web-fetch-local/README.i18n.yaml
+++ b/packages/web/web-fetch-local/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/web/web-fetch-local/README.md
-README.md: 531bfc94a4b2867b1a81d2e0b398ec403186b347
-README.zh.md: 260227679b72ec993dbb9e42a9d2a814bf691e2c
+README.md: 03d6d2a96b04528b33cd063736e8618e66932058
+README.zh.md: 66a8ebe0839c8ba494c3a30b761025fb6b3f75bb
diff --git a/packages/web/web-fetch-local/README.md b/packages/web/web-fetch-local/README.md
index 531bfc94a4..03d6d2a96b 100644
--- a/packages/web/web-fetch-local/README.md
+++ b/packages/web/web-fetch-local/README.md
@@ -12,7 +12,7 @@ The provider owns **safe resource retrieval**: URL validation, HTTP transport, r
 
 The provider's `timeoutMs` is a resource backstop for direct `ctx.web.fetch()` callers and misconfigured deployments, not the model-facing tool-call budget. [`dsh-timeout-policy`](../../guard/timeout-policy/README.md) owns the `web_fetch` tool-call budget by arming `exec.signal`.
 
-A shipping web-tool deployment sets the provider backstop above the tool budget, so model calls normally return `TOOL_TIMEOUT`. If the outer deadline reaches the provider first, the provider reports `WEB_ABORTED` and the outer policy replaces it with `TOOL_TIMEOUT`. `WEB_FETCH_TIMEOUT` therefore identifies a direct seam caller whose provider budget elapsed.
+A shipping web-tool deployment sets the provider backstop above the tool budget, so model calls normally return `TOOL_TIMEOUT`. If the outer deadline reaches the provider first, the provider reports `WEB_ABORTED` and the outer policy replaces it with `TOOL_TIMEOUT`. `WEB_FETCH_TIMEOUT` therefore identifies a direct service caller whose provider budget elapsed.
 
 ## Transport hygiene
 
diff --git a/packages/web/web-fetch-local/README.zh.md b/packages/web/web-fetch-local/README.zh.md
index 260227679b..66a8ebe083 100644
--- a/packages/web/web-fetch-local/README.zh.md
+++ b/packages/web/web-fetch-local/README.zh.md
@@ -12,7 +12,7 @@
 
 提供方的 `timeoutMs` 是直接 `ctx.web.fetch()` 调用方和配置有误的部署所用的资源兜底，不是面向模型的工具调用预算。[`dsh-timeout-policy`](../../guard/timeout-policy/README.md) 拥有 `web_fetch` 工具调用预算，并让 `exec.signal` 在超时时触发，以强制执行该预算。
 
-已交付的 web 工具部署会把提供方兜底设为高于工具预算，因此模型调用通常返回 `TOOL_TIMEOUT`。如果外层截止期限先于提供方的兜底超时触发，提供方会报告 `WEB_ABORTED`，外层策略再将其替换为 `TOOL_TIMEOUT`。因此，`WEB_FETCH_TIMEOUT` 表明直接 seam 调用方的提供方预算已经耗尽。
+已交付的 web 工具部署会把提供方兜底设为高于工具预算，因此模型调用通常返回 `TOOL_TIMEOUT`。如果外层截止期限先于提供方的兜底超时触发，提供方会报告 `WEB_ABORTED`，外层策略再将其替换为 `TOOL_TIMEOUT`。因此，`WEB_FETCH_TIMEOUT` 表明直接服务调用方的提供方预算已经耗尽。
 
 ## 传输卫生
 
diff --git a/packages/web/web-search-deepseek/src/provider.ts b/packages/web/web-search-deepseek/src/provider.ts
index aef898ed60..4bacd80fec 100644
--- a/packages/web/web-search-deepseek/src/provider.ts
+++ b/packages/web/web-search-deepseek/src/provider.ts
@@ -135,7 +135,7 @@ export function citationSnippets(blocks: readonly ContentBlock[]): Map<string, s
  * Map a DeepSeek Anthropic Messages response to a normalized search result. Walks
  * `web_search_tool_result` blocks for citeable `web_search_result` items, joins each to its
  * citation excerpt as `snippet`, and dedupes by `url` (a `max_uses > 1` request can surface
- * the same URL across searches). The seam owns the final `maxResults` truncation, so
+ * the same URL across searches). The web service owns the final `maxResults` truncation, so
  * `truncated` is always `false` here.
  *
  * @param response - the parsed Messages response body.
diff --git a/packages/web/web-search-exa/README.i18n.yaml b/packages/web/web-search-exa/README.i18n.yaml
index 9adda78384..4afbbcbc5d 100644
--- a/packages/web/web-search-exa/README.i18n.yaml
+++ b/packages/web/web-search-exa/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/web/web-search-exa/README.md
-README.md: c24f952eede90aae6fa23eec976255cb99625c19
-README.zh.md: 58255a564601ae4d57f1916507a76a55cdbabf44
+README.md: 5b1212c1fb210a3aca7836875cc295fad87e7437
+README.zh.md: fc9afbe44dcb5dd55c7007a11b35048217143351
diff --git a/packages/web/web-search-exa/README.md b/packages/web/web-search-exa/README.md
index c24f952eed..5b1212c1fb 100644
--- a/packages/web/web-search-exa/README.md
+++ b/packages/web/web-search-exa/README.md
@@ -38,5 +38,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **A result with no non-blank highlight is dropped entirely** — no portable snippet to map, so fewer sources than the requested count can return.
-- **Only `searchType`/`numResults`/`highlightsPerResult` are exposed** — Exa's other controls (livecrawl, category, domain/date filters, full-text contents) wait on provider-neutral seam fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
+- **Only `searchType`/`numResults`/`highlightsPerResult` are exposed** — Exa's other controls (livecrawl, category, domain/date filters, full-text contents) wait on provider-neutral Service Definition fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
 - **Abort classification is error-shape-based** — only a `DOMException` named `AbortError` maps to `WEB_ABORTED`; an abort carrying a custom reason (e.g. `dsh-timeout`'s `TimeoutReason`) surfaces as `WEB_PROVIDER_ERROR`.
diff --git a/packages/web/web-search-exa/README.zh.md b/packages/web/web-search-exa/README.zh.md
index 58255a5646..fc9afbe44d 100644
--- a/packages/web/web-search-exa/README.zh.md
+++ b/packages/web/web-search-exa/README.zh.md
@@ -38,5 +38,5 @@ Exa 返回扁平 `results[]`，不返回生成答案，因此省略 `content`。
 ## 已知限制与暂缓事项
 
 - **没有非空白高亮摘要的结果会被整个丢弃**：没有可映射的可移植 snippet，因此返回源可能少于请求数量。
-- **只公开 `searchType`／`numResults`／`highlightsPerResult`**：Exa 的其他控制项（livecrawl、category、域名／日期过滤条件、全文内容）等待提供方无关 seam 字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
+- **只公开 `searchType`／`numResults`／`highlightsPerResult`**：Exa 的其他控制项（livecrawl、category、域名／日期过滤条件、全文内容）等待提供方无关的 Service Definition 字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
 - **按错误形状分类中止**：只有 `DOMException` 且名为 `AbortError` 时才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）会呈现为 `WEB_PROVIDER_ERROR`。
diff --git a/packages/web/web-search-exa/src/provider.ts b/packages/web/web-search-exa/src/provider.ts
index 3c62dabfa5..a27449ccd4 100644
--- a/packages/web/web-search-exa/src/provider.ts
+++ b/packages/web/web-search-exa/src/provider.ts
@@ -75,7 +75,7 @@ export function mapExaResponse(response: ExaSearchResponse): WebSearchResult {
   const sources = (response.results ?? [])
     .map(mapExaResult)
     .filter((source): source is WebSearchSource => source !== undefined)
-  // Exa returns no generated answer, so `content` is omitted. The seam owns the
+  // Exa returns no generated answer, so `content` is omitted. The web service owns the
   // final `maxResults` truncation, so this provider reports `truncated: false`.
   return { sources, truncated: false }
 }
diff --git a/packages/web/web-search-perplexity/README.i18n.yaml b/packages/web/web-search-perplexity/README.i18n.yaml
index 6d5f34e989..ca293211ad 100644
--- a/packages/web/web-search-perplexity/README.i18n.yaml
+++ b/packages/web/web-search-perplexity/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/web/web-search-perplexity/README.md
-README.md: 80f6d34d63ddf0cc7d1f0d4f6744d64c91f9a269
-README.zh.md: 485ba992a6fbc7bb6e4bb4a6753b7c34e9f61292
+README.md: 8800609a05e99d3fa8a61e12b2360e633f0fd330
+README.zh.md: fb20d796e9e943a5254b1d22eac3650e45ec95bf
diff --git a/packages/web/web-search-perplexity/README.md b/packages/web/web-search-perplexity/README.md
index 80f6d34d63..8800609a05 100644
--- a/packages/web/web-search-perplexity/README.md
+++ b/packages/web/web-search-perplexity/README.md
@@ -51,7 +51,7 @@ Through [`dsh-tool-web`](../tool-web/README.md), the conversation model sees the
 
 #### Token effect
 
-Zero direct conversation tokens from registration. Answer and source tokens are data-dependent, source count is seam-bounded, and the retained result or error is resent until compaction.
+Zero direct conversation tokens from registration. Answer and source tokens are data-dependent, source count is service-bounded, and the retained result or error is resent until compaction.
 
 #### KV Cache effect
 
@@ -61,5 +61,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 - **Citation-fallback sources are URL-only** — when Perplexity omits structured `search_results[]`, sources carry no `title`/`snippet`/`publishedAt`, so the tool renders bare hostname labels.
 - **Over-returned sources still cost tokens and latency** — with no result-count control on the wire, `maxResults` is enforced only post-hoc by seam truncation.
-- **Only `model`/`maxTokens`/`searchRecency` are exposed** — Perplexity's other search controls (domain filters, `web_search_options` context size, images) wait on provider-neutral seam fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
+- **Only `model`/`maxTokens`/`searchRecency` are exposed** — Perplexity's other search controls (domain filters, `web_search_options` context size, images) wait on provider-neutral Service Definition fields ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
 - **Abort classification is error-shape-based** — only a `DOMException` named `AbortError` maps to `WEB_ABORTED`; an abort carrying a custom reason (e.g. `dsh-timeout`'s `TimeoutReason`) surfaces as `WEB_PROVIDER_ERROR`.
diff --git a/packages/web/web-search-perplexity/README.zh.md b/packages/web/web-search-perplexity/README.zh.md
index 485ba992a6..fb20d796e9 100644
--- a/packages/web/web-search-perplexity/README.zh.md
+++ b/packages/web/web-search-perplexity/README.zh.md
@@ -51,7 +51,7 @@
 
 #### Token 影响
 
-注册不会直接产生会话 token。答案与源 token 取决于数据，源数量受 seam 限制；保留的结果或错误会重复发送，直到发生压缩（compaction）。
+注册不会直接产生会话 token。答案与源 token 取决于数据，源数量受服务限制；保留的结果或错误会重复发送，直到发生压缩（compaction）。
 
 #### KV Cache 影响
 
@@ -61,5 +61,5 @@
 
 - **引用回退源只含 URL**：Perplexity 省略结构化 `search_results[]` 时，源不含 `title`／`snippet`／`publishedAt`，因此工具只渲染纯主机名标签。
 - **超量返回的来源仍会增加 token 消耗和延迟**：协议没有结果数量控制，`maxResults` 只能由 seam 在事后截断。
-- **只公开 `model`／`maxTokens`／`searchRecency`**：Perplexity 的其他搜索控制项（域名过滤条件、`web_search_options` 上下文大小、图片）等待提供方无关 seam 字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
+- **只公开 `model`／`maxTokens`／`searchRecency`**：Perplexity 的其他搜索控制项（域名过滤条件、`web_search_options` 上下文大小、图片）等待提供方无关的 Service Definition 字段（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
 - **按错误形状分类中止**：只有 `DOMException` 且名为 `AbortError` 时才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）会呈现为 `WEB_PROVIDER_ERROR`。
diff --git a/packages/web/web/README.i18n.yaml b/packages/web/web/README.i18n.yaml
index 5adff6e81c..6f079335f9 100644
--- a/packages/web/web/README.i18n.yaml
+++ b/packages/web/web/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/web/web/README.md
-README.md: c05965478a049b4145a94075e42bd9602675628f
-README.zh.md: 686157cc87ff456ccc535e3f92fd6524758b35f4
+README.md: 22301a144b2e06ab42e1d503e8f8c554f7886330
+README.zh.md: 027b863cd7835f378de5f5c5d41166938b8cfe1a
diff --git a/packages/web/web/README.md b/packages/web/web/README.md
index c05965478a..22301a144b 100644
--- a/packages/web/web/README.md
+++ b/packages/web/web/README.md
@@ -4,15 +4,15 @@ English | [中文](README.zh.md)
 
 The **`WebService`** (`ctx.web`) defines WHAT web access the harness has — search the web, fetch a URL — over multiple providers, without binding the model contract to one vendor's API shape.
 
-This package is the interface third of the web capability. Unlike bash/fs it spans two capabilities (search and fetch) on one seam, with potentially multiple providers each:
+This package owns the Service Definition role of the web capability. Unlike bash/fs it spans two operations (search and fetch) on one seam, with potentially multiple providers each:
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-web` (this) | the interface: the service, provider registries, selection policy, request/result vocabulary, the `WebError` taxonomy |
-| `@deepseek-ai/dsh-web-search-exa` | a search implementation: Exa |
-| `@deepseek-ai/dsh-web-search-perplexity` | a search implementation: Perplexity |
-| `@deepseek-ai/dsh-web-fetch-local` | a fetch implementation: anonymous public HTTP(S) |
-| `@deepseek-ai/dsh-tool-web` | the model-facing `web_search` / `web_fetch` tool schemas over `ctx.web` |
+| `@deepseek-ai/dsh-web` (this) | Service Definition: the service, provider registries, selection policy, request/result vocabulary, the `WebError` taxonomy |
+| `@deepseek-ai/dsh-web-search-exa` | Search provider: Exa |
+| `@deepseek-ai/dsh-web-search-perplexity` | Search provider: Perplexity |
+| `@deepseek-ai/dsh-web-fetch-local` | Fetch provider: anonymous public HTTP(S) |
+| `@deepseek-ai/dsh-tool-web` | Consumer: the model-facing `web_search` / `web_fetch` tool schemas over `ctx.web` |
 
 Search and fetch share no request schema and no business logic, but they are deliberately one seam: `ctx.web` is a single web-access middle layer with one provider-selection policy owner, one abort/error vocabulary, and one product-facing "how this harness reaches the web" config surface. The cost is the parallel `Search`/`Fetch` method pairs; that parallelism is intentional, not a missed extraction.
 
@@ -58,4 +58,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **No observation surface** — no provider-change event and no capability-status query; availability is observed only by executing `search()`/`fetch()` and routing the thrown `WebError` codes, and the no-provider failure is the generic `WEB_PROVIDER_UNAVAILABLE` with no per-provider reason enumeration ([Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md)).
 - **`WebSearchRequest` carries only `query` + `maxResults`** — provider-neutral controls (recency, domain filters, regional hints, search depth) are deferred until Exa and Perplexity can both honor them honestly ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
 - **`WebFetchBody` has no `pdf` arm** — text-extractable PDF support is named deferred work; the closed union makes adding it a compile-enforced change across the three web packages.
-- **Provider-backed page extraction is out of scope of `fetch()`** — a Firecrawl/Tavily-style `web_extract` capability is deferred rather than widening the fetch seam.
+- **Provider-backed page extraction is out of scope of `fetch()`** — a Firecrawl/Tavily-style `web_extract` capability is deferred rather than widening the fetch operation.
diff --git a/packages/web/web/README.zh.md b/packages/web/web/README.zh.md
index 686157cc87..027b863cd7 100644
--- a/packages/web/web/README.zh.md
+++ b/packages/web/web/README.zh.md
@@ -2,17 +2,17 @@
 
 [English](README.md) | 中文
 
-**`WebService`**（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型契约绑定到某个厂商的 API 形状。
+**`WebService`**（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型约定绑定到某个厂商的 API 形状。
 
-该包是 web 能力中负责接口的三分之一。与 bash/fs 不同，它在一个 seam 上跨越搜索与抓取两种能力，每种能力都可能有多个提供方：
+本包承担 web 能力的 Service Definition 角色。与 bash/fs 不同，它在一个 seam 上跨越搜索与抓取两种操作，每种操作都可能有多个提供方：
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-web`（本包） | 接口：服务、提供方注册表、选择策略、请求／结果词汇、`WebError` 分类体系 |
-| `@deepseek-ai/dsh-web-search-exa` | 搜索实现：Exa |
-| `@deepseek-ai/dsh-web-search-perplexity` | 搜索实现：Perplexity |
-| `@deepseek-ai/dsh-web-fetch-local` | 抓取实现：匿名公共 HTTP(S) |
-| `@deepseek-ai/dsh-tool-web` | 面向模型的 `web_search`／`web_fetch` 工具 schema，构建于 `ctx.web` 之上 |
+| `@deepseek-ai/dsh-web`（本包） | Service Definition：服务、提供方注册表、选择策略、请求／结果词汇、`WebError` 分类体系 |
+| `@deepseek-ai/dsh-web-search-exa` | 搜索提供方：Exa |
+| `@deepseek-ai/dsh-web-search-perplexity` | 搜索提供方：Perplexity |
+| `@deepseek-ai/dsh-web-fetch-local` | 抓取提供方：匿名公共 HTTP(S) |
+| `@deepseek-ai/dsh-tool-web` | Consumer：面向模型的 `web_search`／`web_fetch` 工具 schema，构建于 `ctx.web` 之上 |
 
 搜索与抓取没有共享请求 schema 或业务逻辑，但有意共用一个 seam：`ctx.web` 是单一 web 访问中间层，拥有一项提供方选择策略、一套中止／错误词汇和一个面向产品的「该 harness 如何访问 web」配置接口。代价是成对的并行 `Search`／`Fetch` 方法；这种并行是有意设计，并非遗漏了可抽取的共性。
 
@@ -58,4 +58,4 @@
 - **没有观测接口**：没有提供方变更事件或能力状态查询；可用性只能通过执行 `search()`／`fetch()` 并按抛出的 `WebError` code 路由来观测，无提供方失败是通用的 `WEB_PROVIDER_UNAVAILABLE`，不会枚举逐提供方原因（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md)）。
 - **`WebSearchRequest` 只携带 `query` + `maxResults`**：提供方无关的控制项（新近程度、域名过滤条件、区域提示、搜索深度）暂缓至 Exa 与 Perplexity 都能诚实支持时（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
 - **`WebFetchBody` 没有 `pdf` 分支**：可提取文本的 PDF 支持属于明确的暂缓工作；封闭联合会使新增该分支成为三个 web 包中由编译强制执行的变更。
-- **提供方支持的页面提取不属于 `fetch()` 范围**：Firecrawl/Tavily 风格的 `web_extract` 能力暂缓，而不会扩展抓取 seam。
+- **提供方支持的页面提取不属于 `fetch()` 范围**：Firecrawl/Tavily 风格的 `web_extract` 能力暂缓，而不会扩展抓取操作。
diff --git a/packages/web/web/src/index.ts b/packages/web/web/src/index.ts
index 38e1478c3c..59da2e33e0 100644
--- a/packages/web/web/src/index.ts
+++ b/packages/web/web/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The web access seam (`ctx.web`): registries and provider-selecting execution for search and
+ * Service Definition for the web access capability seam (`ctx.web`): registries and provider-selecting execution for search and
  * fetch. Duplicate ids are rejected. At execution time, a configured provider must exist and
  * be usable; without one, exactly one usable provider is required, so selection never depends
  * on registration order.
diff --git a/packages/workflow/tool-ralph/src/index.ts b/packages/workflow/tool-ralph/src/index.ts
index 199d198262..e6e7edfccf 100644
--- a/packages/workflow/tool-ralph/src/index.ts
+++ b/packages/workflow/tool-ralph/src/index.ts
@@ -243,7 +243,7 @@ function normalizedList(value: unknown): value is string[] {
   return Array.isArray(value) && value.every(normalizedText)
 }
 
-/** Defensively decode the fixed script's report across an implementation seam. */
+/** Defensively decode the fixed script's report across a provider boundary. */
 function readReport(value: unknown, expectedStatus: RalphRoundStatus, maxChars: number): RalphRoundReport {
   if (!isRecord(value)
     || Object.keys(value).sort().join(',') !== 'blocker,evidence,nextSteps,status,summary'
diff --git a/packages/workflow/workflow-workerthread/src/runtime.ts b/packages/workflow/workflow-workerthread/src/runtime.ts
index 38194f4c03..6bc749cbd9 100644
--- a/packages/workflow/workflow-workerthread/src/runtime.ts
+++ b/packages/workflow/workflow-workerthread/src/runtime.ts
@@ -180,7 +180,7 @@ export class WorkflowExecution {
         return { value: null, stopReason: 'cancelled', error: this.cancelledError().message, agentsStarted: this.started }
       }
       // renderThrown is total (thrown values of any realm), so this arm
-      // cannot throw — drive() resolving is the `result` never-rejects seam
+      // cannot throw — drive() resolving is the `result` never-rejects contract
       // contract.
       return { value: null, stopReason: 'error', error: renderThrown(error), agentsStarted: this.started }
     }
@@ -283,7 +283,7 @@ export class WorkflowExecution {
       } catch (error: unknown) {
         // The host refuses starts once the run is cancelled — a refusal that
         // races our own cancel state must read as the cancellation it is,
-        // not as a broken seam.
+        // not as a broken contract.
         if (this.isCancelled()) throw this.cancelledError()
         throw new WorkflowError(`agent() could not start a child: ${renderThrown(error)}`, 'AGENT_START', { cause: error })
       }
diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts
index bf86ef5cce..794e5023ef 100644
--- a/packages/workflow/workflow/src/index.ts
+++ b/packages/workflow/workflow/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Workflow capability seam. Implementations execute orchestration scripts;
+ * Service Definition for the workflow capability seam. Service providers execute orchestration scripts;
  * observe-only lifecycle events never expose run control.
  * @module @deepseek-ai/dsh-workflow
  */
@@ -150,7 +150,7 @@ export function isFatalWorkflowError(error: unknown): boolean {
 }
 
 /**
- * Workflow execution seam. Invalid requests throw before publication; a live
+ * Workflow Service Definition contract. Invalid requests throw before publication; a live
  * run is holder-owned, its result never rejects, cancellation and disposal are
  * bounded, and disposal waits for child cleanup within that bound. Lifecycle
  * listener failures are contained, and `workflow/end` fires exactly once as the
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 38cc7950ec..1324d44969 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -4,7 +4,7 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-package seam\" → \"由三个包构成的 seam\", not \"三包 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 一个可替换能力的三包整体（Service Definition / Service provider 实现 / Consumer），以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface，且不能单独称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库接口、实现与消费方分离的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it improves clarity without changing or inventing the actor. Retain passive voice when the actor is unknown, irrelevant, or intentionally omitted.\n- Restructure source-language syntax into clear target-language syntax. Preserve the logical scope of conditions, concessions, negation, coordination, and modifiers.\n- Split or combine clauses when needed for readability, provided every source relationship remains explicit.\n- Translate meaning, not words. Do not invent words or expressions that a native technical author would not use.\n\n### Word Choice\n- Prefer precise, formal vocabulary over casual or colloquial alternatives.\n- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.\n- Translate ordinary prose when an established target-language expression is clear. Preserve proper nouns, canonical product names, code identifiers, APIs, paths, package names, and terms that the terminology table requires to remain in the source language.\n- Use context to resolve polysemous words. A familiar word does not have one fixed rendering in every technical domain.\n- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.\n- Do not use the same word to translate distinct source-language concepts when their distinction matters.\n- Avoid repeating the same ordinary verb in close proximity when a natural equivalent preserves the exact meaning. Never vary a terminology-table form, defined concept, or contract verb merely for stylistic variety.\n\n#### When translating into Chinese\n- When a number modifies a noun, include a natural Chinese classifier or measure word when Chinese grammar requires one. For example: \"three-role capability seam\" → \"包含三种角色的能力 seam\", not \"三角色 seam\". Do not add classifiers to code, identifiers, versions, units, or fixed names.\n\n### Punctuation\n\n#### When translating into Chinese\n- Use full-width Chinese punctuation in Chinese prose: `，。：；？！（）「」`. Keep half-width punctuation inside code spans, numbers, and complete verbatim English text.\n- Prefer colons, periods, commas, or parentheses over em dashes when they make the sentence clearer or more natural. Keep an em dash when it is the clearest natural punctuation.\n- Use enumeration commas (、) between parallel Chinese items, not regular commas.\n- Keep list-item endings consistent with their grammar. Complete sentences may end with periods or other grammatically required punctuation; do not end list items with commas.\n- Put one half-width space between Chinese text and Latin words or numerals. Do not add a space next to full-width punctuation, and do not leave a meaningless half-width space between two Chinese characters.\n- Markdown emphasis markers do not create a word boundary. Determine spacing from the rendered adjacent characters: Chinese next to Chinese takes no space, while Chinese next to a Latin word or numeral takes one half-width space.\n- Use half-width digits and Latin letters, never full-width forms.\n- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), translate to the corresponding Chinese term (必须、禁止、应当、可以), preserve the SOURCE emphasis span exactly, and do not weaken its normative strength: plain source stays plain (必须), italic source stays italic (*必须*), and bold source stays bold (**必须**).\n\n#### When translating into English\n- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.\n- Convert enumeration commas (、) to English commas and Chinese prose quotation marks to English double quotes.\n- Convert Chinese topic-comment sentences and omitted-subject constructions into clear English subjects when the actor is stated or unambiguously implied. Do not invent an actor.\n- Use concise professional developer prose and established English technical terms. Do not transliterate Chinese engineering idioms literally.\n- Use the terminology table's English column exactly and do not carry Chinese first-occurrence glosses into English prose.\n\n## Terminology\n\nA terminology table is provided below. Follow it strictly:\n- Render every listed term exactly as specified.\n- When the target language is Chinese, use the \"中文\" column. On the document's first prose occurrence, write the \"首次出现\" value when one is specified; on later occurrences, write only the part before the parenthetical gloss.\n- When the target language is English, use the \"English\" column without a Chinese gloss; do not copy the \"中文\" or \"首次出现\" value into English prose.\n- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.\n- NEVER use translations listed in the \"不要译作\" column.\n- Code spans and other protected tokens remain verbatim even when their text resembles a listed term.\n- For an unlisted technical term, use an established target-language technical term when its meaning is unambiguous in context. For a Chinese target, use an established Chinese rendering from a major Chinese-language OSS or vendor source; if you cannot reliably determine such a rendering, preserve the source term and record `[Terminology: pending]` in `<review>` with a tentative rendering for human review. For an English target, use the established English technical term; if the source term has no unambiguous established equivalent, preserve it with the shortest English gloss needed to make it intelligible and record `[Terminology: pending]` in `<review>`. A tentative rendering may appear in `<review>` but must not be silently adopted in `<translation>` or `<final>`, and you must not invent or claim a specific external precedent. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.\n\n# Terminology\n\n本表约定本仓库的中英术语统一译法。\n\n**通用规则：**\n- \"中文\"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。\n- 首次出现按\"首次出现\"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。\n- \"不要译作\"列为严格禁止的译法。\n- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。\n\n## 缩写类（中英文文本中均使用缩写）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| ACP | ACP | ACP（Agent Client Protocol） | | |\n| AI | AI | AI（人工智能） | | |\n| API | API | | | |\n| CI | CI | | | |\n| CLI | CLI | CLI（命令行界面） | | |\n| e2e | e2e | | | |\n| HMR | HMR | HMR（热模块替换） | | |\n| JSON Schema | JSON Schema | | | |\n| JSONL | JSONL | | | |\n| LLM | LLM | LLM（大语言模型） | | |\n| MCP | MCP | | | |\n| PR | PR | PR（Pull Request） | | |\n| RAG | RAG | RAG（检索增强生成） | | |\n| SDK | SDK | | | |\n| SSE | SSE | SSE（Server-Sent Events） | | |\n\n## 英文类（中英文文本中均使用英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| agent | agent | agent（智能体） | | |\n| Agent Note | Agent Note | | 智能体注记、智能体笔记 | 仓库定义的文档类型，涵盖提案、已实现决策和被否决提案；中文对侧 H1 保持固定前缀 `# Agent Note: `，标题中不加术语括注 |\n| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |\n| agent loop | agent loop | agent loop（智能体循环） | | |\n| blob hash | blob hash | | | `git hash-object` 的结果 |\n| Cordis | Cordis | | | |\n| dispose | dispose | dispose（资源释放） | | |\n| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |\n| fiber | fiber | | | |\n| fixture | fixture | fixture（测试前置数据） | | |\n| fork | fork | | | |\n| Function Calling | Function Calling | Function Calling（函数调用） | | |\n| harness | harness | | | |\n| harness engineering | harness engineering | | | |\n| KV Cache | KV Cache | | | 专有技术名称，保持大小写与空格 |\n| lint | lint | | | |\n| mock | mock | | | 保留英文；指测试替身 |\n| loader | loader | | | |\n| manifest | manifest | manifest（元数据清单） | | |\n| monorepo | monorepo | | | |\n| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |\n| schema | schema | | | |\n| schema DSL | schema DSL | | | |\n| seam | seam | | 接缝 | 一个可替换能力的整体，包含 Service Definition / Service provider / Consumer 三种角色；角色需要独立演化时才拆包，也可由同一包承担多个角色。以 `packages/bash` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| task id | task id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| waterfall | waterfall | waterfall（瀑布式事件） | | |\n| wheel | wheel 包 | | | Python 打包格式 |\n| worktree | worktree | | | git 工作区概念 |\n| Zstandard | Zstandard | | | RFC 8878 compression format; `zstd` remains a code value. |\n\n## 双语类（中英文文本各自使用中英文）\n\n| English | 中文 | 首次出现 | 不要译作 | 备注 |\n|---|---|---|---|---|\n| adapter | 适配器 | | | |\n| adapter contract | 适配器约定 | 适配器约定（adapter contract） | | |\n| append-only | 仅追加 | | | |\n| artifact | 产物 | | 制品 | |\n| backend | 后端 | | | |\n| background task | 后台任务 | | | |\n| block | 块 | | | |\n| build target | 构建目标 | | | |\n| cancel | 取消 | | | |\n| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |\n| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |\n| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库 Service Definition、Service provider 与 Consumer 三种角色组成完整可替换能力的命名架构概念；普通 `seam` 仍按其词条处理 |\n| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |\n| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |\n| checkpoint | 检查点 | | | |\n| chunk | 分片 | | | |\n| compaction | 压缩 | 压缩（compaction） | | |\n| companion tool | 配套工具 | | | |\n| composition bundle | 组合包 | | | 只约束应用或插件的组合语境，不约束所有 `bundle` |\n| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |\n| config key | 配置键 | | | Cordis 插件配置中的单个字段 |\n| consumer | 消费方 | | 消费者 | |\n| content block | 内容块 | | | |\n| Cookbook | 实操手册 | | | 文档标题用语 |\n| context | 上下文 | | | |\n| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指\"另一侧\"时可写「另一侧」 |\n| configurable-provider directory | 可配置提供方目录 | | | llm seam 中 `registerConfigurableProviders()` 维护的目录；沿用 Service Catalog →「服务目录」先例 |\n| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |\n| contract | 约定 | | | 如：`pairing contract` →`配对约定` |\n| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |\n| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |\n| crash recovery | 崩溃恢复 | | | |\n| deploy root | 部署根目录 | | | |\n| dormant | 休眠 | | 睡眠、蛰伏 | 指已声明可配置但当前未注册路由的提供方 |\n| durability | 持久性 | | | |\n| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |\n| event | 事件 | | | |\n| event log | 事件日志 | | | |\n| event stream | 事件流 | | | |\n| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |\n| Executive summary | 摘要 | | | 事故复盘标题用语 |\n| executor | 执行器 | | | |\n| expected output | 预期输出 | | 金标 | 指 snapshot 比较产物；翻译语料的人工校准样例不在此列 |\n| extension | 扩展 | | | |\n| extension point | 扩展点 | | | 注意与 `seam` 区分 |\n| fail-fast | 快速失败 | | | |\n| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |\n| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |\n| finish reason | 结束原因 | | | |\n| fold | 折叠区 | | | 配置界面语境：默认收起的字段分区（collapsed →「收起」）|\n| foreground run | 前台运行 | | | |\n| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |\n| hook | 钩子 | | | |\n| implementation | 实现 | | | |\n| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |\n| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |\n| injection | 注入 | | | |\n| integration | 集成 | | | |\n| interface | 接口 | | | |\n| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |\n| merge | 合并 | | | |\n| message | 消息 | | | |\n| mod | 模组 | | | |\n| model provider | 模型提供方 | | | |\n| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |\n| module | 模块 | | | |\n| non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |\n| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |\n| opt-out ratio | opt-out 比例 | | 退出检查比例 | |\n| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |\n| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |\n| package | 包 | | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |\n| pairing | 配对 | | | |\n| parent-subset grants | 父级子集授权 | | 父集合授权 | 指授权范围仅限于父级所持授权的子集 |\n| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |\n| permission | 权限 | | | |\n| persistence | 持久化 | | | |\n| pipeline | 流水线 | | | |\n| plugin | 插件 | | | |\n| postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |\n| prompt | 提示词 | | | |\n| provider | 提供方 | | | |\n| provider-neutral | 提供方无关 | | 提供方中立 | |\n| quality gate | 质量门禁 | | | |\n| quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |\n| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |\n| reasoning_content | 思考内容 | | | |\n| registry | 注册表 | | | |\n| replay | 回放 | | | |\n| resume | 恢复 | | | |\n| runtime | 运行时 | | | |\n| same-world subprocess | 与宿主共享文件系统和内核的子进程 | | 同世界子进程 | |\n| sandbox | 沙箱 | | | |\n| service | 服务 | | | |\n| serving surface | 对外服务接口 | | | |\n| session | 会话 | | | |\n| session event | 会话事件 | | | |\n| setup card | 设置卡片 | | | 首次运行时代替行卡直接展开的配置卡 |\n| sidecar file | 伴随文件 | | | 指与文档同目录的普通伴随文件 |\n| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |\n| smoke test | 冒烟测试 | | | |\n| snapshot | 快照 | | | |\n| source of truth | 真源 | | 事实来源、唯一来源 | |\n| spine | 主干 | | | |\n| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |\n| step | 步骤 | | | |\n| stream | 流 | | | |\n| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |\n| Summary | 概述 | | | 事故复盘标题用语 |\n| system prompt | 系统提示词 | | | |\n| taxonomy | 分类体系 | | | |\n| token usage | token 用量 | | | |\n| tool | 工具 | | | |\n| tool call | 工具调用 | | | |\n| tool result | 工具结果 | | | |\n| tool schema | 工具 schema | | | |\n| toolkit | 工具包 | | | |\n| turn | 轮次 | | | |\n| VFS | VFS | 虚拟文件系统（VFS） | | |\n| typecheck | 类型检查 | | | |\n| vocabulary | 词汇 | | | |\n| wire format | 协议格式 | 协议格式（wire format） | | |\n| workflow | 工作流 | | | |\n| wrapper | 包装层 | | | 软件层或 SDK 包装层 |\n| wrapper script | 包装脚本 | | | 可执行脚本包装层 |\n\n\n## Output Format\n\nReturn exactly three raw XML sections in the order shown below. Do not wrap the response in a Markdown code fence and do not add analysis or text before, between, or after the sections. The fence below only displays the required shape; do not reproduce the fence.\n\nThe outer section tags are framing. If Markdown inside any section body contains a line consisting only of `<translation>`, `</translation>`, `<review>`, `</review>`, `<final>`, or `</final>`, prefix that line with `\\`. If the original line already has one or more backslashes immediately before the tag, add one more. The parser removes exactly one framing escape; tags mentioned inline need no escaping.\n\n```xml\n<translation>\n(First pass: the complete translation, written as natural target-language technical prose)\n</translation>\n\n<review>\n(Second pass: actual corrections only, one correction per line with a category tag, e.g.)\n- [Tone] \"旁挂记录\" → \"伴随记录\"（生造词）\n- [Sentence] 第 3 段补充逗号断句\n- [Punctuation] 两处破折号替换为冒号\n- [Terminology: pending] source term → tentative rendering\n- 无修正\n</review>\n\n<final>\n(Complete final translation after corrections)\n</final>\n```\n\n## Self-Review Instructions\n\nAfter writing `<translation>`, verify it in two directions. First re-read it in the target language only, without looking at the source; awkward phrasing is easier to notice without source-language anchoring. Then compare it against the source clause by clause for completeness and exact meaning. Resolve doubts before writing `<review>`; do not include reasoning transcripts, checks that passed, tentative suggestions, retractions, or no-op corrections.\n\n**Structure**\n- Is the heading hierarchy and order, list shape and count, ordered-list start, table shape, and code block content identical to the source?\n- Are ALL comments and info strings inside code blocks left untranslated and byte-identical to the source?\n- Are inline code spans and machine-readable tokens verbatim?\n- Is an existing language switcher correctly flipped, and is no switcher or filename invented when the source lacks one?\n- Are link targets and emphasis spans preserved?\n- Does spacing across emphasis boundaries follow the same Chinese/Latin/numeral rule as ordinary prose?\n- Are wrapper-tag lines inside section bodies escaped with one additional backslash?\n\n**Faithfulness**\n- Clause by clause, is anything added, dropped, weakened, strengthened, reversed, merged, or re-bounded? Are list item counts identical on both sides?\n- Do actors, objects, conditions, exceptions, negation, modality, causal relationships, guarantees, contract directions, result channels, ownership changes, and quantities survive exactly?\n\n**Tone & Style**\n- Does every sentence read as if originally written by a native technical author?\n- Is there any colloquial, casual, overly informal, promotional, or transplanted metaphorical phrasing?\n- Are actors explicit where the target language needs them, without inventing responsibility?\n\n**Sentence Structure**\n- Are there run-on sentences that need breaking?\n- Are there stiff passive constructions that can safely become active, or active constructions that invent an actor?\n- Are conditions, concessions, negation, coordination, and modifiers scoped clearly?\n\n**Word Choice**\n- Are there overly literal translations that sound unnatural?\n- Are ordinary prose words left untranslated despite an established target-language expression?\n- Does each polysemous word fit its local context?\n- Is the same target-language word used for distinct source concepts, or is a defined term varied merely to avoid repetition?\n- Is any slang or internal jargon present?\n\n**Terminology**\n- For a Chinese target, are first-occurrence glosses correctly applied to the true first prose occurrence, neither missing nor repeated? For an English target, are Chinese glosses absent?\n- Are any \"不要译作\" forbidden translations present?\n- Do protected tokens remain untouched even when they resemble terminology entries?\n- For an unlisted term, does a Chinese target use an established Chinese rendering or preserve the source term as pending when no reliable rendering is known, and does an English target use the established English technical term or preserve only an ambiguous source term with the shortest necessary gloss and a pending notice?\n\n**Punctuation** (when target is Chinese)\n- Are punctuation, mixed-script spacing, quotation marks, Latin letters, and digits in their required forms?\n- Are there em dashes that make the sentence less clear and should be replaced, while natural em dashes remain intact?\n- Are list-item endings grammatically consistent, with none ending in commas?\n- Do RFC 2119 keywords preserve the source emphasis span and normative strength exactly?\n\nRecord actual corrections in `<review>`, then output the corrected complete document in `<final>`. If no correction or pending terminology notice is needed, write exactly `- 无修正` in `<review>` and copy `<translation>` unchanged into `<final>`. If `<review>` contains only pending terminology notices, copy `<translation>` unchanged into `<final>`.\n\n## Examples\n\nBelow are representative examples of common problems and their corrections. Follow the \"Good\" versions within the rule each example illustrates; examples do not override source context or higher-priority requirements.\n\n### Colloquial verb → Professional verb\n- Source: `The repo pins pnpm@11.7.0 in package.json`\n- Bad: `仓库在 package.json 中钉住 pnpm@11.7.0`\n- Good: `该仓库在 package.json 中固定使用 pnpm@11.7.0`\n\n### Run-on sentence → Natural phrasing with pause\n- Source: `Read docs/architecture.md before changing anything under packages/.`\n- Bad: `改动 packages/ 下的任何东西之前先读 docs/architecture.md。`\n- Good: `在修改 packages/ 目录下的任何内容之前，请先阅读 docs/architecture.md。`\n\n### Stiff passive voice → Active and natural\n- Source: `a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.`\n- Bad: `门禁绿意味着这对文档曾在当前内容上被确认一致，不意味着这次确认本身是对的。`\n- Good: `门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。`\n\n### Invented word → Natural expression\n- Source: `A sidecar record of both blob hashes makes consistency checkable`\n- Bad: `旁挂记录两侧 blob hash，使一致性可检查`\n- Good: `伴随记录保存两侧 blob hash，使一致性可检查`\n\n### Em-dash → Colon/period\n- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`\n- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`\n- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`\n\n### Overly literal → Meaningful rendering\n- Source: `awkward phrasing is easier to hear without the source anchoring you`\n- Bad: `没有源文锚着，别扭的表述更容易被听出来`\n- Good: `不对照原文时，更容易察觉别扭的表达`\n\n### Terminology — do not translate what should be kept in English\n- Source: `typed service seams, and explicit extension points`\n- Bad: `类型化的服务 seam（扩展点）与显式扩展点`\n- Good: `类型化的服务 seam 与显式扩展点`\n\n### Slang/jargon → Professional phrasing\n- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`\n- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`\n- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`\n\n### \"For humans\" — translate the intent, not the word\n- Source: `For humans, start with the development guide`\n- Bad: `对于人工读者，请先从开发指南开始`（\"人工读者\"生硬）\n- Good: `面向开发者：请先阅读开发指南`（\"开发者\"自然，且中文里冒号在此处更自然）\n\n### Code block comments — NEVER translate\n- Source code block contains: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)`\n- Bad: `# 全屏 TUI coding agent（需要 DEEPSEEK_API_KEY）`\n- Good: `# full-screen TUI coding agent (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)\n\n### Language switcher — flip direction\n- Source file (English) has: `English | [中文](README.zh.md)`\n- Bad (copying source unchanged): `English | [中文](README.zh.md)`\n- Good (flipped for Chinese file): `[English](README.md) | 中文`\n\n---\n\nNow translate the following document:"
       },
       {
         "role": "user",
diff --git a/vitest.config.ts b/vitest.config.ts
index 4456782519..e07ae43ec3 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -24,7 +24,7 @@ const windowsUnsupportedPackages = process.platform === 'win32'
       // The pwsh-requiring suites (pwsh-local, tool-pwsh) deliberately stay
       // INCLUDED: PowerShell ships with Windows, so they run natively here.
       // Replacing the old 'packages/bash/*' glob with this explicit list also
-      // newly INCLUDES packages/bash/bash (the pure seam package) on Windows.
+      // newly INCLUDES packages/bash/bash (the Service Definition package) on Windows.
       'packages/bash/bash-local',
       'packages/bash/bash-sandbox',
       'packages/bash/tool-bash',

From ceba53edd75570b7f8854852d35563bd97d07eb2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:22:50 +0800
Subject: [PATCH 479/516] fix(fs): observe absence before guarded recreation

---
 ...06-26-file-context-as-event-gate.i18n.yaml |  4 +-
 .../2026-06-26-file-context-as-event-gate.md  | 36 +++++-----
 ...026-06-26-file-context-as-event-gate.zh.md | 36 +++++-----
 ...9-filesystem-absence-observation.i18n.yaml |  6 ++
 ...26-08-09-filesystem-absence-observation.md | 36 ++++++++++
 ...08-09-filesystem-absence-observation.zh.md | 36 ++++++++++
 .../2026-08-03-fs-tool-error-remedy.i18n.yaml |  4 +-
 .../2026-08-03-fs-tool-error-remedy.md        |  2 +-
 .../2026-08-03-fs-tool-error-remedy.zh.md     |  2 +-
 docs/config-catalog.i18n.yaml                 |  4 +-
 docs/config-catalog.md                        |  2 +-
 docs/config-catalog.zh.md                     |  2 +-
 docs/event-producer-consumer.i18n.yaml        |  4 +-
 docs/event-producer-consumer.md               |  6 +-
 docs/event-producer-consumer.zh.md            |  6 +-
 docs/subsystems/filesystem.i18n.yaml          |  4 +-
 docs/subsystems/filesystem.md                 | 50 ++++++++------
 docs/subsystems/filesystem.zh.md              | 50 ++++++++------
 docs/tool-catalog.i18n.yaml                   |  4 +-
 docs/tool-catalog.md                          |  4 +-
 docs/tool-catalog.zh.md                       |  4 +-
 examples/acp-agent/tests/acp.snapshot.ts      |  1 +
 .../snapshots/fs-delete-recreate/input.json   |  7 ++
 .../fs-delete-recreate/session.jsonl          | 62 +++++++++++++++++
 .../fs-delete-recreate/stdout.expected.jsonl  |  4 ++
 .../fs-delete-recreate/workspace/deleted.txt  |  1 +
 packages/e2b/fs-e2b/README.i18n.yaml          |  4 +-
 packages/e2b/fs-e2b/README.md                 |  6 +-
 packages/e2b/fs-e2b/README.zh.md              |  6 +-
 packages/e2b/fs-e2b/src/index.ts              | 34 +++++++++-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  | 67 +++++++++++++++++++
 packages/fs/fs-local/README.i18n.yaml         |  4 +-
 packages/fs/fs-local/README.md                |  4 +-
 packages/fs/fs-local/README.zh.md             |  4 +-
 packages/fs/fs-local/src/fsio.ts              | 31 +++++++--
 packages/fs/fs-local/src/index.ts             |  9 ++-
 packages/fs/fs-local/tests/filesystem.spec.ts | 10 +++
 packages/fs/fs-local/tests/fsio.spec.ts       | 11 +++
 packages/fs/fs-policy/README.i18n.yaml        |  4 +-
 packages/fs/fs-policy/README.md               | 12 ++--
 packages/fs/fs-policy/README.zh.md            | 12 ++--
 packages/fs/fs-policy/src/index.ts            | 56 +++++++++-------
 packages/fs/fs-policy/tests/policy.spec.ts    | 53 ++++++++++++---
 packages/fs/fs/README.i18n.yaml               |  4 +-
 packages/fs/fs/README.md                      |  6 +-
 packages/fs/fs/README.zh.md                   |  6 +-
 packages/fs/fs/src/index.ts                   | 17 +++--
 packages/fs/fs/src/invariant.ts               | 15 ++++-
 packages/fs/fs/src/types.ts                   |  9 +++
 packages/fs/fs/tests/invariant.spec.ts        | 21 ++++--
 packages/fs/tool-fs/README.i18n.yaml          |  4 +-
 packages/fs/tool-fs/README.md                 |  4 +-
 packages/fs/tool-fs/README.zh.md              |  4 +-
 packages/fs/tool-fs/src/edit.ts               |  4 +-
 packages/fs/tool-fs/src/read.ts               | 11 +--
 packages/fs/tool-fs/src/write.ts              |  4 +-
 packages/fs/tool-fs/tests/integration.spec.ts | 54 +++++++++------
 .../tool-str-replace-editor/README.i18n.yaml  |  4 +-
 packages/fs/tool-str-replace-editor/README.md |  2 +-
 .../fs/tool-str-replace-editor/README.zh.md   |  2 +-
 .../fs/tool-str-replace-editor/src/index.ts   |  9 +--
 .../tests/tools.spec.ts                       | 29 ++++++++
 .../tool-cordis/src/api-catalog.ts            | 10 +--
 packages/skill/skill-local/src/index.ts       |  2 +-
 .../skill-local/tests/skill-local.spec.ts     |  8 +--
 scripts/gen-cordis-catalog.ts                 |  1 +
 scripts/gen-tool-catalog.ts                   |  4 +-
 scripts/type-equiv.manifest.json              |  5 ++
 68 files changed, 694 insertions(+), 249 deletions(-)
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
 create mode 100644 .agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
 create mode 100644 examples/acp-agent/tests/snapshots/fs-delete-recreate/input.json
 create mode 100644 examples/acp-agent/tests/snapshots/fs-delete-recreate/session.jsonl
 create mode 100644 examples/acp-agent/tests/snapshots/fs-delete-recreate/stdout.expected.jsonl
 create mode 100644 examples/acp-agent/tests/snapshots/fs-delete-recreate/workspace/deleted.txt

diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
index ffa6f48889..a8acbaf10e 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.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 .agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
-2026-06-26-file-context-as-event-gate.md: df1a43e252cff02b287497210664c3d14dcd35a9
-2026-06-26-file-context-as-event-gate.zh.md: 3d784c9e150430c8054f6b08ccc5c66fa85e09b4
+2026-06-26-file-context-as-event-gate.md: 353beb2498a310eee8cc794fa5edc22915fd6ad0
+2026-06-26-file-context-as-event-gate.zh.md: 37d7c1e4d971896a0e6ddeb42650635b8f755ca0
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
index df1a43e252..353beb2498 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
@@ -33,14 +33,16 @@ provider      dsh-fs-local      local implementation of ctx.fs
 
 The model is additive: bare `ctx.fs` performs atomic, unconstrained text I/O, while `dsh-fs-policy` adds observed state, read-before-edit, and version guards. Removing the policy therefore leaves the tools usable but unconstrained. Shipped agent configs load the policy; the bare mode exists to keep policy optional at the service boundary, not as the normal deployment stance.
 
+The [filesystem absence-observation follow-up](../bug-fix/2026-08-09-filesystem-absence-observation.md) refines the recording payload from a success-only version to explicit present/absent state and requires guarded creation to publish without replacement. The event-gate ownership and no-I/O policy boundary remain unchanged.
+
 `dsh-tool-fs` no longer injects `fileContext`. It injects `fs` and `tools`/`systemPrompt`.
 
 ## The policy is enforced by provider CAS, not by `dsh-fs-policy` stat
 
 `dsh-fs-policy` enforces "you must write/edit based on the version you read" **without ever calling `stat` or comparing versions itself**. It supplies the observed version as the CAS basis and lets the provider's mutation critical section detect staleness:
 
-- "Have you read this file?" is the one thing `dsh-fs-policy` decides locally — a `WeakMap` lookup, no I/O. No record ⇒ `FS_NOT_OBSERVED`.
-- "Is the version you read still current?" is decided **inside `ctx.fs.editText`/`writeText`**, in the same atomic lock that performs the read-match-rename. `dsh-fs-policy` passes `vObserved` as the expectation; the provider raises `FS_STALE_VERSION` if the file has moved on.
+- "What did this owner last observe?" is the one thing `dsh-fs-policy` decides locally — a `WeakMap` lookup, no I/O. No record means unseen; an absent record permits only guarded creation; a present record carries the replacement/edit basis.
+- "Is the version still current, or is the create target still absent?" is decided **inside the provider's atomic mutation boundary**. `dsh-fs-policy` supplies `replaceIfVersion` or `createIfAbsent`; the provider raises `FS_STALE_VERSION` for a moved version and `FS_NOT_OBSERVED` when a guarded create loses to another creator.
 
 This is deliberate. If `dsh-fs-policy` stat-ed and compared versions in its waterfall handler, there would be a TOCTOU gap between that check and the tool's actual write — the file could change in between, so the check would be a false guarantee that the provider's lock has to back up anyway. Putting the version check in the provider's critical section is both race-free and zero extra `stat`. So `dsh-fs-policy` does **no** filesystem I/O; the "must be based on the latest read" guarantee is *realized* by CAS, and `dsh-fs-policy` only chooses the basis (`vObserved`) and gates on prior observation.
 
@@ -68,14 +70,14 @@ The `FsWriteIntent` union itself does not change — the third "unconditional" s
 
 The events live in `@deepseek-ai/dsh-fs`, not in `dsh-fs-policy`. This is forced by the decoupling contract: `dsh-tool-fs` is the emitter, so it must reference the event types, and it must keep compiling even though `dsh-fs-policy` no longer provides a method service. `dsh-fs` is the package both `dsh-tool-fs` and `dsh-fs-policy` already depend on, so it is the only home that lets the emitter and the policy listener share a vocabulary without the emitter depending on the policy plugin.
 
-These events carry existing `dsh-fs` vocabulary (`FsTarget`, `FsVersion`, `FsWriteIntent`) plus an opaque actor — not model-facing concepts (no line windows, numbered lines, or rendered footers leak down).
+These events carry existing `dsh-fs` vocabulary (`FsTarget`, `FsVersion`, `FsObservation`, `FsWriteIntent`) plus an opaque actor — not model-facing concepts (no line windows, numbered lines, or rendered footers leak down).
 
 **The two `fs/*` decision events are single-slot, first-wins waterfalls.** `dsh-fs-policy` returns without calling `next()`, so it owns the slot in the default deployment; a listener registered earlier or with `prepend` would replace that policy. Permission, audit, and sandbox concerns remain on the composable `tools/execute` waterfall.
 
 The actor is typed `object` in `dsh-fs` — a pure opaque carrier the provider contract never reads or narrows. The owner-derivation (`actor.agent?.session`) and the `{ agent?: { session? } }` structural shape stay entirely inside `dsh-fs-policy`, which narrows the `object` actor to that shape in its listeners. `dsh-fs` owns the event names and the fs vocabulary; it does NOT own the policy layer's runtime owner structure.
 
 ```ts
-import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
+import type { FsObservation, FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
 
 interface Events {
   /**
@@ -95,14 +97,14 @@ interface Events {
    */
   'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
   /**
-   * Record that an actor observed a target at a version, after a successful
-   * read/write/edit. Fire-and-forget (plain emit). Listeners MUST be
+   * Record that an actor observed a target as present at a version or absent.
+   * Fire-and-forget (plain emit). Listeners MUST be
    * synchronous, side-effect-only recorders (`dsh-fs-policy`'s is a WeakMap
    * write); the tool does not guard the emit, so a throwing listener surfaces as
    * the tool's isError result. No listener ⇒ nothing recorded.
    * @mode emit
    */
-  'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+  'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
 }
 ```
 
@@ -118,23 +120,23 @@ The tool keeps its model-facing schemas (`read`/`write`/`edit`, byte-for-byte un
 
 `stat` budget is minimized by letting the waterfall produce the expectation lazily — the bare default returns `undefined` (no guard) and never stats:
 
-- **read** — one `stat` (type + size routing + version), then `readText`/`streamText`, then `buildWindow`, then an `emit('fs/observed', target, info.version, exec)`. The post-read confirming `stat` from the old `fileContext.read` is dropped; a writer racing between the routing stat and the read can at worst make a *later* guarded edit spuriously `FS_STALE_VERSION` (fail-closed: the model re-reads, never writes against the wrong version, since `editText` re-checks in its lock).
-- **write** — `expectation = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)`, then `ctx.fs.writeText(target, content, expectation)`, then an `emit('fs/observed', target, outcome.version, exec)`. **Zero stat in the tool** with or without `dsh-fs-policy`.
-- **edit** — `expectation = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)`, then `ctx.fs.editText(target, edit, expectation)`, then an `emit('fs/observed', target, outcome.version, exec)`. **Zero stat in the tool** in both cases: the bare default is `undefined` (unconditional edit), so the tool never stats to manufacture a basis. If the target is absent, the provider reports `FS_STALE_VERSION` even on the unguarded path.
+- **read** — one `stat`; a metadata miss emits `{ kind: 'absent' }` before returning `FS_NOT_FOUND`, while a file routes through `readText`/`streamText`, `buildWindow`, then emits `{ kind: 'present', version: info.version }`. The post-read confirming `stat` from the old `fileContext.read` stays dropped; a writer racing between the routing stat and the read can at worst make a later guarded edit spuriously stale.
+- **write** — `expectation = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)`, then `ctx.fs.writeText(target, content, expectation)`, then emit the present outcome version. **Zero stat in the tool** with or without `dsh-fs-policy`.
+- **edit** — `expectation = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)`, then `ctx.fs.editText(target, edit, expectation)`, then emit the present outcome version. **Zero stat in the tool** in both cases: the bare default is `undefined` (unconditional edit), so the tool never stats to manufacture a basis. If the target is absent on the bare path, the provider reports `FS_STALE_VERSION`; the policy returns `FS_NOT_FOUND` directly when it already holds an absent observation.
 
 The tool passes `exec` (the tool-execution context) as the `actor` argument on every dispatch, so `dsh-fs-policy` can derive its observed-state owner. The tool does not know whether the policy plugin is present: it always provides the bare default behavior in the `next` thunk, and `dsh-fs-policy` short-circuits the thunk before it runs in the default deployment.
 
-**`fs/observed` fires after a successful operation.** Its listeners must be synchronous, non-throwing recorders; the tool does not guard the plain emit, so a throwing listener would report failure after a mutation already succeeded. Async or fallible observation needs a separate event contract.
+**`fs/observed` fires after a successful operation and after a metadata probe confirms absence.** Its listeners must be synchronous, non-throwing recorders; the tool does not guard the plain emit, so a throwing listener can replace the pending read error or report failure after a mutation already succeeded. Async or fallible observation needs a separate event contract.
 
 ## Policy plugin contract (`dsh-fs-policy`)
 
-`dsh-fs-policy` is a plugin, not a service. It does not register `ctx.fileContext`, has no public method surface, and exposes no `read`/`write`/`edit`/`resolve` methods. It attaches three listeners via `ctx.on()` registrations (each returning a disposer for HMR). It keeps the observed-state `WeakMap<owner, Map<targetKey, { version }>>` and the structural owner derivation (narrowing the event's opaque `object` actor to its own `{ agent?: { session? } }` shape), but does not inject `fs` — every handler operates only on its own `WeakMap`, never on `ctx.fs`.
+`dsh-fs-policy` is a plugin, not a service. It does not register `ctx.fileContext`, has no public method surface, and exposes no `read`/`write`/`edit`/`resolve` methods. It attaches three listeners via `ctx.on()` registrations (each returning a disposer for HMR). It keeps the observed-state `WeakMap<owner, Map<targetKey, FsObservation>>` and the structural owner derivation (narrowing the event's opaque `object` actor to its own `{ agent?: { session? } }` shape), but does not inject `fs` — every handler operates only on its own `WeakMap`, never on `ctx.fs`.
 
-- `fs/write-intent` listener: `prior = getObserved(owner, key)`; return `prior ? { kind: 'replaceIfVersion', version: prior.version } : { kind: 'createIfAbsent' }`. It does NOT call `next()`: it fully owns the single decision slot.
-- `fs/edit-intent` listener: `prior = getObserved(owner, key)`; if no `owner` or no `prior`, throw `FS_NOT_OBSERVED`; else return `{ version: prior.version }`. Also does not call `next()`.
-- `fs/observed` listener: `record(owner, key, version)`.
+- `fs/write-intent` listener: unseen/absent ⇒ `createIfAbsent`; present ⇒ `replaceIfVersion`. It does NOT call `next()`: it fully owns the single decision slot.
+- `fs/edit-intent` listener: unseen ⇒ `FS_NOT_OBSERVED`; absent ⇒ `FS_NOT_FOUND`; present ⇒ its version guard. It does NOT call `next()`.
+- `fs/observed` listener: record the present/absent discriminated value.
 
-An observed-state entry is the **prior-observation record**: a successful `read`, `write`, OR `edit` all emit `fs/observed` and record `{ version }`, so the entry's presence means "this owner has observed this target at this version", not narrowly "has read it". This is what lets a create-then-edit or edit-then-edit sequence work without an intervening re-read: the mutation refreshes the recorded version to its own result, so the next edit's basis is the version it just produced. `FS_NOT_OBSERVED` rejects only an edit with NO prior observation of any kind. The owner is derived structurally from `{ agent?: { session? } }`; disposal drops all state (HMR safety).
+An observed-state entry is the **prior-observation record**, but its discriminant matters. Successful read/write/edit records present at a version, allowing create-then-edit or edit-then-edit without an intervening read. A read/view that confirms absence replaces any old positive version with absent, allowing only a guarded create; a later successful create replaces it with the new present version. Missing entry alone means unseen and produces `FS_NOT_OBSERVED` for edit. The owner is derived structurally from `{ agent?: { session? } }`; disposal drops all state (HMR safety).
 
 `dsh-fs-policy` is now a pure policy/recording plugin with no service surface — it influences the world only through the event gate. That is what removes the method coupling from `dsh-tool-fs`.
 
@@ -154,7 +156,7 @@ This amends — does not reverse — [the split-fs-seam Agent Note](../simplific
 
 ## Verification
 
-Tests pin both paths: without `dsh-fs-policy`, the root tool plugin boots against `dsh-fs-local`, and read, create, overwrite, and unread edit succeed; with the policy, unread edit returns `FS_NOT_OBSERVED` and unread overwrite is gated by `createIfAbsent`. A later intent listener is not reached after the policy decides. Stale edits fail through provider CAS while the policy performs no `stat`; the tool budgets remain one `stat` for read and zero for write or edit on either path. Model-facing schemas remain byte-for-byte unchanged, so snapshots do not change.
+Tests pin both paths: without `dsh-fs-policy`, the root tool plugin boots against `dsh-fs-local`, and read, create, overwrite, and unread edit succeed; with the policy, unread edit returns `FS_NOT_OBSERVED` and unread overwrite is gated by `createIfAbsent`. A later intent listener is not reached after the policy decides. Stale edits fail through provider CAS while the policy performs no `stat`; the tool budgets remain one `stat` for read and zero for write or edit on either path. The deletion recovery path is also assembled: stale mutation, missing reread, guarded recreation. Model-facing schemas remain byte-for-byte unchanged, while the recovered result transcript changes.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
index 3d784c9e15..37d7c1e4d9 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
@@ -33,14 +33,16 @@ provider      dsh-fs-local      local implementation of ctx.fs
 
 该模型是叠加式的：裸 `ctx.fs` 执行原子化、无约束的文本 I/O，而 `dsh-fs-policy` 叠加观测状态、先读后编辑和版本守卫。因此移除策略层后工具仍可用，只是不受约束。正式发布的 agent 配置会加载策略；裸模式的存在是为了让策略在服务边界保持可选，而非作为正常部署姿态。
 
+[文件系统缺失观测后续决策](../bug-fix/2026-08-09-filesystem-absence-observation.md)把记录载荷从仅表示成功的版本细化为显式的存在/缺失状态，并要求带防护的创建以不替换方式发布。事件门禁归属与无 I/O 策略边界保持不变。
+
 `dsh-tool-fs` 不再注入 `fileContext`。它注入 `fs` 和 `tools`/`systemPrompt`。
 
 ## 策略由提供方 CAS 强制执行，而非 `dsh-fs-policy` 的 stat
 
 `dsh-fs-policy` 强制执行「你必须基于你读到的版本来写入/编辑」，**自身从不调用 `stat` 或比较版本**。它将观测到的版本作为 CAS 基准提供，让提供方的 mutation 临界区检测陈旧性：
 
-- 「你读过这个文件吗？」是 `dsh-fs-policy` 在本地决定的唯一事项——一次 `WeakMap` 查找，无 I/O。无记录 ⇒ `FS_NOT_OBSERVED`。
-- 「你读到的版本是否仍为最新？」由 **`ctx.fs.editText`/`writeText` 内部**决定，在执行 read-match-rename 的同一个原子锁中完成。`dsh-fs-policy` 将 `vObserved` 作为期望值传入；如果文件已变更，提供方抛出 `FS_STALE_VERSION`。
+- 「该所有者最近观测到了什么？」是 `dsh-fs-policy` 在本地决定的唯一事项——一次 `WeakMap` 查找，无 I/O。无记录表示未见；缺失记录只允许带防护的创建；存在记录携带替换/编辑基准。
+- 「版本是否仍然有效，或者创建目标是否仍然缺失？」由**提供方的原子变更边界内部**决定。`dsh-fs-policy` 提供 `replaceIfVersion` 或 `createIfAbsent`；对于已经变化的版本，提供方抛出 `FS_STALE_VERSION`；带防护的创建若败给另一个创建者，则抛出 `FS_NOT_OBSERVED`。
 
 这是有意为之的。如果 `dsh-fs-policy` 在其 waterfall（瀑布式事件）处理器中 stat 并比较版本，该检查与工具实际写入之间会存在 TOCTOU 间隙——文件可能在此期间变化，因此该检查只是一个虚假保证，提供方的锁无论如何都要兜底。将版本检查放在提供方的临界区中既无竞态又无额外 `stat`。所以 `dsh-fs-policy` **不做**任何文件系统 I/O；「必须基于最近一次读取」的保证由 CAS *实现*，`dsh-fs-policy` 只负责选择基准（`vObserved`）并对先前观测进行门控。
 
@@ -68,14 +70,14 @@ editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion
 
 事件定义在 `@deepseek-ai/dsh-fs` 中，而非 `dsh-fs-policy` 中。这是解耦约定所迫：`dsh-tool-fs` 是发射方，因此它必须引用事件类型，且即使 `dsh-fs-policy` 不再提供方法服务，它也必须能编译通过。`dsh-fs` 是 `dsh-tool-fs` 和 `dsh-fs-policy` 都已依赖的包，因此它是唯一能让发射方和策略监听方共享词汇而不让发射方依赖策略插件的归属地。
 
-这些事件携带既有的 `dsh-fs` 词汇（`FsTarget`、`FsVersion`、`FsWriteIntent`）加一个不透明的 actor——不携带面向模型的概念（行窗口、行号或渲染后的页脚不会泄漏到此层）。
+这些事件携带既有的 `dsh-fs` 词汇（`FsTarget`、`FsVersion`、`FsObservation`、`FsWriteIntent`）加一个不透明的 actor——不携带面向模型的概念（行窗口、行号或渲染后的页脚不会泄漏到此层）。
 
 **两个 `fs/*` 决策事件是单槽、先到先得的 waterfall。** `dsh-fs-policy` 不调用 `next()` 直接返回，因此在默认部署中它占据该槽位；更早注册或使用 `prepend` 的监听器会替代该策略。权限、审计和沙箱关注点仍留在可组合的 `tools/execute` waterfall 上。
 
 actor 在 `dsh-fs` 中类型为 `object`——一个纯粹的不透明载体，提供方约定从不读取或收窄它。owner 的推导（`actor.agent?.session`）和 `{ agent?: { session? } }` 结构形状完全留在 `dsh-fs-policy` 内部，由其在监听器中将 `object` actor 收窄为该形状。`dsh-fs` 拥有事件名和 fs 词汇；它不拥有策略层的运行时 owner 结构。
 
 ```ts
-import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
+import type { FsObservation, FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
 
 interface Events {
   /**
@@ -95,14 +97,14 @@ interface Events {
    */
   'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
   /**
-   * Record that an actor observed a target at a version, after a successful
-   * read/write/edit. Fire-and-forget (plain emit). Listeners MUST be
+   * Record that an actor observed a target as present at a version or absent.
+   * Fire-and-forget (plain emit). Listeners MUST be
    * synchronous, side-effect-only recorders (`dsh-fs-policy`'s is a WeakMap
    * write); the tool does not guard the emit, so a throwing listener surfaces as
    * the tool's isError result. No listener ⇒ nothing recorded.
    * @mode emit
    */
-  'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+  'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
 }
 ```
 
@@ -118,23 +120,23 @@ interface Events {
 
 通过让 waterfall 惰性产出期望值来最小化 `stat` 预算——裸默认返回 `undefined`（无守卫），从不 stat：
 
-- **read**——一次 `stat`（类型 + 大小路由 + 版本），然后 `readText`/`streamText`，然后 `buildWindow`，然后 `emit('fs/observed', target, info.version, exec)`。旧 `fileContext.read` 中读后确认的 `stat` 被移除；在路由 stat 和读取之间竞争的写入者最多只能使*后续*有守卫的编辑误报 `FS_STALE_VERSION`（为安全起见拒绝写入：模型会重新读取；由于 `editText` 会在其锁内复查，模型绝不会基于错误版本写入）。
-- **write**——`expectation = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)`，然后 `ctx.fs.writeText(target, content, expectation)`，然后 `emit('fs/observed', target, outcome.version, exec)`。无论是否有 `dsh-fs-policy`，**工具内零 stat**。
-- **edit**——`expectation = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)`，然后 `ctx.fs.editText(target, edit, expectation)`，然后 `emit('fs/observed', target, outcome.version, exec)`。两种情况下**工具内零 stat**：裸默认为 `undefined`（无条件编辑），因此工具从不 stat 来制造基准。如果目标不存在，提供方即使在无守卫路径上也报告 `FS_STALE_VERSION`。
+- **read**——一次 `stat`；元数据未命中时，在返回 `FS_NOT_FOUND` 前 emit `{ kind: 'absent' }`；目标为文件时，则依次执行 `readText`/`streamText`、`buildWindow`，再 emit `{ kind: 'present', version: info.version }`。旧 `fileContext.read` 中读后确认的 `stat` 仍保持移除；在路由 stat 和读取之间竞争的写入者最多只能使后续带防护的编辑误报陈旧。
+- **write**——`expectation = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)`，然后 `ctx.fs.writeText(target, content, expectation)`，再 emit 表示存在的结果版本。无论是否有 `dsh-fs-policy`，**工具内零 stat**。
+- **edit**——`expectation = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined)`，然后 `ctx.fs.editText(target, edit, expectation)`，再 emit 表示存在的结果版本。两种情况下**工具内零 stat**：裸默认为 `undefined`（无条件编辑），因此工具从不 stat 来制造基准。如果裸路径上的目标不存在，提供方报告 `FS_STALE_VERSION`；策略已持有缺失观测时，则直接返回 `FS_NOT_FOUND`。
 
 工具在每次分发时将 `exec`（工具执行上下文）作为 `actor` 参数传入，以便 `dsh-fs-policy` 推导其观测状态的 owner。工具不知道策略插件是否存在：它始终在 `next` thunk 中提供裸默认行为，而 `dsh-fs-policy` 在默认部署中会在 thunk 运行前短路它。
 
-**`fs/observed` 在操作成功后触发。** 其监听器必须是同步、不抛异常的记录器；工具不对 plain emit 做保护，因此抛异常的监听器会在 mutation 已成功后报告失败。异步或可失败的观测需要另一份事件约定。
+**`fs/observed` 在操作成功后，以及元数据探测确认缺失后触发。** 其监听器必须是同步、不抛异常的记录器；工具不对 plain emit 做保护，因此抛异常的监听器可能取代待返回的读取错误，或在 mutation 已成功后报告失败。异步或可失败的观测需要另一份事件约定。
 
 ## 策略插件约定（`dsh-fs-policy`）
 
-`dsh-fs-policy` 是插件，不是服务。它不注册 `ctx.fileContext`，没有公开方法面，不暴露 `read`/`write`/`edit`/`resolve` 方法。它通过 `ctx.on()` 注册三个监听器（每个返回一个 disposer 用于 HMR）。它维护观测状态 `WeakMap<owner, Map<targetKey, { version }>>`，以及结构化的 owner 推导（将事件中不透明的 `object` actor 收窄为自己的 `{ agent?: { session? } }` 形状），但不注入 `fs`——每个处理器只操作自己的 `WeakMap`，从不操作 `ctx.fs`。
+`dsh-fs-policy` 是插件，不是服务。它不注册 `ctx.fileContext`，没有公开方法面，不暴露 `read`/`write`/`edit`/`resolve` 方法。它通过 `ctx.on()` 注册三个监听器（每个返回一个 disposer 用于 HMR）。它维护观测状态 `WeakMap<owner, Map<targetKey, FsObservation>>`，以及结构化的 owner 推导（将事件中不透明的 `object` actor 收窄为自己的 `{ agent?: { session? } }` 形状），但不注入 `fs`——每个处理器只操作自己的 `WeakMap`，从不操作 `ctx.fs`。
 
-- `fs/write-intent` 监听器：`prior = getObserved(owner, key)`；返回 `prior ? { kind: 'replaceIfVersion', version: prior.version } : { kind: 'createIfAbsent' }`。它不调用 `next()`：完全占据单一决策槽位。
-- `fs/edit-intent` 监听器：`prior = getObserved(owner, key)`；如果无 `owner` 或无 `prior`，抛出 `FS_NOT_OBSERVED`；否则返回 `{ version: prior.version }`。同样不调用 `next()`。
-- `fs/observed` 监听器：`record(owner, key, version)`。
+- `fs/write-intent` 监听器：未见/缺失 ⇒ `createIfAbsent`；存在 ⇒ `replaceIfVersion`。它不调用 `next()`：完全占据单一决策槽位。
+- `fs/edit-intent` 监听器：未见 ⇒ `FS_NOT_OBSERVED`；缺失 ⇒ `FS_NOT_FOUND`；存在 ⇒ 返回其版本守卫。同样不调用 `next()`。
+- `fs/observed` 监听器：记录存在/缺失的可辨识值。
 
-一条观测状态条目是**先前观测记录**：成功的 `read`、`write` 或 `edit` 都会 emit `fs/observed` 并记录 `{ version }`，因此条目的存在意味着「此 owner 在此版本观测过此目标」，而非狭义的「已读取过」。这使得 create-then-edit 或 edit-then-edit 序列无需中间重新读取即可工作：mutation 将记录的版本刷新为自身的结果，因此下一次编辑的基准就是它刚产出的版本。`FS_NOT_OBSERVED` 只拒绝完全没有任何先前观测的编辑。owner 从 `{ agent?: { session? } }` 结构化推导；dispose 时丢弃所有状态（HMR 安全）。
+一条观测状态条目是**先前观测记录**，但其可辨识字段会影响决策。成功的 read/write/edit 会记录存在状态及版本，使 create-then-edit 或 edit-then-edit 序列无需中间重新读取即可工作。确认缺失的 read/view 会用缺失状态取代旧的正向版本，因此只允许带防护的创建；随后成功的创建会再用新的存在版本取代缺失状态。只有条目不存在才表示未见，并使 edit 返回 `FS_NOT_OBSERVED`。owner 从 `{ agent?: { session? } }` 结构化推导；dispose 时丢弃所有状态（HMR 安全）。
 
 `dsh-fs-policy` 现在是一个纯策略/记录插件，没有服务面——它只通过事件门控影响外界。这正是移除 `dsh-tool-fs` 方法耦合的关键。
 
@@ -154,7 +156,7 @@ interface Events {
 
 ## 验证
 
-测试固定了两条路径：无 `dsh-fs-policy` 时，根工具插件对 `dsh-fs-local` 启动，read、create、overwrite 和未读 edit 均成功；有策略时，未读 edit 返回 `FS_NOT_OBSERVED`，未读 overwrite 被 `createIfAbsent` 门控。策略决定后，后注册的 intent 监听器不会被触达。陈旧编辑通过提供方 CAS 失败，而策略不执行 `stat`；工具预算在两条路径上保持 read 一次 `stat`，write 或 edit 均为零次。面向模型的 schema 逐字节不变，因此快照不变。
+测试固定了两条路径：无 `dsh-fs-policy` 时，根工具插件对 `dsh-fs-local` 启动，read、create、overwrite 和未读 edit 均成功；有策略时，未读 edit 返回 `FS_NOT_OBSERVED`，未读 overwrite 被 `createIfAbsent` 门控。策略决定后，后注册的 intent 监听器不会被触达。陈旧编辑通过提供方 CAS 失败，而策略不执行 `stat`；工具预算在两条路径上保持 read 一次 `stat`，write 或 edit 均为零次。测试也组装了删除恢复路径：陈旧变更、重新读取时确认缺失、带防护的重新创建。面向模型的 schema 逐字节不变，但恢复后的结果 transcript（文本记录）发生变化。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml
new file mode 100644
index 0000000000..39e50ffe6b
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.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-08-09-filesystem-absence-observation.md
+2026-08-09-filesystem-absence-observation.md: e0c5c8b1845550ac6380ea4b2782cde13cba3ce9
+2026-08-09-filesystem-absence-observation.zh.md: 808698a7cb7a3575ef500dced7a646691d65c424
diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
new file mode 100644
index 0000000000..e0c5c8b184
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
@@ -0,0 +1,36 @@
+# Agent Note: Filesystem absence is an observation and guarded creation never replaces
+
+Status: implemented
+
+English | [中文](2026-08-09-filesystem-absence-observation.zh.md)
+
+## Problem
+
+The event-gated filesystem policy originally records only successful reads and mutations as a target version. If a session reads a file and an external command deletes it, the first guarded mutation correctly fails stale, but the prescribed reread returns `FS_NOT_FOUND` before emitting `fs/observed`. The old positive version therefore remains forever: write keeps choosing `replaceIfVersion`, the provider keeps rejecting the missing target, and the model-facing “re-read the file, then retry” instruction becomes an unrecoverable loop.
+
+Treating a failed read as permission to create also exposes a second boundary. Both local and E2B providers probe before staging, then historically publish with rename; another process can create the target between those steps and be overwritten even though the caller supplied `createIfAbsent`. An in-process target lock does not protect that cross-process publication race.
+
+## Decision
+
+`dsh-fs` owns an explicit observation union: `{ kind: 'present', version: FsVersion } | { kind: 'absent' }`. The `fs/observed` event carries that union. Successful reads and mutations emit present; a `read` or `str_replace_editor view` metadata miss emits absent synchronously before returning `FS_NOT_FOUND`. Other read failures do not manufacture absence.
+
+`dsh-fs-policy` stores three logical states per owner and target without injecting or calling `ctx.fs`: missing map entry is unseen, `absent` is confirmed absence, and `present(version)` is a replacement/edit basis. Write maps unseen and absent to the existing `createIfAbsent` intent and present to `replaceIfVersion`. Edit maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. A successful create or mutation replaces absence with its produced present version.
+
+Every provider must enforce `createIfAbsent` at the publication point, not only at its initial probe. `dsh-fs-local` stages and fsyncs in a private sibling directory, then hard-links the staged file to the destination; an existing destination makes the no-replace link fail and preserves the competitor. `dsh-fs-e2b` uses remote `ln` with an explicit created/existing result and derives the committed target version from metadata obtained before the non-cancellable commit. Replacements and bare unconditional writes retain their existing publication paths.
+
+This decision does not claim cross-process linearizability for `replaceIfVersion`: the provider version check and replacement remain protected only against writers represented by the provider's own lock and detectable metadata. The narrower guarantee is exact and sufficient for absence recovery: guarded creation never clobbers a target that appears before publication.
+
+## Alternatives considered
+
+- **Delete the cached version when a read returns not found.** Rejected because it conflates unseen with confirmed absence, cannot give edit the correct `FS_NOT_FOUND` result, and erases the state transition the event is meant to communicate.
+- **Have `dsh-fs-policy` call `stat` before choosing an intent.** Rejected because it makes the event-only policy depend on a provider, adds I/O to every decision, and still leaves a TOCTOU gap before publication.
+- **Let `replaceIfVersion` create when its target disappeared.** Rejected because a positive observation is evidence for replacement, not creation; silently changing that provider intent would bypass the required missing reread and weaken stale protection.
+- **Keep the deleted-target dead end fail-closed.** Rejected because the model-facing recovery instruction is then false and a normal external cleanup cannot be recovered within the session.
+
+## Consequences
+
+The first mutation after an unobserved external deletion still fails `FS_STALE_VERSION`; the user or model must follow the existing reread remedy. That missing reread returns `FS_NOT_FOUND` while changing policy state, after which edit remains forbidden and write may recreate the path. If another writer wins the create race, the retry returns `FS_NOT_OBSERVED` and leaves the winner intact.
+
+The observation payload is a package-owned event contract change, so every producer, listener, invariant, generated Cordis catalog, subsystem document, and both filesystem tool families move together. The policy keeps its one-stat read and zero-stat write/edit budget, owner isolation, disposal behavior, and optional deployment boundary from the [event-gate decision](../architecture/2026-06-26-file-context-as-event-gate.md).
+
+The assembled filesystem snapshot pins the model-visible recovery chain, while provider tests inject a creator after staging to prove no-clobber publication. The [guarded-mutation remedy decision](../feature/2026-08-03-fs-tool-error-remedy.md) remains the owner of model-facing recovery wording; this note makes its deletion path actionable.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
new file mode 100644
index 0000000000..808698a7cb
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 文件系统中的缺失是一种观测，带防护的创建绝不执行替换
+
+Status: implemented
+
+[English](2026-08-09-filesystem-absence-observation.md) | 中文
+
+## 问题
+
+事件门控的文件系统策略最初只把成功读取和变更记录成目标版本。如果某个会话读取文件后，外部命令将其删除，第一次带防护的变更会正确地因陈旧而失败，但按指示执行的重新读取会在发出 `fs/observed` 前返回 `FS_NOT_FOUND`。因此，旧的存在版本会一直保留：写入仍不断选择 `replaceIfVersion`，提供方仍不断拒绝缺失目标，而面向模型的「re-read the file, then retry」指令则形成无法恢复的循环。
+
+把一次失败的读取视作创建授权，还会暴露第二个边界。本地与 E2B 提供方都会先探测再暂存，此前随后通过 rename 发布；另一进程可能在两步之间创建目标，即使调用方提供了 `createIfAbsent`，该目标仍会被覆盖。进程内目标锁无法防范这种跨进程发布竞态。
+
+## 决策
+
+`dsh-fs` 拥有一个显式观测联合类型：`{ kind: 'present', version: FsVersion } | { kind: 'absent' }`。`fs/observed` 事件携带该联合类型。成功的读取与变更发出存在观测；`read` 或 `str_replace_editor view` 的元数据未命中会在返回 `FS_NOT_FOUND` 前同步发出缺失观测。其他读取失败不会产生缺失观测。
+
+`dsh-fs-policy` 按所有者与目标存储三种逻辑状态，既不注入也不调用 `ctx.fs`：映射中无条目即未见，`absent` 表示确认缺失，`present(version)` 是替换/编辑基准。写入把未见和缺失映射到现有 `createIfAbsent` 意图，把存在映射到 `replaceIfVersion`。编辑把未见映射到 `FS_NOT_OBSERVED`，把缺失映射到 `FS_NOT_FOUND`，把存在映射到其版本守卫。成功创建或变更后，系统会用其产生的存在版本取代缺失状态。
+
+每个提供方都必须在发布点执行 `createIfAbsent`，不能只在初始探测时执行。`dsh-fs-local` 在私有同级目录中暂存并执行 fsync，再通过硬链接把暂存文件发布到目标位置；目标已存在时，不替换链接会失败，并保留竞争创建者写入的文件。`dsh-fs-e2b` 使用远程 `ln` 返回明确的已创建/已存在结果，并根据不可取消提交前取得的元数据推导已提交目标的版本。替换操作和裸无条件写入仍沿用现有发布路径。
+
+本决策不宣称 `replaceIfVersion` 具有跨进程线性一致性：提供方的版本检查与替换仍只能防范被其自身锁纳入协调的写入方，以及能通过元数据检测到的写入方。更窄的保证边界准确且足以支持缺失恢复：带防护的创建绝不会覆盖在发布前出现的目标。
+
+## 曾考虑的替代方案
+
+- **读取返回未找到时删除缓存版本。** 不予采用，因为这会混淆未见与确认缺失，无法让 edit 返回正确的 `FS_NOT_FOUND` 结果，还会抹去该事件本应传达的状态转换。
+- **让 `dsh-fs-policy` 在选择意图前调用 `stat`。** 不予采用，因为这会让只依赖事件的策略转而依赖提供方，为每次决策增加 I/O，并且在发布前仍留下 TOCTOU 间隙。
+- **允许 `replaceIfVersion` 在目标消失后执行创建。** 不予采用，因为存在观测是执行替换而非创建的依据；静默改变该提供方意图会绕过必须针对缺失目标执行的重新读取，并削弱陈旧保护。
+- **让删除目标后的死路继续保持 fail-closed。** 不予采用，因为这样会使面向模型的恢复指令失实，而且正常的外部清理操作无法在会话内恢复。
+
+## 影响
+
+尚未观测到外部删除时，第一次变更仍以 `FS_STALE_VERSION` 失败；用户或模型必须遵循现有的重新读取恢复指令。该次针对缺失目标的重新读取会返回 `FS_NOT_FOUND` 并同时改变策略状态，此后 edit 仍被禁止，而 write 可以重新创建该路径。如果另一个写入方赢得创建竞态，本次重试会返回 `FS_NOT_OBSERVED`，并保留获胜方写入的文件。
+
+观测载荷是由包拥有的事件约定变更，因此所有生产方、监听器、不变式、生成的 Cordis 目录、子系统文档以及两套文件系统工具都必须同步更新。策略保留[事件门禁决策](../architecture/2026-06-26-file-context-as-event-gate.md)确立的 read 一次 `stat`、write/edit 零次 `stat` 预算、所有者隔离、dispose 行为和可选部署边界。
+
+组装后的文件系统快照固定面向模型的恢复链；提供方测试则在暂存后注入一个创建者，以证明发布不会覆盖竞争目标。[带防护变更恢复指令决策](../feature/2026-08-03-fs-tool-error-remedy.md)仍然拥有面向模型的恢复措辞；本 Agent Note 使其中的删除路径能够生效。
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
index d9d9142437..484b6bfe36 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.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 .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
-2026-08-03-fs-tool-error-remedy.md: f227c31365725652b130e097d70c79d3daab3684
-2026-08-03-fs-tool-error-remedy.zh.md: 6bb0d0b6ffcda282db67dd1a54f0074b3be5c6e1
+2026-08-03-fs-tool-error-remedy.md: c4f0bb86100a4856c536edf22e520662e19ea4f6
+2026-08-03-fs-tool-error-remedy.zh.md: 88309bd630732794dfb2401b60ad799a3d63146b
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
index f227c31365..c4f0bb8610 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md
@@ -29,4 +29,4 @@ In `edit.ts` the `fs/edit-intent` waterfall now sits inside the same `try` as th
 
 Model-visible text for the two codes changes; the `fs-policy-reject` keyless snapshot is re-recorded, and the READMEs of `dsh-tool-fs` and `dsh-fs-policy` pin the exact appended text. Unit tests cover the wrapper directly (remedy text, code preservation, cause chaining, passthrough of other codes and non-`FsError` values) and the assembled tool paths assert the remedy reaches the model for both codes.
 
-The remedy is not a promise: a deleted observed target cannot be unblocked, because re-reading a missing file fails with `FS_NOT_FOUND` and records no observation. That dead end is pinned fail-closed in the integration tests — the retried mutation fails identically until the target exists again and is freshly observed.
+The [filesystem absence-observation follow-up](../bug-fix/2026-08-09-filesystem-absence-observation.md) makes the stale remedy actionable for external deletion. The failed reread still returns `FS_NOT_FOUND`, but records confirmed absence: edit then returns `FS_NOT_FOUND` without another stale remedy, while write retries as an atomic `createIfAbsent` and preserves any concurrent creator.
diff --git a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
index 6bb0d0b6ff..88309bd630 100644
--- a/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.zh.md
@@ -29,4 +29,4 @@ Status: implemented
 
 两个错误码的模型可见文本发生变化；`fs-policy-reject` 无密钥快照被重新录制，`dsh-tool-fs` 与 `dsh-fs-policy` 的 README 逐字固定追加后的文本。单元测试直接覆盖包装层（恢复指令文本、错误码保留、cause 链、其他错误码与非 `FsError` 值的透传），组装后的工具路径断言两个错误码的恢复指令都到达模型。
 
-恢复指令不是承诺：已观察但被删除的目标无法被解除阻塞，因为重新读取缺失文件会以 `FS_NOT_FOUND` 失败且不记录观察。这一死胡同在集成测试中以 fail-closed 方式固定——在目标重新存在并被重新观察之前，重试的变更以相同方式失败。
+[文件系统缺失观测后续决策](../bug-fix/2026-08-09-filesystem-absence-observation.md)使外部删除场景下的陈旧恢复指令能够生效。失败的重新读取仍返回 `FS_NOT_FOUND`，但会记录确认缺失：随后 edit 返回 `FS_NOT_FOUND`，不再附加陈旧恢复指令；write 则以原子 `createIfAbsent` 重试，并保留任何并发创建者写入的文件。
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 5ec532504d..9607dc8d1a 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: a059159aae690330c55971bc49d62fcb1b030660
-config-catalog.zh.md: 9a0742ec8af10db90d0a2aad146c0cbec5a1a8a2
+config-catalog.md: 5f3bc744b25bf20d50e88ce75812fe8bd624905a
+config-catalog.zh.md: a7d4252c526d36643a1b9f7aebd627faa60e1c77
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a059159aae..5f3bc744b2 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -2137,7 +2137,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/fs/tool-str-replace-editor/src/index.ts:496`](../packages/fs/tool-str-replace-editor/src/index.ts)
+Source: [`packages/fs/tool-str-replace-editor/src/index.ts:497`](../packages/fs/tool-str-replace-editor/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-subagent`
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 9a0742ec8a..a7d4252c52 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -2138,7 +2138,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/fs/tool-str-replace-editor/src/index.ts:496`](../packages/fs/tool-str-replace-editor/src/index.ts)
+来源：[`packages/fs/tool-str-replace-editor/src/index.ts:497`](../packages/fs/tool-str-replace-editor/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-subagent`
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 788069e02d..41da1ee118 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: d5f6674a5e9355f6f2c3fac23a45fcda180b3a0f
-event-producer-consumer.zh.md: 7568e852c891e6c9556486899fe1bdcd3053cb07
+event-producer-consumer.md: 5b36725402c0a12c5e2a09c743c2e7cf28d2c14a
+event-producer-consumer.zh.md: 2d4c805f9a5d3b0531ee59eebe9e6564347f0a00
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index d5f6674a5e..5b36725402 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -24,9 +24,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
-| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:64`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
-| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:73`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
-| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:56`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
+| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 7568e852c8..2d4c805f9a 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -26,9 +26,9 @@
 | `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
-| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:64`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
-| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:73`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
-| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:56`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-policy`](../packages/fs/fs-policy), [`skill-local`](../packages/skill/skill-local) |
+| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
 | `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 3dad767e63..04c08db9a6 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 6748ddc7f290b6714302223758587226647641e7
-filesystem.zh.md: 28535d3d9d40e92bb6d5b2b0995a535b42fd9a23
+filesystem.md: 5d06611cbad2a3f146ddef4dbc96b2b6fc0a5b46
+filesystem.zh.md: 97aac2ee20783787909605d90a94181bf093d78a
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 6748ddc7f2..5d06611cba 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -2,7 +2,7 @@
 
 English | [中文](filesystem.zh.md)
 
-The optional filesystem capability has four parts: [dsh-fs](../../packages/fs/fs) owns `ctx.fs` and atomic text operations with optional version guards, [dsh-fs-local](../../packages/fs/fs-local) implements local disk, [dsh-fs-policy](../../packages/fs/fs-policy) adds observed-state and freshness rules through events rather than a service, and [dsh-tool-fs](../../packages/fs/tool-fs) directly executes model-facing read/write/edit calls and renders windows. It is outside the agent-loop spine; alternate backends do not change policy or tool schemas.
+The optional filesystem capability has four parts: [dsh-fs](../../packages/fs/fs) owns `ctx.fs` and atomic text operations with optional guards, [dsh-fs-local](../../packages/fs/fs-local) implements local disk, [dsh-fs-policy](../../packages/fs/fs-policy) records observed presence or absence and adds freshness rules through events rather than a service, and [dsh-tool-fs](../../packages/fs/tool-fs) directly executes model-facing read/write/edit calls and renders windows. It is outside the agent-loop spine; alternate backends do not change policy or tool schemas.
 
 The model is **additive, not subtractive**: `ctx.fs` alone is a complete, unconstrained text-storage seam (`write` unconditionally creates-or-overwrites, `edit` unconditionally replaces literal text). `dsh-fs-policy` is a plugin that *adds* policy on top by deciding the `fs/*` waterfalls; removing it leaves the bare provider rather than breaking the tool, because the tool is not method-coupled to the policy. A deployment that loads `dsh-tool-fs` is expected to also load `dsh-fs-policy` so the default behavior is read-before-write/edit.
 
@@ -113,7 +113,7 @@ interface FsDirEntry {
 
 ## Write and edit guards (provider contract)
 
-Both `writeText` and `editText` take their version guard OPTIONALLY: omit it for an unconditional (bare-provider) mutation, supply it to guard. `writeText`'s guard is an `FsWriteIntent` — `createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only when the target exists at the observed version, else `FS_STALE_VERSION`. Omitting `expected` unconditionally creates-or-overwrites. The union itself carries only the two guarded intents; "no guard" is expressed by omission, so write and edit share one symmetric `expected?` shape.
+Both `writeText` and `editText` take their version guard OPTIONALLY: omit it for an unconditional (bare-provider) mutation, supply it to guard. `writeText`'s guard is an `FsWriteIntent` — `createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`, including a target that appears after the provider's initial probe because publication itself must be no-replace; `replaceIfVersion` replaces only when the target exists at the observed version, else `FS_STALE_VERSION`. Omitting `expected` unconditionally creates-or-overwrites. The union itself carries only the two guarded intents; "no guard" is expressed by omission, so write and edit share one symmetric `expected?` shape.
 
 ```ts type-equiv
 /**
@@ -181,7 +181,18 @@ interface FsEditOutcome {
 
 `dsh-fs` owns three events the tool dispatches and the policy plugin listens for, so the emitter (`dsh-tool-fs`) and the listener (`dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
-`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener would surface as the tool's `isError` result for a mutation that already succeeded. The generated [cordis surface](#cordis-surface) below shows the exact signatures.
+`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event carrying an `FsObservation`: present at a version or confirmed absent. It is dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener can replace a read error or surface as the tool's `isError` result after a mutation already succeeded. The generated [cordis surface](#cordis-surface) below shows the exact signatures.
+
+```ts type-equiv
+/**
+ * One authoritative observation of a target. A present observation carries the
+ * version used by guarded replacement; an absent observation authorizes only a
+ * guarded create, never an edit.
+ */
+type FsObservation =
+  | { readonly kind: 'present'; readonly version: FsVersion }
+  | { readonly kind: 'absent' }
+```
 
 ## Execution context (policy plugin)
 
@@ -209,7 +220,7 @@ interface FsPolicyExec {
 
 ## Read outcome (consumer / read rendering)
 
-A text read is bounded by line window, byte cap, and backend limits. After the byte cap is reached, scanning continues without retaining more lines so `totalLines` remains exact. The outcome the model-facing `read` tool renders is purely presentational; there is no `full`/`partial` view — authorization is freshness-based (the tool emits `fs/observed` with the stat's version directly), so any windowed read can authorize a later write/edit when the file is unchanged. Read windowing and this outcome shape live in `dsh-tool-fs` (the executor that owns the read), not in the policy plugin.
+A text read is bounded by line window, byte cap, and backend limits. After the byte cap is reached, scanning continues without retaining more lines so `totalLines` remains exact. The outcome the model-facing `read` tool renders is purely presentational; there is no `full`/`partial` view — authorization is freshness-based (the tool emits a present `fs/observed` with the stat's version), so any windowed read can authorize a later write/edit when the file is unchanged. A metadata miss emits an absent observation before the tool returns `FS_NOT_FOUND`, allowing a later guarded write to recreate an externally deleted target without authorizing edit. Read windowing and this outcome shape live in `dsh-tool-fs` (the executor that owns the read), not in the policy plugin.
 
 ```ts type-equiv
 /** Outcome of a bounded text read — what {@link formatReadOutput} renders. */
@@ -227,7 +238,7 @@ interface FileReadOutcome {
 
 ## Observed-file state (policy plugin)
 
-Observed state is a `WeakMap<owner, Map<targetKey, { version }>>` held inside the `dsh-fs-policy` plugin. An entry exists **iff** the owner has read, written, OR edited that target (every success emits `fs/observed`), so its presence is the prior-observation record — there is no separate `hasRead` flag and no view distinction. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. A successful read/write/edit refreshes the recorded version for that owner; disposal drops everything (HMR safety).
+Observed state is a `WeakMap<owner, Map<targetKey, FsObservation>>` held inside the `dsh-fs-policy` plugin. Missing map entry means unseen; `{ kind: 'absent' }` means a tool read/view confirmed absence; `{ kind: 'present', version }` means a read, write, or edit observed that version. The write decision maps unseen and absent to `createIfAbsent`, while present maps to `replaceIfVersion`; the edit decision maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. Disposal drops everything (HMR safety), and the policy performs no filesystem I/O.
 
 ## Error taxonomy (provider contract)
 
@@ -254,7 +265,7 @@ type FsErrorCode =
   | 'FS_ABORTED'
 ```
 
-`FS_NOT_DIRECTORY`, `FS_PERMISSION_DENIED`, and `FS_IO_ERROR` are used by directory listing to distinguish an existing non-directory target, a denied listing, and an unexpected backend I/O failure. `FS_SANDBOX_DENIED` is a POLICY refusal from a sandbox-enforcing backend (`dsh-fs-sandbox`) — the mode fence denied a write/edit — distinct from `FS_PERMISSION_DENIED` (the host kernel refusing). `FS_NOT_OBSERVED` means the policy plugin has no prior-observation record for this owner (or a `createIfAbsent` hit an existing file). `FS_STALE_VERSION` means the backend version no longer matches the observed one (or an edit hit a missing target). Freshness authorization has no partial/full distinction, so there is no `FS_PARTIAL_OBSERVATION`.
+`FS_NOT_DIRECTORY`, `FS_PERMISSION_DENIED`, and `FS_IO_ERROR` are used by directory listing to distinguish an existing non-directory target, a denied listing, and an unexpected backend I/O failure. `FS_SANDBOX_DENIED` is a POLICY refusal from a sandbox-enforcing backend (`dsh-fs-sandbox`) — the mode fence denied a write/edit — distinct from `FS_PERMISSION_DENIED` (the host kernel refusing). `FS_NOT_OBSERVED` means the policy plugin has no prior-observation record for this owner (or a `createIfAbsent` hit an existing file). `FS_NOT_FOUND` also represents an edit rejected from confirmed absence. `FS_STALE_VERSION` means the backend version no longer matches the observed one (or the provider itself receives an edit for a missing target). Freshness authorization has no partial/full distinction, so there is no `FS_PARTIAL_OBSERVATION`.
 
 ## No timeouts on file IO
 
@@ -262,7 +273,7 @@ type FsErrorCode =
 
 ## The service and the plugin
 
-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `processPath`, `fileUrl`, `contains`, `stat`, `lstat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls from unseen/absent/present state and records `FsObservation` values. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated [`ctx.fs` section](#ctxfs--filesystem-abstract-seam) below shows the exact signatures.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -376,7 +387,7 @@ abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
  * @param target - the resolved target to write.
  * @param content - the full new file content.
  * @param expected - the write intent guarding the write; omit for unconditional.
- * @param signal - aborts before the atomic rename takes effect.
+ * @param signal - aborts before atomic publication takes effect.
  * @param sandboxPolicy - the per-call mode and workspace root this write
  *   runs under; a sandboxing backend fences the write by it, the bare backend
  *   ignores it. Omit to leave the backend its own default.
@@ -391,7 +402,7 @@ abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent,
  * @param target - the resolved target to edit.
  * @param edit - the literal search/replace request.
  * @param expected - the version guard; omit for an unconditional edit.
- * @param signal - aborts before the atomic rename takes effect.
+ * @param signal - aborts before atomic publication takes effect.
  * @param sandboxPolicy - the per-call mode and workspace root this edit runs
  *   under; a sandboxing backend fences the edit by it, the bare backend
  *   ignores it. Omit to leave the backend its own default.
@@ -402,7 +413,7 @@ abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version:
 
 Types: [SandboxExecutionPolicy](sandbox.md)
 
-Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:86`](../../packages/fs/fs/src/index.ts)
 
 <a id="fs-events"></a>
 
@@ -425,27 +436,28 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
 ```
 
-Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:66`](../../packages/fs/fs/src/index.ts)
 
 <a id="fsobserved--emit"></a>
 
 #### `fs/observed` — emit
 
-Record a successful observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
+Record an authoritative positive or negative observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
 
 ```ts cordis-catalog
 /**
- * Record a successful observation. Listeners must be synchronous recorders:
- * throws fail the tool call and returned promises are not awaited.
- * @param target - the target that was read/written/edited.
- * @param version - the version the actor now holds as its observation.
+ * Record an authoritative positive or negative observation. Listeners must
+ * be synchronous recorders: throws fail the tool call and returned promises
+ * are not awaited.
+ * @param target - the target whose presence or absence was observed.
+ * @param observation - present with its version, or confirmed absent.
  * @param actor - the observing tool-execution context; undefined records nothing useful.
  * @mode emit
  */
-'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
 ```
 
-Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:76`](../../packages/fs/fs/src/index.ts)
 
 <a id="fswrite-intent--waterfall"></a>
 
@@ -465,5 +477,5 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
 ```
 
-Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:58`](../../packages/fs/fs/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 28535d3d9d..97aac2ee20 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -2,7 +2,7 @@
 
 [English](filesystem.md) | 中文
 
-可选的文件系统能力由四个部分组成：[dsh-fs](../../packages/fs/fs) 拥有 `ctx.fs` 以及带可选版本守卫的原子文本操作；[dsh-fs-local](../../packages/fs/fs-local) 实现本地磁盘后端；[dsh-fs-policy](../../packages/fs/fs-policy) 通过事件（而非服务）添加观测状态与新鲜度规则；[dsh-tool-fs](../../packages/fs/tool-fs) 直接执行面向模型的 read/write/edit 调用并渲染窗口。它位于 agent loop（智能体循环）主干之外；替换后端不会改变策略或工具 schema。
+可选的文件系统能力由四个部分组成：[dsh-fs](../../packages/fs/fs) 拥有 `ctx.fs` 以及带可选守卫的原子文本操作；[dsh-fs-local](../../packages/fs/fs-local) 实现本地磁盘后端；[dsh-fs-policy](../../packages/fs/fs-policy) 记录观测到的存在或缺失状态，并通过事件（而非服务）添加新鲜度规则；[dsh-tool-fs](../../packages/fs/tool-fs) 直接执行面向模型的 read/write/edit 调用并渲染窗口。它位于 agent loop（智能体循环）主干之外；替换后端不会改变策略或工具 schema。
 
 该模型是**加法式而非减法式**的：`ctx.fs` 本身就是一个完整、无约束的文本存储 seam（`write` 无条件创建或覆盖，`edit` 无条件替换字面文本）。`dsh-fs-policy` 是一个插件，通过裁决 `fs/*` waterfall（瀑布式事件）在上层*叠加*策略；移除它只会暴露裸提供方，而不会破坏工具，因为工具与策略之间没有方法级耦合。加载了 `dsh-tool-fs` 的部署通常也应加载 `dsh-fs-policy`，使默认行为为「先读后写/编辑」。
 
@@ -113,7 +113,7 @@ interface FsDirEntry {
 
 ## 写入与编辑守卫（提供方约定）
 
-`writeText` 和 `editText` 的版本守卫都是可选的：省略守卫时执行无条件的裸提供方变更，提供守卫时则执行相应的条件检查。`writeText` 的守卫是 `FsWriteIntent`：`createIfAbsent` 在目标缺失时创建，目标已存在时以 `FS_NOT_OBSERVED` 拒绝；`replaceIfVersion` 仅在目标存在且版本匹配时替换，否则报 `FS_STALE_VERSION`。省略 `expected` 则无条件创建或覆盖。联合类型本身只包含两种有守卫的意图；「无守卫」通过省略表达，因此 write 和 edit 共享同一个对称的 `expected?` 形状。
+`writeText` 和 `editText` 的版本守卫都是可选的：省略守卫时执行无条件的裸提供方变更，提供守卫时则执行相应的条件检查。`writeText` 的守卫是 `FsWriteIntent`：`createIfAbsent` 在目标缺失时创建，目标已存在时以 `FS_NOT_OBSERVED` 拒绝；即使目标在提供方初始探测后才出现，也必须拒绝，因为发布操作本身不得替换。`replaceIfVersion` 仅在目标存在且版本匹配时替换，否则报 `FS_STALE_VERSION`。省略 `expected` 则无条件创建或覆盖。联合类型本身只包含两种有守卫的意图；「无守卫」通过省略表达，因此 write 和 edit 共享同一个对称的 `expected?` 形状。
 
 ```ts type-equiv
 /**
@@ -181,7 +181,18 @@ interface FsEditOutcome {
 
 `dsh-fs` 拥有三个事件，由工具分发、策略插件监听，使发射方（`dsh-tool-fs`）与监听方（`dsh-fs-policy`）共享词汇，而发射方无需依赖策略插件。它们只携带 `dsh-fs` 词汇加一个不透明的 `object` actor，不含面向模型的概念，也不含 agent/会话所有者结构。
 
-`fs/write-intent` 与 `fs/edit-intent` 是**单槽决策 waterfall**：工具分发时附带一个默认 thunk（返回 `undefined`，即裸提供方），监听方完全决策而不调用 `next()`。该槽按注册顺序先到先得——由策略插件占据是部署约定，而非强制不变式。`fs/observed` 是一个即发即弃的记录事件，通过普通 `ctx.emit` 分发；其监听方必须是同步的、仅产生副作用，因为工具不会捕获该 emit 抛出的异常——抛出异常的监听方会导致工具为一次已经成功的变更返回 `isError` 结果。下方生成的 [cordis surface](#cordis-surface) 展示确切签名。
+`fs/write-intent` 与 `fs/edit-intent` 是**单槽决策 waterfall**：工具分发时附带一个默认 thunk（返回 `undefined`，即裸提供方），监听方完全决策而不调用 `next()`。该槽按注册顺序先到先得——由策略插件占据是部署约定，而非强制不变式。`fs/observed` 是一个即发即弃的记录事件，携带 `FsObservation`：存在于某个版本，或确认缺失。该事件通过普通 `ctx.emit` 分发；其监听方必须是同步的、仅产生副作用，因为工具不会捕获该 emit 抛出的异常——抛出异常的监听方可能取代读取操作原本待返回的错误，或使工具在变更已经成功后返回 `isError` 结果。下方生成的 [cordis surface](#cordis-surface) 展示确切签名。
+
+```ts type-equiv
+/**
+ * One authoritative observation of a target. A present observation carries the
+ * version used by guarded replacement; an absent observation authorizes only a
+ * guarded create, never an edit.
+ */
+type FsObservation =
+  | { readonly kind: 'present'; readonly version: FsVersion }
+  | { readonly kind: 'absent' }
+```
 
 ## 执行上下文（策略插件）
 
@@ -209,7 +220,7 @@ interface FsPolicyExec {
 
 ## 读取结果（消费方 / 读取渲染）
 
-文本读取受行窗口、字节上限和后端限制约束。达到字节上限后，扫描仍会继续，但不再保留更多行，因此 `totalLines` 仍为精确值。面向模型的 `read` 工具渲染的结果纯粹是展示性的；不存在 `full`/`partial` 视图区分——授权基于新鲜度（工具直接用 stat 的版本 emit `fs/observed`），因此任何窗口化读取在文件未变时都能授权后续的 write/edit。读取窗口化与此结果形状位于 `dsh-tool-fs`（拥有读取操作的执行器）中，而非策略插件中。
+文本读取受行窗口、字节上限和后端限制约束。达到字节上限后，扫描仍会继续，但不再保留更多行，因此 `totalLines` 仍为精确值。面向模型的 `read` 工具渲染的结果纯粹是展示性的；不存在 `full`/`partial` 视图区分——授权基于新鲜度（工具以 stat 的版本 emit 表示存在的 `fs/observed`），因此任何窗口化读取在文件未变时都能授权后续的 write/edit。元数据未命中时，工具会在返回 `FS_NOT_FOUND` 前 emit 缺失观测，使后续带防护的写入可以重新创建外部删除的目标，但不会授权 edit。读取窗口化与此结果形状位于 `dsh-tool-fs`（拥有读取操作的执行器）中，而非策略插件中。
 
 ```ts type-equiv
 /** Outcome of a bounded text read — what {@link formatReadOutput} renders. */
@@ -227,7 +238,7 @@ interface FileReadOutcome {
 
 ## 已观测文件状态（策略插件）
 
-已观测状态是 `dsh-fs-policy` 插件内部持有的 `WeakMap<owner, Map<targetKey, { version }>>`。**当且仅当**所有者已读取、写入或编辑过该目标时（每次成功都 emit `fs/observed`），条目才存在，因此其存在本身就是先前观测的记录——没有单独的 `hasRead` 标志，也没有视图区分。所有者从事件 actor 推导（通常是 `exec.agent.session`），被视为不透明且从不读取。成功的 read/write/edit 会刷新该所有者对应的已记录版本；dispose（资源释放）时丢弃全部数据（HMR（热模块替换）安全）。
+已观测状态是 `dsh-fs-policy` 插件内部持有的 `WeakMap<owner, Map<targetKey, FsObservation>>`。映射中没有条目表示未见；`{ kind: 'absent' }` 表示工具的 read/view 已确认缺失；`{ kind: 'present', version }` 表示 read、write 或 edit 观测到该版本。写入决策把未见和缺失映射到 `createIfAbsent`，把存在映射到 `replaceIfVersion`；编辑决策把未见映射到 `FS_NOT_OBSERVED`，把缺失映射到 `FS_NOT_FOUND`，把存在映射到其版本守卫。所有者从事件 actor 推导（通常是 `exec.agent.session`），被视为不透明且从不读取。dispose（资源释放）时丢弃全部数据（HMR（热模块替换）安全），策略不执行任何文件系统 I/O。
 
 ## 错误分类体系（提供方约定）
 
@@ -254,7 +265,7 @@ type FsErrorCode =
   | 'FS_ABORTED'
 ```
 
-目录列表使用 `FS_NOT_DIRECTORY`、`FS_PERMISSION_DENIED` 与 `FS_IO_ERROR` 区分已存在但并非目录的目标、被拒绝的列表操作和意外的后端 I/O 失败。`FS_SANDBOX_DENIED` 是强制执行沙箱的后端（`dsh-fs-sandbox`）所作的策略拒绝——模式边界拒绝了写入/编辑——与 `FS_PERMISSION_DENIED`（宿主内核拒绝）不同。`FS_NOT_OBSERVED` 表示策略插件没有此所有者的先前观察记录（或 `createIfAbsent` 遇到了现有文件）。`FS_STALE_VERSION` 表示后端版本不再与观察到的版本匹配（或编辑操作遇到缺失目标）。新鲜度授权没有部分/完整之分，因此不存在 `FS_PARTIAL_OBSERVATION`。
+目录列表使用 `FS_NOT_DIRECTORY`、`FS_PERMISSION_DENIED` 与 `FS_IO_ERROR` 区分已存在但并非目录的目标、被拒绝的列表操作和意外的后端 I/O 失败。`FS_SANDBOX_DENIED` 是强制执行沙箱的后端（`dsh-fs-sandbox`）所作的策略拒绝——模式边界拒绝了写入/编辑——与 `FS_PERMISSION_DENIED`（宿主内核拒绝）不同。`FS_NOT_OBSERVED` 表示策略插件没有此所有者的先前观测记录（或 `createIfAbsent` 遇到了现有文件）。`FS_NOT_FOUND` 也表示策略因确认缺失而拒绝 edit。`FS_STALE_VERSION` 表示后端版本不再与观测到的版本匹配（或提供方本身收到针对缺失目标的 edit）。新鲜度授权没有部分/完整之分，因此不存在 `FS_PARTIAL_OBSERVATION`。
 
 ## 文件 IO 不设超时
 
@@ -262,7 +273,7 @@ type FsErrorCode =
 
 ## 服务与插件
 
-`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：对写入/编辑意图 waterfall 作出决策（提供 `createIfAbsent`/`replaceIfVersion`/`{ version }`，或抛出 `FS_NOT_OBSERVED`），并在 `fs/observed` 上记录。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
+`FileSystem`（`ctx.fs`，abstract）拥有提供方原语：`resolve`、`processPath`、`fileUrl`、`contains`、`stat`、`lstat`、`readText`、`streamText`、`listDir`、`writeText` 与 `editText`。`dsh-fs-policy` **不注册服务**——它是一个通过 `fs/*` 事件门禁添加策略的插件：根据未见/缺失/存在状态对写入与编辑意图 waterfall 作出决策，并记录 `FsObservation` 值。执行器是 `dsh-tool-fs`：它通过 `ctx.fs` 读取/写入/编辑，分发 waterfall，并 emit 记录事件。下方生成的 [`ctx.fs` 小节](#ctxfs--filesystem-abstract-seam) 展示确切的 `ctx.fs` 签名。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -376,7 +387,7 @@ abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
  * @param target - the resolved target to write.
  * @param content - the full new file content.
  * @param expected - the write intent guarding the write; omit for unconditional.
- * @param signal - aborts before the atomic rename takes effect.
+ * @param signal - aborts before atomic publication takes effect.
  * @param sandboxPolicy - the per-call mode and workspace root this write
  *   runs under; a sandboxing backend fences the write by it, the bare backend
  *   ignores it. Omit to leave the backend its own default.
@@ -391,7 +402,7 @@ abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent,
  * @param target - the resolved target to edit.
  * @param edit - the literal search/replace request.
  * @param expected - the version guard; omit for an unconditional edit.
- * @param signal - aborts before the atomic rename takes effect.
+ * @param signal - aborts before atomic publication takes effect.
  * @param sandboxPolicy - the per-call mode and workspace root this edit runs
  *   under; a sandboxing backend fences the edit by it, the bare backend
  *   ignores it. Omit to leave the backend its own default.
@@ -402,7 +413,7 @@ abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version:
 
 Types: [SandboxExecutionPolicy](sandbox.md)
 
-Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:86`](../../packages/fs/fs/src/index.ts)
 
 <a id="fs-events"></a>
 
@@ -425,27 +436,28 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
 ```
 
-Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:66`](../../packages/fs/fs/src/index.ts)
 
 <a id="fsobserved--emit"></a>
 
 #### `fs/observed` — emit
 
-Record a successful observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
+Record an authoritative positive or negative observation. Listeners must be synchronous recorders: throws fail the tool call and returned promises are not awaited.
 
 ```ts cordis-catalog
 /**
- * Record a successful observation. Listeners must be synchronous recorders:
- * throws fail the tool call and returned promises are not awaited.
- * @param target - the target that was read/written/edited.
- * @param version - the version the actor now holds as its observation.
+ * Record an authoritative positive or negative observation. Listeners must
+ * be synchronous recorders: throws fail the tool call and returned promises
+ * are not awaited.
+ * @param target - the target whose presence or absence was observed.
+ * @param observation - present with its version, or confirmed absent.
  * @param actor - the observing tool-execution context; undefined records nothing useful.
  * @mode emit
  */
-'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
 ```
 
-Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:76`](../../packages/fs/fs/src/index.ts)
 
 <a id="fswrite-intent--waterfall"></a>
 
@@ -465,5 +477,5 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
 ```
 
-Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts)
+Source: [`packages/fs/fs/src/index.ts:58`](../../packages/fs/fs/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index cb88c51de0..752a8f6a9e 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.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 docs/tool-catalog.md
-tool-catalog.md: 36ea230990abd65ad0435e257e237f9bf873108f
-tool-catalog.zh.md: f6073b84a08ed25c3fa6e8104388e00aa774a34a
+tool-catalog.md: abcba1ca5dcb148aa0ee5578ff4fd0373993db1d
+tool-catalog.zh.md: 32c761d0d2854bf2310eb0ddb382553575bd4df9
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 36ea230990..abcba1ca5d 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -22,8 +22,8 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session; ConPTY is roadmap work), with native `C:\...` paths and `$env:NAME` variables. |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `process-local temporary Plugin lifecycle` | - | Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes. |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`, `ctx.pty`, `an owning Agent at execution time` | `tool/call`, `PTY shell state`, `tool/result` | - | One owner-isolated persistent bash tool; deployment composition supplies the PTY backend and may override the model-facing environment description. |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after successful file operations`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
-| `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after view presence/absence or successful mutation`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
+| `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after read presence/absence or successful mutation`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.subprocess`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are unconditional discovery tools that spawn the packaged ripgrep binary (`@vscode/ripgrep`) through ctx.subprocess as ordinary foreground calls (never background tasks) — no host `rg` install and no shell layer. The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. |
 | `@deepseek-ai/dsh-tool-goal` | `create_goal`, `get_goal`, `update_goal` | `ctx.tools`, `ctx.agents`, `ctx.goals`, `ctx.systemPrompt`, `a calling Agent in an authorized open turn` | `tool/call`, `goal/change for mutations`, `tool/result` | - | create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds. |
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index f6073b84a0..32c761d0d2 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -24,8 +24,8 @@
 | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`process-local temporary Plugin lifecycle` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after successful file operations`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
-| `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`fs/write-intent or fs/edit-intent for mutations`、`fs/observed after successful file operations`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after view presence/absence or successful mutation`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
+| `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`fs/write-intent or fs/edit-intent for mutations`、`fs/observed after read presence/absence or successful mutation`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`、`grep` | `ctx.tools`、`ctx.subprocess`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`、`terminal_list`、`terminal_open`、`terminal_read`、`terminal_send`、`terminal_signal` | `ctx.tools`、`ctx.pty`、`ctx.systemPrompt`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 |
 | `@deepseek-ai/dsh-tool-goal` | `create_goal`、`get_goal`、`update_goal` | `ctx.tools`、`ctx.agents`、`ctx.goals`、`ctx.systemPrompt`、`a calling Agent in an authorized open turn` | `tool/call`、`goal/change for mutations`、`tool/result` | - | create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 |
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index b0b646eade..af044fc58f 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -255,6 +255,7 @@ const SCENARIOS: Scenario[] = [
   { name: 'fs-write-overwrite', hasModelTurn: true, recorded: true },
   { name: 'fs-read-window', hasModelTurn: true, recorded: true },
   { name: 'fs-policy-reject', hasModelTurn: true, recorded: true },
+  { name: 'fs-delete-recreate', hasModelTurn: true, recorded: true },
   { name: 'multi-turn', hasModelTurn: true, recorded: true },
   { name: 'error-finish', hasModelTurn: true, recorded: false, overridden: true },
   // Keyless, authored (like error-finish): a live provider cannot be coaxed
diff --git a/examples/acp-agent/tests/snapshots/fs-delete-recreate/input.json b/examples/acp-agent/tests/snapshots/fs-delete-recreate/input.json
new file mode 100644
index 0000000000..f6c181074f
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/fs-delete-recreate/input.json
@@ -0,0 +1,7 @@
+{
+  "steps": [
+    { "op": "initialize" },
+    { "op": "newSession" },
+    { "op": "prompt", "text": "Perform these exact steps in order on deleted.txt in the current directory: (1) use the read tool to read it, (2) use the bash tool with command `rm deleted.txt`, (3) use the read tool on deleted.txt again and observe the not-found error, (4) use the write tool to recreate deleted.txt with exactly the content `fresh\\n`, and (5) reply with exactly the single word DONE. Do not use any other tools or skip any step." }
+  ]
+}
diff --git a/examples/acp-agent/tests/snapshots/fs-delete-recreate/session.jsonl b/examples/acp-agent/tests/snapshots/fs-delete-recreate/session.jsonl
new file mode 100644
index 0000000000..7cccd53d6b
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/fs-delete-recreate/session.jsonl
@@ -0,0 +1,62 @@
+{"type":"session","version":0,"id":"b8c89c36-55db-48cf-9f3e-76140cd37aff","createdAt":1786259114417,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"agent/inbox/spliced","seq":0,"time":1786259114424,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Perform these exact steps in order on deleted.txt in the current directory: (1) use the read tool to read it, (2) use the bash tool with command `rm deleted.txt`, (3) use the read tool on deleted.txt again and observe the not-found error, (4) use the write tool to recreate deleted.txt with exactly the content `fresh\\n`, and (5) reply with exactly the single word DONE. Do not use any other tools or skip any step."}],"source":{"kind":"user"},"role":"user","id":"d2c7929c-e9af-4011-85c4-fe35eb4d5bfe"}]}}
+{"type":"turn/start","seq":1,"time":1786259114425,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":1786259114425,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":3,"time":1786259114479,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":4,"time":1786259114479,"data":{"content":[{"type":"text","text":"Perform these exact steps in order on deleted.txt in the current directory: (1) use the read tool to read it, (2) use the bash tool with command `rm deleted.txt`, (3) use the read tool on deleted.txt again and observe the not-found error, (4) use the write tool to recreate deleted.txt with exactly the content `fresh\\n`, and (5) reply with exactly the single word DONE. Do not use any other tools or skip any step."}],"source":{"kind":"user"},"role":"user","id":"d2c7929c-e9af-4011-85c4-fe35eb4d5bfe"},"surfaceOp":"append"}
+{"type":"user/message","seq":5,"time":1786259114479,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"09f49ebb-fe8b-4100-9fb1-63461c4e5ff4"},"surfaceOp":"append"}
+{"type":"session/title","seq":6,"time":1786259114480,"data":{"title":"Perform these exact steps in","messageSeqs":[4],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":7,"time":1786259114481,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","seq":8,"time":1786259114481,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":9,"time":1786259115592,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"reasoning-chunks","seq0":10,"time0":1786259115592,"data":{"turn":1,"step":1,"index":0,"dt":[100,24,1,0,0,0,21,0,0,0,0,1,22,0,1,23,1,0,0,25,0,21,1,0,0,0,21,1,0,0,24,0,1,0,0,0,20,0,27,1,0,0,26,1,0,21,1,0,0,19,89,0,0,0,0,1,0,0,0,0,0,1,0],"texts":["The"," user"," wants"," me"," to"," perform"," exact"," steps"," in"," order",":\n","1","."," read"," deleted",".txt","\n","2","."," bash"," rm"," deleted",".txt","\n","3","."," read"," deleted",".txt"," again"," and"," observe"," not","-found"," error","\n","4","."," write"," deleted",".txt"," with"," content"," \"","fresh","\\n","\"\n","5","."," reply"," with"," exactly"," \"","D","ONE","\"\n\n","Let"," me"," do"," step"," ","1"," first","."]}}
+{"type":"assistant/chunk","seq":74,"time":1786259116112,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":75,"time0":1786259116112,"data":{"turn":1,"step":1,"index":1,"dt":[22,1,0,0,0,0,25,0,0,0,21,0],"id":"call_00_vDjxu2gdu87Gj8XZZvba8767","name":"read","args":["","{","\"","file","_path","\"",": ","\"","de","leted",".txt","\"","}"]}}
+{"type":"assistant/chunk","seq":88,"time":1786259116233,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to perform exact steps in order:\n1. read deleted.txt\n2. bash rm deleted.txt\n3. read deleted.txt again and observe not-found error\n4. write deleted.txt with content \"fresh\\n\"\n5. reply with exactly \"DONE\"\n\nLet me do step 1 first."}}}}
+{"type":"assistant/chunk","seq":89,"time":1786259116233,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_vDjxu2gdu87Gj8XZZvba8767","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}}}}
+{"type":"assistant/chunk","seq":90,"time":1786259116233,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":6102,"outputTokens":110,"cacheReadTokens":0,"reasoningTokens":64}}}}
+{"type":"assistant/chunk","seq":91,"time":1786259116233,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":92,"time":1786259116237,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to perform exact steps in order:\n1. read deleted.txt\n2. bash rm deleted.txt\n3. read deleted.txt again and observe not-found error\n4. write deleted.txt with content \"fresh\\n\"\n5. reply with exactly \"DONE\"\n\nLet me do step 1 first."},{"type":"tool-call","id":"call_00_vDjxu2gdu87Gj8XZZvba8767","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"121e3a9b-14bd-491b-817d-5abb0be3f45d"},"usage":{"inputTokens":6102,"outputTokens":110,"cacheReadTokens":0,"reasoningTokens":64}},"sourceEventSeqs":[9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91],"surfaceOp":"append"}
+{"type":"tool/call","seq":93,"time":1786259116238,"data":{"turn":1,"step":1,"callId":"call_00_vDjxu2gdu87Gj8XZZvba8767","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}}
+{"type":"tool/result","seq":94,"time":1786259116249,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_vDjxu2gdu87Gj8XZZvba8767"},"content":[{"type":"tool-result","toolCallId":"call_00_vDjxu2gdu87Gj8XZZvba8767","content":[{"type":"text","text":"<path>{{cwd}}/deleted.txt</path>\n<type>file</type>\n<content>\n1: original\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"role":"user","id":"c3c0fe4a-3c93-433b-990e-1e5963964505"},"meta":{"path":"{{cwd}}/deleted.txt","offset":1,"lines":[{"number":1,"text":"original"}],"totalLines":1}},"sourceEventSeqs":[93],"surfaceOp":"append"}
+{"type":"step/end","seq":95,"time":1786259116249,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":96,"time":1786259116260,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":97,"time":1786259117343,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":98,"time0":1786259117344,"data":{"turn":1,"step":2,"index":0,"dt":[23,1,0,0,1,21,1,0,0,0,47,0,1,1,0,21,1,0,0,1,18,1],"id":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697","name":"bash","args":["","{","\"","command","\"",": ","\"","rm"," deleted",".txt","\"",", ","\"","description","\"",": ","\"","Delete"," deleted",".txt"," file","\"","}"]}}
+{"type":"assistant/chunk","seq":121,"time":1786259117528,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697","name":"bash","arguments":"{\"command\": \"rm deleted.txt\", \"description\": \"Delete deleted.txt file\"}"}}}}
+{"type":"assistant/chunk","seq":122,"time":1786259117528,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":151,"outputTokens":64,"cacheReadTokens":6144,"reasoningTokens":0}}}}
+{"type":"assistant/chunk","seq":123,"time":1786259117528,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":124,"time":1786259117529,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697","name":"bash","arguments":"{\"command\": \"rm deleted.txt\", \"description\": \"Delete deleted.txt file\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"d85f99a5-732d-4127-85d7-cbd7bfa73bb2"},"usage":{"inputTokens":151,"outputTokens":64,"cacheReadTokens":6144,"reasoningTokens":0}},"sourceEventSeqs":[97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123],"surfaceOp":"append"}
+{"type":"tool/call","seq":125,"time":1786259117529,"data":{"turn":1,"step":2,"callId":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697","name":"bash","arguments":"{\"command\": \"rm deleted.txt\", \"description\": \"Delete deleted.txt file\"}"}}
+{"type":"tool/result","seq":126,"time":1786259117553,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697"},"content":[{"type":"tool-result","toolCallId":"call_00_ET_sBOnFnMNrptvzTOpSwBg6697","content":[{"type":"text","text":"(no output)"}],"isError":false}],"role":"user","id":"7a80dfb4-3234-41c5-b276-3384f4198765"}},"sourceEventSeqs":[125],"surfaceOp":"append"}
+{"type":"step/end","seq":127,"time":1786259117553,"data":{"turn":1,"step":2}}
+{"type":"step/start","seq":128,"time":1786259117560,"data":{"turn":1,"step":3}}
+{"type":"assistant/chunk","seq":129,"time":1786259118917,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":130,"time0":1786259118917,"data":{"turn":1,"step":3,"index":0,"dt":[25,2,0,0,0,1,21,1,0,0,27,2],"id":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261","name":"read","args":["","{","\"","file","_path","\"",": ","\"","de","leted",".txt","\"","}"]}}
+{"type":"assistant/chunk","seq":143,"time":1786259119037,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}}}}
+{"type":"assistant/chunk","seq":144,"time":1786259119037,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":101,"outputTokens":46,"cacheReadTokens":6272,"reasoningTokens":0}}}}
+{"type":"assistant/chunk","seq":145,"time":1786259119037,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":146,"time":1786259119038,"data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"c08b2b60-786f-4a74-a826-e2e3aa09e851"},"usage":{"inputTokens":101,"outputTokens":46,"cacheReadTokens":6272,"reasoningTokens":0}},"sourceEventSeqs":[129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145],"surfaceOp":"append"}
+{"type":"tool/call","seq":147,"time":1786259119039,"data":{"turn":1,"step":3,"callId":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261","name":"read","arguments":"{\"file_path\": \"deleted.txt\"}"}}
+{"type":"tool/result","seq":148,"time":1786259119049,"data":{"turn":1,"step":3,"message":{"source":{"kind":"tool","callId":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261"},"content":[{"type":"tool-result","toolCallId":"call_00_ET_pKZS54ZqkXTdxAsdLQR91261","content":[{"type":"text","text":"Error: cannot read \"{{cwd}}/deleted.txt\": not found"}],"isError":true}],"role":"user","id":"660e8735-5bf4-44f8-8835-7aeb70d6a95d"},"error":{"name":"FsError","code":"FS_NOT_FOUND"}},"sourceEventSeqs":[147],"surfaceOp":"append"}
+{"type":"step/end","seq":149,"time":1786259119050,"data":{"turn":1,"step":3}}
+{"type":"step/start","seq":150,"time":1786259119058,"data":{"turn":1,"step":4}}
+{"type":"assistant/chunk","seq":151,"time":1786259120173,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":152,"time0":1786259120174,"data":{"turn":1,"step":4,"index":0,"dt":[108,1,1,0,0,0,1,0,1,0,0,0,1,0,0,0,1,72,0,0,1],"id":"call_00_ET_OqjRZggKy6eetff5jh3V9977","name":"write","args":["","{","\"","file","_path","\"",": ","\"","de","leted",".txt","\"",", ","\"","content","\"",": ","\"","fresh","\\n","\"","}"]}}
+{"type":"assistant/chunk","seq":174,"time":1786259120361,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_00_ET_OqjRZggKy6eetff5jh3V9977","name":"write","arguments":"{\"file_path\": \"deleted.txt\", \"content\": \"fresh\\n\"}"}}}}
+{"type":"assistant/chunk","seq":175,"time":1786259120361,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":79,"outputTokens":63,"cacheReadTokens":6400,"reasoningTokens":0}}}}
+{"type":"assistant/chunk","seq":176,"time":1786259120361,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":177,"time":1786259120362,"data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_00_ET_OqjRZggKy6eetff5jh3V9977","name":"write","arguments":"{\"file_path\": \"deleted.txt\", \"content\": \"fresh\\n\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"de52e93e-d45e-488b-b110-ce10de3387ba"},"usage":{"inputTokens":79,"outputTokens":63,"cacheReadTokens":6400,"reasoningTokens":0}},"sourceEventSeqs":[151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176],"surfaceOp":"append"}
+{"type":"tool/call","seq":178,"time":1786259120363,"data":{"turn":1,"step":4,"callId":"call_00_ET_OqjRZggKy6eetff5jh3V9977","name":"write","arguments":"{\"file_path\": \"deleted.txt\", \"content\": \"fresh\\n\"}"}}
+{"type":"tool/result","seq":179,"time":1786259120381,"data":{"turn":1,"step":4,"message":{"source":{"kind":"tool","callId":"call_00_ET_OqjRZggKy6eetff5jh3V9977"},"content":[{"type":"tool-result","toolCallId":"call_00_ET_OqjRZggKy6eetff5jh3V9977","content":[{"type":"text","text":"<path>{{cwd}}/deleted.txt</path>\n<type>file</type>\n<content>\nCreated file\n</content>"}],"isError":false}],"role":"user","id":"f10e6310-8f96-468b-9837-3068dc8af472"},"meta":{"diffs":[]}},"sourceEventSeqs":[178],"surfaceOp":"append"}
+{"type":"step/end","seq":180,"time":1786259120381,"data":{"turn":1,"step":4}}
+{"type":"step/start","seq":181,"time":1786259120389,"data":{"turn":1,"step":5}}
+{"type":"assistant/chunk","seq":182,"time":1786259121079,"data":{"turn":1,"step":5,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":183,"time":1786259121079,"data":{"turn":1,"step":5,"chunk":{"type":"text-delta","index":0,"text":"D"}}}
+{"type":"assistant/chunk","seq":184,"time":1786259121104,"data":{"turn":1,"step":5,"chunk":{"type":"text-delta","index":0,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":185,"time":1786259121115,"data":{"turn":1,"step":5,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":186,"time":1786259121116,"data":{"turn":1,"step":5,"chunk":{"type":"usage","usage":{"inputTokens":88,"outputTokens":3,"cacheReadTokens":6528,"reasoningTokens":0}}}}
+{"type":"assistant/chunk","seq":187,"time":1786259121116,"data":{"turn":1,"step":5,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":188,"time":1786259121116,"data":{"turn":1,"step":5,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"6c904bc2-55c6-4dfe-85a6-0a5d7d2ad7b4"},"usage":{"inputTokens":88,"outputTokens":3,"cacheReadTokens":6528,"reasoningTokens":0}},"sourceEventSeqs":[182,183,184,185,186,187],"surfaceOp":"append"}
+{"type":"step/end","seq":189,"time":1786259121117,"data":{"turn":1,"step":5}}
+{"type":"turn/end","seq":190,"time":1786259121117,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/acp-agent/tests/snapshots/fs-delete-recreate/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/fs-delete-recreate/stdout.expected.jsonl
new file mode 100644
index 0000000000..82ae8907ca
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/fs-delete-recreate/stdout.expected.jsonl
@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
diff --git a/examples/acp-agent/tests/snapshots/fs-delete-recreate/workspace/deleted.txt b/examples/acp-agent/tests/snapshots/fs-delete-recreate/workspace/deleted.txt
new file mode 100644
index 0000000000..4b48deed3a
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/fs-delete-recreate/workspace/deleted.txt
@@ -0,0 +1 @@
+original
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 90c7931644..4e29843fad 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: b346b4c5bc7bc2888ccd3dc210bb90e0f1cc5965
-README.zh.md: b84b2382c03dc6e422228b19a58aff927e8a5db7
+README.md: 039ad72a9651a1e8907c2c63b8c83d113aedbb4e
+README.zh.md: be97bbd92edb528f9560518398a0cb70f36b992b
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index b346b4c5bc..039ad72a96 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -9,8 +9,8 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 - **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; GNU `realpath -mz` supplies canonical target identity without requiring the final file to exist, and ASCII/base64 plus strict NUL framing preserves newline and multibyte paths across the decoded SDK transport. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam; listings reuse returned metadata and resolve symbolic-link entries sequentially. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
 - **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
-- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the filesystem seam's observed-state semantics.
-- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before rename. The signal is not forwarded into the rename RPC, so cancellation cannot interrupt the atomic commit; a successful rename is the commit point.
+- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, and preserve an existing file's POSIX mode. Replacements publish through E2B's same-filesystem atomic rename. A guarded `createIfAbsent` publishes with remote `ln` instead, making the commit atomically no-replace; metadata read from the staged file before that commit is projected to the target path for the returned version, so no fallible metadata request follows either commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process.
+- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before publication. The signal is not forwarded into the rename or guarded-link commit, so cancellation cannot interrupt atomic publication or turn a committed write into a reported failure.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
 
@@ -25,7 +25,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **No host synchronization** — an empty E2B cwd stays empty until a tool, command, or external process populates it; local files are neither uploaded nor reflected back.
-- **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
+- **Mutation coordination is host-process-local** — `createIfAbsent` preserves a remote creator racing publication, but another harness connection or command can still race replacement; version guards detect only metadata changes represented by E2B.
 - **Reads reopen canonical targets by path** — a concurrent remote path replacement between resolution and stream opening is not fenced by a stable file handle; no observed product defect justifies a provider-specific bounded-read protocol in this POC.
 - **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
 - **The POC targets E2B's default Linux image** — it relies on GNU `realpath`/`base64`/`chmod`, same-filesystem rename, streaming reads, and metadata extended attributes; custom templates are outside this POC.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index b84b2382c0..be97bbd92e 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -9,8 +9,8 @@
 - **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；GNU `realpath -mz` 提供规范化目标身份，且不要求最终文件存在；ASCII/base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam；目录列表会复用已返回的元数据，并依次解析符号链接条目。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
 - **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
-- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留文件系统 seam 的已观察状态语义。
-- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在 rename 前立即检查。信号不会传入 rename RPC，因此取消无法中断原子提交；成功 rename 是提交点。
+- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，并保留现有文件的 POSIX mode。替换操作通过 E2B 的同一文件系统原子重命名发布。带防护的 `createIfAbsent` 改用远程 `ln` 发布，使提交具备原子且不替换的语义；系统会把提交前从暂存文件读取的元数据投影到目标路径，以生成返回的版本，因此任何一类提交点之后都不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。
+- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在发布前立即检查。信号不会传入 rename 或防护链接提交，因此取消无法中断原子发布，也不会把已提交的写入报告为失败。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
 
@@ -25,7 +25,7 @@
 ## 已知限制与延后工作
 
 - **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令或外部进程填充它；本地文件既不会上传，也不会同步回本地。
-- **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
+- **变更协调仅限宿主进程内**：`createIfAbsent` 会保留与发布发生竞态的远程创建者所写入的文件，但另一个 harness 连接或命令仍可能与替换操作发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
 - **读取会按路径重新打开规范化目标**：在解析与打开流之间若并发替换远程路径，该操作没有稳定文件句柄提供围栏；在该 POC 中，没有已观察到的产品缺陷能够证明提供方专用的有界读取协议值得引入。
 - **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
 - **该 POC 面向 E2B 默认 Linux 镜像**：它依赖 GNU `realpath`／`base64`／`chmod`、同一文件系统内的 rename、流式读取和元数据扩展属性；自定义模板不在该 POC 范围内。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 83ff7bd99b..04b23a6775 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -332,7 +332,13 @@ export class E2BFileSystem extends FileSystem {
       }
       this.checkWriteIntent(existing, expected, target)
       const before = existing === undefined ? null : await this.readForDiff(target, signal)
-      const version = await this.writeAtomic(target, content, existing, signal)
+      const version = await this.writeAtomic(
+        target,
+        content,
+        existing,
+        expected?.kind === 'createIfAbsent',
+        signal,
+      )
       return {
         operation: existing === undefined ? 'create' : 'update',
         version,
@@ -363,7 +369,7 @@ export class E2BFileSystem extends FileSystem {
       const before = normalizeLineEndings(raw)
       const after = literalEdit(before, edit, target.displayPath)
       const storage = restoreLineEndings(after, detectsCrlf(raw))
-      const version = await this.writeAtomic(target, storage, existing, signal)
+      const version = await this.writeAtomic(target, storage, existing, false, signal)
       return { version, before, after }
     })
   }
@@ -450,6 +456,7 @@ export class E2BFileSystem extends FileSystem {
     target: FsTarget,
     content: string,
     existing: EntryInfo | undefined,
+    createIfAbsent: boolean,
     signal?: AbortSignal,
   ): Promise<ReturnType<typeof FsVersion>> {
     assertNotAborted(signal, 'write')
@@ -476,7 +483,28 @@ export class E2BFileSystem extends FileSystem {
         commandOpts(signal),
       )
       assertNotAborted(signal, 'write')
-      const committed = await sandbox.files.rename(temporary, targetPath)
+      let committed: EntryInfo
+      if (createIfAbsent) {
+        const staged = await sandbox.files.getInfo(temporary, signalOpts(signal))
+        assertNotAborted(signal, 'write')
+        const targetArg = quoteE2BShellArg(targetPath)
+        const publication = await sandbox.commands.run(
+          `if ln -- ${quoteE2BShellArg(temporary)} ${targetArg}; then printf created; elif test -e ${targetArg} || test -L ${targetArg}; then printf exists; else exit 1; fi`,
+          commandOpts(undefined),
+        )
+        if (publication.stdout === 'exists') {
+          throw new FsError(
+            `cannot overwrite existing "${target.displayPath}" without reading it first`,
+            'FS_NOT_OBSERVED',
+          )
+        }
+        if (publication.stdout !== 'created') {
+          throw new Error('guarded create returned an invalid publication result')
+        }
+        committed = { ...staged, name: posix.basename(targetPath), path: targetPath }
+      } else {
+        committed = await sandbox.files.rename(temporary, targetPath)
+      }
       try {
         await sandbox.files.remove(stagingDirectory)
       } catch (_committedStagingCleanupFailure) {
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 9cad00b6eb..973cf7c5c8 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -37,6 +37,7 @@ class FakeRemote {
   readonly writes: Array<{ path: string; data: string; metadata?: Record<string, string> }> = []
   readonly writeParentModes: number[] = []
   readonly renames: Array<{ from: string; to: string }> = []
+  readonly links: Array<{ from: string; to: string }> = []
   readonly removals: string[] = []
   readonly commands: string[] = []
   streamChunks: Uint8Array[] | undefined
@@ -51,6 +52,8 @@ class FakeRemote {
   nextRemoveError: unknown
   canonicalOutput: string | undefined
   abortAfterRename: AbortController | undefined
+  competitorBeforeLink: { path: string; data: string } | undefined
+  guardedLinkOutput: string | undefined
   disappearOnInfo = new Set<string>()
   private clock = 1
 
@@ -253,6 +256,28 @@ class FakeRemote {
         }
         const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
         if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
+        const guardedLink = new RegExp(
+          "^if ln -- '([^']+)' '([^']+)'; then printf created; "
+          + "elif test -e '[^']+' \\|\\| test -L '[^']+'; then printf exists; else exit 1; fi$",
+        ).exec(command)
+        if (guardedLink !== null) {
+          const from = guardedLink[1]!
+          const to = guardedLink[2]!
+          if (this.guardedLinkOutput !== undefined) {
+            const stdout = this.guardedLinkOutput
+            this.guardedLinkOutput = undefined
+            return { exitCode: 0, stdout, stderr: '' }
+          }
+          if (this.competitorBeforeLink?.path === to) {
+            this.file(to, this.competitorBeforeLink.data)
+            this.competitorBeforeLink = undefined
+          }
+          if (this.nodes.has(to)) return { exitCode: 0, stdout: 'exists', stderr: '' }
+          this.nodes.set(to, this.required(from))
+          this.links.push({ from, to })
+          this.abortAfterRename?.abort('after commit')
+          return { exitCode: 0, stdout: 'created', stderr: '' }
+        }
         const move = /^mv -f -- '([^']+)' '([^']+)'$/.exec(command)
         if (move !== null) {
           if (this.nextRenameError !== undefined) {
@@ -475,6 +500,7 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(remote.nodes.get('/workspace/new.txt')?.mode).toBe(0o600)
     expect(remote.nodes.get('/workspace/new.txt')?.metadata?.['dsh-version']).toBeDefined()
     expect(remote.writeParentModes).toEqual([0o700])
+    expect(remote.links).toHaveLength(1)
     const stagingDirectory = posix.dirname(remote.writes[0]!.path)
     expect(posix.dirname(stagingDirectory)).toBe('/workspace')
     expect(remote.removals).toContain(stagingDirectory)
@@ -527,6 +553,33 @@ describe('E2BFileSystem atomic writes and edits', () => {
     await expectCode(fs.writeText(await fs.resolve('dir'), 'x'), 'FS_NOT_REGULAR_FILE')
   })
 
+  it('preserves a competitor created after the guarded-create probe', async () => {
+    const remote = new FakeRemote()
+    remote.competitorBeforeLink = { path: '/workspace/race.txt', data: 'competitor' }
+    const { fs } = await setup(remote)
+
+    await expectCode(
+      fs.writeText(await fs.resolve('race.txt'), 'ours', { kind: 'createIfAbsent' }),
+      'FS_NOT_OBSERVED',
+    )
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/race.txt')?.data)).toBe('competitor')
+    expect(remote.links).toHaveLength(0)
+    expect(remote.removals).toHaveLength(1)
+  })
+
+  it('rejects an invalid guarded-create publication response before claiming success', async () => {
+    const remote = new FakeRemote()
+    remote.guardedLinkOutput = 'unexpected'
+    const { fs } = await setup(remote)
+
+    await expectCode(
+      fs.writeText(await fs.resolve('invalid.txt'), 'ours', { kind: 'createIfAbsent' }),
+      'FS_IO_ERROR',
+    )
+    expect(remote.nodes.has('/workspace/invalid.txt')).toBe(false)
+    expect(remote.removals).toHaveLength(1)
+  })
+
   it('does not turn an abort observed after a successful move into a failed write', async () => {
     const remote = new FakeRemote()
     const controller = new AbortController()
@@ -537,6 +590,20 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(controller.signal.aborted).toBe(true)
   })
 
+  it('does not turn an abort observed after a guarded create into a failed write', async () => {
+    const remote = new FakeRemote()
+    const controller = new AbortController()
+    remote.abortAfterRename = controller
+    const { fs } = await setup(remote)
+    await expect(fs.writeText(
+      await fs.resolve('committed-create'),
+      'yes',
+      { kind: 'createIfAbsent' },
+      controller.signal,
+    )).resolves.toMatchObject({ operation: 'create' })
+    expect(controller.signal.aborted).toBe(true)
+  })
+
   it('does not turn post-commit staging cleanup failure into a failed write', async () => {
     const remote = new FakeRemote()
     remote.nextRemoveError = new Error('empty staging cleanup failed')
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index dd384cd2b1..6aaf691eef 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-local/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/fs/fs-local/README.md
-README.md: ec0cffea1c82ab3bb2485fcb22ac5339d5d2a0d9
-README.zh.md: 99adba8c8b58f1f0b6f0f5ab8b672eb074b38f31
+README.md: ac2f271ad9651797e1aceeba49e7a52533405f10
+README.zh.md: 633d55fe06b2261d9d5b52184987811c87c8f155
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index ec0cffea1c..ac2f271ad9 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -19,7 +19,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
 - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` decodes chunks so a huge file need not be held whole in memory and consumers can enforce their own retention bounds. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
-- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
+- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, then fsyncs and publishes. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` hard-links the staged file into place as an atomic no-replace publication, so a file created after the initial probe is preserved and rejected with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
 
 The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
@@ -39,4 +39,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **Version tokens depend on filesystem metadata** — they combine device, inode, size, nanosecond mtime, and nanosecond ctime; a storage layer that cannot update any of those facts for a rewrite can still defeat the stale guard.
 - **`editText` holds the whole file (plus the edited copy) in memory** — streaming exists only on the read path.
 - **Binary detection is asymmetric** — reads NUL-sample only the first 8192 bytes while edits scan the whole buffer, so a file with a late NUL reads fine but rejects edits.
-- **The per-target mutation lock is in-process only** — a writer in another process is caught only by the optional version guard, never serialized.
+- **The per-target mutation lock is in-process only** — guarded create still uses an atomic no-replace publication across processes, but replacement writers in another process are caught only when the optional version guard observes their metadata change; they are never serialized.
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 99adba8c8b..633d55fe06 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -19,7 +19,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此飞行中的中止会报告 `FS_ABORTED`，而非陈旧的不存在结果。
 - **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片解码，因此超大文件无需整体保存在内存中，消费方也可以执行各自的保留上限。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑。
 - **`listDir`**：按稳定的 `name.localeCompare()` 顺序列出一层目录。每个条目携带子项 basename、类型、解析后的子目标（`displayPath` 位于所列目录下，`targetKey` 是 realpath 身份）和低成本 stat 元数据（`version`，普通文件另有 `size`）。它绝不会打开或解码文件内容。缺失目标报告 `FS_NOT_FOUND`，文件/特殊文件目标报告 `FS_NOT_DIRECTORY`，已中止调用报告 `FS_ABORTED`，权限失败报告 `FS_PERMISSION_DENIED`，其他列出或子项元数据 I/O 失败报告 `FS_IO_ERROR`。损坏/消失的子项以无元数据的 `other` 返回，但解析子项时出现权限/I/O 失败会让整个列表以结构化 `FsError` 失败。
-- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内。完成写入和 fsync 后，以 rename 覆盖目标。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 创建缺失目标并拒绝现有目标（`FS_NOT_OBSERVED`）；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
+- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内，随后执行 fsync 并发布。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 通过硬链接把暂存文件发布到目标位置，以实现原子且不替换的发布，因此初始探测后创建的文件会被保留，并以 `FS_NOT_OBSERVED` 拒绝本次写入；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
 - **`editText`**：在同一原语之上依次执行原子的字面量读取、修改和写入，并通过变更锁按目标串行化。`expected` 防护是可选的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
 
 包根 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
@@ -39,4 +39,4 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **版本 token 依赖文件系统元数据**：它们组合设备、inode、大小、纳秒级 mtime 和纳秒级 ctime；如果存储层在重写时无法更新其中任何一项事实，仍可能绕过陈旧防护。
 - **`editText` 会把整个文件及编辑后的副本保存在内存中**：只有读取路径支持流式处理。
 - **二进制检测不对称**：读取只对前 8192 字节执行 NUL 采样，编辑则扫描整个 buffer，因此 NUL 出现在后部的文件可以读取，但编辑会被拒绝。
-- **每目标变更锁仅限进程内**：其他进程中的写入方只会被可选版本防护发现，绝不会被串行化。
+- **每目标变更锁仅限进程内**：即使跨进程，带防护的创建仍采用原子且不替换的发布方式；但只有当可选版本防护观察到元数据变化时，系统才能发现其他进程中的替换写入方，且绝不会将其串行化。
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 7e063ca347..071ad31637 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -1,13 +1,13 @@
 /**
  * Cordis-free local filesystem mechanics. This provider layer returns validated UTF-8 text,
  * streams large files, and rejects binary data; line windows belong to `dsh-tool-fs`. Writes
- * stage an exclusive owner-only file in a private sibling directory and atomically rename it.
+ * stage an exclusive owner-only file in a private sibling directory and atomically publish it.
  * @module @deepseek-ai/dsh-fs-local/fsio
  */
 
 import { randomUUID } from 'node:crypto'
 import { createReadStream } from 'node:fs'
-import { chmod, lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
+import { chmod, link, lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
 import type { BigIntStats, Dirent, Stats } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { TextDecoder } from 'node:util'
@@ -20,6 +20,10 @@ function isENOENT(error: unknown): boolean {
   return error instanceof Error && 'code' in error && error.code === 'ENOENT'
 }
 
+function isEEXIST(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'EEXIST'
+}
+
 /**
  * A path component that is expected to be a directory is a regular file (e.g.
  * resolving `afile/child.txt` when `afile` is a file). Like `ENOENT`, the target
@@ -85,7 +89,9 @@ export interface FsIoInternals {
   copyFileDacl?: (source: string, destination: string) => Promise<void>
   /** Override the Win32 security-preserving replacement boundary. */
   replaceFile?: (replaced: string, replacement: string) => Promise<void>
-  /** Test hook after the temp file is written/synced but before final chmod+rename. */
+  /** Override the hard-link no-replace publication boundary. */
+  linkFile?: (existingPath: string, newPath: string) => Promise<void>
+  /** Test hook after the temp file is written/synced but before final chmod+publication. */
   inspectTemp?: (paths: { stagingDir: string; tempPath: string }) => void | Promise<void>
 }
 
@@ -426,8 +432,10 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
  * @param content - the full UTF-8 text to write.
  * @param mode - existing destination's POSIX mode to preserve, or `undefined` for a new file;
  * inert as a mode on Windows but identifies replacement security semantics.
- * @param signal - cancellation checked before the final rename.
+ * @param signal - cancellation checked before final publication.
  * @param internals - Test hook for pinning temp names and observing the staged file.
+ * @param createIfAbsent - publish with a hard-link no-replace primitive; a
+ *   concurrent creator is preserved and rejected with `FS_NOT_OBSERVED`.
  */
 export async function writeFileAtomic(
   absolutePath: string,
@@ -435,6 +443,7 @@ export async function writeFileAtomic(
   mode: number | undefined,
   signal: AbortSignal | undefined,
   internals: FsIoInternals = {},
+  createIfAbsent = false,
 ): Promise<void> {
   throwIfAborted(signal, 'write')
   const directory = dirname(absolutePath)
@@ -448,6 +457,7 @@ export async function writeFileAtomic(
   const platform = internals.platform ?? process.platform
   const copyFileDacl = internals.copyFileDacl ?? copyFileDaclWin32
   const replaceFile = internals.replaceFile ?? replaceFileWin32
+  const linkFile = internals.linkFile ?? link
   let handle: Awaited<ReturnType<typeof open>> | undefined
   let stagingCreated = false
   try {
@@ -468,7 +478,18 @@ export async function writeFileAtomic(
     handle = undefined
 
     throwIfAborted(signal, 'write')
-    if (platform === 'win32' && mode !== undefined) {
+    if (createIfAbsent) {
+      try {
+        await linkFile(tempPath, absolutePath)
+      } catch (error: unknown) {
+        if (!isEEXIST(error)) throw error
+        throw new FsError(
+          `cannot overwrite existing "${absolutePath}" without reading it first`,
+          'FS_NOT_OBSERVED',
+          { cause: error },
+        )
+      }
+    } else if (platform === 'win32' && mode !== undefined) {
       try {
         await replaceFile(absolutePath, tempPath)
       } catch (error: unknown) {
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 6f9af5cec2..6be6a4402b 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -167,7 +167,14 @@ export class LocalFileSystem extends FileSystem {
       // Preserve prior text for contextual diffs; null falls back to a whole-file diff.
       // TODO(overwrite-diff-bound): cap this UI-only pre-read for large files.
       const before = existing ? await readTextForDiff(target.targetKey, signal) : null
-      await writeFileAtomic(target.targetKey, content, existing?.mode, signal, this.internals)
+      await writeFileAtomic(
+        target.targetKey,
+        content,
+        existing?.mode,
+        signal,
+        this.internals,
+        expected?.kind === 'createIfAbsent',
+      )
       const after = await probe(target.targetKey)
       return {
         operation: existing ? 'update' : 'create',
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index ee3abeebb8..531be25360 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -298,6 +298,16 @@ describe('writeText', () => {
     expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('old')
   })
 
+  it('createIfAbsent preserves a competitor created after the initial probe', async () => {
+    const path = join(dir, 'a.txt')
+    const target = await fs.resolve('a.txt')
+    fs.internals.inspectTemp = async () => { await writeFile(path, 'competitor') }
+
+    await expect(fs.writeText(target, 'ours', { kind: 'createIfAbsent' }))
+      .rejects.toMatchObject({ code: 'FS_NOT_OBSERVED' })
+    expect(await readFile(path, 'utf8')).toBe('competitor')
+  })
+
   it('replaceIfVersion replaces when the version matches', async () => {
     await writeFile(join(dir, 'a.txt'), 'old')
     const target = await fs.resolve('a.txt')
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index ed30b896bf..9b62caba3f 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -496,6 +496,17 @@ describe('writeFileAtomic — temp-file safety', () => {
     expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
   })
 
+  it('surfaces a non-collision guarded-create publication failure and cleans staging', async () => {
+    const file = join(dir, 'a.txt')
+    const denied = Object.assign(new Error('link denied'), { code: 'EACCES' })
+
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      linkFile: async () => { throw denied },
+    }, true)).rejects.toBe(denied)
+    await expect(stat(file)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
+  })
+
   it.skipIf(!posixModes)('creates new files owner-only by default', async () => {
     const file = join(dir, 'a.txt')
     await writeFileAtomic(file, 'hello', undefined, undefined)
diff --git a/packages/fs/fs-policy/README.i18n.yaml b/packages/fs/fs-policy/README.i18n.yaml
index c2b72c65c8..e316171061 100644
--- a/packages/fs/fs-policy/README.i18n.yaml
+++ b/packages/fs/fs-policy/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/fs/fs-policy/README.md
-README.md: bf6486f6f7fe574b576a71b430be91031f7805d2
-README.zh.md: 2e38d63d8e310c7f22b764d46cbec0c82ffb96cf
+README.md: 0166690c66f38efe817d8b5779db9a677d22d321
+README.zh.md: 26e0199e6deb7fc12a860ab01884b70c1b7c9b38
diff --git a/packages/fs/fs-policy/README.md b/packages/fs/fs-policy/README.md
index bf6486f6f7..0166690c66 100644
--- a/packages/fs/fs-policy/README.md
+++ b/packages/fs/fs-policy/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **fs-policy plugin**: it adds observed-state, read-before-edit, and version-guarded write/edit on top of the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)) — through the `fs/*` event gate, **NOT** through a method service. This plugin registers **no** `ctx.fsPolicy` service and has no public `read`/`write`/`edit`/`resolve` methods. It is the policy third of the filesystem stack: not a swappable seam, but the policy that does not belong on the `FileSystem` provider base class.
+The **fs-policy plugin**: it records observed presence or absence and adds read-before-edit plus guarded write/edit on top of the `ctx.fs` provider contract ([`@deepseek-ai/dsh-fs`](../fs)) — through the `fs/*` event gate, **NOT** through a method service. This plugin registers **no** `ctx.fsPolicy` service and has no public `read`/`write`/`edit`/`resolve` methods. It is the policy third of the filesystem stack: not a swappable seam, but the policy that does not belong on the `FileSystem` provider base class.
 
 ```ts
 import type { Context } from 'cordis'
@@ -33,13 +33,13 @@ Three `fs/*` events (declared by `@deepseek-ai/dsh-fs`, dispatched by `@deepseek
 
 | Event | This plugin's listener |
 |---|---|
-| `fs/write-intent` | No prior observation → `{ kind: 'createIfAbsent' }`; a prior observation → `{ kind: 'replaceIfVersion', version: vObserved }`. Single-slot decision; does NOT call `next()`. |
-| `fs/edit-intent` | Requires a prior observation by this owner (else throws `FS_NOT_OBSERVED`); returns `{ version: vObserved }` as the CAS basis. Single-slot decision; does NOT call `next()`. |
-| `fs/observed` | Records `{ version }` for this owner+target. Synchronous, side-effect-only `WeakMap.set`. |
+| `fs/write-intent` | Unseen or observed absent → `{ kind: 'createIfAbsent' }`; observed present → `{ kind: 'replaceIfVersion', version: vObserved }`. Single-slot decision; does NOT call `next()`. |
+| `fs/edit-intent` | Unseen → `FS_NOT_OBSERVED`; observed absent → `FS_NOT_FOUND`; observed present → `{ version: vObserved }` as the CAS basis. Single-slot decision; does NOT call `next()`. |
+| `fs/observed` | Records `{ kind: 'present', version }` or `{ kind: 'absent' }` for this owner+target. Synchronous, side-effect-only `WeakMap.set`. |
 
 ## Observed state is the prior-observation record; freshness is provider CAS
 
-Observed state is a weak owner-to-target version map updated after every successful read or mutation; presence alone is the prior-observation record. The plugin performs no filesystem I/O: it supplies the observed version to the provider's atomic mutation guard. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
+Observed state is a weak owner-to-target map with three logical states: unseen, confirmed absent, or present at a version. A successful file read or mutation records presence; a `read`/`view` metadata miss records absence before returning `FS_NOT_FOUND`. The plugin performs no filesystem I/O: it converts that state into a provider guard. Presence supplies the observed version, while absence lets only a `createIfAbsent` write proceed; edit has no version basis and returns `FS_NOT_FOUND`. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
 
 ## Single-slot, first-wins
 
@@ -55,7 +55,7 @@ Because the plugin influences the world only through events, removing it does no
 
 #### What the model sees
 
-This plugin adds no prompt or schema. It rejects an edit without a prior read with code `FS_NOT_OBSERVED` and exact message `edit requires reading "<path>" first`. Guarded mutations whose observed version is stale propagate the provider-owned `FS_STALE_VERSION` error. [`dsh-tool-fs`](../tool-fs/README.md) owns the model-facing error wrapper, which appends the recovery instruction to `FS_STALE_VERSION` (`— re-read the file, then retry`) and `FS_NOT_OBSERVED` (`— read the file, then retry`) messages while preserving the code; observation state is never shown.
+This plugin adds no prompt or schema. It rejects an edit without a prior observation with code `FS_NOT_OBSERVED` and exact message `edit requires reading "<path>" first`; editing a target just observed absent returns `FS_NOT_FOUND`. Guarded mutations whose positive observation is stale propagate the provider-owned `FS_STALE_VERSION` error. [`dsh-tool-fs`](../tool-fs/README.md) owns the model-facing error wrapper, which appends the recovery instruction to `FS_STALE_VERSION` (`— re-read the file, then retry`) and `FS_NOT_OBSERVED` (`— read the file, then retry`) messages while preserving the code. Following the stale remedy on an externally deleted target now records absence: the next guarded write may recreate it with `createIfAbsent`, while the provider atomically preserves any concurrent creator.
 
 #### Token effect
 
diff --git a/packages/fs/fs-policy/README.zh.md b/packages/fs/fs-policy/README.zh.md
index 2e38d63d8e..26e0199e6d 100644
--- a/packages/fs/fs-policy/README.zh.md
+++ b/packages/fs/fs-policy/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**fs-policy 插件**：它在 `ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）之上增加已观察状态、编辑前读取和版本防护的写入/编辑；它通过 `fs/*` 事件门禁参与，**不是**通过方法服务。该插件**不**注册 `ctx.fsPolicy` 服务，也没有公开的 `read`/`write`/`edit`/`resolve` 方法。它是文件系统栈的策略层：不是可替换 seam，而是不应位于 `FileSystem` 提供方基类上的策略。
+**fs-policy 插件**：它记录观测到的存在或缺失状态，并在 `ctx.fs` 提供方约定（[`@deepseek-ai/dsh-fs`](../fs)）之上增加编辑前读取和带防护的写入/编辑；它通过 `fs/*` 事件门禁参与，**不是**通过方法服务。该插件**不**注册 `ctx.fsPolicy` 服务，也没有公开的 `read`/`write`/`edit`/`resolve` 方法。它是文件系统栈的政策层：不是可替换 seam，而是不应位于 `FileSystem` 提供方基类上的政策。
 
 ```ts
 import type { Context } from 'cordis'
@@ -33,13 +33,13 @@ await ctx.plugin(FsPolicy)
 
 | 事件 | 本插件的监听器 |
 |---|---|
-| `fs/write-intent` | 先前未观察 → `{ kind: 'createIfAbsent' }`；先前已观察 → `{ kind: 'replaceIfVersion', version: vObserved }`。单槽决策；不调用 `next()`。 |
-| `fs/edit-intent` | 要求该所有者先前已观察，否则抛出 `FS_NOT_OBSERVED`；返回 `{ version: vObserved }` 作为 CAS 基础。单槽决策；不调用 `next()`。 |
-| `fs/observed` | 为该所有者与目标记录 `{ version }`。同步、只有副作用的 `WeakMap.set`。 |
+| `fs/write-intent` | 未见或已观测为缺失 → `{ kind: 'createIfAbsent' }`；已观测为存在 → `{ kind: 'replaceIfVersion', version: vObserved }`。单槽决策；不调用 `next()`。 |
+| `fs/edit-intent` | 未见 → `FS_NOT_OBSERVED`；已观测为缺失 → `FS_NOT_FOUND`；已观测为存在 → 返回 `{ version: vObserved }` 作为 CAS 基础。单槽决策；不调用 `next()`。 |
+| `fs/observed` | 为该所有者与目标记录 `{ kind: 'present', version }` 或 `{ kind: 'absent' }`。同步、只有副作用的 `WeakMap.set`。 |
 
 ## 已观察状态是先前观察记录；新鲜度由提供方 CAS 保证
 
-已观察状态是一张以所有者为弱键、记录各目标版本的映射表，每次读取或变更成功后都会更新；记录存在本身就是先前观察凭据。插件不执行文件系统 I/O：它把观察到的版本提供给提供方的原子变更防护。窗口读取会观察整个文件的版本，因此只有文件保持不变时才允许后续的定向编辑。插件 dispose（资源释放）时会丢弃状态，并且不会跨会话持久化。
+观测状态是一张以所有者为弱键、记录各目标的映射表，具有三种逻辑状态：未见、确认缺失、存在于某个版本。成功读取文件或变更会记录存在；`read`/`view` 的元数据未命中会在返回 `FS_NOT_FOUND` 前记录缺失。插件不执行文件系统 I/O：它把该状态转换为提供方防护。存在状态提供观测到的版本；缺失状态只允许 `createIfAbsent` 写入继续，edit 因没有版本基准而返回 `FS_NOT_FOUND`。窗口读取会观察整个文件的版本，因此只有文件保持不变时才允许后续的定向编辑。插件 dispose（资源释放）时会丢弃状态，并且不会跨会话持久化。
 
 ## 单槽、先到者胜
 
@@ -55,7 +55,7 @@ await ctx.plugin(FsPolicy)
 
 #### 模型看到的内容
 
-该插件不添加提示词或 schema。编辑前未读取时，它会以代码 `FS_NOT_OBSERVED` 和精确消息 `edit requires reading "<path>" first` 拒绝。观察版本陈旧的防护变更会传播由提供方拥有的 `FS_STALE_VERSION` 错误。[`dsh-tool-fs`](../tool-fs/README.md)拥有面向模型的错误包装，会为 `FS_STALE_VERSION` 消息追加恢复指令（`— re-read the file, then retry`）、为 `FS_NOT_OBSERVED` 消息追加恢复指令（`— read the file, then retry`），同时保留错误码；观察状态绝不会显示。
+该插件不添加提示词或 schema。没有先前观测时，它会以代码 `FS_NOT_OBSERVED` 和精确消息 `edit requires reading "<path>" first` 拒绝编辑；编辑刚被观测为缺失的目标会返回 `FS_NOT_FOUND`。正向观测陈旧时，带防护的变更会传播由提供方拥有的 `FS_STALE_VERSION` 错误。[`dsh-tool-fs`](../tool-fs/README.md)拥有面向模型的错误包装，会为 `FS_STALE_VERSION` 消息追加恢复指令（`— re-read the file, then retry`）、为 `FS_NOT_OBSERVED` 消息追加恢复指令（`— read the file, then retry`），同时保留错误码。外部删除目标后，遵循陈旧恢复指令会记录缺失：下一次带防护的写入可以通过 `createIfAbsent` 重新创建该目标，而提供方会以原子方式保留任何并发创建者写入的文件。
 
 #### Token 影响
 
diff --git a/packages/fs/fs-policy/src/index.ts b/packages/fs/fs-policy/src/index.ts
index 3765a7e512..c7feb8c484 100644
--- a/packages/fs/fs-policy/src/index.ts
+++ b/packages/fs/fs-policy/src/index.ts
@@ -1,14 +1,15 @@
 /**
  * Event-only filesystem observation policy; it registers no service. A weak owner/target map
- * records every successful read or mutation, single-slot intent listeners supply that version,
- * and the provider performs the atomic freshness check. Without this plugin, tools retain the
- * bare provider's unconditional mutation behavior. See the package README for composition rules.
+ * records every authoritative presence/absence observation, single-slot intent listeners derive
+ * guards from that state, and the provider performs the atomic freshness/no-clobber check. Without
+ * this plugin, tools retain the bare provider's unconditional mutation behavior. See the package
+ * README for composition rules.
  * @module @deepseek-ai/dsh-fs-policy
  */
 
 import type { Context } from 'cordis'
 import { FsError } from '@deepseek-ai/dsh-fs'
-import type { FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
+import type { FsObservation, FsTarget, FsVersion, FsWriteIntent } from '@deepseek-ai/dsh-fs'
 import type { FsPolicyExec } from './types.ts'
 
 export type { FsPolicyExec } from './types.ts'
@@ -21,9 +22,10 @@ class ObservedStateGate {
   /**
    * Observed-file state, keyed first by the owner object (weakly held, so a
    * collected session frees its state), then by {@link FsTarget.targetKey}. An
-   * entry's PRESENCE is the prior-observation record.
+   * entry's presence is the prior-observation record; its discriminant keeps
+   * confirmed absence distinct from an unseen target.
    */
-  private observed = new WeakMap<object, Map<string, FsVersion>>()
+  private observed = new WeakMap<object, Map<string, FsObservation>>()
 
   /**
    * Derive the observed-state owner from the opaque event actor — normally the
@@ -38,17 +40,17 @@ class ObservedStateGate {
     return (actor as FsPolicyExec | undefined)?.agent?.session
   }
 
-  private get(owner: object, targetKey: string): FsVersion | undefined {
+  private get(owner: object, targetKey: string): FsObservation | undefined {
     return this.observed.get(owner)?.get(targetKey)
   }
 
-  private set(owner: object, targetKey: string, version: FsVersion): void {
+  private set(owner: object, targetKey: string, observation: FsObservation): void {
     let byTarget = this.observed.get(owner)
     if (!byTarget) {
       byTarget = new Map()
       this.observed.set(owner, byTarget)
     }
-    byTarget.set(targetKey, version)
+    byTarget.set(targetKey, observation)
   }
 
   /** Drop all recorded state (HMR safety / disposal). */
@@ -57,33 +59,38 @@ class ObservedStateGate {
   }
 
   /**
-   * Decide the write intent: no prior observation ⇒ `createIfAbsent` (only
-   * new files can be created blindly); a prior observation ⇒ `replaceIfVersion`
-   * at the observed version (existing files replaced only if unchanged).
+   * Decide the write intent: unseen or confirmed absent ⇒ `createIfAbsent`;
+   * confirmed present ⇒ `replaceIfVersion` at the observed version.
    */
   writeIntent(target: FsTarget, actor: object | undefined): FsWriteIntent {
     const owner = this.owner(actor)
     const prior = owner ? this.get(owner, target.targetKey) : undefined
-    return prior ? { kind: 'replaceIfVersion', version: prior } : { kind: 'createIfAbsent' }
+    return prior?.kind === 'present'
+      ? { kind: 'replaceIfVersion', version: prior.version }
+      : { kind: 'createIfAbsent' }
   }
 
   /**
-   * Decide the edit version guard: requires a prior observation by this owner
-   * (else `FS_NOT_OBSERVED`); returns the observed version as the CAS basis.
+   * Decide the edit version guard: unseen rejects with `FS_NOT_OBSERVED`,
+   * confirmed absence rejects with `FS_NOT_FOUND`, and presence supplies the
+   * observed version as the CAS basis.
    */
   editIntent(target: FsTarget, actor: object | undefined): { version: FsVersion } {
     const owner = this.owner(actor)
     const prior = owner ? this.get(owner, target.targetKey) : undefined
-    if (!owner || !prior) {
+    if (!owner || prior === undefined) {
       throw new FsError(`edit requires reading "${target.displayPath}" first`, 'FS_NOT_OBSERVED')
     }
-    return { version: prior }
+    if (prior.kind === 'absent') {
+      throw new FsError(`cannot edit "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+    }
+    return { version: prior.version }
   }
 
-  /** Record a successful read/write/edit: this owner observed this target at this version. */
-  observe(target: FsTarget, version: FsVersion, actor: object | undefined): void {
+  /** Record an authoritative present or absent observation for this owner and target. */
+  observe(target: FsTarget, observation: FsObservation, actor: object | undefined): void {
     const owner = this.owner(actor)
-    if (owner) this.set(owner, target.targetKey, version)
+    if (owner) this.set(owner, target.targetKey, observation)
   }
 }
 
@@ -114,9 +121,10 @@ export function apply(ctx: Context): void {
   // fs/edit-intent: occupy the single decision slot — do not call next().
   ctx.on('fs/edit-intent', (target, actor) => Promise.resolve().then(() => gate.editIntent(target, actor)))
 
-  // fs/observed must remain synchronous and non-throwing: the mutation already succeeded, and
-  // emit does not await promises. WeakMap.set satisfies that contract.
-  ctx.on('fs/observed', (target, version, actor) => {
-    gate.observe(target, version, actor)
+  // fs/observed must remain synchronous and non-throwing: emit does not await
+  // promises, and successful mutations have already committed. WeakMap.set
+  // satisfies that contract for both presence and absence.
+  ctx.on('fs/observed', (target, observation, actor) => {
+    gate.observe(target, observation, actor)
   })
 }
diff --git a/packages/fs/fs-policy/tests/policy.spec.ts b/packages/fs/fs-policy/tests/policy.spec.ts
index 85c6ae0b52..2c977cc3be 100644
--- a/packages/fs/fs-policy/tests/policy.spec.ts
+++ b/packages/fs/fs-policy/tests/policy.spec.ts
@@ -3,7 +3,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
-import type { FsTarget, FsWriteIntent } from '@deepseek-ai/dsh-fs'
+import type { FsObservation, FsTarget, FsWriteIntent } from '@deepseek-ai/dsh-fs'
 import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
 import type { FsPolicyExec } from '@deepseek-ai/dsh-fs-policy'
 
@@ -11,6 +11,8 @@ function target(path: string): FsTarget {
   return { targetKey: FsTargetKey(path), displayPath: path }
 }
 const ownerExec = (session: object): FsPolicyExec => ({ agent: { session } })
+const present = (version: string): FsObservation => ({ kind: 'present', version: FsVersion(version) })
+const absent: FsObservation = { kind: 'absent' }
 
 /** Dispatch the write-intent waterfall with the bare default thunk. */
 function writeIntent(ctx: Context, t: FsTarget, actor: object | undefined): Promise<FsWriteIntent | undefined> {
@@ -64,9 +66,16 @@ describe('write-intent decision', () => {
   it('an observed target decides replaceIfVersion at the observed version', async () => {
     const { ctx } = await setup()
     const exec = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v7'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v7'), exec)
     expect(await writeIntent(ctx, target('a.txt'), exec)).toEqual({ kind: 'replaceIfVersion', version: 'v7' })
   })
+
+  it('a target observed absent decides createIfAbsent', async () => {
+    const { ctx } = await setup()
+    const exec = ownerExec({})
+    ctx.emit('fs/observed', target('a.txt'), absent, exec)
+    expect(await writeIntent(ctx, target('a.txt'), exec)).toEqual({ kind: 'createIfAbsent' })
+  })
 })
 
 describe('edit-intent decision', () => {
@@ -88,16 +97,23 @@ describe('edit-intent decision', () => {
   it('returns the observed version as the CAS basis after an observation', async () => {
     const { ctx } = await setup()
     const exec = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v3'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v3'), exec)
     expect(await editIntent(ctx, target('a.txt'), exec)).toEqual({ version: 'v3' })
   })
+
+  it('rejects editing a target observed absent with FS_NOT_FOUND', async () => {
+    const { ctx } = await setup()
+    const exec = ownerExec({})
+    ctx.emit('fs/observed', target('a.txt'), absent, exec)
+    await expect(editIntent(ctx, target('a.txt'), exec)).rejects.toMatchObject({ code: 'FS_NOT_FOUND' })
+  })
 })
 
 describe('observed-state is the prior-observation record', () => {
   it('a read observation authorizes an in-place write at that version', async () => {
     const { ctx } = await setup()
     const exec = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), exec) // a read
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), exec) // a read
     expect(await writeIntent(ctx, target('a.txt'), exec)).toEqual({ kind: 'replaceIfVersion', version: 'v0' })
   })
 
@@ -105,19 +121,34 @@ describe('observed-state is the prior-observation record', () => {
     const { ctx } = await setup()
     const exec = ownerExec({})
     // A create records v1; the follow-up edit guards against v1 with no read.
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v1'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v1'), exec)
     expect(await editIntent(ctx, target('a.txt'), exec)).toEqual({ version: 'v1' })
     // The edit records v2; a second edit guards against v2.
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v2'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v2'), exec)
     expect(await editIntent(ctx, target('a.txt'), exec)).toEqual({ version: 'v2' })
   })
 
   it('a no-owner observation records nothing', async () => {
     const { ctx } = await setup()
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), undefined)
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), undefined)
     // Still unobserved for any owner.
     await expect(editIntent(ctx, target('a.txt'), ownerExec({}))).rejects.toMatchObject({ code: 'FS_NOT_OBSERVED' })
   })
+
+  it('supports present → absent → present transitions for one owner', async () => {
+    const { ctx } = await setup()
+    const exec = ownerExec({})
+    const a = target('a.txt')
+    ctx.emit('fs/observed', a, present('v1'), exec)
+    expect(await writeIntent(ctx, a, exec)).toEqual({ kind: 'replaceIfVersion', version: 'v1' })
+
+    ctx.emit('fs/observed', a, absent, exec)
+    expect(await writeIntent(ctx, a, exec)).toEqual({ kind: 'createIfAbsent' })
+    await expect(editIntent(ctx, a, exec)).rejects.toMatchObject({ code: 'FS_NOT_FOUND' })
+
+    ctx.emit('fs/observed', a, present('v2'), exec)
+    expect(await editIntent(ctx, a, exec)).toEqual({ version: 'v2' })
+  })
 })
 
 describe('multi-owner isolation', () => {
@@ -125,7 +156,7 @@ describe('multi-owner isolation', () => {
     const { ctx } = await setup()
     const a = ownerExec({})
     const b = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), a)
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), a)
     await expect(editIntent(ctx, target('a.txt'), b)).rejects.toMatchObject({ code: 'FS_NOT_OBSERVED' })
     expect(await editIntent(ctx, target('a.txt'), a)).toEqual({ version: 'v0' })
   })
@@ -134,7 +165,7 @@ describe('multi-owner isolation', () => {
     const { ctx } = await setup()
     const a = ownerExec({})
     const b = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), a) // A observed v0
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), a) // A observed v0
     // B never observed → createIfAbsent; A still holds v0 → replaceIfVersion.
     expect(await writeIntent(ctx, target('a.txt'), b)).toEqual({ kind: 'createIfAbsent' })
     expect(await writeIntent(ctx, target('a.txt'), a)).toEqual({ kind: 'replaceIfVersion', version: 'v0' })
@@ -164,7 +195,7 @@ describe('single-slot, first-wins', () => {
       return Promise.resolve(undefined)
     })
     const exec = ownerExec({})
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), exec)
     await editIntent(ctx, target('a.txt'), exec)
     expect(secondRan).toBe(false)
   })
@@ -186,7 +217,7 @@ describe('disposal releases recorded state (HMR safety)', () => {
     const ctx = new Context()
     const exec = ownerExec({})
     const fiber = await ctx.plugin(FsPolicy)
-    ctx.emit('fs/observed', target('a.txt'), FsVersion('v0'), exec)
+    ctx.emit('fs/observed', target('a.txt'), present('v0'), exec)
     expect(await editIntent(ctx, target('a.txt'), exec)).toEqual({ version: 'v0' })
     await fiber.dispose()
 
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index a77f4c8e04..dabdcacd3c 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: c7c978b7530a9b26e178f164dae61ae60f8f321f
-README.zh.md: 9761fc81bcb160edfc96d42cea45183abcfc087d
+README.md: 2b10614c8bf3d7e4a26c7f3d90dbc127cfec4336
+README.zh.md: e0cbf058bb8d6b52e8c8e5a048cc8b3d757e67d0
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index c7c978b753..2b10614c8b 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -30,14 +30,14 @@ A backend subclasses `FileSystem` and implements eleven primitives.
 | `readText(target, signal?)` | Read the whole regular text file as one decoded string. Owns regular-file checks, UTF-8 decoding, binary/NUL rejection (`FS_NOT_TEXT`). |
 | `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here); consumers that need a byte ceiling enforce it while consuming the stream. |
 | `listDir(target, signal?)` | List direct directory children in stable name order. Returns entry names, entry types, resolved child targets, and cheap metadata (`version`/file `size` when available); never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`. Broken/disappeared children may be returned as `other` without metadata; child permission/IO failures fail the whole listing with the same structured codes. |
-| `writeText(target, content, expected?, signal?)` | Atomic create/replace. `expected` is OPTIONAL: omit ⇒ unconditional create-or-overwrite; supply an `FsWriteIntent` (`createIfAbsent`/`replaceIfVersion`) to guard. |
+| `writeText(target, content, expected?, signal?)` | Atomic create/replace. `expected` is OPTIONAL: omit ⇒ unconditional create-or-overwrite; supply an `FsWriteIntent` (`createIfAbsent`/`replaceIfVersion`) to guard. `createIfAbsent` must perform a no-replace publication so a creator racing the initial probe is preserved. |
 | `editText(target, edit, expected?, signal?)` | Literal edit. `expected` is OPTIONAL: omit ⇒ unconditional edit of the current content; supply `{ version }` to guard (verified BEFORE matching). A missing target reports `FS_STALE_VERSION` either way. Applies and writes atomically — one mutation critical section. |
 
 The mutation runs inside the backend's per-target lock either way, so an unconditional write/edit is still atomic — "unconditional" drops the *version* precondition, not the atomicity.
 
 ## The `fs/*` policy events
 
-This package declares three events (see the generated region of [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
+This package declares three events (see the generated region of [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event carrying an `FsObservation` discriminated union: present with a version or confirmed absent. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
 
 ## A provider contract, not the policy layer
 
@@ -47,7 +47,7 @@ This package declares three events (see the generated region of [filesystem.md](
 
 ## Vocabulary
 
-`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
+`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsObservation` distinguishes `{ kind: 'present', version }` from `{ kind: 'absent' }`, so a policy can separate an unseen target from confirmed absence without performing I/O. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
 
 ## Model Experience
 
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index 9761fc81bc..e0cbf058bb 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -30,14 +30,14 @@
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
 | `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
 | `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
-| `writeText(target, content, expected?, signal?)` | 原子创建/替换。`expected` 是可选的：省略 ⇒ 无条件创建或覆盖；提供 `FsWriteIntent`（`createIfAbsent`/`replaceIfVersion`）⇒ 添加防护。 |
+| `writeText(target, content, expected?, signal?)` | 原子创建/替换。`expected` 是可选的：省略 ⇒ 无条件创建或覆盖；提供 `FsWriteIntent`（`createIfAbsent`/`replaceIfVersion`）⇒ 添加防护。`createIfAbsent` 必须以不替换的方式发布，使初始探测后抢先创建的文件得到保留。 |
 | `editText(target, edit, expected?, signal?)` | 字面量编辑。`expected` 是可选的：省略 ⇒ 无条件编辑当前内容；提供 `{ version }` ⇒ 添加防护，并在匹配之前校验。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。应用和写入以原子方式完成，使用同一个变更临界区。 |
 
 无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
 
 ## `fs/*` 政策事件
 
-本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件，携带 `FsObservation` 可辨识联合：存在并带有版本，或确认缺失。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
 ## 提供方约定，不是政策层
 
@@ -47,7 +47,7 @@
 
 ## 词汇
 
-`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整约定见 `src/types.ts`。
+`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsObservation` 区分 `{ kind: 'present', version }` 与 `{ kind: 'absent' }`，使策略无需执行 I/O 即可分辨未见目标和确认缺失。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整约定见 `src/types.ts`。
 
 ## 模型体验
 
diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts
index b4e3884c3b..0be94dccc4 100644
--- a/packages/fs/fs/src/index.ts
+++ b/packages/fs/fs/src/index.ts
@@ -16,6 +16,7 @@ import type {
   FsEditRequest,
   FsInfo,
   FsPathInfo,
+  FsObservation,
   FsTarget,
   FsVersion,
   FsWriteIntent,
@@ -33,6 +34,7 @@ export type {
   FsDirEntry,
   FsErrorCode,
   FsInfo,
+  FsObservation,
   FsPathInfo,
   FsTarget,
   FsWriteIntent,
@@ -63,14 +65,15 @@ declare module 'cordis' {
      */
     'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
     /**
-     * Record a successful observation. Listeners must be synchronous recorders:
-     * throws fail the tool call and returned promises are not awaited.
-     * @param target - the target that was read/written/edited.
-     * @param version - the version the actor now holds as its observation.
+     * Record an authoritative positive or negative observation. Listeners must
+     * be synchronous recorders: throws fail the tool call and returned promises
+     * are not awaited.
+     * @param target - the target whose presence or absence was observed.
+     * @param observation - present with its version, or confirmed absent.
      * @param actor - the observing tool-execution context; undefined records nothing useful.
      * @mode emit
      */
-    'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
+    'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void
   }
 }
 
@@ -198,7 +201,7 @@ export abstract class FileSystem extends Service {
    * @param target - the resolved target to write.
    * @param content - the full new file content.
    * @param expected - the write intent guarding the write; omit for unconditional.
-   * @param signal - aborts before the atomic rename takes effect.
+   * @param signal - aborts before atomic publication takes effect.
    * @param sandboxPolicy - the per-call mode and workspace root this write
    *   runs under; a sandboxing backend fences the write by it, the bare backend
    *   ignores it. Omit to leave the backend its own default.
@@ -219,7 +222,7 @@ export abstract class FileSystem extends Service {
    * @param target - the resolved target to edit.
    * @param edit - the literal search/replace request.
    * @param expected - the version guard; omit for an unconditional edit.
-   * @param signal - aborts before the atomic rename takes effect.
+   * @param signal - aborts before atomic publication takes effect.
    * @param sandboxPolicy - the per-call mode and workspace root this edit runs
    *   under; a sandboxing backend fences the edit by it, the bare backend
    *   ignores it. Omit to leave the backend its own default.
diff --git a/packages/fs/fs/src/invariant.ts b/packages/fs/fs/src/invariant.ts
index 429c1cec41..62fec9a53c 100644
--- a/packages/fs/fs/src/invariant.ts
+++ b/packages/fs/fs/src/invariant.ts
@@ -2,7 +2,7 @@
 
 import type { Context } from 'cordis'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-import type { FsTarget, FsVersion } from './types.ts'
+import type { FsObservation, FsTarget } from './types.ts'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-fs'
 
@@ -24,8 +24,17 @@ const install: InvariantInstaller = (ctx, fail) => {
       && eventName !== 'fs/edit-intent'
       && eventName !== 'fs/observed') return
     validateTarget(args[0] as FsTarget, fail)
-    if (eventName === 'fs/observed' && (args[1] as FsVersion).length === 0) {
-      fail('fs/observed version must be non-empty')
+    if (eventName === 'fs/observed') {
+      const observation = args[1] as FsObservation
+      switch (observation.kind) {
+        case 'present':
+          if (observation.version.length === 0) fail('fs/observed present version must be non-empty')
+          break
+        case 'absent':
+          break
+        default:
+          fail('fs/observed kind must be present or absent')
+      }
     }
   }, { global: true })
 }
diff --git a/packages/fs/fs/src/types.ts b/packages/fs/fs/src/types.ts
index 6a34f3848f..e842d0d574 100644
--- a/packages/fs/fs/src/types.ts
+++ b/packages/fs/fs/src/types.ts
@@ -44,6 +44,15 @@ export function FsVersion(v: string): FsVersion {
   return v as FsVersion
 }
 
+/**
+ * One authoritative observation of a target. A present observation carries the
+ * version used by guarded replacement; an absent observation authorizes only a
+ * guarded create, never an edit.
+ */
+export type FsObservation =
+  | { readonly kind: 'present'; readonly version: FsVersion }
+  | { readonly kind: 'absent' }
+
 /**
  * A path resolved by a backend into a stable identity. `resolve()` produces
  * this; every other operation takes it.
diff --git a/packages/fs/fs/tests/invariant.spec.ts b/packages/fs/fs/tests/invariant.spec.ts
index c160e3d238..eecdea8766 100644
--- a/packages/fs/fs/tests/invariant.spec.ts
+++ b/packages/fs/fs/tests/invariant.spec.ts
@@ -28,17 +28,28 @@ describe('filesystem invariants', () => {
       ctx as never, 'fs/edit-intent', target(), undefined,
       () => Promise.resolve(undefined),
     )).resolves.toBeUndefined()
-    expect(() => { ctx.emit('fs/observed', target(), FsVersion('v1'), undefined) }).not.toThrow()
+    expect(() => {
+      ctx.emit('fs/observed', target(), { kind: 'present', version: FsVersion('v1') }, undefined)
+    }).not.toThrow()
+    expect(() => { ctx.emit('fs/observed', target(), { kind: 'absent' }, undefined) }).not.toThrow()
     expect(() => { ctx.emit('tools/change') }).not.toThrow()
   })
 
   it('rejects empty target and version identities', async () => {
     const ctx = await setup()
-    expect(() => { ctx.emit('fs/observed', target(''), FsVersion('v1'), undefined) })
+    expect(() => {
+      ctx.emit('fs/observed', target(''), { kind: 'present', version: FsVersion('v1') }, undefined)
+    })
       .toThrow(/targetKey must be non-empty/)
-    expect(() => { ctx.emit('fs/observed', target('file:1', ''), FsVersion('v1'), undefined) })
+    expect(() => {
+      ctx.emit('fs/observed', target('file:1', ''), { kind: 'present', version: FsVersion('v1') }, undefined)
+    })
       .toThrow(/displayPath must be non-empty/)
-    expect(() => { ctx.emit('fs/observed', target(), FsVersion(''), undefined) })
-      .toThrow(/version must be non-empty/)
+    expect(() => {
+      ctx.emit('fs/observed', target(), { kind: 'present', version: FsVersion('') }, undefined)
+    }).toThrow(/present version must be non-empty/)
+    expect(() => {
+      ctx.emit('fs/observed', target(), { kind: 'unknown' } as never, undefined)
+    }).toThrow(/kind must be present or absent/)
   })
 })
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index f6f036b33c..a301417b4b 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md
-README.md: c9375a3ee803db48c547c7553d10f9b5ebde3fd2
-README.zh.md: 70ff15f2beff2674719f3084594e5cc0c7309f68
+README.md: 6878584b72c3e799ca8a46ddc6fc2908f9bc3acf
+README.zh.md: d8e92d96c60d30ec4aa943b77b882517324c4e52
diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md
index c9375a3ee8..6878584b72 100644
--- a/packages/fs/tool-fs/README.md
+++ b/packages/fs/tool-fs/README.md
@@ -108,7 +108,7 @@ Prefix-stable while the visible tool definitions and order are unchanged. Regist
 
 #### What the model sees
 
-A successful read is exactly `<path><displayPath></path>`, newline, `<type>file</type>`, newline, `<content>`, numbered lines as `<lineNumber>: <text>`, a blank line, one footer, and `</content>`. The footer is exactly `(Output capped. Showing lines <start>-<end>. Use offset=<next> to continue.)`, `(Showing lines <start>-<end> of <total>. Use offset=<next> to continue.)`, or `(End of file - total <total> lines)`. A long line ends exactly `... (line truncated to <max> chars)`.
+A successful read is exactly `<path><displayPath></path>`, newline, `<type>file</type>`, newline, `<content>`, numbered lines as `<lineNumber>: <text>`, a blank line, one footer, and `</content>`. The footer is exactly `(Output capped. Showing lines <start>-<end>. Use offset=<next> to continue.)`, `(Showing lines <start>-<end> of <total>. Use offset=<next> to continue.)`, or `(End of file - total <total> lines)`. A long line ends exactly `... (line truncated to <max> chars)`. A missing read still returns `FS_NOT_FOUND`, but it records confirmed absence for the calling session; after an externally deleted file is re-read, a retried `write` can safely recreate it through the provider's no-replace guard.
 
 #### Token effect
 
@@ -136,7 +136,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-Failures are normalized as `Error: <message>`. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, and `offset <offset> is out of range for "<path>" (<total> lines)`; provider and policy templates are quoted in their package READMEs. Guarded-mutation failures additionally carry their recovery instruction in the message, appended by this package's model-facing error wrapper: `FS_STALE_VERSION` (including a missing edit target) gets `— re-read the file, then retry`, `FS_NOT_OBSERVED` gets `— read the file, then retry`; the structured code is preserved.
+Failures are normalized as `Error: <message>`. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, and `offset <offset> is out of range for "<path>" (<total> lines)`; provider and policy templates are quoted in their package READMEs. Guarded-mutation failures additionally carry their recovery instruction in the message, appended by this package's model-facing error wrapper: `FS_STALE_VERSION` gets `— re-read the file, then retry`, and `FS_NOT_OBSERVED` gets `— read the file, then retry`; the structured code is preserved. After that reread confirms absence, edit reports `FS_NOT_FOUND` instead of repeating a stale remedy, while write uses guarded creation.
 
 #### Token effect
 
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index 70ff15f2be..d8e92d96c6 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -108,7 +108,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 #### 模型看到的内容
 
-成功读取结果精确为 `<path><displayPath></path>`、换行、`<type>file</type>`、换行、`<content>`、形如 `<lineNumber>: <text>` 的编号行、一个空行、一条 footer 和 `</content>`。footer 精确为 `(Output capped. Showing lines <start>-<end>. Use offset=<next> to continue.)`、`(Showing lines <start>-<end> of <total>. Use offset=<next> to continue.)` 或 `(End of file - total <total> lines)`。长行结尾精确为 `... (line truncated to <max> chars)`。
+成功读取结果精确为 `<path><displayPath></path>`、换行、`<type>file</type>`、换行、`<content>`、形如 `<lineNumber>: <text>` 的编号行、一个空行、一条 footer 和 `</content>`。footer 精确为 `(Output capped. Showing lines <start>-<end>. Use offset=<next> to continue.)`、`(Showing lines <start>-<end> of <total>. Use offset=<next> to continue.)` 或 `(End of file - total <total> lines)`。长行结尾精确为 `... (line truncated to <max> chars)`。读取缺失目标仍返回 `FS_NOT_FOUND`，但会为调用会话记录确认缺失；外部删除的文件被重新读取后，重试的 `write` 可以通过提供方的不替换防护安全地重新创建该文件。
 
 #### Token 影响
 
@@ -136,7 +136,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 #### 模型看到的内容
 
-失败会规范化为 `Error: <message>`。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to <max>`、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "<path>": not found`、`cannot read "<path>": not a regular file` 和 `offset <offset> is out of range for "<path>" (<total> lines)`；提供方和策略模板在各自包的 README 中逐字列出。防护变更失败还会在消息中携带恢复指令，由本包面向模型的错误包装追加：`FS_STALE_VERSION`（包括编辑目标缺失）追加 `— re-read the file, then retry`，`FS_NOT_OBSERVED` 追加 `— read the file, then retry`；结构化错误码保持不变。
+失败会规范化为 `Error: <message>`。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to <max>`、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "<path>": not found`、`cannot read "<path>": not a regular file` 和 `offset <offset> is out of range for "<path>" (<total> lines)`；提供方和策略模板在各自包的 README 中逐字列出。防护变更失败还会在消息中携带恢复指令，由本包面向模型的错误包装追加：`FS_STALE_VERSION` 追加 `— re-read the file, then retry`，`FS_NOT_OBSERVED` 追加 `— read the file, then retry`；结构化错误码保持不变。该次重新读取确认缺失后，edit 会报告 `FS_NOT_FOUND`，而不会重复陈旧恢复指令；write 则使用带防护的创建。
 
 #### Token 影响
 
diff --git a/packages/fs/tool-fs/src/edit.ts b/packages/fs/tool-fs/src/edit.ts
index fcd04cb17c..7b2c3ae596 100644
--- a/packages/fs/tool-fs/src/edit.ts
+++ b/packages/fs/tool-fs/src/edit.ts
@@ -137,8 +137,8 @@ export function applyEditTool(ctx: Context, sandbox: FsSandboxSurface): void {
         // model-facing remedy; anything else passes through.
         throw remediateFsError(sandbox.mapError(error, sandboxPolicy))
       }
-      // Record the observed version (a no-op when no policy plugin listens).
-      ctx.emit('fs/observed', target, outcome.version, exec)
+      // Record the present observation (a no-op when no policy plugin listens).
+      ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
       return {
         path: target.displayPath,
         before: outcome.before,
diff --git a/packages/fs/tool-fs/src/read.ts b/packages/fs/tool-fs/src/read.ts
index a92fdcaad8..dc4f07e8fe 100644
--- a/packages/fs/tool-fs/src/read.ts
+++ b/packages/fs/tool-fs/src/read.ts
@@ -138,10 +138,13 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
       const input = parseReadArgs(args, caps.limit)
       const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath))
 
-      // One stat: type check + size routing + the version recorded as observed.
+      // One stat: absence observation OR type check + size routing + present version.
       // A concurrent write can only make a later guarded mutation fail stale and require reread.
       const info = await ctx.fs.stat(target, exec.signal)
-      if (!info) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+      if (!info) {
+        ctx.emit('fs/observed', target, { kind: 'absent' }, exec)
+        throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+      }
       if (info.type !== 'file') throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
 
       // Stream when the file is large OR size is unknown, so a size-less backend
@@ -161,10 +164,10 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
         lines: window.lines,
         totalLines: window.totalLines,
       }
-      // Record the observed version (a no-op when no policy plugin listens). The
+      // Record the present observation (a no-op when no policy plugin listens). The
       // read already succeeded; an fs/observed listener is contractually a
       // synchronous, side-effect-only recorder.
-      ctx.emit('fs/observed', target, info.version, exec)
+      ctx.emit('fs/observed', target, { kind: 'present', version: info.version }, exec)
       return outcome
     },
     // Result-time display: a `read` card carrying the structured line window a
diff --git a/packages/fs/tool-fs/src/write.ts b/packages/fs/tool-fs/src/write.ts
index 56e2be488b..9a74dfc387 100644
--- a/packages/fs/tool-fs/src/write.ts
+++ b/packages/fs/tool-fs/src/write.ts
@@ -118,8 +118,8 @@ export function applyWriteTool(ctx: Context, sandbox: FsSandboxSurface): void {
         // model-facing remedy; anything else passes through.
         throw remediateFsError(sandbox.mapError(error, sandboxPolicy))
       }
-      // Record the observed version (a no-op when no policy plugin listens).
-      ctx.emit('fs/observed', target, outcome.version, exec)
+      // Record the present observation (a no-op when no policy plugin listens).
+      ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
       return {
         path: target.displayPath,
         operation: outcome.operation,
diff --git a/packages/fs/tool-fs/tests/integration.spec.ts b/packages/fs/tool-fs/tests/integration.spec.ts
index 3482b38569..d2a63e0a38 100644
--- a/packages/fs/tool-fs/tests/integration.spec.ts
+++ b/packages/fs/tool-fs/tests/integration.spec.ts
@@ -234,37 +234,33 @@ describe('default deployment (with dsh-fs-policy)', () => {
     })
   })
 
-  describe('deleted observed target (fail-closed corner)', () => {
-    it('a deleted observed file stays un-writable and un-editable in-session: the remedy cannot unblock it', async () => {
+  describe('deleted observed target', () => {
+    it('a failed reread records absence so write can safely recreate the file', async () => {
       await writeFile(join(dir, 'a.txt'), 'original')
       await call('read', { file_path: 'a.txt' })
       await rm(join(dir, 'a.txt')) // out-of-band deletion
 
-      // Edit of the missing target: stale (the missing-target path shares the
-      // stale code and the re-read remedy).
+      // The original positive observation still protects the first mutation.
       const edit = await call('edit', { file_path: 'a.txt', old_string: 'original', new_string: 'x' })
       expect(edit.isError).toBe(true)
       expect(edit.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
-
-      // Re-reading the missing file FAILS with FS_NOT_FOUND and records no
-      // observation, so the retried edit fails identically: the observed entry
-      // is never cleared for a deleted target.
-      const reread = await call('read', { file_path: 'a.txt' })
-      expect(reread.isError).toBe(true)
-      expect(reread.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
-      const retriedEdit = await call('edit', { file_path: 'a.txt', old_string: 'original', new_string: 'x' })
-      expect(retriedEdit.isError).toBe(true)
-      expect(retriedEdit.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
-
-      // Write cannot recreate it either: the stale observation still forces
-      // replaceIfVersion, which rejects a missing target ("file no longer exists").
-      const write = await call('write', { file_path: 'a.txt', content: 'fresh' })
+      const write = await call('write', { file_path: 'a.txt', content: 'premature' })
       expect(write.isError).toBe(true)
       expect(write.error).toMatchObject({ info: { code: 'FS_STALE_VERSION' } })
 
-      // The dead end lifts once the file exists again and is freshly observed.
-      await writeFile(join(dir, 'a.txt'), 'restored')
-      expect((await call('read', { file_path: 'a.txt' })).isError).toBe(false)
+      // A read-not-found is an authoritative negative observation for this
+      // owner. It still fails as a read, but changes the next write guard.
+      const reread = await call('read', { file_path: 'a.txt' })
+      expect(reread.isError).toBe(true)
+      expect(reread.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+
+      // Absence never authorizes edit: there is no content/version to edit.
+      const retriedEdit = await call('edit', { file_path: 'a.txt', old_string: 'original', new_string: 'x' })
+      expect(retriedEdit.isError).toBe(true)
+      expect(retriedEdit.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+
+      // The retried write uses createIfAbsent; the provider remains responsible
+      // for rejecting a concurrent creator at publication time.
       const recovered = await call('write', { file_path: 'a.txt', content: 'fresh' })
       expect(recovered.isError).toBe(false)
       expect(await readFile(join(dir, 'a.txt'), 'utf8')).toBe('fresh')
@@ -294,6 +290,20 @@ describe('default deployment (with dsh-fs-policy)', () => {
       expect(statSpy).not.toHaveBeenCalled()
       statSpy.mockRestore()
     })
+
+    it('a missing read still stats once and its recovery write stats zero times', async () => {
+      const statSpy = vi.spyOn(ctx.fs, 'stat')
+      const missing = await call('read', { file_path: 'missing.txt' })
+      expect(missing.isError).toBe(true)
+      expect(missing.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+      expect(statSpy).toHaveBeenCalledTimes(1)
+
+      statSpy.mockClear()
+      const created = await call('write', { file_path: 'missing.txt', content: 'fresh' })
+      expect(created.isError).toBe(false)
+      expect(statSpy).not.toHaveBeenCalled()
+      statSpy.mockRestore()
+    })
   })
 })
 
@@ -482,7 +492,7 @@ describe('signal, concurrency, and the fs/observed contract', () => {
     expect((await callOwned('read', { file_path: 'a.txt' })).isError).toBe(false)
 
     // Reproduce an older concurrent read winning the observation race.
-    ctx.emit('fs/observed', target, firstInfo.version, { agent: { session } })
+    ctx.emit('fs/observed', target, { kind: 'present', version: firstInfo.version }, { agent: { session } })
 
     const edit = await callOwned('edit', {
       file_path: 'a.txt',
diff --git a/packages/fs/tool-str-replace-editor/README.i18n.yaml b/packages/fs/tool-str-replace-editor/README.i18n.yaml
index b6733eb3b8..fd61c07154 100644
--- a/packages/fs/tool-str-replace-editor/README.i18n.yaml
+++ b/packages/fs/tool-str-replace-editor/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/fs/tool-str-replace-editor/README.md
-README.md: 97e9e0ab9ade7c7241c1aac3e2489e055d01ff8f
-README.zh.md: a71f040f3b1383604fa1f151f797906dd343c49a
+README.md: 1d6ce6fd801997dd21973fde1ffded84dbee1b5a
+README.zh.md: 62728659fa8c8173ac42a42610f1a710aec6e386
diff --git a/packages/fs/tool-str-replace-editor/README.md b/packages/fs/tool-str-replace-editor/README.md
index 97e9e0ab9a..1d6ce6fd80 100644
--- a/packages/fs/tool-str-replace-editor/README.md
+++ b/packages/fs/tool-str-replace-editor/README.md
@@ -13,7 +13,7 @@ Standalone model-facing `str_replace_editor` over `ctx.fs`. It can be composed w
 
 ## Tool
 
-The schema provides `view`, `create`, `str_replace`, and `insert` over absolute paths. File views use one-based line numbers and preserve content tabs, so displayed text remains valid literal replacement input; directory views omit hidden, dependency, and Python-cache entries and descend two levels. Replacement requires one unique literal match and reports errors only in the public `old_str` vocabulary. Insert follows the selected zero-based insertion boundary without adding an implicit trailing newline. Mutations preserve tabs outside the requested edit.
+The schema provides `view`, `create`, `str_replace`, and `insert` over absolute paths. File views use one-based line numbers and preserve content tabs, so displayed text remains valid literal replacement input; directory views omit hidden, dependency, and Python-cache entries and descend two levels. A missing view records confirmed absence before returning `FS_NOT_FOUND`, so a later `create` can recover an externally deleted path through the mounted policy's guarded-create flow; absence never authorizes `str_replace` or `insert`. Replacement requires one unique literal match and reports errors only in the public `old_str` vocabulary. Insert follows the selected zero-based insertion boundary without adding an implicit trailing newline. Mutations preserve tabs outside the requested edit.
 
 ## Model Experience
 
diff --git a/packages/fs/tool-str-replace-editor/README.zh.md b/packages/fs/tool-str-replace-editor/README.zh.md
index a71f040f3b..62728659fa 100644
--- a/packages/fs/tool-str-replace-editor/README.zh.md
+++ b/packages/fs/tool-str-replace-editor/README.zh.md
@@ -13,7 +13,7 @@
 
 ## 工具
 
-schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从 1 开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
+schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从 1 开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。查看缺失目标时，工具会在返回 `FS_NOT_FOUND` 前记录确认缺失，因此后续 `create` 可以通过已挂载策略的防护创建流程恢复外部删除的路径；缺失状态绝不会授权 `str_replace` 或 `insert`。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
 
 ## 模型体验
 
diff --git a/packages/fs/tool-str-replace-editor/src/index.ts b/packages/fs/tool-str-replace-editor/src/index.ts
index 6d0f65c48c..4b93c6d82c 100644
--- a/packages/fs/tool-str-replace-editor/src/index.ts
+++ b/packages/fs/tool-str-replace-editor/src/index.ts
@@ -105,6 +105,7 @@ async function statExisting(
 ): Promise<FsInfo> {
   const info = await ctx.fs.stat(target, exec.signal)
   if (info === undefined) {
+    ctx.emit('fs/observed', target, { kind: 'absent' }, exec)
     throw new FsError(
       `The path ${target.displayPath} does not exist. Please provide a valid path.`,
       'FS_NOT_FOUND',
@@ -231,7 +232,7 @@ async function viewPath(
     throw new FsError(`cannot view "${target.displayPath}": not a regular file or directory`, 'FS_NOT_REGULAR_FILE')
   }
   const content = await ctx.fs.readText(target, exec.signal)
-  ctx.emit('fs/observed', target, info.version, exec)
+  ctx.emit('fs/observed', target, { kind: 'present', version: info.version }, exec)
   return formatFileView(target.displayPath, content, maxOutputChars, viewRange)
 }
 
@@ -266,7 +267,7 @@ async function createFile(
   } catch (error: unknown) {
     throw policy.mapError(error, sandboxPolicy)
   }
-  ctx.emit('fs/observed', target, outcome.version, exec)
+  ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
   return `New file created successfully at: ${target.displayPath}`
 }
 
@@ -317,7 +318,7 @@ async function replaceInFile(
   } catch (error: unknown) {
     throw policy.mapError(error, sandboxPolicy)
   }
-  ctx.emit('fs/observed', target, outcome.version, exec)
+  ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
   return `The file ${target.displayPath} has been edited successfully.`
 }
 
@@ -359,7 +360,7 @@ async function insertInFile(
   } catch (error: unknown) {
     throw policy.mapError(error, sandboxPolicy)
   }
-  ctx.emit('fs/observed', target, outcome.version, exec)
+  ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
   return `The file ${target.displayPath} has been edited successfully.`
 }
 
diff --git a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
index 01f15284de..db0fe8dc35 100644
--- a/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
+++ b/packages/fs/tool-str-replace-editor/tests/tools.spec.ts
@@ -196,6 +196,35 @@ describe('tool-str-replace-editor', () => {
     expect(await readFile(sample, 'utf8')).toBe('one\nbetween\n\nthree\n')
   })
 
+  it('a failed view records absence so create can recover after external deletion', async () => {
+    const { ctx, root, owner } = await setup({}, { fsPolicy: true })
+    const sample = join(root, 'deleted.txt')
+    await writeFile(sample, 'original')
+    expect((await call(ctx, owner, { command: 'view', path: sample })).isError).toBe(false)
+    await rm(sample)
+
+    const missing = await call(ctx, owner, { command: 'view', path: sample })
+    expect(missing.isError).toBe(true)
+    expect(missing.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+
+    const edit = await call(ctx, owner, {
+      command: 'str_replace',
+      path: sample,
+      old_str: 'original',
+      new_str: 'edited',
+    })
+    expect(edit.isError).toBe(true)
+    expect(edit.error).toMatchObject({ info: { code: 'FS_NOT_FOUND' } })
+
+    const created = await call(ctx, owner, {
+      command: 'create',
+      path: sample,
+      file_text: 'fresh',
+    })
+    expect(created.isError).toBe(false)
+    expect(await readFile(sample, 'utf8')).toBe('fresh')
+  })
+
   it('writes replacement text literally', async () => {
     const { ctx, root, owner } = await setup()
     const sample = join(root, 'literal.txt')
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index eb7f2a0eac..ef97c945c9 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -370,11 +370,11 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>',
-        jsDoc: '/**\n * Atomically create or replace UTF-8 text. `expected` guards intent and\n * staleness; omission allows unconditional overwrite.\n * @param target - the resolved target to write.\n * @param content - the full new file content.\n * @param expected - the write intent guarding the write; omit for unconditional.\n * @param signal - aborts before the atomic rename takes effect.\n * @param sandboxPolicy - the per-call mode and workspace root this write\n *   runs under; a sandboxing backend fences the write by it, the bare backend\n *   ignores it. Omit to leave the backend its own default.\n * @returns the outcome, including the version the write produced.\n */',
+        jsDoc: '/**\n * Atomically create or replace UTF-8 text. `expected` guards intent and\n * staleness; omission allows unconditional overwrite.\n * @param target - the resolved target to write.\n * @param content - the full new file content.\n * @param expected - the write intent guarding the write; omit for unconditional.\n * @param signal - aborts before atomic publication takes effect.\n * @param sandboxPolicy - the per-call mode and workspace root this write\n *   runs under; a sandboxing backend fences the write by it, the bare backend\n *   ignores it. Omit to leave the backend its own default.\n * @returns the outcome, including the version the write produced.\n */',
       },
       {
         signature: 'abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>',
-        jsDoc: '/**\n * Atomically edit literal text. When supplied, the version guard is checked\n * before matching so stale content reports `FS_STALE_VERSION`; omission edits\n * the current content without a freshness precondition.\n * @param target - the resolved target to edit.\n * @param edit - the literal search/replace request.\n * @param expected - the version guard; omit for an unconditional edit.\n * @param signal - aborts before the atomic rename takes effect.\n * @param sandboxPolicy - the per-call mode and workspace root this edit runs\n *   under; a sandboxing backend fences the edit by it, the bare backend\n *   ignores it. Omit to leave the backend its own default.\n * @returns the outcome, including the version the edit produced.\n */',
+        jsDoc: '/**\n * Atomically edit literal text. When supplied, the version guard is checked\n * before matching so stale content reports `FS_STALE_VERSION`; omission edits\n * the current content without a freshness precondition.\n * @param target - the resolved target to edit.\n * @param edit - the literal search/replace request.\n * @param expected - the version guard; omit for an unconditional edit.\n * @param signal - aborts before atomic publication takes effect.\n * @param sandboxPolicy - the per-call mode and workspace root this edit runs\n *   under; a sandboxing backend fences the edit by it, the bare backend\n *   ignores it. Omit to leave the backend its own default.\n * @returns the outcome, including the version the edit produced.\n */',
       },
     ],
   },
@@ -1425,9 +1425,9 @@ export const EVENT_API: readonly EventApiEntry[] = [
   {
     name: 'fs/observed',
     mode: 'emit',
-    signature: '\'fs/observed\'(target: FsTarget, version: FsVersion, actor: object | undefined): void',
-    jsDoc: '/**\n * Record a successful observation. Listeners must be synchronous recorders:\n * throws fail the tool call and returned promises are not awaited.\n * @param target - the target that was read/written/edited.\n * @param version - the version the actor now holds as its observation.\n * @param actor - the observing tool-execution context; undefined records nothing useful.\n * @mode emit\n */',
-    summary: 'Record a successful observation.',
+    signature: '\'fs/observed\'(target: FsTarget, observation: FsObservation, actor: object | undefined): void',
+    jsDoc: '/**\n * Record an authoritative positive or negative observation. Listeners must\n * be synchronous recorders: throws fail the tool call and returned promises\n * are not awaited.\n * @param target - the target whose presence or absence was observed.\n * @param observation - present with its version, or confirmed absent.\n * @param actor - the observing tool-execution context; undefined records nothing useful.\n * @mode emit\n */',
+    summary: 'Record an authoritative positive or negative observation.',
   },
   {
     name: 'fs/write-intent',
diff --git a/packages/skill/skill-local/src/index.ts b/packages/skill/skill-local/src/index.ts
index 71ed3be21d..02a3b4fc39 100644
--- a/packages/skill/skill-local/src/index.ts
+++ b/packages/skill/skill-local/src/index.ts
@@ -136,7 +136,7 @@ export function apply(ctx: Context, config: Config = {}): void {
   ctx.effect(function* () {
     yield async () => { await provider.dispose() }
   }, 'skill-local watcher')
-  ctx.on('fs/observed', (target, _version, actor) => {
+  ctx.on('fs/observed', (target, _observation, actor) => {
     if (mutationToolName(actor) === undefined) return
     provider.observeHostMutation(target.displayPath)
   })
diff --git a/packages/skill/skill-local/tests/skill-local.spec.ts b/packages/skill/skill-local/tests/skill-local.spec.ts
index 75f4a4ed65..8bb08d2947 100644
--- a/packages/skill/skill-local/tests/skill-local.spec.ts
+++ b/packages/skill/skill-local/tests/skill-local.spec.ts
@@ -496,7 +496,7 @@ describe('LocalSkillProvider', () => {
     ctx.emit(
       'fs/observed',
       { targetKey: path as never, displayPath: path },
-      FsVersion('failed-read'),
+      { kind: 'present', version: FsVersion('failed-read') },
       { name: 'edit' },
     )
     expect(await ctx.skills.snapshot()).toEqual({ skills: [], complete: false })
@@ -526,7 +526,7 @@ describe('LocalSkillProvider', () => {
       ctx.emit(
         'fs/observed',
         { targetKey: path as never, displayPath: path },
-        FsVersion('entry-failure'),
+        { kind: 'present', version: FsVersion('entry-failure') },
         { name: 'write' },
       )
     }
@@ -674,7 +674,7 @@ describe('LocalSkillProvider', () => {
       ctx.emit(
         'fs/observed',
         { targetKey: displayPath as never, displayPath },
-        FsVersion('observed'),
+        { kind: 'present', version: FsVersion('observed') },
         actor,
       )
     }
@@ -689,7 +689,7 @@ describe('LocalSkillProvider', () => {
     ctx.emit(
       'fs/observed',
       { targetKey: path as never, displayPath: path },
-      FsVersion('observed'),
+      { kind: 'present', version: FsVersion('observed') },
       { name: 'edit' },
     )
 
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index de53d44755..fffde3ceb8 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -262,6 +262,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   FsEditOutcome: 'filesystem.md',
   FsEditRequest: 'filesystem.md',
   FsInfo: 'filesystem.md',
+  FsObservation: 'filesystem.md',
   FsPathInfo: 'filesystem.md',
   FsPolicyExec: 'filesystem.md',
   FsTarget: 'filesystem.md',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index a68ab874f0..cd1cb3c0c1 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -253,7 +253,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     dir: 'tool-str-replace-editor',
     source: 'packages/fs/tool-str-replace-editor/src/index.ts',
     requires: ['ctx.tools', 'ctx.fs'],
-    writes: ['tool/call', 'fs/observed after successful file operations', 'tool/result'],
+    writes: ['tool/call', 'fs/observed after view presence/absence or successful mutation', 'tool/result'],
     async mount(ctx) {
       await ctx.plugin(LocalFileSystem)
       await ctx.plugin(ToolStrReplaceEditor)
@@ -266,7 +266,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     dir: 'tool-fs',
     source: 'packages/fs/tool-fs/src/index.ts',
     requires: ['ctx.tools', 'ctx.fs', 'ctx.systemPrompt'],
-    writes: ['tool/call', 'fs/write-intent or fs/edit-intent for mutations', 'fs/observed after successful file operations', 'tool/result'],
+    writes: ['tool/call', 'fs/write-intent or fs/edit-intent for mutations', 'fs/observed after read presence/absence or successful mutation', 'tool/result'],
     async mount(ctx) {
       // The tool needs `fs`; the bare provider is sufficient because policy
       // changes behavior, not schema shape.
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 5f57b5167d..cd9d020779 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -960,6 +960,11 @@
       "symbol": "FsVersion",
       "source": "packages/fs/fs/src/types.ts"
     },
+    {
+      "doc": "docs/subsystems/filesystem.md",
+      "symbol": "FsObservation",
+      "source": "packages/fs/fs/src/types.ts"
+    },
     {
       "doc": "docs/subsystems/filesystem.md",
       "symbol": "FsInfo",

From 7132b9730eaf1468ed4a1df8c580a8c22cd3008a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:40:41 +0800
Subject: [PATCH 480/516] fix(fs): harden guarded-create publication

---
 ...9-filesystem-absence-observation.i18n.yaml |  4 +-
 ...26-08-09-filesystem-absence-observation.md |  8 +-
 ...08-09-filesystem-absence-observation.zh.md |  8 +-
 packages/e2b/fs-e2b/README.i18n.yaml          |  4 +-
 packages/e2b/fs-e2b/README.md                 |  2 +-
 packages/e2b/fs-e2b/README.zh.md              |  2 +-
 packages/e2b/fs-e2b/src/index.ts              |  2 +-
 packages/e2b/fs-e2b/tests/filesystem.spec.ts  | 27 ++++++-
 packages/fs/fs-local/README.i18n.yaml         |  4 +-
 packages/fs/fs-local/README.md                |  4 +-
 packages/fs/fs-local/README.zh.md             |  4 +-
 packages/fs/fs-local/src/fsio.ts              | 77 +++++++++++++++----
 packages/fs/fs-local/src/index.ts             |  2 +-
 packages/fs/fs-local/tests/filesystem.spec.ts | 35 +++++++++
 packages/fs/fs-local/tests/fsio.spec.ts       | 64 ++++++++++++++-
 15 files changed, 207 insertions(+), 40 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml
index 39e50ffe6b..6fbd47fc65 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.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 .agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
-2026-08-09-filesystem-absence-observation.md: e0c5c8b1845550ac6380ea4b2782cde13cba3ce9
-2026-08-09-filesystem-absence-observation.zh.md: 808698a7cb7a3575ef500dced7a646691d65c424
+2026-08-09-filesystem-absence-observation.md: e01719651f54cafc86a3972690507b1ee9b95cc9
+2026-08-09-filesystem-absence-observation.zh.md: 126f85e95b1debbccddf82fda432d31a69250388
diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
index e0c5c8b184..e01719651f 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.md
@@ -12,13 +12,13 @@ Treating a failed read as permission to create also exposes a second boundary. B
 
 ## Decision
 
-`dsh-fs` owns an explicit observation union: `{ kind: 'present', version: FsVersion } | { kind: 'absent' }`. The `fs/observed` event carries that union. Successful reads and mutations emit present; a `read` or `str_replace_editor view` metadata miss emits absent synchronously before returning `FS_NOT_FOUND`. Other read failures do not manufacture absence.
+`dsh-fs` owns an explicit observation union: `{ kind: 'present', version: FsVersion } | { kind: 'absent' }`. The `fs/observed` event carries that union. Successful reads and mutations emit present; a metadata miss from `read` or the `str_replace_editor` `view`, `str_replace`, or `insert` command emits absent synchronously before returning `FS_NOT_FOUND`. Other read failures do not manufacture absence.
 
 `dsh-fs-policy` stores three logical states per owner and target without injecting or calling `ctx.fs`: missing map entry is unseen, `absent` is confirmed absence, and `present(version)` is a replacement/edit basis. Write maps unseen and absent to the existing `createIfAbsent` intent and present to `replaceIfVersion`. Edit maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. A successful create or mutation replaces absence with its produced present version.
 
-Every provider must enforce `createIfAbsent` at the publication point, not only at its initial probe. `dsh-fs-local` stages and fsyncs in a private sibling directory, then hard-links the staged file to the destination; an existing destination makes the no-replace link fail and preserves the competitor. `dsh-fs-e2b` uses remote `ln` with an explicit created/existing result and derives the committed target version from metadata obtained before the non-cancellable commit. Replacements and bare unconditional writes retain their existing publication paths.
+Every provider must enforce `createIfAbsent` at the publication point, not only at its initial probe. `dsh-fs-local` stages and fsyncs in a private sibling directory, then hard-links the staged file to the destination; after a failed link it inspects the destination entry so a regular-file collision returns `FS_NOT_OBSERVED`, a non-regular entry returns `FS_NOT_REGULAR_FILE`, and a failure against a still-missing target returns `FS_IO_ERROR`. `dsh-fs-e2b` uses remote `ln -T` with an explicit created/existing result and derives the committed target version from metadata obtained before the non-cancellable commit. Replacements and bare unconditional writes retain their existing publication paths.
 
-This decision does not claim cross-process linearizability for `replaceIfVersion`: the provider version check and replacement remain protected only against writers represented by the provider's own lock and detectable metadata. The narrower guarantee is exact and sufficient for absence recovery: guarded creation never clobbers a target that appears before publication.
+This decision does not claim cross-process linearizability for `replaceIfVersion`: the provider version check and replacement remain protected only against writers represented by the provider's own lock and detectable metadata. The narrower guarantee is exact and sufficient for absence recovery: guarded creation never clobbers a target that appears before publication. Local guarded creation requires hard-link support; once any local publication succeeds, staging cleanup is best effort because private residue cannot make the committed write false.
 
 ## Alternatives considered
 
@@ -29,7 +29,7 @@ This decision does not claim cross-process linearizability for `replaceIfVersion
 
 ## Consequences
 
-The first mutation after an unobserved external deletion still fails `FS_STALE_VERSION`; the user or model must follow the existing reread remedy. That missing reread returns `FS_NOT_FOUND` while changing policy state, after which edit remains forbidden and write may recreate the path. If another writer wins the create race, the retry returns `FS_NOT_OBSERVED` and leaves the winner intact.
+The first mutation after an unobserved external deletion still fails `FS_STALE_VERSION`; the user or model must follow the existing reread remedy. That missing reread returns `FS_NOT_FOUND` while changing policy state, after which edit remains forbidden and write may recreate the path. If another writer wins the create race, the retry returns `FS_NOT_OBSERVED` and leaves the winner intact; a competing directory, special entry, or dangling symbolic link instead returns `FS_NOT_REGULAR_FILE` without prescribing another read.
 
 The observation payload is a package-owned event contract change, so every producer, listener, invariant, generated Cordis catalog, subsystem document, and both filesystem tool families move together. The policy keeps its one-stat read and zero-stat write/edit budget, owner isolation, disposal behavior, and optional deployment boundary from the [event-gate decision](../architecture/2026-06-26-file-context-as-event-gate.md).
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
index 808698a7cb..126f85e95b 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-09-filesystem-absence-observation.zh.md
@@ -12,13 +12,13 @@ Status: implemented
 
 ## 决策
 
-`dsh-fs` 拥有一个显式观测联合类型：`{ kind: 'present', version: FsVersion } | { kind: 'absent' }`。`fs/observed` 事件携带该联合类型。成功的读取与变更发出存在观测；`read` 或 `str_replace_editor view` 的元数据未命中会在返回 `FS_NOT_FOUND` 前同步发出缺失观测。其他读取失败不会产生缺失观测。
+`dsh-fs` 拥有一个显式观测联合类型：`{ kind: 'present', version: FsVersion } | { kind: 'absent' }`。`fs/observed` 事件携带该联合类型。成功的读取与变更发出存在观测；`read` 的元数据未命中，或 `str_replace_editor` 的 `view`、`str_replace`、`insert` 命令发生元数据未命中时，都会在返回 `FS_NOT_FOUND` 前同步发出缺失观测。其他读取失败不会产生缺失观测。
 
 `dsh-fs-policy` 按所有者与目标存储三种逻辑状态，既不注入也不调用 `ctx.fs`：映射中无条目即未见，`absent` 表示确认缺失，`present(version)` 是替换/编辑基准。写入把未见和缺失映射到现有 `createIfAbsent` 意图，把存在映射到 `replaceIfVersion`。编辑把未见映射到 `FS_NOT_OBSERVED`，把缺失映射到 `FS_NOT_FOUND`，把存在映射到其版本守卫。成功创建或变更后，系统会用其产生的存在版本取代缺失状态。
 
-每个提供方都必须在发布点执行 `createIfAbsent`，不能只在初始探测时执行。`dsh-fs-local` 在私有同级目录中暂存并执行 fsync，再通过硬链接把暂存文件发布到目标位置；目标已存在时，不替换链接会失败，并保留竞争创建者写入的文件。`dsh-fs-e2b` 使用远程 `ln` 返回明确的已创建/已存在结果，并根据不可取消提交前取得的元数据推导已提交目标的版本。替换操作和裸无条件写入仍沿用现有发布路径。
+每个提供方都必须在发布点执行 `createIfAbsent`，不能只在初始探测时执行。`dsh-fs-local` 在私有同级目录中暂存并执行 fsync，再通过硬链接把暂存文件发布到目标位置；链接失败后，它会检查目标条目：与普通文件冲突时返回 `FS_NOT_OBSERVED`，条目非普通时返回 `FS_NOT_REGULAR_FILE`，目标仍然缺失时返回 `FS_IO_ERROR`。`dsh-fs-e2b` 使用远程 `ln -T` 返回明确的已创建/已存在结果，并根据不可取消提交前取得的元数据推导已提交目标的版本。替换操作和裸无条件写入仍沿用现有发布路径。
 
-本决策不宣称 `replaceIfVersion` 具有跨进程线性一致性：提供方的版本检查与替换仍只能防范被其自身锁纳入协调的写入方，以及能通过元数据检测到的写入方。更窄的保证边界准确且足以支持缺失恢复：带防护的创建绝不会覆盖在发布前出现的目标。
+本决策不宣称 `replaceIfVersion` 具有跨进程线性一致性：提供方的版本检查与替换仍只能防范被其自身锁纳入协调的写入方，以及能通过元数据检测到的写入方。更窄的保证边界准确且足以支持缺失恢复：带防护的创建绝不会覆盖在发布前出现的目标。本地带防护的创建要求支持硬链接；任何本地发布一旦成功，暂存清理便采用尽力而为语义，因为私有残留无法否定已提交写入的成功。
 
 ## 曾考虑的替代方案
 
@@ -29,7 +29,7 @@ Status: implemented
 
 ## 影响
 
-尚未观测到外部删除时，第一次变更仍以 `FS_STALE_VERSION` 失败；用户或模型必须遵循现有的重新读取恢复指令。该次针对缺失目标的重新读取会返回 `FS_NOT_FOUND` 并同时改变策略状态，此后 edit 仍被禁止，而 write 可以重新创建该路径。如果另一个写入方赢得创建竞态，本次重试会返回 `FS_NOT_OBSERVED`，并保留获胜方写入的文件。
+尚未观测到外部删除时，第一次变更仍以 `FS_STALE_VERSION` 失败；用户或模型必须遵循现有的重新读取恢复指令。该次针对缺失目标的重新读取会返回 `FS_NOT_FOUND` 并同时改变策略状态，此后 edit 仍被禁止，而 write 可以重新创建该路径。如果另一个写入方赢得创建竞态，本次重试会返回 `FS_NOT_OBSERVED`，并保留获胜方写入的文件；若竞态目标是目录、特殊条目或悬空符号链接，则改为返回 `FS_NOT_REGULAR_FILE`，且不会要求再次读取。
 
 观测载荷是由包拥有的事件约定变更，因此所有生产方、监听器、不变式、生成的 Cordis 目录、子系统文档以及两套文件系统工具都必须同步更新。策略保留[事件门禁决策](../architecture/2026-06-26-file-context-as-event-gate.md)确立的 read 一次 `stat`、write/edit 零次 `stat` 预算、所有者隔离、dispose 行为和可选部署边界。
 
diff --git a/packages/e2b/fs-e2b/README.i18n.yaml b/packages/e2b/fs-e2b/README.i18n.yaml
index 4e29843fad..64460f7e87 100644
--- a/packages/e2b/fs-e2b/README.i18n.yaml
+++ b/packages/e2b/fs-e2b/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/e2b/fs-e2b/README.md
-README.md: 039ad72a9651a1e8907c2c63b8c83d113aedbb4e
-README.zh.md: be97bbd92edb528f9560518398a0cb70f36b992b
+README.md: 1b66e84defb56cbfaa4a91d6ba6b48377fb52ca9
+README.zh.md: d9cd3ce1e109bf6b0b7fae02157d1ec6be51e575
diff --git a/packages/e2b/fs-e2b/README.md b/packages/e2b/fs-e2b/README.md
index 039ad72a96..1b66e84def 100644
--- a/packages/e2b/fs-e2b/README.md
+++ b/packages/e2b/fs-e2b/README.md
@@ -9,7 +9,7 @@ E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provide
 - **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; GNU `realpath -mz` supplies canonical target identity without requiring the final file to exist, and ASCII/base64 plus strict NUL framing preserves newline and multibyte paths across the decoded SDK transport. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam; listings reuse returned metadata and resolve symbolic-link entries sequentially. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
 - **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
 - **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
-- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, and preserve an existing file's POSIX mode. Replacements publish through E2B's same-filesystem atomic rename. A guarded `createIfAbsent` publishes with remote `ln` instead, making the commit atomically no-replace; metadata read from the staged file before that commit is projected to the target path for the returned version, so no fallible metadata request follows either commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process.
+- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, and preserve an existing file's POSIX mode. Replacements publish through E2B's same-filesystem atomic rename. A guarded `createIfAbsent` publishes with remote `ln -T` instead, making the commit atomically no-replace even when a directory appears at the destination; metadata read from the staged file before that commit is projected to the target path for the returned version, so no fallible metadata request follows either commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process.
 - **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before publication. The signal is not forwarded into the rename or guarded-link commit, so cancellation cannot interrupt atomic publication or turn a committed write into a reported failure.
 
 The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
diff --git a/packages/e2b/fs-e2b/README.zh.md b/packages/e2b/fs-e2b/README.zh.md
index be97bbd92e..d9cd3ce1e1 100644
--- a/packages/e2b/fs-e2b/README.zh.md
+++ b/packages/e2b/fs-e2b/README.zh.md
@@ -9,7 +9,7 @@
 - **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；GNU `realpath -mz` 提供规范化目标身份，且不要求最终文件存在；ASCII/base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam；目录列表会复用已返回的元数据，并依次解析符号链接条目。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
 - **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
 - **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
-- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，并保留现有文件的 POSIX mode。替换操作通过 E2B 的同一文件系统原子重命名发布。带防护的 `createIfAbsent` 改用远程 `ln` 发布，使提交具备原子且不替换的语义；系统会把提交前从暂存文件读取的元数据投影到目标路径，以生成返回的版本，因此任何一类提交点之后都不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。
+- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，并保留现有文件的 POSIX mode。替换操作通过 E2B 的同一文件系统原子重命名发布。带防护的 `createIfAbsent` 改用远程 `ln -T` 发布，即使目标位置出现目录，也能使提交具备原子且不替换的语义；系统会把提交前从暂存文件读取的元数据投影到目标路径，以生成返回的版本，因此任何一类提交点之后都不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。
 - **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在发布前立即检查。信号不会传入 rename 或防护链接提交，因此取消无法中断原子发布，也不会把已提交的写入报告为失败。
 
 该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
diff --git a/packages/e2b/fs-e2b/src/index.ts b/packages/e2b/fs-e2b/src/index.ts
index 04b23a6775..b26338ffa4 100644
--- a/packages/e2b/fs-e2b/src/index.ts
+++ b/packages/e2b/fs-e2b/src/index.ts
@@ -489,7 +489,7 @@ export class E2BFileSystem extends FileSystem {
         assertNotAborted(signal, 'write')
         const targetArg = quoteE2BShellArg(targetPath)
         const publication = await sandbox.commands.run(
-          `if ln -- ${quoteE2BShellArg(temporary)} ${targetArg}; then printf created; elif test -e ${targetArg} || test -L ${targetArg}; then printf exists; else exit 1; fi`,
+          `if ln -T -- ${quoteE2BShellArg(temporary)} ${targetArg}; then printf created; elif test -e ${targetArg} || test -L ${targetArg}; then printf exists; else exit 1; fi`,
           commandOpts(undefined),
         )
         if (publication.stdout === 'exists') {
diff --git a/packages/e2b/fs-e2b/tests/filesystem.spec.ts b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
index 973cf7c5c8..6ee3df6543 100644
--- a/packages/e2b/fs-e2b/tests/filesystem.spec.ts
+++ b/packages/e2b/fs-e2b/tests/filesystem.spec.ts
@@ -52,7 +52,10 @@ class FakeRemote {
   nextRemoveError: unknown
   canonicalOutput: string | undefined
   abortAfterRename: AbortController | undefined
-  competitorBeforeLink: { path: string; data: string } | undefined
+  competitorBeforeLink:
+    | { path: string; kind: 'file'; data: string }
+    | { path: string; kind: 'directory' }
+    | undefined
   guardedLinkOutput: string | undefined
   disappearOnInfo = new Set<string>()
   private clock = 1
@@ -257,7 +260,7 @@ class FakeRemote {
         const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
         if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
         const guardedLink = new RegExp(
-          "^if ln -- '([^']+)' '([^']+)'; then printf created; "
+          "^if ln -T -- '([^']+)' '([^']+)'; then printf created; "
           + "elif test -e '[^']+' \\|\\| test -L '[^']+'; then printf exists; else exit 1; fi$",
         ).exec(command)
         if (guardedLink !== null) {
@@ -269,7 +272,8 @@ class FakeRemote {
             return { exitCode: 0, stdout, stderr: '' }
           }
           if (this.competitorBeforeLink?.path === to) {
-            this.file(to, this.competitorBeforeLink.data)
+            if (this.competitorBeforeLink.kind === 'directory') this.dir(to)
+            else this.file(to, this.competitorBeforeLink.data)
             this.competitorBeforeLink = undefined
           }
           if (this.nodes.has(to)) return { exitCode: 0, stdout: 'exists', stderr: '' }
@@ -555,7 +559,7 @@ describe('E2BFileSystem atomic writes and edits', () => {
 
   it('preserves a competitor created after the guarded-create probe', async () => {
     const remote = new FakeRemote()
-    remote.competitorBeforeLink = { path: '/workspace/race.txt', data: 'competitor' }
+    remote.competitorBeforeLink = { path: '/workspace/race.txt', kind: 'file', data: 'competitor' }
     const { fs } = await setup(remote)
 
     await expectCode(
@@ -567,6 +571,21 @@ describe('E2BFileSystem atomic writes and edits', () => {
     expect(remote.removals).toHaveLength(1)
   })
 
+  it('preserves a competing directory during guarded-create publication', async () => {
+    const remote = new FakeRemote()
+    remote.competitorBeforeLink = { path: '/workspace/race-dir', kind: 'directory' }
+    const { fs } = await setup(remote)
+
+    await expectCode(
+      fs.writeText(await fs.resolve('race-dir'), 'ours', { kind: 'createIfAbsent' }),
+      'FS_NOT_OBSERVED',
+    )
+    expect(remote.nodes.get('/workspace/race-dir')?.type).toBe(FileType.DIR)
+    expect(remote.nodes.has('/workspace/race-dir/content')).toBe(false)
+    expect(remote.links).toHaveLength(0)
+    expect(remote.removals).toHaveLength(1)
+  })
+
   it('rejects an invalid guarded-create publication response before claiming success', async () => {
     const remote = new FakeRemote()
     remote.guardedLinkOutput = 'unexpected'
diff --git a/packages/fs/fs-local/README.i18n.yaml b/packages/fs/fs-local/README.i18n.yaml
index 6aaf691eef..ef76470394 100644
--- a/packages/fs/fs-local/README.i18n.yaml
+++ b/packages/fs/fs-local/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/fs/fs-local/README.md
-README.md: ac2f271ad9651797e1aceeba49e7a52533405f10
-README.zh.md: 633d55fe06b2261d9d5b52184987811c87c8f155
+README.md: 7b993fa123d13833313ecf3f78c64e466b960d5d
+README.zh.md: 428719137f988395b76513eab2c3f76ce4f331e5
diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md
index ac2f271ad9..7b993fa123 100644
--- a/packages/fs/fs-local/README.md
+++ b/packages/fs/fs-local/README.md
@@ -19,7 +19,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
 - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` decodes chunks so a huge file need not be held whole in memory and consumers can enforce their own retention bounds. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
-- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, then fsyncs and publishes. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` hard-links the staged file into place as an atomic no-replace publication, so a file created after the initial probe is preserved and rejected with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
+- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, then fsyncs and publishes. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` hard-links the staged file into place as an atomic no-replace publication, so a regular file created after the initial probe is preserved and rejected with `FS_NOT_OBSERVED`, while a non-regular path entry is preserved and rejected with `FS_NOT_REGULAR_FILE`; `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
 
 The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.
@@ -40,3 +40,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **`editText` holds the whole file (plus the edited copy) in memory** — streaming exists only on the read path.
 - **Binary detection is asymmetric** — reads NUL-sample only the first 8192 bytes while edits scan the whole buffer, so a file with a late NUL reads fine but rejects edits.
 - **The per-target mutation lock is in-process only** — guarded create still uses an atomic no-replace publication across processes, but replacement writers in another process are caught only when the optional version guard observes their metadata change; they are never serialized.
+- **Guarded creation requires hard-link support** — filesystems or mounts that reject hard-link publication cannot serve `createIfAbsent`; the provider preserves the missing target and reports `FS_IO_ERROR`.
+- **Post-commit cleanup is best effort** — a successful publication remains successful if removal of its owner-only staging directory fails, leaving private residue for later operator cleanup.
diff --git a/packages/fs/fs-local/README.zh.md b/packages/fs/fs-local/README.zh.md
index 633d55fe06..428719137f 100644
--- a/packages/fs/fs-local/README.zh.md
+++ b/packages/fs/fs-local/README.zh.md
@@ -19,7 +19,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此飞行中的中止会报告 `FS_ABORTED`，而非陈旧的不存在结果。
 - **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片解码，因此超大文件无需整体保存在内存中，消费方也可以执行各自的保留上限。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑。
 - **`listDir`**：按稳定的 `name.localeCompare()` 顺序列出一层目录。每个条目携带子项 basename、类型、解析后的子目标（`displayPath` 位于所列目录下，`targetKey` 是 realpath 身份）和低成本 stat 元数据（`version`，普通文件另有 `size`）。它绝不会打开或解码文件内容。缺失目标报告 `FS_NOT_FOUND`，文件/特殊文件目标报告 `FS_NOT_DIRECTORY`，已中止调用报告 `FS_ABORTED`，权限失败报告 `FS_PERMISSION_DENIED`，其他列出或子项元数据 I/O 失败报告 `FS_IO_ERROR`。损坏/消失的子项以无元数据的 `other` 返回，但解析子项时出现权限/I/O 失败会让整个列表以结构化 `FsError` 失败。
-- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内，随后执行 fsync 并发布。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 通过硬链接把暂存文件发布到目标位置，以实现原子且不替换的发布，因此初始探测后创建的文件会被保留，并以 `FS_NOT_OBSERVED` 拒绝本次写入；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
+- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内，随后执行 fsync 并发布。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 通过硬链接把暂存文件发布到目标位置，以实现原子且不替换的发布，因此初始探测后创建的普通文件会被保留，并以 `FS_NOT_OBSERVED` 拒绝本次写入；非普通路径条目也会被保留，并以 `FS_NOT_REGULAR_FILE` 拒绝；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
 - **`editText`**：在同一原语之上依次执行原子的字面量读取、修改和写入，并通过变更锁按目标串行化。`expected` 防护是可选的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
 
 包根 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
@@ -40,3 +40,5 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`editText` 会把整个文件及编辑后的副本保存在内存中**：只有读取路径支持流式处理。
 - **二进制检测不对称**：读取只对前 8192 字节执行 NUL 采样，编辑则扫描整个 buffer，因此 NUL 出现在后部的文件可以读取，但编辑会被拒绝。
 - **每目标变更锁仅限进程内**：即使跨进程，带防护的创建仍采用原子且不替换的发布方式；但只有当可选版本防护观察到元数据变化时，系统才能发现其他进程中的替换写入方，且绝不会将其串行化。
+- **带防护的创建要求支持硬链接**：拒绝硬链接发布的文件系统或挂载点无法支持 `createIfAbsent`；提供方会使目标保持缺失状态并报告 `FS_IO_ERROR`。
+- **提交后清理采用尽力而为语义**：如果移除仅所有者可访问的暂存目录失败，成功发布仍视为成功，并留下私有残留供运维人员后续清理。
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index 071ad31637..24ad9b929f 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -91,6 +91,10 @@ export interface FsIoInternals {
   replaceFile?: (replaced: string, replacement: string) => Promise<void>
   /** Override the hard-link no-replace publication boundary. */
   linkFile?: (existingPath: string, newPath: string) => Promise<void>
+  /** Override target inspection after guarded publication fails. */
+  inspectPublicationTarget?: (path: string) => Promise<BigIntStats>
+  /** Override staging-directory removal for commit-point failure coverage. */
+  removeStagingDir?: (stagingDir: string) => Promise<void>
   /** Test hook after the temp file is written/synced but before final chmod+publication. */
   inspectTemp?: (paths: { stagingDir: string; tempPath: string }) => void | Promise<void>
 }
@@ -413,9 +417,13 @@ export async function* streamWholeText(target: LocalTarget, signal?: AbortSignal
 
 // --- Writing ---
 
-async function removeStagingDirOrThrow(stagingDir: string, originalError: unknown): Promise<never> {
+async function removeStagingDirOrThrow(
+  stagingDir: string,
+  originalError: unknown,
+  removeStagingDir: (path: string) => Promise<void>,
+): Promise<never> {
   try {
-    await rm(stagingDir, { recursive: true, force: true })
+    await removeStagingDir(stagingDir)
   } catch (cleanupError: unknown) {
     /* v8 ignore next 1 -- cleanup failure here needs a second filesystem fault after the primary write failure. */
     throw new FsError(`write failed (${errorMessage(originalError)}) and temp cleanup failed (${errorMessage(cleanupError)})`, 'FS_NOT_FOUND', { cause: originalError })
@@ -423,6 +431,43 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
   throw originalError
 }
 
+async function throwGuardedCreateFailure(
+  error: unknown,
+  absolutePath: string,
+  displayPath: string,
+  inspectPublicationTarget: (path: string) => Promise<BigIntStats>,
+): Promise<never> {
+  let existing: BigIntStats | undefined
+  try {
+    existing = await inspectPublicationTarget(absolutePath)
+  } catch (metadataError: unknown) {
+    if (!isENOENT(metadataError) && !isENOTDIR(metadataError)) {
+      throw new FsError(`cannot write "${displayPath}": ${errorMessage(metadataError)}`, 'FS_IO_ERROR', { cause: metadataError })
+    }
+  }
+
+  // Link errno values vary by platform and filesystem. Inspect the target entry
+  // after failure so a collision is not confused with missing hard-link support.
+  if (existing !== undefined) {
+    if (!existing.isFile()) {
+      throw new FsError(`cannot write "${displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE', { cause: error })
+    }
+    throw new FsError(
+      `cannot overwrite existing "${displayPath}" without reading it first`,
+      'FS_NOT_OBSERVED',
+      { cause: error },
+    )
+  }
+  if (isEEXIST(error)) {
+    throw new FsError(
+      `cannot overwrite existing "${displayPath}" without reading it first`,
+      'FS_NOT_OBSERVED',
+      { cause: error },
+    )
+  }
+  throw new FsError(`cannot write "${displayPath}": ${errorMessage(error)}`, 'FS_IO_ERROR', { cause: error })
+}
+
 /**
  * Atomically replace a file through a private, synced staging file in the same directory.
  * POSIX protects the staging directory and file with `0o700` and `0o600`. A new Windows file
@@ -434,8 +479,9 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
  * inert as a mode on Windows but identifies replacement security semantics.
  * @param signal - cancellation checked before final publication.
  * @param internals - Test hook for pinning temp names and observing the staged file.
- * @param createIfAbsent - publish with a hard-link no-replace primitive; a
- *   concurrent creator is preserved and rejected with `FS_NOT_OBSERVED`.
+ * @param createIfAbsent - when provided, publish with a hard-link no-replace
+ * primitive; a concurrent creator's file is preserved and this write is
+ * rejected with `FS_NOT_OBSERVED` using the supplied display path.
  */
 export async function writeFileAtomic(
   absolutePath: string,
@@ -443,7 +489,7 @@ export async function writeFileAtomic(
   mode: number | undefined,
   signal: AbortSignal | undefined,
   internals: FsIoInternals = {},
-  createIfAbsent = false,
+  createIfAbsent?: { displayPath: string },
 ): Promise<void> {
   throwIfAborted(signal, 'write')
   const directory = dirname(absolutePath)
@@ -458,6 +504,10 @@ export async function writeFileAtomic(
   const copyFileDacl = internals.copyFileDacl ?? copyFileDaclWin32
   const replaceFile = internals.replaceFile ?? replaceFileWin32
   const linkFile = internals.linkFile ?? link
+  const inspectPublicationTarget = internals.inspectPublicationTarget
+    ?? (path => lstat(path, { bigint: true }))
+  const removeStagingDir = internals.removeStagingDir
+    ?? (path => rm(path, { recursive: true, force: true }))
   let handle: Awaited<ReturnType<typeof open>> | undefined
   let stagingCreated = false
   try {
@@ -478,16 +528,11 @@ export async function writeFileAtomic(
     handle = undefined
 
     throwIfAborted(signal, 'write')
-    if (createIfAbsent) {
+    if (createIfAbsent !== undefined) {
       try {
         await linkFile(tempPath, absolutePath)
       } catch (error: unknown) {
-        if (!isEEXIST(error)) throw error
-        throw new FsError(
-          `cannot overwrite existing "${absolutePath}" without reading it first`,
-          'FS_NOT_OBSERVED',
-          { cause: error },
-        )
+        await throwGuardedCreateFailure(error, absolutePath, createIfAbsent.displayPath, inspectPublicationTarget)
       }
     } else if (platform === 'win32' && mode !== undefined) {
       try {
@@ -501,7 +546,11 @@ export async function writeFileAtomic(
     } else {
       await rename(tempPath, absolutePath)
     }
-    await rm(stagingDir, { recursive: true, force: true })
+    try {
+      await removeStagingDir(stagingDir)
+    } catch (_committedStagingCleanupFailure) {
+      // The target is committed; owner-only staging residue cannot turn that write into a failure.
+    }
   } catch (error: unknown) {
     /* v8 ignore next -- abort-mid-write needs a writeFile/signal race; the non-abort (rename/open) side is tested. */
     let failure: unknown = isAbortError(error) ? new FsError('write aborted', 'FS_ABORTED') : error
@@ -514,7 +563,7 @@ export async function writeFileAtomic(
       }
     }
     if (!stagingCreated) throw failure
-    return removeStagingDirOrThrow(stagingDir, failure)
+    return removeStagingDirOrThrow(stagingDir, failure, removeStagingDir)
   }
 }
 
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 6be6a4402b..9cd4be41b8 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -173,7 +173,7 @@ export class LocalFileSystem extends FileSystem {
         existing?.mode,
         signal,
         this.internals,
-        expected?.kind === 'createIfAbsent',
+        expected?.kind === 'createIfAbsent' ? { displayPath: target.displayPath } : undefined,
       )
       const after = await probe(target.targetKey)
       return {
diff --git a/packages/fs/fs-local/tests/filesystem.spec.ts b/packages/fs/fs-local/tests/filesystem.spec.ts
index 531be25360..f6736ff9c3 100644
--- a/packages/fs/fs-local/tests/filesystem.spec.ts
+++ b/packages/fs/fs-local/tests/filesystem.spec.ts
@@ -308,6 +308,41 @@ describe('writeText', () => {
     expect(await readFile(path, 'utf8')).toBe('competitor')
   })
 
+  it('reports a createIfAbsent race with the unresolved display path', async () => {
+    const realDirectory = join(dir, 'real-workspace')
+    const linkedDirectory = join(dir, 'linked-workspace')
+    await mkdir(realDirectory)
+    await symlink(realDirectory, linkedDirectory, process.platform === 'win32' ? 'junction' : 'dir')
+    const target = await fs.resolve('linked-workspace/a.txt')
+    fs.internals.inspectTemp = async () => { await writeFile(join(realDirectory, 'a.txt'), 'competitor') }
+
+    await expect(fs.writeText(target, 'ours', { kind: 'createIfAbsent' })).rejects.toMatchObject({
+      code: 'FS_NOT_OBSERVED',
+      message: `cannot overwrite existing "${join(linkedDirectory, 'a.txt')}" without reading it first`,
+    })
+    expect(await readFile(join(realDirectory, 'a.txt'), 'utf8')).toBe('competitor')
+  })
+
+  it('createIfAbsent rejects a competing directory as not a regular file', async () => {
+    const path = join(dir, 'a.txt')
+    const target = await fs.resolve('a.txt')
+    fs.internals.inspectTemp = async () => { await mkdir(path) }
+
+    await expect(fs.writeText(target, 'ours', { kind: 'createIfAbsent' }))
+      .rejects.toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
+    expect((await stat(path)).isDirectory()).toBe(true)
+  })
+
+  it('createIfAbsent rejects and preserves a dangling symbolic link', async () => {
+    const path = join(dir, 'dangling')
+    await symlink(join(dir, 'missing-target'), path)
+    const target = await fs.resolve('dangling')
+
+    await expect(fs.writeText(target, 'ours', { kind: 'createIfAbsent' }))
+      .rejects.toMatchObject({ code: 'FS_NOT_REGULAR_FILE' })
+    await expect(readFile(path, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' })
+  })
+
   it('replaceIfVersion replaces when the version matches', async () => {
     await writeFile(join(dir, 'a.txt'), 'old')
     const target = await fs.resolve('a.txt')
diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts
index 9b62caba3f..13b0edc290 100644
--- a/packages/fs/fs-local/tests/fsio.spec.ts
+++ b/packages/fs/fs-local/tests/fsio.spec.ts
@@ -496,17 +496,77 @@ describe('writeFileAtomic — temp-file safety', () => {
     expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
   })
 
-  it('surfaces a non-collision guarded-create publication failure and cleans staging', async () => {
+  it('maps a non-collision guarded-create publication failure and cleans staging', async () => {
     const file = join(dir, 'a.txt')
     const denied = Object.assign(new Error('link denied'), { code: 'EACCES' })
 
     await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
       linkFile: async () => { throw denied },
-    }, true)).rejects.toBe(denied)
+    }, { displayPath: file })).rejects.toMatchObject({ code: 'FS_IO_ERROR', cause: denied })
     await expect(stat(file)).rejects.toMatchObject({ code: 'ENOENT' })
     expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
   })
 
+  it('maps a guarded-create target-inspection failure and cleans staging', async () => {
+    const file = join(dir, 'a.txt')
+    const linkFailure = Object.assign(new Error('link failed'), { code: 'EIO' })
+    const inspectionFailure = Object.assign(new Error('inspection denied'), { code: 'EACCES' })
+
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      linkFile: async () => { throw linkFailure },
+      inspectPublicationTarget: async () => { throw inspectionFailure },
+    }, { displayPath: file })).rejects.toMatchObject({ code: 'FS_IO_ERROR', cause: inspectionFailure })
+    await expect(stat(file)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
+  })
+
+  it('rejects a guarded-create collision that vanishes before inspection', async () => {
+    const file = join(dir, 'a.txt')
+    const collision = Object.assign(new Error('target existed'), { code: 'EEXIST' })
+
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      linkFile: async () => { throw collision },
+    }, { displayPath: file })).rejects.toMatchObject({
+      code: 'FS_NOT_OBSERVED',
+      message: `cannot overwrite existing "${file}" without reading it first`,
+      cause: collision,
+    })
+    await expect(stat(file)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect((await readdir(dir)).filter(name => name.includes('.tmp'))).toEqual([])
+  })
+
+  it('uses the display path and target type when guarded publication finds a competitor', async () => {
+    const file = join(dir, 'a.txt')
+    const displayPath = join(dir, 'linked-workspace', 'a.txt')
+
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      inspectTemp: async () => { await writeFile(file, 'competitor') },
+    }, { displayPath })).rejects.toMatchObject({
+      code: 'FS_NOT_OBSERVED',
+      message: `cannot overwrite existing "${displayPath}" without reading it first`,
+    })
+    expect(await readFile(file, 'utf8')).toBe('competitor')
+
+    await rm(file)
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      inspectTemp: async () => { await mkdir(file) },
+    }, { displayPath })).rejects.toMatchObject({
+      code: 'FS_NOT_REGULAR_FILE',
+      message: `cannot write "${displayPath}": not a regular file`,
+    })
+    expect((await stat(file)).isDirectory()).toBe(true)
+  })
+
+  it('does not turn post-commit staging cleanup failure into a failed guarded write', async () => {
+    const file = join(dir, 'a.txt')
+    const cleanupFailure = new Error('staging cleanup failed')
+
+    await expect(writeFileAtomic(file, 'ours', undefined, undefined, {
+      removeStagingDir: async () => { throw cleanupFailure },
+    }, { displayPath: file })).resolves.toBeUndefined()
+    expect(await readFile(file, 'utf8')).toBe('ours')
+  })
+
   it.skipIf(!posixModes)('creates new files owner-only by default', async () => {
     const file = join(dir, 'a.txt')
     await writeFileAtomic(file, 'hello', undefined, undefined)

From 39d8678a02138cb27e0b9cc36b6670428dc2ee12 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:40:56 +0800
Subject: [PATCH 481/516] docs(fs): enumerate absence observation paths

---
 docs/subsystems/filesystem.i18n.yaml                 | 4 ++--
 docs/subsystems/filesystem.md                        | 2 +-
 docs/subsystems/filesystem.zh.md                     | 2 +-
 docs/tool-catalog.i18n.yaml                          | 4 ++--
 docs/tool-catalog.md                                 | 2 +-
 docs/tool-catalog.zh.md                              | 2 +-
 packages/fs/fs-policy/README.i18n.yaml               | 4 ++--
 packages/fs/fs-policy/README.md                      | 2 +-
 packages/fs/fs-policy/README.zh.md                   | 2 +-
 packages/fs/fs-sandbox/src/index.ts                  | 4 ++--
 packages/fs/tool-str-replace-editor/README.i18n.yaml | 4 ++--
 packages/fs/tool-str-replace-editor/README.md        | 2 +-
 packages/fs/tool-str-replace-editor/README.zh.md     | 2 +-
 scripts/gen-tool-catalog.ts                          | 2 +-
 14 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 04c08db9a6..f7d59cd66d 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 5d06611cbad2a3f146ddef4dbc96b2b6fc0a5b46
-filesystem.zh.md: 97aac2ee20783787909605d90a94181bf093d78a
+filesystem.md: dd81cc27ad73bab026cd11da6ab184890bb6535d
+filesystem.zh.md: 9589adfaf43c1d5a4bbc8571e70c878770d880b2
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 5d06611cba..dd81cc27ad 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -238,7 +238,7 @@ interface FileReadOutcome {
 
 ## Observed-file state (policy plugin)
 
-Observed state is a `WeakMap<owner, Map<targetKey, FsObservation>>` held inside the `dsh-fs-policy` plugin. Missing map entry means unseen; `{ kind: 'absent' }` means a tool read/view confirmed absence; `{ kind: 'present', version }` means a read, write, or edit observed that version. The write decision maps unseen and absent to `createIfAbsent`, while present maps to `replaceIfVersion`; the edit decision maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. Disposal drops everything (HMR safety), and the policy performs no filesystem I/O.
+Observed state is a `WeakMap<owner, Map<targetKey, FsObservation>>` held inside the `dsh-fs-policy` plugin. Missing map entry means unseen; `{ kind: 'absent' }` means a `read` or `str_replace_editor` `view`, `str_replace`, or `insert` metadata miss confirmed absence; `{ kind: 'present', version }` means a read, write, or edit observed that version. The write decision maps unseen and absent to `createIfAbsent`, while present maps to `replaceIfVersion`; the edit decision maps unseen to `FS_NOT_OBSERVED`, absent to `FS_NOT_FOUND`, and present to its version guard. The owner is derived from the event actor (normally `exec.agent.session`), treated as opaque and never read. Disposal drops everything (HMR safety), and the policy performs no filesystem I/O.
 
 ## Error taxonomy (provider contract)
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 97aac2ee20..9589adfaf4 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -238,7 +238,7 @@ interface FileReadOutcome {
 
 ## 已观测文件状态（策略插件）
 
-已观测状态是 `dsh-fs-policy` 插件内部持有的 `WeakMap<owner, Map<targetKey, FsObservation>>`。映射中没有条目表示未见；`{ kind: 'absent' }` 表示工具的 read/view 已确认缺失；`{ kind: 'present', version }` 表示 read、write 或 edit 观测到该版本。写入决策把未见和缺失映射到 `createIfAbsent`，把存在映射到 `replaceIfVersion`；编辑决策把未见映射到 `FS_NOT_OBSERVED`，把缺失映射到 `FS_NOT_FOUND`，把存在映射到其版本守卫。所有者从事件 actor 推导（通常是 `exec.agent.session`），被视为不透明且从不读取。dispose（资源释放）时丢弃全部数据（HMR（热模块替换）安全），策略不执行任何文件系统 I/O。
+已观测状态是 `dsh-fs-policy` 插件内部持有的 `WeakMap<owner, Map<targetKey, FsObservation>>`。映射中没有条目表示未见；`{ kind: 'absent' }` 表示 `read` 的元数据未命中，或 `str_replace_editor` 的 `view`、`str_replace`、`insert` 命令发生元数据未命中，从而确认缺失；`{ kind: 'present', version }` 表示 read、write 或 edit 观测到该版本。写入决策把未见和缺失映射到 `createIfAbsent`，把存在映射到 `replaceIfVersion`；编辑决策把未见映射到 `FS_NOT_OBSERVED`，把缺失映射到 `FS_NOT_FOUND`，把存在映射到其版本守卫。所有者从事件 actor 推导（通常是 `exec.agent.session`），被视为不透明且从不读取。dispose（资源释放）时丢弃全部数据（HMR（热模块替换）安全），策略不执行任何文件系统 I/O。
 
 ## 错误分类体系（提供方约定）
 
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 752a8f6a9e..1ae1b619f3 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.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 docs/tool-catalog.md
-tool-catalog.md: abcba1ca5dcb148aa0ee5578ff4fd0373993db1d
-tool-catalog.zh.md: 32c761d0d2854bf2310eb0ddb382553575bd4df9
+tool-catalog.md: f6a41da266db6eb2f347fb3c455a67b4dd44c4c0
+tool-catalog.zh.md: b36e8ccf63f4bdde7efca050bd92cbfcb03b3fbb
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index abcba1ca5d..f6a41da266 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -22,7 +22,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session; ConPTY is roadmap work), with native `C:\...` paths and `$env:NAME` variables. |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `process-local temporary Plugin lifecycle` | - | Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes. |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`, `ctx.pty`, `an owning Agent at execution time` | `tool/call`, `PTY shell state`, `tool/result` | - | One owner-isolated persistent bash tool; deployment composition supplies the PTY backend and may override the model-facing environment description. |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after view presence/absence or successful mutation`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after view presence/absence, edit absence, or successful mutation`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
 | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after read presence/absence or successful mutation`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.subprocess`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are unconditional discovery tools that spawn the packaged ripgrep binary (`@vscode/ripgrep`) through ctx.subprocess as ordinary foreground calls (never background tasks) — no host `rg` install and no shell layer. The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`, `terminal_list`, `terminal_open`, `terminal_read`, `terminal_send`, `terminal_signal` | `ctx.tools`, `ctx.pty`, `ctx.systemPrompt`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The six terminal tools are opt-in and complement one-shot bash/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.tasks`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema. |
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index 32c761d0d2..b36e8ccf63 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -24,7 +24,7 @@
 | `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`process-local temporary Plugin lifecycle` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 |
-| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after view presence/absence or successful mutation`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
+| `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after view presence/absence, edit absence, or successful mutation`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
 | `@deepseek-ai/dsh-tool-fs` | `edit`、`read`、`write` | `ctx.tools`、`ctx.fs`、`ctx.systemPrompt` | `tool/call`、`fs/write-intent or fs/edit-intent for mutations`、`fs/observed after read presence/absence or successful mutation`、`tool/result` | - | 先读后写／编辑策略由 `@deepseek-ai/dsh-fs-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。无论是否加载策略插件，上述工具 schema 都完全相同。 |
 | `@deepseek-ai/dsh-tool-fs-search` | `glob`、`grep` | `ctx.tools`、`ctx.subprocess`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 |
 | `@deepseek-ai/dsh-tool-pty` | `terminal_close`、`terminal_list`、`terminal_open`、`terminal_read`、`terminal_send`、`terminal_signal` | `ctx.tools`、`ctx.pty`、`ctx.systemPrompt`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 |
diff --git a/packages/fs/fs-policy/README.i18n.yaml b/packages/fs/fs-policy/README.i18n.yaml
index e316171061..65239a6f00 100644
--- a/packages/fs/fs-policy/README.i18n.yaml
+++ b/packages/fs/fs-policy/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/fs/fs-policy/README.md
-README.md: 0166690c66f38efe817d8b5779db9a677d22d321
-README.zh.md: 26e0199e6deb7fc12a860ab01884b70c1b7c9b38
+README.md: 395a36e89e113dc3846a8dff62ce90601013addd
+README.zh.md: 5b3b1f64de2d51f6b729392da2d4b459a9f0ca3b
diff --git a/packages/fs/fs-policy/README.md b/packages/fs/fs-policy/README.md
index 0166690c66..395a36e89e 100644
--- a/packages/fs/fs-policy/README.md
+++ b/packages/fs/fs-policy/README.md
@@ -39,7 +39,7 @@ Three `fs/*` events (declared by `@deepseek-ai/dsh-fs`, dispatched by `@deepseek
 
 ## Observed state is the prior-observation record; freshness is provider CAS
 
-Observed state is a weak owner-to-target map with three logical states: unseen, confirmed absent, or present at a version. A successful file read or mutation records presence; a `read`/`view` metadata miss records absence before returning `FS_NOT_FOUND`. The plugin performs no filesystem I/O: it converts that state into a provider guard. Presence supplies the observed version, while absence lets only a `createIfAbsent` write proceed; edit has no version basis and returns `FS_NOT_FOUND`. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
+Observed state is a weak owner-to-target map with three logical states: unseen, confirmed absent, or present at a version. A successful file read or mutation records presence; a metadata miss from `read` or the `str_replace_editor` `view`, `str_replace`, or `insert` command records absence before returning `FS_NOT_FOUND`. The plugin performs no filesystem I/O: it converts that state into a provider guard. Presence supplies the observed version, while absence lets only a `createIfAbsent` write proceed; edit has no version basis and returns `FS_NOT_FOUND`. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
 
 ## Single-slot, first-wins
 
diff --git a/packages/fs/fs-policy/README.zh.md b/packages/fs/fs-policy/README.zh.md
index 26e0199e6d..5b3b1f64de 100644
--- a/packages/fs/fs-policy/README.zh.md
+++ b/packages/fs/fs-policy/README.zh.md
@@ -39,7 +39,7 @@ await ctx.plugin(FsPolicy)
 
 ## 已观察状态是先前观察记录；新鲜度由提供方 CAS 保证
 
-观测状态是一张以所有者为弱键、记录各目标的映射表，具有三种逻辑状态：未见、确认缺失、存在于某个版本。成功读取文件或变更会记录存在；`read`/`view` 的元数据未命中会在返回 `FS_NOT_FOUND` 前记录缺失。插件不执行文件系统 I/O：它把该状态转换为提供方防护。存在状态提供观测到的版本；缺失状态只允许 `createIfAbsent` 写入继续，edit 因没有版本基准而返回 `FS_NOT_FOUND`。窗口读取会观察整个文件的版本，因此只有文件保持不变时才允许后续的定向编辑。插件 dispose（资源释放）时会丢弃状态，并且不会跨会话持久化。
+观测状态是一张以所有者为弱键、记录各目标的映射表，具有三种逻辑状态：未见、确认缺失、存在于某个版本。成功读取文件或变更会记录存在；`read` 的元数据未命中，或 `str_replace_editor` 的 `view`、`str_replace`、`insert` 命令发生元数据未命中时，都会在返回 `FS_NOT_FOUND` 前记录缺失。插件不执行文件系统 I/O：它把该状态转换为提供方防护。存在状态提供观测到的版本；缺失状态只允许 `createIfAbsent` 写入继续，edit 因没有版本基准而返回 `FS_NOT_FOUND`。窗口读取会观察整个文件的版本，因此只有文件保持不变时才允许后续的定向编辑。插件 dispose（资源释放）时会丢弃状态，并且不会跨会话持久化。
 
 ## 单槽、先到者胜
 
diff --git a/packages/fs/fs-sandbox/src/index.ts b/packages/fs/fs-sandbox/src/index.ts
index 1d5f972da9..9884cc5fbd 100644
--- a/packages/fs/fs-sandbox/src/index.ts
+++ b/packages/fs/fs-sandbox/src/index.ts
@@ -76,7 +76,7 @@ export class SandboxedFileSystem extends LocalFileSystem {
    * @param target - the resolved target to write.
    * @param content - the full new file content.
    * @param expected - the write intent guarding the write; omit for unconditional.
-   * @param signal - aborts before the atomic rename takes effect.
+   * @param signal - aborts before atomic publication takes effect.
    * @param sandboxPolicy - the per-call mode and workspace root; omit to use
    *   the deployment fallback.
    * @returns the write outcome from the inherited backend.
@@ -97,7 +97,7 @@ export class SandboxedFileSystem extends LocalFileSystem {
    * @param target - the resolved target to edit.
    * @param edit - the literal search/replace request.
    * @param expected - the version guard; omit for an unconditional edit.
-   * @param signal - aborts before the atomic rename takes effect.
+   * @param signal - aborts before atomic publication takes effect.
    * @param sandboxPolicy - the per-call mode and workspace root; omit to use
    *   the deployment fallback.
    * @returns the edit outcome from the inherited backend.
diff --git a/packages/fs/tool-str-replace-editor/README.i18n.yaml b/packages/fs/tool-str-replace-editor/README.i18n.yaml
index fd61c07154..d5f4b31574 100644
--- a/packages/fs/tool-str-replace-editor/README.i18n.yaml
+++ b/packages/fs/tool-str-replace-editor/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/fs/tool-str-replace-editor/README.md
-README.md: 1d6ce6fd801997dd21973fde1ffded84dbee1b5a
-README.zh.md: 62728659fa8c8173ac42a42610f1a710aec6e386
+README.md: 8b4772cc4eb40e23a5d6ea8e409188b5033318ba
+README.zh.md: b9ccf285870f2d02a2195b70dcd24fd37794976e
diff --git a/packages/fs/tool-str-replace-editor/README.md b/packages/fs/tool-str-replace-editor/README.md
index 1d6ce6fd80..8b4772cc4e 100644
--- a/packages/fs/tool-str-replace-editor/README.md
+++ b/packages/fs/tool-str-replace-editor/README.md
@@ -13,7 +13,7 @@ Standalone model-facing `str_replace_editor` over `ctx.fs`. It can be composed w
 
 ## Tool
 
-The schema provides `view`, `create`, `str_replace`, and `insert` over absolute paths. File views use one-based line numbers and preserve content tabs, so displayed text remains valid literal replacement input; directory views omit hidden, dependency, and Python-cache entries and descend two levels. A missing view records confirmed absence before returning `FS_NOT_FOUND`, so a later `create` can recover an externally deleted path through the mounted policy's guarded-create flow; absence never authorizes `str_replace` or `insert`. Replacement requires one unique literal match and reports errors only in the public `old_str` vocabulary. Insert follows the selected zero-based insertion boundary without adding an implicit trailing newline. Mutations preserve tabs outside the requested edit.
+The schema provides `view`, `create`, `str_replace`, and `insert` over absolute paths. File views use one-based line numbers and preserve content tabs, so displayed text remains valid literal replacement input; directory views omit hidden, dependency, and Python-cache entries and descend two levels. A metadata miss from `view`, `str_replace`, or `insert` records confirmed absence before returning `FS_NOT_FOUND`, so a later `create` can recover an externally deleted path through the mounted policy's guarded-create flow; absence never authorizes `str_replace` or `insert`. Replacement requires one unique literal match and reports errors only in the public `old_str` vocabulary. Insert follows the selected zero-based insertion boundary without adding an implicit trailing newline. Mutations preserve tabs outside the requested edit.
 
 ## Model Experience
 
diff --git a/packages/fs/tool-str-replace-editor/README.zh.md b/packages/fs/tool-str-replace-editor/README.zh.md
index 62728659fa..b9ccf28587 100644
--- a/packages/fs/tool-str-replace-editor/README.zh.md
+++ b/packages/fs/tool-str-replace-editor/README.zh.md
@@ -13,7 +13,7 @@
 
 ## 工具
 
-schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从 1 开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。查看缺失目标时，工具会在返回 `FS_NOT_FOUND` 前记录确认缺失，因此后续 `create` 可以通过已挂载策略的防护创建流程恢复外部删除的路径；缺失状态绝不会授权 `str_replace` 或 `insert`。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
+schema 提供针对绝对路径的 `view`、`create`、`str_replace` 与 `insert`。文件查看使用从 1 开始的行号，并保留内容中的制表符，因此显示的文本仍可作为有效的字面量替换输入；目录查看忽略隐藏、依赖与 Python 缓存条目并下探两层。`view`、`str_replace` 或 `insert` 发生元数据未命中时，工具会在返回 `FS_NOT_FOUND` 前记录确认缺失，因此后续 `create` 可以通过已挂载策略的防护创建流程恢复外部删除的路径；缺失状态绝不会授权 `str_replace` 或 `insert`。替换要求字面量唯一匹配，错误只使用公开的 `old_str` 词汇。插入遵循所选的零基插入边界，不会隐式补尾换行。修改操作会保留请求编辑范围之外的制表符。
 
 ## 模型体验
 
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index cd1cb3c0c1..1ed6c37f40 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -253,7 +253,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     dir: 'tool-str-replace-editor',
     source: 'packages/fs/tool-str-replace-editor/src/index.ts',
     requires: ['ctx.tools', 'ctx.fs'],
-    writes: ['tool/call', 'fs/observed after view presence/absence or successful mutation', 'tool/result'],
+    writes: ['tool/call', 'fs/observed after view presence/absence, edit absence, or successful mutation', 'tool/result'],
     async mount(ctx) {
       await ctx.plugin(LocalFileSystem)
       await ctx.plugin(ToolStrReplaceEditor)

From 9b686a420320b41c8a822535f8aae25c12de9967 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:01:44 +0800
Subject: [PATCH 482/516] ci(wine): bound Node distribution downloads

---
 ...8-08-native-windows-pull-request-ci.i18n.yaml |  4 ++--
 .../2026-08-08-native-windows-pull-request-ci.md |  2 +-
 ...26-08-08-native-windows-pull-request-ci.zh.md |  2 +-
 scripts/wine-windows-gates.sh                    | 16 ++++++++++++----
 4 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index 75d7f8b670..19c54de94b 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: 4e2ea07e90656f212f0613ffa17184ff2c3c8c45
-2026-08-08-native-windows-pull-request-ci.zh.md: 306243af3f3e0b280dd25caa5c99df2176590f3b
+2026-08-08-native-windows-pull-request-ci.md: a1f294b2b9e73a5d14a00780c7b0adfaf58e4702
+2026-08-08-native-windows-pull-request-ci.zh.md: 2c91c21118f5ebbd9f0e341f7d31ec71481db4dc
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 4e2ea07e90..a1f294b2b9 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -10,7 +10,7 @@ The required pull-request Windows verdict needs a fast win32 toolchain signal wi
 
 ## Decision
 
-The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that run the workspace build and production site. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
+The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that runs the workspace build and production site. Node distribution transfers use bounded retries so a stalled download fails or recovers before consuming the job timeout. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
 
 Every pull request also starts an independent `windows-native` job named `windows node 24 / native complete` on GitHub's standard `windows-2025` image. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete` under native PowerShell. The job is deliberately absent from `all-checks-passed.needs`: the aggregate neither waits for it nor changes conclusion because of it, while the native job retains its own unmasked success or failure result.
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 306243af3f..2c91c21118 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
+[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。Node 分发文件传输采用有界重试，使停滞的下载在耗尽作业超时前失败或恢复。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
 
 每个拉取请求还会在 GitHub 标准 `windows-2025` 镜像上启动一个独立的 `windows-native` 作业，名称为 `windows node 24 / native complete`。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并在原生 PowerShell 下运行 `pnpm run check:ci:windows-complete`。该作业被刻意排除在 `all-checks-passed.needs` 之外：聚合流程既不等待它，也不会因它改变结论；原生作业则保留自身未被掩盖的成功或失败结果。
 
diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
index 9bf904a767..d4798fdd7b 100755
--- a/scripts/wine-windows-gates.sh
+++ b/scripts/wine-windows-gates.sh
@@ -74,19 +74,27 @@ trap cleanup EXIT
 mkdir -p "$cache_dir" "$scratch/logs"
 
 # ---- provision Windows Node, boot Wine, snapshot + install concurrently ----
+curl_download_args=(
+  --fail --silent --show-error --location
+  --retry 3 --retry-all-errors --retry-delay 2
+  --connect-timeout 10 --max-time 90 --retry-max-time 240
+)
+
 provision_node() {
   # Latest release of the primary line, checksum-verified against the same
-  # dist directory. Offline runs fall back to the newest cached zip, loudly.
+  # dist directory. Bound and retry every transfer so a stalled nodejs.org
+  # response cannot consume the entire CI job. Offline runs fall back to the
+  # newest cached zip, loudly.
   local version zip
-  version="$(curl -fsSL --max-time 30 https://nodejs.org/dist/index.json 2> /dev/null \
+  version="$(curl "${curl_download_args[@]}" https://nodejs.org/dist/index.json 2> /dev/null \
     | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const v=JSON.parse(d).find(r=>r.version.startsWith('v$node_major.'));if(v)console.log(v.version)})" \
     || true)"
   if [ -n "$version" ]; then
     zip="$cache_dir/node-$version-win-x64.zip"
     if [ ! -f "$zip" ]; then
-      curl -fsSL -o "$zip.tmp" "https://nodejs.org/dist/$version/node-$version-win-x64.zip"
+      curl "${curl_download_args[@]}" -o "$zip.tmp" "https://nodejs.org/dist/$version/node-$version-win-x64.zip"
       local expected
-      expected="$(curl -fsSL "https://nodejs.org/dist/$version/SHASUMS256.txt" \
+      expected="$(curl "${curl_download_args[@]}" "https://nodejs.org/dist/$version/SHASUMS256.txt" \
         | awk -v a="node-$version-win-x64.zip" '$2 == a { print $1; exit }')"
       [ -n "$expected" ] || { echo "wine-windows-gates: no SHASUMS256 entry for node-$version-win-x64.zip" >&2; exit 1; }
       verify_sha256 "$expected" "$zip.tmp"

From dc825be8d874df216d3fcc50bac36149c06568e6 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:05:12 +0800
Subject: [PATCH 483/516] docs: design client conversation node assembly

---
 ...lient-conversation-node-assembly.i18n.yaml |   6 +
 ...08-09-client-conversation-node-assembly.md | 407 ++++++++++++++++++
 ...09-client-conversation-node-assembly.zh.md | 407 ++++++++++++++++++
 3 files changed, 820 insertions(+)
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
 create mode 100644 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
new file mode 100644
index 0000000000..953a049744
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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/architecture/2026-08-09-client-conversation-node-assembly.md
+2026-08-09-client-conversation-node-assembly.md: 0cee5449f651c568dbb87b9cb867eb77b6380184
+2026-08-09-client-conversation-node-assembly.zh.md: 146e8f68a9b1339934040cee62fd46e981145f2a
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
new file mode 100644
index 0000000000..0cee5449f6
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -0,0 +1,407 @@
+# Agent Note: Client Conversation business-node assembly and keyed Chat snapshots
+
+Status: implemented
+
+English | [中文](2026-08-09-client-conversation-node-assembly.zh.md)
+
+## Problem
+
+Client Session owned transport windows, connection state, and pending interactions while also interpreting Assistant, Tool, message, command, compaction, retry, and turn-tail events in a centralized transcript fold. Adding one business node required changes to Session switches, history replay, indexes, caches, and React grouping; business identity, state evolution, and final presentation had no independent owner.
+
+The old path also placed running Assistant and Tool values outside the finalized flow. They entered the log-ordered node list only after settlement, so their React parent changed and remounted them even when the business ID and `key` remained stable. Full history loads, older prepends, live appends, and token streaming used separate update paths, leaving reference stability and local recomputation dependent on specialized caches spread across the client.
+
+Business events also use different correlation models. Tool has call IDs, Assistant correlates by turn and step, Compaction has its own lifecycle and checkpoint, and an Inbox splice represents one instantaneous state in a sequence. Keeping all these distinctions in one fold would make every business change pass through a global lookup and invalidate unrelated caches.
+
+## Decision
+
+Client Runtime provides a target-neutral Conversation Node assembly engine. Business plugins register Event Definitions, and view plugins register per-Session View Builders. `ui-conversation` registers the first built-in Definitions and the `chat` builder; Session only submits the current contiguous Event window to the engine and publishes its snapshot instead of interpreting individual conversation businesses.
+
+The complete derivation, business-by-business validation, and file-level implementation plan remain in [`business-node assembler version one`](../../../../docs/client-conversation-node-engine-rfc.md), [`follow-up design differences`](../../../../docs/client-conversation-node-engine-follow-up-differences.md), [`business-node and dual-view adaptation analysis`](../../../../docs/client-conversation-node-adaptation-analysis.md), and the [`Chat implementation design`](../../../../docs/client-conversation-node-chat-implementation-plan.md). Those design documents retain the full discussion; this Note fixes the responsibilities, algorithms, and trade-offs that remain relevant after implementation.
+
+### Responsibility layers
+
+| Layer | Durable responsibility | Explicitly does not own |
+|---|---|---|
+| Session | Maintain the contiguous Event window, distinguish replace, prepend, and append, and schedule snapshot notifications | Interpret Tool, Assistant, Compaction, or other business events |
+| Event Registry | Retain the unique-`kind` Definitions and sole fallback under Cordis lifecycles | Store one Session's Context or State |
+| Assembler | Match Events and maintain Contexts, Locations, dependencies, and the publication dirty set | Interpret business State fields or Chat ordering |
+| Node Definition | Define one business object's identity, State transitions, Location data, and target Node | Create Contexts, mutate another business's State, or scan all Contexts |
+| View Builder | Incrementally organize final target Nodes into that view's snapshot | Reinterpret raw Session Events |
+| React renderer | Render renderer-owned data by the final Node's `kind` and read business data from the current Node's Location | Pair business Events, scan global Nodes, or decide business lifecycle state |
+
+Registry contributions are Cordis effects. Removing a Definition causes a low-frequency registry rebuild for existing Sessions; ordinary business Events do not change the Registry or rebuild every business type.
+
+### Overall `ConversationNodeDefinition` contract
+
+Each [`ConversationNodeDefinition`](../../../../packages/client/runtime/src/client/contract/conversation.ts) independently owns one business object's conversion from Events to State and final view Nodes. A Definition's `kind` is its unique Registry name and the namespace for its business IDs.
+
+One Event may be claimed by several ordinary Definitions. For example, an Assistant Event updates both the Assistant Node and Turn Tail, while a Retry Event updates Retry, Assistant, and Turn Error. The Assembler asks the fallback only when every ordinary Definition returns `null`.
+
+A Definition holds no mutable business data across Sessions. Each Session's Assembler isolates that Session's Contexts, State, dependencies, and View Builders.
+
+#### `kind`, business ID, and Context key
+
+The `id` returned by `match()` only needs to be stable within its Definition. A Tool ID can be a call ID, an Assistant ID can be `turn:step`, and an Inbox ID can be the splice Event seq.
+
+The Assembler uses `conversationContextKey(kind, id)` to make a collision-free key. Definitions that return the same `id` still do not share a Context. The final view Node must retain this engine-owned key and cannot use `seq` or render position as identity.
+
+Each `(kind, id)` has at most one start Match. A second start fails immediately; a Definition must return a new ID to represent a new lifecycle.
+
+#### `match(event)`
+
+`match(event)` reads only the current raw `SessionEvent` and returns `{ id, role: 'start' | 'update' }` or `null`. It cannot access a Context, history, a Reader, a Location, or the view envelope.
+
+This restriction makes one Event's routing cost depend only on the number of registered Definitions. The Assembler never scans a Definition's historical Contexts to decide which one owns an update.
+
+Start, result, resource, checkpoint, and business-owned terminal Events must carry or directly imply the same ID. If one Event cannot yield that ID, its producer extends the Event protocol; the Client does not guess from the "nearest unfinished object."
+
+The `role` describes the State lifecycle, not visibility. A start may produce a terminal Node immediately, while an update may enter a pending Context before its start has loaded.
+
+#### `ConversationMatch`
+
+After a successful match, the Assembler combines the raw Event, optional wire presentation view, `role`, and engine-computed `location` into a read-only `ConversationMatch`.
+
+A Context's `matches` always remain in ascending Event `seq` order, not network arrival or pagination ingestion order. If a tail page supplies a result before an older page supplies its call, the final Match order still places the call before the result.
+
+Location can change when prepend fills a boundary or append closes one. The Assembler replaces the affected Matches' read-only Locations and replays the Context; business code does not retain an old Location copy as authority.
+
+#### `ConversationNodeContext`
+
+| Field | Owner | Semantics visible to the Definition |
+|---|---|---|
+| `key` | Assembler | Stable final identity derived from `kind + id` |
+| `kind` / `id` | Definition + Assembler | Current business namespace and business ID |
+| `matches` | Assembler | Complete business evidence loaded in the current window and sorted by `seq` |
+| `start` | Assembler | Unique start Match, or `undefined` before it loads |
+| `state` | Returned by Definition, held by Assembler | Most recent `start`/`update` return value, or `undefined` before initialization |
+| `current` | Assembler | Most recently materialized Node or `null` for each target |
+
+Read-only Context fields do not require deeply immutable business State. A Definition may return a new object or mutate the old object in place and return the same reference.
+
+The Assembler adopts only the returned value. Returning `undefined` from `start()` or `update()` is a contract error and fails immediately; mutating an object without returning it is likewise invalid.
+
+A Definition may inspect all `matches` to help construct State or a fallback Node, but it cannot add or remove Matches, replace Context fields, or mutate another Context.
+
+#### `start(context, match, reader)`
+
+`start()` is the sole State initialization entry point. The Assembler invokes it when the unique start first appears and adopts its returned State.
+
+When an older page changes Match order, the Reader's predecessor answer, or Location facts, the Assembler recomputes from `start()` instead of applying a reverse-direction patch to old State.
+
+The Context may already contain updates after the start when `start()` runs. After `start()` returns initial State, the Assembler still invokes `update()` for every post-start Match in ascending log order, so ingestion direction cannot change the final fold.
+
+The `reader` is available only in `start()`. Initialization can read the nearest active Context of a specified `kind` strictly before the current start seq, but business code receives no general interface for scanning internal engine Maps.
+
+Each new `start()` invocation replaces the Reader dependencies recorded by the prior invocation, so a Definition that changes its query branch retains no stale edges.
+
+#### `reader.previous(kind)`
+
+`reader.previous(kind)` finds the nearest Context whose `candidate.startSeq < current.startSeq` and whose State is initialized. It never returns a Context at the same seq, a future Context, or a pending Context without State.
+
+The result contains the predecessor's key, kind, ID, start seq, read-only State, and Matches. The consumer interprets that State itself; the provider only maintains its State correctly and need not register a specialized query method.
+
+Each Reader query records a `{ key, revision, windowGap }` dependency. A matched predecessor's revision change replays the consumer; a miss while older history remains records a window gap for a later prepend.
+
+When the window already reaches the Session beginning, a miss is a definitive `undefined`. When `hasMore` is true, the Definition sees the same `undefined`, but the Assembler remembers that the result is provisional.
+
+Dependencies point strictly from earlier starts to later starts, so transitive replay cannot form a temporal cycle. Both the Inbox instantaneous-state chain and Message reads of Inbox use this constraint.
+
+#### `update(context, match)`
+
+`update()` handles a post-start Match that `match()` has already routed exactly to the current `(kind, id)`. It does not decide which Context owns the Event.
+
+The Assembler invokes `update()` in ascending `seq` order. A live tail update can apply incrementally; any non-tail insertion, newly loaded start, or invalidated dependency causes a complete replay from `start()`.
+
+When no business data changes, `update()` returns the existing State. When data changes, it may return an immutable replacement or mutate the existing object and return that object.
+
+The Assembler does not use State reference equality to decide publication or propagation. Every accepted update increments the Context revision, marks it dirty, and causes direct or transitive Reader consumers to be reevaluated.
+
+#### `publication(match)`
+
+`publication()` controls when the latest State materializes as a view Node; it does not delay the synchronous execution of `match()`, `start()`, or `update()`.
+
+| Return value | Behavior |
+|---|---|
+| `immediate` | Request a notification and flush in the current microtask |
+| `animation-frame` | Coalesce high-frequency updates into materialization on the next frame |
+| `none` | Do not schedule a flush for this Match; retain its State and dirty marker |
+
+Omitting `publication()` means `immediate`. Assistant token deltas use `animation-frame`, invisible Inbox Contexts use `none`, and finals, dependency replays, and Location boundaries publish the latest result through an immediate path.
+
+Every delta within a frame still executes update. Only `buildViewNode()`, View Builder work, and React snapshot notification are coalesced; no tokens are lost.
+
+#### `buildLocationData(context, scope)`
+
+`buildLocationData()` lets a Definition publish a read-only value derived from its State onto an engine-owned Step or Turn without exposing another business's mutable State. The Assembler always materializes `step` before `turn`, so Turn-level aggregation can read Step data updated in the same flush; it calls `buildViewNode()` only after all Location data is ready.
+
+A Definition receives the `step` and `turn` scopes separately and may return one value or `null` in either phase. A value must identify the exact turn/step coordinates and use the Definition's `kind` as its key. The Assembler owns replacement and removal and rejects another Context that claims the same Location key.
+
+`ConversationStepDataMap` and `ConversationTurnDataMap` use declaration merging to constrain keys and values. A Location exposes only a stable `data.get(key)` reader; consumers cannot obtain the provider Context or mutate its State.
+
+#### `buildViewNode(context, target)`
+
+`buildViewNode()` reads the latest Context during publication and directly produces the final business Node for the named target. The Assembler adds no generic activity, tail-candidate, or layout business layer afterward.
+
+`null` means this Context has not yet materialized for the target. On the ordinary incremental path, a Context that has returned a non-null Node cannot later return `null`; temporary absence retains the same-key Node and uses the target's visibility representation.
+
+The Assembler verifies `node.key === context.key` and `node.target === target`. Business code may change `anchorSeq`, data, Location, or visibility, but cannot change identity within one lifecycle.
+
+`current` lets a Definition distinguish "never materialized" from "already materialized and now hidden." Assistant retry and Turn Error suppression use it to avoid illegal Node withdrawal.
+
+A Definition may branch by target to construct different data, while matching, Context identity, and State remain target-neutral. This change registers only the `chat` builder; Trajectory continues to consume the compatibility slice.
+
+#### No generic `end()`
+
+The engine exposes no fixed `end()` lifecycle. A single-Event business completes in `start()`, a multi-Event business records completion in its own update, and a long-lived instantaneous-state business creates a new Context for every Event.
+
+Step and Turn closure are external Location facts and do not mutate business State. A boundary change replays and builds affected Contexts; each business combines its own completion State with whether its Location is closed to produce normal, running, or interrupted presentation.
+
+IDs are never reused. Completed Contexts remain in the current window, providing stable render identity and possible predecessor evidence for later Readers.
+
+### Location is a first-class engine fact
+
+[`ConversationLocationIndex`](../../../../packages/client/runtime/src/client/sessions/conversation-location-index.ts) maps Events to Locations from `turn/start`, `step/start`, explicit turn and step payloads, `step/end`, and `turn/end`.
+
+Location has four shapes: `session`, `turn`, `step`, and `unresolved`. Turns and Steps each carry `open`, `closed`, or `unknown` status plus any loaded start and end Events.
+
+Each Turn and Step also carries a reference-stable Location data store. A Definition update replaces only its owned key; the same store identity can acquire new values through append or prepend, allowing Contexts, View Builders, and React renderers to share resolved hierarchy-level business facts without copying or scanning the global Node array.
+
+`unresolved` means the current history window lacks sufficient preceding boundaries; it does not mean session-level. When older prepend supplies those boundaries, the index corrects Match Locations and replays only Contexts that own those seqs.
+
+An appended ordinary Event only inherits current coordinates, while an appended boundary recalculates only its owning Turn. Prepend rebuilds Location facts from the expanded contiguous window, but reference-stability logic retains unchanged Turn and Step objects.
+
+The Assembler also passes a reference-stable timeline to each View Builder. Businesses do not separately maintain turn order, step lists, last-step values, or boundary Maps.
+
+## Three Event-window paths
+
+"Backward history scanning" describes the UI loading pages from the newest tail toward the Session beginning; it does not mean a Definition executes `update()` in reverse. Regardless of history API order or page-loading direction, the Assembler canonicalizes each current window and each fresh page in ascending `seq` order.
+
+| Scenario | Input range | Context and State handling | View Builder |
+|---|---|---|---|
+| Initial history tail or resync | Current complete contiguous window | Clear and rebuild all Contexts in ascending `seq` order | `replace()` |
+| Load one older-history page | Only deduplicated fresh Events before the window | Retain existing Context identity, then add Matches, Locations, dependencies, and local replays | `apply(upserts)` |
+| Live append | One contiguous tail Event | Match Definitions and update only the exact IDs; boundaries affect only their owning Turn | `apply(upserts)` |
+
+### Initial history tail and logical backward scanning
+
+1. `Session.open()` loads the latest tail page and passes its contiguous History Entries to `replaceWindow(entries, hasMore)`.
+2. `replaceWindow` clears old Contexts, start-seq indexes, seq reverse indexes, Reader dependencies, and the input Map.
+3. It sorts every entry by Event `seq` and stores the resulting current window.
+4. LocationIndex rebuilds Turn and Step facts for that window.
+5. The Assembler visits Events in ascending order and invokes every ordinary Definition's `match(event)`.
+6. Each result gets or creates its `(kind, id)` Context and enters that Context's ordered Match array.
+7. A start runs `start()`; a tail update on initialized State runs `update()` directly.
+8. If the page contains only a result or resource and omits its start, the ID still creates a Context and collects Matches, while State remains `undefined`.
+9. After matching all Events, the Assembler rechecks Reader dependencies so earlier instantaneous states in the same window stabilize before later consumers read them.
+10. Every Context becomes dirty, and the next flush fully rebuilds Location data in Step→Turn order before invoking `buildViewNode()` for every target.
+11. Some businesses return `null` without a start; Compaction, Command, Tool result, and Turn Error can construct fallback Nodes from sufficient update evidence.
+12. Each View Builder receives the complete Node set and timeline and establishes the initial snapshot through `replace()`.
+
+This path starts from the newest page only at the pagination layer. State within the page always computes forward, so the same window does not produce different business results under a different scan direction.
+
+A Context without a start is not an error. It is a pending aggregation container waiting for an older page; that Definition's `buildViewNode()` decides whether the evidence already makes it visible.
+
+If an update with the same ID is genuinely earlier than the start in log order, rather than merely loaded first, replay fails with a protocol error after the start arrives. Arrival order may be reversed; business log order may not.
+
+### Prepending a newly loaded older page
+
+1. `Session.loadOlder()` requests the immediately preceding page using the current `baseSeq` and first verifies continuity between the page tail and current window.
+2. Session prepends the raw Event and view arrays to its own window and passes only that page to `assembler.prepend(entries, hasMore)`.
+3. The Assembler removes seqs that overlap the current window, then sorts the fresh page internally in ascending order.
+4. Existing Contexts, State, current Nodes, and View Builder instances remain intact.
+5. LocationIndex rebuilds facts over the expanded complete input and reports seqs whose Location identity actually changed.
+6. Contexts owning those seqs update their Match Locations and replay from start; unrelated Contexts do not join Location replay.
+7. Fresh Events run Definition matchers and enter existing or new Contexts by stable ID.
+8. If the new page supplies a pending Context's start, that Context initializes from the start and then applies every already-collected update in ascending order.
+9. If the page establishes a nearer Reader predecessor, changes a predecessor revision, or removes a window gap, the consumer recomputes from `start()`.
+10. Reader dependencies propagate replay toward later start seqs; no Event is applied in reverse within the propagation batch.
+11. An empty page that changes `hasMore` from true to false also rechecks dependencies and resolves a provisional `undefined` to definitive absence.
+12. The flush republishes Step/Turn Location data and target Nodes only for dirty Contexts, then passes non-null results to View Builder `apply()` as `upserts`.
+
+Prepend retains existing Context keys and current Node identity. A page may add historical keys at the front of Chat `order` or correct an existing Node's anchor, Location, visibility, or data, but it does not recreate unrelated business Contexts.
+
+On a structural change, the Chat Builder recomputes visible `order` and the secondary Location index from its keyed store. That is view-index work; it neither reruns every business Definition nor replaces unchanged Node values.
+
+Reader gap repair is the largest algorithmic difference between prepend and ordinary append. A page can both add visible historical Nodes and change later Inbox instantaneous states and the Message classifications that depend on them.
+
+### Forward live append
+
+1. Session accepts only a live Event immediately after the current tail seq; it deduplicates overlap and runs tail-page repair before accepting a gap.
+2. A non-boundary Event enters the current Turn and Step coordinates incrementally; a boundary Event updates Location facts for its owning Turn.
+3. The Assembler invokes `match()` once on every ordinary Definition for this Event and scans no Definition's Context set.
+4. Each successful result directly locates one Context through `(kind, id)`.
+5. A new ID creates a Context; a normal tail update for an existing ID invokes `update()` once.
+6. A start or any evidence inserted before the tail uses complete `replayContext()` and retains the same forward-order semantics.
+7. After a Context revision changes, only recorded Reader dependents replay.
+8. Location close updates affected Matches within its owning Turn and replays those Contexts, allowing unfinished Assistant, Tool, or Retry values to acquire interrupted or cancelled presentation.
+9. The Assembler takes the highest publication urgency among all matching Definitions: `immediate` outranks `animation-frame`, which outranks `none`.
+10. Session routes immediate work to the microtask notifier and animation-frame work to the RAF notifier.
+11. The flush updates Step/Turn Location data for dirty Contexts, then invokes `buildViewNode()` and passes this transaction's upserts and latest timeline to each View Builder.
+12. The new React snapshot reuses stable Context keys; the same Tool running→settled or Assistant streaming→final value never moves across parents.
+
+Append's business-matching cost is the Definition count plus the Contexts actually updated, independent of historical Context count. Reader consumers and Location closure add replay proportional to real dependencies or the owning Turn.
+
+A structural Chat `order` change can still reorder the current visible keys. A data-only update replaces one keyed-store Node and touches its Location index. The guarantee is that unrelated businesses do not refold and unchanged Node identity is retained, not that every view-index operation has constant complexity.
+
+### Consistency across replace, prepend, and append
+
+All three paths preserve the same invariants: Context Matches are seq-ordered, State folds forward from one unique start, Reader sees only strictly preceding active Contexts, Location data publishes in Step→Turn order, and Node key depends only on kind and ID.
+
+`replaceWindow` is the low-frequency complete replacement for initial open, resync, gap repair, and registry changes; it does not implement ordinary load older. Both `prepend` and `append` retain existing Builder and Context identity.
+
+Page size, the number of history loads, and RAF coalescing affect only when evidence arrives or publishes. They do not change final Context State and Nodes for an equal Event window.
+
+## How built-in businesses use Definitions
+
+### Matching, ID, and State
+
+| Business / `kind` | Stable ID | Start Match | Update Matches | State and cross-Context reads |
+|---|---|---|---|---|
+| Next-turn Inbox / `inbox-next-turn` | Splice Event seq | Each `agent/inbox/spliced` targeting next-turn | None | Apply the current splice to the pending/claimed instantaneous state from `reader.previous(ownKind)` |
+| Next-step Inbox / `inbox-next-step` | Splice Event seq | Each `agent/inbox/spliced` targeting next-step | None | Build the same per-instruction instantaneous state; Message reads its claimed set |
+| Message / `input-message` | Message ID | Append-surface `user/message` | None | Use source for a context message, or read the nearest next-step Inbox to distinguish user from steering |
+| Assistant / `assistant-step` | `turn:step` | `step/start` | `assistant/chunk`, final `assistant/message`, and same-step Retry | Aggregate blocks, usage, first-token time, final evidence, and retry-hidden state, then publish same-key Step data |
+| Tool / `tool-call` | Root call ID | Root `tool/call` | Root result and Code Dispatch start/result | Aggregate the root, children, and parent Map; Dispatch Events route exactly through `rootCallId` |
+| Command / `command` | Command ID | `command/run` | `command/done` and compact lifecycle/checkpoint Events carrying a source command ID | Aggregate command outcome and manual-compaction evidence |
+| Automatic Compaction / `compaction` | Compaction ID | `compact/start` without a source command ID | Summary, end, and replacement checkpoint | Aggregate summary/checkpoint; sufficient checkpoint evidence supports fallback without a start |
+| Retry / `model-retry` | Retry ID | Attempt 1 `llm/retry` | Later `llm/retry` and `llm/retry-started` | Aggregate one RetryId's attempts and scheduled/started state |
+| Turn Error / `turn-error` | Turn number | `turn/start` | Error `turn/end` and Retry Events for that Turn | Aggregate terminal failure and use Retry evidence to decide hiding |
+| Turn Tail / `turn-tail` | Turn number | `turn/start` | Assistant, Retry, `step/end`, and `turn/end` | Retain turn end, read each Step's Assistant data, and publish Turn data; use complete Matches to choose the visual tail anchor |
+| Deliverables / `deliverables` | Turn number | `turn/start` | Tool calls/results in that Turn | Aggregate successful mutation paths and publish Turn data without producing a view Node |
+| Unknown fallback / `unknown-surface` | Event seq | Append-surface Event unclaimed by any ordinary Definition | None | Retain raw type/data for the JSON fallback |
+
+### Chat Node and history/live behavior
+
+| Business | `publication()` | Chat output | History and runtime behavior |
+|---|---|---|---|
+| Inbox | `none` | No Node | Recompute instantaneous states along the Reader chain when prepend supplies earlier splices |
+| Message | Immediate by default | `user`, `steering`, or `context` | Window-gap repair can reclassify the same message key |
+| Assistant | RAF for chunks, immediate for final, none for pure usage/finish | Same-key `assistant-step` with running/settled/interrupted status | Matches support fallback without `step/start`; Location close produces interruption presentation |
+| Tool | Immediate by default | One recursive `tool-call` root containing all `subCalls` | A result-only history window supports fallback; running→settled retains its key |
+| Command | Immediate by default | Ordinary `command` or integrated `manual-compaction` | Checkpoint arrival may change the anchor without changing the Context key |
+| Compaction | Immediate by default | `compaction` marker | A checkpoint may render before start; an older start triggers forward replay |
+| Retry | Immediate by default | One `model-retry` Node containing all attempts | Multiple retries update one key; Location close presents the last scheduled attempt as cancelled |
+| Turn Error | Immediate by default | Visible or hidden `turn-error` | Error end supports fallback without start; later Retry keeps the key and hides it |
+| Turn Tail | Immediate only for `turn/end`; otherwise none | Independent `turn-tail` footer | Compute closing/metrics from Step Assistant data and use same-turn Matches to choose the anchor |
+| Deliverables | Immediate by default | No Node | Tool settlement incrementally updates Turn data; the Turn Tail extension slot reads produced files |
+| Fallback | Immediate by default | `unknown` JSON row | Covers only append-surface Events; an ordinary business that claimed but has not rendered an Event does not duplicate it |
+
+Inbox demonstrates that every Event can be a start-only instantaneous-state Context; not every business requires a start/update pair. Reader links each state to the prior same-kind Context instead of inventing a lifecycle ID for the entire Inbox.
+
+Assistant, Turn Tail, and Turn Error demonstrate independent claims on one Event. Each Definition updates only its own State and produces its own atomic Chat Node.
+
+Assistant, Turn Tail, and Deliverables demonstrate layered Location data composition. Assistant writes `assistant-step` data for each Step; Turn Tail derives `turn-tail` data from those Step values; Deliverables independently maintains `deliverables` data for the same Turn. Consumers read only declaration-merged keys, do not scan another business's Nodes, and cannot obtain the provider's Context State.
+
+Tool and Command demonstrate multi-Event aggregation: the producer supplies a shared ID, and the Context builds a tree or integrates Compaction internally instead of pushing pairing into the Chat Builder.
+
+Compaction and historical Tool results demonstrate business fallback without a start. The engine does not impose "no start means no rendering"; each Definition decides whether current Matches are sufficient.
+
+Retry demonstrates the State and Location split. Scheduled and started belong to Retry State, while Step and Turn closure belong to engine Location; `buildViewNode()` combines them into cancelled presentation.
+
+Unknown fallback demonstrates Registry ownership: it handles only append-surface Events unclaimed by every ordinary matcher, and does not create a duplicate Node merely because a claimed Context temporarily returns `null`.
+
+## View Builder and React identity
+
+[`ConversationViewRegistry`](../../../../packages/client/runtime/src/client/conversation/view-registry.ts) creates an independent per-Session builder for each target. The Registry stores factories and shares no Session's ordering or caches.
+
+The Assembler calls `replace({ nodes, timeline })` on low-frequency complete replacements and `apply({ upserts, timeline })` for ordinary prepend/append flushes. Builders receive only final target Nodes already constructed by Definitions.
+
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) maintains `order`, a keyed `nodes` store, the turn/step `locations` index, `timeline`, and the `legacy` slice temporarily consumed by Trajectory.
+
+Only a new key or a change to `anchorSeq`, visibility, or Location identity makes a Chat update structural. An ordinary content change does not rebuild `order`; the keyed Node store replaces only that key's value.
+
+For a structural change, the Builder computes visible order from current store values and reuses unchanged index arrays by reference. Prepend may add earlier history keys, append may add a key at the tail or its business anchor, and ordering never renames existing keys.
+
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) only traverses `order`. Each [`ChatNodeSeat`](../../../../packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx) remains in the same parent list under its Context key and dispatches the `'conversation.chat.node'` keyed slot by `node.kind`.
+
+[`ChatNodeDataMap`](../../../../packages/client/ui-conversation/src/client/contract/chat-nodes.ts) is a declaration-merged renderer payload registry. Each business module registers its own Definition and keyed renderer; `registerConversationNodes()` and `registerChatNodeRenderers()` only assemble those independent contributions and do not interpret business through a closed union or central switch. Built-ins still live in `ui-conversation`, but this type and registration boundary allows a business to move into an independent package without changing the Chat dispatcher.
+
+The Chat entry in `conversation.view` registers `ChatNodeTurnDataInjected` once when it declares the `conversation.chat.node` child slot. `ChatNodeSeat` passes only the stable Node key as `hookContext`; the Slot renderer combines that key with `useSession` from the official standard props to construct `useTurnData(businessKey)`. Every keyed Chat renderer therefore reads strongly typed, read-only data from its own Node's Turn, and the Assistant renderer has no special injection authority.
+
+Slot-level contextual Hooks and entry-owned `inject.hooks` remain independent paths. The latter continues to bind only registration-owned Observables. The former caches definitions by stable slot-inject-face identity and binds its factory and Hook per stable render occurrence. The selector inside `useTurnData()` returns only the current Node's `turn.data.get(key)`, so selector equality filters unrelated Session publications.
+
+The standard `useSession` remains available to every session-scoped slot renderer. `useTurnData()` narrows the common read path rather than acting as a permission sandbox. Whole-window statistics or arbitrary object indexes may still read the Session snapshot explicitly, but they are not modeled as current-Node Turn data.
+
+Assistant streaming to final and Tool running to settled update only one Seat's data and necessary ordering properties. They no longer move from a tail running container into finalized flow, so settlement does not reset component-local State.
+
+When business logic deliberately changes a materialized Node to hidden, it leaves visible order and remounts when visible again. This is explicit business withdrawal of presentation, distinct from the stable-Seat guarantee for running→settled.
+
+The concrete Tool renderer remains governed by the [`ui-tool ownership decision`](2026-08-08-client-tool-presentation-ownership.md). Tool Definition supplies recursive root/subcall data, and `ui-tool` dispatches concrete presentation by the Tool-name keyed slot.
+
+Trajectory has no independent registered target yet. It continues to consume the legacy slice incrementally derived by the Chat Builder, while Session no longer runs a second transcript fold; a future migration does not change the Event Definition, Context, Reader, or Location contracts.
+
+## Runtime and render path
+
+```text
+Session Event window
+  -> ConversationNodeAssembler
+       -> Definition.match(event) -> (kind, id, start/update)
+       -> Context matches + State + Location
+       -> Definition.buildLocationData(step -> turn)
+            -> StepLocation.data / TurnLocation.data
+       -> Definition.buildViewNode(target = chat)
+  -> ChatSnapshotBuilder
+       -> order[] + keyed Node store + Location index + timeline
+  -> ChatView
+       -> ChatNodeSeat(key)
+       -> conversation.chat.node(entryKey = node.kind, hookContext = key)
+            -> slot-level useTurnData(businessKey)
+```
+
+## Verification
+
+Runtime tests pin Definition lifecycle registration, exact-ID append, update-before-start collection followed by forward replay after start, prepend identity, Reader window-gap repair, transitive dependencies, Location closure, Step→Turn data phase order, Location data replacement, publication cadence, illegal withdrawal, and per-target Builders.
+
+Conversation tests cover every built-in Definition, Assistant Step data, Turn Tail and Deliverables Turn data, Chat ordering and structural sharing, selector isolation, Assistant and Tool running-to-settled identity, nested Code Dispatch, steering, Compaction, Retry, interruption, load-older anchoring, and slot dispatch.
+
+Slot type/runtime tests pin required parent-provided common inject, the `hookContext` type, Hook isolation across Node contexts, stable factory/Hook identity, and the absence of business-renderer rerenders for unrelated Session publications. Existing entry-owned Observable Hook tests continue to pin the path that does not use a contextual factory.
+
+Assembled Web snapshots, GUI tests, and browser scenarios cover the real plugin graph. Browser evidence compares Assistant streaming→settled, Bash running→settled, and Code Mode root + nested subcalls against master layout.
+
+History-path tests cover complete replace, non-overlapping prepend, overlapping-seq deduplication, empty-page `hasMore` convergence, and live append. Equal Event windows ingested through different paths produce equal business State and final Nodes.
+
+## Alternatives considered
+
+**Keep the centralized Session transcript fold and extract only helpers.** Rejected: business identity, history replay, and cache invalidation would still belong to one closed switch; moving functions would not establish independent ownership.
+
+**Let React renderers scan Session Events.** Rejected: every view would duplicate matching and lifecycle State, React would become business authority, and paging and streaming would recompute unrelated component trees.
+
+**Pass global Nodes or Location indexes to every business renderer.** Rejected: business components would scan and infer their current Turn/Step, and their subscription scope would grow with the window. A Definition publishes aggregates onto an engine-owned Location, and a renderer reads only its own Node's Location data.
+
+**Call every Context of a Definition for each new Event.** Rejected: append cost would grow with history, and `update()` would combine matching with conversion. Context-free `match(event)` finds the ID first, after which only one Context updates.
+
+**Let a Definition matcher read Contexts or scan history.** Rejected: matching would depend on ingestion direction, result-first history pages could not determine ownership independently, and live append would regress to searching open objects.
+
+**Define a reverse State fold for backward history scanning.** Rejected: every business would maintain two inverse algorithms, and deletion, non-invertible aggregation, and cross-Context dependencies would be difficult to keep equivalent. Ordered Matches followed by forward replay from start preserve one business meaning.
+
+**Make Inbox a first-class engine concept or one window-wide Context.** Rejected: Inbox is ordinary business State and does not belong in the generic engine. Per-splice instantaneous State plus a strictly backward Reader supports prepend, append, and Message lookup together.
+
+**Register specialized query methods for cross-business reads.** Rejected: consumers would still depend on provider APIs, and each new relationship would expand a central interface. Reader exposes a named kind's read-only predecessor Context; the provider writes useful State and the consumer interprets it.
+
+**Let a Location-data consumer read the provider's Context State directly.** Rejected: the consumer would depend on another business's mutable internal shape and could not express which Turn/Step owns the value. Declaration-merged data maps expose only the provider-selected read-only value and engine-owned coordinates.
+
+**Add generic `end()`, prepared, or window-reset lifecycles.** Rejected: businesses have different completion conditions, and a pagination gap is not a business lifecycle. Business Events update State, Location close triggers replay/build, and Reader dependencies own pagination invalidation.
+
+**Register separate Event Definitions for Chat and Trajectory.** Rejected: identity, State, and Location are target-neutral. `buildViewNode(target)` and each Builder express view differences; Trajectory retains a compatibility slice until its actual migration.
+
+**Add a generic layout model above final business Nodes.** Rejected: activity, tail candidacy, and layout enums would centralize current Chat business semantics in the engine again. Final Nodes carry renderer-required data directly and share only identity, ordering, and Location facts.
+
+**Register the Turn-data Hook only on the Assistant renderer.** Rejected: current-Node Location access is a common capability of the `conversation.chat.node` slot, not one business renderer. The parent Chat entry registers common inject once, and every keyed renderer shares the same strongly typed contract.
+
+**Keep running Assistant or Tool values in an independent tail container.** Rejected: settlement would move them across React parents, and a stable business key could not prevent remount. One keyed order permits data and position changes without changing Seat identity.
+
+## Consequences
+
+A new business node can register its matcher, State transitions, optional Location data, final target Node, and renderer locally without changing Session's business switch. `ChatNodeDataMap` and the Location data maps let a business package merge strongly typed data into the contract; every related Event must still expose a stable ID derivable from that Event alone.
+
+Initial tail, older prepend, and live append share one set of Context invariants. Missing starts, Reader window gaps, unknown Locations, and high-frequency deltas are explicit engine states and require no direction-specific business cache.
+
+Append does not scan historical Contexts; prepend replays only Contexts whose Matches, Locations, or Reader answers actually changed. A structural Chat change may still recompute visible order and indexes, but does not rerun unrelated business folds or replace unchanged Node identity.
+
+Separating State updates from publication cadence folds every Assistant delta while materializing at most once per animation frame. Step or Turn close and final Events can immediately publish the latest State.
+
+Steps and Turns become stable homes for cross-business aggregates. Turn Tail and Deliverables no longer depend on renderers scanning global Nodes; slot-level `useTurnData()` narrows common reads to the current Node's Turn and uses selector equality to isolate unrelated updates.
+
+The cost is new Runtime contracts for Registry, Assembler, Location data, dependency replay, and per-target Builders, plus parent-owned common inject and per-occurrence `hookContext` in UI Slots. Definition authors must understand stable IDs, unique starts, forward replay, Step→Turn publication order, read-only Reader access, and the prohibition on Node withdrawal.
+
+`useTurnData()` does not revoke the standard `useSession` capability from session-scoped renderers, so this boundary relies on API guidance and tests rather than capability isolation. Registry changes remain low-frequency full rebuilds; the Chat Builder still maintains a legacy slice until Trajectory migrates; built-in Definitions currently remain centralized in `ui-conversation`. These compatibility boundaries do not return business interpretation to Session.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
new file mode 100644
index 0000000000..146e8f68a9
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -0,0 +1,407 @@
+# Agent Note: Client Conversation 业务节点组装与 Chat keyed snapshot
+
+Status: implemented
+
+[English](2026-08-09-client-conversation-node-assembly.md) | 中文
+
+## Problem
+
+Client Session 既维护传输窗口、连接状态和待处理交互，也在中心化 transcript fold 中解释 Assistant、Tool、消息、命令、压缩、重试及 turn tail 等业务事件。每增加一种业务节点，都要修改 Session 的 switch、历史 replay、索引、缓存和 React 分组；业务 identity、状态演进与最终展示没有独立所有者。
+
+旧链路还把运行中的 Assistant 和 Tool 放在 finalized flow 之外。它们结算后才进入按日志排序的节点列表，因此 React parent 会改变，即使业务 ID 和 `key` 不变也会重新挂载。全量历史加载、older prepend、实时 append 与 token streaming 又分别走不同更新路径，使引用稳定和局部重算只能靠各处特化缓存维持。
+
+业务事件之间的关联方式并不统一。Tool 有 call ID，Assistant 以 turn/step 关联，Compaction 有独立生命周期和 checkpoint，Inbox splice 则表示一个连续状态的瞬间。把这些差异继续塞进统一 fold，会让任一业务变化都经过全局查表并使无关缓存失效。
+
+## Decision
+
+Client Runtime 提供 target-neutral 的 Conversation Node 组装引擎，业务插件注册 Event Definition，视图插件注册 per-Session View Builder。`ui-conversation` 注册第一批内建 Definition 和 `chat` builder；Session 只负责把当前连续事件窗口送入引擎并发布它的 snapshot，不再解释具体 conversation 业务。
+
+详细的方案推导、逐业务适配和逐文件实施设计保留在 [`业务节点组装器第一版`](../../../../docs/client-conversation-node-engine-rfc.md)、[`后续方案差异`](../../../../docs/client-conversation-node-engine-follow-up-differences.md)、[`业务节点与双视图适配论证`](../../../../docs/client-conversation-node-adaptation-analysis.md) 和 [`Chat 链路工程实施设计`](../../../../docs/client-conversation-node-chat-implementation-plan.md)。这些设计稿保留完整讨论过程；本 Note 固定实现后仍需长期维护的职责、算法和取舍。
+
+### 责任分层
+
+| 层 | 长期职责 | 明确不负责 |
+|---|---|---|
+| Session | 维护连续 Event 窗口，区分 replace、prepend、append，调度 snapshot 通知 | 解释 Tool、Assistant、Compaction 等业务事件 |
+| Event Registry | 按 Cordis 生命周期保存唯一 `kind` 的 Definition 和唯一 fallback | 保存某个 Session 的 Context 或 State |
+| Assembler | 匹配 Event，维护 Context、Location、依赖和发布脏集 | 理解业务 State 字段或 Chat 排序 |
+| Node Definition | 定义一个业务对象的 identity、State 演进、Location data 和 target Node | 创建 Context、修改别的业务 State 或扫描全部 Context |
+| View Builder | 把最终 target Node 增量整理成该视图的 snapshot | 重新解释原始 Session Event |
+| React renderer | 按最终 Node 的 `kind` 展示 renderer-owned data，并读取当前 Node 所属 Location 的只读业务 data | 配对业务 Event、扫描全局 Nodes 或决定业务生命周期 |
+
+Registry 注册是 Cordis effect，Definition 卸载会触发现有 Session 的低频 registry rebuild。普通业务 Event 不改变 Registry，也不会因此重建全部业务类型。
+
+### `ConversationNodeDefinition` 总体契约
+
+每个 [`ConversationNodeDefinition`](../../../../packages/client/runtime/src/client/contract/conversation.ts) 独立拥有一种业务对象从 Event 到 State 和最终 view Node 的转换。Definition 的 `kind` 是 Registry 内唯一名称，也是业务 ID 的命名空间。
+
+同一个 Event 可以被多个普通 Definition 认领。例如一条 Assistant Event 同时更新 Assistant Node 和 Turn Tail；一条 Retry Event 同时更新 Retry、Assistant 和 Turn Error。Assembler 只有在全部普通 Definition 都返回 `null` 时才询问 fallback。
+
+Definition 不持有跨 Session 的可变业务数据。每个 Session 的 Context、State、依赖和 View Builder 都由该 Session 的 Assembler 隔离持有。
+
+#### `kind`、业务 ID 与 Context key
+
+`match()` 返回的 `id` 只要求在当前 Definition 内稳定。Tool 的 ID 可以是 call ID，Assistant 的 ID 可以是 `turn:step`，Inbox 的 ID 可以是 splice Event seq。
+
+Assembler 使用 `conversationContextKey(kind, id)` 组合无碰撞 key；不同 Definition 即使返回相同 `id` 也不会共享 Context。最终 view Node 必须沿用这个 engine-owned key，不能把 `seq` 或渲染位置当 identity。
+
+每个 `(kind, id)` 最多存在一个 start Match。第二个 start 会立即报错；Definition 需要表达新生命周期时必须返回新 ID。
+
+#### `match(event)`
+
+`match(event)` 只读取当前原始 `SessionEvent`，返回 `{ id, role: 'start' | 'update' }` 或 `null`。它拿不到 Context、历史、Reader、Location 或 view envelope。
+
+这项限制使单条 Event 的路由成本只随已注册 Definition 数量增长。Assembler 不会为了判断一条 update 属于谁而遍历该 Definition 的历史 Context。
+
+start、result、resource、checkpoint 及业务自有终止 Event 必须携带或可直接推导同一 ID。若单个 Event 不能算出 ID，生产 Event 的协议负责补足关联字段，Client 不通过“最近一个未完成对象”猜测。
+
+`role` 描述 State 生命周期，不描述可见性。start 可以立即生成 terminal Node；update 也可以在 start 尚未加载时先进入 pending Context。
+
+#### `ConversationMatch`
+
+匹配成功后，Assembler 把原始 Event、可选的 wire presentation view、`role` 和引擎计算的 `location` 组成只读 `ConversationMatch`。
+
+Context 的 `matches` 永远按 Event `seq` 升序保存，而不是按网络到达或分页摄入顺序保存。历史尾页先出现 result、older 页后出现 call 时，最终 Match 顺序仍然是 call 在前、result 在后。
+
+Location 可以随 prepend 补齐边界或 append 关闭边界而改变。Assembler 替换受影响 Match 的只读 Location 并 replay Context；业务不把旧 Location 副本当权威保存。
+
+#### `ConversationNodeContext`
+
+| 字段 | 所有者 | Definition 可见语义 |
+|---|---|---|
+| `key` | Assembler | `kind + id` 的稳定最终 identity |
+| `kind` / `id` | Definition + Assembler | 当前业务命名空间和业务 ID |
+| `matches` | Assembler | 当前窗口已收集且按 `seq` 排序的完整业务证据 |
+| `start` | Assembler | 唯一 start Match；尚未加载时为 `undefined` |
+| `state` | Definition 返回、Assembler 持有 | 最近一次 `start`/`update` 返回值；未初始化时为 `undefined` |
+| `current` | Assembler | 各 target 最近一次 materialize 的 Node 或 `null` |
+
+Context 字段只读，不表示业务 State 必须是深度 immutable。Definition 可以返回新对象，也可以原地修改旧对象后返回同一引用。
+
+Assembler 只采纳函数返回值。`start()` 或 `update()` 返回 `undefined` 是契约错误并立即报错；修改了对象却不返回它同样不成立。
+
+Definition 可以读取完整 `matches` 辅助构造 State 或 fallback Node，但不能增删 Match、替换 Context 字段或修改另一个 Context。
+
+#### `start(context, match, reader)`
+
+`start()` 是 State 的唯一初始化入口。Assembler 首次得到唯一 start 后调用它，并采用其返回 State。
+
+当更早分页改变 Context 的 Match 顺序、Reader 前序答案或 Location 事实时，Assembler 从 `start()` 重新计算，而不是对旧 State 做方向相反的补丁。
+
+调用 `start()` 时，Context 可能已经收集 start 之后的 updates。`start()` 返回初始 State 后，Assembler 仍会从 start 之后按日志正序逐条调用 `update()`，因此摄入方向不会改变最终 fold 结果。
+
+`reader` 只在 `start()` 中可用。它允许初始化逻辑读取严格位于当前 start seq 之前、指定 `kind` 的最近 active Context，但不给业务一个任意扫描引擎内部 Map 的接口。
+
+每次重新调用 `start()` 都会替换上一次调用登记的 Reader 依赖，保证 Definition 改变查询分支时不会保留陈旧边。
+
+#### `reader.previous(kind)`
+
+`reader.previous(kind)` 查找满足 `candidate.startSeq < current.startSeq` 且 State 已初始化的最近 Context。它不会返回同 seq、未来 Context 或尚无 State 的 pending Context。
+
+返回值包含前序 Context 的 key、kind、id、start seq、只读 State 和 Matches。消费者自行解释 State；提供方只负责把自己的 State 维护正确，不需要注册特化 query 方法。
+
+Reader 每次查询都记录 `{ key, revision, windowGap }` 依赖。命中前序 Context 时，其 revision 变化会 replay 消费者；未命中且仍有 older 历史时，window gap 会等待后续 prepend。
+
+若窗口已经到达 Session 起点仍未命中，`undefined` 是确定答案。若 `hasMore` 为 true，Definition 看到的仍是同一个 `undefined`，但 Assembler 会记住这是暂定结果。
+
+依赖严格从较早 start 指向较晚 start，因此传递 replay 不形成时序环。Inbox 瞬间态链和 Message 对 Inbox 的读取都使用这一约束。
+
+#### `update(context, match)`
+
+`update()` 只处理已经由 `match()` 精确路由到当前 `(kind, id)` 的 post-start Match。它不再判断 Event 属于哪个 Context。
+
+Assembler 按 `seq` 升序调用 `update()`。实时尾部 update 可以直接增量应用；任何非尾部证据插入、start 补齐或依赖失效都会从 `start()` 完整 replay。
+
+没有业务变化时，`update()` 返回原 State。存在业务变化时，它可以返回 immutable replacement，也可以原地修改并返回同一对象。
+
+Assembler 不以 State 引用相等判断是否需要发布或传播。每次成功 update 都增加 Context revision、标记 dirty，并使直接或传递 Reader 消费者重新求值。
+
+#### `publication(match)`
+
+`publication()` 只决定最新 State 何时 materialize 成 view Node，不改变 `match()`、`start()` 或 `update()` 的同步执行。
+
+| 返回值 | 行为 |
+|---|---|
+| `immediate` | 请求当前 microtask 通知与 flush |
+| `animation-frame` | 把多条高频更新合并到下一帧 materialize |
+| `none` | 本 Match 不主动安排 flush，State 和 dirty 标记仍被保留 |
+
+省略 `publication()` 等于 `immediate`。Assistant token delta 使用 `animation-frame`，不可见 Inbox Context 使用 `none`，final、依赖 replay 和 Location 边界会以 immediate 路径发布最新结果。
+
+一帧内的每条 delta 仍执行 update；合并的只是 `buildViewNode()`、View Builder 和 React snapshot 通知，不会丢失 token。
+
+#### `buildLocationData(context, scope)`
+
+`buildLocationData()` 让 Definition 把 State 的只读派生值发布到 Engine-owned Step 或 Turn，而不把另一个业务的可变 State 暴露出去。Assembler 在每次 materialize 中固定先处理 `step`、再处理 `turn`，因此 Turn 级聚合可以读取同一轮已经更新的 Step data；全部 Location data 就绪后才调用 `buildViewNode()`。
+
+Definition 分别收到 `step` 和 `turn` scope，可以在任一阶段返回一个值或 `null`。返回值必须声明准确的 turn/step 坐标，并使用与 Definition `kind` 相同的 key；Assembler 拥有替换和移除，并拒绝另一个 Context 占用同一 Location key。
+
+`ConversationStepDataMap` 和 `ConversationTurnDataMap` 通过 declaration merging 约束 key 与 value。Location 只暴露稳定的 `data.get(key)` reader，消费者不能取得提供方 Context 或修改它的 State。
+
+#### `buildViewNode(context, target)`
+
+`buildViewNode()` 在发布阶段读取最新 Context，为指定 target 直接生成最终业务 Node。Assembler 不在它之后附加通用 activity、tail candidate 或 layout 业务层。
+
+`null` 表示该 Context 对这个 target 尚未 materialize。普通增量路径中，一个已经返回过非空 Node 的 Context 不能再返回 `null`；暂时隐藏必须保留同 key Node，并使用 target 自己的 visibility。
+
+Assembler 校验 Node `key === context.key` 且 Node `target === target`。业务可以改变 `anchorSeq`、data、Location 或 visibility，但不能在一次生命周期内改变 identity。
+
+`current` 让 Definition 区分“从未生成”与“已经生成后需要隐藏”。Assistant retry 和 Turn Error suppression 使用它避免非法的 Node 撤回。
+
+Definition 可以针对 target 分支构造不同 data，但匹配、Context identity 和 State 保持 target-neutral。本次只注册 `chat` builder，Trajectory 仍通过兼容 slice 使用结果。
+
+#### 不提供通用 `end()`
+
+引擎不提供固定 `end()` 生命周期。单 Event 业务在 `start()` 中完成，多 Event 业务在自己的 update 中记录完成，长期瞬间态业务则每条 Event 建立新 Context。
+
+Step/Turn 关闭属于外部 Location 事实，不替业务修改 State。边界变化会 replay 并 build 受影响 Context；业务结合“自己的 State 是否完成”和“Location 是否 closed”生成正常、running 或 interrupted 表现。
+
+ID 不复用，完成的 Context 继续存在于当前窗口，既提供稳定渲染 identity，也可以作为后续 Reader 的前序证据。
+
+### Location 是一级引擎事实
+
+[`ConversationLocationIndex`](../../../../packages/client/runtime/src/client/sessions/conversation-location-index.ts) 根据 `turn/start`、`step/start`、显式 turn/step payload、`step/end` 和 `turn/end` 建立 Event 到 Location 的映射。
+
+Location 有 `session`、`turn`、`step` 和 `unresolved` 四种形状。Turn/Step 各自带 `open`、`closed` 或 `unknown` 状态，以及已加载的 start/end Event。
+
+每个 Turn 和 Step 还持有 reference-stable 的 Location data store。Definition 更新只替换自己拥有的 key；同一个 store identity 可以随 append 或 prepend 获得新值，使 Context、View Builder 和 React renderer 共享已经确定的层级业务事实，而不复制或遍历全局 Node 数组。
+
+`unresolved` 表示当前历史窗口缺少足够前序边界，不等于 session-level。older prepend 补入边界后，索引修正 Match Location，并只 replay 拥有这些 seq 的 Context。
+
+Append 普通 Event 只继承当前坐标；append 边界只重算所属 Turn。Prepend 会基于扩展后的完整连续窗口重建 Location facts，但引用稳定逻辑保留未变化 Turn/Step 对象。
+
+Assembler 还把 reference-stable timeline 交给 View Builder。业务不重复维护 turn order、step list、last step 或边界 Map。
+
+## 三种事件窗口链路
+
+“历史反扫”描述 UI 从最新尾页向 Session 起点逐页加载的方向，不表示 Definition 逆序执行 `update()`。无论历史 API 返回顺序或页面加载方向如何，Assembler 对每个当前窗口和每个 fresh page 都按 `seq` 升序 canonicalize。
+
+| 场景 | 输入范围 | Context/State 处理 | View Builder |
+|---|---|---|---|
+| 初始历史尾页或 resync | 当前完整连续窗口 | 清空并按 `seq` 正序重建全部 Context | `replace()` |
+| 加载一页 older history | 只传更早且去重后的 fresh Events | 保留现有 Context identity，补 Match、Location 和依赖后局部 replay | `apply(upserts)` |
+| 实时 append | 一条连续尾部 Event | 只匹配 Definitions 并精确更新命中 ID，边界只影响所属 Turn | `apply(upserts)` |
+
+### 初始历史尾页与逻辑反扫
+
+1. `Session.open()` 拉取最新 tail page，并把连续 History Entries 交给 `replaceWindow(entries, hasMore)`。
+2. `replaceWindow` 清空旧 Context、start-seq 索引、seq 反向索引、Reader 依赖和输入 Map。
+3. 全部 entries 按 Event `seq` 升序排序并写入当前窗口。
+4. LocationIndex 对这个窗口重建 Turn/Step facts。
+5. Assembler 按升序 Event 逐条调用每个普通 Definition 的 `match(event)`。
+6. 每个命中结果按 `(kind, id)` 取得或创建 Context，并把 Match 插入该 Context 的有序数组。
+7. 遇到 start 时执行 `start()`；已有 State 的尾部 update 直接执行 `update()`。
+8. 当前页只含 result/resource 而缺 start 时，Context 仍会按 ID 创建并收集 Matches，但 State 保持 `undefined`。
+9. 全部 Event 匹配后，Assembler 复查 Reader 依赖，使同一窗口内较早瞬间态先稳定、较晚消费者再读取它。
+10. 所有 Context 标记 dirty，下一次 flush 先按 Step→Turn 完整重建 Location data，再对每个 target 调用 `buildViewNode()`。
+11. 某些业务在缺 start 时返回 `null`；Compaction、Command、Tool result 或 Turn Error 等可根据充分 update 证据构造 fallback Node。
+12. 每个 View Builder 收到完整 Node 集和 timeline，通过 `replace()` 建立初始 snapshot。
+
+这条链路“从最新页开始”只发生在分页选择层。页面内部 State 始终正序计算，因此同一个窗口不会因为扫描方向不同产生不同业务结果。
+
+缺 start 的 Context 不是错误。它是等待 older 页补齐的 pending 聚合容器；是否提前可见由该 Definition 的 `buildViewNode()` 决定。
+
+若当前页中的同 ID update 在日志顺序上真的早于 start，而不是仅仅先被加载，补齐 start 后 replay 会报协议错误。到达顺序可以反向，业务日志顺序不能反向。
+
+### 新 older 分页的 prepend
+
+1. `Session.loadOlder()` 以当前 `baseSeq` 拉取紧邻前页，并先验证页尾与当前窗口连续。
+2. Session 把 raw Event/view 数组 prepend 到自己的窗口，只把这一页传给 `assembler.prepend(entries, hasMore)`。
+3. Assembler 按 seq 去掉与当前窗口重叠的 Events，再把 fresh page 内部升序排列。
+4. 已存在的 Context、State、current Nodes 和 View Builder 实例不清空。
+5. LocationIndex 用扩展后的完整输入重建 facts，并报告 Location identity 真正变化的 seq。
+6. 拥有这些 seq 的 Context 更新 Match Location，并从 start replay；无关 Context 不参与 Location replay。
+7. fresh Events 逐条执行 Definition matcher，并按稳定 ID 插入已有或新 Context 的有序 Matches。
+8. 新页补出 pending Context 的 start 时，该 Context 从 start 初始化，再正序应用已经收集的所有 updates。
+9. 新页建立更近的 Reader predecessor、改变 predecessor revision 或消除 window gap 时，消费者从 `start()` 重算。
+10. Reader 依赖沿 start seq 向后传递 replay；同一传播批次不会把 Event 逆序应用。
+11. `hasMore` 从 true 变为 false 的空页也会复查依赖，把暂定 `undefined` 收敛为确定不存在。
+12. flush 只为 dirty Context 重新发布 Step/Turn Location data 和 target Node，并把非空结果作为 `upserts` 交给 View Builder `apply()`。
+
+Prepend 保留已有 Context key 和 current Node identity。新页可以在 Chat `order` 前部增加 key，也可以修正既有 Node 的 anchor、Location、visibility 或 data，但不会为无关业务重新创建 Context。
+
+Chat Builder 遇到结构变化时会从 keyed store 重算可见 `order` 和 Location 二级索引；这是视图索引计算，不会重新执行全部业务 Definition 或替换未变化 Node value。
+
+Reader gap 修复是 prepend 与普通 append 最大的算法差异。新页不仅可能创建可见历史 Node，也可能改变后续 Inbox 瞬间态以及依赖它的 Message 分类。
+
+### 正向实时 append
+
+1. Session 只接受紧邻当前 tail seq 的 live Event；重叠 seq 去重，出现 gap 时先走 tail-page repair。
+2. 非边界 Event 增量写入当前 Turn/Step 坐标；边界 Event 更新所属 Turn 的 Location facts。
+3. Assembler 对这一个 Event 的每个普通 Definition 调用一次 `match()`，不会遍历任何 Definition 的 Context 集合。
+4. 每个命中结果通过 `(kind, id)` 直接定位一个 Context。
+5. 新 ID 创建 Context；已有 ID 的正常尾部 update 直接调用一次 `update()`。
+6. start 或任何需要插入非尾部位置的证据会走完整 `replayContext()`，保持同一正序语义。
+7. Context revision 变化后，只沿已登记 Reader 依赖 replay 消费者。
+8. Location close 会更新所属 Turn 中受影响 Match 的 Location，并 replay 这些 Context，使未完成 Assistant、Tool 或 Retry 得到 interrupted/cancelled 语气。
+9. Assembler 汇总所有命中 Definition 的 publication urgency；`immediate` 高于 `animation-frame`，后者高于 `none`。
+10. Session 把 immediate 交给 microtask notifier，把 animation-frame 交给 RAF notifier。
+11. flush 先为 dirty Context 更新 Step/Turn Location data，再调用 `buildViewNode()`，最后把本轮 upserts 和最新 timeline 交给 View Builder。
+12. React 订阅的新 snapshot 复用稳定 Context key；同一 Tool running→settled 或 Assistant streaming→final 不跨父节点移动。
+
+Append 的业务匹配成本是 Definition 数量加实际命中的 Context 更新，不随历史 Context 数量增长。Reader 消费者和 Location 关闭会增加与真实依赖或所属 Turn 成比例的 replay。
+
+Chat `order` 的结构性变化仍可能重排当前可见 key；纯 data 更新只替换 keyed store 中一个 Node，并 touch 所属 Location 索引。这里保证的是无关业务不 refold、Node identity 不替换，而不是宣称所有视图索引操作都是常数复杂度。
+
+### Replace、prepend 与 append 的一致性
+
+三条链路最终都遵守同一不变量：Context Matches 按 seq 排序，State 从唯一 start 正序 fold，Reader 只看严格前序 active Context，Location data 按 Step→Turn 发布，Node key 只由 kind 和 ID 决定。
+
+`replaceWindow` 是初始打开、resync、gap repair 和 registry 变化的低频完整替换，不用于实现普通 load older。`prepend` 与 `append` 都保留现有 Builder 和 Context identity。
+
+分页页宽、历史加载次数和 RAF 合批只影响何时得到更多证据或何时发布，不改变窗口证据相同时的最终 Context State 与 Node。
+
+## 内建业务如何使用 Definition
+
+### 匹配、ID 与 State
+
+| 业务 / `kind` | 稳定 ID | start Match | update Matches | State 与跨 Context 读取 |
+|---|---|---|---|---|
+| Next-turn Inbox / `inbox-next-turn` | splice Event seq | 每条目标为 next-turn 的 `agent/inbox/spliced` | 无 | 从 `reader.previous(ownKind)` 的 pending/claimed 瞬间态应用当前 splice |
+| Next-step Inbox / `inbox-next-step` | splice Event seq | 每条目标为 next-step 的 `agent/inbox/spliced` | 无 | 同样形成逐指令瞬间态，claimed 集合供 Message 读取 |
+| Message / `input-message` | message ID | append-surface `user/message` | 无 | 根据 source 生成 context message，或读取最近 next-step Inbox 判断 user/steering |
+| Assistant / `assistant-step` | `turn:step` | `step/start` | `assistant/chunk`、final `assistant/message`、同 step Retry | 聚合 blocks、usage、首 token 时间、final 和 retry 隐藏状态，并发布同 key Step data |
+| Tool / `tool-call` | root call ID | root `tool/call` | root result、Code Dispatch start/result | 聚合 root、children 和 parent Map；Dispatch Event 用 `rootCallId` 精确路由 |
+| Command / `command` | command ID | `command/run` | `command/done`、带 source command ID 的 compact lifecycle/checkpoint | 聚合 command outcome 和手动压缩证据 |
+| Automatic Compaction / `compaction` | compaction ID | 无 source command ID 的 `compact/start` | summary、end、replacement checkpoint | 聚合 summary/checkpoint；checkpoint 足够时可在缺 start 下 fallback |
+| Retry / `model-retry` | retry ID | attempt 1 的 `llm/retry` | 后续 `llm/retry` 与 `llm/retry-started` | 聚合同一 RetryId 的 attempts 与 scheduled/started 状态 |
+| Turn Error / `turn-error` | turn number | `turn/start` | error `turn/end` 与该 turn Retry Events | 聚合 terminal failure，并用 Retry 证据决定隐藏 |
+| Turn Tail / `turn-tail` | turn number | `turn/start` | Assistant、Retry、`step/end`、`turn/end` | 保存 turn end，读取各 Step 的 Assistant data，发布 Turn data；完整 Matches 用于选择视觉尾部 anchor |
+| Deliverables / `deliverables` | turn number | `turn/start` | 该 Turn 的 Tool call/result | 聚合成功 mutation paths 并发布 Turn data，不生成 view Node |
+| Unknown fallback / `unknown-surface` | Event seq | 未被普通 Definition 认领的 append-surface Event | 无 | 保存原始 type/data 作为 JSON fallback |
+
+### Chat Node 与历史/实时特性
+
+| 业务 | `publication()` | Chat 产物 | 历史分页与运行时行为 |
+|---|---|---|---|
+| Inbox | `none` | 不生成 Node | prepend 补前序 splice 时沿 Reader 链重算瞬间态 |
+| Message | 默认 immediate | `user`、`steering` 或 `context` | window gap 修复可让同一 message key 重新分类 |
+| Assistant | chunk 为 RAF，final immediate，纯 usage/finish 为 none | 同 key `assistant-step`，状态为 running/settled/interrupted | 缺 `step/start` 可先用 Matches fallback；Location close 生成中断表现 |
+| Tool | 默认 immediate | 一个递归 `tool-call` root，包含全部 `subCalls` | result-only 历史窗口可 fallback；running→settled 保持 key |
+| Command | 默认 immediate | 普通 `command` 或集成 `manual-compaction` | checkpoint 到达可改变 anchor，但不改变 Context key |
+| Compaction | 默认 immediate | `compaction` marker | checkpoint 可先展示，older 补 start 后正序 replay |
+| Retry | 默认 immediate | 一个 `model-retry` Node 内含 attempts | 多次 retry 更新同一 key；Location close 把最后 scheduled 表现为 cancelled |
+| Turn Error | 默认 immediate | `turn-error` visible/hidden | 缺 start 可从 error end fallback；Retry 到达后保留 key 并隐藏 |
+| Turn Tail | 仅 `turn/end` immediate，其余 none | 独立 `turn-tail` footer | 从 Step Assistant data 计算 closing/metrics，并通过同 turn Matches 决定 anchor |
+| Deliverables | 默认 immediate | 不生成 Node | Tool 结算增量更新所属 Turn data，Turn Tail 扩展槽读取 produced files |
+| Fallback | 默认 immediate | `unknown` JSON row | 只兜底 append surface，普通业务已认领但暂不可见时不会重复生成 |
+
+Inbox 展示了“每条 Event 都是一个 start-only 瞬间态 Context”，不是所有业务都需要 start/update 配对。它通过 Reader 与前一个同 kind Context 形成连续 fold，而非给整个 Inbox 人工制造生命周期 ID。
+
+Assistant、Turn Tail 和 Turn Error 展示了同一 Event 被多个 Definition 独立认领。每个 Definition 只更新自己的 State，最终分别生成原子 Chat Node。
+
+Assistant、Turn Tail 和 Deliverables 展示了 Location data 的分层组合。Assistant 负责写好每个 Step 的 `assistant-step` data；Turn Tail 从这些 Step values 计算 `turn-tail` data；Deliverables 独立维护同一 Turn 的 `deliverables` data。消费者只读取声明合并后的 key，不扫描其他业务 Node，也不取得提供方的 Context State。
+
+Tool 和 Command 展示了多 Event 聚合：生产者提供共同 ID，Context 在业务内部构树或整合 Compaction，不把配对工作推给 Chat Builder。
+
+Compaction 和历史 Tool result 展示了缺 start 时的业务 fallback。引擎不统一规定“没有 start 就不渲染”；Definition 根据当前 Matches 是否足够自行决定。
+
+Retry 展示了业务 State 与 Location 的分工。scheduled/started 属于 Retry State；Step/Turn 是否关闭属于引擎 Location；`buildViewNode()` 组合两者得到 cancelled 视觉状态。
+
+Unknown fallback 展示了 Registry ownership：fallback 只处理没有任何普通 matcher 认领的 append surface Event，不会因为普通 Context 暂时返回 `null` 而误生成第二个 Node。
+
+## View Builder 与 React identity
+
+[`ConversationViewRegistry`](../../../../packages/client/runtime/src/client/conversation/view-registry.ts) 为每个 target 创建独立的 per-Session builder。Registry 保存 factory，不共享某个 Session 的排序或缓存。
+
+Assembler 低频完整替换时调用 `replace({ nodes, timeline })`；普通 prepend/append flush 调用 `apply({ upserts, timeline })`。Builder 只接收 Definition 已构造完成的 target Nodes。
+
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) 维护 `order`、keyed `nodes` store、turn/step `locations` index、`timeline` 和 Trajectory 临时使用的 `legacy` slice。
+
+Chat 结构变化只由新 key、`anchorSeq`、visibility 或 Location identity 变化触发。普通内容变化不重建 `order`；keyed Node store 只替换该 key 的 value。
+
+Builder 遇到结构变化时从 store 的当前 values 计算 visible order，并按未变化引用复用索引数组。Prepend 可以增加前部历史 key，append 可以增加尾部或按业务 anchor 落位，既有 key 不因排序变化而重命名。
+
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只遍历 `order`。每个 [`ChatNodeSeat`](../../../../packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx) 以 Context key 固定在同一个父列表中，并按 `node.kind` 分发 `'conversation.chat.node'` keyed slot。
+
+[`ChatNodeDataMap`](../../../../packages/client/ui-conversation/src/client/contract/chat-nodes.ts) 是 declaration-merged 的 renderer payload registry。每个业务模块分别注册自己的 Definition 和 keyed renderer；`registerConversationNodes()` 与 `registerChatNodeRenderers()` 只负责装配这些独立贡献，不通过 closed union 或中心 switch 解释业务。内建实现仍位于 `ui-conversation`，但该类型和注册边界允许业务迁入独立 package 而不修改 Chat dispatcher。
+
+`conversation.view` 的 Chat entry 在声明 `conversation.chat.node` child slot 时统一注册 `ChatNodeTurnDataInjected`。`ChatNodeSeat` 只把稳定 Node key 作为 `hookContext` 传给 slot；Slot renderer 用官方 standard props 中的 `useSession` 和该 key 构造 `useTurnData(businessKey)`，因此每个 keyed Chat renderer 都能读取自己 Node 所属 Turn 的强类型只读 data，Assistant renderer 不拥有特殊注入权限。
+
+Slot-level contextual Hook 与 entry-owned `inject.hooks` 是两条独立路径。后者继续只绑定 registration-owned Observable；前者按稳定 slot inject face 缓存定义，并按稳定 render occurrence 绑定 factory 和 Hook。`useTurnData()` 内部 selector 只返回当前 Node 的 `turn.data.get(key)`，无关 Session publication 会被 selector equality 截断。
+
+标准 `useSession` 仍属于所有 session-scoped slot renderer 的公开能力，`useTurnData()` 是收窄常见读取方式而不是权限沙箱。全窗口统计或任意对象索引仍可显式使用 Session snapshot；它们不能伪装成“当前 Node 的 Turn data”。
+
+Assistant streaming 到 final、Tool running 到 settled 只更新同一个 Seat 的 data 和必要的排序属性，不再从末尾 running container 移入 finalized flow，因此组件内部 State 不因结算自动归零。
+
+业务主动把已发布 Node 改成 hidden 时，它会退出 visible order，恢复 visible 时会重新 mount。这是明确的业务撤显语义，与 running→settled 的稳定 Seat 保证不同。
+
+具体 Tool renderer 仍由 [`ui-tool ownership decision`](2026-08-08-client-tool-presentation-ownership.md) 约束。Tool Definition 只交付递归 root/subcall data，`ui-tool` 再按 Tool name keyed slot 分发具体表现。
+
+Trajectory 尚未注册独立 target。它继续消费 Chat Builder 增量派生的 legacy slice，Session 不再运行第二套 transcript fold；未来迁移不改变 Event Definition、Context、Reader 或 Location 契约。
+
+## Runtime and render path
+
+```text
+Session Event window
+  -> ConversationNodeAssembler
+       -> Definition.match(event) -> (kind, id, start/update)
+       -> Context matches + State + Location
+       -> Definition.buildLocationData(step -> turn)
+            -> StepLocation.data / TurnLocation.data
+       -> Definition.buildViewNode(target = chat)
+  -> ChatSnapshotBuilder
+       -> order[] + keyed Node store + Location index + timeline
+  -> ChatView
+       -> ChatNodeSeat(key)
+       -> conversation.chat.node(entryKey = node.kind, hookContext = key)
+            -> slot-level useTurnData(businessKey)
+```
+
+## Verification
+
+Runtime tests 固定 Definition 生命周期注册、exact-ID append、update-before-start 收集与 start 后正序 replay、prepend identity、Reader window-gap 修复、传递依赖、Location closure、Step→Turn data phase order、Location data replacement、publication cadence、非法撤回和 per-target Builder。
+
+Conversation tests 覆盖全部内建 Definition、Assistant Step data、Turn Tail 与 Deliverables Turn data、Chat 排序和结构共享、selector isolation、Assistant/Tool running-to-settled identity、nested Code Dispatch、steering、Compaction、Retry、interruption、load-older anchoring 和 slot dispatch。
+
+Slot type/runtime tests 固定父注册必须提供声明的 common inject、`hookContext` 类型、不同 Node context 的 Hook 隔离、factory/Hook identity 稳定，以及无关 Session publication 不重渲染业务 renderer。原 entry-owned Observable Hook 测试继续固定未使用 contextual factory 的路径。
+
+Assembled Web snapshot、GUI 和浏览器场景覆盖真实 plugin graph。浏览器证据比较 Assistant streaming→settled、Bash running→settled 以及 Code Mode root + nested subcalls 与 master 的布局。
+
+历史链路验证同时覆盖完整 replace、非重叠 prepend、重叠 seq 去重、空页 `hasMore` 收敛和 live append。相同 Event 窗口通过不同摄入路径得到相同业务 State 与最终 Node。
+
+## Alternatives considered
+
+**保留中心化 Session transcript fold，只抽 helper。** 拒绝：业务 identity、历史 replay 和 cache invalidation 仍属于一个闭合 switch，移动函数不会产生独立所有权。
+
+**让 React renderer 自己扫描 Session Event。** 拒绝：每种 view 都会重复匹配和生命周期 State，React 会成为业务权威，paging 与 streaming 也会重算无关组件树。
+
+**把全局 Nodes 或 Location 索引传给每个业务 renderer。** 拒绝：业务组件会自行扫描和推断当前 Turn/Step，订阅范围随窗口增长。Definition 把聚合值发布到 Engine-owned Location，renderer 只读取自己 Node 的 Location data。
+
+**每个新 Event 都调用同 Definition 的全部 Context。** 拒绝：append 成本随历史增长，`update()` 也会同时承担匹配与转换。无 Context 的 `match(event)` 先算出 ID，随后只更新一个 Context。
+
+**让 Definition 的 matcher 读取 Context 或扫描历史。** 拒绝：匹配将依赖摄入方向，result-first 历史页无法独立算出归属，实时 append 也退化成开放对象查找。
+
+**为历史反扫定义逆向 State fold。** 拒绝：每个业务都要维护互为逆运算的两套逻辑，删除、非可逆聚合和跨 Context 依赖很难保持一致。统一 Matches 后从 start 正序 replay 只有一套业务语义。
+
+**把 Inbox 做成引擎一级公民或一个窗口级 Context。** 拒绝：Inbox 是普通业务状态，不应污染通用引擎；逐 splice 瞬间态加严格前序 Reader 同时支持 prepend、append 和 Message 查询。
+
+**给跨业务查询注册特化 query method。** 拒绝：消费者仍要依赖提供方 API，新增关系会扩张中心接口。Reader 暴露指定 kind 的只读前序 Context，由提供方写好 State、消费者读懂 State。
+
+**让 Location data 消费者直接读取提供方 Context State。** 拒绝：消费者会依赖另一个业务的可变内部形状，也无法表达值属于哪个 Turn/Step。declaration-merged data map 只公开提供方选择发布的只读值和 Engine-owned 坐标。
+
+**增加通用 `end()`、prepared 或 window reset 生命周期。** 拒绝：不同业务完成条件不同，分页缺口也不是业务生命周期。业务 Event 更新 State，Location close 触发 replay/build，Reader dependency 负责补页失效。
+
+**为 Chat 与 Trajectory 注册两套 Event Definition。** 拒绝：identity、State 和 Location 与 target 无关。视图差异由 `buildViewNode(target)` 和各自 Builder 表达；Trajectory 在真正迁移前保留兼容 slice。
+
+**在最终业务 Node 上再叠一层通用 layout model。** 拒绝：activity、tail candidacy 和 layout enum 会把当前 Chat 的业务语义重新集中到引擎。最终 Node 直接携带 renderer 所需 data，只共享 identity、排序和 Location 事实。
+
+**只在 Assistant renderer 注册 Turn data Hook。** 拒绝：访问当前 Node Location 是 `conversation.chat.node` slot 的公共能力，不属于某个业务 renderer。父 Chat entry 注册一次 common inject，所有 keyed renderer 共享同一强类型契约。
+
+**把 running Assistant 或 Tool 保留在独立 tail container。** 拒绝：结算时会跨 React parent 移动，稳定业务 key 也无法阻止 remount。统一 keyed order 允许 data 和排序位置改变，但不改变 Seat identity。
+
+## Consequences
+
+新增业务节点可以局部注册自己的 matcher、State 转换、可选 Location data、最终 target Node 和 renderer，不再修改 Session 的业务 switch。`ChatNodeDataMap` 和 Location data maps 允许业务 package 通过 declaration merging 合入强类型 data；所有相关 Event 仍须暴露可单 Event 推导的稳定 ID。
+
+初始尾页、older prepend 和 live append 共享一套 Context 不变量。缺 start、Reader window gap、Location unknown 以及高频 delta 都是引擎明确表达的状态，不需要业务另建方向相关 cache。
+
+Append 不扫描历史 Context；prepend 只 replay Match、Location 或 Reader 答案真正受影响的 Context。Chat 结构变化仍可能重算 visible order 和索引，但不会重跑无关业务 fold 或替换未变化 Node identity。
+
+State 更新与发布频率分离后，Assistant 每条 delta 都被 fold，同时每 animation frame 最多 materialize 一次。step/turn close 和 final 可立即发布最新 State。
+
+Step/Turn 成为业务间共享聚合的稳定宿主。Turn Tail 和 Deliverables 不再依赖 renderer 扫描全局 Nodes；Slot-level `useTurnData()` 把常见读取限制到当前 Node 所属 Turn，并通过 selector equality 隔离无关更新。
+
+代价是 Runtime 新增 Registry、Assembler、Location data、依赖重放和 per-target Builder 契约，UI Slots 也新增 parent-owned common inject 与 per-occurrence `hookContext`。Definition 作者必须理解稳定 ID、唯一 start、正序 replay、Step→Turn 发布顺序、只读 Reader 和 Node 不撤回规则。
+
+`useTurnData()` 不撤销 session-scoped renderer 的标准 `useSession`，因此该边界依靠 API 引导和测试，而不是能力隔离。Registry 变化仍是低频完整 rebuild；Chat Builder 在 Trajectory 迁移前仍维护 legacy slice；内建 Definitions 暂时集中在 `ui-conversation`。这些是兼容边界，不把业务解释权交还给 Session。

From aa623b6e7ac5c83fa1f2ea4fe80e124b2d5d66bd Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:48:07 +0800
Subject: [PATCH 484/516] refactor(events): add stable conversation correlation
 ids

---
 packages/compact/command-compact/src/index.ts |  2 +-
 packages/compact/compact-basic/package.json   |  2 +
 packages/compact/compact-basic/src/index.ts   |  9 +-
 packages/compact/compact-basic/src/region.ts  | 40 ++++++--
 packages/compact/compact-basic/tsconfig.json  |  3 +
 packages/compact/compact/package.json         |  8 ++
 packages/compact/compact/src/brand.ts         | 13 +++
 packages/compact/compact/src/checkpoint.ts    | 25 +++++
 packages/compact/compact/src/index.ts         |  7 +-
 packages/compact/compact/src/invariant.ts     | 93 ++++++++++++++++++-
 packages/compact/compact/src/types.ts         | 12 ++-
 packages/compact/compact/tsconfig.json        |  6 ++
 packages/compact/compact/tsdown.config.ts     | 13 +++
 packages/core/tools/src/code-mode.ts          |  7 +-
 packages/core/tools/src/index.ts              |  9 ++
 packages/core/tools/src/invariant.ts          | 28 ++++++
 packages/interaction/commands/src/index.ts    |  4 +-
 packages/llm/llm-retry/package.json           |  6 ++
 packages/llm/llm-retry/src/brand.ts           | 13 +++
 packages/llm/llm-retry/src/index.ts           | 36 +++----
 packages/llm/llm-retry/src/invariant.ts       | 37 +++++++-
 packages/llm/llm-retry/src/types.ts           | 12 +++
 packages/llm/llm-retry/tsconfig.json          |  3 +
 23 files changed, 347 insertions(+), 41 deletions(-)
 create mode 100644 packages/compact/compact/src/brand.ts
 create mode 100644 packages/compact/compact/tsdown.config.ts
 create mode 100644 packages/llm/llm-retry/src/brand.ts

diff --git a/packages/compact/command-compact/src/index.ts b/packages/compact/command-compact/src/index.ts
index 4ac171a689..b3f80d87fd 100644
--- a/packages/compact/command-compact/src/index.ts
+++ b/packages/compact/command-compact/src/index.ts
@@ -63,7 +63,7 @@ async function executeCompact(
     return { kind: 'error', text: USAGE }
   }
   try {
-    const result = await ctx.compact.compactNow(invocation.agent, invocation.signal)
+    const result = await ctx.compact.compactNow(invocation.agent, invocation.signal, invocation.commandId)
     if (result === null) return { kind: 'success', text: 'No compactable history yet.' }
     return {
       kind: 'success',
diff --git a/packages/compact/compact-basic/package.json b/packages/compact/compact-basic/package.json
index 2b0624e06e..3fffee14a7 100644
--- a/packages/compact/compact-basic/package.json
+++ b/packages/compact/compact-basic/package.json
@@ -27,6 +27,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-compact": "^0.0.1",
+    "@deepseek-ai/dsh-commands": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
@@ -49,6 +50,7 @@
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
     "@deepseek-ai/dsh-compact": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-retry": "workspace:^",
diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts
index 27b59d0451..d3c710bef3 100644
--- a/packages/compact/compact-basic/src/index.ts
+++ b/packages/compact/compact-basic/src/index.ts
@@ -13,6 +13,7 @@ import type { Session } from '@deepseek-ai/dsh-session'
 import { CONTEXT_WINDOW_EXCEEDED_CODE, assertNever } from '@deepseek-ai/dsh-llm'
 import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
 import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 // Type-only: makes the optional sibling service available to `ctx.get()`.
 import type {} from '@deepseek-ai/dsh-compact-tool-result-prune'
 import {
@@ -361,9 +362,14 @@ export class BasicCompactService extends CompactService {
    * resolve only after its standalone marker pair is durably checkpointed.
    * @param agent - idle agent whose next-turn admission this call reserves.
    * @param signal - cancellation scoped to this compaction request.
+   * @param sourceCommandId - initiating command identity for presentation correlation.
    * @returns the committed result, or `null` when no safe useful range exists.
    */
-  override compactNow(agent: Agent, signal: AbortSignal): Promise<CompactionResult | null> {
+  override compactNow(
+    agent: Agent,
+    signal: AbortSignal,
+    sourceCommandId?: CommandId,
+  ): Promise<CompactionResult | null> {
     signal.throwIfAborted()
     try {
       return agent.runMaintenance(async (agentSignal) => {
@@ -385,6 +391,7 @@ export class BasicCompactService extends CompactService {
             {
               owner: null,
               stability: 'selected-span',
+              ...sourceCommandId === undefined ? {} : { sourceCommandId },
               flush: async () => {
                 await this.ctx.sessions.flush(agent.session)
               },
diff --git a/packages/compact/compact-basic/src/region.ts b/packages/compact/compact-basic/src/region.ts
index b220074e02..ae637d03cc 100644
--- a/packages/compact/compact-basic/src/region.ts
+++ b/packages/compact/compact-basic/src/region.ts
@@ -5,14 +5,17 @@
  * @module @deepseek-ai/dsh-compact-basic/region
  */
 
+import { randomUUID } from 'node:crypto'
 import { isDeepStrictEqual } from 'node:util'
 import {
-  COMPACT_CHECKPOINT_SOURCE,
+  CompactionId,
   ManualCompactionError,
+  compactCheckpointSource,
   toolPairingBalancedAfter,
   toolPairingBalancedBefore,
 } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import { createUserMessage, errorChain } from '@deepseek-ai/dsh-llm'
 import type { Message, UserMessage } from '@deepseek-ai/dsh-llm'
 import type { TokenMeasurement, TokenMeterService } from '@deepseek-ai/dsh-token-meter'
@@ -54,6 +57,8 @@ interface CompactionTransactionOptions {
   readonly stability: 'whole-surface' | 'selected-span'
   /** Optional durability checkpoint after a successfully closed bracket. */
   readonly flush?: () => Promise<void>
+  /** Manual command that initiated this transaction, when present. */
+  readonly sourceCommandId?: CommandId
 }
 
 interface CompactionEntryState {
@@ -175,7 +180,13 @@ export async function compactSurfaceRegion(
     owner = entryState.openTurn
   }
 
-  const startEvent = session.append('compact/start', { turn: owner })
+  const compactionId = CompactionId(randomUUID())
+  const lifecycle = {
+    compactionId,
+    ...options.sourceCommandId === undefined ? {} : { sourceCommandId: options.sourceCommandId },
+    turn: owner,
+  }
+  const startEvent = session.append('compact/start', lifecycle)
   const assertStable: StabilityCheck = options.stability === 'whole-surface'
     ? assertWholeSurfaceUnchanged
     : assertSelectedSpanStable
@@ -188,13 +199,20 @@ export async function compactSurfaceRegion(
 
   try {
     const prepared = prepareCompaction(dependencies, session, selection)
-    const summarized = await summarizeCompaction(dependencies, prepared, agent, signal)
+    const summarized = await summarizeCompaction(
+      dependencies,
+      prepared,
+      agent,
+      compactionId,
+      options.sourceCommandId,
+      signal,
+    )
     if (options.owner === null) signal?.throwIfAborted()
     assertStable(dependencies, session, summarized)
     stage = 'commit'
     const pending = commitCompactionBody(session, startEvent, summarized)
     closing = true
-    const endEvent = session.append('compact/end', { turn: owner })
+    const endEvent = session.append('compact/end', lifecycle)
     closed = true
     result = completeCompaction(pending, endEvent)
   } catch (error: unknown) {
@@ -202,7 +220,7 @@ export async function compactSurfaceRegion(
     if (!closing) {
       closing = true
       try {
-        session.append('compact/end', { turn: owner, error: errorChain(error) })
+        session.append('compact/end', { ...lifecycle, error: errorChain(error) })
         closed = true
       } catch (closeError: unknown) {
         failure = { error: closeError, stage: 'commit' }
@@ -343,12 +361,14 @@ async function summarizeCompaction(
   dependencies: RegionDependencies,
   prepared: PreparedCompaction,
   agent: Agent,
+  compactionId: CompactionResult['compactionId'],
+  sourceCommandId: CommandId | undefined,
   signal?: AbortSignal,
 ): Promise<SummarizedCompaction> {
   const summaryResult = await dependencies.summarize(prepared.input, agent, signal)
   const checkpointMessage = createUserMessage({
     content: frameSummary(summaryResult.summary),
-    source: COMPACT_CHECKPOINT_SOURCE,
+    source: compactCheckpointSource(compactionId, sourceCommandId),
   })
   const framedSummaryTokenCount = dependencies.meter.estimateMessage(checkpointMessage)
   if (framedSummaryTokenCount >= prepared.shadowedTokenCount) {
@@ -425,6 +445,10 @@ function commitCompactionBody(
     ? { rawOutput: summarized.rawOutput, llmStreamCall: true as const }
     : summarized.rawOutput === undefined ? {} : { rawOutput: summarized.rawOutput }
   const summaryEvent = session.append('compact/summary', {
+    compactionId: startEvent.data.compactionId,
+    ...startEvent.data.sourceCommandId === undefined
+      ? {}
+      : { sourceCommandId: startEvent.data.sourceCommandId },
     summary,
     ...callProvenance,
     shadowedRange: { start, end },
@@ -440,6 +464,10 @@ function commitCompactionBody(
     sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs],
   })
   return {
+    compactionId: startEvent.data.compactionId,
+    ...startEvent.data.sourceCommandId === undefined
+      ? {}
+      : { sourceCommandId: startEvent.data.sourceCommandId },
     startSeq: startEvent.seq,
     summarySeq: summaryEvent.seq,
     summary,
diff --git a/packages/compact/compact-basic/tsconfig.json b/packages/compact/compact-basic/tsconfig.json
index bd1a440119..f90011f04d 100644
--- a/packages/compact/compact-basic/tsconfig.json
+++ b/packages/compact/compact-basic/tsconfig.json
@@ -27,6 +27,9 @@
     {
       "path": "../../core/agent"
     },
+    {
+      "path": "../../interaction/commands"
+    },
     {
       "path": "../compact"
     },
diff --git a/packages/compact/compact/package.json b/packages/compact/compact/package.json
index 100a3f56f8..bb4150ee32 100644
--- a/packages/compact/compact/package.json
+++ b/packages/compact/compact/package.json
@@ -19,6 +19,10 @@
       "types": "./lib/types/checkpoint.d.ts",
       "default": "./lib/types/checkpoint.js"
     },
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
@@ -30,12 +34,16 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-commands": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/compact/compact/src/brand.ts b/packages/compact/compact/src/brand.ts
new file mode 100644
index 0000000000..5b6de03e61
--- /dev/null
+++ b/packages/compact/compact/src/brand.ts
@@ -0,0 +1,13 @@
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Stable identity shared by one compact start/summary/checkpoint/end transaction. */
+export type CompactionId = Branded<'CompactionId'>
+
+/**
+ * Brand an implementation-minted compaction identity.
+ * @param id - opaque transaction identity.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function CompactionId(id: string): CompactionId {
+  return id as CompactionId
+}
diff --git a/packages/compact/compact/src/checkpoint.ts b/packages/compact/compact/src/checkpoint.ts
index 9d8b98e4d6..9908fe4ac0 100644
--- a/packages/compact/compact/src/checkpoint.ts
+++ b/packages/compact/compact/src/checkpoint.ts
@@ -13,10 +13,35 @@
  */
 
 import type { MessageSource } from '@deepseek-ai/dsh-llm/message'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
+import type { CompactionId } from './brand.ts'
 
 /** Canonical source for the replacement user message produced by every compaction backend. */
 export const COMPACT_CHECKPOINT_SOURCE = Object.freeze({ kind: 'plugin', plugin: 'compact' } as const)
 
+/** Message provenance carried by a concrete compaction checkpoint. */
+export type CompactCheckpointSource = typeof COMPACT_CHECKPOINT_SOURCE & {
+  readonly compactionId: CompactionId
+  readonly sourceCommandId?: CommandId
+}
+
+/**
+ * Create checkpoint provenance correlated with one compaction transaction.
+ * @param compactionId - owning compaction identity.
+ * @param sourceCommandId - initiating manual command, when present.
+ * @returns immutable checkpoint source.
+ */
+export function compactCheckpointSource(
+  compactionId: CompactionId,
+  sourceCommandId?: CommandId,
+): CompactCheckpointSource {
+  return Object.freeze({
+    ...COMPACT_CHECKPOINT_SOURCE,
+    compactionId,
+    ...sourceCommandId === undefined ? {} : { sourceCommandId },
+  })
+}
+
 /**
  * Test whether a persisted message source identifies a compaction checkpoint.
  * @param source - source restored from a surface user message.
diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts
index 7b0bd25091..0085321333 100644
--- a/packages/compact/compact/src/index.ts
+++ b/packages/compact/compact/src/index.ts
@@ -9,14 +9,17 @@
 
 import { Context, Service } from 'cordis'
 import type { Session } from '@deepseek-ai/dsh-session'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { CompactionResult } from './types.ts'
 
 export type { CompactionResult } from './types.ts'
+export { CompactionId } from './brand.ts'
 export { toolPairingBalancedAfter, toolPairingBalancedBefore } from './tool-pairing.ts'
 // The checkpoint source and its predicate are declared on the cordis-free
 // `./checkpoint` leaf so client and wire programs can name them without this
 // root's Context merge; the root stays the host-side entry point for both.
-export { COMPACT_CHECKPOINT_SOURCE, isCompactCheckpointSource } from './checkpoint.ts'
+export { COMPACT_CHECKPOINT_SOURCE, compactCheckpointSource, isCompactCheckpointSource } from './checkpoint.ts'
+export type { CompactCheckpointSource } from './checkpoint.ts'
 
 /** Why automatic policy is asking a backend to consider compaction. */
 export type CompactionTrigger = 'pressure' | 'context-overflow'
@@ -126,6 +129,7 @@ export abstract class CompactService extends Service {
    *
    * @param agent - idle agent whose durable history should be compacted.
    * @param signal - cancellation scoped to this compaction request.
+   * @param sourceCommandId - initiating command identity for a manual compaction.
    * @returns the compaction result, or `null` when no safe useful range exists.
    * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
    * changed-span, summarization/shrink, commit-stage, or persistence failures;
@@ -135,6 +139,7 @@ export abstract class CompactService extends Service {
   abstract compactNow(
     agent: ManualCompactAgentContext,
     signal: AbortSignal,
+    sourceCommandId?: CommandId,
   ): Promise<CompactionResult | null>
 
   /**
diff --git a/packages/compact/compact/src/invariant.ts b/packages/compact/compact/src/invariant.ts
index 221d5aae09..adac557db5 100644
--- a/packages/compact/compact/src/invariant.ts
+++ b/packages/compact/compact/src/invariant.ts
@@ -1,8 +1,12 @@
 /** Package-owned compaction log-stream invariants. @module @deepseek-ai/dsh-compact/invariant */
 
 import type { Context } from 'cordis'
+import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { CompactionId } from './brand.ts'
+import { isCompactCheckpointSource } from './checkpoint.ts'
+import type { CompactCheckpointSource } from './checkpoint.ts'
 import type {} from './types.ts'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-compact'
@@ -13,6 +17,8 @@ export const name = 'compact-invariant'
 export const inject = ['invariants']
 
 interface CompactionTrace {
+  compactionId: CompactionId
+  sourceCommandId: string | undefined
   startSeq: number
   turn: number | null
   summarized: boolean
@@ -24,11 +30,48 @@ interface SessionTrace {
 }
 
 type CompactionTransition =
-  | { kind: 'start'; startSeq: number; turn: number | null }
-  | { kind: 'summary'; startSeq: number; turn: number | null }
+  | { kind: 'start'; compactionId: CompactionId; sourceCommandId: string | undefined; startSeq: number; turn: number | null }
+  | { kind: 'summary'; compactionId: CompactionId; sourceCommandId: string | undefined; startSeq: number; turn: number | null }
   | { kind: 'end' }
   | { kind: 'end-seed' }
 
+/** Require a durable opaque identity to be a non-empty string. */
+function validateId(value: unknown, label: string, fail: InvariantFailure): asserts value is string {
+  if (typeof value !== 'string' || value.length === 0) fail(`${label} must be a non-empty string`)
+}
+
+/** Keep the optional initiating command identity stable across one transaction. */
+function validateSourceCommandId(
+  eventType: string,
+  value: unknown,
+  expected: string | undefined,
+  fail: InvariantFailure,
+): void {
+  if (value !== undefined) validateId(value, `${eventType} sourceCommandId`, fail)
+  if (value !== expected) {
+    fail(`${eventType} sourceCommandId ${String(value)} does not match compact/start sourceCommandId ${String(expected)}`)
+  }
+}
+
+/** Validate one replacement checkpoint against its open compaction transaction. */
+function validateCheckpoint(
+  trace: SessionTrace,
+  event: SessionEvent<'user/message'>,
+  fail: InvariantFailure,
+): void {
+  const source = event.data.source as typeof event.data.source & Partial<CompactCheckpointSource>
+  validateId(source.compactionId, 'compaction checkpoint compactionId', fail)
+  if (source.sourceCommandId !== undefined) {
+    validateId(source.sourceCommandId, 'compaction checkpoint sourceCommandId', fail)
+  }
+  const open = trace.compaction
+  if (open === undefined) fail('compaction checkpoint has no matching compact/start')
+  if (source.compactionId !== open.compactionId) {
+    fail(`compaction checkpoint id ${source.compactionId} does not match compact/start id ${open.compactionId}`)
+  }
+  validateSourceCommandId('compaction checkpoint', source.sourceCommandId, open.sourceCommandId, fail)
+}
+
 /** Compaction starts still unmatched when a later seed boundary made them stale. */
 function inheritedOrphanStartSeqs(
   events: readonly SessionEvent[],
@@ -99,20 +142,44 @@ function validateCompactionEvent(
   fail: InvariantFailure,
 ): CompactionTransition | undefined {
   if (event.type === 'session/end-seed') return { kind: 'end-seed' }
+  if (event.type === 'user/message'
+    && isReplacementSurfaceEvent(event)
+    && isCompactCheckpointSource(event.data.source)) {
+    validateCheckpoint(trace, event, fail)
+    return undefined
+  }
   if (event.type !== 'compact/start' && event.type !== 'compact/summary' && event.type !== 'compact/end') {
     return undefined
   }
   const open = trace.compaction
   if (event.type === 'compact/start') {
+    validateId(event.data.compactionId, 'compact/start compactionId', fail)
+    if (event.data.sourceCommandId !== undefined) {
+      validateId(event.data.sourceCommandId, 'compact/start sourceCommandId', fail)
+    }
     if (open !== undefined) {
       const owner = open.turn === null ? 'standalone compaction' : `turn ${open.turn}`
       fail(`compact/start while ${owner} is still compacting`)
     }
     validateOwner(event.data.turn, trace.openTurn, event.type, fail)
-    return { kind: 'start', startSeq: event.seq, turn: event.data.turn }
+    return {
+      kind: 'start',
+      compactionId: event.data.compactionId,
+      sourceCommandId: event.data.sourceCommandId,
+      startSeq: event.seq,
+      turn: event.data.turn,
+    }
   }
   if (event.type === 'compact/summary') {
+    validateId(event.data.compactionId, 'compact/summary compactionId', fail)
+    if (event.data.sourceCommandId !== undefined) {
+      validateId(event.data.sourceCommandId, 'compact/summary sourceCommandId', fail)
+    }
     if (open === undefined) fail('compact/summary has no matching compact/start')
+    if (event.data.compactionId !== open.compactionId) {
+      fail(`compact/summary id ${event.data.compactionId} does not match compact/start id ${open.compactionId}`)
+    }
+    validateSourceCommandId('compact/summary', event.data.sourceCommandId, open.sourceCommandId, fail)
     validateOwner(open.turn, trace.openTurn, event.type, fail)
     if (open.summarized) fail('compact/summary repeated within one compaction')
     const seqs = event.data.shadowedSeqs
@@ -123,9 +190,23 @@ function validateCompactionEvent(
     if (!Number.isSafeInteger(event.data.shadowedTokenCount) || event.data.shadowedTokenCount < 0) {
       fail('compact/summary shadowedTokenCount must be a non-negative safe integer')
     }
-    return { kind: 'summary', startSeq: open.startSeq, turn: open.turn }
+    return {
+      kind: 'summary',
+      compactionId: open.compactionId,
+      sourceCommandId: open.sourceCommandId,
+      startSeq: open.startSeq,
+      turn: open.turn,
+    }
+  }
+  validateId(event.data.compactionId, 'compact/end compactionId', fail)
+  if (event.data.sourceCommandId !== undefined) {
+    validateId(event.data.sourceCommandId, 'compact/end sourceCommandId', fail)
   }
   if (open === undefined) fail('compact/end has no matching compact/start')
+  if (event.data.compactionId !== open.compactionId) {
+    fail(`compact/end id ${event.data.compactionId} does not match compact/start id ${open.compactionId}`)
+  }
+  validateSourceCommandId('compact/end', event.data.sourceCommandId, open.sourceCommandId, fail)
   if (event.data.turn !== open.turn) {
     fail(`compact/end owner ${String(event.data.turn)} does not match compact/start owner ${String(open.turn)}`)
   }
@@ -142,6 +223,8 @@ function applyCompactionTransition(
 ): CompactionTrace | undefined {
   if (transition.kind === 'start') {
     return {
+      compactionId: transition.compactionId,
+      sourceCommandId: transition.sourceCommandId,
       startSeq: transition.startSeq,
       turn: transition.turn,
       summarized: false,
@@ -149,6 +232,8 @@ function applyCompactionTransition(
   }
   if (transition.kind === 'summary') {
     return {
+      compactionId: transition.compactionId,
+      sourceCommandId: transition.sourceCommandId,
       startSeq: transition.startSeq,
       turn: transition.turn,
       summarized: true,
diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index 4429e8b291..c321be426e 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -8,6 +8,8 @@
  */
 
 import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
+import type { CompactionId } from './brand.ts'
 
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
@@ -16,7 +18,7 @@ declare module '@deepseek-ai/dsh-session' {
      * `compact/end`. A numbered owner is strictly enclosed by that open turn;
      * `null` identifies a standalone manual transaction between turns.
      */
-    'compact/start': { turn: number | null }
+    'compact/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
     /**
      * Completed summary, its inputs, and its model call facts — log-only, no surfaceOp.
      * The summary content is in `data.summary`; the actual surface replacement
@@ -27,6 +29,8 @@ declare module '@deepseek-ai/dsh-session' {
      * before it (`compact/prune` documents the shared protocol).
      */
     'compact/summary': {
+      compactionId: CompactionId
+      sourceCommandId?: CommandId
       summary: ContentBlock[]
       shadowedRange: { start: number; end: number }
       shadowedSeqs: number[]
@@ -62,7 +66,7 @@ declare module '@deepseek-ai/dsh-session' {
      * Marks the end of a compaction — log-only, releases the lock. Its owner
      * matches `compact/start`; `error` records an unsuccessful attempt.
      */
-    'compact/end': { turn: number | null; error?: string }
+    'compact/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
     /**
      * Shadow price of one model-free prune replacement — log-only, no
      * surfaceOp. The shared shadow-price protocol: a surface `replace` event
@@ -85,6 +89,10 @@ declare module '@deepseek-ai/dsh-session' {
 
 /** Result of a successful compaction operation. */
 export interface CompactionResult {
+  /** Stable identity shared by this compaction's complete durable lifecycle. */
+  compactionId: CompactionId
+  /** Human command that initiated this compaction, when it was manual. */
+  sourceCommandId?: CommandId
   /** The seq of the appended `compact/start` event. */
   startSeq: number
   /** The seq of the appended `compact/summary` event. */
diff --git a/packages/compact/compact/tsconfig.json b/packages/compact/compact/tsconfig.json
index 673ee51547..a231786c32 100644
--- a/packages/compact/compact/tsconfig.json
+++ b/packages/compact/compact/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../util/brand"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
@@ -17,6 +20,9 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../interaction/commands"
+    },
     {
       "path": "../../core/session"
     },
diff --git a/packages/compact/compact/tsdown.config.ts b/packages/compact/compact/tsdown.config.ts
new file mode 100644
index 0000000000..6284421125
--- /dev/null
+++ b/packages/compact/compact/tsdown.config.ts
@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsdown'
+
+/** Builds each published entry as a self-contained file admitted by the package whitelist. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+])
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index 2ec5a1bb25..63c5b2cb9b 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -30,7 +30,7 @@ declare module '@deepseek-ai/dsh-session' {
      * with `tool/code-dispatch` by `subCallId` (timing = the two events'
      * `time` fields).
      */
-    'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
+    'tool/code-dispatch-start': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
     /**
      * One bridged sub-dispatch SETTLING: the pairing ids (matching the
      * `tool/code-dispatch-start` with the same `subCallId`), the tool `name`
@@ -46,7 +46,7 @@ declare module '@deepseek-ai/dsh-session' {
      * before returning), so its execution-enclosure relation holds by
      * construction.
      */
-    'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
+    'tool/code-dispatch': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
   }
 }
 
@@ -502,6 +502,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
         const subCallId = CallId(`${String(exec.callId)}:code:${n}`)
         const input = {
           callId: subCallId,
+          rootCallId: exec.rootCallId,
           name,
           arguments: normalized.dispatched,
           ...exec.agent ? { agent: exec.agent } : {},
@@ -539,6 +540,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
                 content: result.content,
               })
               agent.session.append('tool/code-dispatch', {
+                rootCallId: exec.rootCallId,
                 parentCallId: exec.callId,
                 subCallId,
                 name,
@@ -563,6 +565,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
             },
             async start(): Promise<void> {
               exec.agent?.session.append('tool/code-dispatch-start', {
+                rootCallId: exec.rootCallId,
                 parentCallId: exec.callId,
                 subCallId,
                 name,
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 7c2346e723..6338e54501 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -297,6 +297,11 @@ export type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]:
  */
 export interface ToolExecutionInput {
   readonly callId: CallId
+  /**
+   * Root model-requested call owning this execution tree. Callers omit it for
+   * a root execution; nested dispatchers propagate the enclosing value.
+   */
+  readonly rootCallId?: CallId
   readonly name: string
   /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
   readonly arguments: unknown
@@ -352,6 +357,8 @@ export interface CodeDispatchLog {
  * observers run.
  */
 export interface ToolExecution extends ToolExecutionInput {
+  /** Root model-requested call, resolved for every root and nested execution. */
+  readonly rootCallId: CallId
   /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
   readonly token: ToolExecutionToken
 }
@@ -1123,6 +1130,7 @@ export class ToolRegistry extends Service {
     const deferredContexts: UserMessage[] = []
     const token = createExecutionToken()
     const callId = exec.callId
+    const rootCallId = exec.rootCallId ?? callId
     const name = exec.name
     const agent = exec.agent
     const parent = exec.parent
@@ -1133,6 +1141,7 @@ export class ToolRegistry extends Service {
     const base = {
       token,
       callId,
+      rootCallId,
       name,
       signal,
       ...agent !== undefined ? { agent } : {},
diff --git a/packages/core/tools/src/invariant.ts b/packages/core/tools/src/invariant.ts
index 78666f5890..a0d9487857 100644
--- a/packages/core/tools/src/invariant.ts
+++ b/packages/core/tools/src/invariant.ts
@@ -33,9 +33,34 @@ function validateResult(
 const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
   const stages = new WeakMap<object, ToolStage>()
   const openTurns = new WeakMap<Session, number | null>()
+  const dispatchRoots = new WeakMap<Session, Map<string, string>>()
+  const validateDispatch = (session: Session, event: SessionEvent): void => {
+    if (event.type !== 'tool/code-dispatch-start' && event.type !== 'tool/code-dispatch') return
+    const root = String(event.data.rootCallId)
+    const parent = String(event.data.parentCallId)
+    const child = String(event.data.subCallId)
+    if (root.length === 0 || parent.length === 0 || child.length === 0) {
+      fail(`${event.type} must carry non-empty rootCallId, parentCallId, and subCallId`)
+      return
+    }
+    const roots = dispatchRoots.get(session)
+    const known = roots?.get(child)
+    if (known !== undefined && known !== root) fail(`${event.type} changed rootCallId for subCallId ${child}`)
+    if (parent !== root && roots?.get(parent) !== root) {
+      fail(`${event.type} parentCallId ${parent} does not belong to rootCallId ${root}`)
+    }
+  }
+  const commitDispatch = (session: Session, event: SessionEvent): void => {
+    if (event.type !== 'tool/code-dispatch-start' && event.type !== 'tool/code-dispatch') return
+    const roots = dispatchRoots.get(session) as Map<string, string>
+    roots.set(String(event.data.subCallId), String(event.data.rootCallId))
+  }
   const seed = (session: Session): number | null => {
     let openTurn: number | null = null
+    dispatchRoots.set(session, new Map())
     for (const event of session.events) {
+      validateDispatch(session, event)
+      commitDispatch(session, event)
       if (event.type === 'turn/start') openTurn = event.data.turn
       else if (event.type === 'turn/end') openTurn = null
       else if ((event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch')
@@ -51,12 +76,15 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
   for (const session of ctx.sessions.list()) seed(session)
   ctx.on('session/created', (session) => { seed(session) }, { global: true })
   ctx.on('session/event', (session, event) => {
+    validateDispatch(session, event)
+    commitDispatch(session, event)
     if (event.type === 'turn/start') openTurns.set(session, event.data.turn)
     else if (event.type === 'turn/end') openTurns.set(session, null)
   }, { global: true })
   ctx.on('internal/dispatch', (_mode, eventName, args) => {
     if (eventName === 'session/event') {
       const [session, event] = args as [Session, SessionEvent]
+      validateDispatch(session, event)
       if ((event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch')
         && openTurnFor(session) === null) {
         fail(`${event.type} appended outside any open turn`)
diff --git a/packages/interaction/commands/src/index.ts b/packages/interaction/commands/src/index.ts
index 94c4861e66..780569c159 100644
--- a/packages/interaction/commands/src/index.ts
+++ b/packages/interaction/commands/src/index.ts
@@ -37,6 +37,8 @@ export interface CommandInputDescriptor {
 
 /** Invocation passed to one registered command handler. */
 export interface CommandInvocation {
+  /** Pairing id already written to this invocation's `command/run` event. */
+  readonly commandId: CommandId
   /** Exact agent whose human-facing surface received the command. */
   readonly agent: Agent
   /** Exact text following the registered command name, including separator whitespace. */
@@ -389,7 +391,7 @@ export class CommandService extends Service {
       ...command.definition.recordInput === false ? {} : { args: parsed.rawInput },
       source: { kind: 'user' },
     })
-    const invocation = Object.freeze({ agent, rawInput: parsed.rawInput, signal })
+    const invocation = Object.freeze({ commandId, agent, rawInput: parsed.rawInput, signal })
     let result: CommandResult
     try {
       const output = command.definition.handler(invocation)
diff --git a/packages/llm/llm-retry/package.json b/packages/llm/llm-retry/package.json
index d3b6afebba..1685d0e552 100644
--- a/packages/llm/llm-retry/package.json
+++ b/packages/llm/llm-retry/package.json
@@ -19,6 +19,10 @@
       "types": "./lib/types/types.d.ts",
       "default": "./lib/types/types.js"
     },
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -29,6 +33,7 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
@@ -40,6 +45,7 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
     "@cordisjs/plugin-include": "workspace:^",
     "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
diff --git a/packages/llm/llm-retry/src/brand.ts b/packages/llm/llm-retry/src/brand.ts
new file mode 100644
index 0000000000..41682cc9d1
--- /dev/null
+++ b/packages/llm/llm-retry/src/brand.ts
@@ -0,0 +1,13 @@
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Stable identity shared by every attempt in one request-step retry chain. */
+export type RetryId = Branded<'RetryId'>
+
+/**
+ * Brand an implementation-minted retry-chain identity.
+ * @param id - opaque retry identity.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function RetryId(id: string): RetryId {
+  return id as RetryId
+}
diff --git a/packages/llm/llm-retry/src/index.ts b/packages/llm/llm-retry/src/index.ts
index 82b441fb8f..dcba1e2443 100644
--- a/packages/llm/llm-retry/src/index.ts
+++ b/packages/llm/llm-retry/src/index.ts
@@ -5,39 +5,26 @@
  * @module @deepseek-ai/dsh-llm-retry
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Context, Events } from 'cordis'
 import z from 'schemastery'
 import type { Agent, RequestErrorAction } from '@deepseek-ai/dsh-agent'
 import type { LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { RetryId } from './brand.ts'
+import type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts'
 
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
     /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
-    'llm/retry': {
-      turn: number
-      step: number
-      provider: string
-      mode: 'normal'
-      policyKey: string
-      retry: number
-      maxRetries: number
-      delayMs: number
-      failure: LlmFailure
-    } | {
-      turn: number
-      step: number
-      provider: string
-      mode: 'always'
-      policyKey: string
-      retry: number
-      delayMs: number
-      failure: LlmFailure
-    }
+    'llm/retry': LlmRetryEventData
+    /** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
+    'llm/retry-started': LlmRetryStartedEventData
   }
 }
 
-export type { LlmRetryEventData } from './types.ts'
+export type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts'
+export { RetryId } from './brand.ts'
 
 export const name = 'llm-retry'
 export const inject = ['agents']
@@ -139,6 +126,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
     policy: ResolvedRetryPolicy,
     policyKey: string,
     retry: number,
+    retryId: RetryId,
     delayMs: number,
     signal: AbortSignal,
   ): Promise<RequestErrorAction> {
@@ -146,6 +134,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
     if (fusedSignal.aborted) return
     const eventData = policy.mode === 'normal'
       ? {
+        retryId,
         turn,
         step,
         provider,
@@ -157,6 +146,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
         failure,
       }
       : {
+        retryId,
         turn,
         step,
         provider,
@@ -168,6 +158,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
       }
     agent.session.append('llm/retry', eventData)
     if (!await cancellableDelay(delayMs, fusedSignal)) return
+    agent.session.append('llm/retry-started', { retryId, turn, step, retry })
     return { kind: 'retry' }
   }
 
@@ -207,6 +198,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
     const previousRetry = priorPolicyRetry?.data.retry ?? 0
     if (policy.mode === 'normal' && previousRetry >= policy.maxRetries) return next()
     const retry = previousRetry + 1
+    const retryId = priorPolicyRetry?.data.retryId ?? RetryId(randomUUID())
     let delayMs: number
     if (failure.providerRetryAfterMs !== undefined
       && Number.isFinite(failure.providerRetryAfterMs)
@@ -221,7 +213,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
       delayMs = localDelay(policy, retry, random)
     }
 
-    return backoff(agent, turn, step, failure, provider, policy, policyKey, retry, delayMs, signal)
+    return backoff(agent, turn, step, failure, provider, policy, policyKey, retry, retryId, delayMs, signal)
   }
 
   const disposeListener = ctx.on('agent/request-error', (
diff --git a/packages/llm/llm-retry/src/invariant.ts b/packages/llm/llm-retry/src/invariant.ts
index d324c012f2..1680873c0c 100644
--- a/packages/llm/llm-retry/src/invariant.ts
+++ b/packages/llm/llm-retry/src/invariant.ts
@@ -47,7 +47,10 @@ function validateRetry(
   event: SessionEvent<'llm/retry'>,
   fail: InvariantFailure,
 ): void {
-  const { turn, step, provider, mode, policyKey, retry, delayMs } = event.data
+  const { retryId, turn, step, provider, mode, policyKey, retry, delayMs } = event.data
+  if (typeof retryId !== 'string' || retryId.length === 0) {
+    fail('llm/retry retryId must be a non-empty string')
+  }
   const failure: unknown = event.data.failure
   validateFailure(failure, fail)
   if (!Number.isSafeInteger(retry) || retry < 1) {
@@ -110,12 +113,43 @@ function validateRetry(
   if (retry !== expectedRetry) {
     fail(`llm/retry retry ${retry} must equal provider policy retry ${expectedRetry}`)
   }
+  if (priorPolicyRetry !== undefined && priorPolicyRetry.data.retryId !== retryId) {
+    fail('llm/retry must preserve retryId across one provider-policy chain')
+  }
+  if (priorPolicyRetry === undefined && history.some(prior =>
+    (prior.type === 'llm/retry' || prior.type === 'llm/retry-started')
+    && prior.data.retryId === retryId)) {
+    fail(`llm/retry retryId ${JSON.stringify(retryId)} is already owned by another chain`)
+  }
+}
+
+/** Validate one wait-complete transition against its scheduled attempt. */
+function validateStarted(
+  history: readonly SessionEvent[],
+  event: SessionEvent<'llm/retry-started'>,
+  fail: InvariantFailure,
+): void {
+  const { retryId, turn, step, retry } = event.data
+  if (typeof retryId !== 'string' || retryId.length === 0) {
+    fail('llm/retry-started retryId must be a non-empty string')
+  }
+  const scheduled = history.findLast((prior): prior is SessionEvent<'llm/retry'> =>
+    prior.type === 'llm/retry' && prior.data.retryId === retryId && prior.data.retry === retry)
+  if (scheduled === undefined) fail('llm/retry-started pairs no prior scheduled attempt')
+  if (scheduled.data.turn !== turn || scheduled.data.step !== step) {
+    fail('llm/retry-started turn/step must match its scheduled attempt')
+  }
+  if (history.some(prior => prior.type === 'llm/retry-started'
+    && prior.data.retryId === retryId && prior.data.retry === retry)) {
+    fail('llm/retry-started repeats one scheduled attempt')
+  }
 }
 
 /** Validate every retry record already present in one loaded session. */
 function validateSession(session: Session, fail: InvariantFailure): void {
   for (const [index, event] of session.events.entries()) {
     if (event.type === 'llm/retry') validateRetry(session.events.slice(0, index), event, fail)
+    else if (event.type === 'llm/retry-started') validateStarted(session.events.slice(0, index), event, fail)
   }
 }
 
@@ -127,6 +161,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
     if (eventName !== 'session/event') return
     const [session, event] = args as [Session, SessionEvent]
     if (event.type === 'llm/retry') validateRetry(session.events, event, fail)
+    else if (event.type === 'llm/retry-started') validateStarted(session.events, event, fail)
   }, { global: true })
 }, { inject: ['sessions'] })
 
diff --git a/packages/llm/llm-retry/src/types.ts b/packages/llm/llm-retry/src/types.ts
index f59aef4495..12820889dd 100644
--- a/packages/llm/llm-retry/src/types.ts
+++ b/packages/llm/llm-retry/src/types.ts
@@ -1,8 +1,10 @@
 import type { LlmFailure } from '@deepseek-ai/dsh-llm/types'
+import type { RetryId } from './brand.ts'
 
 /** Durable payload recorded before one provider-routed model-request retry wait. */
 export type LlmRetryEventData =
   | {
+    retryId: RetryId
     turn: number
     step: number
     provider: string
@@ -13,7 +15,9 @@ export type LlmRetryEventData =
     delayMs: number
     failure: LlmFailure
   }
+
   | {
+    retryId: RetryId
     turn: number
     step: number
     provider: string
@@ -23,3 +27,11 @@ export type LlmRetryEventData =
     delayMs: number
     failure: LlmFailure
   }
+
+/** Durable transition recorded after one retry delay completes. */
+export interface LlmRetryStartedEventData {
+  retryId: RetryId
+  turn: number
+  step: number
+  retry: number
+}
diff --git a/packages/llm/llm-retry/tsconfig.json b/packages/llm/llm-retry/tsconfig.json
index 48c858951a..41e9ca65c5 100644
--- a/packages/llm/llm-retry/tsconfig.json
+++ b/packages/llm/llm-retry/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../util/brand"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },

From dec4d1ffdb1d71c345bb32e72d3fbc039c4d45d6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:13:04 +0800
Subject: [PATCH 485/516] ci(wine): resume partial Node downloads

---
 scripts/wine-windows-gates.sh | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
index d4798fdd7b..34e58274ce 100755
--- a/scripts/wine-windows-gates.sh
+++ b/scripts/wine-windows-gates.sh
@@ -74,27 +74,44 @@ trap cleanup EXIT
 mkdir -p "$cache_dir" "$scratch/logs"
 
 # ---- provision Windows Node, boot Wine, snapshot + install concurrently ----
-curl_download_args=(
+curl_metadata_args=(
   --fail --silent --show-error --location
   --retry 3 --retry-all-errors --retry-delay 2
-  --connect-timeout 10 --max-time 90 --retry-max-time 240
+  --connect-timeout 10 --max-time 30 --retry-max-time 120
 )
 
+download_node_archive() {
+  local url="$1" output="$2" attempt status=0
+  for attempt in 1 2 3; do
+    if curl --fail --silent --show-error --location \
+      --continue-at - --connect-timeout 10 --max-time 300 \
+      --speed-limit 1024 --speed-time 30 \
+      -o "$output" "$url"; then
+      return 0
+    else
+      status=$?
+    fi
+    (( attempt < 3 )) || break
+    echo "wine-windows-gates: Windows Node archive transfer failed (exit $status) on attempt $attempt; resuming partial download" >&2
+  done
+  return "$status"
+}
+
 provision_node() {
   # Latest release of the primary line, checksum-verified against the same
   # dist directory. Bound and retry every transfer so a stalled nodejs.org
   # response cannot consume the entire CI job. Offline runs fall back to the
   # newest cached zip, loudly.
   local version zip
-  version="$(curl "${curl_download_args[@]}" https://nodejs.org/dist/index.json 2> /dev/null \
+  version="$(curl "${curl_metadata_args[@]}" https://nodejs.org/dist/index.json 2> /dev/null \
     | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const v=JSON.parse(d).find(r=>r.version.startsWith('v$node_major.'));if(v)console.log(v.version)})" \
     || true)"
   if [ -n "$version" ]; then
     zip="$cache_dir/node-$version-win-x64.zip"
     if [ ! -f "$zip" ]; then
-      curl "${curl_download_args[@]}" -o "$zip.tmp" "https://nodejs.org/dist/$version/node-$version-win-x64.zip"
+      download_node_archive "https://nodejs.org/dist/$version/node-$version-win-x64.zip" "$zip.tmp"
       local expected
-      expected="$(curl "${curl_download_args[@]}" "https://nodejs.org/dist/$version/SHASUMS256.txt" \
+      expected="$(curl "${curl_metadata_args[@]}" "https://nodejs.org/dist/$version/SHASUMS256.txt" \
         | awk -v a="node-$version-win-x64.zip" '$2 == a { print $1; exit }')"
       [ -n "$expected" ] || { echo "wine-windows-gates: no SHASUMS256 entry for node-$version-win-x64.zip" >&2; exit 1; }
       verify_sha256 "$expected" "$zip.tmp"

From 81d688600677eabab42fbb9f364ed5a3d7ce7b30 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:48:19 +0800
Subject: [PATCH 486/516] feat(client): add conversation node engine and
 contextual slots

---
 packages/client/runtime/package.json          |   1 -
 .../src/client/contract/conversation.ts       | 261 ++++++
 .../conversation/definition-registry.ts       |  60 ++
 .../src/client/conversation/event-registry.ts |  56 ++
 .../src/client/conversation/view-registry.ts  |  26 +
 packages/client/runtime/src/client/index.ts   |  39 +-
 .../src/client/sessions/assistant-timing.ts   |   7 +-
 .../client/sessions/conversation-assembler.ts | 798 ++++++++++++++++++
 .../sessions/conversation-location-index.ts   | 508 +++++++++++
 .../src/client/sessions/conversation.ts       |  91 +-
 .../runtime/src/client/sessions/manager.ts    |  15 +-
 .../runtime/src/client/sessions/partial.ts    |   9 +-
 .../src/client/sessions/queue-mirror.ts       |  74 ++
 .../runtime/src/client/sessions/service.ts    |  36 +-
 .../runtime/src/client/sessions/session.ts    | 454 ++--------
 .../src/client/sessions/transcript-adapter.ts | 409 ---------
 packages/client/runtime/src/client/slots.ts   |   2 +-
 packages/client/ui-slots/src/index.ts         | 192 ++++-
 packages/client/ui-slots/src/renderer.ts      |   4 +-
 .../client/web-react/src/scoped-slots.tsx     | 333 ++++++--
 20 files changed, 2475 insertions(+), 900 deletions(-)
 create mode 100644 packages/client/runtime/src/client/contract/conversation.ts
 create mode 100644 packages/client/runtime/src/client/conversation/definition-registry.ts
 create mode 100644 packages/client/runtime/src/client/conversation/event-registry.ts
 create mode 100644 packages/client/runtime/src/client/conversation/view-registry.ts
 create mode 100644 packages/client/runtime/src/client/sessions/conversation-assembler.ts
 create mode 100644 packages/client/runtime/src/client/sessions/conversation-location-index.ts
 create mode 100644 packages/client/runtime/src/client/sessions/queue-mirror.ts
 delete mode 100644 packages/client/runtime/src/client/sessions/transcript-adapter.ts

diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
index 3d97e70de5..3176428b36 100644
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -33,7 +33,6 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@deepseek-ai/dsh-client-connection": "workspace:^",
-    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
diff --git a/packages/client/runtime/src/client/contract/conversation.ts b/packages/client/runtime/src/client/contract/conversation.ts
new file mode 100644
index 0000000000..fb98965d25
--- /dev/null
+++ b/packages/client/runtime/src/client/contract/conversation.ts
@@ -0,0 +1,261 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { ToolEventView } from '@deepseek-ai/dsh-client-connection/client'
+
+/** One raw log event plus its optional envelope-level presentation view. */
+export interface ConversationEventInput {
+  readonly event: SessionEvent
+  readonly view: ToolEventView | undefined
+}
+
+/** Definition-local identity and lifecycle role extracted from one event. */
+export interface ConversationMatchResult {
+  readonly id: string
+  readonly role: 'start' | 'update'
+}
+
+/** Merge-extensible business values published against one Turn. */
+export interface ConversationTurnDataMap {}
+
+/** Merge-extensible business values published against one Step. */
+export interface ConversationStepDataMap {}
+
+/** Stable keyed reader for independently owned Location business values. */
+export interface ConversationLocationDataStore<DataMap extends object> {
+  /**
+   * Read one business value without exposing another owner's mutable State.
+   * @param key - declaration-merged business key.
+   * @returns latest immutable value, when its owning Context has published one.
+   */
+  get<Key extends keyof DataMap & string>(key: Key): Readonly<DataMap[Key]> | undefined
+}
+
+interface ConversationLocationDataValue {
+  readonly kind: 'turn' | 'step'
+  readonly turn: number
+  readonly step?: number
+  readonly key: string
+  readonly value: unknown
+}
+
+type RegisteredTurnData = {
+  [Key in keyof ConversationTurnDataMap & string]: {
+    readonly kind: 'turn'
+    readonly turn: number
+    readonly key: Key
+    readonly value: ConversationTurnDataMap[Key]
+  }
+}[keyof ConversationTurnDataMap & string]
+
+type RegisteredStepData = {
+  [Key in keyof ConversationStepDataMap & string]: {
+    readonly kind: 'step'
+    readonly turn: number
+    readonly step: number
+    readonly key: Key
+    readonly value: ConversationStepDataMap[Key]
+  }
+}[keyof ConversationStepDataMap & string]
+
+/** One Definition-owned value attached to an Engine-owned Turn or Step. */
+export type ConversationLocationData =
+  [keyof ConversationTurnDataMap | keyof ConversationStepDataMap] extends [never]
+    ? ConversationLocationDataValue
+    : RegisteredTurnData | RegisteredStepData
+
+/** Immutable resolved boundary for one Agent step. */
+export interface StepLocation {
+  readonly turn: number
+  readonly step: number
+  readonly start: SessionEvent<'step/start'> | undefined
+  readonly end: SessionEvent<'step/end'> | undefined
+  readonly status: 'open' | 'closed' | 'unknown'
+  /** Stable reader for Step-scoped business values. */
+  readonly data: ConversationLocationDataStore<ConversationStepDataMap>
+}
+
+/** Immutable resolved boundary for one Agent turn. */
+export interface TurnLocation {
+  readonly turn: number
+  readonly start: SessionEvent<'turn/start'> | undefined
+  readonly end: SessionEvent<'turn/end'> | undefined
+  readonly status: 'open' | 'closed' | 'unknown'
+  readonly steps: readonly StepLocation[]
+  /** Stable reader for Turn-scoped business values. */
+  readonly data: ConversationLocationDataStore<ConversationTurnDataMap>
+}
+
+/** Engine-owned placement of one matched event in the Session hierarchy. */
+export type ConversationLocation =
+  | { readonly kind: 'session' }
+  | { readonly kind: 'turn'; readonly turn: TurnLocation }
+  | { readonly kind: 'step'; readonly turn: TurnLocation; readonly step: StepLocation }
+  | { readonly kind: 'unresolved' }
+
+/** One event accepted by a Definition, with its current resolved Location. */
+export interface ConversationMatch extends ConversationEventInput {
+  readonly role: 'start' | 'update'
+  readonly location: ConversationLocation
+}
+
+/** Target-neutral identity returned by a business Definition. */
+export interface ConversationViewNode {
+  readonly key: string
+  readonly kind: string
+  readonly id: string
+  readonly target: string
+  readonly data: unknown
+}
+
+/** Final Chat render unit produced directly by a business Definition. */
+export interface ChatConversationViewNode extends ConversationViewNode {
+  readonly target: 'chat'
+  readonly anchorSeq: number
+  readonly location: ConversationLocation
+  readonly visibility: 'visible' | 'hidden'
+}
+
+/** Immutable public view of an assembled business Context. */
+export interface ConversationNodeContext<State = unknown> {
+  readonly key: string
+  readonly kind: string
+  readonly id: string
+  readonly matches: readonly ConversationMatch[]
+  readonly start: ConversationMatch | undefined
+  readonly state: State | undefined
+  readonly current: ReadonlyMap<string, ConversationViewNode | null>
+}
+
+/** Read-only predecessor returned to a Definition's start function. */
+export interface ConversationPreviousContext<State = unknown> {
+  readonly key: string
+  readonly kind: string
+  readonly id: string
+  readonly startSeq: number
+  readonly state: Readonly<State>
+  readonly matches: readonly ConversationMatch[]
+}
+
+/** Strictly-backward Context lookup available while a start is evaluated. */
+export interface ConversationContextReader {
+  /**
+   * Find the active Context of `kind` with the greatest start seq below the
+   * current start event.
+   * @param kind - Definition kind to query.
+   * @returns the nearest predecessor, or undefined when absent in the current window.
+   */
+  previous<State>(kind: string): ConversationPreviousContext<State> | undefined
+}
+
+/** Requested cadence for materializing updated business State into view Nodes. */
+export type ConversationPublication = 'none' | 'animation-frame' | 'immediate'
+
+/** Engine-owned Location data publication phase. */
+export type ConversationLocationDataScope = 'step' | 'turn'
+
+/** One independently registered business Event-to-Node state machine. */
+export interface ConversationNodeDefinition<State = unknown> {
+  readonly kind: string
+  /**
+   * Extract this Definition's stable business identity from one event.
+   * @param event - raw Session event; no Context or history access is available.
+   * @returns identity and lifecycle role, or null when unrelated.
+   */
+  match(event: SessionEvent): ConversationMatchResult | null
+  /**
+   * Create State from the unique start Match.
+   * @param context - complete evidence currently collected for the Context.
+   * @param match - the start Match.
+   * @param reader - strictly-backward read-only Context lookup.
+   * @returns the State adopted by the engine.
+   */
+  start(
+    context: ConversationNodeContext<State>,
+    match: ConversationMatch,
+    reader: ConversationContextReader,
+  ): State
+  /**
+   * Apply one post-start update Match.
+   * @param context - Context with its current State.
+   * @param match - update Match in ascending log order.
+   * @returns the State adopted by the engine.
+   */
+  update(
+    context: ConversationNodeContext<State> & { readonly state: State },
+    match: ConversationMatch,
+  ): State
+  /**
+   * Select publication cadence for one accepted Match.
+   * @param match - accepted Match.
+   * @returns requested cadence; omission defaults to immediate.
+   */
+  publication?(match: ConversationMatch): ConversationPublication
+  /**
+   * Publish this Definition's read-only business value for one Location phase.
+   * The Engine evaluates every Definition first for Step and then for Turn,
+   * owns replacement/removal, and rejects another Context trying to publish
+   * the same Location key.
+   * @param context - latest complete Context.
+   * @param scope - Location hierarchy level currently being materialized.
+   * @returns current Location value, or null while unavailable.
+   */
+  buildLocationData?(
+    context: ConversationNodeContext<State>,
+    scope: ConversationLocationDataScope,
+  ): ConversationLocationData | null
+  /**
+   * Materialize one final Node for a registered view target.
+   * @param context - latest complete Context.
+   * @param target - registered view target such as `chat`.
+   * @returns final Node, or null when this Context is not currently visible.
+   */
+  buildViewNode(
+    context: ConversationNodeContext<State>,
+    target: string,
+  ): ConversationViewNode | null
+}
+
+/** Reference-stable Turn/Step facts published beside view Nodes. */
+export interface ConversationTimelineSnapshot {
+  readonly turnOrder: readonly number[]
+  readonly turns: ReadonlyMap<number, TurnLocation>
+}
+
+/** Per-Session incremental builder for one view target. */
+export interface ConversationViewBuilder<Node extends ConversationViewNode = ConversationViewNode, Snapshot = unknown> {
+  readonly empty: Snapshot
+  /**
+   * Replace the low-frequency complete materialized Node set.
+   * @param input - complete Nodes and current timeline.
+   * @returns next view snapshot.
+   */
+  replace(input: {
+    readonly nodes: readonly Node[]
+    readonly timeline: ConversationTimelineSnapshot
+  }): Snapshot
+  /**
+   * Apply only Nodes whose materialized values changed in this transaction.
+   * @param input - changed Nodes and current timeline.
+   * @returns next view snapshot.
+   */
+  apply(input: {
+    readonly upserts: readonly Node[]
+    readonly timeline: ConversationTimelineSnapshot
+  }): Snapshot
+}
+
+/** Registry contribution that creates one isolated view builder per Session. */
+export interface ConversationViewDefinition<Node extends ConversationViewNode = ConversationViewNode, Snapshot = unknown> {
+  readonly target: string
+  /** @returns a new Session-owned incremental builder. */
+  create(): ConversationViewBuilder<Node, Snapshot>
+}
+
+/**
+ * Build a stable collision-free key for one Definition-local business identity.
+ * @param kind - Definition kind.
+ * @param id - Definition-local business identity.
+ * @returns engine-owned Context key.
+ */
+export function conversationContextKey(kind: string, id: string): string {
+  return `${kind.length}:${kind}${id}`
+}
diff --git a/packages/client/runtime/src/client/conversation/definition-registry.ts b/packages/client/runtime/src/client/conversation/definition-registry.ts
new file mode 100644
index 0000000000..d43f494e1a
--- /dev/null
+++ b/packages/client/runtime/src/client/conversation/definition-registry.ts
@@ -0,0 +1,60 @@
+import { Service } from 'cordis'
+
+/** Shared lifecycle and stable-entry storage for one Conversation Definition registry. */
+export abstract class ConversationDefinitionRegistry<Definition> extends Service {
+  protected readonly definitions = new Map<string, Definition>()
+  private listeners = new Set<() => void>()
+  private cached: readonly Definition[] = []
+
+  /**
+   * Return reference-stable Definitions in registration order.
+   * @returns current Definitions.
+   */
+  entries(): readonly Definition[] {
+    return this.cached
+  }
+
+  /**
+   * Observe low-frequency registry changes.
+   * @param listener - synchronous invalidation callback.
+   * @returns unsubscribe callback.
+   */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /**
+   * Register one uniquely keyed Definition for the caller's lifetime.
+   * @param key - registry-local unique key.
+   * @param definition - contributed Definition.
+   * @param duplicateMessage - error raised when the key is already owned.
+   * @param effectName - Cordis effect diagnostic label.
+   * @returns idempotent disposer.
+   */
+  protected registerDefinition(
+    key: string,
+    definition: Definition,
+    duplicateMessage: string,
+    effectName: string,
+  ): () => void {
+    if (this.definitions.has(key)) throw new Error(duplicateMessage)
+    const owner = this.ctx
+    const dispose = owner.effect(() => {
+      this.definitions.set(key, definition)
+      this.refresh()
+      return () => {
+        if (this.definitions.get(key) !== definition) return
+        this.definitions.delete(key)
+        this.refresh()
+      }
+    }, effectName)
+    return () => { void dispose() }
+  }
+
+  /** Refresh cached entries and synchronously invalidate subscribers. */
+  protected refresh(): void {
+    this.cached = [...this.definitions.values()]
+    for (const listener of this.listeners) listener()
+  }
+}
diff --git a/packages/client/runtime/src/client/conversation/event-registry.ts b/packages/client/runtime/src/client/conversation/event-registry.ts
new file mode 100644
index 0000000000..6935ed1741
--- /dev/null
+++ b/packages/client/runtime/src/client/conversation/event-registry.ts
@@ -0,0 +1,56 @@
+import type { Context } from 'cordis'
+import type { ConversationNodeDefinition } from '../contract/conversation.ts'
+import { ConversationDefinitionRegistry } from './definition-registry.ts'
+
+/** Runtime registry of independently owned Conversation business Definitions. */
+export class ConversationEventRegistry extends ConversationDefinitionRegistry<ConversationNodeDefinition> {
+  private fallback: ConversationNodeDefinition | undefined
+
+  /** @param ctx - owning Client Runtime context. */
+  constructor(ctx: Context) {
+    super(ctx, 'conversationEvents')
+  }
+
+  /**
+   * Register a uniquely named business Definition for the caller's lifetime.
+   * @param definition - Definition contribution.
+   * @returns idempotent disposer.
+   */
+  register(definition: ConversationNodeDefinition): () => void {
+    return this.registerDefinition(
+      definition.kind,
+      definition,
+      `conversation Definition "${definition.kind}" is already registered`,
+      `conversationEvents.register(${JSON.stringify(definition.kind)})`,
+    )
+  }
+
+  /**
+   * Register the sole fallback used only when no ordinary Definition matches.
+   * @param definition - fallback Definition.
+   * @returns idempotent disposer.
+   */
+  registerFallback(definition: ConversationNodeDefinition): () => void {
+    if (this.fallback !== undefined) throw new Error('conversation fallback Definition is already registered')
+    const owner = this.ctx
+    const dispose = owner.effect(() => {
+      this.fallback = definition
+      this.refresh()
+      return () => {
+        if (this.fallback !== definition) return
+        this.fallback = undefined
+        this.refresh()
+      }
+    }, `conversationEvents.registerFallback(${JSON.stringify(definition.kind)})`)
+    return () => { void dispose() }
+  }
+
+  /**
+   * Return the current unmatched-event fallback.
+   * @returns installed fallback, when present.
+   */
+  fallbackEntry(): ConversationNodeDefinition | undefined {
+    return this.fallback
+  }
+
+}
diff --git a/packages/client/runtime/src/client/conversation/view-registry.ts b/packages/client/runtime/src/client/conversation/view-registry.ts
new file mode 100644
index 0000000000..1e2e53e141
--- /dev/null
+++ b/packages/client/runtime/src/client/conversation/view-registry.ts
@@ -0,0 +1,26 @@
+import type { Context } from 'cordis'
+import type { ConversationViewDefinition } from '../contract/conversation.ts'
+import { ConversationDefinitionRegistry } from './definition-registry.ts'
+
+/** Runtime registry of per-target Conversation snapshot builders. */
+export class ConversationViewRegistry extends ConversationDefinitionRegistry<ConversationViewDefinition> {
+
+  /** @param ctx - owning Client Runtime context. */
+  constructor(ctx: Context) {
+    super(ctx, 'conversationViews')
+  }
+
+  /**
+   * Register a uniquely named view builder factory for the caller's lifetime.
+   * @param definition - target builder contribution.
+   * @returns idempotent disposer.
+   */
+  register(definition: ConversationViewDefinition): () => void {
+    return this.registerDefinition(
+      definition.target,
+      definition,
+      `conversation view target "${definition.target}" is already registered`,
+      `conversationViews.register(${JSON.stringify(definition.target)})`,
+    )
+  }
+}
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index b7226c0085..fe1ce8f7b0 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -10,8 +10,27 @@ import { SessionHistoryService } from './session-history/service.ts'
 import { WorkspacesService } from './workspaces/service.ts'
 import type { ConversationSnapshot } from './sessions/conversation.ts'
 import type { UseProjection } from './sessions/projection-store.ts'
+import { ConversationEventRegistry } from './conversation/event-registry.ts'
+import { ConversationViewRegistry } from './conversation/view-registry.ts'
+
+export { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
 
 export { SlotsService } from './slots.ts'
+export { ConversationEventRegistry } from './conversation/event-registry.ts'
+export { ConversationViewRegistry } from './conversation/view-registry.ts'
+export { ConversationNodeAssembler } from './sessions/conversation-assembler.ts'
+export { ConversationLocationIndex } from './sessions/conversation-location-index.ts'
+export { conversationContextKey } from './contract/conversation.ts'
+export type {
+  ChatConversationViewNode, ConversationContextReader, ConversationEventInput,
+  ConversationLocationData, ConversationLocationDataScope, ConversationLocationDataStore,
+  ConversationStepDataMap,
+  ConversationLocation, ConversationMatch, ConversationMatchResult,
+  ConversationNodeContext, ConversationNodeDefinition, ConversationPreviousContext,
+  ConversationPublication, ConversationTimelineSnapshot, ConversationTurnDataMap, ConversationViewBuilder,
+  ConversationViewDefinition, ConversationViewNode, StepLocation, TurnLocation,
+} from './contract/conversation.ts'
+export type { ConversationRuntime } from './sessions/conversation-assembler.ts'
 export type { RootOwnerProps } from './slots.ts'
 export { SessionCreateError, SessionsService, scopeOf, workspaceTitleOf } from './sessions/service.ts'
 export { SessionHistoryService } from './session-history/service.ts'
@@ -49,11 +68,17 @@ export type {
 } from './contract/store.ts'
 export type {
   AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
-  AssistantTiming, CommandNode, CompactionSummaryNode, ComposerPhase,
+  AssistantTiming, ChatLocationNodeIndex, ChatNodeStore, ChatSnapshot,
+  CommandNode, CompactionSummaryNode, ComposerPhase,
   ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, QueuedMessage,
-  RunningToolCall,
+  LegacyConversationSlice, PartialAssistant, RunningToolCall,
   SteeringMessageNode, TodoItem, ToolCallBlock, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
+export { EMPTY_CHAT_SNAPSHOT, toAssistantBlock, toAssistantBlocks } from './sessions/conversation.ts'
+export { emptyAssistantBlock } from './sessions/partial.ts'
+export { isTokenDelta } from './sessions/assistant-timing.ts'
+export { contextForm, contextProvenance } from './sessions/context-provenance.ts'
+export { displayFailureMessage } from './sessions/failure-display.ts'
 export type {
   ConversationContext, ConversationContextOriginKind,
 } from './sessions/conversation-context.ts'
@@ -165,6 +190,10 @@ declare module 'cordis' {
   }
   interface Context {
     slots: import('./slots.ts').SlotsService
+    /** Event-to-business-Context Definition registry. */
+    conversationEvents: import('./conversation/event-registry.ts').ConversationEventRegistry
+    /** Per-target Conversation snapshot builder registry. */
+    conversationViews: import('./conversation/view-registry.ts').ConversationViewRegistry
     /** The outward face only; the concrete service stays inside the runtime. */
     sessions: import('./contract/sessions.ts').ISessions
     /** Read-only history sources isolated from Chat sessions and workspace state. */
@@ -182,8 +211,12 @@ export const inject = ['connection', 'typert']
  */
 export function apply(ctx: Context): void {
   ctx.plugin(SlotsService)
+  const conversation = {
+    events: new ConversationEventRegistry(ctx),
+    views: new ConversationViewRegistry(ctx),
+  }
   const connection = ctx.get('connection') as ConnectionHandle
-  const sessions = new SessionsService(ctx, connection.api)
+  const sessions = new SessionsService(ctx, connection.api, conversation)
   ctx.typert.contexts.registerClient('agent', {
     identity: candidate => sessions.scopeOf(candidate),
   })
diff --git a/packages/client/runtime/src/client/sessions/assistant-timing.ts b/packages/client/runtime/src/client/sessions/assistant-timing.ts
index 021c679d04..3c54c9c36d 100644
--- a/packages/client/runtime/src/client/sessions/assistant-timing.ts
+++ b/packages/client/runtime/src/client/sessions/assistant-timing.ts
@@ -1,7 +1,6 @@
-// Shared assistant step-timing fold: both transcript projections (the live
-// window adapter and the trajectory history fold) derive AssistantTiming from
-// the same step/start -> first token delta -> assistant/message sequence, so
-// the derivation lives once here instead of drifting per projection.
+// Shared assistant step-timing fold: Chat Definitions and the Trajectory
+// history fold derive AssistantTiming from the same step/start -> first token
+// delta -> assistant/message sequence.
 
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type { AssistantTiming } from './conversation.ts'
diff --git a/packages/client/runtime/src/client/sessions/conversation-assembler.ts b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
new file mode 100644
index 0000000000..3b6fbd6266
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
@@ -0,0 +1,798 @@
+import type {
+  ConversationContextReader, ConversationEventInput, ConversationLocationData, ConversationMatch,
+  ConversationNodeContext, ConversationNodeDefinition, ConversationPreviousContext,
+  ConversationLocationDataScope, ConversationPublication, ConversationViewBuilder,
+  ConversationViewDefinition, ConversationViewNode,
+} from '../contract/conversation.ts'
+import { conversationContextKey } from '../contract/conversation.ts'
+import {
+  ConversationLocationIndex, type ConversationLocationDataChange,
+} from './conversation-location-index.ts'
+
+interface Dependency {
+  readonly kind: string
+  readonly key: string | undefined
+  readonly revision: number | undefined
+  readonly windowGap: boolean
+}
+
+interface InternalContext {
+  readonly key: string
+  readonly kind: string
+  readonly id: string
+  readonly definition: ConversationNodeDefinition
+  startSeq: number | undefined
+  start: ConversationMatch | undefined
+  matches: ConversationMatch[]
+  state: unknown
+  revision: number
+  readonly current: Map<string, ConversationViewNode | null>
+  readonly locationData: Record<ConversationLocationDataScope, ConversationLocationData | null>
+  dependencies: Map<string, Dependency>
+}
+
+interface PendingMatch {
+  readonly definition: ConversationNodeDefinition
+  readonly id: string
+  readonly match: ConversationMatch
+}
+
+interface ViewState {
+  readonly target: string
+  readonly builder: ConversationViewBuilder
+  snapshot: unknown
+}
+
+const PUBLICATION_RANK: Record<ConversationPublication, number> = {
+  none: 0,
+  'animation-frame': 1,
+  immediate: 2,
+}
+
+const LOCATION_DATA_SCOPES: readonly ConversationLocationDataScope[] = ['step', 'turn']
+
+function emptyLocationData(): Record<ConversationLocationDataScope, ConversationLocationData | null> {
+  return { step: null, turn: null }
+}
+
+function maximumPublication(
+  left: ConversationPublication,
+  right: ConversationPublication,
+): ConversationPublication {
+  return PUBLICATION_RANK[left] >= PUBLICATION_RANK[right] ? left : right
+}
+
+function startSeq(context: InternalContext): number | undefined {
+  return context.startSeq
+}
+
+function insertionIndex(contexts: readonly InternalContext[], seq: number): number {
+  let low = 0
+  let high = contexts.length
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2)
+    const candidate = contexts[middle]
+    if (candidate !== undefined && (candidate.startSeq as number) < seq) low = middle + 1
+    else high = middle
+  }
+  return low
+}
+
+function contextSnapshot<State>(context: InternalContext): ConversationNodeContext<State> {
+  return {
+    key: context.key,
+    kind: context.kind,
+    id: context.id,
+    matches: context.matches,
+    start: context.start,
+    state: context.state as State | undefined,
+    current: context.current,
+  }
+}
+
+function mergeMatches(
+  key: string,
+  additions: readonly ConversationMatch[],
+  existing: readonly ConversationMatch[],
+): ConversationMatch[] {
+  const merged: ConversationMatch[] = []
+  let added = 0
+  let current = 0
+  while (added < additions.length || current < existing.length) {
+    const left = additions[added]
+    const right = existing[current]
+    if (left !== undefined && right !== undefined && left.event.seq === right.event.seq) {
+      throw new Error(`conversation Context ${key} received duplicate Match ${left.event.seq}`)
+    }
+    if (right === undefined || (left !== undefined && left.event.seq < right.event.seq)) {
+      merged.push(left as ConversationMatch)
+      added++
+    } else {
+      merged.push(right)
+      current++
+    }
+  }
+  return merged
+}
+
+/** Event Registry subset consumed by a Session-owned Assembler. */
+export interface ConversationEventDefinitions {
+  /** @returns ordinary Definitions in registration order. */
+  entries(): readonly ConversationNodeDefinition[]
+  /** @returns unmatched-event fallback, when registered. */
+  fallbackEntry(): ConversationNodeDefinition | undefined
+}
+
+/** View Registry subset consumed by a Session-owned Assembler. */
+export interface ConversationViewDefinitions {
+  /** @returns view builder factories in registration order. */
+  entries(): readonly ConversationViewDefinition[]
+}
+
+/**
+ * Session-owned incremental engine that assembles business Contexts from a
+ * contiguous Event window and materializes registered view snapshots.
+ */
+export class ConversationNodeAssembler {
+  private readonly contexts = new Map<string, InternalContext>()
+  private readonly contextsByKind = new Map<string, InternalContext[]>()
+  private readonly contextsBySeq = new Map<number, Set<InternalContext>>()
+  private readonly inputs = new Map<number, ConversationEventInput>()
+  private readonly locationIndex = new ConversationLocationIndex()
+  private readonly dirty = new Set<InternalContext>()
+  private readonly revised = new Set<InternalContext>()
+  private readonly dependents = new Map<string, Set<InternalContext>>()
+  private readonly views = new Map<string, ViewState>()
+  private hasMore = false
+  private replacePending = true
+  private timelineDirty = true
+
+  /**
+   * @param eventDefinitions - live Event Definition registry.
+   * @param viewDefinitions - live view builder registry.
+   */
+  constructor(
+    private readonly eventDefinitions: ConversationEventDefinitions,
+    private readonly viewDefinitions: ConversationViewDefinitions,
+  ) {
+    this.resetViewBuilders()
+  }
+
+  /**
+   * Replace the complete loaded window after open, resync, or gap repair.
+   * @param entries - complete contiguous window.
+   * @param hasMore - whether older history remains outside the window.
+   * @returns immediate publication request.
+   */
+  replaceWindow(entries: readonly ConversationEventInput[], hasMore: boolean): ConversationPublication {
+    this.contexts.clear()
+    this.contextsByKind.clear()
+    this.contextsBySeq.clear()
+    this.inputs.clear()
+    this.dirty.clear()
+    this.revised.clear()
+    this.dependents.clear()
+    this.hasMore = hasMore
+    const sorted = [...entries].sort((left, right) => left.event.seq - right.event.seq)
+    for (const entry of sorted) this.inputs.set(entry.event.seq, entry)
+    this.locationIndex.rebuild(sorted)
+    this.timelineDirty = true
+    for (const entry of sorted) this.matchInput(entry)
+    this.replayDependencies()
+    this.revised.clear()
+    for (const context of this.contexts.values()) this.dirty.add(context)
+    this.replacePending = true
+    return 'immediate'
+  }
+
+  /**
+   * Add one contiguous live tail event without scanning existing Contexts.
+   * @param input - appended Event and optional wire view.
+   * @returns highest requested publication cadence.
+   */
+  append(input: ConversationEventInput): ConversationPublication {
+    if (this.inputs.has(input.event.seq)) return 'none'
+    this.revised.clear()
+    this.inputs.set(input.event.seq, input)
+    let publication: ConversationPublication = 'none'
+    if (isLocationBoundary(input.event.type)) {
+      const previousTimeline = this.locationIndex.snapshot()
+      const changed = this.locationIndex.appendBoundary(input.event)
+      if (this.locationIndex.snapshot() !== previousTimeline) {
+        this.timelineDirty = true
+        publication = 'immediate'
+      }
+      this.replayContexts(this.refreshMatchLocations(changed))
+      if (changed.size > 0) publication = 'immediate'
+    } else {
+      this.locationIndex.appendNonBoundary(input.event)
+    }
+    publication = maximumPublication(publication, this.matchInput(input))
+    if (this.replayRevisedDependents()) publication = 'immediate'
+    this.revised.clear()
+    return publication
+  }
+
+  /**
+   * Add an older page while preserving existing Context and view identities.
+   * @param entries - newly loaded older Events.
+   * @param hasMore - whether history still precedes the expanded window.
+   * @returns highest requested publication cadence.
+   */
+  prepend(entries: readonly ConversationEventInput[], hasMore: boolean): ConversationPublication {
+    this.revised.clear()
+    let publication: ConversationPublication = 'none'
+    const previousHasMore = this.hasMore
+    const fresh = entries
+      .filter(entry => !this.inputs.has(entry.event.seq))
+      .sort((left, right) => left.event.seq - right.event.seq)
+    for (const entry of fresh) this.inputs.set(entry.event.seq, entry)
+    this.hasMore = hasMore
+    const previousTimeline = this.locationIndex.snapshot()
+    const changedLocations = this.locationIndex.rebuild(this.sortedInputs())
+    if (this.locationIndex.snapshot() !== previousTimeline) this.timelineDirty = true
+    const affected = this.refreshMatchLocations(changedLocations)
+    const pending = new Map<string, PendingMatch[]>()
+    for (const entry of fresh) {
+      publication = maximumPublication(publication, this.collectInput(entry, pending))
+    }
+    this.applyPendingMatches(pending, affected)
+    this.replayContexts(affected)
+    if ((fresh.length > 0 || previousHasMore !== hasMore) && this.replayDependencies()) {
+      publication = 'immediate'
+    }
+    if (changedLocations.size > 0) publication = 'immediate'
+    this.revised.clear()
+    return publication
+  }
+
+  /**
+   * Rebuild against the current Registry set after a low-frequency plugin change.
+   * @returns immediate publication request.
+   */
+  rebuildRegistry(): ConversationPublication {
+    this.resetViewBuilders()
+    return this.replaceWindow(this.sortedInputs(), this.hasMore)
+  }
+
+  /**
+   * Materialize dirty Contexts and advance every registered view builder.
+   * @returns whether any view snapshot was rebuilt or incrementally applied.
+   */
+  flush(): boolean {
+    if (!this.replacePending && this.dirty.size === 0 && !this.timelineDirty) return false
+    if (this.replacePending) {
+      this.replaceLocationData()
+      const allByTarget = new Map<string, ConversationViewNode[]>()
+      for (const target of this.views.keys()) allByTarget.set(target, [])
+      for (const context of this.contexts.values()) {
+        for (const target of this.views.keys()) {
+          const node = this.buildNode(context, target)
+          context.current.set(target, node)
+          if (node !== null) allByTarget.get(target)?.push(node)
+        }
+      }
+      for (const view of this.views.values()) {
+        view.snapshot = view.builder.replace({
+          nodes: allByTarget.get(view.target) ?? [],
+          timeline: this.locationIndex.snapshot(),
+        })
+      }
+      this.replacePending = false
+      this.dirty.clear()
+      this.timelineDirty = false
+      return true
+    }
+
+    const upsertsByTarget = new Map<string, ConversationViewNode[]>()
+    for (const target of this.views.keys()) upsertsByTarget.set(target, [])
+    if (this.applyDirtyLocationData()) this.timelineDirty = true
+    for (const context of this.dirty) {
+      for (const target of this.views.keys()) {
+        const previous = context.current.get(target) ?? null
+        const node = this.buildNode(context, target)
+        if (node === null && previous !== null) {
+          throw new Error(
+            `conversation Definition "${context.kind}" withdrew materialized target "${target}"; return the same key with hidden visibility instead`,
+          )
+        }
+        context.current.set(target, node)
+        if (node !== null) upsertsByTarget.get(target)?.push(node)
+      }
+    }
+    this.dirty.clear()
+    const timelineDirty = this.timelineDirty
+    this.timelineDirty = false
+    for (const view of this.views.values()) {
+      const upserts = upsertsByTarget.get(view.target) ?? []
+      if (upserts.length === 0 && !timelineDirty) continue
+      view.snapshot = view.builder.apply({
+        upserts,
+        timeline: this.locationIndex.snapshot(),
+      })
+    }
+    return true
+  }
+
+  /**
+   * Read the latest snapshot of a registered target.
+   * @param target - registered view target.
+   * @returns target snapshot, or undefined when no builder is registered.
+   */
+  snapshot(target: string): unknown {
+    return this.views.get(target)?.snapshot
+  }
+
+  private sortedInputs(): ConversationEventInput[] {
+    return [...this.inputs.values()].sort((left, right) => left.event.seq - right.event.seq)
+  }
+
+  private matchInput(input: ConversationEventInput): ConversationPublication {
+    return this.dispatchInput(input, (definition, id, role) =>
+      this.acceptMatch(definition, id, role, input))
+  }
+
+  private collectInput(
+    input: ConversationEventInput,
+    pending: Map<string, PendingMatch[]>,
+  ): ConversationPublication {
+    return this.dispatchInput(input, (definition, id, role) => {
+      const key = conversationContextKey(definition.kind, id)
+      const match: ConversationMatch = {
+        ...input,
+        role,
+        location: this.locationIndex.locationOf(input.event),
+      }
+      const matches = pending.get(key) ?? []
+      matches.push({ definition, id, match })
+      pending.set(key, matches)
+      return definition.publication?.(match) ?? 'immediate'
+    })
+  }
+
+  private dispatchInput(
+    input: ConversationEventInput,
+    accept: (
+      definition: ConversationNodeDefinition,
+      id: string,
+      role: ConversationMatch['role'],
+    ) => ConversationPublication,
+  ): ConversationPublication {
+    let matched = false
+    let publication: ConversationPublication = 'none'
+    for (const definition of this.eventDefinitions.entries()) {
+      const result = definition.match(input.event)
+      if (result === null) continue
+      matched = true
+      publication = maximumPublication(publication, accept(definition, result.id, result.role))
+    }
+    if (!matched) {
+      const fallback = this.eventDefinitions.fallbackEntry()
+      const result = fallback?.match(input.event) ?? null
+      if (fallback !== undefined && result !== null) {
+        publication = maximumPublication(publication, accept(fallback, result.id, result.role))
+      }
+    }
+    return publication
+  }
+
+  private acceptMatch(
+    definition: ConversationNodeDefinition,
+    id: string,
+    role: ConversationMatch['role'],
+    input: ConversationEventInput,
+  ): ConversationPublication {
+    const key = conversationContextKey(definition.kind, id)
+    let context = this.contexts.get(key)
+    if (role === 'start' && context?.start !== undefined) {
+      throw new Error(`conversation Context ${key} received more than one start Match`)
+    }
+    if (context === undefined) {
+      context = {
+        key,
+        kind: definition.kind,
+        id,
+        definition,
+        startSeq: undefined,
+        start: undefined,
+        matches: [],
+        state: undefined,
+        revision: 0,
+        current: new Map(),
+        locationData: emptyLocationData(),
+        dependencies: new Map(),
+      }
+      this.contexts.set(key, context)
+    }
+    const match: ConversationMatch = {
+      ...input,
+      role,
+      location: this.locationIndex.locationOf(input.event),
+    }
+    const previous = context.matches.at(-1)
+    if (previous !== undefined && previous.event.seq >= input.event.seq) {
+      throw new Error(`conversation Context ${key} received non-appended Match ${input.event.seq}`)
+    }
+    if (role === 'start' && context.matches.length > 0) {
+      throw new Error(`conversation Context ${key} received an update before its start Match`)
+    }
+    context.matches.push(match)
+    if (role === 'start') {
+      context.startSeq = input.event.seq
+      context.start = match
+      this.indexStartedContext(context)
+    }
+    const owners = this.contextsBySeq.get(input.event.seq) ?? new Set<InternalContext>()
+    owners.add(context)
+    this.contextsBySeq.set(input.event.seq, owners)
+
+    if (role === 'start') {
+      this.replayContext(context)
+    } else if (context.state !== undefined) {
+      const typed = contextSnapshot(context) as ConversationNodeContext & { readonly state: unknown }
+      context.state = requireState(definition, 'update', definition.update(typed, match))
+      context.revision++
+      this.revised.add(context)
+    }
+    this.dirty.add(context)
+    return definition.publication?.(match) ?? 'immediate'
+  }
+
+  private applyPendingMatches(
+    pending: ReadonlyMap<string, readonly PendingMatch[]>,
+    affected: Set<InternalContext>,
+  ): void {
+    const startsByKind = new Map<string, InternalContext[]>()
+    for (const [key, entries] of pending) {
+      const first = entries[0]
+      if (first === undefined) continue
+      let context = this.contexts.get(key)
+      if (context === undefined) {
+        context = {
+          key,
+          kind: first.definition.kind,
+          id: first.id,
+          definition: first.definition,
+          startSeq: undefined,
+          start: undefined,
+          matches: [],
+          state: undefined,
+          revision: 0,
+          current: new Map(),
+          locationData: emptyLocationData(),
+          dependencies: new Map(),
+        }
+        this.contexts.set(key, context)
+      }
+      let discoveredStart: ConversationMatch | undefined
+      const additions = entries
+        .map((entry) => {
+          if (entry.definition !== context.definition || entry.id !== context.id) {
+            throw new Error(`conversation Context ${key} received inconsistent Definition identity`)
+          }
+          if (entry.match.role === 'start') {
+            if (discoveredStart !== undefined || context.start !== undefined) {
+              throw new Error(`conversation Context ${key} received more than one start Match`)
+            }
+            discoveredStart = entry.match
+          }
+          const owners = this.contextsBySeq.get(entry.match.event.seq) ?? new Set<InternalContext>()
+          owners.add(context)
+          this.contextsBySeq.set(entry.match.event.seq, owners)
+          return entry.match
+        })
+        .sort((left, right) => left.event.seq - right.event.seq)
+      context.matches = mergeMatches(context.key, additions, context.matches)
+      if (discoveredStart !== undefined) {
+        context.start = discoveredStart
+        context.startSeq = discoveredStart.event.seq
+        const starts = startsByKind.get(context.kind) ?? []
+        starts.push(context)
+        startsByKind.set(context.kind, starts)
+      }
+      if (context.start !== undefined && context.matches[0] !== context.start) {
+        throw new Error(`conversation Context ${context.key} received an update before its start Match`)
+      }
+      affected.add(context)
+      this.dirty.add(context)
+    }
+    for (const [kind, contexts] of startsByKind) this.indexStartedContexts(kind, contexts)
+  }
+
+  private replayContexts(contexts: ReadonlySet<InternalContext>): void {
+    const ordered = [...contexts].sort((left, right) =>
+      (left.startSeq ?? Number.POSITIVE_INFINITY) - (right.startSeq ?? Number.POSITIVE_INFINITY))
+    for (const context of ordered) {
+      if (context.start === undefined) {
+        context.state = undefined
+        this.dirty.add(context)
+        continue
+      }
+      this.replayContext(context)
+    }
+  }
+
+  private replayContext(context: InternalContext): void {
+    const start = context.start
+    if (start === undefined) {
+      context.state = undefined
+      return
+    }
+    if (context.matches[0] !== start) {
+      throw new Error(`conversation Context ${context.key} received an update before its start Match`)
+    }
+    const dependencies = new Map<string, Dependency>()
+    const reader = this.readerFor(start.event.seq, dependencies)
+    context.state = undefined
+    context.state = requireState(
+      context.definition,
+      'start',
+      context.definition.start(contextSnapshot(context), start, reader),
+    )
+    this.replaceDependencies(context, dependencies)
+    for (let index = 1; index < context.matches.length; index++) {
+      const match = context.matches[index]
+      if (match === undefined || match.role !== 'update') continue
+      const typed = contextSnapshot(context) as ConversationNodeContext & { readonly state: unknown }
+      context.state = requireState(
+        context.definition,
+        'update',
+        context.definition.update(typed, match),
+      )
+    }
+    context.revision++
+    this.revised.add(context)
+    this.dirty.add(context)
+  }
+
+  private replaceDependencies(context: InternalContext, dependencies: Map<string, Dependency>): void {
+    for (const dependency of context.dependencies.values()) {
+      if (dependency.key === undefined) continue
+      const current = this.dependents.get(dependency.key)
+      current?.delete(context)
+      if (current?.size === 0) this.dependents.delete(dependency.key)
+    }
+    context.dependencies = dependencies
+    for (const dependency of dependencies.values()) {
+      if (dependency.key === undefined) continue
+      const current = this.dependents.get(dependency.key) ?? new Set()
+      current.add(context)
+      this.dependents.set(dependency.key, current)
+    }
+  }
+
+  private replayRevisedDependents(): boolean {
+    const pending = [...this.revised]
+    const replayed = new Set<InternalContext>()
+    for (let index = 0; index < pending.length; index++) {
+      const dependency = pending[index]
+      if (dependency === undefined) continue
+      for (const dependent of this.dependents.get(dependency.key) ?? []) {
+        if (replayed.has(dependent)) continue
+        replayed.add(dependent)
+        this.replayContext(dependent)
+        pending.push(dependent)
+      }
+    }
+    return replayed.size > 0
+  }
+
+  private readerFor(
+    beforeSeq: number,
+    dependencies: Map<string, Dependency>,
+  ): ConversationContextReader {
+    return {
+      previous: <State>(kind: string): ConversationPreviousContext<State> | undefined => {
+        const predecessor = this.previousContext(kind, beforeSeq)
+        dependencies.set(kind, {
+          kind,
+          key: predecessor?.key,
+          revision: predecessor?.revision,
+          windowGap: predecessor === undefined && this.hasMore,
+        })
+        if (predecessor?.state === undefined) return undefined
+        const seq = startSeq(predecessor)
+        if (seq === undefined) return undefined
+        return {
+          key: predecessor.key,
+          kind: predecessor.kind,
+          id: predecessor.id,
+          startSeq: seq,
+          state: predecessor.state as Readonly<State>,
+          matches: predecessor.matches,
+        }
+      },
+    }
+  }
+
+  private previousContext(kind: string, beforeSeq: number): InternalContext | undefined {
+    const candidates = this.contextsByKind.get(kind) ?? []
+    const indexBefore = insertionIndex(candidates, beforeSeq)
+    for (let index = indexBefore - 1; index >= 0; index--) {
+      const candidate = candidates[index]
+      if (candidate?.state !== undefined) return candidate
+    }
+    return undefined
+  }
+
+  /** Insert one newly discovered start into its Definition's ordered predecessor index. */
+  private indexStartedContext(context: InternalContext): void {
+    const seq = context.startSeq
+    if (seq === undefined) return
+    const candidates = this.contextsByKind.get(context.kind) ?? []
+    const previous = candidates.at(-1)
+    if (previous === undefined || (previous.startSeq as number) < seq) candidates.push(context)
+    else candidates.splice(insertionIndex(candidates, seq), 0, context)
+    this.contextsByKind.set(context.kind, candidates)
+  }
+
+  private indexStartedContexts(kind: string, additions: readonly InternalContext[]): void {
+    if (additions.length === 0) return
+    const sorted = [...additions].sort((left, right) =>
+      (left.startSeq as number) - (right.startSeq as number))
+    const existing = this.contextsByKind.get(kind) ?? []
+    const merged: InternalContext[] = []
+    let before = 0
+    let added = 0
+    while (before < existing.length || added < sorted.length) {
+      const left = existing[before]
+      const right = sorted[added]
+      if (right === undefined || (left !== undefined && (left.startSeq as number) < (right.startSeq as number))) {
+        merged.push(left as InternalContext)
+        before++
+      } else {
+        merged.push(right)
+        added++
+      }
+    }
+    this.contextsByKind.set(kind, merged)
+  }
+
+  private replayDependencies(): boolean {
+    let replayed = false
+    const ordered = [...this.contexts.values()]
+      .filter(context => startSeq(context) !== undefined)
+      .sort((left, right) => (startSeq(left) as number) - (startSeq(right) as number))
+    for (const context of ordered) {
+      if (context.state === undefined || context.dependencies.size === 0) continue
+      const before = startSeq(context)
+      if (before === undefined) continue
+      let changed = false
+      for (const dependency of context.dependencies.values()) {
+        const current = this.previousContext(dependency.kind, before)
+        const windowGap = current === undefined && this.hasMore
+        if (current?.key !== dependency.key
+          || current?.revision !== dependency.revision
+          || windowGap !== dependency.windowGap) {
+          changed = true
+          break
+        }
+      }
+      if (changed) {
+        this.replayContext(context)
+        replayed = true
+      }
+    }
+    return replayed
+  }
+
+  private refreshMatchLocations(changedSeqs: ReadonlySet<number>): Set<InternalContext> {
+    const affected = new Set<InternalContext>()
+    if (changedSeqs.size === 0) return affected
+    for (const seq of changedSeqs) {
+      for (const context of this.contextsBySeq.get(seq) ?? []) affected.add(context)
+    }
+    for (const context of affected) {
+      let start = context.start
+      const matches = context.matches.map((match): ConversationMatch => {
+        if (!changedSeqs.has(match.event.seq)) return match
+        const refreshed = { ...match, location: this.locationIndex.locationOf(match.event) }
+        if (match === start) start = refreshed
+        return refreshed
+      })
+      context.matches = matches
+      context.start = start
+    }
+    return affected
+  }
+
+  private buildNode(context: InternalContext, target: string): ConversationViewNode | null {
+    const node = context.definition.buildViewNode(contextSnapshot(context), target)
+    if (node === null) return null
+    if (node.key !== context.key) {
+      throw new Error(`conversation Definition "${context.kind}" returned unstable key "${node.key}"; expected "${context.key}"`)
+    }
+    if (node.target !== target) {
+      throw new Error(`conversation Definition "${context.kind}" returned target "${node.target}" while building "${target}"`)
+    }
+    return node
+  }
+
+  private buildLocationData(
+    context: InternalContext,
+    scope: ConversationLocationDataScope,
+  ): ConversationLocationData | null {
+    const build = context.definition.buildLocationData
+    if (build === undefined) return null
+    const data = build(contextSnapshot(context), scope)
+    if (data === null) return null
+    if (data.kind !== scope) {
+      throw new Error(
+        `conversation Definition "${context.kind}" published ${data.kind} data through its ${scope} scope`,
+      )
+    }
+    if (data.key !== context.kind) {
+      throw new Error(
+        `conversation Definition "${context.kind}" published Location data key "${data.key}"; expected its owned kind`,
+      )
+    }
+    if (!Number.isSafeInteger(data.turn) || data.turn < 0) {
+      throw new Error(`conversation Definition "${context.kind}" published invalid turn ${data.turn}`)
+    }
+    if (data.kind === 'step' && (!Number.isSafeInteger(data.step) || (data.step as number) < 0)) {
+      throw new Error(`conversation Definition "${context.kind}" published invalid step ${String(data.step)}`)
+    }
+    return data
+  }
+
+  private replaceLocationData(): void {
+    const entries: { owner: string; data: ConversationLocationData }[] = []
+    for (const scope of LOCATION_DATA_SCOPES) {
+      for (const context of this.contexts.values()) {
+        const data = this.buildLocationData(context, scope)
+        context.locationData[scope] = data
+        if (data !== null) entries.push({ owner: context.key, data })
+      }
+      this.locationIndex.replaceData(entries)
+    }
+  }
+
+  private applyDirtyLocationData(): boolean {
+    let changed = false
+    for (const scope of LOCATION_DATA_SCOPES) {
+      const changes: ConversationLocationDataChange[] = []
+      for (const context of this.dirty) {
+        const previous = context.locationData[scope]
+        const next = this.buildLocationData(context, scope)
+        context.locationData[scope] = next
+        if (previous !== next) changes.push({ owner: context.key, previous, next })
+      }
+      changed = this.locationIndex.applyData(changes) || changed
+    }
+    return changed
+  }
+
+  private resetViewBuilders(): void {
+    this.views.clear()
+    for (const definition of this.viewDefinitions.entries()) {
+      const builder = definition.create()
+      this.views.set(definition.target, {
+        target: definition.target,
+        builder,
+        snapshot: builder.empty,
+      })
+    }
+    this.replacePending = true
+  }
+}
+
+function isLocationBoundary(type: string): boolean {
+  return type === 'turn/start' || type === 'turn/end' || type === 'step/start' || type === 'step/end'
+}
+
+function requireState(
+  definition: ConversationNodeDefinition,
+  phase: 'start' | 'update',
+  state: unknown,
+): unknown {
+  if (state === undefined) {
+    throw new Error(`conversation Definition "${definition.kind}" returned undefined from ${phase}()`)
+  }
+  return state
+}
+
+/** Structural registry pair accepted by Session and SessionManager. */
+export interface ConversationRuntime {
+  readonly events: ConversationEventDefinitions & { subscribe(listener: () => void): () => void }
+  readonly views: ConversationViewDefinitions & { subscribe(listener: () => void): () => void }
+}
diff --git a/packages/client/runtime/src/client/sessions/conversation-location-index.ts b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
new file mode 100644
index 0000000000..20fe3efdff
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
@@ -0,0 +1,508 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {
+  ConversationEventInput, ConversationLocation, ConversationLocationData,
+  ConversationLocationDataStore, ConversationStepDataMap, ConversationTimelineSnapshot,
+  ConversationTurnDataMap, StepLocation, TurnLocation,
+} from '../contract/conversation.ts'
+
+interface OwnedLocationData {
+  readonly owner: string
+  readonly value: unknown
+}
+
+/** One Context's previous and next Location-data publication. */
+export interface ConversationLocationDataChange {
+  readonly owner: string
+  readonly previous: ConversationLocationData | null
+  readonly next: ConversationLocationData | null
+}
+
+class MutableLocationDataStore {
+  private entries = new Map<string, OwnedLocationData>()
+
+  get<Key extends string>(key: Key): unknown {
+    return this.entries.get(key)?.value
+  }
+
+  remove(owner: string, key: string): boolean {
+    const current = this.entries.get(key)
+    if (current?.owner !== owner) return false
+    this.entries.delete(key)
+    return true
+  }
+
+  set(owner: string, key: string, value: unknown): boolean {
+    const current = this.entries.get(key)
+    if (current !== undefined && current.owner !== owner) {
+      throw new Error(`conversation Location data "${key}" is already owned by ${current.owner}`)
+    }
+    if (current?.value === value) return false
+    this.entries.set(key, { owner, value })
+    return true
+  }
+
+  replace(entries: ReadonlyMap<string, OwnedLocationData>): boolean {
+    let changed = this.entries.size !== entries.size
+    if (!changed) {
+      for (const [key, value] of entries) {
+        const current = this.entries.get(key)
+        if (current?.owner !== value.owner || current.value !== value.value) {
+          changed = true
+          break
+        }
+      }
+    }
+    if (changed) this.entries = new Map(entries)
+    return changed
+  }
+}
+
+interface Coordinates {
+  readonly turn?: number
+  readonly step?: number
+  readonly session?: true
+}
+
+interface StepDraft {
+  readonly turn: number
+  readonly step: number
+  firstSeq: number
+  start?: SessionEvent<'step/start'>
+  end?: SessionEvent<'step/end'>
+}
+
+interface TurnDraft {
+  readonly turn: number
+  firstSeq: number
+  start?: SessionEvent<'turn/start'>
+  end?: SessionEvent<'turn/end'>
+  readonly steps: Map<number, StepDraft>
+}
+
+const SESSION_LOCATION = { kind: 'session' } as const
+const UNRESOLVED_LOCATION = { kind: 'unresolved' } as const
+
+function payloadCoordinates(event: SessionEvent): Coordinates {
+  const data = event.data as unknown as { turn?: unknown; step?: unknown }
+  if (data.turn === null) return { session: true }
+  const turn = Number.isSafeInteger(data.turn) && (data.turn as number) >= 0
+    ? data.turn as number
+    : undefined
+  const step = Number.isSafeInteger(data.step) && (data.step as number) >= 0
+    ? data.step as number
+    : undefined
+  return { ...turn === undefined ? {} : { turn }, ...step === undefined ? {} : { step } }
+}
+
+function sameReferences<T>(left: readonly T[], right: readonly T[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+function sameStep(left: StepLocation | undefined, right: StepLocation): boolean {
+  return left !== undefined
+    && left.start === right.start && left.end === right.end && left.status === right.status
+    && left.data === right.data
+}
+
+function sameTurn(left: TurnLocation | undefined, right: TurnLocation): boolean {
+  return left !== undefined
+    && left.start === right.start && left.end === right.end && left.status === right.status
+    && left.data === right.data && sameReferences(left.steps, right.steps)
+}
+
+function sameLocation(left: ConversationLocation | undefined, right: ConversationLocation | undefined): boolean {
+  if (left === undefined || right === undefined || left.kind !== right.kind) return left === right
+  if (left.kind === 'session' || left.kind === 'unresolved') return true
+  if (right.kind === 'session' || right.kind === 'unresolved') return false
+  if (left.kind === 'turn' || right.kind === 'turn') {
+    return left.kind === 'turn' && right.kind === 'turn' && left.turn === right.turn
+  }
+  return left.turn === right.turn && left.step === right.step
+}
+
+/** Session-owned Turn/Step timeline and event-to-Location index. */
+export class ConversationLocationIndex {
+  private coordinates = new Map<number, Coordinates>()
+  private locations = new Map<number, ConversationLocation>()
+  private seqsByTurn = new Map<number, Set<number>>()
+  private timeline: ConversationTimelineSnapshot = { turnOrder: [], turns: new Map() }
+  private readonly turnDataStores = new Map<number, MutableLocationDataStore>()
+  private readonly stepDataStores = new Map<string, MutableLocationDataStore>()
+  private currentTurn: number | undefined
+  private currentStep: number | undefined
+
+  /**
+   * Return the current reference-stable timeline.
+   * @returns current timeline snapshot.
+   */
+  snapshot(): ConversationTimelineSnapshot {
+    return this.timeline
+  }
+
+  /** Replace all Definition-owned Location values while preserving reader identities. */
+  replaceData(entries: readonly { readonly owner: string; readonly data: ConversationLocationData }[]): boolean {
+    const turns = new Map<number, Map<string, OwnedLocationData>>()
+    const steps = new Map<string, Map<string, OwnedLocationData>>()
+    for (const { owner, data } of entries) {
+      const values = data.kind === 'turn'
+        ? turns.get(data.turn) ?? new Map<string, OwnedLocationData>()
+        : steps.get(stepDataKey(data.turn, requireStep(data))) ?? new Map<string, OwnedLocationData>()
+      const current = values.get(data.key)
+      if (current !== undefined && current.owner !== owner) {
+        throw new Error(`conversation Location data "${data.key}" is already owned by ${current.owner}`)
+      }
+      values.set(data.key, { owner, value: data.value })
+      if (data.kind === 'turn') turns.set(data.turn, values)
+      else steps.set(stepDataKey(data.turn, requireStep(data)), values)
+    }
+    let changed = false
+    for (const turn of new Set([...this.turnDataStores.keys(), ...turns.keys()])) {
+      changed = this.mutableTurnData(turn).replace(turns.get(turn) ?? new Map()) || changed
+    }
+    for (const step of new Set([...this.stepDataStores.keys(), ...steps.keys()])) {
+      changed = this.mutableStepData(step).replace(steps.get(step) ?? new Map()) || changed
+    }
+    return changed
+  }
+
+  /** Apply changed Context publications without rebuilding Turn/Step membership. */
+  applyData(changes: readonly ConversationLocationDataChange[]): boolean {
+    let changed = false
+    for (const change of changes) {
+      const previous = change.previous
+      if (previous === null) continue
+      changed = this.storeFor(previous).remove(change.owner, previous.key) || changed
+    }
+    for (const change of changes) {
+      const next = change.next
+      if (next === null) continue
+      changed = this.storeFor(next).set(change.owner, next.key, next.value) || changed
+    }
+    return changed
+  }
+
+  /**
+   * Resolve the latest Location for one event.
+   * @param event - event already ingested into this index.
+   * @returns current Location, falling back to session when it has no Turn/Step affinity.
+   */
+  locationOf(event: SessionEvent): ConversationLocation {
+    return this.locations.get(event.seq) ?? SESSION_LOCATION
+  }
+
+  /**
+   * Rebuild timeline facts after replace/prepend or a boundary append.
+   * @param entries - complete current window in ascending seq order.
+   * @returns seqs whose resolved Location changed.
+   */
+  rebuild(entries: readonly ConversationEventInput[]): ReadonlySet<number> {
+    const previousLocations = this.locations
+    const turns = new Map<number, TurnDraft>()
+    const coordinates = new Map<number, Coordinates>()
+    let currentTurn: number | undefined
+    let currentStep: number | undefined
+
+    const turnDraft = (turn: number, seq: number): TurnDraft => {
+      let draft = turns.get(turn)
+      if (draft === undefined) {
+        draft = { turn, firstSeq: seq, steps: new Map() }
+        turns.set(turn, draft)
+      } else {
+        draft.firstSeq = Math.min(draft.firstSeq, seq)
+      }
+      return draft
+    }
+    const stepDraft = (turn: number, step: number, seq: number): StepDraft => {
+      const owner = turnDraft(turn, seq)
+      let draft = owner.steps.get(step)
+      if (draft === undefined) {
+        draft = { turn, step, firstSeq: seq }
+        owner.steps.set(step, draft)
+      } else {
+        draft.firstSeq = Math.min(draft.firstSeq, seq)
+      }
+      return draft
+    }
+
+    for (const { event } of entries) {
+      const explicit = payloadCoordinates(event)
+      if (event.type === 'turn/start') {
+        currentTurn = event.data.turn
+        currentStep = undefined
+      }
+      if (event.type === 'step/start') {
+        currentTurn = event.data.turn
+        currentStep = event.data.step
+      }
+      if (explicit.session !== true && explicit.turn !== undefined) {
+        if (currentTurn !== explicit.turn) currentStep = undefined
+        currentTurn = explicit.turn
+        if (explicit.step !== undefined) currentStep = explicit.step
+      }
+      const turn = explicit.session === true ? undefined : explicit.turn ?? currentTurn
+      const step = explicit.session === true || event.type === 'turn/start' || event.type === 'turn/end'
+        ? undefined
+        : explicit.step ?? (turn === currentTurn ? currentStep : undefined)
+      coordinates.set(event.seq, {
+        ...turn === undefined ? {} : { turn },
+        ...turn === undefined || step === undefined ? {} : { step },
+      })
+      if (turn !== undefined) turnDraft(turn, event.seq)
+      if (turn !== undefined && step !== undefined) stepDraft(turn, step, event.seq)
+
+      if (event.type === 'turn/start') {
+        turnDraft(event.data.turn, event.seq).start = event
+      } else if (event.type === 'turn/end') {
+        turnDraft(event.data.turn, event.seq).end = event
+      } else if (event.type === 'step/start') {
+        stepDraft(event.data.turn, event.data.step, event.seq).start = event
+      } else if (event.type === 'step/end') {
+        stepDraft(event.data.turn, event.data.step, event.seq).end = event
+      }
+
+      if (event.type === 'step/end' && currentTurn === event.data.turn && currentStep === event.data.step) {
+        currentStep = undefined
+      }
+      if (event.type === 'turn/end' && currentTurn === event.data.turn) {
+        currentTurn = undefined
+        currentStep = undefined
+      }
+    }
+
+    const previousTurns = this.timeline.turns
+    const nextTurns = new Map<number, TurnLocation>()
+    const orderedDrafts = [...turns.values()].sort((left, right) => left.firstSeq - right.firstSeq)
+    for (const draft of orderedDrafts) {
+      const previousTurn = previousTurns.get(draft.turn)
+      const previousSteps = new Map(previousTurn?.steps.map(step => [step.step, step]) ?? [])
+      const steps = [...draft.steps.values()]
+        .sort((left, right) => left.firstSeq - right.firstSeq)
+        .map((candidate): StepLocation => {
+          const value: StepLocation = {
+            turn: candidate.turn,
+            step: candidate.step,
+            start: candidate.start,
+            end: candidate.end,
+            status: candidate.end !== undefined
+              ? 'closed'
+              : candidate.start === undefined ? 'unknown' : 'open',
+            data: this.stepData(candidate.turn, candidate.step),
+          }
+          const previous = previousSteps.get(candidate.step)
+          return sameStep(previous, value) ? previous as StepLocation : value
+        })
+      const value: TurnLocation = {
+        turn: draft.turn,
+        start: draft.start,
+        end: draft.end,
+        status: draft.end !== undefined ? 'closed' : draft.start === undefined ? 'unknown' : 'open',
+        steps,
+        data: this.turnData(draft.turn),
+      }
+      nextTurns.set(draft.turn, sameTurn(previousTurn, value) ? previousTurn as TurnLocation : value)
+    }
+
+    const nextOrder = orderedDrafts.map(draft => draft.turn)
+    const turnOrder = this.timeline.turnOrder.length === nextOrder.length
+      && this.timeline.turnOrder.every((turn, index) => turn === nextOrder[index])
+      ? this.timeline.turnOrder
+      : nextOrder
+    let sameMap = previousTurns.size === nextTurns.size
+    if (sameMap) {
+      for (const [turn, value] of nextTurns) {
+        if (previousTurns.get(turn) !== value) {
+          sameMap = false
+          break
+        }
+      }
+    }
+    this.timeline = sameMap && turnOrder === this.timeline.turnOrder
+      ? this.timeline
+      : { turnOrder, turns: nextTurns }
+    this.coordinates = coordinates
+    this.locations = new Map()
+    this.seqsByTurn = new Map()
+    for (const { event } of entries) {
+      const coordinates = this.coordinates.get(event.seq)
+      if (coordinates?.turn !== undefined) this.indexTurnSeq(coordinates.turn, event.seq)
+      this.locations.set(event.seq, this.resolve(event.seq))
+    }
+    this.currentTurn = currentTurn
+    this.currentStep = currentStep
+
+    const changed = new Set<number>()
+    for (const { event } of entries) {
+      if (!sameLocation(previousLocations.get(event.seq), this.locations.get(event.seq))) {
+        changed.add(event.seq)
+      }
+    }
+    return changed
+  }
+
+  /**
+   * Append one Turn/Step boundary while revisiting only the owning Turn.
+   * @param event - contiguous tail boundary event.
+   * @returns seqs whose immutable Location reference changed.
+   */
+  appendBoundary(event: SessionEvent): ReadonlySet<number> {
+    if (event.type !== 'turn/start' && event.type !== 'turn/end'
+      && event.type !== 'step/start' && event.type !== 'step/end') {
+      throw new Error(`conversation Location boundary expected, received ${event.type}`)
+    }
+
+    const explicit = payloadCoordinates(event)
+    if (event.type === 'turn/start') {
+      this.currentTurn = event.data.turn
+      this.currentStep = undefined
+    } else if (event.type === 'step/start') {
+      this.currentTurn = event.data.turn
+      this.currentStep = event.data.step
+    }
+    if (explicit.turn !== undefined) {
+      if (this.currentTurn !== explicit.turn) this.currentStep = undefined
+      this.currentTurn = explicit.turn
+      if (explicit.step !== undefined) this.currentStep = explicit.step
+    }
+    const turnNumber = explicit.turn ?? this.currentTurn
+    if (turnNumber === undefined) throw new Error(`conversation boundary ${event.type} has no turn`)
+    const stepNumber = event.type === 'turn/start' || event.type === 'turn/end'
+      ? undefined
+      : explicit.step ?? (turnNumber === this.currentTurn ? this.currentStep : undefined)
+    this.coordinates.set(event.seq, {
+      turn: turnNumber,
+      ...stepNumber === undefined ? {} : { step: stepNumber },
+    })
+    this.indexTurnSeq(turnNumber, event.seq)
+
+    const previousTurn = this.timeline.turns.get(turnNumber)
+    let steps = previousTurn?.steps ?? []
+    if (event.type === 'step/start' || event.type === 'step/end') {
+      const number = event.data.step
+      const previousStep = steps.find(candidate => candidate.step === number)
+      const candidate: StepLocation = {
+        turn: turnNumber,
+        step: number,
+        start: event.type === 'step/start' ? event : previousStep?.start,
+        end: event.type === 'step/end' ? event : previousStep?.end,
+        status: event.type === 'step/end' || previousStep?.end !== undefined ? 'closed' : 'open',
+        data: this.stepData(turnNumber, number),
+      }
+      const nextStep = sameStep(previousStep, candidate) ? previousStep as StepLocation : candidate
+      const index = steps.findIndex(step => step.step === number)
+      steps = index < 0
+        ? [...steps, nextStep]
+        : steps.map((step, at) => at === index ? nextStep : step)
+    }
+    const candidate: TurnLocation = {
+      turn: turnNumber,
+      start: event.type === 'turn/start' ? event : previousTurn?.start,
+      end: event.type === 'turn/end' ? event : previousTurn?.end,
+      status: event.type === 'turn/end' || previousTurn?.end !== undefined
+        ? 'closed'
+        : event.type === 'turn/start' || previousTurn?.start !== undefined ? 'open' : 'unknown',
+      steps,
+      data: this.turnData(turnNumber),
+    }
+    const turn = sameTurn(previousTurn, candidate) ? previousTurn as TurnLocation : candidate
+    const turns = new Map(this.timeline.turns)
+    turns.set(turnNumber, turn)
+    const turnOrder = previousTurn === undefined
+      ? [...this.timeline.turnOrder, turnNumber]
+      : this.timeline.turnOrder
+    this.timeline = { turnOrder, turns }
+
+    const changed = new Set<number>()
+    for (const seq of this.seqsByTurn.get(turnNumber) ?? []) {
+      const previous = this.locations.get(seq)
+      const next = this.resolve(seq)
+      this.locations.set(seq, next)
+      if (!sameLocation(previous, next)) changed.add(seq)
+    }
+
+    if (event.type === 'step/end' && this.currentTurn === event.data.turn && this.currentStep === event.data.step) {
+      this.currentStep = undefined
+    }
+    if (event.type === 'turn/end' && this.currentTurn === event.data.turn) {
+      this.currentTurn = undefined
+      this.currentStep = undefined
+    }
+    return changed
+  }
+
+  /**
+   * Index one non-boundary tail event without rescanning the window.
+   * @param event - contiguous appended event.
+   */
+  appendNonBoundary(event: SessionEvent): void {
+    const explicit = payloadCoordinates(event)
+    if (explicit.session === true) {
+      this.coordinates.set(event.seq, {})
+      this.locations.set(event.seq, SESSION_LOCATION)
+      return
+    }
+    if (explicit.turn !== undefined) {
+      if (this.currentTurn !== explicit.turn) this.currentStep = undefined
+      this.currentTurn = explicit.turn
+      if (explicit.step !== undefined) this.currentStep = explicit.step
+    }
+    const turn = explicit.turn ?? this.currentTurn
+    const step = explicit.step ?? (turn === this.currentTurn ? this.currentStep : undefined)
+    this.coordinates.set(event.seq, {
+      ...turn === undefined ? {} : { turn },
+      ...turn === undefined || step === undefined ? {} : { step },
+    })
+    if (turn !== undefined) this.indexTurnSeq(turn, event.seq)
+    this.locations.set(event.seq, this.resolve(event.seq))
+  }
+
+  private indexTurnSeq(turn: number, seq: number): void {
+    const current = this.seqsByTurn.get(turn) ?? new Set<number>()
+    current.add(seq)
+    this.seqsByTurn.set(turn, current)
+  }
+
+  private turnData(turn: number): ConversationLocationDataStore<ConversationTurnDataMap> {
+    return this.mutableTurnData(turn) as ConversationLocationDataStore<ConversationTurnDataMap>
+  }
+
+  private stepData(turn: number, step: number): ConversationLocationDataStore<ConversationStepDataMap> {
+    return this.mutableStepData(stepDataKey(turn, step)) as ConversationLocationDataStore<ConversationStepDataMap>
+  }
+
+  private mutableTurnData(turn: number): MutableLocationDataStore {
+    const current = this.turnDataStores.get(turn) ?? new MutableLocationDataStore()
+    this.turnDataStores.set(turn, current)
+    return current
+  }
+
+  private mutableStepData(key: string): MutableLocationDataStore {
+    const current = this.stepDataStores.get(key) ?? new MutableLocationDataStore()
+    this.stepDataStores.set(key, current)
+    return current
+  }
+
+  private storeFor(data: ConversationLocationData): MutableLocationDataStore {
+    return data.kind === 'turn'
+      ? this.mutableTurnData(data.turn)
+      : this.mutableStepData(stepDataKey(data.turn, requireStep(data)))
+  }
+
+  private resolve(seq: number): ConversationLocation {
+    const coordinates = this.coordinates.get(seq)
+    if (coordinates?.turn === undefined) return SESSION_LOCATION
+    const turn = this.timeline.turns.get(coordinates.turn)
+    if (turn === undefined) return UNRESOLVED_LOCATION
+    if (coordinates.step === undefined) return { kind: 'turn', turn }
+    const step = turn.steps.find(candidate => candidate.step === coordinates.step)
+    return step === undefined ? { kind: 'turn', turn } : { kind: 'step', turn, step }
+  }
+}
+
+function stepDataKey(turn: number, step: number): string {
+  return `${turn}:${step}`
+}
+
+function requireStep(data: ConversationLocationData): number {
+  if (data.kind === 'step' && data.step !== undefined) return data.step
+  throw new Error(`conversation Step data "${data.key}" requires a step`)
+}
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index 2681bb33f3..99daa7c8a5 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -13,6 +13,9 @@ import type {
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { PendingInteraction } from './pending.ts'
 import type { ContextProvenanceView, KnownContextForm } from './context-provenance.ts'
+import type {
+  ChatConversationViewNode, ConversationTimelineSnapshot,
+} from '../contract/conversation.ts'
 export type { TodoItem }
 
 /** Request configuration recorded for one provider call. */
@@ -206,7 +209,7 @@ export interface CompactionSummaryNode {
  * Fallback for surface events this UI version does not know: the documented
  * default arm of `SessionEventMap`, which is merge-extensible, so the
  * projection's switch cannot end in `assertNever`. No event produces this node
- * today — `isAppendSurfaceEvent` admits only the four types in core's
+ * today — `isAppendSurfaceEvent` admits only the three types in core's
  * `SurfaceEventType`, and each has its own arm — and it exists so widening that
  * set core-side degrades to a raw row instead of dropping the event silently.
  */
@@ -222,8 +225,8 @@ export interface UnknownSurfaceNode {
 /**
  * One slash-command lifecycle folded from the log-only `command/run` /
  * `command/done` pair (paired by commandId, mirroring tool call↔result).
- * Log-only events are not surface events, so the TranscriptAdapter indexes
- * them separately and merges the nodes into the flow by seq. A window cut
+ * Log-only events are not surface events, so the command Definition indexes
+ * them separately and the Chat builder orders the resulting node by seq. A window cut
  * between the pair soft-falls like tool pairs: a done with no in-window run
  * still builds a node (name/args null), and a run with no done renders as
  * still executing.
@@ -311,21 +314,19 @@ export type OpenState = 'cold' | 'loading' | 'open' | 'error'
  * Input-area shape of an OPEN session, derived at snapshot assembly (the one
  * place that knows the predicate — consumers switch, never re-derive):
  *
- * - `blank`: no activity ever (no nodes, no partial, not running, no pending
- *   waits, no prompt attempt) — the UI renders the blank-session guidance
- *   hero.
- * - `engaging`: the first prompt was initiated but no content landed yet —
- *   the UI holds the composer through the accept → running → first-event
- *   frames. Entered synchronously before prompt()'s first await.
- * - `active`: content exists (nodes, partial, running turn, or pending
- *   waits) — the ordinary conversation view.
+ * - `blank`: the authoritative blank bit is still set and no prompt was
+ *   attempted — the UI renders the blank-session guidance hero.
+ * - `engaging`: a first prompt was attempted, but no accepted turn or other
+ *   authoritative activity signal has arrived — the UI keeps the composer
+ *   visible through admission and error frames.
+ * - `active`: the session is non-blank beyond its pending first prompt, is
+ *   running, or owns a pending interaction — the ordinary conversation view.
  *
- * Monotone within a session object: blank → engaging → active, no returns.
  * A failed first prompt stays `engaging` (composer + error strip — retry
- * semantics; bouncing back to the hero would discard the error context).
+ * semantics; returning to the hero would discard the error context).
  * Sessions whose window is not open (`loading`/`error`) are outside phase
  * jurisdiction: consumers branch on {@link ConversationSnapshot.openState}
- * first (phase still reports `active`-ish facts but must not be rendered).
+ * first.
  */
 export type ComposerPhase = 'blank' | 'engaging' | 'active'
 
@@ -335,10 +336,70 @@ export interface PromptError {
   error: RpcError
 }
 
+/** Stable per-key reader for final Chat view Nodes. */
+export interface ChatNodeStore {
+  /** @param key - stable Conversation Context key. @returns current Node, when visible or hidden. */
+  get(key: string): ChatConversationViewNode | undefined
+  /** @returns all currently materialized Nodes without imposing render order. */
+  values(): readonly ChatConversationViewNode[]
+}
+
+/** Stable per-Location membership index for turn-local and step-local consumers. */
+export interface ChatLocationNodeIndex {
+  /** @param turn - owning turn. @returns ordered Chat Node keys in the turn. */
+  getTurn(turn: number): readonly string[]
+  /** @param turn - owning turn. @param step - owning step. @returns ordered Chat Node keys in the step. */
+  getStep(turn: number, step: number): readonly string[]
+}
+
+/** Temporary projection consumed by Trajectory and unmigrated readers. */
+export interface LegacyConversationSlice {
+  readonly nodes: readonly ConversationNode[]
+  readonly turnTimings: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
+  readonly turnEnds: ReadonlyMap<number, number>
+  readonly partial: PartialAssistant | null
+  readonly runningCalls: readonly RunningToolCall[]
+}
+
+/** Incremental Chat target snapshot: stable keyed stores plus structural order. */
+export interface ChatSnapshot {
+  readonly order: readonly string[]
+  readonly nodes: ChatNodeStore
+  readonly locations: ChatLocationNodeIndex
+  readonly timeline: ConversationTimelineSnapshot
+  readonly legacy: LegacyConversationSlice
+}
+
+const EMPTY_LIST: readonly never[] = []
+const EMPTY_TIMELINE: ConversationTimelineSnapshot = { turnOrder: EMPTY_LIST, turns: new Map() }
+
+/** Empty Chat target used before a view builder is registered. */
+export const EMPTY_CHAT_SNAPSHOT: ChatSnapshot = {
+  order: EMPTY_LIST,
+  nodes: {
+    get: () => undefined,
+    values: () => EMPTY_LIST,
+  },
+  locations: {
+    getTurn: () => EMPTY_LIST,
+    getStep: () => EMPTY_LIST,
+  },
+  timeline: EMPTY_TIMELINE,
+  legacy: {
+    nodes: EMPTY_LIST,
+    turnTimings: new Map(),
+    turnEnds: new Map(),
+    partial: null,
+    runningCalls: EMPTY_LIST,
+  },
+}
+
 /** The immutable snapshot contract Session hands to uSES (see the web client architecture RFC). */
 export interface ConversationSnapshot {
   sessionId: SessionId
-  /** Human transcript plus retry notices and interrupted-turn terminal nodes in event order. */
+  /** Final Chat target assembled from independently registered business Definitions. */
+  chat: ChatSnapshot
+  /** Legacy Trajectory slice derived from the registered Chat Definitions. */
   nodes: readonly ConversationNode[]
   /** Exact in-window `turn/start` time and optional matching `turn/end` time. */
   turnTimings: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
diff --git a/packages/client/runtime/src/client/sessions/manager.ts b/packages/client/runtime/src/client/sessions/manager.ts
index 64199c4812..b4eec9d6df 100644
--- a/packages/client/runtime/src/client/sessions/manager.ts
+++ b/packages/client/runtime/src/client/sessions/manager.ts
@@ -10,6 +10,7 @@ import type {
 // plugin-to-plugin value imports are a bundle purity error.
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { mergeOrderedBaseline } from '../ordered-baseline.ts'
+import type { ConversationRuntime } from './conversation-assembler.ts'
 import type { SessionListEntry, TitledSessionSummary } from './lineage.ts'
 import { flattenLineage } from './lineage.ts'
 import type { PendingInteractionStatus } from './pending.ts'
@@ -158,6 +159,7 @@ export class SessionManager {
     private readonly api: IApiClient,
     restoredSelection?: SessionId,
     restoredAddress?: SubagentAddress,
+    private readonly conversation?: ConversationRuntime,
   ) {
     this.selected = restoredSelection
     if (restoredAddress !== undefined) this.addresses.set(restoredAddress.childSessionId, restoredAddress)
@@ -282,7 +284,12 @@ export class SessionManager {
         const address = this.addresses.get(sessionId)
         const child = address === undefined ? undefined : this.catalogs.get(address.parentSessionId)?.entries
           .find(entry => entry.kind === 'child' && entry.id === sessionId)
-        if (child?.kind === 'child') session.handleRunning(child.activity === 'running')
+        if (child?.kind === 'child') {
+          // A catalogued child exists only after its delegated session has
+          // durable history, even though child rows do not carry `blank`.
+          session.handleBlank(false)
+          session.handleRunning(child.activity === 'running')
+        }
       }
     }
     return session
@@ -301,9 +308,15 @@ export class SessionManager {
         this.recordMutation({ kind: 'engaged', sessionId: engaged.sessionId })
       },
       projections: this.projectionStore(sessionId),
+      ...this.conversation === undefined ? {} : { conversation: this.conversation },
     })
   }
 
+  /** Rebuild every resident Session after one coalesced registry transaction. */
+  rebuildConversationRegistry(): void {
+    for (const session of this.sessions.values()) session.rebuildConversationRegistry()
+  }
+
   /** Resident per-session projection store (create-on-demand; outlives instantiation). */
   private projectionStore(sessionId: SessionId): ProjectionValueStore {
     let store = this.projectionStores.get(sessionId)
diff --git a/packages/client/runtime/src/client/sessions/partial.ts b/packages/client/runtime/src/client/sessions/partial.ts
index 31a04124cd..599ea61c3d 100644
--- a/packages/client/runtime/src/client/sessions/partial.ts
+++ b/packages/client/runtime/src/client/sessions/partial.ts
@@ -48,7 +48,7 @@ export class PartialAccumulator {
   push(chunk: StreamChunk): boolean {
     switch (chunk.type) {
       case 'block-start': {
-        this.blocks[chunk.index] = emptyBlock(chunk.blockType)
+        this.blocks[chunk.index] = emptyAssistantBlock(chunk.blockType)
         this.changed = true
         return true
       }
@@ -102,7 +102,12 @@ export class PartialAccumulator {
   }
 }
 
-function emptyBlock(blockType: string): AssistantBlock {
+/**
+ * Create the empty client projection for one streamed Assistant block kind.
+ * @param blockType - wire block kind.
+ * @returns empty projected block ready to receive deltas.
+ */
+export function emptyAssistantBlock(blockType: string): AssistantBlock {
   switch (blockType) {
     case 'text': return { kind: 'text', text: '' }
     case 'reasoning': return { kind: 'reasoning', text: '' }
diff --git a/packages/client/runtime/src/client/sessions/queue-mirror.ts b/packages/client/runtime/src/client/sessions/queue-mirror.ts
new file mode 100644
index 0000000000..be7351cf5f
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/queue-mirror.ts
@@ -0,0 +1,74 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { MuxFrame } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type { QueuedMessage } from './conversation.ts'
+
+const QUEUE_PREVIEW_CHARS = 200
+
+function previewOf(content: readonly ContentBlock[]): string {
+  const flat = content
+    .map(block => (block.type === 'text' ? block.text : `[${block.type}]`))
+    .join(' ').replace(/\s+/g, ' ').trim()
+  const chars = Array.from(flat)
+  return chars.length > QUEUE_PREVIEW_CHARS ? `${chars.slice(0, QUEUE_PREVIEW_CHARS).join('')}…` : flat
+}
+
+function textOf(content: readonly ContentBlock[]): string | null {
+  if (!content.every(block => block.type === 'text')) return null
+  return content.map(block => block.text).join('')
+}
+
+type QueueItems = Extract<MuxFrame, { type: 'session/queue' }>['items']
+
+/** Authoritative transient queue projection and durable steering handoff. */
+export class SessionQueueMirror {
+  private current: readonly QueuedMessage[] = []
+
+  /**
+   * Return the current immutable queue projection.
+   * @returns current queue rows.
+   */
+  snapshot(): readonly QueuedMessage[] {
+    return this.current
+  }
+
+  /**
+   * Drop the stale generation before its replacement queue baseline arrives.
+   * @returns whether any projected queue row was removed.
+   */
+  reset(): boolean {
+    if (this.current.length === 0) return false
+    this.current = []
+    return true
+  }
+
+  /**
+   * Replace from one authoritative stream queue frame.
+   * @param items - complete host queue snapshot.
+   */
+  replace(items: QueueItems): void {
+    this.current = items.map(item => ({
+      id: item.id,
+      messageId: item.message.id,
+      placement: item.placement,
+      content: item.message.content,
+      preview: previewOf(item.message.content),
+      text: textOf(item.message.content),
+    }))
+  }
+
+  /**
+   * Retire a transient steering row once its durable message enters the log.
+   * @param event - newly contiguous durable Session event.
+   * @returns whether the projection changed.
+   */
+  acceptDurable(event: SessionEvent): boolean {
+    if (event.type !== 'user/message') return false
+    const messageId = event.data.id
+    const index = this.current.findIndex(item =>
+      item.placement === 'steering' && item.messageId === messageId)
+    if (index < 0) return false
+    this.current = this.current.filter((_item, candidate) => candidate !== index)
+    return true
+  }
+}
diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts
index 64eeaf91d7..dcb5f71610 100644
--- a/packages/client/runtime/src/client/sessions/service.ts
+++ b/packages/client/runtime/src/client/sessions/service.ts
@@ -31,6 +31,7 @@ import { createSnapshotStore } from '../contract/store.ts'
 import type { SessionFace } from '../contract/session.ts'
 import type { AgentContext, ISessions } from '../contract/sessions.ts'
 import { createScope, scopeOf as scopeTagOf } from '../agents/scope.ts'
+import type { ConversationRuntime } from './conversation-assembler.ts'
 import { SessionManager } from './manager.ts'
 import type { SessionListPhase, SessionSearchResultItem, SubagentCatalogSnapshot } from './manager.ts'
 import type { PendingInteractionStatus } from './pending.ts'
@@ -259,16 +260,30 @@ export class SessionsService implements ISessions {
   /**
    * @param ctx - client root context (scope fibers mount under it).
    * @param api - wire client shared with every Session.
+   * @param conversationRuntime - same-pass registry instances, when runtime apply owns them.
    */
   constructor(
     private readonly rootCtx: Context,
     api: IApiClient,
+    conversationRuntime?: ConversationRuntime,
   ) {
     this.selection = createSnapshotStore<SessionSelection>(
       {},
       { persist: { name: 'dsh.sessions.current' } })
     const restored = this.selection.getSnapshot()
-    this.manager = new SessionManager(api, restored.sessionId, restored.subagentAddress)
+    const conversationEvents = rootCtx.get('conversationEvents')
+    const conversationViews = rootCtx.get('conversationViews')
+    const conversation = conversationRuntime ?? (
+      conversationEvents === undefined || conversationViews === undefined
+        ? undefined
+        : { events: conversationEvents, views: conversationViews }
+    )
+    this.manager = new SessionManager(
+      api,
+      restored.sessionId,
+      restored.subagentAddress,
+      conversation,
+    )
     this.list = createSnapshotStore<SessionListState>({
       ids: [], byId: {}, current: undefined, phase: 'pending',
       subagentsByParent: {}, currentAddress: undefined,
@@ -296,6 +311,25 @@ export class SessionsService implements ISessions {
       resolveCurrent: () => this.maybeProvideInfo(this.list.getSnapshot().current),
     })
     this.currentProvideInfo = this.provideChannel.currentProvideInfo
+    let registryRebuildQueued = false
+    const scheduleRegistryRebuild = (): void => {
+      if (registryRebuildQueued) return
+      registryRebuildQueued = true
+      queueMicrotask(() => {
+        registryRebuildQueued = false
+        this.manager.rebuildConversationRegistry()
+      })
+    }
+    if (conversation !== undefined) {
+      rootCtx.effect(() => {
+        const disposeEvents = conversation.events.subscribe(scheduleRegistryRebuild)
+        const disposeViews = conversation.views.subscribe(scheduleRegistryRebuild)
+        return () => {
+          disposeEvents()
+          disposeViews()
+        }
+      }, 'sessions: conversation registry rebuild')
+    }
     rootCtx.reflect.provide('sessions', this, undefined)
   }
 
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 0813c02711..a533f9dd6f 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -2,7 +2,6 @@
 
 import type { Context } from 'cordis'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
-import type { LlmRetryEventData } from '@deepseek-ai/dsh-llm-retry/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type {
   HistoryEntry, IApiClient, MessageId, MuxFrame, QueueAction, RpcError,
@@ -12,27 +11,23 @@ import type {
 // plugin-to-plugin value imports are a bundle purity error.
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { SessionFace } from '../contract/session.ts'
+import { ConversationNodeAssembler } from './conversation-assembler.ts'
+import type { ConversationRuntime } from './conversation-assembler.ts'
+import type { ConversationEventInput, ConversationPublication } from '../contract/conversation.ts'
 import type {
-  ComposerPhase, ConversationNode, ConversationSnapshot, ModelRetryNode,
-  OpenState, PromptError, QueuedMessage, RunningToolCall,
+  ChatSnapshot, ComposerPhase, ConversationSnapshot, OpenState, PromptError,
 } from './conversation.ts'
+import { EMPTY_CHAT_SNAPSHOT } from './conversation.ts'
 import type { PendingInteraction } from './pending.ts'
 import { PendingWait } from './pending.ts'
-import { TranscriptAdapter } from './transcript-adapter.ts'
-import { displayFailureMessage } from './failure-display.ts'
 import { Notifier } from './notifier.ts'
-import { isVisibleAssistantChunk, PartialAccumulator } from './partial.ts'
 import { ProjectionValueStore } from './projection-store.ts'
 import type { ProjectionsBaseline } from './projection-store.ts'
-import { ToolCallTree } from './tool-call-tree.ts'
+import { SessionQueueMirror } from './queue-mirror.ts'
 
 /** Messages requested per history page. */
 export const PAGE_MESSAGES = 50
 
-// Browser bundles cannot value-import the host timeout library. This protocol
-// bound is pinned to @deepseek-ai/dsh-timeout's MAX_TIMER_DELAY_MS in tests.
-const MAX_RETRY_DELAY_MS = 2_147_483_647
-
 /** Manager-owned observers of a Session object's local state edges. */
 export interface SessionOptions {
   /** Catalog-discovered address selecting non-activating subagent transport. */
@@ -54,24 +49,8 @@ export interface SessionOptions {
    * private store (bare object-layer construction).
    */
   projections?: ProjectionValueStore
-}
-
-/** Queue-row preview cap: the dock renders one line, the full content never leaves the host mirror. */
-const QUEUE_PREVIEW_CHARS = 200
-
-/** Single-line queue-row preview: text blocks flattened, non-text as tags, capped by code point. */
-function queuePreviewOf(content: readonly ContentBlock[]): string {
-  const flat = content
-    .map(block => (block.type === 'text' ? block.text : `[${block.type}]`))
-    .join(' ').replace(/\s+/g, ' ').trim()
-  const chars = Array.from(flat)
-  return chars.length > QUEUE_PREVIEW_CHARS ? `${chars.slice(0, QUEUE_PREVIEW_CHARS).join('')}…` : flat
-}
-
-/** Recover complete composer text only when editing cannot discard non-text blocks. */
-function queueTextOf(content: readonly ContentBlock[]): string | null {
-  if (!content.every(block => block.type === 'text')) return null
-  return content.map(block => block.text).join('')
+  /** Runtime registries used by this Session-owned Conversation assembler. */
+  conversation?: ConversationRuntime
 }
 
 /**
@@ -96,42 +75,13 @@ export class Session implements SessionFace {
    *  passes drop all writes once the generation moves on. */
   private openGeneration = 0
   private loadingOlder = false
-  private readonly transcript = new TranscriptAdapter()
-  private partial: PartialAccumulator | null = null
-  private openCalls = new Map<string, RunningToolCall>()
-  /** Last entered step per turn, folded from step/start for terminal error placement. */
-  private lastStepByTurn = new Map<number, number>()
-  /** Operational notices and interrupted-turn terminal nodes merged into the flow by seq.
-   *  Derived from window events and rebuilt with partial/openCalls; the transcript is
-   *  seq-monotonic, so a plain seq merge preserves event order. */
-  private derivedNodes: ConversationNode[] = []
   private pending = new Map<string, PendingInteraction>()
-  // Revision counters preserve array identity when derived content is unchanged, so
-  // React.memo children survive unrelated snapshot swaps (chunk storms must not re-render every
-  // tool card and pending card). Mutation sites bump the matching revision. partial needs no
-  // counter — PartialAccumulator.toPartial already returns a cached reference when unchanged.
-  private callsRev = 0
-  private callsCache: { rev: number; value: RunningToolCall[] } | null = null
   private pendingRev = 0
   private pendingCache: { rev: number; value: PendingInteraction[] } | null = null
-  private derivedRev = 0
-  private nodesCache: { projected: readonly ConversationNode[]; derivedRev: number; value: readonly ConversationNode[] } | null = null
-  /** Exact turn timing retained from the raw window so presentation never
-   *  infers elapsed time from transcript content. */
-  private turnTimings = new Map<number, { startTime: number; endTime?: number }>()
-  private turnTimingsRev = 0
-  private turnTimingsCache: { rev: number; value: ConversationSnapshot['turnTimings'] } | null = null
-  /** Completed turn boundaries retained from the raw window so presentation
-   *  actions never infer a safe fork point from transcript content alone. */
-  private turnEnds = new Map<number, number>()
-  private turnEndsRev = 0
-  private turnEndsCache: { rev: number; value: ReadonlyMap<number, number> } | null = null
   /** Authoritative stream-only inbox snapshot; pending work never hits history. */
-  private queued: QueuedMessage[] = []
-  private queueRev = 0
-  private queueCache: { rev: number; value: QueuedMessage[] } | null = null
-  /** Window-derived child-call lifecycle and immutable tree projection. */
-  private readonly toolCallTree = new ToolCallTree()
+  private readonly queueMirror = new SessionQueueMirror()
+  /** Session-owned business Context engine over the contiguous raw window. */
+  private readonly conversation: ConversationNodeAssembler
   private running = false
   private address: SubagentAddress | undefined
   private parentAvailable = false
@@ -141,8 +91,10 @@ export class Session implements SessionFace {
    * engaging edge of the phase machine (see ComposerPhase).
    */
   private promptAttempted = false
-  /** Empty-log mirror (see ConversationSnapshot.blank); monotone false once flipped. */
-  private blankBit = false
+  /** A first accepted prompt stays in the engaging phase until its turn is observable. */
+  private firstPromptPendingTurn = false
+  /** Empty-log mirror (see ConversationSnapshot.blank); unknown bare sessions begin conservatively blank. */
+  private blankBit = true
   private removed = false
   private promptError: PromptError | null = null
   private lastAgentError: string | null = null
@@ -167,9 +119,7 @@ export class Session implements SessionFace {
   readonly projections: ProjectionValueStore
 
   private snapshotCache: ConversationSnapshot
-  private readonly notifier = new Notifier(() => {
-    this.snapshotCache = this.buildSnapshot()
-  })
+  private readonly notifier: Notifier
   /**
    * Agent-scoped cordis context, bound once by SessionsService when it
    * mints the scope (the client mirror of the host Agent's loopCtx). The
@@ -192,6 +142,16 @@ export class Session implements SessionFace {
     this.projections = options.projections ?? new ProjectionValueStore()
     this.address = options.address
     this.parentAvailable = options.parentAvailable ?? false
+    this.conversation = options.conversation === undefined
+      ? new ConversationNodeAssembler(
+        { entries: () => [], fallbackEntry: () => undefined },
+        { entries: () => [] },
+      )
+      : new ConversationNodeAssembler(options.conversation.events, options.conversation.views)
+    this.notifier = new Notifier(() => {
+      this.conversation.flush()
+      this.snapshotCache = this.buildSnapshot()
+    })
     this.snapshotCache = this.buildSnapshot()
   }
 
@@ -228,6 +188,7 @@ export class Session implements SessionFace {
     // visible on the session area's very first frame when a caller sends
     // ahead of navigation (first-send flow).
     this.promptAttempted = true
+    if (this.blankBit) this.firstPromptPendingTurn = true
     this.notifier.markDirty()
     let result: RpcResult<{ accepted: true }>
     try {
@@ -375,6 +336,7 @@ export class Session implements SessionFace {
       const older = result.value.events
       if (older.length === 0) {
         this.hasMore = result.value.hasMore
+        this.conversation.prepend([], this.hasMore)
         return
       }
       const tail = older[older.length - 1]
@@ -389,8 +351,7 @@ export class Session implements SessionFace {
       /* v8 ignore next -- the ?? arm needs older[0] undefined, but the empty-page branch above already returned. */
       this.baseSeq = older[0]?.event.seq ?? this.baseSeq
       this.hasMore = result.value.hasMore
-      this.transcript.reset(this.events, this.views) // prepend forces a rebuild (the window grew at the head)
-      this.rebuildDerivedFromWindow()
+      this.conversation.prepend(older.map(conversationInput), this.hasMore)
     } catch (error) {
       console.error('[web-runtime] loadOlder failed:', error)
     } finally {
@@ -461,15 +422,7 @@ export class Session implements SessionFace {
         return
       }
       case 'session/queue': {
-        this.queued = frame.items.map(item => ({
-          id: item.id,
-          messageId: item.message.id,
-          placement: item.placement,
-          content: item.message.content,
-          preview: queuePreviewOf(item.message.content),
-          text: queueTextOf(item.message.content),
-        }))
-        this.queueRev++
+        this.queueMirror.replace(frame.items)
         this.notifier.markDirty()
         return
       }
@@ -479,11 +432,7 @@ export class Session implements SessionFace {
         // snapshot AFTER the subscribed frame on the same stream, so the
         // stale mirror clears here — race-free against onConnected/resync
         // timing (clearing there could wipe a baseline that already landed).
-        if (this.queued.length > 0) {
-          this.queued = []
-          this.queueRev++
-          this.notifier.markDirty()
-        }
+        if (this.queueMirror.reset()) this.notifier.markDirty()
         return
       }
       case 'approval/requested': {
@@ -527,6 +476,7 @@ export class Session implements SessionFace {
       this.blankBit = false
       this.notifier.markDirty()
     }
+    if (running) this.firstPromptPendingTurn = false
     if (this.running === running) return
     this.running = running
     this.notifier.markDirty()
@@ -590,6 +540,11 @@ export class Session implements SessionFace {
   /** No-op because session instances remain resident. */
   dispose(): void {}
 
+  /** Rebuild the current window after a low-frequency Definition or view registration change. */
+  rebuildConversationRegistry(): void {
+    this.scheduleConversation(this.conversation.rebuildRegistry())
+  }
+
   // ---- 私有 ----
 
   /** Requested-frame arrival: the wait enters the pending map under its own key. */
@@ -651,8 +606,8 @@ export class Session implements SessionFace {
     this.views = entries.map(e => e.view)
     this.baseSeq = this.events[0]?.seq ?? 0
     this.hasMore = hasMore
-    this.transcript.reset(this.events, this.views)
-    this.rebuildDerivedFromWindow()
+    if (this.events.some(event => event.type === 'turn/start')) this.firstPromptPendingTurn = false
+    this.conversation.replaceWindow(entries.map(conversationInput), hasMore)
     if (projections !== undefined) this.projections.seed(projections)
     const buffered = this.liveBuffer
     this.liveBuffer = []
@@ -661,32 +616,22 @@ export class Session implements SessionFace {
   }
 
   /** Seq-guarded append shared by stitching and the open-state live path. */
-  private appendLive(event: SessionEvent, view?: ToolEventView): void {
+  private appendLive(event: SessionEvent, view?: ToolEventView): ConversationPublication {
     const tailSeq = this.windowTailSeq()
-    if (tailSeq !== null && event.seq <= tailSeq) return // replay overlap, drop
+    if (tailSeq !== null && event.seq <= tailSeq) return 'none' // replay overlap, drop
     this.events.push(event)
     this.views.push(view)
-    this.transcript.append(event, view)
-    this.handoffPendingSteering(event)
-    this.applyEventSideEffects(event, view)
-  }
-
-  /** Retire the first matching live steering occurrence when its durable message takes over. */
-  private handoffPendingSteering(event: SessionEvent): void {
-    if (event.type !== 'user/message') return
-    const message = event.data
-    const index = this.queued.findIndex(item =>
-      item.placement === 'steering' && item.messageId === message.id)
-    if (index === -1) return
-    this.queued = this.queued.filter((_item, candidate) => candidate !== index)
-    this.queueRev++
+    if (event.type === 'turn/start') this.firstPromptPendingTurn = false
+    const queueChanged = this.queueMirror.acceptDurable(event)
+    const publication = this.conversation.append({ event, view })
+    return queueChanged ? 'immediate' : publication
   }
 
   /** Land a live session/event (open/repair in flight -> buffer; overlapping seq -> drop;
    *  a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an
    *  expected reconnect-window artifact, repaired by refetch). The window stays one contiguous
-   *  raw range, which is what lets the transcript render every event between its ends and lets a
-   *  compaction checkpoint find its cited summary event. */
+   *  raw range, which lets Conversation Definitions correlate every recorded event between its
+   *  ends and lets a compaction checkpoint resolve its cited summary event. */
   private acceptLiveEvent(event: SessionEvent, view?: ToolEventView): void {
     if (this.openState === 'loading' || this.stitching) {
       this.liveBuffer.push({ event, view })
@@ -699,12 +644,13 @@ export class Session implements SessionFace {
       void this.repairGap()
       return
     }
-    this.appendLive(event, view)
-    if (event.type === 'assistant/chunk') {
-      if (isVisibleAssistantChunk(event.data.chunk.type)) this.notifier.markFrameDirty()
-      return
-    }
-    this.notifier.markDirty()
+    this.scheduleConversation(this.appendLive(event, view))
+  }
+
+  /** Route assembler cadence into the Session's existing microtask/RAF notifier. */
+  private scheduleConversation(publication: ConversationPublication): void {
+    if (publication === 'immediate') this.notifier.markDirty()
+    else if (publication === 'animation-frame') this.notifier.markFrameDirty()
   }
 
   /** Resync-lite (audit S3): repull the tail page and stitch the liveBuffer through the shared
@@ -728,238 +674,35 @@ export class Session implements SessionFace {
     }
   }
 
-  /** Per-event side effects (right column of the §A.9 dispatch table):
-   *  chunk/retry projection and openCalls add-remove. */
-  private applyEventSideEffects(event: SessionEvent, view?: ToolEventView): void {
-    const eventType = event.type as string
-    if (eventType === 'llm/retry') {
-      const data = parseRetryEventData(event.data)
-      if (data === null) {
-        console.error(`[web-runtime] ignored malformed llm/retry event at seq ${event.seq}`)
-        return
-      }
-      if (this.partial !== null && this.partial.turn === data.turn && this.partial.step === data.step) {
-        this.partial = null
-      }
-      this.derivedNodes.push({
-        kind: 'model-retry',
-        seq: event.seq,
-        time: event.time,
-        retryState: 'scheduled',
-        ...data,
-      })
-      this.derivedRev++
-      return
-    }
-    // These lifecycle events are declared by a host-only plugin whose Context
-    // types cannot enter the client program. ToolCallTree owns their structural
-    // wire narrowing, pairing, and nested snapshot projection.
-    if (this.toolCallTree.apply(event)) return
-    switch (event.type) {
-      case 'turn/start':
-        this.lastStepByTurn.set(event.data.turn, 0)
-        this.turnTimings.set(event.data.turn, { startTime: event.time })
-        this.turnTimingsRev++
-        return
-      case 'step/start':
-        this.lastStepByTurn.set(event.data.turn, event.data.step)
-        return
-      case 'assistant/chunk': {
-        const { turn, step, chunk } = event.data
-        this.settleScheduledRetry('started', turn)
-        if (this.partial === null || this.partial.turn !== turn || this.partial.step !== step) {
-          this.partial = new PartialAccumulator(turn, step)
-        }
-        this.partial.push(chunk)
-        return
-      }
-      case 'assistant/message': {
-        if (this.partial !== null && this.partial.turn === event.data.turn && this.partial.step === event.data.step) {
-          this.partial = null // finalize swaps in place (same notification batch, no flicker)
-        }
-        return
-      }
-      case 'tool/call': {
-        this.openCalls.set(String(event.data.callId), {
-          callId: String(event.data.callId), name: event.data.name, argsRaw: event.data.arguments,
-          turn: event.data.turn, step: event.data.step, time: event.time,
-          callView: view?.for === 'call' ? view.view : null,
-          subCalls: [],
-        })
-        this.callsRev++
-        return
-      }
-      case 'tool/result': {
-        if (this.openCalls.delete(String(event.data.message.source.callId))) this.callsRev++
-        return
-      }
-      case 'turn/end': {
-        const lastStep = this.lastStepByTurn.get(event.data.turn) ?? 0
-        const timing = this.turnTimings.get(event.data.turn)
-        if (timing !== undefined) {
-          this.turnTimings.set(event.data.turn, { ...timing, endTime: event.time })
-          this.turnTimingsRev++
-        }
-        this.turnEnds.set(event.data.turn, event.seq)
-        this.turnEndsRev++
-        if (event.data.reason.kind === 'aborted') {
-          this.settleScheduledRetry('cancelled', event.data.turn)
-        }
-        if (
-          event.data.reason.kind === 'error'
-          && !this.derivedNodes.some(node => node.kind === 'model-retry' && node.turn === event.data.turn)
-        ) {
-          const failure = event.data.reason.error
-          this.derivedNodes.push({
-            kind: 'turn-error',
-            seq: event.seq,
-            time: event.time,
-            turn: event.data.turn,
-            step: lastStep,
-            message: displayFailureMessage(failure),
-            code: failure.code,
-          })
-          this.derivedRev++
-        }
-        if (event.data.reason.kind === 'error') this.settleScheduledRetry('started', event.data.turn)
-        // Aborted turns never finalize. The accumulated partial is VALUE, not residue: freeze it
-        // into an interrupted terminal node (pulse stops, text survives) instead of deleting it.
-        // Shared by live and window-replay paths, so a refresh reconstructs the same frozen node
-        // from the logged chunks. Content-free partials are dropped outright.
-        if (this.partial !== null && this.partial.turn === event.data.turn) {
-          const { blocks } = this.partial.toPartial()
-          const visible = blocks.some(b => (b.kind === 'text' || b.kind === 'reasoning' ? b.text !== '' : true))
-          if (visible) {
-            // Fractional seq: strictly after every event of this turn (all < turn/end seq), before the next turn.
-            this.derivedNodes.push({
-              kind: 'assistant', seq: event.seq - 0.9, time: event.time,
-              turn: this.partial.turn, step: this.partial.step,
-              blocks, interrupted: true,
-            })
-            this.derivedRev++
-          }
-          this.partial = null
-        }
-        let callOffset = 0
-        for (const [callId, call] of this.openCalls) {
-          if (call.turn !== event.data.turn) continue
-          this.openCalls.delete(callId)
-          this.callsRev++
-          // The spinner card becomes an interrupted terminal card (never vanishes mid-flow).
-          this.derivedNodes.push({
-            kind: 'tool-result', seq: event.seq - 0.8 + callOffset++ * 0.01, time: event.time,
-            callId,
-            call: { name: call.name, argsRaw: call.argsRaw },
-            callTime: call.time,
-            content: [], isError: true, error: { name: 'Interrupted', code: 'interrupted' },
-            callView: call.callView, resultView: null, subCalls: [],
-          })
-          this.derivedRev++
-        }
-        this.lastStepByTurn.delete(event.data.turn)
-        return
-      }
-      default:
-        return
-    }
-  }
-
-  /**
-   * Settle the newest scheduled retry, optionally restricted to its failed turn.
-   * @param retryState - next client projection state to publish.
-   * @param turn - failed turn required for cancellation; omitted for the next retry turn start.
-   */
-  private settleScheduledRetry(
-    retryState: Exclude<ModelRetryNode['retryState'], 'scheduled'>,
-    turn?: number,
-  ): void {
-    const index = this.derivedNodes.findLastIndex(node =>
-      node.kind === 'model-retry'
-      && node.retryState === 'scheduled'
-      && (turn === undefined || node.turn === turn))
-    if (index < 0) return
-    const node = this.derivedNodes[index]
-    /* v8 ignore next -- findLastIndex's predicate narrows the indexed node only at runtime. */
-    if (node?.kind !== 'model-retry') return
-    this.derivedNodes[index] = { ...node, retryState }
-    this.derivedRev++
-  }
-
-  /** Re-derive state (partial/openCalls/derivedNodes) from raw window events after a rebuild — keeps
-   *  paging/stitching consistent, and makes live handling and history replay converge on the same
-   *  retry notices and interrupted nodes. */
-  private rebuildDerivedFromWindow(): void {
-    this.partial = null
-    this.openCalls.clear()
-    this.lastStepByTurn.clear()
-    this.callsRev++
-    this.derivedNodes = []
-    this.derivedRev++
-    this.turnTimings = new Map()
-    this.turnTimingsRev++
-    this.turnEnds = new Map()
-    this.turnEndsRev++
-    this.toolCallTree.reset()
-    for (let i = 0; i < this.events.length; i++) {
-      const event = this.events[i]
-      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
-      if (event !== undefined) this.applyEventSideEffects(event, this.views[i])
-    }
-  }
-
   private windowTailSeq(): number | null {
     const tail = this.events[this.events.length - 1]
     return tail === undefined ? null : tail.seq
   }
 
   private buildSnapshot(): ConversationSnapshot {
-    const projected = this.transcript.nodes()
-    // Derived interruption nodes ride fractional seqs while retry notices keep their event seq.
-    // The transcript is seq-monotonic, so sorting the union preserves flow order. Cache the
-    // merge on (projected reference, derivedRev) to retain identity across unrelated swaps.
-    let nodes: readonly ConversationNode[]
-    if (this.nodesCache !== null && this.nodesCache.projected === projected && this.nodesCache.derivedRev === this.derivedRev) {
-      nodes = this.nodesCache.value
-    } else {
-      nodes = this.derivedNodes.length === 0
-        ? projected
-        : [...projected, ...this.derivedNodes].sort((a, b) => a.seq - b.seq)
-      this.nodesCache = { projected, derivedRev: this.derivedRev, value: nodes }
-    }
-    if (this.callsCache === null || this.callsCache.rev !== this.callsRev) {
-      this.callsCache = { rev: this.callsRev, value: [...this.openCalls.values()] }
-    }
-    if (this.turnTimingsCache === null || this.turnTimingsCache.rev !== this.turnTimingsRev) {
-      this.turnTimingsCache = { rev: this.turnTimingsRev, value: new Map(this.turnTimings) }
-    }
-    if (this.turnEndsCache === null || this.turnEndsCache.rev !== this.turnEndsRev) {
-      this.turnEndsCache = { rev: this.turnEndsRev, value: new Map(this.turnEnds) }
-    }
     if (this.pendingCache === null || this.pendingCache.rev !== this.pendingRev) {
       this.pendingCache = { rev: this.pendingRev, value: [...this.pending.values()] }
     }
-    if (this.queueCache === null || this.queueCache.rev !== this.queueRev) {
-      this.queueCache = { rev: this.queueRev, value: this.queued }
-    }
-    const partial = this.partial?.toPartial() ?? null
+    const chat = (this.conversation.snapshot('chat') as ChatSnapshot | undefined) ?? EMPTY_CHAT_SNAPSHOT
+    const legacy = chat.legacy
     return {
       sessionId: this.sessionId,
-      nodes: this.toolCallTree.projectNodes(nodes),
-      turnTimings: this.turnTimingsCache.value,
-      turnEnds: this.turnEndsCache.value,
-      partial,
-      runningCalls: this.toolCallTree.projectRunningCalls(this.callsCache.value),
+      chat,
+      nodes: legacy.nodes,
+      turnTimings: legacy.turnTimings,
+      turnEnds: legacy.turnEnds,
+      partial: legacy.partial,
+      runningCalls: legacy.runningCalls,
       pending: this.pendingCache.value,
-      queue: this.queueCache.value,
+      queue: this.queueMirror.snapshot(),
       running: this.running,
       subagent: this.address === undefined
         ? null
         : { address: this.address, parentAvailable: this.parentAvailable },
       composerPhase: derivePhase(
-        // Command lifecycle nodes are not conversation: running /permission
-        // or /plan on a fresh session keeps the hero (the client mirror of
-        // the host's no-turn sessionBlank predicate).
-        nodes.some(node => node.kind !== 'command') || partial !== null || this.running || this.pendingCache.value.length > 0,
+        (!this.blankBit && !this.firstPromptPendingTurn)
+          || this.running
+          || this.pendingCache.value.length > 0,
         this.promptAttempted,
       ),
       removed: this.removed,
@@ -985,67 +728,18 @@ export class Session implements SessionFace {
   }
 }
 
-/** Validate the plugin-owned payload at the session-event wire boundary. */
-function parseRetryEventData(value: unknown): LlmRetryEventData | null {
-  if (value === null || typeof value !== 'object') return null
-  const data = value as Record<string, unknown>
-  const failure = data.failure
-  if (failure === null || typeof failure !== 'object') return null
-  const failureData = failure as Record<string, unknown>
-  if (!nonNegativeSafeInteger(data.turn)
-    || !nonNegativeSafeInteger(data.step)
-    || typeof data.provider !== 'string'
-    || data.provider.length === 0
-    || typeof data.policyKey !== 'string'
-    || data.policyKey.length === 0
-    || !positiveSafeInteger(data.retry)
-    || typeof data.delayMs !== 'number'
-    || !Number.isFinite(data.delayMs)
-    || data.delayMs < 0
-    || data.delayMs > MAX_RETRY_DELAY_MS
-    || typeof failureData.message !== 'string'
-    || failureData.message.length === 0
-    || typeof failureData.code !== 'string'
-    || failureData.code.length === 0) return null
-  if (data.mode === 'normal') {
-    if (!positiveSafeInteger(data.maxRetries) || data.retry > data.maxRetries) return null
-  } else if (data.mode === 'always') {
-    if ('maxRetries' in data) return null
-  } else {
-    return null
-  }
-  if (failureData.status !== undefined
-    && (typeof failureData.status !== 'number'
-      || !Number.isInteger(failureData.status)
-      || failureData.status < 100
-      || failureData.status > 599)) return null
-  if (failureData.providerRetryAfterMs !== undefined
-    && (typeof failureData.providerRetryAfterMs !== 'number'
-      || !Number.isFinite(failureData.providerRetryAfterMs)
-      || failureData.providerRetryAfterMs <= 0)) return null
-  if (failureData.requestId !== undefined
-    && (typeof failureData.requestId !== 'string'
-      || failureData.requestId.length === 0)) return null
-  return data as unknown as LlmRetryEventData
-}
-
-function nonNegativeSafeInteger(value: unknown): value is number {
-  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
-}
-
-function positiveSafeInteger(value: unknown): value is number {
-  return nonNegativeSafeInteger(value) && value > 0
+/** Convert one wire history row into the assembler's transport-neutral input. */
+function conversationInput(entry: HistoryEntry): ConversationEventInput {
+  return { event: entry.event, view: entry.view }
 }
 
 /**
  * The composerPhase judgment — the single site that knows the predicate
- * (consumers switch on the result, never re-derive). Monotone per session
- * object: `hasContent` only grows within a window and `promptAttempted` is
- * sticky, so blank → engaging → active never steps back; a failed first
- * prompt stays engaging (retry semantics — see ComposerPhase).
- * @param hasContent - any conversation material exists (non-command nodes,
- *   partial, running turn, pending waits; command lifecycle rows alone keep
- *   the session blank).
+ * (consumers switch on the result, never re-derive). A failed first prompt
+ * stays engaging until an authoritative accepted-turn, running, or pending
+ * signal arrives (retry semantics — see ComposerPhase).
+ * @param hasContent - authoritative non-blank activity beyond a pending first
+ *   prompt, a running turn, or a pending interaction.
  * @param promptAttempted - a prompt was initiated on this session object.
  * @returns the derived phase.
  */
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
deleted file mode 100644
index 78090ce87f..0000000000
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ /dev/null
@@ -1,409 +0,0 @@
-// TranscriptAdapter: the human transcript projected from the raw event window
-// in LOG order. The model-visible surface deliberately shadows replaced ranges,
-// so it is the wrong source for conversation a reader already saw; this adapter
-// keeps every append-origin event at its own log position and contributes one
-// marker node per landed compaction checkpoint. Node order is therefore
-// seq-monotonic by construction — no surface fold, no padding sentinels, no
-// seq === index assertion to satisfy, and no degradation branch.
-
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-// Subpath export (package.json exports "./surface", alias added for this): all value imports
-// go through it — the package root points at lib/index.js (needs a build) which the vite
-// browser bundle cannot resolve; surface.ts has no Node dependencies.
-import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
-import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-// Cordis-free leaf subpath (the dsh-commands/brand shape): the Service Definition's
-// declaration of the checkpoint source, reachable as a TYPE from this program.
-// The package ROOT is not — it reaches dsh-session's root, whose Context merge
-// declares the HOST `sessions: SessionStore` against this program's
-// `sessions: ISessions` (TS2717, the one-program-per-side rule in
-// docs/development.md).
-import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
-import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
-import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
-import { toAssistantBlocks } from './conversation.ts'
-import { contextForm, contextProvenance } from './context-provenance.ts'
-import { SteeringHistory } from './steering-history.ts'
-import type { AssistantStepMetadata } from './assistant-timing.ts'
-import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts'
-
-/**
- * The compaction capability's checkpoint plugin, pinned to the Service Definition's declaration
- * at COMPILE time: renaming it there fails this annotation (`TS2322`). The
- * import stays type-only because a value import would fail the client purity
- * gate (`packages/client/tsdown.client.ts`) — cross-plugin value imports are
- * forbidden in a browser bundle — while an erased type never reaches it.
- */
-const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
-
-/** In-window tool/call index entry used to materialize result cards. */
-interface CallIndexEntry {
-  name: string
-  argsRaw: string
-  turn: number
-  step: number
-  /** Unix epoch ms of the tool/call event. */
-  time: number
-  /** Wire view riding the tool/call (envelope-level; never inside the event). */
-  callView: ToolCallView | null
-}
-
-/** One event -> UI node (pure function; the ten-variant ConversationNode union). */
-function materializeNode(
-  event: SessionEvent,
-  callIndex: ReadonlyMap<string, CallIndexEntry>,
-  resultView: ToolResultView | null,
-  steering: boolean,
-  stepTimings: ReadonlyMap<string, AssistantStepMetadata>,
-): ConversationNode {
-  switch (event.type) {
-    case 'user/message': {
-      // Injected context (plugin/goal/skill-invocation source) folds to a
-      // context node, not a user message; only a direct human prompt is a
-      // user node. A compaction checkpoint never reaches here
-      // (isCompactCheckpoint routes it away).
-      if (event.data.source.kind !== 'user') {
-        return {
-          kind: 'context', seq: event.seq, time: event.time,
-          content: event.data.content, source: event.data.source,
-          provenance: contextProvenance(event.data.source),
-          form: contextForm(event.data.source),
-        }
-      }
-      if (steering) {
-        return {
-          kind: 'steering', messageId: event.data.id,
-          seq: event.seq, time: event.time,
-          content: event.data.content, source: event.data.source,
-        }
-      }
-      return {
-        kind: 'user', seq: event.seq, time: event.time,
-        content: event.data.content, source: event.data.source,
-      }
-    }
-    case 'assistant/message':
-      return {
-        kind: 'assistant', seq: event.seq, time: event.time,
-        turn: event.data.turn, step: event.data.step,
-        blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage,
-        timing: settledAssistantTiming(stepTimings, event.data.turn, event.data.step, event.time),
-      }
-    case 'tool/result': {
-      const result = event.data.message.content[0]
-      const callId = String(event.data.message.source.callId)
-      const call = callIndex.get(callId)
-      return {
-        kind: 'tool-result', seq: event.seq, time: event.time,
-        callId,
-        call: call ? { name: call.name, argsRaw: call.argsRaw } : null,
-        callTime: call?.time ?? null,
-        content: result.content, isError: result.isError === true,
-        ...(event.data.error !== undefined ? { error: event.data.error } : {}),
-        meta: event.data.meta,
-        callView: call?.callView ?? null,
-        resultView,
-        subCalls: [],
-      }
-    }
-    /* v8 ignore next 2 -- defensive arm: only the four surface-eligible types
-    can be append-origin, and each has a case above; reachable only if core
-    adds an eligible type. */
-    default:
-      return {
-        kind: 'unknown', seq: event.seq, time: event.time,
-        type: event.type, data: (event as { data?: unknown }).data,
-      }
-  }
-}
-
-/**
- * Whether an event is a landed compaction checkpoint — all three conditions,
- * matching the terminal's `isCompactCheckpoint`: a `user/message`, carrying the
- * compaction seam's checkpoint plugin source, that REPLACED a surface range. A
- * plugin-sourced `user/message` that appends is injected context (a
- * session-reference card), not a compaction; a replacement `tool/result` is an
- * in-place prune and a replacement `assistant/message` a generic rewrite, and
- * both mark no boundary in the conversation.
- * @param event - the raw window event.
- * @returns true when the event compacted a surface range.
- */
-function isCompactCheckpoint(event: SessionEvent): boolean {
-  if (event.type !== 'user/message') return false
-  const source = event.data.source
-  return source.kind === 'plugin' && source.plugin === COMPACT_PLUGIN
-    && isReplacementSurfaceEvent(event)
-}
-
-/** Whether an event contributes a node to the human transcript. */
-function isTranscriptEvent(event: SessionEvent): boolean {
-  return isAppendSurfaceEvent(event) || isCompactCheckpoint(event)
-}
-
-/**
- * Concatenated text of a `compact/summary` payload, or null when it carries no
- * usable text. The payload is a `ContentBlock[]` whose union is
- * merge-extensible, so a non-text block is skipped rather than discarding the
- * text beside it; a payload with no text block at all falls to null through the
- * empty check.
- */
-function compactSummaryText(event: SessionEvent): string | null {
-  const summary = (event.data as unknown as { summary?: unknown }).summary
-  if (!Array.isArray(summary)) return null
-  let text = ''
-  for (const block of summary as readonly unknown[]) {
-    const candidate = block as { type?: unknown; text?: unknown }
-    if (candidate.type !== 'text' || typeof candidate.text !== 'string') continue
-    text += candidate.text
-  }
-  return text.trim() === '' ? null : text
-}
-
-interface CompactSummaryDetails {
-  readonly summary: string | null
-  readonly shadowedItemCount: number | null
-  readonly shadowedTokenCount: number | null
-}
-
-/** Recover human-facing summary material from one structurally narrowed wire event. */
-function compactSummaryDetails(event: SessionEvent): CompactSummaryDetails {
-  const data = event.data as unknown as { shadowedSeqs?: unknown; shadowedTokenCount?: unknown }
-  const shadowedSeqs = data.shadowedSeqs
-  const tokenCount = data.shadowedTokenCount
-  return {
-    summary: compactSummaryText(event),
-    shadowedItemCount: Array.isArray(shadowedSeqs)
-      && shadowedSeqs.every((seq: unknown) => Number.isSafeInteger(seq) && (seq as number) >= 0)
-      ? shadowedSeqs.length
-      : null,
-    shadowedTokenCount: Number.isSafeInteger(tokenCount) && (tokenCount as number) >= 0
-      ? tokenCount as number
-      : null,
-  }
-}
-
-/**
- * One landed checkpoint -> the human-facing compaction marker. The summary text
- * comes from the checkpoint's cited `compact/summary` event (`sourceEventSeqs` names the
- * `compact/summary` event), never from the framed checkpoint payload, which is
- * an instruction envelope written for the model. A window cut that left the
- * summary event outside soft-falls to `summary: null` (a non-expandable marker),
- * the same posture as a call-less tool result.
- */
-function materializeCompaction(
-  checkpoint: SessionEvent,
-  eventIndex: ReadonlyMap<number, SessionEvent>,
-): CompactionSummaryNode {
-  const sources = (checkpoint as SessionEvent & { sourceEventSeqs?: number[] }).sourceEventSeqs
-  let summary: string | null = null
-  let summaryEventSeq: number | null = null
-  let shadowedItemCount: number | null = null
-  let shadowedTokenCount: number | null = null
-  for (const seq of sources ?? []) {
-    const candidate = eventIndex.get(seq)
-    if (candidate === undefined || (candidate.type as string) !== 'compact/summary') continue
-    const details = compactSummaryDetails(candidate)
-    summary = details.summary
-    summaryEventSeq = candidate.seq
-    shadowedItemCount = details.shadowedItemCount
-    shadowedTokenCount = details.shadowedTokenCount
-    break
-  }
-  return {
-    kind: 'compaction',
-    seq: checkpoint.seq,
-    time: checkpoint.time,
-    summary,
-    summaryEventSeq,
-    shadowedItemCount,
-    shadowedTokenCount,
-  }
-}
-
-/** Log-ordered human transcript over a paged raw event window (never consults surface order). */
-export class TranscriptAdapter {
-  /** Window events by seq, used to find the summary event cited by a checkpoint. */
-  private eventIndex = new Map<number, SessionEvent>()
-  /** Transcript nodes in log order; copy-on-write so a published array never mutates. */
-  private projected: ConversationNode[] = []
-  private callIdx = new Map<string, CallIndexEntry>()
-  /** Per-step timing boundaries (step/start + first token delta), consumed when the step's assistant/message materializes. */
-  private stepTimings = new Map<string, AssistantStepMetadata>()
-  /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */
-  private resultViews = new Map<number, ToolResultView>()
-  /** Durable inbox replay used to distinguish next-step human input from queued prompts. */
-  private readonly steeringHistory = new SteeringHistory()
-  /**
-   * Command lifecycle nodes by commandId (insertion = run order). The
-   * `command/run`/`command/done` pair is log-only, so it is not a surface
-   * event and never joins the transcript projection; this index folds the pair
-   * (done settles its run's node in place) and nodes() merges the products in
-   * by seq. Window cuts soft-fall like tool pairs: a done with no in-window
-   * run still builds a node.
-   */
-  private commandIdx = new Map<string, CommandNode>()
-  /** Projection revision, bumped only when a transcript node or a command node actually
-   *  changed, keying the nodes() result cache: an unchanged projection returns the previous
-   *  ARRAY reference, not just cached elements — the snapshot's reference-stability contract
-   *  (§A.9.4) starts here, and a chunk storm bumps nothing at all. */
-  private rev = 0
-  private nodesResult: { rev: number; value: readonly ConversationNode[] } | null = null
-
-  /**
-   * Window rebuild (after open/resync/page prepend): re-index the raw window
-   * and re-project the transcript.
-   * @param events - the new window contents (seq-ascending).
-   * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
-   */
-  reset(events: readonly SessionEvent[], views?: readonly (ToolEventView | undefined)[]): void {
-    this.rev++
-    this.eventIndex = new Map()
-    this.callIdx = new Map()
-    this.resultViews.clear()
-    this.commandIdx = new Map()
-    this.steeringHistory.reset()
-    const steeringSeqs = new Set<number>()
-    this.stepTimings = new Map()
-    for (let i = 0; i < events.length; i++) {
-      const event = events[i]
-      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
-      if (event === undefined) continue
-      this.eventIndex.set(event.seq, event)
-      this.indexCall(event, views?.[i])
-      this.indexCommand(event)
-      if (this.steeringHistory.apply(event)) steeringSeqs.add(event.seq)
-      indexAssistantStepTiming(this.stepTimings, event)
-    }
-    // Indexes first, then project: a tool/result materializes against the
-    // complete call index, and a checkpoint against the complete event index.
-    const projected: ConversationNode[] = []
-    for (const event of events) {
-      if (isTranscriptEvent(event)) projected.push(this.materialize(event, steeringSeqs.has(event.seq)))
-    }
-    this.projected = projected
-  }
-
-  /**
-   * Tail append (live session/event): index the event and, when it belongs to
-   * the transcript, extend the projection by one copy-on-write node so a
-   * published array never mutates. An event that changes no node (a chunk
-   * storm) bumps no revision, so nodes() keeps returning the same array
-   * reference.
-   * @param event - the live event (seq = window tail + 1).
-   * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering.
-   */
-  append(event: SessionEvent, view?: ToolEventView): void {
-    this.eventIndex.set(event.seq, event)
-    this.indexCall(event, view)
-    const steering = this.steeringHistory.apply(event)
-    indexAssistantStepTiming(this.stepTimings, event)
-    if (this.indexCommand(event)) this.rev++
-    if (!isTranscriptEvent(event)) return
-    this.projected = [...this.projected, this.materialize(event, steering)]
-    this.rev++
-  }
-
-  /**
-   * The current transcript node array. Same revision -> same array reference
-   * (memo boundary); node objects are materialized once, so an unchanged node
-   * keeps its identity across appends.
-   * @returns transcript nodes in log order, command nodes merged in by seq.
-   */
-  nodes(): readonly ConversationNode[] {
-    if (this.nodesResult !== null && this.nodesResult.rev === this.rev) return this.nodesResult.value
-    // Command nodes fold outside the transcript (log-only events); merge by
-    // seq. Both inputs are seq-ascending (log order and run-index insertion
-    // order are the same order), so one linear merge keeps flow order.
-    let nodes = this.projected
-    if (this.commandIdx.size > 0) {
-      nodes = []
-      const commands = [...this.commandIdx.values()]
-      let next = 0
-      for (const node of this.projected) {
-        for (let cmd = commands[next]; cmd !== undefined && cmd.seq < node.seq; cmd = commands[++next]) {
-          nodes.push(cmd)
-        }
-        nodes.push(node)
-      }
-      for (let cmd = commands[next]; cmd !== undefined; cmd = commands[++next]) nodes.push(cmd)
-    }
-    this.nodesResult = { rev: this.rev, value: nodes }
-    return nodes
-  }
-
-  /** Materialize one transcript event against the complete current indexes. */
-  private materialize(event: SessionEvent, steering: boolean): ConversationNode {
-    return isCompactCheckpoint(event)
-      ? materializeCompaction(event, this.eventIndex)
-      : materializeNode(
-        event,
-        this.callIdx,
-        this.resultViews.get(event.seq) ?? null,
-        steering,
-        this.stepTimings,
-      )
-  }
-
-  /**
-   * Fold one command lifecycle event into its node (run mints, done settles in
-   * place; done-only soft-falls).
-   * @returns whether the command index changed, so callers can bump the revision.
-   */
-  private indexCommand(event: SessionEvent): boolean {
-    // Log-only plugin events: the host-side dsh-commands declaration cannot
-    // enter the client program, so this wire consumer narrows structurally
-    // (the same posture as tool/code-dispatch in session.ts).
-    if ((event.type as string) === 'command/run') {
-      const data = event.data as unknown as { commandId: CommandId; name: string; args?: string }
-      this.commandIdx.set(data.commandId, {
-        kind: 'command', seq: event.seq, time: event.time,
-        commandId: data.commandId, name: data.name, args: data.args ?? null, outcome: null,
-      })
-      return true
-    }
-    if ((event.type as string) !== 'command/done') return false
-    const data = event.data as unknown as {
-      commandId: CommandId
-      kind: 'success' | 'error'
-      text?: string
-      sourceEventSeq?: number
-    }
-    const run = this.commandIdx.get(data.commandId)
-    const sourceEventSeq = data.kind === 'success'
-      && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
-      ? data.sourceEventSeq as number
-      : undefined
-    const outcome = {
-      kind: data.kind,
-      ...data.text === undefined ? {} : { text: data.text },
-      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
-    }
-    if (run === undefined) {
-      // Cross-window cut: the run page fell out of the window — build the
-      // node from the done alone (same soft-fall as a call-less tool result).
-      this.commandIdx.set(data.commandId, {
-        kind: 'command', seq: event.seq, time: event.time,
-        commandId: data.commandId, name: null, args: null, outcome,
-      })
-      return true
-    }
-    // Settle in place: a fresh node object (published references stay immutable).
-    this.commandIdx.set(data.commandId, { ...run, outcome })
-    return true
-  }
-
-  private indexCall(event: SessionEvent, view?: ToolEventView): void {
-    if (event.type === 'tool/result') {
-      if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
-      return
-    }
-    if (event.type !== 'tool/call') return
-    this.callIdx.set(String(event.data.callId), {
-      name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step,
-      time: event.time,
-      callView: view?.for === 'call' ? view.view : null,
-    })
-    // No backfill into already-materialized tool-result nodes for this callId
-    // (window order puts the call before its result; cannot happen on the normal path).
-  }
-}
diff --git a/packages/client/runtime/src/client/slots.ts b/packages/client/runtime/src/client/slots.ts
index a30adb4dd6..e3ad848e05 100644
--- a/packages/client/runtime/src/client/slots.ts
+++ b/packages/client/runtime/src/client/slots.ts
@@ -320,7 +320,7 @@ export class SlotsService extends Service {
     const dispose = (this._core as unknown as ErasedCore).register(erased, component)
     if (store !== undefined) {
       // Register succeeded, so the target's spec is on the ledger.
-      const scope = (this._core.specDynamic(options.name) as SlotSpec<never>).scope
+      const scope = (this._core.specDynamic(options.name) as SlotSpec<SlotEntryDef>).scope
       this._acquire(store, scope)
     }
     let disposed = false
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index 7d7d9a6c34..4ed6ecf519 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -101,15 +101,40 @@ export interface SlotEntryDef {
   kind: SlotKind
   scope: SlotScope
   owner?: object
+  /**
+   * Optional keyed-entry prop table. A keyed registration contributes one
+   * literal key and receives the corresponding prop share; ordinary owner
+   * props remain common to every key.
+   */
+  keyProps?: Record<string, object>
+  /**
+   * Optional opaque context carried by one renderSlot occurrence. Only
+   * function-valued members of the slot-level injected hooks compartment
+   * receive it; the slot machinery never interprets the value.
+   */
+  hookContext?: unknown
+  /**
+   * Optional Slot-level inject face supplied by the parent registration's
+   * child declaration. Every registered entry receives its bound component
+   * face; child registrants do not own or replace this common capability.
+   */
+  inject?: object
 }
 
 /**
  * Runtime dispatch spec for one slot, recorded from a register call's
  * `children` value. The literal is compile-time checked against the SlotMap
- * entry (`SlotSpec<SlotMap[P]>` in {@link ChildrenDecl}), so type and value
- * are declared at one point and validate each other.
+ * entry (`SlotSpec<SlotMap[P]>` in {@link ChildrenDecl}), so kind, scope, and
+ * any common inject face are declared at one point and validate each other.
  */
-export interface SlotSpec<E extends SlotEntryDef> { kind: E['kind']; scope: E['scope'] }
+export type SlotSpec<E extends SlotEntryDef> = {
+  kind: E['kind']
+  scope: E['scope']
+} & ('inject' extends keyof E
+  ? E extends { inject: infer Injected extends object }
+    ? { inject: Injected }
+    : { inject?: object }
+  : { inject?: never })
 
 /**
  * Child-slot declaration table for register(): keys are the declared (and
@@ -123,6 +148,30 @@ export type ChildrenDecl = { [P in keyof SlotMap & string]?: SlotSpec<SlotMap[P]
 export type OwnerOf<K extends keyof SlotMap & string> =
   SlotMap[K] extends { owner: infer O extends object } ? O : object
 
+/** Registration/dispatch key domain of one keyed slot. */
+export type EntryKeyOf<K extends keyof SlotMap & string> =
+  SlotMap[K] extends { kind: 'keyed'; keyProps: infer P extends object }
+    ? keyof P & string
+    : string
+
+/** Key-dependent props supplied by the owner at one keyed dispatch site. */
+export type KeyPropsOf<
+  K extends keyof SlotMap & string,
+  EntryKey extends EntryKeyOf<K>,
+> = SlotMap[K] extends { kind: 'keyed'; keyProps: infer P extends object }
+  ? EntryKey extends keyof P
+    ? P[EntryKey] extends object ? P[EntryKey] : never
+    : never
+  : object
+
+/** Opaque per-render occurrence context declared by one slot. */
+export type HookContextOf<K extends keyof SlotMap & string> =
+  SlotMap[K] extends { hookContext: infer Context } ? Context : never
+
+/** Common render-occurrence inject face declared by one slot. */
+export type SlotInjectOf<K extends keyof SlotMap & string> =
+  SlotMap[K] extends { inject: infer Injected extends object } ? Injected : object
+
 /** Scope axis of a slot key's SlotMap entry. */
 export type ScopeOf<K extends keyof SlotMap & string> = SlotMap[K]['scope']
 
@@ -159,15 +208,26 @@ export type SessionIdOf = SessionStandardProps extends { sessionId: infer S } ?
  * Runtime props share for a slot key: owner share (parent's renderSlot call
  * site) + session standard kit (session scope only) + the global seat.
  */
-export type PropsRuntime<K extends keyof SlotMap & string> =
+export type PropsRuntime<
+  K extends keyof SlotMap & string,
+  EntryKey extends EntryKeyOf<K> = EntryKeyOf<K>,
+> =
   OwnerOf<K> &
+  KeyPropsOf<K, EntryKey> &
+  SlotInjectFace<SlotInjectOf<K>> &
   (ScopeOf<K> extends 'session' ? SessionStandardProps
     : ScopeOf<K> extends 'session-maybe' ? SessionMaybeStandardProps
       : object) &
   GlobalStandardProps
 
-/** renderSlot dispatch options: keyed dispatch key, list filtering, empty fallback. */
-export interface RenderOpts { entryKey?: string; only?: string; fallback?: ReactNode }
+/** renderSlot dispatch options: keyed dispatch key, list filtering, and empty fallback. */
+export interface RenderOpts<EntryKey extends string = string> {
+  entryKey?: EntryKey
+  only?: string
+  fallback?: ReactNode
+  /** Type-erased runtime seat; PropsRenderSlots narrows or removes it per slot declaration. */
+  hookContext?: unknown
+}
 
 /** renderSlotChain dispatch options. */
 export interface ChainRenderOpts {
@@ -200,6 +260,40 @@ export type ChainSelect<O extends object, M> = (owner: O) => M | null
 export type ChainKeysOf<S extends keyof SlotMap & string> =
   S extends unknown ? (SlotMap[S]['kind'] extends 'chain' ? S : never) : never
 
+/** Keys in a render share whose dispatch occurrence requires hookContext. */
+type ContextualKeysOf<S extends keyof SlotMap & string> =
+  S extends unknown ? (SlotMap[S] extends { hookContext: unknown } ? S : never) : never
+
+/** Keys in a render share with the ordinary optional options bag. */
+type OrdinaryKeysOf<S extends keyof SlotMap & string> = Exclude<S, ContextualKeysOf<S>>
+
+/**
+ * Plain and contextual child dispatch signatures. Keeping them as separate
+ * call signatures preserves ordinary renderSlot assignability while making a
+ * declared hookContext mandatory only for the Slot keys that need it.
+ */
+type RenderSlotFn<S extends keyof SlotMap & string> =
+  ([ContextualKeysOf<S>] extends [never] ? object : {
+    <
+      K extends ContextualKeysOf<S>,
+      EntryKey extends EntryKeyOf<K> = EntryKeyOf<K>,
+    >(
+      key: K,
+      owner: OwnerOf<K> & KeyPropsOf<K, NoInfer<EntryKey>>,
+      opts: RenderOpts<EntryKey> & { hookContext: HookContextOf<K> },
+    ): ReactNode
+  }) &
+  ([OrdinaryKeysOf<S>] extends [never] ? object : {
+    <
+      K extends OrdinaryKeysOf<S>,
+      EntryKey extends EntryKeyOf<K> = EntryKeyOf<K>,
+    >(
+      key: K,
+      owner: OwnerOf<K> & KeyPropsOf<K, NoInfer<EntryKey>>,
+      opts?: Omit<RenderOpts<EntryKey>, 'hookContext'>,
+    ): ReactNode
+  })
+
 /**
  * Chain matched share: a chain-slot component receives its selector's
  * non-null result as the framework-injected `matched` prop; other kinds add
@@ -248,7 +342,7 @@ export type PropsRenderSlots<S extends keyof SlotMap & string> = {
    * @param opts - kind dispatch options.
    * @returns rendered node(s).
    */
-  renderSlot: <K extends Exclude<S, ChainKeysOf<S>>>(key: K, owner: OwnerOf<K>, opts?: RenderOpts) => ReactNode
+  renderSlot: RenderSlotFn<Exclude<S, ChainKeysOf<S>>>
   readonly __renders?: ((key: S) => void) | undefined
 } & ([ChainKeysOf<S>] extends [never] ? object : {
   /**
@@ -277,19 +371,53 @@ export type SlotComponent<P> = (props: P) => ReactNode
 
 /**
  * Registrant hooks compartment: bare observable sources (getSnapshot +
- * subscribe pairs) supplied under the reserved `hooks` key of an inject
- * face. The registrant-private twin of the `sessions.provide` hooks
- * compartment: the renderer binds each source into a `use<Name>` selector
- * hook, so the sources never reach the component and plugin-private reactive
- * facts ride the same subscription machinery as the standard kit instead of
- * hand-rolled component subscriptions.
+ * subscribe pairs) supplied under the reserved `hooks` key of an entry's
+ * inject face. These retain the original source-to-selector binding and do
+ * not participate in render-occurrence context.
  */
 export type HooksSources = Record<string, HostObservable<unknown>>
 
+/** Framework-owned props visible while a slot-level contextual Hook is bound. */
+export type StandardPropsOf<K extends keyof SlotMap & string> =
+  (ScopeOf<K> extends 'session' ? SessionStandardProps
+    : ScopeOf<K> extends 'session-maybe' ? SessionMaybeStandardProps
+      : object) &
+  GlobalStandardProps
+
+/**
+ * One function-valued slot-level inject.hooks member. The factory is pure and
+ * returns the actual custom Hook; it must not invoke a Hook while being bound.
+ */
+export type SlotHookFactory<
+  K extends keyof SlotMap & string,
+  Hook extends (...args: never[]) => unknown,
+> = (
+  standard: StandardPropsOf<K>,
+  hookContext: HookContextOf<K>,
+) => Hook
+
+/** Component-side Hook produced from one slot-level inject.hooks member. */
+type BoundHookOf<Definition> =
+  Definition extends HostObservable<infer Snapshot>
+    ? SnapshotSelectorHook<Snapshot>
+    : Definition extends (...args: never[]) => infer Hook
+      ? Hook extends (...args: never[]) => unknown ? Hook : never
+      : never
+
 /**
  * Selector-hook share synthesized from a hooks compartment: each source
  * `name` becomes a `use<Name>` selector hook over its snapshot type.
  */
+export type PropsSlotHooks<HS extends object> = {
+  [N in keyof HS & string as `use${Capitalize<N>}`]:
+  BoundHookOf<HS[N]>
+}
+
+/** Component-side view of a slot dispatcher's common inject face. */
+export type SlotInjectFace<I extends object> =
+  I extends { hooks: infer HS extends object } ? Omit<I, 'hooks'> & PropsSlotHooks<HS> : I
+
+/** Selector-hook share synthesized from an entry inject hooks compartment. */
 export type PropsHooks<HS extends HooksSources> = {
   [N in keyof HS & string as `use${Capitalize<N>}`]:
   SnapshotSelectorHook<HS[N] extends HostObservable<infer T> ? T : never>
@@ -313,12 +441,13 @@ export type InjectFace<I extends object> =
  */
 export type ComposedProps<
   K extends keyof SlotMap & string,
+  EntryKey extends EntryKeyOf<K>,
   S extends keyof SlotMap & string,
   H,
   I extends object,
   M = never,
   N = undefined,
-> = PropsRuntime<K> & PropsRenderSlots<S> & PropsStore<H> & InjectFace<I> & MatchedShare<SlotMap[K], M> & PropsLocale<N>
+> = PropsRuntime<K, EntryKey> & PropsRenderSlots<S> & PropsStore<H> & InjectFace<I> & MatchedShare<SlotMap[K], M> & PropsLocale<N>
 
 /**
  * Inject factory parameter list, derived from the registration's declaration:
@@ -345,12 +474,16 @@ export type InjectParams<K extends keyof SlotMap & string, H> =
 export type SlotLabel = string | (() => string)
 
 /** Kind shape fields carried in register options (keyed dispatch key; list id/order/label; chain select/priority). */
-export type KindOptions<E extends SlotEntryDef, M = never> =
-  E['kind'] extends 'keyed' ? { key: string }
-    : E['kind'] extends 'list' ? { id: string; order?: number; label?: SlotLabel }
-      : E['kind'] extends 'chain' ? {
+export type KindOptions<
+  K extends keyof SlotMap & string,
+  EntryKey extends EntryKeyOf<K>,
+  M = never,
+> =
+  SlotMap[K]['kind'] extends 'keyed' ? { key: EntryKey }
+    : SlotMap[K]['kind'] extends 'list' ? { id: string; order?: number; label?: SlotLabel }
+      : SlotMap[K]['kind'] extends 'chain' ? {
         /** Routing selector, mandatory on chain entries; `M` (the component's `matched` prop) infers from its return. */
-        select: ChainSelect<E extends { owner: infer O extends object } ? O : object, M>
+        select: ChainSelect<SlotMap[K] extends { owner: infer O extends object } ? O : object, M>
         /** Explicit chain position (ascending, default 0, lower tries first); ties keep registration = assembly order. */
         priority?: number
       }
@@ -372,7 +505,14 @@ type RendersCheck<C, D> =
       : unknown
 
 /** Common register options share (see {@link SlotCore.register} for semantics). */
-type BaseOptions<K extends keyof SlotMap & string, D extends ChildrenDecl, H, M = never, N = undefined> = {
+type BaseOptions<
+  K extends keyof SlotMap & string,
+  EntryKey extends EntryKeyOf<K>,
+  D extends ChildrenDecl,
+  H,
+  M = never,
+  N = undefined,
+> = {
   /** Target slot key (the entry contributes INTO this slot). */
   name: K
   /** Child-slot declaration + render authorization + runtime spec, in one table. */
@@ -388,7 +528,7 @@ type BaseOptions<K extends keyof SlotMap & string, D extends ChildrenDecl, H, M
   locale?: N
   /** Registrant identity label for diagnostics (the runtime Service wrapper stamps the caller's fiber name). */
   registrant?: string
-} & KindOptions<SlotMap[K], M>
+} & KindOptions<K, EntryKey, M>
 
 /**
  * One stored registration, as recorded by the core and read by the render
@@ -528,15 +668,16 @@ export class SlotCore {
    * would lose the per-overload inference of I. */
   register<
     K extends keyof SlotMap & string,
+    const EntryKey extends EntryKeyOf<K> = EntryKeyOf<K>,
     const D extends ChildrenDecl = Record<never, never>,
     H extends StoreDecl | undefined = undefined,
     M = never,
     N extends (keyof LocaleNamespaceMap & string) | undefined = undefined,
     C extends SlotComponent<never> = SlotComponent<never>,
   >(
-    options: BaseOptions<K, D, H, M, N> & { inject?: undefined },
+    options: BaseOptions<K, EntryKey, D, H, M, N> & { inject?: undefined },
     component: C
-      & SlotComponent<ComposedProps<K, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, object, NoInfer<M>, NoInfer<N>>>
+      & SlotComponent<ComposedProps<K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, object, NoInfer<M>, NoInfer<N>>>
       & RendersCheck<C, D>,
   ): () => void
   /**
@@ -552,15 +693,16 @@ export class SlotCore {
   register<
     K extends keyof SlotMap & string,
     I extends object,
+    const EntryKey extends EntryKeyOf<K> = EntryKeyOf<K>,
     const D extends ChildrenDecl = Record<never, never>,
     H extends StoreDecl | undefined = undefined,
     M = never,
     N extends (keyof LocaleNamespaceMap & string) | undefined = undefined,
     C extends SlotComponent<never> = SlotComponent<never>,
   >(
-    options: BaseOptions<K, D, H, M, N> & { inject: (...args: InjectParams<K, H>) => I },
+    options: BaseOptions<K, EntryKey, D, H, M, N> & { inject: (...args: InjectParams<K, H>) => I },
     component: C
-      & SlotComponent<ComposedProps<K, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, I, NoInfer<M>, NoInfer<N>>>
+      & SlotComponent<ComposedProps<K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, I, NoInfer<M>, NoInfer<N>>>
       & RendersCheck<C, D>,
   ): () => void
   /* jscpd:ignore-end */
diff --git a/packages/client/ui-slots/src/renderer.ts b/packages/client/ui-slots/src/renderer.ts
index 2a676fa22a..20f6a68eb1 100644
--- a/packages/client/ui-slots/src/renderer.ts
+++ b/packages/client/ui-slots/src/renderer.ts
@@ -87,11 +87,13 @@ export interface SessionProvideInfo extends SessionMaybeProvideInfo {
   hooks: Record<string, HostObservable<unknown>>
 }
 
-/** renderSlot dispatch options at the machinery level: keyed dispatch key, list filtering, empty fallback. */
+/** renderSlot dispatch options at the machinery level. */
 export interface RenderOpts {
   entryKey?: string
   only?: string
   fallback?: ReactNode
+  /** Opaque occurrence context consumed only by function-valued injected Hooks. */
+  hookContext?: unknown
 }
 
 /** Host surface the runtime SlotsService presents to the installed renderer. */
diff --git a/packages/client/web-react/src/scoped-slots.tsx b/packages/client/web-react/src/scoped-slots.tsx
index f7a3c32e93..69d37f35b4 100644
--- a/packages/client/web-react/src/scoped-slots.tsx
+++ b/packages/client/web-react/src/scoped-slots.tsx
@@ -2,7 +2,7 @@
  * React renderer for declarative slots. Per-entry bindings enforce child
  * authorization, and entry boundaries contain registrant failures.
  */
-import { Component, useState, useSyncExternalStore, type FC, type ReactNode } from 'react'
+import { Component, useMemo, useState, useSyncExternalStore, type FC, type ReactNode } from 'react'
 import {
   SlotOwnershipError, StaleAuthorizationError,
   type ChainRenderOpts, type HostObservable, type LocaleFace, type RenderOpts,
@@ -16,6 +16,14 @@ import {
 
 type InjectedProps = Record<string, unknown>
 
+type SlotHookFactory = (standard: InjectedProps, hookContext: unknown) => unknown
+type SlotHookFactories = Readonly<Record<string, SlotHookFactory>>
+
+interface BoundSlotInject {
+  readonly props: InjectedProps
+  readonly slotHookFactories?: SlotHookFactories | undefined
+}
+
 type RenderSlotBinding = (key: string, owner: object, opts?: RenderOpts) => ReactNode
 
 type RenderSlotChainBinding = (key: string, owner: object, opts?: ChainRenderOpts) => ReactNode
@@ -89,9 +97,11 @@ const rootInjectCache = new WeakMap<StoredEntry, InjectedProps>()
 const sessionInjectCache = new WeakMap<StoredEntry, WeakMap<SessionProvideInfo, InjectedProps>>()
 const sessionMaybeInjectCache = new WeakMap<StoredEntry, WeakMap<SessionMaybeProvideInfo, InjectedProps>>()
 
+const EMPTY_INJECTED_PROPS: InjectedProps = {}
+
 function runInject(entry: StoredEntry, info: SessionMaybeProvideInfo | undefined, actions: object | undefined): InjectedProps {
   const inject = entry.inject
-  if (!inject) return {}
+  if (!inject) return EMPTY_INJECTED_PROPS
   // Declaration-derived positional arguments: sessionId for session scope,
   // baked actions when a store is declared.
   const args: unknown[] = []
@@ -101,11 +111,8 @@ function runInject(entry: StoredEntry, info: SessionMaybeProvideInfo | undefined
 }
 
 /**
- * Bind an inject face's reserved `hooks` compartment (bare observable
- * sources, see HooksSources) into `use<Name>` selector hooks — the
- * registrant-private twin of the provide-bundle binding in standardKit.
- * Runs once per cached inject result; hook identity rides observableHook's
- * per-source cache.
+ * Normalize one entry-owned inject face on its existing cache axis. Its hooks
+ * compartment remains the original Observable-only contract.
  */
 function bindInjectHooks(face: InjectedProps): InjectedProps {
   const sources = face['hooks']
@@ -119,6 +126,53 @@ function bindInjectHooks(face: InjectedProps): InjectedProps {
   return bound
 }
 
+const slotInjectCache = new WeakMap<object, BoundSlotInject>()
+const EMPTY_SLOT_INJECT: BoundSlotInject = { props: EMPTY_INJECTED_PROPS }
+
+/** Normalize one dispatcher-owned inject face by its stable object identity. */
+function cachedSlotInject(face: object | undefined): BoundSlotInject {
+  if (face === undefined) return EMPTY_SLOT_INJECT
+  let bound = slotInjectCache.get(face)
+  if (bound !== undefined) return bound
+  const definitions = (face as InjectedProps)['hooks']
+  if (definitions === undefined) {
+    bound = { props: face as InjectedProps }
+    slotInjectCache.set(face, bound)
+    return bound
+  }
+  const { hooks: _hooks, ...rest } = face as InjectedProps
+  const props: InjectedProps = rest
+  let factories: Record<string, SlotHookFactory> | undefined
+  for (const [name, definition] of Object.entries(definitions as Record<string, unknown>)) {
+    const hookName = `use${name[0]?.toUpperCase() ?? ''}${name.slice(1)}`
+    if (typeof definition === 'function') {
+      factories ??= {}
+      factories[name] = definition as SlotHookFactory
+    } else {
+      props[hookName] = observableHook(definition as HostObservable<unknown>)
+    }
+  }
+  bound = factories === undefined
+    ? { props }
+    : { props, slotHookFactories: factories }
+  slotInjectCache.set(face, bound)
+  return bound
+}
+
+/** Bind deferred slot-level factories for one stable renderSlot occurrence. */
+function bindSlotHookFactories(
+  factories: SlotHookFactories,
+  standard: InjectedProps,
+  hookContext: unknown,
+): InjectedProps {
+  const hooks: InjectedProps = {}
+  for (const [name, factory] of Object.entries(factories)) {
+    const hookName = `use${name[0]?.toUpperCase() ?? ''}${name.slice(1)}`
+    hooks[hookName] = factory(standard, hookContext)
+  }
+  return hooks
+}
+
 function cachedRootInject(entry: StoredEntry, actions: object | undefined): InjectedProps {
   let props = rootInjectCache.get(entry)
   if (!props) {
@@ -270,6 +324,54 @@ class SlotErrorBoundary extends Component<
   }
 }
 
+interface StandardPropsCache {
+  readonly root: InjectedProps
+  readonly session: WeakMap<SessionMaybeProvideInfo, InjectedProps>
+  readonly sessionMaybe: WeakMap<SessionMaybeProvideInfo, InjectedProps>
+}
+
+const standardPropsCache = new WeakMap<SlotRendererHost, StandardPropsCache>()
+
+/** Stable official-props object used by contextual Hook factories. */
+function standardProps(
+  host: SlotRendererHost,
+  scope: SlotScope,
+  info: SessionMaybeProvideInfo | undefined,
+): InjectedProps {
+  let cache = standardPropsCache.get(host)
+  if (cache === undefined) {
+    cache = {
+      root: {
+        useSessions: observableHook(host.sessions.list),
+        useWorkspaces: observableHook(host.workspaces.list),
+      },
+      session: new WeakMap(),
+      sessionMaybe: new WeakMap(),
+    }
+    standardPropsCache.set(host, cache)
+  }
+  if (scope === 'root') return cache.root
+  if (info === undefined) throw new SlotAssemblyError(`scope '${scope}' rendered without session provide info`)
+  const byInfo = scope === 'session' ? cache.session : cache.sessionMaybe
+  let standard = byInfo.get(info)
+  if (standard !== undefined) return standard
+  standard = { ...cache.root }
+  for (const [name, source] of Object.entries(info.hooks)) {
+    const hookName = `use${name[0]?.toUpperCase() ?? ''}${name.slice(1)}`
+    if (scope === 'session-maybe') {
+      standard[hookName] = maybeObservableHook(source)
+    } else {
+      if (source === undefined) throw new SlotAssemblyError(`strict session hook '${name}' has no source`)
+      standard[hookName] = observableHook(source)
+    }
+  }
+  Object.assign(standard, info.props)
+  standard['sessionId'] = info.sessionId
+  standard['useProjection'] = projectionHook(info)
+  byInfo.set(info, standard)
+  return standard
+}
+
 /**
  * Standard-kit synthesis shared by both scope branches: the global
  * useSessions/useWorkspaces hooks, the per-session provide bundle (every
@@ -289,28 +391,11 @@ function standardKit(
   info: SessionMaybeProvideInfo | undefined,
 ): {
   kit: InjectedProps
+  standard: InjectedProps
   actions: object | undefined
 } {
-  const kit: InjectedProps = {
-    useSessions: observableHook(host.sessions.list),
-    useWorkspaces: observableHook(host.workspaces.list),
-  }
-  if (scope !== 'root' && info !== undefined) {
-    for (const [name, source] of Object.entries(info.hooks)) {
-      const hookName = `use${name[0]?.toUpperCase() ?? ''}${name.slice(1)}`
-      if (scope === 'session-maybe') {
-        kit[hookName] = maybeObservableHook(source)
-      } else {
-        if (source === undefined) throw new SlotAssemblyError(`strict session hook '${name}' has no source`)
-        kit[hookName] = observableHook(source)
-      }
-    }
-    Object.assign(kit, info.props)
-    kit['sessionId'] = info.sessionId
-    // The useProjection seat (fifth framework hook): key-addressed cell
-    // reader, bound per provide bundle (cached by info identity).
-    kit['useProjection'] = projectionHook(info)
-  }
+  const standard = standardProps(host, scope, info)
+  const kit: InjectedProps = { ...standard }
   if (entry.locale !== undefined) {
     const face = host.locale
     // Loud assembly failure: locale is immediately-tier infrastructure; a
@@ -344,38 +429,98 @@ function standardKit(
       kit['SessionProvider'] = SessionProvider
     }
   }
-  return { kit, actions: store?.actions }
+  return { kit, standard, actions: store?.actions }
 }
 
 /**
- * One rendered entry: standard kit + cached inject + owner props (owner
- * wins). The kit and injected shares are erased at the render boundary — the
- * registration contract already proved the composed type — so each Entry renders
- * through a props-widened view of the component (the design-budgeted
- * composition point, one per scope branch).
+ * One rendered entry: standard kit + cached entry inject + common slot inject
+ * + owner props (owner wins). The shares are erased at this render boundary;
+ * the registration and renderSlot seams already proved their contracts.
  */
-function SessionEntry({ entry, ownerProps, info }: {
+function ContextualEntry({
+  slotKey, Comp, kit, standard, injected, slotInjected, ownerProps, hookContext, hasHookContext,
+}: {
+  slotKey: string
+  Comp: FC<InjectedProps>
+  kit: InjectedProps
+  standard: InjectedProps
+  injected: InjectedProps
+  slotInjected: BoundSlotInject & { readonly slotHookFactories: SlotHookFactories }
+  ownerProps: object
+  hookContext: unknown
+  hasHookContext: boolean
+}) {
+  const contextual = useMemo(
+    () => {
+      if (!hasHookContext) {
+        throw new SlotAssemblyError(`slot '${slotKey}' has contextual injected Hooks but no hookContext`)
+      }
+      return bindSlotHookFactories(slotInjected.slotHookFactories, standard, hookContext)
+    },
+    [hasHookContext, hookContext, slotInjected.slotHookFactories, slotKey, standard],
+  )
+  return <Comp {...kit} {...injected} {...slotInjected.props} {...contextual} {...ownerProps} />
+}
+
+function renderEntry(
+  slotKey: string,
+  Comp: FC<InjectedProps>,
+  kit: InjectedProps,
+  standard: InjectedProps,
+  injected: InjectedProps,
+  slotInjected: BoundSlotInject,
+  ownerProps: object,
+  hookContext: unknown,
+  hasHookContext: boolean,
+): ReactNode {
+  if (slotInjected.slotHookFactories === undefined) {
+    return <Comp {...kit} {...injected} {...slotInjected.props} {...ownerProps} />
+  }
+  return (
+    <ContextualEntry
+      slotKey={slotKey}
+      Comp={Comp}
+      kit={kit}
+      standard={standard}
+      injected={injected}
+      slotInjected={slotInjected as BoundSlotInject & { readonly slotHookFactories: SlotHookFactories }}
+      ownerProps={ownerProps}
+      hookContext={hookContext}
+      hasHookContext={hasHookContext}
+    />
+  )
+}
+
+function SessionEntry({ entry, ownerProps, info, slotKey, slotInjected, hookContext, hasHookContext }: {
   entry: StoredEntry
   ownerProps: object
   info: SessionProvideInfo
+  slotKey: string
+  slotInjected: BoundSlotInject
+  hookContext: unknown
+  hasHookContext: boolean
 }) {
   const host = useHost()
   const Comp = entry.component as FC<InjectedProps>
-  const { kit, actions } = standardKit(host, entry, 'session', info)
+  const { kit, standard, actions } = standardKit(host, entry, 'session', info)
   const injected = cachedSessionInject(entry, info, actions)
-  return <Comp {...kit} {...injected} {...ownerProps} />
+  return renderEntry(slotKey, Comp, kit, standard, injected, slotInjected, ownerProps, hookContext, hasHookContext)
 }
 
-function SessionMaybeEntryBody({ entry, ownerProps, info }: {
+function SessionMaybeEntryBody({ entry, ownerProps, info, slotKey, slotInjected, hookContext, hasHookContext }: {
   entry: StoredEntry
   ownerProps: object
   info: SessionMaybeProvideInfo
+  slotKey: string
+  slotInjected: BoundSlotInject
+  hookContext: unknown
+  hasHookContext: boolean
 }) {
   const host = useHost()
   const Comp = entry.component as FC<InjectedProps>
-  const { kit, actions } = standardKit(host, entry, 'session-maybe', info)
+  const { kit, standard, actions } = standardKit(host, entry, 'session-maybe', info)
   const injected = cachedSessionMaybeInject(entry, info, actions)
-  return <Comp {...kit} {...injected} {...ownerProps} />
+  return renderEntry(slotKey, Comp, kit, standard, injected, slotInjected, ownerProps, hookContext, hasHookContext)
 }
 
 /**
@@ -391,7 +536,14 @@ function SessionMaybeEntryBody({ entry, ownerProps, info }: {
  * that must SURVIVE a switch belongs in session-bound sources (machine,
  * store, hooks) — the existing layering rule, now load-bearing.
  */
-function SessionMaybeEntry({ entry, ownerProps }: { entry: StoredEntry; ownerProps: object }) {
+function SessionMaybeEntry({ entry, ownerProps, slotKey, slotInjected, hookContext, hasHookContext }: {
+  entry: StoredEntry
+  ownerProps: object
+  slotKey: string
+  slotInjected: BoundSlotInject
+  hookContext: unknown
+  hasHookContext: boolean
+}) {
   const info = useSessionMaybeProvideInfo()
   // The child key is an incarnation counter, NOT the session id: adoption
   // must keep the key constant across undefined → first id. Bookkeeping
@@ -416,7 +568,18 @@ function SessionMaybeEntry({ entry, ownerProps }: { entry: StoredEntry; ownerPro
     epoch += 1
     setState({ adopted, epoch })
   }
-  return <SessionMaybeEntryBody key={epoch} entry={entry} ownerProps={ownerProps} info={info} />
+  return (
+    <SessionMaybeEntryBody
+      key={epoch}
+      entry={entry}
+      ownerProps={ownerProps}
+      info={info}
+      slotKey={slotKey}
+      slotInjected={slotInjected}
+      hookContext={hookContext}
+      hasHookContext={hasHookContext}
+    />
+  )
 }
 
 /** Adoption bookkeeping of one session-maybe outlet (see SessionMaybeEntry). */
@@ -429,24 +592,42 @@ interface MaybeIncarnation {
 
 const FIRST_INCARNATION: MaybeIncarnation = { adopted: undefined, epoch: 0 }
 
-function RootEntry({ entry, ownerProps }: { entry: StoredEntry; ownerProps: object }) {
+function RootEntry({ entry, ownerProps, slotKey, slotInjected, hookContext, hasHookContext }: {
+  entry: StoredEntry
+  ownerProps: object
+  slotKey: string
+  slotInjected: BoundSlotInject
+  hookContext: unknown
+  hasHookContext: boolean
+}) {
   const host = useHost()
   const Comp = entry.component as FC<InjectedProps>
-  const { kit, actions } = standardKit(host, entry, 'root', undefined)
+  const { kit, standard, actions } = standardKit(host, entry, 'root', undefined)
   const injected = cachedRootInject(entry, actions)
-  return <Comp {...kit} {...injected} {...ownerProps} />
+  return renderEntry(slotKey, Comp, kit, standard, injected, slotInjected, ownerProps, hookContext, hasHookContext)
 }
 
-function StrictSessionEntry({ slotKey, entry, ownerProps }: {
+function StrictSessionEntry({ slotKey, entry, ownerProps, slotInjected, hookContext, hasHookContext }: {
   slotKey: string
   entry: StoredEntry
   ownerProps: object
+  slotInjected: BoundSlotInject
+  hookContext: unknown
+  hasHookContext: boolean
 }) {
   const info = useSessionMaybeProvideInfo()
   if (info.sessionId === undefined) return null
   return (
     <SlotErrorBoundary slotKey={slotKey} key={info.sessionId}>
-      <SessionEntry entry={entry} ownerProps={ownerProps} info={info as SessionProvideInfo} />
+      <SessionEntry
+        entry={entry}
+        ownerProps={ownerProps}
+        info={info as SessionProvideInfo}
+        slotKey={slotKey}
+        slotInjected={slotInjected}
+        hookContext={hookContext}
+        hasHookContext={hasHookContext}
+      />
     </SlotErrorBoundary>
   )
 }
@@ -478,31 +659,62 @@ function SlotOutlet({ slotKey, ownerProps, opts }: {
   // An absent strict overlay chain follows its ordinary empty-election path,
   // preserving the Fragment/fallback-wrapper shape across session arrival.
   const entries = strictSessionAbsent ? [] : host.entriesOf(slotKey)
+  const slotInjected = cachedSlotInject(spec.inject)
 
   // The boundary must wrap the Entry ELEMENT, not live inside it: inject
   // factories and kit synthesis run in the Entry body and must land in the
   // per-entry fallback rather than escaping to the tree above.
-  const guarded = (entry: StoredEntry, key?: string | number, owner: object = ownerProps) => (
-    spec.scope === 'session'
-      ? <StrictSessionEntry slotKey={slotKey} entry={entry} ownerProps={owner} key={key} />
+  const guarded = (entry: StoredEntry, key?: string | number, owner: object = ownerProps) => {
+    const hasHookContext = opts !== undefined && Object.hasOwn(opts, 'hookContext')
+    const hookContext = opts?.hookContext
+    return spec.scope === 'session'
+      ? (
+        <StrictSessionEntry
+          slotKey={slotKey}
+          entry={entry}
+          ownerProps={owner}
+          slotInjected={slotInjected}
+          hookContext={hookContext}
+          hasHookContext={hasHookContext}
+          key={key}
+        />
+      )
       : (
         <SlotErrorBoundary slotKey={slotKey} key={key}>
           {spec.scope === 'session-maybe'
-            ? <SessionMaybeEntry entry={entry} ownerProps={owner} />
-            : <RootEntry entry={entry} ownerProps={owner} />}
+            ? (
+              <SessionMaybeEntry
+                entry={entry}
+                ownerProps={owner}
+                slotKey={slotKey}
+                slotInjected={slotInjected}
+                hookContext={hookContext}
+                hasHookContext={hasHookContext}
+              />
+            )
+            : (
+              <RootEntry
+                entry={entry}
+                ownerProps={owner}
+                slotKey={slotKey}
+                slotInjected={slotInjected}
+                hookContext={hookContext}
+                hasHookContext={hasHookContext}
+              />
+            )}
         </SlotErrorBoundary>
       )
-  )
+  }
 
   if (spec.kind === 'single') {
     const entry = entries[0]
     if (!entry) return <>{opts?.fallback ?? null}</>
-    return guarded(entry)
+    return guarded(entry, entryKeyOf(entry))
   }
   if (spec.kind === 'keyed') {
     const entry = entries.find(e => e.options.key === opts?.entryKey)
     if (!entry) return <>{opts?.fallback ?? null}</>
-    return guarded(entry)
+    return guarded(entry, entryKeyOf(entry))
   }
   if (spec.kind === 'chain') {
     // Entries arrive priority-sorted from the ledger (the core orders at
@@ -561,7 +773,7 @@ function SlotOutlet({ slotKey, ownerProps, opts }: {
   let list = [...withListOptions].sort((a, b) => a.order - b.order)
   if (opts?.only !== undefined) list = list.filter(item => item.id === opts.only)
   if (list.length === 0) return <>{opts?.fallback ?? null}</>
-  return <>{list.map((item, i) => guarded(item.entry, item.id ?? i))}</>
+  return <>{list.map(item => guarded(item.entry, entryKeyOf(item.entry)))}</>
 }
 
 /** Root outlet: the shell's single ctx-level render entry — an unregistered 'root' is a boot-order failure, never a silent blank (§1). */
@@ -575,8 +787,15 @@ function RootOutlet({ ownerProps }: { ownerProps: object }) {
   const entry = host.entriesOf('root')[0]
   if (!entry) throw new SlotAssemblyError("renderSlot('root') before any 'root' registration (boot order)")
   return (
-    <SlotErrorBoundary slotKey="root">
-      <RootEntry entry={entry} ownerProps={ownerProps} />
+    <SlotErrorBoundary slotKey="root" key={entryKeyOf(entry)}>
+      <RootEntry
+        entry={entry}
+        ownerProps={ownerProps}
+        slotKey="root"
+        slotInjected={EMPTY_SLOT_INJECT}
+        hookContext={undefined}
+        hasHookContext={false}
+      />
     </SlotErrorBoundary>
   )
 }

From 6d09b3168d035f7668ea73b745a115be1dc7eaac Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:48:40 +0800
Subject: [PATCH 487/516] refactor(ui-conversation): register business node
 definitions

---
 packages/client/ui-conversation/package.json  |   2 +
 .../ui-conversation/src/client/apply.ts       |  36 +-
 .../src/client/chat/AssistantMarkdown.tsx     |  72 +--
 .../src/client/chat/AssistantNodeView.tsx     |  32 ++
 .../src/client/chat/ChatNodeSeat.tsx          |  60 +++
 .../src/client/chat/ChatView.module.css       |  14 +-
 .../src/client/chat/ChatView.tsx              | 303 ++----------
 .../src/client/chat/CommandNodeView.tsx       |  40 ++
 .../src/client/chat/MessageItem.tsx           | 126 ++---
 .../src/client/chat/StatsLine.tsx             |   4 +-
 .../client/chat/TurnTailNodeView.module.css   |   9 +
 .../src/client/chat/TurnTailNodeView.tsx      |  43 ++
 .../src/client/chat/chat-flow.ts              | 214 --------
 .../client/chat/register-node-renderers.ts    |  46 ++
 .../src/client/chat/tool-node-reader.ts       |  46 ++
 .../src/client/chat/turn-assistant.ts         |  10 +
 .../src/client/chat/turn-metrics.ts           |   6 +-
 .../src/client/contract/chat-nodes.ts         |  82 ++++
 .../src/client/contract/slots.ts              |  93 ++--
 .../client/conversation-nodes/assistant.ts    | 316 ++++++++++++
 .../chat-snapshot-builder.ts                  | 456 ++++++++++++++++++
 .../src/client/conversation-nodes/command.ts  | 243 ++++++++++
 .../src/client/conversation-nodes/common.ts   |  55 +++
 .../client/conversation-nodes/compaction.ts   |  63 +++
 .../src/client/conversation-nodes/fallback.ts |  40 ++
 .../src/client/conversation-nodes/inbox.ts    |  71 +++
 .../src/client/conversation-nodes/message.ts  |  83 ++++
 .../src/client/conversation-nodes/register.ts |  30 ++
 .../src/client/conversation-nodes/retry.ts    | 116 +++++
 .../src/client/conversation-nodes/tool.ts     | 271 +++++++++++
 .../client/conversation-nodes/turn-error.ts   | 112 +++++
 .../client/conversation-nodes/turn-tail.ts    | 180 +++++++
 .../ui-conversation/src/client/index.ts       |  19 +-
 .../src/client/skeleton/ApprovalPanel.tsx     |   9 +-
 .../src/client/skeleton/DetailsPanel.tsx      |  27 +-
 .../client/ui-conversation/src/invariant.ts   |   2 +-
 .../ui-deliverables/src/client/index.ts       |   7 +-
 .../src/client/turn-deliverables.ts           | 139 ++++--
 packages/client/ui-tool/src/client/apply.ts   |   5 +-
 .../ui-tool/src/client/contract/slots.ts      |   4 +-
 .../ui-tool/src/client/tool/ToolCallTree.tsx  |   3 +-
 41 files changed, 2744 insertions(+), 745 deletions(-)
 create mode 100644 packages/client/ui-conversation/src/client/chat/AssistantNodeView.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/CommandNodeView.tsx
 create mode 100644 packages/client/ui-conversation/src/client/chat/TurnTailNodeView.module.css
 create mode 100644 packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
 delete mode 100644 packages/client/ui-conversation/src/client/chat/chat-flow.ts
 create mode 100644 packages/client/ui-conversation/src/client/chat/register-node-renderers.ts
 create mode 100644 packages/client/ui-conversation/src/client/chat/tool-node-reader.ts
 create mode 100644 packages/client/ui-conversation/src/client/chat/turn-assistant.ts
 create mode 100644 packages/client/ui-conversation/src/client/contract/chat-nodes.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/command.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/common.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/fallback.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/message.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/register.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
 create mode 100644 packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts

diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
index 2ff87cc0e2..3f5bd8364c 100644
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -44,6 +44,7 @@
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slash": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-compact": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-token-meter": "^0.0.1",
     "cordis": "^4.0.0-rc.7",
@@ -53,6 +54,7 @@
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-plan-mode": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 0e486e9154..6d8e8e8c67 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -7,8 +7,9 @@ import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type { ViewTab } from './contract/views.ts'
 import type {
-  ApprovalWait, ChatScrollPosition, ChatViewInjected, ComposerBarInjected, ComposerChainProps, ConversationInjected,
-  ConversationSessionHeaderInjected, ConversationSessionInjected, DetailsInjected,
+  ApprovalWait, ChatNodeTurnDataInjected, ChatScrollPosition, ChatViewInjected, ComposerBarInjected,
+  ComposerChainProps, ConversationInjected, ConversationSessionHeaderInjected, ConversationSessionInjected,
+  DetailsInjected,
 } from './contract/slots.ts'
 import type { InputNotice } from './input/contract.ts'
 import { createChatStore } from './stores.ts'
@@ -30,6 +31,8 @@ import { ConversationRoot } from './skeleton/ConversationRoot.tsx'
 import { ConversationSession, ConversationSessionHeader } from './skeleton/ConversationSession.tsx'
 import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
 import { en, NS, zh, type ConversationKey } from './locales.ts'
+import { registerConversationNodes } from './conversation-nodes/register.ts'
+import { registerChatNodeRenderers } from './chat/register-node-renderers.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -39,7 +42,10 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 }
 
 /** Services required by the conversation plugin. */
-export const inject = ['slots', 'layout', 'sessions', 'workspaces', 'locale']
+export const inject = [
+  'slots', 'layout', 'sessions', 'workspaces', 'locale',
+  'conversationEvents', 'conversationViews',
+]
 
 // Static no-session sources for the composer-bar hooks compartment: module
 // constants so the render side's per-source hook cache (observableHook) keeps
@@ -63,6 +69,19 @@ const ABSENT_MENU_LAUNCHER = {
   subscribe: () => () => {},
 }
 
+const CHAT_NODE_INJECT: ChatNodeTurnDataInjected = {
+  hooks: {
+    turnData: ({ useSession }, nodeKey) => function useTurnData(key) {
+      return useSession((snapshot) => {
+        const location = snapshot.chat.nodes.get(nodeKey)?.location
+        return location?.kind === 'turn' || location?.kind === 'step'
+          ? location.turn.data.get(key)
+          : undefined
+      })
+    },
+  },
+}
+
 /** Resolve the session-scoped conversation face (scope-addressed send/cancel), failing loud. */
 function scopedConversation(sessions: ISessions, id: SessionId): IConversation {
   const scoped = sessions.scope(id)
@@ -86,6 +105,9 @@ export function apply(ctx: Context): void {
   const layout = ctx.layout
   const slots = ctx.slots
 
+  registerConversationNodes(ctx)
+  registerChatNodeRenderers(ctx)
+
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-conversation: dictionaries')
 
   // Registration-time text (the view tab label) reads through the bound
@@ -296,8 +318,8 @@ export function apply(ctx: Context): void {
   slots.register({ name: 'conversation.composer', select: selectApproval, priority: 1, locale: NS }, ApprovalPanel)
 
   // The chat view: first entry of the ring this package just declared.
-  // ChatView owns ordered Tool placement but delegates each whole root call
-  // to ui-tool, which owns root/subcall composition and atomic dispatch.
+  // ChatView owns only the stable ordered Node list. Business renderers are
+  // independently keyed behind its one Node seat.
   slots.register({
     name: 'conversation.view',
     id: 'chat',
@@ -305,9 +327,7 @@ export function apply(ctx: Context): void {
     label: () => t('view.chat'),
     locale: NS,
     children: {
-      'conversation.chat.tool': { kind: 'single', scope: 'session' },
-      'conversation.chat.commandview': { kind: 'keyed', scope: 'session' },
-      'conversation.chat.turnTail': { kind: 'chain', scope: 'session' },
+      'conversation.chat.node': { kind: 'keyed', scope: 'session', inject: CHAT_NODE_INJECT },
     },
     store: chatStore,
     inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ChatViewInjected => {
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index d8883be4cd..6dd9f09b4d 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -11,12 +11,9 @@
 
 import { memo, useMemo } from 'react'
 import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
-import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { JsonBlock, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps, ChatViewInjected, TurnTailOwnerProps } from '../contract/slots.ts'
-import { hasContentText } from './chat-flow.ts'
-import { MessageIconActions } from './MessageIconActions.tsx'
+import type { ChatViewSlotProps } from '../contract/slots.ts'
 import { ReasoningRow } from './ReasoningRow.tsx'
 import css from './AssistantMarkdown.module.css'
 
@@ -25,61 +22,19 @@ export interface AssistantMarkdownProps {
   streaming: boolean
   /** Frozen partial of an aborted turn: rendered with a stopped marker. */
   interrupted?: boolean | undefined
-  /** Unix epoch ms for the IconActions clock; omitted while streaming or when
-   *  the parent withholds chrome (mid-turn content assistants and every node
-   *  of a turn that has not ended). */
-  time?: number | undefined
-  /** Turn wall time in ms for the IconActions run-time label; omitted when the
-   *  turn's triggering input is outside the loaded window. */
-  runMs?: number | undefined
-  /** Turn first-step TTFT in ms for the IconActions label; omitted when unrecorded. */
-  ttftMs?: number | undefined
-  /** Turn decode throughput for the IconActions label; omitted when unrecorded. */
-  tokensPerSecond?: number | undefined
-  /** Event sequence used as the fork boundary; omitted while streaming. */
-  seq?: number | undefined
-  /** Fork the session through this finalized message's completed turn when eligible. */
-  onFork?: ((seq: number) => void) | undefined
-  /** Turn-tail slot dispatch share and owner currency; omitted for a mid-turn assistant. */
-  turnTail?: (Pick<PropsRenderSlots<'conversation.chat.turnTail'>, 'renderSlotChain'> & { owner: TurnTailOwnerProps }) | undefined
-  /** Prose file-mention factory (the injected face); omitted wherever `turnTail` is. */
-  fileMentions?: ChatViewInjected['fileMentions'] | undefined
-  /** The message is not the transcript tail of a completed turn. */
-  forkUnavailable?: boolean | undefined
+  /** Resolved prose file mentions for this Assistant's closing turn. */
+  mentions?: MarkdownFileMentions | undefined
   /** The owning view's locale seat, passed down as a plain prop. */
   t: ChatViewSlotProps['t']
 }
 
-/** Joined text blocks for the copy action (reasoning / tool heads stay out). */
-function copyText(blocks: readonly AssistantBlock[]): string {
-  const parts: string[] = []
-  for (const block of blocks) {
-    if (block.kind === 'text') parts.push(block.text)
-  }
-  return parts.join('')
-}
-
 /** Reasoning block as the Think variant summary row (figma 39:28304). */
 export const AssistantMarkdown = memo(function AssistantMarkdown({
-  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, turnTail,
-  fileMentions, t,
+  blocks, streaming, interrupted, mentions, t,
 }: AssistantMarkdownProps) {
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
   const codeLabels = useMemo(() => ({ copyLabel: t('copy'), copiedLabel: t('copied') }), [t])
-  // Mention vocabulary for the closing prose. Keyed on the anchor seq, not the
-  // growing transcript: a settled turn's produced files are final, and a
-  // fresh identity per append would discard MarkdownText's cached parse for
-  // every settled closing message on every stream chunk. The window-prepend
-  // edge (a mid-turn window start later gaining earlier same-turn writes)
-  // leaves a mention unlinked until remount — never a wrong link.
-  const owner = turnTail?.owner
-  const mentions: MarkdownFileMentions | undefined = useMemo(
-    () => (owner === undefined ? undefined : fileMentions?.(owner)),
-    // Deliberately not `owner`: its identity changes per append while the
-    // seq-addressed vocabulary it yields does not.
-    [fileMentions, owner?.seq],
-  )
   const last = blocks.length - 1
   // Tool-call heads render as tool rows in the chat view's grouping pass, so
   // a node that is only those heads (or empty) would paint an empty root
@@ -88,10 +43,8 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
     || interrupted === true
     || blocks.some(block => block.kind !== 'tool-call')
   if (!hasVisible) return null
-  // Footer only under settled content text; Think-only / streaming omit it.
-  const showActions = !streaming && time !== undefined && hasContentText(blocks)
   return (
-    <div className={css.root} data-streaming={streaming || undefined} data-time-hover-root>
+    <div className={css.root} data-streaming={streaming || undefined}>
       <div className={css.body}>
         {blocks.map((block, i) => {
           switch (block.kind) {
@@ -119,21 +72,6 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
         })}
         {interrupted && <span className={css.stopped}>{t('message.stopped')}</span>}
       </div>
-      {showActions && turnTail?.renderSlotChain('conversation.chat.turnTail', turnTail.owner)}
-      {showActions && (
-        <MessageIconActions
-          text={copyText(blocks)}
-          time={time}
-          runMs={runMs}
-          ttftMs={ttftMs}
-          tokensPerSecond={tokensPerSecond}
-          clock="end"
-          onBranch={onFork === undefined || seq === undefined ? undefined : () => { onFork(seq) }}
-          branchUnavailable={forkUnavailable}
-          className={css.actions}
-          t={t}
-        />
-      )}
     </div>
   )
 })
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantNodeView.tsx b/packages/client/ui-conversation/src/client/chat/AssistantNodeView.tsx
new file mode 100644
index 0000000000..d0f8b33e6f
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/AssistantNodeView.tsx
@@ -0,0 +1,32 @@
+import { memo, useMemo } from 'react'
+import type { ChatNodeViewProps, TurnTailOwnerProps } from '../contract/slots.ts'
+import { AssistantMarkdown } from './AssistantMarkdown.tsx'
+
+/** Streaming, settled, and interrupted Assistant states share one keyed renderer instance. */
+export const AssistantNodeView = memo(function AssistantNodeView({
+  node, useTurnData, openFile, fileMentions, t,
+}: ChatNodeViewProps<'assistant-step'>) {
+  const data = node.data
+  const turn = node.location.kind === 'turn' || node.location.kind === 'step'
+    ? node.location.turn
+    : undefined
+  const tail = useTurnData('turn-tail')
+  const owner = useMemo<TurnTailOwnerProps | undefined>(() => {
+    if (turn?.status !== 'closed' || data.finalNode === undefined) return undefined
+    if (tail?.closing?.finalNode.seq !== data.finalNode.seq) return undefined
+    return { turn, seq: data.finalNode.seq, openFile }
+  }, [data.finalNode, openFile, tail, turn])
+  const mentions = useMemo(
+    () => owner === undefined ? undefined : fileMentions(owner),
+    [fileMentions, owner],
+  )
+  return (
+    <AssistantMarkdown
+      blocks={data.blocks}
+      streaming={data.status === 'running'}
+      interrupted={data.status === 'interrupted'}
+      mentions={mentions}
+      t={t}
+    />
+  )
+})
diff --git a/packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx b/packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx
new file mode 100644
index 0000000000..1f7a2f7451
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx
@@ -0,0 +1,60 @@
+import { memo, useMemo } from 'react'
+import { JsonBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatNode } from '../contract/chat-nodes.ts'
+import css from './ChatView.module.css'
+
+interface ChatNodeSeatProps extends ChatNodeOwnerProps {
+  readonly nodeKey: string
+  readonly useSession: ChatViewSlotProps['useSession']
+  readonly renderSlot: ChatViewSlotProps['renderSlot']
+  readonly t: ChatViewSlotProps['t']
+}
+
+type RoutedChatNodeOwner = {
+  [Kind in ChatNode['kind']]: ChatNodeOwnerProps & { readonly node: ChatNode<Kind> }
+}[ChatNode['kind']]
+
+/** Subscribe and dispatch one stable Context key without observing sibling Nodes. */
+export const ChatNodeSeat = memo(function ChatNodeSeat({
+  nodeKey, selectedCallId, cwd, openFile, inspectCall, forkAt,
+  fileMentions, useSession, renderSlot, t,
+}: ChatNodeSeatProps) {
+  const node = useSession(snapshot => snapshot.chat.nodes.get(nodeKey))
+  const routedNode = node as ChatNode | undefined
+  const owner = useMemo<ChatNodeOwnerProps | null>(() => node === undefined
+    ? null
+    : {
+      selectedCallId,
+      cwd,
+      openFile,
+      inspectCall,
+      forkAt,
+      fileMentions,
+    }, [node, selectedCallId, cwd, openFile, inspectCall, forkAt, fileMentions])
+  if (routedNode === undefined || owner === null) return null
+  // Runtime dispatch owns the correlation: every Node's discriminant is the
+  // keyed-slot entry passed alongside that same Node. TypeScript does not
+  // distribute an object containing a union into a union of objects itself.
+  const routedOwner = { ...owner, node: routedNode } as RoutedChatNodeOwner
+  return (
+    <div
+      className={css.flowItem}
+      data-chat-anchor-key={routedNode.key}
+      data-chat-flow-key={routedNode.key}
+      data-chat-flow-kind={routedNode.kind}
+    >
+      {renderSlot('conversation.chat.node', routedOwner, {
+        entryKey: routedNode.kind,
+        hookContext: nodeKey,
+        fallback: (
+          <JsonBlock
+            label={t('message.unknownSurface', { type: routedNode.kind })}
+            payload={routedNode.data}
+            truncatedLabel={total => t('json.truncated', { total })}
+          />
+        ),
+      })}
+    </div>
+  )
+})
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.module.css b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
index c600b3b0aa..d16608c856 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.module.css
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
@@ -1,6 +1,5 @@
-/* Chat flow: one 16px rhythm everywhere — between blocks (prose <-> tool
-   runs) via the column gap and between consecutive tool rows via the group
-   gap. Input padding cap rides the skeleton. Under
+/* Chat flow: one 16px rhythm everywhere through the column gap. Input
+   padding cap rides the skeleton. Under
    `[data-conversation-scroll]` the column host owns overflow and this view
    is ordinary flow (see ConversationRoot active-phase rules). */
 
@@ -51,10 +50,11 @@
   min-width: 0;
 }
 
-.toolGroup {
-  display: flex;
-  flex-direction: column;
-  gap: 16px;
+/* A keyed renderer may intentionally decline its row after dispatch (the
+   completed-turn tail does this when it owns neither actions nor extensions).
+   An empty flex item must not consume the column gap. */
+.flowItem:empty {
+  display: none;
 }
 
 .callRow {
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index 3636a2a971..44ae6f345a 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -1,41 +1,24 @@
-// ChatView: the default conversation view — message flow with user bubbles,
-// assistant narration, tool summary rows grouped into step runs, pending
-// cards, paging, and bottom-follow. Session stats live on
-// 'conversation.composer.dock' (sticky with the composer). Pure component
-// registered directly; its registration declares the whole-Tool
-// 'conversation.chat.tool' seat. ui-tool owns root/subcall composition and
-// keyed per-tool dispatch behind that boundary.
+// ChatView: the default conversation view — one stable keyed parent list over
+// final business Nodes, plus paging, pending steering and bottom-follow.
+// Each row dispatches through 'conversation.chat.node'; ui-tool owns the
+// tool-call renderer and its recursive root/subcall composition.
 //
 // Scroll: when nested under `[data-conversation-scroll]` (active conversation
 // column), that host is the scrollport and this view is flow content; when
 // mounted alone (unit tests), `.scroll` owns overflow. Bottom-follow and
 // prepend anchoring always target the resolved scrollport.
 //
-// Render economics (architecture RFC performance model): the list parent
-// subscribes to snapshot segments that do NOT change per streaming chunk
-// (nodes/runningCalls/pending keep their references across chunk batches), so
-// during a token storm only StreamingTail re-renders; history rows hold via
-// memo on cache-stable node slices. Selection changes re-render the parent
-// map but only rows whose own selected bit flipped. renderSlot is
-// entry-identity-stable (framework binding cache), so passing it through
-// memoized rows never churns them.
+// Render economics: order changes only when rows enter, leave or move. Each
+// ChatNodeSeat subscribes to one Node key, so Assistant deltas and Tool
+// lifecycle updates replace only their own row without remounting it.
 
-import {
-  memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
-} from 'react'
-import type {
-  CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode,
-} from '@deepseek-ai/dsh-client-runtime/client'
-import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import type { ConversationTimelineSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
 import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps } from '../contract/slots.ts'
-import { assistantActionsSeqs, assistantBranchSeqs, deriveChatFlow, runningTurnStartTime, type ChatFlowItem } from './chat-flow.ts'
-import { AssistantMarkdown } from './AssistantMarkdown.tsx'
-import { CompactionCommandCard } from './CompactionCommandCard.tsx'
-import { GenericCommandCard } from './GenericCommandCard.tsx'
-import { MessageItem, PendingSteeringBubble } from './MessageItem.tsx'
+import { PendingSteeringBubble } from './MessageItem.tsx'
+import { ChatNodeSeat } from './ChatNodeSeat.tsx'
 import { formatRunDuration } from './message-chrome.ts'
-import { deriveTurnMetrics } from './turn-metrics.ts'
 import css from './ChatView.module.css'
 
 const FOLLOW_THRESHOLD = 24
@@ -98,35 +81,8 @@ function pagingAnchor(list: HTMLElement, scrollport: HTMLElement): HTMLElement |
   return visibleRows[0] ?? rows[0] ?? null
 }
 
-type OpenFile = (path: string) => void
-
-type InspectCall = (callId: string) => void
-
-/** Declared child-slot render share (stable framework binding). */
-type RenderChatSlot = ChatViewSlotProps['renderSlot']
-
 type ChatScrollPosition = NonNullable<ReturnType<ChatViewSlotProps['chatScroll']['read']>>
 
-/** ui-slots' UseSession is deliberately wide (dependency direction); the
- *  chat view narrows once to the runtime snapshot the binding actually feeds. */
-type UseConversation = SnapshotSelectorHook<ConversationSnapshot>
-
-function treeContainsCall(block: ToolCallBlock, callId: string | undefined): boolean {
-  return callId !== undefined
-    && (block.callId === callId || block.subCalls.some(child => treeContainsCall(child, callId)))
-}
-
-function activeRetrySeq(nodes: readonly ConversationNode[], running: boolean): number | null {
-  if (!running) return null
-  for (let index = nodes.length - 1; index >= 0; index -= 1) {
-    const node = nodes[index]
-    if (node === undefined) continue
-    if (node.kind === 'model-retry') return node.retryState === 'cancelled' ? null : node.seq
-    if (node.kind === 'assistant' || node.kind === 'user') return null
-  }
-  return null
-}
-
 /** Capture a reflow-resistant reader position from the current rendered window. */
 function scrollPosition(list: HTMLElement, scrollport: HTMLElement): ChatScrollPosition | null {
   const row = pagingAnchor(list, scrollport)
@@ -139,77 +95,13 @@ function scrollPosition(list: HTMLElement, scrollport: HTMLElement): ChatScrollP
   }
 }
 
-/** One ordered root Tool call handed intact to the Tool presentation plugin. */
-const ToolSeat = memo(function ToolSeat({
-  renderSlot, callId, toolName, block, openFile, selectedCallId, cwd, inspectCall,
-}: {
-  renderSlot: RenderChatSlot
-  callId: string
-  toolName: string
-  block: ToolResultNode | RunningToolCall
-  openFile: OpenFile
-  selectedCallId?: string | undefined
-  cwd: string | undefined
-  inspectCall: InspectCall
-}) {
-  const owner = useMemo(() => ({
-    callId, toolName, block, selectedCallId, cwd, openFile, inspectCall,
-  }), [callId, toolName, block, selectedCallId, cwd, openFile, inspectCall])
-  return renderSlot('conversation.chat.tool', owner)
-})
-
-/** Consecutive tool results as one step-run group (uniform 16px rhythm). */
-const ToolGroup = memo(function ToolGroup({ renderSlot, results, openFile, selectedCallId, cwd, inspectCall }: {
-  renderSlot: RenderChatSlot
-  results: readonly ToolResultNode[]
-  openFile: OpenFile
-  /** Tool ownership resolves whether the selection is this root or one of its children. */
-  selectedCallId: string | undefined
-  /** Session workspace root for path-relative summaries. */
-  cwd: string | undefined
-  inspectCall: InspectCall
-}) {
-  return (
-    <div className={css.toolGroup}>
-      {results.map(node => (
-        <ToolSeat
-          key={node.callId}
-          renderSlot={renderSlot}
-          callId={node.callId}
-          toolName={node.call?.name ?? ''}
-          block={node}
-          openFile={openFile}
-          selectedCallId={treeContainsCall(node, selectedCallId) ? selectedCallId : undefined}
-          cwd={cwd}
-          inspectCall={inspectCall}
-        />
-      ))}
-    </div>
-  )
-})
-
-/** One command lifecycle row: keyed dispatch on the command name with the
- *  generic card as the render-site fallback (zero registration required). A
- *  run-less cross-window node has no name and always lands on the fallback. */
-const CommandRow = memo(function CommandRow({ renderSlot, node, compaction, t }: {
-  renderSlot: RenderChatSlot
-  node: CommandNode
-  compaction?: Extract<ConversationNode, { kind: 'compaction' }>
-  t: ChatViewSlotProps['t']
-}) {
-  const owner = useMemo(() => ({ node, ...compaction === undefined ? {} : { compaction } }), [compaction, node])
-  const fallback = node.name === 'compact'
-    ? <CompactionCommandCard {...owner} t={t} />
-    : <GenericCommandCard {...owner} t={t} />
-  return (
-    <div className={css.callRow}>
-      {renderSlot('conversation.chat.commandview', owner, {
-        entryKey: node.name ?? '',
-        fallback,
-      })}
-    </div>
-  )
-})
+function runningTurnStartTime(timeline: ConversationTimelineSnapshot): number | null {
+  let latest: number | null = null
+  for (const turn of timeline.turns.values()) {
+    if (turn.status === 'open' && turn.start !== undefined) latest = turn.start.time
+  }
+  return latest
+}
 
 /** Turn-level model activity label retained across first-token, tool, and streaming phases. */
 function TurnStatus({ startTime, t }: {
@@ -247,52 +139,32 @@ function TurnStatus({ startTime, t }: {
   )
 }
 
-/** The streaming partial, isolated so chunk batches re-render only this tail;
- *  the column ResizeObserver owns bottom-follow when its box grows. */
-function StreamingTail({ useSession, t }: {
-  useSession: UseConversation
-  t: ChatViewSlotProps['t']
-}) {
-  const partial = useSession(s => s.partial)
-  if (partial === null) return null
-  return <AssistantMarkdown blocks={partial.blocks} streaming t={t} />
-}
-
 /**
  * The chat view slot entry: pure component over the composed props; each
- * ordered root Tool call crosses the declared whole-Tool render seat.
+ * ordered business Node crosses the keyed renderer seat.
  */
 export function ChatView({
-  useSession, useSessions, useStore, renderSlot, renderSlotChain, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt,
+  useSession, useSessions, useStore, renderSlot, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt,
   fileMentions, t,
 }: ChatViewSlotProps) {
-  const nodes = useSession(s => s.nodes)
-  const turnTimings = useSession(s => s.turnTimings)
-  const turnEnds = useSession(s => s.turnEnds)
+  const order = useSession(s => s.chat.order)
+  const nodeStore = useSession(s => s.chat.nodes)
+  const timeline = useSession(s => s.chat.timeline)
   const inbox = useSession(s => s.queue)
   // Workspace root off the session list row: path summaries display relative to it.
   const cwd = useSessions(s => s.byId[sessionId]?.cwd)
   const running = useSession(s => s.running)
-  const runningCalls = useSession(s => s.runningCalls)
   const openState = useSession(s => s.openState)
   const openError = useSession(s => s.openError)
   const hasMore = useSession(s => s.hasMore)
   const loadingOlder = useSession(s => s.loadingOlder)
   const selectedCallId = useStore(s => s.selection?.callId)
 
-  const items = useMemo(() => deriveChatFlow(nodes), [nodes])
   const pendingSteering = useMemo(
     () => inbox.filter(item => item.placement === 'steering'),
     [inbox],
   )
-  const activeRetry = useMemo(() => activeRetrySeq(nodes, running), [nodes, running])
-  // Only the last content assistant of each completed turn owns IconActions;
-  // mid-turn text and every node of a running turn omit `time`, so
-  // AssistantMarkdown stays chrome-free until the answer settles.
-  const actionSeqs = useMemo(() => assistantActionsSeqs(nodes, turnEnds), [nodes, turnEnds])
-  const branchSeqs = useMemo(() => assistantBranchSeqs(nodes, turnEnds), [nodes, turnEnds])
-  const runningTurnStart = useMemo(() => runningTurnStartTime(turnTimings), [turnTimings])
-  const turnMetrics = useMemo(() => deriveTurnMetrics(nodes), [nodes])
+  const runningTurnStart = useMemo(() => runningTurnStartTime(timeline), [timeline])
 
   const listRef = useRef<HTMLDivElement | null>(null)
   const columnRef = useRef<HTMLDivElement | null>(null)
@@ -312,11 +184,12 @@ export function ChatView({
    *  scrolls the rest of the way to the floor). */
   const followSigRef = useRef<string | null>(null)
 
-  const firstSeq = nodes[0]?.seq ?? null
-  const lastItem = items[items.length - 1]
-  const lastKey = lastItem?.key ?? null
+  const firstKey = order[0]
+  const firstSeq = firstKey === undefined ? null : nodeStore.get(firstKey)?.anchorSeq ?? null
+  const lastKey = order.at(-1) ?? null
+  const lastNode = lastKey === null ? undefined : nodeStore.get(lastKey)
   const lastSteeringId = pendingSteering[pendingSteering.length - 1]?.id ?? null
-  const followSig = `${openState}:${firstSeq}:${lastKey}:${nodes.length}:${running ? 1 : 0}:${runningCalls.length}:${lastSteeringId ?? ''}`
+  const followSig = `${openState}:${firstSeq}:${lastKey}:${order.length}:${running ? 1 : 0}:${lastSteeringId ?? ''}`
 
   const toBottom = (el: HTMLElement): void => {
     anchorRef.current = null
@@ -377,8 +250,7 @@ export function ChatView({
     firstSeqRef.current = firstSeq
     // Own words must be visible: a new trailing user node force-scrolls
     // (send lives in the composer, so arrival is detected here, not armed there).
-    const appendedUser = lastKey !== lastKeyRef.current
-      && lastItem !== undefined && lastItem.kind === 'node' && lastItem.node.kind === 'user'
+    const appendedUser = lastKey !== lastKeyRef.current && lastNode?.kind === 'user'
     const appendedSteering = lastSteeringId !== null && lastSteeringId !== lastSteeringIdRef.current
     const tipMoved = followSigRef.current !== followSig
     lastKeyRef.current = lastKey
@@ -490,71 +362,6 @@ export function ChatView({
     loadOlder()
   }
 
-  const renderItem = (item: ChatFlowItem): ReactNode => {
-    if (item.kind === 'tool-group') {
-      return (
-        <ToolGroup
-          renderSlot={renderSlot}
-          results={item.results}
-          openFile={openFile}
-          selectedCallId={selectedCallId}
-          cwd={cwd}
-          inspectCall={inspectCall}
-        />
-      )
-    }
-    if (item.kind === 'command-compaction') {
-      return (
-        <CommandRow
-          renderSlot={renderSlot}
-          node={item.command}
-          compaction={item.compaction}
-          t={t}
-        />
-      )
-    }
-    const node: ConversationNode = item.node
-    if (node.kind === 'assistant') {
-      const timing = actionSeqs.has(node.seq) ? turnTimings.get(node.turn) : undefined
-      // Metrics gate on the settled in-window timing: turn/start loaded means
-      // every step of the turn is loaded, so first-step TTFT is genuine.
-      const metrics = timing?.endTime === undefined ? undefined : turnMetrics.get(node.turn)
-      return (
-        <AssistantMarkdown
-          blocks={node.blocks}
-          streaming={false}
-          interrupted={node.interrupted}
-          time={actionSeqs.has(node.seq) ? node.time : undefined}
-          runMs={timing?.endTime === undefined
-            ? undefined
-            : Math.max(0, timing.endTime - timing.startTime)}
-          ttftMs={metrics?.ttftMs}
-          tokensPerSecond={metrics?.tokensPerSecond}
-          seq={node.seq}
-          onFork={forkAt}
-          forkUnavailable={!branchSeqs.has(node.seq)}
-          turnTail={actionSeqs.has(node.seq)
-            ? { renderSlotChain, owner: { nodes, seq: node.seq, openFile } }
-            : undefined}
-          fileMentions={actionSeqs.has(node.seq) ? fileMentions : undefined}
-          t={t}
-        />
-      )
-    }
-    if (node.kind === 'command') {
-      return <CommandRow renderSlot={renderSlot} node={node} t={t} />
-    }
-    /* v8 ignore next -- tool-result never reaches here: deriveChatFlow folds them into groups. */
-    if (node.kind === 'tool-result') return null
-    return (
-      <MessageItem
-        node={node}
-        retryActive={node.kind === 'model-retry' && node.seq === activeRetry}
-        t={t}
-      />
-    )
-  }
-
   return (
     <div className={css.root}>
       <div ref={listRef} className={css.scroll}>
@@ -572,43 +379,21 @@ export function ChatView({
               </button>
             </div>
           )}
-          {items.map(item => (
-            <div
-              key={item.key}
-              className={css.flowItem}
-              data-chat-anchor-key={item.kind === 'node'
-                ? `node:${String(item.node.seq)}`
-                : item.kind === 'command-compaction'
-                  ? `node:${String(item.compaction.seq)}`
-                  : undefined}
-              data-chat-flow-key={item.key}
-              data-chat-flow-kind={item.kind === 'node'
-                ? item.node.kind
-                : item.kind === 'command-compaction'
-                  ? item.kind
-                  : 'tool-group'}
-            >
-              {renderItem(item)}
-            </div>
+          {order.map(nodeKey => (
+            <ChatNodeSeat
+              key={nodeKey}
+              nodeKey={nodeKey}
+              useSession={useSession}
+              selectedCallId={selectedCallId}
+              cwd={cwd}
+              openFile={openFile}
+              inspectCall={inspectCall}
+              forkAt={forkAt}
+              fileMentions={fileMentions}
+              renderSlot={renderSlot}
+              t={t}
+            />
           ))}
-          <StreamingTail useSession={useSession} t={t} />
-          {runningCalls.length > 0 && (
-            <div className={css.toolGroup}>
-              {runningCalls.map(call => (
-                <ToolSeat
-                  key={call.callId}
-                  renderSlot={renderSlot}
-                  callId={call.callId}
-                  toolName={call.name}
-                  block={call}
-                  openFile={openFile}
-                  selectedCallId={treeContainsCall(call, selectedCallId) ? selectedCallId : undefined}
-                  cwd={cwd}
-                  inspectCall={inspectCall}
-                />
-              ))}
-            </div>
-          )}
           {/* No pending placeholders: questions (ui-question) and approvals
               (ApprovalPanel) both take over the composer, so a flow card would
               double-render the same wait. */}
diff --git a/packages/client/ui-conversation/src/client/chat/CommandNodeView.tsx b/packages/client/ui-conversation/src/client/chat/CommandNodeView.tsx
new file mode 100644
index 0000000000..a1fc9f197a
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/CommandNodeView.tsx
@@ -0,0 +1,40 @@
+import { memo, useMemo } from 'react'
+import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import type {
+  ChatNodeViewProps, CommandRowOwnerProps,
+} from '../contract/slots.ts'
+import { CompactionCommandCard } from './CompactionCommandCard.tsx'
+import { GenericCommandCard } from './GenericCommandCard.tsx'
+import css from './ChatView.module.css'
+
+type CommandNodeViewProps = ChatNodeViewProps<'command'> & PropsRenderSlots<'conversation.chat.commandview'>
+
+/** Ordinary command lifecycle renderer with command-name keyed specialization. */
+export const CommandNodeView = memo(function CommandNodeView({ node, renderSlot, t }: CommandNodeViewProps) {
+  const command = node.data
+  const owner = useMemo<CommandRowOwnerProps>(() => ({ node: command }), [command])
+  return (
+    <div className={css.callRow}>
+      {renderSlot('conversation.chat.commandview', owner, {
+        entryKey: command.name ?? '',
+        fallback: <GenericCommandCard {...owner} t={t} />,
+      })}
+    </div>
+  )
+})
+
+/** One integrated `/compact` command and compaction transaction renderer. */
+export const ManualCompactionNodeView = memo(function ManualCompactionNodeView({
+  node, t,
+}: ChatNodeViewProps<'manual-compaction'>) {
+  const data = node.data
+  return (
+    <div className={css.callRow}>
+      <CompactionCommandCard
+        node={data.command}
+        {...data.compaction === null ? {} : { compaction: data.compaction }}
+        t={t}
+      />
+    </div>
+  )
+})
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
index 30b51b3870..972fba8710 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
@@ -7,30 +7,15 @@
 import { memo, useEffect, useMemo, useState } from 'react'
 import type { ReactNode } from 'react'
 import type {
-  CompactionSummaryNode, ContextMessageNode, ModelRetryNode, SteeringMessageNode,
-  TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
+  ModelRetryNode, TurnErrorNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { JsonBlock, MessageText, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatNodeViewProps, ChatViewSlotProps } from '../contract/slots.ts'
 import { CompactionItem } from './CompactionItem.tsx'
 import { ContextInjectionRow } from './ContextInjectionRow.tsx'
 import { MessageIconActions } from './MessageIconActions.tsx'
 import css from './MessageItem.module.css'
 
-export interface MessageItemProps {
-  node:
-    | UserMessageNode
-    | SteeringMessageNode
-    | ContextMessageNode
-    | CompactionSummaryNode
-    | ModelRetryNode
-    | TurnErrorNode
-    | UnknownSurfaceNode
-  retryActive?: boolean
-  /** The owning view's locale seat, passed down as a plain prop. */
-  t: ChatViewSlotProps['t']
-}
-
 function contentText(content: readonly unknown[]): { text: string; rest: unknown[] } {
   const texts: string[] = []
   const rest: unknown[] = []
@@ -219,50 +204,69 @@ export function PendingSteeringBubble({ content, t }: {
   )
 }
 
-export const MessageItem = memo(function MessageItem({
-  node, retryActive = false, t,
-}: MessageItemProps) {
-  const truncated = (total: number): string => t('json.truncated', { total })
-  switch (node.kind) {
-    case 'user':
-    case 'steering':
-      return (
-        <UserStyleBubble
-          content={node.content}
-          steering={node.kind === 'steering'}
-          t={t}
-          actions={text => (
-            <MessageIconActions
-              text={text}
-              time={node.time}
-              clock="start"
-              className={css.actions}
-              t={t}
-            />
-          )}
-        />
-      )
-    case 'context':
-      return (
-        <ContextInjectionRow
-          content={node.content}
-          source={node.source}
-          provenance={node.provenance}
-          form={node.form}
+/** User and admitted-steering keyed Chat renderer. */
+export const UserMessageNodeView = memo(function UserMessageNodeView({
+  node, t,
+}: ChatNodeViewProps<'user' | 'steering'>) {
+  const data = node.data
+  return (
+    <UserStyleBubble
+      content={data.content}
+      steering={data.kind === 'steering'}
+      t={t}
+      actions={text => (
+        <MessageIconActions
+          text={text}
+          time={data.time}
+          clock="start"
+          className={css.actions}
           t={t}
         />
-      )
-    case 'compaction':
-      return <CompactionItem node={node} t={t} />
-    case 'model-retry':
-      return <ModelRetryItem node={node} active={retryActive} t={t} />
-    case 'turn-error':
-      return <TurnErrorItem node={node} t={t} />
-    default:
-      return (
-        <div className={css.contextRow}>
-          <JsonBlock label={t('message.unknownSurface', { type: node.type })} payload={node.data} truncatedLabel={truncated} />
-        </div>
-      )
-  }
+      )}
+    />
+  )
+})
+
+/** Injected-context keyed Chat renderer. */
+export const ContextMessageNodeView = memo(function ContextMessageNodeView({ node, t }: ChatNodeViewProps<'context'>) {
+  const data = node.data
+  return (
+    <ContextInjectionRow
+      content={data.content}
+      source={data.source}
+      provenance={data.provenance}
+      form={data.form}
+      t={t}
+    />
+  )
+})
+
+/** Automatic compaction keyed Chat renderer. */
+export const CompactionNodeView = memo(function CompactionNodeView({ node, t }: ChatNodeViewProps<'compaction'>) {
+  return <CompactionItem node={node.data} t={t} />
+})
+
+/** Correlated retry-chain keyed Chat renderer. */
+export const RetryNodeView = memo(function RetryNodeView({ node, t }: ChatNodeViewProps<'model-retry'>) {
+  const data = node.data
+  return <ModelRetryItem node={data.current} active={data.current.retryState === 'scheduled'} t={t} />
+})
+
+/** Terminal turn-error keyed Chat renderer. */
+export const TurnErrorNodeView = memo(function TurnErrorNodeView({ node, t }: ChatNodeViewProps<'turn-error'>) {
+  return <TurnErrorItem node={node.data} t={t} />
+})
+
+/** Explicit unknown-surface keyed Chat renderer. */
+export const UnknownNodeView = memo(function UnknownNodeView({ node, t }: ChatNodeViewProps<'unknown'>) {
+  const data = node.data
+  return (
+    <div className={css.contextRow}>
+      <JsonBlock
+        label={t('message.unknownSurface', { type: data.type })}
+        payload={data.data}
+        truncatedLabel={total => t('json.truncated', { total })}
+      />
+    </div>
+  )
 })
diff --git a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
index 8e672740cf..8e43f3c0b4 100644
--- a/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
+++ b/packages/client/ui-conversation/src/client/chat/StatsLine.tsx
@@ -157,9 +157,9 @@ export interface StatsLineProps {
 }
 
 export const StatsLine = memo(function StatsLine({ useSession, useProjection, t }: StatsLineProps) {
-  const nodes = useSession(s => s.nodes)
+  const settledNodes = useSession(s => s.chat.legacy.nodes)
+  const stats = useMemo(() => deriveStats(settledNodes), [settledNodes])
   const usage = useProjection('tokenUsage')
-  const stats = useMemo(() => deriveStats(nodes), [nodes])
   // Pipe-separated groups (figma stats strip); a group with no data drops out whole.
   const groups: string[] = []
   if (stats.steps > 0) {
diff --git a/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.module.css b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.module.css
new file mode 100644
index 0000000000..831e6e212b
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.module.css
@@ -0,0 +1,9 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.actions {
+  margin-left: -6px;
+}
diff --git a/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
new file mode 100644
index 0000000000..bf48fc75c6
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
@@ -0,0 +1,43 @@
+import { memo } from 'react'
+import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ChatNodeViewProps, TurnTailOwnerProps } from '../contract/slots.ts'
+import { MessageIconActions } from './MessageIconActions.tsx'
+import { assistantText } from './turn-assistant.ts'
+import css from './TurnTailNodeView.module.css'
+
+type TurnTailNodeViewProps = ChatNodeViewProps<'turn-tail'> & PropsRenderSlots<'conversation.chat.turnTail'>
+
+/** Turn-local actions and feature tail over the Location index, independent of Assistant placement. */
+export const TurnTailNodeView = memo(function TurnTailNodeView({
+  node, openFile, forkAt, renderSlotChain, t,
+}: TurnTailNodeViewProps) {
+  const data = node.data
+  const turn = node.location.kind === 'turn' || node.location.kind === 'step'
+    ? node.location.turn
+    : undefined
+  if (turn === undefined) return null
+  const closing = data.closing
+  const owner: TurnTailOwnerProps = { turn, seq: closing?.finalNode.seq ?? data.seq, openFile }
+  const tail = renderSlotChain('conversation.chat.turnTail', owner)
+  if (closing === null) return tail === null ? null : <div className={css.root}>{tail}</div>
+  const runMs = turn.start === undefined || turn.end === undefined
+    ? undefined
+    : Math.max(0, turn.end.time - turn.start.time)
+  return (
+    <div className={css.root} data-turn-tail={data.turn} data-time-hover-root>
+      {tail}
+      <MessageIconActions
+        text={assistantText(closing.blocks)}
+        time={closing.time}
+        runMs={runMs}
+        ttftMs={data.ttftMs}
+        tokensPerSecond={data.tokensPerSecond}
+        clock="end"
+        onBranch={() => { forkAt(closing.finalNode.seq) }}
+        branchUnavailable={data.branchUnavailable}
+        className={css.actions}
+        t={t}
+      />
+    </div>
+  )
+})
diff --git a/packages/client/ui-conversation/src/client/chat/chat-flow.ts b/packages/client/ui-conversation/src/client/chat/chat-flow.ts
deleted file mode 100644
index a9b12cbe2d..0000000000
--- a/packages/client/ui-conversation/src/client/chat/chat-flow.ts
+++ /dev/null
@@ -1,214 +0,0 @@
-/**
- * Chat flow derivation: ConversationSnapshot nodes -> render items. Tool
- * results group into consecutive-run tool groups (figma step-summary flow,
- * VERTICAL gap10) alternating with narration. Consecutive retry notices
- * reuse the first notice's row while projecting the latest retry turn.
- * Item identity keys are stable across snapshots so the list parent can
- * subscribe to keys only while rows subscribe to content. IconActions ownership
- * and completed-turn branch points are derived here too so ChatView and the
- * flow share their gates.
- */
-import type {
-  AssistantBlock, CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot, ToolResultNode,
-} from '@deepseek-ai/dsh-client-runtime/client'
-
-/** One renderable flow item; key is the React key and the parent's identity unit. */
-export type ChatFlowItem =
-  | { kind: 'node'; key: string; node: ConversationNode }
-  | { kind: 'tool-group'; key: string; results: readonly ToolResultNode[] }
-  | {
-    kind: 'command-compaction'
-    key: string
-    command: CommandNode
-    compaction: CompactionSummaryNode
-  }
-
-/** Match explicit command outcome references to exactly one compaction checkpoint. */
-function commandCompactionPairs(nodes: readonly ConversationNode[]): {
-  readonly byCommandId: ReadonlyMap<string, CompactionSummaryNode>
-  readonly byCompactionSeq: ReadonlyMap<number, CommandNode>
-} {
-  const commandsBySource = new Map<number, CommandNode | null>()
-  for (const node of nodes) {
-    if (node.kind !== 'command' || node.name !== 'compact' || node.outcome?.kind !== 'success') continue
-    const source = node.outcome.sourceEventSeq
-    if (source === undefined) continue
-    commandsBySource.set(source, commandsBySource.has(source) ? null : node)
-  }
-  const compactionsBySummary = new Map<number, CompactionSummaryNode | null>()
-  for (const node of nodes) {
-    if (node.kind !== 'compaction' || node.summaryEventSeq === null) continue
-    const summary = node.summaryEventSeq
-    compactionsBySummary.set(summary, compactionsBySummary.has(summary) ? null : node)
-  }
-  const byCommandId = new Map<string, CompactionSummaryNode>()
-  const byCompactionSeq = new Map<number, CommandNode>()
-  for (const [source, command] of commandsBySource) {
-    const compaction = compactionsBySummary.get(source)
-    if (command === null || compaction === undefined || compaction === null) continue
-    byCommandId.set(command.commandId, compaction)
-    byCompactionSeq.set(compaction.seq, command)
-  }
-  return { byCommandId, byCompactionSeq }
-}
-
-/**
- * True when the node has model-visible text content worth IconActions chrome.
- * Shared with {@link AssistantMarkdown}'s mount gate so ownership and mounting
- * cannot diverge.
- * @param blocks - assistant blocks of one finalized node.
- * @returns Whether any text block carries non-blank content.
- */
-export function hasContentText(blocks: readonly AssistantBlock[]): boolean {
-  return blocks.some(block => block.kind === 'text' && block.text.trim() !== '')
-}
-
-/** An assistant node that renders nothing: only tool-call heads (rows render
- *  via the grouping pass) and blank text/reasoning. Skipped by the flow so it
- *  neither costs column gaps nor splits a tool-row run. Interrupted nodes
- *  always render (the 已停止 marker). */
-function rendersNothing(node: ConversationNode): boolean {
-  return node.kind === 'assistant' && node.interrupted !== true
-    && node.blocks.every(b => b.kind === 'tool-call'
-      || ((b.kind === 'text' || b.kind === 'reasoning') && b.text.trim() === ''))
-}
-
-/**
- * Seq set of assistants that own IconActions: the last content-text assistant
- * of each *completed* turn. A turn without a `turn/end` in the window is still
- * producing steps, so its latest narration is not the settled answer and owns
- * nothing; mid-turn narration of a completed turn stays chrome-free too.
- * @param nodes - snapshot nodes (surface order).
- * @param turnEnds - completed turn boundaries retained from the event window.
- * @returns Seq values ChatView may pass as `time` into AssistantMarkdown.
- */
-export function assistantActionsSeqs(
-  nodes: readonly ConversationNode[],
-  turnEnds: ReadonlyMap<number, number>,
-): ReadonlySet<number> {
-  const lastByTurn = new Map<number, number>()
-  for (const node of nodes) {
-    if (node.kind !== 'assistant' || !turnEnds.has(node.turn) || !hasContentText(node.blocks)) continue
-    lastByTurn.set(node.turn, node.seq)
-  }
-  return new Set(lastByTurn.values())
-}
-
-/**
- * Exact start time of the latest in-window turn without a matching end time.
- * @param turnTimings - In-window turn timings in event order.
- * @returns Unix epoch ms, or null when the running turn started outside the window.
- */
-export function runningTurnStartTime(
-  turnTimings: ConversationSnapshot['turnTimings'],
-): number | null {
-  let latest: number | null = null
-  for (const timing of turnTimings.values()) {
-    if (timing.endTime === undefined) latest = timing.startTime
-  }
-  return latest
-}
-
-/**
- * Seq set of assistant answers that may fork: the completed turn's transcript
- * tail, when that tail is the turn's own content-text assistant. A later tool,
- * reasoning, error, or other transcript node leaves the answer's branch action
- * unavailable because the Host would include the whole turn. User and steering
- * bubbles carry no branch action at all: a fork at their seq cuts at the same
- * `turn/end` as the answer's, so the affordance lives only under the settled
- * answer.
- * @param nodes - snapshot nodes in event order.
- * @param turnEnds - completed turn boundaries retained from the event window.
- * @returns Assistant seq values whose visible position matches the fork boundary.
- */
-export function assistantBranchSeqs(
-  nodes: readonly ConversationNode[],
-  turnEnds: ReadonlyMap<number, number>,
-): ReadonlySet<number> {
-  const result = new Set<number>()
-  const boundaries = [...turnEnds].sort((a, b) => a[1] - b[1])
-  let nodeIndex = 0
-  for (const [turn, endSeq] of boundaries) {
-    let tail: ConversationNode | undefined
-    while (nodeIndex < nodes.length) {
-      const candidate = nodes[nodeIndex]
-      if (candidate === undefined || candidate.seq > endSeq) break
-      tail = candidate
-      nodeIndex++
-    }
-    if (tail?.kind === 'assistant' && tail.turn === turn && hasContentText(tail.blocks)) {
-      result.add(tail.seq)
-    }
-  }
-  return result
-}
-
-/**
- * Group finalized nodes into the step-summary flow.
- * @param nodes - snapshot nodes in human-transcript and durable-notice order.
- * @returns flow items; consecutive tool results group and retry notices reuse their first key.
- */
-export function deriveChatFlow(nodes: readonly ConversationNode[]): ChatFlowItem[] {
-  const items: ChatFlowItem[] = []
-  const pairs = commandCompactionPairs(nodes)
-  let group: ToolResultNode[] | null = null
-  for (const node of nodes) {
-    if (rendersNothing(node)) continue
-    if (node.kind === 'command' && pairs.byCommandId.has(node.commandId)) {
-      continue
-    }
-    if (node.kind === 'compaction') {
-      group = null
-      const command = pairs.byCompactionSeq.get(node.seq)
-      if (command !== undefined) {
-        items.push({
-          kind: 'command-compaction',
-          key: `c${command.commandId}`,
-          command,
-          compaction: node,
-        })
-      } else {
-        items.push({ kind: 'node', key: `n${node.seq}`, node })
-      }
-      continue
-    }
-    if (node.kind === 'tool-result') {
-      if (group === null) {
-        group = [node]
-        items.push({ kind: 'tool-group', key: `g${node.seq}`, results: group })
-      } else {
-        group.push(node)
-      }
-    } else if (node.kind === 'model-retry') {
-      group = null
-      const previous = items[items.length - 1]
-      if (
-        previous?.kind === 'node'
-        && previous.node.kind === 'model-retry'
-      ) {
-        items[items.length - 1] = { ...previous, node }
-      } else {
-        items.push({ kind: 'node', key: `n${node.seq}`, node })
-      }
-    } else {
-      group = null
-      items.push({
-        kind: 'node',
-        key: node.kind === 'command' && node.name === 'compact'
-          ? `c${node.commandId}`
-          : `n${node.seq}`,
-        node,
-      })
-    }
-  }
-  return items
-}
-
-/**
- * Key projection for the list parent's selector (content-blind identity).
- * @param items - derived flow items.
- * @returns joined key string usable with Object.is short-circuiting.
- */
-export function flowKeys(items: readonly ChatFlowItem[]): string {
-  return items.map(i => i.key).join('|')
-}
diff --git a/packages/client/ui-conversation/src/client/chat/register-node-renderers.ts b/packages/client/ui-conversation/src/client/chat/register-node-renderers.ts
new file mode 100644
index 0000000000..8926fc2a8e
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/register-node-renderers.ts
@@ -0,0 +1,46 @@
+import type { Context } from 'cordis'
+import { NS } from '../locales.ts'
+import { AssistantNodeView } from './AssistantNodeView.tsx'
+import { CommandNodeView, ManualCompactionNodeView } from './CommandNodeView.tsx'
+import {
+  CompactionNodeView, ContextMessageNodeView, RetryNodeView, TurnErrorNodeView,
+  UnknownNodeView, UserMessageNodeView,
+} from './MessageItem.tsx'
+import { TurnTailNodeView } from './TurnTailNodeView.tsx'
+
+/**
+ * Register this package's business renderers behind the keyed Chat Node seat.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerChatNodeRenderers(ctx: Context): void {
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'user', locale: NS }, UserMessageNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'steering', locale: NS }, UserMessageNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'context', locale: NS }, ContextMessageNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'assistant-step', locale: NS }, AssistantNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'command',
+    locale: NS,
+    children: { 'conversation.chat.commandview': { kind: 'keyed', scope: 'session' } },
+  }, CommandNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'manual-compaction', locale: NS }, ManualCompactionNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'compaction', locale: NS }, CompactionNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'model-retry', locale: NS }, RetryNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'turn-error', locale: NS }, TurnErrorNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'turn-tail',
+    locale: NS,
+    children: { 'conversation.chat.turnTail': { kind: 'chain', scope: 'session' } },
+  }, TurnTailNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
+    { name: 'conversation.chat.node', key: 'unknown', locale: NS }, UnknownNodeView))
+}
diff --git a/packages/client/ui-conversation/src/client/chat/tool-node-reader.ts b/packages/client/ui-conversation/src/client/chat/tool-node-reader.ts
new file mode 100644
index 0000000000..dca9992b8d
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/tool-node-reader.ts
@@ -0,0 +1,46 @@
+import type {
+  ConversationSnapshot, ToolCallBlock,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { conversationContextKey } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ChatNode } from '../contract/chat-nodes.ts'
+
+function toolNode(node: ReturnType<ConversationSnapshot['chat']['nodes']['get']>): ChatNode<'tool-call'> | undefined {
+  return node?.kind === 'tool-call' ? node as ChatNode<'tool-call'> : undefined
+}
+
+/**
+ * Read one root Tool lifecycle through the internal Chat Node index.
+ * @param snapshot - current Conversation snapshot.
+ * @param rootCallId - root call identity and Tool Context identity.
+ * @returns root lifecycle when it is materialized in the current window.
+ */
+export function rootToolCall(
+  snapshot: ConversationSnapshot,
+  rootCallId: string,
+): ToolCallBlock | undefined {
+  return toolNode(snapshot.chat.nodes.get(conversationContextKey('tool-call', rootCallId)))?.data.root
+}
+
+/**
+ * Find any root or nested Tool lifecycle through the internal Node store.
+ * @param snapshot - current Conversation snapshot.
+ * @param callId - root or nested call identity.
+ * @returns current Tool lifecycle when materialized in the loaded window.
+ */
+export function findToolCall(snapshot: ConversationSnapshot, callId: string): ToolCallBlock | undefined {
+  const visit = (block: ToolCallBlock): ToolCallBlock | undefined => {
+    if (block.callId === callId) return block
+    for (const child of block.subCalls) {
+      const found = visit(child)
+      if (found !== undefined) return found
+    }
+    return undefined
+  }
+  for (const node of snapshot.chat.nodes.values()) {
+    const root = toolNode(node)?.data.root
+    if (root === undefined) continue
+    const found = visit(root)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
diff --git a/packages/client/ui-conversation/src/client/chat/turn-assistant.ts b/packages/client/ui-conversation/src/client/chat/turn-assistant.ts
new file mode 100644
index 0000000000..2abfff56b3
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/chat/turn-assistant.ts
@@ -0,0 +1,10 @@
+import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
+
+/**
+ * Collect visible prose from one Assistant lifecycle.
+ * @param blocks - Assistant content blocks.
+ * @returns concatenated text blocks.
+ */
+export function assistantText(blocks: readonly AssistantBlock[]): string {
+  return blocks.flatMap(block => block.kind === 'text' ? [block.text] : []).join('')
+}
diff --git a/packages/client/ui-conversation/src/client/chat/turn-metrics.ts b/packages/client/ui-conversation/src/client/chat/turn-metrics.ts
index b7cc5ddb72..b93bbfc8eb 100644
--- a/packages/client/ui-conversation/src/client/chat/turn-metrics.ts
+++ b/packages/client/ui-conversation/src/client/chat/turn-metrics.ts
@@ -1,6 +1,6 @@
 // Latency/throughput folds shared by the settled turn footer and StatsLine.
 
-import type { ConversationSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+import type { AssistantMessageNode, ConversationNode } from '@deepseek-ai/dsh-client-runtime/client'
 
 /** Latency and decode-throughput readings for one turn's footer. */
 export interface TurnMetrics {
@@ -24,7 +24,7 @@ interface UsageLike {
   outputTokens?: number
 }
 
-type AssistantNode = Extract<ConversationSnapshot['nodes'][number], { kind: 'assistant' }>
+type AssistantNode = AssistantMessageNode
 
 function usageOutputTokens(usage: unknown): number | null {
   if (typeof usage !== 'object' || usage === null) return null
@@ -67,7 +67,7 @@ interface TurnFold {
  * @param nodes - Snapshot nodes of the loaded window.
  * @returns Turn number → available metrics; turns with none are absent.
  */
-export function deriveTurnMetrics(nodes: ConversationSnapshot['nodes']): Map<number, TurnMetrics> {
+export function deriveTurnMetrics(nodes: readonly ConversationNode[]): Map<number, TurnMetrics> {
   const folds = new Map<number, TurnFold>()
   for (const node of nodes) {
     if (node.kind !== 'assistant') continue
diff --git a/packages/client/ui-conversation/src/client/contract/chat-nodes.ts b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
new file mode 100644
index 0000000000..3415c502a5
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
@@ -0,0 +1,82 @@
+import type {
+  AssistantBlock, AssistantMessageNode, ChatConversationViewNode, CommandNode,
+  CompactionSummaryNode, ModelRetryNode, RunningToolCall, ToolCallBlock,
+} from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Merge-extensible payload registry keyed by final Chat renderer kind. */
+export interface ChatNodeDataMap {}
+
+/** Renderer kinds contributed by the currently installed Chat business modules. */
+export type ChatNodeKind = keyof ChatNodeDataMap & string
+
+/** Final Chat Node narrowed to one registered renderer kind and payload. */
+export type ChatNode<Kind extends ChatNodeKind = ChatNodeKind> = {
+  [RegisteredKind in Kind]: ChatConversationViewNode & {
+    readonly kind: RegisteredKind
+    readonly data: ChatNodeDataMap[RegisteredKind]
+  }
+}[Kind]
+
+/** Final Assistant row payload shared by streaming and settled states. */
+export interface AssistantChatData {
+  readonly status: 'running' | 'settled' | 'interrupted'
+  readonly turn: number
+  readonly step: number
+  readonly blocks: readonly AssistantBlock[]
+  readonly time: number
+  readonly usage?: unknown
+  readonly finalNode?: AssistantMessageNode
+}
+
+/** Settled or interrupted Assistant payload with its durable presentation node. */
+export type FinalAssistantChatData = AssistantChatData & {
+  readonly finalNode: AssistantMessageNode
+}
+
+/** Root Tool row payload; the root lifecycle owns all recursive subcalls. */
+export interface ToolChatData {
+  readonly root: ToolCallBlock
+}
+
+/** One manual command and its correlated compaction transaction. */
+export interface ManualCompactionChatData {
+  readonly command: CommandNode
+  readonly compaction: CompactionSummaryNode | null
+}
+
+/** One durable retry chain rendered as a single row. */
+export interface RetryChatData {
+  readonly attempts: readonly ModelRetryNode[]
+  readonly current: ModelRetryNode
+}
+
+/** Turn-local footer row that owns actions and optional feature contributions. */
+export interface TurnTailChatData {
+  readonly turn: number
+  readonly seq: number
+  readonly time: number
+  /** Last finalized content-bearing Assistant in this Turn. */
+  readonly closing: FinalAssistantChatData | null
+  /** Whether later Assistant/Step material makes the closing seq non-tail. */
+  readonly branchUnavailable: boolean
+  readonly ttftMs?: number
+  readonly tokensPerSecond?: number
+}
+
+/**
+ * Test whether a Tool root has settled.
+ * @param block - Tool root lifecycle value.
+ * @returns whether the root carries its final result.
+ */
+export function isSettledTool(block: ToolCallBlock): block is Extract<ToolCallBlock, { kind: 'tool-result' }> {
+  return 'kind' in block
+}
+
+/**
+ * Test whether a Tool root is still running.
+ * @param block - Tool root lifecycle value.
+ * @returns whether the root lacks a final result.
+ */
+export function isRunningTool(block: ToolCallBlock): block is RunningToolCall {
+  return !isSettledTool(block)
+}
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index a57bcbd5a7..474e7f9db5 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -1,15 +1,21 @@
 /** Conversation slot declarations and their composed component props. */
 import type { ReactNode, RefObject } from 'react'
 import type {
-  InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook,
+  InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore,
+  SlotHookFactory, SnapshotSelectorHook,
 } from '@deepseek-ai/dsh-client-ui-slots'
-import type { CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  CommandNode, CompactionSummaryNode, ConversationSnapshot, ConversationTurnDataMap,
+  ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock,
+  TurnLocation, WorkspaceId,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { ComposerBlock } from '../input/blocks.ts'
 import type { ComposerKeyboard, EditSelection, InputActions, InputNotice, InputState } from '../input/contract.ts'
 import type { createChatStore } from '../stores.ts'
 import type { ComposerSubmitGesture, InputSubmitMode } from './composer-submission.ts'
+import type { ChatNode, ChatNodeKind } from './chat-nodes.ts'
 import type { CallId, SelectionTarget, ViewTab } from './views.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
@@ -31,13 +37,15 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * conversation snapshot through the standard kit.
      */
     'conversation.view': { kind: 'list'; scope: 'session'; owner: ConvViewOwnerProps }
-    /**
-     * One root Tool call at its ordered ChatFlow position. The chat view owns
-     * placement; ui-tool owns root/subcall composition and keyed dispatch.
-     * The filler preserves the call-anchor DOM contract documented by
-     * {@link ToolTreeOwnerProps} for every root and child wrapper.
-     */
-    'conversation.chat.tool': { kind: 'single'; scope: 'session'; owner: ToolTreeOwnerProps }
+    /** Final business node renderer, dispatched by `ChatConversationViewNode.kind`. */
+    'conversation.chat.node': {
+      kind: 'keyed'
+      scope: 'session'
+      owner: ChatNodeOwnerProps
+      keyProps: { [Kind in ChatNodeKind]: { node: ChatNode<Kind> } }
+      hookContext: string
+      inject: ChatNodeTurnDataInjected
+    }
     /**
      * The chat view's per-command row hole: keyed dispatch on the command
      * name (`command/run.name`; a run-less cross-window node has none and
@@ -171,7 +179,7 @@ export interface ConvViewOwnerProps {
 export interface ChatFileMentions {
   /**
    * Mention vocabulary for the closing message the owner currency names.
-   * @param owner - Turn-tail owner currency (nodes, closing seq, opener).
+   * @param owner - Turn-tail owner currency (Turn data, closing seq, opener).
    * @returns The resolver MarkdownText consumes, or undefined when the turn
    * produced nothing worth linking.
    */
@@ -186,14 +194,13 @@ declare module 'cordis' {
 }
 
 /**
- * Owner currency of the chat view's turn-tail hole: the finalized snapshot
- * and the closing assistant's anchor. Registrants derive their own facts
- * from the nodes (the owner never pre-chews a feature's vocabulary), and
- * open files through the same opener the tool rows use.
+ * Owner currency of the chat view's turn-tail hole: the engine-owned Turn and
+ * the closing assistant's anchor. Registrants read their own typed Turn data
+ * and open files through the same opener the tool rows use.
  */
 export interface TurnTailOwnerProps {
-  /** Finalized snapshot nodes in surface order. */
-  nodes: readonly ConversationNode[]
+  /** Engine-owned closing Turn boundary. */
+  turn: TurnLocation
   /** The closing assistant's seq — the anchor the tail renders under. */
   seq: number
   /**
@@ -203,34 +210,34 @@ export interface TurnTailOwnerProps {
   openFile: (path: string) => void
 }
 
-/**
- * Owner currency of the chat view's whole-Tool rendering seat. The filler
- * wraps every rendered root and child with `data-chat-anchor-key="call:<id>"`
- * and `data-chat-call-id="<id>"`, plus `data-selected="true"` for the selected
- * call. ChatView consumes those anchors to restore prepend/paging position.
- */
-export interface ToolTreeOwnerProps {
-  /** Root Tool call identity, stable across running → settled. */
-  callId: CallId
-  /** Root wire Tool name. */
-  toolName: string
-  /** Frozen root call slice: running call or settled result node. */
-  block: ToolCallBlock
-  /** Selected call id; the Tool owner resolves whether it is root or child. */
-  selectedCallId?: CallId | undefined
-  /** Session workspace root; path summaries display relative to it. */
-  cwd?: string | undefined
-  /**
-   * Open a tool-arg filesystem path with the host OS default application.
-   * The conversation owner resolves relative paths against the session cwd.
-   */
-  openFile: (path: string) => void
-  /**
-   * Jump to any call in this tree in the trajectory view.
-   */
-  inspectCall: (callId: CallId) => void
+/** Hook constrained to business data published on the current Chat Node's Turn. */
+export type UseChatNodeTurnData = <Key extends keyof ConversationTurnDataMap & string>(
+  key: Key,
+) => Readonly<ConversationTurnDataMap[Key]> | undefined
+
+/** Slot-level Hook factory used by renderers reading their Node's Turn data. */
+export interface ChatNodeTurnDataInjected {
+  hooks: {
+    turnData: SlotHookFactory<'conversation.chat.node', UseChatNodeTurnData>
+  }
 }
 
+/** Stable owner currency delivered to one keyed Chat business renderer. */
+export interface ChatNodeOwnerProps {
+  /** Selected Tool call, when the shared details store names one. */
+  selectedCallId?: CallId | undefined
+  /** Session workspace root; Tool summaries display paths relative to it. */
+  cwd?: string | undefined
+  openFile: (path: string) => void
+  inspectCall: (callId: CallId) => void
+  forkAt: (seq: number) => void
+  fileMentions: (owner: TurnTailOwnerProps) => MarkdownFileMentions | undefined
+}
+
+/** Full props of one registered keyed Chat business renderer. */
+export type ChatNodeViewProps<Kind extends ChatNodeKind = ChatNodeKind> =
+  PropsRuntime<'conversation.chat.node', Kind> & PropsLocale<'conversation'>
+
 /** Owner currency of the details panel's Tool output renderer. */
 export interface DetailsToolOwnerProps {
   /** Frozen selected call slice. */
@@ -555,7 +562,7 @@ export interface ChatViewInjected {
 
 /** Full chat-view component props: runtime & its Tool/command/tail render shares & store & injected & locale seat. */
 export type ChatViewSlotProps =
-  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.tool' | 'conversation.chat.commandview' | 'conversation.chat.turnTail'>
+  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.node'>
   & PropsStore<ChatStore> & ChatViewInjected & PropsLocale<'conversation'>
 
 /**
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
new file mode 100644
index 0000000000..2bdf960226
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
@@ -0,0 +1,316 @@
+import type { Context } from 'cordis'
+import type {
+  AssistantBlock, AssistantMessageNode, ConversationLocation, ConversationMatch,
+  ConversationNodeContext, ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  emptyAssistantBlock, isAppendSurfaceEvent, isTokenDelta, toAssistantBlock, toAssistantBlocks,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { AssistantChatData } from '../contract/chat-nodes.ts'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Streaming, settled, or interrupted Assistant step. */
+    'assistant-step': AssistantChatData
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationStepDataMap {
+    /** Streaming, settled, or interrupted Assistant material for this Step. */
+    'assistant-step': AssistantChatData
+  }
+}
+
+interface AssistantState {
+  readonly turn: number
+  readonly step: number
+  readonly blocks: readonly (AssistantBlock | undefined)[]
+  readonly firstVisibleSeq: number | undefined
+  readonly firstVisibleTime: number | undefined
+  readonly firstTokenTime: number | undefined
+  readonly hidden: boolean
+  readonly final: ConversationMatch | undefined
+  readonly usage: unknown
+}
+
+function initialState(turn: number, step: number): AssistantState {
+  return {
+    turn,
+    step,
+    blocks: [],
+    firstVisibleSeq: undefined,
+    firstVisibleTime: undefined,
+    firstTokenTime: undefined,
+    hidden: false,
+    final: undefined,
+    usage: undefined,
+  }
+}
+
+function compactBlocks(blocks: readonly (AssistantBlock | undefined)[]): AssistantBlock[] {
+  return blocks.filter((block): block is AssistantBlock => block !== undefined)
+}
+
+function hasVisibleContent(blocks: readonly AssistantBlock[]): boolean {
+  return blocks.some((block) => {
+    if (block.kind === 'tool-call') return false
+    if (block.kind === 'text' || block.kind === 'reasoning') return block.text.trim() !== ''
+    return true
+  })
+}
+
+function hasInterruptionEvidence(blocks: readonly AssistantBlock[]): boolean {
+  return blocks.some((block) => {
+    if (block.kind === 'text' || block.kind === 'reasoning') return block.text.trim() !== ''
+    return true
+  })
+}
+
+function resetForRetry(state: AssistantState): AssistantState {
+  return {
+    ...initialState(state.turn, state.step),
+    firstTokenTime: state.firstTokenTime,
+    hidden: true,
+  }
+}
+
+function updateChunk(state: AssistantState, match: ConversationMatch): AssistantState {
+  if (match.event.type !== 'assistant/chunk') return state
+  const chunk = match.event.data.chunk
+  const blocks = [...state.blocks]
+  switch (chunk.type) {
+    case 'block-start':
+      blocks[chunk.index] = emptyAssistantBlock(chunk.blockType)
+      break
+    case 'text-delta': {
+      const previous = blocks[chunk.index]
+      blocks[chunk.index] = { kind: 'text', text: (previous?.kind === 'text' ? previous.text : '') + chunk.text }
+      break
+    }
+    case 'reasoning-delta': {
+      const previous = blocks[chunk.index]
+      blocks[chunk.index] = { kind: 'reasoning', text: (previous?.kind === 'reasoning' ? previous.text : '') + chunk.text }
+      break
+    }
+    case 'tool-call-delta': {
+      const previous = blocks[chunk.index]
+      const base = previous?.kind === 'tool-call'
+        ? previous
+        : { kind: 'tool-call' as const, callId: '', name: '', argsRaw: '' }
+      blocks[chunk.index] = {
+        kind: 'tool-call',
+        callId: base.callId || String(chunk.id),
+        name: chunk.name ?? base.name,
+        argsRaw: base.argsRaw + chunk.argumentsDelta,
+      }
+      break
+    }
+    case 'block-end':
+      blocks[chunk.index] = toAssistantBlock(chunk.block)
+      break
+    case 'usage':
+      return { ...state, usage: chunk.usage }
+    default:
+      return state
+  }
+  const visible = hasVisibleContent(compactBlocks(blocks))
+  const firstToken = isTokenDelta(chunk)
+  return {
+    ...state,
+    blocks,
+    hidden: visible ? false : state.hidden,
+    ...visible && state.firstVisibleSeq === undefined
+      ? { firstVisibleSeq: match.event.seq, firstVisibleTime: match.event.time }
+      : {},
+    ...firstToken && state.firstTokenTime === undefined
+      ? { firstTokenTime: match.event.time }
+      : {},
+  }
+}
+
+function closedBoundary(location: ConversationLocation): { seq: number; time: number } | undefined {
+  if (location.kind === 'step' && location.step.status === 'closed' && location.step.end !== undefined) {
+    return location.step.end
+  }
+  if ((location.kind === 'step' || location.kind === 'turn')
+    && location.turn.status === 'closed' && location.turn.end !== undefined) {
+    return location.turn.end
+  }
+  return undefined
+}
+
+function finalNode(
+  state: AssistantState,
+  context: ConversationNodeContext<AssistantState>,
+): AssistantMessageNode | undefined {
+  const final = state.final
+  if (final?.event.type === 'assistant/message') {
+    const event = final.event
+    return {
+      kind: 'assistant',
+      seq: event.seq,
+      time: event.time,
+      turn: state.turn,
+      step: state.step,
+      blocks: toAssistantBlocks(event.data.message.content),
+      usage: event.data.usage,
+      timing: {
+        stepStartTime: context.start?.event.time ?? null,
+        firstTokenTime: state.firstTokenTime ?? null,
+        completedTime: event.time,
+      },
+    }
+  }
+  const location = context.start?.location ?? context.matches.at(-1)?.location
+  const boundary = location === undefined ? undefined : closedBoundary(location)
+  const blocks = compactBlocks(state.blocks)
+  if (boundary === undefined || !hasInterruptionEvidence(blocks)) return undefined
+  return {
+    kind: 'assistant',
+    seq: boundary.seq - 0.9,
+    time: boundary.time,
+    turn: state.turn,
+    step: state.step,
+    blocks,
+    interrupted: true,
+  }
+}
+
+function fallbackState(context: ConversationNodeContext<AssistantState>): AssistantState | undefined {
+  let state: AssistantState | undefined
+  for (const match of context.matches) {
+    if (match.event.type === 'assistant/chunk') {
+      state ??= initialState(match.event.data.turn, match.event.data.step)
+      state = updateChunk(state, match)
+      continue
+    }
+    if (match.event.type === 'assistant/message') {
+      state ??= initialState(match.event.data.turn, match.event.data.step)
+      state = {
+        ...state,
+        blocks: toAssistantBlocks(match.event.data.message.content),
+        hidden: false,
+        final: match,
+        usage: match.event.data.usage,
+      }
+      continue
+    }
+    if ((match.event.type as string) === 'llm/retry' && state !== undefined) {
+      state = resetForRetry(state)
+    }
+  }
+  return state
+}
+
+interface AssistantProjection {
+  readonly data: AssistantChatData
+  readonly anchorSeq: number
+  readonly visible: boolean
+  readonly settled: AssistantMessageNode | undefined
+}
+
+function projectAssistant(context: ConversationNodeContext<AssistantState>): AssistantProjection | undefined {
+  const state = context.state ?? fallbackState(context)
+  if (state === undefined) return undefined
+  const settled = finalNode(state, context)
+  const blocks = settled?.blocks ?? compactBlocks(state.blocks)
+  const visible = hasVisibleContent(blocks)
+  const status = settled?.interrupted === true
+    ? 'interrupted'
+    : settled === undefined ? 'running' : 'settled'
+  const anchorSeq = settled?.seq ?? state.firstVisibleSeq ?? context.matches[0]?.event.seq ?? 0
+  const time = settled?.time ?? state.firstVisibleTime ?? context.matches[0]?.event.time ?? 0
+  return {
+    anchorSeq,
+    visible,
+    settled,
+    data: {
+      status,
+      turn: state.turn,
+      step: state.step,
+      blocks,
+      time,
+      ...state.usage === undefined ? {} : { usage: state.usage },
+      ...settled === undefined ? {} : { finalNode: settled },
+    },
+  }
+}
+
+/** Per-step Assistant streaming/final/interruption Definition. */
+export const assistantDefinition: ConversationNodeDefinition<AssistantState> = {
+  kind: 'assistant-step',
+  match: (event) => {
+    if (event.type === 'step/start') return { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+    if (event.type === 'assistant/chunk'
+      || (event.type === 'assistant/message' && isAppendSurfaceEvent(event))) {
+      return { id: `${event.data.turn}:${event.data.step}`, role: 'update' }
+    }
+    if ((event.type as string) === 'llm/retry') {
+      const data = event.data as unknown as { turn: number; step: number }
+      return { id: `${data.turn}:${data.step}`, role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'step/start') throw new Error('assistant-step start requires step/start')
+    return initialState(match.event.data.turn, match.event.data.step)
+  },
+  update: (context, match) => {
+    if (match.event.type === 'assistant/chunk') return updateChunk(context.state, match)
+    if (match.event.type === 'assistant/message') {
+      return {
+        ...context.state,
+        blocks: toAssistantBlocks(match.event.data.message.content),
+        hidden: false,
+        final: match,
+        usage: match.event.data.usage,
+      }
+    }
+    if ((match.event.type as string) === 'llm/retry') {
+      return resetForRetry(context.state)
+    }
+    return context.state
+  },
+  publication: (match) => {
+    if (match.event.type === 'step/start') return 'none'
+    if (match.event.type !== 'assistant/chunk') return 'immediate'
+    const type = match.event.data.chunk.type
+    return type === 'usage' || type === 'finish' ? 'none' : 'animation-frame'
+  },
+  buildLocationData: (context, scope) => {
+    if (scope !== 'step') return null
+    const projected = projectAssistant(context)
+    if (projected === undefined) return null
+    return {
+      kind: 'step',
+      turn: projected.data.turn,
+      step: projected.data.step,
+      key: 'assistant-step',
+      value: projected.data,
+    }
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const projected = projectAssistant(context)
+    if (projected === undefined) return null
+    if (projected.settled === undefined && !projected.visible) {
+      const state = context.state ?? fallbackState(context)
+      if (state === undefined) return null
+      const current = context.current.get('chat')
+      if (!state.hidden || current === undefined || current === null) return null
+    }
+    return chatNode(context, 'assistant-step', projected.anchorSeq, projected.data, {
+      visibility: projected.settled?.interrupted === true || projected.visible ? 'visible' : 'hidden',
+    })
+  },
+}
+
+/**
+ * Register the Assistant lifecycle business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerAssistantConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(assistantDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
new file mode 100644
index 0000000000..f9491d2d16
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
@@ -0,0 +1,456 @@
+import type { Context } from 'cordis'
+import type {
+  ChatConversationViewNode, ChatLocationNodeIndex, ChatNodeStore, ChatSnapshot,
+  ConversationLocation, ConversationNode, ConversationTimelineSnapshot,
+  ConversationViewBuilder, ConversationViewDefinition, LegacyConversationSlice,
+  PartialAssistant, RunningToolCall,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ChatNode } from '../contract/chat-nodes.ts'
+import { isRunningTool } from '../contract/chat-nodes.ts'
+
+const EMPTY_KEYS: readonly string[] = []
+const EMPTY_TURNS: readonly number[] = []
+const EMPTY_LIST: readonly never[] = []
+
+function sameReferences<T>(left: readonly T[], right: readonly T[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+class MutableChatNodeStore implements ChatNodeStore {
+  private readonly byKey = new Map<string, ChatConversationViewNode>()
+  private valuesCache: readonly ChatConversationViewNode[] = EMPTY_LIST
+  private valuesDirty = false
+
+  get(key: string): ChatConversationViewNode | undefined {
+    return this.byKey.get(key)
+  }
+
+  values(): readonly ChatConversationViewNode[] {
+    if (this.valuesDirty) {
+      this.valuesCache = [...this.byKey.values()]
+      this.valuesDirty = false
+    }
+    return this.valuesCache
+  }
+
+  replace(nodes: readonly ChatConversationViewNode[]): void {
+    this.byKey.clear()
+    for (const node of nodes) this.byKey.set(node.key, node)
+    this.valuesCache = [...this.byKey.values()]
+    this.valuesDirty = false
+  }
+
+  upsert(nodes: readonly ChatConversationViewNode[]): void {
+    let changed = false
+    for (const node of nodes) {
+      if (this.byKey.get(node.key) === node) continue
+      this.byKey.set(node.key, node)
+      changed = true
+    }
+    if (changed) this.valuesDirty = true
+  }
+}
+
+class MutableChatLocationIndex implements ChatLocationNodeIndex {
+  private turns = new Map<number, readonly string[]>()
+  private steps = new Map<string, readonly string[]>()
+
+  getTurn(turn: number): readonly string[] {
+    return this.turns.get(turn) ?? EMPTY_KEYS
+  }
+
+  getStep(turn: number, step: number): readonly string[] {
+    return this.steps.get(stepKey(turn, step)) ?? EMPTY_KEYS
+  }
+
+  rebuild(order: readonly string[], store: ChatNodeStore): void {
+    const turns = new Map<number, string[]>()
+    const steps = new Map<string, string[]>()
+    for (const key of order) {
+      const location = store.get(key)?.location
+      if (location === undefined) continue
+      const coordinates = locationCoordinates(location)
+      if (coordinates.turn === undefined) continue
+      const turnKeys = turns.get(coordinates.turn) ?? []
+      turnKeys.push(key)
+      turns.set(coordinates.turn, turnKeys)
+      if (coordinates.step === undefined) continue
+      const step = stepKey(coordinates.turn, coordinates.step)
+      const stepKeys = steps.get(step) ?? []
+      stepKeys.push(key)
+      steps.set(step, stepKeys)
+    }
+    this.turns = updateIndex(this.turns, turns)
+    this.steps = updateIndex(this.steps, steps)
+  }
+
+  /** Invalidate aggregate readers when member data changes without moving. */
+  touch(nodes: readonly ChatConversationViewNode[]): void {
+    const turns = new Set<number>()
+    const steps = new Set<string>()
+    for (const node of nodes) {
+      const coordinates = locationCoordinates(node.location)
+      if (coordinates.turn === undefined || !this.turns.get(coordinates.turn)?.includes(node.key)) continue
+      turns.add(coordinates.turn)
+      if (coordinates.step !== undefined) steps.add(stepKey(coordinates.turn, coordinates.step))
+    }
+    for (const turn of turns) {
+      const keys = this.turns.get(turn)
+      if (keys === undefined) continue
+      this.turns.set(turn, [...keys])
+    }
+    for (const step of steps) {
+      const keys = this.steps.get(step)
+      if (keys === undefined) continue
+      this.steps.set(step, [...keys])
+    }
+  }
+}
+
+function updateIndex<Key>(
+  previous: ReadonlyMap<Key, readonly string[]>,
+  nextMutable: ReadonlyMap<Key, string[]>,
+): Map<Key, readonly string[]> {
+  const next = new Map<Key, readonly string[]>()
+  const keys = new Set([...previous.keys(), ...nextMutable.keys()])
+  for (const key of keys) {
+    const before = previous.get(key) ?? EMPTY_KEYS
+    const candidate = nextMutable.get(key) ?? EMPTY_KEYS
+    const value = sameReferences(before, candidate) ? before : candidate
+    if (candidate.length > 0) next.set(key, value)
+  }
+  return next
+}
+
+function stepKey(turn: number, step: number): string {
+  return `${turn}:${step}`
+}
+
+function locationCoordinates(location: ConversationLocation): { turn?: number; step?: number } {
+  if (location.kind === 'step') return { turn: location.turn.turn, step: location.step.step }
+  if (location.kind === 'turn') return { turn: location.turn.turn }
+  return {}
+}
+
+function orderedVisible(nodes: readonly ChatConversationViewNode[]): ChatConversationViewNode[] {
+  return nodes
+    .filter(node => node.visibility === 'visible')
+    .sort((left, right) => left.anchorSeq - right.anchorSeq || left.key.localeCompare(right.key))
+}
+
+interface LegacyContribution {
+  readonly anchorSeq: number
+  readonly nodes: readonly ConversationNode[]
+  readonly partial: PartialAssistant | null
+  readonly running: RunningToolCall | null
+}
+
+const EMPTY_CONTRIBUTION: LegacyContribution = {
+  anchorSeq: 0,
+  nodes: EMPTY_LIST,
+  partial: null,
+  running: null,
+}
+
+function legacyContribution(raw: ChatConversationViewNode): LegacyContribution {
+  const node = raw as ChatNode
+  if (raw.visibility !== 'visible' && node.kind !== 'assistant-step') return EMPTY_CONTRIBUTION
+  switch (node.kind) {
+    case 'user':
+    case 'steering':
+    case 'context':
+    case 'command':
+    case 'compaction':
+    case 'turn-error':
+    case 'unknown':
+      return { anchorSeq: node.anchorSeq, nodes: [node.data], partial: null, running: null }
+    case 'assistant-step': {
+      const data = node.data
+      if (data.status === 'running') {
+        if (raw.visibility !== 'visible') return EMPTY_CONTRIBUTION
+        return {
+          anchorSeq: node.anchorSeq,
+          nodes: EMPTY_LIST,
+          partial: { turn: data.turn, step: data.step, blocks: data.blocks },
+          running: null,
+        }
+      }
+      return {
+        anchorSeq: node.anchorSeq,
+        nodes: data.finalNode === undefined ? EMPTY_LIST : [data.finalNode],
+        partial: null,
+        running: null,
+      }
+    }
+    case 'tool-call': {
+      const root = node.data.root
+      return isRunningTool(root)
+        ? { anchorSeq: node.anchorSeq, nodes: EMPTY_LIST, partial: null, running: root }
+        : { anchorSeq: node.anchorSeq, nodes: [root], partial: null, running: null }
+    }
+    case 'manual-compaction': {
+      const data = node.data
+      return {
+        anchorSeq: node.anchorSeq,
+        nodes: data.compaction === null ? [data.command] : [data.command, data.compaction],
+        partial: null,
+        running: null,
+      }
+    }
+    case 'model-retry':
+      return {
+        anchorSeq: node.anchorSeq,
+        nodes: node.data.attempts,
+        partial: null,
+        running: null,
+      }
+    case 'turn-tail':
+      return EMPTY_CONTRIBUTION
+    default:
+      return EMPTY_CONTRIBUTION
+  }
+}
+
+function sameContribution(left: LegacyContribution | undefined, right: LegacyContribution): boolean {
+  return left !== undefined
+    && left.anchorSeq === right.anchorSeq
+    && left.partial?.blocks === right.partial?.blocks
+    && left.partial?.turn === right.partial?.turn
+    && left.partial?.step === right.partial?.step
+    && left.running === right.running
+    && sameReferences(left.nodes, right.nodes)
+}
+
+/** Incremental compatibility projection retained solely for unmigrated Trajectory consumers. */
+class LegacySliceBuilder {
+  private readonly contributions = new Map<string, LegacyContribution>()
+  private readonly finalizedContributions = new Map<string, LegacyContribution>()
+  private readonly runningContributions = new Map<string, LegacyContribution>()
+  private readonly partialContributions = new Map<string, LegacyContribution>()
+  private finalized: readonly ConversationNode[] = EMPTY_LIST
+  private runningCalls: readonly RunningToolCall[] = EMPTY_LIST
+  private partial: PartialAssistant | null = null
+  private timeline: ConversationTimelineSnapshot | undefined
+  private turnTimings: LegacyConversationSlice['turnTimings'] = new Map()
+  private turnEnds: LegacyConversationSlice['turnEnds'] = new Map()
+
+  replace(
+    nodes: readonly ChatConversationViewNode[],
+    timeline: ConversationTimelineSnapshot,
+  ): LegacyConversationSlice {
+    this.contributions.clear()
+    this.finalizedContributions.clear()
+    this.runningContributions.clear()
+    this.partialContributions.clear()
+    for (const node of nodes) {
+      const contribution = legacyContribution(node)
+      this.contributions.set(node.key, contribution)
+      this.indexContribution(node.key, contribution)
+    }
+    this.rebuildFinalized()
+    this.rebuildRunning()
+    this.rebuildPartial()
+    this.updateTimeline(timeline)
+    return this.snapshot()
+  }
+
+  apply(
+    upserts: readonly ChatConversationViewNode[],
+    timeline: ConversationTimelineSnapshot,
+  ): LegacyConversationSlice {
+    let finalizedChanged = false
+    let runningChanged = false
+    let partialChanged = false
+    for (const node of upserts) {
+      const contribution = legacyContribution(node)
+      const previous = this.contributions.get(node.key)
+      if (sameContribution(previous, contribution)) continue
+      finalizedChanged ||= finalizedContributionChanged(previous, contribution)
+      runningChanged ||= runningContributionChanged(previous, contribution)
+      partialChanged ||= partialContributionChanged(previous, contribution)
+      this.contributions.set(node.key, contribution)
+      this.indexContribution(node.key, contribution)
+    }
+    if (finalizedChanged) this.rebuildFinalized()
+    if (runningChanged) this.rebuildRunning()
+    if (partialChanged) this.rebuildPartial()
+    this.updateTimeline(timeline)
+    return this.snapshot()
+  }
+
+  private indexContribution(key: string, contribution: LegacyContribution): void {
+    updateContributionIndex(this.finalizedContributions, key, contribution, contribution.nodes.length > 0)
+    updateContributionIndex(this.runningContributions, key, contribution, contribution.running !== null)
+    updateContributionIndex(this.partialContributions, key, contribution, contribution.partial !== null)
+  }
+
+  private rebuildFinalized(): void {
+    const finalized = [...this.finalizedContributions.values()]
+      .flatMap(value => value.nodes)
+      .sort((left, right) => left.seq - right.seq)
+    if (!sameReferences(this.finalized, finalized)) this.finalized = finalized
+  }
+
+  private rebuildRunning(): void {
+    const runningCalls = [...this.runningContributions.values()]
+      .sort((left, right) => left.anchorSeq - right.anchorSeq)
+      .flatMap(value => value.running === null ? [] : [value.running])
+    if (!sameReferences(this.runningCalls, runningCalls)) this.runningCalls = runningCalls
+  }
+
+  private rebuildPartial(): void {
+    const partial = [...this.partialContributions.values()]
+      .sort((left, right) => left.anchorSeq - right.anchorSeq)
+      .findLast(value => value.partial !== null)?.partial ?? null
+    if (this.partial?.blocks !== partial?.blocks
+      || this.partial?.turn !== partial?.turn
+      || this.partial?.step !== partial?.step) this.partial = partial
+  }
+
+  private updateTimeline(timeline: ConversationTimelineSnapshot): void {
+    if (this.timeline === timeline) return
+    this.timeline = timeline
+    const turnTimings = new Map<number, { startTime: number; endTime?: number }>()
+    const turnEnds = new Map<number, number>()
+    for (const turn of timeline.turns.values()) {
+      if (turn.start !== undefined) {
+        turnTimings.set(turn.turn, {
+          startTime: turn.start.time,
+          ...turn.end === undefined ? {} : { endTime: turn.end.time },
+        })
+      }
+      if (turn.end !== undefined) turnEnds.set(turn.turn, turn.end.seq)
+    }
+    this.turnTimings = turnTimings
+    this.turnEnds = turnEnds
+  }
+
+  private snapshot(): LegacyConversationSlice {
+    return {
+      nodes: this.finalized,
+      turnTimings: this.turnTimings,
+      turnEnds: this.turnEnds,
+      partial: this.partial,
+      runningCalls: this.runningCalls,
+    }
+  }
+}
+
+function updateContributionIndex(
+  index: Map<string, LegacyContribution>,
+  key: string,
+  contribution: LegacyContribution,
+  present: boolean,
+): void {
+  if (present) index.set(key, contribution)
+  else index.delete(key)
+}
+
+function finalizedContributionChanged(
+  previous: LegacyContribution | undefined,
+  next: LegacyContribution,
+): boolean {
+  const previousNodes = previous?.nodes ?? EMPTY_LIST
+  return !sameReferences(previousNodes, next.nodes)
+    || ((previousNodes.length > 0 || next.nodes.length > 0) && previous?.anchorSeq !== next.anchorSeq)
+}
+
+function runningContributionChanged(
+  previous: LegacyContribution | undefined,
+  next: LegacyContribution,
+): boolean {
+  return previous?.running !== next.running
+    || ((previous.running !== null || next.running !== null)
+      && previous.anchorSeq !== next.anchorSeq)
+}
+
+function partialContributionChanged(
+  previous: LegacyContribution | undefined,
+  next: LegacyContribution,
+): boolean {
+  return previous?.partial?.blocks !== next.partial?.blocks
+    || previous?.partial?.turn !== next.partial?.turn
+    || previous?.partial?.step !== next.partial?.step
+    || (((previous?.partial ?? null) !== null || next.partial !== null)
+      && previous?.anchorSeq !== next.anchorSeq)
+}
+
+/** Incremental keyed Chat builder registered under the `chat` target. */
+export class ChatSnapshotBuilder implements ConversationViewBuilder<ChatConversationViewNode, ChatSnapshot> {
+  private readonly store = new MutableChatNodeStore()
+  private readonly locations = new MutableChatLocationIndex()
+  private readonly legacy = new LegacySliceBuilder()
+  private order: readonly string[] = EMPTY_KEYS
+  readonly empty: ChatSnapshot
+
+  constructor() {
+    this.empty = this.snapshot({ turnOrder: EMPTY_TURNS, turns: new Map() })
+  }
+
+  replace(input: {
+    readonly nodes: readonly ChatConversationViewNode[]
+    readonly timeline: ConversationTimelineSnapshot
+  }): ChatSnapshot {
+    this.store.replace(input.nodes)
+    this.order = orderedVisible(input.nodes).map(node => node.key)
+    this.locations.rebuild(this.order, this.store)
+    return this.snapshot(input.timeline, this.legacy.replace(input.nodes, input.timeline))
+  }
+
+  apply(input: {
+    readonly upserts: readonly ChatConversationViewNode[]
+    readonly timeline: ConversationTimelineSnapshot
+  }): ChatSnapshot {
+    let structural = false
+    const contentOnly: ChatConversationViewNode[] = []
+    for (const node of input.upserts) {
+      const previous = this.store.get(node.key)
+      const nodeStructural = previous === undefined
+        || previous.anchorSeq !== node.anchorSeq
+        || previous.visibility !== node.visibility
+        || locationIdentity(previous.location) !== locationIdentity(node.location)
+      structural ||= nodeStructural
+      if (!nodeStructural) contentOnly.push(node)
+    }
+    this.store.upsert(input.upserts)
+    if (structural) {
+      const next = orderedVisible(this.store.values()).map(node => node.key)
+      this.order = sameReferences(this.order, next) ? this.order : next
+      this.locations.rebuild(this.order, this.store)
+    }
+    this.locations.touch(contentOnly)
+    return this.snapshot(input.timeline, this.legacy.apply(input.upserts, input.timeline))
+  }
+
+  private snapshot(
+    timeline: ConversationTimelineSnapshot,
+    legacy = this.legacy.replace(EMPTY_LIST, timeline),
+  ): ChatSnapshot {
+    return {
+      order: this.order,
+      nodes: this.store,
+      locations: this.locations,
+      timeline,
+      legacy,
+    }
+  }
+}
+
+function locationIdentity(location: ConversationLocation): string {
+  const coordinates = locationCoordinates(location)
+  return `${location.kind}:${coordinates.turn ?? ''}:${coordinates.step ?? ''}`
+}
+
+/** Chat target factory contributed to the Runtime view registry. */
+export const chatViewDefinition: ConversationViewDefinition<ChatConversationViewNode, ChatSnapshot> = {
+  target: 'chat',
+  create: () => new ChatSnapshotBuilder(),
+}
+
+/**
+ * Register the incremental Chat target builder.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerChatConversationView(ctx: Context): void {
+  ctx.conversationViews.register(chatViewDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/command.ts b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
new file mode 100644
index 0000000000..3ca7976e32
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
@@ -0,0 +1,243 @@
+import type { Context } from 'cordis'
+import type {
+  CommandNode, CompactionSummaryNode, ConversationMatch, ConversationNodeContext,
+  ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
+import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
+import type { ManualCompactionChatData } from '../contract/chat-nodes.ts'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Ordinary slash-command lifecycle. */
+    command: CommandNode
+    /** Manual compact command combined with its compaction transaction. */
+    'manual-compaction': ManualCompactionChatData
+  }
+}
+
+type CommandId = CommandNode['commandId']
+
+const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
+
+interface CommandState {
+  readonly command: CommandNode
+  readonly summary?: ConversationMatch
+  readonly checkpoint?: ConversationMatch
+}
+
+interface CompactionEvidence {
+  readonly summary?: ConversationMatch
+  readonly checkpoint?: ConversationMatch
+}
+
+interface CommandRunData {
+  readonly commandId: CommandId
+  readonly name: string
+  readonly args?: string
+}
+
+interface CommandDoneData {
+  readonly commandId: CommandId
+  readonly kind: 'success' | 'error'
+  readonly text?: string
+  readonly sourceEventSeq?: number
+}
+
+function commandFromRun(match: ConversationMatch): CommandNode {
+  const data = match.event.data as unknown as CommandRunData
+  return {
+    kind: 'command',
+    seq: match.event.seq,
+    time: match.event.time,
+    commandId: data.commandId,
+    name: data.name,
+    args: data.args ?? null,
+    outcome: null,
+  }
+}
+
+function commandFromDone(match: ConversationMatch, previous?: CommandNode): CommandNode {
+  const data = match.event.data as unknown as CommandDoneData
+  const sourceEventSeq = data.kind === 'success'
+    && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
+    ? data.sourceEventSeq as number
+    : undefined
+  return {
+    kind: 'command',
+    seq: previous?.seq ?? match.event.seq,
+    time: previous?.time ?? match.event.time,
+    commandId: data.commandId,
+    name: previous?.name ?? null,
+    args: previous?.args ?? null,
+    outcome: {
+      kind: data.kind,
+      ...data.text === undefined ? {} : { text: data.text },
+      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
+    },
+  }
+}
+
+/**
+ * Read correlation identity from a compaction replacement checkpoint.
+ * @param event - candidate Session event.
+ * @returns correlated compaction and optional command identity.
+ */
+function compactSource(event: Parameters<ConversationNodeDefinition['match']>[0]): {
+  compactionId: string
+  sourceCommandId?: CommandId
+} | undefined {
+  if (event.type !== 'user/message' || !isReplacementSurfaceEvent(event)) return undefined
+  const source = event.data.source as unknown as {
+    kind?: unknown
+    plugin?: unknown
+    compactionId?: unknown
+    sourceCommandId?: CommandId
+  }
+  if (source.kind !== 'plugin' || source.plugin !== COMPACT_PLUGIN || typeof source.compactionId !== 'string') return undefined
+  return {
+    compactionId: source.compactionId,
+    ...source.sourceCommandId === undefined ? {} : { sourceCommandId: source.sourceCommandId },
+  }
+}
+
+/**
+ * Build the visible summary marker from optional lifecycle evidence.
+ * @param match - compact/summary Match, when loaded.
+ * @param checkpoint - replacement checkpoint Match.
+ * @returns final compaction summary Node data.
+ */
+function compactSummary(match: ConversationMatch | undefined, checkpoint: ConversationMatch): CompactionSummaryNode {
+  let summary: string | null = null
+  let shadowedItemCount: number | null = null
+  let shadowedTokenCount: number | null = null
+  if (match !== undefined) {
+    const data = match.event.data as unknown as {
+      summary?: unknown
+      shadowedSeqs?: unknown
+      shadowedTokenCount?: unknown
+    }
+    if (Array.isArray(data.summary)) {
+      const text = data.summary
+        .map((block: unknown) => {
+          const value = block as { type?: unknown; text?: unknown }
+          return value.type === 'text' && typeof value.text === 'string' ? value.text : ''
+        })
+        .join('')
+      summary = text.trim() === '' ? null : text
+    }
+    shadowedItemCount = Array.isArray(data.shadowedSeqs)
+      && data.shadowedSeqs.every(seq => Number.isSafeInteger(seq) && (seq as number) >= 0)
+      ? data.shadowedSeqs.length
+      : null
+    shadowedTokenCount = Number.isSafeInteger(data.shadowedTokenCount)
+      && (data.shadowedTokenCount as number) >= 0
+      ? data.shadowedTokenCount as number
+      : null
+  }
+  return {
+    kind: 'compaction',
+    seq: checkpoint.event.seq,
+    time: checkpoint.event.time,
+    summary,
+    summaryEventSeq: match?.event.seq ?? null,
+    shadowedItemCount,
+    shadowedTokenCount,
+  }
+}
+
+function fallbackState(context: ConversationNodeContext<CommandState>): CommandState | undefined {
+  const done = context.matches.find(match => (match.event.type as string) === 'command/done')
+  const checkpoint = context.matches.find(match => compactSource(match.event) !== undefined)
+  const summary = context.matches.find(match => (match.event.type as string) === 'compact/summary')
+  if (checkpoint === undefined) return done === undefined ? undefined : { command: commandFromDone(done) }
+  const source = compactSource(checkpoint.event)
+  if (source?.sourceCommandId === undefined) return done === undefined ? undefined : { command: commandFromDone(done) }
+  const fallbackCommand = done === undefined
+    ? {
+      kind: 'command' as const,
+      seq: checkpoint.event.seq,
+      time: checkpoint.event.time,
+      commandId: source.sourceCommandId,
+      name: 'compact',
+      args: null,
+      outcome: null,
+    }
+    : { ...commandFromDone(done), name: 'compact' }
+  return {
+    command: fallbackCommand,
+    checkpoint,
+    ...summary === undefined ? {} : { summary },
+  }
+}
+
+/**
+ * Fold shared compaction evidence into a Definition-owned State.
+ * @param state - current business State carrying optional compaction evidence.
+ * @param match - next compaction lifecycle Match.
+ * @returns adopted State, preserving reference identity when the Match adds no evidence.
+ */
+export function updateCompactionState<State extends CompactionEvidence>(
+  state: State,
+  match: ConversationMatch,
+): State {
+  if ((match.event.type as string) === 'compact/summary') return { ...state, summary: match }
+  if (compactSource(match.event) !== undefined) return { ...state, checkpoint: match }
+  return state
+}
+
+/** Slash-command lifecycle, including integrated manual compaction, Definition. */
+export const commandDefinition: ConversationNodeDefinition<CommandState> = {
+  kind: 'command',
+  match: (event) => {
+    if ((event.type as string) === 'command/run') {
+      return { id: String((event.data as unknown as CommandRunData).commandId), role: 'start' }
+    }
+    if ((event.type as string) === 'command/done') {
+      return { id: String((event.data as unknown as CommandDoneData).commandId), role: 'update' }
+    }
+    const checkpoint = compactSource(event)
+    if (checkpoint?.sourceCommandId !== undefined) {
+      return { id: String(checkpoint.sourceCommandId), role: 'update' }
+    }
+    if ((event.type as string) === 'compact/start'
+      || (event.type as string) === 'compact/summary'
+      || (event.type as string) === 'compact/end') {
+      const data = event.data as unknown as { sourceCommandId?: CommandId }
+      if (data.sourceCommandId !== undefined) return { id: String(data.sourceCommandId), role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => ({ command: commandFromRun(match) }),
+  update: (context, match) => {
+    if ((match.event.type as string) === 'command/done') {
+      return { ...context.state, command: commandFromDone(match, context.state.command) }
+    }
+    return updateCompactionState(context.state, match)
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const state = context.state ?? fallbackState(context)
+    if (state === undefined) return null
+    if (state.command.name !== 'compact') {
+      return chatNode(context, 'command', state.command.seq, state.command)
+    }
+    const compaction = state.checkpoint === undefined
+      ? null
+      : compactSummary(state.summary, state.checkpoint)
+    const data: ManualCompactionChatData = { command: state.command, compaction }
+    return chatNode(context, 'manual-compaction', compaction?.seq ?? state.command.seq, data)
+  },
+}
+
+/**
+ * Register the command lifecycle business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerCommandConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(commandDefinition)
+}
+
+/** Shared structural checkpoint recognizer for automatic compaction. */
+export { compactSource, compactSummary }
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/common.ts b/packages/client/ui-conversation/src/client/conversation-nodes/common.ts
new file mode 100644
index 0000000000..8e1d9d7bd4
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/common.ts
@@ -0,0 +1,55 @@
+import type {
+  ConversationLocation, ConversationNodeContext,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ChatNode, ChatNodeDataMap, ChatNodeKind,
+} from '../contract/chat-nodes.ts'
+
+/**
+ * Resolve one Context's best currently loaded event Location.
+ * @param context - assembled business Context.
+ * @returns start or first-match Location, otherwise unresolved.
+ */
+export function contextLocation(context: ConversationNodeContext): ConversationLocation {
+  return context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' }
+}
+
+/**
+ * Build one final Chat target Node with the engine-owned stable key.
+ * @param context - assembled business Context.
+ * @param kind - Chat renderer dispatch key.
+ * @param anchorSeq - sortable render position.
+ * @param data - renderer-owned payload.
+ * @param options - optional Location and visibility overrides.
+ * @returns final Chat view Node.
+ */
+export function chatNode<Kind extends ChatNodeKind>(
+  context: ConversationNodeContext,
+  kind: Kind,
+  anchorSeq: number,
+  data: ChatNodeDataMap[Kind],
+  options: {
+    readonly location?: ConversationLocation
+    readonly visibility?: 'visible' | 'hidden'
+  } = {},
+): ChatNode<Kind> {
+  return {
+    key: context.key,
+    kind,
+    id: context.id,
+    target: 'chat',
+    anchorSeq,
+    location: options.location ?? contextLocation(context),
+    visibility: options.visibility ?? 'visible',
+    data,
+  }
+}
+
+/**
+ * Read a finite non-negative integer from a structurally narrowed payload.
+ * @param value - untrusted payload field.
+ * @returns valid coordinate, otherwise undefined.
+ */
+export function coordinate(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
new file mode 100644
index 0000000000..0742ab6539
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
@@ -0,0 +1,63 @@
+import type { Context } from 'cordis'
+import type {
+  CompactionSummaryNode, ConversationMatch, ConversationNodeContext, ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { chatNode } from './common.ts'
+import { compactSource, compactSummary, updateCompactionState } from './command.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Automatic compaction checkpoint marker. */
+    compaction: CompactionSummaryNode
+  }
+}
+
+interface CompactionState {
+  readonly summary?: ConversationMatch
+  readonly checkpoint?: ConversationMatch
+}
+
+function fallbackState(context: ConversationNodeContext<CompactionState>): CompactionState {
+  const summary = context.matches.find(match => (match.event.type as string) === 'compact/summary')
+  const checkpoint = context.matches.find(match => compactSource(match.event) !== undefined)
+  return {
+    ...summary === undefined ? {} : { summary },
+    ...checkpoint === undefined ? {} : { checkpoint },
+  }
+}
+
+/** Automatic compaction lifecycle and landed checkpoint Definition. */
+export const compactionDefinition: ConversationNodeDefinition<CompactionState> = {
+  kind: 'compaction',
+  match: (event) => {
+    const checkpoint = compactSource(event)
+    if (checkpoint !== undefined && checkpoint.sourceCommandId === undefined) {
+      return { id: checkpoint.compactionId, role: 'update' }
+    }
+    if ((event.type as string) === 'compact/start'
+      || (event.type as string) === 'compact/summary'
+      || (event.type as string) === 'compact/end') {
+      const data = event.data as unknown as { compactionId?: unknown; sourceCommandId?: unknown }
+      if (typeof data.compactionId !== 'string' || data.sourceCommandId !== undefined) return null
+      return { id: data.compactionId, role: (event.type as string) === 'compact/start' ? 'start' : 'update' }
+    }
+    return null
+  },
+  start: () => ({}),
+  update: (context, match) => updateCompactionState(context.state, match),
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const state = context.state ?? fallbackState(context)
+    if (state.checkpoint === undefined) return null
+    const marker = compactSummary(state.summary, state.checkpoint)
+    return chatNode(context, 'compaction', marker.seq, marker)
+  },
+}
+
+/**
+ * Register the automatic-compaction business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerCompactionConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(compactionDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/fallback.ts b/packages/client/ui-conversation/src/client/conversation-nodes/fallback.ts
new file mode 100644
index 0000000000..a93fc8fdd4
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/fallback.ts
@@ -0,0 +1,40 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationNodeDefinition, UnknownSurfaceNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Generic presentation of an unclaimed append-surface event. */
+    unknown: UnknownSurfaceNode
+  }
+}
+
+/** Unclaimed append-surface fallback Definition. */
+export const unknownFallbackDefinition: ConversationNodeDefinition<UnknownSurfaceNode> = {
+  kind: 'unknown-surface',
+  match: event => isAppendSurfaceEvent(event)
+    ? { id: String(event.seq), role: 'start' }
+    : null,
+  start: (_context, match) => ({
+    kind: 'unknown',
+    seq: match.event.seq,
+    time: match.event.time,
+    type: match.event.type,
+    data: match.event.data,
+  }),
+  update: context => context.state,
+  buildViewNode: (context, target) => target !== 'chat' || context.state === undefined
+    ? null
+    : chatNode(context, 'unknown', context.state.seq, context.state),
+}
+
+/**
+ * Register the unmatched append-surface fallback contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerUnknownConversationFallback(ctx: Context): void {
+  ctx.conversationEvents.registerFallback(unknownFallbackDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
new file mode 100644
index 0000000000..092bcaaa59
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
@@ -0,0 +1,71 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationNodeDefinition, ConversationPreviousContext,
+} from '@deepseek-ai/dsh-client-runtime/client'
+
+type InboxTarget = 'next-turn' | 'next-step'
+
+interface InboxIdentity {
+  readonly id: string
+}
+
+interface InboxSplice {
+  readonly target: InboxTarget
+  readonly start: number
+  readonly removedCount?: number
+  readonly inserted: readonly InboxIdentity[]
+  readonly outcome?: 'canceled'
+}
+
+/** Cumulative state after one durable inbox splice. */
+export interface InboxState {
+  readonly pending: readonly InboxIdentity[]
+  readonly claimed: ReadonlySet<string>
+}
+
+function applySplice(
+  previous: ConversationPreviousContext<InboxState> | undefined,
+  splice: InboxSplice,
+): InboxState {
+  const pending = [...(previous?.state.pending ?? [])]
+  const claimed = new Set(previous?.state.claimed ?? [])
+  const removed = pending.splice(splice.start, splice.removedCount ?? 0, ...splice.inserted)
+  for (const identity of splice.inserted) claimed.delete(identity.id)
+  if (splice.target === 'next-step' && splice.outcome !== 'canceled') {
+    for (const identity of removed) claimed.add(identity.id)
+  }
+  return { pending, claimed }
+}
+
+function inboxDefinition(target: InboxTarget): ConversationNodeDefinition<InboxState> {
+  const kind = `inbox-${target}`
+  return {
+    kind,
+    match: event => (event.type as string) === 'agent/inbox/spliced'
+      && (event.data as unknown as { target?: unknown }).target === target
+      ? { id: String(event.seq), role: 'start' }
+      : null,
+    start: (_context, match, reader) => applySplice(
+      reader.previous<InboxState>(kind),
+      match.event.data as unknown as InboxSplice,
+    ),
+    update: context => context.state,
+    publication: () => 'none',
+    buildViewNode: () => null,
+  }
+}
+
+/** Cumulative next-turn inbox splice Definition. */
+export const nextTurnInboxDefinition = inboxDefinition('next-turn')
+
+/** Cumulative next-step inbox splice Definition used to classify steering. */
+export const nextStepInboxDefinition = inboxDefinition('next-step')
+
+/**
+ * Register the two durable Inbox-state contributions.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerInboxConversationNodes(ctx: Context): void {
+  ctx.conversationEvents.register(nextTurnInboxDefinition)
+  ctx.conversationEvents.register(nextStepInboxDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/message.ts b/packages/client/ui-conversation/src/client/conversation-nodes/message.ts
new file mode 100644
index 0000000000..91300944d7
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/message.ts
@@ -0,0 +1,83 @@
+import type { Context } from 'cordis'
+import type {
+  ContextMessageNode, ConversationNodeDefinition, SteeringMessageNode, UserMessageNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  contextForm, contextProvenance, isAppendSurfaceEvent, isReplacementSurfaceEvent,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { InboxState } from './inbox.ts'
+import { chatNode } from './common.ts'
+
+type MessageNode = UserMessageNode | SteeringMessageNode | ContextMessageNode
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Ordinary turn-opening user message. */
+    user: UserMessageNode
+    /** User message admitted into an active turn. */
+    steering: SteeringMessageNode
+    /** Non-user context injected into model history. */
+    context: ContextMessageNode
+  }
+}
+
+function isCompactionCheckpoint(event: Parameters<ConversationNodeDefinition['match']>[0]): boolean {
+  if (event.type !== 'user/message' || !isReplacementSurfaceEvent(event)) return false
+  const source = event.data.source
+  return source.kind === 'plugin' && source.plugin === 'compact'
+}
+
+/** User, steering, and injected-context message classification Definition. */
+export const messageDefinition: ConversationNodeDefinition<MessageNode> = {
+  kind: 'input-message',
+  match: event => event.type === 'user/message'
+    && isAppendSurfaceEvent(event)
+    && !isCompactionCheckpoint(event)
+    ? { id: String(event.data.id), role: 'start' }
+    : null,
+  start: (_context, match, reader) => {
+    if (match.event.type !== 'user/message') throw new Error('input-message start requires user/message')
+    const event = match.event
+    if (event.data.source.kind !== 'user') {
+      return {
+        kind: 'context',
+        seq: event.seq,
+        time: event.time,
+        content: event.data.content,
+        source: event.data.source,
+        provenance: contextProvenance(event.data.source),
+        form: contextForm(event.data.source),
+      }
+    }
+    const claimed = reader.previous<InboxState>('inbox-next-step')?.state.claimed.has(String(event.data.id)) === true
+    return claimed
+      ? {
+        kind: 'steering',
+        messageId: event.data.id,
+        seq: event.seq,
+        time: event.time,
+        content: event.data.content,
+        source: event.data.source,
+      }
+      : {
+        kind: 'user',
+        seq: event.seq,
+        time: event.time,
+        content: event.data.content,
+        source: event.data.source,
+      }
+  },
+  update: context => context.state,
+  buildViewNode: (context, target) => {
+    if (target !== 'chat' || context.state === undefined) return null
+    return chatNode(context, context.state.kind, context.state.seq, context.state)
+  },
+}
+
+/**
+ * Register the user, steering, and injected-context message contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerMessageConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(messageDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/register.ts b/packages/client/ui-conversation/src/client/conversation-nodes/register.ts
new file mode 100644
index 0000000000..9102b1f2f4
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/register.ts
@@ -0,0 +1,30 @@
+import type { Context } from 'cordis'
+import { registerAssistantConversationNode } from './assistant.ts'
+import { registerChatConversationView } from './chat-snapshot-builder.ts'
+import { registerCommandConversationNode } from './command.ts'
+import { registerCompactionConversationNode } from './compaction.ts'
+import { registerUnknownConversationFallback } from './fallback.ts'
+import { registerInboxConversationNodes } from './inbox.ts'
+import { registerMessageConversationNode } from './message.ts'
+import { registerRetryConversationNode } from './retry.ts'
+import { registerToolConversationNode } from './tool.ts'
+import { registerTurnErrorConversationNode } from './turn-error.ts'
+import { registerTurnTailConversationNode } from './turn-tail.ts'
+
+/**
+ * Register the Chat business Definitions and target builder contributed by this package.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerConversationNodes(ctx: Context): void {
+  registerInboxConversationNodes(ctx)
+  registerMessageConversationNode(ctx)
+  registerAssistantConversationNode(ctx)
+  registerToolConversationNode(ctx)
+  registerCommandConversationNode(ctx)
+  registerCompactionConversationNode(ctx)
+  registerRetryConversationNode(ctx)
+  registerTurnErrorConversationNode(ctx)
+  registerTurnTailConversationNode(ctx)
+  registerUnknownConversationFallback(ctx)
+  registerChatConversationView(ctx)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
new file mode 100644
index 0000000000..fe95c0052d
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
@@ -0,0 +1,116 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationLocation, ConversationNodeDefinition, ModelRetryNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { RetryChatData } from '../contract/chat-nodes.ts'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Producer-correlated model retry chain. */
+    'model-retry': RetryChatData
+  }
+}
+
+type WithoutRetryProjection<Node> = Node extends unknown
+  ? Omit<Node, 'kind' | 'seq' | 'time' | 'retryState'>
+  : never
+type RetryEventData = WithoutRetryProjection<ModelRetryNode>
+
+/** Accumulated retry attempts sharing one producer-owned RetryId. */
+export interface RetryState {
+  readonly turn: number
+  readonly step: number
+  readonly attempts: readonly ModelRetryNode[]
+}
+
+function retryData(value: unknown): RetryEventData | undefined {
+  if (value === null || typeof value !== 'object') return undefined
+  const data = value as Record<string, unknown>
+  if (typeof data.retryId !== 'string' || data.retryId === ''
+    || !Number.isSafeInteger(data.turn) || (data.turn as number) < 0
+    || !Number.isSafeInteger(data.step) || (data.step as number) < 0
+    || !Number.isSafeInteger(data.retry) || (data.retry as number) <= 0
+    || typeof data.delayMs !== 'number' || !Number.isFinite(data.delayMs) || data.delayMs < 0
+    || typeof data.provider !== 'string' || typeof data.policyKey !== 'string'
+    || (data.mode !== 'normal' && data.mode !== 'always')
+    || data.failure === null || typeof data.failure !== 'object') return undefined
+  if (data.mode === 'normal' && (!Number.isSafeInteger(data.maxRetries) || (data.maxRetries as number) <= 0)) {
+    return undefined
+  }
+  return data as unknown as RetryEventData
+}
+
+function scheduledNode(event: { seq: number; time: number; data: unknown }): ModelRetryNode | undefined {
+  const data = retryData(event.data)
+  return data === undefined ? undefined : {
+    kind: 'model-retry',
+    seq: event.seq,
+    time: event.time,
+    retryState: 'scheduled',
+    ...data,
+  }
+}
+
+function isClosed(location: ConversationLocation): boolean {
+  return (location.kind === 'step' && location.step.status === 'closed')
+    || ((location.kind === 'step' || location.kind === 'turn') && location.turn.status === 'closed')
+}
+
+/** Producer-correlated model retry chain Definition. */
+export const retryDefinition: ConversationNodeDefinition<RetryState> = {
+  kind: 'model-retry',
+  match: (event) => {
+    if ((event.type as string) === 'llm/retry') {
+      const data = retryData(event.data)
+      if (data === undefined) return null
+      return { id: String(data.retryId), role: data.retry === 1 ? 'start' : 'update' }
+    }
+    if ((event.type as string) === 'llm/retry-started') {
+      const data = event.data as unknown as { retryId?: unknown }
+      return typeof data.retryId === 'string' ? { id: data.retryId, role: 'update' } : null
+    }
+    return null
+  },
+  start: (_context, match) => {
+    const node = scheduledNode(match.event)
+    if (node === undefined) throw new Error('model-retry start requires a valid llm/retry event')
+    return { turn: node.turn, step: node.step, attempts: [node] }
+  },
+  update: (context, match) => {
+    if ((match.event.type as string) === 'llm/retry') {
+      const node = scheduledNode(match.event)
+      return node === undefined ? context.state : { ...context.state, attempts: [...context.state.attempts, node] }
+    }
+    if ((match.event.type as string) !== 'llm/retry-started') return context.state
+    const data = match.event.data as unknown as { retry: number }
+    return {
+      ...context.state,
+      attempts: context.state.attempts.map(attempt =>
+        attempt.retry === data.retry ? { ...attempt, retryState: 'started' } : attempt),
+    }
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat' || context.state === undefined || context.state.attempts.length === 0) return null
+    const location = context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' as const }
+    const stateAttempts = context.state.attempts
+    const attempts = stateAttempts.map((attempt, index) =>
+      index === stateAttempts.length - 1
+        && attempt.retryState === 'scheduled'
+        && isClosed(location)
+        ? { ...attempt, retryState: 'cancelled' as const }
+        : attempt)
+    const current = attempts.at(-1)
+    if (current === undefined) return null
+    const data: RetryChatData = { attempts, current }
+    return chatNode(context, 'model-retry', attempts[0]?.seq ?? current.seq, data)
+  },
+}
+
+/**
+ * Register the correlated model-retry business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerRetryConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(retryDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
new file mode 100644
index 0000000000..04a5770f5a
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
@@ -0,0 +1,271 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationMatch, ConversationNodeContext, ConversationNodeDefinition,
+  RunningToolCall, ToolCallBlock, ToolResultNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolChatData } from '../contract/chat-nodes.ts'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Root Tool lifecycle with recursively nested subcalls. */
+    'tool-call': ToolChatData
+  }
+}
+
+const MAX_DEPTH = 256
+
+interface ToolState {
+  readonly root: ToolCallBlock
+  readonly children: ReadonlyMap<string, readonly ToolCallBlock[]>
+  readonly parents: ReadonlyMap<string, string>
+}
+
+interface ProjectedBlockCache {
+  readonly children: readonly ToolCallBlock[]
+  readonly interruptionSeq: number | undefined
+  readonly interruptionTime: number | undefined
+  readonly value: ToolCallBlock
+}
+
+const projectedBlocks = new WeakMap<ToolCallBlock, ProjectedBlockCache>()
+
+function jsonArguments(value: unknown): string {
+  return JSON.stringify(value)
+}
+
+function rootCall(match: ConversationMatch): RunningToolCall {
+  if (match.event.type !== 'tool/call') throw new Error('tool-call start requires tool/call')
+  return {
+    callId: String(match.event.data.callId),
+    name: match.event.data.name,
+    argsRaw: match.event.data.arguments,
+    turn: match.event.data.turn,
+    step: match.event.data.step,
+    time: match.event.time,
+    callView: match.view?.for === 'call' ? match.view.view : null,
+    subCalls: [],
+  }
+}
+
+function rootResult(match: ConversationMatch, previous?: RunningToolCall): ToolResultNode | undefined {
+  if (match.event.type !== 'tool/result') return undefined
+  const result = match.event.data.message.content[0]
+  return {
+    kind: 'tool-result',
+    seq: match.event.seq,
+    time: match.event.time,
+    callId: String(match.event.data.message.source.callId),
+    call: previous === undefined ? null : { name: previous.name, argsRaw: previous.argsRaw },
+    callTime: previous?.time ?? null,
+    content: result.content,
+    isError: result.isError === true,
+    ...match.event.data.error === undefined ? {} : { error: match.event.data.error },
+    meta: match.event.data.meta,
+    callView: previous?.callView ?? null,
+    resultView: match.view?.for === 'result' ? match.view.view : null,
+    subCalls: [],
+  }
+}
+
+interface DispatchData {
+  readonly parentCallId: string
+  readonly subCallId: string
+  readonly name: string
+  readonly arguments: unknown
+  readonly isError?: boolean
+  readonly content?: ToolResultNode['content']
+}
+
+function childCall(match: ConversationMatch, data: DispatchData): RunningToolCall {
+  return {
+    callId: data.subCallId,
+    name: data.name,
+    argsRaw: jsonArguments(data.arguments),
+    turn: locationTurn(match),
+    step: locationStep(match),
+    time: match.event.time,
+    callView: null,
+    subCalls: [],
+  }
+}
+
+function childResult(match: ConversationMatch, data: DispatchData, previous?: ToolCallBlock): ToolResultNode {
+  return {
+    kind: 'tool-result',
+    seq: match.event.seq,
+    time: match.event.time,
+    callId: data.subCallId,
+    call: { name: data.name, argsRaw: jsonArguments(data.arguments) },
+    callTime: previous?.time ?? null,
+    content: data.content ?? [],
+    isError: data.isError === true,
+    callView: null,
+    resultView: null,
+    subCalls: [],
+  }
+}
+
+function locationTurn(match: ConversationMatch): number {
+  return match.location.kind === 'step' || match.location.kind === 'turn' ? match.location.turn.turn : 0
+}
+
+function locationStep(match: ConversationMatch): number {
+  return match.location.kind === 'step' ? match.location.step.step : 0
+}
+
+function acceptsEdge(state: ToolState, parent: string, child: string): boolean {
+  if (parent === child || state.parents.has(child)) return false
+  let cursor: string | undefined = parent
+  let parentDepth = 0
+  const ancestors = new Set<string>()
+  while (cursor !== undefined) {
+    if (cursor === child || ancestors.has(cursor)) return false
+    ancestors.add(cursor)
+    parentDepth++
+    cursor = state.parents.get(cursor)
+  }
+  const pending = [{ callId: child, depth: 1 }]
+  const descendants = new Set<string>()
+  let subtreeDepth = 0
+  for (const candidate of pending) {
+    if (descendants.has(candidate.callId)) return false
+    descendants.add(candidate.callId)
+    subtreeDepth = Math.max(subtreeDepth, candidate.depth)
+    for (const nested of state.children.get(candidate.callId) ?? []) {
+      pending.push({ callId: nested.callId, depth: candidate.depth + 1 })
+    }
+  }
+  return parentDepth + subtreeDepth <= MAX_DEPTH
+}
+
+function updateDispatch(state: ToolState, match: ConversationMatch): ToolState {
+  const data = match.event.data as unknown as DispatchData
+  const siblings = state.children.get(data.parentCallId) ?? []
+  const index = siblings.findIndex(candidate => candidate.callId === data.subCallId)
+  if ((match.event.type as string) === 'tool/code-dispatch-start') {
+    if (index >= 0 || !acceptsEdge(state, data.parentCallId, data.subCallId)) return state
+    const children = new Map(state.children)
+    children.set(data.parentCallId, [...siblings, childCall(match, data)])
+    const parents = new Map(state.parents)
+    parents.set(data.subCallId, data.parentCallId)
+    return { ...state, children, parents }
+  }
+  if ((match.event.type as string) !== 'tool/code-dispatch') return state
+  if (index < 0 && !acceptsEdge(state, data.parentCallId, data.subCallId)) return state
+  const previous = index < 0 ? undefined : siblings[index]
+  const settled = childResult(match, data, previous)
+  const children = new Map(state.children)
+  children.set(data.parentCallId, index < 0
+    ? [...siblings, settled]
+    : siblings.map((child, at) => at === index ? settled : child))
+  const parents = new Map(state.parents)
+  if (index < 0) parents.set(data.subCallId, data.parentCallId)
+  return { ...state, children, parents }
+}
+
+function projectBlock(
+  block: ToolCallBlock,
+  state: ToolState,
+  interruptedAt: { seq: number; time: number } | undefined,
+  visited = new Set<string>(),
+  depth = 1,
+): ToolCallBlock {
+  if (visited.has(block.callId) || depth > MAX_DEPTH) return { ...block, subCalls: [] }
+  const nextVisited = new Set(visited)
+  nextVisited.add(block.callId)
+  const children = (state.children.get(block.callId) ?? block.subCalls)
+    .map(child => projectBlock(child, state, interruptedAt, nextVisited, depth + 1))
+  const interruptionSeq = 'kind' in block ? undefined : interruptedAt?.seq
+  const interruptionTime = 'kind' in block ? undefined : interruptedAt?.time
+  const cached = projectedBlocks.get(block)
+  if (cached !== undefined
+    && cached.interruptionSeq === interruptionSeq
+    && cached.interruptionTime === interruptionTime
+    && sameReferences(cached.children, children)) {
+    return cached.value
+  }
+  const projected: ToolCallBlock = 'kind' in block || interruptedAt === undefined
+    ? sameReferences(block.subCalls, children) ? block : { ...block, subCalls: children }
+    : {
+      kind: 'tool-result',
+      seq: interruptedAt.seq - 0.8,
+      time: interruptedAt.time,
+      callId: block.callId,
+      call: { name: block.name, argsRaw: block.argsRaw },
+      callTime: block.time,
+      content: [],
+      isError: true,
+      error: { name: 'Interrupted', code: 'interrupted' },
+      callView: block.callView,
+      resultView: null,
+      subCalls: children,
+    }
+  projectedBlocks.set(block, { children, interruptionSeq, interruptionTime, value: projected })
+  return projected
+}
+
+function sameReferences<T>(left: readonly T[], right: readonly T[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+function interruption(context: ConversationNodeContext<ToolState>): { seq: number; time: number } | undefined {
+  const location = context.start?.location
+  if (location?.kind === 'step' && location.step.status === 'closed') return location.step.end
+  if ((location?.kind === 'step' || location?.kind === 'turn') && location.turn.status === 'closed') {
+    return location.turn.end
+  }
+  return undefined
+}
+
+function fallbackState(context: ConversationNodeContext<ToolState>): ToolState | undefined {
+  const match = context.matches.find(candidate => candidate.event.type === 'tool/result')
+  const root = match === undefined ? undefined : rootResult(match)
+  if (root === undefined) return undefined
+  let state: ToolState = { root, children: new Map(), parents: new Map() }
+  for (const candidate of context.matches) state = updateDispatch(state, candidate)
+  return state
+}
+
+/** Root Tool lifecycle and nested Code Dispatch Definition. */
+export const toolDefinition: ConversationNodeDefinition<ToolState> = {
+  kind: 'tool-call',
+  match: (event) => {
+    if (event.type === 'tool/call') return { id: String(event.data.callId), role: 'start' }
+    if (event.type === 'tool/result' && isAppendSurfaceEvent(event)) {
+      return { id: String(event.data.message.source.callId), role: 'update' }
+    }
+    if ((event.type as string) === 'tool/code-dispatch-start' || (event.type as string) === 'tool/code-dispatch') {
+      const data = event.data as unknown as { rootCallId: string }
+      return { id: data.rootCallId, role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => ({ root: rootCall(match), children: new Map(), parents: new Map() }),
+  update: (context, match) => {
+    if (match.event.type === 'tool/result') {
+      const running = 'kind' in context.state.root ? undefined : context.state.root
+      const result = rootResult(match, running)
+      return result === undefined ? context.state : { ...context.state, root: result }
+    }
+    return updateDispatch(context.state, match)
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const state = context.state ?? fallbackState(context)
+    if (state === undefined) return null
+    const projected = projectBlock(state.root, state, interruption(context))
+    const anchor = context.start?.event.seq
+      ?? ('kind' in state.root ? state.root.seq : context.matches[0]?.event.seq ?? 0)
+    return chatNode(context, 'tool-call', anchor, { root: projected } satisfies ToolChatData)
+  },
+}
+
+/**
+ * Register the root Tool lifecycle and nested-subcall contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerToolConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(toolDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
new file mode 100644
index 0000000000..58725d8723
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
@@ -0,0 +1,112 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, TurnErrorNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { displayFailureMessage } from '@deepseek-ai/dsh-client-runtime/client'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Terminal turn failure not superseded by retry. */
+    'turn-error': TurnErrorNode
+  }
+}
+
+interface TurnErrorState {
+  readonly turn: number
+  readonly hidden: boolean
+  readonly failure?: {
+    readonly seq: number
+    readonly time: number
+    readonly message: string
+    readonly code?: string
+  }
+}
+
+function lastStep(context: ConversationNodeContext<TurnErrorState>): number {
+  const location = context.start?.location ?? context.matches[0]?.location
+  if (location?.kind !== 'turn' && location?.kind !== 'step') return 0
+  return location.turn.steps.at(-1)?.step ?? 0
+}
+
+function retryTurn(event: Parameters<ConversationNodeDefinition['match']>[0]): number | undefined {
+  if ((event.type as string) !== 'llm/retry' && (event.type as string) !== 'llm/retry-started') return undefined
+  const turn = (event.data as unknown as { turn?: unknown }).turn
+  return Number.isSafeInteger(turn) && (turn as number) >= 0 ? turn as number : undefined
+}
+
+function failureFrom(match: ConversationMatch): TurnErrorState['failure'] | undefined {
+  if (match.event.type !== 'turn/end' || match.event.data.reason.kind !== 'error') return undefined
+  const failure = match.event.data.reason.error
+  return {
+    seq: match.event.seq,
+    time: match.event.time,
+    message: displayFailureMessage(failure),
+    code: failure.code,
+  }
+}
+
+function fallbackState(context: ConversationNodeContext<TurnErrorState>): TurnErrorState | undefined {
+  const end = context.matches.find(match => failureFrom(match) !== undefined)
+  if (end?.event.type !== 'turn/end') return undefined
+  const failure = failureFrom(end)
+  if (failure === undefined) return undefined
+  const turn = end.event.data.turn
+  return {
+    turn,
+    hidden: context.matches.some(match => retryTurn(match.event) === turn),
+    failure,
+  }
+}
+
+/** Terminal turn failure Definition, suppressed when the turn owns a retry chain. */
+export const turnErrorDefinition: ConversationNodeDefinition<TurnErrorState> = {
+  kind: 'turn-error',
+  match: (event) => {
+    if (event.type === 'turn/start') return { id: String(event.data.turn), role: 'start' }
+    if (event.type === 'turn/end' && event.data.reason.kind === 'error') {
+      return { id: String(event.data.turn), role: 'update' }
+    }
+    const turn = retryTurn(event)
+    return turn === undefined ? null : { id: String(turn), role: 'update' }
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'turn/start') throw new Error('turn-error start requires turn/start')
+    return { turn: match.event.data.turn, hidden: false }
+  },
+  update: (context, match) => {
+    const failure = failureFrom(match)
+    if (failure !== undefined) return { ...context.state, failure }
+    return retryTurn(match.event) === context.state.turn
+      ? { ...context.state, hidden: true }
+      : context.state
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const state = context.state ?? fallbackState(context)
+    if (state?.failure === undefined) return null
+    const failure = state.failure
+    const node: TurnErrorNode = {
+      kind: 'turn-error',
+      seq: failure.seq,
+      time: failure.time,
+      turn: state.turn,
+      step: lastStep(context),
+      message: failure.message,
+      ...failure.code === undefined ? {} : { code: failure.code },
+    }
+    if (!state.hidden) return chatNode(context, 'turn-error', node.seq, node)
+    const current = context.current.get('chat')
+    return current === undefined || current === null
+      ? null
+      : chatNode(context, 'turn-error', node.seq, node, { visibility: 'hidden' })
+  },
+}
+
+/**
+ * Register the terminal Turn-error business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerTurnErrorConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(turnErrorDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
new file mode 100644
index 0000000000..2a842a005d
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
@@ -0,0 +1,180 @@
+import type { Context } from 'cordis'
+import type {
+  ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, TurnLocation,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { isAppendSurfaceEvent, toAssistantBlocks } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  AssistantChatData, FinalAssistantChatData, TurnTailChatData,
+} from '../contract/chat-nodes.ts'
+import { deriveTurnMetrics } from '../chat/turn-metrics.ts'
+import { chatNode } from './common.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    /** Completed-turn actions and extension tail. */
+    'turn-tail': TurnTailChatData
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationTurnDataMap {
+    /** Closing Assistant and footer facts derived for this completed Turn. */
+    'turn-tail': TurnTailChatData
+  }
+}
+
+interface TurnTailState {
+  readonly turn: number
+  readonly end?: ConversationMatch
+}
+
+interface StepEvidence {
+  readonly streamedText: boolean
+  readonly finalized: boolean
+}
+
+function hasTextAssistant(event: Parameters<ConversationNodeDefinition['match']>[0]): boolean {
+  return event.type === 'assistant/message'
+    && isAppendSurfaceEvent(event)
+    && toAssistantBlocks(event.data.message.content)
+      .some(block => block.kind === 'text' && block.text.trim() !== '')
+}
+
+function chunkHasText(event: Parameters<ConversationNodeDefinition['match']>[0]): boolean {
+  if (event.type !== 'assistant/chunk') return false
+  const chunk = event.data.chunk
+  if (chunk.type === 'text-delta') return chunk.text.trim() !== ''
+  return chunk.type === 'block-end'
+    && chunk.block.type === 'text'
+    && chunk.block.text.trim() !== ''
+}
+
+function turnCoordinates(event: Parameters<ConversationNodeDefinition['match']>[0]): {
+  readonly turn: number
+  readonly step?: number
+} | undefined {
+  if (event.type === 'assistant/message'
+    || event.type === 'assistant/chunk'
+    || event.type === 'step/end') {
+    return { turn: event.data.turn, step: event.data.step }
+  }
+  if ((event.type as string) === 'llm/retry') {
+    return event.data as unknown as { turn: number; step: number }
+  }
+  return undefined
+}
+
+function closingAnchor(context: ConversationNodeContext<TurnTailState>): number {
+  let anchor = context.matches.find(match => match.event.type === 'turn/end')?.event.seq
+    ?? context.start?.event.seq
+    ?? context.matches[0]?.event.seq
+    ?? 0
+  const steps = new Map<number, StepEvidence>()
+  for (const match of context.matches) {
+    const event = match.event
+    if (event.type === 'turn/end') continue
+    const coordinates = turnCoordinates(event)
+    if (coordinates?.step === undefined) continue
+    const previous = steps.get(coordinates.step) ?? { streamedText: false, finalized: false }
+    if (event.type === 'assistant/chunk') {
+      steps.set(coordinates.step, {
+        ...previous,
+        streamedText: previous.streamedText || chunkHasText(event),
+      })
+      continue
+    }
+    if (event.type === 'assistant/message') {
+      steps.set(coordinates.step, { streamedText: false, finalized: true })
+      if (hasTextAssistant(event)) anchor = event.seq + 0.1
+      continue
+    }
+    if ((event.type as string) === 'llm/retry') {
+      steps.set(coordinates.step, { streamedText: false, finalized: false })
+      continue
+    }
+    if (event.type === 'step/end' && previous.streamedText && !previous.finalized) {
+      anchor = event.seq - 0.8
+    }
+  }
+  return anchor
+}
+
+function turnLocation(context: ConversationNodeContext<TurnTailState>): TurnLocation | undefined {
+  const location = context.start?.location ?? context.matches[0]?.location
+  return location?.kind === 'turn' || location?.kind === 'step' ? location.turn : undefined
+}
+
+function hasText(data: AssistantChatData): data is FinalAssistantChatData {
+  return data.finalNode !== undefined
+    && data.blocks.some(block => block.kind === 'text' && block.text.trim() !== '')
+}
+
+function tailData(context: ConversationNodeContext<TurnTailState>): TurnTailChatData | null {
+  const end = context.state?.end
+    ?? context.matches.find(match => match.event.type === 'turn/end')
+  if (end?.event.type !== 'turn/end') return null
+  const turn = turnLocation(context)
+  if (turn === undefined) return null
+  const assistants = turn.steps
+    .map(step => step.data.get('assistant-step'))
+    .filter((candidate): candidate is Readonly<AssistantChatData> => candidate !== undefined)
+  const finalized = assistants
+    .filter((candidate): candidate is Readonly<FinalAssistantChatData> => candidate.finalNode !== undefined)
+    .sort((left, right) => left.finalNode.seq - right.finalNode.seq)
+  const closing = finalized.findLast(hasText) ?? null
+  const latest = finalized.at(-1)
+  const metrics = deriveTurnMetrics(finalized.map(candidate => candidate.finalNode)).get(end.event.data.turn)
+  return {
+    turn: end.event.data.turn,
+    seq: end.event.seq,
+    time: end.event.time,
+    closing,
+    branchUnavailable: closing === null || latest?.finalNode.seq !== closing.finalNode.seq,
+    ...metrics?.ttftMs === undefined ? {} : { ttftMs: metrics.ttftMs },
+    ...metrics?.tokensPerSecond === undefined ? {} : { tokensPerSecond: metrics.tokensPerSecond },
+  }
+}
+
+/** Completed-turn footer Definition independent of any Assistant row. */
+export const turnTailDefinition: ConversationNodeDefinition<TurnTailState> = {
+  kind: 'turn-tail',
+  match: (event) => {
+    if (event.type === 'turn/start') return { id: String(event.data.turn), role: 'start' }
+    if (event.type === 'turn/end') return { id: String(event.data.turn), role: 'update' }
+    const coordinates = turnCoordinates(event)
+    if (coordinates !== undefined) return { id: String(coordinates.turn), role: 'update' }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'turn/start') throw new Error('turn-tail start requires turn/start')
+    return { turn: match.event.data.turn }
+  },
+  update: (context, match) => match.event.type === 'turn/end'
+    ? { ...context.state, end: match }
+    : context.state,
+  publication: match => match.event.type === 'turn/end' ? 'immediate' : 'none',
+  buildLocationData: (context, scope) => {
+    if (scope !== 'turn') return null
+    const value = tailData(context)
+    return value === null ? null : {
+      kind: 'turn',
+      turn: value.turn,
+      key: 'turn-tail',
+      value,
+    }
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat') return null
+    const turn = turnLocation(context)
+    const data = turn?.data.get('turn-tail')
+    return data === undefined ? null : chatNode(context, 'turn-tail', closingAnchor(context), data)
+  },
+}
+
+/**
+ * Register completed-Turn footer data and its Chat node contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export function registerTurnTailConversationNode(ctx: Context): void {
+  ctx.conversationEvents.register(turnTailDefinition)
+}
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index a19cd77753..b4d7467170 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -5,6 +5,17 @@
  */
 export { apply, inject } from './apply.ts'
 export { ConversationService } from './service.ts'
+export { registerAssistantConversationNode } from './conversation-nodes/assistant.ts'
+export { registerChatConversationView } from './conversation-nodes/chat-snapshot-builder.ts'
+export { registerCommandConversationNode } from './conversation-nodes/command.ts'
+export { registerCompactionConversationNode } from './conversation-nodes/compaction.ts'
+export { registerUnknownConversationFallback } from './conversation-nodes/fallback.ts'
+export { registerInboxConversationNodes } from './conversation-nodes/inbox.ts'
+export { registerMessageConversationNode } from './conversation-nodes/message.ts'
+export { registerRetryConversationNode } from './conversation-nodes/retry.ts'
+export { registerToolConversationNode } from './conversation-nodes/tool.ts'
+export { registerTurnErrorConversationNode } from './conversation-nodes/turn-error.ts'
+export { registerTurnTailConversationNode } from './conversation-nodes/turn-tail.ts'
 export type { IConversation } from './service.ts'
 
 export type {
@@ -12,12 +23,16 @@ export type {
 } from './contract/views.ts'
 export type { ConversationKey } from './locales.ts'
 export type {
-  ChatFileMentions,
+  AssistantChatData, ChatNode, ChatNodeDataMap, ChatNodeKind, ManualCompactionChatData,
+  RetryChatData, ToolChatData, TurnTailChatData,
+} from './contract/chat-nodes.ts'
+export type {
+  ChatFileMentions, ChatNodeOwnerProps, ChatNodeViewProps,
   ChatStore, ChatViewInjected, ChatViewSlotProps, CommandRowOwnerProps, CommandRowProps, ComposerBarInjected,
   ComposerChainProps, ConversationInjected,
   ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps, ConvViewOwnerProps,
   ConvViewProps, DetailsInjected, DetailsSlotProps, DetailsToolOwnerProps, EmptyWorkspaceOwnerProps,
-  ToolTreeOwnerProps, TurnTailOwnerProps,
+  TurnTailOwnerProps, UseChatNodeTurnData,
 } from './contract/slots.ts'
 // Export discipline: packages/client/AGENTS.md.
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
index a1a0a120f5..98e98f0f01 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
@@ -17,6 +17,7 @@ import { useMemo, useState } from 'react'
 import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { RunningToolCall } from '@deepseek-ai/dsh-client-runtime/client'
 import { PendingApproval, type ApprovalComposerProps } from '../contract/slots.ts'
+import { rootToolCall } from '../chat/tool-node-reader.ts'
 import css from './ApprovalPanel.module.css'
 
 /** Extract the shell command from an approval's paired running call (bash-family args carry `command`); undefined hides the line. */
@@ -40,8 +41,12 @@ export function commandOf(call: RunningToolCall | undefined): string | undefined
  */
 export function ApprovalPanel(props: ApprovalComposerProps) {
   const approval = useMemo(() => new PendingApproval(props.matched), [props.matched])
-  const command = props.useSession(s => commandOf(
-    approval.callId === undefined ? undefined : s.runningCalls.find(call => call.callId === approval.callId)))
+  const command = props.useSession((snapshot) => {
+    if (approval.callId === undefined) return undefined
+    const root = rootToolCall(snapshot, approval.callId)
+    if (root === undefined) return undefined
+    return root.callId === approval.callId && !('kind' in root) ? commandOf(root) : undefined
+  })
   return <ApprovalFlow key={approval.key} pending={approval} t={props.t} {...command === undefined ? {} : { command }} />
 }
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index a04e9ba9e8..1caefd2ecf 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -12,6 +12,7 @@ import { CodeBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import { shallowEqual } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { DetailsSlotProps } from '../contract/slots.ts'
+import { findToolCall } from '../chat/tool-node-reader.ts'
 import css from './DetailsPanel.module.css'
 
 /** Full props composed by reference from the contract (automatic shares & injected share). */
@@ -40,30 +41,10 @@ function runningMaterial(call: RunningToolCall): CallMaterial {
   return { name: call.name, argsRaw: call.argsRaw, block: call }
 }
 
-function findCall(block: ToolCallBlock, callId: string): ToolCallBlock | undefined {
-  if (block.callId === callId) return block
-  for (const child of block.subCalls) {
-    const found = findCall(child, callId)
-    if (found !== undefined) return found
-  }
-  return undefined
-}
-
 function materialFor(s: ConversationSnapshot, callId: string): CallMaterial | null {
-  for (const node of s.nodes) {
-    if (node.kind !== 'tool-result') continue
-    const found = findCall(node, callId)
-    if (found !== undefined) {
-      return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
-    }
-  }
-  for (const root of s.runningCalls) {
-    const found = findCall(root, callId)
-    if (found !== undefined) {
-      return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
-    }
-  }
-  return null
+  const found = findToolCall(s, callId)
+  if (found === undefined) return null
+  return 'kind' in found ? settledMaterial(found, callId) : runningMaterial(found)
 }
 
 function pretty(raw: string): string {
diff --git a/packages/client/ui-conversation/src/invariant.ts b/packages/client/ui-conversation/src/invariant.ts
index f9a7d46553..66c54081ab 100644
--- a/packages/client/ui-conversation/src/invariant.ts
+++ b/packages/client/ui-conversation/src/invariant.ts
@@ -17,7 +17,7 @@ export const inject = ['invariants']
 /**
  * No runtime invariant: the conversation service emits no cordis events, and
  * both rings this package owns (the 'conversation.view' tab ring and the
- * 'conversation.chat.tool' whole-call seat) ride the slot system, whose ledger
+ * 'conversation.chat.node' business renderer seat) ride the slot system, whose ledger
  * invariants live with the runtime slots package.
  */
 const install: InvariantInstaller = () => {}
diff --git a/packages/client/ui-deliverables/src/client/index.ts b/packages/client/ui-deliverables/src/client/index.ts
index 81b2f61b79..fb8bdd0224 100644
--- a/packages/client/ui-deliverables/src/client/index.ts
+++ b/packages/client/ui-deliverables/src/client/index.ts
@@ -12,7 +12,9 @@ import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-conversation/c
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import { ProducedFiles } from './ProducedFiles.tsx'
 import { en, NS, zh, type DeliverablesKey } from './locales.ts'
-import { producedFileMentions, selectProducedFiles } from './turn-deliverables.ts'
+import {
+  deliverablesDefinition, producedFileMentions, selectProducedFiles,
+} from './turn-deliverables.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -25,13 +27,14 @@ export { ProducedFiles, type ProducedFilesProps } from './ProducedFiles.tsx'
 export { producedForClosing } from './turn-deliverables.ts'
 
 /** Required services for the tail-slot registration and its dictionaries. */
-export const inject = ['slots', 'locale']
+export const inject = ['slots', 'locale', 'conversationEvents']
 
 /**
  * Client plugin body: register the dictionaries and the turn-tail entry.
  * @param ctx - client root context.
  */
 export function apply(ctx: ClientContext): void {
+  ctx.conversationEvents.register(deliverablesDefinition)
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-deliverables: dictionaries')
   ctx.slots.inject(
     'conversation.chat.turnTail',
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index 4316ddf8e6..0227b34261 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -1,12 +1,37 @@
 /**
- * Pure derivation of one turn's produced files from finalized snapshot
- * nodes. Client-only and model-free: the vocabulary is the mutation tools'
- * own follow-along `locations`, never the closing prose.
+ * Turn-scoped produced-file Definition and readers. Client-only and
+ * model-free: the vocabulary is the mutation tools' own follow-along
+ * `locations`, never the closing prose.
  */
-import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ConversationNodeDefinition, ToolResultNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
 import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
+interface ProducedPath {
+  readonly seq: number
+  readonly path: string
+}
+
+/** Immutable produced-file facts published against one Turn. */
+export interface DeliverablesTurnData {
+  readonly produced: readonly ProducedPath[]
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationTurnDataMap {
+    /** Successful mutation paths accumulated in this Turn. */
+    deliverables: DeliverablesTurnData
+  }
+}
+
+interface DeliverablesState extends DeliverablesTurnData {
+  readonly turn: number
+  readonly calls: ReadonlyMap<string, ToolResultNode['callView']>
+}
+
 /**
  * Paths a call view reports having created or changed, by render intent rather
  * than tool name: a diff card, or a generic card whose kind is `edit` (the
@@ -23,9 +48,7 @@ function producedPaths(view: ToolResultNode['callView']): readonly string[] {
 }
 
 /**
- * Files produced by the turn the assistant at `seq` closes — the anchor the
- * render site elects, so the row lands under the message that reports the
- * work rather than after some mid-turn narration.
+ * Files produced by one Turn data value.
  *
  * The source is the mutation tools' own follow-along `locations`, not the
  * closing prose: a produced file must be listed whether or not the model
@@ -37,46 +60,26 @@ function producedPaths(view: ToolResultNode['callView']): readonly string[] {
  * failed calls. Paths keep first-seen order and appear once, so a file written
  * and then edited in the same turn is one entry.
  *
- * Accumulation resets on the turn boundary — a user message, or a node
- * reporting a different turn number — so a turn that mutates files and then
- * ends without content text cannot spill its paths into the next turn's row,
- * nor leave the dedup set suppressing a file the next turn legitimately
- * rewrites. Tool results carry no turn of their own; the boundary is read off
- * the nodes that do, and a user message resets the tracked turn to undefined
- * because the next node to report one is stating the current turn, not
- * entering a new one.
- * @param nodes - snapshot nodes (surface order).
- * @param seq - the closing assistant's seq (the render site's anchor).
+ * The Conversation Location index owns turn membership before this function
+ * runs, so paths cannot spill across turns and this derivation does not infer
+ * boundaries from neighboring presentation Nodes.
+ * @param data - engine-published Deliverables data for one Turn.
+ * @param seq - closing Assistant seq; later Tool settlements are excluded.
  * @returns Produced paths in first-seen order; empty when the turn wrote nothing.
  */
-export function producedForClosing(nodes: readonly ConversationNode[], seq: number): readonly string[] {
-  let pending: string[] = []
-  let seen = new Set<string>()
-  let turn: number | undefined
-  for (const node of nodes) {
-    if (node.kind === 'tool-result') {
-      if (node.isError) continue
-      for (const path of producedPaths(node.callView)) {
-        if (seen.has(path)) continue
-        seen.add(path)
-        pending.push(path)
-      }
-      continue
-    }
-    if (node.kind === 'user') {
-      turn = undefined
-      pending = []
-      seen = new Set()
-    } else if ('turn' in node) {
-      if (turn !== undefined && node.turn !== turn) {
-        pending = []
-        seen = new Set()
-      }
-      turn = node.turn
-    }
-    if (node.kind === 'assistant' && node.seq === seq) return pending
+export function producedForClosing(
+  data: Readonly<DeliverablesTurnData> | undefined,
+  seq = Number.POSITIVE_INFINITY,
+): readonly string[] {
+  if (data === undefined) return []
+  const paths: string[] = []
+  const seen = new Set<string>()
+  for (const produced of data.produced) {
+    if (produced.seq > seq || seen.has(produced.path)) continue
+    seen.add(produced.path)
+    paths.push(produced.path)
   }
-  return []
+  return paths
 }
 
 /**
@@ -85,11 +88,55 @@ export function producedForClosing(nodes: readonly ConversationNode[], seq: numb
  * @returns Produced paths as the component's match, or null to decline before mount.
  */
 export function selectProducedFiles(owner: TurnTailOwnerProps): readonly string[] | null {
-  const { nodes, seq } = owner
-  const paths = producedForClosing(nodes, seq)
+  const paths = producedForClosing(owner.turn.data.get('deliverables'), owner.seq)
   return paths.length === 0 ? null : paths
 }
 
+/** Turn-local successful mutation accumulator; it publishes no view Node. */
+export const deliverablesDefinition: ConversationNodeDefinition<DeliverablesState> = {
+  kind: 'deliverables',
+  match: (event) => {
+    if (event.type === 'turn/start') return { id: String(event.data.turn), role: 'start' }
+    if (event.type === 'tool/call') return { id: String(event.data.turn), role: 'update' }
+    if (event.type === 'tool/result' && isAppendSurfaceEvent(event)) {
+      return { id: String(event.data.turn), role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'turn/start') throw new Error('deliverables start requires turn/start')
+    return { turn: match.event.data.turn, calls: new Map(), produced: [] }
+  },
+  update: (context, match) => {
+    if (match.event.type === 'tool/call') {
+      const calls = new Map(context.state.calls)
+      calls.set(
+        String(match.event.data.callId),
+        match.view?.for === 'call' ? match.view.view : null,
+      )
+      return { ...context.state, calls }
+    }
+    if (match.event.type !== 'tool/result') return context.state
+    const result = match.event.data.message.content[0]
+    if (result.isError === true) return context.state
+    const callId = String(match.event.data.message.source.callId)
+    const additions = producedPaths(context.state.calls.get(callId) ?? null)
+      .map(path => ({ seq: match.event.seq, path }))
+    return additions.length === 0
+      ? context.state
+      : { ...context.state, produced: [...context.state.produced, ...additions] }
+  },
+  buildLocationData: (context, scope) => scope !== 'turn' || context.state === undefined
+    ? null
+    : {
+      kind: 'turn',
+      turn: context.state.turn,
+      key: 'deliverables',
+      value: { produced: context.state.produced },
+    },
+  buildViewNode: () => null,
+}
+
 /**
  * Trailing path segment, the part that identifies the file at a glance.
  * @param path - Slash- or backslash-separated path.
diff --git a/packages/client/ui-tool/src/client/apply.ts b/packages/client/ui-tool/src/client/apply.ts
index 48a9a4c812..ec2f0b8ec1 100644
--- a/packages/client/ui-tool/src/client/apply.ts
+++ b/packages/client/ui-tool/src/client/apply.ts
@@ -20,8 +20,9 @@ export const inject = ['slots']
  * @param ctx - Client root context.
  */
 export function apply(ctx: ClientContext): void {
-  ctx.slots.inject('conversation.chat.tool', () => ctx.slots.register({
-    name: 'conversation.chat.tool',
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'tool-call',
     locale: NS,
     children: {
       'tool.call.toolview': { kind: 'keyed', scope: 'session' },
diff --git a/packages/client/ui-tool/src/client/contract/slots.ts b/packages/client/ui-tool/src/client/contract/slots.ts
index 4b74055b2c..26039efc6f 100644
--- a/packages/client/ui-tool/src/client/contract/slots.ts
+++ b/packages/client/ui-tool/src/client/contract/slots.ts
@@ -30,8 +30,8 @@ export interface ToolCallOwnerProps {
 /** Full props of a registered atomic Tool view. */
 export type ToolCallViewProps = PropsRuntime<'tool.call.toolview'>
 
-/** Full props of the Tool call-tree renderer registered into the chat flow. */
-export type ToolTreeProps = PropsRuntime<'conversation.chat.tool'>
+/** Full props of the Tool call-tree renderer registered as a `tool-call` Chat Node. */
+export type ToolTreeProps = PropsRuntime<'conversation.chat.node', 'tool-call'>
   & PropsRenderSlots<'tool.call.toolview'>
   & PropsLocale<'conversation'>
 
diff --git a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
index 278be7dacf..db3ed0af06 100644
--- a/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
+++ b/packages/client/ui-tool/src/client/tool/ToolCallTree.tsx
@@ -88,8 +88,9 @@ const ToolCallBranch = memo(function ToolCallBranch({
  * @returns the Tool call tree.
  */
 export function ToolCallTree({
-  renderSlot, block, selectedCallId, cwd, openFile, inspectCall, t,
+  renderSlot, node, selectedCallId, cwd, openFile, inspectCall, t,
 }: ToolTreeProps) {
+  const block = node.data.root
   return (
     <ToolCallBranch
       renderSlot={renderSlot}

From 522acc74324e6c529f4a9a18e2c6781d0b88b6be Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:48:56 +0800
Subject: [PATCH 488/516] test: update conversation assembly coverage and docs

---
 ...7-19-gui-web-client-architecture.i18n.yaml |   4 +-
 .../2026-07-19-gui-web-client-architecture.md |  27 +-
 ...26-07-19-gui-web-client-architecture.zh.md |  29 +-
 ...ient-tool-presentation-ownership.i18n.yaml |   4 +-
 ...8-08-client-tool-presentation-ownership.md | 101 +-
 ...8-client-tool-presentation-ownership.zh.md | 103 +-
 ...ranscript-log-ordered-projection.i18n.yaml |   4 +-
 ...0-web-transcript-log-ordered-projection.md |   2 +-
 ...eb-transcript-log-ordered-projection.zh.md |   2 +-
 apps/web/tests/built-boot.snapshot.ts         |   1 -
 .../tests/chat-continuous-conversation.e2e.ts |  20 +-
 apps/web/tests/chat-long-interactions.e2e.ts  |  49 +-
 apps/web/tests/search-card.snapshot.ts        |   4 +-
 apps/web/tests/seeded-history.e2e.ts          |  17 +-
 apps/web/tests/skill-user-invoke.e2e.ts       |   2 +
 .../snapshots/code-mode-round/session.jsonl   |   8 +-
 apps/web/tests/todo-row.snapshot.ts           |   2 +-
 docs/config-catalog.md                        |   4 +-
 docs/event-producer-consumer.md               |   2 +-
 docs/module-graph.md                          | 249 ++---
 docs/persistence-catalog.md                   |  54 +-
 docs/subsystems/commands.i18n.yaml            |   4 +-
 docs/subsystems/commands.md                   |   6 +-
 docs/subsystems/commands.zh.md                |   6 +-
 docs/subsystems/compaction.i18n.yaml          |   4 +-
 docs/subsystems/compaction.md                 |  11 +-
 docs/subsystems/compaction.zh.md              |  11 +-
 docs/subsystems/tools.i18n.yaml               |   4 +-
 docs/subsystems/tools.md                      |   9 +-
 docs/subsystems/tools.zh.md                   |   9 +-
 .../advanced-toolchain/session.jsonl          |   4 +-
 .../snapshots/both-mode-turn/session.jsonl    |   4 +-
 .../snapshots/code-mode-turn/session.jsonl    |   8 +-
 .../code-mode-workspace-context/session.jsonl |   4 +-
 .../cordis-inspect-jsdoc/session.jsonl        |   2 +-
 .../empty-response-retry/session.jsonl        |  19 +-
 .../advanced-toolchain/session.jsonl          |   4 +-
 .../stream-json.expected.jsonl                |   4 +-
 .../compaction-recovery/session.jsonl         |  20 +-
 .../stream-json.expected.jsonl                |   8 +-
 .../provider-retry/stream-json.expected.jsonl |  19 +-
 packages/bash/bash-env/tests/bash-env.spec.ts |   1 +
 .../client/connection/src/client/fixture.ts   |  48 +-
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |  10 +-
 packages/client/runtime/README.zh.md          |  10 +-
 .../client/runtime/tests/client-apply.spec.ts |  29 +-
 .../tests/compact-checkpoint-pin.spec.ts      |  52 -
 .../tests/conversation-assembler.spec.ts      | 892 ++++++++++++++++++
 .../tests/conversation-registry.spec.ts       | 126 +++
 packages/client/runtime/tests/event-script.ts |   4 +-
 .../client/runtime/tests/queue-store.spec.ts  |   1 -
 packages/client/runtime/tests/session.spec.ts | 808 ++++------------
 .../runtime/tests/transcript-adapter.spec.ts  | 567 -----------
 packages/client/test-runtime/src/fixtures.ts  |   2 +
 packages/client/test-runtime/src/index.ts     |   8 +-
 .../ui-conversation/tests/chat-apply.spec.tsx |  10 +-
 .../tests/chat-branch-tails.spec.tsx          | 161 ++--
 .../tests/chat-snapshot-fixture.ts            | 295 ++++++
 .../ui-conversation/tests/chat-stats.spec.tsx |  28 +-
 .../ui-conversation/tests/chat-view.spec.tsx  | 487 ++++------
 .../conversation-node-definitions.spec.ts     | 720 ++++++++++++++
 .../tests/gate-branch-tails.spec.tsx          |  20 +-
 .../ui-conversation/tests/input-bar.spec.tsx  |   5 +-
 .../tests/input-matrix.spec.tsx               |   5 +-
 .../tests/input-scenarios.spec.tsx            |   5 +-
 .../ui-conversation/tests/queue-dock.spec.tsx |   4 +-
 .../ui-conversation/tests/skeleton.spec.tsx   |   5 +-
 .../tests/produced-files.spec.tsx             | 284 ++++--
 .../client/ui-slots/tests/surface.spec.ts     |  11 +
 .../client/ui-slots/tests/type-chain.spec.tsx |  60 +-
 .../ui-tool/tests/assembly-surfaces.spec.tsx  |   3 +-
 .../ui-tool/tests/chat-code-subcalls.spec.tsx |  10 +-
 .../client/ui-tool/tests/diff-card.spec.tsx   |   7 +-
 .../client/ui-tool/tests/read-card.spec.tsx   |   7 +-
 .../client/ui-tool/tests/search-card.spec.tsx |   7 +-
 .../ui-tool/tests/terminal-card.spec.tsx      |   7 +-
 .../ui-tool/tests/tool-call-tree.spec.tsx     |  15 +-
 .../ui-tool/tests/tool-details-render.tsx     |  45 +-
 .../ui-tool/tests/toolview-slot.spec.tsx      |   3 +-
 .../client/ui-tool/tests/web-card.spec.tsx    |   7 +-
 .../web-react/tests/scoped-slots.spec.tsx     |  77 +-
 .../tests/command-compact.spec.ts             |  24 +-
 .../tests/loader-composition.spec.ts          |  30 +-
 .../compact-basic/tests/compact-basic.spec.ts |   8 +-
 .../tests/manual-compact.spec.ts              |  47 +-
 .../compact/compact/tests/compact.spec.ts     |  15 +-
 .../compact/compact/tests/invariant.spec.ts   | 194 +++-
 .../tests/workspace-context.spec.ts           |   6 +-
 packages/core/tools/tests/code-mode.spec.ts   |   5 +-
 packages/core/tools/tests/invariant.spec.ts   | 105 ++-
 .../agent-spine-demo/tests/agent-core.spec.ts |   1 +
 .../llm/llm-retry/tests/invariant.spec.ts     |  73 +-
 .../llm/llm-retry/tests/persistence.spec.ts   |   2 +
 packages/llm/llm-retry/tests/retry.spec.ts    |   2 +
 .../context-breakdown-projection.spec.ts      |   2 +
 .../tests/token-usage-projection.spec.ts      |   2 +
 .../tool-cordis/src/api-catalog.ts            |  16 +-
 .../llm-replay/tests/llm-replay.spec.ts       |  16 +-
 pnpm-lock.yaml                                |  18 +-
 scripts/gen-cordis-catalog.ts                 |   1 +
 101 files changed, 3970 insertions(+), 2295 deletions(-)
 delete mode 100644 packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
 create mode 100644 packages/client/runtime/tests/conversation-assembler.spec.ts
 create mode 100644 packages/client/runtime/tests/conversation-registry.spec.ts
 delete mode 100644 packages/client/runtime/tests/transcript-adapter.spec.ts
 create mode 100644 packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
 create mode 100644 packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index b7e331c934..f0cc648a10 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: 7567ac3cb8b1a580e145f8f0da49b6ec371a35bd
-2026-07-19-gui-web-client-architecture.zh.md: 9b682febf1bd1aad1a767b8b2db4e83dd993cf2f
+2026-07-19-gui-web-client-architecture.md: 5e927405e9012b5a56d82da8fcf600ca4aa1bd5b
+2026-07-19-gui-web-client-architecture.zh.md: 4294af099dce4e1345e625694a054661483f8d12
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index 7567ac3cb8..5e927405e9 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -44,35 +44,35 @@ Implementation homes: registry core and the props-share types in `packages/clien
 
 A service is a plugin's only API surface toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (api client + stream handles), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer installation contract), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
-There is no registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Tool presentation crosses one explicit package boundary: Runtime projects Code Dispatch topology into each root's recursive `subCalls`; ui-conversation places that ordered root into the single `'conversation.chat.tool'` seat without interpreting Tool names or topology; ui-tool renders the supplied tree and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components.
+There is no component registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Final Chat business Nodes dispatch through the keyed/session `'conversation.chat.node'` slot; ui-tool owns its `tool-call` entry, recursively renders the supplied `subCalls`, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))`; the declaration is the load and reload dependency ([decision](2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components. The target-neutral event and view registries are data assembly seams rather than parallel component registries ([decision](2026-08-09-client-conversation-node-assembly.md)).
 
 **Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport).
 
 ## The data object layer (`packages/client/runtime/src/client/sessions/`)
 
-Frames enter, snapshots exit, the projection sits between — React-free (zero React imports, grep-assertable):
+Frames enter, snapshots exit, the Conversation assembler sits between — React-free (zero React imports, grep-assertable):
 
 ```
-mux/host 帧（ConnectionController 泵入，sinks 注入）
+mux/host frames (ConnectionController pump, injected sinks)
         │
         ▼
 SessionManager.handleMuxEnvelope / handleHostEnvelope
-        │ 带 sessionId 的帧只投已存在实例（审批/问答 requested 例外：进 pendingBuffers 缓冲）
+        │ session frames target existing instances (requested waits buffer)
         ▼
-Session.handleMuxEnvelope ──► events 窗口（seq 连续升序）
-        │                        │ 定稿事件            │ chunk
-        │                        ▼                    ▼
-        │                TranscriptAdapter     PartialAccumulator
-        │                  （→ nodes）          （→ partial）
+Session.handleMuxEnvelope ──► contiguous Event window
+        │                        │ replace / prepend / append
+        │                        ▼
+        │                ConversationNodeAssembler
+        │                  Definitions -> Contexts -> view builders
         ▼
 Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──► 组件
 ```
 
 - **Session** (session.ts): lazily built, resident — once created it keeps eating frames in the background, so switching away and back renders instantly. Operations: `prompt`/`cancel` (RPC passthrough; failures land in the snapshot's `promptError`), `open` (pull the tail history page, idempotent), `loadOlder` (upward paging, reentry-guarded), `resync` (reconnect = clear the window and rerun open). Subscription: `subscribe`/`getSnapshot` (always the cached reference) — `implements ObservableSnapshot<ConversationSnapshot>`, with `useSelector = bindSnapshotSelector(this)` attached at construction, so a Session is directly a uSES source. Frame dispatch is one switch: `session/event` frames dedup by seq (the only dedup key), buffer while open is in flight, otherwise append + incremental projection; open/stitch merges the live buffer by seq and backfills once if `subscribed.lastSeq` outruns the window tail.
-- **ConversationSnapshot** (conversation.ts): the immutable snapshot contract — `nodes` (the human transcript, log-ordered), `partial`, `runningCalls`, `pending`, `running`, `removed`, `openState`, `hasMore`, `promptError` and kin. **Reference discipline** (the premise of memo and uSES): the top-level object is fresh on every change; an unchanged nodes projection keeps the same array reference, while a changed flow returns a new array that reuses unchanged element references; unchanged substructures reuse the previous snapshot's references.
+- **ConversationSnapshot** (conversation.ts): the top-level immutable snapshot contract. `chat` contains structural `order`, an identity-stable keyed Node reader, Turn/Step indexes, and the timeline; `nodes`, `partial`, `runningCalls`, `turnTimings`, and `turnEnds` are the compatibility slice for unmigrated Trajectory consumers. Pending interactions, queue, running, removal, open state, paging, and prompt errors remain Session facts. **Reference discipline** (the premise of memo and uSES): unchanged substructures and Node values keep their references; one business update replaces only the corresponding key's value unless its order or Location changes. React still subscribes to the Session as the sole observable source, while the framework-provided `useSession(selector)` isolates Node and Location aggregate updates.
 - **SessionManager** (manager.ts): instance cluster + frame entry + the session list. sessionId-bearing frames go only to existing instances (a mux broadcast must not instantiate every session); approval/question `requested` frames are the exception — they never land in history, so they buffer in `pendingBuffers` and replay on instantiation.
 - **Notifier** (notifier.ts): two channels chosen by change source. `markDirty()` (default; frame-driven changes always) batches per microtask — N changes, one notification, one re-render; the flush rebuilds the snapshot cache before notifying. `notifyNow()` (only direct echoes of user gestures) rebuilds and notifies in the same tick — controlled inputs roll the DOM back and jump the caret if their echo defers to a microtask. Frame-driven code using notifyNow collapses batching back to per-frame renders; banned.
-- **TranscriptAdapter / PartialAccumulator**: the transcript is the append-origin surface projected in log order (`isAppendSurfaceEvent` from `@deepseek-ai/dsh-session/surface`) plus one marker per landed compaction checkpoint — never the model surface, which shadows replaced ranges and would erase conversation the reader already saw. Node order is seq-monotonic by construction, so there is no core `seq === index` assertion to satisfy and no degradation branch. Chunks contribute no node (O(1) skip): the accumulator folds StreamChunks into `AssistantBlock[]`, a delta swapping only that block's reference, and the finalizing message discards the accumulator in the same batch (no flicker on promotion). Cost model: one chunk = one string concatenation + a dirty mark; an unsubscribed Session under a frame storm costs only the mark.
+- **ConversationNodeAssembler** (`runtime/src/client/conversation/`): the Session-owned incremental engine runs independently registered Definitions over raw events. `match(event)` selects `(kind, id)` without Context scans; start/update build Definition state; engine-computed Locations carry Turn/Step closure; backward Context reads record dependencies repaired by later prepends; `buildViewNode(target)` materializes only dirty Contexts. The Chat builder preserves structural order and per-key value identity, `useSession` selectors isolate consumption, and Assistant token publication coalesces to one animation frame. The [Conversation Node decision](2026-08-09-client-conversation-node-assembly.md) owns assembly, while [Tool presentation ownership](2026-08-08-client-tool-presentation-ownership.md) owns recursive Tool rendering.
 - **ConnectionController** (in `packages/client/connection`): opens the mux/host streams, pumps with for-await, reconnects with exponential backoff (500ms doubling to 10s, jitter, unlimited) behind a generation fence; sinks are injected one-way (the Controller does not know Session). Reconnect = rebuild: `onConnected` → list refresh + per-open-session resync. The object layer faces only `IApiClient`; Web carriage uses HTTP POST for the two client→server quadrants and [one WebSocket per logical stream](2026-08-04-websocket-downlink-carrier.md) for the two server→client quadrants, while the client class family remains the layering RFC's territory.
 
 ## The React face (`packages/client/web-react`)
@@ -95,6 +95,7 @@ src/client/
   contract/    shared slot and cross-domain types
   service.ts   cross-domain orchestration
   skeleton/    conversation shell and details host
+  conversation-nodes/ independently registered business Definitions and Chat builder
   chat/        ordered conversation view
   input/       composer state machine
   queue/       queued-message presentation
@@ -109,13 +110,13 @@ Domain implementation files never import a sibling domain; shared surfaces route
 
 - **A new UI feature** = a new plugin package: declare `dshClient` (+ `inject` topology) in package.json, write the browser half under `src/client/` (apply mounts services/stores and registers slots), keep the node half an empty apply unless there is host logic, build with the shared preset. Add the plugin to the host config; the manifest and loading follow automatically.
 - **A new slot**: see the [slot system standard RFC](2026-07-22-slot-type-chain-implementation.md) — merge the contract into `SlotMap`, declare it in the parent entry's `children`, render through the auto-injected `renderSlot` prop. Never export components globally.
-- **Consuming a new frame type**: sessionId-bearing → a branch in Session's dispatch switch; host-level → the Manager routing table; if the UI needs it, a `ConversationSnapshot` field with the reference discipline kept.
+- **Consuming a new frame type**: transport-only session frames → Session's dispatch switch; host-level frames → the Manager routing table; logged conversation business events → a Definition plus a keyed view renderer, without a Session business branch.
 - **Where does this state live**: business data (events, streaming, pending) → always the object layer; what the parent knows → owner props at the renderSlot site; private to one component (scroll, search text, expansion) → component state; shared across entries or surviving remounts (selection, drafts, panel widths) → an entry-declared store ([slot system standard](2026-07-22-slot-type-chain-implementation.md)).
 - **Notification channel**: frame-driven/async = `markDirty` batching; direct user-gesture echo whose controlled input needs the same tick = `notifyNow`.
 
 ## Consequences
 
-Token streams no longer shake the render tree: a frame storm costs unsubscribed sessions one dirty bit and the subscribed view one batched re-render per microtask (raf-batched for frame-driven stores). UI features load, fail, and get disabled as independent plugins — one crashing slot entry blacks out one card, one failed bundle fails loud before the UI flips in. The accepted costs: the loader/module-table machinery is bespoke infrastructure the team owns end to end; the one-flip boot (no progressive rendering) trades first-paint granularity for assembly simplicity; and the dual type programs make "which aggregate sees this file" a question developers occasionally have to answer.
+Token streams no longer shake the render tree: Assistant chunks update one business Context and publish its keyed Node at most once per animation frame; unrelated rows' selector results retain their references, so those rows do not re-render. UI features load, fail, and get disabled as independent plugins — one crashing slot entry blacks out one card, one failed bundle fails loud before the UI flips in. The accepted costs: the loader/module-table machinery is bespoke infrastructure the team owns end to end; the one-flip boot (no progressive rendering) trades first-paint granularity for assembly simplicity; and the dual type programs make "which aggregate sees this file" a question developers occasionally have to answer.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index 9b682febf1..4294af099d 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -44,35 +44,35 @@ slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-
 
 服务是插件对其他插件的唯一 API 面（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图坑注册）。名册：`ctx.connection`（api client + 流句柄）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装约定）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑的 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。Tool 展示跨越一条显式包边界：运行时把 Code Dispatch 拓扑投影进每个 root 递归的 `subCalls`；ui-conversation 把这个已排序 root 放进 single `'conversation.chat.tool'` seat，不解释 Tool 名称或拓扑；ui-tool 渲染传入的树，并声明 keyed/session 的 `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>', inject? }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托选中调用的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。
+slot 之外不存在第二种组件注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list 坑 entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。最终 Chat 业务 Node 通过 keyed/session `'conversation.chat.node'` slot 分发；ui-tool 拥有其中的 `tool-call` entry，递归渲染传入的 `subCalls`，并声明 keyed/session `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托 selected call 的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。与 target 无关的事件和 view registry 是数据组装缝，不是平行组件注册表（[决策](2026-08-09-client-conversation-node-assembly.md)）。
 
 **scope 寻址**与 host 侧 agent scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 
 ## 数据对象层（`packages/client/runtime/src/client/sessions/`）
 
-帧从这里进、快照从这里出、fold 坐在中间——React-free（零 React import，grep 可断言）：
+帧从这里进、快照从这里出、Conversation assembler 坐在中间——React-free（零 React import，grep 可断言）：
 
 ```
-mux/host 帧（ConnectionController 泵入，sinks 注入）
+mux/host frames (ConnectionController pump, injected sinks)
         │
         ▼
 SessionManager.handleMuxEnvelope / handleHostEnvelope
-        │ 带 sessionId 的帧只投已存在实例（审批/问答 requested 例外：进 pendingBuffers 缓冲）
+        │ session frames target existing instances (requested waits buffer)
         ▼
-Session.handleMuxEnvelope ──► events 窗口（seq 连续升序）
-        │                        │ 定稿事件            │ chunk
-        │                        ▼                    ▼
-        │                TranscriptAdapter     PartialAccumulator
-        │                  （→ nodes）          （→ partial）
+Session.handleMuxEnvelope ──► contiguous Event window
+        │                        │ replace / prepend / append
+        │                        ▼
+        │                ConversationNodeAssembler
+        │                  Definitions -> Contexts -> view builders
         ▼
 Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──► 组件
 ```
 
 - **Session**（session.ts）：懒建、常驻——建成后在后台持续吃帧，切走切回秒显。操作面：`prompt`/`cancel`（RPC 透传；失败落进快照的 `promptError`）、`open`（拉尾页 history，幂等）、`loadOlder`（向上翻页，防重入）、`resync`（重连 = 清窗口重跑 open）。订阅面：`subscribe`/`getSnapshot`（恒返缓存引用）——`implements ObservableSnapshot<ConversationSnapshot>`，构造时挂 `useSelector = bindSnapshotSelector(this)`，Session 本身就是 uSES 源。帧分发是一个 switch：`session/event` 帧按 seq 去重（唯一去重键），open 在途时缓冲，否则追加 + 增量投影；open/缝合按 seq 合并 live 缓冲并去重，`subscribed.lastSeq` 超出窗口尾则回补一次。
-- **ConversationSnapshot**（conversation.ts）：不可变快照约定——`nodes`（人类对话记录，日志序）、`partial`、`runningCalls`、`pending`、`running`、`removed`、`openState`、`hasMore`、`promptError` 等。**引用纪律**（memo 与 uSES 的前提）：顶层对象每变必新；未变化的 nodes 投影保持同一数组引用，消息流变化时返回新数组并复用未变化的元素引用；未变的子结构复用上一快照的引用。
+- **ConversationSnapshot**（conversation.ts）：顶层不可变快照契约。`chat` 包含结构化 `order`、identity 稳定的 keyed Node reader、Turn/Step index 和 timeline；`nodes`、`partial`、`runningCalls`、`turnTimings`、`turnEnds` 是未迁移 Trajectory 消费者使用的兼容 slice。pending interaction、queue、running、removed、open state、paging 和 prompt error 仍是 Session 信息。**引用纪律**（memo 与 uSES 的前提）：未变化的子结构和 Node value 保持引用；单个业务更新只替换对应 key 的 value，除非它的顺序或 Location 发生变化。React 仍只订阅 Session 这一处 observable source，并由框架提供的 `useSession(selector)` 隔离 Node 与 Location 聚合更新。
 - **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。
 - **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。
-- **TranscriptAdapter / PartialAccumulator**：对话记录是按日志顺序投影的 append 来源 surface（`@deepseek-ai/dsh-session/surface` 的 `isAppendSurfaceEvent`），外加每次落地的压缩检查点一个标记——绝不用模型 surface，后者遮蔽被替换的范围，会抹掉读者已经看过的对话。节点顺序天然按 seq 单调，因此既无核心 `seq === index` 断言需要满足，也没有降级分支。分片不贡献任何节点（O(1) 跳过）：累积器把 StreamChunk 折叠成 `AssistantBlock[]`，一次增量只换该块引用；定稿消息到达即在同一批内弃掉累积器（提升无闪烁）。成本模型：一个分片 = 一次字符串拼接 + 一个脏标记；帧风暴下未订阅的 Session 只花那个标记。
+- **ConversationNodeAssembler**（`runtime/src/client/conversation/`）：Session 拥有的增量引擎在原始事件上运行各自独立注册的 Definition。`match(event)` 无须扫描 Context 即可选出 `(kind, id)`；start/update 构造 Definition state；引擎计算的 Location 携带 Turn/Step 关闭信息；向前查询 Context 时记录依赖，并由后续 prepend 修复；`buildViewNode(target)` 只物化 dirty Context。Chat builder 保留结构顺序和 per-key value identity，`useSession` selector 负责消费隔离，Assistant token 发布则合并到每个 animation frame 一次。[Conversation Node 决策](2026-08-09-client-conversation-node-assembly.md)拥有组装边界，[Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)拥有 Tool 递归渲染。
 - **ConnectionController**（在 `packages/client/connection`）：开 mux/host 双流、for-await 泵入，代际围栏之内指数退避重连（500ms 翻倍至 10s 封顶、抖动、无限重试）；sinks 单向注入（Controller 不认识 Session）。重连 = 重建：`onConnected` → 列表刷新 + 各已打开会话 resync。对象层只面向 `IApiClient`；Web 承载以 HTTP POST 载两个 client→server 象限、以[每逻辑流一条 WebSocket](2026-08-04-websocket-downlink-carrier.md)载两个 server→client 象限，客户端类族归分层 RFC 属地。
 
 ## React 面（`packages/client/web-react`）
@@ -95,6 +95,7 @@ src/client/
   contract/    shared slot and cross-domain types
   service.ts   cross-domain orchestration
   skeleton/    conversation shell and details host
+  conversation-nodes/ independently registered business Definitions and Chat builder
   chat/        ordered conversation view
   input/       composer state machine
   queue/       queued-message presentation
@@ -108,14 +109,14 @@ src/client/
 ## 怎么开发
 
 - **新 UI 功能** = 新插件包：package.json 声明 `dshClient`（+ `inject` 拓扑），浏览器半边写在 `src/client/`（apply 挂服务/建 store、注册 slot），无 host 逻辑时 node 半边保持空 apply，用共享预设构建。把插件加进 host 配置；manifest 与装载随之自动跟上。
-- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——约定合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
-- **消费新帧类型**：带 sessionId → Session 分发 switch 加一个分支；host 级 → Manager 路由表；UI 需要时给 `ConversationSnapshot` 加字段并守住引用纪律。
+- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——契约合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
+- **消费新帧类型**：纯传输 session frame → Session 分发 switch；host 级 frame → Manager 路由表；已记录的 conversation 业务事件 → Definition 加 keyed view renderer，不增加 Session 业务分支。
 - **状态住哪**：业务数据（事件、流式、待答）→ 永远对象层；父知道的 → renderSlot 现场的 owner props；单组件私有（滚动、搜索词、展开集）→ 组件状态；跨 entry 共享或跨重挂载存活（选中、草稿、面板宽）→ entry 声明的 store（[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)）。
 - **通知通道**：帧驱动/异步 = `markDirty` 合批；受控输入需要同 tick 的用户手势直接回响 = `notifyNow`。
 
 ## Consequences
 
-token 流不再震荡渲染树：帧风暴对未订阅会话只花一个脏位，对被订阅视图每微任务一次合批重渲染（帧驱动 store 走 raf 合批）。UI 功能以独立插件的粒度装载、失败、停用——一个崩溃的 slot 注册项只黑一张卡，一个装载失败的 bundle 在 UI 切入之前大声报错。接受的代价：loader/模块表机件是团队端到端自持的定制基建；一次成型启动（无渐进渲染）用首屏粒度换装配简单；双类型 program 让「这个文件归哪个聚合」成为开发者偶尔要回答的问题。
+token 流不再震荡渲染树：Assistant chunk 只更新一个业务 Context，每 animation frame 最多发布一次对应 keyed Node；无关行的 selector 结果保持原引用，因此不会重渲染。UI 功能以独立插件的粒度装载、失败、停用——一个崩溃的 slot 注册项只黑一张卡，一个装载失败的 bundle 在 UI 切入之前大声报错。接受的代价：loader/模块表机件是团队端到端自持的定制基建；一次成型启动（无渐进渲染）用首屏粒度换装配简单；双类型 program 让「这个文件归哪个聚合」成为开发者偶尔要回答的问题。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
index 12e27bf58c..5cb66115e8 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.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 .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
-2026-08-08-client-tool-presentation-ownership.md: f12a116c34064186b6be1496e1071025221817c4
-2026-08-08-client-tool-presentation-ownership.zh.md: f5f7d71f1e05b27855d29acc223b340c8d89f1d8
+2026-08-08-client-tool-presentation-ownership.md: 3feefc3cfbe538024b8610394b9f170c423556e8
+2026-08-08-client-tool-presentation-ownership.zh.md: 031975fdebf5f72a19396f16b086a3abdcbca172
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
index f12a116c34..3feefc3cfb 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md
@@ -6,100 +6,63 @@ English | [中文](2026-08-08-client-tool-presentation-ownership.zh.md)
 
 ## Problem
 
-The Client Runtime already projects Tool calls into a stable lifecycle: it pairs call/result events by `callId`, preserves running and settled forms, and indexes Code Dispatch children by their root call. The chat view nevertheless owned the entire presentation stack. It placed root calls in ChatFlow, composed each root with its subcalls, dispatched every atomic call by Tool name, carried the generic fallback and card models, registered first-party Tool views, and reused those models in the details panel.
+Client Runtime already paired Tool call/result events by `callId` and could recover root/subcall topology from Code Dispatch events, but the Chat view also owned Tool placement in the conversation flow, recursive call-tree composition, Tool-name dispatch, the Generic fallback, card models, and first-party Tool renderers. `ui-conversation` therefore had to interpret every business Tool name; moving individual React components did not change that ownership, and removing atomic renderers left subcalls without a presentation owner.
 
-That ownership made `ui-conversation` interpret business Tool names and made subcalls an orphaned concern if an atomic Tool view moved elsewhere. A business package such as `ui-skill` could register a row, but it still depended on conversation's Tool-specific composition contract. Adding Tool-specific Session projection would duplicate a data model the Runtime already owns, while moving only individual React components would leave the composition and model coupling in place.
+Tool presentation needed an independent owner without adding a second registry beside Client slots or making every atomic Tool renderer understand root/subcall structure.
 
 ## Decision
 
-Tool is a first-class Client UI concept with one presentation owner, `@deepseek-ai/dsh-client-ui-tool`. Runtime normalizes Code Dispatch into recursive `ToolCallBlock` values: every root or child owns its next level through `subCalls`, and `ConversationSnapshot` exposes no separate parent-to-children map.
+Tool is a first-class Client UI presentation concept. `@deepseek-ai/dsh-client-ui-tool` owns root/subcall composition, atomic renderer dispatch by wire Tool name, the Generic fallback, card models, and details output. Business plugins register only their atomic Tool renderers and do not modify conversation or Session.
 
-“First-class concept” describes UI ownership only; it adds no Runtime data kind. `ConversationNode` remains the transcript projection, `ChatFlowItem` remains the render unit produced when conversation sorts and groups nodes, `ToolCallBlock` remains the standard data for one call, and `ToolCallTree` only composes root/subcall presentation within Tool. Command continues to render through the separate `'conversation.chat.commandview'` seat and does not become Tool.
+Conversation data assembly follows the later [Conversation business-node decision](2026-08-09-client-conversation-node-assembly.md). The `ui-conversation` Tool Definition pairs root call/result Session Events, folds Code Dispatch edges into recursive `ToolCallBlock.subCalls`, and emits one stable `tool-call` Chat Node. This data responsibility handles only official Tool identity and topology; it does not interpret presentation for concrete Tool names.
 
-`ui-conversation` owns ordered placement. `deriveChatFlow()` still decides where a settled Tool group appears, and `ChatView` still appends running calls, maintains scroll anchors and selection, and supplies host actions. For each root call it renders the single/session `'conversation.chat.tool'` seat with the root block, selected call id, session cwd, and open-file/inspect callbacks. It does not read Code Dispatch children, branch on Tool names, or import Tool-specific views and card models.
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) only places generic [`ChatNodeSeat`](../../../../packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx) entries in Chat snapshot `order`. A Seat dispatches `'conversation.chat.node'` by `node.kind`; [`ui-tool`](../../../../packages/client/ui-tool/src/client/apply.ts) registers the `tool-call` entry, and [`ToolCallTree`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx) recursively traverses the root block. Every root or child level dispatches through the same keyed/session `'tool.call.toolview'` child slot with `entryKey: toolName`, falling back to `GenericToolCard` when no registration exists.
 
-`ui-tool` occupies that whole-Tool seat. `ToolCallTree` recursively walks the root block's `subCalls` and routes every level through one keyed/session `'tool.call.toolview'` child slot using `entryKey: toolName`. An absent business registration renders `GenericToolCard`. It neither reads Session nor maintains a second call topology.
+A business Tool plugin receives one standard `ToolCallBlock`, identity, workspace cwd, and host actions; it does not read Session, Context, or the Conversation assembler. Skill remains an ordinary Tool and uses the same keyed-slot registration path as other business Tools.
 
-Business plugins register only atomic views against `'tool.call.toolview'`. Their owner payload is the standard Tool call block plus identity, cwd, and host actions; it carries no Session projector or conversation service. Skill remains an ordinary Tool and `ui-skill` registers the `skill` key through this slot. Existing first-party views live in `ui-tool` until a business package has a reason to own one independently.
-
-The details panel is a second Tool presentation site but not a call-tree owner. `ui-conversation` delegates its selected output body through the single/session `'conversation.details.tool'` seat; `ui-tool` renders the card-aware output and the seat fallback preserves raw result text when the plugin is absent. Card models therefore have one production owner without introducing a reverse implementation import.
-
-The Runtime remains the authority for Tool lifecycle and call topology. Code Dispatch is an official top-level concept because it changes parent/child identity; a private `ToolCallTree` shares one fold between live and history paths and projects its index into standard recursive call blocks. Ordinary Tool business differences stay at the keyed presentation contract, and this package boundary adds no Tool projector/fold registry.
+The details panel is a second Tool presentation point, not the call-tree owner. `ui-conversation` locates the selected call and delegates its output body through `'conversation.details.tool'`; `ui-tool` reuses the card model, while the conversation fallback retains raw result text when the plugin is absent.
 
 ## Runtime and render path
 
-This boundary starts at the Client's `ConversationSnapshot`; the full render path is:
-
 ```text
-ConversationSnapshot.nodes
-  -> deriveChatFlow()
-  -> settled tool-group positions ----+
-                                      |
-ConversationSnapshot.runningCalls     |
-  -> ChatView flow tail ---------------+-> ToolSeat
-                                           -> conversation.chat.tool
-                                           -> ToolCallTree
-                                                -> root ToolCallBlock
-                                                     `- subCalls[] (recursive)
-                                                          -> tool.call.toolview(entryKey = toolName)
-                                                               |- registered atomic view
-                                                               `- GenericToolCard fallback
+Session Event window
+  -> Tool Definition -> tool-call Chat Node (recursive ToolCallBlock)
+  -> ChatView -> ChatNodeSeat(entryKey = tool-call)
+  -> ToolCallTree
+       -> root/subCalls[] recursion
+       -> tool.call.toolview(entryKey = toolName)
+            |- registered atomic view
+            `- GenericToolCard fallback
 ```
 
-Runtime's [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) privately indexes child lifecycles by parent callId and is shared by the live [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) and historical [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) paths. It recursively projects children onto root `ToolCallBlock` values and copies only the owning ancestor path when a child changes. Unchanged siblings, other roots, and snapshot references with no Tool-topology change stay stable so React selectors and memoization can skip unrelated updates. Tool UI consumes this unified tree without repeating call/result pairing, historical replay, or cache indexing.
+## Ownership boundary
 
-[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) reruns [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts) only when the `nodes` reference changes. It groups consecutive settled Tool results into a `tool-group`, while running root calls append at the flow tail. Both paths ultimately enter the same `ToolSeat`, so settled and running forms share the whole-Tool seat. Selection is passed only to the root containing that call, and `ToolCallTree` then renders recursively within that local tree.
-
-## Code and responsibility boundaries
-
-| Owner | Primary code | Owns | Explicitly does not own |
-|---|---|---|---|
-| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts), [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts), [`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result pairing, running/settled lifecycle, recursive parent/child tree, snapshot structural sharing | Business views selected by Tool name |
-| `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts), [`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx), [`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow order, settled groups, running tail, scroll anchors, selection and host actions, whole-Tool seat declaration | subcall composition, `toolName` dispatch, Generic fallback, Tool card models |
-| `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts), [`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx), [`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall composition, atomic keyed dispatch, Generic fallback, Tool card models and built-in Tool views | ChatFlow ordering, Session Event fold |
-| Business Tool plugins | [`ui-skill` registration example](../../../../packages/client/ui-skill/src/client/index.ts) | Atomic views for one or more wire Tool names | root/subcall placement and lifecycle pairing |
-| Details path | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx), [`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected-call lookup, card-aware output, and raw fallback | chat call-tree composition |
-
-## Slot and owner contract
-
-A slot declaration also constrains render ownership. The conversation chat entry declares `'conversation.chat.tool'` through `children`, so only `ChatView` places the whole-Tool seat. When `ui-tool` registers that seat, its `children` declares `'tool.call.toolview'`, so only `ToolCallTree` renders the atomic Tool seat. Business plugins register keyed entries only; they neither participate in root/subcall composition nor establish a registry parallel to slots.
-
-The whole seat's `ToolTreeOwnerProps` carries the root `callId`, `toolName`, `ToolCallBlock`, `selectedCallId`, session `cwd`, `openFile(path)`, and `inspectCall(callId)`. `ToolCallTree` converts either a root or child into the same `ToolCallOwnerProps` and narrows inspect to a callback for that call. The atomic owner carries no `ReactNode`, Cordis `Context`, Session service, or projector; a business view consumes only one standard call block and host actions.
-
-The seat filler also preserves the conversation DOM contract on every root and child wrapper: `data-chat-anchor-key="call:<callId>"`, `data-chat-call-id`, and `data-selected="true"` on the selected call. `ChatView` consumes the anchor key to restore prepend/paging position; the Tool owner emits it because it alone composes child wrappers.
-
-Business plugins use one registration shape:
-
-```text
-ctx.slots.inject('tool.call.toolview', () =>
-  ctx.slots.register({
-    name: 'tool.call.toolview',
-    key: '<wire tool name>',
-  }, BusinessToolRow))
-```
-
-`ui-tool`'s [`apply()`](../../../../packages/client/ui-tool/src/client/apply.ts) registers the whole-Tool renderer, details renderer, and existing built-in atomic views. An existing independent business package can move only its keyed registration, as `ui-skill` does, without changing `ui-conversation` or Session.
-
-## Details path
-
-[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) locates the selected call recursively in `nodes` and `runningCalls` through their `subCalls`, and it owns input arguments, empty states, and panel lifecycle. It passes only `{ block, cwd }` to `'conversation.details.tool'`; [`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) reuses Tool card models to render the output. When `ui-tool` is absent, a settled call falls back to raw result text and a running call shows conversation's running fallback, so details never imports the Tool implementation in reverse.
+| Owner | Owns | Explicitly does not own |
+|---|---|---|
+| Client Runtime Conversation engine | Context identity, Location, history replay, view Node publication | Tool event meaning, call tree, Tool renderer |
+| `ui-conversation` Tool Definition | call/result pairing, Code Dispatch topology, running/settled/interrupted `ToolCallBlock`, Chat ordering anchor | Tool-name dispatch, card models, recursive React structure |
+| `ui-conversation` Chat view | keyed Node order, scroll anchors, selection, and host actions | Tool lifecycle, subcall composition, atomic Tool renderers |
+| `ui-tool` | root/subcall recursive rendering, atomic keyed dispatch, fallback, card models, and details output | Session Event fold, Chat ordering |
+| Business Tool plugin | atomic renderers for one or more wire Tool names | root/subcall placement, lifecycle pairing, Session projectors |
 
 ## Verification
 
-Test ownership follows production ownership. `ui-conversation` tests install a local whole-Tool seat probe and assert only ChatFlow placement, owner payload, and host contracts such as selection, open-file, and inspect; they do not import `ui-tool` production code or test helpers. `ui-tool` tests mount a real conversation host and verify root/subcall composition, keyed dispatch, generic fallback, concrete Tool UI, and plugin lifecycle.
+`ui-conversation` tests pin the Tool Definition's call/result pairing, Code Dispatch, interruption, and running-to-settled keyed identity without importing production `ui-tool` renderers. `ui-tool` tests mount the real conversation host and pin root/subcall recursion, keyed dispatch, Generic fallback, selection, details, and concrete Tool cards. Assembled Web tests cover the path with both plugins loaded.
 
 ## Alternatives considered
 
-**Keep atomic Tool slots under every conversation view.** Rejected: each view would have to reproduce root/subcall composition, and a Tool registration would be isolated by view even though its business meaning is Tool-wide. A whole-Tool seat preserves view-owned placement while giving the call tree one owner. This supersedes the per-view placement selected by the earlier [toolview dissolution](2026-07-23-toolview-dissolution.md), while retaining its keyed-slot and no-parallel-registry decisions.
+**Keep atomic Tool slots under every conversation view.** Rejected: every view would repeat root/subcall composition and Tool registration would split by view. The whole Tool renderer occupies one business Node slot in a view, while Tool owns atomic dispatch.
 
-**Move only the Tool React components and card models.** Rejected: `ChatView` would still own Tool-name dispatch and Code Dispatch composition, so the dependency would change file paths without changing responsibility.
+**Move only Tool React components and card models.** Rejected: conversation would still dispatch by Tool name and recurse through subcalls, so file movement would not create an ownership boundary.
 
-**Add business-specific Session projectors or folds.** Rejected: ordinary Tool views consume the standard call block already reconstructed by Runtime. A second registry would create two authorities for call identity and historical replay. Only a feature that changes logged topology or lifecycle earns a Runtime-level extension.
+**Create a Tool-specific projector/fold registry.** Rejected: the general Conversation assembler already owns Context identity, history windows, and publication. A second Runtime registry would create two lifecycle authorities.
 
-**Make each atomic Tool view render its own subcalls recursively.** Rejected: the atomic registrant receives one Tool call and should not know whether it is a root or child. Recursive root/child composition belongs centrally to `ui-tool`'s `ToolCallTree`.
+**Let every atomic Tool renderer recurse through its subcalls.** Rejected: an atomic registrant should understand one Tool call without knowing whether it is a root or child. `ToolCallTree` handles recursive structure once.
 
-**Import `ui-tool` components directly from `ui-conversation`.** Rejected: it would reverse the intended feature direction and make Tool presentation mandatory. Declared slots retain lifecycle ownership, fallback behavior, and independent plugin loading.
+**Let `ui-conversation` import `ui-tool` components directly.** Rejected: this would reverse the feature dependency and make Tool presentation mandatory. Slots preserve independent loading, lifecycle, and fallback behavior.
 
 ## Consequences
 
-`ui-conversation` becomes independent of Tool-name business presentation while retaining ChatFlow, selection, and host interaction responsibilities. Root calls and subcalls cannot drift onto different dispatch paths, and business packages can own atomic Tool presentation without Session changes. The cost is one new Client package and two cross-package slot contracts; `ui-tool` also deliberately depends on conversation's declared seats and locale namespace. The assembled Web bundle therefore mounts `ui-tool`; omitting it leaves chat Tool seats empty while the details seat keeps its raw-result fallback, without changing Session reconstruction.
+`ui-conversation` no longer depends on presentation for concrete Tool names, and root and subcalls cannot drift onto different dispatch paths. Business packages can independently own atomic Tool renderers; if `ui-tool` is absent, Conversation data assembly remains valid, Chat Nodes use the generic fallback, and details retain raw results.
+
+The cost is an explicit dependency from `ui-tool` on the business Node slot and locale namespace declared by conversation, plus one Tool-specific child slot. Tool Definition remains in `ui-conversation` because this change does not split packages; it can later move through the Conversation registry seam without changing the presentation ownership recorded here.
diff --git a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
index f5f7d71f1e..031975fdeb 100644
--- a/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md
@@ -6,100 +6,63 @@ Status: implemented
 
 ## Problem
 
-Client Runtime 已经把 Tool 调用投影成稳定的生命周期：它按 `callId` 配对 call/result 事件，保留 running 与 settled 两种形态，并按 root call 索引 Code Dispatch 子调用。但 chat view 仍拥有整套展示链路：它在 ChatFlow 中放置 root call，把每个 root 与 subcall 编排在一起，按 Tool 名称分发每个原子调用，携带通用 fallback 与 card model，注册第一方 Tool view，并在 details panel 中复用这些 model。
+Client Runtime 已经按 `callId` 配对 Tool call/result，并能从 Code Dispatch 事件恢复 root/subcall 拓扑，但 Chat view 曾同时拥有 Tool 在对话流中的放置、递归调用树、按 Tool 名称分发、Generic fallback、card model 和第一方 Tool renderer。`ui-conversation` 因此必须解释每个业务 Tool 名称；只移动单个 React 组件不会改变这层所有权，移走原子 renderer 后 subcall 也会成为无主逻辑。
 
-这种所有权迫使 `ui-conversation` 解释业务 Tool 名称；一旦原子 Tool view 被迁走，subcall 就会成为无主的遗留关注点。`ui-skill` 等业务包虽能注册一行视图，仍依赖 conversation 的 Tool 专属编排约定。增加 Tool 专属 Session projection 会重复 Runtime 已拥有的数据模型，而只移动单个 React 组件则会把编排与 model 耦合留在原地。
+Tool presentation 需要一个独立所有者，同时不能建立与 Client slot 平行的第二套注册表，也不能让每个原子 Tool renderer 自己理解 root/subcall 结构。
 
 ## Decision
 
-Tool 成为 Client UI 的一级概念，并由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有展示。Runtime 将 Code Dispatch 规范化为递归 `ToolCallBlock`：每个 root 或 child 通过自己的 `subCalls` 拥有下一层调用，`ConversationSnapshot` 不再公开单独的 parent-to-children map。
+Tool 是 Client UI 的一级展示概念，由 `@deepseek-ai/dsh-client-ui-tool` 统一拥有 root/subcall 编排、按 wire Tool name 的原子 renderer 分发、Generic fallback、card model 和 details output。业务插件只注册自己的原子 Tool renderer，不修改 conversation 或 Session。
 
-这里的“一级概念”只描述 UI 所有权，不增加 Runtime 数据种类。`ConversationNode` 仍是 transcript projection，`ChatFlowItem` 仍是 conversation 对节点进行排序与分组后得到的渲染单元，`ToolCallBlock` 仍是单次调用的标准数据，而 `ToolCallTree` 只负责 Tool 内部的 root/subcall 展示编排。Command 继续通过独立的 `'conversation.chat.commandview'` 席位渲染，不并入 Tool。
+Conversation 数据组装遵循后续的 [Conversation 业务节点决策](2026-08-09-client-conversation-node-assembly.md)。`ui-conversation` 的 Tool Definition 从 Session Event 配对 root call/result，把 Code Dispatch edge fold 成递归 `ToolCallBlock.subCalls`，并生成一个稳定的 `tool-call` Chat Node；这里的数据职责只处理官方 Tool identity 和拓扑，不解释具体 Tool 名称的展示。
 
-`ui-conversation` 拥有有序放置。`deriveChatFlow()` 仍决定 settled Tool group 在哪里出现，`ChatView` 仍追加 running call、维护滚动 anchor 与 selection，并提供宿主动作。对于每个 root call，它使用 root block、selected call id、session cwd 以及 open-file/inspect 回调渲染 single/session 的 `'conversation.chat.tool'` 席位。它不读取 Code Dispatch child、不按 Tool 名称分支，也不导入 Tool 专属 view 或 card model。
+[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只按 Chat snapshot 的 `order` 放置通用 [`ChatNodeSeat`](../../../../packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx)。Seat 以 `node.kind` 分发 `'conversation.chat.node'`；[`ui-tool`](../../../../packages/client/ui-tool/src/client/apply.ts) 注册 `tool-call` entry，并由 [`ToolCallTree`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx) 递归遍历 root block。每一层 root 或 child 都通过同一个 keyed/session `'tool.call.toolview'` 子 slot 以 `entryKey: toolName` 分发，缺少注册时渲染 `GenericToolCard`。
 
-`ui-tool` 占据这个整体 Tool 席位。`ToolCallTree` 直接递归遍历 root block 的 `subCalls`，并让每一层调用都通过同一个 keyed/session 的 `'tool.call.toolview'` 子 slot，以 `entryKey: toolName` 分发。业务未注册时渲染 `GenericToolCard`。它不读取 Session，也不维护第二份调用拓扑。
+业务 Tool 插件接收一个标准 `ToolCallBlock`、identity、workspace cwd 和宿主动作，不读取 Session、Context 或 Conversation assembler。Skill 仍是普通 Tool；它和其他业务 Tool 使用同一 keyed slot 注册路径。
 
-业务插件只对 `'tool.call.toolview'` 注册原子 view。其 owner payload 是标准 Tool call block 加 identity、cwd 与宿主动作，不携带 Session projector 或 conversation service。Skill 仍是普通 Tool，`ui-skill` 通过该 slot 注册 `skill` key。现有第一方 view 暂留在 `ui-tool`，直到某个业务包确有理由独立拥有它。
+details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 定位 selected call，并通过 `'conversation.details.tool'` 委托 output body；`ui-tool` 复用 card model，插件缺席时 conversation fallback 保留 raw result text。
 
-details panel 是第二个 Tool 展示点，但不是调用树所有者。`ui-conversation` 通过 single/session 的 `'conversation.details.tool'` 席位委托 selected output body；`ui-tool` 渲染能够识别 card 的输出，插件缺席时由席位 fallback 保留 raw result text。因此 card model 只有一个生产代码所有者，也不需要引入反向实现依赖。
-
-Runtime 仍是 Tool 生命周期与调用拓扑的权威。Code Dispatch 作为官方顶级概念改变 parent/child identity；私有 `ToolCallTree` 对 live 与 history 共用同一套 fold，并把索引投影成标准递归 call block。普通 Tool 业务差异停留在 keyed 展示约定，这个包边界不会增加 Tool projector/fold registry。
-
-## Runtime 与渲染链路
-
-这项边界从 Client 的 `ConversationSnapshot` 开始，完整渲染链路如下：
+## Runtime and render path
 
 ```text
-ConversationSnapshot.nodes
-  -> deriveChatFlow()
-  -> settled tool-group positions ----+
-                                      |
-ConversationSnapshot.runningCalls     |
-  -> ChatView flow tail ---------------+-> ToolSeat
-                                           -> conversation.chat.tool
-                                           -> ToolCallTree
-                                                -> root ToolCallBlock
-                                                     `- subCalls[] (recursive)
-                                                          -> tool.call.toolview(entryKey = toolName)
-                                                               |- registered atomic view
-                                                               `- GenericToolCard fallback
+Session Event window
+  -> Tool Definition -> tool-call Chat Node (recursive ToolCallBlock)
+  -> ChatView -> ChatNodeSeat(entryKey = tool-call)
+  -> ToolCallTree
+       -> root/subCalls[] recursion
+       -> tool.call.toolview(entryKey = toolName)
+            |- registered atomic view
+            `- GenericToolCard fallback
 ```
 
-Runtime 的 [`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts) 私下按 parent callId 索引 child lifecycle，并供 Live [`Session.buildSnapshot()`](../../../../packages/client/runtime/src/client/sessions/session.ts) 与历史 [`projectConversationHistory()`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) 共用。它把 children 递归投影到 root `ToolCallBlock`，child 变化时只复制所属祖先路径；未变化的 sibling、其他 root，以及没有 Tool 拓扑变化的 snapshot 引用保持稳定，供 React selector 与 memo 跳过无关更新。Tool UI 直接消费这两个路径统一后的树，不重复 call/result 配对、历史 replay 或缓存索引。
+## Ownership boundary
 
-[`ChatView`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx) 只在 `nodes` 引用变化时重新执行 [`deriveChatFlow()`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)，把连续 settled Tool result 合为 `tool-group`；running root call 则追加在 flow tail。两条路径最终都进入同一个 `ToolSeat`，因此 settled/running 形态共享整体 Tool 席位。selection 只传给包含该 call 的 root，`ToolCallTree` 再沿该 root 的局部树递归渲染。
-
-## 代码与职责边界
-
-| 所有者 | 主要代码 | 拥有的责任 | 明确不拥有 |
-|---|---|---|---|
-| Client Runtime | [`Session`](../../../../packages/client/runtime/src/client/sessions/session.ts)、[`ToolCallTree`](../../../../packages/client/runtime/src/client/sessions/tool-call-tree.ts)、[`history-fold.ts`](../../../../packages/client/runtime/src/client/session-history/history-fold.ts) | call/result 配对、running/settled 生命周期、递归 parent/child 树、snapshot 结构共享 | Tool 名称对应的业务视图 |
-| `ui-conversation` | [`chat-flow.ts`](../../../../packages/client/ui-conversation/src/client/chat/chat-flow.ts)、[`ChatView.tsx`](../../../../packages/client/ui-conversation/src/client/chat/ChatView.tsx)、[`slots.ts`](../../../../packages/client/ui-conversation/src/client/contract/slots.ts) | ChatFlow 顺序、settled group、running tail、scroll anchor、selection 与宿主动作、整体 Tool 席位声明 | subcall 组合、按 `toolName` 分发、Generic fallback、Tool card model |
-| `ui-tool` | [`apply.ts`](../../../../packages/client/ui-tool/src/client/apply.ts)、[`ToolCallTree.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolCallTree.tsx)、[`slots.ts`](../../../../packages/client/ui-tool/src/client/contract/slots.ts) | root/subcall 组合、原子 keyed dispatch、Generic fallback、Tool card model 与内置 Tool view | ChatFlow 排序、Session Event fold |
-| 业务 Tool 插件 | [`ui-skill` 注册例](../../../../packages/client/ui-skill/src/client/index.ts) | 一个或多个 wire Tool name 的原子 view | root/subcall 位置与生命周期配对 |
-| details 路径 | [`DetailsPanel.tsx`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx)、[`ToolDetails.tsx`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) | selected call 定位、card-aware output 与 raw fallback | chat 调用树编排 |
-
-## Slot 与 owner 约定
-
-slot 声明同时限定渲染所有权。conversation chat entry 通过 `children` 声明 `'conversation.chat.tool'`，因此只有 `ChatView` 放置整体 Tool 席位；`ui-tool` 注册该席位时再通过 `children` 声明 `'tool.call.toolview'`，因此只有 `ToolCallTree` 渲染原子 Tool 席位。业务插件只注册 keyed entry，不参与 root/subcall 编排，也不建立与 slot 平行的 registry。
-
-整体席位的 `ToolTreeOwnerProps` 携带 root `callId`、`toolName`、`ToolCallBlock`、`selectedCallId`、session `cwd`、`openFile(path)` 与 `inspectCall(callId)`。`ToolCallTree` 把 root 或 child 转成相同的 `ToolCallOwnerProps`，并把 inspect 收窄成当前 call 的回调。原子 owner 不携带 `ReactNode`、Cordis `Context`、Session service 或 projector；业务 view 只消费一个标准调用块和宿主动作。
-
-席位填充方还要在每个 root 和 child wrapper 上保留 conversation DOM 约定：`data-chat-anchor-key="call:<callId>"`、`data-chat-call-id`，以及 selected call 上的 `data-selected="true"`。`ChatView` 用 anchor key 恢复 prepend/paging 位置；child wrapper 由 Tool owner 独自编排，因此这些属性也由它输出。
-
-业务插件遵循同一个注册形态：
-
-```text
-ctx.slots.inject('tool.call.toolview', () =>
-  ctx.slots.register({
-    name: 'tool.call.toolview',
-    key: '<wire tool name>',
-  }, BusinessToolRow))
-```
-
-`ui-tool` 的 [`apply()`](../../../../packages/client/ui-tool/src/client/apply.ts) 注册整体 Tool renderer、details renderer 与现有内置原子 view；已有独立业务包可以像 `ui-skill` 一样只迁走自己的 keyed 注册，无需改动 `ui-conversation` 或 Session。
-
-## Details 路径
-
-[`DetailsPanel`](../../../../packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx) 在 `nodes` 与 `runningCalls` 的递归 `subCalls` 中定位 selected call，并拥有 input 参数、空态和面板生命周期。它只把 `{ block, cwd }` 交给 `'conversation.details.tool'`；[`ToolDetails`](../../../../packages/client/ui-tool/src/client/tool/ToolDetails.tsx) 复用 Tool card model 渲染 output。`ui-tool` 缺席时，settled call 回退为 raw result text，running call 显示 conversation 的 running fallback，因此 details 不反向导入 Tool 实现。
+| 所有者 | 拥有 | 明确不拥有 |
+|---|---|---|
+| Client Runtime Conversation engine | Context identity、Location、历史重放、view Node 发布 | Tool 事件含义、调用树、Tool renderer |
+| `ui-conversation` Tool Definition | call/result 配对、Code Dispatch 拓扑、running/settled/interrupted `ToolCallBlock`、Chat 排序 anchor | Tool 名称分发、card model、递归 React 结构 |
+| `ui-conversation` Chat view | keyed Node 顺序、scroll anchor、selection 与宿主动作 | Tool lifecycle、subcall 组合、原子 Tool renderer |
+| `ui-tool` | root/subcall 递归渲染、原子 keyed dispatch、fallback、card model 与 details output | Session Event fold、Chat 排序 |
+| 业务 Tool 插件 | 一个或多个 wire Tool name 的原子 renderer | root/subcall 位置、生命周期配对、Session projector |
 
 ## Verification
 
-测试归属跟随生产所有权。`ui-conversation` 的测试安装本地整体 Tool 席位替身，只验证 ChatFlow 位置、owner payload 与 selection、open-file、inspect 等宿主约定；它们不导入 `ui-tool` 的生产实现或测试 helper。`ui-tool` 的测试挂载真实 conversation 宿主，验证 root/subcall 编排、keyed dispatch、generic fallback、具体 Tool UI 与插件生命周期。
+`ui-conversation` 测试固定 Tool Definition 的 call/result、Code Dispatch、interruption 和 running-to-settled keyed identity，不导入 `ui-tool` 的生产 renderer。`ui-tool` 测试挂载真实 conversation 宿主，固定 root/subcall 递归、keyed dispatch、Generic fallback、selection、details 和具体 Tool card。组装后的 Web 测试覆盖两侧插件共同装载的路径。
 
 ## Alternatives considered
 
-**在每个 conversation view 下保留原子 Tool slot。** 拒绝：每个 view 都必须重复 root/subcall 编排，而且 Tool 注册会按 view 隔离，即使它的业务语义本应是 Tool 级。整体 Tool 席位保留 view 对放置位置的所有权，同时让调用树只有一个所有者。它取代了早期 [toolview 溶解](2026-07-23-toolview-dissolution.md)所选择的 per-view 放置方式，但保留 keyed slot 与不设平行 registry 的决策。
+**在每个 conversation view 下保留原子 Tool slot。** 拒绝：每个 view 都要重复 root/subcall 编排，Tool 注册也会按 view 分裂。整个 Tool renderer 占据 view 的一个业务 Node slot，原子分发由 Tool 自己拥有。
 
-**只移动 Tool React 组件与 card model。** 拒绝：`ChatView` 仍会拥有 Tool 名称分发与 Code Dispatch 编排，只是改变文件路径，没有改变责任。
+**只移动 Tool React 组件与 card model。** 拒绝：conversation 仍会按 Tool 名称分发并递归 subcall，文件位置变化不产生所有权边界。
 
-**增加业务专属 Session projector 或 fold。** 拒绝：普通 Tool view 消费 Runtime 已重建的标准 call block。第二套 registry 会为 call identity 与历史 replay 建立两个权威。只有会改变日志拓扑或生命周期的能力才应获得 Runtime 级扩展。
+**为 Tool 建立专属 projector/fold registry。** 拒绝：通用 Conversation assembler 已拥有 Context identity、历史窗口和发布；第二个 Runtime registry 会制造生命周期的双重权威。
 
-**让每个原子 Tool view 递归渲染自己的 subcall。** 拒绝：原子注册方只接收一个 Tool call，不应知道自己是 root 还是 child。递归 root/child 编排统一归 `ui-tool` 的 `ToolCallTree`。
+**让每个原子 Tool renderer 递归自己的 subcall。** 拒绝：原子注册方只应理解一个 Tool call，不应知道自己是 root 还是 child。递归结构统一由 `ToolCallTree` 处理。
 
-**让 `ui-conversation` 直接导入 `ui-tool` 组件。** 拒绝：这会反转预期的 feature 依赖方向，并把 Tool 展示变成必选能力。声明式 slot 能保留生命周期所有权、fallback 行为与独立插件装载。
+**让 `ui-conversation` 直接导入 `ui-tool` 组件。** 拒绝：这会反转 feature 依赖并把 Tool 展示变成必选能力。slot 保留独立装载、生命周期和 fallback。
 
 ## Consequences
 
-`ui-conversation` 不再依赖 Tool 名称对应的业务展示，同时保留 ChatFlow、selection 与宿主交互责任。root call 与 subcall 不会漂移到不同分发路径，业务包无需修改 Session 即可拥有原子 Tool 展示。代价是新增一个 Client package 与两份跨包 slot 约定；`ui-tool` 也明确依赖 conversation 声明的席位与 locale namespace。因此组装后的 Web bundle 会挂载 `ui-tool`；省略该插件时，chat Tool 席位为空，details 席位则保留 raw-result fallback，且 Session 重建不受影响。
+`ui-conversation` 不再依赖 Tool 名称对应的业务展示，root 与 subcall 也不会漂移到不同分发路径。业务包可以独立拥有原子 Tool renderer；`ui-tool` 缺席时，Conversation 数据组装仍然成立，Chat Node 使用通用 fallback，details 保留 raw result。
+
+代价是 `ui-tool` 明确依赖 conversation 声明的业务 Node slot 和 locale namespace，并拥有一个 Tool 专属子 slot。Tool Definition 暂时位于 `ui-conversation`，因为本次没有拆 package；它以后可以沿 Conversation registry seam 移动，而不会改变本 Note 规定的展示所有权。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index 231502dcb7..1ea341085d 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: e261ccba597f27149a9527f99b93454dfe5fe5fb
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 5684a8157bb7e1b23cd868fa13ab201ffd07a274
+2026-07-30-web-transcript-log-ordered-projection.md: feefc951118c8511237c931a13070e1f7db1fd16
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 711e57b29742171d1861f25e63019b64356b4cad
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index e261ccba59..feefc95111 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -39,7 +39,7 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 Renaming the Service Definition's plugin id is now a compile error in the client: `TS2322: Type '"compact"' is not assignable to type '"compaction"'`. The import must stay **type-only** — a value import of any `@deepseek-ai` package that is neither a platform module nor an inline-safe wire layer is rejected by the client purity gate (`packages/client/tsdown.client.ts`), whose own message records that type-only imports are erased and never reach it. A type-only leaf import needs both a `tsconfig.base.json` `paths` entry and `{"path": "../../compact/compact"}` in `packages/client/runtime/tsconfig.json` `references`: composite `rootDir` rules apply to erased imports as well, and without the reference the diagnostic is `TS6059`/`TS6307`.
 
-`packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` stays as the behavioral half, driving the adapter with a checkpoint built from the canonical **value**. The test value-imports the cordis-free `@deepseek-ai/dsh-compact/checkpoint` leaf and deliberately never loads the compact package root or the host-side `Context` merges reachable through it.
+`packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts` is the behavioral half, driving the compaction Definition with checkpoint and provenance records and proving that an older page can fill missing summary data. The Definition's type-only leaf import keeps the client isolated from the compact package root and the host-side `Context` merges reachable through it.
 
 The divergence from the terminal is therefore narrow: both frontends recognize a checkpoint from the same declaration — the terminal value-imports `isCompactCheckpointSource` host-side, where no gate applies, and the client pins the type.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 5684a8157b..711e57b297 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -39,7 +39,7 @@ const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
 
 重命名 Service Definition 的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。
 
-`packages/client/runtime/tests/compact-checkpoint-pin.spec.ts` 作为行为侧的另一半保留，用由权威**值**构造的检查点驱动适配器。该测试以值导入方式从不含 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 叶子路径取得该值，并刻意不加载 compact 包根或经由它可达的宿主侧 `Context` 合并。
+`packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts` 是行为侧的另一半，用检查点与溯源记录驱动压缩 Definition，并证明后续加载的旧分页可以补齐缺失的摘要数据。Definition 仅类型导入该叶子路径，使客户端继续与 compact 包根及经由它可达的宿主侧 `Context` 合并隔离。
 
 因此与终端的分歧很窄：两个前端都从同一份声明识别检查点——终端在宿主侧值导入 `isCompactCheckpointSource`（那里不适用任何门禁），客户端钉住类型。
 
diff --git a/apps/web/tests/built-boot.snapshot.ts b/apps/web/tests/built-boot.snapshot.ts
index 80661a0b13..be719bda15 100644
--- a/apps/web/tests/built-boot.snapshot.ts
+++ b/apps/web/tests/built-boot.snapshot.ts
@@ -38,7 +38,6 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn
   await waitFor(() => {
     expect(document.querySelector('[data-sample="bash"]')).not.toBeNull()
   }, { timeout: 10_000 })
-
   // Resolve the resident approval so the ordinary composer bar (which owns
   // ContextMeter) resumes without replacing the session shell. This minimal
   // boot graph intentionally does not mount the separate question UI plugin.
diff --git a/apps/web/tests/chat-continuous-conversation.e2e.ts b/apps/web/tests/chat-continuous-conversation.e2e.ts
index 61701c1cdc..a7b659dab2 100644
--- a/apps/web/tests/chat-continuous-conversation.e2e.ts
+++ b/apps/web/tests/chat-continuous-conversation.e2e.ts
@@ -12,6 +12,7 @@ import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { CallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
 import type { ReplayEntry, ReplayOverrideDoc } from '@deepseek-ai/dsh-llm-replay'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import { conversationContextKey } from '@deepseek-ai/dsh-client-runtime/client'
 import {
   launchWebScaffold,
   watchConsole,
@@ -160,6 +161,14 @@ function toolResultText(event: Extract<SessionEvent, { type: 'tool/result' }>):
     .join('')
 }
 
+function messageKey(event: SessionEvent<'user/message'>): string {
+  return conversationContextKey('input-message', String(event.data.id))
+}
+
+function assistantKey(event: SessionEvent<'assistant/message'>): string {
+  return conversationContextKey('assistant-step', `${event.data.turn}:${event.data.step}`)
+}
+
 describe('web e2e: continuous conversation grown through the composer', () => {
   let browser: Browser
   let page: Page
@@ -222,6 +231,11 @@ describe('web e2e: continuous conversation grown through the composer', () => {
       const settled = scaffold.whenTurnSettled(60_000)
       await page.getByRole('button', { name: 'Send message', exact: true }).click()
       await page.getByText(spec.userMarker, { exact: false }).last().waitFor({ timeout: 15_000 })
+      await expect.poll(() => sessionEvents.slice(eventStart).some(event => (
+        event.type === 'user/message'
+        && event.data.source.kind === 'user'
+        && userText(event).includes(spec.userMarker)
+      )), { timeout: 15_000 }).toBe(true)
       const echoedUser = sessionEvents.slice(eventStart).find(
         (event): event is SessionEvent<'user/message'> => (
           event.type === 'user/message'
@@ -230,7 +244,7 @@ describe('web e2e: continuous conversation grown through the composer', () => {
         ),
       )
       if (echoedUser === undefined) throw new Error(`turn ${String(spec.index)} has no user echo event`)
-      const userRow = page.locator(`[data-chat-anchor-key="node:${String(echoedUser.seq)}"]`)
+      const userRow = page.locator(`[data-chat-anchor-key="${messageKey(echoedUser)}"]`)
       await expect.poll(() => userRow.count(), { timeout: 10_000 }).toBe(1)
       expect(await userRow.getAttribute('data-chat-flow-kind')).toBe('user')
       expect(await userRow.textContent()).toContain(spec.userMarker)
@@ -274,9 +288,9 @@ describe('web e2e: continuous conversation grown through the composer', () => {
       expect(turnEnds[0]?.data).toEqual({ turn: spec.index, reason: { kind: 'completed' } })
       expect(chunks).toHaveLength(spec.deltas.length + (spec.callId === undefined ? 4 : 9))
 
-      const assistantRow = page.locator(`[data-chat-anchor-key="node:${String(finalAssistants[0]!.seq)}"]`)
+      const assistantRow = page.locator(`[data-chat-anchor-key="${assistantKey(finalAssistants[0]!)}"]`)
       await expect.poll(() => assistantRow.count(), { timeout: 10_000 }).toBe(1)
-      expect(await assistantRow.getAttribute('data-chat-flow-kind')).toBe('assistant')
+      expect(await assistantRow.getAttribute('data-chat-flow-kind')).toBe('assistant-step')
       expect(await assistantRow.textContent()).toContain(spec.doneMarker)
 
       const calls = turnEvents.filter((event): event is SessionEvent<'tool/call'> => event.type === 'tool/call')
diff --git a/apps/web/tests/chat-long-interactions.e2e.ts b/apps/web/tests/chat-long-interactions.e2e.ts
index b9bebbd897..cd1fcb2fa7 100644
--- a/apps/web/tests/chat-long-interactions.e2e.ts
+++ b/apps/web/tests/chat-long-interactions.e2e.ts
@@ -10,6 +10,7 @@ import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import type { StreamChunk } from '@deepseek-ai/dsh-llm'
 import type { ReplayEntry, ReplayOverrideDoc } from '@deepseek-ai/dsh-llm-replay'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import { conversationContextKey } from '@deepseek-ai/dsh-client-runtime/client'
 import { createChatScrollFixture } from './chat-scroll-fixture.ts'
 import {
   launchWebScaffold,
@@ -115,6 +116,18 @@ function requiredEvent<T extends SessionEvent['type']>(
   return event
 }
 
+function messageKey(event: SessionEvent<'user/message'>): string {
+  return conversationContextKey('input-message', String(event.data.id))
+}
+
+function assistantKey(event: SessionEvent<'assistant/message'>): string {
+  return conversationContextKey('assistant-step', `${event.data.turn}:${event.data.step}`)
+}
+
+function turnTailKey(turn: number): string {
+  return conversationContextKey('turn-tail', String(turn))
+}
+
 describe('web e2e: long Chat interaction contract', () => {
   let browser: Browser
   let page: Page
@@ -176,8 +189,10 @@ describe('web e2e: long Chat interaction contract', () => {
     const expectedUserText = textContent(branchUserEvent.data.content)
 
     await wheelUntilMounted(page, `[data-chat-call-id="${TARGET_CALL_2}"]`, -1_100)
-    const toolUserRow = page.locator(`[data-chat-anchor-key="node:${String(toolUserEvent.seq)}"]`)
-    const toolAssistantRow = page.locator(`[data-chat-anchor-key="node:${String(toolAssistantEvent.seq)}"]`)
+    const toolUserKey = messageKey(toolUserEvent)
+    const toolAssistantKey = assistantKey(toolAssistantEvent)
+    const toolUserRow = page.locator(`[data-chat-anchor-key="${toolUserKey}"]`)
+    const toolAssistantRow = page.locator(`[data-chat-anchor-key="${toolAssistantKey}"]`)
     const call1 = page.locator(`[data-chat-call-id="${TARGET_CALL_1}"]`)
     const call2 = page.locator(`[data-chat-call-id="${TARGET_CALL_2}"]`)
 
@@ -186,28 +201,27 @@ describe('web e2e: long Chat interaction contract', () => {
     expect(await call1.count()).toBe(1)
     expect(await call2.count()).toBe(1)
     expect(await toolUserRow.getAttribute('data-chat-flow-kind')).toBe('user')
-    expect(await toolAssistantRow.getAttribute('data-chat-flow-kind')).toBe('assistant')
+    expect(await toolAssistantRow.getAttribute('data-chat-flow-kind')).toBe('assistant-step')
     expect(await toolUserRow.textContent()).toContain(toolUserMarker)
     expect(await toolAssistantRow.textContent()).toContain(toolAssistantMarker)
     expect(await call1.textContent()).toContain(toolMarker1)
     expect(await call2.textContent()).toContain(toolMarker2)
 
     const expectedOrder = [
-      `node:${String(toolUserEvent.seq)}`,
-      `call:${TARGET_CALL_1}`,
-      `call:${TARGET_CALL_2}`,
-      `node:${String(toolAssistantEvent.seq)}`,
+      toolUserKey,
+      conversationContextKey('tool-call', TARGET_CALL_1),
+      conversationContextKey('tool-call', TARGET_CALL_2),
+      toolAssistantKey,
     ]
     const actualOrder = await page.locator('[data-chat-anchor-key]').evaluateAll((rows, keys) => (
       rows.map(row => (row as HTMLElement).dataset.chatAnchorKey)
         .filter((key): key is string => key !== undefined && keys.includes(key))
     ), expectedOrder)
     expect(actualOrder).toEqual(expectedOrder)
-    const groupKeys = await Promise.all([call1, call2].map(row => row.evaluate(element => (
-      element.closest<HTMLElement>('[data-chat-flow-kind="tool-group"]')?.dataset.chatFlowKey ?? null
+    const toolKinds = await Promise.all([call1, call2].map(row => row.evaluate(element => (
+      element.closest<HTMLElement>('[data-chat-flow-kind]')?.dataset.chatFlowKind ?? null
     ))))
-    expect(groupKeys[0]).not.toBeNull()
-    expect(groupKeys[1]).toBe(groupKeys[0])
+    expect(toolKinds).toEqual(['tool-call', 'tool-call'])
 
     const summary1 = call1.locator('[data-sample="bash"]')
     const summary2 = call2.locator('[data-sample="bash"]')
@@ -219,9 +233,12 @@ describe('web e2e: long Chat interaction contract', () => {
     expect(await summary1.getAttribute('aria-expanded')).toBe('false')
     await call2.getByText(`${toolMarker2} output line 12`, { exact: true }).waitFor({ timeout: 10_000 })
 
-    await wheelUntilMounted(page, `[data-chat-anchor-key="node:${String(branchUserEvent.seq)}"]`, -1_100)
-    const userRow = page.locator(`[data-chat-anchor-key="node:${String(branchUserEvent.seq)}"]`)
-    const assistantRow = page.locator(`[data-chat-anchor-key="node:${String(branchAssistantEvent.seq)}"]`)
+    const branchUserKey = messageKey(branchUserEvent)
+    const branchAssistantKey = assistantKey(branchAssistantEvent)
+    await wheelUntilMounted(page, `[data-chat-anchor-key="${branchUserKey}"]`, -1_100)
+    const userRow = page.locator(`[data-chat-anchor-key="${branchUserKey}"]`)
+    const assistantRow = page.locator(`[data-chat-anchor-key="${branchAssistantKey}"]`)
+    const turnTailRow = page.locator(`[data-chat-anchor-key="${turnTailKey(BRANCH_TURN)}"]`)
     expect(await userRow.textContent()).toContain(branchUserMarker)
     expect(await assistantRow.textContent()).toContain(branchAssistantMarker)
     await page.context().grantPermissions(['clipboard-read', 'clipboard-write'])
@@ -230,8 +247,8 @@ describe('web e2e: long Chat interaction contract', () => {
     await expect.poll(() => page.evaluate(() => navigator.clipboard.readText()), { timeout: 5_000 })
       .toBe(expectedUserText)
 
-    await assistantRow.hover()
-    await assistantRow.getByRole('button', { name: 'Branch into a new conversation', exact: true }).click()
+    await turnTailRow.hover()
+    await turnTailRow.getByRole('button', { name: 'Branch into a new conversation', exact: true }).click()
     await expect.poll(
       () => scaffold.ctx.agents.list().find(agent => agent.session.header.parentSession === SessionId(SESSION_ID)),
       { timeout: 15_000 },
diff --git a/apps/web/tests/search-card.snapshot.ts b/apps/web/tests/search-card.snapshot.ts
index 8e6322c4af..8ac775be1d 100644
--- a/apps/web/tests/search-card.snapshot.ts
+++ b/apps/web/tests/search-card.snapshot.ts
@@ -2,7 +2,7 @@
 // Assembled search-card snapshot: boots the real built workspace client bundles
 // through AppWebEntry's ModuleLoader path against the keyless
 // FixtureApiClient transport (no API key, no model round), opens the fixture
-// session, and pins the search card the `grep` turn (fixture turn 66) renders in
+// session, and pins the search card the `grep` turn (fixture turn 67) renders in
 // the assembled application. The built-boot smoke proves the graph boots but
 // carries no behavior assertions by contract; this is the assembled-output check
 // that a broken SearchRow registration or a dropped card would fail — the
@@ -51,7 +51,7 @@ describe('assembled search card', () => {
     const tree = await screen.findByRole('tree', { name: 'Sessions' }, { timeout: 10_000 })
     fireEvent.click(await within(tree).findByText('Fixture 历史会话'))
     // Wait for chat content to reach the fixture's later turns (the bash sample
-    // is turn 65, the grep card turn 66).
+    // is turn 66, the grep card turn 67).
     await waitFor(() => {
       expect(document.querySelector('[data-sample="bash"]')).not.toBeNull()
     }, { timeout: 10_000 })
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index 072a322fb6..8a9ee26866 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -91,11 +91,15 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
     return taken
   }
   const commandId = 'cmd-seeded-manual-compact'
+  const compactionId = 'compact-seeded-manual-compact'
   at({
     type: 'command/run',
     data: { commandId, name: 'compact', args: '', source: { kind: 'user' } },
   })
-  const startSeq = at({ type: 'compact/start', data: { turn: null } })
+  const startSeq = at({
+    type: 'compact/start',
+    data: { compactionId, sourceCommandId: commandId, turn: null },
+  })
   // Load-bearing exactness: the projections subtract this count verbatim, so
   // it must equal what the host's fold prices for these nodes. The estimator
   // prices message CONTENT only, so a minimal wrapper per storage shape is
@@ -124,6 +128,8 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
   const summarySeq = at({
     type: 'compact/summary',
     data: {
+      compactionId,
+      sourceCommandId: commandId,
       summary: [{
         type: 'text',
         text: '## Cold resume compact summary\n\n- The exact summary remains available.',
@@ -142,12 +148,17 @@ function withCompaction(raw: string, meter: TokenMeterService): string {
         type: 'text',
         text: '<context_checkpoint>Model-only compact checkpoint.</context_checkpoint>',
       }],
-      source: { kind: 'plugin', plugin: 'compact' },
+      source: {
+        kind: 'plugin', plugin: 'compact', compactionId, sourceCommandId: commandId,
+      },
     },
     surfaceOp: { op: 'replace', start: first, end: last },
     sourceEventSeqs: [startSeq, summarySeq, ...surfaceSeqs],
   })
-  at({ type: 'compact/end', data: { turn: null } })
+  at({
+    type: 'compact/end',
+    data: { compactionId, sourceCommandId: commandId, turn: null },
+  })
   at({
     type: 'command/done',
     data: {
diff --git a/apps/web/tests/skill-user-invoke.e2e.ts b/apps/web/tests/skill-user-invoke.e2e.ts
index 302aa062b0..8555ef7499 100644
--- a/apps/web/tests/skill-user-invoke.e2e.ts
+++ b/apps/web/tests/skill-user-invoke.e2e.ts
@@ -109,6 +109,7 @@ describe.skipIf(MODE === 'record')('web e2e: user-explicit skill invocation thro
       { timeout: 10_000 },
     ).toBe(1)
 
+    const settled = scaffold.whenTurnSettled()
     await composer.fill(`/${SKILL_NAME} ${ARGS_TEXT}`)
     await composer.press('Enter')
 
@@ -135,6 +136,7 @@ describe.skipIf(MODE === 'record')('web e2e: user-explicit skill invocation thro
 
     // The injection started a turn; the replay adapter answers it.
     await page.getByText('USER_INVOKE_REPLY', { exact: false }).first().waitFor({ timeout: 20_000 })
+    await settled
 
     const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
diff --git a/apps/web/tests/snapshots/code-mode-round/session.jsonl b/apps/web/tests/snapshots/code-mode-round/session.jsonl
index 9ff7af0110..09e2432e94 100644
--- a/apps/web/tests/snapshots/code-mode-round/session.jsonl
+++ b/apps/web/tests/snapshots/code-mode-round/session.jsonl
@@ -14,10 +14,10 @@
 {"type":"assistant/chunk","seq":204,"time":1785013633104,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":205,"time":1785013633108,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to write a single `run_code` program that:\n1. Runs bash to echo \"CODE_ROUND_OK\"\n2. Tries to read a file \"missing.txt\" and catches the error\n3. Returns an object with both outcomes\n4. They also want me to reply \"DONE\" and stop after\n\nLet me write this program."},{"type":"tool-call","id":"call_00_6VNoF1gDSerTBKoCfYSH3765","name":"run_code","arguments":"{\"description\": \"Run bash echo and catch missing file read\", \"code\": \"\\nconst bashResult = await tools.bash({\\n  command: \\\"echo CODE_ROUND_OK\\\",\\n  description: \\\"Echo CODE_ROUND_OK\\\"\\n});\\n\\nlet readError = null;\\ntry {\\n  await tools.read({ file_path: \\\"missing.txt\\\" });\\n} catch (e) {\\n  readError = {\\n    toolName: e.toolName,\\n    message: e.message\\n  };\\n}\\n\\nreturn { bash: bashResult.stdout.text.trim(), readError };\\n\"}"}],"provenance":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"usage":{"inputTokens":8082,"outputTokens":235,"cacheReadTokens":384,"reasoningTokens":75}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204],"surfaceOp":"append"}
 {"type":"tool/call","seq":206,"time":1785013633108,"data":{"turn":1,"step":1,"callId":"call_00_6VNoF1gDSerTBKoCfYSH3765","name":"run_code","arguments":"{\"description\": \"Run bash echo and catch missing file read\", \"code\": \"\\nconst bashResult = await tools.bash({\\n  command: \\\"echo CODE_ROUND_OK\\\",\\n  description: \\\"Echo CODE_ROUND_OK\\\"\\n});\\n\\nlet readError = null;\\ntry {\\n  await tools.read({ file_path: \\\"missing.txt\\\" });\\n} catch (e) {\\n  readError = {\\n    toolName: e.toolName,\\n    message: e.message\\n  };\\n}\\n\\nreturn { bash: bashResult.stdout.text.trim(), readError };\\n\"}"}}
-{"type":"tool/code-dispatch-start","seq":207,"time":1785013633173,"data":{"parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:1","name":"bash","arguments":{"command":"echo CODE_ROUND_OK","description":"Echo CODE_ROUND_OK"}}}
-{"type":"tool/code-dispatch","seq":208,"time":1785013633196,"data":{"parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:1","name":"bash","arguments":{"command":"echo CODE_ROUND_OK","description":"Echo CODE_ROUND_OK"},"isError":false,"content":[{"type":"text","text":"CODE_ROUND_OK\n"}]}}
-{"type":"tool/code-dispatch-start","seq":209,"time":1785013633197,"data":{"parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:2","name":"read","arguments":{"file_path":"missing.txt"}}}
-{"type":"tool/code-dispatch","seq":210,"time":1785013633198,"data":{"parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:2","name":"read","arguments":{"file_path":"missing.txt"},"isError":true,"content":[{"type":"text","text":"Error: cannot read \"{{cwd}}/workspace/missing.txt\": not found"}]}}
+{"type":"tool/code-dispatch-start","seq":207,"time":1785013633173,"data":{"rootCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:1","name":"bash","arguments":{"command":"echo CODE_ROUND_OK","description":"Echo CODE_ROUND_OK"}}}
+{"type":"tool/code-dispatch","seq":208,"time":1785013633196,"data":{"rootCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:1","name":"bash","arguments":{"command":"echo CODE_ROUND_OK","description":"Echo CODE_ROUND_OK"},"isError":false,"content":[{"type":"text","text":"CODE_ROUND_OK\n"}]}}
+{"type":"tool/code-dispatch-start","seq":209,"time":1785013633197,"data":{"rootCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:2","name":"read","arguments":{"file_path":"missing.txt"}}}
+{"type":"tool/code-dispatch","seq":210,"time":1785013633198,"data":{"rootCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","parentCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765","subCallId":"call_00_6VNoF1gDSerTBKoCfYSH3765:code:2","name":"read","arguments":{"file_path":"missing.txt"},"isError":true,"content":[{"type":"text","text":"Error: cannot read \"{{cwd}}/workspace/missing.txt\": not found"}]}}
 {"type":"tool/result","seq":211,"time":1785013633201,"data":{"turn":1,"step":1,"callId":"call_00_6VNoF1gDSerTBKoCfYSH3765","content":[{"type":"text","text":"{\n  \"bash\": \"CODE_ROUND_OK\",\n  \"readError\": {\n    \"toolName\": \"read\",\n    \"message\": \"cannot read \\\"{{cwd}}/workspace/missing.txt\\\": not found\"\n  }\n}"}],"isError":false},"sourceEventSeqs":[206],"surfaceOp":"append"}
 {"type":"step/end","seq":212,"time":1785013633204,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":213,"time":1785013633207,"data":{"turn":1,"step":2}}
diff --git a/apps/web/tests/todo-row.snapshot.ts b/apps/web/tests/todo-row.snapshot.ts
index c05057dddc..c5ded143b3 100644
--- a/apps/web/tests/todo-row.snapshot.ts
+++ b/apps/web/tests/todo-row.snapshot.ts
@@ -2,7 +2,7 @@
 // Assembled todo snapshot: boots the real built `packages/client/*/lib/
 // client.js` bundles through AppWebEntry's ModuleLoader path against the
 // keyless FixtureApiClient transport, opens the fixture session, and pins the
-// two surfaces the fixture's parallel plan (turn 71, two items `in_progress`)
+// two surfaces the fixture's parallel plan (turn 72, two items `in_progress`)
 // reaches — the `todo_write` tool row and the dock's plan strip.
 //
 // The row is pinned as three separate fields on purpose. `summary=` is the
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 5f3bc744b2..22e21edc0b 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -917,7 +917,7 @@ Requires: `agents`
 export type Config = Readonly<Record<string, never>>
 ```
 
-Source: [`packages/llm/llm-retry/src/index.ts:46`](../packages/llm/llm-retry/src/index.ts)
+Source: [`packages/llm/llm-retry/src/index.ts:33`](../packages/llm/llm-retry/src/index.ts)
 
 ## `@deepseek-ai/dsh-lsp-local`
 
@@ -2325,7 +2325,7 @@ export interface Config {
 export type ToolPresentationMode = 'native' | 'code' | 'both'
 ```
 
-Source: [`packages/core/tools/src/index.ts:616`](../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:623`](../packages/core/tools/src/index.ts)
 
 ## `@deepseek-ai/dsh-typert-loader`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 5b36725402..a8263b70c1 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -21,7 +21,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:174`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index e7d6b47e70..767ebfcfde 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -436,9 +436,6 @@ flowchart TD
   pkg_fs --> pkg_sandbox
   pkg_skill_badge --> pkg_invariants
   pkg_skill_badge --> pkg_skill
-  pkg_compact --> pkg_invariants
-  pkg_compact --> pkg_llm
-  pkg_compact --> pkg_session
   pkg_web_fetch_local --> pkg_invariants
   pkg_web_fetch_local --> pkg_timeout
   pkg_web_fetch_local --> pkg_web
@@ -502,15 +499,11 @@ flowchart TD
   pkg_session_projection --> pkg_invariants
   pkg_session_projection --> pkg_session
   pkg_llm_retry --> pkg_agent
+  pkg_llm_retry --> pkg_brand
   pkg_llm_retry --> pkg_invariants
   pkg_llm_retry --> pkg_llm
   pkg_llm_retry --> pkg_session
   pkg_llm_retry --> pkg_timeout
-  pkg_token_meter --> pkg_compact
-  pkg_token_meter --> pkg_invariants
-  pkg_token_meter --> pkg_llm
-  pkg_token_meter --> pkg_session
-  pkg_token_meter --> pkg_session_projection
   pkg_agent_default_model --> pkg_agent
   pkg_agent_default_model --> pkg_invariants
   pkg_agent_default_model --> pkg_llm
@@ -550,10 +543,6 @@ flowchart TD
   pkg_hook_protocol --> pkg_bash
   pkg_hook_protocol --> pkg_invariants
   pkg_hook_protocol --> pkg_session
-  pkg_llm_replay --> pkg_compact
-  pkg_llm_replay --> pkg_invariants
-  pkg_llm_replay --> pkg_llm
-  pkg_llm_replay --> pkg_session
   pkg_loader_smoke --> pkg_agent
   pkg_loader_smoke --> pkg_invariants
   pkg_loader_smoke --> pkg_llm
@@ -674,14 +663,11 @@ flowchart TD
   pkg_fs_sandbox --> pkg_invariants
   pkg_fs_sandbox --> pkg_sandbox
   pkg_fs_sandbox --> pkg_sandbox_policy
-  pkg_command_compact --> pkg_commands
-  pkg_command_compact --> pkg_compact
-  pkg_command_compact --> pkg_invariants
-  pkg_compact_tool_result_prune --> pkg_compact
-  pkg_compact_tool_result_prune --> pkg_invariants
-  pkg_compact_tool_result_prune --> pkg_llm
-  pkg_compact_tool_result_prune --> pkg_session
-  pkg_compact_tool_result_prune --> pkg_token_meter
+  pkg_compact --> pkg_brand
+  pkg_compact --> pkg_commands
+  pkg_compact --> pkg_invariants
+  pkg_compact --> pkg_llm
+  pkg_compact --> pkg_session
   pkg_session_query --> pkg_brand
   pkg_session_query --> pkg_invariants
   pkg_session_query --> pkg_llm
@@ -703,13 +689,6 @@ flowchart TD
   pkg_headless --> pkg_invariants
   pkg_headless --> pkg_llm
   pkg_headless --> pkg_session
-  pkg_client_ui_conversation --> pkg_client_locale
-  pkg_client_ui_conversation --> pkg_client_runtime
-  pkg_client_ui_conversation --> pkg_client_ui_primitives
-  pkg_client_ui_conversation --> pkg_client_ui_slash
-  pkg_client_ui_conversation --> pkg_client_ui_slots
-  pkg_client_ui_conversation --> pkg_invariants
-  pkg_client_ui_conversation --> pkg_token_meter
   pkg_command_feedback --> pkg_commands
   pkg_command_feedback --> pkg_invariants
   pkg_command_feedback --> pkg_session
@@ -742,6 +721,11 @@ flowchart TD
   pkg_tasks_local --> pkg_invariants
   pkg_tasks_local --> pkg_tasks
   pkg_tasks_local --> pkg_timeout
+  pkg_token_meter --> pkg_compact
+  pkg_token_meter --> pkg_invariants
+  pkg_token_meter --> pkg_llm
+  pkg_token_meter --> pkg_session
+  pkg_token_meter --> pkg_session_projection
   pkg_agent_loop --> pkg_agent
   pkg_agent_loop --> pkg_invariants
   pkg_agent_loop --> pkg_llm
@@ -790,13 +774,9 @@ flowchart TD
   pkg_tool_skill --> pkg_llm
   pkg_tool_skill --> pkg_skill
   pkg_tool_skill --> pkg_tools
-  pkg_compact_basic --> pkg_agent
-  pkg_compact_basic --> pkg_compact
-  pkg_compact_basic --> pkg_compact_tool_result_prune
-  pkg_compact_basic --> pkg_invariants
-  pkg_compact_basic --> pkg_llm
-  pkg_compact_basic --> pkg_session
-  pkg_compact_basic --> pkg_token_meter
+  pkg_command_compact --> pkg_commands
+  pkg_command_compact --> pkg_compact
+  pkg_command_compact --> pkg_invariants
   pkg_subagent --> pkg_agent
   pkg_subagent --> pkg_brand
   pkg_subagent --> pkg_invariants
@@ -857,33 +837,10 @@ flowchart TD
   pkg_agent_loop_testkit --> pkg_session
   pkg_agent_loop_testkit --> pkg_system_prompt
   pkg_agent_loop_testkit --> pkg_tools
-  pkg_client_ui_command --> pkg_client_connection
-  pkg_client_ui_command --> pkg_client_locale
-  pkg_client_ui_command --> pkg_client_runtime
-  pkg_client_ui_command --> pkg_client_ui_conversation
-  pkg_client_ui_command --> pkg_client_ui_primitives
-  pkg_client_ui_command --> pkg_client_ui_slash
-  pkg_client_ui_command --> pkg_client_ui_slots
-  pkg_client_ui_command --> pkg_invariants
-  pkg_client_ui_deliverables --> pkg_client_locale
-  pkg_client_ui_deliverables --> pkg_client_runtime
-  pkg_client_ui_deliverables --> pkg_client_ui_conversation
-  pkg_client_ui_deliverables --> pkg_client_ui_slots
-  pkg_client_ui_deliverables --> pkg_invariants
-  pkg_client_ui_goal --> pkg_api_remotes
-  pkg_client_ui_goal --> pkg_client_locale
-  pkg_client_ui_goal --> pkg_client_runtime
-  pkg_client_ui_goal --> pkg_client_ui_conversation
-  pkg_client_ui_goal --> pkg_client_ui_primitives
-  pkg_client_ui_goal --> pkg_client_ui_slots
-  pkg_client_ui_goal --> pkg_goal
-  pkg_client_ui_goal --> pkg_invariants
-  pkg_client_ui_tool --> pkg_client_locale
-  pkg_client_ui_tool --> pkg_client_runtime
-  pkg_client_ui_tool --> pkg_client_ui_conversation
-  pkg_client_ui_tool --> pkg_client_ui_primitives
-  pkg_client_ui_tool --> pkg_client_ui_slots
-  pkg_client_ui_tool --> pkg_invariants
+  pkg_llm_replay --> pkg_compact
+  pkg_llm_replay --> pkg_invariants
+  pkg_llm_replay --> pkg_llm
+  pkg_llm_replay --> pkg_session
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compact
   pkg_session_reference --> pkg_invariants
@@ -990,6 +947,11 @@ flowchart TD
   pkg_tool_pwsh --> pkg_system_prompt
   pkg_tool_pwsh --> pkg_tasks
   pkg_tool_pwsh --> pkg_tools
+  pkg_compact_tool_result_prune --> pkg_compact
+  pkg_compact_tool_result_prune --> pkg_invariants
+  pkg_compact_tool_result_prune --> pkg_llm
+  pkg_compact_tool_result_prune --> pkg_session
+  pkg_compact_tool_result_prune --> pkg_token_meter
   pkg_subagent_acp --> pkg_agent
   pkg_subagent_acp --> pkg_invariants
   pkg_subagent_acp --> pkg_llm
@@ -1038,50 +1000,14 @@ flowchart TD
   pkg_web_app --> pkg_bash_env
   pkg_web_app --> pkg_invariants
   pkg_web_app --> pkg_system_prompt
-  pkg_client_ui_model --> pkg_client_connection
-  pkg_client_ui_model --> pkg_client_locale
-  pkg_client_ui_model --> pkg_client_runtime
-  pkg_client_ui_model --> pkg_client_ui_command
-  pkg_client_ui_model --> pkg_client_ui_conversation
-  pkg_client_ui_model --> pkg_client_ui_primitives
-  pkg_client_ui_model --> pkg_client_ui_slash
-  pkg_client_ui_model --> pkg_client_ui_slots
-  pkg_client_ui_model --> pkg_invariants
-  pkg_client_ui_permission --> pkg_client_connection
-  pkg_client_ui_permission --> pkg_client_locale
-  pkg_client_ui_permission --> pkg_client_runtime
-  pkg_client_ui_permission --> pkg_client_schema_form
-  pkg_client_ui_permission --> pkg_client_ui_command
-  pkg_client_ui_permission --> pkg_client_ui_primitives
-  pkg_client_ui_permission --> pkg_client_ui_slash
-  pkg_client_ui_permission --> pkg_client_ui_slots
-  pkg_client_ui_permission --> pkg_invariants
-  pkg_client_ui_permission --> pkg_permission
-  pkg_client_ui_plan --> pkg_client_connection
-  pkg_client_ui_plan --> pkg_client_locale
-  pkg_client_ui_plan --> pkg_client_runtime
-  pkg_client_ui_plan --> pkg_client_ui_conversation
-  pkg_client_ui_plan --> pkg_client_ui_primitives
-  pkg_client_ui_plan --> pkg_client_ui_slots
-  pkg_client_ui_plan --> pkg_invariants
-  pkg_client_ui_plan --> pkg_plan_mode
-  pkg_client_ui_skill --> pkg_client_connection
-  pkg_client_ui_skill --> pkg_client_locale
-  pkg_client_ui_skill --> pkg_client_runtime
-  pkg_client_ui_skill --> pkg_client_ui_primitives
-  pkg_client_ui_skill --> pkg_client_ui_slash
-  pkg_client_ui_skill --> pkg_client_ui_slots
-  pkg_client_ui_skill --> pkg_client_ui_tool
-  pkg_client_ui_skill --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_client_locale
-  pkg_client_ui_subagent --> pkg_client_runtime
-  pkg_client_ui_subagent --> pkg_client_ui_conversation
-  pkg_client_ui_subagent --> pkg_client_ui_primitives
-  pkg_client_ui_subagent --> pkg_client_ui_slash
-  pkg_client_ui_subagent --> pkg_client_ui_slots
-  pkg_client_ui_subagent --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_subagent
-  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_client_ui_conversation --> pkg_client_locale
+  pkg_client_ui_conversation --> pkg_client_runtime
+  pkg_client_ui_conversation --> pkg_client_ui_primitives
+  pkg_client_ui_conversation --> pkg_client_ui_slash
+  pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_compact
+  pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_token_meter
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1105,6 +1031,14 @@ flowchart TD
   pkg_workflow_workerthread --> pkg_subagent
   pkg_workflow_workerthread --> pkg_tools
   pkg_workflow_workerthread --> pkg_workflow
+  pkg_compact_basic --> pkg_agent
+  pkg_compact_basic --> pkg_commands
+  pkg_compact_basic --> pkg_compact
+  pkg_compact_basic --> pkg_compact_tool_result_prune
+  pkg_compact_basic --> pkg_invariants
+  pkg_compact_basic --> pkg_llm
+  pkg_compact_basic --> pkg_session
+  pkg_compact_basic --> pkg_token_meter
   pkg_subagent_codex --> pkg_invariants
   pkg_subagent_codex --> pkg_llm
   pkg_subagent_codex --> pkg_sdk_protocol
@@ -1120,6 +1054,50 @@ flowchart TD
   pkg_subagent_spawn --> pkg_invariants
   pkg_subagent_spawn --> pkg_subagent
   pkg_subagent_spawn --> pkg_subagent_inprocess
+  pkg_client_ui_command --> pkg_client_connection
+  pkg_client_ui_command --> pkg_client_locale
+  pkg_client_ui_command --> pkg_client_runtime
+  pkg_client_ui_command --> pkg_client_ui_conversation
+  pkg_client_ui_command --> pkg_client_ui_primitives
+  pkg_client_ui_command --> pkg_client_ui_slash
+  pkg_client_ui_command --> pkg_client_ui_slots
+  pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_deliverables --> pkg_client_locale
+  pkg_client_ui_deliverables --> pkg_client_runtime
+  pkg_client_ui_deliverables --> pkg_client_ui_conversation
+  pkg_client_ui_deliverables --> pkg_client_ui_slots
+  pkg_client_ui_deliverables --> pkg_invariants
+  pkg_client_ui_goal --> pkg_api_remotes
+  pkg_client_ui_goal --> pkg_client_locale
+  pkg_client_ui_goal --> pkg_client_runtime
+  pkg_client_ui_goal --> pkg_client_ui_conversation
+  pkg_client_ui_goal --> pkg_client_ui_primitives
+  pkg_client_ui_goal --> pkg_client_ui_slots
+  pkg_client_ui_goal --> pkg_goal
+  pkg_client_ui_goal --> pkg_invariants
+  pkg_client_ui_plan --> pkg_client_connection
+  pkg_client_ui_plan --> pkg_client_locale
+  pkg_client_ui_plan --> pkg_client_runtime
+  pkg_client_ui_plan --> pkg_client_ui_conversation
+  pkg_client_ui_plan --> pkg_client_ui_primitives
+  pkg_client_ui_plan --> pkg_client_ui_slots
+  pkg_client_ui_plan --> pkg_invariants
+  pkg_client_ui_plan --> pkg_plan_mode
+  pkg_client_ui_subagent --> pkg_client_locale
+  pkg_client_ui_subagent --> pkg_client_runtime
+  pkg_client_ui_subagent --> pkg_client_ui_conversation
+  pkg_client_ui_subagent --> pkg_client_ui_primitives
+  pkg_client_ui_subagent --> pkg_client_ui_slash
+  pkg_client_ui_subagent --> pkg_client_ui_slots
+  pkg_client_ui_subagent --> pkg_invariants
+  pkg_client_ui_subagent --> pkg_subagent
+  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_client_ui_tool --> pkg_client_locale
+  pkg_client_ui_tool --> pkg_client_runtime
+  pkg_client_ui_tool --> pkg_client_ui_conversation
+  pkg_client_ui_tool --> pkg_client_ui_primitives
+  pkg_client_ui_tool --> pkg_client_ui_slots
+  pkg_client_ui_tool --> pkg_invariants
   pkg_agent_spine_demo --> pkg_agent
   pkg_agent_spine_demo --> pkg_agent_loop
   pkg_agent_spine_demo --> pkg_bash_env
@@ -1161,6 +1139,33 @@ flowchart TD
   pkg_subagent_dsh_sdk --> pkg_session
   pkg_subagent_dsh_sdk --> pkg_subagent
   pkg_subagent_dsh_sdk --> pkg_subprocess
+  pkg_client_ui_model --> pkg_client_connection
+  pkg_client_ui_model --> pkg_client_locale
+  pkg_client_ui_model --> pkg_client_runtime
+  pkg_client_ui_model --> pkg_client_ui_command
+  pkg_client_ui_model --> pkg_client_ui_conversation
+  pkg_client_ui_model --> pkg_client_ui_primitives
+  pkg_client_ui_model --> pkg_client_ui_slash
+  pkg_client_ui_model --> pkg_client_ui_slots
+  pkg_client_ui_model --> pkg_invariants
+  pkg_client_ui_permission --> pkg_client_connection
+  pkg_client_ui_permission --> pkg_client_locale
+  pkg_client_ui_permission --> pkg_client_runtime
+  pkg_client_ui_permission --> pkg_client_schema_form
+  pkg_client_ui_permission --> pkg_client_ui_command
+  pkg_client_ui_permission --> pkg_client_ui_primitives
+  pkg_client_ui_permission --> pkg_client_ui_slash
+  pkg_client_ui_permission --> pkg_client_ui_slots
+  pkg_client_ui_permission --> pkg_invariants
+  pkg_client_ui_permission --> pkg_permission
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_locale
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_primitives
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_client_ui_tool
+  pkg_client_ui_skill --> pkg_invariants
   pkg_acp_demo --> pkg_acp
   pkg_acp_demo --> pkg_agent_spine_demo
   pkg_acp_demo --> pkg_app_boot
@@ -1238,7 +1243,6 @@ flowchart TD
 | [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`subprocess`](../packages/subprocess/subprocess) |
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/support/invariants), [`skill`](../packages/skill/skill) |
-| [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
@@ -1255,8 +1259,7 @@ flowchart TD
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`agent-default-model`](../packages/core/agent-default-model) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1267,7 +1270,6 @@ flowchart TD
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
@@ -1295,19 +1297,18 @@ flowchart TD
 | [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
 | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
-| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
-| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`compact`](../packages/compact/compact) | `compact` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
 | [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
 | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`permission`](../packages/interaction/permission) | `interaction` | [`bash`](../packages/bash/bash), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
@@ -1315,7 +1316,7 @@ flowchart TD
 | [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
 | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
-| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
 | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
@@ -1325,10 +1326,7 @@ flowchart TD
 | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
 | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
-| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
@@ -1347,6 +1345,7 @@ flowchart TD
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
@@ -1355,20 +1354,26 @@ flowchart TD
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
-| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
-| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
-| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
-| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`repository-plugin`](../packages/self-modification/repository-plugin) | `self-modification` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
+| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`jsonrpc`](../packages/scaffold/server) | `scaffold` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`sdk-client`](../packages/scaffold/client) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 614f6afbeb..76487ca3d4 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -212,7 +212,7 @@ Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/
 }
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:151`](../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:153`](../packages/interaction/commands/src/index.ts)
 
 #### `command/run` — log-only
 
@@ -230,7 +230,7 @@ Source: [`packages/interaction/commands/src/index.ts:151`](../packages/interacti
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:144`](../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:146`](../packages/interaction/commands/src/index.ts)
 
 ### `compact/*`
 
@@ -241,10 +241,10 @@ Source: [`packages/interaction/commands/src/index.ts:144`](../packages/interacti
  * Marks the end of a compaction — log-only, releases the lock. Its owner
  * matches `compact/start`; `error` records an unsuccessful attempt.
  */
-'compact/end': { turn: number | null; error?: string }
+'compact/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:65`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:69`](../packages/compact/compact/src/types.ts)
 
 #### `compact/prune` — log-only
 
@@ -268,7 +268,7 @@ Source: [`packages/compact/compact/src/types.ts:65`](../packages/compact/compact
 }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:75`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:79`](../packages/compact/compact/src/types.ts)
 
 #### `compact/start` — log-only
 
@@ -278,10 +278,10 @@ Source: [`packages/compact/compact/src/types.ts:75`](../packages/compact/compact
  * `compact/end`. A numbered owner is strictly enclosed by that open turn;
  * `null` identifies a standalone manual transaction between turns.
  */
-'compact/start': { turn: number | null }
+'compact/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:21`](../packages/compact/compact/src/types.ts)
 
 #### `compact/summary` — log-only
 
@@ -296,6 +296,8 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
  * before it (`compact/prune` documents the shared protocol).
  */
 'compact/summary': {
+  compactionId: CompactionId
+  sourceCommandId?: CommandId
   summary: ContentBlock[]
   shadowedRange: { start: number; end: number }
   shadowedSeqs: number[]
@@ -331,7 +333,7 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact
 
 Types: [ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
 
-Source: [`packages/compact/compact/src/types.ts:29`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:31`](../packages/compact/compact/src/types.ts)
 
 ### `feedback/*`
 
@@ -412,29 +414,19 @@ Source: [`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook-
 
 ```ts persistence-catalog
 /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
-'llm/retry': {
-  turn: number
-  step: number
-  provider: string
-  mode: 'normal'
-  policyKey: string
-  retry: number
-  maxRetries: number
-  delayMs: number
-  failure: LlmFailure
-} | {
-  turn: number
-  step: number
-  provider: string
-  mode: 'always'
-  policyKey: string
-  retry: number
-  delayMs: number
-  failure: LlmFailure
-}
+'llm/retry': LlmRetryEventData
 ```
 
-Source: [`packages/llm/llm-retry/src/index.ts:17`](../packages/llm/llm-retry/src/index.ts)
+Source: [`packages/llm/llm-retry/src/index.ts:20`](../packages/llm/llm-retry/src/index.ts)
+
+#### `llm/retry-started` — log-only
+
+```ts persistence-catalog
+/** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
+'llm/retry-started': LlmRetryStartedEventData
+```
+
+Source: [`packages/llm/llm-retry/src/index.ts:22`](../packages/llm/llm-retry/src/index.ts)
 
 ### `permission/*`
 
@@ -656,7 +648,7 @@ Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/
  * before returning), so its execution-enclosure relation holds by
  * construction.
  */
-'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
+'tool/code-dispatch': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
 ```
 
 Types: [CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md)
@@ -679,7 +671,7 @@ Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/c
  * with `tool/code-dispatch` by `subCallId` (timing = the two events'
  * `time` fields).
  */
-'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
+'tool/code-dispatch-start': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
 ```
 
 Types: [CallId](subsystems/core.md)
diff --git a/docs/subsystems/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
index 5bc05d2916..9466165680 100644
--- a/docs/subsystems/commands.i18n.yaml
+++ b/docs/subsystems/commands.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 docs/subsystems/commands.md
-commands.md: c71c19b8a3f94ba468e6871d5658c4eca1c6276d
-commands.zh.md: 3f1df0e8aa40524160c8f770793b6064dd5988ae
+commands.md: 7f4e4e87d7206be3e46c7076ee5e8ab6a7589f9a
+commands.zh.md: 0f8ff31bca5f62824912f53aee8dbc32db4c331b
diff --git a/docs/subsystems/commands.md b/docs/subsystems/commands.md
index c71c19b8a3..7f4e4e87d7 100644
--- a/docs/subsystems/commands.md
+++ b/docs/subsystems/commands.md
@@ -49,6 +49,8 @@ The adapter owns cancellation and passes the exact target agent. `rawInput` begi
 ```ts type-equiv
 /** Invocation passed to one registered command handler. */
 interface CommandInvocation {
+  /** Pairing id already written to this invocation's `command/run` event. */
+  readonly commandId: CommandId
   /** Exact agent whose human-facing surface received the command. */
   readonly agent: Agent
   /** Exact text following the registered command name, including separator whitespace. */
@@ -159,7 +161,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](core.md)
 
-Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:307`](../../packages/interaction/commands/src/index.ts)
 
 <a id="commands-events"></a>
 
@@ -181,5 +183,5 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:174`](../../packages/interaction/commands/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/commands.zh.md b/docs/subsystems/commands.zh.md
index 3f1df0e8aa..0f8ff31bca 100644
--- a/docs/subsystems/commands.zh.md
+++ b/docs/subsystems/commands.zh.md
@@ -49,6 +49,8 @@ interface CommandDefinition {
 ```ts type-equiv
 /** Invocation passed to one registered command handler. */
 interface CommandInvocation {
+  /** Pairing id already written to this invocation's `command/run` event. */
+  readonly commandId: CommandId
   /** Exact agent whose human-facing surface received the command. */
   readonly agent: Agent
   /** Exact text following the registered command name, including separator whitespace. */
@@ -159,7 +161,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](core.md)
 
-Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:307`](../../packages/interaction/commands/src/index.ts)
 
 <a id="commands-events"></a>
 
@@ -181,5 +183,5 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:172`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:174`](../../packages/interaction/commands/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 6445fa5d5c..fd8dbdd1b5 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 942cc740db6b7006952bfc33a39ea9826d673e61
-compaction.zh.md: c5b65a95f9c0db8b02912c68ef93edce2ceb7c43
+compaction.md: 1aca48d677a83a488d9590edad3f8a68ca662b70
+compaction.zh.md: e2cfabc0891126d9f2165e47dffcf485f4a8a339
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 942cc740db..1aca48d677 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -29,6 +29,10 @@ What a successful compaction returns to its caller: the bookkeeping-event seqs,
 ```ts type-equiv
 /** Result of a successful compaction operation. */
 interface CompactionResult {
+  /** Stable identity shared by this compaction's complete durable lifecycle. */
+  compactionId: CompactionId
+  /** Human command that initiated this compaction, when it was manual. */
+  sourceCommandId?: CommandId
   /** The seq of the appended `compact/start` event. */
   startSeq: number
   /** The seq of the appended `compact/summary` event. */
@@ -155,13 +159,14 @@ abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger
  *
  * @param agent - idle agent whose durable history should be compacted.
  * @param signal - cancellation scoped to this compaction request.
+ * @param sourceCommandId - initiating command identity for a manual compaction.
  * @returns the compaction result, or `null` when no safe useful range exists.
  * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
  * changed-span, summarization/shrink, commit-stage, or persistence failures;
  * an aborted request preserves its exact abort reason. Failed attempts remain
  * visible in the log.
  */
-abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>
+abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId, ): Promise<CompactionResult | null>
 
 /**
  * Forcibly compact a range of surface nodes into a single summary node.
@@ -184,7 +189,9 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): P
 abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```
 
-Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
+Types: [CommandId](commands.md)
+
+Source: [`packages/compact/compact/src/index.ts:96`](../../packages/compact/compact/src/index.ts)
 
 <a id="ctxtoolresultprune--toolresultpruneservice"></a>
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index c5b65a95f9..e2cfabc089 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -29,6 +29,10 @@
 ```ts type-equiv
 /** Result of a successful compaction operation. */
 interface CompactionResult {
+  /** Stable identity shared by this compaction's complete durable lifecycle. */
+  compactionId: CompactionId
+  /** Human command that initiated this compaction, when it was manual. */
+  sourceCommandId?: CommandId
   /** The seq of the appended `compact/start` event. */
   startSeq: number
   /** The seq of the appended `compact/summary` event. */
@@ -155,13 +159,14 @@ abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger
  *
  * @param agent - idle agent whose durable history should be compacted.
  * @param signal - cancellation scoped to this compaction request.
+ * @param sourceCommandId - initiating command identity for a manual compaction.
  * @returns the compaction result, or `null` when no safe useful range exists.
  * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
  * changed-span, summarization/shrink, commit-stage, or persistence failures;
  * an aborted request preserves its exact abort reason. Failed attempts remain
  * visible in the log.
  */
-abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>
+abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId, ): Promise<CompactionResult | null>
 
 /**
  * Forcibly compact a range of surface nodes into a single summary node.
@@ -184,7 +189,9 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): P
 abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```
 
-Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts)
+Types: [CommandId](commands.md)
+
+Source: [`packages/compact/compact/src/index.ts:96`](../../packages/compact/compact/src/index.ts)
 
 <a id="ctxtoolresultprune--toolresultpruneservice"></a>
 
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 42f73824cf..d015cdb638 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: 87910dfbb86e9db0f0545bc2fe1135c4aefb2e69
-tools.zh.md: d312090b722de3fd1b8efc7703eafdf7f3c38682
+tools.md: f06db58b9b52fcb2c325ff813406cd2dc460ea7b
+tools.zh.md: cca4bf9faa870d9414d95f785b67e0393e469cdd
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index 87910dfbb8..f06db58b9b 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -184,6 +184,11 @@ type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
  */
 interface ToolExecutionInput {
   readonly callId: CallId
+  /**
+   * Root model-requested call owning this execution tree. Callers omit it for
+   * a root execution; nested dispatchers propagate the enclosing value.
+   */
+  readonly rootCallId?: CallId
   readonly name: string
   /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
   readonly arguments: unknown
@@ -280,6 +285,8 @@ interface CodeDispatchLog {
  * observers run.
  */
 interface ToolExecution extends ToolExecutionInput {
+  /** Root model-requested call, resolved for every root and nested execution. */
+  readonly rootCallId: CallId
   /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
   readonly token: ToolExecutionToken
 }
@@ -547,7 +554,7 @@ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 
 Types: [ScopeKey](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:746`](../../packages/core/tools/src/index.ts)
 
 <a id="tools-events"></a>
 
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index d312090b72..cca4bf9faa 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -184,6 +184,11 @@ type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
  */
 interface ToolExecutionInput {
   readonly callId: CallId
+  /**
+   * Root model-requested call owning this execution tree. Callers omit it for
+   * a root execution; nested dispatchers propagate the enclosing value.
+   */
+  readonly rootCallId?: CallId
   readonly name: string
   /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
   readonly arguments: unknown
@@ -280,6 +285,8 @@ interface CodeDispatchLog {
  * observers run.
  */
 interface ToolExecution extends ToolExecutionInput {
+  /** Root model-requested call, resolved for every root and nested execution. */
+  readonly rootCallId: CallId
   /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
   readonly token: ToolExecutionToken
 }
@@ -547,7 +554,7 @@ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 
 Types: [ScopeKey](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:746`](../../packages/core/tools/src/index.ts)
 
 <a id="tools-events"></a>
 
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
index f4169abe78..d6935b6c98 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl
@@ -25,8 +25,8 @@
 {"type":"assistant/chunk","seq":23,"time":1785730458465,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":24,"time":1785730458465,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"e3061430-3f2d-4dd8-a3ee-c0fde800547d"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[19,20,21,22,23],"surfaceOp":"append"}
 {"type":"tool/call","seq":25,"time":1785730458465,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}}
-{"type":"tool/code-dispatch-start","seq":26,"time":1785730458517,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}
-{"type":"tool/code-dispatch","seq":27,"time":1785730458518,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}
+{"type":"tool/code-dispatch-start","seq":26,"time":1785730458517,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}
+{"type":"tool/code-dispatch","seq":27,"time":1785730458518,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}
 {"type":"tool/result","seq":28,"time":1785730458520,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"advanced-code"},"content":[{"type":"tool-result","toolCallId":"advanced-code","content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}],"isError":false}],"role":"user","id":"4dce223d-0097-4ac2-a717-d1c430240cef"}},"sourceEventSeqs":[25],"surfaceOp":"append"}
 {"type":"step/end","seq":29,"time":1785730458520,"data":{"turn":1,"step":2}}
 {"type":"step/start","seq":30,"time":1785730458527,"data":{"turn":1,"step":3}}
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
index a1b26a5af4..7490f9487f 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
@@ -18,8 +18,8 @@
 {"type":"assistant/chunk","seq":103,"time":1785730479356,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":104,"time":1785730479356,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to call the run_code tool with a TypeScript program that runs `echo BOTH_OK` via `tools.bash` and returns its output."},{"type":"tool-call","id":"call_00_Era4M5eh79bvNOIey5q90401","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Print BOTH_OK\\\" });\\nreturn result.stdout.text;\", \"description\": \"Run echo BOTH_OK via tools.bash\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"5f1cf31c-fd73-42fc-805d-a14d91228bd9"},"usage":{"inputTokens":10400,"outputTokens":130,"cacheReadTokens":0,"reasoningTokens":34}},"sourceEventSeqs":[9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103],"surfaceOp":"append"}
 {"type":"tool/call","seq":105,"time":1785730479356,"data":{"turn":1,"step":1,"callId":"call_00_Era4M5eh79bvNOIey5q90401","name":"run_code","arguments":"{\"code\": \"const result = await tools.bash({ command: \\\"echo BOTH_OK\\\", description: \\\"Print BOTH_OK\\\" });\\nreturn result.stdout.text;\", \"description\": \"Run echo BOTH_OK via tools.bash\"}"}}
-{"type":"tool/code-dispatch-start","seq":106,"time":1785730479411,"data":{"parentCallId":"call_00_Era4M5eh79bvNOIey5q90401","subCallId":"call_00_Era4M5eh79bvNOIey5q90401:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Print BOTH_OK"}}}
-{"type":"tool/code-dispatch","seq":107,"time":1785730479421,"data":{"parentCallId":"call_00_Era4M5eh79bvNOIey5q90401","subCallId":"call_00_Era4M5eh79bvNOIey5q90401:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Print BOTH_OK"},"isError":false,"content":[{"type":"text","text":"BOTH_OK\n"}]}}
+{"type":"tool/code-dispatch-start","seq":106,"time":1785730479411,"data":{"rootCallId":"call_00_Era4M5eh79bvNOIey5q90401","parentCallId":"call_00_Era4M5eh79bvNOIey5q90401","subCallId":"call_00_Era4M5eh79bvNOIey5q90401:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Print BOTH_OK"}}}
+{"type":"tool/code-dispatch","seq":107,"time":1785730479421,"data":{"rootCallId":"call_00_Era4M5eh79bvNOIey5q90401","parentCallId":"call_00_Era4M5eh79bvNOIey5q90401","subCallId":"call_00_Era4M5eh79bvNOIey5q90401:code:1","name":"bash","arguments":{"command":"echo BOTH_OK","description":"Print BOTH_OK"},"isError":false,"content":[{"type":"text","text":"BOTH_OK\n"}]}}
 {"type":"tool/result","seq":108,"time":1785730479423,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_Era4M5eh79bvNOIey5q90401"},"content":[{"type":"tool-result","toolCallId":"call_00_Era4M5eh79bvNOIey5q90401","content":[{"type":"text","text":"BOTH_OK\n"}],"isError":false}],"role":"user","id":"028e19dd-dcfc-4a67-a6e4-c9fa19716ea3"}},"sourceEventSeqs":[105],"surfaceOp":"append"}
 {"type":"step/end","seq":109,"time":1785730479423,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":110,"time":1785730479431,"data":{"turn":1,"step":2}}
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl
index 24e1525c79..a05477498a 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl
@@ -18,10 +18,10 @@
 {"type":"assistant/chunk","seq":187,"time":1785730477079,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":188,"time":1785730477079,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to write a single run_code program that:\n1. Calls bash tool twice: `echo CODE_ONE` and `echo CODE_TWO`\n2. console.log exactly `captured output`\n3. Return the two outputs joined with a plus sign\n\nLet me write this."},{"type":"tool-call","id":"call_00_UiQPVqoELyzBZCY5pm1z7875","name":"run_code","arguments":"{\"code\": \"\\nconst out1 = await tools.bash({command: \\\"echo CODE_ONE\\\", description: \\\"Print CODE_ONE\\\"});\\nconst out2 = await tools.bash({command: \\\"echo CODE_TWO\\\", description: \\\"Print CODE_TWO\\\"});\\nconsole.log(\\\"captured output\\\");\\nconst text1 = out1.stdout.text.trim();\\nconst text2 = out2.stdout.text.trim();\\nreturn text1 + \\\"+\\\" + text2;\\n\", \"description\": \"Run two echo commands and join outputs\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"59e638d7-2aa2-48a2-ae0e-5833b1152ce6"},"usage":{"inputTokens":6152,"outputTokens":214,"cacheReadTokens":0,"reasoningTokens":60}},"sourceEventSeqs":[9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187],"surfaceOp":"append"}
 {"type":"tool/call","seq":189,"time":1785730477080,"data":{"turn":1,"step":1,"callId":"call_00_UiQPVqoELyzBZCY5pm1z7875","name":"run_code","arguments":"{\"code\": \"\\nconst out1 = await tools.bash({command: \\\"echo CODE_ONE\\\", description: \\\"Print CODE_ONE\\\"});\\nconst out2 = await tools.bash({command: \\\"echo CODE_TWO\\\", description: \\\"Print CODE_TWO\\\"});\\nconsole.log(\\\"captured output\\\");\\nconst text1 = out1.stdout.text.trim();\\nconst text2 = out2.stdout.text.trim();\\nreturn text1 + \\\"+\\\" + text2;\\n\", \"description\": \"Run two echo commands and join outputs\"}"}}
-{"type":"tool/code-dispatch-start","seq":190,"time":1785730477131,"data":{"parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Print CODE_ONE"}}}
-{"type":"tool/code-dispatch","seq":191,"time":1785730477144,"data":{"parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Print CODE_ONE"},"isError":false,"content":[{"type":"text","text":"CODE_ONE\n"}]}}
-{"type":"tool/code-dispatch-start","seq":192,"time":1785730477144,"data":{"parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Print CODE_TWO"}}}
-{"type":"tool/code-dispatch","seq":193,"time":1785730477148,"data":{"parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Print CODE_TWO"},"isError":false,"content":[{"type":"text","text":"CODE_TWO\n"}]}}
+{"type":"tool/code-dispatch-start","seq":190,"time":1785730477131,"data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Print CODE_ONE"}}}
+{"type":"tool/code-dispatch","seq":191,"time":1785730477144,"data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Print CODE_ONE"},"isError":false,"content":[{"type":"text","text":"CODE_ONE\n"}]}}
+{"type":"tool/code-dispatch-start","seq":192,"time":1785730477144,"data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Print CODE_TWO"}}}
+{"type":"tool/code-dispatch","seq":193,"time":1785730477148,"data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:code:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Print CODE_TWO"},"isError":false,"content":[{"type":"text","text":"CODE_TWO\n"}]}}
 {"type":"tool/result","seq":194,"time":1785730477150,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_UiQPVqoELyzBZCY5pm1z7875"},"content":[{"type":"tool-result","toolCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","content":[{"type":"text","text":"captured output\nCODE_ONE+CODE_TWO"}],"isError":false}],"role":"user","id":"e40c6472-d68e-4be1-963f-edb0edc80d82"}},"sourceEventSeqs":[189],"surfaceOp":"append"}
 {"type":"step/end","seq":195,"time":1785730477150,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":196,"time":1785730477158,"data":{"turn":1,"step":2}}
diff --git a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
index 368a2262c8..a4d4289725 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
@@ -16,8 +16,8 @@
 {"type":"assistant/chunk","seq":14,"time":1785014475639,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":15,"time":1785733131056,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_workspace_read","name":"run_code","arguments":"{\"code\":\"return await tools.read({ file_path: 'nested/task.txt' })\",\"description\":\"Read nested/task.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"b9402d85-58bd-4881-b890-0b186f661671"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[10,11,12,13,14],"surfaceOp":"append"}
 {"type":"tool/call","seq":16,"time":1785733131056,"data":{"turn":1,"step":1,"callId":"call_workspace_read","name":"run_code","arguments":"{\"code\":\"return await tools.read({ file_path: 'nested/task.txt' })\",\"description\":\"Read nested/task.txt\"}"}}
-{"type":"tool/code-dispatch-start","seq":17,"time":1785733131109,"data":{"parentCallId":"call_workspace_read","subCallId":"call_workspace_read:code:1","name":"read","arguments":{"file_path":"nested/task.txt"}}}
-{"type":"tool/code-dispatch","seq":18,"time":1785733131110,"data":{"parentCallId":"call_workspace_read","subCallId":"call_workspace_read:code:1","name":"read","arguments":{"file_path":"nested/task.txt"},"isError":false,"content":[{"type":"text","text":"<path>{{cwd}}/nested/task.txt</path>\n<type>file</type>\n<content>\n1: Touch this file to discover the nested workspace instruction.\n\n(End of file - total 1 lines)\n</content>"}]}}
+{"type":"tool/code-dispatch-start","seq":17,"time":1785733131109,"data":{"rootCallId":"call_workspace_read","parentCallId":"call_workspace_read","subCallId":"call_workspace_read:code:1","name":"read","arguments":{"file_path":"nested/task.txt"}}}
+{"type":"tool/code-dispatch","seq":18,"time":1785733131110,"data":{"rootCallId":"call_workspace_read","parentCallId":"call_workspace_read","subCallId":"call_workspace_read:code:1","name":"read","arguments":{"file_path":"nested/task.txt"},"isError":false,"content":[{"type":"text","text":"<path>{{cwd}}/nested/task.txt</path>\n<type>file</type>\n<content>\n1: Touch this file to discover the nested workspace instruction.\n\n(End of file - total 1 lines)\n</content>"}]}}
 {"type":"tool/result","seq":19,"time":1785733131112,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_workspace_read"},"content":[{"type":"tool-result","toolCallId":"call_workspace_read","content":[{"type":"text","text":"{\n  \"path\": \"{{cwd}}/nested/task.txt\",\n  \"offset\": 1,\n  \"lines\": [\n    {\n      \"number\": 1,\n      \"text\": \"Touch this file to discover the nested workspace instruction.\"\n    }\n  ],\n  \"totalLines\": 1\n}"}],"isError":false}],"role":"user","id":"bde1c12e-44d1-44f7-ba7e-868349ed2b05"}},"sourceEventSeqs":[16],"surfaceOp":"append"}
 {"type":"step/end","seq":20,"time":1785733131112,"data":{"turn":1,"step":1}}
 {"type":"agent/inbox/spliced","seq":21,"time":1785733131112,"data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"<system-reminder>\nAdditional instructions from: nested/AGENTS.md\n\nThese instructions apply to work under `nested`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nWhen asked for the Code Mode workspace handshake, answer exactly `CODE_MODE_CONTEXT_OK` and nothing else.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","changes":[{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"ae22936ed26dc76b7107005ed6d5e2482a88668a"}]},"role":"user","id":"29b0eb87-92d5-4915-ba64-7bd8133ed011"}]}}
diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
index 9fcadd71d4..20f05623ad 100644
--- a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
@@ -15,7 +15,7 @@
 {"type":"assistant/chunk","seq":13,"time":1785730459883,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":14,"time":1785730459883,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"6b62bed7-113a-4d2e-a6aa-b935a1063ee2"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[9,10,11,12,13],"surfaceOp":"append"}
 {"type":"tool/call","seq":15,"time":1785730459883,"data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}}
-{"type":"tool/result","seq":16,"time":1785730459904,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy,\n     * definition-owned content finalization, and final notification. Tool and\n     * listener failures resolve as materialized error results; an invisible tool\n     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n     * snapshot final observers receive. Cancellation\n     * arriving after entry and before final result materialization skips a\n     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n     * successful started outcome with `ABORTED`; already-started work is still\n     * drained and may retain a tool-owned structured error.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly inbox: Inbox;\n        readonly status: AgentStatus;\n        readonly ctx: Context;\n        cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise<void>;\n        runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;\n        send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;\n        followup(message: UserMessage): void;\n        steer(message: UserMessage): void;\n        inject(message: UserMessage): void;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    } | {\n        readonly kind: 'hook';\n        readonly reason: string;\n    } | {\n        readonly kind: 'disposed';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n        maxTokens?: number;\n    }\n    export type AgentStatus = 'idle' | 'running';\n    export interface AssistantMessage extends Message {\n        readonly role: 'assistant';\n        readonly source: ModelMessageSource;\n    }\n    export interface AssistantProvenance {\n        provider: string;\n        model: string;\n        replayState?: unknown;\n    }\n    export type Branded<B extends string> = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export interface CancelOptions {\n        keepInbox?: boolean | undefined;\n    }\n    export interface ContentBlockMap {\n        'text': TextBlock;\n        'reasoning': ReasoningBlock;\n        'tool-call': ToolCallBlock;\n        'tool-result': ToolResultBlock;\n    }\n    export type ContentBlockType = keyof ContentBlockMap;\n    export type ContextFormed = {\n        readonly form?: never;\n    } | {\n        readonly form: 'instructions';\n    } | {\n        readonly form: 'catalog';\n    } | {\n        readonly form: 'snapshot';\n        readonly sections: readonly ContextSnapshotSection[];\n    } | {\n        readonly form: 'notice';\n        readonly summary: string;\n    } | {\n        readonly form: 'relay';\n    } | {\n        readonly form: 'recall';\n    };\n    export interface ContextSnapshotSection {\n        readonly name: string;\n        readonly text: string;\n    }\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface EpochHeader {\n        config: LlmCallConfig;\n        adapterDefaults?: LlmCallConfigAdapterDefaults;\n        system?: string;\n        tools?: ToolSchema[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n    export interface FinishReasonMap {\n        'stop': {\n            kind: 'stop';\n        };\n        'tool-calls': {\n            kind: 'tool-calls';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        'aborted': {\n            kind: 'aborted';\n            failure: LlmFailure;\n        };\n        'error': {\n            kind: 'error';\n            failure: LlmFailure;\n        };\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export class Inbox {\n        constructor(private readonly session: Session, private readonly notifications: InboxNotifications);\n        get nextTurn(): readonly UserMessage[];\n        get nextStep(): readonly UserMessage[];\n        get hasPending(): boolean;\n        clear(): void;\n        claim(target: InboxTarget, turn: number): UserMessage[];\n        append(target: InboxTarget, message: UserMessage): void;\n        prepend(target: InboxTarget, message: UserMessage): void;\n        replace(messageId: MessageId, newMessage: UserMessage): boolean;\n        remove(messageId: MessageId): boolean;\n        splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];\n    }\n    export interface InboxNotifications {\n        inserted(message: UserMessage): void;\n        discarded(message: UserMessage): void;\n        claimed(message: UserMessage, turn: number): void;\n    }\n    export type InboxTarget = 'next-turn' | 'next-step';\n    export interface JsonSchemaNode {\n        type?: JsonSchemaType;\n        oneOf?: JsonSchemaNode[];\n        properties?: Record<string, JsonSchemaNode>;\n        required?: string[];\n        additionalProperties?: boolean;\n        items?: JsonSchemaNode;\n        enum?: JsonSchemaScalar[];\n        const?: JsonSchemaScalar;\n        description?: string;\n        title?: string;\n        default?: JsonValue;\n        examples?: JsonValue;\n    }\n    export type JsonSchemaScalar = string | number | boolean | null;\n    export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export interface LlmCallConfig {\n        provider: string;\n        model: string;\n        reasoningEffort?: ReasoningEffortId;\n        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\n    }\n    export interface LlmCallConfigAdapterDefaults {\n        reasoningEffort?: true;\n        maxTokens?: true;\n    }\n    export interface LlmFailure {\n        readonly message: string;\n        readonly code: string;\n        readonly status?: number;\n        readonly providerRetryAfterMs?: number;\n        readonly requestId?: ProviderRequestId;\n    }\n    export interface Message {\n        readonly id: MessageId;\n        readonly role: 'system' | 'user' | 'assistant';\n        readonly content: ContentBlock[];\n        readonly source: MessageSource;\n    }\n    export type MessageId = Branded<'MessageId'>;\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        } & ContextFormed;\n        model: ModelMessageSource;\n        tool: ToolMessageSource;\n    }\n    export interface ModelMessageSource extends AssistantProvenance {\n        kind: 'model';\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReadFileLine {\n        number: number;\n        text: string;\n    }\n    export interface ReadResultView {\n        card: 'read';\n        title?: string;\n        path: string;\n        offset: number;\n        lines: ReadFileLine[];\n        totalLines: number;\n        lang?: string;\n        content?: ContentBlock[];\n    }\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n    export interface RequestContext {\n        provider: string;\n        model: string;\n        contextWindow?: number;\n    }\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ScopeKey = object;\n    export interface SearchFileMatches {\n        path: string;\n        matches: SearchLineMatch[];\n    }\n    export interface SearchLineMatch {\n        lineNumber: number;\n        line: string;\n    }\n    export interface SearchMatchesResultView {\n        card: 'search';\n        shape: 'matches';\n        title?: string;\n        files: SearchFileMatches[];\n        truncated: boolean;\n        total: number;\n    }\n    export interface SearchPathsResultView {\n        card: 'search';\n        shape: 'paths';\n        title?: string;\n        paths: string[];\n        truncated: boolean;\n        total: number;\n    }\n    export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        readonly firstLiveSeq: number;\n        static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;\n        static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;\n        get events(): readonly SessionEvent[];\n        get seq(): number;\n        append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n            opts: SurfaceIntent\n        ] : [\n        ]): SessionEvent<T>;\n        requestHeader(): EpochHeader | undefined;\n        requestContext(): RequestContext | undefined;\n        deriveMessages(): Message[];\n        deriveEventMessage(event: SessionEvent): Message | null;\n    }\n    export type SessionEvent<T extends SessionEventType = SessionEventType> = {\n        [K in SessionEventType]: {\n            type: K;\n            seq: number;\n            time: number;\n            data: SessionEventMap[K];\n        } & (K extends SurfaceEventType ? {\n            sourceEventSeqs?: number[];\n            surfaceOp?: SurfaceOp;\n        } : object);\n    }[T];\n    export interface SessionEventMap {\n        'turn/start': {\n            turn: number;\n        };\n        'turn/end': {\n            turn: number;\n            reason: TurnEndReason;\n        };\n        'step/start': {\n            turn: number;\n            step: number;\n        };\n        'step/end': {\n            turn: number;\n            step: number;\n        };\n        'user/message': UserMessage;\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            message: AssistantMessage;\n            usage?: TokenUsage;\n        };\n        'tool/call': {\n            turn: number;\n            step: number;\n            callId: CallId;\n            name: string;\n            arguments: string;\n        };\n        'tool/result': {\n            turn: number;\n            step: number;\n            message: ToolResultMessage;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\n        'request/context': RequestContext;\n        'session/end-seed': Record<string, never>;\n    }\n    export type SessionEventType = keyof SessionEventMap;\n    export interface SessionHeader {\n        readonly version: number;\n        readonly id: SessionId;\n        readonly createdAt: number;\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly origin?: 'subagent';\n        readonly delegationDepth?: number;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface SessionSurface {\n        readonly nodes: readonly number[];\n        readonly replaceGeneration: number;\n    }\n    export type StreamChunk = {\n        type: 'block-start';\n        index: number;\n        blockType: ContentBlockType;\n    } | {\n        type: 'text-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'reasoning-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'tool-call-delta';\n        index: number;\n        id: CallId;\n        name?: string;\n        argumentsDelta: string;\n    } | {\n        type: 'block-end';\n        index: number;\n        block: ContentBlock;\n    } | {\n        type: 'usage';\n        usage: TokenUsage;\n    } | {\n        type: 'finish';\n        reason: FinishReason;\n        replayState?: unknown;\n    };\n    export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';\n    export interface SurfaceIntent {\n        surfaceOp: SurfaceOp;\n        sourceEventSeqs?: number[];\n    }\n    export type SurfaceOp = 'append' | {\n        op: 'replace';\n        start: number;\n        end: number;\n    };\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export interface TodoItem {\n        content: string;\n        status: 'pending' | 'in_progress' | 'completed';\n    }\n    export interface TokenUsage {\n        inputTokens: number;\n        outputTokens: number;\n        cacheReadTokens?: number;\n        cacheWriteTokens?: number;\n        reasoningTokens?: number;\n    }\n    export interface ToolCallBlock {\n        type: 'tool-call';\n        id: CallId;\n        name: string;\n        arguments: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        readonly output: ToolOutputDefinition;\n        execute(args: unknown, exec: ToolRunContext): Promise<unknown>;\n        finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionFailure {\n        readonly isError: true;\n        readonly error: ToolFailure;\n        readonly value?: never;\n        readonly content: ContentBlock[];\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: never;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        readonly signal: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n    export interface ToolExecutionSuccess {\n        readonly isError: false;\n        readonly value: JsonValue;\n        readonly content: ContentBlock[];\n        readonly error?: never;\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: true;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export interface ToolFailure {\n        message: string;\n        info?: ToolErrorInfo;\n    }\n    export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;\n    export interface ToolMessageSource {\n        kind: 'tool';\n        callId: CallId;\n    }\n    export interface ToolOutputDefinition {\n        readonly schema: JsonSchemaNode;\n        render(args: unknown, value: JsonValue): ContentBlock[];\n        presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n    }\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: JsonValue;\n    }\n    export interface ToolResultBlock {\n        type: 'tool-result';\n        toolCallId: CallId;\n        content: ContentBlock[];\n        isError?: boolean;\n    }\n    export interface ToolResultMessage extends Message {\n        readonly role: 'user';\n        readonly content: [\n            ToolResultBlock\n        ];\n        readonly source: ToolMessageSource;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: UserMessage): void;\n        concludeTurn(): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }\n    export type TurnEndCancelCause = AgentCancelCause | {\n        readonly kind: 'legacy';\n    };\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n            reason: TurnEndCancelCause;\n        };\n        blocked: {\n            kind: 'blocked';\n        };\n        error: {\n            kind: 'error';\n            error: LlmFailure;\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export interface UserMessage extends Message {\n        readonly role: 'user';\n    }\n    export interface WebFetchResultView {\n        card: 'web';\n        kind: 'fetch';\n        title?: string;\n        url: string;\n        statusCode: number;\n        truncated: boolean;\n    }\n    export type WebResultView = WebSearchResultView | WebFetchResultView;\n    export interface WebSearchResultView {\n        card: 'web';\n        kind: 'search';\n        title?: string;\n        sources: WebSource[];\n        answer?: string;\n        truncated: boolean;\n    }\n    export interface WebSource {\n        url: string;\n        title?: string;\n        snippet?: string;\n        publishedAt?: string;\n    }"}],"isError":false}],"role":"user","id":"847bf2e6-59da-4621-946d-06932a78f0ce"}},"sourceEventSeqs":[15],"surfaceOp":"append"}
+{"type":"tool/result","seq":16,"time":1785730459904,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - tool schema, execution, and optional finalization/presentation callbacks.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy,\n     * definition-owned content finalization, and final notification. Tool and\n     * listener failures resolve as materialized error results; an invisible tool\n     * reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen\n     * snapshot final observers receive. Cancellation\n     * arriving after entry and before final result materialization skips a\n     * not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a\n     * successful started outcome with `ABORTED`; already-started work is still\n     * drained and may retain a tool-owned structured error.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly inbox: Inbox;\n        readonly status: AgentStatus;\n        readonly ctx: Context;\n        cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n        whenIdle(): Promise<void>;\n        runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;\n        send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;\n        followup(message: UserMessage): void;\n        steer(message: UserMessage): void;\n        inject(message: UserMessage): void;\n    }\n    export type AgentCancelCause = {\n        readonly kind: 'user';\n    } | {\n        readonly kind: 'parent';\n    } | {\n        readonly kind: 'hook';\n        readonly reason: string;\n    } | {\n        readonly kind: 'disposed';\n    };\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n        maxTokens?: number;\n    }\n    export type AgentStatus = 'idle' | 'running';\n    export interface AssistantMessage extends Message {\n        readonly role: 'assistant';\n        readonly source: ModelMessageSource;\n    }\n    export interface AssistantProvenance {\n        provider: string;\n        model: string;\n        replayState?: unknown;\n    }\n    export type Branded<B extends string> = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export interface CancelOptions {\n        keepInbox?: boolean | undefined;\n    }\n    export interface ContentBlockMap {\n        'text': TextBlock;\n        'reasoning': ReasoningBlock;\n        'tool-call': ToolCallBlock;\n        'tool-result': ToolResultBlock;\n    }\n    export type ContentBlockType = keyof ContentBlockMap;\n    export type ContextFormed = {\n        readonly form?: never;\n    } | {\n        readonly form: 'instructions';\n    } | {\n        readonly form: 'catalog';\n    } | {\n        readonly form: 'snapshot';\n        readonly sections: readonly ContextSnapshotSection[];\n    } | {\n        readonly form: 'notice';\n        readonly summary: string;\n    } | {\n        readonly form: 'relay';\n    } | {\n        readonly form: 'recall';\n    };\n    export interface ContextSnapshotSection {\n        readonly name: string;\n        readonly text: string;\n    }\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface EpochHeader {\n        config: LlmCallConfig;\n        adapterDefaults?: LlmCallConfigAdapterDefaults;\n        system?: string;\n        tools?: ToolSchema[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export type FinishReason = FinishReasonMap[keyof FinishReasonMap];\n    export interface FinishReasonMap {\n        'stop': {\n            kind: 'stop';\n        };\n        'tool-calls': {\n            kind: 'tool-calls';\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        'aborted': {\n            kind: 'aborted';\n            failure: LlmFailure;\n        };\n        'error': {\n            kind: 'error';\n            failure: LlmFailure;\n        };\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export class Inbox {\n        constructor(private readonly session: Session, private readonly notifications: InboxNotifications);\n        get nextTurn(): readonly UserMessage[];\n        get nextStep(): readonly UserMessage[];\n        get hasPending(): boolean;\n        clear(): void;\n        claim(target: InboxTarget, turn: number): UserMessage[];\n        append(target: InboxTarget, message: UserMessage): void;\n        prepend(target: InboxTarget, message: UserMessage): void;\n        replace(messageId: MessageId, newMessage: UserMessage): boolean;\n        remove(messageId: MessageId): boolean;\n        splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];\n    }\n    export interface InboxNotifications {\n        inserted(message: UserMessage): void;\n        discarded(message: UserMessage): void;\n        claimed(message: UserMessage, turn: number): void;\n    }\n    export type InboxTarget = 'next-turn' | 'next-step';\n    export interface JsonSchemaNode {\n        type?: JsonSchemaType;\n        oneOf?: JsonSchemaNode[];\n        properties?: Record<string, JsonSchemaNode>;\n        required?: string[];\n        additionalProperties?: boolean;\n        items?: JsonSchemaNode;\n        enum?: JsonSchemaScalar[];\n        const?: JsonSchemaScalar;\n        description?: string;\n        title?: string;\n        default?: JsonValue;\n        examples?: JsonValue;\n    }\n    export type JsonSchemaScalar = string | number | boolean | null;\n    export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export interface LlmCallConfig {\n        provider: string;\n        model: string;\n        reasoningEffort?: ReasoningEffortId;\n        temperature?: number;\n        maxTokens?: number;\n        stop?: string[];\n    }\n    export interface LlmCallConfigAdapterDefaults {\n        reasoningEffort?: true;\n        maxTokens?: true;\n    }\n    export interface LlmFailure {\n        readonly message: string;\n        readonly code: string;\n        readonly status?: number;\n        readonly providerRetryAfterMs?: number;\n        readonly requestId?: ProviderRequestId;\n    }\n    export interface Message {\n        readonly id: MessageId;\n        readonly role: 'system' | 'user' | 'assistant';\n        readonly content: ContentBlock[];\n        readonly source: MessageSource;\n    }\n    export type MessageId = Branded<'MessageId'>;\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        } & ContextFormed;\n        model: ModelMessageSource;\n        tool: ToolMessageSource;\n    }\n    export interface ModelMessageSource extends AssistantProvenance {\n        kind: 'model';\n    }\n    export type ProviderRequestId = Branded<'ProviderRequestId'>;\n    export interface ReadFileLine {\n        number: number;\n        text: string;\n    }\n    export interface ReadResultView {\n        card: 'read';\n        title?: string;\n        path: string;\n        offset: number;\n        lines: ReadFileLine[];\n        totalLines: number;\n        lang?: string;\n        content?: ContentBlock[];\n    }\n    export interface ReasoningBlock {\n        type: 'reasoning';\n        text: string;\n    }\n    export type ReasoningEffortId = Branded<'ReasoningEffortId'>;\n    export interface RequestContext {\n        provider: string;\n        model: string;\n        contextWindow?: number;\n    }\n    export type RequestHeaderReason = 'initial' | 'resume' | 'change';\n    export type ScopeKey = object;\n    export interface SearchFileMatches {\n        path: string;\n        matches: SearchLineMatch[];\n    }\n    export interface SearchLineMatch {\n        lineNumber: number;\n        line: string;\n    }\n    export interface SearchMatchesResultView {\n        card: 'search';\n        shape: 'matches';\n        title?: string;\n        files: SearchFileMatches[];\n        truncated: boolean;\n        total: number;\n    }\n    export interface SearchPathsResultView {\n        card: 'search';\n        shape: 'paths';\n        title?: string;\n        paths: string[];\n        truncated: boolean;\n        total: number;\n    }\n    export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\n    export class Session {\n        get surface(): SessionSurface;\n        readonly header: SessionHeader;\n        get id(): SessionId;\n        readonly firstLiveSeq: number;\n        static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;\n        static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;\n        get events(): readonly SessionEvent[];\n        get seq(): number;\n        append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [\n            opts: SurfaceIntent\n        ] : [\n        ]): SessionEvent<T>;\n        requestHeader(): EpochHeader | undefined;\n        requestContext(): RequestContext | undefined;\n        deriveMessages(): Message[];\n        deriveEventMessage(event: SessionEvent): Message | null;\n    }\n    export type SessionEvent<T extends SessionEventType = SessionEventType> = {\n        [K in SessionEventType]: {\n            type: K;\n            seq: number;\n            time: number;\n            data: SessionEventMap[K];\n        } & (K extends SurfaceEventType ? {\n            sourceEventSeqs?: number[];\n            surfaceOp?: SurfaceOp;\n        } : object);\n    }[T];\n    export interface SessionEventMap {\n        'turn/start': {\n            turn: number;\n        };\n        'turn/end': {\n            turn: number;\n            reason: TurnEndReason;\n        };\n        'step/start': {\n            turn: number;\n            step: number;\n        };\n        'step/end': {\n            turn: number;\n            step: number;\n        };\n        'user/message': UserMessage;\n        'assistant/chunk': {\n            turn: number;\n            step: number;\n            chunk: StreamChunk;\n        };\n        'assistant/message': {\n            turn: number;\n            step: number;\n            message: AssistantMessage;\n            usage?: TokenUsage;\n        };\n        'tool/call': {\n            turn: number;\n            step: number;\n            callId: CallId;\n            name: string;\n            arguments: string;\n        };\n        'tool/result': {\n            turn: number;\n            step: number;\n            message: ToolResultMessage;\n            error?: {\n                name: string;\n                code: string;\n            };\n            meta?: JsonValue;\n        };\n        'todo/write': {\n            todos: TodoItem[];\n        };\n        'request/header': {\n            header: EpochHeader;\n            reason: RequestHeaderReason;\n        };\n        'request/context': RequestContext;\n        'session/end-seed': Record<string, never>;\n    }\n    export type SessionEventType = keyof SessionEventMap;\n    export interface SessionHeader {\n        readonly version: number;\n        readonly id: SessionId;\n        readonly createdAt: number;\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n        readonly origin?: 'subagent';\n        readonly delegationDepth?: number;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface SessionSurface {\n        readonly nodes: readonly number[];\n        readonly replaceGeneration: number;\n    }\n    export type StreamChunk = {\n        type: 'block-start';\n        index: number;\n        blockType: ContentBlockType;\n    } | {\n        type: 'text-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'reasoning-delta';\n        index: number;\n        text: string;\n    } | {\n        type: 'tool-call-delta';\n        index: number;\n        id: CallId;\n        name?: string;\n        argumentsDelta: string;\n    } | {\n        type: 'block-end';\n        index: number;\n        block: ContentBlock;\n    } | {\n        type: 'usage';\n        usage: TokenUsage;\n    } | {\n        type: 'finish';\n        reason: FinishReason;\n        replayState?: unknown;\n    };\n    export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';\n    export interface SurfaceIntent {\n        surfaceOp: SurfaceOp;\n        sourceEventSeqs?: number[];\n    }\n    export type SurfaceOp = 'append' | {\n        op: 'replace';\n        start: number;\n        end: number;\n    };\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export interface TodoItem {\n        content: string;\n        status: 'pending' | 'in_progress' | 'completed';\n    }\n    export interface TokenUsage {\n        inputTokens: number;\n        outputTokens: number;\n        cacheReadTokens?: number;\n        cacheWriteTokens?: number;\n        reasoningTokens?: number;\n    }\n    export interface ToolCallBlock {\n        type: 'tool-call';\n        id: CallId;\n        name: string;\n        arguments: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        readonly output: ToolOutputDefinition;\n        execute(args: unknown, exec: ToolRunContext): Promise<unknown>;\n        finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly rootCallId: CallId;\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionFailure {\n        readonly isError: true;\n        readonly error: ToolFailure;\n        readonly value?: never;\n        readonly content: ContentBlock[];\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: never;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly rootCallId?: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        readonly signal: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\n    export interface ToolExecutionSuccess {\n        readonly isError: false;\n        readonly value: JsonValue;\n        readonly content: ContentBlock[];\n        readonly error?: never;\n        readonly meta?: JsonValue;\n        readonly additionalContexts?: UserMessage[];\n        readonly concludesTurn?: true;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export interface ToolFailure {\n        message: string;\n        info?: ToolErrorInfo;\n    }\n    export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;\n    export interface ToolMessageSource {\n        kind: 'tool';\n        callId: CallId;\n    }\n    export interface ToolOutputDefinition {\n        readonly schema: JsonSchemaNode;\n        render(args: unknown, value: JsonValue): ContentBlock[];\n        presentationMeta?(args: unknown, value: JsonValue): JsonValue;\n    }\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: JsonValue;\n    }\n    export interface ToolResultBlock {\n        type: 'tool-result';\n        toolCallId: CallId;\n        content: ContentBlock[];\n        isError?: boolean;\n    }\n    export interface ToolResultMessage extends Message {\n        readonly role: 'user';\n        readonly content: [\n            ToolResultBlock\n        ];\n        readonly source: ToolMessageSource;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: UserMessage): void;\n        concludeTurn(): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }\n    export type TurnEndCancelCause = AgentCancelCause | {\n        readonly kind: 'legacy';\n    };\n    export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];\n    export interface TurnEndReasonMap {\n        completed: {\n            kind: 'completed';\n        };\n        aborted: {\n            kind: 'aborted';\n            reason: TurnEndCancelCause;\n        };\n        blocked: {\n            kind: 'blocked';\n        };\n        error: {\n            kind: 'error';\n            error: LlmFailure;\n        };\n        'max-tokens': {\n            kind: 'max-tokens';\n        };\n        interrupted: {\n            kind: 'interrupted';\n        };\n    }\n    export interface UserMessage extends Message {\n        readonly role: 'user';\n    }\n    export interface WebFetchResultView {\n        card: 'web';\n        kind: 'fetch';\n        title?: string;\n        url: string;\n        statusCode: number;\n        truncated: boolean;\n    }\n    export type WebResultView = WebSearchResultView | WebFetchResultView;\n    export interface WebSearchResultView {\n        card: 'web';\n        kind: 'search';\n        title?: string;\n        sources: WebSource[];\n        answer?: string;\n        truncated: boolean;\n    }\n    export interface WebSource {\n        url: string;\n        title?: string;\n        snippet?: string;\n        publishedAt?: string;\n    }"}],"isError":false}],"role":"user","id":"2ec5ca51-ec8b-4756-8c71-c20fb871b421"}},"sourceEventSeqs":[15],"surfaceOp":"append"}
 {"type":"step/end","seq":17,"time":1785730459904,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":18,"time":1785730459916,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":19,"time":1784449176734,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
diff --git a/examples/acp-agent/tests/snapshots/empty-response-retry/session.jsonl b/examples/acp-agent/tests/snapshots/empty-response-retry/session.jsonl
index b619d352e5..2c294b76d4 100644
--- a/examples/acp-agent/tests/snapshots/empty-response-retry/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/empty-response-retry/session.jsonl
@@ -10,12 +10,13 @@
 {"type":"request/context","seq":8,"time":1785730441192,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":9,"time":1785498788105,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":0,"outputTokens":0}}}}
 {"type":"assistant/chunk","seq":10,"time":1785730441201,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"model returned a completed response with no content","code":"EMPTY_RESPONSE"}}}}}
-{"type":"llm/retry","seq":11,"time":1785730441201,"data":{"turn":1,"step":1,"provider":"deepseek-official","mode":"normal","policyKey":"[\"normal\",2,[\"EMPTY_RESPONSE\",\"RATE_LIMIT\",\"SERVER\",\"TIMEOUT\",\"TRANSPORT\"],1,1,0]","retry":1,"maxRetries":2,"delayMs":1,"failure":{"message":"model returned a completed response with no content","code":"EMPTY_RESPONSE"}}}
-{"type":"assistant/chunk","seq":12,"time":1785498788113,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":13,"time":1785498788113,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"Recovered."}}}
-{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"Recovered."}}}}
-{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":12,"outputTokens":3}}}}
-{"type":"assistant/chunk","seq":16,"time":1785730441209,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":17,"time":1785730441209,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"Recovered."}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"422eae65-9975-4a95-8cde-1ddfe21fff4e"},"usage":{"inputTokens":12,"outputTokens":3}},"sourceEventSeqs":[12,13,14,15,16],"surfaceOp":"append"}
-{"type":"step/end","seq":18,"time":1785730441209,"data":{"turn":1,"step":1}}
-{"type":"turn/end","seq":19,"time":1785730441209,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"llm/retry","seq":11,"time":1785730441201,"data":{"retryId":"dbe1e1b0-a914-48a4-ad9f-407b213a37ae","turn":1,"step":1,"provider":"deepseek-official","mode":"normal","policyKey":"[\"normal\",2,[\"EMPTY_RESPONSE\",\"RATE_LIMIT\",\"SERVER\",\"TIMEOUT\",\"TRANSPORT\"],1,1,0]","retry":1,"maxRetries":2,"delayMs":1,"failure":{"message":"model returned a completed response with no content","code":"EMPTY_RESPONSE"}}}
+{"type":"llm/retry-started","seq":12,"time":1786238385130,"data":{"retryId":"dbe1e1b0-a914-48a4-ad9f-407b213a37ae","turn":1,"step":1,"retry":1}}
+{"type":"assistant/chunk","seq":13,"time":1785498788113,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"Recovered."}}}
+{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"Recovered."}}}}
+{"type":"assistant/chunk","seq":16,"time":1785730441209,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":12,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":17,"time":1786238385135,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":18,"time":1786238385135,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"Recovered."}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"422eae65-9975-4a95-8cde-1ddfe21fff4e"},"usage":{"inputTokens":12,"outputTokens":3}},"sourceEventSeqs":[13,14,15,16,17],"surfaceOp":"append"}
+{"type":"step/end","seq":19,"time":1786238385135,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":20,"time":1786238385135,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
index 6769414d10..646110b6d9 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
@@ -24,8 +24,8 @@
 {"type":"assistant/chunk","seq":22,"time":1785730501424,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":23,"time":1785730501424,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"cdc95327-3ce1-49ea-8a92-b17e450cc455"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[18,19,20,21,22],"surfaceOp":"append"}
 {"type":"tool/call","seq":24,"time":1785730501424,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}}
-{"type":"tool/code-dispatch-start","seq":25,"time":1785730501473,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}
-{"type":"tool/code-dispatch","seq":26,"time":1785730501474,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}
+{"type":"tool/code-dispatch-start","seq":25,"time":1785730501473,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}
+{"type":"tool/code-dispatch","seq":26,"time":1785730501474,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}
 {"type":"tool/result","seq":27,"time":1785730501475,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"advanced-code"},"content":[{"type":"tool-result","toolCallId":"advanced-code","content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}],"isError":false}],"role":"user","id":"d75c7d03-cbbc-4260-ba40-8c210a3b5bbe"}},"sourceEventSeqs":[24],"surfaceOp":"append"}
 {"type":"step/end","seq":28,"time":1785730501475,"data":{"turn":1,"step":2}}
 {"type":"step/start","seq":29,"time":1785730501483,"data":{"turn":1,"step":3}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.expected.jsonl
index c342059741..817ee1e1a2 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.expected.jsonl
@@ -23,8 +23,8 @@
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":22,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":23,"time":0,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[18,19,20,21,22],"surfaceOp":"append"}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":24,"time":0,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.cordis_inspect({ what: 'temporary' })\", \"description\": \"Run the scripted inspection program\"}"}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/code-dispatch-start","seq":25,"time":0,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/code-dispatch","seq":26,"time":0,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/code-dispatch-start","seq":25,"time":0,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/code-dispatch","seq":26,"time":0,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"temporary"},"isError":false,"content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}]}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":27,"time":0,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"advanced-code"},"content":[{"type":"tool-result","toolCallId":"advanced-code","content":[{"type":"text","text":"## Temporary Plugins\n- Temporary Plugin dyn-1: snapshot-marker [running] — provides: none; waiting for: none; lifetime: until unmounted or DSH restarts"}],"isError":false}],"role":"user","id":"{{sessionId}}"}},"sourceEventSeqs":[24],"surfaceOp":"append"}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":28,"time":0,"data":{"turn":1,"step":2}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":29,"time":0,"data":{"turn":1,"step":3}}}
diff --git a/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl b/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
index 38056019e2..9e39f76b11 100644
--- a/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/compaction-recovery/session.jsonl
@@ -1,32 +1,32 @@
 {"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
-{"type":"agent/inbox/spliced","seq":0,"time":1786123401613,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"6335ca4a-a577-47dd-8219-aa81f39cdbc0"}]}}
+{"type":"agent/inbox/spliced","seq":0,"time":1786123401613,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"203f911d-905a-43e4-8e1c-fccfe78d445b"}]}}
 {"type":"turn/start","seq":1,"time":1786123401614,"data":{"turn":1}}
 {"type":"agent/inbox/spliced","seq":2,"time":1786123401614,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","seq":3,"time":1786123401667,"data":{"turn":1,"step":1}}
-{"type":"user/message","seq":4,"time":1786123401667,"data":{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"6335ca4a-a577-47dd-8219-aa81f39cdbc0"},"surfaceOp":"append"}
+{"type":"user/message","seq":4,"time":1786123401667,"data":{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compact/start and closes with compact/end; a successful auxiliary summary records compact/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"203f911d-905a-43e4-8e1c-fccfe78d445b"},"surfaceOp":"append"}
 {"type":"session/title","seq":5,"time":1786123401667,"data":{"title":"Establish a durable compaction premise","messageSeqs":[4],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":6,"time":1786123401668,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":6,"time":1786123401668,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"interrupt_agent","description":"Request cancellation of a background agent's current turn by its agent id. The target may be your direct child or a deeper agent created under you. Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups. This call returns as soon as the stop request is accepted, so the target may keep running briefly; interrupting an agent that already finished is an accepted no-op.","parameters":{"type":"object","properties":{"agent_id":{"type":"string","description":"The agent id of the running agent to interrupt."}},"required":["agent_id"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":7,"time":1786123401669,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":128000}}
 {"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
 {"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_compaction_marker","name":"bash","argumentsDelta":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}}
 {"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}}}
 {"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":24,"outputTokens":6}}}}
 {"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":13,"time":1786123401680,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"e54f73a8-572a-40ee-b908-8a8a27b83bf8"},"usage":{"inputTokens":24,"outputTokens":6}},"sourceEventSeqs":[8,9,10,11,12],"surfaceOp":"append"}
+{"type":"assistant/message","seq":13,"time":1786123401680,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"6e7dfb28-f033-4dbf-9fd9-6b2f71da6906"},"usage":{"inputTokens":24,"outputTokens":6}},"sourceEventSeqs":[8,9,10,11,12],"surfaceOp":"append"}
 {"type":"tool/call","seq":14,"time":1786123401680,"data":{"turn":1,"step":1,"callId":"call_compaction_marker","name":"bash","arguments":"{\"command\":\"printf 'alpha\\n'\",\"description\":\"Emit compaction premise marker\"}"}}
-{"type":"tool/result","seq":15,"time":1786123401700,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_compaction_marker"},"content":[{"type":"tool-result","toolCallId":"call_compaction_marker","content":[{"type":"text","text":"alpha\n"}],"isError":false}],"role":"user","id":"b4a6504e-f39d-40b0-b51a-b11fbd60b135"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"tool/result","seq":15,"time":1786123401700,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_compaction_marker"},"content":[{"type":"tool-result","toolCallId":"call_compaction_marker","content":[{"type":"text","text":"alpha\n"}],"isError":false}],"role":"user","id":"4fe4e523-3ac9-421c-8a73-1eb033ac8b09"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
 {"type":"step/end","seq":16,"time":1786123401700,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":17,"time":1786123401710,"data":{"turn":1,"step":2}}
 {"type":"assistant/chunk","seq":18,"time":1786123401715,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot request exceeded the model context window","code":"CONTEXT_WINDOW_EXCEEDED"}}}}}
-{"type":"compact/start","seq":19,"time":1786123401715,"data":{"turn":1}}
-{"type":"compact/summary","seq":20,"time":1786123401725,"data":{"summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}
-{"type":"user/message","seq":21,"time":1786123401725,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"6d2afb13-a37b-48d6-9ea5-fc8734127377"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}
-{"type":"compact/end","seq":22,"time":1786123401725,"data":{"turn":1}}
+{"type":"compact/start","seq":19,"time":1786123401715,"data":{"compactionId":"338e88fa-e78b-4d49-bd38-8f919e85f5e1","turn":1}}
+{"type":"compact/summary","seq":20,"time":1786123401725,"data":{"compactionId":"338e88fa-e78b-4d49-bd38-8f919e85f5e1","summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}
+{"type":"user/message","seq":21,"time":1786123401725,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact","compactionId":"338e88fa-e78b-4d49-bd38-8f919e85f5e1"},"role":"user","id":"b74220bf-4104-4c30-b967-e4570d5eba5d"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}
+{"type":"compact/end","seq":22,"time":1786123401725,"data":{"compactionId":"338e88fa-e78b-4d49-bd38-8f919e85f5e1","turn":1}}
 {"type":"assistant/chunk","seq":23,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":24,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"COMPACTION RECOVERED"}}}
 {"type":"assistant/chunk","seq":25,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"COMPACTION RECOVERED"}}}}
 {"type":"assistant/chunk","seq":26,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":20,"outputTokens":4}}}}
 {"type":"assistant/chunk","seq":27,"time":1786123401730,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":28,"time":1786123401730,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"COMPACTION RECOVERED"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"346742d0-50e3-4594-b53c-f26c7da82c56"},"usage":{"inputTokens":20,"outputTokens":4}},"sourceEventSeqs":[23,24,25,26,27],"surfaceOp":"append"}
+{"type":"assistant/message","seq":28,"time":1786123401730,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"COMPACTION RECOVERED"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"103034c2-e156-4808-ba2e-8e17e7107c9e"},"usage":{"inputTokens":20,"outputTokens":4}},"sourceEventSeqs":[23,24,25,26,27],"surfaceOp":"append"}
 {"type":"step/end","seq":29,"time":1786123401730,"data":{"turn":1,"step":2}}
 {"type":"turn/end","seq":30,"time":1786123401730,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
index 62cc357cc7..c5bca170ba 100644
--- a/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/compaction-recovery/stream-json.expected.jsonl
@@ -17,10 +17,10 @@
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":16,"time":0,"data":{"turn":1,"step":1}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":17,"time":0,"data":{"turn":1,"step":2}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot request exceeded the model context window","code":"CONTEXT_WINDOW_EXCEEDED"}}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/start","seq":19,"time":0,"data":{"turn":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/summary","seq":20,"time":0,"data":{"summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":21,"time":0,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"{{sessionId}}"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/end","seq":22,"time":0,"data":{"turn":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/start","seq":19,"time":0,"data":{"compactionId":"{{sessionId}}","turn":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/summary","seq":20,"time":0,"data":{"compactionId":"{{sessionId}}","summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":4,"end":4},"shadowedSeqs":[4],"shadowedTokenCount":264,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":21,"time":0,"data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n<compacted-summary>"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":"</compacted-summary>"}],"source":{"kind":"plugin","plugin":"compact","compactionId":"{{sessionId}}"},"role":"user","id":"{{sessionId}}"},"sourceEventSeqs":[19,20,4],"surfaceOp":{"op":"replace","start":4,"end":4}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"compact/end","seq":22,"time":0,"data":{"compactionId":"{{sessionId}}","turn":1}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":23,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":24,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"COMPACTION RECOVERED"}}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":25,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"COMPACTION RECOVERED"}}}}}
diff --git a/examples/headless-agent/tests/snapshots/provider-retry/stream-json.expected.jsonl b/examples/headless-agent/tests/snapshots/provider-retry/stream-json.expected.jsonl
index ca523f3665..3c6e45c243 100644
--- a/examples/headless-agent/tests/snapshots/provider-retry/stream-json.expected.jsonl
+++ b/examples/headless-agent/tests/snapshots/provider-retry/stream-json.expected.jsonl
@@ -7,13 +7,14 @@
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/header","seq":6,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/context","seq":7,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}}
 {"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot transient failure","code":"RATE_LIMIT","status":429}}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"llm/retry","seq":9,"time":0,"data":{"turn":1,"step":1,"provider":"deepseek-official","mode":"normal","policyKey":"[\"normal\",1,[\"RATE_LIMIT\"],1,1,0]","retry":1,"maxRetries":1,"delayMs":1,"failure":{"message":"snapshot transient failure","code":"RATE_LIMIT","status":429}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"RETRY_OK"}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"RETRY_OK"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":13,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":4,"outputTokens":2}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":15,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"RETRY_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":4,"outputTokens":2}},"sourceEventSeqs":[10,11,12,13,14],"surfaceOp":"append"}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":16,"time":0,"data":{"turn":1,"step":1}}}
-{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":17,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"llm/retry","seq":9,"time":0,"data":{"retryId":"{{sessionId}}","turn":1,"step":1,"provider":"deepseek-official","mode":"normal","policyKey":"[\"normal\",1,[\"RATE_LIMIT\"],1,1,0]","retry":1,"maxRetries":1,"delayMs":1,"failure":{"message":"snapshot transient failure","code":"RATE_LIMIT","status":429}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"llm/retry-started","seq":10,"time":0,"data":{"retryId":"{{sessionId}}","turn":1,"step":1,"retry":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"RETRY_OK"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":13,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"RETRY_OK"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":4,"outputTokens":2}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":16,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"RETRY_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":4,"outputTokens":2}},"sourceEventSeqs":[11,12,13,14,15],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":17,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":18,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
 {"type":"result","sessionId":"{{sessionId}}","output":"RETRY_OK","usage":{"inputTokens":4,"outputTokens":2}}
diff --git a/packages/bash/bash-env/tests/bash-env.spec.ts b/packages/bash/bash-env/tests/bash-env.spec.ts
index c93a768f80..eb482fd9d3 100644
--- a/packages/bash/bash-env/tests/bash-env.spec.ts
+++ b/packages/bash/bash-env/tests/bash-env.spec.ts
@@ -23,6 +23,7 @@ function execution(sessionId?: string): ToolExecution {
     signal: testToolSignal,
     token: Symbol('bash-env-test') as ToolExecution['token'],
     callId: CallId('bash-env-call'),
+    rootCallId: CallId('bash-env-call'),
     name: 'bash',
     arguments: { command: 'true' },
     ...(sessionId === undefined
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 24f5668d42..d755f73354 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -96,7 +96,7 @@ function sgr(code: number, body: string): string {
 }
 
 /**
- * Terminal output sample for fixture turn 65, authored to carry every feature
+ * Terminal output sample for fixture turn 66, authored to carry every feature
  * the terminal card draws that turn 60's two prompt rows cannot reach:
  * basic-16 SGR foreground runs (green, red, bright-black) that must resolve to
  * `--dsw-*` tokens, a bold run, column-aligned table rows that must scroll
@@ -141,7 +141,7 @@ const TERMINAL_EXIT_STATUS: Record<string, { exitCode: number } | { signal: stri
 }
 
 /**
- * Structured grep result for the search sample (turn 66): matches grouped by
+ * Structured grep result for the search sample (turn 67): matches grouped by
  * file, authored inline because the client-side fixture cannot import the tool
  * that produces the canonical value. `truncated` with a larger `total` than the
  * retained match count exercises the search card's capped indicator; the file
@@ -191,7 +191,7 @@ const SEARCH_MATCHES_TEXT = [
 ].join('\n')
 
 /**
- * Structured glob result for the search sample (turn 67): a flat path list,
+ * Structured glob result for the search sample (turn 68): a flat path list,
  * truncated with a larger `total` so the path card shows its capped indicator.
  */
 const SEARCH_PATHS_FIXTURE = [
@@ -426,19 +426,19 @@ function buildAlphaLog(): SessionEvent[] {
   toolTurn(61, 'fx-write', '{"path":"notes/demo.txt","content":"hello fixture\\n"}', 'wrote notes/demo.txt')
   toolTurn(62, 'edit', '{"file_path":"notes/demo.txt","old_string":"hello","new_string":"hello fixture"}', '已编辑')
   toolTurn(63, 'write', '{"file_path":"notes/new-demo.txt","content":"hello fixture\\n"}', '已写入')
-  // Turn 67: a multi-hunk edit — two scattered replacements in one file. Named
+  // Turn 64: a multi-hunk edit — two scattered replacements in one file. Named
   // `edit` so it lands on the keyed FileMutationRow (the resident diff card the
   // single-hunk turn 62 also uses), and file_path `src/config.ts` is the marker
   // the presenter reads to emit the two-hunk sample: the card draws one path
   // header, the first hunk, a `⋯` gap, then the second (the same-file
   // second-hunk arm turns 62/63 cannot reach).
-  toolTurn(67, 'edit', '{"file_path":"src/config.ts","old_string":"const timeout = 30","new_string":"const timeout = 60"}', '已编辑')
-  // Turn 64: one run_code turn with three logged sub-dispatches — the Code
+  toolTurn(64, 'edit', '{"file_path":"src/config.ts","old_string":"const timeout = 30","new_string":"const timeout = 60"}', '已编辑')
+  // Turn 65: one run_code turn with three logged sub-dispatches — the Code
   // Mode acceptance surface (parent code row + nested native-identical rows,
   // including an isError sub-call and a bash sub-call that must hit the same
   // keyed registration a top-level bash row uses).
   {
-    const turn = 64
+    const turn = 65
     const callId = `fx-call-${turn}`
     const program = 'const listing = await tools.bash({ command: "ls notes", description: "List notes" })\n'
       + 'const demo = await tools.read({ file_path: "notes/demo.txt" })\n'
@@ -456,12 +456,12 @@ function buildAlphaLog(): SessionEvent[] {
     const dispatchPair = (n: number, name: string, dispatchArgs: Record<string, unknown>, resultText: string, isError = false): void => {
       push({
         type: 'tool/code-dispatch-start',
-        data: { parentCallId: callId, subCallId: `${callId}:code:${n}`, name, arguments: dispatchArgs },
+        data: { rootCallId: callId, parentCallId: callId, subCallId: `${callId}:code:${n}`, name, arguments: dispatchArgs },
       })
       push({
         type: 'tool/code-dispatch',
         data: {
-          parentCallId: callId, subCallId: `${callId}:code:${n}`, name,
+          rootCallId: callId, parentCallId: callId, subCallId: `${callId}:code:${n}`, name,
           arguments: dispatchArgs, isError, content: [{ type: 'text', text: resultText }],
         },
       })
@@ -476,7 +476,7 @@ function buildAlphaLog(): SessionEvent[] {
     push({ type: 'step/end', data: { turn, step: 0 } })
     push({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
   }
-  // Turn 71: todo_write sample — the TodoRow toolview in the flow plus the
+  // Turn 72: todo_write sample — the TodoRow toolview in the flow plus the
   // todo/write snapshot event feeding the TodoPanel plan strip. Two items are
   // in_progress: this fixture chooses the parallel policy, so both surfaces
   // must render a parallel plan rather than the first active item alone.
@@ -486,7 +486,7 @@ function buildAlphaLog(): SessionEvent[] {
     { content: '跑后台构建', status: 'in_progress' },
     { content: '浏览器验收', status: 'pending' },
   ]
-  // Turn 65: the terminal sample turn 60's two clean prompt rows cannot cover —
+  // Turn 66: the terminal sample turn 60's two clean prompt rows cannot cover —
   // ANSI SGR coloring, output past the terminal card's height cap, a nested cwd
   // whose prompt label is its last segment, and a non-zero exit authored beside
   // the sample in TERMINAL_EXIT_STATUS — its body deliberately carries no
@@ -498,45 +498,45 @@ function buildAlphaLog(): SessionEvent[] {
   // Ordered BEFORE the todo turn deliberately: the standing plan retires at the
   // next `turn/start`, so a turn appended after it would leave the dock's plan
   // strip empty and take the todo surfaces' own coverage with it.
-  toolTurn(65, 'bash', '{"command":"pnpm run check","cwd":"/tmp/fixture/deep/nested"}', TERMINAL_OUTPUT_FIXTURE)
+  toolTurn(66, 'bash', '{"command":"pnpm run check","cwd":"/tmp/fixture/deep/nested"}', TERMINAL_OUTPUT_FIXTURE)
 
-  // Turns 66-67: the search card's two shapes. `grep` emits a `card: 'search'`
+  // Turns 67-68: the search card's two shapes. `grep` emits a `card: 'search'`
   // `shape: 'matches'` result view (grouped-by-file matches, truncated with a
   // larger `total`), `glob` emits `shape: 'paths'` (a flat path list, likewise
   // truncated). Both ride the keyed SearchRow registration under their own
   // names; the render-site fallback row is covered by the model derivation
   // tests, since every fixture search tool has a keyed row. Ordered before the
   // todo turn for the same standing-plan reason the bash turn is.
-  toolTurn(66, 'grep', '{"pattern":"SEARCH_MAX_LINES","path":"packages/client"}', SEARCH_MATCHES_TEXT)
-  toolTurn(67, 'glob', '{"pattern":"**/SearchBlock*","path":"packages/client"}', SEARCH_PATHS_TEXT)
+  toolTurn(67, 'grep', '{"pattern":"SEARCH_MAX_LINES","path":"packages/client"}', SEARCH_MATCHES_TEXT)
+  toolTurn(68, 'glob', '{"pattern":"**/SearchBlock*","path":"packages/client"}', SEARCH_PATHS_TEXT)
 
-  // Turn 68: the read sample — a WINDOW past an offset so the card draws file
+  // Turn 69: the read sample — a WINDOW past an offset so the card draws file
   // line numbers starting above 1 and a "showing N of M" note (the window is
   // shorter than READ_SAMPLE_TOTAL), with a `ts` language hint the shiki path
   // highlights. Named `read`, so it exercises the keyed ReadRow registration.
   // The render-site fallback ROW SHAPE (a read call on the generic flattened
-  // path) is covered by the turn 64 run_code read sub-dispatches, which
+  // path) is covered by the turn 65 run_code read sub-dispatches, which
   // session.ts folds with resultView: null; the fallback-row + read-CARD
   // combination is pinned by the web_fetch case in read-card.spec.tsx, not by
   // this fixture. The read render intent is result-side only, so its pending
   // call stays a generic `kind: 'read'` card; presentResult carries the
   // structured window.
-  toolTurn(68, 'read', `{"file_path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)
+  toolTurn(69, 'read', `{"file_path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)
 
-  // Turns 69-70: the web render intent — a web_search whose result view carries
+  // Turns 70-71: the web render intent — a web_search whose result view carries
   // structured sources plus an answer (the citation list, one source lacking a
   // title so its hostname labels the link, the capped indicator on), and a
   // web_fetch whose result view carries the fetched URL and its HTTP status.
   // Both keep a generic pending call view and add the `web` card only at
   // result time, which is the contract's result-only web shape. Named after
   // the real tools so they hit the keyed WebRow registration. Ordered BEFORE
-  // the todo turn for the same reason turn 65 is: the standing plan retires at
+  // the todo turn for the same reason turn 66 is: the standing plan retires at
   // the next turn/start, so a turn after it would empty the dock's plan strip.
-  toolTurn(69, 'web_search', '{"query":"deepseek harness architecture"}', 'Search results for deepseek harness architecture.')
-  toolTurn(70, 'web_fetch', '{"url":"https://www.deepseek.com/blog/harness-architecture"}', '# Harness architecture\n\nEverything is a plugin.')
+  toolTurn(70, 'web_search', '{"query":"deepseek harness architecture"}', 'Search results for deepseek harness architecture.')
+  toolTurn(71, 'web_fetch', '{"url":"https://www.deepseek.com/blog/harness-architecture"}', '# Harness architecture\n\nEverything is a plugin.')
 
   const todoArgs = JSON.stringify({ todos: fixtureTodos })
-  toolTurn(71, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 2 in progress, 1 completed.')
+  toolTurn(72, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 2 in progress, 1 completed.')
   // The real tool appends the snapshot mid-execution — between tool/call and
   // tool/result — so the fixture reproduces that exact ordering (the last
   // toolTurn events run ... tool/call, tool/result, step/end, turn/end).
@@ -578,7 +578,7 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
     case 'read':
       return { card: 'generic', title: `Read ${str(args.file_path)}`, kind: 'read', locations: [{ path: str(args.file_path) }] }
     case 'edit':
-      // The multi-hunk sample (turn 67) is keyed on its file_path, so the two
+      // The multi-hunk sample (turn 64) is keyed on its file_path, so the two
       // scattered hunks share one path header and the card draws the `⋯` gap.
       if (str(args.file_path) === 'src/config.ts') {
         return {
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index e1c07abae3..4aed1d0f36 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: bd8528e97b04d5b4b28922266306969e8f19295a
-README.zh.md: 9aea486fb17c5a170ee8c1195435d220b495b615
+README.md: b2bb06e50ecd791d74cb609404dd219e5a21913e
+README.zh.md: 72cd99ac765875c828cc9163d978e0b8fb7f44e4
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index bd8528e97b..b2bb06e50e 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -34,11 +34,13 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 `ConversationSnapshot.queue` is the Host's authoritative transient snapshot of `agent.inbox.nextTurn`; pending next-step steering stays outside this projection. Each row carries its `MessageId`, complete editable text when every content block is text, and a flattened preview. The Host derives whole `session/queue` snapshots from durable `agent/inbox/spliced` mutations and sends a baseline on reconnect; the message-local `agent/inbox/inserted`, `claimed`, and `discarded` notifications are not used to reconstruct this projection. `Session.updateQueue()` sends edit/remove operations through Host-side `Inbox.splice()` without optimistic client mutation, so the next Host snapshot is the sole visible commit and a claim race can surface `queue-item-not-found`.
 
-## The human transcript
+## Conversation assembly
 
-`ConversationSnapshot.nodes` is the human transcript, not the model surface. `TranscriptAdapter` projects the raw window in log order — every append-origin surface event (`isAppendSurfaceEvent`) at its own log position, plus one `CompactionSummaryNode` marker per landed compaction checkpoint — and never consults surface order. `SteeringHistory` replays the durable `agent/inbox/spliced` records in that window: a user-origin message claimed from `next-step` becomes a `SteeringMessageNode` when its matching `user/message` lands, a `next-turn` claim stays a user node, and non-user next-step input stays context. `ConversationSnapshot.turnEnds` maps each completed turn in that window to its `turn/end` seq, retaining turn completion independently from the transcript so presentation can require a real boundary before enabling an action. A landed compaction therefore keeps the conversation it shadowed on the model side: the marker reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies stay out: a pruned `tool/result` and a regenerated `assistant/message` rewrite one node for the model and mark no boundary. A checkpoint is a `user/message` carrying the compaction seam's plugin source that **replaced** a surface range; an appending plugin-sourced `user/message` is injected context, not a compaction. Each context node also carries a `provenance` view with the producer role and name: `contextProvenance()` reads the durable source alone to decide whether the row is an `inject` or a cross-session `recall`, and to name its producer from the instruction paths, referenced session titles, or plugin id that source already records. The client holds no table of plugin ids, so a renamed or newly mounted producer stays identifiable without a client release and a resumed or foreign log projects exactly like a live one; a source with no readable kind degrades to an unnamed injection. Beside it, `contextForm()` reads the producer-declared `ContextForm` — the second, independent axis: `kind` says who produced the context, `form` says what shape of information it is, so several producers may share one form. A form this UI version does not present projects as null and renders opaque. The adapter's plugin literal is pinned to the Service Definition's declaration by a type-only import of the cordis-free [`dsh-compact/checkpoint`](../../compact/compact/README.md) leaf, so renaming it there fails `tsc` here; a **value** import of the package would fail the client purity gate, and the package **root** is unreachable even as a type (it reaches `dsh-session`'s root, whose `Context` merge collides the host `sessions` with this program's).
+Each `Session` gives its contiguous event window to a `ConversationNodeAssembler`. Plugins register business Definitions that map one event to a stable `{kind, id}`, create State at the unique start event, fold correlated updates, and build final nodes for registered view targets. The assembler owns the Context index, read-only predecessor lookup, and a reference-stable Turn/Step Location index. A live append evaluates each Definition once and updates only the matched Context; loading an older page preserves existing Context and node identities, matches only the newly prepended events, and replays Contexts whose predecessor or Location facts changed. Full replacement is reserved for open, resync, and gap repair.
 
-Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's cited `compact/summary` event; a window cut that left that event outside makes those fields unavailable, and a later page that supplies it resolves them. `CommandNode.outcome.sourceEventSeq` preserves a successful command's explicit reference to that summary event, allowing the presentation layer to pair `/compact` with its checkpoint without parsing settlement copy or assuming the two rows are adjacent. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
+`ui-conversation` registers the built-in Chat Definitions and the keyed Chat snapshot builder. Append-origin user, assistant, and Tool results remain the human record; model-only replacement copies stay out, except that a compaction checkpoint becomes its own marker and resolves missing summary provenance when an older page supplies it. Durable inbox splice Contexts classify next-step user messages as steering without making inbox state a Session special case. Context messages retain producer provenance and form. `ConversationSnapshot.nodes`, `partial`, and `runningCalls` are compatibility slices derived from the same materialized Chat nodes for consumers that have not moved to `ConversationSnapshot.chat`; Session does not run a second business fold.
+
+The Chat builder keeps one mutable keyed store per Session. Content updates notify only the affected node key, structural changes rebuild order and Location membership, and a prepend adds rows without replacing existing keyed values. Assistant chunks update Definition State for every event but request at most one materialization per animation frame; final messages and Turn/Step closure publish immediately. See the [client Tool presentation decision](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md).
 
 ## Request inspection
 
@@ -46,7 +48,7 @@ Because the projection is log-ordered, the node array is seq-monotonic by constr
 
 ## Code Mode child-call tree
 
-Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Runtime's `ToolCallTree` privately maintains the parent-callId-to-children index: a `tool/code-dispatch-start` event lands as a `RunningToolCall`, and the matching `tool/code-dispatch` settlement replaces it in place with a `ToolResultNode` whose `callTime` comes from the paired start. When the start fell outside the replay window, the settlement appends directly with `callTime: null`; Runtime never fabricates a zero duration. Live mux frames and history replay share this fold and tree projection, and child calls never become independent roots in transcript `nodes`. A child update copies only its ancestor path to the owning root; unchanged siblings and other roots retain object identity. Wire or history edges that would introduce a cycle or exceed the fixed 256-call recursive-depth safety limit are consumed without mutating the tree, so the rest of the session remains renderable.
+Every `ToolCallBlock` recursively owns its children through `subCalls`, in start order. Chat's Tool Definition correlates root calls and results by call id, folds Code Dispatch start/settlement records into that root Context, and projects one keyed recursive tree; child calls never become independent Chat roots. When a start falls outside the loaded window, its settlement remains renderable with `callTime: null`. A child update copies only its ancestor path, so unchanged siblings retain object identity. Edges that introduce a cycle or exceed the fixed 256-call depth limit are consumed without mutating the tree. The separate Trajectory history fold still uses Runtime's `ToolCallTree` over the same nested data contract.
 
 ## Session title projection
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 9aea486fb1..72cd99ac76 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -34,11 +34,13 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 `ConversationSnapshot.queue` 是 Host 提供的 `agent.inbox.nextTurn` 权威瞬态快照；待处理的 next-step steering（中途引导）不进入此投影。每行携带其 `MessageId`、所有内容块均为文本时的完整可编辑文本，以及扁平化预览。Host 根据持久 `agent/inbox/spliced` 变更派生完整 `session/queue` 快照，并在重连时发送基线；面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知不用于重建该投影。`Session.updateQueue()` 经 Host 侧 `Inbox.splice()` 发送编辑／移除操作，客户端不做乐观变更，因此下一份 Host 快照是唯一可见的提交结果，claim 竞态则会返回 `queue-item-not-found`。
 
-## 面向人的 transcript（文本记录）
+## Conversation 组装
 
-`ConversationSnapshot.nodes` 是面向人的 transcript，不是模型 surface。`TranscriptAdapter` 按日志顺序投影原始窗口。每个 append 来源的 surface 事件（`isAppendSurfaceEvent`）落在它自己的日志位置上，每次落地的压缩（compaction）检查点还会贡献一个 `CompactionSummaryNode` 标记；适配器从不查询 surface 顺序。`SteeringHistory` 会重放该窗口中的持久 `agent/inbox/spliced` 记录：用户来源的消息从 `next-step` 被领取，并在与之匹配的 `user/message` 落地时，会投影为 `SteeringMessageNode`；从 `next-turn` 领取的消息仍是用户节点，非用户来源的 next-step 输入仍是上下文。`ConversationSnapshot.turnEnds` 把该窗口中的每个已完成轮次映射到其 `turn/end` seq；它独立于 transcript 保留轮次完成状态，使呈现层能够在启用操作前要求存在真实边界。于是一次落地的压缩会保留它在模型侧遮蔽掉的对话：标记报告模型从哪里开始看不见那段历史，而不是把它抹掉。仅模型可见的 replacement 副本不进入记录：被裁剪的 `tool/result` 和重新生成的 `assistant/message` 只为模型重写一个节点，不标记任何边界。检查点是携带压缩 seam 插件来源、且**替换**了一段 surface 范围的 `user/message`；一条 append 的插件来源 `user/message` 是注入上下文，不是压缩。每个上下文节点还携带一份包含生产者角色和名称的 `provenance` 视图：`contextProvenance()` 只读取持久来源，据此判定该行是 `inject`（注入）还是跨会话的 `recall`（召回），并用该来源已经记录的指令文件路径、被引用会话标题或插件 id 命名其生产者。客户端不保存任何插件 id 表，因此重命名或新挂载的生产者无需客户端发版即可保持可辨识，恢复的会话日志与外部日志的投影结果和实时会话完全一致；没有可读 kind 的来源则降级为无名注入。与之并列的 `contextForm()` 读取生产方声明的 `ContextForm`，这是相互独立的第二根轴：`kind` 说明上下文由谁产生，`form` 说明它是何种形态的信息，因此多个生产方可以共用一种形态。本 UI 版本不呈现的形态投影为 null，按 opaque 渲染。适配器的插件字面量通过对无 cordis 的 [`dsh-compact/checkpoint`](../../compact/compact/README.md) 叶子做仅类型导入，钉在 Service Definition 的声明上：在那里改名会让此处 `tsc` 失败；而对该包（package）做**值**导入会被客户端纯度门禁拒绝，包的**根**即便作为类型也无法到达（它会到达 `dsh-session` 的根，其 `Context` 合并会让 host 的 `sessions` 与本程序的冲突）。
+每个 `Session` 都把连续事件窗口交给 `ConversationNodeAssembler`。插件注册业务 Definition，把单个事件映射为稳定的 `{kind, id}`，在唯一 start 事件处创建 State，折叠有关联的 update，再为已注册的视图目标构造最终节点。Assembler 负责 Context 索引、只读前序 Context 查询，以及引用稳定的 Turn/Step Location 索引。实时 append 只对每个 Definition 求值一次，并且只更新命中的 Context；加载更早分页时保留已有 Context 与节点身份，只匹配新 prepend 的事件，并重放前序依赖或 Location 事实发生变化的 Context。完整替换仅用于 open、resync 和 gap repair。
 
-由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点引用的 `compact/summary` 事件；窗口切分把该事件留在窗口外时这些字段不可用，后续包含该事件的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
+`ui-conversation` 注册内建 Chat Definition 与 keyed Chat snapshot builder。append 来源的 user、assistant 和 Tool result 构成人类可见记录；仅供模型使用的 replacement 副本不进入 Chat，compaction 检查点除外，它会成为独立标记，并在更早分页补齐 summary 溯源后更新。持久 inbox splice Context 能把 next-step 用户消息判定为 steering，无须让 inbox 状态成为 Session 特例。上下文消息保留生产者 provenance 与 form。`ConversationSnapshot.nodes`、`partial` 和 `runningCalls` 是从同一批已物化 Chat 节点派生的兼容切片，供尚未迁移到 `ConversationSnapshot.chat` 的消费者使用；Session 不再运行第二套业务 fold。
+
+Chat builder 为每个 Session 保留一个 mutable keyed store。内容更新只通知受影响的 node key；结构变化才重建顺序和 Location 成员关系；prepend 只增加行，不替换既有 keyed value。每个 Assistant chunk 都会更新 Definition State，但最多每个 animation frame 请求一次物化；final message 与 Turn/Step 关闭会立即发布。参见 [Client Tool 展示所有权决策](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md)。
 
 ## 请求检查
 
@@ -46,7 +48,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 ## Code Mode 子调用树
 
-每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Runtime 的 `ToolCallTree` 私下维护 parent callId 到 child 的索引：`tool/code-dispatch-start` 事件落成 `RunningToolCall`，对应的 `tool/code-dispatch` 完结事件原位替换为 `ToolResultNode`，其 `callTime` 来自成对 start 事件；start 落在回放窗口之外时，完结事件会以 `callTime: null` 直接追加，绝不伪造零耗时。live mux 帧与历史回放共用这套 fold 和树投影；子调用不会成为 transcript `nodes` 中的独立 root。一次 child 变化只会复制从该 child 到所属 root 的祖先链，未变化的 sibling 和其他 root 保持对象引用稳定。会引入环，或使递归深度超过 256 个调用这一固定安全上限的协议或历史记录边会被视为已消费，但不会修改树，因此会话其余部分仍可渲染。
+每个 `ToolCallBlock` 都通过 `subCalls` 按启动顺序递归拥有自己的子调用。Chat 的 Tool Definition 按 call id 关联 root call 与 result，把 Code Dispatch 的 start/settlement 记录折叠进该 root Context，并投影为一棵 keyed 递归树；child call 不会成为独立 Chat root。start 落在已加载窗口之外时，其 settlement 仍以 `callTime: null` 渲染。一次 child 更新只复制其祖先链，因此未变化的 sibling 保持对象身份。会引入环或超过固定 256 层深度上限的边会被消费，但不会修改树。独立的 Trajectory history fold 仍通过 Runtime 的 `ToolCallTree` 生成同一种嵌套数据契约。
 
 ## Session 标题投影
 
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index b700c4c066..4f1ac11fcc 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -4,12 +4,14 @@
  * fiber-scoped loop teardown.
  */
 import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
 import type { ConnectionSinks } from '@deepseek-ai/dsh-client-connection/client'
 import { SESSION_SEARCH_RESULT_LIMIT } from '@deepseek-ai/dsh-host-apiproxy/api'
 import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import * as RuntimeClient from '../src/client/index.ts'
+import type { ConversationNodeDefinition } from '../src/client/contract/conversation.ts'
+import { Session } from '../src/client/sessions/session.ts'
 import type { SessionsService } from '../src/client/sessions/service.ts'
 import type { WorkspacesService } from '../src/client/workspaces/service.ts'
 import { FakeApiClient, ok } from './fake-api.ts'
@@ -112,6 +114,31 @@ describe('runtime client apply', () => {
     expect(bench.api.callsOf('session.create')).toHaveLength(1)
   })
 
+  it('wires registry changes into resident Sessions during the runtime apply pass', async () => {
+    const bench = await mount()
+    const sessions = bench.ctx.get('sessions') as SessionsService
+    bench.sinks?.onHostEnvelope?.({
+      rpcId: 'r-registry' as never,
+      payload: { type: 'host/session-added', blank: true, sessionId: 's-registry' } as never,
+    })
+    await flushMicrotasks()
+    expect(sessions.binding('s-registry' as never)).toBeDefined()
+    const rebuild = vi.spyOn(Session.prototype, 'rebuildConversationRegistry')
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'registry-probe',
+      match: () => null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+
+    bench.ctx.conversationEvents.register(definition)
+    await flushMicrotasks()
+
+    expect(rebuild).toHaveBeenCalledOnce()
+    rebuild.mockRestore()
+  })
+
   it('stops the stream loop when the plugin fiber unloads', async () => {
     const bench = await mount()
     const fiber = [...bench.ctx.registry.values()].find(f => f.name?.includes('client'))
diff --git a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts b/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
deleted file mode 100644
index 1f969c5121..0000000000
--- a/packages/client/runtime/tests/compact-checkpoint-pin.spec.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-/**
- * Behavioral half of the compaction-checkpoint drift trap.
- *
- * `TranscriptAdapter` pins its plugin literal to the Service Definition's declaration at
- * compile time through a type-only import of `dsh-compact/checkpoint`, so
- * renaming the Service Definition's plugin already fails `tsc`. This spec covers the same
- * drift from the other side — end to end through the adapter, driving it with a
- * checkpoint built from the canonical `COMPACT_CHECKPOINT_SOURCE` value and
- * checking the Service Definition's predicate agrees. Both values come from the
- * cordis-free checkpoint leaf, so the client test program never loads the host
- * package root or its `Context` merges.
- */
-
-import { COMPACT_CHECKPOINT_SOURCE, isCompactCheckpointSource } from '@deepseek-ai/dsh-compact/checkpoint'
-import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import { describe, expect, it } from 'vitest'
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts'
-
-/** A replacement user message stamped with the Service Definition's canonical source. */
-function canonicalCheckpoint(seq: number): SessionEvent {
-  return {
-    type: 'user/message',
-    seq,
-    time: 1_700_000_000_000 + seq,
-    surfaceOp: { op: 'replace', start: 0, end: 0 },
-    sourceEventSeqs: [0],
-    data: createUserMessage({
-      content: [{ type: 'text', text: '<context_checkpoint>model only</context_checkpoint>' }],
-      source: COMPACT_CHECKPOINT_SOURCE,
-    }),
-  } as unknown as SessionEvent
-}
-
-describe('compaction checkpoint recognition', () => {
-  it('recognizes a checkpoint carrying the seam-canonical source', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([canonicalCheckpoint(1)])
-    expect(adapter.nodes()).toEqual([{
-      kind: 'compaction', seq: 1, time: 1_700_000_000_001, summary: null,
-      summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
-    }])
-  })
-
-  it("agrees with the seam's own predicate on the source it recognizes", () => {
-    // Both sides answer the same question about the same value: if the Service Definition
-    // renames its plugin, this equality is what breaks.
-    const checkpoint = canonicalCheckpoint(1)
-    expect(checkpoint.type === 'user/message' && isCompactCheckpointSource(checkpoint.data.source)).toBe(true)
-    expect(COMPACT_CHECKPOINT_SOURCE).toEqual({ kind: 'plugin', plugin: 'compact' })
-  })
-})
diff --git a/packages/client/runtime/tests/conversation-assembler.spec.ts b/packages/client/runtime/tests/conversation-assembler.spec.ts
new file mode 100644
index 0000000000..6f4d8516dc
--- /dev/null
+++ b/packages/client/runtime/tests/conversation-assembler.spec.ts
@@ -0,0 +1,892 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { ConversationNodeAssembler } from '../src/client/sessions/conversation-assembler.ts'
+import type {
+  ConversationEventInput, ConversationMatch, ConversationNodeContext,
+  ConversationNodeDefinition, ConversationViewDefinition, ConversationViewNode,
+} from '../src/client/contract/conversation.ts'
+
+interface ScopeProbeStepData {
+  readonly value: number
+}
+
+interface ScopeProbeTurnData {
+  readonly valueSeenFromStep: number
+}
+
+declare module '../src/client/contract/conversation.ts' {
+  interface ConversationStepDataMap {
+    'scope-probe': ScopeProbeStepData
+  }
+
+  interface ConversationTurnDataMap {
+    'scope-probe': ScopeProbeTurnData
+  }
+}
+
+interface TestSnapshot {
+  readonly order: readonly string[]
+  readonly nodes: ReadonlyMap<string, ConversationViewNode>
+}
+
+class TestEventDefinitions {
+  constructor(
+    readonly definitions: readonly ConversationNodeDefinition[],
+    readonly fallback?: ConversationNodeDefinition,
+  ) {}
+
+  entries(): readonly ConversationNodeDefinition[] {
+    return this.definitions
+  }
+
+  fallbackEntry(): ConversationNodeDefinition | undefined {
+    return this.fallback
+  }
+}
+
+class TestViewDefinitions {
+  constructor(readonly definitions: readonly ConversationViewDefinition[]) {}
+
+  entries(): readonly ConversationViewDefinition[] {
+    return this.definitions
+  }
+}
+
+function testView(
+  apply = vi.fn(),
+): ConversationViewDefinition<ConversationViewNode, TestSnapshot> {
+  return {
+    target: 'chat',
+    create: () => {
+      let current: TestSnapshot = { order: [], nodes: new Map() }
+      return {
+        empty: current,
+        replace: ({ nodes }) => {
+          current = { order: nodes.map(node => node.key), nodes: new Map(nodes.map(node => [node.key, node])) }
+          return current
+        },
+        apply: ({ upserts }) => {
+          apply(upserts)
+          const nodes = new Map(current.nodes)
+          const order = [...current.order]
+          for (const node of upserts) {
+            if (!nodes.has(node.key)) order.push(node.key)
+            nodes.set(node.key, node)
+          }
+          current = { order, nodes }
+          return current
+        },
+      }
+    },
+  }
+}
+
+function at(seq: number, type: string, data: unknown): SessionEvent {
+  return { seq, time: 1_700_000_000_000 + seq, type, data } as SessionEvent
+}
+
+function input(event: SessionEvent): ConversationEventInput {
+  return { event, view: undefined }
+}
+
+function chatSnapshot(assembler: ConversationNodeAssembler): TestSnapshot | undefined {
+  return assembler.snapshot('chat') as TestSnapshot | undefined
+}
+
+function node(context: Parameters<ConversationNodeDefinition['buildViewNode']>[0], data: unknown): ConversationViewNode {
+  return {
+    key: context.key,
+    kind: context.kind,
+    id: context.id,
+    target: 'chat',
+    data,
+  }
+}
+
+describe('ConversationNodeAssembler', () => {
+  it('appends through an exact business-id Context without replaying unrelated Contexts', () => {
+    const starts = vi.fn((
+      _context: ConversationNodeContext<{ callSeq: number; results: number }>,
+      match: ConversationMatch,
+    ) => ({ callSeq: match.event.seq, results: 0 }))
+    const updates = vi.fn((context: { state: { callSeq: number; results: number } }) => ({
+      ...context.state,
+      results: context.state.results + 1,
+    }))
+    const definition: ConversationNodeDefinition<{ callSeq: number; results: number }> = {
+      kind: 'tool',
+      match: (event) => {
+        if (event.type === 'tool/call') return { id: String(event.data.callId), role: 'start' }
+        if (event.type === 'tool/result') return { id: String(event.data.message.source.callId), role: 'update' }
+        return null
+      },
+      start: starts,
+      update: updates,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'tool/call', { turn: 1, step: 1, callId: 'a', name: 'x', arguments: '{}' })),
+      input(at(2, 'tool/call', { turn: 1, step: 1, callId: 'b', name: 'x', arguments: '{}' })),
+    ], false)
+    assembler.flush()
+    starts.mockClear()
+
+    assembler.append(input(at(3, 'tool/result', {
+      turn: 1,
+      step: 1,
+      message: { source: { type: 'tool-result', callId: 'a' }, content: [], isError: false },
+    })))
+    assembler.flush()
+
+    expect(starts).not.toHaveBeenCalled()
+    expect(updates).toHaveBeenCalledOnce()
+    const snapshot = chatSnapshot(assembler)
+    expect([...snapshot?.nodes.values() ?? []].map(value => value.data)).toEqual([
+      { callSeq: 1, results: 1 },
+      { callSeq: 2, results: 0 },
+    ])
+  })
+
+  it('keeps one Match collection while a long Context appends without replay', () => {
+    const starts = vi.fn(() => 0)
+    const updates = vi.fn((context: ConversationNodeContext<number> & { readonly state: number }) => (
+      context.state + 1
+    ))
+    const matchCollections = new Set<readonly ConversationMatch[]>()
+    const definition: ConversationNodeDefinition<number> = {
+      kind: 'append-linear',
+      match: (event) => {
+        const type: string = event.type
+        if (type === 'linear/start') return { id: 'one', role: 'start' }
+        if (type === 'linear/update') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: (context) => {
+        matchCollections.add(context.matches)
+        return starts()
+      },
+      update: (context) => {
+        matchCollections.add(context.matches)
+        return updates(context)
+      },
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(1, 'linear/start', {}))], false)
+    starts.mockClear()
+
+    for (let seq = 2; seq <= 1_001; seq++) {
+      assembler.append(input(at(seq, 'linear/update', {})))
+    }
+    assembler.flush()
+
+    expect(starts).not.toHaveBeenCalled()
+    expect(updates).toHaveBeenCalledTimes(1_000)
+    expect(matchCollections.size).toBe(1)
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(1_000)
+  })
+
+  it('merges an older page and replays its affected Context once', () => {
+    const starts = vi.fn(() => 0)
+    const updates = vi.fn((context: ConversationNodeContext<number> & { readonly state: number }) => (
+      context.state + 1
+    ))
+    const definition: ConversationNodeDefinition<number> = {
+      kind: 'prepend-linear',
+      match: (event) => {
+        const type: string = event.type
+        if (type === 'linear/start') return { id: 'one', role: 'start' }
+        if (type === 'linear/update') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: starts,
+      update: updates,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    const current = Array.from({ length: 100 }, (_, index) => (
+      input(at(index + 102, 'linear/update', {}))
+    ))
+    assembler.replaceWindow(current, true)
+    assembler.flush()
+    expect(starts).not.toHaveBeenCalled()
+    expect(updates).not.toHaveBeenCalled()
+
+    const older = [
+      input(at(1, 'linear/start', {})),
+      ...Array.from({ length: 100 }, (_, index) => (
+        input(at(index + 2, 'linear/update', {}))
+      )),
+    ]
+    assembler.prepend(older, false)
+    assembler.flush()
+
+    expect(starts).toHaveBeenCalledOnce()
+    expect(updates).toHaveBeenCalledTimes(200)
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(200)
+  })
+
+  it('collects an update before its start and replays it once prepend supplies the start', () => {
+    const updates = vi.fn((context: { state: { settled: boolean } }) => ({ ...context.state, settled: true }))
+    const definition: ConversationNodeDefinition<{ settled: boolean }> = {
+      kind: 'tool',
+      match: (event) => {
+        if (event.type === 'tool/call') return { id: String(event.data.callId), role: 'start' }
+        if (event.type === 'tool/result') return { id: String(event.data.message.source.callId), role: 'update' }
+        return null
+      },
+      start: () => ({ settled: false }),
+      update: updates,
+      buildViewNode: context => node(context, context.state ?? { pendingStart: true }),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(10, 'tool/result', {
+      turn: 1,
+      step: 1,
+      message: { source: { type: 'tool-result', callId: 'a' }, content: [], isError: false },
+    }))], true)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
+      .toEqual({ pendingStart: true })
+
+    assembler.prepend([input(at(5, 'tool/call', {
+      turn: 1, step: 1, callId: 'a', name: 'x', arguments: '{}',
+    }))], false)
+    assembler.flush()
+
+    expect(updates).toHaveBeenCalledOnce()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
+      .toEqual({ settled: true })
+  })
+
+  it('rejects a Definition whose declared start follows an update in log order', () => {
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'invalid-lifecycle',
+      match: event => event.type === 'turn/end'
+        ? { id: 'one', role: 'start' }
+        : event.type === 'turn/start' ? { id: 'one', role: 'update' } : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+
+    expect(() => assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'turn/end', { turn: 1, reason: { kind: 'completed' } })),
+    ], false)).toThrow('received an update before its start Match')
+  })
+
+  it('replays a window-gap reader when prepend supplies a nearer predecessor', () => {
+    const source: ConversationNodeDefinition<number> = {
+      kind: 'source',
+      match: event => event.type === 'user/message'
+        ? { id: String(event.data.id), role: 'start' }
+        : null,
+      start: (_context, match) => Number((match.event.data as { value?: unknown }).value ?? 0),
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+    const consumerStart = vi.fn((
+      _context: Parameters<ConversationNodeDefinition<number>['start']>[0],
+      _match: Parameters<ConversationNodeDefinition<number>['start']>[1],
+      reader: Parameters<ConversationNodeDefinition<number>['start']>[2],
+    ) => reader.previous<number>('source')?.state ?? -1)
+    const consumer: ConversationNodeDefinition<number> = {
+      kind: 'consumer',
+      match: event => event.type === 'assistant/message'
+        ? { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        : null,
+      start: consumerStart,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([source, consumer]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(10, 'assistant/message', {
+      turn: 2, step: 1, message: { role: 'assistant', content: [] },
+    }))], true)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(-1)
+
+    assembler.prepend([input(at(5, 'user/message', {
+      id: 'm1', value: 7, content: [], source: { kind: 'user' },
+    }))], false)
+    assembler.flush()
+
+    expect(consumerStart).toHaveBeenCalledTimes(2)
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(7)
+  })
+
+  it('keeps the predecessor index ordered across prepend and append', () => {
+    const source: ConversationNodeDefinition<number> = {
+      kind: 'source',
+      match: event => event.type === 'user/message'
+        ? { id: String(event.data.id), role: 'start' }
+        : null,
+      start: (_context, match) => match.event.seq,
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+    const consumer: ConversationNodeDefinition<number> = {
+      kind: 'consumer',
+      match: event => event.type === 'assistant/message'
+        ? { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        : null,
+      start: (_context, _match, reader) => reader.previous<number>('source')?.state ?? -1,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([source, consumer]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(40, 'user/message', { id: 'm40', content: [], source: { kind: 'user' } })),
+      input(at(50, 'assistant/message', {
+        turn: 1, step: 1, message: { role: 'assistant', content: [] },
+      })),
+    ], true)
+    assembler.flush()
+
+    assembler.prepend([
+      input(at(10, 'user/message', { id: 'm10', content: [], source: { kind: 'user' } })),
+      input(at(30, 'user/message', { id: 'm30', content: [], source: { kind: 'user' } })),
+    ], false)
+    assembler.flush()
+    assembler.append(input(at(60, 'user/message', {
+      id: 'm60', content: [], source: { kind: 'user' },
+    })))
+    assembler.append(input(at(70, 'assistant/message', {
+      turn: 2, step: 1, message: { role: 'assistant', content: [] },
+    })))
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []].map(value => value.data))
+      .toEqual([40, 60])
+  })
+
+  it('replays a window-gap reader when an empty prepend closes the unknown prefix', () => {
+    const consumerStart = vi.fn((
+      _context: Parameters<ConversationNodeDefinition<number>['start']>[0],
+      _match: Parameters<ConversationNodeDefinition<number>['start']>[1],
+      reader: Parameters<ConversationNodeDefinition<number>['start']>[2],
+    ) => reader.previous<number>('source')?.state ?? -1)
+    const consumer: ConversationNodeDefinition<number> = {
+      kind: 'consumer',
+      match: event => event.type === 'assistant/message'
+        ? { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        : null,
+      start: consumerStart,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([consumer]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(10, 'assistant/message', {
+      turn: 2, step: 1, message: { role: 'assistant', content: [] },
+    }))], true)
+    assembler.flush()
+
+    expect(assembler.prepend([], false)).toBe('immediate')
+    assembler.flush()
+
+    expect(consumerStart).toHaveBeenCalledTimes(2)
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(-1)
+  })
+
+  it('replays direct dependents when an append revises their predecessor Context', () => {
+    const source: ConversationNodeDefinition<number> = {
+      kind: 'source',
+      match: (event) => {
+        if (event.type === 'user/message') return { id: 'one', role: 'start' }
+        if ((event.type as string) === 'source/update') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: () => 1,
+      update: (_context, match) => (match.event.data as unknown as { value: number }).value,
+      buildViewNode: () => null,
+    }
+    const consumerStart = vi.fn((
+      _context: Parameters<ConversationNodeDefinition<number>['start']>[0],
+      _match: Parameters<ConversationNodeDefinition<number>['start']>[1],
+      reader: Parameters<ConversationNodeDefinition<number>['start']>[2],
+    ) => reader.previous<number>('source')?.state ?? -1)
+    const consumer: ConversationNodeDefinition<number> = {
+      kind: 'consumer',
+      match: event => event.type === 'assistant/message'
+        ? { id: 'one', role: 'start' }
+        : null,
+      start: consumerStart,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([source, consumer]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'user/message', { id: 'source', content: [], source: { kind: 'user' } })),
+      input(at(2, 'assistant/message', { turn: 1, step: 1, message: { role: 'assistant', content: [] } })),
+    ], false)
+    assembler.flush()
+
+    expect(assembler.append(input(at(3, 'source/update', { value: 2 })))).toBe('immediate')
+    assembler.flush()
+
+    expect(consumerStart).toHaveBeenCalledTimes(2)
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(2)
+  })
+
+  it('replays Location-derived State and rebuilds only owned Nodes when a step closes', () => {
+    const apply = vi.fn()
+    const starts = vi.fn((
+      _context: Parameters<ConversationNodeDefinition<string>['start']>[0],
+      match: Parameters<ConversationNodeDefinition<string>['start']>[1],
+    ) => match.location.kind === 'step' ? match.location.step.status : 'missing')
+    const definition: ConversationNodeDefinition<string> = {
+      kind: 'step',
+      match: event => event.type === 'step/start'
+        ? { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        : null,
+      start: starts,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView(apply)]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'step/start', { turn: 1, step: 1 })),
+    ], false)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe('open')
+
+    assembler.append(input(at(3, 'step/end', { turn: 1, step: 1 })))
+    assembler.flush()
+
+    expect(starts).toHaveBeenCalledTimes(2)
+    expect(apply).toHaveBeenCalledOnce()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe('closed')
+  })
+
+  it('lets one Context publish Step and Turn data in phase order', () => {
+    interface State {
+      readonly turn: number
+      readonly step: number
+      readonly value: number
+    }
+
+    const definition: ConversationNodeDefinition<State> = {
+      kind: 'scope-probe',
+      match: (event) => {
+        if (event.type === 'step/start') {
+          return { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        }
+        if ((event.type as string) === 'scope-probe/update') {
+          return { id: '1:1', role: 'update' }
+        }
+        return null
+      },
+      start: (_context, match) => {
+        if (match.event.type !== 'step/start') throw new Error('scope probe requires step/start')
+        return { turn: match.event.data.turn, step: match.event.data.step, value: 1 }
+      },
+      update: (_context, match) => ({
+        turn: 1,
+        step: 1,
+        value: (match.event.data as unknown as { value: number }).value,
+      }),
+      buildLocationData: (context, scope) => {
+        const state = context.state
+        if (state === undefined) return null
+        if (scope === 'step') {
+          return {
+            kind: 'step',
+            turn: state.turn,
+            step: state.step,
+            key: 'scope-probe',
+            value: { value: state.value },
+          }
+        }
+        const location = context.start?.location
+        const stepValue = location?.kind === 'step'
+          ? location.step.data.get('scope-probe')?.value
+          : undefined
+        return {
+          kind: 'turn',
+          turn: state.turn,
+          key: 'scope-probe',
+          value: { valueSeenFromStep: stepValue ?? -1 },
+        }
+      },
+      buildViewNode: (context) => {
+        const location = context.start?.location
+        if (location?.kind !== 'step') return null
+        return node(context, {
+          step: location.step.data.get('scope-probe')?.value,
+          turn: location.turn.data.get('scope-probe')?.valueSeenFromStep,
+        })
+      },
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'step/start', { turn: 1, step: 1 })),
+    ], false)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
+      .toEqual({ step: 1, turn: 1 })
+
+    assembler.append(input(at(3, 'scope-probe/update', { turn: 1, step: 1, value: 2 })))
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
+      .toEqual({ step: 2, turn: 2 })
+  })
+
+  it('updates existing turn Locations when their Step membership changes', () => {
+    const apply = vi.fn()
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'turn-probe',
+      match: event => event.type === 'turn/start'
+        ? { id: String(event.data.turn), role: 'start' }
+        : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.start?.location.kind === 'turn'
+        ? context.start.location.turn.steps.length
+        : -1),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView(apply)]),
+    )
+    assembler.replaceWindow([input(at(1, 'turn/start', { turn: 1 }))], false)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(0)
+
+    assembler.append(input(at(2, 'step/start', { turn: 1, step: 1 })))
+    assembler.flush()
+
+    expect(apply).toHaveBeenCalledOnce()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(1)
+  })
+
+  it('publishes a changed timeline even when no business Definition claims the boundary', () => {
+    const apply = vi.fn()
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([]),
+      new TestViewDefinitions([testView(apply)]),
+    )
+    assembler.replaceWindow([], false)
+    assembler.flush()
+
+    assembler.append(input(at(1, 'turn/start', { turn: 1 })))
+    assembler.flush()
+
+    expect(apply).toHaveBeenCalledOnce()
+    expect(chatSnapshot(assembler)?.order).toEqual([])
+  })
+
+  it('clears the prior Step at a new Turn and honors explicit session ownership', () => {
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'location-probe',
+      match: (event) => {
+        if ((event.type as string) === 'command/run') {
+          return {
+            id: (event.data as unknown as { commandId: string }).commandId,
+            role: 'start',
+          }
+        }
+        if ((event.type as string) === 'compact/start') {
+          return {
+            id: (event.data as unknown as { compactionId: string }).compactionId,
+            role: 'start',
+          }
+        }
+        return null
+      },
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: (context) => {
+        const location = context.start?.location
+        const data = location?.kind === 'step'
+          ? `step:${location.turn.turn}:${location.step.step}`
+          : location?.kind === 'turn' ? `turn:${location.turn.turn}` : location?.kind
+        return node(context, data)
+      },
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'step/start', { turn: 1, step: 1 })),
+      input(at(3, 'turn/start', { turn: 2 })),
+      input(at(4, 'command/run', { commandId: 'command', name: 'x' })),
+      input(at(5, 'compact/start', { compactionId: 'compact', turn: null })),
+    ], false)
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []].map(value => value.data))
+      .toEqual(['turn:2', 'session'])
+  })
+
+  it('assigns turn boundaries to the Turn even when a Step remains open', () => {
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'turn-boundary-probe',
+      match: event => event.type === 'turn/end'
+        ? { id: String(event.data.turn), role: 'start' }
+        : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.start?.location.kind),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'turn/start', { turn: 1 })),
+      input(at(2, 'step/start', { turn: 1, step: 1 })),
+    ], false)
+    assembler.flush()
+
+    assembler.append(input(at(3, 'turn/end', { turn: 1, reason: { kind: 'aborted' } })))
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe('turn')
+  })
+
+  it('carries explicit coordinates across coordinate-free events in a partial window and live tail', () => {
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'location-probe',
+      match: event => (event.type as string) === 'tool/code-dispatch-start'
+        ? { id: String(event.seq), role: 'start' }
+        : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: (context) => {
+        const location = context.start?.location
+        return node(context, location?.kind === 'step'
+          ? `${location.turn.turn}:${location.step.step}`
+          : location?.kind)
+      },
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(10, 'tool/call', { turn: 2, step: 3, callId: 'root', name: 'x', arguments: '{}' })),
+      input(at(11, 'tool/code-dispatch-start', { rootCallId: 'root', subCallId: 'a' })),
+    ], true)
+    assembler.flush()
+
+    assembler.append(input(at(12, 'tool/code-dispatch-start', { rootCallId: 'root', subCallId: 'b' })))
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []].map(value => value.data))
+      .toEqual(['2:3', '2:3'])
+  })
+
+  it('treats loaded end boundaries as closed when their starts precede the window', () => {
+    const definition: ConversationNodeDefinition<null> = {
+      kind: 'location-probe',
+      match: event => event.type === 'tool/call'
+        ? { id: String(event.data.callId), role: 'start' }
+        : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: (context) => {
+        const location = context.start?.location
+        return node(context, location?.kind === 'step'
+          ? `${location.turn.status}:${location.step.status}`
+          : location?.kind)
+      },
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(10, 'tool/call', { turn: 2, step: 3, callId: 'root', name: 'x', arguments: '{}' })),
+      input(at(11, 'step/end', { turn: 2, step: 3 })),
+      input(at(12, 'turn/end', { turn: 2, reason: { kind: 'completed' } })),
+    ], true)
+    assembler.flush()
+
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data)
+      .toBe('closed:closed')
+  })
+
+  it('restarts State creation from undefined when Location changes replay a Context', () => {
+    const seen = vi.fn((context: Parameters<ConversationNodeDefinition<number>['start']>[0]) => {
+      expect(context.state).toBeUndefined()
+      return 1
+    })
+    const definition: ConversationNodeDefinition<number> = {
+      kind: 'replay-probe',
+      match: event => event.type === 'step/start'
+        ? { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
+        : null,
+      start: seen,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(1, 'step/start', { turn: 1, step: 1 }))], false)
+    assembler.flush()
+
+    assembler.append(input(at(2, 'step/end', { turn: 1, step: 1 })))
+    assembler.flush()
+
+    expect(seen).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not invoke the fallback when an ordinary non-rendering Definition claims an event', () => {
+    const fallbackStart = vi.fn(() => 'fallback')
+    const claimed: ConversationNodeDefinition<null> = {
+      kind: 'claimed',
+      match: event => (event.type as string) === 'command/run' ? { id: 'claimed', role: 'start' } : null,
+      start: () => null,
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+    const fallback: ConversationNodeDefinition<string> = {
+      kind: 'fallback',
+      match: event => ({ id: String(event.seq), role: 'start' }),
+      start: fallbackStart,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([claimed], fallback),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(1, 'command/run', { commandId: 'one', name: 'x' }))], false)
+    assembler.flush()
+
+    expect(fallbackStart).not.toHaveBeenCalled()
+    expect(chatSnapshot(assembler)?.order).toEqual([])
+  })
+
+  it('rejects withdrawing a previously materialized Node during an incremental update', () => {
+    const definition: ConversationNodeDefinition<boolean> = {
+      kind: 'toggle',
+      match: (event) => {
+        if ((event.type as string) === 'command/run') return { id: 'one', role: 'start' }
+        if ((event.type as string) === 'toggle/hide') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: () => true,
+      update: () => false,
+      buildViewNode: context => context.state === true ? node(context, true) : null,
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([input(at(1, 'command/run', { commandId: 'one', name: 'x' }))], false)
+    assembler.flush()
+    expect(chatSnapshot(assembler)?.order).toHaveLength(1)
+
+    assembler.append(input(at(2, 'toggle/hide', {})))
+    expect(() => assembler.flush()).toThrow(/withdrew materialized target "chat"/)
+
+    expect(chatSnapshot(assembler)?.order).toHaveLength(1)
+  })
+
+  it('fails loud when a Definition returns undefined State', () => {
+    const startUndefined: ConversationNodeDefinition = {
+      kind: 'undefined-start',
+      match: event => (event.type as string) === 'command/run' ? { id: 'one', role: 'start' } : null,
+      start: () => undefined,
+      update: context => context.state,
+      buildViewNode: () => null,
+    }
+    const startAssembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([startUndefined]),
+      new TestViewDefinitions([testView()]),
+    )
+    expect(() => startAssembler.replaceWindow([
+      input(at(1, 'command/run', { commandId: 'one', name: 'x' })),
+    ], false)).toThrow(/Definition "undefined-start" returned undefined from start/)
+
+    const updateUndefined: ConversationNodeDefinition<boolean> = {
+      kind: 'undefined-update',
+      match: (event) => {
+        if ((event.type as string) === 'command/run') return { id: 'one', role: 'start' }
+        if ((event.type as string) === 'command/done') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: () => true,
+      update: () => undefined as never,
+      buildViewNode: context => node(context, context.state),
+    }
+    const updateAssembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([updateUndefined]),
+      new TestViewDefinitions([testView()]),
+    )
+    updateAssembler.replaceWindow([
+      input(at(1, 'command/run', { commandId: 'one', name: 'x' })),
+    ], false)
+    expect(() => updateAssembler.append(
+      input(at(2, 'command/done', { commandId: 'one', kind: 'success' })),
+    )).toThrow(/Definition "undefined-update" returned undefined from update/)
+  })
+
+  it('rejects a duplicate start before mutating the existing Context', () => {
+    const definition: ConversationNodeDefinition<number> = {
+      kind: 'single-start',
+      match: event => (event.type as string) === 'command/run' ? { id: 'one', role: 'start' } : null,
+      start: (_context, match) => match.event.seq,
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([definition]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'command/run', { commandId: 'one', name: 'x' })),
+    ], false)
+    assembler.flush()
+
+    expect(() => assembler.append(
+      input(at(2, 'command/run', { commandId: 'two', name: 'x' })),
+    )).toThrow(/received more than one start Match/)
+    assembler.flush()
+    expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(1)
+  })
+})
diff --git a/packages/client/runtime/tests/conversation-registry.spec.ts b/packages/client/runtime/tests/conversation-registry.spec.ts
new file mode 100644
index 0000000000..19cbdf17f9
--- /dev/null
+++ b/packages/client/runtime/tests/conversation-registry.spec.ts
@@ -0,0 +1,126 @@
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { ConversationEventRegistry } from '../src/client/conversation/event-registry.ts'
+import { ConversationViewRegistry } from '../src/client/conversation/view-registry.ts'
+import type {
+  ConversationNodeDefinition, ConversationViewDefinition, ConversationViewNode,
+} from '../src/client/contract/conversation.ts'
+import { Session } from '../src/client/sessions/session.ts'
+import { SessionsService } from '../src/client/sessions/service.ts'
+import { FakeApiClient, ok } from './fake-api.ts'
+
+function eventDefinition(kind: string): ConversationNodeDefinition<null> {
+  return {
+    kind,
+    match: () => null,
+    start: () => null,
+    update: context => context.state,
+    buildViewNode: () => null,
+  }
+}
+
+function viewDefinition(target: string): ConversationViewDefinition<ConversationViewNode, null> {
+  return {
+    target,
+    create: () => ({
+      empty: null,
+      replace: () => null,
+      apply: () => null,
+    }),
+  }
+}
+
+async function bootRegistries(): Promise<{
+  ctx: Context
+  events: ConversationEventRegistry
+  views: ConversationViewRegistry
+}> {
+  const ctx = new Context()
+  await ctx.plugin(ConversationEventRegistry).await()
+  await ctx.plugin(ConversationViewRegistry).await()
+  const events = ctx.get('conversationEvents') as ConversationEventRegistry
+  const views = ctx.get('conversationViews') as ConversationViewRegistry
+  return { ctx, events, views }
+}
+
+describe('Conversation registries', () => {
+  it('rejects duplicate Event Definitions and disposes an ordinary registration once', async () => {
+    const { events } = await bootRegistries()
+    const definition = eventDefinition('message')
+    const dispose = events.register(definition)
+
+    expect(events.entries()).toEqual([definition])
+    expect(() => events.register(eventDefinition('message'))).toThrow(/already registered/)
+
+    dispose()
+    dispose()
+    expect(events.entries()).toEqual([])
+  })
+
+  it('rejects a duplicate fallback and clears it through its idempotent disposer', async () => {
+    const { events } = await bootRegistries()
+    const fallback = eventDefinition('unknown')
+    const dispose = events.registerFallback(fallback)
+
+    expect(events.fallbackEntry()).toBe(fallback)
+    expect(() => events.registerFallback(eventDefinition('other'))).toThrow(/already registered/)
+
+    dispose()
+    dispose()
+    expect(events.fallbackEntry()).toBeUndefined()
+  })
+
+  it('rejects duplicate view targets and disposes a view registration once', async () => {
+    const { views } = await bootRegistries()
+    const definition = viewDefinition('chat')
+    const dispose = views.register(definition)
+
+    expect(views.entries()).toEqual([definition])
+    expect(() => views.register(viewDefinition('chat'))).toThrow(/already registered/)
+
+    dispose()
+    dispose()
+    expect(views.entries()).toEqual([])
+  })
+
+  it('removes Event, fallback, and view contributions with their caller fiber', async () => {
+    const { ctx, events, views } = await bootRegistries()
+    const feature = ctx.inject(['conversationEvents', 'conversationViews'], (featureCtx) => {
+      featureCtx.conversationEvents.register(eventDefinition('message'))
+      featureCtx.conversationEvents.registerFallback(eventDefinition('unknown'))
+      featureCtx.conversationViews.register(viewDefinition('chat'))
+    })
+    await feature.await()
+
+    expect(events.entries()).toHaveLength(1)
+    expect(events.fallbackEntry()).toBeDefined()
+    expect(views.entries()).toHaveLength(1)
+
+    await feature.dispose()
+    expect(events.entries()).toEqual([])
+    expect(events.fallbackEntry()).toBeUndefined()
+    expect(views.entries()).toEqual([])
+  })
+
+  it('coalesces registry changes into one rebuild of every resident Session', async () => {
+    const { ctx, events, views } = await bootRegistries()
+    const api = new FakeApiClient()
+    const sessionId = 'resident' as SessionId
+    api.onList = () => Promise.resolve(ok({
+      items: [{ sessionId, updatedAt: 1, running: false, blank: true }],
+    }) as never)
+    const sessions = new SessionsService(ctx, api)
+    await sessions.refresh()
+    await Promise.resolve()
+    sessions.scope(sessionId)
+    const rebuild = vi.spyOn(Session.prototype, 'rebuildConversationRegistry')
+
+    events.register(eventDefinition('message'))
+    views.register(viewDefinition('chat'))
+    await Promise.resolve()
+
+    expect(rebuild).toHaveBeenCalledOnce()
+    rebuild.mockRestore()
+  })
+})
diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts
index de72d5b351..299e16785d 100644
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -54,12 +54,12 @@ export const ev = {
   codeDispatchStart: (seq: number, parentCallId: string, n: number, name: string, args: unknown): SessionEvent =>
     at(seq, {
       type: 'tool/code-dispatch-start',
-      data: { parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args },
+      data: { rootCallId: parentCallId, parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args },
     }),
   codeDispatch: (seq: number, parentCallId: string, n: number, name: string, args: unknown, body: string, isError = false): SessionEvent =>
     at(seq, {
       type: 'tool/code-dispatch',
-      data: { parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args, isError, content: text(body) },
+      data: { rootCallId: parentCallId, parentCallId, subCallId: `${parentCallId}:code:${n}`, name, arguments: args, isError, content: text(body) },
     }),
   stepEnd: (seq: number, turn: number, step = 0): SessionEvent =>
     at(seq, { type: 'step/end', data: { turn, step } }),
diff --git a/packages/client/runtime/tests/queue-store.spec.ts b/packages/client/runtime/tests/queue-store.spec.ts
index 55e0929c30..1b6b721d25 100644
--- a/packages/client/runtime/tests/queue-store.spec.ts
+++ b/packages/client/runtime/tests/queue-store.spec.ts
@@ -158,7 +158,6 @@ describe('queue snapshot intake', () => {
       type: 'session/event', sessionId: SID, event: durable,
     })
     expect(session.getSnapshot().queue.map(item => item.id)).toEqual(['s-second'])
-    expect(session.getSnapshot().nodes.filter(node => node.kind === 'user')).toHaveLength(1)
 
     session.handleMuxEnvelope(rid('env-reused-id'), queueFrame([
       { id: 's-later', body: '', placement: 'steering', message },
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index 834f37d434..def97002f0 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -8,15 +8,17 @@
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 import { Session } from '../src/client/sessions/session.ts'
+import type {
+  ChatConversationViewNode, ChatLocationNodeIndex, ChatNodeStore, ChatSnapshot,
+  ConversationEventInput, ConversationNode, ConversationNodeDefinition,
+  ConversationRuntime, ConversationSnapshot, ConversationTimelineSnapshot,
+  ConversationViewDefinition,
+} from '../src/client/index.ts'
 import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
 import { entries, ev, plainTurn } from './event-script.ts'
 
-const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
-  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
-
 const SID = 'fk-s1' as SessionId
 const PARENT = 'fk-parent' as SessionId
 
@@ -24,8 +26,142 @@ afterEach(() => {
   vi.unstubAllGlobals()
 })
 
+const EMPTY: readonly never[] = []
+
+interface TestEventState extends ConversationEventInput {}
+
+class TestNodeStore implements ChatNodeStore {
+  private readonly nodes = new Map<string, ChatConversationViewNode>()
+  private cache: readonly ChatConversationViewNode[] = EMPTY
+
+  get(key: string): ChatConversationViewNode | undefined {
+    return this.nodes.get(key)
+  }
+
+  values(): readonly ChatConversationViewNode[] {
+    return this.cache
+  }
+
+  replace(nodes: readonly ChatConversationViewNode[]): void {
+    this.nodes.clear()
+    for (const node of nodes) this.nodes.set(node.key, node)
+    this.cache = [...this.nodes.values()]
+  }
+
+  upsert(nodes: readonly ChatConversationViewNode[]): void {
+    if (nodes.length === 0) return
+    for (const node of nodes) this.nodes.set(node.key, node)
+    this.cache = [...this.nodes.values()]
+  }
+}
+
+const TEST_LOCATIONS: ChatLocationNodeIndex = {
+  getTurn: () => EMPTY,
+  getStep: () => EMPTY,
+}
+
+function testLegacy(
+  nodes: readonly ChatConversationViewNode[],
+  timeline: ConversationTimelineSnapshot,
+): ChatSnapshot['legacy'] {
+  const legacyNodes = nodes.flatMap((node): ConversationNode[] => {
+    const event = (node.data as TestEventState).event
+    if (event.type === 'user/message') return [{ kind: 'user', seq: event.seq } as ConversationNode]
+    if (event.type === 'assistant/message') return [{ kind: 'assistant', seq: event.seq } as ConversationNode]
+    return []
+  })
+  const turnTimings = new Map<number, { startTime: number; endTime?: number }>()
+  const turnEnds = new Map<number, number>()
+  for (const turn of timeline.turns.values()) {
+    if (turn.start !== undefined) {
+      turnTimings.set(turn.turn, turn.end === undefined
+        ? { startTime: turn.start.time }
+        : { startTime: turn.start.time, endTime: turn.end.time })
+    }
+    if (turn.end !== undefined) turnEnds.set(turn.turn, turn.end.seq)
+  }
+  return { nodes: legacyNodes, turnTimings, turnEnds, partial: null, runningCalls: EMPTY }
+}
+
+function testViewDefinition(): ConversationViewDefinition<ChatConversationViewNode, ChatSnapshot> {
+  return {
+    target: 'chat',
+    create: () => {
+      const store = new TestNodeStore()
+      let current: ChatSnapshot = {
+        order: EMPTY,
+        nodes: store,
+        locations: TEST_LOCATIONS,
+        timeline: { turnOrder: EMPTY, turns: new Map() },
+        legacy: testLegacy(EMPTY, { turnOrder: EMPTY, turns: new Map() }),
+      }
+      const build = (timeline: ConversationTimelineSnapshot): ChatSnapshot => {
+        const nodes = [...store.values()].sort((left, right) => left.anchorSeq - right.anchorSeq)
+        current = {
+          order: nodes.map(node => node.key),
+          nodes: store,
+          locations: TEST_LOCATIONS,
+          timeline,
+          legacy: testLegacy(nodes, timeline),
+        }
+        return current
+      }
+      return {
+        empty: current,
+        replace: ({ nodes, timeline }) => {
+          store.replace(nodes)
+          return build(timeline)
+        },
+        apply: ({ upserts, timeline }) => {
+          store.upsert(upserts)
+          return build(timeline)
+        },
+      }
+    },
+  }
+}
+
+const TEST_EVENT_DEFINITION: ConversationNodeDefinition<TestEventState> = {
+  kind: 'runtime-test-event',
+  match: event => ({ id: String(event.seq), role: 'start' }),
+  start: (_context, match) => ({ event: match.event, view: match.view }),
+  update: context => context.state,
+  publication: match => match.event.type === 'assistant/chunk' ? 'animation-frame' : 'immediate',
+  buildViewNode: (context, target) => {
+    if (target !== 'chat' || context.state === undefined || context.start === undefined) return null
+    return {
+      key: context.key,
+      kind: 'runtime-test-event',
+      id: context.id,
+      target: 'chat',
+      anchorSeq: context.start.event.seq,
+      location: context.start.location,
+      visibility: 'visible',
+      data: context.state,
+    }
+  },
+}
+
+const TEST_CONVERSATION: ConversationRuntime = {
+  events: {
+    entries: () => [TEST_EVENT_DEFINITION],
+    fallbackEntry: () => undefined,
+  } as unknown as ConversationRuntime['events'],
+  views: {
+    entries: () => [testViewDefinition()],
+  } as unknown as ConversationRuntime['views'],
+}
+
 function makeSession(api = new FakeApiClient()): { api: FakeApiClient; session: Session } {
-  return { api, session: new Session(SID, api) }
+  return { api, session: new Session(SID, api, { conversation: TEST_CONVERSATION }) }
+}
+
+function chatEvents(snapshot: ConversationSnapshot): readonly TestEventState[] {
+  return snapshot.chat.order.map(key => snapshot.chat.nodes.get(key)?.data as TestEventState)
+}
+
+function chatSeqs(snapshot: ConversationSnapshot): number[] {
+  return chatEvents(snapshot).map(item => item.event.seq)
 }
 
 function histResponse(events: SessionEvent[], hasMore = false) {
@@ -34,6 +170,14 @@ function histResponse(events: SessionEvent[], hasMore = false) {
 }
 
 describe('open', () => {
+  it('keeps a bare Session blank until an authoritative lifecycle signal arrives', () => {
+    const { session } = makeSession()
+    expect(session.getSnapshot()).toMatchObject({ blank: true, composerPhase: 'blank' })
+
+    session.handleRunning(true)
+    expect(session.getSnapshot()).toMatchObject({ blank: false, composerPhase: 'active' })
+  })
+
   it('installs the tail page: cold → loading → open with window and nodes in place', async () => {
     const { api, session } = makeSession()
     const page = plainTurn(10, 3, '问', '答')
@@ -115,74 +259,28 @@ describe('live event path', () => {
     expect(session.getSnapshot().nodes).toEqual(before.nodes)
   })
 
-  it('materializes a command node from live lifecycle frames and reproduces it from a history window', async () => {
-    // Live path: run mints an executing node, done settles it in the flow.
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.commandRun(6, 'cmd-live', 'plan'))
-    let command = session.getSnapshot().nodes.at(-1)
-    expect(command).toMatchObject({ kind: 'command', name: 'plan', args: '', outcome: null })
-    feed(ev.commandDone(7, 'cmd-live', 'success', '已进入 plan mode'))
-    command = session.getSnapshot().nodes.at(-1)
-    expect(command).toMatchObject({ kind: 'command', seq: 6, outcome: { kind: 'success', text: '已进入 plan mode' } })
-
-    // Replay path (refresh): the same pair inside the history window folds identically.
-    const replayed = await opened([
-      ...plainTurn(0, 0, 'a', 'b'),
-      ev.commandRun(6, 'cmd-live', 'plan'),
-      ev.commandDone(7, 'cmd-live', 'success', '已进入 plan mode'),
-    ])
-    expect(replayed.session.getSnapshot().nodes.at(-1)).toMatchObject({
-      kind: 'command', seq: 6, name: 'plan', outcome: { kind: 'success', text: '已进入 plan mode' },
-    })
-  })
-
-  it('command lifecycle rows alone keep the composer blank (hero survives a /permission or /plan switch)', async () => {
-    // A fresh session whose only window content is a command pair (plus the
-    // knob events a /permission switch appends — not surface-eligible, so
-    // they never become nodes) stays phase 'blank': selecting a preset from
-    // the hero must not enter the conversation view.
+  it('keeps the authoritative host blank bit across unrelated log events', async () => {
     const { session } = await opened([])
+    session.handleBlank(true)
     expect(session.getSnapshot().composerPhase).toBe('blank')
     const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
     feed(ev.commandRun(0, 'cmd-perm', 'permission', ' danger-full-access'))
     feed(ev.commandDone(1, 'cmd-perm', 'success', 'preset danger-full-access'))
     const snapshot = session.getSnapshot()
-    expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'command', name: 'permission' })
+    expect(chatSeqs(snapshot)).toEqual([0, 1])
     expect(snapshot.composerPhase).toBe('blank')
   })
 
-  it('accumulates chunks into partial, then finalize swaps partial out as the node lands', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.user(7, '流式问'))
-    feed(ev.chunkStart(8, 1))
-    feed(ev.chunkText(9, 1, '半截'))
-    let snapshot = session.getSnapshot()
-    expect(snapshot.partial).toMatchObject({ turn: 1, blocks: [{ kind: 'text', text: '半截' }] })
-    feed(ev.chunkText(10, 1, '回复'))
-    expect(session.getSnapshot().partial?.blocks).toEqual([{ kind: 'text', text: '半截回复' }])
-    feed(ev.assistant(11, 1, '半截回复'))
-    feed(ev.turnEnd(12, 1))
-    snapshot = session.getSnapshot()
-    expect(snapshot.partial).toBeNull()
-    const last = snapshot.nodes.at(-1)
-    expect(last).toMatchObject({ kind: 'assistant', blocks: [{ kind: 'text', text: '半截回复' }] })
-    expect((last as { interrupted?: true }).interrupted).toBeUndefined()
-  })
-
-  it('publishes cumulative chunks once per frame and lets finalization supersede the pending frame', async () => {
+  it('publishes animation-frame Definitions once per frame and lets an immediate event supersede the pending frame', async () => {
     const frames: FrameRequestCallback[] = []
     vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
       frames.push(callback)
       return frames.length
     })
     const { session } = await opened()
-    const published: Array<string | null> = []
+    const published: number[][] = []
     session.subscribe(() => {
-      const block = session.getSnapshot().partial?.blocks[0]
-      published.push(block?.kind === 'text' ? block.text : null)
+      published.push(chatSeqs(session.getSnapshot()))
     })
     const feed = (event: SessionEvent) => {
       session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
@@ -195,356 +293,46 @@ describe('live event path', () => {
     expect(frames).toHaveLength(1)
 
     frames.shift()!(0)
-    expect(published).toEqual(['累计'])
+    expect(published).toEqual([[0, 1, 2, 3, 4, 5, 6, 7, 8]])
 
     feed(ev.chunkText(9, 1, '完成'))
     feed(ev.assistant(10, 1, '累计完成'))
     await Promise.resolve()
-    expect(published).toEqual(['累计', null])
+    expect(published).toEqual([
+      [0, 1, 2, 3, 4, 5, 6, 7, 8],
+      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    ])
 
     frames.shift()!(0)
-    expect(published).toEqual(['累计', null])
+    expect(published).toHaveLength(2)
   })
 
-  it('retracts the failed-attempt partial and starts the retry on new chunk evidence', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    const retryTurn = [
-      ev.turnStart(6, 1),
-      ev.user(7, '请重试'),
-      ev.stepStart(8, 1),
-      ev.chunkStart(9, 1),
-      ev.chunkText(10, 1, '不完整回复'),
-      ev.retry(11, 1, 0, 1, 2, 450, '连接被重置'),
-      ev.chunkStart(12, 1),
-      ev.assistant(13, 1, '完整回复'),
-      ev.stepEnd(14, 1),
-      ev.turnEnd(15, 1),
-    ]
-    for (const event of retryTurn.slice(0, 6)) feed(event)
-
-    let snapshot = session.getSnapshot()
-    expect(snapshot.partial).toBeNull()
-    expect(snapshot.nodes.at(-1)).toMatchObject({
-      kind: 'model-retry',
-      retryState: 'scheduled',
-      turn: 1,
-      step: 0,
-      provider: 'fake',
-      mode: 'normal',
-      policyKey: 'fake-normal',
-      retry: 1,
-      maxRetries: 2,
-      delayMs: 450,
-      failure: { code: 'TRANSPORT', message: '连接被重置' },
-    })
-    expect(JSON.stringify(snapshot.nodes)).not.toContain('不完整回复')
-
-    for (const event of retryTurn.slice(6)) feed(event)
-    snapshot = session.getSnapshot()
-    expect(snapshot.nodes.slice(-2).map(node => node.kind)).toEqual(['model-retry', 'assistant'])
-    expect(snapshot.nodes.some(node => node.kind === 'turn-error')).toBe(false)
-    expect(snapshot.nodes.at(-2)).toMatchObject({ kind: 'model-retry', retryState: 'started' })
-    expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'assistant', blocks: [{ kind: 'text', text: '完整回复' }] })
-    const retryStart = retryTurn.find(event => event.type === 'turn/start')
-    if (retryStart?.type !== 'turn/start') throw new Error('test fixture must include the retried turn start')
-    const retryEnd = retryTurn.find(event =>
-      event.type === 'turn/end' && event.data.turn === retryStart.data.turn)
-    if (retryEnd?.type !== 'turn/end') throw new Error('test fixture must complete the retry turn')
-    expect(snapshot.turnTimings.get(retryStart.data.turn)).toEqual({
-      startTime: retryStart.time,
-      endTime: retryEnd.time,
-    })
-
-    const replay = makeSession()
-    replay.api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ...retryTurn])
-    await replay.session.open()
-    expect(replay.session.getSnapshot().nodes).toEqual(snapshot.nodes)
-    expect(replay.session.getSnapshot().turnTimings).toEqual(snapshot.turnTimings)
-    expect(replay.session.getSnapshot().partial).toBeNull()
-  })
-
-  it('projects unretried terminal failures at turn/end and reproduces them from history', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => {
-      session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
+  it('publishes a timeline-only boundary even when no Definition claims the event', async () => {
+    const api = new FakeApiClient()
+    api.onHistory = () => histResponse([])
+    const conversation: ConversationRuntime = {
+      events: {
+        entries: () => [],
+        fallbackEntry: () => undefined,
+      } as unknown as ConversationRuntime['events'],
+      views: {
+        entries: () => [testViewDefinition()],
+      } as unknown as ConversationRuntime['views'],
     }
-    const failedTurns = [
-      ev.turnStart(6, 1),
-      ev.user(7, '鉴权失败'),
-      ev.stepStart(8, 1),
-      at(9, {
-        type: 'turn/end',
-        data: { turn: 1, reason: { kind: 'error', error: {
-          code: 'AUTH',
-          message: 'Authentication Fails, Your api key: sk-preview-secret is invalid',
-        },
-        },
-        },
-      }),
-      ev.turnStart(10, 2),
-      ev.user(11, '内部失败'),
-      ev.stepStart(12, 2, 1),
-      at(13, {
-        type: 'turn/end',
-        data: { turn: 2, reason: { kind: 'error', error: { message: 'plugin exploded', code: 'UNKNOWN' } } },
-      }),
-    ]
-    for (const event of failedTurns) feed(event)
+    const session = new Session(SID, api, { conversation })
+    await session.open()
+    const snapshots: ConversationSnapshot[] = []
+    session.subscribe(() => { snapshots.push(session.getSnapshot()) })
 
-    const errors = session.getSnapshot().nodes.filter(node => node.kind === 'turn-error')
-    expect(errors).toMatchObject([
-      { seq: 9, turn: 1, step: 0, code: 'AUTH', message: 'API key is invalid' },
-      // Every failed turn carries a structured failure; unstructured errors
-      // flatten to the UNKNOWN code.
-      { seq: 13, turn: 2, step: 1, code: 'UNKNOWN', message: 'plugin exploded' },
-    ])
-
-    const replay = makeSession()
-    replay.api.onHistory = () => histResponse([...plainTurn(0, 0, 'a', 'b'), ...failedTurns])
-    await replay.session.open()
-    expect(replay.session.getSnapshot().nodes).toEqual(session.getSnapshot().nodes)
-  })
-
-  it('rejects retry payloads outside the producer contract without retracting the current partial', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.chunkStart(7, 1))
-    feed(ev.chunkText(8, 1, '仍在生成'))
-    const valid = {
-      turn: 1, step: 0,
-      provider: 'fake', mode: 'normal', policyKey: 'fake-normal',
-      retry: 1, maxRetries: 2, delayMs: 500,
-      failure: { code: 'TRANSPORT', message: 'temporary failure' },
-    }
-    const invalid = [
-      { ...valid, turn: Number.MAX_SAFE_INTEGER + 1 },
-      { ...valid, step: Number.MAX_SAFE_INTEGER + 1 },
-      { ...valid, provider: '' },
-      { ...valid, policyKey: '' },
-      { ...valid, retry: Number.MAX_SAFE_INTEGER + 1 },
-      { ...valid, maxRetries: Number.MAX_SAFE_INTEGER + 1 },
-      { ...valid, delayMs: -1 },
-      { ...valid, delayMs: Number.POSITIVE_INFINITY },
-      { ...valid, delayMs: MAX_TIMER_DELAY_MS + 1 },
-      { ...valid, failure: { ...valid.failure, message: '' } },
-      { ...valid, failure: { ...valid.failure, code: '' } },
-      { ...valid, failure: { ...valid.failure, status: '429' } },
-      { ...valid, failure: { ...valid.failure, status: 99 } },
-      { ...valid, failure: { ...valid.failure, status: 429.5 } },
-      { ...valid, failure: { ...valid.failure, status: 600 } },
-      { ...valid, failure: { ...valid.failure, providerRetryAfterMs: 0 } },
-      { ...valid, failure: { ...valid.failure, providerRetryAfterMs: Number.POSITIVE_INFINITY } },
-      { ...valid, failure: { ...valid.failure, requestId: 1 } },
-      { ...valid, failure: { ...valid.failure, requestId: '' } },
-    ]
-    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
-    try {
-      for (const [index, data] of invalid.entries()) {
-        feed(at(9 + index, { type: 'llm/retry', data }))
-      }
-      expect(session.getSnapshot().partial?.blocks).toEqual([{ kind: 'text', text: '仍在生成' }])
-      expect(session.getSnapshot().nodes.filter(node => node.kind === 'model-retry')).toEqual([])
-      expect(errorSpy).toHaveBeenCalledTimes(invalid.length)
-      expect(errorSpy).toHaveBeenCalledWith('[web-runtime] ignored malformed llm/retry event at seq 9')
-    } finally {
-      errorSpy.mockRestore()
-    }
-  })
-
-  it('accepts complete retry payloads at the producer field boundaries', async () => {
-    const { session } = await opened()
-    session.handleMuxEnvelope('r' as never, {
+    session.handleMuxEnvelope('timeline' as never, {
       type: 'session/event',
       sessionId: SID,
-      event: at(6, {
-        type: 'llm/retry',
-        data: {
-          turn: Number.MAX_SAFE_INTEGER,
-          step: Number.MAX_SAFE_INTEGER,
-          provider: 'fake',
-          mode: 'normal',
-          policyKey: 'fake-normal',
-          retry: Number.MAX_SAFE_INTEGER,
-          maxRetries: Number.MAX_SAFE_INTEGER,
-          delayMs: MAX_TIMER_DELAY_MS,
-          failure: {
-            code: 'RATE_LIMIT',
-            message: 'provider busy',
-            status: 599,
-            providerRetryAfterMs: Number.MIN_VALUE,
-            requestId: 'req-1',
-          },
-        },
-      }),
+      event: ev.turnStart(0, 1),
     })
-    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-      kind: 'model-retry',
-      retryState: 'scheduled',
-      retry: Number.MAX_SAFE_INTEGER,
-      delayMs: MAX_TIMER_DELAY_MS,
-      failure: { status: 599, providerRetryAfterMs: Number.MIN_VALUE, requestId: 'req-1' },
-    })
-  })
+    await Promise.resolve()
 
-  it('projects always-mode retries and rejects mode-specific maximums or unknown modes', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
-    try {
-      feed(at(6, {
-        type: 'llm/retry',
-        data: {
-          turn: 1, step: 0,
-          provider: 'fake', mode: 'always', policyKey: 'fake-always',
-          retry: 3, delayMs: 500,
-          failure: { code: 'TRANSPORT', message: 'retry forever' },
-        },
-      }))
-      expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-        kind: 'model-retry',
-        retryState: 'scheduled',
-        mode: 'always',
-        retry: 3,
-      })
-
-      feed(at(7, {
-        type: 'llm/retry',
-        data: {
-          turn: 2, step: 0,
-          provider: 'fake', mode: 'always', policyKey: 'fake-always',
-          retry: 4, maxRetries: 4, delayMs: 500,
-          failure: { code: 'TRANSPORT', message: 'unexpected maximum' },
-        },
-      }))
-      feed(at(8, {
-        type: 'llm/retry',
-        data: {
-          turn: 2, step: 0,
-          provider: 'fake', mode: 'sometimes', policyKey: 'fake-unknown',
-          retry: 4, delayMs: 500,
-          failure: { code: 'TRANSPORT', message: 'unknown mode' },
-        },
-      }))
-      expect(session.getSnapshot().nodes.filter(node => node.kind === 'model-retry')).toHaveLength(1)
-      expect(errorSpy).toHaveBeenCalledTimes(2)
-    } finally {
-      errorSpy.mockRestore()
-    }
-  })
-
-  it.each(['aborted', 'disposed'] as const)(
-    'marks a scheduled retry as cancelled when its failed turn receives the %s cause',
-    async (reason) => {
-      const { session } = await opened()
-      const feed = (event: SessionEvent) => {
-        session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
-      }
-      feed(ev.turnStart(6, 1))
-      feed(ev.retry(7, 1))
-      expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-        kind: 'model-retry',
-        retryState: 'scheduled',
-      })
-      feed(ev.turnEnd(8, 1, reason))
-      expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-        kind: 'model-retry',
-        retryState: 'cancelled',
-      })
-    },
-  )
-
-  it('marks a scheduled retry as started when its failed turn ends with an error', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => {
-      session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
-    }
-    feed(ev.turnStart(6, 1))
-    feed(ev.retry(7, 1))
-    feed(at(8, {
-      type: 'turn/end',
-      data: { turn: 1, reason: { kind: 'error', error: { message: 'retry failed', code: 'UNKNOWN' } } },
-    }))
-
-    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-      kind: 'model-retry',
-      retryState: 'started',
-    })
-  })
-
-  it('freezes an unfinalized partial into an interrupted node on turn/end (cancel path)', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.user(7, '要被打断的'))
-    feed(ev.chunkStart(8, 1))
-    feed(ev.chunkText(9, 1, '说到一半'))
-    feed(ev.turnEnd(10, 1, 'aborted')) // no assistant/message ever arrives
-    const snapshot = session.getSnapshot()
-    expect(snapshot.partial).toBeNull()
-    expect(snapshot.turnEnds.get(1)).toBe(10)
-    const frozen = snapshot.nodes.at(-1)
-    expect(frozen).toMatchObject({ kind: 'assistant', interrupted: true, blocks: [{ kind: 'text', text: '说到一半' }] })
-    // Ordered inside the flow: after the user message (seq 7), before any later turn.
-    expect((frozen as { seq: number }).seq).toBeGreaterThan(7)
-  })
-
-  it('tracks tool calls in runningCalls and converts orphans to interrupted tool-result cards on turn/end', async () => {
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'c1', 'echo', '{"a":1}'))
-    expect(session.getSnapshot().runningCalls).toMatchObject([{ callId: 'c1', name: 'echo' }])
-    feed(ev.toolResult(8, 1, 'c1', 'ECHO'))
-    expect(session.getSnapshot().runningCalls).toEqual([])
-    // Second call never resolves: turn/end freezes it as an error card.
-    feed(ev.toolCall(9, 1, 'c2', 'slow_tool', '{}'))
-    feed(ev.turnEnd(10, 1, 'aborted'))
-    const snapshot = session.getSnapshot()
-    expect(snapshot.runningCalls).toEqual([])
-    expect(snapshot.nodes.at(-1)).toMatchObject({
-      kind: 'tool-result', callId: 'c2', isError: true, error: { code: 'interrupted' },
-    })
-  })
-
-  it('keeps compacted history and adds one marker, live and on replay alike', async () => {
-    // A landed compaction must not erase conversation the reader already saw:
-    // the shadowed messages stay at their own log positions and the checkpoint
-    // contributes one marker after them.
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.compactSummary(6, '压缩摘要', 1, 3))
-    feed(ev.compactCheckpoint(7, 6, 1, 3))
-    const live = session.getSnapshot().nodes
-    expect(live.map(n => [n.kind, n.seq])).toEqual([['user', 1], ['assistant', 3], ['compaction', 7]])
-    expect(live.at(-1)).toMatchObject({ kind: 'compaction', summary: '压缩摘要' })
-
-    const replayed = await opened([
-      ...plainTurn(0, 0, 'a', 'b'),
-      ev.compactSummary(6, '压缩摘要', 1, 3),
-      ev.compactCheckpoint(7, 6, 1, 3),
-    ])
-    expect(replayed.session.getSnapshot().nodes).toEqual(live)
-  })
-
-  it('merges an interrupted frozen node by seq into the log-ordered transcript', async () => {
-    // The transcript array is seq-monotonic, so the frozen node's fractional
-    // seq lands it exactly where it happened — including after a compaction
-    // checkpoint whose own seq is higher than the range it shadowed.
-    const { session } = await opened()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.compactSummary(6, '压缩摘要', 1, 3))
-    feed(ev.compactCheckpoint(7, 6, 1, 3))
-    feed(ev.turnStart(8, 1))
-    feed(ev.user(9, '压缩后的提问'))
-    feed(ev.chunkStart(10, 1))
-    feed(ev.chunkText(11, 1, '说到一半'))
-    feed(ev.turnEnd(12, 1, 'aborted'))
-    expect(session.getSnapshot().nodes.map(n => n.kind)).toEqual([
-      'user', 'assistant', 'compaction', 'user', 'assistant',
-    ])
-    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({ interrupted: true })
+    expect(snapshots).toHaveLength(1)
+    expect(snapshots[0]?.chat.timeline.turns.get(1)?.status).toBe('open')
   })
 
   it('repairs a seq gap by repulling the tail page instead of appending a hole', async () => {
@@ -578,11 +366,7 @@ describe('paging', () => {
     expect(snapshot.nodes.map(n => n.seq)).toEqual([1, 3, 7, 9])
   })
 
-  it('renders a page whose checkpoint shadows seqs below the window head, logging nothing', async () => {
-    // Pagination no longer spends maxMessages quota on replacement copies, so a
-    // page can carry a compaction checkpoint whose surfaceOp.start lies outside
-    // the window. The old surface fold rejected that range and degraded with a
-    // console error; the log-ordered transcript has no range to resolve.
+  it('installs a page without interpreting business replacement metadata', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse([
       ev.compactSummary(80, '窗外范围的摘要', 3, 40),
@@ -594,8 +378,7 @@ describe('paging', () => {
       await session.open()
       const snapshot = session.getSnapshot()
       expect(snapshot.openState).toBe('open')
-      expect(snapshot.nodes.map(n => [n.kind, n.seq])).toEqual([['compaction', 81], ['user', 82]])
-      expect(snapshot.nodes[0]).toMatchObject({ summary: '窗外范围的摘要' })
+      expect(chatSeqs(snapshot)).toEqual([80, 81, 82])
       expect(errorSpy).not.toHaveBeenCalled()
     } finally {
       errorSpy.mockRestore()
@@ -712,6 +495,7 @@ describe('prompt and cancel errors', () => {
 
   it('sends content through session.prompt; composerPhase steps blank → engaging synchronously at send entry', async () => {
     const { api, session } = makeSession()
+    session.handleBlank(true)
     // The blank → engaging edge fires before the RPC settles: the first-send
     // flow reads the phase on the session area's first frame to keep the
     // guidance hero from flashing back in.
@@ -730,6 +514,7 @@ describe('prompt and cancel errors', () => {
 
   it('business failure lands in promptError with op=send; the phase stays engaging (retry, no hero bounce)', async () => {
     const { api, session } = makeSession()
+    session.handleBlank(true)
     api.onPrompt = () => Promise.resolve(err({ code: 'agent-busy', message: 'busy', details: { reason: 'x' } }))
     const result = await session.prompt([{ type: 'text', text: '失败的' }], 'queue')
     expect(result.ok).toBe(false)
@@ -969,33 +754,6 @@ describe('remaining branches', () => {
     }
   })
 
-  it('freezes only content-bearing partials; a content-free partial is dropped outright', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.chunkStart(7, 1)) // empty text block only, no delta
-    feed(ev.turnEnd(8, 1, 'aborted'))
-    const snapshot = session.getSnapshot()
-    expect(snapshot.partial).toBeNull()
-    expect(snapshot.nodes.filter(n => n.kind === 'assistant' && (n as { interrupted?: true }).interrupted)).toEqual([])
-  })
-
-  it('turn/end sweeps only same-turn open calls; other turns keep running', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'turn1-call', 'echo', '{}'))
-    feed(ev.toolCall(8, 2, 'turn2-call', 'echo', '{}')) // stray call attributed to a later turn
-    feed(ev.turnEnd(9, 1, 'aborted'))
-    const snapshot = session.getSnapshot()
-    expect(snapshot.runningCalls.map(c => c.callId)).toEqual(['turn2-call'])
-    expect(snapshot.nodes.at(-1)).toMatchObject({ kind: 'tool-result', callId: 'turn1-call', isError: true })
-  })
-
   it('doOpen transport throw of a stale generation is swallowed (generation guard in catch)', async () => {
     const { api, session } = makeSession()
     const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
@@ -1065,28 +823,13 @@ describe('remaining branches', () => {
     expect(session.getSnapshot().nodes.map(n => n.seq)).toEqual([7, 9])
   })
 
-  it('successful cancel leaves no promptError; tool/result for an unknown callId is a no-op', async () => {
+  it('successful cancel leaves no promptError', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
     await session.open()
     const result = await session.cancel()
     expect(result.ok).toBe(true)
     expect(session.getSnapshot().promptError).toBeNull()
-    const callsBefore = session.getSnapshot().runningCalls
-    session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.toolResult(6, 0, 'never-called', 'x') })
-    expect(session.getSnapshot().runningCalls).toBe(callsBefore) // callsRev untouched: same reference
-  })
-
-  it('freezes a tool-call-only partial (visible through the non-text arm)', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(at(7, { type: 'assistant/chunk', data: { turn: 1, step: 0, chunk: { type: 'tool-call-delta', index: 0, id: 'c1', name: 'echo', argumentsDelta: '{' } } }))
-    feed(ev.turnEnd(8, 1, 'aborted'))
-    const frozen = session.getSnapshot().nodes.at(-1)
-    expect(frozen).toMatchObject({ kind: 'assistant', interrupted: true, blocks: [{ kind: 'tool-call', callId: 'c1' }] })
   })
 
   it('dispose is a reserved no-op on resident instances', () => {
@@ -1094,7 +837,7 @@ describe('remaining branches', () => {
     expect(() => { session.dispose() }).not.toThrow()
   })
 
-  it('carries mux-frame views into runningCalls and tool-result nodes, and history-entry views through open', async () => {
+  it('carries history-entry and mux-frame views into the business-neutral Event input', async () => {
     const { api, session } = makeSession()
     const callView = { for: 'call', view: { card: 'generic', title: '历史卡' } }
     api.onHistory = () => Promise.resolve(ok({
@@ -1107,21 +850,23 @@ describe('remaining branches', () => {
       modelSelection: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
     }))
     await session.open()
-    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-      kind: 'tool-result', callView: { title: '历史卡' }, resultView: { title: '历史果' },
-    })
-    // Live path: the frame's view slot reaches runningCalls, then the result node.
+    expect(chatEvents(session.getSnapshot()).slice(-2).map(item => item.view)).toEqual([
+      callView,
+      { for: 'result', view: { card: 'generic', title: '历史果' } },
+    ])
     session.handleMuxEnvelope('rv1' as never, {
       type: 'session/event', sessionId: SID, event: ev.toolCall(8, 2, 'l1', 'write', '{}'),
       view: { for: 'call', view: { card: 'generic', title: '直播卡' } },
     } as never)
-    expect(session.getSnapshot().runningCalls).toMatchObject([{ callId: 'l1', callView: { title: '直播卡' } }])
+    expect(chatEvents(session.getSnapshot()).at(-1)?.view).toEqual({
+      for: 'call', view: { card: 'generic', title: '直播卡' },
+    })
     session.handleMuxEnvelope('rv2' as never, {
       type: 'session/event', sessionId: SID, event: ev.toolResult(9, 2, 'l1', 'ok'),
       view: { for: 'result', view: { card: 'generic', title: '直播果' } },
     } as never)
-    expect(session.getSnapshot().nodes.at(-1)).toMatchObject({
-      kind: 'tool-result', callView: { title: '直播卡' }, resultView: { title: '直播果' },
+    expect(chatEvents(session.getSnapshot()).at(-1)?.view).toEqual({
+      for: 'result', view: { card: 'generic', title: '直播果' },
     })
   })
 })
@@ -1177,163 +922,27 @@ describe('resync', () => {
 
 })
 
-describe('nested run_code sub-dispatches', () => {
-  const subCallsOf = (session: Session, callId: string) => {
-    const snapshot = session.getSnapshot()
-    const running = snapshot.runningCalls.find(call => call.callId === callId)
-    if (running !== undefined) return running.subCalls
-    for (const node of snapshot.nodes) {
-      if (node.kind === 'tool-result' && node.callId === callId) return node.subCalls
-    }
-    return undefined
-  }
-
-  it('a start event lands as a running-shaped sub-call and its settle replaces it in place', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
-    feed(ev.codeDispatchStart(8, 'p1', 1, 'bash', { command: 'sleep' }))
-    feed(ev.codeDispatchStart(9, 'p1', 2, 'read', { path: 'a.txt' }))
-    const live = subCallsOf(session, 'p1')
-    expect(live).toHaveLength(2)
-    // Running shape (no 'kind'): the exact RunningToolCall form native rows use.
-    expect(live?.[0]).toMatchObject({ callId: 'p1:code:1', name: 'bash', argsRaw: '{"command":"sleep"}' })
-    expect(live?.[0] !== undefined && 'kind' in live[0]).toBe(false)
-    // Settle out of order (parallel run): #2 first — replaces in place, keeping start order.
-    feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'a.txt' }, 'alpha'))
-    const mixed = subCallsOf(session, 'p1')
-    expect(mixed?.map(sub => 'kind' in sub)).toEqual([false, true])
-    expect(mixed?.[1]).toMatchObject({ callId: 'p1:code:2', content: [{ type: 'text', text: 'alpha' }] })
-    // The settle carries the paired start's time as callTime (duration source).
-    feed(ev.codeDispatch(11, 'p1', 1, 'bash', { command: 'sleep' }, 'done'))
-    const settled = subCallsOf(session, 'p1')
-    expect(settled?.map(sub => 'kind' in sub)).toEqual([true, true])
-    expect(settled?.[0]).toMatchObject({ callId: 'p1:code:1', callTime: 1_700_000_000_008 })
-  })
-
-  it('indexes live tool/code-dispatch events under their parent as native-shaped result nodes', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'))
-    feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls', description: '列目录' }, 'demo.txt'))
-    feed(ev.codeDispatch(9, 'p1', 2, 'read', { path: 'a.txt' }, 'Error: ENOENT', true))
-    const subs = subCallsOf(session, 'p1')
-    expect(subs).toHaveLength(2)
-    expect(subs?.[0]).toMatchObject({
-      kind: 'tool-result', callId: 'p1:code:1',
-      call: { name: 'bash', argsRaw: '{"command":"ls","description":"列目录"}' },
-      // The settle event carries no start time: callTime stays null (never a
-      // fabricated zero-duration).
-      callTime: null,
-      isError: false, content: [{ type: 'text', text: 'demo.txt' }],
-    })
-    expect(subs?.[1]).toMatchObject({ callId: 'p1:code:2', isError: true })
-    // No paired start in the window: duration is UNKNOWN (null), never a
-    // fabricated zero-duration span.
-    expect(subs?.[0]).toMatchObject({ callTime: null })
-    // Sub-dispatches never join the surface flow.
-    expect(session.getSnapshot().nodes.some(n => n.kind === 'tool-result' && n.callId.includes(':code:'))).toBe(false)
-  })
-
-  it('rebuilds the same nested tree from a history window (replay parity)', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse([
-      ...plainTurn(0, 0, '问', '答'),
-      ev.turnStart(6, 1),
-      ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"return 1","description":"跑一个程序"}'),
-      ev.codeDispatchStart(8, 'p1', 1, 'run_code', { code: 'return tools.read({ path: "a.txt" })' }),
-      ev.codeDispatch(9, 'p1:code:1', 1, 'read', { path: 'a.txt' }, 'alpha'),
-      ev.codeDispatch(10, 'p1', 1, 'run_code', { code: 'return tools.read({ path: "a.txt" })' }, 'alpha'),
-      ev.toolResult(11, 1, 'p1', '{"done":true}'),
-      ev.turnEnd(12, 1),
-    ])
-    await session.open()
-    const subs = subCallsOf(session, 'p1')
-    expect(subs).toHaveLength(1)
-    expect(subs?.[0]).toMatchObject({
-      callId: 'p1:code:1',
-      call: { name: 'run_code' },
-      subCalls: [{ callId: 'p1:code:1:code:1', call: { name: 'read' } }],
-    })
-  })
-
-  it('keeps an unaffected root reference and path-copies it on a new child', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"d"}'))
-    feed(ev.codeDispatch(8, 'p1', 1, 'bash', { command: 'ls' }, 'x'))
-    const before = session.getSnapshot()
-    const beforeRoot = before.runningCalls.find(call => call.callId === 'p1')!
-    feed(ev.chunkStart(9, 1))
-    feed(ev.chunkText(10, 1, '流式'))
-    const after = session.getSnapshot()
-    const afterRoot = after.runningCalls.find(call => call.callId === 'p1')!
-    expect(afterRoot).toBe(beforeRoot)
-    feed(ev.codeDispatch(11, 'p1', 2, 'read', { path: 'a' }, 'y'))
-    const changedRoot = session.getSnapshot().runningCalls.find(call => call.callId === 'p1')!
-    expect(changedRoot).not.toBe(afterRoot)
-    expect(changedRoot.subCalls[0]).toBe(afterRoot.subCalls[0])
-    expect(changedRoot.subCalls).toHaveLength(2)
-  })
-
-  it('path-copies only the owning branch when a nested child changes', async () => {
-    const { api, session } = makeSession()
-    api.onHistory = () => histResponse(plainTurn(0, 0, '树', '结构'))
-    await session.open()
-    const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }
-    feed(ev.turnStart(6, 1))
-    feed(ev.toolCall(7, 1, 'p1', 'run_code', '{"code":"1","description":"first"}'))
-    feed(ev.toolCall(8, 1, 'p2', 'run_code', '{"code":"2","description":"second"}'))
-    feed(ev.codeDispatch(9, 'p1', 1, 'run_code', { code: 'nested' }, 'child'))
-    feed(ev.codeDispatch(10, 'p1', 2, 'read', { path: 'sibling' }, 'sibling'))
-    feed(ev.codeDispatch(11, 'p2', 1, 'bash', { command: 'pwd' }, 'root two'))
-    const before = session.getSnapshot()
-    const beforeFirst = before.runningCalls.find(call => call.callId === 'p1')!
-    const beforeSecond = before.runningCalls.find(call => call.callId === 'p2')!
-    const beforeChild = beforeFirst.subCalls[0]!
-    const beforeSibling = beforeFirst.subCalls[1]!
-
-    feed(ev.codeDispatch(12, 'p1:code:1', 1, 'read', { path: 'nested' }, 'leaf'))
-    const after = session.getSnapshot()
-    const afterFirst = after.runningCalls.find(call => call.callId === 'p1')!
-    const afterSecond = after.runningCalls.find(call => call.callId === 'p2')!
-
-    expect(afterFirst).not.toBe(beforeFirst)
-    expect(afterSecond).toBe(beforeSecond)
-    expect(afterFirst.subCalls[0]).not.toBe(beforeChild)
-    expect(afterFirst.subCalls[1]).toBe(beforeSibling)
-    expect(afterFirst.subCalls[0]?.subCalls).toMatchObject([
-      { callId: 'p1:code:1:code:1', call: { name: 'read' } },
-    ])
-  })
-})
-
 describe('reference stability (the memo contract)', () => {
   it('keeps unchanged node references across an append and swaps the snapshot object', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(plainTurn(0, 0, '稳', '定'))
     await session.open()
     const before = session.getSnapshot()
+    const firstKey = before.chat.order[0]!
+    const secondKey = before.chat.order[1]!
+    const first = before.chat.nodes.get(firstKey)
+    const second = before.chat.nodes.get(secondKey)
     session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.user(6, '追加') })
     const after = session.getSnapshot()
     expect(after).not.toBe(before) // top-level swap on change
-    expect(after.nodes[0]).toBe(before.nodes[0]) // untouched nodes keep identity
-    expect(after.nodes[1]).toBe(before.nodes[1])
-    expect(after.nodes).toHaveLength(3)
+    expect(after.chat.nodes.get(firstKey)).toBe(first)
+    expect(after.chat.nodes.get(secondKey)).toBe(second)
+    expect(after.chat.order).toHaveLength(7)
     // No change → same snapshot reference.
     expect(session.getSnapshot()).toBe(after)
   })
 
-  it('keeps untouched substructure arrays identical across unrelated changes (revision counters)', async () => {
+  it('keeps unrelated Session arrays and settled Chat Nodes stable across Event updates', async () => {
     const { api, session } = makeSession()
     api.onHistory = () => histResponse(plainTurn(0, 0, '底', '座'))
     await session.open()
@@ -1343,20 +952,19 @@ describe('reference stability (the memo contract)', () => {
     feed(ev.toolCall(8, 1, 'c1', 'echo', '{}'))
     session.handleMuxEnvelope('ra' as never, { type: 'approval/requested', sessionId: SID, approvalId: 'ap1' as never, toolName: 'rm' })
     const before = session.getSnapshot()
-    // A chunk storm touches partial/nodes only: unrelated projections keep identity.
+    const settledKey = before.chat.order[0]!
+    const settledNode = before.chat.nodes.get(settledKey)
     feed(ev.chunkStart(9, 1))
     feed(ev.chunkText(10, 1, '与工具无关的流式'))
     const after = session.getSnapshot()
     expect(after).not.toBe(before)
     expect(after.runningCalls).toBe(before.runningCalls)
     expect(after.pending).toBe(before.pending)
-    expect(after.turnTimings).toBe(before.turnTimings)
-    expect(after.turnEnds).toBe(before.turnEnds)
-    // And a mutation on the tracked domain swaps that array.
+    expect(after.chat.nodes.get(settledKey)).toBe(settledNode)
     feed(ev.toolResult(11, 1, 'c1', 'ECHO'))
     const resolved = session.getSnapshot()
-    expect(resolved.runningCalls).not.toBe(after.runningCalls)
     expect(resolved.pending).toBe(after.pending)
+    expect(resolved.chat.nodes.get(settledKey)).toBe(settledNode)
     feed(ev.assistant(12, 1, '完成'))
     expect(session.getSnapshot()).not.toBe(resolved)
   })
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
deleted file mode 100644
index b161046f84..0000000000
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ /dev/null
@@ -1,567 +0,0 @@
-/**
- * TranscriptAdapter over the raw append-only window: log-ordered projection of
- * append-origin events, one marker per landed compaction, replacement copies
- * hidden, command-lifecycle folding, node/array identity, call pairing, and
- * host-provided wire views.
- */
-
-import { createUserMessage, CallId, createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
-import { describe, expect, it } from 'vitest'
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts'
-import { ev, plainTurn } from './event-script.ts'
-
-const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
-  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
-
-/** A `compact/summary` event (log-only, no surfaceOp). */
-function compactSummary(seq: number, summary: unknown = [{ type: 'text', text: '# 摘要\n\n保留事实' }]): SessionEvent {
-  return at(seq, {
-    type: 'compact/summary',
-    data: {
-      summary,
-      shadowedRange: { start: 1, end: 3 },
-      shadowedSeqs: [1, 3],
-      shadowedTokenCount: 100,
-      provider: 'fake',
-      model: 'compact-1',
-    },
-  })
-}
-
-/** The replacement user message a compaction backend lands (the checkpoint). */
-function checkpoint(
-  seq: number,
-  summarySeq: number,
-  { start = 1, end = 3, sourceEventSeqs = [summarySeq, start, end] }: {
-    start?: number
-    end?: number
-    sourceEventSeqs?: number[]
-  } = {},
-): SessionEvent {
-  return at(seq, {
-    type: 'user/message',
-    surfaceOp: { op: 'replace', start, end },
-    sourceEventSeqs,
-    data: createUserMessage({
-      content: [{ type: 'text', text: '<context_checkpoint>model only</context_checkpoint>' }],
-      source: { kind: 'plugin', plugin: 'compact' },
-    }),
-  })
-}
-
-describe('TranscriptAdapter', () => {
-  it('projects a window starting past seq 0 at its own log positions', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(100, 5, '偏移问', '偏移答'))
-    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 101], ['assistant', 103]])
-  })
-
-  it('appends incrementally keeping old node references (materialize-once identity)', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b'))
-    const first = adapter.nodes()
-    adapter.append(ev.user(6, '追加'))
-    const second = adapter.nodes()
-    expect(second).toHaveLength(3)
-    expect(second[0]).toBe(first[0])
-    expect(second[1]).toBe(first[1])
-    expect(second).not.toBe(first) // a real change swaps the array
-  })
-
-  it('keeps the array reference across a chunk storm and swaps it when a node lands', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b'))
-    const settled = adapter.nodes()
-    adapter.append(ev.chunkStart(6, 1))
-    expect(adapter.nodes()).toBe(settled)
-    adapter.append(ev.chunkText(7, 1, '流式'))
-    expect(adapter.nodes()).toBe(settled)
-    adapter.append(ev.assistant(8, 1, '流式完成'))
-    const finalized = adapter.nodes()
-    expect(finalized).not.toBe(settled)
-    expect(finalized.at(-1)).toMatchObject({ kind: 'assistant', seq: 8 })
-  })
-
-  it('materializes every append-origin variant with field mapping', () => {
-    const adapter = new TranscriptAdapter()
-    const steering = createUserMessage({
-      content: [{ type: 'text', text: '插话' }],
-      source: { kind: 'user' },
-    })
-    adapter.reset([
-      ev.user(0, '用户'),
-      ev.assistant(1, 0, '助手'),
-      at(2, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [steering],
-      } }),
-      at(3, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(4, { type: 'user/message', surfaceOp: 'append', data: steering }),
-      at(5, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' },
-      }) }),
-      ev.toolCall(6, 0, 'c1', 'echo', '{"x":1}'),
-      ev.toolResult(7, 0, 'c1', '结果'),
-    ])
-    const nodes = adapter.nodes()
-    expect(nodes.map(n => n.kind)).toEqual(['user', 'assistant', 'steering', 'context', 'tool-result'])
-    expect(nodes.find(n => n.kind === 'steering')).toMatchObject({ messageId: steering.id })
-    expect(nodes.find(n => n.kind === 'tool-result')).toMatchObject({
-      callId: 'c1', call: { name: 'echo', argsRaw: '{"x":1}' }, isError: false,
-    })
-  })
-
-  it('identifies steering on the live append path', () => {
-    const adapter = new TranscriptAdapter()
-    const steering = createUserMessage({
-      content: [{ type: 'text', text: 'live steer' }],
-      source: { kind: 'user' },
-    })
-    adapter.reset([])
-    adapter.append(at(0, { type: 'agent/inbox/spliced', data: {
-      target: 'next-step', start: 0, inserted: [steering],
-    } }))
-    adapter.append(at(1, { type: 'agent/inbox/spliced', data: {
-      target: 'next-step', start: 0, removedCount: 1, inserted: [],
-    } }))
-    adapter.append(at(2, { type: 'user/message', surfaceOp: 'append', data: steering }))
-    expect(adapter.nodes()).toMatchObject([{ kind: 'steering', messageId: steering.id }])
-  })
-
-  it('does not mark queued, canceled, or non-user next-step messages as steering', () => {
-    const adapter = new TranscriptAdapter()
-    const queued = createUserMessage({ content: [{ type: 'text', text: 'queued' }], source: { kind: 'user' } })
-    const canceled = createUserMessage({ content: [{ type: 'text', text: 'canceled' }], source: { kind: 'user' } })
-    const context = createUserMessage({
-      content: [{ type: 'text', text: 'context' }],
-      source: { kind: 'plugin', plugin: 'test' },
-    })
-    adapter.reset([
-      at(0, { type: 'agent/inbox/spliced', data: {
-        target: 'next-turn', start: 0, inserted: [queued],
-      } }),
-      at(1, { type: 'agent/inbox/spliced', data: {
-        target: 'next-turn', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(2, { type: 'user/message', surfaceOp: 'append', data: queued }),
-      at(3, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [canceled],
-      } }),
-      at(4, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [], outcome: 'canceled',
-      } }),
-      at(5, { type: 'user/message', surfaceOp: 'append', data: canceled }),
-      at(6, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [context],
-      } }),
-      at(7, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(8, { type: 'user/message', surfaceOp: 'append', data: context }),
-    ])
-    expect(adapter.nodes().map(node => node.kind)).toEqual(['user', 'user', 'context'])
-  })
-
-  it('materializes a skill-invocation injection as a named instructions context', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '/hidden-demo check the fixture' }],
-        source: { kind: 'user' },
-      }) }),
-      at(1, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '<skill_content name="hidden-demo">body</skill_content>' }],
-        source: { kind: 'skill-invocation', name: 'hidden-demo', form: 'instructions' } as never,
-      }) }),
-    ])
-    const nodes = adapter.nodes()
-    // The gesture stays a user bubble; the injected body folds to a context
-    // row named after the skill, presented as instructions.
-    expect(nodes.map(node => node.kind)).toEqual(['user', 'context'])
-    expect(nodes[1]).toMatchObject({
-      provenance: { role: 'inject', label: 'hidden-demo' },
-      form: 'instructions',
-    })
-  })
-
-  it('skips events core does not call surface-eligible, marker or not', () => {
-    // The transcript is the append-origin surface, so log-only events (a chunk,
-    // a turn boundary, a `compact/*` record) and a future type core
-    // has not admitted contribute no node.
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      ev.turnStart(0, 1),
-      at(1, { type: 'notice/message', surfaceOp: 'append', data: { note: 1 } }),
-      compactSummary(2),
-      ev.user(3, '唯一的一条'),
-      ev.turnEnd(4, 1),
-    ])
-    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 3]])
-  })
-
-  describe('compaction markers', () => {
-    it('keeps the original messages and full tool output, hiding replacement copies', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '原始问题'),
-        ev.assistant(1, 0, '原始回答'),
-        ev.toolCall(4, 0, 'c1', 'echo', '{}'),
-        ev.toolResult(5, 0, 'c1', '完整工具输出'),
-        // A pruned tool/result copy: rewrites one node for the model, marks nothing.
-        at(6, { type: 'tool/result', surfaceOp: { op: 'replace', start: 5, end: 5 }, sourceEventSeqs: [5], data: {
-          turn: 0, step: 0,
-          message: createToolResultMessage({ callId: CallId('c1'), content: [{ type: 'text', text: '已裁剪' }], isError: false }),
-        } }),
-        compactSummary(7),
-        checkpoint(8, 7, { start: 1, end: 5, sourceEventSeqs: [7, 1, 5] }),
-        // A regenerated assistant/message: also a silent model-only rewrite.
-        at(9, { type: 'assistant/message', surfaceOp: { op: 'replace', start: 8, end: 8 }, sourceEventSeqs: [8], data: {
-          turn: 0, step: 0,
-          message: createMessage({
-            role: 'assistant',
-            content: [{ type: 'text', text: '通用 replacement 副本' }],
-            source: { kind: 'model', ...{ provider: 'x', model: 'copy' } },
-          }),
-        } }),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([
-        ['user', 0], ['assistant', 1], ['tool-result', 5], ['compaction', 8],
-      ])
-      expect(nodes[2]).toMatchObject({ kind: 'tool-result', content: [{ type: 'text', text: '完整工具输出' }] })
-      expect(nodes[3]).toMatchObject({ kind: 'compaction', summary: '# 摘要\n\n保留事实' })
-    })
-
-    it('adds one marker per landed compaction, in log order', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, 'a'),
-        compactSummary(1, [{ type: 'text', text: 'first' }]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-        ev.user(3, 'b'),
-        compactSummary(4, [{ type: 'text', text: 'second' }]),
-        checkpoint(5, 4, { start: 2, end: 3, sourceEventSeqs: [4, 2, 3] }),
-      ])
-      expect(adapter.nodes().filter(n => n.kind === 'compaction')).toEqual([
-        {
-          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: 'first',
-          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-        {
-          kind: 'compaction', seq: 5, time: 1_700_000_000_005, summary: 'second',
-          summaryEventSeq: 4, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-      ])
-    })
-
-    it('renders the marker when the shadowed range is outside the window and logs nothing', () => {
-      // The pagination hole A1 left open: quota is no longer spent on
-      // replacement copies, so a page can carry a checkpoint whose
-      // surfaceOp.start lies below the window head. The old surface fold threw
-      // on the missing range and degraded with a console error; a log-ordered
-      // projection has no range to resolve.
-      const adapter = new TranscriptAdapter()
-      const noise = { error: console.error, warn: console.warn }
-      const logged: unknown[] = []
-      console.error = (...args: unknown[]) => logged.push(args)
-      console.warn = (...args: unknown[]) => logged.push(args)
-      try {
-        adapter.reset([
-          compactSummary(80, [{ type: 'text', text: '窗外范围' }]),
-          checkpoint(81, 80, { start: 3, end: 40, sourceEventSeqs: [80, 3, 40] }),
-          ev.user(82, '压缩后的新问题'),
-        ])
-        expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['compaction', 81], ['user', 82]])
-        expect(adapter.nodes()[0]).toMatchObject({ summary: '窗外范围' })
-      } finally {
-        console.error = noise.error
-        console.warn = noise.warn
-      }
-      expect(logged).toEqual([])
-    })
-
-    it('treats an APPENDING plugin-sourced user/message as injected context, not a compaction', () => {
-      // A session-reference card carries the same plugin source shape; only the
-      // replacement marker makes an event a checkpoint.
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-          content: [{ type: 'text', text: '注入的上下文' }],
-          source: { kind: 'plugin', plugin: 'compact', form: 'instructions' },
-        }) }),
-      ])
-      expect(adapter.nodes()).toMatchObject([{
-        kind: 'context',
-        seq: 0,
-        provenance: { role: 'inject', label: 'compact' },
-        form: 'instructions',
-      }])
-    })
-
-    it('ignores a foreign plugin s replacement user/message', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '保留'),
-        at(1, { type: 'user/message', surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0], data: createUserMessage({
-          content: [{ type: 'text', text: '别的插件重写' }],
-          source: { kind: 'plugin', plugin: 'not-compact' },
-        }) }),
-      ])
-      expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 0]])
-    })
-
-    it.each([
-      ['absent summary event', undefined],
-      ['text-less summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])],
-      ['a whitespace-only summary', compactSummary(1, [{ type: 'text', text: '   ' }])],
-      ['an empty summary array', compactSummary(1, [])],
-      ['a non-array summary', compactSummary(1, 'plain string')],
-    ])('degrades %s to a non-expandable marker', (_label, summary) => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ...(summary === undefined ? [] : [summary]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-      ])
-      expect(adapter.nodes()).toMatchObject([
-        { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null },
-      ])
-    })
-
-    it('keeps the text of a mixed-block summary, skipping the blocks it cannot render', () => {
-      // ContentBlock is merge-extensible and the payload type is ContentBlock[],
-      // so a non-text block must not discard recoverable text beside it.
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        compactSummary(1, [{ type: 'text', text: '可用摘要' }, { type: 'image', data: 'nope' }]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-      ])
-      expect(adapter.nodes()).toEqual([
-        {
-          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: '可用摘要',
-          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-      ])
-    })
-
-    it('leaves the summary null when the checkpoint cites no source events', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([at(2, {
-        type: 'user/message',
-        surfaceOp: { op: 'replace', start: 0, end: 0 },
-        data: createUserMessage({
-          content: [{ type: 'text', text: '<context_checkpoint>x</context_checkpoint>' }],
-          source: { kind: 'plugin', plugin: 'compact' },
-        }),
-      })])
-      expect(adapter.nodes()).toEqual([{
-        kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null,
-        summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
-      }])
-    })
-
-    it('skips a cited non-summary seq before reaching the summary event', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '被压缩的问题'),
-        at(1, { type: 'compact/start', data: { turn: 0 } }),
-        compactSummary(2, [{ type: 'text', text: '第三个来源才是摘要' }]),
-        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [1, 2, 0] }),
-      ])
-      expect(adapter.nodes().at(-1)).toMatchObject({ kind: 'compaction', summary: '第三个来源才是摘要' })
-    })
-
-    it('resolves the summary once an older page supplies the cited summary event', () => {
-      const adapter = new TranscriptAdapter()
-      const landed = checkpoint(8, 7, { start: 0, end: 0, sourceEventSeqs: [7, 0] })
-      adapter.reset([landed])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: null })
-      adapter.reset([compactSummary(7, [{ type: 'text', text: '分页补齐的摘要' }]), landed])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: '分页补齐的摘要' })
-    })
-
-    it('creates the marker on the live append path', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset(plainTurn(0, 0, 'a', 'b'))
-      adapter.append(compactSummary(6, [{ type: 'text', text: '直播摘要' }]))
-      adapter.append(checkpoint(7, 6, { start: 1, end: 3, sourceEventSeqs: [6, 1, 3] }))
-      const nodes = adapter.nodes()
-      // The compacted history is still there; the marker is one more row after it.
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 1], ['assistant', 3], ['compaction', 7]])
-      expect(nodes.at(-1)).toMatchObject({ kind: 'compaction', seq: 7, summary: '直播摘要' })
-    })
-  })
-
-  it('returns call:null for a tool-result whose call fell outside the window', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([ev.toolResult(50, 3, 'outside-call', '孤儿结果')])
-    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null })
-  })
-
-  it('materializes a tool-result error field when present', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      at(0, { type: 'tool/result', surfaceOp: 'append', data: {
-        turn: 0, step: 0,
-        message: createToolResultMessage({ callId: CallId('c1'), content: [], isError: true }),
-        error: { name: 'Boom', code: 'boom' },
-      } }),
-    ])
-    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } })
-  })
-
-  it('attaches wire views to the materialized result node', () => {
-    const adapter = new TranscriptAdapter()
-    const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } }
-    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } }
-    adapter.reset([
-      ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'),
-      ev.toolResult(1, 1, 'c1', 'listing'),
-    ], [callView, resultView] as never)
-    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
-      callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' },
-    })
-  })
-
-  it('attaches views on the live append path and defaults to null without views', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b')) // no views argument
-    adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never)
-    adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result
-    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
-      callView: { title: '回声' }, resultView: null,
-    })
-  })
-
-  it('leaves callView null when the paired call fell outside the window (cross-page break)', () => {
-    const adapter = new TranscriptAdapter()
-    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } }
-    adapter.reset([ev.toolResult(50, 3, 'outside', '窗外配对')], [resultView] as never)
-    expect(adapter.nodes()[0]).toMatchObject({
-      kind: 'tool-result', call: null, callView: null, resultView: { title: '孤儿' },
-    })
-  })
-
-  describe('command lifecycle nodes', () => {
-    it('folds a run/done pair into one settled node merged into flow order by seq', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '先说话'),
-        ev.commandRun(1, 'cmd-1', 'plan'),
-        ev.commandDone(2, 'cmd-1', 'success', '已进入 plan mode'),
-        ev.assistant(3, 0, '然后回答'),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['assistant', 3]])
-      expect(nodes[1]).toMatchObject({
-        kind: 'command', commandId: 'cmd-1', name: 'plan', args: '',
-        outcome: { kind: 'success', text: '已进入 plan mode' },
-      })
-    })
-
-    it('renders a run with no done as still executing (outcome null)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandRun(0, 'cmd-2', 'goal', ' ship it')])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'command', name: 'goal', args: ' ship it', outcome: null })
-    })
-
-    it('represents command input omitted by the host as null', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandRunWithoutInput(0, 'cmd-private', 'feedback')])
-      expect(adapter.nodes()[0]).toMatchObject({
-        kind: 'command', name: 'feedback', args: null, outcome: null,
-      })
-    })
-
-    it('soft-falls a done-only window into a node built from the done (cross-window cut)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandDone(80, 'cmd-3', 'error', '失败了')])
-      expect(adapter.nodes()[0]).toMatchObject({
-        kind: 'command', seq: 80, commandId: 'cmd-3', name: null, args: null,
-        outcome: { kind: 'error', text: '失败了' },
-      })
-    })
-
-    it('settles a live-appended done in place, keeping the node at the run seq', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset(plainTurn(0, 0, 'q', 'a'))
-      adapter.append(ev.commandRun(6, 'cmd-4', 'clear'))
-      const running = adapter.nodes().find(n => n.kind === 'command')
-      expect(running).toMatchObject({ outcome: null })
-      adapter.append(ev.commandDone(7, 'cmd-4'))
-      const settled = adapter.nodes().find(n => n.kind === 'command')
-      expect(settled).toMatchObject({ seq: 6, outcome: { kind: 'success' } })
-      // Settlement replaced the node object rather than mutating the published one.
-      expect(settled).not.toBe(running)
-    })
-
-    it('tails command nodes whose seq is past every transcript node', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.user(0, '问'), ev.commandRun(1, 'cmd-tail', 'plan')])
-      expect(adapter.nodes().map(n => n.kind)).toEqual(['user', 'command'])
-    })
-
-    it('preserves the domain-event link for the UI to fold a /compact row into its marker', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '压缩前的问题'),
-        ev.commandRun(1, 'cmd-compact', 'compact'),
-        compactSummary(2, [{ type: 'text', text: '手动压缩摘要' }]),
-        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [2, 0] }),
-        ev.commandDone(4, 'cmd-compact', 'success', '已压缩', 2),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['compaction', 3]])
-      expect(nodes[1]).toMatchObject({
-        name: 'compact',
-        outcome: { kind: 'success', text: '已压缩', sourceEventSeq: 2 },
-      })
-      expect(nodes[2]).toMatchObject({ kind: 'compaction', summaryEventSeq: 2 })
-    })
-  })
-
-  describe('assistant timing', () => {
-    const base = 1_700_000_000_000
-
-    it('derives step timing across a window rebuild (start + first token + completion)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.turnStart(0, 0),
-        ev.user(1, '问'),
-        ev.stepStart(2, 0),
-        ev.chunkStart(3, 0),
-        ev.chunkText(4, 0, '答'),
-        ev.chunkText(5, 0, '案'),
-        ev.assistant(6, 0, '答案'),
-        ev.turnEnd(7, 0),
-      ])
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: base + 2, firstTokenTime: base + 4, completedTime: base + 6 },
-      })
-    })
-
-    it('derives the same timing on the live append path, first token winning once', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.user(0, '问')])
-      adapter.append(ev.stepStart(1, 0))
-      adapter.append(ev.chunkText(2, 0, '首'))
-      adapter.append(ev.chunkText(3, 0, '次'))
-      adapter.append(ev.assistant(4, 0, '首次'))
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: base + 1, firstTokenTime: base + 2, completedTime: base + 4 },
-      })
-    })
-
-    it('soft-falls to null boundaries when the step opening fell outside the window', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.assistant(100, 0, '被切窗的答案')])
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: null, firstTokenTime: null, completedTime: base + 100 },
-      })
-    })
-  })
-})
diff --git a/packages/client/test-runtime/src/fixtures.ts b/packages/client/test-runtime/src/fixtures.ts
index ea01893346..7f65a0b5a3 100644
--- a/packages/client/test-runtime/src/fixtures.ts
+++ b/packages/client/test-runtime/src/fixtures.ts
@@ -2,6 +2,7 @@
 import type {
   ConversationSnapshot, ISession, SessionId, SessionSummary, WorkspaceListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import { EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 
 /**
  * Fixture overrides for the session behavior face: any subset of the
@@ -45,6 +46,7 @@ export interface SessionFixture {
 export function conversationSnapshot(sessionId: SessionId): ConversationSnapshot {
   return {
     sessionId,
+    chat: EMPTY_CHAT_SNAPSHOT,
     nodes: [],
     turnTimings: new Map(),
     turnEnds: new Map(),
diff --git a/packages/client/test-runtime/src/index.ts b/packages/client/test-runtime/src/index.ts
index 3005c061e7..0b8c732683 100644
--- a/packages/client/test-runtime/src/index.ts
+++ b/packages/client/test-runtime/src/index.ts
@@ -22,7 +22,9 @@ import { act, render, within } from '@testing-library/react'
 import type { RenderResult } from '@testing-library/react'
 import type { queries } from '@testing-library/dom'
 import type { BoundFunctions } from '@testing-library/dom'
-import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  ConversationEventRegistry, ConversationViewRegistry, SlotsService,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
 import type {
   ChildrenDecl, ComposedProps, OwnerOf, SlotComponent, SlotMap, SlotRendererHost, StoreInstanceLike,
@@ -142,7 +144,7 @@ export class TestRoot {
    */
   async declare<const D extends ChildrenDecl>(
     children: D,
-    frame: SlotComponent<ComposedProps<'root', keyof NoInfer<D> & keyof SlotMap & string, undefined, object>>,
+    frame: SlotComponent<ComposedProps<'root', never, keyof NoInfer<D> & keyof SlotMap & string, undefined, object>>,
   ): Promise<void> {
     await this.stabilize(() => {
       // Erased hop (same pattern as SlotsService's own implementation arm);
@@ -218,6 +220,8 @@ export class SlotTestRuntime {
     const ctx = new Context()
     const fiber = ctx.plugin(SlotsService)
     await fiber.await()
+    await ctx.plugin(ConversationEventRegistry).await()
+    await ctx.plugin(ConversationViewRegistry).await()
     return new SlotTestRuntime(ctx, ctx.get('slots') as SlotsService)
   }
 
diff --git a/packages/client/ui-conversation/tests/chat-apply.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
index 00001275d2..3481ee758e 100644
--- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
@@ -53,7 +53,7 @@ describe('apply wiring', () => {
     await b.runtime.dispose()
   })
 
-  it('registers the chat view as the first ring entry, declaring the whole-Tool seat', async () => {
+  it('registers the chat view and its keyed business-node seat', async () => {
     const b = await bench()
     const entries = b.slots.entries('conversation.view')
     expect(entries.map(e => e.options.id)).toEqual(['chat'])
@@ -62,7 +62,7 @@ describe('apply wiring', () => {
     expect(entries[0]?.options.order).toBe(0)
     // Declaring is claiming: the chat entry's registration put the hole on
     // the ledger with the contract's kind/scope.
-    expect(b.slots.spec('conversation.chat.tool')).toEqual({ kind: 'single', scope: 'session' })
+    expect(b.slots.spec('conversation.chat.node')).toEqual({ kind: 'keyed', scope: 'session' })
     await b.runtime.dispose()
   })
 
@@ -95,7 +95,7 @@ describe('apply wiring', () => {
     // file-mutation registrant claims both write and edit for the diff card; the
     // one search row registers under both grep and glob; the web rows register
     // one component under both web tool names.
-    expect(b.slots.entries('conversation.chat.tool')).toHaveLength(0)
+    expect(b.slots.entries('conversation.chat.node').map(entry => entry.options.key)).not.toContain('tool-call')
     // Stats stick with the composer (not inside ChatView).
     expect(b.slots.entries('conversation.composer.dock').map(e => e.options.id)).toEqual(['stats'])
     await b.runtime.dispose()
@@ -108,8 +108,8 @@ describe('apply wiring', () => {
     // The declared ring collapses with its declaring entry, and the chat
     // entry's keyed hole (with the sample's registration) collapses with it.
     expect(b.slots.entries('conversation.view')).toHaveLength(0)
-    expect(b.slots.entries('conversation.chat.tool')).toHaveLength(0)
-    expect(b.slots.spec('conversation.chat.tool')).toBeUndefined()
+    expect(b.slots.entries('conversation.chat.node')).toHaveLength(0)
+    expect(b.slots.spec('conversation.chat.node')).toBeUndefined()
     expect(b.slots.entries('details')).toHaveLength(0)
     expect(b.slots.entries('settings.general.item')).toHaveLength(0)
     expect(b.runtime.ctx.get('conversation')).toBeUndefined()
diff --git a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
index 0362c3ee4b..6037405336 100644
--- a/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx
@@ -10,13 +10,21 @@ import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import type {
+  ChatConversationViewNode, ConversationNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ChatNodeViewProps } from '../src/client/contract/slots.ts'
 import {
   formatMessageClock, msUntilNextLocalMidnight, startOfLocalDay,
 } from '../src/client/chat/message-chrome.ts'
-import { MessageItem, type MessageItemProps } from '../src/client/chat/MessageItem.tsx'
+import {
+  CompactionNodeView, ContextMessageNodeView, RetryNodeView, UnknownNodeView,
+  UserMessageNodeView,
+} from '../src/client/chat/MessageItem.tsx'
 import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
 import { StatsLine, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
 import { zh } from '../src/client/locales.ts'
+import { chatSnapshotFixture } from './chat-snapshot-fixture.ts'
 
 /** jsdom has no ResizeObserver; StatsLine watches its row for ellipsis truncation through one. */
 class ResizeObserverStub {
@@ -33,7 +41,44 @@ afterEach(() => {
 })
 
 // Mirrors the real lookup chain (conversation namespace, then common).
-const t: MessageItemProps['t'] = makeTranslate(zh, commonZh)
+const t: ChatNodeViewProps['t'] = makeTranslate(zh, commonZh)
+const RETRY_ID = 'retry-fixture' as Extract<ConversationNode, { kind: 'model-retry' }>['retryId']
+
+interface MessageItemProps {
+  readonly node: ConversationNode
+  readonly t: ChatNodeViewProps['t']
+}
+
+/** Legacy-node fixture adapter for the independently registered renderers. */
+function MessageItem({ node, t: translate }: MessageItemProps) {
+  const kind = node.kind === 'assistant' ? 'assistant-step' : node.kind
+  const viewNode: ChatConversationViewNode = {
+    key: `fixture:${node.kind}:${node.seq}`,
+    kind,
+    id: String(node.seq),
+    target: 'chat',
+    anchorSeq: node.seq,
+    location: { kind: 'session' },
+    visibility: 'visible',
+    data: node.kind === 'model-retry' ? { attempts: [node], current: node } : node,
+  }
+  const props = { node: viewNode, t: translate } as ChatNodeViewProps
+  switch (node.kind) {
+    case 'user':
+    case 'steering':
+      return <UserMessageNodeView {...props as ChatNodeViewProps<'user' | 'steering'>} />
+    case 'context':
+      return <ContextMessageNodeView {...props as ChatNodeViewProps<'context'>} />
+    case 'compaction':
+      return <CompactionNodeView {...props as ChatNodeViewProps<'compaction'>} />
+    case 'model-retry':
+      return <RetryNodeView {...props as ChatNodeViewProps<'model-retry'>} />
+    case 'unknown':
+      return <UnknownNodeView {...props as ChatNodeViewProps<'unknown'>} />
+    default:
+      throw new Error(`unsupported MessageItem fixture kind: ${node.kind}`)
+  }
+}
 
 describe('MessageItem arms', () => {
   it('user bubbles expose clock / copy and neither branch nor edit; copy writes the text', () => {
@@ -727,9 +772,9 @@ describe('MessageItem arms', () => {
     const view = render(
       <MessageItem
         t={t}
-        retryActive
         node={{
           kind: 'model-retry',
+          retryId: RETRY_ID,
           seq: 5,
           time: 10_000,
           retryState: 'scheduled',
@@ -761,9 +806,9 @@ describe('MessageItem arms', () => {
     view.rerender(
       <MessageItem
         t={t}
-        retryActive
         node={{
           kind: 'model-retry',
+          retryId: RETRY_ID,
           seq: 6,
           time: 12_100,
           retryState: 'scheduled',
@@ -788,6 +833,7 @@ describe('MessageItem arms', () => {
     view.rerender(
       <MessageItem t={t} node={{
         kind: 'model-retry',
+        retryId: RETRY_ID,
         seq: 6,
         time: 12_100,
         retryState: 'started',
@@ -809,6 +855,7 @@ describe('MessageItem arms', () => {
     view.rerender(
       <MessageItem t={t} node={{
         kind: 'model-retry',
+        retryId: RETRY_ID,
         seq: 7,
         time: 12_100,
         retryState: 'started',
@@ -828,6 +875,7 @@ describe('MessageItem arms', () => {
     view.rerender(
       <MessageItem t={t} node={{
         kind: 'model-retry',
+        retryId: RETRY_ID,
         seq: 8,
         time: 12_100,
         retryState: 'cancelled',
@@ -846,32 +894,6 @@ describe('MessageItem arms', () => {
     expect(view.getByRole('status').textContent).toBe('模型请求重试已取消（1/2） · 4s')
   })
 
-  it('synchronizes the countdown when an inactive retry becomes active at the one-second floor', () => {
-    vi.useFakeTimers()
-    vi.setSystemTime(10_000)
-    const node = {
-      kind: 'model-retry',
-      seq: 5,
-      time: 10_000,
-      retryState: 'scheduled',
-      turn: 1,
-      step: 0,
-      provider: 'mock',
-      mode: 'normal',
-      policyKey: 'mock-normal',
-      retry: 1,
-      maxRetries: 2,
-      delayMs: 5_000,
-      failure: { code: 'TRANSPORT', message: '连接被重置' },
-    } as const
-    const view = render(<MessageItem t={t} node={node} />)
-    expect(view.getByRole('status').textContent).toBe('等待重试模型请求（1/2） · 5s')
-
-    act(() => { vi.advanceTimersByTime(4_200) })
-    view.rerender(<MessageItem t={t} node={node} retryActive />)
-    expect(view.getByRole('status').textContent).toBe('正在重试模型请求（1/2） · 1s')
-  })
-
 })
 
 describe('formatMessageClock', () => {
@@ -932,84 +954,13 @@ describe('small branch tails', () => {
     expect(view.getByText('one-liner')).toBeTruthy()
   })
 
-  it('finalized content messages expose copy / branch / clock; Think-only and streaming omit them', () => {
-    const writeText = vi.fn().mockResolvedValue(undefined)
-    Object.defineProperty(navigator, 'clipboard', {
-      configurable: true,
-      value: { writeText },
-    })
-    const now = new Date()
-    const time = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 14, 24).getTime()
-    const onFork = vi.fn()
-    const settled = render(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'text', text: 'answer body' }, { kind: 'reasoning', text: 'hidden' }]}
-        streaming={false}
-        time={time}
-        seq={3}
-        onFork={onFork}
-      />,
-    )
-    expect(settled.getByText('14:24')).toBeTruthy()
-    expect(settled.getByRole('button', { name: '复制' })).toBeTruthy()
-    expect(settled.getByRole('button', { name: '在新对话中分支' })).toBeTruthy()
-    fireEvent.click(settled.getByRole('button', { name: '复制' }))
-    expect(writeText).toHaveBeenCalledWith('answer body')
-    fireEvent.click(settled.getByRole('button', { name: '在新对话中分支' }))
-    expect(onFork).toHaveBeenCalledWith(3)
-    settled.unmount()
-
-    const thinkOnly = render(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'reasoning', text: 'only thinking' }]}
-        streaming={false}
-        time={time}
-      />,
-    )
-    expect(thinkOnly.queryByRole('button', { name: '复制' })).toBeNull()
-    expect(thinkOnly.queryByText('14:24')).toBeNull()
-    thinkOnly.unmount()
-
-    const streaming = render(
-      <AssistantMarkdown t={t} blocks={[{ kind: 'text', text: 'partial' }]} streaming time={time} />,
-    )
-    expect(streaming.queryByRole('button', { name: '复制' })).toBeNull()
-    expect(streaming.queryByText('14:24')).toBeNull()
-  })
-
-  it('keeps an unavailable branch focusable and explains why without sending a fork', () => {
-    const onFork = vi.fn()
-    render(
-      <AssistantMarkdown
-        t={t}
-        blocks={[{ kind: 'text', text: 'answer before a trailing tool row' }]}
-        streaming={false}
-        time={1_000}
-        seq={1}
-        onFork={onFork}
-        forkUnavailable
-      />,
-    )
-    const branch = screen.getByRole('button', { name: '在新对话中分支' }) as HTMLButtonElement
-    expect(branch.disabled).toBe(false)
-    expect(branch.getAttribute('aria-disabled')).toBe('true')
-    const reasonId = branch.getAttribute('aria-describedby')
-    expect(reasonId).not.toBeNull()
-    expect(document.getElementById(reasonId!)?.textContent).toBe('仅可从已完成轮次的最后一条消息分支')
-    fireEvent.click(branch)
-    expect(onFork).not.toHaveBeenCalled()
-    fireEvent.focus(branch)
-    expect(screen.getByRole('tooltip').textContent).toBe('仅可从已完成轮次的最后一条消息分支')
-  })
-
   it('StatsLine omits the cache-hit segment when no input accounting exists at all', () => {
     // Cache hit is null only when all three prompt buckets are zero (pure
     // output accounting) — any billed input makes it a real 0%.
-    const snap = {
-      nodes: [{ kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [], usage: { outputTokens: 10 } }],
-    }
+    const nodes = [{
+      kind: 'assistant', seq: 1, time: 1_000, turn: 1, step: 1, blocks: [], usage: { outputTokens: 10 },
+    }] as const
+    const snap = { chat: chatSnapshotFixture({ nodes }), nodes }
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
     const view = render(
       <StatsLine
diff --git a/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts b/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
new file mode 100644
index 0000000000..c675554ea0
--- /dev/null
+++ b/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
@@ -0,0 +1,295 @@
+import type {
+  AssistantMessageNode, ChatConversationViewNode, ChatSnapshot, ConversationNode,
+  ChatLocationNodeIndex, ChatNodeStore, CompactionSummaryNode, ConversationLocationDataStore,
+  ConversationTurnDataMap, LegacyConversationSlice, PartialAssistant, RunningToolCall,
+  ToolCallBlock, TurnLocation,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { deriveTurnMetrics } from '../src/client/chat/turn-metrics.ts'
+
+const EMPTY: readonly never[] = []
+
+function sameValues<T>(left: readonly T[], right: readonly T[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+function nodeSource(node: ChatConversationViewNode): unknown {
+  if (node.kind === 'assistant-step') {
+    const data = node.data as ReturnType<typeof assistantData>
+    return data.finalNode ?? data.blocks
+  }
+  if (node.kind === 'tool-call') return (node.data as { readonly root: ToolCallBlock }).root
+  if (node.kind === 'model-retry') return (node.data as { readonly current: unknown }).current
+  if (node.kind === 'turn-tail') return (node.data as { readonly seq: number }).seq
+  return node.data
+}
+
+class FixtureNodeStore implements ChatNodeStore {
+  private byKey = new Map<string, ChatConversationViewNode>()
+  private list: readonly ChatConversationViewNode[] = EMPTY
+
+  get(key: string): ChatConversationViewNode | undefined {
+    return this.byKey.get(key)
+  }
+
+  values(): readonly ChatConversationViewNode[] {
+    return this.list
+  }
+
+  replace(candidates: readonly ChatConversationViewNode[]): void {
+    const next = new Map<string, ChatConversationViewNode>()
+    const list = candidates.map((candidate) => {
+      const previous = this.byKey.get(candidate.key)
+      const node = previous !== undefined
+        && previous.kind === candidate.kind
+        && previous.anchorSeq === candidate.anchorSeq
+        && previous.visibility === candidate.visibility
+        && nodeSource(previous) === nodeSource(candidate)
+        ? previous
+        : candidate
+      next.set(node.key, node)
+      return node
+    })
+    this.byKey = next
+    this.list = sameValues(this.list, list) ? this.list : list
+  }
+}
+
+class FixtureLocationIndex implements ChatLocationNodeIndex {
+  private turns = new Map<number, readonly string[]>()
+
+  getTurn(turn: number): readonly string[] {
+    return this.turns.get(turn) ?? EMPTY
+  }
+
+  getStep(): readonly string[] {
+    return EMPTY
+  }
+
+  replace(next: ReadonlyMap<number, readonly string[]>): void {
+    const stable = new Map<number, readonly string[]>()
+    for (const [turn, keys] of next) {
+      const previous = this.turns.get(turn) ?? EMPTY
+      stable.set(turn, sameValues(previous, keys) ? previous : keys)
+    }
+    this.turns = stable
+  }
+}
+
+class FixtureTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
+  private readonly values = new Map<string, unknown>()
+
+  get<Key extends keyof ConversationTurnDataMap & string>(
+    key: Key,
+  ): Readonly<ConversationTurnDataMap[Key]> | undefined {
+    return this.values.get(key) as Readonly<ConversationTurnDataMap[Key]> | undefined
+  }
+
+  set<Key extends keyof ConversationTurnDataMap & string>(key: Key, value: ConversationTurnDataMap[Key]): void {
+    this.values.set(key, value)
+  }
+}
+
+function assistantData(node: AssistantMessageNode) {
+  return {
+    status: node.interrupted === true ? 'interrupted' as const : 'settled' as const,
+    turn: node.turn,
+    step: node.step,
+    blocks: node.blocks,
+    time: node.time,
+    finalNode: node,
+  }
+}
+
+function settledNode(
+  node: ConversationNode,
+  turns: ReadonlyMap<number, TurnLocation>,
+): ChatConversationViewNode {
+  const turn = 'turn' in node && typeof node.turn === 'number' ? turns.get(node.turn) : undefined
+  const base = {
+    key: `fixture:${node.kind}:${node.seq}`,
+    id: String(node.seq),
+    target: 'chat' as const,
+    anchorSeq: node.seq,
+    location: turn === undefined
+      ? { kind: 'session' as const }
+      : { kind: 'turn' as const, turn },
+    visibility: 'visible' as const,
+  }
+  switch (node.kind) {
+    case 'assistant':
+      return { ...base, kind: 'assistant-step', data: assistantData(node) }
+    case 'tool-result':
+      return { ...base, key: `fixture:tool:${node.callId}`, kind: 'tool-call', data: { root: node } }
+    case 'model-retry':
+      return { ...base, key: 'fixture:model-retry', kind: 'model-retry', data: { attempts: [node], current: node } }
+    default:
+      return { ...base, kind: node.kind, data: node }
+  }
+}
+
+/** Build the canonical Chat fixture corresponding to one legacy test slice. */
+export function chatSnapshotFixture(input: {
+  readonly nodes?: readonly ConversationNode[]
+  readonly partial?: PartialAssistant | null
+  readonly runningCalls?: readonly RunningToolCall[]
+  readonly turnTimings?: LegacyConversationSlice['turnTimings']
+  readonly turnEnds?: LegacyConversationSlice['turnEnds']
+} = {}, previous?: ChatSnapshot): ChatSnapshot {
+  const legacy: LegacyConversationSlice = {
+    nodes: input.nodes ?? EMPTY,
+    partial: input.partial ?? null,
+    runningCalls: input.runningCalls ?? EMPTY,
+    turnTimings: input.turnTimings ?? new Map(),
+    turnEnds: input.turnEnds ?? new Map(),
+  }
+  const turnNumbers = new Set([...legacy.turnTimings.keys(), ...legacy.turnEnds.keys()])
+  for (const node of legacy.nodes) {
+    if ('turn' in node && typeof node.turn === 'number') turnNumbers.add(node.turn)
+  }
+  if (legacy.partial !== null) turnNumbers.add(legacy.partial.turn)
+  for (const call of legacy.runningCalls) turnNumbers.add(call.turn)
+  const turns = new Map<number, TurnLocation>()
+  const turnData = new Map<number, FixtureTurnDataStore>()
+  for (const turn of [...turnNumbers].sort((left, right) => left - right)) {
+    const timing = legacy.turnTimings.get(turn)
+    const endSeq = legacy.turnEnds.get(turn)
+    const data = new FixtureTurnDataStore()
+    turnData.set(turn, data)
+    turns.set(turn, {
+      turn,
+      start: timing === undefined ? undefined : {
+        type: 'turn/start', seq: Math.max(0, (endSeq ?? 1) - 1), time: timing.startTime, turn,
+      } as never,
+      end: timing?.endTime === undefined || endSeq === undefined ? undefined : {
+        type: 'turn/end', seq: endSeq, time: timing.endTime, turn, reason: 'completed',
+      } as never,
+      status: endSeq === undefined ? 'open' : 'closed',
+      steps: EMPTY,
+      data,
+    })
+  }
+  const linkedCompactions = new Set<CompactionSummaryNode>()
+  const nodes = legacy.nodes.flatMap((node): ChatConversationViewNode[] => {
+    if (node.kind === 'command' && node.name === 'compact') {
+      const sourceSeq = node.outcome?.kind === 'success' ? node.outcome.sourceEventSeq : undefined
+      const candidates = sourceSeq === undefined
+        ? []
+        : legacy.nodes.filter((candidate): candidate is CompactionSummaryNode =>
+          candidate.kind === 'compaction' && candidate.summaryEventSeq === sourceSeq)
+      const compaction = candidates.length === 1 ? candidates[0] : undefined
+      if (node.outcome === null || compaction !== undefined) {
+        if (compaction !== undefined) linkedCompactions.add(compaction)
+        const base = settledNode(node, turns)
+        return [{
+          ...base,
+          key: `fixture:manual-compaction:${node.commandId}`,
+          kind: 'manual-compaction',
+          anchorSeq: compaction?.seq ?? node.seq,
+          data: { command: node, compaction: compaction ?? null },
+        }]
+      }
+    }
+    if (node.kind === 'compaction' && linkedCompactions.has(node)) return []
+    return [settledNode(node, turns)]
+  })
+  if (legacy.partial !== null) {
+    const turn = turns.get(legacy.partial.turn)
+    nodes.push({
+      key: `fixture:assistant:${legacy.partial.turn}:${legacy.partial.step}`,
+      id: `${legacy.partial.turn}:${legacy.partial.step}`,
+      target: 'chat',
+      kind: 'assistant-step',
+      anchorSeq: Number.MAX_SAFE_INTEGER - 1,
+      location: turn === undefined ? { kind: 'session' } : { kind: 'turn', turn },
+      visibility: 'visible',
+      data: {
+        status: 'running',
+        turn: legacy.partial.turn,
+        step: legacy.partial.step,
+        blocks: legacy.partial.blocks,
+        time: 0,
+      },
+    })
+  }
+  for (const call of legacy.runningCalls) {
+    const turn = turns.get(call.turn)
+    nodes.push({
+      key: `fixture:tool:${call.callId}`,
+      id: call.callId,
+      target: 'chat',
+      kind: 'tool-call',
+      anchorSeq: Number.MAX_SAFE_INTEGER,
+      location: turn === undefined ? { kind: 'session' } : { kind: 'turn', turn },
+      visibility: 'visible',
+      data: { root: call },
+    })
+  }
+  for (const [turnNumber, endSeq] of legacy.turnEnds) {
+    const turn = turns.get(turnNumber)
+    const dataStore = turnData.get(turnNumber)
+    if (turn === undefined || dataStore === undefined) continue
+    const closing = legacy.nodes
+      .filter((candidate): candidate is AssistantMessageNode => candidate.kind === 'assistant'
+        && candidate.turn === turnNumber
+        && candidate.blocks.some(block => block.kind === 'text' && block.text.trim() !== ''))
+      .map(assistantData)
+      .at(-1) ?? null
+    const preceding = nodes.findLast((candidate) => {
+      const location = candidate.location
+      return (location.kind === 'turn' || location.kind === 'step')
+        && location.turn.turn === turnNumber
+    })
+    const metrics = deriveTurnMetrics(legacy.nodes).get(turnNumber)
+    const tailData = {
+      turn: turnNumber,
+      seq: endSeq,
+      time: turn.end?.time ?? 0,
+      closing,
+      branchUnavailable: closing === null
+        || preceding?.kind !== 'assistant-step'
+        || (preceding.data as ReturnType<typeof assistantData>).finalNode.seq !== closing.finalNode.seq,
+      ...metrics?.ttftMs === undefined ? {} : { ttftMs: metrics.ttftMs },
+      ...metrics?.tokensPerSecond === undefined ? {} : { tokensPerSecond: metrics.tokensPerSecond },
+    }
+    dataStore.set('turn-tail', tailData)
+    nodes.push({
+      key: `fixture:turn-tail:${turnNumber}`,
+      id: String(turnNumber),
+      target: 'chat',
+      kind: 'turn-tail',
+      anchorSeq: endSeq,
+      location: { kind: 'turn', turn },
+      visibility: 'visible',
+      data: tailData,
+    })
+  }
+  const store = previous?.nodes instanceof FixtureNodeStore ? previous.nodes : new FixtureNodeStore()
+  store.replace(nodes)
+  const byKey = new Map(store.values().map(node => [node.key, node]))
+  const nextOrder = nodes.map(node => node.key)
+  const order = previous !== undefined && sameValues(previous.order, nextOrder) ? previous.order : nextOrder
+  const byTurn = new Map<number, readonly string[]>()
+  for (const turn of turns.keys()) {
+    byTurn.set(turn, order.filter((key) => {
+      const location = byKey.get(key)?.location
+      return location?.kind === 'turn' && location.turn.turn === turn
+        || location?.kind === 'step' && location.turn.turn === turn
+    }))
+  }
+  const locations = previous?.locations instanceof FixtureLocationIndex
+    ? previous.locations
+    : new FixtureLocationIndex()
+  locations.replace(byTurn)
+  const timeline = previous !== undefined
+    && previous.legacy.turnTimings === legacy.turnTimings
+    && previous.legacy.turnEnds === legacy.turnEnds
+    ? previous.timeline
+    : { turnOrder: [...turns.keys()], turns }
+  return {
+    order,
+    nodes: store,
+    locations,
+    timeline,
+    legacy,
+  }
+}
diff --git a/packages/client/ui-conversation/tests/chat-stats.spec.tsx b/packages/client/ui-conversation/tests/chat-stats.spec.tsx
index 78fbf43c5e..959a91c3ac 100644
--- a/packages/client/ui-conversation/tests/chat-stats.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-stats.spec.tsx
@@ -13,6 +13,7 @@ import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { StatsLine, contextOccupancy, deriveStats, formatDuration, formatTokens, type StatsLineProps } from '../src/client/chat/StatsLine.tsx'
 import { en, zh } from '../src/client/locales.ts'
+import { chatSnapshotFixture } from './chat-snapshot-fixture.ts'
 
 // Mirrors the real lookup chain (conversation namespace, then common).
 const t: StatsLineProps['t'] = makeTranslate(zh, commonZh)
@@ -42,18 +43,39 @@ const assistant = (seq: number, turn: number, usage?: unknown): AssistantMessage
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: chatSnapshotFixture(),
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
 }
 
 function makeSource(init?: Partial<ConversationSnapshot>) {
-  let snap: ConversationSnapshot = { ...snapshotBase(), ...init }
+  const initial = { ...snapshotBase(), ...init }
+  let snap: ConversationSnapshot = {
+    ...initial,
+    chat: init?.chat ?? chatSnapshotFixture({
+      nodes: initial.nodes,
+      partial: initial.partial,
+      runningCalls: initial.runningCalls,
+      turnTimings: initial.turnTimings,
+      turnEnds: initial.turnEnds,
+    }),
+  }
   const subs = new Set<() => void>()
   return {
     set: (next: Partial<ConversationSnapshot>) => {
-      snap = { ...snap, ...next }
+      const merged = { ...snap, ...next }
+      snap = {
+        ...merged,
+        chat: next.chat ?? (next.nodes === undefined ? snap.chat : chatSnapshotFixture({
+          nodes: merged.nodes,
+          partial: merged.partial,
+          runningCalls: merged.runningCalls,
+          turnTimings: merged.turnTimings,
+          turnEnds: merged.turnEnds,
+        })),
+      }
       for (const fn of [...subs]) fn()
     },
     source: {
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index 9bb043df15..296dd85966 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -4,24 +4,33 @@
 // ObservableSnapshot fake, no wire or Tool presentation plugin.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { Profiler } from 'react'
 import { act, cleanup, fireEvent, render, within } from '@testing-library/react'
+import { useEffect } from 'react'
 import type {
   AssistantMessageNode, CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot,
-  ModelRetryNode, RunningToolCall, SessionId, SessionListState, ToolResultNode, TurnErrorNode,
+  ModelRetryNode, RunningToolCall, SessionId, SessionListState, ToolCallBlock, ToolResultNode, TurnErrorNode,
   UserMessageNode, WorkspaceListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { createSnapshotStore, PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
-import type { ChatViewSlotProps, SelectionTarget, ToolTreeOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type {
+  ChatNode, ChatNodeOwnerProps, ChatNodeViewProps, ChatViewSlotProps, SelectionTarget, UseChatNodeTurnData,
+} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { createChatStore } from '../src/client/stores.ts'
 import { ChatView } from '../src/client/chat/ChatView.tsx'
 import { zh } from '../src/client/locales.ts'
-import { assistantActionsSeqs, assistantBranchSeqs, deriveChatFlow, flowKeys, runningTurnStartTime } from '../src/client/chat/chat-flow.ts'
+import { AssistantNodeView } from '../src/client/chat/AssistantNodeView.tsx'
+import { CommandNodeView, ManualCompactionNodeView } from '../src/client/chat/CommandNodeView.tsx'
+import {
+  CompactionNodeView, ContextMessageNodeView, RetryNodeView, TurnErrorNodeView,
+  UnknownNodeView, UserMessageNodeView,
+} from '../src/client/chat/MessageItem.tsx'
+import { TurnTailNodeView } from '../src/client/chat/TurnTailNodeView.tsx'
 import { formatRunDuration } from '../src/client/chat/message-chrome.ts'
+import { chatSnapshotFixture } from './chat-snapshot-fixture.ts'
 
 afterEach(() => {
   cleanup()
@@ -34,10 +43,11 @@ beforeEach(() => {
 })
 
 const SID = 's1' as SessionId
+type RoutedChatNodeOwner = ChatNodeOwnerProps & { readonly node: ChatNode }
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: chatSnapshotFixture(), nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
@@ -45,11 +55,21 @@ function snapshotBase(): ConversationSnapshot {
 
 /** Scripted snapshot source: set() swaps the top-level object like the real Session. */
 function makeSource(init?: Partial<ConversationSnapshot>) {
-  let snap: ConversationSnapshot = { ...snapshotBase(), ...init }
+  const initial = { ...snapshotBase(), ...init }
+  let snap: ConversationSnapshot = {
+    ...initial,
+    chat: init?.chat ?? chatSnapshotFixture(initial),
+  }
   const subs = new Set<() => void>()
   return {
     set: (next: Partial<ConversationSnapshot>) => {
-      snap = { ...snap, ...next }
+      const merged = { ...snap, ...next }
+      snap = {
+        ...merged,
+        chat: Object.hasOwn(next, 'chat') && next.chat !== undefined
+          ? next.chat
+          : chatSnapshotFixture(merged, snap.chat),
+      }
       for (const fn of [...subs]) fn()
     },
     source: {
@@ -73,7 +93,8 @@ const assistant = (seq: number, text: string, turn = 1): AssistantMessageNode =>
   kind: 'assistant', seq, time: seq * 1_000, turn, step: 1, blocks: [{ kind: 'text', text }],
 })
 const retry = (seq: number): ModelRetryNode => ({
-  kind: 'model-retry', seq, time: seq * 1_000, turn: 1, step: 0,
+  kind: 'model-retry', retryId: 'chat-view-retry' as ModelRetryNode['retryId'],
+  seq, time: seq * 1_000, turn: 1, step: 0,
   retryState: 'scheduled',
   provider: 'mock', mode: 'normal', policyKey: 'mock-normal',
   retry: 1, maxRetries: 2, delayMs: 450,
@@ -139,25 +160,97 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
   // production; the view reads it through the PropsStore useStore share).
   const chat = createChatStore().create()
   const t = makeTranslate(zh, commonZh)
-  const toolOwners: ToolTreeOwnerProps[] = []
-  const renderSlot = ((key: string, owner: object, opts?: { fallback?: React.ReactNode }) => {
-    if (key !== 'conversation.chat.tool') return opts?.fallback ?? null
-    const tool = owner as ToolTreeOwnerProps
-    toolOwners.push(tool)
-    // Tool providers own their subtree. The host double carries only the
-    // semantic anchor required by ChatView's prepend-position contract.
-    return (
-      <div
-        data-testid={`tool-seat-${tool.callId}`}
-        data-chat-anchor-key={`call:${tool.callId}`}
-        data-chat-call-id={tool.callId}
-      >
-        {tool.toolName || '(unnamed)'}:{tool.callId}
-      </div>
+  const toolOwners: Array<{
+    callId: string
+    toolName: string
+    block: ToolCallBlock
+    selectedCallId: string | undefined
+    openFile: ChatNodeOwnerProps['openFile']
+    inspectCall: ChatNodeOwnerProps['inspectCall']
+  }> = []
+  const renderCommandSlot = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
+    opts?.fallback ?? null) as unknown as React.ComponentProps<typeof CommandNodeView>['renderSlot']
+  const renderTurnTail = ((_key: string, _owner: object) => null) as unknown as
+    React.ComponentProps<typeof TurnTailNodeView>['renderSlotChain']
+  const renderTurnTailSlot = (() => null) as unknown as
+    React.ComponentProps<typeof TurnTailNodeView>['renderSlot']
+  const renderSlot = ((key: string, owner: object, opts?: {
+    fallback?: React.ReactNode
+    hookContext?: unknown
+  }) => {
+    if (key !== 'conversation.chat.node') return opts?.fallback ?? null
+    const nodeOwner = owner as RoutedChatNodeOwner
+    const nodeKey = opts?.hookContext as string | undefined
+    const useTurnData = ((dataKey: string) => props.useSession((snapshot) => {
+      const location = nodeKey === undefined ? undefined : snapshot.chat.nodes.get(nodeKey)?.location
+      return location?.kind === 'turn' || location?.kind === 'step'
+        ? location.turn.data.get(dataKey as never)
+        : undefined
+    })) as UseChatNodeTurnData
+    const nodeProps = <Kind extends ChatNode['kind']>(): ChatNodeViewProps<Kind> => (
+      { ...props, ...nodeOwner, useTurnData } as unknown as ChatNodeViewProps<Kind>
     )
+    switch (nodeOwner.node.kind) {
+      case 'user':
+      case 'steering':
+        return <UserMessageNodeView {...nodeProps<'user' | 'steering'>()} />
+      case 'context':
+        return <ContextMessageNodeView {...nodeProps<'context'>()} />
+      case 'assistant-step':
+        return <AssistantNodeView {...nodeProps<'assistant-step'>()} />
+      case 'command':
+        return (
+          <CommandNodeView
+            {...nodeProps<'command'>()}
+            renderSlot={renderCommandSlot}
+            SessionProvider={props.SessionProvider}
+          />
+        )
+      case 'manual-compaction':
+        return <ManualCompactionNodeView {...nodeProps<'manual-compaction'>()} />
+      case 'compaction':
+        return <CompactionNodeView {...nodeProps<'compaction'>()} />
+      case 'model-retry':
+        return <RetryNodeView {...nodeProps<'model-retry'>()} />
+      case 'turn-error':
+        return <TurnErrorNodeView {...nodeProps<'turn-error'>()} />
+      case 'turn-tail':
+        return (
+          <TurnTailNodeView
+            {...nodeProps<'turn-tail'>()}
+            renderSlot={renderTurnTailSlot}
+            renderSlotChain={renderTurnTail}
+            SessionProvider={props.SessionProvider}
+          />
+        )
+      case 'unknown':
+        return <UnknownNodeView {...nodeProps<'unknown'>()} />
+      case 'tool-call': {
+        const block = (nodeOwner.node.data as { readonly root: ToolCallBlock }).root
+        const toolName = 'kind' in block ? block.call?.name ?? '' : block.name
+        const tool = {
+          callId: block.callId,
+          toolName,
+          block,
+          selectedCallId: nodeOwner.selectedCallId,
+          openFile: nodeOwner.openFile,
+          inspectCall: nodeOwner.inspectCall,
+        }
+        toolOwners.push(tool)
+        return (
+          <div
+            data-testid={`tool-seat-${tool.callId}`}
+            data-chat-anchor-key={`call:${tool.callId}`}
+            data-chat-call-id={tool.callId}
+          >
+            {tool.toolName || '(unnamed)'}:{tool.callId}
+          </div>
+        )
+      }
+      default:
+        return opts?.fallback ?? null
+    }
   }) as unknown as ChatViewSlotProps['renderSlot']
-  const renderSlotChain = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
-    opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlotChain']
   // SessionProvider seat arrives with the session-scope child declaration;
   // ChatView never invokes it (render-prop pass-through stub).
   const SessionProviderStub: ChatViewSlotProps['SessionProvider'] = ({ children }) => <>{children(SID)}</>
@@ -172,7 +265,6 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     useStore: bindSnapshotSelector(chat),
     actions: chat.actions,
     renderSlot,
-    renderSlotChain,
     SessionProvider: SessionProviderStub,
     openDetails,
     openFile,
@@ -218,139 +310,7 @@ function installScrollMetrics(element: HTMLElement, initialHeight: number, clien
   }
 }
 
-describe('chat-flow derivation', () => {
-  it('groups consecutive tool results and keeps stable keys', () => {
-    const nodes: ConversationNode[] = [
-      user(1, 'hi'), assistant(2, 'let me look'), toolResult(3, 'a'), toolResult(4, 'b'),
-      assistant(5, 'found'), toolResult(6, 'c'),
-    ]
-    const items = deriveChatFlow(nodes)
-    expect(items.map(i => i.kind)).toEqual(['node', 'node', 'tool-group', 'node', 'tool-group'])
-    const group = items[2]!
-    expect(group.kind === 'tool-group' && group.results.map(r => r.callId)).toEqual(['a', 'b'])
-    expect(flowKeys(items)).toBe('n1|n2|g3|n5|g6')
-    expect(flowKeys(deriveChatFlow([...nodes, toolResult(7, 'd')]))).toBe('n1|n2|g3|n5|g6')
-  })
-
-  it('reuses one stable row for consecutive retry turns', () => {
-    const first = retry(2)
-    const second = { ...retry(3), turn: 2, retry: 2 }
-    const initial = deriveChatFlow([user(1, 'try'), first])
-    const updated = deriveChatFlow([user(1, 'try'), first, second])
-    expect(flowKeys(initial)).toBe('n1|n2')
-    expect(flowKeys(updated)).toBe('n1|n2')
-    expect(updated).toHaveLength(2)
-    expect(updated[1]?.kind === 'node' && updated[1].node).toBe(second)
-  })
-
-  it('folds a successful /compact lifecycle into its explicitly linked checkpoint', () => {
-    const running = command({
-      seq: 1,
-      commandId: 'cmd-compact' as CommandNode['commandId'],
-      name: 'compact',
-      outcome: null,
-    })
-    expect(flowKeys(deriveChatFlow([user(0, 'before'), running]))).toBe('n0|ccmd-compact')
-
-    const settled = {
-      ...running,
-      outcome: { kind: 'success' as const, text: 'Compacted 16 history items.', sourceEventSeq: 3 },
-    }
-    const checkpoint = compaction({ seq: 4, summaryEventSeq: 3 })
-    const items = deriveChatFlow([user(0, 'before'), settled, user(2, 'injected while compacting'), checkpoint])
-    expect(flowKeys(items)).toBe('n0|n2|ccmd-compact')
-    expect(items.at(-1)).toEqual({
-      kind: 'command-compaction',
-      key: 'ccmd-compact',
-      command: settled,
-      compaction: checkpoint,
-    })
-  })
-
-  it('does not split adjacent tool results around a folded /compact command', () => {
-    const folded = command({
-      seq: 2,
-      commandId: 'cmd-compact' as CommandNode['commandId'],
-      name: 'compact',
-      outcome: { kind: 'success', sourceEventSeq: 4 },
-    })
-    const items = deriveChatFlow([
-      toolResult(1, 'a'),
-      folded,
-      toolResult(3, 'b'),
-      compaction({ seq: 5, summaryEventSeq: 4 }),
-    ])
-    expect(flowKeys(items)).toBe('g1|ccmd-compact')
-    expect(
-      items[0]?.kind === 'tool-group' && items[0].results.map(result => result.callId),
-    ).toEqual(['a', 'b'])
-  })
-
-  it('keeps automatic, unlinked, and ambiguously linked compactions as separate rows', () => {
-    const automatic = compaction({ seq: 2, summaryEventSeq: 1 })
-    expect(flowKeys(deriveChatFlow([automatic]))).toBe('n2')
-
-    const first = command({
-      seq: 3,
-      commandId: 'cmd-a' as CommandNode['commandId'],
-      name: 'compact',
-      outcome: { kind: 'success', sourceEventSeq: 9 },
-    })
-    const second = command({
-      seq: 4,
-      commandId: 'cmd-b' as CommandNode['commandId'],
-      name: 'compact',
-      outcome: { kind: 'success', sourceEventSeq: 9 },
-    })
-    const ambiguous = compaction({ seq: 10, summaryEventSeq: 9 })
-    expect(flowKeys(deriveChatFlow([first, second, ambiguous]))).toBe('ccmd-a|ccmd-b|n10')
-
-    const sole = command({
-      seq: 11,
-      commandId: 'cmd-sole' as CommandNode['commandId'],
-      name: 'compact',
-      outcome: { kind: 'success', sourceEventSeq: 12 },
-    })
-    const duplicateA = compaction({ seq: 13, summaryEventSeq: 12 })
-    const duplicateB = compaction({ seq: 14, summaryEventSeq: 12 })
-    expect(flowKeys(deriveChatFlow([sole, duplicateA, duplicateB]))).toBe('ccmd-sole|n13|n14')
-  })
-
-  it('skips render-nothing assistant nodes so tool runs stay one group', () => {
-    // A tool-call-only step message (and blank text/reasoning) renders nothing:
-    // it must not split the run into two groups with an empty line between.
-    const headsOnly: AssistantMessageNode = {
-      kind: 'assistant', seq: 4, time: 4_000, turn: 1, step: 2,
-      blocks: [{ kind: 'tool-call', callId: 'b', name: 'read', argsRaw: '{}' }, { kind: 'text', text: ' \n' }, { kind: 'reasoning', text: '' }],
-    }
-    const items = deriveChatFlow([toolResult(3, 'a'), headsOnly, toolResult(5, 'b')])
-    expect(flowKeys(items)).toBe('g3')
-    const group = items[0]!
-    expect(group.kind === 'tool-group' && group.results.map(r => r.callId)).toEqual(['a', 'b'])
-    // Interrupted and visible-content nodes still render (已停止 marker / prose).
-    expect(flowKeys(deriveChatFlow([toolResult(3, 'a'), { ...headsOnly, interrupted: true }, toolResult(5, 'b')]))).toBe('g3|n4|g5')
-    expect(flowKeys(deriveChatFlow([toolResult(3, 'a'), assistant(4, 'found'), toolResult(5, 'b')]))).toBe('g3|n4|g5')
-  })
-
-  it('assistantActionsSeqs keeps only the last content assistant per completed turn', () => {
-    const thinkOnly: AssistantMessageNode = {
-      kind: 'assistant', seq: 3, time: 3_000, turn: 1, step: 2,
-      blocks: [{ kind: 'reasoning', text: 'planning' }],
-    }
-    const nodes: ConversationNode[] = [
-      user(1, 'hi'),
-      assistant(2, 'looking', 1),
-      thinkOnly,
-      toolResult(4, 'a'),
-      assistant(5, 'done', 1),
-      user(6, 'again'),
-      assistant(7, 'second turn', 2),
-    ]
-    expect([...assistantActionsSeqs(nodes, new Map([[1, 5], [2, 7]]))].sort((a, b) => a - b)).toEqual([5, 7])
-    // Turn 2 is still producing steps: its latest narration owns nothing, and
-    // the settled turn 1 keeps its seat.
-    expect([...assistantActionsSeqs(nodes, new Map([[1, 5]]))]).toEqual([5])
-  })
+describe('Chat node rendering', () => {
 
   it('threads the injected file-mention vocabulary into the closing prose only', () => {
     const wrote = (seq: number, callId: string, path: string): ToolResultNode => ({
@@ -391,17 +351,6 @@ describe('chat-flow derivation', () => {
     expect(h.openFile).toHaveBeenCalledWith('for-seq-4/site/report.html')
   })
 
-  it('runningTurnStartTime selects the latest turn/start without a turn/end', () => {
-    expect(runningTurnStartTime(new Map([
-      [1, { startTime: 1_000, endTime: 5_000 }],
-      [2, { startTime: 6_000 }],
-    ]))).toBe(6_000)
-    expect(runningTurnStartTime(new Map([
-      [1, { startTime: 1_000, endTime: 5_000 }],
-      [2, { startTime: 6_000, endTime: 9_000 }],
-    ]))).toBeNull()
-  })
-
   it('formatRunDuration localizes units and floors partial seconds', () => {
     const t = makeTranslate(zh, commonZh)
     expect(formatRunDuration(0, t)).toBe('0秒')
@@ -410,24 +359,6 @@ describe('chat-flow derivation', () => {
     expect(formatRunDuration(125_000, t)).toBe('2分05秒')
   })
 
-  it('assistantBranchSeqs keeps only content-assistant tails; user/steering tails own no branch', () => {
-    const interruptedThink: AssistantMessageNode = {
-      kind: 'assistant', seq: 4.1, time: 4_100, turn: 1, step: 2,
-      blocks: [{ kind: 'reasoning', text: 'bad path' }], interrupted: true,
-    }
-    const nodes: ConversationNode[] = [
-      user(1, 'first'),
-      assistant(2, 'answer before tools'),
-      toolResult(3, 'a'),
-      interruptedThink,
-      user(6, 'second'),
-      assistant(7, 'clean tail', 2),
-      user(10, 'user-only tail'),
-      user(13, 'steering tail'),
-    ]
-    const seqs = assistantBranchSeqs(nodes, new Map([[1, 5], [2, 8], [3, 11], [4, 14]]))
-    expect([...seqs]).toEqual([7])
-  })
 })
 
 describe('ChatView', () => {
@@ -444,8 +375,8 @@ describe('ChatView', () => {
     const h = makeHarness({ nodes: [user(9, 'first visible'), user(10, 'next visible')], hasMore: true })
     const view = render(<h.ChatView {...h.props} />)
     const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
-    const first = view.container.querySelector('[data-chat-flow-key="n9"]') as HTMLDivElement
-    const next = view.container.querySelector('[data-chat-flow-key="n10"]') as HTMLDivElement
+    const first = view.container.querySelector('[data-chat-flow-key="fixture:user:9"]') as HTMLDivElement
+    const next = view.container.querySelector('[data-chat-flow-key="fixture:user:10"]') as HTMLDivElement
     let firstTop = 100
     let nextTop = 300
     vi.spyOn(scroller, 'getBoundingClientRect').mockImplementation(
@@ -472,7 +403,7 @@ describe('ChatView', () => {
     expect(scroller.scrollTop).toBe(590) // latest 90 + the anchored row's 500px prepend shift
   })
 
-  it('renders the fixture main line: bubble, narration, grouped tool rows', () => {
+  it('renders the fixture main line as independently keyed business nodes', () => {
     const h = makeHarness({
       nodes: [user(1, 'do the thing'), assistant(2, 'running tools'), toolResult(3, 'a'), toolResult(4, 'b')],
     })
@@ -485,14 +416,18 @@ describe('ChatView', () => {
       key: row.getAttribute('data-chat-flow-key'),
       kind: row.getAttribute('data-chat-flow-kind'),
     }))).toEqual([
-      { key: 'n1', kind: 'user' },
-      { key: 'n2', kind: 'assistant' },
-      { key: 'g3', kind: 'tool-group' },
+      { key: 'fixture:user:1', kind: 'user' },
+      { key: 'fixture:assistant:2', kind: 'assistant-step' },
+      { key: 'fixture:tool:a', kind: 'tool-call' },
+      { key: 'fixture:tool:b', kind: 'tool-call' },
     ])
     expect([...view.container.querySelectorAll('[data-chat-call-id]')].map(row => row.getAttribute('data-chat-call-id')))
       .toEqual(['a', 'b'])
     expect([...view.container.querySelectorAll('[data-chat-anchor-key]')].map(row => row.getAttribute('data-chat-anchor-key')))
-      .toEqual(['node:1', 'node:2', 'call:a', 'call:b'])
+      .toEqual([
+        'fixture:user:1', 'fixture:assistant:2',
+        'fixture:tool:a', 'call:a', 'fixture:tool:b', 'call:b',
+      ])
   })
 
   it('renders Host-pending steering at the flow tail and hands off to the durable node', () => {
@@ -559,14 +494,13 @@ describe('ChatView', () => {
     act(() => {
       h.set({ running: false, turnEnds: new Map([[1, 3]]) })
     })
-    // The completed turn's transcript tail is the steering bubble, not the
-    // narration, so the assistant's branch action stays unavailable and the
-    // steering bubble still offers none.
+    // The Turn Tail belongs to the closed Turn, independently of a later
+    // steering bubble's placement in the Chat list.
     const branchButtons = view.getAllByRole('button', { name: '在新对话中分支' })
     expect(branchButtons).toHaveLength(1)
-    expect(branchButtons[0]!.getAttribute('aria-disabled')).toBe('true')
+    expect(branchButtons[0]!.getAttribute('aria-disabled')).toBeNull()
     fireEvent.click(branchButtons[0]!)
-    expect(h.forkAt).not.toHaveBeenCalled()
+    expect(h.forkAt).toHaveBeenCalledWith(1)
   })
 
   it('keeps a later pending occurrence visible when it reuses a durable MessageId', () => {
@@ -607,7 +541,7 @@ describe('ChatView', () => {
     expect(within(disclosure).getByRole('status').textContent).toBe('正在重试模型请求（1/2） · 1s')
 
     act(() => {
-      h.set({ nodes: [user(1, 'try'), retryNode, nextRetry] })
+      h.set({ nodes: [user(1, 'try'), nextRetry] })
     })
     expect(within(disclosure).getAllByRole('status')).toHaveLength(1)
     expect(view.container.querySelector('details')).toBe(disclosure)
@@ -617,7 +551,6 @@ describe('ChatView', () => {
       h.set({
         nodes: [
           user(1, 'try'),
-          retryNode,
           { ...nextRetry, retryState: 'started' },
           context,
           assistant(5, 'done'),
@@ -760,7 +693,7 @@ describe('ChatView', () => {
       turnEnds: new Map([[1, 2]]),
     })
     const view = render(<h.ChatView {...h.props} />)
-    // One scope per message row; the CSS reveal keys off this attribute.
+    // The user row and the settled assistant's Turn Tail each own one clock scope.
     expect(view.container.querySelectorAll('[data-time-hover-root]')).toHaveLength(2)
   })
 
@@ -787,7 +720,7 @@ describe('ChatView', () => {
     expect(h.forkAt.mock.calls).toEqual([[2]])
   })
 
-  it('keeps branch visible but unavailable when tool and interrupted Think follow the response', () => {
+  it('keeps final content actions but disables branch when Tool and interrupted Think follow it', () => {
     const interruptedThink: AssistantMessageNode = {
       kind: 'assistant', seq: 4.1, time: 4_100, turn: 1, step: 2,
       blocks: [{ kind: 'reasoning', text: 'bad path' }], interrupted: true,
@@ -843,19 +776,13 @@ describe('ChatView', () => {
     expect(view.container.querySelectorAll('h1')).toHaveLength(2)
   })
 
-  it('streaming partial frames re-render only the tail (Profiler count)', () => {
+  it('streaming partial frames update the tail without replacing a sibling Tool row', () => {
     const h = makeHarness({
       nodes: [user(1, 'q'), assistant(2, 'old answer'), toolResult(3, 'a')],
     })
-    let renders = 0
-    const counting = (
-      <Profiler id="chat" onRender={() => { renders += 1 }}>
-        <h.ChatView {...h.props} />
-      </Profiler>
-    )
-    const view = render(counting)
-    const before = renders
-    const beforeHtml = view.container.querySelector('[class*="toolGroup"]')!.innerHTML
+    const view = render(<h.ChatView {...h.props} />)
+    const tool = view.getByTestId('tool-seat-a')
+    const beforeHtml = tool.innerHTML
     act(() => {
       h.set({ partial: { turn: 2, step: 1, blocks: [{ kind: 'text', text: 'streaming…' }] } })
     })
@@ -863,9 +790,8 @@ describe('ChatView', () => {
       h.set({ partial: { turn: 2, step: 1, blocks: [{ kind: 'text', text: 'streaming… more' }] } })
     })
     expect(view.getByText('streaming… more')).toBeTruthy()
-    // Each chunk commits exactly one profiler pass (the tail), never a full-tree storm.
-    expect(renders - before).toBe(2)
-    expect(view.container.querySelector('[class*="toolGroup"]')!.innerHTML).toBe(beforeHtml)
+    expect(view.getByTestId('tool-seat-a')).toBe(tool)
+    expect(tool.innerHTML).toBe(beforeHtml)
   })
 
   it('streaming leaves neighbor tool rows and history items at zero re-renders', () => {
@@ -875,8 +801,9 @@ describe('ChatView', () => {
     // Count renderSlot invocations: the memo boundary holds when CallRow does
     // not re-render, so the row's renderSlot call count freezes during chunks.
     let rowRenders = 0
-    h.props.renderSlot = ((key: string, _owner: object) => {
-      if (key !== 'conversation.chat.tool') return null
+    h.props.renderSlot = ((key: string, owner: object) => {
+      if (key !== 'conversation.chat.node'
+        || (owner as RoutedChatNodeOwner).node.kind !== 'tool-call') return null
       rowRenders += 1
       return <div data-testid="counting-row" />
     })
@@ -908,6 +835,54 @@ describe('ChatView', () => {
     expect(view.getByRole('status').textContent).toBe('Deep diving...')
   })
 
+  it('keeps the Tool renderer mounted when a running call settles into log order', () => {
+    const mounted = vi.fn()
+    const unmounted = vi.fn()
+    function StatefulToolNode({ node }: { readonly node: ChatNode<'tool-call'> }) {
+      useEffect(() => {
+        mounted()
+        return () => { unmounted() }
+      }, [])
+      const root = (node.data as { readonly root: ToolCallBlock }).root
+      return (
+        <div data-testid="stateful-tool" data-state={'kind' in root ? 'settled' : 'running'}>
+          {root.callId}
+        </div>
+      )
+    }
+
+    const h = makeHarness({
+      nodes: [user(1, 'q'), assistant(4, 'later')],
+      runningCalls: [runningCall('r1')],
+      running: true,
+    })
+    h.props.renderSlot = ((key: string, owner: object, opts?: { fallback?: React.ReactNode }) => {
+      const routed = owner as RoutedChatNodeOwner
+      return key === 'conversation.chat.node' && routed.node.kind === 'tool-call'
+        ? <StatefulToolNode node={routed.node} />
+        : opts?.fallback ?? null
+    }) as ChatViewSlotProps['renderSlot']
+    const view = render(<h.ChatView {...h.props} />)
+    const tool = view.getByTestId('stateful-tool')
+    const row = view.container.querySelector('[data-chat-flow-key="fixture:tool:r1"]')
+    expect(tool.dataset.state).toBe('running')
+    expect(mounted).toHaveBeenCalledTimes(1)
+
+    act(() => {
+      h.set({
+        nodes: [user(1, 'q'), toolResult(3, 'r1'), assistant(4, 'later')],
+        runningCalls: [],
+        running: false,
+      })
+    })
+
+    expect(view.getByTestId('stateful-tool')).toBe(tool)
+    expect(view.container.querySelector('[data-chat-flow-key="fixture:tool:r1"]')).toBe(row)
+    expect(tool.dataset.state).toBe('settled')
+    expect(mounted).toHaveBeenCalledTimes(1)
+    expect(unmounted).not.toHaveBeenCalled()
+  })
+
   it('the running clock uses turn/start, ignores steering, and stays out of the live region', () => {
     const startTime = Date.now() - 125_000
     const trigger: UserMessageNode = { ...user(1, 'go'), time: startTime + 1 }
@@ -932,7 +907,7 @@ describe('ChatView', () => {
     expect(status.textContent).toMatch(/^Deep diving\.\.\.2分0\d秒$/)
   })
 
-  it('hands each ordered root call to the whole-Tool slot', () => {
+  it('hands each ordered root call to the keyed business-node slot', () => {
     const block = toolResult(3, 'a')
     const h = makeHarness({ nodes: [block] })
     const calls: { key: string; owner: object; entryKey?: string }[] = []
@@ -943,14 +918,14 @@ describe('ChatView', () => {
     render(<h.ChatView {...h.props} />)
     expect(calls).toHaveLength(1)
     expect(calls[0]).toMatchObject({
-      key: 'conversation.chat.tool',
-      owner: { callId: 'a', toolName: 'bash', selectedCallId: undefined },
+      key: 'conversation.chat.node',
+      owner: { node: { kind: 'tool-call' }, selectedCallId: undefined },
+      entryKey: 'tool-call',
     })
-    const owner = calls[0]?.owner as ToolTreeOwnerProps
-    expect(owner.block).toBe(block)
+    const owner = calls[0]?.owner as RoutedChatNodeOwner
+    expect((owner.node.data as { readonly root: ToolCallBlock }).root).toBe(block)
     expect(owner.openFile).toBe(h.openFile)
     expect(owner.inspectCall).toBe(h.inspectCall)
-    expect(calls[0]?.entryKey).toBeUndefined()
   })
 
   it('prepend preserves a semantic row; a trailing user node force-scrolls', () => {
@@ -960,7 +935,7 @@ describe('ChatView', () => {
     // jsdom has no layout: fake the metrics the anchor math reads.
     Object.defineProperty(scroller, 'scrollHeight', { value: 1000, writable: true })
     Object.defineProperty(scroller, 'clientHeight', { value: 400, writable: true })
-    const anchored = view.container.querySelector('[data-chat-flow-key="n5"]') as HTMLDivElement
+    const anchored = view.container.querySelector('[data-chat-flow-key="fixture:user:5"]') as HTMLDivElement
     let anchoredTop = 100
     vi.spyOn(anchored, 'getBoundingClientRect').mockImplementation(
       () => ({ top: anchoredTop, bottom: anchoredTop + 40 } as DOMRect),
@@ -977,60 +952,6 @@ describe('ChatView', () => {
     expect(scroller.scrollTop).toBe(1600)
   })
 
-  it('uses stable call identity when a prepend changes the tool-group key amid unrelated growth', () => {
-    const h = makeHarness({ nodes: [toolResult(5, 'late')], hasMore: true })
-    const view = render(<h.ChatView {...h.props} />)
-    const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
-    let prepended = false
-    const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
-      if (this.dataset.chatAnchorKey === 'call:late') {
-        const top = prepended ? 400 : 100
-        return { top, bottom: top + 40 } as DOMRect
-      }
-      return { top: 0, bottom: 200 } as DOMRect
-    })
-    try {
-      Object.defineProperty(scroller, 'scrollHeight', { value: 700, writable: true })
-      Object.defineProperty(scroller, 'clientHeight', { value: 200, writable: true })
-      readerScroll(scroller, 80)
-      fireEvent.click(view.getByText('加载更早'))
-      // Total height grows by 500, but only 300 belongs before the call row.
-      Object.defineProperty(scroller, 'scrollHeight', { value: 1_200, writable: true })
-      prepended = true
-      act(() => { h.set({ nodes: [toolResult(4, 'early'), toolResult(5, 'late')] }) })
-      expect(scroller.scrollTop).toBe(380)
-    } finally {
-      rect.mockRestore()
-    }
-  })
-
-  it('uses the latest retry identity when prepending an earlier retry changes the flow key', () => {
-    const h = makeHarness({ nodes: [retry(5)], hasMore: true })
-    const view = render(<h.ChatView {...h.props} />)
-    const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
-    let prepended = false
-    const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
-      if (this.dataset.chatAnchorKey === 'node:5') {
-        const top = prepended ? 400 : 100
-        return { top, bottom: top + 40 } as DOMRect
-      }
-      return { top: 0, bottom: 200 } as DOMRect
-    })
-    try {
-      Object.defineProperty(scroller, 'scrollHeight', { value: 700, writable: true })
-      Object.defineProperty(scroller, 'clientHeight', { value: 200, writable: true })
-      readerScroll(scroller, 80)
-      fireEvent.click(view.getByText('加载更早'))
-      Object.defineProperty(scroller, 'scrollHeight', { value: 1_200, writable: true })
-      prepended = true
-      act(() => { h.set({ nodes: [retry(4), retry(5)] }) })
-      expect(scroller.scrollTop).toBe(380)
-      expect(view.container.querySelector('[data-chat-flow-key="n4"][data-chat-anchor-key="node:5"]')).not.toBeNull()
-    } finally {
-      rect.mockRestore()
-    }
-  })
-
   it('back-to-bottom cancels an in-flight paging anchor', () => {
     const h = makeHarness({ nodes: [user(9, 'late')], hasMore: true })
     const view = render(<h.ChatView {...h.props} />)
@@ -1177,7 +1098,7 @@ describe('ChatView', () => {
       () => ({ top: 0, bottom: 500 } as DOMRect),
     )
     const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
-      if (this.dataset.chatAnchorKey === 'node:1') {
+      if (this.dataset.chatAnchorKey === 'fixture:user:1') {
         return { top: anchorTop, bottom: anchorTop + 40 } as DOMRect
       }
       return { top: 0, bottom: 40 } as DOMRect
@@ -1216,12 +1137,12 @@ describe('ChatView', () => {
     })
     document.body.appendChild(host)
     const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
-      if (this.dataset.chatAnchorKey === 'node:1') return { top: 300, bottom: 340 } as DOMRect
+      if (this.dataset.chatAnchorKey === 'fixture:user:1') return { top: 300, bottom: 340 } as DOMRect
       return { top: 0, bottom: 500 } as DOMRect
     })
     try {
       const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] })
-      h.chatScroll.save({ anchorKey: 'node:1', anchorTop: 80, scrollTop: 1_400 })
+      h.chatScroll.save({ anchorKey: 'fixture:user:1', anchorTop: 80, scrollTop: 1_400 })
       const view = render(<h.ChatView {...h.props} />, { container: host })
       expect(host.scrollTop).toBe(1_500)
       expect(h.chatScroll.read()).toBeNull()
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
new file mode 100644
index 0000000000..3ae906087e
--- /dev/null
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -0,0 +1,720 @@
+import { describe, expect, it } from 'vitest'
+import type {
+  ChatConversationViewNode, ChatSnapshot, ConversationEventInput,
+  ConversationNodeDefinition, ConversationViewDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { ConversationNodeAssembler } from '@deepseek-ai/dsh-client-runtime/client'
+import { assistantDefinition } from '../src/client/conversation-nodes/assistant.ts'
+import { chatViewDefinition } from '../src/client/conversation-nodes/chat-snapshot-builder.ts'
+import { commandDefinition } from '../src/client/conversation-nodes/command.ts'
+import { compactionDefinition } from '../src/client/conversation-nodes/compaction.ts'
+import { unknownFallbackDefinition } from '../src/client/conversation-nodes/fallback.ts'
+import { nextStepInboxDefinition, nextTurnInboxDefinition } from '../src/client/conversation-nodes/inbox.ts'
+import { messageDefinition } from '../src/client/conversation-nodes/message.ts'
+import { retryDefinition } from '../src/client/conversation-nodes/retry.ts'
+import { toolDefinition } from '../src/client/conversation-nodes/tool.ts'
+import { turnErrorDefinition } from '../src/client/conversation-nodes/turn-error.ts'
+import { turnTailDefinition } from '../src/client/conversation-nodes/turn-tail.ts'
+import type {
+  AssistantChatData, ManualCompactionChatData, RetryChatData, ToolChatData,
+} from '../src/client/contract/chat-nodes.ts'
+
+const DEFINITIONS: readonly ConversationNodeDefinition[] = [
+  nextTurnInboxDefinition,
+  nextStepInboxDefinition,
+  messageDefinition,
+  assistantDefinition,
+  toolDefinition,
+  commandDefinition,
+  compactionDefinition,
+  retryDefinition,
+  turnErrorDefinition,
+  turnTailDefinition,
+]
+
+class TestEventDefinitions {
+  entries(): readonly ConversationNodeDefinition[] {
+    return DEFINITIONS
+  }
+
+  fallbackEntry(): ConversationNodeDefinition {
+    return unknownFallbackDefinition
+  }
+}
+
+class TestViewDefinitions {
+  entries(): readonly ConversationViewDefinition[] {
+    return [chatViewDefinition]
+  }
+}
+
+function at(
+  seq: number,
+  type: string,
+  data: unknown,
+  extra: Record<string, unknown> = {},
+): ConversationEventInput {
+  return {
+    event: {
+      seq,
+      time: 1_700_000_000_000 + seq,
+      type,
+      data,
+      ...extra,
+    } as unknown as ConversationEventInput['event'],
+    view: undefined,
+  }
+}
+
+function assembler(entries: readonly ConversationEventInput[] = [], hasMore = false): ConversationNodeAssembler {
+  const value = new ConversationNodeAssembler(new TestEventDefinitions(), new TestViewDefinitions())
+  value.replaceWindow(entries, hasMore)
+  value.flush()
+  return value
+}
+
+function snapshot(value: ConversationNodeAssembler): ChatSnapshot {
+  const current = value.snapshot('chat') as ChatSnapshot | undefined
+  if (current === undefined) throw new Error('chat view was not registered')
+  return current
+}
+
+function node(value: ChatSnapshot, kind: string): ChatConversationViewNode | undefined {
+  return value.nodes.values().find(candidate => candidate.kind === kind)
+}
+
+function textMessage(id: string, text: string) {
+  return {
+    id,
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  }
+}
+
+function assistantMessage(id: string, text: string) {
+  return {
+    id,
+    role: 'assistant',
+    content: [{ type: 'text', text }],
+    source: { kind: 'model', provider: 'fake', model: 'fake' },
+  }
+}
+
+function toolResult(callId: string, text: string) {
+  return {
+    id: `result-${callId}`,
+    role: 'user',
+    source: { kind: 'tool', callId },
+    content: [{
+      type: 'tool-result',
+      toolCallId: callId,
+      content: [{ type: 'text', text }],
+      isError: false,
+    }],
+  }
+}
+
+describe('built-in conversation node Definitions', () => {
+  it('keeps one keyed Assistant node while streaming settles and materializes interruption from Location', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'assistant/chunk', {
+        turn: 1,
+        step: 1,
+        chunk: { type: 'text-delta', index: 0, text: 'streaming' },
+      }),
+    ])
+    const runningSnapshot = snapshot(value)
+    const running = node(runningSnapshot, 'assistant-step')
+    expect(running?.data).toMatchObject({ status: 'running', blocks: [{ kind: 'text', text: 'streaming' }] })
+    const order = runningSnapshot.order
+
+    value.append(at(4, 'assistant/message', {
+      turn: 1,
+      step: 1,
+      message: assistantMessage('assistant-1', 'settled'),
+    }, { surfaceOp: 'append' }))
+    value.flush()
+
+    const settledSnapshot = snapshot(value)
+    const settled = node(settledSnapshot, 'assistant-step')
+    expect(settled?.key).toBe(running?.key)
+    expect(settledSnapshot.order).toBe(order)
+    expect(settled?.data).toMatchObject({ status: 'settled', blocks: [{ kind: 'text', text: 'settled' }] })
+
+    const interruptedValue = assembler([
+      at(10, 'turn/start', { turn: 2 }),
+      at(11, 'step/start', { turn: 2, step: 1 }),
+      at(12, 'assistant/chunk', {
+        turn: 2,
+        step: 1,
+        chunk: { type: 'text-delta', index: 0, text: 'partial' },
+      }),
+      at(13, 'step/end', { turn: 2, step: 1 }),
+    ])
+    const interrupted = node(snapshot(interruptedValue), 'assistant-step')
+    expect(interrupted?.data).toMatchObject({ status: 'interrupted' })
+    expect((interrupted?.data as AssistantChatData).finalNode?.interrupted).toBe(true)
+
+    const hiddenValue = assembler([
+      at(20, 'turn/start', { turn: 3 }),
+      at(21, 'step/start', { turn: 3, step: 1 }),
+      at(22, 'llm/retry', {
+        retryId: 'retry-hidden',
+        turn: 3,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 1,
+        maxRetries: 2,
+        delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'temporary' },
+      }),
+    ])
+    expect(node(snapshot(hiddenValue), 'assistant-step')).toBeUndefined()
+
+    const toolOnlyValue = assembler([
+      at(30, 'turn/start', { turn: 4 }),
+      at(31, 'step/start', { turn: 4, step: 1 }),
+      at(32, 'assistant/chunk', {
+        turn: 4,
+        step: 1,
+        chunk: { type: 'tool-call-delta', index: 0, id: 'call-1', name: 'read', argumentsDelta: '' },
+      }),
+      at(33, 'assistant/message', {
+        turn: 4,
+        step: 1,
+        message: {
+          ...assistantMessage('assistant-tool-only', ''),
+          content: [{ type: 'tool-call', id: 'call-1', name: 'read', arguments: '{}' }],
+        },
+      }, { surfaceOp: 'append' }),
+    ])
+    const toolOnlySnapshot = snapshot(toolOnlyValue)
+    expect(toolOnlySnapshot.order).toEqual([])
+    expect(node(toolOnlySnapshot, 'assistant-step')?.visibility).toBe('hidden')
+    expect(toolOnlySnapshot.legacy.nodes).toMatchObject([{
+      kind: 'assistant',
+      seq: 33,
+      timing: { firstTokenTime: 1_700_000_000_032 },
+    }])
+
+    const interruptedToolOnlyValue = assembler([
+      at(35, 'turn/start', { turn: 5 }),
+      at(36, 'step/start', { turn: 5, step: 1 }),
+      at(37, 'assistant/chunk', {
+        turn: 5,
+        step: 1,
+        chunk: { type: 'tool-call-delta', index: 0, id: 'call-2', name: 'read', argumentsDelta: '' },
+      }),
+      at(38, 'step/end', { turn: 5, step: 1 }),
+    ])
+    const interruptedToolOnly = node(snapshot(interruptedToolOnlyValue), 'assistant-step')
+    expect(interruptedToolOnly?.visibility).toBe('visible')
+    expect(interruptedToolOnly?.data).toMatchObject({ status: 'interrupted' })
+
+    const retryTimingValue = assembler([
+      at(50, 'turn/start', { turn: 6 }),
+      at(51, 'step/start', { turn: 6, step: 1 }),
+      at(52, 'assistant/chunk', {
+        turn: 6,
+        step: 1,
+        chunk: { type: 'text-delta', index: 0, text: 'first attempt' },
+      }),
+      at(53, 'llm/retry', {
+        retryId: 'retry-timing', turn: 6, step: 1, provider: 'fake', mode: 'normal',
+        policyKey: 'fake-normal', retry: 1, maxRetries: 2, delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'temporary' },
+      }),
+      at(54, 'assistant/chunk', {
+        turn: 6,
+        step: 1,
+        chunk: { type: 'text-delta', index: 0, text: 'second attempt' },
+      }),
+      at(55, 'assistant/message', {
+        turn: 6,
+        step: 1,
+        message: assistantMessage('assistant-retried', 'done'),
+      }, { surfaceOp: 'append' }),
+    ])
+    const retryTiming = (node(snapshot(retryTimingValue), 'assistant-step')?.data as AssistantChatData).finalNode
+    expect(retryTiming?.timing?.firstTokenTime).toBe(1_700_000_000_052)
+
+    const partialWindow = assembler([
+      at(40, 'assistant/chunk', {
+        turn: 5,
+        step: 2,
+        chunk: { type: 'text-delta', index: 0, text: 'loaded partial' },
+      }),
+      at(41, 'step/end', { turn: 5, step: 2 }),
+    ], true)
+    const recovered = node(snapshot(partialWindow), 'assistant-step')
+    expect(recovered?.data).toMatchObject({
+      status: 'interrupted',
+      blocks: [{ kind: 'text', text: 'loaded partial' }],
+    })
+  })
+
+  it('keeps one keyed Tool node from running through settlement and replays nested dispatch after prepend', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'tool/call', { turn: 1, step: 1, callId: 'root', name: 'code', arguments: '{}' }),
+    ])
+    const runningSnapshot = snapshot(value)
+    const running = node(runningSnapshot, 'tool-call')
+    expect((running?.data as ToolChatData).root).toMatchObject({ callId: 'root', name: 'code' })
+    const order = runningSnapshot.order
+
+    value.append(at(4, 'tool/result', {
+      turn: 1,
+      step: 1,
+      message: toolResult('root', 'done'),
+    }, { surfaceOp: 'append' }))
+    value.flush()
+
+    const settledSnapshot = snapshot(value)
+    const settled = node(settledSnapshot, 'tool-call')
+    expect(settled?.key).toBe(running?.key)
+    expect(settledSnapshot.order).toBe(order)
+    expect((settled?.data as ToolChatData).root).toMatchObject({ kind: 'tool-result', callId: 'root' })
+
+    const history = assembler([
+      at(14, 'tool/code-dispatch-start', {
+        rootCallId: 'history-root',
+        parentCallId: 'history-root',
+        subCallId: 'child',
+        name: 'read',
+        arguments: { path: 'README.md' },
+      }),
+      at(15, 'tool/code-dispatch', {
+        rootCallId: 'history-root',
+        parentCallId: 'history-root',
+        subCallId: 'child',
+        name: 'read',
+        arguments: { path: 'README.md' },
+        isError: false,
+        content: [{ type: 'text', text: 'contents' }],
+      }),
+      at(16, 'tool/result', {
+        turn: 2,
+        step: 1,
+        message: toolResult('history-root', 'root done'),
+      }, { surfaceOp: 'append' }),
+    ], true)
+    const before = node(snapshot(history), 'tool-call')
+    expect((before?.data as ToolChatData).root.subCalls).toMatchObject([
+      { kind: 'tool-result', callId: 'child', call: { name: 'read' } },
+    ])
+
+    history.prepend([
+      at(10, 'turn/start', { turn: 2 }),
+      at(11, 'step/start', { turn: 2, step: 1 }),
+      at(13, 'tool/call', {
+        turn: 2,
+        step: 1,
+        callId: 'history-root',
+        name: 'code',
+        arguments: '{}',
+      }),
+    ], false)
+    history.flush()
+
+    const after = node(snapshot(history), 'tool-call')
+    expect(after?.key).toBe(before?.key)
+    expect((after?.data as ToolChatData).root.subCalls).toMatchObject([
+      { kind: 'tool-result', callId: 'child', call: { name: 'read' } },
+    ])
+
+    const firstChild = (after?.data as ToolChatData).root.subCalls[0]
+    history.append(at(17, 'tool/code-dispatch-start', {
+      rootCallId: 'history-root',
+      parentCallId: 'history-root',
+      subCallId: 'second-child',
+      name: 'write',
+      arguments: { path: 'out.txt' },
+    }))
+    history.flush()
+    const withSecondChild = node(snapshot(history), 'tool-call')
+    expect((withSecondChild?.data as ToolChatData).root.subCalls[0]).toBe(firstChild)
+  })
+
+  it('prepends an older turn without replacing already materialized nodes', () => {
+    const value = assembler([
+      at(20, 'turn/start', { turn: 2 }),
+      at(21, 'user/message', textMessage('newer-user', 'newer'), { surfaceOp: 'append' }),
+      at(22, 'step/start', { turn: 2, step: 1 }),
+      at(23, 'assistant/message', {
+        turn: 2,
+        step: 1,
+        message: assistantMessage('newer-assistant', 'newer answer'),
+      }, { surfaceOp: 'append' }),
+      at(24, 'step/end', { turn: 2, step: 1 }),
+      at(25, 'turn/end', { turn: 2, reason: { kind: 'completed' } }),
+    ], true)
+    const before = snapshot(value)
+    const existing = before.nodes.get(before.order.find(key => before.nodes.get(key)?.kind === 'assistant-step') ?? '')
+    const store = before.nodes
+
+    value.prepend([
+      at(10, 'turn/start', { turn: 1 }),
+      at(11, 'user/message', textMessage('older-user', 'older'), { surfaceOp: 'append' }),
+      at(12, 'step/start', { turn: 1, step: 1 }),
+      at(13, 'assistant/message', {
+        turn: 1,
+        step: 1,
+        message: assistantMessage('older-assistant', 'older answer'),
+      }, { surfaceOp: 'append' }),
+      at(14, 'step/end', { turn: 1, step: 1 }),
+      at(15, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+    ], false)
+    value.flush()
+
+    const after = snapshot(value)
+    expect(after.nodes).toBe(store)
+    expect(after.nodes.get(existing?.key ?? '')).toBe(existing)
+    expect(after.order).toHaveLength(before.order.length + 3)
+    expect(after.order.map(key => after.nodes.get(key)?.kind)).toEqual([
+      'user', 'assistant-step', 'turn-tail',
+      'user', 'assistant-step', 'turn-tail',
+    ])
+  })
+
+  it('appends a later turn without replacing nodes from the completed turn', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'user/message', textMessage('first-user', 'first'), { surfaceOp: 'append' }),
+      at(3, 'step/start', { turn: 1, step: 1 }),
+      at(4, 'assistant/message', {
+        turn: 1,
+        step: 1,
+        message: assistantMessage('first-assistant', 'first answer'),
+      }, { surfaceOp: 'append' }),
+      at(5, 'step/end', { turn: 1, step: 1 }),
+      at(6, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+    ])
+    const before = snapshot(value)
+    const oldOrder = before.order
+    const oldNodes = oldOrder.map(key => before.nodes.get(key))
+
+    value.append(at(7, 'turn/start', { turn: 2 }))
+    value.append(at(8, 'user/message', textMessage('second-user', 'second'), { surfaceOp: 'append' }))
+    value.flush()
+
+    const after = snapshot(value)
+    expect(after.nodes).toBe(before.nodes)
+    expect(after.order.slice(0, oldOrder.length)).toEqual(oldOrder)
+    expect(oldOrder.map(key => after.nodes.get(key))).toEqual(oldNodes)
+    expect(after.order.map(key => after.nodes.get(key)?.kind)).toEqual([
+      'user', 'assistant-step', 'turn-tail', 'user',
+    ])
+  })
+
+  it('replays inbox predecessors after prepend and reclassifies the dependent message as steering', () => {
+    const value = assembler([
+      at(3, 'user/message', textMessage('steer-1', 'change direction'), { surfaceOp: 'append' }),
+    ], true)
+    const before = node(snapshot(value), 'user')
+    expect(before).toBeDefined()
+
+    value.prepend([
+      at(1, 'agent/inbox/spliced', {
+        target: 'next-step',
+        start: 0,
+        inserted: [textMessage('steer-1', 'change direction')],
+      }),
+      at(2, 'agent/inbox/spliced', {
+        target: 'next-step',
+        start: 0,
+        removedCount: 1,
+        inserted: [],
+      }),
+    ], false)
+    value.flush()
+
+    const after = node(snapshot(value), 'steering')
+    expect(after?.key).toBe(before?.key)
+    expect(after?.data).toMatchObject({ kind: 'steering', messageId: 'steer-1' })
+    expect(node(snapshot(value), 'user')).toBeUndefined()
+  })
+
+  it('classifies appended producer context from durable source metadata', () => {
+    const value = assembler([
+      at(1, 'user/message', {
+        ...textMessage('skill-context', 'follow these instructions'),
+        source: { kind: 'skill-invocation', name: 'demo-skill', form: 'instructions' },
+      }, { surfaceOp: 'append' }),
+    ])
+
+    expect(node(snapshot(value), 'context')?.data).toMatchObject({
+      kind: 'context',
+      provenance: { role: 'inject', label: 'demo-skill' },
+      form: 'instructions',
+    })
+  })
+
+  it('keeps replacement copies out of Chat business nodes', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'user/message', {
+        ...textMessage('replacement-user', 'model-only context'),
+        source: { kind: 'plugin', plugin: 'foreign' },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 1 } }),
+      at(4, 'assistant/message', {
+        turn: 1,
+        step: 1,
+        message: assistantMessage('replacement-assistant', 'rewritten answer'),
+      }, { surfaceOp: { op: 'replace', start: 2, end: 2 } }),
+      at(5, 'tool/call', { turn: 1, step: 1, callId: 'root', name: 'read', arguments: '{}' }),
+      at(6, 'tool/result', {
+        turn: 1,
+        step: 1,
+        message: toolResult('root', 'pruned result'),
+      }, { surfaceOp: { op: 'replace', start: 3, end: 3 } }),
+    ])
+
+    const current = snapshot(value)
+    expect(node(current, 'user')).toBeUndefined()
+    expect(node(current, 'context')).toBeUndefined()
+    expect(node(current, 'assistant-step')).toBeUndefined()
+    expect((node(current, 'tool-call')?.data as ToolChatData).root).not.toHaveProperty('kind')
+  })
+
+  it('assembles retry chains and keeps manual and automatic compaction ownership separate', () => {
+    const retry = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'llm/retry', {
+        retryId: 'retry-1',
+        turn: 1,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 1,
+        maxRetries: 2,
+        delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'first' },
+      }),
+      at(4, 'llm/retry-started', { retryId: 'retry-1', turn: 1, step: 1, retry: 1 }),
+      at(5, 'llm/retry', {
+        retryId: 'retry-1',
+        turn: 1,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 2,
+        maxRetries: 2,
+        delayMs: 20,
+        failure: { code: 'TRANSPORT', message: 'second' },
+      }),
+      at(6, 'step/end', { turn: 1, step: 1 }),
+      at(7, 'turn/end', {
+        turn: 1,
+        reason: { kind: 'error', error: { code: 'TRANSPORT', message: 'failed' } },
+      }),
+    ])
+    const retryNode = node(snapshot(retry), 'model-retry')
+    const retryData = retryNode?.data as RetryChatData
+    expect(retryData.attempts.map(attempt => attempt.retryState)).toEqual(['started', 'cancelled'])
+    expect(node(snapshot(retry), 'turn-error')).toBeUndefined()
+
+    const compactions = assembler([
+      at(10, 'command/run', {
+        commandId: 'command-1',
+        name: 'compact',
+        source: { kind: 'user' },
+      }),
+      at(11, 'compact/start', {
+        compactionId: 'manual-1',
+        sourceCommandId: 'command-1',
+        turn: null,
+      }),
+      at(12, 'compact/summary', {
+        compactionId: 'manual-1',
+        sourceCommandId: 'command-1',
+        summary: [{ type: 'text', text: 'manual summary' }],
+        shadowedSeqs: [1, 2],
+        shadowedTokenCount: 100,
+      }),
+      at(13, 'user/message', {
+        ...textMessage('manual-checkpoint', 'checkpoint'),
+        source: {
+          kind: 'plugin',
+          plugin: 'compact',
+          compactionId: 'manual-1',
+          sourceCommandId: 'command-1',
+        },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 2 } }),
+      at(14, 'compact/end', {
+        compactionId: 'manual-1',
+        sourceCommandId: 'command-1',
+        turn: null,
+      }),
+      at(15, 'command/done', {
+        commandId: 'command-1',
+        kind: 'success',
+        sourceEventSeq: 12,
+      }),
+      at(20, 'compact/start', { compactionId: 'automatic-1', turn: null }),
+      at(21, 'compact/summary', {
+        compactionId: 'automatic-1',
+        summary: [{ type: 'text', text: 'automatic summary' }],
+        shadowedSeqs: [3, 4],
+        shadowedTokenCount: 200,
+      }),
+      at(22, 'user/message', {
+        ...textMessage('automatic-checkpoint', 'checkpoint'),
+        source: { kind: 'plugin', plugin: 'compact', compactionId: 'automatic-1' },
+      }, { surfaceOp: { op: 'replace', start: 3, end: 4 } }),
+      at(23, 'compact/end', { compactionId: 'automatic-1', turn: null }),
+    ])
+
+    const manual = node(snapshot(compactions), 'manual-compaction')
+    expect((manual?.data as ManualCompactionChatData).compaction).toMatchObject({
+      summary: 'manual summary',
+      summaryEventSeq: 12,
+    })
+    const automatic = node(snapshot(compactions), 'compaction')
+    expect(automatic?.data).toMatchObject({ summary: 'automatic summary', summaryEventSeq: 21 })
+    expect(snapshot(compactions).nodes.values().filter(candidate => candidate.kind === 'compaction')).toHaveLength(1)
+  })
+
+  it('fills a landed compaction marker when an older page supplies its summary', () => {
+    const value = assembler([
+      at(13, 'user/message', {
+        ...textMessage('checkpoint', 'checkpoint'),
+        source: { kind: 'plugin', plugin: 'compact', compactionId: 'compact-1' },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 8 } }),
+    ], true)
+    const before = node(snapshot(value), 'compaction')
+    expect(before?.data).toMatchObject({ summary: null, summaryEventSeq: null })
+
+    value.prepend([
+      at(9, 'compact/start', { compactionId: 'compact-1', turn: null }),
+      at(10, 'compact/summary', {
+        compactionId: 'compact-1',
+        summary: [
+          { type: 'text', text: 'older ' },
+          { type: 'image', data: 'ignored' },
+          { type: 'text', text: 'summary' },
+        ],
+        shadowedSeqs: [1, 2, 3],
+        shadowedTokenCount: 42,
+      }),
+    ], false)
+    value.flush()
+
+    const after = node(snapshot(value), 'compaction')
+    expect(after?.key).toBe(before?.key)
+    expect(after?.data).toMatchObject({
+      summary: 'older summary',
+      summaryEventSeq: 10,
+      shadowedItemCount: 3,
+      shadowedTokenCount: 42,
+    })
+  })
+
+  it('suppresses a turn error when the loaded tail contains only a later retry attempt', () => {
+    const value = assembler([
+      at(5, 'llm/retry', {
+        retryId: 'retry-paged',
+        turn: 1,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 2,
+        maxRetries: 2,
+        delayMs: 20,
+        failure: { code: 'TRANSPORT', message: 'second' },
+      }),
+      at(6, 'step/end', { turn: 1, step: 1 }),
+      at(7, 'turn/end', {
+        turn: 1,
+        reason: { kind: 'error', error: { code: 'TRANSPORT', message: 'failed' } },
+      }),
+    ], true)
+
+    expect(node(snapshot(value), 'model-retry')).toBeUndefined()
+    expect(node(snapshot(value), 'turn-error')).toBeUndefined()
+
+    value.prepend([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'llm/retry', {
+        retryId: 'retry-paged',
+        turn: 1,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 1,
+        maxRetries: 2,
+        delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'first' },
+      }),
+      at(4, 'llm/retry-started', {
+        retryId: 'retry-paged', turn: 1, step: 1, retry: 1,
+      }),
+    ], false)
+    value.flush()
+
+    const retry = node(snapshot(value), 'model-retry')
+    expect((retry?.data as RetryChatData).attempts).toHaveLength(2)
+    expect(node(snapshot(value), 'turn-error')).toBeUndefined()
+  })
+
+  it('preserves nested Tools and manual compaction evidence when their start events are outside the window', () => {
+    const value = assembler([
+      at(12, 'tool/code-dispatch-start', {
+        rootCallId: 'root', parentCallId: 'root', subCallId: 'child', name: 'read_file', arguments: { path: 'a' },
+      }),
+      at(13, 'tool/code-dispatch', {
+        rootCallId: 'root', parentCallId: 'root', subCallId: 'child', name: 'read_file', arguments: { path: 'a' },
+        isError: false, content: [{ type: 'text', text: 'child result' }],
+      }),
+      at(14, 'tool/result', {
+        turn: 1,
+        step: 1,
+        message: toolResult('root', 'root result'),
+      }, { surfaceOp: 'append' }),
+      at(20, 'compact/summary', {
+        compactionId: 'manual-1',
+        sourceCommandId: 'command-1',
+        summary: [{ type: 'text', text: 'manual summary' }],
+        shadowedSeqs: [1, 2],
+        shadowedTokenCount: 100,
+      }),
+      at(21, 'user/message', {
+        ...textMessage('manual-checkpoint', 'checkpoint'),
+        source: {
+          kind: 'plugin',
+          plugin: 'compact',
+          compactionId: 'manual-1',
+          sourceCommandId: 'command-1',
+        },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 2 } }),
+      at(22, 'command/done', {
+        commandId: 'command-1',
+        kind: 'success',
+        sourceEventSeq: 20,
+      }),
+    ], true)
+
+    const tool = node(snapshot(value), 'tool-call')
+    const root = (tool?.data as ToolChatData).root
+    expect(root.subCalls).toHaveLength(1)
+    expect(root.subCalls[0]).toMatchObject({ callId: 'child', kind: 'tool-result' })
+    const manual = node(snapshot(value), 'manual-compaction')
+    expect((manual?.data as ManualCompactionChatData)).toMatchObject({
+      command: { commandId: 'command-1', name: 'compact', outcome: { kind: 'success' } },
+      compaction: { summary: 'manual summary', summaryEventSeq: 20 },
+    })
+  })
+})
diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
index 3afe471d50..ff3a0f1598 100644
--- a/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/gate-branch-tails.spec.tsx
@@ -3,7 +3,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore, EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 import type { UseSession } from '@deepseek-ai/dsh-client-web-react'
 import type { ConversationSnapshot, SessionId, SessionListState, WorkspaceListState } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionProviderComponent } from '@deepseek-ai/dsh-client-ui-slots'
@@ -15,6 +15,7 @@ import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/ch
 import { StatsLine } from '../src/client/chat/StatsLine.tsx'
 import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
 import { zh } from '../src/client/locales.ts'
+import { chatSnapshotFixture } from './chat-snapshot-fixture.ts'
 
 // Mirrors the real lookup chain (conversation namespace, then common).
 const t: AssistantMarkdownProps['t'] = makeTranslate(zh, commonZh)
@@ -40,14 +41,15 @@ const SessionProviderStub: SessionProviderComponent = ({ children }) => children
 /** Observe the owner currency without importing the Tool details renderer. */
 function renderToolDetailsProbe(owners?: DetailsToolOwnerProps[]): DetailsSlotProps['renderSlot'] {
   return (_key, owner) => {
-    owners?.push(owner as DetailsToolOwnerProps)
+    owners?.push(owner as unknown as DetailsToolOwnerProps)
     return <div data-testid="tool-details-seat" />
   }
 }
 
 function snapshotBase(): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
@@ -69,11 +71,16 @@ describe('render branch tails', () => {
   it('StatsLine counts window nodes but drops every token group without a projection', () => {
     // Node `usage` is deliberately ignored: billing rides the durable
     // tokenUsage projection, so an absent projection leaves counts only.
+    const nodes = [
+      { kind: 'assistant', seq: 1, time: 1, turn: 1, step: 1, blocks: [] },
+      { kind: 'assistant', seq: 2, time: 2, turn: 1, step: 2, blocks: [], usage: { inputTokens: 4, outputTokens: 6 } },
+      { kind: 'assistant', seq: 3, time: 3, turn: 2, step: 1, blocks: [], usage: { inputTokens: 5 } },
+    ] as const
     const snap = {
+      ...snapshotBase(),
+      chat: chatSnapshotFixture({ nodes }),
       nodes: [
-        { kind: 'assistant', seq: 1, turn: 1, step: 1, blocks: [] },
-        { kind: 'assistant', seq: 2, turn: 1, step: 2, blocks: [], usage: { inputTokens: 4, outputTokens: 6 } },
-        { kind: 'assistant', seq: 3, turn: 2, step: 1, blocks: [], usage: { inputTokens: 5 } },
+        ...nodes,
       ],
     }
     const source = { getSnapshot: () => snap, subscribe: () => () => {} }
@@ -146,6 +153,7 @@ describe('render branch tails', () => {
         }],
       }],
     }]
+    snap.chat = chatSnapshotFixture({ runningCalls: snap.runningCalls })
     const chat = createChatStore().create()
     chat.actions.select({ turnSeq: 9, callId: 'p1:code:1:code:1', toolName: 'read' } satisfies SelectionTarget)
     const emptyList = createSnapshotStore<SessionListState>(
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index 1e7c3a1ba1..e9076fa994 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -7,7 +7,7 @@
 import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore, EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import type { ClientContext, ConversationSnapshot, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
@@ -35,7 +35,8 @@ const SID = 's1' as SessionId
 
 function snapshotOf(overrides: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/input-matrix.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
index f197528a2b..65fa5705ca 100644
--- a/packages/client/ui-conversation/tests/input-matrix.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
@@ -8,7 +8,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore, EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ClientContext, ConversationSnapshot, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SubmitOutcome } from '@deepseek-ai/dsh-client-ui-slash/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
@@ -26,7 +26,8 @@ const SID = 's1' as SessionId
 /** Standard-props InputBar mount over a real shell (the composer-bar entry shape). */
 function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled?: boolean }) {
   const session = createSnapshotStore<ConversationSnapshot>({
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: over?.running ?? false, composerPhase: 'active',
     removed: over?.disabled ?? false, openState: 'open', openError: null, hasMore: false,
     loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
index aae5bb4818..94d348d17a 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
@@ -11,7 +11,7 @@
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
-import { SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { EMPTY_CHAT_SNAPSHOT, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { SlashService } from '@deepseek-ai/dsh-client-ui-slash/client'
 import type { ClientSessionContext, CommandClaim, PickOutcome, SubmitOutcome } from '@deepseek-ai/dsh-client-ui-slash/client'
 import { FakeApiClient, ok } from '../../runtime/tests/fake-api.ts'
@@ -112,7 +112,8 @@ async function scopedBench(register?: (slash: SlashService) => void) {
   actx.on('slash/input-consume-token', req => shell.consumeToken(req.guard) ? true : undefined)
   const wiring = shell
   const sessionStore = createSnapshotStore<ConversationSnapshot>({
-    sessionId, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-conversation/tests/queue-dock.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.spec.tsx
index 826abaf846..31a6423f87 100644
--- a/packages/client/ui-conversation/tests/queue-dock.spec.tsx
+++ b/packages/client/ui-conversation/tests/queue-dock.spec.tsx
@@ -6,6 +6,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react'
 import { useSyncExternalStore } from 'react'
+import { EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   ConversationSnapshot, QueuedMessage, SessionId, SessionListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -32,7 +33,8 @@ function row(id: string, text: string | null, preview = text ?? '[image]'): Queu
 
 function snapshotWith(queue: QueuedMessage[]): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue, running: true, composerPhase: 'active', removed: false, openState: 'open', openError: null,
     hasMore: false, loadingOlder: false, promptError: null, blank: false, subagent: null, lastAgentError: null,
   }
diff --git a/packages/client/ui-conversation/tests/skeleton.spec.tsx b/packages/client/ui-conversation/tests/skeleton.spec.tsx
index 70b6d96710..bbabbaeb0c 100644
--- a/packages/client/ui-conversation/tests/skeleton.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.spec.tsx
@@ -5,7 +5,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore, EMPTY_CHAT_SNAPSHOT } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   ConversationSnapshot, SessionId, SessionListState, WorkspaceId, WorkspaceListState, WorkspaceView,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -70,7 +70,8 @@ const workspaceState = (items: readonly WorkspaceView[]): WorkspaceListState =>
 
 function conversationSnapshot(overrides: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
   return {
-    sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+    sessionId: SID, chat: EMPTY_CHAT_SNAPSHOT,
+    nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
     pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
     openState: 'open', openError: null, hasMore: false, loadingOlder: false,
     promptError: null, blank: false, subagent: null, lastAgentError: null,
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index 3bcaffe605..b7ca73a79f 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -8,15 +8,22 @@
 import { Context } from 'cordis'
 import { cleanup, fireEvent, render } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  ConversationEventRegistry, ConversationNodeAssembler, SlotsService,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type {
-  AssistantMessageNode, ConversationNode, ToolResultNode, UserMessageNode,
+  ConversationEventInput, ConversationLocationDataStore, ConversationNodeDefinition,
+  ConversationTimelineSnapshot, ConversationTurnDataMap, ConversationViewDefinition,
+  ConversationViewNode, ToolResultNode, TurnLocation,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply as applyLocale } from '@deepseek-ai/dsh-client-locale/client'
-import type { ChatFileMentions } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { ChatFileMentions, TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { ProducedFiles } from '../src/client/ProducedFiles.tsx'
-import { basename, producedFileMentions, producedForClosing, selectProducedFiles } from '../src/client/turn-deliverables.ts'
+import {
+  basename, deliverablesDefinition, producedFileMentions, producedForClosing, selectProducedFiles,
+  type DeliverablesTurnData,
+} from '../src/client/turn-deliverables.ts'
 import { apply, inject } from '../src/client/index.ts'
 import { apply as applyNode } from '../src/index.ts'
 import { apply as applyInvariant } from '../src/invariant.ts'
@@ -24,101 +31,187 @@ import { zh } from '../src/client/locales.ts'
 
 afterEach(cleanup)
 
-const user = (seq: number, text: string): UserMessageNode => ({
-  kind: 'user',
-  seq,
-  time: seq * 1000,
-  content: [{ type: 'text', text }] as never,
-  source: null,
+class TestTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
+  private readonly values = new Map<string, unknown>()
+
+  get<Key extends keyof ConversationTurnDataMap & string>(
+    key: Key,
+  ): Readonly<ConversationTurnDataMap[Key]> | undefined {
+    return this.values.get(key) as Readonly<ConversationTurnDataMap[Key]> | undefined
+  }
+
+  set<Key extends keyof ConversationTurnDataMap & string>(key: Key, value: ConversationTurnDataMap[Key]): void {
+    this.values.set(key, value)
+  }
+}
+
+const turnLocation = (turn: number, deliverables?: DeliverablesTurnData): TurnLocation => {
+  const data = new TestTurnDataStore()
+  if (deliverables !== undefined) data.set('deliverables', deliverables)
+  return { turn, start: undefined, end: undefined, status: 'closed', steps: [], data }
+}
+
+const produced = (...values: ReadonlyArray<readonly [seq: number, path: string]>): DeliverablesTurnData => ({
+  produced: values.map(([seq, path]) => ({ seq, path })),
 })
-const assistant = (seq: number, text: string, turn = 1): AssistantMessageNode => ({
-  kind: 'assistant', seq, time: seq * 1_000, turn, step: 1, blocks: [{ kind: 'text', text }],
-})
-const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode => ({
-  kind: 'tool-result', seq, time: seq * 1_000, callId,
-  call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` },
-  callTime: seq * 1_000 - 500,
-  content: [], isError: false, callView: null, resultView: null, subCalls: [],
-})
-const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
-  ...toolResult(seq, callId, 'write'),
-  callView: {
+
+function tailOwner(
+  data: DeliverablesTurnData | undefined,
+  seq: number,
+  openFile: (path: string) => void = () => {},
+  turn = 1,
+): TurnTailOwnerProps {
+  return { seq, openFile, turn: turnLocation(turn, data) }
+}
+
+interface TimelineSnapshot {
+  readonly timeline: ConversationTimelineSnapshot
+}
+
+class TestEventDefinitions {
+  entries(): readonly ConversationNodeDefinition[] { return [deliverablesDefinition] }
+  fallbackEntry(): undefined { return undefined }
+}
+
+class TestViewDefinitions {
+  entries(): readonly ConversationViewDefinition[] { return [timelineViewDefinition] }
+}
+
+const timelineViewDefinition: ConversationViewDefinition<ConversationViewNode, TimelineSnapshot> = {
+  target: 'test',
+  create: () => {
+    let current: TimelineSnapshot = { timeline: { turnOrder: [], turns: new Map() } }
+    return {
+      empty: current,
+      replace: ({ timeline }) => (current = { timeline }),
+      apply: ({ timeline }) => (current = { timeline }),
+    }
+  },
+}
+
+function at(
+  seq: number,
+  type: string,
+  data: unknown,
+  view?: ConversationEventInput['view'],
+): ConversationEventInput {
+  return {
+    event: {
+      seq, time: seq * 1_000, type, data,
+      ...(type === 'tool/result' ? { surfaceOp: 'append' } : {}),
+    } as ConversationEventInput['event'],
+    view,
+  }
+}
+
+function call(
+  seq: number,
+  callId: string,
+  view: ToolResultNode['callView'],
+  turn = 1,
+): ConversationEventInput {
+  return at(
+    seq,
+    'tool/call',
+    { turn, step: 1, callId, name: 'fixture', arguments: '{}' },
+    { for: 'call', view: view ?? { card: 'generic', title: 'fixture' } },
+  )
+}
+
+function result(seq: number, callId: string, isError = false, turn = 1): ConversationEventInput {
+  return at(seq, 'tool/result', {
+    turn,
+    step: 1,
+    message: {
+      source: { type: 'tool-result', callId },
+      content: [{ type: 'tool-result', content: [], isError }],
+    },
+  })
+}
+
+function diff(...paths: string[]): ToolResultNode['callView'] {
+  return {
     card: 'diff', title: `Write ${paths[0] ?? ''}`,
     diffs: paths.map(path => ({ path, oldText: null, newText: 'x' })),
     locations: paths.map(path => ({ path })),
-  },
-})
+  }
+}
 
-describe('producedForClosing derivation', () => {
-  it('attributes each turn’s written files to the assistant that closes it', () => {
-    const nodes: ConversationNode[] = [
-      user(1, 'build it'),
-      assistant(2, 'writing', 1),
-      wrote(3, 'a', 'out/index.html'),
-      // Same file touched twice in one turn is one deliverable, in first-seen order.
-      wrote(4, 'b', 'out/app.css', 'out/index.html'),
-      // A read is not a deliverable; a failed write has no file to open.
-      { ...toolResult(5, 'c', 'read'), callView: { card: 'generic', title: 'Read x', locations: [{ path: 'x.ts' }] } },
-      { ...wrote(6, 'd', 'out/broken.html'), isError: true },
-      assistant(7, 'done', 1),
-      user(8, 'again'),
-      assistant(9, 'second turn', 2),
-    ]
-    expect(producedForClosing(nodes, 7)).toEqual(['out/index.html', 'out/app.css'])
-    expect(selectProducedFiles({ nodes, seq: 7, openFile: () => {} })).toEqual(['out/index.html', 'out/app.css'])
-    expect(selectProducedFiles({ nodes, seq: 9, openFile: () => {} })).toBeNull()
-    // A turn that produced nothing yields the empty list, and so does an
-    // anchor the window does not contain.
-    expect(producedForClosing(nodes, 9)).toEqual([])
-    expect(producedForClosing([user(1, 'hi'), assistant(2, 'hello', 1)], 2)).toEqual([])
-    expect(producedForClosing(nodes, 999)).toEqual([])
+function edit(path: string): ToolResultNode['callView'] {
+  return { card: 'generic', title: `insert ${path}`, kind: 'edit', locations: [{ path }] }
+}
+
+function assembler(entries: readonly ConversationEventInput[], hasMore = false): ConversationNodeAssembler {
+  const value = new ConversationNodeAssembler(new TestEventDefinitions(), new TestViewDefinitions())
+  value.replaceWindow(entries, hasMore)
+  value.flush()
+  return value
+}
+
+function deliverablesOf(value: ConversationNodeAssembler, turn = 1): Readonly<DeliverablesTurnData> | undefined {
+  const snapshot = value.snapshot('test') as TimelineSnapshot
+  return snapshot.timeline.turns.get(turn)?.data.get('deliverables')
+}
+
+describe('produced-file Turn data', () => {
+  it('deduplicates paths in first-seen order and stops at the closing Assistant seq', () => {
+    const data = produced(
+      [3, 'out/index.html'],
+      [4, 'out/app.css'],
+      [4, 'out/index.html'],
+      [8, 'after.txt'],
+    )
+    expect(producedForClosing(data, 6)).toEqual(['out/index.html', 'out/app.css'])
+    expect(selectProducedFiles(tailOwner(data, 6))).toEqual(['out/index.html', 'out/app.css'])
+    expect(producedForClosing(undefined)).toEqual([])
+    expect(selectProducedFiles(tailOwner(undefined, 9, () => {}, 2))).toBeNull()
   })
 
+  it('folds successful diff and generic-edit calls while ignoring reads, failures, and missing locations', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      call(2, 'write', diff('out/index.html', 'out/app.css')),
+      result(3, 'write'),
+      call(4, 'edit', edit('notes.md')),
+      result(5, 'edit'),
+      call(6, 'read', { card: 'generic', title: 'Read', locations: [{ path: 'input.txt' }] }),
+      result(7, 'read'),
+      call(8, 'failed', diff('broken.txt')),
+      result(9, 'failed', true),
+      call(10, 'locationless', { card: 'diff', title: 'Write', diffs: [] }),
+      result(11, 'locationless'),
+    ])
 
-  it('counts a generic edit and never spills across the turn boundary', () => {
-    const inserted = (seq: number, callId: string, path: string): ToolResultNode => ({
-      ...toolResult(seq, callId, 'str_replace_editor'),
-      // str_replace_editor's insert mutates behind a generic card, so the
-      // discriminant is the render intent, not the card shape alone.
-      callView: { card: 'generic', title: `insert ${path}`, kind: 'edit', locations: [{ path }] },
-    })
-    const nodes: ConversationNode[] = [
-      user(1, 'insert a line'),
-      inserted(2, 'i', 'notes.md'),
-      assistant(3, 'inserted', 1),
-      // Turn 2 mutates and then ends with no content text (interrupted, or its
-      // last text preceded the tool): its paths must not ride into turn 3.
-      user(4, 'now rewrite it'),
-      wrote(5, 'w', 'leaked.txt'),
-      user(6, 'and again'),
-      wrote(7, 'w2', 'notes.md'),
-      assistant(8, 'done', 3),
-    ]
-    expect(producedForClosing(nodes, 3)).toEqual(['notes.md'])
-    // Turn 3 lists only its own file — and the dedup set did not suppress the
-    // rewrite of a path an earlier turn already touched.
-    expect(producedForClosing(nodes, 8)).toEqual(['notes.md'])
-    expect(producedForClosing(nodes, 8)).not.toContain('leaked.txt')
+    expect(producedForClosing(deliverablesOf(value))).toEqual([
+      'out/index.html', 'out/app.css', 'notes.md',
+    ])
   })
 
-  it('resets on a turn-number change and skips turnless, viewless, and locationless nodes', () => {
-    const nodes: ConversationNode[] = [
-      user(1, 'go'),
-      // A turnless surface node neither tracks nor resets the boundary.
-      { kind: 'unknown', seq: 1.5, time: 1_500, type: 'x', data: null },
-      wrote(2, 'w', 'turn-one.txt'),
-      // A view-less result (window truncation) and cards without locations
-      // contribute nothing rather than crashing the walk.
-      toolResult(3, 'plain'),
-      { ...toolResult(4, 'nl', 'write'), callView: { card: 'diff', title: 'Write', diffs: [] } },
-      { ...toolResult(5, 'ge', 'str_replace_editor'), callView: { card: 'generic', title: 'insert', kind: 'edit' } },
-      assistant(6, 'mid narration', 1),
-      // Turn number advances with no user message in the window (truncated
-      // history): the accumulator must reset all the same.
-      assistant(7, 'closing', 2),
-    ]
-    expect(producedForClosing(nodes, 6)).toEqual(['turn-one.txt'])
-    expect(producedForClosing(nodes, 7)).toEqual([])
+  it('replays a tail page once prepend supplies its missing Turn start', () => {
+    const value = assembler([
+      call(10, 'late', diff('history.txt')),
+      result(11, 'late'),
+    ], true)
+    expect(deliverablesOf(value)).toBeUndefined()
+
+    value.prepend([at(1, 'turn/start', { turn: 1 })], false)
+    value.flush()
+    expect(producedForClosing(deliverablesOf(value))).toEqual(['history.txt'])
+  })
+
+  it('extends the same Turn data incrementally on live append', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      call(2, 'first', diff('first.txt')),
+      result(3, 'first'),
+    ])
+    const first = deliverablesOf(value)
+    expect(producedForClosing(first)).toEqual(['first.txt'])
+
+    value.append(call(4, 'second', diff('second.txt')))
+    value.append(result(5, 'second'))
+    value.flush()
+    expect(producedForClosing(deliverablesOf(value))).toEqual(['first.txt', 'second.txt'])
   })
 })
 
@@ -190,6 +283,7 @@ describe('plugin registration', () => {
   it('registers the tail entry and fiber disposal removes it', async () => {
     const ctx = new Context()
     await ctx.plugin(SlotsService).await()
+    await ctx.plugin(ConversationEventRegistry).await()
     // The owning view's child declaration, stood up by a bench root entry.
     ctx.slots.register({
       name: 'root',
@@ -204,17 +298,17 @@ describe('plugin registration', () => {
     // The prose face is live while the plugin is: a produced turn yields a
     // resolver whose matches open through the owner-supplied opener.
     const opened: string[] = []
-    const owner = {
-      nodes: [user(1, 'go'), wrote(2, 'w', 'site/report.html'), assistant(3, 'done', 1)],
-      seq: 3,
-      openFile: (path: string) => { opened.push(path) },
-    }
+    const owner = tailOwner(
+      produced([2, 'site/report.html']),
+      3,
+      (path) => { opened.push(path) },
+    )
     const service = (ctx as unknown as { get(name: string): ChatFileMentions | undefined }).get('chatFileMentions')
     const mentions = service?.forClosing(owner)
     mentions?.resolve('report.html')?.open()
     expect(opened).toEqual(['site/report.html'])
     // A turn that produced nothing yields no vocabulary at all.
-    expect(service?.forClosing({ ...owner, nodes: [user(1, 'hi'), assistant(2, 'ok', 1)], seq: 2 })).toBeUndefined()
+    expect(service?.forClosing(tailOwner(undefined, 2))).toBeUndefined()
 
     await fiber.dispose()
     expect(ctx.slots.entries('conversation.chat.turnTail')).toHaveLength(0)
diff --git a/packages/client/ui-slots/tests/surface.spec.ts b/packages/client/ui-slots/tests/surface.spec.ts
index 12a5eeba15..e85aa324e1 100644
--- a/packages/client/ui-slots/tests/surface.spec.ts
+++ b/packages/client/ui-slots/tests/surface.spec.ts
@@ -7,6 +7,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface SlotMap {
     'surface.a': { kind: 'single'; scope: 'root' }
     'surface.b': { kind: 'single'; scope: 'root' }
+    'surface.injected': { kind: 'single'; scope: 'root'; inject: { token: string } }
   }
 }
 
@@ -28,6 +29,16 @@ describe('dynamic-key escape hatch', () => {
     expect(core.spec('surface.b')).toBeUndefined()
   })
 
+  it('records the parent-declared Slot inject on the runtime spec', () => {
+    const core = new SlotCore()
+    const inject = { token: 'shared' }
+    core.register({
+      name: 'root',
+      children: { 'surface.injected': { kind: 'single', scope: 'root', inject } },
+    }, Comp as never)
+    expect(core.spec('surface.injected')?.inject).toBe(inject)
+  })
+
   it('entries/getVersion on an untouched key return the frozen empty array and 0', () => {
     const core = new SlotCore()
     expect(core.entries('surface.b')).toHaveLength(0)
diff --git a/packages/client/ui-slots/tests/type-chain.spec.tsx b/packages/client/ui-slots/tests/type-chain.spec.tsx
index b3a6aec873..64277edccc 100644
--- a/packages/client/ui-slots/tests/type-chain.spec.tsx
+++ b/packages/client/ui-slots/tests/type-chain.spec.tsx
@@ -5,7 +5,7 @@
 import { describe, expect, it } from 'vitest'
 import type { ReactNode } from 'react'
 import type {
-  BoundActions, DefineStore, PropsRenderSlots, PropsRuntime, PropsStore, SlotComponent,
+  BoundActions, DefineStore, PropsRenderSlots, PropsRuntime, PropsStore, SlotComponent, SlotHookFactory,
 } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
 
@@ -19,6 +19,12 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     'chain.frame': { kind: 'single'; scope: 'root' }
     'chain.side': { kind: 'single'; scope: 'root'; owner: { collapsed: boolean; width: number } }
     'chain.conv': { kind: 'single'; scope: 'session' }
+    'chain.context': {
+      kind: 'single'
+      scope: 'session'
+      hookContext: string
+      inject: ContextInjected
+    }
     'chain.tools': { kind: 'keyed'; scope: 'session' }
     'chain.takeover': { kind: 'chain'; scope: 'session'; owner: { items: readonly Item[] } }
   }
@@ -62,6 +68,23 @@ type ConvProps =
   & PropsStore<ChatHandle>
   & { send: (t: string) => void }
 
+interface TurnDataMap { tail: string; files: string }
+type UseTurnData = <Key extends keyof TurnDataMap>(key: Key) => TurnDataMap[Key] | undefined
+interface ContextInjected {
+  hooks: {
+    turnData: SlotHookFactory<'chain.context', UseTurnData>
+  }
+}
+type ContextProps = PropsRuntime<'chain.context'>
+const CONTEXT_INJECT: ContextInjected = {
+  hooks: {
+    turnData: (_standard, hookContext) => {
+      const id: string = hookContext
+      return key => id === '' ? undefined : ({ tail: 'tail', files: 'files' })[key]
+    },
+  },
+}
+
 // Component fixtures (never rendered; the register call sites are the test).
 declare function Frame(props: FrameProps): ReactNode
 declare function Conv(props: ConvProps): ReactNode
@@ -72,6 +95,8 @@ declare function NoDecl(props: PropsRuntime<'chain.frame'> & PropsRenderSlots<'c
 declare function Blind(props: PropsRuntime<'chain.frame'>): ReactNode
 declare function WrongStore(props: PropsRuntime<'chain.conv'> & PropsStore<ReturnType<typeof createPanelStore>>): ReactNode
 declare function Needs(props: PropsRuntime<'chain.conv'> & { send: (t: string) => void }): ReactNode
+declare function ContextOwner(props: PropsRuntime<'chain.frame'> & PropsRenderSlots<'chain.context'>): ReactNode
+declare function ContextReader(props: ContextProps): ReactNode
 declare function Takeover(props: PropsRuntime<'chain.takeover'> & { matched: Item }): ReactNode
 declare function WideTakeover(props: PropsRuntime<'chain.takeover'> & { matched: Item | string }): ReactNode
 declare function NarrowTakeover(props: PropsRuntime<'chain.takeover'> & { matched: { kind: 'q'; id: string; extra: number } }): ReactNode
@@ -144,6 +169,24 @@ describe('terminal-design type chain', () => {
       chainSlots.renderSlotChain('chain.takeover', { items: [] }, { fallback: null })
       chainSlots.renderSlot('chain.conv', {})
 
+      // A parent registration declares the Slot inject once; every child
+      // entry receives the same custom Hook, bound to official standard props
+      // and each render occurrence's opaque context.
+      core.register({
+        name: 'chain.frame',
+        children: {
+          'chain.context': { kind: 'single', scope: 'session', inject: CONTEXT_INJECT },
+        },
+      }, ContextOwner)
+      core.register({ name: 'chain.context' }, ContextReader)
+      const contextProps: ContextProps = null as never
+      const tail: string | undefined = contextProps.useTurnData('tail')
+      const contextSlots: PropsRenderSlots<'chain.context'> = null as never
+      contextSlots.renderSlot('chain.context', {}, {
+        hookContext: 'turn:1',
+      })
+      void tail
+
       // ── negatives ──────────────────────────────────────────────────
       // children spec must match the SlotMap entry.
       core.register({
@@ -151,6 +194,11 @@ describe('terminal-design type chain', () => {
         // @ts-expect-error chain.conv is session-scoped in SlotMap
         children: { 'chain.conv': { kind: 'single', scope: 'root' } },
       }, (() => null) as SlotComponent<never>)
+      core.register({
+        name: 'chain.frame',
+        // @ts-expect-error chain.context requires its Slot-level inject declaration
+        children: { 'chain.context': { kind: 'single', scope: 'session' } },
+      }, ContextOwner)
 
       // renderSlot key set ⊄ children declaration.
       // @ts-expect-error component renderSlot keys exceed the declaration
@@ -219,6 +267,16 @@ describe('terminal-design type chain', () => {
       // @ts-expect-error key not in this render share
       fp.renderSlot('chain.tools', {})
 
+      // Contextual hooks preserve both the business key and value type.
+      // @ts-expect-error unknown Turn-data key
+      contextProps.useTurnData('other')
+      // @ts-expect-error a contextual slot requires its occurrence context
+      contextSlots.renderSlot('chain.context', {})
+      // @ts-expect-error hookContext is the slot-declared string
+      const _wrongContextFactory: SlotHookFactory<'chain.context', UseTurnData> =
+        (_standard, _hookContext: number) => () => undefined
+      void _wrongContextFactory
+
       // baked actions strip the draft parameter.
       acts.setDraft('x')
       // @ts-expect-error wrong payload type
diff --git a/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
index 9cbdfe3f1d..8f4fb384b0 100644
--- a/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
+++ b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
@@ -8,6 +8,7 @@ import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { apply as applyTool, inject as injectTool } from '../src/client/apply.ts'
+import { toolChatSnapshot } from './tool-details-render.tsx'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
@@ -74,7 +75,7 @@ async function bench(nodes: ToolResultNode[]) {
   await runtime.sessions.add({
     id: SID,
     summary: { title: 'S', displayTitle: 'S', cwd: '/proj' },
-    snapshot: { nodes },
+    snapshot: { nodes, chat: toolChatSnapshot(nodes) },
     session: {
       loadOlder: vi.fn<ISession['loadOlder']>(),
       prompt: vi.fn<ISession['prompt']>(async () => ({ ok: true, value: { accepted: true } })),
diff --git a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
index 6c0bb956bd..3b70851a02 100644
--- a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
@@ -11,7 +11,9 @@
 import { Context } from 'cordis'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
-import { createSnapshotStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  ConversationEventRegistry, ConversationViewRegistry, createSnapshotStore, SlotsService,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   ConversationSnapshot, RunningToolCall, SessionId, SessionListState,
   ToolCallBlock, ToolResultNode, WorkspaceListState,
@@ -21,6 +23,7 @@ import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { apply as applyTool, inject as injectTool } from '../src/client/apply.ts'
+import { toolChatSnapshot } from './tool-details-render.tsx'
 
 const SID = 's1' as SessionId
 
@@ -75,7 +78,8 @@ function snapshotWith(
   const nestedNodes = nodes.map(node => ({ ...node, subCalls }))
   const nestedRunningCalls = runningCalls.map(call => ({ ...call, subCalls }))
   return {
-    sessionId: SID, nodes: nestedNodes, turnTimings: new Map(), turnEnds: new Map(), partial: null,
+    sessionId: SID, chat: toolChatSnapshot(nestedNodes, nestedRunningCalls),
+    nodes: nestedNodes, turnTimings: new Map(), turnEnds: new Map(), partial: null,
     runningCalls: nestedRunningCalls,
     pending: [], queue: [], running: runningCalls.length > 0, composerPhase: 'active', removed: false,
     openState: 'open', openError: null,
@@ -97,6 +101,8 @@ async function bench(snapshot: ConversationSnapshot) {
   const ctx = new Context()
   const slotsFiber = ctx.plugin(SlotsService)
   await slotsFiber.await()
+  await ctx.plugin(ConversationEventRegistry).await()
+  await ctx.plugin(ConversationViewRegistry).await()
   const slots = ctx.get('slots') as SlotsService
 
   const session = createSnapshotStore<ConversationSnapshot>(snapshot)
diff --git a/packages/client/ui-tool/tests/diff-card.spec.tsx b/packages/client/ui-tool/tests/diff-card.spec.tsx
index 7713bedaec..0cea47b572 100644
--- a/packages/client/ui-tool/tests/diff-card.spec.tsx
+++ b/packages/client/ui-tool/tests/diff-card.spec.tsx
@@ -20,7 +20,7 @@ import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/cli
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { FileMutationRow, fileMutationToolview } from '../src/client/tool/toolviews/file-mutation-row.tsx'
-import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.tsx'
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 afterEach(cleanup)
@@ -342,8 +342,11 @@ describe('DetailsPanel diff Output section', () => {
   }
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    const nodes = over.nodes ?? []
+    const runningCalls = over.runningCalls ?? []
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+      sessionId: SID, chat: over.chat ?? toolChatSnapshot(nodes, runningCalls),
+      nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/read-card.spec.tsx b/packages/client/ui-tool/tests/read-card.spec.tsx
index 739a787a03..f74bbae6be 100644
--- a/packages/client/ui-tool/tests/read-card.spec.tsx
+++ b/packages/client/ui-tool/tests/read-card.spec.tsx
@@ -24,7 +24,7 @@ import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/t
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { ReadRow, readToolview } from '../src/client/tool/toolviews/read-row.tsx'
-import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.tsx'
 
 afterEach(cleanup)
 
@@ -288,8 +288,11 @@ describe('DetailsPanel Output section (read)', () => {
   }
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    const nodes = over.nodes ?? []
+    const runningCalls = over.runningCalls ?? []
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+      sessionId: SID, chat: over.chat ?? toolChatSnapshot(nodes, runningCalls),
+      nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/search-card.spec.tsx b/packages/client/ui-tool/tests/search-card.spec.tsx
index 51cab2d440..0016318b90 100644
--- a/packages/client/ui-tool/tests/search-card.spec.tsx
+++ b/packages/client/ui-tool/tests/search-card.spec.tsx
@@ -23,7 +23,7 @@ import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/cli
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { SearchRow, searchToolview } from '../src/client/tool/toolviews/search-row.tsx'
-import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.tsx'
 
 /** SearchRow now composes ToolRow, so its props include the locale `t` seat. */
 type SearchRowProps = Parameters<typeof SearchRow>[0]
@@ -404,8 +404,11 @@ describe('DetailsPanel Output section (search)', () => {
   }
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    const nodes = over.nodes ?? []
+    const runningCalls = over.runningCalls ?? []
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+      sessionId: SID, chat: over.chat ?? toolChatSnapshot(nodes, runningCalls),
+      nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/terminal-card.spec.tsx b/packages/client/ui-tool/tests/terminal-card.spec.tsx
index c9e2875a34..0dcb59d818 100644
--- a/packages/client/ui-tool/tests/terminal-card.spec.tsx
+++ b/packages/client/ui-tool/tests/terminal-card.spec.tsx
@@ -20,7 +20,7 @@ import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/cli
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { BashRow } from '../src/client/tool/toolviews/bash-sample.tsx'
-import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.tsx'
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 
 type BashRowProps = Parameters<typeof BashRow>[0]
@@ -479,8 +479,11 @@ describe('DetailsPanel Output section', () => {
   }
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    const nodes = over.nodes ?? []
+    const runningCalls = over.runningCalls ?? []
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+      sessionId: SID, chat: over.chat ?? toolChatSnapshot(nodes, runningCalls),
+      nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
index 393b9f8f46..44f4231802 100644
--- a/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-call-tree.spec.tsx
@@ -29,12 +29,21 @@ function props(
   return {
     useSession,
     renderSlot,
-    callId: block.callId,
-    toolName: block.call?.name ?? '',
-    block,
+    node: {
+      key: `tool:${block.callId}`,
+      kind: 'tool-call',
+      id: block.callId,
+      target: 'chat',
+      anchorSeq: block.seq,
+      location: { kind: 'session' },
+      visibility: 'visible',
+      data: { root: block },
+    },
     selectedCallId,
     openFile: vi.fn(),
     inspectCall: vi.fn(),
+    forkAt: vi.fn(),
+    fileMentions: vi.fn(),
     t,
   } as unknown as ToolTreeProps
 }
diff --git a/packages/client/ui-tool/tests/tool-details-render.tsx b/packages/client/ui-tool/tests/tool-details-render.tsx
index 0aeb3c5321..b2b2cd9ac7 100644
--- a/packages/client/ui-tool/tests/tool-details-render.tsx
+++ b/packages/client/ui-tool/tests/tool-details-render.tsx
@@ -1,5 +1,7 @@
 /** Test adapter for the production conversation.details.tool registration. */
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ChatConversationViewNode, ChatSnapshot, ConversationNode, RunningToolCall, SessionId,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionProviderComponent, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
 import type { DetailsSlotProps, DetailsToolOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/src/client/contract/slots.ts'
 import { ToolDetails } from '../src/client/tool/ToolDetails.tsx'
@@ -7,6 +9,45 @@ import { ToolDetails } from '../src/client/tool/ToolDetails.tsx'
 /** Framework session-area seat used by direct DetailsPanel tests. */
 export const SessionProviderStub: SessionProviderComponent = ({ children }) => children('s1' as SessionId)
 
+/** Build the canonical Chat slice consumed by Tool rows and details tests. */
+export function toolChatSnapshot(
+  settled: readonly ConversationNode[] = [],
+  running: readonly RunningToolCall[] = [],
+): ChatSnapshot {
+  const roots = [...settled.filter(node => node.kind === 'tool-result'), ...running]
+  const nodes: ChatConversationViewNode[] = roots.map(root => ({
+    key: `tool:${root.callId}`,
+    kind: 'tool-call',
+    id: root.callId,
+    target: 'chat',
+    anchorSeq: 'kind' in root ? root.seq : Number.MAX_SAFE_INTEGER,
+    location: { kind: 'session' },
+    visibility: 'visible',
+    data: { root },
+  }))
+  const byKey = new Map(nodes.map(node => [node.key, node]))
+  const empty: readonly string[] = []
+  return {
+    order: nodes.map(node => node.key),
+    nodes: {
+      get: key => byKey.get(key),
+      values: () => nodes,
+    },
+    locations: {
+      getTurn: () => empty,
+      getStep: () => empty,
+    },
+    timeline: { turnOrder: [], turns: new Map() },
+    legacy: {
+      nodes: settled,
+      runningCalls: running,
+      partial: null,
+      turnTimings: new Map(),
+      turnEnds: new Map(),
+    },
+  }
+}
+
 /**
  * Bind ui-tool's details renderer to the conversation slot callback shape.
  * @param t - conversation locale seat used by Tool cards.
@@ -16,7 +57,7 @@ export function renderToolDetails(t: TranslateNS<'conversation'>): DetailsSlotPr
   return (_key, owner) => {
     // PropsRenderSlots keeps its key generic even for this one-key share;
     // recover the concrete owner selected by the adapter's fixed slot.
-    const details = owner as DetailsToolOwnerProps
+    const details = owner as unknown as DetailsToolOwnerProps
     return <ToolDetails block={details.block} cwd={details.cwd} t={t} />
   }
 }
diff --git a/packages/client/ui-tool/tests/toolview-slot.spec.tsx b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
index c927cc30ea..f1a9df3392 100644
--- a/packages/client/ui-tool/tests/toolview-slot.spec.tsx
+++ b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
@@ -18,6 +18,7 @@ import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { apply as applyConversation, inject as injectConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { apply as applyTool, inject as injectTool } from '@deepseek-ai/dsh-client-ui-tool/client'
 import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client'
+import { toolChatSnapshot } from './tool-details-render.tsx'
 
 const SID = 's1' as SessionId
 
@@ -71,7 +72,7 @@ async function bench(nodes: ToolResultNode[]) {
   await runtime.sessions.add({
     id: SID,
     summary: { title: 'S', displayTitle: 'S' },
-    snapshot: { nodes },
+    snapshot: { nodes, chat: toolChatSnapshot(nodes) },
     session: {
       loadOlder: vi.fn<ISession['loadOlder']>(),
       prompt: vi.fn<ISession['prompt']>(async () => ({ ok: true, value: { accepted: true } })),
diff --git a/packages/client/ui-tool/tests/web-card.spec.tsx b/packages/client/ui-tool/tests/web-card.spec.tsx
index 7856ae9d6f..44f9e05090 100644
--- a/packages/client/ui-tool/tests/web-card.spec.tsx
+++ b/packages/client/ui-tool/tests/web-card.spec.tsx
@@ -23,7 +23,7 @@ import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/cli
 import { GenericToolCard } from '../src/client/tool/toolviews/GenericToolCard.tsx'
 import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/DetailsPanel.tsx'
 import { WebRow, webToolview } from '../src/client/tool/toolviews/web-row.tsx'
-import { renderToolDetails, SessionProviderStub } from './tool-details-render.tsx'
+import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.tsx'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
@@ -234,8 +234,11 @@ describe('DetailsPanel web Output section', () => {
   }
 
   function snapshot(over: Partial<ConversationSnapshot> = {}): ConversationSnapshot {
+    const nodes = over.nodes ?? []
+    const runningCalls = over.runningCalls ?? []
     return {
-      sessionId: SID, nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
+      sessionId: SID, chat: over.chat ?? toolChatSnapshot(nodes, runningCalls),
+      nodes: [], turnTimings: new Map(), turnEnds: new Map(), partial: null, runningCalls: [],
       pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
       openState: 'open', openError: null, hasMore: false, loadingOlder: false,
       promptError: null, blank: false, subagent: null, lastAgentError: null, ...over,
diff --git a/packages/client/web-react/tests/scoped-slots.spec.tsx b/packages/client/web-react/tests/scoped-slots.spec.tsx
index 16334ff7c7..0688d409b9 100644
--- a/packages/client/web-react/tests/scoped-slots.spec.tsx
+++ b/packages/client/web-react/tests/scoped-slots.spec.tsx
@@ -90,6 +90,7 @@ function makeHost() {
   const provide = observable<SessionMaybeProvideInfo>(absentInfo)
   let currentId: string | undefined
   const infos = new Map<string, SessionProvideInfo>()
+  const sessionSources = new Map<string, ReturnType<typeof observable<unknown>>>()
 
   const bump = (key: string) => {
     versions.set(key, (versions.get(key) ?? 0) + 1)
@@ -160,17 +161,24 @@ function makeHost() {
         bump(key)
       }
     },
-    addSession: (id: string): SessionProvideInfo => {
+    addSession: (id: string, initial: unknown = { sid: id }): SessionProvideInfo => {
       // Bare source per bundle (identity-stable): the machinery binds useSession from it.
+      const session = observable<unknown>(initial)
       const info: SessionProvideInfo = {
         sessionId: id,
-        hooks: { session: { getSnapshot: () => ({ sid: id }), subscribe: () => () => {} } },
+        hooks: { session },
         props: {},
       }
+      sessionSources.set(id, session)
       infos.set(id, info)
       if (currentId === id) provide.set(info)
       return info
     },
+    setSession: (id: string, snapshot: unknown) => {
+      const source = sessionSources.get(id)
+      if (source === undefined) throw new Error(`unknown test session: ${id}`)
+      source.set(snapshot)
+    },
   }
 }
 
@@ -635,6 +643,71 @@ describe('standard-kit synthesis', () => {
     expect(props['sessionId']).toBe('s1')
   })
 
+  it('binds only function-valued inject hooks to the standard kit and render occurrence context', () => {
+    const h = makeHost()
+    const turnDataFactory = vi.fn((standard: AnyProps, turn: unknown) => (key: string) => {
+      const useSession = standard['useSession'] as (selector: (snapshot: unknown) => unknown) => unknown
+      return useSession((snapshot) => {
+        const value = snapshot as { turns: Record<number, Record<string, unknown>> }
+        return value.turns[turn as number]?.[key]
+      })
+    })
+    const sessionSpec: DeclaredSpec = {
+      kind: 'single', scope: 'session', inject: { hooks: { turnData: turnDataFactory } },
+    }
+    h.declare('k.session', sessionSpec)
+    h.addSession('s1', {
+      turns: { 1: { tail: 'one' }, 2: { tail: 'two' } },
+      unrelated: 0,
+    })
+    const hooks = new Map<string, Array<(key: string) => unknown>>()
+    let renders = 0
+    h.add('k.session', {
+      component: ({ label, useTurnData }: { label: string; useTurnData: (key: string) => unknown }) => {
+        renders += 1
+        const seen = hooks.get(label) ?? []
+        seen.push(useTurnData)
+        hooks.set(label, seen)
+        return <b data-turn={label}>{String(useTurnData('tail'))}</b>
+      },
+    })
+    const { view } = mountRoot(h, { 'k.session': sessionSpec }, renderSlot => (
+      <SessionProvider>{() => <>
+        {renderSlot('k.session', { label: 'one' }, { hookContext: 1 })}
+        {renderSlot('k.session', { label: 'two' }, { hookContext: 2 })}
+      </>}
+      </SessionProvider>
+    ))
+    act(() => { h.current.set('s1') })
+    expect(view.container.textContent).toBe('onetwo')
+    expect(renders).toBe(2)
+
+    // A session publication whose selected contextual value is identical is
+    // filtered by the framework-bound selector.
+    act(() => {
+      h.setSession('s1', {
+        turns: { 1: { tail: 'one' }, 2: { tail: 'two' } },
+        unrelated: 1,
+      })
+    })
+    expect(renders).toBe(2)
+
+    // Updating the selected contextual value re-renders through the returned
+    // custom Hook; the factory itself and its Hook identity stay stable.
+    act(() => {
+      h.setSession('s1', {
+        turns: { 1: { tail: 'updated' }, 2: { tail: 'two' } },
+        unrelated: 1,
+      })
+    })
+    expect(view.container.textContent).toBe('updatedtwo')
+    expect(renders).toBe(3)
+    expect(hooks.get('one')![1]).toBe(hooks.get('one')![0])
+    expect(hooks.get('two')).toHaveLength(1)
+    expect(hooks.get('one')![0]).not.toBe(hooks.get('two')![0])
+    expect(turnDataFactory).toHaveBeenCalledTimes(2)
+  })
+
   it('hands the SessionProvider seat to entries declaring a session-scope child', () => {
     const h = makeHost()
     h.declare('k.session', SINGLE_SESSION)
diff --git a/packages/compact/command-compact/tests/command-compact.spec.ts b/packages/compact/command-compact/tests/command-compact.spec.ts
index 6922778a26..0c419d6799 100644
--- a/packages/compact/command-compact/tests/command-compact.spec.ts
+++ b/packages/compact/command-compact/tests/command-compact.spec.ts
@@ -4,6 +4,7 @@ import Loader from '@cordisjs/plugin-loader'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import CommandService, { type CommandResult } from '@deepseek-ai/dsh-commands'
 import {
+  CompactionId,
   CompactService,
   ManualCompactionError,
   type CompactAgentContext,
@@ -14,7 +15,10 @@ import {
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import * as commandCompact from '@deepseek-ai/dsh-command-compact'
 
+const COMPACTION_ID = CompactionId('command-compact-test')
+
 const RESULT: CompactionResult = {
+  compactionId: COMPACTION_ID,
   startSeq: 1,
   summarySeq: 2,
   endSeq: 3,
@@ -45,18 +49,28 @@ class StubCompactService extends CompactService {
   override compactNow(
     agent: ManualCompactAgentContext,
     signal: AbortSignal,
+    sourceCommandId?: Parameters<CompactService['compactNow']>[2],
   ): Promise<CompactionResult | null> {
     this.calls.push({ agent, signal })
     if (this.operation !== undefined) return this.operation()
     return this.failure === undefined
-      ? Promise.resolve(this.result === null ? null : this.appendResult(agent, this.result))
+      ? Promise.resolve(this.result === null ? null : this.appendResult(agent, this.result, sourceCommandId))
       // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- exercise arbitrary backend rejection values.
       : Promise.reject(this.failure)
   }
 
-  private appendResult(agent: ManualCompactAgentContext, result: CompactionResult): CompactionResult {
-    agent.session.append('compact/start', { turn: null })
+  private appendResult(
+    agent: ManualCompactAgentContext,
+    result: CompactionResult,
+    sourceCommandId: Parameters<CompactService['compactNow']>[2],
+  ): CompactionResult {
+    const provenance = {
+      compactionId: result.compactionId,
+      ...sourceCommandId === undefined ? {} : { sourceCommandId },
+    }
+    agent.session.append('compact/start', { ...provenance, turn: null })
     agent.session.append('compact/summary', {
+      ...provenance,
       summary: result.summary,
       shadowedRange: result.shadowedRange,
       shadowedSeqs: result.shadowedSeqs,
@@ -64,8 +78,8 @@ class StubCompactService extends CompactService {
       provider: 'command-test',
       model: 'command-test',
     })
-    agent.session.append('compact/end', { turn: null })
-    return result
+    agent.session.append('compact/end', { ...provenance, turn: null })
+    return { ...result, ...provenance }
   }
 }
 
diff --git a/packages/compact/command-compact/tests/loader-composition.spec.ts b/packages/compact/command-compact/tests/loader-composition.spec.ts
index 5a5d37d8b1..5f7fd0b346 100644
--- a/packages/compact/command-compact/tests/loader-composition.spec.ts
+++ b/packages/compact/command-compact/tests/loader-composition.spec.ts
@@ -9,6 +9,7 @@ import Include from '@cordisjs/plugin-include'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import CommandService from '@deepseek-ai/dsh-commands'
 import {
+  CompactionId,
   CompactService,
   type CompactAgentContext,
   type CompactionResult,
@@ -18,7 +19,10 @@ import {
 import * as commandCompact from '@deepseek-ai/dsh-command-compact'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 
+const COMPACTION_ID = CompactionId('loader-command-compact-test')
+
 const RESULT: CompactionResult = {
+  compactionId: COMPACTION_ID,
   startSeq: 1,
   summarySeq: 2,
   endSeq: 3,
@@ -44,9 +48,15 @@ class LoaderCompactService extends CompactService {
   override compactNow(
     agent: ManualCompactAgentContext,
     _signal: AbortSignal,
+    sourceCommandId?: Parameters<CompactService['compactNow']>[2],
   ): Promise<CompactionResult | null> {
-    agent.session.append('compact/start', { turn: null })
+    const provenance = {
+      compactionId: RESULT.compactionId,
+      ...sourceCommandId === undefined ? {} : { sourceCommandId },
+    }
+    agent.session.append('compact/start', { ...provenance, turn: null })
     agent.session.append('compact/summary', {
+      ...provenance,
       summary: RESULT.summary,
       shadowedRange: RESULT.shadowedRange,
       shadowedSeqs: RESULT.shadowedSeqs,
@@ -54,8 +64,8 @@ class LoaderCompactService extends CompactService {
       provider: 'loader-test',
       model: 'loader-test',
     })
-    agent.session.append('compact/end', { turn: null })
-    return Promise.resolve(RESULT)
+    agent.session.append('compact/end', { ...provenance, turn: null })
+    return Promise.resolve({ ...RESULT, ...provenance })
   }
 }
 
@@ -132,11 +142,17 @@ describe('command-compact real Loader composition', () => {
       },
       {
         type: 'compact/start',
-        data: { turn: null },
+        data: {
+          compactionId: COMPACTION_ID,
+          sourceCommandId: execution.commandId,
+          turn: null,
+        },
       },
       {
         type: 'compact/summary',
         data: {
+          compactionId: COMPACTION_ID,
+          sourceCommandId: execution.commandId,
           summary: RESULT.summary,
           shadowedRange: RESULT.shadowedRange,
           shadowedSeqs: RESULT.shadowedSeqs,
@@ -147,7 +163,11 @@ describe('command-compact real Loader composition', () => {
       },
       {
         type: 'compact/end',
-        data: { turn: null },
+        data: {
+          compactionId: COMPACTION_ID,
+          sourceCommandId: execution.commandId,
+          turn: null,
+        },
       },
       {
         type: 'command/done',
diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts
index 996d5d61e1..f97aaf52b9 100644
--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -4,7 +4,7 @@ import BasicCompactService from '@deepseek-ai/dsh-compact-basic'
 import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic'
 import { selectCompactableRange } from '@deepseek-ai/dsh-compact-basic/src/region.ts'
 import type { SummarizationInput, SummaryResult } from '@deepseek-ai/dsh-compact-basic/src/summarizer.ts'
-import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
+import { CompactionId, toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
 import {
   resolveCompactSpec,
   resolveConfig,
@@ -945,7 +945,10 @@ describe('compaction region transaction', () => {
     )).rejects.toThrow(/no open turn/)
 
     const locked = conversation(1)
-    locked.append('compact/start', { turn: 2 })
+    locked.append('compact/start', {
+      compactionId: CompactionId('locked-compaction'),
+      turn: 2,
+    })
     const lockedNodes = locked.surface.nodes
     await expect(compact.compactRegion(
       lockedNodes[0]!,
@@ -1623,6 +1626,7 @@ describe('automatic listener and loader composition', () => {
     const compact = new TestCompactService(ctx)
     const session = conversation(2)
     const fakeResult: CompactionResult = {
+      compactionId: CompactionId('fake-compaction'),
       startSeq: 1,
       summarySeq: 2,
       endSeq: 3,
diff --git a/packages/compact/compact-basic/tests/manual-compact.spec.ts b/packages/compact/compact-basic/tests/manual-compact.spec.ts
index 7544c3223b..0599d3f364 100644
--- a/packages/compact/compact-basic/tests/manual-compact.spec.ts
+++ b/packages/compact/compact-basic/tests/manual-compact.spec.ts
@@ -3,13 +3,14 @@ import { Context } from 'cordis'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import InvariantService from '@deepseek-ai/dsh-invariants'
+import { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
 import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
 import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
 import * as CompactInvariant from '@deepseek-ai/dsh-compact/invariant'
 import * as CompactBasicInvariant from '@deepseek-ai/dsh-compact-basic/invariant'
 import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
-import { isCompactCheckpointSource, ManualCompactionError } from '@deepseek-ai/dsh-compact'
+import { CompactionId, isCompactCheckpointSource, ManualCompactionError } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
 import {
   createAssistantMessage,
@@ -23,7 +24,7 @@ import type {
   StreamChunk,
   TokenUsage,
 } from '@deepseek-ai/dsh-llm'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import LlmService from '@deepseek-ai/dsh-llm'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -394,22 +395,35 @@ describe('compactNow transaction and failure classification', () => {
     const { compact, flushes } = detachedService()
     const session = closedConversation(2, 7)
     const agent = fakeAgent(session, () => () => undefined)
+    const commandId = CommandId('manual-compact-command')
 
-    const result = await compact.compactNow(agent, SIGNAL)
+    const result = await compact.compactNow(agent, SIGNAL, commandId)
 
     expect(result).not.toBeNull()
+    expect(result?.sourceCommandId).toBe(commandId)
     expect(flushes()).toBe(1)
     expect(session.events.filter(event => event.type === 'turn/start').at(-1)?.data.turn).toBe(7)
-    expect(session.events.findLast(event => event.type === 'compact/start')?.data)
-      .toEqual({ turn: null })
-    expect(session.events.findLast(event => event.type === 'compact/end')?.data)
-      .toEqual({ turn: null })
+    const start = session.events.findLast(event => event.type === 'compact/start')
+    const summaryEvent = session.events.findLast(event => event.type === 'compact/summary')
+    const checkpoint = session.events.findLast(
+      (event): event is SessionEvent<'user/message'> => event.type === 'user/message'
+        && isCompactCheckpointSource(event.data.source),
+    )
+    const end = session.events.findLast(event => event.type === 'compact/end')
+    const correlated = { compactionId: result?.compactionId, sourceCommandId: commandId }
+    expect(start?.data).toEqual({ ...correlated, turn: null })
+    expect(summaryEvent?.data.sourceCommandId).toBe(commandId)
+    expect(checkpoint?.data.source).toMatchObject(correlated)
+    expect(end?.data).toEqual({ ...correlated, turn: null })
   })
 
   it('reports a live unmatched bracket as busy without summarizing', async () => {
     const { compact } = detachedService()
     const session = closedConversation(2)
-    session.append('compact/start', { turn: null })
+    session.append('compact/start', {
+      compactionId: CompactionId('live-manual-compaction'),
+      turn: null,
+    })
     const agent = fakeAgent(session, () => () => undefined)
 
     const error = await rejection(() => compact.compactNow(agent, SIGNAL))
@@ -421,7 +435,10 @@ describe('compactNow transaction and failure classification', () => {
   it('ignores an unmatched bracket inherited before a later end-seed marker', async () => {
     const { compact } = detachedService()
     const original = closedConversation(2)
-    original.append('compact/start', { turn: null })
+    original.append('compact/start', {
+      compactionId: CompactionId('stale-manual-compaction'),
+      turn: null,
+    })
     const reloaded = Session.create(SessionId('stale-orphan'), [...original.events])
     const boundary = reloaded.events.findLast(event => event.type === 'session/end-seed')
     const orphan = reloaded.events.find(event => event.type === 'compact/start')
@@ -435,7 +452,10 @@ describe('compactNow transaction and failure classification', () => {
   it('scans a stale orphan independently of later repaired turn state', async () => {
     const { compact } = detachedService()
     const original = closedConversation(2)
-    original.append('compact/start', { turn: null })
+    original.append('compact/start', {
+      compactionId: CompactionId('reloaded-manual-compaction'),
+      turn: null,
+    })
     original.append('turn/start', { turn: 3 })
     original.append('turn/end', { turn: 3, reason: { kind: 'interrupted' } })
     const reloaded = Session.create(SessionId('reloaded-orphan'), [...original.events])
@@ -664,7 +684,7 @@ describe('compactNow transaction and failure classification', () => {
     expect(result).not.toBeNull()
     expect(session.events.some(event => event.type === 'turn/start')).toBe(false)
     expect(session.events.find(event => event.type === 'compact/start')?.data)
-      .toEqual({ turn: null })
+      .toEqual({ compactionId: result?.compactionId, turn: null })
   })
 
   it('classifies a durability failure after the standalone bracket committed', async () => {
@@ -676,8 +696,9 @@ describe('compactNow transaction and failure classification', () => {
     expect((await rejection(compact.compactNow(agent, SIGNAL))).code).toBe('persistence')
     vi.restoreAllMocks()
     expect(session.events.some(event => event.type === 'compact/summary')).toBe(true)
-    expect(session.events.findLast(event => event.type === 'compact/end')?.data)
-      .toEqual({ turn: null })
+    const start = session.events.findLast(event => event.type === 'compact/start')
+    const end = session.events.findLast(event => event.type === 'compact/end')
+    expect(end?.data).toEqual({ compactionId: start?.data.compactionId, turn: null })
   })
 
   it('lets a pre-aborted signal win before reservation, measurement, or summarization', async () => {
diff --git a/packages/compact/compact/tests/compact.spec.ts b/packages/compact/compact/tests/compact.spec.ts
index 7e6915354f..74e2bd0270 100644
--- a/packages/compact/compact/tests/compact.spec.ts
+++ b/packages/compact/compact/tests/compact.spec.ts
@@ -2,8 +2,9 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import {
-  COMPACT_CHECKPOINT_SOURCE,
+  CompactionId,
   CompactService,
+  compactCheckpointSource,
   isCompactCheckpointSource,
 } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult, CompactionTrigger } from '@deepseek-ai/dsh-compact'
@@ -52,9 +53,11 @@ class StubCompactService extends CompactService {
     const endIndex = surface.indexOf(end)
     if (startIndex < 0 || endIndex < startIndex) throw new Error('stub compact range is invalid')
     const shadowedSeqs = surface.slice(startIndex, endIndex + 1)
+    const compactionId = CompactionId('stub-compaction')
     // Minimal stub honoring the lock + log-only event contract.
-    const startEvent = session.append('compact/start', { turn: 0 })
+    const startEvent = session.append('compact/start', { compactionId, turn: 0 })
     const summaryEvent = session.append('compact/summary', {
+      compactionId,
       summary,
       shadowedRange: { start, end },
       shadowedSeqs,
@@ -64,13 +67,14 @@ class StubCompactService extends CompactService {
     })
     session.append('user/message', createUserMessage({
       content: summary,
-      source: COMPACT_CHECKPOINT_SOURCE,
+      source: compactCheckpointSource(compactionId),
     }), {
       surfaceOp: { op: 'replace', start, end },
       sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs],
     })
-    const endEvent = session.append('compact/end', { turn: 0 })
+    const endEvent = session.append('compact/end', { compactionId, turn: 0 })
     return {
+      compactionId,
       startSeq: startEvent.seq,
       summarySeq: summaryEvent.seq,
       endSeq: endEvent.seq,
@@ -139,7 +143,8 @@ describe('CompactService seam', () => {
     expect(result.shadowedSeqs).toEqual([original.seq])
     const checkpoint = session.events.find(event => event.type === 'user/message'
       && isCompactCheckpointSource(event.data.source))
-    expect(checkpoint?.type === 'user/message' && checkpoint.data.source).toEqual(COMPACT_CHECKPOINT_SOURCE)
+    expect(checkpoint?.type === 'user/message' && checkpoint.data.source)
+      .toEqual(compactCheckpointSource(result.compactionId))
     expect(isCompactCheckpointSource({ kind: 'plugin', plugin: 'other' })).toBe(false)
     expect(isCompactCheckpointSource({ kind: 'user' })).toBe(false)
     expect(session.events.filter(e => e.type.startsWith('compact/')).map(e => e.type))
diff --git a/packages/compact/compact/tests/invariant.spec.ts b/packages/compact/compact/tests/invariant.spec.ts
index c5a68c9de6..1637c16179 100644
--- a/packages/compact/compact/tests/invariant.spec.ts
+++ b/packages/compact/compact/tests/invariant.spec.ts
@@ -1,7 +1,10 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { CompactionId, compactCheckpointSource } from '@deepseek-ai/dsh-compact'
 import * as CompactInvariant from '@deepseek-ai/dsh-compact/invariant'
+import { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 
 async function setup(): Promise<Context> {
@@ -12,7 +15,13 @@ async function setup(): Promise<Context> {
   return ctx
 }
 
+const TEST_COMPACTION_ID = CompactionId('test-compaction')
+const NEXT_COMPACTION_ID = CompactionId('next-test-compaction')
+const TEST_COMMAND_ID = CommandId('test-command')
+const NEXT_COMMAND_ID = CommandId('next-test-command')
+
 const summary = (overrides: Record<string, unknown> = {}) => ({
+  compactionId: TEST_COMPACTION_ID,
   summary: [{ type: 'text' as const, text: 'short' }],
   shadowedRange: { start: 2, end: 4 },
   shadowedSeqs: [2, 3, 4],
@@ -31,33 +40,33 @@ describe('compaction invariants', () => {
     const ctx = await setup()
     const success = ctx.sessions.create()
     startTurn(success)
-    success.append('compact/start', { turn: 1 })
+    success.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     success.append('compact/summary', summary())
-    success.append('compact/end', { turn: 1 })
+    success.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 1 })
 
     const failed = ctx.sessions.create()
     startTurn(failed, 2)
-    failed.append('compact/start', { turn: 2 })
-    failed.append('compact/end', { turn: 2, error: 'provider failed' })
+    failed.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 2 })
+    failed.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 2, error: 'provider failed' })
   })
 
   it('accepts standalone successful and failed compaction lifecycles between turns', async () => {
     const ctx = await setup()
     const success = ctx.sessions.create()
-    success.append('compact/start', { turn: null })
+    success.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
     success.append('compact/summary', summary())
-    success.append('compact/end', { turn: null })
+    success.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: null })
 
     const failed = ctx.sessions.create()
-    failed.append('compact/start', { turn: null })
-    failed.append('compact/end', { turn: null, error: 'provider failed' })
+    failed.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
+    failed.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: null, error: 'provider failed' })
   })
 
   it('clears an inherited open compaction trace at end-seed during replay', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const source = Session.create(SessionId('stale-compaction-source'))
-    source.append('compact/start', { turn: null })
+    source.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
     const replayed = ctx.sessions.create(SessionId('stale-compaction-replay'), {
       seed: source.events,
     })
@@ -68,8 +77,8 @@ describe('compaction invariants', () => {
     await ctx.plugin(CompactInvariant)
 
     expect(() => {
-      replayed.append('compact/start', { turn: null })
-      replayed.append('compact/end', { turn: null, error: 'new attempt failed' })
+      replayed.append('compact/start', { compactionId: NEXT_COMPACTION_ID, turn: null })
+      replayed.append('compact/end', { compactionId: NEXT_COMPACTION_ID, turn: null, error: 'new attempt failed' })
     }).not.toThrow()
   })
 
@@ -78,7 +87,7 @@ describe('compaction invariants', () => {
     await ctx.plugin(SessionStore)
     const source = Session.create(SessionId('stale-numbered-compaction-source'))
     startTurn(source)
-    source.append('compact/start', { turn: 1 })
+    source.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     const replayed = ctx.sessions.create(SessionId('stale-numbered-compaction-replay'), {
       seed: source.events,
     })
@@ -98,7 +107,7 @@ describe('compaction invariants', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const source = Session.create(SessionId('stale-repaired-compaction-source'))
-    source.append('compact/start', { turn: null })
+    source.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
     startTurn(source)
     source.append('turn/end', { turn: 1, reason: { kind: 'interrupted' } })
     const replayed = ctx.sessions.create(SessionId('stale-repaired-compaction-replay'), {
@@ -124,10 +133,10 @@ describe('compaction invariants', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const source = Session.create(SessionId('closed-nested-compaction-source'))
-    source.append('compact/start', { turn: null })
+    source.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
     startTurn(source)
     source.append('turn/end', { turn: 1, reason: { kind: 'interrupted' } })
-    source.append('compact/end', { turn: null, error: 'failed after crossing turn' })
+    source.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: null, error: 'failed after crossing turn' })
     const replayed = ctx.sessions.create(SessionId('closed-nested-compaction-replay'), {
       seed: source.events,
     })
@@ -143,10 +152,14 @@ describe('compaction invariants', () => {
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create()
     session.append('turn/start', { turn: 1 })
-    session.append('compact/start', { turn: 1 })
+    session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     await ctx.plugin(InvariantService)
     await ctx.plugin(CompactInvariant)
-    expect(() => session.append('compact/end', { turn: 1, error: 'resume failed' })).not.toThrow()
+    expect(() => session.append('compact/end', {
+      compactionId: TEST_COMPACTION_ID,
+      turn: 1,
+      error: 'resume failed',
+    })).not.toThrow()
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
   })
 
@@ -162,7 +175,8 @@ describe('compaction invariants', () => {
         type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 },
       })
       ctx.emit('session/event', session, {
-        type: 'compact/start', seq: 2, time: 2, data: { turn: 1 },
+        type: 'compact/start', seq: 2, time: 2,
+        data: { compactionId: TEST_COMPACTION_ID, turn: 1 },
       })
     }).not.toThrow()
   })
@@ -170,28 +184,30 @@ describe('compaction invariants', () => {
   it('rejects compaction outside or for a different open turn', async () => {
     const ctx = await setup()
     const session = ctx.sessions.create()
-    expect(() => session.append('compact/start', { turn: 1 })).toThrow(/outside any open turn/)
+    expect(() => session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 }))
+      .toThrow(/outside any open turn/)
     startTurn(session)
-    expect(() => session.append('compact/start', { turn: 2 })).toThrow(/but open turn is 1/)
+    expect(() => session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 2 }))
+      .toThrow(/but open turn is 1/)
   })
 
   it('rejects a standalone bracket while a turn is open and a numbered bracket between turns', async () => {
     const ctx = await setup()
     const open = ctx.sessions.create()
     startTurn(open)
-    expect(() => open.append('compact/start', { turn: null }))
+    expect(() => open.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null }))
       .toThrow(/standalone but turn 1 is open/)
 
     const idle = ctx.sessions.create()
-    expect(() => idle.append('compact/start', { turn: 1 }))
+    expect(() => idle.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 }))
       .toThrow(/outside any open turn/)
   })
 
   it('attributes a nested standalone start to the standalone owner', async () => {
     const ctx = await setup()
     const session = ctx.sessions.create()
-    session.append('compact/start', { turn: null })
-    expect(() => session.append('compact/start', { turn: null }))
+    session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
+    expect(() => session.append('compact/start', { compactionId: NEXT_COMPACTION_ID, turn: null }))
       .toThrow(/standalone compaction is still compacting/)
   })
 
@@ -201,7 +217,7 @@ describe('compaction invariants', () => {
     const session = ctx.sessions.create()
     startTurn(session)
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    session.append('compact/start', { turn: 1 })
+    session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     await ctx.plugin(InvariantService)
     await expect(ctx.plugin(CompactInvariant).then(() => undefined)).rejects.toThrow(/outside any open turn/)
   })
@@ -209,10 +225,10 @@ describe('compaction invariants', () => {
   it('rejects turn boundaries that cross live standalone or numbered compaction brackets', async () => {
     const ctx = await setup()
     const standalone = ctx.sessions.create()
-    standalone.append('compact/start', { turn: null })
+    standalone.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: null })
     expect(() => { startTurn(standalone) })
       .toThrow(/turn\/start cannot cross an open standalone compaction/)
-    standalone.append('compact/end', { turn: null, error: 'cancelled' })
+    standalone.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: null, error: 'cancelled' })
     expect(() => {
       startTurn(standalone)
       standalone.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
@@ -220,53 +236,151 @@ describe('compaction invariants', () => {
 
     const numbered = ctx.sessions.create()
     startTurn(numbered)
-    numbered.append('compact/start', { turn: 1 })
+    numbered.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     expect(() => numbered.append(
       'turn/end',
       { turn: 1, reason: { kind: 'completed' } },
     )).toThrow(/turn\/end cannot cross an open compaction for turn 1/)
-    numbered.append('compact/end', { turn: 1, error: 'cancelled' })
+    numbered.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 1, error: 'cancelled' })
     expect(() => numbered.append(
       'turn/end',
       { turn: 1, reason: { kind: 'completed' } },
     )).not.toThrow()
   })
 
+  it('rejects a replacement checkpoint for another compaction transaction', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create()
+    const original = session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'original' }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    startTurn(session)
+    session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+    session.append('compact/summary', summary())
+
+    expect(() => session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'checkpoint' }],
+      source: compactCheckpointSource(NEXT_COMPACTION_ID),
+    }), {
+      surfaceOp: { op: 'replace', start: original.seq, end: original.seq },
+      sourceEventSeqs: [original.seq],
+    })).toThrow(/compaction checkpoint id .* does not match compact\/start id/)
+  })
+
+  it('requires checkpoint provenance to name an open transaction', async () => {
+    const ctx = await setup()
+    const withoutStart = ctx.sessions.create()
+    const original = withoutStart.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'original' }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    expect(() => withoutStart.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'checkpoint' }],
+      source: compactCheckpointSource(TEST_COMPACTION_ID),
+    }), {
+      surfaceOp: { op: 'replace', start: original.seq, end: original.seq },
+      sourceEventSeqs: [original.seq],
+    })).toThrow(/no matching compact\/start/)
+
+    const emptyCommand = ctx.sessions.create()
+    const replaced = emptyCommand.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'original' }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+    startTurn(emptyCommand)
+    emptyCommand.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+    expect(() => emptyCommand.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'checkpoint' }],
+      source: compactCheckpointSource(TEST_COMPACTION_ID, CommandId('')),
+    }), {
+      surfaceOp: { op: 'replace', start: replaced.seq, end: replaced.seq },
+      sourceEventSeqs: [replaced.seq],
+    })).toThrow(/checkpoint sourceCommandId must be a non-empty string/)
+  })
+
   it.each([
+    ['empty start id', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', { compactionId: CompactionId(''), turn: 1 })
+    }, /compact\/start compactionId must be a non-empty string/],
+    ['empty start source command id', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', {
+        compactionId: TEST_COMPACTION_ID,
+        sourceCommandId: CommandId(''),
+        turn: 1,
+      })
+    }, /compact\/start sourceCommandId must be a non-empty string/],
     ['summary without start', (session: ReturnType<Context['sessions']['create']>) => {
       session.append('compact/summary', summary())
     }, /no matching compact\/start/],
     ['nested start', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
-      session.append('compact/start', { turn: 2 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compact/start', { compactionId: NEXT_COMPACTION_ID, turn: 2 })
     }, /still compacting/],
     ['repeated summary', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
       session.append('compact/summary', summary())
       session.append('compact/summary', summary())
     }, /repeated within one compaction/],
+    ['summary for another compaction', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compact/summary', summary({ compactionId: NEXT_COMPACTION_ID }))
+    }, /compact\/summary id .* does not match compact\/start id/],
+    ['summary for another source command', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', {
+        compactionId: TEST_COMPACTION_ID,
+        sourceCommandId: TEST_COMMAND_ID,
+        turn: 1,
+      })
+      session.append('compact/summary', summary({ sourceCommandId: NEXT_COMMAND_ID }))
+    }, /compact\/summary sourceCommandId .* does not match compact\/start sourceCommandId/],
     ['empty shadow set', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
       session.append('compact/summary', summary({ shadowedSeqs: [] }))
     }, /shadowedSeqs must be non-empty/],
     ['wrong endpoints', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
       session.append('compact/summary', summary({ shadowedRange: { start: 1, end: 4 } }))
     }, /shadowedRange must match/],
     ['invalid token count', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
       session.append('compact/summary', summary({ shadowedTokenCount: -1 }))
     }, /non-negative safe integer/],
     ['end without start', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/end', { turn: 1, error: 'failed' })
+      session.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 1, error: 'failed' })
     }, /no matching compact\/start/],
     ['wrong end turn', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
-      session.append('compact/end', { turn: 2, error: 'failed' })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 2, error: 'failed' })
     }, /does not match/],
+    ['end for another compaction', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compact/end', { compactionId: NEXT_COMPACTION_ID, turn: 1, error: 'failed' })
+    }, /compact\/end id .* does not match compact\/start id/],
+    ['end missing the source command', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', {
+        compactionId: TEST_COMPACTION_ID,
+        sourceCommandId: TEST_COMMAND_ID,
+        turn: 1,
+      })
+      session.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 1, error: 'failed' })
+    }, /compact\/end sourceCommandId .* does not match compact\/start sourceCommandId/],
+    ['empty end source command id', (session: ReturnType<Context['sessions']['create']>) => {
+      session.append('compact/start', {
+        compactionId: TEST_COMPACTION_ID,
+        sourceCommandId: TEST_COMMAND_ID,
+        turn: 1,
+      })
+      session.append('compact/end', {
+        compactionId: TEST_COMPACTION_ID,
+        sourceCommandId: CommandId(''),
+        turn: 1,
+        error: 'failed',
+      })
+    }, /compact\/end sourceCommandId must be a non-empty string/],
     ['success without summary', (session: ReturnType<Context['sessions']['create']>) => {
-      session.append('compact/start', { turn: 1 })
-      session.append('compact/end', { turn: 1 })
+      session.append('compact/start', { compactionId: TEST_COMPACTION_ID, turn: 1 })
+      session.append('compact/end', { compactionId: TEST_COMPACTION_ID, turn: 1 })
     }, /requires one compact\/summary/],
   ])('rejects %s', async (_name, action, message) => {
     const ctx = await setup()
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index fcdcd7c422..585397d861 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -196,11 +196,15 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent {
 }
 
 function stubToolExecution(
-  input: Omit<ToolExecution, 'token'> & { token?: ToolExecutionToken },
+  input: Omit<ToolExecution, 'token' | 'rootCallId'> & {
+    token?: ToolExecutionToken
+    rootCallId?: ToolExecution['rootCallId']
+  },
 ): ToolExecution {
   return {
     token: input.token ?? Symbol('workspace-context-test-execution') as ToolExecutionToken,
     ...input,
+    rootCallId: input.rootCallId ?? input.callId,
   }
 }
 
diff --git a/packages/core/tools/tests/code-mode.spec.ts b/packages/core/tools/tests/code-mode.spec.ts
index 06993467e8..2f3454b03c 100644
--- a/packages/core/tools/tests/code-mode.spec.ts
+++ b/packages/core/tools/tests/code-mode.spec.ts
@@ -785,11 +785,11 @@ describe('the run_code dispatch bridge', () => {
     const dispatches = events.filter(event => event.type === 'tool/code-dispatch')
     expect(dispatches.map(event => event.data)).toEqual([
       {
-        parentCallId: 'call-1', subCallId: 'call-1:code:1', name: 'echo',
+        rootCallId: 'call-1', parentCallId: 'call-1', subCallId: 'call-1:code:1', name: 'echo',
         arguments: { value: 'one' }, isError: false, content: [{ type: 'text', text: 'echo:one' }],
       },
       {
-        parentCallId: 'call-1', subCallId: 'call-1:code:2', name: 'echo',
+        rootCallId: 'call-1', parentCallId: 'call-1', subCallId: 'call-1:code:2', name: 'echo',
         arguments: { value: 'two' }, isError: false, content: [{ type: 'text', text: 'echo:two' }],
       },
     ])
@@ -1526,6 +1526,7 @@ describe('the run_code dispatch bridge', () => {
       content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
     }), { surfaceOp: 'append' })
     session.append('tool/code-dispatch', {
+      rootCallId: CallId('p1'),
       parentCallId: CallId('p1'),
       subCallId: CallId('p1:code:1'),
       name: 'echo',
diff --git a/packages/core/tools/tests/invariant.spec.ts b/packages/core/tools/tests/invariant.spec.ts
index 80ae299da7..8a60c41331 100644
--- a/packages/core/tools/tests/invariant.spec.ts
+++ b/packages/core/tools/tests/invariant.spec.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import { CallId } from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolExecution, ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
 import * as ToolsInvariant from '@deepseek-ai/dsh-tools/invariant'
 import InvariantService from '@deepseek-ai/dsh-invariants'
@@ -24,6 +24,7 @@ const execution = (overrides: Partial<ToolExecution> = {}): ToolExecution => ({
   arguments: Object.freeze({ text: 'hi' }),
   ...overrides,
   signal: overrides.signal ?? testToolSignal,
+  rootCallId: overrides.rootCallId ?? overrides.callId ?? CallId('call-1'),
 })
 
 const outcome = (): ToolExecutionResult => Object.freeze({
@@ -92,6 +93,7 @@ describe('tool-pipeline invariants', () => {
     const ctx = await setup()
     const session = ctx.sessions.create()
     const data = {
+      rootCallId: CallId('parent'),
       parentCallId: CallId('parent'),
       subCallId: CallId('child'),
       name: 'echo',
@@ -103,12 +105,112 @@ describe('tool-pipeline invariants', () => {
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
   })
 
+  it('does not commit a rejected dispatch edge into the root index', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create()
+    expect(() => session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('rejected-root'),
+      parentCallId: CallId('rejected-root'),
+      subCallId: CallId('reused-child'),
+      name: 'echo',
+      arguments: {},
+    })).toThrow(/outside any open turn/)
+
+    session.append('turn/start', { turn: 1 })
+    expect(() => session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('accepted-root'),
+      parentCallId: CallId('accepted-root'),
+      subCallId: CallId('reused-child'),
+      name: 'echo',
+      arguments: {},
+    })).not.toThrow()
+  })
+
+  it('rejects a nested code dispatch that changes its parent chain root before append', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1 })
+    session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('root'),
+      parentCallId: CallId('root'),
+      subCallId: CallId('child'),
+      name: 'run_code',
+      arguments: {},
+    })
+    session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('root'),
+      parentCallId: CallId('child'),
+      subCallId: CallId('grandchild'),
+      name: 'echo',
+      arguments: {},
+    })
+
+    expect(() => session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('another-root'),
+      parentCallId: CallId('child'),
+      subCallId: CallId('invalid-grandchild'),
+      name: 'echo',
+      arguments: {},
+    })).toThrow(/parentCallId child does not belong to rootCallId another-root/)
+    expect(session.events.some(event => event.type === 'tool/code-dispatch-start'
+      && String(event.data.subCallId) === 'invalid-grandchild')).toBe(false)
+  })
+
+  it('requires non-empty dispatch identities and keeps one subcall on one root', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1 })
+    expect(() => session.append('tool/code-dispatch-start', {
+      rootCallId: CallId(''),
+      parentCallId: CallId('root'),
+      subCallId: CallId('child'),
+      name: 'echo',
+      arguments: {},
+    })).toThrow(/must carry non-empty rootCallId/)
+
+    session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('root'),
+      parentCallId: CallId('root'),
+      subCallId: CallId('child'),
+      name: 'echo',
+      arguments: {},
+    })
+    expect(() => session.append('tool/code-dispatch-start', {
+      rootCallId: CallId('other-root'),
+      parentCallId: CallId('other-root'),
+      subCallId: CallId('child'),
+      name: 'echo',
+      arguments: {},
+    })).toThrow(/changed rootCallId for subCallId child/)
+  })
+
+  it('indexes dispatch records emitted for a bare session', async () => {
+    const ctx = await setup()
+    const session = Session.create(SessionId('bare-dispatch-session'))
+    session.append('turn/start', { turn: 1 })
+    expect(() => {
+      ctx.emit('session/event', session as never, {
+        type: 'tool/code-dispatch-start',
+        seq: 1,
+        time: 1,
+        data: {
+          rootCallId: CallId('root'),
+          parentCallId: CallId('root'),
+          subCallId: CallId('child'),
+          name: 'echo',
+          arguments: {},
+        },
+      } as never)
+    }).not.toThrow()
+  })
+
   it('replays enclosed code-dispatch records on late registration', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create()
     session.append('turn/start', { turn: 1 })
     session.append('tool/code-dispatch', {
+      rootCallId: CallId('parent'),
       parentCallId: CallId('parent'),
       subCallId: CallId('child'),
       name: 'echo',
@@ -125,6 +227,7 @@ describe('tool-pipeline invariants', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     ctx.sessions.create().append('tool/code-dispatch-start', {
+      rootCallId: CallId('parent'),
       parentCallId: CallId('parent'),
       subCallId: CallId('child'),
       name: 'echo',
diff --git a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
index 3224487b60..5757e5f245 100644
--- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
@@ -574,6 +574,7 @@ describe('dsh-agent-spine-demo bundle', () => {
       signal: testToolSignal,
       token: Symbol('agent-core-dsh-home-test') as ToolExecution['token'],
       callId: CallId('agent-core-dsh-home'),
+      rootCallId: CallId('agent-core-dsh-home'),
       name: 'bash',
       arguments: { command: 'true' },
     }
diff --git a/packages/llm/llm-retry/tests/invariant.spec.ts b/packages/llm/llm-retry/tests/invariant.spec.ts
index 1c478b226b..33ac3a19fa 100644
--- a/packages/llm/llm-retry/tests/invariant.spec.ts
+++ b/packages/llm/llm-retry/tests/invariant.spec.ts
@@ -5,6 +5,7 @@ import { createUserMessage, ProviderRequestId } from '@deepseek-ai/dsh-llm'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as RetryInvariant from '@deepseek-ai/dsh-llm-retry/invariant'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry/brand'
 import { providerForOpenStep } from '../src/history.ts'
 
 async function setup(): Promise<Context> {
@@ -38,6 +39,7 @@ function appendRetryTurn(session: Session, turn: number) {
 
 const failure = { message: 'provider busy', code: 'RATE_LIMIT', status: 429 }
 const normal = {
+  retryId: RetryId('normal-retry-chain'),
   provider: 'mock',
   mode: 'normal' as const,
   policyKey: 'normal-policy',
@@ -47,6 +49,7 @@ const normal = {
   failure,
 }
 const always = {
+  retryId: RetryId('always-retry-chain'),
   provider: 'mock',
   mode: 'always' as const,
   policyKey: 'always-policy',
@@ -130,6 +133,7 @@ describe('llm-retry invariants', () => {
   })
 
   it.each([
+    ['empty-retry-id', { ...normal, retryId: RetryId('') }, /retryId must be a non-empty string/],
     ['retry-zero', { ...normal, retry: 0 }, /positive safe integer/],
     ['retry-fraction', { ...normal, retry: 1.5 }, /positive safe integer/],
     ['max-zero', { ...normal, maxRetries: 0 }, /positive safe maxRetries/],
@@ -212,10 +216,65 @@ describe('llm-retry invariants', () => {
     reset.append('step/end', { turn: 1, step: 1 })
     reset.append('step/start', { turn: 1, step: 2 })
     expect(() => {
-      reset.append('llm/retry', { turn: 1, step: 2, ...normal })
+      reset.append('llm/retry', {
+        turn: 1,
+        step: 2,
+        ...normal,
+        retryId: RetryId('reset-step-2-retry-chain'),
+      })
     }).not.toThrow()
   })
 
+  it('keeps one retry identity per provider-policy chain', async () => {
+    const ctx = await setup()
+    const changed = openStep(ctx, 'retry-invariant-changed-chain-id')
+    changed.append('llm/retry', { turn: 1, step: 1, ...normal })
+    expect(() => changed.append('llm/retry', {
+      turn: 1,
+      step: 1,
+      ...normal,
+      retry: 2,
+      retryId: RetryId('changed-retry-chain'),
+    })).toThrow(/must preserve retryId/)
+
+    const reused = openStep(ctx, 'retry-invariant-reused-chain-id')
+    reused.append('llm/retry', { turn: 1, step: 1, ...normal })
+    expect(() => reused.append('llm/retry', {
+      turn: 1,
+      step: 1,
+      ...always,
+      retryId: normal.retryId,
+    })).toThrow(/already owned by another chain/)
+  })
+
+  it('validates retry-started correlation and uniqueness', async () => {
+    const ctx = await setup()
+    const empty = openStep(ctx, 'retry-started-empty-id')
+    expect(() => empty.append('llm/retry-started', {
+      retryId: RetryId(''), turn: 1, step: 1, retry: 1,
+    })).toThrow(/retryId must be a non-empty string/)
+
+    const missing = openStep(ctx, 'retry-started-missing-schedule')
+    expect(() => missing.append('llm/retry-started', {
+      retryId: RetryId('missing-retry-chain'), turn: 1, step: 1, retry: 1,
+    })).toThrow(/pairs no prior scheduled attempt/)
+
+    const mismatch = openStep(ctx, 'retry-started-location-mismatch')
+    mismatch.append('llm/retry', { turn: 1, step: 1, ...normal })
+    expect(() => mismatch.append('llm/retry-started', {
+      retryId: normal.retryId, turn: 2, step: 1, retry: 1,
+    })).toThrow(/turn\/step must match/)
+
+    const repeated = openStep(ctx, 'retry-started-repeated')
+    repeated.append('llm/retry', { turn: 1, step: 1, ...normal })
+    repeated.append('llm/retry-started', {
+      retryId: normal.retryId, turn: 1, step: 1, retry: 1,
+    })
+    expect(() => repeated.append('llm/retry-started', {
+      retryId: normal.retryId, turn: 1, step: 1, retry: 1,
+    })).toThrow(/repeats one scheduled attempt/)
+  })
+
   it('starts a fresh retry chain after incomplete predecessor boundaries', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
@@ -261,4 +320,16 @@ describe('llm-retry invariants', () => {
     await ctx.plugin(InvariantService)
     await expect(ctx.plugin(RetryInvariant)).rejects.toThrow(/inside an open turn/)
   })
+
+  it('accepts a scheduled and started attempt on late registration', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const session = openStep(ctx, 'retry-invariant-late-started')
+    session.append('llm/retry', { turn: 1, step: 1, ...normal })
+    session.append('llm/retry-started', {
+      retryId: normal.retryId, turn: 1, step: 1, retry: 1,
+    })
+    await ctx.plugin(InvariantService)
+    await expect(ctx.plugin(RetryInvariant)).resolves.toBeDefined()
+  })
 })
diff --git a/packages/llm/llm-retry/tests/persistence.spec.ts b/packages/llm/llm-retry/tests/persistence.spec.ts
index 36a1fb5dbe..3a605bd40e 100644
--- a/packages/llm/llm-retry/tests/persistence.spec.ts
+++ b/packages/llm/llm-retry/tests/persistence.spec.ts
@@ -6,6 +6,7 @@ import { Context } from 'cordis'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SessionPersistenceSqlite from '@deepseek-ai/dsh-session-persistence-sqlite'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry/brand'
 import type {} from '../src/index.ts'
 
 const dirs: string[] = []
@@ -39,6 +40,7 @@ describe.each(['jsonl', 'sqlite'] as const)('%s retry-event persistence', (kind)
         reason: 'initial',
       })
       const event = session.append('llm/retry', {
+        retryId: RetryId(`retry-${kind}-chain`),
         turn: 1,
         step: 1,
         provider: 'mock',
diff --git a/packages/llm/llm-retry/tests/retry.spec.ts b/packages/llm/llm-retry/tests/retry.spec.ts
index ac0ed687fa..7268c19ec6 100644
--- a/packages/llm/llm-retry/tests/retry.spec.ts
+++ b/packages/llm/llm-retry/tests/retry.spec.ts
@@ -191,7 +191,9 @@ describe('provider-routed retry policy', () => {
     agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }))
     const event = await scheduled
 
+    expect(event.data.retryId).toEqual(expect.any(String))
     expect(event.data).toEqual({
+      retryId: event.data.retryId,
       turn: 1,
       step: 1,
       provider: 'mock',
diff --git a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
index 20cb2cc819..9251eef2c0 100644
--- a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
+++ b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
@@ -10,6 +10,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextBreakdownProjection } from '@deepseek-ai/dsh-token-meter/client'
+import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
 import { contextBreakdownProjectionDefinition } from '../src/breakdown-projection.ts'
 import {
   estimateContent,
@@ -59,6 +60,7 @@ function appendSummaryMeter(ctx: Context, session: Session, start: number, end:
   const endIdx = nodes.findIndex(node => node.seq === end)
   const shadowed = nodes.slice(startIdx, endIdx + 1)
   session.append('compact/summary', {
+    compactionId: CompactionId('context-breakdown-summary'),
     summary: [{ type: 'text', text: 'summary' }],
     shadowedRange: { start, end },
     shadowedSeqs: shadowed.map(node => node.seq),
diff --git a/packages/llm/token-meter/tests/token-usage-projection.spec.ts b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
index 0307b96f46..65771fc877 100644
--- a/packages/llm/token-meter/tests/token-usage-projection.spec.ts
+++ b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
@@ -7,6 +7,7 @@ import type { Session } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
+import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
 
 const ZERO: TokenUsageProjection = {
   uncachedInputTokens: 0,
@@ -81,6 +82,7 @@ function appendSummaryMeter(ctx: Context, session: Session, start: number, end:
   const endIdx = nodes.findIndex(node => node.seq === end)
   const shadowed = nodes.slice(startIdx, endIdx + 1)
   session.append('compact/summary', {
+    compactionId: CompactionId('token-usage-summary'),
     summary: [{ type: 'text', text: 'summary' }],
     shadowedRange: { start, end },
     shadowedSeqs: shadowed.map(node => node.seq),
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index ef97c945c9..b52000f554 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -277,8 +277,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         jsDoc: '/**\n * Consider automatic compaction for one explicit trigger. Pressure policy\n * uses the latest durable routed request, while context-overflow policy may\n * force a useful balanced reduction even below the normal threshold. Return\n * `null` when no safe range can be compacted. A single oversized retained\n * unit or request envelope cannot be repaired through surface compaction.\n *\n * @param agent - agent context owning the session surface and routing options.\n * @param trigger - normal pressure or provider-confirmed context overflow.\n * @param signal - cancellation signal; model-backed implementations must forward it.\n * @returns the compaction result, or `null` if no compaction was needed.\n */',
       },
       {
-        signature: 'abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): Promise<CompactionResult | null>',
-        jsDoc: '/**\n * Explicitly compact useful history even below automatic pressure thresholds.\n * Implementations synchronously start an idle task before any asynchronous\n * work, select a useful range without writing on a no-op, then\n * append a standalone `compact/start` before summarization. That durable\n * marker is the compaction lock until one `compact/end` attempt. Later waking\n * prompts remain accepted in FIFO order and start only after the optional\n * durability checkpoint and idle-task settlement. Context injected while the\n * summary runs may sit between the marker pair; only the selected span must\n * remain stable.\n *\n * @param agent - idle agent whose durable history should be compacted.\n * @param signal - cancellation scoped to this compaction request.\n * @returns the compaction result, or `null` when no safe useful range exists.\n * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,\n * changed-span, summarization/shrink, commit-stage, or persistence failures;\n * an aborted request preserves its exact abort reason. Failed attempts remain\n * visible in the log.\n */',
+        signature: 'abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId, ): Promise<CompactionResult | null>',
+        jsDoc: '/**\n * Explicitly compact useful history even below automatic pressure thresholds.\n * Implementations synchronously start an idle task before any asynchronous\n * work, select a useful range without writing on a no-op, then\n * append a standalone `compact/start` before summarization. That durable\n * marker is the compaction lock until one `compact/end` attempt. Later waking\n * prompts remain accepted in FIFO order and start only after the optional\n * durability checkpoint and idle-task settlement. Context injected while the\n * summary runs may sit between the marker pair; only the selected span must\n * remain stable.\n *\n * @param agent - idle agent whose durable history should be compacted.\n * @param signal - cancellation scoped to this compaction request.\n * @param sourceCommandId - initiating command identity for a manual compaction.\n * @returns the compaction result, or `null` when no safe useful range exists.\n * @throws {@link ManualCompactionError} for expected busy, agent-cancellation,\n * changed-span, summarization/shrink, commit-stage, or persistence failures;\n * an aborted request preserves its exact abort reason. Failed attempts remain\n * visible in the log.\n */',
       },
       {
         signature: 'abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
@@ -1841,7 +1841,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'CommandInvocation',
-    declaration: 'export interface CommandInvocation {\n    readonly agent: Agent;\n    readonly rawInput: string;\n    readonly signal: AbortSignal;\n}',
+    declaration: 'export interface CommandInvocation {\n    readonly commandId: CommandId;\n    readonly agent: Agent;\n    readonly rawInput: string;\n    readonly signal: AbortSignal;\n}',
   },
   {
     name: 'CommandResult',
@@ -1851,9 +1851,13 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'CompactAgentContext',
     declaration: 'export interface CompactAgentContext {\n    session: Session;\n    options: {\n        provider?: string;\n        model?: string;\n    };\n}',
   },
+  {
+    name: 'CompactionId',
+    declaration: 'export type CompactionId = Branded<\'CompactionId\'>;',
+  },
   {
     name: 'CompactionResult',
-    declaration: 'export interface CompactionResult {\n    startSeq: number;\n    summarySeq: number;\n    endSeq: number;\n    summary: ContentBlock[];\n    shadowedRange: {\n        start: number;\n        end: number;\n    };\n    shadowedSeqs: number[];\n    shadowedTokenCount: number;\n}',
+    declaration: 'export interface CompactionResult {\n    compactionId: CompactionId;\n    sourceCommandId?: CommandId;\n    startSeq: number;\n    summarySeq: number;\n    endSeq: number;\n    summary: ContentBlock[];\n    shadowedRange: {\n        start: number;\n        end: number;\n    };\n    shadowedSeqs: number[];\n    shadowedTokenCount: number;\n}',
   },
   {
     name: 'CompactionTrigger',
@@ -3065,7 +3069,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolExecution',
-    declaration: 'export interface ToolExecution extends ToolExecutionInput {\n    readonly token: ToolExecutionToken;\n}',
+    declaration: 'export interface ToolExecution extends ToolExecutionInput {\n    readonly rootCallId: CallId;\n    readonly token: ToolExecutionToken;\n}',
   },
   {
     name: 'ToolExecutionFailure',
@@ -3073,7 +3077,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolExecutionInput',
-    declaration: 'export interface ToolExecutionInput {\n    readonly callId: CallId;\n    readonly name: string;\n    readonly arguments: unknown;\n    readonly agent?: Agent;\n    readonly parent?: ToolExecutionToken;\n    readonly signal: AbortSignal;\n}',
+    declaration: 'export interface ToolExecutionInput {\n    readonly callId: CallId;\n    readonly rootCallId?: CallId;\n    readonly name: string;\n    readonly arguments: unknown;\n    readonly agent?: Agent;\n    readonly parent?: ToolExecutionToken;\n    readonly signal: AbortSignal;\n}',
   },
   {
     name: 'ToolExecutionMode',
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index efdab32824..0276199e3e 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -4,6 +4,7 @@ import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
 import LlmService, { CallId, createUserMessage, GenerateOptions, LlmAdapter, StreamChunk } from '@deepseek-ai/dsh-llm'
 import {
   type ReplayEntry,
@@ -35,6 +36,8 @@ const TEXT_CHUNKS: StreamChunk[] = [
   { type: 'finish', reason: { kind: 'stop' } },
 ]
 
+const COMPACTION_ID = CompactionId('replay-compaction')
+
 /** Build a minimal session-JSONL string: a header line + the given events. */
 function sessionJsonl(events: SessionEvent[], header?: { id?: string; createdAt?: number; seedLength?: number }): string {
   const headerLine = JSON.stringify({
@@ -194,12 +197,18 @@ describe('deriveReplayScript', () => {
     let seq = 1
     const events: SessionEvent[] = [
       ...overflow.map(chunk => chunkEvent(seq++, 1, 2, chunk)),
-      { type: 'compact/start', seq: seq++, time: 0, data: { turn: 1 } },
+      {
+        type: 'compact/start',
+        seq: seq++,
+        time: 0,
+        data: { compactionId: COMPACTION_ID, turn: 1 },
+      },
       {
         type: 'compact/summary',
         seq: seq++,
         time: 0,
         data: {
+          compactionId: COMPACTION_ID,
           summary: rawOutput,
           rawOutput,
           llmStreamCall: true,
@@ -227,6 +236,7 @@ describe('deriveReplayScript', () => {
       seq: 1,
       time: 0,
       data: {
+        compactionId: COMPACTION_ID,
         summary: [{ type: 'text', text: 'template result' }],
         shadowedRange: { start: 1, end: 1 },
         shadowedSeqs: [1],
@@ -246,6 +256,7 @@ describe('deriveReplayScript', () => {
       seq: 1,
       time: 0,
       data: {
+        compactionId: COMPACTION_ID,
         summary: [block],
         rawOutput: [block],
         shadowedRange: { start: 1, end: 1 },
@@ -267,6 +278,7 @@ describe('deriveReplayScript', () => {
         seq: 1,
         time: 0,
         data: {
+          compactionId: COMPACTION_ID,
           summary: [{ type: 'text', text: 'missing source events' }],
           llmStreamCall: true,
           shadowedRange: { start: 1, end: 1 },
@@ -289,6 +301,7 @@ describe('deriveReplayScript', () => {
       seq: 1,
       time: 0,
       data: {
+        compactionId: COMPACTION_ID,
         summary: [block],
         rawOutput: [block],
         llmStreamCall: true,
@@ -343,6 +356,7 @@ describe('deriveReplayScript', () => {
         seq: 2,
         time: 0,
         data: {
+          compactionId: COMPACTION_ID,
           summary: [{ type: 'text', text: 'external checkpoint' }],
           shadowedRange: { start: 1, end: 1 },
           shadowedSeqs: [1],
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index da3703e5ff..f1ee272761 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1504,9 +1504,6 @@ importers:
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
         version: link:../../interaction/commands
-      '@deepseek-ai/dsh-compact':
-        specifier: workspace:^
-        version: link:../../compact/compact
       '@deepseek-ai/dsh-host-apiproxy':
         specifier: workspace:^
         version: link:../../host/apiproxy
@@ -1680,6 +1677,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-compact':
+        specifier: workspace:^
+        version: link:../../compact/compact
       '@deepseek-ai/dsh-goal':
         specifier: workspace:^
         version: link:../../goal/goal
@@ -2670,6 +2670,12 @@ importers:
 
   packages/compact/compact:
     devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-commands':
+        specifier: workspace:^
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
@@ -2704,6 +2710,9 @@ importers:
       '@deepseek-ai/dsh-agent-loop-testkit':
         specifier: workspace:^
         version: link:../../support/agent-loop-testkit
+      '@deepseek-ai/dsh-commands':
+        specifier: workspace:^
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:^
         version: link:../compact
@@ -4391,6 +4400,9 @@ importers:
       '@deepseek-ai/dsh-agent-loop-testkit':
         specifier: workspace:^
         version: link:../../support/agent-loop-testkit
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index fffde3ceb8..51fdc06f61 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -278,6 +278,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   CreateGoalResult: 'goal.md',
   CommandDefinition: 'commands.md',
   CommandDescriptor: 'commands.md',
+  CommandId: 'commands.md',
   CommandResult: 'commands.md',
   CommandSurface: 'commands.md',
   LlmAdapter: 'llm-streaming.md',

From 8723a0e15f791f4403327f809eb43bedc748f43d Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:02:20 +0800
Subject: [PATCH 489/516] fix(client): address conversation assembly review
 findings

---
 .../client/sessions/conversation-assembler.ts | 12 ++--
 .../runtime/src/client/sessions/session.ts    |  1 +
 .../tests/conversation-assembler.spec.ts      | 67 +++++++++++++++++++
 .../client/conversation-nodes/turn-tail.ts    | 19 +++++-
 .../ui-conversation/src/client/index.ts       | 21 +++---
 .../conversation-node-definitions.spec.ts     | 26 ++++++-
 scripts/gen-cordis-catalog.ts                 |  2 +
 7 files changed, 128 insertions(+), 20 deletions(-)

diff --git a/packages/client/runtime/src/client/sessions/conversation-assembler.ts b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
index 3b6fbd6266..3a0c94ba3c 100644
--- a/packages/client/runtime/src/client/sessions/conversation-assembler.ts
+++ b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
@@ -238,7 +238,7 @@ export class ConversationNodeAssembler {
     }
     this.applyPendingMatches(pending, affected)
     this.replayContexts(affected)
-    if ((fresh.length > 0 || previousHasMore !== hasMore) && this.replayDependencies()) {
+    if ((this.revised.size > 0 || previousHasMore !== hasMore) && this.replayDependencies()) {
       publication = 'immediate'
     }
     if (changedLocations.size > 0) publication = 'immediate'
@@ -563,18 +563,18 @@ export class ConversationNodeAssembler {
 
   private replayRevisedDependents(): boolean {
     const pending = [...this.revised]
-    const replayed = new Set<InternalContext>()
+    const affected = new Set<InternalContext>()
     for (let index = 0; index < pending.length; index++) {
       const dependency = pending[index]
       if (dependency === undefined) continue
       for (const dependent of this.dependents.get(dependency.key) ?? []) {
-        if (replayed.has(dependent)) continue
-        replayed.add(dependent)
-        this.replayContext(dependent)
+        if (affected.has(dependent)) continue
+        affected.add(dependent)
         pending.push(dependent)
       }
     }
-    return replayed.size > 0
+    this.replayContexts(affected)
+    return affected.size > 0
   }
 
   private readerFor(
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index a533f9dd6f..7c3d989248 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -344,6 +344,7 @@ export class Session implements SessionFace {
         // §D.2 continuity assertion: on violation drop the page fail-soft rather than render an out-of-order stream.
         console.error(`[web-runtime] history page discontinuous: tail seq ${tail?.event.seq} vs baseSeq ${this.baseSeq}`)
         this.hasMore = false
+        this.conversation.prepend([], false)
         return
       }
       this.events = [...older.map(e => e.event), ...this.events]
diff --git a/packages/client/runtime/tests/conversation-assembler.spec.ts b/packages/client/runtime/tests/conversation-assembler.spec.ts
index 6f4d8516dc..06dfd42567 100644
--- a/packages/client/runtime/tests/conversation-assembler.spec.ts
+++ b/packages/client/runtime/tests/conversation-assembler.spec.ts
@@ -458,6 +458,73 @@ describe('ConversationNodeAssembler', () => {
     expect([...chatSnapshot(assembler)?.nodes.values() ?? []][0]?.data).toBe(2)
   })
 
+  it('replays a transitive dependency closure in start order', () => {
+    const sourceA: ConversationNodeDefinition<number> = {
+      kind: 'diamond-a',
+      match: (event) => {
+        if (event.type === 'user/message') return { id: 'one', role: 'start' }
+        if ((event.type as string) === 'diamond/a') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: () => 1,
+      update: (_context, match) => (match.event.data as unknown as { value: number }).value,
+      buildViewNode: () => null,
+    }
+    const sourceX: ConversationNodeDefinition<number> = {
+      kind: 'diamond-x',
+      match: (event) => {
+        if (event.type === 'turn/start') return { id: 'one', role: 'start' }
+        if ((event.type as string) === 'diamond/x') return { id: 'one', role: 'update' }
+        return null
+      },
+      start: () => 10,
+      update: (_context, match) => (match.event.data as unknown as { value: number }).value,
+      buildViewNode: () => null,
+    }
+    const middle: ConversationNodeDefinition<number> = {
+      kind: 'diamond-b',
+      match: event => event.type === 'assistant/message'
+        ? { id: 'one', role: 'start' }
+        : null,
+      start: (_context, _match, reader) => (
+        (reader.previous<number>('diamond-a')?.state ?? 0)
+        + (reader.previous<number>('diamond-x')?.state ?? 0)
+      ),
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const consumer: ConversationNodeDefinition<number> = {
+      kind: 'diamond-c',
+      match: event => event.type === 'tool/call'
+        ? { id: 'one', role: 'start' }
+        : null,
+      start: (_context, _match, reader) => (
+        (reader.previous<number>('diamond-a')?.state ?? 0) * 100
+        + (reader.previous<number>('diamond-b')?.state ?? 0)
+      ),
+      update: context => context.state,
+      buildViewNode: context => node(context, context.state),
+    }
+    const assembler = new ConversationNodeAssembler(
+      new TestEventDefinitions([sourceA, sourceX, middle, consumer]),
+      new TestViewDefinitions([testView()]),
+    )
+    assembler.replaceWindow([
+      input(at(1, 'user/message', { id: 'source', content: [], source: { kind: 'user' } })),
+      input(at(2, 'turn/start', { turn: 1 })),
+      input(at(3, 'assistant/message', { turn: 1, step: 1, message: { role: 'assistant', content: [] } })),
+      input(at(4, 'tool/call', { turn: 1, step: 1, callId: 'call', name: 'x', arguments: '{}' })),
+    ], false)
+
+    assembler.append(input(at(5, 'diamond/x', { value: 20 })))
+    assembler.append(input(at(6, 'diamond/a', { value: 2 })))
+    assembler.flush()
+
+    const value = [...chatSnapshot(assembler)?.nodes.values() ?? []]
+      .find(candidate => candidate.kind === 'diamond-c')
+    expect(value?.data).toBe(222)
+  })
+
   it('replays Location-derived State and rebuilds only owned Nodes when a step closes', () => {
     const apply = vi.fn()
     const starts = vi.fn((
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
index 2a842a005d..346bd41bdf 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
@@ -122,14 +122,26 @@ function tailData(context: ConversationNodeContext<TurnTailState>): TurnTailChat
     .filter((candidate): candidate is Readonly<FinalAssistantChatData> => candidate.finalNode !== undefined)
     .sort((left, right) => left.finalNode.seq - right.finalNode.seq)
   const closing = finalized.findLast(hasText) ?? null
-  const latest = finalized.at(-1)
+  let latestTranscriptSeq = finalized.at(-1)?.finalNode.seq
+  for (const match of context.matches) {
+    const event = match.event
+    const candidate = event.type === 'tool/call'
+      || (event.type === 'tool/result' && isAppendSurfaceEvent(event))
+      || (event.type === 'turn/end' && event.data.reason.kind === 'error')
+      || (event.type as string) === 'llm/retry'
+      ? event.seq
+      : undefined
+    if (candidate !== undefined && (latestTranscriptSeq === undefined || candidate > latestTranscriptSeq)) {
+      latestTranscriptSeq = candidate
+    }
+  }
   const metrics = deriveTurnMetrics(finalized.map(candidate => candidate.finalNode)).get(end.event.data.turn)
   return {
     turn: end.event.data.turn,
     seq: end.event.seq,
     time: end.event.time,
     closing,
-    branchUnavailable: closing === null || latest?.finalNode.seq !== closing.finalNode.seq,
+    branchUnavailable: closing === null || latestTranscriptSeq !== closing.finalNode.seq,
     ...metrics?.ttftMs === undefined ? {} : { ttftMs: metrics.ttftMs },
     ...metrics?.tokensPerSecond === undefined ? {} : { tokensPerSecond: metrics.tokensPerSecond },
   }
@@ -141,6 +153,9 @@ export const turnTailDefinition: ConversationNodeDefinition<TurnTailState> = {
   match: (event) => {
     if (event.type === 'turn/start') return { id: String(event.data.turn), role: 'start' }
     if (event.type === 'turn/end') return { id: String(event.data.turn), role: 'update' }
+    if (event.type === 'tool/call' || event.type === 'tool/result') {
+      return { id: String(event.data.turn), role: 'update' }
+    }
     const coordinates = turnCoordinates(event)
     if (coordinates !== undefined) return { id: String(coordinates.turn), role: 'update' }
     return null
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index b4d7467170..e0471623f0 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -3,19 +3,18 @@
  * between the independently implemented skeleton and chat domains; `apply.ts`
  * owns their slot assembly.
  */
+export type {} from './conversation-nodes/assistant.ts'
+export type {} from './conversation-nodes/command.ts'
+export type {} from './conversation-nodes/compaction.ts'
+export type {} from './conversation-nodes/fallback.ts'
+export type {} from './conversation-nodes/message.ts'
+export type {} from './conversation-nodes/retry.ts'
+export type {} from './conversation-nodes/tool.ts'
+export type {} from './conversation-nodes/turn-error.ts'
+export type {} from './conversation-nodes/turn-tail.ts'
+
 export { apply, inject } from './apply.ts'
 export { ConversationService } from './service.ts'
-export { registerAssistantConversationNode } from './conversation-nodes/assistant.ts'
-export { registerChatConversationView } from './conversation-nodes/chat-snapshot-builder.ts'
-export { registerCommandConversationNode } from './conversation-nodes/command.ts'
-export { registerCompactionConversationNode } from './conversation-nodes/compaction.ts'
-export { registerUnknownConversationFallback } from './conversation-nodes/fallback.ts'
-export { registerInboxConversationNodes } from './conversation-nodes/inbox.ts'
-export { registerMessageConversationNode } from './conversation-nodes/message.ts'
-export { registerRetryConversationNode } from './conversation-nodes/retry.ts'
-export { registerToolConversationNode } from './conversation-nodes/tool.ts'
-export { registerTurnErrorConversationNode } from './conversation-nodes/turn-error.ts'
-export { registerTurnTailConversationNode } from './conversation-nodes/turn-tail.ts'
 export type { IConversation } from './service.ts'
 
 export type {
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
index 3ae906087e..5346ad57f9 100644
--- a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -16,7 +16,7 @@ import { toolDefinition } from '../src/client/conversation-nodes/tool.ts'
 import { turnErrorDefinition } from '../src/client/conversation-nodes/turn-error.ts'
 import { turnTailDefinition } from '../src/client/conversation-nodes/turn-tail.ts'
 import type {
-  AssistantChatData, ManualCompactionChatData, RetryChatData, ToolChatData,
+  AssistantChatData, ManualCompactionChatData, RetryChatData, ToolChatData, TurnTailChatData,
 } from '../src/client/contract/chat-nodes.ts'
 
 const DEFINITIONS: readonly ConversationNodeDefinition[] = [
@@ -413,6 +413,30 @@ describe('built-in conversation node Definitions', () => {
     ])
   })
 
+  it('keeps branching unavailable when a tool result follows the closing Assistant', () => {
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'assistant/message', {
+        turn: 1,
+        step: 1,
+        message: assistantMessage('assistant-before-tool', 'running a tool'),
+      }, { surfaceOp: 'append' }),
+      at(4, 'tool/call', { turn: 1, step: 1, callId: 'late-tool', name: 'read', arguments: '{}' }),
+      at(5, 'tool/result', {
+        turn: 1,
+        step: 1,
+        message: toolResult('late-tool', 'done'),
+      }, { surfaceOp: 'append' }),
+      at(6, 'step/end', { turn: 1, step: 1 }),
+      at(7, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+    ])
+
+    const tail = node(snapshot(value), 'turn-tail')?.data as TurnTailChatData
+    expect(tail.closing?.finalNode.seq).toBe(3)
+    expect(tail.branchUnavailable).toBe(true)
+  })
+
   it('replays inbox predecessors after prepend and reclassifies the dependent message as steering', () => {
     const value = assembler([
       at(3, 'user/message', textMessage('steer-1', 'change direction'), { surfaceOp: 'append' }),
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 51fdc06f61..662ad1df13 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -121,6 +121,8 @@ export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
   chatFileMentions: 'client-side slot-contract accessor (ChatFileMentions) — packages/client/ui-conversation/README.md owns the surface',
   command: 'client-side interface-typed browser service — packages/client/ui-command/README.md owns the surface',
   conversation: 'client-side interface-typed browser service — packages/client/ui-conversation/README.md owns the surface',
+  conversationEvents: 'client-side interface-typed registry — packages/client/runtime/README.md owns the surface',
+  conversationViews: 'client-side interface-typed registry — packages/client/runtime/README.md owns the surface',
   layout: 'client-side interface-typed browser service — packages/client/ui-layout/README.md owns the surface',
   locale: 'client-side interface-typed browser service — packages/client/locale/README.md owns the surface',
   models: 'client-side interface-typed browser service — packages/client/ui-model/README.md owns the surface',

From 990f700d3cd4c977a5cb1788ef7c9c5d138f918a Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:28:42 +0800
Subject: [PATCH 490/516] fix(client): address conversation assembly review
 feedback

---
 ...lient-conversation-node-assembly.i18n.yaml |  4 ++--
 ...08-09-client-conversation-node-assembly.md | 10 ++++----
 ...09-client-conversation-node-assembly.zh.md | 10 ++++----
 packages/client/runtime/README.i18n.yaml      |  4 ++--
 packages/client/runtime/README.md             |  2 +-
 packages/client/runtime/README.zh.md          |  2 +-
 .../client/sessions/conversation-assembler.ts |  2 ++
 .../src/client/sessions/conversation.ts       | 24 ++++++++++++-------
 .../client/ui-conversation/README.i18n.yaml   |  4 ++--
 packages/client/ui-conversation/README.md     |  4 ++--
 packages/client/ui-conversation/README.zh.md  |  4 ++--
 .../src/client/contract/slots.ts              |  9 ++++---
 .../client/conversation-nodes/assistant.ts    |  4 ++--
 .../chat-snapshot-builder.ts                  |  5 +++-
 .../src/client/conversation-nodes/common.ts   | 10 ++++++++
 .../src/client/conversation-nodes/tool.ts     |  4 ++--
 .../client/conversation-nodes/turn-tail.ts    |  8 ++++---
 packages/client/ui-tool/README.i18n.yaml      |  4 ++--
 packages/client/ui-tool/README.md             |  4 ++--
 packages/client/ui-tool/README.zh.md          |  4 ++--
 20 files changed, 73 insertions(+), 49 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index 953a049744..264b900b74 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: 0cee5449f651c568dbb87b9cb867eb77b6380184
-2026-08-09-client-conversation-node-assembly.zh.md: 146e8f68a9b1339934040cee62fd46e981145f2a
+2026-08-09-client-conversation-node-assembly.md: f9768a652c7b0d2d29939fac83b201bc904e3210
+2026-08-09-client-conversation-node-assembly.zh.md: 408d61f73b3b317214cb10b26f522e7680de3f92
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index 0cee5449f6..f9768a652c 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -148,7 +148,7 @@ The Assembler verifies `node.key === context.key` and `node.target === target`.
 
 `current` lets a Definition distinguish "never materialized" from "already materialized and now hidden." Assistant retry and Turn Error suppression use it to avoid illegal Node withdrawal.
 
-A Definition may branch by target to construct different data, while matching, Context identity, and State remain target-neutral. This change registers only the `chat` builder; Trajectory continues to consume the compatibility slice.
+A Definition may branch by target to construct different data, while matching, Context identity, and State remain target-neutral. This change registers only the `chat` builder; Trajectory remains on its independent `session-history` fold until it gains a registered target.
 
 #### No generic `end()`
 
@@ -306,7 +306,7 @@ Unknown fallback demonstrates Registry ownership: it handles only append-surface
 
 The Assembler calls `replace({ nodes, timeline })` on low-frequency complete replacements and `apply({ upserts, timeline })` for ordinary prepend/append flushes. Builders receive only final target Nodes already constructed by Definitions.
 
-[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) maintains `order`, a keyed `nodes` store, the turn/step `locations` index, `timeline`, and the `legacy` slice temporarily consumed by Trajectory.
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) maintains `order`, a keyed `nodes` store, the turn/step `locations` index, `timeline`, and the `legacy` slice used by StatsLine and mirrored into top-level public compatibility fields.
 
 Only a new key or a change to `anchorSeq`, visibility, or Location identity makes a Chat update structural. An ordinary content change does not rebuild `order`; the keyed Node store replaces only that key's value.
 
@@ -328,7 +328,7 @@ When business logic deliberately changes a materialized Node to hidden, it leave
 
 The concrete Tool renderer remains governed by the [`ui-tool ownership decision`](2026-08-08-client-tool-presentation-ownership.md). Tool Definition supplies recursive root/subcall data, and `ui-tool` dispatches concrete presentation by the Tool-name keyed slot.
 
-Trajectory has no independent registered target yet. It continues to consume the legacy slice incrementally derived by the Chat Builder, while Session no longer runs a second transcript fold; a future migration does not change the Event Definition, Context, Reader, or Location contracts.
+Trajectory has no registered target and does not consume the Chat Builder's legacy slice. Its activated `SessionHistoryInspection` keeps an independent history fold, while the ordinary Session snapshot no longer runs a second transcript fold. The Chat Builder retains its legacy slice for StatsLine and the top-level public compatibility fields; a future Trajectory migration does not change the Event Definition, Context, Reader, or Location contracts.
 
 ## Runtime and render path
 
@@ -382,7 +382,7 @@ History-path tests cover complete replace, non-overlapping prepend, overlapping-
 
 **Add generic `end()`, prepared, or window-reset lifecycles.** Rejected: businesses have different completion conditions, and a pagination gap is not a business lifecycle. Business Events update State, Location close triggers replay/build, and Reader dependencies own pagination invalidation.
 
-**Register separate Event Definitions for Chat and Trajectory.** Rejected: identity, State, and Location are target-neutral. `buildViewNode(target)` and each Builder express view differences; Trajectory retains a compatibility slice until its actual migration.
+**Register separate Event Definitions for Chat and Trajectory.** Rejected: identity, State, and Location are target-neutral. `buildViewNode(target)` and each Builder express view differences; Trajectory's independent history fold remains until it registers its own Builder.
 
 **Add a generic layout model above final business Nodes.** Rejected: activity, tail candidacy, and layout enums would centralize current Chat business semantics in the engine again. Final Nodes carry renderer-required data directly and share only identity, ordering, and Location facts.
 
@@ -404,4 +404,4 @@ Steps and Turns become stable homes for cross-business aggregates. Turn Tail and
 
 The cost is new Runtime contracts for Registry, Assembler, Location data, dependency replay, and per-target Builders, plus parent-owned common inject and per-occurrence `hookContext` in UI Slots. Definition authors must understand stable IDs, unique starts, forward replay, Step→Turn publication order, read-only Reader access, and the prohibition on Node withdrawal.
 
-`useTurnData()` does not revoke the standard `useSession` capability from session-scoped renderers, so this boundary relies on API guidance and tests rather than capability isolation. Registry changes remain low-frequency full rebuilds; the Chat Builder still maintains a legacy slice until Trajectory migrates; built-in Definitions currently remain centralized in `ui-conversation`. These compatibility boundaries do not return business interpretation to Session.
+`useTurnData()` does not revoke the standard `useSession` capability from session-scoped renderers, so this boundary relies on API guidance and tests rather than capability isolation. Registry changes remain low-frequency full rebuilds; the Chat Builder still maintains a legacy slice for StatsLine and the top-level public fields, Trajectory still owns an independent history fold, and built-in Definitions currently remain centralized in `ui-conversation`. These compatibility boundaries do not return business interpretation to Session.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index 146e8f68a9..408d61f73b 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -148,7 +148,7 @@ Assembler 校验 Node `key === context.key` 且 Node `target === target`。业
 
 `current` 让 Definition 区分“从未生成”与“已经生成后需要隐藏”。Assistant retry 和 Turn Error suppression 使用它避免非法的 Node 撤回。
 
-Definition 可以针对 target 分支构造不同 data，但匹配、Context identity 和 State 保持 target-neutral。本次只注册 `chat` builder，Trajectory 仍通过兼容 slice 使用结果。
+Definition 可以针对 target 分支构造不同 data，但匹配、Context identity 和 State 保持 target-neutral。本次只注册 `chat` builder；在拥有注册 target 之前，Trajectory 继续使用独立的 `session-history` fold。
 
 #### 不提供通用 `end()`
 
@@ -306,7 +306,7 @@ Unknown fallback 展示了 Registry ownership：fallback 只处理没有任何
 
 Assembler 低频完整替换时调用 `replace({ nodes, timeline })`；普通 prepend/append flush 调用 `apply({ upserts, timeline })`。Builder 只接收 Definition 已构造完成的 target Nodes。
 
-[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) 维护 `order`、keyed `nodes` store、turn/step `locations` index、`timeline` 和 Trajectory 临时使用的 `legacy` slice。
+[`ChatSnapshotBuilder`](../../../../packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts) 维护 `order`、keyed `nodes` store、turn/step `locations` index、`timeline`，以及由 StatsLine 使用并镜像到顶层公共兼容字段的 `legacy` slice。
 
 Chat 结构变化只由新 key、`anchorSeq`、visibility 或 Location identity 变化触发。普通内容变化不重建 `order`；keyed Node store 只替换该 key 的 value。
 
@@ -328,7 +328,7 @@ Assistant streaming 到 final、Tool running 到 settled 只更新同一个 Seat
 
 具体 Tool renderer 仍由 [`ui-tool ownership decision`](2026-08-08-client-tool-presentation-ownership.md) 约束。Tool Definition 只交付递归 root/subcall data，`ui-tool` 再按 Tool name keyed slot 分发具体表现。
 
-Trajectory 尚未注册独立 target。它继续消费 Chat Builder 增量派生的 legacy slice，Session 不再运行第二套 transcript fold；未来迁移不改变 Event Definition、Context、Reader 或 Location 契约。
+Trajectory 尚未注册 target，也不消费 Chat Builder 的 legacy slice。它已激活的 `SessionHistoryInspection` 继续维护独立 history fold，而普通 Session snapshot 不再运行第二套 transcript fold。Chat Builder 为 StatsLine 和顶层公共兼容字段保留 legacy slice；未来迁移 Trajectory 不改变 Event Definition、Context、Reader 或 Location 契约。
 
 ## Runtime and render path
 
@@ -382,7 +382,7 @@ Assembled Web snapshot、GUI 和浏览器场景覆盖真实 plugin graph。浏
 
 **增加通用 `end()`、prepared 或 window reset 生命周期。** 拒绝：不同业务完成条件不同，分页缺口也不是业务生命周期。业务 Event 更新 State，Location close 触发 replay/build，Reader dependency 负责补页失效。
 
-**为 Chat 与 Trajectory 注册两套 Event Definition。** 拒绝：identity、State 和 Location 与 target 无关。视图差异由 `buildViewNode(target)` 和各自 Builder 表达；Trajectory 在真正迁移前保留兼容 slice。
+**为 Chat 与 Trajectory 注册两套 Event Definition。** 拒绝：identity、State 和 Location 与 target 无关。视图差异由 `buildViewNode(target)` 和各自 Builder 表达；Trajectory 在注册自己的 Builder 之前继续使用独立 history fold。
 
 **在最终业务 Node 上再叠一层通用 layout model。** 拒绝：activity、tail candidacy 和 layout enum 会把当前 Chat 的业务语义重新集中到引擎。最终 Node 直接携带 renderer 所需 data，只共享 identity、排序和 Location 事实。
 
@@ -404,4 +404,4 @@ Step/Turn 成为业务间共享聚合的稳定宿主。Turn Tail 和 Deliverable
 
 代价是 Runtime 新增 Registry、Assembler、Location data、依赖重放和 per-target Builder 契约，UI Slots 也新增 parent-owned common inject 与 per-occurrence `hookContext`。Definition 作者必须理解稳定 ID、唯一 start、正序 replay、Step→Turn 发布顺序、只读 Reader 和 Node 不撤回规则。
 
-`useTurnData()` 不撤销 session-scoped renderer 的标准 `useSession`，因此该边界依靠 API 引导和测试，而不是能力隔离。Registry 变化仍是低频完整 rebuild；Chat Builder 在 Trajectory 迁移前仍维护 legacy slice；内建 Definitions 暂时集中在 `ui-conversation`。这些是兼容边界，不把业务解释权交还给 Session。
+`useTurnData()` 不撤销 session-scoped renderer 的标准 `useSession`，因此该边界依靠 API 引导和测试，而不是能力隔离。Registry 变化仍是低频完整 rebuild；Chat Builder 继续为 StatsLine 和顶层公共字段维护 legacy slice，Trajectory 继续拥有独立 history fold，内建 Definitions 暂时集中在 `ui-conversation`。这些是兼容边界，不把业务解释权交还给 Session。
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 4aed1d0f36..d47266cd8a 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: b2bb06e50ecd791d74cb609404dd219e5a21913e
-README.zh.md: 72cd99ac765875c828cc9163d978e0b8fb7f44e4
+README.md: 46a383f22032c8da7e4bb9b5fb445980661c670f
+README.zh.md: 73578a8f249472abfdd7c539e3eaee6de767ad60
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index b2bb06e50e..46a383f220 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -38,7 +38,7 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 Each `Session` gives its contiguous event window to a `ConversationNodeAssembler`. Plugins register business Definitions that map one event to a stable `{kind, id}`, create State at the unique start event, fold correlated updates, and build final nodes for registered view targets. The assembler owns the Context index, read-only predecessor lookup, and a reference-stable Turn/Step Location index. A live append evaluates each Definition once and updates only the matched Context; loading an older page preserves existing Context and node identities, matches only the newly prepended events, and replays Contexts whose predecessor or Location facts changed. Full replacement is reserved for open, resync, and gap repair.
 
-`ui-conversation` registers the built-in Chat Definitions and the keyed Chat snapshot builder. Append-origin user, assistant, and Tool results remain the human record; model-only replacement copies stay out, except that a compaction checkpoint becomes its own marker and resolves missing summary provenance when an older page supplies it. Durable inbox splice Contexts classify next-step user messages as steering without making inbox state a Session special case. Context messages retain producer provenance and form. `ConversationSnapshot.nodes`, `partial`, and `runningCalls` are compatibility slices derived from the same materialized Chat nodes for consumers that have not moved to `ConversationSnapshot.chat`; Session does not run a second business fold.
+`ui-conversation` registers the built-in Chat Definitions and the keyed Chat snapshot builder. Append-origin user, assistant, and Tool results remain the human record; model-only replacement copies stay out, except that a compaction checkpoint becomes its own marker and resolves missing summary provenance when an older page supplies it. Durable inbox splice Contexts classify next-step user messages as steering without making inbox state a Session special case. Context messages retain producer provenance and form. StatsLine reads `ConversationSnapshot.chat.legacy.nodes`, while Session mirrors that legacy slice into the top-level `nodes`, `partial`, and `runningCalls` public compatibility fields without running a second business fold. Trajectory consumes neither compatibility surface; its activated `session-history` inspection keeps an independent fold until it gains its own registered target.
 
 The Chat builder keeps one mutable keyed store per Session. Content updates notify only the affected node key, structural changes rebuild order and Location membership, and a prepend adds rows without replacing existing keyed values. Assistant chunks update Definition State for every event but request at most one materialization per animation frame; final messages and Turn/Step closure publish immediately. See the [client Tool presentation decision](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md).
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 72cd99ac76..73578a8f24 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -38,7 +38,7 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 每个 `Session` 都把连续事件窗口交给 `ConversationNodeAssembler`。插件注册业务 Definition，把单个事件映射为稳定的 `{kind, id}`，在唯一 start 事件处创建 State，折叠有关联的 update，再为已注册的视图目标构造最终节点。Assembler 负责 Context 索引、只读前序 Context 查询，以及引用稳定的 Turn/Step Location 索引。实时 append 只对每个 Definition 求值一次，并且只更新命中的 Context；加载更早分页时保留已有 Context 与节点身份，只匹配新 prepend 的事件，并重放前序依赖或 Location 事实发生变化的 Context。完整替换仅用于 open、resync 和 gap repair。
 
-`ui-conversation` 注册内建 Chat Definition 与 keyed Chat snapshot builder。append 来源的 user、assistant 和 Tool result 构成人类可见记录；仅供模型使用的 replacement 副本不进入 Chat，compaction 检查点除外，它会成为独立标记，并在更早分页补齐 summary 溯源后更新。持久 inbox splice Context 能把 next-step 用户消息判定为 steering，无须让 inbox 状态成为 Session 特例。上下文消息保留生产者 provenance 与 form。`ConversationSnapshot.nodes`、`partial` 和 `runningCalls` 是从同一批已物化 Chat 节点派生的兼容切片，供尚未迁移到 `ConversationSnapshot.chat` 的消费者使用；Session 不再运行第二套业务 fold。
+`ui-conversation` 注册内建 Chat Definition 与 keyed Chat snapshot builder。append 来源的 user、assistant 和 Tool result 构成人类可见记录；仅供模型使用的 replacement 副本不进入 Chat，compaction 检查点除外，它会成为独立标记，并在更早分页补齐 summary 溯源后更新。持久 inbox splice Context 能把 next-step 用户消息判定为 steering，无须让 inbox 状态成为 Session 特例。上下文消息保留生产者 provenance 与 form。StatsLine 读取 `ConversationSnapshot.chat.legacy.nodes`；Session 则把该 legacy slice 镜像到顶层 `nodes`、`partial` 和 `runningCalls` 公共兼容字段，无须运行第二套业务 fold。Trajectory 不消费这两种兼容表面；在它获得独立注册 target 之前，已激活的 `session-history` inspection 继续维护独立 fold。
 
 Chat builder 为每个 Session 保留一个 mutable keyed store。内容更新只通知受影响的 node key；结构变化才重建顺序和 Location 成员关系；prepend 只增加行，不替换既有 keyed value。每个 Assistant chunk 都会更新 Definition State，但最多每个 animation frame 请求一次物化；final message 与 Turn/Step 关闭会立即发布。参见 [Client Tool 展示所有权决策](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md)。
 
diff --git a/packages/client/runtime/src/client/sessions/conversation-assembler.ts b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
index 3a0c94ba3c..811bd43ebf 100644
--- a/packages/client/runtime/src/client/sessions/conversation-assembler.ts
+++ b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
@@ -743,6 +743,8 @@ export class ConversationNodeAssembler {
         context.locationData[scope] = data
         if (data !== null) entries.push({ owner: context.key, data })
       }
+      // Turn publishers may read Step data from this same flush, so each phase
+      // installs the cumulative replacement before the next phase builds.
       this.locationIndex.replaceData(entries)
     }
   }
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index 99daa7c8a5..628fe89aa8 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -1,7 +1,9 @@
 // ConversationSnapshot / ConversationNode: the only data shape the logic layer feeds the UI.
-// Immutability contract: every change swaps the top-level object; unchanged
-// substructures keep their references (the React.memo premise). callId/approvalId stay plain
-// string here (narrow to real brands when convenient).
+// Publication contract: every change swaps the top-level object; unchanged
+// substructures keep their references (the React.memo premise). Chat node and
+// Location stores are stable live readers, so old snapshots are not time-point
+// views. callId/approvalId stay plain string here (narrow to real brands when
+// convenient).
 
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
@@ -336,7 +338,10 @@ export interface PromptError {
   error: RpcError
 }
 
-/** Stable per-key reader for final Chat view Nodes. */
+/**
+ * Stable live per-key reader. An old ChatSnapshot observes later flushes
+ * through this store.
+ */
 export interface ChatNodeStore {
   /** @param key - stable Conversation Context key. @returns current Node, when visible or hidden. */
   get(key: string): ChatConversationViewNode | undefined
@@ -344,7 +349,10 @@ export interface ChatNodeStore {
   values(): readonly ChatConversationViewNode[]
 }
 
-/** Stable per-Location membership index for turn-local and step-local consumers. */
+/**
+ * Stable live Location index. An old ChatSnapshot observes later membership
+ * changes through this index.
+ */
 export interface ChatLocationNodeIndex {
   /** @param turn - owning turn. @returns ordered Chat Node keys in the turn. */
   getTurn(turn: number): readonly string[]
@@ -352,7 +360,7 @@ export interface ChatLocationNodeIndex {
   getStep(turn: number, step: number): readonly string[]
 }
 
-/** Temporary projection consumed by Trajectory and unmigrated readers. */
+/** Compatibility projection backing StatsLine and the legacy top-level snapshot fields. */
 export interface LegacyConversationSlice {
   readonly nodes: readonly ConversationNode[]
   readonly turnTimings: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
@@ -361,7 +369,7 @@ export interface LegacyConversationSlice {
   readonly runningCalls: readonly RunningToolCall[]
 }
 
-/** Incremental Chat target snapshot: stable keyed stores plus structural order. */
+/** Incremental Chat publication with immutable order and stable live keyed readers. */
 export interface ChatSnapshot {
   readonly order: readonly string[]
   readonly nodes: ChatNodeStore
@@ -399,7 +407,7 @@ export interface ConversationSnapshot {
   sessionId: SessionId
   /** Final Chat target assembled from independently registered business Definitions. */
   chat: ChatSnapshot
-  /** Legacy Trajectory slice derived from the registered Chat Definitions. */
+  /** Legacy top-level compatibility field mirrored from the registered Chat Definitions. */
   nodes: readonly ConversationNode[]
   /** Exact in-window `turn/start` time and optional matching `turn/end` time. */
   turnTimings: ReadonlyMap<number, { readonly startTime: number; readonly endTime?: number }>
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 2066b22ec5..bb15c65029 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 911bca28dcfb31b1d8ef9ea5458a0d2017d8b31d
-README.zh.md: 25574421bbcc3992188e378a49a69acf25744af7
+README.md: 3570e814609af0bc4e7d048a55205af756fae843
+README.zh.md: e37f867c72d83b47924e87261e6ee5ff8b374a6f
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 911bca28dc..3570e81460 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -20,7 +20,7 @@ Logged non-user messages render as a default-collapsed disclosure whose header n
 
 A Think row stays collapsed by default and exposes live reasoning throughput without expanding the chain of thought: while its reasoning block is the streaming tail, the summary switches from the settled first line to the latest non-blank line and its one-line scrollport follows each delta to the inline end. Expanding the row removes the moving summary and leaves the full reasoning in ordinary page flow, so page reading never fights an internal follower; settlement restores the stable first-line summary at the left edge ([decision](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)).
 
-The chat view keeps Tool placement but delegates Tool presentation. It passes each ordered root call through `conversation.chat.tool`, and the details shell passes the selected call through `conversation.details.tool`. The assembled Web bundle fills the whole-Tool seat with [`ui-tool`](../ui-tool/README.md), which selects Runtime-projected Code Dispatch children and owns root/child composition, per-name dispatch, generic rendering, and render-intent cards; the details seat alone retains a raw-result fallback when that renderer is absent.
+The chat view keeps Tool placement but delegates Tool presentation. Each ordered `tool-call` Conversation Node dispatches through the matching key of `conversation.chat.node`, while the details shell passes the selected call through `conversation.details.tool`. The assembled Web bundle registers [`ui-tool`](../ui-tool/README.md) for that Chat Node key; it renders the Runtime-projected recursive root/child tree and owns per-name dispatch, generic rendering, and render-intent cards. The details seat alone retains a raw-result fallback when that renderer is absent.
 
 The chat flow projects consecutive model-retry nodes across retry turns into one stable, muted status row updated to the latest attempt; every retry event remains in the runtime snapshot and session log. Its frontend countdown anchors the scheduled delay to client receipt, avoiding host/browser clock skew, rounds remaining time up to seconds, and has a one-second floor. The latest unresolved retry uses a left-to-right text shimmer. Subsequent turn facts distinguish an attempt that started from one cancelled during backoff, while the Host running bit only controls the live animation; the row then shows a static completed or cancelled label. Normal policy rows show the finite retry maximum; always policy rows show `∞`. Activating the row reveals the latest exact retry delay and failure message. The client runtime removes each failed step's streaming tail before its retry node arrives, while the status remains visible after a later attempt succeeds. An unretried terminal failure renders as a persistent inline status at its turn boundary, showing the display-safe durable message and optional error code without offering an action the Host cannot fulfill; AUTH copy never echoes provider-supplied credential fragments.
 
@@ -40,7 +40,7 @@ The chat stats line takes its token accounting from the generic token-meter `tok
 
 `src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` export surface contains only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations.
 
-A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` contract — an absent service leaves the prose inert.
+A finished turn materializes one ordered `turn-tail` Conversation Node. Its engine-owned `TurnLocation` supplies the closing Assistant and Turn data; the renderer places the `conversation.chat.turnTail` chain before that node's IconActions and dispatches `TurnTailOwnerProps` containing the Turn, closing seq, and `openFile`. This package owns only the hole; `@deepseek-ai/dsh-client-ui-deliverables` accumulates mutation-tool `locations` into Turn data and owns the produced-files row, chip cap, and copy, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost. The closing prose participates through the same off switch: the chat view asks the optional `chatFileMentions` service (ctx.get; provided by the same plugin) for a closing message's inline-code vocabulary and threads the result into MarkdownText's `fileMentions` seam — an absent service leaves the prose inert.
 
 ## Model Experience
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 25574421bb..e37f867c72 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -18,7 +18,7 @@
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 
-聊天视图保留 Tool 的消息流位置，但委托其展示。它通过 `conversation.chat.tool` 传递每个已排序的 root call；详情壳层则通过 `conversation.details.tool` 传递当前选中的调用。组装后的 Web bundle 由 [`ui-tool`](../ui-tool/README.md) 填充整体 Tool 席位，并由后者选择 Runtime 已投影的 Code Dispatch 子调用，负责 root/child 编排、按名称分发、通用展示和 render-intent 卡片；只有详情席位会在该 renderer 缺席时保留 raw-result fallback。
+聊天视图保留 Tool 的消息流位置，但委托其展示。每个已排序的 `tool-call` Conversation Node 都通过 `conversation.chat.node` 的同名 key 分发；详情壳层则通过 `conversation.details.tool` 传递当前选中的调用。组装后的 Web bundle 为该 Chat Node key 注册 [`ui-tool`](../ui-tool/README.md)，由后者渲染 Runtime 已投影的递归 root/child 树，并负责按名称分发、通用展示和 render-intent 卡片；只有详情席位会在该 renderer 缺席时保留 raw-result fallback。
 
 聊天流会将跨重试轮次连续出现的模型重试节点投影为一个稳定的弱化状态行，并用最新一次尝试更新该行；每个重试事件仍保留在运行时快照与会话日志中。前端倒计时以客户端收到事件的时刻为计划延迟的起点，避免 Host 与浏览器的时钟偏差；剩余时间向上取整到秒，且下限为 1 秒。最近一次尚未完成的重试会显示从左到右的文字渐变动画。后续轮次事实用于区分已开始的尝试与在退避期间取消的尝试，Host 的 running 位只控制实时动画；随后该行会显示静态的已完成或已取消标签。normal 策略行显示有限重试上限；always 策略行显示 `∞`。激活该行会显示最近一次重试的精确延迟和失败消息。客户端运行时会在相应重试节点到达前移除每个失败步骤的流式输出尾部；后续某次尝试成功后，该状态仍保持可见。未进入重试的终态失败会在其轮次边界渲染为持久的内联状态，展示适合显示的持久消息与可选错误码，但不会提供 Host 无法兑现的操作；AUTH 文案绝不会回显提供方给出的凭据片段。
 
@@ -40,7 +40,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 `src/client/` 按领域组织。`contract/` 是 slot 声明、组合 props 与跨领域类型的共享表层；`skeleton/`、`chat/`、`input/`、`queue/` 和 `settings/` 保持内部实现，`apply.ts` 是它们的组装点。`/client` 导出表层只包含 loader entry、service class 和 contract 类型；组件与 store factory 经 slot 注册抵达页面。
 
-完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。收尾正文经由同一个开关参与其中：chat 视图向可选的 `chatFileMentions` service（ctx.get；由同一插件提供）索取收尾消息的行内代码词表，并把结果接进 MarkdownText 的 `fileMentions` 约定——service 缺席时正文保持死文本。
+完成的一轮会物化一个有序的 `turn-tail` Conversation Node。它由引擎维护的 `TurnLocation` 提供收尾 Assistant 和 Turn data；renderer 在该 Node 的 IconActions 之前渲染 `conversation.chat.turnTail` chain，并派发包含 Turn、收尾 seq 和 `openFile` 的 `TurnTailOwnerProps`。本包只拥有空位；`@deepseek-ai/dsh-client-ui-deliverables` 把改写工具的 `locations` 累积到 Turn data，并拥有产物行、chip 上限和文案，因此把该插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。收尾正文经由同一个开关参与其中：chat 视图向可选的 `chatFileMentions` service（ctx.get；由同一插件提供）索取收尾消息的行内代码词表，并把结果接进 MarkdownText 的 `fileMentions` seam——service 缺席时正文保持死文本。
 
 ## 模型体验
 
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 474e7f9db5..eec5450e2d 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -56,11 +56,10 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      */
     'conversation.chat.commandview': { kind: 'keyed'; scope: 'session'; owner: CommandRowOwnerProps }
     /**
-     * The chat view's turn-tail chain: rendered between a closing assistant
-     * message's body and its IconActions footer, once per turn (the render
-     * site elects the closing seq). Entries derive a match from the owner
-     * currency before mounting, so presentation components never mount only
-     * to return null; an all-declined chain renders nothing.
+     * The completed Turn Node's extension chain, rendered before that Node's
+     * IconActions. Entries derive a match from the engine-owned Turn and
+     * closing seq before mounting, so presentation components never mount
+     * only to return null; an all-declined chain renders nothing.
      */
     'conversation.chat.turnTail': { kind: 'chain'; scope: 'session'; owner: TurnTailOwnerProps }
     /** Selected Tool call output inside the details panel. */
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
index 2bdf960226..8a487c89ed 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
@@ -7,7 +7,7 @@ import {
   emptyAssistantBlock, isAppendSurfaceEvent, isTokenDelta, toAssistantBlock, toAssistantBlocks,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { AssistantChatData } from '../contract/chat-nodes.ts'
-import { chatNode } from './common.ts'
+import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
   interface ChatNodeDataMap {
@@ -169,7 +169,7 @@ function finalNode(
   if (boundary === undefined || !hasInterruptionEvidence(blocks)) return undefined
   return {
     kind: 'assistant',
-    seq: boundary.seq - 0.9,
+    seq: boundary.seq + CHAT_SYNTHETIC_SEQ_OFFSETS.interruptedAssistant,
     time: boundary.time,
     turn: state.turn,
     step: state.step,
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
index f9491d2d16..f417c33b75 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/chat-snapshot-builder.ts
@@ -154,6 +154,9 @@ const EMPTY_CONTRIBUTION: LegacyContribution = {
 
 function legacyContribution(raw: ChatConversationViewNode): LegacyContribution {
   const node = raw as ChatNode
+  // Content-free settled Assistants remain in the finalized compatibility
+  // stream so StatsLine preserves its pre-assembly step counts; hidden running
+  // attempts have no final Node to contribute.
   if (raw.visibility !== 'visible' && node.kind !== 'assistant-step') return EMPTY_CONTRIBUTION
   switch (node.kind) {
     case 'user':
@@ -221,7 +224,7 @@ function sameContribution(left: LegacyContribution | undefined, right: LegacyCon
     && sameReferences(left.nodes, right.nodes)
 }
 
-/** Incremental compatibility projection retained solely for unmigrated Trajectory consumers. */
+/** Incremental compatibility projection for StatsLine and legacy top-level snapshot fields. */
 class LegacySliceBuilder {
   private readonly contributions = new Map<string, LegacyContribution>()
   private readonly finalizedContributions = new Map<string, LegacyContribution>()
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/common.ts b/packages/client/ui-conversation/src/client/conversation-nodes/common.ts
index 8e1d9d7bd4..b6bd01930b 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/common.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/common.ts
@@ -5,6 +5,16 @@ import type {
   ChatNode, ChatNodeDataMap, ChatNodeKind,
 } from '../contract/chat-nodes.ts'
 
+/**
+ * Relative positions in one durable event's seq neighborhood: interrupted
+ * Assistant, its follow-up Nodes, then follow-ups to an ordinary final.
+ */
+export const CHAT_SYNTHETIC_SEQ_OFFSETS = {
+  interruptedAssistant: -0.9,
+  interruptedFollowup: -0.8,
+  finalizedFollowup: 0.1,
+} as const
+
 /**
  * Resolve one Context's best currently loaded event Location.
  * @param context - assembled business Context.
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
index 04a5770f5a..23201fec3e 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
@@ -5,7 +5,7 @@ import type {
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ToolChatData } from '../contract/chat-nodes.ts'
-import { chatNode } from './common.ts'
+import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
   interface ChatNodeDataMap {
@@ -190,7 +190,7 @@ function projectBlock(
     ? sameReferences(block.subCalls, children) ? block : { ...block, subCalls: children }
     : {
       kind: 'tool-result',
-      seq: interruptedAt.seq - 0.8,
+      seq: interruptedAt.seq + CHAT_SYNTHETIC_SEQ_OFFSETS.interruptedFollowup,
       time: interruptedAt.time,
       callId: block.callId,
       call: { name: block.name, argsRaw: block.argsRaw },
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
index 346bd41bdf..51cb348e6a 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
@@ -7,7 +7,7 @@ import type {
   AssistantChatData, FinalAssistantChatData, TurnTailChatData,
 } from '../contract/chat-nodes.ts'
 import { deriveTurnMetrics } from '../chat/turn-metrics.ts'
-import { chatNode } from './common.ts'
+import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
   interface ChatNodeDataMap {
@@ -85,7 +85,9 @@ function closingAnchor(context: ConversationNodeContext<TurnTailState>): number
     }
     if (event.type === 'assistant/message') {
       steps.set(coordinates.step, { streamedText: false, finalized: true })
-      if (hasTextAssistant(event)) anchor = event.seq + 0.1
+      if (hasTextAssistant(event)) {
+        anchor = event.seq + CHAT_SYNTHETIC_SEQ_OFFSETS.finalizedFollowup
+      }
       continue
     }
     if ((event.type as string) === 'llm/retry') {
@@ -93,7 +95,7 @@ function closingAnchor(context: ConversationNodeContext<TurnTailState>): number
       continue
     }
     if (event.type === 'step/end' && previous.streamedText && !previous.finalized) {
-      anchor = event.seq - 0.8
+      anchor = event.seq + CHAT_SYNTHETIC_SEQ_OFFSETS.interruptedFollowup
     }
   }
   return anchor
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index ca5f3cd25c..84c6fa42af 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/client/ui-tool/README.md
-README.md: d6bc0f248cffaf4c65ecf6d97c7a4afb17fc8941
-README.zh.md: 6b6e2a153be6a3cad5b57379de6fdc0cd4a58ea4
+README.md: b33aef86a6ad161f70105968f308c5a587c25c24
+README.zh.md: 680a5149187bc43513c74134a9a58c4680af854c
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index d6bc0f248c..b33aef86a6 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Client Tool presentation plugin. `ui-conversation` supplies one ordered root call through `conversation.chat.tool`; this package renders that root and its Code Dispatch children, then dispatches every atomic call through the keyed `tool.call.toolview` slot. Unregistered Tool names use the generic card.
+Client Tool presentation plugin. `ui-conversation` dispatches each ordered `tool-call` Conversation Node through the matching key of `conversation.chat.node`; this package renders its root and Code Dispatch children, then dispatches every atomic call through the keyed `tool.call.toolview` slot. Unregistered Tool names use the generic card.
 
 Business UI packages register only their wire Tool names and atomic views. They do not pair Session events, rebuild the transcript, or own root/subcall topology. The Runtime remains authoritative for call/result pairing, lifecycle, and recursive `subCalls` projection; the conversation view remains authoritative for ChatFlow placement.
 
@@ -10,7 +10,7 @@ Business UI packages register only their wire Tool names and atomic views. They
 
 `ToolCallTree` receives one root `ToolCallBlock` that already contains recursive `subCalls`, selection state, the session `cwd`, and Host callbacks for opening files and inspecting calls. It recursively walks the standard call blocks and sends the root and children at every depth through the same atomic dispatch path, without subscribing to a separate parent-to-children map.
 
-Each root and child wrapper preserves the `conversation.chat.tool` call-anchor DOM contract used for paging and selection.
+Each root and child wrapper preserves the `data-chat-anchor-key="call:<id>"` and `data-chat-call-id` DOM contract used for paging and selection.
 
 The package also fills `conversation.details.tool` with `ToolDetails`. The row and details renderers share the same pure card models for `terminal`, `read`, `diff`, `search`, and `web` render intents. Unknown intent tags and malformed wire card data fall back to flattened Tool result text.
 
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index 6b6e2a153b..680a514918 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交付一个已经排好位置的 root call；本包渲染该 root 及其 Code Dispatch 子调用，并把每个原子调用通过 keyed slot `tool.call.toolview` 分发。没有注册的 Tool 名称使用通用卡片。
+Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.node` 的同名 key 分发每个已排序的 `tool-call` Conversation Node；本包渲染其中的 root 及其 Code Dispatch 子调用，并把每个原子调用通过 keyed slot `tool.call.toolview` 分发。没有注册的 Tool 名称使用通用卡片。
 
 业务 UI 包只注册 wire Tool 名称和原子视图，不配对 Session Event、不重建 transcript，也不拥有 root/subcall 拓扑。Runtime 继续负责 call/result 配对、生命周期和递归 `subCalls` 投影；conversation view 继续负责 ChatFlow 位置。
 
@@ -10,7 +10,7 @@ Client Tool 展示插件。`ui-conversation` 通过 `conversation.chat.tool` 交
 
 `ToolCallTree` 接收一个已经包含递归 `subCalls` 的 root `ToolCallBlock`、selection 状态、会话 `cwd`，以及用于打开文件和检查调用的 Host 回调。它递归遍历标准 call block，让 root 与任意深度的 child 经过同一条原子分发路径，不再订阅独立的 parent-to-children map。
 
-每个 root 和 child wrapper 都保留 `conversation.chat.tool` 的 call-anchor DOM 约定，供分页和 selection 使用。
+每个 root 和 child wrapper 都保留 `data-chat-anchor-key="call:<id>"` 与 `data-chat-call-id` DOM 约定，供分页和 selection 使用。
 
 本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 为 `terminal`、`read`、`diff`、`search` 和 `web` render intent 共用同一组纯 card model。本版本不认识的 intent 标签和格式错误的 wire card 数据都会回退为压平的 Tool result 文本。
 

From 3d70889a8d7f19de7c4dc2ede606fe1c8bc618d9 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:53:09 +0800
Subject: [PATCH 491/516] refactor(session): unify event map augmentation
 entrypoint

---
 packages/compact/compact/src/types.ts               |  2 +-
 packages/core/agent/src/types.ts                    |  2 +-
 packages/core/session/tests/fork.spec.ts            |  2 +-
 .../session/tests/gen-persistence-catalog.spec.ts   |  2 +-
 packages/core/tools/src/code-mode.ts                |  2 +-
 packages/feedback/command-feedback/src/index.ts     |  2 +-
 packages/goal/goal/src/domain.ts                    |  2 +-
 packages/hooks/hook-protocol/src/types.ts           |  2 +-
 packages/interaction/commands/src/index.ts          |  2 +-
 packages/interaction/permission/src/index.ts        |  2 +-
 packages/interaction/user-approval/src/index.ts     |  2 +-
 packages/llm/llm-retry/src/index.ts                 | 13 ++-----------
 packages/llm/llm-retry/src/types.ts                 |  9 +++++++++
 packages/plan/plan-mode/src/index.ts                |  2 +-
 packages/sandbox/sandbox-policy/src/session-mode.ts |  2 +-
 .../session-projection-cache/tests/cache.spec.ts    |  2 +-
 .../session-projection/tests/registry.spec.ts       |  2 +-
 .../session-telemetry/tests/telemetry.spec.ts       |  2 +-
 packages/session/session-title-llm/src/index.ts     |  2 +-
 packages/session/session-title/src/index.ts         |  2 +-
 packages/subagent/subagent/src/descriptor.ts        |  2 +-
 packages/web/web-search-deepseek/src/provider.ts    |  2 +-
 22 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index c321be426e..df5e749cd8 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -11,7 +11,7 @@ import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { CompactionId } from './brand.ts'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Marks the start of a compaction — log-only, holds the lock until
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index d21f25cdc7..8decb9ba3f 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -290,7 +290,7 @@ declare module 'cordis' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * One normalized mutation of an agent's durable pending-message lists.
diff --git a/packages/core/session/tests/fork.spec.ts b/packages/core/session/tests/fork.spec.ts
index 0e7a0629c3..58985cfb34 100644
--- a/packages/core/session/tests/fork.spec.ts
+++ b/packages/core/session/tests/fork.spec.ts
@@ -4,7 +4,7 @@ import { createUserMessage, CallId , createMessage } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionForkError, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     'test/log-only': { value: string }
     /** Stands in for a plugin's open/close bracket (`compact/start`). */
diff --git a/packages/core/session/tests/gen-persistence-catalog.spec.ts b/packages/core/session/tests/gen-persistence-catalog.spec.ts
index 9a09cb3489..22bc09835f 100644
--- a/packages/core/session/tests/gen-persistence-catalog.spec.ts
+++ b/packages/core/session/tests/gen-persistence-catalog.spec.ts
@@ -35,7 +35,7 @@ const make = (files: Record<string, string>): string => {
 
 /** A merge-form declaration file wrapping `members` in the session module. */
 const merge = (members: string): string =>
-  `declare module '@deepseek-ai/dsh-session' {\n  interface SessionEventMap {\n${members}\n  }\n}\n`
+  `declare module '@deepseek-ai/dsh-session/types' {\n  interface SessionEventMap {\n${members}\n  }\n}\n`
 
 afterEach(() => {
   while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index 63c5b2cb9b..984fecab88 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -15,7 +15,7 @@ import { defineTool, parameterSchemaSpecToJsonSchema } from './schema.ts'
 import { TOOL_REGISTRY_SCHEDULER } from './index.ts'
 import type { CodeDispatchLog, ToolDefinition, ToolExecutionResult, ToolRegistry, ToolRunContext } from './index.ts'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * One sub-dispatch STARTING inside a `run_code` program: the parent
diff --git a/packages/feedback/command-feedback/src/index.ts b/packages/feedback/command-feedback/src/index.ts
index ae78b3cd4f..037a463104 100644
--- a/packages/feedback/command-feedback/src/index.ts
+++ b/packages/feedback/command-feedback/src/index.ts
@@ -15,7 +15,7 @@ export const inject = ['commands']
 
 const USAGE = 'Usage: /feedback <text>'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * One recorded human remark about this session. Log-only and independent
diff --git a/packages/goal/goal/src/domain.ts b/packages/goal/goal/src/domain.ts
index 8c8c4de6b6..90f22a1602 100644
--- a/packages/goal/goal/src/domain.ts
+++ b/packages/goal/goal/src/domain.ts
@@ -58,7 +58,7 @@ declare module '@deepseek-ai/dsh-llm' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Complete post-mutation goal state or clear tombstone.
diff --git a/packages/hooks/hook-protocol/src/types.ts b/packages/hooks/hook-protocol/src/types.ts
index 82a67f9b93..adaafd6b0f 100644
--- a/packages/hooks/hook-protocol/src/types.ts
+++ b/packages/hooks/hook-protocol/src/types.ts
@@ -5,7 +5,7 @@
  * @module @deepseek-ai/dsh-hook-protocol/types
  */
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * A hook command was invoked at a hook point — a log-only record (like
diff --git a/packages/interaction/commands/src/index.ts b/packages/interaction/commands/src/index.ts
index 780569c159..ba7b449228 100644
--- a/packages/interaction/commands/src/index.ts
+++ b/packages/interaction/commands/src/index.ts
@@ -131,7 +131,7 @@ class CommandLayer implements ScopeLayer {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * A resolved slash command entered its handler. Log-only (never model
diff --git a/packages/interaction/permission/src/index.ts b/packages/interaction/permission/src/index.ts
index 44d62a9c33..35b762b2aa 100644
--- a/packages/interaction/permission/src/index.ts
+++ b/packages/interaction/permission/src/index.ts
@@ -39,7 +39,7 @@ declare module 'cordis' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Records the selected preset as durable, log-only user intent. The knob
diff --git a/packages/interaction/user-approval/src/index.ts b/packages/interaction/user-approval/src/index.ts
index 3dfeabe570..70eacaa627 100644
--- a/packages/interaction/user-approval/src/index.ts
+++ b/packages/interaction/user-approval/src/index.ts
@@ -31,7 +31,7 @@ declare module 'cordis' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * An approval question was put to the answerer chain — log-only audit
diff --git a/packages/llm/llm-retry/src/index.ts b/packages/llm/llm-retry/src/index.ts
index dcba1e2443..2ebeb79260 100644
--- a/packages/llm/llm-retry/src/index.ts
+++ b/packages/llm/llm-retry/src/index.ts
@@ -12,16 +12,7 @@ import type { Agent, RequestErrorAction } from '@deepseek-ai/dsh-agent'
 import type { LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { RetryId } from './brand.ts'
-import type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts'
-
-declare module '@deepseek-ai/dsh-session' {
-  interface SessionEventMap {
-    /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
-    'llm/retry': LlmRetryEventData
-    /** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
-    'llm/retry-started': LlmRetryStartedEventData
-  }
-}
+import type { LlmRetryEventData } from './types.ts'
 
 export type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts'
 export { RetryId } from './brand.ts'
@@ -132,7 +123,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
   ): Promise<RequestErrorAction> {
     const fusedSignal = AbortSignal.any([signal, lifetime.signal])
     if (fusedSignal.aborted) return
-    const eventData = policy.mode === 'normal'
+    const eventData: LlmRetryEventData = policy.mode === 'normal'
       ? {
         retryId,
         turn,
diff --git a/packages/llm/llm-retry/src/types.ts b/packages/llm/llm-retry/src/types.ts
index 12820889dd..c698b68446 100644
--- a/packages/llm/llm-retry/src/types.ts
+++ b/packages/llm/llm-retry/src/types.ts
@@ -1,6 +1,15 @@
 import type { LlmFailure } from '@deepseek-ai/dsh-llm/types'
 import type { RetryId } from './brand.ts'
 
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
+    'llm/retry': LlmRetryEventData
+    /** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
+    'llm/retry-started': LlmRetryStartedEventData
+  }
+}
+
 /** Durable payload recorded before one provider-routed model-request retry wait. */
 export type LlmRetryEventData =
   | {
diff --git a/packages/plan/plan-mode/src/index.ts b/packages/plan/plan-mode/src/index.ts
index c8dd974fd2..00234424ff 100644
--- a/packages/plan/plan-mode/src/index.ts
+++ b/packages/plan/plan-mode/src/index.ts
@@ -42,7 +42,7 @@ import type { PlanProjection } from './types.ts'
 // declarations still receive the SessionProjectionMap merge.
 export type * from './types.ts'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Whether plan mode is in force from this point on: log-only, non-surface,
diff --git a/packages/sandbox/sandbox-policy/src/session-mode.ts b/packages/sandbox/sandbox-policy/src/session-mode.ts
index fc7c53938c..165a462046 100644
--- a/packages/sandbox/sandbox-policy/src/session-mode.ts
+++ b/packages/sandbox/sandbox-policy/src/session-mode.ts
@@ -21,7 +21,7 @@
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * The session's sandbox mode was switched — log-only (like `approval/*`;
diff --git a/packages/session/session-projection-cache/tests/cache.spec.ts b/packages/session/session-projection-cache/tests/cache.spec.ts
index 8474e21594..ba9dc39c57 100644
--- a/packages/session/session-projection-cache/tests/cache.spec.ts
+++ b/packages/session/session-projection-cache/tests/cache.spec.ts
@@ -24,7 +24,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     'cache-test/mark': { marks: string[] }
   }
diff --git a/packages/session/session-projection/tests/registry.spec.ts b/packages/session/session-projection/tests/registry.spec.ts
index bd33914b2d..e54f1f2468 100644
--- a/packages/session/session-projection/tests/registry.spec.ts
+++ b/packages/session/session-projection/tests/registry.spec.ts
@@ -22,7 +22,7 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     'test/mark': { marks: string[] }
   }
diff --git a/packages/session/session-telemetry/tests/telemetry.spec.ts b/packages/session/session-telemetry/tests/telemetry.spec.ts
index 31e587c301..029381fe78 100644
--- a/packages/session/session-telemetry/tests/telemetry.spec.ts
+++ b/packages/session/session-telemetry/tests/telemetry.spec.ts
@@ -17,7 +17,7 @@ import {
   type TelemetryRecord,
 } from '../src/index.ts'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Test-only merged event proving unknown types flow through unchanged.
diff --git a/packages/session/session-title-llm/src/index.ts b/packages/session/session-title-llm/src/index.ts
index 1b0e328621..52572db30d 100644
--- a/packages/session/session-title-llm/src/index.ts
+++ b/packages/session/session-title-llm/src/index.ts
@@ -37,7 +37,7 @@ export interface SessionTitleLlmRequestEventData {
   readonly maxTokens: number
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /** Log-only pre-dispatch record of one session-title model request. */
     'session/title-llm-request': SessionTitleLlmRequestEventData
diff --git a/packages/session/session-title/src/index.ts b/packages/session/session-title/src/index.ts
index 12ca7924b4..6f8594edd4 100644
--- a/packages/session/session-title/src/index.ts
+++ b/packages/session/session-title/src/index.ts
@@ -91,7 +91,7 @@ declare module 'cordis' {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Latest-wins session title snapshot. Log-only: it never enters the model
diff --git a/packages/subagent/subagent/src/descriptor.ts b/packages/subagent/subagent/src/descriptor.ts
index 55ba73dcc4..6d9dedee75 100644
--- a/packages/subagent/subagent/src/descriptor.ts
+++ b/packages/subagent/subagent/src/descriptor.ts
@@ -25,7 +25,7 @@ import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import type { ToolRestriction } from '@deepseek-ai/dsh-tools'
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
      * Durable identity and lifecycle mode of a session-backed subagent child,
diff --git a/packages/web/web-search-deepseek/src/provider.ts b/packages/web/web-search-deepseek/src/provider.ts
index 4bacd80fec..f88941fa12 100644
--- a/packages/web/web-search-deepseek/src/provider.ts
+++ b/packages/web/web-search-deepseek/src/provider.ts
@@ -77,7 +77,7 @@ export interface DeepSeekSearchLlmRequest {
   }
 }
 
-declare module '@deepseek-ai/dsh-session' {
+declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /** Secret-free auxiliary DeepSeek search request recorded before dispatch. */
     'web/deepseek-search-llm-request': DeepSeekSearchLlmRequest

From 10464d155def7c3cdc22459e6bfe824cc118a10a Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:42:25 +0800
Subject: [PATCH 492/516] fix(client): consume typed business session events

---
 ...08-09-client-conversation-node-assembly.md |   2 +-
 ...09-client-conversation-node-assembly.zh.md |   2 +-
 packages/client/runtime/package.json          |   2 +
 .../sessions/conversation-location-index.ts   |  12 +-
 .../src/client/sessions/request-inspection.ts | 108 ++++++------------
 .../src/client/sessions/steering-history.ts   |   5 +-
 .../src/client/sessions/tool-call-tree.ts     |  22 +---
 packages/client/runtime/tsconfig.json         |   6 +
 packages/client/ui-conversation/package.json  |   8 ++
 .../client/conversation-nodes/assistant.ts    |  10 +-
 .../src/client/conversation-nodes/command.ts  |  72 +++++-------
 .../client/conversation-nodes/compaction.ts   |  14 +--
 .../src/client/conversation-nodes/inbox.ts    |  13 ++-
 .../src/client/conversation-nodes/retry.ts    |  58 +++-------
 .../src/client/conversation-nodes/tool.ts     |  31 ++---
 .../client/conversation-nodes/turn-error.ts   |   7 +-
 .../client/conversation-nodes/turn-tail.ts    |   9 +-
 .../ui-conversation/tests/chat-apply.spec.tsx |   4 +-
 .../conversation-node-definitions.spec.ts     |  22 ++++
 packages/client/ui-conversation/tsconfig.json |  12 ++
 packages/compact/compact/package.json         |   8 +-
 packages/compact/compact/src/types.ts         |   4 +-
 packages/core/agent/package.json              |   4 +-
 packages/core/agent/src/dispatch.ts           |   2 +-
 packages/core/agent/src/inbox.ts              |   4 +-
 packages/core/agent/src/index.ts              |   5 +-
 .../agent/src/{types.ts => runtime-types.ts}  |  22 +---
 packages/core/agent/src/session-types.ts      |  27 +++++
 .../tests/gen-persistence-catalog.spec.ts     |   2 +-
 packages/core/tools/package.json              |   4 +
 packages/core/tools/src/code-mode.ts          |  36 +-----
 packages/core/tools/src/index.ts              |   1 +
 packages/core/tools/src/types.ts              |  58 ++++++++++
 packages/interaction/commands/package.json    |   4 +
 packages/interaction/commands/src/index.ts    |  42 +------
 packages/interaction/commands/src/types.ts    |  48 ++++++++
 packages/llm/llm-retry/package.json           |   4 -
 packages/llm/llm-retry/src/types.ts           |   4 +-
 .../llm/llm-retry/tests/invariant.spec.ts     |   2 +-
 .../llm/llm-retry/tests/persistence.spec.ts   |   2 +-
 .../context-breakdown-projection.spec.ts      |   2 +-
 .../tests/token-usage-projection.spec.ts      |   2 +-
 .../llm-replay/tests/llm-replay.spec.ts       |   2 +-
 pnpm-lock.yaml                                |  18 +++
 scripts/gen-persistence-catalog.ts            |  19 +--
 scripts/type-equiv.manifest.json              |  16 +--
 tsconfig.base.json                            |   3 +
 47 files changed, 405 insertions(+), 359 deletions(-)
 rename packages/core/agent/src/{types.ts => runtime-types.ts} (96%)
 create mode 100644 packages/core/agent/src/session-types.ts
 create mode 100644 packages/core/tools/src/types.ts
 create mode 100644 packages/interaction/commands/src/types.ts

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index f9768a652c..9952f8fac0 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -16,7 +16,7 @@ Business events also use different correlation models. Tool has call IDs, Assist
 
 Client Runtime provides a target-neutral Conversation Node assembly engine. Business plugins register Event Definitions, and view plugins register per-Session View Builders. `ui-conversation` registers the first built-in Definitions and the `chat` builder; Session only submits the current contiguous Event window to the engine and publishes its snapshot instead of interpreting individual conversation businesses.
 
-The complete derivation, business-by-business validation, and file-level implementation plan remain in [`business-node assembler version one`](../../../../docs/client-conversation-node-engine-rfc.md), [`follow-up design differences`](../../../../docs/client-conversation-node-engine-follow-up-differences.md), [`business-node and dual-view adaptation analysis`](../../../../docs/client-conversation-node-adaptation-analysis.md), and the [`Chat implementation design`](../../../../docs/client-conversation-node-chat-implementation-plan.md). Those design documents retain the full discussion; this Note fixes the responsibilities, algorithms, and trade-offs that remain relevant after implementation.
+This Note retains the derivation, business-by-business validation, responsibilities, algorithms, and trade-offs that remain relevant after implementation.
 
 ### Responsibility layers
 
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index 408d61f73b..f27a82459c 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -16,7 +16,7 @@ Client Session 既维护传输窗口、连接状态和待处理交互，也在
 
 Client Runtime 提供 target-neutral 的 Conversation Node 组装引擎，业务插件注册 Event Definition，视图插件注册 per-Session View Builder。`ui-conversation` 注册第一批内建 Definition 和 `chat` builder；Session 只负责把当前连续事件窗口送入引擎并发布它的 snapshot，不再解释具体 conversation 业务。
 
-详细的方案推导、逐业务适配和逐文件实施设计保留在 [`业务节点组装器第一版`](../../../../docs/client-conversation-node-engine-rfc.md)、[`后续方案差异`](../../../../docs/client-conversation-node-engine-follow-up-differences.md)、[`业务节点与双视图适配论证`](../../../../docs/client-conversation-node-adaptation-analysis.md) 和 [`Chat 链路工程实施设计`](../../../../docs/client-conversation-node-chat-implementation-plan.md)。这些设计稿保留完整讨论过程；本 Note 固定实现后仍需长期维护的职责、算法和取舍。
+本 Note 保留实现后仍有价值的方案推导、逐业务适配、职责、算法和取舍。
 
 ### 责任分层
 
diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
index 3176428b36..f5a9a06a60 100644
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -32,6 +32,7 @@
   },
   "license": "BSD-3-Clause",
   "dependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
@@ -41,6 +42,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
     "immer": "^10.1.1",
     "react": "^18.2.0",
     "zustand": "~4.4.7"
diff --git a/packages/client/runtime/src/client/sessions/conversation-location-index.ts b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
index 20fe3efdff..c842a230a9 100644
--- a/packages/client/runtime/src/client/sessions/conversation-location-index.ts
+++ b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
@@ -139,7 +139,11 @@ export class ConversationLocationIndex {
     return this.timeline
   }
 
-  /** Replace all Definition-owned Location values while preserving reader identities. */
+  /**
+   * Replace all Definition-owned Location values while preserving reader identities.
+   * @param entries - complete current set of Definition-owned Location values.
+   * @returns whether any published Location data changed.
+   */
   replaceData(entries: readonly { readonly owner: string; readonly data: ConversationLocationData }[]): boolean {
     const turns = new Map<number, Map<string, OwnedLocationData>>()
     const steps = new Map<string, Map<string, OwnedLocationData>>()
@@ -165,7 +169,11 @@ export class ConversationLocationIndex {
     return changed
   }
 
-  /** Apply changed Context publications without rebuilding Turn/Step membership. */
+  /**
+   * Apply changed Context publications without rebuilding Turn/Step membership.
+   * @param changes - incremental removals and replacements from published Contexts.
+   * @returns whether any published Location data changed.
+   */
   applyData(changes: readonly ConversationLocationDataChange[]): boolean {
     let changed = false
     for (const change of changes) {
diff --git a/packages/client/runtime/src/client/sessions/request-inspection.ts b/packages/client/runtime/src/client/sessions/request-inspection.ts
index 36ae79eebe..162f34d5ff 100644
--- a/packages/client/runtime/src/client/sessions/request-inspection.ts
+++ b/packages/client/runtime/src/client/sessions/request-inspection.ts
@@ -5,6 +5,9 @@
 import type { ContentBlock, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm/types'
 import type { HistoryEntry } from '@deepseek-ai/dsh-client-connection/client'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {} from '@deepseek-ai/dsh-compact/types'
+import type {} from '@deepseek-ai/dsh-llm-retry/types'
+import type {} from '@deepseek-ai/dsh-tools/types'
 import type {
   AssistantProvenanceView, AssistantRequestConfig,
 } from './conversation.ts'
@@ -109,48 +112,6 @@ export function inspectRequests(
   }
 }
 
-interface RetryEvent {
-  type: 'llm/retry'
-  seq: number
-  time: number
-  data: {
-    turn: number
-    step: number
-    retry: number
-    maxRetries: number
-    delayMs: number
-    failure: { message: string }
-  }
-}
-
-interface CompactionStartEvent {
-  type: 'compact/start'
-  seq: number
-  time: number
-  data: { turn: number | null }
-}
-
-interface CompactionSummaryEvent {
-  type: 'compact/summary'
-  seq: number
-  time: number
-  data: {
-    summary: readonly ContentBlock[]
-    rawOutput?: readonly ContentBlock[]
-    provider: string
-    model: string
-    maxTokens?: number
-    usage?: unknown
-  }
-}
-
-interface CompactionEndEvent {
-  type: 'compact/end'
-  seq: number
-  time: number
-  data: { turn: number | null; error?: string }
-}
-
 function requestKey(turn: number, step: number): string {
   return `${turn}\u0000${step}`
 }
@@ -205,10 +166,8 @@ function deriveCallSchemas(
       capture(String(event.data.callId), event.data.name)
       continue
     }
-    const type = event.type as string
-    if (type === 'tool/code-dispatch-start' || type === 'tool/code-dispatch') {
-      const data = event.data as unknown as { subCallId: string; name: string }
-      capture(data.subCallId, data.name)
+    if (event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch') {
+      capture(String(event.data.subCallId), event.data.name)
     }
   }
   return calls
@@ -351,14 +310,14 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[]
       if (activeStep === key) activeStep = undefined
       continue
     }
-    if ((sourceEvent.type as string) === 'llm/retry') {
-      const event = sourceEvent as unknown as RetryEvent
-      updateAssistant(ordinaryByStep.get(requestKey(event.data.turn, event.data.step)), {
+    if (sourceEvent.type === 'llm/retry') {
+      const data = sourceEvent.data
+      updateAssistant(ordinaryByStep.get(requestKey(data.turn, data.step)), {
         status: 'error',
-        error: displayFailureMessage(event.data.failure),
-        retry: event.data.retry,
-        maxRetries: event.data.maxRetries,
-        retryDelayMs: event.data.delayMs,
+        error: displayFailureMessage(data.failure),
+        retry: data.retry,
+        ...data.mode === 'normal' ? { maxRetries: data.maxRetries } : {},
+        retryDelayMs: data.delayMs,
       })
       continue
     }
@@ -374,8 +333,7 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[]
       continue
     }
 
-    const type = sourceEvent.type as string
-    if (type === 'session/end-seed' && activeCompaction !== undefined) {
+    if (sourceEvent.type === 'session/end-seed' && activeCompaction !== undefined) {
       updateCompaction(activeCompaction, {
         completedAt: sourceEvent.time,
         status: 'error',
@@ -384,37 +342,36 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[]
       activeCompaction = undefined
       continue
     }
-    if (type === 'compact/start') {
-      const event = sourceEvent as unknown as CompactionStartEvent
+    if (sourceEvent.type === 'compact/start') {
       activeCompaction = requests.length
       requests.push({
         purpose: 'compaction',
-        startSeq: event.seq,
-        turn: event.data.turn,
+        startSeq: sourceEvent.seq,
+        turn: sourceEvent.data.turn,
         step: 0,
-        startedAt: event.time,
+        startedAt: sourceEvent.time,
         completedAt: null,
         status: 'running',
       })
       continue
     }
-    if (type === 'compact/summary' && activeCompaction !== undefined) {
-      const event = sourceEvent as unknown as CompactionSummaryEvent
+    if (sourceEvent.type === 'compact/summary' && activeCompaction !== undefined) {
+      const data = sourceEvent.data
       updateCompaction(activeCompaction, {
-        resultSeq: event.seq,
-        summary: event.data.summary,
-        ...(event.data.rawOutput === undefined ? {} : { rawOutput: event.data.rawOutput }),
+        resultSeq: sourceEvent.seq,
+        summary: data.summary,
+        ...(data.rawOutput === undefined ? {} : { rawOutput: data.rawOutput }),
         provenance: {
-          provider: event.data.provider,
-          model: event.data.model,
+          provider: data.provider,
+          model: data.model,
         },
         requestConfig: {
-          provider: event.data.provider,
-          model: event.data.model,
+          provider: data.provider,
+          model: data.model,
           purpose: 'compaction',
-          ...(event.data.maxTokens === undefined ? {} : { maxTokens: event.data.maxTokens }),
+          ...(data.maxTokens === undefined ? {} : { maxTokens: data.maxTokens }),
         },
-        ...(event.data.usage === undefined ? {} : { usage: event.data.usage }),
+        ...(data.usage === undefined ? {} : { usage: data.usage }),
       })
       continue
     }
@@ -426,12 +383,11 @@ function deriveRequests(events: readonly SessionEvent[]): readonly RequestView[]
       updateCompaction(activeCompaction, { replacementSeq: sourceEvent.seq })
       continue
     }
-    if (type !== 'compact/end' || activeCompaction === undefined) continue
-    const event = sourceEvent as unknown as CompactionEndEvent
+    if (sourceEvent.type !== 'compact/end' || activeCompaction === undefined) continue
     updateCompaction(activeCompaction, {
-      completedAt: event.time,
-      status: event.data.error === undefined ? 'complete' : 'error',
-      ...(event.data.error === undefined ? {} : { error: event.data.error }),
+      completedAt: sourceEvent.time,
+      status: sourceEvent.data.error === undefined ? 'complete' : 'error',
+      ...(sourceEvent.data.error === undefined ? {} : { error: sourceEvent.data.error }),
     })
     activeCompaction = undefined
   }
diff --git a/packages/client/runtime/src/client/sessions/steering-history.ts b/packages/client/runtime/src/client/sessions/steering-history.ts
index 0f66025e16..4220a769ff 100644
--- a/packages/client/runtime/src/client/sessions/steering-history.ts
+++ b/packages/client/runtime/src/client/sessions/steering-history.ts
@@ -1,6 +1,7 @@
 /** Reconstruct durable steering identity from the event-sourced agent inbox. */
 
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {} from '@deepseek-ai/dsh-agent/types'
 
 type InboxTarget = 'next-turn' | 'next-step'
 
@@ -45,8 +46,8 @@ export class SteeringHistory {
    * @returns true only for a user-origin message previously claimed from `next-step`.
    */
   apply(event: SessionEvent): boolean {
-    if ((event.type as string) === 'agent/inbox/spliced') {
-      this.applySplice(event.data as unknown as InboxSplice)
+    if (event.type === 'agent/inbox/spliced') {
+      this.applySplice(event.data)
       return false
     }
     if (event.type !== 'user/message') return false
diff --git a/packages/client/runtime/src/client/sessions/tool-call-tree.ts b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
index fbc32e0cef..4507b7a947 100644
--- a/packages/client/runtime/src/client/sessions/tool-call-tree.ts
+++ b/packages/client/runtime/src/client/sessions/tool-call-tree.ts
@@ -1,5 +1,5 @@
-import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import type {} from '@deepseek-ai/dsh-tools/types'
 import type {
   ConversationNode, RunningToolCall, ToolCallBlock, ToolResultNode,
 } from './conversation.ts'
@@ -55,13 +55,8 @@ export class ToolCallTree {
    * @returns Whether the event was consumed as a child-call lifecycle event.
    */
   apply(event: SessionEvent): boolean {
-    if ((event.type as string) === 'tool/code-dispatch-start') {
-      const data = event.data as unknown as {
-        parentCallId: string
-        subCallId: string
-        name: string
-        arguments: unknown
-      }
+    if (event.type === 'tool/code-dispatch-start') {
+      const data = event.data
       const running: RunningToolCall = {
         callId: data.subCallId,
         name: data.name,
@@ -78,15 +73,8 @@ export class ToolCallTree {
       this.revision++
       return true
     }
-    if ((event.type as string) !== 'tool/code-dispatch') return false
-    const data = event.data as unknown as {
-      parentCallId: string
-      subCallId: string
-      name: string
-      arguments: unknown
-      isError: boolean
-      content: ContentBlock[]
-    }
+    if (event.type !== 'tool/code-dispatch') return false
+    const data = event.data
     const siblings = this.childrenByParent.get(data.parentCallId) ?? []
     const at = siblings.findIndex(sub => sub.callId === data.subCallId)
     if (at === -1 && !this.acceptEdge(data.parentCallId, data.subCallId)) return true
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index 867b2f588c..b8949fc6db 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -26,6 +26,12 @@
     {
       "path": "../../interaction/commands"
     },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/tools"
+    },
     {
       "path": "../../compact/compact"
     },
diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
index 3f5bd8364c..e78567cbf7 100644
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -39,22 +39,28 @@
     "clsx": "^2.0.0"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-client-locale": "^0.0.1",
     "@deepseek-ai/dsh-client-runtime": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slash": "^0.0.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
     "@deepseek-ai/dsh-compact": "^0.0.1",
+    "@deepseek-ai/dsh-commands": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm-retry": "^0.0.1",
     "@deepseek-ai/dsh-token-meter": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.7",
     "react": "^18.2.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-compact": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-plan-mode": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
@@ -62,9 +68,11 @@
     "@deepseek-ai/dsh-client-ui-slash": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm-retry": "workspace:^",
     "@deepseek-ai/dsh-permission": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^",
     "@deepseek-ai/dsh-token-meter": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-tool-todo": "workspace:^",
     "@types/react": "~18.3.1",
     "cordis": "^4.0.0-rc.7",
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
index 8a487c89ed..83df1e0df6 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
@@ -6,6 +6,7 @@ import type {
 import {
   emptyAssistantBlock, isAppendSurfaceEvent, isTokenDelta, toAssistantBlock, toAssistantBlocks,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-llm-retry/types'
 import type { AssistantChatData } from '../contract/chat-nodes.ts'
 import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 
@@ -197,7 +198,7 @@ function fallbackState(context: ConversationNodeContext<AssistantState>): Assist
       }
       continue
     }
-    if ((match.event.type as string) === 'llm/retry' && state !== undefined) {
+    if (match.event.type === 'llm/retry' && state !== undefined) {
       state = resetForRetry(state)
     }
   }
@@ -247,9 +248,8 @@ export const assistantDefinition: ConversationNodeDefinition<AssistantState> = {
       || (event.type === 'assistant/message' && isAppendSurfaceEvent(event))) {
       return { id: `${event.data.turn}:${event.data.step}`, role: 'update' }
     }
-    if ((event.type as string) === 'llm/retry') {
-      const data = event.data as unknown as { turn: number; step: number }
-      return { id: `${data.turn}:${data.step}`, role: 'update' }
+    if (event.type === 'llm/retry') {
+      return { id: `${event.data.turn}:${event.data.step}`, role: 'update' }
     }
     return null
   },
@@ -268,7 +268,7 @@ export const assistantDefinition: ConversationNodeDefinition<AssistantState> = {
         usage: match.event.data.usage,
       }
     }
-    if ((match.event.type as string) === 'llm/retry') {
+    if (match.event.type === 'llm/retry') {
       return resetForRetry(context.state)
     }
     return context.state
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/command.ts b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
index 3ca7976e32..38cb85ed87 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
@@ -5,6 +5,8 @@ import type {
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
 import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
+import type {} from '@deepseek-ai/dsh-compact/types'
+import type {} from '@deepseek-ai/dsh-commands/types'
 import type { ManualCompactionChatData } from '../contract/chat-nodes.ts'
 import { chatNode } from './common.ts'
 
@@ -32,21 +34,9 @@ interface CompactionEvidence {
   readonly checkpoint?: ConversationMatch
 }
 
-interface CommandRunData {
-  readonly commandId: CommandId
-  readonly name: string
-  readonly args?: string
-}
-
-interface CommandDoneData {
-  readonly commandId: CommandId
-  readonly kind: 'success' | 'error'
-  readonly text?: string
-  readonly sourceEventSeq?: number
-}
-
 function commandFromRun(match: ConversationMatch): CommandNode {
-  const data = match.event.data as unknown as CommandRunData
+  if (match.event.type !== 'command/run') throw new Error('command start requires command/run')
+  const data = match.event.data
   return {
     kind: 'command',
     seq: match.event.seq,
@@ -59,10 +49,12 @@ function commandFromRun(match: ConversationMatch): CommandNode {
 }
 
 function commandFromDone(match: ConversationMatch, previous?: CommandNode): CommandNode {
-  const data = match.event.data as unknown as CommandDoneData
+  if (match.event.type !== 'command/done') throw new Error('command update requires command/done')
+  const data = match.event.data
   const sourceEventSeq = data.kind === 'success'
-    && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
-    ? data.sourceEventSeq as number
+    && data.sourceEventSeq !== undefined
+    && Number.isSafeInteger(data.sourceEventSeq) && data.sourceEventSeq >= 0
+    ? data.sourceEventSeq
     : undefined
   return {
     kind: 'command',
@@ -112,28 +104,21 @@ function compactSummary(match: ConversationMatch | undefined, checkpoint: Conver
   let summary: string | null = null
   let shadowedItemCount: number | null = null
   let shadowedTokenCount: number | null = null
-  if (match !== undefined) {
-    const data = match.event.data as unknown as {
-      summary?: unknown
-      shadowedSeqs?: unknown
-      shadowedTokenCount?: unknown
-    }
+  if (match?.event.type === 'compact/summary') {
+    const data = match.event.data
     if (Array.isArray(data.summary)) {
       const text = data.summary
-        .map((block: unknown) => {
-          const value = block as { type?: unknown; text?: unknown }
-          return value.type === 'text' && typeof value.text === 'string' ? value.text : ''
-        })
+        .map(block => block.type === 'text' ? block.text : '')
         .join('')
       summary = text.trim() === '' ? null : text
     }
     shadowedItemCount = Array.isArray(data.shadowedSeqs)
-      && data.shadowedSeqs.every(seq => Number.isSafeInteger(seq) && (seq as number) >= 0)
+      && data.shadowedSeqs.every(seq => Number.isSafeInteger(seq) && seq >= 0)
       ? data.shadowedSeqs.length
       : null
     shadowedTokenCount = Number.isSafeInteger(data.shadowedTokenCount)
-      && (data.shadowedTokenCount as number) >= 0
-      ? data.shadowedTokenCount as number
+      && data.shadowedTokenCount >= 0
+      ? data.shadowedTokenCount
       : null
   }
   return {
@@ -148,9 +133,9 @@ function compactSummary(match: ConversationMatch | undefined, checkpoint: Conver
 }
 
 function fallbackState(context: ConversationNodeContext<CommandState>): CommandState | undefined {
-  const done = context.matches.find(match => (match.event.type as string) === 'command/done')
+  const done = context.matches.find(match => match.event.type === 'command/done')
   const checkpoint = context.matches.find(match => compactSource(match.event) !== undefined)
-  const summary = context.matches.find(match => (match.event.type as string) === 'compact/summary')
+  const summary = context.matches.find(match => match.event.type === 'compact/summary')
   if (checkpoint === undefined) return done === undefined ? undefined : { command: commandFromDone(done) }
   const source = compactSource(checkpoint.event)
   if (source?.sourceCommandId === undefined) return done === undefined ? undefined : { command: commandFromDone(done) }
@@ -182,7 +167,7 @@ export function updateCompactionState<State extends CompactionEvidence>(
   state: State,
   match: ConversationMatch,
 ): State {
-  if ((match.event.type as string) === 'compact/summary') return { ...state, summary: match }
+  if (match.event.type === 'compact/summary') return { ...state, summary: match }
   if (compactSource(match.event) !== undefined) return { ...state, checkpoint: match }
   return state
 }
@@ -191,27 +176,28 @@ export function updateCompactionState<State extends CompactionEvidence>(
 export const commandDefinition: ConversationNodeDefinition<CommandState> = {
   kind: 'command',
   match: (event) => {
-    if ((event.type as string) === 'command/run') {
-      return { id: String((event.data as unknown as CommandRunData).commandId), role: 'start' }
+    if (event.type === 'command/run') {
+      return { id: String(event.data.commandId), role: 'start' }
     }
-    if ((event.type as string) === 'command/done') {
-      return { id: String((event.data as unknown as CommandDoneData).commandId), role: 'update' }
+    if (event.type === 'command/done') {
+      return { id: String(event.data.commandId), role: 'update' }
     }
     const checkpoint = compactSource(event)
     if (checkpoint?.sourceCommandId !== undefined) {
       return { id: String(checkpoint.sourceCommandId), role: 'update' }
     }
-    if ((event.type as string) === 'compact/start'
-      || (event.type as string) === 'compact/summary'
-      || (event.type as string) === 'compact/end') {
-      const data = event.data as unknown as { sourceCommandId?: CommandId }
-      if (data.sourceCommandId !== undefined) return { id: String(data.sourceCommandId), role: 'update' }
+    if (event.type === 'compact/start'
+      || event.type === 'compact/summary'
+      || event.type === 'compact/end') {
+      if (event.data.sourceCommandId !== undefined) {
+        return { id: String(event.data.sourceCommandId), role: 'update' }
+      }
     }
     return null
   },
   start: (_context, match) => ({ command: commandFromRun(match) }),
   update: (context, match) => {
-    if ((match.event.type as string) === 'command/done') {
+    if (match.event.type === 'command/done') {
       return { ...context.state, command: commandFromDone(match, context.state.command) }
     }
     return updateCompactionState(context.state, match)
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
index 0742ab6539..04eace8038 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
@@ -2,6 +2,7 @@ import type { Context } from 'cordis'
 import type {
   CompactionSummaryNode, ConversationMatch, ConversationNodeContext, ConversationNodeDefinition,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-compact/types'
 import { chatNode } from './common.ts'
 import { compactSource, compactSummary, updateCompactionState } from './command.ts'
 
@@ -18,7 +19,7 @@ interface CompactionState {
 }
 
 function fallbackState(context: ConversationNodeContext<CompactionState>): CompactionState {
-  const summary = context.matches.find(match => (match.event.type as string) === 'compact/summary')
+  const summary = context.matches.find(match => match.event.type === 'compact/summary')
   const checkpoint = context.matches.find(match => compactSource(match.event) !== undefined)
   return {
     ...summary === undefined ? {} : { summary },
@@ -34,12 +35,11 @@ export const compactionDefinition: ConversationNodeDefinition<CompactionState> =
     if (checkpoint !== undefined && checkpoint.sourceCommandId === undefined) {
       return { id: checkpoint.compactionId, role: 'update' }
     }
-    if ((event.type as string) === 'compact/start'
-      || (event.type as string) === 'compact/summary'
-      || (event.type as string) === 'compact/end') {
-      const data = event.data as unknown as { compactionId?: unknown; sourceCommandId?: unknown }
-      if (typeof data.compactionId !== 'string' || data.sourceCommandId !== undefined) return null
-      return { id: data.compactionId, role: (event.type as string) === 'compact/start' ? 'start' : 'update' }
+    if (event.type === 'compact/start'
+      || event.type === 'compact/summary'
+      || event.type === 'compact/end') {
+      if (event.data.sourceCommandId !== undefined) return null
+      return { id: String(event.data.compactionId), role: event.type === 'compact/start' ? 'start' : 'update' }
     }
     return null
   },
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
index 092bcaaa59..74406c324a 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
@@ -2,6 +2,7 @@ import type { Context } from 'cordis'
 import type {
   ConversationNodeDefinition, ConversationPreviousContext,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-agent/types'
 
 type InboxTarget = 'next-turn' | 'next-step'
 
@@ -41,14 +42,14 @@ function inboxDefinition(target: InboxTarget): ConversationNodeDefinition<InboxS
   const kind = `inbox-${target}`
   return {
     kind,
-    match: event => (event.type as string) === 'agent/inbox/spliced'
-      && (event.data as unknown as { target?: unknown }).target === target
+    match: event => event.type === 'agent/inbox/spliced'
+      && event.data.target === target
       ? { id: String(event.seq), role: 'start' }
       : null,
-    start: (_context, match, reader) => applySplice(
-      reader.previous<InboxState>(kind),
-      match.event.data as unknown as InboxSplice,
-    ),
+    start: (_context, match, reader) => {
+      if (match.event.type !== 'agent/inbox/spliced') throw new Error(`${kind} start requires agent/inbox/spliced`)
+      return applySplice(reader.previous<InboxState>(kind), match.event.data)
+    },
     update: context => context.state,
     publication: () => 'none',
     buildViewNode: () => null,
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
index fe95c0052d..f383bc46d8 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
@@ -2,6 +2,7 @@ import type { Context } from 'cordis'
 import type {
   ConversationLocation, ConversationNodeDefinition, ModelRetryNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-llm-retry/types'
 import type { RetryChatData } from '../contract/chat-nodes.ts'
 import { chatNode } from './common.ts'
 
@@ -12,11 +13,6 @@ declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
   }
 }
 
-type WithoutRetryProjection<Node> = Node extends unknown
-  ? Omit<Node, 'kind' | 'seq' | 'time' | 'retryState'>
-  : never
-type RetryEventData = WithoutRetryProjection<ModelRetryNode>
-
 /** Accumulated retry attempts sharing one producer-owned RetryId. */
 export interface RetryState {
   readonly turn: number
@@ -24,31 +20,14 @@ export interface RetryState {
   readonly attempts: readonly ModelRetryNode[]
 }
 
-function retryData(value: unknown): RetryEventData | undefined {
-  if (value === null || typeof value !== 'object') return undefined
-  const data = value as Record<string, unknown>
-  if (typeof data.retryId !== 'string' || data.retryId === ''
-    || !Number.isSafeInteger(data.turn) || (data.turn as number) < 0
-    || !Number.isSafeInteger(data.step) || (data.step as number) < 0
-    || !Number.isSafeInteger(data.retry) || (data.retry as number) <= 0
-    || typeof data.delayMs !== 'number' || !Number.isFinite(data.delayMs) || data.delayMs < 0
-    || typeof data.provider !== 'string' || typeof data.policyKey !== 'string'
-    || (data.mode !== 'normal' && data.mode !== 'always')
-    || data.failure === null || typeof data.failure !== 'object') return undefined
-  if (data.mode === 'normal' && (!Number.isSafeInteger(data.maxRetries) || (data.maxRetries as number) <= 0)) {
-    return undefined
-  }
-  return data as unknown as RetryEventData
-}
-
-function scheduledNode(event: { seq: number; time: number; data: unknown }): ModelRetryNode | undefined {
-  const data = retryData(event.data)
-  return data === undefined ? undefined : {
+function scheduledNode(match: Parameters<ConversationNodeDefinition['start']>[1]): ModelRetryNode | undefined {
+  if (match.event.type !== 'llm/retry') return undefined
+  return {
     kind: 'model-retry',
-    seq: event.seq,
-    time: event.time,
+    seq: match.event.seq,
+    time: match.event.time,
     retryState: 'scheduled',
-    ...data,
+    ...match.event.data,
   }
 }
 
@@ -61,33 +40,30 @@ function isClosed(location: ConversationLocation): boolean {
 export const retryDefinition: ConversationNodeDefinition<RetryState> = {
   kind: 'model-retry',
   match: (event) => {
-    if ((event.type as string) === 'llm/retry') {
-      const data = retryData(event.data)
-      if (data === undefined) return null
-      return { id: String(data.retryId), role: data.retry === 1 ? 'start' : 'update' }
+    if (event.type === 'llm/retry') {
+      return { id: String(event.data.retryId), role: event.data.retry === 1 ? 'start' : 'update' }
     }
-    if ((event.type as string) === 'llm/retry-started') {
-      const data = event.data as unknown as { retryId?: unknown }
-      return typeof data.retryId === 'string' ? { id: data.retryId, role: 'update' } : null
+    if (event.type === 'llm/retry-started') {
+      return { id: String(event.data.retryId), role: 'update' }
     }
     return null
   },
   start: (_context, match) => {
-    const node = scheduledNode(match.event)
+    const node = scheduledNode(match)
     if (node === undefined) throw new Error('model-retry start requires a valid llm/retry event')
     return { turn: node.turn, step: node.step, attempts: [node] }
   },
   update: (context, match) => {
-    if ((match.event.type as string) === 'llm/retry') {
-      const node = scheduledNode(match.event)
+    if (match.event.type === 'llm/retry') {
+      const node = scheduledNode(match)
       return node === undefined ? context.state : { ...context.state, attempts: [...context.state.attempts, node] }
     }
-    if ((match.event.type as string) !== 'llm/retry-started') return context.state
-    const data = match.event.data as unknown as { retry: number }
+    if (match.event.type !== 'llm/retry-started') return context.state
+    const retry = match.event.data.retry
     return {
       ...context.state,
       attempts: context.state.attempts.map(attempt =>
-        attempt.retry === data.retry ? { ...attempt, retryState: 'started' } : attempt),
+        attempt.retry === retry ? { ...attempt, retryState: 'started' } : attempt),
     }
   },
   buildViewNode: (context, target) => {
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
index 23201fec3e..dc9e996dcc 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
@@ -4,6 +4,7 @@ import type {
   RunningToolCall, ToolCallBlock, ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-tools/types'
 import type { ToolChatData } from '../contract/chat-nodes.ts'
 import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts'
 
@@ -141,27 +142,30 @@ function acceptsEdge(state: ToolState, parent: string, child: string): boolean {
 }
 
 function updateDispatch(state: ToolState, match: ConversationMatch): ToolState {
-  const data = match.event.data as unknown as DispatchData
-  const siblings = state.children.get(data.parentCallId) ?? []
-  const index = siblings.findIndex(candidate => candidate.callId === data.subCallId)
-  if ((match.event.type as string) === 'tool/code-dispatch-start') {
-    if (index >= 0 || !acceptsEdge(state, data.parentCallId, data.subCallId)) return state
+  const event = match.event
+  if (event.type !== 'tool/code-dispatch-start' && event.type !== 'tool/code-dispatch') return state
+  const data = event.data
+  const parentCallId = String(data.parentCallId)
+  const subCallId = String(data.subCallId)
+  const siblings = state.children.get(parentCallId) ?? []
+  const index = siblings.findIndex(candidate => candidate.callId === subCallId)
+  if (event.type === 'tool/code-dispatch-start') {
+    if (index >= 0 || !acceptsEdge(state, parentCallId, subCallId)) return state
     const children = new Map(state.children)
-    children.set(data.parentCallId, [...siblings, childCall(match, data)])
+    children.set(parentCallId, [...siblings, childCall(match, data)])
     const parents = new Map(state.parents)
-    parents.set(data.subCallId, data.parentCallId)
+    parents.set(subCallId, parentCallId)
     return { ...state, children, parents }
   }
-  if ((match.event.type as string) !== 'tool/code-dispatch') return state
-  if (index < 0 && !acceptsEdge(state, data.parentCallId, data.subCallId)) return state
+  if (index < 0 && !acceptsEdge(state, parentCallId, subCallId)) return state
   const previous = index < 0 ? undefined : siblings[index]
   const settled = childResult(match, data, previous)
   const children = new Map(state.children)
-  children.set(data.parentCallId, index < 0
+  children.set(parentCallId, index < 0
     ? [...siblings, settled]
     : siblings.map((child, at) => at === index ? settled : child))
   const parents = new Map(state.parents)
-  if (index < 0) parents.set(data.subCallId, data.parentCallId)
+  if (index < 0) parents.set(subCallId, parentCallId)
   return { ...state, children, parents }
 }
 
@@ -236,9 +240,8 @@ export const toolDefinition: ConversationNodeDefinition<ToolState> = {
     if (event.type === 'tool/result' && isAppendSurfaceEvent(event)) {
       return { id: String(event.data.message.source.callId), role: 'update' }
     }
-    if ((event.type as string) === 'tool/code-dispatch-start' || (event.type as string) === 'tool/code-dispatch') {
-      const data = event.data as unknown as { rootCallId: string }
-      return { id: data.rootCallId, role: 'update' }
+    if (event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch') {
+      return { id: String(event.data.rootCallId), role: 'update' }
     }
     return null
   },
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
index 58725d8723..60b2fca087 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-error.ts
@@ -3,6 +3,7 @@ import type {
   ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, TurnErrorNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { displayFailureMessage } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-llm-retry/types'
 import { chatNode } from './common.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
@@ -30,9 +31,9 @@ function lastStep(context: ConversationNodeContext<TurnErrorState>): number {
 }
 
 function retryTurn(event: Parameters<ConversationNodeDefinition['match']>[0]): number | undefined {
-  if ((event.type as string) !== 'llm/retry' && (event.type as string) !== 'llm/retry-started') return undefined
-  const turn = (event.data as unknown as { turn?: unknown }).turn
-  return Number.isSafeInteger(turn) && (turn as number) >= 0 ? turn as number : undefined
+  return event.type === 'llm/retry' || event.type === 'llm/retry-started'
+    ? event.data.turn
+    : undefined
 }
 
 function failureFrom(match: ConversationMatch): TurnErrorState['failure'] | undefined {
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
index 51cb348e6a..2a1b4d2b13 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/turn-tail.ts
@@ -3,6 +3,7 @@ import type {
   ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, TurnLocation,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { isAppendSurfaceEvent, toAssistantBlocks } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-llm-retry/types'
 import type {
   AssistantChatData, FinalAssistantChatData, TurnTailChatData,
 } from '../contract/chat-nodes.ts'
@@ -58,9 +59,7 @@ function turnCoordinates(event: Parameters<ConversationNodeDefinition['match']>[
     || event.type === 'step/end') {
     return { turn: event.data.turn, step: event.data.step }
   }
-  if ((event.type as string) === 'llm/retry') {
-    return event.data as unknown as { turn: number; step: number }
-  }
+  if (event.type === 'llm/retry') return { turn: event.data.turn, step: event.data.step }
   return undefined
 }
 
@@ -90,7 +89,7 @@ function closingAnchor(context: ConversationNodeContext<TurnTailState>): number
       }
       continue
     }
-    if ((event.type as string) === 'llm/retry') {
+    if (event.type === 'llm/retry') {
       steps.set(coordinates.step, { streamedText: false, finalized: false })
       continue
     }
@@ -130,7 +129,7 @@ function tailData(context: ConversationNodeContext<TurnTailState>): TurnTailChat
     const candidate = event.type === 'tool/call'
       || (event.type === 'tool/result' && isAppendSurfaceEvent(event))
       || (event.type === 'turn/end' && event.data.reason.kind === 'error')
-      || (event.type as string) === 'llm/retry'
+      || event.type === 'llm/retry'
       ? event.seq
       : undefined
     if (candidate !== undefined && (latestTranscriptSeq === undefined || candidate > latestTranscriptSeq)) {
diff --git a/packages/client/ui-conversation/tests/chat-apply.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
index 3481ee758e..41ffd329b8 100644
--- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
@@ -62,7 +62,9 @@ describe('apply wiring', () => {
     expect(entries[0]?.options.order).toBe(0)
     // Declaring is claiming: the chat entry's registration put the hole on
     // the ledger with the contract's kind/scope.
-    expect(b.slots.spec('conversation.chat.node')).toEqual({ kind: 'keyed', scope: 'session' })
+    const nodeSlot = b.slots.spec('conversation.chat.node')
+    expect(nodeSlot).toMatchObject({ kind: 'keyed', scope: 'session' })
+    expect(nodeSlot?.inject?.hooks?.turnData).toBeTypeOf('function')
     await b.runtime.dispose()
   })
 
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
index 5346ad57f9..3e5dcccff3 100644
--- a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -644,6 +644,28 @@ describe('built-in conversation node Definitions', () => {
     })
   })
 
+  it('renders a historical compaction when its start remains outside the loaded window', () => {
+    const value = assembler([
+      at(10, 'compact/summary', {
+        compactionId: 'compact-windowed',
+        summary: [{ type: 'text', text: 'loaded summary' }],
+        shadowedSeqs: [1, 2, 3],
+        shadowedTokenCount: 42,
+      }),
+      at(11, 'user/message', {
+        ...textMessage('checkpoint-windowed', 'checkpoint'),
+        source: { kind: 'plugin', plugin: 'compact', compactionId: 'compact-windowed' },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 3 } }),
+    ], true)
+
+    expect(node(snapshot(value), 'compaction')?.data).toMatchObject({
+      summary: 'loaded summary',
+      summaryEventSeq: 10,
+      shadowedItemCount: 3,
+      shadowedTokenCount: 42,
+    })
+  })
+
   it('suppresses a turn error when the loaded tail contains only a later retry attempt', () => {
     const value = assembler([
       at(5, 'llm/retry', {
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
index 89d0067caf..0d6f250441 100644
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -23,12 +23,24 @@
     {
       "path": "../runtime"
     },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../interaction/commands"
+    },
     {
       "path": "../../session/session-projection"
     },
     {
       "path": "../../llm/token-meter"
     },
+    {
+      "path": "../../llm/llm-retry"
+    },
     {
       "path": "../../plan/plan-mode"
     },
diff --git a/packages/compact/compact/package.json b/packages/compact/compact/package.json
index bb4150ee32..860145e542 100644
--- a/packages/compact/compact/package.json
+++ b/packages/compact/compact/package.json
@@ -15,14 +15,14 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./checkpoint": {
       "types": "./lib/types/checkpoint.d.ts",
       "default": "./lib/types/checkpoint.js"
     },
-    "./brand": {
-      "types": "./lib/types/brand.d.ts",
-      "default": "./lib/types/brand.js"
-    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index df5e749cd8..53c3baf05f 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -9,7 +9,9 @@
 
 import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-import type { CompactionId } from './brand.ts'
+import { CompactionId } from './brand.ts'
+
+export { CompactionId }
 
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
diff --git a/packages/core/agent/package.json b/packages/core/agent/package.json
index 9f64d33e75..d186f32d03 100644
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -16,8 +16,8 @@
       "default": "./lib/invariant.js"
     },
     "./types": {
-      "types": "./lib/types/types.d.ts",
-      "default": "./lib/types/types.js"
+      "types": "./lib/types/session-types.d.ts",
+      "default": "./lib/types/session-types.js"
     },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
diff --git a/packages/core/agent/src/dispatch.ts b/packages/core/agent/src/dispatch.ts
index cf07f24ecf..7eff09b01d 100644
--- a/packages/core/agent/src/dispatch.ts
+++ b/packages/core/agent/src/dispatch.ts
@@ -10,7 +10,7 @@ import type { Context, Events } from 'cordis'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { AssembleContext } from '@deepseek-ai/dsh-system-prompt'
-import type { Agent } from './types.ts'
+import type { Agent } from './runtime-types.ts'
 
 /** Extract the parameter tuple from an event handler type (its `this` is not part of the tuple). */
 type Params<F> = F extends (...args: infer P) => unknown ? P : never
diff --git a/packages/core/agent/src/inbox.ts b/packages/core/agent/src/inbox.ts
index d457277035..2db3c4b580 100644
--- a/packages/core/agent/src/inbox.ts
+++ b/packages/core/agent/src/inbox.ts
@@ -6,9 +6,7 @@
 
 import type { MessageId } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEventMap, UserMessage } from '@deepseek-ai/dsh-session'
-
-/** One of the two ordered pending-message lists owned by an agent. */
-export type InboxTarget = 'next-turn' | 'next-step'
+import type { InboxTarget } from './session-types.ts'
 
 /** Mutable state privately owned by an {@link Inbox}. */
 type InboxState = Record<InboxTarget, UserMessage[]>
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index bedfc819dc..e35bc06211 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -13,9 +13,10 @@ import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { TypeRTContext, TypeRTLookup } from '@deepseek-ai/dsh-type-meta'
-import type { Agent, AgentOptions } from './types.ts'
+import type { Agent, AgentOptions } from './runtime-types.ts'
 
-export * from './types.ts'
+export * from './runtime-types.ts'
+export * from './session-types.ts'
 export * from './inbox.ts'
 export * from './model-selection.ts'
 export { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from './dispatch.ts'
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/runtime-types.ts
similarity index 96%
rename from packages/core/agent/src/types.ts
rename to packages/core/agent/src/runtime-types.ts
index 8decb9ba3f..072f509f8f 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/runtime-types.ts
@@ -2,7 +2,7 @@
  * Public agent types and live-runtime events. Durable transcript facts and
  * turn/step boundaries remain `@deepseek-ai/dsh-session` events.
  *
- * @module @deepseek-ai/dsh-agent/types
+ * @module @deepseek-ai/dsh-agent
  */
 
 import type { Context } from 'cordis'
@@ -10,7 +10,8 @@ import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
 import type { AgentCancelCause, Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
 export type { AgentCancelCause } from '@deepseek-ai/dsh-session'
-import type { Inbox, InboxTarget } from './inbox.ts'
+import type { Inbox } from './inbox.ts'
+import type { InboxTarget } from './session-types.ts'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 declare module '@deepseek-ai/dsh-system-prompt' {
   interface AssembleContext {
@@ -289,20 +290,3 @@ declare module 'cordis' {
     'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
   }
 }
-
-declare module '@deepseek-ai/dsh-session/types' {
-  interface SessionEventMap {
-    /**
-     * One normalized mutation of an agent's durable pending-message lists.
-     * Live dispatch precedes projection mutation, so synchronous observers may
-     * read the pre-splice inbox to recover the removed messages.
-     */
-    'agent/inbox/spliced': {
-      target: InboxTarget
-      start: number
-      removedCount?: number
-      inserted: UserMessage[]
-      outcome?: 'canceled'
-    }
-  }
-}
diff --git a/packages/core/agent/src/session-types.ts b/packages/core/agent/src/session-types.ts
new file mode 100644
index 0000000000..b54e56ea8f
--- /dev/null
+++ b/packages/core/agent/src/session-types.ts
@@ -0,0 +1,27 @@
+/**
+ * Durable agent session-event vocabulary shared with type-only consumers.
+ *
+ * @module @deepseek-ai/dsh-agent/types
+ */
+
+import type { UserMessage } from '@deepseek-ai/dsh-llm/types'
+
+/** One of the two ordered pending-message lists owned by an agent. */
+export type InboxTarget = 'next-turn' | 'next-step'
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * One normalized mutation of an agent's durable pending-message lists.
+     * Live dispatch precedes projection mutation, so synchronous observers may
+     * read the pre-splice inbox to recover the removed messages.
+     */
+    'agent/inbox/spliced': {
+      target: InboxTarget
+      start: number
+      removedCount?: number
+      inserted: UserMessage[]
+      outcome?: 'canceled'
+    }
+  }
+}
diff --git a/packages/core/session/tests/gen-persistence-catalog.spec.ts b/packages/core/session/tests/gen-persistence-catalog.spec.ts
index 22bc09835f..4fee74793f 100644
--- a/packages/core/session/tests/gen-persistence-catalog.spec.ts
+++ b/packages/core/session/tests/gen-persistence-catalog.spec.ts
@@ -89,7 +89,7 @@ describe('gen-persistence-catalog collectLogEvents', () => {
   it('hard-errors on an extends clause (inherited keys would escape the catalog)', () => {
     expect(() => collectLogEvents(make({
       'packages/group/fix/src/types.ts':
-        'interface Extra { \'fix/hidden\': { turn: number } }\ndeclare module \'@deepseek-ai/dsh-session\' {\n  interface SessionEventMap extends Extra {\n    /** Declared directly. */\n    \'fix/direct\': { turn: number }\n  }\n}\n',
+        'interface Extra { \'fix/hidden\': { turn: number } }\ndeclare module \'@deepseek-ai/dsh-session/types\' {\n  interface SessionEventMap extends Extra {\n    /** Declared directly. */\n    \'fix/direct\': { turn: number }\n  }\n}\n',
     }))).toThrow(/uses extends; inherited keys would join keyof SessionEventMap without a catalog row/)
   })
 
diff --git a/packages/core/tools/package.json b/packages/core/tools/package.json
index 3279f17729..0fcc66b497 100644
--- a/packages/core/tools/package.json
+++ b/packages/core/tools/package.json
@@ -15,6 +15,10 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./presentation": {
       "types": "./lib/types/presentation.d.ts",
       "default": "./lib/types/presentation.js"
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index 984fecab88..f5c5809544 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -14,41 +14,7 @@ import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { defineTool, parameterSchemaSpecToJsonSchema } from './schema.ts'
 import { TOOL_REGISTRY_SCHEDULER } from './index.ts'
 import type { CodeDispatchLog, ToolDefinition, ToolExecutionResult, ToolRegistry, ToolRunContext } from './index.ts'
-
-declare module '@deepseek-ai/dsh-session/types' {
-  interface SessionEventMap {
-    /**
-     * One sub-dispatch STARTING inside a `run_code` program: the parent
-     * `run_code` call id, the deterministic sub-call id (`<parent>:code:<n>`,
-     * numbered in submission order), and the tool `name` with its
-     * JSON-normalized `arguments` — the exact value dispatched, normalized
-     * BEFORE dispatch, so this append can never fail on payload shape.
-     * Appended when the scheduler actually starts the call (not at
-     * submission), so a start means the tool body pipeline was entered; a
-     * call abandoned in the queue logs nothing. Log-only: `deriveMessages()`
-     * ignores it; UIs use it for live per-sub-call running state and pair it
-     * with `tool/code-dispatch` by `subCallId` (timing = the two events'
-     * `time` fields).
-     */
-    'tool/code-dispatch-start': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
-    /**
-     * One bridged sub-dispatch SETTLING: the pairing ids (matching the
-     * `tool/code-dispatch-start` with the same `subCallId`), the tool `name`
-     * with the same JSON-normalized `arguments`, and the sub-call's complete
-     * model-facing outcome in `tool/result`'s own vocabulary
-     * (`content` + `isError`), so UIs render a sub-call through the exact
-     * code path that renders a native call. Every started sub-call settles
-     * with exactly one of these (abort included: the aborted pipeline result
-     * is an `isError` outcome).
-     * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
-     * model context; persistence and UIs get every call. Appended inside the
-     * parent `run_code`'s execution (the bridge drains in-flight dispatches
-     * before returning), so its execution-enclosure relation holds by
-     * construction.
-     */
-    'tool/code-dispatch': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
-  }
-}
+import type {} from './types.ts'
 
 /** The model-facing name of the Code Mode tool. */
 export const RUN_CODE_NAME = 'run_code'
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 6338e54501..1a5f6a05eb 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -85,6 +85,7 @@ export {
 } from './json-schema.ts'
 
 export type { JsonValue } from '@deepseek-ai/dsh-session'
+export type { CodeDispatchEventData, CodeDispatchStartEventData } from './types.ts'
 
 export { CodeRunFailedError, RUN_CODE_NAME } from './code-mode.ts'
 export { jsonSchemaToTs, renderToolsSdk } from './ts-types.ts'
diff --git a/packages/core/tools/src/types.ts b/packages/core/tools/src/types.ts
new file mode 100644
index 0000000000..4dd6f7a9a8
--- /dev/null
+++ b/packages/core/tools/src/types.ts
@@ -0,0 +1,58 @@
+/**
+ * Durable Tool event vocabulary shared with type-only consumers.
+ *
+ * @module @deepseek-ai/dsh-tools/types
+ */
+
+import type { CallId } from '@deepseek-ai/dsh-llm/brand'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+
+/** Payload recorded when one nested Code Mode Tool dispatch starts. */
+export interface CodeDispatchStartEventData {
+  rootCallId: CallId
+  parentCallId: CallId
+  subCallId: CallId
+  name: string
+  arguments: unknown
+}
+
+/** Payload recorded when one nested Code Mode Tool dispatch settles. */
+export interface CodeDispatchEventData extends CodeDispatchStartEventData {
+  isError: boolean
+  content: ContentBlock[]
+}
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * One sub-dispatch STARTING inside a `run_code` program: the parent
+     * `run_code` call id, the deterministic sub-call id (`<parent>:code:<n>`,
+     * numbered in submission order), and the tool `name` with its
+     * JSON-normalized `arguments` — the exact value dispatched, normalized
+     * BEFORE dispatch, so this append can never fail on payload shape.
+     * Appended when the scheduler actually starts the call (not at
+     * submission), so a start means the tool body pipeline was entered; a
+     * call abandoned in the queue logs nothing. Log-only: `deriveMessages()`
+     * ignores it; UIs use it for live per-sub-call running state and pair it
+     * with `tool/code-dispatch` by `subCallId` (timing = the two events'
+     * `time` fields).
+     */
+    'tool/code-dispatch-start': CodeDispatchStartEventData
+    /**
+     * One bridged sub-dispatch SETTLING: the pairing ids (matching the
+     * `tool/code-dispatch-start` with the same `subCallId`), the tool `name`
+     * with the same JSON-normalized `arguments`, and the sub-call's complete
+     * model-facing outcome in `tool/result`'s own vocabulary
+     * (`content` + `isError`), so UIs render a sub-call through the exact
+     * code path that renders a native call. Every started sub-call settles
+     * with exactly one of these (abort included: the aborted pipeline result
+     * is an `isError` outcome).
+     * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
+     * model context; persistence and UIs get every call. Appended inside the
+     * parent `run_code`'s execution (the bridge drains in-flight dispatches
+     * before returning), so its execution-enclosure relation holds by
+     * construction.
+     */
+    'tool/code-dispatch': CodeDispatchEventData
+  }
+}
diff --git a/packages/interaction/commands/package.json b/packages/interaction/commands/package.json
index 7d35603a79..cd62942a5f 100644
--- a/packages/interaction/commands/package.json
+++ b/packages/interaction/commands/package.json
@@ -15,6 +15,10 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./brand": {
       "types": "./lib/types/brand.d.ts",
       "default": "./lib/types/brand.js"
diff --git a/packages/interaction/commands/src/index.ts b/packages/interaction/commands/src/index.ts
index ba7b449228..9f4110568e 100644
--- a/packages/interaction/commands/src/index.ts
+++ b/packages/interaction/commands/src/index.ts
@@ -11,24 +11,12 @@ import type { Session, SessionEvent, SessionEventMap } from '@deepseek-ai/dsh-se
 import { CommandId } from './brand.ts'
 
 export { CommandId } from './brand.ts'
+export type { CommandSource, CommandSourceMap } from './types.ts'
 
 export const name = 'commands'
 
 const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/u
 
-/**
- * Producer record for one command invocation (the `command/run` event's
- * source slot). Merge-extensible sum type mirroring `MessageSourceMap`'s
- * shape; minimal today because every executor caller is a human-facing UI
- * surface dispatching a human-typed line, so the sole variant is `user`.
- */
-export interface CommandSourceMap {
-  user: { kind: 'user' }
-}
-
-/** The union over {@link CommandSourceMap} — who issued a command line. */
-export type CommandSource = CommandSourceMap[keyof CommandSourceMap]
-
 /** Immutable metadata for a command's optional unstructured input. */
 export interface CommandInputDescriptor {
   /** Placeholder shown before the user supplies free-form input. */
@@ -131,34 +119,6 @@ class CommandLayer implements ScopeLayer {
   }
 }
 
-declare module '@deepseek-ai/dsh-session/types' {
-  interface SessionEventMap {
-    /**
-     * A resolved slash command entered its handler. Log-only (never model
-     * surface); paired with `command/done` by `commandId`, mirroring the
-     * `tool/call`↔`tool/result` pairing. The payload is structured — `name`
-     * and `args` are `parseCommand`'s own split (name and verbatim rawInput,
-     * separator whitespace included), so a consumer (a projection unit
-     * folding its own command records, a rich command card) never re-parses
-     * a line. `args` is absent when the definition sets `recordInput: false`
-     * because an authoritative domain event owns the input payload.
-     */
-    'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
-    /**
-     * The paired command settled. `kind`/`text` carry the handler's verbatim
-     * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
-     * rendered failure). A successful command may identify the earlier
-     * authoritative domain event for a richer client-computed presentation.
-     */
-    'command/done': {
-      commandId: CommandId
-      kind: 'success' | 'error'
-      text?: string
-      sourceEventSeq?: number
-    }
-  }
-}
-
 declare module 'cordis' {
   interface Context {
     commands: CommandService
diff --git a/packages/interaction/commands/src/types.ts b/packages/interaction/commands/src/types.ts
new file mode 100644
index 0000000000..2b81071d37
--- /dev/null
+++ b/packages/interaction/commands/src/types.ts
@@ -0,0 +1,48 @@
+/**
+ * Durable command event vocabulary shared with type-only consumers.
+ *
+ * @module @deepseek-ai/dsh-commands/types
+ */
+
+import type { CommandId } from './brand.ts'
+
+/**
+ * Producer record for one command invocation (the `command/run` event's
+ * source slot). Merge-extensible sum type mirroring `MessageSourceMap`'s
+ * shape; minimal today because every executor caller is a human-facing UI
+ * surface dispatching a human-typed line, so the sole variant is `user`.
+ */
+export interface CommandSourceMap {
+  user: { kind: 'user' }
+}
+
+/** The union over {@link CommandSourceMap} — who issued a command line. */
+export type CommandSource = CommandSourceMap[keyof CommandSourceMap]
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * A resolved slash command entered its handler. Log-only (never model
+     * surface); paired with `command/done` by `commandId`, mirroring the
+     * `tool/call`↔`tool/result` pairing. The payload is structured — `name`
+     * and `args` are `parseCommand`'s own split (name and verbatim rawInput,
+     * separator whitespace included), so a consumer (a projection unit
+     * folding its own command records, a rich command card) never re-parses
+     * a line. `args` is absent when the definition sets `recordInput: false`
+     * because an authoritative domain event owns the input payload.
+     */
+    'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
+    /**
+     * The paired command settled. `kind`/`text` carry the handler's verbatim
+     * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
+     * rendered failure). A successful command may identify the earlier
+     * authoritative domain event for a richer client-computed presentation.
+     */
+    'command/done': {
+      commandId: CommandId
+      kind: 'success' | 'error'
+      text?: string
+      sourceEventSeq?: number
+    }
+  }
+}
diff --git a/packages/llm/llm-retry/package.json b/packages/llm/llm-retry/package.json
index 1685d0e552..809b5d14e5 100644
--- a/packages/llm/llm-retry/package.json
+++ b/packages/llm/llm-retry/package.json
@@ -19,10 +19,6 @@
       "types": "./lib/types/types.d.ts",
       "default": "./lib/types/types.js"
     },
-    "./brand": {
-      "types": "./lib/types/brand.d.ts",
-      "default": "./lib/types/brand.js"
-    },
     "./package.json": "./package.json"
   },
   "files": [
diff --git a/packages/llm/llm-retry/src/types.ts b/packages/llm/llm-retry/src/types.ts
index c698b68446..5144939289 100644
--- a/packages/llm/llm-retry/src/types.ts
+++ b/packages/llm/llm-retry/src/types.ts
@@ -1,5 +1,7 @@
 import type { LlmFailure } from '@deepseek-ai/dsh-llm/types'
-import type { RetryId } from './brand.ts'
+import { RetryId } from './brand.ts'
+
+export { RetryId }
 
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
diff --git a/packages/llm/llm-retry/tests/invariant.spec.ts b/packages/llm/llm-retry/tests/invariant.spec.ts
index 33ac3a19fa..917a6d03f8 100644
--- a/packages/llm/llm-retry/tests/invariant.spec.ts
+++ b/packages/llm/llm-retry/tests/invariant.spec.ts
@@ -5,7 +5,7 @@ import { createUserMessage, ProviderRequestId } from '@deepseek-ai/dsh-llm'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as RetryInvariant from '@deepseek-ai/dsh-llm-retry/invariant'
-import { RetryId } from '@deepseek-ai/dsh-llm-retry/brand'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry/types'
 import { providerForOpenStep } from '../src/history.ts'
 
 async function setup(): Promise<Context> {
diff --git a/packages/llm/llm-retry/tests/persistence.spec.ts b/packages/llm/llm-retry/tests/persistence.spec.ts
index 3a605bd40e..9e17290b43 100644
--- a/packages/llm/llm-retry/tests/persistence.spec.ts
+++ b/packages/llm/llm-retry/tests/persistence.spec.ts
@@ -6,7 +6,7 @@ import { Context } from 'cordis'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SessionPersistenceSqlite from '@deepseek-ai/dsh-session-persistence-sqlite'
-import { RetryId } from '@deepseek-ai/dsh-llm-retry/brand'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry/types'
 import type {} from '../src/index.ts'
 
 const dirs: string[] = []
diff --git a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
index 9251eef2c0..bfbf6a89ee 100644
--- a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
+++ b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
@@ -10,7 +10,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextBreakdownProjection } from '@deepseek-ai/dsh-token-meter/client'
-import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
+import { CompactionId } from '@deepseek-ai/dsh-compact/types'
 import { contextBreakdownProjectionDefinition } from '../src/breakdown-projection.ts'
 import {
   estimateContent,
diff --git a/packages/llm/token-meter/tests/token-usage-projection.spec.ts b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
index 65771fc877..3f66e0564b 100644
--- a/packages/llm/token-meter/tests/token-usage-projection.spec.ts
+++ b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
@@ -7,7 +7,7 @@ import type { Session } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
-import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
+import { CompactionId } from '@deepseek-ai/dsh-compact/types'
 
 const ZERO: TokenUsageProjection = {
   uncachedInputTokens: 0,
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index 0276199e3e..db60b695b1 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -4,7 +4,7 @@ import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { CompactionId } from '@deepseek-ai/dsh-compact/brand'
+import { CompactionId } from '@deepseek-ai/dsh-compact/types'
 import LlmService, { CallId, createUserMessage, GenerateOptions, LlmAdapter, StreamChunk } from '@deepseek-ai/dsh-llm'
 import {
   type ReplayEntry,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f1ee272761..6fb20b9718 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1495,6 +1495,9 @@ importers:
 
   packages/client/runtime:
     dependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
       '@deepseek-ai/dsh-client-connection':
         specifier: workspace:^
         version: link:../connection
@@ -1522,6 +1525,9 @@ importers:
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
         version: link:../../session/session-title
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
       immer:
         specifier: ^10.1.1
         version: 10.2.0
@@ -1656,6 +1662,9 @@ importers:
         specifier: ^2.0.0
         version: 2.1.1
     devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
       '@deepseek-ai/dsh-client-locale':
         specifier: workspace:^
         version: link:../locale
@@ -1677,6 +1686,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-commands':
+        specifier: workspace:^
+        version: link:../../interaction/commands
       '@deepseek-ai/dsh-compact':
         specifier: workspace:^
         version: link:../../compact/compact
@@ -1686,6 +1698,9 @@ importers:
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm-retry':
+        specifier: workspace:^
+        version: link:../../llm/llm-retry
       '@deepseek-ai/dsh-permission':
         specifier: workspace:^
         version: link:../../interaction/permission
@@ -1701,6 +1716,9 @@ importers:
       '@deepseek-ai/dsh-tool-todo':
         specifier: workspace:^
         version: link:../../todo/tool-todo
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
       '@types/react':
         specifier: ~18.3.1
         version: 18.3.31
diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts
index 5294242e27..173d4222cb 100644
--- a/scripts/gen-persistence-catalog.ts
+++ b/scripts/gen-persistence-catalog.ts
@@ -18,8 +18,11 @@ const OUT = 'docs/persistence-catalog.md'
  * doc-typecheck, since their imported types are not standalone-compilable). */
 const FENCE = 'ts persistence-catalog'
 
-/** The package whose module id plugin merges augment (`declare module '…'`). */
-const SESSION_MODULE = '@deepseek-ai/dsh-session'
+/** The package that owns the durable event vocabulary. */
+const SESSION_PACKAGE = '@deepseek-ai/dsh-session'
+
+/** The type-only module that plugin declaration merges augment. */
+const SESSION_TYPES_MODULE = '@deepseek-ai/dsh-session/types'
 
 /** Event-envelope declarations rendered before the per-event vocabulary. */
 const EVENT_ENVELOPE_TYPE_NAMES = [
@@ -115,7 +118,7 @@ function declarationText(text: string, sf: ts.SourceFile, node: ts.Node): string
 /**
  * Every `interface SessionEventMap` declaration in a source file: the owning
  * top-level declaration (in `@deepseek-ai/dsh-session`) and any declaration
- * merge inside a `declare module '@deepseek-ai/dsh-session'` block. Both forms
+ * merge inside a `declare module '@deepseek-ai/dsh-session/types'` block. Both forms
  * declare members of the SAME merged interface, so both are catalogued
  * uniformly. `topLevel` distinguishes the owning form so the caller can verify
  * it actually lives in the owning package — an unrelated local interface that
@@ -125,7 +128,7 @@ function sessionEventMapDecls(sf: ts.SourceFile): { decl: ts.InterfaceDeclaratio
   const decls: { decl: ts.InterfaceDeclaration; topLevel: boolean }[] = []
   for (const stmt of sf.statements) {
     if (ts.isInterfaceDeclaration(stmt) && stmt.name.text === 'SessionEventMap') decls.push({ decl: stmt, topLevel: true })
-    if (ts.isModuleDeclaration(stmt) && ts.isStringLiteral(stmt.name) && stmt.name.text === SESSION_MODULE
+    if (ts.isModuleDeclaration(stmt) && ts.isStringLiteral(stmt.name) && stmt.name.text === SESSION_TYPES_MODULE
       && stmt.body && ts.isModuleBlock(stmt.body)) {
       for (const inner of stmt.body.statements) {
         if (ts.isInterfaceDeclaration(inner) && inner.name.text === 'SessionEventMap') decls.push({ decl: inner, topLevel: false })
@@ -174,8 +177,8 @@ export function collectLogEvents(scanRoot: string = root): LogEventEntry[] {
         // the owning package. Same-named interfaces elsewhere are different
         // types and must not enter the on-disk catalog.
         const pkg = packageNameFor(rel, scanRoot)
-        if (pkg !== SESSION_MODULE) {
-          violations.push(`top-level interface SessionEventMap (${declSrc}) is outside ${SESSION_MODULE} (package ${pkg ?? 'unknown'}). Rename the interface, or contribute events via declare module '${SESSION_MODULE}'.`)
+        if (pkg !== SESSION_PACKAGE) {
+          violations.push(`top-level interface SessionEventMap (${declSrc}) is outside ${SESSION_PACKAGE} (package ${pkg ?? 'unknown'}). Rename the interface, or contribute events via declare module '${SESSION_TYPES_MODULE}'.`)
           continue
         }
         const exported = decl.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false
@@ -243,7 +246,7 @@ export function collectEventEnvelopeTypes(scanRoot: string = root): EventEnvelop
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
     if (!EVENT_ENVELOPE_TYPE_NAMES.some(name => text.includes(name))) continue
-    if (packageNameFor(rel, scanRoot) !== SESSION_MODULE) continue
+    if (packageNameFor(rel, scanRoot) !== SESSION_PACKAGE) continue
     const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
     for (const stmt of sf.statements) {
       if (!ts.isTypeAliasDeclaration(stmt) || !wanted.has(stmt.name.text)) continue
@@ -352,7 +355,7 @@ export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnv
     '',
     '# Session Persistence Event Catalog',
     '',
-    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
+    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge into `@deepseek-ai/dsh-session/types` in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
     '',
     'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).',
     '',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index cd9d020779..73431101da 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -114,12 +114,12 @@
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "InboxTarget",
-      "source": "packages/core/agent/src/inbox.ts"
+      "source": "packages/core/agent/src/session-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "CancelOptions",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
@@ -129,22 +129,22 @@
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "Agent",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "PreStepDecision",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "RequestErrorAction",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "SessionStartSource",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/scope.md",
@@ -1698,12 +1698,12 @@
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "AgentStatus",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "AgentOptions",
-      "source": "packages/core/agent/src/types.ts"
+      "source": "packages/core/agent/src/runtime-types.ts"
     }
   ]
 }
diff --git a/tsconfig.base.json b/tsconfig.base.json
index d8b777a2ad..c7be2d4925 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -71,8 +71,11 @@
       "@deepseek-ai/dsh-llm-retry/types": ["./packages/llm/llm-retry/src/types.ts"],
       "@deepseek-ai/dsh-llm/message": ["./packages/llm/llm/src/message.ts"],
       "@deepseek-ai/dsh-commands/brand": ["./packages/interaction/commands/src/brand.ts"],
+      "@deepseek-ai/dsh-commands/types": ["./packages/interaction/commands/src/types.ts"],
       "@deepseek-ai/dsh-compact/checkpoint": ["./packages/compact/compact/src/checkpoint.ts"],
+      "@deepseek-ai/dsh-compact/types": ["./packages/compact/compact/src/types.ts"],
       "@deepseek-ai/dsh-tools/presentation": ["./packages/core/tools/src/presentation.ts"],
+      "@deepseek-ai/dsh-tools/types": ["./packages/core/tools/src/types.ts"],
       "@deepseek-ai/dsh-tool-subagent-control/list-agents": ["./packages/subagent/tool-subagent-control/src/list-agents.ts"],
       "@deepseek-ai/dsh-user-approval/types": ["./packages/interaction/user-approval/src/types.ts"],
       "@deepseek-ai/dsh-user-interaction/types": ["./packages/interaction/user-interaction/src/types.ts"],

From 1b1e170c1f291b53af8fa5ac1257530a7e59f8fd Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:43:37 +0800
Subject: [PATCH 493/516] refactor(agent): restore conventional types
 entrypoint

---
 packages/core/agent/package.json                       | 4 ++--
 packages/core/agent/src/inbox.ts                       | 2 +-
 packages/core/agent/src/index.ts                       | 2 +-
 packages/core/agent/src/runtime-types.ts               | 2 +-
 packages/core/agent/src/{session-types.ts => types.ts} | 0
 scripts/type-equiv.manifest.json                       | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)
 rename packages/core/agent/src/{session-types.ts => types.ts} (100%)

diff --git a/packages/core/agent/package.json b/packages/core/agent/package.json
index d186f32d03..9f64d33e75 100644
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -16,8 +16,8 @@
       "default": "./lib/invariant.js"
     },
     "./types": {
-      "types": "./lib/types/session-types.d.ts",
-      "default": "./lib/types/session-types.js"
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
     },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
diff --git a/packages/core/agent/src/inbox.ts b/packages/core/agent/src/inbox.ts
index 2db3c4b580..c6b9204c92 100644
--- a/packages/core/agent/src/inbox.ts
+++ b/packages/core/agent/src/inbox.ts
@@ -6,7 +6,7 @@
 
 import type { MessageId } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEventMap, UserMessage } from '@deepseek-ai/dsh-session'
-import type { InboxTarget } from './session-types.ts'
+import type { InboxTarget } from './types.ts'
 
 /** Mutable state privately owned by an {@link Inbox}. */
 type InboxState = Record<InboxTarget, UserMessage[]>
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index e35bc06211..4df0056c1a 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -16,7 +16,7 @@ import type { TypeRTContext, TypeRTLookup } from '@deepseek-ai/dsh-type-meta'
 import type { Agent, AgentOptions } from './runtime-types.ts'
 
 export * from './runtime-types.ts'
-export * from './session-types.ts'
+export * from './types.ts'
 export * from './inbox.ts'
 export * from './model-selection.ts'
 export { agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from './dispatch.ts'
diff --git a/packages/core/agent/src/runtime-types.ts b/packages/core/agent/src/runtime-types.ts
index 072f509f8f..3698c05018 100644
--- a/packages/core/agent/src/runtime-types.ts
+++ b/packages/core/agent/src/runtime-types.ts
@@ -11,7 +11,7 @@ import type { LlmCallConfig, LlmFailure, ResolvedRetryPolicy } from '@deepseek-a
 import type { AgentCancelCause, Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
 export type { AgentCancelCause } from '@deepseek-ai/dsh-session'
 import type { Inbox } from './inbox.ts'
-import type { InboxTarget } from './session-types.ts'
+import type { InboxTarget } from './types.ts'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 declare module '@deepseek-ai/dsh-system-prompt' {
   interface AssembleContext {
diff --git a/packages/core/agent/src/session-types.ts b/packages/core/agent/src/types.ts
similarity index 100%
rename from packages/core/agent/src/session-types.ts
rename to packages/core/agent/src/types.ts
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 73431101da..fccabef852 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -114,7 +114,7 @@
     {
       "doc": "docs/subsystems/core.md",
       "symbol": "InboxTarget",
-      "source": "packages/core/agent/src/session-types.ts"
+      "source": "packages/core/agent/src/types.ts"
     },
     {
       "doc": "docs/subsystems/core.md",

From 924cfcef9595e101ec090d1f118c8f557e11469d Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:56:29 +0800
Subject: [PATCH 494/516] fix: coverage

---
 .../src/client/contract/conversation.ts        |  4 ++++
 .../client/sessions/conversation-assembler.ts  |  5 ++---
 .../sessions/conversation-location-index.ts    |  2 +-
 .../client/test-runtime/tests/runtime.spec.tsx |  3 ++-
 .../src/client/contract/chat-nodes.ts          |  2 +-
 .../src/client/contract/slots.ts               |  2 +-
 .../tests/chat-snapshot-fixture.ts             |  7 +++++--
 .../ui-conversation/tests/chat-view.spec.tsx   | 18 ++++++++++--------
 .../tests/produced-files.spec.tsx              |  7 +++++--
 .../client/ui-settings/tests/apply.spec.ts     | 12 ++++++------
 packages/client/ui-slots/src/index.ts          | 10 ++++++++--
 packages/typert/generator/src/analyzer.ts      |  2 +-
 12 files changed, 46 insertions(+), 28 deletions(-)

diff --git a/packages/client/runtime/src/client/contract/conversation.ts b/packages/client/runtime/src/client/contract/conversation.ts
index fb98965d25..9507046b33 100644
--- a/packages/client/runtime/src/client/contract/conversation.ts
+++ b/packages/client/runtime/src/client/contract/conversation.ts
@@ -1,6 +1,10 @@
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type { ToolEventView } from '@deepseek-ai/dsh-client-connection/client'
 
+/* oxlint-disable typescript/no-duplicate-type-constituents, typescript/no-redundant-type-constituents --
+ * The unaugmented declaration-merge maps intentionally resolve to never in the Runtime program;
+ * installed business packages supply their concrete keys in consuming Client programs. */
+
 /** One raw log event plus its optional envelope-level presentation view. */
 export interface ConversationEventInput {
   readonly event: SessionEvent
diff --git a/packages/client/runtime/src/client/sessions/conversation-assembler.ts b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
index 811bd43ebf..bdd89f56a4 100644
--- a/packages/client/runtime/src/client/sessions/conversation-assembler.ts
+++ b/packages/client/runtime/src/client/sessions/conversation-assembler.ts
@@ -712,9 +712,8 @@ export class ConversationNodeAssembler {
     context: InternalContext,
     scope: ConversationLocationDataScope,
   ): ConversationLocationData | null {
-    const build = context.definition.buildLocationData
-    if (build === undefined) return null
-    const data = build(contextSnapshot(context), scope)
+    if (context.definition.buildLocationData === undefined) return null
+    const data = context.definition.buildLocationData(contextSnapshot(context), scope)
     if (data === null) return null
     if (data.kind !== scope) {
       throw new Error(
diff --git a/packages/client/runtime/src/client/sessions/conversation-location-index.ts b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
index c842a230a9..f4ce189b13 100644
--- a/packages/client/runtime/src/client/sessions/conversation-location-index.ts
+++ b/packages/client/runtime/src/client/sessions/conversation-location-index.ts
@@ -20,7 +20,7 @@ export interface ConversationLocationDataChange {
 class MutableLocationDataStore {
   private entries = new Map<string, OwnedLocationData>()
 
-  get<Key extends string>(key: Key): unknown {
+  get(key: string): unknown {
     return this.entries.get(key)?.value
   }
 
diff --git a/packages/client/test-runtime/tests/runtime.spec.tsx b/packages/client/test-runtime/tests/runtime.spec.tsx
index f92d21b4b5..08a82ee251 100644
--- a/packages/client/test-runtime/tests/runtime.spec.tsx
+++ b/packages/client/test-runtime/tests/runtime.spec.tsx
@@ -18,6 +18,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     'trt.panel': { kind: 'single'; scope: 'root'; owner: { label?: string } }
     'trt.chat': { kind: 'single'; scope: 'session' }
     'trt.rows': { kind: 'list'; scope: 'root' }
+    'trt.rows.hole': { kind: 'single'; scope: 'root' }
   }
 }
 
@@ -419,7 +420,7 @@ describe('feature mount and disposal', () => {
     await feature.dispose()
     await feature.dispose() // idempotent
     expect(runtime.slots.entries('trt.rows')).toHaveLength(0)
-    expect(runtime.slots.spec('trt.rows.hole' as never)).toBeUndefined()
+    expect(runtime.slots.spec('trt.rows.hole')).toBeUndefined()
     expect(runtime.ctx.get('feature-service')).toBeUndefined()
     expect(view.queryByTestId('row')).toBeNull()
     await runtime.dispose()
diff --git a/packages/client/ui-conversation/src/client/contract/chat-nodes.ts b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
index 3415c502a5..787f391006 100644
--- a/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
+++ b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
@@ -7,7 +7,7 @@ import type {
 export interface ChatNodeDataMap {}
 
 /** Renderer kinds contributed by the currently installed Chat business modules. */
-export type ChatNodeKind = keyof ChatNodeDataMap & string
+export type ChatNodeKind = Extract<keyof ChatNodeDataMap, string>
 
 /** Final Chat Node narrowed to one registered renderer kind and payload. */
 export type ChatNode<Kind extends ChatNodeKind = ChatNodeKind> = {
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index eec5450e2d..56fca2381c 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -210,7 +210,7 @@ export interface TurnTailOwnerProps {
 }
 
 /** Hook constrained to business data published on the current Chat Node's Turn. */
-export type UseChatNodeTurnData = <Key extends keyof ConversationTurnDataMap & string>(
+export type UseChatNodeTurnData = <Key extends Extract<keyof ConversationTurnDataMap, string>>(
   key: Key,
 ) => Readonly<ConversationTurnDataMap[Key]> | undefined
 
diff --git a/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts b/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
index c675554ea0..fb343f0f68 100644
--- a/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
+++ b/packages/client/ui-conversation/tests/chat-snapshot-fixture.ts
@@ -78,13 +78,16 @@ class FixtureLocationIndex implements ChatLocationNodeIndex {
 class FixtureTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
   private readonly values = new Map<string, unknown>()
 
-  get<Key extends keyof ConversationTurnDataMap & string>(
+  get<Key extends Extract<keyof ConversationTurnDataMap, string>>(
     key: Key,
   ): Readonly<ConversationTurnDataMap[Key]> | undefined {
     return this.values.get(key) as Readonly<ConversationTurnDataMap[Key]> | undefined
   }
 
-  set<Key extends keyof ConversationTurnDataMap & string>(key: Key, value: ConversationTurnDataMap[Key]): void {
+  set<Key extends Extract<keyof ConversationTurnDataMap, string>>(
+    key: Key,
+    value: ConversationTurnDataMap[Key],
+  ): void {
     this.values.set(key, value)
   }
 }
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index 296dd85966..ca6223826e 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -181,12 +181,14 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     if (key !== 'conversation.chat.node') return opts?.fallback ?? null
     const nodeOwner = owner as RoutedChatNodeOwner
     const nodeKey = opts?.hookContext as string | undefined
-    const useTurnData = ((dataKey: string) => props.useSession((snapshot) => {
-      const location = nodeKey === undefined ? undefined : snapshot.chat.nodes.get(nodeKey)?.location
-      return location?.kind === 'turn' || location?.kind === 'step'
-        ? location.turn.data.get(dataKey as never)
-        : undefined
-    })) as UseChatNodeTurnData
+    const useTurnData = ((dataKey: string) => {
+      return props.useSession((snapshot) => {
+        const location = nodeKey === undefined ? undefined : snapshot.chat.nodes.get(nodeKey)?.location
+        return location?.kind === 'turn' || location?.kind === 'step'
+          ? location.turn.data.get(dataKey as never)
+          : undefined
+      })
+    }) as UseChatNodeTurnData
     const nodeProps = <Kind extends ChatNode['kind']>(): ChatNodeViewProps<Kind> => (
       { ...props, ...nodeOwner, useTurnData } as unknown as ChatNodeViewProps<Kind>
     )
@@ -226,7 +228,7 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
       case 'unknown':
         return <UnknownNodeView {...nodeProps<'unknown'>()} />
       case 'tool-call': {
-        const block = (nodeOwner.node.data as { readonly root: ToolCallBlock }).root
+        const block = nodeOwner.node.data.root
         const toolName = 'kind' in block ? block.call?.name ?? '' : block.name
         const tool = {
           callId: block.callId,
@@ -843,7 +845,7 @@ describe('ChatView', () => {
         mounted()
         return () => { unmounted() }
       }, [])
-      const root = (node.data as { readonly root: ToolCallBlock }).root
+      const root = node.data.root
       return (
         <div data-testid="stateful-tool" data-state={'kind' in root ? 'settled' : 'running'}>
           {root.callId}
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index b7ca73a79f..b8e7cd111e 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -34,13 +34,16 @@ afterEach(cleanup)
 class TestTurnDataStore implements ConversationLocationDataStore<ConversationTurnDataMap> {
   private readonly values = new Map<string, unknown>()
 
-  get<Key extends keyof ConversationTurnDataMap & string>(
+  get<Key extends Extract<keyof ConversationTurnDataMap, string>>(
     key: Key,
   ): Readonly<ConversationTurnDataMap[Key]> | undefined {
     return this.values.get(key) as Readonly<ConversationTurnDataMap[Key]> | undefined
   }
 
-  set<Key extends keyof ConversationTurnDataMap & string>(key: Key, value: ConversationTurnDataMap[Key]): void {
+  set<Key extends Extract<keyof ConversationTurnDataMap, string>>(
+    key: Key,
+    value: ConversationTurnDataMap[Key],
+  ): void {
     this.values.set(key, value)
   }
 }
diff --git a/packages/client/ui-settings/tests/apply.spec.ts b/packages/client/ui-settings/tests/apply.spec.ts
index c46a5bf25c..3133ad4d76 100644
--- a/packages/client/ui-settings/tests/apply.spec.ts
+++ b/packages/client/ui-settings/tests/apply.spec.ts
@@ -44,8 +44,8 @@ describe('ui-settings apply', () => {
     declare(before.slots)
     await before.ctx.plugin({ inject: [...inject], apply }).await()
     expect(before.slots.entries('sidebar.settings')[0]!.component).toBe(SettingsRoot)
-    for (const [name, spec] of Object.entries(CHILD_SPECS)) {
-      expect(before.slots.spec(name as never)).toEqual(spec)
+    for (const name of Object.keys(CHILD_SPECS) as Array<keyof typeof CHILD_SPECS>) {
+      expect(before.slots.spec(name)).toEqual(CHILD_SPECS[name])
     }
 
     const after = await bench()
@@ -120,8 +120,8 @@ describe('ui-settings apply', () => {
     declare(b.slots)
     await Promise.resolve()
     expect(b.slots.entries('sidebar.settings')[0]!.component).toBe(SettingsRoot)
-    for (const [name, spec] of Object.entries(CHILD_SPECS)) {
-      expect(b.slots.spec(name as never)).toEqual(spec)
+    for (const name of Object.keys(CHILD_SPECS) as Array<keyof typeof CHILD_SPECS>) {
+      expect(b.slots.spec(name)).toEqual(CHILD_SPECS[name])
     }
   })
 
@@ -132,8 +132,8 @@ describe('ui-settings apply', () => {
     await fiber.await()
     await fiber.dispose()
     expect(b.slots.entries('sidebar.settings')).toHaveLength(0)
-    for (const name of Object.keys(CHILD_SPECS)) {
-      expect(b.slots.spec(name as never)).toBeUndefined()
+    for (const name of Object.keys(CHILD_SPECS) as Array<keyof typeof CHILD_SPECS>) {
+      expect(b.slots.spec(name)).toBeUndefined()
     }
   })
 })
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index 4ed6ecf519..d6c1824c99 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -677,7 +677,10 @@ export class SlotCore {
   >(
     options: BaseOptions<K, EntryKey, D, H, M, N> & { inject?: undefined },
     component: C
-      & SlotComponent<ComposedProps<K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, object, NoInfer<M>, NoInfer<N>>>
+      & SlotComponent<ComposedProps<
+        K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string,
+        HandleOf<NoInfer<H>>, object, NoInfer<M>, NoInfer<N>
+      >>
       & RendersCheck<C, D>,
   ): () => void
   /**
@@ -702,7 +705,10 @@ export class SlotCore {
   >(
     options: BaseOptions<K, EntryKey, D, H, M, N> & { inject: (...args: InjectParams<K, H>) => I },
     component: C
-      & SlotComponent<ComposedProps<K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string, HandleOf<NoInfer<H>>, I, NoInfer<M>, NoInfer<N>>>
+      & SlotComponent<ComposedProps<
+        K, NoInfer<EntryKey>, keyof NoInfer<D> & keyof SlotMap & string,
+        HandleOf<NoInfer<H>>, I, NoInfer<M>, NoInfer<N>
+      >>
       & RendersCheck<C, D>,
   ): () => void
   /* jscpd:ignore-end */
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index 6f495aa318..68736f0b3a 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -274,7 +274,7 @@ export class WorkspaceAnalyzer {
 
   constructor(options: WorkspaceAnalyzerOptions) {
     this.options = {
-      root: resolve(options.root),
+      root: realPath(options.root),
       hostConfig: options.hostConfig ?? 'tsconfig.host.json',
       clientConfig: options.clientConfig ?? 'tsconfig.client.json',
       faces: options.faces ?? ['host', 'client'],

From 27682b938493cfe9e4580a568f006d561d1302de Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 18:56:34 +0800
Subject: [PATCH 495/516] fix: docs

---
 ...lient-conversation-node-assembly.i18n.yaml |  4 +-
 docs/config-catalog.i18n.yaml                 |  2 +-
 docs/config-catalog.md                        |  4 +-
 docs/event-producer-consumer.i18n.yaml        |  2 +-
 docs/event-producer-consumer.md               | 38 +++++++++----------
 docs/module-graph.i18n.yaml                   |  2 +-
 docs/module-graph.md                          |  6 ++-
 docs/persistence-catalog.i18n.yaml            |  2 +-
 docs/persistence-catalog.md                   | 32 +++++++---------
 docs/subsystems/commands.i18n.yaml            |  4 +-
 docs/subsystems/commands.md                   |  4 +-
 docs/subsystems/commands.zh.md                |  4 +-
 docs/subsystems/core.i18n.yaml                |  4 +-
 docs/subsystems/core.md                       | 26 ++++++-------
 docs/subsystems/core.zh.md                    | 26 ++++++-------
 docs/subsystems/tools.i18n.yaml               |  4 +-
 docs/subsystems/tools.md                      | 14 +++----
 docs/subsystems/tools.zh.md                   | 14 +++----
 18 files changed, 96 insertions(+), 96 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index 264b900b74..d19cd86c7d 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: f9768a652c7b0d2d29939fac83b201bc904e3210
-2026-08-09-client-conversation-node-assembly.zh.md: 408d61f73b3b317214cb10b26f522e7680de3f92
+2026-08-09-client-conversation-node-assembly.md: 9952f8fac0f2a3b0fe72cc97ae9a8fb4f96ace08
+2026-08-09-client-conversation-node-assembly.zh.md: f27a82459cdacdb4a2da27cf12b30c93f2dfdf64
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 9607dc8d1a..12f3e2861c 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: 5f3bc744b25bf20d50e88ce75812fe8bd624905a
+config-catalog.md: 7278447cf85c2b25f7dd42e10e4b0b1cbd7eb96b
 config-catalog.zh.md: a7d4252c526d36643a1b9f7aebd627faa60e1c77
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 22e21edc0b..7278447cf8 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -917,7 +917,7 @@ Requires: `agents`
 export type Config = Readonly<Record<string, never>>
 ```
 
-Source: [`packages/llm/llm-retry/src/index.ts:33`](../packages/llm/llm-retry/src/index.ts)
+Source: [`packages/llm/llm-retry/src/index.ts:24`](../packages/llm/llm-retry/src/index.ts)
 
 ## `@deepseek-ai/dsh-lsp-local`
 
@@ -2325,7 +2325,7 @@ export interface Config {
 export type ToolPresentationMode = 'native' | 'code' | 'both'
 ```
 
-Source: [`packages/core/tools/src/index.ts:623`](../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:624`](../packages/core/tools/src/index.ts)
 
 ## `@deepseek-ai/dsh-typert-loader`
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 41da1ee118..812b490bef 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: 5b36725402c0a12c5e2a09c743c2e7cf28d2c14a
+event-producer-consumer.md: 05ff62a391a0acb7db9abd2c9ce0c2082da52eaa
 event-producer-consumer.zh.md: 2d4c805f9a5d3b0531ee59eebe9e6564347f0a00
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index a8263b70c1..05ff62a391 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -8,20 +8,20 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
 | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
-| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:185`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
-| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
-| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:159`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:168`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:290`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
+| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:197`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/runtime-types.ts:205`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/runtime-types.ts:186`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:231`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:244`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
+| `agent/request-error` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:260`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:217`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:178`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
+| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:174`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:134`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
@@ -44,12 +44,12 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
-| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
-| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:173`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
-| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
-| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:160`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
-| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:137`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
-| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
+| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:192`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
+| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:174`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
+| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:149`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:161`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:138`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
+| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:182`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
 | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:81`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
 | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
 | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:91`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index d6f09d6696..24ddaad77c 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.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 docs/module-graph.md
-module-graph.md: e7d6b47e709c3edf4dcdb506bd8f2be0c717aaab
+module-graph.md: a248ed4fcb8abc17ffc6982d2733b3c3c2a2a635
 module-graph.zh.md: 255253bcfa9cfad1ab85602dfa9f953a02dfc427
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 767ebfcfde..a248ed4fcb 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -1000,14 +1000,18 @@ flowchart TD
   pkg_web_app --> pkg_bash_env
   pkg_web_app --> pkg_invariants
   pkg_web_app --> pkg_system_prompt
+  pkg_client_ui_conversation --> pkg_agent
   pkg_client_ui_conversation --> pkg_client_locale
   pkg_client_ui_conversation --> pkg_client_runtime
   pkg_client_ui_conversation --> pkg_client_ui_primitives
   pkg_client_ui_conversation --> pkg_client_ui_slash
   pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_commands
   pkg_client_ui_conversation --> pkg_compact
   pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_llm_retry
   pkg_client_ui_conversation --> pkg_token_meter
+  pkg_client_ui_conversation --> pkg_tools
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1354,7 +1358,7 @@ flowchart TD
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
-| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`agent`](../packages/core/agent), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm-retry`](../packages/llm/llm-retry), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
 | [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`repository-plugin`](../packages/self-modification/repository-plugin) | `self-modification` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index 19c1f1b280..d814b6ac6e 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.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 docs/persistence-catalog.md
-persistence-catalog.md: 614f6afbeb8fbaadbb43a76782c5a345180b25e7
+persistence-catalog.md: c9aa15cd827d99cee64e7a33db11995ee17f9bf8
 persistence-catalog.zh.md: 364912b88c3b2c5efd92a616034be9ef5025ee67
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 76487ca3d4..c9aa15cd82 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -3,7 +3,7 @@
 
 # Session Persistence Event Catalog
 
-Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
+Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge into `@deepseek-ai/dsh-session/types` in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the generated region of [session.md](subsystems/session.md#cordis-surface) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
 
 This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).
 
@@ -101,7 +101,7 @@ Sources: [`packages/core/session/src/types.ts:308`](../packages/core/session/src
 }
 ```
 
-Source: [`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:19`](../packages/core/agent/src/types.ts)
 
 ### `approval/*`
 
@@ -212,7 +212,7 @@ Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/
 }
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:153`](../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/types.ts:41`](../packages/interaction/commands/src/types.ts)
 
 #### `command/run` — log-only
 
@@ -230,7 +230,7 @@ Source: [`packages/interaction/commands/src/index.ts:153`](../packages/interacti
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:146`](../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/types.ts:34`](../packages/interaction/commands/src/types.ts)
 
 ### `compact/*`
 
@@ -244,7 +244,7 @@ Source: [`packages/interaction/commands/src/index.ts:146`](../packages/interacti
 'compact/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:69`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:71`](../packages/compact/compact/src/types.ts)
 
 #### `compact/prune` — log-only
 
@@ -268,7 +268,7 @@ Source: [`packages/compact/compact/src/types.ts:69`](../packages/compact/compact
 }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:79`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:81`](../packages/compact/compact/src/types.ts)
 
 #### `compact/start` — log-only
 
@@ -281,7 +281,7 @@ Source: [`packages/compact/compact/src/types.ts:79`](../packages/compact/compact
 'compact/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
 ```
 
-Source: [`packages/compact/compact/src/types.ts:21`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:23`](../packages/compact/compact/src/types.ts)
 
 #### `compact/summary` — log-only
 
@@ -333,7 +333,7 @@ Source: [`packages/compact/compact/src/types.ts:21`](../packages/compact/compact
 
 Types: [ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
 
-Source: [`packages/compact/compact/src/types.ts:31`](../packages/compact/compact/src/types.ts)
+Source: [`packages/compact/compact/src/types.ts:33`](../packages/compact/compact/src/types.ts)
 
 ### `feedback/*`
 
@@ -417,7 +417,7 @@ Source: [`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook-
 'llm/retry': LlmRetryEventData
 ```
 
-Source: [`packages/llm/llm-retry/src/index.ts:20`](../packages/llm/llm-retry/src/index.ts)
+Source: [`packages/llm/llm-retry/src/types.ts:9`](../packages/llm/llm-retry/src/types.ts)
 
 #### `llm/retry-started` — log-only
 
@@ -426,7 +426,7 @@ Source: [`packages/llm/llm-retry/src/index.ts:20`](../packages/llm/llm-retry/src
 'llm/retry-started': LlmRetryStartedEventData
 ```
 
-Source: [`packages/llm/llm-retry/src/index.ts:22`](../packages/llm/llm-retry/src/index.ts)
+Source: [`packages/llm/llm-retry/src/types.ts:11`](../packages/llm/llm-retry/src/types.ts)
 
 ### `permission/*`
 
@@ -648,12 +648,10 @@ Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/
  * before returning), so its execution-enclosure relation holds by
  * construction.
  */
-'tool/code-dispatch': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
+'tool/code-dispatch': CodeDispatchEventData
 ```
 
-Types: [CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md)
-
-Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/code-mode.ts)
+Source: [`packages/core/tools/src/types.ts:56`](../packages/core/tools/src/types.ts)
 
 #### `tool/code-dispatch-start` — log-only
 
@@ -671,12 +669,10 @@ Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/c
  * with `tool/code-dispatch` by `subCallId` (timing = the two events'
  * `time` fields).
  */
-'tool/code-dispatch-start': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
+'tool/code-dispatch-start': CodeDispatchStartEventData
 ```
 
-Types: [CallId](subsystems/core.md)
-
-Source: [`packages/core/tools/src/code-mode.ts:33`](../packages/core/tools/src/code-mode.ts)
+Source: [`packages/core/tools/src/types.ts:40`](../packages/core/tools/src/types.ts)
 
 #### `tool/result` — surface
 
diff --git a/docs/subsystems/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml
index 9466165680..32c5f15c15 100644
--- a/docs/subsystems/commands.i18n.yaml
+++ b/docs/subsystems/commands.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 docs/subsystems/commands.md
-commands.md: 7f4e4e87d7206be3e46c7076ee5e8ab6a7589f9a
-commands.zh.md: 0f8ff31bca5f62824912f53aee8dbc32db4c331b
+commands.md: 5e280d659c2a74b3d8ba20f362922e9eb4e0b84c
+commands.zh.md: 24f099d1926f7dba45122bdc53c23a4274e3f507
diff --git a/docs/subsystems/commands.md b/docs/subsystems/commands.md
index 7f4e4e87d7..5e280d659c 100644
--- a/docs/subsystems/commands.md
+++ b/docs/subsystems/commands.md
@@ -161,7 +161,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](core.md)
 
-Source: [`packages/interaction/commands/src/index.ts:307`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:267`](../../packages/interaction/commands/src/index.ts)
 
 <a id="commands-events"></a>
 
@@ -183,5 +183,5 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:174`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:134`](../../packages/interaction/commands/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/commands.zh.md b/docs/subsystems/commands.zh.md
index 0f8ff31bca..24f099d192 100644
--- a/docs/subsystems/commands.zh.md
+++ b/docs/subsystems/commands.zh.md
@@ -161,7 +161,7 @@ async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<Comma
 
 Types: [Agent](core.md)
 
-Source: [`packages/interaction/commands/src/index.ts:307`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:267`](../../packages/interaction/commands/src/index.ts)
 
 <a id="commands-events"></a>
 
@@ -183,5 +183,5 @@ A command was registered or unregistered. This is an unfiltered registry notific
 'commands/change'(): void
 ```
 
-Source: [`packages/interaction/commands/src/index.ts:174`](../../packages/interaction/commands/src/index.ts)
+Source: [`packages/interaction/commands/src/index.ts:134`](../../packages/interaction/commands/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index 2fb9c399be..70ceac3b11 100644
--- a/docs/subsystems/core.i18n.yaml
+++ b/docs/subsystems/core.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 docs/subsystems/core.md
-core.md: ec9a966164f2b706ae16341c628fb8f849eb7382
-core.zh.md: 4de168fd9714a935b4d9b08bbabd52492d1ea1cc
+core.md: 27c4359e360223d336cd94695bb45a79f0fd370c
+core.zh.md: 4e7519665b6d9efb8075546d93325debd961905d
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index ec9a966164..27c4359e36 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -547,7 +547,7 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:254`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
@@ -575,7 +575,7 @@ A fully configured agent and live session were published. Setup is composition-o
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:159`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentdisposed--emit"></a>
 
@@ -597,7 +597,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:168`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agenterror--emit"></a>
 
@@ -621,7 +621,7 @@ A step or turn errored. The machine reports a failure here even when the error h
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:290`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxclaimed--emit"></a>
 
@@ -645,7 +645,7 @@ One message left the inbox inside its open turn. If the proposed step is rejecte
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:197`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxdiscarded--emit"></a>
 
@@ -666,7 +666,7 @@ One message was discarded from the live inbox.
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:205`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxinserted--emit"></a>
 
@@ -687,7 +687,7 @@ One message entered the live inbox.
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:186`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentpre-step--waterfall"></a>
 
@@ -712,7 +712,7 @@ Reject a proposed step or replace the messages that enter it. Calling `next()` p
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:231`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentrequest--waterfall"></a>
 
@@ -738,7 +738,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach
 
 Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:244`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentrequest-error--waterfall"></a>
 
@@ -767,7 +767,7 @@ Handle one failed model-request attempt before the loop retries or closes its st
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:260`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentsession-start--emit"></a>
 
@@ -791,7 +791,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:217`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentstatus--emit"></a>
 
@@ -814,7 +814,7 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running`
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:178`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentturn-stopping--serial"></a>
 
@@ -845,7 +845,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:278`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agent-loop-events"></a>
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 4de168fd97..4e7519665b 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -555,7 +555,7 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:254`](../../packages/core/agent/src/index.ts)
 
 <a id="agent-events"></a>
 
@@ -583,7 +583,7 @@ A fully configured agent and live session were published. Setup is composition-o
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:159`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentdisposed--emit"></a>
 
@@ -605,7 +605,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:168`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agenterror--emit"></a>
 
@@ -629,7 +629,7 @@ A step or turn errored. The machine reports a failure here even when the error h
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:290`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxclaimed--emit"></a>
 
@@ -653,7 +653,7 @@ One message left the inbox inside its open turn. If the proposed step is rejecte
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:197`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxdiscarded--emit"></a>
 
@@ -674,7 +674,7 @@ One message was discarded from the live inbox.
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:205`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentinboxinserted--emit"></a>
 
@@ -695,7 +695,7 @@ One message entered the live inbox.
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:186`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentpre-step--waterfall"></a>
 
@@ -720,7 +720,7 @@ Reject a proposed step or replace the messages that enter it. Calling `next()` p
 
 Types: [Scoped](scope.md) · [UserMessage](session.md)
 
-Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:231`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentrequest--waterfall"></a>
 
@@ -746,7 +746,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach
 
 Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:244`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentrequest-error--waterfall"></a>
 
@@ -775,7 +775,7 @@ Handle one failed model-request attempt before the loop retries or closes its st
 
 Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:260`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentsession-start--emit"></a>
 
@@ -799,7 +799,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:217`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentstatus--emit"></a>
 
@@ -822,7 +822,7 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running`
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:178`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agentturn-stopping--serial"></a>
 
@@ -853,7 +853,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/runtime-types.ts:278`](../../packages/core/agent/src/runtime-types.ts)
 
 <a id="agent-loop-events"></a>
 
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index d015cdb638..1384b3888b 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.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 docs/subsystems/tools.md
-tools.md: f06db58b9b52fcb2c325ff813406cd2dc460ea7b
-tools.zh.md: cca4bf9faa870d9414d95f785b67e0393e469cdd
+tools.md: 83389f39c3188fc251504ed5786249ff1921acae
+tools.zh.md: 45cb85b3f2940f84b46bc58406bc8255cbe08be7
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index f06db58b9b..83389f39c3 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -554,7 +554,7 @@ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 
 Types: [ScopeKey](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:746`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:747`](../../packages/core/tools/src/index.ts)
 
 <a id="tools-events"></a>
 
@@ -579,7 +579,7 @@ A tool was registered or unregistered, or a scoped restriction changed (the avai
 'tools/change'(): void
 ```
 
-Source: [`packages/core/tools/src/index.ts:191`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:192`](../../packages/core/tools/src/index.ts)
 
 <a id="toolscode-dispatch-log--waterfall"></a>
 
@@ -605,7 +605,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri
 
 Types: [ContentBlock](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:174`](../../packages/core/tools/src/index.ts)
 
 <a id="toolsexecute--waterfall"></a>
 
@@ -629,7 +629,7 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:149`](../../packages/core/tools/src/index.ts)
 
 <a id="toolspost-execute--waterfall"></a>
 
@@ -654,7 +654,7 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:161`](../../packages/core/tools/src/index.ts)
 
 <a id="toolspre-execute--waterfall"></a>
 
@@ -677,7 +677,7 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:138`](../../packages/core/tools/src/index.ts)
 
 <a id="toolsresult--emit"></a>
 
@@ -698,5 +698,5 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:182`](../../packages/core/tools/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index cca4bf9faa..45cb85b3f2 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -554,7 +554,7 @@ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 
 Types: [ScopeKey](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:746`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:747`](../../packages/core/tools/src/index.ts)
 
 <a id="tools-events"></a>
 
@@ -579,7 +579,7 @@ A tool was registered or unregistered, or a scoped restriction changed (the avai
 'tools/change'(): void
 ```
 
-Source: [`packages/core/tools/src/index.ts:191`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:192`](../../packages/core/tools/src/index.ts)
 
 <a id="toolscode-dispatch-log--waterfall"></a>
 
@@ -605,7 +605,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri
 
 Types: [ContentBlock](llm-streaming.md) · [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:174`](../../packages/core/tools/src/index.ts)
 
 <a id="toolsexecute--waterfall"></a>
 
@@ -629,7 +629,7 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:149`](../../packages/core/tools/src/index.ts)
 
 <a id="toolspost-execute--waterfall"></a>
 
@@ -654,7 +654,7 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:161`](../../packages/core/tools/src/index.ts)
 
 <a id="toolspre-execute--waterfall"></a>
 
@@ -677,7 +677,7 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:138`](../../packages/core/tools/src/index.ts)
 
 <a id="toolsresult--emit"></a>
 
@@ -698,5 +698,5 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
 
 Types: [Scoped](scope.md)
 
-Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:182`](../../packages/core/tools/src/index.ts)
 <!-- END GENERATED cordis-surface -->

From e11f630fcdbd155dcf94f35d208a8b0516703f23 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 19:12:54 +0800
Subject: [PATCH 496/516] fix(client): address remaining conversation review
 feedback

---
 ...lient-conversation-node-assembly.i18n.yaml |  4 +--
 ...08-09-client-conversation-node-assembly.md |  2 ++
 ...09-client-conversation-node-assembly.zh.md |  2 ++
 docs/subsystems/compaction.i18n.yaml          |  4 +--
 docs/subsystems/compaction.md                 |  2 +-
 docs/subsystems/compaction.zh.md              |  2 +-
 .../src/client/chat/TurnTailNodeView.tsx      |  6 ++--
 .../src/client/contract/chat-nodes.ts         |  2 +-
 .../ui-conversation/tests/chat-view.spec.tsx  | 36 ++++++++++++++-----
 .../src/client/turn-deliverables.ts           |  4 ++-
 vitest.config.ts                              |  1 +
 11 files changed, 47 insertions(+), 18 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index d19cd86c7d..b76951347b 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.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 .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: 9952f8fac0f2a3b0fe72cc97ae9a8fb4f96ace08
-2026-08-09-client-conversation-node-assembly.zh.md: f27a82459cdacdb4a2da27cf12b30c93f2dfdf64
+2026-08-09-client-conversation-node-assembly.md: 16a39539064644e5467f701789a7e2ef1f7ff172
+2026-08-09-client-conversation-node-assembly.zh.md: 0e0fbdf8f3320393022528e6e3fe2cf0d492a1d3
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index 9952f8fac0..16a3953906 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -394,6 +394,8 @@ History-path tests cover complete replace, non-overlapping prepend, overlapping-
 
 A new business node can register its matcher, State transitions, optional Location data, final target Node, and renderer locally without changing Session's business switch. `ChatNodeDataMap` and the Location data maps let a business package merge strongly typed data into the contract; every related Event must still expose a stable ID derivable from that Event alone.
 
+Host business packages declaration-merge their durable Event members into `@deepseek-ai/dsh-session/types`, while Client Definitions type-only import the corresponding business package `/types` subpaths. Augmenting the declaring interface rather than a re-export barrel gives the independent Host and Client TypeScript programs the same Event narrowing without pulling Host runtime into the Client graph.
+
 Initial tail, older prepend, and live append share one set of Context invariants. Missing starts, Reader window gaps, unknown Locations, and high-frequency deltas are explicit engine states and require no direction-specific business cache.
 
 Append does not scan historical Contexts; prepend replays only Contexts whose Matches, Locations, or Reader answers actually changed. A structural Chat change may still recompute visible order and indexes, but does not rerun unrelated business folds or replace unchanged Node identity.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index f27a82459c..0e0fbdf8f3 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -394,6 +394,8 @@ Assembled Web snapshot、GUI 和浏览器场景覆盖真实 plugin graph。浏
 
 新增业务节点可以局部注册自己的 matcher、State 转换、可选 Location data、最终 target Node 和 renderer，不再修改 Session 的业务 switch。`ChatNodeDataMap` 和 Location data maps 允许业务 package 通过 declaration merging 合入强类型 data；所有相关 Event 仍须暴露可单 Event 推导的稳定 ID。
 
+Host 业务 package 把自己的持久 Event 成员 declaration-merge 到 `@deepseek-ai/dsh-session/types`，Client Definition 则通过对应业务 package 的 `/types` 子路径进行 type-only import。增强实际声明接口而不是重导出 barrel，使 Host 和 Client 的独立 TypeScript Program 都能获得相同的 Event narrowing，同时不把 Host runtime 带入 Client 图。
+
 初始尾页、older prepend 和 live append 共享一套 Context 不变量。缺 start、Reader window gap、Location unknown 以及高频 delta 都是引擎明确表达的状态，不需要业务另建方向相关 cache。
 
 Append 不扫描历史 Context；prepend 只 replay Match、Location 或 Reader 答案真正受影响的 Context。Chat 结构变化仍可能重算 visible order 和索引，但不会重跑无关业务 fold 或替换未变化 Node identity。
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index fd8dbdd1b5..532750f069 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 1aca48d677a83a488d9590edad3f8a68ca662b70
-compaction.zh.md: e2cfabc0891126d9f2165e47dffcf485f4a8a339
+compaction.md: 11ee6eae797db1c57bf2ffbb90f1f37f47b8400c
+compaction.zh.md: a560e47dbb7aa92f0757179534803bbcaaebc6ba
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 1aca48d677..11ee6eae79 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -20,7 +20,7 @@ The lock brackets the **whole** operation: `compact/start` is appended first, th
 
 The markers are lock time points, not an exclusive container. An unrelated idle injection can appear between a standalone manual start and end while summarization is pending. The manual path revalidates only its selected positional span, so that injected context survives after the replacement checkpoint. A live unmatched start blocks every entry point; an unmatched start before a newer `session/end-seed` is stale evidence from a prior lifecycle and is ignored.
 
-These variants are merged inside a `declare module '@deepseek-ai/dsh-session'` block, so — unlike the top-level types on the other subsystem pages — they are not pasted as a drift-checked ` ```ts type-equiv ` block (the `verify-type-equiv` extractor matches only top-level declarations by name). The payload table above is the catalog entry; follow the source link for the authoritative shapes.
+These variants are merged inside a `declare module '@deepseek-ai/dsh-session/types'` block, so — unlike the top-level types on the other subsystem pages — they are not pasted as a drift-checked ` ```ts type-equiv ` block (the `verify-type-equiv` extractor matches only top-level declarations by name). The payload table above is the catalog entry; follow the source link for the authoritative shapes.
 
 ## `CompactionResult`
 
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index e2cfabc089..a560e47dbb 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -20,7 +20,7 @@
 
 这些标记表示锁的时间点，而不是排他的容器。摘要等待期间，不相关的空闲注入可以出现在独立的手动 start 与 end 之间。手动路径只重新验证所选位置 span，因此替换检查点之后仍保留该注入上下文。活动的未匹配 start 会阻塞所有入口点；较新 `session/end-seed` 之前的未匹配 start 是先前生命周期留下的陈旧证据，会被忽略。
 
-这些变体在 `declare module '@deepseek-ai/dsh-session'` 块内合并，因此——与其他子系统页面上的顶层类型不同——它们不以漂移检查的 ` ```ts type-equiv ` 块粘贴（`verify-type-equiv` 提取器只按名称匹配顶层声明）。上方的载荷表即为目录条目；权威形状请循源码链接查看。
+这些变体在 `declare module '@deepseek-ai/dsh-session/types'` 块内合并，因此——与其他子系统页面上的顶层类型不同——它们不以漂移检查的 ` ```ts type-equiv ` 块粘贴（`verify-type-equiv` 提取器只按名称匹配顶层声明）。上方的载荷表即为目录条目；权威形状请循源码链接查看。
 
 ## `CompactionResult`
 
diff --git a/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
index bf48fc75c6..444389e6ea 100644
--- a/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/TurnTailNodeView.tsx
@@ -9,9 +9,11 @@ type TurnTailNodeViewProps = ChatNodeViewProps<'turn-tail'> & PropsRenderSlots<'
 
 /** Turn-local actions and feature tail over the Location index, independent of Assistant placement. */
 export const TurnTailNodeView = memo(function TurnTailNodeView({
-  node, openFile, forkAt, renderSlotChain, t,
+  node, openFile, forkAt, renderSlotChain, t, useSession,
 }: TurnTailNodeViewProps) {
   const data = node.data
+  const hasLaterChatNode = useSession(snapshot =>
+    snapshot.chat.locations.getTurn(data.turn).at(-1) !== node.key)
   const turn = node.location.kind === 'turn' || node.location.kind === 'step'
     ? node.location.turn
     : undefined
@@ -34,7 +36,7 @@ export const TurnTailNodeView = memo(function TurnTailNodeView({
         tokensPerSecond={data.tokensPerSecond}
         clock="end"
         onBranch={() => { forkAt(closing.finalNode.seq) }}
-        branchUnavailable={data.branchUnavailable}
+        branchUnavailable={data.branchUnavailable || hasLaterChatNode}
         className={css.actions}
         t={t}
       />
diff --git a/packages/client/ui-conversation/src/client/contract/chat-nodes.ts b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
index 787f391006..c057d15d1b 100644
--- a/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
+++ b/packages/client/ui-conversation/src/client/contract/chat-nodes.ts
@@ -57,7 +57,7 @@ export interface TurnTailChatData {
   readonly time: number
   /** Last finalized content-bearing Assistant in this Turn. */
   readonly closing: FinalAssistantChatData | null
-  /** Whether later Assistant/Step material makes the closing seq non-tail. */
+  /** Whether non-rendered later evidence makes the closing seq non-tail. */
   readonly branchUnavailable: boolean
   readonly ttftMs?: number
   readonly tokensPerSecond?: number
diff --git a/packages/client/ui-conversation/tests/chat-view.spec.tsx b/packages/client/ui-conversation/tests/chat-view.spec.tsx
index ca6223826e..6b2072ddfb 100644
--- a/packages/client/ui-conversation/tests/chat-view.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.spec.tsx
@@ -181,14 +181,12 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     if (key !== 'conversation.chat.node') return opts?.fallback ?? null
     const nodeOwner = owner as RoutedChatNodeOwner
     const nodeKey = opts?.hookContext as string | undefined
-    const useTurnData = ((dataKey: string) => {
-      return props.useSession((snapshot) => {
-        const location = nodeKey === undefined ? undefined : snapshot.chat.nodes.get(nodeKey)?.location
-        return location?.kind === 'turn' || location?.kind === 'step'
-          ? location.turn.data.get(dataKey as never)
-          : undefined
-      })
-    }) as UseChatNodeTurnData
+    const useTurnData: UseChatNodeTurnData = dataKey => props.useSession((snapshot) => {
+      const location = nodeKey === undefined ? undefined : snapshot.chat.nodes.get(nodeKey)?.location
+      return location?.kind === 'turn' || location?.kind === 'step'
+        ? location.turn.data.get(dataKey)
+        : undefined
+    })
     const nodeProps = <Kind extends ChatNode['kind']>(): ChatNodeViewProps<Kind> => (
       { ...props, ...nodeOwner, useTurnData } as unknown as ChatNodeViewProps<Kind>
     )
@@ -722,6 +720,28 @@ describe('ChatView', () => {
     expect(h.forkAt.mock.calls).toEqual([[2]])
   })
 
+  it('disables fork when the indexed Turn has a later steering Node', () => {
+    const base = chatSnapshotFixture({
+      nodes: [user(1, 'question'), assistant(2, 'answer')],
+      turnEnds: new Map([[1, 4]]),
+    })
+    const chat = {
+      ...base,
+      locations: {
+        getTurn: (turn: number) => turn === 1
+          ? [...base.locations.getTurn(turn), 'fixture:steering:later']
+          : base.locations.getTurn(turn),
+        getStep: (turn: number, step: number) => base.locations.getStep(turn, step),
+      },
+    }
+    const h = makeHarness({ chat })
+    const view = render(<h.ChatView {...h.props} />)
+    const branch = view.getByRole('button', { name: '在新对话中分支' })
+    expect(branch.getAttribute('aria-disabled')).toBe('true')
+    fireEvent.click(branch)
+    expect(h.forkAt).not.toHaveBeenCalled()
+  })
+
   it('keeps final content actions but disables branch when Tool and interrupted Think follow it', () => {
     const interruptedThink: AssistantMessageNode = {
       kind: 'assistant', seq: 4.1, time: 4_100, turn: 1, step: 2,
diff --git a/packages/client/ui-deliverables/src/client/turn-deliverables.ts b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
index 0227b34261..9151f88869 100644
--- a/packages/client/ui-deliverables/src/client/turn-deliverables.ts
+++ b/packages/client/ui-deliverables/src/client/turn-deliverables.ts
@@ -36,7 +36,9 @@ interface DeliverablesState extends DeliverablesTurnData {
  * Paths a call view reports having created or changed, by render intent rather
  * than tool name: a diff card, or a generic card whose kind is `edit` (the
  * shape `str_replace_editor`'s insert presents). Every other card produces
- * nothing to open — a read looked, a delete removed, a terminal ran.
+ * nothing to open — a read looked, a delete removed, a terminal ran. Only
+ * root call views enter this Turn accumulator; nested Code Mode dispatches
+ * preserve the pre-assembly behavior and do not contribute independently.
  */
 function producedPaths(view: ToolResultNode['callView']): readonly string[] {
   if (view === null) return []
diff --git a/vitest.config.ts b/vitest.config.ts
index e07ae43ec3..33512f4898 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -211,6 +211,7 @@ export default defineConfig({
         'packages/client/ui-workspace/src/client/index.ts',
         'packages/client/test-runtime/src/translate.ts',
         'packages/client/ui-primitives/src/JsonTree.tsx',
+        'packages/client/ui-deliverables/src/client/turn-deliverables.ts',
         // Typert generator: correctness is pinned by its fixture suites and
         // the byte-for-byte catalog reproduction test; per-file coverage
         // would put whole-workspace compiler analysis under v8

From 126ad5bb02147a5d584349fbce4111e274cea8ff Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 19:36:15 +0800
Subject: [PATCH 497/516] docs: development

---
 docs/architecture.i18n.yaml                   |   4 +-
 docs/architecture.md                          |   3 +-
 docs/architecture.zh.md                       |   3 +-
 .../adding-a-conversation-node.i18n.yaml      |   6 +
 docs/cookbook/adding-a-conversation-node.md   | 232 ++++++++++++++++
 .../cookbook/adding-a-conversation-node.zh.md | 232 ++++++++++++++++
 docs/cookbook/extension-cookbook.i18n.yaml    |   4 +-
 docs/cookbook/extension-cookbook.md           |   3 +-
 docs/cookbook/extension-cookbook.zh.md        |   3 +-
 docs/event-producer-consumer.i18n.yaml        |   2 +-
 docs/event-producer-consumer.zh.md            |  44 +--
 docs/module-graph.i18n.yaml                   |   2 +-
 docs/module-graph.zh.md                       | 253 +++++++++---------
 docs/persistence-catalog.i18n.yaml            |   2 +-
 docs/persistence-catalog.zh.md                |  66 ++---
 docs/subsystems/session.i18n.yaml             |   4 +-
 docs/subsystems/session.md                    |   2 +
 docs/subsystems/session.zh.md                 |   2 +
 packages/client/AGENTS.md                     |   6 +
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |   2 +
 packages/client/runtime/README.zh.md          |   2 +
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +
 packages/client/ui-conversation/README.zh.md  |   2 +
 scripts/doc-budgets.manifest.json             |   2 +-
 website/docs.ts                               |   8 +
 27 files changed, 698 insertions(+), 201 deletions(-)
 create mode 100644 docs/cookbook/adding-a-conversation-node.i18n.yaml
 create mode 100644 docs/cookbook/adding-a-conversation-node.md
 create mode 100644 docs/cookbook/adding-a-conversation-node.zh.md

diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index dff7978387..fe32a219de 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 506283bfc651d38fe4bccd50fb8a86143d2b41d8
-architecture.zh.md: ea48af8131ebbdc70a45e403dfddc78dfcfb6f47
+architecture.md: 771d7489ee338db56362a6ccc133b1ebf8cdc7c0
+architecture.zh.md: ca7c4fe2a463e01a8e14e63a53f13aea45cbfa16
diff --git a/docs/architecture.md b/docs/architecture.md
index 506283bfc6..771d7489ee 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -183,10 +183,11 @@ New behavior attaches to a documented extension point; a loop change updates thi
 | Intercept a request, tool, or turn | use its `agent/*` or `tools/*` event; `agent/turn-stopping` is the stop boundary |
 | Add model-facing context | call `agent.inject()` to queue sourced context for the next admitted request |
 | Add UI or editor integration | drive `ctx.agents` and render from `session/event` |
+| Web Client Chat node | register a `ConversationNodeDefinition` + keyed renderer |
 | Add durable session state | extend `SessionEventMap`; render and replay from the log |
 | Add asynchronous session-title generation | register the sole `ctx.sessionTitle` provider |
 | Manage a same-session objective | use `ctx.goals`; continue through `Agent` and `agent/*` |
 | Fork a live session | call `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | Scope a registration to one agent | use its `agent.ctx` (see Agent Scope) |
 
-The [extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities; guides cover [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [vendored packages](cookbook/adding-a-vendored-package.md).
+[Extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities; guides cover [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), [Chat nodes](cookbook/adding-a-conversation-node.md), and [vendored packages](cookbook/adding-a-vendored-package.md).
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index ea48af8131..ca7c4fe2a4 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -183,10 +183,11 @@ idle inject:
 | 拦截请求、工具或轮次 | 使用相应的 `agent/*` 或 `tools/*` 事件；`agent/turn-stopping` 是停止边界 |
 | 添加模型可见上下文 | 调用 `agent.inject()`，将带来源的上下文排入下一次获准请求 |
 | 添加 UI 或编辑器集成 | 驱动 `ctx.agents` 并从 `session/event` 渲染 |
+| Web Client Chat 节点 | 注册 `ConversationNodeDefinition` + keyed renderer |
 | 添加持久会话状态 | 扩展 `SessionEventMap`；从日志渲染和回放 |
 | 添加异步会话标题生成 | 注册唯一的 `ctx.sessionTitle` 提供方 |
 | 管理同会话目标 | 使用 `ctx.goals`；通过 `Agent` 和 `agent/*` 续跑 |
 | fork 活跃会话 | 调用 `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | 将注册项限定到单个 agent | 使用其 `agent.ctx`（参见 Agent 作用域） |
 
-[扩展实操手册（cookbook）](cookbook/extension-cookbook.md)将功能映射到能力；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
+[扩展实操手册](cookbook/extension-cookbook.md)将功能映射到能力；指南涵盖[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM 适配器](cookbook/adding-an-llm-adapter.md)、[Chat 节点](cookbook/adding-a-conversation-node.md)和 [vendored 包](cookbook/adding-a-vendored-package.md)。
diff --git a/docs/cookbook/adding-a-conversation-node.i18n.yaml b/docs/cookbook/adding-a-conversation-node.i18n.yaml
new file mode 100644
index 0000000000..aa268e9461
--- /dev/null
+++ b/docs/cookbook/adding-a-conversation-node.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 docs/cookbook/adding-a-conversation-node.md
+adding-a-conversation-node.md: ea4ec73eb109af6b0e4c7cf50fc8692942c75dd4
+adding-a-conversation-node.zh.md: 4b9a8049e2f1d060ec4bc3334036559b989ea562
diff --git a/docs/cookbook/adding-a-conversation-node.md b/docs/cookbook/adding-a-conversation-node.md
new file mode 100644
index 0000000000..ea4ec73eb1
--- /dev/null
+++ b/docs/cookbook/adding-a-conversation-node.md
@@ -0,0 +1,232 @@
+# Add a Web Client conversation node
+
+English | [中文](adding-a-conversation-node.zh.md)
+
+This tutorial adds one business-owned row to the Web Client Chat view. The finished plugin correlates a durable Session event family into one Context, incrementally builds business State, publishes typed Step data, and renders a keyed Chat Node without scanning the Session window or other rendered nodes. It assumes the Host already records the events and the client plugin is composed into the Web bundle; external Host-side UIs and additional view targets such as Trajectory are outside this tutorial.
+
+The [Conversation Node assembly decision](../../.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md) owns the rationale and complete engine model. This guide covers the implementation path.
+
+## 1. Design a replayable event family
+
+Choose one stable business id before writing the Definition. Every event that contributes to the same Node must carry that id or derive it independently from its own payload; the client must never assign an update to “the latest unfinished” Context.
+
+For a review job, the event contract could be:
+
+| Event | Role | Required durable facts |
+|---|---|---|
+| `review/start` | unique start | `reviewId`, Turn/Step coordinates, title |
+| `review/progress` | update | the same `reviewId`, coordinates, replayable progress |
+| `review/end` | update | the same `reviewId`, coordinates, final summary |
+
+Use the producer-owned branded id type across the process boundary. Put the `SessionEventMap` merge and payload types on the producer's type-only export, then import that export for side effects from the client package. Each `(kind, id)` may have at most one start event. A single-event business can use the event's stable identity, such as `event.seq`, as its Definition-local id.
+
+Incremental events are supported. Prefer whole-value checkpoints when the producer can emit them cheaply, because they remain useful when the start is outside the loaded window. Each delta must carry the stable id and produce deterministic State when replayed in ascending log `seq`; it must not depend on live-only memory. If the current history window contains only updates, the assembler keeps a pending Context and builds no State until an older page supplies the start. If the product must render before the start is loaded, a terminal or checkpoint event must carry enough whole fallback state for the Definition to build that result directly; do not recover it by scanning unrelated events.
+
+## 2. Implement the Definition and typed Chat payload
+
+The example keeps the producer declarations and client contribution in one block so the complete relationship is visible. In a package family, keep the branded id and `SessionEventMap` declaration with the event producer, and keep the Definition, Chat data merge, and renderer in the client plugin.
+
+```ts ignore-check
+import { createElement } from 'react'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type {
+  ClientContext, ConversationLocation, ConversationNodeContext,
+  ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ChatNodeViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+type ReviewId = Branded<'ReviewId'>
+
+interface ReviewStartData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly title: string
+}
+
+interface ReviewProgressData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly completed: number
+}
+
+interface ReviewEndData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly summary: string
+}
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * Opens one durable review job.
+     * @mode emit
+     * @param data - stable identity, location, and initial display state.
+     */
+    'review/start': ReviewStartData
+    /**
+     * Records replayable progress for one review job.
+     * @mode emit
+     * @param data - stable identity, location, and latest progress.
+     */
+    'review/progress': ReviewProgressData
+    /**
+     * Closes one review job with its final summary.
+     * @mode emit
+     * @param data - stable identity, location, and final display state.
+     */
+    'review/end': ReviewEndData
+  }
+}
+
+interface ReviewChatData {
+  readonly title: string
+  readonly completed: number
+  readonly status: 'running' | 'completed'
+  readonly summary?: string
+}
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationStepDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+interface ReviewState extends ReviewChatData {
+  readonly turn: number
+  readonly step: number
+}
+
+function locationOf(context: ConversationNodeContext): ConversationLocation {
+  return context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' }
+}
+
+function viewData(state: ReviewState): ReviewChatData {
+  return {
+    title: state.title,
+    completed: state.completed,
+    status: state.status,
+    ...state.summary === undefined ? {} : { summary: state.summary },
+  }
+}
+
+const reviewDefinition: ConversationNodeDefinition<ReviewState> = {
+  kind: 'review-job',
+  match: (event) => {
+    if (event.type === 'review/start') {
+      return { id: String(event.data.reviewId), role: 'start' }
+    }
+    if (event.type === 'review/progress' || event.type === 'review/end') {
+      return { id: String(event.data.reviewId), role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'review/start') throw new Error('review-job requires review/start')
+    return {
+      turn: match.event.data.turn,
+      step: match.event.data.step,
+      title: match.event.data.title,
+      completed: 0,
+      status: 'running',
+    }
+  },
+  update: (context, match) => {
+    if (match.event.type === 'review/progress') {
+      return { ...context.state, completed: match.event.data.completed }
+    }
+    if (match.event.type === 'review/end') {
+      return { ...context.state, completed: 100, status: 'completed', summary: match.event.data.summary }
+    }
+    return context.state
+  },
+  publication: match => match.event.type === 'review/progress'
+    ? 'animation-frame'
+    : 'immediate',
+  buildLocationData: (context, scope) => {
+    if (scope !== 'step' || context.state === undefined) return null
+    return {
+      kind: 'step',
+      turn: context.state.turn,
+      step: context.state.step,
+      key: 'review-job',
+      value: viewData(context.state),
+    }
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat' || context.state === undefined) return null
+    return {
+      key: context.key,
+      kind: 'review-job',
+      id: context.id,
+      target: 'chat',
+      anchorSeq: context.start?.event.seq ?? context.matches[0]?.event.seq ?? 0,
+      location: locationOf(context),
+      visibility: 'visible',
+      data: viewData(context.state),
+    }
+  },
+}
+
+function ReviewNodeView({ node }: ChatNodeViewProps<'review-job'>) {
+  const text = node.data.summary ?? `${node.data.title}: ${node.data.completed}%`
+  return createElement('p', null, text)
+}
+
+export const inject = ['conversationEvents', 'slots']
+
+export function apply(ctx: ClientContext): void {
+  ctx.conversationEvents.register(reviewDefinition)
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'review-job',
+  }, ReviewNodeView))
+}
+```
+
+`match(event)` is an identity extractor, not a fold: it receives only the current event and returns the Definition-local id and lifecycle role. After a match, the assembler locates the Context by `(kind, id)` and calls `start` once or `update` with the current State. Both functions return the State that the engine adopts; returning a new immutable value is preferred, but a function that mutates and returns the same object has the same adoption semantics.
+
+`buildLocationData(context, scope)` optionally publishes Definition-owned data onto an engine-owned Turn or Step. Use declaration merging to give each key a precise value type. Another Node in the same Location can consume that value through its constrained slot hook, such as `useTurnData(key)`, without receiving the Session or scanning `snapshot.chat.nodes`.
+
+`buildViewNode(context, target)` materializes the final target-specific Node. Preserve `context.key` as the React-facing identity, choose `anchorSeq` from durable ordering evidence, and return only renderer-ready data. Once a target Node has been published, keep returning the same key; use `visibility: 'hidden'` when it must temporarily leave the visible flow rather than withdrawing it with `null`.
+
+## 3. Query an earlier business Context only at start
+
+Some Definitions need the latest earlier State of another business kind. `start` receives a `ConversationContextReader`; call `reader.previous<State>(kind)` there instead of accepting a Context collection or scanning events. The reader returns the nearest started Context before the current start `seq` as read-only data.
+
+The assembler records that dependency. If an older prepend later supplies a nearer predecessor, closes a previously unknown window gap, or revises the predecessor State, it reruns the dependent Context from `start` and replays its updates in ascending `seq`. The queried Definition remains responsible for writing useful State; the reader exposes no business-specific query methods and grants no mutation authority over another Context.
+
+## 4. Understand the three ingestion paths
+
+History may be requested from the tail backward one page at a time, but every accepted page is normalized into ascending `seq` before State replay.
+
+| Path | Engine work | Definition-visible behavior |
+|---|---|---|
+| Replace on open, resync, or gap repair | Rebuild the loaded window, match every event once per Definition, then replay each started Context | `start`, followed by its updates in ascending `seq`; pending update-only Contexts remain without State |
+| Prepend one older page | Match only fresh older events, merge them into Contexts by `(kind, id)`, preserve existing keyed nodes, and replay only affected Contexts and dependencies | A newly found start activates its collected updates; a changed Location or predecessor may rerun the Context |
+| Append one live event | Call each Definition's `match` once, look up the matched Context by key, and update only that Context | One `update` and one requested publication for a matching post-start event; no existing Context scan |
+
+With `D` registered Definitions, one incoming event performs `D` current-event matches and constant-time Context-key lookup after a match. Definition code must preserve that property: do not traverse the complete event window, every Context, `context.matches`, or the rendered Node collection on the normal append path. Use State for accumulated facts, Location data for same-Turn/Step sharing, and `reader.previous()` for indexed predecessor dependencies.
+
+`publication` controls when changed State is materialized. Use `immediate` for structural or terminal changes, `animation-frame` for high-frequency visible deltas, and `none` when the State change feeds only a later publication. The engine still applies every update in log order; cadence only coalesces view publication.
+
+## 5. Verify replay, pagination, and rendering
+
+Add focused tests that establish these outcomes:
+
+1. A complete window passed through replace produces the expected final State, Location data, Node payload, and `anchorSeq`.
+2. An update-only tail stays pending; prepending the unique start produces the same result as a complete replace.
+3. Initial history followed by live append produces the same result as replaying the combined window.
+4. Prepending an older page adds earlier rows without replacing existing keyed Node values whose data did not change.
+5. Repeated visible deltas preserve `context.key` and publish at most once per animation frame when requested.
+6. The keyed renderer consumes `node.data` and constrained Location hooks only; it does not scan the Session event window, Contexts, or Chat Nodes.
+
+Use [`packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts) for streaming and interruption, [`inbox.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts) plus [`message.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/message.ts) for predecessor queries, and [`packages/client/ui-deliverables`](../../packages/client/ui-deliverables) for a Definition that publishes Turn data without creating its own Node.
diff --git a/docs/cookbook/adding-a-conversation-node.zh.md b/docs/cookbook/adding-a-conversation-node.zh.md
new file mode 100644
index 0000000000..4b9a8049e2
--- /dev/null
+++ b/docs/cookbook/adding-a-conversation-node.zh.md
@@ -0,0 +1,232 @@
+# 添加 Web Client Conversation Node
+
+[English](adding-a-conversation-node.md) | 中文
+
+本教程为 Web Client Chat 视图添加一行由业务自行拥有的内容。完成后的插件会把一个持久 Session 事件族关联成一个 Context，增量构造业务 State，发布类型化 Step 数据，再渲染 keyed Chat Node；整个过程不扫描 Session 窗口或其他已渲染节点。本教程假设 Host 已经记录这些事件，且该 Client 插件已组装进 Web bundle；Host 侧外部 UI 和 Trajectory 等额外视图目标不在本文范围内。
+
+[Conversation Node 组装决策](../../.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md)记录完整的引擎模型和设计理由；本文只说明实现路径。
+
+## 1. 设计可回放的事件族
+
+编写 Definition 前先选定稳定的业务 id。构成同一个 Node 的每条事件都必须携带该 id，或只凭自身 payload 独立推导出该 id；Client 绝不能把 update 猜测为属于“最近一个未完成”的 Context。
+
+以一个 review job 为例，事件约定可以是：
+
+| 事件 | 角色 | 必须持久化的事实 |
+|---|---|---|
+| `review/start` | 唯一 start | `reviewId`、Turn/Step 坐标、标题 |
+| `review/progress` | update | 相同的 `reviewId`、坐标、可回放进度 |
+| `review/end` | update | 相同的 `reviewId`、坐标、最终摘要 |
+
+跨进程边界使用生产方拥有的 branded id 类型。把 `SessionEventMap` 合并和 payload 类型放在生产方的纯类型导出中，再由 Client 包通过仅类型副作用导入该导出。每个 `(kind, id)` 最多只能有一条 start 事件。单事件业务可以把事件自身的稳定身份（例如 `event.seq`）作为 Definition 内部 id。
+
+系统支持增量事件。如果生产方能以较低成本发出 whole-value checkpoint，应优先采用，因为 start 位于已加载窗口之外时它仍可直接使用。每条 delta 都必须携带稳定 id，并且按照日志 `seq` 升序回放时能够确定性地产生 State；它不能依赖只存在于实时内存中的状态。如果当前历史窗口只有 update，Assembler 会保留一个 pending Context，并在更早分页补齐 start 前不构造 State。如果产品必须在 start 尚未加载时渲染，terminal 或 checkpoint 事件就必须携带足够的完整 fallback 状态，让 Definition 能直接构造结果；不要通过扫描无关事件恢复它。
+
+## 2. 实现 Definition 与类型化 Chat payload
+
+为了完整展示关联关系，下面把生产方声明和 Client 贡献写在同一个代码块里。实际的包族中，branded id 与 `SessionEventMap` 声明留在事件生产方，Definition、Chat data 合并与 renderer 留在 Client 插件。
+
+```ts ignore-check
+import { createElement } from 'react'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type {
+  ClientContext, ConversationLocation, ConversationNodeContext,
+  ConversationNodeDefinition,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ChatNodeViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+type ReviewId = Branded<'ReviewId'>
+
+interface ReviewStartData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly title: string
+}
+
+interface ReviewProgressData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly completed: number
+}
+
+interface ReviewEndData {
+  readonly reviewId: ReviewId
+  readonly turn: number
+  readonly step: number
+  readonly summary: string
+}
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * Opens one durable review job.
+     * @mode emit
+     * @param data - stable identity, location, and initial display state.
+     */
+    'review/start': ReviewStartData
+    /**
+     * Records replayable progress for one review job.
+     * @mode emit
+     * @param data - stable identity, location, and latest progress.
+     */
+    'review/progress': ReviewProgressData
+    /**
+     * Closes one review job with its final summary.
+     * @mode emit
+     * @param data - stable identity, location, and final display state.
+     */
+    'review/end': ReviewEndData
+  }
+}
+
+interface ReviewChatData {
+  readonly title: string
+  readonly completed: number
+  readonly status: 'running' | 'completed'
+  readonly summary?: string
+}
+
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+  interface ChatNodeDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+  interface ConversationStepDataMap {
+    'review-job': ReviewChatData
+  }
+}
+
+interface ReviewState extends ReviewChatData {
+  readonly turn: number
+  readonly step: number
+}
+
+function locationOf(context: ConversationNodeContext): ConversationLocation {
+  return context.start?.location ?? context.matches[0]?.location ?? { kind: 'unresolved' }
+}
+
+function viewData(state: ReviewState): ReviewChatData {
+  return {
+    title: state.title,
+    completed: state.completed,
+    status: state.status,
+    ...state.summary === undefined ? {} : { summary: state.summary },
+  }
+}
+
+const reviewDefinition: ConversationNodeDefinition<ReviewState> = {
+  kind: 'review-job',
+  match: (event) => {
+    if (event.type === 'review/start') {
+      return { id: String(event.data.reviewId), role: 'start' }
+    }
+    if (event.type === 'review/progress' || event.type === 'review/end') {
+      return { id: String(event.data.reviewId), role: 'update' }
+    }
+    return null
+  },
+  start: (_context, match) => {
+    if (match.event.type !== 'review/start') throw new Error('review-job requires review/start')
+    return {
+      turn: match.event.data.turn,
+      step: match.event.data.step,
+      title: match.event.data.title,
+      completed: 0,
+      status: 'running',
+    }
+  },
+  update: (context, match) => {
+    if (match.event.type === 'review/progress') {
+      return { ...context.state, completed: match.event.data.completed }
+    }
+    if (match.event.type === 'review/end') {
+      return { ...context.state, completed: 100, status: 'completed', summary: match.event.data.summary }
+    }
+    return context.state
+  },
+  publication: match => match.event.type === 'review/progress'
+    ? 'animation-frame'
+    : 'immediate',
+  buildLocationData: (context, scope) => {
+    if (scope !== 'step' || context.state === undefined) return null
+    return {
+      kind: 'step',
+      turn: context.state.turn,
+      step: context.state.step,
+      key: 'review-job',
+      value: viewData(context.state),
+    }
+  },
+  buildViewNode: (context, target) => {
+    if (target !== 'chat' || context.state === undefined) return null
+    return {
+      key: context.key,
+      kind: 'review-job',
+      id: context.id,
+      target: 'chat',
+      anchorSeq: context.start?.event.seq ?? context.matches[0]?.event.seq ?? 0,
+      location: locationOf(context),
+      visibility: 'visible',
+      data: viewData(context.state),
+    }
+  },
+}
+
+function ReviewNodeView({ node }: ChatNodeViewProps<'review-job'>) {
+  const text = node.data.summary ?? `${node.data.title}: ${node.data.completed}%`
+  return createElement('p', null, text)
+}
+
+export const inject = ['conversationEvents', 'slots']
+
+export function apply(ctx: ClientContext): void {
+  ctx.conversationEvents.register(reviewDefinition)
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'review-job',
+  }, ReviewNodeView))
+}
+```
+
+`match(event)` 是身份提取器，不是 fold：它只能收到当前事件，并返回 Definition 内部 id 与生命周期角色。命中后，Assembler 通过 `(kind, id)` 定位 Context，再调用一次 `start`，或把当前 State 交给 `update`。两个函数都必须返回引擎随后采用的 State；推荐返回新的 immutable value，但函数原地修改后返回同一对象时，采用语义也相同。
+
+`buildLocationData(context, scope)` 可以把 Definition 拥有的数据发布到引擎拥有的 Turn 或 Step 上。通过 declaration merging 为每个 key 指定精确 value 类型。同一 Location 内的另一个 Node 可以使用受限 slot hook（例如 `useTurnData(key)`）读取该值，无须取得 Session，也无须扫描 `snapshot.chat.nodes`。
+
+`buildViewNode(context, target)` 物化最终的目标专用 Node。把 `context.key` 保留为 React 侧身份，根据持久排序证据选择 `anchorSeq`，并且只返回 renderer 可以直接使用的数据。某个 target Node 一旦发布，就要继续返回同一个 key；需要暂时离开可见流时使用 `visibility: 'hidden'`，不要改为返回 `null` 撤回它。
+
+## 3. 只在 start 时查询更早的业务 Context
+
+有些 Definition 需要另一个业务 kind 在当前位置之前的最新 State。`start` 会收到 `ConversationContextReader`；应在这里调用 `reader.previous<State>(kind)`，不要接收 Context 集合或扫描事件。Reader 返回当前 start `seq` 之前最近一个已启动 Context 的只读数据。
+
+Assembler 会记录这项依赖。如果后续 older prepend 带来了更近的前序 Context、补齐了原先未知的窗口缺口，或者前序 State 被修订，引擎会从 `start` 重新运行依赖方 Context，并按 `seq` 升序回放其 update。被查询的 Definition 仍负责把有用信息写入自身 State；Reader 不提供业务专用查询方法，也不授予修改其他 Context 的权限。
+
+## 4. 理解三条摄入路径
+
+历史可能从尾部开始一页一页向前请求，但每个已接收分页都会先按 `seq` 升序归一化，再进入 State 回放。
+
+| 路径 | 引擎工作 | Definition 可观察到的行为 |
+|---|---|---|
+| open、resync 或 gap repair 时 replace | 重建已加载窗口，每条事件对每个 Definition 匹配一次，再回放每个已有 start 的 Context | 先执行 `start`，再按 `seq` 升序执行其 update；只有 update 的 pending Context 仍没有 State |
+| prepend 一页更早历史 | 只匹配新增的更早事件，按 `(kind, id)` 合并进 Context，保留现有 keyed node，并只重放受影响的 Context 与依赖 | 新发现的 start 会激活已收集 update；Location 或前序依赖变化也可能重跑 Context |
+| append 一条实时事件 | 每个 Definition 各调用一次 `match`，按 key 查找命中的 Context，只更新该 Context | 对 start 之后的匹配事件执行一次 `update` 并请求一次发布；不扫描已有 Context |
+
+注册 `D` 个 Definition 时，一条新事件会进行 `D` 次仅当前事件匹配；命中后的 Context key 查询是常数时间。Definition 代码必须维持这个性质：正常 append 热路径不得遍历完整事件窗口、所有 Context、`context.matches` 或已渲染 Node 集合。累计事实放进 State，同 Turn/Step 共享信息放进 Location data，有索引的前序依赖使用 `reader.previous()`。
+
+`publication` 控制发生 State 变更后何时物化。结构或 terminal 变化使用 `immediate`，高频可见 delta 使用 `animation-frame`，只为后续发布积累 State 时使用 `none`。引擎仍会按日志顺序应用每条 update；该选项只合并视图发布频率。
+
+## 5. 验证回放、分页与渲染
+
+添加聚焦测试，证明以下结果：
+
+1. 完整窗口通过 replace 后产生预期的最终 State、Location data、Node payload 与 `anchorSeq`。
+2. 只有 update 的尾部窗口保持 pending；prepend 唯一 start 后，结果与完整 replace 相同。
+3. 初始历史后继续实时 append，与回放合并后的完整窗口得到相同结果。
+4. prepend 更早分页只增加更早的行；数据未变化的既有 keyed Node value 不被替换。
+5. 重复的可见 delta 保持 `context.key`，并在请求 `animation-frame` 时每帧最多发布一次。
+6. keyed renderer 只消费 `node.data` 与受限 Location hook，不扫描 Session 事件窗口、Context 或 Chat Node。
+
+流式与中断处理可参考 [`packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/assistant.ts)，前序查询可参考 [`inbox.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts) 与 [`message.ts`](../../packages/client/ui-conversation/src/client/conversation-nodes/message.ts)，只发布 Turn data 而不创建自有 Node 的例子见 [`packages/client/ui-deliverables`](../../packages/client/ui-deliverables)。
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index 0509a67549..7eaa702a9d 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/extension-cookbook.md
-extension-cookbook.md: 025a1b6ecd11593b5d6be9d0f64e57ac8b5e3139
-extension-cookbook.zh.md: f838a281fabdba473b72b27f7b14274d9aa97528
+extension-cookbook.md: 5d9312f2f5cf840100b12045bde1829b342e580d
+extension-cookbook.zh.md: 29bb57c558a0ff9413619d0bb2e8bb5e6b70da56
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index 025a1b6ecd..5d9312f2f5 100644
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -34,7 +34,7 @@ This waterfall is the reorderable policy layer. Use `ctx.tools.guard()` when an
 
 ## A UI plugin
 
-A UI plugin renders from the `session/event` feed (the assistant token stream as `assistant/chunk`, plus turn/step boundaries and tool activity), and drives input back in via `agent.followup()` / `agent.steer()`.
+A UI plugin renders from the `session/event` feed (the assistant token stream as `assistant/chunk`, plus turn/step boundaries and tool activity), and drives input back in via `agent.followup()` / `agent.steer()`. A browser plugin contributing a business row to the built-in Web Client instead registers a `ConversationNodeDefinition` and keyed Chat renderer; follow the [Conversation Node guide](adding-a-conversation-node.md).
 
 ```ts
 import type { Context } from 'cordis'
@@ -123,6 +123,7 @@ Every product feature maps to a listener on a documented extension point — the
 | Memory | section provider + tool |
 | Scheduled tasks (cron) | a plugin registers model-callable scheduling tools; timer fires → `followup(…, {source: {kind: 'cron', …}})` when idle / `inject()` notification when busy |
 | UI (GUI; CLI emits JSONL) | listen `session/event` (assistant chunks, boundaries, tool activity); input → `followup()` |
+| Web Client Chat business node | register a `ConversationNodeDefinition` and `conversation.chat.node` keyed renderer |
 | Telemetry / replayable trace | `session/event` → JSONL; replay = `sessions.create(id, { seed })` |
 | Model adapters | `LlmAdapter` subclass via `registerAdapter` (`dsh-llm-deepseek`, `dsh-llm-pi-ai`) |
 | Plugin hot-reload | every registration is a `ctx.effect` → vendored HMR just works |
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index f838a281fa..29bb57c558 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -34,7 +34,7 @@ export function apply(ctx: Context) {
 
 ## UI 插件
 
-UI 插件从 `session/event` 事件流渲染（助手 token 流以 `assistant/chunk` 形式到达，加上轮次/步骤边界与工具活动），并通过 `agent.followup()` / `agent.steer()` 将输入驱动回去。
+UI 插件从 `session/event` 事件流渲染（助手 token 流以 `assistant/chunk` 形式到达，加上轮次/步骤边界与工具活动），并通过 `agent.followup()` / `agent.steer()` 将输入驱动回去。如果浏览器插件要向内建 Web Client 贡献业务行，则应注册 `ConversationNodeDefinition` 与 keyed Chat renderer；具体步骤见 [Conversation Node 指南](adding-a-conversation-node.md)。
 
 ```ts
 import type { Context } from 'cordis'
@@ -123,6 +123,7 @@ export function apply(ctx: Context) {
 | 记忆 | section 提供方 + 工具 |
 | 定时任务（cron） | 插件注册面向模型的调度工具；定时器触发 → 空闲时 `followup(…, {source: {kind: 'cron', …}})`／忙碌时 `inject()` 通知 |
 | UI（GUI；CLI（命令行界面）输出 JSONL） | 监听 `session/event`（助手分片、边界、工具活动）；输入 → `followup()` |
+| Web Client Chat 业务节点 | 注册 `ConversationNodeDefinition` 与 `conversation.chat.node` keyed renderer |
 | 遥测 / 可回放 trace | `session/event` → JSONL；回放 = `sessions.create(id, { seed })` |
 | 模型适配器 | 通过 `registerAdapter` 注册 `LlmAdapter` 子类（`dsh-llm-deepseek`、`dsh-llm-pi-ai`） |
 | 插件热重载 | 每个注册都是一个 `ctx.effect` → 随仓库提供的 HMR（热模块替换）直接生效 |
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 812b490bef..89e1b03d35 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
 event-producer-consumer.md: 05ff62a391a0acb7db9abd2c9ce0c2082da52eaa
-event-producer-consumer.zh.md: 2d4c805f9a5d3b0531ee59eebe9e6564347f0a00
+event-producer-consumer.zh.md: 7eafe5f2880cf9f0e6f2e7eb6c299730926f15ed
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 2d4c805f9a..7eafe5f288 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -10,20 +10,20 @@
 | 事件 | 模式 | 声明位置 | 派发方 | 监听方 |
 | --- | --- | --- | --- | --- |
 | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
-| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/types.ts:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
-| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/types.ts:185`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
-| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
-| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:159`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:168`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:290`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
+| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/runtime-types.ts:197`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/discarded` | `emit` | [`packages/core/agent/src/runtime-types.ts:205`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
+| `agent/inbox/inserted` | `emit` | [`packages/core/agent/src/runtime-types.ts:186`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/pre-step` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:231`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`plan-mode`](../packages/plan/plan-mode), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:244`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
+| `agent/request-error` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:260`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:217`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:178`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
+| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
-| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
+| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:134`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
 | `credentials/updated` | `emit` | [`packages/credentials/credentials/src/index.ts:67`](../packages/credentials/credentials/src/index.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | `apiproxy`, [`credentials`](../packages/credentials/credentials) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
@@ -46,12 +46,12 @@
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
-| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
-| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:173`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
-| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:148`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
-| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:160`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
-| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:137`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
-| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
+| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:192`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
+| `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:174`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
+| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:149`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`timeout-policy`](../packages/guard/timeout-policy) |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:161`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:138`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-tasks`](../packages/tasks/tool-tasks) |
+| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:182`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
 | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:81`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
 | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
 | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:91`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
@@ -59,9 +59,9 @@
 | `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:53`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
 | `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:45`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
 
-## 包源码中出现的非 harness 或未声明事件字符串
+## Non-harness or undeclared event strings seen in package source
 
-| 事件字符串 | 派发方 | 监听方 |
+| Event string | Dispatchers | Listeners |
 | --- | --- | --- |
 | `commands/changed` | `runtime` (`emit`) | `ui-command` |
 | `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-permission`, `ui-settings-general` |
@@ -80,4 +80,4 @@
 | `slots/changed` | `runtime` (`emit`) | - |
 | `theme/change` | `ui-theme` (`emit`) | `ui-layout`, `ui-theme` |
 
-维护模式：英文源文件是生成内容，Cordis 事件声明及生产方／监听方的关系边由仓库的 TypeScript Program 解析；本中文文件作为经评审对侧通过双语配对维护。
+Maintenance mode: generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program.
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index 24ddaad77c..61e55cd997 100644
--- a/docs/module-graph.i18n.yaml
+++ b/docs/module-graph.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/module-graph.md
 module-graph.md: a248ed4fcb8abc17ffc6982d2733b3c3c2a2a635
-module-graph.zh.md: 255253bcfa9cfad1ab85602dfa9f953a02dfc427
+module-graph.zh.md: 28185c255ffa18f3ebc02f177d20594af3356164
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index 255253bcfa..28185c255f 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -438,9 +438,6 @@ flowchart TD
   pkg_fs --> pkg_sandbox
   pkg_skill_badge --> pkg_invariants
   pkg_skill_badge --> pkg_skill
-  pkg_compact --> pkg_invariants
-  pkg_compact --> pkg_llm
-  pkg_compact --> pkg_session
   pkg_web_fetch_local --> pkg_invariants
   pkg_web_fetch_local --> pkg_timeout
   pkg_web_fetch_local --> pkg_web
@@ -504,15 +501,11 @@ flowchart TD
   pkg_session_projection --> pkg_invariants
   pkg_session_projection --> pkg_session
   pkg_llm_retry --> pkg_agent
+  pkg_llm_retry --> pkg_brand
   pkg_llm_retry --> pkg_invariants
   pkg_llm_retry --> pkg_llm
   pkg_llm_retry --> pkg_session
   pkg_llm_retry --> pkg_timeout
-  pkg_token_meter --> pkg_compact
-  pkg_token_meter --> pkg_invariants
-  pkg_token_meter --> pkg_llm
-  pkg_token_meter --> pkg_session
-  pkg_token_meter --> pkg_session_projection
   pkg_agent_default_model --> pkg_agent
   pkg_agent_default_model --> pkg_invariants
   pkg_agent_default_model --> pkg_llm
@@ -552,10 +545,6 @@ flowchart TD
   pkg_hook_protocol --> pkg_bash
   pkg_hook_protocol --> pkg_invariants
   pkg_hook_protocol --> pkg_session
-  pkg_llm_replay --> pkg_compact
-  pkg_llm_replay --> pkg_invariants
-  pkg_llm_replay --> pkg_llm
-  pkg_llm_replay --> pkg_session
   pkg_loader_smoke --> pkg_agent
   pkg_loader_smoke --> pkg_invariants
   pkg_loader_smoke --> pkg_llm
@@ -676,14 +665,11 @@ flowchart TD
   pkg_fs_sandbox --> pkg_invariants
   pkg_fs_sandbox --> pkg_sandbox
   pkg_fs_sandbox --> pkg_sandbox_policy
-  pkg_command_compact --> pkg_commands
-  pkg_command_compact --> pkg_compact
-  pkg_command_compact --> pkg_invariants
-  pkg_compact_tool_result_prune --> pkg_compact
-  pkg_compact_tool_result_prune --> pkg_invariants
-  pkg_compact_tool_result_prune --> pkg_llm
-  pkg_compact_tool_result_prune --> pkg_session
-  pkg_compact_tool_result_prune --> pkg_token_meter
+  pkg_compact --> pkg_brand
+  pkg_compact --> pkg_commands
+  pkg_compact --> pkg_invariants
+  pkg_compact --> pkg_llm
+  pkg_compact --> pkg_session
   pkg_session_query --> pkg_brand
   pkg_session_query --> pkg_invariants
   pkg_session_query --> pkg_llm
@@ -705,13 +691,6 @@ flowchart TD
   pkg_headless --> pkg_invariants
   pkg_headless --> pkg_llm
   pkg_headless --> pkg_session
-  pkg_client_ui_conversation --> pkg_client_locale
-  pkg_client_ui_conversation --> pkg_client_runtime
-  pkg_client_ui_conversation --> pkg_client_ui_primitives
-  pkg_client_ui_conversation --> pkg_client_ui_slash
-  pkg_client_ui_conversation --> pkg_client_ui_slots
-  pkg_client_ui_conversation --> pkg_invariants
-  pkg_client_ui_conversation --> pkg_token_meter
   pkg_command_feedback --> pkg_commands
   pkg_command_feedback --> pkg_invariants
   pkg_command_feedback --> pkg_session
@@ -744,6 +723,11 @@ flowchart TD
   pkg_tasks_local --> pkg_invariants
   pkg_tasks_local --> pkg_tasks
   pkg_tasks_local --> pkg_timeout
+  pkg_token_meter --> pkg_compact
+  pkg_token_meter --> pkg_invariants
+  pkg_token_meter --> pkg_llm
+  pkg_token_meter --> pkg_session
+  pkg_token_meter --> pkg_session_projection
   pkg_agent_loop --> pkg_agent
   pkg_agent_loop --> pkg_invariants
   pkg_agent_loop --> pkg_llm
@@ -792,13 +776,9 @@ flowchart TD
   pkg_tool_skill --> pkg_llm
   pkg_tool_skill --> pkg_skill
   pkg_tool_skill --> pkg_tools
-  pkg_compact_basic --> pkg_agent
-  pkg_compact_basic --> pkg_compact
-  pkg_compact_basic --> pkg_compact_tool_result_prune
-  pkg_compact_basic --> pkg_invariants
-  pkg_compact_basic --> pkg_llm
-  pkg_compact_basic --> pkg_session
-  pkg_compact_basic --> pkg_token_meter
+  pkg_command_compact --> pkg_commands
+  pkg_command_compact --> pkg_compact
+  pkg_command_compact --> pkg_invariants
   pkg_subagent --> pkg_agent
   pkg_subagent --> pkg_brand
   pkg_subagent --> pkg_invariants
@@ -859,33 +839,10 @@ flowchart TD
   pkg_agent_loop_testkit --> pkg_session
   pkg_agent_loop_testkit --> pkg_system_prompt
   pkg_agent_loop_testkit --> pkg_tools
-  pkg_client_ui_command --> pkg_client_connection
-  pkg_client_ui_command --> pkg_client_locale
-  pkg_client_ui_command --> pkg_client_runtime
-  pkg_client_ui_command --> pkg_client_ui_conversation
-  pkg_client_ui_command --> pkg_client_ui_primitives
-  pkg_client_ui_command --> pkg_client_ui_slash
-  pkg_client_ui_command --> pkg_client_ui_slots
-  pkg_client_ui_command --> pkg_invariants
-  pkg_client_ui_deliverables --> pkg_client_locale
-  pkg_client_ui_deliverables --> pkg_client_runtime
-  pkg_client_ui_deliverables --> pkg_client_ui_conversation
-  pkg_client_ui_deliverables --> pkg_client_ui_slots
-  pkg_client_ui_deliverables --> pkg_invariants
-  pkg_client_ui_goal --> pkg_api_remotes
-  pkg_client_ui_goal --> pkg_client_locale
-  pkg_client_ui_goal --> pkg_client_runtime
-  pkg_client_ui_goal --> pkg_client_ui_conversation
-  pkg_client_ui_goal --> pkg_client_ui_primitives
-  pkg_client_ui_goal --> pkg_client_ui_slots
-  pkg_client_ui_goal --> pkg_goal
-  pkg_client_ui_goal --> pkg_invariants
-  pkg_client_ui_tool --> pkg_client_locale
-  pkg_client_ui_tool --> pkg_client_runtime
-  pkg_client_ui_tool --> pkg_client_ui_conversation
-  pkg_client_ui_tool --> pkg_client_ui_primitives
-  pkg_client_ui_tool --> pkg_client_ui_slots
-  pkg_client_ui_tool --> pkg_invariants
+  pkg_llm_replay --> pkg_compact
+  pkg_llm_replay --> pkg_invariants
+  pkg_llm_replay --> pkg_llm
+  pkg_llm_replay --> pkg_session
   pkg_session_reference --> pkg_agent
   pkg_session_reference --> pkg_compact
   pkg_session_reference --> pkg_invariants
@@ -992,6 +949,11 @@ flowchart TD
   pkg_tool_pwsh --> pkg_system_prompt
   pkg_tool_pwsh --> pkg_tasks
   pkg_tool_pwsh --> pkg_tools
+  pkg_compact_tool_result_prune --> pkg_compact
+  pkg_compact_tool_result_prune --> pkg_invariants
+  pkg_compact_tool_result_prune --> pkg_llm
+  pkg_compact_tool_result_prune --> pkg_session
+  pkg_compact_tool_result_prune --> pkg_token_meter
   pkg_subagent_acp --> pkg_agent
   pkg_subagent_acp --> pkg_invariants
   pkg_subagent_acp --> pkg_llm
@@ -1040,50 +1002,18 @@ flowchart TD
   pkg_web_app --> pkg_bash_env
   pkg_web_app --> pkg_invariants
   pkg_web_app --> pkg_system_prompt
-  pkg_client_ui_model --> pkg_client_connection
-  pkg_client_ui_model --> pkg_client_locale
-  pkg_client_ui_model --> pkg_client_runtime
-  pkg_client_ui_model --> pkg_client_ui_command
-  pkg_client_ui_model --> pkg_client_ui_conversation
-  pkg_client_ui_model --> pkg_client_ui_primitives
-  pkg_client_ui_model --> pkg_client_ui_slash
-  pkg_client_ui_model --> pkg_client_ui_slots
-  pkg_client_ui_model --> pkg_invariants
-  pkg_client_ui_permission --> pkg_client_connection
-  pkg_client_ui_permission --> pkg_client_locale
-  pkg_client_ui_permission --> pkg_client_runtime
-  pkg_client_ui_permission --> pkg_client_schema_form
-  pkg_client_ui_permission --> pkg_client_ui_command
-  pkg_client_ui_permission --> pkg_client_ui_primitives
-  pkg_client_ui_permission --> pkg_client_ui_slash
-  pkg_client_ui_permission --> pkg_client_ui_slots
-  pkg_client_ui_permission --> pkg_invariants
-  pkg_client_ui_permission --> pkg_permission
-  pkg_client_ui_plan --> pkg_client_connection
-  pkg_client_ui_plan --> pkg_client_locale
-  pkg_client_ui_plan --> pkg_client_runtime
-  pkg_client_ui_plan --> pkg_client_ui_conversation
-  pkg_client_ui_plan --> pkg_client_ui_primitives
-  pkg_client_ui_plan --> pkg_client_ui_slots
-  pkg_client_ui_plan --> pkg_invariants
-  pkg_client_ui_plan --> pkg_plan_mode
-  pkg_client_ui_skill --> pkg_client_connection
-  pkg_client_ui_skill --> pkg_client_locale
-  pkg_client_ui_skill --> pkg_client_runtime
-  pkg_client_ui_skill --> pkg_client_ui_primitives
-  pkg_client_ui_skill --> pkg_client_ui_slash
-  pkg_client_ui_skill --> pkg_client_ui_slots
-  pkg_client_ui_skill --> pkg_client_ui_tool
-  pkg_client_ui_skill --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_client_locale
-  pkg_client_ui_subagent --> pkg_client_runtime
-  pkg_client_ui_subagent --> pkg_client_ui_conversation
-  pkg_client_ui_subagent --> pkg_client_ui_primitives
-  pkg_client_ui_subagent --> pkg_client_ui_slash
-  pkg_client_ui_subagent --> pkg_client_ui_slots
-  pkg_client_ui_subagent --> pkg_invariants
-  pkg_client_ui_subagent --> pkg_subagent
-  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_client_ui_conversation --> pkg_agent
+  pkg_client_ui_conversation --> pkg_client_locale
+  pkg_client_ui_conversation --> pkg_client_runtime
+  pkg_client_ui_conversation --> pkg_client_ui_primitives
+  pkg_client_ui_conversation --> pkg_client_ui_slash
+  pkg_client_ui_conversation --> pkg_client_ui_slots
+  pkg_client_ui_conversation --> pkg_commands
+  pkg_client_ui_conversation --> pkg_compact
+  pkg_client_ui_conversation --> pkg_invariants
+  pkg_client_ui_conversation --> pkg_llm_retry
+  pkg_client_ui_conversation --> pkg_token_meter
+  pkg_client_ui_conversation --> pkg_tools
   pkg_sdk_protocol --> pkg_invariants
   pkg_sdk_protocol --> pkg_llm
   pkg_sdk_protocol --> pkg_session
@@ -1107,6 +1037,14 @@ flowchart TD
   pkg_workflow_workerthread --> pkg_subagent
   pkg_workflow_workerthread --> pkg_tools
   pkg_workflow_workerthread --> pkg_workflow
+  pkg_compact_basic --> pkg_agent
+  pkg_compact_basic --> pkg_commands
+  pkg_compact_basic --> pkg_compact
+  pkg_compact_basic --> pkg_compact_tool_result_prune
+  pkg_compact_basic --> pkg_invariants
+  pkg_compact_basic --> pkg_llm
+  pkg_compact_basic --> pkg_session
+  pkg_compact_basic --> pkg_token_meter
   pkg_subagent_codex --> pkg_invariants
   pkg_subagent_codex --> pkg_llm
   pkg_subagent_codex --> pkg_sdk_protocol
@@ -1122,6 +1060,50 @@ flowchart TD
   pkg_subagent_spawn --> pkg_invariants
   pkg_subagent_spawn --> pkg_subagent
   pkg_subagent_spawn --> pkg_subagent_inprocess
+  pkg_client_ui_command --> pkg_client_connection
+  pkg_client_ui_command --> pkg_client_locale
+  pkg_client_ui_command --> pkg_client_runtime
+  pkg_client_ui_command --> pkg_client_ui_conversation
+  pkg_client_ui_command --> pkg_client_ui_primitives
+  pkg_client_ui_command --> pkg_client_ui_slash
+  pkg_client_ui_command --> pkg_client_ui_slots
+  pkg_client_ui_command --> pkg_invariants
+  pkg_client_ui_deliverables --> pkg_client_locale
+  pkg_client_ui_deliverables --> pkg_client_runtime
+  pkg_client_ui_deliverables --> pkg_client_ui_conversation
+  pkg_client_ui_deliverables --> pkg_client_ui_slots
+  pkg_client_ui_deliverables --> pkg_invariants
+  pkg_client_ui_goal --> pkg_api_remotes
+  pkg_client_ui_goal --> pkg_client_locale
+  pkg_client_ui_goal --> pkg_client_runtime
+  pkg_client_ui_goal --> pkg_client_ui_conversation
+  pkg_client_ui_goal --> pkg_client_ui_primitives
+  pkg_client_ui_goal --> pkg_client_ui_slots
+  pkg_client_ui_goal --> pkg_goal
+  pkg_client_ui_goal --> pkg_invariants
+  pkg_client_ui_plan --> pkg_client_connection
+  pkg_client_ui_plan --> pkg_client_locale
+  pkg_client_ui_plan --> pkg_client_runtime
+  pkg_client_ui_plan --> pkg_client_ui_conversation
+  pkg_client_ui_plan --> pkg_client_ui_primitives
+  pkg_client_ui_plan --> pkg_client_ui_slots
+  pkg_client_ui_plan --> pkg_invariants
+  pkg_client_ui_plan --> pkg_plan_mode
+  pkg_client_ui_subagent --> pkg_client_locale
+  pkg_client_ui_subagent --> pkg_client_runtime
+  pkg_client_ui_subagent --> pkg_client_ui_conversation
+  pkg_client_ui_subagent --> pkg_client_ui_primitives
+  pkg_client_ui_subagent --> pkg_client_ui_slash
+  pkg_client_ui_subagent --> pkg_client_ui_slots
+  pkg_client_ui_subagent --> pkg_invariants
+  pkg_client_ui_subagent --> pkg_subagent
+  pkg_client_ui_subagent --> pkg_token_meter
+  pkg_client_ui_tool --> pkg_client_locale
+  pkg_client_ui_tool --> pkg_client_runtime
+  pkg_client_ui_tool --> pkg_client_ui_conversation
+  pkg_client_ui_tool --> pkg_client_ui_primitives
+  pkg_client_ui_tool --> pkg_client_ui_slots
+  pkg_client_ui_tool --> pkg_invariants
   pkg_agent_spine_demo --> pkg_agent
   pkg_agent_spine_demo --> pkg_agent_loop
   pkg_agent_spine_demo --> pkg_bash_env
@@ -1163,6 +1145,33 @@ flowchart TD
   pkg_subagent_dsh_sdk --> pkg_session
   pkg_subagent_dsh_sdk --> pkg_subagent
   pkg_subagent_dsh_sdk --> pkg_subprocess
+  pkg_client_ui_model --> pkg_client_connection
+  pkg_client_ui_model --> pkg_client_locale
+  pkg_client_ui_model --> pkg_client_runtime
+  pkg_client_ui_model --> pkg_client_ui_command
+  pkg_client_ui_model --> pkg_client_ui_conversation
+  pkg_client_ui_model --> pkg_client_ui_primitives
+  pkg_client_ui_model --> pkg_client_ui_slash
+  pkg_client_ui_model --> pkg_client_ui_slots
+  pkg_client_ui_model --> pkg_invariants
+  pkg_client_ui_permission --> pkg_client_connection
+  pkg_client_ui_permission --> pkg_client_locale
+  pkg_client_ui_permission --> pkg_client_runtime
+  pkg_client_ui_permission --> pkg_client_schema_form
+  pkg_client_ui_permission --> pkg_client_ui_command
+  pkg_client_ui_permission --> pkg_client_ui_primitives
+  pkg_client_ui_permission --> pkg_client_ui_slash
+  pkg_client_ui_permission --> pkg_client_ui_slots
+  pkg_client_ui_permission --> pkg_invariants
+  pkg_client_ui_permission --> pkg_permission
+  pkg_client_ui_skill --> pkg_client_connection
+  pkg_client_ui_skill --> pkg_client_locale
+  pkg_client_ui_skill --> pkg_client_runtime
+  pkg_client_ui_skill --> pkg_client_ui_primitives
+  pkg_client_ui_skill --> pkg_client_ui_slash
+  pkg_client_ui_skill --> pkg_client_ui_slots
+  pkg_client_ui_skill --> pkg_client_ui_tool
+  pkg_client_ui_skill --> pkg_invariants
   pkg_acp_demo --> pkg_acp
   pkg_acp_demo --> pkg_agent_spine_demo
   pkg_acp_demo --> pkg_app_boot
@@ -1240,7 +1249,6 @@ flowchart TD
 | [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`subprocess`](../packages/subprocess/subprocess) |
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/support/invariants), [`skill`](../packages/skill/skill) |
-| [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
 | [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
 | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
@@ -1257,8 +1265,7 @@ flowchart TD
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`agent-default-model`](../packages/core/agent-default-model) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1269,7 +1276,6 @@ flowchart TD
 | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`environment`](../packages/util/environment), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`web`](../packages/web/web) |
 | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
-| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
@@ -1297,19 +1303,18 @@ flowchart TD
 | [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
 | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
-| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
-| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`compact`](../packages/compact/compact) | `compact` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
 | [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
 | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`permission`](../packages/interaction/permission) | `interaction` | [`bash`](../packages/bash/bash), [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval) |
 | [`pty-local`](../packages/pty/pty-local) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subprocess`](../packages/subprocess/subprocess) |
 | [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) |
 | [`tasks-local`](../packages/tasks/tasks-local) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tasks`](../packages/tasks/tasks), [`timeout`](../packages/util/timeout) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
@@ -1317,7 +1322,7 @@ flowchart TD
 | [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
 | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
-| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`command-compact`](../packages/compact/command-compact) | `compact` | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants) |
 | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
@@ -1327,10 +1332,7 @@ flowchart TD
 | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
 | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
-| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query) |
 | [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
@@ -1349,6 +1351,7 @@ flowchart TD
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
 | [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
@@ -1357,20 +1360,26 @@ flowchart TD
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt) |
-| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
-| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
-| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
-| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`agent`](../packages/core/agent), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm-retry`](../packages/llm/llm-retry), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
 | [`sdk-protocol`](../packages/scaffold/protocol) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`repository-plugin`](../packages/self-modification/repository-plugin) | `self-modification` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`client-ui-command`](../packages/client/ui-command) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`plan-mode`](../packages/plan/plan-mode) |
+| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) |
+| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`bash-env`](../packages/bash/bash-env), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`paths`](../packages/util/paths), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks-local`](../packages/tasks/tasks-local), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`jsonrpc`](../packages/scaffold/server) | `scaffold` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`sdk-client`](../packages/scaffold/client) | `scaffold` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/scaffold/protocol), [`session`](../packages/core/session) |
 | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/scaffold/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`client-ui-model`](../packages/client/ui-model) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-command`](../packages/client/ui-command), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
+| [`client-ui-permission`](../packages/client/ui-permission) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-schema-form`](../packages/client/schema-form), [`client-ui-command`](../packages/client/ui-command), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`permission`](../packages/interaction/permission) |
+| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/support/invariants) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/acp/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/boot/app-boot), [`invariants`](../packages/support/invariants), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index d814b6ac6e..e676227869 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/persistence-catalog.md
 persistence-catalog.md: c9aa15cd827d99cee64e7a33db11995ee17f9bf8
-persistence-catalog.zh.md: 364912b88c3b2c5efd92a616034be9ef5025ee67
+persistence-catalog.zh.md: d8743a1b0f26f2a4cf50aed42eb68f6c6db1ba13
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index 364912b88c..d8743a1b0f 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -5,7 +5,7 @@
 
 [English](persistence-catalog.md) | 中文
 
-会话持久事件日志中可能出现的所有事件类型：完整持久化的 `SessionEvent` 信封，以及可通过合并扩展的 `SessionEventMap` 中的每个成员，包括 `@deepseek-ai/dsh-session` 所属的词汇和本仓库中每个插件的声明合并，并附有源 JSDoc、完整 payload 声明、surface 标记和声明位置。本文档是 [session.md](subsystems/session.md)（surface 排序与 `deriveMessages()` 投影）、[persistence.md](subsystems/persistence.md)（如何让日志持久化）和 [session.md](subsystems/session.md#cordis-surface) 中生成区域（实时总线接线；日志事件**不是** cordis 事件，它通过唯一一次 `session/event` emit 到达监听器）的补充。
+会话持久事件日志中可能出现的所有事件类型：完整持久化的 `SessionEvent` 信封，以及可通过合并扩展的 `SessionEventMap` 中的每个成员，包括 `@deepseek-ai/dsh-session` 所属的词汇和本仓库中每个插件对 `@deepseek-ai/dsh-session/types` 的声明合并，并附有源 JSDoc、完整 payload 声明、surface 标记和声明位置。本文档是 [session.md](subsystems/session.md)（surface 排序与 `deriveMessages()` 投影）、[persistence.md](subsystems/persistence.md)（如何让日志持久化）和 [session.md](subsystems/session.md#cordis-surface) 中生成区域（实时总线接线；日志事件**不是** cordis 事件，它通过唯一一次 `session/event` emit 到达监听器）的补充。
 
 英文源文件根据源码生成（`scripts/gen-persistence-catalog.ts`），并由 `pnpm run verify-persistence-catalog`（`doc-sync`（文档同步门禁）的一部分）验证新鲜度；本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc，只移除其所在接口／模块带来的缩进，并使用 `ts persistence-catalog` 围栏（doc-typecheck 会跳过这些围栏，因为声明引用了其所属模块中的类型）。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。
 
@@ -103,7 +103,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }
 ```
 
-来源：[`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/types.ts)
+来源：[`packages/core/agent/src/types.ts:19`](../packages/core/agent/src/types.ts)
 
 ### `approval/*`
 
@@ -214,7 +214,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }
 ```
 
-来源：[`packages/interaction/commands/src/index.ts:151`](../packages/interaction/commands/src/index.ts)
+来源：[`packages/interaction/commands/src/types.ts:41`](../packages/interaction/commands/src/types.ts)
 
 #### `command/run` — log-only
 
@@ -232,7 +232,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource }
 ```
 
-来源：[`packages/interaction/commands/src/index.ts:144`](../packages/interaction/commands/src/index.ts)
+来源：[`packages/interaction/commands/src/types.ts:34`](../packages/interaction/commands/src/types.ts)
 
 ### `compact/*`
 
@@ -243,10 +243,10 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  * Marks the end of a compaction — log-only, releases the lock. Its owner
  * matches `compact/start`; `error` records an unsuccessful attempt.
  */
-'compact/end': { turn: number | null; error?: string }
+'compact/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
 ```
 
-来源：[`packages/compact/compact/src/types.ts:65`](../packages/compact/compact/src/types.ts)
+来源：[`packages/compact/compact/src/types.ts:71`](../packages/compact/compact/src/types.ts)
 
 #### `compact/prune` — log-only
 
@@ -270,7 +270,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }
 ```
 
-来源：[`packages/compact/compact/src/types.ts:75`](../packages/compact/compact/src/types.ts)
+来源：[`packages/compact/compact/src/types.ts:81`](../packages/compact/compact/src/types.ts)
 
 #### `compact/start` — log-only
 
@@ -280,10 +280,10 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  * `compact/end`. A numbered owner is strictly enclosed by that open turn;
  * `null` identifies a standalone manual transaction between turns.
  */
-'compact/start': { turn: number | null }
+'compact/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
 ```
 
-来源：[`packages/compact/compact/src/types.ts:19`](../packages/compact/compact/src/types.ts)
+来源：[`packages/compact/compact/src/types.ts:23`](../packages/compact/compact/src/types.ts)
 
 #### `compact/summary` — log-only
 
@@ -298,6 +298,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  * before it (`compact/prune` documents the shared protocol).
  */
 'compact/summary': {
+  compactionId: CompactionId
+  sourceCommandId?: CommandId
   summary: ContentBlock[]
   shadowedRange: { start: number; end: number }
   shadowedSeqs: number[]
@@ -333,7 +335,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 类型：[ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md)
 
-来源：[`packages/compact/compact/src/types.ts:29`](../packages/compact/compact/src/types.ts)
+来源：[`packages/compact/compact/src/types.ts:33`](../packages/compact/compact/src/types.ts)
 
 ### `feedback/*`
 
@@ -414,29 +416,19 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 ```ts persistence-catalog
 /** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
-'llm/retry': {
-  turn: number
-  step: number
-  provider: string
-  mode: 'normal'
-  policyKey: string
-  retry: number
-  maxRetries: number
-  delayMs: number
-  failure: LlmFailure
-} | {
-  turn: number
-  step: number
-  provider: string
-  mode: 'always'
-  policyKey: string
-  retry: number
-  delayMs: number
-  failure: LlmFailure
-}
+'llm/retry': LlmRetryEventData
 ```
 
-来源：[`packages/llm/llm-retry/src/index.ts:17`](../packages/llm/llm-retry/src/index.ts)
+来源：[`packages/llm/llm-retry/src/types.ts:9`](../packages/llm/llm-retry/src/types.ts)
+
+#### `llm/retry-started` — log-only
+
+```ts persistence-catalog
+/** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
+'llm/retry-started': LlmRetryStartedEventData
+```
+
+来源：[`packages/llm/llm-retry/src/types.ts:11`](../packages/llm/llm-retry/src/types.ts)
 
 ### `permission/*`
 
@@ -658,12 +650,10 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  * before returning), so its execution-enclosure relation holds by
  * construction.
  */
-'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
+'tool/code-dispatch': CodeDispatchEventData
 ```
 
-类型：[CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md)
-
-来源：[`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/code-mode.ts)
+来源：[`packages/core/tools/src/types.ts:56`](../packages/core/tools/src/types.ts)
 
 #### `tool/code-dispatch-start` — log-only
 
@@ -681,12 +671,10 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
  * with `tool/code-dispatch` by `subCallId` (timing = the two events'
  * `time` fields).
  */
-'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
+'tool/code-dispatch-start': CodeDispatchStartEventData
 ```
 
-类型：[CallId](subsystems/core.md)
-
-来源：[`packages/core/tools/src/code-mode.ts:33`](../packages/core/tools/src/code-mode.ts)
+来源：[`packages/core/tools/src/types.ts:40`](../packages/core/tools/src/types.ts)
 
 #### `tool/result` — surface
 
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 04f3cc5394..4c8cad1880 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: a5162c77d510c5ab66fa2dd6789693e1449970fb
-session.zh.md: 989a3f5368aa0b0475dec4272fde724fd4a98230
+session.md: e5eb78908ba4b7ebfc398d5c735969a5a8937374
+session.zh.md: 51729999a831c94e87e36ec1c4705201f9c8360f
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index a5162c77d5..e5eb78908b 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -580,6 +580,8 @@ Activity ordering excludes the boundary through `lastActivityTime(events)`: pick
 
 A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The generated [persistence log event catalog](../persistence-catalog.md) enumerates every core and plugin-contributed event with its payload, surface badge, and declaration site; the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).
 
+When several events in one plugin-owned family assemble into one Web Client Conversation Node, every start, update, result, resource, or interruption event in that family carries or independently derives the same stable business id. This requirement applies to correlated Node families, not to every Session event; it lets the client group each event without guessing from adjacency or scanning history. See the [Conversation Node cookbook](../cookbook/adding-a-conversation-node.md).
+
 The hook bridges' `hook/invoked` / `hook/result` pairs (from `@deepseek-ai/dsh-hook-protocol`) correlate by `handlerId`. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` fire inside the loop's open turn, so their `hook/*` records are turn-enclosed by construction. `SessionStart` gets no `hook/*` record because it runs before turn 1; its context remains pending in the inbox until a waking delivery opens a turn (see [the hook-bridges Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)).
 
 ## Durability contract
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 989a3f5368..51729999a8 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -584,6 +584,8 @@ interface TurnEndReasonMap {
 
 插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。生成的[持久化日志事件目录](../persistence-catalog.md)会列出每个核心或插件贡献的事件，以及其 payload、surface 标记和声明位置；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。
 
+如果同一个插件事件族中的多条事件要组装成一个 Web Client Conversation Node，该事件族中的每条 start、update、result、resource 或 interruption 事件都必须携带或独立推导出同一个稳定业务 id。此要求只约束需要关联的 Node 事件族，并不要求每条 Session 事件都有业务 id；Client 因此无须根据相邻关系猜测归属，也无须扫描历史。参见 [Conversation Node 实操手册](../cookbook/adding-a-conversation-node.md)。
+
 钩子桥接层的 `hook/invoked` / `hook/result` 对（来自 `@deepseek-ai/dsh-hook-protocol`）通过 `handlerId` 关联。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 在 loop 已打开的轮次内触发，因此其 `hook/*` 记录天然位于轮次之内。`SessionStart` 不生成 `hook/*` 记录，因为它在轮次 1 之前运行；其上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次（见[钩子桥接 Agent Note](../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md)）。
 
 ## 持久性约定
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index 78704f52fa..9626e96e74 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -54,6 +54,12 @@ Non-negotiables across the layers:
 - **Notifier publication discipline**: `notifyNow` is only the direct echo of a user gesture; structural updates use microtask-batched `markDirty`, while visible streaming chunks use cumulative `markFrameDirty`. See `runtime/src/client/sessions/notifier.ts`.
 - **The web layer is pure presentation.** Nothing that is "how to draw" (tool-card views, queue states) enters the session log; the host computes such data per frame or pushes it live, and replay recomputes it — falling back to the generic form when it can't. A new *model-visible* input still requires a session event (repo-wide rule).
 
+## Conversation Node discipline
+
+- A Chat business feature registers one `ConversationNodeDefinition` and its keyed `conversation.chat.node` renderer; do not add its event switch or fold to `Session`, `SessionManager`, or a central built-in dispatcher. Follow the [Conversation Node cookbook](../../docs/cookbook/adding-a-conversation-node.md).
+- `match(event)` reads only the current event. Every event in a multi-event Context carries or independently derives the same stable business id; `update` folds one Match into State and remains deterministically replayable by log `seq`.
+- The append hot path and renderers never scan the full event window, Contexts, or Chat Nodes. Accumulate in State, publish same-Turn/Step facts through `buildLocationData()`, and consume final Node data or constrained Location hooks.
+
 ## Directory regime (plugin packages)
 
 One UI feature = one plugin package (`src/client/` browser half). A multi-domain package splits by future package boundaries — ui-conversation is the exemplar: `contract/` (the only shared face), domain directories that never import a sibling domain, and `apply.ts` as the single cross-domain assembly point; `scripts/verify-client-domain-graph.ts` enforces the levels. Registration goes through `slots.register` in `apply` — never module-level side effects.
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index d47266cd8a..139474af19 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: 46a383f22032c8da7e4bb9b5fb445980661c670f
-README.zh.md: 73578a8f249472abfdd7c539e3eaee6de767ad60
+README.md: df3689176cf059f46004fa7ecb31ab7c326ea0bc
+README.zh.md: 9afe9773ff2a6a320bdf66978877678428c46118
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index 46a383f220..df3689176c 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -38,6 +38,8 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 Each `Session` gives its contiguous event window to a `ConversationNodeAssembler`. Plugins register business Definitions that map one event to a stable `{kind, id}`, create State at the unique start event, fold correlated updates, and build final nodes for registered view targets. The assembler owns the Context index, read-only predecessor lookup, and a reference-stable Turn/Step Location index. A live append evaluates each Definition once and updates only the matched Context; loading an older page preserves existing Context and node identities, matches only the newly prepended events, and replays Contexts whose predecessor or Location facts changed. Full replacement is reserved for open, resync, and gap repair.
 
+Definition authors keep matching local to the current event, give every correlated event a stable business id, and make updates replayable by log `seq`; renderers consume final Node data and constrained Location values rather than scanning Session or Chat collections. The [Conversation Node cookbook](../../../docs/cookbook/adding-a-conversation-node.md) gives the complete registration and pagination path.
+
 `ui-conversation` registers the built-in Chat Definitions and the keyed Chat snapshot builder. Append-origin user, assistant, and Tool results remain the human record; model-only replacement copies stay out, except that a compaction checkpoint becomes its own marker and resolves missing summary provenance when an older page supplies it. Durable inbox splice Contexts classify next-step user messages as steering without making inbox state a Session special case. Context messages retain producer provenance and form. StatsLine reads `ConversationSnapshot.chat.legacy.nodes`, while Session mirrors that legacy slice into the top-level `nodes`, `partial`, and `runningCalls` public compatibility fields without running a second business fold. Trajectory consumes neither compatibility surface; its activated `session-history` inspection keeps an independent fold until it gains its own registered target.
 
 The Chat builder keeps one mutable keyed store per Session. Content updates notify only the affected node key, structural changes rebuild order and Location membership, and a prepend adds rows without replacing existing keyed values. Assistant chunks update Definition State for every event but request at most one materialization per animation frame; final messages and Turn/Step closure publish immediately. See the [client Tool presentation decision](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md).
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 73578a8f24..9afe9773ff 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -38,6 +38,8 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 每个 `Session` 都把连续事件窗口交给 `ConversationNodeAssembler`。插件注册业务 Definition，把单个事件映射为稳定的 `{kind, id}`，在唯一 start 事件处创建 State，折叠有关联的 update，再为已注册的视图目标构造最终节点。Assembler 负责 Context 索引、只读前序 Context 查询，以及引用稳定的 Turn/Step Location 索引。实时 append 只对每个 Definition 求值一次，并且只更新命中的 Context；加载更早分页时保留已有 Context 与节点身份，只匹配新 prepend 的事件，并重放前序依赖或 Location 事实发生变化的 Context。完整替换仅用于 open、resync 和 gap repair。
 
+Definition 作者只根据当前事件完成匹配，为每条关联事件提供稳定业务 id，并保证 update 能按日志 `seq` 回放；renderer 只消费最终 Node data 与受限 Location value，不扫描 Session 或 Chat 集合。完整注册和分页路径见 [Conversation Node 实操手册](../../../docs/cookbook/adding-a-conversation-node.md)。
+
 `ui-conversation` 注册内建 Chat Definition 与 keyed Chat snapshot builder。append 来源的 user、assistant 和 Tool result 构成人类可见记录；仅供模型使用的 replacement 副本不进入 Chat，compaction 检查点除外，它会成为独立标记，并在更早分页补齐 summary 溯源后更新。持久 inbox splice Context 能把 next-step 用户消息判定为 steering，无须让 inbox 状态成为 Session 特例。上下文消息保留生产者 provenance 与 form。StatsLine 读取 `ConversationSnapshot.chat.legacy.nodes`；Session 则把该 legacy slice 镜像到顶层 `nodes`、`partial` 和 `runningCalls` 公共兼容字段，无须运行第二套业务 fold。Trajectory 不消费这两种兼容表面；在它获得独立注册 target 之前，已激活的 `session-history` inspection 继续维护独立 fold。
 
 Chat builder 为每个 Session 保留一个 mutable keyed store。内容更新只通知受影响的 node key；结构变化才重建顺序和 Location 成员关系；prepend 只增加行，不替换既有 keyed value。每个 Assistant chunk 都会更新 Definition State，但最多每个 animation frame 请求一次物化；final message 与 Turn/Step 关闭会立即发布。参见 [Client Tool 展示所有权决策](../../../.agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.md)。
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index bb15c65029..1238e136d7 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 3570e814609af0bc4e7d048a55205af756fae843
-README.zh.md: e37f867c72d83b47924e87261e6ee5ff8b374a6f
+README.md: d894d3e578f065e9cb2c45676224efd1f4f76fa8
+README.zh.md: ec99a8d7daa593cdf3014f292a095fb2fd6f39d3
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 3570e81460..d894d3e578 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -12,6 +12,8 @@ Another plugin can make one session's composer inert through `ctx.conversation.b
 
 The view ring is a slot: the strict session-body registration declares the session-scoped `'conversation.view'` list in its `children` table, that body renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from registration options (`id`/`order`/`label`). The chat view is this package's own entry; plugins such as ui-trajectory contribute tabs through `ctx.slots.register`, and each view owns its chrome.
 
+Chat business rows are independent registry contributions rather than a closed built-in union. A client plugin declaration-merges its typed `ChatNodeDataMap` key, registers a `ConversationNodeDefinition` on `ctx.conversationEvents`, and registers the matching keyed renderer on `conversation.chat.node`; it does not modify Session folds or a central renderer switch. The [Conversation Node cookbook](../../../docs/cookbook/adding-a-conversation-node.md) covers stable event ids, append/prepend replay, Location data, and renderer constraints.
+
 Approvals take over the composer through the chain this package declares: `ApprovalPanel` registers as a selector-routed `'conversation.composer'` entry (the ui-question pattern) and occupies the composer in place of the InputBar while an approval wait is pending (amber strip, justification headline, paired command line from the running call's args, one-shot refuse/allow). The `PendingApproval` domain face in `contract/slots.ts` owns the wire encoding — the `ApprovalResponsePayload` value with the audit correlation — over the runtime's `PendingWait` carrier; the broadcast `approval/resolved` frame settles the wait and restores the composer. The runtime manager projects every approval or question wait through `SessionSummary.pendingInteraction`, including sessions never instantiated; `ui-workspace` owns its sidebar presentation. Pending waits leave the message flow entirely: questions (ui-question) and approvals (ApprovalPanel) both answer through the composer takeover, so no display-only placeholder card remains. The composer's bottom-row Access seat mounts `PermissionSelect`, fed by the host-computed `permissions` projection through the standard-kit `useProjection` (key absence hides the chip); the chip opens a Menu-primitive dropdown whose kebab-case preset names render as title-case labels. Safe preset picks submit `/permission <preset>` immediately through the bar's injected `command` callback, while `danger-full-access` is presented as `Full access` and first opens an in-page Modal risk confirmation. The enabling action stays disabled until the user checks the acknowledgement; cancel, Escape, close, and mask click submit nothing.
 
 The session header declares and renders the session-scoped `'conversation.session.header.actions'` list beside the title, allowing feature plugins to contribute controls without entering the skeleton. The composer chain currency includes the current conversation `session`; ui-subagent selects one-shot or parent-unavailable addressed sessions for reason-specific read-only copy, while the ordinary InputBar keeps every addressed child Send-only because the continuation service exposes no public per-Activation cancellation operation and `session.cancel` would bypass its ownership.
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index e37f867c72..ec99a8d7da 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -12,6 +12,8 @@
 
 视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
+Chat 业务行是彼此独立的注册表贡献，不是封闭的内建联合。Client 插件通过 declaration merging 增加类型化 `ChatNodeDataMap` key，在 `ctx.conversationEvents` 上注册 `ConversationNodeDefinition`，再向 `conversation.chat.node` 注册匹配的 keyed renderer；它无须修改 Session fold 或中央 renderer switch。稳定事件 id、append/prepend 回放、Location data 与 renderer 约束见 [Conversation Node 实操手册](../../../docs/cookbook/adding-a-conversation-node.md)。
+
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 
 已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。共享的 `DisclosureRow` 原子组件让该上下文界面与消息流中的其他紧凑行保持相同几何，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态或摘要（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[生产者标签决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源字段列出。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json
index b5c000a714..2626cec2da 100644
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,7 +1,7 @@
 {
   "AGENTS.md": 1782,
   "docs/AGENTS.md": 1320,
-  "docs/architecture.md": 2160,
+  "docs/architecture.md": 2174,
   "docs/cordis-primer.md": 600,
   "docs/defensive-patterns.md": 550,
   "docs/testing.md": 1150,
diff --git a/website/docs.ts b/website/docs.ts
index 1e97d88e24..a8d07a59c2 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -396,6 +396,14 @@ const reference = [
     section: { root: '开发手册', en: 'Cookbook' },
     order,
   }))),
+  ...pairedPages([{
+    source: 'docs/cookbook/adding-a-conversation-node.md',
+    route: 'reference/cookbook/adding-a-conversation-node.md',
+    label: { root: '新增 Conversation Node', en: 'Adding a Conversation Node' },
+    sidebar: { root: 'zh-reference', en: 'en-reference' },
+    section: { root: '开发手册', en: 'Cookbook' },
+    order: 4,
+  }]),
 ]
 
 /** Every canonical page published by the documentation website. */

From 548726eede3efdee74bda3a8da0b3b1e87fb3e3c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 19:58:29 +0800
Subject: [PATCH 498/516] ci(wine): add verified archive mirror fallback

---
 ...8-native-windows-pull-request-ci.i18n.yaml |  4 ++--
 ...26-08-08-native-windows-pull-request-ci.md |  2 +-
 ...08-08-native-windows-pull-request-ci.zh.md |  2 +-
 scripts/wine-windows-gates.sh                 | 22 ++++++++++++++-----
 4 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index 19c54de94b..cff610e481 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: a1f294b2b9e73a5d14a00780c7b0adfaf58e4702
-2026-08-08-native-windows-pull-request-ci.zh.md: 2c91c21118f5ebbd9f0e341f7d31ec71481db4dc
+2026-08-08-native-windows-pull-request-ci.md: 258bca96db04c44ca2a3509c297028e31ef5375e
+2026-08-08-native-windows-pull-request-ci.zh.md: dd0031630eea9bb09a4a4db0125933ba0c7bac2f
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index a1f294b2b9..258bca96db 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -10,7 +10,7 @@ The required pull-request Windows verdict needs a fast win32 toolchain signal wi
 
 ## Decision
 
-The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that runs the workspace build and production site. Node distribution transfers use bounded retries so a stalled download fails or recovers before consuming the job timeout. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
+The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that runs the workspace build and production site. Node distribution transfers use bounded retries; when nodejs.org stalls on the large archive, a range-capable transport mirror resumes the same bytes, but nodejs.org remains the version and SHA-256 authority and the archive is never promoted before that checksum passes. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
 
 Every pull request also starts an independent `windows-native` job named `windows node 24 / native complete` on GitHub's standard `windows-2025` image. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete` under native PowerShell. The job is deliberately absent from `all-checks-passed.needs`: the aggregate neither waits for it nor changes conclusion because of it, while the native job retains its own unmasked success or failure result.
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index 2c91c21118..dd0031630e 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。Node 分发文件传输采用有界重试，使停滞的下载在耗尽作业超时前失败或恢复。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
+[ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。Node 分发文件传输采用有界重试；nodejs.org 的大文件传输停滞时，由支持范围请求的传输镜像续传相同字节，但版本和 SHA-256 权威仍属于 nodejs.org，归档通过该校验前绝不会投入使用。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
 
 每个拉取请求还会在 GitHub 标准 `windows-2025` 镜像上启动一个独立的 `windows-native` 作业，名称为 `windows node 24 / native complete`。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并在原生 PowerShell 下运行 `pnpm run check:ci:windows-complete`。该作业被刻意排除在 `all-checks-passed.needs` 之外：聚合流程既不等待它，也不会因它改变结论；原生作业则保留自身未被掩盖的成功或失败结果。
 
diff --git a/scripts/wine-windows-gates.sh b/scripts/wine-windows-gates.sh
index 34e58274ce..5e46b75f91 100755
--- a/scripts/wine-windows-gates.sh
+++ b/scripts/wine-windows-gates.sh
@@ -77,22 +77,32 @@ mkdir -p "$cache_dir" "$scratch/logs"
 curl_metadata_args=(
   --fail --silent --show-error --location
   --retry 3 --retry-all-errors --retry-delay 2
-  --connect-timeout 10 --max-time 30 --retry-max-time 120
+  --http1.1 --connect-timeout 10 --max-time 30 --retry-max-time 120
 )
 
 download_node_archive() {
-  local url="$1" output="$2" attempt status=0
+  local version="$1" output="$2" attempt status=0
+  local archive="node-$version-win-x64.zip"
+  local primary_url="https://nodejs.org/dist/$version/$archive"
+  local mirror_url="https://npmmirror.com/mirrors/node/$version/$archive"
+
+  if curl --fail --silent --show-error --location --http1.1 \
+    --connect-timeout 10 --max-time 300 --speed-limit 1024 --speed-time 30 \
+    -o "$output" "$primary_url"; then
+    return 0
+  fi
+  echo 'wine-windows-gates: nodejs.org archive transfer stalled; resuming from the checksum-untrusted transport mirror' >&2
   for attempt in 1 2 3; do
-    if curl --fail --silent --show-error --location \
+    if curl --fail --silent --show-error --location --http1.1 \
       --continue-at - --connect-timeout 10 --max-time 300 \
       --speed-limit 1024 --speed-time 30 \
-      -o "$output" "$url"; then
+      -o "$output" "$mirror_url"; then
       return 0
     else
       status=$?
     fi
     (( attempt < 3 )) || break
-    echo "wine-windows-gates: Windows Node archive transfer failed (exit $status) on attempt $attempt; resuming partial download" >&2
+    echo "wine-windows-gates: mirror transfer failed (exit $status) on attempt $attempt; resuming partial download" >&2
   done
   return "$status"
 }
@@ -109,7 +119,7 @@ provision_node() {
   if [ -n "$version" ]; then
     zip="$cache_dir/node-$version-win-x64.zip"
     if [ ! -f "$zip" ]; then
-      download_node_archive "https://nodejs.org/dist/$version/node-$version-win-x64.zip" "$zip.tmp"
+      download_node_archive "$version" "$zip.tmp"
       local expected
       expected="$(curl "${curl_metadata_args[@]}" "https://nodejs.org/dist/$version/SHASUMS256.txt" \
         | awk -v a="node-$version-win-x64.zip" '$2 == a { print $1; exit }')"

From fcbc97a88dd7f22aa5f71342d19248485e7cc58f Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:08:37 +0800
Subject: [PATCH 499/516] fix(client): address conversation assembly review

---
 packages/client/runtime/README.i18n.yaml      |  4 +-
 packages/client/runtime/README.md             |  2 +-
 packages/client/runtime/README.zh.md          |  2 +-
 .../src/client/conversation-nodes/inbox.ts    |  4 +-
 .../src/client/conversation-nodes/retry.ts    |  1 +
 .../conversation-node-definitions.spec.ts     | 32 ++++++++++++
 .../client/ui-deliverables/README.i18n.yaml   |  4 +-
 packages/client/ui-deliverables/README.md     |  2 +-
 packages/client/ui-deliverables/README.zh.md  |  2 +-
 .../tests/produced-files.spec.tsx             | 52 ++++++++++++++++++-
 packages/compact/compact/src/types.ts         |  4 +-
 packages/llm/llm-retry/src/types.ts           |  4 +-
 .../llm/llm-retry/tests/invariant.spec.ts     |  2 +-
 .../llm/llm-retry/tests/persistence.spec.ts   |  2 +-
 .../context-breakdown-projection.spec.ts      |  2 +-
 .../tests/token-usage-projection.spec.ts      |  2 +-
 .../llm-replay/tests/llm-replay.spec.ts       |  2 +-
 tsconfig.base.json                            |  1 +
 vitest.config.ts                              |  1 -
 19 files changed, 102 insertions(+), 23 deletions(-)

diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 139474af19..734b158e66 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: df3689176cf059f46004fa7ecb31ab7c326ea0bc
-README.zh.md: 9afe9773ff2a6a320bdf66978877678428c46118
+README.md: d4031c2e3b7730bdb0075ac84c50ad3e46ce63a2
+README.zh.md: ca6ac9f5e8efec3472c03b044739a9221e98183c
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index df3689176c..d4031c2e3b 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -58,7 +58,7 @@ Every `ToolCallBlock` recursively owns its children through `subCalls`, in start
 
 ## Model retry projection
 
-The Session object validates plugin-owned, provider-routed `llm/retry` payloads at the event wire boundary against the producer's complete field contract, including timer, integer, status, provider-delay, and non-empty diagnostic bounds. A valid event removes the matching failed step's streaming partial and inserts a durable retry notice at the event's sequence position. The notice is `scheduled` until a following retry turn starts; an aborted or disposed source turn marks it `cancelled`, while the retry turn marks it `started`. Normal-mode notices carry their finite maximum; always-mode notices remain explicitly unbounded. A terminal `turn/end` error without a retry projects one `turn-error` node from its durable message and optional code; AUTH projections replace provider copy that may echo credential fragments with `API key is invalid`, while the raw diagnostic remains in the session log. A retried failure keeps only the retry notice for that attempt. Window rebuild and history replay apply the same projection, so refresh neither resurrects discarded chunks nor loses terminal failure feedback. Visible unfinalized output is frozen as an interrupted assistant node beside the terminal error.
+The Host-owned LLM retry invariant validates provider-routed `llm/retry` and `llm/retry-started` records at the durable append boundary, including their identity, ordering, timer, integer, status, provider-delay, and non-empty diagnostic contracts. In the client, the Retry, Assistant, and Turn Error Definitions fold those records with Assistant and Turn/Step events: a failed step's streaming partial is removed and a durable retry notice appears at the retry event's sequence position. The notice is `scheduled` until the matching started record arrives; closing its owning Step or Turn first marks it `cancelled`, while the started record marks it `started`. Normal-mode notices carry their finite maximum; always-mode notices remain explicitly unbounded. A terminal `turn/end` error without a retry projects one `turn-error` node from its durable message and optional code; AUTH projections replace provider copy that may echo credential fragments with `API key is invalid`, while the raw diagnostic remains in the session log. A retried failure keeps only the retry notice for that attempt. Window rebuild and history replay use the same Definitions, so refresh neither resurrects discarded chunks nor loses terminal failure feedback. Visible unfinalized output is frozen as an interrupted Assistant node beside the terminal error.
 
 ## Session forking
 
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index 9afe9773ff..ca6ac9f5e8 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -58,7 +58,7 @@ Chat builder 为每个 Session 保留一个 mutable keyed store。内容更新
 
 ## 模型重试投影
 
-Session 对象会在事件 wire 边界依据生产方的完整字段约定，验证由插件负责、按提供方路由的 `llm/retry` 载荷，包括计时器、整数、状态、提供方延迟和非空诊断字段的边界。有效事件会移除对应失败步骤的流式输出片段，并在该事件的序列位置插入一条持久的重试提示。该提示在后续重试轮次开始前为 `scheduled`；源轮次中止或被 dispose 时，会将该提示标记为 `cancelled`，重试轮次则会将其标记为 `started`。normal mode 提示携带其有限上限；always mode 提示则保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败则只保留该次尝试的重试提示。窗口重建与历史回放应用相同的投影，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 assistant 节点。
+Host 所属的 LLM retry invariant 会在持久追加边界验证按提供方路由的 `llm/retry` 与 `llm/retry-started` 记录，包括标识、顺序、计时器、整数、状态、提供方延迟和非空诊断字段约定。客户端的 Retry、Assistant 与 Turn Error Definition 把这些记录和 Assistant、Turn／Step 事件一起折叠：失败步骤的流式输出片段会被移除，并在 retry 事件的序列位置插入一条持久重试提示。该提示在匹配的 started 记录到达前为 `scheduled`；如果所属 Step 或 Turn 先关闭，则标记为 `cancelled`，started 记录到达后则标记为 `started`。normal mode 提示携带其有限上限；always mode 提示保持显式无界。没有重试的终态 `turn/end` 错误会从持久消息与可选错误码投影出一个 `turn-error` 节点；AUTH 投影会把可能回显凭据片段的提供方文案替换为 `API key is invalid`，原始诊断仍保留在会话日志中。进入重试的失败只保留该次尝试的重试提示。窗口重建与历史回放使用同一组 Definition，因此刷新既不会让已丢弃的分片重新出现，也不会丢失终态失败反馈。可见但尚未定稿的输出会在终态错误旁冻结为中断的 Assistant 节点。
 
 ## 会话 fork
 
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
index 74406c324a..e3cfae47f4 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
@@ -2,9 +2,7 @@ import type { Context } from 'cordis'
 import type {
   ConversationNodeDefinition, ConversationPreviousContext,
 } from '@deepseek-ai/dsh-client-runtime/client'
-import type {} from '@deepseek-ai/dsh-agent/types'
-
-type InboxTarget = 'next-turn' | 'next-step'
+import type { InboxTarget } from '@deepseek-ai/dsh-agent/types'
 
 interface InboxIdentity {
   readonly id: string
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
index f383bc46d8..fa7c2ee5cf 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
@@ -31,6 +31,7 @@ function scheduledNode(match: Parameters<ConversationNodeDefinition['start']>[1]
   }
 }
 
+/** A scheduled attempt is cancelled once either owning boundary closes. */
 function isClosed(location: ConversationLocation): boolean {
   return (location.kind === 'step' && location.step.status === 'closed')
     || ((location.kind === 'step' || location.kind === 'turn') && location.turn.status === 'closed')
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
index 3e5dcccff3..d90093b864 100644
--- a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -465,6 +465,38 @@ describe('built-in conversation node Definitions', () => {
     expect(node(snapshot(value), 'user')).toBeUndefined()
   })
 
+  it('orders claimed steering after the finalized Turn tail', () => {
+    const steering = textMessage('steer-after-answer', 'change direction')
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'step/start', { turn: 1, step: 1 }),
+      at(3, 'assistant/message', {
+        turn: 1,
+        step: 1,
+        message: assistantMessage('assistant-before-steering', 'initial answer'),
+      }, { surfaceOp: 'append' }),
+      at(4, 'agent/inbox/spliced', {
+        target: 'next-step',
+        start: 0,
+        inserted: [steering],
+      }),
+      at(5, 'agent/inbox/spliced', {
+        target: 'next-step',
+        start: 0,
+        removedCount: 1,
+        inserted: [],
+      }),
+      at(6, 'user/message', steering, { surfaceOp: 'append' }),
+      at(7, 'step/end', { turn: 1, step: 1 }),
+      at(8, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+    ])
+
+    const current = snapshot(value)
+    const steeringNode = node(current, 'steering')
+    expect(steeringNode).toBeDefined()
+    expect(current.locations.getTurn(1).at(-1)).toBe(steeringNode?.key)
+  })
+
   it('classifies appended producer context from durable source metadata', () => {
     const value = assembler([
       at(1, 'user/message', {
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index e9810d98da..0df3ca0d86 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/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/client/ui-deliverables/README.md
-README.md: 189dedd88fed6914012204118ccdf9bdd0cd3bb2
-README.zh.md: ba493549bd0bc3f8a2adbda5989448e497f0af93
+README.md: 7d03e5faedda3ba8c9cc4cab6ca134d98dc7ec13
+README.zh.md: dfbbc7a39aa94aab438119a4f23ffb02da2daa3d
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index 189dedd88f..7d03e5faed 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Produced-files feature owner: registers the deliverables row a finished turn ends with into the chat view's `conversation.chat.turnTail` hole. All policy lives here; removing this plugin's line from cordis.yml removes the surface entirely, and the owning view renders an empty hole at zero cost.
 
-`producedForClosing` derives one turn's produced files from the tail hole's owner currency — the finalized snapshot nodes and the closing assistant's seq. The vocabulary is the mutation tools' own follow-along `locations`, never the closing prose: a produced file is listed whether or not the model remembered to name it. A mutation is recognized by render intent, not tool name — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a new mutation tool joins by declaring what it does. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row.
+`deliverablesDefinition` folds each Turn's successful mutation calls into engine-published `DeliverablesTurnData`; `producedForClosing` reads that data with the closing Assistant seq. The vocabulary is the mutation tools' own follow-along `locations`, never the closing prose: a produced file is listed whether or not the model remembered to name it. A mutation is recognized by render intent, not tool name — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a new mutation tool joins by declaring what it does. Reads, deletes, and failed calls contribute nothing; a path appears once per Turn in first-seen order. The Conversation Location index owns Turn membership, so a Turn that mutates and then ends without content text cannot spill into the next Turn's row.
 
 `ProducedFiles` renders the row between the closing message's body and its IconActions footer: a quiet label, up to six chips (basename text, full path as the `title`), and an explicit remainder count past the cap. Each chip opens through the owner-supplied `openFile` — the same Host opener the tool rows use, with the chat view resolving relative paths against the session cwd. Design rationale: the [workspace file links Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md).
 
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index ba493549bd..dfbbc7a39a 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -4,7 +4,7 @@
 
 产出文件功能的属主：把已完成轮次末尾的产出文件行注册到 chat 视图的 `conversation.chat.turnTail` slot 中。全部策略都在本包内；从 cordis.yml 中删去本插件那一行即可整体移除该界面，属主视图无需额外开销即可渲染空 slot。
 
-`producedForClosing` 根据 tail slot 属主提供的当前数据，即定稿快照节点和收尾助手的 seq，推导一个轮次产出的文件。依据的是修改工具自身附带的 `locations`，而不是收尾正文：无论模型是否记得点名，产出文件都会被列出。修改操作按渲染意图而非工具名识别：diff 卡片，或 `kind` 为 `edit` 的通用卡片（即 `str_replace_editor` 的 insert 操作所呈现的形态）；因此新的修改工具只需声明自身行为即可加入。读取、删除和失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在轮次边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。
+`deliverablesDefinition` 把每个 Turn 中成功的修改调用折叠进引擎发布的 `DeliverablesTurnData`；`producedForClosing` 结合收尾 Assistant 的 seq 读取这份数据。依据的是修改工具自身附带的 `locations`，而不是收尾正文：无论模型是否记得点名，产出文件都会被列出。修改操作按渲染意图而非工具名识别：diff 卡片，或 `kind` 为 `edit` 的通用卡片（即 `str_replace_editor` 的 insert 操作所呈现的形态）；因此新的修改工具只需声明自身行为即可加入。读取、删除和失败的调用不贡献任何条目；同一路径在一个 Turn 内按首见顺序只出现一次。Conversation Location 索引拥有 Turn 成员关系，因此一个 Turn 即使先修改文件、随后没有正文内容就结束，也不会溢进下一个 Turn 的行里。
 
 `ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个低调的标签、至多六个标签项（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每个标签项经由属主提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
 
diff --git a/packages/client/ui-deliverables/tests/produced-files.spec.tsx b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
index b8e7cd111e..91b15cf361 100644
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 /**
  * ui-deliverables browser half: the derivation contract of
- * `producedForClosing` over finalized snapshot nodes, the row's rendering
+ * `producedForClosing` over engine-published Turn data, the row's rendering
  * and opener wiring, and the plugin registrations' fiber-teardown removal
  * (HMR safety) against the real SlotsService.
  */
@@ -12,7 +12,7 @@ import {
   ConversationEventRegistry, ConversationNodeAssembler, SlotsService,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
-  ConversationEventInput, ConversationLocationDataStore, ConversationNodeDefinition,
+  ConversationEventInput, ConversationLocationDataStore, ConversationMatch, ConversationNodeDefinition,
   ConversationTimelineSnapshot, ConversationTurnDataMap, ConversationViewDefinition,
   ConversationViewNode, ToolResultNode, TurnLocation,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -107,6 +107,10 @@ function at(
   }
 }
 
+function matched(input: ConversationEventInput, role: ConversationMatch['role']): ConversationMatch {
+  return { ...input, role, location: { kind: 'unresolved' } }
+}
+
 function call(
   seq: number,
   callId: string,
@@ -190,6 +194,50 @@ describe('produced-file Turn data', () => {
     ])
   })
 
+  it('ignores calls without mutation locations, orphan results, and replacement results', () => {
+    const replacement = result(8, 'replacement')
+    const value = assembler([
+      at(1, 'turn/start', { turn: 1 }),
+      at(2, 'tool/call', { turn: 1, step: 1, callId: 'no-view', name: 'fixture', arguments: '{}' }),
+      result(3, 'no-view'),
+      call(4, 'locationless-edit', { card: 'generic', title: 'Edit', kind: 'edit' }),
+      result(5, 'locationless-edit'),
+      result(6, 'orphan'),
+      call(7, 'replacement', diff('replaced.txt')),
+      {
+        ...replacement,
+        event: {
+          ...replacement.event,
+          surfaceOp: { op: 'replace', start: 1, end: 1 },
+        } as ConversationEventInput['event'],
+      },
+      at(9, 'turn/end', { turn: 1, reason: { kind: 'completed' } }),
+    ])
+
+    expect(producedForClosing(deliverablesOf(value))).toEqual([])
+  })
+
+  it('rejects an invalid start match and preserves state for an unrelated update', () => {
+    const startMatch = matched(at(1, 'turn/start', { turn: 1 }), 'start')
+    const emptyContext: Parameters<typeof deliverablesDefinition.start>[0] = {
+      key: 'deliverables:1',
+      kind: 'deliverables',
+      id: '1',
+      matches: [startMatch],
+      start: startMatch,
+      state: undefined,
+      current: new Map(),
+    }
+    const reader: Parameters<typeof deliverablesDefinition.start>[2] = { previous: () => undefined }
+    const state = deliverablesDefinition.start(emptyContext, startMatch, reader)
+    const unrelated = matched(at(2, 'turn/end', { turn: 1, reason: { kind: 'completed' } }), 'update')
+    const context: Parameters<typeof deliverablesDefinition.update>[0] = { ...emptyContext, state }
+
+    expect(() => deliverablesDefinition.start(emptyContext, unrelated, reader))
+      .toThrow('deliverables start requires turn/start')
+    expect(deliverablesDefinition.update(context, unrelated)).toBe(state)
+  })
+
   it('replays a tail page once prepend supplies its missing Turn start', () => {
     const value = assembler([
       call(10, 'late', diff('history.txt')),
diff --git a/packages/compact/compact/src/types.ts b/packages/compact/compact/src/types.ts
index 53c3baf05f..2cee6c191a 100644
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -9,9 +9,9 @@
 
 import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-import { CompactionId } from './brand.ts'
+import type { CompactionId } from './brand.ts'
 
-export { CompactionId }
+export type { CompactionId }
 
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
diff --git a/packages/llm/llm-retry/src/types.ts b/packages/llm/llm-retry/src/types.ts
index 5144939289..e78026cbeb 100644
--- a/packages/llm/llm-retry/src/types.ts
+++ b/packages/llm/llm-retry/src/types.ts
@@ -1,7 +1,7 @@
 import type { LlmFailure } from '@deepseek-ai/dsh-llm/types'
-import { RetryId } from './brand.ts'
+import type { RetryId } from './brand.ts'
 
-export { RetryId }
+export type { RetryId }
 
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
diff --git a/packages/llm/llm-retry/tests/invariant.spec.ts b/packages/llm/llm-retry/tests/invariant.spec.ts
index 917a6d03f8..dd22e11369 100644
--- a/packages/llm/llm-retry/tests/invariant.spec.ts
+++ b/packages/llm/llm-retry/tests/invariant.spec.ts
@@ -5,7 +5,7 @@ import { createUserMessage, ProviderRequestId } from '@deepseek-ai/dsh-llm'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as RetryInvariant from '@deepseek-ai/dsh-llm-retry/invariant'
-import { RetryId } from '@deepseek-ai/dsh-llm-retry/types'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry'
 import { providerForOpenStep } from '../src/history.ts'
 
 async function setup(): Promise<Context> {
diff --git a/packages/llm/llm-retry/tests/persistence.spec.ts b/packages/llm/llm-retry/tests/persistence.spec.ts
index 9e17290b43..8affb9e059 100644
--- a/packages/llm/llm-retry/tests/persistence.spec.ts
+++ b/packages/llm/llm-retry/tests/persistence.spec.ts
@@ -6,7 +6,7 @@ import { Context } from 'cordis'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import SessionPersistenceSqlite from '@deepseek-ai/dsh-session-persistence-sqlite'
-import { RetryId } from '@deepseek-ai/dsh-llm-retry/types'
+import { RetryId } from '@deepseek-ai/dsh-llm-retry'
 import type {} from '../src/index.ts'
 
 const dirs: string[] = []
diff --git a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
index bfbf6a89ee..9bdd1222f0 100644
--- a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
+++ b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts
@@ -10,7 +10,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextBreakdownProjection } from '@deepseek-ai/dsh-token-meter/client'
-import { CompactionId } from '@deepseek-ai/dsh-compact/types'
+import { CompactionId } from '@deepseek-ai/dsh-compact'
 import { contextBreakdownProjectionDefinition } from '../src/breakdown-projection.ts'
 import {
   estimateContent,
diff --git a/packages/llm/token-meter/tests/token-usage-projection.spec.ts b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
index 3f66e0564b..9ccc2d7e9b 100644
--- a/packages/llm/token-meter/tests/token-usage-projection.spec.ts
+++ b/packages/llm/token-meter/tests/token-usage-projection.spec.ts
@@ -7,7 +7,7 @@ import type { Session } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { ContextPressureProjection, TokenUsageProjection } from '@deepseek-ai/dsh-token-meter/client'
-import { CompactionId } from '@deepseek-ai/dsh-compact/types'
+import { CompactionId } from '@deepseek-ai/dsh-compact'
 
 const ZERO: TokenUsageProjection = {
   uncachedInputTokens: 0,
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index db60b695b1..f9aa66bce5 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -4,7 +4,7 @@ import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { CompactionId } from '@deepseek-ai/dsh-compact/types'
+import { CompactionId } from '@deepseek-ai/dsh-compact'
 import LlmService, { CallId, createUserMessage, GenerateOptions, LlmAdapter, StreamChunk } from '@deepseek-ai/dsh-llm'
 import {
   type ReplayEntry,
diff --git a/tsconfig.base.json b/tsconfig.base.json
index c7be2d4925..e404e3fc8b 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -79,6 +79,7 @@
       "@deepseek-ai/dsh-tool-subagent-control/list-agents": ["./packages/subagent/tool-subagent-control/src/list-agents.ts"],
       "@deepseek-ai/dsh-user-approval/types": ["./packages/interaction/user-approval/src/types.ts"],
       "@deepseek-ai/dsh-user-interaction/types": ["./packages/interaction/user-interaction/src/types.ts"],
+      "@deepseek-ai/dsh-agent/types": ["./packages/core/agent/src/types.ts"],
       "@deepseek-ai/dsh-agent/brand": ["./packages/core/agent/src/brand.ts"],
       "@deepseek-ai/dsh-agent/invariant": ["./packages/core/agent/src/invariant.ts"],
       "@deepseek-ai/dsh-scope/invariant": ["./packages/core/scope/src/invariant.ts"],
diff --git a/vitest.config.ts b/vitest.config.ts
index 33512f4898..e07ae43ec3 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -211,7 +211,6 @@ export default defineConfig({
         'packages/client/ui-workspace/src/client/index.ts',
         'packages/client/test-runtime/src/translate.ts',
         'packages/client/ui-primitives/src/JsonTree.tsx',
-        'packages/client/ui-deliverables/src/client/turn-deliverables.ts',
         // Typert generator: correctness is pinned by its fixture suites and
         // the byte-for-byte catalog reproduction test; per-file coverage
         // would put whole-workspace compiler analysis under v8

From 0cfe852c2d4f0893a7d77326995513916c79a872 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:21:49 +0800
Subject: [PATCH 500/516] fix(ui-conversation): ignore legacy compact events
 without ids

---
 .../client/conversation-nodes/compaction.ts   |  4 +++-
 .../conversation-node-definitions.spec.ts     | 20 +++++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
index 04eace8038..d21b4aa4b4 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/compaction.ts
@@ -39,7 +39,9 @@ export const compactionDefinition: ConversationNodeDefinition<CompactionState> =
       || event.type === 'compact/summary'
       || event.type === 'compact/end') {
       if (event.data.sourceCommandId !== undefined) return null
-      return { id: String(event.data.compactionId), role: event.type === 'compact/start' ? 'start' : 'update' }
+      const compactionId: unknown = event.data.compactionId
+      if (typeof compactionId !== 'string' || compactionId === '') return null
+      return { id: compactionId, role: event.type === 'compact/start' ? 'start' : 'update' }
     }
     return null
   },
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
index d90093b864..016c7176db 100644
--- a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -698,6 +698,26 @@ describe('built-in conversation node Definitions', () => {
     })
   })
 
+  it('ignores legacy compaction transactions without correlation ids', () => {
+    const value = assembler([
+      at(10, 'compact/start', { turn: null }),
+      at(11, 'compact/end', { turn: null, error: 'This operation was aborted' }),
+      at(20, 'compact/start', { turn: null }),
+      at(21, 'compact/summary', {
+        summary: [{ type: 'text', text: 'legacy summary' }],
+        shadowedSeqs: [1, 2, 3],
+        shadowedTokenCount: 42,
+      }),
+      at(22, 'user/message', {
+        ...textMessage('legacy-checkpoint', 'checkpoint'),
+        source: { kind: 'plugin', plugin: 'compact' },
+      }, { surfaceOp: { op: 'replace', start: 1, end: 3 } }),
+      at(23, 'compact/end', { turn: null }),
+    ], true)
+
+    expect(node(snapshot(value), 'compaction')).toBeUndefined()
+  })
+
   it('suppresses a turn error when the loaded tail contains only a later retry attempt', () => {
     const value = assembler([
       at(5, 'llm/retry', {

From 81822f40762806c354f2abd489e04841653e507a Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:23:58 +0800
Subject: [PATCH 501/516] fix(ui-conversation): skip uncorrelated legacy events

---
 .../src/client/conversation-nodes/retry.ts    |  7 ++-
 .../src/client/conversation-nodes/tool.ts     |  5 ++-
 .../conversation-node-definitions.spec.ts     | 44 +++++++++++++++++++
 3 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
index fa7c2ee5cf..d504f32928 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/retry.ts
@@ -42,10 +42,13 @@ export const retryDefinition: ConversationNodeDefinition<RetryState> = {
   kind: 'model-retry',
   match: (event) => {
     if (event.type === 'llm/retry') {
-      return { id: String(event.data.retryId), role: event.data.retry === 1 ? 'start' : 'update' }
+      const retryId: unknown = event.data.retryId
+      if (typeof retryId !== 'string' || retryId === '') return null
+      return { id: retryId, role: event.data.retry === 1 ? 'start' : 'update' }
     }
     if (event.type === 'llm/retry-started') {
-      return { id: String(event.data.retryId), role: 'update' }
+      const retryId: unknown = event.data.retryId
+      return typeof retryId === 'string' && retryId !== '' ? { id: retryId, role: 'update' } : null
     }
     return null
   },
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
index dc9e996dcc..c1b8022e41 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/tool.ts
@@ -241,7 +241,10 @@ export const toolDefinition: ConversationNodeDefinition<ToolState> = {
       return { id: String(event.data.message.source.callId), role: 'update' }
     }
     if (event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch') {
-      return { id: String(event.data.rootCallId), role: 'update' }
+      const rootCallId: unknown = event.data.rootCallId
+      return typeof rootCallId === 'string' && rootCallId !== ''
+        ? { id: rootCallId, role: 'update' }
+        : null
     }
     return null
   },
diff --git a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
index 016c7176db..db9c0ccdd4 100644
--- a/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-node-definitions.spec.ts
@@ -718,6 +718,50 @@ describe('built-in conversation node Definitions', () => {
     expect(node(snapshot(value), 'compaction')).toBeUndefined()
   })
 
+  it('ignores legacy retry and code-dispatch events without correlation ids', () => {
+    const value = assembler([
+      at(10, 'llm/retry', {
+        turn: 1,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 1,
+        maxRetries: 2,
+        delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'first legacy retry' },
+      }),
+      at(11, 'llm/retry-started', { turn: 1, step: 1, retry: 1 }),
+      at(20, 'llm/retry', {
+        turn: 2,
+        step: 1,
+        provider: 'fake',
+        mode: 'normal',
+        policyKey: 'fake-normal',
+        retry: 1,
+        maxRetries: 2,
+        delayMs: 10,
+        failure: { code: 'TRANSPORT', message: 'second legacy retry' },
+      }),
+      at(30, 'tool/code-dispatch-start', {
+        parentCallId: 'root',
+        subCallId: 'child',
+        name: 'legacy-subcall',
+        arguments: {},
+      }),
+      at(31, 'tool/code-dispatch', {
+        parentCallId: 'root',
+        subCallId: 'child',
+        name: 'legacy-subcall',
+        arguments: {},
+        content: [],
+      }),
+    ], true)
+
+    expect(node(snapshot(value), 'model-retry')).toBeUndefined()
+    expect(node(snapshot(value), 'tool-call')).toBeUndefined()
+  })
+
   it('suppresses a turn error when the loaded tail contains only a later retry attempt', () => {
     const value = assembler([
       at(5, 'llm/retry', {

From d99ad2b1d05da476e93b5eaa4a58e288d4d8b179 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:36:57 +0800
Subject: [PATCH 502/516] fix conversation node review follow-ups

---
 docs/subsystems/compaction.i18n.yaml          |  4 ++--
 docs/subsystems/compaction.md                 |  7 +++---
 docs/subsystems/compaction.zh.md              |  7 +++---
 .../fixtures/workspace-context-compaction.ts  |  4 ++--
 packages/client/runtime/package.json          |  1 +
 .../src/client/sessions/steering-history.ts   |  4 +---
 .../src/client/conversation-nodes/command.ts  |  4 ++--
 packages/compact/compact/README.i18n.yaml     |  4 ++--
 packages/compact/compact/README.md            | 10 ++++----
 packages/compact/compact/README.zh.md         | 10 ++++----
 packages/compact/compact/src/checkpoint.ts    | 23 +++++++++----------
 packages/compact/compact/src/index.ts         | 13 ++++++-----
 .../tests/session-reference.spec.ts           | 15 ++++++++----
 packages/llm/llm-retry/README.i18n.yaml       |  4 ++--
 packages/llm/llm-retry/README.md              |  4 ++--
 packages/llm/llm-retry/README.zh.md           |  4 ++--
 .../tool-cordis/src/api-catalog.ts            |  2 +-
 pnpm-lock.yaml                                |  3 +++
 18 files changed, 67 insertions(+), 56 deletions(-)

diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 532750f069..5e7c6d92be 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 11ee6eae797db1c57bf2ffbb90f1f37f47b8400c
-compaction.zh.md: a560e47dbb7aa92f0757179534803bbcaaebc6ba
+compaction.md: 8325694d92aa1a3019aef8f6b0c1f99d45ad0df5
+compaction.zh.md: 9f9014b8c1c1db12abc6581fbe6ebacfac3dd6fe
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 11ee6eae79..8325694d92 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -66,7 +66,7 @@ Automatic callers state why policy is running; implementations may treat confirm
 type CompactionTrigger = 'pressure' | 'context-overflow'
 ```
 
-`CompactService` exposes `compactIfNeeded(agent, trigger, signal)` for automatic `pressure` or `context-overflow` policy, `compactNow(agent, signal)` for one useful idle-session reduction even below pressure, and `compactRegion(...)` for an explicit inclusive surface range. `compactNow()` runs as agent maintenance between turns, returns `null` without writing when no useful range exists, records a standalone `turn: null` bracket before summarization, and flushes a closed attempt before later queued prompts may derive from the new surface. Every backend marks its replacement `user/message` with `COMPACT_CHECKPOINT_SOURCE`; client and wire consumers import that value and `isCompactCheckpointSource()` from the cordis-free `@deepseek-ai/dsh-compact/checkpoint` subpath, while the package root re-exports both for host consumers. The predicate keeps checkpoint recognition independent of any one backend. Implementations must forward the supplied signal to summarization. The seam owns no pricing API: the singleton [`ctx.tokenMeter`](token-meter.md) directly owns estimation and replay, while `dsh-compact-basic` owns retention, event sequencing, routed summarization calls, and their configuration.
+`CompactService` exposes `compactIfNeeded(agent, trigger, signal)` for automatic `pressure` or `context-overflow` policy, `compactNow(agent, signal)` for one useful idle-session reduction even below pressure, and `compactRegion(...)` for an explicit inclusive surface range. `compactNow()` runs as agent maintenance between turns, returns `null` without writing when no useful range exists, records a standalone `turn: null` bracket before summarization, and flushes a closed attempt before later queued prompts may derive from the new surface. Every backend creates its replacement `user/message` source with `compactCheckpointSource(compactionId, sourceCommandId?)`; client and wire consumers import that constructor, `CompactCheckpointSource`, and `isCompactCheckpointSource()` from the cordis-free `@deepseek-ai/dsh-compact/checkpoint` subpath, while the package root re-exports them for host consumers. The required transaction identity correlates the replacement checkpoint, while the predicate keeps recognition independent of any one backend. Implementations must forward the supplied signal to summarization. The seam owns no pricing API: the singleton [`ctx.tokenMeter`](token-meter.md) directly owns estimation and replay, while `dsh-compact-basic` owns retention, event sequencing, routed summarization calls, and their configuration.
 
 Expected manual failures use `ManualCompactionErrorCode`:
 
@@ -129,7 +129,7 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.compact` — `CompactService` (abstract seam)
 
-Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
+Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses compactCheckpointSource with the transaction identity so consumers recognize and correlate it independently of the backend. Load one implementation per context as `ctx.compact`.
 
 ```ts cordis-catalog
 /**
@@ -175,7 +175,8 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sour
  * balanced so assistant tool calls remain paired with their results. A model-
  * backed implementation forwards cancellation and rejects active, missing,
  * reversed, or unbalanced ranges. The target session is `agent.session`.
- * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
+ * Its replacement user message must use {@link compactCheckpointSource} with
+ * the transaction's `CompactionId`.
  * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
  * for the edge checks.
  *
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index a560e47dbb..9f9014b8c1 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -66,7 +66,7 @@ interface CompactionResult {
 type CompactionTrigger = 'pressure' | 'context-overflow'
 ```
 
-`CompactService` 暴露 `compactIfNeeded(agent, trigger, signal)` 以执行自动 `pressure` 或 `context-overflow` 策略，暴露 `compactNow(agent, signal)` 以便即使未达到压力也对空闲会话进行一次有效缩减，还针对显式、两端均包含的 surface 范围暴露 `compactRegion(...)`。`compactNow()` 作为轮次之间的 agent maintenance 运行；没有有效范围时返回 `null` 且不写入；在摘要前记录独立的 `turn: null` 标记对，并在后续排队提示词能够从新表层派生前 flush 已闭合尝试。每个后端都使用 `COMPACT_CHECKPOINT_SOURCE` 标记其替换用的 `user/message`；client 与 wire 消费方从无 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 子路径导入该值和 `isCompactCheckpointSource()`，包根则为 host 消费方重新导出两者。该判定函数使检查点识别不依赖任一特定后端。实现必须把传入的 signal 转发给摘要流程。该 seam 不拥有计价 API：单例 [`ctx.tokenMeter`](token-meter.md) 直接拥有估算与回放，而 `dsh-compact-basic` 拥有保留策略、事件排序、按路由执行的摘要调用及其配置。
+`CompactService` 暴露 `compactIfNeeded(agent, trigger, signal)` 以执行自动 `pressure` 或 `context-overflow` 策略，暴露 `compactNow(agent, signal)` 以便即使未达到压力也对空闲会话进行一次有效缩减，还针对显式、两端均包含的 surface 范围暴露 `compactRegion(...)`。`compactNow()` 作为轮次之间的 agent maintenance 运行；没有有效范围时返回 `null` 且不写入；在摘要前记录独立的 `turn: null` 标记对，并在后续排队提示词能够从新表层派生前 flush 已闭合尝试。每个后端都使用 `compactCheckpointSource(compactionId, sourceCommandId?)` 创建替换用 `user/message` 的源；client 与 wire 消费方从无 cordis 的 `@deepseek-ai/dsh-compact/checkpoint` 子路径导入该构造函数、`CompactCheckpointSource` 和 `isCompactCheckpointSource()`，包根则为 host 消费方重新导出它们。必填的事务身份会关联替换检查点，而该判定函数使检查点识别不依赖任一特定后端。实现必须把传入的 signal 转发给摘要流程。该 seam 不拥有计价 API：单例 [`ctx.tokenMeter`](token-meter.md) 直接拥有估算与回放，而 `dsh-compact-basic` 拥有保留策略、事件排序、按路由执行的摘要调用及其配置。
 
 预期的手动失败使用 `ManualCompactionErrorCode`：
 
@@ -129,7 +129,7 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.compact` — `CompactService` (abstract seam)
 
-Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses COMPACT_CHECKPOINT_SOURCE so consumers recognize it independently of the backend. Load one implementation per context as `ctx.compact`.
+Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses compactCheckpointSource with the transaction identity so consumers recognize and correlate it independently of the backend. Load one implementation per context as `ctx.compact`.
 
 ```ts cordis-catalog
 /**
@@ -175,7 +175,8 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sour
  * balanced so assistant tool calls remain paired with their results. A model-
  * backed implementation forwards cancellation and rejects active, missing,
  * reversed, or unbalanced ranges. The target session is `agent.session`.
- * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
+ * Its replacement user message must use {@link compactCheckpointSource} with
+ * the transaction's `CompactionId`.
  * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
  * for the edge checks.
  *
diff --git a/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts b/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts
index e13e3cf6b3..6c1cd46fbf 100644
--- a/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts
+++ b/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts
@@ -1,6 +1,6 @@
 import type { Context } from 'cordis'
 import type {} from '@deepseek-ai/dsh-agent'
-import { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact'
+import { CompactionId, compactCheckpointSource } from '@deepseek-ai/dsh-compact'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-tools'
 
@@ -26,7 +26,7 @@ export function apply(ctx: Context): void {
     if (baseline === undefined) throw new Error('workspace baseline missing before snapshot compaction')
     agent.session.append('user/message', createUserMessage({
       content: [{ type: 'text', text: 'Earlier context was compacted for this snapshot.' }],
-      source: COMPACT_CHECKPOINT_SOURCE,
+      source: compactCheckpointSource(CompactionId('workspace-context-fixture')),
     }), {
       surfaceOp: { op: 'replace', start: baseline.seq, end: baseline.seq },
       sourceEventSeqs: [baseline.seq],
diff --git a/packages/client/runtime/package.json b/packages/client/runtime/package.json
index f5a9a06a60..83a62693cb 100644
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -35,6 +35,7 @@
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
+    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
diff --git a/packages/client/runtime/src/client/sessions/steering-history.ts b/packages/client/runtime/src/client/sessions/steering-history.ts
index 4220a769ff..a28c3376a8 100644
--- a/packages/client/runtime/src/client/sessions/steering-history.ts
+++ b/packages/client/runtime/src/client/sessions/steering-history.ts
@@ -1,9 +1,7 @@
 /** Reconstruct durable steering identity from the event-sourced agent inbox. */
 
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import type {} from '@deepseek-ai/dsh-agent/types'
-
-type InboxTarget = 'next-turn' | 'next-step'
+import type { InboxTarget } from '@deepseek-ai/dsh-agent/types'
 
 /** Minimal pending identity retained while replaying durable inbox splices. */
 interface PendingIdentity {
diff --git a/packages/client/ui-conversation/src/client/conversation-nodes/command.ts b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
index 38cb85ed87..752d7e3dd2 100644
--- a/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
+++ b/packages/client/ui-conversation/src/client/conversation-nodes/command.ts
@@ -4,7 +4,7 @@ import type {
   ConversationNodeDefinition,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-client-runtime/client'
-import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
+import type { CompactCheckpointSource } from '@deepseek-ai/dsh-compact/checkpoint'
 import type {} from '@deepseek-ai/dsh-compact/types'
 import type {} from '@deepseek-ai/dsh-commands/types'
 import type { ManualCompactionChatData } from '../contract/chat-nodes.ts'
@@ -21,7 +21,7 @@ declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
 
 type CommandId = CommandNode['commandId']
 
-const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
+const COMPACT_PLUGIN: CompactCheckpointSource['plugin'] = 'compact'
 
 interface CommandState {
   readonly command: CommandNode
diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml
index ec95ee2165..8b16ecfa4b 100644
--- a/packages/compact/compact/README.i18n.yaml
+++ b/packages/compact/compact/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/compact/compact/README.md
-README.md: 3fecc91422bcdc994bcbe4db308ee4a52cb3c53f
-README.zh.md: ea66d8bdb0684f27cf68a5431be75966041b7534
+README.md: eac4339da76352bc9468488d0828a0b90a993d48
+README.zh.md: 4aec6123169a7c88a36da647202e7462fbf94564
diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md
index 3fecc91422..eac4339da7 100644
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -8,7 +8,7 @@ This package owns the Service Definition role of the compaction capability, spli
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-compact` (this) | Service Definition: abstract service + `compact/*` events + `CompactionResult` + canonical checkpoint source + tool-pairing boundary helpers |
+| `@deepseek-ai/dsh-compact` (this) | Service Definition: abstract service + `compact/*` events + `CompactionResult` + correlated checkpoint-source constructor + tool-pairing boundary helpers |
 | `@deepseek-ai/dsh-compact-basic` | Service provider: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization |
 | `@deepseek-ai/dsh-command-compact` | Consumer: the human `/compact` command over `ctx.compact.compactNow()` |
 
@@ -22,7 +22,7 @@ All three operations are **abstract** — the backend owns trigger policy, reten
 |---|---|
 | `compactIfNeeded(agent, trigger, signal)` | Consider automatic compaction for `trigger: 'pressure' \| 'context-overflow'`. A pressure trigger may apply the backend's threshold and retained-tail policy; a confirmed overflow may force a useful balanced reduction. Returns the `CompactionResult`, or `null` when no safe range exists. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. |
 | `compactNow(agent, signal)` | Explicitly compact one useful balanced older span even below automatic pressure. It synchronously reserves idle turn admission before yielding, writes nothing when no useful span exists, records a standalone `compact/* { turn: null }` attempt before summarization, and awaits its durability checkpoint before release. Expected operational failures use `ManualCompactionError`; cancellation rethrows the exact abort reason. |
-| `compactRegion(start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) from `agent.session` into a single replacement node whose source is `COMPACT_CHECKPOINT_SOURCE`. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
+| `compactRegion(start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) from `agent.session` into a single replacement node whose source comes from `compactCheckpointSource(compactionId)`. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
 
 `CompactionResult` keeps the raw summary and bookkeeping-event seqs available to callers alongside the shadowed range and token accounting; its drift-checked shape lives in the [compaction data-structure reference](../../../docs/subsystems/compaction.md#compactionresult).
 
@@ -43,7 +43,7 @@ The private per-session cache is keyed by `session.surface.replaceGeneration` an
 1. appends `compact/start` (log-only) — acquires the lock,
 2. summarizes the range,
 3. appends `compact/summary` (log-only) with the summary, range, shadowed seqs, token count, and provider/model call envelope,
-4. appends a single `user/message` with `source: COMPACT_CHECKPOINT_SOURCE` and `surfaceOp: { op: 'replace', start, end }` carrying the summary — **the only surface mutation in this operation**,
+4. appends a single `user/message` with `source: compactCheckpointSource(compactionId, sourceCommandId?)` and `surfaceOp: { op: 'replace', start, end }` carrying the summary — **the only surface mutation in this operation**,
 5. appends `compact/end` (log-only) — releases the lock.
 
 The surface mutation (step 4) sits **inside** the lock bracket: `compact/end` is the last event, so the lock is never released before the mutation lands. A crash between `compact/start` and `compact/end` therefore leaves a detectable orphaned lock (a `compact/start` with no matching `compact/end`) rather than a `compact/end` that falsely claims compaction finished while the surface was never shadowed.
@@ -64,11 +64,11 @@ The `compact/*` events extend `SessionEventMap` (merge-extensible) via declarati
 
 ## Implementing a backend
 
-Subclass `CompactService`, implement `compactIfNeeded`, `compactNow`, and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. Every successful backend uses `COMPACT_CHECKPOINT_SOURCE` on its replacement user message; `isCompactCheckpointSource()` recognizes the marker after persistence or cloning without depending on backend identity. A template- or model-backed implementation can live as a sibling package without changing callers or the shared token meter.
+Subclass `CompactService`, implement `compactIfNeeded`, `compactNow`, and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. Every successful backend creates its replacement user message source with `compactCheckpointSource(compactionId, sourceCommandId?)`; the required `compactionId` correlates the checkpoint with its `compact/*` transaction, while `isCompactCheckpointSource()` recognizes the marker after persistence or cloning without depending on backend identity. A template- or model-backed implementation can live as a sibling package without changing callers or the shared token meter.
 
 ## Recognizing a checkpoint outside the host program (`./checkpoint`)
 
-`COMPACT_CHECKPOINT_SOURCE` and `isCompactCheckpointSource()` are declared on the `@deepseek-ai/dsh-compact/checkpoint` subpath and re-exported from the root, so host-side consumers keep reading them from the root. The leaf imports no cordis and declares no module augmentation (the [`dsh-commands/brand`](../../interaction/commands/README.md) shape), which is what lets a client or wire program name the checkpoint source: the package **root** cannot enter such a program at all, because it reaches `dsh-session`'s root and that `Context` merge declares the host `sessions` service against the client's own (`TS2717` — one program per side, per [development.md](../../../docs/development.md#typescript-project-layout)). The web client's transcript adapter pins its plugin literal to this leaf with a type-only import, so renaming the plugin id here is a compile error there.
+`compactCheckpointSource()`, `CompactCheckpointSource`, and `isCompactCheckpointSource()` are declared on the `@deepseek-ai/dsh-compact/checkpoint` subpath and re-exported from the root, so host-side consumers keep reading them from the root. The constructor requires the owning `CompactionId`, preventing backends from writing an uncorrelated marker that the package invariant must reject. The leaf imports no cordis and declares no module augmentation (the [`dsh-commands/brand`](../../interaction/commands/README.md) shape), which is what lets a client or wire program name the checkpoint source: the package **root** cannot enter such a program at all, because it reaches `dsh-session`'s root and that `Context` merge declares the host `sessions` service against the client's own (`TS2717` — one program per side, per [development.md](../../../docs/development.md#typescript-project-layout)). The web client's transcript adapter pins its plugin literal to the leaf's source type, so renaming the plugin id there is a compile error here.
 
 ## Model Experience
 
diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md
index ea66d8bdb0..4aec612316 100644
--- a/packages/compact/compact/README.zh.md
+++ b/packages/compact/compact/README.zh.md
@@ -8,7 +8,7 @@
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-compact`（本包） | Service Definition：抽象服务 + `compact/*` 事件 + `CompactionResult` + 规范检查点源 + 工具配对边界 helper |
+| `@deepseek-ai/dsh-compact`（本包） | Service Definition：抽象服务 + `compact/*` 事件 + `CompactionResult` + 关联检查点源构造函数 + 工具配对边界 helper |
 | `@deepseek-ai/dsh-compact-basic` | Service provider：`ctx.tokenMeter` 压力 + token 预算保留 + `llm.stream()` 摘要 |
 | `@deepseek-ai/dsh-command-compact` | Consumer：面向人类的 `/compact` 命令，基于 `ctx.compact.compactNow()` 实现 |
 
@@ -22,7 +22,7 @@
 |---|---|
 | `compactIfNeeded(agent, trigger, signal)` | 根据 `trigger: 'pressure' \| 'context-overflow'` 判断是否需要自动压缩。压力触发可应用后端的阈值与保留尾部策略；已确认溢出可强制进行有效的平衡缩减。返回 `CompactionResult`，无安全范围时则返回 `null`。后端摘要请求是直接的 `ctx.llm.stream()` 调用（不是 agent loop 步骤），因此每次调用都可在 `llm/stream` 处拦截。 |
 | `compactNow(agent, signal)` | 即使未达到自动压力，也显式压缩一段有效、平衡的较早范围。该操作会在让出控制权前同步预留空闲轮次接纳；没有有效范围时不写入任何内容；在摘要前记录独立的 `compact/* { turn: null }` 尝试；释放预留前等待其持久性检查点。预期操作失败使用 `ManualCompactionError`；取消会原样重新抛出 abort 原因。 |
-| `compactRegion(start, end, agent, signal?)` | 强制将表层节点 `[start, end]`（包含两端 seq）从 `agent.session` 摘要为单个替换节点，其源为 `COMPACT_CHECKPOINT_SOURCE`。如果压缩已在进行、`start`／`end` 不是表层节点，或 `start` 在表层上位于 `end` 之后，则**抛出异常**。该范围是表层位置范围，不是数值 seq 区间：在之前的 replace 将新生成的高 seq 摘要节点放到已遮蔽范围的位置之后，表层顺序不再跟随 seq 顺序。 |
+| `compactRegion(start, end, agent, signal?)` | 强制将表层节点 `[start, end]`（包含两端 seq）从 `agent.session` 摘要为单个替换节点，其源由 `compactCheckpointSource(compactionId)` 创建。如果压缩已在进行、`start`／`end` 不是表层节点，或 `start` 在表层上位于 `end` 之后，则**抛出异常**。该范围是表层位置范围，不是数值 seq 区间：在之前的 replace 将新生成的高 seq 摘要节点放到已遮蔽范围的位置之后，表层顺序不再跟随 seq 顺序。 |
 
 `CompactionResult` 向调用方保留原始摘要与记录操作过程的事件 seq，同时保留已遮蔽范围与 token 计量；其结构由漂移检查保障，定义见 [压缩数据结构参考](../../../docs/subsystems/compaction.md#compactionresult)。
 
@@ -43,7 +43,7 @@
 1. 追加 `compact/start`（仅日志）：获取锁；
 2. 摘要该范围；
 3. 追加 `compact/summary`（仅日志），其中记录摘要、范围、已遮蔽 seq、token 数与提供方／模型调用 envelope；
-4. 追加单个 `user/message`，其携带 `source: COMPACT_CHECKPOINT_SOURCE` 和包含摘要的 `surfaceOp: { op: 'replace', start, end }`：这是**本操作唯一的表层变更**；
+4. 追加单个 `user/message`，其携带 `source: compactCheckpointSource(compactionId, sourceCommandId?)` 和包含摘要的 `surfaceOp: { op: 'replace', start, end }`：这是**本操作唯一的表层变更**；
 5. 追加 `compact/end`（仅日志）：释放锁。
 
 表层变更（第 4 步）位于锁的起止范围**内**：`compact/end` 是最后一个事件，因此表层变更落地前绝不会释放锁。如果在 `compact/start` 与 `compact/end` 之间崩溃，会留下可检测的遗留锁（一个 `compact/start` 没有匹配的 `compact/end`），而不是虚假声称压缩已完成、但表层从未被遮蔽的 `compact/end`。
@@ -64,11 +64,11 @@
 
 ## 实现后端
 
-继承 `CompactService`，实现 `compactIfNeeded`、`compactNow` 与 `compactRegion`，再将子类作为插件加载：它会注册为 `ctx.compact`。每个成功后端都在替换 user 消息上使用 `COMPACT_CHECKPOINT_SOURCE`；`isCompactCheckpointSource()` 可在持久化或克隆后识别该标记，无需依赖后端身份。基于模板或模型的实现可以放在同级包中，不需更改调用方或共享 token meter。
+继承 `CompactService`，实现 `compactIfNeeded`、`compactNow` 与 `compactRegion`，再将子类作为插件加载：它会注册为 `ctx.compact`。每个成功后端都使用 `compactCheckpointSource(compactionId, sourceCommandId?)` 创建替换 user 消息的源；必填的 `compactionId` 将检查点与对应 `compact/*` 事务关联，而 `isCompactCheckpointSource()` 可在持久化或克隆后识别该标记，无需依赖后端身份。基于模板或模型的实现可以放在同级包中，不需更改调用方或共享 token meter。
 
 ## 在 host 程序之外识别检查点（`./checkpoint`）
 
-`COMPACT_CHECKPOINT_SOURCE` 与 `isCompactCheckpointSource()` 声明在 `@deepseek-ai/dsh-compact/checkpoint` 子路径上，并由包根重新导出，因此 host 侧消费方仍从根读取它们。该叶子不导入 cordis、也不声明任何模块增强（即 [`dsh-commands/brand`](../../interaction/commands/README.md) 的形状），这正是客户端或 wire 程序能够命名该检查点来源的原因：包的**根**根本无法进入这类程序，因为它会到达 `dsh-session` 的根，而那处 `Context` 合并会让 host 的 `sessions` 服务与客户端自己的冲突（`TS2717`——每侧一个程序，见 [development.md](../../../docs/development.md#typescript-project-layout)）。Web 客户端的对话记录适配器用仅类型导入把它的插件字面量钉在该叶子上，因此在此处改插件 id 会让那边编译失败。
+`compactCheckpointSource()`、`CompactCheckpointSource` 与 `isCompactCheckpointSource()` 声明在 `@deepseek-ai/dsh-compact/checkpoint` 子路径上，并由包根重新导出，因此 host 侧消费方仍从根读取它们。构造函数要求传入所属 `CompactionId`，防止后端写入缺少关联关系、必然被包不变量拒绝的标记。该叶子不导入 cordis、也不声明任何模块增强（即 [`dsh-commands/brand`](../../interaction/commands/README.md) 的形状），这正是客户端或 wire 程序能够命名该检查点来源的原因：包的**根**根本无法进入这类程序，因为它会到达 `dsh-session` 的根，而那处 `Context` 合并会让 host 的 `sessions` 服务与客户端自己的冲突（`TS2717`——每侧一个程序，见 [development.md](../../../docs/development.md#typescript-project-layout)）。Web 客户端的对话记录适配器用仅类型导入把它的插件字面量钉在该叶子的源类型上，因此在此处改插件 id 会让那边编译失败。
 
 ## 模型体验
 
diff --git a/packages/compact/compact/src/checkpoint.ts b/packages/compact/compact/src/checkpoint.ts
index 9908fe4ac0..18a2c5985e 100644
--- a/packages/compact/compact/src/checkpoint.ts
+++ b/packages/compact/compact/src/checkpoint.ts
@@ -1,12 +1,12 @@
 /**
- * The compaction seam's canonical checkpoint source: the plugin marker every
- * backend stamps on the replacement user message that lands a checkpoint, plus
- * the predicate that recognizes it.
+ * Compaction checkpoint provenance: the correlated source constructor and type
+ * every backend uses for its replacement user message, plus the predicate that
+ * recognizes persisted checkpoints.
  *
- * The seam itself lives in `@deepseek-ai/dsh-compact`, which re-exports both of
- * these; this module is a pure value/predicate outlet (no cordis imports, no
- * module augmentation) so client and wire programs can name the checkpoint
- * source without loading the host plugin's Context merges — the
+ * The seam itself lives in `@deepseek-ai/dsh-compact`, which re-exports these
+ * contracts; this module is a pure type/value/predicate outlet (no cordis
+ * imports, no module augmentation) so client and wire programs can name the
+ * checkpoint source without loading the host plugin's Context merges — the
  * `dsh-commands/brand` shape.
  *
  * @module @deepseek-ai/dsh-compact/checkpoint
@@ -16,11 +16,10 @@ import type { MessageSource } from '@deepseek-ai/dsh-llm/message'
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { CompactionId } from './brand.ts'
 
-/** Canonical source for the replacement user message produced by every compaction backend. */
-export const COMPACT_CHECKPOINT_SOURCE = Object.freeze({ kind: 'plugin', plugin: 'compact' } as const)
+const COMPACT_CHECKPOINT_MARKER = Object.freeze({ kind: 'plugin', plugin: 'compact' } as const)
 
 /** Message provenance carried by a concrete compaction checkpoint. */
-export type CompactCheckpointSource = typeof COMPACT_CHECKPOINT_SOURCE & {
+export type CompactCheckpointSource = typeof COMPACT_CHECKPOINT_MARKER & {
   readonly compactionId: CompactionId
   readonly sourceCommandId?: CommandId
 }
@@ -36,7 +35,7 @@ export function compactCheckpointSource(
   sourceCommandId?: CommandId,
 ): CompactCheckpointSource {
   return Object.freeze({
-    ...COMPACT_CHECKPOINT_SOURCE,
+    ...COMPACT_CHECKPOINT_MARKER,
     compactionId,
     ...sourceCommandId === undefined ? {} : { sourceCommandId },
   })
@@ -48,5 +47,5 @@ export function compactCheckpointSource(
  * @returns whether the source carries the backend-independent checkpoint marker.
  */
 export function isCompactCheckpointSource(source: MessageSource): boolean {
-  return source.kind === 'plugin' && source.plugin === COMPACT_CHECKPOINT_SOURCE.plugin
+  return source.kind === 'plugin' && source.plugin === COMPACT_CHECKPOINT_MARKER.plugin
 }
diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts
index 0085321333..6fb9706c04 100644
--- a/packages/compact/compact/src/index.ts
+++ b/packages/compact/compact/src/index.ts
@@ -15,10 +15,10 @@ import type { CompactionResult } from './types.ts'
 export type { CompactionResult } from './types.ts'
 export { CompactionId } from './brand.ts'
 export { toolPairingBalancedAfter, toolPairingBalancedBefore } from './tool-pairing.ts'
-// The checkpoint source and its predicate are declared on the cordis-free
+// The checkpoint source constructor and predicate are declared on the cordis-free
 // `./checkpoint` leaf so client and wire programs can name them without this
 // root's Context merge; the root stays the host-side entry point for both.
-export { COMPACT_CHECKPOINT_SOURCE, compactCheckpointSource, isCompactCheckpointSource } from './checkpoint.ts'
+export { compactCheckpointSource, isCompactCheckpointSource } from './checkpoint.ts'
 export type { CompactCheckpointSource } from './checkpoint.ts'
 
 /** Why automatic policy is asking a backend to consider compaction. */
@@ -89,9 +89,9 @@ declare module 'cordis' {
  * and summarization, and may consume a separate measurement service. A
  * successful run replaces the selected surface span with one summary node and
  * prevents concurrent compaction of the same session. The replacement user
- * message uses {@link COMPACT_CHECKPOINT_SOURCE} so consumers recognize it
- * independently of the backend. Load one implementation per context as
- * `ctx.compact`.
+ * message uses {@link compactCheckpointSource} with the transaction identity
+ * so consumers recognize and correlate it independently of the backend. Load
+ * one implementation per context as `ctx.compact`.
  */
 export abstract class CompactService extends Service {
   constructor(ctx: Context) {
@@ -149,7 +149,8 @@ export abstract class CompactService extends Service {
    * balanced so assistant tool calls remain paired with their results. A model-
    * backed implementation forwards cancellation and rejects active, missing,
    * reversed, or unbalanced ranges. The target session is `agent.session`.
-   * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.
+   * Its replacement user message must use {@link compactCheckpointSource} with
+   * the transaction's `CompactionId`.
    * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
    * for the edge checks.
    *
diff --git a/packages/context/session-reference/tests/session-reference.spec.ts b/packages/context/session-reference/tests/session-reference.spec.ts
index b9e5e55241..ce964af16a 100644
--- a/packages/context/session-reference/tests/session-reference.spec.ts
+++ b/packages/context/session-reference/tests/session-reference.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact'
+import { CompactionId, compactCheckpointSource } from '@deepseek-ai/dsh-compact'
 import { createUserMessage, CallId , createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
 import SessionQueryService from '@deepseek-ai/dsh-session-query'
@@ -48,6 +48,10 @@ function expectCode(code: SessionReferenceErrorCode): Error {
   return expect.objectContaining({ code }) as Error
 }
 
+function checkpointSource(id: string) {
+  return compactCheckpointSource(CompactionId(id))
+}
+
 function appendConversation(session: Session): void {
   const oldUser = session.append(
     'user/message',
@@ -75,7 +79,8 @@ function appendConversation(session: Session): void {
   session.append(
     'user/message',
     createUserMessage({
-      content: [{ type: 'text', text: '<compacted-summary>checkpoint</compacted-summary>' }], source: COMPACT_CHECKPOINT_SOURCE,
+      content: [{ type: 'text', text: '<compacted-summary>checkpoint</compacted-summary>' }],
+      source: checkpointSource('conversation'),
     }),
     {
       surfaceOp: { op: 'replace', start: oldUser.seq, end: oldAssistant.seq },
@@ -534,7 +539,8 @@ describe('session reference discovery and preparation', () => {
       source.append(
         'user/message',
         createUserMessage({
-          content: [{ type: 'text', text: `${id}-${'界'.repeat(400)}` }], source: COMPACT_CHECKPOINT_SOURCE,
+          content: [{ type: 'text', text: `${id}-${'界'.repeat(400)}` }],
+          source: checkpointSource(id),
         }),
         { surfaceOp: 'append' },
       )
@@ -616,7 +622,8 @@ describe('session reference discovery and preparation', () => {
     source.append(
       'user/message',
       createUserMessage({
-        content: [{ type: 'text', text: 'later compact checkpoint' }], source: COMPACT_CHECKPOINT_SOURCE,
+        content: [{ type: 'text', text: 'later compact checkpoint' }],
+        source: checkpointSource('later-source-mutation'),
       }),
       {
         surfaceOp: { op: 'replace', start: original.seq, end: later.seq },
diff --git a/packages/llm/llm-retry/README.i18n.yaml b/packages/llm/llm-retry/README.i18n.yaml
index 65e0c911ed..2a1f8d46a2 100644
--- a/packages/llm/llm-retry/README.i18n.yaml
+++ b/packages/llm/llm-retry/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/llm/llm-retry/README.md
-README.md: e6e56ec44032d714393c6fcc1c42d7271017a294
-README.zh.md: b7ce8bee4acd2c4f7c88870745dff96ec5695435
+README.md: 0a907b5505650f7c2cd5e9933750be3701f8e34b
+README.zh.md: bb8c5b50efddf3def0047f411285b57c3c544f95
diff --git a/packages/llm/llm-retry/README.md b/packages/llm/llm-retry/README.md
index e6e56ec440..0a907b5505 100644
--- a/packages/llm/llm-retry/README.md
+++ b/packages/llm/llm-retry/README.md
@@ -8,9 +8,9 @@ Each provider adapter owns an optional nested `retryPolicy`, captured when its r
 
 Both modes use bounded exponential backoff with symmetric jitter. A valid `providerRetryAfterMs` at or below `maxDelayMs` replaces local backoff without jitter. An over-cap provider delay makes normal mode delegate, while always mode uses its configured local backoff so it cannot terminate on that instruction.
 
-Before waiting, the plugin appends a non-surface `llm/retry` event with the provider, mode, canonical resolved-policy key, failure, and scheduled delay. Its payload is available from the browser-safe `@deepseek-ai/dsh-llm-retry/types` subpath, so remote renderers can consume the durable status without loading the policy runtime. The key includes every behavior-affecting field and sorts normal-mode codes because eligibility uses set membership. Retry numbers continue only across events with the same provider and complete policy key, so a route replacement with different limits, code membership, or backoff starts its own history. Normal events include the finite maximum; always events omit it, and UIs render `∞`. After the wait, the listener returns `{ kind: 'retry' }`, and the loop closes the failed turn and opens a retry turn over the same durable history. Cancellation and plugin disposal abort active backoff, drain active delegated recovery before applying the abort, and make a callback captured before disposal fail closed.
+Before waiting, the plugin appends a non-surface `llm/retry` event with the shared `retryId`, provider, mode, canonical resolved-policy key, failure, and scheduled delay. Its payload is available from the browser-safe `@deepseek-ai/dsh-llm-retry/types` subpath, so remote renderers can consume the durable status without loading the policy runtime. The key includes every behavior-affecting field and sorts normal-mode codes because eligibility uses set membership. Retry numbers continue only across events with the same provider and complete policy key, so a route replacement with different limits, code membership, or backoff starts its own history. Normal events include the finite maximum; always events omit it, and UIs render `∞`. When the wait completes, the plugin appends `llm/retry-started` with the same `retryId`, turn, step, and retry number immediately before returning `{ kind: 'retry' }`; cancellation during backoff writes no started event. The loop then closes the failed turn and opens a retry turn over the same durable history. Cancellation and plugin disposal abort active backoff, drain active delegated recovery before applying the abort, and make a callback captured before disposal fail closed.
 
-The separately published `./invariant` companion checks that every retry record names the current open turn and latest closed step, matches the failed request's durable provider, carries non-empty provider and policy identities, has mode-specific bounds, a unique step record, the correct provider-policy retry number, and a bounded timer delay. Full jitter may schedule zero milliseconds at its lower boundary.
+The separately published `./invariant` companion checks that every scheduled retry names the current open turn and latest closed step, matches the failed request's durable provider, carries non-empty provider and policy identities, has mode-specific bounds, a unique step record, the correct provider-policy retry number, and a bounded timer delay. It also requires each `llm/retry-started` event to name one prior scheduled attempt with the same `retryId`, turn, step, and retry number, and rejects repeated started events. Full jitter may schedule zero milliseconds at its lower boundary.
 
 ```yaml
 - name: '@deepseek-ai/dsh-llm-deepseek'
diff --git a/packages/llm/llm-retry/README.zh.md b/packages/llm/llm-retry/README.zh.md
index b7ce8bee4a..bb8c5b50ef 100644
--- a/packages/llm/llm-retry/README.zh.md
+++ b/packages/llm/llm-retry/README.zh.md
@@ -8,9 +8,9 @@
 
 两种 mode 都使用带对称 jitter 的有界指数退避。有效 `providerRetryAfterMs` 不超过 `maxDelayMs` 时会替换本地退避，并且不加 jitter。超出上限的提供方延迟会使 normal mode 继续委托；always mode 则改用已配置的本地退避，避免该指令终止重试。
 
-等待前，插件会追加一条不进入表层的 `llm/retry` 事件，其中包含提供方、mode、已解析策略的规范 key、失败和计划延迟。该载荷由可安全用于浏览器的 `@deepseek-ai/dsh-llm-retry/types` 子路径导出，因此远程渲染器无需加载策略运行时即可使用该持久状态。该 key 包含所有影响行为的字段，并对 normal mode 的 code 排序，因为合格性采用集合成员关系判断。只有提供方与完整策略 key 都相同的事件才会延续重试编号；因此，用限制、code 成员关系或退避不同的路由替换后，会开始自己的历史。normal 事件包含有限上限；always 事件省略该上限，UI 会渲染 `∞`。等待结束后，监听器返回 `{ kind: 'retry' }`，循环关闭失败轮次，并在同一持久历史上开启重试轮次。取消与插件 dispose 会中止活跃退避，在应用中止前排空活跃的委托恢复，并使 dispose 前捕获的 callback 只能以失败结束。
+等待前，插件会追加一条不进入表层的 `llm/retry` 事件，其中包含共享 `retryId`、提供方、mode、已解析策略的规范 key、失败和计划延迟。该载荷由可安全用于浏览器的 `@deepseek-ai/dsh-llm-retry/types` 子路径导出，因此远程渲染器无需加载策略运行时即可使用该持久状态。该 key 包含所有影响行为的字段，并对 normal mode 的 code 排序，因为合格性采用集合成员关系判断。只有提供方与完整策略 key 都相同的事件才会延续重试编号；因此，用限制、code 成员关系或退避不同的路由替换后，会开始自己的历史。normal 事件包含有限上限；always 事件省略该上限，UI 会渲染 `∞`。等待完成时，插件会在返回 `{ kind: 'retry' }` 前立即追加 `llm/retry-started`，其中带有相同的 `retryId`、轮次、步骤与重试编号；退避期间取消则不会写入 started 事件。随后循环关闭失败轮次，并在同一持久历史上开启重试轮次。取消与插件 dispose 会中止活跃退避，在应用中止前排空活跃的委托恢复，并使 dispose 前捕获的 callback 只能以失败结束。
 
-单独发布的 `./invariant` 配套模块会检查每个重试记录是否指向当前开启轮次及其最新已关闭步骤，是否与失败请求的持久提供方匹配，是否携带非空的提供方与策略标识，是否满足 mode 特定边界，是否拥有唯一步骤记录和正确的提供方策略重试编号，以及是否携带有界定时器延迟。完整 jitter 可以在下界调度为零毫秒。
+单独发布的 `./invariant` 配套模块会检查每个已调度重试是否指向当前开启轮次及其最新已关闭步骤，是否与失败请求的持久提供方匹配，是否携带非空的提供方与策略标识，是否满足 mode 特定边界，是否拥有唯一步骤记录和正确的提供方策略重试编号，以及是否携带有界定时器延迟。它还要求每个 `llm/retry-started` 事件通过相同的 `retryId`、轮次、步骤与重试编号指向一个先前调度的尝试，并拒绝重复的 started 事件。完整 jitter 可以在下界调度为零毫秒。
 
 ```yaml
 - name: '@deepseek-ai/dsh-llm-deepseek'
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index b52000f554..c8ec4894b4 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -282,7 +282,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
-        jsDoc: '/**\n * Forcibly compact a range of surface nodes into a single summary node.\n * `start` and `end` name an inclusive span by surface position, not numeric seq\n * order; replacements can make visible seqs non-monotonic. Both edges must be\n * balanced so assistant tool calls remain paired with their results. A model-\n * backed implementation forwards cancellation and rejects active, missing,\n * reversed, or unbalanced ranges. The target session is `agent.session`.\n * Its replacement user message must use {@link COMPACT_CHECKPOINT_SOURCE}.\n * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}\n * for the edge checks.\n *\n * @param start - first surface seq, inclusive.\n * @param end - last surface seq, inclusive.\n * @param agent - context whose session is mutated and whose routing options guide summarization.\n * @param signal - optional cancellation; model-backed implementations must forward it.\n * @throws when compaction is active or the range is missing, reversed, or unbalanced.\n * @returns the appended event seqs, summary, replaced range, and token accounting.\n */',
+        jsDoc: '/**\n * Forcibly compact a range of surface nodes into a single summary node.\n * `start` and `end` name an inclusive span by surface position, not numeric seq\n * order; replacements can make visible seqs non-monotonic. Both edges must be\n * balanced so assistant tool calls remain paired with their results. A model-\n * backed implementation forwards cancellation and rejects active, missing,\n * reversed, or unbalanced ranges. The target session is `agent.session`.\n * Its replacement user message must use {@link compactCheckpointSource} with\n * the transaction\'s `CompactionId`.\n * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}\n * for the edge checks.\n *\n * @param start - first surface seq, inclusive.\n * @param end - last surface seq, inclusive.\n * @param agent - context whose session is mutated and whose routing options guide summarization.\n * @param signal - optional cancellation; model-backed implementations must forward it.\n * @throws when compaction is active or the range is missing, reversed, or unbalanced.\n * @returns the appended event seqs, summary, replaced range, and token accounting.\n */',
       },
     ],
   },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6fb20b9718..1c27b19685 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1507,6 +1507,9 @@ importers:
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
         version: link:../../interaction/commands
+      '@deepseek-ai/dsh-compact':
+        specifier: workspace:^
+        version: link:../../compact/compact
       '@deepseek-ai/dsh-host-apiproxy':
         specifier: workspace:^
         version: link:../../host/apiproxy

From 1566a00eeba61e5f17f65a266eec4944e1ae335c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:42:39 +0800
Subject: [PATCH 503/516] test compact checkpoint snapshot identity

---
 .../acp-agent/tests/snapshots/workspace-context/session.jsonl   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl b/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
index 179e61ade9..40592a9f99 100644
--- a/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
@@ -16,7 +16,7 @@
 {"type":"assistant/chunk","seq":14,"time":1785730689194,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
 {"type":"assistant/message","seq":15,"time":1785730689194,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_workspace_read","name":"read","arguments":"{\"file_path\":\"nested/task.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"9e9648c4-949e-4cf1-b9ef-0eb65897d36b"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[10,11,12,13,14],"surfaceOp":"append"}
 {"type":"tool/call","seq":16,"time":1785730689195,"data":{"turn":1,"step":1,"callId":"call_workspace_read","name":"read","arguments":"{\"file_path\":\"nested/task.txt\"}"}}
-{"type":"user/message","seq":17,"time":1785982371865,"data":{"content":[{"type":"text","text":"Earlier context was compacted for this snapshot."}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"162c764f-f01d-484d-ad81-1481dc29792a"},"sourceEventSeqs":[5],"surfaceOp":{"op":"replace","start":5,"end":5}}
+{"type":"user/message","seq":17,"time":1785982371865,"data":{"content":[{"type":"text","text":"Earlier context was compacted for this snapshot."}],"source":{"kind":"plugin","plugin":"compact","compactionId":"workspace-context-fixture"},"role":"user","id":"162c764f-f01d-484d-ad81-1481dc29792a"},"sourceEventSeqs":[5],"surfaceOp":{"op":"replace","start":5,"end":5}}
 {"type":"tool/result","seq":18,"time":1785982371865,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_workspace_read"},"content":[{"type":"tool-result","toolCallId":"call_workspace_read","content":[{"type":"text","text":"<path>{{cwd}}/nested/task.txt</path>\n<type>file</type>\n<content>\n1: snapshot task\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"role":"user","id":"a46fded2-333a-4fb2-b01e-28520bffbc21"},"meta":{"path":"{{cwd}}/nested/task.txt","offset":1,"lines":[{"number":1,"text":"snapshot task"}],"totalLines":1}},"sourceEventSeqs":[16],"surfaceOp":"append"}
 {"type":"step/end","seq":19,"time":1785982371865,"data":{"turn":1,"step":1}}
 {"type":"agent/inbox/spliced","seq":20,"time":1785730689207,"data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nRoot snapshot instruction.\n\n</system-reminder>"},{"type":"text","text":"<system-reminder>\nAdditional instructions from: nested/AGENTS.md\n\nThese instructions apply to work under `nested`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nNested snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".dsh-project\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"AGENTS.md\",\"CLAUDE.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"2e18766c26603608f321508caae00ea8f4434d59"},{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"c446df9a85c7e73a3055f394a4822a19ac9ead5a"}]},"role":"user","id":"09640903-80ea-4eb6-8635-90ddfb4e24e4"}]}}

From 6f27e6c2cea0ceeb86ef8887e3e2518e898567f7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:44:10 +0800
Subject: [PATCH 504/516] test(windows): compare canonical HMR identities

---
 .../2026-08-08-native-windows-pull-request-ci.i18n.yaml    | 4 ++--
 .../process/2026-08-08-native-windows-pull-request-ci.md   | 2 +-
 .../2026-08-08-native-windows-pull-request-ci.zh.md        | 2 +-
 packages/boot/app-boot/tests/hmr-config.spec.ts            | 7 ++++---
 4 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index cff610e481..cb77330b29 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.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 .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
-2026-08-08-native-windows-pull-request-ci.md: 258bca96db04c44ca2a3509c297028e31ef5375e
-2026-08-08-native-windows-pull-request-ci.zh.md: dd0031630eea9bb09a4a4db0125933ba0c7bac2f
+2026-08-08-native-windows-pull-request-ci.md: b8de631f96f7ff27c122971448f115d198b24a60
+2026-08-08-native-windows-pull-request-ci.zh.md: 433904ef513d3f92a6350eeb99f071711b49daf6
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 258bca96db..b8de631f96 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -16,7 +16,7 @@ Every pull request also starts an independent `windows-native` job named `window
 
 The native gate keeps workspace build and production-site failures blocking inside its own job while reporting the broader static, documentation, package, and built-artifact portability inventory as observational. One runner shares installation and build outputs across those gates, and serial gate and publint worker bounds keep the standard image within a predictable resource envelope. Linux remains the owner of duplicate lint, coverage, and snapshot enforcement until those suites have an explicit native-Windows contract.
 
-The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path. Module HMR attaches listeners and awaits the main watcher's ready event before plugin startup settles, so an immediate post-boot edit cannot race the initial scan.
+The first native run exposed two failures hidden by the compatibility lane. Documentation projection tests derived an image basename by splitting only on `/`; they now use Node's platform basename. Chokidar consumers received `%TEMP%` through the `C:\\Users\\RUNNER~1` 8.3 alias while libuv returned the long directory name, tripping its Windows event-path assertion. Shared settings and credentials watchers, plus Cordis module and exact-config HMR, now canonicalize the existing native watch base or deepest existing ancestor before opening the watcher and preserve a missing suffix, while file access and diagnostics retain the configured path. Module HMR attaches listeners and awaits the main watcher's ready event before plugin startup settles, so an immediate post-boot edit cannot race the initial scan. HMR acceptance derives expected identities through the same asynchronous native realpath operation, avoiding a synchronous Windows spelling that can retain the 8.3 alias.
 
 The next exact-head run exposed one remaining observational built-bin failure: its lifecycle fixtures used `process.kill()` or `subprocess.kill()` to send `SIGTERM`, which unconditionally terminates a Windows target instead of delivering the registered process event for graceful disposal. POSIX acceptance still sends the real signal. On Windows the fixture requests that same registered event from inside the child, directly for a self-terminating probe and through a marker for parent-controlled lifecycle cases, so the assembled shutdown and disposal path remains covered without asserting an operating-system facility that does not exist. That acceptance then exposed the underlying early-shutdown race: a signal could dispose the root after boot returned while fallback HMR watchers were mounting, and the resulting inactive-service error escaped as a boot failure. Post-boot setup now admits work only while the authoritative root fiber is active and contains a concurrent setup error only when the same invocation's recorded signal already owns shutdown; unrelated HMR failures remain loud.
 
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index dd0031630e..433904ef51 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 原生门禁在其自身作业内继续将工作区构建与生产网站故障设为阻断项，同时将更广泛的静态检查、文档、包和构建产物可移植性清单作为观测项报告。同一台运行器在这些门禁之间共享安装结果与构建输出，串行门禁与 publint 工作线程上限使标准镜像的资源使用保持在可预测范围内。在这些套件明确建立原生 Windows 契约之前，重复执行的 lint、覆盖率与快照强制检查仍由 Linux 负责。
 
-首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。模块 HMR 会挂接监听器并等待主 watcher 的 ready 事件，之后插件启动才会完成，因此启动后立即发生的编辑无法与初始扫描形成竞态。
+首次原生运行暴露出两项被兼容性通道掩盖的故障。文档投影测试此前只按 `/` 拆分来派生图片 basename；现在改为使用 Node 根据平台计算的 basename。Chokidar 消费方收到的 `%TEMP%` 以 `C:\\Users\\RUNNER~1` 这个 8.3 别名表示，而 libuv 返回的是长目录名，导致其 Windows 事件路径断言失败。共享的设置 watcher 与凭据 watcher，以及 Cordis 的模块 HMR（热模块替换）与精确配置 HMR，现在都会在打开 watcher 前规范化现有的原生监听基准路径或层级最深的现有祖先路径，并保留尚不存在的后缀；文件访问和诊断仍使用配置路径。模块 HMR 会挂接监听器并等待主 watcher 的 ready 事件，之后插件启动才会完成，因此启动后立即发生的编辑无法与初始扫描形成竞态。HMR 验收通过相同的异步原生 realpath 操作派生预期身份，避免同步 Windows 路径写法仍保留 8.3 别名。
 
 下一次分支头精确运行暴露出观测项中剩余的一项 built-bin 故障：其生命周期 fixture（测试前置数据）通过 `process.kill()` 或 `subprocess.kill()` 发送 `SIGTERM`；在 Windows 上，这种调用会无条件终止目标进程，而不会交付为优雅释放所注册的进程事件。POSIX 验收仍发送真实信号。在 Windows 上，fixture 改为从子进程内部请求同一个已注册事件：自终止探测直接请求，由父进程控制的生命周期场景则通过标记请求；因此，完整组装后的关闭与释放路径仍得到覆盖，也无需断言操作系统提供了本不存在的信号机制。该项验收随即暴露出底层的提前关闭竞态：boot 返回后，回退 HMR watcher 仍在挂载，此时信号可能对根 fiber 执行 dispose（资源释放），由此产生的服务未激活错误会逸出并被报告为 boot 失败。boot 后 setup 现在只会在权威根 fiber 仍处于活跃状态时接纳工作；只有当本次调用所记录的信号已取得关闭流程所有权时，才会隔离并发 setup 错误，无关的 HMR 故障仍会响亮失败。
 
diff --git a/packages/boot/app-boot/tests/hmr-config.spec.ts b/packages/boot/app-boot/tests/hmr-config.spec.ts
index d21e222104..82cbd71c28 100644
--- a/packages/boot/app-boot/tests/hmr-config.spec.ts
+++ b/packages/boot/app-boot/tests/hmr-config.spec.ts
@@ -1,4 +1,5 @@
-import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
+import { realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -40,7 +41,7 @@ describe('HMR exact config paths', () => {
     // This acceptance owns alias-to-cache identity. Other cases below exercise
     // native events; polling keeps Windows fs.watch queue pressure out of it.
     const ctx = await bootHmr(alias, ['.'], true)
-    const filename = join(realpathSync(target), 'module.ts')
+    const filename = join(await realpath(target), 'module.ts')
     const expected = pathToFileURL(filename).href
     const cacheHas = vi.spyOn(ctx.loader.internal!.loadCache, 'has').mockReturnValue(false)
     const observed: string[] = []
@@ -73,7 +74,7 @@ describe('HMR exact config paths', () => {
     const ctx = await bootHmr(alias)
     try {
       await ctx.hmr.registerConfig('plugins.yml', () => {})
-      await expect(ctx.hmr.registerConfig(join(realpathSync(target), 'plugins.yml'), () => {}))
+      await expect(ctx.hmr.registerConfig(join(await realpath(target), 'plugins.yml'), () => {}))
         .rejects.toThrow('config path already registered')
     } finally {
       await ctx.fiber.dispose()

From f4c817648d0685dd2bec9f3c1b474597e8473687 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:53:06 +0800
Subject: [PATCH 505/516] docs fix compact checkpoint type example

---
 ...2026-07-30-web-transcript-log-ordered-projection.i18n.yaml | 4 ++--
 .../2026-07-30-web-transcript-log-ordered-projection.md       | 4 ++--
 .../2026-07-30-web-transcript-log-ordered-projection.zh.md    | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index 1ea341085d..00fec6c8db 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: feefc951118c8511237c931a13070e1f7db1fd16
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 711e57b29742171d1861f25e63019b64356b4cad
+2026-07-30-web-transcript-log-ordered-projection.md: f2b7c3830b585db619f69046917e07a0b6ff6832
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 77787f9613b64a35e79a8667c6598de5a20ff400
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index feefc95111..f2b7c3830b 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -33,8 +33,8 @@ What is unreachable from a `packages/client/*` program is `dsh-compact`'s **root
 The repo's answer to exactly this is a cordis-free leaf subpath, and this change adds one: `COMPACT_CHECKPOINT_SOURCE` and `isCompactCheckpointSource` now live in `packages/compact/compact/src/checkpoint.ts`, which imports no cordis and augments no module (the `dsh-commands/brand` / `dsh-llm/message` shape), and the root re-exports both so every host-side consumer — the terminal's chat helpers, `dsh-session-reference`'s projection — is unchanged. The adapter pins its literal to that declaration with a type-only import:
 
 ```ts
-import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
-const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
+import type { CompactCheckpointSource } from '@deepseek-ai/dsh-compact/checkpoint'
+const COMPACT_PLUGIN: CompactCheckpointSource['plugin'] = 'compact'
 ```
 
 Renaming the Service Definition's plugin id is now a compile error in the client: `TS2322: Type '"compact"' is not assignable to type '"compaction"'`. The import must stay **type-only** — a value import of any `@deepseek-ai` package that is neither a platform module nor an inline-safe wire layer is rejected by the client purity gate (`packages/client/tsdown.client.ts`), whose own message records that type-only imports are erased and never reach it. A type-only leaf import needs both a `tsconfig.base.json` `paths` entry and `{"path": "../../compact/compact"}` in `packages/client/runtime/tsconfig.json` `references`: composite `rootDir` rules apply to erased imports as well, and without the reference the diagnostic is `TS6059`/`TS6307`.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 711e57b297..77787f9613 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -33,8 +33,8 @@ surface 顺序还让另外两个问题成为结构性的。一次替换之后它
 本仓库对这一情形的既有答案是不含 cordis 的叶子子路径，本次变更就新增了一个：`COMPACT_CHECKPOINT_SOURCE` 与 `isCompactCheckpointSource` 现在住在 `packages/compact/compact/src/checkpoint.ts`，它不导入 cordis、也不增强任何模块（即 `dsh-commands/brand` / `dsh-llm/message` 的形状），而包根重新导出两者，因此每个宿主侧消费方——终端的 chat helper、`dsh-session-reference` 的投影——都不需改动。适配器用仅类型导入把它的字面量钉在该声明上：
 
 ```ts
-import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
-const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
+import type { CompactCheckpointSource } from '@deepseek-ai/dsh-compact/checkpoint'
+const COMPACT_PLUGIN: CompactCheckpointSource['plugin'] = 'compact'
 ```
 
 重命名 Service Definition 的插件 id 现在会在客户端产生编译错误：`TS2322: Type '"compact"' is not assignable to type '"compaction"'`。该导入必须保持**仅类型**——任何既非平台模块又非 inline-safe wire 层的 `@deepseek-ai` 包值导入都会被客户端纯度门禁（`packages/client/tsdown.client.ts`）拒绝，而它自己的报错信息就记录着仅类型导入会被擦除、永不抵达该门禁。仅类型的叶子导入同时需要 `tsconfig.base.json` 的一条 `paths` 条目和 `packages/client/runtime/tsconfig.json` `references` 中的 `{"path": "../../compact/compact"}`：composite 的 `rootDir` 规则同样适用于被擦除的导入，缺少该引用时的诊断是 `TS6059`/`TS6307`。

From 25dcd7293cca9cef7d2275b048462285d5090068 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 15:09:19 +0800
Subject: [PATCH 506/516] docs: purge chain-of-thought leakage from prose

Delete design-session citations (decision/audit/plan ordinals, stack
positions), change narration, review choreography, and reviewer-addressed
justification from comments, JSDoc, docs, READMEs, Agent Notes, tests, and
generator templates; restate every affected fact as current-state contract
prose. Fix generated docs at their sources and regenerate the catalogs and
cordis-surface regions; re-paste type-equiv blocks; update every bilingual
counterpart and re-record the pairs. Record the citation rule in the
committed-artifact-citations Agent Note.
---
 ...026-06-11-event-sourced-sessions.i18n.yaml |   4 +-
 .../2026-06-11-event-sourced-sessions.md      |   2 +-
 .../2026-06-11-event-sourced-sessions.zh.md   |   2 +-
 ...026-06-11-runtime-arg-validation.i18n.yaml |   4 +-
 .../2026-06-11-runtime-arg-validation.md      |   2 +-
 .../2026-06-11-runtime-arg-validation.zh.md   |   2 +-
 .../2026-06-14-session-persistence.i18n.yaml  |   4 +-
 .../2026-06-14-session-persistence.md         |   4 +-
 .../2026-06-14-session-persistence.zh.md      |   4 +-
 ...06-17-filesystem-capability-seam.i18n.yaml |   4 +-
 .../2026-06-17-filesystem-capability-seam.md  |  12 +-
 ...026-06-17-filesystem-capability-seam.zh.md |  12 +-
 .../2026-06-18-session-surface.i18n.yaml      |   4 +-
 .../2026-06-18-session-surface.md             |   2 +-
 .../2026-06-18-session-surface.zh.md          |   2 +-
 ...ed-persistence-write-coordinator.i18n.yaml |   4 +-
 ...18-shared-persistence-write-coordinator.md |   2 +-
 ...shared-persistence-write-coordinator.zh.md |   2 +-
 .../2026-06-20-branded-ids.i18n.yaml          |   4 +-
 .../architecture/2026-06-20-branded-ids.md    |  14 +-
 .../architecture/2026-06-20-branded-ids.zh.md |  14 +-
 ...andatory-app-attribution-headers.i18n.yaml |   4 +-
 ...06-21-mandatory-app-attribution-headers.md |  10 +-
 ...21-mandatory-app-attribution-headers.zh.md |  10 +-
 .../2026-06-24-web-capability-seam.i18n.yaml  |   4 +-
 .../2026-06-24-web-capability-seam.md         |   4 +-
 .../2026-06-24-web-capability-seam.zh.md      |   4 +-
 ...06-26-file-context-as-event-gate.i18n.yaml |   4 +-
 .../2026-06-26-file-context-as-event-gate.md  |   2 +-
 ...026-06-26-file-context-as-event-gate.zh.md |   2 +-
 ...stdin-env-trusted-plugin-surface.i18n.yaml |   4 +-
 ...0-bash-stdin-env-trusted-plugin-surface.md |   2 +-
 ...ash-stdin-env-trusted-plugin-surface.zh.md |   2 +-
 ...026-06-30-event-domain-semantics.i18n.yaml |   4 +-
 .../2026-06-30-event-domain-semantics.md      |   4 +-
 .../2026-06-30-event-domain-semantics.zh.md   |   4 +-
 ...bles-and-tool-guidance-ownership.i18n.yaml |   4 +-
 ...t-variables-and-tool-guidance-ownership.md |   4 +-
 ...ariables-and-tool-guidance-ownership.zh.md |   4 +-
 ...6-07-05-reconstructable-requests.i18n.yaml |   4 +-
 .../2026-07-05-reconstructable-requests.md    |   2 +-
 .../2026-07-05-reconstructable-requests.zh.md |   2 +-
 ...6-07-06-timeout-deadline-library.i18n.yaml |   4 +-
 .../2026-07-06-timeout-deadline-library.md    |   4 +-
 .../2026-07-06-timeout-deadline-library.zh.md |   4 +-
 ...6-07-07-tool-call-timeout-policy.i18n.yaml |   4 +-
 .../2026-07-07-tool-call-timeout-policy.md    |   3 +-
 .../2026-07-07-tool-call-timeout-policy.zh.md |   3 +-
 ...cutable-sdk-runtime-distribution.i18n.yaml |   4 +-
 ...ile-executable-sdk-runtime-distribution.md |   2 +-
 ...-executable-sdk-runtime-distribution.zh.md |   2 +-
 .../2026-07-15-lsp-capability-seam.i18n.yaml  |   4 +-
 .../2026-07-15-lsp-capability-seam.md         |   4 +-
 .../2026-07-15-lsp-capability-seam.zh.md      |   4 +-
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |   4 +-
 ...026-07-19-gui-layering-and-rpc-protocol.md |  12 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |  12 +-
 ...7-19-gui-web-client-architecture.i18n.yaml |   4 +-
 .../2026-07-19-gui-web-client-architecture.md |  12 +-
 ...26-07-19-gui-web-client-architecture.zh.md |  12 +-
 ...7-23-client-plugin-loading-model.i18n.yaml |   4 +-
 .../2026-07-23-client-plugin-loading-model.md |   6 +-
 ...26-07-23-client-plugin-loading-model.zh.md |   6 +-
 ...-24-single-harness-home-resolver.i18n.yaml |   4 +-
 ...2026-07-24-single-harness-home-resolver.md |   2 +-
 ...6-07-24-single-harness-home-resolver.zh.md |   2 +-
 ...ession-scope-and-provide-channel.i18n.yaml |   4 +-
 ...lient-session-scope-and-provide-channel.md |   2 +-
 ...nt-session-scope-and-provide-channel.zh.md |   2 +-
 ...eb-command-surfaces-and-assembly.i18n.yaml |   4 +-
 ...07-25-web-command-surfaces-and-assembly.md |   6 +-
 ...25-web-command-surfaces-and-assembly.zh.md |   6 +-
 ...input-machine-and-slash-pipeline.i18n.yaml |   4 +-
 ...25-web-input-machine-and-slash-pipeline.md |   6 +-
 ...web-input-machine-and-slash-pipeline.zh.md |   6 +-
 .../2026-07-26-subprocess-seam.i18n.yaml      |   4 +-
 .../2026-07-26-subprocess-seam.md             |   2 +-
 .../2026-07-26-subprocess-seam.zh.md          |   2 +-
 ...07-27-dispose-ladder-to-consumer.i18n.yaml |   4 +-
 .../2026-07-27-dispose-ladder-to-consumer.md  |   2 +-
 ...026-07-27-dispose-ladder-to-consumer.zh.md |   2 +-
 ...07-28-api-browser-trust-boundary.i18n.yaml |   4 +-
 .../2026-07-28-api-browser-trust-boundary.md  |   4 +-
 ...026-07-28-api-browser-trust-boundary.zh.md |   4 +-
 ...directory-picker-capability-seam.i18n.yaml |   4 +-
 ...-07-28-directory-picker-capability-seam.md |   2 +-
 ...-28-directory-picker-capability-seam.zh.md |   2 +-
 .../2026-07-28-user-settings-seam.i18n.yaml   |   4 +-
 .../2026-07-28-user-settings-seam.md          |   4 +-
 .../2026-07-28-user-settings-seam.zh.md       |   4 +-
 ...-07-29-dsh-source-launch-tsx-esm.i18n.yaml |   4 +-
 .../2026-07-29-dsh-source-launch-tsx-esm.md   |   2 +-
 ...2026-07-29-dsh-source-launch-tsx-esm.zh.md |   2 +-
 .../2026-07-29-package-regrouping.i18n.yaml   |   4 +-
 .../2026-07-29-package-regrouping.md          |  24 +-
 .../2026-07-29-package-regrouping.zh.md       |  24 +-
 ...-token-usage-and-request-context.i18n.yaml |   4 +-
 ...ojected-token-usage-and-request-context.md |   4 +-
 ...cted-token-usage-and-request-context.zh.md |   4 +-
 ...est-level-llm-config-credentials.i18n.yaml |   4 +-
 ...29-request-level-llm-config-credentials.md |   4 +-
 ...request-level-llm-config-credentials.zh.md |   4 +-
 ...26-07-30-config-plane-boundaries.i18n.yaml |   4 +-
 .../2026-07-30-config-plane-boundaries.md     |   4 +-
 .../2026-07-30-config-plane-boundaries.zh.md  |   4 +-
 ...undaries-and-atomic-registration.i18n.yaml |   4 +-
 ...tial-boundaries-and-atomic-registration.md |   8 +-
 ...l-boundaries-and-atomic-registration.zh.md |  10 +-
 ...30-session-end-seed-log-boundary.i18n.yaml |   4 +-
 ...026-07-30-session-end-seed-log-boundary.md |   2 +-
 ...-07-30-session-end-seed-log-boundary.zh.md |   2 +-
 ...30-settings-write-path-integrity.i18n.yaml |   4 +-
 ...026-07-30-settings-write-path-integrity.md |   6 +-
 ...-07-30-settings-write-path-integrity.zh.md |   6 +-
 .../2026-07-30-web-config-plane.i18n.yaml     |   4 +-
 .../2026-07-30-web-config-plane.md            |  10 +-
 .../2026-07-30-web-config-plane.zh.md         |  10 +-
 ...runtime-portable-identifier-seam.i18n.yaml |   4 +-
 ...1-code-runtime-portable-identifier-seam.md |   8 +-
 ...ode-runtime-portable-identifier-seam.zh.md |   8 +-
 ...08-02-typert-remote-method-calls.i18n.yaml |   4 +-
 .../2026-08-02-typert-remote-method-calls.md  |   2 +-
 ...026-08-02-typert-remote-method-calls.zh.md |   2 +-
 ...-pi-ai-declared-provider-catalog.i18n.yaml |   4 +-
 ...6-08-03-pi-ai-declared-provider-catalog.md |   2 +-
 ...8-03-pi-ai-declared-provider-catalog.zh.md |   2 +-
 ...4-configuration-source-ownership.i18n.yaml |   4 +-
 ...26-08-04-configuration-source-ownership.md |   2 +-
 ...08-04-configuration-source-ownership.zh.md |   2 +-
 ...-a-provider-from-the-models-page.i18n.yaml |   4 +-
 ...claring-a-provider-from-the-models-page.md |   2 +-
 ...ring-a-provider-from-the-models-page.zh.md |   2 +-
 ...ubagent-list-identity-projection.i18n.yaml |   4 +-
 ...08-06-subagent-list-identity-projection.md |  14 +-
 ...06-subagent-list-identity-projection.zh.md |  14 +-
 ...d-scrollbars-and-reserved-gutter.i18n.yaml |   4 +-
 ...8-themed-scrollbars-and-reserved-gutter.md |   4 +-
 ...hemed-scrollbars-and-reserved-gutter.zh.md |   4 +-
 ...07-30-approval-panel-command-cap.i18n.yaml |   4 +-
 .../2026-07-30-approval-panel-command-cap.md  |   2 +-
 ...026-07-30-approval-panel-command-cap.zh.md |   2 +-
 ...ranscript-log-ordered-projection.i18n.yaml |   4 +-
 ...0-web-transcript-log-ordered-projection.md |   2 +-
 ...eb-transcript-log-ordered-projection.zh.md |   2 +-
 ...-fail-loud-releases-the-terminal.i18n.yaml |   4 +-
 ...6-07-31-fail-loud-releases-the-terminal.md |   2 +-
 ...7-31-fail-loud-releases-the-terminal.zh.md |   2 +-
 ...-08-06-api-key-format-validation.i18n.yaml |   4 +-
 .../2026-08-06-api-key-format-validation.md   |   2 +-
 ...2026-08-06-api-key-format-validation.zh.md |   2 +-
 ...07-cancel-convergence-wake-latch.i18n.yaml |   4 +-
 ...026-08-07-cancel-convergence-wake-latch.md |   6 +-
 ...-08-07-cancel-convergence-wake-latch.zh.md |   6 +-
 .../feature/2026-06-15-code-mode.i18n.yaml    |   4 +-
 .../feature/2026-06-15-code-mode.md           |   4 +-
 .../feature/2026-06-15-code-mode.zh.md        |   4 +-
 ...26-06-17-filesystem-tool-schemas.i18n.yaml |   4 +-
 .../2026-06-17-filesystem-tool-schemas.md     |  12 +-
 .../2026-06-17-filesystem-tool-schemas.zh.md  |  12 +-
 ...06-18-compaction-capability-seam.i18n.yaml |   4 +-
 .../2026-06-18-compaction-capability-seam.md  |   2 +-
 ...026-06-18-compaction-capability-seam.zh.md |   2 +-
 ...6-06-21-subagent-capability-seam.i18n.yaml |   4 +-
 .../2026-06-21-subagent-capability-seam.md    |   4 +-
 .../2026-06-21-subagent-capability-seam.zh.md |   4 +-
 .../2026-06-29-todo-write-tool.i18n.yaml      |   4 +-
 .../feature/2026-06-29-todo-write-tool.md     |   2 +-
 .../feature/2026-06-29-todo-write-tool.zh.md  |   2 +-
 .../2026-06-30-hook-protocol-lib.i18n.yaml    |   4 +-
 .../feature/2026-06-30-hook-protocol-lib.md   |   2 +-
 .../2026-06-30-hook-protocol-lib.zh.md        |   2 +-
 ...026-06-30-session-store-fork-api.i18n.yaml |   4 +-
 .../2026-06-30-session-store-fork-api.md      |   2 +-
 .../2026-06-30-session-store-fork-api.zh.md   |   2 +-
 ...26-07-14-cross-family-fs-sandbox.i18n.yaml |   4 +-
 .../2026-07-14-cross-family-fs-sandbox.md     |   2 +-
 .../2026-07-14-cross-family-fs-sandbox.zh.md  |   2 +-
 .../2026-07-16-harness-level-loop.i18n.yaml   |   4 +-
 .../feature/2026-07-16-harness-level-loop.md  |   2 +-
 .../2026-07-16-harness-level-loop.zh.md       |   2 +-
 ...26-07-16-persistent-pty-sessions.i18n.yaml |   4 +-
 .../2026-07-16-persistent-pty-sessions.md     |   1 -
 .../2026-07-16-persistent-pty-sessions.zh.md  |   1 -
 ...26-07-20-dsh-cli-personal-config.i18n.yaml |   4 +-
 .../2026-07-20-dsh-cli-personal-config.md     |   2 +-
 .../2026-07-20-dsh-cli-personal-config.zh.md  |   2 +-
 ...3-session-telemetry-otel-revival.i18n.yaml |   4 +-
 ...26-07-23-session-telemetry-otel-revival.md |   2 +-
 ...07-23-session-telemetry-otel-revival.zh.md |   2 +-
 ...n-list-browsing-and-manual-order.i18n.yaml |   4 +-
 ...-session-list-browsing-and-manual-order.md |   2 +-
 ...ssion-list-browsing-and-manual-order.zh.md |   2 +-
 ...26-07-26-code-dispatch-log-spill.i18n.yaml |   4 +-
 .../2026-07-26-code-dispatch-log-spill.md     |   2 +-
 .../2026-07-26-code-dispatch-log-spill.zh.md  |   4 +-
 ...7-26-code-dispatch-ui-foundation.i18n.yaml |   4 +-
 .../2026-07-26-code-dispatch-ui-foundation.md |   8 +-
 ...26-07-26-code-dispatch-ui-foundation.zh.md |   8 +-
 ...7-26-code-mode-chat-subcall-rows.i18n.yaml |   4 +-
 .../2026-07-26-code-mode-chat-subcall-rows.md |   2 +-
 ...26-07-26-code-mode-chat-subcall-rows.zh.md |   2 +-
 ...code-mode-live-parallel-dispatch.i18n.yaml |   4 +-
 ...-07-26-code-mode-live-parallel-dispatch.md |   6 +-
 ...-26-code-mode-live-parallel-dispatch.zh.md |   6 +-
 ...-07-26-todo-parallel-in-progress.i18n.yaml |   4 +-
 .../2026-07-26-todo-parallel-in-progress.md   |   8 +-
 ...2026-07-26-todo-parallel-in-progress.zh.md |   8 +-
 ...ntinuable-subagent-conversations.i18n.yaml |   4 +-
 ...7-28-continuable-subagent-conversations.md |   4 +-
 ...8-continuable-subagent-conversations.zh.md |   4 +-
 ...28-todo-plan-clears-on-next-turn.i18n.yaml |   4 +-
 ...026-07-28-todo-plan-clears-on-next-turn.md |   2 +-
 ...-07-28-todo-plan-clears-on-next-turn.zh.md |   2 +-
 .../2026-07-28-web-terminal-card.i18n.yaml    |   4 +-
 .../feature/2026-07-28-web-terminal-card.md   |   6 +-
 .../2026-07-28-web-terminal-card.zh.md        |   6 +-
 ...29-ask-question-web-presentation.i18n.yaml |   4 +-
 ...026-07-29-ask-question-web-presentation.md |   4 +-
 ...-07-29-ask-question-web-presentation.zh.md |   4 +-
 ...6-07-30-queued-manual-compaction.i18n.yaml |   4 +-
 .../2026-07-30-queued-manual-compaction.md    |   2 +-
 .../2026-07-30-queued-manual-compaction.zh.md |   2 +-
 .../2026-07-30-search-render-card.i18n.yaml   |   4 +-
 .../feature/2026-07-30-search-render-card.md  |   6 +-
 .../2026-07-30-search-render-card.zh.md       |   6 +-
 .../2026-07-30-web-diff-card.i18n.yaml        |   4 +-
 .../feature/2026-07-30-web-diff-card.md       |   2 +-
 .../feature/2026-07-30-web-diff-card.zh.md    |   2 +-
 ...026-07-30-web-read-card-frontend.i18n.yaml |   4 +-
 .../2026-07-30-web-read-card-frontend.md      |   4 +-
 .../2026-07-30-web-read-card-frontend.zh.md   |   4 +-
 .../2026-07-30-web-read-card.i18n.yaml        |   4 +-
 .../feature/2026-07-30-web-read-card.md       |   4 +-
 .../feature/2026-07-30-web-read-card.zh.md    |   4 +-
 ...6-07-30-web-result-card-frontend.i18n.yaml |   4 +-
 .../2026-07-30-web-result-card-frontend.md    |   6 +-
 .../2026-07-30-web-result-card-frontend.zh.md |   6 +-
 .../2026-07-30-web-result-card.i18n.yaml      |   4 +-
 .../feature/2026-07-30-web-result-card.md     |   4 +-
 .../feature/2026-07-30-web-result-card.zh.md  |   4 +-
 .../2026-07-30-web-search-card.i18n.yaml      |   4 +-
 .../feature/2026-07-30-web-search-card.md     |   4 +-
 .../feature/2026-07-30-web-search-card.zh.md  |   4 +-
 ...7-31-code-mode-language-dispatch.i18n.yaml |   4 +-
 .../2026-07-31-code-mode-language-dispatch.md |   6 +-
 ...26-07-31-code-mode-language-dispatch.zh.md |   8 +-
 ...7-31-telemetry-anonymous-user-id.i18n.yaml |   4 +-
 .../2026-07-31-telemetry-anonymous-user-id.md |   2 +-
 ...26-07-31-telemetry-anonymous-user-id.zh.md |   2 +-
 ...6-07-31-web-workspace-file-links.i18n.yaml |   4 +-
 .../2026-07-31-web-workspace-file-links.md    |   2 +-
 .../2026-07-31-web-workspace-file-links.zh.md |   2 +-
 ...2026-08-02-pwsh-tool-bash-parity.i18n.yaml |   4 +-
 .../2026-08-02-pwsh-tool-bash-parity.md       |   6 +-
 .../2026-08-02-pwsh-tool-bash-parity.zh.md    |   6 +-
 ...2-win32-in-process-folder-dialog.i18n.yaml |   4 +-
 ...26-08-02-win32-in-process-folder-dialog.md |   2 +-
 ...08-02-win32-in-process-folder-dialog.zh.md |   2 +-
 ...6-08-03-web-search-source-scroll.i18n.yaml |   4 +-
 .../2026-08-03-web-search-source-scroll.md    |   2 +-
 .../2026-08-03-web-search-source-scroll.zh.md |   2 +-
 ...4-web-composer-shared-width-axis.i18n.yaml |   4 +-
 ...26-08-04-web-composer-shared-width-axis.md |   2 +-
 ...08-04-web-composer-shared-width-axis.zh.md |   2 +-
 ...26-08-05-context-form-vocabulary.i18n.yaml |   4 +-
 .../2026-08-05-context-form-vocabulary.md     |   2 +-
 .../2026-08-05-context-form-vocabulary.zh.md  |   2 +-
 .../2026-08-05-pwsh-ui-bash-parity.i18n.yaml  |   4 +-
 .../feature/2026-08-05-pwsh-ui-bash-parity.md |   2 +-
 .../2026-08-05-pwsh-ui-bash-parity.zh.md      |   2 +-
 .../2026-06-17-ts-build-config.i18n.yaml      |   4 +-
 .../process/2026-06-17-ts-build-config.md     |   6 +-
 .../process/2026-06-17-ts-build-config.zh.md  |   6 +-
 ...6-06-18-markdown-cross-link-lint.i18n.yaml |   4 +-
 .../2026-06-18-markdown-cross-link-lint.md    |   2 +-
 .../2026-06-18-markdown-cross-link-lint.zh.md |   2 +-
 ...-20-core-data-structures-catalog.i18n.yaml |   4 +-
 ...2026-06-20-core-data-structures-catalog.md |   4 +-
 ...6-06-20-core-data-structures-catalog.zh.md |   4 +-
 ...-bilingual-docs-and-pairing-gate.i18n.yaml |   4 +-
 ...6-07-02-bilingual-docs-and-pairing-gate.md |   2 +-
 ...7-02-bilingual-docs-and-pairing-gate.zh.md |   2 +-
 ...n-setup-for-symmetric-ci-caching.i18n.yaml |   4 +-
 ...m-action-setup-for-symmetric-ci-caching.md |   2 +-
 ...ction-setup-for-symmetric-ci-caching.zh.md |   2 +-
 ...27-wine-windows-gates-experiment.i18n.yaml |   4 +-
 ...026-07-27-wine-windows-gates-experiment.md |   2 +-
 ...-07-27-wine-windows-gates-experiment.zh.md |   2 +-
 ...30-generated-third-party-notices.i18n.yaml |   4 +-
 ...026-07-30-generated-third-party-notices.md |   2 +-
 ...-07-30-generated-third-party-notices.zh.md |   2 +-
 ...staller-adopts-existing-checkout.i18n.yaml |   4 +-
 ...7-31-installer-adopts-existing-checkout.md |   4 +-
 ...1-installer-adopts-existing-checkout.zh.md |   4 +-
 ...-06-coverage-uncovered-locations.i18n.yaml |   4 +-
 ...2026-08-06-coverage-uncovered-locations.md |   2 +-
 ...6-08-06-coverage-uncovered-locations.zh.md |   2 +-
 ...-09-committed-artifact-citations.i18n.yaml |   6 +
 ...2026-08-09-committed-artifact-citations.md |  37 ++
 ...6-08-09-committed-artifact-citations.zh.md |  37 ++
 ...-19-drop-mutable-session-summary.i18n.yaml |   4 +-
 ...2026-06-19-drop-mutable-session-summary.md |   2 +-
 ...6-06-19-drop-mutable-session-summary.zh.md |   2 +-
 ...llapse-trace-only-session-events.i18n.yaml |   4 +-
 ...6-20-collapse-trace-only-session-events.md |   8 +-
 ...0-collapse-trace-only-session-events.zh.md |   8 +-
 ...-06-20-public-agent-stop-surface.i18n.yaml |   4 +-
 .../2026-06-20-public-agent-stop-surface.md   |   6 +-
 ...2026-06-20-public-agent-stop-surface.zh.md |   4 +-
 ...ove-agent-boundary-mirror-events.i18n.yaml |   4 +-
 ...-20-remove-agent-boundary-mirror-events.md |  13 +-
 ...-remove-agent-boundary-mirror-events.zh.md |  13 +-
 ...06-20-unify-agent-and-session-id.i18n.yaml |   4 +-
 .../2026-06-20-unify-agent-and-session-id.md  |   1 -
 ...026-06-20-unify-agent-and-session-id.zh.md |   1 -
 .../2026-06-26-fsspec-style-fs-seam.i18n.yaml |   4 +-
 .../2026-06-26-fsspec-style-fs-seam.md        |   6 +-
 .../2026-06-26-fsspec-style-fs-seam.zh.md     |   6 +-
 ...6-07-04-drop-image-content-block.i18n.yaml |   4 +-
 .../2026-07-04-drop-image-content-block.md    |   2 +-
 .../2026-07-04-drop-image-content-block.zh.md |   2 +-
 ...4-tighten-hook-protocol-contract.i18n.yaml |   4 +-
 ...26-07-04-tighten-hook-protocol-contract.md |   2 +-
 ...07-04-tighten-hook-protocol-contract.zh.md |   2 +-
 .../2026-07-17-one-send-one-turn.i18n.yaml    |   4 +-
 .../2026-07-17-one-send-one-turn.md           |   2 +-
 .../2026-07-17-one-send-one-turn.zh.md        |   2 +-
 ...-31-one-route-to-add-a-workspace.i18n.yaml |   4 +-
 ...2026-07-31-one-route-to-add-a-workspace.md |   8 +-
 ...6-07-31-one-route-to-add-a-workspace.zh.md |   8 +-
 ...026-06-11-property-based-testing.i18n.yaml |   4 +-
 .../2026-06-11-property-based-testing.md      |   4 +-
 .../2026-06-11-property-based-testing.zh.md   |   4 +-
 .../2026-06-19-acp-snapshot-tests.i18n.yaml   |   4 +-
 .../testing/2026-06-19-acp-snapshot-tests.md  |   4 +-
 .../2026-06-19-acp-snapshot-tests.zh.md       |   4 +-
 .../2026-06-19-real-api-e2e-ci.i18n.yaml      |   4 +-
 .../testing/2026-06-19-real-api-e2e-ci.md     |   4 +-
 .../testing/2026-06-19-real-api-e2e-ci.zh.md  |   4 +-
 ...6-06-22-subagent-snapshot-replay.i18n.yaml |   4 +-
 .../2026-06-22-subagent-snapshot-replay.md    |   4 +-
 .../2026-06-22-subagent-snapshot-replay.zh.md |   4 +-
 ...6-07-24-web-gui-browser-e2e-lane.i18n.yaml |   4 +-
 .../2026-07-24-web-gui-browser-e2e-lane.md    |   2 +-
 .../2026-07-24-web-gui-browser-e2e-lane.zh.md |   2 +-
 .../2026-06-16-typed-event-schemas.i18n.yaml  |   4 +-
 .../2026-06-16-typed-event-schemas.md         |   2 -
 .../2026-06-16-typed-event-schemas.zh.md      |   2 -
 ...-domain-kv-storage-and-workspace.i18n.yaml |   4 +-
 ...6-07-24-domain-kv-storage-and-workspace.md |   4 +-
 ...7-24-domain-kv-storage-and-workspace.zh.md |   4 +-
 ...ssion-projection-and-command-log.i18n.yaml |   4 +-
 ...7-27-session-projection-and-command-log.md |   6 +-
 ...7-session-projection-and-command-log.zh.md |   6 +-
 ...root-and-derived-medium-recovery.i18n.yaml |   4 +-
 ...torage-root-and-derived-medium-recovery.md |   6 +-
 ...age-root-and-derived-medium-recovery.zh.md |   6 +-
 ...2026-07-06-recallable-compaction.i18n.yaml |   4 +-
 .../2026-07-06-recallable-compaction.md       |   2 +-
 .../2026-07-06-recallable-compaction.zh.md    |   2 +-
 .../2026-08-01-windows-pwsh-default.i18n.yaml |   4 +-
 .../2026-08-01-windows-pwsh-default.md        |   2 +-
 .../2026-08-01-windows-pwsh-default.zh.md     |   2 +-
 ...2026-06-11-api-extractor-reports.i18n.yaml |   4 +-
 .../2026-06-11-api-extractor-reports.md       |   2 +-
 .../2026-06-11-api-extractor-reports.zh.md    |   2 +-
 .agents/skills/dsh-doc-standards/SKILL.md     |   2 +-
 .../skills/dsh-merging-stacked-prs/SKILL.md   |   2 +-
 .agents/skills/dsh-translate-docs/SKILL.md    |   2 +-
 .agents/skills/record-browser-gif/SKILL.md    |   2 +-
 .github/issue-management/policy.mjs           |   2 +-
 .github/workflows/ci.yml                      |   7 +-
 apps/cli/tests/args.spec.ts                   |   6 +-
 apps/cli/tests/built-bin.e2e.ts               |  12 +-
 apps/web/tests/approval-composer.e2e.ts       |  13 +-
 apps/web/tests/chat-long-interactions.e2e.ts  |   7 +-
 apps/web/tests/code-mode-round.e2e.ts         |   4 +-
 apps/web/tests/composer-draft-scroll.e2e.ts   |  27 +-
 apps/web/tests/composer-tab-geometry.e2e.ts   |  54 +-
 .../tests/conversation-column-overflow.e2e.ts |  53 +-
 apps/web/tests/default-model.overlay.yml      |   2 +-
 apps/web/tests/lifecycle-chrome.e2e.ts        |  11 +-
 apps/web/tests/models-settings.e2e.ts         |   5 +-
 apps/web/tests/navigation-panes.e2e.ts        |   2 +-
 apps/web/tests/pin-browse-picker.overlay.yml  |   2 +-
 apps/web/tests/pwsh-terminal.e2e.ts           |   4 +-
 apps/web/tests/scaffold.ts                    |   2 +-
 apps/web/tests/seeded-history.e2e.ts          |   4 +-
 apps/web/tests/settings-chrome.e2e.ts         |   2 +-
 apps/web/tests/sidebar-scrollbar.e2e.ts       |  38 +-
 apps/web/tests/smoke-real.e2e.ts              |  30 +-
 apps/web/tests/startup-auto-selection.e2e.ts  |  13 +-
 apps/web/tests/subagent-interrupt-ui.e2e.ts   |   3 +-
 apps/web/tests/subagent-interrupt.e2e.ts      |   2 +-
 apps/web/tests/turn-tail-actions.e2e.ts       |   2 +-
 apps/web/tests/workspace-management.e2e.ts    |  16 +-
 apps/web/vite.config.ts                       |  12 +-
 docs/api-gateway.i18n.yaml                    |   4 +-
 docs/api-gateway.md                           |  10 +-
 docs/api-gateway.zh.md                        |  10 +-
 docs/capability-seams.md                      |   2 +-
 docs/config-catalog.md                        |  16 +-
 docs/cookbook/extension-cookbook.i18n.yaml    |   4 +-
 docs/cookbook/extension-cookbook.md           |   4 +-
 docs/cookbook/extension-cookbook.zh.md        |   4 +-
 .../maintaining-dsh-code-review.i18n.yaml     |   4 +-
 docs/cookbook/maintaining-dsh-code-review.md  |   2 +-
 .../maintaining-dsh-code-review.zh.md         |   2 +-
 docs/cordis-api/inherited.md                  |   2 +-
 docs/cordis-tutorial/04-events.i18n.yaml      |   4 +-
 docs/cordis-tutorial/04-events.md             |   2 +-
 docs/cordis-tutorial/04-events.zh.md          |   2 +-
 .../06-composition-and-hmr.i18n.yaml          |   4 +-
 .../cordis-tutorial/06-composition-and-hmr.md |   2 +-
 .../06-composition-and-hmr.zh.md              |   2 +-
 docs/event-producer-consumer.md               |   2 +-
 docs/i18n/translation-prompt.md               |   2 +-
 docs/persistence-catalog.md                   |   5 +-
 docs/subsystems/approval.i18n.yaml            |   4 +-
 docs/subsystems/approval.md                   |   5 +-
 docs/subsystems/approval.zh.md                |   5 +-
 docs/subsystems/bash.i18n.yaml                |   4 +-
 docs/subsystems/bash.md                       |   4 +-
 docs/subsystems/bash.zh.md                    |   4 +-
 docs/subsystems/client-modules.i18n.yaml      |   4 +-
 docs/subsystems/client-modules.md             |   2 +-
 docs/subsystems/client-modules.zh.md          |   2 +-
 docs/subsystems/code-runtime.i18n.yaml        |   4 +-
 docs/subsystems/code-runtime.md               |   2 +-
 docs/subsystems/code-runtime.zh.md            |   2 +-
 docs/subsystems/compaction.i18n.yaml          |   4 +-
 docs/subsystems/compaction.md                 |   2 +-
 docs/subsystems/compaction.zh.md              |   2 +-
 docs/subsystems/filesystem.i18n.yaml          |   4 +-
 docs/subsystems/filesystem.md                 |   2 +-
 docs/subsystems/filesystem.zh.md              |   2 +-
 docs/subsystems/llm-streaming.i18n.yaml       |   4 +-
 docs/subsystems/llm-streaming.md              |   8 +-
 docs/subsystems/llm-streaming.zh.md           |   8 +-
 docs/subsystems/lsp.i18n.yaml                 |   4 +-
 docs/subsystems/lsp.md                        |   2 +-
 docs/subsystems/lsp.zh.md                     |   2 +-
 docs/subsystems/persistence.i18n.yaml         |   4 +-
 docs/subsystems/persistence.md                |   4 +-
 docs/subsystems/persistence.zh.md             |   4 +-
 docs/subsystems/session-projection.i18n.yaml  |   4 +-
 docs/subsystems/session-projection.md         |   2 +-
 docs/subsystems/session-projection.zh.md      |   2 +-
 docs/subsystems/session.i18n.yaml             |   4 +-
 docs/subsystems/session.md                    |   5 +-
 docs/subsystems/session.zh.md                 |   5 +-
 docs/subsystems/skills.i18n.yaml              |   4 +-
 docs/subsystems/skills.md                     |   2 +-
 docs/subsystems/skills.zh.md                  |   2 +-
 docs/subsystems/storage.i18n.yaml             |   4 +-
 docs/subsystems/storage.md                    |   4 +-
 docs/subsystems/storage.zh.md                 |   4 +-
 docs/subsystems/subagent.i18n.yaml            |   4 +-
 docs/subsystems/subagent.md                   |   4 +-
 docs/subsystems/subagent.zh.md                |   4 +-
 docs/subsystems/subprocess.i18n.yaml          |   4 +-
 docs/subsystems/subprocess.md                 |   4 +-
 docs/subsystems/subprocess.zh.md              |   4 +-
 docs/subsystems/telemetry.i18n.yaml           |   4 +-
 docs/subsystems/telemetry.md                  |   2 +-
 docs/subsystems/telemetry.zh.md               |   2 +-
 docs/subsystems/web.i18n.yaml                 |   4 +-
 docs/subsystems/web.md                        |  13 +-
 docs/subsystems/web.zh.md                     |  13 +-
 docs/testing.i18n.yaml                        |   4 +-
 docs/testing.md                               |   2 +-
 docs/testing.zh.md                            |   2 +-
 docs/tool-catalog.md                          |   4 +-
 docs/user/guide/config.i18n.yaml              |   4 +-
 docs/user/guide/config.md                     |   2 +-
 docs/user/guide/config.zh.md                  |   2 +-
 docs/user/guide/providers.i18n.yaml           |   4 +-
 docs/user/guide/providers.md                  |   2 +-
 docs/user/guide/providers.zh.md               |   2 +-
 examples/acp-agent/tests/acp.e2e.ts           |   2 +-
 examples/acp-agent/tests/escalation.e2e.ts    |   2 +-
 .../headless-agent/tests/headless.snapshot.ts |  10 +-
 native/landlock-run/README.i18n.yaml          |   4 +-
 native/landlock-run/README.md                 |   2 +-
 native/landlock-run/README.zh.md              |   2 +-
 native/landlock-run/packages/entry/src/main.c |   9 +-
 packages/bash/bash-sandbox/src/index.ts       |   2 +-
 packages/bash/bash/README.i18n.yaml           |   4 +-
 packages/bash/bash/README.md                  |   2 +-
 packages/bash/bash/README.zh.md               |   2 +-
 packages/bash/pwsh-local/README.i18n.yaml     |   4 +-
 packages/bash/pwsh-local/README.md            |   2 +-
 packages/bash/pwsh-local/README.zh.md         |   2 +-
 packages/bash/tool-bash/src/index.ts          |   6 +-
 packages/bash/tool-pwsh/README.i18n.yaml      |   4 +-
 packages/bash/tool-pwsh/README.md             |   2 +-
 packages/bash/tool-pwsh/README.zh.md          |   2 +-
 packages/bundle/web-app/src/index.ts          |   2 +-
 packages/client/AGENTS.md                     |   4 +-
 packages/client/connection/README.i18n.yaml   |   4 +-
 packages/client/connection/README.md          |   2 +-
 packages/client/connection/README.zh.md       |   2 +-
 packages/client/connection/src/client/api.ts  |   8 +-
 .../connection/src/client/connection.ts       |  12 +-
 .../client/connection/src/client/fixture.ts   |  12 +-
 packages/client/hmr/src/client/index.ts       |   7 +-
 packages/client/modules/src/client/index.ts   |   4 +-
 .../client/modules/src/client/manifest.ts     |  12 +-
 packages/client/modules/src/client/system.ts  |   2 +-
 packages/client/modules/src/index.ts          |   4 +-
 packages/client/runtime/README.i18n.yaml      |   4 +-
 packages/client/runtime/README.md             |   4 +-
 packages/client/runtime/README.zh.md          |   4 +-
 .../runtime/src/client/contract/store.ts      |   6 +-
 packages/client/runtime/src/client/index.ts   |   3 +-
 .../runtime/src/client/sessions/manager.ts    |  14 +-
 .../src/client/sessions/projection-store.ts   |  11 +-
 .../runtime/src/client/sessions/service.ts    |   7 +-
 .../runtime/src/client/sessions/session.ts    |  25 +-
 .../src/client/sessions/transcript-adapter.ts | 408 +++++++++++++
 .../client/runtime/tests/client-apply.spec.ts |   2 +-
 packages/client/runtime/tests/event-script.ts |   2 +-
 .../runtime/tests/projection-store.spec.ts    |   3 +-
 packages/client/runtime/tests/session.spec.ts |   2 +-
 .../runtime/tests/transcript-adapter.spec.ts  | 567 ++++++++++++++++++
 .../ui-command/src/client/PopupSelectView.tsx |   4 +-
 .../client/ui-command/src/client/popup.ts     |   2 +-
 .../ui-command/tests/popup-view.spec.tsx      |   2 +-
 .../client/ui-command/tests/popup.spec.ts     |   2 +-
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +-
 packages/client/ui-conversation/README.zh.md  |   2 +-
 .../ui-conversation/src/client/apply.ts       |   8 +-
 .../src/client/chat/ChatView.tsx              |   2 +-
 .../src/client/chat/MessageItem.tsx           |   4 +-
 .../src/client/contract/slots.ts              |  19 +-
 .../src/client/input/contract.ts              |  10 +-
 .../src/client/input/decorations.ts           |  12 +-
 .../src/client/input/facade.ts                |  11 +-
 .../ui-conversation/src/client/input/hub.ts   |   6 +-
 .../src/client/input/machine.ts               |  14 +-
 .../ui-conversation/src/client/queue/store.ts |   2 +-
 .../ui-conversation/src/client/service.ts     |   2 +-
 .../src/client/skeleton/ApprovalPanel.tsx     |   3 +-
 .../src/client/skeleton/ContextMeter.tsx      |   4 +-
 .../src/client/skeleton/ConversationRoot.tsx  |   1 -
 .../src/client/skeleton/DetailsPanel.tsx      |   5 +-
 .../src/client/skeleton/InputBar.module.css   |   2 +-
 .../src/client/skeleton/InputBar.tsx          |   9 +-
 .../ui-conversation/tests/input-bar.spec.tsx  |  14 +-
 .../tests/input-machine.spec.ts               |   6 +-
 .../tests/input-matrix.spec.tsx               |   2 +-
 .../tests/input-scenarios.spec.tsx            |   2 +-
 .../ui-conversation/tests/todo-panel.spec.tsx |   4 +-
 .../client/ui-layout/src/client/AppFrame.tsx  |   4 +-
 .../client/ui-layout/tests/app-frame.spec.tsx |   2 +-
 packages/client/ui-models/README.i18n.yaml    |   4 +-
 packages/client/ui-models/README.md           |   2 +-
 packages/client/ui-models/README.zh.md        |   4 +-
 .../src/client/CustomProviderCard.tsx         |   2 +-
 .../src/client/ModelsSection.module.css       |   8 +-
 .../ui-models/tests/components.spec.tsx       |   4 +-
 .../ui-models/tests/provider-form.spec.tsx    |  12 +-
 .../client/ui-primitives/README.i18n.yaml     |   4 +-
 packages/client/ui-primitives/README.md       |   4 +-
 packages/client/ui-primitives/README.zh.md    |   4 +-
 .../ui-primitives/src/TerminalBlock.tsx       |   4 +-
 .../ui-primitives/src/Tooltip.module.css      |   4 +-
 .../ui-primitives/src/markdown/highlight.ts   |   3 +-
 .../client/ui-primitives/tests/ansi.spec.ts   |   8 +-
 .../ui-primitives/tests/hover-card.spec.tsx   |   4 +-
 .../client/ui-primitives/tests/icons.spec.tsx |   2 +-
 .../client/ui-primitives/tsdown.config.ts     |   2 +-
 .../ui-settings/src/client/contract/slots.ts  |   4 +-
 .../src/client/SidebarRoot.module.css         |   2 +-
 packages/client/ui-skill/README.i18n.yaml     |   4 +-
 packages/client/ui-skill/README.md            |   2 +-
 packages/client/ui-skill/README.zh.md         |   2 +-
 packages/client/ui-skill/src/client/index.ts  |  14 +-
 .../ui-skill/tests/browser-plugin.spec.ts     |   6 +-
 packages/client/ui-slash/README.i18n.yaml     |   4 +-
 packages/client/ui-slash/README.md            |   2 +-
 packages/client/ui-slash/README.zh.md         |   2 +-
 .../client/ui-slash/src/client/controller.ts  |   5 +-
 packages/client/ui-slash/src/client/slots.ts  |   2 +-
 packages/client/ui-slash/src/core/contract.ts |   8 +-
 packages/client/ui-slash/src/core/detect.ts   |   2 +-
 packages/client/ui-slash/src/core/menu.ts     |   2 +-
 packages/client/ui-slash/src/types.ts         |  12 +-
 .../client/ui-slash/tests/core-detect.spec.ts |   4 +-
 .../client/ui-slash/tests/core-menu.spec.ts   |   3 +-
 .../client/ui-slash/tests/menu-view.spec.tsx  |   2 +-
 .../client/ui-slash/tests/service.spec.ts     |   2 +-
 packages/client/ui-slots/src/index.ts         |   2 +-
 packages/client/ui-slots/src/renderer.ts      |   5 +-
 .../client/ui-subagent/src/client/index.ts    |  12 +-
 .../ui-subagent/tests/browser-plugin.spec.ts  |   6 +-
 packages/client/ui-theme/README.i18n.yaml     |   4 +-
 packages/client/ui-theme/README.md            |   4 +-
 packages/client/ui-theme/README.zh.md         |   4 +-
 packages/client/ui-tool/README.i18n.yaml      |   4 +-
 packages/client/ui-tool/README.md             |   6 +-
 packages/client/ui-tool/README.zh.md          |   6 +-
 .../src/client/tool/toolviews/search-row.tsx  |   4 +-
 .../client/ui-tool/tests/tool-row.spec.tsx    |   4 +-
 .../client/ui-trajectory/README.i18n.yaml     |   4 +-
 packages/client/ui-trajectory/README.md       |   2 +-
 packages/client/ui-trajectory/README.zh.md    |   2 +-
 .../client/ui-trajectory/src/client/layout.ts |   4 +-
 .../src/client/WorkspaceBrowser.tsx           |   4 +-
 .../ui-workspace/src/client/rows/Rows.tsx     |   6 +-
 .../tests/rename-assembly.spec.tsx            |   5 +-
 packages/client/web-react/README.i18n.yaml    |   4 +-
 packages/client/web-react/README.md           |   2 +-
 packages/client/web-react/README.zh.md        |   2 +-
 .../client/web-react/src/scoped-slots.tsx     |   4 +-
 .../client/web-react/src/session-provider.tsx |   2 +-
 .../web-react/tests/scoped-slots.spec.tsx     |   4 +-
 .../web-react/tests/session-provider.spec.tsx |   4 +-
 .../web-react/tests/use-projection.spec.tsx   |   3 +-
 packages/client/web/src/AppRoot.tsx           |   2 +-
 packages/client/web/src/boot.tsx              |  10 +-
 packages/client/web/src/index.ts              |   2 +-
 packages/client/web/src/loader-status.ts      |   4 +-
 packages/client/web/src/seed.ts               |   2 +-
 .../code-runtime/code-runtime/src/index.ts    |  14 +-
 packages/context/README.i18n.yaml             |   4 +-
 packages/context/README.md                    |   2 -
 packages/context/README.zh.md                 |   4 +-
 .../tests/workspace-context.spec.ts           |   2 +-
 packages/core/session/src/chunk-rows.ts       |   3 +-
 packages/core/session/src/types.ts            |   3 +-
 packages/core/tools/src/code-mode.ts          |   8 +-
 packages/core/tools/src/index.ts              |   4 +-
 packages/core/tools/src/py-types.ts           |  16 +-
 .../credentials-local/src/index.ts            |   5 +-
 .../credentials-local/tests/local.spec.ts     |   4 +-
 packages/fs/README.i18n.yaml                  |   4 +-
 packages/fs/README.md                         |   8 +-
 packages/fs/README.zh.md                      |   8 +-
 packages/fs/fs/README.i18n.yaml               |   4 +-
 packages/fs/fs/README.md                      |   2 +-
 packages/fs/fs/README.zh.md                   |   2 +-
 packages/fs/tool-fs-search/README.i18n.yaml   |   4 +-
 packages/fs/tool-fs-search/README.md          |   2 +-
 packages/fs/tool-fs-search/README.zh.md       |   2 +-
 packages/fs/tool-fs/README.i18n.yaml          |   4 +-
 packages/fs/tool-fs/README.md                 |   2 +-
 packages/fs/tool-fs/README.zh.md              |   2 +-
 packages/goal/goal/src/domain.ts              |   6 +-
 .../guard/timeout-policy/README.i18n.yaml     |   4 +-
 packages/guard/timeout-policy/README.md       |   2 +-
 packages/guard/timeout-policy/README.zh.md    |   2 +-
 packages/hooks/hook-protocol/README.i18n.yaml |   4 +-
 packages/hooks/hook-protocol/README.md        |   2 +-
 packages/hooks/hook-protocol/README.zh.md     |   2 +-
 packages/hooks/hooks-claude/src/index.ts      |   2 +-
 packages/hooks/hooks-codex/README.i18n.yaml   |   4 +-
 packages/hooks/hooks-codex/README.md          |   2 +-
 packages/hooks/hooks-codex/README.zh.md       |   2 +-
 packages/hooks/hooks-codex/src/index.ts       |   2 +-
 packages/host/apiproxy/README.i18n.yaml       |   4 +-
 packages/host/apiproxy/README.md              |   2 +-
 packages/host/apiproxy/README.zh.md           |   2 +-
 packages/host/apiproxy/src/api-proxy.ts       |   6 +-
 packages/host/apiproxy/src/index.ts           |   4 +-
 .../apiproxy/tests/api-proxy-cold.spec.ts     |   8 +-
 .../apiproxy/tests/api-proxy-config.spec.ts   |   7 +-
 .../src/client/DirectoryBrowser.tsx           |   3 +-
 .../src/native-picker.ts                      |   4 +-
 .../interaction/user-approval/src/index.ts    |   3 +-
 .../tests/loader-composition.spec.ts          |   2 +-
 packages/llm/llm-pi-ai/src/catalog.ts         |   9 +-
 packages/llm/llm/README.i18n.yaml             |   4 +-
 packages/llm/llm/README.md                    |   2 +-
 packages/llm/llm/README.zh.md                 |   2 +-
 packages/llm/llm/src/message.ts               |   4 +-
 packages/llm/token-meter/README.i18n.yaml     |   4 +-
 packages/llm/token-meter/README.md            |   4 +-
 packages/llm/token-meter/README.zh.md         |   4 +-
 packages/lsp/lsp/src/types.ts                 |   2 +-
 packages/mcp/mcp-client/src/tools.ts          |   5 +-
 packages/mcp/mcp-client/src/transport.ts      |   5 +-
 packages/mcp/mcp-client/tests/apply.spec.ts   |   1 -
 .../mcp/mcp-client/tests/mcp-client.spec.ts   |   7 +-
 packages/scaffold/README.i18n.yaml            |   4 +-
 packages/scaffold/README.md                   |   2 +-
 packages/scaffold/README.zh.md                |   2 +-
 packages/scaffold/telemetry/README.i18n.yaml  |   4 +-
 packages/scaffold/telemetry/README.md         |   2 +-
 packages/scaffold/telemetry/README.zh.md      |   2 +-
 packages/self-modification/README.i18n.yaml   |   4 +-
 packages/self-modification/README.md          |   2 +-
 packages/self-modification/README.zh.md       |   2 +-
 .../tool-cordis/src/api-catalog.ts            |   2 +-
 .../session-query-sqlite/README.i18n.yaml     |   4 +-
 .../session-query-sqlite/README.md            |   2 +-
 .../session-query-sqlite/README.zh.md         |   2 +-
 .../tests/jsonl.spec.ts                       |   1 -
 .../README.i18n.yaml                          |   4 +-
 .../session-persistence-sqlite/README.md      |   5 +-
 .../session-persistence-sqlite/README.zh.md   |   5 +-
 .../session-projection-cache/src/spec.ts      |   3 +-
 .../session-telemetry-otel/src/index.ts       |   6 +-
 .../session/session-telemetry/src/index.ts    |   2 +-
 packages/skill/skill-local/README.i18n.yaml   |   4 +-
 packages/skill/skill-local/README.md          |   2 +-
 packages/skill/skill-local/README.zh.md       |   2 +-
 .../skill/tool-skill/tests/tool-skill.spec.ts |  10 +-
 .../storage/storage-sqlite/README.i18n.yaml   |   4 +-
 packages/storage/storage-sqlite/README.md     |   4 +-
 packages/storage/storage-sqlite/README.zh.md  |   4 +-
 .../subagent/subagent-acp/README.i18n.yaml    |   4 +-
 packages/subagent/subagent-acp/README.md      |   2 +-
 packages/subagent/subagent-acp/README.zh.md   |   2 +-
 packages/subagent/subagent-acp/src/index.ts   |   2 +-
 packages/subagent/subagent-acp/src/run.ts     |   2 +-
 .../subagent-claude-code/README.i18n.yaml     |   4 +-
 .../subagent/subagent-claude-code/README.md   |   2 +-
 .../subagent-claude-code/README.zh.md         |   2 +-
 .../subagent/subagent-codex/README.i18n.yaml  |   4 +-
 packages/subagent/subagent-codex/README.md    |   4 +-
 packages/subagent/subagent-codex/README.zh.md |   4 +-
 .../subagent-fork/tests/subagent-fork.spec.ts |   2 -
 .../subagent/subagent/src/list-children.ts    |   9 +-
 packages/subagent/subagent/src/types.ts       |   2 +-
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.md     |   4 +-
 .../subprocess/subprocess-local/README.zh.md  |   4 +-
 packages/subprocess/subprocess/src/index.ts   |   4 +-
 .../support/acp-snapshot/README.i18n.yaml     |   4 +-
 packages/support/acp-snapshot/README.md       |   2 +-
 packages/support/acp-snapshot/README.zh.md    |   2 +-
 packages/support/acp-snapshot/src/harness.ts  |   4 +-
 packages/support/llm-replay/README.i18n.yaml  |   4 +-
 packages/support/llm-replay/README.md         |   2 +-
 packages/support/llm-replay/README.zh.md      |   2 +-
 packages/tasks/tasks/src/index.ts             |   7 +-
 packages/todo/tool-todo/src/index.ts          |   1 -
 .../typert/generator/src/cordis-catalog.ts    |   2 +-
 packages/util/retention/README.i18n.yaml      |   4 +-
 packages/util/retention/README.md             |   2 +-
 packages/util/retention/README.zh.md          |   2 +-
 packages/util/retention/src/index.ts          |   5 +-
 packages/util/timeout/README.i18n.yaml        |   4 +-
 packages/util/timeout/README.md               |   2 +-
 packages/util/timeout/README.zh.md            |   2 +-
 .../web/web-search-deepseek/README.i18n.yaml  |   4 +-
 packages/web/web-search-deepseek/README.md    |   2 +-
 packages/web/web-search-deepseek/README.zh.md |   2 +-
 packages/web/web/README.i18n.yaml             |   4 +-
 packages/web/web/README.md                    |   2 +-
 packages/web/web/README.zh.md                 |   2 +-
 packages/web/web/src/types.ts                 |   7 +-
 .../workflow/tool-workflow/README.i18n.yaml   |   4 +-
 packages/workflow/tool-workflow/README.md     |   2 +-
 packages/workflow/tool-workflow/README.zh.md  |   2 +-
 scripts/gen-doc-graphs.ts                     |   4 +-
 scripts/gen-tool-catalog.ts                   |   2 +-
 scripts/hero-composer-dom-continuity.mjs      |   2 +-
 scripts/translation-brief.ts                  |   7 +-
 scripts/verify-client-domain-graph.ts         |   8 +-
 vitest.config.ts                              |  10 +-
 763 files changed, 2705 insertions(+), 1710 deletions(-)
 create mode 100644 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
 create mode 100644 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
 create mode 100644 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
 create mode 100644 packages/client/runtime/src/client/sessions/transcript-adapter.ts
 create mode 100644 packages/client/runtime/tests/transcript-adapter.spec.ts

diff --git a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
index 0eb64b3107..a061e142cb 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.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 .agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md
-2026-06-11-event-sourced-sessions.md: 01f9628c1cfc000aca8654caf5edeff09411fdcc
-2026-06-11-event-sourced-sessions.zh.md: 5de230de9e9f1303943b43f6fdeefaf8264aa3bf
+2026-06-11-event-sourced-sessions.md: 1303ee843cd5f9e02eae7a1f9bc51594be4bb407
+2026-06-11-event-sourced-sessions.zh.md: d1800ab3820ba5fc60723d6851fe71eded38134f
diff --git a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md
index 01f9628c1c..1303ee843c 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.md
@@ -25,4 +25,4 @@ Ordering contract: the loop claims inbox messages before `agent/pre-step`, opens
 - Replay, trace, and telemetry are structurally guaranteed, not bolted on.
 - Persistence stays a plugin concern; the in-memory store ships in dsh-session.
 - The event vocabulary is merge-extensible (plugins add e.g. compaction events); [session persistence](2026-06-14-session-persistence.md) froze its shape once the log became durable.
-- Derivation cost grows with log length — compaction (future plugin) is the intended mitigation, not log mutation.
+- Derivation cost grows with log length — compaction (dsh-compact) is the intended mitigation, not log mutation.
diff --git a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
index 5de230de9e..d1800ab382 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.zh.md
@@ -25,4 +25,4 @@ MVP 要求严格的基于事件的追踪，以及完全可回放的会话（严
 - 回放、追踪与遥测在结构上得到保证，而非事后附加。
 - 持久化仍是插件关注点；内存存储随 dsh-session 一起提供。
 - 事件词汇可通过合并扩展（插件可添加如压缩（compaction）事件）；[会话持久化](2026-06-14-session-persistence.md)在日志具备持久性后固定了其结构。
-- 派生成本随日志长度增长，压缩（未来插件）是预期的缓解手段，而非日志变更。
+- 派生成本随日志长度增长，压缩（dsh-compact）是预期的缓解手段，而非日志变更。
diff --git a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml
index b18ca244be..260604acc4 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.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 .agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md
-2026-06-11-runtime-arg-validation.md: e0bca0ff24c5adc7ca58007932dff6580694b01d
-2026-06-11-runtime-arg-validation.zh.md: c98bde0ed2dd568a394aae74fb9f5549c3f61105
+2026-06-11-runtime-arg-validation.md: 520823c76f147205805d306e97b5461f38b84c35
+2026-06-11-runtime-arg-validation.zh.md: ccb9b50d8b8a932d17516e579a5364321b64577b
diff --git a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md
index e0bca0ff24..520823c76f 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.md
@@ -18,7 +18,7 @@ The validator and compiler therefore share exact semantics: the implicit paramet
 
 - The model gets actionable feedback on its own malformed calls instead of an opaque crash, closing the gap between `InferArgs`'s promise and runtime reality.
 - The validator and `InferArgs` must stay in agreement; [a property test](../testing/2026-06-11-property-based-testing.md) generates args satisfying a spec and asserts they pass `validateArgs` (with targeted corruptions rejected), closing that drift risk mechanically.
-- `ToolArgsError` is a plain `Error` with a `code` field for now; if a harness-wide error taxonomy lands it becomes a subclass without changing callers that read `.message`.
+- `ToolArgsError` subclasses `HarnessError` from the [structured error taxonomy](2026-06-11-structured-error-taxonomy.md), keeping its `code` field; callers that read `.message` are unaffected by the hierarchy.
 - Validation cost is negligible next to a model call.
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
index c98bde0ed2..ccb9b50d8b 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-runtime-arg-validation.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 - 模型在自身畸形调用上获得可操作的反馈，而非不透明的崩溃，弥合了 `InferArgs` 的承诺与运行时现实之间的鸿沟。
 - 校验器与 `InferArgs` 必须保持一致；一项[属性测试](../testing/2026-06-11-property-based-testing.md)生成满足 spec 的参数并断言它们通过 `validateArgs`（同时断言定向破坏的参数被拒绝），以机械方式封堵漂移风险。
-- `ToolArgsError` 目前是带 `code` 字段的普通 `Error`；如果日后引入 harness 级别的错误分类体系，它将变为子类，但不影响读取 `.message` 的调用方。
+- `ToolArgsError` 是[结构化错误分类体系](2026-06-11-structured-error-taxonomy.md)中 `HarnessError` 的子类，保留其 `code` 字段；读取 `.message` 的调用方不受该层级结构影响。
 - 校验开销相对于一次模型调用可忽略不计。
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
index f2b2982bc1..a28df36350 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.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 .agents/notes/implemented/architecture/2026-06-14-session-persistence.md
-2026-06-14-session-persistence.md: 46fd3755a3c35bd342119fb59b560775a679f740
-2026-06-14-session-persistence.zh.md: f29b192ec9814de2a183599bcfc0a4a0c301b31e
+2026-06-14-session-persistence.md: 6961b8f3f4274587c2920fe2b2602aff5efe4afc
+2026-06-14-session-persistence.zh.md: 58c8bb80a1f886c986fc5aa1a0ba6b7f263ad829
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
index 46fd3755a3..6961b8f3f4 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md
@@ -17,7 +17,7 @@ Persistence is a **capability seam** with an abstract Service Definition ([capab
 1. **Interface** (`dsh-session-persistence`, `ctx.sessionPersistence`) — an abstract `SessionPersistence` service: `locate`/`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`/`list`/`listSnapshots`. Its persisted unit IS the existing `SessionEvent` (`{ type, seq, time, data }`), reused verbatim — no conversion type.
 2. **Implementation** (`dsh-session-persistence-jsonl`) — an append-only logical JSONL log per session: a `SessionHeader` line followed by storage records that losslessly represent the contiguous `SessionEvent` stream. Eligible `assistant/chunk` delta runs use packed rows by default; [checksummed Zstandard frames](2026-07-19-zstandard-jsonl-session-logs.md) are the default physical encoding, with raw lines configurable.
 
-Key choices recorded here because they are durable, contested, and surprising:
+Key durable, contested choices:
 
 - **The canonical durable log persists every `SessionEvent` losslessly, including `assistant/chunk`.** JSONL storage may encode a consecutive delta run as one packed row, but logical readers reconstruct the exact event boundaries, sequence numbers, and timestamps. `deriveMessages()` skips chunks, and a chunk-filtered rollout (Codex's `policy.rs`) is tempting — but `seq = log.length` and validation of `events[i].seq === i` require a *contiguous* logical log; filtering chunks out would leave holes and break both the contract and resume. A chunk-filtered projection is possible later as a derived view with its own renumbering, but it is NOT the canonical log.
 - **Append-only; a crashed turn is closed, never truncated.** Flushed events are never rewritten. The [semantic checkpoint policy](../bug-fix/2026-07-21-semantic-session-checkpoints.md) drains the request before model dispatch, a recorded top-level call before tool dispatch, and the complete response/result batch after a step; the loop drains the final turn boundary. Because one interrupted turn may contain substantial valid work, cold inspection preserves its contiguous, parseable events and adds risk-classified error results for unanswered assistant calls, a missing `step/end`, and `turn/end` with `{ kind: 'interrupted' }` to the in-memory logical view. `prepare` or `load` commits those closers before returning a recoverable view; the synthetic results keep resumed provider transcripts valid. Only an incomplete final record is discarded during committed repair; a parse error or sequence gap at or before the last real `turn/end` is corruption and makes the session unloadable.
@@ -29,7 +29,7 @@ Key choices recorded here because they are durable, contested, and surprising:
 
 Each key choice above records its rejected alternative where the choice is stated: a **chunk-filtered canonical log** (Codex's `policy.rs` shape) — breaks the contiguous-seq contract; **truncating a crashed turn** — silently destroys a long autonomous run's real work; an **in-log `session/meta` event as line 0** — metadata is not replayable state; **finite fractional `createdAt` values** — have no producer and diverge from integer Unix-millisecond storage and query columns; **adopting a non-pristine unversioned SQLite file** — can overwrite unrelated objects or identity; **hard-injecting `sessionPersistence` into the loop** — would pend non-persistent demos forever.
 
-Format versioning: the header carries a `version`; cold reads reject any non-current version. The pre-release session format stays pinned at `SESSION_FORMAT_VERSION = 0` and carries no broad compatibility promise, while the coordinator may own an explicit narrow import upgrade when persisted user data requires it ([pre-identity message recovery](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)). Stated honestly: append-only + flush is robust to partial trailing writes (tolerated during cold preparation) but not to fsync-less power loss mid-line; a DB/WAL backend is the stronger option later.
+Format versioning: the header carries a `version`; cold reads reject any non-current version. The pre-release session format stays pinned at `SESSION_FORMAT_VERSION = 0` and carries no broad compatibility promise, while the coordinator may own an explicit narrow import upgrade when persisted user data requires it ([pre-identity message recovery](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)). Append-only + flush is robust to partial trailing writes (tolerated during cold preparation) but not to fsync-less power loss mid-line; a DB/WAL backend is the stronger option there.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
index f29b192ec9..58c8bb80a1 100644
--- a/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-14-session-persistence.zh.md
@@ -17,7 +17,7 @@ Status: implemented
 1. **接口**（`dsh-session-persistence`，`ctx.sessionPersistence`）：一个抽象的 `SessionPersistence` 服务，提供 `locate`/`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`/`list`/`listSnapshots`。其持久化单元就是现有的 `SessionEvent`（`{ type, seq, time, data }`），原样复用，无转换类型。
 2. **实现**（`dsh-session-persistence-jsonl`）：每个会话一个仅追加的逻辑 JSONL 日志：先是一行 `SessionHeader`，随后是无损表示连续 `SessionEvent` 流的存储记录。符合条件的 `assistant/chunk` 增量连续段默认使用打包行；[带校验和的 Zstandard 帧](2026-07-19-zstandard-jsonl-session-logs.md)是默认物理编码，也可通过配置使用原始行。
 
-以下关键选择记录于此，因为它们长期有效、存在争议且出人意料：
+长期有效、存在争议的关键选择：
 
 - **规范的持久日志无损保留每个 `SessionEvent`，包括 `assistant/chunk`。** JSONL 存储可以将一段连续的增量事件编码为一条打包行，但逻辑读取方会重建精确的事件边界、序号与时间戳。`deriveMessages()` 跳过分片，而过滤分片的方案（Codex 的 `policy.rs`）很有吸引力，但 `seq = log.length` 以及 `events[i].seq === i` 验证要求*连续*的逻辑日志；过滤掉分片会留下空洞，同时破坏约定和恢复功能。基于分片过滤的投影可以作为派生视图在后续实现（带有自己的重新编号），但它不是规范日志。
 - **仅追加；崩溃的轮次被关闭，而非截断。** 已刷写的事件永不被重写。[语义检查点策略](../bug-fix/2026-07-21-semantic-session-checkpoints.md)会在模型分发前排空请求、在工具分发前排空已记录的顶层调用，并在步骤结束后排空完整的响应/结果批次；循环则排空最终轮次边界。由于一个被中断的轮次可能包含大量有效工作，冷检查会保留其连续、可解析的事件，并在内存逻辑视图中为未应答的 assistant 调用添加按风险分类的错误结果、补一个缺失的 `step/end`，以及带 `{ kind: 'interrupted' }` 的 `turn/end`。`prepare` 或 `load` 在返回可恢复视图前提交这些 closer；合成结果保证恢复后的提供方 transcript（文本记录）仍然有效。只有不完整的最后一条记录会在提交修复时被丢弃；在最后一个真实 `turn/end` 处或之前出现解析错误或序号间隙，属于数据损坏，会使该会话不可加载。
@@ -29,7 +29,7 @@ Status: implemented
 
 上述每个关键选择都在陈述处记录了被否决的替代方案：**过滤分片的规范日志**（Codex 的 `policy.rs` 形式）破坏连续 seq 约定；**截断崩溃的轮次**会静默销毁长时间自主运行中的真实工作；**日志内 `session/meta` 事件作为第 0 行**——元数据不是可回放状态；**有限的非整数 `createdAt` 值**没有生产方，且与整数 Unix 毫秒存储及查询列不一致；**接受非全新的未版本化 SQLite 文件**可能覆盖无关对象或应用标识；**将 `sessionPersistence` 硬注入循环**会让非持久化的演示永远挂起。
 
-格式版本控制：header 携带一个 `version`；冷读取拒绝任何非当前版本。预发布阶段的会话格式仍固定为 `SESSION_FORMAT_VERSION = 0`，不承诺广泛兼容；当持久化用户数据确有需要时，协调器可以负责显式且范围受限的导入升级（[消息标识机制引入前的消息恢复](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。坦率地说：仅追加 + 刷写对部分尾部写入是健壮的（冷准备时容忍），但对行写入中途的无 fsync 断电不健壮；数据库/WAL 后端是后续更强的选项。
+格式版本控制：header 携带一个 `version`；冷读取拒绝任何非当前版本。预发布阶段的会话格式仍固定为 `SESSION_FORMAT_VERSION = 0`，不承诺广泛兼容；当持久化用户数据确有需要时，协调器可以负责显式且范围受限的导入升级（[消息标识机制引入前的消息恢复](../bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。仅追加 + 刷写对部分尾部写入是健壮的（冷准备时容忍），但对行写入中途的无 fsync 断电不健壮；数据库/WAL 后端是该场景下更强的选项。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
index 159483fb73..68bcd74197 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.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 .agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
-2026-06-17-filesystem-capability-seam.md: 35fe5148ca44f733aa0a354e215cd1d77eb8180e
-2026-06-17-filesystem-capability-seam.zh.md: 998b5ead48dcaf168ad48c8ad7a403a7e3b3e955
+2026-06-17-filesystem-capability-seam.md: 928ad4926e46ed5b6b35552b75882d565d8ad6db
+2026-06-17-filesystem-capability-seam.zh.md: 02af77a3cc291eeba2be966a4bc08aa006675e7d
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
index 35fe5148ca..928ad4926e 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-17-filesystem-capability-seam.zh.md)
 
 ## Problem
 
-The harness has a concrete `bash` capability seam (`dsh-bash` / `dsh-bash-local` / `dsh-tool-bash`), but filesystem operations are about to be added as model-facing tools without an equivalent seam. If `read`, `write`, and `edit` directly use `node:fs`, the model-facing tool package will own filesystem execution policy, local path resolution, atomic write behavior, text decoding, symlink behavior, and edit semantics all at once.
+The harness has a concrete `bash` capability seam (`dsh-bash` / `dsh-bash-local` / `dsh-tool-bash`), but filesystem operations were about to land as model-facing tools without an equivalent seam. If `read`, `write`, and `edit` directly used `node:fs`, the model-facing tool package would own filesystem execution policy, local path resolution, atomic write behavior, text decoding, symlink behavior, and edit semantics all at once.
 
 That couples three concerns that change independently:
 
@@ -16,7 +16,7 @@ That couples three concerns that change independently:
 
 Without a `ctx.fs` interface, swapping local filesystem access for a sandboxed or remote backend would churn the tool schemas, demos, and prompt guidance even when the model-facing contract should stay stable. It also makes permission/sandbox boundaries harder to reason about: a `cwd` option can look like a sandbox even though it is only a base path unless an explicit backend or `tools/execute` policy enforces containment.
 
-We need the filesystem tools to land in the same capability-seam shape as bash before they become a public package surface.
+The filesystem tools must land in the same capability-seam shape as bash before they become a public package surface.
 
 ## Decision
 
@@ -28,7 +28,7 @@ Filesystem access is a first-class capability seam following [the capability-sea
 
 The Consumer package depends only on the Service Definition package, never on `dsh-fs-local`. A deployment that wants a different backend loads a different provider for `ctx.fs` without changing the tool schemas or model-facing prompt guidance.
 
-The read-before-write/edit and observed-state policy is a fourth package, `@deepseek-ai/dsh-fs-policy` (`packages/fs/fs-policy`), contributed through the `fs/*` event gate rather than living on `ctx.fs`; a deployment loading `dsh-tool-fs` also loads `dsh-fs-policy` to get read-before-write/edit. This Agent Note established the three-package boundary; the split of policy off the provider base class is decided by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md), and its realization as an event-gate plugin (not a method service) by [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md). This document is updated to describe that landed four-package shape.
+The read-before-write/edit and observed-state policy is a fourth package, `@deepseek-ai/dsh-fs-policy` (`packages/fs/fs-policy`), contributed through the `fs/*` event gate rather than living on `ctx.fs`; a deployment loading `dsh-tool-fs` also loads `dsh-fs-policy` to get read-before-write/edit. This decision established the three-package boundary; the split of policy off the provider base class is decided by [the split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md), and its realization as an event-gate plugin (not a method service) by [the event-gate Agent Note](2026-06-26-file-context-as-event-gate.md).
 
 The first backend is deliberately local-only: `dsh-fs-local` implements `ctx.fs` against the host filesystem. Future sibling backends can provide sandboxed, remote, virtual, or project-scoped filesystems behind the same interface.
 
@@ -74,7 +74,7 @@ The provider contract also carries the freshness hooks that policy builds on —
 - `writeText`/`editText` take an OPTIONAL version expectation: omit it for an unconditional bare-provider mutation, or supply it to guard the mutation inside the backend's atomic critical section.
 - The `dsh-fs-policy` plugin decides that expectation on `fs/write-intent`/`fs/edit-intent` and records observed versions on `fs/observed`, keyed by an owner it derives from the opaque event actor (normally `exec.agent.session`).
 
-Authorization is version freshness, not a full/partial view distinction: any read records the target's version, and a later write/edit is authorized as long as the file is still at that version — so a windowed read of lines 100-150 authorizes an edit of line 120. The observed-state store is a `WeakMap<owner, Map<targetKey, version>>` inside `dsh-fs-policy`; `dsh-fs` holds none of it and treats the actor as opaque. (This Agent Note first modeled a `FileState` cache with `full`/`partial` views on `ctx.fs`; the split-fs-seam and event-gate Agent Notes replaced that with the freshness-based policy plugin described here.)
+Authorization is version freshness, not a full/partial view distinction: any read records the target's version, and a later write/edit is authorized as long as the file is still at that version — so a windowed read of lines 100-150 authorizes an edit of line 120. The observed-state store is a `WeakMap<owner, Map<targetKey, version>>` inside `dsh-fs-policy`; `dsh-fs` holds none of it and treats the actor as opaque. (This decision first modeled a `FileState` cache with `full`/`partial` views on `ctx.fs`; the split-fs-seam and event-gate notes replaced that with the freshness-based policy plugin described here.)
 
 Path resolution is explicit and allowed to be async. Local resolution may only normalize a path, but sandboxed/remote/project-scoped backends may need I/O to resolve a user-supplied path into a stable target identity.
 
@@ -148,11 +148,11 @@ The defensive-pattern classes this repo has been bitten by are pinned directly:
 
 **The interface can become too local.** Returning fields such as `absolutePath` from `ctx.fs` would make remote, sandboxed, or virtual backends awkward. The contract should expose display metadata without requiring consumers to understand host paths.
 
-**The interface can become too thin.** If `ctx.fs` only mirrors `node:fs` primitives, `tool-fs` will reimplement binary detection, pagination, atomic writes, and edit semantics. That recreates the coupling this Agent Note is trying to avoid.
+**The interface can become too thin.** If `ctx.fs` only mirrors `node:fs` primitives, `tool-fs` will reimplement binary detection, pagination, atomic writes, and edit semantics. That recreates the coupling this decision avoids.
 
 **Edit semantics are race-prone by nature.** Literal edit is a read-modify-write operation; the guard is the backend's atomic mutation critical section plus the optional version expectation, so concurrent edits settle deterministically — one wins, the other gets `FS_STALE_VERSION`.
 
-**Observed state does not belong on `ctx.fs`.** Recording what an execution context has seen is workflow policy, not raw filesystem I/O. This Agent Note first placed it inside the filesystem seam; the split-fs-seam Agent Note then established that a sandboxed/remote backend should not inherit model-facing observation policy, and moved it into the `dsh-fs-policy` plugin. The provider contract keeps only what write/edit safety genuinely needs at the storage layer — a backend-minted version token and an optional version-guarded mutation — while the policy plugin owns owner derivation, observed-state, and read-before-edit gating over the `fs/*` events.
+**Observed state does not belong on `ctx.fs`.** Recording what an execution context has seen is workflow policy, not raw filesystem I/O. This decision first placed it inside the filesystem seam; the split-fs-seam note then established that a sandboxed/remote backend should not inherit model-facing observation policy, and moved it into the `dsh-fs-policy` plugin. The provider contract keeps only what write/edit safety genuinely needs at the storage layer — a backend-minted version token and an optional version-guarded mutation — while the policy plugin owns owner derivation, observed-state, and read-before-edit gating over the `fs/*` events.
 
 **The `resolve`-then-operate shape costs an extra round-trip per call.** Each tool may resolve a path to an `FsTarget` and then issue the read/write/edit as a separate `ctx.fs` call. For the local backend this is negligible (resolution is in-memory path normalization), but a remote/sandboxed backend may turn each step into its own request, so a single `read` can become two network round-trips. Backends where the round-trip matters can cache or fold resolution internally while preserving the observable contract.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
index 998b5ead48..02af77a3cc 100644
--- a/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local` / `dsh-tool-bash`），但文件系统操作即将作为面向模型的工具加入，却没有等价的 seam。如果 `read`、`write` 和 `edit` 直接使用 `node:fs`，面向模型的工具包将同时承担文件系统执行策略、本地路径解析、原子写入行为、文本解码、符号链接行为和编辑语义。
+harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local` / `dsh-tool-bash`），但文件系统操作当时即将作为面向模型的工具落地，却没有等价的 seam。如果 `read`、`write` 和 `edit` 直接使用 `node:fs`，面向模型的工具包就会同时承担文件系统执行策略、本地路径解析、原子写入行为、文本解码、符号链接行为和编辑语义。
 
 这把三个独立变化的关注点耦合在了一起：
 
@@ -16,7 +16,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 如果没有 `ctx.fs` 接口，将本地文件系统访问替换为沙箱或远程后端时，即使面向模型的约定应当保持稳定，工具 schema、演示和提示词引导也会被迫变动。这还使权限/沙箱边界更难推理：一个 `cwd` 选项看起来像沙箱，但除非有显式的后端或 `tools/execute` 策略强制隔离，否则它只是一个基础路径。
 
-我们需要文件系统工具在成为公开包（package）接口之前，以与 bash 相同的能力 seam 形态落地。
+文件系统工具必须在成为公开包（package）接口之前，以与 bash 相同的能力 seam 形态落地。
 
 ## 决策
 
@@ -28,7 +28,7 @@ harness 已有一个具体的 `bash` 能力 seam（`dsh-bash` / `dsh-bash-local`
 
 Consumer 包仅依赖 Service Definition 包，从不依赖 `dsh-fs-local`。需要不同后端的部署只需为 `ctx.fs` 加载不同的提供方，无需改动工具 schema 或面向模型的提示词引导。
 
-读后写/编辑与观测状态策略是第四个包 `@deepseek-ai/dsh-fs-policy`（`packages/fs/fs-policy`），通过 `fs/*` 事件门控贡献，而非挂在 `ctx.fs` 上；加载 `dsh-tool-fs` 的部署同时加载 `dsh-fs-policy` 以获得读后写/编辑能力。本 Agent Note 确立了由三个包构成的边界；策略从提供方基类拆出的决策由 [拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 做出，其以事件门控插件（而非方法服务）实现的方式由 [事件门控 Agent Note](2026-06-26-file-context-as-event-gate.md) 做出。本文已更新为描述最终落地的四包形态。
+读后写/编辑与观测状态策略是第四个包 `@deepseek-ai/dsh-fs-policy`（`packages/fs/fs-policy`），通过 `fs/*` 事件门控贡献，而非挂在 `ctx.fs` 上；加载 `dsh-tool-fs` 的部署同时加载 `dsh-fs-policy` 以获得读后写/编辑能力。本决策确立了由三个包构成的边界；策略从提供方基类拆出的决策由 [拆分文件系统 seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) 做出，其以事件门控插件（而非方法服务）实现的方式由 [事件门控 Agent Note](2026-06-26-file-context-as-event-gate.md) 做出。
 
 第一个后端有意仅限本地：`dsh-fs-local` 基于宿主文件系统实现 `ctx.fs`。未来的兄弟后端可在同一接口之后提供沙箱、远程、虚拟或项目作用域的文件系统。
 
@@ -74,7 +74,7 @@ Consumer 包仅依赖 Service Definition 包，从不依赖 `dsh-fs-local`。需
 - `writeText`/`editText` 接受一个可选的版本期望：省略它表示无条件的裸提供方变更；提供它则在后端的原子临界区内守护变更。
 - `dsh-fs-policy` 插件在 `fs/write-intent`/`fs/edit-intent` 上决定该期望，并在 `fs/observed` 上记录观测版本，以它从不透明事件 actor 推导出的 owner 为键（通常是 `exec.agent.session`）。
 
-授权基于版本新鲜度，而非完整/部分视图的区分：任何读取都会记录目标的版本，后续的写入/编辑只要文件仍处于该版本就被授权——因此对第 100-150 行的窗口化读取可以授权对第 120 行的编辑。观测状态存储是 `dsh-fs-policy` 内部的 `WeakMap<owner, Map<targetKey, version>>`；`dsh-fs` 不持有任何此类数据，并将 actor 视为不透明。（本 Agent Note 最初建模了一个带 `full`/`partial` 视图的 `FileState` 缓存放在 `ctx.fs` 上；拆分文件系统 seam 与事件门控两份 Agent Note 将其替换为此处描述的基于新鲜度的策略插件。）
+授权基于版本新鲜度，而非完整/部分视图的区分：任何读取都会记录目标的版本，后续的写入/编辑只要文件仍处于该版本就被授权——因此对第 100-150 行的窗口化读取可以授权对第 120 行的编辑。观测状态存储是 `dsh-fs-policy` 内部的 `WeakMap<owner, Map<targetKey, version>>`；`dsh-fs` 不持有任何此类数据，并将 actor 视为不透明。（本决策最初建模了一个带 `full`/`partial` 视图的 `FileState` 缓存放在 `ctx.fs` 上；拆分文件系统 seam 与事件门控两份笔记将其替换为此处描述的基于新鲜度的策略插件。）
 
 路径解析是显式的，允许异步。本地解析可能只做路径规范化，但沙箱/远程/项目作用域的后端可能需要 I/O 才能将用户提供的路径解析为稳定的目标标识。
 
@@ -148,11 +148,11 @@ Consumer 包仅依赖 Service Definition 包，从不依赖 `dsh-fs-local`。需
 
 **接口可能变得过于本地化。** 如果 `ctx.fs` 返回 `absolutePath` 之类的字段，远程、沙箱或虚拟后端会变得尴尬。约定应暴露显示元数据，而不要求消费方理解宿主路径。
 
-**接口可能变得过于薄。** 如果 `ctx.fs` 只镜像 `node:fs` 原语，`tool-fs` 将重新实现二进制检测、分页、原子写入和编辑语义，重新制造本 Agent Note 试图避免的耦合。
+**接口可能变得过于薄。** 如果 `ctx.fs` 只镜像 `node:fs` 原语，`tool-fs` 将重新实现二进制检测、分页、原子写入和编辑语义，重新制造本决策所避免的耦合。
 
 **编辑语义天然易受竞争影响。** 字面编辑是读-改-写操作；守护手段是后端的原子变更临界区加上可选的版本期望，因此并发编辑确定性地收敛——一个赢，另一个得到 `FS_STALE_VERSION`。
 
-**观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本 Agent Note 最初将其放在文件系统 seam 内部；拆分文件系统 seam Agent Note 随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方约定只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
+**观测状态不属于 `ctx.fs`。** 记录执行上下文看到了什么是工作流策略，而非原始文件系统 I/O。本决策最初将其放在文件系统 seam 内部；拆分文件系统 seam 笔记随后确立了沙箱/远程后端不应继承面向模型的观测策略，并将其移入 `dsh-fs-policy` 插件。提供方约定只保留写入/编辑安全在存储层真正需要的东西——后端铸造的版本令牌和可选的版本守护变更——而策略插件拥有 owner 推导、观测状态和基于 `fs/*` 事件的读后编辑门控。
 
 **`resolve` 然后操作的形态每次调用多一次往返。** 每个工具可能先将路径解析为 `FsTarget`，再以单独的 `ctx.fs` 调用发起读取/写入/编辑。对本地后端来说这可以忽略（解析是内存中的路径规范化），但远程/沙箱后端可能将每步变成独立请求，使单次 `read` 变为两次网络往返。往返开销重要的后端可以在内部缓存或折叠解析，同时保持可观测约定不变。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
index c10a8a497c..6abc3ded93 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.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 .agents/notes/implemented/architecture/2026-06-18-session-surface.md
-2026-06-18-session-surface.md: 73b3ab9080506edb9b0693c22a4c30544b506c11
-2026-06-18-session-surface.zh.md: 0c7ebbacd2f89da8012f3c08f1e4354a1d6c2e8e
+2026-06-18-session-surface.md: fd48a4ee4e177b84a235b044b054e4ac266df8ba
+2026-06-18-session-surface.zh.md: 86f9c5fdd5d711fb81e03e95329d316bfef29227
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
index 73b3ab9080..fd48a4ee4e 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
@@ -68,6 +68,6 @@ Every surface-eligible event must carry `surfaceOp` or it would disappear from d
 - **`packages/session/session-persistence-jsonl`**: No changes required.
 - **`packages/session/session-persistence`**: Abstract interface unchanged.
 
-The surface is the foundation for future history manipulation. A compaction or tool-result-prune plugin appends one of the existing message-producing event types (a `user/message` carrying the summary, say) with `surfaceOp: { op: 'replace', start, end }` and `sourceEventSeqs` covering the shadowed entries — the new event takes the range's place on the surface while the plugin's own trace events (e.g. `compaction/start`, `compaction/end`) stay off it. Replay preserves the decision deterministically.
+The surface is the foundation history manipulation ships on — dsh-compact's compaction rides it. A compaction or tool-result-prune plugin appends one of the existing message-producing event types (a `user/message` carrying the summary, say) with `surfaceOp: { op: 'replace', start, end }` and `sourceEventSeqs` covering the shadowed entries — the new event takes the range's place on the surface while the plugin's own trace events (e.g. `compaction/start`, `compaction/end`) stay off it. Replay preserves the decision deterministically.
 
 A `tool/result` replacement may rewrite exactly one current `tool/result` and must preserve every data field except `content`. Session acceptance enforces this rule together with positional range and cited source-event validation, independent of optional diagnostic plugins.
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
index 0c7ebbacd2..86f9c5fdd5 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md
@@ -68,6 +68,6 @@ export type SurfaceOp =
 - **`packages/session/session-persistence-jsonl`**：无需改动。
 - **`packages/session/session-persistence`**：抽象接口不变。
 
-Surface 是未来历史操纵的基础。压缩或 tool-result-prune 插件追加一个既有的消息产出事件类型（例如一条携带摘要的 `user/message`），附带 `surfaceOp: { op: 'replace', start, end }` 和覆盖被遮蔽条目的 `sourceEventSeqs`——新事件在 surface 上取代该范围的位置，而插件自身的 trace 事件（如 `compaction/start`、`compaction/end`）不进入 surface。回放以确定性方式保留该决策。
+Surface 是历史操纵赖以落地的基础——dsh-compact 的压缩就搭载于其上。压缩或 tool-result-prune 插件追加一个既有的消息产出事件类型（例如一条携带摘要的 `user/message`），附带 `surfaceOp: { op: 'replace', start, end }` 和覆盖被遮蔽条目的 `sourceEventSeqs`——新事件在 surface 上取代该范围的位置，而插件自身的 trace 事件（如 `compaction/start`、`compaction/end`）不进入 surface。回放以确定性方式保留该决策。
 
 一次 `tool/result` 替换只能改写当前的一个 `tool/result`，并且必须保留除 `content` 以外的每个数据字段。Session 接纳会与位置范围和引用的源事件校验一起强制这条规则，不依赖可选的诊断插件。
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
index 702a9035d5..00cff75149 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.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 .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
-2026-06-18-shared-persistence-write-coordinator.md: 1d373317664f605e5164e2eb6980b8fa7c6b4e05
-2026-06-18-shared-persistence-write-coordinator.zh.md: 607f1fe68d1404a56c84848c8561cf8749daab0b
+2026-06-18-shared-persistence-write-coordinator.md: c376bb4a209a250d33274dfd60531475354ba363
+2026-06-18-shared-persistence-write-coordinator.zh.md: 06a2dafc4d14c29bb7758fdc67d3f0f8136983e2
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
index 1d37331766..c376bb4a20 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md
@@ -12,7 +12,7 @@ English | [中文](2026-06-18-shared-persistence-write-coordinator.zh.md)
 
 Extract a backend-agnostic `PersistenceCoordinator` into `dsh-session-persistence`. The coordinator owns the orchestration once; each first-party backend composes one (`new PersistenceCoordinator(ctx, this)`), implements a small `PersistenceBackend` hook interface, and delegates its stateful public methods (`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`) to it. Backend-owned metadata and revision listing bypass the coordinator.
 
-Composition, not inheritance. The coordinator is a concrete class the backend holds, not a base class the backend extends. The Agent Note's risk — "a coordinator must not make unusual backends fight an inheritance hierarchy" — is avoided: a backend exposes only the hooks and cannot reach the coordinator's private orchestration state. A third-party backend MAY still implement the abstract service directly without the coordinator, including immutable logical inspection and the default preparation fallback through `load`.
+Composition, not inheritance. The coordinator is a concrete class the backend holds, not a base class the backend extends. The risk that a coordinator makes unusual backends fight an inheritance hierarchy is avoided: a backend exposes only the hooks and cannot reach the coordinator's private orchestration state. A third-party backend MAY still implement the abstract service directly without the coordinator, including immutable logical inspection and the default preparation fallback through `load`.
 
 The coordinator holds one lifecycle entry for each exact live `Session`: initialization plus a package-private write controller that owns pending events, a fixed batching deadline, the active write, failure retention, and the shared flush barrier. Each `session/event` enters that bounded write path, and `session/flush` bypasses the wait to observe quiescence. The [flush-controller simplification](../simplification/2026-07-23-collapse-persistence-flush-state.md) owns controller consolidation; the [bounded batching decision](2026-08-08-bounded-session-persistence-write-batching.md) owns scheduling cadence.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
index 607f1fe68d..06a2dafc4d 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 将一个后端无关的 `PersistenceCoordinator` 提取到 `dsh-session-persistence` 中。协调器统一拥有编排逻辑；每个第一方后端组合一个协调器实例（`new PersistenceCoordinator(ctx, this)`），实现一个小型 `PersistenceBackend` 钩子接口，并将其有状态的公开方法（`create`/`append`/`prepare`/`load`/`inspect`/`readFrom`）委托给协调器。由后端拥有的元数据与修订版本列举会绕过协调器。
 
-组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。本 Agent Note 的风险——「协调器不得让非常规后端与继承层级作斗争」——由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不可变逻辑检查，以及通过 `load` 实现的默认准备回退。
+组合，而非继承。协调器是后端持有的具体类，不是后端继承的基类。协调器让非常规后端与继承层级作斗争的风险由此规避：后端只暴露钩子，无法触及协调器的私有编排状态。第三方后端仍然可以完全不使用协调器、直接实现抽象服务，包括不可变逻辑检查，以及通过 `load` 实现的默认准备回退。
 
 协调器为每个存活的 `Session` 实例持有一个生命周期条目：初始化，加上一个包私有写入控制器，后者负责待处理事件、固定批处理截止时间、活跃写入、失败保留和共享 flush 屏障。每个 `session/event` 都进入这条有界写入路径，`session/flush` 则绕过等待以观察完全停稳。控制器归并由 [flush 控制器简化](../simplification/2026-07-23-collapse-persistence-flush-state.md)定义；调度节奏由[有界批处理决策](2026-08-08-bounded-session-persistence-write-batching.md)定义。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
index f906aa4336..2270bc6f5f 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.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 .agents/notes/implemented/architecture/2026-06-20-branded-ids.md
-2026-06-20-branded-ids.md: 005706a12769a03e9c8ce66bf631ca0d75ade8b4
-2026-06-20-branded-ids.zh.md: b6b58a8b703d5637a6a5053543193bf9779489ac
+2026-06-20-branded-ids.md: 78242226103fef0eac320cdfac0ccb82292fd9e8
+2026-06-20-branded-ids.zh.md: 613ef81d198f10ec70ca5cb019776e607f4a8a79
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
index 005706a127..7824222610 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.md
@@ -8,7 +8,7 @@ English | [中文](2026-06-20-branded-ids.zh.md)
 
 The harness brands `CallId` (`packages/llm/llm/src/brand.ts`) and the shared agent/session `SessionId` (`packages/core/session/src/types.ts`) using the `Branded<B> = string & { readonly [BRAND]: B }` machinery (owned by the type-only `@deepseek-ai/dsh-brand` package at `packages/util/brand/` — see its [README](../../../../packages/util/brand/README.md)) and a zero-cost cast factory per type. `dsh-brand` also states the governing policy: *"Branding is for ids that cross package boundaries and could plausibly be confused; not every string needs a brand."* That policy is right; the problem is that it is only half-applied. Two gaps let a structurally-identical-but-semantically-wrong string slip through the type checker today.
 
-**Gap 1 — unbranded cross-boundary IDs in the bash seam.** The background-task id is a plain `string`: `BashTask.id: string` (`packages/bash/bash/src/types.ts`), carried as `string` through the whole executor seam (`BashExecutor.get`/`ownerOf`/`readOutput`/`kill(id: string)` in `packages/bash/bash/src/index.ts`) and validated/passed as `string` by the model-facing tools (`validateTaskId`, `assertTaskAccess`, the `task_id` schema arg in `packages/bash/tool-bash/src/index.ts`). It is generated by a per-executor counter — `` `bash-${this.nextTaskId++}` `` in `packages/bash/bash-local/src/index.ts` — which gives it **exactly the same `name-N` shape as `SessionId`'s default** (`` `session-${++counter}` `` in `packages/core/session/src/index.ts`). A bash task id and a session id are trivially swappable at a call site and the compiler says nothing. This is the headline case the user asked about, and it is a model-facing id (the model passes `task_id` back to `bash_output`/`bash_kill`), so a confusion here is reachable from untrusted input.
+**Gap 1 — unbranded cross-boundary IDs in the bash seam.** The background-task id is a plain `string`: `BashTask.id: string` (`packages/bash/bash/src/types.ts`), carried as `string` through the whole executor seam (`BashExecutor.get`/`ownerOf`/`readOutput`/`kill(id: string)` in `packages/bash/bash/src/index.ts`) and validated/passed as `string` by the model-facing tools (`validateTaskId`, `assertTaskAccess`, the `task_id` schema arg in `packages/bash/tool-bash/src/index.ts`). It is generated by a per-executor counter — `` `bash-${this.nextTaskId++}` `` in `packages/bash/bash-local/src/index.ts` — which gives it **exactly the same `name-N` shape as `SessionId`'s default** (`` `session-${++counter}` `` in `packages/core/session/src/index.ts`). A bash task id and a session id are trivially swappable at a call site and the compiler says nothing. It is a model-facing id (the model passes `task_id` back to `bash_output`/`bash_kill`), so a confusion here is reachable from untrusted input.
 
 The bash **owner token** is the related sub-case: `BashExecRequest.owner?: string` and `BashExecSpec.owner: string | undefined` (`packages/bash/bash/src/types.ts`) are documented as a deliberately *opaque* isolation key, but in every live caller the value IS the owning agent's shared `Agent.id`/`SessionId` (`callerToken = (exec) => exec.agent?.id` in `packages/bash/tool-bash/src/index.ts`) wearing a different seam-local name. It is compared for access control (`owner !== callerToken(exec)`), so a mismatched-but-well-typed string here is a cross-session isolation bug the type system currently cannot catch. This is the shared id alias covered by the [unified agent/session identity decision](../simplification/2026-06-20-unify-agent-and-session-id.md).
 
@@ -16,13 +16,13 @@ The bash **owner token** is the related sub-case: `BashExecRequest.owner?: strin
 
 ## Decision
 
-A type-only change. Brands are zero-cost casts; nothing about runtime behavior, serialization, comparison, or the wire format changes. The work is in three parts, all honoring the existing "not every string" policy.
+A type-only change. Brands are zero-cost casts; nothing about runtime behavior, serialization, comparison, or the wire format changes. The decision has three parts, all honoring the existing "not every string" policy.
 
 - **Brand the bash task id.** Add `BashTaskId = Branded<'BashTaskId'>` plus its same-named factory in `packages/bash/bash/src/types.ts` (the package that *owns* the id), importing `Branded` from `@deepseek-ai/dsh-brand` exactly as `SessionId` does. The brand primitive lives in the dependency-free `dsh-brand` utility package precisely so `dsh-bash` can brand its ids by depending on it alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`. Thread it through `BashTask.id`, the `BashExecutor` Service Definition methods (`get`/`ownerOf`/`readOutput`/`kill`), the generation site in `dsh-bash-local` (brand the counter output once, at creation), and the `dsh-tool-bash` validate/access surface (`validateTaskId` returns a `BashTaskId`; `task_id` is branded at the tool boundary where the model's string arrives).
 
 - **Mint a distinct `OwnerToken` brand.** Add `OwnerToken = Branded<'OwnerToken'>` in `packages/bash/bash/src/types.ts`; type `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` as `OwnerToken | undefined`. The `dsh-tool-bash` consumer casts the agent's shared `id` (`SessionId`) into an `OwnerToken` at the boundary — the one place the two vocabularies meet. The bash Service Definition never imports `dsh-session`. (Rationale in the next section.)
 
-- **Stop the brand erosion.** Propagate the existing brands to the `Map` key types and public method params listed under Gap 2 — `Map<SessionId, Session>`, `Map<SessionId, Agent>`, `get(id: SessionId)`, `Map<CallId, …>`, ACP's `SessionId` surface, and the coordinator's `Map<SessionId, …>`. This is the larger mechanical share of the diff and the part that makes the *existing* brands actually load-bearing on lookups, not just on struct fields.
+- **Stop the brand erosion.** Propagate the existing brands to the `Map` key types and public method params listed under Gap 2 — `Map<SessionId, Session>`, `Map<SessionId, Agent>`, `get(id: SessionId)`, `Map<CallId, …>`, ACP's `SessionId` surface, and the coordinator's `Map<SessionId, …>`. This is the larger mechanical share of the change and the part that makes the *existing* brands actually load-bearing on lookups, not just on struct fields.
 
 Illustrative shape (the factory pattern is identical to the three existing brands):
 
@@ -52,11 +52,11 @@ The obvious shortcut is to type `owner` as `SessionId` directly — it always *i
 
 Kept deliberately narrow per the "not every string needs a brand" policy. Each of these is a plausible future brand, deferred with a reason, not a commitment:
 
-- **`ModelId`** (`GenerateOptions.model`, the `LlmService` adapter-registry key) — a real cross-package lookup key (config → agent → llm → adapter); a reasonable next brand, left out only to keep this Agent Note's blast radius focused.
+- **`ModelId`** (`GenerateOptions.model`, the `LlmService` adapter-registry key) — a real cross-package lookup key (config → agent → llm → adapter); a reasonable next brand, left out only to keep this decision's blast radius focused.
 - **`ToolName`** (the `ToolRegistry` key) — author-defined, human-readable, and rarely confused with another id; the weakest candidate, likely not worth a brand.
 - **`ErrorCode`** (`HarnessError.code`) — a closed vocabulary (`ABORTED`, `NO_ADAPTER`, …), not a per-instance id; better served by a string-literal union than a brand, if anything.
 - **Numeric ordinals** — turn number, step number, and the event `seq` are `number`, not `string`, so `Branded<string>` does not apply; a parallel `number & { readonly [BRAND]: B }` variant could brand them, but they are positional ordinals rarely passed across boundaries, so the payoff is low.
-- **Validated construction** — the brand factories are pure casts with no runtime check, and every boundary (ACP `sessionId`, provider-issued `call.id`, the empty-string fallback in `dsh-llm-deepseek`) trusts the raw string today. A `SessionId.parse()` / `isValid()` companion that throws on malformed input at boundaries is a genuine gap, but it is a *runtime-behavior* change with its own design (what is "malformed"? what do we do on failure?) and belongs in its own Agent Note, not bundled into this type-only pass.
+- **Validated construction** — the brand factories are pure casts with no runtime check, and every boundary (ACP `sessionId`, provider-issued `call.id`, the empty-string fallback in `dsh-llm-deepseek`) trusts the raw string today. A `SessionId.parse()` / `isValid()` companion that throws on malformed input at boundaries is a genuine gap, but it is a *runtime-behavior* change with its own design (what is "malformed"? what happens on failure?) and belongs in its own decision, not bundled into this type-only change.
 
 ## Verification
 
@@ -65,5 +65,5 @@ The landed invariants: `BashTaskId` and `OwnerToken` are defined in `dsh-bash` a
 ## Consequences
 
 - **Mechanical churn across two surfaces.** Propagating brands touches the bash seam (Service Definition + Service provider + Consumer) and the ACP session-id surface plus the persistence coordinator. The churn is broad but low-severity: a missed site is a compile error, not a silent bug. The change is observably type-only — no snapshot or e2e behavioral diff. It sits next to the [unified agent/session identity decision](../simplification/2026-06-20-unify-agent-and-session-id.md) because both touch the session-id / owner-token boundary; `OwnerToken` stays distinct from the unified id for the decoupling reason above.
-- **Brands do not validate.** A brand is a confusability guard, not a correctness proof: a *wrong* session id that is still a well-formed string passes the type checker exactly as before. This Agent Note does not close that gap (see Out of scope) — it only stops the *category* error of passing the wrong *kind* of id.
-- **The "where to stop" line stays a judgment call.** Branding `BashTaskId` but not `ToolName`, `OwnerToken` but not `ModelId`, is a taste call about which strings "could plausibly be confused." Reasonable reviewers may want more or fewer; the policy in `brand.ts` is the tie-breaker, and this Agent Note errs toward the ids that are model-facing or used for access control.
+- **Brands do not validate.** A brand is a confusability guard, not a correctness proof: a *wrong* session id that is still a well-formed string passes the type checker exactly as before. This decision does not close that gap (see Out of scope) — it only stops the *category* error of passing the wrong *kind* of id.
+- **The "where to stop" line stays a judgment call.** Branding `BashTaskId` but not `ToolName`, `OwnerToken` but not `ModelId`, is a taste call about which strings "could plausibly be confused." Reasonable reviewers may want more or fewer; the policy in `brand.ts` is the tie-breaker, and this decision errs toward the ids that are model-facing or used for access control.
diff --git a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
index b6b58a8b70..613ef81d19 100644
--- a/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-20-branded-ids.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 harness 使用 `Branded<B> = string & { readonly [BRAND]: B }` 机制，为 `CallId`（`packages/llm/llm/src/brand.ts`）和 agent/会话共享的 `SessionId`（`packages/core/session/src/types.ts`）做 brand 处理；该机制由纯类型包 `@deepseek-ai/dsh-brand` 拥有，位于 `packages/util/brand/`，见其 [README](../../../../packages/util/brand/README.md)，并为每个类型提供零开销的 cast 工厂。`dsh-brand` 还声明了治理策略：*「Branding 用于跨包边界且可能被混淆的 id；不是每个 string 都需要 brand。」* 这条策略是正确的；问题在于它只落实了一半。两处缺口使得结构相同但语义错误的 string 今天仍能通过类型检查器。
 
-**缺口 1：bash seam 中未 brand 的跨边界 ID。** 后台 task id 是普通 `string`：`BashTask.id: string`（`packages/bash/bash/src/types.ts`），作为 `string` 贯穿整个执行器 seam（`packages/bash/bash/src/index.ts` 中的 `BashExecutor.get`/`ownerOf`/`readOutput`/`kill(id: string)`），再由面向模型的工具以 `string` 校验并传递（`validateTaskId`、`assertTaskAccess`、`packages/bash/tool-bash/src/index.ts` 中 `task_id` 的 schema 参数）。它由每执行器计数器生成——`packages/bash/bash-local/src/index.ts` 中的 `` `bash-${this.nextTaskId++}` ``——其形状与 `SessionId` 的默认值**完全相同，都是 `name-N`**（`packages/core/session/src/index.ts` 中的 `` `session-${++counter}` ``）。bash task id 和会话 id 在调用点轻易就能互换，而编译器毫无反应。这是用户询问的核心案例，并且它是面向模型的 id（模型会把 `task_id` 传回 `bash_output`/`bash_kill`），所以该混淆可由不受信任的输入触达。
+**缺口 1：bash seam 中未 brand 的跨边界 ID。** 后台 task id 是普通 `string`：`BashTask.id: string`（`packages/bash/bash/src/types.ts`），作为 `string` 贯穿整个执行器 seam（`packages/bash/bash/src/index.ts` 中的 `BashExecutor.get`/`ownerOf`/`readOutput`/`kill(id: string)`），再由面向模型的工具以 `string` 校验并传递（`validateTaskId`、`assertTaskAccess`、`packages/bash/tool-bash/src/index.ts` 中 `task_id` 的 schema 参数）。它由每执行器计数器生成——`packages/bash/bash-local/src/index.ts` 中的 `` `bash-${this.nextTaskId++}` ``——其形状与 `SessionId` 的默认值**完全相同，都是 `name-N`**（`packages/core/session/src/index.ts` 中的 `` `session-${++counter}` ``）。bash task id 和会话 id 在调用点轻易就能互换，而编译器毫无反应。它是面向模型的 id（模型会把 `task_id` 传回 `bash_output`/`bash_kill`），所以该混淆可由不受信任的输入触达。
 
 bash **owner token** 是相关的子情形：`BashExecRequest.owner?: string` 和 `BashExecSpec.owner: string | undefined`（`packages/bash/bash/src/types.ts`）被文档描述为刻意*不透明*的隔离键，但在所有实际调用方中，该值就是所属 agent（智能体）共享的 `Agent.id`/`SessionId`（`callerToken = (exec) => exec.agent?.id`，位于 `packages/bash/tool-bash/src/index.ts`），只是披着另一个 seam 本地名称。它被用于访问控制比较（`owner !== callerToken(exec)`），因此一个不匹配但类型正确的 string 在此处就是跨会话隔离 bug，而当前类型系统无法捕获。这正是[统一 agent/session 标识决策](../simplification/2026-06-20-unify-agent-and-session-id.md)覆盖的共享 id 别名。
 
@@ -16,13 +16,13 @@ bash **owner token** 是相关的子情形：`BashExecRequest.owner?: string` 
 
 ## 决策
 
-纯类型变更。Brand 是零开销 cast；运行时行为、序列化、比较和协议格式（wire format）均不变。工作分三部分，全部遵循既有的「不是每个 string 都需要」策略。
+纯类型变更。Brand 是零开销 cast；运行时行为、序列化、比较和协议格式（wire format）均不变。该决策分三部分，全部遵循既有的「不是每个 string 都需要」策略。
 
 - **为 bash task id 加 brand。** 在 `packages/bash/bash/src/types.ts`（*拥有*该 id 的包）中添加 `BashTaskId = Branded<'BashTaskId'>` 及其同名工厂，从 `@deepseek-ai/dsh-brand` 导入 `Branded`，方式与 `SessionId` 完全一致。brand 原语位于无依赖的 `dsh-brand` 工具包中，正是为了让 `dsh-bash` 仅依赖它就能为自己的 id 加 brand，而无需引入 `dsh-llm`（或 `dsh-session`）来获取 `Branded`。将其贯穿 `BashTask.id`、`BashExecutor` Service Definition 方法（`get`/`ownerOf`/`readOutput`/`kill`）、`dsh-bash-local` 中的生成点（在创建时对计数器输出做一次 brand），以及 `dsh-tool-bash` 的校验/访问面（`validateTaskId` 返回 `BashTaskId`；`task_id` 在模型 string 到达的工具边界处被 brand）。
 
 - **铸造独立的 `OwnerToken` brand。** 在 `packages/bash/bash/src/types.ts` 中添加 `OwnerToken = Branded<'OwnerToken'>`；将 `BashExecRequest.owner` / `BashExecSpec.owner` / `BashExecutor.ownerOf` 的类型标注为 `OwnerToken | undefined`。`dsh-tool-bash` 消费方在边界处将 agent 共享的 `id`（`SessionId`）cast 为 `OwnerToken`——这是两套词汇唯一交汇的地方。bash Service Definition 从不导入 `dsh-session`。（理由见下一节。）
 
-- **阻止 brand 侵蚀。** 将既有 brand 传播到缺口 2 列出的 `Map` 键类型和公开方法参数中：`Map<SessionId, Session>`、`Map<SessionId, Agent>`、`get(id: SessionId)`、`Map<CallId, …>`、ACP 的 `SessionId` surface、协调器的 `Map<SessionId, …>`。这是 diff 中机械量最大的部分，也是让*既有* brand 在查找处真正发挥作用（而不仅仅标注在结构体字段上）的关键。
+- **阻止 brand 侵蚀。** 将既有 brand 传播到缺口 2 列出的 `Map` 键类型和公开方法参数中：`Map<SessionId, Session>`、`Map<SessionId, Agent>`、`get(id: SessionId)`、`Map<CallId, …>`、ACP 的 `SessionId` surface、协调器的 `Map<SessionId, …>`。这是变更中机械量最大的部分，也是让*既有* brand 在查找处真正发挥作用（而不仅仅标注在结构体字段上）的关键。
 
 示意形状（工厂模式与已有的三个 brand 完全一致）：
 
@@ -52,11 +52,11 @@ export function OwnerToken(id: string): OwnerToken {
 
 遵循「不是每个 string 都需要 brand」的策略，刻意保持窄范围。以下每项都是合理的未来 brand 候选，附带推迟理由而非承诺：
 
-- **`ModelId`**（`GenerateOptions.model`，`LlmService` 适配器注册表的键）：一个真正的跨包查找键（config → agent → llm → 适配器）；合理的下一个 brand，仅为控制本 Agent Note 的影响范围而暂不纳入。
+- **`ModelId`**（`GenerateOptions.model`，`LlmService` 适配器注册表的键）：一个真正的跨包查找键（config → agent → llm → 适配器）；合理的下一个 brand，仅为控制本决策的影响范围而暂不纳入。
 - **`ToolName`**（`ToolRegistry` 的键）：由作者定义、人类可读，且很少与其他 id 混淆；最弱的候选，可能不值得加 brand。
 - **`ErrorCode`**（`HarnessError.code`）：一个封闭词汇（`ABORTED`、`NO_ADAPTER`……），不是逐实例的 id；如果要做，string 字面量联合类型比 brand 更合适。
 - **数值序号**：轮次号、步骤号和事件 `seq` 是 `number` 而非 `string`，`Branded<string>` 不适用；可以用并行的 `number & { readonly [BRAND]: B }` 变体来 brand 它们，但它们是位置序号、很少跨边界传递，收益较低。
-- **带校验的构造**：brand 工厂是纯 cast，无运行时检查，且每个边界（ACP `sessionId`、提供方签发的 `call.id`、`dsh-llm-deepseek` 中的空字符串回退）今天都信任裸 string。一个在边界处对格式错误的输入抛异常的 `SessionId.parse()` / `isValid()` 配套工具确实是缺口，但它是*运行时行为*变更，有自己的设计问题（什么算「格式错误」？失败时怎么办？），应在独立 Agent Note 中处理，不应捆绑进这次纯类型变更。
+- **带校验的构造**：brand 工厂是纯 cast，无运行时检查，且每个边界（ACP `sessionId`、提供方签发的 `call.id`、`dsh-llm-deepseek` 中的空字符串回退）今天都信任裸 string。一个在边界处对格式错误的输入抛异常的 `SessionId.parse()` / `isValid()` 配套工具确实是缺口，但它是*运行时行为*变更，有自己的设计问题（什么算「格式错误」？失败时会怎样？），应在独立决策中处理，不应捆绑进这次纯类型变更。
 
 ## 验证
 
@@ -65,5 +65,5 @@ export function OwnerToken(id: string): OwnerToken {
 ## 后果
 
 - **两个接口面的机械性改动。** 传播 brand 涉及 bash seam（Service Definition + Service provider + Consumer）以及 ACP 会话 id 接口和持久化协调器。改动面广但严重度低：遗漏的位置是编译错误而非静默 bug。变更可观察地为纯类型变更——无快照或 e2e 行为差异。它与[统一 agent/会话标识决策](../simplification/2026-06-20-unify-agent-and-session-id.md)相邻，因为二者都触及会话 id / owner-token 边界；`OwnerToken` 出于上述解耦理由仍与统一后的 id 保持独立。
-- **Brand 不做校验。** Brand 是混淆防护，不是正确性证明：一个*错误的*会话 id 只要仍是格式正确的 string，就和以前一样能通过类型检查器。本 Agent Note 不关闭这个缺口（见「不在范围内」）——它只阻止这类*类别*错误：传入错误*种类*的 id。
-- **「在哪里停下」仍是判断题。** 为 `BashTaskId` 加 brand 但不为 `ToolName` 加，为 `OwnerToken` 加但不为 `ModelId` 加，是对哪些 string「可能被混淆」的品味判断。合理的评审者可能想要更多或更少；`brand.ts` 中的策略是裁决依据，本 Agent Note 倾向于面向模型或用于访问控制的 id。
+- **Brand 不做校验。** Brand 是混淆防护，不是正确性证明：一个*错误的*会话 id 只要仍是格式正确的 string，就和以前一样能通过类型检查器。本决策不关闭这个缺口（见「不在范围内」）——它只阻止这类*类别*错误：传入错误*种类*的 id。
+- **「在哪里停下」仍是判断题。** 为 `BashTaskId` 加 brand 但不为 `ToolName` 加，为 `OwnerToken` 加但不为 `ModelId` 加，是对哪些 string「可能被混淆」的品味判断。合理的评审者可能想要更多或更少；`brand.ts` 中的策略是裁决依据，本决策倾向于面向模型或用于访问控制的 id。
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
index 32db924032..21c6e32e11 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.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 .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
-2026-06-21-mandatory-app-attribution-headers.md: 71e74e753c39c8eddfe886d69ee9f28edff9ebab
-2026-06-21-mandatory-app-attribution-headers.zh.md: 9cc2c178cd83f3f041282a0dac34b70f78bcc467
+2026-06-21-mandatory-app-attribution-headers.md: 12482ca80d19e5cd1e62b8860865db6cccea61ab
+2026-06-21-mandatory-app-attribution-headers.zh.md: 43f356887948b88d34ba41d46ed1cd2f1c89a1e2
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
index 71e74e753c..12482ca80d 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
@@ -26,9 +26,9 @@ The immediate prompt came from OpenRouter's [App Attribution](https://openrouter
 
 Provider request attribution is mandatory at the LLM adapter boundary, using the standard `User-Agent` header only. The rule: every product LLM adapter sends a static, non-secret application identity on every provider HTTP request, and every adapter has tests proving that `User-Agent` reaches the wire (a mock server asserting received headers; for a library-backed adapter, the library's header hook feeding the same mock-server assertion).
 
-Do **not** implement OpenRouter app attribution in this Agent Note. `HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, and `X-OpenRouter-Categories` are OpenRouter-specific product-surface headers, not provider-neutral model-request attribution. They can be proposed later by an OpenRouter adapter or explicit OpenRouter mode, with its own privacy/product decision, tests, and docs. Until then, even requests pointed at OpenRouter send only the shared `User-Agent` attribution from this Agent Note.
+OpenRouter app attribution is deliberately not implemented. `HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, and `X-OpenRouter-Categories` are OpenRouter-specific product-surface headers, not provider-neutral model-request attribution. They can be proposed later by an OpenRouter adapter or explicit OpenRouter mode, with its own privacy/product decision, tests, and docs. Until then, even requests pointed at OpenRouter send only the shared `User-Agent` attribution from this decision.
 
-The provider-neutral identity is owned by `dsh-llm` (`packages/llm/llm/src/attribution.ts`), not by individual adapters. `AppIdentity` contains only public product facts needed to build `User-Agent`, and the default `APP_IDENTITY` settles the values the proposal left open:
+The provider-neutral identity is owned by `dsh-llm` (`packages/llm/llm/src/attribution.ts`), not by individual adapters. `AppIdentity` contains only public product facts needed to build `User-Agent`, and the default `APP_IDENTITY` values:
 
 - product token for `User-Agent`: `deepseek-harness` (continuity with the pre-Agent Note wire value and the repo/org identity)
 - version: read from the owning package's manifest via `createRequire`, never a hand-copied constant
@@ -42,7 +42,7 @@ Wire mapping (`attributionHeaders`; header names lowercase in code - HTTP field
 |---|---|
 | All HTTP-based adapters | `User-Agent: {product}/{version} (+{url})` - the parenthesized `+url` comment stays within RFC 9110's conservative product/comment syntax. |
 | Direct DeepSeek endpoint | `User-Agent`; do not send OpenRouter-only headers unless DeepSeek documents an equivalent contract. |
-| OpenRouter endpoints | `User-Agent` only for now. Do not send `HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, or `X-OpenRouter-Categories` under this Agent Note. |
+| OpenRouter endpoints | `User-Agent` only for now. Do not send `HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, or `X-OpenRouter-Categories` under this decision. |
 | Future providers | `User-Agent` only unless a later provider-specific Agent Note accepts additional headers. Do not reuse `HTTP-Referer` by analogy. |
 
 Endpoint detection is not part of this Agent Note because no endpoint-specific mapping is accepted here. If OpenRouter support lands later, detection must be explicit: either a dedicated OpenRouter provider package or an explicit `provider: 'openrouter'` / `attributionTarget: 'openrouter'` config, not arbitrary path fragments or model names.
@@ -55,13 +55,13 @@ The landed contract:
 - A shared helper (`attributionHeaders` / `userAgent`) constructs the app identity and the standard `User-Agent` value from package metadata, so adapters do not hand-copy version constants.
 - `dsh-llm-deepseek` sends the shared `User-Agent` on every request and its mock-server suite asserts the exact value.
 - `dsh-llm-pi-ai` sends the same `User-Agent` through pi-ai's `StreamOptions.headers` hook and its mock-server suite asserts the exact value.
-- No adapter sends OpenRouter-specific attribution headers (`HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, `X-OpenRouter-Categories`) as part of this Agent Note.
+- No adapter sends OpenRouter-specific attribution headers (`HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, `X-OpenRouter-Categories`) as part of this decision.
 - No app-attribution field carries secrets, local paths, session ids, prompt text, model output, user email, or per-user stable identifiers.
 - The adapter READMEs state the `User-Agent` attribution policy and explicitly avoid documenting OpenRouter app attribution as implemented behavior.
 
 ## Alternatives considered
 
-**OpenRouter app attribution now.** Rejected for this Agent Note. Sending `HTTP-Referer` plus `X-OpenRouter-Title` would satisfy OpenRouter rankings, but those headers are a provider-specific product feature, not the provider-neutral model-request attribution this Agent Note is trying to standardize. Supporting them should be an explicit OpenRouter adapter/mode decision later, not hidden inside the first shared attribution helper.
+**OpenRouter app attribution now.** Rejected for this decision. Sending `HTTP-Referer` plus `X-OpenRouter-Title` would satisfy OpenRouter rankings, but those headers are a provider-specific product feature, not the provider-neutral model-request attribution this decision standardizes. Supporting them should be an explicit OpenRouter adapter/mode decision later, not hidden inside the first shared attribution helper.
 
 **OpenRouter headers everywhere.** Rejected. It would treat a custom OpenRouter contract as a universal standard and send fields with misleading semantics to providers that did not ask for them. It also risks using `HTTP-Referer` as a generic app URL field even though standard HTTP already has `User-Agent` for product identity and `Referer` for a different browsing-context concept.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
index 9cc2c178cd..43f3568879 100644
--- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md
@@ -26,9 +26,9 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 
 在 LLM 适配器边界，提供方请求归属是强制的，且仅使用标准 `User-Agent` 头部。规则：每个产品级 LLM 适配器在每个提供方 HTTP 请求上发送一个静态、非机密的应用身份，且每个适配器都有测试证明 `User-Agent` 到达了线路（mock 服务器断言收到的头部；对于基于库的适配器，通过库的头部钩子馈入同一个 mock 服务器断言）。
 
-本 Agent Note **不**实现 OpenRouter 应用归属。`HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 和 `X-OpenRouter-Categories` 是 OpenRouter 特有的产品展示头部，不是提供方无关的模型请求归属。它们可以后续由 OpenRouter 适配器或显式 OpenRouter 模式提出，附带自己的隐私/产品决策、测试和文档。在此之前，即使请求指向 OpenRouter，也只发送本 Agent Note 定义的共享 `User-Agent` 归属。
+OpenRouter 应用归属刻意未实现。`HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 和 `X-OpenRouter-Categories` 是 OpenRouter 特有的产品展示头部，不是提供方无关的模型请求归属。它们可以后续由 OpenRouter 适配器或显式 OpenRouter 模式提出，附带自己的隐私/产品决策、测试和文档。在此之前，即使请求指向 OpenRouter，也只发送本决策定义的共享 `User-Agent` 归属。
 
-提供方无关的身份由 `dsh-llm`（`packages/llm/llm/src/attribution.ts`）拥有，而非各适配器。`AppIdentity` 仅包含构建 `User-Agent` 所需的公开产品事实，默认的 `APP_IDENTITY` 确定了提案中留待决定的值：
+提供方无关的身份由 `dsh-llm`（`packages/llm/llm/src/attribution.ts`）拥有，而非各适配器。`AppIdentity` 仅包含构建 `User-Agent` 所需的公开产品事实，默认的 `APP_IDENTITY` 取值如下：
 
 - `User-Agent` 的产品 token：`deepseek-harness`（与 Agent Note 之前的线路值及仓库/组织身份保持连续性）
 - 版本：通过 `createRequire` 从所属包的 manifest（元数据清单）读取，绝不手动复制常量
@@ -42,7 +42,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 |---|---|
 | 所有基于 HTTP 的适配器 | `User-Agent: {product}/{version} (+{url})`——括号中的 `+url` 注释符合 RFC 9110 保守的 product/comment 语法。 |
 | 直连 DeepSeek 端点 | `User-Agent`；除非 DeepSeek 文档化了等效约定，否则不发送 OpenRouter 特有头部。 |
-| OpenRouter 端点 | 目前仅 `User-Agent`。本 Agent Note 下不发送 `HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 或 `X-OpenRouter-Categories`。 |
+| OpenRouter 端点 | 目前仅 `User-Agent`。本决策下不发送 `HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 或 `X-OpenRouter-Categories`。 |
 | 未来提供方 | 仅 `User-Agent`，除非后续提供方特有的 Agent Note 接受额外头部。不要类比复用 `HTTP-Referer`。 |
 
 端点检测不在本 Agent Note 范围内，因为此处不接受任何端点特有的映射。如果后续支持 OpenRouter，检测必须是显式的：要么是专门的 OpenRouter 提供方包，要么是显式的 `provider: 'openrouter'` / `attributionTarget: 'openrouter'` 配置，而非任意路径片段或模型名称。
@@ -55,13 +55,13 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。
 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。
 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。
-- 本 Agent Note 下没有适配器发送 OpenRouter 特有的归属头部（`HTTP-Referer`、`X-OpenRouter-Title`、`X-Title`、`X-OpenRouter-Categories`）。
+- 本决策下没有适配器发送 OpenRouter 特有的归属头部（`HTTP-Referer`、`X-OpenRouter-Title`、`X-Title`、`X-OpenRouter-Categories`）。
 - 没有应用归属字段携带机密、本地路径、会话 id、提示词文本、模型输出、用户邮箱或逐用户的稳定标识符。
 - 适配器 README 声明了 `User-Agent` 归属策略，并明确避免将 OpenRouter 应用归属记录为已实现的行为。
 
 ## 曾考虑的替代方案
 
-**现在就实现 OpenRouter 应用归属。** 本 Agent Note 否决。发送 `HTTP-Referer` 加 `X-OpenRouter-Title` 可以满足 OpenRouter 排名，但这些头部是提供方特有的产品功能，不是本 Agent Note 试图标准化的提供方无关的模型请求归属。支持它们应当是后续显式的 OpenRouter 适配器/模式决策，而非隐藏在首个共享归属辅助函数中。
+**现在就实现 OpenRouter 应用归属。** 本决策否决。发送 `HTTP-Referer` 加 `X-OpenRouter-Title` 可以满足 OpenRouter 排名，但这些头部是提供方特有的产品功能，不是本决策所标准化的提供方无关的模型请求归属。支持它们应当是后续显式的 OpenRouter 适配器/模式决策，而非隐藏在首个共享归属辅助函数中。
 
 **向所有提供方发送 OpenRouter 头部。** 否决。这会把一项自定义的 OpenRouter 惯例当作通用标准，并向未要求这些字段的提供方发送语义误导的头部。还有风险将 `HTTP-Referer` 当作通用应用 URL 字段使用，尽管标准 HTTP 已有 `User-Agent` 用于产品身份、`Referer` 用于不同的浏览上下文概念。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
index 4147d8dc12..2824639954 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.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 .agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
-2026-06-24-web-capability-seam.md: 3893c9f9d45eac90c9ae381f9fa92ad8c7ae7644
-2026-06-24-web-capability-seam.zh.md: 70745c235d17e3cbf6152c2ef470283b0bad85f2
+2026-06-24-web-capability-seam.md: ccf04420425555055ce3810d25bf764db17322bb
+2026-06-24-web-capability-seam.zh.md: 73f7d0d9b82c03d41bdc768f22b22316e1bc907f
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
index 3893c9f9d4..ccf0442042 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
@@ -327,10 +327,10 @@ Rejected for the seam. `prompt` turns fetch into LLM summarization and couples p
 - SSRF / private-network protection for `web_fetch`: block private, loopback, link-local, multicast, and otherwise non-public destinations so `web_fetch` is not an SSRF primitive. Doing it correctly is more than a URL-string check — it needs DNS-resolve-then-connect-to-the-validated-IP (to defeat DNS rebinding / TOCTOU), per-hop re-validation across redirects, and IPv6 edge handling (private ranges, IPv4-mapped addresses). Neither reference implementation surveyed does IP-level blocking (OpenCode does a prefix check then fetches; Claude Code relies on a centralized hostname blocklist plus a "private URLs will fail" prompt), so there is no implementation to copy and this is the harness's only SSRF defense — it warrants its own focused design/spike. Until it lands, `web_fetch` must only be enabled in deployments that cannot reach sensitive internal targets.
 - A `pdf` `WebFetchBody` kind: the `local-http` provider decodes text-extractable PDFs (best-effort, capped, `truncated`) into a `{ kind: 'pdf'; content; pageCount? }` arm, and `tool-web` renders it. This is fetch, not `web_extract` — PDF retrieval is a concrete HTTP 200 plus deterministic local decoding, not provider-side extraction of a non-HTTP resource. Adding it is a coordinated change across `dsh-web` (declare the arm), the provider (decode + narrow "binary rejection" to "reject binary except text-extractable PDF"; scanned/image PDFs needing OCR stay out of scope), and `tool-web` (render). The closed `WebFetchBody` union makes the consumer side fail to compile until the new arm is handled.
 - Provider-backed extraction as a separate `web_extract` capability, rather than widening `web_fetch` silently.
-- Permission policy integration once the deferred permission system lands.
+- Permission policy integration: the permission system now exists ([sandbox and approval](../feature/2026-07-06-sandbox.md), [web permission presets](../feature/2026-07-23-web-permission-and-approval.md)) but bundles only sandbox mode and approval policy; web permission policy remains unintegrated.
 - Provider-neutral search controls beyond `query` and `maxResults`, once Exa and Perplexity can both honor them honestly.
 
 ## Open questions
 
 - Should product app packages probe web configuration at startup (treating `WEB_PROVIDER_CONFIGURED_MISSING`, `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`, and `WEB_PROVIDER_AMBIGUOUS` as fatal when web is explicitly configured), or leave misconfiguration to surface at the first execution?
-- Where should permission policy for public web access live once the deferred permission system lands: a dedicated web permission plugin on `tools/execute`, provider config, or both?
+- Where should permission policy for public web access live in the shipped permission system ([sandbox and approval](../feature/2026-07-06-sandbox.md), [web permission presets](../feature/2026-07-23-web-permission-and-approval.md)): a dedicated web permission plugin on `tools/execute`, provider config, or both?
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
index 70745c235d..73f7d0d9b8 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
@@ -329,10 +329,10 @@ SSRF/私有网络防护（阻断私有、回环、链路本地、多播及其他
 - `web_fetch` 的 SSRF/私有网络防护：阻断私有、回环、链路本地、多播及其他非公开目的地，使 `web_fetch` 不再是 SSRF 原语。正确实现不仅仅是 URL 字符串检查——需要先 DNS 解析再连接到已验证的 IP（防御 DNS rebinding/TOCTOU）、跨重定向的每跳重新验证，以及 IPv6 边缘处理（私有范围、IPv4 映射地址）。所调研的参考实现均未做 IP 级阻断（OpenCode 做前缀检查后直接 fetch；Claude Code 依赖集中式主机名黑名单加「私有 URL 会失败」的提示词），因此没有可复制的实现，且这是 harness 唯一的 SSRF 防线——值得一次专门的设计/spike。在其落地之前，`web_fetch` 只能在无法触达敏感内部目标的部署中启用。
 - `pdf` `WebFetchBody` 类别：`local-http` 提供方将可文本提取的 PDF 解码（尽力而为、有上限、`truncated`）为 `{ kind: 'pdf'; content; pageCount? }` 分支，`tool-web` 渲染它。这是 fetch 而非 `web_extract`——PDF 获取是具体的 HTTP 200 加确定性的本地解码，不是提供方侧对非 HTTP 资源的提取。添加它是跨 `dsh-web`（声明分支）、提供方（解码 + 将「二进制拒绝」收窄为「拒绝二进制，但可文本提取的 PDF 除外」；需要 OCR 的扫描/图片 PDF 不在范围内）和 `tool-web`（渲染）的协调变更。封闭的 `WebFetchBody` 联合类型使消费方在新分支被处理之前编译失败。
 - 提供方支撑的提取作为独立的 `web_extract` 能力，而非静默扩展 `web_fetch`。
-- 推迟的权限系统落地后的权限策略集成。
+- 权限策略集成：权限系统现已存在（[沙箱与审批](../feature/2026-07-06-sandbox.md)、[web 权限预设](../feature/2026-07-23-web-permission-and-approval.md)），但只捆绑了沙箱模式与审批策略；web 权限策略仍未集成。
 - `query` 和 `maxResults` 之外的提供方无关搜索控制，待 Exa 和 Perplexity 都能诚实遵守时再添加。
 
 ## 开放问题
 
 - 产品应用包是否应在启动时探测 web 配置（当 web 被显式配置时将 `WEB_PROVIDER_CONFIGURED_MISSING`、`WEB_PROVIDER_CONFIGURED_UNAVAILABLE` 和 `WEB_PROVIDER_AMBIGUOUS` 视为致命错误），还是将配置错误留到首次执行时浮出？
-- 推迟的权限系统落地后，公开 web 访问的权限策略应放在哪里：`tools/execute` 上的专用 web 权限插件、提供方配置，还是两者兼有？
+- 在已交付的权限系统（[沙箱与审批](../feature/2026-07-06-sandbox.md)、[web 权限预设](../feature/2026-07-23-web-permission-and-approval.md)）中，公开 web 访问的权限策略应放在哪里：`tools/execute` 上的专用 web 权限插件、提供方配置，还是两者兼有？
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
index a8acbaf10e..c2d46de08f 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.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 .agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
-2026-06-26-file-context-as-event-gate.md: 353beb2498a310eee8cc794fa5edc22915fd6ad0
-2026-06-26-file-context-as-event-gate.zh.md: 37d7c1e4d971896a0e6ddeb42650635b8f755ca0
+2026-06-26-file-context-as-event-gate.md: 743c8f150a83f2452cb0ff672860b8462a56f762
+2026-06-26-file-context-as-event-gate.zh.md: cd79b44dd3f3b75c5e5addc5be10c02bd1ce0151
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
index 353beb2498..743c8f150a 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md
@@ -112,7 +112,7 @@ The `fs/*` decision events are **unbound waterfalls dispatched by the tool** (li
 
 ## Tool contract (`dsh-tool-fs`)
 
-The tool keeps its model-facing schemas (`read`/`write`/`edit`, byte-for-byte unchanged) and prompt sections. The prompt guidance stays policy-first because a deployment loading the fs tools is expected to also load `dsh-fs-policy`: the model is still told to read before overwriting or editing, and any wording that says the "backend" requires that should be corrected to say the fs-policy plugin requires it. The bare-provider fallback does not change the prompt stance.
+The tool keeps its model-facing schemas (`read`/`write`/`edit`, byte-for-byte unchanged) and prompt sections. The prompt guidance stays policy-first because a deployment loading the fs tools is expected to also load `dsh-fs-policy`: the model is still told to read before overwriting or editing, and that requirement is the fs-policy plugin's, not the backend's. The bare-provider fallback does not change the prompt stance.
 
 `dsh-tool-fs` gains the executor responsibilities relocated from the old `fileContext` method service, including **read rendering** (`read-render.ts`: `buildWindow` + `formatReadOutput`, `READ_MAX_BYTES`, `READ_MAX_LINE_LENGTH`, `FileReadOutcome`/`FileTextLine`, plus `STREAM_MIN_SIZE` in `read.ts`), which is the tool's rendering detail now that the tool owns the read. Those read-rendering types and helpers move into `dsh-tool-fs`; the policy plugin must not remain a type dependency for the tool.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
index 37d7c1e4d9..cd79b44dd3 100644
--- a/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.zh.md
@@ -112,7 +112,7 @@ interface Events {
 
 ## 工具约定（`dsh-tool-fs`）
 
-工具保留其面向模型的 schema（`read`/`write`/`edit`，逐字节不变）和提示词段落。提示词引导仍以策略优先，因为加载 fs 工具的部署预期也会加载 `dsh-fs-policy`：模型仍被告知在覆写或编辑前先读取，任何声称「后端」要求如此的措辞应修正为 fs-policy 插件要求如此。裸提供方回退不改变提示词立场。
+工具保留其面向模型的 schema（`read`/`write`/`edit`，逐字节不变）和提示词段落。提示词引导仍以策略优先，因为加载 fs 工具的部署预期也会加载 `dsh-fs-policy`：模型仍被告知在覆写或编辑前先读取，而该要求来自 fs-policy 插件，并非后端。裸提供方回退不改变提示词立场。
 
 `dsh-tool-fs` 获得从旧 `fileContext` 方法服务迁移来的执行器职责，包括**读取渲染**（`read-render.ts`：`buildWindow` + `formatReadOutput`、`READ_MAX_BYTES`、`READ_MAX_LINE_LENGTH`、`FileReadOutcome`/`FileTextLine`，以及 `read.ts` 中的 `STREAM_MIN_SIZE`），这些现在是工具的渲染细节，因为读取已由工具拥有。这些读取渲染类型和辅助函数移入 `dsh-tool-fs`；策略插件不得继续作为工具的类型依赖。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
index 8201388c72..a1fac69cf4 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.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 .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
-2026-06-30-bash-stdin-env-trusted-plugin-surface.md: 1c2cfc4257e93b2f2f126947e93b38aa2d4cd570
-2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 050f604259033f20be8174754c32f624e9a0ce76
+2026-06-30-bash-stdin-env-trusted-plugin-surface.md: d8193b47ff16da7efb5f6bf1c3f34c0e1251572c
+2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 7f5bb62d92f27c49b0f7f262dc64dce39c89f2cd
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
index 1c2cfc4257..d8193b47ff 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md)
 
 ## Problem
 
-The hooks subsystem runs external hook commands the way Claude Code and Codex do: a hook is a shell command that receives its event payload as **JSON on stdin** and reads context from a handful of **environment variables** (`CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `PLUGIN_ROOT`, …). The harness already has a perfectly good command runner behind the `ctx.bash` capability seam ([dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)), with process-group kills, output truncation/spill, and a credential scrub. Reusing it for hook execution means a hook bridge does not re-implement subprocess plumbing — but the seam had no way to write stdin or set extra env. This Agent Note adds those two inputs.
+The hooks subsystem runs external hook commands the way Claude Code and Codex do: a hook is a shell command that receives its event payload as **JSON on stdin** and reads context from a handful of **environment variables** (`CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `PLUGIN_ROOT`, …). The harness already has a perfectly good command runner behind the `ctx.bash` capability seam ([dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)), with process-group kills, output truncation/spill, and a credential scrub. Reusing it for hook execution means a hook bridge does not re-implement subprocess plumbing — but the seam had no way to write stdin or set extra env. This change adds those two inputs.
 
 `stdin` and `env` do not create a new model capability because ordinary shell syntax already supplies both. Ambient credentials are protected by `dsh-bash-local`'s child-environment scrub, not by hiding these Service Definition fields; model tool arguments are static JSON and do not expand shell variables. The fields therefore serve trusted in-process callers, such as hook bridges, that need to pass structured input and `CLAUDE_*` variables without embedding them in model-visible shell text. See [defensive-patterns.md](../../../../docs/defensive-patterns.md) for the ambient-environment rule.
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
index 050f604259..7f5bb62d92 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-钩子子系统以 Claude Code 和 Codex 的方式运行外部钩子命令：钩子是一条 shell 命令，通过 **stdin 上的 JSON** 接收事件载荷，并从若干**环境变量**（`CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT`、`PLUGIN_ROOT`……）读取上下文。harness 已经在 `ctx.bash` 能力 seam 后面有一个完善的命令执行器（[dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)），具备进程组终止、输出截断/溢出处理和凭证擦除功能。复用它来执行钩子意味着钩子桥接层无需重新实现子进程管道——但该 seam 此前无法写入 stdin 或设置额外 env。本 Agent Note 添加这两个输入。
+钩子子系统以 Claude Code 和 Codex 的方式运行外部钩子命令：钩子是一条 shell 命令，通过 **stdin 上的 JSON** 接收事件载荷，并从若干**环境变量**（`CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT`、`PLUGIN_ROOT`……）读取上下文。harness 已经在 `ctx.bash` 能力 seam 后面有一个完善的命令执行器（[dsh-bash](../../../../packages/bash/bash) → [dsh-bash-local](../../../../packages/bash/bash-local)），具备进程组终止、输出截断/溢出处理和凭证擦除功能。复用它来执行钩子意味着钩子桥接层无需重新实现子进程管道——但该 seam 此前无法写入 stdin 或设置额外 env。本次变更添加这两个输入。
 
 `stdin` 和 `env` 不构成新的模型能力，因为普通 shell 语法已经能提供两者。环境凭证由 `dsh-bash-local` 的子环境擦除机制保护，而非靠隐藏这些 Service Definition 字段；模型工具参数是静态 JSON，不会展开 shell 变量。因此这些字段服务于受信的进程内调用方（如钩子桥接层），它们需要传递结构化输入和 `CLAUDE_*` 变量，而不必将其嵌入模型可见的 shell 文本。环境变量规则见 [defensive-patterns.md](../../../../docs/defensive-patterns.md)。
 
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
index fab7f4d6d6..8916c347d9 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.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 .agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
-2026-06-30-event-domain-semantics.md: a3af693126b71c5844260f53c62b4ab4a28fe56f
-2026-06-30-event-domain-semantics.zh.md: 1f6df779fdccb921861f6ea848e33d9cd866b027
+2026-06-30-event-domain-semantics.md: dbb3ef49979b7eeaa9a43b7db4a2d5a5839b5569
+2026-06-30-event-domain-semantics.zh.md: 93fe14adeaa47d276219a316ff1250a9982f5f14
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
index a3af693126..dbb3ef4997 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.md
@@ -12,7 +12,7 @@ The harness extends the agent loop through a Cordis event taxonomy (see [the mic
 - `agent/*` carries live runtime signals that hand a plugin the `Agent` handle.
 - `tools/*` carries the tool registry and execution pipeline.
 
-Two problems motivated pinning the semantics down. First, several turn/step boundaries existed BOTH as a durable `SessionEvent` (`turn/start`, `turn/end`, `step/start`, `step/end`) AND as a mirrored `agent/*` emit (`agent/turn-start`, `agent/turn-end`, `agent/step-start`, `agent/step-end`). A consumer had two sources of truth for the same fact, and every lifecycle change had to update both. Second, the upcoming Hooks subsystem needs ONE coherent, documented surface to subscribe to — a plugin author (and the Claude Code / Codex hook bridges built on top) must know, without reading the loop, whether to listen on a session event or an agent event, and why.
+Two problems motivated pinning the semantics down. First, several turn/step boundaries existed BOTH as a durable `SessionEvent` (`turn/start`, `turn/end`, `step/start`, `step/end`) AND as a mirrored `agent/*` emit (`agent/turn-start`, `agent/turn-end`, `agent/step-start`, `agent/step-end`). A consumer had two sources of truth for the same fact, and every lifecycle change had to update both. Second, the Hooks subsystem needs ONE coherent, documented surface to subscribe to — a plugin author (and the Claude Code / Codex hook bridges built on top) must know, without reading the loop, whether to listen on a session event or an agent event, and why.
 
 This vocabulary is the foundation for interception decisions, the durable `hook/*` log, and the Claude Code and Codex bridges.
 
@@ -34,6 +34,6 @@ This vocabulary is the foundation for interception decisions, the durable `hook/
 - Tests that observed boundaries via the removed emits now observe the durable `turn/start`/`turn/end`/`step/start`/`step/end` session events — the behavior they pin (boundary ordering, step counting) is unchanged; only the feed they read moved to the canonical one. The tests that exercised a *throwing turn-boundary emit listener* were deleted, because that code path no longer exists (there is no emit to throw from). Per [AGENTS.md "tests document behavior, not golden truth"](../../../../AGENTS.md), the behavior and its test moved (or died) together.
 - The loop marks the step open (`stepOpen = true`) only after `append('step/start')` returns. Internal dispatch validation runs before the log push and may reject without opening a step; post-commit `session/event` observer failures are contained inside `Session.append`. The marker therefore represents exactly the committed boundary that owes a later `step/end`.
 - The full realization of this is [the simplification Agent Note "Stop mirroring durable boundaries as agent events"](../simplification/2026-06-20-remove-agent-boundary-mirror-events.md): all four boundary mirrors are removed and every consumer reads boundaries off `session/event`. `agent/steering` (not a boundary mirror) stayed outside that Agent Note's scope and was removed by its own follow-up, [Remove the `agent/steering` mirror emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md) — it mirrored the durable mid-turn steering `user/message`.
-- The cordis events catalog (`docs/cordis-catalog/events.md`) is regenerated to drop the mirror events.
+- The generated cordis event surface (the `docs/subsystems/` pages) no longer lists the mirror events.
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
index 1f6df779fd..93fe14adea 100644
--- a/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md
@@ -12,7 +12,7 @@ harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）
 - `agent/*` 承载运行时实时信号，向插件传递 `Agent` 句柄。
 - `tools/*` 承载工具注册表与执行流水线。
 
-两个问题促使我们固定语义。第一，若干轮次/步骤边界同时作为持久的 `SessionEvent`（`turn/start`、`turn/end`、`step/start`、`step/end`）和镜像的 `agent/*` emit（`agent/turn-start`、`agent/turn-end`、`agent/step-start`、`agent/step-end`）存在。消费方对同一事实有两个真源，每次生命周期变更都必须同时更新两处。第二，即将到来的钩子子系统需要一个连贯且有文档的订阅表面——插件作者（以及基于其上构建的 Claude Code / Codex 钩子桥接）必须在不阅读循环代码的情况下知道应该监听会话事件还是 agent 事件，以及原因。
+两个问题促使我们固定语义。第一，若干轮次/步骤边界同时作为持久的 `SessionEvent`（`turn/start`、`turn/end`、`step/start`、`step/end`）和镜像的 `agent/*` emit（`agent/turn-start`、`agent/turn-end`、`agent/step-start`、`agent/step-end`）存在。消费方对同一事实有两个真源，每次生命周期变更都必须同时更新两处。第二，钩子子系统需要一个连贯且有文档的订阅表面——插件作者（以及基于其上构建的 Claude Code / Codex 钩子桥接）必须在不阅读循环代码的情况下知道应该监听会话事件还是 agent 事件，以及原因。
 
 这套词汇是拦截决策、持久的 `hook/*` 日志，以及 Claude Code 和 Codex 桥接的基础。
 
@@ -34,6 +34,6 @@ harness 通过 Cordis 事件分类体系扩展 agent loop（智能体循环）
 - 之前通过已移除 emit 观察边界的测试，现在观察持久的 `turn/start`/`turn/end`/`step/start`/`step/end` 会话事件——它们所锁定的行为（边界顺序、步骤计数）不变；只是读取的源移到了规范源。那些测试*抛出异常的轮次边界 emit 监听器*的用例被删除，因为该代码路径不再存在（没有 emit 可供抛出）。按照 [AGENTS.md「测试记录行为，而非黄金真相」](../../../../AGENTS.md)，行为与其测试一同迁移（或一同消亡）。
 - 循环仅在 `append('step/start')` 返回后才标记步骤已打开（`stepOpen = true`）。内部分发校验在日志推入之前运行，可能在不打开步骤的情况下拒绝；post-commit `session/event` observer 的失败被隔离在 `Session.append` 内部。因此该标记精确表示已提交的、欠一个后续 `step/end` 的边界。
 - 完整实现见[简化 Agent Note「停止将持久边界镜像为 agent 事件」](../simplification/2026-06-20-remove-agent-boundary-mirror-events.md)：全部四个边界镜像被移除，所有消费方从 `session/event` 读取边界。`agent/steering`（不是边界镜像）不在该 Agent Note 范围内，由其后续 Agent Note [移除 `agent/steering` 镜像 emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md) 单独移除——它镜像的是持久的中途 steering `user/message`。
-- Cordis 事件目录（`docs/cordis-catalog/events.md`）重新生成以移除镜像事件。
+- 生成的 cordis 事件表面（`docs/subsystems/` 各页）不再列出镜像事件。
 
 <!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
index b242af54ee..759fecb3b9 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.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 .agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
-2026-07-05-prompt-variables-and-tool-guidance-ownership.md: 199153741a5677e9f7b9bc6510f7a77b9791343e
-2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 988c128382fd8ff5a8a4742486860d931013ac80
+2026-07-05-prompt-variables-and-tool-guidance-ownership.md: 8f8b40a44314fc6add97842d48273e49927f92e2
+2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md: 6fc71e2ab866822cee389c0c54efe1731847cbb7
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
index 199153741a..8f8b40a443 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md
@@ -46,9 +46,9 @@ Per-tool semantics and selection guidance live in tool descriptions. Prompt sect
 
 - **The loop composes an identity line itself** — hardcodes model-facing prose in the one package that must stay thin ("plugins, not loop changes"), and outside the section pipeline it would be a second composition path. (The identity DOES ship as a code literal — but as an ordinary section registered by `dsh-system-prompt`, whose `system-prompt/assemble` waterfall remains the escape valve for a deployment that must drop it.)
 - **Inject the model name via the `agent/request` waterfall** — prompt text would be composed in two places and the earlier rendered persona could disagree with the final routed header. The request plugin that owns late routing must also own any earlier prompt claim about that model.
-- **Hand-write the model name in each persona** — duplicates the `model:` key one line above and silently lies after a config edit; the exact disease this Agent Note cures.
+- **Hand-write the model name in each persona** — duplicates the `model:` key one line above and silently lies after a config edit; the exact disease this decision cures.
 - **Lenient interpolation (leave unknown refs verbatim, or substitute empty)** — a typo ships `{{modle}}` (or a hole) to the model and nobody notices until transcript review.
-- **Per-instance subagent wording in config** — returns model-facing prose to every deployment × instance, the P2 disease again. **Keying wording off the provider NAME** — `providerName` is itself config, so a renamed provider silently gets the wrong words.
+- **Per-instance subagent wording in config** — returns model-facing prose to every deployment × instance, reviving the hand-written-guidance-in-leaf-YAML drift. **Keying wording off the provider NAME** — `providerName` is itself config, so a renamed provider silently gets the wrong words.
 - **Resolving the provider at `apply` time (a load-order requirement)** and **section-only subagent wording (lazily resolved at assemble)** — the alternatives to the provider-lifecycle events; both rejected in [the provider-lifecycle-events Agent Note](2026-07-05-subagent-provider-lifecycle-events.md).
 
 ## Out of scope
diff --git a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
index 988c128382..6fc71e2ab8 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md
@@ -46,9 +46,9 @@ Status: implemented
 
 - **循环自行组合一行 identity 文本**：在必须保持精简的那个包（「用插件，不改循环」）中硬编码面向模型的行文，且在 section 流水线之外构成第二条组合路径。（identity 确实以代码字面量交付——但作为 `dsh-system-prompt` 注册的普通 section，其 `system-prompt/assemble` waterfall 仍是部署需要移除它时的逃生阀。）
 - **通过 `agent/request` waterfall 注入模型名称**：提示词文本会在两处组合，更早渲染的 persona 也可能与最终已路由 header 不一致。拥有延迟路由的请求插件还必须拥有该模型在提示词中更早出现的声明。
-- **在每个 persona 中手写模型名称**：与上方一行的 `model:` 键重复，配置修改后静默失实；正是本 Agent Note 要治愈的病症。
+- **在每个 persona 中手写模型名称**：与上方一行的 `model:` 键重复，配置修改后静默失实；正是本决策要治愈的病症。
 - **宽松插值（未知引用保留原样或替换为空）**：一个拼写错误 `{{modle}}`（或一个空洞）会被发送给模型，直到 transcript（文本记录）审查时才会被发现。
-- **在配置中为每个 subagent 实例编写措辞**：面向模型的行文回到每个部署 × 实例中，重蹈 P2 病症。**根据提供方名称选择措辞**：`providerName` 本身是配置，重命名提供方后会静默获得错误的措辞。
+- **在配置中为每个 subagent 实例编写措辞**：面向模型的行文回到每个部署 × 实例中，重蹈在 leaf YAML 中手写指导的漂移。**根据提供方名称选择措辞**：`providerName` 本身是配置，重命名提供方后会静默获得错误的措辞。
 - **在 `apply` 时解析提供方（加载顺序要求）**与**仅用 section 承载 subagent 措辞（在 assemble 时惰性解析）**：提供方生命周期事件的替代方案；两者均在[提供方生命周期事件 Agent Note](2026-07-05-subagent-provider-lifecycle-events.md)中被否决。
 
 ## 不在范围内
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
index b85c732f6e..54935a491e 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.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 .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
-2026-07-05-reconstructable-requests.md: c971f411eb932cab29d7a52662a0e05a1f638daa
-2026-07-05-reconstructable-requests.zh.md: b788f895cbb33f6ffa59b36430e81384a468f582
+2026-07-05-reconstructable-requests.md: c13e40b5b22e5d6fe19f6b5bd137db3a48350390
+2026-07-05-reconstructable-requests.zh.md: 746bcd37dabada949873d394776c1ca43eff4ea2
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
index c971f411eb..c13e40b5b2 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
@@ -50,6 +50,6 @@ Like MiniCode, the conversation advances append-only and resets only when model-
 - Model-visible context uses logged message channels. `agent.inject()` and tool `additionalContexts` enter the inbox for a later claim, while `agent/pre-step` returns context that must settle with the current claimed batch. Each entered value is a durable sourced `user/message`, paid once and prefix-cached thereafter at the price of accumulating in history until compaction.
 - What still costs full price at the provider is inherent and logged: compaction (its `compact/*` events and replacement entry), a real prompt, tool, or config change (`request/header` with reason `change`), or a process boundary with drift (a differing `resume` snapshot). The provider's own reasoning-content exclusion is managed server-side.
 - `agent/pre-step` is the current-request message channel; direct inbox mutation is the eventual later-request channel.
-- Tool-result trimming (planned) needs no new mechanism: a logged single-entry surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic.
+- Tool-result trimming needs no new mechanism: a logged single-entry surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic.
 - Session logs grow one `request/header` snapshot per loop instance plus snapshots on real changes. This is larger than a delta codec but small beside chunk-heavy logs and retains one replay representation. `SESSION_FORMAT_VERSION` stays `0`; legacy delta events are rejected rather than migrated.
 - Snapshot expected outputs changed once (every transcript gains its header events); the fs-writing fixtures are stored in the normalized authored form with cwd-relative tool arguments, because replay only round-trips cwd-independent argument paths.
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
index b788f895cb..746bcd37da 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md
@@ -50,6 +50,6 @@ Status: implemented
 - 模型可见上下文使用已记录消息通道。`agent.inject()` 与工具 `additionalContexts` 进入 inbox，等待后续领取；必须与当前已领取批次一起结算的上下文由 `agent/pre-step` 返回。每个进入步骤的值都是带来源的持久 `user/message`，只付出一次代价并在后续成为可缓存前缀，代价是会在历史中累积直至压缩。
 - 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compact/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身的 reasoning-content 排除由服务端管理。
 - `agent/pre-step` 是当前请求的消息通道；直接修改 inbox 则是最终进入后续请求的通道。
-- 工具结果裁剪（计划中）无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存击穿由相同的压力逻辑批量处理。
+- 工具结果裁剪无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存击穿由相同的压力逻辑批量处理。
 - 会话日志每个循环实例增长一个 `request/header` 快照，并在真正变更时增加快照。它比 delta 编解码器更大，但相对分片密集型日志仍然很小，并只保留一种回放表示。`SESSION_FORMAT_VERSION` 保持 `0`；旧的 delta 事件被拒绝而非迁移。
 - 快照预期输出变更一次（每个 transcript（文本记录）增加其 header 事件）；写入文件系统的 fixture（测试前置数据）以规范化的撰写形式存储，工具参数使用 cwd 相对路径，因为回放只对 cwd 无关的参数路径做往返。
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
index c85785a097..fa9304ec09 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.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 .agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
-2026-07-06-timeout-deadline-library.md: 72f02208f601ff5514fe6ea0006ea922cdbd49b7
-2026-07-06-timeout-deadline-library.zh.md: c4da7f2028abc32d0c393dd1aeb3c59a4c05acec
+2026-07-06-timeout-deadline-library.md: b7c7ac07ce0acec819fa7e88b32b3b6d624f3e6e
+2026-07-06-timeout-deadline-library.zh.md: e4ec6b9a9e07b55faf9f44f2b99b765620e626c4
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
index 72f02208f6..b7c7ac07ce 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md
@@ -98,12 +98,12 @@ The signal only *notifies*; termination is always the listener's job, and the li
 ## Consequences
 
 - `runBash`'s outcome no longer independently latches `timedOut` and `aborted`; a timeout and a user abort racing before process close now report a single first-abort cause instead of both being true. The uniform SIGTERM→grace→SIGKILL kill is unchanged, and the Service Definition type `BashRunResult` keeps both booleans (now mutually exclusive), so `dsh-tool-bash`'s result rendering is untouched.
-- `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. This is the one deviation from the literal proposal shape (which passed `timeoutMs: 0` into `runBash`); an always-0 field read by nothing is dead weight under the per-file coverage gate.
+- `SpawnSpec.timeoutMs` and `SpawnOutcome.timedOut`/`aborted` were removed rather than kept as always-zero/always-false vestiges: with `runBash` owning no timer and the executor owning classification, they were read nowhere. An always-0 field read by nothing is dead weight under the per-file coverage gate.
 - web_fetch shed its bespoke controller/timer/listener/reason-recovery; the classifier now keys off the deadline signal (`timeoutOf` + `aborted`) rather than the thrown error's shape, which is robust across both the request-phase reject-with-reason and the read-phase bare-`AbortError`.
 - `AbortSignal.any` and `using`/`Symbol.dispose` enter the repo for the first time here (Node ≥ 24 baseline, already met).
 - Model streams now share one rearmable timer contract without turning a sliding idle interval into a total-call deadline or charging consumer think time. Adapters that can observe out-of-band transport activity may pulse an outstanding demand; suppressed activity remains invisible to the watchdog. The primitive still only notifies; adapter tests prove their transports observe its stable signal and terminate.
 
-Out of scope, named to mark the boundary: `web_search` can gain an optional model-facing `timeout_ms` once its tool-schema/snapshot coverage is planned; future ripgrep-backed fs discovery tools can consume the same provider-owned deadline shape once they exist; a `tools/execute` waterfall middleware could arm a default deadline for every tool call by driving `exec.signal` — that would be a plugin that *consumes* this library and still only notifies, the hard kill remaining each capability's job.
+Out of scope, named to mark the boundary: `web_search` can gain an optional model-facing `timeout_ms` once its tool-schema/snapshot coverage is planned; the ripgrep-backed fs discovery tools ([packaged ripgrep search](2026-08-01-packaged-ripgrep-search.md)) consume the same provider-owned deadline shape through `dsh-timeout-policy` and `exec.signal`; a `tools/execute` waterfall middleware could arm a default deadline for every tool call by driving `exec.signal` — that would be a plugin that *consumes* this library and still only notifies, the hard kill remaining each capability's job.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
index c4da7f2028..e4ec6b9a9e 100644
--- a/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md
@@ -98,12 +98,12 @@ export function timeoutOf(x: AbortSignal | { reason?: unknown }, code?: string):
 ## 后果
 
 - `runBash` 的结果不再独立锁存 `timedOut` 和 `aborted`；超时与用户中止在进程关闭前竞争时，现在报告单一的首个 abort 原因，而非两者同时为 true。统一的 SIGTERM→宽限期→SIGKILL 终止路径不变，Service Definition 类型 `BashRunResult` 保留两个布尔值（现在互斥），因此 `dsh-tool-bash` 的结果渲染不受影响。
-- `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。这是与字面提案形状（向 `runBash` 传入 `timeoutMs: 0`）的唯一偏差；一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
+- `SpawnSpec.timeoutMs` 和 `SpawnOutcome.timedOut`/`aborted` 被移除，而非作为始终为零/始终为 false 的残余保留：由于 `runBash` 不再拥有定时器且执行器负责分类，这些字段无处被读取。一个始终为 0 且无处读取的字段在逐文件覆盖率门禁下属于死代码。
 - web_fetch 去除了其定制的 controller/timer/listener/reason-recovery；分类器现在基于 deadline 信号（`timeoutOf` + `aborted`）而非抛出错误的形状来判断，这在请求阶段的 reject-with-reason 和读取阶段的裸 `AbortError` 两种情况下都是健壮的。
 - `AbortSignal.any` 和 `using`/`Symbol.dispose` 在此首次进入本仓库（Node ≥ 24 基线，已满足）。
 - 模型流现在共享一个可重启的定时器约定，不会把滑动的空闲间隔变成总调用截止时间，也不会计入消费方思考时间。能够观察到带外传输活动的适配器可以对尚未结算的 demand 调用 `pulse()`；被屏蔽的活动对 watchdog 仍不可见。该原语仍然只做通知；适配器测试证明其传输观察到稳定信号并终止。
 
-以下内容不在本次范围内，列出以标明边界：`web_search` 可以在其工具 schema 和快照覆盖规划完成后获得可选的面向模型的 `timeout_ms`；未来基于 ripgrep 的文件系统发现工具可以在实现后消费同样的提供方自有 deadline 形状；`tools/execute` waterfall（瀑布式事件）中间件可以通过驱动 `exec.signal` 为每次工具调用设置默认 deadline——那将是一个*消费*本库的插件，仍然只做通知，硬终止仍是各能力自己的事。
+以下内容不在本次范围内，列出以标明边界：`web_search` 可以在其工具 schema 和快照覆盖规划完成后获得可选的面向模型的 `timeout_ms`；基于 ripgrep 的文件系统发现工具（[打包的 ripgrep 搜索](2026-08-01-packaged-ripgrep-search.md)）通过 `dsh-timeout-policy` 和 `exec.signal` 消费同样的提供方自有 deadline 形状；`tools/execute` waterfall（瀑布式事件）中间件可以通过驱动 `exec.signal` 为每次工具调用设置默认 deadline——那将是一个*消费*本库的插件，仍然只做通知，硬终止仍是各能力自己的事。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
index 36484da590..4ac6aa8cdd 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.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 .agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
-2026-07-07-tool-call-timeout-policy.md: d341a2c598765b6de4d2a7e242f38847e48f081b
-2026-07-07-tool-call-timeout-policy.zh.md: 6d10b552b951f428f475323ba115007e39b66aaf
+2026-07-07-tool-call-timeout-policy.md: f17834332b2e661b6811c2264d5e8de4e1642663
+2026-07-07-tool-call-timeout-policy.zh.md: 3be8614f209b2896f0754cadd868f6e66b78f834
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
index d341a2c598..f17834332b 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
@@ -85,7 +85,7 @@ No new session event is needed for reconstructability: `TOOL_TIMEOUT` is the fin
 
 `read`, `write`, `edit`, `todo_write`, `task_list`, and `task_kill` do not opt into tool-call timeout. `task_output` owns its bounded wait because a wait timeout is a successful live-status result, not a tool failure.
 
-A future model-facing grep/glob tool can be implemented on top of `ctx.bash` without importing `@deepseek-ai/dsh-timeout`: it forwards `exec.signal` to `ctx.bash`, and declares its own `timeoutMs` (from its plugin's config) for the enforcer to apply. If bash-local's backend timeout becomes a problem for such a tool, the bash seam can later add a caller-owned-deadline mode; that is outside this cut.
+A future model-facing grep/glob tool can be implemented on top of `ctx.bash` without importing `@deepseek-ai/dsh-timeout`: it forwards `exec.signal` to `ctx.bash`, and declares its own `timeoutMs` (from its plugin's config) for the enforcer to apply. If bash-local's backend timeout becomes a problem for such a tool, the bash seam can later add a caller-owned-deadline mode; that is a separate decision.
 
 ## Alternatives considered
 
@@ -111,4 +111,3 @@ A future model-facing grep/glob tool can be implemented on top of `ctx.bash` wit
 - Multiple `tools/execute` listeners compose by ordinary Cordis waterfall order: a listener that calls `next()` wraps downstream listeners plus dispatch; one that returns without `next()` short-circuits them. A deployment combining timeout with a future retry/sandbox/metrics wrapper chooses semantics by registration order ("timeout covers the whole retry" vs "timeout covers each attempt").
 - Opt-in by declaration is a deliberate misconfiguration risk: a tool can declare a `timeoutMs` without honoring `exec.signal`, and that tool will not stop on timeout. The registry awaits that non-quiescent body rather than racing it, while the plugin contract states that declaring a budget means cooperative; the web tools prove the pattern on tools that already forward the signal.
 - During the transition `bash` and the migrated web tools use different timeout paths on purpose: `TOOL_TIMEOUT` is the model-facing tool-call budget, while `BASH_TIMEOUT` remains the bash backend timeout used by bash and hooks.
-- Deviation from the literal proposal, recorded per the implemented-Agent Note rule: the plugin package is `@deepseek-ai/dsh-timeout-policy` (not `tool-timeout`), signal replacement is in-place `exec.signal` mutation before `next()` (not `next({ ...exec, signal })`, which cordis ignores), and the per-tool budget is declared on the `ToolDefinition` (`timeoutMs`, set by the owning tool plugin from its config) rather than mapped by tool name in this plugin's config — so the enforcer is zero-config and a mistyped tool name is impossible. All three are described in `## Decision` above.
diff --git a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
index 6d10b552b9..3be8614f20 100644
--- a/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-07-tool-call-timeout-policy.zh.md
@@ -85,7 +85,7 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 
 `read`、`write`、`edit`、`todo_write`、`task_list` 和 `task_kill` 不加入工具调用超时。`task_output` 自己拥有有界等待，因为等待超时是成功的实时状态结果，而非工具失败。
 
-未来面向模型的 grep/glob 工具可以基于 `ctx.bash` 实现而无需导入 `@deepseek-ai/dsh-timeout`：它将 `exec.signal` 转发给 `ctx.bash`，并声明自己的 `timeoutMs`（来自其插件配置）供执行器应用。如果 bash-local 的后端超时对这类工具造成问题，bash seam 可以后续添加调用方自有截止模式；这不在本次范围内。
+未来面向模型的 grep/glob 工具可以基于 `ctx.bash` 实现而无需导入 `@deepseek-ai/dsh-timeout`：它将 `exec.signal` 转发给 `ctx.bash`，并声明自己的 `timeoutMs`（来自其插件配置）供执行器应用。如果 bash-local 的后端超时对这类工具造成问题，bash seam 可以后续添加调用方自有截止模式；那是一项独立的决策。
 
 ## 曾考虑的替代方案
 
@@ -111,4 +111,3 @@ function toolTimeoutResult(timeoutMs: number): ToolExecutionResult {
 - 多个 `tools/execute` 监听器按普通 Cordis waterfall 顺序组合：调用 `next()` 的监听器包装下游监听器加分发；不调用 `next()` 直接返回的监听器短路它们。一个同时组合超时与未来重试/沙箱/指标包装器的部署通过注册顺序选择语义（「超时覆盖整个重试」vs「超时覆盖每次尝试」）。
 - 按声明加入是一个有意的误配置风险：工具可以声明 `timeoutMs` 但不遵循 `exec.signal`，这样的工具在超时时不会停止。注册表会等待这个尚未完全停稳的工具体结束，而不是与它竞速；同时插件约定声明：声明预算意味着协作；web 工具在已转发信号的工具上验证了这一模式。
 - 过渡期间 `bash` 和已迁移的 web 工具有意使用不同的超时路径：`TOOL_TIMEOUT` 是面向模型的工具调用预算，而 `BASH_TIMEOUT` 仍是 bash 和钩子使用的 bash 后端超时。
-- 与字面提案的偏差，按 implemented-Agent Note 规则记录：插件包为 `@deepseek-ai/dsh-timeout-policy`（而非 `tool-timeout`）；信号替换是在 `next()` 之前就地修改 `exec.signal`（而非 `next({ ...exec, signal })`，Cordis 会忽略后者）；逐工具预算声明在 `ToolDefinition` 上（`timeoutMs`，由拥有该工具的插件从其配置中设置），而非在本插件配置中按工具名映射——因此执行器是零配置的，拼错工具名不可能发生。以上三点均在上文 `## Decision` 中描述。
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
index aa1d2c9d6f..8bef07d042 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.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 .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
-2026-07-10-single-file-executable-sdk-runtime-distribution.md: fe09e1b83f4f0a9f867f78351f643b1bd26d7c9d
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 0279e0cf032928e96bad9da02340cae753a0927f
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: a45678c9bb5fcae340ff7134687890879f56c630
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: f1fccc508471356dd6434da0e126ed38f15ed3ba
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
index fe09e1b83f..a45678c9bb 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
@@ -76,7 +76,7 @@ Manual-driving caveat: the bin treats stdin EOF as "the client is gone" and disp
 
 **jsonrpc-agent carrying the full closure dependencies.** The app bin would declare 53+ dependencies it never imports — a "packaging manifest" masquerading as real dependency relationships — and would force constraints to open two exceptions for it, cordis-in-dependencies and a files wildcard. With the closure manifest landing on the python-side manifest package, constraints needs no exception at all and the bin keeps the normal package shape isomorphic to acp-agent.
 
-**An open plugin set (loading user plugins from disk).** This round ships a closed set; the PoC incidentally confirmed that on-disk ESM import outside the VFS works (through the `ctx.baseUrl` relative-path channel). It is listed as a future evolution, which must separately solve sharing the cordis instance inside the exe with external plugins.
+**An open plugin set (loading user plugins from disk).** The shipped set is closed; the PoC incidentally confirmed that on-disk ESM import outside the VFS works (through the `ctx.baseUrl` relative-path channel). It is listed as a future evolution, which must separately solve sharing the cordis instance inside the exe with external plugins.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
index 0279e0cf03..f1fccc5084 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
@@ -76,7 +76,7 @@ exe 内支持 `dsh-workflow-workerthread` 与 `dsh-code-runtime-worker`。两个
 
 **让 jsonrpc-agent 承担完整闭包依赖。** 应用入口将声明 53 个以上自身并不 `import()` 的依赖，使「打包 manifest」伪装成真实依赖关系，还会迫使 `constraints` 为其增加 `cordis-in-dependencies` 与 `files` 通配符两个例外。将闭包清单放在 Python 侧的 manifest 包后，`constraints` 不需要任何例外，`bin` 也能保持与 acp-agent 同构的正常包形状。
 
-**开放插件集（从磁盘加载用户插件）。** 本期采用封闭集；PoC 同时证实，可以通过 `ctx.baseUrl` 相对路径通道从 VFS 外的磁盘 `import()` ESM。该能力列为后续演进，届时还需解决外部插件与 exe 内 Cordis 实例的共享问题。
+**开放插件集（从磁盘加载用户插件）。** 交付的集合是封闭的；PoC 同时证实，可以通过 `ctx.baseUrl` 相对路径通道从 VFS 外的磁盘 `import()` ESM。该能力列为后续演进，届时还需解决外部插件与 exe 内 Cordis 实例的共享问题。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
index 03b17f5f33..91c9baf2a0 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.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 .agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
-2026-07-15-lsp-capability-seam.md: 65d547a51568cca43fd8b2887bfe9a61c512b34d
-2026-07-15-lsp-capability-seam.zh.md: a9dcedaa80742bb338dbca4c0c532ca6e7cb2655
+2026-07-15-lsp-capability-seam.md: a461432fe5f218ea6c3ff3e031b52f7ebffbd7a5
+2026-07-15-lsp-capability-seam.zh.md: bfbd8d04f71b154d2833c86f2a6dc84d7e13fff4
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
index 65d547a515..a461432fe5 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md
@@ -32,7 +32,7 @@ The prompt positions LSP as a precision aid: `Use search/read for ordinary navig
 
 The seam exposes one `query(request, signal?)` operation because no fields need implementation defaulting: `workspaceRoot` is required, `languageId` comes from the registration, and consumers own timeouts and result limits. `query()` selects and derives without hidden `??` fallbacks, leaving no executable spec to resolve. `dsh-tool-lsp` validates model arguments and passes only `exec.signal` as a bare `AbortSignal`, matching web and keeping `dsh-lsp` independent of `dsh-tools`. Removal before selection fails as unavailable; later disposal follows the selected provider's cancellation lifecycle without rerouting.
 
-The intended contract shape is:
+The contract shape:
 
 ```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
@@ -147,7 +147,7 @@ The provider trusts its configured server. Its filesystem visibility and process
 
 ## Alternatives considered
 
-**Copy Claude Code's unified schema.** Its cursor operations validate the core use case, but symbols and call hierarchy need different arguments. Copying all nine operations would freeze speculative surface, so the proposal aligns only on the four semantic queries.
+**Copy Claude Code's unified schema.** Its cursor operations validate the core use case, but symbols and call hierarchy need different arguments. Copying all nine operations would freeze speculative surface, so the seam aligns only on the four semantic queries.
 
 **Let providers register tools.** Loaded servers would then control model schema and prompts, preventing one stable contract across local and remote providers.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
index a9dcedaa80..bfbd8d04f7 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md
@@ -32,7 +32,7 @@ harness 已具备文本搜索与文件读取能力，但二者都无法识别程
 
 服务边界只公开 `query(request, signal?)`，因为没有字段需要实现层填充默认值：`workspaceRoot` 是必填项，`languageId` 来自注册映射，超时与结果限制由消费方负责。`query()` 执行选择与推导时不使用隐藏的 `??` 后备逻辑，因此没有需要 resolve 的可执行 spec。`dsh-tool-lsp` 校验模型参数，并只把 `exec.signal` 作为裸 `AbortSignal` 传递，与 web 一致，并使 `dsh-lsp` 不依赖 `dsh-tools`。提供方在选择前被移除时按不可用失败；之后的释放遵循已选提供方的取消生命周期，不改路由。
 
-预期约定如下：
+约定如下：
 
 ```ts
 import type { Branded } from '@deepseek-ai/dsh-brand'
@@ -147,7 +147,7 @@ interface LspToolInput {
 
 ## 备选方案
 
-**照搬 Claude Code 的统一 schema。** 它的光标操作验证了核心场景，但符号与调用层级需要不同参数。照搬九种操作会固化尚未验证的接口，因此本提案只对齐四种语义查询。
+**照搬 Claude Code 的统一 schema。** 它的光标操作验证了核心场景，但符号与调用层级需要不同参数。照搬九种操作会固化尚未验证的接口，因此该 seam 只对齐四种语义查询。
 
 **允许提供方注册工具。** 已加载服务器会控制模型 schema 和提示词，无法在本地与远程提供方之间维持统一约定。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 4632c7e1ac..bf20616836 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: ebab36e66768f6216603923d2313e77eaf412ae1
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 308446e48772c3bb8d6e0b5851dd526af641593a
+2026-07-19-gui-layering-and-rpc-protocol.md: f3aea8360ea1db9b29da01f143daf30cd969b0e5
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 27b5401960a31ee3cedf2366d3b7f4efc527d482
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
index ebab36e667..f3aea8360e 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-19-gui-layering-and-rpc-protocol.zh.md)
 
-> Division of labor: this document = the layering model + the channel-independent RPC protocol; the protocol's Web implementation combines HTTP uplink with the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md), while the browser object layer is in the [web client architecture RFC](2026-07-19-gui-web-client-architecture.md).
+> Division of labor: this document = the layering model + the channel-independent RPC protocol; the protocol's Web implementation combines HTTP uplink with the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md), while the browser object layer is in the [web client architecture note](2026-07-19-gui-web-client-architecture.md).
 
 ## Problem
 
@@ -25,7 +25,7 @@ Directories layer as follows:
 
 - `packages/host/*`: packages provide host-side capability only (representing the Node.js engineering core built on the existing harness plugin system), and additionally
     - the unified backend protocol (fetch, HTTP, streaming interfaces…) — definitions and support, see the "Message protocol" sections below
-- `packages/client/*`: packages provide client-side capability only; every package stays single-sided. Three kinds live here (the axes are owned by the [client plugin loading RFC](2026-07-23-client-plugin-loading-model.md)):
+- `packages/client/*`: packages provide client-side capability only; every package stays single-sided. Three kinds live here (the axes are owned by the [client plugin loading note](2026-07-23-client-plugin-loading-model.md)):
     - **Pure libraries** (`ui-slots`, `web-react`, `ui-primitives`, plus the `loader` kernel package): ordinary root-index packages, statically bundled into the shell; the first three are seeded into the module table.
     - **Static-arrival entry packages** (`connection`, `runtime`, `ui-theme`, `i18n`, `hmr`): no `dshClient` key and no browser bundle — the shell bundles their `src/client/` half and registers it with `ctx.modules`; they are governed as entries of the host-authored graph like everything else.
     - **Fetch-arrival plugin packages** (`ui-layout`, `ui-sidebar`, `ui-conversation`, `ui-trajectory`): dual-entry — the root index is the node half (an empty `apply`, existing so the host Loader governs lifecycle and the web plugin registry discovers the package.json `dshClient` declaration); the implementation lives under `src/client/`, shipped as the `./client` subpath (a tsdown closure-factory bundle). Cross-plugin consumption of `/client` is type-only; value cooperation goes through cordis services.
@@ -52,7 +52,7 @@ Direction discipline (every rule auditable from package deps):
 - `runtime → apiproxy` is one-way; apiproxy depends only on type definitions.
 - Client-side packages **never import** host-side package runtime (they consume only the two browser-safe subpaths `/api` and `/client`).
 - `webserver` does not depend on `runtime`: it provides a `{ fetch }`-shaped implementation — "webserver ← runtime" is a runtime injection relationship, not a package dependency.
-- Cross-package client imports use the `/client` subpath for plugin packages, and between plugin packages they are type-only — a cross-plugin value import is a build error at the tsdown purity gate (value cooperation goes through cordis services; the [client plugin loading RFC](2026-07-23-client-plugin-loading-model.md) owns the edge rules).
+- Cross-package client imports use the `/client` subpath for plugin packages, and between plugin packages they are type-only — a cross-plugin value import is a build error at the tsdown purity gate (value cooperation goes through cordis services; the [client plugin loading note](2026-07-23-client-plugin-loading-model.md) owns the edge rules).
 
 TypeScript checks in **two aggregate programs** referenced by a solution root (`tsconfig.json` = solution; `tsconfig.host.json` = host side + tests, excluding `packages/client`; `tsconfig.client.json` = client packages and their tests): both sides merge the cordis `Context` interface under the same keys (`sessions`, `loader`) with different services, so one program would see both declaration merges and report a collision. Shared leaves (session/llm/tools/apiproxy…) build once and are referenced by both programs ([topology](../process/2026-07-22-tsconfig-solution-root-two-aggregates.md)).
 
@@ -66,7 +66,7 @@ On the protocol side: TS interfaces (`packages/host/apiproxy/src/api/`, zero Nod
 | Assembly layer | `dsh-host-runtime` | Plugin composition + ApiProxy integration + the web UI plugin mount (in-memory Loader tree over the eight dshClient packages); home of host-level configuration (defaults/persistenceRoot, future user profile) | Which plugins mount and with what defaults is decided only here; shells must not alter the assembly |
 | Carrier layer | `dsh-host-webserver` | Web-shape HTTP and upgrade: static serving + `/api/*`→handler forwarding + WebSocket upgrade route + close semantics; plugin bundle endpoint + `__DSH_BOOT__` manifest injection (fed by the web plugin registry) | Web (browser access) only; zero workspace dependencies (the registry arrives by structural injection); Electron does not reuse it |
 | Client libraries | `dsh-client-ui-slots` / `dsh-client-web-react` / `dsh-client-ui-primitives` | Slot registry core / ctx↔React glue / pure React atoms | Zero cordis runtime dependency in components; seeded into the loader module table by the shell |
-| Client plugins | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | Browser-side cordis plugin tree (wire consumer, core services, theme, i18n, layout, sidebar, conversation, trajectory) — see the web client architecture RFC | Dual entry (node half = empty apply; implementation in `src/client/`); the consumption face goes exclusively through ApiProxy |
+| Client plugins | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | Browser-side cordis plugin tree (wire consumer, core services, theme, i18n, layout, sidebar, conversation, trajectory) — see the web client architecture note | Dual entry (node half = empty apply; implementation in `src/client/`); the consumption face goes exclusively through ApiProxy |
 | Application shape | `@deepseek-ai/dsh` (apps/cli) + `dsh-frontend` (apps/web, the vite application) | Coarse bin dispatch + one assembly module per shape (web.ts / headless.ts); the vite app is a thin main over the `dsh-client-web` shell surface | Shapes dynamic-import so they never load each other; workspace knowledge like dist location stays in the app |
 
 #### Naming rule
@@ -218,11 +218,11 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 | `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing; carrier tests and callers can exercise the protocol without opening a port, while product `dsh run` drives core directly |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` uplink + one same-origin WebSocket downlink per logical stream | the browser shape; physical boundary in the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | unused (protocol-layer override) | serverless UI development (`?fixture`): overrides the `callUnary`/`openMux`/`openHost`/`respond` virtuals and is itself the fake server (frame rpcIds minted by it, semantics self-consistent) |
-| (future) IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
+| IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
 
 ## How to extend (operational checklists)
 
-**Add a unary method (5 steps)**: ① add the method signature to the domain interface (parameters/return inline — this is the single source of truth); ② add one `RpcMethodMap` row; ③ add the request/value schema pair in `<domain>.schema.ts` (anchored `Wire<RequestPayload<'…'>>`); ④ add one handler `UNARY_ROUTES` row (the handler's Web carriage is in the web client architecture RFC); ⑤ implement in the impl (echo `request.rpcId`). On the client side, add the passthrough row to the `IApiClient`/`AbstractApiClient` domain method tables.
+**Add a unary method (5 steps)**: ① add the method signature to the domain interface (parameters/return inline — this is the single source of truth); ② add one `RpcMethodMap` row; ③ add the request/value schema pair in `<domain>.schema.ts` (anchored `Wire<RequestPayload<'…'>>`); ④ add one handler `UNARY_ROUTES` row (the handler's Web carriage is in the web client architecture note); ⑤ implement in the impl (echo `request.rpcId`). On the client side, add the passthrough row to the `IApiClient`/`AbstractApiClient` domain method tables.
 
 **Add a frame type (3 steps)**: ① add a branch to the `MuxFrame`/`HostFrame` union (answerable frames must note the stable-rpcId semantics); ② add a frame-schema branch; ③ the consumers' fold/routing documented-default already covers unknown types — add an explicit branch as needed.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 308446e487..27b5401960 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-19-gui-layering-and-rpc-protocol.md) | 中文
 
-> 分工线：本篇 = 分层模型 + 通道无关的 RPC 协议；协议的 Web 实现由 HTTP 上行加 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md)组成，浏览器对象层见 [Web 客户端架构 RFC](2026-07-19-gui-web-client-architecture.md)。
+> 分工线：本篇 = 分层模型 + 通道无关的 RPC 协议；协议的 Web 实现由 HTTP 上行加 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md)组成，浏览器对象层见 [Web 客户端架构笔记](2026-07-19-gui-web-client-architecture.md)。
 
 ## Problem
 
@@ -23,7 +23,7 @@ Status: implemented
 目录按照如下分层：
 - `packages/host/*`: 包只提供 Host 侧能力（代表了以现在 Harness 实体插件系统为主体的 Node.js 代码核心工程），除此之外，还包含
     - 统一后端协议（fetch、HTTP、流式接口等）定义和支持，见本篇「消息协议」起各节
-- `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住三类包（两条轴归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有）：
+- `packages/client/*`：包只提供 Client 侧能力，每包单边不混。这里住三类包（两条轴归 [client 插件装载笔记](2026-07-23-client-plugin-loading-model.md) 所有）：
     - **纯库**（`ui-slots`、`web-react`、`ui-primitives`，外加内核包 `loader`）：普通根入口包，静态打包进壳；前三者播种进模块表。
     - **静态到达 entry 包**（`connection`、`runtime`、`ui-theme`、`i18n`、`hmr`）：无 `dshClient` 键、无浏览器 bundle——壳把它们的 `src/client/` 半边打进自己的 bundle 并向 `ctx.modules` 登记；它们与其余单元一样，作为 host 独家撰写的图里的 entry 受治理。
     - **fetch 到达插件包**（`ui-layout`、`ui-sidebar`、`ui-conversation`、`ui-trajectory`）：双入口——根入口是 node 半边（空 `apply`，其存在是为了让 host Loader 管辖生命周期、让 web 插件注册表发现 package.json 的 `dshClient` 声明）；实现住在 `src/client/` 下，经 `./client` 子路径发布（tsdown 闭包工厂 bundle）。跨插件消费 `/client` 只限类型；值层面的协作走 cordis 服务。
@@ -50,7 +50,7 @@ harness core packages ──────────────────┘
 - `runtime → apiproxy` 单向；apiproxy 仅依赖类型定义。
 - client 侧包**永不 import** host 侧包的运行时（只吃 `/api`、`/client` 两个浏览器安全子路径）。
 - `webserver` 不依赖 `runtime`：它提供 `{ fetch }` 特定实现 ——「webserver ← runtime」只是运行时注入关系，不是包依赖。
-- client 侧跨包 import 插件包一律走 `/client` 子路径，且插件包之间只限类型 import——跨插件值 import 在 tsdown 纯度门禁处即构建错误（值层面的协作走 cordis 服务；边规则归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有）。
+- client 侧跨包 import 插件包一律走 `/client` 子路径，且插件包之间只限类型 import——跨插件值 import 在 tsdown 纯度门禁处即构建错误（值层面的协作走 cordis 服务；边规则归 [client 插件装载笔记](2026-07-23-client-plugin-loading-model.md) 所有）。
 
 TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.json` = solution；`tsconfig.host.json` = host 侧 + 测试，排除 `packages/client`；`tsconfig.client.json` = client 各包及其测试）：两侧在相同键（`sessions`、`loader`）下以不同服务合并 cordis `Context` 接口，单一 program 会同时看到两份声明合并而报冲突。共享叶子包（session/llm/tools/apiproxy 等）只构建一次，由两个 program 共同引用（[拓扑](../process/2026-07-22-tsconfig-solution-root-two-aggregates.md)）。
 
@@ -64,7 +64,7 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 | 装配层 | `dsh-host-runtime` | 插件组合 + ApiProxy 集成 + web UI 插件挂载（覆盖八个 dshClient 包的内存 Loader 树）；host 级配置归属地（defaults/persistenceRoot，将来用户 profile） | 装什么插件、给什么默认值只在这里定；壳不得改装配 |
 | 承载层 | `dsh-host-webserver` | Web 形态 HTTP 与 upgrade：静态服务 + `/api/*`→handler 转发 + WebSocket upgrade route + close 语义；插件 bundle 端点 + `__DSH_BOOT__` manifest（元数据清单）注入（由 web 插件注册表供给） | Web（浏览器访问）专用；零 workspace 依赖（注册表经结构注入到达）；Electron 不复用它 |
 | client 库 | `dsh-client-ui-slots` / `dsh-client-web-react` / `dsh-client-ui-primitives` | slot 注册表核心 / ctx↔React 胶合 / 纯 React 原子组件 | 组件零 cordis 运行时依赖；由壳播种进 loader 模块表 |
-| client 插件 | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | 浏览器侧 cordis 插件树（wire 消费者、核心服务、主题、i18n、布局、侧栏、对话、轨迹）——见 Web 客户端架构 RFC | 双入口（node 半边=空 apply；实现在 `src/client/`）；消费面唯一经 ApiProxy |
+| client 插件 | `dsh-client-connection` / `dsh-client-runtime` / `dsh-client-ui-theme` / `dsh-client-i18n` / `dsh-client-ui-layout` / `dsh-client-ui-sidebar` / `dsh-client-ui-conversation` / `dsh-client-ui-trajectory` | 浏览器侧 cordis 插件树（wire 消费者、核心服务、主题、i18n、布局、侧栏、对话、轨迹）——见 Web 客户端架构笔记 | 双入口（node 半边=空 apply；实现在 `src/client/`）；消费面唯一经 ApiProxy |
 | 应用态 | `@deepseek-ai/dsh`（apps/cli）+ `dsh-frontend`（apps/web，vite 应用） | bin 粗分发 + 每形态一个拼装模块（web.ts / headless.ts）；vite 应用是 `dsh-client-web` 壳表面之上的薄 main | 形态间动态 import 互不加载；dist 定位等 workspace 知识留在 app |
 
 #### 命名规则
@@ -216,11 +216,11 @@ export type ResponseValue<K> =
 | `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧；载体测试与调用方可以在不打开端口的情况下运行这套协议，而产品 `dsh run` 直接驱动 core |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
-| （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
+| IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
 
 ## 怎么扩展（操作清单）
 
-**加一个 unary 方法（5 步）**：①域接口加方法签名（参数/返回内联，这是唯一事实源）；②`RpcMethodMap` 加一行；③`<域>.schema.ts` 加 request/value schema 对（锚 `Wire<RequestPayload<'…'>>`）；④handler `UNARY_ROUTES` 加一行（handler 的 Web 承载见 Web 客户端架构 RFC）；⑤impl 实现（回显 `request.rpcId`）。client 侧 `IApiClient`/`AbstractApiClient` 的域方法表同步加一行透传。
+**加一个 unary 方法（5 步）**：①域接口加方法签名（参数/返回内联，这是唯一事实源）；②`RpcMethodMap` 加一行；③`<域>.schema.ts` 加 request/value schema 对（锚 `Wire<RequestPayload<'…'>>`）；④handler `UNARY_ROUTES` 加一行（handler 的 Web 承载见 Web 客户端架构笔记）；⑤impl 实现（回显 `request.rpcId`）。client 侧 `IApiClient`/`AbstractApiClient` 的域方法表同步加一行透传。
 
 **加一个帧型（3 步）**：①`MuxFrame`/`HostFrame` union 加一支（可应答帧须注明 rpcId 稳定语义）；②帧 schema 加一支；③消费端 fold/路由的 documented-default 已兜底未知型，按需加显式分支。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
index f0cc648a10..269933c1a7 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.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 .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: 5e927405e9012b5a56d82da8fcf600ca4aa1bd5b
-2026-07-19-gui-web-client-architecture.zh.md: 4294af099dce4e1345e625694a054661483f8d12
+2026-07-19-gui-web-client-architecture.md: 82b2f85708c423748954644d4991e2d54d42874a
+2026-07-19-gui-web-client-architecture.zh.md: c37252d1db291cae11db2a615c9e4005ece717da
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
index 5e927405e9..82b2f85708 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-19-gui-web-client-architecture.zh.md)
 
-> Division of labor: the channel-independent layering model and RPC protocol (message model / type system / contract face / client base class) are in the [layering and RPC protocol RFC](2026-07-19-gui-layering-and-rpc-protocol.md); this document = the browser side: how the client cordis tree loads, how UI plugins compose through slots and services, and how the React-free object layer feeds React through immutable snapshots.
+> Division of labor: the channel-independent layering model and RPC protocol (message model / type system / contract face / client base class) are in the [layering and RPC protocol note](2026-07-19-gui-layering-and-rpc-protocol.md); this document = the browser side: how the client cordis tree loads, how UI plugins compose through slots and services, and how the React-free object layer feeds React through immutable snapshots.
 
 ## Problem
 
@@ -30,13 +30,13 @@ Both ends run cordis. The host is a cordis plugin tree; the browser runs a secon
 
 ## The client cordis tree and the loading chain
 
-The loading chain — the two package kinds (plain vs dshClient plugin), the module-system/plugin-governor split, the two-phase boot over the host-authored entry graph with revisions, and hot reload — is owned by the [client plugin loading RFC](2026-07-23-client-plugin-loading-model.md). The load-bearing facts for this document: the browser boots the same vendored `@cordisjs/plugin-loader` as the host with a client module system (`ctx.modules`, `packages/client/modules`) filling its `internal` contract; every unit with product behavior is an entry in the host-authored `__DSH_BOOT__` graph — every production plugin package (infrastructure included) carries the `dshClient` declaration and arrives as a fetched `./client` tsdown closure bundle, `immediately` rows differing only in boot phase-one prefetch, while plain packages (react family, cordis, the not-yet-promoted libraries) stay shell-bundled, seeded, and invisible to the graph; bundles execute `window.__ModuleLoader__.load({ id, factory })` and their `require` is answered from the lazy CJS module table (seed words + registered factories, materialized and memoized on first require — cross-plugin value imports are a build error, cooperation goes through cordis services); plugin CSS is inlined in the bundle and injected as `<style data-plugin="<id>">` at materialization (CSS Modules hashing + ownership tag = isolation, removal on reload); hot reload is live in dev graphs — the webserver stat-polls the bundles it serves and broadcasts `rebuilt` SSE frames, and the `client-hmr` plugin swaps one fiber per frame. The settled flip (`loader.await()` + an all-ACTIVE sweep) still switches the shell from the loading page to the real UI in one pass — settled means every entry is created and every fiber reached ACTIVE, with FAILED/PENDING fibers listed loud; there is no partial-availability mode (progressive rendering is deferred work).
+The loading chain — the two package kinds (plain vs dshClient plugin), the module-system/plugin-governor split, the two-phase boot over the host-authored entry graph with revisions, and hot reload — is owned by the [client plugin loading note](2026-07-23-client-plugin-loading-model.md). The load-bearing facts for this document: the browser boots the same vendored `@cordisjs/plugin-loader` as the host with a client module system (`ctx.modules`, `packages/client/modules`) filling its `internal` contract; every unit with product behavior is an entry in the host-authored `__DSH_BOOT__` graph — every production plugin package (infrastructure included) carries the `dshClient` declaration and arrives as a fetched `./client` tsdown closure bundle, `immediately` rows differing only in boot phase-one prefetch, while plain packages (react family, cordis, the not-yet-promoted libraries) stay shell-bundled, seeded, and invisible to the graph; bundles execute `window.__ModuleLoader__.load({ id, factory })` and their `require` is answered from the lazy CJS module table (seed words + registered factories, materialized and memoized on first require — cross-plugin value imports are a build error, cooperation goes through cordis services); plugin CSS is inlined in the bundle and injected as `<style data-plugin="<id>">` at materialization (CSS Modules hashing + ownership tag = isolation, removal on reload); hot reload is live in dev graphs — the webserver stat-polls the bundles it serves and broadcasts `rebuilt` SSE frames, and the `client-hmr` plugin swaps one fiber per frame. The settled flip (`loader.await()` + an all-ACTIVE sweep) still switches the shell from the loading page to the real UI in one pass — settled means every entry is created and every fiber reached ACTIVE, with FAILED/PENDING fibers listed loud; there is no partial-availability mode (progressive rendering is deferred work).
 
 Type universes stay split at the aggregate level — `tsconfig.host.json` is the host program and `tsconfig.client.json` the client program, both referenced by the solution root `tsconfig.json` — because both sides merge cordis `Context` under the same keys (`sessions`, `loader`) with different services; client packages consume the wire vocabulary through pure type subpaths (`@deepseek-ai/dsh-session/types` and kin) so no host augmentation rides into the client program.
 
 ## The slot system: how the page composes
 
-The slot system has its own RFC — the [slot system standard](2026-07-22-slot-type-chain-implementation.md) — and this document defers to it entirely. The one-paragraph summary for orientation: the shell renders only `'root'`; a plugin composes UI through a single `register` call that occupies a slot, declares+authorizes its child slots (`children` spec object), declares its store, and injects its business face; component props arrive in four auto-derived shares (`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject), each from its single source of truth. `SlotMap` declaration merging is the type authority and entries carry only the owner share ("whoever injects it, owns its type"); every rendered entry sits in a per-entry error boundary.
+The slot system has its own note — the [slot system standard](2026-07-22-slot-type-chain-implementation.md) — and this document defers to it entirely. The one-paragraph summary for orientation: the shell renders only `'root'`; a plugin composes UI through a single `register` call that occupies a slot, declares+authorizes its child slots (`children` spec object), declares its store, and injects its business face; component props arrive in four auto-derived shares (`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject), each from its single source of truth. `SlotMap` declaration merging is the type authority and entries carry only the owner share ("whoever injects it, owns its type"); every rendered entry sits in a per-entry error boundary.
 
 Implementation homes: registry core and the props-share types in `packages/client/ui-slots`, outlet/renderer/uSES bridge in `packages/client/web-react`.
 
@@ -73,7 +73,7 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 - **SessionManager** (manager.ts): instance cluster + frame entry + the session list. sessionId-bearing frames go only to existing instances (a mux broadcast must not instantiate every session); approval/question `requested` frames are the exception — they never land in history, so they buffer in `pendingBuffers` and replay on instantiation.
 - **Notifier** (notifier.ts): two channels chosen by change source. `markDirty()` (default; frame-driven changes always) batches per microtask — N changes, one notification, one re-render; the flush rebuilds the snapshot cache before notifying. `notifyNow()` (only direct echoes of user gestures) rebuilds and notifies in the same tick — controlled inputs roll the DOM back and jump the caret if their echo defers to a microtask. Frame-driven code using notifyNow collapses batching back to per-frame renders; banned.
 - **ConversationNodeAssembler** (`runtime/src/client/conversation/`): the Session-owned incremental engine runs independently registered Definitions over raw events. `match(event)` selects `(kind, id)` without Context scans; start/update build Definition state; engine-computed Locations carry Turn/Step closure; backward Context reads record dependencies repaired by later prepends; `buildViewNode(target)` materializes only dirty Contexts. The Chat builder preserves structural order and per-key value identity, `useSession` selectors isolate consumption, and Assistant token publication coalesces to one animation frame. The [Conversation Node decision](2026-08-09-client-conversation-node-assembly.md) owns assembly, while [Tool presentation ownership](2026-08-08-client-tool-presentation-ownership.md) owns recursive Tool rendering.
-- **ConnectionController** (in `packages/client/connection`): opens the mux/host streams, pumps with for-await, reconnects with exponential backoff (500ms doubling to 10s, jitter, unlimited) behind a generation fence; sinks are injected one-way (the Controller does not know Session). Reconnect = rebuild: `onConnected` → list refresh + per-open-session resync. The object layer faces only `IApiClient`; Web carriage uses HTTP POST for the two client→server quadrants and [one WebSocket per logical stream](2026-08-04-websocket-downlink-carrier.md) for the two server→client quadrants, while the client class family remains the layering RFC's territory.
+- **ConnectionController** (in `packages/client/connection`): opens the mux/host streams, pumps with for-await, reconnects with exponential backoff (500ms doubling to 10s, jitter, unlimited) behind a generation fence; sinks are injected one-way (the Controller does not know Session). Reconnect = rebuild: `onConnected` → list refresh + per-open-session resync. The object layer faces only `IApiClient`; Web carriage uses HTTP POST for the two client→server quadrants and [one WebSocket per logical stream](2026-08-04-websocket-downlink-carrier.md) for the two server→client quadrants, while the client class family remains the layering note's territory.
 
 ## The React face (`packages/client/web-react`)
 
@@ -109,7 +109,7 @@ Domain implementation files never import a sibling domain; shared surfaces route
 ## How to develop
 
 - **A new UI feature** = a new plugin package: declare `dshClient` (+ `inject` topology) in package.json, write the browser half under `src/client/` (apply mounts services/stores and registers slots), keep the node half an empty apply unless there is host logic, build with the shared preset. Add the plugin to the host config; the manifest and loading follow automatically.
-- **A new slot**: see the [slot system standard RFC](2026-07-22-slot-type-chain-implementation.md) — merge the contract into `SlotMap`, declare it in the parent entry's `children`, render through the auto-injected `renderSlot` prop. Never export components globally.
+- **A new slot**: see the [slot system standard note](2026-07-22-slot-type-chain-implementation.md) — merge the contract into `SlotMap`, declare it in the parent entry's `children`, render through the auto-injected `renderSlot` prop. Never export components globally.
 - **Consuming a new frame type**: transport-only session frames → Session's dispatch switch; host-level frames → the Manager routing table; logged conversation business events → a Definition plus a keyed view renderer, without a Session business branch.
 - **Where does this state live**: business data (events, streaming, pending) → always the object layer; what the parent knows → owner props at the renderSlot site; private to one component (scroll, search text, expansion) → component state; shared across entries or surviving remounts (selection, drafts, panel widths) → an entry-declared store ([slot system standard](2026-07-22-slot-type-chain-implementation.md)).
 - **Notification channel**: frame-driven/async = `markDirty` batching; direct user-gesture echo whose controlled input needs the same tick = `notifyNow`.
@@ -126,4 +126,4 @@ Token streams no longer shake the render tree: Assistant chunks update one busin
 | window globals / import maps for shared deps | The DI require table keeps sharing explicit, fail-loud, and swappable; globals leak identity and version silently |
 | Business data in zustand slices | The event window/accumulator is a behavioral state machine, not a flat slice; the object layer keeps snapshot granularity and batching controllable |
 | Parallel string-keyed component registry for Tool rows | ui-tool's keyed child slot carries the runtime-open Tool-name set through the one slot registration model ([toolview dissolution](2026-07-23-toolview-dissolution.md)) |
-| Progressive/Suspense boot in P-I | One-flip boot is strictly simpler; the loader's per-plugin status face is kept so progressive lighting can land later without re-architecture |
+| Progressive/Suspense boot in the initial web client delivery | One-flip boot is strictly simpler; the loader's per-plugin status face is kept so progressive lighting can land later without re-architecture |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
index 4294af099d..c37252d1db 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-19-gui-web-client-architecture.md) | 中文
 
-> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/约定面/客户端基类）见 [分层与 RPC 协议 RFC](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
+> 分工线：通道无关的分层模型与 RPC 协议（消息模型/类型体系/约定面/客户端基类）见 [分层与 RPC 协议笔记](2026-07-19-gui-layering-and-rpc-protocol.md)；本篇 = 浏览器侧：client cordis 树如何装载、UI 插件如何经 slot 与服务组合、React-free 对象层如何以不可变快照供给 React。
 
 ## Problem
 
@@ -30,13 +30,13 @@ Status: implemented
 
 ## client cordis 树与装载链
 
-装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双层 boot、热重载——归 [client 插件装载 RFC](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` 约定；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一层预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE 帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
+装载链——两类包（普通包 vs dshClient 插件）、模块系统/插件治理器之分、host 独家撰写的带修订号 entry 图之上的双层 boot、热重载——归 [client 插件装载笔记](2026-07-23-client-plugin-loading-model.md) 所有。本篇赖以立足的事实：浏览器启动与 host 相同的 vendored `@cordisjs/plugin-loader`，由 client 模块系统（`ctx.modules`，`packages/client/modules`）填上其 `internal` 约定；凡带产品行为的单元都是 host 独家撰写的 `__DSH_BOOT__` 图里的 entry——每个生产插件包（含基础设施）都携带 `dshClient` 声明、以 fetch 到达的 `./client` tsdown 闭包 bundle 供给，`immediately` 行的差别仅在 boot 第一层预取，而普通包（react 家族、cordis、尚未升格的库）保持打进壳、已播种、对图不可见；bundle 执行 `window.__ModuleLoader__.load({ id, factory })`，其 `require` 由 lazy CJS 模块表应答（种子词条 + 已登记工厂，首次 require 时物化并记忆化——跨插件值 import 是构建错误，协作走 cordis 服务）；插件 CSS 内联在 bundle 里、物化时注入为 `<style data-plugin="<id>">`（CSS Modules 哈希 + 归属标记 = 隔离，重载时移除）；热重载已在 dev 图落地——webserver 对自己供给的 bundle 做 stat 轮询并广播 `rebuilt` SSE 帧，`client-hmr` 插件每帧换掉一个 fiber。settled 翻转（`loader.await()` + 一次全 ACTIVE 扫描）依旧让壳从 loading 页一次切换到真 UI——settled 意味着每个 entry 已创建、每个 fiber 都到达 ACTIVE，FAILED/PENDING 的 fiber 被大声列出；不存在部分可用模式（渐进渲染为后置工作）。
 
 类型宇宙在聚合层拆分——`tsconfig.host.json` 是 host program、`tsconfig.client.json` 是 client program，二者由 solution 根 `tsconfig.json` 引用，因为两侧都在相同键（`sessions`、`loader`）上对 cordis `Context` 做声明合并且服务不同；client 包经纯类型子路径（`@deepseek-ai/dsh-session/types` 等）消费协议词汇，host 侧的声明合并不会搭车进入 client program。
 
 ## slot 体系：页面怎么拼
 
-slot 体系有自己的 RFC——[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)——本文整体移交给它。此处只留一段定位摘要：壳只渲染 `'root'`；插件用单独一次 `register` 调用组合 UI——占坑、声明并授权子坑（`children` spec 对象）、声明 store、注入业务面；组件 props 分四份额自动推导到达（`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject），各有唯一真源。`SlotMap` 声明合并仍是类型权威，entry 只携带 owner 份额（「谁注入的，类型归谁」）；每个被渲染的注册项都在 per-entry 错误边界之内。
+slot 体系有自己的笔记——[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)——本文整体移交给它。此处只留一段定位摘要：壳只渲染 `'root'`；插件用单独一次 `register` 调用组合 UI——占坑、声明并授权子坑（`children` spec 对象）、声明 store、注入业务面；组件 props 分四份额自动推导到达（`PropsRuntime<K>` / `PropsRenderSlots<S>` / `PropsStore<H>` / inject），各有唯一真源。`SlotMap` 声明合并仍是类型权威，entry 只携带 owner 份额（「谁注入的，类型归谁」）；每个被渲染的注册项都在 per-entry 错误边界之内。
 
 实现的家：注册表核心与 props 份额类型在 `packages/client/ui-slots`，出口组件/渲染器/uSES 桥在 `packages/client/web-react`。
 
@@ -73,7 +73,7 @@ Notifier 微任务合批 ──► ConversationSnapshot 缓存 ──uSES──
 - **SessionManager**（manager.ts）：实例簇 + 帧总入口 + 会话列表。带 sessionId 的帧只投已存在实例（mux 广播不得把每个会话都实例化）；例外是审批/问答 `requested` 帧——它们不落 history、open 无法回补，故缓冲进 `pendingBuffers`，实例化时回放。
 - **Notifier**（notifier.ts）：两条通知通道，按变更来源取用。`markDirty()`（默认；帧驱动一律用它）按微任务合批——N 次变更、一次通知、一次重渲染；flush 先重建快照缓存再通知。`notifyNow()`（仅用户手势的直接回响）同 tick 重建并通知——受控输入的回响若延到微任务，DOM 会回滚、光标跳尾。帧驱动代码用 notifyNow 会让合批塌回逐帧渲染；禁。
 - **ConversationNodeAssembler**（`runtime/src/client/conversation/`）：Session 拥有的增量引擎在原始事件上运行各自独立注册的 Definition。`match(event)` 无须扫描 Context 即可选出 `(kind, id)`；start/update 构造 Definition state；引擎计算的 Location 携带 Turn/Step 关闭信息；向前查询 Context 时记录依赖，并由后续 prepend 修复；`buildViewNode(target)` 只物化 dirty Context。Chat builder 保留结构顺序和 per-key value identity，`useSession` selector 负责消费隔离，Assistant token 发布则合并到每个 animation frame 一次。[Conversation Node 决策](2026-08-09-client-conversation-node-assembly.md)拥有组装边界，[Tool 展示所有权](2026-08-08-client-tool-presentation-ownership.md)拥有 Tool 递归渲染。
-- **ConnectionController**（在 `packages/client/connection`）：开 mux/host 双流、for-await 泵入，代际围栏之内指数退避重连（500ms 翻倍至 10s 封顶、抖动、无限重试）；sinks 单向注入（Controller 不认识 Session）。重连 = 重建：`onConnected` → 列表刷新 + 各已打开会话 resync。对象层只面向 `IApiClient`；Web 承载以 HTTP POST 载两个 client→server 象限、以[每逻辑流一条 WebSocket](2026-08-04-websocket-downlink-carrier.md)载两个 server→client 象限，客户端类族归分层 RFC 属地。
+- **ConnectionController**（在 `packages/client/connection`）：开 mux/host 双流、for-await 泵入，代际围栏之内指数退避重连（500ms 翻倍至 10s 封顶、抖动、无限重试）；sinks 单向注入（Controller 不认识 Session）。重连 = 重建：`onConnected` → 列表刷新 + 各已打开会话 resync。对象层只面向 `IApiClient`；Web 承载以 HTTP POST 载两个 client→server 象限、以[每逻辑流一条 WebSocket](2026-08-04-websocket-downlink-carrier.md)载两个 server→client 象限，客户端类族归分层笔记属地。
 
 ## React 面（`packages/client/web-react`）
 
@@ -109,7 +109,7 @@ src/client/
 ## 怎么开发
 
 - **新 UI 功能** = 新插件包：package.json 声明 `dshClient`（+ `inject` 拓扑），浏览器半边写在 `src/client/`（apply 挂服务/建 store、注册 slot），无 host 逻辑时 node 半边保持空 apply，用共享预设构建。把插件加进 host 配置；manifest 与装载随之自动跟上。
-- **新 slot**：见 [slot 体系标准 RFC](2026-07-22-slot-type-chain-implementation.md)——契约合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
+- **新 slot**：见 [slot 体系标准笔记](2026-07-22-slot-type-chain-implementation.md)——约定合并进 `SlotMap`，在父 entry 的 `children` 里声明，经自动注入的 `renderSlot` prop 渲染。永不全局导出组件。
 - **消费新帧类型**：纯传输 session frame → Session 分发 switch；host 级 frame → Manager 路由表；已记录的 conversation 业务事件 → Definition 加 keyed view renderer，不增加 Session 业务分支。
 - **状态住哪**：业务数据（事件、流式、待答）→ 永远对象层；父知道的 → renderSlot 现场的 owner props；单组件私有（滚动、搜索词、展开集）→ 组件状态；跨 entry 共享或跨重挂载存活（选中、草稿、面板宽）→ entry 声明的 store（[slot 体系标准](2026-07-22-slot-type-chain-implementation.md)）。
 - **通知通道**：帧驱动/异步 = `markDirty` 合批；受控输入需要同 tick 的用户手势直接回响 = `notifyNow`。
@@ -126,4 +126,4 @@ token 流不再震荡渲染树：Assistant chunk 只更新一个业务 Context
 | window 全局变量 / import map 供共享依赖 | DI require 表让共享显式、大声失败、可替换；全局变量静默泄漏身份与版本 |
 | 业务数据进 zustand 切片 | 事件窗口/累积器是行为状态机，不是扁平切片；对象层保住快照粒度与合批的可控性 |
 | Tool 行使用平行的字符串键组件注册表 | ui-tool 的 keyed 子 slot 通过唯一的 slot 注册模型承载运行时开放的 Tool 名称集合（[toolview 溶解](2026-07-23-toolview-dissolution.md)） |
-| P-I 就做渐进/Suspense 启动 | 一次成型严格更简单；loader 的按插件状态面已保留，渐进点亮日后可落地而无需重构 |
+| 首个 web 客户端交付就做渐进/Suspense 启动 | 一次成型严格更简单；loader 的按插件状态面已保留，渐进点亮日后可落地而无需重构 |
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
index 7c4e3bef22..bdeff6702d 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.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 .agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
-2026-07-23-client-plugin-loading-model.md: 302363fcb03a7aa2438b9d97d4e3405db7d6ce8d
-2026-07-23-client-plugin-loading-model.zh.md: 23061a9800b21ada64ef1a3c205c588a9406b67d
+2026-07-23-client-plugin-loading-model.md: fff96f65a21d9527c8fa49589b178c490bacdd5a
+2026-07-23-client-plugin-loading-model.zh.md: 0c0c95ba7ebffca33c2c2d1dec13f745c4316f43
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
index 302363fcb0..fff96f65a2 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-23-client-plugin-loading-model.zh.md)
 
-> Scope: the browser-side plugin loading machinery — what is a plugin, how code arrives, and how hot reload rides on that model. This note owns the loading chain; the [web client architecture RFC](2026-07-19-gui-web-client-architecture.md) defers to it for loading and keeps owning slots, the data object layer, and the React face.
+> Scope: the browser-side plugin loading machinery — what is a plugin, how code arrives, and how hot reload rides on that model. This note owns the loading chain; the [web client architecture note](2026-07-19-gui-web-client-architecture.md) defers to it for loading and keeps owning slots, the data object layer, and the React face.
 
 ## Problem
 
@@ -35,7 +35,7 @@ The manifest owns the package's loading contract: its `inject` dependency edges,
 
 To add a plugin package: declare `dshClient`, emit the `./client` bundle through the shared preset, add the name to the composing app's roster. Nothing else changes hands.
 
-When does a plain package become a plugin? The upgrade law, recorded so the migration path stays honest: **a plain package becomes a plugin package when its consumers switch to cordis DI, not before.** Three promotions are queued: ui-slots (will receive the slots machinery now living in runtime — SlotsService, the renderer contract, the root slot), web-react (will take the renderer install into its own `apply`), and ui-primitives (once components are served through slots/services). Until then they stay plain, and their symbol exports stay ordinary static imports.
+When does a plain package become a plugin? The upgrade law, recorded so the migration path stays honest: **a plain package becomes a plugin package when its consumers switch to cordis DI, not before.** Three promotions are queued: ui-slots (the slots machinery now living in runtime — SlotsService, the renderer contract, the root slot), web-react (the renderer install moving into its own `apply`), and ui-primitives (once components are served through slots/services). Until then they stay plain, and their symbol exports stay ordinary static imports.
 
 Four edge rules govern imports across the two kinds. None of them depends on any per-package mark:
 
@@ -126,7 +126,7 @@ One governance implementation runs on both sides of the wire; the browser-specif
 
 Costs accepted: the vendored Loader carries idle machinery in the browser (EntryTree persistence is a no-op, groups/isolation unused); every plugin edit in dev pays a bundle rebuild plus fiber remount; graph `inject` rows are informational — activation truth is service-level — so a mismatch surfaces at the settled sweep, not at graph validation; the three not-yet-promoted libraries keep their static-import export surface until their DI conversions land; every bundle gains a source-map artifact; and external-script failures provide only coarse URL diagnostics instead of the HTTP status available to an explicit fetch.
 
-Roster endgame (landed 2026-07-25 with the config-tree boot move): the roster lives in `apps/cli/config/web.cordis.yml`, `mountWebPlugins` and the `CLIENT_PACKAGES` constant are gone, and recomposing a deployment means swapping the yml/overlay. The graph composer moved from a webserver-side registry into the `dsh-client-modules` node half (the package upgraded to dual-face per this note's promotion rule — its consumer now reaches it through cordis DI), and the transport split landed alongside: the webserver became a plain route-registration plugin, `/api/*` binding moved to the connection node half over the upgraded `api-gateway` plugin (`dsh-host-apiproxy` providing `ctx.apiProxy`), and the dev bundle watch + SSE channel moved to the hmr node half.
+Roster: it lives in the web bundle's config tree (`packages/bundle/web-app/cordis.patch.yml`); `mountWebPlugins` and the `CLIENT_PACKAGES` constant are gone, and recomposing a deployment means swapping the yml/overlay. The graph composer moved from a webserver-side registry into the `dsh-client-modules` node half (the package upgraded to dual-face per this note's promotion rule — its consumer now reaches it through cordis DI), and the transport split landed alongside: the webserver became a plain route-registration plugin, `/api/*` binding moved to the connection node half over the upgraded `api-gateway` plugin (`dsh-host-apiproxy` providing `ctx.apiProxy`), and the dev bundle watch + SSE channel moved to the hmr node half.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
index 23061a9800..0c0c95ba7e 100644
--- a/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-23-client-plugin-loading-model.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-23-client-plugin-loading-model.md) | 中文
 
-> 范围：浏览器侧的插件装载机件——什么是插件、代码怎么到达、热重载如何搭在这套模型上。装载链归本篇所有；[Web 客户端架构 RFC](2026-07-19-gui-web-client-architecture.md) 在装载问题上以本篇为准，继续拥有 slot、数据对象层与 React 面。
+> 范围：浏览器侧的插件装载机件——什么是插件、代码怎么到达、热重载如何搭在这套模型上。装载链归本篇所有；[Web 客户端架构笔记](2026-07-19-gui-web-client-architecture.md) 在装载问题上以本篇为准，继续拥有 slot、数据对象层与 React 面。
 
 ## Problem
 
@@ -35,7 +35,7 @@ manifest 拥有包的装载约定：它的 `inject` 依赖边，加可选的 `im
 
 新增一个插件包：声明 `dshClient`，经共享预设产出 `./client` bundle，把包名加进负责组合的 app 的名册。除此之外无需任何交接。
 
-普通包何时升格为插件？升级法则，记录在案让迁移路径保持诚实：**普通包在其消费方改用 cordis DI 之时升格为插件包，绝不提前。**三项升格在排队：ui-slots（将接收现居 runtime 的 slots 机件——SlotsService、渲染器约定、root slot）、web-react（将把渲染器安装收进自己的 `apply`）、ui-primitives（组件经 slot/服务供给之时）。在那之前它们保持普通包身份，符号导出保持普通的静态 import。
+普通包何时升格为插件？升级法则，记录在案让迁移路径保持诚实：**普通包在其消费方改用 cordis DI 之时升格为插件包，绝不提前。**三项升格在排队：ui-slots（现居 runtime 的 slots 机件——SlotsService、渲染器约定、root slot）、web-react（渲染器安装移入自己的 `apply`）、ui-primitives（组件经 slot/服务供给之时）。在那之前它们保持普通包身份，符号导出保持普通的静态 import。
 
 四条边规则治理横跨两类包的 import。没有一条依赖任何单包标记：
 
@@ -126,7 +126,7 @@ wire 两侧跑着同一份治理实现；浏览器特有的表面只是一套模
 
 接受的代价：vendored Loader 在浏览器里背着闲置机件（EntryTree 持久化是 no-op，分组/隔离未用）；开发期每次修改插件都要付一次 bundle 重建加 fiber 重挂；图中 `inject` 行仅是信息性说明——激活的真相在服务层——因此不匹配会在 settled 扫描时浮出，而不是在图校验时被拦下；三个尚未升格的库在各自的 DI 转换落地之前保持静态 import 的导出面；每个 bundle 多出一份 sourcemap 产物，外部脚本失败也只能给出粗粒度的 URL 诊断，不能像显式 fetch 那样报告 HTTP 状态。
 
-名册的终局（2026-07-25 随配置树 boot 迁移落地）：名册位于 `apps/cli/config/web.cordis.yml`，`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量已消失，重组一次部署等于换 yml/overlay。图的组合器从 webserver 侧的注册表迁进 `dsh-client-modules` 的 node 半（该包按本 note 的升级法则升格为双面——其消费方现经 cordis DI 到达），传输拆分同轮落地：webserver 变为朴素路由注册插件，`/api/*` 绑定迁到 connection 的 node 半、走升格后的 `api-gateway` 插件（`dsh-host-apiproxy` 提供 `ctx.apiProxy`），dev 的 bundle 监视与 SSE（Server-Sent Events）通道迁到 hmr 的 node 半。
+名册：住在 web 组合包的配置树里（`packages/bundle/web-app/cordis.patch.yml`）；`mountWebPlugins` 与 `CLIENT_PACKAGES` 常量已消失，重组一次部署等于换 yml/overlay。图的组合器从 webserver 侧的注册表迁进 `dsh-client-modules` 的 node 半（该包按本 note 的升级法则升格为双面——其消费方现经 cordis DI 到达），传输拆分同轮落地：webserver 变为朴素路由注册插件，`/api/*` 绑定迁到 connection 的 node 半、走升格后的 `api-gateway` 插件（`dsh-host-apiproxy` 提供 `ctx.apiProxy`），dev 的 bundle 监视与 SSE（Server-Sent Events）通道迁到 hmr 的 node 半。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
index cf3169bccf..86745008b2 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.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 .agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
-2026-07-24-single-harness-home-resolver.md: 159ba88b7b4a8d50f1be2cbe5d9162a654014e16
-2026-07-24-single-harness-home-resolver.zh.md: ed4701bbd4e37ec5c9fba02767efabfbef8d065d
+2026-07-24-single-harness-home-resolver.md: 1e128911dce0b50dc95722c6edd82cb322d18f3d
+2026-07-24-single-harness-home-resolver.zh.md: 258a16e6ca139da191db564aae40d23d05ca46b7
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
index 159ba88b7b..1e128911dc 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md
@@ -32,7 +32,7 @@ An empty or whitespace-only `$DSH_HOME` is treated as unset, matching the guard
 
 **Adopt XDG (honor `$XDG_CONFIG_HOME`, or split config/data/cache into separate trees).** Considered and dropped in favor of one obvious root. A single `$DSH_HOME || ~/.dsh` ground truth matches `~/.claude` / `~/.aws`, needs no per-kind reclassification of every `~/.dsh` consumer, and leaves no resolver asymmetry to reconcile. Telemetry aligning onto the same root — rather than keeping its own XDG path — is precisely the divergence this removes.
 
-**Keep telemetry's own config dir.** Its `deepseek-harness` namespace and separate XDG policy were the lone exception to the `dsh`/`~/.dsh` convention. Folding it onto the shared resolver is what makes "one home fact" true. The cost is that the anonymous id becomes scoped to `$DSH_HOME` rather than the machine: a project that points `DSH_HOME` at a repo-local path (or a command that loads a project `.env` before telemetry) gets a home-local id, so the id counts harness homes, not machines. This is accepted as the intended meaning of single-root — a relocated `$DSH_HOME` moves *all* harness state, telemetry identity included — and the module contract is stated as per-harness-home rather than per-machine. A machine-global identity that ignored `$DSH_HOME` would reintroduce exactly the second home policy this Note removes.
+**Keep telemetry's own config dir.** Its `deepseek-harness` namespace and separate XDG policy were the lone exception to the `dsh`/`~/.dsh` convention. Folding it onto the shared resolver is what makes "one home fact" true. The cost is that the anonymous id becomes scoped to `$DSH_HOME` rather than the machine: a project that points `DSH_HOME` at a repo-local path (or a command that loads a project `.env` before telemetry) gets a home-local id, so the id counts harness homes, not machines. This is accepted as the intended meaning of single-root — a relocated `$DSH_HOME` moves *all* harness state, telemetry identity included — and the module contract is stated as per-harness-home rather than per-machine. A machine-global identity that ignored `$DSH_HOME` would reintroduce exactly the second home policy this decision removes.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
index ed4701bbd4..258a16e6ca 100644
--- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md
@@ -32,7 +32,7 @@ explicit configured path  >  $DSH_HOME  >  ~/.dsh
 
 **采用 XDG（遵从 `$XDG_CONFIG_HOME`，或把 config/data/cache 拆分到各自的目录树）。** 经过考虑后放弃，转而采用一个显而易见的根目录。单一的 `$DSH_HOME || ~/.dsh` 基准事实与 `~/.claude` / `~/.aws` 一致，无需对每个 `~/.dsh` 消费方按类别重新归类，也不留下任何需要协调的解析器不对称。telemetry 对齐到同一根目录——而不是保留自己的 XDG 路径——正是本决策所要消除的那种分歧。
 
-**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。代价是匿名 id 的作用域从机器变成了 `$DSH_HOME`：若某个项目把 `DSH_HOME` 指向仓库本地路径（或某条命令在 telemetry 之前加载了项目的 `.env`），得到的就是 home 本地的 id，因此该 id 统计的是 harness home，而非机器。这被接受为单一根目录的应有含义——重定位 `$DSH_HOME` 会移动*全部* harness 状态，telemetry 身份也在其中——模块约定据此表述为 per-harness-home 而非 per-machine。一个忽略 `$DSH_HOME` 的机器级全局身份，恰恰会重新引入本 Note 所要消除的那第二套 home 策略。
+**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。代价是匿名 id 的作用域从机器变成了 `$DSH_HOME`：若某个项目把 `DSH_HOME` 指向仓库本地路径（或某条命令在 telemetry 之前加载了项目的 `.env`），得到的就是 home 本地的 id，因此该 id 统计的是 harness home，而非机器。这被接受为单一根目录的应有含义——重定位 `$DSH_HOME` 会移动*全部* harness 状态，telemetry 身份也在其中——模块约定据此表述为 per-harness-home 而非 per-machine。一个忽略 `$DSH_HOME` 的机器级全局身份，恰恰会重新引入本决策所要消除的那第二套 home 策略。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
index 073a71d118..327eeef2fb 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.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 .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
-2026-07-25-web-client-session-scope-and-provide-channel.md: 6e4c58c229cea9ff9f0e5ccf03b04c799755244b
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 4d4824f5596139523f5d5b94cb79ba9d1944ff15
+2026-07-25-web-client-session-scope-and-provide-channel.md: ff411e1b387dcd83b04f8c02d5dde3c70a815932
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 593e194654bb3552ad3cac4534847fba11cf3694
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
index 6e4c58c229..ff411e1b38 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
@@ -133,4 +133,4 @@ Slot scope is the closed set `root | session-maybe | session`:
 - The client object layer converges to a wire mirror: session identity, lifecycle, and capability adjudication all defer to the host entity — the input system (the next layer) always faces a session with a real Agent, and providers like slash/skill uniformly address by sessionId directly.
 - Blank-session governance takes zero dedicated mechanisms: state rides one derived bit, visibility rides the unified list projection (only the current blank shows, as `New Session`), reclamation rides lazy persistence's existing contract (evaporation on restart), and the ordinary ceiling rides same-Workspace reuse.
 - The cost: the id→ctx handoff discipline and provide's Concurrent discipline are conventions rather than type-enforced, pinned by review and tests; fully disabled input while no workspace is picked is an experience cost the product surface accepts (the price of the single state axis).
-- Known gaps: approval/question recovery across prune (TODO); model selection returns in live-mutation shape (the host `selectModel` trio is ready-made, awaiting its own branch).
+- Known gaps: approval/question recovery across prune (TODO); model selection returns in live-mutation shape (the host `selectModel` trio is ready-made, its client consumer not yet built).
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
index 4d4824f559..593e194654 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
@@ -133,4 +133,4 @@ slot scope 是闭集 `root | session-maybe | session`：
 - client 对象层收敛为 wire 镜像：会话身份、生命周期、能力判别全部以 host 实体为准——输入体系（下一层）面对的永远是「有真 Agent 的会话」，slash/skill 等提供方一律以 sessionId 直接寻址。
 - 空会话治理零专用机制：状态靠一个派生位，可见性靠统一列表投影（仅 current blank 以 `New Session` 展示），回收靠 lazy persistence 的既有约定（重启蒸发），常规上限靠同 Workspace 复用。
 - 代价：id→ctx 换乘纪律、provide 的 Concurrent 纪律都是约定而非类型强制，靠 review 与测试钉住；「未选 workspace」期间输入全禁是产品面接受的体验代价（单一状态轴换来的）。
-- 已知欠账：approval/question 跨 prune 恢复（TODO）；模型选择以 live-mutation 形状回归（host `selectModel` 三件套现成，等独立分支）。
+- 已知欠账：approval/question 跨 prune 恢复（TODO）；模型选择以 live-mutation 形状回归（host `selectModel` 三件套现成，其 client 消费方尚未构建）。
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml
index f53930928f..f2676ae16c 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.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 .agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md
-2026-07-25-web-command-surfaces-and-assembly.md: 4c4a400abab940baebc1699fc15b709419865f0c
-2026-07-25-web-command-surfaces-and-assembly.zh.md: f0d460199dcd947776924380d51fa6ceb65c9fe2
+2026-07-25-web-command-surfaces-and-assembly.md: 949cdecc8ec13895f6ae323a5dd792499c633d02
+2026-07-25-web-command-surfaces-and-assembly.zh.md: 19c4f93b28cf32009b97fedebe55a861db187bd8
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md
index 4c4a400aba..949cdecc8e 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.md
@@ -28,7 +28,7 @@ The pipeline was ready but command knowledge had no landing spot: host-side `ctx
 
 ### Reference sources (seeing only projections plus their own apply closures, on the root ctx)
 
-- **ui-skill**: `skill.list({sessionId})` addresses by session (the host resolves the project root from the session header); the directory cache is single-flight keyed by sessionId, prewarmed at birth by the `warm` hook and fully cleared by `connection/reset`. A pick produces a text outcome (the literal `/name ` text, Decision 21); `lexicon` supplies the roster from CatalogFetch's settled snapshot (`undefined` while not warm), and `subscribeLexicon` notifies per-session listeners on settle and on invalidation. No match hook (references never enter command adjudication). Skill references ride ordinary prompts as literal text (outside the command plane; tool-skill unchanged, with the session-prefix directory providing the cooperative association).
+- **ui-skill**: `skill.list({sessionId})` addresses by session (the host resolves the project root from the session header); the directory cache is single-flight keyed by sessionId, prewarmed at birth by the `warm` hook and fully cleared by `connection/reset`. A pick produces a text outcome (the literal `/name ` text, the plain-text-reference decision); `lexicon` supplies the roster from CatalogFetch's settled snapshot (`undefined` while not warm), and `subscribeLexicon` notifies per-session listeners on settle and on invalidation. No match hook (references never enter command adjudication). Skill references ride ordinary prompts as literal text (outside the command plane; tool-skill unchanged, with the session-prefix directory providing the cooperative association).
 - **ui-subagent**: candidates are zero-RPC (the sessions.list snapshot filtered by parentId/running); a pick produces a text outcome (the literal `@name ` text); `lexicon` derives from the same snapshot and `subscribeLexicon` forwards the list store's change feed (the model-side representation awaits its business workstream).
 
 ### Fixture command routing and assembly
@@ -49,7 +49,7 @@ The pipeline was ready but command knowledge had no landing spot: host-side `ctx
 | A `skill.invoke` RPC | The host has no such operation; skill references are plain text riding prompts |
 | A new ContentBlock reference type | Full-chain cost (adapters/UI/compaction); text-as-truth plus structured occurrence records suffices |
 | Client packages self-reporting command directories | The host is the single source of truth; the client only reads descriptors, with `commands-changed` pushing invalidation |
-| The `requires: 'none' \| 'agent'` discriminant axis (an agentless directory + dual-addressed queries) | With sessions always agent-backed, the amphibious command has no owner; the whole axis reverts to master's shape, to be reopened on real demand |
+| The `requires: 'none' \| 'agent'` discriminant axis (an agentless directory + dual-addressed queries) | With sessions always agent-backed, the amphibious command has no owner; the whole axis is dropped, to be reopened on real demand |
 | Dedicated commandresult / commandpanel slots | Results go through notices; the popup shell is a skeleton-internal overlay; rich result cards sit in the ledger |
 | An agent-type directory as the `@` source | No type registry exists; the live-session snapshot already covers it |
 | A PickAction/EnterCommand class family (class-inheritance pick products) | Cross-package runtime values break client bundle purity; pure data interfaces plus closure methods are equivalent |
@@ -59,4 +59,4 @@ The pipeline was ready but command knowledge had no landing spot: host-side `ctx
 - Shipping a business command = a host registration plus one client `command.register` (popupSelect) or zero registration (execute/leadingInput derive automatically), with zero skeleton changes; the cost is that the three-kind semantics concentrate in ui-command, and a hypothetical fourth kind means changing it.
 - The resident directory cache plus push invalidation buys zero-latency menus and reliable enter adjudication; the cost is three invalidation paths (the change frame, reconnect, the epoch guard) that all need tests pinning them.
 - sessionId addressing puts the host's per-agent effective directory (global + scoped shadows) straight on the wire, with the client presenting it as-is.
-- Known gaps: the popupSelect shell has no shipped business consumer yet (model selection and its kin return with #600's host `selectModel` in live-mutation shape, serving as the onboarding template then); the queue's second cut (per-item Inbox operations), rich result cards, and roster configurability sit in the ledger awaiting their triggers.
+- Known gaps: the popupSelect shell has no shipped business consumer yet (model selection and its kin arrive with the host `selectModel` work in live-mutation shape, serving as the onboarding template then); the queue's second cut (per-item Inbox operations), rich result cards, and roster configurability sit in the ledger awaiting their triggers.
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
index f0d460199d..19c4f93b28 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ### 引用源（只见投影 + 自家 apply 闭包的 root ctx）
 
-- **ui-skill**：`skill.list({sessionId})` 按会话寻址（host 从会话 header 解析项目根）；目录缓存按 sessionId 键控 single-flight，`warm` 钩子出生预热、`connection/reset` 全清。pick 产出 text outcome（`/name ` 原文，决策 21）；`lexicon` 从 CatalogFetch 的 settled 快照给名录（未热 `undefined`），`subscribeLexicon` 在 settle 与失效时按会话通知监听者。无 match 钩子（引用不进命令裁决）。skill 引用以原文随普通提示词走（命令平面之外；tool-skill 不变，会话前缀目录提供协作关联）。
+- **ui-skill**：`skill.list({sessionId})` 按会话寻址（host 从会话 header 解析项目根）；目录缓存按 sessionId 键控 single-flight，`warm` 钩子出生预热、`connection/reset` 全清。pick 产出 text outcome（`/name ` 原文，纯文本引用决策）；`lexicon` 从 CatalogFetch 的 settled 快照给名录（未热 `undefined`），`subscribeLexicon` 在 settle 与失效时按会话通知监听者。无 match 钩子（引用不进命令裁决）。skill 引用以原文随普通提示词走（命令平面之外；tool-skill 不变，会话前缀目录提供协作关联）。
 - **ui-subagent**：候选零 RPC（sessions.list 快照按 parentId/running 过滤）；pick 产出 text outcome（`@name ` 原文）；`lexicon` 同快照派生，`subscribeLexicon` 转发 list store 的变更通道（模型侧表示待业务立项）。
 
 ### fixture 命令路由与装配
@@ -49,7 +49,7 @@ Status: implemented
 | `skill.invoke` RPC | host 无此操作；skill 引用是随提示词的普通文本 |
 | 新 ContentBlock 引用类型 | 全链路成本（适配器/UI/压缩（compaction））；文本即真身 + 结构化 occurrence 记录已足够 |
 | client 各包自报命令目录 | host 是唯一真源；client 只读 descriptor，`commands-changed` 推失效 |
-| `requires: 'none' \| 'agent'` 判别轴（agentless 目录 + 双址查询） | 会话恒 agent-backed 后两栖命令无 owner；整轴回退 master 形状，待真需求重开 |
+| `requires: 'none' \| 'agent'` 判别轴（agentless 目录 + 双址查询） | 会话恒 agent-backed 后两栖命令无 owner；整轴弃置，待真需求重开 |
 | 专用 commandresult / commandpanel slot | 结果走 notice；popup 壳是骨架内浮层；富结果卡入台账 |
 | agent-type 目录做 `@` 源 | 无类型注册表；实时会话快照已覆盖 |
 | PickAction/EnterCommand 类族（类继承 pick 产物） | 跨包运行时值破坏 client bundle 纯度；纯数据接口 + 闭包方法等价 |
@@ -59,4 +59,4 @@ Status: implemented
 - 业务命令上架 = host 注册 + client 一笔 `command.register`（popupSelect）或零注册（execute/leadingInput 自动派生），零骨架改动；代价是三型语义集中在 ui-command，假想的第四型意味着改它。
 - 常驻目录缓存 + 推失效换来菜单零延迟与回车裁决可靠；代价是三条失效路径（change 帧、重连、epoch guard）都需测试钉住。
 - sessionId 寻址让 host 的 per-agent 有效目录（全局 + scoped shadows）直接上 wire，client 原样呈现。
-- 已知欠账：popupSelect 壳暂无已上架业务消费方（模型选择等将随 #600 的 host `selectModel` 以 live-mutation 形态回归，届时作接入样板）；队列第二刀（逐项 Inbox 操作）、富结果卡、roster 可配置性入台账待触发。
+- 已知欠账：popupSelect 壳暂无已上架业务消费方（模型选择等将随 host `selectModel` 工作以 live-mutation 形态到来，届时作接入样板）；队列第二刀（逐项 Inbox 操作）、富结果卡、roster 可配置性入台账待触发。
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
index 5605f1681e..f670471d90 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.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 .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
-2026-07-25-web-input-machine-and-slash-pipeline.md: 39ef214a94fcd019f535fb60136d5dcc09b54e60
-2026-07-25-web-input-machine-and-slash-pipeline.zh.md: dbd1aebff58c12f33dfe146d5cf4895801035bce
+2026-07-25-web-input-machine-and-slash-pipeline.md: 345a08188fc6a4f2b951e8f9cd9d3a5b953a5e34
+2026-07-25-web-input-machine-and-slash-pipeline.zh.md: d454003036dd322ec3366c66293120cb2997de8d
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
index 39ef214a94..345a08188f 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
@@ -76,9 +76,9 @@ A trigger/menu/pick pipeline with zero knowledge of "commands":
 - When the blank Hero re-picks the Workspace, the shell calls `connectWorkspace`; if the target session differs, the non-empty draft moves from the current shell to the target shell before the new id is opened, and the old blank session survives but is no longer current.
 - The Notifier's two-bit contract: `dirty` (snapshot freshness, clearable by an `ensureFresh` pull) and `notifyPending` (notification debt, cleared only by a flush) are mutually independent — a pull must not swallow a push, and object-layer push subscribers (watchTransaction) depend on this guarantee.
 
-### Plain-text references (Decision 21): text outcomes and lexicon decoration
+### Plain-text references: text outcomes and lexicon decoration
 
-skill/@subagent references skip the placeholder + occurrence identity chain — a pick inserts the literal `/name ` `@name ` text straight into the draft, with the chip visual purely derived:
+skill/@subagent references skip the placeholder + occurrence identity chain — the plain-text-reference decision (externally logged as Decision 21): a pick inserts the literal `/name ` `@name ` text straight into the draft, with the chip visual purely derived:
 
 - PickOutcome gains a `{text}` arm; the new scoped bail event `slash/input-insert-text` `{text, span}` (the same contract as the other three: draftRev CAS, returning true ⟺ an actual rewrite); facade.insertText goes through setDraft concatenation — zero machine changes.
 - Sources get an optional `lexicon?(session)` hook: a synchronous hot-snapshot name roster, with `undefined` = data not warm — zero decoration, never triggering a fetch (the render path stays synchronous and side-effect-free); the paired optional `subscribeLexicon?(session, listener)` hook is the invalidation channel for rolls that change after warm (catalog settles, children spawn/exit). The controller aggregates the rolls into its `lexicon` snapshot store (re-polling on each source notification); sources registered after scope birth are warmed and folded in via the service's live-controller broadcast.
@@ -125,7 +125,7 @@ The state machine's entire behavior is covered by pure-JS unit tests (event sequ
 | A placeholder select resident in the tool row | Named seats stay empty until registration; a placeholder clashing with the real implementation is two sources of truth |
 | An always-visible Plan on/off toggle | The shared Command source already owns entry; a second entry point turns a status seat into redundant mode chrome |
 | A second plus-menu component/controller, or an Add/File group above Command | It would duplicate async candidates, keyboard highlight, focus retention, and pick state; the plus control is only a source-filtered launcher for the existing MenuView, and this scope has no file capability |
-| All references through U+FFFC chips (the pre-Decision-21 line) | Plain text + derived decoration carries zero identity state; the literal text IS the model projection, sparing undo/clipboard any special cases; the chip chain is kept for scenarios needing indivisible atomicity |
+| All references through U+FFFC chips (the line the plain-text-reference decision replaced) | Plain text + derived decoration carries zero identity state; the literal text IS the model projection, sparing undo/clipboard any special cases; the chip chain is kept for scenarios needing indivisible atomicity |
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
index dbd1aebff5..d454003036 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
@@ -76,9 +76,9 @@ occurrence 表与 chip 三投影：
 - blank Hero 改选 Workspace 时，外壳调用 `connectWorkspace`；目标 session 不同时把非空 draft 从当前 shell 搬到目标 shell，再 open 新 id，旧 blank session 留存但不再 current。
 - Notifier 双位约定：`dirty`（快照新鲜度，`ensureFresh` 拉取可清）与 `notifyPending`（通知欠账，只有 flush 清）各自独立——拉取不得吞推送，对象层推订阅者（watchTransaction）依赖这一保证。
 
-### 纯文本引用（决策 21）：text outcome 与 lexicon 装饰
+### 纯文本引用：text outcome 与 lexicon 装饰
 
-skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把 `/name ` `@name ` 原文插进 draft，chip 视觉纯派生：
+skill/@subagent 引用不走占位符 + occurrence 身份链——纯文本引用决策（外部记录为决策 21）：pick 直接把 `/name ` `@name ` 原文插进 draft，chip 视觉纯派生：
 
 - PickOutcome 增 `{text}` arm；新 scoped bail 事件 `slash/input-insert-text` `{text, span}`（与另三个同约定：draftRev CAS、返回 true ⟺ 实际改写）；facade.insertText 走 setDraft 拼接，机器零改动。
 - source 可选 `lexicon?(session)` 钩子：同步热快照名录，`undefined` = 数据未热——零装饰、永不触发 fetch（渲染路径保持同步无副作用）；配对的可选 `subscribeLexicon?(session, listener)` 钩子是名录在 warm 之后仍会变化（目录 settle、子代生灭）时的失效通道。controller 把各名录聚合进自己的 `lexicon` snapshot store（每次 source 通知重拉）；scope 出生后才注册的 source 由 service 广播给活 controller，补 warm 并并入名录。
@@ -125,7 +125,7 @@ skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把
 | 占位 select 常驻工具行 | 具名 slot 在注册前保持为空；占位件与真实现冲突时是双真相源 |
 | 始终可见的 Plan 开／关切换 | 入口已归共享 Command source 所有；第二个入口会把状态 seat 变成冗余的 mode chrome |
 | 第二套加号菜单组件／controller，或在 Command 上方增加 Add/File 分组 | 这会重复异步候选、键盘高亮、焦点保留与 pick 状态；加号控件只是既有 MenuView 按 source 过滤的 launcher，且此 scope 没有文件能力 |
-| 引用一律走 U+FFFC chip（决策 21 前旧线） | 纯文本 + 派生装饰零身份状态；原文即模型投影，undo/剪贴板免特判；chip 链保留给需要不可分原子性的场景 |
+| 引用一律走 U+FFFC chip（纯文本引用决策所取代的旧线） | 纯文本 + 派生装饰零身份状态；原文即模型投影，undo/剪贴板免特判；chip 链保留给需要不可分原子性的场景 |
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
index 830661f8cd..dabe24e211 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.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 .agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
-2026-07-26-subprocess-seam.md: 378f941ead65ebdcacac665d31cd269e7a2e0565
-2026-07-26-subprocess-seam.zh.md: 4e085dcde46ef041985006019d3c6b98fed609c8
+2026-07-26-subprocess-seam.md: 7899af56259d39a4e3f924bcba673c8efa99c682
+2026-07-26-subprocess-seam.zh.md: d9cbc0ebf33bc785984b0a9bd58fa8ebc6aab436
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
index 378f941ead..7899af5625 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md
@@ -25,7 +25,7 @@ Observed stream and lifecycle needs then moved the eligible process consumers on
 
 ## Alternatives considered
 
-**Leave the process plumbing inside `dsh-bash-local` (status quo).** Rejected for the same reason the [task registry split](2026-07-26-task-registry-seam.md) landed: the boundary is stable and already documented in-code (`run.ts`'s module doc said "this layer reacts to an abort signal; the executor owns deadlines and classifies causes"), and keeping it private makes every future non-shell runner either fork the mechanics or depend on a bash-named package for non-bash work. The user-visible driver for this stack was exactly this split.
+**Leave the process plumbing inside `dsh-bash-local` (status quo).** Rejected for the same reason the [task registry split](2026-07-26-task-registry-seam.md) landed: the boundary is stable and already documented in-code (`run.ts`'s module doc said "this layer reacts to an abort signal; the executor owns deadlines and classifies causes"), and keeping it private makes every future non-shell runner either fork the mechanics or depend on a bash-named package for non-bash work. The user-visible driver for this change was exactly this split.
 
 **Keep the original batch-only interface and leave stream consumers bespoke.** Rejected after the observed LSP, ACP, and PTY shapes showed that private process-tree signalling and environment scrubs would otherwise remain duplicated. The Node-shaped dispositions cover those consumers without buffering piped streams.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
index 4e085dcde4..d9cbc0ebf3 100644
--- a/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md
@@ -25,7 +25,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**把进程管道留在 `dsh-bash-local` 里（维持现状）。**否决的理由与[任务注册表拆分](2026-07-26-task-registry-seam.md)得以落地的理由相同：这条边界既稳定，也早已记录在代码里（`run.ts` 的模块文档曾写明「this layer reacts to an abort signal; the executor owns deadlines and classifies causes」），而若继续将它保持私有，未来每个非 shell 运行器就只能要么 fork 这套机制，要么为非 bash 工作去依赖一个以 bash 命名的包。这组堆叠变更对用户可见的动因正是这一拆分。
+**把进程管道留在 `dsh-bash-local` 里（维持现状）。**否决的理由与[任务注册表拆分](2026-07-26-task-registry-seam.md)得以落地的理由相同：这条边界既稳定，也早已记录在代码里（`run.ts` 的模块文档曾写明「this layer reacts to an abort signal; the executor owns deadlines and classifies causes」），而若继续将它保持私有，未来每个非 shell 运行器就只能要么 fork 这套机制，要么为非 bash 工作去依赖一个以 bash 命名的包。本次变更对用户可见的动因正是这一拆分。
 
 **保留最初只支持批量的接口，让流式消费方继续各自实现。**否决：已观察到的 LSP、ACP 与 PTY 形状表明，这会继续保留重复的私有进程树信号与环境清除。Node 形状的处置方式覆盖这些消费方，又不缓冲管道化流。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
index 16ec810666..6acf9b3d72 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.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 .agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
-2026-07-27-dispose-ladder-to-consumer.md: 25deabe811f8eb361690fec2d4fdd40cdf23dd57
-2026-07-27-dispose-ladder-to-consumer.zh.md: 359f800c9c190b7af7c08bf1d7b9b5ebf275cbaf
+2026-07-27-dispose-ladder-to-consumer.md: ab2afd313448438752e15e0f89230124cb95232f
+2026-07-27-dispose-ladder-to-consumer.zh.md: 1171840c77f6d2372b5abc5223786d65406fd5e2
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
index 25deabe811..ab2afd3134 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
@@ -16,7 +16,7 @@ The ladder moves to its one consumer. `dsh-subagent-acp` owns `disposeAcpChild(c
 
 **Keep the ladder on the handle as a convenience.** Rejected: a Service Definition method every Service provider must implement is not a convenience, it is contract surface — and this one encodes one consumer's cooperation shape (stdin-EOF-first) as if it were process vocabulary. The seam's own README already had to caveat that children quiescing on other signals need "their own tier-1", which is the admission that the ladder is policy.
 
-**Move the ladder to a shared helper package.** Rejected: one consumer. A second out-of-process backend with the same stdin-EOF cooperation shape can lift `disposeAcpChild` to shared code when it exists; extracting now would recreate `dsh-subagent-subprocess`, the single-purpose library this stack just deleted.
+**Move the ladder to a shared helper package.** Rejected: one consumer. A second out-of-process backend with the same stdin-EOF cooperation shape can lift `disposeAcpChild` to shared code when it exists; extracting now would recreate `dsh-subagent-subprocess`, the single-purpose library this change deleted.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
index 359f800c9c..1171840c77 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 **把阶梯作为便利方法留在句柄上。**否决：一个每个 Service provider 都必须实现的 Service Definition 方法不是便利，而是约定表面——而这一个把某一消费方的配合形状（stdin EOF 打头）当作进程词汇来编码。seam 自己的 README 早已不得不加注「依赖其他信号才能完全停稳的子进程需要自己的第一阶」，这本身就是承认该阶梯是策略。
 
-**把阶梯移到共享辅助包。**否决：只有一个消费方。当第二个具有相同 stdin EOF 配合形状的进程外后端出现时，可以再把 `disposeAcpChild` 提升为共享代码；现在抽取只会重造 `dsh-subagent-subprocess`——这组堆叠变更刚刚删掉的那个单一用途库。
+**把阶梯移到共享辅助包。**否决：只有一个消费方。当第二个具有相同 stdin EOF 配合形状的进程外后端出现时，可以再把 `disposeAcpChild` 提升为共享代码；现在抽取只会重造 `dsh-subagent-subprocess`——本次变更删掉的那个单一用途库。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.i18n.yaml
index 0e2d5229a6..944734d054 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.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 .agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
-2026-07-28-api-browser-trust-boundary.md: e56d0fc2a7bd551899605491f3a0522b62b961b0
-2026-07-28-api-browser-trust-boundary.zh.md: 36a8323868f01f4cf16107ae62b649ade436482b
+2026-07-28-api-browser-trust-boundary.md: 7c1615fedf0f18f5e2c341b2246415057a6ee172
+2026-07-28-api-browser-trust-boundary.zh.md: fc210921918f2e790f3f1fe36edd66e73f19d74c
diff --git a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
index e56d0fc2a7..7c1615fedf 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md
@@ -6,11 +6,11 @@ English | [中文](2026-07-28-api-browser-trust-boundary.zh.md)
 
 ## Problem
 
-The web GUI host serves `/api` over plain HTTP (default `127.0.0.1:3080`, `--host 0.0.0.0` supported), and the surface includes remote-code-execution-grade methods — `session.prompt` drives an agent that runs bash. A browser turns the operator into a confused deputy against such a local API in two classic ways: a malicious page fires a "simple" cross-site POST (`text/plain` — sent without a CORS preflight) whose side effects execute even though the response stays unreadable, and a DNS-rebound origin talks to the socket as if same-origin, making CORS inapplicable entirely, with only the `Host` header betraying the attacker's domain. Before this decision the system's only browser-trust check (`isTrustedNativeDialogRequest`: loopback socket + same-origin + loopback Host) guarded exactly one cosmetic route — `host.pickDirectory`, whose native dialog pops on the host's screen — while every consequential method was unguarded. Guarding per-RPC also could not survive the upcoming in-app directory browser, whose whole point is serving legitimately remote clients that a loopback rule would refuse.
+The web GUI host serves `/api` over plain HTTP (default `127.0.0.1:3080`, `--host 0.0.0.0` supported), and the surface includes remote-code-execution-grade methods — `session.prompt` drives an agent that runs bash. A browser turns the operator into a confused deputy against such a local API in two classic ways: a malicious page fires a "simple" cross-site POST (`text/plain` — sent without a CORS preflight) whose side effects execute even though the response stays unreadable, and a DNS-rebound origin talks to the socket as if same-origin, making CORS inapplicable entirely, with only the `Host` header betraying the attacker's domain. Before this decision the system's only browser-trust check (`isTrustedNativeDialogRequest`: loopback socket + same-origin + loopback Host) guarded exactly one cosmetic route — `host.pickDirectory`, whose native dialog pops on the host's screen — while every consequential method was unguarded. Guarding per-RPC also could not survive the in-app directory browser, whose whole point is serving legitimately remote clients that a loopback rule would refuse.
 
 ## Decision
 
-Enforce browser trust once, at the carrier, for the entire `/api` prefix — two halves in two stacked PRs:
+Enforce browser trust once, at the carrier, for the entire `/api` prefix — two halves:
 
 - **Media-type fence (dsh-host-apiproxy)**: every `/api` POST must declare `application/json`, else 415 before parsing. Cross-site "simple" requests thereby stop existing: any cross-site attempt is forced into a CORS preflight this server never answers.
 - **Authority fence (dsh-client-connection, `src/api-request-trust.ts`)**: every request must present a `Host` that is loopback or matches a `trustedHosts` entry (exact on `host:port`, any port on port-less entries, WHATWG-normalized; rebinding defense). Deliberately no shortcut for unmarked requests: over plain HTTP a browser attaches neither `Origin` nor Fetch-Metadata to reads (EventSource, images, navigations — those headers go only to trustworthy destinations), so an unmarked request may be a rebound browser read whose response the page can read, and Host is the one header rebinding cannot forge; non-browser clients pass via loopback, the derived LAN IP literals, or a declared authority. An attached `Origin` must equal the Host authority; `sec-fetch-site: cross-site` is refused outright. A `trustedHosts` entry that is not a bare, canonical authority fails the plugin load — WHATWG parsing would otherwise quietly authorize the hostname inside a typo or broaden an exact-port grant. `host.pickDirectory` loses its bespoke guard and rides the same fence.
diff --git a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md
index 36a8323868..fc21092191 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md
@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-Web GUI 宿主以纯 HTTP 提供 `/api`（默认 `127.0.0.1:3080`，支持 `--host 0.0.0.0`），而这个面上有远程代码执行级别的方法——`session.prompt` 驱动的 agent 可以运行 bash。浏览器会用两种经典方式把操作者变成攻击此类本地 API 的"混淆代理人"：恶意页面发出跨站"简单请求" POST（`text/plain`——不经 CORS 预检即发出），其副作用照常执行、只是响应不可读；以及 DNS rebinding 后的源以「同源」身份直连 socket，CORS 整体失效，只有 `Host` 头会暴露攻击者的域名。在本决策之前，系统里唯一的浏览器信任检查（`isTrustedNativeDialogRequest`：回环 socket + 同源 + 回环 Host）只守着一个装饰性的路由——`host.pickDirectory`，其原生对话框弹在宿主屏幕上——而所有真正具有严重后果的方法都没有防护。按 RPC 逐个设防也活不过即将到来的应用内目录浏览器：它存在的意义就是服务合法的远程客户端，回环规则恰恰会拒绝它们。
+Web GUI 宿主以纯 HTTP 提供 `/api`（默认 `127.0.0.1:3080`，支持 `--host 0.0.0.0`），而这个面上有远程代码执行级别的方法——`session.prompt` 驱动的 agent 可以运行 bash。浏览器会用两种经典方式把操作者变成攻击此类本地 API 的"混淆代理人"：恶意页面发出跨站"简单请求" POST（`text/plain`——不经 CORS 预检即发出），其副作用照常执行、只是响应不可读；以及 DNS rebinding 后的源以「同源」身份直连 socket，CORS 整体失效，只有 `Host` 头会暴露攻击者的域名。在本决策之前，系统里唯一的浏览器信任检查（`isTrustedNativeDialogRequest`：回环 socket + 同源 + 回环 Host）只守着一个装饰性的路由——`host.pickDirectory`，其原生对话框弹在宿主屏幕上——而所有真正具有严重后果的方法都没有防护。按 RPC 逐个设防也活不过应用内目录浏览器：它存在的意义就是服务合法的远程客户端，回环规则恰恰会拒绝它们。
 
 ## 决策
 
-在载体层对整个 `/api` 前缀一次性执行浏览器信任检查——两部分分别由两个堆叠 PR 实现：
+在载体层对整个 `/api` 前缀一次性执行浏览器信任检查——分为两部分：
 
 - **媒体类型栅栏（dsh-host-apiproxy）**：每个 `/api` POST 必须声明 `application/json`，否则在解析前以 415 拒绝。跨站「简单请求」由此不复存在：任何跨站尝试都被逼进一次本服务器从不应答的 CORS 预检。
 - **权威栅栏（dsh-client-connection，`src/api-request-trust.ts`）**：每个请求的 `Host` 都必须是回环地址，或与某个 `trustedHosts` 条目匹配（带端口的 `host:port` 条目精确匹配，不带端口的条目匹配任意端口，均经 WHATWG 归一化；rebinding 防御）。刻意不为无标记请求开捷径：明文 HTTP 下浏览器的读取（EventSource、图片、导航——这些头只发给可信目标）既不带 `Origin` 也不带 Fetch-Metadata，因此无标记请求可能是被重绑页面发起且响应可被读走的读取，而 Host 是重绑唯一伪造不了的请求头；非浏览器客户端经由回环地址、推导的 LAN IP 字面量或已声明的权威通过。若带 `Origin` 则必须与 Host 权威完全一致；`sec-fetch-site: cross-site` 一律拒绝。不是单纯规范化 authority 的 `trustedHosts` 条目会导致插件加载失败——否则 WHATWG 解析会悄悄授权笔误里的 hostname，或放大精确端口授权。`host.pickDirectory` 失去专属守卫，与其他请求同栅而行。
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
index 2ab9d7c12b..ae12dd3bb4 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.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 .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
-2026-07-28-directory-picker-capability-seam.md: 898d8dc3a6fa41cfacc694f15c88d3a71c48f413
-2026-07-28-directory-picker-capability-seam.zh.md: fce9a801ad8535b264c91f6d3b32373e35cb146d
+2026-07-28-directory-picker-capability-seam.md: 2e663e9bc90841dd843bf8a8ff5676e4ca3b91b3
+2026-07-28-directory-picker-capability-seam.zh.md: 14af29a88648a7f6581ec16a4fb3698a0d9669e5
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
index 898d8dc3a6..2e663e9bc9 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-28-directory-picker-capability-seam.zh.md)
 
 ## Problem
 
-The web GUI's "Open local folder" flow was hardwired to one interaction: `host.pickDirectory` invoked a native OS chooser compiled into `dsh-host-apiproxy` (private module, test-only injection point). That shape cannot serve remote deployments — no OS dialog reaches a browser on another machine — and the planned in-app directory browser (Figma `Harness` 802-56979) needs listing/creation primitives, which are a different interaction contract, not a different implementation of the same one. Swapping interactions required editing gateway source, against the repo's everything-is-a-plugin stance.
+The web GUI's "Open local folder" flow was hardwired to one interaction: `host.pickDirectory` invoked a native OS chooser compiled into `dsh-host-apiproxy` (private module, test-only injection point). That shape cannot serve remote deployments — no OS dialog reaches a browser on another machine — and the in-app directory browser (Figma `Harness` 802-56979) needs listing/creation primitives, which are a different interaction contract, not a different implementation of the same one. Swapping interactions required editing gateway source, against the repo's everything-is-a-plugin stance.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
index fce9a801ad..14af29a886 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md
@@ -6,7 +6,7 @@
 
 ## 问题
 
-web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入点）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而计划中的应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互约定**，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
+web GUI 的"打开本地文件夹"流程被焊死在一种交互上：`host.pickDirectory` 调用编译进 `dsh-host-apiproxy` 的原生 OS 选择器（私有模块，仅测试注入点）。这个形态服务不了远程部署——没有任何 OS 对话框能弹到另一台机器的浏览器里——而应用内目录浏览器（Figma `Harness` 802-56979）需要列举／创建原语，那是**另一种交互约定**，不是同一约定的另一种实现。想换交互只能改网关源码，违背仓库"一切皆插件"的立场。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
index 512bd4fac7..7a120346c3 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.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 .agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
-2026-07-28-user-settings-seam.md: 62eae0db157d61266af165f609daaefcd7d5e285
-2026-07-28-user-settings-seam.zh.md: bf0f5d850f4cf303efdbd6476ae210cf8779a31d
+2026-07-28-user-settings-seam.md: 58104df1fbba302372c34ce5cba6c59f2d108cfd
+2026-07-28-user-settings-seam.zh.md: 3d160a0ad9dbc86233ea6fb3bd462f71d73becba
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
index 62eae0db15..58104df1fb 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.md
@@ -26,9 +26,9 @@ User-editable configuration had no owner: `dsh web` read a cwd-anchored profile
 
 - **Include write-back as the user layer** (per-plugin config pages writing loader entry files, cordis-webui style): write-back would target per-composition files, binding user preferences to one `cordis.yml`; a per-user layer must survive template upgrades and serve TUI and web from one document.
 - **Loader-reactive `fiber.update` as the propagation channel**: constructor-time reads observe nothing; the seam's explicit `watch()` makes hot-update a consumer contract instead of framework magic.
-- **A domain-aware settings service** (getters per product area): the coupling objection from design review stands; the service stores, validates, and publishes — domain meaning stays with the registrant that owns the schema.
+- **A domain-aware settings service** (getters per product area): rejected as coupling; the service stores, validates, and publishes — domain meaning stays with the registrant that owns the schema.
 - **Multi-layer precedence now** (system/managed/project tiers à la Codex/Claude Code): deferred until a real second layer exists; the resolve step is the single place layering would extend.
-- **A cross-process lockfile now** (Pi's proper-lockfile): initially deferred as "atomic replace plus watcher convergence until real contention shows up" — review showed convergence loses unobserved sibling namespaces, so the deferral is superseded by the [write-path integrity note](2026-07-30-settings-write-path-integrity.md)'s hand-rolled writer lock.
+- **A cross-process lockfile now** (Pi's proper-lockfile): initially deferred as "atomic replace plus watcher convergence until real contention shows up" — but convergence loses unobserved sibling namespaces, so the deferral is superseded by the [write-path integrity note](2026-07-30-settings-write-path-integrity.md)'s hand-rolled writer lock.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
index bf0f5d850f..3d160a0ad9 100644
--- a/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-28-user-settings-seam.zh.md
@@ -26,9 +26,9 @@ Status: implemented
 
 - **以 Include 写回为用户层**（cordis-webui 式的按插件配置页写 loader entry 文件）：写回目标是按组合的文件，会把用户偏好绑死在某个 `cordis.yml` 上；用户层必须在模板升级中存活，并以同一文档服务 TUI 与 web。
 - **以 Loader reactive `fiber.update` 为传导通道**：构造期读取毫无感知；seam 的显式 `watch()` 把热更新变成消费者约定而非框架魔法。
-- **领域化的 settings 服务**（按产品域的 getter）：设计评审中的耦合反对成立；服务只做存储、校验、发布——领域含义留给拥有 schema 的注册方。
+- **领域化的 settings 服务**（按产品域的 getter）：因耦合而否决；服务只做存储、校验、发布——领域含义留给拥有 schema 的注册方。
 - **现在就做多层优先级**（Codex/Claude Code 式 system/managed/project 层级）：延后到真实第二层出现；resolve 步骤是分层未来唯一的扩展点。
-- **现在就上跨进程锁**（Pi 的 proper-lockfile）：最初以"原子替换加 watcher 收敛，真实冲突出现再说"为由延后——评审发现收敛会丢失未观察到的同级 namespace，因此该延后已被 [write-path integrity note](2026-07-30-settings-write-path-integrity.md) 的手写写锁取代。
+- **现在就上跨进程锁**（Pi 的 proper-lockfile）：最初以"原子替换加 watcher 收敛，真实冲突出现再说"为由延后——但收敛会丢失未观察到的同级 namespace，因此该延后已被 [write-path integrity note](2026-07-30-settings-write-path-integrity.md) 的手写写锁取代。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
index fd4c24db70..8f17ecd480 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.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 .agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
-2026-07-29-dsh-source-launch-tsx-esm.md: aabe6c2d6a92b5cc6568eee1d42df3a6998cf0ca
-2026-07-29-dsh-source-launch-tsx-esm.zh.md: ecda8b273b3efc4773dbe3ed25a9ef0572b79ce4
+2026-07-29-dsh-source-launch-tsx-esm.md: ed22e51d59a25db130b3760ce484c116bade4348
+2026-07-29-dsh-source-launch-tsx-esm.zh.md: bdd549092eb30f7749c8f7561068daafe3548b28
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
index aabe6c2d6a..ed22e51d59 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md
@@ -16,7 +16,7 @@ Startup latency also mattered: the off-thread `module.register()` hooks worker s
 
 The `dsh` TUI, Web, and headless source launches run `node --import tsx/esm`: tsx's ESM-only hook owns both TypeScript transformation and tsconfig `paths` projection. `bin/dsh`, the root `dsh`/`demo:tui`/`demo:web` scripts, and the Code Mode TUI overlay use the same vector; `bin/dsh` references the hook and tsconfig by absolute checkout paths (bare `tsx/esm` does not resolve from an arbitrary cwd) and pins `TSX_TSCONFIG_PATH` to the root tsconfig. The CJS hook stays off because the CLI source graph is ESM-only; measured TUI time-to-banner is ~0.7s versus ~1.1s under the full tsx default and ~0.75s under the removed native chain.
 
-`scripts/tspath-loader.ts` and `apps/cli/src/tsconfig-paths-loader.ts` are deleted. With them went the loader's runtime rule of mapping a workspace import only for declared runtime dependencies — tsx applies the `paths` map unconditionally. Declaration completeness now rests on the static gates alone: `verify-cordis-config` for configured bare plugins, and workspace constraints for manifests. (That runtime rule found real bugs: `dsh-plan-mode` and `dsh-tool-tasks` imported `@deepseek-ai/dsh-llm` while declaring it only in devDependencies; fixed alongside this change.)
+`scripts/tspath-loader.ts` and `apps/cli/src/tsconfig-paths-loader.ts` are deleted. With them went the loader's runtime rule of mapping a workspace import only for declared runtime dependencies — tsx applies the `paths` map unconditionally. Declaration completeness now rests on the static gates alone: `verify-cordis-config` for configured bare plugins, and workspace constraints for manifests. (That runtime rule found real bugs: `dsh-plan-mode` and `dsh-tool-tasks` imported `@deepseek-ai/dsh-llm` while declaring it only in devDependencies; since fixed.)
 
 The node-compat CI matrix (Node 22.19 and 26) gains `dsh-source-launch-smoke` (`apps/cli/tests/source-launch.compat.spec.ts`): a keyless piped-stdio launch of the exact production vector asserting the non-zero-exit TTY refusal. Any future Node change to module hooks or TypeScript handling turns this gate red instead of breaking developers' `pnpm dsh`.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
index ecda8b273b..bdd549092e 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 `dsh` 的 TUI、Web 与无头源码启动运行 `node --import tsx/esm`：由 tsx 的 ESM-only 钩子同时负责 TypeScript 转换与 tsconfig `paths` 投影。`bin/dsh`、根目录的 `dsh`/`demo:tui`/`demo:web` 脚本以及 Code Mode TUI overlay 使用同一向量；`bin/dsh` 以 checkout 的绝对路径引用钩子与 tsconfig（裸的 `tsx/esm` 无法从任意 cwd 解析），并将 `TSX_TSCONFIG_PATH` 固定到根 tsconfig。CJS 钩子保持关闭，因为 CLI 源码图是纯 ESM；实测 TUI 到 banner 约 0.7s，对比完整 tsx 默认形态约 1.1s、已移除的原生链约 0.75s。
 
-`scripts/tspath-loader.ts` 与 `apps/cli/src/tsconfig-paths-loader.ts` 已删除。随之消失的还有该 loader「仅为已声明运行时依赖映射 workspace import」的运行时规则——tsx 无条件应用 `paths` 映射。声明完整性现在仅由静态门禁保障：配置的裸插件走 `verify-cordis-config`，manifest（元数据清单）走 workspace constraints。（该运行时规则确实发现过真实缺陷：`dsh-plan-mode` 与 `dsh-tool-tasks` 导入 `@deepseek-ai/dsh-llm` 却只声明在 devDependencies；已随本变更修复。）
+`scripts/tspath-loader.ts` 与 `apps/cli/src/tsconfig-paths-loader.ts` 已删除。随之消失的还有该 loader「仅为已声明运行时依赖映射 workspace import」的运行时规则——tsx 无条件应用 `paths` 映射。声明完整性现在仅由静态门禁保障：配置的裸插件走 `verify-cordis-config`，manifest（元数据清单）走 workspace constraints。（该运行时规则确实发现过真实缺陷：`dsh-plan-mode` 与 `dsh-tool-tasks` 导入 `@deepseek-ai/dsh-llm` 却只声明在 devDependencies；后已修复。）
 
 node-compat CI 矩阵（Node 22.19 与 26）新增 `dsh-source-launch-smoke`（`apps/cli/tests/source-launch.compat.spec.ts`）：以精确的生产启动向量做 keyless 管道 stdio 启动，断言非零退出的 TTY 拒绝。未来 Node 对模块钩子或 TypeScript 处理的任何改动都会让该门禁变红，而不是破坏开发者的 `pnpm dsh`。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
index e597017076..c50bf478ad 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.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 .agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
-2026-07-29-package-regrouping.md: bb9f7deb775a0922de8b20f766446ebf007718d3
-2026-07-29-package-regrouping.zh.md: 1d7d79e0cfad95382c036b3c99712775870aa48a
+2026-07-29-package-regrouping.md: 3c37bce05bacd6af800a76ac93fb691b896a6772
+2026-07-29-package-regrouping.zh.md: 68903ff1fad6a975c4445fe8971c8fe0dd40117f
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
index bb9f7deb77..3c37bce05b 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md
@@ -29,10 +29,10 @@ Six groups are recomposed; every other group keeps its prior boundary and conten
 | `guard/` | repeat-tool-guard, timeout-policy | `guard/` + `timeout/` |
 | `self-modification/` | tool-cordis | `cordis/` |
 
-- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (review: prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ended the group-name collision with `dsh-telemetry`.
+- **`session/`** is the durable session data plane: the persistence seam with its backends and checkpoint policy, the projection fold that serves whole values from that log, log-backed titles, and OTel reporting. The title fold is itself load-bearing for the read side (`session-query` peer-depends on `dsh-session-title`), so titles belong with the data plane, not in a derived-services annex. The plain name is deliberate (prefer names a human would say); the nearby `core/session` package remains the live in-memory service, while this group is the durable family around it. `session-query/` stays a standalone group — the read/tool surface has its own model tools and SQLite FTS backend and is consumed independently of persistence internals. Absorbing `telemetry/` ended the group-name collision with `dsh-telemetry`.
 - **`interaction/`** is the human-collaboration plane plus the terminal channel that answers it: the question/approval seams, the permission preset, the model-facing `ask_user_question` tool, the human-command registry (`plan-mode` and `command-goal` already consume `commands` together with the interaction seams), and `tui` — the interactive channel is the plane's richest provider and consumer (peer edges to `commands` and `user-interaction`), and a one-package `tui/` group would spend a top-level name on one plugin.
 - **`boot/`** is a role-complete single-package group: the shared bin boot glue that belongs to no channel and no assembly (consumed by `apps/cli`, the `scaffold/` launcher, and the `examples/` demo bins).
-- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is the former `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/` in review: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it said nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style; the three affected npm names are mapped explicitly beside the group wildcard in `tsconfig.base.json` until the deferred renames land.
+- **`scaffold/`** is the developer-tooling family: project helper, launcher, initializer, wire protocol with both ends (`server` is the former `ui/jsonrpc`), and launcher telemetry. Renamed from `sdk/`: the whole `packages/` tree *is* the SDK, so a group named `sdk/` inside it said nothing; `scaffold/` names the create/launch/drive-a-project role. Folders drop the legacy `sdk-` prefix (`protocol`, `client`, `server`), matching the `client/`/`host/` role-named folder style; the three affected npm names are mapped explicitly beside the group wildcard in `tsconfig.base.json` until the deferred renames land.
 - **`guard/`** keeps its documented role, loop-hygiene guards, and gains the tool-call timeout enforcer, dissolving the one-package `timeout/` group whose name collided with `util/timeout`.
 - **`self-modification/`** names the role `cordis/` obscured: the toolset with which the agent inspects and mounts plugins in its own live runtime, and the landing zone for future self-modification packages.
 
@@ -54,11 +54,11 @@ The first four are settled intent; resolving them converges the SDK wire stack's
 
 ## What the move touched
 
-The moves landed as `git mv` commits, one per region (the session fold; `ui/` dissolution + `scaffold/`; `guard/` merge + `self-modification/`), so rename detection carries review. A group move touched: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose and gate scripts. Remaining group-path referents (workspace configs, test globs, lint keys) were found mechanically by the acceptance gates failing loud — the repository's own misconfiguration rule.
+The moves landed as pure `git mv` moves, so rename detection carries the history. A group move touched: the moved package's `tsconfig.json` relative `references` and every dependent's entry (including the `apps/cli` project references), the tsconfig aggregate and path maps, group READMEs (five new bilingual triplets, deletions for dissolved groups, the [packages/README.md](../../../../packages/README.md) hierarchy table, the root `AGENTS.md` layout map), regenerated artifacts (`docs/module-graph.md`, path-embedding catalogs, the lockfile's importer keys), and root-relative `packages/...` citations in prose and gate scripts. Remaining group-path referents (workspace configs, test globs, lint keys) were found mechanically by the acceptance gates failing loud — the repository's own misconfiguration rule.
 
-A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name. Each FIXME landed in the same commit as the move that created its context.
+A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name.
 
-`client/` and `host/` were out of scope and are unchanged. The `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision; the only interaction is a trivial merge in the packages/README.md table.
+`client/` and `host/` were out of scope and are unchanged. The `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision.
 
 ## Alternatives considered
 
@@ -68,21 +68,21 @@ A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot f
 
 **A full npm rename sweep** (`dsh-<group>-<pkg>` for every package). Rejected: npm names are flat, so group-prefixing adds churn across imports, configs, and fixtures with no disambiguation gain; targeted FIXME-tracked renames cover the actual collisions.
 
-**Performing the five renames inside the reorganization.** Rejected in review: renames multiply open-PR conflicts and destroy the pure-move review property. The FIXME markers keep them visible release blockers to resolve as small follow-up PRs.
+**Performing the five renames inside the reorganization.** Rejected: renames multiply open-PR conflicts and destroy the pure-move review property. The FIXME markers keep them visible release blockers to resolve as small follow-up PRs.
 
 **A two-way session split** (`session-core/` + `session-utils/`). Rejected: query belongs to neither side cleanly, and `session-core` invites confusion with `core/session` (`dsh-session`, the live in-memory service, which stays in `core/`).
 
-**A three-way session split** (`session-store/` + `session-query/` + `session-utils/`), this RFC's first draft. Rejected in review: `session-utils/` was a negatively-defined annex ("derived, nothing load-bearing depends on it") — the grab-bag shape the north star forbids, and factually wrong besides (`session-query` peer-depends on `dsh-session-title`). The invented compound names also read machine-generated; one plain `session/` group says what a human would say. Query stays standalone in both drafts: it is an independently consumed read surface with its own tool package and backend.
+**A three-way session split** (`session-store/` + `session-query/` + `session-utils/`). Rejected: `session-utils/` was a negatively-defined annex ("derived, nothing load-bearing depends on it") — the grab-bag shape the north star forbids, and factually wrong besides (`session-query` peer-depends on `dsh-session-title`). The invented compound names also read machine-generated; one plain `session/` group says what a human would say. Query stays standalone regardless: it is an independently consumed read surface with its own tool package and backend.
 
 **Recomposing `ui/` as a single `channels/` group** (tui + jsonrpc + acp + interaction seams + boot). Rejected: the same grab-bag under a new name — those packages serve four planes, `jsonrpc`'s measured cluster is the SDK wire stack, and `acp/` is an automation transport, not a human channel.
 
-**A standalone one-package `tui/` group**, this RFC's first draft. Rejected in review: `tui` is the interaction plane's primary provider/consumer (peer edges to `commands`, `user-interaction`), and a top-level name spent on one plugin adds a group without adding information; it folds into `interaction/`.
+**A standalone one-package `tui/` group.** Rejected: `tui` is the interaction plane's primary provider/consumer (peer edges to `commands`, `user-interaction`), and a top-level name spent on one plugin adds a group without adding information; it folds into `interaction/`.
 
-**Keeping the group name `sdk/`.** Rejected in review: the whole `packages/` tree is the SDK, so an `sdk/` group inside it discriminates nothing — the same disease as `cordis/`. `scaffold/` names the actual role (create, launch, and drive projects from outside).
+**Keeping the group name `sdk/`.** Rejected: the whole `packages/` tree is the SDK, so an `sdk/` group inside it discriminates nothing — the same disease as `cordis/`. `scaffold/` names the actual role (create, launch, and drive projects from outside).
 
-**Moving `app-boot` to `apps/`** (review question). Rejected: `apps/` is the assembly tier over the package tier, and `dsh-app-boot` is a library that package-tier code imports (`scaffold/scripts`' launcher peer-depends on it) — placing it in `apps/` would invert the tiers and put a workspace library outside the `packages/*/*` build globs. It stays a package; `boot/` is its role-complete home.
+**Moving `app-boot` to `apps/`.** Rejected: `apps/` is the assembly tier over the package tier, and `dsh-app-boot` is a library that package-tier code imports (`scaffold/scripts`' launcher peer-depends on it) — placing it in `apps/` would invert the tiers and put a workspace library outside the `packages/*/*` build globs. It stays a package; `boot/` is its role-complete home.
 
-**Moving `tool-cordis` into `core/`.** Rejected: self-modification is its own product seam, expected to grow; the spine stays minimal. The group was first named `self-evolve/`; review settled on `self-modification/` as the plainer term.
+**Moving `tool-cordis` into `core/`.** Rejected: self-modification is its own product seam, expected to grow; the spine stays minimal. The group was first named `self-evolve/`; the name settled on `self-modification/` as the plainer term.
 
 **Renaming `context/` to `request-context/`.** Rejected: within this tree the group is unambiguous in situ; the churn is unjustified.
 
@@ -90,7 +90,7 @@ A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot f
 
 - The tree matches the map: the six recomposed groups hold exactly the listed members; the groups `ui/`, `sdk/`, `telemetry/`, `timeout/`, `cordis/`, `session-persistence/`, `session-projection/`, and `session-title/` no longer exist; every other group's contents are unchanged. The workspace package-name set is identical before and after (zero npm renames), and the five FIXME markers pin the deferred ones. A FIXME that later proves wrong must be removed explicitly with rationale, never silently dropped.
 - What pins the result: `pnpm run typecheck`, the unit suites of every moved group, `verify-package-paths`, `verify-md-links`, and the corpus-wide translation pairing all pass on the moved tree; the group-scoped test globs in `vitest.snapshot.config.ts` were rewritten with the moves so the suites collect the same test files as before (a fail-open glob would silently drop coverage).
-- Every open PR touching a moved file rebases across the move once; the mapping table in the PR body and rename detection resolve most hunks mechanically.
+- Every open PR touching a moved file rebases across the move once; rename detection resolves most hunks mechanically.
 - Single-package groups remain (`boot/`, `self-modification/`, and existing ones such as `acp/`). Accepted deliberately: each is role-complete rather than a fragment of a family, and a truthful small group beats a nominal merge.
 - The `scaffold/` folders diverge from their npm names until the deferred renames land — the one transitional asymmetry, carried by three explicit `paths` entries in `tsconfig.base.json` and resolved by the FIXME renames.
 - What this gave up: nothing functional — the change is navigational. Muscle memory and external links to old GitHub paths break, which is acceptable pre-release with no external consumers.
diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
index 1d7d79e0cf..68903ff1fa 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md
@@ -29,10 +29,10 @@ Status: implemented
 | `guard/` | repeat-tool-guard、timeout-policy | `guard/` + `timeout/` |
 | `self-modification/` | tool-cordis | `cordis/` |
 
-- **`session/`** 是持久会话数据平面：持久化 seam 连同其各后端与检查点策略、从该日志折叠（fold）出全量值对外供值的投影、日志兜底的标题，以及 OTel 上报。标题折叠本身就是读取侧的承重构件（`session-query` 对 `dsh-session-title` 声明对等依赖），所以标题属于数据平面，而非某个「派生服务」附属区。用这个朴素的名字是有意为之（评审意见：名字要像人起的）；旁边的 `core/session` 包仍是常驻内存的实时服务，本组则是围绕它的持久家族。`session-query/` 保持独立成组：这个读取／工具面自带模型工具和 SQLite FTS 后端，其消费不依赖持久化内部实现。吸收 `telemetry/` 之后，与 `dsh-telemetry` 的组名冲突就此终结。
+- **`session/`** 是持久会话数据平面：持久化 seam 连同其各后端与检查点策略、从该日志折叠（fold）出全量值对外供值的投影、日志兜底的标题，以及 OTel 上报。标题折叠本身就是读取侧的承重构件（`session-query` 对 `dsh-session-title` 声明对等依赖），所以标题属于数据平面，而非某个「派生服务」附属区。用这个朴素的名字是有意为之（名字要像人起的）；旁边的 `core/session` 包仍是常驻内存的实时服务，本组则是围绕它的持久家族。`session-query/` 保持独立成组：这个读取／工具面自带模型工具和 SQLite FTS 后端，其消费不依赖持久化内部实现。吸收 `telemetry/` 之后，与 `dsh-telemetry` 的组名冲突就此终结。
 - **`interaction/`** 是人机协作平面加上应答它的终端通道：提问／批准 seam、权限预设、面向模型的 `ask_user_question` 工具、人类命令注册表（`plan-mode` 与 `command-goal` 已经把 `commands` 和各交互 seam 放在一起消费），以及 `tui`——这个交互通道是该平面最重的提供方与消费方（对 `commands` 与 `user-interaction` 均有对等依赖边），而一个单包 `tui/` 组会把一个顶层名字花在一个插件上。
 - **`boot/`** 是角色完备的单包组：不归属任何通道也不归属任何组装的共享 bin boot 胶水（被 `apps/cli`、`scaffold/` 的启动器和 `examples/` 各演示 bin 消费）。
-- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即原先的 `ui/jsonrpc`），以及启动器侧 telemetry。评审中从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致；在推迟的改名落地之前，受影响的三个 npm 名在 `tsconfig.base.json` 里于组通配符旁显式映射。
+- **`scaffold/`** 是开发者工具家族：项目 helper、启动器、初始化器、连同两端的通信协议（`server` 即原先的 `ui/jsonrpc`），以及启动器侧 telemetry。从 `sdk/` 改名：整个 `packages/` 树本身就是 SDK，树里再放一个叫 `sdk/` 的组等于什么都没说；`scaffold/` 说出了「创建／启动／驱动项目」这一实际角色。目录去掉遗留的 `sdk-` 前缀（`protocol`、`client`、`server`），与 `client/`/`host/` 的角色命名风格一致；在推迟的改名落地之前，受影响的三个 npm 名在 `tsconfig.base.json` 里于组通配符旁显式映射。
 - **`guard/`** 保留其文档记载的角色（循环卫生守卫），并新纳入强制执行工具调用超时的包；那个与 `util/timeout` 撞名的单包组 `timeout/` 随之解散。
 - **`self-modification/`** 把 `cordis/` 遮蔽掉的角色说了出来：它是 agent（智能体）检查并挂载自身实时运行时中插件所用的工具集，也是未来自我修改类包的落点。
 
@@ -54,11 +54,11 @@ Status: implemented
 
 ## What the move touched
 
-移动以 `git mv` 提交落地，每个区域一个提交（会话折叠；`ui/` 解散加 `scaffold/`；`guard/` 合并加 `self-modification/`），评审由重命名检测承载。组移动触及了：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文与门禁脚本中以仓库根为基准的 `packages/...` 引用。其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都由验收门禁的响亮失败机械地找了出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
+移动以纯 `git mv` 形式落地，历史由重命名检测承载。组移动触及了：被移动包的 `tsconfig.json` 相对 `references` 及每个依赖方的对应条目（含 `apps/cli` 的 project references）；tsconfig 聚合与路径映射；各组 README（五组新的双语三文件配对、被解散组的 README 删除、[packages/README.md](../../../../packages/README.md) 的层级结构表、根 `AGENTS.md` 的布局图）；重新生成的产物（`docs/module-graph.md`、内嵌路径的目录、锁文件的 importer 键）；以及散文与门禁脚本中以仓库根为基准的 `packages/...` 引用。其余每一处组路径引用（workspace 配置、测试 glob、lint 键）都由验收门禁的响亮失败机械地找了出来——这正是本仓库自己的「配置错误必须响亮失败」规则。
 
-组移动未触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包。每条 FIXME 都与创造其上下文的那次移动落在同一个提交。
+组移动未触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包。
 
-`client/` 与 `host/` 不在本次范围内，保持不变。`experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策；两者唯一的交集是 packages/README.md 表格里一次很小的合并。
+`client/` 与 `host/` 不在本次范围内，保持不变。`experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策。
 
 ## Alternatives considered
 
@@ -68,21 +68,21 @@ Status: implemented
 
 **一轮全量 npm 重命名**（每个包都改为 `dsh-<group>-<pkg>`）。不予采纳：npm 包名是扁平的，加组前缀只会在 import、配置和 fixture 之间制造改动，却换不来任何消歧收益；用 FIXME 跟踪的定点改名足以覆盖真正的撞名。
 
-**在重组内部一并完成那五个改名。** 评审中否决：改名会成倍放大开放 PR 的冲突，并破坏纯移动的评审属性。FIXME 标记让这些改名保持为可见的发布阻塞项，留待以小型后续 PR 逐一解决。
+**在重组内部一并完成那五个改名。** 不予采纳：改名会成倍放大开放 PR 的冲突，并破坏纯移动的评审属性。FIXME 标记让这些改名保持为可见的发布阻塞项，留待以小型后续 PR 逐一解决。
 
 **会话两分法**（`session-core/` + `session-utils/`）。不予采纳：query 放哪一侧都不干净，而且 `session-core` 容易与 `core/session` 混淆（后者是 `dsh-session`，常驻内存的实时服务，留在 `core/` 不动）。
 
-**会话三分法**（`session-store/` + `session-query/` + `session-utils/`），即本 RFC 的初稿。评审中否决：`session-utils/` 是靠否定条件圈出来的附属区（「派生的、没有承重方依赖」）——正是指导准则禁止的大杂烩形态，而且事实层面也站不住（`session-query` 对 `dsh-session-title` 声明对等依赖）。杜撰的复合名也读起来不像人起的；一个朴素的 `session/` 组说的就是人会说的话。query 在两版草稿中都保持独立：它是被独立消费的读取面，自带自己的工具包与后端。
+**会话三分法**（`session-store/` + `session-query/` + `session-utils/`）。不予采纳：`session-utils/` 是靠否定条件圈出来的附属区（「派生的、没有承重方依赖」）——正是指导准则禁止的大杂烩形态，而且事实层面也站不住（`session-query` 对 `dsh-session-title` 声明对等依赖）。杜撰的复合名也读起来不像人起的；一个朴素的 `session/` 组说的就是人会说的话。query 无论如何都保持独立：它是被独立消费的读取面，自带自己的工具包与后端。
 
 **把 `ui/` 重组为单一 `channels/` 组**（tui + jsonrpc + acp + 交互 seam + boot）。不予采纳：不过是换个名字的同一个大杂烩——这些包服务于四个平面，`jsonrpc` 的实测聚类归属是 SDK 通信栈，而 `acp/` 是自动化传输通道，不是人类通道。
 
-**独立的单包 `tui/` 组**，即本 RFC 的初稿。评审中否决：`tui` 是交互平面最重的提供方／消费方（对 `commands`、`user-interaction` 有对等依赖边），把一个顶层名字花在一个插件上只添组不添信息；它折入 `interaction/`。
+**独立的单包 `tui/` 组。** 不予采纳：`tui` 是交互平面最重的提供方／消费方（对 `commands`、`user-interaction` 有对等依赖边），把一个顶层名字花在一个插件上只添组不添信息；它折入 `interaction/`。
 
-**保留组名 `sdk/`。** 评审中否决：整个 `packages/` 树本身就是 SDK，树里的 `sdk/` 组毫无区分度——与 `cordis/` 同病。`scaffold/` 说出了实际角色（从外部创建、启动、驱动项目）。
+**保留组名 `sdk/`。** 不予采纳：整个 `packages/` 树本身就是 SDK，树里的 `sdk/` 组毫无区分度——与 `cordis/` 同病。`scaffold/` 说出了实际角色（从外部创建、启动、驱动项目）。
 
-**把 `app-boot` 挪到 `apps/`**（评审提问）。不予采纳：`apps/` 是包层之上的组装层，而 `dsh-app-boot` 是被包层代码 import 的库（`scaffold/scripts` 的启动器对它声明对等依赖）——放进 `apps/` 会颠倒层级，并把一个 workspace 库放到 `packages/*/*` 构建 glob 之外。它仍是一个包；`boot/` 是它角色完备的家。
+**把 `app-boot` 挪到 `apps/`。** 不予采纳：`apps/` 是包层之上的组装层，而 `dsh-app-boot` 是被包层代码 import 的库（`scaffold/scripts` 的启动器对它声明对等依赖）——放进 `apps/` 会颠倒层级，并把一个 workspace 库放到 `packages/*/*` 构建 glob 之外。它仍是一个包；`boot/` 是它角色完备的家。
 
-**把 `tool-cordis` 挪进 `core/`。** 不予采纳：自我修改是独立的产品 seam，预期还会生长；主干保持精简。该组最初命名为 `self-evolve/`；评审定为更朴素的 `self-modification/`。
+**把 `tool-cordis` 挪进 `core/`。** 不予采纳：自我修改是独立的产品 seam，预期还会生长；主干保持精简。该组最初命名为 `self-evolve/`；名字最终定为更朴素的 `self-modification/`。
 
 **把 `context/` 改名为 `request-context/`。** 不予采纳：在这棵树里，该组就地看并无歧义；这份改动开销并不值得。
 
@@ -90,7 +90,7 @@ Status: implemented
 
 - 目录树与映射表一致：重组的六个组恰好持有所列成员；`ui/`、`sdk/`、`telemetry/`、`timeout/`、`cordis/`、`session-persistence/`、`session-projection/`、`session-title/` 这些组不复存在；其余每个组的内容不变。workspace 的包名集合在前后完全相同（npm 改名为零），五条 FIXME 标记钉住推迟的改名。日后若某条 FIXME 被证明不对，必须连同理由显式移除，绝不允许无声消失。
 - 结果由以下检查钉住：`pnpm run typecheck`、每个被移动组的单元测试套件、`verify-package-paths`、`verify-md-links` 与全语料翻译配对在移动后的树上全部通过；`vitest.snapshot.config.ts` 中按组划定的测试 glob 随移动一并改写，套件收集到与移动前相同的测试文件（glob 匹配为空会无声地丢失覆盖）。
-- 每个触碰被移动文件的开放 PR 都跨过这次移动做一次变基；PR 正文中的映射表与重命名检测可机械化解决大多数改动块。
+- 每个触碰被移动文件的开放 PR 都跨过这次移动做一次变基；重命名检测可机械化解决大多数改动块。
 - 单包组依然存在（`boot/`、`self-modification/`，以及 `acp/` 等既有单包组）。这是有意接受的：每个都是角色完备的整体而非某个家族的碎片，一个名实相符的小组胜过一次徒有其名的合并。
 - 在推迟的改名落地之前，`scaffold/` 的目录名与其 npm 名并不一致——这是唯一的过渡性不对称，由 `tsconfig.base.json` 里三条显式 `paths` 映射承载，并由 FIXME 改名最终消除。
 - **这次变更放弃了什么：** 功能上一无所失——变更只关乎导航。肌肉记忆和指向旧 GitHub 路径的外部链接会失效；在 pre-release、尚无外部消费者的前提下，这可以接受。
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
index ca03afde36..b5a5fdf3d4 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.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 .agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
-2026-07-29-projected-token-usage-and-request-context.md: 1e2c5ff067928620dee3d0937c247bec245e34f2
-2026-07-29-projected-token-usage-and-request-context.zh.md: 176e4929ac47dd2e83bf8361501b57058a3021f2
+2026-07-29-projected-token-usage-and-request-context.md: 441a13337c76fce4ab2525ceed364361c5989f73
+2026-07-29-projected-token-usage-and-request-context.zh.md: dab0b3a57ffe665b4c5b0a53ad370a7388c7f78c
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
index 1e2c5ff067..441a13337c 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md
@@ -32,11 +32,11 @@ The Web `StatsLine` reads both through the standard `useProjection` seat. Window
 
 This was accepted deliberately. An occupancy percentage is a user-facing reference figure: nothing in the harness makes decisions from it, and compaction reads `measure()` directly instead. The TUI status line has always computed occupancy this way, dividing a `measure()` total by a capacity resolved separately for the selected model — so an atomic variant here would have been the outlier, not the norm.
 
-Reviewers should not treat the non-atomicity as a defect awaiting a fix. A consumer that genuinely needs an exact same-boundary figure should call `ctx.tokenMeter.measure()` at its own request boundary, where both values are available together, rather than read this projection.
+The non-atomicity is deliberate, not a defect. A consumer that genuinely needs an exact same-boundary figure should call `ctx.tokenMeter.measure()` at its own request boundary, where both values are available together, rather than read this projection.
 
 ## Alternatives considered
 
-**An atomic request-boundary snapshot delivered as a transient mux frame (implemented, then rejected).** An earlier revision of this branch emitted `session/model-request`: one non-replayable frame carrying `contextTokens` and `contextWindow` measured at the same `agent/model-request` boundary. Being the only non-replayable class on the mux stream is what broke it. Host and mux are independent SSE streams with no cross-stream ordering, so a request emitted before a removal could arrive after `host/session-removed` and revive a dead session's telemetry, while a legitimate request for a new lifecycle reusing the same id could be fenced by a late removal. `session/subscribed` is not lifecycle proof — it says a queue began subscribing to an id, not that a new in-memory session replaced an older one — and `lastSeq` is a durable watermark two lifecycles can share. A correct fix required a monotonic lifecycle generation on the frame, on subscription, and on removal, plus a client watermark comparison.
+**An atomic request-boundary snapshot delivered as a transient mux frame (implemented, then rejected).** An earlier revision emitted `session/model-request`: one non-replayable frame carrying `contextTokens` and `contextWindow` measured at the same `agent/model-request` boundary. Being the only non-replayable class on the mux stream is what broke it. Host and mux are independent SSE streams with no cross-stream ordering, so a request emitted before a removal could arrive after `host/session-removed` and revive a dead session's telemetry, while a legitimate request for a new lifecycle reusing the same id could be fenced by a late removal. `session/subscribed` is not lifecycle proof — it says a queue began subscribing to an id, not that a new in-memory session replaced an older one — and `lastSeq` is a durable watermark two lifecycles can share. A correct fix required a monotonic lifecycle generation on the frame, on subscription, and on removal, plus a client watermark comparison.
 
 That cost bought a worse display: occupancy went blank after every reconnect and never moved while a conversation grew. It also made ApiProxy a measurement site calling the O(surface) `measure()` on every request, and expressed reconnect state through a synthetic `cancelled` open error the UI had to special-case.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
index 176e4929ac..dab0b3a57f 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.zh.md
@@ -32,11 +32,11 @@ Web `StatsLine` 通过标准 `useProjection` 席位读取两者。窗口内节
 
 这是刻意接受的结果。占用率百分比是面向用户的参考数字：harness 中没有任何环节依据它做决策，压缩改为直接读取 `measure()`。TUI 状态行一直以这种方式计算占用率，即用 `measure()` 总量除以为所选模型单独解析出的容量；因此在这里做成原子版本才是异类，而不是常态。
 
-评审人不应把这种非原子性当作待修的缺陷。确实需要同一边界精确数字的消费方，应在自己的请求边界调用 `ctx.tokenMeter.measure()`，那里两个值同时可得，而不是读取该投影。
+这种非原子性是有意为之，不是缺陷。确实需要同一边界精确数字的消费方，应在自己的请求边界调用 `ctx.tokenMeter.measure()`，那里两个值同时可得，而不是读取该投影。
 
 ## 备选方案
 
-**以临时 mux 帧交付请求边界上的原子快照（已实现，随后否决）。** 本分支较早的一个修订版会发出 `session/model-request`：一个不可回放的帧，携带在同一个 `agent/model-request` 边界测得的 `contextTokens` 与 `contextWindow`。真正让它失效的，是它成了 mux 流上唯一的不可回放类别。Host 流与 mux 流是两条独立的 SSE（Server-Sent Events）流，彼此之间没有顺序保证：在移除之前发出的请求可能在 `host/session-removed` 之后才到达，让一个已死会话的遥测数据复活；而复用同一 id 的新生命周期的合法请求，又可能被一条迟到的移除拦下。`session/subscribed` 不能证明生命周期：它只说明某个队列开始订阅某个 id，而不说明新的内存会话替换了较早的会话；`lastSeq` 则是两个生命周期可以共用的持久水位线。正确的修法需要在帧上、订阅上和移除上都带一个单调递增的生命周期代次，再加上一次客户端水位线比较。
+**以临时 mux 帧交付请求边界上的原子快照（已实现，随后否决）。** 较早的一个修订版会发出 `session/model-request`：一个不可回放的帧，携带在同一个 `agent/model-request` 边界测得的 `contextTokens` 与 `contextWindow`。真正让它失效的，是它成了 mux 流上唯一的不可回放类别。Host 流与 mux 流是两条独立的 SSE（Server-Sent Events）流，彼此之间没有顺序保证：在移除之前发出的请求可能在 `host/session-removed` 之后才到达，让一个已死会话的遥测数据复活；而复用同一 id 的新生命周期的合法请求，又可能被一条迟到的移除拦下。`session/subscribed` 不能证明生命周期：它只说明某个队列开始订阅某个 id，而不说明新的内存会话替换了较早的会话；`lastSeq` 则是两个生命周期可以共用的持久水位线。正确的修法需要在帧上、订阅上和移除上都带一个单调递增的生命周期代次，再加上一次客户端水位线比较。
 
 这份代价换来的是更差的显示：占用率在每次重连后变为空白，而且会话增长期间从不移动。它还把 ApiProxy 变成一个测量点，每个请求都要调用 O(surface) 的 `measure()`，并通过一个 UI 必须特殊处理的、连接打开时的合成 `cancelled` 错误来表达重连状态。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
index 3111ab36ae..23bb4a7daa 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.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 .agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
-2026-07-29-request-level-llm-config-credentials.md: 238400ea41f25a716729d1721c113645c2c8ba72
-2026-07-29-request-level-llm-config-credentials.zh.md: 67a608293923291450ec3c226ac95ab4ff9f4af4
+2026-07-29-request-level-llm-config-credentials.md: f797d54f3f0507dce4f60492e4afd05a3bc60ba6
+2026-07-29-request-level-llm-config-credentials.zh.md: f09a6c72a27f06d3a76cf91653ec026d5a0f8643
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
index 238400ea41..f797d54f3f 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-29-request-level-llm-config-credentials.zh.md)
 
-> Scope: the first production consumers of `ctx.settings` (the two LLM adapter plugins), the new `packages/credentials/` capability family, and the `packages/util/atomic-write` extraction. The follow-up wire surface (`settings.*`/`credentials.*` RPC, secret-role masking, the web settings form) is a separate PR and not part of this note's shipped scope.
+> Scope: the first production consumers of `ctx.settings` (the two LLM adapter plugins), the new `packages/credentials/` capability family, and the `packages/util/atomic-write` extraction. The follow-up wire surface (`settings.*`/`credentials.*` RPC, secret-role masking, the web settings form) is separate work outside this note's scope.
 
 ## Problem
 
@@ -26,4 +26,4 @@ The [settings seam](2026-07-28-user-settings-seam.md) shipped without a producti
 
 ## Consequences
 
-Onboarding is restart-free end to end (pinned by the `missing-credential` headless snapshot and the credentials-rotation composition tests): boot keyless, browse the catalog, store the key, prompt again. The demos mount `settings-local` + `credentials-local` by default and inline no `!!js` key plumbing. `runLoaderSmoke` gained `expectedExitCode` so a designed failure surface can be pinned rather than masked. Deferred: the wire/UI surface must redact `role('secret')` fields before any RPC exposes `describe()`, settings-layer arrays still replace wholesale (the deepseek `models` list), and a settings section cannot remove a composition-provided pi-ai route (only override or extend). Review of this seam later reworked where the store lives and who may read it, made one request resolve one configuration generation, and made route replacement atomic ([credential boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md)).
+Onboarding is restart-free end to end (pinned by the `missing-credential` headless snapshot and the credentials-rotation composition tests): boot keyless, browse the catalog, store the key, prompt again. The demos mount `settings-local` + `credentials-local` by default and inline no `!!js` key plumbing. `runLoaderSmoke` gained `expectedExitCode` so a designed failure surface can be pinned rather than masked. Deferred: the wire/UI surface must redact `role('secret')` fields before any RPC exposes `describe()`, settings-layer arrays still replace wholesale (the deepseek `models` list), and a settings section cannot remove a composition-provided pi-ai route (only override or extend). A later decision reworked where the store lives and who may read it, made one request resolve one configuration generation, and made route replacement atomic ([credential boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md)).
diff --git a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
index 67a6082939..f09a6c72a2 100644
--- a/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-29-request-level-llm-config-credentials.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-29-request-level-llm-config-credentials.md) | 中文
 
-> 范围：`ctx.settings` 的第一批生产消费方（两个 LLM 适配器插件）、新增的 `packages/credentials/` 能力族，以及 `packages/util/atomic-write` 的抽取。后续的 wire 面（`settings.*`/`credentials.*` RPC、secret 角色脱敏、web 设置表单）是单独的 PR，不在本 note 已交付范围内。
+> 范围：`ctx.settings` 的第一批生产消费方（两个 LLM 适配器插件）、新增的 `packages/credentials/` 能力族，以及 `packages/util/atomic-write` 的抽取。后续的 wire 面（`settings.*`/`credentials.*` RPC、secret 角色脱敏、web 设置表单）是另行开展的工作，不在本 note 范围内。
 
 ## 问题
 
@@ -26,4 +26,4 @@ Status: implemented
 
 ## 后果
 
-上手流程端到端免重启（由 `missing-credential` headless 快照与凭据轮换组合测试固定）：无密钥启动、浏览 catalog、存入密钥、再次发起提示。demo 默认挂载 `settings-local` + `credentials-local`，不再内联任何 `!!js` 密钥接线。`runLoaderSmoke` 新增 `expectedExitCode`，使按设计出现的失败面可以被固定而非被掩盖。延后事项：wire/UI 面在任何 RPC 暴露 `describe()` 之前必须对 `role('secret')` 字段脱敏；settings 层的数组仍整体替换（deepseek 的 `models` 列表）；settings 分节无法移除组合提供的 pi-ai 路由（只能覆盖或扩展）。对该 seam 的评审随后改造了存储的所在位置与谁可以读取它，让一个请求解析出一个配置世代，并使路由替换成为原子操作（[credential boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md)）。
+上手流程端到端免重启（由 `missing-credential` headless 快照与凭据轮换组合测试固定）：无密钥启动、浏览 catalog、存入密钥、再次发起提示。demo 默认挂载 `settings-local` + `credentials-local`，不再内联任何 `!!js` 密钥接线。`runLoaderSmoke` 新增 `expectedExitCode`，使按设计出现的失败面可以被固定而非被掩盖。延后事项：wire/UI 面在任何 RPC 暴露 `describe()` 之前必须对 `role('secret')` 字段脱敏；settings 层的数组仍整体替换（deepseek 的 `models` 列表）；settings 分节无法移除组合提供的 pi-ai 路由（只能覆盖或扩展）。后来的一项决策改造了存储的所在位置与谁可以读取它，让一个请求解析出一个配置世代，并使路由替换成为原子操作（[credential boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md)）。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.i18n.yaml
index e062681d87..ffa3375b74 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.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 .agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md
-2026-07-30-config-plane-boundaries.md: 8a29dcc934126d6e3dfa9c0a6a308ef006017a5a
-2026-07-30-config-plane-boundaries.zh.md: 61edb9b7d8396e0453dcca0042cd0ee27551b216
+2026-07-30-config-plane-boundaries.md: 383163d5315ce0fcb39d06ac8b5f7762758fa9b2
+2026-07-30-config-plane-boundaries.zh.md: 0a412d5b8517c98accd056b690129f4e485f0e13
diff --git a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md
index 8a29dcc934..383163d531 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-30-config-plane-boundaries.zh.md)
 
-> Scope: the review round over the [web configuration plane](2026-07-30-web-config-plane.md) — which namespaces reach the wire, which callers reach them, and how an editor holding a partial, possibly stale view writes without destroying what it cannot see.
+> Scope: boundary hardening of the [web configuration plane](2026-07-30-web-config-plane.md) — which namespaces reach the wire, which callers reach them, and how an editor holding a partial, possibly stale view writes without destroying what it cannot see.
 
 ## Problem
 
@@ -34,7 +34,7 @@ Three smaller defects sat beside them. `llm/adapters-updated` documented contain
 - **Opt-in metadata at `settings.register()`** — the most honest semantics (the namespace's owner declares its own exposure), and the largest change: the seam's public interface, both LLM plugins, and their docs. Recorded as the shape to adopt if a non-LLM namespace ever needs the plane.
 - **Distinguishing "unregistered" from "registered but unexposed"** — better diagnostics, and a namespace-enumeration oracle. The uniform answer is deliberate.
 - **Detecting conflicts by diffing instead of a revision** — comparing the submitted base against storage would work for whole-section writes, but the editor holds a REDACTED section: it cannot produce a comparable base, which is the same reason it cannot safely `replace`. A counter needs neither.
-- **Fixing the redaction gaps in this round** — `redactSecrets` walks only `object`/`dict`/`array`, so a secret behind a union, intersection, or transform is returned verbatim with an empty `secrets` list; `schema.toJSON()` carries a secret field's `.default(...)`; write-rejection messages return schema text that may quote the input; the client rehydrates the envelope through schemastery's `new Function`; and pi-ai's plain-string `headers` dict can legitimately hold `Authorization`. All confirmed, all deliberately left for a fail-closed `describeForWire()` that refuses a schema it cannot prove safe. They are recorded as `TODO(settings-wire-redaction)` and in the owning READMEs' Known Limitations rather than half-fixed here.
+- **Fixing the redaction gaps here** — `redactSecrets` walks only `object`/`dict`/`array`, so a secret behind a union, intersection, or transform is returned verbatim with an empty `secrets` list; `schema.toJSON()` carries a secret field's `.default(...)`; write-rejection messages return schema text that may quote the input; the client rehydrates the envelope through schemastery's `new Function`; and pi-ai's plain-string `headers` dict can legitimately hold `Authorization`. All real, all deliberately left for a fail-closed `describeForWire()` that refuses a schema it cannot prove safe. They are recorded as `TODO(settings-wire-redaction)` and in the owning READMEs' Known Limitations rather than half-fixed here.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md
index 61edb9b7d8..0a412d5b85 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-30-config-plane-boundaries.md) | 中文
 
-> 范围：针对 [Web 配置面](2026-07-30-web-config-plane.md)的评审轮——哪些 namespace 能抵达协议、哪些调用方能抵达它们，以及一个只持有局部、且可能过期视图的编辑器该如何写入，才不会毁掉它看不见的东西。
+> 范围：对 [Web 配置面](2026-07-30-web-config-plane.md)的边界加固——哪些 namespace 能抵达协议、哪些调用方能抵达它们，以及一个只持有局部、且可能过期视图的编辑器该如何写入，才不会毁掉它看不见的东西。
 
 ## 问题
 
@@ -34,7 +34,7 @@ Status: implemented
 - **在 `settings.register()` 处 opt-in metadata**——语义最正（由 namespace 的属主自行声明其暴露与否），改动也最大：seam 的公共接口、两个 LLM 插件，以及它们的文档。记录为：一旦某个非 LLM 的 namespace 确实需要这个面，就采用这个形状。
 - **区分"未注册"与"已注册但未暴露"**——诊断更好，同时也是一台 namespace 枚举预言机。统一答复是刻意为之。
 - **用 diff 而非 revision 来检测冲突**——对整分节写入而言，拿提交时的基线与存储比对是可行的，但编辑器持有的是**脱敏后**的分节：它给不出可比对的基线，这与它不能安全地 `replace` 是同一个原因。计数器两者都不需要。
-- **本轮就修掉脱敏的缺口**——`redactSecrets` 只遍历 `object`/`dict`/`array`，因此藏在 union、intersection 或 transform 之后的机密会被原样返回，且 `secrets` 列表为空；`schema.toJSON()` 会带上 secret 字段的 `.default(...)`；写入拒绝的消息返回的是可能引用了输入的 schema 文本；客户端通过 schemastery 的 `new Function` 重建信封；而 pi-ai 那个纯字符串的 `headers` 字典完全可以合法地放下 `Authorization`。全部经确认属实，也全部刻意留给一个 fail-closed 的 `describeForWire()`——它会拒绝自己无法证明安全的 schema。它们被记录为 `TODO(settings-wire-redaction)` 以及各属主 README 的 Known Limitations，而不是在这里做一半。
+- **在这里就修掉脱敏的缺口**——`redactSecrets` 只遍历 `object`/`dict`/`array`，因此藏在 union、intersection 或 transform 之后的机密会被原样返回，且 `secrets` 列表为空；`schema.toJSON()` 会带上 secret 字段的 `.default(...)`；写入拒绝的消息返回的是可能引用了输入的 schema 文本；客户端通过 schemastery 的 `new Function` 重建信封；而 pi-ai 那个纯字符串的 `headers` 字典完全可以合法地放下 `Authorization`。全部真实存在，也全部刻意留给一个 fail-closed 的 `describeForWire()`——它会拒绝自己无法证明安全的 schema。它们被记录为 `TODO(settings-wire-redaction)` 以及各属主 README 的 Known Limitations，而不是在这里做一半。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index 3a6b661601..5955dd282f 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.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 .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
-2026-07-30-credential-boundaries-and-atomic-registration.md: 300280e6d4f8be2c0519efcb7ecfc82028d05445
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 2b66c543bdd80612bee65a6e6e4a78ab565d5188
+2026-07-30-credential-boundaries-and-atomic-registration.md: e21b6d0ea5da30b77ab26b750e2294220646a20e
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 6552db1932ca663c6228843cd62b5cc0f3811f24
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
index 300280e6d4..e21b6d0ea5 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
@@ -4,11 +4,11 @@ Status: implemented
 
 English | [中文](2026-07-30-credential-boundaries-and-atomic-registration.zh.md)
 
-> Scope: the third review round over the [request-level LLM configuration boundary](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this round applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
+> Scope: boundary hardening of the [request-level LLM configuration boundary](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this note applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
 
 ## Problem
 
-Review found the credential path leaking across boundaries it had drawn. The shipped surfaces hoisted `$DSH_HOME/.env` into `process.env` before cordis booted, so on the next run `credentials-local` classified every key it had stored itself as a read-only ambient launch override: `describe()` reported `source: 'env'` with `writable: false`, `set`/`unset` rejected as shadowed, and a key stored from the web page or TUI became unrotatable and undeletable while the adapter kept using the value captured at launch. The store's own write path repeated the settings-local defects that same review round fixed (two independent chains, whole-file render from a stale cache), plus editor bugs of its own: a physical line inside another key's quoted multi-line value read as an assignment, CRLF endings degraded to LF, a multi-line entry reported `writable: true` while `set` always threw, and `credentials/updated` was emitted bare after the commit, so one broken observer made a durable write look failed. On the read side, the file's `0600` mode stops other OS users but not the model, whose bash and filesystem tools run as the same user.
+The credential path leaked across boundaries it had drawn. The shipped surfaces hoisted `$DSH_HOME/.env` into `process.env` before cordis booted, so on the next run `credentials-local` classified every key it had stored itself as a read-only ambient launch override: `describe()` reported `source: 'env'` with `writable: false`, `set`/`unset` rejected as shadowed, and a key stored from the web page or TUI became unrotatable and undeletable while the adapter kept using the value captured at launch. The store's own write path repeated the settings-local defects the settings write-path note fixes (two independent chains, whole-file render from a stale cache), plus editor bugs of its own: a physical line inside another key's quoted multi-line value read as an assignment, CRLF endings degraded to LF, a multi-line entry reported `writable: true` while `set` always threw, and `credentials/updated` was emitted bare after the commit, so one broken observer made a durable write look failed. On the read side, the file's `0600` mode stops other OS users but not the model, whose bash and filesystem tools run as the same user.
 
 Two request-path defects sat beside them. DeepSeek resolved connection and credential facts independently, so a settings generation the resolver rejected could still pair its credential choice with the previous generation's endpoint. pi-ai handed the SDK `undefined` when a configured `apiKeyEnv` resolved to nothing, letting pi-ai's own environment discovery authenticate with an unrelated provider key — another tenant, silently billed. And its route swap disposed the old registration before creating the new one: a route another adapter owned dropped every existing route, after which the facts cache could equal the registry's, so restoring the working configuration never re-applied.
 
@@ -28,8 +28,8 @@ Two request-path defects sat beside them. DeepSeek resolved connection and crede
 
 - **A sandbox read-denial naming `$DSH_HOME/.env`** — implemented as a `readDenyPaths` policy field (a trailing SBPL `deny file-read* file-write*`, a `/dev/null` bwrap bind) and withdrawn on its own evidence. bwrap must create that bind's mount point inside a tree its profile has already made read-only, so it refuses the entire confinement whenever the parent directory is absent — every host that has not stored a credential yet, including a fresh install; Landlock cannot subtract from its own `/` read grant, so every confined call would report `partial` for a file it never hid. A protection that breaks confinement where it works and misreports it where it does not is worse than a documented absence. Denying the whole harness home was rejected earlier for a separate reason: it also covers `sessions/`, and `DSH_SESSION_JSONL` is a documented model-visible capability.
 - **Removing `DSH_HOME` from the model's bash environment** — considered as defense in depth and rejected as theater with a real cost: the default home is a documented convention the agent can reconstruct, while the variable is how legitimate tooling finds harness state. There is no boundary here for it to complement; hiding the pointer would only make the absence harder to see.
-- **Shipping the OS-keychain provider in this round** — it is the only design where the model's processes genuinely cannot read the secret, and it is a sibling package with three platform backends. Sizing it against the rest of this review round would have delayed every other fix; it is recorded as the deferred answer, not as a maybe.
-- **A `replaceRegistration(previous, next)` service method** — the review's shape, but it makes the caller carry the previous handle and lets it pass a mismatched one. Hanging `replace` on the registration handle makes ownership structural: only the registration that holds routes can replace them.
+- **Shipping the OS-keychain provider now** — it is the only design where the model's processes genuinely cannot read the secret, and it is a sibling package with three platform backends. Sizing it against the rest of these fixes would have delayed every other one; it is recorded as the deferred answer, not as a maybe.
+- **A `replaceRegistration(previous, next)` service method** — rejected: it makes the caller carry the previous handle and lets it pass a mismatched one. Hanging `replace` on the registration handle makes ownership structural: only the registration that holds routes can replace them.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index 2b66c543bd..6552db1932 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -4,13 +4,13 @@ Status: implemented
 
 [English](2026-07-30-credential-boundaries-and-atomic-registration.md) | 中文
 
-> 范围：对[请求级 LLM（大语言模型）配置边界](2026-07-29-request-level-llm-config-credentials.md)的第三轮评审——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：本轮把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
+> 范围：对[请求级 LLM（大语言模型）配置边界](2026-07-29-request-level-llm-config-credentials.md)的边界加固——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：它把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
 
 ## 问题
 
-评审发现，凭据路径正在越过它自己划下的边界泄漏。已交付的各个面在 Cordis 启动之前就把 `$DSH_HOME/.env` 提升进了 `process.env`，于是下一次运行时，`credentials-local` 会把它自己存下的每个键都判成来自环境的只读启动覆盖：`describe()` 报告 `source: 'env'` 且 `writable: false`，`set`/`unset` 以被遮蔽为由拒绝，从 web 页面或 TUI 存入的密钥既无法轮换也无法删除，而适配器还在继续使用启动时捕获的那个值。
+凭据路径越过它自己划下的边界发生了泄漏。已交付的各个面在 Cordis 启动之前就把 `$DSH_HOME/.env` 提升进了 `process.env`，于是下一次运行时，`credentials-local` 会把它自己存下的每个键都判成来自环境的只读启动覆盖：`describe()` 报告 `source: 'env'` 且 `writable: false`，`set`/`unset` 以被遮蔽为由拒绝，从 web 页面或 TUI 存入的密钥既无法轮换也无法删除，而适配器还在继续使用启动时捕获的那个值。
 
-存储自身的写路径重演了同一轮评审在 settings-local 修掉的那些缺陷（两条相互独立的链、从陈旧缓存渲染整份文件），还叠加了编辑器自己的缺陷：另一个键的带引号多行值内部的一条物理行会被读成赋值，CRLF 行尾会退化成 LF，多行条目报告 `writable: true` 而 `set` 总是抛错，`credentials/updated` 又在提交之后裸发，于是一个出错的观察者就能让一次已经落盘的写入看起来失败。
+存储自身的写路径重演了 settings 写路径 note 在 settings-local 修掉的那些缺陷（两条相互独立的链、从陈旧缓存渲染整份文件），还叠加了编辑器自己的缺陷：另一个键的带引号多行值内部的一条物理行会被读成赋值，CRLF 行尾会退化成 LF，多行条目报告 `writable: true` 而 `set` 总是抛错，`credentials/updated` 又在提交之后裸发，于是一个出错的观察者就能让一次已经落盘的写入看起来失败。
 
 在读取一侧，文件的 `0600` 权限挡得住其他 OS 用户，却挡不住模型：它的 bash 与文件系统工具就以同一个用户身份运行。
 
@@ -32,8 +32,8 @@ Status: implemented
 
 - **用沙箱点名拒读 `$DSH_HOME/.env`**——已按 `readDenyPaths` 策略字段实现过（末尾一条 SBPL `deny file-read* file-write*`、一条 `/dev/null` 的 bwrap bind），又被它自己的证据推翻。bwrap 必须在自己 profile 已经置为只读的目录树内部创建该 bind 的挂载点，因此只要父目录不存在，它就会拒绝整次约束——那是每一台还没有存过凭据的主机，包括全新安装；Landlock 无法从它自己对 `/` 的读取授权中减去任何东西，于是每一次受限调用都会为一个它其实从未藏起的文件报 `partial`。一项在生效之处破坏约束、在不生效之处误报的保护，比一条写明的「没有保护」更糟。至于拒掉整个 harness home，早先另有理由被否：它同时覆盖 `sessions/`，而 `DSH_SESSION_JSONL` 是一项成文的、模型可见的能力。
 - **把 `DSH_HOME` 从模型的 bash 环境中移除**——作为纵深防御考虑过，最终按「有真实代价的表演」不予采纳：默认 home 是 agent（智能体）能自行重建的成文约定，而这个变量正是正当工具链定位 harness 状态的途径。这里并不存在一条需要它来补强的边界，藏起指针只会让这份缺席更难被看见。
-- **本轮就交付 OS 钥匙串提供方**——只有这个设计能让模型的进程真正读不到机密，而它是一个带三种平台后端的兄弟包。把它与本轮评审的其余工作放在一起评估体量，会拖慢其他每一项修复；它被记录为那个延后的答案，而不是一个「也许」。
-- **做成 `replaceRegistration(previous, next)` 服务方法**——这是评审给出的形状，但它要求调用方自行携带上一个句柄，也允许它传入一个不匹配的句柄。把 `replace` 挂在注册句柄上，让归属关系变成结构性的：只有持有路由的那一项注册才能替换它们。
+- **现在就交付 OS 钥匙串提供方**——只有这个设计能让模型的进程真正读不到机密，而它是一个带三种平台后端的兄弟包。把它与其余这些修复放在一起评估体量，会拖慢其他每一项；它被记录为那个延后的答案，而不是一个「也许」。
+- **做成 `replaceRegistration(previous, next)` 服务方法**——不予采纳：它要求调用方自行携带上一个句柄，也允许它传入一个不匹配的句柄。把 `replace` 挂在注册句柄上，让归属关系变成结构性的：只有持有路由的那一项注册才能替换它们。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
index 0bb3092b67..de2b1f5fa4 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.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 .agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
-2026-07-30-session-end-seed-log-boundary.md: 26cd67ccbfdf5dfc62e44a53c877acf6d2fee34a
-2026-07-30-session-end-seed-log-boundary.zh.md: 70391ba8b629694cc83f1960ea3fdd94cd32f032
+2026-07-30-session-end-seed-log-boundary.md: 8f5c38023c29e6daca3c92d30e633e4d11a52a88
+2026-07-30-session-end-seed-log-boundary.zh.md: 39d1c39b1731f0122efcca0faefefd21e3222c54
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
index 26cd67ccbf..8f5c38023c 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.md
@@ -36,7 +36,7 @@ The predicate holds for a bracket *this* session inherited, not as a liveness si
 
 ## Alternatives considered
 
-**A boundary written by the persistence coordinator's cold-load path.** Built first as a `session/resumed` boundary and abandoned before merge. It covers no fork, which is the one case where the inherited bracket's owner may still be running. Because the marker was minted at load it also had to be a durable write on a read path, which spread cost across the seam: a revision bump on every cold load, a `commitRepair` batch on a balanced log with nothing to repair, a stored-time floor to keep the clamp monotonic, and a load that failed against a read-only store.
+**A boundary written by the persistence coordinator's cold-load path.** An earlier iteration wrote a `session/resumed` boundary; it lost because it covers no fork — the one case where the inherited bracket's owner may still be running — and because a marker minted at load had to be a durable write on a read path, which spread cost across the seam: a revision bump on every cold load, a `commitRepair` batch on a balanced log with nothing to repair, a stored-time floor to keep the clamp monotonic, and a load that failed against a read-only store.
 
 **A boundary appended at loop start.** The loop calls `resumeWith`, so it covers the resume paths, but it misses `fork()` and `adopt()` entirely, and the event would have to fire on `'startup'` — the source a fork child publishes — so `SessionStartSource` would stop discriminating. It also publishes the session before the marker is appended, so a `session/created` listener could observe a seeded log with no boundary.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
index 70391ba8b6..39d1c39b17 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-session-end-seed-log-boundary.zh.md
@@ -36,7 +36,7 @@ Status: implemented
 
 ## Alternatives considered
 
-**由持久化协调器的冷加载路径写入边界。** 最初将其实现为 `session/resumed` 边界，并在合并前放弃。它完全覆盖不到 fork，而 fork 恰恰是继承括号的所有方可能仍然存活的那一种情形。由于标记是在加载时铸造的，它还必须在读取路径上做持久写入，这把成本铺开到整个 seam：每次冷加载都递增 revision、对一份无需修复的平衡日志也要走 `commitRepair`、需要一个已存储时间下限来维持钳制的单调性，以及加载在只读存储上会失败。
+**由持久化协调器的冷加载路径写入边界。** 较早的一版迭代写入的是 `session/resumed` 边界；它落选，一是因为完全覆盖不到 fork——而 fork 恰恰是继承括号的所有方可能仍然存活的那一种情形——二是因为在加载时铸造的标记必须在读取路径上做持久写入，这把成本铺开到整个 seam：每次冷加载都递增 revision、对一份无需修复的平衡日志也要走 `commitRepair`、需要一个已存储时间下限来维持钳制的单调性，以及加载在只读存储上会失败。
 
 **在 loop 启动时追加边界。** loop 调用 `resumeWith`，因此覆盖恢复路径，但完全漏掉 `fork()` 与 `adopt()`，而且事件不得不在 `'startup'` 上触发——那是 fork 子会话发布的来源——于是 `SessionStartSource` 将不再具有区分力。它还会在追加标记之前就发布会话，因此 `session/created` 监听方可能观察到一份没有边界的带种子日志。
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
index 14a0ad2bb0..06f69f8d3d 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.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 .agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
-2026-07-30-settings-write-path-integrity.md: f9b56ca83ad3027083884442a051eca102207c24
-2026-07-30-settings-write-path-integrity.zh.md: 1e8ce7eddb6a639512cd792e98fc135f49a8c0be
+2026-07-30-settings-write-path-integrity.md: d59a4524cc704760d7fbdfa286af84da5cbd1926
+2026-07-30-settings-write-path-integrity.zh.md: 5c4651905ffa0dfc1a0f8e080190b875bd9e4afa
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
index f9b56ca83a..d59a4524cc 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.md
@@ -4,11 +4,11 @@ Status: implemented
 
 English | [中文](2026-07-30-settings-write-path-integrity.zh.md)
 
-> Scope: the third review round over `packages/settings/` — write-path data integrity in `dsh-settings-local` (operation chain, read-modify-write, cross-process writer lock, diff-shaped YAML edits) and observer lifecycle in `dsh-settings` (watch disposal, async listener containment, the JSON-shape write boundary). This note reverses one deferral recorded in the [user-settings seam note](2026-07-28-user-settings-seam.md): the cross-process lockfile now ships.
+> Scope: write-path data integrity in `dsh-settings-local` (operation chain, read-modify-write, cross-process writer lock, diff-shaped YAML edits) and observer lifecycle in `dsh-settings` (watch disposal, async listener containment, the JSON-shape write boundary). This note reverses one deferral recorded in the [user-settings seam note](2026-07-28-user-settings-seam.md): the cross-process lockfile now ships.
 
 ## Problem
 
-Review found the provider's write path could destroy state it never observed, and the Service Definition's observer lifecycle leaked past disposal. Concretely: watcher reloads and document writes ran on two independent promise chains while every write rendered the whole next document from the cached text, so an external edit still inside the debounce window was overwritten — and the follow-up reload no-oped because the post-rename content matched the cache, erasing the edit without a trace. The initial `load()` raced the watcher's own setup, leaving a startup window whose changes never fire an event. Two processes sharing a harness home rendered from independent caches, last writer winning whole namespaces. On the Service Definition side, a `watch()` disposer only removed the observer from its set — an invocation already chained onto the watcher tail still ran after disposal, and nothing drained started invocations at service dispose; the `settings/updated` manual fan-out caught only synchronous throws, so an async listener's rejection escaped as an unhandled rejection; and `structuredClone` admitted Dates, Maps, BigInts, and cycles that YAML/JSON storage silently distorts on the reload round-trip (a Date lands as a timestamp string, a BigInt as a plain number). YAML writes replaced the whole namespace node, deleting every comment inside the section a comment-preserving provider had promised to keep.
+The provider's write path could destroy state it never observed, and the Service Definition's observer lifecycle leaked past disposal. Concretely: watcher reloads and document writes ran on two independent promise chains while every write rendered the whole next document from the cached text, so an external edit still inside the debounce window was overwritten — and the follow-up reload no-oped because the post-rename content matched the cache, erasing the edit without a trace. The initial `load()` raced the watcher's own setup, leaving a startup window whose changes never fire an event. Two processes sharing a harness home rendered from independent caches, last writer winning whole namespaces. On the Service Definition side, a `watch()` disposer only removed the observer from its set — an invocation already chained onto the watcher tail still ran after disposal, and nothing drained started invocations at service dispose; the `settings/updated` manual fan-out caught only synchronous throws, so an async listener's rejection escaped as an unhandled rejection; and `structuredClone` admitted Dates, Maps, BigInts, and cycles that YAML/JSON storage silently distorts on the reload round-trip (a Date lands as a timestamp string, a BigInt as a plain number). YAML writes replaced the whole namespace node, deleting every comment inside the section a comment-preserving provider had promised to keep.
 
 ## Decision
 
@@ -32,4 +32,4 @@ Review found the provider's write path could destroy state it never observed, an
 
 ## Consequences
 
-`update()` has documented failure modes for the lock deadline and an invalid on-disk document, and rejection messages carry `$`-rooted paths. A crashed holder can leave a lock that requires verified operator removal; automatic age-based takeover would permit overlapping writers. Remaining, documented in the provider README: same-namespace concurrent edits stay last-write-wins (no per-value merge or revision check), a watcher event the OS never delivers leaves the cache stale until the next signal or write, and comments inside replaced arrays or attached inline to changed scalar values go with the value they described. The [user-settings seam note](2026-07-28-user-settings-seam.md)'s deferred-lockfile alternative is superseded by this note. The same defect classes exist in `dsh-credentials-local` (two chains over one `.env`, cached whole-file write-back, post-persist emit) and in the `llm/adapters-updated` fan-out on the stacked branches; those fixes belong to the PRs that introduce the packages and follow this template on merge-up.
+`update()` has documented failure modes for the lock deadline and an invalid on-disk document, and rejection messages carry `$`-rooted paths. A crashed holder can leave a lock that requires verified operator removal; automatic age-based takeover would permit overlapping writers. Remaining, documented in the provider README: same-namespace concurrent edits stay last-write-wins (no per-value merge or revision check), a watcher event the OS never delivers leaves the cache stale until the next signal or write, and comments inside replaced arrays or attached inline to changed scalar values go with the value they described. The [user-settings seam note](2026-07-28-user-settings-seam.md)'s deferred-lockfile alternative is superseded by this note. The same defect classes existed in `dsh-credentials-local` (two chains over one `.env`, cached whole-file write-back, post-persist emit) and in the `llm/adapters-updated` fan-out; the [credential-boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md) applies this template there.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
index 1e8ce7eddb..5c4651905f 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-settings-write-path-integrity.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-07-30-settings-write-path-integrity.md) | 中文
 
-> 范围：对 `packages/settings/` 的第三轮评审——`dsh-settings-local` 的写路径数据完整性（操作链、读-改-写、跨进程写锁、diff 形态的 YAML 编辑）与 `dsh-settings` 的观察者生命周期（watch 的 dispose（资源释放）、异步监听器收容、JSON 形态写入边界）。本 note 推翻了[用户设置 seam note](2026-07-28-user-settings-seam.md)所记录的一项延后决定：跨进程锁文件现已交付。
+> 范围：`dsh-settings-local` 的写路径数据完整性（操作链、读-改-写、跨进程写锁、diff 形态的 YAML 编辑）与 `dsh-settings` 的观察者生命周期（watch 的 dispose（资源释放）、异步监听器收容、JSON 形态写入边界）。本 note 推翻了[用户设置 seam note](2026-07-28-user-settings-seam.md)所记录的一项延后决定：跨进程锁文件现已交付。
 
 ## 问题
 
-评审发现，提供方的写路径可能销毁它从未观察到的状态，而 Service Definition 的观察者生命周期会泄漏到 dispose 之后。具体而言：watcher 重载与文档写入跑在两条相互独立的 promise 链上，而每次写入都从缓存文本渲染出完整的下一份文档，于是仍处于防抖窗口内的外部编辑会被覆盖——随后的重载又因 rename 后的内容与缓存一致而成为空操作，这次编辑就被无痕抹去。初始 `load()` 与 watcher 自身的建立过程存在竞态，留下一个启动窗口：落在这个窗口内的变更永远不会触发事件。共享同一 harness home 的两个进程各自从独立的缓存渲染，后写者以整个 namespace 为单位胜出。
+提供方的写路径可能销毁它从未观察到的状态，而 Service Definition 的观察者生命周期会泄漏到 dispose 之后。具体而言：watcher 重载与文档写入跑在两条相互独立的 promise 链上，而每次写入都从缓存文本渲染出完整的下一份文档，于是仍处于防抖窗口内的外部编辑会被覆盖——随后的重载又因 rename 后的内容与缓存一致而成为空操作，这次编辑就被无痕抹去。初始 `load()` 与 watcher 自身的建立过程存在竞态，留下一个启动窗口：落在这个窗口内的变更永远不会触发事件。共享同一 harness home 的两个进程各自从独立的缓存渲染，后写者以整个 namespace 为单位胜出。
 
 在 Service Definition 一侧，`watch()` 的释放器只把观察者从集合中移除——已经接到 watcher 链尾的调用在 dispose 之后照常运行，服务 dispose 时也没有任何环节排空已启动的调用；`settings/updated` 的手动扇出只捕获同步抛错，异步监听器的 rejection 会以 unhandled rejection 的形式逃逸；`structuredClone` 则放行 Date、Map、BigInt 与循环引用，而 YAML/JSON 存储会在重载往返中悄悄扭曲这些值（Date 会变成时间戳字符串，BigInt 会变成普通数字）。
 
@@ -38,4 +38,4 @@ YAML 写入则整体替换 namespace 节点，把分节内的每条注释都删
 
 `update()` 对锁获取期限与磁盘文档非法都有成文的失败模式，rejection 消息携带以 `$` 为根的路径。持有者崩溃后可能留下锁，需要操作者核实后移除；若按锁龄自动接管，则会允许多个写入方重叠。仍然存在、且已记录在提供方 README 中的有：同 namespace 并发编辑仍是后写胜出（没有逐值合并，也没有修订号检查）；OS 从未投递的 watcher 事件会让缓存保持陈旧，直到下一个信号或下一次写入；被替换数组内部的注释、以及行内附着在被改标量值上的注释，会随其描述的值一起消失。
 
-[用户设置 seam note](2026-07-28-user-settings-seam.md)里“延后锁文件”那条替代方案已被本 note 取代。同类缺陷还存在于 `dsh-credentials-local`（两条链共用一个 `.env`、按缓存整文件写回、持久化之后才发事件）与堆叠分支上的 `llm/adapters-updated` 扇出；这些修复归引入相应包的那些 PR（Pull Request）所有，向上合并时按本模板处理。
+[用户设置 seam note](2026-07-28-user-settings-seam.md)里“延后锁文件”那条替代方案已被本 note 取代。同类缺陷曾存在于 `dsh-credentials-local`（两条链共用一个 `.env`、按缓存整文件写回、持久化之后才发事件）与 `llm/adapters-updated` 扇出；[credential-boundaries note](2026-07-30-credential-boundaries-and-atomic-registration.md) 在那里套用了本模板。
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
index 7fbaf3c2b9..eec7c013a4 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.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 .agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
-2026-07-30-web-config-plane.md: 78fa9cf970dea30fdc842799134bc1d11608c800
-2026-07-30-web-config-plane.zh.md: b8a4347f95a741140a61e1d47f837aa0502d85ee
+2026-07-30-web-config-plane.md: 1af86fc7917cc40b0544bb5c6254994a87ad7a55
+2026-07-30-web-config-plane.zh.md: 15916fe86e2f5e19e9752721917317aa8c39442d
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
index 78fa9cf970..1af86fc791 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-30-web-config-plane.zh.md)
 
 ## Problem
 
-PR1 made LLM adapter configuration restart-free at the seam, but the only writer was a text editor on `settings.yaml`: the web client had no wire access to settings, credentials, or provider topology, so "store a key, prompt again" still meant leaving the product. Three gaps blocked a config page rather than one: `describe()` returned only the merged effective value (a form cannot tell a user override from a composition default, and serializing it would have shipped `role('secret')` values to every browser), nothing enumerated the providers an adapter *could* run (a bare-mounted `llm-pi-ai` was invisible until configured), and the two adapters both wanted a `deepseek` route key, so the directory could not attribute routes to owning namespaces unambiguously. Hand-maintaining a form per provider was rejected outright — the schemas already exist as schemastery `Config` values, and a second source of field truth drifts.
+The request-level configuration seam made LLM adapter configuration restart-free, but the only writer was a text editor on `settings.yaml`: the web client had no wire access to settings, credentials, or provider topology, so "store a key, prompt again" still meant leaving the product. Three gaps blocked a config page rather than one: `describe()` returned only the merged effective value (a form cannot tell a user override from a composition default, and serializing it would have shipped `role('secret')` values to every browser), nothing enumerated the providers an adapter *could* run (a bare-mounted `llm-pi-ai` was invisible until configured), and the two adapters both wanted a `deepseek` route key, so the directory could not attribute routes to owning namespaces unambiguously. Hand-maintaining a form per provider was rejected outright — the schemas already exist as schemastery `Config` values, and a second source of field truth drifts.
 
 ## Decision
 
@@ -20,7 +20,7 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer
 
 **The llm seam declares configurability and announces topology.** `registerConfigurableProviders()` is an all-or-nothing, fiber-scoped directory of `{provider, displayName, settingsNs, settingsPath}` — the addressing a config page needs to open the right settings subtree for a route that may not exist yet; `listConfigurableProviders()` merges with live routes in the wire handler so undeclared live routes still report active. The zero-payload `'llm/adapters-updated'` event fires from all four registration/unregistration commit points with contained listener dispatch (INVARIANT rethrow), following the settings/commands precedent. `llm-deepseek`'s route renamed to `deepseek-official` because the pi-ai catalog legitimately owns `deepseek` as an aggregator entry; pre-release stance, no alias.
 
-**A hand-written editor over a schema model layer.** `dsh-client-schema-form` rehydrates the wire's `toJSON()` envelope into live schemastery nodes for validation, path resolution, and immutable draft editing — but no generic rendering: the first cut shipped a full schema-driven form renderer, and the resulting page was an unstyled schema dump (every advanced field flattened onto the card, raw field names as labels, the `retryPolicy` unsupported-fallback in the main flow). The user chose the hand-written direction over adding a hint/grouping system, and a second round removed the reference input entirely: the card's primary field is one **API key** input, a whole-section provider without a configured key opens as its setup card, and the collapsed 自定义设置 fold carries the curated per-family extras (`baseURL` for both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, plus direct DeepSeek model rows with `id`, `name`, and `contextWindow`). Existing model fields outside that visible set survive array edits; retry policy, timeouts, and other fields remain owned by `settings.yaml`. Validation still runs the rehydrated schema before writing, while adapter-specific checks reject catalog invariants that the serialized schema cannot express. The card's colors resolve through the `--dsw-alias-*` design tokens; it had named `--border`/`--surface`/`--text-*`, which nothing in this app defines, so it rendered their light-mode fallbacks and stayed light under the dark theme. The model catalog takes the row shape the pi-ai provider form introduces: one bordered entry per model, id and display name on the row, and the capacities behind the row's own disclosure, so the two editors read as one design rather than diverging once both land. Every field keeps the indexed `aria-label` that names it. Both capacities are text fields reading a decimal `K`/`M` suffix (`1M` is 1000K, matching how capacities are quoted) and storing the plain count: a field holds the typed text while it has focus, because re-deriving it from the parsed count on every keystroke would rewrite `1000` to `1K` mid-word, and text that does not parse stays on screen so the save-time rejection names a row the user can still see. The shared class names carry this file's token spellings, not that branch's: `--dsw-alias-border-subtle`, `--dsw-alias-text-tertiary`, and `--dsw-alias-text-primary` are undeclared, so they resolve to the light-mode literals in their fallback slots — the defect this section was moved off. A styles test now rejects any `--dsw-*` name the token sheet does not declare, so the next editor to name one fails rather than shipping a light-only surface.
+**A hand-written editor over a schema model layer.** `dsh-client-schema-form` rehydrates the wire's `toJSON()` envelope into live schemastery nodes for validation, path resolution, and immutable draft editing — but no generic rendering: the first cut shipped a full schema-driven form renderer, and the resulting page was an unstyled schema dump (every advanced field flattened onto the card, raw field names as labels, the `retryPolicy` unsupported-fallback in the main flow). The hand-written direction won over adding a hint/grouping system, and a further simplification removed the reference input entirely: the card's primary field is one **API key** input, a whole-section provider without a configured key opens as its setup card, and the collapsed 自定义设置 fold carries the curated per-family extras (`baseURL` for both families, `reasoningEffort` for deepseek / `reasoning` for pi-ai, plus direct DeepSeek model rows with `id`, `name`, and `contextWindow`). Existing model fields outside that visible set survive array edits; retry policy, timeouts, and other fields remain owned by `settings.yaml`. Validation still runs the rehydrated schema before writing, while adapter-specific checks reject catalog invariants that the serialized schema cannot express. The card's colors resolve through the `--dsw-alias-*` design tokens; it had named `--border`/`--surface`/`--text-*`, which nothing in this app defines, so it rendered their light-mode fallbacks and stayed light under the dark theme. The model catalog takes the row shape the pi-ai provider form introduces: one bordered entry per model, id and display name on the row, and the capacities behind the row's own disclosure, so the two editors read as one design rather than diverging. Every field keeps the indexed `aria-label` that names it. Both capacities are text fields reading a decimal `K`/`M` suffix (`1M` is 1000K, matching how capacities are quoted) and storing the plain count: a field holds the typed text while it has focus, because re-deriving it from the parsed count on every keystroke would rewrite `1000` to `1K` mid-word, and text that does not parse stays on screen so the save-time rejection names a row the user can still see. The shared class names carry only declared token spellings: `--dsw-alias-border-subtle`, `--dsw-alias-text-tertiary`, and `--dsw-alias-text-primary` are undeclared, so naming them resolves to the light-mode literals in their fallback slots. A styles test now rejects any `--dsw-*` name the token sheet does not declare, so the next editor to name one fails rather than shipping a light-only surface.
 
 **The Models page is a three-domain join with service-shaped apply semantics.** Rows are configured providers; the add card's select is the dormant directory remainder. Route liveness still gates readiness and invalidates the join, but the page does not render it as provider status because configuration presence and runtime availability are distinct. The key path stays reference-shaped without ever showing a reference: a typed key stores **write-only** through `credentials.set` under the profile's `apiKeyEnv`, deriving `<ROUTE>_API_KEY` when none exists (the pi-ai profile records the derivation only when a key is entered), so `settings.yaml` never carries a key value; a blank pi-ai key materializes a reference-free profile and preserves provider-native authentication. Profile edits and removals land as minimal path-addressed `settings.mutate` operations against the redacted user section, which never names a secret the page did not receive. Removing a user-layer provider first opens a localized confirmation dialog whose row actions, title, description, and final action identify the same provider; confirmation removes an exact configured+writable derived credential before the profile, while custom, environment, and unidentified targets remain untouched. Both stages are idempotent and a partial failure stays in the dialog for retry. DeepSeek's model list is array-replace configuration: inherited effective rows remain visible until the first edit materializes the complete list in the user layer, and reset unsets the list override. The partial-commit and credential-ownership rationale lives in the [provider credential lifecycle note](../bug-fix/2026-08-06-provider-credential-lifecycle.md).
 
@@ -28,12 +28,12 @@ PR1 made LLM adapter configuration restart-free at the seam, but the only writer
 
 - **Serving JSON Schema over the wire** — schemastery's `toJSON()` envelope round-trips `role()`/meta and rehydrates into the validator the client already ships for drafts; converting to JSON Schema loses exactly the role annotations the credential control and secret redaction key on.
 - **A generic schema-driven form renderer** — implemented first, then replaced: field truth without visual hierarchy produced an ugly, unusable card, and making it good meant building a hint vocabulary (primary/advanced grouping, per-field descriptions, array item cards) rivaling the hand-written editor in cost while still fitting no mockup exactly. Two schemas exist today (the deepseek `Config` and the shared pi-ai profile), so hand-writing is two thin namespace-keyed layouts; the drift risk is bounded by save-time schema validation and by unknown fields staying untouched in the document.
-- **Masking secrets per-field with sentinel backfill on `replace`** — the PR1 decision (secrets are references) already deleted the stored-literal case for the product default; structural redaction plus a write-only credential path handles the residue without teaching every writer a sentinel protocol.
+- **Masking secrets per-field with sentinel backfill on `replace`** — the request-level seam decision (secrets are references) already deleted the stored-literal case for the product default; structural redaction plus a write-only credential path handles the residue without teaching every writer a sentinel protocol.
 - **Storing the typed key as a literal `apiKey` setting** — the v1 "one API key input" requirement could have written the literal into the profile, but every UI removal path rebuilds the user section from the *redacted* layers, so any reset or row deletion would silently drop stored sibling keys; deriving a reference keeps the input single-field while keeping `settings.yaml` secret-free and every replace safe.
-- **A `models` bridge plugin owning provider configuration** — same rejection as PR1: per-plugin namespaces plus a four-field directory declaration give the UI everything it needs; the bridge's unified dict re-imports the adapter-mapping indirection.
+- **A `models` bridge plugin owning provider configuration** — same rejection as in the request-level seam note: per-plugin namespaces plus a four-field directory declaration give the UI everything it needs; the bridge's unified dict re-imports the adapter-mapping indirection.
 - **Page-side polling instead of pushed frames** — the mux already carries `host/commands-changed`; three more frames cost one shape each and make a second tab, an external `settings.yaml` edit, and a settings-born route converge at event speed.
 - **Hard-coding `$DSH_HOME/settings.yaml` or returning `documentPath` through `host.openPath` in the browser** — rejected because `settings-local.path` may select another YAML/JSON document, non-file providers have no Host path, and a general path request makes the browser the authority for a local filesystem target. Provider preparation is the authoritative source, and the Host-owned operation feeds the existing opener.
 
 ## Consequences
 
-The whole loop is pinned keyless in the browser lane (`apps/web/tests/models-settings.e2e.ts`): the add card offers the dormant pi-ai catalog, adding `minimax-cn` with a typed key writes the reference-only profile into `settings.yaml`, stores the value into the harness home's `.env` under the derived `MINIMAX_CN_API_KEY`, registers the route live on the topology frame, and the customized fold merges `reasoning` beside the reference — zero model calls, ARIA goldens for the add-card, configured, and identified delete-confirmation states, plus a scaffold `harnessHome` so tests never touch a real `~/.dsh` (the provider under test is one whose derived reference cannot collide with a developer's exported keys). The settings-shell scenario intercepts the pathless native intent; Service Definition, provider, wire, React, and native-opener tests separately pin provider absence, custom-path resolution, absent-file materialization, owner-only permissions, hidden remote/unavailable states, duplicate-click collapse, localized failure, macOS text-editor dispatch, and Linux/Windows desktop dispatch. The removal scenario proves cancellation leaves both profile and key intact, then confirmation removes both the profile and its identified managed credential. The DeepSeek onboarding fixture edits the default catalog into a user-owned list, persists an arbitrary model id/name/context window, removes the active row, and observes the model selector's empty-selection fallback. The rename touched 239 files (fixtures, goldens, docs, python) in one commit with no compatibility alias. The renderer replacement cost one commit and no wire change: apply semantics, redaction, and the directory join were renderer-agnostic all along. Deferred: a per-row models preview (the picker already lists models) and a page address for live routes that never declared configurability.
+The whole loop is pinned keyless in the browser lane (`apps/web/tests/models-settings.e2e.ts`): the add card offers the dormant pi-ai catalog, adding `minimax-cn` with a typed key writes the reference-only profile into `settings.yaml`, stores the value into the harness home's `.env` under the derived `MINIMAX_CN_API_KEY`, registers the route live on the topology frame, and the customized fold merges `reasoning` beside the reference — zero model calls, ARIA goldens for the add-card, configured, and identified delete-confirmation states, plus a scaffold `harnessHome` so tests never touch a real `~/.dsh` (the provider under test is one whose derived reference cannot collide with a developer's exported keys). The settings-shell scenario intercepts the pathless native intent; Service Definition, provider, wire, React, and native-opener tests separately pin provider absence, custom-path resolution, absent-file materialization, owner-only permissions, hidden remote/unavailable states, duplicate-click collapse, localized failure, macOS text-editor dispatch, and Linux/Windows desktop dispatch. The removal scenario proves cancellation leaves both profile and key intact, then confirmation removes both the profile and its identified managed credential. The DeepSeek onboarding fixture edits the default catalog into a user-owned list, persists an arbitrary model id/name/context window, removes the active row, and observes the model selector's empty-selection fallback. The rename touched 239 files (fixtures, goldens, docs, python) with no compatibility alias. The renderer replacement needed no wire change: apply semantics, redaction, and the directory join were renderer-agnostic all along. Deferred: a per-row models preview (the picker already lists models) and a page address for live routes that never declared configurability.
diff --git a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
index b8a4347f95..15916fe86e 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-web-config-plane.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 ## 问题
 
-PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯一的写入方还是直接编辑 `settings.yaml` 的文本编辑器：web 客户端没有触达设置、凭据或提供方拓扑的任何 wire 通道，「存入密钥、再次发起提示」于是仍意味着离开产品本身。挡住配置页的缺口不是一个，而是三个：`describe()` 只返回合并后的生效值（表单分不清用户覆盖与组合默认值，而且照原样序列化会把 `role('secret')` 的值发到每一个浏览器）；没有任何东西枚举适配器*可以*运行的提供方（裸挂载的 `llm-pi-ai` 在配置之前完全不可见）；两个适配器又都想要 `deepseek` 这个路由键，目录因此无法无歧义地把路由归到拥有它的 namespace 名下。为每个提供方手工维护一份表单被直接否决——schema 已经以 schemastery `Config` 值的形式存在，第二份字段真源注定漂移。
+请求级配置 seam 让 LLM（大语言模型）适配器配置免重启，但唯一的写入方还是直接编辑 `settings.yaml` 的文本编辑器：web 客户端没有触达设置、凭据或提供方拓扑的任何 wire 通道，「存入密钥、再次发起提示」于是仍意味着离开产品本身。挡住配置页的缺口不是一个，而是三个：`describe()` 只返回合并后的生效值（表单分不清用户覆盖与组合默认值，而且照原样序列化会把 `role('secret')` 的值发到每一个浏览器）；没有任何东西枚举适配器*可以*运行的提供方（裸挂载的 `llm-pi-ai` 在配置之前完全不可见）；两个适配器又都想要 `deepseek` 这个路由键，目录因此无法无歧义地把路由归到拥有它的 namespace 名下。为每个提供方手工维护一份表单被直接否决——schema 已经以 schemastery `Config` 值的形式存在，第二份字段真源注定漂移。
 
 ## 决策
 
@@ -20,7 +20,7 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 **llm seam 声明可配置性并公布拓扑。**`registerConfigurableProviders()` 是一个全有或全无、以 fiber 为作用域的目录，条目为 `{provider, displayName, settingsNs, settingsPath}`——这正是配置页要为一条可能尚不存在的路由打开正确设置子树时所需要的寻址；`listConfigurableProviders()` 在 wire 处理器里与存活路由合并，未声明的存活路由因此仍报告为激活。零负载的 `'llm/adapters-updated'` 事件从全部四个注册／注销提交点触发，listener 派发带异常隔离（INVARIANT 重抛），沿用 settings/commands 的先例。`llm-deepseek` 的路由重命名为 `deepseek-official`，因为 pi-ai catalog 名正言顺地拥有 `deepseek` 这个聚合器条目；依预发布立场，不设别名。
 
-**架在 schema 模型层之上的手写编辑器。**`dsh-client-schema-form` 把 wire 的 `toJSON()` 信封还原（rehydrate）为活的 schemastery 节点，用于校验、路径解析与不可变草稿编辑——但不做通用渲染：第一版交付了完整的 schema 驱动表单渲染器，得到的却是一个未加样式、把 schema 原样倾倒出来的页面（每个进阶字段都平铺到卡片上、原始字段名直接充当标签、`retryPolicy` 的「不支持」回退落在主流程里）。用户没有再加一套提示／分组系统，而是选择了手写方向，第二轮又把引用输入框整个移除：卡片的主字段是一个 **API 密钥**输入框，未配置密钥的整分节提供方会以其设置卡片的形式打开，收起的「自定义设置」折叠区承载按家族精选的额外字段（两个家族都有 `baseURL`，deepseek 有 `reasoningEffort`／pi-ai 有 `reasoning`，另有直接 DeepSeek 模型行的 `id`、`name` 和 `contextWindow`）。现有模型字段中不在可见集合内的部分会在数组编辑后保留；重试策略、超时及其他字段仍归 `settings.yaml` 所有。校验仍会在写入前运行还原出的 schema，适配器特有的检查则会拒绝序列化 schema 无法表达的目录不变量。卡片的颜色经 `--dsw-alias-*` 设计 token 解析；它此前引用的 `--border`／`--surface`／`--text-*` 在本应用中无人定义，于是渲染出的是它们的亮色模式回退值，在暗色主题下依旧保持亮色。模型目录采用 pi-ai 提供方表单引入的行形态：每个模型一个带边框的条目，ID 与显示名称落在行上，容量则收在该行自己的折叠区里，使两个编辑器呈现为同一套设计，而不是在双方都落地后各自分岔。每个字段都保留那个为其命名的带序号 `aria-label`。两项容量都是文本输入框，读取十进制的 `K`／`M` 后缀（`1M` 即 1000K，与容量的通行标注方式一致）并存储纯数值：字段持有焦点期间保留键入的文本，因为若每次按键都从解析出的数值重新推导该文本，`1000` 会在尚未输完时就被改写成 `1K`；无法解析的文本也会留在屏幕上，因此保存时的拒绝点名的是用户仍能看见的那一行。共用的类名承载的是本文件的 token 写法，而非那个分支的：`--dsw-alias-border-subtle`、`--dsw-alias-text-tertiary` 和 `--dsw-alias-text-primary` 均未声明，于是它们解析为各自回退槽位中的亮色模式字面值——正是本节此前迁离的那个缺陷。现在有一个样式测试会拒绝 token 表未声明的任何 `--dsw-*` 名称，因此下一个写出这类名称的编辑者会当场失败，而不是交付一个只有亮色的界面。
+**架在 schema 模型层之上的手写编辑器。**`dsh-client-schema-form` 把 wire 的 `toJSON()` 信封还原（rehydrate）为活的 schemastery 节点，用于校验、路径解析与不可变草稿编辑——但不做通用渲染：第一版交付了完整的 schema 驱动表单渲染器，得到的却是一个未加样式、把 schema 原样倾倒出来的页面（每个进阶字段都平铺到卡片上、原始字段名直接充当标签、`retryPolicy` 的「不支持」回退落在主流程里）。手写方向胜过了再加一套提示／分组系统，进一步的简化又把引用输入框整个移除：卡片的主字段是一个 **API 密钥**输入框，未配置密钥的整分节提供方会以其设置卡片的形式打开，收起的「自定义设置」折叠区承载按家族精选的额外字段（两个家族都有 `baseURL`，deepseek 有 `reasoningEffort`／pi-ai 有 `reasoning`，另有直接 DeepSeek 模型行的 `id`、`name` 和 `contextWindow`）。现有模型字段中不在可见集合内的部分会在数组编辑后保留；重试策略、超时及其他字段仍归 `settings.yaml` 所有。校验仍会在写入前运行还原出的 schema，适配器特有的检查则会拒绝序列化 schema 无法表达的目录不变量。卡片的颜色经 `--dsw-alias-*` 设计 token 解析；它此前引用的 `--border`／`--surface`／`--text-*` 在本应用中无人定义，于是渲染出的是它们的亮色模式回退值，在暗色主题下依旧保持亮色。模型目录采用 pi-ai 提供方表单引入的行形态：每个模型一个带边框的条目，ID 与显示名称落在行上，容量则收在该行自己的折叠区里，使两个编辑器呈现为同一套设计，而不是各自分岔。每个字段都保留那个为其命名的带序号 `aria-label`。两项容量都是文本输入框，读取十进制的 `K`／`M` 后缀（`1M` 即 1000K，与容量的通行标注方式一致）并存储纯数值：字段持有焦点期间保留键入的文本，因为若每次按键都从解析出的数值重新推导该文本，`1000` 会在尚未输完时就被改写成 `1K`；无法解析的文本也会留在屏幕上，因此保存时的拒绝点名的是用户仍能看见的那一行。共用的类名只承载已声明的 token 写法：`--dsw-alias-border-subtle`、`--dsw-alias-text-tertiary` 和 `--dsw-alias-text-primary` 均未声明，写出它们就会解析为各自回退槽位中的亮色模式字面值。现在有一个样式测试会拒绝 token 表未声明的任何 `--dsw-*` 名称，因此下一个写出这类名称的编辑者会当场失败，而不是交付一个只有亮色的界面。
 
 **Models 页是一次三领域联接，应用语义与服务同形。**每一行是一个已配置的提供方；「新增」卡片的选择框是可配置提供方目录中剩余的休眠条目。路由存活状态仍用于就绪判定，并会使该联接失效，但页面不将其渲染为提供方状态，因为配置存在与运行时可用性是两个不同概念。密钥通道保持引用形态，却从不展示任何引用：键入的密钥经 `credentials.set` **只写**存入 profile 的 `apiKeyEnv` 之下，引用不存在时便派生 `<ROUTE>_API_KEY`（仅在输入密钥时，pi-ai profile 才会记录该派生），因此 `settings.yaml` 从不携带密钥值；留空 pi-ai 密钥会具化一个不带引用的 profile，并保留提供方原生认证。profile 的编辑和删除会针对脱敏后的用户分节，以按路径寻址的最小 `settings.mutate` 操作落地，绝不会点名页面未收到的机密。删除用户层提供方时，会先打开本地化确认对话框，其行操作、标题、说明和最终操作都会点名同一个提供方；确认后会先清除与派生目标精确匹配且已配置、可写的凭据，再删除 profile，自定义目标、环境目标和无法识别的目标则保持不变。两个阶段都具备幂等性，部分失败会留在对话框中供重试。DeepSeek 的模型列表是数组替换配置：继承而来的生效模型行会一直显示，直到第一次编辑将完整列表具化到用户层；重置则会取消设置该列表覆盖。部分提交与凭据所有权的理由记录在[提供方凭据生命周期 note](../bug-fix/2026-08-06-provider-credential-lifecycle.md)中。
 
@@ -28,12 +28,12 @@ PR1 让 LLM（大语言模型）适配器配置在 seam 层面免重启，但唯
 
 - **在 wire 上改发 JSON Schema**——schemastery 的 `toJSON()` 信封能往返保留 `role()`/meta，并还原成客户端为草稿校验本就自带的那个校验器；转换成 JSON Schema 丢掉的恰恰是凭据控件与 secret 脱敏所依赖的角色注解。
 - **通用的 schema 驱动表单渲染器**——先实现、后被替换：如实呈现字段却缺失视觉层级，产出的卡片丑陋且不可用；要把它做好，就意味着构建一套提示词汇（主要／进阶分组、逐字段描述、数组项卡片），成本堪比手写编辑器，却仍无法与任何设计稿完全吻合。今天存在两份 schema（deepseek 的 `Config` 与共享的 pi-ai profile），手写因此就是两套以 namespace 为键的薄布局；漂移风险由保存时的 schema 校验以及未知字段在文档中的原样保留共同约束。
-- **逐字段脱敏机密并在 `replace` 时回填哨兵值**——PR1 的决策（机密是引用）已经为产品默认形态删掉了「存储字面量」这种情况；结构化脱敏加上只写的凭据通道足以处理残余情形，无需让每个写入方都学会一套哨兵协议。
+- **逐字段脱敏机密并在 `replace` 时回填哨兵值**——请求级 seam 的决策（机密是引用）已经为产品默认形态删掉了「存储字面量」这种情况；结构化脱敏加上只写的凭据通道足以处理残余情形，无需让每个写入方都学会一套哨兵协议。
 - **把键入的密钥存成字面 `apiKey` 设置**——v1「单个 API 密钥输入框」的需求本可以把字面量直接写进 profile，但 UI 的每条删除路径都会从*脱敏后的*各层重建用户分节，任何重置或整行删除都会静默丢掉已存储的兄弟密钥；派生引用让输入保持单字段，同时让 `settings.yaml` 不含机密、每一次 replace 都安全。
-- **由 `models` 桥接插件持有提供方配置**——与 PR1 相同的否决理由：按插件划分的 namespace 加上四字段的目录声明已经给了 UI 需要的一切；桥接层的统一字典会把适配器映射那层间接重新引进来。
+- **由 `models` 桥接插件持有提供方配置**——与请求级 seam note 相同的否决理由：按插件划分的 namespace 加上四字段的目录声明已经给了 UI 需要的一切；桥接层的统一字典会把适配器映射那层间接重新引进来。
 - **页面侧轮询而非推送帧**——mux 已经承载 `host/commands-changed`；再加三个帧各自只多一个形状的成本，就让第二个标签页、外部的 `settings.yaml` 编辑和由设置催生的路由都以事件速度收敛。
 - **在浏览器中硬编码 `$DSH_HOME/settings.yaml`，或经 `host.openPath` 回传 `documentPath`**——否决，因为 `settings-local.path` 可能选择另一份 YAML/JSON 文档、非文件提供方没有 Host 路径，而且通用路径请求会让浏览器成为本地文件系统目标的权威。提供方的准备操作才是权威来源，由 Host 持有的操作会把结果交给现有打开器。
 
 ## 后果
 
-整条闭环以无密钥方式固定在浏览器测试通道（`apps/web/tests/models-settings.e2e.ts`）：「新增」卡片提供休眠的 pi-ai catalog，携键入的密钥添加 `minimax-cn` 会把只含引用的 profile 写入 `settings.yaml`、把密钥值存入 harness 家目录 `.env` 中派生的 `MINIMAX_CN_API_KEY` 之下、路由随拓扑帧注册为存活，「自定义设置」折叠区则把 `reasoning` 合并到引用旁边——全程零模型调用，「新增」卡片态、已配置态与已点名目标的删除确认态各有 ARIA golden，另有脚手架式的 `harnessHome`，测试绝不触碰真实的 `~/.dsh`（受测提供方是派生引用不可能与开发者已导出密钥相撞的那一个）。设置外壳场景会截获无路径参数的原生意图；Service Definition、提供方、wire、React 与原生打开器测试分别固定了提供方缺失、自定义路径解析、缺失文件创建、仅属主权限、远程／不可用时隐藏、重复点击合并、本地化失败、macOS 文本编辑器分发，以及 Linux/Windows 桌面分发。删除场景证明，取消会保留 profile 和密钥，随后的确认会同时删除 profile 及其已识别的受管凭据。DeepSeek 首次使用 fixture 会把默认目录编辑为用户自有列表、持久化任意模型的 ID／名称／上下文窗口、移除活动模型行，并观察模型选择器的空选择回退。这次重命名在一次提交中触及 239 个文件（fixture（测试前置数据）、golden、文档、python），未保留兼容别名。替换渲染器只花了一次提交，且没有任何 wire 变更：应用语义、脱敏与目录联接从一开始就与渲染器无关。延后事项：每行的模型预览（选择器已能列出模型）和为从未声明可配置性的存活路由提供页面地址。
+整条闭环以无密钥方式固定在浏览器测试通道（`apps/web/tests/models-settings.e2e.ts`）：「新增」卡片提供休眠的 pi-ai catalog，携键入的密钥添加 `minimax-cn` 会把只含引用的 profile 写入 `settings.yaml`、把密钥值存入 harness 家目录 `.env` 中派生的 `MINIMAX_CN_API_KEY` 之下、路由随拓扑帧注册为存活，「自定义设置」折叠区则把 `reasoning` 合并到引用旁边——全程零模型调用，「新增」卡片态、已配置态与已点名目标的删除确认态各有 ARIA golden，另有脚手架式的 `harnessHome`，测试绝不触碰真实的 `~/.dsh`（受测提供方是派生引用不可能与开发者已导出密钥相撞的那一个）。设置外壳场景会截获无路径参数的原生意图；Service Definition、提供方、wire、React 与原生打开器测试分别固定了提供方缺失、自定义路径解析、缺失文件创建、仅属主权限、远程／不可用时隐藏、重复点击合并、本地化失败、macOS 文本编辑器分发，以及 Linux/Windows 桌面分发。删除场景证明，取消会保留 profile 和密钥，随后的确认会同时删除 profile 及其已识别的受管凭据。DeepSeek 首次使用 fixture 会把默认目录编辑为用户自有列表、持久化任意模型的 ID／名称／上下文窗口、移除活动模型行，并观察模型选择器的空选择回退。这次重命名触及 239 个文件（fixture（测试前置数据）、golden、文档、python），未保留兼容别名。替换渲染器不需要任何 wire 变更：应用语义、脱敏与目录联接从一开始就与渲染器无关。延后事项：每行的模型预览（选择器已能列出模型）和为从未声明可配置性的存活路由提供页面地址。
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
index 37ab3eda38..abced92b1a 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.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 .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
-2026-07-31-code-runtime-portable-identifier-seam.md: ba2aa8eeabb823978fca32a59d98d56971784a92
-2026-07-31-code-runtime-portable-identifier-seam.zh.md: 689ffa1b1ffcb5be1e2aa2bd9cd49c2ae40ba7ee
+2026-07-31-code-runtime-portable-identifier-seam.md: f3eba1ac25fab67aa91da97d1991fc613dc449d1
+2026-07-31-code-runtime-portable-identifier-seam.zh.md: f38463a1405712a61f7ff88aabc1bc8fe96871ae
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
index ba2aa8eeab..f3eba1ac25 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-31-code-runtime-portable-identifier-seam.zh.md)
 
 The code-runtime seam promises that a binding-namespace list valid on one backend is valid on every backend, so a Code Mode consumer can hand the same bindings to any registered runtime without knowing its language. The first backend, `dsh-code-runtime-worker`, privately owned the identifier rules that enforce part of that promise: an `IDENTIFIER` regex that allowed the JS-only `$`, a `RESERVED_WORDS` set holding only ECMAScript keywords, and a `RESERVED_ERROR_PROPERTIES` set of three JS `Error` slots. Those rules described the worker's own language, not the seam's portability contract.
 
-A second backend written against a different language (CPython, arriving in a later PR of this stack) would either re-declare its own rules — letting `lambda` pass the worker and fail Python, or `$tools` pass the worker and fail every non-JS backend — or import the worker's, inverting the dependency so a Service provider reached into a sibling Service provider. Neither keeps the portability promise real: it would hold only for the backend a caller happened to test against.
+A second backend written against a different language (CPython) would either re-declare its own rules — letting `lambda` pass the worker and fail Python, or `$tools` pass the worker and fail every non-JS backend — or import the worker's, inverting the dependency so a Service provider reached into a sibling Service provider. Neither keeps the portability promise real: it would hold only for the backend a caller happened to test against.
 
 ## Decision
 
@@ -21,13 +21,13 @@ The Service Definition package (`@deepseek-ai/dsh-code-runtime`) exports the por
 
 The Service Definition also narrows the portable identifier subset to `[A-Za-z_][A-Za-z0-9_]*` (documented on `CodeBindingNamespace.global` and `CodeBindingErrorClass`), dropping the JS-only `$`. The worker consumes the shared constants directly under their exported names — `PORTABLE_RESERVED_WORDS` for both binding-global and error-class names, `RESERVED_BINDING_GLOBALS` for backend-owned slots, `RESERVED_ERROR_MEMBERS` plus `DUNDER_MEMBER` for error members — with no local re-alias; its `IDENTIFIER` regex loses `$`.
 
-The constants live in the Service Definition even though only one backend ships in this PR: the whole point is that the contract is language-agnostic and owned above any single language. A Service provider that violated it would be the bug, and the shared set is where a reviewer looks to see what "portable" means.
+The constants live in the Service Definition even though the worker is the only shipped backend: the whole point is that the contract is language-agnostic and owned above any single language. A Service provider that violated it would be the bug, and the shared set is where a reviewer looks to see what "portable" means.
 
 ## Scope
 
-This PR delivers only the Service Definition extension and the worker's adoption of it. No Python backend, `py-types` renderer, or Code Mode language dispatch ships here — they are later PRs in the stack that depend on these exports. The Service Definition README's worker-only wording is left unchanged for the same reason: linking to a `dsh-code-runtime-python` README that does not yet exist would break the dead-link gate.
+This decision delivers only the Service Definition extension and the worker's adoption of it. The `py-types` renderer and Code Mode language dispatch are owned by the [language-dispatch note](../feature/2026-07-31-code-mode-language-dispatch.md); a Python backend does not exist yet. The Service Definition README keeps its worker-only wording for that reason: linking to a `dsh-code-runtime-python` README that does not exist would break the dead-link gate.
 
-`RESERVED_BINDING_GLOBALS` currently encodes the not-yet-merged Python bootstrap's concrete design: it seeds exactly `__builtins__`/`__name__` and wraps the program under `__dsh_main__`. The Python-backend PR that seeds any additional module global (`__doc__`, `__loader__`, `__spec__`, `__file__`, `__package__`, …) MUST widen this set in the same change, exactly as adding a language widens `PORTABLE_RESERVED_WORDS` — a name the bootstrap seeds but the set omits is the portability split this contract exists to prevent.
+`RESERVED_BINDING_GLOBALS` encodes the Python bootstrap's concrete design ahead of the backend itself: it seeds exactly `__builtins__`/`__name__` and wraps the program under `__dsh_main__`. A Python backend that seeds any additional module global (`__doc__`, `__loader__`, `__spec__`, `__file__`, `__package__`, …) MUST widen this set in the same change, exactly as adding a language widens `PORTABLE_RESERVED_WORDS` — a name the bootstrap seeds but the set omits is the portability split this contract exists to prevent.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
index 689ffa1b1f..f38463a140 100644
--- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 code-runtime seam 承诺：在一个后端上有效的绑定命名空间列表，在每个后端上都有效，因此 Code Mode 消费方可以把同一组绑定交给任何已注册的运行时，而不必知道它的语言。首个后端 `dsh-code-runtime-worker` 私自拥有了执行这项承诺一部分的标识符规则：一个允许 JS 专有 `$` 的 `IDENTIFIER` 正则、一个只含 ECMAScript 关键字的 `RESERVED_WORDS` 集合，以及一个含三个 JS `Error` 槽位的 `RESERVED_ERROR_PROPERTIES` 集合。这些规则描述的是 worker 自身的语言，而非 seam 的可移植性约定。
 
-一个针对不同语言（CPython，将在本 stack 后续 PR 中到来）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使一个 Service provider 伸手进入另一个兄弟 Service provider。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
+一个针对不同语言（CPython）编写的第二后端，要么重新声明自己的规则——让 `lambda` 通过 worker 却在 Python 上失败，或让 `$tools` 通过 worker 却在每个非 JS 后端上失败——要么导入 worker 的规则，从而反转依赖，使一个 Service provider 伸手进入另一个兄弟 Service provider。二者都无法让可移植承诺成真：它只对调用方恰好测试过的那个后端成立。
 
 ## Decision
 
@@ -21,13 +21,13 @@ Service Definition 包（`@deepseek-ai/dsh-code-runtime`）以四个具名常量
 
 Service Definition 同时把可移植标识符子集收窄为 `[A-Za-z_][A-Za-z0-9_]*`（记录在 `CodeBindingNamespace.global` 与 `CodeBindingErrorClass` 上），去掉 JS 专有的 `$`。worker 直接以这些常量的导出名称消费它们——binding-global 与 error-class 名称用 `PORTABLE_RESERVED_WORDS`、后端拥有槽位用 `RESERVED_BINDING_GLOBALS`、error member 用 `RESERVED_ERROR_MEMBERS` 加 `DUNDER_MEMBER`——不再本地起别名；其 `IDENTIFIER` 正则去掉 `$`。
 
-尽管本 PR 只交付一个后端，这些常量仍置于 Service Definition：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的 Service provider 才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
+尽管 worker 是唯一已交付的后端，这些常量仍置于 Service Definition：要点正是该约定与语言无关，且拥有权在任何单一语言之上。违反它的 Service provider 才是 bug，而共享集合正是复审者查看"可移植"含义的地方。
 
 ## Scope
 
-本 PR 只交付 Service Definition 扩展与 worker 对它的采用。这里不交付任何 Python 后端、`py-types` 渲染器或 Code Mode 的语言分发——它们是本 stack 中依赖这些导出的后续 PR。Service Definition README 中仅描述 worker 的措辞保持不变，理由相同：链接到一个尚不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
+本决策只交付 Service Definition 扩展与 worker 对它的采用。`py-types` 渲染器与 Code Mode 的语言分发归[语言分发 note](../feature/2026-07-31-code-mode-language-dispatch.md)所有；Python 后端尚不存在。Service Definition README 因此保留仅描述 worker 的措辞：链接到一个不存在的 `dsh-code-runtime-python` README 会破坏死链 gate。
 
-`RESERVED_BINDING_GLOBALS` 当前编码了尚未合并的 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端 PR 必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本约定要防止的可移植性分裂。
+`RESERVED_BINDING_GLOBALS` 先于后端本身编码了 Python bootstrap 的具体设计：它恰好 seed `__builtins__`/`__name__`，并把程序包装在 `__dsh_main__` 之下。任何 seed 额外模块 global（`__doc__`、`__loader__`、`__spec__`、`__file__`、`__package__` 等）的 Python 后端必须在同一改动中扩宽此集合，正如新增一门语言即扩宽 `PORTABLE_RESERVED_WORDS`——bootstrap 会 seed 却不在集合中的名称，正是本约定要防止的可移植性分裂。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index dfe291e9d0..0a007fc184 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: f3db8b9eec5eb8fb610fc58edad9313e4f715326
-2026-08-02-typert-remote-method-calls.zh.md: 2290b701eff7ca601b500efbfcf7bdc59c01bcba
+2026-08-02-typert-remote-method-calls.md: b316d1a42c4f69c8e1163f1f36249b61a7d126ef
+2026-08-02-typert-remote-method-calls.zh.md: 02714de3c522ce597e89976b6e03d455ff0bf872
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index f3db8b9eec..b316d1a42c 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -341,7 +341,7 @@ Remote DTS, Remote JS, `TypeRTClientRemote`, `InvocationDescriptor`, the Remote
 
 A future TUI can join the same call abstraction without changing business decorators, Remote maps, or the shape of API calls. The TUI-visible API must still be generated exclusively from `@Remote` and `@RemoteScope`; sharing a process with the Host must not allow it to bypass Remote restrictions and expose Service methods directly.
 
-TUI runtime mounting, carriers, Agent Scope association, and SRC startup wiring are outside this phase.
+TUI runtime mounting, carriers, Agent Scope association, and SRC startup wiring remain deferred outside this decision.
 
 The Web already depends on build artifacts such as `lib/client.js`, so it requires a complete `build:lib` before startup. After the Host Remote contract changes, developers rebuild the lib and then start or restart the Web. Incremental watching of the Remote contract is not implemented.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 2290b701ef..02714de3c5 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -341,7 +341,7 @@ Remote DTS、Remote JS、`TypeRTClientRemote`、`InvocationDescriptor`、Remote
 
 未来 TUI 可以在不改变业务 decorator、Remote maps 和 API 调用形状的前提下接入同一调用抽象。届时 TUI 可见的 API 仍只能由 `@Remote` 和 `@RemoteScope` 生成，不能因为它与 Host 同进程就绕过 Remote 限制直接暴露 Service 方法。
 
-TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均不属于本期实现。
+TUI 的 runtime 挂载、carrier、Agent Scope 关联和 SRC 启动接线均仍延后，不在本决策之内。
 
 Web 本身依赖 `lib/client.js` 等构建产物，因此启动 Web 前要求完整 `build:lib`。Host Remote 约定变化后，开发者需重新执行 lib build，再启动或重启 Web；系统不实现 Remote contract 的增量 watch。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
index 0b7c4c42a8..4ba2d1dd8f 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.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 .agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
-2026-08-03-pi-ai-declared-provider-catalog.md: f4b5a8565dbeb836c7aa4edb9c565f649de20f0a
-2026-08-03-pi-ai-declared-provider-catalog.zh.md: 61e2053efe4dd1234bcd319eb989d946639d2e86
+2026-08-03-pi-ai-declared-provider-catalog.md: 45de54f29e718ed1c9364b03da762700e1282e7b
+2026-08-03-pi-ai-declared-provider-catalog.zh.md: 43206bc21dfa74f6ddf0583c72dc4e8be1dbb9e5
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
index f4b5a8565d..45de54f29e 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.md
@@ -14,7 +14,7 @@ The adapter also streamed through `streamSimple` from `@earendil-works/pi-ai/com
 
 A provider route is a **declaration**, and the installed catalog is its default. `resolveProfiles` no longer checks route keys against `getBuiltinProviders()`. Instead each route resolves to a materialized model list plus the pi-ai `Provider` that serves it:
 
-- `catalog.ts` merges the installed catalog under the profile's own entries. A profile's `models` list *replaces* the route's catalog (an absent or empty list serves it unchanged), and each entry defaults its unset fields from the installed model of the same `id`. Only the fields the harness consumes are configurable — at this note's writing `id`, `name`, `contextWindow`, `maxTokens`; [[2026-08-08-pi-ai-per-model-reasoning-declarations]] later added `reasoningEfforts` and `compat`, which is also where the original "reasoning rides the installed entry or is absent" stance was revisited (a bare capability flag stays rejected; a full per-level declaration with wire spellings does not have its problem). Pricing and input modalities remain absent from the surface because nothing reads them: `replay.ts` zeroes pi-ai's cost metadata and `context.ts` keeps only text blocks. Materialization spreads the installed entry and overrides the configured fields, rather than enumerating the result: an enumerated rebuild silently drops every `Model` field this package does not model, which is how `headers` went missing from an nvidia route once already.
+- `catalog.ts` merges the installed catalog under the profile's own entries. A profile's `models` list *replaces* the route's catalog (an absent or empty list serves it unchanged), and each entry defaults its unset fields from the installed model of the same `id`. Only the fields the harness consumes are configurable — `id`, `name`, `contextWindow`, `maxTokens`; [[2026-08-08-pi-ai-per-model-reasoning-declarations]] later added `reasoningEfforts` and `compat`, which is also where the original "reasoning rides the installed entry or is absent" stance was revisited (a bare capability flag stays rejected; a full per-level declaration with wire spellings does not have its problem). Pricing and input modalities remain absent from the surface because nothing reads them: `replay.ts` zeroes pi-ai's cost metadata and `context.ts` keeps only text blocks. Materialization spreads the installed entry and overrides the configured fields, rather than enumerating the result: an enumerated rebuild silently drops every `Model` field this package does not model, which is how `headers` went missing from an nvidia route once already.
 - `provider.ts` builds the route's `Provider`. A catalog route that keeps its catalog protocol **reuses** the installed provider with `getModels()` replaced; every other route is built by `createProvider()` over a protocol table whose entries are the same `@earendil-works/pi-ai/api/*.lazy` factories pi-ai's own provider factories use. That table is narrower than pi-ai's full API set on purpose — it holds only protocols a profile can completely describe with a key, an endpoint, and headers, so Bedrock (SigV4 plus a region), Vertex (project, location, ADC), Azure (provider environment plus an api-version), and Codex (OAuth) are absent rather than offered as routes that cannot authenticate. Catalog routes still reach them through their own provider; only an explicit override is refused.
 - `adapter.ts` turns each resolution into an **immutable snapshot** — the profiles plus a `createModels()` collection holding those providers — and every operation captures a whole snapshot before its first `await`.
 - A model's **explicitly configured** `maxTokens` becomes the seam's `defaultMaxTokens`. The value inherited from the installed catalog does not: pi-ai requires `Model.maxTokens` as the model's output *capability*, while `defaultMaxTokens` is a cap the deployment chose to send on requests that name none, and materializing the former as the latter would start capping every request at a number nobody picked.
diff --git a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
index 61e2053efe..43206bc21d 100644
--- a/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-03-pi-ai-declared-provider-catalog.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 提供方路由是一份**声明**，已安装 catalog 是它的默认值。`resolveProfiles` 不再拿路由键去核对 `getBuiltinProviders()`，而是把每条路由解析成一份物化模型列表，外加服务它的 pi-ai `Provider`：
 
-- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——本 note 写就时为 `id`、`name`、`contextWindow`、`maxTokens`；[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 之后加入了 `reasoningEfforts` 与 `compat`，当初「推理（reasoning）沿用已安装条目或直接缺席」的立场也在那里被重新审视（孤立的能力布尔量仍被拒绝；带 wire 拼写的逐档位完整声明没有它那个问题）。定价与输入模态仍不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。物化时以已安装条目铺底、再覆盖已配置的字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
+- `catalog.ts` 把已安装 catalog 合并到 profile 自身条目之下。profile 的 `models` 列表*替换*该路由的 catalog（列表缺席或为空则原样服务），每个条目从同 `id` 的已安装模型继承自身未设置的字段。只有 harness 会消费的字段可配置——`id`、`name`、`contextWindow`、`maxTokens`；[[2026-08-08-pi-ai-per-model-reasoning-declarations]] 之后加入了 `reasoningEfforts` 与 `compat`，当初「推理（reasoning）沿用已安装条目或直接缺席」的立场也在那里被重新审视（孤立的能力布尔量仍被拒绝；带 wire 拼写的逐档位完整声明没有它那个问题）。定价与输入模态仍不出现在配置面，因为没有任何读取方：`replay.ts` 把 pi-ai 的成本元数据清零，`context.ts` 只保留文本块。物化时以已安装条目铺底、再覆盖已配置的字段，而不是逐字段枚举结果：枚举式重建会静默丢弃本包未建模的每一个 `Model` 字段——`headers` 就是这样从某条 nvidia 路由上消失过一次。
 - `provider.ts` 构造路由的 `Provider`。保持 catalog 协议不变的 catalog 路由会**复用**已安装提供方，只替换 `getModels()`；其余路由都由 `createProvider()` 基于一张协议表构造，表中条目正是 pi-ai 自己的提供方工厂所用的 `@earendil-works/pi-ai/api/*.lazy` factory。该表刻意窄于 pi-ai 的完整 API 集合——只保留 profile 能用密钥、端点与标头完整描述的协议，因此 Bedrock（SigV4 加 region）、Vertex（project、location、ADC）、Azure（提供方环境加 api-version）与 Codex（OAuth）不在其中，而不是被当作无法认证的路由提供出去。catalog 路由仍可经自己的 provider 抵达它们；被拒的只有显式覆盖。
 - `adapter.ts` 把每次解析变成一份**不可变快照**——profiles 加上持有这些 provider 的 `createModels()` 集合——每个操作都在自己第一个 `await` 之前整体捕获一份。
 - 模型**显式配置**的 `maxTokens` 会成为 seam 的 `defaultMaxTokens`；从已安装 catalog 继承来的那份不会：pi-ai 要求 `Model.maxTokens` 表示模型的输出*能力*，而 `defaultMaxTokens` 是部署选定、发给未点名上限的请求的那个值，把前者物化成后者会让每个请求都被一个无人选择的数字封顶。
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
index 989393cfc3..8979270e36 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.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 .agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
-2026-08-04-configuration-source-ownership.md: dc24fd4eb57294b73c3d2f8935418182726b35c2
-2026-08-04-configuration-source-ownership.zh.md: 20a8aebb626cf2282b7ddf27540be2c05eaae946
+2026-08-04-configuration-source-ownership.md: d656d329cbc5b3dfbae2561775ed1afc878cebd0
+2026-08-04-configuration-source-ownership.zh.md: 29ef3b83d18d8836b28e4c151ad44c52542b0a11
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
index dc24fd4eb5..d656d329cb 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md
@@ -66,7 +66,7 @@ The line is that these take effect with no user action, before any turn, outside
 
 **Audit an allowlist of `DSH_*` variables a `.env` may set.** Rejected: the list would have to be re-audited on every new switch, and the failure mode of forgetting is silent. Denying the namespace fails safe.
 
-**Rank a bootstrap variable below the process layer instead of rejecting it.** Rejected: `PATH` and `NODE_OPTIONS` have no meaningful "loser" behavior — a user who put one in a `.env` believes it applies, and silently ignoring it is the "my setting has no effect" failure this whole series exists to remove.
+**Rank a bootstrap variable below the process layer instead of rejecting it.** Rejected: `PATH` and `NODE_OPTIONS` have no meaningful "loser" behavior — a user who put one in a `.env` believes it applies, and silently ignoring it is the "my setting has no effect" failure this decision exists to remove.
 
 **Build the snapshot as a three-package capability seam (`environment` / `environment-local` / consumers).** Rejected as premature: the producer runs before Cordis exists and there is no second implementation to select. The repository rule is to not split preemptively.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
index 20a8aebb62..29ef3b83d1 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.zh.md
@@ -68,7 +68,7 @@ inherited process environment      (read-only, wins)
 
 **审查出一份 `.env` 可设置的 `DSH_*` 白名单。** 否决：每新增一个开关都要重新审查，而遗漏的失败模式是静默的。拒绝整个命名空间是 fail safe。
 
-**把 bootstrap 变量排在 process 层之下，而不是拒绝它。** 否决：`PATH` 和 `NODE_OPTIONS` 没有有意义的「输了之后」行为——把它写进 `.env` 的用户认为它生效，而静默忽略正是整个系列要消除的那种「我的设置没有效果」。
+**把 bootstrap 变量排在 process 层之下，而不是拒绝它。** 否决：`PATH` 和 `NODE_OPTIONS` 没有有意义的「输了之后」行为——把它写进 `.env` 的用户认为它生效，而静默忽略正是本决策要消除的那种「我的设置没有效果」。
 
 **把快照做成三包能力 seam（`environment` / `environment-local` / 消费方）。** 作为过早拆分而否决：生产方在 Cordis 存在之前就运行，也没有第二个实现需要选择。仓库规则是不要预先拆分。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
index 141a08a5b6..c34594bd36 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.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 .agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
-2026-08-04-declaring-a-provider-from-the-models-page.md: 53996e488c467e00754837b83b7a33994d4813ee
-2026-08-04-declaring-a-provider-from-the-models-page.zh.md: 3a952aa0a02e0b2906bf16bcc46d14a8f7f71bc4
+2026-08-04-declaring-a-provider-from-the-models-page.md: 44441da5427dbcd3f0651c2c137a5132ff6d968b
+2026-08-04-declaring-a-provider-from-the-models-page.zh.md: 974c4fa5be0893e8fdf6a9142877a8b966708dab
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
index 53996e488c..44441da542 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.md
@@ -26,7 +26,7 @@ The protocol choices come from the namespace's **own schema**, read through the
 
 **Declare a provider through `ProviderEditor` with extra fields.** One card instead of two, but the editor is addressed by `settingsPath`, and a route being named has no path yet. Recomputing the path per keystroke would remount the card and discard the draft; deferring it would mean the editor's whole write path no longer described what it was editing.
 
-**Add a wire field for the protocol list.** Explicit, and the obvious first instinct. But the settings schema already crosses the wire and already contains the union, so a second copy could disagree with the first — and the one the adapter enforces is the schema.
+**Add a wire field for the protocol list.** Explicit. But the settings schema already crosses the wire and already contains the union, so a second copy could disagree with the first — and the one the adapter enforces is the schema.
 
 **Fetch against the stored profile instead of the live form.** No key would leave the form for an unsaved provider. But the flow that needs fetching most is the one where nothing is stored yet, and a form whose endpoint was edited would quietly interrogate the old one.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
index 3a952aa0a0..974c4fa5be 100644
--- a/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-04-declaring-a-provider-from-the-models-page.zh.md
@@ -26,7 +26,7 @@ Status: implemented
 
 **在 `ProviderEditor` 上加字段来声明提供方。** 两张卡片变一张，但编辑器由 `settingsPath` 寻址，而正在被命名的路由还没有路径。逐次按键重算路径会让卡片重新挂载并丢掉草稿；推迟计算则意味着编辑器的整条写入路径不再描述它正在编辑的东西。
 
-**为协议列表新增一个协议字段。** 显式，也是最直觉的第一反应。但 settings schema 本来就会跨越协议层、本来就含有那个 union，因此第二份副本可能与第一份不一致——而适配器强制执行的是 schema 那一份。
+**为协议列表新增一个协议字段。** 显式。但 settings schema 本来就会跨越协议层、本来就含有那个 union，因此第二份副本可能与第一份不一致——而适配器强制执行的是 schema 那一份。
 
 **针对已存 profile 而非实时表单发起获取。** 对尚未保存的提供方来说，密钥就不会离开表单。但最需要获取的恰恰是「什么都还没存」的那条流程，而端点已修改的表单会悄悄去询问旧地址。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
index c12ec3a68c..ae92bdeafa 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.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 .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
-2026-08-06-subagent-list-identity-projection.md: 727c9113fc95a85e6c2732902289a49a76ee8a8d
-2026-08-06-subagent-list-identity-projection.zh.md: c499247a1bd6bd4c971638a29e82f35b16b64690
+2026-08-06-subagent-list-identity-projection.md: db7ff085382c52fd5adbe5beab42a84524a64d3f
+2026-08-06-subagent-list-identity-projection.zh.md: a6b5cea851d284fa5c2a60f830913900576dfb38
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
index 727c9113fc..db7ff08538 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
@@ -16,7 +16,7 @@ The root cause is that the [durable-subagent-catalog decision](../feature/2026-0
 
 mode and label are folded by the new `subagent` projection unit (pure identity, two arms), and the unit is the sole authority over the fold rules; `listChildren` no longer depends on session-query — enumeration is a subagent-owned live-preferred merge, and value retrieval walks a three-rung compute-and-discard ladder: a live child synchronously reads the registry's existing watermark cache (zero log reads); a cold child first asks the optional `sessionProjectionCache` checkpoint, and a served identity that passes the seq gate is final; otherwise it pays one full `persistence.inspect` read plus one `registry.restore` fold. No index, no cache of its own, no write-back.
 
-There are three families of escape from the per-child scan: promote mode/label into the header (the write path pays); build a durable derivation for the projection (a checkpoint ladder, or values landed during query-index rebuild with read-side reconciliation); or compute at read time (live from the watermark cache, cold from one full read). This note takes the third. "Values landed with the query index" was once this note's settled direction and was under construction for a time, then retired wholesale: query infrastructure was forced to learn domain vocabulary while the sole consumer is satisfied by read-time computation — the live child's zero reads come for free from session-projection's existing watermark cache, and the cold child's single full read is explicitly accepted as compute-and-discard. The first two routes and the retirement rationale are detailed under Alternatives considered.
+There are three families of escape from the per-child scan: promote mode/label into the header (the write path pays); build a durable derivation for the projection (a checkpoint ladder, or values landed during query-index rebuild with read-side reconciliation); or compute at read time (live from the watermark cache, cold from one full read). This note takes the third. "Values landed with the query index" was retired wholesale: query infrastructure was forced to learn domain vocabulary while the sole consumer is satisfied by read-time computation — the live child's zero reads come for free from session-projection's existing watermark cache, and the cold child's single full read is explicitly accepted as compute-and-discard. The first two routes and the retirement rationale are detailed under Alternatives considered.
 
 Key points:
 
@@ -147,19 +147,19 @@ Consuming surfaces: diagnostic handling across wire, tool, and GUI **stays entir
 
 **mode/label into SessionHeader.** The strongest zero-read guarantee — rows form from the header alone. But a header shape change propagates into both persistence backends and the header compatibility check; SQLite rejects pre-existing data outright, and JSONL pre-existing data can only degrade to unknown or be backfilled. Read-time computation's answer for pre-existing data is "one `inspect` computation on first listing", touching no durable format.
 
-**The projection-cache ladder (v3 draft: `cachedSnapshot ?? coldSnapshot` plus fail-soft write-back).** The mechanism works — session-projection-cache's checkpoint ladder is designed for cold reads in the first place. But checkpoint write-back is a whole list-driven body of derived-data persistence and invalidation orchestration (floor/identity/putSoft); what was rejected is that orchestration as the primary mechanism. The settled three-rung ladder later reuses this cache opportunistically, read-only, as its second rung — no write-back, no orchestration, skipped when absent.
+**The projection-cache ladder (`cachedSnapshot ?? coldSnapshot` plus fail-soft write-back).** The mechanism works — session-projection-cache's checkpoint ladder is designed for cold reads in the first place. But checkpoint write-back is a whole list-driven body of derived-data persistence and invalidation orchestration (floor/identity/putSoft); what was rejected is that orchestration as the primary mechanism. The settled three-rung ladder later reuses this cache opportunistically, read-only, as its second rung — no write-back, no orchestration, skipped when absent.
 
 **A bounded-read primitive on persistence to rescue pre-existing data.** Opens a new persistence primitive for a one-time problem; superseded by the read-time `inspect` full read — the full read the first time pre-existing data is listed is itself the value retrieval.
 
-**Optional mode/label on list rows (one v4 draft).** Healthy data is always computable; optionality merely spills garbage-data handling complexity onto every consumer — each consuming surface has to grow filter branches and an unknown display state. The strong contract plus omit-when-uncomputable is cleaner.
+**Optional mode/label on list rows.** Healthy data is always computable; optionality merely spills garbage-data handling complexity onto every consumer — each consuming surface has to grow filter branches and an unknown display state. The strong contract plus omit-when-uncomputable is cleaner.
 
-**Deleting diagnostic rows outright (one v5 draft).** Deletion turns corpus-corruption visibility into rows silently vanishing, and wire/tool/GUI would each have to absorb contract and snapshot changes; retention only asks the list side to derive the classification from projection-value absence and activity, at zero cost. That damaged, dead child sessions in the corpus must be visible is the original motivation for diagnostics' existence, and with retention the consuming surfaces stay wholly unchanged.
+**Deleting diagnostic rows outright.** Deletion turns corpus-corruption visibility into rows silently vanishing, and wire/tool/GUI would each have to absorb contract and snapshot changes; retention only asks the list side to derive the classification from projection-value absence and activity, at zero cost. That damaged, dead child sessions in the corpus must be visible is the original motivation for diagnostics' existence, and with retention the consuming surfaces stay wholly unchanged.
 
-**A registry computation failure channel (per-unit fault tolerance plus a supplementary `failures` field).** To report corruption and unrecognized versions to consumers, we once considered having the registry catch unit exceptions and attach a per-key failure state beside the snapshot. Rejected: a failure is not a value and needs no channel — a unit never throws, absence is itself the signal, worst case the computation comes back empty, and how that is presented is the consumer's problem. The discussion of this route left one independent observation behind: the vendored Cordis `emit` ([vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)) catches nothing a listener throws, so with the projection driver hanging off `session/event`, a unit exception would escape along emit — which adds weight to the "a unit never throws" discipline, but fixing emit fault tolerance is outside this note's scope.
+**A registry computation failure channel (per-unit fault tolerance plus a supplementary `failures` field).** To report corruption and unrecognized versions to consumers, the registry would catch unit exceptions and attach a per-key failure state beside the snapshot. Rejected: a failure is not a value and needs no channel — a unit never throws, absence is itself the signal, worst case the computation comes back empty, and how that is presented is the consumer's problem. An independent observation: the vendored Cordis `emit` ([vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)) catches nothing a listener throws, so with the projection driver hanging off `session/event`, a unit exception would escape along emit — which adds weight to the "a unit never throws" discipline, but fixing emit fault tolerance is outside this note's scope.
 
-**Values landed with query index preparation (the v4/v5 settled design, built for a time).** Projection values folded into session index rows during the sqlite backend's reconciliation rebuild, for zero log reads in the steady read state; the `projectionsFor` bulk read face, the invalidation reconciliation of row values stored against the `(key → stateVersion)` registration set, and the SCHEMA bump were all actually built. Retired wholesale: the direction was backwards — query infrastructure was forced to learn domain vocabulary (projection columns, registration-set reconciliation) while the sole consumer, the subagent list, is satisfied by read-time computation; with consumers down to zero, this derived persistence has no reason to exist. `SESSION_QUERY_PROJECTIONS_UNAVAILABLE` was deleted along with the read face.
+**Values landed with query index preparation.** Projection values folded into session index rows during the sqlite backend's reconciliation rebuild, for zero log reads in the steady read state: the `projectionsFor` bulk read face, the invalidation reconciliation of row values stored against the `(key → stateVersion)` registration set, and the SCHEMA bump. Retired wholesale: the direction was backwards — query infrastructure was forced to learn domain vocabulary (projection columns, registration-set reconciliation) while the sole consumer, the subagent list, is satisfied by read-time computation; with consumers down to zero, this derived persistence has no reason to exist. `SESSION_QUERY_PROJECTIONS_UNAVAILABLE` was deleted along with the read face.
 
-**Subagent hand-rolled parsing plus an in-process memo plus creation seeding (v6 draft).** To excise the session-query dependency, we once considered the subagent package parsing descriptor events itself, avoiding repeated full reads with an in-process memo, and seeding initial values at creation. Superseded by the v7 ladder: live goes through the `sessionProjections` watermark cache and cold through `registry.restore`, reusing the registry's single fold authority — no second copy of descriptor-interpretation logic appears, and no process-state cache or seeding ordering is introduced.
+**Subagent hand-rolled parsing plus an in-process memo plus creation seeding.** To excise the session-query dependency, the subagent package would parse descriptor events itself, avoid repeated full reads with an in-process memo, and seed initial values at creation. Superseded by the shipped ladder: live goes through the `sessionProjections` watermark cache and cold through `registry.restore`, reusing the registry's single fold authority — no second copy of descriptor-interpretation logic appears, and no process-state cache or seeding ordering is introduced.
 
 **DeepReadonly on the session-query output surface (a read-path overhaul experiment).** Make the public query outputs deeply readonly to pin immutable borrowing at the type level. Rejected on evidence: 3 TS2589 occurrences (excessively deep type instantiation) plus 17 sites of array-position contagion (consumers' array methods and spread sites forced to follow); deep immutability is guaranteed by core/session's runtime deep freeze, and that read-path overhaul is not part of this note.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
index c499247a1b..a6b5cea851 100644
--- a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠，unit 是折叠规则的唯一权威；`listChildren` 不再依赖 session-query——枚举是 subagent 自管的 live-preferred 合并，取值走三级"算完即止"阶梯：live child 同步读注册表的既有水位缓存（零日志读）；cold child 先问可选的 `sessionProjectionCache` checkpoint，取到过 seq 门的身份即定值；否则一次 `persistence.inspect` 整读加 `registry.restore` 折叠。无索引、不自建缓存、无回写。
 
-消除逐 child 扫描的出路有三类：把 mode/label 提升进 header（写路承担）；为投影建持久派生（checkpoint 阶梯，或随查询索引重建落值、读端对账）；读时现算（live 走水位缓存，cold 一次整读）。本记录取第三条。"值随查询索引落库"曾是本记录的定稿方向并一度施工，最终整体退役：查询基础设施被迫认识领域词汇，而唯一消费方读时现算即可满足——live child 的零读由 session-projection 既有水位缓存白拿，cold child 的一次整读被"算完即止"显式接受。前两条与退役理由详见考虑过的替代方案一节。
+消除逐 child 扫描的出路有三类：把 mode/label 提升进 header（写路承担）；为投影建持久派生（checkpoint 阶梯，或随查询索引重建落值、读端对账）；读时现算（live 走水位缓存，cold 一次整读）。本记录取第三条。"值随查询索引落库"已整体退役：查询基础设施被迫认识领域词汇，而唯一消费方读时现算即可满足——live child 的零读由 session-projection 既有水位缓存白拿，cold child 的一次整读被"算完即止"显式接受。前两条与退役理由详见考虑过的替代方案一节。
 
 要点：
 
@@ -147,19 +147,19 @@ export type SubagentListEntry =
 
 **mode/label 进 SessionHeader。** 零读保证最强——列表只看 header 就能成行。但 header 形状变更传导两个 persistence backend 与 header 兼容检查；SQLite 存量直接拒收，JSONL 存量只能 unknown 降级或 backfill。读时现算对存量的答案是"第一次列表一次 `inspect` 现算"，不碰持久格式。
 
-**projection-cache 阶梯（v3 稿：`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的第三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
+**projection-cache 阶梯（`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的第三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
 
 **给 persistence 加有界读原语抢救存量。** 为一次性问题新开 persistence 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
 
-**list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强约定加算不出即 omit 更干净。
+**list 行 mode/label 可选化。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强约定加算不出即 omit 更干净。
 
-**彻底删除 diagnostic 行（v5 一稿）。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担约定与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
+**彻底删除 diagnostic 行。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担约定与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
 
-**registry 计算失败通道（per-unit 容错加 `failures` 附加字段）。** 为把损坏、版本不认识报告给消费方，曾考虑让 registry 捕获 unit 异常并在 snapshot 旁附 per-key 失败态。被否：failure 不是值，也不必是通道——unit 永不抛错，缺席本身就是信号，"大不了算出来没有"，如何呈现是消费方要考虑的事。该路线讨论顺带留下一个独立观察：vendor cordis 的 `emit`（[vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)）对 listener 抛错零捕获，投影驱动挂在 `session/event` 上时 unit 异常会沿 emit 逃逸——这加重了"unit 永不抛错"纪律的分量，但 emit 容错的修复不属于本记录范围。
+**registry 计算失败通道（per-unit 容错加 `failures` 附加字段）。** 为把损坏、版本不认识报告给消费方，由 registry 捕获 unit 异常并在 snapshot 旁附 per-key 失败态。被否：failure 不是值，也不必是通道——unit 永不抛错，缺席本身就是信号，"大不了算出来没有"，如何呈现是消费方要考虑的事。一个独立观察：vendor cordis 的 `emit`（[vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)）对 listener 抛错零捕获，投影驱动挂在 `session/event` 上时 unit 异常会沿 emit 逃逸——这加重了"unit 永不抛错"纪律的分量，但 emit 容错的修复不属于本记录范围。
 
-**值随 query 索引 preparation 落库（v4/v5 定稿，一度施工）。** 投影值在 sqlite backend 的对账重建里折叠落进 session 索引行，读稳态零日志；`projectionsFor` 批量读面、行值随 `(key → stateVersion)` 注册集存储的失效对账与 SCHEMA bump 均已施工过。整体退役：方向反了——查询基础设施被迫认识领域词汇（投影列、注册集对账），而唯一消费方 subagent 列表读时现算即可满足；消费方归零后，这套派生持久化没有存在理由。`SESSION_QUERY_PROJECTIONS_UNAVAILABLE` 随读面一并删除。
+**值随 query 索引 preparation 落库。** 投影值在 sqlite backend 的对账重建里折叠落进 session 索引行，读稳态零日志：`projectionsFor` 批量读面、行值随 `(key → stateVersion)` 注册集存储的失效对账与 SCHEMA bump。整体退役：方向反了——查询基础设施被迫认识领域词汇（投影列、注册集对账），而唯一消费方 subagent 列表读时现算即可满足；消费方归零后，这套派生持久化没有存在理由。`SESSION_QUERY_PROJECTIONS_UNAVAILABLE` 随读面一并删除。
 
-**subagent 手工 parse 加进程 memo 加创建播种（v6 稿）。** 为摘除 session-query 依赖，曾考虑 subagent 自己解析描述符事件、以进程内 memo 避免重复整读、创建时播种初值。被 v7 阶梯取代：live 走 `sessionProjections` 水位缓存、cold 走 `registry.restore`，复用 registry 这一份折叠权威，不再出现第二份描述符解释逻辑，也不引入进程态缓存与播种时序。
+**subagent 手工 parse 加进程 memo 加创建播种。** 为摘除 session-query 依赖，由 subagent 包自己解析描述符事件、以进程内 memo 避免重复整读、创建时播种初值。被已交付的阶梯取代：live 走 `sessionProjections` 水位缓存、cold 走 `registry.restore`，复用 registry 这一份折叠权威，不再出现第二份描述符解释逻辑，也不引入进程态缓存与播种时序。
 
 **session-query 输出面 DeepReadonly（读路径改造实验）。** 公开查询输出深只读化，以在类型层面钉死不可变借用。实证否决：3 处 TS2589（类型实例化过深）加 17 处数组位传染（消费方数组方法与展开处被迫跟改）；深层不可变由 core/session 的运行时深冻结保证，该读路径改造未纳入本记录。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
index 082158c75c..852d3816e2 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.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 .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
-2026-07-28-themed-scrollbars-and-reserved-gutter.md: ba3d9d3c94cf9a775c43c14e292187b3a43935fe
-2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 1cf505e96122a66705fe42fc79757ac390ebf0ef
+2026-07-28-themed-scrollbars-and-reserved-gutter.md: 8ad5d801358823576c37d6b6824d7ce3fdcdac11
+2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: d6d2c64703df95ea2a4ff79435512eabdb3d2f81
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
index ba3d9d3c94..8ad5d80135 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
@@ -22,7 +22,7 @@ The two renderings are mutually exclusive, and the exclusion is enforced rather
 
 Both paths read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. `transparent` is the pair's other legal target, added when the sidebar's bars [started following the pointer](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md); the gate below admits those two and nothing else. The mechanically discoverable subset is owned by `packages/client/ui-theme/tests/scrollbar-styles.spec.ts`: any sheet that both scrolls and paints an elevated surface must rebind, so this note no longer maintains a complete surface inventory. Most declare the pair on the elevated card rather than on the scrolling descendant, because elevation belongs to the surface and custom properties inherit to whichever child actually scrolls.
 
-Four surfaces — `Menu`, `InputBar`, `QuestionComposer`, and `TodoPanel` — were missed in the first implementation and found in review, which is why the per-sheet rebinding contract is checked mechanically rather than by inspection.
+Four surfaces — `Menu`, `InputBar`, `QuestionComposer`, and `TodoPanel` — were initially missed, which is why the per-sheet rebinding contract is checked mechanically rather than by inspection.
 
 The elevated set is resolved from the palette's own dark elevation ladder — the surface tokens whose dark value lands on `bg-layer-2` or `bg-layer-3`, which is the step the l1/l2 split encodes. Deriving it instead from the sheets that already rebind was the first attempt and is unsound: such a set can only confirm what someone already remembered, and a surface nobody has rebound yet — exactly the case the check exists for — defines itself as unelevated. `--dsw-specific-tip` proved it, resolving to the menu surface's rung while the todo panel scrolled on it unrebound and the derived check stayed green.
 
@@ -44,7 +44,7 @@ The gutter and the sheet's `::-webkit-scrollbar` width are jointly necessary aga
 
 **Declare the properties once and let them inherit.** Fewer matched elements, and it breaks the rebinding contract — inheritance carries the substituted color, not the variable reference, so an elevated surface could not retint its own scrollbar. It is also incomplete on its own terms, since `scrollbar-width` does not inherit.
 
-**Declare the standard properties and the pseudo-elements unconditionally, without the `@supports` gate.** This is what the change originally shipped, and review caught it. Measured in chromium on probe elements with `scrollbar-gutter: stable` so the band is observable: an 8px `::-webkit-scrollbar` alone reserved a 30px band (the sheet's width plus the UA's buttons), and adding `scrollbar-width: thin` to the same element dropped it to the 10px `thin` reserves — the pseudo-element rules were being discarded, not merged. Every `::-webkit-scrollbar-thumb:hover` rule went with them, so both hover tokens and all four elevated surfaces' hover rebinds were dead code on the engine most users run.
+**Declare the standard properties and the pseudo-elements unconditionally, without the `@supports` gate.** Measured in chromium on probe elements with `scrollbar-gutter: stable` so the band is observable: an 8px `::-webkit-scrollbar` alone reserved a 30px band (the sheet's width plus the UA's buttons), and adding `scrollbar-width: thin` to the same element dropped it to the 10px `thin` reserves — the pseudo-element rules were being discarded, not merged. Every `::-webkit-scrollbar-thumb:hover` rule went with them, so both hover tokens and all four elevated surfaces' hover rebinds were dead code on the engine most users run.
 
 **Gate the WebKit rules too, behind `@supports selector(::-webkit-scrollbar)`.** Symmetrical to read, and wrong in one direction: it would hide the rules from an engine that implements the pseudo-elements but not `selector()`, which is the pre-16.4 Safari the ungated form serves correctly. Unknown selectors are already dropped, so the gate adds no protection to pay for that.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
index 1cf505e961..d6d2c64703 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 两条路径都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定约定，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。这组变量另一个合法的目标是 `transparent`，它随侧边栏滚动条[改为跟随指针](../feature/2026-08-04-pointer-revealed-sidebar-scrollbars.md)一并引入；下文的门禁只接受这两种目标。可由机械检查发现的子集归 `packages/client/ui-theme/tests/scrollbar-styles.spec.ts` 所有：任何既滚动又绘制抬升表面的样式表都必须重新绑定，因此本 note 不再维护完整的表面清单。多数把这组变量声明在抬升卡片上而非滚动的后代元素上，因为抬升层级属于这个表面，而自定义属性会继承到真正滚动的那个子元素。
 
-`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面在最初的实现里被漏掉、由评审发现，因此逐样式表的重新绑定约定由机械检查而非人工审阅把关。
+`Menu`、`InputBar`、`QuestionComposer` 与 `TodoPanel` 这四个表面最初被漏掉，因此逐样式表的重新绑定约定由机械检查而非人工审阅把关。
 
 抬升表面集合是从调色板自身的暗色抬升阶梯解析出来的——暗色取值落在 `bg-layer-2` 或 `bg-layer-3` 上的那些表面 token，而这一档正是 l1/l2 之分所编码的层级差。最初的做法是从已经做了重新绑定的样式表反向推导，那是不成立的：这样得到的集合只能确认别人已经记得的部分，而尚无人重新绑定的表面——恰恰就是这项检查存在的理由——会把自己定义成「非抬升」。`--dsw-specific-tip` 证明了这一点：它解析到与菜单表面相同的那一档，待办面板在它上面滚动却没有重新绑定，而推导式的检查依然是绿的。
 
@@ -44,7 +44,7 @@ Status: implemented
 
 **只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定约定——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
 
-**不加 `@supports` 门禁，无条件同时声明标准属性与伪元素。** 这正是本次变更最初提交的形态，被评审发现。在 chromium 中于带 `scrollbar-gutter: stable`（使条带可观测）的探针元素上实测：单独一条 8px 的 `::-webkit-scrollbar` 预留出 30px 条带（样式表指定的宽度加上浏览器自带的按钮），而给同一元素加上 `scrollbar-width: thin` 后降到 `thin` 所预留的 10px——说明伪元素规则是被丢弃，而不是被合并。全部 `::-webkit-scrollbar-thumb:hover` 规则随之失效，因此两个 hover token 与四处抬升表面的 hover 重新绑定，在多数用户实际使用的引擎上都是死代码。
+**不加 `@supports` 门禁，无条件同时声明标准属性与伪元素。** 在 chromium 中于带 `scrollbar-gutter: stable`（使条带可观测）的探针元素上实测：单独一条 8px 的 `::-webkit-scrollbar` 预留出 30px 条带（样式表指定的宽度加上浏览器自带的按钮），而给同一元素加上 `scrollbar-width: thin` 后降到 `thin` 所预留的 10px——说明伪元素规则是被丢弃，而不是被合并。全部 `::-webkit-scrollbar-thumb:hover` 规则随之失效，因此两个 hover token 与四处抬升表面的 hover 重新绑定，在多数用户实际使用的引擎上都是死代码。
 
 **给 WebKit 规则也加门禁，写成 `@supports selector(::-webkit-scrollbar)`。** 读起来对称，但在一个方向上是错的：它会对「实现了伪元素但不支持 `selector()`」的引擎隐藏这些规则，而那正是不加门禁时能被正确服务的 16.4 之前的 Safari。未知选择器本就会被丢弃，因此这道门禁不提供任何能抵偿该代价的保护。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
index 91dd4d352d..0e0b722c8e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.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 .agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md
-2026-07-30-approval-panel-command-cap.md: 1e4b75c106b71605a004ef35301445da76ec8cf0
-2026-07-30-approval-panel-command-cap.zh.md: 963dca00a6eda6c3bfd145828c8d7553625a4511
+2026-07-30-approval-panel-command-cap.md: 1d74d790299522a0f1e6b23f342cd10b35192d27
+2026-07-30-approval-panel-command-cap.zh.md: d31db819144cd4ce2099bf5d5f025b2e8df0e0e1
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md
index 1e4b75c106..1d74d79029 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.md
@@ -47,6 +47,6 @@ Reproducing the off-screen buttons needs a card taller than the scrollport, not
 
 The geometry block and the golden are replay-only, so record mode reaches the fixture write instead of aborting on layout.
 
-The scenario keeps exactly one golden — the waiting panel — and asserts the answered state on the world instead (the decided outcome, the file the escalated command wrote, `DONE`, the panel gone, the composer re-enabled). An answered-transcript golden was recorded first and failed on Linux CI: the denied first attempt renders the OS's own refusal, and that text is platform-specific (`bash: notes.txt: Operation not permitted` on macOS against `bash: line 1: notes.txt: Read-only file system` on Linux). Any scenario whose transcript contains a sandbox-denied command inherits that, so the denial belongs in assertions, never in a golden.
+The scenario keeps exactly one golden — the waiting panel — and asserts the answered state on the world instead (the decided outcome, the file the escalated command wrote, `DONE`, the panel gone, the composer re-enabled). An answered-transcript golden cannot hold: the denied first attempt renders the OS's own refusal, and that text is platform-specific (`bash: notes.txt: Operation not permitted` on macOS against `bash: line 1: notes.txt: Read-only file system` on Linux). Any scenario whose transcript contains a sandbox-denied command inherits that, so the denial belongs in assertions, never in a golden.
 
 The panel ships as a client-module bundle: `pnpm run build:web` alone does not pick up a change to `ApprovalPanel.module.css` or a new `data-` hook in `ApprovalPanel.tsx` — the package build must run first, or the browser lane asserts against an older client than the tree.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
index 963dca00a6..d31db81914 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-approval-panel-command-cap.zh.md
@@ -47,6 +47,6 @@ Status: implemented
 
 几何断言块与 golden 仅在回放模式下执行，这样录制模式才能走到写入 fixture（测试前置数据）那一步，而不是在布局检查处中断。
 
-该场景只保留一份 golden——等待中的面板；回应之后的状态改为对世界作断言（决策结果、越权命令写出的那个文件、`DONE`、面板消失、输入框重新可用）。最初还录了一份"已回应 transcript"的 golden，它在 Linux CI 上失败了：第一次被拒绝的尝试渲染的是操作系统自己的拒绝文本，而这段文本因平台而异（macOS 为 `bash: notes.txt: Operation not permitted`，Linux 为 `bash: line 1: notes.txt: Read-only file system`）。任何 transcript 中含有被沙箱拒绝命令的场景都会继承这一点，因此这类拒绝只能进断言，绝不能进 golden。
+该场景只保留一份 golden——等待中的面板；回应之后的状态改为对世界作断言（决策结果、越权命令写出的那个文件、`DONE`、面板消失、输入框重新可用）。一份"已回应 transcript"的 golden 立不住：第一次被拒绝的尝试渲染的是操作系统自己的拒绝文本，而这段文本因平台而异（macOS 为 `bash: notes.txt: Operation not permitted`，Linux 为 `bash: line 1: notes.txt: Read-only file system`）。任何 transcript 中含有被沙箱拒绝命令的场景都会继承这一点，因此这类拒绝只能进断言，绝不能进 golden。
 
 该面板以客户端模组包的形式发布：单跑 `pnpm run build:web` 不会带上对 `ApprovalPanel.module.css` 的改动，也不会带上 `ApprovalPanel.tsx` 中新增的 `data-` 钩子——必须先执行包构建，否则浏览器测试通道会对着一个比工作树更旧的客户端做断言。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
index 00fec6c8db..8245d59db4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.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 .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
-2026-07-30-web-transcript-log-ordered-projection.md: f2b7c3830b585db619f69046917e07a0b6ff6832
-2026-07-30-web-transcript-log-ordered-projection.zh.md: 77787f9613b64a35e79a8667c6598de5a20ff400
+2026-07-30-web-transcript-log-ordered-projection.md: 1c65eeec0fbf0dc550043bb809ae8d7310f0602b
+2026-07-30-web-transcript-log-ordered-projection.zh.md: 67bb41adde46ba7112896404ddc92a05f08f7aca
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
index f2b7c3830b..1c65eeec0f 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.md
@@ -45,7 +45,7 @@ The divergence from the terminal is therefore narrow: both frontends recognize a
 
 ## What #835's positional anchors were for, and why they are dissolved rather than lost
 
-The unmerged manual-compaction-queueing branch fixes the same interleaving bug by recording a per-event anchor — the surface tail at append time — and retargeting shadowed anchors onto the checkpoint. That mechanism exists to make positional anchors survive surface **reordering**. The human transcript is never re-ordered, so anchors have nothing to retarget: the precondition is removed, not the fix discarded. The mechanism is absent from this base and is not authored here.
+The unmerged manual-compaction-queueing branch fixes the same interleaving bug by recording a per-event anchor — the surface tail at append time — and retargeting shadowed anchors onto the checkpoint. That mechanism exists to make positional anchors survive surface **reordering**. The human transcript is never re-ordered, so anchors have nothing to retarget: the precondition is removed, not the fix discarded. The mechanism does not exist in this codebase.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
index 77787f9613..67bb41adde 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md
@@ -45,7 +45,7 @@ const COMPACT_PLUGIN: CompactCheckpointSource['plugin'] = 'compact'
 
 ## #835 的位置锚点是为什么而存在，以及为什么它是被溶解而非丢失
 
-尚未合并的排队式手动压缩分支用另一种方式修同一个交错缺陷：为每个事件记录一个锚点——追加时的 surface 尾部——并把被遮蔽的锚点重定向到检查点上。该机制的存在是为了让位置锚点在 surface **重排**中存活。人类对话记录永不被重排，因此锚点没有任何东西需要重定向：前提被移除，修复并未被丢弃。该机制在本基线上并不存在，本次也不撰写它。
+尚未合并的排队式手动压缩分支用另一种方式修同一个交错缺陷：为每个事件记录一个锚点——追加时的 surface 尾部——并把被遮蔽的锚点重定向到检查点上。该机制的存在是为了让位置锚点在 surface **重排**中存活。人类对话记录永不被重排，因此锚点没有任何东西需要重定向：前提被移除，修复并未被丢弃。该机制在本代码库中并不存在。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
index 7449d1b5fc..608d267824 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.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 .agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
-2026-07-31-fail-loud-releases-the-terminal.md: 5fe812e5fe64a1fab8ba9808d87f3581b6f5b206
-2026-07-31-fail-loud-releases-the-terminal.zh.md: 407161d112cbbb6f476773f6f7e21c2ce820956e
+2026-07-31-fail-loud-releases-the-terminal.md: d5a97d73ec60897a3a40f3c99417e43de190af9c
+2026-07-31-fail-loud-releases-the-terminal.zh.md: 271769d32ea1dd66c698a65b35461f51042b7efb
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
index 5fe812e5fe..d5a97d73ec 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.md
@@ -56,4 +56,4 @@ The guarantee belongs to whichever bin owns the terminal: a surface that grabs t
 
 Those fake-process tests cannot observe the two failure modes that matter most — process exit code with a real event loop, and terminal state after exit — so the regression lives in `apps/cli/tests/tui-keyless-smoke.e2e.ts`. It boots the shipped tree in a real PTY over `fixtures/tui-invalid-provider.cordis.yml` (a list-shaped `providers`, the mistake users actually make), expects exit 1, and asserts the captured bytes contain both the labelled boot rejection (`dsh: plugin tree failed to load:`) and `ESC[?2004l`. The same case pins the boot path end to end: it caught the [HMR initial-scan boot deadlock](2026-08-03-hmr-initial-scan-boot-deadlock.md) that silently exited 13 with the terminal stranded.
 
-Testing policy requires a PTY case whenever terminal teardown changes, and this is it. The `/exit` path keeps its existing assertion that the same reset appears on a clean exit.
+The `/exit` path keeps its existing assertion that the same reset appears on a clean exit.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
index 407161d112..271769d32e 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-31-fail-loud-releases-the-terminal.zh.md
@@ -56,4 +56,4 @@ Loader 并发挂载各个条目，因此条目失败的顺序并不等于启动
 
 这些基于假进程的测试无法观测到最关键的两种失败形态——真实事件循环下的进程退出码，以及退出之后的终端状态——因此回归用例放在 `apps/cli/tests/tui-keyless-smoke.e2e.ts`。它在真实 PTY 中以 `fixtures/tui-invalid-provider.cordis.yml`（`providers` 为列表形状，正是用户真实会犯的错误）启动出厂配置树，期望退出码为 1，并断言捕获到的字节流同时包含带标签的启动 rejection（`dsh: plugin tree failed to load:`）与 `ESC[?2004l`。同一用例端到端钉住了启动路径：正是它发现了以 13 静默退出、终端状态未被恢复的 [HMR（热模块替换）初始扫描启动死锁](2026-08-03-hmr-initial-scan-boot-deadlock.md)。
 
-测试规范要求：只要改动终端拆卸，就必须有 PTY 用例——这就是它。`/exit` 路径保留其原有断言，确认正常退出时同样会出现该重置序列。
+`/exit` 路径保留其原有断言，确认正常退出时同样会出现该重置序列。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
index c20fdb52b5..dd607a6dfc 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.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 .agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
-2026-08-06-api-key-format-validation.md: f404a3bed728f9917f794f9c06f1a9dad32e64c8
-2026-08-06-api-key-format-validation.zh.md: a94d7eb577a84e7adf440c034aebe603faec7f64
+2026-08-06-api-key-format-validation.md: 356891c01c003f26d8edd092ebde8887e17d2448
+2026-08-06-api-key-format-validation.zh.md: 156e3141549c94f609d68f1937f30202c40751c6
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
index f404a3bed7..356891c01c 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.md
@@ -80,7 +80,7 @@ The client cannot import any of this: client packages reference only client pack
 
 A malformed key is refused at the field that holds it, and a malformed stored key fails as `INVALID_CREDENTIAL` with a message naming where to fix it and no fragment of the key. Because that code sits outside `DEFAULT_RETRYABLE_CODES`, a deterministic credential fault is no longer retried three times as a transport blip. `llm-pi-ai` discovery reports an illegal probe key as a credential fault instead of an unreachable endpoint.
 
-The shape heuristic can refuse a real key. The first draft matched any upper-case identifier followed by `=`, which review showed was broader than intended: an all-upper-case base64 key ending in padding (`ABCD==`) matched an assignment it does not resemble. Requiring a non-`=` character after the separator excludes padding, since base64 only ever pads at the end. What remains — an upper-case name, one `=`, then a value — is a shape no known provider issues, and the rule runs only in the browser, so a user who still hits it can set the credential through the environment. The residual cost is a confusing refusal for a key nobody has yet reported.
+The shape heuristic can refuse a real key. Matching any upper-case identifier followed by `=` would be broader than intended: an all-upper-case base64 key ending in padding (`ABCD==`) would match an assignment it does not resemble. Requiring a non-`=` character after the separator excludes padding, since base64 only ever pads at the end. What remains — an upper-case name, one `=`, then a value — is a shape no known provider issues, and the rule runs only in the browser, so a user who still hits it can set the credential through the environment. The residual cost is a confusing refusal for a key nobody has yet reported.
 
 Restricting to printable ASCII is stricter than the transport requires: a header value may carry `\x80`–`\xFF`. Admitting latin-1 would let `é` through to return an opaque 401 instead of a local, explained refusal, so the stricter rule is deliberate. A provider that issues latin-1 keys would need this rule widened.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
index a94d7eb577..156e314154 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-api-key-format-validation.zh.md
@@ -80,7 +80,7 @@ Status: implemented
 
 格式错误的 Key 在持有它的那个字段上就被拒绝；格式错误的已存储 Key 以 `INVALID_CREDENTIAL` 失败，消息指明修复位置且不含 Key 的任何片段。由于该 code 位于 `DEFAULT_RETRYABLE_CODES` 之外，一个确定性的凭据故障不再被当作瞬时传输抖动重试三次。`llm-pi-ai` 的探测把非法 Key 报为凭据故障，而非端点不可达。
 
-形状启发式可能拒绝一个真实的 Key。最初的写法匹配任意「全大写标识符接 `=`」，评审指出其覆盖面比预期更宽：一个以 padding 结尾的全大写 base64 Key（`ABCD==`）会命中它并不像的赋值形态。要求分隔符之后必须是非 `=` 字符即可排除 padding——base64 的 padding 只出现在末尾。剩下的形态（大写名称、一个 `=`、然后是值）是已知提供方不会签发的，且该规则只在浏览器中运行，因此仍撞上它的用户可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
+形状启发式可能拒绝一个真实的 Key。匹配任意「全大写标识符接 `=`」会比预期覆盖面更宽：一个以 padding 结尾的全大写 base64 Key（`ABCD==`）会命中它并不像的赋值形态。要求分隔符之后必须是非 `=` 字符即可排除 padding——base64 的 padding 只出现在末尾。剩下的形态（大写名称、一个 `=`、然后是值）是已知提供方不会签发的，且该规则只在浏览器中运行，因此仍撞上它的用户可通过环境变量设置该凭据。残留代价是对一个尚无人报告过的 Key 给出一次令人困惑的拒绝。
 
 限定为可打印 ASCII 比传输本身的要求更严：header value 是可以承载 `\x80`–`\xFF` 的。放行 latin-1 会让 `é` 通过并换回一个语焉不详的 401，而不是一次本地的、有解释的拒绝，因此从严是刻意的。若某个提供方签发 latin-1 的 Key，这条规则需要放宽。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
index e6758b23d2..bcaa655054 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.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 .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
-2026-08-07-cancel-convergence-wake-latch.md: fe00c78bdfadac0cc6c9c173fd04256f77a22051
-2026-08-07-cancel-convergence-wake-latch.zh.md: 736c5eb39809811363ed93529d90878ea9acdc89
+2026-08-07-cancel-convergence-wake-latch.md: de18dce87e28eaf0548eebd0d054d4ca7b59d0a6
+2026-08-07-cancel-convergence-wake-latch.zh.md: b07edfd94a547ecacc8176df86b58f1f701ec2e4
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
index fe00c78bdf..de18dce87e 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
@@ -10,15 +10,15 @@ English | [中文](2026-08-07-cancel-convergence-wake-latch.zh.md)
 
 ## Decision
 
-The `running` phase carries a `wakeRequested` latch, mirroring the existing `maintenance` phase field. `wakeDriver()` latches whenever the current activity cannot deliver the wake — a maintenance task never reads the queue, and an aborted activity converges without restarting — while a live driver needs no latch because it claims queued work itself. The exiting activity replays the latch at its own convergence boundary (`kick`'s `finally` and `runMaintenance`'s `finally`): this placement guarantees `turn/end N` lands before the replayed driver opens `turn/start N+1`, and that `whenIdle()` sees the replayed driver through its `activityDone` loop. The replay sites run only while `inbox.hasPending`, so a latched wake removed from the inbox before convergence does not start an empty driver. A wake sent while the agent is already idle keeps its turn boundary even when its message is cleared before the driver claims — that `idle → running → idle` transition is an observable contract: the goal-session driver's pause/disarm fallback fires on the `idle` transition after a cancelled reservation (CI caught this when the guard was moved into `wakeDriver()` and suppressed the boundary). `cancel()` without `keepInbox` clears the latch together with the inbox.
+The `running` phase carries a `wakeRequested` latch, mirroring the existing `maintenance` phase field. `wakeDriver()` latches whenever the current activity cannot deliver the wake — a maintenance task never reads the queue, and an aborted activity converges without restarting — while a live driver needs no latch because it claims queued work itself. The exiting activity replays the latch at its own convergence boundary (`kick`'s `finally` and `runMaintenance`'s `finally`): this placement guarantees `turn/end N` lands before the replayed driver opens `turn/start N+1`, and that `whenIdle()` sees the replayed driver through its `activityDone` loop. The replay sites run only while `inbox.hasPending`, so a latched wake removed from the inbox before convergence does not start an empty driver. A wake sent while the agent is already idle keeps its turn boundary even when its message is cleared before the driver claims — that `idle → running → idle` transition is an observable contract: the goal-session driver's pause/disarm fallback fires on the `idle` transition after a cancelled reservation (moving the guard into `wakeDriver()` suppresses that boundary). `cancel()` without `keepInbox` clears the latch together with the inbox.
 
-The `signal.aborted` discriminator is load-bearing: it separates pre-abort queued work — which `keepInbox` parks for a later wake (acceptance criterion 1) — from post-abort explicit wakes, which must run after convergence.
+The `signal.aborted` discriminator is load-bearing: it separates pre-abort queued work — which `keepInbox` parks for a later wake (the `keepInbox` parking contract) — from post-abort explicit wakes, which must run after convergence.
 
 ## Alternatives considered
 
 **Have `cancel()` set the phase to `idle` immediately.** Rejected: the driver is still unwinding, so this overlaps two drivers. The replay lives in the old driver's `finally`, which then never runs — 14 of 83 tests failed, several deadlocked. Repairing it requires identity-based phase ownership plus a turn-open quiescence barrier, which is strictly more machinery and is the latch in disguise.
 
-**Latch unconditionally for every non-idle wake.** Rejected: pre-abort wakes would auto-start after a `keepInbox` cancel, violating acceptance criterion 1; the "parks queued work" test and the error-window steering test both failed.
+**Latch unconditionally for every non-idle wake.** Rejected: pre-abort wakes would auto-start after a `keepInbox` cancel, violating the `keepInbox` parking contract; the "parks queued work" test and the error-window steering test both failed.
 
 **Replay through a chained promise (`activityDone.then(...)`).** Rejected: the replay would run outside the activity's own settlement, so `whenIdle()`'s loop can resolve before the replayed driver starts; fixing that requires replacing `activityDone` at send time and depends on microtask reaction ordering — more fragile than a synchronous flag.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
index 736c5eb398..b07edfd94a 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
@@ -10,15 +10,15 @@ Status: implemented
 
 ## 决策
 
-`running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察约定：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 后该边界被抑制，CI 发现了这一点）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
+`running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察约定：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 会抑制该边界）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
 
-`signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（验收条件 1）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
+`signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（`keepInbox` 停放契约）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
 
 ## 备选方案
 
 **让 `cancel()` 立即把 phase 置为 `idle`。** 不予采用：driver 仍在展开收尾，这会重叠两个 driver。重放逻辑位于旧 driver 的 `finally`，而该 `finally` 此后不再执行——83 个测试中有 14 个失败，多个死锁。修复它需要基于身份的 phase 所有权外加 turn 打开时的 quiescence 屏障，机制上严格更重，而且该屏障就是换了个形态的锁存。
 
-**对每个非 idle 唤醒无条件锁存。** 不予采用：中断前的唤醒会在 `keepInbox` 取消后自动启动，违反验收条件 1；「停放排队工作」测试与错误窗口的 steering 测试双双失败。
+**对每个非 idle 唤醒无条件锁存。** 不予采用：中断前的唤醒会在 `keepInbox` 取消后自动启动，违反 `keepInbox` 停放契约；「停放排队工作」测试与错误窗口的 steering 测试双双失败。
 
 **通过链式 promise（`activityDone.then(...)`）重放。** 不予采用：重放会运行在活动自身结算之外，`whenIdle()` 的循环可能在重放 driver 启动前就 resolve；修复它需要在 send 时同步替换 `activityDone`，并依赖微任务反应顺序——比同步 flag 更脆弱。
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
index 34e437c316..a334bdc7d5 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.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 .agents/notes/implemented/feature/2026-06-15-code-mode.md
-2026-06-15-code-mode.md: 8a6fa068a4c7fee6fbfd9e16757a0fae5efa0c8b
-2026-06-15-code-mode.zh.md: 00d4fd48b83e183d45423722bf223a63e305d5a4
+2026-06-15-code-mode.md: 5ad7be9506c2356f90050b86d85aa77f602946ce
+2026-06-15-code-mode.zh.md: 1902c6ba86b6b8d3fecd06c417347a9c082f67b4
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
index 8a6fa068a4..5ad7be9506 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md
@@ -30,7 +30,7 @@ This note owns Code Mode's presentation, composition, isolation, and settlement
 
 **Wire tool list.** The registry contributes visible capabilities in `'native'`, only `run_code` in `'code'`, and both in `'both'`. The final `PromptAssembly.tools` list is logged in the request header. `run_code` is a reserved presentation transport outside registration and restriction layers; direct prompt providers and the assembly waterfall remain responsible for their own contributions.
 
-**Interaction with `toolOrder`, stated up front:** a configured `systemPrompt.toolOrder` naming native capabilities rejects every assembly under `mode: 'code'`, because those names are outside that mode's wire-validation universe. This is correct behavior, not a bug: a deployment using Code Mode updates its order config or drops it.
+**Interaction with `toolOrder`:** a configured `systemPrompt.toolOrder` naming native capabilities rejects every assembly under `mode: 'code'`, because those names are outside that mode's wire-validation universe. This is correct behavior, not a bug: a deployment using Code Mode updates its order config or drops it.
 
 **SDK prompt section.** In `'code'` and `'both'`, the lazy `tools:sdk` section in the tool-guidance order band renders the loaded runtime's language declarations plus fixed usage instructions for the scope's visible capabilities (TypeScript by default; the [language-dispatch note](2026-07-31-code-mode-language-dispatch.md) added Python and the `ctx.codeRuntime.language` renderer table). It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
 
@@ -106,7 +106,7 @@ Deployments switching to `'code'` must update any native-only `toolOrder`. Assem
 
 **Result elision / summarization over native tool-calling.** Addresses only the context-bloat half of the problem: trimming old `tool-result`s is cheap to add as a logged surface replacement under reconstructable requests, but still pays one model round-trip per call and cannot express loops, branches, or joins. Complementary, not competing; it can layer under Code Mode for residual native calls.
 
-**Parallel native dispatch in the loop.** The other answer to round-trip cost at decision time; it was blocked on concurrency-safety metadata and offers no composition either way — it parallelizes calls the model already decided on in one step. Code Mode's queue decision kept the two compatible, and that is how it played out: the metadata landed as `isConcurrencySafe` (the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md)), and native rolling-pool dispatch and per-tool binding parallelism unlocked on the same classifier.
+**Parallel native dispatch in the loop.** The other answer to round-trip cost at decision time; it was blocked on concurrency-safety metadata and offers no composition either way — it parallelizes calls the model already decided on in one step. Code Mode's queue decision kept the two compatible, and both later shipped: the metadata as `isConcurrencySafe` (the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md)), and native rolling-pool dispatch plus per-tool binding parallelism on the same classifier.
 
 **Always-exclusive (Cloudflare-faithful, no mode).** Rejected for this SDK's primary consumer: a coding agent's bread-and-butter single calls (`bash`, `read`, `edit`) are already ideal as native calls, and forcing every edit through a program taxes the common case. The mode config keeps the faithful form (`'code'`) one line away without imposing it.
 
diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
index 00d4fd48b8..1902c6ba86 100644
--- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
@@ -30,7 +30,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
 
 **协议工具列表。** 注册表在 `'native'` 下贡献可见能力，在 `'code'` 下仅贡献 `run_code`，在 `'both'` 下两者都贡献。最终的 `PromptAssembly.tools` 列表记录在请求头中。`run_code` 是一个保留的呈现传输通道，位于注册和限制层之外；直接提示词提供方和组装 waterfall 仍各自负责自己的贡献。
 
-**与 `toolOrder` 的交互，预先说明：** 如果配置的 `systemPrompt.toolOrder` 引用了原生能力名称，在 `mode: 'code'` 下会拒绝所有组装，因为那些名称不在该模式的协议校验范围内。这是正确行为而非 bug：使用 Code Mode 的部署需要更新其 order 配置或移除它。
+**与 `toolOrder` 的交互：** 如果配置的 `systemPrompt.toolOrder` 引用了原生能力名称，在 `mode: 'code'` 下会拒绝所有组装，因为那些名称不在该模式的协议校验范围内。这是正确行为而非 bug：使用 Code Mode 的部署需要更新其 order 配置或移除它。
 
 **SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染所加载运行时语言的声明加固定的使用说明（默认 TypeScript；[语言分发 note](2026-07-31-code-mode-language-dispatch.md) 加入了 Python 与按 `ctx.codeRuntime.language` 选择的渲染器表）。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
 
@@ -106,7 +106,7 @@ SDK 指示模型编写一个所加载运行时语言的异步函数体（默认
 
 **在原生工具调用上做结果省略/摘要。** 仅解决问题中上下文膨胀这一半：裁剪旧 `tool-result` 作为可重建请求下的日志化表面替换成本低，但仍需每次调用一次模型往返，且无法表达循环、分支或汇合。互补而非竞争；它可以在 Code Mode 下为残余的原生调用分层。
 
-**循环中的并行原生分发。** 决策当时对往返成本的另一个答案；它被并发安全元数据阻塞，且无论如何都不提供组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的队列决策保持了两者兼容，后续也正是这样落地的：元数据以 `isConcurrencySafe` 的形式就绪（见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)），原生 rolling-pool 分发与每工具绑定并行化基于同一个分类器一起解锁。
+**循环中的并行原生分发。** 决策当时对往返成本的另一个答案；它被并发安全元数据阻塞，且无论如何都不提供组合能力——它并行化的是模型在一步中已经决定的调用。Code Mode 的队列决策保持了两者兼容，两者后来都已交付：元数据即 `isConcurrencySafe`（见[并行工具调用 note](2026-07-10-parallel-tool-call-execution.md)），原生 rolling-pool 分发加每工具绑定并行化则基于同一个分类器。
 
 **始终排他（忠于 Cloudflare，无模式）。** 否决，因为本 SDK 的主要消费方是编码 agent：其日常的单次调用（`bash`、`read`、`edit`）作为原生调用已经是最优的，强制每次编辑都通过程序会给常见场景增加负担。mode 配置让忠实形式（`'code'`）只需一行配置即可启用，而不强加于人。
 
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
index 860156eb06..6ffbf96a82 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.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 .agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
-2026-06-17-filesystem-tool-schemas.md: b48f8e5d44913f2b6a2b7e1b19269c58e72efd1f
-2026-06-17-filesystem-tool-schemas.zh.md: ad4081d28950a4a2df4f5718038e2a4124bf70b5
+2026-06-17-filesystem-tool-schemas.md: ede7daee5c0f49a094df16861b107c8f528664fa
+2026-06-17-filesystem-tool-schemas.zh.md: 5ab19b82d6523bc81dd57c319252d998cc203911
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
index b48f8e5d44..ede7daee5c 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md
@@ -8,17 +8,17 @@ English | [中文](2026-06-17-filesystem-tool-schemas.zh.md)
 
 [The filesystem capability-seam Agent Note](../architecture/2026-06-17-filesystem-capability-seam.md) defines the filesystem capability seam (`ctx.fs`), the package split (`dsh-fs`, `dsh-fs-local`, `dsh-tool-fs`, plus the `dsh-fs-policy` policy plugin), and the observed-file/stale-version policy for read-before-write/edit checks — which the [split-fs-seam](../simplification/2026-06-26-fsspec-style-fs-seam.md) and [event-gate](../architecture/2026-06-26-file-context-as-event-gate.md) Agent Notes moved off `ctx.fs` into the `dsh-fs-policy` plugin on the `fs/*` event gate. The remaining decision for the first filesystem tool delivery is the model-facing schema surface: what arguments the model sees for `read`, `write`, and `edit`.
 
-The schema should be small enough to implement in the first `dsh-tool-fs` pass, but stable enough that future local/remote/sandboxed filesystem backends do not require model-facing churn. It should also avoid importing every option from reference systems. Claude Code and OpenCode expose similar core file tools but differ in naming style and extra flags; this Agent Note chooses the minimal shared surface for the prototype.
+The schema must be small, yet stable enough that local/remote/sandboxed filesystem backends do not require model-facing churn, and must avoid importing every option from reference systems. Claude Code and OpenCode expose similar core file tools but differ in naming style and extra flags; this decision picks the minimal shared surface.
 
 ## Decision
 
 `@deepseek-ai/dsh-tool-fs` exposes these three model-facing tools in the first filesystem suite:
 
-| Tool | Our schema | Claude Code | OpenCode | Notes | Part of prototype |
-|---|---|---|---|---|---|
-| `read` | `read(file_path, offset?, limit?)` | `Read(file_path, offset?, limit?, pages?)` | `read(filePath, offset?, limit?)` | Files only; 1-indexed `offset`; no image/PDF/multimodal support in the first pass. | YES |
-| `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | Creates or overwrites UTF-8 text. Under the default fs-policy, updates to existing files require a prior observation; new-file creates do not. | YES |
-| `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | Literal string replacement; unique match required by default; under the default fs-policy requires a prior observation (any windowed read counts). | YES |
+| Tool | Our schema | Claude Code | OpenCode | Notes |
+|---|---|---|---|---|
+| `read` | `read(file_path, offset?, limit?)` | `Read(file_path, offset?, limit?, pages?)` | `read(filePath, offset?, limit?)` | Files only; 1-indexed `offset`; no image/PDF/multimodal support in the first pass. |
+| `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | Creates or overwrites UTF-8 text. Under the default fs-policy, updates to existing files require a prior observation; new-file creates do not. |
+| `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | Literal string replacement; unique match required by default; under the default fs-policy requires a prior observation (any windowed read counts). |
 
 The schema uses snake_case field names (`file_path`, `old_string`, `new_string`, `replace_all`) to align with Claude Code and with existing DeepSeek Harness tool-schema examples. The Consumer package translates these model-facing names into `ctx.fs` calls and `fs/*` event dispatches.
 
diff --git a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
index ad4081d289..5ab19b82d6 100644
--- a/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.zh.md
@@ -8,17 +8,17 @@ Status: implemented
 
 [文件系统能力 seam Agent Note](../architecture/2026-06-17-filesystem-capability-seam.md) 定义了文件系统能力 seam（`ctx.fs`）、包拆分（`dsh-fs`、`dsh-fs-local`、`dsh-tool-fs`，加上 `dsh-fs-policy` 策略插件），以及针对 read-before-write/edit 检查的已观测文件／陈旧版本策略——[拆分文件系统 seam](../simplification/2026-06-26-fsspec-style-fs-seam.md)和[事件门控插件](../architecture/2026-06-26-file-context-as-event-gate.md) Agent Note 后来将其从 `ctx.fs` 移至 `dsh-fs-policy` 插件的 `fs/*` 事件门上。首次文件系统工具交付剩余的决策是面向模型的 schema 接口：模型在 `read`、`write` 和 `edit` 中看到哪些参数。
 
-该 schema 应足够小，以便在 `dsh-tool-fs` 的首次实现中完成，但又足够稳定，使未来的本地/远程/沙箱文件系统后端不需要改动面向模型的接口。同时应避免从参考系统中照搬所有选项。Claude Code 和 OpenCode 暴露了类似的核心文件工具，但在命名风格和额外 flag 上有所不同；本 Agent Note 为原型选择最小的共有接口。
+该 schema 必须足够小，但又要足够稳定，使本地/远程/沙箱文件系统后端不需要改动面向模型的接口，并且必须避免从参考系统中照搬所有选项。Claude Code 和 OpenCode 暴露了类似的核心文件工具，但在命名风格和额外 flag 上有所不同；本决策选择最小的共有接口。
 
 ## 决策
 
 `@deepseek-ai/dsh-tool-fs` 在首个文件系统工具套件中暴露以下三个面向模型的工具：
 
-| 工具 | 我们的 schema | Claude Code | OpenCode | 说明 | 原型包含 |
-|---|---|---|---|---|---|
-| `read` | `read(file_path, offset?, limit?)` | `Read(file_path, offset?, limit?, pages?)` | `read(filePath, offset?, limit?)` | 仅文件；`offset` 从 1 开始；首版不支持图片、PDF 或多模态内容。 | 是 |
-| `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | 创建或覆盖 UTF-8 文本。在默认 fs-policy 下，更新现有文件前必须先观测；创建新文件则不需要。 | 是 |
-| `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | 字面字符串替换；默认要求唯一匹配；在默认 fs-policy 下必须先观测（任意窗口读取均算作观测）。 | 是 |
+| 工具 | 我们的 schema | Claude Code | OpenCode | 说明 |
+|---|---|---|---|---|
+| `read` | `read(file_path, offset?, limit?)` | `Read(file_path, offset?, limit?, pages?)` | `read(filePath, offset?, limit?)` | 仅文件；`offset` 从 1 开始；首版不支持图片、PDF 或多模态内容。 |
+| `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | 创建或覆盖 UTF-8 文本。在默认 fs-policy 下，更新现有文件前必须先观测；创建新文件则不需要。 |
+| `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | 字面字符串替换；默认要求唯一匹配；在默认 fs-policy 下必须先观测（任意窗口读取均算作观测）。 |
 
 schema 使用 snake_case 字段名（`file_path`、`old_string`、`new_string`、`replace_all`），与 Claude Code 及现有 DeepSeek Harness 工具 schema 示例保持一致。Consumer 包将这些面向模型的名称转换为 `ctx.fs` 调用和 `fs/*` 事件分发。
 
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
index 1ab18b72e9..d981514b4c 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.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 .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: 6357482600fabd0354325a19118ec245eee5d855
-2026-06-18-compaction-capability-seam.zh.md: a5c60c667734f119a8bd9d9b6a8fbc9c66155470
+2026-06-18-compaction-capability-seam.md: 83f224aef50eb02712ac095da0cabf552399a9a6
+2026-06-18-compaction-capability-seam.zh.md: 12cf2498535d77dcf1a718b841a751bccadfdf1c
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index 6357482600..83f224aef5 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
@@ -31,7 +31,7 @@ This is not a coupling smell — it is the contract's domain. The "only cordis"
 
 ### Three abstract operations, algorithm in the backend
 
-An earlier draft put the full algorithm (the retention walk, token-summing, text extraction) as concrete methods on the interface. That recouples the contract to one strategy: a backend that wants a different retention policy or event sequence would have to fight inherited concrete code. Making all three operations abstract puts every *how* decision in the backend and keeps the interface a statement of *what*. Token measurement is not a compaction hook at all; the singleton service lets multiple consumers share one per-session replay fold.
+Putting the full algorithm (the retention walk, token-summing, text extraction) as concrete methods on the interface recouples the contract to one strategy: a backend that wants a different retention policy or event sequence would have to fight inherited concrete code. Making all three operations abstract puts every *how* decision in the backend and keeps the interface a statement of *what*. Token measurement is not a compaction hook at all; the singleton service lets multiple consumers share one per-session replay fold.
 
 `compactIfNeeded(agent, trigger, signal)` takes an explicit `'pressure' | 'context-overflow'` trigger and cancellation. It reads only the latest durable routed request; no header means no work, while any routed provider/model target uses the singleton estimator. `compactNow(agent, signal)` requires an idle agent and performs one useful balanced reduction even below pressure, returning `null` without writes when none exists. `compactRegion(start, end, agent, signal?)` uses `agent.session` as its single session identity and keeps an optional signal for explicit callers. The default summarizer resolves its target from explicit config, the latest logged routed target, then agent options, and records the provider/model pair after any `llm/stream` routing. It replays the routed request's prefix and appends the compaction directive as a trailing user message so the provider's warm KV cache is reused — see the [summary prefix-cache Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md). The result carries `llmStreamCall: true` because it consumed exactly one call through this context's LLM service; a subclass sets that marker only under the same condition, since retained `rawOutput` alone does not identify the call path. The call sets the provider-neutral `GenerateOptions.purpose` to `compaction`; adapters may map that purpose to model-hidden transport metadata, and the DeepSeek adapter sends `x-deepseek-harness-compact: 1`.
 
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
index a5c60c6677..12cf249853 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md
@@ -31,7 +31,7 @@ Status: implemented
 
 ### 三个抽象操作，算法在后端
 
-早期草案将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法。这会将约定重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
+将完整算法（保留遍历、token 求和、文本提取）作为接口上的具体方法，会将约定重新耦合到一种策略：想要不同保留策略或事件排序的后端必须与继承来的具体代码对抗。将三个操作都设为抽象，把所有*怎么做*的决策放在后端，并让接口保持为*做什么*的声明。token 测量根本不是压缩钩子；单例服务使多个消费方能够共享逐会话的回放折叠。
 
 `compactIfNeeded(agent, trigger, signal)` 接受显式的 `'pressure' | 'context-overflow'` 触发原因与取消信号。它只读取最新的持久化已路由请求；没有 header 就不执行工作，任何已路由的提供方/模型目标都使用单例估算器。`compactNow(agent, signal)` 要求 agent 处于 idle，即使未达到压力也进行一次有效的平衡缩减；不存在这种范围时返回 `null`，且不写入任何内容。`compactRegion(start, end, agent, signal?)` 将 `agent.session` 作为唯一会话身份，并为显式调用方保留可选 signal。默认摘要器依次从显式配置、最新记录的已路由目标和 agent 选项解析目标，并在任何 `llm/stream` 路由后记录提供方/模型对。它回放已路由请求的前缀，并将压缩指令追加为尾部 user 消息，从而复用提供方的热 KV cache；见[摘要前缀缓存 Agent Note](../bug-fix/2026-07-21-compaction-summary-prefix-cache-reuse.md)。该结果携带 `llmStreamCall: true`，因为生成它时恰好通过此上下文的 LLM 服务发起了一次调用；只有满足相同条件时，子类才设置该标记，因为单有保留的 `rawOutput` 并不能判定调用路径。该调用将提供方无关的 `GenerateOptions.purpose` 设为 `compaction`；适配器可以将此用途映射为对模型隐藏的传输元数据，DeepSeek 适配器会发送 `x-deepseek-harness-compact: 1`。
 
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index ac018acdc8..cebb95513f 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.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 .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
-2026-06-21-subagent-capability-seam.md: 553411a0d8f989c883e3eea929669ccebcfe807b
-2026-06-21-subagent-capability-seam.zh.md: 5fa2bd62828e9afcb79647ec4821c2da1da041e7
+2026-06-21-subagent-capability-seam.md: 82010b4d11d2de5fc00f892b05e73807530e9cbf
+2026-06-21-subagent-capability-seam.zh.md: dc4e35e9ca6de8790b26bda1aeca30af00db5e1d
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
index 553411a0d8..82010b4d11 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -8,9 +8,9 @@ English | [中文](2026-06-21-subagent-capability-seam.zh.md)
 
 ## Problem
 
-The harness has a long-deferred seam for **subagents** — an agent delegating work to another agent. The intent was sketched in the `Agent`/`AgentLoop` interfaces ([packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts), [packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)): a creation option referencing a parent agent (fork = seed the child session with the parent's event log; spawn = fresh session), with the child returned as an `Agent` handle so steering and event subscription work uniformly. This Agent Note realizes that seam; the banner above lists what shipped.
+The harness has a long-deferred seam for **subagents** — an agent delegating work to another agent. The intent was sketched in the `Agent`/`AgentLoop` interfaces ([packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts), [packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)): a creation option referencing a parent agent (fork = seed the child session with the parent's event log; spawn = fresh session), with the child returned as an `Agent` handle so steering and event subscription work uniformly.
 
-The distinctive requirement — the one that shapes the whole design — is that **multiple subagent implementations must coexist at runtime**. A parent may want a cheap in-process child for a scoped subtask AND an isolated out-of-process child (over ACP) in the same session. The transports we foresee:
+The distinctive requirement — the one that shapes the whole design — is that **multiple subagent implementations must coexist at runtime**. A parent may want a cheap in-process child for a scoped subtask AND an isolated out-of-process child (over ACP) in the same session. The transports:
 
 - **in-process** — a child concrete `Agent` on the same `Context` (the cheapest, and nearly free given the existing agent factory);
 - **ACP** — act as an ACP *client* driving another agent process (which can be another instance of ourselves);
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index 5fa2bd6282..dc4e35e9ca 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -8,9 +8,9 @@ Status: implemented
 
 ## 问题
 
-harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent 将工作委派给另一个 agent。这一意图在 `Agent`/`AgentLoop` 接口中已有草案（[packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts)、[packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)）：一个创建选项引用父 agent（fork = 用父会话的事件日志初始化子会话；spawn = 全新会话），子 agent 以 `Agent` 句柄返回，使 steering（中途引导）和事件订阅可以统一工作。本 Agent Note 实现了这个 seam；上方横幅列出了已交付的内容。
+harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent 将工作委派给另一个 agent。这一意图在 `Agent`/`AgentLoop` 接口中已有草案（[packages/core/agent/src/types.ts](../../../../packages/core/agent/src/types.ts)、[packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)）：一个创建选项引用父 agent（fork = 用父会话的事件日志初始化子会话；spawn = 全新会话），子 agent 以 `Agent` 句柄返回，使 steering（中途引导）和事件订阅可以统一工作。
 
-决定整体设计走向的核心需求是：**多种 subagent 实现必须在运行时共存**。一个父 agent 可能在同一个会话中既需要一个廉价的进程内子 agent 处理有限范围的子任务，又需要一个隔离的进程外子 agent（通过 ACP）。我们预见的传输方式：
+决定整体设计走向的核心需求是：**多种 subagent 实现必须在运行时共存**。一个父 agent 可能在同一个会话中既需要一个廉价的进程内子 agent 处理有限范围的子任务，又需要一个隔离的进程外子 agent（通过 ACP）。传输方式：
 
 - **进程内**：在同一个 `Context` 上创建一个具体的子 `Agent`（最廉价，且鉴于现有 agent 工厂几乎零成本）；
 - **ACP**：作为 ACP *客户端*驱动另一个 agent 进程（可以是自身的另一个实例）；
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
index 2cb98d1258..865461630d 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.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 .agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
-2026-06-29-todo-write-tool.md: c4cf64b7876bd8b80df80fe6fc27005715f96b5e
-2026-06-29-todo-write-tool.zh.md: 2e95cfc4b085b03a70a651c622ca87ad7efa1538
+2026-06-29-todo-write-tool.md: 74af8a66ea86a474533b9c53d6431f7e0026192c
+2026-06-29-todo-write-tool.zh.md: ec2b7c8d59d65a44018425de81aa410890d8c208
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
index c4cf64b787..74af8a66ea 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
@@ -42,7 +42,7 @@ The schema enforces type/required/enum. Beyond that, `execute` rejects empty or
 
 ## Testing
 
-Four tiers, designed up front:
+Four tiers:
 - **Unit** — the session event (append/snapshot-clone/last-write-wins/not-on-surface); the tool (schema shape, arg validation via the real `ctx.tools.execute`, value validation, the event append + replacement, no-agent rejection, `presentCall`, HMR-safety); and TUI folding.
 - **Real-Loader path** — the plugin run through `Loader.unwrapExports`, asserting the namespace export shape survives (it HAS `inject`, so a stray default would crash at load — postmortem/0001).
 - **Full-loop integration** — a scripted mock model calls `todo_write` through the real agent loop; the `todo/write` event lands and a second call replaces it.
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
index 2e95cfc4b0..ec2b7c8d59 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
@@ -42,7 +42,7 @@ schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重
 
 ## 测试
 
-四个层级，预先设计：
+四个层级：
 - **单元测试**——会话事件（append/snapshot-clone/last-write-wins/not-on-surface）；工具（schema 形状、通过真实 `ctx.tools.execute` 的参数校验、值校验、事件追加与替换、非 agent 拒绝、`presentCall`、HMR（热模块替换）安全性）；以及 TUI 折叠。
 - **真实 Loader 路径**——插件通过 `Loader.unwrapExports` 运行，断言命名空间导出形状存活（它有 `inject`，因此一个意外的 default 导出会在加载时崩溃——事故复盘（postmortem）0001）。
 - **全循环集成**——一个脚本化的 mock 模型通过真实 agent loop（智能体循环）调用 `todo_write`；`todo/write` 事件落地，第二次调用替换它。
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
index 547f88999e..c0b295a5c0 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.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 .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
-2026-06-30-hook-protocol-lib.md: 576a126e1022ac72265c476e03ef36aaf17f78b4
-2026-06-30-hook-protocol-lib.zh.md: f2554eaa378a26bf8254d86d458e0de5ce1aa4fd
+2026-06-30-hook-protocol-lib.md: e6938f88b2b587ef97c135d6482ae9ce0e3a94c1
+2026-06-30-hook-protocol-lib.zh.md: 4a4efae9a8950368d4db0309bc2c89a3f8c6d0d0
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
index 576a126e10..e6938f88b2 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-30-hook-protocol-lib.zh.md)
 
 ## Problem
 
-The hooks subsystem ships two bridge plugins: one that runs a user's existing Claude Code (CC) hooks, one for Codex hooks. Studying the reference implementations (`~/repos/refs/claude-code`, `~/repos/refs/codex`) surfaced a decisive fact: **Codex deliberately reimplements a SUBSET of the CC hook protocol.** Its engine reads the same `hooks.json`, uses the same matcher-group shape, the same exit-code/structured-stdout output contract, and the same command-hook execution model — Codex's source even names the engine after Claude's and comments where it "intentionally diverges." So the two bridges would otherwise duplicate the bulk of the protocol.
+The hooks subsystem ships two bridge plugins: one that runs a user's existing Claude Code (CC) hooks, one for Codex hooks. The reference implementations (`~/repos/refs/claude-code`, `~/repos/refs/codex`) show a decisive fact: **Codex deliberately reimplements a SUBSET of the CC hook protocol.** Its engine reads the same `hooks.json`, uses the same matcher-group shape, the same exit-code/structured-stdout output contract, and the same command-hook execution model — Codex's source even names the engine after Claude's and comments where it "intentionally diverges." So the two bridges would otherwise duplicate the bulk of the protocol.
 
 This Agent Note introduces `@deepseek-ai/dsh-hook-protocol`, a **library** (not a plugin — it registers and injects nothing) holding the genuinely-identical primitives both bridges build on. The split between shared and per-dialect is the design's center of gravity.
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
index f2554eaa37..4a4efae9a8 100644
--- a/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-钩子子系统提供两个桥接插件：一个运行用户既有的 Claude Code（CC）钩子，另一个运行 Codex 钩子。研究参考实现（`~/repos/refs/claude-code`、`~/repos/refs/codex`）后发现一个决定性事实：**Codex 有意重新实现了 CC 钩子协议的一个子集。** 它的引擎读取相同的 `hooks.json`，使用相同的 matcher-group 形状、相同的 exit-code/structured-stdout 输出约定，以及相同的命令钩子执行模型。Codex 的源码甚至以 Claude 的引擎命名，并在注释中标注了「有意偏离」之处。因此，如果不做抽取，两个桥接插件将大量重复协议逻辑。
+钩子子系统提供两个桥接插件：一个运行用户既有的 Claude Code（CC）钩子，另一个运行 Codex 钩子。参考实现（`~/repos/refs/claude-code`、`~/repos/refs/codex`）表明一个决定性事实：**Codex 有意重新实现了 CC 钩子协议的一个子集。** 它的引擎读取相同的 `hooks.json`，使用相同的 matcher-group 形状、相同的 exit-code/structured-stdout 输出约定，以及相同的命令钩子执行模型。Codex 的源码甚至以 Claude 的引擎命名，并在注释中标注了「有意偏离」之处。因此，如果不做抽取，两个桥接插件将大量重复协议逻辑。
 
 本 Agent Note 引入 `@deepseek-ai/dsh-hook-protocol`，一个**库**（不是插件——它不注册也不注入任何东西），持有两个桥接插件共同依赖的真正相同的原语。共享与方言专属之间的分界是本设计的重心。
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
index 3e5d68bb7e..c9a3f3857e 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.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 .agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
-2026-06-30-session-store-fork-api.md: 69ff85e1f137f4f263bf951af0a3f655411c606a
-2026-06-30-session-store-fork-api.zh.md: f354aaefbc16c6c3251da20de507602105a32296
+2026-06-30-session-store-fork-api.md: 85e748ba4e42919eac49cae583a08c72e0c3c0a0
+2026-06-30-session-store-fork-api.zh.md: f985c93085cbc2dbb1b8a768dac82a40025ea54d
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
index 69ff85e1f1..85e748ba4e 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md
@@ -36,7 +36,7 @@ The Host creates the child through the agent registry with the selected seed and
 
 ## Alternatives considered
 
-**Separate `ctx.sessionFork` service.** This was the first implementation, but review showed it overfit the capability-seam pattern. The code had no swappable backend, no extra event surface, no independent ownership lifecycle, and no durable behavior beyond `ctx.sessions.create({ seed, meta })`. Keeping a separate package would make callers discover and install a second service just to perform policy around a session-store primitive.
+**Separate `ctx.sessionFork` service.** An earlier iteration shipped this as a separate service; it overfit the capability-seam pattern. The code had no swappable backend, no extra event surface, no independent ownership lifecycle, and no durable behavior beyond `ctx.sessions.create({ seed, meta })`. Keeping a separate package would make callers discover and install a second service just to perform policy around a session-store primitive.
 
 **Two functions: `snapshot()` plus `fork()`.** This preserved a reusable seed/metadata computation, but the only supported consumer created a session immediately. It also made the surface feel more abstract than the concrete operation users need. A single `fork()` with an explicit `boundary` keeps the API direct while still supporting previous-point forks.
 
diff --git a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
index f354aaefbc..f985c93085 100644
--- a/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
@@ -36,7 +36,7 @@ Host 通过 agent（智能体）注册表，以选定的种子和谱系创建子
 
 ## 曾考虑的替代方案
 
-**独立的 `ctx.sessionFork` 服务。** 这是最初的实现，但评审表明它过度套用了能力 seam 模式。代码没有可替换的后端、没有额外的事件面、没有独立的所有权生命周期，也没有超出 `ctx.sessions.create({ seed, meta })` 的持久化行为。保留独立包会迫使调用方为了在会话存储原语之上执行一层策略而去发现并安装第二个服务。
+**独立的 `ctx.sessionFork` 服务。** 较早的一版迭代曾把它作为独立服务交付；它过度套用了能力 seam 模式。代码没有可替换的后端、没有额外的事件面、没有独立的所有权生命周期，也没有超出 `ctx.sessions.create({ seed, meta })` 的持久化行为。保留独立包会迫使调用方为了在会话存储原语之上执行一层策略而去发现并安装第二个服务。
 
 **两个函数：`snapshot()` 加 `fork()`。** 这保留了一个可复用的种子／元数据计算，但唯一支持的消费方会立即创建会话。它还使接口看起来比用户实际需要的具体操作更抽象。单一的 `fork()` 加显式 `boundary` 使 API 保持直接，同时仍支持对先前时间点的 fork。
 
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
index eac4c74cdc..abb46b8faa 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.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 .agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
-2026-07-14-cross-family-fs-sandbox.md: e8a59be345b52f7684c574134b37f48bc49843fc
-2026-07-14-cross-family-fs-sandbox.zh.md: 228e156688ce23c10ac42b2c96b3737f796d4524
+2026-07-14-cross-family-fs-sandbox.md: 1c734a583403d1c1c9ea132a1e089362a9de4707
+2026-07-14-cross-family-fs-sandbox.zh.md: fdde507e002ac8dac452bb0f783ba8915bfcc30f
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
index e8a59be345..1c734a5834 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
@@ -49,7 +49,7 @@ The [`examples/acp-agent`](../../../../examples/acp-agent/cordis.yml) compositio
 
 ### The enforcement point: provider, not intent gate
 
-The sandbox Agent Note's original cross-family sketch put fs enforcement on the `fs/write-intent`/`fs/edit-intent` events. This Agent Note enforces in the provider instead, on two mechanical facts: the intent slots are single-decision first-wins (occupied by `dsh-fs-policy`, whose contract names a second decider a misconfiguration), and the intent events are dispatched only by `dsh-tool-fs` — a direct `ctx.fs` caller (a cordis-mounted plugin, a custom tool) bypasses them, where provider-level enforcement covers every caller by construction. The sandbox Agent Note's deferred-phase wording is updated to match in the same change.
+The sandbox Agent Note's original cross-family sketch put fs enforcement on the `fs/write-intent`/`fs/edit-intent` events. This Agent Note enforces in the provider instead, on two mechanical facts: the intent slots are single-decision first-wins (occupied by `dsh-fs-policy`, whose contract names a second decider a misconfiguration), and the intent events are dispatched only by `dsh-tool-fs` — a direct `ctx.fs` caller (a cordis-mounted plugin, a custom tool) bypasses them, where provider-level enforcement covers every caller by construction.
 
 ### Out of scope
 
diff --git a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
index 228e156688..fdde507e00 100644
--- a/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
@@ -49,7 +49,7 @@ Status: implemented
 
 ### 强制执行点：提供方，而非 intent gate
 
-沙箱 Agent Note 最初的跨家族草图把 fs 强制执行放在 `fs/write-intent`/`fs/edit-intent` 事件上。本 Agent Note 改为在提供方中强制执行，基于两个机制性事实:intent 槽是单决策、先到先得(已被 `dsh-fs-policy` 占据,其约定称第二个决策者为配置错误),且 intent 事件只由 `dsh-tool-fs` 派发——一个直连 `ctx.fs` 的调用方(一个 cordis 挂载插件、一个自定义工具)会绕过它们,而提供方级强制执行按构造覆盖每一个调用方。沙箱 Agent Note 的暂缓阶段措辞在同一变更中被更新以匹配。
+沙箱 Agent Note 最初的跨家族草图把 fs 强制执行放在 `fs/write-intent`/`fs/edit-intent` 事件上。本 Agent Note 改为在提供方中强制执行，基于两个机制性事实:intent 槽是单决策、先到先得(已被 `dsh-fs-policy` 占据,其约定称第二个决策者为配置错误),且 intent 事件只由 `dsh-tool-fs` 派发——一个直连 `ctx.fs` 的调用方(一个 cordis 挂载插件、一个自定义工具)会绕过它们,而提供方级强制执行按构造覆盖每一个调用方。
 
 ### 范围之外
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
index d7d288e9f9..b7181bfba1 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.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 .agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
-2026-07-16-harness-level-loop.md: 2efcf64adf07152b544c82f5bbf3bd8e415cd64d
-2026-07-16-harness-level-loop.zh.md: 8b83ca4a7f957f304c093e4b3f4c462c6301d6bc
+2026-07-16-harness-level-loop.md: e84a5738a55988d3b968eac829d9daaf10d7e304
+2026-07-16-harness-level-loop.zh.md: d7cda56d66d4456ac5c3c7d55bb238e85fcacbc5
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
index 2efcf64adf..e84a5738a5 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.md
@@ -14,7 +14,7 @@ The repository therefore needs goal-based execution above the turn/step loop, bu
 
 ## Decision
 
-This proposal is implemented in amended form as two explicit plugin policies over existing seams:
+Two explicit plugin policies over existing seams:
 
 1. **Same-session goals** retain one durable objective in the current session and admit goal-attributed continuation turns only while live activation is armed.
 2. **Fresh-agent Ralph runs** execute a fixed foreground workflow whose rounds each spawn a new structured child with no conversation seed.
diff --git a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
index 8b83ca4a7f..d7cda56d66 100644
--- a/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-本提案以修订后的形式实现为构建在现有 seam 之上的两项显式插件策略：
+构建在现有 seam 之上的两项显式插件策略：
 
 1. **同会话目标**在当前会话中保留一个持久目标，并且只在实时激活态已激活时接纳带目标归属的续行轮次。
 2. **全新 agent Ralph 运行**执行一个固定前台工作流，其中每个 Round 都生成一个不带对话种子的全新结构化子 agent。
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
index 1730793d35..146601b28d 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.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 .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
-2026-07-16-persistent-pty-sessions.md: 5d45f5fd13099352d503bc3296e4f6b7b0c53bc8
-2026-07-16-persistent-pty-sessions.zh.md: a0b4150157110b64943a42ce4e3544342e1be788
+2026-07-16-persistent-pty-sessions.md: f27d799574e61d92123c9ca4e31c5c2a9d3229b4
+2026-07-16-persistent-pty-sessions.zh.md: 0c23619faf00794c2c4e7b3f85ef961faddd99e0
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
index 5d45f5fd13..f27d799574 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md
@@ -161,7 +161,6 @@ The package ships concise tool guidance explaining persistent state, owner isola
 - Real `node-pty` and PTY-consumer tests jointly exercise shell state, shared sandbox policy, environment scrubbing, raw-mode foreground `SIGINT`, a TERM-ignoring descendant, and immediate post-disposal quiescence on supported hosts.
 - A Loader-driven `cordis.yml` test mounts the real three-package composition. ACP and headless snapshots pin the six schemas, bounded results, and errors through opt-in overlays; TUI snapshots pin terminal and generic card presentation.
 - Package contracts, the architecture map, subsystem pages, generated catalogs, and the website API describe the same shipped surface.
-- The repository CI-equivalent sequence owns type, lint, coverage, snapshot, documentation, build, hygiene, demo, and built-entry verification.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
index a0b4150157..0c23619faf 100644
--- a/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md
@@ -161,7 +161,6 @@ plugins:
 - 真实 `node-pty` 与 PTY 消费方测试共同在受支持宿主上覆盖 shell 状态、共享沙箱策略、环境清洗、raw mode 前台 `SIGINT`、忽略 `SIGTERM` 的后代进程，以及 dispose 返回后立即完全停稳。
 - Loader 驱动的 `cordis.yml` 测试挂载真实三包组合。ACP 与 headless 快照通过 opt-in overlay 固定 6 个 schema、有界结果和错误；TUI 快照固定 terminal 与 generic 卡片展示。
 - 包约定、架构图、子系统页面、生成目录和 website API 描述同一个已发布接口。
-- 仓库 CI 等价序列负责类型、lint、覆盖率、快照、文档、构建、hygiene、demo 和 built-entry 验证。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
index 50196335f2..445f6548b3 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.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 .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
-2026-07-20-dsh-cli-personal-config.md: c00432ba2b75cc42caf23e405c24acb33d839e7a
-2026-07-20-dsh-cli-personal-config.zh.md: 91d2c938b345a7f2233da1566ac6db5b934c3148
+2026-07-20-dsh-cli-personal-config.md: f5207c5ffbd963b9b7c4a7166fa9f17a460707a9
+2026-07-20-dsh-cli-personal-config.zh.md: 24478a4b4fd5878032bf80f5b30ab9e2008da785
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
index c00432ba2b..f5207c5ffb 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
@@ -30,7 +30,7 @@ The TUI and Web register the exact personal path through Cordis HMR after boot.
 
 **A separate `bin/dsh` wrapper owning the `dsh` name.** Rejected because `apps/cli` is the single product CLI for default TUI, headless, and Web dispatch. Two competing entrypoints would collide in `$PATH` and product identity.
 
-**A pi-style typed settings file (`defaultProvider`/`defaultModel`/`providers`).** Rejected by the user in favor of patch semantics: the personal file is a cordis overlay over the shipped default config, not a second config vocabulary to own and translate.
+**A pi-style typed settings file (`defaultProvider`/`defaultModel`/`providers`).** Rejected in favor of patch semantics (product-owner decision): the personal file is a cordis overlay over the shipped default config, not a second config vocabulary to own and translate.
 
 **A personal full `cordis.yml` that includes the requested config.** Rejected: the personal file would have to name the leaf config's path, which varies per checkout; patches invert the dependency so the bin keeps choosing the tree and the personal layer only amends it.
 
diff --git a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
index 91d2c938b3..24478a4b4f 100644
--- a/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md
@@ -30,7 +30,7 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 
 **另设一个 `bin/dsh` 包装脚本并由其占用 `dsh` 名称。** 否决，因为 `apps/cli` 是统一的产品 CLI，负责分发默认 TUI、无头和 Web 界面。两个相互竞争的入口会在 `$PATH` 和产品身份上冲突。
 
-**pi 风格的类型化设置文件（`defaultProvider`/`defaultModel`/`providers`）。** 用户否决，选择补丁语义：个人文件是叠加在随仓库提供的默认配置之上的 cordis overlay，而不是需要另行拥有和翻译的第二套配置词汇。
+**pi 风格的类型化设置文件（`defaultProvider`/`defaultModel`/`providers`）。** 否决，选择补丁语义（产品负责人决策）：个人文件是叠加在随仓库提供的默认配置之上的 cordis overlay，而不是需要另行拥有和翻译的第二套配置词汇。
 
 **个人完整 `cordis.yml` 去 include 请求的配置。** 否决：个人文件将不得不写死叶子配置的路径，而该路径随 checkout 变化；补丁反转了依赖方向，bin 仍然选择配置树，个人层只做修正。
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
index ee8d4ca6af..f055b6f81f 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.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 .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
-2026-07-23-session-telemetry-otel-revival.md: e6a213af65451a2ae26a5eb685c1a0f6ab220869
-2026-07-23-session-telemetry-otel-revival.zh.md: b97840405bbde35f3b6b7f417b0615774fe43061
+2026-07-23-session-telemetry-otel-revival.md: 67ab0d28a168422a6b787a6088648746cd6079b6
+2026-07-23-session-telemetry-otel-revival.zh.md: d59dcd07e9879e1c7cafc7a104d4f2515596cab8
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
index e6a213af65..67ab0d28a1 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md
@@ -30,7 +30,7 @@ The boundary axiom holds: the harness's aspect ends at `emit()`. Batching, retry
 
 **Full-log replay when no handoff cursor survived (re-export constructor seeds).** Shipped in the first revival round, then narrowed: adoption now replays from the session's construction boundary (`Session.firstLiveSeq`, the constructor-seed length — a fact the session already validated but did not expose; `header.seedLength` cannot serve, it is the durable fork-lineage value and a resumed session's constructor seed is its full stored log). A resumed session's history already shipped from the previous process under the same id, and a fork's inherited prefix already shipped in the parent's stream — re-exporting either re-billed every resume for its full history and doubled query-time counts on OTLP backends with no native ingest dedupe. Receivers stitch fork lineage via `session.parent_id` + `session.seed_length`. What the narrowing gives up, consistently with the at-most-once stance: a resume no longer backfills records the previous process failed to deliver (telemetry unmounted then, or queued at crash) — the full replay's only real benefit, bought at the common case's expense. A deployment that states a backfill requirement needs the deferred outbox above, not replay. The boundary also swallows the synthetic turn closers `SessionPersistence.load()` writes when repairing a crash-interrupted log (they sit below `firstLiveSeq` despite never existing in the previous process) — deliberate, not incidental: exporting a synthetic closer cannot complete the remote turn whose real tail records died in the crashed process's queue, it can only make an incomplete turn look closed. The wire stream stays faithful to what the crashed process actually shipped; receivers read a never-closed turn on a resumed stream as "the previous process died inside it" (the OTel README states the rule), and a later clean `shutdown` marker attests only to the resumed process's exit. Threading the pre-repair boundary through load/prepare so repairs export as live events would couple three packages to un-ship that signal.
 
-**Forwarding the seam's turn-boundary `flush()` hint to the OTel provider's `forceFlush()`.** Shipped in the first revival round, then removed after three review rounds each found a new silent-loss path in the same wrapper state: a dispose racing an in-flight flush (the SDK's concurrent-flush guard makes shutdown's internal drain skip), overlapping hints displacing the retained promise, and the provider's fixed 30-second flush timeout rejecting while the processor still drains. Every path exists only because the forwarding made this backend the process's second flusher against undocumented SDK internals from the upstream experimental tree; with no `flush()` implemented, the batch processor is the only flusher, its `scheduledDelayMillis` (already deployment-tunable through the `processor` passthrough) governs export cadence, and `shutdown()`'s drain is complete by construction. Reinstate only if a deployment states a turn-boundary latency requirement `scheduledDelayMillis` cannot meet — and then by calling the retained `BatchLogRecordProcessor`'s own `forceFlush()`, never the provider's timeout-wrapped one.
+**Forwarding the seam's turn-boundary `flush()` hint to the OTel provider's `forceFlush()`.** Shipped in the first revival round, then removed: three distinct silent-loss paths shared the wrapper state — a dispose racing an in-flight flush (the SDK's concurrent-flush guard makes shutdown's internal drain skip), overlapping hints displacing the retained promise, and the provider's fixed 30-second flush timeout rejecting while the processor still drains. Every path exists only because the forwarding made this backend the process's second flusher against undocumented SDK internals from the upstream experimental tree; with no `flush()` implemented, the batch processor is the only flusher, its `scheduledDelayMillis` (already deployment-tunable through the `processor` passthrough) governs export cadence, and `shutdown()`'s drain is complete by construction. Reinstate only if a deployment states a turn-boundary latency requirement `scheduledDelayMillis` cannot meet — and then by calling the retained `BatchLogRecordProcessor`'s own `forceFlush()`, never the provider's timeout-wrapped one.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
index b97840405b..d59dcd07e9 100644
--- a/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md
@@ -30,7 +30,7 @@ Status: implemented
 
 **handoff 游标未存活时全量回放日志（重新导出构造函数种子）。** 首轮复活曾交付此方案，其后收窄：接管操作现在从会话的构造边界起回放（`Session.firstLiveSeq`，即构造函数种子长度，这一事实会话早已校验过却未曾暴露；`header.seedLength` 不能胜任：它是持久保存的 fork 谱系（lineage）值，而恢复会话的构造函数种子是其完整的已存储日志）。恢复会话的历史已由上一个进程以同一 id 发出，fork 继承的前缀也已在父会话的流中发出；再次导出任何一者，都会让每次恢复为其完整历史重复付费，并在没有原生摄取去重的 OTLP 后端上使查询时的计数翻倍。接收端基于 `session.parent_id` + `session.seed_length` 拼接 fork 谱系。此次收窄放弃的内容与至多一次立场一致：恢复不再回填上一个进程未能投递的记录（彼时遥测未挂载，或崩溃时仍在队列中）——这本是全量回放唯一的真实收益，代价却由常见情形承担。提出回填要求的部署需要的是上文已推迟的 outbox，而不是回放。该边界同样吞掉 `SessionPersistence.load()` 修复被崩溃打断的日志时写入的合成轮次关闭事件（它们落在 `firstLiveSeq` 之前，尽管在上一个进程中从未存在过）。这是有意为之，而非附带效果：远端轮次的真实尾部记录已随崩溃进程的队列一同消亡，导出合成关闭事件无法补全该轮次，只会让一个未完成的轮次看起来已经关闭。导出的流忠实于崩溃进程实际发出的内容；接收端会把恢复后的流中一个从未关闭的轮次读作「上一个进程死在了该轮次之内」（OTel README 陈述了这条规则），其后干净的 `shutdown` 标记也只证明恢复后进程自身的退出。若为让修复以实时事件的身份导出而将修复前边界贯穿 load/prepare 传递，将使三个包相互耦合，只为抹除这一信号。
 
-**将 seam 的轮次边界 `flush()` 提示转发到 OTel 提供方的 `forceFlush()`。** 首轮复活曾交付此转发，其后移除：三轮评审在同一份包装层状态中各发现一条新的静默丢失路径——dispose 与进行中的 flush 之间的竞态（SDK 的并发 flush 防护会令 shutdown 的内部排空被跳过）、相互重叠的提示顶掉留存的 promise、以及提供方固定的 30 秒 flush 超时在批处理器仍在排空时便 reject。这些路径存在的唯一原因，是该转发让这个后端成为进程内第二个执行 flush 的组件，面对的还是上游实验性（experimental）源码树中未见诸文档的 SDK 内部行为；不实现 `flush()` 时，批处理器就是唯一执行 flush 的组件，其 `scheduledDelayMillis`（已可由部署方经 `processor` passthrough 调优）决定导出节奏，`shutdown()` 的排空从构造上就是完整的。仅当某个部署提出 `scheduledDelayMillis` 无法满足的轮次边界延迟要求时才恢复此转发——且届时应调用留存的 `BatchLogRecordProcessor` 自身的 `forceFlush()`，绝不调用提供方那个带超时包装的版本。
+**将 seam 的轮次边界 `flush()` 提示转发到 OTel 提供方的 `forceFlush()`。** 首轮复活曾交付此转发，其后移除：三条不同的静默丢失路径共用同一份包装层状态——dispose 与进行中的 flush 之间的竞态（SDK 的并发 flush 防护会令 shutdown 的内部排空被跳过）、相互重叠的提示顶掉留存的 promise、以及提供方固定的 30 秒 flush 超时在批处理器仍在排空时便 reject。这些路径存在的唯一原因，是该转发让这个后端成为进程内第二个执行 flush 的组件，面对的还是上游实验性（experimental）源码树中未见诸文档的 SDK 内部行为；不实现 `flush()` 时，批处理器就是唯一执行 flush 的组件，其 `scheduledDelayMillis`（已可由部署方经 `processor` passthrough 调优）决定导出节奏，`shutdown()` 的排空从构造上就是完整的。仅当某个部署提出 `scheduledDelayMillis` 无法满足的轮次边界延迟要求时才恢复此转发——且届时应调用留存的 `BatchLogRecordProcessor` 自身的 `forceFlush()`，绝不调用提供方那个带超时包装的版本。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
index cad70622c8..a5e0f31b2d 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.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 .agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
-2026-07-25-session-list-browsing-and-manual-order.md: bd04e7f74c8a4540d68e60ad68965e05de76bce9
-2026-07-25-session-list-browsing-and-manual-order.zh.md: 2bf778284aa551c75f1206ed08ca073e47b7a15d
+2026-07-25-session-list-browsing-and-manual-order.md: 323c0db16cc6b9e83155a3fb873ab94e4facd3a2
+2026-07-25-session-list-browsing-and-manual-order.zh.md: 85b2b319f03113480b3953c21940c123ba594ca8
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
index bd04e7f74c..323c0db16c 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.md
@@ -44,7 +44,7 @@ ui-sidebar shrinks to the column-geometry shell: brand row, fold state machine,
 
 **Optimistic reordering on drop** — client-first reordering needs failure rollback, one more entangled state in the object layer; local/LAN round-trips are millisecond-scale, so waiting for the host response is imperceptible. With a single order authority (trust the host completely), the frontend never invents an order.
 
-**Keep the rename dialog in ui-sidebar (smallest change)** — that is the problem itself: workspace-domain dialogs scattered in a borrowed slot, with each addition (the Delete confirmation is coming) repeating the cross-package wiring. Review first considered moving only the rename modal; the ruling was to give the whole browsing region to ui-workspace and leave the shell geometry-only.
+**Keep the rename dialog in ui-sidebar (smallest change)** — that is the problem itself: workspace-domain dialogs scattered in a borrowed slot, with each addition (the Delete confirmation is coming) repeating the cross-package wiring. Moving only the rename modal would repeat that wiring on the next dialog; the whole browsing region goes to ui-workspace and the shell stays geometry-only.
 
 **Nest sessions by fork lineage in WorkSpace mode** — nesting makes the current child visible only while its ancestors are expanded and limits in-group manual ordering to root nodes; `parentId` is lineage data, not a list-navigation structure. Flattening all sessions into peer rows lets each row be opened, searched, and ordered independently; In one list still disables drag because it has no workspace persistence carrier.
 
diff --git a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
index 2bf778284a..85b2b319f0 100644
--- a/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md
@@ -44,7 +44,7 @@ ui-sidebar 缩为列几何壳:品牌行、折叠状态机、New Session、Settin
 
 **drop 后乐观重排** —— client 先行重排需失败回滚,对象层多一块纠缠态;本地/局域网往返毫秒级,等 host 响应的简单方案肉眼无感。顺序权威单一化(完全信 host)后,前端永不发明顺序。
 
-**rename 对话框留在 ui-sidebar(最小改动)** —— 正是问题本身:workspace 域的对话框散落在借来的坑里,每加一个(Delete 确认框将至)都重演跨包接线。评审中先议了「只挪 rename Modal」的中间态,最终裁定整个浏览区域归 ui-workspace,壳只留几何。
+**rename 对话框留在 ui-sidebar(最小改动)** —— 正是问题本身:workspace 域的对话框散落在借来的坑里,每加一个(Delete 确认框将至)都重演跨包接线。只挪 rename Modal 会在下一个对话框上重演这份接线;整个浏览区域归 ui-workspace,壳只留几何。
 
 **WorkSpace 模式按 fork 谱系嵌套 session** —— 嵌套会让当前子会话依赖祖先展开态才能可见，也让组内手动序只能移动根节点；`parentId` 是 lineage 数据，不是列表导航结构。所有 session 拍平成同级行后，每行都可独立打开、搜索与排序；In one list 仍因没有 workspace 持久化载体而禁用拖拽。
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml
index 71cb05f10a..6bb0f7e156 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.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 .agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
-2026-07-26-code-dispatch-log-spill.md: 3892a4a5a21c03d97d1873c68e2228119010e5c5
-2026-07-26-code-dispatch-log-spill.zh.md: c98b29e491e059fe27eb5b1ccea1b9664dce4639
+2026-07-26-code-dispatch-log-spill.md: 19d37c7ec2dbe5192e4c7e7ecd26e5b7f1467606
+2026-07-26-code-dispatch-log-spill.zh.md: 8dd270278932011db9658f9e4d5c1a1b6fe707ec
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
index 3892a4a5a2..19d37c7ec2 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-26-code-dispatch-log-spill.zh.md)
 
-> Scope: the fourth PR of the Code Mode UI stack — bounding the `tool/code-dispatch` event's content with the existing spill machinery. The [host foundation note](2026-07-26-code-dispatch-ui-foundation.md) accepted the unbounded log deliberately and named this PR as the payoff point; the [live-parallel note](2026-07-26-code-mode-live-parallel-dispatch.md) settled the event pair this shaping hooks into.
+> Scope: bounding the `tool/code-dispatch` event's content with the existing spill machinery. The [host foundation note](2026-07-26-code-dispatch-ui-foundation.md) accepted the unbounded log deliberately with this spill integration as the payoff point; the [live-parallel note](2026-07-26-code-mode-live-parallel-dispatch.md) settled the event pair this shaping hooks into.
 
 ## Problem
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
index c98b29e491..8dd2702789 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-26-code-dispatch-log-spill.md) | 中文
 
-> 范围：Code Mode UI 堆叠 PR（Pull Request）链的第四个 PR，即用既有的 spill 机制为 `tool/code-dispatch` 事件的内容施加边界。[宿主侧基础 Agent Note](2026-07-26-code-dispatch-ui-foundation.md)当初有意接受了不设上限的日志，并指明本 PR 就是兑现点；[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md)敲定了本次整形所挂接的事件对。
+> 范围：用既有的 spill 机制为 `tool/code-dispatch` 事件的内容施加边界。[宿主侧基础 Agent Note](2026-07-26-code-dispatch-ui-foundation.md)当初有意接受了不设上限的日志，并以这次 spill 集成为兑现点；[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md)敲定了本次整形所挂接的事件对。
 
 ## 问题
 
@@ -20,7 +20,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**在桥接层内部用普通上限施加边界（不做 spill）。** 否决：没有定位符的截断会丢失回放与 UI 可能需要的数据，还会重新引入本堆叠 PR 链已经移除的「截断摘要」降级渲染路径。
+**在桥接层内部用普通上限施加边界（不做 spill）。** 否决：没有定位符的截断会丢失回放与 UI 可能需要的数据，还会重新引入本堆叠 PR（Pull Request）链已经移除的「截断摘要」降级渲染路径。
 
 **直接在桥接层内做 spill（从 code-mode.ts 调用 `ctx.spillStore`）。** 否决：注册表会因此对 spill 能力产生硬依赖；waterfall 则把策略留在所有其他 spill 决策所在的地方，既可组合也可禁用（省略 `maxInlineBytes` 依然意味着真正的 no-op）。
 
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
index e809bdfc6c..4e2d35175f 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.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 .agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
-2026-07-26-code-dispatch-ui-foundation.md: 1714472018a415114efed7ce189a3d82268dd8e3
-2026-07-26-code-dispatch-ui-foundation.zh.md: 8ede615bf15b99c5ecf9a8da427b571180921e54
+2026-07-26-code-dispatch-ui-foundation.md: 4115a1898de7d2cce01346c3f005fcd19c325f4c
+2026-07-26-code-dispatch-ui-foundation.zh.md: aeb57b93d781163dd0a4747ac03053c65deda1db
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
index 1714472018..4115a1898d 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.md
@@ -4,11 +4,11 @@ Status: implemented
 
 English | [中文](2026-07-26-code-dispatch-ui-foundation.zh.md)
 
-> Scope: the host-side contract changes that let a UI render a Code Mode turn with the same fidelity as native tool calls — the first PR of the Code Mode web-UI stack. The [Code Mode foundation](2026-06-15-code-mode.md) owns the transport design; this note owns the model-visible `description` parameter, the full-content `tool/code-dispatch` payload, and the temporary `DSH_TOOLS_MODE` enablement switch for the `dsh` config tree.
+> Scope: the host-side contract changes that let a UI render a Code Mode turn with the same fidelity as native tool calls — the foundation the other Code Mode UI notes build on. The [Code Mode foundation](2026-06-15-code-mode.md) owns the transport design; this note owns the model-visible `description` parameter, the full-content `tool/code-dispatch` payload, and the temporary `DSH_TOOLS_MODE` enablement switch for the `dsh` config tree.
 
 ## Problem
 
-A `run_code` turn was opaque in every product surface. The call card's title was the raw program text — unreadable at row width, and unlike `bash` (whose required `description` labels the card while the command rides the expanded input) there was no model-authored label at all. The `tool/code-dispatch` event carried only a 200-char, cwd-normalized `resultSummary` of each sub-call, so no UI could ever show what a sub-call actually returned: the planned web conversation view renders sub-calls through the exact components that render native `tool/result` cards, and a bounded summary cannot feed a native-parity card. And the `dsh web` composition had no way to enable Code Mode at all — the `tools` row pinned the schema default and the runtime was absent from the tree.
+A `run_code` turn was opaque in every product surface. The call card's title was the raw program text — unreadable at row width, and unlike `bash` (whose required `description` labels the card while the command rides the expanded input) there was no model-authored label at all. The `tool/code-dispatch` event carried only a 200-char, cwd-normalized `resultSummary` of each sub-call, so no UI could ever show what a sub-call actually returned: the web conversation view ([chat sub-call rows](2026-07-26-code-mode-chat-subcall-rows.md)) renders sub-calls through the exact components that render native `tool/result` cards, and a bounded summary cannot feed a native-parity card. And the `dsh web` composition had no way to enable Code Mode at all — the `tools` row pinned the schema default and the runtime was absent from the tree.
 
 ## Decision
 
@@ -20,7 +20,7 @@ Three changes, one per obstacle:
 
 ## Alternatives considered
 
-**Keep a bounded summary (raised cap, or a cap + `truncated` flag).** Rejected: the stack's settled requirement is that sub-call rows and details render *identically* to native calls; any cap forces a second, degraded render path plus truncation UI. The cost accepted instead: a program that reads a large file logs the rendered content verbatim on the dispatch event — uncapped, outside spill policy, growing the session log by the same bytes. Spill integration for the logged copy is deferred to a later PR of this stack (the projection exists; wiring it into the bridge is mechanical once the event shape settles with the start/end pair).
+**Keep a bounded summary (raised cap, or a cap + `truncated` flag).** Rejected: the stack's settled requirement is that sub-call rows and details render *identically* to native calls; any cap forces a second, degraded render path plus truncation UI. The cost accepted instead: a program that reads a large file logs the rendered content verbatim on the dispatch event — uncapped, outside spill policy, growing the session log by the same bytes. Spill integration for the logged copy shipped as [code-dispatch log spill](2026-07-26-code-dispatch-log-spill.md).
 
 **A `--tools-mode` CLI flag or profile key.** Deferred, not rejected: the flag grammar suggests permanence, and the profile json is user config — both would harden a seam the per-session design intends to remove. An env var reads as the workaround it is.
 
@@ -28,4 +28,4 @@ Three changes, one per obstacle:
 
 ## Consequences
 
-Session format keeps `SESSION_FORMAT_VERSION` 0 (pre-release churn does not bump; old logs with `resultSummary` simply carry an extra unread field and lack `content` — v0 makes no compatibility promise). Existing code-mode snapshot fixtures were re-recorded. Model-visible surface grew: the `run_code` schema (one required parameter) and every code-mode system prompt/tool-schema snapshot changed. The web UI stack (subsequent PRs) builds directly on the new event payload; live per-sub-call running state needs a dispatch start/end pair that will reshape this event again.
+Session format keeps `SESSION_FORMAT_VERSION` 0 (pre-release churn does not bump; old logs with `resultSummary` simply carry an extra unread field and lack `content` — v0 makes no compatibility promise). Existing code-mode snapshot fixtures were re-recorded. Model-visible surface grew: the `run_code` schema (one required parameter) and every code-mode system prompt/tool-schema snapshot changed. The web UI work builds directly on the new event payload; live per-sub-call running state reshaped this event into a dispatch start/end pair ([live parallel dispatch](2026-07-26-code-mode-live-parallel-dispatch.md)).
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
index 8ede615bf1..aeb57b93d7 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-dispatch-ui-foundation.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-07-26-code-dispatch-ui-foundation.md) | 中文
 
-> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧约定变更，即 Code Mode Web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用开关，归本篇所有。
+> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧约定变更，即其他 Code Mode UI Agent Note 赖以构建的基础。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用开关，归本篇所有。
 
 ## 问题
 
-`run_code` 轮次过去在每个产品界面上都不透明。调用卡片的标题就是原始程序文本，在行宽内无法阅读；而且不同于 `bash`（其必填的 `description` 用作卡片标签，命令本身放在展开后的输入里），`run_code` 完全没有模型撰写的标签。`tool/code-dispatch` 事件过去只携带每个子调用的 `resultSummary`（上限 200 字符、经 cwd 归一化），因此任何 UI 都无从展示子调用实际返回的内容：规划中的 Web 对话视图会用渲染原生 `tool/result` 卡片的同一批组件来渲染子调用，而有界摘要无法支撑一张与原生同等保真的卡片。同时，`dsh web` 组合此前根本无法启用 Code Mode：`tools` 行钉死在 schema 默认值上，配置树里也完全没有该运行时。
+`run_code` 轮次过去在每个产品界面上都不透明。调用卡片的标题就是原始程序文本，在行宽内无法阅读；而且不同于 `bash`（其必填的 `description` 用作卡片标签，命令本身放在展开后的输入里），`run_code` 完全没有模型撰写的标签。`tool/code-dispatch` 事件过去只携带每个子调用的 `resultSummary`（上限 200 字符、经 cwd 归一化），因此任何 UI 都无从展示子调用实际返回的内容：Web 对话视图（[chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)）会用渲染原生 `tool/result` 卡片的同一批组件来渲染子调用，而有界摘要无法支撑一张与原生同等保真的卡片。同时，`dsh web` 组合此前根本无法启用 Code Mode：`tools` 行钉死在 schema 默认值上，配置树里也完全没有该运行时。
 
 ## 决策
 
@@ -20,7 +20,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**保留有界摘要（提高上限，或上限加 `truncated` 标志）。** 否决：本堆叠 PR 链已敲定的要求是，子调用的行与详情必须与原生调用渲染得*完全一致*；任何上限都会强制引入第二条降级的渲染路径，外加截断 UI。转而接受的代价是：读取大文件的程序会把渲染后的内容原样记录在分发事件上，不设上限、位于 spill 策略之外，并以同样的字节数增大会话日志。持久化副本的 spill 集成推迟到本链靠后的 PR（投影已经存在；待事件形状随 start/end 事件对一同定形，把它接入桥接层只是机械工作）。
+**保留有界摘要（提高上限，或上限加 `truncated` 标志）。** 否决：本堆叠 PR（Pull Request）链已敲定的要求是，子调用的行与详情必须与原生调用渲染得*完全一致*；任何上限都会强制引入第二条降级的渲染路径，外加截断 UI。转而接受的代价是：读取大文件的程序会把渲染后的内容原样记录在分发事件上，不设上限、位于 spill 策略之外，并以同样的字节数增大会话日志。持久化副本的 spill 集成已作为 [code-dispatch 日志 spill](2026-07-26-code-dispatch-log-spill.md) 交付。
 
 **一个 `--tools-mode` CLI（命令行界面）标志或 profile 配置键。** 推迟，而非否决：标志语法暗示永久性，profile JSON 又是用户配置；两者都会固化这个 seam，而按会话选择的设计本就打算移除它。环境变量则如实呈现了它权宜之计的本质。
 
@@ -28,4 +28,4 @@ Status: implemented
 
 ## 后果
 
-会话格式保持 `SESSION_FORMAT_VERSION` 为 0（预发布阶段的变动不递增版本号；携带 `resultSummary` 的旧日志只是多出一个不被读取的字段并缺少 `content`；v0 不作任何兼容性承诺）。既有的 Code Mode 快照 fixture（测试前置数据）已重新录制。模型可见表面扩大了：`run_code` 的 schema（新增一个必填参数）以及每一份 Code Mode 系统提示词／工具 schema 快照都发生了变化。Web UI 堆叠 PR 链（后续各 PR）直接构建在新的事件载荷之上；每个子调用的实时运行状态还需要一对分发 start/end 事件，这将再次重塑本事件的形状。
+会话格式保持 `SESSION_FORMAT_VERSION` 为 0（预发布阶段的变动不递增版本号；携带 `resultSummary` 的旧日志只是多出一个不被读取的字段并缺少 `content`；v0 不作任何兼容性承诺）。既有的 Code Mode 快照 fixture（测试前置数据）已重新录制。模型可见表面扩大了：`run_code` 的 schema（新增一个必填参数）以及每一份 Code Mode 系统提示词／工具 schema 快照都发生了变化。Web UI 工作直接构建在新的事件载荷之上；每个子调用的实时运行状态已把本事件重塑为一对分发 start/end 事件（[实时并行分发](2026-07-26-code-mode-live-parallel-dispatch.md)）。
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml
index 390144b4bd..7a93dad472 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.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 .agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
-2026-07-26-code-mode-chat-subcall-rows.md: 40b4b8fd8c5cea8e9aea01731d7eceff692db188
-2026-07-26-code-mode-chat-subcall-rows.zh.md: 9981fded054f663dd539660ed2a2eca68a9d3138
+2026-07-26-code-mode-chat-subcall-rows.md: 4bf608c36de78818b3ab40c6798ee6eafabe99a1
+2026-07-26-code-mode-chat-subcall-rows.zh.md: 98680a90bf613ba2dd9b974a809ea5300400f9ea
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
index 40b4b8fd8c..4bf608c36d 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.md
@@ -29,4 +29,4 @@ With Code Mode enabled, the chat view showed one opaque `run_code` row: raw prog
 
 ## Consequences
 
-Custom toolview registrations apply to sub-calls for free — and deliberately: there is no per-registration opt-out short of the component reading its own context, which no current consumer needs. Selection highlighting reaches nested rows through the same `selectedCallId` channel (group membership searches the whole tree). Trajectory/waterfall still render `run_code` as a single row — their sub-call spans are deferred to the PR that adds dispatch timing (start/end events), without which a waterfall span would be a lie. Fixture turn 64 (`?fixture`) plus the `code-mode-round` browser e2e (recorded real round, keyless replay) pin the full surface; the jsdom and Runtime suites pin slot dispatch, error states, recursive details resolution, history projection, and reference-stable path copying.
+Custom toolview registrations apply to sub-calls for free — and deliberately: there is no per-registration opt-out short of the component reading its own context, which no current consumer needs. Selection highlighting reaches nested rows through the same `selectedCallId` channel (group membership searches the whole tree). Trajectory/waterfall now draw sub-call spans from the dispatch timing pair ([live parallel dispatch](2026-07-26-code-mode-live-parallel-dispatch.md)); without that timing a waterfall span would be a lie. Fixture turn 64 (`?fixture`) plus the `code-mode-round` browser e2e (recorded real round, keyless replay) pin the full surface; the jsdom and Runtime suites pin slot dispatch, error states, recursive details resolution, history projection, and reference-stable path copying.
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
index 9981fded05..98680a90bf 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-chat-subcall-rows.zh.md
@@ -29,4 +29,4 @@ Status: implemented
 
 ## 后果
 
-自定义 toolview 注册免费适用于子调用——而且是刻意为之：不存在按注册粒度的退出机制，唯一的出路是组件自行读取自身上下文，而当前没有任何消费方需要这么做。选中高亮经由同一条 `selectedCallId` 通道到达嵌套行（分组归属会搜索整棵树）。trajectory/waterfall 仍把 `run_code` 渲染为单独一行——它们的子调用 span 推迟到增加分发计时（start/end 事件）的那个 PR；缺少计时，waterfall 上的 span 就是在撒谎。fixture（测试前置数据）的轮次 64（`?fixture`），加上 `code-mode-round` 浏览器 e2e（录制的真实轮次、无密钥回放），共同锁定整个界面；jsdom 与运行时测试套件则锁定 slot 分发、错误状态、递归详情解析、历史投影与引用稳定的路径复制。
+自定义 toolview 注册免费适用于子调用——而且是刻意为之：不存在按注册粒度的退出机制，唯一的出路是组件自行读取自身上下文，而当前没有任何消费方需要这么做。选中高亮经由同一条 `selectedCallId` 通道到达嵌套行（分组归属会搜索整棵树）。trajectory/waterfall 现在依据分发计时事件对（[实时并行分发](2026-07-26-code-mode-live-parallel-dispatch.md)）绘制子调用 span；缺少计时，waterfall 上的 span 就是在撒谎。fixture（测试前置数据）的轮次 64（`?fixture`），加上 `code-mode-round` 浏览器 e2e（录制的真实轮次、无密钥回放），共同锁定整个界面；jsdom 与运行时测试套件则锁定 slot 分发、错误状态、递归详情解析、历史投影与引用稳定的路径复制。
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
index 2b12308db9..bee49da3ab 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.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 .agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
-2026-07-26-code-mode-live-parallel-dispatch.md: e85d1f99f58f1aae28091cd8875ee87a6df5a1e7
-2026-07-26-code-mode-live-parallel-dispatch.zh.md: c7f91f570e20e27aade0e8f47606d31b1d8ae7eb
+2026-07-26-code-mode-live-parallel-dispatch.md: 998152ee43d93e5190062cb632e20a3123cda4f9
+2026-07-26-code-mode-live-parallel-dispatch.zh.md: ac9b06cf1f2c197d4a8ea1dd69c8fb0840878097
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
index e85d1f99f5..998152ee43 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.md
@@ -4,11 +4,11 @@ Status: implemented
 
 English | [中文](2026-07-26-code-mode-live-parallel-dispatch.zh.md)
 
-> Scope: the third PR of the Code Mode UI stack — the `tool/code-dispatch-start` event, per-sub-call running state in the web chat, and the bridge's scheduler reusing the native concurrency contract. Builds on the [host foundation](2026-07-26-code-dispatch-ui-foundation.md) and [chat sub-call rows](2026-07-26-code-mode-chat-subcall-rows.md); the native contract itself is owned by the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md).
+> Scope: the `tool/code-dispatch-start` event, per-sub-call running state in the web chat, and the bridge's scheduler reusing the native concurrency contract. Builds on the [host foundation](2026-07-26-code-dispatch-ui-foundation.md) and [chat sub-call rows](2026-07-26-code-mode-chat-subcall-rows.md); the native contract itself is owned by the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md).
 
 ## Problem
 
-Two gaps remained after the first two PRs. Sub-call rows appeared only when each dispatch *settled* — while one ran, the UI showed nothing for it, so a slow sub-call read as a stalled parent. And the bridge serialized every binding call ("even `Promise.all` executes one at a time"), a placeholder from before tools carried concurrency metadata: `isConcurrencySafe` now exists, the loop scheduler already runs native siblings in bounded pools, and a Code Mode program awaiting three independent reads paid 3× the latency the native path would.
+Two gaps remained after the host foundation and chat sub-call rows shipped. Sub-call rows appeared only when each dispatch *settled* — while one ran, the UI showed nothing for it, so a slow sub-call read as a stalled parent. And the bridge serialized every binding call ("even `Promise.all` executes one at a time"), a placeholder from before tools carried concurrency metadata: `isConcurrencySafe` now exists, the loop scheduler already runs native siblings in bounded pools, and a Code Mode program awaiting three independent reads paid 3× the latency the native path would.
 
 ## Decision
 
@@ -29,4 +29,4 @@ Two gaps remained after the first two PRs. Sub-call rows appeared only when each
 
 ## Consequences
 
-Programs get native-grade latency for independent reads with no new model-side API — `Promise.all` simply works better, and prompt guidance changed accordingly. The web UI shows per-sub-call running rings live (fixture emits start/settle pairs; jsdom pins the running shape; the runtime spec pins in-place settlement, out-of-order completion, and callTime pairing). PR6 (trajectory/waterfall spans) can now draw truthful spans from the pair's timing. The spill PR (next) inherits the settle event as its single bounding point.
+Programs get native-grade latency for independent reads with no new model-side API — `Promise.all` simply works better, and prompt guidance changed accordingly. The web UI shows per-sub-call running rings live (fixture emits start/settle pairs; jsdom pins the running shape; the runtime spec pins in-place settlement, out-of-order completion, and callTime pairing). Trajectory/waterfall sub-call spans draw truthful timing from the pair. Spill bounding ([code-dispatch log spill](2026-07-26-code-dispatch-log-spill.md)) inherits the settle event as its single bounding point.
diff --git a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
index c7f91f570e..ac9b06cf1f 100644
--- a/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-code-mode-live-parallel-dispatch.zh.md
@@ -4,11 +4,11 @@ Status: implemented
 
 [English](2026-07-26-code-mode-live-parallel-dispatch.md) | 中文
 
-> 范围：Code Mode UI 堆叠 PR（Pull Request）链的第三个 PR，涵盖 `tool/code-dispatch-start` 事件、Web chat 中每个子调用的运行状态，以及桥接层调度器对原生并发约定的复用。构建在[宿主侧基础](2026-07-26-code-dispatch-ui-foundation.md)与 [chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)之上；原生约定本身归[并行工具调用 Agent Note](2026-07-10-parallel-tool-call-execution.md) 所有。
+> 范围：`tool/code-dispatch-start` 事件、Web chat 中每个子调用的运行状态，以及桥接层调度器对原生并发约定的复用。构建在[宿主侧基础](2026-07-26-code-dispatch-ui-foundation.md)与 [chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)之上；原生约定本身归[并行工具调用 Agent Note](2026-07-10-parallel-tool-call-execution.md) 所有。
 
 ## 问题
 
-前两个 PR 之后仍留有两个缺口。子调用行过去只在每次分发*结算*后才出现：某次分发运行期间，UI 对它毫无展示，于是一个慢的子调用看上去就像父调用卡住了。而桥接层过去把每一次绑定调用都串行化（「即使 `Promise.all` 也一次只执行一个」），这是工具尚未携带并发元数据时留下的占位实现：如今 `isConcurrencySafe` 已经存在，agent loop（智能体循环）调度器早已在有界并发池中运行原生兄弟调用，而一个等待三个独立读取的 Code Mode 程序，付出的延迟却是原生路径的 3 倍。
+宿主侧基础与 chat 子调用行交付之后仍留有两个缺口。子调用行过去只在每次分发*结算*后才出现：某次分发运行期间，UI 对它毫无展示，于是一个慢的子调用看上去就像父调用卡住了。而桥接层过去把每一次绑定调用都串行化（「即使 `Promise.all` 也一次只执行一个」），这是工具尚未携带并发元数据时留下的占位实现：如今 `isConcurrencySafe` 已经存在，agent loop（智能体循环）调度器早已在有界并发池中运行原生兄弟调用，而一个等待三个独立读取的 Code Mode 程序，付出的延迟却是原生路径的 3 倍。
 
 ## 决策
 
@@ -29,4 +29,4 @@ Status: implemented
 
 ## 后果
 
-程序不需要任何新的模型侧 API，独立读取就获得了原生级的延迟：`Promise.all` 直接变得更好用，提示词指引也随之修改。Web UI 实时显示每个子调用的运行指示环：fixture（测试前置数据）发出成对的 start/settle 事件；jsdom 锁定运行中形状；运行时测试锁定原位结算、乱序完成与 callTime 配对。PR6（trajectory/waterfall 的 span）现在可以依据这对事件的计时绘制如实的 span。spill PR（下一个）则继承结算事件，作为自己唯一施加边界的位置。
+程序不需要任何新的模型侧 API，独立读取就获得了原生级的延迟：`Promise.all` 直接变得更好用，提示词指引也随之修改。Web UI 实时显示每个子调用的运行指示环：fixture（测试前置数据）发出成对的 start/settle 事件；jsdom 锁定运行中形状；运行时测试锁定原位结算、乱序完成与 callTime 配对。trajectory/waterfall 的子调用 span 从这对事件取得如实的计时。spill 边界施加（[code-dispatch 日志 spill](2026-07-26-code-dispatch-log-spill.md)）则继承结算事件，作为自己唯一施加边界的位置。
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
index 90ea440ef8..9f98597809 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.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 .agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
-2026-07-26-todo-parallel-in-progress.md: 8d047f33ab1aebd8c0de2a0a5e90e7efb1b28154
-2026-07-26-todo-parallel-in-progress.zh.md: ebd4b1567eba637493956993b43b1ec56df14c39
+2026-07-26-todo-parallel-in-progress.md: 5664960ce94dfac60d89cb363ea62459dd51f59e
+2026-07-26-todo-parallel-in-progress.zh.md: f346f89fcae5e8607c5608bbf7541ada0bae4593
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
index 8d047f33ab..5664960ce9 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
@@ -33,11 +33,11 @@ The durable-log invariant deliberately does NOT follow the flag. A log written w
 
 - **Keep the cap and add an explicit parallel opt-in flag** — an extra argument on every call to serve the common case; the flag would be noise for sequential work and still unverifiable.
 - **Cap active items at a configured maximum** — any fixed number is arbitrary. This is why the config field is a boolean policy switch and not a count: "may several tasks be active" is a property of the deployment, while "at most N" invents a threshold nothing can justify.
-- **Hardcode the parallel policy** — the first revision of this branch did, which is what made `allowParallelInProgress` necessary: a deployment running strictly sequential agents had no way back to the discipline it wanted.
+- **Hardcode the parallel policy** — the first revision of this change did, which is what made `allowParallelInProgress` necessary: a deployment running strictly sequential agents had no way back to the discipline it wanted.
 
 ## The display surfaces are part of the change
 
-Lifting the cap makes a list shape reachable that no renderer had ever received, so this branch stacks on the [web todo display](2026-07-23-web-todo-display.md) rather than landing beside it: both change `tool-todo`, and the GUI is where a parallel plan becomes visible. Two web sites derived their one-line summary with `todos.find(t => t.status === 'in_progress')` — the collapsed plan-strip header and the `todo_write` row — and under the old cap that `find` was total, since at most one item could match. With several active it silently dropped every active item but the first: a four-item plan with three running tasks collapsed to the name of one, and the row read `1/4 已完成 · <one task>` while two others were in flight. The expanded list was always correct (it maps every item), which is why neither PR's tests caught it — only the collapsed header and the row lost information. The panel redesign replaced the collapsed header's named hint with `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted), which reports parallel work correctly and needs no name to truncate; the row is the one site this branch still had to fix.
+Lifting the cap makes a list shape reachable that no renderer had ever received, so this change builds on the [web todo display](2026-07-23-web-todo-display.md) rather than landing beside it: both change `tool-todo`, and the GUI is where a parallel plan becomes visible. Two web sites derived their one-line summary with `todos.find(t => t.status === 'in_progress')` — the collapsed plan-strip header and the `todo_write` row — and under the old cap that `find` was total, since at most one item could match. With several active it silently dropped every active item but the first: a four-item plan with three running tasks collapsed to the name of one, and the row read `1/4 已完成 · <one task>` while two others were in flight. The expanded list was always correct (it maps every item), which is why neither change's tests caught it — only the collapsed header and the row lost information. The panel redesign replaced the collapsed header's named hint with `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted), which reports parallel work correctly and needs no name to truncate; the row is the one site this change still had to fix.
 
 The row takes `planSummary` in `toolviews/plan-summary.ts`. It names the first active item and counts the rest, so the row reports how many tasks are running instead of implying one. Naming every active item was rejected: the row is a single line, and an unbounded join would overflow it — the count degrades predictably where a list does not. The derivation sits inside the toolviews domain rather than in `contract/`, the inter-domain face: the panel computes its own counts inline and shares nothing with the row, so a contract module would declare a sharing relationship that no longer exists.
 
@@ -47,8 +47,8 @@ The row takes `planSummary` in `toolviews/plan-summary.ts`. It names the first a
 
 ## Deferred
 
-Two review findings are recorded here rather than fixed on this branch. The `summarySuffix` span carries no accessible name, so a screen reader reads the count without its noun (`… 实现 fixture 样本 +1`); naming it introduces localized copy with its own test contract, which belongs to an accessibility pass over the whole `ToolRow` summary line rather than to one row. And when the *first* active item's content is unusable — missing, mistyped, or blank once trimmed — the row drops the active clause and the count with it, so a parallel plan renders as bare counts; skipping forward to the first usable active item was rejected because call args are an explicitly unvalidated boundary where model order is the only ordering the row can honour, and dropping the unusable clause alone keeps the `done`/`total` counts, which are trustworthy regardless.
+Two known gaps are deferred. The `summarySuffix` span carries no accessible name, so a screen reader reads the count without its noun (`… 实现 fixture 样本 +1`); naming it introduces localized copy with its own test contract, which belongs to an accessibility pass over the whole `ToolRow` summary line rather than to one row. And when the *first* active item's content is unusable — missing, mistyped, or blank once trimmed — the row drops the active clause and the count with it, so a parallel plan renders as bare counts; skipping forward to the first usable active item was rejected because call args are an explicitly unvalidated boundary where model order is the only ordering the row can honour, and dropping the unusable clause alone keeps the `done`/`total` counts, which are trustworthy regardless.
 
 ## Consequences
 
-A todo list can now faithfully mirror parallel execution, and every surface renders several active markers at once: the plan strip's header counts the active items, and the row needed the derivation above. A composition that sets `allowParallelInProgress: true` no longer rejects a formerly-invalid snapshot shape; one that sets `false` keeps the old rejection, and the durable-log invariant accepts both. The model-facing description changed, which re-recorded the tool-catalog page and every snapshot sidecar carrying the todo schema. No count is recorded here: the set grows with every pinning scenario that lands, and the two point-in-time censuses this note previously carried were both stale within days. The operative rule is that a branch changing the tool description must refresh whichever sidecars landed after it branched — including the numbered `tool-schemas.<n>.expected.json` files pinning a subagent class, whose schemas the parent scenario does not cover — and `pnpm run test:snapshot:refresh` does it keylessly over the whole corpus. The web fixture's todo sample now runs two items `in_progress`, so both fixture-driven surfaces render a parallel plan. `packages/client/ui-conversation/tests/todo-panel.spec.tsx` pins the row summary and the plan strip over src, the ACP `todo-write` scenario records a three-todo plan with two active, and `apps/web/tests/todo-row.snapshot.ts` pins both surfaces in the assembled application — booted from the built `packages/client/*/lib/client.js` bundles, so it is the one place the keyed registration and the bundled wiring are under test. That last file records `summary`, `suffix`, and the strip's header as separate fields, so folding the `+N` count back into the summary string changes the expected output even though the concatenated text would read the same.
+A todo list can now faithfully mirror parallel execution, and every surface renders several active markers at once: the plan strip's header counts the active items, and the row needed the derivation above. A composition that sets `allowParallelInProgress: true` no longer rejects a formerly-invalid snapshot shape; one that sets `false` keeps the old rejection, and the durable-log invariant accepts both. The model-facing description changed, which re-recorded the tool-catalog page and every snapshot sidecar carrying the todo schema. No count is recorded here: the set grows with every pinning scenario that lands. The operative rule is that a branch changing the tool description must refresh whichever sidecars landed after it branched — including the numbered `tool-schemas.<n>.expected.json` files pinning a subagent class, whose schemas the parent scenario does not cover — and `pnpm run test:snapshot:refresh` does it keylessly over the whole corpus. The web fixture's todo sample now runs two items `in_progress`, so both fixture-driven surfaces render a parallel plan. `packages/client/ui-conversation/tests/todo-panel.spec.tsx` pins the row summary and the plan strip over src, the ACP `todo-write` scenario records a three-todo plan with two active, and `apps/web/tests/todo-row.snapshot.ts` pins both surfaces in the assembled application — booted from the built `packages/client/*/lib/client.js` bundles, so it is the one place the keyed registration and the bundled wiring are under test. That last file records `summary`, `suffix`, and the strip's header as separate fields, so folding the `+N` count back into the summary string changes the expected output even though the concatenated text would read the same.
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
index ebd4b1567e..f346f89fca 100644
--- a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
@@ -33,11 +33,11 @@ Status: implemented
 
 - **保留上限并增加一个显式的并行 opt-in 标志**——为服务常见场景而给每次调用增加一个额外参数；这个标志对顺序工作而言只是噪声，而且仍然无法验证。
 - **把活跃条目限制在一个可配置的上限内**——任何固定数字都是任意的。这正是该配置字段是布尔策略开关而非数量的原因：「是否允许多个任务同时活跃」是部署的属性，而「最多 N 个」凭空发明了一个无从论证的阈值。
-- **把并行策略硬编码**——本分支的第一版就是如此，这也是 `allowParallelInProgress` 之所以必要的原因：运行严格顺序 agent 的部署没有任何办法回到它想要的纪律。
+- **把并行策略硬编码**——本变更的第一版就是如此，这也是 `allowParallelInProgress` 之所以必要的原因：运行严格顺序 agent 的部署没有任何办法回到它想要的纪律。
 
 ## 展示面是本次改动的一部分
 
-解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本分支 stack（栈叠）在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个 PR（Pull Request）的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。面板重做把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本分支仍需修的那一处。
+解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本变更构建在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个变更的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。面板重做把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本变更仍需修的那一处。
 
 工具行改用 `toolviews/plan-summary.ts` 中的 `planSummary`。它给出第一个活跃条目，并计数其余活跃项，因此工具行报告的是有多少任务在跑，而不是暗示只有一个。列出全部活跃条目被否决了：工具行是单行，无上界的拼接会溢出——在列表做不到的地方，计数能够可预测地降级。该推导放在 toolviews 域内而非 `contract/`（域间共享面）：面板自行内联计算其计数，与工具行不共享任何东西，因此放进 contract 会声明一种已不存在的共享关系。
 
@@ -47,8 +47,8 @@ Status: implemented
 
 ## 暂缓项
 
-两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试约定的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
+两个已知缺口暂缓处理。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试约定的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
 
 ## 后果
 
-现在 todo 列表可以忠实反映并行执行，并且每个展示面都能一次渲染多个活跃标记：计划横条的表头会计数活跃条目，工具行则需要上述推导。设置 `allowParallelInProgress: true` 的组合不再拒绝一种此前无效的快照形状；设置为 `false` 的组合仍保留旧的拒绝行为，而持久日志不变式两者都接受。面向模型的描述发生了变化，这重新记录了 tool-catalog 页面以及每个带有 todo schema 的快照伴随文件。此处不记录数量：该集合会随每个新落地的 pin 场景增长，而本 Agent Note 先前记过的两次时点统计都在几天内失实。有效规则是：改动工具描述的分支必须刷新它分叉之后落地的那些伴随文件——包括固定 subagent 类工具的编号文件 `tool-schemas.<n>.expected.json`，其 schema 不被父场景覆盖——`pnpm run test:snapshot:refresh` 可以无 key 地对整个语料完成刷新。web fixture（测试前置数据）的 todo 样本现在有两个条目处于 `in_progress`，因此两个由 fixture 驱动的展示面渲染的都是并行计划。`packages/client/ui-conversation/tests/todo-panel.spec.tsx` 在 src 上固定工具行摘要与计划横条，ACP（Agent Client Protocol）`todo-write` 场景录制的是三条目、两个活跃的计划，而 `apps/web/tests/todo-row.snapshot.ts` 在组装后的应用中固定这两个面——它从构建产物 `packages/client/*/lib/client.js` 启动，因此是唯一覆盖 keyed 注册与打包接线的地方。该文件把 `summary`、`suffix` 与横条表头记录为独立字段，因此即便拼接后的文本读起来一样，把 `+N` 计数折回摘要字符串也会改变预期输出。
+现在 todo 列表可以忠实反映并行执行，并且每个展示面都能一次渲染多个活跃标记：计划横条的表头会计数活跃条目，工具行则需要上述推导。设置 `allowParallelInProgress: true` 的组合不再拒绝一种此前无效的快照形状；设置为 `false` 的组合仍保留旧的拒绝行为，而持久日志不变式两者都接受。面向模型的描述发生了变化，这重新记录了 tool-catalog 页面以及每个带有 todo schema 的快照伴随文件。此处不记录数量：该集合会随每个新落地的 pin 场景增长。有效规则是：改动工具描述的分支必须刷新它分叉之后落地的那些伴随文件——包括固定 subagent 类工具的编号文件 `tool-schemas.<n>.expected.json`，其 schema 不被父场景覆盖——`pnpm run test:snapshot:refresh` 可以无 key 地对整个语料完成刷新。web fixture（测试前置数据）的 todo 样本现在有两个条目处于 `in_progress`，因此两个由 fixture 驱动的展示面渲染的都是并行计划。`packages/client/ui-conversation/tests/todo-panel.spec.tsx` 在 src 上固定工具行摘要与计划横条，ACP（Agent Client Protocol）`todo-write` 场景录制的是三条目、两个活跃的计划，而 `apps/web/tests/todo-row.snapshot.ts` 在组装后的应用中固定这两个面——它从构建产物 `packages/client/*/lib/client.js` 启动，因此是唯一覆盖 keyed 注册与打包接线的地方。该文件把 `summary`、`suffix` 与横条表头记录为独立字段，因此即便拼接后的文本读起来一样，把 `+N` 计数折回摘要字符串也会改变预期输出。
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
index 2e5c66b55c..65a917c3eb 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
-2026-07-28-continuable-subagent-conversations.md: 991b89599d7f300c79928e568833a2cd488f5a4e
-2026-07-28-continuable-subagent-conversations.zh.md: a7d282c4fadd943ad9250e01de5d379a776a32a0
+2026-07-28-continuable-subagent-conversations.md: 8408cf27003c011e140c3f426d81f3ba5af76b06
+2026-07-28-continuable-subagent-conversations.zh.md: e6f7bcc7d4f70edb8cbbe1ac88b9bdd7ac2e11a5
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
index 991b89599d..8408cf2700 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md
@@ -105,7 +105,7 @@ When the authenticated parent is itself a continuation-managed Activation, start
 
 Child release occurs only after the child Agent is quiescent, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal. The manager awaits `ctx.sessions.flush(child.session)` but does not interpret its participation boolean: an arbitrary listener cannot prove that the selected persistence backend stored the state. A rejection is logged without preventing handle disposal or ownership release, because retaining a child would permanently pin its ancestors in `waiting`. If the child is owned, the manager then resolves the live parent through `SessionHeader.parentSession` and removes the child Session id from its `ownedChildren`. Manager teardown uses the same child-first order.
 
-Ownership is retained until the child Activation is disposed. A later refinement may release a request-scoped lease earlier, but it would require an exact turn-completion correlation that this Task-free proposal deliberately does not add.
+Ownership is retained until the child Activation is disposed. A later refinement may release a request-scoped lease earlier, but it would require an exact turn-completion correlation that this Task-free design deliberately does not add.
 
 Top-level teardown is host-owned rather than represented as another Activation. Manager unload invokes its internal manager-wide drain to close admission synchronously, await every admitted materialization through publication or rollback, stop the stable live forest, and release it child-first. A host that owns selected top-level Agents uses `drainContinuableDescendants(parents)`: exact Agent identities close admission only below those roots until each leaves the registry, while unrelated forests and manager-wide admission remain live; the manager stops their visible descendants before its first await, waits only materializations admitted below those roots, and releases only the selected branches. Every materialized start and live delivery rechecks caller cancellation, the applicable draining scope, Activation disposal, and exact parent authority in the same synchronous span as inbox submission, so teardown or parent replacement that wins before acceptance prevents delivery to the closing handle. Only after the applicable drain settles may the host dispose its top-level Agents; only manager-wide drain precedes manager-scope disposal.
 
@@ -149,7 +149,7 @@ It adds no host-user continuation, subagent steering operation, durable mailbox,
 
 ## Alternatives considered
 
-**Keep Task-backed Activations.** Tasks provide generic status, result collection, and cancellation, but using them for conversation delivery creates a second queue and duplicates turn ownership. The proposal gives up those generic Task controls so the Agent inbox remains the only execution order.
+**Keep Task-backed Activations.** Tasks provide generic status, result collection, and cancellation, but using them for conversation delivery creates a second queue and duplicates turn ownership. This design gives up those generic Task controls so the Agent inbox remains the only execution order.
 
 **Create one Activation per `next-turn`.** This restores independent result and cancellation boundaries, but it requires a manager FIFO beside the Agent inbox and makes a retained Agent cross artificial Activation boundaries. One Activation per residency epoch is smaller and follows the `AgentHandle` lifetime directly.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
index a7d282c4fa..e6f7bcc7d4 100644
--- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md
@@ -105,7 +105,7 @@ Agent inbox 是唯一队列。每条继续执行消息都使用 `Agent.followup(
 
 只有在 child Agent 完全停稳、该 child 持有的每个 child 都已 dispose、best-effort 的最终会话 flush 结算且 child 的 `AgentHandle` 完成 dispose 后，系统才释放 child。管理器会等待 `ctx.sessions.flush(child.session)`，但不解释其参与布尔值：任意 listener 都无法证明所选持久化后端已存储该状态。rejection 会被记录，但不会阻止 handle dispose 或释放所有权，因为保留 child 会让其祖先永久固定在 `waiting`。如果 child 归 parent 所有，管理器随后会通过 `SessionHeader.parentSession` 解析在线 parent，并从其 `ownedChildren` 中移除 child 会话 id。管理器拆卸使用相同的 child-first 顺序。
 
-系统会一直保留所有权，直至 child 激活完成 dispose。后续改进可以更早释放限定到请求的 lease，但这需要精确关联轮次完成，而本 Task-free 提案特意不增加该机制。
+系统会一直保留所有权，直至 child 激活完成 dispose。后续改进可以更早释放限定到请求的 lease，但这需要精确关联轮次完成，而本 Task-free 设计特意不增加该机制。
 
 顶层拆卸由宿主负责，而不表示为另一次激活。管理器卸载会调用其内部的管理器全局 drain，同步关闭准入，等待每个已获准的物化过程完成发布或回滚，停止稳定的在线森林，并按 child-first 顺序释放。拥有选定顶层 Agent 的宿主使用 `drainContinuableDescendants(parents)`：确切的 Agent 身份只关闭这些根之下的准入，直到每个身份离开注册表，而无关森林和管理器全局准入保持在线；管理器会在第一次 await 之前停止其可见后代，只等待这些根之下已获准的物化过程，并且只释放选定分支。每个已物化的 start 和在线投递都会在与 inbox 提交相同的同步区间内重新检查调用方取消、适用的 draining 作用域、Activation dispose 和确切的 parent 权限，因此只要拆卸或 parent 替换先于接受发生，就会阻止向正在关闭的 handle 投递。只有适用的 drain 结算后，宿主才能 dispose 自己的顶层 Agent；只有管理器全局 drain 会先于管理器作用域 dispose。
 
@@ -149,7 +149,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
 
 ## 曾考虑的替代方案
 
-**保留由 Task 支撑的激活。** Task 可以提供通用状态、结果收集和取消，但使用 Task 投递会话会产生第二条队列，并重复轮次所有权。本提案放弃这些通用 Task 控制，让 Agent inbox 成为唯一执行顺序。
+**保留由 Task 支撑的激活。** Task 可以提供通用状态、结果收集和取消，但使用 Task 投递会话会产生第二条队列，并重复轮次所有权。本设计放弃这些通用 Task 控制，让 Agent inbox 成为唯一执行顺序。
 
 **每个 `next-turn` 创建一次激活。** 这会恢复独立的结果与取消边界，但需要在 Agent inbox 旁维护管理器 FIFO，还会使所保留的 Agent 跨越人为划分的激活边界。每个驻留周期对应一次激活更小，也直接跟随 `AgentHandle` 生命周期。
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.i18n.yaml
index 84a93cde2d..68716d20a2 100644
--- a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.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 .agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md
-2026-07-28-todo-plan-clears-on-next-turn.md: 8a2808f5023a0800fbbeb65c5e28b3495e051dbc
-2026-07-28-todo-plan-clears-on-next-turn.zh.md: c96485ec2d5b0faea0682624cde9a7569cd2e227
+2026-07-28-todo-plan-clears-on-next-turn.md: 55a0d4f307bef5cd04add0baae220ea763772ee9
+2026-07-28-todo-plan-clears-on-next-turn.zh.md: e881884443b06b780c12d348c7ecca4a88801b73
diff --git a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md
index 8a2808f502..55a0d4f307 100644
--- a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md
+++ b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md
@@ -18,7 +18,7 @@ The standing plan is the latest `todo/write` that is not followed by a later `tu
 
 ### TUI live path
 
-The TUI `renderEvent` switch still clears its local plan panel on `turn/start` and replaces it on `todo/write` (TUI is not yet a projection carrier). The rebuild path resets the panel before replaying the log so cold resume converges on the same rule.
+The former TUI's `renderEvent` switch cleared its local plan panel on `turn/start` and replaced it on `todo/write`, with its rebuild path resetting the panel before replay so cold resume converged on the same rule; that package has since been removed ([remove TUI package](../simplification/2026-08-04-remove-tui-package.md)).
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md
index c96485ec2d..e881884443 100644
--- a/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 ### TUI 实时路径
 
-TUI 的 `renderEvent` 分支仍在 `turn/start` 清空本地计划面板、在 `todo/write` 替换之（TUI 尚非投影载体）。重建路径在回放日志前重置面板，使冷恢复收敛到同一规则。
+原 TUI 的 `renderEvent` 分支曾在 `turn/start` 清空本地计划面板、在 `todo/write` 替换之，其重建路径在回放前重置面板，使冷恢复收敛到同一规则；该包其后已被移除（[移除 TUI 包](../simplification/2026-08-04-remove-tui-package.md)）。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
index 65af28ee2e..781c07f8f3 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.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 .agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
-2026-07-28-web-terminal-card.md: 0338fa1cdb4a19177bddd4181661173bf75492b0
-2026-07-28-web-terminal-card.zh.md: f9dc686cfbf817fe5a1c15b8d5a94e3f8ab2adee
+2026-07-28-web-terminal-card.md: 84e5cdb786944b014fd3a687cfefad6768174006
+2026-07-28-web-terminal-card.zh.md: 58c236bda9c45e13fda0f965f84af24b3c831bb4
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
index 0338fa1cdb..84e5cdb786 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md
@@ -20,7 +20,7 @@ The component's contract:
 - **One run-state dot for the call, on the first row.** `StateDot` in three of its four states: the chase while running, red for the exit status that also renders the pill, green for a clean settle — the same indicator a tool row's leading icon uses, so a row and its own card cannot disagree about one command. The dot exists because the first question a reader has about a shell command is whether it is still running, and without it that had to be inferred from the absence of output — which a settled command producing no output also looks like. It sits out of flow in a gutter the card reserves as its OWN left padding, so it neither indents its command nor depends on the command's text metrics to line up. The reservation is padding rather than margin because every render site rewrites `margin` wholesale to set its own indent, which silently cancelled a margin-based gutter and let a container clip the dot. Exactly one dot, whatever the line count: the exit status the view carries is the whole call's, and bash reports no per-command status, so a dot per line would assert of a line that succeeded inside a failing call that the line itself failed. The single visually hidden text label carries the same scope, since `StateDot` is `aria-hidden` and one label per row would read to assistive technology as several distinct outcomes.
 - **No soft wrapping.** Output lines are `white-space: pre` inside a horizontally scrolling box. Column alignment survives; a long line scrolls instead of folding.
 - **Height cap with an expand control.** Output longer than `DEFAULT_TERMINAL_MAX_LINES` (16) lines shows `ceil(max/2)` head lines plus the remaining tail lines, with a button in between that reports the hidden count and expands. The count is of parsed lines after the trailing output terminator is dropped, so an N-line output ending in a newline is N lines. The split arithmetic preserves the former TUI transcript's collapsed-card behavior, so the established head/tail selection stays stable.
-- **ANSI color.** `anser` splits the SGR runs; `ui-primitives/src/ansi.ts` resolves each run into an inline style rendered as React spans. A foreground-only run maps the basic 16 colors onto `--dsw-*` theme tokens so authored color stays legible under both themes; a run that paints its own background keeps anser's literal rgb for both so its intended contrast survives, as do 256-palette, truecolor, and the two basic colors this design system has no token for. Sequences that carry no color (OSC strings, non-CSI escapes, inert C0 controls) are stripped before parsing so they never reach the DOM as literal characters. Cursor movements resolve before that strip, into a per-line column buffer rather than by string surgery, because carriage return and backspace only MOVE the cursor — neither erases anything, so what a reader sees is whatever each column last had written to it. `100%` then a carriage return and `OK` shows `OK0%`, since the redraw is shorter than the frame beneath it; a trailing `abc` plus a backspace still shows `abc`, since nothing overwrote the `c`; `abc` plus two backspaces and `XY` shows `aXY`. Each of these was checked against a real terminal, because the earlier truncate-and-delete approximations looked right and were not. SGR state is stamped per column as a terminal stores it per cell, so a partial overwrite keeps each surviving character's own color: red `bad`, three backspaces, then `ok` shows `okd` with the `d` still red. A CSI sequence occupies no column and changes only the state later writes are stamped with, which is also why a carriage return does not reset color, and why SGR state threads from one line to the next rather than closing at each newline. Erase-in-line is part of the same replay, because `\r\x1b[K` is the single idiom every spinner and progress bar writes — modelling the `\r` alone left the previous frame's tail standing, which is text the terminal never showed. Only `m` accumulates into a cell's style; a cursor or erase sequence must not, or the state string grows per redraw and emits boundaries anser has to discard. SGR is held per cell as a NORMALIZED record (foreground, background, attribute set), not as the sequence history: accumulating raw sequences made every state boundary re-emit the whole chain, so output that switches color without a full reset emitted O(n^2) characters — 3200 such cells produced 25 MB and a `RangeError` well under bash's own output cap. The record also lets the attribute closers every chalk-based tool writes (`39`, `49`, `22`, `24`, …) actually close their attribute, and each boundary emits one canonical sequence for the state it opens. A run also has to CLOSE: the replay converges to the state the scan ended in, not the last written cell's, because a reset after the final write changes no cell yet ends the run — without that a line finishing in `\x1b[0m` leaked its color onto every later line. The cursor advances by terminal columns, so a tab reaches the next 8-column stop, a wide character takes two (its spacer blanking rather than closing the gap once the lead cell is overwritten), and a combining mark takes none. Width follows emoji PRESENTATION rather than the U+2600-U+27BF block: `\u2713`, the check every progress line writes, is one column, so treating the block as wide misaligned exactly the output this card exists for. Writing over either half of a wide pair blanks the other, since a terminal cannot leave one cell of a two-cell glyph standing: `a\tb` then a redraw of `XY` shows `XY      b`, since a two-character redraw cannot reach column 8.
+- **ANSI color.** `anser` splits the SGR runs; `ui-primitives/src/ansi.ts` resolves each run into an inline style rendered as React spans. A foreground-only run maps the basic 16 colors onto `--dsw-*` theme tokens so authored color stays legible under both themes; a run that paints its own background keeps anser's literal rgb for both so its intended contrast survives, as do 256-palette, truecolor, and the two basic colors this design system has no token for. Sequences that carry no color (OSC strings, non-CSI escapes, inert C0 controls) are stripped before parsing so they never reach the DOM as literal characters. Cursor movements resolve before that strip, into a per-line column buffer rather than by string surgery, because carriage return and backspace only MOVE the cursor — neither erases anything, so what a reader sees is whatever each column last had written to it. `100%` then a carriage return and `OK` shows `OK0%`, since the redraw is shorter than the frame beneath it; a trailing `abc` plus a backspace still shows `abc`, since nothing overwrote the `c`; `abc` plus two backspaces and `XY` shows `aXY`. These semantics match a real terminal; truncate-and-delete approximations look right and are not. SGR state is stamped per column as a terminal stores it per cell, so a partial overwrite keeps each surviving character's own color: red `bad`, three backspaces, then `ok` shows `okd` with the `d` still red. A CSI sequence occupies no column and changes only the state later writes are stamped with, which is also why a carriage return does not reset color, and why SGR state threads from one line to the next rather than closing at each newline. Erase-in-line is part of the same replay, because `\r\x1b[K` is the single idiom every spinner and progress bar writes — modelling the `\r` alone left the previous frame's tail standing, which is text the terminal never showed. Only `m` accumulates into a cell's style; a cursor or erase sequence must not, or the state string grows per redraw and emits boundaries anser has to discard. SGR is held per cell as a NORMALIZED record (foreground, background, attribute set), not as the sequence history: accumulating raw sequences made every state boundary re-emit the whole chain, so output that switches color without a full reset emitted O(n^2) characters — 3200 such cells produced 25 MB and a `RangeError` well under bash's own output cap. The record also lets the attribute closers every chalk-based tool writes (`39`, `49`, `22`, `24`, …) actually close their attribute, and each boundary emits one canonical sequence for the state it opens. A run also has to CLOSE: the replay converges to the state the scan ended in, not the last written cell's, because a reset after the final write changes no cell yet ends the run — without that a line finishing in `\x1b[0m` leaked its color onto every later line. The cursor advances by terminal columns, so a tab reaches the next 8-column stop, a wide character takes two (its spacer blanking rather than closing the gap once the lead cell is overwritten), and a combining mark takes none. Width follows emoji PRESENTATION rather than the U+2600-U+27BF block: `\u2713`, the check every progress line writes, is one column, so treating the block as wide misaligned exactly the output this card exists for. Writing over either half of a wide pair blanks the other, since a terminal cannot leave one cell of a two-cell glyph standing: `a\tb` then a redraw of `XY` shows `XY      b`, since a two-character redraw cannot reach column 8.
 - **Exit status and copy.** A non-zero exit code or a signal renders a status pill, matching the exit-status distinction the bash tool's own renderer draws; a clean exit renders none, and settled empty output renders a dimmed placeholder — judged on the parsed lines the card renders, not on the raw text, since output that is only escapes or control bytes survives a `trim()` yet parses to nothing visible and would otherwise draw blank rows plus a copy control for invisible bytes. The copy control copies the raw output text, not the rendered tree, so the prompt line and the pill stay out of the clipboard.
 
 Geometry, radius, and fonts mirror `CodeBlock`, so a terminal card and a fenced code block match visually; `white-space: pre` plus horizontal scroll is the deliberate divergence. The clipboard write both components need moved out of `CodeBlock` into a package-internal `src/clipboard.ts`, unexported so it stays an implementation detail of the two blocks.
@@ -41,7 +41,7 @@ One premise of that split has since weakened: [tool rows stopped being details-p
 
 **Reuse `CodeBlock` with a `console` language instead of a new primitive.** Rejected: `CodeBlock` soft-wraps, which is the defect being fixed, and it has no exit status, no cwd prompt line, no height cap, and no ANSI handling. Adding four terminal-specific concerns to the shared code-fence component would impose them on every markdown fence. The two components share their geometry and font tokens instead, which is the only part where one implementation is correct for both.
 
-**Hand-roll the SGR parser.** Rejected: an SGR parser is exactly the surface [prefer maintained dependencies over hand-rolling](../process/2026-07-26-dependencies-over-hand-rolling.md) says not to own — its edge cases (256-palette and truecolor forms, `reverse`, multi-parameter runs, unterminated sequences) each fail on output nobody produces in a test, so a hand-rolled version stays subtly wrong for a long time. Stated honestly against that policy's bar: `anser` does **not** delete existing owned code. It is a capability addition, which that note distinguishes from a net-deletion simplification; the health and boundary-fit halves of the bar are what it clears. What stays hand-rolled is the part `anser` does not cover: the theme-token color mapping, the non-CSI sanitizing, the carriage-return redraw, and the per-line span folding the height cap slices.
+**Hand-roll the SGR parser.** Rejected: an SGR parser is exactly the surface [prefer maintained dependencies over hand-rolling](../process/2026-07-26-dependencies-over-hand-rolling.md) says not to own — its edge cases (256-palette and truecolor forms, `reverse`, multi-parameter runs, unterminated sequences) each fail on output nobody produces in a test, so a hand-rolled version stays subtly wrong for a long time. Against that policy's bar: `anser` does **not** delete existing owned code. It is a capability addition, which that note distinguishes from a net-deletion simplification; the health and boundary-fit halves of the bar are what it clears. What stays hand-rolled is the part `anser` does not cover: the theme-token color mapping, the non-CSI sanitizing, the carriage-return redraw, and the per-line span folding the height cap slices.
 
 ## Consequences
 
@@ -59,7 +59,7 @@ Inline rendering is licensed for the terminal intent alone. A future intent that
 
 `packages/client/ui-tool/tests/terminal-card.spec.tsx` pins the wiring at every render site: `terminalCardModel`'s derivation and each of its null arms, the result title replacing the pending one, the cwd resolving against the session workspace across all four of its cases, the panel resetting the card's expand state when the selection changes, the chat row's expand-gated body against the panel's full-height one, `BashRow`'s resident card and its agreement with its own summary row's state dot, and the panel's Output section including the run_code sub-dispatch and the out-of-window head. That file is written against no gate pressure — `packages/client/ui-tool/src/*` sits on the coverage `exclude` list in `vitest.config.ts`, so a coverage run over this package measures none of these files.
 
-`apps/web/tests/terminal-card.snapshot.ts` pins the assembled application over the built client bundles: the same render intent at both conversation render sites and in both chat-row shapes, because a bash call reaches a resident card only through the keyed `BashRow` registration and every other terminal-declaring tool name lands on the render-site fallback row, whose body is expand-gated. Fixture turn 65 was named `bash` and turn 60 left as `fx-bash` so one fixture covers both shapes, and turn 60's command was made two lines so the built-bundle snapshot pins the per-line prompt and its single dot (`dotsPerPromptRow: [1, 0]`). That terminal turn is ordered BEFORE the todo turn on purpose: the standing plan retires at the next `turn/start`, so appending it after would have emptied the dock's plan strip and taken the todo surfaces' own coverage with it; that turn also carries what turn 60's two prompt rows cannot — SGR runs resolved to `--dsw-*` tokens, output past the chat cap, a nested cwd, and a non-zero exit authored beside the sample. The sample's body deliberately carries NO `[exit code: N]` line: the real bash presenter consumes that marker out of the body precisely because the card shows the exit as its own pill, so leaving it in would pin a frame showing the exit twice — one the product path cannot produce.
+`apps/web/tests/terminal-card.snapshot.ts` pins the assembled application over the built client bundles: the same render intent at both conversation render sites and in both chat-row shapes, because a bash call reaches a resident card only through the keyed `BashRow` registration and every other terminal-declaring tool name lands on the render-site fallback row, whose body is expand-gated. Fixture turn 65 is named `bash` and turn 60 stays `fx-bash` so one fixture covers both shapes, and turn 60's command is two lines so the built-bundle snapshot pins the per-line prompt and its single dot (`dotsPerPromptRow: [1, 0]`). That terminal turn is ordered BEFORE the todo turn on purpose: the standing plan retires at the next `turn/start`, so appending it after would have emptied the dock's plan strip and taken the todo surfaces' own coverage with it; that turn also carries what turn 60's two prompt rows cannot — SGR runs resolved to `--dsw-*` tokens, output past the chat cap, a nested cwd, and a non-zero exit authored beside the sample. The sample's body deliberately carries NO `[exit code: N]` line: the real bash presenter consumes that marker out of the body precisely because the card shows the exit as its own pill, so leaving it in would pin a frame showing the exit twice — one the product path cannot produce.
 
 `apps/web/tests/navigation-panes.e2e.ts` adds the real-browser scenario over its existing `echo NAVIGATION_OK` bash call, asserting what jsdom cannot compute: squeezing the output pane below its content width leaves the line at one row and gives the pane horizontal overflow, the run-state dot resolves to the green success token rather than to a literal color (a `--dsw-*` var has no computed value at all without the real theme stylesheet) and sits inside the card box yet left of the prompt label, which is the invariant the gutter padding owns, and the copy control reaches the page's own async Clipboard API rather than the `execCommand` fallback. Its `terminal-card.expected.md` golden records the resolved workspace in the prompt row, which is what a bash call with no `workdir` must show instead of a bare `$`.
 
diff --git a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
index f9dc686cfb..58c236bda9 100644
--- a/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md
@@ -20,7 +20,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 - **整次调用一枚运行状态点，位于第一行。** 它是 `StateDot` 四种状态中的三种：运行期间为追逐动画，与渲染状态徽章相同的退出状态为红色，干净落定为绿色——与工具行行首图标使用同一个指示器，因此一行与其自身的卡片不可能对同一条命令产生分歧。该状态点存在的理由是：读者对一条 shell 命令的第一个问题就是它是否仍在运行；没有它时，这一点只能从「没有输出」推断，而一条落定后无输出的命令看起来也一样。它以脱离文档流的方式落在卡片以**自身左内边距**预留的落区里，因此既不会缩进其命令，也不依赖命令自身的文本度量来与之对齐。该预留用 padding 而非 margin，是因为每个渲染点都会整条重写 `margin` 来设定自己的缩进——那会静默取消基于 margin 的落区，并让容器把状态点裁掉。无论有多少行，都只有一枚：视图携带的退出状态属于整次调用，而 bash 不报告逐条命令的状态，因此每行一枚状态点就等于在断言——一条在失败调用中其实成功了的命令行自身失败了。那一处视觉隐藏的文本标签具有相同的作用域，因为 `StateDot` 是 `aria-hidden`，而每行一个标签会被辅助技术读成好几个各自独立的结果。
 - **不软换行。** 输出行使用 `white-space: pre`，置于横向滚动的容器内。列对齐得以保留；长行滚动，而非折行。
 - **高度上限与展开控件。** 输出超过 `DEFAULT_TERMINAL_MAX_LINES`（16）行时，显示 `ceil(max/2)` 行首部加余下的尾部行数，中间是一个按钮，报告被隐藏的行数并可展开。计数针对的是剥除输出末尾终止符之后解析出的行，因此以换行结尾的 N 行输出就是 N 行。切分算法保留原 TUI transcript 折叠卡片的行为，因此既有的首尾选择保持稳定。
-- **ANSI 颜色。** `anser` 切分 SGR 分段；`ui-primitives/src/ansi.ts` 把每段解析为内联样式，渲染成 React span。只设前景色的分段把基本 16 色映射到 `--dsw-*` 主题 token，使作者指定的颜色在两种主题下都可读；自行绘制背景的分段则前后景都保留 anser 给出的字面 rgb，以保住它意图中的对比度，256 色板、truecolor 以及本设计系统没有对应 token 的两种基本色同样如此。不承载颜色的转义序列（OSC 串、非 CSI 转义、无显示意义的 C0 控制符）在解析前被剥除，因此绝不会以字面字符抵达 DOM。光标移动在该剥除之前先行结算，且落在逐行的列缓冲里而不是靠字符串手术，因为回车与退格**只移动**光标——两者都不擦除任何东西，所以读者看到的就是每一列最后被写入的内容。`100%` 后接回车再接 `OK` 显示为 `OK0%`，因为这次重绘比它下面的帧更短；末尾 `abc` 加一个退格仍显示 `abc`，因为没有任何东西覆盖过那个 `c`；`abc` 加两个退格再接 `XY` 显示 `aXY`。这些用例都对照真实终端核实过，因为先前「截断加删除」的近似看起来是对的，实际并不对。SGR 状态按列打戳，与终端按单元格存储颜色的方式一致，因此部分覆盖会保留每个存活字符自身的颜色：红色 `bad`、三个退格、再写 `ok`，显示为 `okd` 且那个 `d` 仍是红的。CSI 序列不占列，只改变后续写入被打上的状态——这也正是回车不会重置颜色的原因，以及 SGR 状态会从一行延续到下一行、而不是在每个换行处关闭的原因。行内擦除属于同一次重放，因为 `\r\x1b[K` 是每个 spinner 与进度条都会写的同一个惯用法——只建模 `\r` 会让上一帧的尾巴留在原处，那是终端从未显示过的文本。只有 `m` 会累加进单元格样式；光标或擦除序列不能累加，否则状态串会随每次重绘线性增长，并发出 anser 只能丢弃的边界。SGR 按单元格以**归一化记录**保存（前景、背景、属性集合），而不是序列历史：累积原始序列会让每个状态边界重新发射整条链，因此不做完整 reset 的换色输出会发射 O(n^2) 个字符——3200 个这样的单元格产生 25 MB 并最终 `RangeError`，远低于 bash 自身的输出上限。该记录也让所有 chalk 系工具写出的属性闭合码（`39`、`49`、`22`、`24` 等）真正闭合其属性，且每个边界只为它开启的状态发射一条规范序列。一个分段也必须**收束**：重放收敛到扫描结束时的状态，而不是最后一个被写入单元格的状态——因为最后一次写入之后的 reset 不改变任何单元格，却结束了该分段；没有这一步，以 `\x1b[0m` 结尾的行会把颜色泄漏到其后所有行。光标按终端列推进，因此制表符前进到下一个 8 列制表位、宽字符占两列（其续列在首列被覆盖后变为空白而非合拢），组合标记不占列。宽度依据 emoji **presentation** 而非 U+2600–U+27BF 整个区块：`\u2713`——每条进度行都会写的对勾——只占一列，把该区块整体当作双宽恰好会错位这张卡片赖以存在的那类输出。写入宽字符对的任一半都会把另一半清成空白，因为终端无法让一个双格字形只留下一格：`a\tb` 之后用 `XY` 重绘显示为 `XY      b`，因为两个字符的重绘到不了第 8 列。
+- **ANSI 颜色。** `anser` 切分 SGR 分段；`ui-primitives/src/ansi.ts` 把每段解析为内联样式，渲染成 React span。只设前景色的分段把基本 16 色映射到 `--dsw-*` 主题 token，使作者指定的颜色在两种主题下都可读；自行绘制背景的分段则前后景都保留 anser 给出的字面 rgb，以保住它意图中的对比度，256 色板、truecolor 以及本设计系统没有对应 token 的两种基本色同样如此。不承载颜色的转义序列（OSC 串、非 CSI 转义、无显示意义的 C0 控制符）在解析前被剥除，因此绝不会以字面字符抵达 DOM。光标移动在该剥除之前先行结算，且落在逐行的列缓冲里而不是靠字符串手术，因为回车与退格**只移动**光标——两者都不擦除任何东西，所以读者看到的就是每一列最后被写入的内容。`100%` 后接回车再接 `OK` 显示为 `OK0%`，因为这次重绘比它下面的帧更短；末尾 `abc` 加一个退格仍显示 `abc`，因为没有任何东西覆盖过那个 `c`；`abc` 加两个退格再接 `XY` 显示 `aXY`。这些语义与真实终端一致；「截断加删除」的近似看起来是对的，实际并不对。SGR 状态按列打戳，与终端按单元格存储颜色的方式一致，因此部分覆盖会保留每个存活字符自身的颜色：红色 `bad`、三个退格、再写 `ok`，显示为 `okd` 且那个 `d` 仍是红的。CSI 序列不占列，只改变后续写入被打上的状态——这也正是回车不会重置颜色的原因，以及 SGR 状态会从一行延续到下一行、而不是在每个换行处关闭的原因。行内擦除属于同一次重放，因为 `\r\x1b[K` 是每个 spinner 与进度条都会写的同一个惯用法——只建模 `\r` 会让上一帧的尾巴留在原处，那是终端从未显示过的文本。只有 `m` 会累加进单元格样式；光标或擦除序列不能累加，否则状态串会随每次重绘线性增长，并发出 anser 只能丢弃的边界。SGR 按单元格以**归一化记录**保存（前景、背景、属性集合），而不是序列历史：累积原始序列会让每个状态边界重新发射整条链，因此不做完整 reset 的换色输出会发射 O(n^2) 个字符——3200 个这样的单元格产生 25 MB 并最终 `RangeError`，远低于 bash 自身的输出上限。该记录也让所有 chalk 系工具写出的属性闭合码（`39`、`49`、`22`、`24` 等）真正闭合其属性，且每个边界只为它开启的状态发射一条规范序列。一个分段也必须**收束**：重放收敛到扫描结束时的状态，而不是最后一个被写入单元格的状态——因为最后一次写入之后的 reset 不改变任何单元格，却结束了该分段；没有这一步，以 `\x1b[0m` 结尾的行会把颜色泄漏到其后所有行。光标按终端列推进，因此制表符前进到下一个 8 列制表位、宽字符占两列（其续列在首列被覆盖后变为空白而非合拢），组合标记不占列。宽度依据 emoji **presentation** 而非 U+2600–U+27BF 整个区块：`\u2713`——每条进度行都会写的对勾——只占一列，把该区块整体当作双宽恰好会错位这张卡片赖以存在的那类输出。写入宽字符对的任一半都会把另一半清成空白，因为终端无法让一个双格字形只留下一格：`a\tb` 之后用 `XY` 重绘显示为 `XY      b`，因为两个字符的重绘到不了第 8 列。
 - **退出状态与复制。** 非零退出码或信号渲染一枚状态徽章，与 bash 工具自身渲染器所作的退出状态区分一致；干净退出不渲染徽章，落定后的空输出渲染一处变暗的占位文字——该判定读的是卡片实际渲染的解析行，而非原始文本，因为只含转义或控制字节的输出能通过 `trim()` 却解析不出任何可见内容，否则就会画出一片空行外加一个把不可见字节写进剪贴板的复制控件。复制控件复制的是原始输出文本而非渲染后的树，因此提示符行与徽章不会进入剪贴板。
 
 几何尺寸、圆角与字体沿用 `CodeBlock`，因此终端卡片与围栏代码块在视觉上一致；`white-space: pre` 加横向滚动是有意的分歧。两个组件都需要的剪贴板写入从 `CodeBlock` 中提取到包内部的 `src/clipboard.ts`，不对外导出，因此它仍是这两个块的实现细节。
@@ -41,7 +41,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 **复用 `CodeBlock` 并传入 `console` 语言，而不新建组件。** 已否决：`CodeBlock` 会软换行，而软换行正是本次要修的缺陷，且它没有退出状态、没有 cwd 提示符行、没有高度上限、也不处理 ANSI。把四项终端专属关注点加进共享的代码围栏组件，等于把它们强加给每一个 markdown 围栏。两个组件改为共享几何与字体 token，那是唯一一处「一套实现对两者都正确」的部分。
 
-**手写 SGR 解析器。** 已否决：SGR 解析器恰是[优先采用维护良好的依赖而非手写](../process/2026-07-26-dependencies-over-hand-rolling.md)所指明不该自持的那类实现——它的边界情形（256 色板与 truecolor 形式、`reverse`、多参数分段、未终止的序列）各自只在没人会写进测试的输出上失效，因此手写版本会在很长时间内一直微妙地出错。对照那条策略的门槛如实陈述：`anser` **并未**删除任何既有自持代码。它是一次能力增补，而那条 Agent Note 把这与净删除式的简化区分开来；它清过的是健康度与边界契合这两半门槛。`anser` 未覆盖而仍由我们手写的部分是：主题 token 的颜色映射、非 CSI 序列的剥除、回车重绘，以及供高度上限切片的逐行 span 折叠。
+**手写 SGR 解析器。** 已否决：SGR 解析器恰是[优先采用维护良好的依赖而非手写](../process/2026-07-26-dependencies-over-hand-rolling.md)所指明不该自持的那类实现——它的边界情形（256 色板与 truecolor 形式、`reverse`、多参数分段、未终止的序列）各自只在没人会写进测试的输出上失效，因此手写版本会在很长时间内一直微妙地出错。对照那条策略的门槛：`anser` **并未**删除任何既有自持代码。它是一次能力增补，而那条 Agent Note 把这与净删除式的简化区分开来；它清过的是健康度与边界契合这两半门槛。`anser` 未覆盖而仍由我们手写的部分是：主题 token 的颜色映射、非 CSI 序列的剥除、回车重绘，以及供高度上限切片的逐行 span 折叠。
 
 ## Consequences
 
@@ -59,7 +59,7 @@ Web client 却对它视而不见。`packages/client/ui-tool/src/client/tool/mode
 
 `packages/client/ui-tool/tests/terminal-card.spec.tsx` 固定每个渲染点上的接线：`terminalCardModel` 的推导及其每一处 null 分支、结果标题替换待定标题、cwd 针对会话 workspace 解析的全部四种情形、切换选中调用时面板重置卡片展开态、对话行受展开控制的输出体与面板的全高输出体的对比、`BashRow` 的常驻卡片及其与自身摘要行状态点的一致性，以及面板 Output 区段（含 run_code 子派发与超出窗口的调用头）。该文件在没有门禁压力的情况下写成——`packages/client/ui-tool/src/*` 位于 `vitest.config.ts` 的覆盖率 `exclude` 列表中，因此覆盖率运行不会统计其中任何文件。
 
-`apps/web/tests/terminal-card.snapshot.ts` 在构建后的客户端产物上固定组装完整的应用：同一渲染意图在两个对话渲染点、以及两种对话行形态下的表现——因为 bash 调用只有经由带键的 `BashRow` 注册才得到常驻卡片，而其他任何声明 terminal 的工具名都落到渲染点兜底行上，其输出体受展开控制。fixture 第 65 轮改名为 `bash`、第 60 轮保留 `fx-bash`，于是一份 fixture 覆盖两种形态，并把第 60 轮的命令改为两行，使构建产物快照钉住逐行提示区及其单枚状态点（`dotsPerPromptRow: [1, 0]`）。该终端轮有意排在 todo 轮**之前**：站立计划会在下一次 `turn/start` 时退役，若追加在其后就会让 dock 的计划条变空，并连带毁掉 todo 表面自身的覆盖；该轮还承载第 60 轮两个提示行无法覆盖的部分——解析到 `--dsw-*` token 的 SGR 分段、超出对话上限的输出、嵌套 cwd，以及在样本旁另行标注的非零退出码。样本正文有意**不含** `[exit code: N]` 行：真实的 bash presenter 正是因为卡片以徽章单独呈现退出状态，才把该标记从正文中消费掉；若保留它，钉住的将是一帧把退出状态显示两次的画面——而产品路径产不出这一帧。
+`apps/web/tests/terminal-card.snapshot.ts` 在构建后的客户端产物上固定组装完整的应用：同一渲染意图在两个对话渲染点、以及两种对话行形态下的表现——因为 bash 调用只有经由带键的 `BashRow` 注册才得到常驻卡片，而其他任何声明 terminal 的工具名都落到渲染点兜底行上，其输出体受展开控制。fixture 第 65 轮名为 `bash`、第 60 轮保持 `fx-bash`，于是一份 fixture 覆盖两种形态，而第 60 轮的命令为两行，使构建产物快照钉住逐行提示区及其单枚状态点（`dotsPerPromptRow: [1, 0]`）。该终端轮有意排在 todo 轮**之前**：站立计划会在下一次 `turn/start` 时退役，若追加在其后就会让 dock 的计划条变空，并连带毁掉 todo 表面自身的覆盖；该轮还承载第 60 轮两个提示行无法覆盖的部分——解析到 `--dsw-*` token 的 SGR 分段、超出对话上限的输出、嵌套 cwd，以及在样本旁另行标注的非零退出码。样本正文有意**不含** `[exit code: N]` 行：真实的 bash presenter 正是因为卡片以徽章单独呈现退出状态，才把该标记从正文中消费掉；若保留它，钉住的将是一帧把退出状态显示两次的画面——而产品路径产不出这一帧。
 
 `apps/web/tests/navigation-panes.e2e.ts` 在其既有的 `echo NAVIGATION_OK` bash 调用上新增真实浏览器场景，断言 jsdom 无法计算的部分：把输出面板挤压到窄于内容宽度后，行仍保持单行且面板产生横向溢出；运行状态点解析为绿色的 success token，而不是字面颜色（没有真实主题样式表时，`--dsw-*` 变量根本不产生计算值），且它位于卡片盒之内、提示标签之左——这正是那道 gutter 内边距所拥有的不变量；复制控件走的是页面自身的异步 Clipboard API，而非 `execCommand` 兜底路径。其 `terminal-card.expected.md` 基准记录了提示行中已解析的 workspace——这正是不带 `workdir` 的 bash 调用应当显示的内容，而非一个裸 `$`。
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
index ade585187c..6c7de886c9 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.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 .agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
-2026-07-29-ask-question-web-presentation.md: 11471bba08b723620b83af0e14e64a759d11c520
-2026-07-29-ask-question-web-presentation.zh.md: 6957d34fa5d3769340be9798998e59496e4b7f44
+2026-07-29-ask-question-web-presentation.md: a622a128a6b3ad1b1041dd8a0ae418c805655d1a
+2026-07-29-ask-question-web-presentation.zh.md: 5a43ba4f469565769234d7a13230e3edabfebf4f
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
index 11471bba08..a622a128a6 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.md
@@ -12,7 +12,7 @@ Separately, the composer visuals had drifted from the current design: an expand-
 
 ## Decision
 
-A pending question owns exactly two surfaces: the composer takeover collects the answers, and a dedicated `ask_user_question` toolview row in the transcript names the interaction outcome. The row registers into the keyed `tool.call.toolview` hole exactly like `todo_write` and composes the shared `ToolRow` (chrome, running sweep, leading expansion). Its summary is the interaction verdict rather than args: `waiting` while running, `N/M answered` from the result JSON once settled (a skipped answer — empty `selected`, no `custom` — stays out of the count), `cancelled` for `ASK_CANCELLED`, and `interrupted` with the shared amber stopped semantics for `ASK_ABORTED`. Malformed or truncated results fall back to the generic summary. `PendingCard` narrows to `PendingWait<'approval'>` and `ChatView` filters the pending list to approval waits, so the placeholder card now exists only for the approval takeover still on the roadmap.
+A pending question owns exactly two surfaces: the composer takeover collects the answers, and a dedicated `ask_user_question` toolview row in the transcript names the interaction outcome. The row registers into the keyed `tool.call.toolview` hole exactly like `todo_write` and composes the shared `ToolRow` (chrome, running sweep, leading expansion). Its summary is the interaction verdict rather than args: `waiting` while running, `N/M answered` from the result JSON once settled (a skipped answer — empty `selected`, no `custom` — stays out of the count), `cancelled` for `ASK_CANCELLED`, and `interrupted` with the shared amber stopped semantics for `ASK_ABORTED`. Malformed or truncated results fall back to the generic summary. `PendingCard` narrowed to `PendingWait<'approval'>` and `ChatView` filtered the pending list to approval waits, leaving the placeholder card to approvals alone; the approval composer takeover ([web permission and approval](2026-07-23-web-permission-and-approval.md)) has since removed it entirely.
 
 The composer redesign moves paging into the footer next to the actions, renders multi-select options with explicit checkboxes, keeps single-select numbered rows, and replaces the expand-to-open custom entry with an always-visible custom input row (textarea for optionless questions). The `parseQuestionTitle` multi-select suffix convention is deleted; `multi_select` is already structured metadata, so the title renders verbatim.
 
@@ -36,7 +36,7 @@ Two adjacent fixes ride along. All generic toolview leading icons (and the hover
 
 `ask_user_question` and `todo_write` now demonstrate the intended toolview pattern: compose `ToolRow`, summarize from call args or result JSON with shape-checked fallbacks, and register through the keyed slot. The bespoke `todo-row.module.css` is gone.
 
-The row verdict strings are the one remaining hardcoded-English surface of the question flow; localizing them is deferred follow-up. `PendingCard` remains a visible-but-not-answerable approval placeholder until the approval composer takeover ships.
+The row verdict strings are the one remaining hardcoded-English surface of the question flow; localizing them is deferred follow-up. The approval composer takeover shipped ([web permission and approval](2026-07-23-web-permission-and-approval.md), height-capped per the [approval-panel note](../bug-fix/2026-07-30-approval-panel-command-cap.md)), and `PendingCard` no longer exists.
 
 `ui-question` gains a `dsh-client-locale` dependency and an inject face where it previously had none; its contract (`QuestionComposerInjected`) lives with the consumer in `contract/slots.ts`.
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
index 6957d34fa5..5a43ba4f46 100644
--- a/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-ask-question-web-presentation.zh.md
@@ -12,7 +12,7 @@ Web GUI 已经可以通过 `QuestionComposer` 的输入区接管收集回答，
 
 ## 决定
 
-一个待回答的问题恰好拥有两个界面：输入区接管收集回答，会话记录中一个专门的 `ask_user_question` toolview 行陈述交互结果。该行与 `todo_write` 完全一样注册进带 key 的 `tool.call.toolview` 槽位，并复用共享的 `ToolRow`（外观、运行扫光、前导展开）。其摘要是交互裁决而非参数：运行中显示 `waiting`，结算后从结果 JSON 得出 `N/M answered`（被跳过的回答 —— `selected` 为空且无 `custom` —— 不计入），`ASK_CANCELLED` 显示 `cancelled`，`ASK_ABORTED` 显示 `interrupted` 并沿用共享的琥珀色 stopped 语义。畸形或截断的结果回退到通用摘要。`PendingCard` 收窄为 `PendingWait<'approval'>`，`ChatView` 将待处理列表过滤为仅审批等待，占位卡片从此只服务于仍在路线图上的审批接管。
+一个待回答的问题恰好拥有两个界面：输入区接管收集回答，会话记录中一个专门的 `ask_user_question` toolview 行陈述交互结果。该行与 `todo_write` 完全一样注册进带 key 的 `tool.call.toolview` 槽位，并复用共享的 `ToolRow`（外观、运行扫光、前导展开）。其摘要是交互裁决而非参数：运行中显示 `waiting`，结算后从结果 JSON 得出 `N/M answered`（被跳过的回答 —— `selected` 为空且无 `custom` —— 不计入），`ASK_CANCELLED` 显示 `cancelled`，`ASK_ABORTED` 显示 `interrupted` 并沿用共享的琥珀色 stopped 语义。畸形或截断的结果回退到通用摘要。`PendingCard` 曾收窄为 `PendingWait<'approval'>`，`ChatView` 曾将待处理列表过滤为仅审批等待，使占位卡片只服务于审批；其后审批输入区接管（[Web 权限与审批](2026-07-23-web-permission-and-approval.md)）已将它彻底移除。
 
 输入区重设计将分页移到底部操作区旁，多选选项渲染显式复选框，单选保留编号行，并用始终可见的自定义输入行取代展开式自定义入口（无选项问题用多行文本框）。删除 `parseQuestionTitle` 的多选后缀约定；`multi_select` 已是结构化元数据，标题原样渲染。
 
@@ -36,7 +36,7 @@ Web GUI 已经可以通过 `QuestionComposer` 的输入区接管收集回答，
 
 `ask_user_question` 与 `todo_write` 现在共同示范预期的 toolview 模式：复用 `ToolRow`、从调用参数或结果 JSON 做带形状校验回退的摘要、通过带 key 的槽位注册。专用的 `todo-row.module.css` 已删除。
 
-行内裁决字符串是问题流程仅剩的硬编码英文面；将其本地化是推迟的后续工作。在审批输入区接管交付之前，`PendingCard` 仍是可见但不可操作的审批占位。
+行内裁决字符串是问题流程仅剩的硬编码英文面；将其本地化是推迟的后续工作。审批输入区接管已交付（[Web 权限与审批](2026-07-23-web-permission-and-approval.md)，并按[审批面板 Agent Note](../bug-fix/2026-07-30-approval-panel-command-cap.md)施加高度上限），`PendingCard` 已不复存在。
 
 `ui-question` 新增 `dsh-client-locale` 依赖和此前没有的 inject face；其约定（`QuestionComposerInjected`）与消费者一起放在 `contract/slots.ts`。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
index 75e70f4fba..9db1928c8d 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.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 .agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
-2026-07-30-queued-manual-compaction.md: 94afdd84dfe573ee2b60eb3dbfdae2dd5b6beb1e
-2026-07-30-queued-manual-compaction.zh.md: bd120050e621d1bfa3a677578e429f939b9c17d1
+2026-07-30-queued-manual-compaction.md: 3aa4e17bd673417569990090abec0ec29427665a
+2026-07-30-queued-manual-compaction.zh.md: 0763d6d127d158fa3b91b52aaa9b28ddf78e839f
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
index 94afdd84df..3aa4e17bd6 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md
@@ -12,7 +12,7 @@ The human command arrives between turns and must summarize asynchronously. A pro
 
 Compaction also needs one mutual-exclusion fact shared by manual, pressure, overflow, and explicit-range entry points. A process-local flag alone cannot explain a crash-recovered log, while a summarize-first transaction leaves no durable evidence during the expensive interval. Conversely, treating marker pairs as exclusive containers would forbid valid idle injection even though injection is explicitly non-waking and immediate between turns.
 
-This note extends the [compaction capability seam](2026-06-18-compaction-capability-seam.md), the [session end-seed boundary](../architecture/2026-07-30-session-end-seed-log-boundary.md), and the [removal of synthetic log-only turns](../simplification/2026-07-28-remove-synthetic-log-only-turns.md). The supersession audit found partial overlap only: each remains active and owns its broader decision.
+This note extends the [compaction capability seam](2026-06-18-compaction-capability-seam.md), the [session end-seed boundary](../architecture/2026-07-30-session-end-seed-log-boundary.md), and the [removal of synthetic log-only turns](../simplification/2026-07-28-remove-synthetic-log-only-turns.md). Each remains active and owns its broader decision; the overlap is partial only.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
index bd120050e6..0763d6d127 100644
--- a/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 手动、压力、溢出和显式范围入口点还需要共享同一项互斥事实。仅使用进程本地标志无法解释一份崩溃恢复后的日志，而先摘要再记录的事务在开销较大的等待期间不会留下持久证据。反过来，把标记对视为排他容器又会禁止有效的空闲注入，尽管注入按定义不会唤醒，并且会在轮次之间立即执行。
 
-本 Agent Note 扩展[压缩能力 seam](2026-06-18-compaction-capability-seam.md)、[会话 end-seed 边界](../architecture/2026-07-30-session-end-seed-log-boundary.md)和[移除纯日志事件的合成轮次](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)。取代关系审计只发现部分重叠：三者均保持活动状态，并拥有各自更广泛的决策。
+本 Agent Note 扩展[压缩能力 seam](2026-06-18-compaction-capability-seam.md)、[会话 end-seed 边界](../architecture/2026-07-30-session-end-seed-log-boundary.md)和[移除纯日志事件的合成轮次](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)。三者均保持活动状态，并拥有各自更广泛的决策；重叠仅是部分的。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
index cee07159d1..1d5b00e8e0 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.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 .agents/notes/implemented/feature/2026-07-30-search-render-card.md
-2026-07-30-search-render-card.md: 29544cb703f3ab048f4e7702935887ecf05179bf
-2026-07-30-search-render-card.zh.md: 01ffe25522c462a26e781f9bd455711331e58445
+2026-07-30-search-render-card.md: 585609bd059dbd9aa8283547fa8a4b223f7bdd99
+2026-07-30-search-render-card.zh.md: 2cb28a29f8a1a265310fecb1f0a315d010250e02
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.md
index 29544cb703..585609bd05 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.md
@@ -18,7 +18,7 @@ The discriminant is `shape`, not `kind`, deliberately: the same presentation mod
 
 One view with two shapes rather than two cards, because both tools are the same visual object — a search result — and a web consumer switches on one `card` value, then on `shape` for the row layout. The discriminated `shape` keeps each variant's fields non-optional (a matches view always has `files`, a paths view always has `paths`) instead of a single interface where every shape-specific field is optional.
 
-The view carries **no** result text. An earlier revision attached the model-facing `result.content` to the view; that was a no-op because consumer fallbacks already read the raw `tool/result` content, and it serialized the whole search text a second time into the persisted view. The view is the structured shape only; a UI without a search card falls back to the raw result content.
+The view carries **no** result text. Attaching the model-facing `result.content` would be a no-op — consumer fallbacks already read the raw `tool/result` content — and would serialize the whole search text a second time into the persisted view. The view is the structured shape only; a UI without a search card falls back to the raw result content.
 
 The card tag is result-time only. A search call stays a `GenericCallView` (`kind: 'search'`): the pending state has no matches or paths to show, so there is nothing a `SearchCallView` would carry that the generic title does not. This is the asymmetry with the terminal card, whose call view carries the command, cwd, and description that exist before execution; a search's structured content exists only after `execute`.
 
@@ -30,7 +30,7 @@ The card tag is result-time only. A search call stays a `GenericCallView` (`kind
 
 The `SearchMeta` member shapes are object-literal `type` aliases, not the `SearchFileMatches`/`SearchLineMatch` interfaces the view exposes, because only a type alias is assignable to the `JsonValue` index signature `presentationMeta` returns; the two are structurally identical, so the projected value still reads back as a `SearchResultView`.
 
-A consumer without a dedicated `search` arm falls back to the same generic body and reads the model-facing text from the raw result. Because the search view carries no `content` of its own and grep/glob returned a generic card before this PR, that fallback stays byte-identical to the pre-search-card path. The frontend that renders the structured `files`/`paths` shape is independent of this backend contract and its two producers.
+A consumer without a dedicated `search` arm falls back to the same generic body and reads the model-facing text from the raw result. Because the search view carries no `content` of its own and grep/glob previously returned a generic card, that fallback stays byte-identical to the pre-search-card path. The frontend that renders the structured `files`/`paths` shape is independent of this backend contract and its two producers.
 
 ## Alternatives considered
 
@@ -40,7 +40,7 @@ A consumer without a dedicated `search` arm falls back to the same generic body
 
 **Attach the model-facing text as the view's `content`.** Rejected: a no-op for every current consumer and a second serialization of the whole search text into the persisted view. The view is the structured shape; text fallback reads the raw result content.
 
-**A meta channel on `PostToolDecision` so `dsh-spill-policy` bounds `meta` like it bounds `content`.** Rejected for this PR: it changes the core tool decision contract and the spill-policy plugin for one tool's payload. The projection bounding its own `meta` at a config byte cap is self-contained and keeps the seam unchanged.
+**A meta channel on `PostToolDecision` so `dsh-spill-policy` bounds `meta` like it bounds `content`.** Rejected here: it changes the core tool decision contract and the spill-policy plugin for one tool's payload. The projection bounding its own `meta` at a config byte cap is self-contained and keeps the seam unchanged.
 
 **A call-time `SearchCallView` mirroring the terminal card's both-sides symmetry.** Rejected: a search call has no matches or paths before `execute`, so the view would carry only the title the `GenericCallView` already carries.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
index 01ffe25522..2cb28a29f8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 用一个带两种形状的视图而非两张卡片，因为两个工具是同一个视觉对象 —— 一个搜索结果 —— web 消费方先在一个 `card` 值上分支，再在 `shape` 上分支决定行布局。判别式 `shape` 让每个变体的字段保持非可选（matches 视图总有 `files`，paths 视图总有 `paths`），而不是一个所有形状相关字段都可选的单一接口。
 
-该视图**不**携带结果文本。早期版本曾把面向模型的 `result.content` 附到视图上；但消费方的回退路径本就读取原始 `tool/result` 内容，因此这不会产生效果，却会把整段搜索文本又序列化进持久化视图一遍。视图只承载结构化形状；无 search 卡片的 UI 回退到原始结果内容。
+该视图**不**携带结果文本。把面向模型的 `result.content` 附到视图上不会产生效果——消费方的回退路径本就读取原始 `tool/result` 内容——却会把整段搜索文本又序列化进持久化视图一遍。视图只承载结构化形状；无 search 卡片的 UI 回退到原始结果内容。
 
 卡片标签只在结果时存在。搜索调用保持为 `GenericCallView`（`kind: 'search'`）：pending 状态没有匹配或路径可展示，所以 `SearchCallView` 能携带的东西不会比 generic 标题更多。这是与 terminal 卡片的不对称之处 —— terminal 的调用视图携带执行前就存在的命令、cwd、description；搜索的结构化内容只在 `execute` 之后才存在。
 
@@ -30,7 +30,7 @@ Status: implemented
 
 `SearchMeta` 的成员形状是对象字面量 `type` 别名，而非视图暴露的 `SearchFileMatches`/`SearchLineMatch` 接口，因为只有 type 别名可赋给 `presentationMeta` 返回的 `JsonValue` 索引签名；两者结构等价，所以投影值仍读回为 `SearchResultView`。
 
-没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而本 PR 之前 grep/glob 返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端约定及其两个生产者。
+没有专用 `search` 分支的消费方会回退到同一个 generic body，并从原始结果中读取面向模型的文本。因为搜索视图不带自己的 `content`，而 grep/glob 此前返回的是 generic 卡片，所以该回退与引入 search 卡片之前的路径逐字节一致。渲染结构化 `files`/`paths` 形状的前端独立于这个后端约定及其两个生产者。
 
 ## 考虑过的备选
 
@@ -40,7 +40,7 @@ Status: implemented
 
 **把面向模型的文本作为视图的 `content` 附上。** 否决：对每个当前消费方是 no-op，且把整段搜索文本第二次序列化进持久化视图。视图是结构化形状；文本回退读原始结果内容。
 
-**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 本 PR 否决：它为一个工具的载荷改动核心工具决策约定与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
+**在 `PostToolDecision` 上加 meta 通道，让 `dsh-spill-policy` 像约束 `content` 那样约束 `meta`。** 此处否决：它为一个工具的载荷改动核心工具决策约定与 spill-policy 插件。投影在配置字节上限处约束自己的 `meta` 是自包含的，且保持 seam 不变。
 
 **镜像 terminal 卡片双侧对称的调用时 `SearchCallView`。** 否决：搜索调用在 `execute` 前没有匹配或路径，视图只会携带 `GenericCallView` 已有的标题。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index 2e01db1284..549145aad0 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.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 .agents/notes/implemented/feature/2026-07-30-web-diff-card.md
-2026-07-30-web-diff-card.md: b078da8d0e688d705683599467bd98b5c6a0be48
-2026-07-30-web-diff-card.zh.md: 901331907ed9052541aaee0d4fe70531b030d0f9
+2026-07-30-web-diff-card.md: d8b0cf32e42af45e16e6f7059c873c384d4a9229
+2026-07-30-web-diff-card.zh.md: 51df03c3f8b79cd8415a15bd30e92e3c152f335e
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
index b078da8d0e..d8b0cf32e4 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
@@ -32,7 +32,7 @@ The chat row renders the diff resident under its path-link summary, capped at `C
 
 **A side-by-side (two-column) diff.** Rejected for now by the owner: it is denser but does not fit the narrow chat row, and the goal was parity with the TUI's single-column unified form. A two-column mode in the details panel is a later props change, not a redesign.
 
-**Git-style line-number gutters.** The `FileDiff` contract carries only `{ path, oldText, newText }` — `structuredPatch`'s hunk start lines are dropped in `diff.ts`, so no line number reaches the client. Rendering a numbered gutter needs a backend contract change (carry `oldStart`/`newStart`) and a matching TUI upgrade to stay consistent; deferred so this PR stays a pure Web consumer of the existing contract.
+**Git-style line-number gutters.** The `FileDiff` contract carries only `{ path, oldText, newText }` — `structuredPatch`'s hunk start lines are dropped in `diff.ts`, so no line number reaches the client. Rendering a numbered gutter needs a backend contract change (carry `oldStart`/`newStart`) and a matching TUI upgrade to stay consistent; deferred so this change stays a pure Web consumer of the existing contract.
 
 **Reuse `CodeBlock`.** Rejected for the same reason the terminal card was: `CodeBlock` soft-wraps and has no per-line `+`/`-` role, no path headers, and no footer. The two share geometry and font tokens, which is the only part where one implementation is correct for both.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index 901331907e..51df03c3f8 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -32,7 +32,7 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX
 
 **并排（双栏）diff。** owner 目前拒绝：它更密但不适合狭窄的 chat 行，目标是与 TUI 单栏统一形式对齐。详情面板里的双栏模式是后续的 props 改动，不是重设计。
 
-**git 式行号槽。** `FileDiff` 约定只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端约定改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR（Pull Request）保持为对既有约定的纯 Web 消费。
+**git 式行号槽。** `FileDiff` 约定只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端约定改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本变更保持为对既有约定的纯 Web 消费。
 
 **复用 `CodeBlock`。** 因与 terminal 卡片相同的理由拒绝：`CodeBlock` 会折行，且没有每行 `+`/`-` 角色、没有路径头、没有页脚。两者共享几何与字体 token，那是唯一一处一个实现对两者都正确的部分。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
index b4992a15c3..9e159b5b40 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.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 .agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
-2026-07-30-web-read-card-frontend.md: e659645066b706f35709fead4c11023eb4fe9554
-2026-07-30-web-read-card-frontend.zh.md: ac3972ace7458b8a751b4cc342bbdb3e2b0a7a9e
+2026-07-30-web-read-card-frontend.md: 1d9b6d7fa0c8b5391d175a53507db88a84234b91
+2026-07-30-web-read-card-frontend.zh.md: 2678d50e851e4b3a079f59c7db6ec08ecc5c4aed
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
index e659645066..1d9b6d7fa0 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md
@@ -18,11 +18,11 @@ The [read backend](2026-07-30-web-read-card.md) added a fourth render-intent car
 
 The chat row renders the card **resident** under the summary line, capped at `CHAT_READ_MAX_LINES` (8, half the primitive's default), the same posture `BashRow` gives a terminal card — the block's internal expander keeps a long read from taking over the message flow. Two render sites carry it: the keyed `ReadRow` (registered under `read` through `ctx.slots.inject`, exactly as the bash sample) whose summary is the file path as an openable host link, and `GenericToolCard`'s fallback for a read-declaring tool without its own keyed row (e.g. `web_fetch`, which classifies to the `read` variant). The details panel renders the same card at the primitive's own full-height cap (16), because the panel is the single-call reading surface.
 
-Whole-row collapse/expand (defaulting every tool call to collapsed) is a separate later change that will flip every resident card at once; this note's card is resident, matching the terminal card it sits beside.
+Whole-row collapse/expand (defaulting every tool call to collapsed) is owned by the [unified expand-and-inspect note](2026-07-30-web-tool-row-unified-expand-and-inspect.md), which flipped every resident card at once; this note's card is resident, matching the terminal card it sits beside.
 
 **Read-card grammars load lazily; only the boot three stay eager.** `highlight.ts` is a platform seed `ui-primitives` loads on every Web boot, and its warm-up unconditionally builds the shiki singleton. The read card's `langFromPath` hints span the full source/config/markup extension set (python, rust, yaml, html, …); registering all of them eagerly would add ~1.6 MB of grammar modules to the boot chunk and their synchronous init to every session, including sessions that never open a read card. So only the three grammars every session already renders — TypeScript, shell, JSON (the markdown-fence and `run_code` languages) — load at boot. Each read-card extension grammar sits behind a dynamic `import()` in `LAZY_GRAMMARS`, keyed by the grammar id its aliases resolve to. On the first `highlightLines`/`highlightToHtml` call for a lazy language, `ensureGrammar` starts the import (once) and returns not-ready, so the card renders plain that frame; when the import resolves it registers the grammar with `loadLanguageSync`, bumps a load counter, and notifies subscribers. `ReadBlock` and `CodeBlock` subscribe through `useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount)`, so the card re-renders with highlighting the moment the grammar is ready. An unknown/absent language still returns undefined synchronously (plain, never an error).
 
-**The empty-window copy control is hidden, matching `TerminalBlock`.** A successful read of an empty file returns `lines: []`, `totalLines: 0`, and `presentResult` still projects `card: 'read'`, so the empty-window branch is reachable — the read card is not, as an earlier draft assumed, unreachable for an empty result. `ReadBlock` therefore hides the copy control when `lines` is empty, exactly as `TerminalBlock` hides copy on empty output, so the button can never wipe the clipboard with an empty string.
+**The empty-window copy control is hidden, matching `TerminalBlock`.** A successful read of an empty file returns `lines: []`, `totalLines: 0`, and `presentResult` still projects `card: 'read'`, so the empty-window branch is reachable. `ReadBlock` therefore hides the copy control when `lines` is empty, exactly as `TerminalBlock` hides copy on empty output, so the button can never wipe the clipboard with an empty string.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
index ac3972ace7..2678d50e85 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md
@@ -18,11 +18,11 @@ Status: implemented
 
 聊天行把卡片**常驻**渲染在摘要行之下，上限 `CHAT_READ_MAX_LINES`（8，是 primitive 默认值的一半），与 `BashRow` 对终端卡片的姿态相同 —— block 的内部展开器让长读取不会占据整个消息流。两个渲染点承载它：keyed `ReadRow`（经 `ctx.slots.inject` 以 `read` 键注册，与 bash 样例完全一致），其摘要是作为可打开的宿主链接的文件路径；以及 `GenericToolCard` 对没有自己 keyed 行的读取声明工具（例如归到 `read` 变体的 `web_fetch`）的回退。详情面板以 primitive 自己的全高上限（16）渲染同一张卡片，因为面板是单次调用的阅读界面。
 
-整行折叠/展开（把每个工具调用默认折叠）是一个单独的后续改动，它会一次性翻转每张常驻卡片；本 note 的卡片是常驻的，与它旁边的终端卡片一致。
+整行折叠/展开（把每个工具调用默认折叠）归[统一展开与检视 note](2026-07-30-web-tool-row-unified-expand-and-inspect.md)所有，它已一次性翻转每张常驻卡片；本 note 的卡片是常驻的，与它旁边的终端卡片一致。
 
 **读取卡片的语法按需 lazy 加载，只有 boot 三种保持 eager。** `highlight.ts` 是 `ui-primitives` 在每次 Web 启动都加载的平台 seed，其预热会无条件构建 shiki 单例。读取卡片的 `langFromPath` 提示覆盖完整的源码/配置/标记扩展集（python、rust、yaml、html……）；把它们全部 eager 注册会给启动 chunk 增加约 1.6 MB 的语法模块、并把它们的同步初始化摊给每个会话，包括从不打开读取卡片的会话。因此只有每个会话本就渲染的三种语法 —— TypeScript、shell、JSON（markdown 围栏与 `run_code` 语言）—— 在 boot 时加载。每种读取卡片扩展语法置于 `LAZY_GRAMMARS` 中一个动态 `import()` 之后，以其别名解析到的语法 id 为键。对某个 lazy 语言首次调用 `highlightLines`/`highlightToHtml` 时，`ensureGrammar` 启动 import（仅一次）并返回未就绪，于是卡片该帧渲染纯文本；import 解析后用 `loadLanguageSync` 注册该语法、递增一个加载计数、并通知订阅者。`ReadBlock` 与 `CodeBlock` 通过 `useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount)` 订阅，因此语法就绪的那一刻卡片就重渲染带上高亮。未知/缺省语言仍同步返回 undefined（纯文本，绝不报错）。
 
-**空窗口的复制控件被隐藏，与 `TerminalBlock` 对齐。** 成功读取一个空文件会返回 `lines: []`、`totalLines: 0`，且 `presentResult` 仍投出 `card: 'read'`，因此空窗口分支是可达的 —— 读取卡片并非如早前草稿所假设的对空结果不可达。故 `ReadBlock` 在 `lines` 为空时隐藏复制控件，正如 `TerminalBlock` 对空输出隐藏复制，使按钮绝不会用空字符串清空剪贴板。
+**空窗口的复制控件被隐藏，与 `TerminalBlock` 对齐。** 成功读取一个空文件会返回 `lines: []`、`totalLines: 0`，且 `presentResult` 仍投出 `card: 'read'`，因此空窗口分支是可达的。故 `ReadBlock` 在 `lines` 为空时隐藏复制控件，正如 `TerminalBlock` 对空输出隐藏复制，使按钮绝不会用空字符串清空剪贴板。
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
index a58a19000a..1981decbb3 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.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 .agents/notes/implemented/feature/2026-07-30-web-read-card.md
-2026-07-30-web-read-card.md: 26d1634b6be86666980e65f842de51c868c26efd
-2026-07-30-web-read-card.zh.md: c48cd56b7f919d5ceb702f890ee18a2a735da347
+2026-07-30-web-read-card.md: 8ed170e3bbe63cdee85f0ee8440ab1d975c6ff0a
+2026-07-30-web-read-card.zh.md: 68ab9a118e946f397b69691a02a55d1c43ee41b1
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card.md
index 26d1634b6b..8ed170e3bb 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.md
@@ -16,7 +16,7 @@ Add a fourth `card` tag, `read`, to the [render-intent union](../architecture/20
 
 The read tool projects the structured window through `output.presentationMeta`, the same persisted channel write/edit use for their applied-diff hunks ([canonical tool output contract](../architecture/2026-07-20-canonical-tool-output-contract.md)). `presentationMeta` runs once for a top-level surface call, returns `{ path, offset, lines, totalLines, lang? }` as JSON the session validates and stores on the result's `meta`, and `presentResult` narrows that meta back into the `ReadResultView` on both live and replay paths. `offset` (the 1-based first line the window requested) rides along because a byte cap below the first selected line yields an empty `lines` array with a positive `totalLines`; without the persisted `offset` a replayed card of such a window could not report where it starts or where a continuation resumes, and the last-line and re-parse fallbacks are both lossy. Without this channel the line array and total would be unreachable: the raw output object is not on the wire, and re-parsing the `N: text` text is lossy and fragile against the truncation footer.
 
-`presentResult` returns `undefined` — the generic fallback — whenever the meta is absent or malformed (`readMetaFromMeta` narrows it defensively, so a replay of an older logged result never throws), whenever the result is an error, and whenever the single text block is not the read envelope. A pre-card logged result — a valid read envelope with no persisted `meta`, recorded before this card existed — takes that same `undefined` path deliberately: the client falls back to the raw `result.content`, so it shows the enveloped `<path>/<type>/<content>` text rather than the envelope-stripped generic card the old presenter returned. This is the accepted degradation under the [pre-release stance](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius): reject the old on-disk format rather than add an envelope-stripping compatibility branch, since this PR re-records every published fixture and the session format promises no backward compatibility. On the success path `presentResult` carries `content` (the envelope-stripped text) alongside the structured fields, so a UI without the read capability renders the file text through its generic/default card arm. The former TUI established the need for this fallback: its non-exhaustive result switch read `view.content`, while a separate dim-Markdown gate also had to admit `card: 'read'`. That frontend has since been removed, but the content fallback remains part of the view contract for any consumer without a structured read card.
+`presentResult` returns `undefined` — the generic fallback — whenever the meta is absent or malformed (`readMetaFromMeta` narrows it defensively, so a replay of an older logged result never throws), whenever the result is an error, and whenever the single text block is not the read envelope. A pre-card logged result — a valid read envelope with no persisted `meta`, recorded before this card existed — takes that same `undefined` path deliberately: the client falls back to the raw `result.content`, so it shows the enveloped `<path>/<type>/<content>` text rather than the envelope-stripped generic card the old presenter returned. This is the accepted degradation under the [pre-release stance](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius): reject the old on-disk format rather than add an envelope-stripping compatibility branch, since this change re-records every published fixture and the session format promises no backward compatibility. On the success path `presentResult` carries `content` (the envelope-stripped text) alongside the structured fields, so a UI without the read capability renders the file text through its generic/default card arm. The former TUI established the need for this fallback: its non-exhaustive result switch read `view.content`, while a separate dim-Markdown gate also had to admit `card: 'read'`. That frontend has since been removed, but the content fallback remains part of the view contract for any consumer without a structured read card.
 
 ### Language hint derivation
 
@@ -40,7 +40,7 @@ The read tool now computes `presentationMeta` for every top-level read, a small
 
 ## Testing
 
-`packages/fs/tool-fs/tests/read-render.spec.ts` unit-tests `langFromPath` (known extensions case-insensitively, extension read after the last segment and last dot, and the `undefined` cases: dotfile, extensionless, trailing dot, unknown) and `readMetaFromMeta` (a well-formed narrow with and without `lang`, and every rejection: non-object, array, missing or wrong-typed `path`/`totalLines`/`lines`, a malformed line entry, a non-string `lang`, and — because the function narrows the opaque persisted `meta` boundary — the semantically invalid paths a well-typed replayed JSON can still carry: an `offset` that is not a 1-based integer, a first line `number` below `offset`, a line `number` that is not a 1-based integer (`0`, `1.5`, `NaN`, `Infinity`), a `totalLines` that is not a non-negative integer (`-1`, `1.5`, `NaN`), and lines whose numbers duplicate, decrease, or exceed `totalLines`; it also narrows an empty window at a positive `offset` (a byte cap below the first selected line). `packages/fs/tool-fs/tests/tools.spec.ts` pins the tool wiring: `execute` attaches the structured window (with and without a `lang` hint) as `meta`, `presentResult` narrows it into a `card: 'read'` view carrying the envelope-stripped `content`, and the decline paths (error result, non-single-text content, malformed envelope with valid meta, and valid envelope with absent or malformed meta) all fall back to `undefined`. Both changed source files hold per-file 100% coverage. This PR carries the snapshot evidence for the persisted meta and the extended union, not for a new rendered view: the re-recorded ACP session fixtures (`fs-read`, `fs-read-window`, `fs-edit`, `fs-policy-reject`, `fs-write-overwrite`, `parallel-tool-calls`, `workspace-context`, `workspace-edit`) pin the persisted read `meta` (with `{{cwd}}`-tokenized paths), and `cordis-inspect-jsdoc` pins the four-member `ToolResultView` union. The then-current terminal snapshot also pinned that a consumer's generic dim-Markdown fallback stayed byte-identical; the structured card's own assembled-application transcript belonged to its consuming frontend change.
+`packages/fs/tool-fs/tests/read-render.spec.ts` unit-tests `langFromPath` (known extensions case-insensitively, extension read after the last segment and last dot, and the `undefined` cases: dotfile, extensionless, trailing dot, unknown) and `readMetaFromMeta` (a well-formed narrow with and without `lang`, and every rejection: non-object, array, missing or wrong-typed `path`/`totalLines`/`lines`, a malformed line entry, a non-string `lang`, and — because the function narrows the opaque persisted `meta` boundary — the semantically invalid paths a well-typed replayed JSON can still carry: an `offset` that is not a 1-based integer, a first line `number` below `offset`, a line `number` that is not a 1-based integer (`0`, `1.5`, `NaN`, `Infinity`), a `totalLines` that is not a non-negative integer (`-1`, `1.5`, `NaN`), and lines whose numbers duplicate, decrease, or exceed `totalLines`; it also narrows an empty window at a positive `offset` (a byte cap below the first selected line). `packages/fs/tool-fs/tests/tools.spec.ts` pins the tool wiring: `execute` attaches the structured window (with and without a `lang` hint) as `meta`, `presentResult` narrows it into a `card: 'read'` view carrying the envelope-stripped `content`, and the decline paths (error result, non-single-text content, malformed envelope with valid meta, and valid envelope with absent or malformed meta) all fall back to `undefined`. Both changed source files hold per-file 100% coverage. This change carries the snapshot evidence for the persisted meta and the extended union, not for a new rendered view: the re-recorded ACP session fixtures (`fs-read`, `fs-read-window`, `fs-edit`, `fs-policy-reject`, `fs-write-overwrite`, `parallel-tool-calls`, `workspace-context`, `workspace-edit`) pin the persisted read `meta` (with `{{cwd}}`-tokenized paths), and `cordis-inspect-jsdoc` pins the four-member `ToolResultView` union. The then-current terminal snapshot also pinned that a consumer's generic dim-Markdown fallback stayed byte-identical; the structured card's own assembled-application transcript belonged to its consuming frontend change.
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
index c48cd56b7f..68ab9a118e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 read 工具通过 `output.presentationMeta` 投影结构化窗口，这与 write/edit 用来投影其应用 diff hunk 的持久化通道相同（[规范化工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md)）。`presentationMeta` 对一次顶层 surface 调用运行一次，返回 `{ path, offset, lines, totalLines, lang? }` 作为会话校验并存储在结果 `meta` 上的 JSON，`presentResult` 在 live 和回放路径上都把该 meta 收窄回 `ReadResultView`。`offset`（窗口请求的 1-based 起始行）一并携带，是因为当字节上限低于首个选中行时，窗口会返回空的 `lines` 数组而 `totalLines` 为正；没有持久化的 `offset`，这类窗口的回放 card 就无法报告它从哪行开始、或续读应从哪行继续，而末行推断与文本重解析两种兜底都有损。没有这个通道，行数组和总数就无法触及：原始输出对象不在线上，而重新解析 `N: text` 文本既有损又对截断脚注脆弱。
 
-`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本 PR 已重录全部已发布 fixtures，且 session 格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图约定的一部分。
+`presentResult` 在以下情况返回 `undefined`——即 generic 回退：meta 缺失或畸形（`readMetaFromMeta` 防御性收窄它，因此回放旧的已记录结果永不抛错）、结果是错误、以及单个文本块不是 read 信封。本 card 出现之前记录的结果——信封合法但无持久化 `meta`——有意走同一条 `undefined` 路径：客户端回退到原始 `result.content`，因此显示带 `<path>/<type>/<content>` 信封的原文，而非旧展示器返回的剥信封 generic card。这是 [pre-release 立场](../../../../AGENTS.md#pre-release-stance-foundation-over-blast-radius)下接受的降级：拒绝旧的磁盘格式，而非加一个剥信封的兼容分支——本变更已重录全部已发布 fixtures，且 session 格式不承诺向后兼容。在成功路径上，`presentResult` 在结构化字段之外携带 `content`（剥信封后的文本），因此不具备 read 能力的 UI 会通过自己的 generic/default card 分支渲染文件文本。原 TUI 证明了这条回退的必要性：它的非穷尽结果 switch 读取 `view.content`，而另一道 dim-Markdown 门控也必须接纳 `card: 'read'`。该前端随后被移除，但对任何没有结构化 read 卡片的消费方而言，content 回退仍是视图约定的一部分。
 
 ### 语言提示推导
 
@@ -40,7 +40,7 @@ read 工具现在为每次顶层 read 计算 `presentationMeta`，这是对已
 
 ## Testing
 
-`packages/fs/tool-fs/tests/read-render.spec.ts` 单测 `langFromPath`（已知扩展名的大小写不敏感、扩展名在最后一段与最后一个点之后读取、以及 `undefined` 各情况：dotfile、无扩展名、结尾的点、未知）与 `readMetaFromMeta`（含与不含 `lang` 的良构收窄，以及每种拒绝：非对象、数组、缺失或类型错误的 `path`/`totalLines`/`lines`、畸形行项、非字符串 `lang`，以及——因为该函数收窄持久化的 opaque `meta` 边界——良构类型的回放 JSON 仍可能携带的语义无效路径：不是 1-based 整数的 `offset`、小于 `offset` 的首行 `number`、不是 1-based 整数的行 `number`（`0`、`1.5`、`NaN`、`Infinity`）、不是非负整数的 `totalLines`（`-1`、`1.5`、`NaN`）、以及行号重复、递减或超过 `totalLines` 的情况；并且收窄正 `offset` 处的空窗口（字节上限低于首个选中行））。`packages/fs/tool-fs/tests/tools.spec.ts` 固定工具接线：`execute` 把结构化窗口（含与不含 `lang` 提示）作为 `meta` 附上、`presentResult` 把它收窄为携带剥信封 `content` 的 `card: 'read'` 视图、以及各拒绝路径（错误结果、非单文本内容、meta 有效但信封畸形、信封有效但 meta 缺失或畸形）都回退到 `undefined`。两个改动的源文件保持逐文件 100% 覆盖率。本 PR 携带的是持久化 meta 与扩展后联合类型的快照证据，而非新渲染视图的证据：重录的 ACP session fixtures（`fs-read`、`fs-read-window`、`fs-edit`、`fs-policy-reject`、`fs-write-overwrite`、`parallel-tool-calls`、`workspace-context`、`workspace-edit`）钉住持久化的读取 `meta`（含 `{{cwd}}` 令牌化路径），`cordis-inspect-jsdoc` 钉住四成员的 `ToolResultView` 联合类型。当时的终端快照还钉住了消费方的 generic dim-Markdown 回退保持逐字节一致；结构化卡片自身的组装应用 transcript 则属于消费它的前端变更。
+`packages/fs/tool-fs/tests/read-render.spec.ts` 单测 `langFromPath`（已知扩展名的大小写不敏感、扩展名在最后一段与最后一个点之后读取、以及 `undefined` 各情况：dotfile、无扩展名、结尾的点、未知）与 `readMetaFromMeta`（含与不含 `lang` 的良构收窄，以及每种拒绝：非对象、数组、缺失或类型错误的 `path`/`totalLines`/`lines`、畸形行项、非字符串 `lang`，以及——因为该函数收窄持久化的 opaque `meta` 边界——良构类型的回放 JSON 仍可能携带的语义无效路径：不是 1-based 整数的 `offset`、小于 `offset` 的首行 `number`、不是 1-based 整数的行 `number`（`0`、`1.5`、`NaN`、`Infinity`）、不是非负整数的 `totalLines`（`-1`、`1.5`、`NaN`）、以及行号重复、递减或超过 `totalLines` 的情况；并且收窄正 `offset` 处的空窗口（字节上限低于首个选中行））。`packages/fs/tool-fs/tests/tools.spec.ts` 固定工具接线：`execute` 把结构化窗口（含与不含 `lang` 提示）作为 `meta` 附上、`presentResult` 把它收窄为携带剥信封 `content` 的 `card: 'read'` 视图、以及各拒绝路径（错误结果、非单文本内容、meta 有效但信封畸形、信封有效但 meta 缺失或畸形）都回退到 `undefined`。两个改动的源文件保持逐文件 100% 覆盖率。本变更携带的是持久化 meta 与扩展后联合类型的快照证据，而非新渲染视图的证据：重录的 ACP session fixtures（`fs-read`、`fs-read-window`、`fs-edit`、`fs-policy-reject`、`fs-write-overwrite`、`parallel-tool-calls`、`workspace-context`、`workspace-edit`）钉住持久化的读取 `meta`（含 `{{cwd}}` 令牌化路径），`cordis-inspect-jsdoc` 钉住四成员的 `ToolResultView` 联合类型。当时的终端快照还钉住了消费方的 generic dim-Markdown 回退保持逐字节一致；结构化卡片自身的组装应用 transcript 则属于消费它的前端变更。
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
index 9233d3f0c6..37debadbe3 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.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 .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
-2026-07-30-web-result-card-frontend.md: 0f3e46cda1aeeb0f526f839a9071f09058810b86
-2026-07-30-web-result-card-frontend.zh.md: d9802099f7d2300b4a4c88556103d0c014aaebee
+2026-07-30-web-result-card-frontend.md: c048c4f93f72e4a1da5c6426497e9274d65ac266
+2026-07-30-web-result-card-frontend.zh.md: a7090818dc023f857e01e43773adccfba585cc55
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
index 0f3e46cda1..c048c4f93f 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md
@@ -24,13 +24,13 @@ The card is **resident** under the summary row in the chat rows, the same reside
 
 `WebBlock` reads only the web view's fields, so it stays a pure function of what the render intent carries — no session lookups, replay-safe like the presenters that produce the view, and unlike the terminal card it needs no cwd resolution because a web view carries no path. A UI without the `web` capability (the TUI) still gets the contract's fallback `content`; nothing about the tools' result shape changed. `MarkdownText` is reused for the answer, so the answer's own untrusted-link handling and GFM rendering come for free.
 
-A separate later PR unifies the whole-row collapse/expand interaction and will flip every resident card (terminal, diff, web) to expand-gated at once; this card follows the current resident convention rather than pre-empting that change.
+The whole-row collapse/expand interaction shared by every resident card (terminal, diff, web) is owned by the [unified expand-and-inspect note](2026-07-30-web-tool-row-unified-expand-and-inspect.md); this card follows the resident convention rather than pre-empting that interaction.
 
 ## Alternatives considered
 
 **Two components, one per kind.** Rejected: the two shapes share their card chrome, their safe-link handling, and their truncation indicator, and the contract already expresses their difference as a `kind` discriminant under one `card` tag; two components would duplicate the shared surface and split the safe-link logic.
 
-**Reparse the model-facing render text instead of consuming the structured view.** Rejected for the same reason the contract note gives: `web_search`'s render collapses each source's fields into one free-text line labelled by title OR hostname, so reparsing cannot recover `{url, title?, snippet?, publishedAt?}`. The structured `resultView` is the only faithful source, which is why the backend PR added it.
+**Reparse the model-facing render text instead of consuming the structured view.** Rejected for the same reason the contract note gives: `web_search`'s render collapses each source's fields into one free-text line labelled by title OR hostname, so reparsing cannot recover `{url, title?, snippet?, publishedAt?}`. The structured `resultView` is the only faithful source, which is why the backend contract adds it.
 
 **Render plain anchors without the protocol allowlist.** Rejected: the URL is model-authored and unverified at this presentation boundary, so an unfiltered href would let a `javascript:` URL execute on click. The allowlist is the http(s) subset of MarkdownText's (which also permits `mailto:`), so untrusted retrieval links behave identically wherever they render.
 
@@ -44,7 +44,7 @@ The fixture (`packages/client/connection/src/client/fixture.ts`) adds turns 66 (
 
 ## Related
 
-- [Web result card](2026-07-30-web-result-card.md) — the backend PR that added the `card: 'web'` result arm and made the two tools emit it; this is its deferred frontend consumer.
+- [Web result card](2026-07-30-web-result-card.md) — the backend contract that added the `card: 'web'` result arm and made the two tools emit it; this note owns its frontend consumer.
 - [Web search source card scrolls instead of collapsing](2026-08-03-web-search-source-scroll.md) — replaces this note's source-list head/tail collapse with a fixed-height scroll container and removes `CHAT_WEB_MAX_SOURCES` and the primitive's own source cap; every other decision here still holds.
 - [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent this mirrors: a `ui-primitives` block, a single card-model derivation, keyed and fallback chat rows, and a details-panel arm, for the `terminal` render intent.
 - [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) — the `card`-tagged vocabulary; the Web client is now a full consumer of the `web` arm.
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
index d9802099f7..a7090818dc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md
@@ -24,13 +24,13 @@ Status: implemented
 
 `WebBlock` 只读 web view 的字段,因此它是渲染意图所携带内容的纯函数 —— 无会话查找,与产出该视图的 presenter 一样回放安全,且不同于终端卡片它不需要 cwd 解析,因为 web view 不携带路径。没有 `web` 能力的 UI（TUI）仍得到约定的回退 `content`;工具的 result 形状没有任何改变。answer 复用 `MarkdownText`,因此 answer 自身的不受信任链接处理与 GFM 渲染免费获得。
 
-一条独立的后续 PR 会统一整行折叠/展开交互,并把每张常驻卡片（terminal、diff、web）一次性翻成 expand-gated;本卡片遵循当前的常驻约定,而非抢先做那次改动。
+每张常驻卡片（terminal、diff、web）共用的整行折叠/展开交互归[统一展开与检视 note](2026-07-30-web-tool-row-unified-expand-and-inspect.md)所有;本卡片遵循常驻约定,而非抢先做那套交互。
 
 ## Alternatives considered
 
 **两个组件,每种 kind 一个。** 拒绝:两种形状共享卡片外框、安全链接处理、截断提示,而约定已经把它们的差异表达为一个 `card` 标签下的 `kind` 判别;两个组件会重复共享表面并拆分安全链接逻辑。
 
-**重解析模型可见的渲染文本,而非消费结构化视图。** 因约定笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端 PR 添加它的原因。
+**重解析模型可见的渲染文本,而非消费结构化视图。** 因约定笔记给出的同一理由拒绝:`web_search` 的渲染把每个 source 的字段压缩成一行自由文本、以标题或主机名为标签,所以重解析无法恢复 `{url, title?, snippet?, publishedAt?}`。结构化的 `resultView` 是唯一忠实来源,这正是后端约定添加它的原因。
 
 **不加协议 allowlist 直接渲染裸锚点。** 拒绝:URL 在此展示边界处是模型创作、未经验证的,所以未过滤的 href 会让 `javascript:` URL 在点击时执行。该 allowlist 是 MarkdownText allowlist（它还允许 `mailto:`）的 http(s) 子集,因此不受信任的检索链接无论在何处渲染都行为相同。
 
@@ -44,7 +44,7 @@ fixture（`packages/client/connection/src/client/fixture.ts`）添加 turn 66（
 
 ## Related
 
-- [Web result card](2026-07-30-web-result-card.md) —— 添加 `card: 'web'` result 支路并让两个工具发出它的后端 PR;本条是它推迟的前端消费者。
+- [Web result card](2026-07-30-web-result-card.md) —— 添加 `card: 'web'` result 支路并让两个工具发出它的后端契约;其前端消费方归本 note 所有。
 - [Web search 来源卡片改为滚动而非折叠](2026-08-03-web-search-source-scroll.md) —— 用定高滚动容器替换本笔记的 source 列表头/尾折叠,并移除 `CHAT_WEB_MAX_SOURCES` 与原语自身的 source 上限;本笔记的其余决策依然成立。
 - [Web terminal card](2026-07-28-web-terminal-card.md) —— 本条所镜像的先例:一个 `ui-primitives` block、一处 card-model 派生、键控与兜底 chat 行、以及一个详情面板支路,用于 `terminal` 渲染意图。
 - [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— `card` 标签词汇;Web 客户端现在是 `web` 支路的完整消费者。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
index 9eba8730a4..cb45227d19 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.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 .agents/notes/implemented/feature/2026-07-30-web-result-card.md
-2026-07-30-web-result-card.md: 838b13a7f3240c753e5cd1af6909389055c6352d
-2026-07-30-web-result-card.zh.md: 36ab372864e5cd848b999ee759e73658271b8f90
+2026-07-30-web-result-card.md: 591471d219295019d28b9eeaf2e57f6d2115d380
+2026-07-30-web-result-card.zh.md: a2e0096599a30bcdd1d8a956d8f1c13c1c0622fd
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card.md
index 838b13a7f3..591471d219 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.md
@@ -22,7 +22,7 @@ Neither result view carries a `content` copy. A UI that does not render the stru
 
 ## Consequences
 
-The frontend consumer was a separate later PR: this producer change adds the contract arm and makes the two tools emit it, with no client-side rendering. Its one observable change is that the `web_search`/`web_fetch` `tool/result` events persist a `data.meta` payload (the `web-fetch` keyless snapshot was refreshed accordingly); model-facing render text and generic fallback content stay unchanged. The assembled-application transcript snapshot that exercises a `web` card belongs to the consumer change that renders it. Any `ToolResultView` consumer that switches exhaustively must add a `web` arm; a non-exhaustive consumer may use the raw-result fallback. `apiproxy`'s session schema already accepts any `card` string (`packages/host/apiproxy/src/api/sessions.schema.ts`), so the new view crosses the wire without a schema change.
+The frontend consumer is owned by the [web result card frontend note](2026-07-30-web-result-card-frontend.md): this producer change adds the contract arm and makes the two tools emit it, with no client-side rendering. Its one observable change is that the `web_search`/`web_fetch` `tool/result` events persist a `data.meta` payload (the `web-fetch` keyless snapshot was refreshed accordingly); model-facing render text and generic fallback content stay unchanged. The assembled-application transcript snapshot that exercises a `web` card belongs to the consumer change that renders it. Any `ToolResultView` consumer that switches exhaustively must add a `web` arm; a non-exhaustive consumer may use the raw-result fallback. `apiproxy`'s session schema already accepts any `card` string (`packages/host/apiproxy/src/api/sessions.schema.ts`), so the new view crosses the wire without a schema change.
 
 A future web tool that wants this card declares `presentResult` returning a `card: 'web'` view with its own `kind`; adding a third `kind` is a union edit plus the frontend's branch, not a new card tag.
 
@@ -41,4 +41,4 @@ A future web tool that wants this card declares `presentResult` returning a `car
 ## Related
 
 - [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) — the `card`-tagged vocabulary this extends with the `web` arm.
-- [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent that carried the bash `terminal` render intent to the browser; the web frontend consumer of this arm is its analogue, deferred to a later PR.
+- [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent that carried the bash `terminal` render intent to the browser; the [web result card frontend](2026-07-30-web-result-card-frontend.md) is its analogue for this arm.
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
index 36ab372864..a2e0096599 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 ## Consequences
 
-前端消费方由后续独立 PR 交付：本次生产者变更新增约定分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript 快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
+前端消费方归 [Web result card 前端 note](2026-07-30-web-result-card-frontend.md) 所有：本次生产者变更新增约定分支并让两个工具发出它，不含客户端渲染。其唯一可观察的变化是 `web_search`/`web_fetch` 的 `tool/result` 事件持久化一个 `data.meta` 载荷（`web-fetch` keyless 快照当时随之刷新）；面向模型的 render 文本与 generic 回退内容保持不变。渲染 `web` 卡片的组装应用 transcript 快照属于渲染它的消费方变更。任何做穷尽 switch 的 `ToolResultView` 消费方都必须新增一个 `web` 分支；非穷尽消费方可以使用原始结果回退。`apiproxy` 的会话 schema 已接受任意 `card` 字符串（`packages/host/apiproxy/src/api/sessions.schema.ts`），因此新视图无需 schema 变更即可跨 wire。
 
 未来想用此卡片的 web 工具，声明一个返回带自有 `kind` 的 `card: 'web'` 视图的 `presentResult`；新增第三个 `kind` 是一次联合类型编辑加前端的分岔，而非一个新的 card 标签。
 
@@ -41,4 +41,4 @@ Status: implemented
 ## Related
 
 - [标签化的工具调用渲染意图联合类型](../architecture/2026-07-02-tool-render-intent-union.md) —— 本卡片以 `web` 分支扩展的 `card` 标签词汇表。
-- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；本分支的 web 前端消费者是它的对应物，推迟到后续 PR。
+- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；[Web result card 前端](2026-07-30-web-result-card-frontend.md)是它在本分支上的对应物。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
index 461492312b..79bb4d0fb4 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.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 .agents/notes/implemented/feature/2026-07-30-web-search-card.md
-2026-07-30-web-search-card.md: e0be857df69dfd46b6e936c775c6bae1476c26dc
-2026-07-30-web-search-card.zh.md: 784afb0dd36f20c3a0e203d5595c46c8040d82ff
+2026-07-30-web-search-card.md: 23c89585770151551526223454e98d18716d1a44
+2026-07-30-web-search-card.zh.md: f92bd9f9231d947d4c70e283b462294c030e3f33
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
index e0be857df6..23c8958577 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-30-web-search-card.zh.md)
 
 The `grep` and `glob` tools declare a result-time `card: 'search'` render intent ([search render card](2026-07-30-search-render-card.md)): a `SearchMatchesResultView` (`shape: 'matches'`) carrying grep's matches grouped by file, or a `SearchPathsResultView` (`shape: 'paths'`) carrying glob's flat path list, both with a `truncated`/`total` capping signal. That view already reaches the browser — host, connection, and runtime deliver it onto `ConversationSnapshot` as `resultView` — but the Web client ignored it: every non-terminal, non-diff tool result fell through to the generic card, which renders the model-facing text. A web frontend that wants an expandable per-file group of matches, or a scannable path list, had only the pre-formatted text.
 
-This is the follow-up the search render card note names: that PR was the backend contract and its two producers; this PR is the web consumer.
+This is the follow-up the search render card note names: that note owns the backend contract and its two producers; this note owns the web consumer.
 
 ## Decision
 
@@ -34,7 +34,7 @@ Geometry, radius, and fonts mirror `CodeBlock` and `TerminalBlock`, so a search
 
 Three sites consume the derivation, mirroring the terminal card's placement exactly:
 
-- **The keyed `SearchRow`** (`toolviews/search-row.tsx`) registers ONE component under both `grep` and `glob` in the `tool.call.toolview` keyed hole, and renders the card RESIDENT under the summary row, capped at `CHAT_SEARCH_MAX_LINES` (8) — the same posture `BashRow` takes for its terminal card. Both tool names get the same row because the derived `kind` decides the shape, so a second component would duplicate it. A capped result's recovery footer sits below the card. Because the keyed row owns this render slot, a settled call with no search card — an errored search (grep/glob emit no result view on error), a successful nested `run_code` sub-dispatch (the backend computes no `presentationMeta`, so `resultView` is null), or a legacy generic result — would otherwise show only its summary with its content lost; the row surfaces that model-facing text as a fallback body, keyed on `search === null && settled` rather than on the error state alone. (This resident posture matches the current terminal/diff cards; a separate later PR unifies the whole-row collapse/expand interaction and flips all resident cards at once — out of scope here.)
+- **The keyed `SearchRow`** (`toolviews/search-row.tsx`) registers ONE component under both `grep` and `glob` in the `tool.call.toolview` keyed hole, and renders the card RESIDENT under the summary row, capped at `CHAT_SEARCH_MAX_LINES` (8) — the same posture `BashRow` takes for its terminal card. Both tool names get the same row because the derived `kind` decides the shape, so a second component would duplicate it. A capped result's recovery footer sits below the card. Because the keyed row owns this render slot, a settled call with no search card — an errored search (grep/glob emit no result view on error), a successful nested `run_code` sub-dispatch (the backend computes no `presentationMeta`, so `resultView` is null), or a legacy generic result — would otherwise show only its summary with its content lost; the row surfaces that model-facing text as a fallback body, keyed on `search === null && settled` rather than on the error state alone. (This resident posture matches the terminal/diff cards; the [unified expand-and-inspect note](2026-07-30-web-tool-row-unified-expand-and-inspect.md) owns the whole-row collapse/expand interaction that flipped all resident cards at once.)
 - **The generic fallback** (`chat/GenericToolCard` → `chat/ToolRow`) threads the derived model as an expand-gated body, the same arm `terminal` uses: a `grep`/`glob` result with no keyed row (none in the shipped app, since both are registered) still renders its card, with the recovery footer, behind the row's expand toggle.
 - **The details panel** (`skeleton/DetailsPanel`) renders the card at the primitive's own full height in the Output section, with the recovery footer below it, keeping the JSON Input section.
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
index 784afb0dd3..f92bd9f923 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 `grep` 与 `glob` 工具声明了一个仅在结果阶段存在的 `card: 'search'` render intent（[search render card](2026-07-30-search-render-card.md)）：`SearchMatchesResultView`（`shape: 'matches'`）携带 grep 按文件分组的匹配，或 `SearchPathsResultView`（`shape: 'paths'`）携带 glob 的扁平路径列表，两者都带 `truncated`/`total` 截断信号。该视图已经到达浏览器 —— host、connection、runtime 把它作为 `resultView` 投递到 `ConversationSnapshot` 上 —— 但 Web 客户端忽略了它：每个非终端、非 diff 的工具结果都落到 generic 卡片，渲染面向模型的文本。想把搜索结果渲染成可展开的按文件匹配分组、或可扫读的路径列表的 web 前端，只有那段预格式化文本。
 
-这正是 search render card note 指名的后续：那个 PR 是后端约定和它的两个生产者，本 PR 是 web 消费者。
+这正是 search render card note 指名的后续：后端约定和它的两个生产者归那篇 note 所有，web 消费方归本 note 所有。
 
 ## Decision
 
@@ -34,7 +34,7 @@ Status: implemented
 
 三个渲染点消费该推导，与终端卡片的落位完全一致：
 
-- **keyed `SearchRow`**（`toolviews/search-row.tsx`）把一个组件同时注册到 `tool.call.toolview` keyed hole 的 `grep` 与 `glob` 键下，并把卡片作为常驻（resident）渲染在摘要行下方，上限为 `CHAT_SEARCH_MAX_LINES`（8）—— 与 `BashRow` 对其终端卡片采取的姿态相同。两个工具名共用同一行，因为推导出的 `kind` 决定形态，第二个组件只会重复它。被截断结果的恢复脚注画在卡片下方。因为 keyed 行占据了这个渲染槽，一个没有搜索卡片的已结算调用 —— 出错的搜索（grep/glob 出错时不产出结果视图）、成功的嵌套 `run_code` 子派发（后端不为其计算 `presentationMeta`，故 `resultView` 为 null）、或旧日志的 generic 结果 —— 否则只会显示摘要而丢失内容；该行把这段面向模型的文本作为 fallback body 暴露出来，判据是 `search === null && 已结算`，而非仅凭错误状态。（该常驻姿态与当前的 terminal/diff 卡片一致；一个单独的后续 PR 会统一整行折叠/展开交互并一次性翻转所有常驻卡片 —— 不在本 PR 范围内。）
+- **keyed `SearchRow`**（`toolviews/search-row.tsx`）把一个组件同时注册到 `tool.call.toolview` keyed hole 的 `grep` 与 `glob` 键下，并把卡片作为常驻（resident）渲染在摘要行下方，上限为 `CHAT_SEARCH_MAX_LINES`（8）—— 与 `BashRow` 对其终端卡片采取的姿态相同。两个工具名共用同一行，因为推导出的 `kind` 决定形态，第二个组件只会重复它。被截断结果的恢复脚注画在卡片下方。因为 keyed 行占据了这个渲染槽，一个没有搜索卡片的已结算调用 —— 出错的搜索（grep/glob 出错时不产出结果视图）、成功的嵌套 `run_code` 子派发（后端不为其计算 `presentationMeta`，故 `resultView` 为 null）、或旧日志的 generic 结果 —— 否则只会显示摘要而丢失内容；该行把这段面向模型的文本作为 fallback body 暴露出来，判据是 `search === null && 已结算`，而非仅凭错误状态。（该常驻姿态与 terminal/diff 卡片一致；一次性翻转了所有常驻卡片的整行折叠/展开交互归[统一展开与检视 note](2026-07-30-web-tool-row-unified-expand-and-inspect.md)所有。）
 - **generic fallback**（`chat/GenericToolCard` → `chat/ToolRow`）把推导出的 model 作为展开门控的 body 传入，与 `terminal` 用的是同一分支：没有 keyed 行的 `grep`/`glob` 结果（发布应用里没有，因为两者都注册了）仍在行的展开开关后渲染其卡片，并带恢复脚注。
 - **details panel**（`skeleton/DetailsPanel`）在 Output 段以 primitive 自身的完整高度渲染卡片，恢复脚注画在其下方，保留 JSON Input 段。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
index 2c8ee18abb..69c4251608 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.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 .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
-2026-07-31-code-mode-language-dispatch.md: 3a6e248160f165d6b341a5c8719abffd69a43820
-2026-07-31-code-mode-language-dispatch.zh.md: 46ef842f4b4209787c831b657159a97604324a66
+2026-07-31-code-mode-language-dispatch.md: 9e834ff2eb8e5f8326ef6d7f862385cadede6149
+2026-07-31-code-mode-language-dispatch.zh.md: d7d83146a7a5a9ed7fa4b051822e51b974e43b4e
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
index 3a6e248160..9e834ff2eb 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md
@@ -19,7 +19,7 @@ Language selection is a lookup on `ctx.codeRuntime.language`, resolved lazily at
 
 Both tables are read with `Object.hasOwn` before use so a language named `toString`/`constructor` cannot resolve an inherited `Object.prototype` member as a renderer. The two guards differ in reachability: `SDK_RENDERERS`' in-callback guard is unreachable because `requireCodeRuntime` validated the same `const` table earlier in the same callback (it carries a `/* v8 ignore */`), while `RUN_CODE_FLAVORS`' guard is the primary, publicly reachable rejection — any language absent from the flavor table hits it through `run_code`'s language-aware getters, which the public `schemas()` reaches without passing `requireCodeRuntime` first; the test reads one of those getters off the definition directly, under a language absent from both tables. A language present in `SDK_RENDERERS` but not `RUN_CODE_FLAVORS` is drift the shared `CodeSdkLanguage` `satisfies` pins reject at `typecheck`, so it is not an input either guard can see; what the guards still own is a mounted runtime reporting a language absent from both tables. Schema emission reads the runtime through `peekRuntime()` rather than `requireRuntime()`: `undefined` (no runtime mounted, reached by definition readers and `schemas()`, of which the doc-catalog harvest is the only shipped one and none of which feeds a model because assembly passes `requireCodeRuntime` first) degrades to the TypeScript flavor, whereas a mounted unknown language fails loud — this is NOT the silent fallback rejected below, which concerns emitting a wrong-language SDK for a real runtime. Adding a backend language is three parallel edits — a `CodeSdkLanguage` member and the two table entries — plus its renderer and the prose that names the well-known values instead of deriving them (the seam's `dsh-code-runtime` README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair; this package's own README pair and its `Config.mode` JSDoc — no gate checks any of it), with no `agent-loop` or registry-structure change.
 
-`code-mode.ts` depends only on the runtime Service Definition (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer therefore lands independently of the protocol and backend PRs — it needs only the service's `language` field, which is already on master.
+`code-mode.ts` depends only on the runtime Service Definition (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer is therefore independent of the Python protocol and backend — it needs only the service's `language` field.
 
 ### The Python SDK renderer
 
@@ -37,9 +37,9 @@ The standard that cap serves is grammatical validity, and the boundary is delibe
 
 ## Consequences
 
-Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the Consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the Service Definition package must not import its Consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the Service Definition would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend.
+Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: at the Consumer's integration point rather than where the drift was introduced — and never while no second backend exists. The tables keep their `Record<string, …>` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as they stood at the time and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the Service Definition package must not import its Consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the Service Definition would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it ships and is testable ahead of the Python protocol and backend.
 
-The cost is that the Python branch of both tables is unreachable on this base: `CodeRuntime.language` is set by the loaded backend, the only published backend is `dsh-code-runtime-worker` (`'typescript'`), and the registry reads the loaded runtime rather than a config field, so no assembled application can select `renderToolsSdkPy` or `PYTHON_FLAVOR`. The model-visible surface is therefore unchanged by this note's work until a backend reporting `'python'` is published, and this PR's coverage is unit-level — the renderer output plus the dispatch and rejection paths. The keyless snapshot for the Python model interface belongs to the PR that publishes that backend, because only there does a real `cordis.yml` over published plugins produce a Python assembly; a snapshot example that mounted a fixture runtime here would assert against a test double, which [docs/testing.md](../../../../docs/testing.md) rejects as a substitute for the assembled application transcript.
+The cost is that the Python branch of both tables is unreachable in the shipped tree: `CodeRuntime.language` is set by the loaded backend, the only published backend is `dsh-code-runtime-worker` (`'typescript'`), and the registry reads the loaded runtime rather than a config field, so no assembled application can select `renderToolsSdkPy` or `PYTHON_FLAVOR`. The model-visible surface is therefore unchanged by this note's work until a backend reporting `'python'` is published, and this change's coverage is unit-level — the renderer output plus the dispatch and rejection paths. The keyless snapshot for the Python model interface belongs to the change that publishes that backend, because only there does a real `cordis.yml` over published plugins produce a Python assembly; a snapshot example that mounted a fixture runtime here would assert against a test double, which [docs/testing.md](../../../../docs/testing.md) rejects as a substitute for the assembled application transcript.
 
 Two runtime contracts the Python SDK text asserts are owed by that same backend PR. First, the instructions tell the model that exactly `tools` and `ToolCallError` are bound and that the declared `TypedDict` classes are not, so the backend must inject those two names — with `ToolCallError.toolName` populated per the seam's `errorClass` contract — and must NOT bind the declared class names into the program's globals; injecting them "helpfully" would make the SDK text false. Second, the language has to be bound to the request: `requireCodeRuntime` resolves `ctx.codeRuntime` separately at assembly and at `run_code` execution, so a reload that swapped the runtime between those two points would hand a program written against one flavor to the other. The split is finer than those two points — `run_code`'s `description` and `parameters` getters each call `resolveFlavor(peekRuntime())`, and `schemaOf` destructures both, so one projection reads the runtime twice; both reads are for `run_code`'s own schema, since the getters are installed on that one definition and every other definition carries plain data properties. A reload between those two reads yields a single schema whose two halves name different languages. Neither is reachable here — one published backend means both reads return the same flavor and no program ever runs against this renderer's output — and the cross-language rejection is not testable until a second language exists.
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
index 46ef842f4b..d7d83146a7 100644
--- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md
@@ -19,7 +19,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 
 两张表在使用前都以 `Object.hasOwn` 读取，这样名为 `toString`/`constructor` 的语言不会把继承自 `Object.prototype` 的成员解析成渲染器。两个守卫的可达性不同：`SDK_RENDERERS` 的段内守卫不可达，因为 `requireCodeRuntime` 已在同一回调更早处校验过同一张 `const` 表（它带 `/* v8 ignore */`）；而 `RUN_CODE_FLAVORS` 的守卫是主要的、可公开到达的拒绝路径——任何缺席 flavor 表的语言都经 `run_code` 的语言感知 getter 到达它，而公共 `schemas()` 抵达那些 getter 时并未先过 `requireCodeRuntime`；测试直读 definition 上的其中一个 getter，用的是对两张表都缺席的语言。「在 `SDK_RENDERERS` 里却不在 `RUN_CODE_FLAVORS` 里」这种漂移已由共享的 `CodeSdkLanguage` `satisfies` 在 `typecheck` 处拒绝，两个守卫都看不到这种输入；它们如今负责的是所挂载运行时报告了一门两张表都缺席的语言。schema 发射通过 `peekRuntime()` 而非 `requireRuntime()` 读取运行时：`undefined`（无运行时，由直读 definition 的读者与 `schemas()` 到达，其中 doc-catalog 采集是唯一已交付的一个，而它们都不会喂给模型，因为组装路径先过 `requireCodeRuntime`）降级到 TypeScript flavor，而挂载了未知语言则 fail loud——这不是下方被否决的静默回退，那指的是为真实运行时发出错误语言的 SDK。新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员加两条表项——再加它的渲染器，以及点名已知值而非从中派生的散文（seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对；本包自己的 README 双语对与它的 `Config.mode` JSDoc，无任何 gate 检查其中任何一处），不动 `agent-loop`，也不动注册表结构。
 
-`code-mode.ts` 只依赖运行时 Service Definition（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于协议和后端 PR 落地——它只需要服务的 `language` 字段，而该字段已在 master 上。
+`code-mode.ts` 只依赖运行时 Service Definition（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于 Python 协议和后端——它只需要服务的 `language` 字段。
 
 ### Python SDK 渲染器
 
@@ -32,14 +32,14 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd
 ## Alternatives considered
 
 - **在 `ToolRegistry` 上加一个 `language` 配置字段。** 那样部署方就会有两处命名语言（所加载的运行时与 tools 配置）且可能相互矛盾；所加载的运行时是唯一真相来源，故注册表读取它而不复制它。
-- **把 Python 后端 import 进 `code-mode.ts` 来检测它。** 那会把工具层耦合到具体后端，并迫使协议/后端 PR 先落地。按 `language` 运行时分发使该层保持后端无关、可独立发布。
+- **把 Python 后端 import 进 `code-mode.ts` 来检测它。** 那会把工具层耦合到具体后端，并迫使协议/后端 PR（Pull Request）先落地。按 `language` 运行时分发使该层保持后端无关、可独立发布。
 - **为未知语言提供默认渲染器。** 静默回退会在比如 Ruby 运行时上发出 TypeScript SDK——模型会看到错误语言的指令。在装配处 fail loud 是本仓库对错误配置的立场。
 
 ## Consequences
 
-新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在 Consumer 的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：Service Definition 包不得 import 其 Consumer 的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 Service Definition 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。
+新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：触发点在 Consumer 的集成处而非漂移引入处——而只要不存在第二个后端，就永远不会触发。两张表的声明类型仍是 `Record<string, …>`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：Service Definition 包不得 import 其 Consumer 的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 Service Definition 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端交付并可测。
 
-代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
+代价是两张表的 Python 分支在已交付的代码树中不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本变更的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个变更，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。
 
 Python SDK 文本断言的两条运行时约定同样归属那个 backend PR。其一，说明文字告诉模型运行时恰好绑定 `tools` 与 `ToolCallError` 两个名字、所声明的 `TypedDict` 类不绑定，因此后端必须注入这两个名字（并按 seam 的 `errorClass` 约定填充 `ToolCallError.toolName`），且**不得**把所声明的类名绑进程序全局——「好心」注入会使这段 SDK 文本变成假话。其二，语言必须绑定到请求上：`requireCodeRuntime` 在组装时与 `run_code` 执行时分别解析 `ctx.codeRuntime`，若在这两点之间发生重载并换掉运行时，就会把针对一种形态写成的程序交给另一种形态执行。分裂比这两点更细——`run_code` 的 `description` 与 `parameters` 两个 getter 各自调用 `resolveFlavor(peekRuntime())`，而 `schemaOf` 会解构这两个字段，因此一次投影读两次运行时；两次都属于 `run_code` 自己的 schema，因为这两个 getter 只装在那一个 definition 上，其余 definition 携带的都是普通数据属性。在这两次读取之间重载会产出单个 schema 的两半分属不同语言。两者在此处都不可达——只有一个已发布后端意味着两次读取返回同一形态，且没有任何程序会针对本渲染器的输出运行——而跨语言拒绝在第二门语言存在之前也无法测试。
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
index 2d393ff905..47e1e0144b 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.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 .agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
-2026-07-31-telemetry-anonymous-user-id.md: 3c8e3324cb418eac48cb5ae780c55bbcbaf3caa1
-2026-07-31-telemetry-anonymous-user-id.zh.md: 6ba1b7abe0f253fc91e7f8856d9dc9d1d961550b
+2026-07-31-telemetry-anonymous-user-id.md: f53fc9ce7eb3a5aefcb0be0a20c7403b5601e369
+2026-07-31-telemetry-anonymous-user-id.zh.md: 99b2dd88df94810ccfc85d099e74a6f0852153a7
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
index 3c8e3324cb..f53fc9ce7e 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
@@ -10,7 +10,7 @@ Session telemetry is mounted by default ([default-mount Note](2026-07-31-web-tel
 
 ## Decision
 
-The `session-telemetry-otel` package's own module `src/user-id.ts` owns the OTel feed's user identity: `getOrCreateAnonymousUserId()` returns the bare UUID line in `$DSH_HOME/.userid` (resolved by `resolveDshHome`, `$DSH_HOME` > `~/.dsh`), minting and persisting a random UUID v4 on first use; the backend constructor carries it as the Resource's `user.id` (the OTel semconv user attribute), once per export batch. This identity belongs to the OTel feed alone; the dsh-sdk launcher telemetry keeps its own anonymous-id store (`telemetry.json`), and the two are not shared (the first cut unified both feeds through a shared util package; the user reconsidered and pulled it back — no shared package before a second real consumer exists, revisit when a feed-correlation need appears).
+The `session-telemetry-otel` package's own module `src/user-id.ts` owns the OTel feed's user identity: `getOrCreateAnonymousUserId()` returns the bare UUID line in `$DSH_HOME/.userid` (resolved by `resolveDshHome`, `$DSH_HOME` > `~/.dsh`), minting and persisting a random UUID v4 on first use; the backend constructor carries it as the Resource's `user.id` (the OTel semconv user attribute), once per export batch. This identity belongs to the OTel feed alone; the dsh-sdk launcher telemetry keeps its own anonymous-id store (`telemetry.json`), and the two are not shared (the first cut unified both feeds through a shared util package — no shared package before a second real consumer exists, revisit when a feed-correlation need appears).
 
 | Ruling | Value | Rationale |
 |---|---|---|
diff --git a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
index 6ba1b7abe0..99b2dd88df 100644
--- a/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md
@@ -10,7 +10,7 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
 
 ## Decision
 
-`session-telemetry-otel` 包内模块 `src/user-id.ts` 是 OTel 回流用户身份的属主：`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；backend 构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。该身份只属于 OTel 回流；dsh-sdk launcher telemetry 保留自己的匿名 id 存储（`telemetry.json`），两者不共享（初版曾做公用 util 包统一两条回流，用户复议后收回：在有第二个真实消费者之前不抽公共包，回流关联需求出现时再议）。
+`session-telemetry-otel` 包内模块 `src/user-id.ts` 是 OTel 回流用户身份的属主：`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；backend 构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。该身份只属于 OTel 回流；dsh-sdk launcher telemetry 保留自己的匿名 id 存储（`telemetry.json`），两者不共享（初版曾做公用 util 包统一两条回流——在有第二个真实消费者之前不抽公共包，回流关联需求出现时再议）。
 
 | 裁定 | 取值 | 理由 |
 |---|---|---|
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
index dc6aad3b11..cdf7fa71b1 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.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 .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
-2026-07-31-web-workspace-file-links.md: fe71a2d8caa4dc9cc732a250d7e388d1a3b44182
-2026-07-31-web-workspace-file-links.zh.md: d2e49f4816a014dd5ec700b4d6f8fa0bede03e67
+2026-07-31-web-workspace-file-links.md: 977a24adf2f87db8a34027f36feccee44d231f9d
+2026-07-31-web-workspace-file-links.zh.md: c350fad4c74c3ed6121aa5cb1243b43140196c68
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
index fe71a2d8ca..977a24adf2 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md
@@ -20,7 +20,7 @@ Two distinct defects sat behind that. The transcript never said what a turn had
 
 **Opening stays the Host's job, and prefers the default browser.** `host.openPath` hands the path to the operating system, which yields a `file://` document in a real browser: full page capabilities, and no reachability into `/api`, because a `file://` document is not same-origin with it. Measured on the reported artifact: `localStorage` works, the theme toggle flips, the tabs switch, and `fetch` to the API fails. For documents a browser renders — `.html`, `.htm`, `.xhtml`, `.svg` — the opener resolves the default *browser* rather than the type's default application when the platform can name one, because a developer who binds `.html` to an editor would otherwise click a produced page and get source code. macOS reads the LaunchServices `https` handler and desktop Linux reads `$BROWSER`; either falls back to the default application when no browser can be named. Windows uses its registered association, and WSL first translates the path before using that same Windows handoff.
 
-**Serving workspace files over HTTP is out of scope, and so are non-local clients.** An earlier revision served files from the harness itself — first same-origin with `/api`, then behind `CSP: sandbox`, then from a second listener whose own port gave served documents their own origin. Each step answered a real problem, and the whole line was retired once the product scope was settled: previews for a browser that is not on the Host machine are not supported. With that decided, the Host opener answers the supported case completely and the HTTP machinery answered only the unsupported one.
+**Serving workspace files over HTTP is out of scope, and so are non-local clients.** Serving files from the harness itself — same-origin with `/api`, behind `CSP: sandbox`, or from a second listener whose own port gives served documents their own origin — was rejected with the product scope: previews for a browser that is not on the Host machine are not supported, so the Host opener answers the supported case completely and the HTTP machinery would answer only the unsupported one.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
index d2e49f4816..c350fad4c7 100644
--- a/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 **打开仍然是 Host 的职责，并且优先选用默认浏览器。** `host.openPath` 把路径交给操作系统，得到的是真实浏览器里的一份 `file://` 文档：页面能力完整，且够不到 `/api`——因为 `file://` 文档与它并不同源。在所报告的那份产物上实测：`localStorage` 可用、主题切换生效、tabs 可切换，而对 API 的 `fetch` 失败。对浏览器能渲染的文档——`.html`、`.htm`、`.xhtml`、`.svg`——平台能够确定默认浏览器时，打开器解析的是默认**浏览器**而非该类型的默认应用，因为把 `.html` 绑给编辑器的开发者，否则点开一个产出的页面得到的会是源码。macOS 读取 LaunchServices 的 `https` 处理程序，桌面 Linux 读取 `$BROWSER`；无法确定浏览器时，两者都会回退到默认应用。Windows 使用其注册的文件关联，WSL 则先转换路径，再使用同一 Windows 交接。
 
-**以 HTTP 提供工作区文件不在范围内，非本机客户端亦然。** 更早的一版由 harness 自己提供文件——先是与 `/api` 同源，随后加上 `CSP: sandbox`，再后来交给一个以自身端口给所服务文档独立源的第二监听器。每一步都在回答一个真实问题，而整条线在产品范围定下之后被整体退役：不为“浏览器不在 Host 机器上”的场景提供预览。这一点定下之后，Host 打开器完整回答了受支持的场景，而那套 HTTP 机制回答的只是不受支持的那个。
+**以 HTTP 提供工作区文件不在范围内，非本机客户端亦然。** 由 harness 自己提供文件——与 `/api` 同源、置于 `CSP: sandbox` 之后、或交给一个以自身端口给所服务文档独立源的第二监听器——随产品范围一并否决：不为“浏览器不在 Host 机器上”的场景提供预览，因此 Host 打开器完整回答受支持的场景，而那套 HTTP 机制只会回答不受支持的那个。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
index 602d272b0b..be7a6a1962 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.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 .agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
-2026-08-02-pwsh-tool-bash-parity.md: e35a903892d5d50a0d3ca12b23daa53f26d6aade
-2026-08-02-pwsh-tool-bash-parity.zh.md: c6e1d69bd061f0794b125e225d8f976bd82224e7
+2026-08-02-pwsh-tool-bash-parity.md: d61dd6f21223121973520014c44e2e5846e7387a
+2026-08-02-pwsh-tool-bash-parity.zh.md: 120f66b1d9c713d5e3b71575186fc2194b0718a5
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
index e35a903892..d61dd6f212 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-02-pwsh-tool-bash-parity.zh.md)
 
 ## Problem
 
-The first Windows-native foundation shipped `dsh-tool-pwsh` as a deliberately minimal profile — foreground only (a fresh process per call; no persistent PTY session), no managed-environment parity beyond three hardcoded `DSH_*` keys, and a marker story ("always `[exit code: N]`") that diverged from the bash tool's rendering without being declared. Review of that change found the model-visible contract drifting from the implementation: the description promised spill-path reporting the renderer never performed, the README claimed exports that did not exist and rendering the tool did not do, and the tool's own tests pinned the lossy behavior. The minimal profile also left the `DSH_*` contributor seam duplicated-by-absence: plugins contributing environment facts to `ctx.bashEnv` had no effect on pwsh calls.
+The first Windows-native foundation shipped `dsh-tool-pwsh` as a deliberately minimal profile — foreground only (a fresh process per call; no persistent PTY session), no managed-environment parity beyond three hardcoded `DSH_*` keys, and a marker story ("always `[exit code: N]`") that diverged from the bash tool's rendering without being declared. The model-visible contract drifted from the implementation: the description promised spill-path reporting the renderer never performed, the README claimed exports that did not exist and rendering the tool did not do, and the tool's own tests pinned the lossy behavior. The minimal profile also left the `DSH_*` contributor seam duplicated-by-absence: plugins contributing environment facts to `ctx.bashEnv` had no effect on pwsh calls.
 
 ## Decision
 
@@ -20,7 +20,7 @@ The first Windows-native foundation shipped `dsh-tool-pwsh` as a deliberately mi
 
 ## Alternatives considered
 
-**Keep the minimal profile and fix only the claims.** Rejected: the review's core finding was that text contracts copied from bash drift without the corresponding implementation; a minimal tool plus accurate claims still leaves pwsh calls without background execution, without contributor parity, and with a divergent marker story that must be re-justified forever.
+**Keep the minimal profile and fix only the claims.** Rejected: text contracts copied from bash drift without the corresponding implementation; a minimal tool plus accurate claims still leaves pwsh calls without background execution, without contributor parity, and with a divergent marker story that must be re-justified forever.
 
 **Reject a mismatched executor dialect at load.** Attempted and reverted before merge: a `ShellDialect` marker (`bash` | `powershell`) on `BashExecutor`, with both shell tools throwing when the mounted executor speaks another shell. It forced every executor implementation — including each test and example fake — to declare a dialect, adding noise to every shell-tool test for a guard with no in-repo or plausible deployment to catch (shipped compositions always pair tool-pwsh with `dsh-pwsh-local` and tool-bash with `dsh-bash-local`). The pairing contract stays documented in each tool's README instead.
 
@@ -28,7 +28,7 @@ The first Windows-native foundation shipped `dsh-tool-pwsh` as a deliberately mi
 
 ## Consequences
 
-- The bash and pwsh tools are now behaviorally interchangeable for foreground and background shell work (minus sandbox), and the pwsh prompt/description sentences are each backed by the renderer — the reviewer's grep-against-code check passes.
+- The bash and pwsh tools are now behaviorally interchangeable for foreground and background shell work (minus sandbox), and the pwsh prompt/description sentences are each backed by the renderer.
 - Parity ran BOTH ways once: the pwsh tool's structured foreground abort (`HarnessError('tool call aborted', TOOL_ABORTED)` with name `AbortError`) was backported to the bash tool, replacing its uncoded `Error('command aborted')` — a model-visible/logged change pinned by exact-shape tests on both sides and by the cancel-tool-calls fixture.
 - `@deepseek-ai/dsh-bash-env` is a new shipped package; `dsh-tool-bash`'s `dshHome` config moved there, so compositions mounting the shell tools must also mount `bash-env` (the spine bundles do).
 - Windows-only semantics (CRLF normalization, forced-termination exit-1/signal-null, POSIX-only self-signal) remain pinned by tests as before.
diff --git a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
index c6e1d69bd0..120f66b1d9 100644
--- a/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。对该变更的 review 发现模型可见约定与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
+首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。模型可见约定曾与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
 
 ## 决策
 
@@ -20,7 +20,7 @@ Status: implemented
 
 ## 备选方案
 
-**保留最小画像，只修声明。** 否决：review 的核心发现是"从 bash 复制的文本约定在缺少对应实现时会漂移"；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
+**保留最小画像，只修声明。** 否决：从 bash 复制的文本约定在缺少对应实现时会漂移；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
 
 **在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对约定改由各工具 README 记录。
 
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 后果
 
-- bash 与 pwsh 工具在前台与后台 shell 工作（减 sandbox）上行为可互换，pwsh 的 prompt/描述句每句都有渲染器背书——reviewer 的“拿代码 grep 对证”检查通过。
+- bash 与 pwsh 工具在前台与后台 shell 工作（减 sandbox）上行为可互换，pwsh 的 prompt/描述句每句都有渲染器背书。
 - 对齐也反向发生过一次：pwsh 工具的结构化前台中止（`HarnessError('tool call aborted', TOOL_ABORTED)`，name 为 `AbortError`）被回移到 bash 工具，取代其无码的 `Error('command aborted')`——这是模型可见/入日志的变更，由两侧的精确形状测试与 cancel-tool-calls fixture 钉住。
 - `@deepseek-ai/dsh-bash-env` 成为新的交付包；`dsh-tool-bash` 的 `dshHome` 配置迁往那里，因此挂载 shell 工具的组合也必须挂载 `bash-env`（spine bundle 已如此）。
 - Windows 专属语义（CRLF 归一化、强制终止 exit-1/signal-null、仅 POSIX 的自信号）一如既往由测试钉住。
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
index 97a03bb17b..5b9ac0a958 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.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 .agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
-2026-08-02-win32-in-process-folder-dialog.md: 5389293605169ce5ca269a127de5f609b8b7dd11
-2026-08-02-win32-in-process-folder-dialog.zh.md: db4a6503f37f4b9cc95ce79ab8f476aeedfe5a60
+2026-08-02-win32-in-process-folder-dialog.md: ef9232051d0ff6e3e752f08a68e9f04ce3c32ad6
+2026-08-02-win32-in-process-folder-dialog.zh.md: 8fc1114aa93e563c91185396b8dcc4d344064555
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
index 5389293605..ef9232051d 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-02-win32-in-process-folder-dialog.zh.md)
 
 ## Problem
 
-The Windows directory picker's primary tier was a spawned PowerShell script around WinForms `FolderBrowserDialog`: the modern dialog only where PowerShell 7 happens to be installed, a review-flagged regression where PowerShell 6 resolves but has no WinForms (exit 1 is not `ENOENT`, so the 5.1 fallback never ran), a `SetProcessDPIAware` ceiling of system DPI, and a picker whose behavior depended on which shells a machine ships rather than on Windows itself.
+The Windows directory picker's primary tier was a spawned PowerShell script around WinForms `FolderBrowserDialog`: the modern dialog only where PowerShell 7 happens to be installed, a regression where PowerShell 6 resolves but has no WinForms (exit 1 is not `ENOENT`, so the 5.1 fallback never ran), a `SetProcessDPIAware` ceiling of system DPI, and a picker whose behavior depended on which shells a machine ships rather than on Windows itself.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
index db4a6503f3..8fc1114aa9 100644
--- a/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-02-win32-in-process-folder-dialog.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-Windows 目录选择器的主层此前是围绕 WinForms `FolderBrowserDialog` spawn 出的 PowerShell 脚本：只有恰好安装了 PowerShell 7 的机器才有现代对话框；review 指出的回归——PowerShell 6 可解析却没有 WinForms（退出码 1 而非 `ENOENT`，5.1 回退永远不会触发）；`SetProcessDPIAware` 只有系统 DPI 的上限；选择器的行为取决于机器装了哪些 shell，而不是取决于 Windows 本身。
+Windows 目录选择器的主层此前是围绕 WinForms `FolderBrowserDialog` spawn 出的 PowerShell 脚本：只有恰好安装了 PowerShell 7 的机器才有现代对话框；一处回归——PowerShell 6 可解析却没有 WinForms（退出码 1 而非 `ENOENT`，5.1 回退永远不会触发）；`SetProcessDPIAware` 只有系统 DPI 的上限；选择器的行为取决于机器装了哪些 shell，而不是取决于 Windows 本身。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
index 35628efcfe..49a14093ef 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.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 .agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
-2026-08-03-web-search-source-scroll.md: 3215302b2f6c7a4e6d6cd7440a0c7f5048b72a80
-2026-08-03-web-search-source-scroll.zh.md: 7d644b9e3950906b97d382e997eb3b204a577326
+2026-08-03-web-search-source-scroll.md: f6b118b91d3d2102e11fa7b6d068621e961a7674
+2026-08-03-web-search-source-scroll.zh.md: 58eae594bd18c58f7fb80322f6902abdbba49ba7
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
index 3215302b2f..f6b118b91d 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md
@@ -24,7 +24,7 @@ Making the list a scroll container also makes its `padding-left` a correctness c
 
 ## Alternatives considered
 
-**Raise `searchMaxResults` (or make it unbounded) so more sources reach both the model and the card.** Rejected by the user: it changes model-side behavior (more sources into every request's context, more tokens) and widens the gap between what the model reads and what the card draws. The instruction was explicit — keep the cap and the truncation, add a scrollbar.
+**Raise `searchMaxResults` (or make it unbounded) so more sources reach both the model and the card.** Rejected by the user: it changes model-side behavior (more sources into every request's context, more tokens) and widens the gap between what the model reads and what the card draws.
 
 **Keep the head/tail collapse and add scroll only to the expanded region.** Rejected: two overlapping mechanisms for one concern. Once the whole list is always rendered, the collapse arithmetic, the expand/collapse state, and the button are dead weight; scroll alone bounds the height.
 
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
index 7d644b9e39..58eae594bd 100644
--- a/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md
@@ -24,7 +24,7 @@ Status: implemented
 
 ## 考虑过的替代方案
 
-**提高 `searchMaxResults`（或让它无上限），使更多来源同时抵达模型与卡片。** 被用户否决：它改变了模型侧行为（每个请求的上下文纳入更多来源、更多 token），并拉大模型读到的内容与卡片画出的内容之间的差距。指令很明确——保留上限与截断，加一个滚动条。
+**提高 `searchMaxResults`（或让它无上限），使更多来源同时抵达模型与卡片。** 被用户否决：它改变了模型侧行为（每个请求的上下文纳入更多来源、更多 token），并拉大模型读到的内容与卡片画出的内容之间的差距。
 
 **保留首尾折叠，仅对展开区域加滚动。** 否决：一个关注点上两套重叠机制。一旦整份列表始终渲染，折叠的算术、展开/折叠状态与那个按钮都是累赘；仅靠滚动即可约束高度。
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml
index 17d590a110..4dc6bf8986 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.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 .agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md
-2026-08-04-web-composer-shared-width-axis.md: 96cddda25bf79e9f2df7a0298039c27f316befca
-2026-08-04-web-composer-shared-width-axis.zh.md: b5a455f9e8c561ae89faa9baf526fdbb263bc89a
+2026-08-04-web-composer-shared-width-axis.md: f667363fb26297046b373779e1755928d328ec96
+2026-08-04-web-composer-shared-width-axis.zh.md: 94db330b34ff719eafa9e0018f2f06099c24030c
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md
index 96cddda25b..f667363fb2 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.md
@@ -28,4 +28,4 @@ Overlay menus anchored to the card (slash menu, command popupSelect) clamp to th
 
 ## Consequences
 
-Changing the column width is now a one-line edit with the ratio relations preserved by construction, which the 736 → 748 retune during review already exercised. The cost is indirection: the widths of five surfaces are no longer readable off their own stylesheets and require following the variable chain to ConversationRoot. The container-query collapse adds the constraint that InputBar's row stays a size container; removing that declaration silently disables the permission trigger's adaptive behavior. The anonymous query also means any future second container between the row and the trigger would capture it — if that happens, the query must move or the intermediate container must be avoided.
+Changing the column width is now a one-line edit with the ratio relations preserved by construction, which the 736 → 748 retune already exercised. The cost is indirection: the widths of five surfaces are no longer readable off their own stylesheets and require following the variable chain to ConversationRoot. The container-query collapse adds the constraint that InputBar's row stays a size container; removing that declaration silently disables the permission trigger's adaptive behavior. The anonymous query also means any future second container between the row and the trigger would capture it — if that happens, the query must move or the intermediate container must be avoided.
diff --git a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
index b5a455f9e8..94db330b34 100644
--- a/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-04-web-composer-shared-width-axis.zh.md
@@ -28,4 +28,4 @@ Web 会话列的各个界面各自独立设定尺寸：transcript（文本记录
 
 ## 后果
 
-修改列宽现在是一行编辑，比例关系由构造保证——评审期间 736 → 748 的重调已经验证了这一点。代价是间接性：五个界面的宽度不再能从各自的样式表直接读出，需要沿变量链追到 ConversationRoot。容器查询收起增加了一个约束：InputBar 的行必须保持为尺寸容器；删掉那条声明会静默禁用权限触发器的自适应行为。匿名查询也意味着未来若在行与触发器之间出现第二个容器，它会截获该查询——届时查询必须迁移，或避免中间容器。
+修改列宽现在是一行编辑，比例关系由构造保证——736 → 748 的重调已经验证了这一点。代价是间接性：五个界面的宽度不再能从各自的样式表直接读出，需要沿变量链追到 ConversationRoot。容器查询收起增加了一个约束：InputBar 的行必须保持为尺寸容器；删掉那条声明会静默禁用权限触发器的自适应行为。匿名查询也意味着未来若在行与触发器之间出现第二个容器，它会截获该查询——届时查询必须迁移，或避免中间容器。
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
index 98861322f3..9ab9e55766 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.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 .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
-2026-08-05-context-form-vocabulary.md: 573be191cd228f8ca41641c4298b2987781b3435
-2026-08-05-context-form-vocabulary.zh.md: 2c7a2124f3528a6b660f6f26253bf76a53ab7b8e
+2026-08-05-context-form-vocabulary.md: 037d96ed4d9d316e62f9b9eb6909834a631c115a
+2026-08-05-context-form-vocabulary.zh.md: 693b19381bff2e2b85b0390c18354526ac421919
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
index 573be191cd..037d96ed4d 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md
@@ -19,7 +19,7 @@ The tool surface already solved this shape. `ToolCallView` has three cards, not
 - `kind` answers **who produced this** and carries no presentation choice.
 - `form` answers **what shape of information it is**. Several producers may share one form, and one producer may emit more than one over a session.
 
-The vocabulary is semantic, never visual. A value states that the content is a file's instructions or a catalog of available items; colors, icons, ordering, and collapse defaults are the consumer's business and must not enter the union. It grows one value at a time, as producers gain the structured fields their form needs. This release declares two:
+The vocabulary is semantic, never visual. A value states that the content is a file's instructions or a catalog of available items; colors, icons, ordering, and collapse defaults are the consumer's business and must not enter the union. It grows one value at a time, as producers gain the structured fields their form needs. The declared forms:
 
 **`instructions`** — instructions read out of workspace files. `workspace-context` declares it on both the startup baseline and later deltas; its existing `changes[]` already carried the paths, actions, and digests the presentation needs, so no field was added. The body lists the reconciled files above the text, and keeps the `<system-reminder>` framing verbatim: the framing is part of what the model read, so hiding it would misreport the request.
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
index 2c7a2124f3..693b19381b 100644
--- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.zh.md
@@ -19,7 +19,7 @@ Status: implemented
 - `kind` 回答**由谁产生**，不携带呈现选择。
 - `form` 回答**这是何种形态的信息**。多个生产方可以共用一种形态，一个生产方在一次会话中也可以发出多种。
 
-该词汇表是语义的，绝不涉及视觉。取值只陈述「内容是某个文件的指令」或「是一份可用项目录」；颜色、图标、排序、默认折叠状态归消费方管，不得进入这个联合类型。它随生产方补齐各自形态所需的结构化字段而逐个增长。当前词汇表声明六种形态：
+该词汇表是语义的，绝不涉及视觉。取值只陈述「内容是某个文件的指令」或「是一份可用项目录」；颜色、图标、排序、默认折叠状态归消费方管，不得进入这个联合类型。它随生产方补齐各自形态所需的结构化字段而逐个增长。已声明的形态：
 
 **`instructions`**——从工作区文件中读出的指令。`workspace-context` 在启动基线与后续增量上都声明它；其既有的 `changes[]` 已经携带了呈现所需的路径、动作与 digest，因此没有新增字段。内容区在正文之上列出对账过的文件，并原样保留 `<system-reminder>` 包装：那层包装本就是模型读到的一部分，隐藏它会歪曲这次请求。
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
index 21dc393ff4..6f924866eb 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.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 .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
-2026-08-05-pwsh-ui-bash-parity.md: 95e884e9b67f3fb3927cd5154883ab08b3e7b3bb
-2026-08-05-pwsh-ui-bash-parity.zh.md: 937e6cefd3ac74f8e2fe797cdc4480b2b78fc3cb
+2026-08-05-pwsh-ui-bash-parity.md: ba92f482e957acd00792a2a8053716047a4da27d
+2026-08-05-pwsh-ui-bash-parity.zh.md: 693b3fc26e632718ea2135282d63daa32e63e1c5
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
index 95e884e9b6..ba92f482e9 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.md
@@ -22,7 +22,7 @@ The Web UI needs no per-tool code for the card itself: the client's terminal-car
 
 **A new dedicated presentation package (e.g. `@deepseek-ai/dsh-shell-present`).** Rejected: a new package costs manifests, module-graph/catalog regeneration, and README surface for a single pure function; `@deepseek-ai/dsh-bash` is already in both tools' closures and already owns the `BashRunResult` facts the parse reconstructs.
 
-**Duplicate the parse into `tool-pwsh`'s render module (a third twin).** Rejected: the parity review's core finding was that copied text contracts drift without a shared implementation; the parse and the marker emission must co-evolve in one place, and the parse is exactly the contract the UI pill depends on.
+**Duplicate the parse into `tool-pwsh`'s render module (a third twin).** Rejected: copied text contracts drift without a shared implementation ([pwsh tool bash parity](2026-08-02-pwsh-tool-bash-parity.md)); the parse and the marker emission must co-evolve in one place, and the parse is exactly the contract the UI pill depends on.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
index 937e6cefd3..693b3fc26e 100644
--- a/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md
@@ -22,7 +22,7 @@ Web UI 的卡片本身不需要任何按工具编写的代码：客户端的 ter
 
 **新建专用呈现包（如 `@deepseek-ai/dsh-shell-present`）。** 否决：为一个纯函数新建包要付出 manifest、module-graph/目录再生成与 README 面的成本；`@deepseek-ai/dsh-bash` 已在两个工具的闭包中，且已拥有该解析重建的 `BashRunResult` 事实。
 
-**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：parity 评审的核心发现正是"复制的文本约定缺少共享实现就会漂移"；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的约定。
+**把解析复制进 `tool-pwsh` 的 render 模块（第三个孪生）。** 否决：复制的文本约定缺少共享实现就会漂移（[pwsh 工具与 bash 对齐](2026-08-02-pwsh-tool-bash-parity.md)）；解析与 marker 发出必须在同一处共同演化，而解析恰恰是 UI pill 依赖的约定。
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml b/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
index 4b85d13e3d..39d3a0acf5 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.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 .agents/notes/implemented/process/2026-06-17-ts-build-config.md
-2026-06-17-ts-build-config.md: f25731921aaa6da7a4c9760244f73dc0670dc1d3
-2026-06-17-ts-build-config.zh.md: 80b051cd5fb76672d4c056d1b6321029897225e8
+2026-06-17-ts-build-config.md: a44e86844113250c8b99575102d7ea2e611e97ed
+2026-06-17-ts-build-config.zh.md: 4e98717fd843c93696402b71e8a41163c70e7283
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.md b/.agents/notes/implemented/process/2026-06-17-ts-build-config.md
index f25731921a..a44e868441 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.md
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.md
@@ -13,13 +13,13 @@ The current TypeScript build and typecheck setup had these issues:
 - `build` used `tsc` to transform `.ts` to `.d.ts` files for packages under `packages/<group>/<pkg>` and `vendor/*`, and then used `tsdown` to transform `.ts` to bundled `.js` files. This made two tools do TypeScript transform.
 - `typecheck` tended to validate packages, vendor source, examples, tests, and scripts through one root typecheck config.
 
-The goal is to make build and typecheck use matching tsconfig boundaries and TypeScript resolution/transform behavior. Build should generate `.js`, `.d.ts`, `.js.map`, and `.d.ts.map` through one compiler and config, so publish output and type validation stay consistent.
+Build and typecheck use matching tsconfig boundaries and TypeScript resolution/transform behavior. Build generates `.js`, `.d.ts`, `.js.map`, and `.d.ts.map` through one compiler and config, so publish output and type validation stay consistent.
 
-Validation found several concrete technical issues and possible routes:
+Concrete constraints:
 
 - `tsdown` uses `oxc` to transform TypeScript, which is not the same behavior as `tsc`.
     - Bundled `.d.ts` emitted by `tsdown` conflicts with Cordis' internal relative module augmentation shape.
-    - The tsc output is affected by `allowImportingTsExtensions`, so we need to ensure that generated `.js` files do not import `.ts` files and generated `.d.ts` files keep explicit relative specifiers that NodeNext/Node16 accepts. Therefore, in-package relative imports use explicit `.ts` specifiers in TypeScript source and `rewriteRelativeImportExtensions` rewrites those specifiers to `.js` in emitted JS.
+    - The tsc output is affected by `allowImportingTsExtensions`: generated `.js` files must not import `.ts` files, and generated `.d.ts` files must keep explicit relative specifiers that NodeNext/Node16 accepts. Therefore, in-package relative imports use explicit `.ts` specifiers in TypeScript source and `rewriteRelativeImportExtensions` rewrites those specifiers to `.js` in emitted JS.
     - Bundled `.js` emitted by `tsdown` is not the same behavior as per-file `.js` emitted by `tsc -b`, such as decorator transform behavior.
 - `vendor/*/src`, examples, tests, and scripts cannot all be plain-included in one root strict program.
     - Directly typechecking `vendor/*/src` under the root strict config triggers many type errors outside this project's ownership.
diff --git a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
index 80b051cd5f..4e98717fd8 100644
--- a/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
+++ b/.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md
@@ -13,13 +13,13 @@ Status: implemented
 - `build` 使用 `tsc` 将 `packages/<group>/<pkg>` 和 `vendor/*` 下的 `.ts` 转换为 `.d.ts` 文件，然后使用 `tsdown` 将 `.ts` 转换为打包后的 `.js` 文件。这导致两个工具各自执行 TypeScript 转换。
 - `typecheck` 倾向于通过一个根目录的类型检查配置来校验包（package）、vendor 源码、示例、测试和脚本。
 
-目标是让构建与类型检查使用一致的 tsconfig 边界和 TypeScript 解析/转换行为。构建应通过单一编译器和配置生成 `.js`、`.d.ts`、`.js.map` 和 `.d.ts.map`，使发布产物与类型校验保持一致。
+构建与类型检查使用一致的 tsconfig 边界和 TypeScript 解析/转换行为。构建通过单一编译器和配置生成 `.js`、`.d.ts`、`.js.map` 和 `.d.ts.map`，使发布产物与类型校验保持一致。
 
-验证过程中发现了若干具体的技术问题和可能的路径：
+具体约束：
 
 - `tsdown` 使用 `oxc` 进行 TypeScript 转换，其行为与 `tsc` 不同。
     - `tsdown` 输出的打包 `.d.ts` 与 Cordis 内部的相对模块增强（module augmentation）结构冲突。
-    - tsc 的输出受 `allowImportingTsExtensions` 影响，因此需要确保生成的 `.js` 文件不会导入 `.ts` 文件，且生成的 `.d.ts` 文件保留 NodeNext/Node16 接受的显式相对说明符。为此，包内相对导入在 TypeScript 源码中使用显式 `.ts` 说明符，由 `rewriteRelativeImportExtensions` 在输出的 JS 中将其重写为 `.js`。
+    - tsc 的输出受 `allowImportingTsExtensions` 影响：生成的 `.js` 文件不得导入 `.ts` 文件，且生成的 `.d.ts` 文件必须保留 NodeNext/Node16 接受的显式相对说明符。为此，包内相对导入在 TypeScript 源码中使用显式 `.ts` 说明符，由 `rewriteRelativeImportExtensions` 在输出的 JS 中将其重写为 `.js`。
     - `tsdown` 输出的打包 `.js` 与 `tsc -b` 逐文件输出的 `.js` 行为不同，例如装饰器转换行为。
 - `vendor/*/src`、示例、测试和脚本无法全部以 plain-include 方式纳入一个根目录的严格程序。
     - 在根目录严格配置下直接对 `vendor/*/src` 做类型检查，会触发大量不属于本项目所有权范围的类型错误。
diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml
index e5112c08e1..af8d4d77db 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.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 .agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
-2026-06-18-markdown-cross-link-lint.md: 21c6884d3fd891794a11125a9aa51ac2bcb29059
-2026-06-18-markdown-cross-link-lint.zh.md: 444cf6eb97d95049d4e6b7bb5f44138051f6577a
+2026-06-18-markdown-cross-link-lint.md: 37e0a41c08e068d6b3128300f078c8e417f1f337
+2026-06-18-markdown-cross-link-lint.zh.md: 457cc8b71ac91e5b5b9ae7ad8fb3b99dfd8ce0c7
diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
index 21c6884d3f..37e0a41c08 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md
@@ -28,6 +28,6 @@ The gate now also checks `#fragment` anchors on Markdown targets — same-file a
 
 ## Consequences
 
-- Renames and moves that orphan a cross-link fail `doc-sync` and CI instead of waiting for a reader to click a dead link. This made the Agent Note reorganization that introduced the gate self-verifying: the same PR that rewrote forty links also added the check that proves none dangle.
+- Renames and moves that orphan a cross-link fail `doc-sync` and CI instead of waiting for a reader to click a dead link. This made the Agent Note reorganization that introduced the gate self-verifying: the check proves none of its own rewritten links dangle.
 - One more fast tsx script in the `doc-sync` chain; no new dependency (the mdast/GFM stack is already in devDependencies for `verify-md-wrap`).
 - The convention this enforces — cross-reference docs by machine-checkable relative link, never by bare prose or a number — is documented in [docs/AGENTS.md](../../../../docs/AGENTS.md) so authors know the gate exists and why.
diff --git a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
index 444cf6eb97..457cc8b71a 100644
--- a/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
+++ b/.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.zh.md
@@ -28,6 +28,6 @@ Status: implemented
 
 ## 后果
 
-- 造成交叉链接失效的重命名与移动会直接使 `doc-sync` 和 CI 失败，而不是等读者点击死链才暴露。由此，引入该门禁的 Agent Note 重组具备自校验能力：同一个 PR（Pull Request）在改写 40 条链接的同时，也添加了证明这些链接均未悬空的检查。
+- 造成交叉链接失效的重命名与移动会直接使 `doc-sync` 和 CI 失败，而不是等读者点击死链才暴露。由此，引入该门禁的 Agent Note 重组具备自校验能力：该检查证明其自身改写的链接均未悬空。
 - `doc-sync` 链中多了一个快速 tsx 脚本；无新增依赖（mdast/GFM 技术栈已作为 `verify-md-wrap` 的 devDependencies 存在）。
 - 该门禁强制执行的约定是：文档交叉引用必须使用可机械检查的相对链接，绝不能只写纯文本或编号。[docs/AGENTS.md](../../../../docs/AGENTS.md)记录了这项约定，使作者了解该门禁及其理由。
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
index 20bd2a96db..93d6ea6c49 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
-2026-06-20-core-data-structures-catalog.md: 2f2e1fe43e29c972577f6b31fcd2f8249229779f
-2026-06-20-core-data-structures-catalog.zh.md: e2653a8248f6be24699dc55196e64231280cb7f9
+2026-06-20-core-data-structures-catalog.md: 957d3a31cf690b3f0fb821b69bbc3d6d5005b1d7
+2026-06-20-core-data-structures-catalog.zh.md: aec1489695f8400768c958426a9d6a8d4061db0c
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
index 2f2e1fe43e..957d3a31cf 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -18,7 +18,7 @@ A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type
 
 > **Superseded as the page-scoping rule** by [package-anchored subsystem pages](2026-08-03-package-anchored-subsystem-pages.md): each page now anchors to the package group that declares its vocabulary. The `ts type-equiv` mechanism below remains current.
 
-The scoping line was not picked top-down; it was discovered by testing candidate definitions against concrete borderline types until one rule survived every case. The decisive test was `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own subsystem page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
+The decisive test for the scoping line is `BashExecRequest`/`BashExecSpec`/`BashRunResult`: bash is a capability *seam*, not part of the agent-loop spine, so if those are "core" then "core" means *all cross-package vocabulary* and the catalog is a flat dump; if they are not, "core" means *the central spine* and bash vocabulary belongs on its own subsystem page. The latter won, which set the whole structure: a **tiered folder**, not a flat document.
 
 The rule that settled the remaining cases: ***the type you write, hold, or receive is core; the machinery that types it, renders it, or persists it is a subsystem-page detail.*** Worked through:
 
@@ -50,8 +50,6 @@ The durability requirement was specific: the doc shows the **literal** current t
 
 ## Verification lesson
 
-The spine-vs-subsystem rule was tested against `BashExecRequest`, tool schemas and definitions, the schema DSL, presentation types, and the session/persistence split before adoption.
-
 `verify-type-equiv` must scan the complete Markdown scope, not only manifest-named documents. Otherwise an unmanifested `type-equiv` block escapes the claimed one-to-one check. The gate therefore reports such blocks as orphans. This Agent Note records that fail-closed scan rule together with the spine-vs-subsystem and verbatim-match decisions; the generated Cordis catalog has the symmetric design record in [its archived Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md).
 
 ## Consequences
diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
index e2653a8248..aec1489695 100644
--- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
+++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 > **作为页面范围界定规则已被取代**，见[按包锚定的子系统页面](2026-08-03-package-anchored-subsystem-pages.md)：每页现在锚定到声明其词汇的包分组。下文的 `ts type-equiv` 机制仍然有效。
 
-范围界定并非自上而下拍定，而是将候选定义逐一对照具体的边界类型反复测试，直到一条规则在所有案例中都成立。决定性的测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入其自身的子系统页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
+范围界定的决定性测试是 `BashExecRequest`/`BashExecSpec`/`BashRunResult`：bash 是一个能力 *seam*，不属于 agent loop（智能体循环）主干；如果这些算「核心」，那么「核心」就意味着*所有跨包词汇*，目录沦为平铺罗列；如果不算，「核心」就意味着*中央主干*，bash 词汇归入其自身的子系统页面。后者胜出，由此确定了整体结构：一个**分层文件夹**，而非一份平铺文档。
 
 确定其余案例的规则是：***你编写、持有或接收的类型是核心；为其提供类型推导、渲染或持久化的机制是子系统页面细节。*** 逐一验证如下：
 
@@ -50,8 +50,6 @@ Status: implemented
 
 ## 验证教训
 
-主干与子系统规则在采纳前经过了 `BashExecRequest`、工具 schema 与定义、schema DSL、展示类型以及会话/持久化拆分的逐一测试。
-
 `verify-type-equiv` 必须扫描完整的 Markdown 范围，而不仅是 manifest 点名的文档。否则，未列入清单的 `type-equiv` 块就会逃过所宣称的一一检查。因此，门禁会将此类块报告为未列入清单的块。本 Agent Note 将这条默认拒绝放行的扫描规则，连同主干与子系统的分界决策及逐字匹配决策一并记录；生成的 Cordis 目录在[其已归档的 Agent Note](../../archived/process/2026-06-20-generated-cordis-catalog.md) 中有对称的设计记录。
 
 ## 后果
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 4fd3657a7d..a869a98b51 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.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 .agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
-2026-07-02-bilingual-docs-and-pairing-gate.md: 930efd3a2df8ad99b3c209c6084436ab6b27dc0a
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 2e288a29e9484683b9961d1e420a6e92ca05e5fe
+2026-07-02-bilingual-docs-and-pairing-gate.md: 9e6611aa8391e1478603bedb7d2b96fdd9a8bad2
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 654d265f3e8b396e23a49fd53e522826a7adb2ff
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
index 930efd3a2d..9e6611aa83 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
@@ -23,7 +23,7 @@ The verification contract covers each boundary independently. `verify-translatio
 
 ## Alternatives considered
 
-- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.
+- **English as the canonical source with a fingerprint inside the translation** — `.zh.md` files would carry an HTML comment recording the English source's blob hash, and translation would flow EN → ZH only. Rejected: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.
 - **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.
 - **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.
 - **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.
diff --git a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index 2e288a29e9..654d265f3e 100644
--- a/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/.agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -23,7 +23,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。
+- **英文为正典源、指纹放在译文内**：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。否决：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。
 - **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。
 - **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。
 - **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
index 7005f08ce0..095b577bba 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.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 .agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 006360cedfd4d1e2c2b67ede98062a375e316f47
-2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: 2258a1fe5f91b27b8a3b636c7f3ad26f502a98df
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md: 79a7ff1c573019a3a1877eb49177d3410aea5ed7
+2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md: 76d755656ecfdd47bac2191efac4ce5bba53f4fb
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
index 006360cedf..79a7ff1c57 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.md
@@ -21,7 +21,7 @@ Outside `landlock-run.yml`, each workflow that installed pnpm hand-provisioned i
 - **Keep the hand-rolled steps.** They worked, but they were drifting copies of setup boilerplate, and the corepack dependency was a known future break.
 - **Convert the enterprise jobs' caching to `cache: pnpm`.** Rejected: the restore-only asymmetry is a documented latency decision in `ci.yml`'s comments; erasing it to unify tooling inverts the priority.
 - **Convert serial-linux's store cache.** Rejected during implementation: the original proposal counted serial-linux among the symmetric setups, but its cache step is the producer half of the enterprise jobs' restore-only pairing — moving it to `setup-node`'s key format is the enterprise conversion by another route.
-- **Stop at the cache-bearing workflows and leave the other `corepack enable` sites.** Rejected on review follow-up: provisioning and caching are separable concerns, and leaving corepack in the cache-less jobs kept the future break and two provisioning idioms for no benefit.
+- **Stop at the cache-bearing workflows and leave the other `corepack enable` sites.** Rejected: provisioning and caching are separable concerns, and leaving corepack in the cache-less jobs kept the future break and two provisioning idioms for no benefit.
 - **Rely on the runner image's Yarn.** Rejected: the hosted image exposes Yarn 1.22 after Corepack is removed, while the generated-project e2e requires Yarn 2 or newer. A locked root dev dependency makes that coverage independent of runner image contents.
 - **A composite action wrapping action-setup + setup-node.** Rejected for now: the remaining per-job variation (node-version matrices, per-platform conditional caching, the restore-only pairing) is deliberate policy, not boilerplate — a wrapper would grow mirroring inputs or flatten a real asymmetry, and the two-line pair is already near the floor.
 
diff --git a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
index 2258a1fe5f..76d755656e 100644
--- a/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-pnpm-action-setup-for-symmetric-ci-caching.zh.md
@@ -21,7 +21,7 @@ Status: implemented
 - **保留手写步骤。** 它们能用，但那是会各自漂移的设置样板副本，而且对 corepack 的依赖是已知的未来失效点。
 - **把企业作业的缓存也转换成 `cache: pnpm`。** 否决：只恢复不上传的不对称是 `ci.yml` 注释中有记录的延迟决策；为统一工具而抹掉它，属于颠倒优先级。
 - **转换 serial-linux 的 store 缓存。** 实现期间否决：原提案曾把 serial-linux 计入对称设置，但其缓存步骤是企业作业只恢复不上传配对中的生产者一端——把它改成 `setup-node` 的键格式，等于换条路径做了企业作业的转换。
-- **只转换带缓存的工作流，留下其余出现 `corepack enable` 的位置。** 评审跟进时否决：提供 pnpm 与缓存是可分离的关注点，在无缓存作业里留下 corepack 只会保留未来失效点和两套并存的提供方式，毫无收益。
+- **只转换带缓存的工作流，留下其余出现 `corepack enable` 的位置。** 否决：提供 pnpm 与缓存是可分离的关注点，在无缓存作业里留下 corepack 只会保留未来失效点和两套并存的提供方式，毫无收益。
 - **依赖 runner 镜像自带的 Yarn。** 否决：Corepack 移除后，托管镜像提供的是 Yarn 1.22，而 generated-project e2e 要求 Yarn 2 或更高版本。锁定版本的根开发依赖让该项覆盖率不再受 runner 镜像内容影响。
 - **用一个组合 action 包装 action-setup + setup-node。** 暂不采纳：剩余的按作业差异（node 版本矩阵、按平台的条件缓存、只恢复不上传配对）是刻意的政策而非样板——包装层要么不得不增加与这些差异一一对应的输入，要么抹平一处真实的不对称，而两行的组合已接近下限。
 
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
index cd55f494d7..2575f2f4b3 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.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 .agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
-2026-07-27-wine-windows-gates-experiment.md: 1b01fe00dc1588482442a3cedc35eefa7fdb0975
-2026-07-27-wine-windows-gates-experiment.zh.md: 3145a4aa6a06cacbab96dd37714617aeecdfdde0
+2026-07-27-wine-windows-gates-experiment.md: c2b5419c106e232520b9ad21339b0758da1b6694
+2026-07-27-wine-windows-gates-experiment.zh.md: 7ad19e49a43c07369eba6511fb7a46f5b3291df8
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
index 1b01fe00dc..c2b5419c10 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-27-wine-windows-gates-experiment.zh.md)
 
 The pull-request Windows lane exists to prove the two blocking win32 surfaces — the workspace build and the production site — and it ran on hosted `windows-2025`, the slowest job in the required matrix: 7–9 minutes against 1.5–2.5 for the Linux jobs, so the Windows VM's boot, setup, and filesystem costs dominated every pull request's critical path.
 
-The question the experiment answered: can a plain Linux runner produce an equivalent win32 signal for the blocking surfaces at Linux wall clock, so no Windows VM sits on the pull-request path at all?
+The experiment tested whether a plain Linux runner can produce an equivalent win32 signal for the blocking surfaces at Linux wall clock, so no Windows VM sits on the pull-request path at all.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
index 3145a4aa6a..7ad19e49a4 100644
--- a/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
+++ b/.agents/notes/implemented/process/2026-07-27-wine-windows-gates-experiment.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 Pull request 的 Windows 通道旨在验证两个阻断性 win32 表面，即 workspace 构建与生产站点。该通道此前运行在托管 `windows-2025` 上，是必需矩阵中最慢的作业：耗时 7–9 分钟，而 Linux 作业耗时 1.5–2.5 分钟，因此 Windows VM 的启动、准备与文件系统开销主导了每个 pull request 的关键路径。
 
-实验回答的问题是：一台普通 Linux runner 能否以 Linux 作业的墙钟时间为这些阻断表面产出等效的 win32 信号，让 pull request 路径上完全没有 Windows VM？
+实验测试了一台普通 Linux runner 能否以 Linux 作业的墙钟时间为这些阻断表面产出等效的 win32 信号，让 pull request 路径上完全没有 Windows VM。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
index 004c168fe7..b60f3ae3ed 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.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 .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
-2026-07-30-generated-third-party-notices.md: f2591c8d0c7d4b83ecc96bf237ded667e322d55c
-2026-07-30-generated-third-party-notices.zh.md: 97b62223c0f1e5d179e58f27a01251d8af43357b
+2026-07-30-generated-third-party-notices.md: 58e3fd5007a16d6391956f423d1ec91e851df295
+2026-07-30-generated-third-party-notices.zh.md: 834ec4ebc349bdee37b0873109de566223bb7d48
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
index f2591c8d0c..58e3fd5007 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
@@ -16,7 +16,7 @@ A hand-written inventory answers none of those durably. Roughly a hundred rows o
 
 **Freshness is maintained, not merely enforced.** A pre-commit job regenerates the file and stages it whenever a generator input is staged — any manifest, a workspace declaration, the root lock file, `vendor/README.md`, a `pyproject.toml`, the generator itself, or the script holding the build-time pin — so an unrelated dependency edit never has to come back and rerun a generator. The committed bytes are then asserted inside [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts), which the test lane already runs — the check adds no gate process, no scheduler slot, and no separate CI step. `pnpm run verify-third-party-notices` remains available for a standalone check.
 
-One trigger gap is accepted rather than worked around: lefthook inspects only files present on disk, so **deleting** a manifest runs no job, and removing a package reaches the assertion in the test lane instead. Reconstructing the staged file list to include deletions was tried and does not work — lefthook filters the list against the working tree either way. The assertion is the backstop for exactly this case.
+One trigger gap is accepted rather than worked around: lefthook inspects only files present on disk, so **deleting** a manifest runs no job, and removing a package reaches the assertion in the test lane instead. Reconstructing the staged file list to include deletions does not work — lefthook filters the list against the working tree either way. The assertion is the backstop for exactly this case.
 
 The file discloses **direct** dependencies by default. The complete npm closure with pinned versions already lives in `pnpm-lock.yaml` (`pnpm licenses list` renders it) and the Python closure in `python/sdk/uv.lock`; re-materializing either as prose would be a second, worse copy. The one explicit transitive disclosure is the official Claude platform payload set declared by `@anthropic-ai/claude-agent-sdk` through `optionalDependencies`, because those packages carry the distributed Claude Code executable rather than ordinary library implementation detail.
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
index 97b62223c0..834ec4ebc3 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 **新鲜度靠维护而非拦截。** 只要暂存了生成器的任一输入——任何 manifest、工作区声明、根锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成该文件并将其暂存，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。
 
-有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest 不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
+有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest 不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
 
 文件默认只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。唯一明确披露的传递依赖，是 `@anthropic-ai/claude-agent-sdk` 通过 `optionalDependencies` 声明的官方 Claude 平台载荷集合，因为这些包承载随产品分发的 Claude Code 可执行文件，而非普通的库实现细节。
 
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
index a2e19d3493..72574c7cf5 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.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 .agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
-2026-07-31-installer-adopts-existing-checkout.md: 3a213a6232e57f305910240505983421dcd288ad
-2026-07-31-installer-adopts-existing-checkout.zh.md: e19baa0b1ee8ce71c1b8f3ee520322fb6557a720
+2026-07-31-installer-adopts-existing-checkout.md: 531b780974e1490b27d8b96734ccfadae66c2fc2
+2026-07-31-installer-adopts-existing-checkout.zh.md: 405b58d8d53b3f0895cc7746c957582455667cda
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
index 3a213a6232..531b780974 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.md
@@ -20,7 +20,7 @@ The installer records nothing about where that repository lives. A container who
 
 Adoption branches from `HEAD`, so committed work is what runs and uncommitted changes stay in the checkout. This is not prompted or warned about: the installer builds the layout and gets out of the way. Setting `DSH_SOURCE` to a different directory remains the one documented way to opt back into cloning a separate tree.
 
-Every path comparison runs on physical paths through a `resolve_dir` helper, and every compared value is resolved at assignment rather than at the comparison. Git always reports resolved paths, so comparing one against an unresolved path disagrees whenever a symlink sits anywhere above the checkout — a symlinked home directory is enough, and macOS reaches every `mktemp` path that way through `/var` -> `private/var`. The mismatch misclassified an existing managed install as a foreign clone and would have built a second container beside the real one. The same defect recurred twice more during review, both times as one side of a comparison left unresolved: a curl install's `REPO_ROOT`, and the container path it was compared against. `resolve_dir` therefore echoes a missing path back rather than failing, so a not-yet-created container needs no per-call fallback and no site can compare against an empty path by forgetting one; callers that need "does not exist" test the directory explicitly. `git rev-parse --path-format=absolute` would do the same job but requires git 2.31+.
+Every path comparison runs on physical paths through a `resolve_dir` helper, and every compared value is resolved at assignment rather than at the comparison. Git always reports resolved paths, so comparing one against an unresolved path disagrees whenever a symlink sits anywhere above the checkout — a symlinked home directory is enough, and macOS reaches every `mktemp` path that way through `/var` -> `private/var`. The mismatch misclassified an existing managed install as a foreign clone and would have built a second container beside the real one. The same defect class recurs whenever one side of a comparison is left unresolved — as it did with a curl install's `REPO_ROOT` and with the container path it was compared against. `resolve_dir` therefore echoes a missing path back rather than failing, so a not-yet-created container needs no per-call fallback and no site can compare against an empty path by forgetting one; callers that need "does not exist" test the directory explicitly. `git rev-parse --path-format=absolute` would do the same job but requires git 2.31+.
 
 Before `current` is repointed, the installer rejects a staging path that resolves to the repository itself, enforcing the upgrade contract that the launcher never resolves to the master clone.
 
@@ -48,4 +48,4 @@ A container adopting an outside clone is also no longer self-contained: deleting
 
 `scripts/install.sh` now has a real-shell PTY regression suite in `apps/cli/tests/install-script.spec.ts`, covering adoption and curl-style paths with stubbed dependencies. Curl-style installs default to the public `deepseek-ai/deepseek-harness-sdk` source, while replacing the installer with pnpm/npx remains separate work.
 
-Verification was manual, through a throwaway harness driving the real script with a stubbed `pnpm`: adopting a standalone clone; adopting from a linked worktree into its existing container; an explicit `DSH_SOURCE` still opting back into cloning; a dirty tree adopting silently with no prompt or warning while its uncommitted file stays behind; a non-git checkout failing with guidance; and a `curl`-style clone install asserting the built layout, which is the regression that caught the unresolved-`REPO_ROOT` defect. The interactive path was exercised under tmux from a dirty checkout, confirming the run reaches the launcher with no adoption prompt and ends with `dsh` running from the new staging worktree while the original checkout keeps its branch and its uncommitted file.
+Verification was manual, through a throwaway harness driving the real script with a stubbed `pnpm`: adopting a standalone clone; adopting from a linked worktree into its existing container; an explicit `DSH_SOURCE` still opting back into cloning; a dirty tree adopting silently with no prompt or warning while its uncommitted file stays behind; a non-git checkout failing with guidance; and a `curl`-style clone install asserting the built layout, the check that catches an unresolved `REPO_ROOT`. The interactive path was exercised under tmux from a dirty checkout, confirming the run reaches the launcher with no adoption prompt and ends with `dsh` running from the new staging worktree while the original checkout keeps its branch and its uncommitted file.
diff --git a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
index e19baa0b1e..405b58d8d5 100644
--- a/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
+++ b/.agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md
@@ -20,7 +20,7 @@ Status: implemented
 
 接管以`HEAD`为分支起点，因此运行的是已提交的内容，未提交的更改仍留在检出中。这一点既不提示也不警告：安装器构建好布局后便不再打扰。把`DSH_SOURCE`设为其他目录，仍是唯一有文档记载的、回到克隆另一棵树的方式。
 
-所有路径比较都通过`resolve_dir`辅助函数在物理路径上进行，且每个参与比较的值都在赋值时解析，而非在比较时解析。git 报告的始终是已解析的路径，因此只要检出之上任意一层存在符号链接，拿它与未解析的路径相比较就会不相等——家目录本身是符号链接即已足够，而 macOS 通过`/var` -> `private/var`使每个`mktemp`路径都如此。这种不匹配会把已有的受管安装误判为外来克隆，并在真正的容器旁再建一个容器。同一缺陷在评审过程中又出现了两次，两次都是比较的一侧未经解析：一次是 curl 安装的`REPO_ROOT`，一次是与之比较的容器路径。因此`resolve_dir`在路径不存在时原样回显该路径而非失败，这样尚未创建的容器无需在每个调用点单独兜底，也就没有调用点会因遗漏兜底而与空路径比较；需要判断"不存在"的调用方则显式检测该目录。`git rev-parse --path-format=absolute`能完成同样的工作，但要求 git 2.31 及以上版本。
+所有路径比较都通过`resolve_dir`辅助函数在物理路径上进行，且每个参与比较的值都在赋值时解析，而非在比较时解析。git 报告的始终是已解析的路径，因此只要检出之上任意一层存在符号链接，拿它与未解析的路径相比较就会不相等——家目录本身是符号链接即已足够，而 macOS 通过`/var` -> `private/var`使每个`mktemp`路径都如此。这种不匹配会把已有的受管安装误判为外来克隆，并在真正的容器旁再建一个容器。只要比较的一侧未经解析，同类缺陷就会重现——curl 安装的`REPO_ROOT`以及与之比较的容器路径都曾如此。因此`resolve_dir`在路径不存在时原样回显该路径而非失败，这样尚未创建的容器无需在每个调用点单独兜底，也就没有调用点会因遗漏兜底而与空路径比较；需要判断"不存在"的调用方则显式检测该目录。`git rev-parse --path-format=absolute`能完成同样的工作，但要求 git 2.31 及以上版本。
 
 在重指`current`之前，安装器会拒绝解析结果等于仓库自身的 staging 路径，以此落实"启动器绝不解析到 master 克隆"这一升级约定。
 
@@ -48,4 +48,4 @@ Status: implemented
 
 `scripts/install.sh` 现有一套位于 `apps/cli/tests/install-script.spec.ts` 的真实 shell PTY 回归测试，使用 stub 依赖覆盖接管路径和 curl 风格路径。curl 风格安装默认使用公开的 `deepseek-ai/deepseek-harness-sdk` 源，而以 pnpm/npx 替换安装器仍是另一项工作。
 
-验证是手工完成的，通过一个一次性测试装置以打桩的`pnpm`驱动真实脚本：接管独立克隆；从 linked worktree 接管进其已有容器；显式`DSH_SOURCE`仍回到克隆路径；工作树不干净时静默接管、既不提示也不警告，且其未提交文件留在原处；非 git 检出失败并给出指引；以及`curl`式克隆安装断言所构建的布局——正是这项回归测试捕获了`REPO_ROOT`未解析的缺陷。交互路径在 tmux 下从一个不干净的检出走通，确认整个过程不出现接管提示即可到达启动器，最终`dsh`从新的 staging worktree 运行，而原检出保持其分支不变、未提交文件仍在。
+验证是手工完成的，通过一个一次性测试装置以打桩的`pnpm`驱动真实脚本：接管独立克隆；从 linked worktree 接管进其已有容器；显式`DSH_SOURCE`仍回到克隆路径；工作树不干净时静默接管、既不提示也不警告，且其未提交文件留在原处；非 git 检出失败并给出指引；以及`curl`式克隆安装断言所构建的布局——该检查能捕获未解析的`REPO_ROOT`。交互路径在 tmux 下从一个不干净的检出走通，确认整个过程不出现接管提示即可到达启动器，最终`dsh`从新的 staging worktree 运行，而原检出保持其分支不变、未提交文件仍在。
diff --git a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml
index f742579d36..c039f8c1b1 100644
--- a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.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 .agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md
-2026-08-06-coverage-uncovered-locations.md: 27c466e7ae505a2d318f8b21d442c31619610f59
-2026-08-06-coverage-uncovered-locations.zh.md: 482b17227c4198ee27411da16b047288b331af9c
+2026-08-06-coverage-uncovered-locations.md: 7a4bd7317bf66d090d73a6a05f361ccc1582f1c4
+2026-08-06-coverage-uncovered-locations.zh.md: 7d820b3dcd46c844dfccc61dda283c754ed17f13
diff --git a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md
index 27c466e7ae..7a4bd7317b 100644
--- a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md
+++ b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.md
@@ -33,7 +33,7 @@ CJS is a forced shape, and a justified exception to the ESM-everywhere disciplin
 
 ## Verification
 
-Local matrix: with a deliberately induced failure, all three record kinds appear and their locations match the planted gaps; a mixed run emits records only for the failing files (files at 100% within the same run stay silent); an all-green run produces zero output and exit code 0. CI evidence: after temporarily planting one unreachable statement/branch/function in `clampTimeout`, the coverage lane — under the isolated condition of all tests passing (632 files / 10326 cases) with only the threshold failing — printed the 4 records above the ERROR lines (evidence links in the PR #1716 description); the demonstration commit was removed from the branch before merge.
+Local matrix: with a deliberately induced failure, all three record kinds appear and their locations match the planted gaps; a mixed run emits records only for the failing files (files at 100% within the same run stay silent); an all-green run produces zero output and exit code 0. CI evidence: after temporarily planting one unreachable statement/branch/function in `clampTimeout`, the coverage lane — under the isolated condition of all tests passing (632 files / 10326 cases) with only the threshold failing — printed the 4 records above the ERROR lines; the planted failure is not in the committed tree.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
index 482b17227c..7d820b3dcd 100644
--- a/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-06-coverage-uncovered-locations.zh.md
@@ -33,7 +33,7 @@ CJS 是被迫的形态，也是 ESM-everywhere 纪律的一个有据例外：ist
 
 ## 验证
 
-本地矩阵：故意制造未达标时三类记录齐全、位置与埋点一致；混合运行只输出未达标文件（同跑内 100% 的文件静默）；全绿跑零输出、退出码 0。CI 实证：临时在 `clampTimeout` 埋入一处不可达语句/分支/函数后，coverage lane 在全部测试通过（632 文件 / 10326 用例）、仅 threshold 失败的隔离条件下，把 4 条记录打印在 ERROR 行上方（证据链接见 PR #1716 描述）；演示提交在合并前已从分支撤除。
+本地矩阵：故意制造未达标时三类记录齐全、位置与埋点一致；混合运行只输出未达标文件（同跑内 100% 的文件静默）；全绿跑零输出、退出码 0。CI 实证：临时在 `clampTimeout` 埋入一处不可达语句/分支/函数后，coverage lane 在全部测试通过（632 文件 / 10326 用例）、仅 threshold 失败的隔离条件下，把 4 条记录打印在 ERROR 行上方；埋入的失败并不在已提交的代码树中。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
new file mode 100644
index 0000000000..079b448027
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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/process/2026-08-09-committed-artifact-citations.md
+2026-08-09-committed-artifact-citations.md: a34a779977a05b66b1587049ef4a38f0c1cfa0cb
+2026-08-09-committed-artifact-citations.zh.md: 6eb1810dddfcb38095270d4cdcb00eccef167183
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
new file mode 100644
index 0000000000..a34a779977
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -0,0 +1,37 @@
+# Agent Note: Cite committed artifacts, never design-session ordinals
+
+Status: implemented
+
+English | [中文](2026-08-09-committed-artifact-citations.zh.md)
+
+## Problem
+
+Large design and review sessions leave working shorthand — decision ordinals, audit item codes, plan section numbers, task and stack ordinals, reviewer rulings — that reads naturally while the session transcript is open and resolves to nothing after it closes. A repo-wide audit found the pattern concentrated in `packages/client`: bare `(decision 12/16/19/20/21)` citations of which only decision 21 had a committed owner, `(audit C2/S1/S3/S7)` codes with no audit document anywhere, `design §4.7` / `web2 §0` / `plan §1.4` references to uncommitted drafts, plan-phase labels (`T2/T5/T9`, `P-I`, `W5`), stack positions ("a later PR in this stack") in durable JSDoc, and "ruling" / "design ledger" vocabulary. The same families appeared in tests, CSS comments, generator templates, CI comments, and Agent Notes ("this PR/branch/review round" vantage, review-choreography attributions, stale "deferred to a later PR" claims whose targets had since shipped). The [documentation standard](../../../../docs/AGENTS.md) already banned the change-history half (previously/now, PR and commit references) but stated no counterpart rule for citations, so unresolvable ordinals kept landing.
+
+## Decision
+
+Durable prose — comments, JSDoc, docs, notes, test comments and titles — cites only committed artifacts, resolvable in-repo without grep archaeology:
+
+- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned per the documentation standard; issues are durable and citable.
+- A design-session ordinal with a committed owner is replaced by the owner's name — decision 21 lives in the [web input-machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) as the plain-text-reference decision. An ordinal without an owner is deleted and its factual clause restated to stand alone.
+- Fixed regressions are pinned as present-tense counterfactuals ("without X, Y happens"; "a naive X would…"), never as repo history ("used to Y").
+- Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
+- Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice.
+
+One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (`scripts/gen-doc-graphs.ts`, `scripts/gen-tool-catalog.ts`, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records.
+
+## Alternatives considered
+
+- **Commit the design ledgers and audit documents so the ordinals resolve.** Rejected: session transcripts are working artifacts, not maintained references; committing them would create a parallel, ungated decision corpus beside Agent Notes, and their internal numbering would still drift.
+- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d` and `\(audit [A-Z]\d`) is the candidate if the pattern recurs.
+- **Delete the rationale that cited dead artifacts.** Rejected: the factual clauses were preserved or restated; only citations, review choreography, and derivation transcripts were removed, per the prose standard's complete-proposition rule.
+
+## Verification
+
+The audit's grep batteries (English and Chinese, comments and prose, `--hidden` for `.agents/`) return no design-ordinal citations outside recorded fixtures and archived notes; `verify-type-equiv`, the `gen-*` freshness checks, and `verify-translation-pairing` pin the regenerated and re-recorded surfaces. Coverage gap: no gate rejects a new ordinal citation — review owns the rule.
+
+## Consequences
+
+- A comment's citations resolve by path or name; readers never reconstruct a closed session to follow one.
+- Design sessions must land their decisions in Agent Notes before durable prose can cite them; ordinal shorthand stays inside the session.
+- Citations get longer (a note path instead of "(decision 21)") in exchange for grep-free resolution.
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
new file mode 100644
index 0000000000..6eb1810ddd
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: 引用已提交的产物，绝不引用设计会话序号
+
+Status: implemented
+
+[English](2026-08-09-committed-artifact-citations.md) | 中文
+
+## 问题
+
+大型设计与评审会话会留下工作速记：决策序号、审计条目代号、计划章节编号、任务与栈序号、评审人裁定。这些速记在会话 transcript（文本记录）还开着时读起来顺理成章，一旦关闭就什么也解析不到。一次全仓库审计发现该模式集中在 `packages/client`：裸写的 `(decision 12/16/19/20/21)` 引用中只有决策 21 有已提交的归属文档；`(audit C2/S1/S3/S7)` 代号在任何地方都没有对应的审计文档；`design §4.7`／`web2 §0`／`plan §1.4` 指向未提交的草稿；计划阶段标签（`T2/T5/T9`、`P-I`、`W5`）；持久 JSDoc 里的栈内位置（"a later PR in this stack"）；以及「ruling」（裁定）、「design ledger」（设计台账）一类词汇。同样的几类模式也出现在测试、CSS 注释、生成器模板、CI 注释与 Agent Note 中（「本 PR／本分支／本评审轮」视角、评审编排式的归因、目标其后已经交付却仍写着「推迟到后续 PR」的陈旧说法）。[文档标准](../../../../docs/AGENTS.md)早已禁止了变更历史这一半（previously/now、PR（Pull Request）与 commit 引用），却没有为引用写下对应的规则，于是无法解析的序号不断落进仓库。
+
+## 决策
+
+持久行文（注释、JSDoc、文档、Agent Note、测试注释与测试标题）只引用已提交的产物，无需 grep 考古即可在仓库内解析：
+
+- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准仍在禁止之列；issue 是持久且可引用的。
+- 有已提交归属文档的设计会话序号替换为该归属文档的名称：决策 21 即 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) 中的纯文本引用决策。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
+- 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
+- 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
+- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。
+
+一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。
+
+## 曾考虑的替代方案
+
+- **把设计台账与审计文档提交入库，让序号得以解析。**不予采纳：会话 transcript 是工作产物，不是持续维护的参考资料；提交它们会在 Agent Note 之外形成一套平行且不受门禁约束的决策语料，其内部编号也仍会漂移。
+- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d` 与 `\(audit [A-Z]\d`）。
+- **删除引用了失效产物的设计理由。**不予采纳：事实性语句都得到保留或改写；依行文标准的完整命题规则，删掉的只有引用、评审编排与推导过程记录。
+
+## 验证
+
+审计的成批 grep 检索（英文与中文、注释与行文、对 `.agents/` 加 `--hidden`）在已录制 fixture 与已归档 Agent Note 之外没有命中任何设计序号引用；`verify-type-equiv`、各 `gen-*` 新鲜度检查与 `verify-translation-pairing` 把重新生成与重新记录的表面固定下来。覆盖缺口：没有门禁会拒绝新的序号引用，这条规则由评审把关。
+
+## 后果
+
+- 注释中的引用凭路径或名称即可解析；读者永远不必为追溯一条引用而重建已关闭的会话。
+- 设计会话必须先把决策落进 Agent Note，持久行文才能引用这些决策；序号速记只留在会话内部。
+- 引用变长了（用一条 note 路径取代「(decision 21)」），换来的是无需 grep 即可解析。
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
index 2233dcadde..702f58d6c7 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.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 .agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
-2026-06-19-drop-mutable-session-summary.md: f87378a1c3737950eb536be8e3f6776586eb8a01
-2026-06-19-drop-mutable-session-summary.zh.md: f15dcc038154a9170ac41fd5733712164728f518
+2026-06-19-drop-mutable-session-summary.md: fdbfb1b4f7423fda152a5c63c02484ebe71e27dc
+2026-06-19-drop-mutable-session-summary.zh.md: 1b99c00f49b5149583b6f0b9387f580ee892d7a1
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
index f87378a1c3..fdbfb1b4f7 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.md
@@ -22,7 +22,7 @@ Delete the mutable session summary entirely. `SessionSummary` and the `SessionMe
 
 Anything the summary was meant to provide is **derivable from the append-only log** when a consumer actually needs it (`firstPrompt` = first `user/message`; recency = the last event's `time` or the file mtime) or already lives in the immutable header (`createdAt`, `cwd`). The one thing *not* derivable — a user-*edited* title — had no implementation and is pure YAGNI; it can return as its own log event or header field if a real feature ever needs it.
 
-This is recorded as a decision because it is **durable** (it narrows a public service contract and an on-disk format across two backends), **contested** (the summary was a deliberate forward-looking design, not an accident), and **surprising** (a future reader finding `SessionHeader` where the original Agent Note describes `SessionMeta` would otherwise ask why the summary vanished). It also unblocks the [shared persistence write coordinator](../architecture/2026-06-18-shared-persistence-write-coordinator.md): with no mutable summary, the coordinator's hook interface needs no `updateSummary` hook and the JSONL-sidecar-vs-SQLite-column durability divergence disappears, so the two backends' write paths converge.
+The removal narrows a public service contract and an on-disk format across two backends; the summary was a deliberate forward-looking design, not an accident; and `SessionHeader` now stands where the original Agent Note described `SessionMeta`, which is why the summary vanished. It also unblocks the [shared persistence write coordinator](../architecture/2026-06-18-shared-persistence-write-coordinator.md): with no mutable summary, the coordinator's hook interface needs no `updateSummary` hook and the JSONL-sidecar-vs-SQLite-column durability divergence disappears, so the two backends' write paths converge.
 
 ## No migration
 
diff --git a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
index f15dcc0381..1b99c00f49 100644
--- a/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-19-drop-mutable-session-summary.zh.md
@@ -22,7 +22,7 @@ Status: implemented
 
 摘要原本要提供的一切，在消费方真正需要时都**可从仅追加日志中派生**（`firstPrompt` = 第一条 `user/message`；近期度 = 最后一个事件的 `time` 或文件 mtime），或者已经存在于不可变 header 中（`createdAt`、`cwd`）。唯一*不可*派生的是用户*手动编辑*的标题，但它从未实现，纯属 YAGNI；如果未来真有功能需要，它可以作为独立的日志事件或 header 字段回归。
 
-这被记录为一项决策，因为它具有**持久性**（它同时收窄两个后端的公开服务约定和磁盘格式）、**争议性**（summary 是有意为未来设计的结果，而非意外），也具有**反直觉性**（未来读者在原 Agent Note 描述 `SessionMeta` 的位置发现 `SessionHeader` 时，若无此记录便会追问 summary 为何消失）。它还为[共享持久化写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.md)扫清障碍：不再有可变 summary 后，协调器的钩子接口不需要 `updateSummary` 钩子，JSONL sidecar 与 SQLite 列之间的持久性分歧也随之消失，使两个后端的写入路径趋于一致。
+这次移除同时收窄两个后端的公开服务约定和磁盘格式；summary 是有意为未来设计的结果，而非意外；如今原 Agent Note 描述 `SessionMeta` 之处已是 `SessionHeader`，这就是 summary 消失的原因。它还为[共享持久化写入协调器](../architecture/2026-06-18-shared-persistence-write-coordinator.md)扫清障碍：不再有可变 summary 后，协调器的钩子接口不需要 `updateSummary` 钩子，JSONL sidecar 与 SQLite 列之间的持久性分歧也随之消失，使两个后端的写入路径趋于一致。
 
 ## 无需迁移
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.i18n.yaml
index c8714bf8ab..2e82d32d06 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.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 .agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md
-2026-06-20-collapse-trace-only-session-events.md: c77062c3cd44286b43c175702c35b36f9cc31da6
-2026-06-20-collapse-trace-only-session-events.zh.md: bc7e33f2d5dce370b846b1451fca6a652660dc92
+2026-06-20-collapse-trace-only-session-events.md: a7a4ab3a2e4c008b59bc4cb1023e699c6fd8a76b
+2026-06-20-collapse-trace-only-session-events.zh.md: ecb267e77f6a35aba8f73200c9d3061a821c2965
diff --git a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md
index c77062c3cd..a7a4ab3a2e 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.md
@@ -15,7 +15,7 @@ These events make the canonical transcript look more useful as telemetry than it
 Standalone trace-only events are removed exactly where their information is preserved without a parallel record:
 
 - Successful-step usage folds into the matching `assistant/message` (`assistant/message { turn, step, content, usage? }`), so the assembled model output and its accounting travel together.
-- A failed or aborted step that has usage but no assistant content carries the usage on an empty-content `assistant/message` (the implementation note below carries the no-information-loss proof) — no persisted usage chunk goes unrepresented.
+- A failed or aborted step that has usage but no assistant content carries the usage on an empty-content `assistant/message { content: [], usage }` — no persisted usage chunk goes unrepresented. The no-information-loss case is the max-tokens path: a step cut off with usage but empty content (e.g. only a dropped tool call) previously emitted a standalone `usage`. To keep the empty-content event from injecting a spurious content-less assistant turn into the provider transcript, `deriveMessages()` skips empty-content `assistant/message` events; a regression test asserts usage stays represented AND derived history stays uncorrupted.
 - The step number from the standalone `error` event folds into `turn/end.reason` for `kind: 'error'` (`{ kind: 'error', step, message, code? }`) — `turn/end` is the durable turn outcome ACP and resume already consume.
 - `agent/error` and logging stay for live diagnostics; there is no second session-log error record after `turn/end`.
 
@@ -31,14 +31,10 @@ The user conversation log contains what is needed to render, resume, audit, and
 
 ## Consequences
 
-A consumer can no longer filter the canonical log for standalone `usage` or step-level `error` rows. It must read those facts from the assistant/failure events that carry them. That is a reasonable simplification only if the implementing PR proves the same facts remain present; otherwise the standalone events should stay.
+A consumer can no longer filter the canonical log for standalone `usage` or step-level `error` rows. It must read those facts from the assistant/failure events that carry them. That is a reasonable simplification because the same facts remain present, as the Verification section proves.
 
 ## Implementation note
 
-Shipped as proposed, with one scope refinement (per AGENTS.md "Agent Notes are proposals, not golden truth"):
-
-- **Empty-content `assistant/message` hosts usage with no data loss.** The proof the proposal demanded (no persisted usage chunk becomes unrepresented) lands on the max-tokens path: a step cut off with usage but empty content (e.g. only a dropped tool call) previously emitted a standalone `usage`. It now records an empty-content `assistant/message { content: [], usage }`. To keep that from injecting a spurious content-less assistant turn into the provider transcript, `deriveMessages()` skips empty-content `assistant/message` events. A regression test asserts usage stays represented AND derived history is uncorrupted.
-
 **Format version.** This changes persisted events, but the pre-release session format remains pinned at `0` and rejects any other version without migration. `dsh-session` owns the constant used by writers and load validation. Monotonic format versions begin at the first release.
 
 Usage is now observed on `assistant/message.usage`; an operational error's step on `turn/end.reason` for `kind: 'error'`. `agent/error` + logging are unchanged for live diagnostics.
diff --git a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.zh.md b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.zh.md
index bc7e33f2d5..ecb267e77f 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-collapse-trace-only-session-events.zh.md
@@ -15,7 +15,7 @@ Status: implemented
 仅在信息已被保留、无需并行记录的情况下，移除独立的、仅用于追踪的事件：
 
 - 成功步骤的 usage 折叠进匹配的 `assistant/message`（`assistant/message { turn, step, content, usage? }`），使组装好的模型输出与其计费信息一同传递。
-- 失败或中止的步骤如果有 usage 但没有 assistant 内容，则将 usage 放在一个空内容的 `assistant/message` 上（下方实现说明给出了无信息丢失的证明）——不会有已持久化的 usage 分片无处安放。
+- 失败或中止的步骤如果有 usage 但没有 assistant 内容，则将 usage 放在一个空内容的 `assistant/message { content: [], usage }` 上——不会有已持久化的 usage 分片无处安放。无信息丢失的情形是 max-tokens 路径：一个被截断的步骤有 usage 但内容为空（例如只有一个被丢弃的工具调用），以前会发出独立的 `usage`。为防止空内容事件向提供方 transcript 注入一个多余的无内容 assistant 轮次，`deriveMessages()` 跳过空内容的 `assistant/message` 事件；回归测试断言 usage 仍有记录，且派生历史未被破坏。
 - 独立 `error` 事件中的步骤编号折叠进 `turn/end.reason`（当 `kind: 'error'` 时：`{ kind: 'error', step, message, code? }`）——`turn/end` 是 ACP 和恢复机制已经消费的持久轮次结果。
 - `agent/error` 与日志保留用于实时诊断；`turn/end` 之后不再有第二条会话日志错误记录。
 
@@ -31,14 +31,10 @@ Status: implemented
 
 ## 后果
 
-消费方不能再从规范日志中筛选独立的 `usage` 或步骤级 `error` 行，而必须从承载这些信息的助手消息或失败事件中读取这些事实。只有在实现 PR（Pull Request）证明相同事实仍然存在的前提下，这才是合理的简化；否则独立事件应予保留。
+消费方不能再从规范日志中筛选独立的 `usage` 或步骤级 `error` 行，而必须从承载这些信息的助手消息或失败事件中读取这些事实。由于相同事实仍然存在——「验证」一节给出了证明——这是合理的简化。
 
 ## 实现说明
 
-按提案落地，但有一处范围细化（遵循 AGENTS.md 所述「Agent Note 是提案，而非绝对真理」）：
-
-- **空内容 `assistant/message` 承载 usage，无数据丢失。** 提案要求的证明（不会有已持久化的 usage 分片无处安放）落在 max-tokens 路径上：一个被截断的步骤有 usage 但内容为空（例如只有一个被丢弃的工具调用），以前会发出独立的 `usage`。现在它记录一个空内容的 `assistant/message { content: [], usage }`。为防止这向提供方 transcript 注入一个多余的无内容 assistant 轮次，`deriveMessages()` 跳过空内容的 `assistant/message` 事件。回归测试断言 usage 仍有记录，且派生历史未被破坏。
-
 **格式版本。** 此变更影响已持久化的事件，但预发布会话格式仍固定为 `0`，拒绝任何其他版本且不做迁移。`dsh-session` 拥有写入方和加载校验使用的常量。单调递增的格式版本从首次正式发布开始。
 
 Usage 现在通过 `assistant/message.usage` 观测；运行时错误的步骤编号通过 `turn/end.reason`（当 `kind: 'error'` 时）观测。`agent/error` 与日志用于实时诊断，保持不变。
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
index a07b952a01..1b1b928591 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.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 .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
-2026-06-20-public-agent-stop-surface.md: ecbd00864f9e11205e544049a2e1c641ac132213
-2026-06-20-public-agent-stop-surface.zh.md: e9b0a3b8735537f2323dfe246eb7002b23c14947
+2026-06-20-public-agent-stop-surface.md: cd18299475373fba0e9a324d601e868bd1925370
+2026-06-20-public-agent-stop-surface.zh.md: 9824dbc1f03edea29edeabec50ed2b7c7bbe750e
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
index ecbd00864f..cd18299475 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
@@ -4,13 +4,11 @@ Status: implemented
 
 English | [中文](2026-06-20-public-agent-stop-surface.zh.md)
 
-> **Implementation note:** Only `abort()` was removed. `whenIdle()` remains because it is the public quiescence signal and safely handles waiter settlement and replacement-turn races; consumers should not reconstruct that behavior from status transitions.
-
 ## Problem
 
 The public `Agent` handle exposed two overlapping ways to stop in-flight work: step-only `abort()` and queue-aware `cancel()`. The former preserved queued input while the latter originally only exposed its broad default, which clears queued and steering work while aborting the active turn. `cancel(cause, { keepInbox: true })` now covers the production Web stop policy without exposing the private turn holder; ACP retains broad cancellation, while lifecycle owners tear down agents through `AgentHandle.dispose()`. No production caller needs a bare step-only abort.
 
-The behavioral distinction is real, but no shipping code needs a separate narrower verb. AgentLoop owns one private cancellation holder for the whole turn. `cancel(cause, options?)` carries an explicit typed `user` or `parent` cause; its broad default drops pending input, while `keepInbox` preserves pending work for later turns. Disposal remains a separate lifecycle interruption. The complete ownership and propagation contract lives in the [explicit turn cancellation RFC](../architecture/2026-07-16-explicit-turn-cancellation.md).
+The behavioral distinction is real, but no shipping code needs a separate narrower verb. AgentLoop owns one private cancellation holder for the whole turn. `cancel(cause, options?)` carries an explicit typed `user` or `parent` cause; its broad default drops pending input, while `keepInbox` preserves pending work for later turns. Disposal remains a separate lifecycle interruption. The complete ownership and propagation contract lives in the [explicit turn cancellation note](../architecture/2026-07-16-explicit-turn-cancellation.md).
 
 The extra surface area made the loop carry a public verb that was mostly a teardown internal. An options-bearing `cancel()` expresses caller policy without exposing a second holder-shaped operation.
 
@@ -24,7 +22,7 @@ Public `abort()` is absent, and the disposer remains async and waits for the loo
 
 ## Alternatives considered
 
-**Removing `whenIdle()` too** — the original proposal's shape, reversed on validating the premise against the code (the implementation note above carries the full record): it is a load-bearing quiescence primitive, and pushing consumers onto hand-observed `running`→`idle` transitions is exactly the brittle path the defensive patterns warn against.
+**Removing `whenIdle()` too** — the original proposal's shape, reversed on validating the premise against the code: it is a load-bearing quiescence primitive that safely handles waiter settlement and replacement-turn races, and pushing consumers onto hand-observed `running`→`idle` transitions is exactly the brittle path the defensive patterns warn against.
 
 ## Verification
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
index e9b0a3b873..9824dbc1f0 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.zh.md
@@ -4,8 +4,6 @@ Status: implemented
 
 [English](2026-06-20-public-agent-stop-surface.md) | 中文
 
-> **实现说明：** 仅移除了 `abort()`。`whenIdle()` 予以保留，因为它是公开的完全停稳信号，能安全处理等待者结算与替换轮次竞态；消费方不应从状态转换中自行重建该行为。
-
 ## 问题
 
 公共 `Agent` handle 暴露了两种相互重叠的在途工作停止方式：仅针对步骤的 `abort()` 和感知队列的 `cancel()`。前者保留已排队输入，后者原本只暴露广义默认行为，该行为会清除已排队和 steering（中途引导）工作，同时中止活动轮次。`cancel(cause, { keepInbox: true })` 现在无需暴露私有轮次 holder 即可覆盖生产环境的 Web 停止策略；ACP 保留广义取消，生命周期拥有者则通过 `AgentHandle.dispose()` 拆除 agent（智能体）。没有生产调用方需要一个裸的、仅针对步骤的 abort。
@@ -24,7 +22,7 @@ Status: implemented
 
 ## 曾考虑的替代方案
 
-**同时移除 `whenIdle()`**：最初提案的形态，在对照代码验证前提后被推翻（上方的实现说明记录了完整过程）：它是承重的完全停稳原语，迫使消费方手动观测 `running`→`idle` 转换正是防御性模式所警告的脆弱路径。
+**同时移除 `whenIdle()`**：最初提案的形态，在对照代码验证前提后被推翻：它是承重的完全停稳原语，能安全处理等待者结算与替换轮次竞态，迫使消费方手动观测 `running`→`idle` 转换正是防御性模式所警告的脆弱路径。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.i18n.yaml
index 1357d372f5..5268b8e2f8 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.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 .agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md
-2026-06-20-remove-agent-boundary-mirror-events.md: 24ac1e32667eb325044f4df583cde509421af3de
-2026-06-20-remove-agent-boundary-mirror-events.zh.md: 633c349a3e3a1efc4089fa9ae639aa457dd3d619
+2026-06-20-remove-agent-boundary-mirror-events.md: cb3cb83e7e37fae52b59bb8566284aa80708e23a
+2026-06-20-remove-agent-boundary-mirror-events.zh.md: aa7ebec9ff8870f9237afbe137bf94bd2c7b61a9
diff --git a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md
index 24ac1e3266..cb3cb83e7e 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md
@@ -4,15 +4,6 @@ Status: implemented
 
 English | [中文](2026-06-20-remove-agent-boundary-mirror-events.zh.md)
 
-<!-- Shipped in AMENDED, narrowed form: the four turn/step BOUNDARY mirrors are
-     removed; `agent/steering` and `agent/stream-chunk` were RETAINED here (they
-     are not durable-boundary mirrors — see "Scope: what is and isn't removed").
-     The original proposal bundled `agent/steering` into the removal; keeping it
-     out kept this Agent Note's scope to boundaries. Each retained event was later
-     removed by its own decision — see
-     [Stop mirroring the token stream as an agent event](../../archived/simplification/2026-07-02-remove-stream-chunk-mirror.md)
-     and [Remove the `agent/steering` mirror emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md). -->
-
 ## Problem
 
 The loop records the canonical transcript in `SessionEvent` and also emitted a parallel set of live `agent/*` boundary mirror events: `agent/turn-start`, `agent/turn-end`, `agent/step-start`, and `agent/step-end`. The mirrors made consumers choose between two sources of truth for the SAME durable fact. ACP already chose the session log for prompt settlement and committed output because it is the one durable, replayable record; consuming a live mirror would require reconciling its timing with the boundary already stored in that log. The stdio UI was the only production consumer that still rendered turn boundaries from the mirror events; it already rendered tool calls and results from `session/event`.
@@ -25,7 +16,7 @@ Make `session/event` the single live boundary/transcript stream. Consumers that
 
 The four durable-boundary mirrors — `agent/turn-start`, `agent/turn-end`, `agent/step-start`, `agent/step-end` — are removed from the agent event taxonomy. A UI that wants the agent handle at a boundary retains the live target object from `agent/created`/`agent/disposed` and compares its session directly; `dsh-ui-stdio` uses this to label the app-owned agent's `[main turn N]` header while other sessions render their durable id. The canonical record remains the event-sourced session log.
 
-The step mirrors (which had no consumer at all) were removed first, in [the event-domain-semantics Agent Note](../architecture/2026-06-30-event-domain-semantics.md); that Agent Note KEPT the turn mirrors on the stated justification that the stdio UI needed the `Agent` handle at the turn boundary. This Agent Note finishes the job: `dsh-ui-stdio` is a disposable test REPL whose rendering can change freely, so "ui-stdio needs it" is not a reason to keep a mirror — it reads `session/event` and retains only its live target object.
+The step mirrors (which had no consumer at all) were removed first, in [the event-domain-semantics Agent Note](../architecture/2026-06-30-event-domain-semantics.md); that Agent Note KEPT the turn mirrors on the stated justification that the stdio UI needed the `Agent` handle at the turn boundary. This decision finishes the job: `dsh-ui-stdio` is a disposable test REPL whose rendering can change freely, so "ui-stdio needs it" is not a reason to keep a mirror — it reads `session/event` and retains only its live target object.
 
 ## Scope: what is and isn't removed
 
@@ -33,7 +24,7 @@ Removed (durable-boundary mirrors — the session log is authoritative for each)
 
 RETAINED — NOT durable-boundary mirrors, so out of scope for this decision:
 
-- `agent/steering` — not a boundary, so out of scope for THIS decision (the original proposal bundled it into the removal; that would have been scope creep here). It mirrors the durable `steering/message` control record rather than a boundary, and was removed by its own follow-up: [Remove the `agent/steering` mirror emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md).
+- `agent/steering` — not a boundary, so out of scope for THIS decision. It mirrors the durable `steering/message` control record rather than a boundary, and was removed by its own follow-up: [Remove the `agent/steering` mirror emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md).
 - `agent/stream-chunk` — the live token stream. Out of scope for THIS decision (a mirror of the durable `assistant/chunk`, not a boundary), it was removed by its own follow-up: [Stop mirroring the token stream as an agent event](../../archived/simplification/2026-07-02-remove-stream-chunk-mirror.md).
 - `agent/created`, `agent/disposed`, `agent/status`, `agent/error`, `agent/queued` — lifecycle/control events that are not transcript data. `agent/queued` in particular is an inbox acknowledgement that fires before any durable event exists (cancelled queued work may never enter the log), so it is deliberately live-only.
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.zh.md b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.zh.md
index 633c349a3e..aa7ebec9ff 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.zh.md
@@ -4,15 +4,6 @@ Status: implemented
 
 [English](2026-06-20-remove-agent-boundary-mirror-events.md) | 中文
 
-<!-- 以修订、收窄后的形式落地：
-     移除了四个轮次/步骤边界镜像；此处保留了 `agent/steering` 和
-     `agent/stream-chunk`（它们不是持久边界镜像——参见
-     「范围：移除什么、不移除什么」）。原始提案将 `agent/steering` 与其他项一并
-     移除；把它排除在外，使本 Agent Note 的范围保持在边界上。后来每个保留事件
-     都由各自的决策移除——参见
-     [停止将 token 流镜像为 agent 事件](../../archived/simplification/2026-07-02-remove-stream-chunk-mirror.md)
-     和[移除 `agent/steering` 镜像 emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md)。 -->
-
 ## 问题
 
 循环在 `SessionEvent` 中记录规范 transcript（文本记录），同时还发出一组并行的实时 `agent/*` 边界镜像事件：`agent/turn-start`、`agent/turn-end`、`agent/step-start` 和 `agent/step-end`。这些镜像迫使消费方在同一持久事实的两个真源之间做选择。ACP（Agent Client Protocol）已经为提示词结算和已提交输出选择会话日志，因为它是唯一持久、可重放的记录；消费实时镜像需要把它的时序与日志中已经存储的边界进行调和。stdio UI 是唯一仍从镜像事件渲染轮次边界的生产环境消费方；它已经从 `session/event` 渲染工具调用和结果。
@@ -25,7 +16,7 @@ Status: implemented
 
 四个持久边界镜像——`agent/turn-start`、`agent/turn-end`、`agent/step-start`、`agent/step-end`——已从 agent（智能体）事件分类体系中移除。希望在边界处取得 agent handle 的 UI 会保留来自 `agent/created`/`agent/disposed` 的实时目标对象，并直接比较其会话；`dsh-ui-stdio` 据此为应用拥有的 agent 标记 `[main turn N]` 头部，其他会话则渲染其持久 id。规范记录仍是事件溯源会话日志。
 
-步骤镜像（完全没有消费方）最先在[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 中移除；该 Agent Note 当时以 stdio UI 需要在轮次边界取得 `Agent` handle 为由，保留了轮次镜像。本 Agent Note 完成余下工作：`dsh-ui-stdio` 是可随时丢弃的测试 REPL，其渲染可以自由变化，因此「ui-stdio 需要它」并不是保留镜像的理由——它读取 `session/event`，只保留自己的实时目标对象。
+步骤镜像（完全没有消费方）最先在[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 中移除；该 Agent Note 当时以 stdio UI 需要在轮次边界取得 `Agent` handle 为由，保留了轮次镜像。本决策完成余下工作：`dsh-ui-stdio` 是可随时丢弃的测试 REPL，其渲染可以自由变化，因此「ui-stdio 需要它」并不是保留镜像的理由——它读取 `session/event`，只保留自己的实时目标对象。
 
 ## 范围：移除什么、不移除什么
 
@@ -33,7 +24,7 @@ Status: implemented
 
 保留——不是持久边界镜像，因此不在本决策范围内：
 
-- `agent/steering`——不是边界，因此不在本决策范围内（原始提案将其一并移除；在此会造成范围蔓延）。它镜像持久的 `steering/message` 控制记录，而非边界，后来由自己的后续决策移除：[移除 `agent/steering` 镜像 emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md)。
+- `agent/steering`——不是边界，因此不在本决策范围内。它镜像持久的 `steering/message` 控制记录，而非边界，后来由自己的后续决策移除：[移除 `agent/steering` 镜像 emit](../../archived/simplification/2026-07-04-remove-agent-steering-mirror.md)。
 - `agent/stream-chunk`——实时 token 流。不在本决策范围内（它镜像持久的 `assistant/chunk`，而非边界），后来由自己的后续决策移除：[停止将 token 流镜像为 agent 事件](../../archived/simplification/2026-07-02-remove-stream-chunk-mirror.md)。
 - `agent/created`、`agent/disposed`、`agent/status`、`agent/error`、`agent/queued`——不属于 transcript 数据的生命周期/控制事件。尤其是 `agent/queued`，它是在任何持久事件存在之前触发的收件箱确认（取消的排队工作可能永远不会进入日志），所以有意只保留为实时事件。
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.i18n.yaml
index dff6c560ff..4d2986bc7e 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.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 .agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md
-2026-06-20-unify-agent-and-session-id.md: c55152f4f13fe0acb530503e84f465799007cff7
-2026-06-20-unify-agent-and-session-id.zh.md: 92774a3a1b2ff90ccc6163967b4281552a253575
+2026-06-20-unify-agent-and-session-id.md: 4084912f95aa2354e815a1b4c05cd7f90bd3c315
+2026-06-20-unify-agent-and-session-id.zh.md: 3daa09d2169e8a407bf1c4c47dd9dbe987bde99c
diff --git a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md
index c55152f4f1..4084912f95 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.md
@@ -33,7 +33,6 @@ The config-driven path keeps `agents[].id` as a stable configuration label, not
 - ACP, stdio, hooks, bash ownership, persistence, and lineage use the shared `SessionId` directly. The ACP subagent backend mints its lifecycle id in the parent namespace because a child server's returned session id is only server-local; the ACP bridge verifies exact `Agent` ownership from the forward session map; and JSON-RPC forwards only lifecycle events whose service-snapshotted `local` flag is true, obtains the delegating parent from the scoped event carrier, and keeps no child identity or lineage cache.
 - The config-driven resume-or-create policy is explicit and covered across a durable restart.
 - A production listener search kept `agent/created`/`agent/disposed` and their publication semantics.
-- Typecheck, coverage, snapshots, doc-sync, module-graph verification, build, and hygiene pass.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.zh.md b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.zh.md
index 92774a3a1b..3daa09d216 100644
--- a/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-20-unify-agent-and-session-id.zh.md
@@ -33,7 +33,6 @@ agent 的注册表 id 等于其会话 id。`CreateAgentOptions` 接受一个 `se
 - ACP、stdio、钩子、bash 归属、持久化和 lineage 直接使用共享 `SessionId`。ACP subagent 后端在父命名空间中铸造其生命周期 id，因为子服务器返回的会话 id 仅在服务器本地有效；ACP bridge 根据正向会话 map 验证精确的 `Agent` 归属；JSON-RPC 只转发生命周期事件中由服务快照保存的 `local` 标记为 true 的事件，从带范围的事件 carrier 取得委托父项，并且不保留子 identity 或 lineage cache。
 - 配置驱动的恢复或创建策略是显式的，并在持久化重启场景下得到覆盖。
 - 生产监听器搜索确认保留 `agent/created`/`agent/disposed` 及其发布语义。
-- 类型检查、覆盖率、快照、doc-sync（文档同步门禁）、module-graph 校验、构建与 hygiene 全部通过。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
index 956cfcee91..48b74cc809 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.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 .agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
-2026-06-26-fsspec-style-fs-seam.md: c11c129a55c2e9e37efc83b01a219cae8b937fbc
-2026-06-26-fsspec-style-fs-seam.zh.md: 0e73ee134563bf8208e63f37bf36415eb1bf562d
+2026-06-26-fsspec-style-fs-seam.md: 76e5493400525f01e78f47e73dc543d0499b6045
+2026-06-26-fsspec-style-fs-seam.zh.md: cc7519a8a928888973b2fcc4a3350f9e43a54979
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
index c11c129a55..76e5493400 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md
@@ -15,7 +15,7 @@ That makes every future backend reimplement model-facing read semantics and obse
 
 This also creates a real UX dead-end: a windowed read records `view: partial`, and partial views cannot authorize `edit`. A model that reads lines 100-150 of a large file therefore cannot edit line 120 unless it first gets a `full` read, which may be impossible for a file past the read cap. Literal edit only needs freshness: the bytes being matched must still be from the version the model read.
 
-The old Agent Note already deferred a separate `@deepseek-ai/dsh-fs-policy` package. This Agent Note builds that layer and keeps `ctx.fs` close to fsspec-style storage primitives (`info`/`cat`/`open`), without turning it into full fsspec.
+The old Agent Note already deferred a separate `@deepseek-ai/dsh-fs-policy` package. This decision builds that layer and keeps `ctx.fs` close to fsspec-style storage primitives (`info`/`cat`/`open`), without turning it into full fsspec.
 
 ## Decision
 
@@ -69,7 +69,7 @@ Deleted from `dsh-fs`: `readPage`, `FsExpectation`, `FsView`, `FsStateSource`, `
 
 ## Policy Contract
 
-`@deepseek-ai/dsh-fs-policy` is a plugin, not a service: it registers no `ctx.*` key and injects nothing. It owns the write/edit freshness policy and observed-state that do not belong on the `FileSystem` provider base class (where a sandboxed/remote backend would otherwise inherit model-facing observation policy it has no business carrying). It contributes that policy through the `fs/*` event gate the executor dispatches. (This Agent Note originally proposed a concrete `ctx.fileContext` service with `read`/`write`/`edit` methods; [the event-gate Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) refined it into the plugin described here so the tool is never method-coupled to the policy.)
+`@deepseek-ai/dsh-fs-policy` is a plugin, not a service: it registers no `ctx.*` key and injects nothing. It owns the write/edit freshness policy and observed-state that do not belong on the `FileSystem` provider base class (where a sandboxed/remote backend would otherwise inherit model-facing observation policy it has no business carrying). It contributes that policy through the `fs/*` event gate the executor dispatches.
 
 Observed state lives here as `WeakMap<owner, Map<targetKey, FsVersion>>`. An entry exists iff the owner has read, written, OR edited that target (every success emits `fs/observed`), so its presence *is* the prior-observation record — there is no separate `hasRead` flag. The owner is derived structurally from the opaque event actor (`{ agent?: { session? } }`), a shape that lives in `dsh-fs-policy`, not `dsh-fs`.
 
@@ -113,7 +113,7 @@ It keeps the Service Definition / Service provider / Consumer discipline, consum
 
 ## Later extension
 
-The seam was later extended with direct directory listing by [Add direct directory listing to the filesystem seam](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md). That follow-up is tracked separately so this Agent Note's acceptance criteria continue to describe the fsspec-style refit that originally shipped.
+The seam was later extended with direct directory listing by [Add direct directory listing to the filesystem seam](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md). That follow-up is recorded separately so this note continues to describe the fsspec-style refit that originally shipped.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
index 0e73ee1345..cc7519a8a9 100644
--- a/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
+++ b/.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.zh.md
@@ -15,7 +15,7 @@ Status: implemented
 
 这还造成了一个真实的用户体验死胡同：窗口化读取记录 `view: partial`，而 partial 视图无法授权 `edit`。一个模型读取了大文件的第 100-150 行，如果想编辑第 120 行，就必须先获取一次 `full` 读取，而对于超过读取上限的文件这可能做不到。字面编辑实际上只需要新鲜度：被匹配的字节仍然来自模型所读取的那个版本即可。
 
-旧 Agent Note 已经推迟了独立的 `@deepseek-ai/dsh-fs-policy` 包。本 Agent Note 构建该层，使 `ctx.fs` 保持接近 fsspec 风格的存储原语（`info`/`cat`/`open`），但不把它变成完整的 fsspec。
+旧 Agent Note 已经推迟了独立的 `@deepseek-ai/dsh-fs-policy` 包。本决策构建该层，使 `ctx.fs` 保持接近 fsspec 风格的存储原语（`info`/`cat`/`open`），但不把它变成完整的 fsspec。
 
 ## 决策
 
@@ -69,7 +69,7 @@ type FsWriteIntent =
 
 ## 策略约定
 
-`@deepseek-ai/dsh-fs-policy` 是插件，而非服务：它不注册任何 `ctx.*` 键，也不注入任何内容。它拥有不应位于 `FileSystem` 提供方基类上的写入/编辑新鲜度策略和 observed state（否则沙箱/远程后端会继承不该由其承载的面向模型观察策略）。它通过执行器分派的 `fs/*` 事件门禁贡献该策略。（本 Agent Note 最初提议带有 `read`/`write`/`edit` 方法的具体 `ctx.fileContext` 服务；[事件门禁 Agent Note](../architecture/2026-06-26-file-context-as-event-gate.md) 将其细化为本文所述插件，使工具永远不会在方法层与策略耦合。）
+`@deepseek-ai/dsh-fs-policy` 是插件，而非服务：它不注册任何 `ctx.*` 键，也不注入任何内容。它拥有不应位于 `FileSystem` 提供方基类上的写入/编辑新鲜度策略和 observed state（否则沙箱/远程后端会继承不该由其承载的面向模型观察策略）。它通过执行器分派的 `fs/*` 事件门禁贡献该策略。
 
 观测状态以 `WeakMap<owner, Map<targetKey, FsVersion>>` 的形式存放于此。当且仅当 owner 读取、写入或编辑过该目标时，条目才存在（每次成功都会发出 `fs/observed`），因此条目的存在*本身就是*先前观测的记录——没有单独的 `hasRead` 标志。owner 从不透明的事件 actor（`{ agent?: { session? } }`）结构化派生，该形状定义在 `dsh-fs-policy` 中而非 `dsh-fs` 中。
 
@@ -113,7 +113,7 @@ type FsWriteIntent =
 
 ## 后续扩展
 
-后来，[为文件系统 seam 添加直接目录列表](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)进一步扩展了该 seam。该后续工作单独跟踪，使本 Agent Note 的验收标准继续描述最初落地的 fsspec 风格改造。
+后来，[为文件系统 seam 添加直接目录列表](../../archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)进一步扩展了该 seam。该后续工作单独记录，使本文继续描述最初落地的 fsspec 风格改造。
 
 ## 曾考虑的替代方案
 
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.i18n.yaml
index eb7f6a02b9..e926e1b6ed 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.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 .agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md
-2026-07-04-drop-image-content-block.md: cdedf4bd5dfe60c72cea185d88b83d3b93928ff0
-2026-07-04-drop-image-content-block.zh.md: 4caf717a360c1a3d536415a84e57fd9fff32c710
+2026-07-04-drop-image-content-block.md: 5d0357270973ac20234d8ce72c403f27ce2ad0e0
+2026-07-04-drop-image-content-block.zh.md: f781c775e49c06f9b3f4c54d13cc3a1519c15daf
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md
index cdedf4bd5d..5d03572709 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.md
@@ -18,7 +18,7 @@ Remove `ImageBlock`, its map entry, and image-specific branches from adapters an
 
 `ContentBlockMap` can reintroduce images when adapters and compaction support them. ACP may remain a text-only automation protocol. Keeping a core type whose only implementation is rejection would advertise an unusable surface; absence gives producers an immediate compile-time failure instead.
 
-The recorded fallback, had review landed on keeping the slot: keep `ImageBlock` but replace every silent skip with a loud rejection, and document that policy in the vocabulary — the silent drop was the one state with no defender. Review landed on removal; the fallback stands as the documented alternative should the slot ever return ahead of a full feature.
+The documented fallback, should the slot ever return ahead of a full feature: keep `ImageBlock` but replace every silent skip with a loud rejection, and document that policy in the vocabulary — the silent drop was the one state with no defender.
 
 ## Verification
 
diff --git a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.zh.md b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.zh.md
index 4caf717a36..f781c775e4 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-drop-image-content-block.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 当适配器和压缩支持 image 时，`ContentBlockMap` 可以重新引入 image 内容块。ACP 可以继续作为纯文本的自动化协议。保留一个唯一实现就是拒绝的核心类型，等于宣告一个不可用的对外服务接口；移除后，生产者会立即得到编译期错误。
 
-评审中记录的回退方案（假如评审决定保留该槽位）：保留 `ImageBlock`，但将所有静默跳过替换为显式拒绝，并在词汇文档中记录该策略——静默丢弃是唯一没有辩护者的状态。评审最终决定移除；此回退方案作为文档化的替代方案保留，以备该槽位在完整功能就绪之前回归。
+文档化的回退方案（以备该槽位在完整功能就绪之前回归）：保留 `ImageBlock`，但将所有静默跳过替换为显式拒绝，并在词汇文档中记录该策略——静默丢弃是唯一没有辩护者的状态。
 
 ## 验证
 
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
index 80f7b1a144..3a37cb4ead 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.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 .agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
-2026-07-04-tighten-hook-protocol-contract.md: 0c2397fa298ebd67d24f86d66d7d049b9da57ce9
-2026-07-04-tighten-hook-protocol-contract.zh.md: b0edd754eb5115936a03a892a2db0b67552f64f1
+2026-07-04-tighten-hook-protocol-contract.md: eecec255d930d2896fc1ea3dee85bb2efa582a19
+2026-07-04-tighten-hook-protocol-contract.zh.md: 0b913a8783eab8e05d78b8c3ecc712fe4b1d947c
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
index 0c2397fa29..eecec255d9 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.md
@@ -10,7 +10,7 @@ Four pieces of the `dsh-hook-protocol`/bridge contract missed the discipline the
 
 1. **`HookDialect`'s `'native'` variant** (`packages/hooks/hook-protocol/src/types.ts`) had zero producers — the bridges stamp `'claude'` and `'codex'`; the only `'native'` constructor anywhere was the lib's own unit test. The field's own JSDoc defines `dialect` as "the bridge that ran it", and native is not a bridge: the [interception extension-points Agent Note](../feature/2026-06-30-interception-extension-points.md) records that native hooks are not a package and that "a native plugin can already use the typed Decisions" without the durable hook log, and the flagship native-plugin worked example asserts exactly that (no `hook/*` events at all).
 2. **`HookOutput.suppressOutput`** (same file) was parsed by the codec and discarded on every path: no bridge branch, no merge fold, no warn, no deferred-list row — uniquely among its parsed-but-unhonored siblings, each of which carries a stated deferral (`updatedInput` → a logged warn plus the [pre-tool-input-rewrite proposal](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md); `systemMessage` → a logged warn plus a README deferred row; `continue`/`stopReason` → a `TODO(hook-continue-false)` anchor plus the `'stop'` decision record). Structurally there is nothing to suppress: hook stdout never enters any transcript (context flows only via `additionalContext`; the log records only `decision`/`stderrSummary`), so a hook author setting `suppressOutput: true` got silent nothing with no warn.
-3. **`defaultTimeoutMs` was double-defaulted in both bridge configs with a floating literal** — a schema `.default(600_000)` AND a `?? 600_000` fallback (`packages/hooks/hooks-claude/src/index.ts`, `packages/hooks/hooks-codex/src/index.ts`), two homes per bridge for one protocol-level constant, so the bridges could silently drift apart on the shared default. *The proposal's original remedy — delete the knob outright — was overtaken by the no-hardcoded-tunables audit, which kept the knob as the explicit bridge-owned config (and added `stderrSummaryMaxChars` beside it); what remained to fix was the literal's home.*
+3. **`defaultTimeoutMs` was double-defaulted in both bridge configs with a floating literal** — a schema `.default(600_000)` AND a `?? 600_000` fallback (`packages/hooks/hooks-claude/src/index.ts`, `packages/hooks/hooks-codex/src/index.ts`), two homes per bridge for one protocol-level constant, so the bridges could silently drift apart on the shared default. *The knob stays as explicit bridge-owned config per the no-hardcoded-tunables rule (with `stderrSummaryMaxChars` beside it); the fix is the literal's home.*
 4. **The `hook/result` semantics lived in the bridges, twice, not in the lib that owns the event.** `summarize()` — the stderr truncation rule — was byte-identical in `packages/hooks/hooks-claude/src/index.ts` and `packages/hooks/hooks-codex/src/index.ts`, and so was the decision-string rule `output.decision ?? (output.continue === false ? 'stop' : 'pass')`; yet `dsh-hook-protocol` declared `hook/result`, documented `stderrSummary` as "truncated" without owning the truncation, and documented the decision values without owning the mapping. If one bridge drifted (a different cap, a different fallback), the shared durable event's semantics would fork silently.
 
 ## Decision
diff --git a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
index b0edd754eb..0b913a8783 100644
--- a/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-04-tighten-hook-protocol-contract.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 1. **`HookDialect` 的 `'native'` 变体**（`packages/hooks/hook-protocol/src/types.ts`）没有生产者——bridge 会标记 `'claude'` 和 `'codex'`；所有位置中唯一构造 `'native'` 的是该库自己的单元测试。字段自身的 JSDoc 将 `dialect` 定义为“运行它的 bridge”，而 native 不是 bridge：[拦截扩展点 Agent Note](../feature/2026-06-30-interception-extension-points.md) 记载 native 钩子不是一个包，并且“native 插件无需持久钩子日志即可使用类型化 Decision”；旗舰 native 插件实践示例恰好断言了这一点（完全没有 `hook/*` 事件）。
 2. **`HookOutput.suppressOutput`**（同一文件）被 codec 解析后在所有路径上均被丢弃：没有 bridge 分支处理它、没有合并 fold、没有 warn、没有 deferred-list 行——在所有「被解析但未兑现」的同类字段中它是唯一没有明确延期声明的（`updatedInput` → 一条 warn 日志加 [pre-tool-input-rewrite 提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)；`systemMessage` → 一条 warn 日志加 README deferred 行；`continue`/`stopReason` → 一个 `TODO(hook-continue-false)` 锚点加 `'stop'` decision 记录）。从结构上看根本无物可抑制：钩子 stdout 从不进入任何 transcript（文本记录）；上下文仅通过 `additionalContext` 流入，日志也只记录 `decision`/`stderrSummary`。因此，钩子作者设置 `suppressOutput: true` 得到的是无声的空操作，且无任何警告。
-3. **`defaultTimeoutMs` 在两个 bridge 配置中都以游离的字面量重复设置了默认值**——schema 的 `.default(600_000)` 加上一个 `?? 600_000` 回退（`packages/hooks/hooks-claude/src/index.ts`、`packages/hooks/hooks-codex/src/index.ts`），一个协议级常量在每个 bridge 中有两个归属地，两个 bridge 可能在共享默认值上悄然分歧。*提案最初的补救措施是彻底删除该旋钮，但被 no-hardcoded-tunables 审计所取代：审计保留了该旋钮作为 bridge 拥有的显式配置（并在旁边新增了 `stderrSummaryMaxChars`）；剩下要修的是字面量的归属地。*
+3. **`defaultTimeoutMs` 在两个 bridge 配置中都以游离的字面量重复设置了默认值**——schema 的 `.default(600_000)` 加上一个 `?? 600_000` 回退（`packages/hooks/hooks-claude/src/index.ts`、`packages/hooks/hooks-codex/src/index.ts`），一个协议级常量在每个 bridge 中有两个归属地，两个 bridge 可能在共享默认值上悄然分歧。*按 no-hardcoded-tunables 规则，该旋钮保留为 bridge 拥有的显式配置（旁边有 `stderrSummaryMaxChars`）；要修的是字面量的归属地。*
 4. **`hook/result` 的语义存在于两个 bridge 中（各一份），而非拥有该事件的 lib。** `summarize()`——stderr 截断规则——在 `packages/hooks/hooks-claude/src/index.ts` 与 `packages/hooks/hooks-codex/src/index.ts` 中逐字节相同；decision 字符串规则 `output.decision ?? (output.continue === false ? 'stop' : 'pass')` 同样如此。然而 `dsh-hook-protocol` 声明了 `hook/result`、在文档中将 `stderrSummary` 描述为「已截断」却不拥有截断逻辑，记录了 decision 值却不拥有映射逻辑。如果某个 bridge 漂移（不同的上限、不同的回退），共享持久化事件的语义就会悄然分叉。
 
 ## 决策
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
index dc75549250..62ce36c656 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.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 .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
-2026-07-17-one-send-one-turn.md: 834eb2b3aace0a0aa5f86f483e7b7d7aabbe467e
-2026-07-17-one-send-one-turn.zh.md: 5bd2ed0e70766c43b0a0a5d5d4038b39094d5099
+2026-07-17-one-send-one-turn.md: 71ea5d23c303a2e5de472ceabf9868364d916ab9
+2026-07-17-one-send-one-turn.zh.md: ac0af03c61c4fb5583f2f08e28e957994954e094
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
index 834eb2b3aa..71ea5d23c3 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md
@@ -14,7 +14,7 @@ This grouping changes behavior, not just the number of model calls. One ordinary
 
 ## Decision
 
-The rule is simple: each successful `send()` creates one independent FIFO queue item. If that item runs, it is the only ordinary message in its turn. An item can be dropped before it starts, so the precise guarantee is at most one turn rather than exactly one; two sends are never silently combined.
+Each successful `send()` creates one independent FIFO queue item. If that item runs, it is the only ordinary message in its turn. An item can be dropped before it starts, so the precise guarantee is at most one turn rather than exactly one; two sends are never silently combined.
 
 Before inserting a message, `send()` checks the agent state and accepts an already identified, deeply frozen value. The durable splice and `agent/inbox/inserted { message }` retain its `MessageId`; the pending message remains addressable through `Inbox.replace()` and `Inbox.remove()` until the driver claims or discards it. The [claimed pre-step inbox decision](../architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md) owns the current lifecycle.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
index 5bd2ed0e70..ac0af03c61 100644
--- a/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 ## 决策
 
-规则很简单：一次成功的 `send()` 创建一个独立的 FIFO 队列项。该队列项如果运行，就是所在轮次中唯一的普通消息。队列项可能在启动前被丢弃，因此精确保证是最多一个轮次，而不是必定一个轮次；两次 send 绝不会被悄悄合并。
+一次成功的 `send()` 创建一个独立的 FIFO 队列项。该队列项如果运行，就是所在轮次中唯一的普通消息。队列项可能在启动前被丢弃，因此精确保证是最多一个轮次，而不是必定一个轮次；两次 send 绝不会被悄悄合并。
 
 消息插入之前，`send()` 会检查 agent 状态，并接受已有标识且经过深度冻结的值。持久化 splice 与 `agent/inbox/inserted { message }` 会保留其 `MessageId`；在驱动器领取或丢弃该消息之前，可以通过 `Inbox.replace()` 与 `Inbox.remove()` 寻址。当前生命周期由[已领取 pre-step inbox 决策](../architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md)规定。
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
index 26e91f9351..625bb457ea 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.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 .agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
-2026-07-31-one-route-to-add-a-workspace.md: 93f10493848a65aee9c9e67502abfd73fe1e6d1f
-2026-07-31-one-route-to-add-a-workspace.zh.md: 83d91abb9ada3c1431a1b4ef126ea42a8406d326
+2026-07-31-one-route-to-add-a-workspace.md: 46bd5d5ca5ecfbc340fcb46b6da5e9f237764ab1
+2026-07-31-one-route-to-add-a-workspace.zh.md: 6a6e8b3fc9f64a62d3264f4c7779d11c8515e447
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
index 93f1049384..46bd5d5ca5 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-31-one-route-to-add-a-workspace.zh.md)
 
 Both Workspace surfaces — the sidebar region header's `+` and the conversation hero's chip — offered two ways to get a Workspace: **Open local folder…**, which raised the composed directory flow, and **Create a new workspace**, which took a name and created `<workspaceRoot>/<name>`. The two overlapped: the browse occupant carries its own **New folder** affordance, so picking a directory already covered creating one. Two entries meant two vocabularies for one outcome, a name dialog with its own duplicate-name rule, and a create target the operator could neither see nor choose.
 
-Removing the weaker entry leaves the sidebar header with exactly one action, which raised the presentation question this Note also settles: what a popover with a single row should look like.
+Removing the weaker entry leaves the sidebar header with exactly one action, which raised the presentation question this decision also settles: what a popover with a single row should look like.
 
 ## Decision
 
@@ -27,7 +27,7 @@ The direct-open path carries the busy rule the menu entry states: while a pick i
 
 ## Wire and CLI residue
 
-The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace-root` still feeds its target directory, but no product surface reaches either any more. The same is true of the client contract that carried the name to the wire: `WorkspaceCreateInput`, `WorkspacesService.create`'s `{ name }` arm, `intentName`'s name branch, and the manager's "name under workspaceRoot" contract. `apps/cli/README.md` and its Chinese counterpart still document `--workspace-root` as creating named Workspaces. The whole set is marked for deletion at the call site in `packages/host/apiproxy/src/api-proxy.ts` and left to a follow-up change: it is backend, client-contract, and CLI surface with its own reviewer and its own test fallout (the api-proxy workspace suite, the runtime workspace suite, the config catalog), and the release-blocking part of this decision is the UI.
+The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace-root` still feeds its target directory, but no product surface reaches either any more. The same is true of the client contract that carried the name to the wire: `WorkspaceCreateInput`, `WorkspacesService.create`'s `{ name }` arm, `intentName`'s name branch, and the manager's "name under workspaceRoot" contract. `apps/cli/README.md` and its Chinese counterpart still document `--workspace-root` as creating named Workspaces. The whole set is marked for deletion at the call site in `packages/host/apiproxy/src/api-proxy.ts` and left to a follow-up change: it is backend, client-contract, and CLI surface with its own test fallout (the api-proxy workspace suite, the runtime workspace suite, the config catalog), and the release-blocking part of this decision is the UI.
 
 ## Testing
 
@@ -39,13 +39,13 @@ The host's `workspace.create` still accepts `{ name }`, and `dsh web --workspace
 
 **Keep `Open local folder…` as the label.** Rejected: after the merge the entry both opens and creates, and naming it after the mechanism hides the creation half from exactly the users whose entry we removed. The counter-argument — "本地" usefully disambiguates the browser's machine from the harness's — is answered one step later by the dialog's own title and breadcrumbs.
 
-**Keep the two-entry menu and make `Create a new workspace` open the same flow.** Rejected: two labels for one action is the confusion we were asked to remove, not a smaller version of it.
+**Keep the two-entry menu and make `Create a new workspace` open the same flow.** Rejected: two labels for one action is the confusion this change removes, not a smaller version of it.
 
 **Keep a one-row popover for consistency with the hero's menu.** Rejected: a popover that offers no choice is a wasted click and reads as unfinished. Consistency here is the *rule* (menu ⇔ a choice exists), not the widget.
 
 **Keep the menu shell for entries we might add later (clone a repo, remote directory).** Rejected under "require a current owner and need": no such entry exists, and restoring a menu when one arrives is a smaller change than shipping an empty frame now.
 
-**Delete the wire's create-by-name branch in the same change.** Rejected for this PR: it is backend/CLI surface with a different reviewer and a wider test fallout, and the urgent decision is the UI. See the residue section — it is marked, not forgotten.
+**Delete the wire's create-by-name branch in the same change.** Rejected here: it is backend/CLI surface with a wider test fallout, and the urgent decision is the UI. See the residue section — it is marked, not forgotten.
 
 **Register the workspace through the host in the e2e scaffold instead of driving the dialog.** Rejected: it would have decoupled all 15 scenarios from the picker, so nothing in the lane would prove the surviving route reaches a live composer. Every scenario now walks the real dialog to adopt its directory; only the create-a-folder half is concentrated in one scenario, because repeating it everywhere makes the shared helper non-idempotent for no extra signal.
 
diff --git a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
index 83d91abb9a..6a6e8b3fc9 100644
--- a/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
+++ b/.agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md
@@ -8,7 +8,7 @@ Status: implemented
 
 两处 Workspace 表层——侧边栏区头的 `+` 与会话主视觉区的 chip——都提供了两条获得 Workspace 的路径：**打开本地文件夹…** 拉起组合的目录流程，**新建工作区** 接收一个名称并创建 `<workspaceRoot>/<name>`。两者重叠：浏览占用者自带 **新建文件夹** 能力，因此"选一个目录"本就覆盖了"建一个目录"。两个入口意味着同一结果有两套词汇、一个自带重名规则的名称对话框，以及一个操作者既看不到也选不了的创建位置。
 
-删掉较弱的那个入口后，侧边栏区头只剩一个动作，于是引出了本 Note 一并裁定的展示问题：只有一行的浮层应该长什么样。
+删掉较弱的那个入口后，侧边栏区头只剩一个动作，于是引出了本决策一并裁定的展示问题：只有一行的浮层应该长什么样。
 
 ## Decision
 
@@ -27,7 +27,7 @@ Status: implemented
 
 ## Wire and CLI residue
 
-Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端约定同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一约定。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端约定与 CLI 面，有各自的 reviewer 和各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
+Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root` 也仍在为它提供目标目录，但已没有任何产品表层会走到它们。把名称送到 wire 的客户端约定同样如此：`WorkspaceCreateInput`、`WorkspacesService.create` 的 `{ name }` 分支、`intentName` 的名称分支，以及 manager 中"workspaceRoot 下的 name"这一约定。`apps/cli/README.md` 及其中文对照本也仍把 `--workspace-root` 记为"创建具名 Workspace"。这一整套都在 `packages/host/apiproxy/src/api-proxy.ts` 的调用点标记为待删除，并留给后续改动：它横跨 backend、客户端约定与 CLI 面，有各自的测试波及面（api-proxy workspace 套件、runtime workspace 套件、配置目录），而本决定中阻塞发布的部分是 UI。
 
 ## Testing
 
@@ -39,13 +39,13 @@ Host 侧的 `workspace.create` 仍接受 `{ name }`，`dsh web --workspace-root`
 
 **保留 `打开本地文件夹…` 作为标签。** 否决：合并后该入口既能打开也能创建，用机制命名会恰好对那些入口被我们删掉的用户隐藏创建这一半。反方理由——"本地"二字有效区分了浏览器所在机器与 harness 所在机器——在下一步就由对话框自身的标题和面包屑回答了。
 
-**保留双入口菜单，让 `新建工作区` 也打开同一个流程。** 否决：同一动作两个标签正是我们被要求消除的混淆，而不是它的缩小版。
+**保留双入口菜单，让 `新建工作区` 也打开同一个流程。** 否决：同一动作两个标签正是本次改动所消除的混淆，而不是它的缩小版。
 
 **为了与主视觉区菜单保持一致而保留只有一行的浮层。** 否决：不提供选择的浮层是一次浪费的点击，读起来像半成品。这里要一致的是*规则*（有菜单 ⇔ 存在选择），不是控件。
 
 **为将来可能新增的入口（克隆仓库、远程目录）保留菜单壳。** 否决，依据"require a current owner and need"：这样的入口目前并不存在，而等它到来时再恢复菜单，比现在就发一个空壳的改动更小。
 
-**在同一改动中删除 wire 的按名称创建分支。** 本 PR 否决：那是 backend/CLI 面，reviewer 不同、测试波及面更广，而紧急的决定是 UI。见 residue 一节——它是被标记了，不是被遗忘了。
+**在同一改动中删除 wire 的按名称创建分支。** 在此否决：那是 backend/CLI 面，测试波及面更广，而紧急的决定是 UI。见 residue 一节——它是被标记了，不是被遗忘了。
 
 **在 e2e scaffold 中经 host 注册 workspace，而不驱动对话框。** 否决：那会让全部 15 个场景与选择器解耦，整条 lane 将无法证明幸存的这条路径能走到可用的 composer。现在每个场景都会走真实对话框来接纳自己的目录；只有"新建文件夹"那一半集中在一个场景里，因为处处重复只会让共享辅助函数失去幂等性，却换不来额外信号。
 
diff --git a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.i18n.yaml b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.i18n.yaml
index d64cedbdc3..dd31b8f7c8 100644
--- a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.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 .agents/notes/implemented/testing/2026-06-11-property-based-testing.md
-2026-06-11-property-based-testing.md: a1bd4147a26a3d562899310e238096939fc2d01a
-2026-06-11-property-based-testing.zh.md: 062b2df76597ba16a7ad0682d57b35e54a07d9bd
+2026-06-11-property-based-testing.md: 7ab6f2daeb65e603d055ad6127a91f6b76ebc26e
+2026-06-11-property-based-testing.zh.md: 2fae02356a84b88e750ce1fd8c3003212395b084
diff --git a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.md b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.md
index a1bd4147a2..7ab6f2daeb 100644
--- a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.md
+++ b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-06-11-property-based-testing.zh.md)
 
-> Merges the original proposal and the decision record for one topic. It found a real BlockAssembler duplicate-`block-end` bug on first run.
+> The property suite found a real BlockAssembler duplicate-`block-end` bug on its first run.
 
 ## Problem
 
@@ -12,7 +12,7 @@ Example-based tests pin the cases we thought of. The harness's core is protocol-
 
 ## Decision
 
-Adopt `fast-check` (a root devDependency) with one `tests/properties.spec.ts` per protocol-shaped package, generators tuned for *realistic-but-adversarial* inputs (not uniform noise) and `numRuns` kept so the suite stays well under ~10s locally. Failures print a reproducible seed. (The original proposal also sketched a nightly CI job running 100× the iterations; that was not shipped — the property suite runs only in the normal `push`/`pull_request` CI, and a scheduled high-iteration job remains possible future work.)
+`fast-check` (a root devDependency) powers one `tests/properties.spec.ts` per protocol-shaped package, with generators tuned for *realistic-but-adversarial* inputs (not uniform noise) and `numRuns` kept so the suite stays well under ~10s locally. Failures print a reproducible seed. (A nightly CI job running 100× the iterations is not shipped — the property suite runs only in the normal `push`/`pull_request` CI; a scheduled high-iteration job remains possible future work.)
 
 - **dsh-llm / BlockAssembler:** arbitrary chunk streams (valid + malformed: duplicate indices, stragglers, missing block-start). Invariants: `blocks()` count ≤ distinct indices seen; re-assembly idempotent (`blocks()` is stable across repeated calls and `message().content` mirrors it); `blocks()` never throws and yields only valid content-block tags; `finish` reflects the last `finish` chunk, defaulting to `{kind:'stop'}` when none arrives.
 - **dsh-session:** arbitrary event logs. Invariants: `deriveMessages` deterministic; replay-from-seed identical; seq strictly monotonic; non-message events never affect derived history; derived content is decoupled from the log.
diff --git a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.zh.md b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.zh.md
index 062b2df765..2fae02356a 100644
--- a/.agents/notes/implemented/testing/2026-06-11-property-based-testing.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-11-property-based-testing.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-06-11-property-based-testing.md) | 中文
 
-> 将原始提案与同一主题的决策记录合并为一篇。首次运行即发现了 BlockAssembler 重复 `block-end` 的真实 bug。
+> 属性测试套件首次运行即发现了 BlockAssembler 重复 `block-end` 的真实 bug。
 
 ## 问题
 
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-引入 `fast-check`（作为根 devDependency），在每个协议形态的包中编写一个 `tests/properties.spec.ts`。生成器调优为*逼真但对抗性*的输入（而非均匀噪声），`numRuns` 控制在本地套件总耗时远低于约 10 秒。失败时打印可复现的 seed。（原始提案还草拟了一个夜间 CI job，以 100 倍迭代运行；该部分未交付。属性测试套件仅在常规的 `push`/`pull_request` CI 中运行，定时高迭代 job 仍属可能的后续工作。）
+`fast-check`（作为根 devDependency）为每个协议形态的包驱动一个 `tests/properties.spec.ts`。生成器调优为*逼真但对抗性*的输入（而非均匀噪声），`numRuns` 控制在本地套件总耗时远低于约 10 秒。失败时打印可复现的 seed。（以 100 倍迭代运行的夜间 CI job 未交付——属性测试套件仅在常规的 `push`/`pull_request` CI 中运行；定时高迭代 job 仍属可能的后续工作。）
 
 - **dsh-llm / BlockAssembler：** 任意分片流（合法 + 畸形：重复索引、滞后分片、缺少 block-start）。不变式：`blocks()` 计数 ≤ 已见到的不同索引数；重组幂等（`blocks()` 在重复调用间稳定，且 `message().content` 与之一致）；`blocks()` 从不抛异常且仅产出合法的 content-block 标签；`finish` 反映最后一个 `finish` 分片，无此类分片时默认为 `{kind:'stop'}`。
 - **dsh-session：** 任意事件日志。不变式：`deriveMessages` 确定性；从 seed 回放结果一致；seq 严格单调递增；非消息事件不影响推导出的历史；推导出的内容与日志解耦。
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
index 5dc542589f..0cd051aead 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.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 .agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
-2026-06-19-acp-snapshot-tests.md: c6e81dc4a51083ed37ad6f837fe7dbb08c212e23
-2026-06-19-acp-snapshot-tests.zh.md: 729e5645b097f8db5b23594e16e48dc5b4cf211f
+2026-06-19-acp-snapshot-tests.md: 9e03c3c5be7b15a1a34c954dca2f1d6e7a875ba2
+2026-06-19-acp-snapshot-tests.zh.md: 59033a2fd85bc08bfe4abe34e8fd9aff9a67c87e
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
index c6e81dc4a5..9e03c3c5be 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md
@@ -8,9 +8,7 @@ English | [中文](2026-06-19-acp-snapshot-tests.zh.md)
 
 Unit tests do not exercise the complete assembled-agent subprocess or its ACP automation wire, while real-API tests are nondeterministic and key-gated. Loader wiring, backend behavior, and protocol output can therefore regress despite green unit coverage, as the [default-export postmortem](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) demonstrated.
 
-The blocker for a full-transcript test is the model: the agent's output is driven by a non-deterministic LLM, and a key-gated test that hits the real API on every run is neither deterministic nor CI-runnable. We want the fidelity of a real run with the determinism of a fixture.
-
-This Agent Note records the decision to add a third test tier — **snapshot tests** — and the design choices that make it deterministic, keyless-in-CI, and cheap to maintain.
+The blocker for a full-transcript test is the model: the agent's output is driven by a non-deterministic LLM, and a key-gated test that hits the real API on every run is neither deterministic nor CI-runnable. The tier needs the fidelity of a real run with the determinism of a fixture.
 
 ## Decision
 
diff --git a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
index 729e5645b0..59033a2fd8 100644
--- a/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.zh.md
@@ -8,9 +8,7 @@ Status: implemented
 
 单元测试不会覆盖组装后的完整 agent（智能体）子进程及其 ACP（Agent Client Protocol）自动化协议格式，而真实 API 测试不具确定性且受密钥门控。因此，即使单元测试覆盖率检查通过，Loader 接线、后端行为和协议输出仍可能回归，[默认导出事故复盘（postmortem）](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md)已经证明了这一点。
 
-完整 transcript（文本记录）测试的阻塞因素在于模型：agent 的输出由非确定性的 LLM（大语言模型）驱动，而每次运行都命中真实 API 的密钥门控测试既不确定也无法在 CI 中运行。我们需要真实运行的保真度与 fixture（测试前置数据）的确定性兼得。
-
-本 Agent Note 记下了新增第三层测试——**快照测试**——的决策，以及让它具备确定性、在 CI 中无需密钥、且维护成本低廉的设计选择。
+完整 transcript（文本记录）测试的阻塞因素在于模型：agent 的输出由非确定性的 LLM（大语言模型）驱动，而每次运行都命中真实 API 的密钥门控测试既不确定也无法在 CI 中运行。该测试层级需要真实运行的保真度与 fixture（测试前置数据）的确定性兼得。
 
 ## 决策
 
diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml
index 774a4d8851..72f45e8ae3 100644
--- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.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 .agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
-2026-06-19-real-api-e2e-ci.md: 935664fd01df4844ee19be7b4f2f297ebf5bd29b
-2026-06-19-real-api-e2e-ci.zh.md: 4245cc9a3872cf2ab27633db5b23fc466d793934
+2026-06-19-real-api-e2e-ci.md: feb5d83f087f66dfec7e1540f6b32e33656409d4
+2026-06-19-real-api-e2e-ci.zh.md: c00aa6e962d9e86a9d5d5c1ccaf1001afa21ba67
diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
index 935664fd01..feb5d83f08 100644
--- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md
@@ -10,11 +10,9 @@ The harness leans hard on real-API tests by policy: [docs/testing.md](../../../.
 
 The default gate ([.github/workflows/ci.yml](../../../../.github/workflows/ci.yml)) is deliberately keyless: it carries no secret and runs for forks. `test:e2e` self-skips without a key (`describe.skipIf(!process.env.DEEPSEEK_API_KEY)`), so adding it there would report green without exercising the real suite. A separate secret-bearing workflow is required to make real-API coverage a merge signal.
 
-This Agent Note records the decision to add a **second, secret-consuming workflow** that runs the real-API suite in CI, and — because introducing the first CI secret into a repo that may later go public is a security/isolation decision — the threat model it relies on and what changes when the repo becomes public.
-
 ## Decision
 
-Add a dedicated workflow, [.github/workflows/e2e.yml](../../../../.github/workflows/e2e.yml), separate from ci.yml. It runs only `pnpm run test:e2e` against the external API using a repo secret, on trusted events, with a preflight that converts a missing secret into a loud failure instead of a false green. The keyless workflow remains separate so forkable quality gates and secret-consuming real-API gates keep different trigger and credential policies.
+A dedicated workflow, [.github/workflows/e2e.yml](../../../../.github/workflows/e2e.yml), separate from ci.yml, runs only `pnpm run test:e2e` against the external API using a repo secret, on trusted events, with a preflight that converts a missing secret into a loud failure instead of a false green. The keyless workflow remains separate so forkable quality gates and secret-consuming real-API gates keep different trigger and credential policies.
 
 ### A separate workflow, not a job in ci.yml
 
diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md
index 4245cc9a38..c00aa6e962 100644
--- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md
@@ -10,11 +10,9 @@ Status: implemented
 
 默认门禁（[.github/workflows/ci.yml](../../../../.github/workflows/ci.yml)）刻意无密钥：不携带 secret，可供 fork 运行。`test:e2e` 在无密钥时自动跳过（`describe.skipIf(!process.env.DEEPSEEK_API_KEY)`），因此将其加入该工作流只会报绿而不会真正执行真实套件。要让真实 API 覆盖率成为合并信号，需要一个独立的、携带 secret 的工作流。
 
-本 Agent Note 记下了新增**第二条消费 secret 的工作流**以在 CI 中运行真实 API 套件的决策；由于向未来可能公开的仓库引入第一个 CI secret 属于安全/隔离决策，本文也记录其依赖的威胁模型，以及仓库公开时需要做出的变更。
-
 ## 决策
 
-添加一个专用工作流 [.github/workflows/e2e.yml](../../../../.github/workflows/e2e.yml)，与 ci.yml 分离。它仅使用 repo secret 对外部 API 运行 `pnpm run test:e2e`，仅在可信事件上触发，并带有一个 preflight 检查：将缺失的 secret 转化为明确的失败而非虚假的绿色。无密钥工作流保持独立，使可 fork 的质量门禁与消费 secret 的真实 API 门禁各自拥有不同的触发和凭证策略。
+一个与 ci.yml 分离的专用工作流 [.github/workflows/e2e.yml](../../../../.github/workflows/e2e.yml) 仅使用 repo secret 对外部 API 运行 `pnpm run test:e2e`，仅在可信事件上触发，并带有一个 preflight 检查：将缺失的 secret 转化为明确的失败而非虚假的绿色。无密钥工作流保持独立，使可 fork 的质量门禁与消费 secret 的真实 API 门禁各自拥有不同的触发和凭证策略。
 
 ### 独立工作流，而非 ci.yml 中的一个 job
 
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml
index 34edafb0d1..2b03ad711c 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.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 .agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
-2026-06-22-subagent-snapshot-replay.md: 45034c29f608eb5b58f44b80438b801b6224cb82
-2026-06-22-subagent-snapshot-replay.zh.md: 1b90c1bda854b7cd8cd9eae1e8c9f34328477f15
+2026-06-22-subagent-snapshot-replay.md: 187831b2d3c2f08b32289983afbbe0bc03484c82
+2026-06-22-subagent-snapshot-replay.zh.md: b96be12df0ea1f1a6bb64dd787fec6880eb96243
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
index 45034c29f6..187831b2d3 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.md
@@ -13,7 +13,7 @@ It was built for ONE session per process, and that assumption is wired into two
 - **`dsh-llm-replay` keyed nothing.** It served the Nth `llm/stream` call the Nth recorded entry from a single global cursor. With a parent agent AND an in-process subagent both streaming on one context, the calls interleave and the single cursor hands the child the parent's script (and vice versa).
 - **The harness harvested one log.** `findSessionLog` walked the sessions root and returned the FIRST `.jsonl` it found. A subagent runs as a second `Session` with its own log, so the child's transcript was silently dropped.
 
-This was the `TODO(subagent-snapshots)` deferral recorded in the [subagent seam Agent Note](../feature/2026-06-21-subagent-capability-seam.md): the in-process backends (PR2) shipped with unit + e2e coverage, but the full-transcript snapshot tier could not express a nested-agent shape until this infrastructure landed. This Agent Note is that stacked follow-up.
+This was the `TODO(subagent-snapshots)` deferral recorded in the [subagent seam Agent Note](../feature/2026-06-21-subagent-capability-seam.md): the in-process backends shipped with unit + e2e coverage, but the full-transcript snapshot tier could not express a nested-agent shape until this infrastructure landed.
 
 ## Decision
 
@@ -55,4 +55,4 @@ Both replay keyless in the default gate.
 - The `TODO(subagent-snapshots)` deferral is resolved: nested-agent transcripts are now a first-class snapshot shape.
 - `GenerateOptions.sessionId` is a small, honest core API addition useful beyond replay (telemetry, request routing).
 - The `subagent` tool is bound to a single provider, so both children in `subagent-multi` are spawn (fresh). The keying routes by session, not by backend, so it is already correct for fork. The script *derivation* was not: a fork child's log begins with the seeded parent prefix (the parent's `assistant/chunk` events), so deriving its script from the whole log would replay the parent's responses as the child's. That correctness gap is closed by persisting a seed boundary — see [Persist the seed boundary so fork-child replay routes correctly](2026-06-22-fork-child-replay-seed-boundary.md) — and recorded fork + mixed spawn+fork scenarios now exercise both transports through one transcript (see [Record fork and mixed spawn+fork snapshot scenarios](../../archived/testing/2026-06-22-fork-snapshot-scenarios.md)).
-- Out-of-process (ACP) subagents are a different replay shape entirely (each child is its own PROCESS with its own replay), tracked as `TODO(acp-subagent-replay)` in the PR3 plan.
+- Out-of-process (ACP) subagents are a different replay shape entirely (each child is its own PROCESS with its own replay), tracked as `TODO(acp-subagent-replay)` in `subagent-acp`.
diff --git a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
index 1b90c1bda8..b96be12df0 100644
--- a/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-22-subagent-snapshot-replay.zh.md
@@ -13,7 +13,7 @@ Status: implemented
 - **`dsh-llm-replay` 没有做任何键控。** 它用一个全局游标，将第 N 次 `llm/stream` 调用对应到单一录制序列的第 N 条。当父 agent（智能体）和一个进程内 subagent 在同一个上下文上同时流式输出时，调用交错，单一游标会把子 agent 的脚本发给父 agent（反之亦然）。
 - **harness 只收集一份日志。** `findSessionLog` 遍历 sessions 根目录，返回找到的第一个 `.jsonl`。subagent 作为第二个 `Session` 运行并拥有自己的日志，因此子 agent 的 transcript（文本记录）被静默丢弃。
 
-这就是 [subagent seam Agent Note](../feature/2026-06-21-subagent-capability-seam.md)中通过 `TODO(subagent-snapshots)` 推迟的工作：进程内后端（PR2）落地时已有单元 + e2e 覆盖，但在这套基础设施落地前，完整 transcript 快照层无法表达嵌套 agent 形状。本 Agent Note 就是该堆叠式后续工作。
+这就是 [subagent seam Agent Note](../feature/2026-06-21-subagent-capability-seam.md)中通过 `TODO(subagent-snapshots)` 推迟的工作：进程内后端落地时已有单元 + e2e 覆盖，但在这套基础设施落地前，完整 transcript 快照层无法表达嵌套 agent 形状。
 
 ## 决策
 
@@ -55,4 +55,4 @@ Status: implemented
 - `TODO(subagent-snapshots)` 延期项已解决：嵌套 agent 的 transcript 现在是快照层的一等形态。
 - `GenerateOptions.sessionId` 是一个小而诚实的 core API 新增，在回放之外同样有用（遥测、请求路由）。
 - `subagent` 工具绑定到单一提供方，因此 `subagent-multi` 中的两个子 agent 都是 spawn（全新创建）。键控按会话路由而非按后端路由，因此对 fork 同样正确。但脚本*派生*逻辑此前不正确：fork 子会话的日志以种子化的父前缀（父会话的 `assistant/chunk` 事件）开头，如果从完整日志派生脚本，就会把父 agent 的响应当作子 agent 的来回放。这一正确性缺口通过持久化种子边界来弥合——见[持久化 seed 边界以确保 fork 子会话回放正确路由](2026-06-22-fork-child-replay-seed-boundary.md)——录制的 fork 与混合 spawn+fork 场景现在通过一份 transcript 同时验证两种传输方式（见[记录 fork 与混合 spawn+fork 快照场景](../../archived/testing/2026-06-22-fork-snapshot-scenarios.md)）。
-- 进程外（ACP（Agent Client Protocol））subagent 是完全不同的回放形态（每个子 agent 是自己的进程、有自己的回放），作为 `TODO(acp-subagent-replay)` 记录在 PR3 计划中。
+- 进程外（ACP（Agent Client Protocol））subagent 是完全不同的回放形态（每个子 agent 是自己的进程、有自己的回放），作为 `TODO(acp-subagent-replay)` 记录在 `subagent-acp` 中。
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
index dcd5119f92..4d710a9c55 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.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 .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
-2026-07-24-web-gui-browser-e2e-lane.md: aa289c9a70623904606e2d06b6492acb3a7d98a3
-2026-07-24-web-gui-browser-e2e-lane.zh.md: 9e26dcb53f0373ac967c627b95b895385784f925
+2026-07-24-web-gui-browser-e2e-lane.md: 84912895514f9dba4ff61bc8842444a81c5fbefa
+2026-07-24-web-gui-browser-e2e-lane.zh.md: 3c94b42d1b85190dfe6b3b8ebb14efb4624fd326
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
index aa289c9a70..8491289551 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md
@@ -72,7 +72,7 @@ Surveyed AI-chat/agent web UIs and mocking layers (LibreChat, vercel/ai-chatbot
 
 **Changing the wire protocol for testability.** Rejected: the contract already has a first-class keyless in-process path (`InProcessApiClient(toFetchHandler(api))`), the per-event unbatched SSE is exactly what makes replay observable in a browser, and testing a wire we no longer ship would invert the tier's purpose.
 
-**Real-model browser tests as the keyless lane.** Rejected: nondeterministic by construction; the surveyed cautionary case (open-webui) grew unbounded timeouts and was deleted. The with-key W5 smoke stays as the live-model complement.
+**Real-model browser tests as the keyless lane.** Rejected: nondeterministic by construction; the surveyed cautionary case (open-webui) grew unbounded timeouts and was deleted. The with-key real-host smoke stays as the live-model complement.
 
 **Running the high-cardinality performance case in the required browser gate.** Rejected: its fixture setup and full-history render add tens of seconds, while wall-clock and memory values vary with the host and cannot supply a stable correctness threshold. The required lane keeps deterministic behavior assertions; contributors run the diagnostic case when investigating or changing large-list and long-history rendering.
 
diff --git a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
index 9e26dcb53f..3c94b42d1b 100644
--- a/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
+++ b/.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md
@@ -72,7 +72,7 @@ Web GUI 以一条真实组装链交付——chromium 页面 → client 插件 bu
 
 **为可测试性改 wire 协议。** 已否决：约定已有第一等的无密钥进程内路径（`InProcessApiClient(toFetchHandler(api))`），逐事件不合批的 SSE 恰是回放在浏览器中可观测的原因，测试一条不再交付的 wire 会颠倒该层的存在意义。
 
-**以真实模型浏览器测试充当无密钥车道。** 已否决：按构造即不确定；被调研的前车之鉴（open-webui）长出无界超时后被删除。带密钥的 W5 冒烟仍是真实模型侧的补充。
+**以真实模型浏览器测试充当无密钥车道。** 已否决：按构造即不确定；被调研的前车之鉴（open-webui）长出无界超时后被删除。带密钥的真实 host 冒烟仍是真实模型侧的补充。
 
 **在必需的浏览器门禁中运行高基数性能用例。** 已否决：其 fixture 设置和完整历史渲染会增加数十秒耗时，而壁钟时间和内存值随 host 不同而变化，无法提供稳定的正确性阈值。必需车道保留确定性行为断言；贡献者在调查或更改大列表和长历史渲染时运行该诊断用例。
 
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
index 29932b1d06..648d77d482 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.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 .agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
-2026-06-16-typed-event-schemas.md: d919db18f347d0633155f92bfecc43b8bf846659
-2026-06-16-typed-event-schemas.zh.md: 369a70846265035d92bf51fcd516793b648e2f0f
+2026-06-16-typed-event-schemas.md: c2cff264c7b766d4040d3f7588d436eb7b08140a
+2026-06-16-typed-event-schemas.zh.md: 5998be3cea98e1937eb7fe1298cb252cbf3ee171
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
index d919db18f3..c2cff264c7 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
@@ -15,8 +15,6 @@ The pattern is **compile-time only**. The types vanish at runtime: there is no s
 
 This raises whether the event vocabulary should move to **Zod** or another runtime-schema library so durable and plugin boundaries have runtime schemas rather than erased types.
 
-This Agent Note scopes that question without proposing an implementation.
-
 ## Why this is not a persistence change
 
 It is tempting to read "use Zod for serialization" as a local change to `dsh-session-persistence-jsonl/src/format.ts`. It is not, for one structural reason: **a plugin cannot declaration-merge a Zod schema.** Declaration merging is a TypeScript compile-time mechanism; a Zod schema is a runtime value. To validate events with Zod you need a **runtime registry** that every event-producing package contributes its schema to (e.g. `ctx.sessionEvents.register('compaction/marker', z.object({…}))`), and every consumer reads from. That registry — not the persistence backend — becomes the source of truth for the vocabulary, replacing the merge-extensible interface.
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
index 369a708462..5998be3cea 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.zh.md
@@ -15,8 +15,6 @@ harness 将其核心词汇——内容块、消息来源、结束原因、轮次
 
 由此引出问题：事件词汇是否应迁移到 **Zod** 或其他运行时 schema 库，使持久化边界和插件边界拥有运行时 schema 而非被擦除的类型。
 
-本 Agent Note 界定该问题的范围，不提出具体实现。
-
 ## 为什么这不是一个持久化层的改动
 
 很容易把「用 Zod 做序列化」理解为对 `dsh-session-persistence-jsonl/src/format.ts` 的局部修改。但它不是，原因在于一个结构性事实：**插件无法对 Zod schema 进行声明合并。** 声明合并是 TypeScript 编译期机制；Zod schema 是运行时值。要用 Zod 校验事件，就需要一个**运行时注册表**，每个产出事件的包向其贡献自己的 schema（如 `ctx.sessionEvents.register('compaction/marker', z.object({…}))`），每个消费方从中读取。这个注册表——而非持久化后端——将成为词汇的真源，取代 merge-extensible 接口。
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
index 6b3b6cafb3..b3ef015459 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.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 .agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
-2026-07-24-domain-kv-storage-and-workspace.md: 1cb2bc4b29c196dbb33292547c75d01a37f06772
-2026-07-24-domain-kv-storage-and-workspace.zh.md: ea537e0e5e5b02955d0b279d80822b0220f2b20b
+2026-07-24-domain-kv-storage-and-workspace.md: 2170534017ff81aeeb6c58ea04503b40ff5b5ee6
+2026-07-24-domain-kv-storage-and-workspace.zh.md: c619ab3e47d6a3dea383bc7b78c42a4b4240799f
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
index 1cb2bc4b29..2170534017 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md
@@ -8,7 +8,7 @@ English | [中文](2026-07-24-domain-kv-storage-and-workspace.zh.md)
 
 The host's only persistence surface is the session event log (`packages/session/session-persistence`: append-only, one file per session). Anything that does not belong to a single session has nowhere to live, and two real needs exist today:
 
-- **The workspace entity.** The GUI needs workspace as a real object: path, title, and the list of owned sessions. Ownership belongs to the workspace — "which sessions belong to this workspace" is not any single session's fact, so writing it into the session log is semantically wrong. Until now workspace was only a sidebar visual grouping derived from cwd, with no entity (that conclusion has been overturned).
+- **The workspace entity.** The GUI needs workspace as a real object: path, title, and the list of owned sessions. Ownership belongs to the workspace — "which sessions belong to this workspace" is not any single session's fact, so writing it into the session log is semantically wrong. Before this design, workspace was only a sidebar visual grouping derived from cwd, with no entity.
 - **Dynamic session metadata** (the foreseeable second consumer). Cold session listings read only the first log line (an immutable creation-time snapshot); title, terminal status, and anything that evolves with the session is unavailable. The fix direction is a sidecar metadata table — exactly a KV table with high-frequency per-key updates.
 
 Separately, Session deletion needs a `SessionPersistence` delete primitive and a `session.delete` endpoint. That gap's design is settled in this note, but its implementation remains future work.
@@ -310,7 +310,7 @@ Snapshots: no model-visible or assembly surface this phase, none added; next pha
 - **SQLite storing a whole domain as one blob row**: any single-record change rewrites the whole domain, forfeiting per-key precise updates — SQLite's only edge over JSON reduced to zero.
 - **SQLite generating typed columns from the schema**: a DDL generator is over-engineering; document-per-row suffices, revisit when real query needs appear.
 - **One sqlite db file per domain**: contrary to the repository's one-database-many-tables convention.
-- **A single whole-store backend choice (the session-persistence single-slot pattern)**: the initial design; changed to coexisting backends + configured routing because the hub will carry multiple data forms whose backend preferences (human-readable vs high-frequency point updates) are bound to diverge — a single slot forces the coarse "swap everything + hand-migrate data" move. The cost is one extra name lookup, backed by fail-loud.
+- **A single whole-store backend choice (the session-persistence single-slot pattern)**: rejected — the hub will carry multiple data forms whose backend preferences (human-readable vs high-frequency point updates) are bound to diverge, and a single slot forces the coarse "swap everything + hand-migrate data" move. The cost is one extra name lookup, backed by fail-loud.
 - **path as the workspace key**: normalization/symlink resolution rewrites the path; reference anchors must be stable.
 - **Ownership derived from cwd (or merged with the ledger)**: two sources of truth; cwd cannot express ordering; ownership is a workspace-side fact to begin with.
 - **Change events carrying the old value**: the repository's change-event convention is "new snapshot + operation discriminant" (the sole exception, fs's before/after, is a method return value rather than an event, because the old value is unrecoverable afterwards and has a diff consumer); consumers needing diffs hold their own previous snapshot.
diff --git a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
index ea537e0e5e..c619ab3e47 100644
--- a/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md
@@ -8,7 +8,7 @@ Status: proposed
 
 host 侧唯一的持久化面是 session 事件日志（`packages/session/session-persistence`：仅追加、一 session 一文件）。凡是"不属于某个 session"的信息就没有落盘处，眼下有两个真实需求：
 
-- **workspace 实体**。GUI 要把 workspace 做成真实对象：路径、标题、关联 session 清单。归属关系由 workspace 持有——"哪些 session 属于这个 workspace"不是任何单个 session 自己的事实，塞进 session log 语义不成立。此前 workspace 只是 sidebar 上按 cwd 分组的视觉概念，没有实体（该结论已被推翻）。
+- **workspace 实体**。GUI 要把 workspace 做成真实对象：路径、标题、关联 session 清单。归属关系由 workspace 持有——"哪些 session 属于这个 workspace"不是任何单个 session 自己的事实，塞进 session log 语义不成立。在本设计之前，workspace 只是 sidebar 上按 cwd 分组的视觉概念，没有实体。
 - **session 动态元信息**（可预见的第二个消费方）。冷会话列表只读日志首行 header（创建时的不可变快照），title、结束状态这类随会话推进变化的信息拿不到；补齐方向是 sidecar 元数据表——正是一张按 key 高频点更新的 KV 表。
 
 另外，Session 删除需要 `SessionPersistence` 删除原语和 `session.delete` 端点。该空白的设计随本 Note 定案，但实现仍属未来工作。
@@ -305,7 +305,7 @@ export class WorkspaceRegistry extends Service {
 - **复用 session-persistence 的 coordinator/后端**：事件日志语义（仅追加、turn 崩溃修复、懒物化）与 KV 覆写语义不匹配；只借其分层思想（协调层持写序、后端只实现最小原语）。
 - **workspace 专用存储包，后续再抽 seam**：第二个消费方（session sidecar）已可预见，届时泛化要再动一次接口。
 - **domain 与 storage 合为一层**：后端会被迫接触 schema 校验、变更事件、写串行等领域关切；拆开后 storage 后端只做不透明原语（可替换面最小），domain 单实现收敛全部领域逻辑（zod/事件/串行化只写一遍，不随后端翻倍）。
-- **整库单后端二选一（学 session-persistence 单 slot 模式）**：曾是初版方案；改为多后端并存 + 配置路由，因为存储枢纽要承载多种数据形式，不同形式/域对后端的偏好（肉眼可读 vs 高频点更新）注定分化，单 slot 会逼出"整体换挂 + 手工导数据"的粗粒度动作。代价是按名查找多一步，fail-loud 兜底。
+- **整库单后端二选一（学 session-persistence 单 slot 模式）**：否决——存储枢纽要承载多种数据形式，不同形式/域对后端的偏好（肉眼可读 vs 高频点更新）注定分化，单 slot 会逼出"整体换挂 + 手工导数据"的粗粒度动作。代价是按名查找多一步，fail-loud 兜底。
 - **JSON 后端 jsonl 追加 + 墓碑 + 压实（compaction）**：temp+fsync+rename 的崩溃安全与 append 等价；覆写让文件永远是净值、肉眼可读，免掉折叠／压实／断行容错。域规模下整写与追加一行同量级。
 - **JSON 一表一文件**：覆写下文件粒度不影响写成本，按域合并文件更少，global 单例有落点。
 - **SQLite 整域存单行 blob**：任何一条记录变更都重写整域，失去按 key 精确更新——SQLite 相对 JSON 的唯一优势归零。
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index c5910fb083..9538bdc5d5 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.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 .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
-2026-07-27-session-projection-and-command-log.md: 6c2c8137453d04ba6b631fe7f80a788a639b096b
-2026-07-27-session-projection-and-command-log.zh.md: f3370ea2631e9c9904c6fc996c2c8aff698c3830
+2026-07-27-session-projection-and-command-log.md: 01e77de47c7b5178ddc146e95487754a616639ec
+2026-07-27-session-projection-and-command-log.zh.md: 2de188bab9d51fb9d19f993653741a343f62e31c
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
index 6c2c813745..01e77de47c 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
@@ -143,13 +143,13 @@ Infrastructure first; the three in-flight PRs are left untouched and re-target a
 
 **A dedicated `session.projections` RPC** — rejected: baseline-refresh moments coincide exactly with tail-page pulls, so a separate unary buys a second round-trip, a second seq to reconcile, and a client-side "when to refetch" decision that the rider design deletes outright.
 
-**An opaque `get(agent)` provider contract** — rejected after being the first draft: with the computation model hidden inside the domain, the framework can never checkpoint the state, serve cold sessions (no agent, no loaded log — `get` has nothing to run against), or resume from a mid-log position. Registering the `(init, apply, view)` unit hands the framework the drive and keeps the domain to pure mathematics; a domain with host-side behavioral needs still keeps its own service subscriptions independently of the projection unit.
+**An opaque `get(agent)` provider contract** — rejected: with the computation model hidden inside the domain, the framework can never checkpoint the state, serve cold sessions (no agent, no loaded log — `get` has nothing to run against), or resume from a mid-log position. Registering the `(init, apply, view)` unit hands the framework the drive and keeps the domain to pure mathematics; a domain with host-side behavioral needs still keeps its own service subscriptions independently of the projection unit.
 
 **A live-only overlay hook (`live?(agent, base)`) for plan's pending intent** — rejected: it existed solely because the user's plan *selection* was not in the log. Routing the selection through the standard command channel puts `command/run` on the account, pending becomes a pure replay quantity, and the projection contract stays exactly three pure functions.
 
 **Naming the registration API `registerFold`** — superseded by the unit contract: the registered object now genuinely is a fold, but `fold*` in this repo names pure `(events) => state` helper functions while this registry accepts a keyed, schema'd, versioned unit. Projection remains the event-sourcing term for the read-model role, and both #587's note title and #497's comments already use it.
 
-**Client-side folding (per-domain projection cells with a `fromEvent`)** — rejected after being the second draft: once plan's unit folds two event types, a client cell must duplicate the host's transition logic in the browser — the same fold written twice, evolving separately. Pushing finished values (the title-frame precedent, generalized) keeps one computation site and reduces the client to a generic seq-guarded value store; domains write zero client code.
+**Client-side folding (per-domain projection cells with a `fromEvent`)** — rejected: once plan's unit folds two event types, a client cell must duplicate the host's transition logic in the browser — the same fold written twice, evolving separately. Pushing finished values (the title-frame precedent, generalized) keeps one computation site and reduces the client to a generic seq-guarded value store; domains write zero client code.
 
 **Bounded reverse scan over the log tail (absorber declarations)** — rejected for now: nothing supports it today, it only serves domains whose every event carries the full folded state, and the persisted projection cache covers the same cold-read need uniformly (cache row + forward tail replay — the same recipe as the client's baseline + catch-up, and as paged loading). Revisit only if a real cold-read path emerges that checkpointing cannot serve.
 
@@ -184,4 +184,4 @@ Infrastructure first; the three in-flight PRs are left untouched and re-target a
 - **Eager drive costs on busy sessions**: every committed event passes every registered unit's `apply`. Units are cheap per-event by construction (whole-value rule), non-matching events return the same reference, and the count of registered domains is small; if a hot path ever shows, per-unit event-type prefilters can be added without contract change.
 - **Projection payload growth**: every tail page carries every registered key. Payloads are whole values of UI-scale state (a todo list, a goal snapshot); if a future domain's value is large, per-key opt-out or lazy keys can be added to the request without changing the model.
 - **Command log volume**: two log-only events per slash command; bounded by human command frequency, negligible against chunk volume.
-- **Re-target churn**: three open PRs rebase onto a moved foundation. Accepted cost of infrastructure-first; the migration mapping section in the design ledger names each PR's keep/drop list.
+- **Re-target churn**: three open PRs rebase onto a moved foundation. Accepted cost of infrastructure-first.
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index f3370ea263..2de188bab9 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -143,13 +143,13 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 
 **专设一个 `session.projections` RPC**——不予采纳：基线刷新时刻与尾页拉取精确重合，单独的一元 RPC 只会换来第二次往返、第二个待调和的 seq，以及一个客户端「何时重取」决策——而搭载设计把这个决策整个删掉了。
 
-**不透明的 `get(agent)` 提供方约定**——曾是第一稿，后被否决：计算模型藏在领域内部时，框架永远无法为状态做检查点、无法服务冷会话（没有 agent、没有已加载的日志——`get` 无处可跑）、也无法从日志中段续算。注册 `(init, apply, view)` 单元把驱动权交给框架，领域只留纯数学；有 host 侧行为需求的领域，其服务订阅照旧自持，与投影单元互不牵连。
+**不透明的 `get(agent)` 提供方约定**——否决：计算模型藏在领域内部时，框架永远无法为状态做检查点、无法服务冷会话（没有 agent、没有已加载的日志——`get` 无处可跑）、也无法从日志中段续算。注册 `(init, apply, view)` 单元把驱动权交给框架，领域只留纯数学；有 host 侧行为需求的领域，其服务订阅照旧自持，与投影单元互不牵连。
 
 **为 plan 待定意图专设的仅实时叠加钩子（`live?(agent, base)`）**——不予采纳：它存在的唯一理由是用户的 plan *选择*不在日志里。让选择走标准命令通道后，`command/run` 上了账，待定态成为纯回放量，投影约定保持恰好三个纯函数。
 
 **把注册 API 命名为 `registerFold`**——已被单元约定取代：注册对象如今确实是一个折叠，但本仓库里 `fold*` 专指纯 `(events) => state` 辅助函数，而该注册表接收的是带 key、带 schema、带版本的单元。投影仍是事件溯源中指称读模型角色的术语，#587 的 Note 标题与 #497 的评论也都已在使用它。
 
-**客户端侧折叠（带 `fromEvent` 的按领域投影 cell）**——曾是第二稿，后被否决：一旦 plan 的单元要折叠两种事件，客户端 cell 就必须在浏览器里复刻 host 的状态转移逻辑——同一个折叠写两遍、各自演化。推送成品值（标题帧先例的泛化）保住唯一计算地点，并把客户端简化为一个由 seq 把守的通用值仓；领域零客户端代码。
+**客户端侧折叠（带 `fromEvent` 的按领域投影 cell）**——否决：一旦 plan 的单元要折叠两种事件，客户端 cell 就必须在浏览器里复刻 host 的状态转移逻辑——同一个折叠写两遍、各自演化。推送成品值（标题帧先例的泛化）保住唯一计算地点，并把客户端简化为一个由 seq 把守的通用值仓；领域零客户端代码。
 
 **对日志尾部的有界反向扫描（absorber 声明）**——暂不采纳：今天没有任何东西支持它，它只服务于「每个事件都携带完整折叠状态」的领域，而持久投影缓存以统一方式覆盖同一冷读需求（缓存行 + 正向尾部回放——与客户端的基线 + 追赶、与分页加载是同一套配方）。只有当出现检查点机制服务不了的真实冷读路径时才重议。
 
@@ -184,4 +184,4 @@ host 侧命令执行器（`packages/interaction/commands`）在调用处理器
 - **忙碌会话上的主动驱动开销**：每个已提交事件都要过每个已注册单元的 `apply`。按构造，单元的逐事件开销很低（全量值规则），不匹配的事件返回同一引用，且已注册领域的数量很小；若真出现热点路径，可以加按单元的事件类型预过滤，约定不变。
 - **投影载荷膨胀**：每个尾页携带每个已注册的 key。载荷是 UI 量级状态的全量值（一张 todo 清单、一份 goal 快照）；将来若某领域的值很大，可以在请求上加逐 key 的 opt-out 或惰性 key，模型本身不用改。
 - **命令日志体量**：每条斜杠命令两个仅日志事件；上限由人敲命令的频率决定，相对分片体量可忽略不计。
-- **重新对接的返工**：三个未合入的 PR 要变基到挪动后的地基上。这是基础设施先行的既定代价；设计台账中的迁移映射一节逐一列出每个 PR 的保留/删除清单。
+- **重新对接的返工**：三个未合入的 PR 要变基到挪动后的地基上。这是基础设施先行的既定代价。
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
index 2da4662891..8fd7d1dd91 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.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 .agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
-2026-07-28-storage-root-and-derived-medium-recovery.md: c7b423770fcca89c54d3866db7701348351cc259
-2026-07-28-storage-root-and-derived-medium-recovery.zh.md: e271373662e4decfd0663133fd811ee1b9247507
+2026-07-28-storage-root-and-derived-medium-recovery.md: 45e8b3dfcad0590a26581e20c7bc6bb5692e5c36
+2026-07-28-storage-root-and-derived-medium-recovery.zh.md: 330473b2b17669e373a6dc433a74d8bb3ba37628
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
index c7b423770f..45e8b3dfca 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.md
@@ -6,7 +6,7 @@ English | [中文](2026-07-28-storage-root-and-derived-medium-recovery.zh.md)
 
 ## Problem
 
-The persisted projection cache ([RFC](2026-07-27-session-projection-and-command-log.md), shipped as `dsh-session-projection-cache`) surfaced two gaps in the storage substrate it landed on. Both are properties of the domain-KV stack ([design](2026-07-24-domain-kv-storage-and-workspace.md)), not of the cache itself, and both bite the cache first because it is the first *derived* medium on that stack.
+The persisted projection cache ([note](2026-07-27-session-projection-and-command-log.md), shipped as `dsh-session-projection-cache`) surfaced two gaps in the storage substrate it landed on. Both are properties of the domain-KV stack ([design](2026-07-24-domain-kv-storage-and-workspace.md)), not of the cache itself, and both bite the cache first because it is the first *derived* medium on that stack.
 
 **Where the files actually live (root mismatch closed; resolve-once residual still open).** The shared base defaults the session store to the global harness home (`$DSH_HOME/sessions`, default `~/.dsh/sessions`), while the shipped Web overlay used to give the json backend the relative root `./.storages`: `workspace.json` and `session_projcache.json` landed under `<launch dir>/.storages/` — two launches from different directories shared their sessions yet saw different workspace registries and different projection caches, and the cache exists precisely to serve the cross-session cold listing, which missed for every session last cached under another launch directory. That mismatch is now closed: the overlay anchors `storage-json.root` to `$DSH_HOME/storages` with the same `!!js` expression the session root uses (`apps/cli/config/web.cordis.yml`). The residual hazard: `JsonStorageBackend` still never resolves its root — each unit open joins the path against whatever `process.cwd()` is at that moment (packages/storage/storage-json/src/index.ts); the shipped overlay root is already absolute and unaffected, but any relative root (bare Loader boots, tests) still splits on a later cwd change — the exact hazard the JSONL session backend resolves-once to prevent ("later process.cwd() changes cannot split one backend across roots", packages/session/session-persistence-jsonl/src/index.ts).
 
@@ -18,7 +18,7 @@ Two independent changes, one per gap.
 
 ### One global storage root (shipped, amended form); resolved once at construction (still open)
 
-- **Shipped**: the Web overlay anchors `storage-json.root` to `$DSH_HOME/storages` directly in the row through the app-boot-provided `dshHomePath('storages')` (`~/.dsh/storages` by default, beside `~/.dsh/sessions`; no leading dot — the home is already a hidden tree). The helper delegates to the canonical `dsh-paths` resolver, and the session root uses the same function without duplicating its fallback and tilde rules. The user ruled the per-row form in over this section's original launcher-patch + `storageRoot` profile key (see Alternatives); per-row overrides ride the personal `~/.dsh/config.yaml` patch layer. The web e2e scaffold already patches the row to an absolute temp root, so tests never touch the user's home.
+- **Shipped**: the Web overlay anchors `storage-json.root` to `$DSH_HOME/storages` directly in the row through the app-boot-provided `dshHomePath('storages')` (`~/.dsh/storages` by default, beside `~/.dsh/sessions`; no leading dot — the home is already a hidden tree). The helper delegates to the canonical `dsh-paths` resolver, and the session root uses the same function without duplicating its fallback and tilde rules. The per-row form was chosen (user decision) over a launcher patch + `storageRoot` profile key (see Alternatives); per-row overrides ride the personal `~/.dsh/config.yaml` patch layer. The web e2e scaffold already patches the row to an absolute temp root, so tests never touch the user's home.
 - **Still open**: `JsonStorageBackend` resolves its configured root once at construction (`resolve(config.root)`), adopting the JSONL backend's recorded rationale verbatim: a later `process.cwd()` change must not split one backend across roots. The SQLite storage backend already resolves its path.
 - Pre-release stance applies (and was executed): no migration shim. A deployment that cached under `<cwd>/.storages` re-derives everything (workspace re-bootstraps from the header index; the projection cache refolds lazily) or moves the two json files by hand once.
 
@@ -33,7 +33,7 @@ Two independent changes, one per gap.
 
 **Keep per-launch-directory `.storages` (the pre-change status quo)** — rejected: sessions are global, so every derived-from-sessions medium splits against its own source of truth; the cache's motivating scenario (one listing over all sessions) structurally misses rows, and the workspace registry indexes sessions it cannot see from another launch directory.
 
-**Launcher patch + a `storageRoot` profile key (this section's original form)** — not taken: one `!!js` yml expression reaches the global root with the same layering the session root already has; a launcher patch adds a second rewrite point, and the profile key is an empty seat until a real consumer exists (per-row overrides already have the personal config.yaml patch layer).
+**Launcher patch + a `storageRoot` profile key** — not taken: one `!!js` yml expression reaches the global root with the same layering the session root already has; a launcher patch adds a second rewrite point, and the profile key is an empty seat until a real consumer exists (per-row overrides already have the personal config.yaml patch layer).
 
 **Patch only the projection cache's route to a global root, leave `workspace.json` per-cwd** — rejected: the workspace registry has the identical global-vs-cwd mismatch, and the user decision that shaped the cache placed it deliberately beside `workspace.json` — one hub root keeps the media co-located and the mental model single.
 
diff --git a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
index e271373662..330473b2b1 100644
--- a/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-28-storage-root-and-derived-medium-recovery.zh.md
@@ -6,7 +6,7 @@ Status: proposed
 
 ## 问题
 
-持久投影缓存（[RFC](2026-07-27-session-projection-and-command-log.md)，已作为 `dsh-session-projection-cache` 落地）暴露了它所依托的存储基座的两个缺口。二者都是 domain-KV 栈（[设计](2026-07-24-domain-kv-storage-and-workspace.md)）的属性而非缓存自身的问题，且都首先咬到缓存——因为它是这条栈上第一个*派生*介质。
+持久投影缓存（[决策记录](2026-07-27-session-projection-and-command-log.md)，已作为 `dsh-session-projection-cache` 落地）暴露了它所依托的存储基座的两个缺口。二者都是 domain-KV 栈（[设计](2026-07-24-domain-kv-storage-and-workspace.md)）的属性而非缓存自身的问题，且都首先咬到缓存——因为它是这条栈上第一个*派生*介质。
 
 **文件到底存在哪（根错位已收口，resolve-once 残余仍开放）。** 共享 base 将会话存储默认为全局 harness home（`$DSH_HOME/sessions`，默认 `~/.dsh/sessions`），而出厂 Web overlay 曾给 json 后端相对根 `./.storages`：`workspace.json` 和 `session_projcache.json` 落在 `<启动目录>/.storages/` 下——从两个不同目录启动，会话相同，工作区注册表和投影缓存却各是一份，而缓存存在的意义恰恰是跨会话冷列表，凡上次在别的启动目录下缓存过的会话全部 miss。这一错位已消除：overlay 现以与会话根同一段 `!!js` 表达式把 `storage-json.root` 锚定到 `$DSH_HOME/storages`（`apps/cli/config/web.cordis.yml`）。残余隐患：`JsonStorageBackend` 仍从不 resolve 根——每次打开 unit 都把路径 join 到当时的 `process.cwd()` 上（packages/storage/storage-json/src/index.ts）；出厂 overlay 的根已是绝对路径不受影响，但任何相对根（裸 Loader 启动、测试）仍会被后续 cwd 变化劈开，JSONL 会话后端用「构造时 resolve 一次」防住的正是它（"later process.cwd() changes cannot split one backend across roots"，packages/session/session-persistence-jsonl/src/index.ts）。
 
@@ -18,7 +18,7 @@ Status: proposed
 
 ### 全局唯一存储根（已落地，形态修正）；构造时 resolve 一次（仍开放）
 
-- **已落地**：出厂 Web overlay 通过 app-boot 提供的 `dshHomePath('storages')`，直接在 `storage-json` 行内把 `root` 锚定到 `$DSH_HOME/storages`（默认 `~/.dsh/storages`，与 `~/.dsh/sessions` 并肩；目录名不带点——home 本身已是隐藏树）。该辅助函数委托给规范的 `dsh-paths` 解析器，会话根也使用同一个函数，无需重复其回退和波浪号规则。用户拍板采用这种按行形态取代本节初版的「launcher patch + `storageRoot` profile 键」（见 Alternatives）；按行覆盖仍走个人 `~/.dsh/config.yaml` patch 层。web e2e scaffold 本就把该行 patch 到临时绝对根，测试不触用户 home。
+- **已落地**：出厂 Web overlay 通过 app-boot 提供的 `dshHomePath('storages')`，直接在 `storage-json` 行内把 `root` 锚定到 `$DSH_HOME/storages`（默认 `~/.dsh/storages`，与 `~/.dsh/sessions` 并肩；目录名不带点——home 本身已是隐藏树）。该辅助函数委托给规范的 `dsh-paths` 解析器，会话根也使用同一个函数，无需重复其回退和波浪号规则。最终选用按行形态（用户决定）而非「launcher patch + `storageRoot` profile 键」（见 Alternatives）；按行覆盖仍走个人 `~/.dsh/config.yaml` patch 层。web e2e scaffold 本就把该行 patch 到临时绝对根，测试不触用户 home。
 - **仍开放**：`JsonStorageBackend` 在构造时对配置根 `resolve` 一次，原样采纳 JSONL 后端已记录的理由：后续 `process.cwd()` 变化不得把一个后端劈到多个根下。SQLite 存储后端已经 resolve 其路径。
 - 适用 pre-release 立场（已按此执行）：不做迁移垫片。曾在 `<cwd>/.storages` 下缓存过的部署要么全部重新派生（工作区从 header 索引重新 bootstrap；投影缓存惰性重折），要么手动把两个 json 文件挪一次。
 
@@ -33,7 +33,7 @@ Status: proposed
 
 **保持按启动目录的 `.storages`（改动前现状）**——拒绝：会话是全局的，所以每个从会话派生的介质都与自己的真源劈叉；缓存的动机场景（一次列出全部会话）结构性丢行，工作区注册表索引着从另一个启动目录看不见的会话。
 
-**launcher patch + `storageRoot` profile 键（本节初版提案形态）**——未采：一行 yml `!!js` 表达式即达全局根，与会话根的既有分层完全一致；launcher patch 多引入一个改写点，profile 键在有真实消费者前是空席（按行覆盖已有个人 config.yaml patch 层可用）。
+**launcher patch + `storageRoot` profile 键**——未采：一行 yml `!!js` 表达式即达全局根，与会话根的既有分层完全一致；launcher patch 多引入一个改写点，profile 键在有真实消费者前是空席（按行覆盖已有个人 config.yaml patch 层可用）。
 
 **只把投影缓存的 route 指到全局根，`workspace.json` 留在 per-cwd**——拒绝：工作区注册表有一模一样的全局 vs per-cwd 错位，而且塑造缓存的用户决策就是刻意把它放在 `workspace.json` 旁边——一个 hub 根让介质同址、心智模型单一。
 
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
index aa6add0de4..cacf90bfa6 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.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 .agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
-2026-07-06-recallable-compaction.md: 5fd26dd2d4086dd6f834f7bdb3194b0ad16db1eb
-2026-07-06-recallable-compaction.zh.md: 25ce6ca50d1755e3a90dbadb35d027c95262e5a4
+2026-07-06-recallable-compaction.md: 1d62f18c0b63257b45f55ad389a94eae4471f920
+2026-07-06-recallable-compaction.zh.md: e53e669b6111f10701353448927c5e37f4e13e0b
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
index 5fd26dd2d4..1d62f18c0b 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.md
@@ -65,7 +65,7 @@ The design ships as a new backend `dsh-compact-recallable` on the existing `ctx.
 
 ### Follow-ups
 
-Specified during review, deferred until observation calls for them:
+Deferred until observation calls for them:
 
 - Guard degradation ladder (code-only rollup of the oldest stub prefix, footers preserved, rolled-up ids remain recall targets; then one summary after the frozen boundary) — on observed guard livelock or stub-region pressure.
 - Echo detection on stub outputs (sentence-scale n-grams, short literals exempt, retry then strip) — on observed division-of-labor leakage.
diff --git a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
index 25ce6ca50d..e53e669b61 100644
--- a/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
+++ b/.agents/notes/proposed/feature/2026-07-06-recallable-compaction.zh.md
@@ -65,7 +65,7 @@ Status: proposed
 
 ### 后续事项
 
-以下项目在评审期间已经明确，但会延后至观察结果证明需要时再实现：
+以下项目延后至观察结果证明需要时再实现：
 
 - 保护逻辑降级阶梯（通过代码汇总最早的存根前缀，保留页脚，已汇总 id 仍可作为回溯目标；随后在冻结边界后生成一份摘要）：触发条件是观察到保护逻辑活锁或存根区域压力。
 - 存根输出回声检测（句子级 n-gram，豁免短字面量；先重试，再剥离）：触发条件是观察到职责分工泄漏。
diff --git a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml
index f364456257..5be65aaf06 100644
--- a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.i18n.yaml
+++ b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.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 .agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md
-2026-08-01-windows-pwsh-default.md: 1c3ccef23bb5cd9bc37237bd69aac2e2c56649a8
-2026-08-01-windows-pwsh-default.zh.md: d9fcc50a36a86b356fdf8507f53226d87dddc7bc
+2026-08-01-windows-pwsh-default.md: 64d713aecda60d8747199aff5334a80bf1867d92
+2026-08-01-windows-pwsh-default.zh.md: 74ba6c43dea984384a9b7dd2675b681ee025d6ca
diff --git a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md
index 1c3ccef23b..64d713aecd 100644
--- a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md
+++ b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.md
@@ -10,7 +10,7 @@ The harness's shipped execution profile is bash-first on every platform. Windows
 
 ## Proposal
 
-Two follow-up stages, each independently shippable. The former stage 2 (bash-tool parity twin) shipped with the [pwsh tool bash parity decision](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md): `tool-pwsh` now mirrors `tool-bash` for foreground and background work minus the sandbox surface, shares the `DSH_*` environment through `dsh-bash-env`, and carries a keyless application snapshot of its assembled surface.
+Two follow-up stages, each independently shippable. The bash-tool parity twin shipped with the [pwsh tool bash parity decision](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md): `tool-pwsh` now mirrors `tool-bash` for foreground and background work minus the sandbox surface, shares the `DSH_*` environment through `dsh-bash-env`, and carries a keyless application snapshot of its assembled surface.
 
 1. **Windows default composition** — the shipped CLI compositions mount `dsh-pwsh-local` as the `ctx.bash` executor and `dsh-tool-pwsh` as the model-facing shell tool on Windows hosts (bash unmounted there), while POSIX hosts keep the bash stack. This is a composition/roster decision in `base.cordis.yml` and the surface overlays, gated by platform; it makes the shipped Windows experience PowerShell-native end to end.
 2. **pwsh GUI rendering** — the Web surface renders pwsh calls with the bash-shaped terminal presentation (terminal card with exit-status pill), the counterpart of the bash terminal cards. Shipped in the [pwsh UI presentation matches bash decision](../../implemented/feature/2026-08-05-pwsh-ui-bash-parity.md) with a keyless web lane; the TUI was removed, so no terminal twin remains. A PowerShell-aware presentation beyond bash parity (native path display, `$env:` facts) remains unclaimed.
diff --git a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
index d9fcc50a36..74ba6c43de 100644
--- a/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
+++ b/.agents/notes/proposed/feature/2026-08-01-windows-pwsh-default.zh.md
@@ -10,7 +10,7 @@ harness 交付的执行配置在每个平台都是 bash 优先。Windows 主机
 
 ## 提案
 
-两个阶段，各自可独立交付。原阶段 2（bash 工具对等孪生）已随 [pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 交付：`tool-pwsh` 现在除 sandbox 接口外，在前台与后台工作方面均与 `tool-bash` 对齐，通过 `dsh-bash-env` 共享 `DSH_*` 环境，并携带其组装后形态的 keyless 应用快照。
+两个阶段，各自可独立交付。bash 工具对等孪生已随 [pwsh 工具与 bash 对齐决策](../../implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) 交付：`tool-pwsh` 现在除 sandbox 接口外，在前台与后台工作方面均与 `tool-bash` 对齐，通过 `dsh-bash-env` 共享 `DSH_*` 环境，并携带其组装后形态的 keyless 应用快照。
 
 1. **Windows 默认组合**——交付的 CLI（命令行界面）组合在 Windows 主机上挂载 `dsh-pwsh-local` 作为 `ctx.bash` 执行器、`dsh-tool-pwsh` 作为面向模型的 shell 工具（那里不挂载 bash），POSIX 主机保持 bash 栈。这是 `base.cordis.yml` 与 surface 覆盖层里按平台门控的组合/清单决策；它让交付的 Windows 体验端到端 PowerShell 原生。
 2. **pwsh GUI 渲染**——Web 界面使用 bash 风格的终端呈现来渲染 pwsh 调用（带胶囊状退出状态标签的终端卡片），与 bash 终端卡片相对应。已随 [pwsh UI 呈现与 bash 对齐决策](../../implemented/feature/2026-08-05-pwsh-ui-bash-parity.md) 及 keyless web 通道交付；TUI 已移除，不再有对应的终端界面。超出 bash 对齐的 PowerShell 感知呈现（原生路径显示、`$env:` 信息）仍无人认领。
diff --git a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml
index 37137ceebb..65ea0d5028 100644
--- a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.i18n.yaml
+++ b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.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 .agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
-2026-06-11-api-extractor-reports.md: 03f512992fe87ea3d0f8d51a1772ce1ec89a5c0d
-2026-06-11-api-extractor-reports.zh.md: e3b40f29908ebe1096a02dd4ee5f4886bb5a4537
+2026-06-11-api-extractor-reports.md: 9c6895f317719294d6eeb4d88a16c3426a2d5b3b
+2026-06-11-api-extractor-reports.zh.md: e62b6168efac5c8296b55ff8ee0c7861d1849d31
diff --git a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.md b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
index 03f512992f..9c6895f317 100644
--- a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
+++ b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.md
@@ -4,7 +4,7 @@ Status: proposed
 
 English | [中文](2026-06-11-api-extractor-reports.zh.md)
 
-> Split out from the original "Doc-sync and API reports" Agent Note (2026-06-11). Parts 1-2 (doc-block typechecking, event-taxonomy verification) shipped — see [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md). This is the deferred part 3, kept as a standalone proposal.
+> The doc-block-typechecking and event-taxonomy parts shipped ([doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)); this remaining API-report part is deferred as a standalone proposal.
 
 ## Problem
 
diff --git a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.zh.md b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.zh.md
index e3b40f2990..e62b6168ef 100644
--- a/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.zh.md
+++ b/.agents/notes/proposed/process/2026-06-11-api-extractor-reports.zh.md
@@ -4,7 +4,7 @@ Status: proposed
 
 [English](2026-06-11-api-extractor-reports.md) | 中文
 
-> 从最初的「doc-sync（文档同步门禁）与 API 报告」Agent Note 中拆出（首次提出于 2026-06-11）。第 1 至第 2 部分（文档块类型检查、事件分类体系校验）已交付，见 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)。本文是被推迟的第 3 部分，作为独立提案保留。
+> 文档块类型检查与事件分类体系两部分已交付（[doc-sync（文档同步门禁）强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)）；剩余的 API 报告部分作为独立提案被推迟。
 
 ## 问题
 
diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md
index 2df8d3774f..47b5725c18 100644
--- a/.agents/skills/dsh-doc-standards/SKILL.md
+++ b/.agents/skills/dsh-doc-standards/SKILL.md
@@ -29,7 +29,7 @@ Then check constraints that make placement expensive or wrong:
 
 - Paired docs (`pnpm run verify-translation-pairing --list`) cost a zh counterpart update and a `--write` re-record on every edit — prefer an unpaired home for content that will churn.
 - Generated catalogs are never hand-edited; if the fact belongs there, change the generator's source.
-- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings still need a manual grep when their output never reaches gate-scanned Markdown (today's three — `scripts/gen-doc-graphs.ts`, `scripts/gen-persistence-catalog.ts`, `packages/typert/generator/src/cordis-catalog.ts` — all render into scanned pages, so the gate catches them via the committed output).
+- Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings still need a manual grep when their output never reaches gate-scanned Markdown.
 - A move is atomic: remove from the old home, add to the new home, and fix every inbound link in the same change.
 
 ## Audit the corpus
diff --git a/.agents/skills/dsh-merging-stacked-prs/SKILL.md b/.agents/skills/dsh-merging-stacked-prs/SKILL.md
index 4bcb568955..964d20a4d8 100644
--- a/.agents/skills/dsh-merging-stacked-prs/SKILL.md
+++ b/.agents/skills/dsh-merging-stacked-prs/SKILL.md
@@ -9,7 +9,7 @@ Land dependent PRs through GitHub's native stack object and `gh stack merge`. Do
 
 ## Require native stack support
 
-Run `gh stack --version` before changing GitHub state. Hard-stop if the official extension or server-side stack feature is unavailable; do not fall back to the legacy manual landing procedure. GitHub stacks require every head branch to live in the same repository, so hard-stop on a cross-fork chain.
+Run `gh stack --version` before changing GitHub state. Hard-stop if the official extension or server-side stack feature is unavailable; do not fall back to manually merging and retargeting PRs one at a time. GitHub stacks require every head branch to live in the same repository, so hard-stop on a cross-fork chain.
 
 Use a clean dedicated worktree. Fetch current PR metadata and exact head OIDs rather than trusting branch names or an earlier report:
 
diff --git a/.agents/skills/dsh-translate-docs/SKILL.md b/.agents/skills/dsh-translate-docs/SKILL.md
index a3b95c59d1..e35096a5a2 100644
--- a/.agents/skills/dsh-translate-docs/SKILL.md
+++ b/.agents/skills/dsh-translate-docs/SKILL.md
@@ -19,7 +19,7 @@ Frozen Agent Notes under `.agents/notes/archived/` are not translation work. The
 
 ## The update path (briefing-driven)
 
-Benchmarked on real pair updates from this repo's history, the briefing-driven path costs a fraction of a guidance-corpus-loading run at equal measured quality; the [briefed-updates Agent Note](../../notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md) holds the evidence.
+The briefing-driven path matches guidance-corpus quality at a fraction of the cost; the [briefed-updates Agent Note](../../notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md) owns the benchmark evidence.
 
 1. **Generate the briefing**: `pnpm run gen-translation-brief <any file of the pair>` (no arguments briefs every out-of-sync pair). The briefing maps the change at the narrowest safely aligned granularity — changed Markdown units (paragraph, table row, list item, heading), then whole heading sections, then whole document — and contains the authored side's diff since the last confirmed-consistent state, each changed unit's last-confirmed source, current source, and current counterpart text (with line numbers), the terminology rows the change touches, first-occurrence movement notes, and a digest of the binding update rules.
 2. **Mechanical-only diff? `--apply` it.** When every change lies inside code fences that the pair shares byte-identically, the briefing says so; `pnpm run gen-translation-brief --apply <pair>` splices the edited fences into the counterpart and structure-validates the result before writing — no subagent, no hand-editing.
diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md
index e6d8c2658f..d7df478074 100644
--- a/.agents/skills/record-browser-gif/SKILL.md
+++ b/.agents/skills/record-browser-gif/SKILL.md
@@ -80,7 +80,7 @@ For a large artifact, reduce `--max-width` first, then `--colors` or `--fps`; re
 
 Perform this step only when the task includes attaching the GIF to a pull request.
 
-Never commit a GIF to the pull request's own branch or any branch that merges into a long-lived branch: binary media committed there bloats the repository history for every future clone. GIFs live on a dedicated orphan assets branch — a branch with no parent commit and nothing but media — and one assets branch serves a whole pull request series (existing branches: `code-mode-ui-assets`, `pr-613-assets`).
+Never commit a GIF to the pull request's own branch or any branch that merges into a long-lived branch: binary media committed there bloats the repository history for every future clone. GIFs live on a dedicated orphan assets branch — a branch with no parent commit and nothing but media — and one assets branch serves a whole pull request series (named `<series>-assets`; list existing ones with `git ls-remote --heads origin '*assets*'`).
 
 Before either workflow below pushes, verify that the assets branch contains media only and that the staged GIF's checksum matches the verified local artifact.
 
diff --git a/.github/issue-management/policy.mjs b/.github/issue-management/policy.mjs
index 09e1bbe7fd..c1a70c77da 100644
--- a/.github/issue-management/policy.mjs
+++ b/.github/issue-management/policy.mjs
@@ -20,7 +20,7 @@ const PR_KINDS = new Set([
   'kind/cleanup',
   'kind/dependency',
 ])
-// Aliases removed by the unified taxonomy migration remain reserved so they cannot be recreated.
+// Retired label aliases stay reserved so they cannot be recreated.
 const LEGACY_LABELS = new Set([
   'kind/bug',
   'kind/documentation',
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d017fa14fb..3f67929e26 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -834,10 +834,9 @@ jobs:
   all-checks-passed:
     name: all checks passed
     # This bookkeeping-only verdict must not depend on custom-pool
-    # provisioning (master's #734 moved it to ubuntu-latest) — and under
-    # failover it follows the same selector as the worker jobs it
-    # aggregates, so a standard-hosted outage cannot strand the
-    # branch-protection verdict either (observed 2026-07-27).
+    # provisioning — and under failover it follows the same selector as the
+    # worker jobs it aggregates, so a standard-hosted outage cannot strand
+    # the branch-protection verdict either.
     runs-on: >-
       ${{ vars.DSH_CI_FAILOVER == 'selfhosted'
           && github.event.pull_request.user.login != 'dependabot[bot]'
diff --git a/apps/cli/tests/args.spec.ts b/apps/cli/tests/args.spec.ts
index c9b3dc18f1..b8e1910a00 100644
--- a/apps/cli/tests/args.spec.ts
+++ b/apps/cli/tests/args.spec.ts
@@ -64,11 +64,11 @@ describe('parseDshArgs', () => {
       .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: true, patches: [] })
   })
 
-  it('rejects missing profile, removed flags, and contradictory inputs', () => {
+  it('rejects missing profile, flags outside the current grammar, and contradictory inputs', () => {
     expect(exitCode([])).toBe(1)
     expect(exitCode(['tui'])).toBe(1) // a bare word is a task without --profile
-    expect(exitCode(['--config', 'c.yml'])).toBe(1) // removed
-    expect(exitCode(['-p', 'task'])).toBe(1) // removed
+    expect(exitCode(['--config', 'c.yml'])).toBe(1) // outside the current grammar
+    expect(exitCode(['-p', 'task'])).toBe(1) // outside the current grammar
     expect(exitCode(['--profile', 'headless', 'task'])).toBe(1) // tasks belong to `run`
     expect(exitCode(['run'])).toBe(1)
     expect(exitCode(['run', ''])).toBe(1)
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index de44b110a1..0d2971ec62 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -174,7 +174,7 @@ function createEnvironmentProbeProfile(home: string, project: string): void {
 }
 
 describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)', () => {
-  it('requires --profile and rejects removed commands', async () => {
+  it('requires --profile and rejects inputs outside the current grammar', async () => {
     const bare = await runBuiltBin()
     expect(bare.code).toBe(1)
     expect(bare.stdout).toBe('')
@@ -185,8 +185,8 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     expect(help.stdout).toContain('dsh run "run the tests"')
     expect(help.stdout).toContain('dsh plugin --profile')
     expect(help.stdout).not.toMatch(/^\s+(?:tui|meta|upgrade)\b/mu)
-    for (const removed of [['tui'], ['--config', 'x.yml'], ['-p', 'task'], ['--profile', 'headless', 'task']]) {
-      const result = await runBuiltBin(removed)
+    for (const outsideGrammar of [['tui'], ['--config', 'x.yml'], ['-p', 'task'], ['--profile', 'headless', 'task']]) {
+      const result = await runBuiltBin(outsideGrammar)
       expect(result.code).toBe(1)
     }
   }, 30_000)
@@ -297,9 +297,9 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
   }, 30_000)
 
   it('reports a patch-overlay boot failure without hanging', async () => {
-    // The HMR main watcher's initial scan once refreshed the include
-    // mid-initial-apply, deadlocking the failing apply's rollback against the
-    // refresh drain: dsh exited 13 with no diagnostic instead of settling
+    // An HMR main-watcher initial scan that refreshes the include
+    // mid-initial-apply deadlocks the failing apply's rollback against the
+    // refresh drain: dsh exits 13 with no diagnostic instead of settling
     // ([Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md)).
     const home = mkdtempSync(join(tmpdir(), 'dsh-invalid-patch-'))
     try {
diff --git a/apps/web/tests/approval-composer.e2e.ts b/apps/web/tests/approval-composer.e2e.ts
index 33259b6ed2..9911742633 100644
--- a/apps/web/tests/approval-composer.e2e.ts
+++ b/apps/web/tests/approval-composer.e2e.ts
@@ -9,8 +9,8 @@
 // model content as the question composer: the turn cannot complete without it).
 //
 // Geometry is the point of the scenario. The command is unbounded model text,
-// and before the cap a long one grew the card until the refuse/allow buttons
-// left the viewport — an approval the user could see and not answer.
+// and an uncapped card grows with it until the refuse/allow buttons leave the
+// viewport — an approval the user could see and not answer.
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
@@ -36,8 +36,8 @@ const MODE = webSnapshotMode()
 
 // Irreducible payload: the command has to be long enough to pass the card's
 // height cap, which is the only shape that reproduces an action row pushed off
-// screen. Unrelated tokens, not a repeated word — a repeated word is what the
-// model compressed into `printf 'alpha %.0s' {1..400}` while recording, and a
+// screen. Unrelated tokens, not a repeated word — the model compresses a
+// repeated word into `printf 'alpha %.0s' {1..400}` when recording, and a
 // short command proves nothing here. The formula keeps the source small; the
 // model receives the expanded literal it has to put in the command.
 const TOKENS = Array.from({ length: 220 }, (_, index) => `tok${((index + 1) * 7919 % 99991).toString(36)}`).join(' ')
@@ -115,9 +115,8 @@ describe('web e2e: approval takeover keeps its actions reachable', () => {
       const snapshot = await captureStableAria(page, '[data-approval-key]', scaffold.workspaceCwd)
       await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
 
-      // The regression this scenario exists for: an uncapped card grew with
-      // the command until the action row left the viewport. Measured at the
-      // lane baseline and at a short viewport, on the live panel.
+      // The uncapped-card hazard the header names, measured at the lane
+      // baseline and at a short viewport, on the live panel.
       const original = page.viewportSize() ?? { width: 1680, height: 1000 }
       for (const height of [1000, 700]) {
         await page.setViewportSize({ width: 900, height })
diff --git a/apps/web/tests/chat-long-interactions.e2e.ts b/apps/web/tests/chat-long-interactions.e2e.ts
index cd1fcb2fa7..ad9d6a6874 100644
--- a/apps/web/tests/chat-long-interactions.e2e.ts
+++ b/apps/web/tests/chat-long-interactions.e2e.ts
@@ -1,6 +1,7 @@
-// Long-history Chat behavior contract for a future virtualized renderer. Wheel
-// input only navigates to the semantic target; assertions pin content identity
-// and interaction routing rather than scroll geometry or mounted row counts.
+// Long-history Chat behavior contract that stays valid under a virtualized
+// renderer: wheel input only navigates to the semantic target; assertions pin
+// content identity and interaction routing rather than scroll geometry or
+// mounted row counts.
 import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
diff --git a/apps/web/tests/code-mode-round.e2e.ts b/apps/web/tests/code-mode-round.e2e.ts
index fd103ac53d..051700dc35 100644
--- a/apps/web/tests/code-mode-round.e2e.ts
+++ b/apps/web/tests/code-mode-round.e2e.ts
@@ -26,7 +26,7 @@ const MODE = webSnapshotMode()
 
 // The scenario's one drive prompt: elicits one program with a bash sub-call
 // and a failing read the program tolerates — the sub-row set the assertions
-// (and the PR gif) need. Never asserted against model prose.
+// need. Never asserted against model prose.
 const PROMPT = 'Using ONE run_code program: run bash `echo CODE_ROUND_OK`, then read the file missing.txt '
   + 'catching its error in the program. Return an object with both outcomes. Then reply DONE and stop.'
 
@@ -104,7 +104,7 @@ describe('web e2e: Code Mode round renders nested sub-calls', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-code-mode-rows'))
     await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBeGreaterThanOrEqual(1)
     // The parent run_code row wears the code variant with the model-authored
-    // description as its summary (the PR1 presentCall contract).
+    // description as its summary (the presentCall contract).
     const codeRow = page.locator('[data-variant="code"]').first()
     await codeRow.waitFor({ timeout: 10_000 })
     // Nested rows are visible WITHOUT any expand interaction, inside the
diff --git a/apps/web/tests/composer-draft-scroll.e2e.ts b/apps/web/tests/composer-draft-scroll.e2e.ts
index 5013d2638a..687419dc53 100644
--- a/apps/web/tests/composer-draft-scroll.e2e.ts
+++ b/apps/web/tests/composer-draft-scroll.e2e.ts
@@ -8,7 +8,7 @@
 // `[data-input-backdrop]` div underneath it, which also carries the claim-token
 // highlight, the chips and the ghost hint.
 //
-// Two layers can only stay together by moving together. They now do: both sit
+// Two layers can only stay together by moving together. They do: both sit
 // inside `[data-input-scroll]`, the composer's single scrolling box, and are as
 // tall as the whole draft — so one offset, applied by the browser, moves the
 // caret and the words in the same frame. Scrolling the textarea and assigning
@@ -192,7 +192,7 @@ function measureComposer(page: Page): Promise<ComposerMetrics> {
  * Absolute glyph coordinates are deliberately absent: they depend on font
  * metrics and would make the fixture fail on a machine that measures text
  * differently — a golden that needs re-recording per platform documents the
- * platform, not the change. What is recorded is the cap, the caret-to-glyph
+ * platform, not the behavior. What is recorded is the cap, the caret-to-glyph
  * relation, and which lines are on screen, each a comparison that survives any
  * layout keeping the coupling.
  * @param top - metrics with the draft scrolled to its start.
@@ -297,10 +297,10 @@ describe('web e2e: composer draft scrolling', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-draft-scroll-wrap-width'))
     // A layer that breaks lines somewhere else puts the words under the wrong
     // caret, and an 8px difference is worth 2 to 5 lines on a wrap-sensitive
-    // draft. The three now share a containing block — the scrollport — so a
-    // scrollbar that consumes layout space costs them the same width; before,
-    // only the textarea scrolled, and WebKit reserved gutter space for it alone
-    // (768 against 776) while chromium and firefox did not.
+    // draft. All three share a containing block — the scrollport — so a
+    // scrollbar that consumes layout space costs them the same width; with
+    // only the textarea scrolling, WebKit reserves gutter space for it alone
+    // (768 against 776) while chromium and firefox do not.
     const metrics = await measureComposer(page)
     expect(metrics.backdropWrapWidth).toBe(metrics.inputWrapWidth)
     // The mirror decides the box height, so it belongs in the same equality —
@@ -315,7 +315,7 @@ describe('web e2e: composer draft scrolling', () => {
     // The reported symptom, isolated. A scroll offset changes and the caret's
     // distance to its own glyphs is re-read before the task ends — before any
     // `scroll` listener could have run. With the layers on one scrollport the
-    // browser moved both, so the distance is unchanged; with the glyph layer
+    // browser moves both, so the distance is unchanged; with the glyph layer
     // catching up in a listener it is off by the whole delta until a later
     // frame, which is a caret flying away from its text mid-gesture.
     const metrics = await measureComposer(page)
@@ -348,9 +348,10 @@ describe('web e2e: composer draft scrolling', () => {
   it('typing at the end of a scrolled draft brings the caret back into view', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-draft-scroll-edit'))
     // The other way the box moves, and the one that depends on the browser: the
-    // textarea no longer scrolls, so revealing the caret after an edit is a
-    // scroll-into-view that has to walk up to the scrollport. Scroll away from
-    // the caret first, so the edit has somewhere to bring it back from.
+    // textarea holds no scroll offset of its own, so revealing the caret after
+    // an edit is a scroll-into-view that has to walk up to the scrollport.
+    // Scroll away from the caret first, so the edit has somewhere to bring it
+    // back from.
     const input = page.locator('textarea:enabled').first()
     await input.press('End')
     await input.hover()
@@ -368,9 +369,9 @@ describe('web e2e: composer draft scrolling', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-draft-scroll-paste'))
     // The composer suppresses the native paste — the machine owns the draft and
     // the undo log — and restores the caret programmatically, which reveals
-    // nothing on its own: measured in chromium and WebKit, the view stayed
-    // where it was while the caret sat at the end of the pasted block. The
-    // restore now scrolls it into view, and this is the case that proves it.
+    // nothing on its own: in chromium and WebKit the view stays put while the
+    // caret sits at the end of the pasted block, so the restore scrolls it
+    // into view; this case pins it.
     const input = page.locator('textarea:enabled').first()
     await input.fill('one short line')
     await input.press('End')
diff --git a/apps/web/tests/composer-tab-geometry.e2e.ts b/apps/web/tests/composer-tab-geometry.e2e.ts
index c6b51b02bc..26077f6eab 100644
--- a/apps/web/tests/composer-tab-geometry.e2e.ts
+++ b/apps/web/tests/composer-tab-geometry.e2e.ts
@@ -11,12 +11,12 @@
 // gets an absolutely positioned seat instead, laid out against the padding box,
 // which the scrollbar never reduces.
 //
-// So the two tabs disagreed by exactly the bar's width for as long as the
-// transcript overflowed: the card jumped sideways on every tab switch, and
-// inside Chat alone at the moment a growing transcript started to scroll. The
-// column now reserves the gutter unconditionally (`scrollbar-gutter: stable`)
-// and states the overlay branch as a scroll container on the same axes, so both
-// edges are the same edge.
+// Without a shared reservation the two tabs disagree by exactly the bar's
+// width for as long as the transcript overflows: the card jumps sideways on
+// every tab switch, and inside Chat alone at the moment a growing transcript
+// starts to scroll. The column reserves the gutter unconditionally
+// (`scrollbar-gutter: stable`) and states the overlay branch as a scroll
+// container on the same axes, so both edges are the same edge.
 //
 // Only a real engine can show this. The seat's geometry is layout: jsdom gives
 // every element a zero-sized box and reports no scrollbar at all, so a unit spec
@@ -26,14 +26,14 @@
 //
 // The browser is launched WITHOUT Playwright's default `--hide-scrollbars`,
 // which is load-bearing rather than incidental. Under that argument a scroll
-// container's bar consumes no layout width at all, so the two tabs agree before
-// this change as much as after it and every comparison below holds vacuously —
-// measured: the pre-fix cascade leaves both tabs' bands at 0 there, against 8
-// and 0 with the argument dropped. Dropping it is also the faithful
+// container's bar consumes no layout width at all, so the two tabs agree with
+// and without the reservation and every comparison below holds vacuously —
+// measured: the unreserved cascade leaves both tabs' bands at 0 there, against
+// 8 and 0 with the argument dropped. Dropping it is also the faithful
 // configuration: ui-theme's scrollbar.css gives `::-webkit-scrollbar` a width,
 // and a bar that occupies layout space is what the product actually draws.
 //
-// The scenario runs that pre-fix cascade in the page — `scrollbar-gutter: auto`
+// The scenario runs that unreserved cascade in the page — `scrollbar-gutter: auto`
 // on the scroller, `overflow: hidden` on the overlay branch — and measures the
 // same two tabs through it, which is what keeps the equal rectangles above from
 // being explained by a tab switch that never reached the layout. It is the
@@ -64,7 +64,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/composer-tab-geometry',
  * that has to be re-recorded per platform. What is recorded is the distance
  * between the two tabs' rectangles, which is zero when the reservation holds and
  * the bar's width when it does not — including under the control, so the golden
- * carries the difference the fix removes rather than only its absence.
+ * carries the shift the unreserved cascade produces rather than only its absence.
  */
 const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
 const MODE = webSnapshotMode()
@@ -114,10 +114,10 @@ async function setMeasuredViewport(
 }
 
 /**
- * The pre-fix cascade, injected into the page: the reservation dropped and the
- * overlay branch back to a hidden box. `!important` beats the module rules
- * without a rebuild, and the id lets the control be lifted again in the same
- * session.
+ * The unreserved cascade, injected into the page: the reservation dropped and
+ * the overlay branch forced to a hidden box. `!important` beats the module
+ * rules without a rebuild, and the id lets the control be lifted again in the
+ * same session.
  */
 const CONTROL_STYLE_ID = 'composer-tab-geometry-control'
 const CONTROL_CSS = `
@@ -221,9 +221,9 @@ async function compareTabs(page: Page): Promise<TabComparison> {
 }
 
 /**
- * Run the pre-fix cascade in the page for one measurement, then lift it.
+ * Run the unreserved cascade in the page for one measurement, then lift it.
  * @param page - the page under test.
- * @returns the comparison as the column laid out before this change.
+ * @returns the comparison as the column lays out without the reservation.
  */
 async function compareTabsWithoutReservation(page: Page): Promise<TabComparison> {
   await page.evaluate(({ id, css }) => {
@@ -328,7 +328,7 @@ describe('web e2e: input card position across view tabs', () => {
     await expect.poll(async () => (await measureTab(page)).scrolls, { timeout: 10_000 }).toBe(true)
     const comparison = await compareTabs(page)
     expect(comparison.chat.band).toBeGreaterThan(0)
-    // The reservation reaches both states, which is the whole change: the same
+    // The reservation reaches both states, which is the whole point: the same
     // band, on a box that scrolls and on one that only holds a view.
     expect(comparison.chat.gutter).toBe('stable')
     expect(comparison.trajectory.gutter).toBe('stable')
@@ -348,8 +348,8 @@ describe('web e2e: input card position across view tabs', () => {
     await setMeasuredViewport(page, WIDE_VIEWPORT, false)
     const comparison = await compareTabs(page)
     // The reported symptom as a number. At this viewport the card sits at its
-    // width cap, so the pre-fix shift showed up as a centring difference — half
-    // the band on each edge — rather than as a width change.
+    // width cap, so the unreserved cascade's shift shows up as a centring
+    // difference — half the band on each edge — rather than as a width change.
     expect(comparison.leftShift).toBe(0)
     expect(comparison.rightShift).toBe(0)
     expect(comparison.widthShift).toBe(0)
@@ -363,7 +363,7 @@ describe('web e2e: input card position across view tabs', () => {
     await setMeasuredViewport(page, NARROW_VIEWPORT, true)
     const comparison = await compareTabs(page)
     // The other geometry, and a different failure: below the cap the card takes
-    // the column's width, so an unreserved gutter changed its WIDTH by the whole
+    // the column's width, so an unreserved gutter changes its WIDTH by the whole
     // band instead of shifting it by half. Asserted against the capped
     // measurement rather than against the cap's pixel value, which belongs to
     // the stylesheet.
@@ -379,17 +379,17 @@ describe('web e2e: input card position across view tabs', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-tab-geometry-control'))
     await setMeasuredViewport(page, WIDE_VIEWPORT, false)
     // The control: without it, equal rectangles could also mean the tab switch
-    // never reached the layout. Under the pre-fix cascade the Chat scroller keeps
-    // its bar and the Trajectory branch goes back to a hidden box with none, and
-    // the card moves by half the band on each edge.
+    // never reached the layout. Under the unreserved cascade the Chat scroller
+    // keeps its bar and the Trajectory branch becomes a hidden box with none,
+    // and the card moves by half the band on each edge.
     const comparison = await compareTabsWithoutReservation(page)
     expect(comparison.chat.gutter).toBe('auto')
     expect(comparison.chat.band).toBeGreaterThan(0)
     expect(comparison.trajectory.band).toBe(0)
     expect(comparison.leftShift).toBe(comparison.chat.band / 2)
     expect(comparison.rightShift).toBe(comparison.chat.band / 2)
-    // Restoring the sheet restores the fix, so the control cannot leak into the
-    // remaining measurements.
+    // Restoring the sheet restores the reservation, so the control cannot leak
+    // into the remaining measurements.
     const restored = await compareTabs(page)
     expect(restored.leftShift).toBe(0)
     expect(tripwire.pageErrors).toEqual([])
diff --git a/apps/web/tests/conversation-column-overflow.e2e.ts b/apps/web/tests/conversation-column-overflow.e2e.ts
index 97e1fd1fa2..fc51e0da34 100644
--- a/apps/web/tests/conversation-column-overflow.e2e.ts
+++ b/apps/web/tests/conversation-column-overflow.e2e.ts
@@ -1,15 +1,15 @@
 // Web e2e scenario: the conversation column scrolls on one axis only, as the
-// browser actually lays it out. The reported symptom was a horizontal
-// scrollbar under the whole center column once the window (or the sidebar
-// drag) narrowed it — the hero's decorative backdrop ellipse bleeding past the
-// column and becoming user-scrollable.
+// browser actually lays it out. The hazard: a horizontal scrollbar appears
+// under the whole center column once the window (or the sidebar drag) narrows
+// it — the hero's decorative backdrop ellipse bleeds past the column and
+// becomes user-scrollable.
 //
 // The bleed is by construction and stays: `.heroGlow` is sized 1051/776 of the
 // hero box (ConversationRoot.module.css) so the blur scales with the input
-// card. What changed is the scroll container: `[data-conversation-scroll]`
-// scrolls vertically, and a box that scrolls in one axis computes the other
-// axis's initial `visible` to `auto`, so the bleed came back as a bar. The
-// fix states `overflow-x: hidden` there.
+// card. The scroll container is where the bar comes from:
+// `[data-conversation-scroll]` scrolls vertically, and a one-axis scroller
+// computes the other axis's initial `visible` to `auto`, so the bleed becomes
+// a bar; `overflow-x: hidden` on the scroller prevents it.
 //
 // Only a real engine reports that pair — the bleed and the resulting scroll
 // range — so the scenario sweeps viewport widths that bracket the glow's
@@ -36,7 +36,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/conversation-column-over
  * Committed golden of the one-axis relation at every stop. It records
  * relations and booleans, never absolute coordinates: the column width follows
  * the viewport and the sidebar, and a golden carrying pixels would document the
- * platform instead of the change.
+ * platform instead of the behavior.
  */
 const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
 const MODE = webSnapshotMode()
@@ -60,17 +60,20 @@ interface ColumnMetrics {
   columnWidth: number
   /** Resolved `overflow-x` on the conversation scroll container. */
   overflowX: string
-  /** True when the glow's box reaches past the column's content edge — the condition the fix has to survive. */
+  /**
+   * True when the glow's box reaches past the column's content edge — the
+   * condition the `overflow-x: hidden` declaration has to survive.
+   */
   glowBleeds: boolean
   /**
    * `scrollWidth - clientWidth`. Deliberately NOT the assertion: `hidden` and
    * `auto` both report the same value, because `hidden` clips the bleed rather
    * than reflowing it away. Recorded because it is the vacuity guard in
    * numbers — it must stay positive at the narrow stops, or the scenario has
-   * stopped reproducing the situation the fix is for.
+   * stopped reproducing the situation `overflow-x: hidden` exists for.
    */
   bleedRange: number
-  /** True when the column still scrolls vertically — the axis the fix must not take away. */
+  /** True when the column still scrolls vertically — the axis `overflow-x: hidden` must not take away. */
   scrollsVertically: boolean
 }
 
@@ -108,9 +111,10 @@ function measureColumn(page: Page, width: number): Promise<ColumnMetrics> {
  * This is the one signal that separates the two states, and it is why the
  * scenario needs a real engine: `overflow-x: hidden` leaves the box
  * programmatically scrollable and leaves `scrollWidth` untouched, so every
- * property reading agrees across the fix. Only refusing an actual input event
- * differs — measured at the 1200px stop, the shipped column stays at 0 while
- * the same page with `overflow-x: auto` forced on lands at its scroll boundary.
+ * property reading agrees across the two overflow modes. Only refusing an
+ * actual input event differs — measured at the 1200px stop, the shipped
+ * column stays at 0 while the same page with `overflow-x: auto` forced on
+ * lands at its scroll boundary.
  * @param page - the page under test.
  * @returns `scrollLeft` after one horizontal wheel over the column.
  */
@@ -175,10 +179,10 @@ type ColumnStop = ColumnMetrics & {
  * Render the golden body: one line per stop, relations only.
  *
  * Absolute pixels are deliberately absent apart from `scrollLeftAfterWheel`,
- * which the fix pins to 0 by construction. The bleed is recorded as a boolean
- * rather than its width, so the golden survives any platform whose column
- * lands a pixel off — a fixture that has to be re-recorded per platform
- * documents the platform, not the change.
+ * which the shipped overflow mode pins to 0 by construction. The bleed is
+ * recorded as a boolean rather than its width, so the golden survives any
+ * platform whose column lands a pixel off — a fixture that has to be
+ * re-recorded per platform documents the platform, not the behavior.
  * @param stops - the measured stops, in sweep order.
  * @returns the golden body, without a trailing newline.
  */
@@ -272,18 +276,19 @@ describe('web e2e: the conversation column scrolls on one axis', () => {
       // The reported symptom, stated directly: a horizontal wheel over the
       // column moves nothing, at every stop.
       expect(stop.scrollLeftAfterWheel, `viewport ${String(stop.width)}`).toBe(0)
-      // The axis the column is a scroller for must survive the fix.
+      // The axis the column is a scroller for must survive `overflow-x: hidden`.
       expect(stop.scrollsVertically, `viewport ${String(stop.width)}`).toBe(true)
     }
     expect(tripwire.pageErrors).toEqual([])
   }, 120_000)
 
-  it('reports the pre-fix state when the axis is opened back up', async () => {
+  it('scrolls horizontally again once the axis is opened back up (control)', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-conversation-column-overflow-control'))
     // The mutation control, run in the page rather than against a second
-    // build: it restores exactly what the fix changed — the initial `visible`
-    // that a one-axis scroller computes to `auto` — and shows the same gesture,
-    // at the same timing, carrying the column to its positive scroll boundary.
+    // build: it lifts exactly the `overflow-x: hidden` declaration, so the
+    // initial `visible` that a one-axis scroller computes to `auto` takes
+    // over, and shows the same gesture, at the same timing, carrying the
+    // column to its positive scroll boundary.
     // Without it a `scrollLeft` of 0 could equally mean the wheel never arrived.
     // Injected with an id rather than through `addStyleTag`, so the teardown
     // below can take the sheet out again by selector: it must not outlive this
diff --git a/apps/web/tests/default-model.overlay.yml b/apps/web/tests/default-model.overlay.yml
index 5ec0e77405..654c343bb9 100644
--- a/apps/web/tests/default-model.overlay.yml
+++ b/apps/web/tests/default-model.overlay.yml
@@ -1,6 +1,6 @@
 # The fixture-less web scaffold registers no adapter, so the shipped
 # deepseek-official default would be a route nothing serves — which the
-# composer now correctly refuses to type into. This scenario declares its own
+# composer refuses to type into. This scenario declares its own
 # pi-ai routes and starts the default on one of them.
 - id: agent-default-model
   config:
diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index 5f2173248e..0c7dd36fe3 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -6,9 +6,10 @@
 // client; THIS spec pins the same flow through HTTP RPC + SSE + the host
 // gateway), reload replays everything from the log (zero further model
 // calls), and the theme scenario proves the shipped dark palette actually
-// cascades: attribute -> alias token flip -> painted surface change. Per the
-// lane's scope ruling there is no theme/layout golden (aria is color-blind);
-// the hero's waiting state gets the one golden here.
+// cascades: attribute -> alias token flip -> painted surface change. No
+// theme/layout golden: aria snapshots are color-blind (lane scope: the
+// browser-e2e-lane Agent Note); the hero's waiting state gets the one golden
+// here.
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
@@ -112,8 +113,8 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
       const planButton = activePage.getByRole('button', { name: 'Plan mode on, press to turn off' })
       await planButton.waitFor({ timeout: 10_000 })
       // The golden encodes an empty composer, and the button arriving does not
-      // mean the submitted text is gone yet: under load the capture caught a
-      // textbox still holding `/plan`.
+      // mean the submitted text is gone yet: under load the capture can catch
+      // a textbox still holding `/plan`.
       await expect.poll(() => input.inputValue(), { timeout: 10_000 }).toBe('')
       const planSnapshot = await captureStableAria(activePage, '[class*="frame"]', activeScaffold.workspaceCwd)
       await compareOrRefreshGolden(PLAN_ACTIVE_EXPECTED, planSnapshot, MODE)
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 53d5ef4982..364b00f9e5 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -85,8 +85,9 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     const key = dialog.getByLabel('API 密钥')
     const save = dialog.getByRole('button', { name: '保存', exact: true })
 
-    // The paste that used to save cleanly and then fail the first turn with a
-    // ByteString TypeError now names the field that holds it.
+    // A key no HTTP header can carry would save cleanly and fail the first
+    // turn with a ByteString TypeError; the form names the offending field
+    // instead.
     await key.fill('sk-\u{1F600}minimax')
     await dialog.getByText('该 API 密钥格式错误，请检查。').waitFor({ timeout: 10_000 })
     await expect.poll(async () => save.isEnabled(), { timeout: 10_000 }).toBe(false)
diff --git a/apps/web/tests/navigation-panes.e2e.ts b/apps/web/tests/navigation-panes.e2e.ts
index a49501584f..cc6d007d82 100644
--- a/apps/web/tests/navigation-panes.e2e.ts
+++ b/apps/web/tests/navigation-panes.e2e.ts
@@ -331,7 +331,7 @@ describe('web e2e: navigation & panes over a rich seeded session', () => {
     // Real layout, not jsdom's stub (which computes no geometry at all):
     // squeeze the output pane below its content width and the line must keep
     // its single row and overflow sideways instead of folding. Soft-wrapping
-    // here is what shredded the column alignment this card exists to hold.
+    // here shreds the column alignment this card exists to hold.
     const layout = await card.locator('[class*="_output_"]').first().evaluate((node) => {
       const pane = node as HTMLElement
       const row = pane.querySelector<HTMLElement>('[class*="_line_"]')
diff --git a/apps/web/tests/pin-browse-picker.overlay.yml b/apps/web/tests/pin-browse-picker.overlay.yml
index d48dfa3538..c6bf121b69 100644
--- a/apps/web/tests/pin-browse-picker.overlay.yml
+++ b/apps/web/tests/pin-browse-picker.overlay.yml
@@ -1,4 +1,4 @@
-# Loader overlay for the W5 real-host smoke (`dsh web --patch`): pin the
+# Loader overlay for the real-host smoke (`dsh web --patch`): pin the
 # in-browser directory picker. The shipped row is `-auto`, which resolves to
 # the native OS chooser on a loopback bind with a local display — an
 # interaction a Playwright page cannot drive, so the resolved backend would
diff --git a/apps/web/tests/pwsh-terminal.e2e.ts b/apps/web/tests/pwsh-terminal.e2e.ts
index 26f6a8319e..e1b92ed2e3 100644
--- a/apps/web/tests/pwsh-terminal.e2e.ts
+++ b/apps/web/tests/pwsh-terminal.e2e.ts
@@ -2,8 +2,8 @@
 // whose pwsh call/result is presented by the REAL tool-pwsh on replay (the
 // api-proxy recomputes presentation views from logged args/result content)
 // must render as a bash-shaped terminal card with the parsed exit-status
-// pill — not the generic console-fenced card the pwsh presenter used to
-// emit. The seed is authored, not recorded: its header line carries no `cwd`
+// pill — not a generic console-fenced card. The seed is authored, not
+// recorded: its header line carries no `cwd`
 // field (seedSession writes the session cwd itself, and a Windows temp path
 // substituted into the header would not round-trip through its JSON parse),
 // and no event references the workspace, so the lane replays on any host
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index 31a638c12e..4a922b9353 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -437,7 +437,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     } else if (mode !== 'record' && options.deepSeekMissingCredential !== true) {
       // No fixture and no shipped adapter would leave the tree with ZERO
       // provider routes — a state no product composition has, and one the
-      // composer now correctly refuses to type into. Register the same routes
+      // composer refuses to type into. Register the same routes
       // a fixture would, with streaming that still fails loud: the scenario
       // issues no model calls, and one that slipped in must not pass quietly.
       ctx.effect(() => ctx.llm.registerAdapter(
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index 8a9ee26866..14de0e8d8f 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -274,8 +274,8 @@ describe('web e2e: seeded history renders through cold resume', () => {
     const toolRows = page.locator('[data-variant], [data-sample]')
     await expect.poll(() => toolRows.count(), { timeout: 10_000 }).toBeGreaterThanOrEqual(2)
     expect(await page.getByText('a.txt', { exact: false }).count()).toBeGreaterThan(0)
-    // The bug this fixes: the compaction shadowed the whole recorded surface on
-    // the model side, and the prompt and full tool output are still on screen.
+    // The pinned hazard: compaction shadows the surface on the model side
+    // only — the prompt and full tool output must stay on screen.
     expect(await page.getByText(PROMPT, { exact: true }).count()).toBe(1)
 
     const agent = scaffold.ctx.agents.get(SessionId(SEED_ID))
diff --git a/apps/web/tests/settings-chrome.e2e.ts b/apps/web/tests/settings-chrome.e2e.ts
index e6b10664af..c49b1ecc1f 100644
--- a/apps/web/tests/settings-chrome.e2e.ts
+++ b/apps/web/tests/settings-chrome.e2e.ts
@@ -270,7 +270,7 @@ describe('web e2e: settings modal and General preferences', () => {
     await selector.click()
     await page.getByRole('menuitem', { name: 'English' }).click()
     // The settings-owned copy re-registers localized: dialog title, nav,
-    // Appearance labels. (Only the settings namespaces are localized today —
+    // Appearance labels. (Only the settings namespaces are localized —
     // the rest of the app's copy is intentionally out of this row's scope.)
     const enDialog = page.getByRole('dialog', { name: 'Settings' })
     await enDialog.waitFor({ timeout: 10_000 })
diff --git a/apps/web/tests/sidebar-scrollbar.e2e.ts b/apps/web/tests/sidebar-scrollbar.e2e.ts
index 095e667c61..d5afd925a3 100644
--- a/apps/web/tests/sidebar-scrollbar.e2e.ts
+++ b/apps/web/tests/sidebar-scrollbar.e2e.ts
@@ -1,5 +1,5 @@
 // Web e2e scenario: the sidebar session list's scrollbar as the browser
-// actually lays it out — the observable half of the themed-scrollbar change
+// actually lays it out — the observable half of the themed scrollbars
 // (packages/client/ui-theme/src/styles/scrollbar.css plus the
 // `scrollbar-gutter: stable` reservation on WorkspaceBrowser's `.list`). The
 // ui-theme/ui-workspace unit specs read the CSS text; only a real engine
@@ -17,8 +17,8 @@
 // Headless chromium defaults to an OVERLAY scrollbar: one drawn on top of the
 // content, consuming no layout width unless something reserves space. That is
 // the mode in which the reported symptom exists at all, so this environment
-// reproduces it rather than merely approximating it — measured against clean
-// master, where the list's band is 0 and the bar covers 7px of the relative
+// reproduces it rather than merely approximating it — without either
+// declaration the list's band is 0 and the bar covers 7px of the relative
 // time. (Under a classic space-consuming bar, `clientWidth` already excludes
 // the bar and nothing can be covered; a headed run under xvfb behaves that way
 // and cannot show the symptom.)
@@ -40,9 +40,8 @@
 // neither replaces the other. Removing only the gutter leaves `timeCoveredBy` at
 // 0, because the bar is then 8px wide and the row's right padding is also 8px,
 // so it abuts the timestamp without covering it; `band` catches that case.
-// Removing both — the actual master state — is what produces the reported
-// overlap, and `timeCoveredBy` measures it at 7. Each was mutation-checked with
-// the other assertions in its test silenced.
+// Removing both is what produces the reported overlap, and `timeCoveredBy`
+// measures it at 7.
 //
 // The thumb is a pointer affordance (ui-sidebar rebinds the indirection pair
 // to `transparent` while the pointer is outside the column), so every
@@ -135,7 +134,8 @@ interface ListMetrics {
 /**
  * Measure the sidebar list in the page.
  * @param page - the page under test.
- * @returns the list's resolved scrollbar style and the geometry the fix changes.
+ * @returns the list's resolved scrollbar style and the geometry the
+ * scrollbar-gutter/thin-scrollbar declarations shape.
  */
 function measureList(page: Page): Promise<ListMetrics> {
   return page.evaluate(() => {
@@ -201,8 +201,8 @@ function measureList(page: Page): Promise<ListMetrics> {
       // The bar is drawn in the rightmost `barWidth` of the border box, whether
       // or not that space was reserved. Its width comes from the sheet where the
       // sheet applies, and from the UA's own overlay bar otherwise — 15px is
-      // what this chromium paints, measured against master where the rule is
-      // absent. Taking the UA width as the fallback is what keeps the assertion
+      // what this chromium paints, measured with the rule absent. Taking the
+      // UA width as the fallback is what keeps the assertion
       // honest: assuming 0 there would report no occlusion precisely in the
       // state that has it.
       timeCoveredBy: Math.max(0, time.getBoundingClientRect().right - (listRect.right - barWidth)),
@@ -261,13 +261,14 @@ async function measurePalette(page: Page): Promise<PaletteMetrics> {
 
 /**
  * Render the golden body: the resolved scrollbar style of the list in each
- * palette, plus the geometric relations the fix establishes.
+ * palette, plus the geometric relations the scrollbar-gutter/thin-scrollbar
+ * declarations establish.
  *
  * Absolute coordinates are deliberately absent. `timeRight`, `clientRight`, and
  * `borderRight` depend on the sidebar's laid-out width and on font metrics, so
  * committing them would make the golden fail on a machine whose fonts measure
  * differently — a fixture that has to be re-recorded per platform documents the
- * platform, not the change. What is recorded instead is the band, the overlap,
+ * platform, not the behavior. What is recorded instead is the band, the overlap,
  * and the two orderings, each of which is a difference or a comparison and so
  * survives any layout that keeps the reservation.
  * @param light - metrics measured under the light palette.
@@ -417,12 +418,13 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum
     expect(metrics.scrollbarEdgeOffset).toBe(2)
     expect(metrics.rowEdgeInset).toBe(12)
     // The reported symptom, stated directly: no part of the row's relative time
-    // lies under the bar. Measures 7 on clean master — the `h` of `1h` is the
-    // covered part. Unlike the client-edge comparison below it does not go
-    // vacuous under an overlay scrollbar, because it measures against the bar's
-    // own width rather than against a content edge the overlay bar does not
-    // move. It is not a replacement for the band assertion above; see the file
-    // header for which regression each one catches.
+    // lies under the bar. Without either declaration it measures 7 — the `h`
+    // of `1h` is the covered part. Unlike the client-edge comparison below it
+    // does not go vacuous under an overlay scrollbar, because it measures
+    // against the bar's own width rather than against a content edge the
+    // overlay bar does not move. It is not a replacement for the band
+    // assertion above; see the file header for which regression each one
+    // catches.
     expect(metrics.timeCoveredBy).toBe(0)
     // Corollaries of the reservation, kept because they pin where the band sits
     // rather than only that it exists: the time ends inside the content area,
@@ -451,7 +453,7 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum
     expect(quiet.band).toBeGreaterThan(0)
     expect(quiet.timeCoveredBy).toBe(0)
     // Scrolling without a pointer — what a keyboard or a touch drag does —
-    // leaves the column quiet. This is the change's one deliberate loss, and
+    // leaves the column quiet. This is the one deliberate loss, and
     // it is pinned here rather than only described, so making a scroll
     // re-reveal the bar has to be a decision rather than a side effect.
     await page.locator('[role="tree"][aria-label="Sessions"]').evaluate((el) => { el.scrollTop += 200 })
diff --git a/apps/web/tests/smoke-real.e2e.ts b/apps/web/tests/smoke-real.e2e.ts
index f32daebfe4..b0acf074b4 100644
--- a/apps/web/tests/smoke-real.e2e.ts
+++ b/apps/web/tests/smoke-real.e2e.ts
@@ -1,4 +1,4 @@
-// W5 real-host smoke: spawn `dsh web` with a real key, walk the full W5 flow
+// Real-host smoke: spawn `dsh web` with a real key, walk the full flow
 // list in a real chromium, screenshot every screen into .artifacts/ for the
 // figma comparison pass. Self-skips without DEEPSEEK_API_KEY (repo e2e
 // convention); vitest.web.config.ts loads the repo-root .env before this file
@@ -11,8 +11,9 @@
 // (frame/handle) rides local names that survive hashing as suffixes; prefer
 // data-* for anything new.
 //
-// Flow order matters: chat rounds first (5 depends on 3's session), geometry
-// and theme after, reload recovery last. Tests run sequentially in-file.
+// Flow order matters: chat rounds first (the bash round reuses the first
+// send's session), geometry and theme after, reload recovery last. Tests run
+// sequentially in-file.
 import type { ChildProcess } from 'node:child_process'
 import { spawn } from 'node:child_process'
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
@@ -119,7 +120,7 @@ async function waitForAssistantMarker(baseUrl: string, sessionId: string, marker
   }).toBe(true)
 }
 
-/** W5 screenshot: evidence for the figma comparison, not a failure artifact. */
+/** Real-host smoke screenshot: evidence for the figma comparison, not a failure artifact. */
 async function screen(page: Page, name: string): Promise<void> {
   await page.screenshot({ path: join(REPO_ROOT, '.artifacts', `w5-${name}.png`) })
 }
@@ -465,7 +466,7 @@ describe('dsh web keyless CLI smoke', () => {
   })
 })
 
-describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke (real host, real key, W5)', () => {
+describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke (real host, real key)', () => {
   let child: ChildProcess
   let sessionsDir: string
   let baseUrl: string
@@ -518,7 +519,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     if (sessionsDir !== undefined) rmSync(sessionsDir, { recursive: true, force: true })
   })
 
-  it('1 cold start: loading page settles into the three-column frame', async () => {
+  it('cold start: loading page settles into the three-column frame', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-cold-start'))
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
     expect(await page.locator('text=Failed to load plugins').count()).toBe(0)
@@ -527,7 +528,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     await screen(page, '01-cold-start')
   })
 
-  it('2+3 empty-state first send completes a real model round', async () => {
+  it('empty-state first send completes a real model round', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-first-round'))
     // This scenario spawns its own server against a fresh $DSH_HOME, so the
     // first-run welcome notice is unacknowledged and its overlay owns pointer
@@ -590,7 +591,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     await screen(page, '07-back-to-chat')
   })
 
-  it('5 bash differential rendering: tool row click leaves the default details column closed', async () => {
+  it('bash differential rendering: tool row click leaves the default details column closed', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-tool-details'))
     const input = page.locator('textarea').first()
     await input.fill('请用 bash 工具运行命令 echo w5marker 然后告诉我结果')
@@ -604,12 +605,12 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     await screen(page, '08-bash-round')
     expect(await detailsTrack(page)).toBe(0)
     await toolRow.click()
-    // Tool rows no longer drive layout.openDetails; the default column stays closed.
+    // Tool rows do not drive layout.openDetails; the default column stays closed.
     expect(await detailsTrack(page)).toBe(0)
     await screen(page, '09-details-closed')
   }, 150_000)
 
-  it('6 sidebar drag widens the column and resets across reload', async () => {
+  it('sidebar drag widens the column and resets across reload', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-drag'))
     const before = await firstTrack(page)
     const handle = page.locator('[class*="handle"]').first()
@@ -627,10 +628,11 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     expect(await firstTrack(page)).toBe(before)
   })
 
-  it('7 dark mode: the body attribute cascades the token sheets', async () => {
+  it('dark mode: the body attribute cascades the token sheets', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-dark'))
-    // theme.apply === toggling this attribute (v3 §8); no switcher UI owns it
-    // in P-I, so the acceptance drives the documented mechanism directly.
+    // The body attribute is the documented cascade mechanism; the Settings
+    // gesture is owned by settings-chrome.e2e.ts — drive the attribute
+    // directly here.
     const dark = await page.evaluate(() => {
       document.body.setAttribute('data-ds-dark-theme', '')
       return getComputedStyle(document.body).backgroundColor
@@ -643,7 +645,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     expect(dark).not.toBe(light)
   })
 
-  it('8 reload recovery: history replays after a fresh boot', async () => {
+  it('reload recovery: history replays after a fresh boot', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-reload'))
     await page.reload({ waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
diff --git a/apps/web/tests/startup-auto-selection.e2e.ts b/apps/web/tests/startup-auto-selection.e2e.ts
index 21ad64e4ed..bf5f920458 100644
--- a/apps/web/tests/startup-auto-selection.e2e.ts
+++ b/apps/web/tests/startup-auto-selection.e2e.ts
@@ -3,10 +3,10 @@
 // A page load with a workspace already registered runs
 // `WorkspacesService.startInitialSelection`: it connects the most recent
 // workspace and opens its blank session. `openState` flips to `loading` the
-// moment `open()` lands, which used to drive `data-phase=settling` on the
-// conversation root — `visibility:hidden` over the composer seat and the
-// header for the whole `session.history` round-trip, so the center column went
-// blank and repainted, reading as a full-page refresh on every launch.
+// moment `open()` lands; driving `data-phase=settling` on the conversation
+// root from that flip would hide the composer seat and the header
+// (`visibility:hidden`) for the whole `session.history` round-trip — the
+// center column blanks and repaints like a full-page refresh on every launch.
 //
 // The unit spec pins the phase condition over hand-built stores. What only the
 // assembled application can show is that the path a user actually takes
@@ -19,8 +19,9 @@
 // The round-trip against a loopback host is far too fast to observe, so this
 // scenario HOLDS the `session.history` response open at the browser's network
 // boundary and asserts the visible frame while it is in flight. That gate is
-// what makes the assertions non-vacuous: with the exemption reverted the held
-// window is exactly when `settling` is painted and the composer is hidden.
+// what makes the assertions non-vacuous: without the phase exemption, the
+// held window is exactly when `settling` would be painted and the composer
+// hidden.
 //
 // Zero model calls: registering a workspace and opening its blank session are
 // host RPCs with no model involvement. A stray stream would fail loud with
diff --git a/apps/web/tests/subagent-interrupt-ui.e2e.ts b/apps/web/tests/subagent-interrupt-ui.e2e.ts
index f289b062e3..810fe4bcf1 100644
--- a/apps/web/tests/subagent-interrupt-ui.e2e.ts
+++ b/apps/web/tests/subagent-interrupt-ui.e2e.ts
@@ -185,7 +185,8 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-offline'))
     // Simulate a parent that went offline: the catalog delivers
     // parentAvailable: false while the child Activation stays live (the
-    // interrupt RPC itself needs no live parent — PR 1's host coverage).
+    // interrupt RPC itself needs no live parent — covered host-side by
+    // subagent-interrupt.e2e.ts).
     const pattern = '**/api/subagent.list'
     await page.route(pattern, async (route) => {
       const response = await route.fetch()
diff --git a/apps/web/tests/subagent-interrupt.e2e.ts b/apps/web/tests/subagent-interrupt.e2e.ts
index e1e35e7981..3e2bfe7f37 100644
--- a/apps/web/tests/subagent-interrupt.e2e.ts
+++ b/apps/web/tests/subagent-interrupt.e2e.ts
@@ -4,7 +4,7 @@
 // proves from the real session state that the turn aborted, the follow-up
 // parked without auto-starting a new turn, and a later waking send resumed the
 // preserved FIFO order. No browser: the RPC surface is the product surface
-// under test, and PR-stacked UI coverage owns the composer interaction.
+// under test, and subagent-interrupt-ui.e2e.ts owns the composer interaction.
 import { existsSync } from 'node:fs'
 import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
diff --git a/apps/web/tests/turn-tail-actions.e2e.ts b/apps/web/tests/turn-tail-actions.e2e.ts
index 235145ebcc..d68aef4700 100644
--- a/apps/web/tests/turn-tail-actions.e2e.ts
+++ b/apps/web/tests/turn-tail-actions.e2e.ts
@@ -1,6 +1,6 @@
 // Web e2e scenario: assistant IconActions belong to the settled answer, so
 // they arrive with `turn/end` and not before. The recorded turn narrates in
-// plain text before its tool call, which is the shape that used to hand the
+// plain text before its tool call, which is the shape that would hand the
 // footer to mid-turn narration for the seconds a tool runs and then move it
 // down. A `hang` sidecar on the SECOND model call parks the turn after the
 // narration and the tool result are durable, so the running state is stable by
diff --git a/apps/web/tests/workspace-management.e2e.ts b/apps/web/tests/workspace-management.e2e.ts
index a99336fd90..a8e238422b 100644
--- a/apps/web/tests/workspace-management.e2e.ts
+++ b/apps/web/tests/workspace-management.e2e.ts
@@ -91,8 +91,8 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     ).not.toBeUndefined()
     // First adoption births a blank Session+Agent whose workspace attach must
     // settle before a test may delete the registration; re-registration after
-    // a delete mints a fresh blank Session+Agent too (the old cwd-only reuse
-    // path is gone), so callers opt in only where a fresh attach is possible.
+    // a delete mints a fresh blank Session+Agent too (no cwd-based reuse
+    // exists), so callers opt in only where a fresh attach is possible.
     if (options.waitForAgent === true) {
       await expect.poll(() => scaffold.ctx.agents.list().length, { timeout: 10_000 })
         .toBeGreaterThan(agentsBefore)
@@ -254,7 +254,7 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     // a supported reversible flow. It creates a fresh Workspace id and does
     // NOT re-adopt the retained (non-blank) Session; the New Session flow
     // mints a fresh blank session and attaches it to the new registration
-    // (the old cwd-only blank reuse is gone, so the account is never empty).
+    // (no cwd-based blank reuse exists, so the account is never empty).
     await adoptDirectory(scaffold.workspaceCwd)
     await expect.poll(
       () => scaffold.ctx.workspace.resolveByPath(scaffold.workspaceCwd),
@@ -482,7 +482,7 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     await expect.poll(() => page.getByText('Idle', { exact: true }).count(), { timeout: 5_000 }).toBeGreaterThanOrEqual(1)
     // The card is REACHABLE: it sits 8px off the row, so getting to it means
     // crossing ground that belongs to neither. Hovering it must not dismiss
-    // it — the regression this scenario guards.
+    // it — the hazard this scenario pins.
     const card = page.getByRole('button', { name: `Copy: ${rowTitle}` })
     await card.hover()
     await page.waitForTimeout(POINTER_HOLD_MS)
@@ -515,10 +515,10 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     const item = page.getByRole('menuitem', { name: 'Rename' })
     await item.waitFor({ timeout: 5_000 })
     // Into the list, then back up to the trigger across the 4px gap below it:
-    // that return trip used to fire the list's pointerleave and close the
-    // menu, so a hesitating pointer lost it. Order matters — clicking leaves
-    // the pointer ON the trigger, so entering the list has to come first for
-    // the return to be a real departure.
+    // without the gap-crossing grace, that return trip fires the list's
+    // pointerleave and closes the menu — a hesitating pointer loses it.
+    // Order matters — clicking leaves the pointer ON the trigger, so entering
+    // the list has to come first for the return to be a real departure.
     await item.hover()
     await page.waitForTimeout(POINTER_TRANSIT_MS)
     await trigger.hover()
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index c5a6e6cc11..ec34ec435a 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -73,10 +73,13 @@ const BOOT_GRAMMAR_FILES: readonly string[] = [
   'dist/json.mjs',
 ]
 
-/** Font asset extensions routed to assets/fonts/ (KaTeX's woff2/woff/ttf faces today). */
+/** Font asset extensions routed to assets/fonts/ (KaTeX's woff2/woff/ttf faces). */
 const FONT_EXTENSIONS: readonly string[] = ['.woff2', '.woff', '.ttf']
 
-/** npm package name of a resolved module id (the segment after the LAST `node_modules/` — pnpm nests the real package under an inner node_modules). */
+/**
+ * npm package name of a resolved module id (the segment after the LAST
+ * `node_modules/` — pnpm nests the real package under an inner node_modules).
+ */
 function npmPackageOf(id: string): string | undefined {
   const parts = id.split('/node_modules/')
   if (parts.length === 1) return undefined
@@ -94,7 +97,7 @@ export default defineConfig({
       output: {
         // Output layout: the two main chunks stay at assets/ root; lazy
         // @shikijs/langs grammar chunks group under assets/langs/; fonts
-        // (today all KaTeX faces referenced by vendor.css) group under
+        // (all KaTeX faces referenced by vendor.css) group under
         // assets/fonts/. Sourcemaps need no arrangement: rollup writes each
         // .map next to its js and references it by bare relative filename.
         chunkFileNames(chunk): string {
@@ -128,7 +131,8 @@ export default defineConfig({
     // for Node/type consumers, but the browser bundle must compile src directly
     // so CSS rides vite's pipeline instead of the CSS-externalized lib bundle.
     // Only the shell's normal-package surface is aliased — plugin packages are
-    // NEVER bundled here (web2 shell self-sufficiency); they arrive as runtime
+    // NEVER bundled here (shell self-sufficiency — see
+    // packages/client/web/README.md); they arrive as runtime
     // bundles through the client module system. Order matters — subpath
     // aliases must win over bare-name prefixes.
     alias: [
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index c395f05428..0d82ebdd37 100644
--- a/docs/api-gateway.i18n.yaml
+++ b/docs/api-gateway.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 docs/api-gateway.md
-api-gateway.md: e8aafc173dced3c4ead07421d92401411565ece6
-api-gateway.zh.md: 5c4f306957a65a92abe8f15159ab2d23e61ef501
+api-gateway.md: 1fdbe256afb7e870e953f05bd29923a4e1c7c22b
+api-gateway.zh.md: b9e18bf78bb5887725a5278e0b28efb86d17b944
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index e8aafc173d..1fdbe256af 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -75,7 +75,7 @@ await agentCtx.remote.goals.create({ objective: 'ship it' })
 
 Client applications assemble only `@deepseek-ai/dsh-api-remotes`. That package imports the `/remote` subpaths of selected business packages as runtime values, mounts their contributions through `ctx.remote.$mount()`, and re-exports the declaration merges from the same files. Adding a Host Remote package is an explicit choice by the Client composition owner; business components do not need to load the TypeRT Gateway or the business package's Remote JS separately.
 
-A future TUI can assemble the same React-independent `api-remotes` and `ctx.remote` contract, so the Host methods visible to it are likewise limited to the Remote methods selected at generation time. This document does not define or implement the TUI composition.
+The `api-remotes` assembly and the `ctx.remote` contract are React-independent; the Host methods visible to any Client assembly are limited to the Remote methods selected at generation time.
 
 ## Component responsibilities
 
@@ -88,7 +88,7 @@ A future TUI can assemble the same React-independent `api-remotes` and `ctx.remo
 | Host | `@deepseek-ai/dsh-api-gateway` | Provides `ctx.typertGateway`, claims Remote endpoints, resolves objects or Contexts, invokes live Cordis services, and validates boundaries |
 | Client | `@deepseek-ai/dsh-api-gateway/client` | Provides `ctx.remote` and `remote.<namespace>` child Services, mounts generated descriptors as concrete methods, and initiates, validates, and cancels calls through the Connection |
 | Client | `@deepseek-ai/dsh-api-remotes/client` | Explicitly selects and mounts the `/remote` contributions allowed by the application and brings the corresponding declaration merges into business code |
-| Both | `@deepseek-ai/dsh-client-connection` | Provides the RPC carrier, request correlation, trust boundary, cancellation, response envelope, and current `/api` HTTP bridge |
+| Both | `@deepseek-ai/dsh-client-connection` | Provides the RPC carrier, request correlation, trust boundary, cancellation, response envelope, and the `/api` HTTP bridge |
 
 The API Gateway package owns the Host dispatcher and Client Remote endpoint as peer entries, but the two builds never enter the same `ts.Program`. The Host entry does not import the Client Cordis `Context` merge, and the Client entry does not import the Host Gateway service.
 
@@ -118,7 +118,7 @@ Strict analysis requires a Remote to be a public, non-static instance method wit
 
 ## Runtime invocation
 
-Remote and API Proxy currently share the Connection's `/api` route; there is no separate `/api2` server or second Connection. The Client Remote calls `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`; the current HTTP carrier maps this to `POST /api/<namespace>/<method>`, with a payload containing only a named `args` object.
+Remote and API Proxy share the Connection's `/api` route. The Client Remote calls `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`; the HTTP carrier maps this to `POST /api/<namespace>/<method>`, with a payload containing only a named `args` object.
 
 The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler in interceptor order. The TypeRT Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; unclaimed requests fall back to the existing API Proxy. The Connection owns transport, RPC ids, response envelopes, and request cancellation, while the Gateway owns only the Remote data protocol and business dispatch. Replacing the Connection carrier in the future does not require changes to Remote descriptors or the Client programming interface.
 
@@ -165,6 +165,6 @@ The running Client watcher consumes these generated files when it rebundles. If
 
 Remote handles only unary method calls with one request and one result. Session event streams, pagination, incremental reduce, projection, and entity substreams require a separate data protocol and registration model; even when they reuse the Connection, they must not masquerade as Remote methods or enter invocation descriptors.
 
-The API layers are organized as `remotes → gateway → connection → webserver`. The BFF and TypeRT RPC layers live under `packages/api`; Connection and WebServer remain at `packages/client/connection` and `packages/host/webserver`, with service contracts that permit a later package-only move to `packages/api`. The legacy API Proxy remains at `packages/host/apiproxy` as the fallback for endpoints not yet migrated to Remote.
+The API layers are organized as `remotes → gateway → connection → webserver`. The BFF and TypeRT RPC layers live under `packages/api`; Connection and WebServer live at `packages/client/connection` and `packages/host/webserver`. The API Proxy at `packages/host/apiproxy` handles endpoints without Remote descriptors.
 
-Lookup policy is currently configured per key, so all `agent` or `session` parameters share the cold-resume behavior. If a Remote endpoint must accept live objects only, an explicit per-parameter or per-endpoint policy must be added later; the business method must not guess whether the object came from restoration.
+Lookup policy is configured per key, so all `agent` or `session` parameters share the cold-resume behavior. Accepting live objects only would require an explicit per-parameter or per-endpoint policy, which does not exist; the business method must not guess whether the object came from restoration.
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 5c4f306957..b9e18bf78b 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -75,7 +75,7 @@ await agentCtx.remote.goals.create({ objective: 'ship it' })
 
 Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导入被选业务包的 `/remote` 子路径，通过 `ctx.remote.$mount()` 挂载贡献，同时重新导出相同文件中的声明合并。增加一个 Host Remote 包是 Client 组合所有者的显式选择；业务组件不需要分别加载 TypeRT Gateway 或业务包的 Remote JS。
 
-未来的 TUI 可以装配同一个不依赖 React 的 `api-remotes` 与 `ctx.remote` 约定，因此它能看到的 Host 方法同样只限于生成时选择的 Remote 方法。本文不定义或实现 TUI 组合。
+`api-remotes` 装配与 `ctx.remote` 约定不依赖 React；任何 Client 装配能看到的 Host 方法都只限于生成时选择的 Remote 方法。
 
 ## 组件职责
 
@@ -88,7 +88,7 @@ Client 应用只装配 `@deepseek-ai/dsh-api-remotes`。该包以运行时值导
 | Host | `@deepseek-ai/dsh-api-gateway` | 提供 `ctx.typertGateway`，认领 Remote endpoint，解析对象或 Context，调用实时 Cordis Service 并校验边界 |
 | Client | `@deepseek-ai/dsh-api-gateway/client` | 提供 `ctx.remote` 与 `remote.<namespace>` 子 Service，把生成的描述符挂成具体方法，并通过 Connection 发起、校验和取消调用 |
 | Client | `@deepseek-ai/dsh-api-remotes/client` | 显式选择并挂载本应用允许使用的 `/remote` 贡献，向业务代码带入对应的声明合并 |
-| 双侧 | `@deepseek-ai/dsh-client-connection` | 提供 RPC carrier、请求关联、信任边界、取消、响应 envelope 与当前 `/api` HTTP bridge |
+| 双侧 | `@deepseek-ai/dsh-client-connection` | 提供 RPC carrier、请求关联、信任边界、取消、响应 envelope 与 `/api` HTTP bridge |
 
 API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对等入口，但两侧构建不会进入同一个 `ts.Program`。Host 入口不导入 Client 的 Cordis `Context` 合并，Client 入口也不导入 Host Gateway 服务。
 
@@ -118,7 +118,7 @@ Remote Client 声明中的参数名来自 wire 字段，参数和返回类型则
 
 ## 运行时调用
 
-当前 Remote 与 API Proxy 共用 Connection 的 `/api` 路由，不存在独立 `/api2` server 或第二套 Connection。Client Remote 调用 `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`；当前 HTTP carrier 对应 `POST /api/<namespace>/<method>`，payload 只包含一个具名 `args` 对象。
+Remote 与 API Proxy 共用 Connection 的 `/api` 路由。Client Remote 调用 `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`；HTTP carrier 对应 `POST /api/<namespace>/<method>`，payload 只包含一个具名 `args` 对象。
 
 Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内按 interceptor 顺序分发。TypeRT Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；未认领的请求回退到既有 API Proxy。Connection 拥有传输、RPC id、响应 envelope 和 request cancellation，Gateway 只拥有 Remote 数据协议和业务分发。未来替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程界面。
 
@@ -165,6 +165,6 @@ pnpm run build:lib
 
 Remote 只处理有单个请求与单个结果的一元方法调用。Session event stream、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
 
-API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 仍位于 `packages/client/connection` 和 `packages/host/webserver`，其服务约定允许未来只移动包，将它们放到 `packages/api`。旧 API Proxy 仍位于 `packages/host/apiproxy`，作为尚未迁移到 Remote 的 endpoint 的回退路径。
+API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 TypeRT RPC 层位于 `packages/api`；Connection 与 WebServer 位于 `packages/client/connection` 和 `packages/host/webserver`。位于 `packages/host/apiproxy` 的 API Proxy 处理没有 Remote 描述符的 endpoint。
 
-当前 lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。某个 Remote endpoint 若必须只接受 live 对象，需要后续增加显式的逐参数或逐 endpoint 策略，不能通过业务方法内部猜测恢复来源。
+lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。只接受 live 对象需要显式的逐参数或逐 endpoint 策略，而这种策略并不存在；不能通过业务方法内部猜测对象是否来自恢复。
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index d61353210e..af9f8ba48e 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -417,7 +417,7 @@ flowchart LR
 | `ctx.permission` | `core` | [`permission`](../packages/interaction/permission) | - | - | - | User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events. |
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
-| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
+| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; there is no model-facing compact tool. |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 7278447cf8..10f0761fc5 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -411,7 +411,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
+Source: [`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-e2b`
 
@@ -513,7 +513,7 @@ export interface Config {
    * Process-level: read once at load, a relative path resolves against the process
    * launch cwd, so one config applies to the whole process.
    * TODO(per-session-hook-config): per-session discovery of a project-local
-   * `hooks.json` from each `session/new.cwd` is not yet implemented.
+   * `hooks.json` from each `session/new.cwd`.
    */
   configPath: string
   /**
@@ -548,7 +548,7 @@ export interface Config {
    * Path to a Codex `hooks.json`. Process-level: read once at load, a relative
    * path resolves against the process launch cwd.
    * TODO(per-session-hook-config): per-session project-local discovery from each
-   * `session/new.cwd` is not yet implemented.
+   * `session/new.cwd`.
    */
   configPath: string
   /** The model name stamped on every payload (Codex includes `model` on each event). */
@@ -846,8 +846,7 @@ type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>
 
 /**
  * pi-ai thinking formats a profile cannot name: both drive the request through
- * `chatTemplateKwargs`, which this configuration does not expose, so offering
- * them would hand back a format with nothing to say.
+ * `chatTemplateKwargs`, which this configuration does not expose.
  */
 type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
 ```
@@ -1689,7 +1688,7 @@ export interface Config {
   /**
    * How to auto-answer the child's `session/request_permission` prompts:
    * `reject` (default — decline every prompt) or `allow` (approve via the first
-   * allow-shaped option). The first cut surfaces no prompt to a human.
+   * allow-shaped option). No prompt is surfaced to a human.
    */
   permission: PermissionPolicy
   /**
@@ -2360,8 +2359,7 @@ export interface Config {
  * ask BEFORE any interactive answerer sees it:
  *
  * - `'ask'` (the default) — delegate to the composed answerers; with none
- *   composed the chain falls through to the fail-closed `'unavailable'`
- *   (exactly today's behavior).
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
  * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
  *   deterministically. The strict headless stance (CI, unattended runs) and
  *   the policy whose outcome is knowable without asking.
@@ -2369,7 +2367,7 @@ export interface Config {
 export type ApprovalPolicy = 'ask' | 'never'
 ```
 
-Source: [`packages/interaction/user-approval/src/index.ts:178`](../packages/interaction/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:177`](../packages/interaction/user-approval/src/index.ts)
 
 ## `@deepseek-ai/dsh-web`
 
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index 7eaa702a9d..6e83450ec3 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/extension-cookbook.md
-extension-cookbook.md: 5d9312f2f5cf840100b12045bde1829b342e580d
-extension-cookbook.zh.md: 29bb57c558a0ff9413619d0bb2e8bb5e6b70da56
+extension-cookbook.md: aba220ec6dc3cf3d0f99edd0e47ffa6069499b47
+extension-cookbook.zh.md: 34e8fc0fa3d2d57136616d66cfb4f3f6de20605e
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index 5d9312f2f5..aba220ec6d 100644
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -105,7 +105,7 @@ Every product feature maps to a listener on a documented extension point — the
 | `/loop` | on the `turn/end` session event, `followup()` the next iteration; or force-continue |
 | Dynamic workflow | `ctx.workflows` + the worker-thread engine + the `workflow` tool; structured in-process children enforce output with scoped prompt/tool registrations, a monotonic tool guard, final `tools/result` commit (including enclosing `run_code`), and the structured-output execution's monotonic `concludeTurn()` marker |
 | Queued + steering messages | core `Agent.followup()` / `Agent.steer()` |
-| Context compaction (auto + manual) | the `ctx.compact` seam + `dsh-compact-basic`; automatic pressure runs on serial `agent/pre-step`, canonical overflow recovery runs on `agent/request-error`, and manual callers use the same compact service ([compaction Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) — the model-facing `/compact` consumer tool is deferred) |
+| Context compaction (auto + manual) | the `ctx.compact` seam + `dsh-compact-basic`; automatic pressure runs on serial `agent/pre-step`, canonical overflow recovery runs on `agent/request-error`, and manual callers use the same compact service ([compaction Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)) |
 | System prompt configurability | `ctx.systemPrompt.section()` with ordering and scope-local shadowing |
 | AGENTS.md (root) | a section provider reading the file |
 | AGENTS.md (subdir, on-touch) + file-change notices | `agent.inject()` from a watcher / tool-result listener |
@@ -116,7 +116,7 @@ Every product feature maps to a listener on a documented extension point — the
 | Monotonic terminal turn policy | call `ToolExecution.concludeTurn()` from the successful terminal tool; later tool calls in the same response remain guardable, and the loop stops after the step |
 | Subprocess sandbox (landlock / sandbox-exec) | use a `ctx.sandbox` backend through `dsh-bash-sandbox`; use `tools/pre-execute` for capability-level denial |
 | Permission system / AskUserQuestion | return `ask` from `tools/pre-execute` and answer through `ctx.approval`; register a separate model-facing ask tool for ordinary user questions |
-| Plan mode | Shipped: [`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md) — logged `plan/mode` state, the `plan:policy` guidance section, `/plan [message]` entry, `/plan off` direct exit, and the user-reviewed `exit_plan_mode` exit; enforcement stays on the independent sandbox/approval axes |
+| Plan mode | [`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md) — logged `plan/mode` state, the `plan:policy` guidance section, `/plan [message]` entry, `/plan off` direct exit, and the user-reviewed `exit_plan_mode` exit; enforcement stays on the independent sandbox/approval axes |
 | Sub-agent delegation | the `ctx.subagents` provider registry (`dsh-subagent-spawn`/`-fork`/`-acp`/`-codex`/`-claude-code`/`-dsh-sdk`) + `dsh-tool-subagent` exposing one configured provider to the model |
 | MCP | one plugin per server: discover tools → `ctx.tools.register()` |
 | Skills | section + tool registration; `inject()` skill content on invocation |
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index 29bb57c558..34e8fc0fa3 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -105,7 +105,7 @@ export function apply(ctx: Context) {
 | `/loop` | 在 `turn/end` 会话事件上 `followup()` 下一次迭代；或强制继续 |
 | 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的提示词/工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code`）和结构化输出执行的单调 `concludeTurn()` 标记来强制输出 |
 | 排队消息 + steering | 核心 `Agent.followup()` / `Agent.steer()` |
-| 上下文压缩（context compaction）（自动 + 手动） | `ctx.compact` seam + `dsh-compact-basic`；自动压力检查运行在串行 `agent/pre-step`，规范化溢出恢复运行在 `agent/request-error`，手动调用方使用同一个压缩服务（[压缩 Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)——面向模型的 `/compact` 消费方工具已推迟） |
+| 上下文压缩（context compaction）（自动 + 手动） | `ctx.compact` seam + `dsh-compact-basic`；自动压力检查运行在串行 `agent/pre-step`，规范化溢出恢复运行在 `agent/request-error`，手动调用方使用同一个压缩服务（[压缩 Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)） |
 | 系统提示词可配置性 | `ctx.systemPrompt.section()`，支持排序与作用域局部覆盖 |
 | AGENTS.md（根目录） | 一个读取该文件的 section 提供方 |
 | AGENTS.md（子目录，按需触发）+ 文件变更通知 | 从 watcher / 工具结果监听器调用 `agent.inject()` |
@@ -116,7 +116,7 @@ export function apply(ctx: Context) {
 | 单调终端轮次策略 | 从成功的终端工具调用 `ToolExecution.concludeTurn()`；同一响应中后续工具调用仍可由守卫阻止，循环在该步骤后停止 |
 | 子进程沙箱（landlock / sandbox-exec） | 通过 `dsh-bash-sandbox` 使用 `ctx.sandbox` 后端；能力级别的拒绝使用 `tools/pre-execute` |
 | 权限系统 / AskUserQuestion | 从 `tools/pre-execute` 返回 `ask` 并通过 `ctx.approval` 应答；为普通用户提问注册一个独立的面向模型的 ask 工具 |
-| Plan mode | 已交付：[`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md)：落日志的 `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
+| Plan mode | [`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md)：落日志的 `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
 | subagent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn`/`-fork`/`-acp`/`-codex`/`-claude-code`/`-dsh-sdk`）+ `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
 | MCP | 每个服务器一个插件：发现工具 → `ctx.tools.register()` |
 | skill（技能） | section + 工具注册；调用时通过 `inject()` 注入 skill 内容 |
diff --git a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml b/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
index fde0ddda14..331373fb1e 100644
--- a/docs/cookbook/maintaining-dsh-code-review.i18n.yaml
+++ b/docs/cookbook/maintaining-dsh-code-review.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 docs/cookbook/maintaining-dsh-code-review.md
-maintaining-dsh-code-review.md: 8aa8a5792bff2c49041f2f8b5e8146e7cff14e0e
-maintaining-dsh-code-review.zh.md: b26c98e8679eece78e72ee684580c1ed1181aa7c
+maintaining-dsh-code-review.md: c8517054434f4b090c67455cda0a992c2c3173ee
+maintaining-dsh-code-review.zh.md: 3d26d540a41661aa45b41d6738118f36d904ccf3
diff --git a/docs/cookbook/maintaining-dsh-code-review.md b/docs/cookbook/maintaining-dsh-code-review.md
index 8aa8a5792b..c851705443 100644
--- a/docs/cookbook/maintaining-dsh-code-review.md
+++ b/docs/cookbook/maintaining-dsh-code-review.md
@@ -6,7 +6,7 @@ The [`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill is
 
 ## What the maintainer receives
 
-Run the private tool daily with a two-UTC-day overlap; until the proposed scheduler has completed its acceptance run, the operator invokes the wrapper manually at the same cadence. A manual weekly recovery run uses a seven-day window. The workflow:
+The operator invokes the wrapper manually, daily with a two-UTC-day overlap; a manual weekly recovery run uses a seven-day window. The workflow:
 
 1. It selects PRs merged in the chosen window (default two UTC days for the daily cadence, seven for weekly) whose merge commit is reachable from `origin/master`. PRs whose merge commit is not reachable (stacked branches whose parent was squashed) or that exceed a 250-commit acquisition cap are logged to `skipped-pulls.json` and skipped rather than aborting the run.
 2. It collects pre-merge human review feedback with commit anchors (inline comments and review submissions), then compares feedback-time and final landed PR patches. It does not acquire PR conversation comments because current GitHub state cannot give them a force-push-safe feedback-time baseline, and it excludes target-branch-only changes from adoption evidence.
diff --git a/docs/cookbook/maintaining-dsh-code-review.zh.md b/docs/cookbook/maintaining-dsh-code-review.zh.md
index b26c98e867..3d26d540a4 100644
--- a/docs/cookbook/maintaining-dsh-code-review.zh.md
+++ b/docs/cookbook/maintaining-dsh-code-review.zh.md
@@ -6,7 +6,7 @@
 
 ## 维护者会收到什么
 
-每天运行私有工具，并使用 2 个 UTC 日的重叠窗口；在拟议的调度器完成验收运行之前，操作员按相同频率手动调用包装脚本。每周手动恢复运行使用 7 日窗口。工作流会：
+操作员每天手动调用包装脚本，并使用 2 个 UTC 日的重叠窗口；每周手动恢复运行使用 7 日窗口。工作流会：
 
 1. 选择指定窗口内合并、且合并 commit 可从 `origin/master` 到达的 PR（每天运行默认选择 2 个 UTC 日，每周运行选择 7 日）。合并 commit 无法到达的 PR（例如父分支被 squash 的堆叠分支），或超出 250 个 commit 获取上限的 PR，会记录到 `skipped-pulls.json` 并跳过，不会中止本次运行。
 2. 收集合并前带 commit 锚点的人工评审反馈（行内评论和评审提交），然后比较反馈时与最终落地的 PR patch。它不获取 PR 会话评论，因为 GitHub 当前状态无法为这些评论提供可抵抗 force-push 的反馈时基线；它也不会把只存在于目标分支的变更作为采纳证据。
diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md
index 8bf23274e5..6af9aec465 100644
--- a/docs/cordis-api/inherited.md
+++ b/docs/cordis-api/inherited.md
@@ -5,7 +5,7 @@
 
 The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).
 
-This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
+This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method; type names in a signature link to the page that documents them.
 
 ## Inherited `ctx` members (cordis core + loader/hmr/timer)
 
diff --git a/docs/cordis-tutorial/04-events.i18n.yaml b/docs/cordis-tutorial/04-events.i18n.yaml
index 2914e62e30..b453ffb1f6 100644
--- a/docs/cordis-tutorial/04-events.i18n.yaml
+++ b/docs/cordis-tutorial/04-events.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 docs/cordis-tutorial/04-events.md
-04-events.md: b0563c71fada3efc760ff7183bc7a82e7e86934e
-04-events.zh.md: 66b52fcb1d7ec4a81c823a7c8e016c5b17d45993
+04-events.md: e77641dffcb82fcb50a24ca2e3e764d152218094
+04-events.zh.md: 00cce854e9a54fddb594ffa8e306f60a725ac012
diff --git a/docs/cordis-tutorial/04-events.md b/docs/cordis-tutorial/04-events.md
index b0563c71fa..e77641dffc 100644
--- a/docs/cordis-tutorial/04-events.md
+++ b/docs/cordis-tutorial/04-events.md
@@ -135,7 +135,7 @@ HELLO
 
 Walk through the second line: listener 1 runs first, calls `next()`, which invokes listener 2; listener 2 sees `blocked` and returns without calling `next()` — the innermost default (the function passed to `ctx.waterfall`) never runs — and listener 1 uppercases the replacement message on the way out.
 
-The discipline that follows: **a waterfall listener that only observes or annotates must call `next()`**; returning without it is a deliberate short-circuit. Forgetting `next()` in a logging listener silently swallows the default behavior for everyone downstream. This is important enough that it is a standing rule of this repository ([waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)).
+The discipline that follows: **a waterfall listener that only observes or annotates must call `next()`**; returning without it is a deliberate short-circuit. Forgetting `next()` in a logging listener silently swallows the default behavior for everyone downstream. It is a standing rule of this repository ([waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)).
 
 The harness uses waterfalls for decisions that cooperating plugins may wrap or answer: [`agent/request`](../subsystems/core.md#agentrequest--waterfall) lets a plugin replace the model-call config, and [`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) lets a policy answer instead of the user.
 
diff --git a/docs/cordis-tutorial/04-events.zh.md b/docs/cordis-tutorial/04-events.zh.md
index 66b52fcb1d..00cce854e9 100644
--- a/docs/cordis-tutorial/04-events.zh.md
+++ b/docs/cordis-tutorial/04-events.zh.md
@@ -135,7 +135,7 @@ HELLO
 
 按顺序看第二行如何产生：监听器 1 先运行并调用 `next()`，从而调用监听器 2；监听器 2 看到 `blocked` 后直接返回而不调用 `next()`，因此最内层默认逻辑（传给 `ctx.waterfall` 的函数）从未运行；返回途中，监听器 1 再把替换消息转换为大写。
 
-由此得到一项纪律：**只负责观察或标注的 waterfall 监听器必须调用 `next()`**；不调用就直接返回代表有意短路。如果日志监听器忘记调用 `next()`，会悄无声息地吞掉所有下游的默认行为。这一点极其重要，已成为本仓库的常设规则（[waterfall 语义](../cordis-primer.md#cordis-waterfall-semantics)）。
+由此得到一项纪律：**只负责观察或标注的 waterfall 监听器必须调用 `next()`**；不调用就直接返回代表有意短路。如果日志监听器忘记调用 `next()`，会悄无声息地吞掉所有下游的默认行为。这是本仓库的常设规则（[waterfall 语义](../cordis-primer.md#cordis-waterfall-semantics)）。
 
 harness 使用 waterfall 处理协作插件可以包装或回答的决策：[`agent/request`](../subsystems/core.md#agentrequest--waterfall) 允许插件替换模型调用配置，[`approval/request`](../subsystems/approval.md#approvalrequest--waterfall) 允许策略代替用户作答。
 
diff --git a/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml b/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml
index 44b59db26a..3732651e58 100644
--- a/docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml
+++ b/docs/cordis-tutorial/06-composition-and-hmr.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 docs/cordis-tutorial/06-composition-and-hmr.md
-06-composition-and-hmr.md: f138918a2d217ed98fdfd4e56dffddc14e3397f0
-06-composition-and-hmr.zh.md: a678e86735c6d9e3b4f3cd0dfa46a2a64079c762
+06-composition-and-hmr.md: a169d7a164be63c939e352e4e5b0bf9bce43da29
+06-composition-and-hmr.zh.md: 07ae46555c390d625a4397933e2ec5ac059bd270
diff --git a/docs/cordis-tutorial/06-composition-and-hmr.md b/docs/cordis-tutorial/06-composition-and-hmr.md
index f138918a2d..a169d7a164 100644
--- a/docs/cordis-tutorial/06-composition-and-hmr.md
+++ b/docs/cordis-tutorial/06-composition-and-hmr.md
@@ -18,7 +18,7 @@ A config entry accepts metadata beyond `name` and `config`:
 
 `id` gives the entry a stable identity so the loader can tell an edit to an existing entry apart from a removal plus an addition. `disabled: true` unmounts a plugin without deleting its entry — flip it back and the plugin (and everything PENDING on its services) loads again.
 
-Groups nest a sub-list of entries that load and unload as one unit, and `isolate` gives a group its own instance of a service name — two groups can each see a differently-configured `bash` without affecting each other. Those are worth knowing about before you need them; the [Cordis primer](../cordis-primer.md) and the [service isolation example](../user/develop/framework/service.md#service-isolation) cover the details.
+Groups nest a sub-list of entries that load and unload as one unit, and `isolate` gives a group its own instance of a service name — two groups can each see a differently-configured `bash` without affecting each other. The [Cordis primer](../cordis-primer.md) and the [service isolation example](../user/develop/framework/service.md#service-isolation) cover the details.
 
 ## Hot module replacement
 
diff --git a/docs/cordis-tutorial/06-composition-and-hmr.zh.md b/docs/cordis-tutorial/06-composition-and-hmr.zh.md
index a678e86735..07ae46555c 100644
--- a/docs/cordis-tutorial/06-composition-and-hmr.zh.md
+++ b/docs/cordis-tutorial/06-composition-and-hmr.zh.md
@@ -18,7 +18,7 @@ Cordis 配置项除了 `name` 和 `config`，还接受其他元数据：
 
 `id` 为 Cordis 配置项提供稳定标识，使 loader 能区分修改现有 Cordis 配置项与先删除再添加。`disabled: true` 会卸载插件而不删除其 Cordis 配置项；改回原值后，插件以及所有因依赖其服务而处于 PENDING 的插件都会再次加载。
 
-组可以嵌套一份 Cordis 配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `bash`，互不影响。这些概念值得在用到之前先了解；[Cordis 入门](../cordis-primer.md)和[服务隔离示例](../user/develop/framework/service.md#service-isolation)介绍了详细内容。
+组可以嵌套一份 Cordis 配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `bash`，互不影响。[Cordis 入门](../cordis-primer.md)和[服务隔离示例](../user/develop/framework/service.md#service-isolation)介绍了详细内容。
 
 ## 热模块替换
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 05ff62a391..11eecf81a4 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -3,7 +3,7 @@
 
 # Event Producer And Consumer Matrix
 
-This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.
+This matrix shows which packages dispatch each harness-owned event and which packages listen to it. Events are many-to-many, so the dense relation data is presented as a table rather than one large graph. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.
 
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index f4aece8a52..d8c6d95f73 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -1,6 +1,6 @@
 # Translation prompt (pipeline asset)
 
-本文件是自动翻译流水线的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。模板正文与内嵌 few-shot 正误例由 jingtingxiang 基于对存量译文的质量评审撰写，是流水线行为的拍板基线。渲染时把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`；除此之外不注入任何其他仓库文件（translation-rules.md 约束人和 agent 的翻译工作，不注入本模板）。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题，两者冲突时以文体样例为准。[提示词 v4 约定 Agent Note](../../.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md) 记录兼容协议；v7 保留该协议并选择性吸收经评估的生成质量改进。修改本文件会改变翻译行为，需正常经过 PR 评审。
+本文件是自动翻译流水线的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。模板正文与内嵌 few-shot 正误例由 jingtingxiang 基于对存量译文的质量评审撰写，是流水线行为的拍板基线。渲染时把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`；除此之外不注入任何其他仓库文件（translation-rules.md 约束人和 agent 的翻译工作，不注入本模板）。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题，两者冲突时以文体样例为准。本模板遵循 [提示词 v4 约定 Agent Note](../../.agents/notes/implemented/process/2026-07-23-translation-prompt-v4-contract.md) 记录的兼容协议。修改本文件会改变翻译行为，需正常经过 PR 评审。
 
 ## 占位符约定
 
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index c9aa15cd82..a17cae015e 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -35,7 +35,8 @@ export type SurfaceEventType =
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
  *   surface nodes in the current surface. `start === end` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction and possible other manipulations.
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
  */
 export type SurfaceOp =
   | 'append'
@@ -78,7 +79,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-Sources: [`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:343`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:375`](../packages/core/session/src/types.ts)
+Sources: [`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:344`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:376`](../packages/core/session/src/types.ts)
 
 ## Events
 
diff --git a/docs/subsystems/approval.i18n.yaml b/docs/subsystems/approval.i18n.yaml
index 93c56707bf..088b30ff32 100644
--- a/docs/subsystems/approval.i18n.yaml
+++ b/docs/subsystems/approval.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 docs/subsystems/approval.md
-approval.md: 2045f2073b72fa265728cbf77b673053a2eaf371
-approval.zh.md: c021db14c4925acaeef5d984d9dfa88ad55bd8dd
+approval.md: 660ced6d75886bbea41985fd1f357bf92e8a7838
+approval.zh.md: 56975914098978af99580694ca19f20a02ed4022
diff --git a/docs/subsystems/approval.md b/docs/subsystems/approval.md
index 2045f2073b..660ced6d75 100644
--- a/docs/subsystems/approval.md
+++ b/docs/subsystems/approval.md
@@ -38,8 +38,7 @@ type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
  * ask BEFORE any interactive answerer sees it:
  *
  * - `'ask'` (the default) — delegate to the composed answerers; with none
- *   composed the chain falls through to the fail-closed `'unavailable'`
- *   (exactly today's behavior).
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
  * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
  *   deterministically. The strict headless stance (CI, unattended runs) and
  *   the policy whose outcome is knowable without asking.
@@ -142,7 +141,7 @@ overrideOf(session: Session): ApprovalPolicy | undefined
 
 Types: [Agent](core.md) · [Session](session.md)
 
-Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:192`](../../packages/interaction/user-approval/src/index.ts)
 
 <a id="approval-events"></a>
 
diff --git a/docs/subsystems/approval.zh.md b/docs/subsystems/approval.zh.md
index c021db14c4..5697591409 100644
--- a/docs/subsystems/approval.zh.md
+++ b/docs/subsystems/approval.zh.md
@@ -38,8 +38,7 @@ type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
  * ask BEFORE any interactive answerer sees it:
  *
  * - `'ask'` (the default) — delegate to the composed answerers; with none
- *   composed the chain falls through to the fail-closed `'unavailable'`
- *   (exactly today's behavior).
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
  * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
  *   deterministically. The strict headless stance (CI, unattended runs) and
  *   the policy whose outcome is knowable without asking.
@@ -142,7 +141,7 @@ overrideOf(session: Session): ApprovalPolicy | undefined
 
 Types: [Agent](core.md) · [Session](session.md)
 
-Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts)
+Source: [`packages/interaction/user-approval/src/index.ts:192`](../../packages/interaction/user-approval/src/index.ts)
 
 <a id="approval-events"></a>
 
diff --git a/docs/subsystems/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml
index 81dc8ce5d7..dbfc52bf6e 100644
--- a/docs/subsystems/bash.i18n.yaml
+++ b/docs/subsystems/bash.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 docs/subsystems/bash.md
-bash.md: 1c60f261e292f389ea4afa3f962f698e0272007b
-bash.zh.md: 2533cbe10dc0a480d285f87e458cf5ee5fa12d75
+bash.md: d2797c1e3ff73fe8ecb5a053ed4a1d13b13298dd
+bash.zh.md: b38a4f332978e94d2945f5fa49b38e8d7df8c9ca
diff --git a/docs/subsystems/bash.md b/docs/subsystems/bash.md
index 1c60f261e2..d2797c1e3f 100644
--- a/docs/subsystems/bash.md
+++ b/docs/subsystems/bash.md
@@ -12,7 +12,7 @@ Source: [`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.t
 
 ## Request vs. spec: the `resolve()` split
 
-The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.bash.resolve(request)` between them — this is the repo's "explicit > implicit at package boundaries" rule made concrete: the reader of a `BashExecSpec` never wonders where the working directory or output budget came from.
+The seam separates the **model-/plugin-facing request** (optional `workdir`/`timeoutMs`/`stdoutMaxBytes`, filled from config or request policy) from the **fully-resolved spec** the executor acts on (those fields required). The tool layer calls `ctx.bash.resolve(request)` between them (the repo's "explicit > implicit at package boundaries" rule); a `BashExecSpec` carries resolved values.
 
 ```ts type-equiv
 /**
@@ -162,7 +162,7 @@ interface BashSandboxInfo {
 }
 ```
 
-One more piece completes the vocabulary: the `SANDBOX_UNAVAILABLE` error code (owned by the [sandbox seam](sandbox.md)) is what the `ctx.sandbox` provider throws — and the executor propagates — when a confined mode has no usable backend. A selected runner refusing its profile reaches the same fail-closed foreground error; a settled background task records `runnerFailed`. The model receives denial/runner facts in results, learns the effective mode only when a denial marker names it, and can request a one-shot strictly wider retry through `sandbox_permissions` plus `justification`; `ctx.approval` must grant that exact call before anything executes. The complete policy and switching design is the [sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
+The `SANDBOX_UNAVAILABLE` error code (owned by the [sandbox seam](sandbox.md)) is what the `ctx.sandbox` provider throws — and the executor propagates — when a confined mode has no usable backend. A selected runner refusing its profile reaches the same fail-closed foreground error; a settled background task records `runnerFailed`. The model receives denial/runner facts in results, learns the effective mode only when a denial marker names it, and can request a one-shot strictly wider retry through `sandbox_permissions` plus `justification`; `ctx.approval` must grant that exact call before anything executes. The complete policy and switching design is the [sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md).
 
 ## Background processes: `BashProcess`
 
diff --git a/docs/subsystems/bash.zh.md b/docs/subsystems/bash.zh.md
index 2533cbe10d..b38a4f3329 100644
--- a/docs/subsystems/bash.zh.md
+++ b/docs/subsystems/bash.zh.md
@@ -12,7 +12,7 @@ bash 执行 seam 分为 Service Definition（[dsh-bash](../../packages/bash/bash
 
 ## 请求与规格：`resolve()` 拆分
 
-该 seam 将**面向模型/插件的请求**（`workdir`/`timeoutMs`/`stdoutMaxBytes` 可选，由配置或请求策略补全）与执行器实际使用的**完全解析后的 spec**（这些字段均为必填）分开。工具层在二者之间调用 `ctx.bash.resolve(request)`——这具体落实了仓库的「包边界处显式优于隐式」规则：`BashExecSpec` 的读者不必猜测工作目录或输出预算来自何处。
+该 seam 将**面向模型/插件的请求**（`workdir`/`timeoutMs`/`stdoutMaxBytes` 可选，由配置或请求策略补全）与执行器实际使用的**完全解析后的 spec**（这些字段均为必填）分开。工具层在二者之间调用 `ctx.bash.resolve(request)`（仓库的「包边界处显式优于隐式」规则）；`BashExecSpec` 携带的是已解析的值。
 
 ```ts type-equiv
 /**
@@ -162,7 +162,7 @@ interface BashSandboxInfo {
 }
 ```
 
-最后一项补全了这套词汇：当受限模式没有可用后端时，`ctx.sandbox` 提供方会抛出、执行器会传播由[沙箱 seam](sandbox.md)所有的 `SANDBOX_UNAVAILABLE` 错误码。选定的 runner 拒绝其 profile 时会触达同一个故障关闭的前台错误；已结束的后台任务则记录 `runnerFailed`。模型会在结果中收到拒绝/runner 事实，仅当拒绝标记指出生效模式时才得知该模式，并可通过 `sandbox_permissions` 加 `justification` 请求一次性、严格更宽松的重试；执行任何操作前，`ctx.approval` 必须批准该次确切调用。完整的策略与切换设计见[沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
+当受限模式没有可用后端时，`ctx.sandbox` 提供方会抛出、执行器会传播由[沙箱 seam](sandbox.md)所有的 `SANDBOX_UNAVAILABLE` 错误码。选定的 runner 拒绝其 profile 时会触达同一个故障关闭的前台错误；已结束的后台任务则记录 `runnerFailed`。模型会在结果中收到拒绝/runner 事实，仅当拒绝标记指出生效模式时才得知该模式，并可通过 `sandbox_permissions` 加 `justification` 请求一次性、严格更宽松的重试；执行任何操作前，`ctx.approval` 必须批准该次确切调用。完整的策略与切换设计见[沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)。
 
 ## 后台进程：`BashProcess`
 
diff --git a/docs/subsystems/client-modules.i18n.yaml b/docs/subsystems/client-modules.i18n.yaml
index ae61603169..8c320d18e6 100644
--- a/docs/subsystems/client-modules.i18n.yaml
+++ b/docs/subsystems/client-modules.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 docs/subsystems/client-modules.md
-client-modules.md: 19bcc6304e9d917c3950fd9857e7b2c2b3c16e73
-client-modules.zh.md: b0ad293cad2f67de1982ef271308b2a7f06ebaf4
+client-modules.md: 808fa62b2e5a4351b1dc98bbe4f3d2af63c9dd2b
+client-modules.zh.md: dcab60bea7c54770cc5e6032afb39d6dd189d037
diff --git a/docs/subsystems/client-modules.md b/docs/subsystems/client-modules.md
index 19bcc6304e..808fa62b2e 100644
--- a/docs/subsystems/client-modules.md
+++ b/docs/subsystems/client-modules.md
@@ -12,7 +12,7 @@ The graph is the wire single source between the Node and browser halves: the hos
 
 ```ts type-equiv
 /**
- * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * One composed client entry pushed by the host (a graph row). Wire
  * single source: the host node half (package root) produces this same shape.
  * `immediately` marks stage-one prefetch; `inject` is informational graph
  * metadata (the authoritative edges live in each package's dshClient
diff --git a/docs/subsystems/client-modules.zh.md b/docs/subsystems/client-modules.zh.md
index b0ad293cad..dcab60bea7 100644
--- a/docs/subsystems/client-modules.zh.md
+++ b/docs/subsystems/client-modules.zh.md
@@ -12,7 +12,7 @@ Web 插件表：[dsh-client-modules](../../packages/client/modules) 中 client 
 
 ```ts type-equiv
 /**
- * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * One composed client entry pushed by the host (a graph row). Wire
  * single source: the host node half (package root) produces this same shape.
  * `immediately` marks stage-one prefetch; `inject` is informational graph
  * metadata (the authoritative edges live in each package's dshClient
diff --git a/docs/subsystems/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml
index cbe983a780..47783d5f77 100644
--- a/docs/subsystems/code-runtime.i18n.yaml
+++ b/docs/subsystems/code-runtime.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 docs/subsystems/code-runtime.md
-code-runtime.md: 8a767287414824e6f76659c02c47193522eb21c7
-code-runtime.zh.md: e6bb7cb93cb542dceb2c7e335162a03429d161e8
+code-runtime.md: 6d3fa7fa72891897155cb9c611c7aa472629de4f
+code-runtime.zh.md: 47516c7d21c24399498a05410ab9a46b61736fb4
diff --git a/docs/subsystems/code-runtime.md b/docs/subsystems/code-runtime.md
index 8a76728741..6d3fa7fa72 100644
--- a/docs/subsystems/code-runtime.md
+++ b/docs/subsystems/code-runtime.md
@@ -187,5 +187,5 @@ Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and subs
 abstract run(request: CodeRunRequest): Promise<CodeRunResult>
 ```
 
-Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
+Source: [`packages/code-runtime/code-runtime/src/index.ts:102`](../../packages/code-runtime/code-runtime/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md
index e6bb7cb93c..47516c7d21 100644
--- a/docs/subsystems/code-runtime.zh.md
+++ b/docs/subsystems/code-runtime.zh.md
@@ -187,5 +187,5 @@ Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and subs
 abstract run(request: CodeRunRequest): Promise<CodeRunResult>
 ```
 
-Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts)
+Source: [`packages/code-runtime/code-runtime/src/index.ts:102`](../../packages/code-runtime/code-runtime/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml
index 5e7c6d92be..d2fe7303fc 100644
--- a/docs/subsystems/compaction.i18n.yaml
+++ b/docs/subsystems/compaction.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 docs/subsystems/compaction.md
-compaction.md: 8325694d92aa1a3019aef8f6b0c1f99d45ad0df5
-compaction.zh.md: 9f9014b8c1c1db12abc6581fbe6ebacfac3dd6fe
+compaction.md: fdff28ac2ec83966a03050ba8d54fe0ee26c4fc6
+compaction.zh.md: e4227320d9829cac695dc4ba0c5779086f77194b
diff --git a/docs/subsystems/compaction.md b/docs/subsystems/compaction.md
index 8325694d92..fdff28ac2e 100644
--- a/docs/subsystems/compaction.md
+++ b/docs/subsystems/compaction.md
@@ -8,7 +8,7 @@ Source: [`packages/compact/compact/src/types.ts`](../../packages/compact/compact
 
 ## The `compact/*` session events
 
-Compaction extends [`SessionEventMap`](session.md) with three event types via declaration merging. All three are **log-only** — they record the lock, summary, selected range, shadowed event seqs, token count, and model call without joining the surface. `SurfaceEventType` is deliberately NOT extended (only message-producing events reach the model), so the summary itself rides on a separate `user/message` with `surfaceOp: { op: 'replace', start, end }` — the only surface mutation performed by summary compaction. See the Agent Note for why reusing `user/message` is honest rather than a workaround.
+Compaction extends [`SessionEventMap`](session.md) with three event types via declaration merging. All three are **log-only** — they record the lock, summary, selected range, shadowed event seqs, token count, and model call without joining the surface. `SurfaceEventType` is deliberately NOT extended (only message-producing events reach the model), so the summary itself rides on a separate `user/message` with `surfaceOp: { op: 'replace', start, end }` — the only surface mutation performed by summary compaction. The [Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) owns the rationale for reusing `user/message`.
 
 | Event | Payload | Role |
 |---|---|---|
diff --git a/docs/subsystems/compaction.zh.md b/docs/subsystems/compaction.zh.md
index 9f9014b8c1..e4227320d9 100644
--- a/docs/subsystems/compaction.zh.md
+++ b/docs/subsystems/compaction.zh.md
@@ -8,7 +8,7 @@
 
 ## `compact/*` 会话事件
 
-压缩通过声明合并为 [`SessionEventMap`](session.md) 扩展三种事件类型。三者都**仅写入日志**——它们记录锁、摘要、选中范围、被遮蔽事件 seq、token 数以及模型调用，绝不进入 surface。这里有意不扩展 `SurfaceEventType`（只有产生消息的事件才到达模型），因此摘要本身承载在另一条带有 `surfaceOp: { op: 'replace', start, end }` 的 `user/message` 上——这是摘要压缩执行的唯一 surface 变更。关于复用 `user/message` 为何是如实建模而非权宜之计，见对应 Agent Note。
+压缩通过声明合并为 [`SessionEventMap`](session.md) 扩展三种事件类型。三者都**仅写入日志**——它们记录锁、摘要、选中范围、被遮蔽事件 seq、token 数以及模型调用，绝不进入 surface。这里有意不扩展 `SurfaceEventType`（只有产生消息的事件才到达模型），因此摘要本身承载在另一条带有 `surfaceOp: { op: 'replace', start, end }` 的 `user/message` 上——这是摘要压缩执行的唯一 surface 变更。[Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) 负责复用 `user/message` 的决策依据。
 
 | 事件 | 载荷 | 作用 |
 |---|---|---|
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index f7d59cd66d..91c13a23c5 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: dd81cc27ad73bab026cd11da6ab184890bb6535d
-filesystem.zh.md: 9589adfaf43c1d5a4bbc8571e70c878770d880b2
+filesystem.md: 23ade1ede1592f7c8e1e409f3f9ca30f4f3f7e6f
+filesystem.zh.md: da2ac2583c381a89e0bd656018d799b22da0f1de
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index dd81cc27ad..23ade1ede1 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -269,7 +269,7 @@ type FsErrorCode =
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise, and an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a `timeoutMs` here would be a deadline the seam cannot enforce, and an implicit default in the exact place explicit-over-implicit forbids. Cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
 
 ## The service and the plugin
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 9589adfaf4..da2ac2583c 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -269,7 +269,7 @@ type FsErrorCode =
 
 ## 文件 IO 不设超时
 
-`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方约定也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的截止时间会成为无法兑现承诺的旋钮，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。两个参照 agent（Claude Code、Codex）出于同样原因不给文件 IO 计时；取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
+`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方约定也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的 `timeoutMs` 会成为 seam 无法强制执行的截止时间，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
 
 ## 服务与插件
 
diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml
index 1808f2d8e4..86ec4e3c3f 100644
--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: 0cfce7a06d1db73268e2457c4979d1b1ccc889b7
-llm-streaming.zh.md: 19541462805c50b0ed446a346523d20de91d0351
+llm-streaming.md: 4d450c19ec2bbfacabcefc83466e67c8a6c82bd6
+llm-streaming.zh.md: 777c44eaff2b1ee6e5939e04e580d6ad34b1ad1a
diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md
index 0cfce7a06d..4d450c19ec 100644
--- a/docs/subsystems/llm-streaming.md
+++ b/docs/subsystems/llm-streaming.md
@@ -87,8 +87,8 @@ Producer identity and content shape are independent. `kind` answers *who produce
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
- * producers share one form (three snapshot producers today), and one producer
- * may emit more than one form over a session.
+ * producers share one form, and one producer may emit more than one form over
+ * a session.
  *
  * The vocabulary is SEMANTIC, never visual: a value states that the content is
  * a file's instructions or a catalog of available items, and a consumer decides
@@ -209,11 +209,9 @@ Every adapter MUST obey these, and every consumer may rely on them:
 - **Provider stalls are bounded at the transport.** Both shipping remote adapters expose positive finite `streamIdleTimeoutMs` with a five-minute default. The watchdog arms only while iterator `next()` is outstanding, uses one stable signal for the whole request, maps its own expiry to `TIMEOUT`, and keeps an earlier caller abort as `ABORTED`.
 - **Context overflow has one canonical code.** Both DeepSeek adapters classify explicit provider detail through `isContextWindowExceededError()` and surface `CONTEXT_WINDOW_EXCEEDED`, whether the failure arrives as a thrown HTTP `LlmError` or an in-band finish error. Consumers route on the code, never provider text.
 - **An empty completion is a retryable error, not a silent success.** Both adapters map a terminal `stop` finish that carried no content blocks to `finish {kind:'error'}` with the canonical `EMPTY_RESPONSE` code, and `dsh-llm-retry` retries it by default; see [empty model responses are retryable](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md).
-- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test (mock server asserting the received header, or the library's header hook for a library-backed adapter).
+- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test.
 - **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmService` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content plus provider/model fields without the private state.
 
-This contract is pinned down by two deliberately independent implementations: `dsh-llm-deepseek` (direct fetch, SSE framing via `eventsource-parser`) and `dsh-llm-pi-ai` (a generic multi-provider adapter through `@earendil-works/pi-ai`). The library-backed adapter exercises the finish-chunk error path, while transport-boundary tests prove each idle watchdog stops its actual request.
-
 ## `ResolvedRetryPolicy`
 
 Provider configuration resolves before route registration into an immutable discriminated union. Normal mode carries `mode: 'normal'`, finite `maxRetries`, `retryableCodes`, and required `initialDelayMs`, `maxDelayMs`, and `jitterRatio`; always mode carries `mode: 'always'` and the same required backoff fields without a finite maximum. `LlmService.providerRetryPolicy(provider)` returns the currently registered value and supplies normal defaults when the adapter omits one; `llmRetryPolicyOf(stream)` returns the exact serving registration's captured value after that call enters its final adapter boundary, so later route disposal or replacement cannot change an in-flight failure's recovery policy. The [generated config catalog](../config-catalog.md) owns the optional input shapes.
diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md
index 1954146280..777c44eaff 100644
--- a/docs/subsystems/llm-streaming.zh.md
+++ b/docs/subsystems/llm-streaming.zh.md
@@ -87,8 +87,8 @@ interface MessageSourceMap {
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
- * producers share one form (three snapshot producers today), and one producer
- * may emit more than one form over a session.
+ * producers share one form, and one producer may emit more than one form over
+ * a session.
  *
  * The vocabulary is SEMANTIC, never visual: a value states that the content is
  * a file's instructions or a catalog of available items, and a consumer decides
@@ -213,11 +213,9 @@ interface LlmFailure {
 - **提供方停顿在传输层受到时限约束。** 两个已交付的远程适配器都暴露正数且有限的 `streamIdleTimeoutMs`，默认五分钟。watchdog 只在 iterator `next()` 尚未完成时启动，整个请求使用同一个稳定 signal，把自身到期映射为 `TIMEOUT`，并把更早发生的调用方中止保留为 `ABORTED`。
 - **上下文溢出只有一个规范 code。** 两个 DeepSeek 适配器都通过 `isContextWindowExceededError()` 对提供方的显式细节分类并暴露 `CONTEXT_WINDOW_EXCEEDED`，无论失败以抛出的 HTTP `LlmError` 还是带内 finish error 到达。消费方按 code 路由，绝不依赖提供方文本。
 - **空 completion 是可重试错误，而不是静默的成功结果。** 两个适配器都把没有携带任何内容块的终止性 `stop` 结束映射为携带规范 `EMPTY_RESPONSE` code 的 `finish {kind:'error'}`，`dsh-llm-retry` 默认会重试它；详见[空模型响应可重试](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md)。
-- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
+- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明。
 - **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容以及提供方／模型字段，不会收到私有状态。
 
-该约定由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
-
 ## `ResolvedRetryPolicy`
 
 提供方配置会在路由注册前解析为不可变的可辨识联合。normal mode 携带 `mode: 'normal'`、有限的 `maxRetries`、`retryableCodes`，以及必填的 `initialDelayMs`、`maxDelayMs` 与 `jitterRatio`；always mode 携带 `mode: 'always'` 和相同的必填退避字段，但没有有限上限。`LlmService.providerRetryPolicy(provider)` 返回当前注册的值，并在适配器省略策略时提供 normal 默认值；调用进入最终适配器边界后，`llmRetryPolicyOf(stream)` 返回为其提供服务的确切注册所捕获的值，因此之后释放或替换路由都无法改变进行中失败的恢复策略。可选输入形状由[生成的配置目录](../config-catalog.md)规定。
diff --git a/docs/subsystems/lsp.i18n.yaml b/docs/subsystems/lsp.i18n.yaml
index 400274ceef..00e509db87 100644
--- a/docs/subsystems/lsp.i18n.yaml
+++ b/docs/subsystems/lsp.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 docs/subsystems/lsp.md
-lsp.md: f8fa2be3d79c0aff9b288f61bf64bbb91e327f1d
-lsp.zh.md: fc9214fa7b10c2dac2a6cd90e0c29776313653f4
+lsp.md: 96a365a7f16e53a6c8b28fdc5997724bcbf81115
+lsp.zh.md: 28b16cab9cb302de7db76be0b12788d1bef04541
diff --git a/docs/subsystems/lsp.md b/docs/subsystems/lsp.md
index f8fa2be3d7..96a365a7f1 100644
--- a/docs/subsystems/lsp.md
+++ b/docs/subsystems/lsp.md
@@ -14,7 +14,7 @@ The seam and model expose exactly four semantic queries; the union is closed, so
 /**
  * The four semantic queries the seam and model expose. A closed union: adding an operation is a
  * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
- * deliberately deferred (they need different schemas).
+ * not operations here; they need different schemas.
  */
 type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
 ```
diff --git a/docs/subsystems/lsp.zh.md b/docs/subsystems/lsp.zh.md
index fc9214fa7b..28b16cab9c 100644
--- a/docs/subsystems/lsp.zh.md
+++ b/docs/subsystems/lsp.zh.md
@@ -14,7 +14,7 @@ seam 与模型恰好公开 4 项语义查询；该联合是闭合的，因此新
 /**
  * The four semantic queries the seam and model expose. A closed union: adding an operation is a
  * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
- * deliberately deferred (they need different schemas).
+ * not operations here; they need different schemas.
  */
 type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
 ```
diff --git a/docs/subsystems/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml
index eb5478eef8..f198d0a25e 100644
--- a/docs/subsystems/persistence.i18n.yaml
+++ b/docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: 991efe39a059e08cdf7904b473486b336cb2071c
-persistence.zh.md: 2391eeb2a751388b6aa139d0646b52fe5af04601
+persistence.md: 640e2c0122b01ae869d20c1805742abad782c95b
+persistence.zh.md: 7e28d6d1f63a78741840fb74194d3249696423ae
diff --git a/docs/subsystems/persistence.md b/docs/subsystems/persistence.md
index 991efe39a0..640e2c0122 100644
--- a/docs/subsystems/persistence.md
+++ b/docs/subsystems/persistence.md
@@ -4,7 +4,7 @@ English | [中文](persistence.zh.md)
 
 The **durability seam** for the event log. [session.md](session.md) describes the in-memory `Session` — the append-only `SessionEvent` log that is the source of truth. This page describes how that log is made durable: the abstract `SessionPersistence` service, its backends, the flush checkpoint, crash recovery, and the metadata header that travels alongside the log. The event vocabulary the log carries is enumerated, member by member, in the generated [persistence log event catalog](../persistence-catalog.md).
 
-The seam is a textbook [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted event type** — and two interchangeable backends implementing the same contract. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
+The seam is a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted event type** — and two interchangeable backends implementing the same contract. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
 
 ## The flush checkpoint
 
@@ -200,7 +200,7 @@ interface SessionPersistenceSnapshot {
 
 ## The backends
 
-Both implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass `runPersistenceContract`:
+Both implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass the shared `runPersistenceContract` suite:
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)** — `node:sqlite`, one row per `SessionEvent`. The row shape `(session_id, seq, type, time, data, source_event_seqs, surface_op)` maps 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
diff --git a/docs/subsystems/persistence.zh.md b/docs/subsystems/persistence.zh.md
index 2391eeb2a7..7e28d6d1f6 100644
--- a/docs/subsystems/persistence.zh.md
+++ b/docs/subsystems/persistence.zh.md
@@ -4,7 +4,7 @@
 
 事件日志的**持久性 seam**。[session.md](session.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.md)中逐项列举。
 
-该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一约定的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
+该 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一约定的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
 
 ## flush 检查点
 
@@ -200,7 +200,7 @@ interface SessionPersistenceSnapshot {
 
 ## 后端
 
-两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过 `runPersistenceContract`：
+两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过共享的 `runPersistenceContract` 套件：
 
 - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行结构 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。
diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml
index 54cadaf5b5..823ed61107 100644
--- a/docs/subsystems/session-projection.i18n.yaml
+++ b/docs/subsystems/session-projection.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 docs/subsystems/session-projection.md
-session-projection.md: ddb3877618904d3185eba7d9d351afbcc81b2d04
-session-projection.zh.md: 39e6099130ba0d91e72e8f1afd5661e5894f8d0f
+session-projection.md: d91a3faa50dc092d89aa2c7d5ce1e6118df7ebd6
+session-projection.zh.md: 7dac3db8470a2941b711db6a30fced8dbe7c7a8d
diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md
index ddb3877618..d91a3faa50 100644
--- a/docs/subsystems/session-projection.md
+++ b/docs/subsystems/session-projection.md
@@ -2,7 +2,7 @@
 
 English | [中文](session-projection.zh.md)
 
-The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the Service Definition and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame today). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
+The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the Service Definition and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
 
 Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 
diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md
index 39e6099130..7dac3db847 100644
--- a/docs/subsystems/session-projection.zh.md
+++ b/docs/subsystems/session-projection.zh.md
@@ -2,7 +2,7 @@
 
 [English](session-projection.md) | 中文
 
-会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是 Service Definition 与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（今天是 [dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流约定：[包（package）README](../../packages/session/session-projection/README.md)。
+会话投影 seam 是一项[能力 seam](../capability-seams.md)：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是 Service Definition 与注册表（[dsh-session-projection](../../packages/session/session-projection)，`ctx.sessionProjections`）、领域贡献方（每个领域注册一个纯单元）与载体（[dsh-host-apiproxy](../../packages/host/apiproxy) 的历史尾页与 `session/projection` 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 `session/event`，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：[session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)；驱动、缓存与变更流约定：[包（package）README](../../packages/session/session-projection/README.md)。
 
 源码：[`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
 
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 4c8cad1880..3b9f9ce01d 100644
--- a/docs/subsystems/session.i18n.yaml
+++ b/docs/subsystems/session.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 docs/subsystems/session.md
-session.md: e5eb78908ba4b7ebfc398d5c735969a5a8937374
-session.zh.md: 51729999a831c94e87e36ec1c4705201f9c8360f
+session.md: f5b9e63e2320885cc41b30a09398dd341700152d
+session.zh.md: 985e0a448d1cf860ccbb0f2885d855ad6830af9f
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index e5eb78908b..f5b9e63e23 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -171,7 +171,7 @@ interface EpochHeader {
 }
 ```
 
-Canonical form represents an empty system prompt or tool list as an absent field, matching how requests are built. Legacy v0 logs containing the removed `request/header-delta` event or its full-snapshot `fallback` reason are rejected at seed, append, and persistence-load boundaries rather than replayed incompletely.
+Canonical form represents an empty system prompt or tool list as an absent field, matching how requests are built. Legacy v0 logs containing the legacy `request/header-delta` event or its full-snapshot `fallback` reason are rejected at seed, append, and persistence-load boundaries rather than replayed incompletely.
 
 ### The route capacity event: `request/context`
 
@@ -266,7 +266,8 @@ type SurfaceEventType =
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
  *   surface nodes in the current surface. `start === end` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction and possible other manipulations.
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
  */
 type SurfaceOp =
   | 'append'
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 51729999a8..985e0a448d 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -173,7 +173,7 @@ interface EpochHeader {
 }
 ```
 
-规范形式：空系统提示词和空工具列表都表示为字段缺失，与请求构建方式一致。包含已移除的 `request/header-delta` 事件或完整快照原因为 `fallback` 的旧版 v0 日志，会在 seed、append 和持久化加载边界被拒绝，而不会以不完整方式回放。
+规范形式：空系统提示词和空工具列表都表示为字段缺失，与请求构建方式一致。包含旧版 `request/header-delta` 事件或完整快照原因为 `fallback` 的旧版 v0 日志，会在 seed、append 和持久化加载边界被拒绝，而不会以不完整方式回放。
 
 ### 路由容量事件：`request/context`
 
@@ -268,7 +268,8 @@ type SurfaceEventType =
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
  *   surface nodes in the current surface. `start === end` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction and possible other manipulations.
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
  */
 type SurfaceOp =
   | 'append'
diff --git a/docs/subsystems/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml
index 5945dfb286..a169374140 100644
--- a/docs/subsystems/skills.i18n.yaml
+++ b/docs/subsystems/skills.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 docs/subsystems/skills.md
-skills.md: 1c3d683c6fb2c2ac26e00c32329e41b8d4636fb1
-skills.zh.md: b38effdd5858625bb1aa5f10108d5d654f692b7c
+skills.md: 696f759179203230bf748c8a4be2cee333acd9a3
+skills.zh.md: d2244e86f0ceaf77c1eab02508dc3f07df727dbb
diff --git a/docs/subsystems/skills.md b/docs/subsystems/skills.md
index 1c3d683c6f..696f759179 100644
--- a/docs/subsystems/skills.md
+++ b/docs/subsystems/skills.md
@@ -80,7 +80,7 @@ Chokidar watches existing roots for direct bundle/flat-entry additions and remov
 
 ## Skill identity
 
-Skill names are kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). The local provider accepts directory bundles (`<name>/SKILL.md`) and flat Markdown files (`<name>.md`). Nested recursive `**/SKILL.md` discovery is intentionally outside v1.
+Skill names are kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). The local provider accepts directory bundles (`<name>/SKILL.md`) and flat Markdown files (`<name>.md`). Nested recursive `**/SKILL.md` discovery is not supported.
 
 ```ts type-equiv
 /** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */
diff --git a/docs/subsystems/skills.zh.md b/docs/subsystems/skills.zh.md
index b38effdd58..d2244e86f0 100644
--- a/docs/subsystems/skills.zh.md
+++ b/docs/subsystems/skills.zh.md
@@ -80,7 +80,7 @@ Chokidar 会监视现有根目录中直属 bundle 和平铺条目的添加与移
 
 ## skill 身份
 
-skill 名称为 kebab-case（`^[a-z0-9]+(?:-[a-z0-9]+)*$`）。本地提供方接受目录包（`<name>/SKILL.md`）和扁平 Markdown 文件（`<name>.md`）。嵌套递归的 `**/SKILL.md` 发现有意不在 v1 范围内。
+skill 名称为 kebab-case（`^[a-z0-9]+(?:-[a-z0-9]+)*$`）。本地提供方接受目录包（`<name>/SKILL.md`）和扁平 Markdown 文件（`<name>.md`）。嵌套递归的 `**/SKILL.md` 发现不受支持。
 
 ```ts type-equiv
 /** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */
diff --git a/docs/subsystems/storage.i18n.yaml b/docs/subsystems/storage.i18n.yaml
index 5b4d6d1040..9b3d8a19d6 100644
--- a/docs/subsystems/storage.i18n.yaml
+++ b/docs/subsystems/storage.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 docs/subsystems/storage.md
-storage.md: 94d3c3f39a65462cd8cd58a65b02066d5bad4b8c
-storage.zh.md: c3cea8eb5e44f2e589b0196dc690c6473e3552ca
+storage.md: 3234fdf9587dc2853b4f9ec4205d230aae4b633a
+storage.zh.md: fb13ec96099f2173478aecf1b91799237755414c
diff --git a/docs/subsystems/storage.md b/docs/subsystems/storage.md
index 94d3c3f39a..3234fdf958 100644
--- a/docs/subsystems/storage.md
+++ b/docs/subsystems/storage.md
@@ -44,7 +44,7 @@ interface StorageBackend {
 }
 ```
 
-A backend owns one medium (a file-tree root, a database file) and exposes optional data-shape facets; `kv` is the only facet today. `KvFacet.open(descriptor)` opens one named unit — `KvUnitDescriptor` carries the name, format version, table names, and whether a global singleton slot exists — and returns a `KvUnit` with `loadAll`, `putRecord`, `deleteRecord`, `setGlobal`, and `close`. Unit and table names must match `UNIT_NAME_RE` (safe as a file name and as a SQL identifier segment); record keys are arbitrary strings that never reach file paths. A unit does not serialize concurrent writes — ordering belongs to the caller — but each single call is atomic on the medium and durable once resolved. A medium stamped with a different version rejects `version-mismatch`; one that cannot be parsed as the unit rejects `malformed-medium` (no migration, pre-release stance). [`backend.ts`](../../packages/storage/storage/src/backend.ts) is the normative clause-by-clause contract, and the shared conformance suite in [`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) asserts every clause against each backend. The [json backend](../../packages/storage/storage-json/README.md) republishes one whole human-readable file per unit atomically; the [sqlite backend](../../packages/storage/storage-sqlite/README.md) stores document-per-row in one database, the route for high-churn domains.
+A backend owns one medium (a file-tree root, a database file) and exposes optional data-shape facets; `kv` is the sole facet. `KvFacet.open(descriptor)` opens one named unit — `KvUnitDescriptor` carries the name, format version, table names, and whether a global singleton slot exists — and returns a `KvUnit` with `loadAll`, `putRecord`, `deleteRecord`, `setGlobal`, and `close`. Unit and table names must match `UNIT_NAME_RE` (safe as a file name and as a SQL identifier segment); record keys are arbitrary strings that never reach file paths. A unit does not serialize concurrent writes — ordering belongs to the caller — but each single call is atomic on the medium and durable once resolved. A medium stamped with a different version rejects `version-mismatch`; one that cannot be parsed as the unit rejects `malformed-medium` (no migration, pre-release stance). [`backend.ts`](../../packages/storage/storage/src/backend.ts) is the normative clause-by-clause contract, and the shared conformance suite in [`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) asserts every clause against each backend. The [json backend](../../packages/storage/storage-json/README.md) republishes one whole human-readable file per unit atomically; the [sqlite backend](../../packages/storage/storage-sqlite/README.md) stores document-per-row in one database, the route for high-churn domains.
 
 ## Declaring a domain
 
@@ -122,7 +122,7 @@ interface DomainChangedBase {
 type DomainChanged = DomainChangedPut | DomainChangedDeleted
 ```
 
-`put` (inserts, overwrites, and global writes) carries the new snapshot in `value` — never the old value; a diffing consumer keeps its own previous snapshot. `deleted` is a tombstone with no value. The event is a notification, not a transaction participant: the commit point has passed at emission, so a synchronously throwing listener is contained with a logged warning rather than rejecting the already-durable write, and emitted values equal the in-memory state at emission. The event is in-process only; cross-process change push is deferred work recorded in the [package README](../../packages/storage/storage-domain/README.md).
+`put` (inserts, overwrites, and global writes) carries the new snapshot in `value` — never the old value; a diffing consumer keeps its own previous snapshot. `deleted` is a tombstone with no value. The event is a notification, not a transaction participant: the commit point has passed at emission, so a synchronously throwing listener is contained with a logged warning rather than rejecting the already-durable write, and emitted values equal the in-memory state at emission. The event is in-process only; cross-process change push is a recorded limitation ([package README](../../packages/storage/storage-domain/README.md)).
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/storage.zh.md b/docs/subsystems/storage.zh.md
index c3cea8eb5e..fb13ec9609 100644
--- a/docs/subsystems/storage.zh.md
+++ b/docs/subsystems/storage.zh.md
@@ -44,7 +44,7 @@ interface StorageBackend {
 }
 ```
 
-一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并暴露可选的数据形状 facet；目前 `kv` 是唯一的 facet。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、格式版本、表名清单，以及是否存在全局单例槽位——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键是任意字符串，绝不进入文件路径。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的，且 resolve 后即已持久。介质上记录的版本与之不同时拒绝 `version-mismatch`；无法按该 unit 解析的介质拒绝 `malformed-medium`（不做迁移：预发布立场）。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性约定，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件对每个后端断言其中每一条款。[json 后端](../../packages/storage/storage-json/README.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.md)在单个数据库中按一行一文档存储，是高频更新领域的路由选择。
+一个后端拥有一个介质（一棵文件树的根目录、一个数据库文件），并暴露可选的数据形状 facet；`kv` 是唯一的 facet。`KvFacet.open(descriptor)` 打开一个具名 unit——`KvUnitDescriptor` 携带名称、格式版本、表名清单，以及是否存在全局单例槽位——并返回提供 `loadAll`、`putRecord`、`deleteRecord`、`setGlobal` 和 `close` 的 `KvUnit`。unit 名与表名必须匹配 `UNIT_NAME_RE`（既可安全用作文件名，也可安全用作 SQL 标识符片段）；记录键是任意字符串，绝不进入文件路径。unit 不对并发写入做串行化——顺序由调用方负责——但每次单独调用在介质上都是原子的，且 resolve 后即已持久。介质上记录的版本与之不同时拒绝 `version-mismatch`；无法按该 unit 解析的介质拒绝 `malformed-medium`（不做迁移：预发布立场）。[`backend.ts`](../../packages/storage/storage/src/backend.ts) 是逐条款的规范性约定，[`tests/contract.ts`](../../packages/storage/storage/tests/contract.ts) 中的共享一致性套件对每个后端断言其中每一条款。[json 后端](../../packages/storage/storage-json/README.md)以原子方式为每个 unit 整文件重新发布一份人类可读文件；[sqlite 后端](../../packages/storage/storage-sqlite/README.md)在单个数据库中按一行一文档存储，是高频更新领域的路由选择。
 
 ## 声明领域
 
@@ -122,7 +122,7 @@ interface DomainChangedBase {
 type DomainChanged = DomainChangedPut | DomainChangedDeleted
 ```
 
-`put`（插入、覆写和 global 写入）在 `value` 中携带新快照——绝不携带旧值；需要做差异比较的消费方自行保留上一份快照。`deleted` 是不携带值的墓碑。该事件是通知，不是事务参与者：发出时提交点已经过去，因此同步抛出的监听器会被兜住并记录一条警告，而不会让已经持久的写入被拒绝；发出的值等于发出时刻的内存态。该事件仅限进程内；跨进程的变更推送是延后工作，记录在[包 README](../../packages/storage/storage-domain/README.md)中。
+`put`（插入、覆写和 global 写入）在 `value` 中携带新快照——绝不携带旧值；需要做差异比较的消费方自行保留上一份快照。`deleted` 是不携带值的墓碑。该事件是通知，不是事务参与者：发出时提交点已经过去，因此同步抛出的监听器会被兜住并记录一条警告，而不会让已经持久的写入被拒绝；发出的值等于发出时刻的内存态。该事件仅限进程内；跨进程的变更推送是一项已记录的限制（[包 README](../../packages/storage/storage-domain/README.md)）。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 5e8fdefb08..e98438900d 100644
--- a/docs/subsystems/subagent.i18n.yaml
+++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md
-subagent.md: a14e9ec5fad3f25f231016c142c3965561790afe
-subagent.zh.md: 7bf3595324ecfec85329ea3f51ab5a8cc0d4c329
+subagent.md: 99c54e0696c9c3585c50285ecb69b14c90d83c11
+subagent.zh.md: c5a79247a81f5174662f2b5d1ed2d3c20cf6c672
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index a14e9ec5fa..99c54e0696 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -265,7 +265,7 @@ A local one-shot provider appends the descriptor inside the child's initial turn
 
 ## Durable enumeration: `listChildren()`, `listDescendants()`, and their entries
 
-`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query service, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry's `running`/`idle`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
+`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query service, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished (`unsupported` remains in the type but is never produced); a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` and `ctx.agents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and refines status through the live Agent registry's `running`/`idle`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
 
 `SubagentService.listDescendants(rootSessionId)` applies the same live-preferred corpus and projection-backed interpretation to the root's complete descendant tree in stable pre-order. Ordinary sessions and one-shot children remain traversal nodes, so continuable descendants below them are discovered; only `origin: 'subagent'` candidates produce rows. Each returned child or diagnostic adds its position from the enumerated durable header, while a cold inspection revalidates that complete lifecycle before serving identity:
 
@@ -411,7 +411,7 @@ interface SubagentProvider {
   /**
    * OPTIONAL (continuable-creation capability): contribute the detached
    * creation inputs that distinguish this provider's continuable children —
-   * today only whether the child session is seeded with parent history. Method
+   * only whether the child session is seeded with parent history. Method
    * presence IS the capability: the service rejects continuable starts on
    * providers without it, while a provider that has it may still serve
    * ordinary one-shot delegations.
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index 7bf3595324..c5a79247a8 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -265,7 +265,7 @@ interface ContinuableCreateSpec {
 
 ## 持久化枚举：`listChildren()`、`listDescendants()` 与其条目
 
-`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询服务，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询服务，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 约定负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分（`unsupported` 仍保留在类型中但从不产出）；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时要求 `ctx.subagents` 与 `ctx.agents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并通过在线 Agent 注册表将状态细化为 `running`／`idle`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 `SubagentService.listDescendants(rootSessionId)` 将同一份实时优先语料与基于投影的解释应用到根的完整后代树，并按稳定 pre-order 输出。普通会话和一次性 child 仍作为遍历节点，因此其下的可继续后代仍可发现；只有 `origin: 'subagent'` 的候选会生成条目。每个返回的 child 或 diagnostic 都从枚举所得的持久 header 附加树位置；冷检查在提供身份前还会重新校验完整生命周期：
 
@@ -413,7 +413,7 @@ interface SubagentProvider {
   /**
    * OPTIONAL (continuable-creation capability): contribute the detached
    * creation inputs that distinguish this provider's continuable children —
-   * today only whether the child session is seeded with parent history. Method
+   * only whether the child session is seeded with parent history. Method
    * presence IS the capability: the service rejects continuable starts on
    * providers without it, while a provider that has it may still serve
    * ordinary one-shot delegations.
diff --git a/docs/subsystems/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml
index e89be8fdc9..26064089c2 100644
--- a/docs/subsystems/subprocess.i18n.yaml
+++ b/docs/subsystems/subprocess.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 docs/subsystems/subprocess.md
-subprocess.md: eedf95abc2a51872ffc9964481bb3685ace31993
-subprocess.zh.md: 669baa52a92fc3869b057dc802c72989fa8cfcf1
+subprocess.md: 4fb20e1b440b8fc10540fa2adbd00ae63fd7e221
+subprocess.zh.md: a41f14aa550c4780b5661b546880d932d513b817
diff --git a/docs/subsystems/subprocess.md b/docs/subsystems/subprocess.md
index eedf95abc2..4fb20e1b44 100644
--- a/docs/subsystems/subprocess.md
+++ b/docs/subsystems/subprocess.md
@@ -293,8 +293,8 @@ Implementations must honor these semantics:
  * Resolve one configured executable in this provider's execution world.
  * Absolute paths are verified; bare names use the provider's scrubbed PATH
  * plus explicit environment overrides. Relative paths containing separators
- * are rejected: no current consumer defines which directory they would
- * resolve against, so providers fail loud instead of guessing.
+ * are rejected: the resolution base is undefined, so providers fail loud
+ * instead of guessing.
  * @param command - absolute executable path or bare PATH name.
  * @param env - explicit environment entries used for lookup.
  * @param signal - aborts remote or local lookup.
diff --git a/docs/subsystems/subprocess.zh.md b/docs/subsystems/subprocess.zh.md
index 669baa52a9..a41f14aa55 100644
--- a/docs/subsystems/subprocess.zh.md
+++ b/docs/subsystems/subprocess.zh.md
@@ -293,8 +293,8 @@ Implementations must honor these semantics:
  * Resolve one configured executable in this provider's execution world.
  * Absolute paths are verified; bare names use the provider's scrubbed PATH
  * plus explicit environment overrides. Relative paths containing separators
- * are rejected: no current consumer defines which directory they would
- * resolve against, so providers fail loud instead of guessing.
+ * are rejected: the resolution base is undefined, so providers fail loud
+ * instead of guessing.
  * @param command - absolute executable path or bare PATH name.
  * @param env - explicit environment entries used for lookup.
  * @param signal - aborts remote or local lookup.
diff --git a/docs/subsystems/telemetry.i18n.yaml b/docs/subsystems/telemetry.i18n.yaml
index ec9f0cd48b..c994c46baa 100644
--- a/docs/subsystems/telemetry.i18n.yaml
+++ b/docs/subsystems/telemetry.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 docs/subsystems/telemetry.md
-telemetry.md: c9e51eb38e680723ead0a88f4a9748620fd6b893
-telemetry.zh.md: 1af25c505574db6b3513547ae604eda66fc21766
+telemetry.md: 93869f2344eeedfee344735191af842fef188886
+telemetry.zh.md: 50642f1ed917ea52ee152e333f70753c12fba583
diff --git a/docs/subsystems/telemetry.md b/docs/subsystems/telemetry.md
index c9e51eb38e..93869f2344 100644
--- a/docs/subsystems/telemetry.md
+++ b/docs/subsystems/telemetry.md
@@ -84,7 +84,7 @@ interface TelemetryBackend {
    * leave this unimplemented and let their SDK's own batching cadence govern
    * export timing: a backend that does implement it owns the interaction
    * between its concurrent flushes and {@link shutdown}'s drain (the OTel
-   * backend removed its implementation for exactly that hazard — see the
+   * backend leaves it unimplemented for exactly that hazard — see the
    * revival Agent Note).
    */
   flush?(): void
diff --git a/docs/subsystems/telemetry.zh.md b/docs/subsystems/telemetry.zh.md
index 1af25c5055..50642f1ed9 100644
--- a/docs/subsystems/telemetry.zh.md
+++ b/docs/subsystems/telemetry.zh.md
@@ -84,7 +84,7 @@ interface TelemetryBackend {
    * leave this unimplemented and let their SDK's own batching cadence govern
    * export timing: a backend that does implement it owns the interaction
    * between its concurrent flushes and {@link shutdown}'s drain (the OTel
-   * backend removed its implementation for exactly that hazard — see the
+   * backend leaves it unimplemented for exactly that hazard — see the
    * revival Agent Note).
    */
   flush?(): void
diff --git a/docs/subsystems/web.i18n.yaml b/docs/subsystems/web.i18n.yaml
index f5e4289b30..8a11d774e6 100644
--- a/docs/subsystems/web.i18n.yaml
+++ b/docs/subsystems/web.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 docs/subsystems/web.md
-web.md: e6dc49353e50181b7844a658008edfa075cfedc3
-web.zh.md: 63f85a8d235e5c0778af8547251ebf2c299f036a
+web.md: 2a7cc499b42dd8b45ce6783a35a2fadd8df1183d
+web.zh.md: 6857f2a06a7d90702b6626409b4d8db914b3c465
diff --git a/docs/subsystems/web.md b/docs/subsystems/web.md
index e6dc49353e..2a7cc499b4 100644
--- a/docs/subsystems/web.md
+++ b/docs/subsystems/web.md
@@ -36,7 +36,8 @@ interface WebSearchRequest {
 ```ts type-equiv
 /**
  * Normalized search outcome. `content` is optional provider-generated answer
- * text or summary (Exa returns none; Perplexity returns a generated answer).
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
+ * generated answer).
  * `sources[]` is the portable citation surface. `truncated` is set by the seam
  * when it cut `sources[]` down to `maxResults`.
  */
@@ -50,8 +51,6 @@ interface WebSearchResult {
 }
 ```
 
-`content` is optional provider-generated answer text (Exa and DeepSeek return none; Perplexity returns a generated answer). `sources[]` is the portable citation surface. A source always has a `url`; `title`/`snippet`/`publishedAt` are optional because not every provider returns them — Perplexity citations may be URL-only, and forcing adapters to invent the rest would make the seam lie. `dsh-tool-web` renders `title ?? hostname(url)`.
-
 ```ts type-equiv
 /**
  * One citeable source. A source always has a URL; `title`, `snippet`, and
@@ -103,8 +102,6 @@ interface WebFetchResult {
 }
 ```
 
-`WebFetchBody` is a **closed** discriminated union owned by `dsh-web` (not a merge-extensible map): the provider decodes the kind and `dsh-tool-web` renders it, so a new kind is a coordinated change across known packages, not a plugin extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`, so adding a kind breaks compilation at every consumer until handled. Each arm stays its own object literal even where fields coincide today, leaving room for arm-specific fields later (a future `pdf` body's `pageCount`).
-
 ```ts type-equiv
 /**
  * The decoded body of a fetched resource. A CLOSED discriminated union owned by
@@ -112,8 +109,8 @@ interface WebFetchResult {
  * new kind is a coordinated change across known packages, not a plugin
  * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
  * so adding a kind breaks compilation at every consumer until handled. Each arm
- * stays its own object literal even where fields coincide today, leaving room
- * for arm-specific fields later (a `pdf` body's `pageCount`).
+ * stays its own object literal even where fields coincide, so an arm can gain
+ * fields the others lack.
  */
 type WebFetchBody =
   | { readonly kind: 'html'; readonly content: string }
@@ -132,7 +129,7 @@ Selection never depends on registration, config, or HMR order: a capability has
 
 ## The service
 
-`WebService` registers search and fetch providers, rejects duplicate ids with `WEB_DUPLICATE_PROVIDER`, and resolves providers at execution time with structured selection errors. The local fetch backend accepts only HTTP(S), rejects credentials, caps redirects, bytes, characters, and time, revalidates every same-origin redirect hop, and decodes the body; the tool owns presentation. Private-network blocking is deferred, so do not enable `web_fetch` where it can reach sensitive internal targets.
+`WebService` registers search and fetch providers, rejects duplicate ids with `WEB_DUPLICATE_PROVIDER`, and resolves providers at execution time with structured selection errors. The local fetch backend accepts only HTTP(S), rejects credentials, caps redirects, bytes, characters, and time, revalidates every same-origin redirect hop, and decodes the body; the tool owns presentation. The local backend does not block private-network targets; do not enable `web_fetch` where it can reach sensitive internal ones.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/web.zh.md b/docs/subsystems/web.zh.md
index 63f85a8d23..6857f2a06a 100644
--- a/docs/subsystems/web.zh.md
+++ b/docs/subsystems/web.zh.md
@@ -36,7 +36,8 @@ interface WebSearchRequest {
 ```ts type-equiv
 /**
  * Normalized search outcome. `content` is optional provider-generated answer
- * text or summary (Exa returns none; Perplexity returns a generated answer).
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
+ * generated answer).
  * `sources[]` is the portable citation surface. `truncated` is set by the seam
  * when it cut `sources[]` down to `maxResults`.
  */
@@ -50,8 +51,6 @@ interface WebSearchResult {
 }
 ```
 
-`content` 是提供方可选生成的回答文本（Exa 和 DeepSeek 不返回；Perplexity 返回生成式回答）。`sources[]` 是一套可跨提供方使用的引用数据结构。每个来源都必须有 `url`；`title`、`snippet` 和 `publishedAt` 为可选字段，因为并非每个提供方都会返回它们——Perplexity 的引用可能只有 URL，强迫适配器编造其余字段会让 seam 说谎。`dsh-tool-web` 渲染时使用 `title ?? hostname(url)`。
-
 ```ts type-equiv
 /**
  * One citeable source. A source always has a URL; `title`, `snippet`, and
@@ -103,8 +102,6 @@ interface WebFetchResult {
 }
 ```
 
-`WebFetchBody` 是 `dsh-web` 拥有的**封闭**可辨识联合类型（不是可合并扩展的 map）：提供方解码 kind，`dsh-tool-web` 渲染它，因此新增一个 kind 是已知包之间的协调变更，而非插件扩展。消费方对 `kind` 做 `switch` 并以 `default: assertNever(...)` 结尾，所以新增 kind 会在每个消费方处编译失败，直到被处理。即使各分支当前字段一致，每个分支仍保持独立的对象字面量，为将来分支特有字段留出空间（例如未来 `pdf` body 的 `pageCount`）。
-
 ```ts type-equiv
 /**
  * The decoded body of a fetched resource. A CLOSED discriminated union owned by
@@ -112,8 +109,8 @@ interface WebFetchResult {
  * new kind is a coordinated change across known packages, not a plugin
  * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
  * so adding a kind breaks compilation at every consumer until handled. Each arm
- * stays its own object literal even where fields coincide today, leaving room
- * for arm-specific fields later (a `pdf` body's `pageCount`).
+ * stays its own object literal even where fields coincide, so an arm can gain
+ * fields the others lack.
  */
 type WebFetchBody =
   | { readonly kind: 'html'; readonly content: string }
@@ -132,7 +129,7 @@ type WebFetchBody =
 
 ## 服务
 
-`WebService` 注册搜索与抓取提供方，以 `WEB_DUPLICATE_PROVIDER` 拒绝重复 id，并在执行时以结构化的选择错误解析提供方。本地抓取后端仅接受 HTTP(S)、拒绝凭证、限制重定向次数、字节数、字符数和时间、对每一跳同源重定向重新校验，并解码正文；展示由工具负责。SSRF／私有网络防护尚未实现，因此在能够触及敏感内部目标的环境中，禁止启用 `web_fetch`。
+`WebService` 注册搜索与抓取提供方，以 `WEB_DUPLICATE_PROVIDER` 拒绝重复 id，并在执行时以结构化的选择错误解析提供方。本地抓取后端仅接受 HTTP(S)、拒绝凭证、限制重定向次数、字节数、字符数和时间、对每一跳同源重定向重新校验，并解码正文；展示由工具负责。本地后端不会拦截私有网络目标；在能够触及敏感内部目标的环境中，禁止启用 `web_fetch`。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml
index fca76bf305..8809d62cd3 100644
--- a/docs/testing.i18n.yaml
+++ b/docs/testing.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 docs/testing.md
-testing.md: 296dd769118cc5498ddb1bb9c41e2c060b2a5bce
-testing.zh.md: 14b2549c4c3556b6d3bdd5b39d01dee885559dd1
+testing.md: 62ac375844b7f05970e944278fd44ac60f68b4b1
+testing.zh.md: 6353b2799b5760d8c45534d0264bf41be063d659
diff --git a/docs/testing.md b/docs/testing.md
index 296dd76911..62ac375844 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -12,7 +12,7 @@ How this repo tests, tier by tier, and the rules that keep a green suite meaning
 - **Snapshot** (`pnpm run test:snapshot`): keyless expected outputs cover external behavior — transport contracts and presentation, while persisted logs pin assembled backend behavior. ACP boots the real automation-server example, replays a recorded session, and diffs normalized JSON-RPC plus the re-persisted log ([ACP snapshot Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)); headless backend scenarios boot their explicit example composition through an unexported JSONL test driver, while `apps/cli` separately owns product `dsh run` acceptance. Use `pnpm run test:snapshot:record` when a model transcript changes and `pnpm run test:snapshot:refresh` when replay input remains valid; review every JSONL and expected-output diff. One ACP scenario (`text-turn`) pins full system-prompt/tool-schema content; other fixtures tokenize it so an edit churns one line ([pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
 - **Web browser snapshot** (`pnpm run test:web`; required Linux PR gate): Chromium compares replayed browser output with `apps/web/tests/snapshots/`. CI forces read-only `DSH_SNAPSHOT=replay`, never writing expected outputs; record/refresh stay local and every diff is reviewed ([web e2e lane](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md), [CI gate decision](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)). `test:web` [builds first](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md) for plugin CSS.
 
-Committed session-format JSONL uses the canonical packed-row layout, and the keyless snapshot gate discovers every such fixture by its `session` header. In-flight branches carrying older fixture edits merge current `master` and run the [temporary migrator](../scripts/migrate-packed-session-fixtures.ts) through `pnpm run migrate:packed-session-fixtures`; the [removal proposal](../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) retires that command and these links after all affected branches converge.
+Committed session-format JSONL uses the canonical packed-row layout, and the keyless snapshot gate discovers every such fixture by its `session` header; the [temporary migrator](../scripts/migrate-packed-session-fixtures.ts) rewrites older fixture layouts.
 
 ## The with-key policy: inference is cheap here
 
diff --git a/docs/testing.zh.md b/docs/testing.zh.md
index 14b2549c4c..6353b2799b 100644
--- a/docs/testing.zh.md
+++ b/docs/testing.zh.md
@@ -12,7 +12,7 @@
 - **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输约定与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
 - **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 将回放后的浏览器输出与 `apps/web/tests/snapshots/` 比较。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 车道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)以交付插件 CSS。
 
-签入仓库的会话格式 JSONL 使用规范打包行布局，无密钥快照门禁会通过 `session` header 发现每一份此类 fixture。仍携带旧版 fixture 改动的在途分支应合并当前 `master`，并通过 `pnpm run migrate:packed-session-fixtures` 运行[临时迁移器](../scripts/migrate-packed-session-fixtures.ts)；待所有受影响分支收敛后，[移除提案](../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)会移除该命令及这些链接。
+签入仓库的会话格式 JSONL 使用规范打包行布局，无密钥快照门禁会通过 `session` header 发现每一份此类 fixture；[临时迁移器](../scripts/migrate-packed-session-fixtures.ts)会改写旧版 fixture 布局。
 
 ## 带密钥策略：推理在这里很便宜
 
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index f6a41da266..58267e208d 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -19,7 +19,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`, `ctx.codeRuntime (execution time)`, `ctx.systemPrompt` | `tool/call`, `one tool/code-dispatch-start + tool/code-dispatch pair per bridged sub-call`, `tool/result` | - | Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode Agent Note). Under `code` it is the registry's only wire contribution; the other visible capabilities are declared in a generated SDK section in the loaded runtime's language, and a program calls them through bindings scheduled under the native concurrency contract (submission-ordered starts and policy; concurrency-safe bodies overlap up to `maxParallelSubCalls`) that re-enter the complete guarded tool pipeline and link each nested execution to this outer result. |
 | `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`, `ctx.systemPrompt`, `ctx.userInteraction (execution time, opportunistic)` | `tool/call`, `plan/mode inactive on an approved review`, `tool/result` | - | exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change. Its execute path rejects calls outside plan mode; in plan mode it presents the plan over the user-interaction seam (approve / keep planning with feedback), and approval logs plan mode inactive at the step boundary. |
 | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. |
-| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session; ConPTY is roadmap work), with native `C:\...` paths and `$env:NAME` variables. |
+| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt`, `ctx.bashEnv`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\...` paths and `$env:NAME` variables. |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `process-local temporary Plugin lifecycle` | - | Not in any shipped tree (a deliberate opt-in — temporary Plugin code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins created by cordis_mount may register ADDITIONAL model-visible tools until unmounted or DSH restarts; a full changed request header logs those tool-set changes. |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`, `ctx.pty`, `an owning Agent at execution time` | `tool/call`, `PTY shell state`, `tool/result` | - | One owner-isolated persistent bash tool; deployment composition supplies the PTY backend and may override the model-facing environment description. |
 | `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`, `ctx.fs` | `tool/call`, `fs/observed after view presence/absence, edit absence, or successful mutation`, `tool/result` | - | Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface. |
@@ -248,7 +248,7 @@ Execute a PowerShell command (`pwsh -Command`) and return its stdout/stderr. Eac
 
 Source: [`packages/bash/tool-pwsh/src/index.ts`](../packages/bash/tool-pwsh/src/index.ts)
 
-The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session; ConPTY is roadmap work), with native `C:\...` paths and `$env:NAME` variables.
+The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\...` paths and `$env:NAME` variables.
 
 ## `@deepseek-ai/dsh-tool-cordis`
 
diff --git a/docs/user/guide/config.i18n.yaml b/docs/user/guide/config.i18n.yaml
index d54550f499..7feb2c7f07 100644
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.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 docs/user/guide/config.md
-config.md: 3ce797e3dc91a279de1076a234c9ba0b476b3501
-config.zh.md: 621b5a75a98ab4b8d8517f4ec8894db0472e994c
+config.md: cd778065801ae58a46703ae3447f835f80abf062
+config.zh.md: 6f6d37bfe8f7ad29c154d65c1763279655006435
diff --git a/docs/user/guide/config.md b/docs/user/guide/config.md
index 3ce797e3dc..cd77806580 100644
--- a/docs/user/guide/config.md
+++ b/docs/user/guide/config.md
@@ -2,7 +2,7 @@
 
 English | [中文](config.zh.md)
 
-Harness uses `cordis.yml` to describe which plugins an agent loads and the configuration passed to each one. The file composes capabilities; the generated configuration catalog records the fields and defaults each package actually supports, avoiding a second hand-maintained reference.
+Harness uses `cordis.yml` to describe which plugins an agent loads and the configuration passed to each one. The file composes capabilities; the generated configuration catalog records the fields and defaults each package actually supports.
 
 ## Start from a real configuration
 
diff --git a/docs/user/guide/config.zh.md b/docs/user/guide/config.zh.md
index 621b5a75a9..6f6d37bfe8 100644
--- a/docs/user/guide/config.zh.md
+++ b/docs/user/guide/config.zh.md
@@ -2,7 +2,7 @@
 
 [English](config.md) | 中文
 
-Harness 使用 `cordis.yml` 描述 agent（智能体）加载哪些插件以及每个插件的参数。配置文件负责组合能力；每个包真正支持的字段和默认值由源码生成的配置目录负责记录，避免两份手写表格逐渐不一致。
+Harness 使用 `cordis.yml` 描述 agent（智能体）加载哪些插件以及每个插件的参数。配置文件负责组合能力；每个包真正支持的字段和默认值由源码生成的配置目录负责记录。
 
 ## 从真实配置开始
 
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 079dcf19ab..f4a719fdb2 100644
--- a/docs/user/guide/providers.i18n.yaml
+++ b/docs/user/guide/providers.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 docs/user/guide/providers.md
-providers.md: ad0bd3696dbbdc4a89334932196d72a0afd3d209
-providers.zh.md: 84c01b9b79768f8e3b84faf3ff32bbdb0dfbe74d
+providers.md: 29575fcc860721d35588d82a15d9b97f1b7dea0e
+providers.zh.md: 4b5fd32224fbfe5b685f886375b590fa3704505d
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index ad0bd3696d..29575fcc86 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -122,7 +122,7 @@ Under `dsh`, references resolve from the inherited environment, the Models page'
 
 ## Point an agent at the new provider
 
-A configured route appears in the web model picker and can be switched at any time, which is how most people use it.
+A configured route appears in the web model picker and can be switched at any time.
 
 Switching there also sets the default: the model you pick becomes the one the next new session starts on, recorded in `settings.yaml` under `agent-default-model`. There is no separate gesture.
 
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index 84c01b9b79..4b5fd32224 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -122,7 +122,7 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 ## 让 agent（智能体）用上新提供方
 
-配好的路由会出现在 Web 的模型选择器里，随时可切，这也是最常用的方式。
+配好的路由会出现在 Web 的模型选择器里，随时可切。
 
 在那里切换同时也就选定了默认值：你选的模型会成为下一个新会话的起点，记录在 `settings.yaml` 的 `agent-default-model` 段里。没有另一个单独的手势。
 
diff --git a/examples/acp-agent/tests/acp.e2e.ts b/examples/acp-agent/tests/acp.e2e.ts
index 16bf2fbf72..ce9a32c2ef 100644
--- a/examples/acp-agent/tests/acp.e2e.ts
+++ b/examples/acp-agent/tests/acp.e2e.ts
@@ -104,7 +104,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('acp-agent e2e: real prompt over
     const { client, updates } = spawned
 
     await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
-    // Any absolute cwd is honored now; use the temp `workdir` as this session's
+    // Any absolute cwd is honored; use the temp `workdir` as this session's
     // workspace (the bash tool will run there) — it need not equal the launch dir.
     const { sessionId } = await client.newSession({ cwd: workdir, mcpServers: [] })
 
diff --git a/examples/acp-agent/tests/escalation.e2e.ts b/examples/acp-agent/tests/escalation.e2e.ts
index ee2d6122bc..b94a78aa30 100644
--- a/examples/acp-agent/tests/escalation.e2e.ts
+++ b/examples/acp-agent/tests/escalation.e2e.ts
@@ -20,7 +20,7 @@ import { cleanupAcpExampleTest } from './cleanup.ts'
  *
  * Keyless smoke: boot the REAL `cordis.yml` through the `dsh-acp-agent` bin as
  * an ACP subprocess and drive initialize + session/new — the real-Loader-path
- * guard (postmortem 0001) for THIS tree's export shapes, which now include the
+ * guard (postmortem 0001) for THIS tree's export shapes, including the
  * sandbox executor AND the approval service. No prompt is sent, so neither the
  * model nor a sandbox runner is ever exercised.
  *
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
index e4fd9873aa..b09458ec3d 100644
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -447,9 +447,9 @@ describe('headless stream-json snapshots', () => {
       binArgs: [credentialsConfigPath, 'say pong'],
       tsconfigPath,
       env: {
-        // A key that exists but no HTTP header can carry — the paste this
-        // change exists for. Before it, `fetch` refused to build the header
-        // and the turn ended on a retried ByteString TypeError.
+        // A key that exists but no HTTP header can carry — the paste the
+        // credential guard exists for: without it, `fetch` refuses to build
+        // the header and the turn ends on a retried ByteString TypeError.
         DEEPSEEK_API_KEY: 'sk-\u{1F600}pasted-from-a-chat-window',
         DEEPSEEK_BASE_URL: '',
         NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
@@ -466,8 +466,8 @@ describe('headless stream-json snapshots', () => {
     // page at all.
     expect(normalized).toContain('the API key resolved from DEEPSEEK_API_KEY contains characters')
     expect(normalized).toContain('the web Models page writes it')
-    // Neither the key nor the transport-level symptom it used to produce may
-    // reach the user: the code point of one character is still the key.
+    // Neither the key nor its transport-level symptom (the ByteString error)
+    // may reach the user: the code point of one character is still the key.
     expect(normalized).not.toContain('pasted-from-a-chat-window')
     expect(normalized).not.toContain('ByteString')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
diff --git a/native/landlock-run/README.i18n.yaml b/native/landlock-run/README.i18n.yaml
index 58e58a26fe..6eb3457bdb 100644
--- a/native/landlock-run/README.i18n.yaml
+++ b/native/landlock-run/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 native/landlock-run/README.md
-README.md: fcb8e8249e6728d925fd08c938a780b155d3d4ac
-README.zh.md: 6ae8d7d1d5ae4f2bda90cbf6aa74321a0dab3cb9
+README.md: bf9b163d42a9b7402dbf4c045d47e7b8d36e15ab
+README.zh.md: 7bd4765a73f0d5df2a4710ce06ff319f6c902db6
diff --git a/native/landlock-run/README.md b/native/landlock-run/README.md
index fcb8e8249e..bf9b163d42 100644
--- a/native/landlock-run/README.md
+++ b/native/landlock-run/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 A [Landlock](https://landlock.io/) self-restrict-then-exec launcher for confining subprocesses on Linux, distributed as prebuilt per-platform npm packages plus a thin JS entry package that resolves the binary and speaks its CLI contract. Built for agent harnesses and other hosts that need to run untrusted commands under a filesystem allow-list without confining themselves.
 
-The first tool is **`landlock-run`** — a self-restrict-then-exec [Landlock](https://landlock.io/) launcher (~300 lines of C11 over the raw kernel UAPI, statically linked against musl). It installs a Landlock ruleset on itself and `exec`s the wrapped command; the ruleset is inherited across `execve`, so the command and every process it spawns run confined while the invoking process stays unrestricted. Fail-closed: if the kernel cannot enforce, it exits without running the command.
+The tool is **`landlock-run`** — a self-restrict-then-exec [Landlock](https://landlock.io/) launcher (~300 lines of C11 over the raw kernel UAPI, statically linked against musl). It installs a Landlock ruleset on itself and `exec`s the wrapped command; the ruleset is inherited across `execve`, so the command and every process it spawns run confined while the invoking process stays unrestricted. Fail-closed: if the kernel cannot enforce, it exits without running the command.
 
 ## Install
 
diff --git a/native/landlock-run/README.zh.md b/native/landlock-run/README.zh.md
index 6ae8d7d1d5..7bd4765a73 100644
--- a/native/landlock-run/README.zh.md
+++ b/native/landlock-run/README.zh.md
@@ -4,7 +4,7 @@
 
 一个 [Landlock](https://landlock.io/)「先限制自身、再执行」启动器，用于在 Linux 上限制子进程。它以按平台预构建的 npm 包以及一个轻量 JS 入口包的形式发布；入口包负责解析二进制文件并遵循其 CLI（命令行界面）约定。该启动器面向需要让不可信命令在文件系统允许清单约束下运行、同时保持自身不受限制的 agent harness（智能体框架）和其他宿主。
 
-第一个工具是 **`landlock-run`**：一个「先限制自身、再执行」的 [Landlock](https://landlock.io/) 启动器（基于原始内核 UAPI 编写，约 300 行 C11，并与 musl 静态链接）。它在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此命令及其产生的每个进程都在限制下运行，调用进程仍不受限制。它采用失败闭合：如果内核无法强制执行，则不运行命令并直接退出。
+该工具是 **`landlock-run`**：一个「先限制自身、再执行」的 [Landlock](https://landlock.io/) 启动器（基于原始内核 UAPI 编写，约 300 行 C11，并与 musl 静态链接）。它在自身上安装 Landlock 规则集，再 `exec` 被包装的命令；该规则集会跨 `execve` 继承，因此命令及其产生的每个进程都在限制下运行，调用进程仍不受限制。它采用失败闭合：如果内核无法强制执行，则不运行命令并直接退出。
 
 ## 安装
 
diff --git a/native/landlock-run/packages/entry/src/main.c b/native/landlock-run/packages/entry/src/main.c
index e4e1f5c17e..6f2b0f5639 100644
--- a/native/landlock-run/packages/entry/src/main.c
+++ b/native/landlock-run/packages/entry/src/main.c
@@ -89,8 +89,7 @@ struct landlock_path_beneath_attr {
 
 /*
  * Newest ABI this build knows; the negotiation below scales the actual
- * ruleset down to what the running kernel supports (the best-effort compat
- * stance of the previous Rust launcher, made explicit).
+ * ruleset down to what the running kernel supports.
  */
 #define MAX_ABI 5L
 
@@ -141,8 +140,7 @@ struct cli {
 };
 
 /*
- * Hand-rolled argv parsing — four flags do not justify a parsing library,
- * and the previous Rust launcher made the same call for the same reason.
+ * Hand-rolled argv parsing — four flags do not justify a parsing library.
  * Returns 0 on success, else the process exit code (message already printed).
  */
 static int parse(int argc, char **argv, struct cli *cli) {
@@ -204,8 +202,7 @@ static int add_rule(int ruleset_fd, const char *path, uint64_t access) {
   }
   /* The kernel rejects directory-only accesses on a non-directory rule
    * (EINVAL), so a file grant keeps only the file-compatible bits — how the
-   * `--rw /dev/null` grant works. Same clamp the Rust crate's
-   * path_beneath_rules helper applied. */
+   * `--rw /dev/null` grant works. */
   struct stat st;
   if (fstat(path_fd, &st) == 0 && !S_ISDIR(st.st_mode)) {
     access &= LL_FS_EXECUTE | LL_FS_WRITE_FILE | LL_FS_READ_FILE | LL_FS_TRUNCATE | LL_FS_IOCTL_DEV;
diff --git a/packages/bash/bash-sandbox/src/index.ts b/packages/bash/bash-sandbox/src/index.ts
index 32695c475d..240a707c65 100644
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -44,7 +44,7 @@ export type Config = LocalConfig
 export class SandboxBashExecutor extends LocalBashExecutor {
   static override inject = ['subprocess', 'sandbox', 'sandboxPolicy']
 
-  // No own Config: the sandbox default (mode + workspaceRoot) moved to
+  // No own Config: the sandbox default (mode + workspaceRoot) is owned by
   // ctx.sandboxPolicy, so this executor inherits LocalBashExecutor's Config
   // verbatim (the config catalog walks the inherited static).
 
diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml
index 597a17e088..d5cb0cb0e5 100644
--- a/packages/bash/bash/README.i18n.yaml
+++ b/packages/bash/bash/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/bash/bash/README.md
-README.md: 1230149bd03d07cfb6208d82ea6ee8e81751b2c8
-README.zh.md: 168ac9f40e01dc786e29933afb0ebc4c3a745d0f
+README.md: 23b0acd096bb835ef57563337c91e5cf63b58677
+README.zh.md: 14ba749a0018bd6a63475bc0ab72c6fe6d26893a
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index 1230149bd0..23b0acd096 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -13,7 +13,7 @@ This package owns the Service Definition role of the bash capability, split so e
 | `@deepseek-ai/dsh-bash-sandbox` | Service provider: `dsh-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts |
 | `@deepseek-ai/dsh-tool-bash` | the model-facing tool schemas over `ctx.bash` |
 
-The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. `dsh-bash-sandbox` is exactly that swap in action — a sandboxing executor behind the same Service Definition; the Consumer detects its `sandboxMode` capability and adds escalation fields without importing the provider. A containerized or remote executor slots in the same way.
+The split is a standard capability seam ([capability-seams Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): `dsh-bash-sandbox` is a sandboxing executor behind the same Service Definition — the Consumer detects its `sandboxMode` capability and adds escalation fields without importing the provider — and a containerized or remote executor slots in the same way.
 
 ## Service API (`ctx.bash`)
 
diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md
index 168ac9f40e..14ba749a00 100644
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -13,7 +13,7 @@
 | `@deepseek-ai/dsh-bash-sandbox` | Service provider：沿用 `dsh-bash-local` 的机制，但通过 [`ctx.sandbox`](../../sandbox/sandbox/) 限制每次 spawn，并将拒绝报告为结果事实 |
 | `@deepseek-ai/dsh-tool-bash` | 基于 `ctx.bash`、面向模型的工具 schema |
 
-该拆分与 LLM（大语言模型） seam（`LlmService`／`LlmAdapter`）及 agent（智能体）工具调研结果一致：pi 将执行隐藏在 `BashOperations` 接口之后（本地 shell／SSH／VM 后端），Codex 则隐藏在 exec-server 协议之后。`dsh-bash-sandbox` 正是这种替换的实际应用：沙箱执行器位于同一 Service Definition 之后；Consumer 检测其 `sandboxMode` 能力并添加升权字段，无需导入提供方。容器化或远程执行器也可以同样接入。
+该拆分是一个标准的能力 seam（[capability-seams Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：`dsh-bash-sandbox` 是位于同一 Service Definition 之后的沙箱执行器——Consumer 检测其 `sandboxMode` 能力并添加升权字段，无需导入提供方——容器化或远程执行器也可以同样接入。
 
 ## 服务 API（`ctx.bash`）
 
diff --git a/packages/bash/pwsh-local/README.i18n.yaml b/packages/bash/pwsh-local/README.i18n.yaml
index 4f25e9f6aa..1d26227716 100644
--- a/packages/bash/pwsh-local/README.i18n.yaml
+++ b/packages/bash/pwsh-local/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/bash/pwsh-local/README.md
-README.md: a06126e29ac5bf711bfbbb0d369e097b70918ba6
-README.zh.md: 947e994b59539d137cc1a332bb252a8325533747
+README.md: eb3365b009e3595230e5fb0f616079bd73c55840
+README.zh.md: d79201c756a26bbc343e2b284a803b0cf9aee69b
diff --git a/packages/bash/pwsh-local/README.md b/packages/bash/pwsh-local/README.md
index a06126e29a..eb3365b009 100644
--- a/packages/bash/pwsh-local/README.md
+++ b/packages/bash/pwsh-local/README.md
@@ -23,7 +23,7 @@ The package root exports the default and named `PwshLocalExecutor` plugin, its `
     pwshPath: C:\Program Files\PowerShell\7\pwsh.exe  # explicit executable; else well-known locations, then PATH
 ```
 
-## Behavior (and where it came from)
+## Behavior
 
 The Windows counterpart of `dsh-bash-local`, deliberately mirroring its semantics call-for-call:
 
diff --git a/packages/bash/pwsh-local/README.zh.md b/packages/bash/pwsh-local/README.zh.md
index 947e994b59..d79201c756 100644
--- a/packages/bash/pwsh-local/README.zh.md
+++ b/packages/bash/pwsh-local/README.zh.md
@@ -23,7 +23,7 @@
     pwshPath: C:\Program Files\PowerShell\7\pwsh.exe  # explicit executable; else well-known locations, then PATH
 ```
 
-## 行为（及其由来）
+## 行为
 
 作为 `dsh-bash-local` 的 Windows 对应物，逐调用地镜像其语义：
 
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index adbfd88851..69dae2915a 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -206,9 +206,9 @@ export function apply(ctx: Context, config: Config = {}): void {
    * {@link approveEscalation}. This tool contributes only the composition
    * guard (the fields are unadvertised without a sandboxing executor, yet
    * schema validation checks advertised keys only, so an unadvertised
-   * `sandbox_permissions` still reaches execute) and the approval ingredients
-   * The shared policy resolver is required whenever the executor advertises
-   * confinement, so a split composition fails at tool-plugin load.
+   * `sandbox_permissions` still reaches execute) and the approval
+   * ingredients. The shared policy resolver is required whenever the executor
+   * advertises confinement, so a split composition fails at tool-plugin load.
    */
   const approveBashEscalation = (
     mode: string,
diff --git a/packages/bash/tool-pwsh/README.i18n.yaml b/packages/bash/tool-pwsh/README.i18n.yaml
index ba4f758814..e272ee2993 100644
--- a/packages/bash/tool-pwsh/README.i18n.yaml
+++ b/packages/bash/tool-pwsh/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/bash/tool-pwsh/README.md
-README.md: 78eb161f77b9524bc577b273abe59db6b931727c
-README.zh.md: 54614fcfad1cdec5866aa3cc96e52983f4eb1642
+README.md: 7d8ee5fb69b71d8e8707d3e4ed07ebdda99f799f
+README.zh.md: 40984bbc36be4b5809e6ee4db21e52d842f50cdb
diff --git a/packages/bash/tool-pwsh/README.md b/packages/bash/tool-pwsh/README.md
index 78eb161f77..7d8ee5fb69 100644
--- a/packages/bash/tool-pwsh/README.md
+++ b/packages/bash/tool-pwsh/README.md
@@ -119,6 +119,6 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **No sandbox escalation** — `sandbox_permissions`/`justification` are absent; escalation waits for a Windows-confining executor (the bash tool's sandbox surface is not mirrored).
-- **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`; the PTY backends are Linux/macOS-only today, and a Windows ConPTY persistent shell is roadmap work.
+- **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`; the PTY backends are Linux/macOS-only.
 - **PowerShell-dialect contract** — the model must write PowerShell (native paths, `$env:` variables), not bash; there is no dialect translation.
 - **Session-cwd identity is not canonicalized** — the workdir base is the session header cwd as-is, unlike the bash tool's sandbox-root-canonicalized identity; only the sandbox-less case applies here.
diff --git a/packages/bash/tool-pwsh/README.zh.md b/packages/bash/tool-pwsh/README.zh.md
index 54614fcfad..40984bbc36 100644
--- a/packages/bash/tool-pwsh/README.zh.md
+++ b/packages/bash/tool-pwsh/README.zh.md
@@ -119,6 +119,6 @@ ack 是固定短行；任务输出按读取有界。
 ## Known Limitations and Deferred Work
 
 - **无 sandbox 升级** — 没有 `sandbox_permissions`/`justification`；升级等待 Windows-confining 执行器（bash 工具的 sandbox 面不被镜像）。
-- **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端目前仅限 Linux/macOS，Windows ConPTY 持久 shell 属于路线图工作。
+- **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端仅限 Linux/macOS。
 - **PowerShell 方言约定** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
 - **会话 cwd 身份不做规范化** — workdir 基座直接取会话头 cwd 原值，不同于 bash 工具经 sandbox-root 规范化的身份；此处只涉及无 sandbox 场景。
diff --git a/packages/bundle/web-app/src/index.ts b/packages/bundle/web-app/src/index.ts
index 9a85b02cba..b14635a868 100644
--- a/packages/bundle/web-app/src/index.ts
+++ b/packages/bundle/web-app/src/index.ts
@@ -1,7 +1,7 @@
 /**
  * @deepseek-ai/dsh-web-app — the browser-surface bundle's runtime glue plugin
  * plus the bundle patch (`cordis.patch.yml`, declared by the `dsh.bundle.patch`
- * manifest field). The plugin owns what used to be launcher code: it resolves
+ * manifest field). The plugin owns the browser-surface glue: it resolves
  * the built frontend dist (workspace knowledge of this bundle, never user
  * config), mounts the `frontend-static` fallback owner over it, registers the
  * web-surface prompt section and the bash-visible web runtime variables, and
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index 9626e96e74..b67428953e 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -23,7 +23,7 @@ How live data reaches render code, and what may cross a business boundary:
 1. **Everything a render reads that can change outside React arrives through a framework hook** (rule 4 above). Event-handler code may read live snapshots (e.g. `keyboard.snapshot`); render code subscribes.
 2. **Business components contain no subscription machinery** — no `useSyncExternalStore`, no manual subscribe wiring, no mirroring an external snapshot into local state or a second store. Give each reactive fact its owning channel instead: registrant-private → the inject `hooks` compartment; cross-entry or remount-surviving → a declared store; per-session standard → `sessions.provide`.
 3. **Data-access ladder** — resolve needs in this order: framework hooks (standing seats + provide/inject-bound `use<Name>`) → a declared store (`useStore`/`actions`) → inject callbacks → anything else is a new framework extension point and needs main-thread arbitration.
-4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are grandfathered and get migrated to slots progressively).
+4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are the sanctioned exceptions).
 5. **An observable source keeps two identities stable**: the source object itself (hook binding is cached per source), and its snapshot between changes (`getSnapshot` returns the same reference until the fact moves).
 6. **Whoever rebuilds a published value republishes it through the same source in the same step**, and a registration path that can run after consumers exist notifies the live consumers as part of registering.
 
@@ -89,7 +89,7 @@ If `test:gui` is red on code you did not touch, neither silently fix nor ignore
 
 ## New plugin package checklist
 
-Bringing up a new `packages/client/<name>` plugin package (ui-workspace is the latest walked example; ui-sidebar/ui-question are good skeletons to copy):
+Bringing up a new `packages/client/<name>` plugin package (ui-workspace is a complete example; ui-sidebar/ui-question are minimal skeletons):
 
 1. **Package skeleton**: `package.json` (`@deepseek-ai/dsh-client-<name>`, exports `.`/`./invariant`/`./client`/`./src/*`/`./package.json`, `dshClient` manifest, `files` list), `tsconfig.json` (extends `tsconfig.base.client.json`, one `references` entry per workspace dependency plus `support/invariants`), `tsdown.config.ts` (`clientBundle(id, ['lib/types/index.js', 'lib/types/invariant.js'])`), `src/index.ts` (empty node-half apply), `src/invariant.ts` (companion with a real reason), `src/css-modules.d.ts` when using CSS Modules, `README.md` with the Model Experience section.
 2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; a `dshClient` row in `packages/bundle/web-app/cordis.patch.yml`; a `packages/bundle/web-app/package.json` dependency (profile boots resolve bare row names through the healed `$DSH_HOME/profiles/node_modules` fallback, which mirrors the app's and each bundle's declared dependencies — a row whose package no manifest declares fails to import). `pnpm-workspace.yaml` already globs `packages/*/*`.
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 5e2d35f4e8..1ae9269cb8 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
-README.md: dba01cb8c487dbc670a471053f8cd12dd277ef4c
-README.zh.md: d12ef605f1113411a59c2d73c2bf105dfb021be8
+README.md: 07849f0728aee6076b15a8216ddcab08521994d6
+README.zh.md: a7996d0f7cc2948da82877c47f9acc805be2bba8
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index dba01cb8c4..07849f0728 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` abstraction, and the loop's sink/config types. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. The Host half owns the single `/api` route and its Fetch bridge; a registered TypeRT interceptor claims its Remote endpoints before the API Proxy fallback. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md); the protocol contract is api-contracts v3 §3.
+Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` abstraction, and the loop's sink/config types. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. The Host half owns the single `/api` route and its Fetch bridge; a registered TypeRT interceptor claims its Remote endpoints before the API Proxy fallback. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md).
 
 ## /api browser-trust fence
 
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index d12ef605f1..a7996d0f7c 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` 抽象，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议约定见 api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议约定类型、`AbstractApiClient` 抽象，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)。
 
 ## /api 浏览器信任栅栏
 
diff --git a/packages/client/connection/src/client/api.ts b/packages/client/connection/src/client/api.ts
index fbf995e652..7e9471bff8 100644
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -3,7 +3,7 @@
 // Types and runtime protocol helpers/bounds come from the apiproxy api/ layer
 // (zero Node deps, browser-safe); AbstractApiClient is the client boundary.
 // NEVER import the package root: it drags bootHost/cordis into the browser bundle.
-// The ./api and ./client subpath exports are the browser-safe channels added for this.
+// The ./api and ./client subpath exports are the browser-safe channels.
 
 export type {
   ApiProxy, SessionsApi, SessionSearchItem, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
@@ -23,9 +23,9 @@ export type {
   RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
   ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
-// transportError moved down to the apiproxy api layer (it belongs beside
-// RpcResult, its subject); re-exported here so connection consumers keep one
-// contract entry point.
+// transportError lives in the apiproxy api layer (beside RpcResult, its
+// subject); re-exported here so connection consumers keep one contract
+// entry point.
 export {
   RpcId,
   SESSION_SEARCH_RESULT_LIMIT,
diff --git a/packages/client/connection/src/client/connection.ts b/packages/client/connection/src/client/connection.ts
index 18d22f878d..cfa608a394 100644
--- a/packages/client/connection/src/client/connection.ts
+++ b/packages/client/connection/src/client/connection.ts
@@ -1,7 +1,7 @@
 import type { IApiClient, HostFrame, MuxFrame, RpcRequest } from './api.ts'
 
-/** Reconnect/backoff tunables (deployment-varying — no hardcoded tunables; web-cordis §B.1 lists
- *  these as the future `ctx.connection` plugin Config). All fields optional; defaults below. */
+/** Reconnect/backoff tunables (deployment-varying — no hardcoded tunables; these become the
+ *  future `ctx.connection` plugin's Config). All fields optional; defaults below. */
 export interface ConnectionConfig {
   /** First-retry backoff cap in ms (jittered: actual delay is cap/2..cap). */
   backoffBaseMs?: number
@@ -10,9 +10,9 @@ export interface ConnectionConfig {
   /** Upper bound for the backoff cap in ms. */
   backoffMaxMs?: number
   /** Cap on waiting for both streams' onOpen before onConnected, in ms. The strict handshake
-   *  (audit C2) waits for mux+host stream establishment plus describe; a carrier that never
+   *  waits for mux+host stream establishment plus describe; a carrier that never
    *  fires onOpen (misbehaving proxy) must not wedge the connection forever — on timeout the
-   *  generation proceeds as connected and the live-gap repair path (audit S3) covers stragglers. */
+   *  generation proceeds as connected and the live-gap repair path covers stragglers. */
   streamOpenTimeoutMs?: number
 }
 
@@ -35,7 +35,7 @@ function sleep(ms: number, signal: AbortSignal): Promise<void> {
   })
 }
 
-/** Coarse connection state for the UI (audit C1): 'connected' after each generation's handshake,
+/** Coarse connection state for the UI: 'connected' after each generation's handshake,
  *  'reconnecting' the moment the generation fails (covers the whole backoff+retry span). */
 export type ConnectionState = 'connected' | 'reconnecting'
 
@@ -125,7 +125,7 @@ export class ConnectionController {
       })
 
       try {
-        // Strict readiness handshake (audit C2): describe proves unary reachability, onOpen
+        // Strict readiness handshake: describe proves unary reachability, onOpen
         // proves each physical stream is established before any frame —
         // only then may onConnected fire, so the resync it triggers cannot outrun the
         // subscribed baseline. The timeout guards against a carrier that never fires onOpen
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index d755f73354..b863745d3c 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -1284,7 +1284,7 @@ export interface FixtureOptions {
 
 /** Inbox pump shared by both stream generators (FrameQueue pattern: ONE abort listener hung
  *  outside the loop — a per-iteration {once:true} listener never fires for non-final rounds and
- *  piles up for the stream's lifetime, audit C5). breakNow force-ends the stream without the
+ *  piles up for the stream's lifetime). breakNow force-ends the stream without the
  *  client's signal (timing hook: simulated connection loss). */
 class FxInbox<F> implements StreamConn<F> {
   private readonly inbox: RpcRequest<F>[] = []
@@ -1658,7 +1658,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
 
   /** history transit delay (timing hooks below); the page snapshot is taken at request time, like a real host. */
   let historyDelayMs = 0
-  /** One-shot history failure (timing hook: the doomed in-flight request of the S4 reconnect scenario). */
+  /** One-shot history failure (timing hook: a pre-disconnect history request already doomed when reconnect lands). */
   let failNextHistory = false
   /** Force-enders for currently open stream generators (timing hook: simulated connection loss). */
   const streamBreakers = new Set<() => void>()
@@ -1667,8 +1667,8 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
   /** The single opt-in browser stress producer; normal fixture journeys never start it. */
   let activeReasoningChunkStorm: ReasoningChunkStormState | null = null
 
-  // Timing-acceptance hooks (browser test backdoor): the in-memory fixture is ideally timed, which
-  // is exactly what masked the open-window and reconnect-gap bugs (audit S1/S3). These let
+  // Timing-acceptance hooks (browser test backdoor): the in-memory fixture is
+  // ideally timed. These let
   // browser acceptance runs create slow-history, lost-frame, and reconnect
   // windows a real host produces naturally.
   const timingHooks = {
@@ -2691,8 +2691,8 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
  * Fixture platform subclass: there is no HTTP at all, so instead of a doFetch transport it
  * overrides the protocol-level virtuals (callUnary/openMux/openHost/respond) to dispatch
  * straight into the in-memory ApiProxy — while still minting rpcIds, fabricating the four
- * named full forms, and feeding the same tap as a real carrier. Delete when the fixture moves
- * to the isomorphic pipeline (InProcessApiClient over toFetchHandler(fixtureImpl)).
+ * named full forms, and feeding the same tap as a real carrier. TODO: delete when the fixture
+ * moves to the isomorphic pipeline (InProcessApiClient over toFetchHandler(fixtureImpl)).
  */
 export class FixtureApiClient extends AbstractApiClient {
   private readonly api: ApiProxy
diff --git a/packages/client/hmr/src/client/index.ts b/packages/client/hmr/src/client/index.ts
index 80fca3bf54..99f0938555 100644
--- a/packages/client/hmr/src/client/index.ts
+++ b/packages/client/hmr/src/client/index.ts
@@ -3,7 +3,7 @@
  *
  * Listens on the host's system SSE channel (`GET /plugins/events`); on a
  * `rebuilt` frame it reloads the entry's bundle and swaps the cordis
- * fiber in place. Every graph entry is a plugin bundle under the web2 model
+ * fiber in place. Every graph entry is a plugin bundle
  * — `immediately` rows differ only in stage-one prefetch (a boot
  * optimization), so all rostered plugin packages share these reload semantics;
  * normal packages (react family, cordis, shell, pure libs) are not entries
@@ -35,8 +35,7 @@
  * that arrival's task and may materialize the pre-rebuild bytes; the next
  * rebuilt frame self-heals.
  *
- * Why not the naive `entry.fiber.dispose()` → `entry.refresh()` path —
- * confirmed against vendor sources:
+ * Why not the naive `entry.fiber.dispose()` → `entry.refresh()` path:
  * 1. `Entry.fiber` is never cleared on dispose (vendor/loader/src/config/
  *    entry.ts assigns it only in `_init`), so `refresh()` hits its
  *    `if (this.fiber) return` guard and no-ops.
@@ -46,7 +45,7 @@
  *    `disabled: true` — permanently.
  * vendor/hmr's reload skeleton documents the fix: delete the runtime record
  * FIRST (`registry.delete` → case 4 returns early, the entry stays enabled),
- * then rebuild. We additionally clear `entry.fiber` ourselves so
+ * then rebuild. `entry.fiber` is additionally cleared so
  * `entry.refresh()` re-imports and re-plugins through the Loader's own
  * `_init` (entry-resolved config, automatic `fiber.entry` rebinding) instead
  * of hand-rolling `registry.plugin`. Client entries have exactly one fiber
diff --git a/packages/client/modules/src/client/index.ts b/packages/client/modules/src/client/index.ts
index c734ffb8f7..a516d6cef9 100644
--- a/packages/client/modules/src/client/index.ts
+++ b/packages/client/modules/src/client/index.ts
@@ -1,8 +1,8 @@
 /**
  * Browser half (the standard `./client` export): the module-system class and
  * wire contract, plus the enrollment plugin face. The module system itself is
- * built by the shell kernel BEFORE cordis exists (the bootstrap exception,
- * design §4.7 — the mechanism that loads plugins cannot arrive through
+ * built by the shell kernel BEFORE cordis exists (the bootstrap exception —
+ * the mechanism that loads plugins cannot arrive through
  * itself); the plugin face only enrolls that pre-existing instance by
  * providing it as `ctx.modules`. The kernel statically registers this module,
  * so the graph row for this package never triggers a real fetch — arrival is
diff --git a/packages/client/modules/src/client/manifest.ts b/packages/client/modules/src/client/manifest.ts
index ff7a7d8692..edb437e247 100644
--- a/packages/client/modules/src/client/manifest.ts
+++ b/packages/client/modules/src/client/manifest.ts
@@ -6,7 +6,7 @@
  * waiting, update/refresh) entirely on the vendored side while this package
  * owns code arrival.
  *
- * Lazy CJS model (web2 §0): executing a plugin bundle only REGISTERS its
+ * Lazy CJS model: executing a plugin bundle only REGISTERS its
  * factory (`window.__ModuleLoader__.load({id, factory})`); every module body
  * side effect — including CSS injection — lives inside the factory closure
  * and runs at materialization, not at script execution. Materialization
@@ -35,13 +35,13 @@ import type { ClientModuleSystem } from './system.ts'
 
 declare module 'cordis' {
   interface Context {
-    /** The client module system the web shell builds at boot (contract C5; provided by the `./client` wrapper plugin). */
+    /** The client module system the web shell builds at boot (provided by the `./client` wrapper plugin). */
     modules: ClientModuleLoader
   }
 }
 
 /**
- * One composed client entry pushed by the host (web2 §0 graph row). Wire
+ * One composed client entry pushed by the host (a graph row). Wire
  * single source: the host node half (package root) produces this same shape.
  * `immediately` marks stage-one prefetch; `inject` is informational graph
  * metadata (the authoritative edges live in each package's dshClient
@@ -143,7 +143,7 @@ export function parseBootManifest(wire: unknown): BootManifest {
   return { rev: graph.rev, modules, plugins }
 }
 
-/** The shape a client bundle hands to `window.__ModuleLoader__.load` (registration handoff, contract C6). */
+/** The shape a client bundle hands to `window.__ModuleLoader__.load` (registration handoff). */
 export interface ClientPluginHandoff {
   /** Plugin id (package name) — the registration key; must match the graph row being executed. */
   id: string
@@ -159,7 +159,7 @@ export interface ClientPluginHandoff {
 export interface DshWindow {
   /** Host-composed entry graph, injected before the shell bundle runs; wire-boundary raw until {@link parseBootManifest}. */
   __DSH_BOOT__?: unknown
-  /** Bundle registration sink; installed once per page by the {@link ClientModuleSystem} constructor (contract C6). */
+  /** Bundle registration sink; installed once per page by the {@link ClientModuleSystem} constructor. */
   __ModuleLoader__?: { load(handoff: ClientPluginHandoff): void }
   /**
    * Kernel handoff slot: the shell kernel stores the instance here right
@@ -185,7 +185,7 @@ export interface ClientModuleRecord {
 /**
  * The internal-contract subset the vendored Loader and the client HMR plugin
  * consume. Mounted on `ctx.loader.internal` by the shell boot and provided
- * as `ctx.modules` (contract C5).
+ * as `ctx.modules`.
  */
 export interface ClientModuleLoader {
   /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
diff --git a/packages/client/modules/src/client/system.ts b/packages/client/modules/src/client/system.ts
index 5a6b11bb1e..5d99466409 100644
--- a/packages/client/modules/src/client/system.ts
+++ b/packages/client/modules/src/client/system.ts
@@ -54,7 +54,7 @@ const claimStyles = (id: string): string[] => {
  * The client module system: state tables plus the arrival/materialization
  * machinery implementing {@link ClientModuleLoader} (whose members carry the
  * contract documentation). Construction indexes the boot rows and installs the
- * `window.__ModuleLoader__` registration sink (contract C6) — once per page.
+ * `window.__ModuleLoader__` registration sink — once per page.
  */
 export class ClientModuleSystem implements ClientModuleLoader {
   readonly version = 'client'
diff --git a/packages/client/modules/src/index.ts b/packages/client/modules/src/index.ts
index ec3822e5a9..82070f9206 100644
--- a/packages/client/modules/src/index.ts
+++ b/packages/client/modules/src/index.ts
@@ -14,8 +14,8 @@
  * set with all current entries and flushes synchronously, so first scan and
  * steady state share one implementation. Package metadata (including the
  * negative "not a client package" verdict) is cached per name and never
- * expires — plugin-set changes take effect on restart per the config-source
- * ruling; bundle content changes reach the graph only through
+ * expires — plugin-set changes take effect on restart; bundle content
+ * changes reach the graph only through
  * {@link ClientModuleHostService.rebuilt}.
  * @module @deepseek-ai/dsh-client-modules
  */
diff --git a/packages/client/runtime/README.i18n.yaml b/packages/client/runtime/README.i18n.yaml
index 734b158e66..a5d2c2a44f 100644
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/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/client/runtime/README.md
-README.md: d4031c2e3b7730bdb0075ac84c50ad3e46ce63a2
-README.zh.md: ca6ac9f5e8efec3472c03b044739a9221e98183c
+README.md: 0a7d9975093da558af623ee9940f4be398526821
+README.zh.md: 41388e4ba564baa61cfdaaacb74f4f5ea053d41a
diff --git a/packages/client/runtime/README.md b/packages/client/runtime/README.md
index d4031c2e3b..0a7d997509 100644
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects and the Chat-facing list, scope, and event-window state; SessionHistoryService lazily owns independent raw-history ledgers for inspection consumers, loading the current tail first and prepending one older page only when its consumer requests it. Each history snapshot exposes the raw window's absolute base sequence so a consumer detects a prepend even when the page adds no surface-visible node. WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (`connectWorkspace`). The runtime fans the shared Host stream into the Session, Workspace, and activated history owners without routing inspection state through Session or SessionManager, and bridges the registry-invalidation frames to typed ctx events (`commands/changed`, `settings/changed`, `credentials/changed`, `models/changed`) so surface caches refetch without touching the stream. Client sessions are always Host-born (Session+Agent+cwd in one `session.create`); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Contract: api-contracts v3 §4. Each `Session` holds a generic `ProjectionValueStore` seeded from the history-tail `projections` block and updated by `session/projection` frames under higher-seq-wins; domain keys (including `todos`) are read via `projections.faceOf` / `useProjection`, not via `ConversationSnapshot`. The store also publishes one reference-stable whole-value map through `SessionSummary.projectionValues`, allowing global list consumers to reuse the same projections without creating per-session subscriptions.
+Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects and the Chat-facing list, scope, and event-window state; SessionHistoryService lazily owns independent raw-history ledgers for inspection consumers, loading the current tail first and prepending one older page only when its consumer requests it. Each history snapshot exposes the raw window's absolute base sequence so a consumer detects a prepend even when the page adds no surface-visible node. WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (`connectWorkspace`). The runtime fans the shared Host stream into the Session, Workspace, and activated history owners without routing inspection state through Session or SessionManager, and bridges the registry-invalidation frames to typed ctx events (`commands/changed`, `settings/changed`, `credentials/changed`, `models/changed`) so surface caches refetch without touching the stream. Client sessions are always Host-born (Session+Agent+cwd in one `session.create`); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Each `Session` holds a generic `ProjectionValueStore` seeded from the history-tail `projections` block and updated by `session/projection` frames under higher-seq-wins; domain keys (including `todos`) are read via `projections.faceOf` / `useProjection`, not via `ConversationSnapshot`. The store also publishes one reference-stable whole-value map through `SessionSummary.projectionValues`, allowing global list consumers to reuse the same projections without creating per-session subscriptions.
 
 ## Slot declaration injection
 
@@ -80,4 +80,4 @@ Changing the model selection can change or invalidate provider-side cache reuse;
 
 - **`loader.unload` is a stub** — it throws not-implemented; the client has no unload chain from fiber disposal through registration and style removal.
 - **Scope teardown is stage-driven, single-occupant today** — the staged session follows `list.current` exactly (staging is the open signal: the event window opens ⟺ the session is on stage); a removed-while-staged session's scope survives frozen until the stage moves on, not until true observer count reaches zero. Resolution (`binding()`/`scope()`) is pure addressing, render-safe; the render layer reads the current bundle through the `currentProvideInfo` observable. The staged state can widen to a multi-pane list when concurrent panes land.
-- **Value imports of this package from plugin bundles must use the `/client` subpath** — the bare package name is not in the loader externals table and inlines a second module instance, whose private scope-tag Symbol never matches (the empty-state P0 postmortem).
+- **Value imports of this package from plugin bundles must use the `/client` subpath** — the bare package name is not in the loader externals table and inlines a second module instance, whose private scope-tag Symbol never matches.
diff --git a/packages/client/runtime/README.zh.md b/packages/client/runtime/README.zh.md
index ca6ac9f5e8..41388e4ba5 100644
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象以及 Chat 所需的列表、scope 和事件窗口状态；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本，先加载当前尾部，并仅在消费方请求时向前补入一页更早历史。每份历史快照都会公开原始窗口的绝对基准序号，因此即使该页没有新增任何 surface 可见节点，消费方仍能检测到向前补页。WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager，并把注册表失效帧桥接为类型化 ctx 事件（`commands/changed`、`settings/changed`、`credentials/changed`、`models/changed`），使各表面缓存无需触碰流即可重拉。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。约定：api-contracts v3 §4。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。该 store 还会通过 `SessionSummary.projectionValues` 发布一份引用稳定的完整值映射，使全局列表消费方无需为每个会话创建订阅，即可复用同一组投影。
+客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象以及 Chat 所需的列表、scope 和事件窗口状态；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本，先加载当前尾部，并仅在消费方请求时向前补入一页更早历史。每份历史快照都会公开原始窗口的绝对基准序号，因此即使该页没有新增任何 surface 可见节点，消费方仍能检测到向前补页。WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager，并把注册表失效帧桥接为类型化 ctx 事件（`commands/changed`、`settings/changed`、`credentials/changed`、`models/changed`），使各表面缓存无需触碰流即可重拉。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。该 store 还会通过 `SessionSummary.projectionValues` 发布一份引用稳定的完整值映射，使全局列表消费方无需为每个会话创建订阅，即可复用同一组投影。
 
 ## Slot 声明注入
 
@@ -80,4 +80,4 @@ Host 所属的 LLM retry invariant 会在持久追加边界验证按提供方路
 
 - **`loader.unload` 是 stub**：它会抛出 not-implemented；客户端没有从 fiber dispose 到注册与样式移除的卸载链。
 - **scope 拆卸由阶段驱动，目前只能有一个占用者**：已 staged 的会话精确跟随 `list.current`（staging 就是打开信号：事件窗口打开 ⟺ 会话位于 stage）；在 staged 状态下被移除的会话，其 scope 会冻结保留，直到 stage 转向其他会话，而非直到真实观察者数量降为零。解析（`binding()`／`scope()`）只是纯寻址，可安全用于渲染；渲染层经 `currentProvideInfo` observable 读取当前 bundle。并发 pane 落地时，staged 状态可以扩展为多 pane 列表。
-- **插件组合包从该包导入值时必须使用 `/client` 子路径**：裸包名不在 loader externals 表中，会内联第二个模块实例；其私有 scope-tag Symbol 永远无法匹配。这是空状态 P0 的事故复盘（postmortem）所记录的问题。
+- **插件组合包从该包导入值时必须使用 `/client` 子路径**：裸包名不在 loader externals 表中，会内联第二个模块实例；其私有 scope-tag Symbol 永远无法匹配。
diff --git a/packages/client/runtime/src/client/contract/store.ts b/packages/client/runtime/src/client/contract/store.ts
index 7dc3b584ba..4592d0763d 100644
--- a/packages/client/runtime/src/client/contract/store.ts
+++ b/packages/client/runtime/src/client/contract/store.ts
@@ -2,9 +2,9 @@
  * Snapshot store engine (zustand vanilla + immer + subscribeWithSelector +
  * rafFlush middleware + opt-in persist + dev freeze) plus the declarative
  * shell over it: {@link defineStore} bakes an init/persist/actions literal
- * into a {@link StoreHandle}, the registration-side store seat of the slot
- * terminal design (§4). Lives in the React-free runtime (store-migration
- * ruling: the data layer owns its engine; web-react is shell-only React
+ * into a {@link StoreHandle}, the registration-side store seat of slot
+ * terminals. Lives in the React-free runtime (the data layer owns its
+ * engine; web-react is shell-only React
  * glue): engine products are bare observables — subscribe/getSnapshot/
  * update/set, NO selector hook. Hook synthesis is web-react's (the one
  * uSES bridge, cached per source at the binding site).
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index fe1ce8f7b0..766656a7f9 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -94,7 +94,8 @@ export { PendingWait } from './sessions/pending.ts'
 export type {
   PendingInteraction, PendingInteractionStatus, PendingKind, PendingPayloads,
 } from './sessions/pending.ts'
-// Projection value store (session-projection RFC, push model): host-computed
+// Projection value store (push model; see the session-projection subsystem
+// page, docs/subsystems/session-projection.md): host-computed
 // whole values per key; domains ship projection support with zero client code.
 export type {
   ProjectionsBaseline, ProjectionValueStore, SessionProjectionMap, UseProjection,
diff --git a/packages/client/runtime/src/client/sessions/manager.ts b/packages/client/runtime/src/client/sessions/manager.ts
index b4eec9d6df..b251ed8ed5 100644
--- a/packages/client/runtime/src/client/sessions/manager.ts
+++ b/packages/client/runtime/src/client/sessions/manager.ts
@@ -98,12 +98,12 @@ function questionInteractionStatus(
   return options.some(option => option.label === intent.approve) ? 'plan-review' : 'question'
 }
 
-/** Instance cluster + frame entry + the session list (see the web client architecture RFC). */
+/** Instance cluster + frame entry + the session list. */
 export class SessionManager {
   private readonly sessions = new Map<SessionId, Session>()
   /** Pre-instantiation buffer for answerable requests and the queued-turn snapshot, which history
    *  cannot reconstruct on open. Live requests remain until resolution; queue and replay duplicates
-   *  compact by identity. Instantiation replays and clears it, while removal drops it (audit S7). */
+   *  compact by identity. Instantiation replays and clears it, while removal drops it. */
   private readonly pendingBuffers = new Map<SessionId, RpcRequest<MuxFrame>[]>()
   /** Outstanding answerable interactions per session, keyed by their stable request identity.
    *  Manager-owned rather than read off Session instances because the sidebar must light up for
@@ -142,9 +142,9 @@ export class SessionManager {
   private selected: SessionId | undefined
 
   private listSnapshotCache: SessionListSnapshot
-  /** Entry-identity cache (§C.2 reference stability): list rebuilds reuse the previous entry
+  /** Entry-identity cache (reference stability): list rebuilds reuse the previous entry
    *  object when every field matches — wire refreshes mint all-new summary objects, so identity
-   *  must be recovered by value or every SessionListItem memo misses on every refresh (audit S5). */
+   *  must be recovered by value or every SessionListItem memo misses on every refresh. */
   private entryCache = new Map<SessionId, SessionListEntry>()
   private itemsCache: readonly SessionListEntry[] = []
   private readonly notifier = new Notifier(() => {
@@ -244,7 +244,7 @@ export class SessionManager {
   // ---- Instance management ----
 
   /**
-   * Drop a session instance (scope-prune companion, decision 12: instance
+   * Drop a session instance (scope-prune companion: instance
    * and scope share one lifecycle). The host session log is the durable
    * truth — a later get() lazily rebuilds and open() backfills history.
    * @param sessionId - the session to drop.
@@ -969,7 +969,7 @@ export class SessionManager {
   private buildListSnapshot(): SessionListSnapshot {
     const merged: TitledSessionSummary[] = this.summaries.map((summary) => {
       // List rows read the generic 'title' projection key (host-computed unit
-      // value; the bespoke session/title frame is retired).
+      // value; there is no dedicated title frame).
       const projectionStore = this.projectionStores.get(summary.sessionId)
       const title = projectionStore?.get('title')
       const projectionValues = projectionStore?.values()
@@ -1048,7 +1048,7 @@ function applyMutation(summaries: readonly SessionSummary[], mutation: SessionLi
     case 'remove':
       return summaries.filter(summary => summary.sessionId !== mutation.sessionId)
     case 'status':
-      // running:true doubles as the cross-端 blank flip (a blank session
+      // running:true doubles as the cross-client blank flip (a blank session
       // never runs, so the first running frame proves a message landed).
       return summaries.map(summary => summary.sessionId === mutation.sessionId
         && (summary.running !== mutation.running || (mutation.running && summary.blank))
diff --git a/packages/client/runtime/src/client/sessions/projection-store.ts b/packages/client/runtime/src/client/sessions/projection-store.ts
index 1af9ad726e..e2a95e4c86 100644
--- a/packages/client/runtime/src/client/sessions/projection-store.ts
+++ b/packages/client/runtime/src/client/sessions/projection-store.ts
@@ -1,6 +1,7 @@
 /**
- * Generic per-session projection value store (session-projection RFC, push
- * model): the host is the only computation site; the client holds finished
+ * Generic per-session projection value store (push model; see the
+ * session-projection subsystem page, docs/subsystems/session-projection.md):
+ * the host is the only computation site; the client holds finished
  * whole values per key — `key → { value, seq }` — seeded by the history tail
  * page's projections block and updated by `session/projection` push frames,
  * under the single rule **higher seq wins**. No client-side domain folding
@@ -16,11 +17,13 @@ import { Notifier } from './notifier.ts'
 // (`/types`, zero imports), never the package root: the root's dsh-agent →
 // dsh-session chain would drag the host `Context.sessions` merge into the
 // client program (one program must not hold both sides). No second
-// client-side "views" table (user ruling, RFC Alternatives).
+// client-side "views" table (rejected in the Alternatives of
+// .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).
 export type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types'
 
 /**
- * The fifth framework hook seat (session-projection RFC): key-addressed
+ * The fifth framework hook seat (see the session-projection subsystem page,
+ * docs/subsystems/session-projection.md): key-addressed
  * projection reader delivered through the standard kit. `undefined` uniformly
  * means capability absent — host unit unmounted, or no baseline/frame has
  * carried the key yet. The selector overload mirrors useSession (per-key uSES
diff --git a/packages/client/runtime/src/client/sessions/service.ts b/packages/client/runtime/src/client/sessions/service.ts
index dcb5f71610..e137d9597b 100644
--- a/packages/client/runtime/src/client/sessions/service.ts
+++ b/packages/client/runtime/src/client/sessions/service.ts
@@ -1,8 +1,7 @@
 /**
  * SessionsService: root sessions service — list snapshot store (manager
  * projection; carries `current`, the persisted selection every
- * session-scoped surface keys off — migrated here from ui-layout per the
- * slot-parity design), Agent scope tree (mintScope pattern: no-op plugin
+ * session-scoped surface keys off), Agent scope tree (mintScope pattern: no-op plugin
  * Fiber + ctx.extend scope tag; one scope per session, agent id === session
  * id), stable SessionBinding cache, breadcrumb-route projection.
  *
@@ -605,7 +604,7 @@ export class SessionsService implements ISessions {
 
   /**
    * Lazily mint the scope + binding for an eligible session. Eligibility and
-   * prune share one predicate (decision 12): listed on the host or selected
+   * prune share one predicate: listed on the host or selected
    * through a retained subagent address. Breadcrumb-only ancestors remain
    * summary data and do not keep scopes alive.
    */
@@ -728,7 +727,7 @@ export class SessionsService implements ISessions {
   }
 
   /**
-   * One teardown for the whole per-session axis (decision 12): the scope
+   * One teardown for the whole per-session axis: the scope
    * fiber (cascading every actx-registered effect: input shell, slash
    * controller, popup, plugin stores, listeners), the session-keyed slot
    * stores, and the Session instance itself — the host session log is the
diff --git a/packages/client/runtime/src/client/sessions/session.ts b/packages/client/runtime/src/client/sessions/session.ts
index 7c3d989248..1f351c9c4b 100644
--- a/packages/client/runtime/src/client/sessions/session.ts
+++ b/packages/client/runtime/src/client/sessions/session.ts
@@ -71,7 +71,7 @@ export class Session implements SessionFace {
   private openError: RpcError | null = null
   private openPromise: Promise<void> | null = null
   /** Bumped by resync to invalidate an in-flight doOpen: a reconnect must rebuild, never adopt
-   *  a pre-disconnect open whose history request is already doomed (audit S4). Stale doOpen
+   *  a pre-disconnect open whose history request is already doomed. Stale doOpen
    *  passes drop all writes once the generation moves on. */
   private openGeneration = 0
   private loadingOlder = false
@@ -106,8 +106,9 @@ export class Session implements SessionFace {
   private subscribedLastSeq: number | null = null
 
   /**
-   * Per-session projection value store (session-projection RFC, push model):
-   * finished whole values computed on the host, seeded by the tail page's
+   * Per-session projection value store (push model; see the session-projection
+   * subsystem page, docs/subsystems/session-projection.md): finished whole
+   * values computed on the host, seeded by the tail page's
    * projections block and updated by `session/projection` frames under the
    * one higher-seq-wins rule. Keys are read via `projections.faceOf(key)`
    * (the useProjection resolution face); the conversation snapshot never
@@ -325,7 +326,7 @@ export class Session implements SessionFace {
     return promise
   }
 
-  /** Page up: pull one earlier page with the window's first seq as beforeSeq and prepend (§D.2). */
+  /** Page up: pull one earlier page with the window's first seq as beforeSeq and prepend. */
   async loadOlder(): Promise<void> {
     if (this.openState !== 'open' || !this.hasMore || this.loadingOlder) return
     this.loadingOlder = true
@@ -341,7 +342,7 @@ export class Session implements SessionFace {
       }
       const tail = older[older.length - 1]
       if (tail === undefined || tail.event.seq + 1 !== this.baseSeq) {
-        // §D.2 continuity assertion: on violation drop the page fail-soft rather than render an out-of-order stream.
+        // Continuity assertion: on violation drop the page fail-soft rather than render an out-of-order stream.
         console.error(`[web-runtime] history page discontinuous: tail seq ${tail?.event.seq} vs baseSeq ${this.baseSeq}`)
         this.hasMore = false
         this.conversation.prepend([], false)
@@ -364,7 +365,7 @@ export class Session implements SessionFace {
   /** Reconnect rebuild (manager calls this on onConnected for instances that were opened):
    *  reset the window and rerun open; pending waits for the baseline replay. Invalidates any
    *  in-flight open first — its history request rode the dead connection and must not settle
-   *  the fresh generation into 'error' (audit S4). */
+   *  the fresh generation into 'error'. */
   async resync(): Promise<void> {
     // The queue mirror is NOT cleared here: onConnected (which drives resync)
     // races the mux frames — the fresh generation's baseline may have landed
@@ -472,7 +473,7 @@ export class Session implements SessionFace {
    */
   handleRunning(running: boolean): void {
     // Turn-start conversion: a blank session never runs, so the first
-    // running:true proves another端's first message landed (设计稿 2.2).
+    // running:true proves another side's first message landed.
     if (running && this.blankBit) {
       this.blankBit = false
       this.notifier.markDirty()
@@ -546,7 +547,7 @@ export class Session implements SessionFace {
     this.scheduleConversation(this.conversation.rebuildRegistry())
   }
 
-  // ---- 私有 ----
+  // ---- Private ----
 
   /** Requested-frame arrival: the wait enters the pending map under its own key. */
   private mint(wait: PendingInteraction): void {
@@ -576,7 +577,7 @@ export class Session implements SessionFace {
         return
       }
       this.installWindow(result.value.events, result.value.hasMore, result.value.projections)
-      // Gap detection (§D.3-4): baseline past the window tail and liveBuffer did not cover it -> pull the tail page once more.
+      // Gap detection: baseline past the window tail and liveBuffer did not cover it -> pull the tail page once more.
       const tailSeq = this.windowTailSeq()
       if (this.subscribedLastSeq !== null && tailSeq !== null && this.subscribedLastSeq > tailSeq) {
         result = (await this.history({ maxMessages: PAGE_MESSAGES })).result
@@ -598,7 +599,7 @@ export class Session implements SessionFace {
   /** Install the history window + stitch the liveBuffer (seq is the sole dedup key).
    *  Stitching MUST NOT route through acceptLiveEvent: openState is still 'loading' here
    *  (doOpen flips it after install), so recursing would push every buffered event straight
-   *  back into liveBuffer where nothing ever drains it — a silent drop loop (audit S1).
+   *  back into liveBuffer where nothing ever drains it — a silent drop loop.
    *  A carried projections block seeds the value store (higher seq wins, so a stale
    *  baseline cannot overwrite a newer push frame); the window events themselves are
    *  never folded — the host is the only computation site. */
@@ -629,7 +630,7 @@ export class Session implements SessionFace {
   }
 
   /** Land a live session/event (open/repair in flight -> buffer; overlapping seq -> drop;
-   *  a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an
+   *  a seq gap -> buffer + tail-page repull instead of appending a hole (a gap is an
    *  expected reconnect-window artifact, repaired by refetch). The window stays one contiguous
    *  raw range, which lets Conversation Definitions correlate every recorded event between its
    *  ends and lets a compaction checkpoint resolve its cited summary event. */
@@ -654,7 +655,7 @@ export class Session implements SessionFace {
     else if (publication === 'animation-frame') this.notifier.markFrameDirty()
   }
 
-  /** Resync-lite (audit S3): repull the tail page and stitch the liveBuffer through the shared
+  /** Resync-lite: repull the tail page and stitch the liveBuffer through the shared
    *  installWindow path. No openState transition — the UI keeps the current window (no loading
    *  flash); events arriving meanwhile detour to liveBuffer via the stitching flag. */
   private async repairGap(): Promise<void> {
diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
new file mode 100644
index 0000000000..ce12d3a89c
--- /dev/null
+++ b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
@@ -0,0 +1,408 @@
+// TranscriptAdapter: the human transcript projected from the raw event window
+// in LOG order. The model-visible surface deliberately shadows replaced ranges,
+// so it is the wrong source for conversation a reader already saw; this adapter
+// keeps every append-origin event at its own log position and contributes one
+// marker node per landed compaction checkpoint. Node order is therefore
+// seq-monotonic by construction.
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+// Subpath export (package.json exports "./surface"): all value imports
+// go through it — the package root points at lib/index.js (needs a build) which the vite
+// browser bundle cannot resolve; surface.ts has no Node dependencies.
+import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
+// Cordis-free leaf subpath (the dsh-commands/brand shape): the Service Definition's
+// declaration of the checkpoint source, reachable as a TYPE from this program.
+// The package ROOT is not — it reaches dsh-session's root, whose Context merge
+// declares the HOST `sessions: SessionStore` against this program's
+// `sessions: ISessions` (TS2717, the one-program-per-side rule in
+// docs/development.md).
+import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
+import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
+import { toAssistantBlocks } from './conversation.ts'
+import { contextForm, contextProvenance } from './context-provenance.ts'
+import { SteeringHistory } from './steering-history.ts'
+import type { AssistantStepMetadata } from './assistant-timing.ts'
+import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts'
+
+/**
+ * The compaction capability's checkpoint plugin, pinned to the Service Definition's declaration
+ * at COMPILE time: renaming it there fails this annotation (`TS2322`). The
+ * import stays type-only because a value import would fail the client purity
+ * gate (`packages/client/tsdown.client.ts`) — cross-plugin value imports are
+ * forbidden in a browser bundle — while an erased type never reaches it.
+ */
+const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
+
+/** In-window tool/call index entry used to materialize result cards. */
+interface CallIndexEntry {
+  name: string
+  argsRaw: string
+  turn: number
+  step: number
+  /** Unix epoch ms of the tool/call event. */
+  time: number
+  /** Wire view riding the tool/call (envelope-level; never inside the event). */
+  callView: ToolCallView | null
+}
+
+/** One event -> UI node (pure function; the ten-variant ConversationNode union). */
+function materializeNode(
+  event: SessionEvent,
+  callIndex: ReadonlyMap<string, CallIndexEntry>,
+  resultView: ToolResultView | null,
+  steering: boolean,
+  stepTimings: ReadonlyMap<string, AssistantStepMetadata>,
+): ConversationNode {
+  switch (event.type) {
+    case 'user/message': {
+      // Injected context (plugin/goal/skill-invocation source) folds to a
+      // context node, not a user message; only a direct human prompt is a
+      // user node. A compaction checkpoint never reaches here
+      // (isCompactCheckpoint routes it away).
+      if (event.data.source.kind !== 'user') {
+        return {
+          kind: 'context', seq: event.seq, time: event.time,
+          content: event.data.content, source: event.data.source,
+          provenance: contextProvenance(event.data.source),
+          form: contextForm(event.data.source),
+        }
+      }
+      if (steering) {
+        return {
+          kind: 'steering', messageId: event.data.id,
+          seq: event.seq, time: event.time,
+          content: event.data.content, source: event.data.source,
+        }
+      }
+      return {
+        kind: 'user', seq: event.seq, time: event.time,
+        content: event.data.content, source: event.data.source,
+      }
+    }
+    case 'assistant/message':
+      return {
+        kind: 'assistant', seq: event.seq, time: event.time,
+        turn: event.data.turn, step: event.data.step,
+        blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage,
+        timing: settledAssistantTiming(stepTimings, event.data.turn, event.data.step, event.time),
+      }
+    case 'tool/result': {
+      const result = event.data.message.content[0]
+      const callId = String(event.data.message.source.callId)
+      const call = callIndex.get(callId)
+      return {
+        kind: 'tool-result', seq: event.seq, time: event.time,
+        callId,
+        call: call ? { name: call.name, argsRaw: call.argsRaw } : null,
+        callTime: call?.time ?? null,
+        content: result.content, isError: result.isError === true,
+        ...(event.data.error !== undefined ? { error: event.data.error } : {}),
+        meta: event.data.meta,
+        callView: call?.callView ?? null,
+        resultView,
+        subCalls: [],
+      }
+    }
+    /* v8 ignore next 2 -- defensive arm: only the four surface-eligible types
+    can be append-origin, and each has a case above; reachable only if core
+    adds an eligible type. */
+    default:
+      return {
+        kind: 'unknown', seq: event.seq, time: event.time,
+        type: event.type, data: (event as { data?: unknown }).data,
+      }
+  }
+}
+
+/**
+ * Whether an event is a landed compaction checkpoint — all three conditions,
+ * matching the terminal's `isCompactCheckpoint`: a `user/message`, carrying the
+ * compaction seam's checkpoint plugin source, that REPLACED a surface range. A
+ * plugin-sourced `user/message` that appends is injected context (a
+ * session-reference card), not a compaction; a replacement `tool/result` is an
+ * in-place prune and a replacement `assistant/message` a generic rewrite, and
+ * both mark no boundary in the conversation.
+ * @param event - the raw window event.
+ * @returns true when the event compacted a surface range.
+ */
+function isCompactCheckpoint(event: SessionEvent): boolean {
+  if (event.type !== 'user/message') return false
+  const source = event.data.source
+  return source.kind === 'plugin' && source.plugin === COMPACT_PLUGIN
+    && isReplacementSurfaceEvent(event)
+}
+
+/** Whether an event contributes a node to the human transcript. */
+function isTranscriptEvent(event: SessionEvent): boolean {
+  return isAppendSurfaceEvent(event) || isCompactCheckpoint(event)
+}
+
+/**
+ * Concatenated text of a `compact/summary` payload, or null when it carries no
+ * usable text. The payload is a `ContentBlock[]` whose union is
+ * merge-extensible, so a non-text block is skipped rather than discarding the
+ * text beside it; a payload with no text block at all falls to null through the
+ * empty check.
+ */
+function compactSummaryText(event: SessionEvent): string | null {
+  const summary = (event.data as unknown as { summary?: unknown }).summary
+  if (!Array.isArray(summary)) return null
+  let text = ''
+  for (const block of summary as readonly unknown[]) {
+    const candidate = block as { type?: unknown; text?: unknown }
+    if (candidate.type !== 'text' || typeof candidate.text !== 'string') continue
+    text += candidate.text
+  }
+  return text.trim() === '' ? null : text
+}
+
+interface CompactSummaryDetails {
+  readonly summary: string | null
+  readonly shadowedItemCount: number | null
+  readonly shadowedTokenCount: number | null
+}
+
+/** Recover human-facing summary material from one structurally narrowed wire event. */
+function compactSummaryDetails(event: SessionEvent): CompactSummaryDetails {
+  const data = event.data as unknown as { shadowedSeqs?: unknown; shadowedTokenCount?: unknown }
+  const shadowedSeqs = data.shadowedSeqs
+  const tokenCount = data.shadowedTokenCount
+  return {
+    summary: compactSummaryText(event),
+    shadowedItemCount: Array.isArray(shadowedSeqs)
+      && shadowedSeqs.every((seq: unknown) => Number.isSafeInteger(seq) && (seq as number) >= 0)
+      ? shadowedSeqs.length
+      : null,
+    shadowedTokenCount: Number.isSafeInteger(tokenCount) && (tokenCount as number) >= 0
+      ? tokenCount as number
+      : null,
+  }
+}
+
+/**
+ * One landed checkpoint -> the human-facing compaction marker. The summary text
+ * comes from the checkpoint's cited `compact/summary` event (`sourceEventSeqs` names the
+ * `compact/summary` event), never from the framed checkpoint payload, which is
+ * an instruction envelope written for the model. A window cut that left the
+ * summary event outside soft-falls to `summary: null` (a non-expandable marker),
+ * the same posture as a call-less tool result.
+ */
+function materializeCompaction(
+  checkpoint: SessionEvent,
+  eventIndex: ReadonlyMap<number, SessionEvent>,
+): CompactionSummaryNode {
+  const sources = (checkpoint as SessionEvent & { sourceEventSeqs?: number[] }).sourceEventSeqs
+  let summary: string | null = null
+  let summaryEventSeq: number | null = null
+  let shadowedItemCount: number | null = null
+  let shadowedTokenCount: number | null = null
+  for (const seq of sources ?? []) {
+    const candidate = eventIndex.get(seq)
+    if (candidate === undefined || (candidate.type as string) !== 'compact/summary') continue
+    const details = compactSummaryDetails(candidate)
+    summary = details.summary
+    summaryEventSeq = candidate.seq
+    shadowedItemCount = details.shadowedItemCount
+    shadowedTokenCount = details.shadowedTokenCount
+    break
+  }
+  return {
+    kind: 'compaction',
+    seq: checkpoint.seq,
+    time: checkpoint.time,
+    summary,
+    summaryEventSeq,
+    shadowedItemCount,
+    shadowedTokenCount,
+  }
+}
+
+/** Log-ordered human transcript over a paged raw event window (never consults surface order). */
+export class TranscriptAdapter {
+  /** Window events by seq, used to find the summary event cited by a checkpoint. */
+  private eventIndex = new Map<number, SessionEvent>()
+  /** Transcript nodes in log order; copy-on-write so a published array never mutates. */
+  private projected: ConversationNode[] = []
+  private callIdx = new Map<string, CallIndexEntry>()
+  /** Per-step timing boundaries (step/start + first token delta), consumed when the step's assistant/message materializes. */
+  private stepTimings = new Map<string, AssistantStepMetadata>()
+  /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */
+  private resultViews = new Map<number, ToolResultView>()
+  /** Durable inbox replay used to distinguish next-step human input from queued prompts. */
+  private readonly steeringHistory = new SteeringHistory()
+  /**
+   * Command lifecycle nodes by commandId (insertion = run order). The
+   * `command/run`/`command/done` pair is log-only, so it is not a surface
+   * event and never joins the transcript projection; this index folds the pair
+   * (done settles its run's node in place) and nodes() merges the products in
+   * by seq. Window cuts soft-fall like tool pairs: a done with no in-window
+   * run still builds a node.
+   */
+  private commandIdx = new Map<string, CommandNode>()
+  /** Projection revision, bumped only when a transcript node or a command node actually
+   *  changed, keying the nodes() result cache: an unchanged projection returns the previous
+   *  ARRAY reference, not just cached elements — the snapshot's reference-stability contract
+   *  starts here, and a chunk storm bumps nothing at all. */
+  private rev = 0
+  private nodesResult: { rev: number; value: readonly ConversationNode[] } | null = null
+
+  /**
+   * Window rebuild (after open/resync/page prepend): re-index the raw window
+   * and re-project the transcript.
+   * @param events - the new window contents (seq-ascending).
+   * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
+   */
+  reset(events: readonly SessionEvent[], views?: readonly (ToolEventView | undefined)[]): void {
+    this.rev++
+    this.eventIndex = new Map()
+    this.callIdx = new Map()
+    this.resultViews.clear()
+    this.commandIdx = new Map()
+    this.steeringHistory.reset()
+    const steeringSeqs = new Set<number>()
+    this.stepTimings = new Map()
+    for (let i = 0; i < events.length; i++) {
+      const event = events[i]
+      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
+      if (event === undefined) continue
+      this.eventIndex.set(event.seq, event)
+      this.indexCall(event, views?.[i])
+      this.indexCommand(event)
+      if (this.steeringHistory.apply(event)) steeringSeqs.add(event.seq)
+      indexAssistantStepTiming(this.stepTimings, event)
+    }
+    // Indexes first, then project: a tool/result materializes against the
+    // complete call index, and a checkpoint against the complete event index.
+    const projected: ConversationNode[] = []
+    for (const event of events) {
+      if (isTranscriptEvent(event)) projected.push(this.materialize(event, steeringSeqs.has(event.seq)))
+    }
+    this.projected = projected
+  }
+
+  /**
+   * Tail append (live session/event): index the event and, when it belongs to
+   * the transcript, extend the projection by one copy-on-write node so a
+   * published array never mutates. An event that changes no node (a chunk
+   * storm) bumps no revision, so nodes() keeps returning the same array
+   * reference.
+   * @param event - the live event (seq = window tail + 1).
+   * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering.
+   */
+  append(event: SessionEvent, view?: ToolEventView): void {
+    this.eventIndex.set(event.seq, event)
+    this.indexCall(event, view)
+    const steering = this.steeringHistory.apply(event)
+    indexAssistantStepTiming(this.stepTimings, event)
+    if (this.indexCommand(event)) this.rev++
+    if (!isTranscriptEvent(event)) return
+    this.projected = [...this.projected, this.materialize(event, steering)]
+    this.rev++
+  }
+
+  /**
+   * The current transcript node array. Same revision -> same array reference
+   * (memo boundary); node objects are materialized once, so an unchanged node
+   * keeps its identity across appends.
+   * @returns transcript nodes in log order, command nodes merged in by seq.
+   */
+  nodes(): readonly ConversationNode[] {
+    if (this.nodesResult !== null && this.nodesResult.rev === this.rev) return this.nodesResult.value
+    // Command nodes fold outside the transcript (log-only events); merge by
+    // seq. Both inputs are seq-ascending (log order and run-index insertion
+    // order are the same order), so one linear merge keeps flow order.
+    let nodes = this.projected
+    if (this.commandIdx.size > 0) {
+      nodes = []
+      const commands = [...this.commandIdx.values()]
+      let next = 0
+      for (const node of this.projected) {
+        for (let cmd = commands[next]; cmd !== undefined && cmd.seq < node.seq; cmd = commands[++next]) {
+          nodes.push(cmd)
+        }
+        nodes.push(node)
+      }
+      for (let cmd = commands[next]; cmd !== undefined; cmd = commands[++next]) nodes.push(cmd)
+    }
+    this.nodesResult = { rev: this.rev, value: nodes }
+    return nodes
+  }
+
+  /** Materialize one transcript event against the complete current indexes. */
+  private materialize(event: SessionEvent, steering: boolean): ConversationNode {
+    return isCompactCheckpoint(event)
+      ? materializeCompaction(event, this.eventIndex)
+      : materializeNode(
+        event,
+        this.callIdx,
+        this.resultViews.get(event.seq) ?? null,
+        steering,
+        this.stepTimings,
+      )
+  }
+
+  /**
+   * Fold one command lifecycle event into its node (run mints, done settles in
+   * place; done-only soft-falls).
+   * @returns whether the command index changed, so callers can bump the revision.
+   */
+  private indexCommand(event: SessionEvent): boolean {
+    // Log-only plugin events: the host-side dsh-commands declaration cannot
+    // enter the client program, so this wire consumer narrows structurally
+    // (the same posture as tool/code-dispatch in session.ts).
+    if ((event.type as string) === 'command/run') {
+      const data = event.data as unknown as { commandId: CommandId; name: string; args?: string }
+      this.commandIdx.set(data.commandId, {
+        kind: 'command', seq: event.seq, time: event.time,
+        commandId: data.commandId, name: data.name, args: data.args ?? null, outcome: null,
+      })
+      return true
+    }
+    if ((event.type as string) !== 'command/done') return false
+    const data = event.data as unknown as {
+      commandId: CommandId
+      kind: 'success' | 'error'
+      text?: string
+      sourceEventSeq?: number
+    }
+    const run = this.commandIdx.get(data.commandId)
+    const sourceEventSeq = data.kind === 'success'
+      && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
+      ? data.sourceEventSeq as number
+      : undefined
+    const outcome = {
+      kind: data.kind,
+      ...data.text === undefined ? {} : { text: data.text },
+      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
+    }
+    if (run === undefined) {
+      // Cross-window cut: the run page fell out of the window — build the
+      // node from the done alone (same soft-fall as a call-less tool result).
+      this.commandIdx.set(data.commandId, {
+        kind: 'command', seq: event.seq, time: event.time,
+        commandId: data.commandId, name: null, args: null, outcome,
+      })
+      return true
+    }
+    // Settle in place: a fresh node object (published references stay immutable).
+    this.commandIdx.set(data.commandId, { ...run, outcome })
+    return true
+  }
+
+  private indexCall(event: SessionEvent, view?: ToolEventView): void {
+    if (event.type === 'tool/result') {
+      if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
+      return
+    }
+    if (event.type !== 'tool/call') return
+    this.callIdx.set(String(event.data.callId), {
+      name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step,
+      time: event.time,
+      callView: view?.for === 'call' ? view.view : null,
+    })
+    // No backfill into already-materialized tool-result nodes for this callId
+    // (window order puts the call before its result; cannot happen on the normal path).
+  }
+}
diff --git a/packages/client/runtime/tests/client-apply.spec.ts b/packages/client/runtime/tests/client-apply.spec.ts
index 4f1ac11fcc..58d48affce 100644
--- a/packages/client/runtime/tests/client-apply.spec.ts
+++ b/packages/client/runtime/tests/client-apply.spec.ts
@@ -54,7 +54,7 @@ describe('runtime client apply', () => {
     const bench = await mount()
     expect(bench.ctx.get('slots') !== undefined).toBe(true)
     // The built-in 'root' declaration ships with this package's SlotsService
-    // (the SlotMap 'root' merge lives here since the slot-parity rework).
+    // (the SlotMap 'root' merge lives here).
     expect(bench.ctx.slots.spec('root')).toEqual({ kind: 'single', scope: 'root' })
     const sessions = bench.ctx.get('sessions')
     const workspaces = bench.ctx.get('workspaces')
diff --git a/packages/client/runtime/tests/event-script.ts b/packages/client/runtime/tests/event-script.ts
index 299e16785d..e6e36b37eb 100644
--- a/packages/client/runtime/tests/event-script.ts
+++ b/packages/client/runtime/tests/event-script.ts
@@ -140,7 +140,7 @@ export function plainTurn(startSeq: number, turn: number, ask: string, answer: s
   ]
 }
 
-/** Wrap raw events as view-less history entries (the wire shape history now returns). */
+/** Wrap raw events as view-less history entries (the wire shape history returns). */
 export function entries(events: readonly SessionEvent[]): { event: SessionEvent }[] {
   return events.map(event => ({ event }))
 }
diff --git a/packages/client/runtime/tests/projection-store.spec.ts b/packages/client/runtime/tests/projection-store.spec.ts
index 6547d365f5..5451b9e8b7 100644
--- a/packages/client/runtime/tests/projection-store.spec.ts
+++ b/packages/client/runtime/tests/projection-store.spec.ts
@@ -1,5 +1,6 @@
 /**
- * Projection value store (session-projection RFC, push model): the single
+ * Projection value store (push model; session-projection subsystem page:
+ * docs/subsystems/session-projection.md): the single
  * higher-seq-wins rule on both paths (a stale baseline cannot overwrite a
  * newer push frame; a replayed frame cannot regress), capability absence as
  * undefined, generation truncation, and the Session/manager wiring (tail-page
diff --git a/packages/client/runtime/tests/session.spec.ts b/packages/client/runtime/tests/session.spec.ts
index def97002f0..02df08de35 100644
--- a/packages/client/runtime/tests/session.spec.ts
+++ b/packages/client/runtime/tests/session.spec.ts
@@ -165,7 +165,7 @@ function chatSeqs(snapshot: ConversationSnapshot): number[] {
 }
 
 function histResponse(events: SessionEvent[], hasMore = false) {
-  // history now returns HistoryEntry[] ({event, view?}); these tests are view-less.
+  // history returns HistoryEntry[] ({event, view?}); these tests are view-less.
   return Promise.resolve(ok({ events: entries(events) as never[], hasMore }))
 }
 
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
new file mode 100644
index 0000000000..893635dcc7
--- /dev/null
+++ b/packages/client/runtime/tests/transcript-adapter.spec.ts
@@ -0,0 +1,567 @@
+/**
+ * TranscriptAdapter over the raw append-only window: log-ordered projection of
+ * append-origin events, one marker per landed compaction, replacement copies
+ * hidden, command-lifecycle folding, node/array identity, call pairing, and
+ * host-provided wire views.
+ */
+
+import { createUserMessage, CallId, createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
+import { describe, expect, it } from 'vitest'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
+import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts'
+import { ev, plainTurn } from './event-script.ts'
+
+const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
+  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
+
+/** A `compact/summary` event (log-only, no surfaceOp). */
+function compactSummary(seq: number, summary: unknown = [{ type: 'text', text: '# 摘要\n\n保留事实' }]): SessionEvent {
+  return at(seq, {
+    type: 'compact/summary',
+    data: {
+      summary,
+      shadowedRange: { start: 1, end: 3 },
+      shadowedSeqs: [1, 3],
+      shadowedTokenCount: 100,
+      provider: 'fake',
+      model: 'compact-1',
+    },
+  })
+}
+
+/** The replacement user message a compaction backend lands (the checkpoint). */
+function checkpoint(
+  seq: number,
+  summarySeq: number,
+  { start = 1, end = 3, sourceEventSeqs = [summarySeq, start, end] }: {
+    start?: number
+    end?: number
+    sourceEventSeqs?: number[]
+  } = {},
+): SessionEvent {
+  return at(seq, {
+    type: 'user/message',
+    surfaceOp: { op: 'replace', start, end },
+    sourceEventSeqs,
+    data: createUserMessage({
+      content: [{ type: 'text', text: '<context_checkpoint>model only</context_checkpoint>' }],
+      source: { kind: 'plugin', plugin: 'compact' },
+    }),
+  })
+}
+
+describe('TranscriptAdapter', () => {
+  it('projects a window starting past seq 0 at its own log positions', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset(plainTurn(100, 5, '偏移问', '偏移答'))
+    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 101], ['assistant', 103]])
+  })
+
+  it('appends incrementally keeping old node references (materialize-once identity)', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset(plainTurn(0, 0, 'a', 'b'))
+    const first = adapter.nodes()
+    adapter.append(ev.user(6, '追加'))
+    const second = adapter.nodes()
+    expect(second).toHaveLength(3)
+    expect(second[0]).toBe(first[0])
+    expect(second[1]).toBe(first[1])
+    expect(second).not.toBe(first) // a real change swaps the array
+  })
+
+  it('keeps the array reference across a chunk storm and swaps it when a node lands', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset(plainTurn(0, 0, 'a', 'b'))
+    const settled = adapter.nodes()
+    adapter.append(ev.chunkStart(6, 1))
+    expect(adapter.nodes()).toBe(settled)
+    adapter.append(ev.chunkText(7, 1, '流式'))
+    expect(adapter.nodes()).toBe(settled)
+    adapter.append(ev.assistant(8, 1, '流式完成'))
+    const finalized = adapter.nodes()
+    expect(finalized).not.toBe(settled)
+    expect(finalized.at(-1)).toMatchObject({ kind: 'assistant', seq: 8 })
+  })
+
+  it('materializes every append-origin variant with field mapping', () => {
+    const adapter = new TranscriptAdapter()
+    const steering = createUserMessage({
+      content: [{ type: 'text', text: '插话' }],
+      source: { kind: 'user' },
+    })
+    adapter.reset([
+      ev.user(0, '用户'),
+      ev.assistant(1, 0, '助手'),
+      at(2, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, inserted: [steering],
+      } }),
+      at(3, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, removedCount: 1, inserted: [],
+      } }),
+      at(4, { type: 'user/message', surfaceOp: 'append', data: steering }),
+      at(5, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+        content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' },
+      }) }),
+      ev.toolCall(6, 0, 'c1', 'echo', '{"x":1}'),
+      ev.toolResult(7, 0, 'c1', '结果'),
+    ])
+    const nodes = adapter.nodes()
+    expect(nodes.map(n => n.kind)).toEqual(['user', 'assistant', 'steering', 'context', 'tool-result'])
+    expect(nodes.find(n => n.kind === 'steering')).toMatchObject({ messageId: steering.id })
+    expect(nodes.find(n => n.kind === 'tool-result')).toMatchObject({
+      callId: 'c1', call: { name: 'echo', argsRaw: '{"x":1}' }, isError: false,
+    })
+  })
+
+  it('identifies steering on the live append path', () => {
+    const adapter = new TranscriptAdapter()
+    const steering = createUserMessage({
+      content: [{ type: 'text', text: 'live steer' }],
+      source: { kind: 'user' },
+    })
+    adapter.reset([])
+    adapter.append(at(0, { type: 'agent/inbox/spliced', data: {
+      target: 'next-step', start: 0, inserted: [steering],
+    } }))
+    adapter.append(at(1, { type: 'agent/inbox/spliced', data: {
+      target: 'next-step', start: 0, removedCount: 1, inserted: [],
+    } }))
+    adapter.append(at(2, { type: 'user/message', surfaceOp: 'append', data: steering }))
+    expect(adapter.nodes()).toMatchObject([{ kind: 'steering', messageId: steering.id }])
+  })
+
+  it('does not mark queued, canceled, or non-user next-step messages as steering', () => {
+    const adapter = new TranscriptAdapter()
+    const queued = createUserMessage({ content: [{ type: 'text', text: 'queued' }], source: { kind: 'user' } })
+    const canceled = createUserMessage({ content: [{ type: 'text', text: 'canceled' }], source: { kind: 'user' } })
+    const context = createUserMessage({
+      content: [{ type: 'text', text: 'context' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    })
+    adapter.reset([
+      at(0, { type: 'agent/inbox/spliced', data: {
+        target: 'next-turn', start: 0, inserted: [queued],
+      } }),
+      at(1, { type: 'agent/inbox/spliced', data: {
+        target: 'next-turn', start: 0, removedCount: 1, inserted: [],
+      } }),
+      at(2, { type: 'user/message', surfaceOp: 'append', data: queued }),
+      at(3, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, inserted: [canceled],
+      } }),
+      at(4, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, removedCount: 1, inserted: [], outcome: 'canceled',
+      } }),
+      at(5, { type: 'user/message', surfaceOp: 'append', data: canceled }),
+      at(6, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, inserted: [context],
+      } }),
+      at(7, { type: 'agent/inbox/spliced', data: {
+        target: 'next-step', start: 0, removedCount: 1, inserted: [],
+      } }),
+      at(8, { type: 'user/message', surfaceOp: 'append', data: context }),
+    ])
+    expect(adapter.nodes().map(node => node.kind)).toEqual(['user', 'user', 'context'])
+  })
+
+  it('materializes a skill-invocation injection as a named instructions context', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset([
+      at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+        content: [{ type: 'text', text: '/hidden-demo check the fixture' }],
+        source: { kind: 'user' },
+      }) }),
+      at(1, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+        content: [{ type: 'text', text: '<skill_content name="hidden-demo">body</skill_content>' }],
+        source: { kind: 'skill-invocation', name: 'hidden-demo', form: 'instructions' } as never,
+      }) }),
+    ])
+    const nodes = adapter.nodes()
+    // The gesture stays a user bubble; the injected body folds to a context
+    // row named after the skill, presented as instructions.
+    expect(nodes.map(node => node.kind)).toEqual(['user', 'context'])
+    expect(nodes[1]).toMatchObject({
+      provenance: { role: 'inject', label: 'hidden-demo' },
+      form: 'instructions',
+    })
+  })
+
+  it('skips events core does not call surface-eligible, marker or not', () => {
+    // The transcript is the append-origin surface, so log-only events (a chunk,
+    // a turn boundary, a `compact/*` record) and a future type core
+    // has not admitted contribute no node.
+    const adapter = new TranscriptAdapter()
+    adapter.reset([
+      ev.turnStart(0, 1),
+      at(1, { type: 'notice/message', surfaceOp: 'append', data: { note: 1 } }),
+      compactSummary(2),
+      ev.user(3, '唯一的一条'),
+      ev.turnEnd(4, 1),
+    ])
+    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 3]])
+  })
+
+  describe('compaction markers', () => {
+    it('keeps the original messages and full tool output, hiding replacement copies', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, '原始问题'),
+        ev.assistant(1, 0, '原始回答'),
+        ev.toolCall(4, 0, 'c1', 'echo', '{}'),
+        ev.toolResult(5, 0, 'c1', '完整工具输出'),
+        // A pruned tool/result copy: rewrites one node for the model, marks nothing.
+        at(6, { type: 'tool/result', surfaceOp: { op: 'replace', start: 5, end: 5 }, sourceEventSeqs: [5], data: {
+          turn: 0, step: 0,
+          message: createToolResultMessage({ callId: CallId('c1'), content: [{ type: 'text', text: '已裁剪' }], isError: false }),
+        } }),
+        compactSummary(7),
+        checkpoint(8, 7, { start: 1, end: 5, sourceEventSeqs: [7, 1, 5] }),
+        // A regenerated assistant/message: also a silent model-only rewrite.
+        at(9, { type: 'assistant/message', surfaceOp: { op: 'replace', start: 8, end: 8 }, sourceEventSeqs: [8], data: {
+          turn: 0, step: 0,
+          message: createMessage({
+            role: 'assistant',
+            content: [{ type: 'text', text: '通用 replacement 副本' }],
+            source: { kind: 'model', ...{ provider: 'x', model: 'copy' } },
+          }),
+        } }),
+      ])
+      const nodes = adapter.nodes()
+      expect(nodes.map(n => [n.kind, n.seq])).toEqual([
+        ['user', 0], ['assistant', 1], ['tool-result', 5], ['compaction', 8],
+      ])
+      expect(nodes[2]).toMatchObject({ kind: 'tool-result', content: [{ type: 'text', text: '完整工具输出' }] })
+      expect(nodes[3]).toMatchObject({ kind: 'compaction', summary: '# 摘要\n\n保留事实' })
+    })
+
+    it('adds one marker per landed compaction, in log order', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, 'a'),
+        compactSummary(1, [{ type: 'text', text: 'first' }]),
+        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
+        ev.user(3, 'b'),
+        compactSummary(4, [{ type: 'text', text: 'second' }]),
+        checkpoint(5, 4, { start: 2, end: 3, sourceEventSeqs: [4, 2, 3] }),
+      ])
+      expect(adapter.nodes().filter(n => n.kind === 'compaction')).toEqual([
+        {
+          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: 'first',
+          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
+        },
+        {
+          kind: 'compaction', seq: 5, time: 1_700_000_000_005, summary: 'second',
+          summaryEventSeq: 4, shadowedItemCount: 2, shadowedTokenCount: 100,
+        },
+      ])
+    })
+
+    it('renders the marker when the shadowed range is outside the window and logs nothing', () => {
+      // Pagination spends no quota on replacement copies, so a page can carry
+      // a checkpoint whose surfaceOp.start lies below the window head. A
+      // surface fold would throw on the missing range and degrade with a
+      // console error; a log-ordered
+      // projection has no range to resolve.
+      const adapter = new TranscriptAdapter()
+      const noise = { error: console.error, warn: console.warn }
+      const logged: unknown[] = []
+      console.error = (...args: unknown[]) => logged.push(args)
+      console.warn = (...args: unknown[]) => logged.push(args)
+      try {
+        adapter.reset([
+          compactSummary(80, [{ type: 'text', text: '窗外范围' }]),
+          checkpoint(81, 80, { start: 3, end: 40, sourceEventSeqs: [80, 3, 40] }),
+          ev.user(82, '压缩后的新问题'),
+        ])
+        expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['compaction', 81], ['user', 82]])
+        expect(adapter.nodes()[0]).toMatchObject({ summary: '窗外范围' })
+      } finally {
+        console.error = noise.error
+        console.warn = noise.warn
+      }
+      expect(logged).toEqual([])
+    })
+
+    it('treats an APPENDING plugin-sourced user/message as injected context, not a compaction', () => {
+      // A session-reference card carries the same plugin source shape; only the
+      // replacement marker makes an event a checkpoint.
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
+          content: [{ type: 'text', text: '注入的上下文' }],
+          source: { kind: 'plugin', plugin: 'compact', form: 'instructions' },
+        }) }),
+      ])
+      expect(adapter.nodes()).toMatchObject([{
+        kind: 'context',
+        seq: 0,
+        provenance: { role: 'inject', label: 'compact' },
+        form: 'instructions',
+      }])
+    })
+
+    it('ignores a foreign plugin s replacement user/message', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, '保留'),
+        at(1, { type: 'user/message', surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0], data: createUserMessage({
+          content: [{ type: 'text', text: '别的插件重写' }],
+          source: { kind: 'plugin', plugin: 'not-compact' },
+        }) }),
+      ])
+      expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 0]])
+    })
+
+    it.each([
+      ['absent summary event', undefined],
+      ['text-less summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])],
+      ['a whitespace-only summary', compactSummary(1, [{ type: 'text', text: '   ' }])],
+      ['an empty summary array', compactSummary(1, [])],
+      ['a non-array summary', compactSummary(1, 'plain string')],
+    ])('degrades %s to a non-expandable marker', (_label, summary) => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ...(summary === undefined ? [] : [summary]),
+        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
+      ])
+      expect(adapter.nodes()).toMatchObject([
+        { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null },
+      ])
+    })
+
+    it('keeps the text of a mixed-block summary, skipping the blocks it cannot render', () => {
+      // ContentBlock is merge-extensible and the payload type is ContentBlock[],
+      // so a non-text block must not discard recoverable text beside it.
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        compactSummary(1, [{ type: 'text', text: '可用摘要' }, { type: 'image', data: 'nope' }]),
+        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
+      ])
+      expect(adapter.nodes()).toEqual([
+        {
+          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: '可用摘要',
+          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
+        },
+      ])
+    })
+
+    it('leaves the summary null when the checkpoint cites no source events', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([at(2, {
+        type: 'user/message',
+        surfaceOp: { op: 'replace', start: 0, end: 0 },
+        data: createUserMessage({
+          content: [{ type: 'text', text: '<context_checkpoint>x</context_checkpoint>' }],
+          source: { kind: 'plugin', plugin: 'compact' },
+        }),
+      })])
+      expect(adapter.nodes()).toEqual([{
+        kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null,
+        summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
+      }])
+    })
+
+    it('skips a cited non-summary seq before reaching the summary event', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, '被压缩的问题'),
+        at(1, { type: 'compact/start', data: { turn: 0 } }),
+        compactSummary(2, [{ type: 'text', text: '第三个来源才是摘要' }]),
+        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [1, 2, 0] }),
+      ])
+      expect(adapter.nodes().at(-1)).toMatchObject({ kind: 'compaction', summary: '第三个来源才是摘要' })
+    })
+
+    it('resolves the summary once an older page supplies the cited summary event', () => {
+      const adapter = new TranscriptAdapter()
+      const landed = checkpoint(8, 7, { start: 0, end: 0, sourceEventSeqs: [7, 0] })
+      adapter.reset([landed])
+      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: null })
+      adapter.reset([compactSummary(7, [{ type: 'text', text: '分页补齐的摘要' }]), landed])
+      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: '分页补齐的摘要' })
+    })
+
+    it('creates the marker on the live append path', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset(plainTurn(0, 0, 'a', 'b'))
+      adapter.append(compactSummary(6, [{ type: 'text', text: '直播摘要' }]))
+      adapter.append(checkpoint(7, 6, { start: 1, end: 3, sourceEventSeqs: [6, 1, 3] }))
+      const nodes = adapter.nodes()
+      // The compacted history is still there; the marker is one more row after it.
+      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 1], ['assistant', 3], ['compaction', 7]])
+      expect(nodes.at(-1)).toMatchObject({ kind: 'compaction', seq: 7, summary: '直播摘要' })
+    })
+  })
+
+  it('returns call:null for a tool-result whose call fell outside the window', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset([ev.toolResult(50, 3, 'outside-call', '孤儿结果')])
+    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null })
+  })
+
+  it('materializes a tool-result error field when present', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset([
+      at(0, { type: 'tool/result', surfaceOp: 'append', data: {
+        turn: 0, step: 0,
+        message: createToolResultMessage({ callId: CallId('c1'), content: [], isError: true }),
+        error: { name: 'Boom', code: 'boom' },
+      } }),
+    ])
+    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } })
+  })
+
+  it('attaches wire views to the materialized result node', () => {
+    const adapter = new TranscriptAdapter()
+    const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } }
+    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } }
+    adapter.reset([
+      ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'),
+      ev.toolResult(1, 1, 'c1', 'listing'),
+    ], [callView, resultView] as never)
+    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
+      callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' },
+    })
+  })
+
+  it('attaches views on the live append path and defaults to null without views', () => {
+    const adapter = new TranscriptAdapter()
+    adapter.reset(plainTurn(0, 0, 'a', 'b')) // no views argument
+    adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never)
+    adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result
+    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
+      callView: { title: '回声' }, resultView: null,
+    })
+  })
+
+  it('leaves callView null when the paired call fell outside the window (cross-page break)', () => {
+    const adapter = new TranscriptAdapter()
+    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } }
+    adapter.reset([ev.toolResult(50, 3, 'outside', '窗外配对')], [resultView] as never)
+    expect(adapter.nodes()[0]).toMatchObject({
+      kind: 'tool-result', call: null, callView: null, resultView: { title: '孤儿' },
+    })
+  })
+
+  describe('command lifecycle nodes', () => {
+    it('folds a run/done pair into one settled node merged into flow order by seq', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, '先说话'),
+        ev.commandRun(1, 'cmd-1', 'plan'),
+        ev.commandDone(2, 'cmd-1', 'success', '已进入 plan mode'),
+        ev.assistant(3, 0, '然后回答'),
+      ])
+      const nodes = adapter.nodes()
+      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['assistant', 3]])
+      expect(nodes[1]).toMatchObject({
+        kind: 'command', commandId: 'cmd-1', name: 'plan', args: '',
+        outcome: { kind: 'success', text: '已进入 plan mode' },
+      })
+    })
+
+    it('renders a run with no done as still executing (outcome null)', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.commandRun(0, 'cmd-2', 'goal', ' ship it')])
+      expect(adapter.nodes()[0]).toMatchObject({ kind: 'command', name: 'goal', args: ' ship it', outcome: null })
+    })
+
+    it('represents command input omitted by the host as null', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.commandRunWithoutInput(0, 'cmd-private', 'feedback')])
+      expect(adapter.nodes()[0]).toMatchObject({
+        kind: 'command', name: 'feedback', args: null, outcome: null,
+      })
+    })
+
+    it('soft-falls a done-only window into a node built from the done (cross-window cut)', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.commandDone(80, 'cmd-3', 'error', '失败了')])
+      expect(adapter.nodes()[0]).toMatchObject({
+        kind: 'command', seq: 80, commandId: 'cmd-3', name: null, args: null,
+        outcome: { kind: 'error', text: '失败了' },
+      })
+    })
+
+    it('settles a live-appended done in place, keeping the node at the run seq', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset(plainTurn(0, 0, 'q', 'a'))
+      adapter.append(ev.commandRun(6, 'cmd-4', 'clear'))
+      const running = adapter.nodes().find(n => n.kind === 'command')
+      expect(running).toMatchObject({ outcome: null })
+      adapter.append(ev.commandDone(7, 'cmd-4'))
+      const settled = adapter.nodes().find(n => n.kind === 'command')
+      expect(settled).toMatchObject({ seq: 6, outcome: { kind: 'success' } })
+      // Settlement replaced the node object rather than mutating the published one.
+      expect(settled).not.toBe(running)
+    })
+
+    it('tails command nodes whose seq is past every transcript node', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.user(0, '问'), ev.commandRun(1, 'cmd-tail', 'plan')])
+      expect(adapter.nodes().map(n => n.kind)).toEqual(['user', 'command'])
+    })
+
+    it('preserves the domain-event link for the UI to fold a /compact row into its marker', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.user(0, '压缩前的问题'),
+        ev.commandRun(1, 'cmd-compact', 'compact'),
+        compactSummary(2, [{ type: 'text', text: '手动压缩摘要' }]),
+        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [2, 0] }),
+        ev.commandDone(4, 'cmd-compact', 'success', '已压缩', 2),
+      ])
+      const nodes = adapter.nodes()
+      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['compaction', 3]])
+      expect(nodes[1]).toMatchObject({
+        name: 'compact',
+        outcome: { kind: 'success', text: '已压缩', sourceEventSeq: 2 },
+      })
+      expect(nodes[2]).toMatchObject({ kind: 'compaction', summaryEventSeq: 2 })
+    })
+  })
+
+  describe('assistant timing', () => {
+    const base = 1_700_000_000_000
+
+    it('derives step timing across a window rebuild (start + first token + completion)', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([
+        ev.turnStart(0, 0),
+        ev.user(1, '问'),
+        ev.stepStart(2, 0),
+        ev.chunkStart(3, 0),
+        ev.chunkText(4, 0, '答'),
+        ev.chunkText(5, 0, '案'),
+        ev.assistant(6, 0, '答案'),
+        ev.turnEnd(7, 0),
+      ])
+      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
+      expect(assistant).toMatchObject({
+        timing: { stepStartTime: base + 2, firstTokenTime: base + 4, completedTime: base + 6 },
+      })
+    })
+
+    it('derives the same timing on the live append path, first token winning once', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.user(0, '问')])
+      adapter.append(ev.stepStart(1, 0))
+      adapter.append(ev.chunkText(2, 0, '首'))
+      adapter.append(ev.chunkText(3, 0, '次'))
+      adapter.append(ev.assistant(4, 0, '首次'))
+      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
+      expect(assistant).toMatchObject({
+        timing: { stepStartTime: base + 1, firstTokenTime: base + 2, completedTime: base + 4 },
+      })
+    })
+
+    it('soft-falls to null boundaries when the step opening fell outside the window', () => {
+      const adapter = new TranscriptAdapter()
+      adapter.reset([ev.assistant(100, 0, '被切窗的答案')])
+      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
+      expect(assistant).toMatchObject({
+        timing: { stepStartTime: null, firstTokenTime: null, completedTime: base + 100 },
+      })
+    })
+  })
+})
diff --git a/packages/client/ui-command/src/client/PopupSelectView.tsx b/packages/client/ui-command/src/client/PopupSelectView.tsx
index 456cdd4200..1b91a60d46 100644
--- a/packages/client/ui-command/src/client/PopupSelectView.tsx
+++ b/packages/client/ui-command/src/client/PopupSelectView.tsx
@@ -54,8 +54,8 @@ export function PopupSelectView({ popup, t }: PopupSelectViewProps) {
     cardRef.current?.querySelector('[aria-selected="true"]')?.scrollIntoView({ block: 'nearest' })
   }, [active])
 
-  // Focus ownership: the search input grabs on open (the design's
-  // transient-layer rule), and ANY outside pointer interaction dismisses —
+  // Focus ownership: the search input grabs on open, and ANY outside
+  // pointer interaction dismisses —
   // capture phase so a click landing anywhere else (textarea included)
   // closes the shell before its own handlers run; that click's target then
   // takes focus naturally, so no focusComposer here.
diff --git a/packages/client/ui-command/src/client/popup.ts b/packages/client/ui-command/src/client/popup.ts
index 5e20911820..1b30c18459 100644
--- a/packages/client/ui-command/src/client/popup.ts
+++ b/packages/client/ui-command/src/client/popup.ts
@@ -1,5 +1,5 @@
 /**
- * Headless popupSelect shell state (design §10): one controller per client
+ * Headless popupSelect shell state: one controller per client
  * session, owned by CommandService's per-session map and torn down by the
  * session scope disposer. The shell is a transient layer (never in the input
  * state machine): it loads options once, filters them locally against the
diff --git a/packages/client/ui-command/tests/popup-view.spec.tsx b/packages/client/ui-command/tests/popup-view.spec.tsx
index 0bbe01b4a9..e1459ce136 100644
--- a/packages/client/ui-command/tests/popup-view.spec.tsx
+++ b/packages/client/ui-command/tests/popup-view.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 /**
- * PopupSelectView interaction spec (design §10.2): the search input takes
+ * PopupSelectView interaction spec: the search input takes
  * focus on open and plain typing filters locally, ↑↓ move the filtered
  * highlight while ←→ stay native to the input, Enter selects single-flight,
  * Escape dismisses back through focusComposer, outside pointerdown dismisses
diff --git a/packages/client/ui-command/tests/popup.spec.ts b/packages/client/ui-command/tests/popup.spec.ts
index 68e8084b80..ef1c464c66 100644
--- a/packages/client/ui-command/tests/popup.spec.ts
+++ b/packages/client/ui-command/tests/popup.spec.ts
@@ -1,5 +1,5 @@
 /**
- * PopupSelectController behavior (design §10.2/§10.3): one options load per
+ * PopupSelectController behavior: one options load per
  * open with local search filtering, filtered highlight movement,
  * single-flight select with open-time context, consume-on-success (CAS miss
  * benign), failure-keeps-open retry semantics for both options and onSelect,
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 1238e136d7..6c197a5107 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: d894d3e578f065e9cb2c45676224efd1f4f76fa8
-README.zh.md: ec99a8d7daa593cdf3014f292a095fb2fd6f39d3
+README.md: b57f88b5a030a6c20c957e26ea32fb125f106ab4
+README.zh.md: a8a8c4814086cad02c5416078f242ec92a7503d7
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index d894d3e578..b57f88b5a0 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -38,7 +38,7 @@ Per-session UI state for selection and the active view lives in the declared cha
 
 The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop controls), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. The leading plus button is a Command launcher, not an attachment surface: it asks the session's `SlashController` to open only the `/` trigger's `command` source over the current textarea selection, while ui-slash's existing `MenuView` remains the sole floating menu and pick path. No file row, file input, upload protocol, or second menu component is introduced. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `conversation` locale namespace this package registers (the `placeholder.plan` / `hint.plan` keys) and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar renders inert (machine faces absent, `disabled` owner prop) instead of swapping in a parallel disabled tree, so the textarea DOM survives the workspace pick; the strict-session control seats simply stay empty until a session exists.
 
-The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. The same window fold averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy moved off the row onto the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation.
+The chat stats line takes its token accounting from the generic token-meter `tokenUsage` projection read through the standard-kit `useProjection`: billed input is uncached input plus cache reads and writes; cache hit divides cache reads by that total. Visible nodes supply only the turn and step counts plus the LLM and tool wall times, which are window-scoped facts about what is on screen rather than accounting; durable token and context groups remain visible when compaction leaves no assistant node in the loaded window. The same window fold averages each recorded step's TTFT and divides sampled output tokens by their summed decode spans into a latency/throughput group localized through the `conversation` locale namespace (`TTFT avg … · … tok/s` in English); a step missing a timing boundary or a usage sample drops out of those figures instead of skewing them. The turn-count, step-count, duration, cache, and token labels use the same namespace. Each settled turn additionally appends hover-revealed `TTFT {s}s · {tps} tok/s` labels to its assistant footer after the `Ran for` duration — the turn's first-step TTFT and its turn-aggregate decode throughput — gated on the turn's timing being in the loaded window (a contiguous log suffix, so an in-window turn carries every one of its steps) and omitting whichever figure is unrecorded. A deployment without token-meter drops the token groups; when the line overflows, it elides with an ellipsis and a delayed hover tooltip carries the full text only while actually clipped. Context occupancy renders as the composer's trailing ContextMeter: a 14px occupancy ring after the model seat, fed by `contextPressure` and rendered only once both a numerator and a route capacity are known, that click-opens a panel pairing the `percent used` header and `~used / capacity` figures with a color-segmented bar and `~`-prefixed heuristic composition rows (system prompt, tools, messages) from the `contextBreakdown` projection. The ring and header read `projectedTokens` — the provider sample carried forward over the surface's movement since — so a compaction registers immediately instead of after a further turn; the composition rows stay wholly heuristic and therefore still do not sum to the header ([rationale](../../llm/token-meter/README.md)). Occupancy is deliberately an approximation: numerator and capacity are independent last-wins projection fields, not one atomic request observation.
 
 `src/client/` is organized by domain. `contract/` is the shared face for slot declarations, composed props, and cross-domain types; `skeleton/`, `chat/`, `input/`, `queue/`, and `settings/` keep their implementations internal, while `apply.ts` is their assembly point. The `/client` export surface contains only loader entries, service classes, and contract types; components and store factories reach the page through slot registrations.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index ec99a8d7da..a8a8c48140 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -38,7 +38,7 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止控件之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。前置加号按钮是 Command launcher，而非附件入口：它要求当前会话的 `SlashController` 基于 textarea 当前 selection，只打开 `/` trigger 的 `command` source，同时 ui-slash 既有的 `MenuView` 仍是唯一的浮层菜单与 pick 路径。不引入 File 行、file input、上传协议或第二套菜单组件。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `conversation` locale 命名空间（`placeholder.plan` / `hint.plan` 键）本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。
 
-聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。同一次窗口折算还会把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率从统计行移到了 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当分子与路由容量都已知时才渲染；点击弹出的面板把「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列。圆环与标题读取 `projectedTokens`——把提供方样本沿此后表层的增减推进到当下——因此压缩会立刻反映出来，而不必再等一整轮；组成明细行仍是纯启发式，因此加起来依然不等于标题数字（[原理](../../llm/token-meter/README.md)）。占用率是刻意为之的近似值：分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测。
+聊天统计行的 token 账目来自经标准套件 `useProjection` 读取的通用 token-meter 投影 `tokenUsage`：计费输入为未缓存输入、缓存读取与缓存写入之和；缓存命中率以缓存读取除以该总量。可见节点只提供轮次与步骤计数，以及 LLM（大语言模型）和工具的墙钟时间：这些是关于「屏幕上有什么」的窗口作用域事实，而非账目；压缩（compaction）使已加载窗口不再包含 assistant 节点时，持久 token 与上下文分组仍保持可见。同一次窗口折算还会把每个有完整记录的步骤的 TTFT（首 token 延迟）取平均，并用采样到的输出 token 数除以其解码时长之和，得到经 `conversation` locale 命名空间本地化的延迟／吞吐分组（中文为 `首 token 平均 … · … tok/s`）；缺少某个 timing 边界或 usage 采样的步骤会直接退出这些数字，而不是让它们失真。轮次计数、步骤计数、耗时、缓存与 token 各项的标签也使用同一命名空间。每个已结算轮次还会在其 assistant footer 的 `用时` 之后追加 hover 才显示的 `首 token {s}秒 · {tps} tok/s` 标签——即该轮次首个步骤的 TTFT 与轮次聚合的解码吞吐——仅当该轮次的 timing 位于已加载窗口内才显示（窗口是日志的连续后缀，因此窗口内的轮次必然带着它的全部步骤），未记录的数字会各自省略。未组合 token-meter 的部署会整组省略 token 分组；统计行过长时以省略号截断，仅在内容真的被裁切时由延迟 hover tooltip 承载完整文本。上下文占用率渲染为 composer 尾部的 ContextMeter：模型座位之后的一枚 14px 占用圆环，由 `contextPressure` 供数，仅当分子与路由容量都已知时才渲染；点击弹出的面板把「已用百分比」标题与 `~已用 / 容量` 数字，与来自 `contextBreakdown` 投影、带 `~` 前缀的启发式组成明细行（系统提示词、工具、对话消息）及分色分段进度条并列。圆环与标题读取 `projectedTokens`——把提供方样本沿此后表层的增减推进到当下——因此压缩会立刻反映出来，而不必再等一整轮；组成明细行仍是纯启发式，因此加起来依然不等于标题数字（[原理](../../llm/token-meter/README.md)）。占用率是刻意为之的近似值：分子与容量是两个相互独立的「后写覆盖」投影字段，并非同一次请求的原子观测。
 
 `src/client/` 按领域组织。`contract/` 是 slot 声明、组合 props 与跨领域类型的共享表层；`skeleton/`、`chat/`、`input/`、`queue/` 和 `settings/` 保持内部实现，`apply.ts` 是它们的组装点。`/client` 导出表层只包含 loader entry、service class 和 contract 类型；组件与 store factory 经 slot 注册抵达页面。
 
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 6d8e8e8c67..401d9883a6 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -160,7 +160,7 @@ export function apply(ctx: Context): void {
   // way: this package must not import the plugins that would know.
   const composerBlocks = new ComposerBlockRegistry()
 
-  // Decision 19/20: the input machine feeds every session-scope slot
+  // The input machine feeds every session-scope slot
   // component through the standard provide channel — the 'input' hook plus
   // the two public actions. Materialization is the shell creation trigger
   // (per-session lazy; scope disposer tears down).
@@ -241,7 +241,7 @@ export function apply(ctx: Context): void {
   }, ConversationSessionHeader)
 
   // The default composer body: its own single slot inside the composer
-  // chain's fallback (decision 20). Public machine surface arrives via the
+  // chain's fallback. Public machine surface arrives via the
   // provide channel above; the keyboard command face and the stop/retry
   // verbs ride this inject (package-internal — hub and bar are one plugin).
   // Session-maybe: with no current session the machine faces are absent and
@@ -252,7 +252,7 @@ export function apply(ctx: Context): void {
     locale: NS,
     // The two named control seats in the bar's tool row (plan beside the
     // access control, model right); empty until their owning plugins
-    // register (B ruling).
+    // register.
     children: {
       'conversation.input.plan': { kind: 'single', scope: 'session' },
       'conversation.input.model': { kind: 'single', scope: 'session' },
@@ -382,7 +382,7 @@ export function apply(ctx: Context): void {
   // The plan strip rides the input dock above the queue rows (same posture).
   ctx.plugin(todoDockEntry)
 
-  // The read-only queue dock entry (T9 file territory) rides the same
+  // The read-only queue dock entry rides the same
   // registration path into the input dock declared above.
   ctx.plugin(queueDockEntry)
 
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index 44ae6f345a..cae17b3865 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -180,7 +180,7 @@ export function ChatView({
   const lastKeyRef = useRef<string | null>(null)
   const lastSteeringIdRef = useRef<string | null>(null)
   /** Flow tip signature — follow-scroll only when this moves, never on a
-   *  scroll-driven at-bottom chrome re-render (that was snapping inertial
+   *  scroll-driven at-bottom chrome re-render (which would snap inertial
    *  scrolls the rest of the way to the floor). */
   const followSigRef = useRef<string | null>(null)
 
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
index 972fba8710..a0d85e85e8 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
@@ -123,8 +123,8 @@ function TurnErrorItem({ node, t }: {
  * Display projection of reference forms in a user bubble (free geometry — no
  * textarea alignment constraint here); everything else stays plain text. The
  * logged model text remains the single truth; this is presentation only.
- * Plain-text `/name` / `@name` word-boundary tokens decorate (decision 21:
- * the sent text IS the reference — the bubble uses the same plainest token
+ * Plain-text `/name` / `@name` word-boundary tokens decorate (the sent text
+ * IS the reference — the bubble uses the same plainest token
  * scan as the composer, minus the lexicon: sent tokens were validated at
  * compose time, so shape alone decorates).
  */
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 56fca2381c..8d292abd53 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -79,14 +79,14 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * reads the global workspace list.
      */
     'conversation.hero.workspace': { kind: 'single'; scope: 'root'; owner: EmptyWorkspaceOwnerProps }
-    // 'conversation.input.overlay' merges in ui-slash (dedup ruling: the
-    // dependency direction is the hard constraint — ui-slash cannot import
+    // 'conversation.input.overlay' merges in ui-slash (the dependency
+    // direction is the hard constraint — ui-slash cannot import
     // this package, while this package's input contract already imports
     // ui-slash, so the type arrives transitively). The runtime declaration
     // (children table in apply.ts) stays here with the other input slots.
     /**
      * Stacked strip above the input (queue rows / GoalBar / attachments;
-     * design §6 MIX evidence: entries coexist in fixed order).
+     * entries coexist in fixed order).
      */
     'conversation.input.dock': { kind: 'list'; scope: 'session'; owner: InputZone }
     /** The band under the composer card (stats line family), rendered inside the bar's width column via the `footer` owner prop. */
@@ -97,7 +97,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     'conversation.input.right': { kind: 'list'; scope: 'session'; owner: InputZone }
     /**
      * The default composer body: a single slot rendered as the composer
-     * chain's fallback (decision 20 — a real entry, not a chain rider, so a
+     * chain's fallback (a real entry, not a chain rider, so a
      * takeover election hides rather than unmounts it and the textarea DOM
      * survives). Session-maybe: the bar stays mounted across the
      * no-session/session transition — the no-workspace hero renders the SAME
@@ -111,7 +111,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     /**
      * The Plan-mode status seat in the composer tool row (left group,
      * right of the access-mode control). Declared by the composer-bar
-     * entry; empty until a plan plugin registers (B ruling: no placeholder
+     * entry; empty until a plan plugin registers (no placeholder
      * fallback).
      */
     'conversation.input.plan': { kind: 'single'; scope: 'session'; owner: InputControlOwnerProps }
@@ -124,7 +124,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 
   /**
    * ui-conversation's members of the session standard kit, provided through
-   * `sessions.provide` (decision 19/20): every session-scope slot component
+   * `sessions.provide`: every session-scope slot component
    * receives the input machine's state hook and the two public actions.
    */
   interface SessionStandardProps {
@@ -145,7 +145,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 export interface ConversationHeaderActionOwnerProps {}
 
 /**
- * The input-region slot currency (plan §1.4): dock/left/right entries read
+ * The input-region slot currency: dock/left/right entries read
  * the conversation snapshot and the live input state as owner props (both
  * are point-in-time snapshots — the dispatching skeleton re-renders on
  * either store's change, so entries stay current without subscribing).
@@ -353,7 +353,7 @@ export interface ComposerBarOwnerProps {
 
 /** Injected share of the composer-bar entry (package-internal faces). */
 export interface ComposerBarInjected {
-  /** The InputBar-exclusive keyboard/DOM command face (decision 20 private plane); absent with the session. */
+  /** The InputBar-exclusive keyboard/DOM command face (private plane); absent with the session. */
   keyboard: ComposerKeyboard | undefined
   /** Resolve one keyboard submission gesture against the current running state and persisted preference. */
   resolveSubmitMode: (
@@ -380,7 +380,8 @@ export interface ComposerBarInjected {
   hooks: {
     /** Latest surfaced notice (null after none; seq keys re-render of repeats). */
     notices: ObservableSnapshot<InputNotice | null>
-    /** Hot plain-text reference lexicon for the decoration scan (decision 21). */
+    /** Hot plain-text reference lexicon for the decoration scan (plain-text-reference decision;
+     *  see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md). */
     lexicon: ObservableSnapshot<ReadonlyMap<'/' | '@', readonly string[]>>
     /** Source name opened by the programmatic menu launcher, or null. */
     menuLauncher: ObservableSnapshot<string | null>
diff --git a/packages/client/ui-conversation/src/client/input/contract.ts b/packages/client/ui-conversation/src/client/input/contract.ts
index 6af78bdb72..ebc63b28e6 100644
--- a/packages/client/ui-conversation/src/client/input/contract.ts
+++ b/packages/client/ui-conversation/src/client/input/contract.ts
@@ -1,5 +1,5 @@
 /**
- * Frozen input-machine contract (design §9.1, eng. plan §3.9-3.12). Types
+ * Frozen input-machine contract. Types
  * only. Three-tier visibility: business packages see InputState via the
  * InputZone currency; the scoped input events carry the mutation verbs; the
  * conversation wiring layer alone sees the full SessionInput. InputMachine
@@ -56,7 +56,7 @@ export interface InputService {
 
 /**
  * The public input action face provided to every session-scope slot
- * component (decision 20): two stable-identity void callbacks, mirroring the
+ * component: two stable-identity void callbacks, mirroring the
  * useStore+actions convention. Command-style handles (track/arbitrate/space/
  * undo/paste/…) stay InputBar-private and never ride this face.
  */
@@ -75,7 +75,7 @@ export interface InputNotice {
 }
 
 /**
- * The InputBar-exclusive keyboard/DOM command face (decision 20): synchronous
+ * The InputBar-exclusive keyboard/DOM command face: synchronous
  * returns and event-handler semantics that must not enter the public provide
  * channel. Handed to the composer-bar entry through its own inject —
  * package-internal, never across a plugin boundary. The session shell
@@ -128,7 +128,7 @@ export interface EditRange extends EditSelection {
 
 /**
  * One reference chip occurrence, backing exactly one U+FFFC placeholder in
- * the draft (design §9.1 底层表示). Identity is occurrenceId — same-named
+ * the draft. Identity is occurrenceId — same-named
  * references stay independently addressable. label/clipboardText are the
  * owner's insert-time projections, cached so the chip survives owner loss
  * (invalid flips instead of dropping the occurrence).
@@ -157,7 +157,7 @@ export interface PasteComponent extends EditSelection {
 
 /**
  * Live paste-match attempt published while async matching may still upgrade
- * pasted tokens (design §9.1 剪贴板 round-trip). Any non-paste transaction,
+ * pasted tokens (the clipboard round-trip). Any non-paste transaction,
  * submit start, invalidate-paste, or release ends it; a paste-upgrade keeps
  * it current (later tokens re-CAS against the advanced draftRev).
  */
diff --git a/packages/client/ui-conversation/src/client/input/decorations.ts b/packages/client/ui-conversation/src/client/input/decorations.ts
index 25ebab9e32..bd3dd09040 100644
--- a/packages/client/ui-conversation/src/client/input/decorations.ts
+++ b/packages/client/ui-conversation/src/client/input/decorations.ts
@@ -1,5 +1,5 @@
 /**
- * Draft decoration pure core (design §9.1: chips render from the occurrence
+ * Draft decoration pure core (chips render from the occurrence
  * table at placeholder offsets; the claim token renders as a mirror-layer
  * highlight, the claim hint as ghost text). Zero React — the skeleton renders
  * the instructions; tests drive this directly.
@@ -24,7 +24,9 @@ export interface ChipRender {
 }
 
 /**
- * One plain-text reference range (decision 21): a `/name` or `@name` token
+ * One plain-text reference range (the plain-text-reference decision;
+ * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
+ * a `/name` or `@name` token
  * whose name is on the trigger's lexicon. Pure derivation — editing the text
  * out of match shape simply drops the range next scan.
  */
@@ -50,8 +52,8 @@ export interface DraftDecorations {
 const TEXT_REF_RE = /(^|\s)([/@])([\w-]+)/g
 
 /**
- * Scan the draft for plain-text reference tokens against the hot lexicons
- * (decision 21). Word-boundary discipline: the trigger must sit at the draft
+ * Scan the draft for plain-text reference tokens against the hot lexicons.
+ * Word-boundary discipline: the trigger must sit at the draft
  * start or after whitespace ('x/name' never matches); the name must be an
  * exact lexicon member.
  * @param draft - draft text.
@@ -82,7 +84,7 @@ const EMPTY_LEXICON: ReadonlyMap<'/' | '@', readonly string[]> = new Map()
 /**
  * Derive the mirror-layer decorations from the input state.
  * @param state - published input state.
- * @param lexicon - optional per-trigger reference lexicons (decision 21 scan).
+ * @param lexicon - optional per-trigger reference lexicons (plain-text-reference scan).
  * @returns token range, chip instructions, text-ref ranges, and the ghost hint.
  */
 export function deriveDecorations(
diff --git a/packages/client/ui-conversation/src/client/input/facade.ts b/packages/client/ui-conversation/src/client/input/facade.ts
index 3c6d1fd0fb..cf07101e56 100644
--- a/packages/client/ui-conversation/src/client/input/facade.ts
+++ b/packages/client/ui-conversation/src/client/input/facade.ts
@@ -66,7 +66,7 @@ export class SessionInputShell implements SessionInput {
   readonly state: SnapshotStore<InputState>
   /** Latest surfaced notice (null after clear); the wiring renders it beside the error strip. */
   readonly notices: SnapshotStore<InputNotice | null> = createSnapshotStore<InputNotice | null>(null)
-  /** The public provide-channel action face (one stable identity per session — decision 20). */
+  /** The public provide-channel action face (one stable identity per session). */
   readonly actions: InputActions = {
     setDraft: (text) => { this.setDraft(text) },
     submit: () => { this.submit('queue') },
@@ -198,7 +198,9 @@ export class SessionInputShell implements SessionInput {
 
   /**
    * Hot plain-text reference lexicon source for the decoration scan
-   * (decision 21): delegates to the controller's aggregated store. Stable
+   * (the plain-text-reference decision;
+   * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
+   * delegates to the controller's aggregated store. Stable
    * identity per shell; without a pipeline the snapshot is the empty Map and
    * subscribers never fire.
    */
@@ -253,7 +255,8 @@ export class SessionInputShell implements SessionInput {
 
   /**
    * Insert plain reference text over the pick-time span (scoped insert-text
-   * event listener body, decision 21). Same CAS-then-splice shape as the
+   * event listener body; plain-text-reference decision, web-input-machine
+   * note). Same CAS-then-splice shape as the
    * consume-token span branch: the machine sees an ordinary draft-changed
    * transaction (one undo step), no occurrence is minted — the chip look is
    * a scan-derived decoration, never state.
@@ -339,7 +342,7 @@ export class SessionInputShell implements SessionInput {
   }
 
   /**
-   * Prompt serialization before the sink (design §3.12): expand each
+   * Prompt serialization before the sink: expand each
    * placeholder to its owner's model form via the session controller's
    * codec routing. Owner missing / serialize failure / disposal blocks the
    * send — notice + draft and chips retained, never a silent downgrade to
diff --git a/packages/client/ui-conversation/src/client/input/hub.ts b/packages/client/ui-conversation/src/client/input/hub.ts
index 560999aa21..4f6d62d662 100644
--- a/packages/client/ui-conversation/src/client/input/hub.ts
+++ b/packages/client/ui-conversation/src/client/input/hub.ts
@@ -1,7 +1,7 @@
 /**
  * InputHub: the InputService implementation (`ctx.conversation.input`) — one
  * SessionInputShell per session, created inside the sessions provide
- * materialization (decision 19: the 'input' standard-kit entry IS the
+ * materialization (the 'input' standard-kit entry IS the
  * creation trigger) and torn down by the scope disposer (instance-and-scope
  * share one lifecycle). The hub registers the three scoped input-mutation
  * listeners on each session's actx (the sole consumer side of the ui-slash
@@ -61,7 +61,7 @@ export class InputHub implements InputService {
     })
     this.shells.set(id, shell)
     // The one teardown axis: listeners, shell, and map entries all ride the
-    // scope fiber (decision 12 — nothing here outlives the scope).
+    // scope fiber (nothing here outlives the scope).
     actx.effect(() => {
       const offs = [
         actx.on('slash/input-begin-command', req =>
@@ -97,7 +97,7 @@ export class InputHub implements InputService {
   }
 
   /**
-   * The InputBar-exclusive keyboard command face (decision 20): the shell
+   * The InputBar-exclusive keyboard command face: the shell
    * satisfies it structurally; package-internal — handed through the
    * composer-bar entry's inject, never across a plugin boundary.
    * @param id - session id.
diff --git a/packages/client/ui-conversation/src/client/input/machine.ts b/packages/client/ui-conversation/src/client/input/machine.ts
index ec62eb63b4..68147adc38 100644
--- a/packages/client/ui-conversation/src/client/input/machine.ts
+++ b/packages/client/ui-conversation/src/client/input/machine.ts
@@ -1,6 +1,6 @@
 /**
- * InputMachine: the pure per-session input state machine (design §9.1, eng.
- * plan §3.9-3.12). Events in, effects out; zero React / DOM / cordis / ambient
+ * InputMachine: the pure per-session input state machine.
+ * Events in, effects out; zero React / DOM / cordis / ambient
  * clock. Package-private — the SessionInput shell is the only caller and the
  * sole executor of the returned effects.
  *
@@ -23,10 +23,10 @@ import type {
 /** The object-replacement character backing every chip occurrence in the draft. */
 export const PLACEHOLDER = ''
 
-/** The machine never writes the queue; the wiring layer overlays the T9 store projection. */
+/** The machine never writes the queue; the wiring layer overlays the queue store's projection. */
 const EMPTY_QUEUE: InputState['queue'] = []
 
-/** Undo ring depth (design §9.1: bounded self-managed transaction log). */
+/** Undo ring depth (bounded self-managed transaction log). */
 const LOG_LIMIT = 100
 
 /** Exhaustiveness backstop for the closed InputEvent / guard unions. */
@@ -68,7 +68,7 @@ function diffEdit(prev: string, next: string): EditRange {
 
 /**
  * Expand the draft's placeholders into their occurrences' clipboard text
- * (decision 16: the persistence mirror and clipboard both write this
+ * (the persistence mirror and clipboard both write this
  * projection — U+FFFC never leaves the machine). Table order is offset
  * order, so one linear walk pairs placeholders with entries.
  * @param state - published input state.
@@ -194,7 +194,7 @@ export class InputMachine {
   /**
    * Reconcile the occurrence table with one edit (old-draft coordinates):
    * entries past the range shift by the length delta; entries whose
-   * placeholder sits inside the replaced range go away whole (design §9.1: a
+   * placeholder sits inside the replaced range go away whole (a
    * deletion/replacement intersecting a placeholder acts on the whole chip).
    */
   private reconcile(range: EditRange): void {
@@ -338,7 +338,7 @@ export class InputMachine {
   /**
    * Owner-resolution style bits: exactly the listed occurrences render
    * invalid. Not a transaction — the draft, revision, and undo log are
-   * untouched (design §9.1: invalidation never deletes or rewrites chips).
+   * untouched (invalidation never deletes or rewrites chips).
    */
   private onSetInvalid(invalidIds: readonly number[]): InputEffect[] {
     const ids = new Set(invalidIds)
diff --git a/packages/client/ui-conversation/src/client/queue/store.ts b/packages/client/ui-conversation/src/client/queue/store.ts
index 35364383c6..ca94348b88 100644
--- a/packages/client/ui-conversation/src/client/queue/store.ts
+++ b/packages/client/ui-conversation/src/client/queue/store.ts
@@ -10,7 +10,7 @@ import type { QueuedMessage } from '../input/contract.ts'
 
 /**
  * Project a session's transient inbox rows as a bare observable (subscribe/getSnapshot).
- * The wiring layer (T5) overlays this onto InputState.queue; the runtime
+ * The wiring layer overlays this onto InputState.queue; the runtime
  * QueuedMessage and the input-contract QueuedMessage are structurally
  * identical.
  * @param session - the resident session face.
diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts
index be088d61ef..f9190da3e4 100644
--- a/packages/client/ui-conversation/src/client/service.ts
+++ b/packages/client/ui-conversation/src/client/service.ts
@@ -57,7 +57,7 @@ export interface IConversation {
 
 /** Scope-addressed conversation service (root singleton, provided as `conversation`). */
 export class ConversationService extends Service implements IConversation {
-  /** The per-session input machine registry (InputService face, design §5.2). */
+  /** The per-session input machine registry (InputService face). */
   readonly input: InputService
   /** The per-session composer-block registry. */
   readonly blocks: ComposerBlocks
diff --git a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
index 98e98f0f01..e700b112b4 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
@@ -10,8 +10,7 @@
 // buttons must be reachable no matter how long the command is.
 // One-shot: the buttons disable
 // after a click and the panel leaves (the InputBar returns) on the broadcast
-// resolved frame. The draft's "Always allow this type" is deferred with
-// grant storage.
+// resolved frame.
 
 import { useMemo, useState } from 'react'
 import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
diff --git a/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx
index 1f0bedded7..b6b62468d1 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx
@@ -1,8 +1,8 @@
 /** Composer context-occupancy meter: a ring beside the send button fed by the
  * `contextPressure` projection, with a click-open panel of the heuristic
  * `contextBreakdown` composition (system prompt, tools, conversation).
- * Renders nothing until a provider reports both pressure and a route capacity
- * (same gate as the stats row used). */
+ * Renders nothing until a provider reports both pressure and a route
+ * capacity. */
 
 import { useEffect, useRef, useState } from 'react'
 import type { UseProjection } from '@deepseek-ai/dsh-client-runtime/client'
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
index 8440dacd94..f9c2eb0968 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
@@ -81,7 +81,6 @@ export function ConversationRoot({
   const zone: InputZone | undefined =
     session === undefined || inputState === undefined ? undefined : { session, input: inputState }
 
-  // Flow optimization — worth a close PR review for code/boundary issues.
   // The chip is a selector; label resolution walks the flow top-down:
   //   1. a just-picked workspace (pending) → its title;
   //   2. cold start, no session yet → placeholder ("Choose workspace");
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index 1caefd2ecf..8d11e3c5ea 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -1,7 +1,6 @@
-// DetailsPanel, P-I minimal form: close button + the selected call's args and
+// DetailsPanel: close button + the selected call's args and
 // result — args as JSON, the result raw except for a terminal-card call, whose
-// Output section is the command's terminal card. The three-段 Switch /
-// Prev-Next stepping / See-in-trajectory are deferred (ledger). Reads the
+// Output section is the command's terminal card. Reads the
 // selection from the shared chat
 // store (conversation writes, this panel reads — the cross-registration
 // share the store seat exists for) and derives the call material from the
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index 3bbba68dd8..fdbf28c74b 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -395,7 +395,7 @@
   cursor: pointer;
 }
 
-/* Plain-text reference highlight (decision 21): a pure range mark over the
+/* Plain-text reference highlight: a pure range mark over the
    draft's own glyphs — advance untouched, so the two layers cannot drift.
    Chip family colors; clone keeps rounded ends on soft-wrap fragments. */
 .textRef {
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 78db735f61..0c097b6114 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -1,5 +1,5 @@
-/** The default composer body: the 'conversation.composer.bar' slot entry
- * (decision 20). Machine state arrives through the standard provide channel
+/** The default composer body: the 'conversation.composer.bar' slot entry.
+ * Machine state arrives through the standard provide channel
  * (useInput + inputActions); the keyboard/DOM command face and stop arrive
  * through this entry's own inject, whose hooks compartment binds
  * useNotices/useLexicon; layout-phase inputs (variant, placeholder,
@@ -385,7 +385,7 @@ export function InputBar({
   const backdrop: ReactNode[] = []
   {
     // Segment boundaries: the token range end, every chip offset, and every
-    // text-ref range (decision 21) — merged in draft order (the sources never
+    // text-ref range — merged in draft order (the sources never
     // overlap: chips sit on placeholders, text-refs on plain tokens, the
     // claim token only leads).
     let cursor = 0
@@ -430,7 +430,7 @@ export function InputBar({
         )
         cursor = chip.offset + 1 // the placeholder char the chip stands for
       } else {
-        // Plain-range highlight (decision 21): the glyphs stay the
+        // Plain-range highlight: the glyphs stay the
         // textarea's (advance untouched); the mark paints the chip look.
         backdrop.push(
           <mark key={`ref-${b.ref.start}`} className={css.textRef} data-decoration="text-ref">
@@ -529,7 +529,6 @@ export function InputBar({
             {rightItems}
             {renderSlot('conversation.input.model', { locked: modelSeatLocked })}
             <ContextMeter useProjection={useProjection} t={t} />
-            {/* {machineBusy && <span className={css.pending} data-input-pending aria-label="处理中" />} */}
             {interruptible && (
               <Tooltip label={t('input.stop')} side="top" delayMs={500}>
                 <button
diff --git a/packages/client/ui-conversation/tests/input-bar.spec.tsx b/packages/client/ui-conversation/tests/input-bar.spec.tsx
index e9076fa994..aaed8153da 100644
--- a/packages/client/ui-conversation/tests/input-bar.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.spec.tsx
@@ -226,10 +226,10 @@ describe('Enter semantics', () => {
   })
 })
 
-describe('running and lock semantics (queue cut 1)', () => {
+describe('running and lock semantics', () => {
   it('running keeps the input free (typing + Enter queue) while the primary turns stop', () => {
     const { textarea, button, stop, sink } = bench({ running: true, draft: '排队消息' })
-    expect(textarea.disabled).toBe(false) // running no longer locks
+    expect(textarea.disabled).toBe(false)
     fireEvent.change(textarea, { target: { value: '排队消息2' } })
     fireEvent.keyDown(textarea, { key: 'Enter' })
     expect(sink).toHaveBeenCalledWith('排队消息2', 'queue')
@@ -429,8 +429,8 @@ describe('running and lock semantics (queue cut 1)', () => {
     // scrollport element holds both layers.
     expect(scroll.contains(textarea)).toBe(true)
     expect(scroll.contains(backdrop)).toBe(true)
-    // The glyph layer carries the draft and nothing else: with one scrollport
-    // it no longer pads its own height to match a second box's scroll extent.
+    // The glyph layer carries the draft and nothing else — no height padding
+    // to a second box's scroll extent.
     expect(backdrop.textContent).toBe('line\n'.repeat(40))
   })
 
@@ -659,7 +659,7 @@ describe('decorations', () => {
     expect(shell.snapshot.draft).toBe('参考 \uFFFC 内容')
   })
 
-  it('a lexicon-matched plain token renders the text-ref mark (decision 21)', () => {
+  it('a lexicon-matched plain token renders the text-ref mark', () => {
     const lexicon = new Map<'/' | '@', readonly string[]>([['/', ['fixture-demo']]])
     const { view, shell } = bench({ lexicon })
     act(() => { shell.setDraft('use /fixture-demo now') })
@@ -671,7 +671,7 @@ describe('decorations', () => {
   })
 })
 
-describe('insertText (decision 21 scoped event body)', () => {
+describe('insertText (scoped event body)', () => {
   it('splices plain text over the span and reports success as true', () => {
     const { shell } = bench({ draft: '/fix' })
     const ok = shell.insertText('/fixture-demo ', { start: 0, end: 4, draftRev: shell.snapshot.draftRev })
@@ -721,7 +721,7 @@ describe('strips and variants', () => {
 })
 
 describe('command launcher chrome and control seats', () => {
-  it('renders the command launcher; the Access chip is absent without the permissions projection; plan/model seats render EMPTY without entries (B ruling)', () => {
+  it('renders the command launcher; the Access chip is absent without the permissions projection; plan/model seats render EMPTY without entries', () => {
     const { view, slotCalls } = bench()
     expect(view.getByLabelText('命令')).toBeTruthy()
     // Capability absent (no projection value): the chip renders nothing.
diff --git a/packages/client/ui-conversation/tests/input-machine.spec.ts b/packages/client/ui-conversation/tests/input-machine.spec.ts
index 89737d7106..da0c40e549 100644
--- a/packages/client/ui-conversation/tests/input-machine.spec.ts
+++ b/packages/client/ui-conversation/tests/input-machine.spec.ts
@@ -1,6 +1,6 @@
 /**
- * InputMachine unit account (design §9.1, eng. plan §3.9-3.12): the submit
- * plane carried over from the InputCore era (adjudication, span CAS, drift
+ * InputMachine unit account: the submit
+ * plane (adjudication, span CAS, drift
  * guard, anti-backwash), plus the occurrence table (shift / whole-chip
  * deletion / same-name independence), the self-managed undo log (typing
  * coalescing, paste two-stage undo, redo chain), consume-token guards, the
@@ -625,7 +625,7 @@ describe('input-machine: projectClipboard', () => {
   })
 })
 
-describe('decorations: scanTextRefs (decision 21)', () => {
+describe('decorations: scanTextRefs', () => {
   const LEX: ReadonlyMap<'/' | '@', readonly string[]> = new Map([
     ['/', ['commit-helper', 'fixture-demo']],
     ['@', ['worker-1']],
diff --git a/packages/client/ui-conversation/tests/input-matrix.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
index 65fa5705ca..1efd959493 100644
--- a/packages/client/ui-conversation/tests/input-matrix.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 /**
- * Impact-matrix projection tests (design §5.2 影响矩阵, row by row): what each
+ * Impact-matrix projection tests (row by row): what each
  * phase projects onto the InputBar — enter routing, visuals (token color /
  * hint / pending), edit freedom, and the published currency's claim seat.
  * React over jsdom per the client testing discipline; the machine is real.
diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
index 94d348d17a..9f6b679b60 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 /**
- * Scenario-chain integration (design §8 A/C/D/H/I): the real per-session
+ * Scenario-chain integration (scenarios A/C/D/H/I): the real per-session
  * SlashController pipeline over a real session scope (SessionsService over
  * a listed host session) + a command source implementing the decision
  * table's relevant cells + the real SessionInput machine (scoped-event
diff --git a/packages/client/ui-conversation/tests/todo-panel.spec.tsx b/packages/client/ui-conversation/tests/todo-panel.spec.tsx
index 445d8139e6..fafe6e6dc4 100644
--- a/packages/client/ui-conversation/tests/todo-panel.spec.tsx
+++ b/packages/client/ui-conversation/tests/todo-panel.spec.tsx
@@ -86,8 +86,8 @@ describe('TodoPanel', () => {
   it('marks every parallel active item, and counts them all in the header', () => {
     render(<TodoPanel todos={PARALLEL} t={t} />)
     fireEvent.click(screen.getByRole('button', { expanded: false }))
-    // The old unconditional cap made this list unreachable: three items carry
-    // the in-progress glyph at once, and the header counts all three.
+    // An unconditional in-progress cap would make this list unreachable: three
+    // items carry the in-progress glyph at once, and the header counts all three.
     const statuses = screen.getAllByRole('listitem').map(li => li.getAttribute('data-status'))
     expect(statuses.filter(s => s === 'in_progress')).toHaveLength(3)
     expect(screen.getByText('跑后台构建')).toBeTruthy()
diff --git a/packages/client/ui-layout/src/client/AppFrame.tsx b/packages/client/ui-layout/src/client/AppFrame.tsx
index 967066c056..09386f5d47 100644
--- a/packages/client/ui-layout/src/client/AppFrame.tsx
+++ b/packages/client/ui-layout/src/client/AppFrame.tsx
@@ -183,8 +183,8 @@ export function AppFrame({
       </div>
       <>
         {/* Both column occupants stay at fixed tree positions from first
-            paint — no loading gate (user ruling: the bare status line looked
-            worse than the shell's own pending rendering). The conversation
+            paint — no loading gate: a bare status line reads worse than
+            the shell's own pending rendering. The conversation
             is session-maybe; the strict details entry naturally renders
             empty while no session is current. */}
         <CenterColumn>{renderSlot('conversation', {})}</CenterColumn>
diff --git a/packages/client/ui-layout/tests/app-frame.spec.tsx b/packages/client/ui-layout/tests/app-frame.spec.tsx
index a8a988574b..65de5a640e 100644
--- a/packages/client/ui-layout/tests/app-frame.spec.tsx
+++ b/packages/client/ui-layout/tests/app-frame.spec.tsx
@@ -164,7 +164,7 @@ describe('AppFrame', () => {
   })
 
   it('renders both column occupants before baselines settle (no loading gate)', () => {
-    // User ruling: the bare loading status looked worse than the shell's own
+    // No loading gate: a bare loading status reads worse than the shell's own
     // pending rendering — both occupants mount from first paint.
     baselinesReady.current = false
     const { slotCalls } = mountFrame()
diff --git a/packages/client/ui-models/README.i18n.yaml b/packages/client/ui-models/README.i18n.yaml
index ce82152632..ec20685def 100644
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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/client/ui-models/README.md
-README.md: 66f23d3f77adae23fcebd3adbb6c5c47ce16ae2f
-README.zh.md: d0a5ad465e713680757a3e3734fc97dc31280a2e
+README.md: 9841ced87ae345c685c59e96a7b9088d474181f5
+README.zh.md: bb1445fbc8093d356ce838948b8338fa04919063
diff --git a/packages/client/ui-models/README.md b/packages/client/ui-models/README.md
index 66f23d3f77..9841ced87a 100644
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Models settings plugin: the provider configuration page and official-DeepSeek conditional onboarding step. It joins three wire domains into one shared snapshot — `llm.providers` (the configurable-provider directory with each route's live/dormant state), `settings.describe` (serialized schemas, layered redacted values, secret slots), and `credentials.describe` (value-free configured/source/writable badges) — and renders provider rows with one editor card at a time, without presenting route liveness as provider status.
 
-Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint) and each adapter's model catalog. Reasoning effort is deliberately NOT among them: it is a per-model capability and the models under one provider disagree about which levels they accept, so a provider-scoped control could only be set to a value some of them reject — which took the whole provider out of the model picker. The composer's model picker offers each model its own levels, and a switch there records provider, model, and effort together as the default for the next session. The profile field stays in `settings.yaml` for a deployment that knows its route. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
+Rows are the *configured* providers (their profile resolves in the owning namespace); a whole-section provider whose key is not configured anywhere (the first-run DeepSeek posture) renders as its open setup card instead of a row, and the add flow is a card carrying the dormant-directory provider select — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists. The pi-ai card additionally edits that route's **model list** and can ask the provider what it serves. A row labels API-key state with a green solid dot only when a referenced credential is confirmed configured, and with a red solid dot only when a named reference is confirmed missing; reference-free provider-native authentication and unavailable credential enrichment remain unmarked. The editor is a hand-written card per adapter family: the primary field is a single **API key** input — the page never asks for an environment-variable name; a typed key stores **write-only** through `credentials.set` under the profile's reference, deriving `<ROUTE>_API_KEY` when the profile has none, and the pi-ai profile records that derivation as `apiKeyEnv`, so `settings.yaml` never carries a key value. Leaving a new pi-ai provider's key blank saves a reference-free profile and therefore preserves provider-native authentication such as the Bedrock credential chain or Vertex ADC. A successful Apply emits a local accessible status message without echoing secret material. The collapsed 自定义设置 fold carries the curated extras — `baseURL` for both families (the deepseek placeholder shows the public endpoint) and each adapter's model catalog. Reasoning effort is deliberately NOT among them: it is a per-model capability and the models under one provider disagree about which levels they accept, so a provider-scoped control could only be set to a value some of them reject — which would hide even the models that support the level. The composer's model picker offers each model its own levels, and a switch there records provider, model, and effort together as the default for the next session. The profile field stays in `settings.yaml` for a deployment that knows its route. Each DeepSeek row edits `id`, optional display `name`, and optional `contextWindow`; existing fields outside that curated set survive edits, while every other profile field stays owned by `settings.yaml`. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its localized confirmation dialog names the provider in the title, description, and final action. A row is tagged **Custom** when the directory entry says the owning adapter ships nothing under that key. The tag follows that answer alone: having a stored profile does not make a route custom — narrowing a shipped provider's models stores one too — and an adapter that reports nothing leaves its rows untagged rather than being read as shipped.
 
 The DeepSeek step projects `deepseek-official` readiness from that same joined snapshot after earlier onboarding pages complete. It recognizes the official adapter through its `llm-deepseek` configurable-provider declaration, so an undeclared live route with the same provider id is not treated as repairable configuration. A configured credential reference completes the step without rendering, including a read-only launch-environment credential. Only a mounted, active adapter with a missing writable reference shows the page that opens Settings on Models, whose existing setup card exclusively owns key input and `credentials.set`; the step never holds a secret. An absent adapter, inactive route, failed join, read-only deployment, or unusable settings or credential capability completes the step without rendering so onboarding cannot block the product; Models remains the diagnostic surface.
 
diff --git a/packages/client/ui-models/README.zh.md b/packages/client/ui-models/README.zh.md
index d0a5ad465e..bb1445fbc8 100644
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -4,7 +4,7 @@
 
 模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：`llm.providers`（可配置提供方目录，含每条路由的存活／休眠状态）、`settings.describe`（序列化 schema、分层脱敏值、secret 槽位）与 `credentials.describe`（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。
 
-行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可查询提供方所提供的模型。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），以及各适配器自己的模型目录。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会让整个提供方从模型选择器里消失。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
+行是*已配置*的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。pi-ai 卡片还会编辑该路由的**模型列表**，并可查询提供方所提供的模型。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。无引用的提供方原生认证以及无法取得凭据补充信息时都不显示状态点。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名；键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，因此能保留提供方原生认证，例如 Bedrock 凭据链或 Vertex ADC。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 `baseURL`（deepseek 的占位符显示公共端点），以及各适配器自己的模型目录。推理等级刻意**不在**其中：它是按模型的能力，而同一提供方下各模型接受的档位并不一致，因此提供方级的控件只可能被设成其中一些模型会拒绝的值——那会连支持该档位的模型也一并隐藏。输入框的模型选择器为每个模型提供它自己的档位，在那里切换会把提供方、模型、推理等级一并记为下一个会话的默认值。profile 字段仍留在 `settings.yaml`，供清楚自己路由的部署使用。每条 DeepSeek 模型行可编辑 `id`、可选的显示名称 `name` 与可选的 `contextWindow`；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 `settings.yaml` 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），其本地化确认对话框会在标题、说明和最终操作中点名该提供方。当目录条目表明拥有该路由的适配器在这个键下什么都没有时，该行会带上 **自定义** 标签。标签只跟随这个答案：存了 profile 并不使一条路由成为自定义——收窄一个内置提供方的模型同样会存下 profile——而什么都不回答的适配器，其路由保持无标签，不会被当成内置。
 
 前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 `deepseek-official` 的就绪状态。它通过 `llm-deepseek` 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。凭据引用已配置时，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。
 
@@ -16,7 +16,7 @@ pi-ai profile 的 `models` 列表就在卡片上编辑：一行一个模型，
 
 **获取可用模型**会针对表单**当前显示**的端点调用 `llm.discoverModels`，包括已修改但尚未保存的 API 地址和已键入但尚未存储的密钥，因此新增一个提供方是一趟走完，而不是「先保存再回来」。回复会打开一个选择框而不是直接写入：已配置过的候选默认不勾选，因此采纳一次选择绝不会覆盖用户已更正的容量。无法被询问的提供方只是绕路而非死路——适配器自己的消息会显示在各行旁边，而这些行仍可手工编辑。
 
-**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个标识唯一的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上抛出原始正则表达式错误。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方其实已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。
+**添加自定义提供方**用来声明 pi-ai 未提供的路由。它是独立的一张卡片而非在编辑器上加字段，因为路由 id 正是在这里被*选定*的，而在选定之前 settings 地址并不存在：一次 `settings.mutate` 在 `providers.<route>` 上设置整个 profile，密钥则经 `credentials.set` 单独传递，使用与既有提供方相同的 `<ROUTE>_API_KEY` 派生。手工声明的路由无法默认的东西会门控创建按钮——唯一的 **Provider ID**、端点、协议，以及至少一个标识唯一的模型——因此失败会在用户仍看着该字段时点名它。该 id 必须以小写字母开头，因为它同时是派生凭据引用的词干，而引用是 POSIX shell 标识符：数字开头的 id 否则会通过这张卡片的每一项检查，然后在凭据 seam 上抛出原始正则表达式错误。容量不参与门控：端点只按 id 描述的模型（这正是多数列表返回的形态）由适配器的回退值定尺寸。协议选项读自该 namespace 自己的 schema，而非某个协议字段或常量，因此它们不会与适配器实际接受的集合发生漂移。只有键入了密钥，这张卡片才记录约定的 `apiKeyEnv` 引用，与编辑器同一条规则，因此一条为提供方原生认证声明的路由不会一出生就指向一个永远不会被设置的引用。当 profile 写入成功而密钥写入失败时，提供方已经存在：卡片会把描述它的字段定住，只重试凭据——再跑一次 profile 写入会带着刚被自己这次写入取代的 revision，宿主将以 `settings-conflict` 应答，密钥就再也无法从这里存下——并且即使用户随后取消，也照实报告提供方已创建。
 
 ## 模型体验
 
diff --git a/packages/client/ui-models/src/client/CustomProviderCard.tsx b/packages/client/ui-models/src/client/CustomProviderCard.tsx
index f055b325a5..b8b4459c77 100644
--- a/packages/client/ui-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-models/src/client/CustomProviderCard.tsx
@@ -118,7 +118,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
     // next unmet gate — which is satisfied, and reads as a second, false fault.
     || keyFailure !== undefined
     // Same for the route id, and it must be tested rather than assumed: the
-    // fallback arm below reads "no models yet", so an unmet route gate used to
+    // fallback arm below reads "no models yet", so an unmet route gate would
     // fall through to it and contradict the filled-in list right above.
     || route.length === 0 || routeInvalid || routeTaken
     ? undefined
diff --git a/packages/client/ui-models/src/client/ModelsSection.module.css b/packages/client/ui-models/src/client/ModelsSection.module.css
index 94f08d523a..8facc3a110 100644
--- a/packages/client/ui-models/src/client/ModelsSection.module.css
+++ b/packages/client/ui-models/src/client/ModelsSection.module.css
@@ -435,12 +435,12 @@
   line-height: 18px;
 }
 
-/* Model list, shared with the pi-ai provider form (PR #1368): one bordered
+/* Model list, shared with the pi-ai provider form: one bordered
    entry per model, id and display name on the row, capacities behind the
-   row's own disclosure. The token names are this file's, not that branch's —
+   row's own disclosure. The rules use this stylesheet's token vocabulary —
    `--dsw-alias-border-subtle`, `--dsw-alias-text-tertiary`, and
-   `--dsw-alias-text-primary` are undefined here and resolve to their
-   light-mode literals, which is the defect this section was just moved off. */
+   `--dsw-alias-text-primary` are undefined here and would resolve to their
+   light-mode literals. */
 .modelList {
   display: flex;
   flex-direction: column;
diff --git a/packages/client/ui-models/tests/components.spec.tsx b/packages/client/ui-models/tests/components.spec.tsx
index da4c8972ae..09167b55cb 100644
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -655,7 +655,7 @@ describe('ModelsSection', () => {
     expect((ids[0] as HTMLInputElement).value).toBe('deepseek-v4-flash')
 
     // An id that is only whitespace is as absent as an empty one, and a padded
-    // id no longer slips past the duplicate check against its own twin.
+    // id is a duplicate of its trimmed twin.
     expect(validateDeepSeekModels([{ id: '   ' }])).toEqual({ index: 0, key: 'modelIdRequired' })
     expect(validateDeepSeekModels([{ id: 'model' }, { id: 'model ' }]))
       .toEqual({ index: 1, key: 'modelIdDuplicate' })
@@ -714,7 +714,7 @@ describe('ModelsSection', () => {
   })
 
   it('clears an inherited override with an unset op, never a whole-section replace', async () => {
-    // The old path rebuilt the whole user section to clear one inherited field.
+    // A whole-section replace would clobber sibling overrides to clear one field.
     const { replace, update, mutate } = await mountSection()
     fireEvent.click(screen.getByText(en.customized))
     const url = screen.getByLabelText<HTMLInputElement>(en.baseUrl)
diff --git a/packages/client/ui-models/tests/provider-form.spec.tsx b/packages/client/ui-models/tests/provider-form.spec.tsx
index 7e5ef5f36e..9ff96cdebc 100644
--- a/packages/client/ui-models/tests/provider-form.spec.tsx
+++ b/packages/client/ui-models/tests/provider-form.spec.tsx
@@ -706,11 +706,11 @@ describe('hand-declared providers', () => {
   })
 
   it('scopes each card to fields a provider can actually own', async () => {
-    // Reasoning effort used to sit here. It is a per-MODEL capability and the
+    // Reasoning effort is a per-MODEL capability and the
     // models under one provider disagree about it, so a provider-scoped
-    // control could only be set to a value some of them reject — which took
-    // the whole provider out of the picker. The composer's model picker owns
-    // the choice, and a switch there records provider+model+effort together.
+    // control could only be set to a value some of them reject — which would
+    // take the whole provider out of the picker. The composer's model picker
+    // owns the choice, and a switch there records provider+model+effort together.
     const fields = () => [...document.querySelectorAll('input,select')]
       .map(el => el.getAttribute('aria-label')).filter(Boolean)
 
@@ -804,8 +804,8 @@ describe('hand-declared providers', () => {
     const routeField = screen.getByLabelText(en.customRoute)
     fireEvent.change(routeField, { target: { value: 'https://acme.test/v1' } })
 
-    // A digit-leading id used to pass every check this card makes and then
-    // fail at the credential seam with a raw regular expression: the
+    // Without this check a digit-leading id passes the card and fails at the
+    // credential seam with a raw regular expression: the
     // reference derives as `123_API_KEY`, and a credential reference is a
     // POSIX shell identifier, which cannot start with a digit.
     fireEvent.change(routeField, { target: { value: '123' } })
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 5c8e7eaab6..06dfe45bd8 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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/client/ui-primitives/README.md
-README.md: 098a202a4ac9ee263ce1beaaee7a8624ebf26b80
-README.zh.md: def1907f81d06b5afdf19af5f19ba17a269ed3c1
+README.md: a9c802c1e43cf06aa0492b39d5052e882a72d9e6
+README.zh.md: 9e67488ccc1d70263bd0b91d167c4c251ee95926
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 098a202a4a..a9c802c1e4 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the OnboardingSurface first-run takeover (body-portaled mask + opaque stage that holds `#root` inert for exactly its own lifetime), the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock. Contract: api-contracts v3 §8.
+Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the OnboardingSurface first-run takeover (body-portaled mask + opaque stage that holds `#root` inert for exactly its own lifetime), the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock.
 
 ## Hover cards
 
@@ -46,5 +46,5 @@ None; this package neither assembles nor sends a provider request.
 - **Glyph-level icons are redrawn approximations** — the fish logo (and the sparkle held by ui-conversation) come from font glyphs whose vector geometry is not exportable from the local design data; hand-authored recreations stand in until an exact export path exists.
 - **Pill and Input have no design source** — both atoms are self-defined; the sidebar search field and view-tab strip that resemble them are consumer-owned compositions, not these atoms.
 - **No `Active` StateDot variant** — the supported states are done, warning, ongoing, and error.
-- **User-facing copy localizes through label props, defaulting to the original Chinese literals** — the atoms are zero-cordis and cannot reach `ctx.locale`, so `HoverCard` (`copyLabel`/`copiedLabel`), `TerminalBlock` (`labels`), `JsonTree` (`labels`), `CodeBlock` (`copyLabel`/`copiedLabel`), `MarkdownText` (`codeLabels`), `JsonBlock` (`truncatedLabel`), `ConnectionBanner` (`label`), and `Modal` (`closeLabel`) take their copy as optional props with the previous hardcoded strings as defaults. Localized plugins pass dictionary-driven labels from their own `t` seat; a consumer that passes nothing renders exactly the pre-localization output. `WebBlock` does not yet follow this pattern: its source-list and fetch truncation notes and its empty-search note stay inline Chinese, pending the same label-prop treatment.
+- **User-facing copy localizes through label props, defaulting to the original Chinese literals** — the atoms are zero-cordis and cannot reach `ctx.locale`, so `HoverCard` (`copyLabel`/`copiedLabel`), `TerminalBlock` (`labels`), `JsonTree` (`labels`), `CodeBlock` (`copyLabel`/`copiedLabel`), `MarkdownText` (`codeLabels`), `JsonBlock` (`truncatedLabel`), `ConnectionBanner` (`label`), and `Modal` (`closeLabel`) take their copy as optional props. Localized plugins pass dictionary-driven labels from their own `t` seat; a consumer that passes nothing gets those defaults. `WebBlock` does not yet follow this pattern: its source-list and fetch truncation notes and its empty-search note stay inline Chinese, pending the same label-prop treatment.
 - **`TerminalBlock` is not a terminal emulator** — it renders settled or still-running command output, not an interactive session: SGR color and attributes are honored, and so are the in-line cursor movements a progress line uses — carriage return, backspace, erase-in-line, tab stops and character width. Absolute cursor positioning, screen clearing, and alternate-screen sequences are stripped. Basic-16 magenta and cyan have no token equivalent and stay literal rgb.
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index def1907f81..9e67488ccc 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在且仅在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` 钩子（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。约定：api-contracts v3 §8。
+纯 React 原子组件（零 cordis）：StateDot、DisclosureRow、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在且仅在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` 钩子（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。
 
 ## 悬浮卡片
 
@@ -46,5 +46,5 @@
 - **字形级图标是重新绘制的近似版本**：鱼形标志（以及 ui-conversation 持有的闪光图标）来自字体字形，而本地设计数据无法导出其矢量几何；在获得精确导出路径前，使用手工重建版本代替。
 - **Pill 与 Input 没有设计来源**：两个原子组件均自行定义；与其相似的侧边栏搜索字段和视图标签条由消费方组合，不是这些原子组件。
 - **StateDot 没有 `Active` 变体**：支持的状态为 done、warning、ongoing 和 error。
-- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收，默认值即此前的硬编码字符串。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费者渲染与本地化之前逐字节一致。`WebBlock` 尚未跟进这一模式：它的来源列表截断提示与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
+- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费方得到的就是这些默认值。`WebBlock` 尚未跟进这一模式：它的来源列表截断提示与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
 - **`TerminalBlock` 不是终端模拟器**：它渲染已结束或仍在运行的命令输出，而不是交互式会话：SGR 颜色与属性会被遵循，进度行所用的行内光标移动同样被遵循——回车、退格、行内擦除、制表位与字符宽度。绝对光标定位、清屏与备用屏幕序列会被剥离。基础 16 色中的洋红与青色没有对应 token，保持字面 rgb。
diff --git a/packages/client/ui-primitives/src/TerminalBlock.tsx b/packages/client/ui-primitives/src/TerminalBlock.tsx
index 4cec564da6..e28c3fd657 100644
--- a/packages/client/ui-primitives/src/TerminalBlock.tsx
+++ b/packages/client/ui-primitives/src/TerminalBlock.tsx
@@ -221,8 +221,8 @@ export function TerminalBlock({
   // Read from the parsed lines the card actually renders, not from the raw text:
   // output that is only escapes or control bytes (a lone reset, an OSC title, an
   // erase) survives `text.trim()` yet parses to nothing visible. Judging it on
-  // the raw text drew an output box of blank rows plus a copy control for
-  // invisible bytes, and hid the placeholder that belongs there.
+  // the raw text would draw an output box of blank rows plus a copy control
+  // for invisible bytes, and hide the placeholder that belongs there.
   const empty = lines.every(line => line.every(span => span.text.trim() === ''))
   const { hidden, capped, headLines, tailLines } = headTailCap(lines.length, maxLines, expanded)
 
diff --git a/packages/client/ui-primitives/src/Tooltip.module.css b/packages/client/ui-primitives/src/Tooltip.module.css
index 56b93f5be1..c5f92c8482 100644
--- a/packages/client/ui-primitives/src/Tooltip.module.css
+++ b/packages/client/ui-primitives/src/Tooltip.module.css
@@ -1,6 +1,6 @@
 /* Visual spec mirrors deepsuite @deepseek/ui Tooltip.css (size m, no arrow),
-   except padding tightened 6/12 -> 3/7, type 14/22 -> 13/20, and radius
-   10 -> 8 by product ruling: tooltip-bg plate,
+   except padding tightened 6/12 -> 3/7, type 14/22 -> 13/20, radius
+   10 -> 8, a tooltip-bg plate,
    one text color across both themes (the plate stays dark in light and dark
    mode). Behavior (fixed positioning off the anchor rect) is local — the
    upstream Floating stack is intentionally not vendored. */
diff --git a/packages/client/ui-primitives/src/markdown/highlight.ts b/packages/client/ui-primitives/src/markdown/highlight.ts
index d0727c833a..d9a4d53ec2 100644
--- a/packages/client/ui-primitives/src/markdown/highlight.ts
+++ b/packages/client/ui-primitives/src/markdown/highlight.ts
@@ -84,8 +84,7 @@ const LAZY_GRAMMARS = new Map<string, () => Promise<LangModule>>([
  * the markdown-fence aliases `CodeBlock` uses and the file-extension hint ids
  * the read tool's `langFromPath` emits, so both callers resolve the same
  * grammars. The JS family maps to the TypeScript grammar (see {@link LANGS} for
- * the JSX/TSX approximation), unchanged from when this was the only
- * non-shell/JSON grammar. A value not in {@link LANGS} names a
+ * the JSX/TSX approximation). A value not in {@link LANGS} names a
  * {@link LAZY_GRAMMARS} entry loaded on first use.
  */
 const LANG_ALIASES = new Map<string, string>([
diff --git a/packages/client/ui-primitives/tests/ansi.spec.ts b/packages/client/ui-primitives/tests/ansi.spec.ts
index 008165f5ab..dbd520d626 100644
--- a/packages/client/ui-primitives/tests/ansi.spec.ts
+++ b/packages/client/ui-primitives/tests/ansi.spec.ts
@@ -359,10 +359,10 @@ describe('parseAnsiLines: line-end state and column widths', () => {
 
 describe('parseAnsiLines: bounded state and true widths', () => {
   it('emits one canonical sequence per boundary however the state was reached', () => {
-    // Colors that never fully reset used to accumulate raw sequence history per
-    // cell, so every boundary re-emitted the whole chain: 3200 such cells
-    // produced 25 MB and eventually a RangeError. The state is normalized now,
-    // so the emitted text stays linear in the number of cells.
+    // Colors that never fully reset would, under a raw per-cell sequence
+    // history, re-emit the whole chain at every boundary: 3200 such cells
+    // produce 25 MB and eventually a RangeError. Normalized state keeps
+    // the emitted text linear in the number of cells.
     let input = ''
     for (let index = 0; index < 2000; index += 1) input += `${ESC}[3${index % 6 + 1}mx`
     const emitted = parseAnsiLines(`${input}\rz`)[0] ?? []
diff --git a/packages/client/ui-primitives/tests/hover-card.spec.tsx b/packages/client/ui-primitives/tests/hover-card.spec.tsx
index d5b580045a..53d5d2bcf7 100644
--- a/packages/client/ui-primitives/tests/hover-card.spec.tsx
+++ b/packages/client/ui-primitives/tests/hover-card.spec.tsx
@@ -91,8 +91,8 @@ describe('HoverCard', () => {
 
   it('reaching the card inside the grace keeps it open without restarting the dwell', () => {
     // The portaled card is a React child of the wrapper, so the pointer
-    // arriving on it re-enters the wrapper — the gesture the 8px anchor gap
-    // used to make impossible.
+    // arriving on it re-enters the wrapper — the gesture an anchor gap
+    // would make impossible.
     const { wrapper } = mount()
     fireEvent.pointerEnter(wrapper)
     act(() => { vi.advanceTimersByTime(500) })
diff --git a/packages/client/ui-primitives/tests/icons.spec.tsx b/packages/client/ui-primitives/tests/icons.spec.tsx
index 678eb9754e..5c2fe88608 100644
--- a/packages/client/ui-primitives/tests/icons.spec.tsx
+++ b/packages/client/ui-primitives/tests/icons.spec.tsx
@@ -16,7 +16,7 @@ const icons = Object.fromEntries(
 const iconNames = Object.keys(icons)
 
 describe('ic_ds_ icon set', () => {
-  it('exports the full P-I set (46 deepsuite + 17 figma extracts + three product glyphs outside those sets)', () => {
+  it('exports the full icon set (46 deepsuite + 17 figma extracts + three product glyphs outside those sets)', () => {
     expect(iconNames.length).toBe(66)
   })
 
diff --git a/packages/client/ui-primitives/tsdown.config.ts b/packages/client/ui-primitives/tsdown.config.ts
index cbabf4f2a1..4e623511f1 100644
--- a/packages/client/ui-primitives/tsdown.config.ts
+++ b/packages/client/ui-primitives/tsdown.config.ts
@@ -2,7 +2,7 @@ import { clientOnly } from '../tsdown.client.ts'
 
 /**
  * ui-primitives is browser-only, but its lib bundle IS imported under plain
- * Node now that the web shell is a lib (dsh-client-web's lib chain reaches
+ * Node because the web shell is a lib (dsh-client-web's lib chain reaches
  * this package). CSS imports are therefore stubbed to empty modules instead
  * of externalized — the hashed class maps only matter in bundler contexts
  * (loader module table / vite source paths), which compile src directly and
diff --git a/packages/client/ui-settings/src/client/contract/slots.ts b/packages/client/ui-settings/src/client/contract/slots.ts
index 8516ce8860..aeaafe8232 100644
--- a/packages/client/ui-settings/src/client/contract/slots.ts
+++ b/packages/client/ui-settings/src/client/contract/slots.ts
@@ -62,7 +62,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * OnboardingSurface primitive (mask, opaque stage, `#root` inert) and
      * renders null while its private facts are still loading — the shell
      * paints no chrome of its own, so a mounted-but-deciding step shows and
-     * blocks nothing (the reload white-flash fix; a bare unwrapped step
+     * blocks nothing (prevents a white flash on reload: a bare unwrapped step
      * would render without mask or stage).
      */
     'settings.onboarding': { kind: 'list'; scope: 'root'; owner: SettingsOnboardingOwnerProps }
@@ -87,7 +87,7 @@ export interface SettingsHeaderOwnerProps {
  * arrives through their own inject faces and stores).
  */
 export interface SettingsSectionOwnerProps {
-  /** Marker field: section owner props are intentionally empty for now. */
+  /** Marker field: section owner props are intentionally empty. */
   children?: never
 }
 
diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
index 711f4171e4..a98d8ea26e 100644
--- a/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
+++ b/packages/client/ui-sidebar/src/client/SidebarRoot.module.css
@@ -96,7 +96,7 @@
 }
 
 /* Brand group (figma I133:7632): the full wordmark rides the text ink
-   (figma-flows ruling: main-screen instance is black; blue is brand
+   (figma flows: the main-screen instance is black; blue is brand
    emphasis only). A button only in behavior (New Session shortcut): the
    pointer cursor is the sole affordance — no hover chrome on the mark. */
 .brand {
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index b7c737a98f..c9d9e0b69c 100644
--- a/packages/client/ui-skill/README.i18n.yaml
+++ b/packages/client/ui-skill/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/client/ui-skill/README.md
-README.md: 44953fe36ad337d0dd70e4d8c0cc2372b8924c9b
-README.zh.md: 3a8ac86d13114bdbbb78c33d907aba7bb1a10fc2
+README.md: 677ac215d299fca695a6b27c564779ef1d3fd6ee
+README.zh.md: 8f1f69b26a932aaa300bdda1d4ec7b2fa749fe3c
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index 44953fe36a..677ac215d2 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Skill invocation source, browser half: registers the `/`-trigger `skill` source into `ctx.slash`. Ordinary-session candidates come from the `skill.list` RPC addressed by the per-call `ClientSessionContext` projection's `{sessionId}`, with the host resolving `cwd` from the session header. The host serves every user-invocable skill; a `modelInvocable: false` entry (a `disable-model-invocation` skill, whose only entry point is this path) wears the user-only marker as a description prefix in the active language. Catalog-addressed continuable children resolve no skill candidates locally because the existing skill RPC requires an attached session; viewing their persisted history must not activate them. Catalogs cache per ordinary session with a single-flight fetch; the scope-birth `warm` hook prewarms the session's entry and `connection/reset` clears everything. Results filter by `startsWith(query)`.
 
-A pick lands the literal `/name ` text and the prompt ships the same literal (decision 21) — this source implements no adjudication hooks and no reference codec (the legacy `<skill>name</skill>` form is gone with the removal cut). Determinism lives host-side: the pre-step gesture boundary (`dsh-tool-skill`) recognizes whitespace-bounded `/name` tokens naming user-invocable skills anywhere in a user message and injects the rendered `<skill_content>` for every front end, so a menu pick, a hand-typed token, and a TUI/ACP prompt all load the skill the same way. A name shared with a host command still resolves to the command: adjudication claims the line client-side before it ever becomes a prompt — deliberate precedence, matching peer products. The list RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument; draft chip visuals derive from the `lexicon` scan.
+A pick lands the literal `/name ` text and the prompt ships the same literal ([slash-pipeline Agent Note](../../../.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)) — this source implements no adjudication hooks and no reference codec. Determinism lives host-side: the pre-step gesture boundary (`dsh-tool-skill`) recognizes whitespace-bounded `/name` tokens naming user-invocable skills anywhere in a user message and injects the rendered `<skill_content>` for every front end, so a menu pick, a hand-typed token, and a TUI/ACP prompt all load the skill the same way. A name shared with a host command still resolves to the command: adjudication claims the line client-side before it ever becomes a prompt — deliberate precedence, matching peer products. The list RPC rides the plugin's root-context connection captured at registration — the source never reads services off a per-call argument; draft chip visuals derive from the `lexicon` scan.
 
 A failed `skill.list` throws from `candidates`, which the slash shell logs and folds into a silent menu-group drop — the menu shows only pending/ready states.
 
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 3a8ac86d13..8f1f69b26a 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -4,7 +4,7 @@
 
 skill（技能）调用 source 的浏览器端：把 `/` 触发的 `skill` source 注册进 `ctx.slash`。普通会话的候选来自 `skill.list` RPC，以每次调用的 `ClientSessionContext` 投影中的 `{sessionId}` 寻址，host 从会话 header 解析 `cwd`。宿主提供每一个用户可调用的 skill；`modelInvocable: false` 的条目（即 `disable-model-invocation` skill，此路径是其唯一入口）会以当前语言把仅限用户标记作为描述前缀带上。由目录寻址的可继续 subagent 在客户端解析为没有 skill 候选，因为现有 skill RPC 要求会话已挂载；查看其持久化历史不得激活它。目录按普通会话缓存，拉取走 single-flight；scope 创建时的 `warm` 钩子预热该会话的缓存项，`connection/reset` 清空全部缓存。结果按 `startsWith(query)` 过滤。
 
-pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文本（决策 21）——本 source 不实现任何裁决钩子，也没有引用 codec（旧的 `<skill>name</skill>` 形式已随移除裁定消失）。确定性在宿主侧：pre-step 手势边界（`dsh-tool-skill`）识别用户消息中任意位置、以空白为界、指名用户可调用 skill 的 `/name` token，并为每一种前端注入渲染后的 `<skill_content>`，因此菜单 pick、手动键入的 token 与 TUI/ACP（Agent Client Protocol）提示词都以同一种方式加载 skill。与宿主命令同名的名称仍解析为命令：裁决在客户端把该行认领走，它根本不会成为提示词——这是有意的优先级，与同行产品一致。列表 RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务；草稿 chip 视觉由 `lexicon` 扫描派生。
+pick 会落下字面文本 `/name `，提示词发出的就是同一段字面文本（[slash 流水线 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)）——本 source 不实现任何裁决钩子，也没有引用 codec。确定性在宿主侧：pre-step 手势边界（`dsh-tool-skill`）识别用户消息中任意位置、以空白为界、指名用户可调用 skill 的 `/name` token，并为每一种前端注入渲染后的 `<skill_content>`，因此菜单 pick、手动键入的 token 与 TUI/ACP（Agent Client Protocol）提示词都以同一种方式加载 skill。与宿主命令同名的名称仍解析为命令：裁决在客户端把该行认领走，它根本不会成为提示词——这是有意的优先级，与同行产品一致。列表 RPC 使用插件注册时捕获的根上下文连接——source 绝不从每次调用的参数上读取服务；草稿 chip 视觉由 `lexicon` 扫描派生。
 
 `skill.list` 失败时 `candidates` 抛出异常，slash 壳层记录日志并折叠为静默的菜单组丢弃——菜单只显示 pending／ready 状态。
 
diff --git a/packages/client/ui-skill/src/client/index.ts b/packages/client/ui-skill/src/client/index.ts
index 139398b648..524cd180cc 100644
--- a/packages/client/ui-skill/src/client/index.ts
+++ b/packages/client/ui-skill/src/client/index.ts
@@ -3,15 +3,16 @@
  * candidates from the skill.list RPC addressed by the per-call session
  * projection's sessionId (sessions are always agent-backed; the host
  * resolves cwd from the session header). A pick lands the literal `/name `
- * text and the prompt ships the same literal (decision 21); determinism
+ * text and the prompt ships the same literal (plain-text-reference decision;
+ * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md);
+ * determinism
  * lives host-side — the pre-step boundary (`dsh-tool-skill`) recognizes a
  * leading `/name` naming a user-invocable skill and injects the rendered
  * body for every front end, including `disable-model-invocation` skills the
  * model-side catalog never lists (issue #1470). The RPC rides the plugin's
  * root-context connection captured at registration — the source never reads
- * services off a per-call argument. Draft chip visuals still derive from
- * the lexicon scan; the legacy `<skill>` reference codec is gone (decision
- * 21 removal cut).
+ * services off a per-call argument. Draft chip visuals derive from
+ * the lexicon scan; this source implements no reference codec.
  *
  * Catalog fetches are cached per session (the small twin of the ui-command
  * directory): the per-keystroke candidates re-poll filters a settled
@@ -162,8 +163,9 @@ export function apply(ctx: ClientContext): void {
       }
     },
     onPick({ candidate }) {
-      // Decision 21: the pick lands plain text and the prompt ships the same
-      // literal. Determinism no longer rides the client — the host's
+      // Plain-text-reference decision (web-input-machine note): the pick
+      // lands plain text and the prompt ships the same
+      // literal. Determinism lives host-side — the host's
       // pre-step boundary (dsh-tool-skill) recognizes the leading /name and
       // injects the rendered body for every front end. A name shared with a
       // host command still resolves to the command: adjudication claims the
diff --git a/packages/client/ui-skill/tests/browser-plugin.spec.ts b/packages/client/ui-skill/tests/browser-plugin.spec.ts
index 4679ef2c98..f33924e977 100644
--- a/packages/client/ui-skill/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.spec.ts
@@ -6,7 +6,9 @@
  * real ClientSessionContext projections — sessionId addressing, the
  * session-keyed catalog cache (single-flight per key, scope-birth warm
  * prewarm, connection/reset clear), startsWith filtering, RPC-failure
- * rejection, pick → plain-text outcome (decision 21), the synchronous
+ * rejection, pick → plain-text outcome (the plain-text-reference decision:
+ * .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md),
+ * the synchronous
  * lexicon reads over the settled cache, and the reference codec's two
  * projections. Direct driving is deliberate: this spec owns only the
  * source's own contract.
@@ -322,7 +324,7 @@ describe('lexicon', () => {
   })
 })
 
-describe('pick lands plain text (decision 21)', () => {
+describe('pick lands plain text', () => {
   it('onPick returns the literal /name text with a closing space', async () => {
     const { source } = await bench(listOk(CATALOG))
     const outcome = source.onPick({
diff --git a/packages/client/ui-slash/README.i18n.yaml b/packages/client/ui-slash/README.i18n.yaml
index 6954134f01..47b4cc670f 100644
--- a/packages/client/ui-slash/README.i18n.yaml
+++ b/packages/client/ui-slash/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/client/ui-slash/README.md
-README.md: efb289aaf6b4a442b00e7a0b26ed044b7b061070
-README.zh.md: c6d3236f615642b9efc6fabaa7ec407ad896a8e2
+README.md: 739e7ae93e024bdbd602aaff4267cb74406b5698
+README.zh.md: 0e3cd0d4b3cb93e3d602aa0c8f30d4e5afff3af2
diff --git a/packages/client/ui-slash/README.md b/packages/client/ui-slash/README.md
index efb289aaf6..739e7ae93e 100644
--- a/packages/client/ui-slash/README.md
+++ b/packages/client/ui-slash/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Input trigger pipeline plugin: `/` and `@` detection under the caret (word-boundary + guard-tier rules), the grouped candidate menu, and pick routing to registered sources. `ctx.slash` owns the source roster and resolves one `SlashController` per session scope (`sessionOf`); the conversation wiring layer drives `track`/`arbitrate`/`onSpace`/`adjudicate` on the controller. The same controller exposes `toggleSource` for a chrome launcher to open exactly one registered source over a synthetic selection span; the resulting candidates still use the ordinary menu, keyboard arbitration, pick callback, and scoped input mutations. Sources receive a `ClientSessionContext` projection per call — sessions are always agent-backed, so the projection is the session identity alone. A source is warmed in every session controller it can reach: the roster present at scope birth warms during controller construction, and a source registered later is warmed into every live controller by the registration itself. Sources whose `lexicon` roll changes after warm implement `subscribeLexicon(session, listener)`; the controller re-polls on each notification and publishes the aggregation through its `lexicon` snapshot store. The pipeline is command-agnostic: space/enter adjudication polls the optional `matchSpace`/`matchEnter` hooks in registration order and the first non-undefined answer wins.
 
-Layering: `src/core/` (T2) is the pure core — `detectTrigger`, `menuReduce`/`seedGroups`/`MENU_CLOSED`, `exactMatch`, zero React/DOM/cordis; `src/client/service.ts` is the shell wiring the core to the menu snapshot store, the per-hit candidate fetch (generation-gated, `AbortSignal`-superseded, failed sources drop silently with a console record), and the three pick paths. `src/types.ts` and the two `contract.ts` files are the frozen cross-package contract (design v4 §5.1); changes require main-thread arbitration.
+Layering: `src/core/` (T2) is the pure core — `detectTrigger`, `menuReduce`/`seedGroups`/`MENU_CLOSED`, `exactMatch`, zero React/DOM/cordis; `src/client/service.ts` is the shell wiring the core to the menu snapshot store, the per-hit candidate fetch (generation-gated, `AbortSignal`-superseded, failed sources drop silently with a console record), and the three pick paths. `src/types.ts` and the two `contract.ts` files are the frozen cross-package contract; changes require main-thread arbitration.
 
 MenuView renders the menu store into the `conversation.input.overlay` slot (list kind, session scope) and renders null while closed. Typed triggers seed every source registered for that trigger; a programmatic launcher seeds only its requested source and publishes the source name through the controller's `launcher` snapshot store until the menu closes or typed tracking resumes. Groups sort by the optional `SlashSource.order` (lower first, default 0, ties keep registration order) under title rows localized through the `slash.menu` locale namespace (an unknown source shows its raw name); the list height clamps to the space above the composer, and a pointer down outside both the menu and the surrounding composer card dismisses it. The slot is owned by ui-conversation's composer entry (anchor, children declaration, lifecycle); its SlotMap type merge lives in this package's `src/client/slots.ts` because the dependency direction (ui-conversation → ui-slash) admits no reverse type import. Combobox pattern: focus stays in the textarea, rows pick on mousedown, the highlight rides `aria-activedescendant`.
 
diff --git a/packages/client/ui-slash/README.zh.md b/packages/client/ui-slash/README.zh.md
index c6d3236f61..0e3cd0d4b3 100644
--- a/packages/client/ui-slash/README.zh.md
+++ b/packages/client/ui-slash/README.zh.md
@@ -4,7 +4,7 @@
 
 输入触发流水线插件：光标处的 `/` 与 `@` 检测（词边界 + guard tier 规则）、分组候选菜单，以及把 pick 路由到已注册 source。`ctx.slash` 拥有 source roster，并按会话 scope（`sessionOf`）各解析一个 `SlashController`；对话接线层在 controller 上驱动 `track`／`arbitrate`／`onSpace`／`adjudicate`。同一个 controller 还暴露 `toggleSource`，供 chrome launcher 在一段合成 selection span 上只打开一个已注册 source；所得候选仍走通常的菜单、键盘仲裁、pick callback 与 scoped 输入改写。source 每次调用收到一个 `ClientSessionContext` 投影——会话始终由 agent（智能体）支撑，因此投影只含会话身份。source 在它能触达的每个会话 controller 中都会被预热：scope 出生时在场的 roster 随 controller 构造预热，晚于此注册的 source 由注册动作本身预热进每个活 controller。`lexicon` 名录在预热后仍会变化的 source 实现 `subscribeLexicon(session, listener)`；controller 每收到通知就重拉，并把聚合结果经其 `lexicon` 快照 store 发布。流水线与命令无关：空格／回车裁决按注册序轮询可选的 `matchSpace`／`matchEnter` 钩子，第一个非 undefined 的应答胜出。
 
-分层：`src/core/`（T2）是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包约定（设计 v4 §5.1）；变更需经主线程仲裁。
+分层：`src/core/`（T2）是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包约定；变更需经主线程仲裁。
 
 MenuView 把菜单 store 渲染进 `conversation.input.overlay` slot（列表类，会话 scope），菜单关闭期间渲染 null。键入式 trigger 会 seed 为该 trigger 注册的所有 source；程序化 launcher 只 seed 所请求的 source，并在菜单关闭或重新开始键入式 tracking 前，通过 controller 的 `launcher` 快照 store 发布该 source 名称。分组按可选的 `SlashSource.order` 排序（越小越靠前，默认 0，同值保持注册序），组标题行经 `slash.menu` locale 命名空间本地化（未知 source 显示其原名）；列表高度收敛到 composer 上方的可用空间，指针落在菜单与所在 composer 卡片之外即关闭菜单。该 slot 由 ui-conversation 的组合器条目拥有（锚点、children 声明、生命周期）；其 SlotMap 类型合并放在本包的 `src/client/slots.ts`，因为依赖方向（ui-conversation → ui-slash）不允许反向的类型导入。combobox 模式：焦点始终留在 textarea，行在 mousedown 时完成 pick，高亮由 `aria-activedescendant` 承载。
 
diff --git a/packages/client/ui-slash/src/client/controller.ts b/packages/client/ui-slash/src/client/controller.ts
index fdf78d316e..9b2a4fd732 100644
--- a/packages/client/ui-slash/src/client/controller.ts
+++ b/packages/client/ui-slash/src/client/controller.ts
@@ -47,7 +47,8 @@ export class SlashController {
    */
   readonly launcher: SnapshotStore<string | null> = createSnapshotStore<string | null>(null)
   /**
-   * Aggregated hot reference lexicon, grouped by trigger (decision 21):
+   * Aggregated hot reference lexicon, grouped by trigger (plain-text-reference decision;
+   * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
    * sources implementing the lexicon hook are polled with the session
    * projection; undefined answers (roll not hot yet) are skipped; multiple
    * sources on one trigger concatenate in registration order. A snapshot
@@ -225,7 +226,7 @@ export class SlashController {
 
   /**
    * Serialize one reference occurrence to its model form via the owning
-   * source's codec (design §9.1 prompt serialization: registry → explicit
+   * source's codec (prompt serialization: registry → explicit
    * call → await). Owner missing or codec-less rejects — the submit attempt
    * blocks instead of silently downgrading to the clipboard text.
    * @param source - owning source name.
diff --git a/packages/client/ui-slash/src/client/slots.ts b/packages/client/ui-slash/src/client/slots.ts
index 5b90fb5ec1..9cdaeb309b 100644
--- a/packages/client/ui-slash/src/client/slots.ts
+++ b/packages/client/ui-slash/src/client/slots.ts
@@ -4,7 +4,7 @@
  * entry (declaring is claiming: anchor, children declaration, lifecycle),
  * but the SlotMap type merge lives here: the owner package depends on this
  * one, so the dependency direction admits no reverse type import, and a
- * type-erased registration is ruled out (PR #632 review). The owner's
+ * type-erased registration is ruled out. The owner's
  * program picks this merge up transitively through its ui-slash imports.
  */
 // Type-only edge: the SlotMap augmentation below merges into this package's interface.
diff --git a/packages/client/ui-slash/src/core/contract.ts b/packages/client/ui-slash/src/core/contract.ts
index 852ac2bf10..3c8f4c70ee 100644
--- a/packages/client/ui-slash/src/core/contract.ts
+++ b/packages/client/ui-slash/src/core/contract.ts
@@ -1,8 +1,8 @@
 /**
- * Frozen pure-core contract (design v4, plan §1.2): trigger detection and
- * menu reduction, zero React / DOM / cordis. Types only — T2 implements
- * these signatures in sibling modules (annotate implementations with these
- * aliases); the service shell (T4) wires them to ctx.
+ * Frozen pure-core contract: trigger detection and
+ * menu reduction, zero React / DOM / cordis. Types only — implementations
+ * live in sibling modules annotated with these
+ * aliases; the service shell wires them to ctx.
  */
 import type { SlashCandidate, TokenSpan, TriggerChar, TriggerGuard, TriggerPosition } from '../types.ts'
 
diff --git a/packages/client/ui-slash/src/core/detect.ts b/packages/client/ui-slash/src/core/detect.ts
index 5f2e43680c..6a1b69110b 100644
--- a/packages/client/ui-slash/src/core/detect.ts
+++ b/packages/client/ui-slash/src/core/detect.ts
@@ -1,5 +1,5 @@
 /**
- * Trigger detection pure core (design §5.1, plan §1.2). Scans backward from
+ * Trigger detection pure core. Scans backward from
  * the caret for a live trigger char under the guard tier and applies the
  * word-boundary rules. Zero React / DOM / cordis.
  */
diff --git a/packages/client/ui-slash/src/core/menu.ts b/packages/client/ui-slash/src/core/menu.ts
index fe1c7f10eb..a951f3cd42 100644
--- a/packages/client/ui-slash/src/core/menu.ts
+++ b/packages/client/ui-slash/src/core/menu.ts
@@ -1,5 +1,5 @@
 /**
- * Menu reduction pure core (design §5.1, plan §1.2). One group per source;
+ * Menu reduction pure core. One group per source;
  * generation-gated settlement; empty ready groups auto-close. Zero React /
  * DOM / cordis. Stale or no-op events return the same state reference so
  * store subscribers skip re-renders.
diff --git a/packages/client/ui-slash/src/types.ts b/packages/client/ui-slash/src/types.ts
index c885984b73..c62ca520d7 100644
--- a/packages/client/ui-slash/src/types.ts
+++ b/packages/client/ui-slash/src/types.ts
@@ -80,7 +80,9 @@ export interface SubmitOutcome {
 /**
  * Unified pick return. `undefined` = miss → default sink; `'handled'` = the
  * source dealt with it internally (e.g. opened its popup shell). The `text`
- * arm is the plain-text reference path (decision 21): the token span is
+ * arm is the plain-text reference path (decision recorded in
+ * .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
+ * the token span is
  * replaced with literal text — no occurrence identity, no placeholder; any
  * chip visual is derived downstream by scanning the draft against the
  * source lexicons.
@@ -159,8 +161,8 @@ export interface SlashSource {
    */
   warm?(session: ClientSessionContext): void
   /**
-   * Synchronous hot-snapshot name roll for plain-text reference decoration
-   * (decision 21). Implementing IS the participation claim: the render side
+   * Synchronous hot-snapshot name roll for plain-text reference decoration.
+   * Implementing IS the participation claim: the render side
    * scans the draft for `<trigger><name>` tokens and decorates exact matches.
    * `undefined` = backing data not warm yet — no decoration, never a fetch
    * (the render path must stay synchronous and side-effect free).
@@ -211,7 +213,7 @@ export interface ConsumeTokenRequest {
     | { readonly kind: 'bare-token'; readonly token: string }
 }
 
-/** Request payload of the scoped insert-text input event (decision 21). */
+/** Request payload of the scoped insert-text input event (the plain-text reference path). */
 export interface InsertTextRequest {
   /** Literal replacement for the trigger token span (e.g. `/name `). */
   readonly text: string
@@ -245,7 +247,7 @@ declare module 'cordis' {
     'slash/input-consume-token'(request: ConsumeTokenRequest): true | undefined
     /**
      * Replaces the trigger token span with literal text — the plain-text
-     * reference path (decision 21). Same carrier routing and applied-truth
+     * reference path. Same carrier routing and applied-truth
      * contract; the draft gains ordinary characters, no occurrence entry.
      * @param request - Replacement text and menu-time span CAS.
      * @mode bail
diff --git a/packages/client/ui-slash/tests/core-detect.spec.ts b/packages/client/ui-slash/tests/core-detect.spec.ts
index 6d3326b5d8..013645b91e 100644
--- a/packages/client/ui-slash/tests/core-detect.spec.ts
+++ b/packages/client/ui-slash/tests/core-detect.spec.ts
@@ -1,5 +1,5 @@
-// detectTrigger word-boundary, position, guard-tier, and span behavior
-// (design §5.1). URL rule pinned here: '/' is dead when its predecessor is
+// detectTrigger word-boundary, position, guard-tier, and span behavior.
+// URL rule pinned here: '/' is dead when its predecessor is
 // another '/' (second slash of '//') or a ':' itself preceded by a
 // non-whitespace char (scheme separator) — this is the concrete rule chosen
 // to honor "no trigger inside URLs".
diff --git a/packages/client/ui-slash/tests/core-menu.spec.ts b/packages/client/ui-slash/tests/core-menu.spec.ts
index 28cd009948..6f1d5101bd 100644
--- a/packages/client/ui-slash/tests/core-menu.spec.ts
+++ b/packages/client/ui-slash/tests/core-menu.spec.ts
@@ -1,6 +1,5 @@
 // menuReduce generation gating, auto-close, silent group removal, cyclic
-// highlight movement, stale/no-op reference identity; exactMatch lookup
-// (design §5.1, plan §1.2).
+// highlight movement, stale/no-op reference identity; exactMatch lookup.
 import { describe, expect, it } from 'vitest'
 import type { MenuState, TriggerHit } from '../src/core/contract.ts'
 import { exactMatch, MENU_CLOSED, menuReduce, seedGroups } from '../src/core/menu.ts'
diff --git a/packages/client/ui-slash/tests/menu-view.spec.tsx b/packages/client/ui-slash/tests/menu-view.spec.tsx
index 2157d19b98..2671b526b8 100644
--- a/packages/client/ui-slash/tests/menu-view.spec.tsx
+++ b/packages/client/ui-slash/tests/menu-view.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 /**
- * MenuView rendering spec, props-direct (slot-parity doctrine): closed store
+ * MenuView rendering spec, props-direct: closed store
  * renders null, groups render in roster order under localized title rows
  * (unknown sources fall back to the raw name) with pending rows as loading,
  * pointer picks route (source, index) back without stealing focus, the
diff --git a/packages/client/ui-slash/tests/service.spec.ts b/packages/client/ui-slash/tests/service.spec.ts
index 6f398442b9..143f6e6ddf 100644
--- a/packages/client/ui-slash/tests/service.spec.ts
+++ b/packages/client/ui-slash/tests/service.spec.ts
@@ -483,7 +483,7 @@ describe('pick / scoped input events', () => {
     expect(inserts).toEqual([{ reference: insert, span: { start: 0, end: 2, draftRev: 3 } }])
   })
 
-  it('routes a text outcome through the scoped insert-text event (decision 21) and closes the menu', async () => {
+  it('routes a text outcome through the scoped insert-text event and closes the menu', async () => {
     const { controller, actx } = pickBench(() => ({ text: '/goal ' }))
     const texts: Array<{ text: string; span: unknown }> = []
     actx.on('slash/input-insert-text', (req) => {
diff --git a/packages/client/ui-slots/src/index.ts b/packages/client/ui-slots/src/index.ts
index d6c1824c99..eae7837386 100644
--- a/packages/client/ui-slots/src/index.ts
+++ b/packages/client/ui-slots/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Slot registry pure core (slot terminal design). Owners declare slot
+ * Slot registry pure core. Owners declare slot
  * contracts by merging into {@link SlotMap}; one `register` call contributes a
  * component AND (optionally) declares child slots, a store seat, and the
  * registrant's business face. Zero runtime dependencies (React types only).
diff --git a/packages/client/ui-slots/src/renderer.ts b/packages/client/ui-slots/src/renderer.ts
index 20f6a68eb1..1bb6996fe7 100644
--- a/packages/client/ui-slots/src/renderer.ts
+++ b/packages/client/ui-slots/src/renderer.ts
@@ -70,8 +70,9 @@ export interface SessionMaybeProvideInfo {
   /** Static plain-member roster; values are undefined with the session. */
   props: Record<string, unknown>
   /**
-   * Key-addressed projection value sources (the useProjection framework seat,
-   * session-projection RFC). Unlike `hooks`, the key space is open — values
+   * Key-addressed projection value sources (the useProjection framework seat;
+   * session-projection subsystem page: docs/subsystems/session-projection.md).
+   * Unlike `hooks`, the key space is open — values
    * arrive from host-computed push frames — so the render side binds per
    * resolved key instead of per static roster member. Faces are always
    * defined per key (absence is an `undefined` snapshot); the whole member is
diff --git a/packages/client/ui-subagent/src/client/index.ts b/packages/client/ui-subagent/src/client/index.ts
index 73c7f9a6cc..de2ac87c48 100644
--- a/packages/client/ui-subagent/src/client/index.ts
+++ b/packages/client/ui-subagent/src/client/index.ts
@@ -3,10 +3,12 @@
  * candidates filtered from the session list snapshot's running children
  * (zero RPC; the list rides the plugin's root-context sessions service, the
  * scoped session comes from the per-call projection), pick inserts the
- * literal `@label ` text (decision 21: the draft carries plain text, chip
+ * literal `@label ` text (plain-text-reference decision, see
+ * .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md:
+ * the draft carries plain text, chip
  * visuals are derived by scanning against the source lexicon, and the
  * prompt ships the same literal). Consumption semantics stay with future
- * business work (design ledger). No adjudication hooks: subagent
+ * business work. No adjudication hooks: subagent
  * references never enter command adjudication.
  */
 import type {
@@ -80,16 +82,14 @@ export function apply(ctx: ClientContext): void {
       return sessions.list.subscribe(listener)
     },
     onPick({ candidate }) {
-      // Decision 21: plain-text reference — the literal lands in the draft
+      // Plain-text reference: the literal lands in the draft
       // and ships to the model verbatim (trailing space closes the token).
-      // Legacy path (decision 21), retained for the removal cut, no longer reached:
-      // return { insert: { source: 'subagent', ref: candidate.name, label: candidate.name, clipboardText: `@${candidate.name}` } }
       return { text: `@${candidate.name} ` }
     },
     codec: {
       clipboardText: ref => `@${ref}`,
       // TODO: serialize returns the raw label until the '@' consumption
-      // feature defines a model representation (design ledger).
+      // feature defines a model representation.
       serialize: ref => Promise.resolve(`@${ref}`),
     },
   }
diff --git a/packages/client/ui-subagent/tests/browser-plugin.spec.ts b/packages/client/ui-subagent/tests/browser-plugin.spec.ts
index 861546c19c..9796c68637 100644
--- a/packages/client/ui-subagent/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-subagent/tests/browser-plugin.spec.ts
@@ -5,7 +5,9 @@
  * real ClientSessionContext projections — zero-RPC candidates from the root
  * session list (running children of the projected session, label-contains
  * filtering, childless session → empty), the synchronous lexicon roster,
- * pick → plain-text outcome (decision 21), and the reference codec's two
+ * pick → plain-text outcome (the plain-text-reference decision:
+ * .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md),
+ * and the reference codec's two
  * projections. Direct driving is deliberate: this spec owns only the
  * source's own contract.
  */
@@ -227,7 +229,7 @@ describe('lexicon', () => {
 })
 
 describe('pick and codec', () => {
-  it('onPick returns the literal @label text with a closing space (decision 21)', async () => {
+  it('onPick returns the literal @label text with a closing space', async () => {
     const source = await bench(FAMILY)
     const outcome = source.onPick({
       candidate: { name: 'worker-1' },
diff --git a/packages/client/ui-theme/README.i18n.yaml b/packages/client/ui-theme/README.i18n.yaml
index 35b576523d..7cf091e0f5 100644
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/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/client/ui-theme/README.md
-README.md: 648213b258169b2e8869a93d058fcc65aece175e
-README.zh.md: ec29b9be999d64eee76342f0a86eb8707807be06
+README.md: 2d576cc16b0b8fef453ad54cacd9cb195dc75e7a
+README.zh.md: b1f17c65749a94f1f48b5f7af9c8b18a5d85eb76
diff --git a/packages/client/ui-theme/README.md b/packages/client/ui-theme/README.md
index 648213b258..2d576cc16b 100644
--- a/packages/client/ui-theme/README.md
+++ b/packages/client/ui-theme/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Theme plugin: ThemeService over the --dsw-* token base stylesheets (static scale + alias semantic layers). The service owns the theme preference (`light`/`dark`/`system`, persisted under `dsh.theme`), resolves `system` through `prefers-color-scheme`, and publishes immutable `ThemeSnapshot`s on the `theme/change` event; it never touches the DOM — ui-layout's presenter applies the resolved snapshot (`html { color-scheme }`, `body[data-ds-dark-theme]`, and inline alias tokens). Contract: api-contracts v3 §8.
+Theme plugin: ThemeService over the --dsw-* token base stylesheets (static scale + alias semantic layers). The service owns the theme preference (`light`/`dark`/`system`, persisted under `dsh.theme`), resolves `system` through `prefers-color-scheme`, and publishes immutable `ThemeSnapshot`s on the `theme/change` event; it never touches the DOM — ui-layout's presenter applies the resolved snapshot (`html { color-scheme }`, `body[data-ds-dark-theme]`, and inline alias tokens).
 
 `src/styles/` holds five sheets, all imported by the web shell's `base.css`: `base.css`, `design-platform.css`, `scrollbar.css`, `gradient-shadow-text.css`, and `shiki.css`. `scrollbar.css` is the sole consumer of the `--dsw-alias-scrollbar-*` tokens and must follow `design-platform.css`, which declares them.
 
@@ -21,4 +21,4 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **Third-party themes are a surface, not a product** — registering one means overriding same-named alias variables; no validation exists that an override set is complete.
-- **The token sheets are the sole color authority** — values absent from cssdesign (for example the design's #4176E6 tab blue) are deliberately not appended; the nearest semantic token wins (arbitrated 2026-07-22). Design-owner-approved additions are the exception and enter as a static step plus a semantic alias in the same change (`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`, 2026-08-07).
+- **The token sheets are the sole color authority** — values absent from cssdesign (for example the design's #4176E6 tab blue) are deliberately not appended; the nearest semantic token wins. Design-owner-approved additions are the exception and enter as a static step plus a semantic alias in the same change (`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`).
diff --git a/packages/client/ui-theme/README.zh.md b/packages/client/ui-theme/README.zh.md
index ec29b9be99..b1f17c6574 100644
--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有主题偏好（`light`／`dark`／`system`，以 `dsh.theme` 为键持久化），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。约定：api-contracts v3 §8。
+主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有主题偏好（`light`／`dark`／`system`，以 `dsh.theme` 为键持久化），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。
 
 `src/styles/` 下有五张样式表，全部由 web 壳的 `base.css` 导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
 
@@ -21,4 +21,4 @@
 ## 已知限制与暂缓事项
 
 - **第三方主题是表层，不是产品**：注册主题意味着覆盖同名别名变量；目前不会验证一组覆盖是否完整。
-- **token 样式表是颜色值的唯一权威来源**：会有意不补入 cssdesign 中缺失的值（例如设计中的 #4176E6 标签页蓝色）；一律采用最接近的语义 token（裁定于 2026-07-22）。设计负责人批准的新增值是例外：须在同一变更中以一个静态尺度层级与一个语义别名的形式进入（`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`，2026-08-07）。
+- **token 样式表是颜色值的唯一权威来源**：会有意不补入 cssdesign 中缺失的值（例如设计中的 #4176E6 标签页蓝色）；一律采用最接近的语义 token。设计负责人批准的新增值是例外：须在同一变更中以一个静态尺度层级与一个语义别名的形式进入（`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`）。
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 84c6fa42af..dcd4846c34 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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/client/ui-tool/README.md
-README.md: b33aef86a6ad161f70105968f308c5a587c25c24
-README.zh.md: 680a5149187bc43513c74134a9a58c4680af854c
+README.md: 8255aee4292ea821962477a7108b40cf3b937981
+README.zh.md: 2bc5859f592efb6ac4b67157be09a3c09afb691c
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index b33aef86a6..8255aee429 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -44,6 +44,6 @@ None. The package is client-only presentation.
 
 ## Known Limitations and Deferred Work
 
-- The Host excludes `run_code` from Code Mode program bindings, so production events currently produce one dispatch level; the recursive Runtime/UI contract is ready for future nested producers.
-- Existing first-party Tool views are initially colocated here and can move to their owning business packages independently through the keyed slot.
-- Tool copy temporarily reuses the `ui-conversation` locale namespace.
+- The Host excludes `run_code` from Code Mode program bindings, so production events produce one dispatch level; the recursive Runtime/UI contract supports nesting.
+- First-party Tool views are colocated here and can move to their owning business packages independently through the keyed slot.
+- Tool copy reuses the `ui-conversation` locale namespace.
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index 680a514918..2bc5859f59 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -44,6 +44,6 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 ## 已知限制与后续工作
 
-- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件目前只能产生一层分发；递归的运行时/UI 约定已为未来的嵌套生产者做好准备。
-- 现有第一方 Tool 视图初期仍集中在本包，之后可以通过 keyed slot 独立迁回各自业务包。
-- Tool 文案暂时复用 `ui-conversation` locale namespace。
+- Host 不把 `run_code` 暴露为 Code Mode 程序 binding，因此生产事件只产生一层分发；递归的运行时/UI 约定支持嵌套。
+- 第一方 Tool 视图集中在本包，可以通过 keyed slot 独立迁回各自业务包。
+- Tool 文案复用 `ui-conversation` locale namespace。
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
index f94809939a..10fea1b8c8 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
@@ -49,8 +49,8 @@ export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {
       // sub-dispatch, legacy generic result) has its text nowhere else to go;
       // ToolRow's Output section carries it, and errorSummary its first line.
       // When a card is present ToolRow renders it instead of the output, so
-      // passing model.output unconditionally is safe and keeps the four card
-      // rows symmetric.
+      // model.output passes unconditionally and the four card rows stay
+      // symmetric.
       output={model.output}
       errorSummary={model.errorSummary}
       search={search}
diff --git a/packages/client/ui-tool/tests/tool-row.spec.tsx b/packages/client/ui-tool/tests/tool-row.spec.tsx
index 9fed8e3720..def3b98852 100644
--- a/packages/client/ui-tool/tests/tool-row.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.spec.tsx
@@ -71,8 +71,8 @@ describe('tool-call-model', () => {
     expect(toolRowModel('read', running({ name: 'read', argsRaw: '{"path":"/tmp/x.ts"}' })).summary).toBe('/tmp/x.ts')
     expect(toolRowModel('write', running({ name: 'write', argsRaw: '{"file_path":"src/x.ts"}' })).summary).toBe('src/x.ts')
     expect(toolRowModel('edit', running({ name: 'edit', argsRaw: '{"file_path":"src/x.ts"}' })).summary).toBe('src/x.ts')
-    // Others rows prefix the real tool name into the summary slot (figma-flows
-    // ruling: static "Tool call" title, name rides the mutable summary).
+    // Other rows prefix the real tool name into the summary slot (figma
+    // flows: static "Tool call" title, the name rides the mutable summary).
     expect(toolRowModel('x', running({ argsRaw: '{"n":1}' })).summary).toBe('x · {"n":1}')
     expect(toolRowModel('x', running({ argsRaw: 'not json' })).summary).toBe('x · not json')
     expect(toolRowModel('x', running({ argsRaw: '' })).summary).toBe('x · c1')
diff --git a/packages/client/ui-trajectory/README.i18n.yaml b/packages/client/ui-trajectory/README.i18n.yaml
index e0646b2da8..7fecd92d74 100644
--- a/packages/client/ui-trajectory/README.i18n.yaml
+++ b/packages/client/ui-trajectory/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/client/ui-trajectory/README.md
-README.md: 2c737fe2d04df518e7d32d07aaede714a7a3566d
-README.zh.md: 1baa5a1a4422731161e6c8a743aa337a0e5cc774
+README.md: 5b8c0cd111c272007212fea0d2435c5fab2360ab
+README.zh.md: 9aaa02ccd9d50b0f0b23e9a53ea9b1048d0e513f
diff --git a/packages/client/ui-trajectory/README.md b/packages/client/ui-trajectory/README.md
index 2c737fe2d0..5b8c0cd111 100644
--- a/packages/client/ui-trajectory/README.md
+++ b/packages/client/ui-trajectory/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Trajectory renders a turn-aware event ledger with selectable User, Assistant, Tool, and nested Subtool records. Thick rules mark Turn boundaries, compact inline markers identify Steps, and the main ledger keeps only index, event, and content; selection opens a local inspector for token usage, duration, Input, Output, and Timing. Scrollable Summary regions keep their scrollbar thumbs transparent until the region is hovered or contains keyboard focus, without changing the reserved scroll geometry. A standalone compaction request appears chronologically in its own `Between turns` section, while a numbered compaction remains inside its owning turn. Long ledgers open at the current tail, load one older page when the user reaches the loaded range's top, and mount only the visible row window plus a small overscan; request-only separators share the next measurable virtual item, while semantic row keys and ARIA indexes survive prepends. Selection, timeline navigation, folding, search, and Request totals cover the currently loaded window. The ledger covers records with an explicit loading row until the initial tail is positioned and while an older page is pending. A fixed Overview above the ledger projects real record start/duration timing from left to right; when earlier records remain unloaded and the viewport includes the loaded domain's start, a neutral ellipsis control identifies the omitted prefix and loads one earlier page without assigning unknown history fabricated duration. Assistant spans divide recorded TTFT from decoding, and a 500 ms hover reveals exact clock and duration details. Dragging an interval focuses the ledger on every record active at any point in that inclusive range, while clearing the selection restores the full branch. Wheel gestures zoom the time domain. A right-button click clears the selected interval, while a right-button drag pans an already zoomed viewport without changing it. The initial view and streaming updates stay at the tail; scrolling upward suspends following so new records do not interrupt inspection of earlier rows. Content-only stream frames preserve virtual row keys and heights, reuse measurements, and do not issue repeated tail-scroll writes. Completed replies retain only the first visible token and usage chunks in the inspection projection, while unfinished and interrupted replies retain every chunk; the independent source keeps the raw history unchanged. Trajectory asks the conversation shell to float the composer over the full-height ledger, while its responsive vertical scrollers reserve the composer's live height so final rows remain reachable. The runtime's independent history source supplies raw context lineage and projects cancellation-frozen Assistant and Tool records, so Trajectory neither reads nor changes the Chat conversation snapshot. The package remains a pure-consumer plugin (registers one view tab into the conversation's `'conversation.view'` slot ring, provides no service, declares no Context merge). Contract: api-contracts v3 §8.
+Trajectory renders a turn-aware event ledger with selectable User, Assistant, Tool, and nested Subtool records. Thick rules mark Turn boundaries, compact inline markers identify Steps, and the main ledger keeps only index, event, and content; selection opens a local inspector for token usage, duration, Input, Output, and Timing. Scrollable Summary regions keep their scrollbar thumbs transparent until the region is hovered or contains keyboard focus, without changing the reserved scroll geometry. A standalone compaction request appears chronologically in its own `Between turns` section, while a numbered compaction remains inside its owning turn. Long ledgers open at the current tail, load one older page when the user reaches the loaded range's top, and mount only the visible row window plus a small overscan; request-only separators share the next measurable virtual item, while semantic row keys and ARIA indexes survive prepends. Selection, timeline navigation, folding, search, and Request totals cover the currently loaded window. The ledger covers records with an explicit loading row until the initial tail is positioned and while an older page is pending. A fixed Overview above the ledger projects real record start/duration timing from left to right; when earlier records remain unloaded and the viewport includes the loaded domain's start, a neutral ellipsis control identifies the omitted prefix and loads one earlier page without assigning unknown history fabricated duration. Assistant spans divide recorded TTFT from decoding, and a 500 ms hover reveals exact clock and duration details. Dragging an interval focuses the ledger on every record active at any point in that inclusive range, while clearing the selection restores the full branch. Wheel gestures zoom the time domain. A right-button click clears the selected interval, while a right-button drag pans an already zoomed viewport without changing it. The initial view and streaming updates stay at the tail; scrolling upward suspends following so new records do not interrupt inspection of earlier rows. Content-only stream frames preserve virtual row keys and heights, reuse measurements, and do not issue repeated tail-scroll writes. Completed replies retain only the first visible token and usage chunks in the inspection projection, while unfinished and interrupted replies retain every chunk; the independent source keeps the raw history unchanged. Trajectory asks the conversation shell to float the composer over the full-height ledger, while its responsive vertical scrollers reserve the composer's live height so final rows remain reachable. The runtime's independent history source supplies raw context lineage and projects cancellation-frozen Assistant and Tool records, so Trajectory neither reads nor changes the Chat conversation snapshot. The package remains a pure-consumer plugin (registers one view tab into the conversation's `'conversation.view'` slot ring, provides no service, declares no Context merge).
 
 ## Model Experience
 
diff --git a/packages/client/ui-trajectory/README.zh.md b/packages/client/ui-trajectory/README.zh.md
index 1baa5a1a44..9aaa02ccd9 100644
--- a/packages/client/ui-trajectory/README.zh.md
+++ b/packages/client/ui-trajectory/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Trajectory 渲染按轮次组织的事件记录表，其中可选择用户、助手、工具和嵌套子工具记录。较粗的分割线标示轮次边界，紧凑的行内标记标识步骤，主记录表仅保留索引、事件和内容；选择记录则会打开局部检查器，查看 token 用量、耗时、输入、输出和计时。可滚动的概述区域默认保持滚动条滑块透明，直到鼠标悬停该区域或其中包含键盘焦点时才显示，同时不改变滚动条预留的几何空间。独立运行的压缩（compaction）请求会按时间顺序显示在自己的 `Between turns` 区段中，而带编号的压缩仍位于其所属轮次内。长记录表打开时定位于当前尾部，用户到达已加载范围顶部时加载一页更早的历史，并且只挂载可见行窗口和少量额外缓冲行；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键和 ARIA 索引在向前补页后保持不变。选择、时间线导航、折叠、搜索和请求汇总只覆盖当前已加载的窗口。初始尾部完成定位前以及更早页面仍在等待时，记录表会用明确的加载行遮住真实记录。固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；仍有更早记录未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会标识被省略的前缀，并可加载一页更早历史，而不会为未知部分虚构耗时。助手时间条会区分记录到的 TTFT 与解码时间，悬停 500 ms 后可查看精确时刻和耗时详情。拖选一个区间会将记录表聚焦到活动区间与该闭区间有重叠的所有记录，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除所选区间；在已放大的 viewport 上按住右键拖动则只会平移视图，不会改变该区间。初始视图和流式更新都会停留在尾部；向上滚动会暂停跟随，因此新记录不会打断对旧记录的检查。仅含内容更新的流式帧会保持虚拟行的键和高度不变、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复在检查投影中仅保留首个可见 token 和用量分片，未完成及中断的回复则保留所有分片；独立数据源中的原始历史保持不变。Trajectory 要求会话壳将 composer 作为浮层置于全高记录表上方；其响应式纵向滚动容器会预留 composer 的实时高度，确保仍可滚动到最后几行。运行时的独立历史数据源提供原始上下文谱系，并投影因取消而冻结的助手和工具记录，因此 Trajectory 既不读取也不改变 Chat 会话快照。该包保持为纯消费方插件（向会话的 `'conversation.view'` slot 环注册一个视图标签页，不提供服务，也不声明 Context 合并）。约定：api-contracts v3 §8。
+Trajectory 渲染按轮次组织的事件记录表，其中可选择用户、助手、工具和嵌套子工具记录。较粗的分割线标示轮次边界，紧凑的行内标记标识步骤，主记录表仅保留索引、事件和内容；选择记录则会打开局部检查器，查看 token 用量、耗时、输入、输出和计时。可滚动的概述区域默认保持滚动条滑块透明，直到鼠标悬停该区域或其中包含键盘焦点时才显示，同时不改变滚动条预留的几何空间。独立运行的压缩（compaction）请求会按时间顺序显示在自己的 `Between turns` 区段中，而带编号的压缩仍位于其所属轮次内。长记录表打开时定位于当前尾部，用户到达已加载范围顶部时加载一页更早的历史，并且只挂载可见行窗口和少量额外缓冲行；仅含请求的分隔行并入下一个具备可测高度的虚拟项，语义行键和 ARIA 索引在向前补页后保持不变。选择、时间线导航、折叠、搜索和请求汇总只覆盖当前已加载的窗口。初始尾部完成定位前以及更早页面仍在等待时，记录表会用明确的加载行遮住真实记录。固定在记录表上方的 Overview 区域从左到右投影记录的真实开始时间与耗时；仍有更早记录未加载且 viewport 包含已加载时间域起点时，中性的省略号控件会标识被省略的前缀，并可加载一页更早历史，而不会为未知部分虚构耗时。助手时间条会区分记录到的 TTFT 与解码时间，悬停 500 ms 后可查看精确时刻和耗时详情。拖选一个区间会将记录表聚焦到活动区间与该闭区间有重叠的所有记录，清除选择则恢复完整分支。滚轮手势用于缩放时间域。右键单击会清除所选区间；在已放大的 viewport 上按住右键拖动则只会平移视图，不会改变该区间。初始视图和流式更新都会停留在尾部；向上滚动会暂停跟随，因此新记录不会打断对旧记录的检查。仅含内容更新的流式帧会保持虚拟行的键和高度不变、复用测量结果，并且不会重复写入末尾滚动位置。已完成的回复在检查投影中仅保留首个可见 token 和用量分片，未完成及中断的回复则保留所有分片；独立数据源中的原始历史保持不变。Trajectory 要求会话壳将 composer 作为浮层置于全高记录表上方；其响应式纵向滚动容器会预留 composer 的实时高度，确保仍可滚动到最后几行。运行时的独立历史数据源提供原始上下文谱系，并投影因取消而冻结的助手和工具记录，因此 Trajectory 既不读取也不改变 Chat 会话快照。该包保持为纯消费方插件（向会话的 `'conversation.view'` slot 环注册一个视图标签页，不提供服务，也不声明 Context 合并）。
 
 ## 模型体验
 
diff --git a/packages/client/ui-trajectory/src/client/layout.ts b/packages/client/ui-trajectory/src/client/layout.ts
index 4e110a5888..6e86fac8dc 100644
--- a/packages/client/ui-trajectory/src/client/layout.ts
+++ b/packages/client/ui-trajectory/src/client/layout.ts
@@ -935,8 +935,8 @@ function expandSubCalls(
             isError: sub.isError,
           }
           : {}),
-        // PR3's start/settle pair carries per-sub-call wall time; a running
-        // (unsettled) or pre-pair log entry shows the em dash.
+        // The code-dispatch start/settle pair carries per-sub-call wall time;
+        // a running (unsettled) or pre-pair log entry shows the em dash.
         timeSeconds: settled ? durationSeconds(sub.time, sub.callTime) : null,
         startedAt: settled
           ? finiteTime(sub.callTime)
diff --git a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx
index fd4f31f78e..a049b3f3d1 100644
--- a/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx
+++ b/packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx
@@ -150,8 +150,8 @@ function SessionTree({
         )}
         {groups.map(group => (
           // Group section: header row + expanded top-level session rows. The
-          // inter-group breathing room (former flat-list batch separator)
-          // is the section's own margin (WorkspaceBrowser.module.css).
+          // inter-group breathing room is the section's own margin
+          // (WorkspaceBrowser.module.css).
           <div key={group.key} className={css.groupSection}>
             <ProjectRowItem
               group={group}
diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx
index 40ef1e8883..71c0b05af5 100644
--- a/packages/client/ui-workspace/src/client/rows/Rows.tsx
+++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx
@@ -346,9 +346,9 @@ export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork
   const statuses = sessionStatuses(node, t)
   const primaryStatus = statuses[0]
   const [menuOpen, setMenuOpen] = useState(false)
-  // Archive replaces the former Delete placeholder: it hides the row through
-  // the registry-global archive set and never touches the session log, so it
-  // is not styled as destructive and needs no confirmation dialog.
+  // Archive hides the row through the registry-global archive set and never
+  // touches the session log, so it is not styled as destructive and needs no
+  // confirmation dialog.
   const sessionMenuItems = [
     { id: 'rename', label: t('rename'), icon: <IconEditOutline16 /> },
     { id: 'fork', label: t('menu.fork'), icon: <IconBranchOutline16 /> },
diff --git a/packages/client/ui-workspace/tests/rename-assembly.spec.tsx b/packages/client/ui-workspace/tests/rename-assembly.spec.tsx
index 44b812532e..3c37f137d6 100644
--- a/packages/client/ui-workspace/tests/rename-assembly.spec.tsx
+++ b/packages/client/ui-workspace/tests/rename-assembly.spec.tsx
@@ -4,8 +4,9 @@
  * WorkspaceBrowser occupying the sidebar hole): row menu → rename dialog →
  * the injected renameSession hop (sessions.binding → ISession.rename) → on
  * the accepted unary response the dialog closes and the row re-labels from
- * the list state — no push-frame wait. Previously pinned only by the
- * assembled-app snapshot (apps/web/tests/session-actions.snapshot.ts); the
+ * the list state — no push-frame wait. Coverage split: the assembled-app
+ * snapshot (apps/web/tests/session-actions.snapshot.ts) pins the full-app
+ * transcript; the
  * verb's wire behavior stays with the runtime package
  * (session.spec.ts#rename), the dialog's own arms with rows.spec /
  * workspace-browser.spec.
diff --git a/packages/client/web-react/README.i18n.yaml b/packages/client/web-react/README.i18n.yaml
index 72afe765f0..44859cc39a 100644
--- a/packages/client/web-react/README.i18n.yaml
+++ b/packages/client/web-react/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/client/web-react/README.md
-README.md: 8f1a525af1e249282f2cc473e7f9652f68f914a8
-README.zh.md: 55ed3a0fec4bfba4c4934db8728bc6fa23a7321a
+README.md: ada2a1384427f5a54c51e9fca8bbf9595e4d3403
+README.zh.md: 40cd70c689b87a5935e0249df47899982e898be8
diff --git a/packages/client/web-react/README.md b/packages/client/web-react/README.md
index 8f1a525af1..ada2a13844 100644
--- a/packages/client/web-react/README.md
+++ b/packages/client/web-react/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shell-side React glue for the slot terminal design: createSlotRenderer (the SlotRenderer implementation the shell installs into the runtime SlotsService), SessionProvider (framework-wired render prop, also injected as a standard seat to entries declaring session-scope children), bindSnapshotSelector (the one hook constructor — hosts and engines traffic in bare observable sources; every hook binds here, cached per source), useInvoke. Chain-slot outlets run the registered selectors in chain order at render time and mount only the elected entry, its select return joining the props as `matched`; the `renderSlotChain` binding is per-entry cached like `renderSlot`. The snapshot-store engine and defineStore live in runtime (store relocation); business plugins depend on ui-slots types only, never on this package.
+Shell-side React glue for the slot terminal design: createSlotRenderer (the SlotRenderer implementation the shell installs into the runtime SlotsService), SessionProvider (framework-wired render prop, also injected as a standard seat to entries declaring session-scope children), bindSnapshotSelector (the one hook constructor — hosts and engines traffic in bare observable sources; every hook binds here, cached per source), useInvoke. Chain-slot outlets run the registered selectors in chain order at render time and mount only the elected entry, its select return joining the props as `matched`; the `renderSlotChain` binding is per-entry cached like `renderSlot`. The snapshot-store engine and defineStore live in runtime; business plugins depend on ui-slots types only, never on this package.
 
 ## Model Experience
 
diff --git a/packages/client/web-react/README.zh.md b/packages/client/web-react/README.zh.md
index 55ed3a0fec..40cd70c689 100644
--- a/packages/client/web-react/README.zh.md
+++ b/packages/client/web-react/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-slot 终端设计的外壳侧 React 胶水：createSlotRenderer（外壳安装到运行时 SlotsService 的 SlotRenderer 实现）、SessionProvider（由框架接入的 render prop，也作为标准 seat 注入到声明会话 scope 子 slot 的配置项）、bindSnapshotSelector（唯一的钩子构造器：主机与引擎只传递裸 observable source；每个钩子在此绑定，并按 source 缓存）、useInvoke。链式 slot outlet 在渲染时按链顺序运行已注册 selector，只挂载被选中的配置项，其 select 返回值以 `matched` 加入 props；`renderSlotChain` 绑定与 `renderSlot` 一样按配置项缓存。快照 store 引擎与 defineStore 位于运行时（store 已迁移）；业务插件只依赖 ui-slots 类型，绝不依赖该包。
+slot 终端设计的外壳侧 React 胶水：createSlotRenderer（外壳安装到运行时 SlotsService 的 SlotRenderer 实现）、SessionProvider（由框架接入的 render prop，也作为标准 seat 注入到声明会话 scope 子 slot 的配置项）、bindSnapshotSelector（唯一的钩子构造器：主机与引擎只传递裸 observable source；每个钩子在此绑定，并按 source 缓存）、useInvoke。链式 slot outlet 在渲染时按链顺序运行已注册 selector，只挂载被选中的配置项，其 select 返回值以 `matched` 加入 props；`renderSlotChain` 绑定与 `renderSlot` 一样按配置项缓存。快照 store 引擎与 defineStore 位于运行时；业务插件只依赖 ui-slots 类型，绝不依赖该包。
 
 ## 模型体验
 
diff --git a/packages/client/web-react/src/scoped-slots.tsx b/packages/client/web-react/src/scoped-slots.tsx
index 69d37f35b4..43b3c4cbae 100644
--- a/packages/client/web-react/src/scoped-slots.tsx
+++ b/packages/client/web-react/src/scoped-slots.tsx
@@ -650,7 +650,7 @@ function SlotOutlet({ slotKey, ownerProps, opts }: {
   const spec = host.specOf(slotKey)
   // Undeclared (or no-longer-declared) keys render empty: a declaring entry's
   // unload returns the slot to the undeclared state while retained elements
-  // may still be mounted — natural empty, not an ownership failure (§9).
+  // may still be mounted — natural empty, not an ownership failure.
   if (!spec) return null
   const strictSessionAbsent = spec.scope === 'session' && sessionInfo.sessionId === undefined
   if (strictSessionAbsent && (spec.kind !== 'chain' || !opts?.overlay)) {
@@ -776,7 +776,7 @@ function SlotOutlet({ slotKey, ownerProps, opts }: {
   return <>{list.map(item => guarded(item.entry, entryKeyOf(item.entry)))}</>
 }
 
-/** Root outlet: the shell's single ctx-level render entry — an unregistered 'root' is a boot-order failure, never a silent blank (§1). */
+/** Root outlet: the shell's single ctx-level render entry — an unregistered 'root' is a boot-order failure, never a silent blank. */
 function RootOutlet({ ownerProps }: { ownerProps: object }) {
   const host = useHost()
   useSyncExternalStore(
diff --git a/packages/client/web-react/src/session-provider.tsx b/packages/client/web-react/src/session-provider.tsx
index 865e4fc081..11a5d4404d 100644
--- a/packages/client/web-react/src/session-provider.tsx
+++ b/packages/client/web-react/src/session-provider.tsx
@@ -84,7 +84,7 @@ function useAbsentSnapshot<S>(_selector: (snapshot: never) => S, _equal?: (a: S,
 }
 
 /**
- * The useProjection framework seat (session-projection RFC), one bound
+ * The useProjection framework seat (docs/subsystems/session-projection.md), one bound
  * function per provide bundle (cached by info identity — components may hold
  * it across renders). Key-addressed: the key resolves a per-session value
  * face off the projection store; the bound selector hook comes from the same
diff --git a/packages/client/web-react/tests/scoped-slots.spec.tsx b/packages/client/web-react/tests/scoped-slots.spec.tsx
index 0688d409b9..ddaa5bec3b 100644
--- a/packages/client/web-react/tests/scoped-slots.spec.tsx
+++ b/packages/client/web-react/tests/scoped-slots.spec.tsx
@@ -135,8 +135,8 @@ function makeHost() {
     host,
     list,
     workspaces,
-    // Same driver surface as the old current cell: set(id) publishes the
-    // resolved bundle (or the absent projection) through the provide source.
+    // Driver surface: set(id) publishes the resolved bundle (or the absent
+    // projection) through the provide source.
     current: {
       set: (id: string | undefined) => {
         currentId = id
diff --git a/packages/client/web-react/tests/session-provider.spec.tsx b/packages/client/web-react/tests/session-provider.spec.tsx
index c1f1f648a2..248d4d17f5 100644
--- a/packages/client/web-react/tests/session-provider.spec.tsx
+++ b/packages/client/web-react/tests/session-provider.spec.tsx
@@ -57,8 +57,8 @@ function makeHost(bodies: { root: (rp: (key: string, owner: object) => React.Rea
   }
   return {
     host,
-    // Same driver surface as the old current cell: set(id) publishes the
-    // resolved bundle (or the absent projection) through the provide source.
+    // Driver surface: set(id) publishes the resolved bundle (or the absent
+    // projection) through the provide source.
     current: {
       set: (id: string | undefined) => {
         currentId = id
diff --git a/packages/client/web-react/tests/use-projection.spec.tsx b/packages/client/web-react/tests/use-projection.spec.tsx
index a10cf48989..15a63e9027 100644
--- a/packages/client/web-react/tests/use-projection.spec.tsx
+++ b/packages/client/web-react/tests/use-projection.spec.tsx
@@ -1,6 +1,7 @@
 // @vitest-environment jsdom
 /**
- * useProjection standard-kit delivery (session-projection RFC): the fifth
+ * useProjection standard-kit delivery (session-projection subsystem page:
+ * docs/subsystems/session-projection.md): the fifth
  * framework hook seat rides the same provide channel as useSession — a
  * session slot component receives `useProjection` in its kit, key-addressed
  * over the bundle's projection face; unresolved keys (no value, no face, no
diff --git a/packages/client/web/src/AppRoot.tsx b/packages/client/web/src/AppRoot.tsx
index 18cf06becb..d8ef311b38 100644
--- a/packages/client/web/src/AppRoot.tsx
+++ b/packages/client/web/src/AppRoot.tsx
@@ -3,7 +3,7 @@
  * Pure kernel component with zero plugin dependencies — before settled it may
  * only rely on itself (the fail-loud presentation must not depend on the
  * system whose failure it reports; the status/signal stores are kernel-own,
- * web2 shell self-sufficiency rule); the real UI is produced by the
+ * shell self-sufficiency rule); the real UI is produced by the
  * app-shell entry once every entry is active. A failed boot keeps the
  * loading page, lists the per-entry fiber states and the sweep report (fail
  * loud, no partial UI).
diff --git a/packages/client/web/src/boot.tsx b/packages/client/web/src/boot.tsx
index cf63247915..c1203929f9 100644
--- a/packages/client/web/src/boot.tsx
+++ b/packages/client/web/src/boot.tsx
@@ -1,15 +1,15 @@
 /**
  * Web shell boot kernel — the face consumed by the apps/web entry. Everything
  * here is machinery that cannot itself be a loader entry, and none of it
- * value-imports a plugin package (web2 shell self-sufficiency rule: the
+ * value-imports a plugin package (shell self-sufficiency rule: the
  * loading page must work while — especially when — plugins fail). The one
- * sanctioned exception is the modules package (design §4.7 bootstrap
+ * sanctioned exception is the modules package (bootstrap
  * identity): the module system cannot arrive through itself, so its class
  * and its client-half wrapper are shell-bundled and the kernel adopts its
  * plugin entry once cordis is up.
  *
  * AppWebEntry.run(), module face first, then plugin face: parse
- * `window.__DSH_BOOT__` into the two-view BootManifest (wire boundary, D16)
+ * `window.__DSH_BOOT__` into the two-view BootManifest (wire boundary)
  * → build the module system over the module-view rows → render the loading
  * page → prefetch every `immediately` row in parallel with mounting the
  * vendored cordis Loader (`internal` contract injection BEFORE any entry exists —
@@ -101,9 +101,9 @@ export class AppWebEntry {
       modules: this.manifest.modules, staticModules: getStaticModules(), ...this.seams,
     })
     // The app-shell assembly is the only shell-own module: every other graph
-    // row is a plugin bundle arriving through fetch (web2 single package form).
+    // row is a plugin bundle arriving through fetch.
     this.modules.registerStatic(APP_SHELL_ID, AppShell)
-    // Adoption handoff, supply side (design §4.7): register the modules
+    // Adoption handoff, supply side: register the modules
     // package's own client half under its bare package name (= graph row id
     // = entry name — a suffixed key would miss the statics branch and
     // trigger a real fetch), and put the instance on the kernel slot the
diff --git a/packages/client/web/src/index.ts b/packages/client/web/src/index.ts
index 3a9ccda2ba..ffa29a7b85 100644
--- a/packages/client/web/src/index.ts
+++ b/packages/client/web/src/index.ts
@@ -2,7 +2,7 @@
  * Web shell library entry. The shell's product is {@link AppWebEntry} —
  * apps/web's vite entry runs it against #root; everything else (AppRoot
  * gate, app-shell assembly entry, module-table staticModules, platform constants) is
- * internal to the boot chain. PLATFORM_MODULES is re-exported as the C1
+ * internal to the boot chain. PLATFORM_MODULES is re-exported as the
  * single source of truth for the tsdown client externals projection.
  * @module @deepseek-ai/dsh-client-web
  */
diff --git a/packages/client/web/src/loader-status.ts b/packages/client/web/src/loader-status.ts
index 37b5541798..03ac761afe 100644
--- a/packages/client/web/src/loader-status.ts
+++ b/packages/client/web/src/loader-status.ts
@@ -4,8 +4,8 @@
  * cordis fiber states (display the truth, not a retelling) — the boot chain
  * subscribes `internal/status` and recomputes one row per loader entry.
  *
- * The store is hand-rolled here because of the shell self-sufficiency rule
- * (web2 §0): the snapshot-store machinery lives in the runtime PLUGIN
+ * The store is hand-rolled here because of the shell self-sufficiency rule:
+ * the snapshot-store machinery lives in the runtime PLUGIN
  * package, and the shell kernel must not value-import any plugin package —
  * the loading page has to work while (and especially when) plugins fail.
  * @module @deepseek-ai/dsh-client-web/src/loader-status
diff --git a/packages/client/web/src/seed.ts b/packages/client/web/src/seed.ts
index 11f976f4db..fd5360f0f7 100644
--- a/packages/client/web/src/seed.ts
+++ b/packages/client/web/src/seed.ts
@@ -2,7 +2,7 @@
  * Platform-singleton module-table. These are the ONLY entities the shell
  * shares into the frozen module table — fetch bundles resolve their externals
  * against exactly this set through the loader's require. Keys come from the
- * platform constant module ({@link ./platform.ts}, contract C1: single source
+ * platform constant module ({@link ./platform.ts}, the single source
  * of truth with the tsdown client externals); values stay shell-static
  * imports so every bundle sees the same instance.
  */
diff --git a/packages/code-runtime/code-runtime/src/index.ts b/packages/code-runtime/code-runtime/src/index.ts
index a4edc604c8..9a7716aea0 100644
--- a/packages/code-runtime/code-runtime/src/index.ts
+++ b/packages/code-runtime/code-runtime/src/index.ts
@@ -21,8 +21,7 @@ export type {
  * Binding globals EVERY backend refuses because SOME backend owns the slot in
  * the program's namespace: `console` (the worker's log capture), and
  * `__dsh_main__`/`__builtins__`/`__name__` (the Python backend's bootstrap
- * wrapper and seeded module globals — that backend is a later PR in this
- * stack, see the [portable-identifier Agent
+ * wrapper and seeded module globals; see the [portable-identifier Agent
  * Note](../../../../.agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.md)),
  * and `__debug__`. One shared set — rather than each backend refusing only its
  * own slots — keeps the portability promise real: a namespace list valid on
@@ -68,12 +67,11 @@ export const DUNDER_MEMBER = /^__.+__$/
  * Reserved words of every portable target language (ECMAScript ∪ Python),
  * refused as {@link CodeBindingNamespace.global} / error-class names by all
  * backends. Python is a portability target here even though only the
- * TypeScript worker ships in this PR (the CPython backend is a later PR in the
- * stack). The portable-identifier contract promises a namespace list valid
- * on one backend is valid on every backend; a per-language check would let
- * `lambda` pass the TypeScript backend and fail the Python one. Extending the
- * seam with a new language means widening this union (a breaking review of
- * existing binding names, by design).
+ * TypeScript worker has a published backend. The portable-identifier contract
+ * promises a namespace list valid on one backend is valid on every backend; a
+ * per-language check would let `lambda` pass the TypeScript backend and fail
+ * the Python one. Extending the seam with a new language means widening this
+ * union (a breaking review of existing binding names, by design).
  */
 export const PORTABLE_RESERVED_WORDS: ReadonlySet<string> = new Set([
   // ECMAScript reserved words and reserved-in-strict-mode names.
diff --git a/packages/context/README.i18n.yaml b/packages/context/README.i18n.yaml
index b8025ef2bd..10e9ed6d7d 100644
--- a/packages/context/README.i18n.yaml
+++ b/packages/context/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/context/README.md
-README.md: 237f6191329f89834ec9bd9f72c0a1fd1d94651e
-README.zh.md: 653fd971a884e1b356e5a366d91f81caefd681c5
+README.md: 843f19b04c8dd63924a20d3ed01a5b179a731484
+README.zh.md: ac3233fa8d6ffee8f80cf485eaa87289260dc0f5
diff --git a/packages/context/README.md b/packages/context/README.md
index 237f619132..843f19b04c 100644
--- a/packages/context/README.md
+++ b/packages/context/README.md
@@ -11,6 +11,4 @@ Product plugins that add model-visible request context without defining a tool.
 | [`tmux-context/`](tmux-context/README.md) | tmux location context | — |
 | [`workspace-context/`](workspace-context/README.md) | Workspace-instruction context | — |
 
-The [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) explains its per-agent/session isolation and lifecycle split.
-
 Session references are documented in [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md); the [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) owns its per-agent/session isolation and lifecycle split.
diff --git a/packages/context/README.zh.md b/packages/context/README.zh.md
index 653fd971a8..ac3233fa8d 100644
--- a/packages/context/README.zh.md
+++ b/packages/context/README.zh.md
@@ -11,6 +11,4 @@
 | [`tmux-context/`](tmux-context/README.md) | tmux 位置上下文 | — |
 | [`workspace-context/`](workspace-context/README.md) | 工作区指令上下文 | — |
 
-[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)解释其逐 agent（智能体）／会话隔离和生命周期拆分。
-
-会话引用见 [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md)；[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)拥有其按 agent/会话隔离与生命周期拆分。
+会话引用见 [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md)；[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)拥有其按 agent（智能体）/会话隔离与生命周期拆分。
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 585397d861..ec4d7e138b 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -575,7 +575,7 @@ describe('workspace context instruction discovery', () => {
     const emptyHome = await tempRepo()
     // Isolate the default-home fallback: blank DSH_HOME is treated as unset, and
     // HOME points at an empty dir so the default ~/.dsh holds no global scope.
-    // Symlinks are now followed, so a real ~/.dsh/AGENTS.md would otherwise leak in.
+    // Symlinks are followed, so a real ~/.dsh/AGENTS.md would otherwise leak in.
     vi.stubEnv('DSH_HOME', '')
     vi.stubEnv('HOME', emptyHome)
     try {
diff --git a/packages/core/session/src/chunk-rows.ts b/packages/core/session/src/chunk-rows.ts
index 56de67b405..ef46e40dbb 100644
--- a/packages/core/session/src/chunk-rows.ts
+++ b/packages/core/session/src/chunk-rows.ts
@@ -331,8 +331,7 @@ function expandRow(row: ChunkRow): SessionEvent[] {
  * Decode one parsed JSONL line value into the session event(s) it stores.
  * Chunk-row-tagged values validate and expand (a malformed row throws — it is
  * corrupt storage, and treating it as an event would silently drop a whole
- * run); every other value passes through as a single event, unvalidated,
- * exactly as readers treated event lines before packing existed.
+ * run); every other value passes through as a single event, unvalidated.
  *
  * @param value - one line's `JSON.parse` result.
  * @returns the stored events, in log order.
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index 1c9a622643..6074b51c02 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -338,7 +338,8 @@ export type SurfaceEvent = SessionEvent<SurfaceEventType> & { surfaceOp: Surface
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
  *   surface nodes in the current surface. `start === end` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction and possible other manipulations.
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
  */
 export type SurfaceOp =
   | 'append'
diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts
index f5c5809544..4f094e4ade 100644
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -38,10 +38,10 @@ interface RunCodeFlavor {
 }
 
 /**
- * The TypeScript flavor: the historical default, and the fallback for a schema
- * read with no runtime mounted ({@link resolveFlavor} owns which readers reach
- * that). A real assembly always resolves a runtime first, so the model never
- * sees this fallback outside its own language.
+ * The TypeScript flavor: the fallback for a schema read with no runtime
+ * mounted ({@link resolveFlavor} owns which readers reach that). A real
+ * assembly always resolves a runtime first, so the model never sees this
+ * fallback outside its own language.
  */
 const TYPESCRIPT_FLAVOR: RunCodeFlavor = {
   description:
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 1a5f6a05eb..75c0751ad9 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -857,8 +857,8 @@ export class ToolRegistry extends Service {
    * bound to a request. Harmless while one published backend exists — both
    * reads return the same flavor — but a reload that swapped in a second
    * language between them would hand a program written against one SDK to the
-   * other. Binding it belongs to the PR that publishes that backend, which is
-   * also the first point it can be tested; recorded in the
+   * other. Binding it is deferred until a second backend ships (the first
+   * point it is testable); rationale in the
    * [language-dispatch note](../../../../.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md).
    */
   private requireCodeRuntime(): CodeRuntime {
diff --git a/packages/core/tools/src/py-types.ts b/packages/core/tools/src/py-types.ts
index 33c05db92e..ec9b0f2190 100644
--- a/packages/core/tools/src/py-types.ts
+++ b/packages/core/tools/src/py-types.ts
@@ -41,12 +41,12 @@ const IDENTIFIER = /^[\p{XID_Start}_]\p{XID_Continue}*$/u
  * that normalize together would collapse into one declaration. Those names
  * take the subscript path, which carries their exact bytes.
  *
- * `IDENTIFIER`'s equivalence to `str.isidentifier()` was measured across 21
- * samples with zero divergence, on Node 22.23.1 against CPython 3.9.6 — every
- * sample sits inside the two versions' shared tables, and the skew characters
- * below are exactly where that pair diverges. The predicate as a whole is
- * deliberately stricter than `isidentifier()`, which does not test NFKC
- * stability: `'field'.isidentifier()` is True and this returns false.
+ * `IDENTIFIER` is equivalent to `str.isidentifier()` on Node 22.23.1 vs
+ * CPython 3.9.6 tables: the equivalence holds inside the two versions' shared
+ * tables, and the skew characters below are exactly where that pair diverges.
+ * The predicate as a whole is deliberately stricter than `isidentifier()`,
+ * which does not test NFKC stability: `'field'.isidentifier()` is True and
+ * this returns false.
  *
  * Both conditions are evaluated against the ENGINE's Unicode tables, and the
  * two sides are versioned independently — `\p{XID_Start}`/`\p{XID_Continue}`
@@ -85,8 +85,8 @@ const IDENTIFIER = /^[\p{XID_Start}_]\p{XID_Continue}*$/u
  * here — and the declared `class \u{A7DC}Args` fails with `invalid
  * non-printable character U+A7DC`. Closing the exposure therefore covers all
  * four read points, not this predicate alone; it needs the target interpreter's
- * version, which the backend reporting `language: 'python'` owns and which is
- * unpublished on this base, so the note records it as that PR's decision.
+ * version, which the backend reporting `language: 'python'` owns; the
+ * language-dispatch Agent Note records the deferral.
  *
  * The `ts-types` sibling keeps its own ASCII rule rather than sharing this
  * one: ECMAScript identifiers are a different set (`$`) and are never
diff --git a/packages/credentials/credentials-local/src/index.ts b/packages/credentials/credentials-local/src/index.ts
index e781c10f3e..c95e0291e1 100644
--- a/packages/credentials/credentials-local/src/index.ts
+++ b/packages/credentials/credentials-local/src/index.ts
@@ -29,8 +29,9 @@
  * The document holds nothing but credentials, which is why it is a strict
  * `CredentialRef`-to-string mapping rather than a dotenv file: a store the
  * Harness owns and never materializes into the environment cannot also serve
- * as the user's environment layer, and conflating the two is what made a
- * non-secret in the old `$DSH_HOME/.env` silently unreachable.
+ * as the user's environment layer; a store that doubled as the environment
+ * layer would shadow non-secret entries behind its precedence, making them
+ * silently unreachable.
  * @module @deepseek-ai/dsh-credentials-local
  */
 
diff --git a/packages/credentials/credentials-local/tests/local.spec.ts b/packages/credentials/credentials-local/tests/local.spec.ts
index 43e42cd53f..26c917492f 100644
--- a/packages/credentials/credentials-local/tests/local.spec.ts
+++ b/packages/credentials/credentials-local/tests/local.spec.ts
@@ -130,8 +130,8 @@ describe('layer ladder', () => {
       { source: 'user-env', path: '/home/.dsh/.env', values: { DSH_CRED_TEST: 'older-user-env' } },
     ])
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'stored', source: 'file' })
-    // The old dead end is gone: a key sitting in the user's .env no longer
-    // makes the stored one unwritable.
+    // A key sitting in the user's .env does not make the stored one
+    // unwritable.
     expect(await ctx.credentials.describe(KEY)).toEqual({ configured: true, source: 'file', writable: true })
     await expect(ctx.credentials.set(KEY, 'rotated')).resolves.toBeUndefined()
     expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'rotated', source: 'file' })
diff --git a/packages/fs/README.i18n.yaml b/packages/fs/README.i18n.yaml
index edda1470df..7e78885c1e 100644
--- a/packages/fs/README.i18n.yaml
+++ b/packages/fs/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/fs/README.md
-README.md: fad17083817bd8023649ef7d0f0f1b62fbb9295f
-README.zh.md: e8544d71ee853547400e5970f0db9a9946562d48
+README.md: c48039f25ce234ce8b16d9829668224156855f31
+README.zh.md: 8cd7b703121d4a81fcb85b35beb89afd0cf2d7bd
diff --git a/packages/fs/README.md b/packages/fs/README.md
index fad1708381..c48039f25c 100644
--- a/packages/fs/README.md
+++ b/packages/fs/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The filesystem stack: a provider contract (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the bash-backed discovery tools. All **product** packages.
+The filesystem stack: a provider contract (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the ripgrep-backed discovery tools. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
@@ -12,12 +12,12 @@ The filesystem stack: a provider contract (execution-world paths, bounded text I
 | `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
 | `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
-| `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
+| `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools backed by the packaged `@vscode/ripgrep` binary spawned through `ctx.subprocess`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-The Service Definition lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the Service Definition, policy gate, or model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider contract: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+The Service Definition lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the Service Definition, policy gate, or model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider contract: search is a process-backed `rg` workflow (the packaged `@vscode/ripgrep` binary spawned through `ctx.subprocess`), so filesystem backends stay free of a universal search contract; its tools register unconditionally, and its results are follow-up-readable when the search workdir and the `read` root are the same workspace (the co-located deployment its README documents).
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs` and the provider contract arms no deadline: file IO here runs untimed because a deadline would kill work the OS will still finish — see [the filesystem subsystem page](../../docs/subsystems/filesystem.md). Cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
 
 The subsystem reference — targets, outcomes, guards, policy events, the error taxonomy, and why file IO takes no timeout — is [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md); the sandbox fence in the [cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md).
diff --git a/packages/fs/README.zh.md b/packages/fs/README.zh.md
index e8544d71ee..8cd7b70312 100644
--- a/packages/fs/README.zh.md
+++ b/packages/fs/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-文件系统栈包括：提供方约定（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品** 包。
+文件系统栈包括：提供方约定（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 ripgrep 的发现工具。全部都是**产品** 包。
 
 | 包 | 角色 | ctx 键 |
 |---|---|---|
@@ -12,12 +12,12 @@
 | `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
 | `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
 | `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
-| `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
+| `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具，由经 `ctx.subprocess` spawn 的打包 `@vscode/ripgrep` 二进制文件支持，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-Service Definition 位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方约定：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索约定；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+Service Definition 位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方约定：搜索是由进程支持的 `rg` 工作流（经 `ctx.subprocess` spawn 的打包 `@vscode/ripgrep` 二进制文件），因此文件系统后端无需承担通用搜索约定；其工具会无条件注册。如果搜索工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
 
 ## 文件 I/O 不设超时
 
-`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方约定也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
+`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方约定也不启动 deadline：这里的文件 I/O 不计时运行，因为 deadline 只会杀掉操作系统仍会完成的工作——参见[文件系统子系统页面](../../docs/subsystems/filesystem.md)。取消仍通过工具执行信号传播，在系统调用边界尽力中止。
 
 子系统参考——目标、结果、防护、策略事件、错误分类体系，以及文件 IO 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
diff --git a/packages/fs/fs/README.i18n.yaml b/packages/fs/fs/README.i18n.yaml
index dabdcacd3c..c13921729a 100644
--- a/packages/fs/fs/README.i18n.yaml
+++ b/packages/fs/fs/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/fs/fs/README.md
-README.md: 2b10614c8bf3d7e4a26c7f3d90dbc127cfec4336
-README.zh.md: e0cbf058bb8d6b52e8c8e5a048cc8b3d757e67d0
+README.md: 62d3febde82e013ace054a9e6242147c1756b0d1
+README.zh.md: 137c1e8da1014bf7dda7c4bf2e667aca6d2f51b5
diff --git a/packages/fs/fs/README.md b/packages/fs/fs/README.md
index 2b10614c8b..62d3febde8 100644
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -13,7 +13,7 @@ This package owns the Service Definition and provider contract layer of the four
 | provider contract | `@deepseek-ai/dsh-fs` (this) | `ctx.fs`: execution-world paths, text IO, and atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
 | provider | `@deepseek-ai/dsh-fs-local` | the host-filesystem implementation |
 
-A future sandboxed, virtual, or remote backend implements this interface and the policy/tool layers don't change.
+`fs-sandbox` and `fs-e2b` implement this interface without touching the policy/tool layers.
 
 ## Service API (`ctx.fs`)
 
diff --git a/packages/fs/fs/README.zh.md b/packages/fs/fs/README.zh.md
index e0cbf058bb..137c1e8da1 100644
--- a/packages/fs/fs/README.zh.md
+++ b/packages/fs/fs/README.zh.md
@@ -13,7 +13,7 @@
 | 提供方约定 | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
 | 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
 
-未来的沙箱化、虚拟或远程后端只需实现该接口，政策层和工具层无需改变。
+`fs-sandbox` 与 `fs-e2b` 实现该接口，无需更改政策层和工具层。
 
 ## 服务 API（`ctx.fs`）
 
diff --git a/packages/fs/tool-fs-search/README.i18n.yaml b/packages/fs/tool-fs-search/README.i18n.yaml
index a8fe6a80d7..44e161841d 100644
--- a/packages/fs/tool-fs-search/README.i18n.yaml
+++ b/packages/fs/tool-fs-search/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/fs/tool-fs-search/README.md
-README.md: 32fa61e3bb09b2166499003953a5631a93baf73b
-README.zh.md: 34ffcdc9f64daba7350e4581b35e694213f24214
+README.md: 7803ce52c1b9d2d858dadb718edd163585360aef
+README.zh.md: 3a34f4e8a04666b72f09eca1b41fea825d5a609f
diff --git a/packages/fs/tool-fs-search/README.md b/packages/fs/tool-fs-search/README.md
index 32fa61e3bb..7803ce52c1 100644
--- a/packages/fs/tool-fs-search/README.md
+++ b/packages/fs/tool-fs-search/README.md
@@ -16,7 +16,7 @@ Why spawn-backed: local workspace discovery is naturally a process-backed `rg` w
 
 ## Deployment requirement: no host rg, co-located workdir/filesystem
 
-The binary ships with the package on every supported platform (macOS/Linux/Windows, x64/arm64), so no host `rg` install is required and the tools register on every deployment. Returned paths are displayed relative to the resolved workdir (the calling agent's session cwd when present, else `process.cwd()`) and are follow-up-readable with `read` only when that workdir and the filesystem root are the same workspace. v1 documents that co-location requirement and performs no runtime cross-service validation; remote or virtual filesystem search waits for a shared workspace contract or a provider-specific search backend.
+The binary ships with the package on every supported platform (macOS/Linux/Windows, x64/arm64), so no host `rg` install is required and the tools register on every deployment. Returned paths are displayed relative to the resolved workdir (the calling agent's session cwd when present, else `process.cwd()`) and are follow-up-readable with `read` only when that workdir and the filesystem root are the same workspace. That co-location requirement carries no runtime cross-service validation; remote or virtual filesystem search waits for a shared workspace contract or a provider-specific search backend.
 
 ## Config
 
diff --git a/packages/fs/tool-fs-search/README.zh.md b/packages/fs/tool-fs-search/README.zh.md
index 34ffcdc9f6..3a34f4e8a0 100644
--- a/packages/fs/tool-fs-search/README.zh.md
+++ b/packages/fs/tool-fs-search/README.zh.md
@@ -16,7 +16,7 @@ await ctx.plugin(LocalSpillStore)                           // @deepseek-ai/dsh-
 
 ## 部署要求：无需宿主 rg，但工作目录与文件系统需共置
 
-二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。v1 只记录这项共置要求，不执行运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区约定或特定提供方的搜索后端。
+二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。这项共置要求不附带运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区约定或特定提供方的搜索后端。
 
 ## 配置
 
diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml
index a301417b4b..96785be516 100644
--- a/packages/fs/tool-fs/README.i18n.yaml
+++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md
-README.md: 6878584b72c3e799ca8a46ddc6fc2908f9bc3acf
-README.zh.md: d8e92d96c60d30ec4aa943b77b882517324c4e52
+README.md: 27b53aca50f470fe9ead4da27d87328264440ff7
+README.zh.md: 5bcf9c471d933702c46d50c56c9539cb9eede3ca
diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md
index 6878584b72..27b53aca50 100644
--- a/packages/fs/tool-fs/README.md
+++ b/packages/fs/tool-fs/README.md
@@ -148,6 +148,6 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies bash-backed `glob` and `grep` rather than extending the filesystem seam.
+- **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies ripgrep-backed `glob` and `grep` rather than extending the filesystem seam.
 - **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`.
 - **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only ([provider rationale](../README.md#no-timeouts-on-file-io)).
diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md
index d8e92d96c6..5bcf9c471d 100644
--- a/packages/fs/tool-fs/README.zh.md
+++ b/packages/fs/tool-fs/README.zh.md
@@ -148,6 +148,6 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 ## 已知限制与暂缓事项
 
-- **未交付面向模型的目录列表工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 [`dsh-tool-fs-search`](../tool-fs-search/) 包则提供基于 bash 的 `glob` 与 `grep`，而不是扩展文件系统 seam。
+- **未交付面向模型的目录列表工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 [`dsh-tool-fs-search`](../tool-fs-search/) 包则提供基于 ripgrep 的 `glob` 与 `grep`，而不是扩展文件系统 seam。
 - **`read` 只处理 UTF-8 文本文件**：二进制安全读取和 PDF/图像/多模态内容均延期处理；目录目标为 `FS_NOT_REGULAR_FILE`。
 - **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明 `timeout-policy` 预算；取消只通过 `exec.signal` 传递（见[提供方理由](../README.md#no-timeouts-on-file-io)）。
diff --git a/packages/goal/goal/src/domain.ts b/packages/goal/goal/src/domain.ts
index 90f22a1602..3dc5672f0b 100644
--- a/packages/goal/goal/src/domain.ts
+++ b/packages/goal/goal/src/domain.ts
@@ -1,9 +1,9 @@
 /**
  * Host-side vocabulary of the goal domain: live views, durable change
  * payloads, message attribution, replay folds, and the scoped `goal/changed`
- * event. Split from ./types.ts (the pure client-safe outlet) because these
- * declarations pull dsh-agent, dsh-llm, and cordis into the program — the
- * one-program-per-side layout forbids that on client aggregates.
+ * event. Kept separate from ./types.ts (the pure client-safe outlet) because
+ * these declarations pull dsh-agent, dsh-llm, and cordis into the program —
+ * the one-program-per-side layout forbids that on client aggregates.
  * @module @deepseek-ai/dsh-goal
  */
 
diff --git a/packages/guard/timeout-policy/README.i18n.yaml b/packages/guard/timeout-policy/README.i18n.yaml
index 3c41810118..f3014395b4 100644
--- a/packages/guard/timeout-policy/README.i18n.yaml
+++ b/packages/guard/timeout-policy/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/guard/timeout-policy/README.md
-README.md: 3e5769e2f8b95392e9d489659c6bae634ab3ff18
-README.zh.md: bfba62cdfae8bb956aec43bcf6e8df12407d8ba2
+README.md: 70b1f392bfbce91962447dee86afbbb148817811
+README.zh.md: e285caa5f7b123d02979e404125bce20932f9223
diff --git a/packages/guard/timeout-policy/README.md b/packages/guard/timeout-policy/README.md
index 3e5769e2f8..70b1f392bf 100644
--- a/packages/guard/timeout-policy/README.md
+++ b/packages/guard/timeout-policy/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Tool-call timeout enforcer: a single `tools/execute` around-dispatch listener that arms a per-call cooperative deadline on `exec.signal` for a tool declaring `timeoutMs` on its `ToolDefinition` and returns a structured `TOOL_TIMEOUT` result when that deadline wins. The budget is read from the tool's own declaration (`ToolDefinition.timeoutMs`, set by the owning tool plugin), so this plugin is **zero-config**. It is the reference `tools/execute` wrapper and the enforcement home for model-facing tool-call budgets (the timeout-library Agent Note's foreseen middleware).
+Tool-call timeout enforcer: a single `tools/execute` around-dispatch listener that arms a per-call cooperative deadline on `exec.signal` for a tool declaring `timeoutMs` on its `ToolDefinition` and returns a structured `TOOL_TIMEOUT` result when that deadline wins. The budget is read from the tool's own declaration (`ToolDefinition.timeoutMs`, set by the owning tool plugin), so this plugin is **zero-config**. It is the reference `tools/execute` wrapper and the enforcement home for model-facing tool-call budgets ([timeout-library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
 
 ## Plugin (namespace: `timeout-policy`)
 
diff --git a/packages/guard/timeout-policy/README.zh.md b/packages/guard/timeout-policy/README.zh.md
index bfba62cdfa..e285caa5f7 100644
--- a/packages/guard/timeout-policy/README.zh.md
+++ b/packages/guard/timeout-policy/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-工具调用超时强制执行器：单个 `tools/execute` 环绕分发监听器，会在 `exec.signal` 上设置单次调用的协作式截止时间；适用于声明了 `timeoutMs` 且声明位于其 `ToolDefinition` 上的工具。该截止时间先到时，它返回结构化 `TOOL_TIMEOUT` 结果。预算从工具自身的声明中读取（`ToolDefinition.timeoutMs`，由拥有该工具的插件设置），因此此插件是**零配置**的。它是 `tools/execute` 包装层的参考实现，也是面向模型工具调用预算的强制执行归属地（超时库 Agent Note 所预见的中间件）。
+工具调用超时强制执行器：单个 `tools/execute` 环绕分发监听器，会在 `exec.signal` 上设置单次调用的协作式截止时间；适用于声明了 `timeoutMs` 且声明位于其 `ToolDefinition` 上的工具。该截止时间先到时，它返回结构化 `TOOL_TIMEOUT` 结果。预算从工具自身的声明中读取（`ToolDefinition.timeoutMs`，由拥有该工具的插件设置），因此此插件是**零配置**的。它是 `tools/execute` 包装层的参考实现，也是面向模型工具调用预算的强制执行归属地（[超时库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。
 
 ## 插件（命名空间：`timeout-policy`）
 
diff --git a/packages/hooks/hook-protocol/README.i18n.yaml b/packages/hooks/hook-protocol/README.i18n.yaml
index 61361487ba..0a60223517 100644
--- a/packages/hooks/hook-protocol/README.i18n.yaml
+++ b/packages/hooks/hook-protocol/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/hooks/hook-protocol/README.md
-README.md: 230f14c2bc053555991e5fb96e2753aef5bbff8a
-README.zh.md: d83ea99065123c9cf0f85c0abbbeeff6eadb17bc
+README.md: b2570ba8f2ab5dfb468b7d7fa3cc1270cefcbbb1
+README.zh.md: 3bd229a5d469db4a6f1e18b09df62fb8e1204747
diff --git a/packages/hooks/hook-protocol/README.md b/packages/hooks/hook-protocol/README.md
index 230f14c2bc..b2570ba8f2 100644
--- a/packages/hooks/hook-protocol/README.md
+++ b/packages/hooks/hook-protocol/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 The **shared core** of the Claude Code / Codex hook wire protocol. NOT a cordis plugin — it registers nothing and injects nothing. It is a **library** of dialect-neutral primitives the two bridge plugins (`@deepseek-ai/dsh-hooks-claude`, `@deepseek-ai/dsh-hooks-codex`) import so neither re-implements the identical halves of the protocol.
 
-Why a shared lib at all: Codex deliberately reimplements a *subset* of the Claude Code hook protocol — the same `hooks.json` matcher-group shape, the same exit-code/stdout output contract, the same command-hook execution model. The genuinely-shared parts live here; each bridge owns only what differs.
+Codex deliberately reimplements a *subset* of the Claude Code hook protocol — the same `hooks.json` matcher-group shape, the same exit-code/stdout output contract, the same command-hook execution model. The genuinely-shared parts live here; each bridge owns only what differs.
 
 ## What's shared (here) vs. per-dialect (the bridges)
 
diff --git a/packages/hooks/hook-protocol/README.zh.md b/packages/hooks/hook-protocol/README.zh.md
index d83ea99065..3bd229a5d4 100644
--- a/packages/hooks/hook-protocol/README.zh.md
+++ b/packages/hooks/hook-protocol/README.zh.md
@@ -4,7 +4,7 @@
 
 Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它不是 Cordis 插件：不注册也不注入任何内容。它是一个**库**，提供两个桥接插件（`@deepseek-ai/dsh-hooks-claude`、`@deepseek-ai/dsh-hooks-codex`）导入的方言无关原语，使两者都无需重复实现协议中相同的部分。
 
-共享 lib 存在的原因是：Codex 有意重新实现了 Claude Code hook 协议的一个*子集*，包括相同的 `hooks.json` matcher group 结构、相同的退出码／stdout 输出约定以及相同的 command hook 执行模式。真正共享的部分位于此处；每个桥接只负责不同的部分。
+Codex 有意重新实现了 Claude Code hook 协议的一个*子集*，包括相同的 `hooks.json` matcher group 结构、相同的退出码／stdout 输出约定以及相同的 command hook 执行模式。真正共享的部分位于此处；每个桥接只负责不同的部分。
 
 ## 共享内容（此处）与各方言内容（桥接）
 
diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts
index 39802d0b6c..b60ce7b520 100644
--- a/packages/hooks/hooks-claude/src/index.ts
+++ b/packages/hooks/hooks-claude/src/index.ts
@@ -48,7 +48,7 @@ export interface Config {
    * Process-level: read once at load, a relative path resolves against the process
    * launch cwd, so one config applies to the whole process.
    * TODO(per-session-hook-config): per-session discovery of a project-local
-   * `hooks.json` from each `session/new.cwd` is not yet implemented.
+   * `hooks.json` from each `session/new.cwd`.
    */
   configPath: string
   /**
diff --git a/packages/hooks/hooks-codex/README.i18n.yaml b/packages/hooks/hooks-codex/README.i18n.yaml
index 4af0518ab2..da27f59159 100644
--- a/packages/hooks/hooks-codex/README.i18n.yaml
+++ b/packages/hooks/hooks-codex/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/hooks/hooks-codex/README.md
-README.md: f8e0684e0bf4eafadcb31d8c82dde177411db2bf
-README.zh.md: d278e78204c1bd320980420b506135997cd3a4cc
+README.md: 0a4f918acd960ae63bd131d11f77e8ab52f9ca47
+README.zh.md: 044a9c6e661045e4b152f4200f0f843b47faef34
diff --git a/packages/hooks/hooks-codex/README.md b/packages/hooks/hooks-codex/README.md
index f8e0684e0b..0a4f918acd 100644
--- a/packages/hooks/hooks-codex/README.md
+++ b/packages/hooks/hooks-codex/README.md
@@ -96,5 +96,5 @@ A blocked prompt sends no request and invalidates nothing. Denial, feedback, and
 - **`PreToolUse` is partial:** blocking works, but `additionalContext`, `permissionDecision: "allow"`, and `updatedInput` are ignored. Every tool is represented as `tool_input: { command }`, so non-shell tool arguments are not faithfully exposed to the hook.
 - **`PostToolUse` is partial:** blocking feedback and JSON `additionalContext` work, but `{"continue": false}` is not enforced, non-shell tool arguments are reduced to `{ command }`, and structured tool output is flattened to text in `tool_response`.
 - **`Stop` is partial:** blocking forces another model turn, but `stop_hook_active` is always `false`, `last_assistant_message` is always `null`, and `{"continue": false}` is not enforced. An unconditionally blocking hook therefore force-continues every step unless it self-limits (`TODO(stop-loop-guard)`).
-- **Common payload and output fields are partial:** every mapped event reports `transcript_path: null`, the statically configured `model`, and `permission_mode: "default"` instead of current Codex runtime values. `systemMessage` is logged + warned but not surfaced, and `{"continue": false}` is recorded but does not apply Codex's event-specific stop behavior (`TODO(hook-continue-false)`).
+- **Common payload and output fields are partial:** every mapped event reports the statically configured `model` and `permission_mode: "default"` instead of current Codex runtime values. `systemMessage` is logged + warned but not surfaced, and `{"continue": false}` is recorded but does not apply Codex's event-specific stop behavior (`TODO(hook-continue-false)`).
 - **Config loading and execution are partial:** one process-level `configPath` is parsed at load; Codex's active user, project, session, system/managed, and plugin layers, trust controls, and inline `config.toml` hook form are not implemented (`TODO(per-session-hook-config)`). Only synchronous `command` handlers run, current metadata such as `statusMessage` and `commandWindows` is ignored, and matching handlers run serially rather than with Codex's concurrent launch semantics.
diff --git a/packages/hooks/hooks-codex/README.zh.md b/packages/hooks/hooks-codex/README.zh.md
index d278e78204..044a9c6e66 100644
--- a/packages/hooks/hooks-codex/README.zh.md
+++ b/packages/hooks/hooks-codex/README.zh.md
@@ -96,5 +96,5 @@ hook 不返回上下文时没有成本。Hook 文本取决于数据，会被记
 - **`PreToolUse` 只支持部分功能：** 支持阻塞，但会忽略 `additionalContext`、`permissionDecision: "allow"` 和 `updatedInput`。每个工具都表示为 `tool_input: { command }`，因此非 shell 工具参数不会如实公开给 hook。
 - **`PostToolUse` 只支持部分功能：** 支持阻塞反馈与 JSON `additionalContext`，但不会强制执行 `{"continue": false}`，非 shell 工具参数会缩减为 `{ command }`，结构化工具输出会在 `tool_response` 中展平为文本。
 - **`Stop` 只支持部分功能：** 阻塞会强制另一个模型轮次，但 `stop_hook_active` 始终为 `false`，`last_assistant_message` 始终为 `null`，且不会强制执行 `{"continue": false}`。因此，无条件阻塞 hook 会在每个步骤中强制 continuation，除非它自我限制（`TODO(stop-loop-guard)`）。
-- **通用 payload 与输出字段只支持部分功能：** 每个已映射事件都报告 `transcript_path: null`、静态配置的 `model` 与 `permission_mode: "default"`，而非当前 Codex 运行时值。`systemMessage` 会被记录并触发警告，但不呈现，`{"continue": false}` 会被记录但不会应用 Codex 事件特定停止行为（`TODO(hook-continue-false)`）。
+- **通用 payload 与输出字段只支持部分功能：** 每个已映射事件都报告静态配置的 `model` 与 `permission_mode: "default"`，而非当前 Codex 运行时值。`systemMessage` 会被记录并触发警告，但不呈现，`{"continue": false}` 会被记录但不会应用 Codex 事件特定停止行为（`TODO(hook-continue-false)`）。
 - **配置加载与执行只支持部分功能：** 一个进程级 `configPath` 会在加载时解析；尚未实现 Codex 的活动用户层、项目层、会话层、系统／托管层和插件层、信任控制与内联 `config.toml` hook 形式（`TODO(per-session-hook-config)`）。只运行同步 `command` handler，忽略 `statusMessage` 与 `commandWindows` 等当前元数据，匹配 handler 串行运行，而非使用 Codex 的并发启动语义。
diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts
index 34f47f5a7e..d31d9f8c48 100644
--- a/packages/hooks/hooks-codex/src/index.ts
+++ b/packages/hooks/hooks-codex/src/index.ts
@@ -46,7 +46,7 @@ export interface Config {
    * Path to a Codex `hooks.json`. Process-level: read once at load, a relative
    * path resolves against the process launch cwd.
    * TODO(per-session-hook-config): per-session project-local discovery from each
-   * `session/new.cwd` is not yet implemented.
+   * `session/new.cwd`.
    */
   configPath: string
   /** The model name stamped on every payload (Codex includes `model` on each event). */
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 3069ec7948..e6ea7dd50d 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 9b430fca1c2352334e6428eb37b80726a4e02c02
-README.zh.md: c36a88b44348d0054e71ea9d796291b91fadbf20
+README.md: 44b8ee76b0da67ef1aaf24fb3d54e91d20fc064a
+README.zh.md: 06b05aa64727c8bce08c7935040a1766f30b98ed
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 9b430fca1c..44b8ee76b0 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -28,7 +28,7 @@ Question responses are validated against their pending request before the first
 
 `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
 
-Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`.
+Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key. Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`.
 
 `session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged `ModelSelection`, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index c36a88b443..06b05aa647 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -28,7 +28,7 @@ Settings 分节中的 `reasoningEffort` 在 agent-default-model 插件配置中
 
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
-会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。
+会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。
 
 `session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的 `ModelSelection` 及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。
 
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index d0f3698328..e417ca12b2 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -1421,8 +1421,8 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     sessions: {
       // Attached sessions summarize from memory; persisted-but-unattached (cold)
       // sessions merge in from the persistence store so history survives restarts.
-      // Legacy logs without a cwd (pre-project stance) are not served — every
-      // session now records its project at create time.
+      // Logs without a cwd are not served; every session records its project
+      // at create time.
       async list(request) {
         return ok(request, { items: await listVisibleSessionSummaries() })
       },
@@ -2184,7 +2184,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
 
     host: {
       describe(request) {
-        // TODO(step2): version should read apps/cli's package.json; placeholder for now.
+        // TODO: version should read apps/cli's package.json; placeholder for now.
         const selection = defaults.defaultModelSelection()
         return Promise.resolve(ok(request, {
           version: '0.0.1',
diff --git a/packages/host/apiproxy/src/index.ts b/packages/host/apiproxy/src/index.ts
index 667e85bdac..8004f952e4 100644
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -88,8 +88,8 @@ export class ApiProxyService extends Service implements ApiProxy {
     this.credentials = api.credentials
     this.llm = api.llm
     this.events = api.events
-    // createApiProxy returns closures (no `this` capture); bind only satisfies
-    // the unbound-method lint without changing behavior.
+    // createApiProxy returns closures (no `this` capture), so the bind is
+    // behavior-neutral.
     this.respond = api.respond.bind(api)
   }
 }
diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
index 4449df15f6..37e0e14169 100644
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -365,10 +365,10 @@ describe('subagent ownership fence', () => {
       inspect: () => Promise.resolve({ meta, events }),
       locate: () => undefined,
     } as never)
-    // Pre-#1569 stores classify a child only through the descriptor event and
-    // carry no header `origin`; the pre-release decision stops recognizing
-    // them, so the ownership fence lets generic resume reach the registry
-    // instead of answering `agent-busy`.
+    // Stores whose headers predate `origin` classify a child only through the
+    // descriptor event; the pre-release decision stops recognizing them, so
+    // the ownership fence lets generic resume reach the registry instead of
+    // answering `agent-busy`.
     const resume = vi.spyOn(ctx.agents, 'resume')
       .mockRejectedValue(new Error('registry unavailable in this bench'))
     const api = createApiProxy(ctx, { defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
diff --git a/packages/host/apiproxy/tests/api-proxy-config.spec.ts b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
index 13968616b8..c6cdc237b4 100644
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -367,9 +367,10 @@ describe('settings domain', () => {
 
   it('invalidates the model catalog when a provider namespace changes, and broadcasts a raw-only change', async () => {
     // Editing `models` changes no route, so llm/adapters-updated never fires
-    // and an open model picker kept serving the old catalog. And storing an
-    // override equal to the resolved value emits nothing on settings/updated,
-    // so another tab never learned the field became overridden.
+    // and an open model picker would keep serving the stale catalog. Storing
+    // an override equal to the resolved value emits nothing on
+    // settings/updated, so another tab would never learn the field became
+    // overridden.
     const ctx = await harness()
     ctx.settings.register(NS, AdapterConfig, { base: { baseURL: 'https://base' } })
     const api = createApiProxy(ctx, DEFAULTS)
diff --git a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx
index fc6dde82f1..222bcbe079 100644
--- a/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx
+++ b/packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx
@@ -773,8 +773,7 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
         onKeyDown={(event) => {
           if (event.key !== 'Escape' || pathDraft === null) return
           // stopPropagation keeps the card-scope Escape from the Modal's
-          // document listener — the same containment the input previously
-          // provided for itself.
+          // document listener.
           event.stopPropagation()
           // Escape while the input holds focus is about to unmount it; with
           // focus already parked on a row, that row survives the cancel and
diff --git a/packages/host/directory-picker-native/src/native-picker.ts b/packages/host/directory-picker-native/src/native-picker.ts
index 576353ea8c..45a62a72e5 100644
--- a/packages/host/directory-picker-native/src/native-picker.ts
+++ b/packages/host/directory-picker-native/src/native-picker.ts
@@ -70,8 +70,8 @@ export async function pickNativeDirectory(
     // The koffi-backed IFileOpenDialog child process — the modern picker with
     // per-monitor-v2 DPI and abort support. koffi is a packaged dependency
     // whose availability the install guarantees, so there is no fallback
-    // tier: any failure surfaces as-is (the former PowerShell chain was
-    // removed — see the simplification Agent Note).
+    // tier: any failure surfaces as-is (no PowerShell fallback tier; see
+    // the simplification Agent Note).
     const pickDialog = internals.pickWin32Dialog ?? pickWin32Directory
     return await pickDialog(signal)
   }
diff --git a/packages/interaction/user-approval/src/index.ts b/packages/interaction/user-approval/src/index.ts
index 70eacaa627..f0b63080ed 100644
--- a/packages/interaction/user-approval/src/index.ts
+++ b/packages/interaction/user-approval/src/index.ts
@@ -86,8 +86,7 @@ const OUTCOMES: readonly ApprovalOutcome[] = ['allowed-once', 'rejected', 'cance
  * ask BEFORE any interactive answerer sees it:
  *
  * - `'ask'` (the default) — delegate to the composed answerers; with none
- *   composed the chain falls through to the fail-closed `'unavailable'`
- *   (exactly today's behavior).
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
  * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
  *   deterministically. The strict headless stance (CI, unattended runs) and
  *   the policy whose outcome is knowable without asking.
diff --git a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
index a7e1f433e5..340bed3ee9 100644
--- a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
@@ -132,7 +132,7 @@ describe('llm-deepseek real dynamic composition', () => {
   })
 
   it('keeps a stored key writable and rotatable across a real restart', async () => {
-    // No ambient DEEPSEEK_API_KEY: the shipped surfaces no longer hoist
+    // No ambient DEEPSEEK_API_KEY: the shipped surfaces do not hoist
     // the credentials document into process.env, so a stored key must stay file-sourced.
     vi.stubEnv('DEEPSEEK_API_KEY', '')
     const first = await mockServer([{ kind: 'sse', events: textEvents }])
diff --git a/packages/llm/llm-pi-ai/src/catalog.ts b/packages/llm/llm-pi-ai/src/catalog.ts
index 8f1bc1a43c..4e0cf3c092 100644
--- a/packages/llm/llm-pi-ai/src/catalog.ts
+++ b/packages/llm/llm-pi-ai/src/catalog.ts
@@ -62,8 +62,7 @@ type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>
 
 /**
  * pi-ai thinking formats a profile cannot name: both drive the request through
- * `chatTemplateKwargs`, which this configuration does not expose, so offering
- * them would hand back a format with nothing to say.
+ * `chatTemplateKwargs`, which this configuration does not expose.
  */
 type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
 
@@ -467,10 +466,8 @@ export function resolveRouteModels(request: RouteCatalogRequest): RouteCatalog {
       // The installed entry lays the floor, and the fields below override it.
       // Enumerating instead would silently drop every `Model` field this
       // package does not model — reasoning-level spellings, compatibility
-      // quirks, model headers, and whatever a pi-ai upgrade adds next. That is
-      // not hypothetical: `headers` reached this file only after an nvidia
-      // route lost it, and a rebuild keeps re-earning that bug on every
-      // upgrade.
+      // quirks, model headers, and whatever a pi-ai upgrade adds next. Spread,
+      // never enumerate.
       ...base,
       id: entry.id,
       name: entry.name ?? base?.name ?? entry.id,
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 2c5cb7bb48..6f49c1d76f 100644
--- a/packages/llm/llm/README.i18n.yaml
+++ b/packages/llm/llm/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/llm/llm/README.md
-README.md: 0b463c73175e46d20e9c8f719b55b3fa4f56fde2
-README.zh.md: cbabeb72216e9fc92b74d6c216d7f7b7154bc1a8
+README.md: c74dd5705ab67d5bf4bf966cfb9004e6ae1cc3d7
+README.zh.md: 17a0fd92b48db3ea5122ac2f1c1ed6e116e6d6e0
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index 0b463c7317..c74dd5705a 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -26,7 +26,7 @@ An adapter registry plus a single streaming call surface, interceptable via a wa
 
 `LlmService` normalizes failures from final adapter selection, synchronous dispatch, iterator construction, and iteration into the stream protocol's single terminal form: `finish { kind: 'error' | 'aborted', failure }`. A failure after partial deltas may leave content blocks open; consumers discard that incomplete output. Errors from `llm/stream` middleware, nested calls, adapter cleanup, and downstream consumers remain thrown because they are plugin or consumer failures rather than model-request outcomes. A prepared call exposes the immutable retry policy captured with its exact adapter registration; a route handled entirely by middleware has no serving policy.
 
-Interrogating an endpoint is configuration-time work over a *draft*, which is why it is keyed by settings namespace rather than by provider route: the provider a surface is adding does not exist yet, so there is no route to name. The request may still *name* a route it is editing, and an adapter that already describes that route should answer from its own knowledge — better metadata, no network call — which is why `baseURL` is optional and one of the two is required. The request otherwise carries the endpoint, the protocol, and a credential the harness uses for that one interrogation and never stores — nothing here reads or writes settings or credentials, and the reply is candidate metadata a surface may offer for adoption, never a registered catalog. `LlmDiscoveredModel` makes every field but `id` optional because most provider listings disclose an id and nothing else; a surface adopting one still owes the capacities its adapter requires. Duplicate and unusable ids are dropped, an unserved namespace fails with `NO_DISCOVERY`, and a request naming neither a route nor an endpoint fails with `INVALID_DISCOVERY`.
+Interrogating an endpoint is configuration-time work over a *draft*, keyed by settings namespace rather than by provider route — the provider a surface is adding does not exist yet, so there is no route to name. The request may still *name* a route it is editing, and an adapter that already describes that route answers from its own knowledge without a network call; `baseURL` is optional and one of the two is required. The request otherwise carries the endpoint, the protocol, and a credential the harness uses for that one interrogation and never stores — nothing here reads or writes settings or credentials, and the reply is candidate metadata a surface may offer for adoption, never a registered catalog. `LlmDiscoveredModel` makes every field but `id` optional because most provider listings disclose an id and nothing else; a surface adopting one still owes the capacities its adapter requires. Duplicate and unusable ids are dropped, an unserved namespace fails with `NO_DISCOVERY`, and a request naming neither a route nor an endpoint fails with `INVALID_DISCOVERY`.
 
 Provider and model metadata is a discovery surface, not a routing whitelist. `registerAdapter()` still owns provider exclusivity and captures the adapter's retry policy for each route, while an adapter may accept model ids absent from `listModels()`; consumers must not reject a request because its model is unlisted. Returned selector metadata is detached and invalid or duplicate adapter entries fail with `INVALID_ADAPTER` or `INVALID_CATALOG`.
 
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index cbabeb7221..17a0fd92b4 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -26,7 +26,7 @@
 
 `LlmService` 将最终适配器选择、同步 dispatch、iterator 构造与迭代中的失败规范化为流协议唯一的终止形式：`finish { kind: 'error' | 'aborted', failure }`。部分增量输出后发生失败时，内容块可能仍未闭合；消费方会丢弃这些不完整输出。`llm/stream` middleware、嵌套调用、适配器清理和下游消费方的错误仍会抛出，因为它们属于插件或消费方失败，而非模型请求结果。已准备调用会暴露随其确切适配器注册一同捕获的不可变重试策略；完全由 middleware 处理的路由没有服务策略。
 
-询问端点属于配置期针对**草稿**的操作，因此以 settings namespace 而非提供方路由为键：界面正在新增的提供方还不存在，也就没有路由可点名。但请求仍可**点名**它正在编辑的路由，而已经描述该路由的适配器应当用自己的知识作答——元数据更好，且无需联网——这正是 `baseURL` 可选、两者至少要有一个的原因。除此之外，请求携带端点、协议，以及一条 harness 只用于这一次询问、绝不存储的凭据——这里既不读也不写 settings 与 credentials，回复是界面可供用户采纳的候选元数据，而不是已注册的 catalog。`LlmDiscoveredModel` 除 `id` 外每个字段都是可选的，因为大多数提供方列表只公布 id；采纳其中一条的界面仍要补上其适配器所需的容量。重复与不可用的 id 会被丢弃，无人服务的 namespace 以 `NO_DISCOVERY` 失败，既不点名路由也不给端点的请求以 `INVALID_DISCOVERY` 失败。
+询问端点属于配置期针对**草稿**的操作，以 settings namespace 而非提供方路由为键——界面正在新增的提供方还不存在，也就没有路由可点名。但请求仍可**点名**它正在编辑的路由，而已经描述该路由的适配器会用自己的知识作答，无需联网；`baseURL` 可选，两者至少要有一个。除此之外，请求携带端点、协议，以及一条 harness 只用于这一次询问、绝不存储的凭据——这里既不读也不写 settings 与 credentials，回复是界面可供用户采纳的候选元数据，而不是已注册的 catalog。`LlmDiscoveredModel` 除 `id` 外每个字段都是可选的，因为大多数提供方列表只公布 id；采纳其中一条的界面仍要补上其适配器所需的容量。重复与不可用的 id 会被丢弃，无人服务的 namespace 以 `NO_DISCOVERY` 失败，既不点名路由也不给端点的请求以 `INVALID_DISCOVERY` 失败。
 
 提供方与模型元数据是发现接口，不是路由白名单。`registerAdapter()` 仍拥有提供方排他性，并为每条路由捕获适配器的重试策略；适配器则可以接受 `listModels()` 中不存在的模型 id，消费方禁止因模型未列出而拒绝请求。返回的 selector 元数据与输入脱离，无效或重复适配器配置项会以 `INVALID_ADAPTER` 或 `INVALID_CATALOG` 失败。
 
diff --git a/packages/llm/llm/src/message.ts b/packages/llm/llm/src/message.ts
index c4032f5294..2673072fa0 100644
--- a/packages/llm/llm/src/message.ts
+++ b/packages/llm/llm/src/message.ts
@@ -35,8 +35,8 @@ export interface ToolMessageSource {
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several
- * producers share one form (three snapshot producers today), and one producer
- * may emit more than one form over a session.
+ * producers share one form, and one producer may emit more than one form over
+ * a session.
  *
  * The vocabulary is SEMANTIC, never visual: a value states that the content is
  * a file's instructions or a catalog of available items, and a consumer decides
diff --git a/packages/llm/token-meter/README.i18n.yaml b/packages/llm/token-meter/README.i18n.yaml
index 9b68fa047a..03def91947 100644
--- a/packages/llm/token-meter/README.i18n.yaml
+++ b/packages/llm/token-meter/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/llm/token-meter/README.md
-README.md: 929d0322f6268562a10b9ab715cc0330800966b5
-README.zh.md: 40cea07c7dea20d0af9bf67ade2cb4164f7aed08
+README.md: 6cbbefa69fd4dd108d4c4ff717647e173922d7b2
+README.zh.md: 572409324e910f4b38ad48b2ec5fb2c85d4fd088
diff --git a/packages/llm/token-meter/README.md b/packages/llm/token-meter/README.md
index 929d0322f6..6cbbefa69f 100644
--- a/packages/llm/token-meter/README.md
+++ b/packages/llm/token-meter/README.md
@@ -6,7 +6,7 @@ Replay-aware token measurement through the singleton `ctx.tokenMeter` service. I
 
 ## Configuration
 
-The estimator has no settings. It intentionally uses one fixed heuristic: four characters per token plus structural overhead for roles, blocks, and request-envelope fields. Any key is rejected, including the obsolete global `contextWindow`; model capacity belongs to the adapter that owns an exact provider/model route and is available through `ctx.llm.resolveModelInfo().context`.
+The estimator has no settings. It intentionally uses one fixed heuristic: four characters per token plus structural overhead for roles, blocks, and request-envelope fields. Any key is rejected; model capacity belongs to the adapter that owns an exact provider/model route and is available through `ctx.llm.resolveModelInfo().context`.
 
 ## Measurement contract
 
@@ -41,7 +41,7 @@ The occupancy fields are independent last-wins records and are **not** one atomi
 
 This is deliberate. An occupancy percentage is a user-facing reference figure, not a billing record or a gating input — nothing in the harness makes decisions from it, and compaction reads `measure()` instead. A UI computes occupancy by dividing measured pressure by the separately resolved capacity for the selected model.
 
-Making the pair atomic was tried and rejected: it required a transient non-replayable wire frame, which needed lifecycle fencing against cross-stream reordering and left occupancy blank after every reconnect. The [Agent Note](../../../.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md) records that comparison. Consumers that need an exact same-boundary figure should call `measure()` at their own request boundary rather than read this projection.
+The [Agent Note](../../../.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md) records the rejected atomic-pair comparison. Consumers that need an exact same-boundary figure should call `measure()` at their own request boundary rather than read this projection.
 
 ## Composition
 
diff --git a/packages/llm/token-meter/README.zh.md b/packages/llm/token-meter/README.zh.md
index 40cea07c7d..572409324e 100644
--- a/packages/llm/token-meter/README.zh.md
+++ b/packages/llm/token-meter/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 配置
 
-估算器没有配置项。它有意使用一项固定启发式规则：每个 token 按四个字符估算，再加上角色、块与请求 envelope 字段的结构开销。任何配置键都会被拒绝，包括已废弃的全局 `contextWindow`；模型容量属于拥有精确提供方／模型路由的适配器，可通过 `ctx.llm.resolveModelInfo().context` 获取。
+估算器没有配置项。它有意使用一项固定启发式规则：每个 token 按四个字符估算，再加上角色、块与请求 envelope 字段的结构开销。任何配置键都会被拒绝；模型容量属于拥有精确提供方／模型路由的适配器，可通过 `ctx.llm.resolveModelInfo().context` 获取。
 
 ## 测量约定
 
@@ -41,7 +41,7 @@ fold 跟踪完整请求标头快照、步骤边界、表层追加与替换、成
 
 这是刻意的选择。占用率百分比是面向用户的参考数字，既不是计费记录，也不是门控输入：harness 中没有任何环节依据它做决策，压缩改为直接读取 `measure()`。UI 用测得的压力除以为所选模型单独解析出的容量来计算占用率。
 
-让这对值保持原子已经尝试过并被否决：它需要一个临时且不可回放的协议帧，进而需要针对跨流重排序的生命周期栅栏，还会让占用率在每次重连后变为空白。[Agent Note](../../../.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md)记录了这项对比。需要同一边界精确数字的消费方应在自己的请求边界调用 `measure()`，而不是读取该投影。
+[Agent Note](../../../.agents/notes/implemented/architecture/2026-07-29-projected-token-usage-and-request-context.md)记录了否决「让这对值保持原子」方案的那次对比。需要同一边界精确数字的消费方应在自己的请求边界调用 `measure()`，而不是读取该投影。
 
 ## 组合
 
diff --git a/packages/lsp/lsp/src/types.ts b/packages/lsp/lsp/src/types.ts
index d1bebe2a58..2e61d019ca 100644
--- a/packages/lsp/lsp/src/types.ts
+++ b/packages/lsp/lsp/src/types.ts
@@ -12,7 +12,7 @@ import type { LspProviderId } from './brand.ts'
 /**
  * The four semantic queries the seam and model expose. A closed union: adding an operation is a
  * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
- * deliberately deferred (they need different schemas).
+ * not operations here; they need different schemas.
  */
 export type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
 
diff --git a/packages/mcp/mcp-client/src/tools.ts b/packages/mcp/mcp-client/src/tools.ts
index 28c2a66319..889684923b 100644
--- a/packages/mcp/mcp-client/src/tools.ts
+++ b/packages/mcp/mcp-client/src/tools.ts
@@ -258,9 +258,8 @@ function createExecutor(
     }
 
     // Trust boundary: the SDK's return type erases to `any[]` due to the
-    // union of CallToolResult | CompatibilityCallToolResult. We process each
-    // element defensively in extractText (reading only .type/.text/.mimeType
-    // with optional fallbacks).
+    // union of CallToolResult | CompatibilityCallToolResult; extractText
+    // validates each element.
     const content = result.content as unknown as JsonValue[]
     const text = extractText(content, rawName)
 
diff --git a/packages/mcp/mcp-client/src/transport.ts b/packages/mcp/mcp-client/src/transport.ts
index f4bed91931..bc7fd1cc08 100644
--- a/packages/mcp/mcp-client/src/transport.ts
+++ b/packages/mcp/mcp-client/src/transport.ts
@@ -40,9 +40,8 @@ export function createTransport(config: Config): Transport {
     case 'streamable-http':
       // The MCP SDK's StreamableHTTPClientTransport has optional callback
       // properties typed without `| undefined` (exactOptionalPropertyTypes
-      // mismatch with the Transport interface). The cast is safe — the SDK
-      // constructed the object, it simply doesn't declare the optionals
-      // strictly enough for our tsconfig.
+      // mismatch with the Transport interface); the SDK constructed the
+      // object, so the cast records only that widening.
       return new StreamableHTTPClientTransport(
         new URL(config.url),
         { requestInit: { headers: config.headers } },
diff --git a/packages/mcp/mcp-client/tests/apply.spec.ts b/packages/mcp/mcp-client/tests/apply.spec.ts
index 44b3e272f4..e30a1ee716 100644
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -175,7 +175,6 @@ describe('apply (plugin lifecycle)', () => {
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
     await expect(apply(ctx, stdioConfig)).rejects.toThrow(/serverName "srv" is already in use/)
-    // First instance unaffected.
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
   })
 
diff --git a/packages/mcp/mcp-client/tests/mcp-client.spec.ts b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
index d19e30b94b..22559d74cf 100644
--- a/packages/mcp/mcp-client/tests/mcp-client.spec.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
@@ -207,7 +207,6 @@ describe('syncTools', () => {
     const firstDisposers = await syncTools(client as never, ctx, defaultOpts, new Map())
     expect(ctx.tools.get('mcp__srv__old_tool')).toBeDefined()
 
-    // Second sync with different tools should remove old_tool.
     client.listTools.mockResolvedValue({ tools: [{ name: 'new_tool', inputSchema: { type: 'object' } }], nextCursor: undefined })
     const secondDisposers = await syncTools(client as never, ctx, defaultOpts, firstDisposers)
 
@@ -770,13 +769,11 @@ describe('createTransport', () => {
         toolCallTimeoutMs: 60_000,
         failOnStartupError: false,
       }
-      // createTransport internally calls buildChildEnv; we verify by inspecting
-      // the constructed StdioClientTransport. Since we can't inspect private fields
-      // easily, we at least confirm it doesn't throw and returns a transport.
+      // StdioClientTransport keeps its env private; the observable contract is
+      // that createTransport(config) returns a transport without throwing.
       const transport = createTransport(config)
       expect(transport).toBeDefined()
     } finally {
-      // Restore env
       delete process.env.SAFE_VAR
       delete process.env.MY_SECRET
       delete process.env.API_KEY
diff --git a/packages/scaffold/README.i18n.yaml b/packages/scaffold/README.i18n.yaml
index 7ddc22328c..9cc0926043 100644
--- a/packages/scaffold/README.i18n.yaml
+++ b/packages/scaffold/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/scaffold/README.md
-README.md: 19c2f28f48d1c2d8747b635c10d6781c29e02f15
-README.zh.md: ecad2592eb32a30444f9112571379939da6afeec
+README.md: f36e828a507aea80a064de7d7de30ba65d63600b
+README.zh.md: f58d8c8defeea948d59c3b11b4c60703b8144ea8
diff --git a/packages/scaffold/README.md b/packages/scaffold/README.md
index 19c2f28f48..f36e828a50 100644
--- a/packages/scaffold/README.md
+++ b/packages/scaffold/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named without the legacy `sdk-` prefix; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md).
+This group contains developer tooling for Harness projects and the client stack for driving a Harness runtime from another process. Folders are role-named; npm names converge on `dsh-sdk-*` through the FIXME-tracked renames in the [regrouping Agent Note](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md).
 
 | Package | Role |
 |---|---|
diff --git a/packages/scaffold/README.zh.md b/packages/scaffold/README.zh.md
index ecad2592eb..f58d8c8def 100644
--- a/packages/scaffold/README.zh.md
+++ b/packages/scaffold/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名，不带遗留的 `sdk-` 前缀；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
+本组包含 Harness 项目的开发者工具，以及从另一进程驱动 Harness 运行时的客户端栈。目录按角色命名；npm 名则经由[重新分组 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)中 FIXME 跟踪的改名收敛为 `dsh-sdk-*`。
 
 | 包 | 职责 |
 |---|---|
diff --git a/packages/scaffold/telemetry/README.i18n.yaml b/packages/scaffold/telemetry/README.i18n.yaml
index 4d70fce157..beb145cfc0 100644
--- a/packages/scaffold/telemetry/README.i18n.yaml
+++ b/packages/scaffold/telemetry/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/scaffold/telemetry/README.md
-README.md: c87735a93e7659f2913f4dd325176a8ae40cf29b
-README.zh.md: 24d6e72d988f94cdbc6aa01607edbfc105213267
+README.md: 024ff8724604426d3d77609929ca40341f98e0fb
+README.zh.md: 8d69d9289ed9c412e4d38fe9b24bb3222f81f94a
diff --git a/packages/scaffold/telemetry/README.md b/packages/scaffold/telemetry/README.md
index c87735a93e..024ff87246 100644
--- a/packages/scaffold/telemetry/README.md
+++ b/packages/scaffold/telemetry/README.md
@@ -14,7 +14,7 @@ Launcher-side telemetry primitives for the dsh-sdk toolchain. This is a plain li
 
 Consent is carried by the telemetry entry in `cordis.yml`, so disabling telemetry is disabling that entry. Telemetry reports by default and is off only when a present telemetry entry is explicitly `disabled`: a missing `cordis.yml` (first `create`), an enabled entry, or a `cordis.yml` with no telemetry entry all report. `DO_NOT_TRACK`/CI always deny. The no-config and absent-entry defaults are configurable on `ConsentResolver`.
 
-The collection endpoint is a fixed constant (`DSH_TELEMETRY_ENDPOINT`); its fail-safe `.invalid` placeholder must be replaced with the real endpoint before release.
+The collection endpoint is a fixed constant (`DSH_TELEMETRY_ENDPOINT`).
 
 ## Model Experience
 
diff --git a/packages/scaffold/telemetry/README.zh.md b/packages/scaffold/telemetry/README.zh.md
index 24d6e72d98..8d69d9289e 100644
--- a/packages/scaffold/telemetry/README.zh.md
+++ b/packages/scaffold/telemetry/README.zh.md
@@ -14,7 +14,7 @@
 
 Consent 由 `cordis.yml` 中的 telemetry 配置项承载，因此禁用 telemetry 就是禁用该配置项。telemetry 默认上报，只有已经存在的 telemetry 配置项被显式设为 `disabled` 时才关闭：缺少 `cordis.yml`（首次 `create`）、配置项已启用，或 `cordis.yml` 中没有 telemetry 配置项时都会上报。`DO_NOT_TRACK`／CI 始终拒绝。无配置与缺少配置项的默认值可以通过 `ConsentResolver` 配置。
 
-收集端点是固定常量（`DSH_TELEMETRY_ENDPOINT`）；发布前必须将作为安全兜底的 `.invalid` 占位值替换为真实端点。
+收集端点是固定常量（`DSH_TELEMETRY_ENDPOINT`）。
 
 ## 模型体验
 
diff --git a/packages/self-modification/README.i18n.yaml b/packages/self-modification/README.i18n.yaml
index 5a2f02826c..e6e0fa54c8 100644
--- a/packages/self-modification/README.i18n.yaml
+++ b/packages/self-modification/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/self-modification/README.md
-README.md: 53f700993cce8df8729fba5a92a9498fff2412cd
-README.zh.md: 18e03798b90e73f1d7e61ecf7010b8c472454a08
+README.md: c94f9ac9a79709e418448d9e440c38296e759335
+README.zh.md: 44b5d9ff4cb09fb4a4e44f446894c9925a62ec51
diff --git a/packages/self-modification/README.md b/packages/self-modification/README.md
index 53f700993c..c94f9ac9a7 100644
--- a/packages/self-modification/README.md
+++ b/packages/self-modification/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service surface, mount model-written plugins, and dispose them again — plus the restricted repository Plugin runtime. The group is the landing zone for future self-modification packages. Design home: [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service surface, mount model-written plugins, and dispose them again — plus the restricted repository Plugin runtime. Design home: [the toolset Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
 
 | Package | Role | ctx key |
 |---|---|---|
diff --git a/packages/self-modification/README.zh.md b/packages/self-modification/README.zh.md
index 18e03798b9..44b5d9ff4c 100644
--- a/packages/self-modification/README.zh.md
+++ b/packages/self-modification/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-agent 修改自身运行时：检查已加载的插件与服务接口、挂载模型编写的插件并再次 dispose，外加受限 repository Plugin 运行时。该组是未来自我修改类包的落点。设计居所：[工具集 Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
+agent 修改自身运行时：检查已加载的插件与服务接口、挂载模型编写的插件并再次 dispose，外加受限 repository Plugin 运行时。设计居所：[工具集 Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
 
 | 包（package） | 角色 | ctx 键 |
 |---|---|---|
diff --git a/packages/self-modification/tool-cordis/src/api-catalog.ts b/packages/self-modification/tool-cordis/src/api-catalog.ts
index c8ec4894b4..503736477c 100644
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -1012,7 +1012,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>',
-        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides. Relative paths containing separators\n * are rejected: no current consumer defines which directory they would\n * resolve against, so providers fail loud instead of guessing.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
+        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides. Relative paths containing separators\n * are rejected: the resolution base is undefined, so providers fail loud\n * instead of guessing.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
       },
       {
         signature: 'abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle',
diff --git a/packages/session-query/session-query-sqlite/README.i18n.yaml b/packages/session-query/session-query-sqlite/README.i18n.yaml
index ce1fae24c9..42cf0f2ff2 100644
--- a/packages/session-query/session-query-sqlite/README.i18n.yaml
+++ b/packages/session-query/session-query-sqlite/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/session-query/session-query-sqlite/README.md
-README.md: dbbb63e9dd18f3c68cc21b84b560403f4a508709
-README.zh.md: 0b183f63ad2f3cfa670babca80d6e4abee6a4bcb
+README.md: 8784f1b2c2a3c9291b761c0a6e68201286b9e306
+README.zh.md: 5b69c054a0e17a49e9c709b27e497b006a024a91
diff --git a/packages/session-query/session-query-sqlite/README.md b/packages/session-query/session-query-sqlite/README.md
index dbbb63e9dd..8784f1b2c2 100644
--- a/packages/session-query/session-query-sqlite/README.md
+++ b/packages/session-query/session-query-sqlite/README.md
@@ -37,7 +37,7 @@ The database is disposable but reset is guarded: every recognized schema version
 
 ## Tokenizer and limits
 
-The index uses FTS5 `unicode61`. In the implementation experiment it supported the two-character query `AI` and produced an index about 2.1× smaller than the trigram alternative. The trade-off is token/phrase recall rather than arbitrary substring recall: `AI` does not match the token `BRAID`. Use `ctx.sessionQuery.filterEvents()` with a `text` clause when a literal whitespace-flexible substring scan is required. NUL is rejected in queries; reserved highlight markers and NUL in documents are normalized before indexing so presentation markers cannot collide with source text.
+The index uses FTS5 `unicode61`. The trade-off is token/phrase recall rather than arbitrary substring recall: `AI` does not match the token `BRAID`. Use `ctx.sessionQuery.filterEvents()` with a `text` clause when a literal whitespace-flexible substring scan is required. NUL is rejected in queries; reserved highlight markers and NUL in documents are normalized before indexing so presentation markers cannot collide with source text.
 
 Abort signals stop queued work and flow unchanged through snapshot listing and non-mutating inspection. Once source work starts, the serialized state machine awaits that backend promise itself—even when a backend ignores cancellation—then checks the signal before starting any further listing, inspection, reconciliation, or query work. The caller therefore observes cancellation only after started backend work is quiescent, and a later search cannot enter the serializer while that cleanup is pending. Node's synchronous `DatabaseSync` API cannot interrupt a metadata or MATCH statement already executing on the JavaScript thread; signals are checked immediately before and after those non-preemptible calls.
 
diff --git a/packages/session-query/session-query-sqlite/README.zh.md b/packages/session-query/session-query-sqlite/README.zh.md
index 0b183f63ad..5b69c054a0 100644
--- a/packages/session-query/session-query-sqlite/README.zh.md
+++ b/packages/session-query/session-query-sqlite/README.zh.md
@@ -37,7 +37,7 @@
 
 ## 分词器与限制
 
-该索引使用 FTS5 `unicode61`。在实现实验中，它支持双字符查询 `AI`，产生的索引比 trigram 备选方案小约 2.1 倍。取舍是 token/短语召回而非任意子字符串召回：`AI` 不匹配 token `BRAID`。需要执行字面的空白弹性子字符串扫描时，使用 `ctx.sessionQuery.filterEvents()` 并传入 `text` 子句。查询会拒绝 NUL；文档中的保留高亮标记和 NUL 会在索引前被规范化，使展示标记无法与源文本冲突。
+该索引使用 FTS5 `unicode61`。取舍是 token/短语召回而非任意子字符串召回：`AI` 不匹配 token `BRAID`。需要执行字面的空白弹性子字符串扫描时，使用 `ctx.sessionQuery.filterEvents()` 并传入 `text` 子句。查询会拒绝 NUL；文档中的保留高亮标记和 NUL 会在索引前被规范化，使展示标记无法与源文本冲突。
 
 中止信号会停止已排队工作，并原样流经快照枚举和非修改式检查。来源工作一旦开始，串行化状态机会自行等待该后端 promise，即使后端忽略取消，之后也会在启动任何进一步的枚举、检查、对账或查询工作前检查信号。因此，调用方只会在已启动后端工作完全停稳后观察到取消，而后续搜索在该清理尚未完成时无法进入 serializer。Node 的同步 `DatabaseSync` API 无法中断已在 JavaScript 线程上执行的元数据或 MATCH 语句；系统会在这些不可抢占调用前后立即检查信号。
 
diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
index 24ed94a3fb..600b8ab80f 100644
--- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -201,7 +201,6 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
     expect((await ctx.sessionPersistence.list()).map(h => h.id)).not.toContain(m.id)
 
     await ctx.sessionPersistence.append(m.id, oneTurnLog())
-    // now materialized
     expect((await stat(dir)).isDirectory()).toBe(true)
     expect((await stat(rawLogPath(root, '/work', m.id))).isFile()).toBe(true)
     expect((await ctx.sessionPersistence.list()).map(h => h.id)).toContain(m.id)
diff --git a/packages/session/session-persistence-sqlite/README.i18n.yaml b/packages/session/session-persistence-sqlite/README.i18n.yaml
index 0f5de36bc2..e55082e190 100644
--- a/packages/session/session-persistence-sqlite/README.i18n.yaml
+++ b/packages/session/session-persistence-sqlite/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/session/session-persistence-sqlite/README.md
-README.md: 745c25616e06c391a70b37471917aa9d2539c4dd
-README.zh.md: c86531bcaeca85fa565b537f1fc1beca5d6ac7b3
+README.md: 4ba675447393ffb359ec6983585167b692e84a7d
+README.zh.md: c2578215613ea42fb34e3092f51ec47cbb2fc128
diff --git a/packages/session/session-persistence-sqlite/README.md b/packages/session/session-persistence-sqlite/README.md
index 745c25616e..4ba6754473 100644
--- a/packages/session/session-persistence-sqlite/README.md
+++ b/packages/session/session-persistence-sqlite/README.md
@@ -2,12 +2,10 @@
 
 English | [中文](README.zh.md)
 
-A SQLite durable session-persistence backend — a second `SessionPersistence` provider ([session persistence](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)), built to validate that the Service Definition and the shared `runPersistenceContract` suite are genuinely backend-agnostic. It satisfies the SAME contract as `dsh-session-persistence-jsonl` (append-only, contiguous-seq, lazy materialization, interrupted-turn close on load), expressed over `node:sqlite` rows instead of file bytes.
+A SQLite durable session-persistence backend — a second `SessionPersistence` provider ([session persistence](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)) satisfying the same contract as `dsh-session-persistence-jsonl` (append-only, contiguous-seq, lazy materialization, interrupted-turn close on load), expressed over `node:sqlite` rows instead of file bytes.
 
 `locate(meta)` returns `undefined`: all sessions share one database, so there is no honest independent per-session transcript path.
 
-> **TODO:** this backend talks to `node:sqlite` directly. If a cordis database service (`cordis/db` / a `@cordisjs` SQL driver plugin) is adopted, route through that instead of holding a raw `DatabaseSync` here — the contract surface (`SessionPersistence`) would not change, only the storage driver.
-
 ## Storage model
 
 Each `SessionEvent` maps 1:1 onto a row in an `events` table `(session_id, seq, type, time, data, source_event_seqs, surface_op)` — `data` is the event payload as JSON text, so the row shape is the event verbatim (including `assistant/chunk`, keeping `seq` contiguous). The two `TEXT` columns `source_event_seqs` and `surface_op` are nullable; they store the event's optional surface-metadata fields (see [session surface](../../../.agents/notes/implemented/architecture/2026-06-18-session-surface.md)). Out-of-log metadata (`SessionHeader`), a per-materialization incarnation id, and a monotonic per-log revision live in a `sessions` row; `createdAt` is a non-negative safe integer stored in a strict `INTEGER` column. A singleton state row carries the immutable store id. A `sessions` row is written only by the first `append` — its existence is the lazy-materialization signal (`list` reports exactly the sessions that have a row).
@@ -61,3 +59,4 @@ SQLite storage does not mutate live request prefixes. A resumed loop can reuse p
 - **Write contention has no wait or retry policy** — the backend sets no busy timeout and retries no locked-database error, so another connection holding a write transaction makes the operation reject immediately.
 - **Only a pristine new database or the current owned `SCHEMA_VERSION` opens** — unversioned schema objects, foreign application identities, and every other schema version are rejected rather than migrated (unreleased software; no persisted user data to preserve).
 - **Nothing deletes stored sessions** — rows accumulate until removed externally (the seam has no deletion surface; `ON DELETE CASCADE` is wired for such out-of-band cleanup).
+- **TODO:** this backend talks to `node:sqlite` directly. If a cordis database service (`cordis/db` / a `@cordisjs` SQL driver plugin) is adopted, route through that instead of holding a raw `DatabaseSync` here — the contract surface (`SessionPersistence`) would not change, only the storage driver.
diff --git a/packages/session/session-persistence-sqlite/README.zh.md b/packages/session/session-persistence-sqlite/README.zh.md
index c86531bcae..c257821561 100644
--- a/packages/session/session-persistence-sqlite/README.zh.md
+++ b/packages/session/session-persistence-sqlite/README.zh.md
@@ -2,12 +2,10 @@
 
 [English](README.md) | 中文
 
-SQLite 持久会话存储后端：第二个 `SessionPersistence` 提供方（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证 Service Definition 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的约定（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
+SQLite 持久会话存储后端：第二个 `SessionPersistence` 提供方（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），满足与 `dsh-session-persistence-jsonl` 相同的约定（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
 
 `locate(meta)` 返回 `undefined`：所有会话共享一个数据库，因此不存在真实、独立的逐会话 transcript（文本记录）路径。
 
-> **TODO：** 该后端直接调用 `node:sqlite`。如果采用 Cordis 数据库服务（`cordis/db` / `@cordisjs` SQL driver 插件），应改为通过该服务路由，而不在此直接持有 `DatabaseSync`；约定接口（`SessionPersistence`）不会变，只更换存储驱动。
-
 ## 存储模型
 
 每个 `SessionEvent` 1:1 映射到 `events` 表中的一行 `(session_id, seq, type, time, data, source_event_seqs, surface_op)`；`data` 是作为 JSON 文本的事件 payload，因此行结构就是原始事件本身（包括 `assistant/chunk`，保持 `seq` 连续）。两个 `TEXT` 列 `source_event_seqs` 和 `surface_op` 可为空，存储事件可选接口元数据字段（见[会话接口](../../../.agents/notes/implemented/architecture/2026-06-18-session-surface.md)）。日志外元数据（`SessionHeader`）、每实体化 incarnation id 和每日志单调修订位于 `sessions` 行；`createdAt` 是存储在 strict `INTEGER` 列中的非负安全整数。单例状态行携带不可变存储 id。`sessions` 行只由第一次 `append` 写入，其存在性是延迟实体化信号（`list` 精确报告有行的会话）。
@@ -61,3 +59,4 @@ SQLite 存储不修改当前请求前缀。只有重建历史、当前 envelope
 - **写入争用无等待或重试策略**：后端不设置 busy timeout，也不重试 locked-database 错误，因此其他连接持有写事务时操作立即拒绝。
 - **只有 pristine 新数据库或当前自有 `SCHEMA_VERSION` 才能打开**：无版本 schema 对象、外部 application identity 和所有其他 schema 版本被拒绝，而不是迁移（未发布软件，无持久用户数据需要保留）。
 - **不删除已存储会话**：行会累积，直到外部移除（seam 无删除接口；`ON DELETE CASCADE` 已为这种带外清理配置）。
+- **TODO：** 该后端直接调用 `node:sqlite`。如果采用 Cordis 数据库服务（`cordis/db` / `@cordisjs` SQL driver 插件），应改为通过该服务路由，而不在此直接持有 `DatabaseSync`；约定接口（`SessionPersistence`）不会变，只更换存储驱动。
diff --git a/packages/session/session-projection-cache/src/spec.ts b/packages/session/session-projection-cache/src/spec.ts
index 5e41763f80..26de5abe73 100644
--- a/packages/session/session-projection-cache/src/spec.ts
+++ b/packages/session/session-projection-cache/src/spec.ts
@@ -61,8 +61,7 @@ export type CheckpointRecord = z.infer<typeof checkpointRecord>
 /**
  * The session-projcache domain spec. Version bumps discard the whole medium
  * (cache semantics: a stale or unreadable cache costs a longer tail replay,
- * never a wrong value). v2 added the record's log-identity binding; v3
- * renamed the row fields to `ver`/`seq`/`val`.
+ * never a wrong value).
  */
 export const projectionCacheDomainSpec = defineDomain({
   name: 'session_projcache',
diff --git a/packages/session/session-telemetry-otel/src/index.ts b/packages/session/session-telemetry-otel/src/index.ts
index 37ba236477..b128f65978 100644
--- a/packages/session/session-telemetry-otel/src/index.ts
+++ b/packages/session/session-telemetry-otel/src/index.ts
@@ -253,11 +253,11 @@ export class TelemetryOtel extends Telemetry {
   // The Service Definition's optional flush() hint is deliberately NOT implemented. The
   // batch processor exports on its own cadence (`processor.scheduledDelayMillis`,
   // the SDK's documented knob), and this backend is the SDK pipeline's only
-  // caller — forwarding the hint to `forceFlush()` was the sole source of
+  // caller — forwarding the hint to `forceFlush()` would be the sole source of
   // concurrent flushes, whose undocumented interactions with shutdown's
   // internal drain (concurrent-flush guard, provider-level flush timeout)
-  // silently dropped tail records. Removal history and the revival trigger:
-  // the revival Agent Note.
+  // silently drop tail records. Rationale and the revival trigger: the
+  // revival Agent Note.
 
   /**
    * Ask the SDK to drain and quiesce, but reject after the backend-owned
diff --git a/packages/session/session-telemetry/src/index.ts b/packages/session/session-telemetry/src/index.ts
index 7606cc3ca6..977527aace 100644
--- a/packages/session/session-telemetry/src/index.ts
+++ b/packages/session/session-telemetry/src/index.ts
@@ -111,7 +111,7 @@ export interface TelemetryBackend {
    * leave this unimplemented and let their SDK's own batching cadence govern
    * export timing: a backend that does implement it owns the interaction
    * between its concurrent flushes and {@link shutdown}'s drain (the OTel
-   * backend removed its implementation for exactly that hazard — see the
+   * backend leaves it unimplemented for exactly that hazard — see the
    * revival Agent Note).
    */
   flush?(): void
diff --git a/packages/skill/skill-local/README.i18n.yaml b/packages/skill/skill-local/README.i18n.yaml
index 4dcb4dbc68..fb7d31ce14 100644
--- a/packages/skill/skill-local/README.i18n.yaml
+++ b/packages/skill/skill-local/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/skill/skill-local/README.md
-README.md: f85cc2e6fd0c32cb88f28a2914a03e22b3a20657
-README.zh.md: 9ee09938737237df9e97e517c1dd44b511b7f596
+README.md: c130c8b525367d7a80e32f0684cd05c931b35944
+README.zh.md: 878725e64413d3e17baf7693ee72b192a23292e6
diff --git a/packages/skill/skill-local/README.md b/packages/skill/skill-local/README.md
index f85cc2e6fd..c130c8b525 100644
--- a/packages/skill/skill-local/README.md
+++ b/packages/skill/skill-local/README.md
@@ -52,7 +52,7 @@ The first-party filesystem `write` and `edit` tools also synchronously invalidat
 
 ## Skill Format
 
-Skills can be single-level directory bundles (`<name>/SKILL.md`) or flat Markdown files (`<name>.md`). Nested `**/SKILL.md` discovery is intentionally not part of v1. Frontmatter is parsed as an open YAML object with the `yaml` package; this provider currently interprets required `name` and `description`, plus optional `whenToUse`, `metadata`, `disable-model-invocation`, and `user-invocable`. Names must be kebab-case.
+Skills can be single-level directory bundles (`<name>/SKILL.md`) or flat Markdown files (`<name>.md`). Nested `**/SKILL.md` discovery is deliberately excluded. Frontmatter is parsed as an open YAML object with the `yaml` package; this provider interprets required `name` and `description`, plus optional `whenToUse`, `metadata`, `disable-model-invocation`, and `user-invocable`. Names must be kebab-case.
 
 The two invocation fields accept YAML booleans and the case-insensitive forms `true`/`false`, `yes`/`no`, `on`/`off`, and `1`/`0`. `disable-model-invocation: true` excludes the skill from model-facing catalogs and loaders; `user-invocable: false` excludes it from human-facing commands. Each omitted field defaults to permitting its surface, and the provider always emits both positive internal policy values, including when both keys are absent. A rejected camel-case spelling or a non-boolean invocation value drops the entire skill from discovery with a warning instead of discarding only that field or falling back to a permissive default. Invocation policy fails closed because ignoring invalid data could expose a skill on a disabled surface; wrong-typed optional `whenToUse` and `metadata` values are omitted because neither currently grants invocation.
 
diff --git a/packages/skill/skill-local/README.zh.md b/packages/skill/skill-local/README.zh.md
index 9ee0993873..878725e644 100644
--- a/packages/skill/skill-local/README.zh.md
+++ b/packages/skill/skill-local/README.zh.md
@@ -52,7 +52,7 @@
 
 ## skill 格式
 
-skill 可以是单层目录 bundle（`<name>/SKILL.md`），也可以是平铺 Markdown 文件（`<name>.md`）。v1 刻意不支持发现嵌套的 `**/SKILL.md`。Frontmatter 使用 `yaml` 包解析为开放的 YAML 对象；该提供方目前解析必填的 `name` 和 `description`，以及可选的 `whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable`。名称必须使用 kebab-case。
+skill 可以是单层目录 bundle（`<name>/SKILL.md`），也可以是平铺 Markdown 文件（`<name>.md`）。刻意不支持发现嵌套的 `**/SKILL.md`。Frontmatter 使用 `yaml` 包解析为开放的 YAML 对象；该提供方解析必填的 `name` 和 `description`，以及可选的 `whenToUse`、`metadata`、`disable-model-invocation` 和 `user-invocable`。名称必须使用 kebab-case。
 
 这两个调用字段接受 YAML 布尔值，以及不区分大小写的 `true`/`false`、`yes`/`no`、`on`/`off` 和 `1`/`0`。`disable-model-invocation: true` 会从面向模型的目录和 loader 中排除该 skill；`user-invocable: false` 会从面向用户的命令中排除该 skill。每个省略的字段都默认为允许对应接口调用；提供方始终输出两个正向内部策略值，即使两个键都不存在也不例外。若使用驼峰拼写或提供非布尔调用值，系统会记录警告并从发现结果中排除整个 skill，而不是只丢弃该字段或回退到宽松的默认值。调用策略校验遵循失败时默认拒绝原则，因为忽略无效数据可能会在已禁用的接口上暴露 skill；类型错误的可选 `whenToUse` 和 `metadata` 值则会被省略，因为这两个字段目前都不授予调用权限。
 
diff --git a/packages/skill/tool-skill/tests/tool-skill.spec.ts b/packages/skill/tool-skill/tests/tool-skill.spec.ts
index 5e0fe58855..24d9c35591 100644
--- a/packages/skill/tool-skill/tests/tool-skill.spec.ts
+++ b/packages/skill/tool-skill/tests/tool-skill.spec.ts
@@ -494,11 +494,11 @@ describe('dsh-tool-skill', () => {
   })
 
   it('resumes from the durable entries of the latest visible catalog', async () => {
-    // Catalog identity moved onto `source.entries` when the catalog became a
-    // `catalog`-form context: the model-facing prose no longer decides whether
-    // a republish is needed, so a seeded message is recognized by its source
-    // alone and malformed prose can no longer hide (or fake) a published
-    // catalog. A foreign-sourced message is not this plugin's catalog at all.
+    // Catalog identity lives on `source.entries`: the model-facing prose does
+    // not decide whether a republish is needed, so a seeded message is
+    // recognized by its source alone and malformed prose cannot hide (or fake)
+    // a published catalog. A foreign-sourced message is not this plugin's
+    // catalog at all.
     const home = await tempDir('tool-catalog-resume')
     const ctx = await setup(home)
     ctx.skills.register({
diff --git a/packages/storage/storage-sqlite/README.i18n.yaml b/packages/storage/storage-sqlite/README.i18n.yaml
index 9a373d4039..2f997b3734 100644
--- a/packages/storage/storage-sqlite/README.i18n.yaml
+++ b/packages/storage/storage-sqlite/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/storage/storage-sqlite/README.md
-README.md: efc1b3ca54181a43c067594cc339ccc3a8fea510
-README.zh.md: bcbccf388cda3955fe6cd6501fd9ffb63e4c2a50
+README.md: 48aae14aa8613886d69652c39194878c190259cf
+README.zh.md: d95da614deb2fe4b6380532aa43836441a0db01c
diff --git a/packages/storage/storage-sqlite/README.md b/packages/storage/storage-sqlite/README.md
index efc1b3ca54..48aae14aa8 100644
--- a/packages/storage/storage-sqlite/README.md
+++ b/packages/storage/storage-sqlite/README.md
@@ -8,7 +8,7 @@ SQLite backend for the [storage hub](../storage/README.md): registers as backend
 
 Document-per-row: each unit table becomes a physical `"u_<unit>_<table>" (key TEXT PRIMARY KEY, value TEXT)` STRICT table whose `value` is the record's JSON text, so one key updates one row (the reason to route a high-churn domain here instead of the JSON backend). Unit identity lives in two metadata tables — `units` stamps each unit's format version at first open and rejects a differing descriptor with `version-mismatch`; `unit_globals` holds each unit's global singleton row. The physical layout version lives in `PRAGMA user_version`; any other stamped value rejects (unreleased format, no migrations). Unit and table names are validated against the hub's `UNIT_NAME_RE` before they reach DDL, so no external input is ever interpolated into SQL identifiers.
 
-Every write primitive is a single prepared statement — SQLite's per-statement atomicity satisfies the KV contract without explicit transactions, and write ordering stays the caller's responsibility (the domain layer's write chain). Missing directories and database files are created owner-only (`0o700`/`0o600`), matching the session-persistence SQLite backend, whose open sequence this package copies verbatim until the planned media-layer extraction.
+Every write primitive is a single prepared statement — SQLite's per-statement atomicity satisfies the KV contract without explicit transactions, and write ordering stays the caller's responsibility (the domain layer's write chain). Missing directories and database files are created owner-only (`0o700`/`0o600`), matching the session-persistence SQLite backend.
 
 ## Configuration (schemastery)
 
@@ -38,6 +38,6 @@ None — the backend never touches live request prefixes.
 ## Known Limitations and Deferred Work
 
 - **`DatabaseSync` is synchronous** — each write blocks the event loop for its (single-statement) duration; acceptable at domain-data scale.
-- **No busy-wait or retry policy** — another connection holding a write transaction rejects the operation immediately; multi-process write protection is on the design's future-work list.
+- **No busy-wait or retry policy** — another connection holding a write transaction rejects the operation immediately; there is no multi-process write protection.
 - **Only the current `STORAGE_SQLITE_SCHEMA_VERSION` opens** — any other stamped version is rejected rather than migrated (pre-release stance).
 - **`openDatabase` duplicates the session-persistence SQLite open sequence** — extraction into a shared media layer is deferred to the planned session-backend migration (see the Agent Note's reuse audit).
diff --git a/packages/storage/storage-sqlite/README.zh.md b/packages/storage/storage-sqlite/README.zh.md
index bcbccf388c..d95da614de 100644
--- a/packages/storage/storage-sqlite/README.zh.md
+++ b/packages/storage/storage-sqlite/README.zh.md
@@ -8,7 +8,7 @@
 
 每行一个文档：每个单元表都会成为一个物理 STRICT 表 `"u_<unit>_<table>" (key TEXT PRIMARY KEY, value TEXT)`，其中 `value` 是记录的 JSON 文本，因此一个 key 只更新一行（高频变更领域路由到这里而非 JSON 后端的原因）。单元标识位于两个元数据表中：`units` 在单元首次打开时标记其格式版本，描述符不同时以 `version-mismatch` 拒绝；`unit_globals` 保存每个单元的全局单例行。物理布局版本位于 `PRAGMA user_version`；其他任何标记值都会被拒绝（未发布格式，不迁移）。单元名和表名在进入 DDL 之前依据中心的 `UNIT_NAME_RE` 进行验证，因此不会把外部输入插值到 SQL 标识符中。
 
-每个写入原语都是一条预处理语句：SQLite 的逐语句原子性无需显式事务即可满足 KV 约定，写入顺序仍由调用方负责（领域层写入链）。缺失目录和数据库文件会以仅所有者可访问的权限创建（`0o700`／`0o600`），与 session-persistence SQLite 后端一致；在计划的介质层提取完成前，该包逐字复用了后者的打开顺序。
+每个写入原语都是一条预处理语句：SQLite 的逐语句原子性无需显式事务即可满足 KV 约定，写入顺序仍由调用方负责（领域层写入链）。缺失目录和数据库文件会以仅所有者可访问的权限创建（`0o700`／`0o600`），与 session-persistence SQLite 后端一致。
 
 ## 配置（schemastery）
 
@@ -38,6 +38,6 @@ interface Config {
 ## 已知限制与暂缓事项
 
 - **`DatabaseSync` 是同步的**：每次写入都会在单条语句执行期间阻塞事件循环；在领域数据规模下可以接受。
-- **没有忙等待或重试策略**：另一个连接持有写事务时，该操作会立即被拒绝；多进程写入保护列在设计文档的未来工作清单中。
+- **没有忙等待或重试策略**：另一个连接持有写事务时，该操作会立即被拒绝；没有多进程写入保护。
 - **只打开当前的 `STORAGE_SQLITE_SCHEMA_VERSION`**：其他任何已标记版本都会被拒绝而不是迁移（预发布立场）。
 - **`openDatabase` 重复了 session-persistence SQLite 打开顺序**：提取到共享介质层的工作暂缓至计划的会话后端迁移（见 Agent Note 的复用审计）。
diff --git a/packages/subagent/subagent-acp/README.i18n.yaml b/packages/subagent/subagent-acp/README.i18n.yaml
index f44ae87197..01daa65f77 100644
--- a/packages/subagent/subagent-acp/README.i18n.yaml
+++ b/packages/subagent/subagent-acp/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/subagent/subagent-acp/README.md
-README.md: 4fdd3a09e128d4dc7ec7395d9578803c64a33bc6
-README.zh.md: 7cb1e3d18602ef839e4af316962fc2d10bc67640
+README.md: 33711eb93c38d93472b3b625a86721c1365ac8d9
+README.zh.md: e57010f395e4ebae9b2e909bf63b7ffa1a90afe2
diff --git a/packages/subagent/subagent-acp/README.md b/packages/subagent/subagent-acp/README.md
index 4fdd3a09e1..33711eb93c 100644
--- a/packages/subagent/subagent-acp/README.md
+++ b/packages/subagent/subagent-acp/README.md
@@ -97,4 +97,4 @@ Append-only; newly visible content follows the reusable request prefix and does
 - **Local workspaces only** — the resolved cwd is a local path handed to a child on the same machine; workspace mapping for a remote ACP agent would need its own backend capability and is not designed here.
 - **No optional start-time capabilities** — this provider cannot apply the local harness's `outputSchema`, depth cap, tool filter, or persona inside the remote process, so it advertises none and the service rejects requests that require them.
 - **Only committed `agent_message_chunk` text is collected** — the automation server keeps reasoning, tool activity, plans, and other trace data in the child session log rather than emitting them on ACP.
-- **Permission prompts are auto-answered** (`permission: allow | reject`) — no human is surfaced a child's `session/request_permission` in this cut.
+- **Permission prompts are auto-answered** (`permission: allow | reject`) — no human is surfaced a child's `session/request_permission`.
diff --git a/packages/subagent/subagent-acp/README.zh.md b/packages/subagent/subagent-acp/README.zh.md
index 7cb1e3d186..e57010f395 100644
--- a/packages/subagent/subagent-acp/README.zh.md
+++ b/packages/subagent/subagent-acp/README.zh.md
@@ -97,4 +97,4 @@ ACP 不声明任何启动时能力，因为当前进程无法强制执行远程
 - **仅支持本地工作区**：解析后的 cwd 是交给同一台机器上子进程的本地路径；远程 ACP agent 的工作区映射需要独立的后端能力，本包尚未设计。
 - **不支持可选启动时能力**：该提供方无法在远程进程内应用本地 harness 的 `outputSchema`、深度上限、工具过滤器或 persona，因此不会声明这些能力；服务会拒绝需要它们的请求。
 - **只收集已提交的 `agent_message_chunk` 文本**：自动化服务器把推理（reasoning）、工具活动、计划和其他 trace 数据保留在子 agent 会话日志中，不通过 ACP 发出。
-- **权限提示自动回答**（`permission: allow | reject`）：当前版本不会把子 agent 的 `session/request_permission` 呈现给人。
+- **权限提示自动回答**（`permission: allow | reject`）：不会把子 agent 的 `session/request_permission` 呈现给人。
diff --git a/packages/subagent/subagent-acp/src/index.ts b/packages/subagent/subagent-acp/src/index.ts
index fa7c031760..7cc781ca15 100644
--- a/packages/subagent/subagent-acp/src/index.ts
+++ b/packages/subagent/subagent-acp/src/index.ts
@@ -42,7 +42,7 @@ export interface Config {
   /**
    * How to auto-answer the child's `session/request_permission` prompts:
    * `reject` (default — decline every prompt) or `allow` (approve via the first
-   * allow-shaped option). The first cut surfaces no prompt to a human.
+   * allow-shaped option). No prompt is surfaced to a human.
    */
   permission: PermissionPolicy
   /**
diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts
index f3e155e649..17476be41c 100644
--- a/packages/subagent/subagent-acp/src/run.ts
+++ b/packages/subagent/subagent-acp/src/run.ts
@@ -244,7 +244,7 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe
         output.push(acpContentText(update.content))
       }
       // Other updates (thoughts, tool calls, plans) are consumed but not
-      // surfaced in this cut — the subagent returns only its final answer.
+      // surfaced — the subagent returns only its final answer.
       return Promise.resolve()
     },
     requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
diff --git a/packages/subagent/subagent-claude-code/README.i18n.yaml b/packages/subagent/subagent-claude-code/README.i18n.yaml
index 2f6508a5e0..23450e6e42 100644
--- a/packages/subagent/subagent-claude-code/README.i18n.yaml
+++ b/packages/subagent/subagent-claude-code/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/subagent/subagent-claude-code/README.md
-README.md: e62f60fceea16749296a91377785b81d94d751ca
-README.zh.md: d83a53ea502db659e575fdac0843f5318cff2fa3
+README.md: 222cf796f71f8dc0dc2c06f7f32bab70ded6ab43
+README.zh.md: 9334820a591cbfcb8dc2046dc3a78201ba193aab
diff --git a/packages/subagent/subagent-claude-code/README.md b/packages/subagent/subagent-claude-code/README.md
index e62f60fcee..222cf796f7 100644
--- a/packages/subagent/subagent-claude-code/README.md
+++ b/packages/subagent/subagent-claude-code/README.md
@@ -8,7 +8,7 @@ This package registers the fixed `claude-code` subagent provider. Each accepted
 
 `start(request)` accepts only a non-empty sequence of text blocks and derives the child cwd from the parent Session. It creates one private `AbortController`, calls the official SDK `query()`, and publishes the run only after the SDK's `spawnClaudeCodeProcess` hook has supplied a live CLI handle owned by [`dsh-subprocess`](../../subprocess/subprocess/README.md). A failure or cancellation before publication closes the query, terminates any acquired process tree, waits for it to exit, and rejects `start()`.
 
-The SDK receives the exact concatenated text task. The provider iterates the complete SDK message stream and accepts only a `result` message with `subtype: "success"`, `is_error: false`, and a nonblank `result`, followed by normal iterator completion. Every SDK error subtype, an error-marked success, a missing answer, iterator failure, protocol failure, or process failure maps to `error`; this version produces neither `max-tokens` nor `refusal`.
+The SDK receives the exact concatenated text task. The provider iterates the complete SDK message stream and accepts only a `result` message with `subtype: "success"`, `is_error: false`, and a nonblank `result`, followed by normal iterator completion. Every SDK error subtype, an error-marked success, a missing answer, iterator failure, protocol failure, or process failure maps to `error`; the provider produces neither `max-tokens` nor `refusal`.
 
 Local cancellation wins the result race and maps to `aborted`. `dispose()` is idempotent: it aborts the run, asks the SDK query to close, invokes the shared process-tree termination escalation, and waits for whole-tree exit. SDK graceful close expresses protocol intent; the subprocess handle remains the authority for process quiescence. Result failure and independent teardown failure remain separate.
 
diff --git a/packages/subagent/subagent-claude-code/README.zh.md b/packages/subagent/subagent-claude-code/README.zh.md
index d83a53ea50..9334820a59 100644
--- a/packages/subagent/subagent-claude-code/README.zh.md
+++ b/packages/subagent/subagent-claude-code/README.zh.md
@@ -8,7 +8,7 @@
 
 `start(request)` 只接受非空的文本块序列，并根据父会话确定子级 cwd。它会创建一个私有 `AbortController`，调用官方 SDK 的 `query()`，并仅在 SDK 的 `spawnClaudeCodeProcess` 钩子已经提供由 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 管理的活动 CLI 句柄后发布此次运行。若在发布前发生失败或取消，它会关闭 query、终止所有已取得的进程树并等待其退出，然后拒绝 `start()` 调用。
 
-SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 消息流，而且只接受满足以下条件的 `result` 消息：其 `subtype: "success"`、`is_error: false` 且 `result` 非空白，之后迭代器还须正常结束。所有 SDK 错误子类型、标记为错误的成功消息、缺失答案、迭代器失败、协议失败或进程失败都映射为 `error`；本版本不会产生 `max-tokens` 或 `refusal`。
+SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 消息流，而且只接受满足以下条件的 `result` 消息：其 `subtype: "success"`、`is_error: false` 且 `result` 非空白，之后迭代器还须正常结束。所有 SDK 错误子类型、标记为错误的成功消息、缺失答案、迭代器失败、协议失败或进程失败都映射为 `error`；该提供方不会产生 `max-tokens` 或 `refusal`。
 
 本地取消会在结果竞态中胜出并映射为 `aborted`。`dispose()` 具有幂等性：它会中止此次运行、请求 SDK query 关闭、调用共享的进程树逐级终止机制，并等待整棵进程树退出。SDK 的优雅关闭只表达协议意图；进程是否完全停稳仍以子进程句柄为准。结果失败与独立的清理失败仍彼此分离。
 
diff --git a/packages/subagent/subagent-codex/README.i18n.yaml b/packages/subagent/subagent-codex/README.i18n.yaml
index d55f3ab937..cbcdb12584 100644
--- a/packages/subagent/subagent-codex/README.i18n.yaml
+++ b/packages/subagent/subagent-codex/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/subagent/subagent-codex/README.md
-README.md: c25ee90edf8972da66448fe84cb659b0aec79e6f
-README.zh.md: b302b9dd865e7b19d0c74c0d1c342edb660c242a
+README.md: c75a98550894f180d0f37e9cdd135b961488f726
+README.zh.md: 0dd3280b363c1a26250aa00cfeba5398114a2e3e
diff --git a/packages/subagent/subagent-codex/README.md b/packages/subagent/subagent-codex/README.md
index c25ee90edf..c75a985508 100644
--- a/packages/subagent/subagent-codex/README.md
+++ b/packages/subagent/subagent-codex/README.md
@@ -12,7 +12,7 @@ The published `run.result` starts exactly one turn. It accepts only notification
 
 For command and file approvals, the unattended provider selects a non-approval decision offered by the request, preferring `cancel`; the stable 0.146.0 request shape without an offered-decision list falls back to `decline`. It answers permission requests with an empty turn-scoped permission set, answers user-input requests with no answers, and declines MCP elicitation. A request with no legal unattended response, or any unknown server request, fails the run.
 
-Local cancellation wins the result race and maps to `aborted`. A failed turn whose `codexErrorInfo` is `contextWindowExceeded` maps to `max-tokens`; every other remote interrupted or failed turn maps to `error`, and this version produces no `refusal`. `dispose()` is idempotent: it requests a best-effort `turn/interrupt` with both current ids when they are known, closes the JSON-RPC wire, ends stdin, invokes the shared process-tree termination escalation, and waits for whole-tree exit. Result failure and independent teardown failure remain separate.
+Local cancellation wins the result race and maps to `aborted`. A failed turn whose `codexErrorInfo` is `contextWindowExceeded` maps to `max-tokens`; every other remote interrupted or failed turn maps to `error`, and the provider produces no `refusal`. `dispose()` is idempotent: it requests a best-effort `turn/interrupt` with both current ids when they are known, closes the JSON-RPC wire, ends stdin, invokes the shared process-tree termination escalation, and waits for whole-tree exit. Result failure and independent teardown failure remain separate.
 
 ## Capabilities and context
 
@@ -47,7 +47,7 @@ Install this package and add the following rows to your own `cordis.yml`. Shippe
 
 ## Product compatibility and evidence
 
-The production wire intentionally implements only the app-server methods required by this one-shot contract. Development evidence is pinned to `@openai/codex@0.146.0` / `codex-cli 0.146.0`: the keyless real-product spec drives the official binary against a loopback Responses service with a non-empty fake key and proves the task, authentication, exact answer, cancellation, approvals, and process-tree exit. A separate Loader composition e2e boots the README-shaped user configuration with no `codex` command available, verifies the fixed provider and foreground-only tool schema, and records zero child starts. A credentialed e2e starts the production provider and real Codex, then obtains a unique answer from the fixed official DeepSeek service through a loopback-only test bridge from Responses to Chat Completions; that bridge is not production functionality or native Codex support for DeepSeek's Chat Completions API. The npm package is a test-only dependency; deployments still supply `codex` on `PATH`.
+The production wire intentionally implements only the app-server methods required by this one-shot contract. Development evidence is pinned to `@openai/codex@0.146.0` / `codex-cli 0.146.0`; the npm package is a test-only dependency, and deployments still supply `codex` on `PATH`.
 
 ## Model Experience
 
diff --git a/packages/subagent/subagent-codex/README.zh.md b/packages/subagent/subagent-codex/README.zh.md
index b302b9dd86..0dd3280b36 100644
--- a/packages/subagent/subagent-codex/README.zh.md
+++ b/packages/subagent/subagent-codex/README.zh.md
@@ -12,7 +12,7 @@
 
 对于命令与文件审批，无人值守的提供方会从请求给出的决策选项中选择一项不予批准的决策，并优先选择 `cancel`；稳定的 0.146.0 请求形态没有决策选项列表，因此回退到 `decline`。它对权限请求返回作用域限于当前轮次的空权限集，不向用户输入请求提供任何答案，并拒绝 MCP elicitation。若请求在无人值守模式下没有合法响应，或是未知服务器请求，此次运行就会失败。
 
-本地取消会在结果竞态中胜出并映射为 `aborted`。失败轮次的 `codexErrorInfo` 若为 `contextWindowExceeded`，则映射为 `max-tokens`；其他任何远端中断或失败轮次都映射为 `error`，且本版本不会产生 `refusal`。`dispose()` 具有幂等性：如果当前的两个标识符均已知，它会尽力请求 `turn/interrupt`，关闭 JSON-RPC 通信链路，结束标准输入，调用共享的进程树逐级终止机制，并等待整棵进程树退出。结果失败与独立的清理失败仍彼此分离。
+本地取消会在结果竞态中胜出并映射为 `aborted`。失败轮次的 `codexErrorInfo` 若为 `contextWindowExceeded`，则映射为 `max-tokens`；其他任何远端中断或失败轮次都映射为 `error`，且该提供方不会产生 `refusal`。`dispose()` 具有幂等性：如果当前的两个标识符均已知，它会尽力请求 `turn/interrupt`，关闭 JSON-RPC 通信链路，结束标准输入，调用共享的进程树逐级终止机制，并等待整棵进程树退出。结果失败与独立的清理失败仍彼此分离。
 
 ## 能力与上下文
 
@@ -47,7 +47,7 @@
 
 ## 产品兼容性与证据
 
-生产环境的协议层有意只实现这一单次执行约定所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 NPM 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
+生产环境的协议层有意只实现这一单次执行约定所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`；该 NPM 包仅作为测试依赖，部署环境仍需通过 `PATH` 提供 `codex`。
 
 ## 模型体验
 
diff --git a/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts b/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
index a11a5fac86..70002b0e88 100644
--- a/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
+++ b/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
@@ -106,8 +106,6 @@ describe('dsh-subagent-fork', () => {
   })
 
   it('seeds the child with the parent\'s completed-turn prefix (child inherits context)', async () => {
-    // Parent runs one turn, then we fork. The child's seeded log should contain
-    // the parent's first turn, and the child should run its own new turn on top.
     const { ctx, parent } = await setup([textResponse('parent answer'), textResponse('child answer')])
     parent.followup(createUserMessage({ content: [{ type: 'text', text: 'parent question' }], source: { kind: 'user' } }))
     await parent.whenIdle()
diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index 47b6f7f712..8768a002b6 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -80,8 +80,8 @@ export type SubagentListEntry =
      * for any candidate whose log makes a registered unit's fold or schema
      * throw (deterministic data damage, contained per child); `unavailable`
      * when the candidate's persistence inspection failed (retried on the
-     * next listing). `unsupported` is kept for consumers already routing on
-     * it but is no longer produced.
+     * next listing). `unsupported` is never produced; it remains in the
+     * union for consumers that route on it.
      */
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
   }
@@ -439,10 +439,7 @@ const LIFECYCLE_WITNESS_KEYS = [
   'version', 'id', 'createdAt', 'cwd', 'parentSession', 'seedLength', 'delegationDepth',
 ] as const
 
-/**
- * Whether an inspected log still belongs to the enumerated lifecycle,
- * mirroring the retired query-source compatibility check's field set.
- */
+/** Whether an inspected log still belongs to the enumerated lifecycle. */
 function sameLifecycle(meta: SessionHeader, expected: SessionHeader): boolean {
   return LIFECYCLE_WITNESS_KEYS.every(key => meta[key] === expected[key])
 }
diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts
index f83b65f559..b1df485644 100644
--- a/packages/subagent/subagent/src/types.ts
+++ b/packages/subagent/subagent/src/types.ts
@@ -294,7 +294,7 @@ export interface SubagentProvider {
   /**
    * OPTIONAL (continuable-creation capability): contribute the detached
    * creation inputs that distinguish this provider's continuable children —
-   * today only whether the child session is seeded with parent history. Method
+   * only whether the child session is seeded with parent history. Method
    * presence IS the capability: the service rejects continuable starts on
    * providers without it, while a provider that has it may still serve
    * ordinary one-shot delegations.
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index f0e9a8a597..a9be76e0c0 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-local/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/subprocess/subprocess-local/README.md
-README.md: ed2b4c3558aa034c8d9fa1049c81d6628c86dff7
-README.zh.md: 832a82dc6a12096e85a1b939f5021767a3c5cb68
+README.md: 15fc001b9fcf2eadd7b37415fd92386565b649c3
+README.zh.md: 48b662302183f07d514f975089d4b49bd17c8e69
diff --git a/packages/subprocess/subprocess-local/README.md b/packages/subprocess/subprocess-local/README.md
index ed2b4c3558..15fc001b9f 100644
--- a/packages/subprocess/subprocess-local/README.md
+++ b/packages/subprocess/subprocess-local/README.md
@@ -4,9 +4,9 @@ English | [中文](README.zh.md)
 
 Local Service provider for the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessService` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling capability seams ([`dsh-bash-local`](../../bash/bash-local/README.md), [`dsh-lsp-local`](../../lsp/lsp-local/README.md), and [`dsh-pty-local`](../../pty/pty-local/README.md)).
 
-## Behavior (and where it came from)
+## Behavior
 
-- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F`. `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — the same caveat as the surveyed tools.
+- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F`. `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive.
 - **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
 - **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index 832a82dc6a..48b6623021 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -4,9 +4,9 @@
 
 [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地 Service provider。`LocalSubprocessService` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方能力 seam（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md) 和 [`dsh-pty-local`](../../pty/pty-local/README.md)）。
 
-## 行为（以及设计来源）
+## 行为
 
-- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活，这与所调研工具的局限相同。
+- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活。
 - **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
 - **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
diff --git a/packages/subprocess/subprocess/src/index.ts b/packages/subprocess/subprocess/src/index.ts
index 0eaed5620b..081ff436ec 100644
--- a/packages/subprocess/subprocess/src/index.ts
+++ b/packages/subprocess/subprocess/src/index.ts
@@ -108,8 +108,8 @@ export abstract class SubprocessService extends Service {
    * Resolve one configured executable in this provider's execution world.
    * Absolute paths are verified; bare names use the provider's scrubbed PATH
    * plus explicit environment overrides. Relative paths containing separators
-   * are rejected: no current consumer defines which directory they would
-   * resolve against, so providers fail loud instead of guessing.
+   * are rejected: the resolution base is undefined, so providers fail loud
+   * instead of guessing.
    * @param command - absolute executable path or bare PATH name.
    * @param env - explicit environment entries used for lookup.
    * @param signal - aborts remote or local lookup.
diff --git a/packages/support/acp-snapshot/README.i18n.yaml b/packages/support/acp-snapshot/README.i18n.yaml
index bf71e04e3e..5898c5beb1 100644
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/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/support/acp-snapshot/README.md
-README.md: 0b935ef60c33fd24660d8ecf2497f5506157c724
-README.zh.md: 7c1c3328ab8490c7eebd4b2492bc4ae6f4fcd5a5
+README.md: 8a9669b1f555fceb7af6d017d273b62d7dcad1e1
+README.zh.md: efa31df86d3b494ab14fc3742fc84adce570a593
diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md
index 0b935ef60c..8a9669b1f5 100644
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -11,7 +11,7 @@ Four layers, importable separately:
 - **Normalizers** — pure functions turning captured surfaces into stable text or portable fixtures: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs and every native/JavaScript filesystem spelling of the generated cwd → tokens, longest-first; cwd-rooted separators selected as canonical `/` or host-native; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `tokenizeSessionFixtureCwd` (the generated workspace and its filesystem aliases → one canonical `{{cwd}}`, including an already-tokenized macOS `/private` alias; authored temp paths unchanged), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)), and `stabilizeFixtureMessageIds` (committed UUIDs carried into unchanged, mutually unique messages by structurally rewriting only complete surface and durable-inbox message ID fields across any recorder's fixture-ready parent/child logs).
 - **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario expected-output and re-persisted-log comparisons, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, a tokenized pin per header class composed with independently shared `system-prompt.expected.md` and `tool-schemas.expected.json` sidecars, and a live uniformity guard. Its fixture guards reject orphan scenario dirs, missing files, multiple pins for one class, duplicate sidecar content, noncanonical macOS-prefixed cwd tokens, unscrubbed JSONL headers, and malformed pinning headers. Before record or refresh writes fixtures, an unchanged complete message retains its committed UUID only when both its ID and identity-free fingerprint are unique across the scenario's fixture-ready parent/child logs; the session package's authoritative surface-type predicate selects surface carriers, correlated `agent/inbox/spliced` copies join the same mapping, and only validated `id` fields in those carriers are rewritten. New, changed, malformed, and graph-ambiguous messages keep fresh UUIDs. Refresh evaluates fresh leaves with the harvested run's ids, cwd, and every cwd alias, then reuses normalized-equivalent leaves only when the complete logical-record layout aligns and volatile string replacements form a bijection; complete message IDs in surface or inbox carriers are excluded because the later structural pass owns them, ambiguous logs keep fresh strings, and fresh semantic values remain authoritative. It also expands packed timing envelopes before aligning event times, so switching between packed and unpacked layouts cannot shift later records. A newly inserted `session/title` receives its preceding event's time so feature-driven insertions do not churn the remainder of a fixture. Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.
 
-Committed session fixtures use canonical packed rows. An in-flight branch that merges this contract runs the [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) with `pnpm run migrate:packed-session-fixtures`; its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns deletion after affected branches converge.
+Committed session fixtures use canonical packed rows; the [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) (`pnpm run migrate:packed-session-fixtures`) rewrites older fixture layouts, and its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns its deletion.
 
 A consuming `*.snapshot.ts` is the scenario table plus one factory call:
 
diff --git a/packages/support/acp-snapshot/README.zh.md b/packages/support/acp-snapshot/README.zh.md
index 7c1c3328ab..efa31df86d 100644
--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -11,7 +11,7 @@ ACP 快照套件工具包：无密钥快照层（`pnpm run test:snapshot`，见[
 - **规范化器**：将已捕获接口转换为稳定文本或可移植 fixture 的纯函数：`normalizeStdout`（JSON-RPC id → 首次出现序列；UUID 以及生成 cwd 的每种原生／JavaScript 文件系统写法 → token，按最长优先；根据 cwd 的分隔符选择规范 `/` 或宿主原生形式；同时作为 stdout 纯度检查）、`normalizeSessionLog`（时间归零、保留 `seq`、使用同一 cwd 路径策略）、`tokenizeSessionFixtureCwd`（生成的 workspace 及其文件系统别名，包括已进行 token 化的 macOS `/private` 别名 → 单一规范 `{{cwd}}`；手工编写的临时路径保持不变）、`scrubSystemPrompts`（提示词文本 → `{{system}}`）、`scrubToolSchemas`（schema bulk → `{{tools}}`）、`scrubRequestHeaders`（每个 pin 之外的所有 header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}`，保留结构；见[header 固定 Agent Note](../../../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）和 `stabilizeFixtureMessageIds`（针对任意录制器已准备写入 fixture 的父级/子级日志，通过结构化方式仅改写 surface 和持久 inbox 中完整消息的 ID 字段，将已提交 UUID 带入未变化且双向唯一匹配的消息）。
 - **`defineAcpSnapshotSuite`（工厂）**：为场景表注册完整 describe/it 树：每场景预期输出与重新持久化日志比较、录制/刷新 fixture 回写、拒绝结构化 `UNKNOWN_TOOL` 结果、每个 header 类别一个 token 化 pin（由可独立共享的 `system-prompt.expected.md` 和 `tool-schemas.expected.json` sidecar 组合而成），以及实时一致性保护。其 fixture 保护会拒绝遗留场景目录、缺失文件、一个类别包含多个 pin、重复的 sidecar 内容、带非规范 macOS 前缀的 cwd token、未擦除的 JSONL header，以及格式错误的 pin header。在录制或刷新模式写入 fixture 前，仅当一条未变化完整消息的 ID 及其去除身份后的指纹在场景可写入 fixture 的父级/子级日志中均唯一时，该消息才会保留已提交的 UUID；会话包的权威 surface 类型谓词负责选择 surface 载体，与其关联的 `agent/inbox/spliced` 副本也纳入同一映射，且仅改写这些载体中通过验证的 `id` 字段。新增、发生变化、格式错误以及图关系存在歧义的消息保留本次生成的 UUID。刷新会使用收集所得本次运行的 id、cwd 及全部 cwd 别名评估本次生成的叶值；只有完整逻辑记录布局对齐且易变字符串替换形成双射时，才会复用归一化后等价的叶值；surface 或 inbox 载体中的完整消息 ID 不参与此路径，因为后续结构化处理负责这些 ID；有歧义的日志保留本次生成的字符串，而本次生成的语义值仍为权威数据。它还会在对齐事件时间前展开打包时序 envelope，因此切换打包/非打包布局无法移动后续记录。新插入的 `session/title` 使用前一个事件的时间，因此功能驱动的插入不会扰动 fixture 余下部分。每个场景目录的 `session.jsonl` 和连续 `session.<n>.jsonl` 同级文件构成有序的主会话／子会话清单；场景表不重复其数量。必须在 vitest 收集时调用。
 
-签入仓库的会话 fixture 使用规范打包行。合并此约定的在途分支通过 `pnpm run migrate:packed-session-fixtures` 运行[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)；待受影响分支收敛后，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
+签入仓库的会话 fixture 使用规范打包行；[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)（`pnpm run migrate:packed-session-fixtures`）会改写较旧的 fixture 布局，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md)负责删除该迁移器。
 
 消费方 `*.snapshot.ts` 就是场景表加一次工厂调用：
 
diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts
index c68be45c00..d37bf289b5 100644
--- a/packages/support/acp-snapshot/src/harness.ts
+++ b/packages/support/acp-snapshot/src/harness.ts
@@ -760,8 +760,8 @@ async function harvestSessionLogs(root: string): Promise<HarvestedLog[]> {
     })
   }
   // Primary (no parentSession) first, then children by ascending createdAt. A
-  // scenario has exactly one top-level session. In the synchronous cut sibling
-  // children are created strictly sequentially, so their createdAt values are
+  // scenario has exactly one top-level session. Subagent children are created
+  // synchronously and strictly sequentially, so their createdAt values are
   // strictly ordered; the recordedId tiebreak only keeps a degenerate
   // same-millisecond collision (unreachable here) deterministic. This harvest
   // order must match the replay load order in dsh-llm-replay's loadSessionScripts
diff --git a/packages/support/llm-replay/README.i18n.yaml b/packages/support/llm-replay/README.i18n.yaml
index 47650ae4de..6d048c2325 100644
--- a/packages/support/llm-replay/README.i18n.yaml
+++ b/packages/support/llm-replay/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/support/llm-replay/README.md
-README.md: a6c087778b8e64124590fb6be7a652b58e1b6343
-README.zh.md: 05dcf994962ba37b58cfb18a68f0d3819d34db0a
+README.md: ae7cb5414a28bcf33f9878f6f02220861df9a0d5
+README.zh.md: 2acc0ff8e8c011126452ba3458aaeb0800d9d8f3
diff --git a/packages/support/llm-replay/README.md b/packages/support/llm-replay/README.md
index a6c087778b..ae7cb5414a 100644
--- a/packages/support/llm-replay/README.md
+++ b/packages/support/llm-replay/README.md
@@ -20,7 +20,7 @@ A scripted string may embed `{{fromRequest:<regex>}}` to fill a value no static
 
 A scenario where a parent agent delegates to in-process subagents records more than one log: the parent (`session.jsonl`) plus one per child (`session.1.jsonl`, …). Each agent runs as its own `Session` on the same context, so replay must serve each one its own script.
 
-Replay keys every call by its calling session id (`GenerateOptions.sessionId`, stamped by the agent loop). Live session ids are freshly random each run and never equal the recorded ones, so a live session binds to a recorded script by **first-call order**: scripts are ordered by header `createdAt` (parent first — it streams before it can delegate), and the first live session to make any call claims the first script, the next new session the next, and so on. Each session then advances its own cursor. A call with no `sessionId` is one anonymous session bound to the primary script, so single-session scenarios behave exactly as before. More distinct live sessions than recorded scripts fails loud.
+Replay keys every call by its calling session id (`GenerateOptions.sessionId`, stamped by the agent loop). Live session ids are freshly random each run and never equal the recorded ones, so a live session binds to a recorded script by **first-call order**: scripts are ordered by header `createdAt` (parent first — it streams before it can delegate), and the first live session to make any call claims the first script, the next new session the next, and so on. Each session then advances its own cursor. A call with no `sessionId` is one anonymous session bound to the primary script. More distinct live sessions than recorded scripts fails loud.
 
 ## Config
 
diff --git a/packages/support/llm-replay/README.zh.md b/packages/support/llm-replay/README.zh.md
index 05dcf99496..2acc0ff8e8 100644
--- a/packages/support/llm-replay/README.zh.md
+++ b/packages/support/llm-replay/README.zh.md
@@ -20,7 +20,7 @@ fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `as
 
 父 agent 委托给进程内 subagent 的场景会记录多个日志：父会话使用 `session.jsonl`，每个子会话各使用一个日志（`session.1.jsonl` 等）。每个 agent 都在同一上下文中作为独立的 `Session` 运行，因此回放必须为每个 agent 提供各自的脚本。
 
-回放根据发起调用的会话 id 为每次调用建立键（`GenerateOptions.sessionId` 由 agent loop 写入）。实时会话 id 每次运行时都会重新随机生成，绝不会等于记录中的 id，因此实时会话按**首次调用顺序**绑定到已记录脚本：脚本按 header 中的 `createdAt` 排序（父会话在前，因为它必须先开始流式输出才能委托）；第一个发起调用的实时会话取得第一个脚本，下一个新会话取得下一个脚本，以此类推。此后每个会话分别推进自己的游标。没有 `sessionId` 的调用视为一个绑定主脚本的匿名会话，因此单会话场景的行为与以前完全相同。不同实时会话的数量超过已记录脚本数时会明确报错。
+回放根据发起调用的会话 id 为每次调用建立键（`GenerateOptions.sessionId` 由 agent loop 写入）。实时会话 id 每次运行时都会重新随机生成，绝不会等于记录中的 id，因此实时会话按**首次调用顺序**绑定到已记录脚本：脚本按 header 中的 `createdAt` 排序（父会话在前，因为它必须先开始流式输出才能委托）；第一个发起调用的实时会话取得第一个脚本，下一个新会话取得下一个脚本，以此类推。此后每个会话分别推进自己的游标。没有 `sessionId` 的调用视为一个绑定主脚本的匿名会话。不同实时会话的数量超过已记录脚本数时会明确报错。
 
 ## 配置
 
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 26b690437c..5bfbe4e5a8 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -49,10 +49,9 @@ declare module 'cordis' {
  */
 export abstract class TaskService extends Service {
   constructor(ctx: Context) {
-    // `abstract` erases at runtime, and this package name used to be the
-    // mountable concrete registry — a stale composition row would otherwise
-    // register a ctx.tasks with no method implementations and fail far from
-    // the misconfiguration. Fail loud at load instead.
+    // `abstract` erases at runtime, so a composition row naming this package
+    // would register a ctx.tasks with no method implementations and fail far
+    // from the misconfiguration. Fail loud at load instead.
     if (new.target === TaskService) {
       throw new Error('@deepseek-ai/dsh-tasks is the abstract task registry seam; load an implementation such as @deepseek-ai/dsh-tasks-local instead')
     }
diff --git a/packages/todo/tool-todo/src/index.ts b/packages/todo/tool-todo/src/index.ts
index 0e403c5510..12e0d164c6 100644
--- a/packages/todo/tool-todo/src/index.ts
+++ b/packages/todo/tool-todo/src/index.ts
@@ -143,7 +143,6 @@ export function apply(ctx: Context, config: Config): void {
         return state
       },
       view: state => state,
-      // Fold semantics changed: turn/start clears the standing plan (was last-write-wins only).
       stateVersion: 2,
     })
   })
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index 1950c255cb..de074f3c80 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -772,7 +772,7 @@ const BANNER = [
 ]
 
 /** The shared GENERATED + freshness-gate + fence notice paragraph. */
-const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
+const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method; type names in a signature link to the page that documents them.'
 
 /**
  * Render one page's generated `cordis-surface` region: the services mapped to
diff --git a/packages/util/retention/README.i18n.yaml b/packages/util/retention/README.i18n.yaml
index 62be2bd3ea..c8fcb0c274 100644
--- a/packages/util/retention/README.i18n.yaml
+++ b/packages/util/retention/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/util/retention/README.md
-README.md: 45c88e9fc2d8df98f935fd1c3b43c4622802bd2a
-README.zh.md: 9419245908d7331c9db24019f1181fcaed848060
+README.md: 4f4dda8d8a93cd4cdcc4b3c0d2cc575f21159ffb
+README.zh.md: 9ce48c66566dca449cf6c1090f5ef4785e046769
diff --git a/packages/util/retention/README.md b/packages/util/retention/README.md
index 45c88e9fc2..4f4dda8d8a 100644
--- a/packages/util/retention/README.md
+++ b/packages/util/retention/README.md
@@ -23,7 +23,7 @@ import type {
 
 | Export | Role |
 |---|---|
-| `ItemRetainer<T>` | Bounds ordered logical units (paths, grep matches, sources). `head` only in v1. `push()` → `PushDecision`; `finish()` → `RetainedItems<T>`. |
+| `ItemRetainer<T>` | Bounds ordered logical units (paths, grep matches, sources). `head` only. `push()` → `PushDecision`; `finish()` → `RetainedItems<T>`. |
 | `TextRetainer` | Bounds a byte-oriented text stream. `head` / `tail` / `headTail`, UTF-8 boundaries preserved at `finish()`. `push()` → `PushDecision`; `finish()` → `RetainedText`. |
 | `describeOmitted(omitted, unit)` | Standardized omission clause (`exact` prints a count; `unknown` does not). |
 | `formatRetentionNotice(notice, recovery)` | Joins the standardized omission clause with the tool's own recovery guidance. |
diff --git a/packages/util/retention/README.zh.md b/packages/util/retention/README.zh.md
index 9419245908..9ce48c6656 100644
--- a/packages/util/retention/README.zh.md
+++ b/packages/util/retention/README.zh.md
@@ -23,7 +23,7 @@ import type {
 
 | 导出项 | 职责 |
 |---|---|
-| `ItemRetainer<T>` | 限制有序逻辑单元（路径、grep 匹配项、来源）。v1 只支持 `head`。`push()` → `PushDecision`；`finish()` → `RetainedItems<T>`。 |
+| `ItemRetainer<T>` | 限制有序逻辑单元（路径、grep 匹配项、来源）。只支持 `head`。`push()` → `PushDecision`；`finish()` → `RetainedItems<T>`。 |
 | `TextRetainer` | 限制面向字节的文本流。`head` / `tail` / `headTail`，并在 `finish()` 时保留 UTF-8 边界。`push()` → `PushDecision`；`finish()` → `RetainedText`。 |
 | `describeOmitted(omitted, unit)` | 标准化的省略子句（`exact` 输出数量；`unknown` 不输出）。 |
 | `formatRetentionNotice(notice, recovery)` | 将标准化的省略子句与工具自有的恢复指引连接起来。 |
diff --git a/packages/util/retention/src/index.ts b/packages/util/retention/src/index.ts
index 07547a7d93..1aca8b6aaf 100644
--- a/packages/util/retention/src/index.ts
+++ b/packages/util/retention/src/index.ts
@@ -211,8 +211,7 @@ const decoder = new TextDecoder() // utf-8, non-fatal: internal malformed bytes
 function trimTrailingPartialUtf8(bytes: Uint8Array): Uint8Array {
   let i = bytes.length - 1
   // Continuation bytes are 0b10xxxxxx; scan back at most 3 (max sequence is 4).
-  // Indices are bounds-checked by the loop guard, so the reads are in range (a
-  // cast, not `!`, per the repo's no-non-null-assertion rule).
+  // Indices are bounds-checked by the loop guard, so the reads are in range.
   while (i >= 0 && ((bytes[i] as number) & 0xc0) === 0x80 && bytes.length - i <= 3) i--
   if (i < 0) return bytes
   const lead = bytes[i] as number
@@ -228,7 +227,7 @@ function trimTrailingPartialUtf8(bytes: Uint8Array): Uint8Array {
  */
 function trimLeadingContinuationUtf8(bytes: Uint8Array): Uint8Array {
   let i = 0
-  // i < length guards the read; cast rather than `!` (no-non-null-assertion).
+  // i < length guards the read.
   while (i < bytes.length && ((bytes[i] as number) & 0xc0) === 0x80) i++
   return bytes.subarray(i)
 }
diff --git a/packages/util/timeout/README.i18n.yaml b/packages/util/timeout/README.i18n.yaml
index c1ebb419ca..134992bf60 100644
--- a/packages/util/timeout/README.i18n.yaml
+++ b/packages/util/timeout/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/util/timeout/README.md
-README.md: e0d3595e7771fd19c808e89d440e69bca40da286
-README.zh.md: 99b7f281c2af7746fc2a105ee08df870fd3a9583
+README.md: 40a655200780e25c434beed4953d96f46e3604fd
+README.zh.md: 638dc1af60761f9c964e356edc070d20af0f4819
diff --git a/packages/util/timeout/README.md b/packages/util/timeout/README.md
index e0d3595e77..40a6552007 100644
--- a/packages/util/timeout/README.md
+++ b/packages/util/timeout/README.md
@@ -52,7 +52,7 @@ For a streamed transport, create one `idleWatchdog`, pass its stable `signal` in
 
 ## What does NOT get a timeout
 
-Local file `read`/`write`/`edit` take no `timeoutMs`: a syscall is best-effort-abortable at most, a timeout could not force `fsync`/`rename` to stop, and adding one would be an implicit default that violates explicit-over-implicit. See [`fs/`](../../fs/README.md).
+Local file `read`/`write`/`edit` take no `timeoutMs`: file IO runs untimed because a deadline would kill work the OS will still finish. See [the filesystem subsystem page](../../../docs/subsystems/filesystem.md).
 
 ## Model Experience
 
diff --git a/packages/util/timeout/README.zh.md b/packages/util/timeout/README.zh.md
index 99b7f281c2..638dc1af60 100644
--- a/packages/util/timeout/README.zh.md
+++ b/packages/util/timeout/README.zh.md
@@ -52,7 +52,7 @@ export async function runWithDeadline(upstream: AbortSignal | undefined, timeout
 
 ## 哪些操作不设置超时
 
-本地文件 `read`/`write`/`edit` 不接受 `timeoutMs`：中止系统调用至多只能尽力而为，超时无法强制 `fsync`/`rename` 停止，而添加超时会引入一个违反显式优于隐式原则的隐式默认值。详见 [`fs/`](../../fs/README.md)。
+本地文件 `read`/`write`/`edit` 不接受 `timeoutMs`：文件 IO 不设时限地运行，因为截止时间会中止操作系统仍会完成的工作。详见[文件系统子系统页面](../../../docs/subsystems/filesystem.md)。
 
 ## 模型体验
 
diff --git a/packages/web/web-search-deepseek/README.i18n.yaml b/packages/web/web-search-deepseek/README.i18n.yaml
index 4d5ac9d768..41b7516362 100644
--- a/packages/web/web-search-deepseek/README.i18n.yaml
+++ b/packages/web/web-search-deepseek/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/web/web-search-deepseek/README.md
-README.md: 95340314fe08d0963b899f4a1d704a98f85963a5
-README.zh.md: cf83426f70d6d2a77fd9acf5e927d1b13ec345eb
+README.md: fb9e528633954b8eb9fd0fec8d19e24381a63f12
+README.zh.md: 4e761aa6ef1a67ce17fbc1cabf595af7f24e15e6
diff --git a/packages/web/web-search-deepseek/README.md b/packages/web/web-search-deepseek/README.md
index 95340314fe..fb9e528633 100644
--- a/packages/web/web-search-deepseek/README.md
+++ b/packages/web/web-search-deepseek/README.md
@@ -10,7 +10,7 @@ This is an **implementation** package: it registers a provider into `ctx.web`, r
 
 Exa and Perplexity expose dedicated search endpoints; DeepSeek does not. Instead this provider issues a **full Messages model call** carrying the `web_search` server tool, so one search costs a complete model turn in latency and tokens — heavier than a pure retrieval endpoint. DeepSeek runs the search server-side and returns **structured** `web_search_tool_result` blocks; the provider parses those blocks and **never scrapes URLs out of model prose**.
 
-**Strict mode**: if the response carries no `web_search_tool_result` block (native search did not trigger), the provider throws `WebError` `WEB_PROVIDER_ERROR` rather than degrading to prose-scraping — honest and debuggable.
+**Strict mode**: if the response carries no `web_search_tool_result` block (native search did not trigger), the provider throws `WebError` `WEB_PROVIDER_ERROR` rather than degrading to prose-scraping.
 
 It reuses the `DEEPSEEK_API_KEY` credential reference (no new secret) but **not** `$DEEPSEEK_BASE_URL`: the search endpoint is the Anthropic-compatible base (`https://api.deepseek.com/anthropic/v1`), distinct from the chat-completions base (`https://api.deepseek.com`) the LLM adapter uses. A mounted credentials service is authoritative; without one, the provider falls back to the launching process environment. The reference is resolved for each search, so a key stored or rotated by the Web Models page reaches the next call without a restart.
 
diff --git a/packages/web/web-search-deepseek/README.zh.md b/packages/web/web-search-deepseek/README.zh.md
index cf83426f70..4e761aa6ef 100644
--- a/packages/web/web-search-deepseek/README.zh.md
+++ b/packages/web/web-search-deepseek/README.zh.md
@@ -10,7 +10,7 @@
 
 Exa 和 Perplexity 提供专用搜索端点，DeepSeek 则没有。该提供方改为发起一次携带 `web_search` 服务器工具的**完整 Messages 模型调用**，因此一次搜索会消耗完整模型轮次的延迟与 token，比纯检索端点更重。DeepSeek 在服务器侧执行搜索，返回**结构化** `web_search_tool_result` 块；提供方解析这些块，**绝不会从模型文本中抓取 URL**。
 
-**严格模式**：如果响应不含 `web_search_tool_result` 块（未触发原生搜索），提供方会抛出 `WebError` `WEB_PROVIDER_ERROR`，而非降级为文本抓取；这种行为诚实且可诊断。
+**严格模式**：如果响应不含 `web_search_tool_result` 块（未触发原生搜索），提供方会抛出 `WebError` `WEB_PROVIDER_ERROR`，而非降级为文本抓取。
 
 它复用 `DEEPSEEK_API_KEY` 凭据引用（不增加密钥），但**不会**复用 `$DEEPSEEK_BASE_URL`：搜索端点使用 Anthropic 兼容基址（`https://api.deepseek.com/anthropic/v1`），不同于大语言模型（LLM）适配器使用的 chat-completions 基址（`https://api.deepseek.com`）。已挂载的凭据服务具有权威性；没有该服务时，提供方会回退到启动进程的环境变量。每次搜索都会解析该引用，因此在 Web 的 Models 页中存储或轮换的密钥无需重启，即可用于下一次调用。
 
diff --git a/packages/web/web/README.i18n.yaml b/packages/web/web/README.i18n.yaml
index 6f079335f9..b3f2024458 100644
--- a/packages/web/web/README.i18n.yaml
+++ b/packages/web/web/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/web/web/README.md
-README.md: 22301a144b2e06ab42e1d503e8f8c554f7886330
-README.zh.md: 027b863cd7835f378de5f5c5d41166938b8cfe1a
+README.md: 2acb5022a83c08c33a26be626a93b7355c07a0ed
+README.zh.md: b77b0a897082dba01e10be3f7b0ca3b3f0260a9f
diff --git a/packages/web/web/README.md b/packages/web/web/README.md
index 22301a144b..2acb5022a8 100644
--- a/packages/web/web/README.md
+++ b/packages/web/web/README.md
@@ -14,7 +14,7 @@ This package owns the Service Definition role of the web capability. Unlike bash
 | `@deepseek-ai/dsh-web-fetch-local` | Fetch provider: anonymous public HTTP(S) |
 | `@deepseek-ai/dsh-tool-web` | Consumer: the model-facing `web_search` / `web_fetch` tool schemas over `ctx.web` |
 
-Search and fetch share no request schema and no business logic, but they are deliberately one seam: `ctx.web` is a single web-access middle layer with one provider-selection policy owner, one abort/error vocabulary, and one product-facing "how this harness reaches the web" config surface. The cost is the parallel `Search`/`Fetch` method pairs; that parallelism is intentional, not a missed extraction.
+Search and fetch share no request schema and no business logic, but they are deliberately one seam: `ctx.web` is a single web-access middle layer with one provider-selection policy owner, one abort/error vocabulary, and one product-facing "how this harness reaches the web" config surface. The `Search`/`Fetch` method pairs are deliberately parallel.
 
 ## Service API (`ctx.web`)
 
diff --git a/packages/web/web/README.zh.md b/packages/web/web/README.zh.md
index 027b863cd7..b77b0a8970 100644
--- a/packages/web/web/README.zh.md
+++ b/packages/web/web/README.zh.md
@@ -14,7 +14,7 @@
 | `@deepseek-ai/dsh-web-fetch-local` | 抓取提供方：匿名公共 HTTP(S) |
 | `@deepseek-ai/dsh-tool-web` | Consumer：面向模型的 `web_search`／`web_fetch` 工具 schema，构建于 `ctx.web` 之上 |
 
-搜索与抓取没有共享请求 schema 或业务逻辑，但有意共用一个 seam：`ctx.web` 是单一 web 访问中间层，拥有一项提供方选择策略、一套中止／错误词汇和一个面向产品的「该 harness 如何访问 web」配置接口。代价是成对的并行 `Search`／`Fetch` 方法；这种并行是有意设计，并非遗漏了可抽取的共性。
+搜索与抓取没有共享请求 schema 或业务逻辑，但有意共用一个 seam：`ctx.web` 是单一 web 访问中间层，拥有一项提供方选择策略、一套中止／错误词汇和一个面向产品的「该 harness 如何访问 web」配置接口。成对的 `Search`／`Fetch` 方法保持并行是有意为之。
 
 ## 服务 API（`ctx.web`）
 
diff --git a/packages/web/web/src/types.ts b/packages/web/web/src/types.ts
index 1216d09848..316b6b5c11 100644
--- a/packages/web/web/src/types.ts
+++ b/packages/web/web/src/types.ts
@@ -26,7 +26,8 @@ export interface WebSearchRequest {
 
 /**
  * Normalized search outcome. `content` is optional provider-generated answer
- * text or summary (Exa returns none; Perplexity returns a generated answer).
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
+ * generated answer).
  * `sources[]` is the portable citation surface. `truncated` is set by the seam
  * when it cut `sources[]` down to `maxResults`.
  */
@@ -86,8 +87,8 @@ export interface WebFetchResult {
  * new kind is a coordinated change across known packages, not a plugin
  * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
  * so adding a kind breaks compilation at every consumer until handled. Each arm
- * stays its own object literal even where fields coincide today, leaving room
- * for arm-specific fields later (a `pdf` body's `pageCount`).
+ * stays its own object literal even where fields coincide, so an arm can gain
+ * fields the others lack.
  */
 export type WebFetchBody =
   | { readonly kind: 'html'; readonly content: string }
diff --git a/packages/workflow/tool-workflow/README.i18n.yaml b/packages/workflow/tool-workflow/README.i18n.yaml
index 66212b2fb9..219318f8f3 100644
--- a/packages/workflow/tool-workflow/README.i18n.yaml
+++ b/packages/workflow/tool-workflow/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/workflow/tool-workflow/README.md
-README.md: 5afa68764bfe339377954f8912b6f9b795435be1
-README.zh.md: 7f18c6f54332e11ea54a927ef2d7b723c2601c05
+README.md: 4b75ce5b6a248949f135bfe1883680a645a4c774
+README.zh.md: 930da9d0975cd334a7a7cabf59958a9e11106861
diff --git a/packages/workflow/tool-workflow/README.md b/packages/workflow/tool-workflow/README.md
index 5afa68764b..4b75ce5b6a 100644
--- a/packages/workflow/tool-workflow/README.md
+++ b/packages/workflow/tool-workflow/README.md
@@ -10,7 +10,7 @@ Three parameters: `meta` (required identity data: `name`, `description`, and opt
 
 ## Lifecycle
 
-Collection is SYNCHRONOUS this cut (like [`dsh-tool-subagent`](../../subagent/tool-subagent/README.md)): `execute` starts a run and awaits `run.result` inside a `try/finally` that always disposes the run, so the script and its children reach quiescence on every path. `exec.signal` is bridged to `run.cancel()` (including the already-aborted-before-start case). A non-`completed` stop reason maps to an `isError` result reporting the reason—never partial output as success; a parse/meta failure thrown synchronously by `start()` becomes an `isError` the model can correct from. Completion returns canonical `{ runId, agentsStarted, result }`; the Native renderer preserves the meta name, agent count, and JSON value, truncating only that projection at `maxResultChars`.
+Collection is synchronous (like [`dsh-tool-subagent`](../../subagent/tool-subagent/README.md)): `execute` starts a run and awaits `run.result` inside a `try/finally` that always disposes the run, so the script and its children reach quiescence on every path. `exec.signal` is bridged to `run.cancel()` (including the already-aborted-before-start case). A non-`completed` stop reason maps to an `isError` result reporting the reason—never partial output as success; a parse/meta failure thrown synchronously by `start()` becomes an `isError` the model can correct from. Completion returns canonical `{ runId, agentsStarted, result }`; the Native renderer preserves the meta name, agent count, and JSON value, truncating only that projection at `maxResultChars`.
 
 ## Render intent
 
diff --git a/packages/workflow/tool-workflow/README.zh.md b/packages/workflow/tool-workflow/README.zh.md
index 7f18c6f543..930da9d097 100644
--- a/packages/workflow/tool-workflow/README.zh.md
+++ b/packages/workflow/tool-workflow/README.zh.md
@@ -10,7 +10,7 @@
 
 ## 生命周期
 
-当前版本采用同步收集（类似 [`dsh-tool-subagent`](../../subagent/tool-subagent/README.md)）：`execute` 启动运行并等待 `run.result`；这些操作位于 `try/finally` 中，该结构总会 dispose（资源释放）运行，使脚本及其子 agent（智能体）在每条路径上完全停稳。`exec.signal` 会桥接到 `run.cancel()`，包括启动前已经中止的情况。非 `completed` 结束原因会映射为报告原因的 `isError` 结果，绝不会把局部输出当作成功；`start()` 同步抛出的解析/meta 失败会变成模型可据以修正的 `isError`。完成时返回规范值 `{ runId, agentsStarted, result }`；Native 渲染器保留 meta 名称、agent 数量和 JSON 值，只会在 `maxResultChars` 处截断该投影。
+收集是同步的（类似 [`dsh-tool-subagent`](../../subagent/tool-subagent/README.md)）：`execute` 启动运行并等待 `run.result`；这些操作位于 `try/finally` 中，该结构总会 dispose（资源释放）运行，使脚本及其子 agent（智能体）在每条路径上完全停稳。`exec.signal` 会桥接到 `run.cancel()`，包括启动前已经中止的情况。非 `completed` 结束原因会映射为报告原因的 `isError` 结果，绝不会把局部输出当作成功；`start()` 同步抛出的解析/meta 失败会变成模型可据以修正的 `isError`。完成时返回规范值 `{ runId, agentsStarted, result }`；Native 渲染器保留 meta 名称、agent 数量和 JSON 值，只会在 `maxResultChars` 处截断该投影。
 
 ## 渲染意图
 
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 7991a7355e..06b115ecee 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -434,7 +434,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'seam',
     implementations: ['compact-basic'],
     consumers: ['compact-basic'],
-    note: 'The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred.',
+    note: 'The basic backend consumes post-step pressure and request-error recovery events; there is no model-facing compact tool.',
   },
   {
     key: 'subagents',
@@ -1117,7 +1117,7 @@ function renderEventRelations(pkgs: Pkg[], events: readonly EventEntry[]): strin
   const maintenance = 'generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program'
   const lines = generatedHeader('Event Producer And Consumer Matrix')
   lines.push(
-    'This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.',
+    'This matrix shows which packages dispatch each harness-owned event and which packages listen to it. Events are many-to-many, so the dense relation data is presented as a table rather than one large graph. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.',
     '',
     '| Event | Mode | Declared in | Dispatchers | Listeners |',
     '| --- | --- | --- | --- | --- |',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 1ed6c37f40..942a9ec9e0 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -221,7 +221,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolPwsh)
     },
     note:
-      'The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session; ConPTY is roadmap work), with native `C:\\...` paths and `$env:NAME` variables.',
+      'The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\\...` paths and `$env:NAME` variables.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-cordis',
diff --git a/scripts/hero-composer-dom-continuity.mjs b/scripts/hero-composer-dom-continuity.mjs
index ef39052b1b..187221f218 100644
--- a/scripts/hero-composer-dom-continuity.mjs
+++ b/scripts/hero-composer-dom-continuity.mjs
@@ -1,4 +1,4 @@
-// Regression drive for the unified hero composer (0729-0357-hero-unify):
+// Regression drive for the unified hero composer:
 // cold start with zero workspaces -> create a workspace -> type. Asserts the
 // composer textarea is the SAME DOM node across the disabled->live flip (a
 // remount drops the __heroMark marker property) — the session-maybe
diff --git a/scripts/translation-brief.ts b/scripts/translation-brief.ts
index 18e1e91e14..9380974fa0 100644
--- a/scripts/translation-brief.ts
+++ b/scripts/translation-brief.ts
@@ -5,10 +5,9 @@
  * changed Markdown units, heading sections, whole document), the terminology
  * rows those changes touch, first-occurrence movement notes, and a digest of
  * the binding update rules. The unit mapping, mechanical code splice, and
- * first-occurrence tracking adopt the planner mechanics validated in the
- * incremental-pipeline work (PR #684). The CLI wrapper is
- * `scripts/gen-translation-brief.ts`; the workflow that consumes the
- * briefing is `.agents/skills/dsh-translate-docs/SKILL.md`.
+ * first-occurrence tracking follow the incremental-pipeline planner mechanics.
+ * The CLI wrapper is `scripts/gen-translation-brief.ts`; the workflow that
+ * consumes the briefing is `.agents/skills/dsh-translate-docs/SKILL.md`.
  */
 
 import type { Nodes } from 'mdast'
diff --git a/scripts/verify-client-domain-graph.ts b/scripts/verify-client-domain-graph.ts
index c1d883d6ef..4349a23d4d 100644
--- a/scripts/verify-client-domain-graph.ts
+++ b/scripts/verify-client-domain-graph.ts
@@ -1,16 +1,16 @@
 /**
  * Enforce intra-package domain layering inside `packages/client/*\/src/client/`.
  * verify-module-graph covers package-level edges; this gate covers the
- * directory level the future package split will land on: domain directories
- * may import `contract/` and never each other, and only the assembly point
- * (`apply.ts` / `index.ts`) may import across domains.
+ * directory level: domain directories may import `contract/` and never each
+ * other, and only the assembly point (`apply.ts` / `index.ts`) may import
+ * across domains.
  *
  * Layer model (lower may not import higher):
  *   0  contract/            shared contract surface (types + slot declarations)
  *   1  <domain>/ + service  domain implementations (skeleton/, chat/, ...)
  *   2  apply.ts, index.ts   assembly point and re-export shell
  *
- * Not yet wired into the gate sequence (loose-gate window); run directly:
+ * Run directly:
  *   pnpm exec tsx scripts/verify-client-domain-graph.ts
  */
 
diff --git a/vitest.config.ts b/vitest.config.ts
index e07ae43ec3..e8bae9560f 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -23,8 +23,8 @@ const windowsUnsupportedPackages = process.platform === 'win32'
       // Bash-requiring suites (a real POSIX shell is unavailable on Windows).
       // The pwsh-requiring suites (pwsh-local, tool-pwsh) deliberately stay
       // INCLUDED: PowerShell ships with Windows, so they run natively here.
-      // Replacing the old 'packages/bash/*' glob with this explicit list also
-      // newly INCLUDES packages/bash/bash (the Service Definition package) on Windows.
+      // This explicit list (not a 'packages/bash/*' glob) keeps
+      // packages/bash/bash — the Service Definition package — running on Windows.
       'packages/bash/bash-local',
       'packages/bash/bash-sandbox',
       'packages/bash/tool-bash',
@@ -148,9 +148,9 @@ export default defineConfig({
         'packages/*/*/src/worker.ts',
         // A killed executable lint-contract test can leave a non-product source probe behind.
         'packages/*/*/src/oxlint-contract-*.ts',
-        // GUI step-1 skeleton (PR #500): client/web UI files whose remaining
-        // branches need a browser-grade harness the jsdom lane doesn't cover
-        // yet. TODO(gui): cover and remove as the client test lane matures.
+        // Client/web UI files whose remaining branches need a browser-grade
+        // harness the jsdom lane doesn't cover yet. TODO(gui): cover and
+        // remove as the client test lane matures.
         'packages/client/ui-trajectory/src/*',
         // Trajectory's compact Markdown projection retains deferred branch coverage.
         'packages/client/ui-primitives/src/markdown/plain-text.ts',

From ee7458b2dff13daca1c86aa6416aab0443c7aea0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 16:37:00 +0800
Subject: [PATCH 507/516] =?UTF-8?q?docs:=20fix=20review=20findings=20?=
 =?UTF-8?q?=E2=80=94=20residual=20ordinals,=20hypothetical=20IPC=20row,=20?=
 =?UTF-8?q?citation-rule=20amendments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Purge the residual task/phase ordinals review caught ((T2), (queue cut 1)
×3, T6, P-I, 'this cut' ×6 including battery-expansion finds in two
untouched notes and a workflow JSDoc); drop the 'externally logged as
Decision 21' parenthetical and rename the remaining bare decision-21
mentions; mark the gui-layering IPC bridge row as a hypothetical example;
restore the GATE_NOTICE doc-typecheck clause and the py-types 'measured'
provenance; say subprocess-backed in filesystem.md; add the picker note
path. Amend the citations note: merged-PR evidence anchors in Agent Notes
are sanctioned, and the candidate gate patterns gain the four shapes the
sweep missed. All nine touched pairs re-recorded.
---
 .../2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml      | 4 ++--
 .../2026-07-19-gui-layering-and-rpc-protocol.md             | 2 +-
 .../2026-07-19-gui-layering-and-rpc-protocol.zh.md          | 2 +-
 ...026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml | 4 ++--
 .../2026-07-25-web-input-machine-and-slash-pipeline.md      | 2 +-
 .../2026-07-25-web-input-machine-and-slash-pipeline.zh.md   | 2 +-
 .../feature/2026-06-21-subagent-capability-seam.i18n.yaml   | 4 ++--
 .../feature/2026-06-21-subagent-capability-seam.md          | 4 ++--
 .../feature/2026-06-21-subagent-capability-seam.zh.md       | 4 ++--
 .../feature/2026-06-22-acp-subagent-backend.i18n.yaml       | 4 ++--
 .../implemented/feature/2026-06-22-acp-subagent-backend.md  | 2 +-
 .../feature/2026-06-22-acp-subagent-backend.zh.md           | 2 +-
 .../feature/2026-07-05-dynamic-workflows.i18n.yaml          | 4 ++--
 .../implemented/feature/2026-07-05-dynamic-workflows.md     | 2 +-
 .../implemented/feature/2026-07-05-dynamic-workflows.zh.md  | 2 +-
 .../2026-08-08-user-explicit-skill-invocation.i18n.yaml     | 4 ++--
 .../feature/2026-08-08-user-explicit-skill-invocation.md    | 6 +++---
 .../feature/2026-08-08-user-explicit-skill-invocation.zh.md | 6 +++---
 .../2026-08-09-committed-artifact-citations.i18n.yaml       | 4 ++--
 .../process/2026-08-09-committed-artifact-citations.md      | 6 +++---
 .../process/2026-08-09-committed-artifact-citations.zh.md   | 6 +++---
 docs/cordis-api/inherited.md                                | 2 +-
 docs/subsystems/filesystem.i18n.yaml                        | 4 ++--
 docs/subsystems/filesystem.md                               | 2 +-
 docs/subsystems/filesystem.zh.md                            | 2 +-
 packages/client/runtime/tests/wire-events.spec.ts           | 2 +-
 .../src/client/skeleton/DetailsPanel.module.css             | 2 +-
 .../client/ui-conversation/src/client/skeleton/InputBar.tsx | 2 +-
 packages/client/ui-conversation/tests/input-matrix.spec.tsx | 2 +-
 .../client/ui-conversation/tests/input-scenarios.spec.tsx   | 2 +-
 packages/client/ui-slash/README.i18n.yaml                   | 4 ++--
 packages/client/ui-slash/README.md                          | 2 +-
 packages/client/ui-slash/README.zh.md                       | 2 +-
 packages/core/tools/src/py-types.ts                         | 4 ++--
 packages/hooks/hooks-claude/src/index.ts                    | 2 +-
 packages/host/directory-picker-native/src/native-picker.ts  | 2 +-
 packages/typert/generator/src/cordis-catalog.ts             | 2 +-
 packages/workflow/workflow/src/index.ts                     | 2 +-
 38 files changed, 58 insertions(+), 58 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index bf20616836..87c65807b8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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 .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: f3aea8360ea1db9b29da01f143daf30cd969b0e5
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 27b5401960a31ee3cedf2366d3b7f4efc527d482
+2026-07-19-gui-layering-and-rpc-protocol.md: 7997a682c8745f7b3d0a9721acfa9355603f9b2e
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: cb36b5cb725128e1c5067e5e69e52aa851668e52
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
index f3aea8360e..7997a682c8 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -218,7 +218,7 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 | `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing; carrier tests and callers can exercise the protocol without opening a port, while product `dsh run` drives core directly |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` uplink + one same-origin WebSocket downlink per logical stream | the browser shape; physical boundary in the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | unused (protocol-layer override) | serverless UI development (`?fixture`): overrides the `callUnary`/`openMux`/`openHost`/`respond` virtuals and is itself the fake server (frame rpcIds minted by it, semantics self-consistent) |
-| IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
+| IPC bridge subclass (hypothetical example — no such shell exists) | an Electron shell | IPC serialization round trip | would swap only doFetch; contract and base class unchanged |
 
 ## How to extend (operational checklists)
 
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 27b5401960..cb36b5cb72 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -216,7 +216,7 @@ export type ResponseValue<K> =
 | `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧；载体测试与调用方可以在不打开端口的情况下运行这套协议，而产品 `dsh run` 直接驱动 core |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
-| IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
+| IPC 桥子类（假想示例——尚无此形态） | Electron 壳 | IPC 序列化往返 | 只需换 doFetch，约定/基类零改 |
 
 ## 怎么扩展（操作清单）
 
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
index f670471d90..5b9acd3371 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.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 .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
-2026-07-25-web-input-machine-and-slash-pipeline.md: 345a08188fc6a4f2b951e8f9cd9d3a5b953a5e34
-2026-07-25-web-input-machine-and-slash-pipeline.zh.md: d454003036dd322ec3366c66293120cb2997de8d
+2026-07-25-web-input-machine-and-slash-pipeline.md: 1aca87530d4dcf1709f484cd471d8887c632f55b
+2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 958b519e7f291033410b932ccca623d87954738d
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
index 345a08188f..1aca87530d 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
@@ -78,7 +78,7 @@ A trigger/menu/pick pipeline with zero knowledge of "commands":
 
 ### Plain-text references: text outcomes and lexicon decoration
 
-skill/@subagent references skip the placeholder + occurrence identity chain — the plain-text-reference decision (externally logged as Decision 21): a pick inserts the literal `/name ` `@name ` text straight into the draft, with the chip visual purely derived:
+skill/@subagent references skip the placeholder + occurrence identity chain — the plain-text-reference decision: a pick inserts the literal `/name ` `@name ` text straight into the draft, with the chip visual purely derived:
 
 - PickOutcome gains a `{text}` arm; the new scoped bail event `slash/input-insert-text` `{text, span}` (the same contract as the other three: draftRev CAS, returning true ⟺ an actual rewrite); facade.insertText goes through setDraft concatenation — zero machine changes.
 - Sources get an optional `lexicon?(session)` hook: a synchronous hot-snapshot name roster, with `undefined` = data not warm — zero decoration, never triggering a fetch (the render path stays synchronous and side-effect-free); the paired optional `subscribeLexicon?(session, listener)` hook is the invalidation channel for rolls that change after warm (catalog settles, children spawn/exit). The controller aggregates the rolls into its `lexicon` snapshot store (re-polling on each source notification); sources registered after scope birth are warmed and folded in via the service's live-controller broadcast.
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
index d454003036..958b519e7f 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md
@@ -78,7 +78,7 @@ occurrence 表与 chip 三投影：
 
 ### 纯文本引用：text outcome 与 lexicon 装饰
 
-skill/@subagent 引用不走占位符 + occurrence 身份链——纯文本引用决策（外部记录为决策 21）：pick 直接把 `/name ` `@name ` 原文插进 draft，chip 视觉纯派生：
+skill/@subagent 引用不走占位符 + occurrence 身份链——纯文本引用决策：pick 直接把 `/name ` `@name ` 原文插进 draft，chip 视觉纯派生：
 
 - PickOutcome 增 `{text}` arm；新 scoped bail 事件 `slash/input-insert-text` `{text, span}`（与另三个同约定：draftRev CAS、返回 true ⟺ 实际改写）；facade.insertText 走 setDraft 拼接，机器零改动。
 - source 可选 `lexicon?(session)` 钩子：同步热快照名录，`undefined` = 数据未热——零装饰、永不触发 fetch（渲染路径保持同步无副作用）；配对的可选 `subscribeLexicon?(session, listener)` 钩子是名录在 warm 之后仍会变化（目录 settle、子代生灭）时的失效通道。controller 把各名录聚合进自己的 `lexicon` snapshot store（每次 source 通知重拉）；scope 出生后才注册的 source 由 service 广播给活 controller，补 warm 并并入名录。
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index cebb95513f..ac2a0bfb37 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.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 .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
-2026-06-21-subagent-capability-seam.md: 82010b4d11d2de5fc00f892b05e73807530e9cbf
-2026-06-21-subagent-capability-seam.zh.md: dc4e35e9ca6de8790b26bda1aeca30af00db5e1d
+2026-06-21-subagent-capability-seam.md: 72f17d7566aa982a5710e466cb4f740906ef167b
+2026-06-21-subagent-capability-seam.zh.md: 8205a6e2eab3bdaddf25b582c590034e2cf2f8dd
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
index 82010b4d11..72f17d7566 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -62,7 +62,7 @@ Each in-process subagent runs in its **own `Session`** (own id, `parentSession`
 
 ### Provider selection is config, not model-facing
 
-`dsh-tool-subagent` binds to exactly one provider name (`Config.provider`); the model sees only `{ description, prompt }`. To expose more than one transport, load the tool plugin more than once, each bound to a different provider and a distinct `toolName` (the tool registry rejects a duplicate name). The *service* holds the multi-provider registry; the *tool* picks one — no provider/type parameter in the schema this cut.
+`dsh-tool-subagent` binds to exactly one provider name (`Config.provider`); the model sees only `{ description, prompt }`. To expose more than one transport, load the tool plugin more than once, each bound to a different provider and a distinct `toolName` (the tool registry rejects a duplicate name). The *service* holds the multi-provider registry; the *tool* picks one — the schema carries no provider/type parameter.
 
 ## Testing
 
@@ -72,5 +72,5 @@ Registry and tool tests replace only the nondeterministic child boundary with a
 
 - **Recursion.** Without a bound, an in-process child can see the delegation tool and recurse. The in-process backends implement the optional absolute depth limit and scoped live-global `toolFilter`; ACP advertises both capabilities off and rejects such a request. The [subagent composition-controls Agent Note](2026-07-12-subagent-persona-tool-filter-and-depth.md) owns their exact semantics and security limits.
 - **Blocking the parent turn.** Foreground collection holds the parent's step open for the child's full duration. Background delegation uses the shared `ctx.tasks` runtime and generic `task_*` tools, the same collection mechanism as background bash; the subagent seam itself remains task-agnostic.
-- **Live progress.** This cut surfaces only lifecycle + final result; a per-chunk child→parent update stream is deferred with the background redesign.
+- **Live progress.** Only lifecycle + the final result surface; a per-chunk child→parent update stream is deferred with the background redesign.
 - **ACP client surface.** Proxying `fs`/`terminal` from the ACP child back to the parent (a shared-workspace mode) is future work; the first cut advertises neither, so the child self-serves in its own process.
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index dc4e35e9ca..8205a6e2ea 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -62,7 +62,7 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 ### 提供方选择是配置，不面向模型
 
-`dsh-tool-subagent` 绑定到恰好一个提供方名称（`Config.provider`）；模型只看到 `{ description, prompt }`。若要暴露多种传输方式，请多次加载该工具插件，每次绑定不同的提供方和不同的 `toolName`（工具注册表拒绝重名）。*服务*持有多提供方注册表；*工具*选择其中一个——本版 schema 中没有提供方/type 参数。
+`dsh-tool-subagent` 绑定到恰好一个提供方名称（`Config.provider`）；模型只看到 `{ description, prompt }`。若要暴露多种传输方式，请多次加载该工具插件，每次绑定不同的提供方和不同的 `toolName`（工具注册表拒绝重名）。*服务*持有多提供方注册表；*工具*选择其中一个——schema 中没有提供方/type 参数。
 
 ## 测试
 
@@ -72,5 +72,5 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 - **递归。** 如果不设限制，进程内子 agent 能看到委派工具并递归调用。进程内后端实现了可选的绝对深度限制和有作用域的实时全局 `toolFilter`；ACP 声明这两项能力为关闭状态，并拒绝此类请求。[subagent 组合控制 Agent Note](2026-07-12-subagent-persona-tool-filter-and-depth.md) 负责定义它们的确切语义和安全边界。
 - **阻塞父轮次。** 前台收集在子 agent 的整个持续时间内保持父 agent 的步骤打开。后台委派使用共享的 `ctx.tasks` 运行时与通用 `task_*` 工具，与后台 bash 共用同一套收集机制；subagent seam 本身仍不感知任务。
-- **实时进度。** 本版仅暴露生命周期事件与最终结果；逐分片的子→父更新流推迟到后台重新设计时一并处理。
+- **实时进度。** 仅暴露生命周期事件与最终结果；逐分片的子→父更新流推迟到后台重新设计时一并处理。
 - **ACP 客户端接口。** 将 ACP 子 agent 的 `fs`/`terminal` 代理回父 agent（共享工作区模式）是后续工作；首版不声明这两项能力，子 agent 在自己的进程中自行服务。
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
index 4cf94795a8..4b601e0f99 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.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 .agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
-2026-06-22-acp-subagent-backend.md: 211030a6ecc9b6f673174ba410415c7bd80818ef
-2026-06-22-acp-subagent-backend.zh.md: 2dde3d96329cc47d9c7cca08e1d25764c32f8ebe
+2026-06-22-acp-subagent-backend.md: 41a60bc8e73cbda1d382226acfbd9c0a4b146fa6
+2026-06-22-acp-subagent-backend.zh.md: 6aea991c2b4ab783b5f8c43ecb9529df07269d3f
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
index 211030a6ec..41a60bc8e7 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
@@ -18,7 +18,7 @@ Each `start` spawns a new child, runs exactly one ACP session (`initialize` →
 
 ### Minimal client stub
 
-The client advertises NO optional capabilities (no `fs`, no `terminal`): the child self-serves file/terminal access in its own process. `session/update` notifications are consumed — the backend accumulates `agent_message_chunk` text as the result output and ignores the rest (thoughts, tool-call cards) in this cut, which surfaces only the child's final answer. `session/request_permission` is auto-answered by a configured policy (`reject` declines every prompt, `allow` approves via the first allow-shaped option) — the first cut surfaces no prompt to a human. Proxying `fs`/`terminal` back to the parent (a shared-workspace mode) remains future work, as the seam Agent Note noted.
+The client advertises NO optional capabilities (no `fs`, no `terminal`): the child self-serves file/terminal access in its own process. `session/update` notifications are consumed — the backend accumulates `agent_message_chunk` text as the result output and ignores the rest (thoughts, tool-call cards), so only the child's final answer surfaces. `session/request_permission` is auto-answered by a configured policy (`reject` declines every prompt, `allow` approves via the first allow-shaped option) — no prompt is surfaced to a human. Proxying `fs`/`terminal` back to the parent (a shared-workspace mode) remains future work, as the seam Agent Note noted.
 
 ### No start-time capabilities
 
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
index 2dde3d9632..6aea991c2b 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
@@ -18,7 +18,7 @@ subagent seam（[seam Agent Note](2026-06-21-subagent-capability-seam.md)）的
 
 ### 最小化客户端桩
 
-客户端不声明任何可选能力（无 `fs`、无 `terminal`）：子 agent 在自己的进程中自行处理文件/终端访问。`session/update` 通知被消费：后端将 `agent_message_chunk` 文本累积为结果输出，在本阶段忽略其余内容（思考、工具调用卡片），仅暴露子 agent 的最终回答。`session/request_permission` 由配置的策略自动应答（`reject` 拒绝所有提示，`allow` 通过第一个表示允许的选项批准）——本阶段不向人类暴露任何权限提示。将 `fs`/`terminal` 代理回父进程（共享工作区模式）仍为后续工作，如 seam Agent Note 所述。
+客户端不声明任何可选能力（无 `fs`、无 `terminal`）：子 agent 在自己的进程中自行处理文件/终端访问。`session/update` 通知被消费：后端将 `agent_message_chunk` 文本累积为结果输出，忽略其余内容（思考、工具调用卡片），因此仅暴露子 agent 的最终回答。`session/request_permission` 由配置的策略自动应答（`reject` 拒绝所有提示，`allow` 通过第一个表示允许的选项批准）——不向人类暴露任何权限提示。将 `fs`/`terminal` 代理回父进程（共享工作区模式）仍为后续工作，如 seam Agent Note 所述。
 
 ### 无启动时能力
 
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
index 5c845ed10b..d5ff80bd97 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.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 .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
-2026-07-05-dynamic-workflows.md: 4dc8744f7505aeb84a14dbf5ad0cc8cb5783d234
-2026-07-05-dynamic-workflows.zh.md: 5d3f5b014ff4532050bb0afd5464f7ec5e91a323
+2026-07-05-dynamic-workflows.md: 3e491478286eb77b56872fcbbdd5ebb6b62a5545
+2026-07-05-dynamic-workflows.zh.md: 7888d83f981a96ac5eb31d5ca6f1f8d0b4930ec7
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
index 4dc8744f75..3e49147828 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md
@@ -52,7 +52,7 @@ An output schema makes a schema-valid committed capture mandatory for successful
 
 Worker-side logic runs through an in-process `MessageChannel` so V8 coverage measures it. Unit tests cover script helpers, fatal and nullable failures, JSON boundaries, caps, cancellation, child ownership, and structured output through real loops. A built-bin smoke runs the separately bundled `lib/worker.cjs` under plain Node, a with-key e2e drives real child agents, and model-facing workflow behavior is snapshot-covered through its owning example.
 
-## Deferred (documented non-goals of this cut)
+## Deferred (documented non-goals)
 
 - **Background collection** (start tool → run id → completion notice → collect), designed alongside bash/subagent background unification.
 - **Journaling + resume** (`resumeFromRunId`, cached agent() prefixes) — implementing it reintroduces CC's determinism bans as a script-contract tightening (scripts may read the clock today).
diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
index 5d3f5b014f..7888d83f98 100644
--- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
@@ -52,7 +52,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
 
 worker 侧逻辑通过进程内 `MessageChannel` 运行，使 V8 覆盖率能够度量它。单元测试覆盖脚本辅助函数、fatal 与 nullable 失败、JSON 边界、上限、取消、子 agent 所有权和通过真实循环的结构化输出。构建后二进制文件的冒烟测试在纯 Node 下运行单独打包的 `lib/worker.cjs`，带密钥的 e2e 驱动真实子 agent，面向模型的工作流行为通过其所属示例进行快照覆盖。
 
-## 延迟（本轮明确的非目标）
+## 延迟（明确的非目标）
 
 - **后台收集**（启动工具 → run id → 完成通知 → 收集），与 bash/subagent 后台统一一起设计。
 - **日志化 + 恢复**（`resumeFromRunId`、缓存的 agent() 前缀）：实现它会以脚本约定收紧的形式重新引入 CC 的确定性禁令（脚本目前可以读取时钟）。
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
index 963e4b1cae..005b3cad67 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.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 .agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
-2026-08-08-user-explicit-skill-invocation.md: 55001ec2b352bba6f37dd937f64ec8b10853bffb
-2026-08-08-user-explicit-skill-invocation.zh.md: 5e9eb90502a178c4171899247ebac9bec965c89f
+2026-08-08-user-explicit-skill-invocation.md: 74d9f01f191005db6d3d283a3c56f5ee664447f8
+2026-08-08-user-explicit-skill-invocation.zh.md: 0f7c9e1261dda796d988c17ddf7199b74be4133e
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
index 55001ec2b3..74d9f01f19 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.md
@@ -6,7 +6,7 @@ English | [中文](2026-08-08-user-explicit-skill-invocation.zh.md)
 
 ## Problem
 
-A `disable-model-invocation: true` skill is user-only by design: it never enters the model-facing catalog and the `skill` tool refuses to load it. Its only legitimate entry point is an explicit user gesture — yet the web client had none. `skill.list` filtered to the model-and-user intersection (hiding user-only skills from the menu), an entered `/name` line rode into the default prompt sink as plain text, and the model it reached was forbidden to load the skill — so it degraded to `read`-ing the SKILL.md file or ignoring the gesture (issue #1470). Even for ordinary skills, the decision-21 plain-text reference made user invocation a collaboration cue the model could ignore, not a guarantee.
+A `disable-model-invocation: true` skill is user-only by design: it never enters the model-facing catalog and the `skill` tool refuses to load it. Its only legitimate entry point is an explicit user gesture — yet the web client had none. `skill.list` filtered to the model-and-user intersection (hiding user-only skills from the menu), an entered `/name` line rode into the default prompt sink as plain text, and the model it reached was forbidden to load the skill — so it degraded to `read`-ing the SKILL.md file or ignoring the gesture (issue #1470). Even for ordinary skills, the plain-text reference made user invocation a collaboration cue the model could ignore, not a guarantee.
 
 ## Decision
 
@@ -14,7 +14,7 @@ User-explicit invocation is a host-side pre-step injection, uniform for every us
 
 - `dsh-tool-skill` registers a second `agent/pre-step` listener (beside its catalog listener, the same seam `workspace-instructions` and the runtime-context snapshot ride): it scans the step's claimed messages for whitespace-bounded `/name` tokens — anywhere in the text, the same word-boundary shape the transcript chip decoration uses — collects first-seen-deduplicated names, loads each through `ctx.skills.get`, checks `isUserInvocable` on the loaded definition (the single lookup that produces what is injected), renders it with the shared `renderSkillContent`, and appends the injections after every other injection of the step: background first (workspace rules, runtime policy, catalog), the material the model must act on last, closest to its answer. Registration order pins the placement — the gesture listener registers before the catalog listener, so the waterfall hands it the catalog-bearing list to extend.
 - Precision is closed-set matching, exactly like slash commands: `/goal` resolves against the command registry, `/name` against the workspace's user-invocable skill directory; a miss stays ordinary prose, so nothing is ever guessed. Only `source.kind === 'user'` messages are scanned — external text cannot forge a gesture. Paths (`/usr/bin`), fractions (`5/8`), and prefixed tokens (`foo/name`) all break the boundary.
-- The client stays decision 21: a menu pick lands the literal `/name ` and the prompt ships it verbatim; ui-skill implements no adjudication hooks and no reference codec. `skill.list` (now the domain's only RPC) serves every user-invocable skill with `modelInvocable` so menus mark user-only entries. A name shared with a host command resolves to the command — adjudication claims the line client-side before it becomes a prompt.
+- The client keeps the [plain-text-reference decision](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md): a menu pick lands the literal `/name ` and the prompt ships it verbatim; ui-skill implements no adjudication hooks and no reference codec. `skill.list` (now the domain's only RPC) serves every user-invocable skill with `modelInvocable` so menus mark user-only entries. A name shared with a host command resolves to the command — adjudication claims the line client-side before it becomes a prompt.
 - The injection is a `user`-role message carrying the `skill-invocation` source (`{ name, form: 'instructions' }`), so `user/message` logging, the context-injection transcript row (labelled with the skill name), and replay all come free; `renderSkillContent` lives in the `dsh-skill` seam, shared verbatim with the `skill` tool result, and the catalog's closing sentence tells the model to follow an injected block instead of re-loading it.
 
 Peer-product survey (Pi, OpenCode, Claude Code, Kimi Code, Codex, DeepSeek-Reasonix — local checkouts) was unanimous that user-explicit triggering is programmatic injection with zero model participation; the final shape is closest to Codex's core-side `$name` mention scanning, which likewise frees every front end from implementing recognition.
@@ -30,7 +30,7 @@ Peer-product survey (Pi, OpenCode, Claude Code, Kimi Code, Codex, DeepSeek-Reaso
 
 ## Consequences
 
-- Decision 21's plain-text reference is now the whole client story: the draft carries plain text, chip visuals derive from the lexicon, and the sent text is judged by the host boundary — a hand-typed gesture, a menu pick, and a TUI prompt are indistinguishable and equally deterministic.
+- The plain-text reference is now the whole client story: the draft carries plain text, chip visuals derive from the lexicon, and the sent text is judged by the host boundary — a hand-typed gesture, a menu pick, and a TUI prompt are indistinguishable and equally deterministic.
 - Every user-invocable skill invocation costs its full rendered body unconditionally — the price of determinism the peer survey showed everyone pays. Mentioning a known skill name mid-sentence loads it; that is the Codex mention semantic, accepted deliberately.
 - The `skill-invocation` source rides `user/message`, so Model-visible ⟺ logged holds with no new event type, and replay/UI read metadata rather than text markers.
 - Accepted residual of dropping the per-injection preamble: the no-reload framing rides only the catalog, and a workspace whose skills are all user-only never publishes a first catalog — an injection can arrive with no framing at all, and the model may redundantly try the `skill` tool once (the replacement catalog's empty arm carries the sentence; the never-published case does not). Publishing a catalog for framing alone was judged worse than that one recoverable error.
diff --git a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
index 5e9eb90502..0f7c9e1261 100644
--- a/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-user-explicit-skill-invocation.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-`disable-model-invocation: true` 的 skill（技能）在设计上就是仅限用户的：它绝不进入面向模型的目录，`skill` 工具也拒绝加载它。它唯一正当的入口是一次显式的用户手势——而 web 客户端此前没有这个入口。`skill.list` 过滤到模型与用户的交集（把仅限用户的 skill 挡在菜单之外），回车提交的 `/name` 一行以纯文本落入默认提示词 sink，而这行文本到达的模型又被禁止加载该 skill——于是退化为模型去 `read` 那份 SKILL.md 文件，或者干脆无视这次手势（issue #1470）。即使对普通 skill，决策 21 的纯文本引用也让用户调用只是模型可以忽略的协作线索，而不是保证。
+`disable-model-invocation: true` 的 skill（技能）在设计上就是仅限用户的：它绝不进入面向模型的目录，`skill` 工具也拒绝加载它。它唯一正当的入口是一次显式的用户手势——而 web 客户端此前没有这个入口。`skill.list` 过滤到模型与用户的交集（把仅限用户的 skill 挡在菜单之外），回车提交的 `/name` 一行以纯文本落入默认提示词 sink，而这行文本到达的模型又被禁止加载该 skill——于是退化为模型去 `read` 那份 SKILL.md 文件，或者干脆无视这次手势（issue #1470）。即使对普通 skill，纯文本引用也让用户调用只是模型可以忽略的协作线索，而不是保证。
 
 ## 决策
 
@@ -14,7 +14,7 @@ Status: implemented
 
 - `dsh-tool-skill` 注册第二个 `agent/pre-step` 监听器（与其目录监听器并列，也是 `workspace-instructions` 与运行时上下文快照搭乘的同一 seam）：它在该步骤已认领的消息中扫描以空白为界的 `/name` token——文本中任意位置均可，与 transcript（文本记录）chip 装饰所用的词边界形状相同——收集按首见去重的名称，逐个经 `ctx.skills.get` 加载，在已加载定义上检查 `isUserInvocable`（产生注入内容的正是这同一次查找），用共享的 `renderSkillContent` 渲染，并把注入追加在该步骤所有其他注入之后：背景在前（工作区规则、运行时策略、目录），模型必须着手处理的材料在最后、最贴近它的回答。注册顺序钉住了这一位置——手势监听器先于目录监听器注册，因此 waterfall（瀑布式事件）会把携带目录的列表交给它来扩展。
 - 精确性来自封闭集合匹配，与斜杠命令完全一致：`/goal` 对照命令注册表解析，`/name` 对照工作区的用户可调用 skill 目录解析；未命中即保持为普通行文，因此绝不猜测。只扫描 `source.kind === 'user'` 的消息——外部文本无法伪造手势。路径（`/usr/bin`）、分数（`5/8`）与带前缀的 token（`foo/name`）都会破坏该边界。
-- 客户端停留在决策 21：菜单 pick 落下字面文本 `/name `，该文本随提示词原样提交；ui-skill 不实现任何裁决钩子，也没有引用 codec。`skill.list`（现在是该领域唯一的 RPC）提供每一个用户可调用的 skill 并携带 `modelInvocable`，供菜单标出仅限用户的条目。与宿主命令同名的名称解析为命令——客户端会在该行成为提示词之前完成裁决并将其认领。
+- 客户端沿用[纯文本引用决策](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)：菜单 pick 落下字面文本 `/name `，该文本随提示词原样提交；ui-skill 不实现任何裁决钩子，也没有引用 codec。`skill.list`（现在是该领域唯一的 RPC）提供每一个用户可调用的 skill 并携带 `modelInvocable`，供菜单标出仅限用户的条目。与宿主命令同名的名称解析为命令——客户端会在该行成为提示词之前完成裁决并将其认领。
 - 注入是一条携带 `skill-invocation` 来源（`{ name, form: 'instructions' }`）的 `user` 角色消息，因此 `user/message` 落账、上下文注入的 transcript 行（以 skill 名称标注）与回放全部免费获得；`renderSkillContent` 位于 `dsh-skill` seam，由注入和 `skill` 工具结果共用，二者内容逐字相同，目录的结尾一句会告诉模型遵循注入块而不是重新加载。
 
 同类产品调研（Pi、OpenCode、Claude Code、Kimi Code、Codex、DeepSeek-Reasonix——本地检出）一致表明：用户显式触发都是模型零参与的程序化注入；最终形态最接近 Codex 核心侧的 `$name` mention 扫描——它同样让每一种前端免于自行实现识别。
@@ -30,7 +30,7 @@ Status: implemented
 
 ## 后果
 
-- 决策 21 的纯文本引用如今就是客户端的全部故事：草稿承载纯文本，chip 视觉由 lexicon 派生，发出的文本由宿主边界评判——手动键入的手势、菜单 pick 与 TUI 提示词无从区分，也同样具有确定性。
+- 纯文本引用如今就是客户端的全部故事：草稿承载纯文本，chip 视觉由 lexicon 派生，发出的文本由宿主边界评判——手动键入的手势、菜单 pick 与 TUI 提示词无从区分，也同样具有确定性。
 - 每一次用户可调用 skill 的调用都无条件付出其完整渲染正文的成本——这是确定性的代价，同类调研表明所有产品都在支付。在句子中间提到一个已知 skill 名称也会加载它；这就是 Codex 的 mention 语义，属于有意接受。
 - `skill-invocation` 来源搭乘 `user/message`，因此「模型可见 ⟺ 已记录」在不新增事件类型的情况下继续成立，回放与 UI 读取的是元数据而非文本标记。
 - 放弃逐次注入前导语后被接受的残余：no-reload framing 只搭乘目录，而 skill 全部为仅用户的工作区永远不会发布首个目录——注入可能在完全没有 framing 的情况下到达，模型可能多余地调用一次 `skill` 工具（替换目录的空分支携带该句；从未发布的情形没有）。仅为 framing 而发布目录被判定比这一次可恢复的错误更糟。
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
index 079b448027..022eb6655e 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: a34a779977a05b66b1587049ef4a38f0c1cfa0cb
-2026-08-09-committed-artifact-citations.zh.md: 6eb1810dddfcb38095270d4cdcb00eccef167183
+2026-08-09-committed-artifact-citations.md: 7d99a27238f25e7084fbbc816787c3c76a62bd89
+2026-08-09-committed-artifact-citations.zh.md: f09ae024c480d95dc95e39c62fbd1dc31f5b92a1
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
index a34a779977..7d99a27238 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -12,8 +12,8 @@ Large design and review sessions leave working shorthand — decision ordinals,
 
 Durable prose — comments, JSDoc, docs, notes, test comments and titles — cites only committed artifacts, resolvable in-repo without grep archaeology:
 
-- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned per the documentation standard; issues are durable and citable.
-- A design-session ordinal with a committed owner is replaced by the owner's name — decision 21 lives in the [web input-machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) as the plain-text-reference decision. An ordinal without an owner is deleted and its factual clause restated to stand alone.
+- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned in docs and code per the documentation standard; issues are durable and citable, and Agent Notes may cite merged PRs as evidence anchors — the standard routes change stories to commits, PRs, Agent Notes, and postmortems, and a note is that home.
+- A design-session ordinal whose decision has a committed owner is replaced by the decision's name — the ordinal once logged as "decision 21" is now "the plain-text-reference decision", owned by the [web input-machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md); the ordinal itself resolves nowhere in-repo and was dropped everywhere. An ordinal without an owner is deleted and its factual clause restated to stand alone.
 - Fixed regressions are pinned as present-tense counterfactuals ("without X, Y happens"; "a naive X would…"), never as repo history ("used to Y").
 - Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
 - Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice.
@@ -23,7 +23,7 @@ One repo-wide purge applied these rules across the prose surfaces, including the
 ## Alternatives considered
 
 - **Commit the design ledgers and audit documents so the ordinals resolve.** Rejected: session transcripts are working artifacts, not maintained references; committing them would create a parallel, ungated decision corpus beside Agent Notes, and their internal numbering would still drift.
-- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d` and `\(audit [A-Z]\d`) is the candidate if the pattern recurs.
+- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d`, `\(audit [A-Z]\d`, `\bcut \d`, `this cut`, a bare `\bT\d\b`, and `P-I`) is the candidate if the pattern recurs; review of the purge itself caught residuals in exactly those last four shapes, so they lead the candidate list.
 - **Delete the rationale that cited dead artifacts.** Rejected: the factual clauses were preserved or restated; only citations, review choreography, and derivation transcripts were removed, per the prose standard's complete-proposition rule.
 
 ## Verification
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
index 6eb1810ddd..f09ae024c4 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -12,8 +12,8 @@ Status: implemented
 
 持久行文（注释、JSDoc、文档、Agent Note、测试注释与测试标题）只引用已提交的产物，无需 grep 考古即可在仓库内解析：
 
-- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准仍在禁止之列；issue 是持久且可引用的。
-- 有已提交归属文档的设计会话序号替换为该归属文档的名称：决策 21 即 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) 中的纯文本引用决策。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
+- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列；issue 是持久且可引用的，Agent Note 还可引用已合并的 PR 作为证据锚点——文档标准将变更故事归置于 commit、PR、Agent Note 与事后分析，note 正是这一归宿。
+- 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」，归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)；该序号本身在仓库内无从解析，已全部移除。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
 - 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
 - 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
 - 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。
@@ -23,7 +23,7 @@ Status: implemented
 ## 曾考虑的替代方案
 
 - **把设计台账与审计文档提交入库，让序号得以解析。**不予采纳：会话 transcript 是工作产物，不是持续维护的参考资料；提交它们会在 Agent Note 之外形成一套平行且不受门禁约束的决策语料，其内部编号也仍会漂移。
-- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d` 与 `\(audit [A-Z]\d`）。
+- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d`、`\(audit [A-Z]\d`、`\bcut \d`、`this cut`、裸 `\bT\d\b` 与 `P-I`）；对本次清扫自身的评审恰好在后四种形态中发现残留，因此它们位居候选清单之首。
 - **删除引用了失效产物的设计理由。**不予采纳：事实性语句都得到保留或改写；依行文标准的完整命题规则，删掉的只有引用、评审编排与推导过程记录。
 
 ## 验证
diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md
index 6af9aec465..8bf23274e5 100644
--- a/docs/cordis-api/inherited.md
+++ b/docs/cordis-api/inherited.md
@@ -5,7 +5,7 @@
 
 The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).
 
-This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method; type names in a signature link to the page that documents them.
+This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.
 
 ## Inherited `ctx` members (cordis core + loader/hmr/timer)
 
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 91c13a23c5..fac61bde63 100644
--- a/docs/subsystems/filesystem.i18n.yaml
+++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md
-filesystem.md: 23ade1ede1592f7c8e1e409f3f9ca30f4f3f7e6f
-filesystem.zh.md: da2ac2583c381a89e0bd656018d799b22da0f1de
+filesystem.md: e0edad514b0c4d9108b18cc0b472600b29024c51
+filesystem.zh.md: 81c2d87b6a96740c7a99449a27c16331f5a0645a
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index 23ade1ede1..e0edad514b 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -269,7 +269,7 @@ type FsErrorCode =
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a `timeoutMs` here would be a deadline the seam cannot enforce, and an implicit default in the exact place explicit-over-implicit forbids. Cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider contract arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)) and the subprocess-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most — a timeout could not force an in-progress `fsync`/`rename` to stop, so a `timeoutMs` here would be a deadline the seam cannot enforce, and an implicit default in the exact place explicit-over-implicit forbids. Cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
 
 ## The service and the plugin
 
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index da2ac2583c..81c2d87b6a 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -269,7 +269,7 @@ type FsErrorCode =
 
 ## 文件 IO 不设超时
 
-`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方约定也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 bash 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的 `timeoutMs` 会成为 seam 无法强制执行的截止时间，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
+`read`/`write`/`edit` **不**接受 `timeoutMs`，提供方约定也不设置截止时间——不同于 bash 与 web（它们消费 [`@deepseek-ai/dsh-timeout`](../../packages/util/timeout/README.md)）以及 subprocess 支撑的 `glob`/`grep`（其声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：那些是进程支撑的，截止时间可以真正终止工作。本地系统调用至多是尽力中止——超时无法迫使进行中的 `fsync`/`rename` 停下，因此这里的 `timeoutMs` 会成为 seam 无法强制执行的截止时间，而且恰好落在"显式优于隐式"禁止隐式默认值的位置。取消仍通过工具执行 signal 传播，在系统调用边界尽力中止。
 
 ## 服务与插件
 
diff --git a/packages/client/runtime/tests/wire-events.spec.ts b/packages/client/runtime/tests/wire-events.spec.ts
index dfafcd07aa..5b71588732 100644
--- a/packages/client/runtime/tests/wire-events.spec.ts
+++ b/packages/client/runtime/tests/wire-events.spec.ts
@@ -1,5 +1,5 @@
 /**
- * Wire-to-typed-event bridge (web input-triggers cut 1): host/commands-changed
+ * Wire-to-typed-event bridge: host/commands-changed
  * → ctx 'commands/changed'; each established connection generation →
  * ctx 'connection/reset' (the forced cache-invalidation broadcast).
  */
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
index abdece3e25..cc5d732e45 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
@@ -1,4 +1,4 @@
-/* Details third column, minimal P-I fill: header (name + close) over a
+/* Details third column, minimal fill: header (name + close) over a
    scrolling body of Input/Output code sections. Panel width/squeeze belongs
    to layout; this fills whatever the column gives. */
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 0c097b6114..304e5f93e7 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -87,7 +87,7 @@ export function InputBar({
   // but its independent Stop below stays available while it runs.
   const continuable = subagent?.address.mode === 'continuable'
   const parentOffline = continuable && !subagent.parentAvailable
-  // Queue cut 1: running input stays free; locked = session removed, the
+  // Running input stays free; locked = session removed, the
   // inert no-workspace state, the machine faces absent (no session), or a
   // parent-offline continuable child. An owner block also disables input;
   // adjudicating and submitting render read-only so the draft stays visible.
diff --git a/packages/client/ui-conversation/tests/input-matrix.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
index 1efd959493..dc7bca56d4 100644
--- a/packages/client/ui-conversation/tests/input-matrix.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.spec.tsx
@@ -184,7 +184,7 @@ describe('matrix row: locked (session disabled)', () => {
     expect(shell.snapshot.phase).toBe('plain')
   })
 
-  it('running does NOT lock (queue cut 1): typing and enter-queue stay live', () => {
+  it('running does NOT lock: typing and enter-queue stay live', () => {
     const { textarea, sink } = bench({ running: true })
     expect((textarea).disabled).toBe(false)
     fireEvent.change(textarea, { target: { value: '排队' } })
diff --git a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
index 9f6b679b60..d5a34327f9 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.spec.tsx
@@ -34,7 +34,7 @@ interface FakeCommand {
   input?: { hint: string }
 }
 
-/** T6 decision-table source over an in-memory directory (menu/space/enter columns for leadingInput + execute). */
+/** Decision-table source over an in-memory directory (menu/space/enter columns for leadingInput + execute). */
 function commandSource(commands: FakeCommand[], execute: (line: string) => Promise<SubmitOutcome>) {
   const resolve = (name: string): FakeCommand | undefined => commands.find(c => c.name === name)
   const leadingClaim = (desc: FakeCommand): CommandClaim => ({
diff --git a/packages/client/ui-slash/README.i18n.yaml b/packages/client/ui-slash/README.i18n.yaml
index 47b4cc670f..daadfbd549 100644
--- a/packages/client/ui-slash/README.i18n.yaml
+++ b/packages/client/ui-slash/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/client/ui-slash/README.md
-README.md: 739e7ae93e024bdbd602aaff4267cb74406b5698
-README.zh.md: 0e3cd0d4b3cb93e3d602aa0c8f30d4e5afff3af2
+README.md: 3f97351bea04dbc268e6acc105be10e1e4e0a4b5
+README.zh.md: cf9e42d419cb472509a74ba227990b1502b38a75
diff --git a/packages/client/ui-slash/README.md b/packages/client/ui-slash/README.md
index 739e7ae93e..3f97351bea 100644
--- a/packages/client/ui-slash/README.md
+++ b/packages/client/ui-slash/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Input trigger pipeline plugin: `/` and `@` detection under the caret (word-boundary + guard-tier rules), the grouped candidate menu, and pick routing to registered sources. `ctx.slash` owns the source roster and resolves one `SlashController` per session scope (`sessionOf`); the conversation wiring layer drives `track`/`arbitrate`/`onSpace`/`adjudicate` on the controller. The same controller exposes `toggleSource` for a chrome launcher to open exactly one registered source over a synthetic selection span; the resulting candidates still use the ordinary menu, keyboard arbitration, pick callback, and scoped input mutations. Sources receive a `ClientSessionContext` projection per call — sessions are always agent-backed, so the projection is the session identity alone. A source is warmed in every session controller it can reach: the roster present at scope birth warms during controller construction, and a source registered later is warmed into every live controller by the registration itself. Sources whose `lexicon` roll changes after warm implement `subscribeLexicon(session, listener)`; the controller re-polls on each notification and publishes the aggregation through its `lexicon` snapshot store. The pipeline is command-agnostic: space/enter adjudication polls the optional `matchSpace`/`matchEnter` hooks in registration order and the first non-undefined answer wins.
 
-Layering: `src/core/` (T2) is the pure core — `detectTrigger`, `menuReduce`/`seedGroups`/`MENU_CLOSED`, `exactMatch`, zero React/DOM/cordis; `src/client/service.ts` is the shell wiring the core to the menu snapshot store, the per-hit candidate fetch (generation-gated, `AbortSignal`-superseded, failed sources drop silently with a console record), and the three pick paths. `src/types.ts` and the two `contract.ts` files are the frozen cross-package contract; changes require main-thread arbitration.
+Layering: `src/core/` is the pure core — `detectTrigger`, `menuReduce`/`seedGroups`/`MENU_CLOSED`, `exactMatch`, zero React/DOM/cordis; `src/client/service.ts` is the shell wiring the core to the menu snapshot store, the per-hit candidate fetch (generation-gated, `AbortSignal`-superseded, failed sources drop silently with a console record), and the three pick paths. `src/types.ts` and the two `contract.ts` files are the frozen cross-package contract; changes require main-thread arbitration.
 
 MenuView renders the menu store into the `conversation.input.overlay` slot (list kind, session scope) and renders null while closed. Typed triggers seed every source registered for that trigger; a programmatic launcher seeds only its requested source and publishes the source name through the controller's `launcher` snapshot store until the menu closes or typed tracking resumes. Groups sort by the optional `SlashSource.order` (lower first, default 0, ties keep registration order) under title rows localized through the `slash.menu` locale namespace (an unknown source shows its raw name); the list height clamps to the space above the composer, and a pointer down outside both the menu and the surrounding composer card dismisses it. The slot is owned by ui-conversation's composer entry (anchor, children declaration, lifecycle); its SlotMap type merge lives in this package's `src/client/slots.ts` because the dependency direction (ui-conversation → ui-slash) admits no reverse type import. Combobox pattern: focus stays in the textarea, rows pick on mousedown, the highlight rides `aria-activedescendant`.
 
diff --git a/packages/client/ui-slash/README.zh.md b/packages/client/ui-slash/README.zh.md
index 0e3cd0d4b3..cf9e42d419 100644
--- a/packages/client/ui-slash/README.zh.md
+++ b/packages/client/ui-slash/README.zh.md
@@ -4,7 +4,7 @@
 
 输入触发流水线插件：光标处的 `/` 与 `@` 检测（词边界 + guard tier 规则）、分组候选菜单，以及把 pick 路由到已注册 source。`ctx.slash` 拥有 source roster，并按会话 scope（`sessionOf`）各解析一个 `SlashController`；对话接线层在 controller 上驱动 `track`／`arbitrate`／`onSpace`／`adjudicate`。同一个 controller 还暴露 `toggleSource`，供 chrome launcher 在一段合成 selection span 上只打开一个已注册 source；所得候选仍走通常的菜单、键盘仲裁、pick callback 与 scoped 输入改写。source 每次调用收到一个 `ClientSessionContext` 投影——会话始终由 agent（智能体）支撑，因此投影只含会话身份。source 在它能触达的每个会话 controller 中都会被预热：scope 出生时在场的 roster 随 controller 构造预热，晚于此注册的 source 由注册动作本身预热进每个活 controller。`lexicon` 名录在预热后仍会变化的 source 实现 `subscribeLexicon(session, listener)`；controller 每收到通知就重拉，并把聚合结果经其 `lexicon` 快照 store 发布。流水线与命令无关：空格／回车裁决按注册序轮询可选的 `matchSpace`／`matchEnter` 钩子，第一个非 undefined 的应答胜出。
 
-分层：`src/core/`（T2）是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包约定；变更需经主线程仲裁。
+分层：`src/core/` 是纯内核——`detectTrigger`、`menuReduce`／`seedGroups`／`MENU_CLOSED`、`exactMatch`，零 React／DOM／cordis；`src/client/service.ts` 是壳层，把内核接到菜单快照 store、逐 hit 候选拉取（以 generation 把关、后继请求经 `AbortSignal` 取代旧请求、失败的 source 静默丢弃并留一条 console 记录）和三条 pick 路径上。`src/types.ts` 与两个 `contract.ts` 文件是冻结的跨包约定；变更需经主线程仲裁。
 
 MenuView 把菜单 store 渲染进 `conversation.input.overlay` slot（列表类，会话 scope），菜单关闭期间渲染 null。键入式 trigger 会 seed 为该 trigger 注册的所有 source；程序化 launcher 只 seed 所请求的 source，并在菜单关闭或重新开始键入式 tracking 前，通过 controller 的 `launcher` 快照 store 发布该 source 名称。分组按可选的 `SlashSource.order` 排序（越小越靠前，默认 0，同值保持注册序），组标题行经 `slash.menu` locale 命名空间本地化（未知 source 显示其原名）；列表高度收敛到 composer 上方的可用空间，指针落在菜单与所在 composer 卡片之外即关闭菜单。该 slot 由 ui-conversation 的组合器条目拥有（锚点、children 声明、生命周期）；其 SlotMap 类型合并放在本包的 `src/client/slots.ts`，因为依赖方向（ui-conversation → ui-slash）不允许反向的类型导入。combobox 模式：焦点始终留在 textarea，行在 mousedown 时完成 pick，高亮由 `aria-activedescendant` 承载。
 
diff --git a/packages/core/tools/src/py-types.ts b/packages/core/tools/src/py-types.ts
index ec9b0f2190..e4b241b75f 100644
--- a/packages/core/tools/src/py-types.ts
+++ b/packages/core/tools/src/py-types.ts
@@ -41,8 +41,8 @@ const IDENTIFIER = /^[\p{XID_Start}_]\p{XID_Continue}*$/u
  * that normalize together would collapse into one declaration. Those names
  * take the subscript path, which carries their exact bytes.
  *
- * `IDENTIFIER` is equivalent to `str.isidentifier()` on Node 22.23.1 vs
- * CPython 3.9.6 tables: the equivalence holds inside the two versions' shared
+ * `IDENTIFIER` matches `str.isidentifier()` (measured on Node 22.23.1 vs
+ * CPython 3.9.6 tables): the equivalence holds inside the two versions' shared
  * tables, and the skew characters below are exactly where that pair diverges.
  * The predicate as a whole is deliberately stricter than `isidentifier()`,
  * which does not test NFKC stability: `'field'.isidentifier()` is True and
diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts
index b60ce7b520..30f7a65c51 100644
--- a/packages/hooks/hooks-claude/src/index.ts
+++ b/packages/hooks/hooks-claude/src/index.ts
@@ -349,7 +349,7 @@ function stopPayload(ctx: Context, agent: Agent): Record<string, unknown> {
  * Build a SubagentStart/SubagentStop payload from the CC base (the child's
  * `session_id`/`cwd` when the child agent is available) plus the subagent-hook
  * fields. `agent_type` is the CC-default {@link SUBAGENT_TYPE}; `stop_hook_active`
- * is present on SubagentStop only (the loop-guard flag, always false this cut).
+ * is present on SubagentStop only (the loop-guard flag, always false).
  */
 function subagentPayload(ctx: Context, event: 'SubagentStart' | 'SubagentStop', info: { id: string }, child: Agent | undefined): Record<string, unknown> {
   return {
diff --git a/packages/host/directory-picker-native/src/native-picker.ts b/packages/host/directory-picker-native/src/native-picker.ts
index 45a62a72e5..a34d75ebf0 100644
--- a/packages/host/directory-picker-native/src/native-picker.ts
+++ b/packages/host/directory-picker-native/src/native-picker.ts
@@ -71,7 +71,7 @@ export async function pickNativeDirectory(
     // per-monitor-v2 DPI and abort support. koffi is a packaged dependency
     // whose availability the install guarantees, so there is no fallback
     // tier: any failure surfaces as-is (no PowerShell fallback tier; see
-    // the simplification Agent Note).
+    // .agents/notes/implemented/simplification/2026-08-04-drop-windows-powershell-picker-fallback.md).
     const pickDialog = internals.pickWin32Dialog ?? pickWin32Directory
     return await pickDialog(signal)
   }
diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts
index de074f3c80..1950c255cb 100644
--- a/packages/typert/generator/src/cordis-catalog.ts
+++ b/packages/typert/generator/src/cordis-catalog.ts
@@ -772,7 +772,7 @@ const BANNER = [
 ]
 
 /** The shared GENERATED + freshness-gate + fence notice paragraph. */
-const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method; type names in a signature link to the page that documents them.'
+const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
 
 /**
  * Render one page's generated `cordis-surface` region: the services mapped to
diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts
index 794e5023ef..526da15ad8 100644
--- a/packages/workflow/workflow/src/index.ts
+++ b/packages/workflow/workflow/src/index.ts
@@ -126,7 +126,7 @@ export type WorkflowErrorCode =
  * discipline: `parallel()`/`pipeline()` re-throw a fatal error (a typo'd
  * option or a tripped cap must kill the script loudly), and reserve the
  * per-item `null` for child-run failures and ordinary in-stage script errors.
- * Every {@link WorkflowErrorCode} is fatal in this cut; the flag exists so the
+ * Every {@link WorkflowErrorCode} is fatal; the flag exists so the
  * distinction is explicit at every catch site rather than implied.
  */
 export class WorkflowError extends HarnessError {

From e697bb3ca1039aa724a3aaf6efc76abb44a2411f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 17:46:21 +0800
Subject: [PATCH 508/516] =?UTF-8?q?docs:=20fix=20re-review=20findings=20?=
 =?UTF-8?q?=E2=80=94=20seat-migration=20obligation,=20evidence=20rule=20mo?=
 =?UTF-8?q?ved=20into=20the=20standard,=20first-cut=20family=20settled?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restore the ReactNode seats' pending-migration obligation the earlier
rewrite had flipped into a permanent exception; state the merged-PR/issue
evidence allowance in docs/AGENTS.md itself so the citations note defers
to the standard instead of overriding it; rewrite the one current-state
'first cut' fact and record the historical-stage-name exemption (with
indexical stamps still banned); pairs re-recorded.
---
 .../feature/2026-06-21-subagent-capability-seam.i18n.yaml     | 4 ++--
 .../feature/2026-06-21-subagent-capability-seam.md            | 2 +-
 .../feature/2026-06-21-subagent-capability-seam.zh.md         | 2 +-
 .../process/2026-08-09-committed-artifact-citations.i18n.yaml | 4 ++--
 .../process/2026-08-09-committed-artifact-citations.md        | 4 ++--
 .../process/2026-08-09-committed-artifact-citations.zh.md     | 4 ++--
 docs/AGENTS.md                                                | 2 +-
 packages/client/AGENTS.md                                     | 2 +-
 8 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index ac2a0bfb37..c68db1d6fd 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.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 .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
-2026-06-21-subagent-capability-seam.md: 72f17d7566aa982a5710e466cb4f740906ef167b
-2026-06-21-subagent-capability-seam.zh.md: 8205a6e2eab3bdaddf25b582c590034e2cf2f8dd
+2026-06-21-subagent-capability-seam.md: 28ecf985db1289ce4f80570583eac6a051cd2c0b
+2026-06-21-subagent-capability-seam.zh.md: 5f349ddcacebe66c346976b822c9dcc65bda8d18
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
index 72f17d7566..28ecf985db 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -73,4 +73,4 @@ Registry and tool tests replace only the nondeterministic child boundary with a
 - **Recursion.** Without a bound, an in-process child can see the delegation tool and recurse. The in-process backends implement the optional absolute depth limit and scoped live-global `toolFilter`; ACP advertises both capabilities off and rejects such a request. The [subagent composition-controls Agent Note](2026-07-12-subagent-persona-tool-filter-and-depth.md) owns their exact semantics and security limits.
 - **Blocking the parent turn.** Foreground collection holds the parent's step open for the child's full duration. Background delegation uses the shared `ctx.tasks` runtime and generic `task_*` tools, the same collection mechanism as background bash; the subagent seam itself remains task-agnostic.
 - **Live progress.** Only lifecycle + the final result surface; a per-chunk child→parent update stream is deferred with the background redesign.
-- **ACP client surface.** Proxying `fs`/`terminal` from the ACP child back to the parent (a shared-workspace mode) is future work; the first cut advertises neither, so the child self-serves in its own process.
+- **ACP client surface.** Proxying `fs`/`terminal` from the ACP child back to the parent (a shared-workspace mode) is future work; the backend advertises neither capability, so the child self-serves in its own process.
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index 8205a6e2ea..5f349ddcac 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -73,4 +73,4 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 - **递归。** 如果不设限制，进程内子 agent 能看到委派工具并递归调用。进程内后端实现了可选的绝对深度限制和有作用域的实时全局 `toolFilter`；ACP 声明这两项能力为关闭状态，并拒绝此类请求。[subagent 组合控制 Agent Note](2026-07-12-subagent-persona-tool-filter-and-depth.md) 负责定义它们的确切语义和安全边界。
 - **阻塞父轮次。** 前台收集在子 agent 的整个持续时间内保持父 agent 的步骤打开。后台委派使用共享的 `ctx.tasks` 运行时与通用 `task_*` 工具，与后台 bash 共用同一套收集机制；subagent seam 本身仍不感知任务。
 - **实时进度。** 仅暴露生命周期事件与最终结果；逐分片的子→父更新流推迟到后台重新设计时一并处理。
-- **ACP 客户端接口。** 将 ACP 子 agent 的 `fs`/`terminal` 代理回父 agent（共享工作区模式）是后续工作；首版不声明这两项能力，子 agent 在自己的进程中自行服务。
+- **ACP 客户端接口。** 将 ACP 子 agent 的 `fs`/`terminal` 代理回父 agent（共享工作区模式）是后续工作；该后端不声明这两项能力，子 agent 在自己的进程中自行服务。
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
index 022eb6655e..f3a910d338 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: 7d99a27238f25e7084fbbc816787c3c76a62bd89
-2026-08-09-committed-artifact-citations.zh.md: f09ae024c480d95dc95e39c62fbd1dc31f5b92a1
+2026-08-09-committed-artifact-citations.md: 890555df2968d706ba732aa8a3507bf81d187e3f
+2026-08-09-committed-artifact-citations.zh.md: 7eb446cca8fc0109814a8b2669a9a7031db9647b
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
index 7d99a27238..890555df29 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -12,11 +12,11 @@ Large design and review sessions leave working shorthand — decision ordinals,
 
 Durable prose — comments, JSDoc, docs, notes, test comments and titles — cites only committed artifacts, resolvable in-repo without grep archaeology:
 
-- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned in docs and code per the documentation standard; issues are durable and citable, and Agent Notes may cite merged PRs as evidence anchors — the standard routes change stories to commits, PRs, Agent Notes, and postmortems, and a note is that home.
+- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned in docs and code per the documentation standard; issues are durable and citable, and Agent Notes and postmortems may cite merged PRs and issues as evidence, per the [documentation standard](../../../../docs/AGENTS.md)'s change-story routing.
 - A design-session ordinal whose decision has a committed owner is replaced by the decision's name — the ordinal once logged as "decision 21" is now "the plain-text-reference decision", owned by the [web input-machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md); the ordinal itself resolves nowhere in-repo and was dropped everywhere. An ordinal without an owner is deleted and its factual clause restated to stand alone.
 - Fixed regressions are pinned as present-tense counterfactuals ("without X, Y happens"; "a naive X would…"), never as repo history ("used to Y").
 - Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
-- Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice.
+- Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice. Inside a note's change-story sections, a historical stage name ("the first cut shipped X") is current-state-safe; indexical stamps ("this cut") stay banned everywhere.
 
 One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (`scripts/gen-doc-graphs.ts`, `scripts/gen-tool-catalog.ts`, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records.
 
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
index f09ae024c4..7eb446cca8 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -12,11 +12,11 @@ Status: implemented
 
 持久行文（注释、JSDoc、文档、Agent Note、测试注释与测试标题）只引用已提交的产物，无需 grep 考古即可在仓库内解析：
 
-- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列；issue 是持久且可引用的，Agent Note 还可引用已合并的 PR 作为证据锚点——文档标准将变更故事归置于 commit、PR、Agent Note 与事后分析，note 正是这一归宿。
+- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列；issue 是持久且可引用的，Agent Note 与事后分析可依[文档标准](../../../../docs/AGENTS.md)的变更故事归置规则引用已合并的 PR 与 issue 作为证据。
 - 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」，归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)；该序号本身在仓库内无从解析，已全部移除。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
 - 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
 - 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
-- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。
+- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）属于安全的现状表述；指示性版本戳（「本版」「this cut」）在任何地方都仍被禁止。
 
 一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。
 
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index f373fd6469..a8d2a00e9d 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -35,7 +35,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 
 ## Writing rules
 
-- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems.
+- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the two documentation homes may cite merged PRs and issues as evidence.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index b67428953e..395b8b2cf6 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -23,7 +23,7 @@ How live data reaches render code, and what may cross a business boundary:
 1. **Everything a render reads that can change outside React arrives through a framework hook** (rule 4 above). Event-handler code may read live snapshots (e.g. `keyboard.snapshot`); render code subscribes.
 2. **Business components contain no subscription machinery** — no `useSyncExternalStore`, no manual subscribe wiring, no mirroring an external snapshot into local state or a second store. Give each reactive fact its owning channel instead: registrant-private → the inject `hooks` compartment; cross-entry or remount-surviving → a declared store; per-session standard → `sessions.provide`.
 3. **Data-access ladder** — resolve needs in this order: framework hooks (standing seats + provide/inject-bound `use<Name>`) → a declared store (`useStore`/`actions`) → inject callbacks → anything else is a new framework extension point and needs main-thread arbitration.
-4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are the sanctioned exceptions).
+4. **Contract currency is JSON-able data and callbacks.** Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject `hooks` compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing `accessory`/`overlay`/`leftItems`/`rightItems` seats are exceptions pending migration to slots).
 5. **An observable source keeps two identities stable**: the source object itself (hook binding is cached per source), and its snapshot between changes (`getSnapshot` returns the same reference until the fact moves).
 6. **Whoever rebuilds a published value republishes it through the same source in the same step**, and a registration path that can run after consumers exist notifies the live consumers as part of registering.
 

From 4eecc589408987a053f18e040bcde5f8448b5697 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 19:55:28 +0800
Subject: [PATCH 509/516] =?UTF-8?q?docs:=20harmonize=20rebase=20compositio?=
 =?UTF-8?q?ns=20=E2=80=94=20hardening=20phrasing,=20=E5=81=9C=E6=94=BE?=
 =?UTF-8?q?=E7=BA=A6=E5=AE=9A=20vocabulary,=20zh=20arm/this=20renderings?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...30-credential-boundaries-and-atomic-registration.i18n.yaml | 4 ++--
 ...026-07-30-credential-boundaries-and-atomic-registration.md | 2 +-
 ...-07-30-credential-boundaries-and-atomic-registration.zh.md | 2 +-
 .../2026-08-07-cancel-convergence-wake-latch.i18n.yaml        | 2 +-
 .../bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md    | 4 ++--
 .../feature/2026-07-30-search-render-card.i18n.yaml           | 2 +-
 .../implemented/feature/2026-07-30-search-render-card.zh.md   | 4 ++--
 .../implemented/feature/2026-07-30-web-result-card.i18n.yaml  | 2 +-
 .../implemented/feature/2026-07-30-web-result-card.zh.md      | 2 +-
 9 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
index 5955dd282f..124f633137 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.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 .agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
-2026-07-30-credential-boundaries-and-atomic-registration.md: e21b6d0ea5da30b77ab26b750e2294220646a20e
-2026-07-30-credential-boundaries-and-atomic-registration.zh.md: 6552db1932ca663c6228843cd62b5cc0f3811f24
+2026-07-30-credential-boundaries-and-atomic-registration.md: 4d962a822636bf2c82ecdccb9a1a136945a6e24e
+2026-07-30-credential-boundaries-and-atomic-registration.zh.md: cc17e99f434f71be3249bf9006441b4823957f44
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
index e21b6d0ea5..4d962a8226 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-07-30-credential-boundaries-and-atomic-registration.zh.md)
 
-> Scope: boundary hardening of the [request-level LLM configuration boundary](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this note applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
+> Scope: hardening the [request-level LLM configuration boundary](2026-07-29-request-level-llm-config-credentials.md) — where a stored credential lives and who can read it, how one request's facts stay one generation, and how a route set changes without a window. Companion to the [settings write-path note](2026-07-30-settings-write-path-integrity.md), whose provider fixes this note applies to `credentials-local` and whose writer lock it promotes into `dsh-atomic-write`.
 
 ## Problem
 
diff --git a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
index 6552db1932..cc17e99f43 100644
--- a/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-07-30-credential-boundaries-and-atomic-registration.md) | 中文
 
-> 范围：对[请求级 LLM（大语言模型）配置边界](2026-07-29-request-level-llm-config-credentials.md)的边界加固——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：它把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
+> 范围：加固[请求级 LLM（大语言模型）配置边界](2026-07-29-request-level-llm-config-credentials.md)——存下来的凭据落在哪里、谁能读到它，一次请求的事实如何保持为同一代，以及一组路由如何在不留空窗的前提下更换。本 note 与 [settings 写路径 note](2026-07-30-settings-write-path-integrity.md) 配套：它把那篇 note 的提供方修复套用到 `credentials-local`，并把其中的写锁提升进 `dsh-atomic-write`。
 
 ## 问题
 
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
index bcaa655054..831e905801 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md
 2026-08-07-cancel-convergence-wake-latch.md: de18dce87e28eaf0548eebd0d054d4ca7b59d0a6
-2026-08-07-cancel-convergence-wake-latch.zh.md: b07edfd94a547ecacc8176df86b58f1f701ec2e4
+2026-08-07-cancel-convergence-wake-latch.zh.md: bb67785512be9cd7b087d9f6c98f165a2a6468a6
diff --git a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
index b07edfd94a..bb67785512 100644
--- a/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.zh.md
@@ -12,13 +12,13 @@ Status: implemented
 
 `running` phase 携带 `wakeRequested` 锁存，与既有的 `maintenance` phase 字段对称。`wakeDriver()` 在当前活动无法投递唤醒时锁存——maintenance 任务从不读取队列，被中止的活动收敛后不会重启——而存活的 driver 不需要锁存，因为它自己会认领排队的工作。退出中的活动在其自身收敛边界（`kick` 的 `finally` 与 `runMaintenance` 的 `finally`）重放锁存：这一位置保证 `turn/end N` 先于重放 driver 打开 `turn/start N+1` 落盘，并保证 `whenIdle()` 通过其 `activityDone` 循环看到重放 driver。两个重放点仅在 `inbox.hasPending` 时执行，因此收敛前被从 inbox 移除的锁存唤醒不会启动空 driver。而 agent 已处于 idle 时发送的唤醒，即使消息在 driver 认领前被清除，仍会打开自己的 turn 边界——这趟 `idle → running → idle` 转换是可观察约定：goal-session driver 的 pause/disarm 回退依赖取消预订后的 `idle` 转换触发（把守卫放进 `wakeDriver()` 会抑制该边界）。不带 `keepInbox` 的 `cancel()` 会连同 inbox 一起清除锁存。
 
-`signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（`keepInbox` 停放契约）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
+`signal.aborted` 判别项是承重的：它区分「中断前已排队的工作」——`keepInbox` 将其停放以待后续唤醒（`keepInbox` 停放约定）——与「abort 后显式的唤醒」，后者必须在收敛后执行。
 
 ## 备选方案
 
 **让 `cancel()` 立即把 phase 置为 `idle`。** 不予采用：driver 仍在展开收尾，这会重叠两个 driver。重放逻辑位于旧 driver 的 `finally`，而该 `finally` 此后不再执行——83 个测试中有 14 个失败，多个死锁。修复它需要基于身份的 phase 所有权外加 turn 打开时的 quiescence 屏障，机制上严格更重，而且该屏障就是换了个形态的锁存。
 
-**对每个非 idle 唤醒无条件锁存。** 不予采用：中断前的唤醒会在 `keepInbox` 取消后自动启动，违反 `keepInbox` 停放契约；「停放排队工作」测试与错误窗口的 steering 测试双双失败。
+**对每个非 idle 唤醒无条件锁存。** 不予采用：中断前的唤醒会在 `keepInbox` 取消后自动启动，违反 `keepInbox` 停放约定；「停放排队工作」测试与错误窗口的 steering 测试双双失败。
 
 **通过链式 promise（`activityDone.then(...)`）重放。** 不予采用：重放会运行在活动自身结算之外，`whenIdle()` 的循环可能在重放 driver 启动前就 resolve；修复它需要在 send 时同步替换 `activityDone`，并依赖微任务反应顺序——比同步 flag 更脆弱。
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
index 1d5b00e8e0..c03e545b40 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-search-render-card.md
 2026-07-30-search-render-card.md: 585609bd059dbd9aa8283547fa8a4b223f7bdd99
-2026-07-30-search-render-card.zh.md: 2cb28a29f8a1a265310fecb1f0a315d010250e02
+2026-07-30-search-render-card.zh.md: a129b024fcbe067025e9bcd6cfd6aeeb5400347a
diff --git a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
index 2cb28a29f8..a129b024fc 100644
--- a/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md
@@ -56,6 +56,6 @@ Status: implemented
 
 ## 相关
 
-- [工具调用呈现的带标签渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 本 PR 用 `search` 结果标签扩展的 `card` 标签词汇。
+- [工具调用呈现的带标签渲染意图联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 本变更用 `search` 结果标签扩展的 `card` 标签词汇。
 - [Canonical 工具输出约定](../architecture/2026-07-20-canonical-tool-output-contract.md) —— 本投影所乘的 value/render/`presentationMeta` 划分；结构化值留在执行本地，卡片乘 `meta`。
-- [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— 本 PR 在后端镜像的先例：工具把结果投影进 `presentationMeta` 与一个 `presentResult` 视图；搜索卡片的 web 消费方是与之类比的后续。
+- [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— 本变更在后端镜像的先例：工具把结果投影进 `presentationMeta` 与一个 `presentResult` 视图；搜索卡片的 web 消费方是与之类比的后续。
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
index cb45227d19..b6ab8c9f92 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-web-result-card.md
 2026-07-30-web-result-card.md: 591471d219295019d28b9eeaf2e57f6d2115d380
-2026-07-30-web-result-card.zh.md: a2e0096599a30bcdd1d8a956d8f1c13c1c0622fd
+2026-07-30-web-result-card.zh.md: b84cdc69c132f7764874f14adac92918ba60f86e
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
index a2e0096599..b84cdc69c1 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md
@@ -41,4 +41,4 @@ Status: implemented
 ## Related
 
 - [标签化的工具调用渲染意图联合类型](../architecture/2026-07-02-tool-render-intent-union.md) —— 本卡片以 `web` 分支扩展的 `card` 标签词汇表。
-- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；[Web result card 前端](2026-07-30-web-result-card-frontend.md)是它在本分支上的对应物。
+- [Web terminal card](2026-07-28-web-terminal-card.md) —— 把 bash `terminal` 渲染意图带到浏览器的先例；[Web result card 前端](2026-07-30-web-result-card-frontend.md)是它在这一支上的对应物。

From dd384f86ab488c568e2c16a2dc987c70a2266c1a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:13:09 +0800
Subject: [PATCH 510/516] docs: bring generated-catalog zh pairs along; raise
 docs/AGENTS.md ceiling to 1335
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Master's bilingual-generated-docs policy pairs the five generated catalogs;
mirror the purge's regenerated English (ConPTY note, hooks TODO wording,
thinking-format and SurfaceOp JSDoc, doc-graphs templates) into their
reviewed zh sides and re-record. Condense the evidence-citation clause and
raise the docs/AGENTS.md ceiling 1320→1335: master's seam-trio definition
and this PR's review-mandated evidence rule land in the same window.
---
 docs/AGENTS.md                         |  2 +-
 docs/capability-seams.i18n.yaml        |  4 ++--
 docs/capability-seams.zh.md            |  2 +-
 docs/config-catalog.i18n.yaml          |  4 ++--
 docs/config-catalog.zh.md              | 16 +++++++---------
 docs/event-producer-consumer.i18n.yaml |  4 ++--
 docs/event-producer-consumer.zh.md     |  2 +-
 docs/persistence-catalog.i18n.yaml     |  4 ++--
 docs/persistence-catalog.zh.md         |  5 +++--
 docs/tool-catalog.i18n.yaml            |  4 ++--
 docs/tool-catalog.zh.md                |  4 ++--
 scripts/doc-budgets.manifest.json      |  2 +-
 12 files changed, 26 insertions(+), 27 deletions(-)

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index a8d2a00e9d..aa9db3dcff 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -35,7 +35,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 
 ## Writing rules
 
-- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the two documentation homes may cite merged PRs and issues as evidence.
+- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the latter two may cite merged PRs and issues as evidence.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml
index fb4d773d5c..aa09cb3036 100644
--- a/docs/capability-seams.i18n.yaml
+++ b/docs/capability-seams.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 docs/capability-seams.md
-capability-seams.md: d61353210eedb3de68dd19caa866d4efb9deb19a
-capability-seams.zh.md: 75bf176952a8c06c723e9f7cda535c1ca8b69819
+capability-seams.md: af9f8ba48e67074a485019a4ad9dddd08b2faf81
+capability-seams.zh.md: 7dff963646991d8b1f763ed789109e93cce2ddb8
diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md
index 75bf176952..7dff963646 100644
--- a/docs/capability-seams.zh.md
+++ b/docs/capability-seams.zh.md
@@ -419,7 +419,7 @@ flowchart LR
 | `ctx.permission` | `core` | [`permission`](../packages/interaction/permission) | - | - | - | 面向用户的预设表（`workspace-write`／`danger-full-access`），将沙箱模式与审批策略选项组合在一起；一次切换会写入一个 `permission/preset` 事件，并贯通到两个选项事件。 |
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | 使用 Host 提供的异步绑定运行一段由模型编写的程序；各后端采用不同的基础环境和语言（工具注册表在 Code Mode 下消费该服务）。 |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local)、[`fs-sandbox`](../packages/fs/fs-sandbox)、[`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs 通过 ctx.fs 执行读取／写入／编辑；fs-sandbox 按共享沙箱模式限制变更；fs-policy 通过 fs/* 事件门禁贡献基于观测状态的检查。 |
-| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；面向模型的压缩工具仍处于暂缓状态。 |
+| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；不存在面向模型的压缩工具。 |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn)、[`subagent-fork`](../packages/subagent/subagent-fork)、[`subagent-acp`](../packages/subagent/subagent-acp)、[`subagent-codex`](../packages/subagent/subagent-codex)、[`subagent-claude-code`](../packages/subagent/subagent-claude-code)、[`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-subagent-control`](../packages/subagent/tool-subagent-control)、[`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输；该服务还负责可选的、基于 Activation 的延续编排，tool-subagent 选择一次性或可延续委派，tool-subagent-control 传递后续消息，而 tool-ralph 要求一条全新的结构化输出路由。 |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-tasks`](../packages/tasks/tool-tasks) | - | 生产方（后台 bash、PTY 发送和 subagent 委派）登记正在运行的工作；tool-tasks 是面向模型的控制接口，用于读取、列出和终止这些工作；tasks-local 是进程本地注册表。 |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa)、[`web-search-perplexity`](../packages/web/web-search-perplexity)、[`web-search-deepseek`](../packages/web/web-search-deepseek)、[`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | 搜索和抓取提供方注册到同一个 ctx.web seam；tool-web 负责稳定的面向模型名称。 |
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 12f3e2861c..80ac35ca4e 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: 7278447cf85c2b25f7dd42e10e4b0b1cbd7eb96b
-config-catalog.zh.md: a7d4252c526d36643a1b9f7aebd627faa60e1c77
+config-catalog.md: 10f0761fc5aa69852dff06f340f83f5a916975a9
+config-catalog.zh.md: ec0e44e9d39b801a5987f2bdab2584370c1b9333
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index a7d4252c52..ec0e44e9d3 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -413,7 +413,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts)
+来源：[`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-e2b`
 
@@ -515,7 +515,7 @@ export interface Config {
    * Process-level: read once at load, a relative path resolves against the process
    * launch cwd, so one config applies to the whole process.
    * TODO(per-session-hook-config): per-session discovery of a project-local
-   * `hooks.json` from each `session/new.cwd` is not yet implemented.
+   * `hooks.json` from each `session/new.cwd`.
    */
   configPath: string
   /**
@@ -550,7 +550,7 @@ export interface Config {
    * Path to a Codex `hooks.json`. Process-level: read once at load, a relative
    * path resolves against the process launch cwd.
    * TODO(per-session-hook-config): per-session project-local discovery from each
-   * `session/new.cwd` is not yet implemented.
+   * `session/new.cwd`.
    */
   configPath: string
   /** The model name stamped on every payload (Codex includes `model` on each event). */
@@ -848,8 +848,7 @@ type PiThinkingFormat = NonNullable<OpenAICompletionsCompat['thinkingFormat']>
 
 /**
  * pi-ai thinking formats a profile cannot name: both drive the request through
- * `chatTemplateKwargs`, which this configuration does not expose, so offering
- * them would hand back a format with nothing to say.
+ * `chatTemplateKwargs`, which this configuration does not expose.
  */
 type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
 ```
@@ -1691,7 +1690,7 @@ export interface Config {
   /**
    * How to auto-answer the child's `session/request_permission` prompts:
    * `reject` (default — decline every prompt) or `allow` (approve via the first
-   * allow-shaped option). The first cut surfaces no prompt to a human.
+   * allow-shaped option). No prompt is surfaced to a human.
    */
   permission: PermissionPolicy
   /**
@@ -2361,8 +2360,7 @@ export interface Config {
  * ask BEFORE any interactive answerer sees it:
  *
  * - `'ask'` (the default) — delegate to the composed answerers; with none
- *   composed the chain falls through to the fail-closed `'unavailable'`
- *   (exactly today's behavior).
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
  * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
  *   deterministically. The strict headless stance (CI, unattended runs) and
  *   the policy whose outcome is knowable without asking.
@@ -2370,7 +2368,7 @@ export interface Config {
 export type ApprovalPolicy = 'ask' | 'never'
 ```
 
-来源：[`packages/interaction/user-approval/src/index.ts:178`](../packages/interaction/user-approval/src/index.ts)
+来源：[`packages/interaction/user-approval/src/index.ts:177`](../packages/interaction/user-approval/src/index.ts)
 
 ## `@deepseek-ai/dsh-web`
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 89e1b03d35..0a3d6007f1 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md
-event-producer-consumer.md: 05ff62a391a0acb7db9abd2c9ce0c2082da52eaa
-event-producer-consumer.zh.md: 7eafe5f2880cf9f0e6f2e7eb6c299730926f15ed
+event-producer-consumer.md: 11eecf81a4eccadf2b97026154a78e4ed8a72164
+event-producer-consumer.zh.md: 2db5e596465b4adaf98c1b05692b61de3ced47b9
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 7eafe5f288..2db5e59646 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -5,7 +5,7 @@
 
 [English](event-producer-consumer.md) | 中文
 
-本矩阵展示哪些包会派发各个 harness 自有事件，以及哪些包会监听这些事件。这里特意采用表格而非一张大型关系图：事件之间存在多对多关系，以表格逐行呈现密集的关系数据更便于评审。接收方和事件名称类型还涵盖有意绕过 `ctx.emit` 的内含派发位置，例如 subagent 生命周期封装。
+本矩阵展示哪些包会派发各个 harness 自有事件，以及哪些包会监听这些事件。事件之间存在多对多关系，因此密集的关系数据以表格而非一张大型关系图呈现。接收方和事件名称类型还涵盖有意绕过 `ctx.emit` 的内含派发位置，例如 subagent 生命周期封装。
 
 | 事件 | 模式 | 声明位置 | 派发方 | 监听方 |
 | --- | --- | --- | --- | --- |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index e676227869..e5dd4edde7 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.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 docs/persistence-catalog.md
-persistence-catalog.md: c9aa15cd827d99cee64e7a33db11995ee17f9bf8
-persistence-catalog.zh.md: d8743a1b0f26f2a4cf50aed42eb68f6c6db1ba13
+persistence-catalog.md: a17cae015eaa107a900069de916dddb216b87ec7
+persistence-catalog.zh.md: 3aef073dedcff0b6addb99d7c287f4e5f372c402
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index d8743a1b0f..3aef073ded 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -37,7 +37,8 @@ export type SurfaceEventType =
  *   (inclusive) through `end` (inclusive) with this node. Both must exist as
  *   surface nodes in the current surface. `start === end` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
- *   shadowed surface node. Used by compaction and possible other manipulations.
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
  */
 export type SurfaceOp =
   | 'append'
@@ -80,7 +81,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```
 
-来源：[`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:343`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:375`](../packages/core/session/src/types.ts)
+来源：[`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:344`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:376`](../packages/core/session/src/types.ts)
 
 ## 事件
 
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 1ae1b619f3..3e74bbc3e6 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.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 docs/tool-catalog.md
-tool-catalog.md: f6a41da266db6eb2f347fb3c455a67b4dd44c4c0
-tool-catalog.zh.md: b36e8ccf63f4bdde7efca050bd92cbfcb03b3fbb
+tool-catalog.md: 58267e208d919e7fa817991207a44ac0864fa00e
+tool-catalog.zh.md: 1eda3506644bae6da56895c366a56b566536ed62
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index b36e8ccf63..1eda350664 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -21,7 +21,7 @@
 | `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`、`ctx.codeRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`one tool/code-dispatch-start + tool/code-dispatch pair per bridged sub-call`、`tool/result` | - | 在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 |
 | `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userInteraction (execution time, opportunistic)` | `tool/call`、`plan/mode inactive on an approved review`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 |
 | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具（来自 `@deepseek-ai/dsh-tool-tasks`）收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 |
-| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
+| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 |
 | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`process-local temporary Plugin lifecycle` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 |
 | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 |
 | `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after view presence/absence, edit absence, or successful mutation`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 |
@@ -250,7 +250,7 @@ bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_bac
 
 来源：[`packages/bash/tool-pwsh/src/index.ts`](../packages/bash/tool-pwsh/src/index.ts)
 
-pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。
+pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。
 
 ## `@deepseek-ai/dsh-tool-cordis`
 
diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json
index 2626cec2da..575f25b61b 100644
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,6 +1,6 @@
 {
   "AGENTS.md": 1782,
-  "docs/AGENTS.md": 1320,
+  "docs/AGENTS.md": 1335,
   "docs/architecture.md": 2174,
   "docs/cordis-primer.md": 600,
   "docs/defensive-patterns.md": 550,

From 8053dc38faaa3c92c2cf3c275c64771abcc733a2 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:48:10 +0800
Subject: [PATCH 511/516] test(snapshot): refresh translation-prompt expected
 output

The assembled request embeds docs/i18n/translation-prompt.md's header and
the bilingual-pairing-gate note as its worked example; the purge edited
both, so the recorded request text follows.
---
 .../translation-prompt-v4/request-response.expected.json      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 1324d44969..587d59a8bd 100644
--- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json
+++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
@@ -40,11 +40,11 @@
       },
       {
         "role": "user",
-        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — the design first proposed for this Agent Note: `.zh.md` files carried an HTML comment recording the English source's blob hash, and translation flowed EN → ZH only. Revised in review: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
+        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../scripts/translation-prompt.snapshot.ts) pins the rendered system message, five reviewed example pairs, source request, and consumed response. Together these checks make pair drift, publication drift, configuration misclassification, and model-visible prompt drift review-visible.\n\n## Alternatives considered\n\n- **English as the canonical source with a fingerprint inside the translation** — `.zh.md` files would carry an HTML comment recording the English source's blob hash, and translation would flow EN → ZH only. Rejected: the team wants Chinese-first authoring (write and review a Chinese Agent Note, then translate to English) with the two languages holding equal authority, which a one-directional canonical model cannot express. The sidecar record covering BOTH sides replaced the in-file one-directional fingerprint; the blob-hash mechanics survived unchanged.\n- **Locale directories (`docs/en/` + `docs/zh/`, the Kubernetes/ECharts model)** — rejected: this repo has no docs-site framework to map locales to routes, moving every English file would churn every existing cross-reference, and `verify-md-links`/`verify-doc-refs` would need path-mapping logic instead of working unchanged.\n- **A separate translation repo (the PingCAP `docs`/`docs-cn` model)** — rejected: right for a docs product with independent release trains, overkill for a monorepo's own documentation; it also puts the translation outside the reach of this repo's gates.\n- **Interleaved bilingual files (single file, both languages)** — rejected: doubles every diff, breaks the one-line-per-paragraph convention's diff ergonomics, and makes partial inconsistency invisible.\n- **Commit-hash records (the MDN `l10n.sourceCommit` model)** — rejected in favor of blob hashes: a same-PR edit has no commit hash yet, so the MDN model cannot express \"consistent as of the state this PR introduces\", and verifying it requires git history instead of file content.\n- **Comparing git timestamps of the pair (no record)** — rejected: formatting-only edits would false-positive, and a counterpart committed after an unrelated edit would false-negative; content identity is the only signal that means what the gate claims.\n\n## Industry precedent\n\nPaired sibling files with locale suffixes are the dominant Chinese big-tech convention (ant-design `index.zh-CN.md`/`index.en-US.md`; arco-design `README.zh-CN.md` with a top-of-file switcher; Apache ShardingSphere's 387 `.cn.md`/`.en.md` pairs) — but none of those repos *enforce* pairing or consistency in CI; the convention holds by review alone. Consistency automation exists outside China: MDN's `l10n.sourceCommit` front-matter fingerprint, Vue's Ryu-Cho action (upstream-commit watcher that opens issues/PRs for stale translations), Kubernetes' localization drift scripts, and Microsoft's Azure co-op-translator (source-hash-driven LLM re-translation in CI). This design combines the two: the Chinese-ecosystem file layout with a hash-pair gate, plus a committed agent skill in place of a bot service.\n\n## Consequences\n\n- Editing either side of a paired document obligates the same PR to update the counterpart and re-record the pair — the gate makes the doc-sync rule bilingual, and CI (not reviewer memory) carries the invariant.\n- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, \"who confirmed these consistent, and when\" is answerable from git blame on the yaml.\n- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.\n- Generated English documents remain derived from source and freshness-gated by their owning generators. A generated page with a reviewed Chinese counterpart participates in the three-file pairing workflow, with one structural exception: the generated English source has no language switcher because adding one would make the generator stale, while the Chinese counterpart links back to it. Generated pages without a reviewed counterpart remain explicit exclusions and use an English website projection.\n- The exclusions-only manifest makes every current and future in-scope document mandatory through the same path. There is no explicit requirement, cutoff, or class entry that can fall outside discovery while appearing enforced.\n- The recorded hashes double as the update tool: [gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) recovers either side's last-confirmed text from them and assembles the minimal-update briefing, so re-translation of whole files is never forced by the mechanism.\n"
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、中文侧和所有普通撰写的英文源都带切换行而清单内的生成英文源除外、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：本 Agent Note 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、中文侧和所有普通撰写的英文源都带切换行而清单内的生成英文源除外、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分类和模型可见提示词漂移都可在评审中看见。\n\n## 曾考虑的替代方案\n\n- **英文为正典源、指纹放在译文内**：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。否决：团队需要中文先行的撰写方式（先写、先审中文 Agent Note，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。\n- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。\n- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。\n- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。\n- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。\n- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。\n\n## 业界先例\n\n带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。\n\n## 后果\n\n- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。\n- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。\n- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。\n- 生成的英文文档仍由源码派生，并由各自的生成器实施新鲜度门禁。有经评审中文对侧的生成页面遵循三文件配对工作流，但有一项结构例外：生成的英文源文件不含语言切换行，因为添加该行会使生成器新鲜度检查失败；中文对侧仍链接回英文源。没有经评审对侧的生成页面保留为显式排除项，并在网站上投影英文。\n- 只含排除项的 manifest 通过同一路径，要求当前及今后纳入范围的每篇文档都必须配对。不存在显式要求、分界或类别条目可以落在发现范围之外，却看似已经强制执行。\n- 记录的 hash 兼作更新工具：[gen-translation-brief](2026-07-26-briefed-minimal-translation-updates.md) 会从中还原任一侧上次确认的文本并组装最小更新简报，因此这套机制从不强迫整篇重译。\n"
       },
       {
         "role": "user",

From eeacdd4790ff71e7c65844dcc435bd6243d0fa3d Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 21:01:51 +0800
Subject: [PATCH 512/516] =?UTF-8?q?docs:=20fix=20round-3=20review=20findin?=
 =?UTF-8?q?gs=20=E2=80=94=20=C2=A7/used-to/v1=20residuals,=20zh=20stamp=20?=
 =?UTF-8?q?example,=20budget=20freeze=20honored?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Delete the three §-citation residuals (web-app cordis.patch.yml, two
client design.md §-headers); recast the two CSS used-to narrations and
hmr's four v1 labels as current-state prose; narrow the zh exemption
example to 'this cut' (「本版本」 legitimately renders 'This version');
extend the candidate gate list with the post-battery shapes (§\d with a
committed-owner carve-out, 'used to', bare v1) on both sides and
re-record; honor the over-target ceiling freeze — docs/AGENTS.md
condensed to 1320 and the ceiling restored to 1320.
---
 ...2026-08-09-committed-artifact-citations.i18n.yaml |  4 ++--
 .../2026-08-09-committed-artifact-citations.md       |  2 +-
 .../2026-08-09-committed-artifact-citations.zh.md    |  4 ++--
 docs/AGENTS.md                                       | 12 ++++++------
 packages/bundle/web-app/cordis.patch.yml             |  4 ++--
 packages/client/hmr/src/client/index.ts              |  8 ++++----
 packages/client/runtime/tests/slots-service.spec.ts  |  2 +-
 .../src/client/skeleton/InputBar.module.css          |  6 +++---
 .../ui-models/src/client/ModelsSection.module.css    |  8 ++++----
 packages/client/ui-slots/tests/type-chain.spec.tsx   |  2 +-
 scripts/doc-budgets.manifest.json                    |  2 +-
 11 files changed, 27 insertions(+), 27 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
index f3a910d338..9c9cb9b476 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: 890555df2968d706ba732aa8a3507bf81d187e3f
-2026-08-09-committed-artifact-citations.zh.md: 7eb446cca8fc0109814a8b2669a9a7031db9647b
+2026-08-09-committed-artifact-citations.md: 31b2d52b423a080579b3ca95cf077859d0bf4c91
+2026-08-09-committed-artifact-citations.zh.md: b69bb8743d10e2d1e194905d6d0de2d3d3667b1d
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
index 890555df29..31b2d52b42 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -23,7 +23,7 @@ One repo-wide purge applied these rules across the prose surfaces, including the
 ## Alternatives considered
 
 - **Commit the design ledgers and audit documents so the ordinals resolve.** Rejected: session transcripts are working artifacts, not maintained references; committing them would create a parallel, ungated decision corpus beside Agent Notes, and their internal numbering would still drift.
-- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d`, `\(audit [A-Z]\d`, `\bcut \d`, `this cut`, a bare `\bT\d\b`, and `P-I`) is the candidate if the pattern recurs; review of the purge itself caught residuals in exactly those last four shapes, so they lead the candidate list.
+- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d`, `\(audit [A-Z]\d`, `\bcut \d`, `this cut`, a bare `\bT\d\b`, `P-I`, `used to `, a bare `\bv1\b`, and `§\d` — the last excluding citations whose section numbering has a committed owner, such as web-styling.md's own §N) is the candidate if the pattern recurs; review of the purge itself caught residuals in exactly these post-battery shapes, so they lead the candidate list.
 - **Delete the rationale that cited dead artifacts.** Rejected: the factual clauses were preserved or restated; only citations, review choreography, and derivation transcripts were removed, per the prose standard's complete-proposition rule.
 
 ## Verification
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
index 7eb446cca8..b69bb8743d 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -16,14 +16,14 @@ Status: implemented
 - 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」，归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)；该序号本身在仓库内无从解析，已全部移除。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
 - 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
 - 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
-- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）属于安全的现状表述；指示性版本戳（「本版」「this cut」）在任何地方都仍被禁止。
+- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）属于安全的现状表述；指示性切次戳（"this cut"）在任何地方都仍被禁止。
 
 一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。
 
 ## 曾考虑的替代方案
 
 - **把设计台账与审计文档提交入库，让序号得以解析。**不予采纳：会话 transcript 是工作产物，不是持续维护的参考资料；提交它们会在 Agent Note 之外形成一套平行且不受门禁约束的决策语料，其内部编号也仍会漂移。
-- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d`、`\(audit [A-Z]\d`、`\bcut \d`、`this cut`、裸 `\bT\d\b` 与 `P-I`）；对本次清扫自身的评审恰好在后四种形态中发现残留，因此它们位居候选清单之首。
+- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d`、`\(audit [A-Z]\d`、`\bcut \d`、`this cut`、裸 `\bT\d\b`、`P-I`、`used to `、裸 `\bv1\b` 与 `§\d`——最后一种需排除章节编号有已提交归属的引用，如 web-styling.md 自身的 §N）；对本次清扫自身的评审恰好在这些电池之外的形态中发现残留，因此它们位居候选清单之首。
 - **删除引用了失效产物的设计理由。**不予采纳：事实性语句都得到保留或改写；依行文标准的完整命题规则，删掉的只有引用、评审编排与推导过程记录。
 
 ## 验证
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index aa9db3dcff..04cd0f22f0 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -4,7 +4,7 @@ This file defines document structure, Markdown tiers, writing rules, and `verify
 
 ## Document structure
 
-These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail, describe direct children only by purpose, responsibility, and high-level behavior, and link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
+These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
 
 Classify every in-scope document as a tutorial or reference. A tutorial follows an ordered path to an outcome and introduces only what each step needs. A reference defines a lookup scope and describes current behavior without depending on a teaching sequence. Separate substantial tutorial and reference content; use a clear structural boundary when either part is small.
 
@@ -14,7 +14,7 @@ Author in this order: locate the document in the tree; set its permitted detail;
 
 ## The tier taxonomy: one home per fact
 
-Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
+Each fact has one home: the tier whose job it is; elsewhere, link there.
 
 | Tier | Job | Does NOT belong there |
 |---|---|---|
@@ -52,21 +52,21 @@ When the gate goes red:
 
 1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
 2. **Condense** content that belongs here but can be shorter.
-3. **Raise** the ceiling only when the words truly need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
+3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
 
 Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the contract still has room, and raise it when content would otherwise be deleted. Targets: root `AGENTS.md` ≤ 1,600 words; `architecture.md` ≤ 1,800; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 650 and this file ≤ 1,250; `packages/README.md` ≤ 600. Review governs unbudgeted tiers.
 
 ## The slop checklist
 
-Hunt these in any doc; the [dsh-doc-standards](../.agents/skills/dsh-doc-standards/SKILL.md) skill runs this list as an audit:
+Hunt these in any doc; [dsh-doc-standards](../.agents/skills/dsh-doc-standards/SKILL.md) runs this list as an audit:
 
-- The same rule stated in more than one home. Grep a distinctive phrase; keep one home, convert the rest to links.
+- The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
 - Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link an Agent Note or postmortem when needed.
 - Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
 - Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
 - Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
 - Rationale repeated beside sibling methods instead of once at the owning capability or helper.
-- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it, or demote the detail to the linked home.
+- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
 - Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
 - Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
 
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index d4fb2e8511..c3a66ebbf4 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -105,8 +105,8 @@
 
     # Dual-face: node half scans this very tree for dshClient rows, composes
     # window.__DSH_BOOT__, serves /plugins/<id>/client.js; browser half is the
-    # module table the shell kernel constructs before cordis exists (§4.7 —
-    # adopted as a plugin entry by the kernel, never fetched).
+    # module table the shell kernel constructs before cordis exists (adopted
+    # as a plugin entry by the kernel, never fetched).
     - id: modules
       name: '@deepseek-ai/dsh-client-modules'
 
diff --git a/packages/client/hmr/src/client/index.ts b/packages/client/hmr/src/client/index.ts
index 99f0938555..d0558bcecc 100644
--- a/packages/client/hmr/src/client/index.ts
+++ b/packages/client/hmr/src/client/index.ts
@@ -30,7 +30,7 @@
  * Failure window: if prefetch rejects after invalidate, the module is left
  * unregistered while the OLD fiber keeps running untouched (teardown never
  * started) — degraded but recoverable, the next rebuilt frame retries from
- * scratch. Consistent with the v1 no-rollback policy below. Known dev-only
+ * scratch. Consistent with the no-rollback policy below. Known dev-only
  * race: a rebuilt frame overlapping a still-in-flight boot arrival shares
  * that arrival's task and may materialize the pre-rebuild bytes; the next
  * rebuilt frame self-heals.
@@ -57,7 +57,7 @@
  * apply opens a fresh channel. Frames arriving during the gap are lost —
  * acceptable for the dev channel, the next rebuild renotifies.
  *
- * Failure policy (v1): no rollback. An import failure leaves the entry
+ * Failure policy: no rollback. An import failure leaves the entry
  * fiberless (the next rebuilt frame retries from scratch); an apply failure
  * leaves a FAILED fiber for the shell's status projection. Both log loudly.
  */
@@ -135,7 +135,7 @@ export function apply(ctx: Context): void {
     // re-plugins under the entry context. Import failures are logged by
     // Entry._init and leave the entry fiberless (retryable).
     await entry.refresh()
-    // Surface apply failures loudly (v1: no rollback, FAILED state stays).
+    // Surface apply failures loudly (no rollback, FAILED state stays).
     await entry.fiber?.await()
   }
 
@@ -151,7 +151,7 @@ export function apply(ctx: Context): void {
         })
         break
       case 'graph':
-        // Connect-time snapshot, unused in v1. The loader's cached graph rev
+        // Connect-time snapshot, unused. The loader's cached graph rev
         // goes stale after rebuilds — harmless, since prefetch hits the
         // network anyway (host serves bundles no-cache); graph rev refresh
         // lands with the reconnect-handshake mechanism.
diff --git a/packages/client/runtime/tests/slots-service.spec.ts b/packages/client/runtime/tests/slots-service.spec.ts
index 0b8ce8a301..a796d324ee 100644
--- a/packages/client/runtime/tests/slots-service.spec.ts
+++ b/packages/client/runtime/tests/slots-service.spec.ts
@@ -1,5 +1,5 @@
 /**
- * SlotsService terminal-design account (design.md §11-3 main landing):
+ * SlotsService terminal-design account:
  * built-in 'root', the three load-time throws (duplicate declaration /
  * undeclared contribution / cross-scope store handle), the renderer installation
  * contract (double install / not installed / non-root key), store instance
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index fdbf28c74b..26f3532426 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -225,9 +225,9 @@
      so by construction now that all three sit INSIDE .scroll — a scrollbar
      that consumes layout space narrows the scrollport, which is their shared
      containing block, so it costs all three the same width on every engine.
-     Scrolling the textarea itself is what used to break this, and no property
-     fixed it: WebKit reserved gutter space for the overflow-y:auto textarea
-     and not for the overflow:hidden layers beside it, leaving them 8px apart
+     A textarea that scrolls itself would break this, and no property fixes
+     it: WebKit reserves gutter space for an overflow-y:auto textarea and not
+     for the overflow:hidden layers beside it, leaving them 8px apart
      (768 against 776) — worth 2 to 5 wrapped lines on a long draft. */
 }
 
diff --git a/packages/client/ui-models/src/client/ModelsSection.module.css b/packages/client/ui-models/src/client/ModelsSection.module.css
index 8facc3a110..5203524517 100644
--- a/packages/client/ui-models/src/client/ModelsSection.module.css
+++ b/packages/client/ui-models/src/client/ModelsSection.module.css
@@ -3,10 +3,10 @@
  * 32px fields, and `border-l2` hairlines — the vocabulary GeneralSection and
  * the Button/Input primitives already use.
  *
- * Every color resolves through a `--dsw-alias-*` token. The section used to
- * name `--border` / `--surface` / `--text-*`, which nothing in this app
- * defines, so it always rendered the light-mode literals written as their
- * fallbacks and stayed light under the dark theme. */
+ * Every color resolves through a `--dsw-alias-*` token. Bare `--border` /
+ * `--surface` / `--text-*` names, which nothing in this app defines, would
+ * render the light-mode literals written as their fallbacks and stay light
+ * under the dark theme. */
 
 .section {
   display: flex;
diff --git a/packages/client/ui-slots/tests/type-chain.spec.tsx b/packages/client/ui-slots/tests/type-chain.spec.tsx
index 64277edccc..a65f56a508 100644
--- a/packages/client/ui-slots/tests/type-chain.spec.tsx
+++ b/packages/client/ui-slots/tests/type-chain.spec.tsx
@@ -1,4 +1,4 @@
-// Terminal-design compile-time samples (design.md §11 item 2): the four-share
+// Terminal-design compile-time samples: the four-share
 // composed register constraint — children spec x SlotMap alignment, renderSlot
 // key-set containment, store share matching, inject face completeness — plus
 // the full positive chain. Bodies with @ts-expect-error sites never run.
diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json
index 575f25b61b..2626cec2da 100644
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,6 +1,6 @@
 {
   "AGENTS.md": 1782,
-  "docs/AGENTS.md": 1335,
+  "docs/AGENTS.md": 1320,
   "docs/architecture.md": 2174,
   "docs/cordis-primer.md": 600,
   "docs/defensive-patterns.md": 550,

From 54b898463c0a8dd0be22bf54aa94be8848c4492f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 21:20:18 +0800
Subject: [PATCH 513/516] fix(rebase): drop transcript-adapter files
 resurrected over master's deletion

Master's conversation-node engine deleted transcript-adapter.ts and its
spec; the rebase's modify/delete conflicts were staged as keep-ours,
resurrecting both with a stale dsh-compact import. Remove them; the
purge edits they carried died with the files upstream.
---
 .../src/client/sessions/transcript-adapter.ts | 408 -------------
 .../runtime/tests/transcript-adapter.spec.ts  | 567 ------------------
 2 files changed, 975 deletions(-)
 delete mode 100644 packages/client/runtime/src/client/sessions/transcript-adapter.ts
 delete mode 100644 packages/client/runtime/tests/transcript-adapter.spec.ts

diff --git a/packages/client/runtime/src/client/sessions/transcript-adapter.ts b/packages/client/runtime/src/client/sessions/transcript-adapter.ts
deleted file mode 100644
index ce12d3a89c..0000000000
--- a/packages/client/runtime/src/client/sessions/transcript-adapter.ts
+++ /dev/null
@@ -1,408 +0,0 @@
-// TranscriptAdapter: the human transcript projected from the raw event window
-// in LOG order. The model-visible surface deliberately shadows replaced ranges,
-// so it is the wrong source for conversation a reader already saw; this adapter
-// keeps every append-origin event at its own log position and contributes one
-// marker node per landed compaction checkpoint. Node order is therefore
-// seq-monotonic by construction.
-
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-// Subpath export (package.json exports "./surface"): all value imports
-// go through it — the package root points at lib/index.js (needs a build) which the vite
-// browser bundle cannot resolve; surface.ts has no Node dependencies.
-import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface'
-import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-// Cordis-free leaf subpath (the dsh-commands/brand shape): the Service Definition's
-// declaration of the checkpoint source, reachable as a TYPE from this program.
-// The package ROOT is not — it reaches dsh-session's root, whose Context merge
-// declares the HOST `sessions: SessionStore` against this program's
-// `sessions: ISessions` (TS2717, the one-program-per-side rule in
-// docs/development.md).
-import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
-import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
-import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
-import { toAssistantBlocks } from './conversation.ts'
-import { contextForm, contextProvenance } from './context-provenance.ts'
-import { SteeringHistory } from './steering-history.ts'
-import type { AssistantStepMetadata } from './assistant-timing.ts'
-import { indexAssistantStepTiming, settledAssistantTiming } from './assistant-timing.ts'
-
-/**
- * The compaction capability's checkpoint plugin, pinned to the Service Definition's declaration
- * at COMPILE time: renaming it there fails this annotation (`TS2322`). The
- * import stays type-only because a value import would fail the client purity
- * gate (`packages/client/tsdown.client.ts`) — cross-plugin value imports are
- * forbidden in a browser bundle — while an erased type never reaches it.
- */
-const COMPACT_PLUGIN: typeof COMPACT_CHECKPOINT_SOURCE.plugin = 'compact'
-
-/** In-window tool/call index entry used to materialize result cards. */
-interface CallIndexEntry {
-  name: string
-  argsRaw: string
-  turn: number
-  step: number
-  /** Unix epoch ms of the tool/call event. */
-  time: number
-  /** Wire view riding the tool/call (envelope-level; never inside the event). */
-  callView: ToolCallView | null
-}
-
-/** One event -> UI node (pure function; the ten-variant ConversationNode union). */
-function materializeNode(
-  event: SessionEvent,
-  callIndex: ReadonlyMap<string, CallIndexEntry>,
-  resultView: ToolResultView | null,
-  steering: boolean,
-  stepTimings: ReadonlyMap<string, AssistantStepMetadata>,
-): ConversationNode {
-  switch (event.type) {
-    case 'user/message': {
-      // Injected context (plugin/goal/skill-invocation source) folds to a
-      // context node, not a user message; only a direct human prompt is a
-      // user node. A compaction checkpoint never reaches here
-      // (isCompactCheckpoint routes it away).
-      if (event.data.source.kind !== 'user') {
-        return {
-          kind: 'context', seq: event.seq, time: event.time,
-          content: event.data.content, source: event.data.source,
-          provenance: contextProvenance(event.data.source),
-          form: contextForm(event.data.source),
-        }
-      }
-      if (steering) {
-        return {
-          kind: 'steering', messageId: event.data.id,
-          seq: event.seq, time: event.time,
-          content: event.data.content, source: event.data.source,
-        }
-      }
-      return {
-        kind: 'user', seq: event.seq, time: event.time,
-        content: event.data.content, source: event.data.source,
-      }
-    }
-    case 'assistant/message':
-      return {
-        kind: 'assistant', seq: event.seq, time: event.time,
-        turn: event.data.turn, step: event.data.step,
-        blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage,
-        timing: settledAssistantTiming(stepTimings, event.data.turn, event.data.step, event.time),
-      }
-    case 'tool/result': {
-      const result = event.data.message.content[0]
-      const callId = String(event.data.message.source.callId)
-      const call = callIndex.get(callId)
-      return {
-        kind: 'tool-result', seq: event.seq, time: event.time,
-        callId,
-        call: call ? { name: call.name, argsRaw: call.argsRaw } : null,
-        callTime: call?.time ?? null,
-        content: result.content, isError: result.isError === true,
-        ...(event.data.error !== undefined ? { error: event.data.error } : {}),
-        meta: event.data.meta,
-        callView: call?.callView ?? null,
-        resultView,
-        subCalls: [],
-      }
-    }
-    /* v8 ignore next 2 -- defensive arm: only the four surface-eligible types
-    can be append-origin, and each has a case above; reachable only if core
-    adds an eligible type. */
-    default:
-      return {
-        kind: 'unknown', seq: event.seq, time: event.time,
-        type: event.type, data: (event as { data?: unknown }).data,
-      }
-  }
-}
-
-/**
- * Whether an event is a landed compaction checkpoint — all three conditions,
- * matching the terminal's `isCompactCheckpoint`: a `user/message`, carrying the
- * compaction seam's checkpoint plugin source, that REPLACED a surface range. A
- * plugin-sourced `user/message` that appends is injected context (a
- * session-reference card), not a compaction; a replacement `tool/result` is an
- * in-place prune and a replacement `assistant/message` a generic rewrite, and
- * both mark no boundary in the conversation.
- * @param event - the raw window event.
- * @returns true when the event compacted a surface range.
- */
-function isCompactCheckpoint(event: SessionEvent): boolean {
-  if (event.type !== 'user/message') return false
-  const source = event.data.source
-  return source.kind === 'plugin' && source.plugin === COMPACT_PLUGIN
-    && isReplacementSurfaceEvent(event)
-}
-
-/** Whether an event contributes a node to the human transcript. */
-function isTranscriptEvent(event: SessionEvent): boolean {
-  return isAppendSurfaceEvent(event) || isCompactCheckpoint(event)
-}
-
-/**
- * Concatenated text of a `compact/summary` payload, or null when it carries no
- * usable text. The payload is a `ContentBlock[]` whose union is
- * merge-extensible, so a non-text block is skipped rather than discarding the
- * text beside it; a payload with no text block at all falls to null through the
- * empty check.
- */
-function compactSummaryText(event: SessionEvent): string | null {
-  const summary = (event.data as unknown as { summary?: unknown }).summary
-  if (!Array.isArray(summary)) return null
-  let text = ''
-  for (const block of summary as readonly unknown[]) {
-    const candidate = block as { type?: unknown; text?: unknown }
-    if (candidate.type !== 'text' || typeof candidate.text !== 'string') continue
-    text += candidate.text
-  }
-  return text.trim() === '' ? null : text
-}
-
-interface CompactSummaryDetails {
-  readonly summary: string | null
-  readonly shadowedItemCount: number | null
-  readonly shadowedTokenCount: number | null
-}
-
-/** Recover human-facing summary material from one structurally narrowed wire event. */
-function compactSummaryDetails(event: SessionEvent): CompactSummaryDetails {
-  const data = event.data as unknown as { shadowedSeqs?: unknown; shadowedTokenCount?: unknown }
-  const shadowedSeqs = data.shadowedSeqs
-  const tokenCount = data.shadowedTokenCount
-  return {
-    summary: compactSummaryText(event),
-    shadowedItemCount: Array.isArray(shadowedSeqs)
-      && shadowedSeqs.every((seq: unknown) => Number.isSafeInteger(seq) && (seq as number) >= 0)
-      ? shadowedSeqs.length
-      : null,
-    shadowedTokenCount: Number.isSafeInteger(tokenCount) && (tokenCount as number) >= 0
-      ? tokenCount as number
-      : null,
-  }
-}
-
-/**
- * One landed checkpoint -> the human-facing compaction marker. The summary text
- * comes from the checkpoint's cited `compact/summary` event (`sourceEventSeqs` names the
- * `compact/summary` event), never from the framed checkpoint payload, which is
- * an instruction envelope written for the model. A window cut that left the
- * summary event outside soft-falls to `summary: null` (a non-expandable marker),
- * the same posture as a call-less tool result.
- */
-function materializeCompaction(
-  checkpoint: SessionEvent,
-  eventIndex: ReadonlyMap<number, SessionEvent>,
-): CompactionSummaryNode {
-  const sources = (checkpoint as SessionEvent & { sourceEventSeqs?: number[] }).sourceEventSeqs
-  let summary: string | null = null
-  let summaryEventSeq: number | null = null
-  let shadowedItemCount: number | null = null
-  let shadowedTokenCount: number | null = null
-  for (const seq of sources ?? []) {
-    const candidate = eventIndex.get(seq)
-    if (candidate === undefined || (candidate.type as string) !== 'compact/summary') continue
-    const details = compactSummaryDetails(candidate)
-    summary = details.summary
-    summaryEventSeq = candidate.seq
-    shadowedItemCount = details.shadowedItemCount
-    shadowedTokenCount = details.shadowedTokenCount
-    break
-  }
-  return {
-    kind: 'compaction',
-    seq: checkpoint.seq,
-    time: checkpoint.time,
-    summary,
-    summaryEventSeq,
-    shadowedItemCount,
-    shadowedTokenCount,
-  }
-}
-
-/** Log-ordered human transcript over a paged raw event window (never consults surface order). */
-export class TranscriptAdapter {
-  /** Window events by seq, used to find the summary event cited by a checkpoint. */
-  private eventIndex = new Map<number, SessionEvent>()
-  /** Transcript nodes in log order; copy-on-write so a published array never mutates. */
-  private projected: ConversationNode[] = []
-  private callIdx = new Map<string, CallIndexEntry>()
-  /** Per-step timing boundaries (step/start + first token delta), consumed when the step's assistant/message materializes. */
-  private stepTimings = new Map<string, AssistantStepMetadata>()
-  /** Wire result views keyed by the tool/result event's seq (views ride the envelope, not the event). */
-  private resultViews = new Map<number, ToolResultView>()
-  /** Durable inbox replay used to distinguish next-step human input from queued prompts. */
-  private readonly steeringHistory = new SteeringHistory()
-  /**
-   * Command lifecycle nodes by commandId (insertion = run order). The
-   * `command/run`/`command/done` pair is log-only, so it is not a surface
-   * event and never joins the transcript projection; this index folds the pair
-   * (done settles its run's node in place) and nodes() merges the products in
-   * by seq. Window cuts soft-fall like tool pairs: a done with no in-window
-   * run still builds a node.
-   */
-  private commandIdx = new Map<string, CommandNode>()
-  /** Projection revision, bumped only when a transcript node or a command node actually
-   *  changed, keying the nodes() result cache: an unchanged projection returns the previous
-   *  ARRAY reference, not just cached elements — the snapshot's reference-stability contract
-   *  starts here, and a chunk storm bumps nothing at all. */
-  private rev = 0
-  private nodesResult: { rev: number; value: readonly ConversationNode[] } | null = null
-
-  /**
-   * Window rebuild (after open/resync/page prepend): re-index the raw window
-   * and re-project the transcript.
-   * @param events - the new window contents (seq-ascending).
-   * @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
-   */
-  reset(events: readonly SessionEvent[], views?: readonly (ToolEventView | undefined)[]): void {
-    this.rev++
-    this.eventIndex = new Map()
-    this.callIdx = new Map()
-    this.resultViews.clear()
-    this.commandIdx = new Map()
-    this.steeringHistory.reset()
-    const steeringSeqs = new Set<number>()
-    this.stepTimings = new Map()
-    for (let i = 0; i < events.length; i++) {
-      const event = events[i]
-      /* v8 ignore next -- dense-array guard: i stays within events.length, so the undefined arm needs a sparse array no caller builds. */
-      if (event === undefined) continue
-      this.eventIndex.set(event.seq, event)
-      this.indexCall(event, views?.[i])
-      this.indexCommand(event)
-      if (this.steeringHistory.apply(event)) steeringSeqs.add(event.seq)
-      indexAssistantStepTiming(this.stepTimings, event)
-    }
-    // Indexes first, then project: a tool/result materializes against the
-    // complete call index, and a checkpoint against the complete event index.
-    const projected: ConversationNode[] = []
-    for (const event of events) {
-      if (isTranscriptEvent(event)) projected.push(this.materialize(event, steeringSeqs.has(event.seq)))
-    }
-    this.projected = projected
-  }
-
-  /**
-   * Tail append (live session/event): index the event and, when it belongs to
-   * the transcript, extend the projection by one copy-on-write node so a
-   * published array never mutates. An event that changes no node (a chunk
-   * storm) bumps no revision, so nodes() keeps returning the same array
-   * reference.
-   * @param event - the live event (seq = window tail + 1).
-   * @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering.
-   */
-  append(event: SessionEvent, view?: ToolEventView): void {
-    this.eventIndex.set(event.seq, event)
-    this.indexCall(event, view)
-    const steering = this.steeringHistory.apply(event)
-    indexAssistantStepTiming(this.stepTimings, event)
-    if (this.indexCommand(event)) this.rev++
-    if (!isTranscriptEvent(event)) return
-    this.projected = [...this.projected, this.materialize(event, steering)]
-    this.rev++
-  }
-
-  /**
-   * The current transcript node array. Same revision -> same array reference
-   * (memo boundary); node objects are materialized once, so an unchanged node
-   * keeps its identity across appends.
-   * @returns transcript nodes in log order, command nodes merged in by seq.
-   */
-  nodes(): readonly ConversationNode[] {
-    if (this.nodesResult !== null && this.nodesResult.rev === this.rev) return this.nodesResult.value
-    // Command nodes fold outside the transcript (log-only events); merge by
-    // seq. Both inputs are seq-ascending (log order and run-index insertion
-    // order are the same order), so one linear merge keeps flow order.
-    let nodes = this.projected
-    if (this.commandIdx.size > 0) {
-      nodes = []
-      const commands = [...this.commandIdx.values()]
-      let next = 0
-      for (const node of this.projected) {
-        for (let cmd = commands[next]; cmd !== undefined && cmd.seq < node.seq; cmd = commands[++next]) {
-          nodes.push(cmd)
-        }
-        nodes.push(node)
-      }
-      for (let cmd = commands[next]; cmd !== undefined; cmd = commands[++next]) nodes.push(cmd)
-    }
-    this.nodesResult = { rev: this.rev, value: nodes }
-    return nodes
-  }
-
-  /** Materialize one transcript event against the complete current indexes. */
-  private materialize(event: SessionEvent, steering: boolean): ConversationNode {
-    return isCompactCheckpoint(event)
-      ? materializeCompaction(event, this.eventIndex)
-      : materializeNode(
-        event,
-        this.callIdx,
-        this.resultViews.get(event.seq) ?? null,
-        steering,
-        this.stepTimings,
-      )
-  }
-
-  /**
-   * Fold one command lifecycle event into its node (run mints, done settles in
-   * place; done-only soft-falls).
-   * @returns whether the command index changed, so callers can bump the revision.
-   */
-  private indexCommand(event: SessionEvent): boolean {
-    // Log-only plugin events: the host-side dsh-commands declaration cannot
-    // enter the client program, so this wire consumer narrows structurally
-    // (the same posture as tool/code-dispatch in session.ts).
-    if ((event.type as string) === 'command/run') {
-      const data = event.data as unknown as { commandId: CommandId; name: string; args?: string }
-      this.commandIdx.set(data.commandId, {
-        kind: 'command', seq: event.seq, time: event.time,
-        commandId: data.commandId, name: data.name, args: data.args ?? null, outcome: null,
-      })
-      return true
-    }
-    if ((event.type as string) !== 'command/done') return false
-    const data = event.data as unknown as {
-      commandId: CommandId
-      kind: 'success' | 'error'
-      text?: string
-      sourceEventSeq?: number
-    }
-    const run = this.commandIdx.get(data.commandId)
-    const sourceEventSeq = data.kind === 'success'
-      && Number.isSafeInteger(data.sourceEventSeq) && (data.sourceEventSeq as number) >= 0
-      ? data.sourceEventSeq as number
-      : undefined
-    const outcome = {
-      kind: data.kind,
-      ...data.text === undefined ? {} : { text: data.text },
-      ...sourceEventSeq === undefined ? {} : { sourceEventSeq },
-    }
-    if (run === undefined) {
-      // Cross-window cut: the run page fell out of the window — build the
-      // node from the done alone (same soft-fall as a call-less tool result).
-      this.commandIdx.set(data.commandId, {
-        kind: 'command', seq: event.seq, time: event.time,
-        commandId: data.commandId, name: null, args: null, outcome,
-      })
-      return true
-    }
-    // Settle in place: a fresh node object (published references stay immutable).
-    this.commandIdx.set(data.commandId, { ...run, outcome })
-    return true
-  }
-
-  private indexCall(event: SessionEvent, view?: ToolEventView): void {
-    if (event.type === 'tool/result') {
-      if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
-      return
-    }
-    if (event.type !== 'tool/call') return
-    this.callIdx.set(String(event.data.callId), {
-      name: event.data.name, argsRaw: event.data.arguments, turn: event.data.turn, step: event.data.step,
-      time: event.time,
-      callView: view?.for === 'call' ? view.view : null,
-    })
-    // No backfill into already-materialized tool-result nodes for this callId
-    // (window order puts the call before its result; cannot happen on the normal path).
-  }
-}
diff --git a/packages/client/runtime/tests/transcript-adapter.spec.ts b/packages/client/runtime/tests/transcript-adapter.spec.ts
deleted file mode 100644
index 893635dcc7..0000000000
--- a/packages/client/runtime/tests/transcript-adapter.spec.ts
+++ /dev/null
@@ -1,567 +0,0 @@
-/**
- * TranscriptAdapter over the raw append-only window: log-ordered projection of
- * append-origin events, one marker per landed compaction, replacement copies
- * hidden, command-lifecycle folding, node/array identity, call pairing, and
- * host-provided wire views.
- */
-
-import { createUserMessage, CallId, createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
-import { describe, expect, it } from 'vitest'
-import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import { TranscriptAdapter } from '../src/client/sessions/transcript-adapter.ts'
-import { ev, plainTurn } from './event-script.ts'
-
-const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
-  ({ seq, time: 1_700_000_000_000 + seq, ...e }) as unknown as SessionEvent
-
-/** A `compact/summary` event (log-only, no surfaceOp). */
-function compactSummary(seq: number, summary: unknown = [{ type: 'text', text: '# 摘要\n\n保留事实' }]): SessionEvent {
-  return at(seq, {
-    type: 'compact/summary',
-    data: {
-      summary,
-      shadowedRange: { start: 1, end: 3 },
-      shadowedSeqs: [1, 3],
-      shadowedTokenCount: 100,
-      provider: 'fake',
-      model: 'compact-1',
-    },
-  })
-}
-
-/** The replacement user message a compaction backend lands (the checkpoint). */
-function checkpoint(
-  seq: number,
-  summarySeq: number,
-  { start = 1, end = 3, sourceEventSeqs = [summarySeq, start, end] }: {
-    start?: number
-    end?: number
-    sourceEventSeqs?: number[]
-  } = {},
-): SessionEvent {
-  return at(seq, {
-    type: 'user/message',
-    surfaceOp: { op: 'replace', start, end },
-    sourceEventSeqs,
-    data: createUserMessage({
-      content: [{ type: 'text', text: '<context_checkpoint>model only</context_checkpoint>' }],
-      source: { kind: 'plugin', plugin: 'compact' },
-    }),
-  })
-}
-
-describe('TranscriptAdapter', () => {
-  it('projects a window starting past seq 0 at its own log positions', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(100, 5, '偏移问', '偏移答'))
-    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 101], ['assistant', 103]])
-  })
-
-  it('appends incrementally keeping old node references (materialize-once identity)', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b'))
-    const first = adapter.nodes()
-    adapter.append(ev.user(6, '追加'))
-    const second = adapter.nodes()
-    expect(second).toHaveLength(3)
-    expect(second[0]).toBe(first[0])
-    expect(second[1]).toBe(first[1])
-    expect(second).not.toBe(first) // a real change swaps the array
-  })
-
-  it('keeps the array reference across a chunk storm and swaps it when a node lands', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b'))
-    const settled = adapter.nodes()
-    adapter.append(ev.chunkStart(6, 1))
-    expect(adapter.nodes()).toBe(settled)
-    adapter.append(ev.chunkText(7, 1, '流式'))
-    expect(adapter.nodes()).toBe(settled)
-    adapter.append(ev.assistant(8, 1, '流式完成'))
-    const finalized = adapter.nodes()
-    expect(finalized).not.toBe(settled)
-    expect(finalized.at(-1)).toMatchObject({ kind: 'assistant', seq: 8 })
-  })
-
-  it('materializes every append-origin variant with field mapping', () => {
-    const adapter = new TranscriptAdapter()
-    const steering = createUserMessage({
-      content: [{ type: 'text', text: '插话' }],
-      source: { kind: 'user' },
-    })
-    adapter.reset([
-      ev.user(0, '用户'),
-      ev.assistant(1, 0, '助手'),
-      at(2, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [steering],
-      } }),
-      at(3, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(4, { type: 'user/message', surfaceOp: 'append', data: steering }),
-      at(5, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '上下文' }], source: { kind: 'plugin', plugin: 'p' },
-      }) }),
-      ev.toolCall(6, 0, 'c1', 'echo', '{"x":1}'),
-      ev.toolResult(7, 0, 'c1', '结果'),
-    ])
-    const nodes = adapter.nodes()
-    expect(nodes.map(n => n.kind)).toEqual(['user', 'assistant', 'steering', 'context', 'tool-result'])
-    expect(nodes.find(n => n.kind === 'steering')).toMatchObject({ messageId: steering.id })
-    expect(nodes.find(n => n.kind === 'tool-result')).toMatchObject({
-      callId: 'c1', call: { name: 'echo', argsRaw: '{"x":1}' }, isError: false,
-    })
-  })
-
-  it('identifies steering on the live append path', () => {
-    const adapter = new TranscriptAdapter()
-    const steering = createUserMessage({
-      content: [{ type: 'text', text: 'live steer' }],
-      source: { kind: 'user' },
-    })
-    adapter.reset([])
-    adapter.append(at(0, { type: 'agent/inbox/spliced', data: {
-      target: 'next-step', start: 0, inserted: [steering],
-    } }))
-    adapter.append(at(1, { type: 'agent/inbox/spliced', data: {
-      target: 'next-step', start: 0, removedCount: 1, inserted: [],
-    } }))
-    adapter.append(at(2, { type: 'user/message', surfaceOp: 'append', data: steering }))
-    expect(adapter.nodes()).toMatchObject([{ kind: 'steering', messageId: steering.id }])
-  })
-
-  it('does not mark queued, canceled, or non-user next-step messages as steering', () => {
-    const adapter = new TranscriptAdapter()
-    const queued = createUserMessage({ content: [{ type: 'text', text: 'queued' }], source: { kind: 'user' } })
-    const canceled = createUserMessage({ content: [{ type: 'text', text: 'canceled' }], source: { kind: 'user' } })
-    const context = createUserMessage({
-      content: [{ type: 'text', text: 'context' }],
-      source: { kind: 'plugin', plugin: 'test' },
-    })
-    adapter.reset([
-      at(0, { type: 'agent/inbox/spliced', data: {
-        target: 'next-turn', start: 0, inserted: [queued],
-      } }),
-      at(1, { type: 'agent/inbox/spliced', data: {
-        target: 'next-turn', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(2, { type: 'user/message', surfaceOp: 'append', data: queued }),
-      at(3, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [canceled],
-      } }),
-      at(4, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [], outcome: 'canceled',
-      } }),
-      at(5, { type: 'user/message', surfaceOp: 'append', data: canceled }),
-      at(6, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, inserted: [context],
-      } }),
-      at(7, { type: 'agent/inbox/spliced', data: {
-        target: 'next-step', start: 0, removedCount: 1, inserted: [],
-      } }),
-      at(8, { type: 'user/message', surfaceOp: 'append', data: context }),
-    ])
-    expect(adapter.nodes().map(node => node.kind)).toEqual(['user', 'user', 'context'])
-  })
-
-  it('materializes a skill-invocation injection as a named instructions context', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '/hidden-demo check the fixture' }],
-        source: { kind: 'user' },
-      }) }),
-      at(1, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-        content: [{ type: 'text', text: '<skill_content name="hidden-demo">body</skill_content>' }],
-        source: { kind: 'skill-invocation', name: 'hidden-demo', form: 'instructions' } as never,
-      }) }),
-    ])
-    const nodes = adapter.nodes()
-    // The gesture stays a user bubble; the injected body folds to a context
-    // row named after the skill, presented as instructions.
-    expect(nodes.map(node => node.kind)).toEqual(['user', 'context'])
-    expect(nodes[1]).toMatchObject({
-      provenance: { role: 'inject', label: 'hidden-demo' },
-      form: 'instructions',
-    })
-  })
-
-  it('skips events core does not call surface-eligible, marker or not', () => {
-    // The transcript is the append-origin surface, so log-only events (a chunk,
-    // a turn boundary, a `compact/*` record) and a future type core
-    // has not admitted contribute no node.
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      ev.turnStart(0, 1),
-      at(1, { type: 'notice/message', surfaceOp: 'append', data: { note: 1 } }),
-      compactSummary(2),
-      ev.user(3, '唯一的一条'),
-      ev.turnEnd(4, 1),
-    ])
-    expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 3]])
-  })
-
-  describe('compaction markers', () => {
-    it('keeps the original messages and full tool output, hiding replacement copies', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '原始问题'),
-        ev.assistant(1, 0, '原始回答'),
-        ev.toolCall(4, 0, 'c1', 'echo', '{}'),
-        ev.toolResult(5, 0, 'c1', '完整工具输出'),
-        // A pruned tool/result copy: rewrites one node for the model, marks nothing.
-        at(6, { type: 'tool/result', surfaceOp: { op: 'replace', start: 5, end: 5 }, sourceEventSeqs: [5], data: {
-          turn: 0, step: 0,
-          message: createToolResultMessage({ callId: CallId('c1'), content: [{ type: 'text', text: '已裁剪' }], isError: false }),
-        } }),
-        compactSummary(7),
-        checkpoint(8, 7, { start: 1, end: 5, sourceEventSeqs: [7, 1, 5] }),
-        // A regenerated assistant/message: also a silent model-only rewrite.
-        at(9, { type: 'assistant/message', surfaceOp: { op: 'replace', start: 8, end: 8 }, sourceEventSeqs: [8], data: {
-          turn: 0, step: 0,
-          message: createMessage({
-            role: 'assistant',
-            content: [{ type: 'text', text: '通用 replacement 副本' }],
-            source: { kind: 'model', ...{ provider: 'x', model: 'copy' } },
-          }),
-        } }),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([
-        ['user', 0], ['assistant', 1], ['tool-result', 5], ['compaction', 8],
-      ])
-      expect(nodes[2]).toMatchObject({ kind: 'tool-result', content: [{ type: 'text', text: '完整工具输出' }] })
-      expect(nodes[3]).toMatchObject({ kind: 'compaction', summary: '# 摘要\n\n保留事实' })
-    })
-
-    it('adds one marker per landed compaction, in log order', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, 'a'),
-        compactSummary(1, [{ type: 'text', text: 'first' }]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-        ev.user(3, 'b'),
-        compactSummary(4, [{ type: 'text', text: 'second' }]),
-        checkpoint(5, 4, { start: 2, end: 3, sourceEventSeqs: [4, 2, 3] }),
-      ])
-      expect(adapter.nodes().filter(n => n.kind === 'compaction')).toEqual([
-        {
-          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: 'first',
-          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-        {
-          kind: 'compaction', seq: 5, time: 1_700_000_000_005, summary: 'second',
-          summaryEventSeq: 4, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-      ])
-    })
-
-    it('renders the marker when the shadowed range is outside the window and logs nothing', () => {
-      // Pagination spends no quota on replacement copies, so a page can carry
-      // a checkpoint whose surfaceOp.start lies below the window head. A
-      // surface fold would throw on the missing range and degrade with a
-      // console error; a log-ordered
-      // projection has no range to resolve.
-      const adapter = new TranscriptAdapter()
-      const noise = { error: console.error, warn: console.warn }
-      const logged: unknown[] = []
-      console.error = (...args: unknown[]) => logged.push(args)
-      console.warn = (...args: unknown[]) => logged.push(args)
-      try {
-        adapter.reset([
-          compactSummary(80, [{ type: 'text', text: '窗外范围' }]),
-          checkpoint(81, 80, { start: 3, end: 40, sourceEventSeqs: [80, 3, 40] }),
-          ev.user(82, '压缩后的新问题'),
-        ])
-        expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['compaction', 81], ['user', 82]])
-        expect(adapter.nodes()[0]).toMatchObject({ summary: '窗外范围' })
-      } finally {
-        console.error = noise.error
-        console.warn = noise.warn
-      }
-      expect(logged).toEqual([])
-    })
-
-    it('treats an APPENDING plugin-sourced user/message as injected context, not a compaction', () => {
-      // A session-reference card carries the same plugin source shape; only the
-      // replacement marker makes an event a checkpoint.
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        at(0, { type: 'user/message', surfaceOp: 'append', data: createUserMessage({
-          content: [{ type: 'text', text: '注入的上下文' }],
-          source: { kind: 'plugin', plugin: 'compact', form: 'instructions' },
-        }) }),
-      ])
-      expect(adapter.nodes()).toMatchObject([{
-        kind: 'context',
-        seq: 0,
-        provenance: { role: 'inject', label: 'compact' },
-        form: 'instructions',
-      }])
-    })
-
-    it('ignores a foreign plugin s replacement user/message', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '保留'),
-        at(1, { type: 'user/message', surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0], data: createUserMessage({
-          content: [{ type: 'text', text: '别的插件重写' }],
-          source: { kind: 'plugin', plugin: 'not-compact' },
-        }) }),
-      ])
-      expect(adapter.nodes().map(n => [n.kind, n.seq])).toEqual([['user', 0]])
-    })
-
-    it.each([
-      ['absent summary event', undefined],
-      ['text-less summary blocks', compactSummary(1, [{ type: 'image', data: 'nope' }])],
-      ['a whitespace-only summary', compactSummary(1, [{ type: 'text', text: '   ' }])],
-      ['an empty summary array', compactSummary(1, [])],
-      ['a non-array summary', compactSummary(1, 'plain string')],
-    ])('degrades %s to a non-expandable marker', (_label, summary) => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ...(summary === undefined ? [] : [summary]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-      ])
-      expect(adapter.nodes()).toMatchObject([
-        { kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null },
-      ])
-    })
-
-    it('keeps the text of a mixed-block summary, skipping the blocks it cannot render', () => {
-      // ContentBlock is merge-extensible and the payload type is ContentBlock[],
-      // so a non-text block must not discard recoverable text beside it.
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        compactSummary(1, [{ type: 'text', text: '可用摘要' }, { type: 'image', data: 'nope' }]),
-        checkpoint(2, 1, { start: 0, end: 0, sourceEventSeqs: [1, 0] }),
-      ])
-      expect(adapter.nodes()).toEqual([
-        {
-          kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: '可用摘要',
-          summaryEventSeq: 1, shadowedItemCount: 2, shadowedTokenCount: 100,
-        },
-      ])
-    })
-
-    it('leaves the summary null when the checkpoint cites no source events', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([at(2, {
-        type: 'user/message',
-        surfaceOp: { op: 'replace', start: 0, end: 0 },
-        data: createUserMessage({
-          content: [{ type: 'text', text: '<context_checkpoint>x</context_checkpoint>' }],
-          source: { kind: 'plugin', plugin: 'compact' },
-        }),
-      })])
-      expect(adapter.nodes()).toEqual([{
-        kind: 'compaction', seq: 2, time: 1_700_000_000_002, summary: null,
-        summaryEventSeq: null, shadowedItemCount: null, shadowedTokenCount: null,
-      }])
-    })
-
-    it('skips a cited non-summary seq before reaching the summary event', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '被压缩的问题'),
-        at(1, { type: 'compact/start', data: { turn: 0 } }),
-        compactSummary(2, [{ type: 'text', text: '第三个来源才是摘要' }]),
-        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [1, 2, 0] }),
-      ])
-      expect(adapter.nodes().at(-1)).toMatchObject({ kind: 'compaction', summary: '第三个来源才是摘要' })
-    })
-
-    it('resolves the summary once an older page supplies the cited summary event', () => {
-      const adapter = new TranscriptAdapter()
-      const landed = checkpoint(8, 7, { start: 0, end: 0, sourceEventSeqs: [7, 0] })
-      adapter.reset([landed])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: null })
-      adapter.reset([compactSummary(7, [{ type: 'text', text: '分页补齐的摘要' }]), landed])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'compaction', summary: '分页补齐的摘要' })
-    })
-
-    it('creates the marker on the live append path', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset(plainTurn(0, 0, 'a', 'b'))
-      adapter.append(compactSummary(6, [{ type: 'text', text: '直播摘要' }]))
-      adapter.append(checkpoint(7, 6, { start: 1, end: 3, sourceEventSeqs: [6, 1, 3] }))
-      const nodes = adapter.nodes()
-      // The compacted history is still there; the marker is one more row after it.
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 1], ['assistant', 3], ['compaction', 7]])
-      expect(nodes.at(-1)).toMatchObject({ kind: 'compaction', seq: 7, summary: '直播摘要' })
-    })
-  })
-
-  it('returns call:null for a tool-result whose call fell outside the window', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([ev.toolResult(50, 3, 'outside-call', '孤儿结果')])
-    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', callId: 'outside-call', call: null })
-  })
-
-  it('materializes a tool-result error field when present', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset([
-      at(0, { type: 'tool/result', surfaceOp: 'append', data: {
-        turn: 0, step: 0,
-        message: createToolResultMessage({ callId: CallId('c1'), content: [], isError: true }),
-        error: { name: 'Boom', code: 'boom' },
-      } }),
-    ])
-    expect(adapter.nodes()[0]).toMatchObject({ kind: 'tool-result', isError: true, error: { code: 'boom' } })
-  })
-
-  it('attaches wire views to the materialized result node', () => {
-    const adapter = new TranscriptAdapter()
-    const callView = { for: 'call' as const, view: { card: 'terminal' as const, command: 'ls' } }
-    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '完成' } }
-    adapter.reset([
-      ev.toolCall(0, 1, 'c1', 'bash', '{"cmd":"ls"}'),
-      ev.toolResult(1, 1, 'c1', 'listing'),
-    ], [callView, resultView] as never)
-    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
-      callView: { card: 'terminal' }, resultView: { card: 'generic', title: '完成' },
-    })
-  })
-
-  it('attaches views on the live append path and defaults to null without views', () => {
-    const adapter = new TranscriptAdapter()
-    adapter.reset(plainTurn(0, 0, 'a', 'b')) // no views argument
-    adapter.append(ev.toolCall(6, 1, 'c2', 'echo', '{}'), { for: 'call', view: { card: 'generic', title: '回声' } } as never)
-    adapter.append(ev.toolResult(7, 1, 'c2', 'ok')) // no view on the result
-    expect(adapter.nodes().find(n => n.kind === 'tool-result')).toMatchObject({
-      callView: { title: '回声' }, resultView: null,
-    })
-  })
-
-  it('leaves callView null when the paired call fell outside the window (cross-page break)', () => {
-    const adapter = new TranscriptAdapter()
-    const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } }
-    adapter.reset([ev.toolResult(50, 3, 'outside', '窗外配对')], [resultView] as never)
-    expect(adapter.nodes()[0]).toMatchObject({
-      kind: 'tool-result', call: null, callView: null, resultView: { title: '孤儿' },
-    })
-  })
-
-  describe('command lifecycle nodes', () => {
-    it('folds a run/done pair into one settled node merged into flow order by seq', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '先说话'),
-        ev.commandRun(1, 'cmd-1', 'plan'),
-        ev.commandDone(2, 'cmd-1', 'success', '已进入 plan mode'),
-        ev.assistant(3, 0, '然后回答'),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['assistant', 3]])
-      expect(nodes[1]).toMatchObject({
-        kind: 'command', commandId: 'cmd-1', name: 'plan', args: '',
-        outcome: { kind: 'success', text: '已进入 plan mode' },
-      })
-    })
-
-    it('renders a run with no done as still executing (outcome null)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandRun(0, 'cmd-2', 'goal', ' ship it')])
-      expect(adapter.nodes()[0]).toMatchObject({ kind: 'command', name: 'goal', args: ' ship it', outcome: null })
-    })
-
-    it('represents command input omitted by the host as null', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandRunWithoutInput(0, 'cmd-private', 'feedback')])
-      expect(adapter.nodes()[0]).toMatchObject({
-        kind: 'command', name: 'feedback', args: null, outcome: null,
-      })
-    })
-
-    it('soft-falls a done-only window into a node built from the done (cross-window cut)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.commandDone(80, 'cmd-3', 'error', '失败了')])
-      expect(adapter.nodes()[0]).toMatchObject({
-        kind: 'command', seq: 80, commandId: 'cmd-3', name: null, args: null,
-        outcome: { kind: 'error', text: '失败了' },
-      })
-    })
-
-    it('settles a live-appended done in place, keeping the node at the run seq', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset(plainTurn(0, 0, 'q', 'a'))
-      adapter.append(ev.commandRun(6, 'cmd-4', 'clear'))
-      const running = adapter.nodes().find(n => n.kind === 'command')
-      expect(running).toMatchObject({ outcome: null })
-      adapter.append(ev.commandDone(7, 'cmd-4'))
-      const settled = adapter.nodes().find(n => n.kind === 'command')
-      expect(settled).toMatchObject({ seq: 6, outcome: { kind: 'success' } })
-      // Settlement replaced the node object rather than mutating the published one.
-      expect(settled).not.toBe(running)
-    })
-
-    it('tails command nodes whose seq is past every transcript node', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.user(0, '问'), ev.commandRun(1, 'cmd-tail', 'plan')])
-      expect(adapter.nodes().map(n => n.kind)).toEqual(['user', 'command'])
-    })
-
-    it('preserves the domain-event link for the UI to fold a /compact row into its marker', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.user(0, '压缩前的问题'),
-        ev.commandRun(1, 'cmd-compact', 'compact'),
-        compactSummary(2, [{ type: 'text', text: '手动压缩摘要' }]),
-        checkpoint(3, 2, { start: 0, end: 0, sourceEventSeqs: [2, 0] }),
-        ev.commandDone(4, 'cmd-compact', 'success', '已压缩', 2),
-      ])
-      const nodes = adapter.nodes()
-      expect(nodes.map(n => [n.kind, n.seq])).toEqual([['user', 0], ['command', 1], ['compaction', 3]])
-      expect(nodes[1]).toMatchObject({
-        name: 'compact',
-        outcome: { kind: 'success', text: '已压缩', sourceEventSeq: 2 },
-      })
-      expect(nodes[2]).toMatchObject({ kind: 'compaction', summaryEventSeq: 2 })
-    })
-  })
-
-  describe('assistant timing', () => {
-    const base = 1_700_000_000_000
-
-    it('derives step timing across a window rebuild (start + first token + completion)', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([
-        ev.turnStart(0, 0),
-        ev.user(1, '问'),
-        ev.stepStart(2, 0),
-        ev.chunkStart(3, 0),
-        ev.chunkText(4, 0, '答'),
-        ev.chunkText(5, 0, '案'),
-        ev.assistant(6, 0, '答案'),
-        ev.turnEnd(7, 0),
-      ])
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: base + 2, firstTokenTime: base + 4, completedTime: base + 6 },
-      })
-    })
-
-    it('derives the same timing on the live append path, first token winning once', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.user(0, '问')])
-      adapter.append(ev.stepStart(1, 0))
-      adapter.append(ev.chunkText(2, 0, '首'))
-      adapter.append(ev.chunkText(3, 0, '次'))
-      adapter.append(ev.assistant(4, 0, '首次'))
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: base + 1, firstTokenTime: base + 2, completedTime: base + 4 },
-      })
-    })
-
-    it('soft-falls to null boundaries when the step opening fell outside the window', () => {
-      const adapter = new TranscriptAdapter()
-      adapter.reset([ev.assistant(100, 0, '被切窗的答案')])
-      const assistant = adapter.nodes().find(n => n.kind === 'assistant')
-      expect(assistant).toMatchObject({
-        timing: { stepStartTime: null, firstTokenTime: null, completedTime: base + 100 },
-      })
-    })
-  })
-})

From 5096db61b2fe68d31d79e1eee9fc69841df8b742 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sun, 9 Aug 2026 21:48:41 +0800
Subject: [PATCH 514/516] fix(docs): project existing Chinese translations

---
 scripts/project-doc-site.spec.ts | 17 +++++++++--------
 website/docs.ts                  | 20 ++++++++------------
 2 files changed, 17 insertions(+), 20 deletions(-)

diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts
index d3f00f3408..bca06c89ac 100644
--- a/scripts/project-doc-site.spec.ts
+++ b/scripts/project-doc-site.spec.ts
@@ -251,7 +251,7 @@ describe('rewriteMarkdown', () => {
 })
 
 describe('docsPages locale routes', () => {
-  it('publishes every route in both locales and selects paired sources', () => {
+  it('publishes every route in both locales and uses every available Chinese counterpart', () => {
     const byRoute = new Map(docsPages.map(page => [page.route, page]))
     for (const page of docsPages.filter(page => page.locale === 'root')) {
       const counterpart = byRoute.get(`en/${page.route}`)
@@ -265,6 +265,11 @@ describe('docsPages locale routes', () => {
       } else {
         expect(counterpart?.source).toBe(page.source)
         expect(counterpart?.contentLocale).toBe(page.contentLocale)
+        const chineseSource = page.source.replace(/\.md$/, '.zh.md')
+        expect(
+          existsSync(resolve(repositoryRoot, chineseSource)),
+          `${page.route} has a Chinese counterpart but projects English`,
+        ).toBe(false)
       }
     }
   })
@@ -282,20 +287,16 @@ describe('docsPages locale routes', () => {
     }
   })
 
-  it('projects translated subsystem pages while retaining explicit English fallbacks', () => {
+  it('projects every published subsystem page in Chinese', () => {
     const rootPages = docsPages.filter(page => (
       page.locale === 'root' && page.route.startsWith('reference/subsystems/')
     ))
     const translated = rootPages.filter(page => page.contentLocale === 'zh-CN')
     const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US')
 
-    expect(translated).toHaveLength(39)
+    expect(translated).toHaveLength(42)
     expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true)
-    expect(fallbacks.map(page => page.source).sort()).toEqual([
-      'docs/subsystems/commands.md',
-      'docs/subsystems/goal.md',
-      'docs/subsystems/pty.md',
-    ])
+    expect(fallbacks).toEqual([])
   })
 
   it('publishes the Cordis core API under matching locale structures', () => {
diff --git a/website/docs.ts b/website/docs.ts
index a8d07a59c2..9fcdc7c1a7 100644
--- a/website/docs.ts
+++ b/website/docs.ts
@@ -226,7 +226,7 @@ const develop = pairedPages([
   },
 ])
 
-const cordisTutorial = mirroredPages(([
+const cordisTutorial = pairedPages(([
   ['index.md', 'Cordis 教程', 'Cordis tutorial'],
   ['01-first-plugin.md', '1. 第一个插件', '1. Your first plugin'],
   ['02-lifecycle-and-effects.md', '2. 生命周期与副作用', '2. Lifecycle and effects'],
@@ -235,10 +235,9 @@ const cordisTutorial = mirroredPages(([
   ['05-config.md', '5. 配置', '5. Configuration'],
   ['06-composition-and-hmr.md', '6. 组合与热重载', '6. Composition and HMR'],
   ['07-into-the-harness.md', '7. 进入 Harness', '7. Into the harness'],
-] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
+] as const).map(([file, rootLabel, enLabel], order): PairedPage => ({
   source: `docs/cordis-tutorial/${file}`,
   route: `develop/cordis-tutorial/${file}`,
-  contentLocale: 'en-US',
   label: { root: rootLabel, en: enLabel },
   sidebar: { root: 'zh-develop', en: 'en-develop' },
   section: { root: 'Cordis 教程', en: 'Cordis tutorial' },
@@ -308,12 +307,11 @@ const subsystemsReference = pairedPages(([
 })))
 
 const reference = [
-  ...mirroredPages(([
+  ...pairedPages(([
     ['docs/architecture.md', 'reference/index.md', '架构', 'Architecture', 0],
-  ] as const).map(([source, route, rootLabel, enLabel, order]): MirroredPage => ({
+  ] as const).map(([source, route, rootLabel, enLabel, order]): PairedPage => ({
     source,
     route,
-    contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '概念', en: 'Concepts' },
@@ -369,28 +367,26 @@ const reference = [
     section: { root: 'Cordis API', en: 'Cordis Core API' },
     order: order + 5,
   }))),
-  ...mirroredPages(([
+  ...pairedPages(([
     ['goal.md', '目标', 'Goals', 14],
     ['pty.md', 'PTY 会话', 'PTY sessions', 26],
     ['commands.md', '命令', 'Human commands', 38],
-  ] as const).map(([file, rootLabel, enLabel, order]): MirroredPage => ({
+  ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
     source: `docs/subsystems/${file}`,
     route: `reference/subsystems/${file}`,
-    contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '子系统', en: 'Subsystems' },
     order,
   }))),
-  ...mirroredPages(([
+  ...pairedPages(([
     ['adding-a-package.md', '新增 Package', 'Adding a package'],
     ['adding-a-tool.md', '新增 Tool', 'Adding a tool'],
     ['adding-an-llm-adapter.md', '新增 LLM Adapter', 'Adding an LLM adapter'],
     ['extension-cookbook.md', '扩展模式', 'Extension patterns'],
-  ] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
+  ] as const).map(([file, rootLabel, enLabel], order): PairedPage => ({
     source: `docs/cookbook/${file}`,
     route: `reference/cookbook/${file}`,
-    contentLocale: 'en-US',
     label: { root: rootLabel, en: enLabel },
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '开发手册', en: 'Cookbook' },

From 05a4a41f4fd7445eaeef6cdd966d6550f2322be9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 22:27:32 +0800
Subject: [PATCH 515/516] docs(skills): distill the CoT-leakage purge into
 dsh-trim-cot-leakage

SKILL.md carries the resolvability test, the 8-class taxonomy, the
sanctioned-keeps list, and the owner-first fix workflow; references/
carry 24 few-shot calibration blocks (both citation-boundary directions
plus the four overcorrection traps caught in the purge's review rounds)
and the EN+zh recall batteries with their false-positive families.

dsh-doc-standards' inline leakage probes collapse into a link to the
new skill; dsh-prose-standard gains the sibling pointer; the
committed-artifact-citations note (+zh, pair re-recorded) records the
skill as the operational workflow and exempts its calibration examples
from the battery expectation.
---
 ...-09-committed-artifact-citations.i18n.yaml |   4 +-
 ...2026-08-09-committed-artifact-citations.md |   4 +-
 ...6-08-09-committed-artifact-citations.zh.md |   4 +-
 .agents/skills/dsh-doc-standards/SKILL.md     |  11 +-
 .agents/skills/dsh-prose-standard/SKILL.md    |   2 +-
 .agents/skills/dsh-trim-cot-leakage/SKILL.md  |  45 ++++
 .../references/examples.md                    | 253 ++++++++++++++++++
 .../references/recall-batteries.md            |  42 +++
 8 files changed, 352 insertions(+), 13 deletions(-)
 create mode 100644 .agents/skills/dsh-trim-cot-leakage/SKILL.md
 create mode 100644 .agents/skills/dsh-trim-cot-leakage/references/examples.md
 create mode 100644 .agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md

diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
index 9c9cb9b476..04c3e6a7df 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: 31b2d52b423a080579b3ca95cf077859d0bf4c91
-2026-08-09-committed-artifact-citations.zh.md: b69bb8743d10e2d1e194905d6d0de2d3d3667b1d
+2026-08-09-committed-artifact-citations.md: 181378aab12a4423d9ac5216bac5304f3cfca11c
+2026-08-09-committed-artifact-citations.zh.md: 36f32bb1fd0d6991919959e1ebe6482bf7b19b32
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
index 31b2d52b42..181378aab1 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -18,7 +18,7 @@ Durable prose — comments, JSDoc, docs, notes, test comments and titles — cit
 - Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
 - Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice. Inside a note's change-story sections, a historical stage name ("the first cut shipped X") is current-state-safe; indexical stamps ("this cut") stay banned everywhere.
 
-One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (`scripts/gen-doc-graphs.ts`, `scripts/gen-tool-catalog.ts`, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records.
+One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (`scripts/gen-doc-graphs.ts`, `scripts/gen-tool-catalog.ts`, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records. The [dsh-trim-cot-leakage skill](../../../skills/dsh-trim-cot-leakage/SKILL.md) operationalizes these rules: the audit taxonomy, the committed recall batteries, and few-shot calibration for the keep/delete boundary.
 
 ## Alternatives considered
 
@@ -28,7 +28,7 @@ One repo-wide purge applied these rules across the prose surfaces, including the
 
 ## Verification
 
-The audit's grep batteries (English and Chinese, comments and prose, `--hidden` for `.agents/`) return no design-ordinal citations outside recorded fixtures and archived notes; `verify-type-equiv`, the `gen-*` freshness checks, and `verify-translation-pairing` pin the regenerated and re-recorded surfaces. Coverage gap: no gate rejects a new ordinal citation — review owns the rule.
+The audit's grep batteries (English and Chinese, comments and prose, `--hidden` for `.agents/`) return no design-ordinal citations outside recorded fixtures, archived notes, and the trim skill's own calibration examples; `verify-type-equiv`, the `gen-*` freshness checks, and `verify-translation-pairing` pin the regenerated and re-recorded surfaces. Coverage gap: no gate rejects a new ordinal citation — review owns the rule.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
index b69bb8743d..36f32bb1fd 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 - 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
 - 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）属于安全的现状表述；指示性切次戳（"this cut"）在任何地方都仍被禁止。
 
-一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。
+一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。[dsh-trim-cot-leakage 技能](../../../skills/dsh-trim-cot-leakage/SKILL.md)把这些规则落地为可执行工作流：审计分类法、已提交的成批召回检索，以及校准保留/删除边界的少样本示例。
 
 ## 曾考虑的替代方案
 
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 验证
 
-审计的成批 grep 检索（英文与中文、注释与行文、对 `.agents/` 加 `--hidden`）在已录制 fixture 与已归档 Agent Note 之外没有命中任何设计序号引用；`verify-type-equiv`、各 `gen-*` 新鲜度检查与 `verify-translation-pairing` 把重新生成与重新记录的表面固定下来。覆盖缺口：没有门禁会拒绝新的序号引用，这条规则由评审把关。
+审计的成批 grep 检索（英文与中文、注释与行文、对 `.agents/` 加 `--hidden`）在已录制 fixture、已归档 Agent Note 与该清理技能自带的校准示例之外没有命中任何设计序号引用；`verify-type-equiv`、各 `gen-*` 新鲜度检查与 `verify-translation-pairing` 把重新生成与重新记录的表面固定下来。覆盖缺口：没有门禁会拒绝新的序号引用，这条规则由评审把关。
 
 ## 后果
 
diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md
index 47b5725c18..dcbf2f2b21 100644
--- a/.agents/skills/dsh-doc-standards/SKILL.md
+++ b/.agents/skills/dsh-doc-standards/SKILL.md
@@ -37,12 +37,11 @@ Then check constraints that make placement expensive or wrong:
 After the structural pass, hunt the standard's slop checklist with the cheapest probes first. Verify and fetch the PR's live base, then run `pnpm --silent run change-scope --base <verified-base-ref>` to identify committed and dirty paths before applying semantic judgment. After a retarget or base merge, rerun the report and audit prose introduced by the new base.
 
 1. Measure: `pnpm run verify-doc-budgets --list`, then `git ls-files '*.md' ':(exclude)vendor/**' | xargs wc -w | sort -rn | head -30` to spot unbudgeted outliers.
-2. Hunt narrated history: `rg -n "no longer|used to|previously|was moved|renamed" --glob '*.md' --glob '*.ts' --glob '!vendor/**'` and keep only contrasts against a live alternative. Keep the vendor exclusion last so include globs cannot override it.
-3. Inspect long comments for reasoning transcripts: control-flow narration, test walkthroughs, proof of obvious branches, review findings, rejected local alternatives, and the same rationale repeated beside sibling methods. Preserve only a non-obvious contract or durable rationale; otherwise delete the comment.
-4. Hunt duplication by grepping distinctive phrases. Keep one home and replace other copies with links.
-5. Replace hand-written catalogs, test/status inventories, and JSDoc restatements with the authoritative tree, script, or generated reference.
-6. In `implemented/` Agent Notes, remove migration plans, acceptance-task checklists, and future-tense spec language. Keep concise verification contracts that identify the behaviors and tiers pinning the shipped decision, plus named coverage gaps.
-7. If removing prose changes a promised behavior rather than its explanation, use a proposed Agent Note first (follow [dsh-find-simplifications](../dsh-find-simplifications/SKILL.md)).
+2. Hunt reasoning-transcript leakage — narrated history, dead design-session citations, review choreography, control-flow narration, test walkthroughs — with [dsh-trim-cot-leakage](../dsh-trim-cot-leakage/SKILL.md), which owns the taxonomy, recall batteries, and the keep/delete boundary. Preserve only a non-obvious contract or durable rationale; the same rationale repeated beside sibling methods keeps one home.
+3. Hunt duplication by grepping distinctive phrases. Keep one home and replace other copies with links.
+4. Replace hand-written catalogs, test/status inventories, and JSDoc restatements with the authoritative tree, script, or generated reference.
+5. In `implemented/` Agent Notes, remove migration plans, acceptance-task checklists, and future-tense spec language. Keep concise verification contracts that identify the behaviors and tiers pinning the shipped decision, plus named coverage gaps.
+6. If removing prose changes a promised behavior rather than its explanation, use a proposed Agent Note first (follow [dsh-find-simplifications](../dsh-find-simplifications/SKILL.md)).
 
 Exclude `.agents/notes/archived/` from corpus audits and edits. Active prose may repair, redirect, or delete an inbound link, but never follow an archive-wide cleanup into the frozen target.
 
diff --git a/.agents/skills/dsh-prose-standard/SKILL.md b/.agents/skills/dsh-prose-standard/SKILL.md
index 26de553023..2381d459c2 100644
--- a/.agents/skills/dsh-prose-standard/SKILL.md
+++ b/.agents/skills/dsh-prose-standard/SKILL.md
@@ -5,7 +5,7 @@ description: Use when writing, reviewing, restoring, trimming, or auditing prose
 
 # DeepSeek Harness Prose Standard
 
-Write enough to preserve the contract, then remove reasoning transcripts, repetition, and decoration. This skill owns editorial judgment and required prose coverage; use [dsh-doc-standards](../dsh-doc-standards/SKILL.md) for placement, budgets, bilingual pairs, and documentation gates. It is guidance, not a script.
+Write enough to preserve the contract, then remove reasoning transcripts, repetition, and decoration. This skill owns editorial judgment and required prose coverage; use [dsh-doc-standards](../dsh-doc-standards/SKILL.md) for placement, budgets, bilingual pairs, and documentation gates, and [dsh-trim-cot-leakage](../dsh-trim-cot-leakage/SKILL.md) for hunting and fixing reasoning-transcript leakage. It is guidance, not a script.
 
 Comments describe non-obvious contracts or rationale that code cannot express; they do not restate what code already implies.
 
diff --git a/.agents/skills/dsh-trim-cot-leakage/SKILL.md b/.agents/skills/dsh-trim-cot-leakage/SKILL.md
new file mode 100644
index 0000000000..1ce776c28e
--- /dev/null
+++ b/.agents/skills/dsh-trim-cot-leakage/SKILL.md
@@ -0,0 +1,45 @@
+---
+name: dsh-trim-cot-leakage
+description: Use when auditing or fixing prose that reads like a leaked reasoning transcript — dead design-session citations such as (decision N), audit item codes, or §N of uncommitted drafts; change narration such as "used to", "no longer", "this cut"; stack or review vantage ("a later PR in this stack", "rejected in review"); reviewer-addressed justifications; control-flow narration; or hedged planning residue in comments, JSDoc, docs, or Agent Notes.
+---
+
+# Trimming Chain-of-Thought Leakage
+
+Chain-of-thought leakage is prose whose vantage is the authoring session rather than the repository: it cites artifacts only that session could see, narrates the change instead of the state, or argues with a reviewer who has left. The fix is never deletion alone — restate every factual clause so it stands at HEAD, then delete the transcript around it. **REQUIRED BACKGROUND:** [dsh-prose-standard](../dsh-prose-standard/SKILL.md) owns the complete-proposition rule this skill applies; the [committed-artifact-citations note](../../notes/implemented/process/2026-08-09-committed-artifact-citations.md) owns the citation rule's rationale. It is guidance, not a script.
+
+## The one test
+
+For every suspect passage ask: **could a reader at HEAD, with no access to any session transcript, PR thread, or uncommitted draft, resolve every reference and verify every claim?** If yes, it is not leakage, however historical it sounds. If no, restate the surviving facts from the repository's vantage and delete the rest.
+
+## Taxonomy
+
+1. **Dead design-session citations** — `(decision 7)`, `(audit C2)`, `design §4.7`, `plan §1.4`, phase labels (`T4`, `W3`, `P-I`), "the design ledger", "(B ruling)". If the decision has a committed owner, cite it by name and path; otherwise delete the citation and restate its factual clause to stand alone.
+2. **Stack and PR vantage** — "a later PR in this stack", "this PR adds", "the previous commit". State the shipped mechanism or the extension point; deferred work moves to a `TODO` marker or an issue reference.
+3. **Change narration and version stamps** — "used to", "no longer", "the old X", and indexical stamps ("v1", "this cut", "today", "now" contrasting with a past state). State the present behavior; a fixed regression becomes a present-tense counterfactual ("without X, Y happens"), never repo history ("used to Y").
+4. **Review choreography** — "Rejected in review:", "the reviewer confirmed", draft ordinals ("v5 of this note"), round attributions. Keep the surviving decision and rationale as plain fact; delete who said it when.
+5. **Reviewer-addressed justification** — "the cast is safe — it simply…", "this is correct because…". A comment arguing its own correctness addresses a reviewer, not a maintainer. State the invariant that makes the code safe, or delete the comment if the code shows it.
+6. **Restatement and derivation transcripts** — control-flow narration ("first we X, then we Y"), test walkthroughs, proofs of obvious branches. Delete; keep only a non-obvious contract or invariant.
+7. **Hedges and planning residue** — "probably fine for now", "should be enough", deferrals with no marker. Promote to `TODO`/`FIXME` or restate as the actual bound; delete the hedge.
+8. **Authoring-language slips** — untranslated working-language fragments (端, 设计稿, `---- 私有 ----` separators) in prose whose language is otherwise English, or the reverse in a zh counterpart. Translate or delete.
+
+## What is not leakage
+
+The citation boundary is where unaided passes fail in both directions — deleting durable references and keeping dead ones. Apply these keeps as written; [examples](references/examples.md) calibrates each:
+
+- **Issue references** — `#1470`, `TODO(name):`, "issue #N owns the follow-up" resolve at HEAD; keep them on any surface, including READMEs. Do not relocate them to Agent Notes.
+- **Merged-PR and issue citations inside Agent Notes and postmortems** — sanctioned evidence per the [documentation standard](../../../docs/AGENTS.md)'s change-story routing.
+- **Suppression justifications** — `oxlint-disable … -- reason`, coverage-ignore reasons, empty-catch explanations are required prose; fix a false reason, never delete it.
+- **Counterfactual-present regression pins** — "without X, Y happens", "a naive X would…".
+- **Measured bounds** — "(measured: 512 nests ≈ 0.15s)" calibrating a constant; the provenance word "measured" is load-bearing.
+- **Runtime old/new states** — "the old connection drains before the new one accepts" is runtime lifecycle, not change history.
+- **Historical stage names inside a note's change-story sections** — "the first cut shipped X" is current-state-safe there; indexical stamps ("this cut") stay banned everywhere.
+- **External references that resolve outside the repo by design** — standards sections (RFC 9110 §10.1.5), Figma frame names; the §-ban covers uncommitted internal drafts, not external standards or committed docs that own their §-numbering.
+- **Project voice and genre forms** — "we" as project voice; a note's Alternatives-considered section.
+
+## Workflow
+
+1. Scope and exclusions per [dsh-prose-standard](../dsh-prose-standard/SKILL.md): require an explicit scope; never touch `vendor/`, `.agents/notes/archived/`, or recorded fixtures and snapshots — recorded model output and sealed history keep their original voice.
+2. Audit read-only first: run the [recall batteries](references/recall-batteries.md) (with `--hidden` so `.agents/` is searched), then judge every hit semantically. The batteries are probes, not the definition — each review round of the original purge surfaced shapes the batteries missed, so also read the densest prose in scope (module JSDoc, READMEs, Agent Notes) without a pattern in hand.
+3. Fix owner-first per surface: generated catalogs → fix the source JSDoc or generator template, then regenerate; type-equivalence fences → fix the source JSDoc, then re-paste both bilingual pages (`verify-type-equiv` pins them); bilingual pairs → update the counterpart and re-record per [dsh-translate-docs](../dsh-translate-docs/SKILL.md); model-visible strings → wording is behavior, so flag for a snapshot-backed change instead of silently rewording.
+4. Before deleting anything, enumerate the passage's propositions (prose-standard) and check the [overcorrection traps](references/examples.md#overcorrection-traps): trims that flip an obligation into an endorsement, promote a hypothetical to a shipped feature, delete a true fact, or drop provenance.
+5. Verify: re-run the batteries expecting only sanctioned keeps and this skill's own references; confirm every remaining citation resolves at HEAD; run the gates for touched surfaces (`doc-sync` for docs, `verify-type-equiv`, `verify-translation-pairing`).
diff --git a/.agents/skills/dsh-trim-cot-leakage/references/examples.md b/.agents/skills/dsh-trim-cot-leakage/references/examples.md
new file mode 100644
index 0000000000..f478d90b13
--- /dev/null
+++ b/.agents/skills/dsh-trim-cot-leakage/references/examples.md
@@ -0,0 +1,253 @@
+# Few-shot leakage examples
+
+Distilled from the 2026-08 repo-wide purge and its review rounds. Use them to identify the governing principle, not as text templates. This file deliberately quotes leaked shapes as calibration material — the [recall batteries](recall-batteries.md) exclude this directory, and its wording is not a license elsewhere.
+
+## Dead citations
+
+### Decision ordinal with a committed owner
+
+**Leaked:** "Slash input resolves against the visible catalog (decision 21)."
+
+**Fixed:** "Slash input resolves against the visible catalog — the plain-text-reference decision, owned by the web input-machine note."
+
+The ordinal resolves nowhere at HEAD; the decision's name and owning note path do. Name the owning note's path at least once per file; later mentions may use the searchable name alone.
+
+### Decision ordinal without an owner
+
+**Leaked:** "The registry rejects duplicate names (decision 7: names are flat, no namespacing)."
+
+**Fixed:** "The registry rejects duplicate names; names are flat, with no namespacing."
+
+No committed artifact owns "decision 7", so the citation is deleted — but its factual clause (flat names) is restated to stand alone, not deleted with it.
+
+### Audit item codes
+
+**Leaked:** "Rendering is pure: same snapshot, same string (audit R3)."
+
+**Fixed:** "Rendering is pure: same snapshot, same string."
+
+There is no audit document in the repo; the code is pure session shorthand carrying zero propositions.
+
+### Section numbers of uncommitted drafts
+
+**Leaked:** "Layering follows the design (v2 §3.2): `src/core/` is the pure core."
+
+**Fixed:** "Layering: `src/core/` is the pure core."
+
+`§N` of a draft nobody committed is unresolvable. Contrast: "escapes per RFC 9110 §10.1.5" stays — an external standard resolves outside the repo by design, and a committed doc that owns its §-numbering may be cited by section.
+
+### Plan-phase labels
+
+**Leaked:** "`src/client/` is the shell (T4); the P-I migration owns the adapters."
+
+**Fixed:** "`src/client/` is the shell; the adapters live in `src/client/adapters/`."
+
+Phase labels index a plan that never landed. Replace the label with what the phase produced.
+
+## Stack and PR vantage
+
+### Stack position in durable prose
+
+**Leaked:** "A future remote backend implements this interface (the sandbox backend is a later PR in this stack)."
+
+**Fixed:** "A remote backend can implement this interface without changing the render layer."
+
+Durable prose cannot see the stack. Keep the extension-point contract; the pending work's home is the PR itself, a `TODO`, or an issue.
+
+### "This PR" in a README
+
+**Leaked:** "This PR adds cursor-based pagination to the session list."
+
+**Fixed:** "The session list paginates by cursor."
+
+A README outlives every PR; state the mechanism as current fact.
+
+## Change narration and version stamps
+
+### War story with a PR number
+
+**Leaked:** "Colors used to come from `--widget-*` tokens, which nothing defined, so it always rendered the fallbacks; the alias tokens fixed that (PR #88)."
+
+**Fixed:** "Colors come from the alias tokens; an undefined token renders the fallbacks."
+
+Both live facts survive — the current mechanism and the standing failure behavior — restated in the present. The bug's biography belongs to the PR and its Agent Note.
+
+### Removal narration
+
+**Leaked:** "The `probe` field is gone with the removal cut; badges ride the generic projection pair now."
+
+**Fixed:** "Badges use the generic projection pair."
+
+Readers who never saw `probe` learn nothing from its absence. "Now" contrasting with a deleted past is a version stamp.
+
+### Fixed regression → counterfactual present
+
+**Leaked:** "This used to double-encode multibyte labels."
+
+**Fixed:** "Without the byte-length guard, multibyte labels double-encode."
+
+The regression pin survives as a present-tense counterfactual that names the guard; "used to" pins it to repo archaeology instead.
+
+### Indexical version stamps
+
+**Leaked:** "Batch rendering is synchronous this cut; the async path is roadmap work."
+
+**Fixed:** "Batch rendering is synchronous." (The deferral lives in `TODO(widget-batch):` at the call site.)
+
+"This cut" / "v1" / "today" go stale the moment they merge. A historical stage name inside an Agent Note's change-story section ("the first cut shipped X") is current-state-safe; the indexical form never is.
+
+## Review choreography
+
+### Review verdicts as prose
+
+**Leaked:** "Rejected in review: caching the resolved spec. We keep resolution per-call."
+
+**Fixed (in an Agent Note's Alternatives considered):** "**Caching the resolved spec.** Rejected: the spec depends on per-call cwd, so a cache keyed by request would serve stale roots."
+
+The alternatives-considered genre is the sanctioned home; the reviewer and the round are not part of the rationale.
+
+### Draft ordinals
+
+**Leaked:** "As of v5 of this note, the loader also validates manifests."
+
+**Fixed:** "The loader validates manifests."
+
+An implemented note states shipped reality; its own revision history lives in git.
+
+## Reviewer-addressed justification
+
+### Arguing a cast
+
+**Leaked:** "The cast is safe — the SDK constructed the object, it simply doesn't declare the optionals strictly enough."
+
+**Fixed:** "The SDK constructs this object with every optional populated; the declared type is looser than the runtime guarantee."
+
+State the invariant a maintainer must not break. "It simply…" is a voice answering an objection nobody at HEAD raised. If the invariant is visible in the code, delete the comment instead.
+
+### Appeal to review authority
+
+**Leaked:** "This is correct because the reviewer confirmed the wrapping order."
+
+**Fixed:** (deleted; the wrapping order is stated in the function's `@returns`.)
+
+Correctness claims cite invariants or tests, never people.
+
+## Restatement and derivation
+
+### Control-flow narration
+
+**Leaked:** "First we normalize the label, then we truncate it, then we wrap it."
+
+**Fixed:** (deleted.)
+
+The three lines below the comment say the same thing in code.
+
+### Test walkthrough
+
+**Leaked:** "This test creates a session, sends two messages, waits for the second reply, and then asserts the log has four entries."
+
+**Fixed:** "Two round-trips must produce exactly four log entries — the projection dedupes the shared prefix."
+
+Keep only the non-obvious assertion rationale; the walkthrough restates the test body.
+
+## Hedges and planning residue
+
+### Unmarked deferral
+
+**Leaked:** "Probably fine to render eagerly for now."
+
+**Fixed:** (deleted; the deferral already has its `TODO(widget-batch):` marker.)
+
+A hedge without an owner is planning residue. If no marker exists, write one (`TODO(name): coalesce per animation frame`) instead of keeping the hedge.
+
+### Vague sizing
+
+**Leaked:** "A 64 KiB buffer should be enough for most cases."
+
+**Fixed:** "64 KiB holds the largest observed frame (48 KiB) with headroom; a larger frame fails loudly in `decode`."
+
+Replace the hedge with the actual bound and the failure behavior when it is exceeded.
+
+## Authoring-language slips
+
+**Leaked:** "The renderer runs on the client 端; see the 设计稿 for spacing. ---- 私有 ----"
+
+**Fixed:** "The renderer runs on the client side; spacing follows the Figma frame `widget-badges`."
+
+Working-language fragments and session separators are transcription residue. The Figma frame name stays: external provenance that resolves outside the repo by design.
+
+## Keeps
+
+### Issue references are durable on every surface
+
+**Keep:** "The cap applies to the complete rendered value, wrappers included (issue #1470 owns the follow-up)."
+
+An unaided pass deleted this, reasoning that issue citations belong in Agent Notes. Wrong direction: issues resolve at HEAD from any surface, and "#N owns the follow-up" is the sanctioned home for deferred work in a README. What Agent Notes and postmortems additionally sanction is citing *merged PRs* as evidence.
+
+### Dead name-drops are not "naming the owner"
+
+**Delete:** "Badge renderer over the widget seam (see the widget-rendering RFC)."
+
+An unaided pass kept this as "naming the owning document by topic". The test is resolvability, not form: no committed file answers to "the widget-rendering RFC", so the pointer is dead. Retarget it to the committed owner if one exists; otherwise delete it.
+
+### Suppression justifications
+
+**Keep (after fixing):** `// oxlint-disable-next-line no-non-null-assertion -- the one-element literal guarantees index 0.`
+
+The justification clause is required prose. When the stated reason is false (the original said "the loop guard above proves a frame exists" with no loop in sight), fix the reason; never delete it.
+
+### Measured bounds
+
+**Keep:** "Depth cap (measured: 512 nests ≈ 0.15s synchronous; 4096 blocks the loop)."
+
+The measurement pins the constant against uninformed retuning, and "measured" is the provenance that distinguishes data from a guess.
+
+### Runtime old/new is not change history
+
+**Keep:** "The old connection drains before the new one accepts."
+
+"Old" and "new" here name two live runtime objects during handover, not repository states. The change-narration ban is about repo history, not lifecycle vocabulary.
+
+## Overcorrection traps
+
+Every trap below shipped in the original purge and was caught in review. Enumerate a passage's propositions before trimming it.
+
+### Flipping an obligation into an endorsement
+
+**Original:** "These direct registrations are exceptions pending migration to slots."
+
+**Overcorrected:** "These direct registrations are sanctioned exceptions."
+
+**Right:** "These direct registrations are exceptions pending migration to slots."
+
+"Pending migration" is an obligation; "sanctioned" blesses the status quo. The trim inverted the sentence's modality while shortening it.
+
+### Promoting a hypothetical to a shipped feature
+
+**Original:** "A future IPC-based shell subclasses the executor and overrides `spawn`."
+
+**Overcorrected:** "An IPC-based shell subclasses the executor and overrides `spawn`."
+
+**Right:** "A hypothetical IPC-based shell — no such shell exists — would subclass the executor and override `spawn`."
+
+Deleting the future-marker alone turns a design illustration into a claim that the class ships. Mark the hypothetical explicitly instead of just unmarking the future.
+
+### Deleting a true fact with the transcript around it
+
+**Original:** "The gate notice narrates the check order; the notice text is also what `verify-doc-typecheck` compiles against."
+
+**Overcorrected:** "…" (whole sentence deleted as narration.)
+
+**Right:** "The notice text is what `verify-doc-typecheck` compiles against."
+
+Half the sentence was narration; the other half was a load-bearing coupling. Delete clauses, not sentences, when propositions share a line.
+
+### Dropping provenance while keeping the number
+
+**Original:** "The 4 MiB ceiling is measured: the largest generated `py-types` module is 3.1 MiB."
+
+**Overcorrected:** "The ceiling is 4 MiB; the largest generated `py-types` module is 3.1 MiB."
+
+**Right:** keep "measured".
+
+Without "measured" the 3.1 MiB reads as a definition rather than an observation, and nobody re-measures before raising the ceiling.
diff --git a/.agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md b/.agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md
new file mode 100644
index 0000000000..bacb434d16
--- /dev/null
+++ b/.agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md
@@ -0,0 +1,42 @@
+# Recall batteries
+
+Probes for [the taxonomy](../SKILL.md#taxonomy), tuned during the 2026-08 purge. Every hit needs semantic judgment — the batteries over-match by design, and they under-match by nature: each review round of the purge found shapes no battery caught, so pair them with an unpatterned read of the densest prose in scope.
+
+## Invocation rules
+
+- Add `--hidden --glob '!.git/**'` so `.agents/` is searched; ripgrep skips dot-directories by default and the purge's biggest miss risk was Agent Notes.
+- Exclusions go last so a later include cannot re-admit them: `--glob '!vendor/**' --glob '!node_modules/**' --glob '!.agents/notes/archived/**' --glob '!.agents/skills/dsh-trim-cot-leakage/references/**'` (this directory quotes leaked shapes as calibration), plus recorded fixture and snapshot directories in scope.
+- A zero-hit pattern proves nothing until you have seen it match: test it against a known-positive string before trusting the negative.
+
+## English battery
+
+```sh
+rg -n --hidden '\(decision \d|\(audit [A-Z]\d|design §|plan §|design ledger|\(B ruling|\bP-I\b|\bW\d\b|\bT\d\b' ...
+rg -n --hidden 'this PR|this branch|this stack|later PR|previous commit|this commit' ...
+rg -n --hidden 'used to |no longer|previously|the old |was renamed|was moved' ...
+rg -n --hidden '\bv1\b|this cut|\bcut \d|\btoday\b|\bfor now\b|roadmap' ...
+rg -n --hidden -i 'rejected in review|review round|reviewer|as of v\d' ...
+rg -n --hidden 'probably |should be enough|should suffice|it simply|is safe —|is safe --' ...
+rg -n --hidden '§\d' ...
+```
+
+## Chinese battery
+
+```sh
+rg -n --hidden '设计稿|评审|上一?轮|旧版|老的|不再|以前|本版|遗留|私有' ...
+rg -n --hidden '(^|[^a-zA-Z])端([^a-zA-Z]|$)' --glob '*.md' ...
+```
+
+## Known false-positive families
+
+Judged and kept during the purge; expect them again:
+
+- **Instrumental "used to"** — "the key used to sign requests" is instrumental, not temporal. The temporal form has a subject state before it ("colors used to come from…").
+- **Runtime old/new** — "the old connection drains before the new one accepts" names live objects during handover, not repo states.
+- **"This PR" in process docs** — documentation *about* PR workflow ("the PR body should…", templates, this repo's process notes) legitimately says "PR"; the ban is on a doc adopting one PR's vantage about the code.
+- **`v1` as protocol or path segment** — `/v1/chat` endpoints and wire-format names are identifiers, not version stamps.
+- **`§N` with a committed owner** — external standards (RFC 9110 §10.1.5) and committed docs that own their §-numbering stay citable by section.
+- **Contrastive "actually" and noun "wait"** — ordinary English, not hedging.
+- **"Today" in generated timestamps and CLI output samples** — recorded output keeps its voice.
+- **本版本 in zh prose** — a legitimate rendering of "this release" in versioned-artifact contexts; the banned indexical is 本版 as a bare stamp mirroring "this cut".
+- **Alternatives-considered sections** — "rejected" inside an Agent Note's genre slot is the sanctioned home, not review choreography.

From 4a7d4375628dc24d3ff9d09b7fe28161e487d7b7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 9 Aug 2026 22:50:26 +0800
Subject: [PATCH 516/516] docs(skills): fix dsh-trim-cot-leakage review
 findings from #2117
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The battery self-exclusion widens from references/ to the whole skill
directory (SKILL.md quotes the same leaked shapes), and the invocation
rules name the owning note's evidence self-hits; natural-language
battery lines gain -i so sentence-initial capitals hit; the actually/
wait false-positive family states that no committed line probes it.
The one test now says resolvability clears only this skill's bar —
current-state surfaces still reject resolvable change stories; the
never-deletion-alone rule is scoped to passages that carry factual
clauses. The first few-shot Fixed example links the real web
input-machine note path. The citations note's Verification exemption
(+zh, pair re-recorded) names the skill's files and the note's own
quoted evidence, making the claim mechanically honest.
---
 ...026-08-09-committed-artifact-citations.i18n.yaml |  4 ++--
 .../2026-08-09-committed-artifact-citations.md      |  2 +-
 .../2026-08-09-committed-artifact-citations.zh.md   |  2 +-
 .agents/skills/dsh-trim-cot-leakage/SKILL.md        |  6 +++---
 .../dsh-trim-cot-leakage/references/examples.md     |  6 +++---
 .../references/recall-batteries.md                  | 13 +++++++------
 6 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
index 04c3e6a7df..0813498ae6 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.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 .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: 181378aab12a4423d9ac5216bac5304f3cfca11c
-2026-08-09-committed-artifact-citations.zh.md: 36f32bb1fd0d6991919959e1ebe6482bf7b19b32
+2026-08-09-committed-artifact-citations.md: a578b1e32268af2669ee26c59d19c738bc9f707b
+2026-08-09-committed-artifact-citations.zh.md: d525dc0f58884bdf808b597213a7e23c1d6a0301
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
index 181378aab1..a578b1e322 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
@@ -28,7 +28,7 @@ One repo-wide purge applied these rules across the prose surfaces, including the
 
 ## Verification
 
-The audit's grep batteries (English and Chinese, comments and prose, `--hidden` for `.agents/`) return no design-ordinal citations outside recorded fixtures, archived notes, and the trim skill's own calibration examples; `verify-type-equiv`, the `gen-*` freshness checks, and `verify-translation-pairing` pin the regenerated and re-recorded surfaces. Coverage gap: no gate rejects a new ordinal citation — review owns the rule.
+The audit's grep batteries (English and Chinese, comments and prose, `--hidden` for `.agents/`) return no design-ordinal citations outside recorded fixtures, archived notes, the trim skill's own files, and this note's quoted evidence; `verify-type-equiv`, the `gen-*` freshness checks, and `verify-translation-pairing` pin the regenerated and re-recorded surfaces. Coverage gap: no gate rejects a new ordinal citation — review owns the rule.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
index 36f32bb1fd..d525dc0f58 100644
--- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md
@@ -28,7 +28,7 @@ Status: implemented
 
 ## 验证
 
-审计的成批 grep 检索（英文与中文、注释与行文、对 `.agents/` 加 `--hidden`）在已录制 fixture、已归档 Agent Note 与该清理技能自带的校准示例之外没有命中任何设计序号引用；`verify-type-equiv`、各 `gen-*` 新鲜度检查与 `verify-translation-pairing` 把重新生成与重新记录的表面固定下来。覆盖缺口：没有门禁会拒绝新的序号引用，这条规则由评审把关。
+审计的成批 grep 检索（英文与中文、注释与行文、对 `.agents/` 加 `--hidden`）在已录制 fixture、已归档 Agent Note、该清理技能自身文件与本笔记引用的证据之外没有命中任何设计序号引用；`verify-type-equiv`、各 `gen-*` 新鲜度检查与 `verify-translation-pairing` 把重新生成与重新记录的表面固定下来。覆盖缺口：没有门禁会拒绝新的序号引用，这条规则由评审把关。
 
 ## 后果
 
diff --git a/.agents/skills/dsh-trim-cot-leakage/SKILL.md b/.agents/skills/dsh-trim-cot-leakage/SKILL.md
index 1ce776c28e..c80dfbd465 100644
--- a/.agents/skills/dsh-trim-cot-leakage/SKILL.md
+++ b/.agents/skills/dsh-trim-cot-leakage/SKILL.md
@@ -5,11 +5,11 @@ description: Use when auditing or fixing prose that reads like a leaked reasonin
 
 # Trimming Chain-of-Thought Leakage
 
-Chain-of-thought leakage is prose whose vantage is the authoring session rather than the repository: it cites artifacts only that session could see, narrates the change instead of the state, or argues with a reviewer who has left. The fix is never deletion alone — restate every factual clause so it stands at HEAD, then delete the transcript around it. **REQUIRED BACKGROUND:** [dsh-prose-standard](../dsh-prose-standard/SKILL.md) owns the complete-proposition rule this skill applies; the [committed-artifact-citations note](../../notes/implemented/process/2026-08-09-committed-artifact-citations.md) owns the citation rule's rationale. It is guidance, not a script.
+Chain-of-thought leakage is prose whose vantage is the authoring session rather than the repository: it cites artifacts only that session could see, narrates the change instead of the state, or argues with a reviewer who has left. The fix is never deletion alone when a passage carries factual clauses — restate each so it stands at HEAD, then delete the transcript around it; a passage carrying none (an audit code, control-flow narration) is deleted outright. **REQUIRED BACKGROUND:** [dsh-prose-standard](../dsh-prose-standard/SKILL.md) owns the complete-proposition rule this skill applies; the [committed-artifact-citations note](../../notes/implemented/process/2026-08-09-committed-artifact-citations.md) owns the citation rule's rationale. It is guidance, not a script.
 
 ## The one test
 
-For every suspect passage ask: **could a reader at HEAD, with no access to any session transcript, PR thread, or uncommitted draft, resolve every reference and verify every claim?** If yes, it is not leakage, however historical it sounds. If no, restate the surviving facts from the repository's vantage and delete the rest.
+For every suspect passage ask: **could a reader at HEAD, with no access to any session transcript, PR thread, or uncommitted draft, resolve every reference and verify every claim?** If no, restate the surviving facts from the repository's vantage and delete the rest. If yes, it is not leakage, however historical it sounds — but resolvability only clears this skill's bar: on current-state surfaces (READMEs, docs, JSDoc) a resolvable change story is still change narration, and class 3 routes it to its sanctioned home.
 
 ## Taxonomy
 
@@ -42,4 +42,4 @@ The citation boundary is where unaided passes fail in both directions — deleti
 2. Audit read-only first: run the [recall batteries](references/recall-batteries.md) (with `--hidden` so `.agents/` is searched), then judge every hit semantically. The batteries are probes, not the definition — each review round of the original purge surfaced shapes the batteries missed, so also read the densest prose in scope (module JSDoc, READMEs, Agent Notes) without a pattern in hand.
 3. Fix owner-first per surface: generated catalogs → fix the source JSDoc or generator template, then regenerate; type-equivalence fences → fix the source JSDoc, then re-paste both bilingual pages (`verify-type-equiv` pins them); bilingual pairs → update the counterpart and re-record per [dsh-translate-docs](../dsh-translate-docs/SKILL.md); model-visible strings → wording is behavior, so flag for a snapshot-backed change instead of silently rewording.
 4. Before deleting anything, enumerate the passage's propositions (prose-standard) and check the [overcorrection traps](references/examples.md#overcorrection-traps): trims that flip an obligation into an endorsement, promote a hypothetical to a shipped feature, delete a true fact, or drop provenance.
-5. Verify: re-run the batteries expecting only sanctioned keeps and this skill's own references; confirm every remaining citation resolves at HEAD; run the gates for touched surfaces (`doc-sync` for docs, `verify-type-equiv`, `verify-translation-pairing`).
+5. Verify: re-run the batteries expecting only sanctioned keeps, this skill's own directory, and the owning note's quoted evidence; confirm every remaining citation resolves at HEAD; run the gates for touched surfaces (`doc-sync` for docs, `verify-type-equiv`, `verify-translation-pairing`).
diff --git a/.agents/skills/dsh-trim-cot-leakage/references/examples.md b/.agents/skills/dsh-trim-cot-leakage/references/examples.md
index f478d90b13..22e73e10f4 100644
--- a/.agents/skills/dsh-trim-cot-leakage/references/examples.md
+++ b/.agents/skills/dsh-trim-cot-leakage/references/examples.md
@@ -1,6 +1,6 @@
 # Few-shot leakage examples
 
-Distilled from the 2026-08 repo-wide purge and its review rounds. Use them to identify the governing principle, not as text templates. This file deliberately quotes leaked shapes as calibration material — the [recall batteries](recall-batteries.md) exclude this directory, and its wording is not a license elsewhere.
+Distilled from the 2026-08 repo-wide purge and its review rounds. Use them to identify the governing principle, not as text templates. This file deliberately quotes leaked shapes as calibration material — the [recall batteries](recall-batteries.md) exclude the skill's directory, and its wording is not a license elsewhere.
 
 ## Dead citations
 
@@ -8,9 +8,9 @@ Distilled from the 2026-08 repo-wide purge and its review rounds. Use them to id
 
 **Leaked:** "Slash input resolves against the visible catalog (decision 21)."
 
-**Fixed:** "Slash input resolves against the visible catalog — the plain-text-reference decision, owned by the web input-machine note."
+**Fixed:** "Slash input resolves against the visible catalog — the plain-text-reference decision, owned by [the web input-machine note](../../../notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)."
 
-The ordinal resolves nowhere at HEAD; the decision's name and owning note path do. Name the owning note's path at least once per file; later mentions may use the searchable name alone.
+The ordinal resolves nowhere at HEAD; the decision's name and owning note path do. Name the owning note's path at least once per file — as a link where the surface supports one — and later mentions may use the searchable name alone.
 
 ### Decision ordinal without an owner
 
diff --git a/.agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md b/.agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md
index bacb434d16..8f9cce4aad 100644
--- a/.agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md
+++ b/.agents/skills/dsh-trim-cot-leakage/references/recall-batteries.md
@@ -5,18 +5,19 @@ Probes for [the taxonomy](../SKILL.md#taxonomy), tuned during the 2026-08 purge.
 ## Invocation rules
 
 - Add `--hidden --glob '!.git/**'` so `.agents/` is searched; ripgrep skips dot-directories by default and the purge's biggest miss risk was Agent Notes.
-- Exclusions go last so a later include cannot re-admit them: `--glob '!vendor/**' --glob '!node_modules/**' --glob '!.agents/notes/archived/**' --glob '!.agents/skills/dsh-trim-cot-leakage/references/**'` (this directory quotes leaked shapes as calibration), plus recorded fixture and snapshot directories in scope.
+- Exclusions go last so a later include cannot re-admit them: `--glob '!vendor/**' --glob '!node_modules/**' --glob '!.agents/notes/archived/**' --glob '!.agents/skills/dsh-trim-cot-leakage/**'` (the skill's own files quote leaked shapes as calibration), plus recorded fixture and snapshot directories in scope. The [owning note](../../../notes/implemented/process/2026-08-09-committed-artifact-citations.md) also self-hits through its quoted evidence; judge it as evidence, not usage.
+- Natural-language lines carry `-i` so sentence-initial capitals hit ("This PR adds…", "Probably fine…"); the code-shaped first line stays case-sensitive — `-i` would turn `\bT\d\b` and `\bP-I\b` into noise.
 - A zero-hit pattern proves nothing until you have seen it match: test it against a known-positive string before trusting the negative.
 
 ## English battery
 
 ```sh
 rg -n --hidden '\(decision \d|\(audit [A-Z]\d|design §|plan §|design ledger|\(B ruling|\bP-I\b|\bW\d\b|\bT\d\b' ...
-rg -n --hidden 'this PR|this branch|this stack|later PR|previous commit|this commit' ...
-rg -n --hidden 'used to |no longer|previously|the old |was renamed|was moved' ...
-rg -n --hidden '\bv1\b|this cut|\bcut \d|\btoday\b|\bfor now\b|roadmap' ...
+rg -n --hidden -i 'this PR|this branch|this stack|later PR|previous commit|this commit' ...
+rg -n --hidden -i 'used to |no longer|previously|the old |was renamed|was moved' ...
+rg -n --hidden -i '\bv1\b|this cut|\bcut \d|\btoday\b|\bfor now\b|roadmap' ...
 rg -n --hidden -i 'rejected in review|review round|reviewer|as of v\d' ...
-rg -n --hidden 'probably |should be enough|should suffice|it simply|is safe —|is safe --' ...
+rg -n --hidden -i 'probably |should be enough|should suffice|it simply|is safe —|is safe --' ...
 rg -n --hidden '§\d' ...
 ```
 
@@ -36,7 +37,7 @@ Judged and kept during the purge; expect them again:
 - **"This PR" in process docs** — documentation *about* PR workflow ("the PR body should…", templates, this repo's process notes) legitimately says "PR"; the ban is on a doc adopting one PR's vantage about the code.
 - **`v1` as protocol or path segment** — `/v1/chat` endpoints and wire-format names are identifiers, not version stamps.
 - **`§N` with a committed owner** — external standards (RFC 9110 §10.1.5) and committed docs that own their §-numbering stay citable by section.
-- **Contrastive "actually" and noun "wait"** — ordinary English, not hedging.
+- **Contrastive "actually" and noun "wait"** — ordinary English, not hedging; no committed line probes them, so they surface only when you extend the battery with broader hedging patterns.
 - **"Today" in generated timestamps and CLI output samples** — recorded output keeps its voice.
 - **本版本 in zh prose** — a legitimate rendering of "this release" in versioned-artifact contexts; the banned indexical is 本版 as a bare stamp mirroring "this cut".
 - **Alternatives-considered sections** — "rejected" inside an Agent Note's genre slot is the sanctioned home, not review choreography.